From 556f396b3cd63da525e2cdac1a5f1c606f4494ce Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 27 May 2026 01:35:13 -0700
Subject: [PATCH 001/222] ci: install unsloth_zoo from git main in notebooks-ci
 + studio-backend-ci (#5802)

* ci: install unsloth_zoo from git main in notebooks-ci + studio-backend-ci

These were the only two workflows that still pulled unsloth_zoo from
PyPI; every other CI (Core, MLX, version-compat, install.sh-driven
Studio smokes) installs zoo from git main. Drift between PyPI and
main hides fixes-on-zoo-main and lets PR-time validation pass on a
stale zoo, then break for users on next release.

Both edits match the retry-with-backoff shape mlx-ci.yml already uses.

* ci: drop --no-deps from studio-backend-ci unsloth_zoo install

The prior PyPI line was `pip install 'unsloth_zoo>=2026.5.1'` (no
--no-deps), which pulled in triton and the rest of zoo's runtime deps.
I dropped that transitive resolve in the first commit, which broke
collection of 5 tests in Repo tests (CPU) with
ModuleNotFoundError: No module named 'triton'.

Match the prior dep-resolve shape, keeping the source-from-git change.
notebooks-ci keeps --no-deps because its original line also had it.
---
 .github/workflows/notebooks-ci.yml      | 10 +++++++++-
 .github/workflows/studio-backend-ci.yml | 16 +++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/notebooks-ci.yml b/.github/workflows/notebooks-ci.yml
index 673b2f3cc5..2edcae8ab2 100644
--- a/.github/workflows/notebooks-ci.yml
+++ b/.github/workflows/notebooks-ci.yml
@@ -285,7 +285,15 @@ jobs:
           # The PR-time CI must validate the code in this PR; PyPI unsloth
           # may lag the in-repo CPU-torch fallback in unsloth/kernels/utils.py
           # (lines 162-170) that handles missing torch._C._cuda_getCurrentRawStream.
-          pip install --no-deps unsloth_zoo
+          # unsloth_zoo from git main mirrors every other CI (Core / MLX /
+          # install.sh) so PR-time validation sees the same zoo HEAD.
+          for attempt in 1 2 3; do
+            if pip install --no-deps "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo"; then
+              break
+            fi
+            [ "$attempt" -eq 3 ] && { echo "::error::unsloth_zoo install failed after 3 attempts"; exit 1; }
+            sleep $((5 * attempt))
+          done
           pip install --no-deps -e ./unsloth
 
       - name: Convert notebooks for AST scan
diff --git a/.github/workflows/studio-backend-ci.yml b/.github/workflows/studio-backend-ci.yml
index 63eb70f7f1..ee5bbe8633 100644
--- a/.github/workflows/studio-backend-ci.yml
+++ b/.github/workflows/studio-backend-ci.yml
@@ -144,9 +144,19 @@ jobs:
           # versions ship a CPU build that imports cleanly on Linux.
           pip install 'bitsandbytes>=0.45'
           # unsloth.device_type imports unsloth_zoo.utils.Version at module
-          # scope, so the conftest preload needs unsloth_zoo even though
-          # it is an optional dep of unsloth.
-          pip install 'unsloth_zoo>=2026.5.1'
+          # scope, so the conftest preload needs unsloth_zoo. Pull from
+          # git main so this job sees the same zoo HEAD as Core / MLX /
+          # install.sh do (otherwise a fix on zoo main hides until release).
+          # No --no-deps: matches prior `pip install 'unsloth_zoo>=2026.5.1'`
+          # behaviour so triton etc. still come in for the Repo tests CPU
+          # collection imports.
+          for attempt in 1 2 3; do
+            if pip install "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo"; then
+              break
+            fi
+            [ "$attempt" -eq 3 ] && { echo "::error::unsloth_zoo install failed after 3 attempts"; exit 1; }
+            sleep $((5 * attempt))
+          done
           pip install -e . --no-deps
 
       - name: Repo tests (CPU, auto-discovered)

From 8b2b99be036dc114700867392f1b6a149ee3fdaf Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Wed, 27 May 2026 16:50:44 +0530
Subject: [PATCH 002/222] tool mask support (#5682)

* tool mask support

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Handle tool masks with older zoo builds

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Keep tool mask implementation in zoo

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 tests/test_tool_mask_zoo_compat.py | 103 +++++++++++++++++++++++++++++
 unsloth/models/rl.py               |  19 ++++++
 unsloth/models/rl_replacements.py  |  45 ++++++++++++-
 3 files changed, 166 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_tool_mask_zoo_compat.py

diff --git a/tests/test_tool_mask_zoo_compat.py b/tests/test_tool_mask_zoo_compat.py
new file mode 100644
index 0000000000..b6b68a7561
--- /dev/null
+++ b/tests/test_tool_mask_zoo_compat.py
@@ -0,0 +1,103 @@
+"""Compatibility checks for env/tool mask support with older unsloth_zoo."""
+
+from __future__ import annotations
+
+import ast
+import os
+import textwrap
+
+import pytest
+import torch
+
+REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+RL_SOURCE_PATH = os.path.join(REPO_ROOT, "unsloth", "models", "rl.py")
+RL_REPLACEMENTS_SOURCE_PATH = os.path.join(
+    REPO_ROOT, "unsloth", "models", "rl_replacements.py"
+)
+
+
+def _read(path: str) -> str:
+    with open(path, "r") as fh:
+        return fh.read()
+
+
+def _load_local_align_completion_tool_mask():
+    src = _read(RL_SOURCE_PATH)
+    tree = ast.parse(src)
+    for node in tree.body:
+        if isinstance(node, ast.If):
+            for item in node.body:
+                if (
+                    isinstance(item, ast.FunctionDef)
+                    and item.name == "align_completion_tool_mask"
+                ):
+                    function_src = ast.get_source_segment(src, item)
+                    break
+            else:
+                continue
+            break
+    else:
+        raise AssertionError("local align_completion_tool_mask fallback is missing")
+
+    calls = []
+
+    def align_logprobs_with_mask(logprob_tensor, completion_mask, pad_value = None):
+        calls.append((logprob_tensor, completion_mask, pad_value))
+        return torch.tensor(
+            [[1, 0, 1], [0, 1, 1]],
+            device = completion_mask.device,
+            dtype = logprob_tensor.dtype,
+        )
+
+    namespace = {
+        "torch": torch,
+        "align_logprobs_with_mask": align_logprobs_with_mask,
+    }
+    exec(textwrap.dedent(function_src), namespace)
+    return namespace["align_completion_tool_mask"], calls
+
+
+def test_rl_uses_optional_zoo_tool_mask_helper():
+    src = _read(RL_SOURCE_PATH)
+    assert 'RL_REPLACEMENTS.get("align_completion_tool_mask")' in src
+    assert 'RL_REPLACEMENTS["align_completion_tool_mask"]' not in src
+
+
+def test_local_tool_mask_fallback_is_only_old_zoo_compat_shim():
+    align_completion_tool_mask, calls = _load_local_align_completion_tool_mask()
+    completion_mask = torch.tensor(
+        [[1, 1, 0], [1, 1, 1]],
+        dtype = torch.float32,
+    )
+
+    assert align_completion_tool_mask(None, completion_mask) is completion_mask
+    assert calls == []
+
+    same_shape_tool_mask = torch.tensor([[1, 0, 1], [0, 1, 1]], dtype = torch.bool)
+    with pytest.raises(RuntimeError, match = "Please upgrade unsloth_zoo"):
+        align_completion_tool_mask(same_shape_tool_mask, completion_mask)
+
+
+def test_grpo_accumulated_loss_omits_none_tool_mask_for_old_zoo():
+    src = _read(RL_REPLACEMENTS_SOURCE_PATH)
+    assert "_grpo_accumulated_loss_kwargs = {}" in src
+    assert (
+        'if tool_mask is not None:\n                _grpo_accumulated_loss_kwargs["tool_mask"] = tool_mask'
+        in src
+    )
+    assert src.count("**_grpo_accumulated_loss_kwargs") == 2
+
+    accelerated_loss_start = src.find('if hasattr(self.args, "loss_type"):')
+    assert accelerated_loss_start != -1
+    accelerated_loss_body = src[
+        accelerated_loss_start : src.find(
+            'if "train" in self._metrics:', accelerated_loss_start
+        )
+    ]
+    assert "tool_mask = tool_mask" not in accelerated_loss_body
+
+
+def test_rollout_output_patch_requires_real_tool_mask_symbol():
+    src = _read(RL_REPLACEMENTS_SOURCE_PATH)
+    assert 're.search(r"\\btool_mask\\b", function)' in src
+    assert 'output["tool_mask"]' in src
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index c82c8364b3..9bf0d3e968 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -365,6 +365,22 @@ calculate_pad_tokens_in_prompt = RL_REPLACEMENTS["calculate_pad_tokens_in_prompt
 create_completion_attention_mask = RL_REPLACEMENTS["create_completion_attention_mask"]
 left_pack_padding = RL_REPLACEMENTS["left_pack_padding"]
 align_logprobs_with_mask = RL_REPLACEMENTS["align_logprobs_with_mask"]
+align_completion_tool_mask = RL_REPLACEMENTS.get("align_completion_tool_mask")
+if align_completion_tool_mask is None:
+
+    def align_completion_tool_mask(
+        tool_mask: torch.Tensor,
+        completion_mask: torch.Tensor,
+    ) -> torch.Tensor:
+        if tool_mask is None:
+            return completion_mask
+        raise RuntimeError(
+            "env_mask/tool_mask GRPO requires an unsloth_zoo build whose "
+            "grpo_accumulated_loss handles tool_mask. Please upgrade "
+            "unsloth_zoo."
+        )
+
+
 autotune_batch_and_chunks = RL_REPLACEMENTS["grpo_autotune_batch_and_chunks"]
 sanitize_logprob = RL_REPLACEMENTS["sanitize_logprob"]
 
@@ -452,6 +468,7 @@ torch_compile_options = {{
 {create_completion_attention_mask_code}
 {left_pack_padding_code}
 {align_logprobs_with_mask_code}
+{align_completion_tool_mask_code}
 {autotune_batch_and_chunks_code}
 {sanitize_logprob_code}
 
@@ -1577,6 +1594,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     )
     left_pack_padding_code = inspect.getsource(left_pack_padding)
     align_logprobs_with_mask_code = inspect.getsource(align_logprobs_with_mask)
+    align_completion_tool_mask_code = inspect.getsource(align_completion_tool_mask)
     autotune_batch_and_chunks_code = inspect.getsource(autotune_batch_and_chunks)
     sanitize_logprob_code = inspect.getsource(sanitize_logprob)
     # Get final source code
@@ -1607,6 +1625,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         autotune_batch_and_chunks_code = autotune_batch_and_chunks_code,
         left_pack_padding_code = left_pack_padding_code,
         align_logprobs_with_mask_code = align_logprobs_with_mask_code,
+        align_completion_tool_mask_code = align_completion_tool_mask_code,
         sanitize_logprob_code = sanitize_logprob_code,
     )
 
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 0f9a324d5b..9ddb5e9453 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -946,6 +946,14 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
         )
         function = function.replace(_save_search, _save_replace)
 
+    if re.search(r"\btool_mask\b", function) and 'output["tool_mask"]' not in function:
+        function = function.replace(
+            "        return output",
+            "        if tool_mask is not None:\n"
+            '            output["tool_mask"] = tool_mask\n'
+            "        return output",
+        )
+
     return function
 
 
@@ -1523,6 +1531,7 @@ def grpo_trainer_compute_loss(function_name, function):
         mm_token_type_ids = inputs.get("mm_token_type_ids", None)
         num_items_in_batch = inputs.get("num_items_in_batch", None)
         sampling_per_token_logps = inputs.get("sampling_per_token_logps", None)
+        tool_mask = inputs.get("tool_mask", None)
         current_gradient_accumulation_steps = self.current_gradient_accumulation_steps
         num_processes = self.accelerator.num_processes
 
@@ -1598,6 +1607,16 @@ def grpo_trainer_compute_loss(function_name, function):
 
         max_left_pad = inputs.get("max_left_pad", 0)
         if per_token_logps is not None:
+            loss_mask = completion_mask
+            if tool_mask is not None:
+                if tool_mask.shape != completion_mask.shape:
+                    raise ValueError(
+                        "tool_mask/env_mask must have the same shape as completion_mask"
+                    )
+                loss_mask = completion_mask * tool_mask.to(
+                    device = completion_mask.device,
+                    dtype = completion_mask.dtype,
+                )
             (
                 loss,
                 completion_length,
@@ -1612,7 +1631,7 @@ def grpo_trainer_compute_loss(function_name, function):
                 old_logps,
                 sampling_per_token_logps,
                 input_ids,
-                completion_mask,
+                loss_mask,
                 self.beta,
                 advantages,
                 pixel_values = pixel_values,
@@ -1662,6 +1681,28 @@ def grpo_trainer_compute_loss(function_name, function):
                         "unsloth_zoo (see https://github.com/unslothai/unsloth-zoo/pull/613)."
                     )
                 self._unsloth_grpo_zoo_checked = True
+            if tool_mask is not None and not getattr(
+                self, "_unsloth_grpo_tool_mask_zoo_checked", False
+            ):
+                _supports_tool_mask = (
+                    "tool_mask" in inspect.signature(grpo_accumulated_loss).parameters
+                )
+                if not _supports_tool_mask:
+                    try:
+                        _zoo_src = inspect.getsource(grpo_accumulated_loss)
+                    except (TypeError, OSError):
+                        _zoo_src = ""
+                    _supports_tool_mask = "tool_mask" in _zoo_src
+                if not _supports_tool_mask:
+                    raise RuntimeError(
+                        "env_mask/tool_mask GRPO requires an unsloth_zoo build whose "
+                        "grpo_accumulated_loss handles tool_mask. Please upgrade "
+                        "unsloth_zoo."
+                    )
+                self._unsloth_grpo_tool_mask_zoo_checked = True
+            _grpo_accumulated_loss_kwargs = {}
+            if tool_mask is not None:
+                _grpo_accumulated_loss_kwargs["tool_mask"] = tool_mask
             if hasattr(self.args, "loss_type"):
                 (
                     loss,
@@ -1703,6 +1744,7 @@ def grpo_trainer_compute_loss(function_name, function):
                     sampling_per_token_logps = sampling_per_token_logps,
                     token_type_ids = token_type_ids,
                     mm_token_type_ids = mm_token_type_ids,
+                    **_grpo_accumulated_loss_kwargs,
                 )
             else:
                 # to ensure backwards compatibility with trl 0.15.2 and maybe even 0.17
@@ -1728,6 +1770,7 @@ def grpo_trainer_compute_loss(function_name, function):
                         attention_mask = attention_mask,
                         token_type_ids = token_type_ids,
                         mm_token_type_ids = mm_token_type_ids,
+                        **_grpo_accumulated_loss_kwargs,
                     )
                 )
         if "train" in self._metrics:

From 4891118b5e31194e79c361de5b6b49cefe9b4112 Mon Sep 17 00:00:00 2001
From: wuwuwu <1498968550@qq.com>
Date: Wed, 27 May 2026 19:52:16 +0800
Subject: [PATCH 003/222] Studio: add frontend i18n support (#5765)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Studio: add frontend i18n support

* Studio i18n: guard storage events, restore plurals, fill zh-CN, add parity check

- locale-store.ts: wrap window.localStorage access in handleStorageEvent
  with try/catch. readStoredLocale and writeStoredLocale already guard the
  same API; the storage-event path can throw the same way in privacy/
  restricted contexts and was the only unguarded localStorage call. Refactor
  the storageArea + key match into isLocaleStorageEvent for clarity.

- chat-tab.tsx + en.ts/zh-CN.ts: restore singular handling for chat-clear
  copy that the i18n migration dropped. Pre-PR code rendered "1 chat" but
  the new template strings always said "chats", so a user with exactly one
  chat saw "Cleared 1 chats", "Clear 1 chats?", and "1 chats cleared;
  1 chats remain". Add clearOneChat*, clearedOneChat, oneChatClearedRemain*,
  chatsClearedRemainOne, and storageClearFailedOne keys and pick them in
  chat-tab.tsx when count === 1.

- zh-CN.ts: fill ~50 previously English-fallback keys across studio.configure,
  studio.model VRAM helpers, studio.dataset (source, browsing, tooltips,
  preview/split/subset), studio.params tooltips and learningRateDescription,
  studio.training (audio/vision incompatible), studio.trainingStart.terminalStart,
  studio.tour.guidedTour, settings.chat.clear*, settings.connections,
  settings.apiKeys.newBadge. shell.{beta,brand,product} kept as brand strings.

- src/i18n/check-parity.ts + npm i18n:check: small script that verifies every
  locale overlay against the English baseline. Catches placeholder mismatches,
  shape mismatches, and unintended extra keys; runs via node --experimental-
  strip-types with no new devDependencies.

Verified locally:
  npm run typecheck, lint, build, biome:check, i18n:check all pass.
  24 vitest unit tests cover locale resolution, persistence failures,
  storage-event sync (including window.localStorage throwing), interpolation,
  and fallback.
  33 Playwright e2e tests pass across Chromium, Firefox, and WebKit covering
  default load, switch + reload persistence, unsupported/garbage locale
  fallback, storage-event cross-tab sync, and storage clear.

* Studio i18n: use translated API-key error copy instead of raw err.message

The API helpers in src/features/settings/api/api-keys.ts throw generic
English Error objects ("Failed to load API access", "Failed to create
access token", "Failed to revoke access token"). ApiKeysTab and
CreateKeyForm caught those and preferred err.message over the translated
"settings.apiKeys.loadError" / .createError / .revokeError keys, so in
zh-CN mode failed load/create/revoke requests still surfaced the English
strings instead of the translated copy.

Switched the four call-sites to always render the translated message and
left the helper throws unchanged (they are still useful for diagnostics
but should not be treated as user-facing localized copy).

* Studio i18n: polish two zh-CN embedding LR tooltips

Translation-pass review surfaced two awkward phrasings I introduced earlier:

  "常用区间是主学习率的 2 至 10 倍小"
    -> "常用区间是比主学习率小 2 至 10 倍"

Both versions are grammatical, but the new "比 X 小 N 倍" phrasing is the
standard idiomatic comparative for "N times smaller than X" in technical
Chinese writing. The earlier "X 的 N 倍小" reads as a non-native construction.

Applies to:
  studio.params.embeddingLearningRateTooltip
  studio.params.embeddingLearningRateDescription

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/frontend/package.json                  |   1 +
 studio/frontend/src/app/router.tsx            |   9 +-
 studio/frontend/src/app/routes/__root.tsx     |  39 +-
 studio/frontend/src/app/routes/studio.tsx     |   2 +-
 .../frontend/src/components/app-sidebar.tsx   | 162 ++--
 .../profile-personalization-panel.tsx         |  25 +-
 .../settings/components/api-key-row.tsx       |  58 +-
 .../settings/components/create-key-form.tsx   |  19 +-
 .../settings/components/key-reveal-card.tsx   |  14 +-
 .../settings/components/language-select.tsx   |  46 ++
 .../settings/components/theme-segmented.tsx   |  16 +-
 .../components/update-studio-instructions.tsx |  94 +--
 .../settings/components/usage-examples.tsx    |  24 +-
 .../src/features/settings/settings-dialog.tsx |  46 +-
 .../src/features/settings/tabs/about-tab.tsx  |  34 +-
 .../features/settings/tabs/api-keys-tab.tsx   |  72 +-
 .../features/settings/tabs/appearance-tab.tsx |  30 +-
 .../src/features/settings/tabs/chat-tab.tsx   |  78 +-
 .../features/settings/tabs/general-tab.tsx    |  56 +-
 .../features/settings/tabs/profile-tab.tsx    |   9 +-
 .../studio/historical-training-view.tsx       |  29 +-
 .../src/features/studio/history-card-grid.tsx |  93 ++-
 .../sections/charts/chart-settings-sheet.tsx  |  60 +-
 .../sections/charts/eval-loss-chart-card.tsx  |  26 +-
 .../sections/charts/grad-norm-chart-card.tsx  |  19 +-
 .../charts/learning-rate-chart-card.tsx       |  19 +-
 .../charts/training-loss-chart-card.tsx       |  28 +-
 .../studio/sections/dataset-section.tsx       | 139 ++--
 .../studio/sections/model-section.tsx         |  81 +-
 .../studio/sections/params-section.tsx        | 212 ++---
 .../studio/sections/progress-section-lib.ts   |  13 -
 .../studio/sections/progress-section.tsx      | 125 +--
 .../studio/sections/training-section.tsx      |  53 +-
 .../src/features/studio/studio-page.tsx       |  23 +-
 .../studio/training-start-overlay.tsx         |  45 +-
 .../frontend/src/features/training/index.ts   |   5 +-
 studio/frontend/src/i18n/AGENTS.md            |  11 +
 studio/frontend/src/i18n/check-parity.ts      | 111 +++
 studio/frontend/src/i18n/index.ts             |  44 ++
 studio/frontend/src/i18n/locale-store.ts      | 130 ++++
 studio/frontend/src/i18n/locales/en.ts        | 731 ++++++++++++++++++
 studio/frontend/src/i18n/locales/zh-CN.ts     | 712 +++++++++++++++++
 studio/frontend/src/i18n/messages.ts          |  76 ++
 studio/frontend/src/i18n/types.ts             |  30 +
 studio/frontend/src/main.tsx                  |   3 +
 45 files changed, 2958 insertions(+), 694 deletions(-)
 create mode 100644 studio/frontend/src/features/settings/components/language-select.tsx
 create mode 100644 studio/frontend/src/i18n/AGENTS.md
 create mode 100644 studio/frontend/src/i18n/check-parity.ts
 create mode 100644 studio/frontend/src/i18n/index.ts
 create mode 100644 studio/frontend/src/i18n/locale-store.ts
 create mode 100644 studio/frontend/src/i18n/locales/en.ts
 create mode 100644 studio/frontend/src/i18n/locales/zh-CN.ts
 create mode 100644 studio/frontend/src/i18n/messages.ts
 create mode 100644 studio/frontend/src/i18n/types.ts

diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 83b1fd96f9..b43e174889 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -12,6 +12,7 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "typecheck": "tsc -b --pretty false",
+    "i18n:check": "node --experimental-strip-types --no-warnings src/i18n/check-parity.ts",
     "biome:check": "biome check",
     "biome:fix": "biome check --write"
   },
diff --git a/studio/frontend/src/app/router.tsx b/studio/frontend/src/app/router.tsx
index c7bc0440bd..f0a417638d 100644
--- a/studio/frontend/src/app/router.tsx
+++ b/studio/frontend/src/app/router.tsx
@@ -3,6 +3,7 @@
 
 import { Link, createRouter, useRouterState } from "@tanstack/react-router";
 import { Button } from "@/components/ui/button";
+import { useT } from "@/i18n";
 import { Route as rootRoute } from "./routes/__root";
 import { Route as dataRecipesRoute } from "./routes/data-recipes";
 import { Route as dataRecipeRoute } from "./routes/data-recipes.$recipeId";
@@ -31,7 +32,9 @@ const routeTree = rootRoute.addChildren([
 ]);
 
 function DefaultNotFound() {
+  const t = useT();
   const pathname = useRouterState({ select: (s) => s.location.pathname });
+
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-4 p-8 text-center">
       <img
@@ -41,14 +44,14 @@ function DefaultNotFound() {
       />
       <div className="flex flex-col items-center gap-1">
         <h1 className="font-heading font-semibold text-2xl tracking-tight">
-          Page not found
+          {t("shell.notFound.title")}
         </h1>
         <p className="text-muted-foreground text-sm break-all">
-          {pathname} does not exist.
+          {t("shell.notFound.description", { path: pathname })}
         </p>
       </div>
       <Button asChild>
-        <Link to="/chat">Back to chat</Link>
+        <Link to="/chat">{t("shell.notFound.backToChat")}</Link>
       </Button>
     </div>
   );
diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index 47bff815e6..57ed233d51 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -6,8 +6,9 @@ import { Navbar } from "@/components/navbar";
 import { fetchDeviceType, usePlatformStore } from "@/config/env";
 import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
 import { SettingsDialog, useSettingsDialogStore } from "@/features/settings";
-import { useTrainingUnloadGuard } from "@/features/training/hooks/use-training-unload-guard";
+import { useTrainingUnloadGuard } from "@/features/training";
 import { useSidebarPin } from "@/hooks/use-sidebar-pin";
+import { useT, type TranslationKey } from "@/i18n";
 import {
   Outlet,
   createRootRoute,
@@ -16,24 +17,25 @@ import {
   useRouterState,
 } from "@tanstack/react-router";
 import { AnimatePresence, motion } from "motion/react";
-import { Suspense, useEffect, useLayoutEffect, type ReactNode } from "react";
+import { Suspense, useEffect, useLayoutEffect } from "react";
 import { AppProvider } from "../provider";
 
-// Type `staticData.title` on every route so the matched-title selector
-// below stays type-safe without an inline cast.
 declare module "@tanstack/react-router" {
   interface StaticDataRouteOption {
     title?: string;
+    titleKey?: TranslationKey;
   }
 }
 
-// Fallback while a lazy route bundle (Train/Recipes/Export) loads.
-// /chat is synchronous and never hits this.
-const RouteFallback: ReactNode = (
-  <div className="flex h-full min-h-0 flex-1 items-center justify-center text-muted-foreground text-sm">
-    Loading...
-  </div>
-);
+function RouteFallback() {
+  const t = useT();
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 items-center justify-center text-muted-foreground text-sm">
+      {t("common.loading")}
+    </div>
+  );
+}
 
 const CHAT_ONLY_ALLOWED = new Set([
   "/",
@@ -68,6 +70,7 @@ const HIDDEN_NAVBAR_ROUTES = ["/onboarding", "/login", "/change-password"];
 const DEFAULT_DOCUMENT_TITLE = "Unsloth Studio";
 
 function RootLayout() {
+  const t = useT();
   const pathname = useRouterState({ select: (s) => s.location.pathname });
   const hideNavbar = HIDDEN_NAVBAR_ROUTES.includes(pathname);
   const isChatRoute = pathname.startsWith("/chat");
@@ -75,24 +78,20 @@ function RootLayout() {
 
   useTrainingUnloadGuard();
 
-  // Walk matches deepest-first; each route declares its own title.
   const matchedTitle = useMatches({
     select: (matches) => {
       for (let i = matches.length - 1; i >= 0; i--) {
-        const title = matches[i].staticData.title;
+        const { title, titleKey } = matches[i].staticData;
+        if (titleKey) return t(titleKey);
         if (title) return title;
       }
       return null;
     },
   });
 
-  // `/settings` redirects in `beforeLoad`, so its route never stays
-  // matched; surface the modal's title via the store instead.
   const settingsDialogOpen = useSettingsDialogStore((s) => s.open);
-  const documentTitle = settingsDialogOpen ? "Settings" : matchedTitle;
+  const documentTitle = settingsDialogOpen ? t("settings.title") : matchedTitle;
 
-  // useLayoutEffect updates the tab title before paint, avoiding a
-  // one-frame flash of the previous route's title on navigation.
   useLayoutEffect(() => {
     document.title = documentTitle
       ? `${documentTitle} - ${DEFAULT_DOCUMENT_TITLE}`
@@ -116,7 +115,7 @@ function RootLayout() {
       <SettingsDialog />
       {hideNavbar ? (
         <main className="flex-1">
-          <Suspense fallback={RouteFallback}>
+          <Suspense fallback={<RouteFallback />}>
             <Outlet />
           </Suspense>
         </main>
@@ -142,7 +141,7 @@ function RootLayout() {
                   transition={{ duration: 0.15 }}
                   className={`flex min-h-0 min-w-0 flex-1 basis-0 flex-col ${isChatRoute ? "overflow-hidden" : "overflow-visible"}`}
                 >
-                  <Suspense fallback={RouteFallback}>
+                  <Suspense fallback={<RouteFallback />}>
                     <Outlet />
                   </Suspense>
                 </motion.div>
diff --git a/studio/frontend/src/app/routes/studio.tsx b/studio/frontend/src/app/routes/studio.tsx
index 75f1a1b937..ae7f445e94 100644
--- a/studio/frontend/src/app/routes/studio.tsx
+++ b/studio/frontend/src/app/routes/studio.tsx
@@ -15,7 +15,7 @@ const StudioPage = lazy(() =>
 export const Route = createRoute({
   getParentRoute: () => rootRoute,
   path: "/studio",
-  staticData: { title: "Train" },
+  staticData: { titleKey: "studio.routeTitle" },
   beforeLoad: () => requireAuth(),
   component: StudioPage,
 });
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index aac5f8f8a8..849e017ea8 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -90,9 +90,33 @@ import {
   useTrainingRuntimeStore,
 } from "@/features/training";
 import type { TrainingRunSummary } from "@/features/training";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import { toast } from "@/lib/toast";
 import { ShutdownDialog } from "@/components/shutdown-dialog";
+import { translate, useT, type TranslationKey } from "@/i18n";
+
+const EMPHASIS_MARKER = "__UNSLOTH_I18N_EMPHASIS_MARKER__";
+
+type AppT = ReturnType<typeof useT>;
+
+function renderEmphasizedTranslation(
+  t: AppT,
+  key: TranslationKey,
+  emphasizedValue: string,
+): ReactNode {
+  const translated = t(key, { name: EMPHASIS_MARKER });
+  const parts = translated.split(EMPHASIS_MARKER);
+  if (parts.length === 1) return translated;
+
+  const nodes: ReactNode[] = [];
+  parts.forEach((part, index) => {
+    if (part.length > 0) nodes.push(part);
+    if (index < parts.length - 1) {
+      nodes.push(<em key={`emphasis-${index}`}>{emphasizedValue}</em>);
+    }
+  });
+  return nodes;
+}
 
 function getTourId(pathname: string): string | null {
   if (pathname.startsWith("/studio")) return "studio";
@@ -185,6 +209,7 @@ function NavItem({
 }
 
 export function AppSidebar() {
+  const t = useT();
   const { isDark, toggleTheme, anchorRef } = useAnimatedThemeToggle();
   const { pathname, search } = useRouterState({
     select: (s) => ({
@@ -204,14 +229,8 @@ export function AppSidebar() {
   const chatOnly = usePlatformStore((s) => s.isChatOnly());
   const [shutdownOpen, setShutdownOpen] = useState(false);
 
-  // Chat collapsible state — open by default, auto-expand on route entry
   const isChatRoute = pathname.startsWith("/chat");
   const isStudioRoute = pathname === "/studio" || pathname.startsWith("/studio/");
-  const [chatOpen, setChatOpen] = useState(true);
-  const [runsOpen, setRunsOpen] = useState(true);
-
-  useEffect(() => { if (isChatRoute) setChatOpen(true); }, [isChatRoute]);
-  useEffect(() => { if (isStudioRoute) setRunsOpen(true); }, [isStudioRoute]);
 
   const scrollRef = useRef<HTMLDivElement | null>(null);
   const [scrolled, setScrolled] = useState(false);
@@ -290,7 +309,7 @@ export function AppSidebar() {
       try {
         await renameChatItem(target.item, renameTrimmed);
       } catch (err) {
-        toast.error("Failed to rename chat", {
+        toast.error(translate("shell.toast.failedToRenameChat"), {
           description: err instanceof Error ? err.message : undefined,
         });
       }
@@ -300,7 +319,7 @@ export function AppSidebar() {
       const updated = await renameTrainingRun(target.run.id, nextRunDisplayName);
       emitTrainingRunUpdated(updated);
     } catch (err) {
-      toast.error("Failed to rename run", {
+      toast.error(translate("shell.toast.failedToRenameRun"), {
         description: err instanceof Error ? err.message : undefined,
       });
     }
@@ -320,14 +339,14 @@ export function AppSidebar() {
       try {
         await handleDeleteThread(target.item);
       } catch (err) {
-        toast.error("Failed to delete chat", {
+        toast.error(translate("shell.toast.failedToDeleteChat"), {
           description: err instanceof Error ? err.message : undefined,
         });
       }
       return;
     }
     if (target.run.status === "running") {
-      toast.error("Cannot delete a running training run");
+      toast.error(t("shell.toast.cannotDeleteRunningRun"));
       return;
     }
     try {
@@ -337,7 +356,7 @@ export function AppSidebar() {
       }
       emitTrainingRunDeleted(target.run.id);
     } catch (err) {
-      toast.error("Failed to delete run", {
+      toast.error(translate("shell.toast.failedToDeleteRun"), {
         description: err instanceof Error ? err.message : undefined,
       });
     }
@@ -366,7 +385,7 @@ export function AppSidebar() {
               });
             }}
             className="flex items-center gap-[6px] select-none"
-            aria-label="Unsloth home"
+            aria-label={t("shell.aria.home")}
           >
             <img
               src="/circle-logo-small.png"
@@ -377,7 +396,7 @@ export function AppSidebar() {
               unsloth
             </span>
             <span className="nav-badge ml-0.5 inline-flex items-center justify-center rounded-full border border-nav-beta-border px-[5px] pt-[3px] pb-[2px] text-[8px] font-medium leading-none tracking-[0.04em] text-nav-fg-muted antialiased subpixel-antialiased shadow-[0_1px_2px_rgba(0,0,0,0.06)] dark:shadow-[0_1px_2px_rgba(0,0,0,0.35)]">
-              BETA
+              {t("shell.beta")}
             </span>
           </Link>
           {!isMobile && (
@@ -387,7 +406,7 @@ export function AppSidebar() {
                   type="button"
                   onClick={togglePinned}
                   className="inline-flex h-[35px] w-[32px] items-center justify-center rounded-[10px] text-nav-icon-idle dark:text-nav-fg-muted transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  aria-label="Close sidebar"
+                  aria-label={t("shell.aria.closeSidebar")}
                 >
                   <HugeiconsIcon icon={LayoutAlignLeftIcon} strokeWidth={1.75} className="size-icon" />
                 </button>
@@ -397,7 +416,7 @@ export function AppSidebar() {
                 sideOffset={6}
                 className="tooltip-compact"
               >
-                Close sidebar
+                {t("shell.aria.closeSidebar")}
               </TooltipContent>
             </Tooltip>
           )}
@@ -412,7 +431,7 @@ export function AppSidebar() {
                   type="button"
                   onClick={togglePinned}
                   className="inline-flex h-[35px] w-[32px] items-center justify-center rounded-[10px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  aria-label="Open sidebar"
+                  aria-label={t("shell.aria.openSidebar")}
                 >
                   <HugeiconsIcon icon={LayoutAlignLeftIcon} strokeWidth={1.75} className="size-icon" />
                 </button>
@@ -422,7 +441,7 @@ export function AppSidebar() {
                 sideOffset={8}
                 className="tooltip-compact"
               >
-                Open sidebar
+                {t("shell.aria.openSidebar")}
               </TooltipContent>
             </Tooltip>
           </div>
@@ -434,7 +453,7 @@ export function AppSidebar() {
           <SidebarMenu>
             <NavItem
               icon={PencilEdit02Icon}
-              label="New Chat"
+              label={t("shell.navigation.newChat")}
               active={false}
               disabled={chatDisabled}
               onClick={() => {
@@ -446,7 +465,7 @@ export function AppSidebar() {
             />
             <NavItem
               icon={ColumnInsertIcon}
-              label="Compare"
+              label={t("shell.navigation.compare")}
               active={!!search.compare && !chatItems.some((i) => i.id === search.compare)}
               disabled={chatDisabled}
               dataTour="chat-compare"
@@ -459,7 +478,7 @@ export function AppSidebar() {
             />
             <NavItem
               icon={Search01Icon}
-              label="Search"
+              label={t("shell.navigation.search")}
               active={false}
               disabled={chatDisabled}
               onClick={() => {
@@ -477,7 +496,7 @@ export function AppSidebar() {
           <SidebarMenu>
             <NavItem
               icon={TestTubeOutlineIcon}
-              label="Train"
+              label={t("shell.navigation.train")}
               active={pathname === "/studio" || pathname.startsWith("/studio/")}
               disabled={chatOnly}
               onClick={() => {
@@ -489,7 +508,7 @@ export function AppSidebar() {
 
             <NavItem
               icon={ChefHatIcon}
-              label="Recipes"
+              label={t("shell.navigation.recipes")}
               active={isRecipesRoute}
               onClick={() => {
                 navigate({ to: "/data-recipes" });
@@ -499,7 +518,7 @@ export function AppSidebar() {
 
             <NavItem
               icon={DownloadSquare01Icon}
-              label="Export"
+              label={t("shell.navigation.export")}
               active={pathname === "/export" || pathname.startsWith("/export/")}
               disabled={chatOnly}
               onClick={() => {
@@ -513,13 +532,16 @@ export function AppSidebar() {
       </SidebarGroup>
 
       <SidebarContent ref={scrollRef} className="gap-0 overflow-y-auto overscroll-contain min-h-0">
-        {/* Recent Chats — hide on Studio only (Eyera fac13); chatOpen = ec695 clickability */}
         {!isStudioRoute && chatItems.length > 0 && (
-          <Collapsible open={chatOpen} onOpenChange={setChatOpen} asChild>
+          <Collapsible
+            key={isChatRoute ? "chat-route" : "non-chat-route"}
+            defaultOpen
+            asChild
+          >
           <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
             <SidebarGroupLabel className={cn("sidebar-sticky-label", scrolled && "is-scrolled")} asChild>
               <CollapsibleTrigger className="cursor-pointer flex w-full items-center justify-between">
-                Recents
+                {t("shell.navigation.recents")}
                 <ChevronDown className="size-3.5 transition-transform duration-200 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
@@ -552,7 +574,7 @@ export function AppSidebar() {
                         <button
                           type="button"
                           onClick={(e) => e.stopPropagation()}
-                          aria-label="Chat options"
+                          aria-label={t("shell.aria.chatOptions")}
                           className="sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
                         >
                           <span className="sidebar-row-action-glyph">
@@ -568,14 +590,14 @@ export function AppSidebar() {
                       >
                         <DropdownMenuItem onSelect={() => openRenameChat(item)}>
                           <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
-                          <span>Rename</span>
+                          <span>{t("common.rename")}</span>
                         </DropdownMenuItem>
                         <DropdownMenuItem
                           variant="destructive"
                           onSelect={() => setConfirmingDelete({ kind: "chat", item })}
                         >
                           <HugeiconsIcon icon={Delete02Icon} strokeWidth={1.75} className="size-icon" />
-                          <span>Delete</span>
+                          <span>{t("common.delete")}</span>
                         </DropdownMenuItem>
                       </DropdownMenuContent>
                     </DropdownMenu>
@@ -588,13 +610,12 @@ export function AppSidebar() {
           </Collapsible>
         )}
 
-        {/* Recent Runs */}
         {isStudioRoute && runItems.length > 0 && !chatOnly && (
-          <Collapsible open={runsOpen} onOpenChange={setRunsOpen} asChild>
+          <Collapsible key="studio-runs-route" defaultOpen asChild>
           <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
             <SidebarGroupLabel className={cn("sidebar-sticky-label", scrolled && "is-scrolled")} asChild>
               <CollapsibleTrigger className="cursor-pointer flex w-full items-center justify-between">
-                Recents
+                {t("shell.navigation.recents")}
                 <ChevronDown className="size-3.5 transition-transform duration-200 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
@@ -641,7 +662,7 @@ export function AppSidebar() {
                             <button
                               type="button"
                               onClick={(e) => e.stopPropagation()}
-                              aria-label="Run options"
+                              aria-label={t("shell.aria.runOptions")}
                               className="sidebar-row-action group-hover/run-item:opacity-100 group-hover/run-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
                             >
                               <span className="sidebar-row-action-glyph">
@@ -657,7 +678,7 @@ export function AppSidebar() {
                           >
                             <DropdownMenuItem onSelect={() => openRenameRun(run)}>
                               <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
-                              <span>Rename</span>
+                              <span>{t("common.rename")}</span>
                             </DropdownMenuItem>
                             <DropdownMenuItem
                               variant="destructive"
@@ -667,7 +688,7 @@ export function AppSidebar() {
                               }
                             >
                               <HugeiconsIcon icon={Delete02Icon} strokeWidth={1.75} className="size-icon" />
-                              <span>Delete</span>
+                              <span>{t("common.delete")}</span>
                             </DropdownMenuItem>
                           </DropdownMenuContent>
                         </DropdownMenu>
@@ -689,7 +710,7 @@ export function AppSidebar() {
               <DropdownMenuTrigger asChild>
                 <SidebarMenuButton
                   size="lg"
-                  aria-label={`${displayTitle} account menu`}
+                  aria-label={t("shell.accountMenu", { name: displayTitle })}
                   className="sidebar-nav-btn !h-[50px] gap-[8px] px-2 py-[9px] rounded-[10px]"
                 >
                   <div className="shrink-0">
@@ -717,16 +738,16 @@ export function AppSidebar() {
                     onSelect={() => useSettingsDialogStore.getState().openDialog()}
                   >
                     <HugeiconsIcon icon={Settings02Icon} strokeWidth={1.75} className="size-icon" />
-                    <span>Settings</span>
+                    <span>{t("shell.navigation.settings")}</span>
                     <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
                   </DropdownMenuItem>
                   <DropdownMenuItem
                     onSelect={() => useSettingsDialogStore.getState().openDialog("api-keys")}
                   >
                     <HugeiconsIcon icon={Globe02Icon} strokeWidth={1.75} className="size-[18px]" />
-                    <span>API</span>
+                    <span>{t("shell.navigation.api")}</span>
                     <span className="ml-auto rounded-[6px] border border-emerald-500/25 bg-emerald-500/10 px-1.5 py-0.5 text-[10px] leading-none font-semibold text-emerald-700 dark:text-emerald-300">
-                      New
+                      {t("common.new")}
                     </span>
                   </DropdownMenuItem>
                   <DropdownMenuItem
@@ -734,7 +755,11 @@ export function AppSidebar() {
                     onSelect={(e) => { e.preventDefault(); toggleTheme(); }}
                   >
                     {isDark ? <Sun strokeWidth={1.75} className="size-icon" /> : <Moon strokeWidth={1.75} className="size-icon" />}
-                    <span>{isDark ? "Light Mode" : "Dark Mode"}</span>
+                    <span>
+                      {isDark
+                        ? t("shell.navigation.lightMode")
+                        : t("shell.navigation.darkMode")}
+                    </span>
                   </DropdownMenuItem>
                   <DropdownMenuItem
                     disabled={!getTourId(pathname)}
@@ -749,7 +774,7 @@ export function AppSidebar() {
                     }}
                   >
                     <HugeiconsIcon icon={CursorInfo02Icon} strokeWidth={1.75} className="size-icon" />
-                    <span>Guided Tour</span>
+                    <span>{t("shell.navigation.guidedTour")}</span>
                   </DropdownMenuItem>
                 </DropdownMenuGroup>
                 <DropdownMenuSeparator className="mx-2.5! my-2.5! h-0! border-t border-border/70 bg-transparent!" />
@@ -757,7 +782,7 @@ export function AppSidebar() {
                   onSelect={() => useSettingsDialogStore.getState().openDialog("about")}
                 >
                   <HugeiconsIcon icon={HelpCircleIcon} strokeWidth={1.75} className="size-icon" />
-                  <span>Help</span>
+                  <span>{t("common.help")}</span>
                 </DropdownMenuItem>
                 <DropdownMenuItem
                   onSelect={async () => {
@@ -772,11 +797,11 @@ export function AppSidebar() {
                   }}
                 >
                   <HugeiconsIcon icon={Logout01Icon} strokeWidth={1.75} className="size-icon" />
-                  <span>Log out</span>
+                  <span>{t("shell.navigation.logOut")}</span>
                 </DropdownMenuItem>
                 <DropdownMenuItem onSelect={() => setShutdownOpen(true)}>
                   <HugeiconsIcon icon={PowerIcon} strokeWidth={1.75} className="size-icon" />
-                  <span>Shutdown</span>
+                  <span>{t("common.shutdown")}</span>
                 </DropdownMenuItem>
               </DropdownMenuContent>
             </DropdownMenu>
@@ -800,20 +825,23 @@ export function AppSidebar() {
         <DialogHeader>
           <DialogTitle>
             {confirmingDelete?.kind === "run"
-              ? "Delete training run"
-              : "Delete chat"}
+              ? t("shell.dialog.deleteRun.title")
+              : t("shell.dialog.deleteChat.title")}
           </DialogTitle>
           <DialogDescription>
             {confirmingDelete?.kind === "run" ? (
-              <>
-                Are you sure you want to delete this run{" "}
-                <em>{confirmingDelete.run.display_name ?? confirmingDelete.run.model_name}</em>?
-              </>
+              renderEmphasizedTranslation(
+                t,
+                "shell.dialog.deleteRun.description",
+                confirmingDelete.run.display_name ??
+                  confirmingDelete.run.model_name,
+              )
             ) : confirmingDelete?.kind === "chat" ? (
-              <>
-                Are you sure you want to delete this chat{" "}
-                <em>{confirmingDelete.item.title}</em>?
-              </>
+              renderEmphasizedTranslation(
+                t,
+                "shell.dialog.deleteChat.description",
+                confirmingDelete.item.title,
+              )
             ) : null}
           </DialogDescription>
         </DialogHeader>
@@ -823,14 +851,14 @@ export function AppSidebar() {
             variant="ghost"
             onClick={() => setConfirmingDelete(null)}
           >
-            Cancel
+            {t("common.cancel")}
           </Button>
           <Button
             type="button"
             variant="destructive"
             onClick={() => void commitDelete()}
           >
-            Delete
+            {t("common.delete")}
           </Button>
         </DialogFooter>
       </DialogContent>
@@ -844,7 +872,9 @@ export function AppSidebar() {
       <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
         <DialogHeader>
           <DialogTitle>
-            {renamingTarget?.kind === "run" ? "Rename run" : "Rename chat"}
+            {renamingTarget?.kind === "run"
+              ? t("shell.dialog.renameRun.title")
+              : t("shell.dialog.renameChat.title")}
           </DialogTitle>
         </DialogHeader>
         <Input
@@ -858,8 +888,16 @@ export function AppSidebar() {
           }}
           autoFocus
           maxLength={120}
-          placeholder={renamingTarget?.kind === "run" ? "Run name" : "Chat title"}
-          aria-label={renamingTarget?.kind === "run" ? "Run name" : "Chat title"}
+          placeholder={
+            renamingTarget?.kind === "run"
+              ? t("shell.dialog.renameRun.placeholder")
+              : t("shell.dialog.renameChat.placeholder")
+          }
+          aria-label={
+            renamingTarget?.kind === "run"
+              ? t("shell.dialog.renameRun.placeholder")
+              : t("shell.dialog.renameChat.placeholder")
+          }
           className="focus-visible:border-input focus-visible:ring-0"
         />
         <DialogFooter className="flex-wrap gap-2 sm:justify-end">
@@ -868,14 +906,14 @@ export function AppSidebar() {
             variant="ghost"
             onClick={() => setRenamingTarget(null)}
           >
-            Cancel
+            {t("common.cancel")}
           </Button>
           <Button
             type="button"
             onClick={() => void commitRename()}
             disabled={!renameDirty}
           >
-            Save
+            {t("common.save")}
           </Button>
         </DialogFooter>
       </DialogContent>
diff --git a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
index f30af7fcf9..ed590f226e 100644
--- a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
+++ b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
@@ -5,6 +5,7 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { getAuthToken } from "@/features/auth";
+import { useT } from "@/i18n";
 import { toastError, toastSuccess } from "@/shared/toast";
 import { Camera } from "lucide-react";
 import { useMemo, useRef, useState } from "react";
@@ -37,6 +38,7 @@ function readPersistedProfile(): { displayName: string; avatarDataUrl: string |
 }
 
 export function ProfilePersonalizationPanel() {
+  const t = useT();
   const displayName = useUserProfileStore((s) => s.displayName);
   const avatarDataUrl = useUserProfileStore((s) => s.avatarDataUrl);
   const setDisplayName = useUserProfileStore((s) => s.setDisplayName);
@@ -60,11 +62,11 @@ export function ProfilePersonalizationPanel() {
       setDisplayName(trimmed);
       const persisted = readPersistedProfile();
       if (persisted && persisted.displayName === trimmed) {
-        toastSuccess("Profile name saved");
+        toastSuccess(t("settings.profile.nameSaved"));
       } else {
         toastError(
-          "Could not persist profile name",
-          "Name updated for this session, but may not persist after reload.",
+          t("settings.profile.namePersistErrorTitle"),
+          t("settings.profile.namePersistErrorDescription"),
         );
       }
     }
@@ -78,17 +80,18 @@ export function ProfilePersonalizationPanel() {
       setAvatarDataUrl(dataUrl);
       const persisted = readPersistedProfile();
       if (persisted && persisted.avatarDataUrl === dataUrl) {
-        toastSuccess("Profile photo updated");
+        toastSuccess(t("settings.profile.photoUpdated"));
       } else {
         toastError(
-          "Could not persist profile photo",
-          "Photo updated for this session, but may not persist after reload.",
+          t("settings.profile.photoPersistErrorTitle"),
+          t("settings.profile.photoPersistErrorDescription"),
         );
       }
     } catch (e) {
-      const message = e instanceof Error ? e.message : "Could not use this image.";
+      const message =
+        e instanceof Error ? e.message : t("settings.profile.imageUseError");
       setImageError(message);
-      toastError("Could not update profile photo", message);
+      toastError(t("settings.profile.photoUpdateErrorTitle"), message);
     }
   };
 
@@ -115,7 +118,7 @@ export function ProfilePersonalizationPanel() {
           type="button"
           onClick={() => fileInputRef.current?.click()}
           className="absolute right-0 bottom-0 -translate-x-[15.625%] -translate-y-[15.625%] flex size-8 items-center justify-center rounded-full border border-border bg-background text-foreground shadow-sm transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
-          aria-label="Change profile picture"
+          aria-label={t("settings.profile.changePicture")}
         >
           <Camera className="size-3.5" strokeWidth={2} />
         </button>
@@ -123,7 +126,7 @@ export function ProfilePersonalizationPanel() {
 
       <div className="flex w-full max-w-[560px] flex-col gap-2">
         <Label htmlFor="profile-display-name" className="text-xs font-medium text-muted-foreground">
-          Display name
+          {t("settings.profile.displayName")}
         </Label>
         <div className="flex items-center gap-2">
           <Input
@@ -142,7 +145,7 @@ export function ProfilePersonalizationPanel() {
             className="h-10 min-w-0 flex-1 rounded-full text-sm"
           />
           <Button type="button" size="sm" className="h-10 px-5" onClick={saveName} disabled={!hasNameChanges}>
-            Save
+            {t("common.save")}
           </Button>
         </div>
       </div>
diff --git a/studio/frontend/src/features/settings/components/api-key-row.tsx b/studio/frontend/src/features/settings/components/api-key-row.tsx
index ced6de17d1..9a6e1ee207 100644
--- a/studio/frontend/src/features/settings/components/api-key-row.tsx
+++ b/studio/frontend/src/features/settings/components/api-key-row.tsx
@@ -14,30 +14,39 @@ import {
   MoreHorizontalIcon,
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
+import { useT } from "@/i18n";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import type { ApiKey } from "../api/api-keys";
 
-function relative(iso: string | null): string {
-  if (!iso) return "never";
+type SettingsT = ReturnType<typeof useT>;
+
+function relative(iso: string | null, t: SettingsT): string {
+  if (!iso) return t("settings.apiKeys.relativeNever");
   const diff = Date.now() - new Date(iso).getTime();
   const days = Math.floor(diff / 86400000);
   if (days < 1) {
     const hours = Math.floor(diff / 3600000);
-    if (hours < 1) return "just now";
-    return `${hours}h ago`;
+    if (hours < 1) return t("settings.apiKeys.relativeJustNow");
+    return t("settings.apiKeys.relativeHoursAgo", { count: hours });
   }
-  if (days < 30) return `${days}d ago`;
-  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
-  return `${Math.floor(days / 365)}y ago`;
+  if (days < 30) return t("settings.apiKeys.relativeDaysAgo", { count: days });
+  if (days < 365) {
+    return t("settings.apiKeys.relativeMonthsAgo", {
+      count: Math.floor(days / 30),
+    });
+  }
+  return t("settings.apiKeys.relativeYearsAgo", {
+    count: Math.floor(days / 365),
+  });
 }
 
-function expiresText(iso: string | null): string {
-  if (!iso) return "never";
+function expiresText(iso: string | null, t: SettingsT): string {
+  if (!iso) return t("settings.apiKeys.relativeNever");
   const diff = new Date(iso).getTime() - Date.now();
-  if (diff < 0) return "expired";
+  if (diff < 0) return t("settings.apiKeys.expired");
   const days = Math.floor(diff / 86400000);
-  if (days < 1) return "today";
-  return `in ${days}d`;
+  if (days < 1) return t("settings.apiKeys.today");
+  return t("settings.apiKeys.inDays", { count: days });
 }
 
 export function ApiKeyRow({
@@ -47,6 +56,7 @@ export function ApiKeyRow({
   apiKey: ApiKey;
   onRevoke: (key: ApiKey) => void;
 }) {
+  const t = useT();
   const prefix = `sk-unsloth-${apiKey.key_prefix}…`;
   return (
     <div className="group flex items-center gap-3 border-b border-border/60 px-1 py-3 last:border-b-0 transition-colors hover:bg-accent/40">
@@ -64,11 +74,23 @@ export function ApiKeyRow({
           </code>
         </div>
         <div className="flex flex-wrap gap-x-1.5 text-[11px] text-muted-foreground">
-          <span>Created {relative(apiKey.created_at)}</span>
+          <span>
+            {t("settings.apiKeys.created", {
+              value: relative(apiKey.created_at, t),
+            })}
+          </span>
           <span>·</span>
-          <span>Used {relative(apiKey.last_used_at)}</span>
+          <span>
+            {t("settings.apiKeys.used", {
+              value: relative(apiKey.last_used_at, t),
+            })}
+          </span>
           <span>·</span>
-          <span>Expires {expiresText(apiKey.expires_at)}</span>
+          <span>
+            {t("settings.apiKeys.expires", {
+              value: expiresText(apiKey.expires_at, t),
+            })}
+          </span>
         </div>
       </div>
       <DropdownMenu>
@@ -77,7 +99,7 @@ export function ApiKeyRow({
             variant="ghost"
             size="sm"
             className="size-7 p-0 opacity-0 transition-opacity group-hover:opacity-100 data-[state=open]:opacity-100 max-sm:!opacity-100 max-sm:size-9"
-            aria-label={`Actions for ${apiKey.name}`}
+            aria-label={t("settings.apiKeys.actionsFor", { name: apiKey.name })}
           >
             <HugeiconsIcon icon={MoreHorizontalIcon} className="size-4" />
           </Button>
@@ -85,14 +107,14 @@ export function ApiKeyRow({
         <DropdownMenuContent align="end">
           <DropdownMenuItem onClick={async () => { await copyToClipboard(prefix); }}>
             <HugeiconsIcon icon={Copy01Icon} className="size-3.5 mr-2" />
-            Copy prefix
+            {t("settings.apiKeys.copyPrefix")}
           </DropdownMenuItem>
           <DropdownMenuItem
             onClick={() => onRevoke(apiKey)}
             className="text-destructive focus:text-destructive"
           >
             <HugeiconsIcon icon={Delete02Icon} className="size-3.5 mr-2" />
-            Revoke token
+            {t("settings.apiKeys.revokeToken")}
           </DropdownMenuItem>
         </DropdownMenuContent>
       </DropdownMenu>
diff --git a/studio/frontend/src/features/settings/components/create-key-form.tsx b/studio/frontend/src/features/settings/components/create-key-form.tsx
index a0f2d7f82d..93802bfad8 100644
--- a/studio/frontend/src/features/settings/components/create-key-form.tsx
+++ b/studio/frontend/src/features/settings/components/create-key-form.tsx
@@ -3,6 +3,7 @@
 
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
+import { useT } from "@/i18n";
 import { cn } from "@/lib/utils";
 import { useState } from "react";
 import { createApiKey } from "../api/api-keys";
@@ -21,6 +22,7 @@ export function CreateKeyForm({
   onCreated: (rawKey: string) => void;
   onError: (message: string) => void;
 }) {
+  const t = useT();
   const [name, setName] = useState("");
   const [expiry, setExpiry] = useState<number | null>(null);
   const [loading, setLoading] = useState(false);
@@ -33,8 +35,11 @@ export function CreateKeyForm({
       const result = await createApiKey(name.trim(), expiry);
       onCreated(result.key);
       setName("");
-    } catch (err) {
-      onError(err instanceof Error ? err.message : "Couldn't create access token.");
+    } catch {
+      // API helpers in ../api/api-keys.ts throw generic English Error
+      // messages; always use the translated message so zh-CN users do not
+      // see English text bleed through from internal exceptions.
+      onError(t("settings.apiKeys.createError"));
     } finally {
       setLoading(false);
     }
@@ -49,9 +54,9 @@ export function CreateKeyForm({
         <Input
           value={name}
           onChange={(e) => setName(e.target.value)}
-          placeholder="Token name (e.g. production)"
+          placeholder={t("settings.apiKeys.tokenNamePlaceholder")}
           className="h-8 min-w-[180px] flex-1 text-sm"
-          aria-label="New access token name"
+          aria-label={t("settings.apiKeys.newAccessTokenName")}
         />
         <div className="inline-flex items-center rounded-md border border-border bg-background p-0.5">
           {EXPIRY_PRESETS.map((p) => {
@@ -69,13 +74,15 @@ export function CreateKeyForm({
                     : "text-muted-foreground hover:text-foreground",
                 )}
               >
-                {p.label}
+                {p.value === null ? t("settings.apiKeys.never") : p.label}
               </button>
             );
           })}
         </div>
         <Button type="submit" size="sm" disabled={loading || !name.trim()}>
-          {loading ? "Creating…" : "Create token"}
+          {loading
+            ? t("settings.apiKeys.creating")
+            : t("settings.apiKeys.createToken")}
         </Button>
       </div>
     </form>
diff --git a/studio/frontend/src/features/settings/components/key-reveal-card.tsx b/studio/frontend/src/features/settings/components/key-reveal-card.tsx
index 2b589e88fe..bdcb861c1d 100644
--- a/studio/frontend/src/features/settings/components/key-reveal-card.tsx
+++ b/studio/frontend/src/features/settings/components/key-reveal-card.tsx
@@ -2,6 +2,7 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { Button } from "@/components/ui/button";
+import { useT } from "@/i18n";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { cn } from "@/lib/utils";
 import { Copy01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
@@ -15,6 +16,7 @@ export function KeyRevealCard({
   rawKey: string;
   onDone: () => void;
 }) {
+  const t = useT();
   const [copied, setCopied] = useState(false);
 
   const handleCopy = async () => {
@@ -32,7 +34,7 @@ export function KeyRevealCard({
           className="size-3.5 text-emerald-600 dark:text-emerald-500"
         />
         <span className="text-xs font-medium text-emerald-700 dark:text-emerald-500">
-          New access token created
+          {t("settings.apiKeys.newTokenCreated")}
         </span>
       </div>
       <button
@@ -43,7 +45,11 @@ export function KeyRevealCard({
           "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
           copied && "border-emerald-500/40 bg-emerald-500/10",
         )}
-        aria-label={copied ? "Access token copied" : "Copy access token"}
+        aria-label={
+          copied
+            ? t("settings.apiKeys.accessTokenCopied")
+            : t("settings.apiKeys.copyAccessToken")
+        }
       >
         <code className="min-w-0 flex-1 break-all text-left text-foreground">
           {rawKey}
@@ -55,7 +61,7 @@ export function KeyRevealCard({
       </button>
       <div className="flex items-center justify-between gap-3 pt-0.5">
         <p className="text-[11px] text-muted-foreground">
-          Copy now — this won't be shown again.
+          {t("settings.apiKeys.copyNow")}
         </p>
         <Button
           type="button"
@@ -63,7 +69,7 @@ export function KeyRevealCard({
           onClick={onDone}
           className="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
         >
-          Done
+          {t("common.done")}
         </Button>
       </div>
     </div>
diff --git a/studio/frontend/src/features/settings/components/language-select.tsx b/studio/frontend/src/features/settings/components/language-select.tsx
new file mode 100644
index 0000000000..9d30e06147
--- /dev/null
+++ b/studio/frontend/src/features/settings/components/language-select.tsx
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  LOCALES,
+  isSupportedLocale,
+  setLocale,
+  useT,
+  useLocale,
+} from "@/i18n";
+
+export function LanguageSelect() {
+  const t = useT();
+  const locale = useLocale();
+
+  return (
+    <Select
+      value={locale}
+      onValueChange={(value) => {
+        if (isSupportedLocale(value)) setLocale(value);
+      }}
+    >
+      <SelectTrigger
+        aria-label={t("settings.appearance.language.label")}
+        className="w-40"
+        size="sm"
+      >
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {Object.entries(LOCALES).map(([value, metadata]) => (
+          <SelectItem key={value} value={value}>
+            {metadata.nativeLabel}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
diff --git a/studio/frontend/src/features/settings/components/theme-segmented.tsx b/studio/frontend/src/features/settings/components/theme-segmented.tsx
index 1061995346..36e7062d8f 100644
--- a/studio/frontend/src/features/settings/components/theme-segmented.tsx
+++ b/studio/frontend/src/features/settings/components/theme-segmented.tsx
@@ -2,6 +2,7 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { cn } from "@/lib/utils";
+import { useT, type TranslationKey } from "@/i18n";
 import {
   LaptopIcon,
   Moon02Icon,
@@ -11,13 +12,18 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { motion, useReducedMotion } from "motion/react";
 import { useTheme, type Theme } from "../stores/theme-store";
 
-const OPTIONS: { value: Theme; label: string; icon: typeof Sun02Icon }[] = [
-  { value: "light", label: "Light", icon: Sun02Icon },
-  { value: "dark", label: "Dark", icon: Moon02Icon },
-  { value: "system", label: "System", icon: LaptopIcon },
+const OPTIONS: {
+  value: Theme;
+  labelKey: TranslationKey;
+  icon: typeof Sun02Icon;
+}[] = [
+  { value: "light", labelKey: "settings.appearance.theme.light", icon: Sun02Icon },
+  { value: "dark", labelKey: "settings.appearance.theme.dark", icon: Moon02Icon },
+  { value: "system", labelKey: "settings.appearance.theme.system", icon: LaptopIcon },
 ];
 
 export function ThemeSegmented() {
+  const t = useT();
   const { theme, setTheme } = useTheme();
   const reduced = useReducedMotion();
   return (
@@ -49,7 +55,7 @@ export function ThemeSegmented() {
               />
             )}
             <HugeiconsIcon icon={opt.icon} className="relative z-10 size-3.5" />
-            <span className="relative z-10">{opt.label}</span>
+            <span className="relative z-10">{t(opt.labelKey)}</span>
           </button>
         );
       })}
diff --git a/studio/frontend/src/features/settings/components/update-studio-instructions.tsx b/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
index e4cdccd2d7..90f66483b7 100644
--- a/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
+++ b/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
@@ -2,6 +2,7 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
+import { useT } from "@/i18n";
 import { cn } from "@/lib/utils";
 import { Copy01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
@@ -29,10 +30,13 @@ export type UpdateInstallSource =
   | "unknown";
 type UpdateInstallSourceState = UpdateInstallSource | "loading";
 
-function getStudioUpdateInstructionLine(shell: UpdateShell): string {
+function getStudioUpdateInstructionLine(
+  shell: UpdateShell,
+  t: ReturnType<typeof useT>,
+): string {
   return shell === "windows"
-    ? "Open PowerShell and run:"
-    : "Open Terminal and run:";
+    ? t("settings.about.update.openPowerShell")
+    : t("settings.about.update.openTerminal");
 }
 
 function isLocalInstallSource(
@@ -59,6 +63,7 @@ function CopyableCommand({
   command: string;
   copyLabel: string;
 }): ReactElement {
+  const t = useT();
   const [copied, setCopied] = useState(false);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -89,14 +94,26 @@ function CopyableCommand({
         value={command}
         className="min-w-0 flex-1 bg-transparent px-2 py-1.5 font-mono text-[11px] text-foreground outline-none"
         title={command}
-        aria-label={`${copyLabel} text`}
+        aria-label={t("settings.about.update.commandText", {
+          label: copyLabel,
+        })}
       />
       <button
         type="button"
         onClick={handleCopy}
         className="flex shrink-0 items-center justify-center border-l border-border px-2 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-        title={copied ? "Copied" : "Copy command"}
-        aria-label={copied ? `${copyLabel} copied` : `Copy ${copyLabel}`}
+        title={
+          copied
+            ? t("settings.about.update.copied")
+            : t("settings.about.update.copyCommand")
+        }
+        aria-label={
+          copied
+            ? t("settings.about.update.commandCopied", { label: copyLabel })
+            : t("settings.about.update.copyNamedCommand", {
+                label: copyLabel,
+              })
+        }
       >
         {copied ? (
           <HugeiconsIcon
@@ -123,7 +140,9 @@ export function UpdateStudioInstructions({
   installSource?: UpdateInstallSourceState | null;
   showTitle?: boolean;
 }): ReactElement {
-  const [shell, setShell] = useState<UpdateShell>(defaultShell);
+  const t = useT();
+  const [shellOverride, setShellOverride] = useState<UpdateShell | null>(null);
+  const shell = shellOverride ?? defaultShell;
   const prefersReducedMotion = useReducedMotion();
   const windows = shell === "windows";
   const localInstallSource = isLocalInstallSource(installSource);
@@ -144,10 +163,6 @@ export function UpdateStudioInstructions({
     ? { opacity: 1 }
     : { opacity: 0, y: -2 };
 
-  useEffect(() => {
-    setShell(defaultShell);
-  }, [defaultShell]);
-
   return (
     <div className={cn("flex flex-col gap-3", className)}>
       <div
@@ -158,13 +173,13 @@ export function UpdateStudioInstructions({
       >
         {showTitle ? (
           <p className="shrink-0 whitespace-nowrap text-sm font-semibold font-heading">
-            Update Unsloth Studio
+            {t("settings.about.update.title")}
           </p>
         ) : null}
         <div className="flex shrink-0 items-center gap-0.5 text-[11px]">
           <button
             type="button"
-            onClick={() => setShell("windows")}
+            onClick={() => setShellOverride("windows")}
             className={cn(
               "px-0.5 py-0.5 font-medium transition-colors",
               windows
@@ -178,7 +193,7 @@ export function UpdateStudioInstructions({
           <span className="text-border">/</span>
           <button
             type="button"
-            onClick={() => setShell("unix")}
+            onClick={() => setShellOverride("unix")}
             className={cn(
               "px-0.5 py-0.5 font-medium transition-colors",
               windows
@@ -193,31 +208,28 @@ export function UpdateStudioInstructions({
       </div>
       {loadingInstallSource ? (
         <p className="text-xs text-muted-foreground leading-relaxed">
-          Checking how Studio was installed…
+          {t("settings.about.update.checkingInstall")}
         </p>
       ) : localInstallSource ? (
         <>
           <p className="text-xs text-muted-foreground leading-relaxed">
-            Source or local install detected. To avoid replacing it with PyPI,
-            update from the checkout or source you originally installed from.
+            {t("settings.about.update.localInstallDetected")}
           </p>
           {checkoutInstallSource ? (
             <>
               <p className="text-xs text-muted-foreground leading-relaxed">
-                Pull latest changes from your Unsloth repo checkout, then update
-                Studio locally:
+                {t("settings.about.update.pullThenUpdate")}
               </p>
               <CopyableCommand
                 command={STUDIO_LOCAL_PULL_CMD}
-                copyLabel="git pull command"
+                copyLabel={t("settings.about.update.gitPullCommand")}
               />
               <CopyableCommand
                 command={STUDIO_LOCAL_UPDATE_CMD}
-                copyLabel="local update command"
+                copyLabel={t("settings.about.update.localUpdateCommand")}
               />
               <p className="text-xs text-muted-foreground leading-relaxed">
-                If the Studio update command is unavailable, run the local
-                installer from that checkout:
+                {t("settings.about.update.localInstallerFallback")}
               </p>
               <AnimatePresence mode="wait" initial={false}>
                 <motion.div
@@ -233,7 +245,7 @@ export function UpdateStudioInstructions({
                         ? STUDIO_LOCAL_FALLBACK_WINDOWS_CMD
                         : STUDIO_LOCAL_FALLBACK_UNIX_CMD
                     }
-                    copyLabel="local installer command"
+                    copyLabel={t("settings.about.update.localInstallerCommand")}
                   />
                 </motion.div>
               </AnimatePresence>
@@ -242,12 +254,10 @@ export function UpdateStudioInstructions({
           {packagedSourceInstall ? (
             <>
               <p className="text-xs text-muted-foreground leading-relaxed">
-                This looks like a source or VCS package install. Reinstall from
-                the original local path or Git URL you used.
+                {t("settings.about.update.sourceInstallDetected")}
               </p>
               <p className="text-xs text-muted-foreground leading-relaxed">
-                If you still have the Unsloth repo checkout, run the local
-                installer from that checkout:
+                {t("settings.about.update.repoCheckoutFallback")}
               </p>
               <AnimatePresence mode="wait" initial={false}>
                 <motion.div
@@ -263,39 +273,37 @@ export function UpdateStudioInstructions({
                         ? STUDIO_LOCAL_FALLBACK_WINDOWS_CMD
                         : STUDIO_LOCAL_FALLBACK_UNIX_CMD
                     }
-                    copyLabel="local installer command"
+                    copyLabel={t("settings.about.update.localInstallerCommand")}
                   />
                 </motion.div>
               </AnimatePresence>
             </>
           ) : null}
           <p className="text-xs text-muted-foreground leading-relaxed">
-            Restart Studio after updating for changes to take effect.
+            {t("settings.about.update.restartAfterUpdate")}
           </p>
         </>
       ) : unknownInstallSource ? (
         <>
           <p className="text-xs text-muted-foreground leading-relaxed">
-            Studio could not detect how it was installed. Check how you
-            installed Studio first, then choose the matching update path.
+            {t("settings.about.update.unknownInstall")}
           </p>
           <p className="text-xs text-muted-foreground leading-relaxed">
-            For curl or PyPI installs, run:
+            {t("settings.about.update.curlOrPypi")}
           </p>
           <CopyableCommand
             command={STUDIO_UPDATE_CMD}
-            copyLabel="update command"
+            copyLabel={t("settings.about.update.updateCommand")}
           />
           <p className="text-xs text-muted-foreground leading-relaxed">
-            For local checkout installs, update from that checkout instead and
-            use the local update command:
+            {t("settings.about.update.localCheckout")}
           </p>
           <CopyableCommand
             command={STUDIO_LOCAL_UPDATE_CMD}
-            copyLabel="local update command"
+            copyLabel={t("settings.about.update.localUpdateCommand")}
           />
           <p className="text-xs text-muted-foreground leading-relaxed">
-            Restart Studio after updating for changes to take effect.
+            {t("settings.about.update.restartAfterUpdate")}
           </p>
         </>
       ) : (
@@ -309,15 +317,15 @@ export function UpdateStudioInstructions({
               transition={fadeTransition}
               className="text-xs text-muted-foreground leading-relaxed"
             >
-              {getStudioUpdateInstructionLine(shell)}
+              {getStudioUpdateInstructionLine(shell, t)}
             </motion.p>
           </AnimatePresence>
           <CopyableCommand
             command={STUDIO_UPDATE_CMD}
-            copyLabel="update command"
+            copyLabel={t("settings.about.update.updateCommand")}
           />
           <p className="text-xs text-muted-foreground leading-relaxed">
-            If that fails or unsloth studio update is unavailable, run:
+            {t("settings.about.update.fallbackInstruction")}
           </p>
           <AnimatePresence mode="wait" initial={false}>
             <motion.div
@@ -333,12 +341,12 @@ export function UpdateStudioInstructions({
                     ? STUDIO_UPDATE_FALLBACK_WINDOWS_CMD
                     : STUDIO_UPDATE_FALLBACK_UNIX_CMD
                 }
-                copyLabel="fallback command"
+                copyLabel={t("settings.about.update.fallbackCommand")}
               />
             </motion.div>
           </AnimatePresence>
           <p className="text-xs text-muted-foreground leading-relaxed">
-            Restart Studio after updating for changes to take effect.
+            {t("settings.about.update.restartAfterUpdate")}
           </p>
         </>
       )}
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 0e68237857..96437b4840 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -3,6 +3,7 @@
 
 import { cn } from "@/lib/utils";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
+import { useT } from "@/i18n";
 import {
   ArrowUpRight01Icon,
   Copy01Icon,
@@ -78,6 +79,7 @@ for chunk in response:
 }
 
 export function UsageExamples() {
+  const t = useT();
   const [lang, setLang] = useState<Lang>("curl");
   const [copied, setCopied] = useState(false);
   const snippets = useMemo(
@@ -97,17 +99,19 @@ export function UsageExamples() {
 
   return (
     <section className="flex min-w-0 max-w-full flex-col">
-      <h2 className="mb-2 text-sm font-semibold text-foreground">Usage examples</h2>
+      <h2 className="mb-2 text-sm font-semibold text-foreground">
+        {t("settings.apiKeys.usageExamples")}
+      </h2>
       <div className="min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-muted/20">
         <div className="flex min-w-0 items-center justify-between gap-2 border-b border-border px-2 py-1.5">
           <div className="flex min-w-0 items-center gap-0.5">
-            {TABS.map((t) => {
-              const active = lang === t.id;
+            {TABS.map((tab) => {
+              const active = lang === tab.id;
               return (
                 <button
-                  key={t.id}
+                  key={tab.id}
                   type="button"
-                  onClick={() => setLang(t.id)}
+                  onClick={() => setLang(tab.id)}
                   aria-pressed={active}
                   className={cn(
                     "rounded px-2 py-1 text-[11px] font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
@@ -116,7 +120,9 @@ export function UsageExamples() {
                       : "text-muted-foreground hover:text-foreground",
                   )}
                 >
-                  {t.label}
+                  {tab.id === "tools"
+                    ? t("settings.apiKeys.usageTools")
+                    : tab.label}
                 </button>
               );
             })}
@@ -125,20 +131,20 @@ export function UsageExamples() {
             type="button"
             onClick={handleCopy}
             className="flex items-center gap-1 rounded px-1.5 py-1 text-[11px] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-            aria-label="Copy snippet"
+            aria-label={t("settings.apiKeys.copySnippet")}
           >
             <HugeiconsIcon
               icon={copied ? Tick02Icon : Copy01Icon}
               className={cn("size-3.5", copied && "text-emerald-600")}
             />
-            {copied ? "Copied" : "Copy"}
+            {copied ? t("settings.apiKeys.copied") : t("settings.apiKeys.copy")}
           </button>
         </div>
         <pre className="max-w-full overflow-x-auto whitespace-pre-wrap break-words p-3 font-mono text-[11px] leading-relaxed text-foreground">
           {snippets[lang]}
         </pre>
         <div className="flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-border px-3 py-2 text-[11px] text-muted-foreground">
-          <span>Setup docs:</span>
+          <span>{t("settings.apiKeys.setupDocs")}</span>
           {DOC_LINKS.map((link) => (
             <a
               key={link.href}
diff --git a/studio/frontend/src/features/settings/settings-dialog.tsx b/studio/frontend/src/features/settings/settings-dialog.tsx
index 3b95cb2355..b6f2463b68 100644
--- a/studio/frontend/src/features/settings/settings-dialog.tsx
+++ b/studio/frontend/src/features/settings/settings-dialog.tsx
@@ -7,6 +7,7 @@ import {
   DialogDescription,
   DialogTitle,
 } from "@/components/ui/dialog";
+import { useT, type TranslationKey } from "@/i18n";
 import { cn } from "@/lib/utils";
 import {
   Cancel01Icon,
@@ -35,19 +36,33 @@ import { ProfileTab } from "./tabs/profile-tab";
 
 interface TabDef {
   id: SettingsTab;
-  label: string;
+  labelKey: TranslationKey;
   icon: typeof Settings02Icon;
-  badge?: string;
+  badgeKey?: TranslationKey;
 }
 
 const TABS: TabDef[] = [
-  { id: "general", label: "General", icon: Settings02Icon },
-  { id: "profile", label: "Profile", icon: UserIcon },
-  { id: "appearance", label: "Appearance", icon: PaintBrush02Icon },
-  { id: "chat", label: "Chat", icon: Message01Icon },
-  { id: "connections", label: "Connections", icon: CloudIcon, badge: "New" },
-  { id: "api-keys", label: "API", icon: Globe02Icon, badge: "New" },
-  { id: "about", label: "Help", icon: HelpCircleIcon },
+  { id: "general", labelKey: "settings.tabs.general", icon: Settings02Icon },
+  { id: "profile", labelKey: "settings.tabs.profile", icon: UserIcon },
+  {
+    id: "appearance",
+    labelKey: "settings.tabs.appearance",
+    icon: PaintBrush02Icon,
+  },
+  { id: "chat", labelKey: "settings.tabs.chat", icon: Message01Icon },
+  {
+    id: "connections",
+    labelKey: "settings.tabs.connections",
+    icon: CloudIcon,
+    badgeKey: "common.new",
+  },
+  {
+    id: "api-keys",
+    labelKey: "settings.tabs.apiKeys",
+    icon: Globe02Icon,
+    badgeKey: "common.new",
+  },
+  { id: "about", labelKey: "settings.tabs.about", icon: HelpCircleIcon },
 ];
 
 function renderTab(tab: SettingsTab) {
@@ -70,6 +85,7 @@ function renderTab(tab: SettingsTab) {
 }
 
 export function SettingsDialog() {
+  const t = useT();
   const open = useSettingsDialogStore((s) => s.open);
   const activeTab = useSettingsDialogStore((s) => s.activeTab);
   const setActiveTab = useSettingsDialogStore((s) => s.setActiveTab);
@@ -117,9 +133,9 @@ export function SettingsDialog() {
           "max-sm:h-dvh max-sm:w-dvw max-sm:!max-w-none max-sm:rounded-none",
         )}
       >
-        <DialogTitle className="sr-only">Settings</DialogTitle>
+        <DialogTitle className="sr-only">{t("settings.dialog.title")}</DialogTitle>
         <DialogDescription className="sr-only">
-          Manage your Unsloth Studio preferences.
+          {t("settings.dialog.description")}
         </DialogDescription>
         <div className="flex h-full min-h-0 max-sm:flex-col">
           <aside className="font-heading flex w-[216px] shrink-0 flex-col border-r border-border bg-muted/20 p-2 max-sm:w-full max-sm:border-r-0 max-sm:border-b">
@@ -165,11 +181,11 @@ export function SettingsDialog() {
                       className="relative z-10 size-icon"
                     />
                     <span className="relative z-10 min-w-0 truncate">
-                      {tab.label}
+                      {t(tab.labelKey)}
                     </span>
-                    {tab.badge ? (
+                    {tab.badgeKey ? (
                       <span className="relative z-10 ml-auto rounded-[6px] border border-emerald-500/25 bg-emerald-500/10 px-1.5 py-0.5 text-[10px] leading-none font-semibold text-emerald-700 dark:text-emerald-300">
-                        {tab.badge}
+                        {t(tab.badgeKey)}
                       </span>
                     ) : null}
                   </button>
@@ -183,7 +199,7 @@ export function SettingsDialog() {
               type="button"
               onClick={closeDialog}
               className="absolute top-3 right-3 z-10 flex size-7 items-center justify-center rounded-[8px] text-[#383835] dark:text-[#c7c7c4] transition-colors hover:bg-[#ececec] dark:hover:bg-[#2d2f33] hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-              aria-label="Close settings"
+              aria-label={t("settings.dialog.closeAriaLabel")}
             >
               <HugeiconsIcon icon={Cancel01Icon} className="size-4" />
             </button>
diff --git a/studio/frontend/src/features/settings/tabs/about-tab.tsx b/studio/frontend/src/features/settings/tabs/about-tab.tsx
index 97f1a0b1d7..e73ad802de 100644
--- a/studio/frontend/src/features/settings/tabs/about-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/about-tab.tsx
@@ -6,6 +6,7 @@ import { Button } from "@/components/ui/button";
 import { usePlatformStore } from "@/config/env";
 import { getAuthToken } from "@/features/auth";
 import { removeTrainingUnloadGuard } from "@/features/training";
+import { useT } from "@/i18n";
 import { apiUrl, isTauri } from "@/lib/api-base";
 import {
   ArrowUpRight01Icon,
@@ -94,6 +95,7 @@ async function fetchInstallSource(): Promise<UpdateInstallSource> {
 }
 
 export function AboutTab() {
+  const t = useT();
   const deviceType = usePlatformStore((s) => s.deviceType);
   const defaultShell = deviceType === "windows" ? "windows" : "unix";
   const [shutdownOpen, setShutdownOpen] = useState(false);
@@ -132,26 +134,28 @@ export function AboutTab() {
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">Help</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.about.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          Documentation, release notes, feedback, and Studio build info.
+          {t("settings.about.description")}
         </p>
       </header>
 
       <SettingsSection title="Studio">
-        <SettingsRow label="Studio Version">
+        <SettingsRow label={t("settings.about.studioVersion")}>
           <code className="font-mono text-xs text-muted-foreground">
             {studioVersion}
           </code>
         </SettingsRow>
-        <SettingsRow label="Package Version">
+        <SettingsRow label={t("settings.about.packageVersion")}>
           <code className="font-mono text-xs text-muted-foreground">
             {packageVersion}
           </code>
         </SettingsRow>
       </SettingsSection>
 
-      <SettingsSection title="Updates">
+      <SettingsSection title={t("settings.about.updates")}>
         <div className="py-2">
           <UpdateStudioInstructions
             defaultShell={defaultShell}
@@ -161,8 +165,8 @@ export function AboutTab() {
         </div>
       </SettingsSection>
 
-      <SettingsSection title="Help">
-        <SettingsRow label="Documentation">
+      <SettingsSection title={t("settings.about.help")}>
+        <SettingsRow label={t("settings.about.documentation")}>
           <a
             href="https://unsloth.ai/docs"
             target="_blank"
@@ -174,7 +178,7 @@ export function AboutTab() {
             <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
           </a>
         </SettingsRow>
-        <SettingsRow label="Release notes">
+        <SettingsRow label={t("settings.about.releaseNotes")}>
           <a
             href="https://unsloth.ai/docs/new/changelog"
             target="_blank"
@@ -182,11 +186,11 @@ export function AboutTab() {
             className="inline-flex items-center gap-1 text-xs font-medium text-muted-foreground hover:text-foreground"
           >
             <HugeiconsIcon icon={NewReleasesIcon} className="size-3.5" />
-            What's new
+            {t("settings.about.whatsNew")}
             <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
           </a>
         </SettingsRow>
-        <SettingsRow label="Feedback">
+        <SettingsRow label={t("settings.about.feedback")}>
           <a
             href="https://github.com/unslothai/unsloth/issues"
             target="_blank"
@@ -197,17 +201,17 @@ export function AboutTab() {
               icon={MessageNotification01Icon}
               className="size-3.5"
             />
-            Report an issue
+            {t("settings.about.reportIssue")}
             <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
           </a>
         </SettingsRow>
       </SettingsSection>
 
-      <SettingsSection title="Danger zone">
+      <SettingsSection title={t("settings.about.dangerZone")}>
         <SettingsRow
           destructive={true}
-          label="Shut down Unsloth Studio"
-          description="Stops the Studio server process and ends your session."
+          label={t("settings.about.shutDownStudio")}
+          description={t("settings.about.shutDownStudioDescription")}
         >
           <Button
             variant="outline"
@@ -216,7 +220,7 @@ export function AboutTab() {
             className="text-destructive hover:text-destructive hover:border-destructive/60"
           >
             <HugeiconsIcon icon={Cancel01Icon} className="size-3.5 mr-1.5" />
-            Shut down
+            {t("settings.about.shutDown")}
           </Button>
         </SettingsRow>
       </SettingsSection>
diff --git a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
index 6cbd28f14d..d562b585b1 100644
--- a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
@@ -10,6 +10,7 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 import { Button } from "@/components/ui/button";
+import { translate, useT } from "@/i18n";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import { useCallback, useEffect, useState } from "react";
 import { fetchApiKeys, revokeApiKey, type ApiKey } from "../api/api-keys";
@@ -19,6 +20,7 @@ import { KeyRevealCard } from "../components/key-reveal-card";
 import { UsageExamples } from "../components/usage-examples";
 
 export function ApiKeysTab() {
+  const t = useT();
   const [keys, setKeys] = useState<ApiKey[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -26,25 +28,47 @@ export function ApiKeysTab() {
   const [revoking, setRevoking] = useState(false);
   const [revealed, setRevealed] = useState<string | null>(null);
   const reduced = useReducedMotion();
-  const t = reduced
+  const transition = reduced
     ? { duration: 0 }
     : { duration: 0.18, ease: [0.165, 0.84, 0.44, 1] as const };
 
+  // API helpers in ../api/api-keys.ts throw generic English Error messages
+  // ("Failed to load API access", etc.). Always use the translated message
+  // so zh-CN users do not see those English strings bleed through.
   const load = useCallback(async () => {
     setLoading(true);
     setError(null);
     try {
       setKeys(await fetchApiKeys());
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Couldn't load API access.");
+    } catch {
+      setError(translate("settings.apiKeys.loadError"));
     } finally {
       setLoading(false);
     }
   }, []);
 
   useEffect(() => {
-    void load();
-  }, [load]);
+    let cancelled = false;
+
+    async function loadInitialApiKeys() {
+      try {
+        const apiKeys = await fetchApiKeys();
+        if (cancelled) return;
+        setKeys(apiKeys);
+        setError(null);
+      } catch {
+        if (cancelled) return;
+        setError(translate("settings.apiKeys.loadError"));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+
+    void loadInitialApiKeys();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
 
   const confirmRevoke = async () => {
     if (!revokeTarget) return;
@@ -53,8 +77,8 @@ export function ApiKeysTab() {
       await revokeApiKey(revokeTarget.id);
       await load();
       setRevokeTarget(null);
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Couldn't revoke access token.");
+    } catch {
+      setError(translate("settings.apiKeys.revokeError"));
     } finally {
       setRevoking(false);
     }
@@ -63,16 +87,18 @@ export function ApiKeysTab() {
   return (
     <div className="flex min-w-0 max-w-full flex-col gap-6">
       <header className="flex min-w-0 flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">API</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.apiKeys.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          Access Unsloth programmatically via the OpenAI-compatible API.{" "}
+          {t("settings.apiKeys.description")}{" "}
           <a
             href="https://unsloth.ai/docs/basics/api"
             target="_blank"
             rel="noreferrer"
             className="font-medium text-foreground underline decoration-border underline-offset-2 transition-colors hover:decoration-foreground"
           >
-            Read the API docs
+            {t("settings.apiKeys.readDocs")}
           </a>
           .
         </p>
@@ -85,7 +111,7 @@ export function ApiKeysTab() {
             initial={{ opacity: 0, y: -4 }}
             animate={{ opacity: 1, y: 0 }}
             exit={{ opacity: 0, y: -4 }}
-            transition={t}
+            transition={transition}
           >
             <KeyRevealCard
               rawKey={revealed}
@@ -98,7 +124,7 @@ export function ApiKeysTab() {
             initial={{ opacity: 0, y: 4 }}
             animate={{ opacity: 1, y: 0 }}
             exit={{ opacity: 0, y: 4 }}
-            transition={t}
+            transition={transition}
           >
             <CreateKeyForm
               onCreated={(raw) => {
@@ -112,7 +138,9 @@ export function ApiKeysTab() {
       </AnimatePresence>
 
       <section className="flex min-w-0 flex-col">
-        <h2 className="mb-2 text-sm font-semibold text-foreground">Access tokens</h2>
+        <h2 className="mb-2 text-sm font-semibold text-foreground">
+          {t("settings.apiKeys.accessTokens")}
+        </h2>
         {error ? (
           <div className="rounded-md border border-destructive/20 bg-destructive/5 p-3 text-xs text-destructive">
             {error}
@@ -128,7 +156,7 @@ export function ApiKeysTab() {
           </div>
         ) : keys.length === 0 ? (
           <p className="py-6 text-center text-xs text-muted-foreground">
-            No API access yet.
+            {t("settings.apiKeys.noAccess")}
           </p>
         ) : (
           <div className="flex min-w-0 flex-col">
@@ -144,21 +172,29 @@ export function ApiKeysTab() {
       <Dialog open={revokeTarget !== null} onOpenChange={(o) => !o && setRevokeTarget(null)}>
         <DialogContent className="max-w-md">
           <DialogHeader>
-            <DialogTitle>Revoke access token “{revokeTarget?.name}”?</DialogTitle>
+            <DialogTitle>
+              {t("settings.apiKeys.revokeTitle", {
+                name: revokeTarget?.name ?? "",
+              })}
+            </DialogTitle>
             <DialogDescription>
-              Applications using this token will immediately lose access. This cannot be undone.
+              {t("settings.apiKeys.revokeDescription")}
             </DialogDescription>
           </DialogHeader>
           <DialogFooter>
             <Button variant="outline" onClick={() => setRevokeTarget(null)}>
-              Cancel
+              {t("common.cancel")}
             </Button>
             <Button
               onClick={confirmRevoke}
               disabled={revoking}
               className="bg-destructive hover:bg-destructive/90 text-destructive-foreground"
             >
-              {revoking ? "Revoking…" : `Revoke “${revokeTarget?.name}”`}
+              {revoking
+                ? t("settings.apiKeys.revoking")
+                : t("settings.apiKeys.revokeAction", {
+                    name: revokeTarget?.name ?? "",
+                  })}
             </Button>
           </DialogFooter>
         </DialogContent>
diff --git a/studio/frontend/src/features/settings/tabs/appearance-tab.tsx b/studio/frontend/src/features/settings/tabs/appearance-tab.tsx
index edcf3a9e4a..1214d86db2 100644
--- a/studio/frontend/src/features/settings/tabs/appearance-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/appearance-tab.tsx
@@ -3,34 +3,48 @@
 
 import { Switch } from "@/components/ui/switch";
 import { useSidebarPin } from "@/hooks/use-sidebar-pin";
+import { useT } from "@/i18n";
+import { LanguageSelect } from "../components/language-select";
 import { SettingsRow } from "../components/settings-row";
 import { SettingsSection } from "../components/settings-section";
 import { ThemeSegmented } from "../components/theme-segmented";
 
 export function AppearanceTab() {
+  const t = useT();
   const { pinned, setPinned } = useSidebarPin();
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">Appearance</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.appearance.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          How Unsloth Studio looks on this device.
+          {t("settings.appearance.description")}
         </p>
       </header>
 
-      <SettingsSection title="Theme">
+      <SettingsSection title={t("settings.appearance.theme.title")}>
         <SettingsRow
-          label="Color scheme"
-          description="Choose light, dark, or follow your system."
+          label={t("settings.appearance.theme.label")}
+          description={t("settings.appearance.theme.description")}
         >
           <ThemeSegmented />
         </SettingsRow>
       </SettingsSection>
 
-      <SettingsSection title="Layout">
+      <SettingsSection title={t("settings.appearance.language.title")}>
         <SettingsRow
-          label="Pin sidebar by default"
-          description="Keep the sidebar expanded instead of collapsing to icons."
+          label={t("settings.appearance.language.label")}
+          description={t("settings.appearance.language.description")}
+        >
+          <LanguageSelect />
+        </SettingsRow>
+      </SettingsSection>
+
+      <SettingsSection title={t("settings.appearance.layout.title")}>
+        <SettingsRow
+          label={t("settings.appearance.layout.compactSidebar")}
+          description={t("settings.appearance.layout.compactSidebarDescription")}
         >
           <Switch checked={pinned} onCheckedChange={setPinned} />
         </SettingsRow>
diff --git a/studio/frontend/src/features/settings/tabs/chat-tab.tsx b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
index 6c9a0762f4..997b342bea 100644
--- a/studio/frontend/src/features/settings/tabs/chat-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
@@ -16,6 +16,7 @@ import {
   countAllChats,
   downloadChatExport,
 } from "@/features/chat";
+import { useT } from "@/i18n";
 import { Delete02Icon, Download02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useState } from "react";
@@ -23,6 +24,7 @@ import { SettingsRow } from "../components/settings-row";
 import { SettingsSection } from "../components/settings-section";
 
 export function ChatTab() {
+  const t = useT();
   const [confirmOpen, setConfirmOpen] = useState(false);
   const [count, setCount] = useState<number | null>(null);
   const [exporting, setExporting] = useState(false);
@@ -53,8 +55,10 @@ export function ChatTab() {
         setConfirmOpen(false);
         toast.success(
           clearedCount === 0
-            ? "Cleared all chats"
-            : `Cleared ${clearedCount} chat${clearedCount === 1 ? "" : "s"}`,
+            ? t("settings.chat.clearedAllChats")
+            : clearedCount === 1
+              ? t("settings.chat.clearedOneChat")
+              : t("settings.chat.clearedChatCount", { count: clearedCount }),
         );
         return;
       }
@@ -66,20 +70,29 @@ export function ChatTab() {
       const remaining = await countAllChats().catch(() => fallbackRemaining);
       setCount(remaining);
       setConfirmOpen(false);
-      toast.warning("Some chats could not be cleared", {
+      toast.warning(t("settings.chat.someChatsCouldNotBeCleared"), {
         description:
           result.failedThreadIds.length > 0
-            ? `${clearedCount} chat${clearedCount === 1 ? "" : "s"} cleared; ${
-                result.failedThreadIds.length
-              } chat${result.failedThreadIds.length === 1 ? "" : "s"} remain. Please retry.`
-            : `A storage clear failed; ${remaining} chat${
-                remaining === 1 ? "" : "s"
-              } may remain. Please retry.`,
+            ? clearedCount === 1 && result.failedThreadIds.length === 1
+              ? t("settings.chat.oneChatClearedRemainOne")
+              : clearedCount === 1
+                ? t("settings.chat.oneChatClearedRemain", {
+                    remainingCount: result.failedThreadIds.length,
+                  })
+                : result.failedThreadIds.length === 1
+                  ? t("settings.chat.chatsClearedRemainOne", { clearedCount })
+                  : t("settings.chat.chatsClearedRemain", {
+                      clearedCount,
+                      remainingCount: result.failedThreadIds.length,
+                    })
+            : remaining === 1
+              ? t("settings.chat.storageClearFailedOne")
+              : t("settings.chat.storageClearFailed", { count: remaining }),
       });
     } catch (error) {
       const remaining = await countAllChats().catch(() => count);
       setCount(remaining);
-      toast.error("Failed to clear chats", {
+      toast.error(t("settings.chat.failedToClearChats"), {
         description: error instanceof Error ? error.message : undefined,
       });
     } finally {
@@ -90,16 +103,18 @@ export function ChatTab() {
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">Chat</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.chat.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          Manage your chat history stored on this device.
+          {t("settings.chat.description")}
         </p>
       </header>
 
-      <SettingsSection title="Data">
+      <SettingsSection title={t("settings.chat.data")}>
         <SettingsRow
-          label="Export chat history"
-          description="Download all chats and messages as a JSON file."
+          label={t("settings.chat.exportHistory")}
+          description={t("settings.chat.exportHistoryDescription")}
         >
           <Button
             variant="outline"
@@ -108,19 +123,23 @@ export function ChatTab() {
             disabled={exporting || count === 0}
           >
             <HugeiconsIcon icon={Download02Icon} className="size-3.5 mr-1.5" />
-            {exporting ? "Exporting…" : "Export"}
+            {exporting
+              ? t("settings.chat.exportingAction")
+              : t("settings.chat.exportAction")}
           </Button>
         </SettingsRow>
 
         <SettingsRow
           destructive
-          label="Clear all chats"
+          label={t("settings.chat.clearAllChats")}
           description={
             count === null
-              ? "Permanently delete every chat on this device."
+              ? t("settings.chat.clearAllChatsDescription")
               : count === 0
-                ? "No chats to clear."
-                : `Permanently delete all ${count} chat${count === 1 ? "" : "s"} on this device.`
+                ? t("settings.chat.noChatsToClear")
+                : count === 1
+                  ? t("settings.chat.clearOneChatDescription")
+                  : t("settings.chat.clearChatCountDescription", { count })
           }
         >
           <Button
@@ -131,7 +150,7 @@ export function ChatTab() {
             className="text-destructive hover:text-destructive hover:border-destructive/60"
           >
             <HugeiconsIcon icon={Delete02Icon} className="size-3.5 mr-1.5" />
-            Clear chats
+            {t("settings.chat.clearChatsAction")}
           </Button>
         </SettingsRow>
       </SettingsSection>
@@ -140,16 +159,17 @@ export function ChatTab() {
         <DialogContent className="max-w-md">
           <DialogHeader>
             <DialogTitle>
-              Clear {count ?? 0} chat{count === 1 ? "" : "s"}?
+              {count === 1
+                ? t("settings.chat.clearOneChatTitle")
+                : t("settings.chat.clearChatsTitle", { count: count ?? 0 })}
             </DialogTitle>
             <DialogDescription>
-              This permanently deletes every chat and message stored on this
-              device. This cannot be undone.
+              {t("settings.chat.clearChatsConfirmDescription")}
             </DialogDescription>
           </DialogHeader>
           <DialogFooter>
             <Button variant="outline" onClick={() => setConfirmOpen(false)}>
-              Cancel
+              {t("common.cancel")}
             </Button>
             <Button
               onClick={handleClear}
@@ -157,8 +177,12 @@ export function ChatTab() {
               className="bg-destructive hover:bg-destructive/90 text-destructive-foreground"
             >
               {clearing
-                ? "Clearing…"
-                : `Clear ${count ?? 0} chat${count === 1 ? "" : "s"}`}
+                ? t("settings.chat.clearingAction")
+                : count === 1
+                  ? t("settings.chat.clearOneChatAction")
+                  : t("settings.chat.clearChatCountAction", {
+                      count: count ?? 0,
+                    })}
             </Button>
           </DialogFooter>
         </DialogContent>
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index 6ce9ad63b3..601854f403 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -14,8 +14,9 @@ import { Input } from "@/components/ui/input";
 import { Switch } from "@/components/ui/switch";
 import { usePlatformStore } from "@/config/env";
 import { resetOnboardingDone } from "@/features/auth";
-import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
+import { useChatRuntimeStore } from "@/features/chat";
 import { useSettingsDialogStore } from "@/features/settings";
+import { LOCALE_STORAGE_KEY, useT } from "@/i18n";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import { useEffect, useRef, useState } from "react";
 import { Eye, EyeOff } from "lucide-react";
@@ -35,6 +36,7 @@ import { SettingsSection } from "../components/settings-section";
 const PREFS_KEYS: string[] = [
   // Appearance
   "theme",
+  LOCALE_STORAGE_KEY,
   // UI state
   "sidebar_pinned",
   "unsloth_sidebar_navigate_open",
@@ -81,6 +83,7 @@ function resetAllPrefs() {
 }
 
 export function GeneralTab() {
+  const t = useT();
   const navigate = useNavigate();
   const closeDialog = useSettingsDialogStore((s) => s.closeDialog);
   const { pathname, search } = useRouterState({
@@ -132,16 +135,18 @@ export function GeneralTab() {
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">General</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.general.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          Global preferences for Unsloth Studio.
+          {t("settings.general.description")}
         </p>
       </header>
 
-      <SettingsSection title="Account">
+      <SettingsSection title={t("settings.general.account")}>
         <SettingsRow
-          label="Hugging Face token"
-          description="Used to load gated models and push artifacts."
+          label={t("settings.general.huggingFaceToken")}
+          description={t("settings.general.huggingFaceTokenDescription")}
         >
           <div className="relative w-[260px]">
             <Input
@@ -156,7 +161,11 @@ export function GeneralTab() {
               type="button"
               onClick={() => setShowToken((s) => !s)}
               className="absolute right-1.5 top-1/2 flex size-5 -translate-y-1/2 items-center justify-center rounded text-muted-foreground transition-colors hover:text-foreground"
-              aria-label={showToken ? "Hide token" : "Show token"}
+              aria-label={
+                showToken
+                  ? t("settings.general.hideToken")
+                  : t("settings.general.showToken")
+              }
               tabIndex={-1}
             >
               {showToken ? <EyeOff className="size-3.5" /> : <Eye className="size-3.5" />}
@@ -165,20 +174,20 @@ export function GeneralTab() {
         </SettingsRow>
       </SettingsSection>
 
-      <SettingsSection title="Chat defaults">
+      <SettingsSection title={t("settings.general.chatDefaults")}>
         <SettingsRow
-          label="Auto-title new chats"
-          description="Generate a short title from the first message."
+          label={t("settings.general.autoTitleNewChats")}
+          description={t("settings.general.autoTitleNewChatsDescription")}
         >
           <Switch checked={autoTitle} onCheckedChange={setAutoTitle} />
         </SettingsRow>
       </SettingsSection>
 
       {!chatOnly && (
-        <SettingsSection title="Getting started">
+        <SettingsSection title={t("settings.general.gettingStarted")}>
           <SettingsRow
-            label="Start onboarding"
-            description="Open the setup wizard again without changing your account."
+            label={t("settings.general.startOnboarding")}
+            description={t("settings.general.startOnboardingDescription")}
           >
             <Button
               variant="outline"
@@ -189,17 +198,17 @@ export function GeneralTab() {
                 navigate({ to: "/onboarding", search: { redirectTo } });
               }}
             >
-              Start onboarding
+              {t("settings.general.startOnboardingAction")}
             </Button>
           </SettingsRow>
         </SettingsSection>
       )}
 
-      <SettingsSection title="Danger zone">
+      <SettingsSection title={t("settings.general.resetPreferences.sectionTitle")}>
         <SettingsRow
           destructive
-          label="Reset all local preferences"
-          description="Clears local-only preferences. Chats, API access, and DB-backed chat settings are not affected."
+          label={t("settings.general.resetPreferences.label")}
+          description={t("settings.general.resetPreferences.description")}
         >
           <Button
             variant="outline"
@@ -207,7 +216,7 @@ export function GeneralTab() {
             onClick={() => setConfirmOpen(true)}
             className="text-destructive hover:text-destructive hover:border-destructive/60"
           >
-            Reset preferences
+            {t("settings.general.resetPreferences.action")}
           </Button>
         </SettingsRow>
       </SettingsSection>
@@ -215,21 +224,22 @@ export function GeneralTab() {
       <Dialog open={confirmOpen} onOpenChange={setConfirmOpen}>
         <DialogContent className="max-w-md">
           <DialogHeader>
-            <DialogTitle>Reset all local preferences?</DialogTitle>
+            <DialogTitle>
+              {t("settings.general.resetPreferences.confirmTitle")}
+            </DialogTitle>
             <DialogDescription>
-              This clears local-only preferences, then reloads Studio. Chats,
-              API access, and DB-backed chat settings are not affected.
+              {t("settings.general.resetPreferences.confirmDescription")}
             </DialogDescription>
           </DialogHeader>
           <DialogFooter>
             <Button variant="outline" onClick={() => setConfirmOpen(false)}>
-              Cancel
+              {t("common.cancel")}
             </Button>
             <Button
               onClick={resetAllPrefs}
               className="bg-destructive hover:bg-destructive/90 text-destructive-foreground"
             >
-              Reset and reload
+              {t("settings.general.resetPreferences.confirmAction")}
             </Button>
           </DialogFooter>
         </DialogContent>
diff --git a/studio/frontend/src/features/settings/tabs/profile-tab.tsx b/studio/frontend/src/features/settings/tabs/profile-tab.tsx
index 2ae283b767..72668d5bf8 100644
--- a/studio/frontend/src/features/settings/tabs/profile-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/profile-tab.tsx
@@ -2,14 +2,19 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { ProfilePersonalizationPanel } from "@/features/profile";
+import { useT } from "@/i18n";
 
 export function ProfileTab() {
+  const t = useT();
+
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
-        <h1 className="text-lg font-semibold font-heading">Profile</h1>
+        <h1 className="text-lg font-semibold font-heading">
+          {t("settings.profile.title")}
+        </h1>
         <p className="text-xs text-muted-foreground">
-          Update how your profile appears in Studio.
+          {t("settings.profile.description")}
         </p>
       </header>
 
diff --git a/studio/frontend/src/features/studio/historical-training-view.tsx b/studio/frontend/src/features/studio/historical-training-view.tsx
index 3ee0aa7982..504e251bc5 100644
--- a/studio/frontend/src/features/studio/historical-training-view.tsx
+++ b/studio/frontend/src/features/studio/historical-training-view.tsx
@@ -8,12 +8,18 @@ import { parseBackendTrainingMethod } from "@/features/training/lib/training-met
 import { type ReactElement, useEffect, useState } from "react";
 import { ChartsSection } from "./sections/charts-section";
 import { ProgressSection } from "./sections/progress-section";
+import { translate, useT } from "@/i18n";
+
+type StudioT = ReturnType<typeof useT>;
 
 interface HistoricalTrainingViewProps {
   runId: string;
 }
 
-function mapToViewData(detail: TrainingRunDetailResponse): TrainingViewData {
+function mapToViewData(
+  detail: TrainingRunDetailResponse,
+  t: StudioT,
+): TrainingViewData {
   const { run, metrics } = detail;
 
   const lossHistory = metrics.loss_step_history
@@ -62,12 +68,12 @@ function mapToViewData(detail: TrainingRunDetailResponse): TrainingViewData {
     evalEnabled: evalLossHistory.length > 0,
     message:
       run.status === "completed"
-        ? "Training completed"
+        ? t("studio.history.message.completed")
         : run.status === "stopped"
-          ? "Training stopped"
+          ? t("studio.history.message.stopped")
           : run.status === "running"
-            ? "Training in progress"
-            : run.error_message ?? "Training errored",
+            ? t("studio.history.message.running")
+            : run.error_message ?? t("studio.history.message.errored"),
     error: run.status === "error" ? run.error_message : null,
     isTrainingRunning: false,
     modelName: run.display_name ?? run.model_name,
@@ -85,6 +91,7 @@ function mapToViewData(detail: TrainingRunDetailResponse): TrainingViewData {
 export function HistoricalTrainingView({
   runId,
 }: HistoricalTrainingViewProps): ReactElement {
+  const t = useT();
   const [detail, setDetail] = useState<TrainingRunDetailResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
 
@@ -99,7 +106,11 @@ export function HistoricalTrainingView({
       })
       .catch((err) => {
         if (err instanceof DOMException && err.name === "AbortError") return;
-        setError(err instanceof Error ? err.message : "Failed to load run");
+        setError(
+          err instanceof Error
+            ? err.message
+            : translate("studio.history.loadingRun"),
+        );
       });
     return () => {
       controller.abort();
@@ -120,7 +131,7 @@ export function HistoricalTrainingView({
   if (loading) {
     return (
       <div className="rounded-xl border bg-card p-8 text-sm text-muted-foreground">
-        Loading training run...
+        {t("studio.history.loadingRun")}
       </div>
     );
   }
@@ -128,12 +139,12 @@ export function HistoricalTrainingView({
   if (error || !detail) {
     return (
       <div className="rounded-xl border border-destructive/30 bg-destructive/5 p-8 text-sm text-red-500">
-        {error ?? "Run not found"}
+        {error ?? t("studio.history.runNotFound")}
       </div>
     );
   }
 
-  const viewData = mapToViewData(detail);
+  const viewData = mapToViewData(detail, t);
   const configOverride = detail.config
     ? {
         epochs: detail.config.num_epochs as number | undefined,
diff --git a/studio/frontend/src/features/studio/history-card-grid.tsx b/studio/frontend/src/features/studio/history-card-grid.tsx
index 6758b6ee9b..75ec43f20d 100644
--- a/studio/frontend/src/features/studio/history-card-grid.tsx
+++ b/studio/frontend/src/features/studio/history-card-grid.tsx
@@ -29,40 +29,46 @@ import { Delete02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { type ReactElement, useCallback, useEffect, useRef, useState } from "react";
 import { Spinner } from "@/components/ui/spinner";
+import { translate, useT } from "@/i18n";
+
+type StudioT = ReturnType<typeof useT>;
 
 const PAGE_SIZE = 12;
 const RUNNING_POLL_INTERVAL_MS = 5000;
 
 const statusBadge: Record<
   string,
-  { label: string; className: string }
+  { className: string }
 > = {
   completed: {
-    label: "Completed",
     className:
       "bg-emerald-100 text-emerald-700 dark:bg-emerald-950 dark:text-emerald-400",
   },
   stopped: {
-    label: "Stopped",
     className:
       "bg-amber-100 text-amber-700 dark:bg-amber-950 dark:text-amber-400",
   },
   error: {
-    label: "Error",
     className: "bg-red-100 text-red-700 dark:bg-red-950 dark:text-red-400",
   },
   running: {
-    label: "Running",
     className:
       "bg-blue-100 text-blue-700 dark:bg-blue-950 dark:text-blue-400",
   },
   resumed_later: {
-    label: "Continued",
     className:
       "bg-emerald-100 text-emerald-700 dark:bg-emerald-950 dark:text-emerald-400",
   },
 };
 
+function formatStatusLabel(status: string, t: StudioT): string {
+  if (status === "completed") return t("studio.history.status.completed");
+  if (status === "stopped") return t("studio.history.status.stopped");
+  if (status === "running") return t("studio.history.status.running");
+  if (status === "resumed_later") return t("studio.history.status.continued");
+  return t("studio.history.status.error");
+}
+
 function wasContinuedInVisibleRuns(
   run: TrainingRunSummary,
   runs: TrainingRunSummary[],
@@ -97,7 +103,15 @@ function catmullRomPath(points: { x: number; y: number }[]): string {
   return d.join(" ");
 }
 
-function Sparkline({ values, id }: { values: number[]; id: string }): ReactElement | null {
+function Sparkline({
+  values,
+  id,
+  ariaLabel,
+}: {
+  values: number[];
+  id: string;
+  ariaLabel: string;
+}): ReactElement | null {
   if (!values || values.length < 2) return null;
   let min = values[0]!;
   let max = values[0]!;
@@ -123,7 +137,7 @@ function Sparkline({ values, id }: { values: number[]; id: string }): ReactEleme
   const fillPath = `${linePath} L${last.x.toFixed(1)},${h} L${first.x.toFixed(1)},${h} Z`;
 
   return (
-    <svg viewBox={`0 0 ${w} ${h}`} className="h-8 w-full" preserveAspectRatio="none" role="img" aria-label="Loss trend sparkline">
+    <svg viewBox={`0 0 ${w} ${h}`} className="h-8 w-full" preserveAspectRatio="none" role="img" aria-label={ariaLabel}>
       <defs>
         <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
           <stop offset="0%" stopColor="currentColor" stopOpacity="0.12" />
@@ -148,15 +162,15 @@ function Sparkline({ values, id }: { values: number[]; id: string }): ReactEleme
   );
 }
 
-function formatRelativeTime(isoDate: string): string {
+function formatRelativeTime(isoDate: string, t: StudioT): string {
   const diff = Date.now() - new Date(isoDate).getTime();
   const mins = Math.floor(diff / 60000);
-  if (mins < 1) return "just now";
-  if (mins < 60) return `${mins}m ago`;
+  if (mins < 1) return t("studio.history.relativeJustNow");
+  if (mins < 60) return t("studio.history.relativeMinutesAgo", { count: mins });
   const hrs = Math.floor(mins / 60);
-  if (hrs < 24) return `${hrs}h ago`;
+  if (hrs < 24) return t("studio.history.relativeHoursAgo", { count: hrs });
   const days = Math.floor(hrs / 24);
-  return `${days}d ago`;
+  return t("studio.history.relativeDaysAgo", { count: days });
 }
 
 
@@ -169,6 +183,7 @@ export function HistoryCardGrid({
   onSelectRun,
   onResumeStarted,
 }: HistoryCardGridProps): ReactElement {
+  const t = useT();
   const [runs, setRuns] = useState<TrainingRunSummary[]>([]);
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(true);
@@ -209,7 +224,7 @@ export function HistoryCardGrid({
     } catch (err) {
       if (err instanceof DOMException && err.name === "AbortError") return;
       if (fetchIdRef.current !== id) return;
-      if (!append) setError("Failed to load training runs");
+      if (!append) setError(translate("studio.history.loadError"));
     } finally {
       if (fetchIdRef.current === id) {
         setLoading(false);
@@ -286,7 +301,7 @@ export function HistoryCardGrid({
         // Refresh failed — card is already removed, no stale display
       });
     } catch {
-      setDeleteError("Failed to delete training run. Please try again.");
+      setDeleteError(translate("studio.history.deleteError"));
     }
     setDeleteTarget(null);
   };
@@ -305,10 +320,13 @@ export function HistoryCardGrid({
 
   if (!loading && error && runs.length === 0) {
     return (
-      <div className="flex flex-col items-center gap-2 py-16 text-center">
+      <div
+        className="flex flex-col items-center gap-2 py-16 text-center"
+        aria-label={t("studio.history.title")}
+      >
         <p className="text-sm text-destructive">{error}</p>
         <Button variant="outline" size="sm" onClick={() => void fetchRuns(0)}>
-          Retry
+          {t("studio.history.retry")}
         </Button>
       </div>
     );
@@ -316,17 +334,19 @@ export function HistoryCardGrid({
 
   if (!loading && runs.length === 0) {
     return (
-      <div className="flex flex-col items-center gap-2 py-16 text-center">
+      <div
+        className="flex flex-col items-center gap-2 py-16 text-center"
+        aria-label={t("studio.history.title")}
+      >
         <p className="text-sm text-muted-foreground">
-          No training runs yet. Start your first training run in the Configure
-          tab.
+          {t("studio.history.emptyDescription")}
         </p>
       </div>
     );
   }
 
   return (
-    <>
+    <div className="contents" aria-label={t("studio.history.title")}>
       {deleteError && (
         <div className="mb-4 rounded-lg border border-destructive/50 bg-destructive/10 px-4 py-2 text-sm text-destructive">
           {deleteError}
@@ -370,10 +390,10 @@ export function HistoryCardGrid({
                   )}
                 >
                   {isRunning && <Spinner className="size-2.5" />}
-                  {badge.label}
+                  {formatStatusLabel(wasContinued ? "resumed_later" : run.status, t)}
                 </span>
                 <span className="text-[10px] text-muted-foreground">
-                  {formatRelativeTime(run.started_at)}
+                  {formatRelativeTime(run.started_at, t)}
                 </span>
               </div>
               {canResume && (
@@ -388,7 +408,7 @@ export function HistoryCardGrid({
                     void handleResume(run.id);
                   }}
                 >
-                  {isResuming ? "Resuming..." : "Resume training"}
+                  {isResuming ? t("studio.history.resuming") : t("studio.history.resumeTraining")}
                 </Button>
               )}
               <div className="min-w-0">
@@ -415,16 +435,20 @@ export function HistoryCardGrid({
               </div>
               {run.loss_sparkline && run.loss_sparkline.length >= 2 && (
                 <div className={cn(canResume && "h-7 overflow-hidden")}>
-                  <Sparkline values={run.loss_sparkline} id={run.id} />
+                  <Sparkline
+                    values={run.loss_sparkline}
+                    id={run.id}
+                    ariaLabel={t("studio.history.lossTrendSparkline")}
+                  />
                 </div>
               )}
               <div className="flex flex-wrap gap-x-4 gap-y-1 text-[11px] text-muted-foreground">
                 <span>
-                  Loss:{" "}
+                  {t("studio.history.loss")}:{" "}
                   {run.final_loss != null ? run.final_loss.toFixed(4) : "--"}
                 </span>
                 <span>
-                  Steps: {run.final_step ?? 0}/{run.total_steps ?? "--"}
+                  {t("studio.history.steps")}: {run.final_step ?? 0}/{run.total_steps ?? "--"}
                 </span>
                 <span>{formatDuration(run.duration_seconds)}</span>
               </div>
@@ -432,7 +456,7 @@ export function HistoryCardGrid({
                 <button
                   type="button"
                   className="absolute right-3 top-3 rounded-md p-1 text-muted-foreground/50 opacity-0 transition-opacity hover:bg-destructive/10 hover:text-destructive group-hover:opacity-100 focus-visible:opacity-100"
-                  aria-label="Delete run"
+                  aria-label={t("studio.history.deleteRun")}
                   onClick={(e) => {
                     e.stopPropagation();
                     setDeleteTarget(run.id);
@@ -453,7 +477,7 @@ export function HistoryCardGrid({
             onClick={() => void fetchRuns(runs.length, true)}
             disabled={loading}
           >
-            {loading ? "Loading..." : "Load more"}
+            {loading ? t("studio.history.loading") : t("studio.history.loadMore")}
           </Button>
         </div>
       )}
@@ -475,23 +499,22 @@ export function HistoryCardGrid({
       >
         <AlertDialogContent>
           <AlertDialogHeader>
-            <AlertDialogTitle>Delete training run?</AlertDialogTitle>
+            <AlertDialogTitle>{t("studio.history.deleteTitle")}</AlertDialogTitle>
             <AlertDialogDescription>
-              This will permanently delete this training run and all its metrics.
-              This action cannot be undone.
+              {t("studio.history.deleteDescription")}
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
-            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogCancel>{t("common.cancel")}</AlertDialogCancel>
             <AlertDialogAction
               variant="destructive"
               onClick={() => void handleDelete()}
             >
-              Delete
+              {t("common.delete")}
             </AlertDialogAction>
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
-    </>
+    </div>
   );
 }
diff --git a/studio/frontend/src/features/studio/sections/charts/chart-settings-sheet.tsx b/studio/frontend/src/features/studio/sections/charts/chart-settings-sheet.tsx
index 3c3445ea6a..baa66e8b83 100644
--- a/studio/frontend/src/features/studio/sections/charts/chart-settings-sheet.tsx
+++ b/studio/frontend/src/features/studio/sections/charts/chart-settings-sheet.tsx
@@ -14,6 +14,7 @@ import {
 } from "@/components/ui/sheet";
 import { Slider } from "@/components/ui/slider";
 import { Switch } from "@/components/ui/switch";
+import { useT } from "@/i18n";
 import { Settings02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { type ReactElement, useState } from "react";
@@ -82,25 +83,29 @@ function ScaleSection({
   outlierMode: OutlierMode;
   setOutlierMode: (value: OutlierMode) => void;
 }): ReactElement {
+  const t = useT();
+
   return (
     <div className="space-y-3">
       <div>
         <p className="text-sm font-medium">{title}</p>
-        <p className="text-xs text-muted-foreground">Scale and cleanup</p>
+        <p className="text-xs text-muted-foreground">
+          {t("studio.charts.scaleAndCleanup")}
+        </p>
       </div>
       <ChoiceButtons
         options={[
-          { label: "Linear", value: "linear" },
-          { label: "Log", value: "log" },
+          { label: t("studio.charts.linear"), value: "linear" },
+          { label: t("studio.charts.log"), value: "log" },
         ]}
         value={scale}
         onChange={setScale}
       />
       <ChoiceButtons
         options={[
-          { label: "No clip", value: "none" },
-          { label: "Clip p99", value: "p99" },
-          { label: "Clip p95", value: "p95" },
+          { label: t("studio.charts.noClip"), value: "none" },
+          { label: t("studio.charts.clipP99"), value: "p99" },
+          { label: t("studio.charts.clipP95"), value: "p95" },
         ]}
         value={outlierMode}
         onChange={setOutlierMode}
@@ -110,6 +115,7 @@ function ScaleSection({
 }
 
 export function ChartSettingsSheet(): ReactElement {
+  const t = useT();
   const [open, setOpen] = useState(false);
   const {
     availableSteps,
@@ -181,7 +187,7 @@ export function ChartSettingsSheet(): ReactElement {
         size="icon-sm"
         className="rounded-full text-muted-foreground hover:bg-muted hover:text-foreground"
         onClick={() => setOpen(true)}
-        aria-label="Open chart settings"
+        aria-label={t("studio.charts.openSettings")}
       >
         <HugeiconsIcon icon={Settings02Icon} className="size-4" />
       </Button>
@@ -191,24 +197,26 @@ export function ChartSettingsSheet(): ReactElement {
           overlayClassName="bg-transparent backdrop-blur-0"
         >
           <SheetHeader className="pb-4">
-            <SheetTitle>Chart Settings</SheetTitle>
+            <SheetTitle>{t("studio.charts.settings")}</SheetTitle>
             <SheetDescription>
-              Tune chart presentation while training keeps running.
+              {t("studio.charts.settingsDescription")}
             </SheetDescription>
           </SheetHeader>
           <div className="flex-1 space-y-6 overflow-y-auto px-6 pb-6">
             <div className="space-y-3">
               <div>
-                <p className="text-sm font-medium">View window</p>
+                <p className="text-sm font-medium">
+                  {t("studio.charts.viewWindow")}
+                </p>
                 <p className="text-xs text-muted-foreground">
-                  Show latest steps only or the full history.
+                  {t("studio.charts.viewWindowDescription")}
                 </p>
               </div>
               <div className="space-y-2">
                 <div className="flex items-center justify-between text-xs text-muted-foreground">
-                  <span>Window</span>
+                  <span>{t("studio.charts.window")}</span>
                   <span className="tabular-nums">
-                    {showingAll ? "All" : effectiveWindowSize}
+                    {showingAll ? t("studio.charts.all") : effectiveWindowSize}
                   </span>
                 </div>
                 <Slider
@@ -224,14 +232,16 @@ export function ChartSettingsSheet(): ReactElement {
             <Separator />
             <div className="space-y-4">
               <div>
-                <p className="text-sm font-medium">Training loss</p>
+                <p className="text-sm font-medium">
+                  {t("studio.charts.trainingLoss")}
+                </p>
                 <p className="text-xs text-muted-foreground">
-                  Control overlays and EMA smoothing.
+                  {t("studio.charts.trainingLossDescription")}
                 </p>
               </div>
               <div className="space-y-2">
                 <div className="flex items-center justify-between text-xs text-muted-foreground">
-                  <span>Smoothing</span>
+                  <span>{t("studio.charts.smoothing")}</span>
                   <span className="tabular-nums">{smoothing.toFixed(2)}</span>
                 </div>
                 <Slider
@@ -242,17 +252,17 @@ export function ChartSettingsSheet(): ReactElement {
                   step={0.01}
                 />
                 <p className="text-[11px] text-muted-foreground">
-                  Move right for more smoothing. `0` = raw.
+                  {t("studio.charts.smoothingDescription")}
                 </p>
               </div>
               <SettingRow
-                label="Show raw loss"
+                label={t("studio.charts.showRawLoss")}
                 control={
                   <Switch checked={showRaw} onCheckedChange={setShowRaw} />
                 }
               />
               <SettingRow
-                label="Show smoothed loss"
+                label={t("studio.charts.showSmoothedLoss")}
                 control={
                   <Switch
                     checked={showSmoothed}
@@ -261,7 +271,7 @@ export function ChartSettingsSheet(): ReactElement {
                 }
               />
               <SettingRow
-                label="Show average line"
+                label={t("studio.charts.showAverageLine")}
                 control={
                   <Switch
                     checked={showAvgLine}
@@ -272,7 +282,7 @@ export function ChartSettingsSheet(): ReactElement {
             </div>
             <Separator />
             <ScaleSection
-              title="Loss axis"
+              title={t("studio.charts.lossAxis")}
               scale={lossScale}
               setScale={setLossScale}
               outlierMode={lossOutlierMode}
@@ -280,7 +290,7 @@ export function ChartSettingsSheet(): ReactElement {
             />
             <Separator />
             <ScaleSection
-              title="Gradient norm axis"
+              title={t("studio.charts.gradientNormAxis")}
               scale={gradScale}
               setScale={setGradScale}
               outlierMode={gradOutlierMode}
@@ -288,7 +298,7 @@ export function ChartSettingsSheet(): ReactElement {
             />
             <Separator />
             <ScaleSection
-              title="Learning rate axis"
+              title={t("studio.charts.learningRateAxis")}
               scale={lrScale}
               setScale={setLrScale}
               outlierMode={lrOutlierMode}
@@ -302,10 +312,10 @@ export function ChartSettingsSheet(): ReactElement {
               size="sm"
               onClick={resetPreferences}
             >
-              Reset defaults
+              {t("studio.charts.resetDefaults")}
             </Button>
             <Button type="button" size="sm" onClick={() => setOpen(false)}>
-              Done
+              {t("common.done")}
             </Button>
           </SheetFooter>
         </SheetContent>
diff --git a/studio/frontend/src/features/studio/sections/charts/eval-loss-chart-card.tsx b/studio/frontend/src/features/studio/sections/charts/eval-loss-chart-card.tsx
index 62dc963587..b5eeac34f3 100644
--- a/studio/frontend/src/features/studio/sections/charts/eval-loss-chart-card.tsx
+++ b/studio/frontend/src/features/studio/sections/charts/eval-loss-chart-card.tsx
@@ -10,6 +10,7 @@ import {
   ChartTooltipContent,
 } from "@/components/ui/chart";
 import type { ChartConfig } from "@/components/ui/chart";
+import { useT } from "@/i18n";
 import { ChartAverageIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import type { ReactElement } from "react";
@@ -24,10 +25,6 @@ import {
   placeholderEvalData,
 } from "./utils";
 
-const evalLossConfig = {
-  loss: { label: "Eval Loss", color: "#ef4444" },
-} satisfies ChartConfig;
-
 export function EvalLossChartCard({
   data,
   domain,
@@ -41,11 +38,16 @@ export function EvalLossChartCard({
   isTraining: boolean;
   evalEnabled: boolean;
 }): ReactElement {
+  const t = useT();
+  const evalLossConfig = {
+    loss: { label: t("studio.charts.evalLoss"), color: "#ef4444" },
+  } satisfies ChartConfig;
+
   return (
     <Card data-tour="studio-eval-loss" size="sm">
       <CardHeader>
         <CardTitle className={`text-sm${data.length > 0 ? "" : " text-muted-foreground"}`}>
-          Eval Loss
+          {t("studio.charts.evalLoss")}
         </CardTitle>
       </CardHeader>
       <CardContent>
@@ -87,11 +89,13 @@ export function EvalLossChartCard({
                 content={
                   <ChartTooltipContent
                     labelFormatter={(_value, payload) =>
-                      `Step ${payload?.[0]?.payload?.step ?? ""}`
+                      t("studio.charts.step", {
+                        step: payload?.[0]?.payload?.step ?? "",
+                      })
                     }
                     formatter={(_value, _name, item) => [
                       formatMetric(Number(item?.payload?.loss)),
-                      "Eval Loss",
+                      t("studio.charts.evalLoss"),
                     ]}
                   />
                 }
@@ -156,13 +160,13 @@ export function EvalLossChartCard({
               />
               <p className="text-sm font-medium text-muted-foreground">
                 {isTraining && evalEnabled
-                  ? "Waiting for first evaluation step…"
-                  : "Evaluation not configured"}
+                  ? t("studio.charts.waitingForFirstEvaluationStep")
+                  : t("studio.charts.evaluationNotConfigured")}
               </p>
               <p className="text-xs text-muted-foreground/60">
                 {isTraining && evalEnabled
-                  ? "Chart will appear once eval_steps is reached"
-                  : "Set eval dataset & eval_steps to track eval loss"}
+                  ? t("studio.charts.evalChartWillAppear")
+                  : t("studio.charts.setEvalDatasetAndSteps")}
               </p>
             </div>
           </div>
diff --git a/studio/frontend/src/features/studio/sections/charts/grad-norm-chart-card.tsx b/studio/frontend/src/features/studio/sections/charts/grad-norm-chart-card.tsx
index d2cc2af84f..2a1c14784c 100644
--- a/studio/frontend/src/features/studio/sections/charts/grad-norm-chart-card.tsx
+++ b/studio/frontend/src/features/studio/sections/charts/grad-norm-chart-card.tsx
@@ -10,6 +10,7 @@ import {
   ChartTooltipContent,
 } from "@/components/ui/chart";
 import type { ChartConfig } from "@/components/ui/chart";
+import { useT } from "@/i18n";
 import type { ReactElement } from "react";
 import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
 import type { ScaleMode } from "./types";
@@ -24,10 +25,6 @@ import {
   fromLog1p,
 } from "./utils";
 
-const gradNormConfig = {
-  displayGradNorm: { label: "Grad Norm", color: "#f97316" },
-} satisfies ChartConfig;
-
 interface GradNormPoint {
   step: number;
   gradNorm: number;
@@ -47,12 +44,18 @@ export function GradNormChartCard({
   xAxisTicks: number[];
   scale: ScaleMode;
 }): ReactElement {
+  const t = useT();
+  const gradNormConfig = {
+    displayGradNorm: { label: t("studio.charts.gradNorm"), color: "#f97316" },
+  } satisfies ChartConfig;
   const showPoint = data.length <= 1 ? { r: 3, strokeWidth: 0 } : false;
 
   return (
     <Card size="sm">
       <CardHeader>
-        <CardTitle className="text-sm">Gradient Norm</CardTitle>
+        <CardTitle className="text-sm">
+          {t("studio.charts.gradientNorm")}
+        </CardTitle>
       </CardHeader>
       <CardContent>
         <ChartContainer config={gradNormConfig} className={CHART_CONTAINER_CLASS}>
@@ -101,11 +104,13 @@ export function GradNormChartCard({
               content={
                 <ChartTooltipContent
                   labelFormatter={(_value, payload) =>
-                    `Step ${payload?.[0]?.payload?.step ?? ""}`
+                    t("studio.charts.step", {
+                      step: payload?.[0]?.payload?.step ?? "",
+                    })
                   }
                   formatter={(_value, _name, item) => {
                     const raw = Number(item?.payload?.gradNorm);
-                    return [formatMetric(raw), "Grad Norm"];
+                    return [formatMetric(raw), t("studio.charts.gradNorm")];
                   }}
                 />
               }
diff --git a/studio/frontend/src/features/studio/sections/charts/learning-rate-chart-card.tsx b/studio/frontend/src/features/studio/sections/charts/learning-rate-chart-card.tsx
index 992b91c761..1a7495b493 100644
--- a/studio/frontend/src/features/studio/sections/charts/learning-rate-chart-card.tsx
+++ b/studio/frontend/src/features/studio/sections/charts/learning-rate-chart-card.tsx
@@ -10,6 +10,7 @@ import {
   ChartTooltipContent,
 } from "@/components/ui/chart";
 import type { ChartConfig } from "@/components/ui/chart";
+import { useT } from "@/i18n";
 import type { ReactElement } from "react";
 import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
 import type { ScaleMode } from "./types";
@@ -22,10 +23,6 @@ import {
   fromLog1p,
 } from "./utils";
 
-const lrConfig = {
-  displayLr: { label: "LR", color: "#8b5cf6" },
-} satisfies ChartConfig;
-
 interface LearningRatePoint {
   step: number;
   lr: number;
@@ -45,12 +42,18 @@ export function LearningRateChartCard({
   xAxisTicks: number[];
   scale: ScaleMode;
 }): ReactElement {
+  const t = useT();
+  const lrConfig = {
+    displayLr: { label: t("studio.charts.lr"), color: "#8b5cf6" },
+  } satisfies ChartConfig;
   const showPoint = data.length <= 1 ? { r: 3, strokeWidth: 0 } : false;
 
   return (
     <Card size="sm">
       <CardHeader>
-        <CardTitle className="text-sm">Learning Rate</CardTitle>
+        <CardTitle className="text-sm">
+          {t("studio.charts.learningRate")}
+        </CardTitle>
       </CardHeader>
       <CardContent>
         <ChartContainer config={lrConfig} className={CHART_CONTAINER_CLASS}>
@@ -99,13 +102,15 @@ export function LearningRateChartCard({
               content={
                 <ChartTooltipContent
                   labelFormatter={(_value, payload) =>
-                    `Step ${payload?.[0]?.payload?.step ?? ""}`
+                    t("studio.charts.step", {
+                      step: payload?.[0]?.payload?.step ?? "",
+                    })
                   }
                   formatter={(_value, _name, item) => {
                     const raw = Number(item?.payload?.lr);
                     return [
                       Number.isFinite(raw) ? raw.toExponential(3) : "0e+0",
-                      "LR",
+                      t("studio.charts.lr"),
                     ];
                   }}
                 />
diff --git a/studio/frontend/src/features/studio/sections/charts/training-loss-chart-card.tsx b/studio/frontend/src/features/studio/sections/charts/training-loss-chart-card.tsx
index 8d9710723f..16113f3219 100644
--- a/studio/frontend/src/features/studio/sections/charts/training-loss-chart-card.tsx
+++ b/studio/frontend/src/features/studio/sections/charts/training-loss-chart-card.tsx
@@ -10,6 +10,7 @@ import {
   ChartTooltipContent,
 } from "@/components/ui/chart";
 import type { ChartConfig } from "@/components/ui/chart";
+import { useT } from "@/i18n";
 import type { ReactElement } from "react";
 import {
   CartesianGrid,
@@ -31,11 +32,6 @@ import {
   fromLog1p,
 } from "./utils";
 
-const lossConfig = {
-  displayLoss: { label: "Loss", color: "#3b82f6" },
-  displaySmoothed: { label: "Smoothed", color: "#f59e0b" },
-} satisfies ChartConfig;
-
 interface LossChartPoint {
   step: number;
   loss: number;
@@ -67,12 +63,17 @@ export function TrainingLossChartCard({
   showAvgLine: boolean;
   scale: ScaleMode;
 }): ReactElement {
+  const t = useT();
+  const lossConfig = {
+    displayLoss: { label: t("studio.charts.loss"), color: "#3b82f6" },
+    displaySmoothed: { label: t("studio.charts.smoothed"), color: "#f59e0b" },
+  } satisfies ChartConfig;
   const showPoint = data.length <= 1 ? { r: 3, strokeWidth: 0 } : false;
 
   return (
     <Card data-tour="studio-training-loss" size="sm">
       <CardHeader>
-        <CardTitle className="text-sm">Training Loss</CardTitle>
+        <CardTitle className="text-sm">{t("studio.charts.trainingLoss")}</CardTitle>
       </CardHeader>
       <CardContent>
         <ChartContainer config={lossConfig} className={CHART_CONTAINER_CLASS}>
@@ -121,16 +122,21 @@ export function TrainingLossChartCard({
               content={
                 <ChartTooltipContent
                   labelFormatter={(_value, payload) =>
-                    `Step ${payload?.[0]?.payload?.step ?? ""}`
+                    t("studio.charts.step", {
+                      step: payload?.[0]?.payload?.step ?? "",
+                    })
                   }
                   formatter={(_value, name, item) => {
                     if (name === "displaySmoothed") {
                       return [
                         formatMetric(Number(item?.payload?.smoothed)),
-                        "Smoothed",
+                        t("studio.charts.smoothed"),
                       ];
                     }
-                    return [formatMetric(Number(item?.payload?.loss)), "Loss"];
+                    return [
+                      formatMetric(Number(item?.payload?.loss)),
+                      t("studio.charts.loss"),
+                    ];
                   }}
                 />
               }
@@ -142,7 +148,9 @@ export function TrainingLossChartCard({
                 strokeDasharray="4 4"
                 strokeOpacity={0.5}
                 label={{
-                  value: `avg ${formatMetric(avgRaw)}`,
+                  value: t("studio.charts.averageValue", {
+                    value: formatMetric(avgRaw),
+                  }),
                   position: "insideTopRight",
                   fontSize: 10,
                   fill: "#3b82f6",
diff --git a/studio/frontend/src/features/studio/sections/dataset-section.tsx b/studio/frontend/src/features/studio/sections/dataset-section.tsx
index fafd1eadf6..f28977978c 100644
--- a/studio/frontend/src/features/studio/sections/dataset-section.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-section.tsx
@@ -70,6 +70,7 @@ import {
 import { toast } from "@/lib/toast";
 import { useShallow } from "zustand/react/shallow";
 import { DocumentUploadRedirectDialog } from "./document-upload-redirect-dialog";
+import { translate, useT } from "@/i18n";
 
 const TRAINING_UPLOAD_EXTENSIONS = [
   ".csv",
@@ -129,6 +130,7 @@ function normalizeSliceInput(value: string): string | null {
 }
 
 export function DatasetSection() {
+  const t = useT();
   const navigate = useNavigate();
   const {
     dataset,
@@ -204,7 +206,9 @@ export function DatasetSection() {
       setLocalDatasets(response.datasets ?? []);
     } catch (error) {
       setLocalError(
-        error instanceof Error ? error.message : "Failed to load local datasets.",
+        error instanceof Error
+          ? error.message
+          : translate("studio.dataset.failedToLoadLocalDatasets"),
       );
     } finally {
       setHasLoadedLocalDatasets(true);
@@ -398,8 +402,8 @@ export function DatasetSection() {
       onSuccess(uploaded.stored_path);
       toast.success(successMessage, { description: uploaded.filename });
     } catch (error) {
-      toast.error("Upload failed", {
-        description: error instanceof Error ? error.message : "Unknown error",
+      toast.error(t("studio.dataset.uploadFailed"), {
+        description: error instanceof Error ? error.message : t("studio.dataset.unknownError"),
       });
     } finally {
       setIsUploading(false);
@@ -409,8 +413,10 @@ export function DatasetSection() {
   const handleDatasetFile = async (file: File) => {
     const extension = getFileExtension(file.name);
     if (!TRAINING_UPLOAD_EXTENSION_SET.has(extension)) {
-      toast.error("Unsupported file type", {
-        description: `Upload one ${TRAINING_UPLOAD_LABEL} file.`,
+      toast.error(t("studio.dataset.unsupportedFileType"), {
+        description: t("studio.dataset.uploadOneFileType", {
+          types: TRAINING_UPLOAD_LABEL,
+        }),
       });
       return;
     }
@@ -421,7 +427,7 @@ export function DatasetSection() {
       return;
     }
 
-    await handleFileUpload(file, selectLocalDataset, "Dataset uploaded");
+    await handleFileUpload(file, selectLocalDataset, t("studio.dataset.datasetUploaded"));
   };
 
   const handleDatasetFileChange = async (event: ChangeEvent<HTMLInputElement>) => {
@@ -441,8 +447,8 @@ export function DatasetSection() {
     if (files.length === 0) return;
 
     if (files.length > 1) {
-      toast.error("Upload one file at a time", {
-        description: "Training dataset upload accepts a single file.",
+      toast.error(t("studio.dataset.uploadOneFileAtATime"), {
+        description: t("studio.dataset.uploadSingleFileDescription"),
       });
       return;
     }
@@ -467,7 +473,7 @@ export function DatasetSection() {
     event.target.value = "";
     if (!file) return;
 
-    await handleFileUpload(file, setUploadedEvalFile, "Eval dataset uploaded");
+    await handleFileUpload(file, setUploadedEvalFile, t("studio.dataset.evalDatasetUploaded"));
   };
 
   const handleOpenLearningRecipes = useCallback(() => {
@@ -480,8 +486,8 @@ export function DatasetSection() {
     <div data-tour="studio-dataset" className="min-w-0">
       <SectionCard
         icon={<HugeiconsIcon icon={Database02Icon} className="size-5" />}
-        title="Dataset"
-        description="Select or upload training data"
+        title={t("studio.dataset.title")}
+        description={t("studio.dataset.description")}
         accent="indigo"
         className={`dark:shadow-border ${
           advancedOpen || (datasetSource === "upload" && uploadedFile)
@@ -492,9 +498,9 @@ export function DatasetSection() {
         <div className="flex min-w-0 flex-col gap-4">
           <div className="flex min-w-0 flex-col gap-2">
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Choose dataset
+              {t("studio.dataset.chooseDataset")}
               <span className="rounded-full border border-border/70 bg-muted/40 px-2 py-0.5 text-[10px] font-medium text-foreground/80">
-                {datasetSource === "upload" ? "Local" : "Hugging Face"}
+                {datasetSource === "upload" ? t("studio.dataset.localTab") : "Hugging Face"}
               </span>
               <Tooltip>
                 <TooltipTrigger asChild={true}>
@@ -509,15 +515,14 @@ export function DatasetSection() {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  Use the popup tabs to switch between Hugging Face and local
-                  recipe outputs.{" "}
+                  {t("studio.dataset.chooseDatasetTooltip")}{" "}
                   <a
                     href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/datasets-guide"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-primary underline"
                   >
-                    Read more
+                    {t("studio.params.readMore")}
                   </a>
                 </TooltipContent>
               </Tooltip>
@@ -590,8 +595,8 @@ export function DatasetSection() {
                 <ComboboxInput
                   placeholder={
                     pickerTab === "huggingface"
-                      ? "Search Hugging Face datasets..."
-                      : "Search local datasets..."
+                      ? t("studio.dataset.searchHuggingFaceDatasets")
+                      : t("studio.dataset.searchLocalDatasets")
                   }
                   className="w-full min-w-0 overflow-hidden leading-5"
                   showClear={true}
@@ -612,16 +617,16 @@ export function DatasetSection() {
                     >
                       <TabsList className=" w-full">
                         <TabsTrigger value="huggingface">Hugging Face</TabsTrigger>
-                        <TabsTrigger value="local">Local</TabsTrigger>
+                        <TabsTrigger value="local">{t("studio.dataset.localTab")}</TabsTrigger>
                       </TabsList>
 
                       <TabsContent value="huggingface" className="m-0">
                         {isLoading ? (
                           <div className="flex items-center justify-center py-4 gap-2 text-xs text-muted-foreground">
-                            <Spinner className="size-4" /> Searching...
+                            <Spinner className="size-4" /> {t("studio.dataset.searching")}
                           </div>
                         ) : (
-                          <ComboboxEmpty>No datasets found</ComboboxEmpty>
+                          <ComboboxEmpty>{t("studio.dataset.noDatasetsFound")}</ComboboxEmpty>
                         )}
                         <div
                           ref={scrollRef}
@@ -660,7 +665,7 @@ export function DatasetSection() {
                       <TabsContent value="local" className="m-0">
                         {localLoading ? (
                           <div className="flex items-center justify-center py-4 gap-2 text-xs text-muted-foreground">
-                            <Spinner className="size-4" /> Loading local datasets...
+                            <Spinner className="size-4" /> {t("studio.dataset.loadingLocalDatasets")}
                           </div>
                         ) : (
                           <>
@@ -671,12 +676,12 @@ export function DatasetSection() {
                                 <div className="flex w-full flex-col items-center gap-2 text-center">
                                   <p className="text-xs text-muted-foreground">
                                     {localDatasets.length === 0
-                                      ? "No local datasets yet."
-                                      : "No local datasets match search."}
+                                      ? t("studio.dataset.noLocalDatasetsYet")
+                                      : t("studio.dataset.noLocalDatasetsMatchSearch")}
                                   </p>
                                   {localDatasets.length === 0 ? (
                                     <Button asChild={true} size="sm" variant="outline">
-                                      <a href="/data-recipes">Open Data Recipes</a>
+                                      <a href="/data-recipes">{t("studio.dataset.openDataRecipes")}</a>
                                     </Button>
                                   ) : null}
                                 </div>
@@ -724,17 +729,27 @@ export function DatasetSection() {
                   rel="noopener noreferrer"
                   className="underline"
                 >
-                  Get or update token
+                  {t("studio.dataset.getOrUpdateToken")}
                 </a>
               </p>
             )}
             {isCheckingToken && (
-              <p className="text-xs text-muted-foreground">Checking token…</p>
+              <p className="text-xs text-muted-foreground">
+                {t("studio.dataset.checkingToken")}
+              </p>
             )}
             {pickerTab !== activeSourceTab && (
               <p className="text-[11px] text-muted-foreground">
-                Browsing {pickerTab === "local" ? "Local datasets" : "Hugging Face"}.
-                Current selection stays {datasetSource === "upload" ? "Local" : "Hugging Face"}.
+                {t("studio.dataset.browsingSource", {
+                  browsing:
+                    pickerTab === "local"
+                      ? t("studio.dataset.localDatasets")
+                      : "Hugging Face",
+                  current:
+                    datasetSource === "upload"
+                      ? t("studio.dataset.localTab")
+                      : "Hugging Face",
+                })}
               </p>
             )}
           </div>
@@ -770,10 +785,10 @@ export function DatasetSection() {
               <div className="mb-3 flex items-center justify-between gap-3">
                 <div>
                   <p className="text-xs font-medium text-muted-foreground">
-                    Local dataset metadata
+                    {t("studio.dataset.localDatasetMetadata")}
                   </p>
                   <p className="text-[10px] text-muted-foreground/80">
-                    Data Recipe output.
+                    {t("studio.dataset.dataRecipeOutput")}
                   </p>
                 </div>
               </div>
@@ -781,7 +796,7 @@ export function DatasetSection() {
               <div className="flex flex-col gap-3">
                 <div className="grid grid-cols-2 gap-x-4 gap-y-2 text-xs">
                   <MetadataRow
-                    label="Rows"
+                    label={t("studio.dataset.rows")}
                     value={
                       typeof selectedLocalRows === "number"
                         ? selectedLocalRows.toLocaleString()
@@ -789,7 +804,7 @@ export function DatasetSection() {
                     }
                   />
                   <MetadataRow
-                    label="Columns"
+                    label={t("studio.dataset.columns")}
                     value={
                       selectedLocalColumns.length > 0
                         ? String(selectedLocalColumns.length)
@@ -797,7 +812,7 @@ export function DatasetSection() {
                     }
                   />
                   <MetadataRow
-                    label="Batches"
+                    label={t("studio.dataset.batches")}
                     value={
                       typeof selectedLocalMetadata?.num_completed_batches === "number" &&
                       typeof selectedLocalMetadata?.total_num_batches === "number"
@@ -806,7 +821,7 @@ export function DatasetSection() {
                     }
                   />
                   <MetadataRow
-                    label="Updated"
+                    label={t("studio.dataset.updated")}
                     value={formatUpdatedDate(selectedLocalUpdatedAt)}
                   />
                 </div>
@@ -817,7 +832,7 @@ export function DatasetSection() {
           {datasetSource === "upload" && uploadedFile && (
             <div className="rounded-lg border bg-muted/20 px-3.5 py-3">
               <p className="mb-2 text-xs font-medium text-muted-foreground">
-                Eval dataset
+                {t("studio.dataset.evalDataset")}
               </p>
               {uploadedEvalFile ? (
                 <div className="flex items-center justify-between gap-2">
@@ -850,10 +865,12 @@ export function DatasetSection() {
                     ) : (
                       <HugeiconsIcon icon={CloudUploadIcon} className="size-3.5" />
                     )}
-                    {isUploading ? "Uploading..." : "Upload eval file"}
+                    {isUploading
+                      ? t("studio.dataset.uploading")
+                      : t("studio.dataset.uploadEvalFile")}
                   </Button>
                   <p className="text-[10px] text-muted-foreground/80">
-                    Optional. If not provided, a small portion will be split from the training data.
+                    {t("studio.dataset.evalDatasetDescription")}
                   </p>
                 </div>
               )}
@@ -866,13 +883,13 @@ export function DatasetSection() {
                 icon={ArrowDown01Icon}
                 className={`size-3.5 transition-transform ${advancedOpen ? "rotate-180" : ""}`}
               />
-              Advanced
+              {t("studio.dataset.advanced")}
             </CollapsibleTrigger>
             <CollapsibleContent className="mt-3 data-[state=open]:overflow-visible">
               <div className="flex flex-col gap-4">
                 <div className="flex flex-col gap-2">
                   <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-                    Target Format
+                    {t("studio.dataset.targetFormat")}
                     <Tooltip>
                       <TooltipTrigger asChild={true}>
                         <button
@@ -886,15 +903,14 @@ export function DatasetSection() {
                         </button>
                       </TooltipTrigger>
                       <TooltipContent>
-                        Format of your training data. Auto-detect works for most
-                        datasets.{" "}
+                        {t("studio.dataset.targetFormatTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/datasets-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </TooltipContent>
                     </Tooltip>
@@ -909,18 +925,18 @@ export function DatasetSection() {
                       <SelectValue />
                     </SelectTrigger>
                     <SelectContent>
-                      <SelectItem value="auto">Auto</SelectItem>
+                      <SelectItem value="auto">{t("studio.dataset.auto")}</SelectItem>
                       <SelectItem value="alpaca">Alpaca</SelectItem>
                       <SelectItem value="chatml">ChatML</SelectItem>
                       <SelectItem value="sharegpt">ShareGPT</SelectItem>
-                      <SelectItem value="raw">Raw Text</SelectItem>
+                      <SelectItem value="raw">{t("studio.dataset.rawText")}</SelectItem>
                     </SelectContent>
                   </Select>
                 </div>
                 <div className="grid grid-cols-2 gap-3">
                   <div className="flex flex-col gap-1.5">
                     <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-                      Train Split Start
+                      {t("studio.dataset.trainSplitStart")}
                       <Tooltip>
                         <TooltipTrigger asChild={true}>
                           <button
@@ -934,9 +950,7 @@ export function DatasetSection() {
                           </button>
                         </TooltipTrigger>
                         <TooltipContent>
-                          Only train on a subset of your training split by
-                          specifying a start row index (inclusive, 0-based).
-                          Leave empty to start from the first row.
+                          {t("studio.dataset.trainSplitStartTooltip")}
                         </TooltipContent>
                       </Tooltip>
                     </span>
@@ -954,7 +968,7 @@ export function DatasetSection() {
                   </div>
                   <div className="flex flex-col gap-1.5">
                     <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-                      Train Split End
+                      {t("studio.dataset.trainSplitEnd")}
                       <Tooltip>
                         <TooltipTrigger asChild={true}>
                           <button
@@ -968,10 +982,7 @@ export function DatasetSection() {
                           </button>
                         </TooltipTrigger>
                         <TooltipContent>
-                          Last row index to include from the training split
-                          (inclusive, 0-based). For example, set Start to 0 and
-                          End to 99 to train on the first 100 rows. Leave empty
-                          to use all remaining rows.
+                          {t("studio.dataset.trainSplitEndTooltip")}
                         </TooltipContent>
                       </Tooltip>
                     </span>
@@ -980,7 +991,7 @@ export function DatasetSection() {
                       inputMode="numeric"
                       min={0}
                       step={1}
-                      placeholder="End"
+                      placeholder={t("studio.dataset.endPlaceholder")}
                       value={datasetSliceEnd ?? ""}
                       onChange={(e) =>
                         setDatasetSliceEnd(normalizeSliceInput(e.target.value))
@@ -1012,17 +1023,19 @@ export function DatasetSection() {
                     {datasetSource === "upload" ? (
                       uploadedFile ? (
                         <>
-                          Local dataset
+                          {t("studio.dataset.localDataset")}
                           {selectedLocalRows != null
-                            ? ` / ${selectedLocalRows.toLocaleString()} rows`
+                            ? t("studio.dataset.localDatasetRows", {
+                                count: selectedLocalRows.toLocaleString(),
+                              })
                             : ""}
                         </>
                       ) : (
-                        "Local dataset"
+                        t("studio.dataset.localDataset")
                       )
                     ) : (
                       <>
-                        Hugging Face Dataset
+                        {t("studio.dataset.huggingFaceDataset")}
                         {datasetSubset && ` / ${datasetSubset}`}
                         {datasetSplit && ` / ${datasetSplit}`}
                       </>
@@ -1035,7 +1048,7 @@ export function DatasetSection() {
                   className="shrink-0 text-xs"
                   onClick={() => clearSelectionForTab(activeSourceTab)}
                 >
-                  Clear
+                  {t("studio.dataset.clear")}
                 </Button>
               </div>
             ) : (
@@ -1058,7 +1071,7 @@ export function DatasetSection() {
                 />
                 <span className="pointer-events-none min-w-0">
                   <span className="block text-xs font-medium text-foreground">
-                    Drop 1 file here or click to upload
+                    {t("studio.dataset.dropFileOrClick")}
                   </span>
                   <span className="mt-0.5 block truncate text-[10px] text-muted-foreground">
                     {TRAINING_UPLOAD_LABEL}
@@ -1080,7 +1093,7 @@ export function DatasetSection() {
                 ) : (
                   <HugeiconsIcon icon={CloudUploadIcon} className="size-3.5" />
                 )}
-                {isUploading ? "Uploading..." : "Upload"}
+                {isUploading ? t("studio.dataset.uploading") : t("studio.dataset.upload")}
               </Button>
               <Button
                 variant="outline"
@@ -1090,7 +1103,7 @@ export function DatasetSection() {
                 onClick={() => openPreview()}
               >
                 <HugeiconsIcon icon={ViewIcon} className="size-3.5" />
-                View dataset
+                {t("studio.dataset.viewDataset")}
               </Button>
             </div>
           </div>
diff --git a/studio/frontend/src/features/studio/sections/model-section.tsx b/studio/frontend/src/features/studio/sections/model-section.tsx
index a3c737dae5..055437a1f5 100644
--- a/studio/frontend/src/features/studio/sections/model-section.tsx
+++ b/studio/frontend/src/features/studio/sections/model-section.tsx
@@ -62,6 +62,7 @@ import {
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useShallow } from "zustand/react/shallow";
+import { translate, useT } from "@/i18n";
 
 const METHOD_DOTS: Record<string, string> = {
   qlora: "bg-emerald-400",
@@ -85,6 +86,7 @@ function extractParamLabel(id: string): string | null {
 }
 
 export function ModelSection() {
+  const t = useT();
   const gpu = useGpuInfo();
 
   const {
@@ -157,7 +159,7 @@ export function ModelSection() {
         setLocalModelsError(
           error instanceof Error
             ? error.message
-            : "Failed to load local models",
+            : translate("studio.model.failedToLoadLocalModels"),
         );
       })
       .finally(() => {
@@ -272,11 +274,11 @@ export function ModelSection() {
     <div data-tour="studio-model" className="w-full min-w-0">
       <SectionCard
         icon={<HugeiconsIcon icon={ChipIcon} className="size-5" />}
-        title="Model"
-        description="Select base model and training method"
+        title={t("studio.model.title")}
+        description={t("studio.model.description")}
         accent="emerald"
         featured={true}
-        badge="2x Faster Training"
+        badge={t("studio.model.fasterTrainingBadge")}
         className="shadow-border ring-border"
       >
         <div className="grid min-w-0 gap-4 md:grid-cols-2 xl:grid-cols-4">
@@ -285,7 +287,7 @@ export function ModelSection() {
             className="flex min-w-0 flex-col gap-2"
           >
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Local Model
+              {t("studio.model.localModel")}
               <Tooltip>
                 <TooltipTrigger asChild={true}>
                   <button
@@ -299,7 +301,7 @@ export function ModelSection() {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  Path to a locally downloaded model or a custom HF repo.
+                  {t("studio.model.localModelTooltip")}
                 </TooltipContent>
               </Tooltip>
             </span>
@@ -321,7 +323,7 @@ export function ModelSection() {
                 <ComboboxInput
                   placeholder={
                     isLoadingLocalModels
-                      ? "Scanning local and cached models..."
+                      ? t("studio.model.scanningLocalAndCachedModels")
                       : "./models/my-model"
                   }
                   className="w-full bg-foreground text-background [&_input]:text-background [&_input]:placeholder:text-background/40 [&_svg]:text-background/50 hover:bg-foreground/90"
@@ -342,26 +344,26 @@ export function ModelSection() {
                 >
                   {isLoadingLocalModels ? (
                     <div className="flex items-center justify-center gap-2 py-4 text-xs text-muted-foreground">
-                      <Spinner className="size-4" /> Scanning...
+                      <Spinner className="size-4" /> {t("studio.model.scanning")}
                     </div>
                   ) : localModelsError ? (
                     <div className="px-3 py-2 text-xs text-red-500">
                       {localModelsError}
                     </div>
                   ) : (
-                    <ComboboxEmpty>No local models found</ComboboxEmpty>
+                    <ComboboxEmpty>{t("studio.model.noLocalModelsFound")}</ComboboxEmpty>
                   )}
                   <ComboboxList className="p-1">
                     {(id: string) => {
                       const model = localMetaById.get(id);
                       const source =
                         model?.source === "hf_cache"
-                          ? "HF cache"
+                          ? t("studio.model.hfCache")
                           : model?.source === "lmstudio"
                             ? "LM Studio"
                             : model?.source === "custom"
-                              ? "Custom Folders"
-                              : "Local dir";
+                              ? t("studio.model.customFolders")
+                              : t("studio.model.localDir");
                       return (
                         <ComboboxItem key={id} value={id} className="gap-2">
                           <Tooltip>
@@ -389,15 +391,17 @@ export function ModelSection() {
             </div>
             {isLoadingLocalModels ? (
               <p className="text-[10px] text-muted-foreground">
-                Scanning local models...
+                {t("studio.model.scanningLocalModels")}
               </p>
             ) : localModelsError ? (
               <p className="text-[10px] text-red-500">{localModelsError}</p>
             ) : (
               <p className="text-[10px] text-muted-foreground">
                 {trainableLocalModels.length > 0
-                  ? `${trainableLocalModels.length} local/cached models found`
-                  : "No local models found. Enter path manually."}
+                  ? t("studio.model.localModelsFound", {
+                      count: trainableLocalModels.length,
+                    })
+                  : t("studio.model.noLocalModelsFoundManual")}
               </p>
             )}
           </div>
@@ -407,7 +411,7 @@ export function ModelSection() {
             className="flex min-w-0 flex-col gap-2"
           >
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Hugging Face Model
+              {t("studio.model.huggingFaceModel")}
               <Tooltip>
                 <TooltipTrigger asChild={true}>
                   <button
@@ -421,14 +425,14 @@ export function ModelSection() {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  Search Hugging Face models or pick from our recommended list.{" "}
+                  {t("studio.model.huggingFaceModelTooltip")}{" "}
                   <a
                     href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/what-model-should-i-use"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-primary underline"
                   >
-                    Read more
+                    {t("studio.model.readMore")}
                   </a>
                 </TooltipContent>
               </Tooltip>
@@ -459,7 +463,7 @@ export function ModelSection() {
                 autoHighlight={true}
               >
                 <ComboboxInput
-                  placeholder="Search models..."
+                  placeholder={t("studio.model.searchModels")}
                   className="w-full leading-5"
                 >
                   <InputGroupAddon>
@@ -469,10 +473,10 @@ export function ModelSection() {
                 <ComboboxContent anchor={comboboxAnchorRef}>
                   {isLoading ? (
                     <div className="flex items-center justify-center py-4 gap-2 text-xs text-muted-foreground">
-                      <Spinner className="size-4" /> Searching…
+                      <Spinner className="size-4" /> {t("studio.model.searching")}
                     </div>
                   ) : (
-                    <ComboboxEmpty>No models found</ComboboxEmpty>
+                    <ComboboxEmpty>{t("studio.model.noModelsFound")}</ComboboxEmpty>
                   )}
                   <div
                     ref={scrollRef}
@@ -510,10 +514,18 @@ export function ModelSection() {
                                   gpu.available && (
                                     <span className="block text-[10px] mt-1">
                                       {exceeds
-                                        ? `Needs ~${vramEst}GB VRAM (GPU: ${gpu.memoryTotalGb}GB)`
+                                        ? t("studio.model.needsVram", {
+                                            vram: vramEst,
+                                            gpu: gpu.memoryTotalGb,
+                                          })
                                         : fitStatus === "tight"
-                                          ? `~${vramEst}GB VRAM (tight fit on ${gpu.memoryTotalGb}GB)`
-                                          : `~${vramEst}GB VRAM`}
+                                          ? t("studio.model.tightVram", {
+                                              vram: vramEst,
+                                              gpu: gpu.memoryTotalGb,
+                                            })
+                                          : t("studio.model.vramEstimate", {
+                                              vram: vramEst,
+                                            })}
                                     </span>
                                   )}
                               </TooltipContent>
@@ -556,7 +568,7 @@ export function ModelSection() {
             className="flex min-w-0 flex-col gap-2"
           >
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Method
+              {t("studio.model.method")}
               <Tooltip>
                 <TooltipTrigger asChild={true}>
                   <button
@@ -570,17 +582,14 @@ export function ModelSection() {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent className="max-w-xs">
-                  QLoRA uses 4-bit quantization for lowest VRAM. LoRA uses
-                  16-bit. Full updates all weights. CPT (Continued Pretraining)
-                  trains on raw text to adapt the model to a new domain without
-                  chat formatting.{" "}
+                  {t("studio.model.methodTooltip")}{" "}
                   <a
                     href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-primary underline"
                   >
-                    Read more
+                    {t("studio.model.readMore")}
                   </a>
                 </TooltipContent>
               </Tooltip>
@@ -617,7 +626,7 @@ export function ModelSection() {
                     <span
                       className={`size-2 shrink-0 rounded-full ${METHOD_DOTS.full}`}
                     />
-                    Full Fine-tune
+                    {t("studio.model.fullFineTune")}
                   </span>
                 </SelectItem>
                 <SelectItem value="cpt">
@@ -625,7 +634,7 @@ export function ModelSection() {
                     <span
                       className={`size-2 shrink-0 rounded-full ${METHOD_DOTS.cpt}`}
                     />
-                    Continued Pretraining
+                    {t("studio.model.continuedPretraining")}
                   </span>
                 </SelectItem>
               </SelectContent>
@@ -634,7 +643,7 @@ export function ModelSection() {
 
           <div className="flex min-w-0 flex-col gap-2">
             <span className="text-xs font-medium text-muted-foreground">
-              Hugging Face Token (Optional)
+              {t("studio.model.huggingFaceTokenOptional")}
             </span>
             <InputGroup>
               <InputGroupAddon>
@@ -659,12 +668,14 @@ export function ModelSection() {
                   rel="noopener noreferrer"
                   className="underline"
                 >
-                  Get or update token
+                  {t("studio.model.getOrUpdateToken")}
                 </a>
               </p>
             )}
             {isCheckingToken && (
-              <p className="text-xs text-muted-foreground">Checking token…</p>
+              <p className="text-xs text-muted-foreground">
+                {t("studio.model.checkingToken")}
+              </p>
             )}
           </div>
         </div>
diff --git a/studio/frontend/src/features/studio/sections/params-section.tsx b/studio/frontend/src/features/studio/sections/params-section.tsx
index 19b75db140..9749eba9b7 100644
--- a/studio/frontend/src/features/studio/sections/params-section.tsx
+++ b/studio/frontend/src/features/studio/sections/params-section.tsx
@@ -50,6 +50,9 @@ import {
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { type ReactElement, type ReactNode, useEffect, useRef, useState } from "react";
+import { useT } from "@/i18n";
+
+type StudioT = ReturnType<typeof useT>;
 
 function Row({
   label,
@@ -126,7 +129,46 @@ function SliderRow({
   );
 }
 
+function formatOptimizerLabel(
+  value: string,
+  fallback: string,
+  t: StudioT,
+): string {
+  switch (value) {
+    case "adamw_8bit":
+      return t("studio.params.optimizerOptions.adamw8bit");
+    case "paged_adamw_8bit":
+      return t("studio.params.optimizerOptions.pagedAdamw8bit");
+    case "adamw_bnb_8bit":
+      return t("studio.params.optimizerOptions.adamwBnb8bit");
+    case "paged_adamw_32bit":
+      return t("studio.params.optimizerOptions.pagedAdamw32bit");
+    case "adamw_torch":
+      return t("studio.params.optimizerOptions.adamwTorch");
+    case "adamw_torch_fused":
+      return t("studio.params.optimizerOptions.adamwTorchFused");
+    default:
+      return fallback;
+  }
+}
+
+function formatSchedulerLabel(
+  value: string,
+  fallback: string,
+  t: StudioT,
+): string {
+  switch (value) {
+    case "linear":
+      return t("studio.params.lrSchedulerOptions.linear");
+    case "cosine":
+      return t("studio.params.lrSchedulerOptions.cosine");
+    default:
+      return fallback;
+  }
+}
+
 export function ParamsSection(): ReactElement {
+  const t = useT();
   const store = useTrainingConfigStore();
   const platformDeviceType = usePlatformStore((s) => s.deviceType);
   const isLora = isAdapterMethod(store.trainingMethod);
@@ -171,8 +213,8 @@ export function ParamsSection(): ReactElement {
     <div data-tour="studio-params" className="min-w-0">
       <SectionCard
         icon={<HugeiconsIcon icon={Settings04Icon} className="size-5" />}
-        title="Parameters"
-        description="Configure training hyperparameters"
+        title={t("studio.params.title")}
+        description={t("studio.params.description")}
         accent="orange"
         className={`${needsExpandedHeight
           ? "min-h-studio-config-column"
@@ -187,7 +229,7 @@ export function ParamsSection(): ReactElement {
             >
               <div className="flex items-center justify-between">
                 <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-                  {useEpochs ? "Epochs" : "Max Steps"}
+                  {useEpochs ? t("studio.params.epochs") : t("studio.params.maxSteps")}
                   <Tooltip>
                     <TooltipTrigger asChild={true}>
                       <button
@@ -202,15 +244,15 @@ export function ParamsSection(): ReactElement {
                     </TooltipTrigger>
                     <TooltipContent>
                       {useEpochs
-                        ? "Number of full passes over the dataset."
-                        : "Override total optimizer steps."}{" "}
+                        ? t("studio.params.epochsTooltip")
+                        : t("studio.params.maxStepsTooltip")}{" "}
                       <a
                         href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                         target="_blank"
                         rel="noopener noreferrer"
                         className="text-primary underline"
                       >
-                        Read more
+                        {t("studio.params.readMore")}
                       </a>
                     </TooltipContent>
                   </Tooltip>
@@ -221,7 +263,7 @@ export function ParamsSection(): ReactElement {
                     onClick={toggleUseEpochs}
                     className="text-xs text-primary underline cursor-pointer"
                   >
-                    {useEpochs ? "Use Max Steps" : "Use Epochs"}
+                    {useEpochs ? t("studio.params.useMaxSteps") : t("studio.params.useEpochs")}
                   </button>
                   <input
                     type="number"
@@ -261,8 +303,8 @@ export function ParamsSection(): ReactElement {
               />
               <p className="text-[10px] text-muted-foreground">
                 {useEpochs
-                  ? "Each epoch is one full pass over your dataset."
-                  : "Limits training to a fixed number of optimizer steps."}
+                  ? t("studio.params.epochsDescription")
+                  : t("studio.params.maxStepsDescription")}
               </p>
             </div>
           </div>
@@ -270,7 +312,7 @@ export function ParamsSection(): ReactElement {
           {/* Context length */}
           <div className="flex flex-col gap-2">
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Context Length
+              {t("studio.params.contextLength")}
               <Tooltip>
                 <TooltipTrigger asChild={true}>
                   <button
@@ -284,14 +326,14 @@ export function ParamsSection(): ReactElement {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  Maximum number of tokens per training sample.{" "}
+                  {t("studio.params.contextLengthTooltip")}{" "}
                   <a
                     href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-primary underline"
                   >
-                    Read more
+                    {t("studio.params.readMore")}
                   </a>
                 </TooltipContent>
               </Tooltip>
@@ -330,7 +372,7 @@ export function ParamsSection(): ReactElement {
                   }}
                 />
                 <ComboboxContent anchor={ctxAnchorRef}>
-                  <ComboboxEmpty>Enter a custom value</ComboboxEmpty>
+                  <ComboboxEmpty>{t("studio.params.customContextLength")}</ComboboxEmpty>
                   <ComboboxList className="p-1">
                     {(id: string) => (
                       <ComboboxItem key={id} value={id} className="font-mono">
@@ -342,14 +384,14 @@ export function ParamsSection(): ReactElement {
               </Combobox>
             </div>
             <p className="text-[10px] text-muted-foreground">
-              Max sequence length for training samples
+              {t("studio.params.contextLengthDescription")}
             </p>
           </div>
 
           {/* Learning Rate */}
           <div className="flex flex-col gap-2">
             <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-              Learning Rate
+              {t("studio.params.learningRate")}
               <Tooltip>
                 <TooltipTrigger asChild={true}>
                   <button
@@ -363,15 +405,14 @@ export function ParamsSection(): ReactElement {
                   </button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  Step size for weight updates. Lower values train slower but more
-                  stably.{" "}
+                  {t("studio.params.learningRateTooltip")}{" "}
                   <a
                     href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-primary underline"
                   >
-                    Read more
+                    {t("studio.params.readMore")}
                   </a>
                 </TooltipContent>
               </Tooltip>
@@ -384,7 +425,7 @@ export function ParamsSection(): ReactElement {
               className="w-full font-mono"
             />
             <p className="text-[10px] text-muted-foreground">
-              Recommended: 2e-4 for LoRA, 5e-5 for CPT, 2e-5 for full fine-tune
+              {t("studio.params.learningRateDescription")}
             </p>
           </div>
 
@@ -392,7 +433,7 @@ export function ParamsSection(): ReactElement {
           {isCpt && (
             <div className="flex flex-col gap-2">
               <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
-                Embedding Learning Rate
+                {t("studio.params.embeddingLearningRate")}
                 <Tooltip>
                   <TooltipTrigger asChild={true}>
                     <button
@@ -406,12 +447,7 @@ export function ParamsSection(): ReactElement {
                     </button>
                   </TooltipTrigger>
                   <TooltipContent>
-                    Only used when CPT is training <code>embed_tokens</code>.
-                    Embeddings are easier to destabilize than LoRA weights, so
-                    they usually need a smaller LR. Leave blank to use
-                    <code>lr/10</code>; typical working range is 2x-10x smaller
-                    than the main LR. Increase it only if vocabulary or
-                    domain-token adaptation is too slow.
+                    {t("studio.params.embeddingLearningRateTooltip")}
                   </TooltipContent>
                 </Tooltip>
               </span>
@@ -434,8 +470,7 @@ export function ParamsSection(): ReactElement {
                 className="w-full font-mono"
               />
               <p className="text-[10px] text-muted-foreground">
-                Leave blank to use lr/10 (recommended). Typical range is
-                2x-10x smaller than the main learning rate.
+                {t("studio.params.embeddingLearningRateDescription")}
               </p>
             </div>
           )}
@@ -448,22 +483,22 @@ export function ParamsSection(): ReactElement {
                   icon={ArrowDown01Icon}
                   className={`size-3.5 transition-transform ${loraOpen ? "rotate-180" : ""}`}
                 />
-                LoRA Settings
+                {t("studio.params.loraSettings")}
               </CollapsibleTrigger>
               <CollapsibleContent className="mt-3 data-[state=open]:overflow-visible">
                 <div className="pt-1.5 flex flex-col gap-4">
                 <SliderRow
-                  label="Rank"
+                  label={t("studio.params.rank")}
                   tooltip={
                     <>
-                      Dimension of the low-rank matrices. Higher = more capacity.{" "}
+                      {t("studio.params.rankTooltip")}{" "}
                       <a
                         href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                         target="_blank"
                         rel="noopener noreferrer"
                         className="text-primary underline"
                       >
-                        Read more
+                        {t("studio.params.readMore")}
                       </a>
                     </>
                   }
@@ -474,17 +509,17 @@ export function ParamsSection(): ReactElement {
                   step={4}
                 />
                 <SliderRow
-                  label="Alpha"
+                  label={t("studio.params.alpha")}
                   tooltip={
                     <>
-                      Scaling factor for LoRA updates. Usually 2x rank.{" "}
+                      {t("studio.params.alphaTooltip")}{" "}
                       <a
                         href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                         target="_blank"
                         rel="noopener noreferrer"
                         className="text-primary underline"
                       >
-                        Read more
+                        {t("studio.params.readMore")}
                       </a>
                     </>
                   }
@@ -495,17 +530,17 @@ export function ParamsSection(): ReactElement {
                   step={4}
                 />
                 <SliderRow
-                  label="Dropout"
+                  label={t("studio.params.dropout")}
                   tooltip={
                     <>
-                      Dropout probability for LoRA layers to reduce overfitting.{" "}
+                      {t("studio.params.dropoutTooltip")}{" "}
                       <a
                         href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                         target="_blank"
                         rel="noopener noreferrer"
                         className="text-primary underline"
                       >
-                        Read more
+                        {t("studio.params.readMore")}
                       </a>
                     </>
                   }
@@ -524,25 +559,25 @@ export function ParamsSection(): ReactElement {
                       [
                         [
                           "finetuneVisionLayers",
-                          "Vision layers",
+                          t("studio.params.visionLayers"),
                           store.finetuneVisionLayers,
                           store.setFinetuneVisionLayers,
                         ],
                         [
                           "finetuneLanguageLayers",
-                          "Language layers",
+                          t("studio.params.languageLayers"),
                           store.finetuneLanguageLayers,
                           store.setFinetuneLanguageLayers,
                         ],
                         [
                           "finetuneAttentionModules",
-                          "Attention modules",
+                          t("studio.params.attentionModules"),
                           store.finetuneAttentionModules,
                           store.setFinetuneAttentionModules,
                         ],
                         [
                           "finetuneMLPModules",
-                          "MLP modules",
+                          t("studio.params.mlpModules"),
                           store.finetuneMLPModules,
                           store.setFinetuneMLPModules,
                         ],
@@ -571,7 +606,7 @@ export function ParamsSection(): ReactElement {
                 {!showVisionLora && (
                   <div className="flex flex-col gap-2 pt-1">
                     <span className="text-xs font-medium text-muted-foreground">
-                      Target Modules
+                      {t("studio.params.targetModules")}
                     </span>
                     <div className="flex flex-wrap gap-1.5">
                       {(isCpt ? CPT_TARGET_MODULES : TARGET_MODULES).map((mod) => {
@@ -606,14 +641,14 @@ export function ParamsSection(): ReactElement {
                     [
                       {
                         value: "lora",
-                        label: "Enable LoRA",
-                        desc: "Train with LoRA",
+                        label: t("studio.params.enableLora"),
+                        desc: t("studio.params.trainWithLora"),
                       },
-                      { value: "rslora", label: "RS-LoRA", desc: "Stable Rank" },
+                      { value: "rslora", label: "RS-LoRA", desc: t("studio.params.stableRank") },
                       {
                         value: "loftq",
                         label: "LoftQ",
-                        desc: "Memory Efficient",
+                        desc: t("studio.params.memoryEfficient"),
                       },
                     ] as const
                   ).map((opt) => (
@@ -645,7 +680,7 @@ export function ParamsSection(): ReactElement {
                 icon={ArrowDown01Icon}
                 className={`size-3.5 transition-transform ${hyperOpen ? "rotate-180" : ""}`}
               />
-              Training Hyperparameters
+              {t("studio.params.trainingHyperparameters")}
             </CollapsibleTrigger>
             <CollapsibleContent className="mt-3 data-[state=open]:overflow-visible">
               <Tabs defaultValue="optimization" className="w-full">
@@ -654,19 +689,19 @@ export function ParamsSection(): ReactElement {
                     value="optimization"
                     className="flex-1 !corner-squircle text-xs cursor-pointer"
                   >
-                    Optimization
+                    {t("studio.params.optimization")}
                   </TabsTrigger>
                   <TabsTrigger
                     value="schedule"
                     className="flex-1 text-xs cursor-pointer"
                   >
-                    Schedule
+                    {t("studio.params.schedule")}
                   </TabsTrigger>
                   <TabsTrigger
                     value="memory"
                     className="flex-1 text-xs cursor-pointer"
                   >
-                    Memory
+                    {t("studio.params.memory")}
                   </TabsTrigger>
                 </TabsList>
 
@@ -675,18 +710,17 @@ export function ParamsSection(): ReactElement {
                   className="mt-3 flex flex-col gap-3"
                 >
                   <Row
-                    label="Optimizer"
+                    label={t("studio.params.optimizer")}
                     tooltip={
                       <>
-                        Optimization algorithm. 8-bit variants reduce memory usage.
-                        Fused is recommended for vision models.{" "}
+                        {t("studio.params.optimizerTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -704,25 +738,24 @@ export function ParamsSection(): ReactElement {
                             key={opt.value}
                             value={opt.value}
                           >
-                            {opt.label}
+                            {formatOptimizerLabel(opt.value, opt.label, t)}
                           </SelectItem>
                         ))}
                       </SelectContent>
                     </Select>
                   </Row>
                   <Row
-                    label="LR scheduler"
+                    label={t("studio.params.lrScheduler")}
                     tooltip={
                       <>
-                        How the learning rate changes over training. Linear decays
-                        steadily; cosine decays in a curve.{" "}
+                        {t("studio.params.lrSchedulerTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -740,24 +773,24 @@ export function ParamsSection(): ReactElement {
                             key={opt.value}
                             value={opt.value}
                           >
-                            {opt.label}
+                            {formatSchedulerLabel(opt.value, opt.label, t)}
                           </SelectItem>
                         ))}
                       </SelectContent>
                     </Select>
                   </Row>
                   <SliderRow
-                    label="Batch Size"
+                    label={t("studio.params.batchSize")}
                     tooltip={
                       <>
-                        Samples processed per step. Higher uses more VRAM.{" "}
+                        {t("studio.params.batchSizeTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -768,17 +801,17 @@ export function ParamsSection(): ReactElement {
                     step={1}
                   />
                   <SliderRow
-                    label="Grad Accum"
+                    label={t("studio.params.gradAccum")}
                     tooltip={
                       <>
-                        Simulates larger batch sizes without extra VRAM.{" "}
+                        {t("studio.params.gradAccumTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -789,17 +822,17 @@ export function ParamsSection(): ReactElement {
                     step={1}
                   />
                   <Row
-                    label="Weight Decay"
+                    label={t("studio.params.weightDecay")}
                     tooltip={
                       <>
-                        L2 regularization to prevent overfitting.{" "}
+                        {t("studio.params.weightDecayTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -821,17 +854,17 @@ export function ParamsSection(): ReactElement {
                   className="mt-3 flex flex-col gap-3"
                 >
                   <SliderRow
-                    label="Warmup Steps"
+                    label={t("studio.params.warmupSteps")}
                     tooltip={
                       <>
-                        Gradually increase LR at training start for stability.{" "}
+                        {t("studio.params.warmupStepsTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -843,18 +876,17 @@ export function ParamsSection(): ReactElement {
                   />
                   {!useEpochs && (
                     <SliderRow
-                      label="Epochs"
+                      label={t("studio.params.epochs")}
                       tooltip={
                         <>
-                          Number of full passes over the dataset. Set 0 to run by
-                          max steps.{" "}
+                          {t("studio.params.scheduleEpochsTooltip")}{" "}
                           <a
                             href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                             target="_blank"
                             rel="noopener noreferrer"
                             className="text-primary underline"
                           >
-                            Read more
+                            {t("studio.params.readMore")}
                           </a>
                         </>
                       }
@@ -866,17 +898,17 @@ export function ParamsSection(): ReactElement {
                     />
                   )}
                   <Row
-                    label="Save Steps"
+                    label={t("studio.params.saveSteps")}
                     tooltip={
                       <>
-                        Save a checkpoint every N steps. 0 to disable.{" "}
+                        {t("studio.params.saveStepsTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -889,8 +921,8 @@ export function ParamsSection(): ReactElement {
                     />
                   </Row>
                   <Row
-                    label="Eval Steps"
-                    tooltip="Fraction of total training steps between evaluations (0-1). Set to 0 to disable evaluation. E.g. 0.01 = evaluate every 1% of steps."
+                    label={t("studio.params.evalSteps")}
+                    tooltip={t("studio.params.evalStepsTooltip")}
                   >
                     <Input
                       type="number"
@@ -902,7 +934,7 @@ export function ParamsSection(): ReactElement {
                       className="w-28 font-mono"
                     />
                   </Row>
-                  <Row label="Seed" tooltip="Random seed for reproducibility.">
+                  <Row label={t("studio.params.seed")} tooltip={t("studio.params.seedTooltip")}>
                     <Input
                       type="number"
                       value={store.randomSeed}
@@ -916,17 +948,17 @@ export function ParamsSection(): ReactElement {
 
                 <TabsContent value="memory" className="mt-3 flex flex-col gap-3">
                   <Row
-                    label="Grad Checkpoint"
+                    label={t("studio.params.gradCheckpoint")}
                     tooltip={
                       <>
-                        Trade compute for memory by recomputing activations.{" "}
+                        {t("studio.params.gradCheckpointTooltip")}{" "}
                         <a
                           href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
                           target="_blank"
                           rel="noopener noreferrer"
                           className="text-primary underline"
                         >
-                          Read more
+                          {t("studio.params.readMore")}
                         </a>
                       </>
                     }
@@ -941,8 +973,8 @@ export function ParamsSection(): ReactElement {
                         <SelectValue />
                       </SelectTrigger>
                       <SelectContent>
-                        <SelectItem value="none">None</SelectItem>
-                        <SelectItem value="true">Standard</SelectItem>
+                        <SelectItem value="none">{t("studio.params.none")}</SelectItem>
+                        <SelectItem value="true">{t("studio.params.standard")}</SelectItem>
                         {platformDeviceType === "mac" ? (
                           <SelectItem value="mlx">MLX</SelectItem>
                         ) : (
@@ -962,7 +994,7 @@ export function ParamsSection(): ReactElement {
                         htmlFor="packing"
                         className="text-xs cursor-pointer text-muted-foreground"
                       >
-                        Enable packing
+                        {t("studio.params.enablePacking")}
                       </label>
                     </div>
                   )}
@@ -977,7 +1009,7 @@ export function ParamsSection(): ReactElement {
                         htmlFor="trainOnCompletions"
                         className="text-xs cursor-pointer text-muted-foreground"
                       >
-                        Assistant completions only
+                        {t("studio.params.assistantCompletionsOnly")}
                       </label>
                     </div>
                   )}
diff --git a/studio/frontend/src/features/studio/sections/progress-section-lib.ts b/studio/frontend/src/features/studio/sections/progress-section-lib.ts
index d8bf87c288..6b18301f8e 100644
--- a/studio/frontend/src/features/studio/sections/progress-section-lib.ts
+++ b/studio/frontend/src/features/studio/sections/progress-section-lib.ts
@@ -3,19 +3,6 @@
 
 import type { TrainingPhase } from "@/features/training";
 
-export const phaseLabel: Record<TrainingPhase, string> = {
-  idle: "Idle",
-  downloading_model: "Downloading model",
-  downloading_dataset: "Downloading dataset",
-  loading_model: "Loading model",
-  loading_dataset: "Loading dataset",
-  configuring: "Configuring",
-  training: "Training",
-  completed: "Completed",
-  error: "Error",
-  stopped: "Stopped",
-};
-
 export const phaseColors: Record<TrainingPhase, string> = {
   idle: "bg-muted text-muted-foreground",
   downloading_model:
diff --git a/studio/frontend/src/features/studio/sections/progress-section.tsx b/studio/frontend/src/features/studio/sections/progress-section.tsx
index 443a7cdb50..f52f3bcb99 100644
--- a/studio/frontend/src/features/studio/sections/progress-section.tsx
+++ b/studio/frontend/src/features/studio/sections/progress-section.tsx
@@ -48,14 +48,27 @@ import {
   formatDuration,
   formatNumber,
   phaseColors,
-  phaseLabel,
 } from "./progress-section-lib";
+import { useT, type TranslationKey } from "@/i18n";
 
 type ConfigGroup = {
   section: string;
   rows: [string, string | number | null | undefined][];
 };
 
+const phaseLabelKeys = {
+  idle: "studio.progress.phase.idle",
+  downloading_model: "studio.progress.phase.downloadingModel",
+  downloading_dataset: "studio.progress.phase.downloadingDataset",
+  loading_model: "studio.progress.phase.loadingModel",
+  loading_dataset: "studio.progress.phase.loadingDataset",
+  configuring: "studio.progress.phase.configuring",
+  training: "studio.progress.phase.training",
+  completed: "studio.progress.phase.completed",
+  error: "studio.progress.phase.error",
+  stopped: "studio.progress.phase.stopped",
+} satisfies Record<TrainingViewData["phase"], TranslationKey>;
+
 function configRow(
   label: string,
   value: string | number | null | undefined,
@@ -86,6 +99,7 @@ export function ProgressSection({
   isHistorical = false,
   configOverride,
 }: ProgressSectionProps): ReactElement {
+  const t = useT();
   const navigate = useNavigate();
   const trainingMethodLabel = getTrainingMethodLabel(data.trainingMethod);
 
@@ -171,15 +185,15 @@ export function ProgressSection({
 
   const configItems: ConfigGroup[] = [
     {
-      section: "Hyperparams",
+      section: t("studio.progress.hyperparams"),
       rows: [
-        configRow("Epochs", cfgEpochs),
-        configRow("Batch size", cfgBatchSize),
-        configRow("Learning rate", cfgLearningRate),
-        configRow("Optimizer", optimizerLabel),
-        configRow("Max steps", cfgMaxSteps),
-        configRow("Context length", cfgContextLength),
-        configRow("Warmup steps", cfgWarmupSteps),
+        configRow(t("studio.progress.epochs"), cfgEpochs),
+        configRow(t("studio.progress.batchSize"), cfgBatchSize),
+        configRow(t("studio.progress.learningRate"), cfgLearningRate),
+        configRow(t("studio.progress.optimizer"), optimizerLabel),
+        configRow(t("studio.progress.maxSteps"), cfgMaxSteps),
+        configRow(t("studio.progress.contextLength"), cfgContextLength),
+        configRow(t("studio.progress.warmupSteps"), cfgWarmupSteps),
       ],
     },
     ...(data.trainingMethod !== "full"
@@ -187,10 +201,10 @@ export function ProgressSection({
           {
             section: "LoRA",
             rows: [
-              configRow("Rank", cfgLoraRank),
-              configRow("Alpha", cfgLoraAlpha),
-              configRow("Dropout", cfgLoraDropout),
-              configRow("Variant", cfgLoraVariant),
+              configRow(t("studio.progress.rank"), cfgLoraRank),
+              configRow(t("studio.progress.alpha"), cfgLoraAlpha),
+              configRow(t("studio.progress.dropout"), cfgLoraDropout),
+              configRow(t("studio.progress.variant"), cfgLoraVariant),
             ],
           },
         ]
@@ -200,8 +214,8 @@ export function ProgressSection({
   return (
     <SectionCard
       icon={<HugeiconsIcon icon={ChartAverageIcon} className="size-5" />}
-      title="Training Progress"
-      description={data.message || "Live training metrics"}
+      title={t("studio.progress.title")}
+      description={data.message || t("studio.progress.liveMetrics")}
       accent="emerald"
       className="shadow-border border border-border/60 bg-card/90 ring-0 backdrop-blur-sm"
       headerAction={
@@ -225,20 +239,25 @@ export function ProgressSection({
             <span
               className={`rounded-full px-2.5 py-1 text-[10px] font-semibold ${phaseColors[data.phase]}`}
             >
-              {phaseLabel[data.phase]}
+              {t(phaseLabelKeys[data.phase])}
             </span>
             <span className="text-[10px] tabular-nums text-muted-foreground">
-              Epoch {formatNumber(data.currentEpoch, 2)}
+              {t("studio.progress.epoch", {
+                value: formatNumber(data.currentEpoch, 2),
+              })}
             </span>
             <span className="rounded-full border border-border/60 px-2.5 py-1 text-[10px] font-medium tabular-nums text-muted-foreground">
-              {pct}% complete
+              {t("studio.progress.percentComplete", { percent: pct })}
             </span>
           </div>
 
           <div className="flex flex-col gap-2">
             <div className="flex justify-between text-xs text-muted-foreground">
               <span>
-                Step {data.currentStep} / {data.totalSteps || "--"}
+                {t("studio.progress.stepProgress", {
+                  current: data.currentStep,
+                  total: data.totalSteps || "--",
+                })}
               </span>
               <span>{pct}%</span>
             </div>
@@ -261,33 +280,37 @@ export function ProgressSection({
 
           <div className="grid gap-x-4 gap-y-3 pt-1 sm:grid-cols-2 xl:grid-cols-5">
             <MetricStat
-              label="Loss"
+              label={t("studio.progress.loss")}
               valueClassName="text-2xl font-bold tracking-tight"
             >
               {stoppedLoss != null ? stoppedLoss.toFixed(4) : "--"}
             </MetricStat>
-            <MetricStat label="LR">{stoppedLr != null ? stoppedLr.toExponential(2) : "--"}</MetricStat>
-            <MetricStat label="Grad Norm">
+            <MetricStat label={t("studio.progress.lr")}>{stoppedLr != null ? stoppedLr.toExponential(2) : "--"}</MetricStat>
+            <MetricStat label={t("studio.progress.gradNorm")}>
               {formatNumber(stoppedGradNorm, 3)}
             </MetricStat>
-            <MetricStat label="Model" valueClassName="truncate">
+            <MetricStat label={t("studio.progress.model")} valueClassName="truncate">
               {data.modelName || "--"}
             </MetricStat>
-            <MetricStat label="Method">
+            <MetricStat label={t("studio.progress.method")}>
               {trainingMethodLabel}
             </MetricStat>
           </div>
 
           <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground">
-            <span>Elapsed: {formatDuration(elapsed)}</span>
-            {!isHistorical && <span>ETA: {formatDuration(eta)}</span>}
+            <span>{t("studio.progress.elapsed", { value: formatDuration(elapsed) })}</span>
+            {!isHistorical && (
+              <span>{t("studio.progress.eta", { value: formatDuration(eta) })}</span>
+            )}
             <span>
               {stepsPerSecond == null
-                ? "-- steps/s"
-                : `${stepsPerSecond.toFixed(2)} steps/s`}
+                ? t("studio.progress.noStepsPerSecond")
+                : t("studio.progress.stepsPerSecond", {
+                    value: stepsPerSecond.toFixed(2),
+                  })}
             </span>
             {data.currentNumTokens != null && (
-              <span>Tokens: {data.currentNumTokens}</span>
+              <span>{t("studio.progress.tokens", { value: data.currentNumTokens })}</span>
             )}
           </div>
         </div>
@@ -305,19 +328,22 @@ function LiveGpuPanel({
 }: {
   isTrainingRunning: boolean;
 }): ReactElement {
+  const t = useT();
   const gpu = useGpuUtilization(isTrainingRunning);
 
   return (
     <div className="flex flex-col gap-3">
       <div className="flex items-center justify-between">
         <p className="text-xs font-medium text-muted-foreground">
-          GPU Monitor
+          {t("studio.progress.gpuMonitor")}
         </p>
-        <span className="text-[11px] text-muted-foreground">Live</span>
+        <span className="text-[11px] text-muted-foreground">
+          {t("studio.progress.live")}
+        </span>
       </div>
       <div className="grid grid-cols-2 gap-2.5">
         <GpuStat
-          label="Utilization"
+          label={t("studio.progress.utilization")}
           icon={
             <HugeiconsIcon
               icon={DashboardSpeed01Icon}
@@ -332,7 +358,7 @@ function LiveGpuPanel({
           pct={gpu.gpu_utilization_pct ?? 0}
         />
         <GpuStat
-          label="Temperature"
+          label={t("studio.progress.temperature")}
           icon={
             <HugeiconsIcon icon={TemperatureIcon} className="size-3.5" />
           }
@@ -343,7 +369,7 @@ function LiveGpuPanel({
           max={100}
         />
         <GpuStat
-          label="VRAM"
+          label={t("studio.progress.vram")}
           icon={<HugeiconsIcon icon={RamMemoryIcon} className="size-3.5" />}
           value={
             gpu.vram_used_gb != null && gpu.vram_total_gb != null
@@ -353,7 +379,7 @@ function LiveGpuPanel({
           pct={gpu.vram_utilization_pct ?? 0}
         />
         <GpuStat
-          label="Power"
+          label={t("studio.progress.power")}
           icon={<HugeiconsIcon icon={ZapIcon} className="size-3.5" />}
           value={
             gpu.power_draw_w != null
@@ -417,6 +443,7 @@ function ConfigPopoverButton({
 }: {
   configItems: ConfigGroup[];
 }): ReactElement {
+  const t = useT();
   return (
     <Popover>
       <PopoverTrigger asChild={true}>
@@ -425,14 +452,14 @@ function ConfigPopoverButton({
           variant="ghost"
           size="icon-sm"
           className="rounded-full text-muted-foreground hover:bg-muted hover:text-foreground"
-          aria-label="Open training config"
+          aria-label={t("studio.progress.openConfig")}
         >
           <HugeiconsIcon icon={Notebook01Icon} className="size-4" />
         </Button>
       </PopoverTrigger>
       <PopoverContent className="w-72" align="end">
         <div className="flex flex-col gap-3">
-          <p className="text-xs font-semibold">Training Config</p>
+          <p className="text-xs font-semibold">{t("studio.progress.configLabel")}</p>
           {configItems.map((group) => (
             <div key={group.section} className="flex flex-col gap-1">
               <p className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
@@ -469,6 +496,7 @@ function TrainingHeaderActions({
   stopDialogOpen: boolean;
   stopRequested: boolean;
 }): ReactElement {
+  const t = useT();
   return (
     <div className="flex items-center gap-2">
       <ConfigPopoverButton configItems={configItems} />
@@ -486,25 +514,25 @@ function TrainingHeaderActions({
           disabled={!isTrainingRunning || stopRequested}
         >
           <HugeiconsIcon icon={StopIcon} className="size-3" />
-          {stopRequested ? "Stopping…" : "Stop"}
+          {stopRequested ? t("studio.training.stopping") : t("studio.training.stopAction")}
         </Button>
         <AlertDialogContent overlayClassName="bg-background/40 supports-backdrop-filter:backdrop-blur-[1px]">
           <AlertDialogHeader>
-            <AlertDialogTitle>Stop Training</AlertDialogTitle>
+            <AlertDialogTitle>{t("studio.training.stopTitle")}</AlertDialogTitle>
             <AlertDialogDescription>
-              Choose how you want to stop the current training run.
+              {t("studio.training.stopDescription")}
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
-            <AlertDialogCancel>Continue Training</AlertDialogCancel>
+            <AlertDialogCancel>{t("studio.training.continueAction")}</AlertDialogCancel>
             <AlertDialogAction
               variant="destructive"
               onClick={() => onRequestStop(false)}
             >
-              Cancel Training
+              {t("studio.training.cancelAction")}
             </AlertDialogAction>
             <AlertDialogAction onClick={() => onRequestStop(true)}>
-              Stop and Save
+              {t("studio.training.stopAndSave")}
             </AlertDialogAction>
           </AlertDialogFooter>
         </AlertDialogContent>
@@ -522,6 +550,7 @@ function MilestoneCallout({
   showHalfwayHint: boolean;
   onCompareInChat: () => Promise<void>;
 }): ReactElement | null {
+  const t = useT();
   if (!(showHalfwayHint || showCompletedHint)) {
     return null;
   }
@@ -532,7 +561,7 @@ function MilestoneCallout({
         <div className="min-w-0">
           {!showCompletedHint && (
             <p className="text-[10px] font-medium uppercase tracking-[0.12em] text-muted-foreground">
-              Milestone
+              {t("studio.training.milestone")}
             </p>
           )}
           <p
@@ -542,8 +571,8 @@ function MilestoneCallout({
             )}
           >
             {showCompletedHint
-              ? "Training done. Next step: compare base vs fine-tuned outputs."
-              : "Halfway done. Training is past 50%."}
+              ? t("studio.training.doneNextStep")
+              : t("studio.training.halfwayDone")}
           </p>
         </div>
         {!showCompletedHint && (
@@ -555,10 +584,10 @@ function MilestoneCallout({
       {showCompletedHint && (
         <div className="mt-2 flex flex-wrap gap-2">
           <Button size="xs" onClick={onCompareInChat}>
-            Compare in Chat
+            {t("studio.training.compareInChat")}
           </Button>
           <Button asChild={true} size="xs" variant="outline">
-            <Link to="/export">Export Model</Link>
+            <Link to="/export">{t("studio.training.exportModel")}</Link>
           </Button>
         </div>
       )}
diff --git a/studio/frontend/src/features/studio/sections/training-section.tsx b/studio/frontend/src/features/studio/sections/training-section.tsx
index 46f97c358f..7ce2462fc1 100644
--- a/studio/frontend/src/features/studio/sections/training-section.tsx
+++ b/studio/frontend/src/features/studio/sections/training-section.tsx
@@ -28,10 +28,7 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { useRef } from "react";
 import { toast } from "@/lib/toast";
 import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
-
-const chartConfig = {
-  loss: { label: "Loss", color: "#3b82f6" },
-} satisfies ChartConfig;
+import { useT } from "@/i18n";
 
 const placeholderData = [
   { step: 0, loss: 2.5 },
@@ -43,6 +40,10 @@ const placeholderData = [
 ];
 
 export function TrainingSection() {
+  const t = useT();
+  const chartConfig = {
+    loss: { label: t("studio.charts.loss"), color: "#3b82f6" },
+  } satisfies ChartConfig;
   const store = useTrainingConfigStore();
   const { isStarting, startError, startTrainingRun } = useTrainingActions();
   const isLoadingModel = store.isLoadingModelDefaults || store.isCheckingVision;
@@ -65,16 +66,16 @@ export function TrainingSection() {
       try {
         const config = parseYamlConfig(reader.result as string);
         store.applyConfigPatch(config);
-        toast.success("Config loaded", { description: file.name });
+        toast.success(t("studio.training.configLoaded"), { description: file.name });
       } catch (err) {
-        toast.error("Failed to load config", {
+        toast.error(t("studio.training.failedToLoadConfig"), {
           description:
-            err instanceof Error ? err.message : "Invalid YAML file",
+            err instanceof Error ? err.message : t("studio.training.invalidYamlFile"),
         });
       }
     };
     reader.onerror = () => {
-      toast.error("Failed to read file");
+      toast.error(t("studio.training.failedToReadFile"));
     };
     reader.readAsText(file);
   };
@@ -98,15 +99,15 @@ export function TrainingSection() {
 
   const handleResetConfig = () => {
     store.resetToModelDefaults();
-    toast.success("Parameters reset to model defaults");
+    toast.success(t("studio.training.parametersReset"));
   };
 
   return (
     <div data-tour="studio-training" className="min-w-0">
       <SectionCard
         icon={<HugeiconsIcon icon={ChartAverageIcon} className="size-5" />}
-        title="Training"
-        description="Monitor and control training"
+        title={t("studio.training.title")}
+        description={t("studio.training.description")}
         accent="blue"
         className={hasMessage ? "min-h-studio-config-column" : "h-studio-config-column"}
       >
@@ -147,10 +148,10 @@ export function TrainingSection() {
               className="size-5 text-muted-foreground/50"
             />
             <p className="text-sm font-medium text-muted-foreground">
-              No training data yet
+              {t("studio.training.chartNoDataTitle")}
             </p>
             <p className="text-xs text-muted-foreground/60">
-              Start training to see loss progress
+              {t("studio.training.chartNoDataDescription")}
             </p>
           </div>
         </div>
@@ -163,7 +164,13 @@ export function TrainingSection() {
           disabled={isStarting || isIncompatible || store.isCheckingDataset || isLoadingModel || !configValidation.ok}
         >
           <HugeiconsIcon icon={Rocket01Icon} className="size-4" />
-          {isStarting ? "Starting..." : isLoadingModel ? "Loading model..." : store.isCheckingDataset ? "Checking dataset..." : "Start Training"}
+          {isStarting
+            ? t("studio.training.starting")
+            : isLoadingModel
+              ? t("studio.training.loadingModel")
+              : store.isCheckingDataset
+                ? t("studio.training.checkingDataset")
+                : t("studio.training.startTraining")}
         </Button>
         {startError && (
           <p className="text-xs text-red-500 leading-relaxed">{startError}</p>
@@ -171,8 +178,8 @@ export function TrainingSection() {
         {isIncompatible && (
           <p className="text-xs text-red-500 leading-relaxed">
             {!store.isAudioModel && store.isDatasetAudio === true
-              ? "This model does not support audio. Switch to an audio-capable model or choose a non-audio dataset."
-              : "Text model is not compatible with a multimodal dataset. Switch to a vision model or choose a text-only dataset."}
+              ? t("studio.training.audioIncompatible")
+              : t("studio.training.visionIncompatible")}
           </p>
         )}
         {!configValidation.ok && configValidation.message && !isIncompatible && (
@@ -180,7 +187,7 @@ export function TrainingSection() {
         )}
 
         {/* Upload / Save / Reset */}
-        <p className="text-xs text-muted-foreground">Training Config</p>
+        <p className="text-xs text-muted-foreground">{t("studio.training.configLabel")}</p>
         <div className="grid grid-cols-3 gap-2">
           <Tooltip>
             <TooltipTrigger asChild>
@@ -191,10 +198,10 @@ export function TrainingSection() {
                 onClick={() => fileInputRef.current?.click()}
               >
                 <HugeiconsIcon icon={CloudUploadIcon} className="size-3.5" />
-                Upload
+                {t("studio.training.upload")}
               </Button>
             </TooltipTrigger>
-            <TooltipContent>Load a saved YAML config</TooltipContent>
+            <TooltipContent>{t("studio.training.uploadConfigTooltip")}</TooltipContent>
           </Tooltip>
           <Tooltip>
             <TooltipTrigger asChild>
@@ -206,10 +213,10 @@ export function TrainingSection() {
                 onClick={handleSaveConfig}
               >
                 <HugeiconsIcon icon={Archive04Icon} className="size-3.5" />
-                Save
+                {t("studio.training.save")}
               </Button>
             </TooltipTrigger>
-            <TooltipContent>Download current config as YAML</TooltipContent>
+            <TooltipContent>{t("studio.training.saveConfigTooltip")}</TooltipContent>
           </Tooltip>
           <Tooltip>
             <TooltipTrigger asChild>
@@ -221,10 +228,10 @@ export function TrainingSection() {
                 disabled={!store.selectedModel}
               >
                 <HugeiconsIcon icon={CleanIcon} className="size-3.5" />
-                Reset
+                {t("studio.training.reset")}
               </Button>
             </TooltipTrigger>
-            <TooltipContent>Reset to model defaults</TooltipContent>
+            <TooltipContent>{t("studio.training.resetConfigTooltip")}</TooltipContent>
           </Tooltip>
         </div>
         <input
diff --git a/studio/frontend/src/features/studio/studio-page.tsx b/studio/frontend/src/features/studio/studio-page.tsx
index 2affe7415a..b13ecbd1c4 100644
--- a/studio/frontend/src/features/studio/studio-page.tsx
+++ b/studio/frontend/src/features/studio/studio-page.tsx
@@ -24,8 +24,10 @@ import { TrainingSection } from "./sections/training-section";
 import { LiveTrainingView } from "./live-training-view";
 import { HistoricalTrainingView } from "./historical-training-view";
 import { HistoryCardGrid } from "./history-card-grid";
+import { useT } from "@/i18n";
 
 export function StudioPage(): ReactElement {
+  const t = useT();
   useTrainingRuntimeLifecycle();
   const showTrainingView = useTrainingRuntimeStore(shouldShowTrainingView);
   const isTrainingRunning = useTrainingRuntimeStore((state) => state.isTrainingRunning);
@@ -120,10 +122,13 @@ export function StudioPage(): ReactElement {
   }
 
   const subtitle = (() => {
-    if (activeTab === "current-run") return runtimeMessage || "Training in progress";
+    if (activeTab === "current-run")
+      return runtimeMessage || t("studio.subtitles.trainingInProgress");
     if (activeTab === "history")
-      return selectedHistoryRunId ? "Viewing past run" : "View past training runs";
-    return "Configure and start training";
+      return selectedHistoryRunId
+        ? t("studio.subtitles.viewingPastRun")
+        : t("studio.subtitles.viewPastRuns");
+    return t("studio.subtitles.configure");
   })();
 
   return (
@@ -150,14 +155,14 @@ export function StudioPage(): ReactElement {
 
         <div className="mb-6 flex flex-col gap-0.5 sm:mb-8">
           <h1 className="text-2xl font-semibold tracking-tight">
-            Fine-tuning Studio
+            {t("studio.title")}
           </h1>
           <p className="text-sm text-muted-foreground">{subtitle}</p>
         </div>
 
         {!hasHydratedRuntime && isHydratingRuntime ? (
           <div className="rounded-xl border bg-card p-8 text-sm text-muted-foreground">
-            Loading training runtime...
+            {t("studio.loadingRuntime")}
           </div>
         ) : (
           <Tabs value={activeTab} onValueChange={handleTabChange}>
@@ -168,19 +173,19 @@ export function StudioPage(): ReactElement {
                   size="icon-sm"
                   className="rounded-full text-muted-foreground"
                   onClick={() => setSelectedHistoryRunId(null)}
-                  aria-label="Back to history"
+                  aria-label={t("studio.backToHistory")}
                 >
                   <HugeiconsIcon icon={ArrowLeft01Icon} className="size-4" />
                 </Button>
               )}
               <TabsList variant="line">
                 <TabsTrigger value="configure" disabled={isTrainingRunning}>
-                  Configure
+                  {t("studio.tabs.configure")}
                 </TabsTrigger>
                 <TabsTrigger value="current-run" disabled={!showTrainingView}>
-                  Current Run
+                  {t("studio.tabs.currentRun")}
                 </TabsTrigger>
-                <TabsTrigger value="history">History</TabsTrigger>
+                <TabsTrigger value="history">{t("studio.tabs.history")}</TabsTrigger>
               </TabsList>
             </div>
 
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index 27c5a13163..8ecd3bb7e9 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -33,6 +33,7 @@ import {
 import { Cancel01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useState, type ReactElement } from "react";
+import { useT } from "@/i18n";
 
 const HF_REPO_REGEX = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 
@@ -171,6 +172,7 @@ type DownloadRowProps = {
 };
 
 function DownloadRow({ label, state }: DownloadRowProps): ReactElement | null {
+  const t = useT();
   // Compute a rolling-window rate + ETA from the same cumulative-byte
   // series the poll hook already produces, so we can show
   // "5.2 / 20.7 GB • 85.3 MB/s • 3m 12s left" instead of just the pair.
@@ -179,22 +181,25 @@ function DownloadRow({ label, state }: DownloadRowProps): ReactElement | null {
   if (state.downloadedBytes <= 0 && !state.cachePath) return null;
   const isComplete = state.totalBytes > 0 && state.percent >= 100;
   const statusLabel = isComplete
-    ? "Ready"
+    ? t("studio.trainingStart.ready")
     : state.totalBytes > 0
-      ? "Downloading"
+      ? t("studio.trainingStart.downloading")
       : state.downloadedBytes === 0
-        ? "Preparing"
+        ? t("studio.trainingStart.preparing")
         : null;
   const showRate = stats.stable && !isComplete;
   const rateSuffix = showRate ? ` • ${formatRate(stats.rateBytesPerSecond)}` : "";
   const etaStr =
     showRate && state.totalBytes > 0 ? formatEta(stats.etaSeconds) : "--";
-  const etaSuffix = etaStr !== "--" ? ` • ${etaStr} left` : "";
+  const etaSuffix =
+    etaStr !== "--" ? ` • ${t("studio.trainingStart.left", { eta: etaStr })}` : "";
   const sizeLabel =
     state.totalBytes > 0
       ? `${formatBytes(state.downloadedBytes)} / ${formatBytes(state.totalBytes)}${rateSuffix}${etaSuffix}`
       : state.downloadedBytes > 0
-        ? `${formatBytes(state.downloadedBytes)} downloaded${rateSuffix}`
+        ? `${t("studio.trainingStart.downloaded", {
+            size: formatBytes(state.downloadedBytes),
+          })}${rateSuffix}`
         : null;
   return (
     <div className="flex flex-col gap-1.5 rounded-md border border-border/50 bg-muted/20 px-3 py-2">
@@ -245,6 +250,7 @@ export function TrainingStartOverlay({
   message,
   currentStep,
 }: TrainingStartOverlayProps): ReactElement {
+  const t = useT();
   const { stopTrainingRun, dismissTrainingRun } = useTrainingActions();
   const isStarting = useTrainingRuntimeStore((s) => s.isStarting);
   const phase = useTrainingRuntimeStore((s) => s.phase);
@@ -273,8 +279,8 @@ export function TrainingStartOverlay({
       : null;
   const displayMessage =
     startFromResume && !isDownloadPhase && /^download/i.test(message)
-      ? "Resuming training..."
-      : message || "starting training...";
+      ? t("studio.trainingStart.resumingTraining")
+      : message || t("studio.trainingStart.startingTraining");
   const rawModelDownload = useModelDownloadProgress(modelName);
   const rawDatasetDownload = useDatasetDownloadProgress(datasetName);
   const modelDownload = isDownloadPhase
@@ -297,7 +303,7 @@ export function TrainingStartOverlay({
       <div className="pointer-events-auto relative flex w-[860px] max-w-[calc(100%-2rem)] flex-col items-center gap-4">
         <img
           src="/unsloth-gem.png"
-          alt="Unsloth mascot"
+          alt="Unsloth Studio"
           className="size-24 object-contain"
         />
         <div className="relative w-full">
@@ -313,13 +319,13 @@ export function TrainingStartOverlay({
             </Button>
             <AlertDialogContent overlayClassName="bg-background/40 supports-backdrop-filter:backdrop-blur-[1px]">
               <AlertDialogHeader>
-                <AlertDialogTitle>Cancel Training</AlertDialogTitle>
+                <AlertDialogTitle>{t("studio.training.cancelTitle")}</AlertDialogTitle>
                 <AlertDialogDescription>
-                  Do you want to cancel the current training run?
+                  {t("studio.training.cancelDescription")}
                 </AlertDialogDescription>
               </AlertDialogHeader>
               <AlertDialogFooter>
-                <AlertDialogCancel>Continue Training</AlertDialogCancel>
+                <AlertDialogCancel>{t("studio.training.continueAction")}</AlertDialogCancel>
                 <AlertDialogAction
                   variant="destructive"
                   onClick={() => {
@@ -335,7 +341,7 @@ export function TrainingStartOverlay({
                     });
                   }}
                 >
-                  Cancel Training
+                  {t("studio.training.cancelAction")}
                 </AlertDialogAction>
               </AlertDialogFooter>
             </AlertDialogContent>
@@ -348,24 +354,27 @@ export function TrainingStartOverlay({
             duration={36}
             className="bg-gradient-to-r from-emerald-300 via-lime-300 to-teal-300 bg-clip-text font-semibold text-transparent"
           >
-            {"> unsloth training starts..."}
+            {t("studio.trainingStart.terminalStart")}
           </TypingAnimation>
           <AnimatedSpan className="my-2">
             <pre className="whitespace-pre text-muted-foreground inline-block">{`==((====))==\n   \\\\   /|\nO^O/ \\_/ \\\n\\        /\n "-____-"`}</pre>
           </AnimatedSpan>
           <TypingAnimation duration={44}>
-            {"> Preparing model and dataset..."}
+            {t("studio.trainingStart.preparingResources")}
           </TypingAnimation>
           <TypingAnimation duration={44}>
-            {"> We are getting everything ready for your run..."}
+            {t("studio.trainingStart.gettingReady")}
           </TypingAnimation>
           <AnimatedSpan className="mt-2 text-muted-foreground">
-            {`> ${displayMessage} | waiting for first step... (${currentStep})`}
+            {t("studio.trainingStart.waitingForFirstStep", {
+              message: displayMessage,
+              step: currentStep,
+            })}
           </AnimatedSpan>
           {datasetDownload.downloadedBytes > 0 || datasetDownload.cachePath ? (
             <AnimatedSpan className="mt-3">
               <DownloadRow
-                label="Dataset"
+                label={t("studio.trainingStart.dataset")}
                 state={datasetDownload}
               />
             </AnimatedSpan>
@@ -373,7 +382,7 @@ export function TrainingStartOverlay({
           {modelDownload.downloadedBytes > 0 || modelDownload.cachePath ? (
             <AnimatedSpan className="mt-3">
               <DownloadRow
-                label="Model weights"
+                label={t("studio.trainingStart.modelWeights")}
                 state={modelDownload}
               />
             </AnimatedSpan>
diff --git a/studio/frontend/src/features/training/index.ts b/studio/frontend/src/features/training/index.ts
index 83d8edba75..654ddedd03 100644
--- a/studio/frontend/src/features/training/index.ts
+++ b/studio/frontend/src/features/training/index.ts
@@ -9,7 +9,10 @@ export {
 export { useTrainingActions } from "./hooks/use-training-actions";
 export { useTrainingHistorySidebarItems } from "./hooks/use-training-history-sidebar";
 export { useTrainingRuntimeLifecycle } from "./hooks/use-training-runtime-lifecycle";
-export { removeTrainingUnloadGuard } from "./hooks/use-training-unload-guard";
+export {
+  removeTrainingUnloadGuard,
+  useTrainingUnloadGuard,
+} from "./hooks/use-training-unload-guard";
 export { useMaxStepsEpochsToggle } from "./hooks/use-max-steps-epochs-toggle";
 export { HfDatasetSubsetSplitSelectors } from "./components/hf-dataset-subset-split-selectors";
 export { useDatasetPreviewDialogStore } from "./stores/dataset-preview-dialog-store";
diff --git a/studio/frontend/src/i18n/AGENTS.md b/studio/frontend/src/i18n/AGENTS.md
new file mode 100644
index 0000000000..42d964acca
--- /dev/null
+++ b/studio/frontend/src/i18n/AGENTS.md
@@ -0,0 +1,11 @@
+# i18n Contribution Instructions
+
+- `locales/en.ts` is the complete baseline message file.
+- Non-English locale files may be partial. Missing keys must fall back to English at runtime.
+- Use BCP 47 locale tags for new languages, for example `zh-CN`, `ja-JP`, and `ko-KR`.
+- Do not change fallback logic to hide missing translations.
+- Do not add automatic DOM translation, MutationObserver text replacement, or runtime guess-based translation.
+- Preserve interpolation variables exactly, for example `{count}`, `{model}`, and `{provider}`.
+- Keep product and technical names unchanged unless there is an established localized name, for example `Unsloth Studio`, `LoRA`, `GGUF`, and `Hugging Face`.
+- Keep translation changes small and reviewable. Prefer separate commits for runtime changes, UI migration, and locale text.
+- When adding user-facing Studio UI text, add the English message key first and add non-English overrides only when the translation is clear.
diff --git a/studio/frontend/src/i18n/check-parity.ts b/studio/frontend/src/i18n/check-parity.ts
new file mode 100644
index 0000000000..9808fd0e36
--- /dev/null
+++ b/studio/frontend/src/i18n/check-parity.ts
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Parity check between en.ts and every non-English locale.
+// - Locale files may be partial; missing keys must fall back to English.
+// - All zh-CN keys must exist in en (no extras).
+// - Placeholder set must match per leaf between en and the overlay.
+//
+// Run: npx tsx src/i18n/check-parity.ts
+
+import { en } from "./locales/en.ts";
+import { zhCN } from "./locales/zh-CN.ts";
+
+type Tree = { readonly [k: string]: string | Tree };
+
+function isTree(v: unknown): v is Tree {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function placeholders(s: string): string[] {
+  const out: string[] = [];
+  const re = /\{([a-zA-Z0-9_]+)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(s))) out.push(m[1]);
+  return out.sort();
+}
+
+function checkOverlay(
+  enNode: Tree,
+  overlay: Tree | undefined,
+  path: string,
+  errors: string[],
+  missing: string[],
+): void {
+  for (const [k, v] of Object.entries(enNode)) {
+    const subPath = path ? `${path}.${k}` : k;
+    if (typeof v === "string") {
+      if (overlay === undefined) {
+        missing.push(subPath);
+        continue;
+      }
+      const overlayV = overlay[k];
+      if (overlayV === undefined) {
+        missing.push(subPath);
+        continue;
+      }
+      if (typeof overlayV !== "string") {
+        errors.push(`${subPath} should be string, got ${typeof overlayV}`);
+        continue;
+      }
+      const enP = placeholders(v);
+      const ovP = placeholders(overlayV);
+      if (JSON.stringify(enP) !== JSON.stringify(ovP)) {
+        errors.push(
+          `${subPath}: placeholder mismatch en={${enP.join(",")}} overlay={${ovP.join(",")}}`,
+        );
+      }
+    } else if (isTree(v)) {
+      const overlaySub = overlay === undefined ? undefined : overlay[k];
+      if (overlaySub !== undefined && !isTree(overlaySub)) {
+        errors.push(`${subPath} should be an object, got ${typeof overlaySub}`);
+        continue;
+      }
+      checkOverlay(v, overlaySub, subPath, errors, missing);
+    }
+  }
+}
+
+function checkExtras(
+  overlay: Tree,
+  enNode: Tree,
+  path: string,
+  errors: string[],
+): void {
+  for (const [k, v] of Object.entries(overlay)) {
+    const subPath = path ? `${path}.${k}` : k;
+    if (!(k in enNode)) {
+      errors.push(`${subPath} exists in overlay but not in en`);
+      continue;
+    }
+    const enV = enNode[k];
+    if (isTree(v) && isTree(enV)) {
+      checkExtras(v, enV, subPath, errors);
+    } else if (isTree(v) !== isTree(enV)) {
+      errors.push(`${subPath}: shape mismatch (en=${typeof enV}, overlay=${typeof v})`);
+    }
+  }
+}
+
+const overlays: Record<string, Tree> = { "zh-CN": zhCN as unknown as Tree };
+let anyError = false;
+
+for (const [locale, overlay] of Object.entries(overlays)) {
+  const errors: string[] = [];
+  const missing: string[] = [];
+  checkOverlay(en as unknown as Tree, overlay, "", errors, missing);
+  checkExtras(overlay, en as unknown as Tree, "", errors);
+
+  console.log(`\n=== ${locale} ===`);
+  console.log(`Missing keys (will fall back to en): ${missing.length}`);
+  if (errors.length) {
+    anyError = true;
+    console.error(`Errors (${errors.length}):`);
+    for (const e of errors) console.error(`  - ${e}`);
+  } else {
+    console.log("No errors.");
+  }
+}
+
+if (anyError) process.exit(1);
+console.log("\nAll locale overlays pass parity.");
diff --git a/studio/frontend/src/i18n/index.ts b/studio/frontend/src/i18n/index.ts
new file mode 100644
index 0000000000..6cd2fe230a
--- /dev/null
+++ b/studio/frontend/src/i18n/index.ts
@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback } from "react";
+import { useLocale } from "./locale-store";
+import { translate } from "./messages";
+import type { InterpolationValues } from "./types";
+import type { TranslationKey } from "./messages";
+
+export {
+  DEFAULT_LOCALE,
+  LOCALE_STORAGE_KEY,
+  getLocale,
+  initializeLocale,
+  setLocale,
+  subscribeLocale,
+  useLocale,
+} from "./locale-store";
+export {
+  LOCALES,
+  isSupportedLocale,
+  messages,
+  translate,
+} from "./messages";
+export type { Locale, TranslationKey } from "./messages";
+export type {
+  DeepPartialMessageTree,
+  InterpolationValues,
+  MessageKey,
+  MessageTree,
+} from "./types";
+
+export function useT(): (
+  key: TranslationKey,
+  values?: InterpolationValues,
+) => string {
+  const locale = useLocale();
+
+  return useCallback(
+    (key: TranslationKey, values?: InterpolationValues) =>
+      translate(key, values, locale),
+    [locale],
+  );
+}
diff --git a/studio/frontend/src/i18n/locale-store.ts b/studio/frontend/src/i18n/locale-store.ts
new file mode 100644
index 0000000000..8b4643f5a9
--- /dev/null
+++ b/studio/frontend/src/i18n/locale-store.ts
@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useSyncExternalStore } from "react";
+import { isSupportedLocale, type Locale } from "./messages";
+
+export const DEFAULT_LOCALE: Locale = "en";
+export const LOCALE_STORAGE_KEY = "unsloth_locale";
+
+const subscribers = new Set<() => void>();
+
+let currentLocale: Locale = DEFAULT_LOCALE;
+let isStorageListenerActive = false;
+
+function normalizeLocale(value: unknown): Locale {
+  return isSupportedLocale(value) ? value : DEFAULT_LOCALE;
+}
+
+function readStoredLocale(): Locale {
+  try {
+    const stored = globalThis.localStorage?.getItem(LOCALE_STORAGE_KEY) ?? null;
+    return normalizeLocale(stored);
+  } catch {
+    return DEFAULT_LOCALE;
+  }
+}
+
+function writeStoredLocale(locale: Locale): void {
+  try {
+    globalThis.localStorage?.setItem(LOCALE_STORAGE_KEY, locale);
+  } catch {
+    // localStorage 可能被禁用；失败只影响持久化，不影响当前会话语言。
+  }
+}
+
+function syncDocumentLang(locale: Locale): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.lang = locale;
+}
+
+function notifySubscribers(): void {
+  for (const subscriber of subscribers) subscriber();
+}
+
+function updateCurrentLocale(locale: Locale): void {
+  if (locale === currentLocale) return;
+  currentLocale = locale;
+  syncDocumentLang(locale);
+  notifySubscribers();
+}
+
+function isLocaleStorageEvent(event: StorageEvent): boolean {
+  if (event.key !== LOCALE_STORAGE_KEY && event.key !== null) return false;
+  if (!event.storageArea || typeof window === "undefined") return true;
+  // Accessing window.localStorage can throw in privacy-restricted contexts
+  // where storage is blocked; mirror the try/catch in readStoredLocale/
+  // writeStoredLocale so storage-event handling is just as resilient.
+  try {
+    return event.storageArea === window.localStorage;
+  } catch {
+    return false;
+  }
+}
+
+function handleStorageEvent(event: StorageEvent): void {
+  if (!isLocaleStorageEvent(event)) return;
+  const nextLocale =
+    event.key === null ? DEFAULT_LOCALE : normalizeLocale(event.newValue);
+  updateCurrentLocale(nextLocale);
+}
+
+function startStorageListener(): void {
+  if (isStorageListenerActive || typeof window === "undefined") return;
+  window.addEventListener("storage", handleStorageEvent);
+  isStorageListenerActive = true;
+}
+
+function stopStorageListener(): void {
+  if (!isStorageListenerActive || typeof window === "undefined") return;
+  window.removeEventListener("storage", handleStorageEvent);
+  isStorageListenerActive = false;
+}
+
+function getLocaleSnapshot(): Locale {
+  return currentLocale;
+}
+
+function getServerLocaleSnapshot(): Locale {
+  return DEFAULT_LOCALE;
+}
+
+export function subscribeLocale(listener: () => void): () => void {
+  const shouldStartStorageListener = subscribers.size === 0;
+  subscribers.add(listener);
+  if (shouldStartStorageListener) startStorageListener();
+
+  return () => {
+    subscribers.delete(listener);
+    if (subscribers.size === 0) stopStorageListener();
+  };
+}
+
+export function initializeLocale(): Locale {
+  const nextLocale = readStoredLocale();
+  currentLocale = nextLocale;
+  syncDocumentLang(nextLocale);
+  notifySubscribers();
+  return nextLocale;
+}
+
+export function getLocale(): Locale {
+  return currentLocale;
+}
+
+export function setLocale(locale: Locale): void {
+  const requestedLocale = normalizeLocale(locale);
+  writeStoredLocale(requestedLocale);
+
+  currentLocale = requestedLocale;
+  syncDocumentLang(requestedLocale);
+  notifySubscribers();
+}
+
+export function useLocale(): Locale {
+  return useSyncExternalStore(
+    subscribeLocale,
+    getLocaleSnapshot,
+    getServerLocaleSnapshot,
+  );
+}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
new file mode 100644
index 0000000000..b94f3aa105
--- /dev/null
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -0,0 +1,731 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export const en = {
+  common: {
+    cancel: "Cancel",
+    close: "Close",
+    delete: "Delete",
+    done: "Done",
+    error: "Error",
+    export: "Export",
+    help: "Help",
+    loading: "Loading...",
+    new: "New",
+    rename: "Rename",
+    save: "Save",
+    search: "Search",
+    shutdown: "Shutdown",
+  },
+  shell: {
+    beta: "BETA",
+    brand: "unsloth",
+    product: "Unsloth Studio",
+    accountMenu: "{name} account menu",
+    aria: {
+      home: "Unsloth home",
+      closeSidebar: "Close sidebar",
+      openSidebar: "Open sidebar",
+      chatOptions: "Chat options",
+      runOptions: "Run options",
+    },
+    navigation: {
+      newChat: "New Chat",
+      compare: "Compare",
+      search: "Search",
+      train: "Train",
+      recipes: "Recipes",
+      export: "Export",
+      recents: "Recents",
+      settings: "Settings",
+      api: "API",
+      lightMode: "Light Mode",
+      darkMode: "Dark Mode",
+      guidedTour: "Guided Tour",
+      help: "Help",
+      logOut: "Log out",
+      shutdown: "Shutdown",
+    },
+    notFound: {
+      title: "Page not found",
+      description: "{path} does not exist.",
+      backToChat: "Back to chat",
+    },
+    dialog: {
+      deleteChat: {
+        title: "Delete chat",
+        description: "Are you sure you want to delete this chat \"{name}\"?",
+      },
+      deleteRun: {
+        title: "Delete training run",
+        description: "Are you sure you want to delete this run \"{name}\"?",
+      },
+      renameChat: {
+        title: "Rename chat",
+        placeholder: "Chat title",
+      },
+      renameRun: {
+        title: "Rename run",
+        placeholder: "Run name",
+      },
+    },
+    toast: {
+      cannotDeleteRunningRun: "Cannot delete a running training run",
+      failedToDeleteChat: "Failed to delete chat",
+      failedToDeleteRun: "Failed to delete run",
+      failedToRenameChat: "Failed to rename chat",
+      failedToRenameRun: "Failed to rename run",
+    },
+  },
+  settings: {
+    title: "Settings",
+    dialog: {
+      title: "Settings",
+      description: "Manage your Unsloth Studio preferences.",
+      closeAriaLabel: "Close settings",
+    },
+    tabs: {
+      general: "General",
+      profile: "Profile",
+      appearance: "Appearance",
+      chat: "Chat",
+      connections: "Connections",
+      apiKeys: "API",
+      about: "Help",
+    },
+    general: {
+      title: "General",
+      description: "Global preferences for Unsloth Studio.",
+      account: "Account",
+      huggingFaceToken: "Hugging Face token",
+      huggingFaceTokenDescription:
+        "Used to load gated models and push artifacts.",
+      hideToken: "Hide token",
+      showToken: "Show token",
+      chatDefaults: "Chat defaults",
+      autoTitleNewChats: "Auto-title new chats",
+      autoTitleNewChatsDescription:
+        "Generate a short title from the first message.",
+      gettingStarted: "Getting started",
+      startOnboarding: "Start onboarding",
+      startOnboardingDescription:
+        "Open the setup wizard again without changing your account.",
+      startOnboardingAction: "Start onboarding",
+      resetPreferences: {
+        sectionTitle: "Danger zone",
+        label: "Reset all local preferences",
+        description:
+          "Clears local-only preferences. Chats, API access, and DB-backed chat settings are not affected.",
+        action: "Reset preferences",
+        confirmTitle: "Reset all local preferences?",
+        confirmDescription:
+          "This clears local-only preferences, then reloads Studio. Chats, API access, and DB-backed chat settings are not affected.",
+        confirmAction: "Reset and reload",
+      },
+    },
+    profile: {
+      title: "Profile",
+      description: "Update how your profile appears in Studio.",
+      changePicture: "Change profile picture",
+      displayName: "Display name",
+      nameSaved: "Profile name saved",
+      namePersistErrorTitle: "Could not persist profile name",
+      namePersistErrorDescription:
+        "Name updated for this session, but may not persist after reload.",
+      photoUpdated: "Profile photo updated",
+      photoPersistErrorTitle: "Could not persist profile photo",
+      photoPersistErrorDescription:
+        "Photo updated for this session, but may not persist after reload.",
+      photoUpdateErrorTitle: "Could not update profile photo",
+      imageUseError: "Could not use this image.",
+    },
+    appearance: {
+      title: "Appearance",
+      description: "How Unsloth Studio looks on this device.",
+      theme: {
+        title: "Theme",
+        label: "Color scheme",
+        description: "Choose light, dark, or follow your system.",
+        system: "System",
+        light: "Light",
+        dark: "Dark",
+      },
+      language: {
+        title: "Language",
+        label: "Display language",
+        description: "Choose the language used by Studio.",
+      },
+      layout: {
+        title: "Layout",
+        compactSidebar: "Pin sidebar by default",
+        compactSidebarDescription:
+          "Keep the sidebar expanded instead of collapsing to icons.",
+      },
+    },
+    chat: {
+      title: "Chat",
+      description: "Manage your chat history stored on this device.",
+      data: "Data",
+      exportHistory: "Export chat history",
+      exportHistoryDescription:
+        "Download all chats and messages as a JSON file.",
+      exportAction: "Export",
+      exportingAction: "Exporting...",
+      clearHistory: "Clear chat history",
+      clearHistoryDescription: "Delete local chat history from this device.",
+      clearAction: "Clear",
+      clearAllChats: "Clear all chats",
+      clearAllChatsDescription:
+        "Permanently delete every chat on this device.",
+      noChatsToClear: "No chats to clear.",
+      clearOneChatDescription:
+        "Permanently delete the only chat on this device.",
+      clearChatCountDescription:
+        "Permanently delete all {count} chats on this device.",
+      clearChatsAction: "Clear chats",
+      clearOneChatTitle: "Clear 1 chat?",
+      clearChatsTitle: "Clear {count} chats?",
+      clearChatsConfirmDescription:
+        "This permanently deletes every chat and message stored on this device. This cannot be undone.",
+      clearingAction: "Clearing...",
+      clearOneChatAction: "Clear 1 chat",
+      clearChatCountAction: "Clear {count} chats",
+      clearedAllChats: "Cleared all chats",
+      clearedOneChat: "Cleared 1 chat",
+      clearedChatCount: "Cleared {count} chats",
+      someChatsCouldNotBeCleared: "Some chats could not be cleared",
+      chatsClearedRemainOne:
+        "{clearedCount} chats cleared; 1 chat remains. Please retry.",
+      chatsClearedRemain:
+        "{clearedCount} chats cleared; {remainingCount} chats remain. Please retry.",
+      oneChatClearedRemain:
+        "1 chat cleared; {remainingCount} chats remain. Please retry.",
+      oneChatClearedRemainOne:
+        "1 chat cleared; 1 chat remains. Please retry.",
+      storageClearFailedOne:
+        "A storage clear failed; 1 chat may remain. Please retry.",
+      storageClearFailed:
+        "A storage clear failed; {count} chats may remain. Please retry.",
+      failedToClearChats: "Failed to clear chats",
+    },
+    connections: {
+      title: "Connections",
+      description: "Manage providers and external service connections.",
+    },
+    apiKeys: {
+      title: "API",
+      description: "Access Unsloth programmatically via the OpenAI-compatible API.",
+      readDocs: "Read the API docs",
+      noAccess: "No API access yet.",
+      newBadge: "New",
+      accessTokens: "Access tokens",
+      loadError: "Couldn't load API access.",
+      createError: "Couldn't create access token.",
+      revokeError: "Couldn't revoke access token.",
+      never: "Never",
+      tokenNamePlaceholder: "Token name (e.g. production)",
+      newAccessTokenName: "New access token name",
+      createToken: "Create token",
+      creating: "Creating...",
+      newTokenCreated: "New access token created",
+      accessTokenCopied: "Access token copied",
+      copyAccessToken: "Copy access token",
+      copyNow: "Copy now - this won't be shown again.",
+      usageExamples: "Usage examples",
+      usageTools: "Tools",
+      copySnippet: "Copy snippet",
+      copy: "Copy",
+      copied: "Copied",
+      setupDocs: "Setup docs:",
+      relativeNever: "never",
+      relativeJustNow: "just now",
+      relativeHoursAgo: "{count}h ago",
+      relativeDaysAgo: "{count}d ago",
+      relativeMonthsAgo: "{count}mo ago",
+      relativeYearsAgo: "{count}y ago",
+      expired: "expired",
+      today: "today",
+      inDays: "in {count}d",
+      created: "Created {value}",
+      used: "Used {value}",
+      expires: "Expires {value}",
+      actionsFor: "Actions for {name}",
+      copyPrefix: "Copy prefix",
+      revokeToken: "Revoke token",
+      revokeTitle: "Revoke access token \"{name}\"?",
+      revokeDescription:
+        "Applications using this token will immediately lose access. This cannot be undone.",
+      revokeAction: "Revoke \"{name}\"",
+      revoking: "Revoking...",
+    },
+    about: {
+      title: "About",
+      description:
+        "Documentation, release notes, feedback, and Studio build info.",
+      studioVersion: "Studio Version",
+      packageVersion: "Package Version",
+      updates: "Updates",
+      help: "Help",
+      documentation: "Documentation",
+      releaseNotes: "Release notes",
+      whatsNew: "What's new",
+      feedback: "Feedback",
+      reportIssue: "Report an issue",
+      dangerZone: "Danger zone",
+      shutDownStudio: "Shut down Unsloth Studio",
+      shutDownStudioDescription:
+        "Stops the Studio server process and ends your session.",
+      shutDown: "Shut down",
+      update: {
+        title: "Update Unsloth Studio",
+        openPowerShell: "Open PowerShell and run:",
+        openTerminal: "Open Terminal and run:",
+        commandText: "{label} text",
+        copied: "Copied",
+        copyCommand: "Copy command",
+        commandCopied: "{label} copied",
+        copyNamedCommand: "Copy {label}",
+        checkingInstall: "Checking how Studio was installed...",
+        localInstallDetected:
+          "Source or local install detected. To avoid replacing it with PyPI, update from the checkout or source you originally installed from.",
+        pullThenUpdate:
+          "Pull latest changes from your Unsloth repo checkout, then update Studio locally:",
+        gitPullCommand: "git pull command",
+        localUpdateCommand: "local update command",
+        localInstallerFallback:
+          "If the Studio update command is unavailable, run the local installer from that checkout:",
+        localInstallerCommand: "local installer command",
+        sourceInstallDetected:
+          "This looks like a source or VCS package install. Reinstall from the original local path or Git URL you used.",
+        repoCheckoutFallback:
+          "If you still have the Unsloth repo checkout, run the local installer from that checkout:",
+        restartAfterUpdate:
+          "Restart Studio after updating for changes to take effect.",
+        unknownInstall:
+          "Studio could not detect how it was installed. Check how you installed Studio first, then choose the matching update path.",
+        curlOrPypi: "For curl or PyPI installs, run:",
+        updateCommand: "update command",
+        localCheckout:
+          "For local checkout installs, update from that checkout instead and use the local update command:",
+        fallbackInstruction:
+          "If that fails or unsloth studio update is unavailable, run:",
+        fallbackCommand: "fallback command",
+      },
+    },
+  },
+  studio: {
+    routeTitle: "Train",
+    title: "Fine-tuning Studio",
+    subtitles: {
+      configure: "Configure and start training",
+      trainingInProgress: "Training in progress",
+      viewPastRuns: "View past training runs",
+      viewingPastRun: "Viewing past run",
+    },
+    tabs: {
+      configure: "Configure",
+      currentRun: "Current Run",
+      history: "History",
+    },
+    loadingRuntime: "Loading training runtime...",
+    backToHistory: "Back to history",
+    sections: {
+      model: "Model",
+      dataset: "Dataset",
+      params: "Parameters",
+      training: "Training",
+      charts: "Charts",
+      progress: "Training Progress",
+    },
+    configure: {
+      title: "Configure",
+      description: "Choose a model, dataset, and training settings.",
+      startTraining: "Start Training",
+      starting: "Starting...",
+      loadingModel: "Loading model...",
+      checkingDataset: "Checking dataset...",
+      trainingConfig: "Training Config",
+    },
+    model: {
+      title: "Model",
+      description: "Select base model and training method",
+      fasterTrainingBadge: "2x Faster Training",
+      baseModel: "Base model",
+      localModel: "Local Model",
+      localModelTooltip: "Path to a locally downloaded model or a custom HF repo.",
+      scanningLocalAndCachedModels: "Scanning local and cached models...",
+      scanning: "Scanning...",
+      scanningLocalModels: "Scanning local models...",
+      noLocalModelsFound: "No local models found",
+      noLocalModelsFoundManual: "No local models found. Enter path manually.",
+      failedToLoadLocalModels: "Failed to load local models",
+      hfCache: "HF cache",
+      customFolders: "Custom Folders",
+      localDir: "Local dir",
+      huggingFaceModel: "Hugging Face Model",
+      huggingFaceModelTooltip:
+        "Search Hugging Face models or pick from our recommended list.",
+      searchModels: "Search models...",
+      searching: "Searching...",
+      noModelsFound: "No models found",
+      needsVram: "Needs ~{vram}GB VRAM (GPU: {gpu}GB)",
+      tightVram: "~{vram}GB VRAM (tight fit on {gpu}GB)",
+      vramEstimate: "~{vram}GB VRAM",
+      method: "Method",
+      methodTooltip:
+        "QLoRA uses 4-bit quantization for lowest VRAM. LoRA uses 16-bit. Full updates all weights. CPT (Continued Pretraining) trains on raw text to adapt the model to a new domain without chat formatting.",
+      readMore: "Read more",
+      fullFineTune: "Full Fine-tune",
+      checkingToken: "Checking token...",
+      getOrUpdateToken: "Get or update token",
+      huggingFaceTokenOptional: "Hugging Face Token (Optional)",
+      continuedPretraining: "Continued Pretraining",
+      localModels: "Local models",
+      localModelsFound: "{count} local/cached models found",
+      loadingLocalModels: "Loading local models...",
+    },
+    dataset: {
+      title: "Dataset",
+      description: "Select or upload training data",
+      source: "Dataset source",
+      chooseDataset: "Choose dataset",
+      chooseDatasetTooltip:
+        "Use the popup tabs to switch between Hugging Face and local recipe outputs.",
+      localTab: "Local",
+      searchHuggingFaceDatasets: "Search Hugging Face datasets...",
+      searchLocalDatasets: "Search local datasets...",
+      searching: "Searching...",
+      noDatasetsFound: "No datasets found",
+      loadingLocalDatasets: "Loading local datasets...",
+      failedToLoadLocalDatasets: "Failed to load local datasets.",
+      noLocalDatasetsYet: "No local datasets yet.",
+      noLocalDatasetsMatchSearch: "No local datasets match search.",
+      openDataRecipes: "Open Data Recipes",
+      browsingSource:
+        "Browsing {browsing}. Current selection stays {current}.",
+      localDatasets: "Local datasets",
+      localDataset: "Local dataset",
+      localDatasetRows: " / {count} rows",
+      huggingFaceDataset: "Hugging Face Dataset",
+      localDatasetMetadata: "Local dataset metadata",
+      dataRecipeOutput: "Data Recipe output.",
+      rows: "Rows",
+      columns: "Columns",
+      batches: "Batches",
+      updated: "Updated",
+      evalDataset: "Eval dataset",
+      uploading: "Uploading...",
+      upload: "Upload",
+      uploadEvalFile: "Upload eval file",
+      evalDatasetDescription:
+        "Optional. If not provided, a small portion will be split from the training data.",
+      advanced: "Advanced",
+      targetFormat: "Target Format",
+      targetFormatTooltip:
+        "Format of your training data. Auto-detect works for most datasets.",
+      auto: "Auto",
+      rawText: "Raw Text",
+      trainSplitStart: "Train Split Start",
+      trainSplitStartTooltip:
+        "Only train on a subset of your training split by specifying a start row index (inclusive, 0-based). Leave empty to start from the first row.",
+      trainSplitEnd: "Train Split End",
+      trainSplitEndTooltip:
+        "Last row index to include from the training split (inclusive, 0-based). For example, set Start to 0 and End to 99 to train on the first 100 rows. Leave empty to use all remaining rows.",
+      endPlaceholder: "End",
+      clear: "Clear",
+      dropFileOrClick: "Drop 1 file here or click to upload",
+      viewDataset: "View dataset",
+      uploadFailed: "Upload failed",
+      unknownError: "Unknown error",
+      unsupportedFileType: "Unsupported file type",
+      uploadOneFileType: "Upload one {types} file.",
+      datasetUploaded: "Dataset uploaded",
+      evalDatasetUploaded: "Eval dataset uploaded",
+      uploadOneFileAtATime: "Upload one file at a time",
+      uploadSingleFileDescription:
+        "Training dataset upload accepts a single file.",
+      checkingToken: "Checking token...",
+      getOrUpdateToken: "Get or update token",
+      preview: "Preview dataset",
+      split: "Split",
+      subset: "Subset",
+    },
+    params: {
+      title: "Parameters",
+      description: "Configure training hyperparameters",
+      loraSettings: "LoRA Settings",
+      trainingHyperparameters: "Training Hyperparameters",
+      maxSteps: "Max Steps",
+      epochs: "Epochs",
+      useMaxSteps: "Use Max Steps",
+      useEpochs: "Use Epochs",
+      maxStepsTooltip: "Override total optimizer steps.",
+      epochsTooltip: "Number of full passes over the dataset.",
+      epochsDescription: "Each epoch is one full pass over your dataset.",
+      maxStepsDescription: "Limits training to a fixed number of optimizer steps.",
+      contextLength: "Context Length",
+      contextLengthTooltip: "Maximum number of tokens per training sample.",
+      customContextLength: "Enter a custom value",
+      contextLengthDescription: "Max sequence length for training samples",
+      learningRate: "Learning Rate",
+      learningRateTooltip:
+        "Step size for weight updates. Lower values train slower but more stably.",
+      learningRateDescription:
+        "Recommended: 2e-4 for LoRA, 5e-5 for CPT, 2e-5 for full fine-tune",
+      embeddingLearningRate: "Embedding Learning Rate",
+      embeddingLearningRateTooltip:
+        "Only used when CPT is training embed_tokens. Embeddings are easier to destabilize than LoRA weights, so they usually need a smaller LR. Leave blank to use lr/10; typical working range is 2x-10x smaller than the main LR. Increase it only if vocabulary or domain-token adaptation is too slow.",
+      embeddingLearningRateDescription:
+        "Leave blank to use lr/10 (recommended). Typical range is 2x-10x smaller than the main learning rate.",
+      rank: "Rank",
+      rankTooltip: "Dimension of the low-rank matrices. Higher = more capacity.",
+      alpha: "Alpha",
+      alphaTooltip: "Scaling factor for LoRA updates. Usually 2x rank.",
+      dropout: "Dropout",
+      dropoutTooltip: "Dropout probability for LoRA layers to reduce overfitting.",
+      visionLayers: "Vision layers",
+      languageLayers: "Language layers",
+      attentionModules: "Attention modules",
+      mlpModules: "MLP modules",
+      targetModules: "Target Modules",
+      enableLora: "Enable LoRA",
+      trainWithLora: "Train with LoRA",
+      stableRank: "Stable Rank",
+      memoryEfficient: "Memory Efficient",
+      optimization: "Optimization",
+      schedule: "Schedule",
+      memory: "Memory",
+      optimizer: "Optimizer",
+      optimizerTooltip:
+        "Optimization algorithm. 8-bit variants reduce memory usage. Fused is recommended for vision models.",
+      lrScheduler: "LR scheduler",
+      lrSchedulerTooltip:
+        "How the learning rate changes over training. Linear decays steadily; cosine decays in a curve.",
+      optimizerOptions: {
+        adamw8bit: "AdamW 8-bit",
+        pagedAdamw8bit: "Paged AdamW 8-bit",
+        adamwBnb8bit: "AdamW BNB 8-bit",
+        pagedAdamw32bit: "Paged AdamW 32-bit",
+        adamwTorch: "AdamW (PyTorch)",
+        adamwTorchFused: "AdamW (PyTorch Fused)",
+      },
+      lrSchedulerOptions: {
+        linear: "Linear",
+        cosine: "Cosine",
+      },
+      batchSize: "Batch Size",
+      batchSizeTooltip: "Samples processed per step. Higher uses more VRAM.",
+      gradAccum: "Grad Accum",
+      gradAccumTooltip: "Simulates larger batch sizes without extra VRAM.",
+      weightDecay: "Weight Decay",
+      weightDecayTooltip: "L2 regularization to prevent overfitting.",
+      warmupSteps: "Warmup Steps",
+      warmupStepsTooltip: "Gradually increase LR at training start for stability.",
+      scheduleEpochsTooltip:
+        "Number of full passes over the dataset. Set 0 to run by max steps.",
+      saveSteps: "Save Steps",
+      saveStepsTooltip: "Save a checkpoint every N steps. 0 to disable.",
+      evalSteps: "Eval Steps",
+      evalStepsTooltip:
+        "Fraction of total training steps between evaluations (0-1). Set to 0 to disable evaluation. E.g. 0.01 = evaluate every 1% of steps.",
+      seed: "Seed",
+      seedTooltip: "Random seed for reproducibility.",
+      gradCheckpoint: "Grad Checkpoint",
+      gradCheckpointTooltip:
+        "Trade compute for memory by recomputing activations.",
+      none: "None",
+      standard: "Standard",
+      enablePacking: "Enable packing",
+      assistantCompletionsOnly: "Assistant completions only",
+      readMore: "Read more",
+    },
+    training: {
+      title: "Training",
+      description: "Monitor and control training",
+      chartNoDataTitle: "No training data yet",
+      chartNoDataDescription: "Start training to see loss progress",
+      startTraining: "Start Training",
+      starting: "Starting...",
+      loadingModel: "Loading model...",
+      checkingDataset: "Checking dataset...",
+      configLabel: "Training Config",
+      upload: "Upload",
+      uploadConfigTooltip: "Load a saved YAML config",
+      save: "Save",
+      saveConfigTooltip: "Download current config as YAML",
+      reset: "Reset",
+      resetConfigTooltip: "Reset to model defaults",
+      configLoaded: "Config loaded",
+      failedToLoadConfig: "Failed to load config",
+      invalidYamlFile: "Invalid YAML file",
+      failedToReadFile: "Failed to read file",
+      parametersReset: "Parameters reset to model defaults",
+      audioIncompatible:
+        "This model does not support audio. Switch to an audio-capable model or choose a non-audio dataset.",
+      visionIncompatible:
+        "Text model is not compatible with a multimodal dataset. Switch to a vision model or choose a text-only dataset.",
+      cancelTitle: "Cancel Training",
+      cancelDescription: "Do you want to cancel the current training run?",
+      continueAction: "Continue Training",
+      cancelAction: "Cancel Training",
+      stopTitle: "Stop Training",
+      stopDescription: "Choose how you want to stop the current training run.",
+      stopAction: "Stop",
+      stopping: "Stopping...",
+      stopAndSave: "Stop and Save",
+      compareInChat: "Compare in Chat",
+      exportModel: "Export Model",
+      milestone: "Milestone",
+      halfwayDone: "Halfway done. Training is past 50%.",
+      doneNextStep: "Training done. Next step: compare base vs fine-tuned outputs.",
+    },
+    history: {
+      title: "History",
+      emptyTitle: "No training runs yet",
+      emptyDescription:
+        "No training runs yet. Start your first training run in the Configure tab.",
+      loadError: "Failed to load training runs",
+      deleteError: "Failed to delete training run. Please try again.",
+      retry: "Retry",
+      loadMore: "Load more",
+      loading: "Loading...",
+      loadingRun: "Loading training run...",
+      runNotFound: "Run not found",
+      deleteTitle: "Delete training run?",
+      deleteDescription:
+        "This will permanently delete this training run and all its metrics. This action cannot be undone.",
+      runCount: "{count} runs",
+      oneRun: "1 run",
+      resume: "Resume",
+      resumeTraining: "Resume training",
+      resuming: "Resuming...",
+      deleteRun: "Delete run",
+      loss: "Loss",
+      steps: "Steps",
+      lossTrendSparkline: "Loss trend sparkline",
+      relativeJustNow: "just now",
+      relativeMinutesAgo: "{count}m ago",
+      relativeHoursAgo: "{count}h ago",
+      relativeDaysAgo: "{count}d ago",
+      status: {
+        completed: "Completed",
+        stopped: "Stopped",
+        error: "Error",
+        running: "Running",
+        continued: "Continued",
+      },
+      message: {
+        completed: "Training completed",
+        stopped: "Training stopped",
+        running: "Training in progress",
+        errored: "Training errored",
+      },
+    },
+    charts: {
+      settings: "Chart Settings",
+      settingsDescription: "Tune chart presentation while training keeps running.",
+      openSettings: "Open chart settings",
+      viewWindow: "View window",
+      viewWindowDescription: "Show latest steps only or the full history.",
+      window: "Window",
+      all: "All",
+      trainingLoss: "Training Loss",
+      trainingLossDescription: "Control overlays and EMA smoothing.",
+      smoothing: "Smoothing",
+      smoothingDescription: "Move right for more smoothing. `0` = raw.",
+      showRawLoss: "Show raw loss",
+      showSmoothedLoss: "Show smoothed loss",
+      showAverageLine: "Show average line",
+      scaleAndCleanup: "Scale and cleanup",
+      linear: "Linear",
+      log: "Log",
+      noClip: "No clip",
+      clipP99: "Clip p99",
+      clipP95: "Clip p95",
+      lossAxis: "Loss axis",
+      gradientNormAxis: "Gradient norm axis",
+      learningRateAxis: "Learning rate axis",
+      resetDefaults: "Reset defaults",
+      loss: "Loss",
+      smoothed: "Smoothed",
+      evalLoss: "Eval Loss",
+      learningRate: "Learning Rate",
+      lr: "LR",
+      gradNorm: "Grad Norm",
+      gradientNorm: "Gradient Norm",
+      step: "Step {step}",
+      averageValue: "avg {value}",
+      waitingForFirstEvaluationStep: "Waiting for first evaluation step...",
+      evaluationNotConfigured: "Evaluation not configured",
+      evalChartWillAppear: "Chart will appear once eval_steps is reached",
+      setEvalDatasetAndSteps: "Set eval dataset & eval_steps to track eval loss",
+    },
+    progress: {
+      title: "Training Progress",
+      liveMetrics: "Live training metrics",
+      openConfig: "Open training config",
+      configLabel: "Training Config",
+      hyperparams: "Hyperparams",
+      epochs: "Epochs",
+      batchSize: "Batch size",
+      learningRate: "Learning rate",
+      optimizer: "Optimizer",
+      maxSteps: "Max steps",
+      contextLength: "Context length",
+      warmupSteps: "Warmup steps",
+      rank: "Rank",
+      alpha: "Alpha",
+      dropout: "Dropout",
+      variant: "Variant",
+      epoch: "Epoch {value}",
+      percentComplete: "{percent}% complete",
+      stepProgress: "Step {current} / {total}",
+      loss: "Loss",
+      lr: "LR",
+      gradNorm: "Grad Norm",
+      model: "Model",
+      method: "Method",
+      elapsed: "Elapsed: {value}",
+      eta: "ETA: {value}",
+      stepsPerSecond: "{value} steps/s",
+      noStepsPerSecond: "-- steps/s",
+      tokens: "Tokens: {value}",
+      gpuMonitor: "GPU Monitor",
+      live: "Live",
+      utilization: "Utilization",
+      temperature: "Temperature",
+      vram: "VRAM",
+      power: "Power",
+      phase: {
+        idle: "Idle",
+        downloadingModel: "Downloading model",
+        downloadingDataset: "Downloading dataset",
+        loadingModel: "Loading model",
+        loadingDataset: "Loading dataset",
+        configuring: "Configuring",
+        training: "Training",
+        completed: "Completed",
+        error: "Error",
+        stopped: "Stopped",
+      },
+    },
+    trainingStart: {
+      ready: "Ready",
+      downloading: "Downloading",
+      preparing: "Preparing",
+      left: "{eta} left",
+      downloaded: "{size} downloaded",
+      terminalStart: "> unsloth training starts...",
+      preparingResources: "> Preparing model and dataset...",
+      gettingReady: "> We are getting everything ready for your run...",
+      waitingForFirstStep: "> {message} | waiting for first step... ({step})",
+      resumingTraining: "Resuming training...",
+      startingTraining: "starting training...",
+      dataset: "Dataset",
+      modelWeights: "Model weights",
+    },
+    tour: {
+      guidedTour: "Guided Tour",
+    },
+  },
+} as const;
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
new file mode 100644
index 0000000000..4074a5760b
--- /dev/null
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -0,0 +1,712 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { DeepPartialMessageTree } from "../types";
+import type { en } from "./en";
+
+export const zhCN = {
+  common: {
+    cancel: "取消",
+    close: "关闭",
+    delete: "删除",
+    done: "完成",
+    error: "错误",
+    export: "导出",
+    help: "帮助",
+    loading: "加载中...",
+    new: "新增",
+    rename: "重命名",
+    save: "保存",
+    search: "搜索",
+    shutdown: "关闭服务",
+  },
+  shell: {
+    accountMenu: "{name} 账号菜单",
+    aria: {
+      home: "Unsloth 首页",
+      closeSidebar: "关闭侧边栏",
+      openSidebar: "打开侧边栏",
+      chatOptions: "聊天选项",
+      runOptions: "训练选项",
+    },
+    navigation: {
+      newChat: "新聊天",
+      compare: "对比",
+      search: "搜索",
+      train: "训练",
+      recipes: "配方",
+      export: "导出",
+      recents: "最近",
+      settings: "设置",
+      api: "API",
+      lightMode: "浅色模式",
+      darkMode: "深色模式",
+      guidedTour: "引导教程",
+      help: "帮助",
+      logOut: "退出登录",
+      shutdown: "关闭服务",
+    },
+    notFound: {
+      title: "页面未找到",
+      description: "{path} 不存在。",
+      backToChat: "返回聊天",
+    },
+    dialog: {
+      deleteChat: {
+        title: "删除聊天",
+        description: "确定要删除聊天“{name}”吗？",
+      },
+      deleteRun: {
+        title: "删除训练运行",
+        description: "确定要删除运行“{name}”吗？",
+      },
+      renameChat: {
+        title: "重命名聊天",
+        placeholder: "聊天标题",
+      },
+      renameRun: {
+        title: "重命名运行",
+        placeholder: "运行名称",
+      },
+    },
+    toast: {
+      cannotDeleteRunningRun: "不能删除正在运行的训练",
+      failedToDeleteChat: "删除聊天失败",
+      failedToDeleteRun: "删除运行失败",
+      failedToRenameChat: "重命名聊天失败",
+      failedToRenameRun: "重命名运行失败",
+    },
+  },
+  settings: {
+    title: "设置",
+    dialog: {
+      title: "设置",
+      description: "管理你的 Unsloth Studio 偏好设置。",
+      closeAriaLabel: "关闭设置",
+    },
+    tabs: {
+      general: "通用",
+      profile: "个人资料",
+      appearance: "外观",
+      chat: "聊天",
+      connections: "连接",
+      apiKeys: "API",
+      about: "帮助",
+    },
+    general: {
+      title: "通用",
+      description: "Unsloth Studio 的全局偏好设置。",
+      account: "账号",
+      huggingFaceToken: "Hugging Face token",
+      huggingFaceTokenDescription: "用于加载受限模型和推送产物。",
+      hideToken: "隐藏 token",
+      showToken: "显示 token",
+      chatDefaults: "聊天默认设置",
+      autoTitleNewChats: "自动为新聊天命名",
+      autoTitleNewChatsDescription: "根据第一条消息生成简短标题。",
+      gettingStarted: "入门",
+      startOnboarding: "开始引导",
+      startOnboardingDescription: "重新打开设置向导，不会更改你的账号。",
+      startOnboardingAction: "开始引导",
+      resetPreferences: {
+        sectionTitle: "危险区域",
+        label: "重置所有本地偏好设置",
+        description:
+          "清除仅保存在本地的偏好设置。聊天、API 访问权限和数据库中的聊天设置不会受到影响。",
+        action: "重置偏好设置",
+        confirmTitle: "重置所有本地偏好设置？",
+        confirmDescription:
+          "这会清除仅保存在本地的偏好设置，然后重新加载 Studio。聊天、API 访问权限和数据库中的聊天设置不会受到影响。",
+        confirmAction: "重置并重新加载",
+      },
+    },
+    profile: {
+      title: "个人资料",
+      description: "更新你在 Studio 中显示的个人资料。",
+      changePicture: "更换头像",
+      displayName: "显示名称",
+      nameSaved: "个人资料名称已保存",
+      namePersistErrorTitle: "无法持久保存个人资料名称",
+      namePersistErrorDescription:
+        "名称已在本次会话中更新，但重新加载后可能不会保留。",
+      photoUpdated: "头像已更新",
+      photoPersistErrorTitle: "无法持久保存头像",
+      photoPersistErrorDescription:
+        "头像已在本次会话中更新，但重新加载后可能不会保留。",
+      photoUpdateErrorTitle: "无法更新头像",
+      imageUseError: "无法使用这张图片。",
+    },
+    appearance: {
+      title: "外观",
+      description: "调整 Unsloth Studio 在此设备上的显示方式。",
+      language: {
+        title: "语言",
+        label: "显示语言",
+        description: "选择 Studio 使用的语言。",
+      },
+      theme: {
+        title: "主题",
+        label: "颜色主题",
+        description: "选择浅色、深色，或跟随系统。",
+        system: "跟随系统",
+        light: "浅色",
+        dark: "深色",
+      },
+      layout: {
+        title: "布局",
+        compactSidebar: "默认固定侧边栏",
+        compactSidebarDescription: "保持侧边栏展开，而不是折叠为图标。",
+      },
+    },
+    chat: {
+      title: "聊天",
+      description: "管理此设备上保存的聊天记录。",
+      data: "数据",
+      exportHistory: "导出聊天记录",
+      exportHistoryDescription: "将所有聊天和消息下载为 JSON 文件。",
+      exportAction: "导出",
+      exportingAction: "导出中...",
+      clearHistory: "清除聊天记录",
+      clearHistoryDescription: "从此设备删除本地聊天记录。",
+      clearAction: "清除",
+      clearAllChats: "清除所有聊天",
+      clearAllChatsDescription: "永久删除此设备上的每个聊天。",
+      noChatsToClear: "没有可清除的聊天。",
+      clearOneChatDescription: "永久删除此设备上的唯一一个聊天。",
+      clearChatCountDescription: "永久删除此设备上的 {count} 个聊天。",
+      clearChatsAction: "清除聊天",
+      clearOneChatTitle: "清除 1 个聊天？",
+      clearChatsTitle: "清除 {count} 个聊天？",
+      clearChatsConfirmDescription:
+        "这会永久删除此设备上保存的每个聊天和消息。此操作无法撤销。",
+      clearingAction: "清除中...",
+      clearOneChatAction: "清除 1 个聊天",
+      clearChatCountAction: "清除 {count} 个聊天",
+      clearedAllChats: "已清除所有聊天",
+      clearedOneChat: "已清除 1 个聊天",
+      clearedChatCount: "已清除 {count} 个聊天",
+      someChatsCouldNotBeCleared: "部分聊天无法清除",
+      chatsClearedRemainOne:
+        "已清除 {clearedCount} 个聊天；仍有 1 个聊天保留。请重试。",
+      chatsClearedRemain:
+        "已清除 {clearedCount} 个聊天；仍有 {remainingCount} 个聊天保留。请重试。",
+      oneChatClearedRemain:
+        "已清除 1 个聊天；仍有 {remainingCount} 个聊天保留。请重试。",
+      oneChatClearedRemainOne: "已清除 1 个聊天；仍有 1 个聊天保留。请重试。",
+      storageClearFailedOne:
+        "某个存储位置清除失败；可能仍有 1 个聊天保留。请重试。",
+      storageClearFailed:
+        "某个存储位置清除失败；可能仍有 {count} 个聊天保留。请重试。",
+      failedToClearChats: "清除聊天失败",
+    },
+    connections: {
+      title: "连接",
+      description: "管理提供方和外部服务的连接。",
+    },
+    apiKeys: {
+      title: "API",
+      description: "通过兼容 OpenAI 的 API 以编程方式访问 Unsloth。",
+      readDocs: "阅读 API 文档",
+      noAccess: "还没有 API 访问权限。",
+      newBadge: "新",
+      accessTokens: "访问 token",
+      loadError: "无法加载 API 访问权限。",
+      createError: "无法创建访问 token。",
+      revokeError: "无法撤销访问 token。",
+      never: "永不过期",
+      tokenNamePlaceholder: "Token 名称（例如 production）",
+      newAccessTokenName: "新的访问 token 名称",
+      createToken: "创建 token",
+      creating: "创建中...",
+      newTokenCreated: "新的访问 token 已创建",
+      accessTokenCopied: "访问 token 已复制",
+      copyAccessToken: "复制访问 token",
+      copyNow: "现在复制 - 之后不会再次显示。",
+      usageExamples: "使用示例",
+      usageTools: "工具",
+      copySnippet: "复制代码片段",
+      copy: "复制",
+      copied: "已复制",
+      setupDocs: "设置文档：",
+      relativeNever: "从未",
+      relativeJustNow: "刚刚",
+      relativeHoursAgo: "{count} 小时前",
+      relativeDaysAgo: "{count} 天前",
+      relativeMonthsAgo: "{count} 个月前",
+      relativeYearsAgo: "{count} 年前",
+      expired: "已过期",
+      today: "今天",
+      inDays: "{count} 天后",
+      created: "创建于 {value}",
+      used: "使用于 {value}",
+      expires: "过期时间 {value}",
+      actionsFor: "{name} 的操作",
+      copyPrefix: "复制前缀",
+      revokeToken: "撤销 token",
+      revokeTitle: "撤销访问 token \"{name}\"？",
+      revokeDescription:
+        "使用此 token 的应用会立即失去访问权限。此操作无法撤销。",
+      revokeAction: "撤销 \"{name}\"",
+      revoking: "撤销中...",
+    },
+    about: {
+      title: "帮助",
+      description: "文档、发布说明、反馈和 Studio 构建信息。",
+      studioVersion: "Studio 版本",
+      packageVersion: "包版本",
+      updates: "更新",
+      help: "帮助",
+      documentation: "文档",
+      releaseNotes: "发布说明",
+      whatsNew: "最新内容",
+      feedback: "反馈",
+      reportIssue: "报告问题",
+      dangerZone: "危险区域",
+      shutDownStudio: "关闭 Unsloth Studio",
+      shutDownStudioDescription: "停止 Studio 服务进程并结束你的会话。",
+      shutDown: "关闭",
+      update: {
+        title: "更新 Unsloth Studio",
+        openPowerShell: "打开 PowerShell 并运行：",
+        openTerminal: "打开终端并运行：",
+        commandText: "{label} 文本",
+        copied: "已复制",
+        copyCommand: "复制命令",
+        commandCopied: "{label} 已复制",
+        copyNamedCommand: "复制 {label}",
+        checkingInstall: "正在检查 Studio 的安装方式...",
+        localInstallDetected:
+          "检测到源码或本地安装。为避免替换为 PyPI 版本，请从最初安装时使用的 checkout 或源码位置更新。",
+        pullThenUpdate:
+          "从你的 Unsloth 仓库 checkout 拉取最新变更，然后本地更新 Studio：",
+        gitPullCommand: "git pull 命令",
+        localUpdateCommand: "本地更新命令",
+        localInstallerFallback:
+          "如果 Studio 更新命令不可用，请从该 checkout 运行本地安装器：",
+        localInstallerCommand: "本地安装器命令",
+        sourceInstallDetected:
+          "这看起来是源码或 VCS 包安装。请从最初使用的本地路径或 Git URL 重新安装。",
+        repoCheckoutFallback:
+          "如果你仍保留 Unsloth 仓库 checkout，请从该 checkout 运行本地安装器：",
+        restartAfterUpdate: "更新后重启 Studio，使变更生效。",
+        unknownInstall:
+          "Studio 无法检测安装方式。请先确认你如何安装 Studio，然后选择匹配的更新方式。",
+        curlOrPypi: "对于 curl 或 PyPI 安装，请运行：",
+        updateCommand: "更新命令",
+        localCheckout:
+          "对于本地 checkout 安装，请改为从该 checkout 更新并使用本地更新命令：",
+        fallbackInstruction:
+          "如果失败，或 unsloth studio update 不可用，请运行：",
+        fallbackCommand: "备用命令",
+      },
+    },
+  },
+  studio: {
+    routeTitle: "训练",
+    title: "微调工作台",
+    subtitles: {
+      configure: "配置并开始训练",
+      trainingInProgress: "训练进行中",
+      viewPastRuns: "查看历史训练",
+      viewingPastRun: "正在查看历史训练",
+    },
+    tabs: {
+      configure: "配置",
+      currentRun: "当前训练",
+      history: "历史",
+    },
+    loadingRuntime: "正在加载训练运行时...",
+    backToHistory: "返回历史",
+    sections: {
+      model: "模型",
+      dataset: "数据集",
+      params: "参数",
+      training: "训练",
+      charts: "图表",
+      progress: "训练进度",
+    },
+    configure: {
+      title: "配置",
+      description: "选择模型、数据集和训练设置。",
+      startTraining: "开始训练",
+      starting: "启动中...",
+      loadingModel: "正在加载模型...",
+      checkingDataset: "正在检查数据集...",
+      trainingConfig: "训练配置",
+    },
+    model: {
+      title: "模型",
+      description: "选择基础模型和训练方法",
+      fasterTrainingBadge: "训练速度提升 2 倍",
+      baseModel: "基础模型",
+      localModel: "本地模型",
+      localModelTooltip: "本地已下载模型的路径，或自定义 HF 仓库。",
+      scanningLocalAndCachedModels: "正在扫描本地和缓存模型...",
+      scanning: "正在扫描...",
+      scanningLocalModels: "正在扫描本地模型...",
+      noLocalModelsFound: "未找到本地模型",
+      noLocalModelsFoundManual: "未找到本地模型。请手动输入路径。",
+      failedToLoadLocalModels: "加载本地模型失败",
+      hfCache: "HF 缓存",
+      customFolders: "自定义文件夹",
+      localDir: "本地目录",
+      huggingFaceModel: "Hugging Face 模型",
+      huggingFaceModelTooltip: "搜索 Hugging Face 模型，或从推荐列表中选择。",
+      searchModels: "搜索模型...",
+      searching: "搜索中...",
+      noModelsFound: "未找到模型",
+      needsVram: "约需 {vram}GB 显存（GPU：{gpu}GB）",
+      tightVram: "约 {vram}GB 显存（在 {gpu}GB 上偏紧）",
+      vramEstimate: "约 {vram}GB 显存",
+      method: "方法",
+      methodTooltip:
+        "QLoRA 使用 4 位量化以最大限度降低显存。LoRA 使用 16 位。Full 会更新所有权重。CPT（持续预训练）在原始文本上训练，使模型适配新领域，不使用聊天格式。",
+      readMore: "了解更多",
+      fullFineTune: "全量微调",
+      checkingToken: "正在检查 token...",
+      getOrUpdateToken: "获取或更新 token",
+      huggingFaceTokenOptional: "Hugging Face Token（可选）",
+      continuedPretraining: "持续预训练",
+      localModels: "本地模型",
+      localModelsFound: "找到 {count} 个本地/缓存模型",
+      loadingLocalModels: "正在加载本地模型...",
+    },
+    dataset: {
+      title: "数据集",
+      description: "选择或上传训练数据",
+      source: "数据集来源",
+      chooseDataset: "选择数据集",
+      chooseDatasetTooltip:
+        "通过弹出标签切换 Hugging Face 与本地数据配方输出。",
+      localTab: "本地",
+      searchHuggingFaceDatasets: "搜索 Hugging Face 数据集...",
+      searchLocalDatasets: "搜索本地数据集...",
+      searching: "搜索中...",
+      noDatasetsFound: "未找到数据集",
+      loadingLocalDatasets: "正在加载本地数据集...",
+      failedToLoadLocalDatasets: "加载本地数据集失败。",
+      noLocalDatasetsYet: "还没有本地数据集。",
+      noLocalDatasetsMatchSearch: "没有本地数据集匹配搜索。",
+      openDataRecipes: "打开数据配方",
+      browsingSource: "正在浏览 {browsing}。当前选择仍保持为 {current}。",
+      localDatasets: "本地数据集",
+      localDataset: "本地数据集",
+      localDatasetRows: " / {count} 行",
+      huggingFaceDataset: "Hugging Face 数据集",
+      localDatasetMetadata: "本地数据集元数据",
+      dataRecipeOutput: "数据配方输出。",
+      rows: "行",
+      columns: "列",
+      batches: "批次",
+      updated: "更新时间",
+      evalDataset: "评估数据集",
+      uploading: "上传中...",
+      upload: "上传",
+      uploadEvalFile: "上传评估文件",
+      evalDatasetDescription:
+        "可选。如果未提供，将从训练数据中切分出一小部分。",
+      advanced: "高级",
+      targetFormat: "目标格式",
+      targetFormatTooltip:
+        "训练数据的格式。自动检测对大多数数据集都有效。",
+      auto: "自动",
+      rawText: "原始文本",
+      trainSplitStart: "训练切分起始",
+      trainSplitStartTooltip:
+        "通过指定起始行索引（含，从 0 开始）仅在训练切分的子集上训练。留空则从第一行开始。",
+      trainSplitEnd: "训练切分结束",
+      trainSplitEndTooltip:
+        "训练切分中包含的最后一行索引（含，从 0 开始）。例如将起始设为 0、结束设为 99，可在前 100 行上训练。留空则使用所有剩余行。",
+      endPlaceholder: "结束",
+      clear: "清除",
+      dropFileOrClick: "拖放 1 个文件到此处，或点击上传",
+      viewDataset: "查看数据集",
+      uploadFailed: "上传失败",
+      unknownError: "未知错误",
+      unsupportedFileType: "不支持的文件类型",
+      uploadOneFileType: "上传一个 {types} 文件。",
+      datasetUploaded: "数据集已上传",
+      evalDatasetUploaded: "评估数据集已上传",
+      uploadOneFileAtATime: "一次只能上传一个文件",
+      uploadSingleFileDescription: "训练数据集上传只接受单个文件。",
+      checkingToken: "正在检查 token...",
+      getOrUpdateToken: "获取或更新 token",
+      preview: "预览数据集",
+      split: "切分",
+      subset: "子集",
+    },
+    params: {
+      title: "参数",
+      description: "配置训练超参数",
+      loraSettings: "LoRA 设置",
+      trainingHyperparameters: "训练超参数",
+      maxSteps: "最大步数",
+      epochs: "轮数",
+      useMaxSteps: "使用最大步数",
+      useEpochs: "使用轮数",
+      maxStepsTooltip: "覆盖优化器总步数。",
+      epochsTooltip: "完整遍历数据集的次数。",
+      epochsDescription: "每个 epoch 是对数据集的一次完整遍历。",
+      maxStepsDescription: "将训练限制为固定数量的优化器步数。",
+      contextLength: "上下文长度",
+      contextLengthTooltip: "每个训练样本的最大 token 数。",
+      customContextLength: "输入自定义值",
+      contextLengthDescription: "训练样本的最大序列长度",
+      learningRate: "学习率",
+      learningRateTooltip: "权重更新步长。较低的值训练更慢但更稳定。",
+      learningRateDescription:
+        "推荐值：LoRA 用 2e-4，CPT 用 5e-5，全量微调用 2e-5",
+      embeddingLearningRate: "Embedding 学习率",
+      embeddingLearningRateTooltip:
+        "仅在 CPT 训练 embed_tokens 时使用。Embedding 比 LoRA 权重更易失稳，通常需要更小的学习率。留空则使用 lr/10；常用区间是比主学习率小 2 至 10 倍。仅在词表或领域 token 适配过慢时才提高。",
+      embeddingLearningRateDescription:
+        "留空使用 lr/10（推荐）。常用区间是比主学习率小 2 至 10 倍。",
+      rank: "Rank",
+      rankTooltip: "低秩矩阵的维度。越高容量越大。",
+      alpha: "Alpha",
+      alphaTooltip: "LoRA 更新的缩放因子。通常为 Rank 的 2 倍。",
+      dropout: "Dropout",
+      dropoutTooltip: "LoRA 层的 dropout 概率，用于减少过拟合。",
+      visionLayers: "视觉层",
+      languageLayers: "语言层",
+      attentionModules: "注意力模块",
+      mlpModules: "MLP 模块",
+      targetModules: "目标模块",
+      enableLora: "启用 LoRA",
+      trainWithLora: "使用 LoRA 训练",
+      stableRank: "稳定 Rank",
+      memoryEfficient: "节省内存",
+      optimization: "优化",
+      schedule: "计划",
+      memory: "内存",
+      optimizer: "优化器",
+      optimizerTooltip:
+        "优化算法。8 位变体可降低内存占用。对视觉模型推荐 Fused。",
+      lrScheduler: "LR 调度器",
+      lrSchedulerTooltip:
+        "学习率随训练变化的方式。Linear 平稳衰减；Cosine 曲线衰减。",
+      optimizerOptions: {
+        adamw8bit: "AdamW 8-bit",
+        pagedAdamw8bit: "Paged AdamW 8-bit",
+        adamwBnb8bit: "AdamW BNB 8-bit",
+        pagedAdamw32bit: "Paged AdamW 32-bit",
+        adamwTorch: "AdamW（PyTorch）",
+        adamwTorchFused: "AdamW（PyTorch Fused）",
+      },
+      lrSchedulerOptions: {
+        linear: "线性",
+        cosine: "余弦",
+      },
+      batchSize: "批大小",
+      batchSizeTooltip: "每步处理的样本数。越高占用越多显存。",
+      gradAccum: "梯度累积",
+      gradAccumTooltip: "在不增加显存的情况下模拟更大的批大小。",
+      weightDecay: "权重衰减",
+      weightDecayTooltip: "L2 正则化，用于防止过拟合。",
+      warmupSteps: "预热步数",
+      warmupStepsTooltip: "在训练开始时逐步提高学习率，提升稳定性。",
+      scheduleEpochsTooltip:
+        "完整遍历数据集的次数。设为 0 则按最大步数运行。",
+      saveSteps: "保存步数",
+      saveStepsTooltip: "每 N 步保存一次检查点。0 表示禁用。",
+      evalSteps: "评估步数",
+      evalStepsTooltip:
+        "评估之间间隔占总训练步数的比例（0-1）。设为 0 则禁用评估。例如 0.01 = 每 1% 步评估一次。",
+      seed: "随机种子",
+      seedTooltip: "用于复现的随机种子。",
+      gradCheckpoint: "梯度检查点",
+      gradCheckpointTooltip: "通过重算激活以时间换显存。",
+      none: "无",
+      standard: "标准",
+      enablePacking: "启用 packing",
+      assistantCompletionsOnly: "仅助手回复",
+      readMore: "了解更多",
+    },
+    training: {
+      title: "训练",
+      description: "监控和控制训练",
+      chartNoDataTitle: "暂无训练数据",
+      chartNoDataDescription: "开始训练后可查看 loss 进度",
+      startTraining: "开始训练",
+      starting: "启动中...",
+      loadingModel: "正在加载模型...",
+      checkingDataset: "正在检查数据集...",
+      configLabel: "训练配置",
+      upload: "上传",
+      uploadConfigTooltip: "加载已保存的 YAML 配置",
+      save: "保存",
+      saveConfigTooltip: "将当前配置下载为 YAML",
+      reset: "重置",
+      resetConfigTooltip: "重置为模型默认值",
+      configLoaded: "配置已加载",
+      failedToLoadConfig: "加载配置失败",
+      invalidYamlFile: "无效的 YAML 文件",
+      failedToReadFile: "读取文件失败",
+      parametersReset: "参数已重置为模型默认值",
+      audioIncompatible:
+        "该模型不支持音频。请切换到支持音频的模型，或选择非音频数据集。",
+      visionIncompatible:
+        "文本模型与多模态数据集不兼容。请切换到视觉模型，或选择纯文本数据集。",
+      cancelTitle: "取消训练",
+      cancelDescription: "要取消当前训练运行吗？",
+      continueAction: "继续训练",
+      cancelAction: "取消训练",
+      stopTitle: "停止训练",
+      stopDescription: "选择如何停止当前训练运行。",
+      stopAction: "停止",
+      stopping: "停止中...",
+      stopAndSave: "停止并保存",
+      compareInChat: "在聊天中对比",
+      exportModel: "导出模型",
+      milestone: "里程碑",
+      halfwayDone: "已完成一半。训练进度超过 50%。",
+      doneNextStep: "训练完成。下一步：对比基础模型和微调模型的输出。",
+    },
+    history: {
+      title: "历史",
+      emptyTitle: "还没有训练运行",
+      emptyDescription: "还没有训练运行。请在配置标签页开始第一次训练。",
+      loadError: "加载训练运行失败",
+      deleteError: "删除训练运行失败。请重试。",
+      retry: "重试",
+      loadMore: "加载更多",
+      loading: "加载中...",
+      loadingRun: "正在加载训练运行...",
+      runNotFound: "未找到运行",
+      deleteTitle: "删除训练运行？",
+      deleteDescription: "这会永久删除该训练运行及其所有指标。此操作无法撤销。",
+      runCount: "{count} 次运行",
+      oneRun: "1 次运行",
+      resume: "继续",
+      resumeTraining: "继续训练",
+      resuming: "继续中...",
+      deleteRun: "删除运行",
+      loss: "Loss",
+      steps: "步数",
+      lossTrendSparkline: "Loss 趋势迷你图",
+      relativeJustNow: "刚刚",
+      relativeMinutesAgo: "{count} 分钟前",
+      relativeHoursAgo: "{count} 小时前",
+      relativeDaysAgo: "{count} 天前",
+      status: {
+        completed: "已完成",
+        stopped: "已停止",
+        error: "错误",
+        running: "运行中",
+        continued: "已继续",
+      },
+      message: {
+        completed: "训练已完成",
+        stopped: "训练已停止",
+        running: "训练进行中",
+        errored: "训练出错",
+      },
+    },
+    charts: {
+      settings: "图表设置",
+      settingsDescription: "训练运行时调整图表显示。",
+      openSettings: "打开图表设置",
+      viewWindow: "查看窗口",
+      viewWindowDescription: "只显示最新步数或完整历史。",
+      window: "窗口",
+      all: "全部",
+      trainingLoss: "训练损失",
+      trainingLossDescription: "控制覆盖线和 EMA 平滑。",
+      smoothing: "平滑",
+      smoothingDescription: "向右移动可增加平滑度。`0` = 原始值。",
+      showRawLoss: "显示原始 loss",
+      showSmoothedLoss: "显示平滑 loss",
+      showAverageLine: "显示平均线",
+      scaleAndCleanup: "比例和清理",
+      linear: "线性",
+      log: "对数",
+      noClip: "不裁剪",
+      clipP99: "裁剪 p99",
+      clipP95: "裁剪 p95",
+      lossAxis: "损失轴",
+      gradientNormAxis: "梯度范数轴",
+      learningRateAxis: "学习率轴",
+      resetDefaults: "恢复默认值",
+      loss: "Loss",
+      smoothed: "平滑",
+      evalLoss: "评估 Loss",
+      learningRate: "学习率",
+      lr: "LR",
+      gradNorm: "梯度范数",
+      gradientNorm: "梯度范数",
+      step: "步数 {step}",
+      averageValue: "平均 {value}",
+      waitingForFirstEvaluationStep: "等待首次评估步...",
+      evaluationNotConfigured: "未配置评估",
+      evalChartWillAppear: "达到 eval_steps 后会显示图表",
+      setEvalDatasetAndSteps: "设置评估数据集和 eval_steps 以追踪评估 loss",
+    },
+    progress: {
+      title: "训练进度",
+      liveMetrics: "实时训练指标",
+      openConfig: "打开训练配置",
+      configLabel: "训练配置",
+      hyperparams: "超参数",
+      epochs: "轮数",
+      batchSize: "批大小",
+      learningRate: "学习率",
+      optimizer: "优化器",
+      maxSteps: "最大步数",
+      contextLength: "上下文长度",
+      warmupSteps: "预热步数",
+      rank: "Rank",
+      alpha: "Alpha",
+      dropout: "Dropout",
+      variant: "变体",
+      epoch: "Epoch {value}",
+      percentComplete: "完成 {percent}%",
+      stepProgress: "步数 {current} / {total}",
+      loss: "Loss",
+      lr: "LR",
+      gradNorm: "梯度范数",
+      model: "模型",
+      method: "方法",
+      elapsed: "已用时间：{value}",
+      eta: "ETA：{value}",
+      stepsPerSecond: "{value} 步/秒",
+      noStepsPerSecond: "-- 步/秒",
+      tokens: "Tokens：{value}",
+      gpuMonitor: "GPU 监控",
+      live: "实时",
+      utilization: "利用率",
+      temperature: "温度",
+      vram: "VRAM",
+      power: "功耗",
+      phase: {
+        idle: "空闲",
+        downloadingModel: "正在下载模型",
+        downloadingDataset: "正在下载数据集",
+        loadingModel: "正在加载模型",
+        loadingDataset: "正在加载数据集",
+        configuring: "配置中",
+        training: "训练中",
+        completed: "已完成",
+        error: "错误",
+        stopped: "已停止",
+      },
+    },
+    trainingStart: {
+      ready: "就绪",
+      downloading: "下载中",
+      preparing: "准备中",
+      left: "剩余 {eta}",
+      downloaded: "已下载 {size}",
+      terminalStart: "> Unsloth 训练开始...",
+      preparingResources: "> 正在准备模型和数据集...",
+      gettingReady: "> 正在为本次运行做好准备...",
+      waitingForFirstStep: "> {message} | 等待第一步...（{step}）",
+      resumingTraining: "正在继续训练...",
+      startingTraining: "正在开始训练...",
+      dataset: "数据集",
+      modelWeights: "模型权重",
+    },
+    tour: {
+      guidedTour: "引导教程",
+    },
+  },
+} satisfies DeepPartialMessageTree<typeof en>;
diff --git a/studio/frontend/src/i18n/messages.ts b/studio/frontend/src/i18n/messages.ts
new file mode 100644
index 0000000000..e75faf697a
--- /dev/null
+++ b/studio/frontend/src/i18n/messages.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { getLocale } from "./locale-store";
+import { en } from "./locales/en";
+import { zhCN } from "./locales/zh-CN";
+import type { InterpolationValues, MessageKey } from "./types";
+
+export const LOCALES = {
+  en: { label: "English", nativeLabel: "English" },
+  "zh-CN": { label: "Chinese (Simplified)", nativeLabel: "简体中文" },
+} as const;
+
+export type Locale = keyof typeof LOCALES;
+export type TranslationKey = MessageKey<typeof en>;
+
+export const messages = { en, "zh-CN": zhCN } as const;
+
+const PLACEHOLDER_PATTERN = /\{([a-zA-Z0-9_]+)\}/g;
+
+function readMessage(tree: unknown, key: string): string | undefined {
+  let cursor = tree;
+  for (const segment of key.split(".")) {
+    if (
+      cursor === null ||
+      typeof cursor !== "object" ||
+      !Object.prototype.hasOwnProperty.call(cursor, segment)
+    ) {
+      return undefined;
+    }
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return typeof cursor === "string" ? cursor : undefined;
+}
+
+function interpolate(
+  template: string,
+  values: InterpolationValues | undefined,
+): string {
+  if (!values) return template;
+
+  return template.replace(PLACEHOLDER_PATTERN, (match, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) return match;
+    const value = values[name];
+    return value === null || value === undefined ? "" : String(value);
+  });
+}
+
+function warnMissingEnglishMessage(key: string): void {
+  if (import.meta.env.DEV) {
+    console.warn(`[i18n] Missing English translation for key "${key}".`);
+  }
+}
+
+export function translate(
+  key: TranslationKey,
+  values?: InterpolationValues,
+  locale: Locale = getLocale(),
+): string {
+  const localized = readMessage(messages[locale], key);
+  const fallback = localized ?? readMessage(messages.en, key);
+
+  if (fallback === undefined) {
+    warnMissingEnglishMessage(key);
+    return key;
+  }
+
+  return interpolate(fallback, values);
+}
+
+export function isSupportedLocale(value: unknown): value is Locale {
+  return (
+    typeof value === "string" &&
+    Object.prototype.hasOwnProperty.call(LOCALES, value)
+  );
+}
diff --git a/studio/frontend/src/i18n/types.ts b/studio/frontend/src/i18n/types.ts
new file mode 100644
index 0000000000..706c3fb1d3
--- /dev/null
+++ b/studio/frontend/src/i18n/types.ts
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export type MessageTree = {
+  readonly [key: string]: string | MessageTree;
+};
+
+export type DeepPartialMessageTree<T> = {
+  readonly [K in keyof T]?: T[K] extends string
+    ? string
+    : T[K] extends MessageTree
+      ? DeepPartialMessageTree<T[K]>
+      : never;
+};
+
+type Join<Prefix extends string, Key extends string> =
+  Prefix extends "" ? Key : `${Prefix}.${Key}`;
+
+export type MessageKey<T, Prefix extends string = ""> = {
+  [K in Extract<keyof T, string>]: T[K] extends string
+    ? Join<Prefix, K>
+    : T[K] extends MessageTree
+      ? MessageKey<T[K], Join<Prefix, K>>
+      : never;
+}[Extract<keyof T, string>];
+
+export type InterpolationValues = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
diff --git a/studio/frontend/src/main.tsx b/studio/frontend/src/main.tsx
index 0db37fdb6e..a924c1652e 100644
--- a/studio/frontend/src/main.tsx
+++ b/studio/frontend/src/main.tsx
@@ -7,6 +7,7 @@ import { createRoot } from "react-dom/client";
 import "./index.css";
 import { fetchDeviceType } from "./config/env";
 import { App } from "./app/app";
+import { initializeLocale } from "./i18n";
 
 const globalCrypto = globalThis.crypto as Crypto | undefined;
 
@@ -33,6 +34,8 @@ if (!rootElement) {
   throw new Error("Root element not found");
 }
 
+initializeLocale();
+
 fetchDeviceType().then(() => {
   createRoot(rootElement).render(
     <StrictMode>

From ca55acbb5f4d1b49fb40124ee99f6d5a1b3b1b01 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 27 May 2026 04:53:38 -0700
Subject: [PATCH 004/222] Studio: unblock install on Linux ARM64 + Windows
 ARM64 + Intel Mac (#5790)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Studio: unblock cross-platform install on Linux ARM64 + Windows ARM64

Three independent bugs that together prevent `install.sh` /
`install.ps1` from completing on the ARM machines GitHub Actions now
ships (`ubuntu-24.04-arm`, `windows-11-arm`) and on equivalent real
hosts (Ampere Altra, Raspberry Pi 5, Snapdragon X Elite, ...).

Validated on the staging-2 cross-OS smoke suite -- five per-OS
workflows pinned to `ubuntu-latest`, `ubuntu-24.04-arm`, `macos-14`,
`macos-15-intel`, `windows-11-arm`. Before this change Windows ARM
exits 1 in the winget gate and Linux ARM source-builds llama.cpp
because the prebuilt selector returns 0 attempts; with it both reach
healthy /api/health.

1. studio/install_llama_prebuilt.py -- resolve_simple_install_release_plans
   had explicit branches for windows+x86_64, macos+arm64, macos+x86_64
   and linux+x86_64 only. Upstream ggml-org/llama.cpp ships
   `llama-bNNNN-bin-ubuntu-arm64.tar.gz` and
   `llama-bNNNN-bin-win-cpu-arm64.zip` (visible in the b9334 release
   manifest), so the missing elif branches force every Linux ARM64 and
   Windows ARM64 host into a source build even when a perfectly good
   upstream prebuilt is one HTTP GET away. Two new branches mirror the
   existing CPU variants; runtime_patterns_for_choice and
   runtime_payload_health_groups gain `linux-arm64` (.so layout) and
   `windows-arm64` (.dll layout) so the health-check pass-through
   matches the asset shape.

2. studio/setup.sh -- the helper-release-repo selector routed any
   non-x86_64 Linux to `unslothai/llama.cpp`, which only publishes the
   Linux CUDA bundle set. The result on Linux ARM64 was a guaranteed
   `direct_linux_release_plan` raise of "no compatible Linux prebuilt
   asset was found" on every release in the scan, then a source-build
   fallback. Pin Linux ARM64 (CPU-only) to `ggml-org/llama.cpp` so the
   new branch in (1) can see the upstream asset. setup.ps1 already
   hardcodes `ggml-org/llama.cpp`, so Windows ARM64 picks up (1)
   without an additional change.

3. install.ps1 -- the winget pre-check hard-failed before Python or uv
   detection. `windows-11-arm` runners (and many corporate Windows
   hosts without the Microsoft Store) ship without winget but already
   have a usable Python plus the Astral uv PowerShell installer
   reachable. Demote the winget check to a soft warning, defer the
   hard failure to the Python install branch (which is the only path
   that genuinely needs winget), and let the uv install fall through
   to `https://astral.sh/uv/install.ps1` when winget is absent. The
   uv PowerShell installer was already the existing fallback for the
   "winget present but uv install failed" case; this just makes it
   the primary path on hosts without winget.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: filter torchcodec on platforms without wheels

torchcodec 0.10.0 ships wheels for manylinux_2_28_x86_64,
macosx_12_0_arm64, and win_amd64 only -- visible on its PyPI page and
in the resolver error reported by #4446. install_python_stack.py
pulls torchcodec via extras-no-deps.txt, which is now installed
unconditionally during `unsloth studio update --local` (the update
command has no --no-torch flag). Result on Linux aarch64 /
Windows ARM64 / Intel Mac (when invoked outside the install.sh
auto-skip-torch path):

  ERROR: Could not find a version that satisfies the requirement
  torchcodec==0.10.0 (from versions: 0.0.0.dev0, ...)
  ERROR: No matching distribution found for torchcodec==0.10.0
  error          Installing extras (no-deps) (pip) failed (exit code 1)

`NO_TORCH_SKIP_PACKAGES` already lists torchcodec but only fires
when NO_TORCH is true -- the update path inherits no NO_TORCH from
the original install and inferrence falls back to IS_MAC_INTEL only,
so Linux aarch64 / Windows ARM64 sail past the guard. Adds a
platform predicate PLATFORM_LACKS_TORCHCODEC_WHEEL and applies the
torchcodec filter unconditionally there, independent of NO_TORCH.

Surfaced by the staging-2 cross-OS smoke `unsloth studio update`
step on ubuntu-24.04-arm; verified the same step is green with this
patch overlaid.

* Studio: skip librosa on no-torch hosts (unblocks Intel Mac install)

Closes the last cross-platform install gap surfaced by the staging-2
cross-OS smoke (see unslothai/unsloth#5046 for the original report):
`install.sh --local` on macos-15-intel fails at

  × Failed to build `llvmlite==0.47.0`
  error: failed-wheel-build-for-install
  ╰─> llvmlite
  error          studio setup failed (exit code 1)

Root cause: upstream llvmlite dropped the macosx_x86_64 wheel between
0.42.0 and 0.46.0 (https://pypi.org/project/llvmlite/0.47.0/#files --
only macosx_arm64 / manylinux / win_amd64 remain). pip falls back to
a from-source build of llvmlite's FFI, which needs LLVM 14/15 dev
headers and matching llvm-config -- not present in Xcode Command
Line Tools' libclang and not installed by install.sh's MAC_INTEL
deps branch.

llvmlite enters Studio's tree via librosa -> numba -> llvmlite in
extras.txt. openai-whisper (extras.txt:28) would also pull numba but
is already filtered on no-torch hosts. Adding librosa to the same
NO_TORCH_SKIP_PACKAGES set makes the install go through cleanly on
Intel Mac (auto-detected NO_TORCH=true via the MAC_INTEL branch) and
on any user-passed --no-torch host where torch-dependent audio
pipelines would not run anyway.

Tracked / verified on the danielhanchen/unsloth-staging-2#154 smoke
matrix (macos-15-intel).

* Studio UI tests: retry evaluate_fetch on transport-level failure (PR #5790)

Mac Studio UI CI on this PR (run 26496820814, job 78026959359) failed
with /api/models/list status=0 error='TypeError: Failed to fetch'.
The artifact studio.log shows the server answered the two preceding
/api/models/list calls from the React mount (both 200) but never
received the third call from the test script: the browser reused a
kept-alive HTTP/1.1 socket that uvicorn (5s keep_alive_timeout) had
closed ~130ms earlier. Chromium under --single-process on macos-14
free runners is most prone to this; the post /api/auth/change-password
session churn accelerates it. A rerun on the same SHA passed, which is
the classic flake signature.

evaluate_fetch in tests/studio/_playwright_robust.py already returns a
structured {status: 0, body: None, error: "..."} on JS-side throws, but
every caller treats status=0 as fatal. Add a bounded retry inside the
helper so the one class of failure recovers transparently:

  status != 0       -> real HTTP response (incl. 4xx/5xx); propagate.
  error has "AbortError" -> caller's AbortSignal deadline; propagate.
  else (status==0)  -> stale-keepalive or other transport failure;
                       retry after 250ms / 500ms backoff so the pool
                       evicts the dead socket before the next attempt.

Defaults transport_retries=2, transport_backoff_ms=250 (max added
latency on the happy path is zero; on a transport failure: up to
750ms of sleep). Callers keep the existing {status, body, error} shape;
no call-site changes needed.

Verified: tests/studio/_playwright_robust.py compiles; signature
gains two kwonly args (transport_retries, transport_backoff_ms);
8 evaluate_fetch call sites in playwright_chat_ui.py +
playwright_extra_ui.py pick up the retry without change.

---------

Co-authored-by: danielhanchen <info@unsloth.ai>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 install.ps1                        | 42 ++++++++++++++++-------
 studio/install_llama_prebuilt.py   | 50 +++++++++++++++++++++++++---
 studio/install_python_stack.py     | 30 ++++++++++++++++-
 studio/setup.sh                    | 10 ++++++
 tests/studio/_playwright_robust.py | 53 ++++++++++++++++++++++++------
 5 files changed, 158 insertions(+), 27 deletions(-)

diff --git a/install.ps1 b/install.ps1
index 1ed8fafdb4..3bb5fb3f8c 100644
--- a/install.ps1
+++ b/install.ps1
@@ -887,12 +887,19 @@ shell.Run cmd, 0, False
     }
 
     # ── Check winget ──
+    # winget is only needed to install Python or uv. If both are
+    # already on PATH (Windows ARM64 GitHub-hosted runners, manual
+    # python.org + Astral uv installs, corporate locked-down hosts
+    # without the Store, etc.) the script can proceed without it.
+    # We defer the hard failure to the Python / uv install branches
+    # below, where winget is actually invoked.
     Write-TauriLog "STEP" "Checking system dependencies"
-    if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
-        step "winget" "not available" "Red"
-        substep "Install it from https://aka.ms/getwinget" "Yellow"
-        substep "or install Python $PythonVersion and uv manually, then re-run." "Yellow"
-        return (Exit-InstallFailure "winget is not available")
+    $script:WingetAvailable = [bool](Get-Command winget -ErrorAction SilentlyContinue)
+    if ($script:WingetAvailable) {
+        step "winget" "available"
+    } else {
+        step "winget" "not available -- will require Python + uv to be already installed" "Yellow"
+        substep "Get it from https://aka.ms/getwinget if Python / uv are not already on PATH." "Yellow"
     }
 
     # ── Helper: detect a working Python 3.11-3.13 on the system ──
@@ -973,6 +980,12 @@ shell.Run cmd, 0, False
         step "python" "Python $($DetectedPython.Version) already installed"
     }
     if (-not $DetectedPython) {
+        if (-not $script:WingetAvailable) {
+            Write-Host "[ERROR] No compatible Python (3.11-3.13) found and winget is unavailable on this host." -ForegroundColor Red
+            Write-Host "        Install Python $PythonVersion from https://www.python.org/downloads/" -ForegroundColor Yellow
+            Write-Host "        and re-run this installer (make sure 'Add Python to PATH' is checked)." -ForegroundColor Yellow
+            return (Exit-InstallFailure "winget required to install Python on this host")
+        }
         substep "installing Python ${PythonVersion}..."
         $pythonPackageId = "Python.Python.$PythonVersion"
         # Temporarily lower ErrorActionPreference so that winget stderr
@@ -1024,14 +1037,19 @@ shell.Run cmd, 0, False
     Write-TauriLog "STEP" "Installing uv package manager"
     if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
         substep "installing uv package manager..."
-        $prevEAP = $ErrorActionPreference
-        $ErrorActionPreference = "Continue"
-        try { winget install --id=astral-sh.uv -e --accept-package-agreements --accept-source-agreements } catch {}
-        $ErrorActionPreference = $prevEAP
-        Refresh-SessionPath
-        # Fallback: if winget didn't put uv on PATH, try the PowerShell installer
+        if ($script:WingetAvailable) {
+            $prevEAP = $ErrorActionPreference
+            $ErrorActionPreference = "Continue"
+            try { winget install --id=astral-sh.uv -e --accept-package-agreements --accept-source-agreements } catch {}
+            $ErrorActionPreference = $prevEAP
+            Refresh-SessionPath
+        }
+        # Fallback: if winget is unavailable or didn't put uv on PATH,
+        # use Astral's official PowerShell installer. This is the only
+        # supported path on hosts without winget (Windows ARM64 runners,
+        # corporate machines without the Store, etc.).
         if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
-            substep "trying alternative uv installer..." "Yellow"
+            substep "installing uv via https://astral.sh/uv/install.ps1..." "Yellow"
             Invoke-Expression (Invoke-RestMethod -Uri "https://astral.sh/uv/install.ps1")
             Refresh-SessionPath
         }
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 7672af6630..68fd9de1d1 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -1349,6 +1349,24 @@ def direct_upstream_release_plan(
                     install_kind = "windows-cpu",
                 )
             )
+    elif host.is_windows and host.is_arm64:
+        # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-win-cpu-arm64.zip
+        # (visible in the b9334 release manifest). Without this branch the
+        # selector returned 0 attempts and the installer fell back to a
+        # source build on every Windows ARM64 host.
+        cpu_asset = f"llama-{release_tag}-bin-win-cpu-arm64.zip"
+        cpu_url = assets.get(cpu_asset)
+        if cpu_url:
+            attempts.append(
+                AssetChoice(
+                    repo = repo,
+                    tag = release_tag,
+                    name = cpu_asset,
+                    url = cpu_url,
+                    source_label = "upstream",
+                    install_kind = "windows-arm64",
+                )
+            )
     elif host.is_macos and host.is_arm64:
         asset_name = f"llama-{release_tag}-bin-macos-arm64.tar.gz"
         asset_url = assets.get(asset_name)
@@ -1391,6 +1409,25 @@ def direct_upstream_release_plan(
                     install_kind = "linux-cpu",
                 )
             )
+    elif host.is_linux and host.is_arm64 and not host.has_usable_nvidia:
+        # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-ubuntu-arm64.tar.gz
+        # (visible in the b9334 release manifest). Without this branch the
+        # selector returned 0 attempts and the installer fell back to a
+        # source build on every Linux ARM64 host (DGX Spark, Ampere
+        # Altra, GitHub-hosted ubuntu-24.04-arm runners, etc.).
+        asset_name = f"llama-{release_tag}-bin-ubuntu-arm64.tar.gz"
+        asset_url = assets.get(asset_name)
+        if asset_url:
+            attempts.append(
+                AssetChoice(
+                    repo = repo,
+                    tag = release_tag,
+                    name = asset_name,
+                    url = asset_url,
+                    source_label = "upstream",
+                    install_kind = "linux-arm64",
+                )
+            )
     if not attempts:
         raise PrebuiltFallback("no compatible upstream prebuilt asset was found")
     return InstallReleasePlan(
@@ -3833,11 +3870,16 @@ def runtime_patterns_for_choice(choice: AssetChoice) -> list[str]:
     # libraries between b9279 and b9283) without us re-enumerating
     # every new file. Studio only invokes llama-server and llama-quantize;
     # other CLIs upstream ships (llama-cli, llama-bench, ...) are skipped.
-    if choice.install_kind in {"linux-cpu", "linux-cuda", "linux-rocm"}:
+    if choice.install_kind in {"linux-cpu", "linux-cuda", "linux-rocm", "linux-arm64"}:
         return ["llama-server", "llama-quantize", "lib*.so*"]
     if choice.install_kind in {"macos-arm64", "macos-x64"}:
         return ["llama-server", "llama-quantize", "lib*.dylib"]
-    if choice.install_kind in {"windows-cpu", "windows-cuda", "windows-hip"}:
+    if choice.install_kind in {
+        "windows-cpu",
+        "windows-cuda",
+        "windows-hip",
+        "windows-arm64",
+    }:
         return ["llama-server.exe", "llama-quantize.exe", "*.dll"]
     raise PrebuiltFallback(
         f"unsupported install kind for runtime overlay: {choice.install_kind}"
@@ -5188,7 +5230,7 @@ def load_prebuilt_metadata(install_dir: Path) -> dict[str, Any] | None:
 
 
 def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
-    if choice.install_kind == "linux-cpu":
+    if choice.install_kind in {"linux-cpu", "linux-arm64"}:
         return [
             ["libllama-common.so*"],
             ["libllama.so*"],
@@ -5223,7 +5265,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             ["libmtmd.so*"],
             ["libggml-hip.so*"],
         ]
-    if choice.install_kind == "windows-cpu":
+    if choice.install_kind in {"windows-cpu", "windows-arm64"}:
         return [["llama.dll"]]
     if choice.install_kind == "windows-cuda":
         groups = [["llama.dll"], ["ggml-cuda.dll"]]
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index ca7fe3f004..c4524b06f5 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -38,6 +38,18 @@ IS_WINDOWS = sys.platform == "win32"
 IS_MACOS = sys.platform == "darwin"
 IS_MAC_INTEL = IS_MACOS and platform.machine() == "x86_64"
 IS_MAC_ARM = IS_MACOS and platform.machine() == "arm64"
+IS_LINUX = sys.platform.startswith("linux")
+# torchcodec ships wheels only for manylinux_2_28_x86_64,
+# macosx_12_0_arm64, and win_amd64 (visible in the 0.10.0 PyPI page).
+# Trying to install it on any other host fails the whole
+# extras-no-deps step. `unsloth studio update` does not have a
+# --no-torch flag, so on these hosts the audio extras must be
+# filtered out independent of the NO_TORCH env var.
+PLATFORM_LACKS_TORCHCODEC_WHEEL = (
+    (IS_LINUX and platform.machine() in {"aarch64", "arm64"})
+    or (IS_WINDOWS and platform.machine().lower() in {"arm64", "aarch64"})
+    or IS_MAC_INTEL
+)
 
 # ── ROCm / AMD GPU support ─────────────────────────────────────────────────────
 # Mapping from detected ROCm (major, minor) to the best PyTorch wheel tag on
@@ -604,7 +616,14 @@ WINDOWS_SKIP_PACKAGES = {"open_spiel", "triton_kernels"}
 # Packages to skip when torch is unavailable (Intel Mac GGUF-only mode).
 # These packages either *are* torch extensions or have unconditional
 # ``Requires-Dist: torch`` in their published metadata, so installing
-# them would pull torch back into the environment.
+# them would pull torch back into the environment. ``librosa`` also
+# lives in this set even though it does not itself require torch:
+# upstream ``llvmlite`` dropped its macOS x86_64 wheel between 0.42.0
+# and 0.46.0+ (see https://pypi.org/project/llvmlite/0.47.0/#files --
+# only macosx_arm64 / manylinux / win_amd64 remain), so on Intel Mac
+# the librosa -> numba -> llvmlite chain triggers a from-source build
+# that fails inside CI and on the host without LLVM 14/15 headers.
+# Tracked separately in unslothai/unsloth#5046.
 NO_TORCH_SKIP_PACKAGES = {
     "torch-stoi",
     "timm",
@@ -612,6 +631,7 @@ NO_TORCH_SKIP_PACKAGES = {
     "torch-c-dlpack-ext",
     "openai-whisper",
     "transformers-cfg",
+    "librosa",
 }
 
 
@@ -839,6 +859,14 @@ def pip_install(
     if actual_req is not None and NO_TORCH and NO_TORCH_SKIP_PACKAGES:
         actual_req = _filter_requirements(actual_req, NO_TORCH_SKIP_PACKAGES)
         temp_reqs.append(actual_req)
+    if actual_req is not None and PLATFORM_LACKS_TORCHCODEC_WHEEL:
+        # Linux aarch64 / Windows ARM64 / Intel Mac have no torchcodec
+        # wheel. `unsloth studio update --local` does not pass
+        # --no-torch, so the NO_TORCH filter above does not fire; do
+        # the targeted skip independently so the audio extras step
+        # does not take down the whole update.
+        actual_req = _filter_requirements(actual_req, {"torchcodec"})
+        temp_reqs.append(actual_req)
     req_args_pip: list[str] = []
     req_args_uv: list[str] = []
     if actual_req is not None:
diff --git a/studio/setup.sh b/studio/setup.sh
index c5beb7ebd3..e8fc8f6f13 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -671,6 +671,16 @@ elif [ "$_HOST_SYSTEM" = "Linux" ] \
         && [ "$_HOST_MACHINE" = "x86_64" ] \
         && [ "$_LINUX_HAS_GPU" = false ]; then
     _HELPER_RELEASE_REPO="ggml-org/llama.cpp"
+elif [ "$_HOST_SYSTEM" = "Linux" ] \
+        && { [ "$_HOST_MACHINE" = "aarch64" ] || [ "$_HOST_MACHINE" = "arm64" ]; } \
+        && [ "$_LINUX_HAS_GPU" = false ]; then
+    # Linux ARM64 (Ampere Altra, Raspberry Pi 5, GitHub `ubuntu-24.04-arm`,
+    # CPU-only Jetson rescue mode, ...). unslothai/llama.cpp only ships
+    # the Linux CUDA bundles, so without this branch the prebuilt
+    # resolver returns 0 attempts on every release and the installer
+    # falls all the way back to a source build. Upstream ggml-org ships
+    # llama-bNNNN-bin-ubuntu-arm64.tar.gz from at least b9072 onward.
+    _HELPER_RELEASE_REPO="ggml-org/llama.cpp"
 else
     _HELPER_RELEASE_REPO="unslothai/llama.cpp"
 fi
diff --git a/tests/studio/_playwright_robust.py b/tests/studio/_playwright_robust.py
index 3deeb38cda..b190b2b3e1 100644
--- a/tests/studio/_playwright_robust.py
+++ b/tests/studio/_playwright_robust.py
@@ -436,6 +436,8 @@ def evaluate_fetch(
     headers: dict[str, str] | None = None,
     body: Any = None,
     timeout_ms: int = 20_000,
+    transport_retries: int = 2,
+    transport_backoff_ms: int = 250,
 ) -> dict[str, Any]:
     """Run `fetch(url, opts)` inside the page with an AbortSignal deadline.
 
@@ -482,16 +484,47 @@ def evaluate_fetch(
             }
         }
     """
-    return page.evaluate(
-        js,
-        {
-            "url": url,
-            "method": method,
-            "headers": headers or {},
-            "body": body_arg,
-            "timeoutMs": int(timeout_ms),
-        },
-    )
+    payload = {
+        "url": url,
+        "method": method,
+        "headers": headers or {},
+        "body": body_arg,
+        "timeoutMs": int(timeout_ms),
+    }
+    # Bounded retry on transport failures only.
+    #   status != 0  -> real HTTP response (incl. 4xx/5xx); propagate.
+    #   AbortError   -> caller's deadline; propagate.
+    #   else (==0)   -> stale-keepalive / "TypeError: Failed to fetch"
+    #                   on macos-14 right after auth rotations close
+    #                   existing sessions. Retry after backoff so the
+    #                   browser pool evicts the dead socket.
+    last: dict[str, Any] | None = None
+    attempts = max(1, int(transport_retries) + 1)
+    for attempt in range(attempts):
+        result = page.evaluate(js, payload)
+        last = result
+        try:
+            status = int(result.get("status") or 0)
+        except (TypeError, ValueError):
+            status = 0
+        if status != 0:
+            return result
+        err = str(result.get("error") or "")
+        if "AbortError" in err:
+            return result
+        if attempt < attempts - 1:
+            wait_ms = transport_backoff_ms * (2**attempt)
+            try:
+                sys.stderr.write(
+                    f"[evaluate_fetch] {method} {url}: transport failure "
+                    f"({attempt + 1}/{attempts}, err={err!r}); "
+                    f"retrying in {wait_ms}ms\n"
+                )
+                sys.stderr.flush()
+            except Exception:
+                pass
+            time.sleep(wait_ms / 1000.0)
+    return last or {"status": 0, "body": None, "error": "no attempt made"}
 
 
 # ─────────────────────────────────────────────────────────────────────

From ad2ba4202ae93db05d3c8085c2784c92c5c0fd37 Mon Sep 17 00:00:00 2001
From: DoubleMathew <mmathew23@gmail.com>
Date: Wed, 27 May 2026 07:01:04 -0500
Subject: [PATCH 005/222] Harden Linux llama.cpp prebuilt reuse (#5796)

Run the Linux llama.cpp prebuilt dependency preflight before reusing an existing install, so cached trees missing newly required per-tool shared libraries (libllama-server-impl.so / libllama-quantize-impl.so introduced upstream between b9279 and b9283) trigger a repair instead of silently skipping reinstall and failing at runtime. Adds a regression test for the new lib*-impl.so overlay layout.
---
 studio/install_llama_prebuilt.py              |  9 ++
 .../test_install_llama_prebuilt_logic.py      | 91 +++++++++++++++++++
 2 files changed, 100 insertions(+)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 68fd9de1d1..394a1c9cd8 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -5340,6 +5340,15 @@ def existing_install_matches_choice(
     for binary in ("llama-server", "llama-quantize"):
         if not (runtime_dir / f"{binary}{ext}").exists():
             return False
+    if host.is_linux:
+        try:
+            preflight_linux_installed_binaries(
+                [runtime_dir / "llama-server", runtime_dir / "llama-quantize"],
+                install_dir,
+                host,
+            )
+        except Exception:
+            return False
     expected_fingerprint = expected_install_fingerprint(
         llama_tag = llama_tag,
         release_tag = release_tag,
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index ed988e081f..49ad6da177 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -2799,6 +2799,97 @@ def test_runtime_overlay_cannot_overwrite_main_archive_payload(
         assert (release_dir / name).exists(), f"missing {name}"
 
 
+def test_linux_runtime_overlay_copies_llama_tool_impl_libraries(
+    tmp_path: Path,
+) -> None:
+    install_from_archives = INSTALL_LLAMA_PREBUILT.install_from_archives
+
+    work = tmp_path / "work"
+    install = tmp_path / "install"
+    archives = tmp_path / "archives"
+    work.mkdir()
+    install.mkdir()
+    archives.mkdir()
+
+    bundle = archives / "app-b9334-linux-x64-cuda13-newer.tar.gz"
+    with tarfile.open(bundle, "w:gz") as archive:
+        for name in (
+            "llama-cli",
+            "llama-server",
+            "llama-quantize",
+            "libllama-cli-impl.so",
+            "libllama-server-impl.so",
+            "libllama-quantize-impl.so",
+            "libllama-common.so",
+            "libllama.so",
+            "libggml.so",
+            "libggml-base.so",
+            "libmtmd.so",
+            "libggml-cpu-x64.so",
+            "libggml-cuda.so",
+        ):
+            payload = f"{name}\n".encode()
+            member = tarfile.TarInfo(name)
+            member.size = len(payload)
+            archive.addfile(member, io.BytesIO(payload))
+
+    import hashlib
+    import shutil as _shutil
+
+    bundle_sha = hashlib.sha256(bundle.read_bytes()).hexdigest()
+    choice = AssetChoice(
+        repo = "unslothai/llama.cpp",
+        tag = "b9334",
+        name = bundle.name,
+        url = f"https://example.com/{bundle.name}",
+        source_label = "published",
+        install_kind = "linux-cuda",
+        runtime_line = "cuda13",
+        expected_sha256 = bundle_sha,
+    )
+    host = HostInfo(
+        system = "Linux",
+        machine = "x86_64",
+        is_windows = False,
+        is_linux = True,
+        is_macos = False,
+        is_x86_64 = True,
+        is_arm64 = False,
+        nvidia_smi = None,
+        driver_cuda_version = (13, 0),
+        compute_caps = [],
+        visible_cuda_devices = None,
+        has_physical_nvidia = True,
+        has_usable_nvidia = True,
+    )
+
+    orig_download = INSTALL_LLAMA_PREBUILT.download_file_verified
+
+    def fake_download(url, target_path, *, expected_sha256 = None, label = None, **kw):
+        _shutil.copy2(bundle, target_path)
+        if expected_sha256:
+            actual = hashlib.sha256(Path(target_path).read_bytes()).hexdigest()
+            if actual != expected_sha256:
+                raise INSTALL_LLAMA_PREBUILT.PrebuiltFallback(
+                    f"sha256 mismatch on {label}"
+                )
+
+    INSTALL_LLAMA_PREBUILT.download_file_verified = fake_download
+    try:
+        install_from_archives(choice, host, install, work)
+    finally:
+        INSTALL_LLAMA_PREBUILT.download_file_verified = orig_download
+
+    runtime_dir = install / "build" / "bin"
+    for name in (
+        "libllama-cli-impl.so",
+        "libllama-server-impl.so",
+        "libllama-quantize-impl.so",
+    ):
+        assert (runtime_dir / name).exists(), f"missing {name}"
+    assert not (runtime_dir / "llama-cli").exists()
+
+
 def test_python_runtime_dirs_covers_cu13_and_library_bin(
     monkeypatch, tmp_path: Path
 ) -> None:

From dac2aeda1aa45271351d55fe90db77e8ea2195b2 Mon Sep 17 00:00:00 2001
From: Dariton4000 <184837391+Dariton4000@users.noreply.github.com>
Date: Wed, 27 May 2026 14:01:24 +0200
Subject: [PATCH 006/222] Studio: expose image size setting in training UI
 (#5743)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Studio: add VLM image-size control for training

  Studio vision fine-tuning had no explicit way to cap image resolution, so
  users could not trade visual detail against context and memory use from the
  training UI, YAML config, or API payload. :) Add a nullable `vision_image_size`
  setting that keeps the current model default when unset and applies a
  max-side resize when provided.

  - Add `vision_image_size` to the training request model, route payload, backend
    training config, and frontend API/types plumbing.
  - Validate the value server-side as either null or an integer in the supported
    256-2048 range.
  - Surface an Image Size selector for vision LoRA training with Default plus
    common preset sizes.
  - Include the value in training start payloads only for image-dataset vision
    models, and serialize it into vision-aware YAML configs.
  - Map backend model defaults back into the training store and reset the value
    when reapplying model defaults.
  - Pass the resize through the Torch trainer via `UnslothVisionDataCollator`
    using max-dimension semantics.
  - Apply the same max-dimension resize in the MLX VLM path before mlx-vlm's
    internal collation, preserving aspect ratio and avoiding upscaling.
  - Add backend validation coverage and MLX resize-size tests for the new
    behavior.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: thread vision_image_size into DeepSeek OCR + writable MLX ndarray

- trainer.py: DeepSeek OCR collator now honors the new vision_image_size
  setting as image_size. Falls back to 640 when null. base_size stays at
  1024 and crop_mode stays True so the Gundam preset's dynamic cropping
  of large documents keeps working.
- worker.py: _resize_mlx_vlm_image returns np.array(image, copy=True)
  instead of np.asarray(image). The PIL view from np.asarray is not
  writable, which makes HF VLM processors emit "The given NumPy array
  is not writable, and PyTorch does not support non-writable tensors..."
  when they call torch.from_numpy. copy=True keeps the same shape and
  dtype but produces a writable buffer.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: align YAML export gate with API mapper + extend Image Size dropdown

- training-section.tsx: handleSaveConfig now passes
  isVisionModel && isDatasetImage === true to serializeConfigToYaml,
  matching buildTrainingStartPayload. Stops vision_image_size from
  leaking into exported YAML for text-only datasets where the API
  would have sent null.
- params-section.tsx: add 256 to visionImageSizePresets so the
  dropdown spans the validator's full [256, 2048] range. Also render
  a synthetic SelectItem for the current value when it was loaded
  from YAML or model defaults and is not in the preset list, so the
  controlled Select always shows the active size.

* Studio: validate vision_image_size in YAML/model-default loader

mapBackendModelConfigToTrainingPatch now mirrors the backend validator
at studio/backend/models/training.py:169 by dropping any value that is
not an integer in [256, 2048]. Pre-fix, an imported YAML like
vision_image_size: 4096 or 640.5 would land in the store and the UI
would happily display it, only to fail when Start Training posted to
the backend. With this guard the store never holds a value the backend
would reject.

* Studio: precise error messages for invalid vision_image_size inputs

Switch the field_validator to mode="before" so True/False surface as
bool (not Pydantic's coerced 1/0) and give a precise
"must be an integer or null" message instead of the misleading
"must be in [256, 2048] (got 1)". Also explicitly accepts numpy
Integral and integral Real scalars so YAML or programmatic callers
using numpy ints keep working.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: test that bool inputs yield the precise 'integer or null' error

Regression guard for the validator switch to mode="before". Pre-fix,
vision_image_size: True was rejected with "must be in [256, 2048]
(got 1)" because Pydantic coerced before our check ran. New test
asserts the message now reads "integer or null".

* Studio: tighten vision_image_size loader + YAML save + MLX rounding

Round 2 of follow-up review surfaced three usability issues:

- model-defaults.ts: switching to a model whose backend YAML omits
  vision_image_size now explicitly resets the store value to null.
  Pre-fix, a stale 2048 from a previous model would silently apply
  to the new run because every checked-in model-default file omits
  the key.
- training-section.tsx: handleSaveConfig now includes vision fields
  unless isDatasetImage is definitively false. isDatasetImage is null
  during dataset checks, after dataset edits, and on import; treating
  unknown as "drop" would silently lose the user's selection in those
  windows. Confirmed-text-only datasets still drop the value.
- worker.py: _mlx_vlm_max_resized_size now mirrors the Torch collator's
  integer formula (w * size + size_func // 2) // size_func instead of
  Python round(), which uses banker's rounding and disagreed by 1px on
  half-pixel inputs like 333x1000 with target 500 (was 166, now 167).
  Test_mlx_training_worker_config gains parity assertions.

* Studio: reset vision_image_size in the model-config error fallback path

mapBackendModelConfigToTrainingPatch resets stale image size on the
success path, but if the /api/models/config endpoint throws,
training-config-store.ts falls through to checkVisionModel and only
updates capability flags. Pre-fix that left a stale 2048 (or any
prior selection) in the store, so once dataset detection marked the
new dataset as image, the next training start would silently apply
the previous model's size. The error branch now also resets to the
DEFAULT_HYPERPARAMS.visionImageSize sentinel.

* Studio: revert DeepSeek OCR Image Size knob + move missing-key reset

Round 3 of the parallel-reviewer pass surfaced two issues that I had
introduced earlier in this PR's follow-ups.

- trainer.py: my prior change threaded vision_image_size into the
  DeepSeek OCR collator's image_size argument. The collator's
  (image_size, base_size, crop_mode) is a single preset
  (Tiny / Small / Base / Large / Gundam); changing image_size in
  isolation desynchronizes the per-crop pixel grid from num_queries
  downstream and produces wrong token grids on documents larger than
  the per-crop tile. The fix pins the collator back at the Gundam
  preset and logs a clear "ignored for DeepSeek OCR" notice when the
  user has selected a non-default Image Size.
- model-defaults.ts + training-config-store.ts: the round 4 fix that
  reset visionImageSize when a model YAML omitted the key also fired
  on same-model reloads (ensureModelDefaultsLoaded re-fires on page
  refresh), wiping a value the user had just selected. The reset is
  now in setSelectedModel, gated on selectedModel != previousModel,
  so true model switches still clear stale values while reloads keep
  the user's selection.

* Studio: extend DeepSeek OCR Image Size exclusion to MLX + frontend

Round 4 of the parallel-reviewer pass flagged that the Torch trainer
exclusion I added did not have a matching MLX guard, and that the UI
still offered the dropdown for DeepSeek OCR even though the backend
ignores it.

- worker.py: _run_mlx_training now mirrors the Torch exclusion. When
  the model name matches DeepSeek OCR, vision_image_size is forced
  back to None before _adapt_for_mlx_vlm sees it, so dataset images
  pass through unchanged just like the Torch path. Emits a clear
  status line when this happens.
- params-section.tsx: the Image Size Row is now gated on
  showVisionImageSize (showVisionLora && !isDeepseekOcr) instead of
  showVisionLora alone, so DeepSeek OCR users no longer see a control
  that silently has no effect.
- mappers.ts: buildTrainingStartPayload sends null for vision_image_size
  whenever the selected model is DeepSeek OCR, so the backend log line
  about ignoring the value never fires from a UI-driven start.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: tighten YAML import/save for vision_image_size

Two YAML-path asymmetries that could leak a stale image size into
training:

- parseYamlConfig now treats a missing training.vision_image_size as
  null. Without this, importing a YAML saved before this feature (or
  any config that omits the key) preserved whatever value the user had
  previously set on a different model. The model-defaults reload path
  still uses Object.hasOwn so same-model defaults reloads do not wipe
  a manual selection; only file import normalises the missing key.

- handleSaveConfig now passes a DeepSeek-OCR-specific guard to
  serializeConfigToYaml so saved YAML matches what the API mapper
  actually sends. Previously a state with visionImageSize set could
  emit the key even though Studio ignored it at training time for
  DeepSeek OCR, and a later import for a non-DeepSeek vision model
  would activate the stale value.

serializeConfigToYaml gains an optional third parameter
includeVisionImageSize defaulting to includeVisionFields, preserving
the existing 2-arg call signature for backwards compatibility.

* Studio: also reset vision_image_size when YAML lacks a training section

Round 9's parseYamlConfig normalization only fired when the YAML had a
training mapping that omitted vision_image_size. A lora-only or
logging-only YAML (or one with `training: null`) still left trainingObj
unset, the mapper saw no vision_image_size key, and the previously
selected store value persisted into the next training run.

Now an absent or null training section is synthesised as
{ vision_image_size: null } so model-defaults.ts always patches
visionImageSize back to Default on file import. Same-model defaults
reloads still preserve manual choices via the existing Object.hasOwn
gate in mapBackendModelConfigToTrainingPatch.

* Studio: unify parseYamlConfig non-object training handling

A fresh static review (Opus subagent) flagged P3-1: parseYamlConfig
only synthesised vision_image_size: null when raw.training was either
absent or a plain object missing the key. If raw.training is a scalar
or an array (malformed but still parseable), the value was passed
through unchanged, the mapper's Object.hasOwn returned false, and any
previously selected visionImageSize persisted - the same stale-state
leak the lora-only fallback was added to close.

Treat any non-plain-object raw.training (null, array, scalar) as a
malformed/missing section and reset to { vision_image_size: null }.

* Studio: tighten code comments for vision_image_size path

* Studio: tighten vision_image_size validator + restore lost comment context

Two issues surfaced by a fresh adversarial review of the validator:

1. v.strip().lstrip("+-").isdigit() let "++512" / "--256" / "+-+512"
   slip past the gate, then int("++512") raised an uncaught ValueError
   and Pydantic surfaced "invalid literal for int() with base 10: '++512'"
   instead of the contracted "vision_image_size must be an integer or null".

2. str.isdigit() returns True for Unicode digit families (full-width '５１２',
   Arabic-Indic '٥١٢', Devanagari '१०२४'), and int() coerces them, so the
   value reaching the backend wasn't the ASCII the user typed.

Replaced the lstrip+isdigit pair with re.fullmatch(r'[+-]?[0-9]+', stripped),
which rejects both shapes with the precise error and accepts the documented
ones ('256', '+512', ' 1024 '). Added 8 regression test cases covering
multi-sign strings, lone sign, and the three Unicode digit families.

Also restored comment context lost in f9c39331:
- model-defaults.ts: name studio/backend/models/training.py:_check_vision_image_size
  as the spec the [256, 2048] range mirrors, so a maintainer changing the
  cap in one file can find the other.
- training-section.tsx: enumerate the three windows in which isDatasetImage
  is null (before a check, after dataset edits, on import) so a future
  maintainer doesn't simplify the gate to `isCheckingDataset`.
- worker.py: qualify the writable-ndarray comment with "when a resize is
  requested" so it doesn't misadvertise the resize=None early-return.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/backend/core/training/trainer.py       | 24 +++++-
 studio/backend/core/training/training.py      |  1 +
 studio/backend/core/training/worker.py        | 78 +++++++++++++++++--
 studio/backend/models/training.py             | 48 ++++++++++++
 studio/backend/routes/training.py             |  1 +
 .../tests/test_mlx_training_worker_config.py  | 12 +++
 .../tests/test_studio_train_validation.py     | 48 ++++++++++++
 studio/frontend/src/config/training.ts        |  1 +
 .../studio/sections/params-section.tsx        | 64 +++++++++++++++
 .../studio/sections/training-section.tsx      | 19 ++++-
 .../src/features/training/api/mappers.ts      | 11 ++-
 .../src/features/training/api/models-api.ts   |  1 +
 .../features/training/lib/model-defaults.ts   | 20 +++++
 .../src/features/training/lib/yaml-config.ts  | 64 ++++++++++-----
 .../training/stores/training-config-store.ts  | 19 ++++-
 .../src/features/training/types/api.ts        |  1 +
 .../src/features/training/types/config.ts     |  2 +
 17 files changed, 384 insertions(+), 30 deletions(-)

diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index b128fb5338..b9643cac6a 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -3057,6 +3057,14 @@ class UnslothTrainer:
 
                     logger.info("Configuring DeepSeek OCR data collator...\n")
                     FastVisionModel.for_training(self.model)
+                    # DeepSeek OCR's (image_size, base_size, crop_mode) is a
+                    # coupled preset; changing image_size alone desyncs the
+                    # per-crop pixel grid from num_queries. Use Gundam.
+                    if training_args.get("vision_image_size") is not None:
+                        logger.info(
+                            "Vision image resize ignored for DeepSeek OCR "
+                            "(uses fixed Gundam preset).\n"
+                        )
                     data_collator = DeepSeekOCRDataCollator(
                         tokenizer = self.tokenizer,
                         model = self.model,
@@ -3123,7 +3131,21 @@ class UnslothTrainer:
                 from unsloth.trainer import UnslothVisionDataCollator
 
                 FastVisionModel.for_training(self.model)
-                data_collator = UnslothVisionDataCollator(self.model, self.tokenizer)
+                vision_image_size = training_args.get("vision_image_size")
+                if vision_image_size is None:
+                    data_collator = UnslothVisionDataCollator(
+                        self.model, self.tokenizer
+                    )
+                else:
+                    logger.info(
+                        f"Vision image resize: {vision_image_size} (max dimension)\n"
+                    )
+                    data_collator = UnslothVisionDataCollator(
+                        self.model,
+                        self.tokenizer,
+                        resize = vision_image_size,
+                        resize_dimension = "max",
+                    )
                 logger.info("Vision data collator configured\n")
 
             # ========== TRAINING CONFIGURATION ==========
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index d2c2316d45..0af3349c6f 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -193,6 +193,7 @@ class TrainingBackend:
             "hf_token": kwargs.get("hf_token", ""),
             "load_in_4bit": kwargs.get("load_in_4bit", True),
             "max_seq_length": kwargs.get("max_seq_length", 2048),
+            "vision_image_size": kwargs.get("vision_image_size"),
             "hf_dataset": kwargs.get("hf_dataset", ""),
             "local_datasets": kwargs.get("local_datasets"),
             "local_eval_datasets": kwargs.get("local_eval_datasets"),
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index f47a6bd599..632b38d75a 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -959,7 +959,47 @@ def _activate_transformers_version(model_name: str) -> None:
     activate_transformers_for_subprocess(model_name)
 
 
-def _adapt_for_mlx_vlm(items):
+def _mlx_vlm_max_resized_size(width: int, height: int, target: int) -> tuple[int, int]:
+    if width <= 0 or height <= 0 or target <= 0:
+        return width, height
+    largest_side = max(width, height)
+    if largest_side <= target:
+        return width, height
+    # Integer formula matches unsloth_zoo's collator (Python round() differs
+    # by 1px on half-pixel cases). max(1, _) avoids zero-side degenerate output.
+    new_w = max(1, (width * target + largest_side // 2) // largest_side)
+    new_h = max(1, (height * target + largest_side // 2) // largest_side)
+    return new_w, new_h
+
+
+def _resize_mlx_vlm_image(image, resize):
+    if resize is None:
+        return image
+    try:
+        from PIL import Image
+        import numpy as np
+    except ImportError:
+        return image
+    if not isinstance(image, Image.Image):
+        return image
+    image = image.convert("RGB")
+    new_size = _mlx_vlm_max_resized_size(*image.size, int(resize))
+    if new_size != image.size:
+        resampling = getattr(Image, "Resampling", Image).LANCZOS
+        image = image.resize(new_size, resampling)
+    # When a resize is requested, hand mlx-vlm a writable RGB ndarray so its
+    # PIL-path square-resize is skipped and HF processors don't warn on
+    # non-writable views. resize=None (Default) above keeps the original PIL.
+    return np.array(image, copy = True)
+
+
+def _resize_mlx_vlm_images(value, resize):
+    if isinstance(value, list):
+        return [_resize_mlx_vlm_image(image, resize) for image in value]
+    return _resize_mlx_vlm_image(value, resize)
+
+
+def _adapt_for_mlx_vlm(items, resize = None):
     """Adapt GPU-path VLM dataset output for mlx-vlm consumption.
 
     The GPU path embeds PIL images inside messages content as
@@ -979,7 +1019,7 @@ def _adapt_for_mlx_vlm(items):
                     if isinstance(part, dict) and part.get("type") == "image":
                         img = part.get("image")
                         if img is not None:
-                            images.append(img)
+                            images.append(_resize_mlx_vlm_image(img, resize))
                         new_content.append({"type": "image"})
                     else:
                         new_content.append(part)
@@ -990,9 +1030,9 @@ def _adapt_for_mlx_vlm(items):
         if images:
             out["image"] = images[0] if len(images) == 1 else images
         elif "image" in item:
-            out["image"] = item["image"]
+            out["image"] = _resize_mlx_vlm_images(item["image"], resize)
         elif "images" in item:
-            out["images"] = item["images"]
+            out["images"] = _resize_mlx_vlm_images(item["images"], resize)
         adapted.append(out)
     return adapted
 
@@ -1168,6 +1208,25 @@ def _run_mlx_training(event_queue, stop_queue, config):
 
     is_vlm = bool(is_dataset_image and getattr(model, "_is_vlm_model", False))
     model._is_vlm_model = is_vlm
+    vision_image_size = config.get("vision_image_size")
+    # DeepSeek OCR uses a coupled preset tuple; skip resize like the Torch path.
+    _model_name_lower = str(config.get("model_name", "")).lower()
+    _is_deepseek_ocr = "deepseek" in _model_name_lower and "ocr" in _model_name_lower
+    if is_vlm and vision_image_size is not None and _is_deepseek_ocr:
+        _send(
+            "status",
+            status_message = (
+                "MLX vision image resize ignored for DeepSeek OCR "
+                "(uses fixed Gundam preset)."
+            ),
+        )
+        vision_image_size = None
+    elif is_vlm and vision_image_size is not None:
+        vision_image_size = int(vision_image_size)
+        _send(
+            "status",
+            status_message = f"MLX vision image resize: {vision_image_size} (max dimension)",
+        )
 
     # ── 2. Apply LoRA / full FT ──
     # Pass gradient_checkpointing as string ("mlx"/"unsloth"/"none"/etc.)
@@ -1302,7 +1361,10 @@ def _run_mlx_training(event_queue, stop_queue, config):
                 progress_callback = _fmt_progress,
             )
             if vlm_info.get("success"):
-                dataset = _adapt_for_mlx_vlm(vlm_info["dataset"])
+                dataset = _adapt_for_mlx_vlm(
+                    vlm_info["dataset"],
+                    resize = vision_image_size,
+                )
             else:
                 errors = vlm_info.get("errors", [])
                 raise ValueError(
@@ -1317,7 +1379,10 @@ def _run_mlx_training(event_queue, stop_queue, config):
                     dataset_name = hf_dataset or "local",
                 )
                 if ev_info.get("success"):
-                    eval_dataset = _adapt_for_mlx_vlm(ev_info["dataset"])
+                    eval_dataset = _adapt_for_mlx_vlm(
+                        ev_info["dataset"],
+                        resize = vision_image_size,
+                    )
 
         elif format_type:
             _send("status", status_message = f"Formatting dataset ({format_type})...")
@@ -2248,6 +2313,7 @@ def run_training_process(
             eval_dataset = eval_dataset,
             eval_steps = eval_steps,
             max_seq_length = config.get("max_seq_length", 2048),
+            vision_image_size = config.get("vision_image_size"),
             optim = config.get("optim", "adamw_8bit"),
             lr_scheduler_type = config.get("lr_scheduler_type", "linear"),
             is_cpt = is_cpt,
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index 7c53b0fee5..c6be1eff4e 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -5,10 +5,17 @@
 Pydantic schemas for Training API
 """
 
+import re
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 from typing import Any, Optional, List, Dict, Literal
 
 
+# ASCII integer with an optional single sign. Used by _check_vision_image_size
+# to reject "++512", "--256", and Unicode-digit strings ("５１２", "٥١٢") that
+# would otherwise slip through str.isdigit() + int().
+_INT_RE = re.compile(r"[+-]?[0-9]+")
+
+
 _MAX_BATCH_SIZE = 4096
 _MAX_GRAD_ACCUM = 4096
 _MAX_STEPS = 1_000_000
@@ -18,6 +25,9 @@ _MAX_SEQ_LENGTH = 2_000_000
 _MAX_LR_VALUE = 1.0
 _MAX_LORA_R = 16_384
 _MAX_LORA_ALPHA = 32_768
+_MIN_VISION_IMAGE_SIZE = 256
+# 2048 was the most I could get most llms to work at without getting unstable
+_MAX_VISION_IMAGE_SIZE = 2048
 
 
 def _parse_lr(v: Any) -> float:
@@ -58,6 +68,10 @@ class TrainingStartRequest(BaseModel):
     hf_token: Optional[str] = Field(None, description = "HuggingFace token")
     load_in_4bit: bool = Field(True, description = "Load model in 4-bit quantization")
     max_seq_length: int = Field(2048, description = "Maximum sequence length")
+    vision_image_size: Optional[int] = Field(
+        None,
+        description = "Optional maximum image side length for VLM training. Null uses model default.",
+    )
     trust_remote_code: bool = Field(
         False,
         description = "Allow loading models with custom code (e.g. NVIDIA Nemotron). Only enable for repos you trust.",
@@ -159,6 +173,40 @@ class TrainingStartRequest(BaseModel):
             )
         return v
 
+    @field_validator("vision_image_size", mode = "before")
+    @classmethod
+    def _check_vision_image_size(cls, v: Any) -> Optional[int]:
+        # mode="before" sees True/False as bool (not 1/0) for a precise error.
+        if v is None:
+            return v
+        if isinstance(v, bool):
+            raise ValueError("vision_image_size must be an integer or null")
+        if isinstance(v, int):
+            coerced = v
+        elif isinstance(v, str) and _INT_RE.fullmatch(v.strip()):
+            coerced = int(v.strip())
+        elif isinstance(v, float) and v.is_integer():
+            coerced = int(v)
+        else:
+            # numpy ints / Integral subclasses, without a hard numpy import.
+            try:
+                import numbers
+
+                if isinstance(v, numbers.Integral):
+                    coerced = int(v)
+                elif isinstance(v, numbers.Real) and float(v).is_integer():
+                    coerced = int(v)
+                else:
+                    raise TypeError
+            except Exception:
+                raise ValueError("vision_image_size must be an integer or null")
+        if coerced < _MIN_VISION_IMAGE_SIZE or coerced > _MAX_VISION_IMAGE_SIZE:
+            raise ValueError(
+                f"vision_image_size must be in [{_MIN_VISION_IMAGE_SIZE}, "
+                f"{_MAX_VISION_IMAGE_SIZE}] (got {coerced!r})"
+            )
+        return coerced
+
     @field_validator("warmup_steps")
     @classmethod
     def _check_warmup_steps(cls, v: Optional[int]) -> Optional[int]:
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 6e2413b3e9..41a9e15562 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -194,6 +194,7 @@ async def start_training(
             "hf_token": request.hf_token or "",
             "load_in_4bit": request.load_in_4bit,
             "max_seq_length": request.max_seq_length,
+            "vision_image_size": request.vision_image_size,
             "hf_dataset": request.hf_dataset or "",
             "local_datasets": request.local_datasets,
             "local_eval_datasets": request.local_eval_datasets,
diff --git a/studio/backend/tests/test_mlx_training_worker_config.py b/studio/backend/tests/test_mlx_training_worker_config.py
index 98c7bdaa55..c36363b1ae 100644
--- a/studio/backend/tests/test_mlx_training_worker_config.py
+++ b/studio/backend/tests/test_mlx_training_worker_config.py
@@ -66,6 +66,7 @@ def _load_worker_module():
 _worker = _load_worker_module()
 _normalize_mlx_studio_optimizer = _worker._normalize_mlx_studio_optimizer
 _normalize_mlx_studio_scheduler = _worker._normalize_mlx_studio_scheduler
+_mlx_vlm_max_resized_size = _worker._mlx_vlm_max_resized_size
 
 
 def test_mlx_studio_optimizer_aliases_are_explicit():
@@ -82,3 +83,14 @@ def test_mlx_studio_rejects_unknown_optimizer():
 def test_mlx_studio_rejects_unknown_scheduler():
     with pytest.raises(ValueError, match = "Unsupported LR scheduler for MLX training"):
         _normalize_mlx_studio_scheduler("linear_typo")
+
+
+def test_mlx_vlm_resize_uses_max_dimension_like_torch_trainer():
+    assert _mlx_vlm_max_resized_size(1000, 500, 512) == (512, 256)
+    assert _mlx_vlm_max_resized_size(500, 1000, 512) == (256, 512)
+    assert _mlx_vlm_max_resized_size(1000, 1000, 512) == (512, 512)
+    assert _mlx_vlm_max_resized_size(256, 128, 1536) == (256, 128)
+    assert _mlx_vlm_max_resized_size(512, 256, 512) == (512, 256)
+    # Half-pixel cases must match the Torch collator (not banker's round).
+    assert _mlx_vlm_max_resized_size(333, 1000, 500) == (167, 500)
+    assert _mlx_vlm_max_resized_size(1000, 333, 500) == (500, 167)
diff --git a/studio/backend/tests/test_studio_train_validation.py b/studio/backend/tests/test_studio_train_validation.py
index 7ffa9bb384..6df491610b 100644
--- a/studio/backend/tests/test_studio_train_validation.py
+++ b/studio/backend/tests/test_studio_train_validation.py
@@ -18,6 +18,8 @@ from models.training import (
     _MAX_LORA_ALPHA,
     _MAX_LORA_R,
     _MAX_SEQ_LENGTH,
+    _MAX_VISION_IMAGE_SIZE,
+    _MIN_VISION_IMAGE_SIZE,
 )
 
 
@@ -62,6 +64,52 @@ class TestBatchSizeCap:
             _check_field("batch_size", 0)
 
 
+class TestVisionImageSizeCap:
+    def test_none_accepts_model_default(self):
+        _check_field("vision_image_size", None)
+
+    @pytest.mark.parametrize(
+        "value",
+        [_MIN_VISION_IMAGE_SIZE, 640, 1000, _MAX_VISION_IMAGE_SIZE],
+    )
+    def test_in_range_accepts(self, value):
+        _check_field("vision_image_size", value)
+        assert _MIN_VISION_IMAGE_SIZE == 256
+        assert _MAX_VISION_IMAGE_SIZE == 2048
+
+    @pytest.mark.parametrize(
+        "value",
+        [_MIN_VISION_IMAGE_SIZE - 1, _MAX_VISION_IMAGE_SIZE + 1, 640.5, True],
+    )
+    def test_invalid_rejects(self, value):
+        with pytest.raises(ValidationError):
+            _check_field("vision_image_size", value)
+
+    @pytest.mark.parametrize("value", [True, False])
+    def test_bool_error_says_integer_not_range(self, value):
+        # Regression guard: bools must say "integer or null", not "in [256, 2048]".
+        with pytest.raises(ValidationError) as exc:
+            _check_field("vision_image_size", value)
+        assert "integer or null" in str(exc.value)
+
+    @pytest.mark.parametrize("value", ["++512", "--256", "+-+512", "+", "-"])
+    def test_multi_sign_string_says_integer_not_raw(self, value):
+        # Regression guard: multi-sign strings must not leak int()'s raw
+        # "invalid literal" message; precise contract is "integer or null".
+        with pytest.raises(ValidationError) as exc:
+            _check_field("vision_image_size", value)
+        assert "integer or null" in str(exc.value)
+        assert "invalid literal" not in str(exc.value)
+
+    @pytest.mark.parametrize("value", ["５１２", "٥١٢", "१०२४"])
+    def test_unicode_digit_string_rejected(self, value):
+        # Full-width / Arabic-Indic / Devanagari digits must be rejected so the
+        # value reaching the backend equals the ASCII the user typed.
+        with pytest.raises(ValidationError) as exc:
+            _check_field("vision_image_size", value)
+        assert "integer or null" in str(exc.value)
+
+
 class TestLoraRCap:
     def test_at_cap_accepts(self):
         _check_field("lora_r", _MAX_LORA_R)
diff --git a/studio/frontend/src/config/training.ts b/studio/frontend/src/config/training.ts
index e9fe1d679c..c0a60d0de2 100644
--- a/studio/frontend/src/config/training.ts
+++ b/studio/frontend/src/config/training.ts
@@ -108,6 +108,7 @@ export const LR_DEFAULT_CPT = 5e-5;
 export const DEFAULT_HYPERPARAMS = {
   epochs: 3,
   contextLength: 2048,
+  visionImageSize: null as number | null,
   learningRate: LR_DEFAULT_LORA,
   // null = let backend auto-compute (lr/10 per Unsloth CPT recipe). Only used by CPT.
   embeddingLearningRate: null as number | null,
diff --git a/studio/frontend/src/features/studio/sections/params-section.tsx b/studio/frontend/src/features/studio/sections/params-section.tsx
index 9749eba9b7..f254921fa6 100644
--- a/studio/frontend/src/features/studio/sections/params-section.tsx
+++ b/studio/frontend/src/features/studio/sections/params-section.tsx
@@ -175,12 +175,20 @@ export function ParamsSection(): ReactElement {
   const isCpt = store.trainingMethod === "cpt";
   const isRawText = isRawTextDatasetFormat(store.datasetFormat);
   const showVisionLora = store.isVisionModel && store.isDatasetImage === true;
+  // DeepSeek OCR uses a coupled preset; backend ignores user image size.
+  const _selectedModelLower = (store.selectedModel ?? "").toLowerCase();
+  const isDeepseekOcr =
+    _selectedModelLower.includes("deepseek") &&
+    _selectedModelLower.includes("ocr");
+  const showVisionImageSize = showVisionLora && !isDeepseekOcr;
   const [loraOpen, setLoraOpen] = useState(false);
   const [hyperOpen, setHyperOpen] = useState(false);
   const needsExpandedHeight = isCpt || (isLora && loraOpen) || hyperOpen;
   const [ctxInput, setCtxInput] = useState(String(store.contextLength));
   const ctxAnchorRef = useRef<HTMLDivElement>(null);
   const ctxItems = CONTEXT_LENGTHS.map(String);
+  // Backend validator allows [256, 2048]; offer the full span.
+  const visionImageSizePresets = [256, 384, 512, 768, 1024, 1536, 2048];
 
   // Keep input in sync when the store value changes externally
   // (e.g. model defaults being applied after model selection).
@@ -947,6 +955,62 @@ export function ParamsSection(): ReactElement {
                 </TabsContent>
 
                 <TabsContent value="memory" className="mt-3 flex flex-col gap-3">
+                  {showVisionImageSize && (
+                    <Row
+                      label="Image Size"
+                      tooltip={
+                        <>
+                          Resize images by maximum side length. Default uses the
+                          model image size. Larger images use up more context. Does not upscale or change aspect ratio.{" "}
+                          <a
+                            href="https://unsloth.ai/docs/basics/vision-fine-tuning"
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="text-primary underline"
+                          >
+                            Read more
+                          </a>
+                        </>
+                      }
+                    >
+                      <Select
+                        value={
+                          store.visionImageSize == null
+                            ? "default"
+                            : String(store.visionImageSize)
+                        }
+                        onValueChange={(value) => {
+                          if (value === "default") {
+                            store.setVisionImageSize(null);
+                            return;
+                          }
+                          store.setVisionImageSize(Number(value));
+                        }}
+                      >
+                        <SelectTrigger className="w-32">
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          <SelectItem value="default">Default</SelectItem>
+                          {store.visionImageSize != null &&
+                            !visionImageSizePresets.includes(
+                              store.visionImageSize,
+                            ) && (
+                              <SelectItem
+                                value={String(store.visionImageSize)}
+                              >
+                                {store.visionImageSize}
+                              </SelectItem>
+                            )}
+                          {visionImageSizePresets.map((size) => (
+                            <SelectItem key={size} value={String(size)}>
+                              {size}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                    </Row>
+                  )}
                   <Row
                     label={t("studio.params.gradCheckpoint")}
                     tooltip={
diff --git a/studio/frontend/src/features/studio/sections/training-section.tsx b/studio/frontend/src/features/studio/sections/training-section.tsx
index 7ce2462fc1..adeb1a7b14 100644
--- a/studio/frontend/src/features/studio/sections/training-section.tsx
+++ b/studio/frontend/src/features/studio/sections/training-section.tsx
@@ -81,7 +81,24 @@ export function TrainingSection() {
   };
 
   const handleSaveConfig = () => {
-    const yamlStr = serializeConfigToYaml(store, store.isVisionModel);
+    // isDatasetImage is null in three windows: before a dataset check
+    // completes, after dataset edits, and on import. Treat all three as
+    // "save it" so the user's choice is never silently dropped while we
+    // wait to confirm the dataset type. Only a confirmed text-only dataset
+    // (=== false) suppresses the vision fields.
+    const includeVisionFields =
+      store.isVisionModel && store.isDatasetImage !== false;
+    // DeepSeek OCR ignores vision_image_size; don't emit it to YAML either,
+    // or a later import on a non-DeepSeek model would activate the stale value.
+    const selectedModelLower = (store.selectedModel ?? "").toLowerCase();
+    const isDeepseekOcr =
+      selectedModelLower.includes("deepseek") &&
+      selectedModelLower.includes("ocr");
+    const yamlStr = serializeConfigToYaml(
+      store,
+      includeVisionFields,
+      includeVisionFields && !isDeepseekOcr,
+    );
     const blob = new Blob([yamlStr], { type: "text/yaml" });
     const url = URL.createObjectURL(blob);
     const a = document.createElement("a");
diff --git a/studio/frontend/src/features/training/api/mappers.ts b/studio/frontend/src/features/training/api/mappers.ts
index 5d81f0df9c..1223888b11 100644
--- a/studio/frontend/src/features/training/api/mappers.ts
+++ b/studio/frontend/src/features/training/api/mappers.ts
@@ -23,7 +23,12 @@ export function buildTrainingStartPayload(
   const isCpt = config.trainingMethod === "cpt";
   const adapterMethod = config.trainingMethod !== "full";
   const isQloraMethod = config.trainingMethod === "qlora";
-  const isFourBitModel = (config.selectedModel ?? "").toLowerCase().includes("4bit");
+  const _selectedModelLower = (config.selectedModel ?? "").toLowerCase();
+  const isFourBitModel = _selectedModelLower.includes("4bit");
+  // DeepSeek OCR ignores user-selected image size; do not send it.
+  const isDeepseekOcr =
+    _selectedModelLower.includes("deepseek") &&
+    _selectedModelLower.includes("ocr");
   const isEmbedding = config.isEmbeddingModel;
   const isRawText = isRawTextDatasetFormat(config.datasetFormat);
   const hfDataset = config.datasetSource === "huggingface" ? config.dataset : null;
@@ -55,6 +60,10 @@ export function buildTrainingStartPayload(
     hf_token: config.hfToken.trim() || null,
     load_in_4bit: (adapterMethod && isQloraMethod) || (isCpt && isFourBitModel),
     max_seq_length: config.contextLength,
+    vision_image_size:
+      config.isVisionModel && config.isDatasetImage === true && !isDeepseekOcr
+        ? config.visionImageSize
+        : null,
     trust_remote_code: config.trustRemoteCode ?? false,
     hf_dataset: hfDataset,
     subset: hfDataset ? config.datasetSubset : null,
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index e512b9e28d..8fecfaf7b8 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -27,6 +27,7 @@ interface BackendTrainingDefaults {
   eval_steps?: number;
   weight_decay?: number;
   random_seed?: number;
+  vision_image_size?: number | string | null;
   packing?: boolean;
   train_on_completions?: boolean;
   gradient_checkpointing?: "none" | "true" | "unsloth";
diff --git a/studio/frontend/src/features/training/lib/model-defaults.ts b/studio/frontend/src/features/training/lib/model-defaults.ts
index 8bc9c4e064..3a0a14b150 100644
--- a/studio/frontend/src/features/training/lib/model-defaults.ts
+++ b/studio/frontend/src/features/training/lib/model-defaults.ts
@@ -28,6 +28,7 @@ type ModelDefaultsPatch = Partial<
     | "trainOnCompletions"
     | "gradientCheckpointing"
     | "randomSeed"
+    | "visionImageSize"
     | "enableWandb"
     | "wandbProject"
     | "enableTensorboard"
@@ -129,6 +130,25 @@ export function mapBackendModelConfigToTrainingPatch(
   const randomSeed = toNumber(training?.random_seed);
   if (randomSeed !== undefined) patch.randomSeed = randomSeed;
 
+  // Only patch when the config carries the key; model-switch reset lives in
+  // setSelectedModel so same-model reloads don't wipe a user's choice.
+  if (Object.hasOwn(training ?? {}, "vision_image_size")) {
+    const raw = training?.vision_image_size;
+    if (raw == null) {
+      patch.visionImageSize = null;
+    } else {
+      // Mirror studio/backend/models/training.py:_check_vision_image_size:
+      // drop anything outside [_MIN_VISION_IMAGE_SIZE, _MAX_VISION_IMAGE_SIZE]
+      // so the store/UI never show a value the backend would reject.
+      const n = toNumber(raw);
+      if (n !== undefined && Number.isInteger(n) && n >= 256 && n <= 2048) {
+        patch.visionImageSize = n;
+      } else {
+        patch.visionImageSize = null;
+      }
+    }
+  }
+
   const packing = toBoolean(training?.packing);
   if (packing !== undefined) patch.packing = packing;
 
diff --git a/studio/frontend/src/features/training/lib/yaml-config.ts b/studio/frontend/src/features/training/lib/yaml-config.ts
index d168da5347..1deabf3547 100644
--- a/studio/frontend/src/features/training/lib/yaml-config.ts
+++ b/studio/frontend/src/features/training/lib/yaml-config.ts
@@ -27,8 +27,27 @@ export function parseYamlConfig(text: string): BackendModelConfig {
     console.warn("Ignored unknown YAML keys:", unknownKeys.join(", "));
   }
 
+  // File import is authoritative: forge vision_image_size = null when the
+  // training section is missing, malformed, or missing the key, so a stale
+  // store value cannot survive an import. (Same-model defaults reloads
+  // preserve user choice via Object.hasOwn in model-defaults.ts.)
+  const rawTraining = raw.training;
+  const isPlainTrainingObject =
+    rawTraining != null &&
+    typeof rawTraining === "object" &&
+    !Array.isArray(rawTraining);
+  let trainingObj: Record<string, unknown>;
+  if (!isPlainTrainingObject) {
+    trainingObj = { vision_image_size: null };
+  } else {
+    trainingObj = { ...(rawTraining as Record<string, unknown>) };
+    if (!Object.hasOwn(trainingObj, "vision_image_size")) {
+      trainingObj.vision_image_size = null;
+    }
+  }
+
   return {
-    training: (raw.training ?? undefined) as BackendModelConfig["training"],
+    training: trainingObj as BackendModelConfig["training"],
     lora: (raw.lora ?? undefined) as BackendModelConfig["lora"],
     logging: (raw.logging ?? undefined) as BackendModelConfig["logging"],
   };
@@ -41,6 +60,7 @@ export function parseYamlConfig(text: string): BackendModelConfig {
 export function serializeConfigToYaml(
   state: TrainingConfigState,
   includeVisionFields: boolean,
+  includeVisionImageSize: boolean = includeVisionFields,
 ): string {
   const lora: Record<string, unknown> = {
     lora_r: state.loraRank,
@@ -58,25 +78,31 @@ export function serializeConfigToYaml(
     lora.finetune_mlp_modules = state.finetuneMLPModules;
   }
 
+  const training: Record<string, unknown> = {
+    max_seq_length: state.contextLength,
+    num_epochs: state.epochs,
+    learning_rate: state.learningRate,
+    batch_size: state.batchSize,
+    gradient_accumulation_steps: state.gradientAccumulation,
+    warmup_steps: state.warmupSteps,
+    max_steps: state.maxSteps,
+    save_steps: state.saveSteps,
+    eval_steps: state.evalSteps,
+    weight_decay: state.weightDecay,
+    random_seed: state.randomSeed,
+    packing: state.packing,
+    train_on_completions: state.trainOnCompletions,
+    gradient_checkpointing: state.gradientCheckpointing,
+    optim: state.optimizerType,
+    lr_scheduler_type: state.lrSchedulerType,
+  };
+
+  if (includeVisionImageSize) {
+    training.vision_image_size = state.visionImageSize;
+  }
+
   const config = {
-    training: {
-      max_seq_length: state.contextLength,
-      num_epochs: state.epochs,
-      learning_rate: state.learningRate,
-      batch_size: state.batchSize,
-      gradient_accumulation_steps: state.gradientAccumulation,
-      warmup_steps: state.warmupSteps,
-      max_steps: state.maxSteps,
-      save_steps: state.saveSteps,
-      eval_steps: state.evalSteps,
-      weight_decay: state.weightDecay,
-      random_seed: state.randomSeed,
-      packing: state.packing,
-      train_on_completions: state.trainOnCompletions,
-      gradient_checkpointing: state.gradientCheckpointing,
-      optim: state.optimizerType,
-      lr_scheduler_type: state.lrSchedulerType,
-    },
+    training,
     lora,
   };
 
diff --git a/studio/frontend/src/features/training/stores/training-config-store.ts b/studio/frontend/src/features/training/stores/training-config-store.ts
index ef16f641f5..137669f8b8 100644
--- a/studio/frontend/src/features/training/stores/training-config-store.ts
+++ b/studio/frontend/src/features/training/stores/training-config-store.ts
@@ -390,6 +390,8 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
                 error instanceof Error
                   ? error.message
                   : "Failed to load model defaults",
+              // Defaults load failed; reset so no prior model's value lingers.
+              visionImageSize: DEFAULT_HYPERPARAMS.visionImageSize,
             });
 
             // Fallback vision check if config endpoint fails.
@@ -498,7 +500,16 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
         },
         setSelectedModel: (selectedModel) => {
           const previousModel = get().selectedModel;
-          set({ selectedModel, modelDefaultsError: null });
+          // Reset vision_image_size on a true switch only; same-model reloads
+          // go through the mapper, which preserves the user's choice.
+          const patch: { selectedModel: string | null; modelDefaultsError: null; visionImageSize?: number | null } = {
+            selectedModel,
+            modelDefaultsError: null,
+          };
+          if (selectedModel !== previousModel) {
+            patch.visionImageSize = DEFAULT_HYPERPARAMS.visionImageSize;
+          }
+          set(patch);
 
           if (!selectedModel) {
             _modelConfigController?.abort();
@@ -701,6 +712,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
         }),
         setEpochs: (epochs) => set({ epochs }),
         setContextLength: (contextLength) => set({ contextLength }),
+        setVisionImageSize: (visionImageSize) => set({ visionImageSize }),
         setLearningRate: (learningRate) => {
           _learningRateManuallySet = true;
           set({ learningRate });
@@ -755,7 +767,10 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
         resetToModelDefaults: () => {
           const { selectedModel } = get();
           if (!selectedModel) return;
-          set({ modelDefaultsAppliedFor: null });
+          set({
+            modelDefaultsAppliedFor: null,
+            visionImageSize: DEFAULT_HYPERPARAMS.visionImageSize,
+          });
           loadAndApplyModelDefaults(selectedModel);
         },
         applyConfigPatch: (config: BackendModelConfig) => {
diff --git a/studio/frontend/src/features/training/types/api.ts b/studio/frontend/src/features/training/types/api.ts
index 0cb881e634..5c12e71186 100644
--- a/studio/frontend/src/features/training/types/api.ts
+++ b/studio/frontend/src/features/training/types/api.ts
@@ -7,6 +7,7 @@ export interface TrainingStartRequest {
   hf_token: string | null;
   load_in_4bit: boolean;
   max_seq_length: number;
+  vision_image_size?: number | null;
   /** Allow loading models with custom code. Only enable for repos you trust. */
   trust_remote_code?: boolean;
   hf_dataset: string | null;
diff --git a/studio/frontend/src/features/training/types/config.ts b/studio/frontend/src/features/training/types/config.ts
index 5b156316ca..f40f053e8b 100644
--- a/studio/frontend/src/features/training/types/config.ts
+++ b/studio/frontend/src/features/training/types/config.ts
@@ -82,6 +82,7 @@ export interface TrainingConfigState {
   finetuneMLPModules: boolean;
   targetModules: string[];
   maxPositionEmbeddings: number | null;
+  visionImageSize: number | null;
 }
 
 export interface TrainingConfigActions {
@@ -115,6 +116,7 @@ export interface TrainingConfigActions {
   setUploadedEvalFile: (file: string | null) => void;
   setEpochs: (epochs: number) => void;
   setContextLength: (length: number) => void;
+  setVisionImageSize: (size: number | null) => void;
   setLearningRate: (rate: number) => void;
   setEmbeddingLearningRate: (rate: number | null) => void;
   setOptimizerType: (value: string) => void;

From 9222ffd9b48e9c93012e026c23aa2152c5b4f294 Mon Sep 17 00:00:00 2001
From: alkinun <alkinunl@gmail.com>
Date: Wed, 27 May 2026 15:09:34 +0300
Subject: [PATCH 007/222] Studio: add configurable CPU thread pool limit
 (#5760)

* Studio: add configurable CPU thread pool limit

* Studio: report invalid CPU thread setting cleanly

* Studio: also cover uvicorn main:app, harden tests, move docs to advanced

---------

Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
Co-authored-by: danielhanchen <danielhanchen@gmail.com>
---
 README.md                                |   3 +
 studio/backend/main.py                   |  11 ++
 studio/backend/run.py                    |  10 ++
 studio/backend/tests/test_cpu_threads.py | 152 +++++++++++++++++++++++
 studio/backend/utils/cpu_threads.py      |  39 ++++++
 5 files changed, 215 insertions(+)
 create mode 100644 studio/backend/tests/test_cpu_threads.py
 create mode 100644 studio/backend/utils/cpu_threads.py

diff --git a/README.md b/README.md
index 3699c50736..eab202f407 100644
--- a/README.md
+++ b/README.md
@@ -215,6 +215,9 @@ Then to launch every time:
 unsloth studio -p 8888
 ```
 
+#### Advanced launch options
+On high core-count systems, set `UNSLOTH_CPU_THREADS=<N>` (e.g. `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`) to cap Studio's native CPU thread pools (OpenMP, MKL, OpenBLAS, NumExpr) and reduce idle worker threads. Unset = current behaviour (each runtime picks its own pool size based on detected cores). Explicit per-library env vars (`OMP_NUM_THREADS=...` etc.) always take precedence over `UNSLOTH_CPU_THREADS`.
+
 #### Uninstall
 The recommended way to fully remove Unsloth Studio is the matching uninstall script for your OS. It stops any running servers, removes the install dir, the launcher data dir, the desktop shortcut, and any platform-specific entries (macOS `.app` bundle + Launch Services on Mac; Start Menu, `HKCU\Software\Unsloth` registry key and user `PATH` entries on Windows):
 
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 689241b915..5b92e1262e 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -18,6 +18,17 @@ _backend_dir = str(_Path(__file__).parent)
 if _backend_dir not in sys.path:
     sys.path.insert(0, _backend_dir)
 
+# `uvicorn main:app` bypasses run.py; seed thread caps here too.
+from utils.cpu_threads import configure_cpu_threads
+
+try:
+    configure_cpu_threads()
+except ValueError as exc:
+    _raw = os.environ.get("UNSLOTH_CPU_THREADS")
+    raise SystemExit(
+        f"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}"
+    ) from None
+
 # Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
 # any library imports that trigger attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
diff --git a/studio/backend/run.py b/studio/backend/run.py
index e96e609659..5ddf404370 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -19,6 +19,16 @@ backend_dir = Path(__file__).parent
 if str(backend_dir) not in sys.path:
     sys.path.insert(0, str(backend_dir))
 
+from utils.cpu_threads import configure_cpu_threads
+
+try:
+    configure_cpu_threads()
+except ValueError as exc:
+    configured = os.environ.get("UNSLOTH_CPU_THREADS")
+    raise SystemExit(
+        f"Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {exc}"
+    ) from None
+
 # Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
 # any library imports that trigger attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
diff --git a/studio/backend/tests/test_cpu_threads.py b/studio/backend/tests/test_cpu_threads.py
new file mode 100644
index 0000000000..0dbcbdb74b
--- /dev/null
+++ b/studio/backend/tests/test_cpu_threads.py
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for Studio's early CPU thread-pool configuration."""
+
+import ast
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from utils.cpu_threads import _THREAD_POOL_ENV_VARS, configure_cpu_threads
+
+
+_BACKEND_DIR = Path(__file__).resolve().parent.parent
+_RUN_PY = _BACKEND_DIR / "run.py"
+_MAIN_PY = _BACKEND_DIR / "main.py"
+
+
+# Explicit positive integers seed all four native pool env vars.
+def test_cpu_thread_cap_seeds_native_pool_limits():
+    env = {"UNSLOTH_CPU_THREADS": " 6 "}
+
+    configure_cpu_threads(env)
+
+    assert {variable: env[variable] for variable in _THREAD_POOL_ENV_VARS} == {
+        variable: "6" for variable in _THREAD_POOL_ENV_VARS
+    }
+
+
+# Explicit per-library values win over the Studio knob via setdefault.
+def test_cpu_thread_cap_preserves_runtime_specific_override():
+    env = {"UNSLOTH_CPU_THREADS": "4", "OMP_NUM_THREADS": "2"}
+
+    configure_cpu_threads(env)
+
+    assert env["OMP_NUM_THREADS"] == "2"
+    assert env["MKL_NUM_THREADS"] == "4"
+
+
+# Whitespace / plus-prefix / leading zero all normalise via int().
+@pytest.mark.parametrize("raw", ["+4", "007", "  4  "])
+def test_cpu_thread_cap_normalises_valid_inputs(raw):
+    env = {"UNSLOTH_CPU_THREADS": raw}
+
+    configure_cpu_threads(env)
+
+    assert env["OMP_NUM_THREADS"] == str(int(raw.strip()))
+
+
+# Unset / empty / whitespace -> no env mutation (pure opt-in).
+@pytest.mark.parametrize("raw", [None, "", "   ", "\t"])
+def test_cpu_thread_cap_is_opt_in(raw):
+    env = {} if raw is None else {"UNSLOTH_CPU_THREADS": raw}
+    snapshot = dict(env)
+
+    configure_cpu_threads(env)
+
+    assert env == snapshot
+    assert all(variable not in env for variable in _THREAD_POOL_ENV_VARS)
+
+
+# Anything that is not a positive integer raises a clear ValueError.
+@pytest.mark.parametrize("raw", ["zero", "0", "-3", "1.5", "abc", "8a", "0x4", "1e3", "4 0"])
+def test_cpu_thread_cap_requires_positive_integer(raw):
+    with pytest.raises(ValueError, match="must be a positive integer"):
+        configure_cpu_threads({"UNSLOTH_CPU_THREADS": raw})
+
+
+# env=None path uses real os.environ (production call from run.py / main.py).
+def test_cpu_thread_cap_uses_os_environ_when_env_is_none(monkeypatch):
+    for variable in (*_THREAD_POOL_ENV_VARS, "UNSLOTH_CPU_THREADS"):
+        monkeypatch.delenv(variable, raising=False)
+    monkeypatch.setenv("UNSLOTH_CPU_THREADS", "3")
+
+    configure_cpu_threads()
+
+    for variable in _THREAD_POOL_ENV_VARS:
+        assert os.environ[variable] == "3"
+
+
+# Calling twice must not flip any seeded value.
+def test_cpu_thread_cap_idempotent(monkeypatch):
+    for variable in (*_THREAD_POOL_ENV_VARS, "UNSLOTH_CPU_THREADS"):
+        monkeypatch.delenv(variable, raising=False)
+    monkeypatch.setenv("UNSLOTH_CPU_THREADS", "5")
+
+    configure_cpu_threads()
+    snapshot = {v: os.environ.get(v) for v in _THREAD_POOL_ENV_VARS}
+    configure_cpu_threads()
+
+    assert {v: os.environ.get(v) for v in _THREAD_POOL_ENV_VARS} == snapshot
+
+
+def _ast_line_of_configure_call(source: str) -> int:
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id == "configure_cpu_threads"
+        ):
+            return node.lineno
+    raise AssertionError("configure_cpu_threads() call not found")
+
+
+def _ast_line_of_platform_compat_import(source: str) -> int:
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "_platform_compat":
+                    return node.lineno
+    raise AssertionError("_platform_compat import not found")
+
+
+# AST-based ordering: configure_cpu_threads() must precede _platform_compat
+# in both run.py and main.py. Robust to formatting / line shifts.
+@pytest.mark.parametrize("entry_point", [_RUN_PY, _MAIN_PY])
+def test_cpu_thread_configuration_runs_before_backend_imports(entry_point):
+    source = entry_point.read_text()
+    call_line = _ast_line_of_configure_call(source)
+    compat_line = _ast_line_of_platform_compat_import(source)
+    assert call_line < compat_line, (
+        f"{entry_point.name}: configure_cpu_threads() (line {call_line}) "
+        f"must precede import _platform_compat (line {compat_line})"
+    )
+
+
+# Invalid env -> exit 1, one-line stderr, no traceback, gated before any
+# heavy import. Parametrised over both entry points.
+@pytest.mark.parametrize("entry_point", [_RUN_PY, _MAIN_PY])
+def test_invalid_cpu_thread_cap_exits_without_traceback(entry_point):
+    env = os.environ.copy()
+    env["UNSLOTH_CPU_THREADS"] = "not-a-count"
+
+    result = subprocess.run(
+        [sys.executable, str(entry_point)],
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 1
+    assert (
+        "Error: Invalid UNSLOTH_CPU_THREADS value 'not-a-count': "
+        "UNSLOTH_CPU_THREADS must be a positive integer"
+    ) in result.stderr
+    assert "Traceback" not in result.stderr
+    assert "_platform_compat" not in result.stderr
diff --git a/studio/backend/utils/cpu_threads.py b/studio/backend/utils/cpu_threads.py
new file mode 100644
index 0000000000..922f95ce55
--- /dev/null
+++ b/studio/backend/utils/cpu_threads.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Early CPU thread-pool configuration for Studio processes."""
+
+import os
+from typing import MutableMapping, Optional
+
+
+_THREAD_POOL_ENV_VARS = (
+    "OMP_NUM_THREADS",
+    "MKL_NUM_THREADS",
+    "OPENBLAS_NUM_THREADS",
+    "NUMEXPR_NUM_THREADS",
+)
+
+
+def configure_cpu_threads(env: Optional[MutableMapping[str, str]] = None) -> None:
+    """Apply ``UNSLOTH_CPU_THREADS`` to native CPU pools when configured.
+
+    This must run before importing libraries that initialize an OpenMP or
+    BLAS thread pool. Library-specific variables are left untouched so users
+    can override a single runtime independently.
+    """
+    environ = os.environ if env is None else env
+    configured = environ.get("UNSLOTH_CPU_THREADS", "").strip()
+    if not configured:
+        return
+
+    try:
+        thread_count = int(configured)
+    except ValueError as exc:
+        raise ValueError("UNSLOTH_CPU_THREADS must be a positive integer") from exc
+    if thread_count < 1:
+        raise ValueError("UNSLOTH_CPU_THREADS must be a positive integer")
+
+    value = str(thread_count)
+    for variable in _THREAD_POOL_ENV_VARS:
+        environ.setdefault(variable, value)

From 131fa4fcae20a97b57da451cafc0c917803a8caa Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 27 May 2026 05:15:45 -0700
Subject: [PATCH 008/222] Trim README Advanced launch options blurb (#5809)

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index eab202f407..ecf0f8a7a3 100644
--- a/README.md
+++ b/README.md
@@ -216,7 +216,7 @@ unsloth studio -p 8888
 ```
 
 #### Advanced launch options
-On high core-count systems, set `UNSLOTH_CPU_THREADS=<N>` (e.g. `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`) to cap Studio's native CPU thread pools (OpenMP, MKL, OpenBLAS, NumExpr) and reduce idle worker threads. Unset = current behaviour (each runtime picks its own pool size based on detected cores). Explicit per-library env vars (`OMP_NUM_THREADS=...` etc.) always take precedence over `UNSLOTH_CPU_THREADS`.
+Cap Studio's native CPU thread pools on high-core hosts: `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`. Explicit `OMP_NUM_THREADS` / `MKL_NUM_THREADS` / `OPENBLAS_NUM_THREADS` / `NUMEXPR_NUM_THREADS` still take precedence.
 
 #### Uninstall
 The recommended way to fully remove Unsloth Studio is the matching uninstall script for your OS. It stops any running servers, removes the install dir, the launcher data dir, the desktop shortcut, and any platform-specific entries (macOS `.app` bundle + Launch Services on Mac; Start Menu, `HKCU\Software\Unsloth` registry key and user `PATH` entries on Windows):

From 88391182689754c251c1013973657a3b2bbc73db Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Wed, 27 May 2026 18:23:26 +0530
Subject: [PATCH 009/222] [RL] make sync weights conditional (#4925)

* make sync weights conditional

* Also conditionalise vllm creation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* guard sync for weight sharing

* Guard self.llm access in VLLMGeneration sync_weights and generate patches for PR #4925

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 unsloth/models/llama.py           |   1 +
 unsloth/models/rl.py              |  37 +++++++---
 unsloth/models/rl_replacements.py | 113 ++++++++++++++++++++++--------
 unsloth/models/vision.py          |   1 +
 4 files changed, 113 insertions(+), 39 deletions(-)

diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index b2e6a45aa0..7af2a7d136 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -2594,6 +2594,7 @@ class FastLlamaModel:
                 quant_state_dict, model_config, dtype, bnb_config
             )
             model.vllm_engine = llm
+            llm.shared_weights = True
             model.fast_generate = model.vllm_engine.generate
             model.fast_generate_batches = functools.partial(
                 generate_batches, model.vllm_engine
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index 9bf0d3e968..359716fda4 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -2002,12 +2002,14 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
                 'GuidedDecodingParams(backend="outlines", regex=args.vllm_guided_decoding_regex) '
                 'if getattr(args, "vllm_guided_decoding_regex", None) is not None else None,',
             )
-            # Replace with our vLLM engine
+            # Replace with our vLLM engine when sharing weights
             sampling_params = (
                 " " * 12
-                + "self.llm = model.vllm_engine; self._last_loaded_step = 0; "
+                + "if getattr(getattr(model, 'vllm_engine', None), 'shared_weights', False): "
+                + "self.llm = model.vllm_engine; self._last_loaded_step = 0\n"
+                + " " * 12
                 + sampling_params
-            )  # Add spaces
+            )
 
             # count the indentation of last line of sampling_params.
             splitted_sampling_params = sampling_params.split("\n")
@@ -2040,14 +2042,27 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
                 )
 
         if trl_version >= Version("0.18.0"):
-            # Replace LLM init with already existing vLLM engine for colocate mode
-            vllm_llm_init_pattern = r"self\.llm\s*=\s*LLM\(.*?\)*\)\s*?\n(?!,)"
-            vllm_llm_replacement = "self.llm = model.vllm_engine\n"
+            # Guard LLM init - use existing vLLM engine when sharing weights,
+            # otherwise keep the original LLM() creation for sync/reload path
+            vllm_llm_init_pattern = (
+                r"(?P<indent>[ \t]*)self\.llm\s*=\s*LLM\(.*?\)*\)\s*?\n(?!,)"
+            )
+
+            def guard_llm_init(match):
+                indent = match.group("indent")
+                original = match.group(0)
+                return (
+                    f"{indent}if getattr(getattr(model, 'vllm_engine', None), 'shared_weights', False):\n"
+                    f"{indent}    self.llm = model.vllm_engine\n"
+                    f"{indent}else:\n"
+                    f"{indent}    {original.lstrip()}"
+                )
+
             new_vllm_part = re.sub(
                 vllm_llm_init_pattern,
-                vllm_llm_replacement,
+                guard_llm_init,
                 new_vllm_part,
-                flags = re.DOTALL,  # Ensure . matches newlines [[5]]
+                flags = re.DOTALL,
             )
 
         init = init.replace(vllm_part, new_vllm_part)
@@ -2116,7 +2131,7 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
             source,
         )
 
-        # Replace self.llm.generate and self.llm.chat
+        # Replace self.llm.generate and self.llm.chat with lora_request (only when sharing weights)
         if "CUDA_VISIBLE_DEVICES" in os.environ:
             lora_name = (
                 trainer_file
@@ -2129,7 +2144,9 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
             r"(self\.llm\.(?:generate|chat)\([^\)]{1,})\)",
             r"\1, lora_request = self.model.load_lora('"
             + lora_name
-            + r", load_tensors = True))",
+            + r", load_tensors = True)"
+            + r" if getattr(self.llm, 'shared_weights', False)"
+            + r" else None)",
             source,
         )
         # All these are to fix multiple commas before lora_request (in case the original code ends with something like ",)")
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 9ddb5e9453..51d20f9ff7 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -613,39 +613,48 @@ def grpo_trainer__prepare_inputs(function_name, function):
 RL_FUNCTIONS["grpo_trainer"].append(grpo_trainer__prepare_inputs)
 
 
-# Remove collective RPC of reload weights from generate
-# trl added reload weights (potentially for quantized models), we don't need it for our use case (LoRA primarily)
+# Guard reload_weights and sync_weights - skip when fast inference LoRA shares weights with vLLM
 # https://github.com/huggingface/trl/commit/7856d3b1f6518601732f489883b341bb6dd36434#diff-964e6fd373aa93037604064cb2b822d7f8e2735e33f791065acf2c4c3552d393R1168-R1169
-def grpo_trainer__generate_single_turn(function_name, function):
-    if function_name != "_generate_single_turn":
-        return function
-
-    # Remove the reload_weights collective RPC call from the generate function's source
-    # function = function.replace('self.llm.collective_rpc("reload_weights")', "")
-    # The regex below does the same thing but is more flexible and can handle single or double quotes
-    # This is for older versions.
-    function = re.sub(
-        r"self\.llm\.collective_rpc\(\s*(['\"])reload_weights\1\s*\)",
-        "",
-        function,
+def _guard_vllm_sync_reload_for_shared_weights(function):
+    # Guard reload_weights - only call when not sharing weights with vLLM
+    reload_weights_pattern = re.compile(
+        r"^(?P<indent>[ \t]*)self\.llm\.collective_rpc\(\s*(['\"])reload_weights\2\s*\)\s*$",
+        re.MULTILINE,
     )
 
-    # Current TRL versions call vllm_generation.sync_weights() every step.
-    # When Unsloth fast inference LoRA is active, weights are already shared.
+    def replace_reload_weights_line(match):
+        indent = match.group("indent")
+        return (
+            f"{indent}if not getattr(self.llm, 'shared_weights', False):\n"
+            f'{indent}    self.llm.collective_rpc("reload_weights")\n'
+        )
+
+    function = reload_weights_pattern.sub(replace_reload_weights_line, function)
+
+    # Guard sync_weights - skip when sharing weights with vLLM
     sync_weights_block = re.compile(
         r"(?P<indent>[ \t]*)with profiling_context\(self,\s*(['\"])sync_weights\2\s*\):\n"
         r"(?P=indent)[ \t]+self\.vllm_generation\.sync_weights\(\)\n",
         re.MULTILINE,
     )
 
-    def remove_sync_weights_block(match):
+    def guard_sync_weights_block(match):
         indent = match.group("indent")
         return (
-            f"{indent}# Unsloth fast inference LoRA shares weights with vLLM already.\n"
-            f"{indent}# Skipping per-step vLLM sync_weights().\n"
+            f"{indent}if not getattr(getattr(self.vllm_generation, 'llm', None), 'shared_weights', False):\n"
+            f"{indent}    with profiling_context(self, 'sync_weights'):\n"
+            f"{indent}        self.vllm_generation.sync_weights()\n"
         )
 
-    function = sync_weights_block.sub(remove_sync_weights_block, function)
+    function = sync_weights_block.sub(guard_sync_weights_block, function)
+    return function
+
+
+def grpo_trainer__generate_single_turn(function_name, function):
+    if function_name != "_generate_single_turn":
+        return function
+
+    function = _guard_vllm_sync_reload_for_shared_weights(function)
 
     # TRL 0.24.0-0.25.1 truncation regression fix
     #
@@ -693,6 +702,16 @@ def grpo_trainer__generate_single_turn(function_name, function):
 RL_FUNCTIONS["grpo_trainer"].append(grpo_trainer__generate_single_turn)
 
 
+def grpo_trainer__generate(function_name, function):
+    if function_name != "_generate":
+        return function
+
+    return _guard_vllm_sync_reload_for_shared_weights(function)
+
+
+RL_FUNCTIONS["grpo_trainer"].append(grpo_trainer__generate)
+
+
 # Fix incorrect special tokens handling and truncation in older TRL versions
 def grpo_trainer__generate_and_score_completions(function_name, function):
     if function_name != "_generate_and_score_completions":
@@ -1970,7 +1989,7 @@ RL_METRICS_CHANGES["grpo_trainer"].append(grpo_trainer_metrics)
 
 def openenv_vllm_reload_weights():
     # This function patches the trl openenv generate_rollout_completions function to:
-    # 1. Remove the reload_weights call (unsloth handles weight reloading)
+    # 1. Guard the reload_weights call (skip when sharing weights with vLLM)
     # 2. Fix wake_up call to be compatible with unsloth (remove tags to wake everything)
     #
     # The issue: TRL's wake_up(tags=["kv_cache"]) only wakes kv_cache, leaving is_sleeping=True
@@ -2027,8 +2046,20 @@ def openenv_vllm_reload_weights():
     src = textwrap.dedent(src)
     original_src = src
 
-    # Remove the reload_weights call - unsloth handles this differently
-    src = re.sub(r'.*\.collective_rpc\(\s*([\'"])reload_weights\1\s*\).*\n?', "", src)
+    reload_weights_pattern = re.compile(
+        r"^(?P<indent>[ \t]*)(?P<obj>\S+)\.collective_rpc\(\s*(['\"])reload_weights\3\s*\)\s*$",
+        re.MULTILINE,
+    )
+
+    def replace_reload_weights(match):
+        indent = match.group("indent")
+        obj = match.group("obj")
+        return (
+            f"{indent}if not getattr({obj}, 'shared_weights', False):\n"
+            f'{indent}    {obj}.collective_rpc("reload_weights")\n'
+        )
+
+    src = reload_weights_pattern.sub(replace_reload_weights, src)
 
     # Change wake_up(tags=["kv_cache"]) to wake_up() - wake everything to set is_sleeping=False
     # This prevents double wake_up issues. Unsloth's allocator skips weights anyway.
@@ -2118,7 +2149,9 @@ def vllm_generation_init_patch():
                 f"{indent}if hasattr(model, 'vllm_engine'):\n"
                 f"{indent}    # Unsloth already inits vLLM in fast inference mode. Do not redo :)\n"
                 f"{indent}    self.llm = model.vllm_engine\n"
-                f"{indent}    self.unsloth_fast_inference_lora = True\n"
+                f"{indent}    self.unsloth_fast_inference_lora = getattr(self.llm, 'shared_weights', False)\n"
+                f"{indent}    if getattr(self.llm, 'shared_weights', False) and hasattr(model, 'load_lora'):\n"
+                f"{indent}        self._unsloth_load_lora = model.load_lora\n"
                 f"{indent}else:\n" + textwrap.indent(llm_block, indent + "    ")
             )
 
@@ -2140,8 +2173,11 @@ def vllm_generation_init_patch():
 
         def replace_sync_weights(match):
             body = match.group("body")
+            # Chain getattr so server mode (where self.llm is not set) does
+            # not raise AttributeError before the default kicks in.
             guard = (
-                "    if getattr(self, 'unsloth_fast_inference_lora', False):\n"
+                "    if getattr(getattr(self, 'llm', None), 'shared_weights', False) or "
+                "getattr(self, 'unsloth_fast_inference_lora', False):\n"
                 "        # Unsloth fast inference LoRA shares weights with vLLM already.\n"
                 "        return\n\n"
             )
@@ -2162,7 +2198,12 @@ def vllm_generation_init_patch():
 
         def replace_reload_weights(match):
             indent = match.group("indent")
-            return f'{indent}pass  # self.llm.collective_rpc("reload_weights")'
+            # Chain getattr so server mode (no self.llm) is safe here too.
+            return (
+                f"{indent}if not (getattr(getattr(self, 'llm', None), 'shared_weights', False) or "
+                f"getattr(self, 'unsloth_fast_inference_lora', False)):\n"
+                f'{indent}    self.llm.collective_rpc("reload_weights")'
+            )
 
         patched_src, num_replacements = pattern.subn(
             replace_reload_weights, src, count = 1
@@ -2171,25 +2212,39 @@ def vllm_generation_init_patch():
             raise RuntimeError(
                 "Unsloth: Warning - regex did not match, VLLMGeneration.generate patch may have failed"
             )
+
+        # Inject lora_request when sharing weights (vLLM needs the adapter)
+        lora_generate_pattern = re.compile(
+            r"(self\.llm\.generate\([^\)]+)\)",
+        )
+
+        def inject_lora_request(match):
+            return (
+                f"{match.group(1)}, lora_request="
+                f"self._unsloth_load_lora('vllm_gen_lora', load_tensors=True) "
+                f"if hasattr(self, '_unsloth_load_lora') else None)"
+            )
+
+        patched_src = lora_generate_pattern.sub(inject_lora_request, patched_src)
         return patched_src
 
     try:
         init_patched = patch_vllm_generation_method(
             "_init_vllm",
             patch_init_vllm,
-            "self.unsloth_fast_inference_lora = True",
+            "self.unsloth_fast_inference_lora = getattr(self.llm, 'shared_weights', False)",
             "init_vllm",
         )
         sync_patched = patch_vllm_generation_method(
             "sync_weights",
             patch_sync_weights,
-            "if getattr(self, 'unsloth_fast_inference_lora', False):",
+            "if getattr(getattr(self, 'llm', None), 'shared_weights', False) or getattr(self, 'unsloth_fast_inference_lora', False):",
             "sync_weights",
         )
         generate_patched = patch_vllm_generation_method(
             "generate",
             patch_generate,
-            'pass  # self.llm.collective_rpc("reload_weights")',
+            "if not (getattr(getattr(self, 'llm', None), 'shared_weights', False) or getattr(self, 'unsloth_fast_inference_lora', False)):",
             "generate",
         )
     except RuntimeError as e:
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 73ef1db7e3..6c4842596f 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -1079,6 +1079,7 @@ class FastBaseModel:
                 is_vision_model = is_vlm,
             )
             model.vllm_engine = llm
+            llm.shared_weights = True
             model.fast_generate = model.vllm_engine.generate
             model.fast_generate_batches = functools.partial(
                 generate_batches, model.vllm_engine

From ab4846513551dac0d30d8caf3f5dcf09af5a67b8 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 27 May 2026 06:01:24 -0700
Subject: [PATCH 010/222] Studio: add Gemini provider with web_search,
 code_execution, prompt caching, and Nano Banana image generation (#5720)

* Studio: add Gemini provider with web_search, code_execution, prompt caching, and Nano Banana image generation

Wires Google's native Gemini API into Studio's external-provider stack
so users can pick gemini-2.5-pro / gemini-2.5-flash / gemini-2.5-flash-image
(Nano Banana) alongside the existing OpenAI / Anthropic / OpenRouter
providers. Gemini does not speak OpenAI Chat Completions on its primary
endpoint; the new `_stream_gemini` async generator translates between
the two shapes the same way `_stream_anthropic` handles the Messages API.

Backend:
- New `_stream_gemini` translator in external_provider.py. Converts
  OpenAI messages -> Gemini `contents` + `systemInstruction`; maps
  generationConfig (temperature / topP / topK / maxOutputTokens);
  forwards `tools: [{googleSearch: {}}]` for web_search and
  `{codeExecution: {}}` for code_execution; passes `cachedContent`
  through for prompt caching; sets `responseModalities=[TEXT, IMAGE]`
  for Nano Banana image generation.
- Translates streamed `GenerateContentResponse` SSE frames back into
  OpenAI chat.completion.chunk frames (text deltas, function_call ->
  tool_calls deltas, inlineData -> image_b64 tool_end envelope, usage
  chunk before [DONE]).
- Registry entry switched to native base URL
  `https://generativelanguage.googleapis.com/v1beta` with
  `openai_compatible: False` and the `x-goog-api-key` auth header.
  Model lineup curated to current 2.5 / 2.0 family + Nano Banana.

Frontend:
- Provider-capability matrix: Gemini supports temperature, top_p, top_k,
  presence_penalty (matches generationConfig); min_p / repetition_penalty
  hidden because the API does not accept them.
- `providerSupportsBuiltinWebSearch` / `providerSupportsBuiltinCodeExecution`
  / `providerSupportsBuiltinImageGeneration` extended for Gemini.
- Prompt caching toggle now also lit on Gemini.

Tests:
- 21 new tests in `test_gemini_provider.py` using httpx.MockTransport.
  Cover request body shape conversion, URL/header wiring, web_search
  forwarded as googleSearch, function-call translation both directions,
  prompt caching passthrough, image generation emitting image_b64,
  grounded-search citations -> tool_end, finish_reason mapping, and
  vision data URL -> inlineData translation.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: forward presence_penalty to Gemini and recover function name from tool_call_id

Two follow-up fixes for the Gemini provider:

  * Thread presence_penalty into _stream_gemini and set
    generationConfig.presencePenalty when non-zero. The OpenAI-side
    capability matrix already exposes the slider for Gemini, so the
    value was being collected and silently dropped on the way out.

  * When an OpenAI role=tool message omits 'name' and only carries
    'tool_call_id', recover the function name from the matching
    functionCall on the prior assistant turn. Gemini 400s on an empty
    functionResponse name.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: surface Gemini code execution parts as code_execution tool events

The Gemini stream parser only handled text/functionCall/inlineData
parts, so when the user toggled the Code pill on a Gemini model the
sandbox output (executableCode + codeExecutionResult parts) was
dropped on the floor while adjacent text reached the UI. Reviewers
flagged this as the headline feature being silently broken.

Translate both parts into the existing code_execution tool envelope
that CodeExecutionToolUI already consumes for OpenAI / Anthropic:

  * executableCode  -> tool_start with kind=code_execution and the
    source code under arguments.code. We mint a tool_call_id and
    stash it so the matching result block can pair to it.
  * codeExecutionResult -> tool_end on that id with the stdout under
    result. Non-OK outcomes (OUTCOME_FAILED / OUTCOME_DEADLINE_EXCEEDED)
    are prefixed onto the text so the failure is visible.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: native Gemini model catalog, function-call ids, and honest cache claim

Three follow-ups to the Gemini provider PR after the codex pass:

  * list_models() now translates Gemini's native /v1beta/models
    payload ({models[{name, baseModelId, displayName,
    supportedGenerationMethods}]}) into the OpenAI-compatible shape
    Studio expects. Without this the picker stayed empty for Gemini
    and fell back to hardcoded defaults. Embedding-only models are
    filtered out.

  * Forward the OpenAI tool_call id into Gemini's functionCall.id
    and mirror it onto functionResponse.id. Two parallel calls to
    the same function name can now be paired unambiguously on the
    follow-up turn.

  * Drop Gemini from the prompt-caching capability set. The wire
    flow requires a separate cachedContents POST first and the
    boolean Studio emits today is a no-op; the toggle should not
    advertise a feature it cannot apply. Leaves a pointer to the
    docs for the eventual two-step orchestration.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: distinct tool_calls index per emitted Gemini function call

Codex flagged that the Gemini stream parser hardcoded
tool_calls[0].index to 0 on every emitted functionCall. OpenAI
reassemblers key tool_calls by index when joining deltas, so two
parallel function calls in one assistant turn collapsed onto a
single slot and the second call's arguments overwrote the first.

Track the running count via len(emitted_function_call_ids) - 1
and emit it as the per-call index. The dedupe guard above (skip
when fc_id already in the set) means the index is monotonic and
stable for the lifetime of the stream. Regression test asserts
[0, 1] across two parallel calls in one candidate parts list.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: surface Gemini 3.5/3.1/3 + Nano Banana 2/Pro and plumb thinking budget

`gemini-2.0-flash` / `gemini-2.0-flash-exp` were retired by Google in 2026
(`/v1beta/models/gemini-2.0-flash:streamGenerateContent` returns HTTP 404
"no longer available to new users"), and the picker had nothing past the
2.x family. Verified against the live ListModels catalog: drop the retired
ids from `default_models` + allowlist and surface the chat-capable
3.5 / 3.1 / 3 families plus the Nano Banana image trio.

Also plumb `enable_thinking` / `reasoning_effort` into Gemini's
`generationConfig.thinkingConfig`. Without this, Gemini 3.5 Flash,
gemini-pro-latest, and the 3.x previews silently spend the caller's
`max_tokens` budget on hidden "thoughts" before emitting any visible
answer -- the chat shows a truncated stub like "The capital of" and
streams stop. Mapping:
  - enable_thinking=False / reasoning_effort=none -> thinkingBudget=0
    (Flash tier; Pro tier coerces to a small positive budget because
    the API 400s on 0 with "This model only works in thinking mode")
  - minimal/low/medium/high -> 512/2048/8192/24576 budget tokens
  - max/xhigh -> -1 (dynamic)
  - default (neither knob set) -> thinkingConfig omitted, model decides

Frontend `getExternalReasoningCapabilities` now surfaces a
`reasoning_effort` picker for every Gemini chat id (Pro tier hides the
"none" option; image-tier ids stay knob-less). Adds 6 unit tests
covering Flash/Pro effort mapping, the off-toggle coercion on Pro,
default omission, and the nano-banana-pro-preview alias routing
through the image modalities path. 28 -> 34 tests in
`test_gemini_provider.py`, all green; full backend suite still passes
(1459/1460; the unrelated test_help_output flake is pre-existing and
not in any file this PR touches).

Live verification against generativelanguage.googleapis.com on
2026-05-24 with `_stream_gemini` directly:
  text   gemini-3.5-flash           single PASS  multi PASS
  text   gemini-3.1-pro-preview     single PASS  multi PASS
  text   gemini-3.1-flash-lite      single PASS  multi PASS
  text   gemini-3-pro-preview       single PASS  multi PASS
  text   gemini-3-flash-preview     single PASS  multi PASS
  text   gemini-2.5-pro             single PASS  multi PASS
  text   gemini-2.5-flash           single PASS  multi PASS
  text   gemini-2.5-flash-lite      single PASS  multi PASS
  text   gemini-flash-latest        single PASS  multi PASS
  text   gemini-flash-lite-latest   single PASS  multi PASS
  text   gemini-pro-latest          single PASS  multi PASS
  image  gemini-2.5-flash-image     PASS (1082 KB png returned)
  image  gemini-3.1-flash-image-preview  PASS (Nano Banana 2)
  image  gemini-3-pro-image-preview      PASS (Nano Banana Pro)
  tool   web_search                 PASS
  tool   code_execution             PASS
  -> 16/16 e2e through the actual ExternalProviderClient code path.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: tighten Gemini provider after review (PR #5720)

Fixes a batch of bugs surfaced by a second-pass review on top of the
3.5/3.1/3 + Nano Banana 2/Pro additions in c6724dbd.

Backend (external_provider.py):
- Constructor normalises legacy /v1beta/openai base URLs to /v1beta so
  Gemini providers saved before the native switch keep working without
  a manual re-config.
- Skip thinkingConfig, googleSearch, and codeExecution on image-tier
  models (-image / nano-banana). The image responseModalities path is
  mutually exclusive with text-tool wiring and stale UI state would
  otherwise 400 the turn.
- _PRO_THINKING_PREFIXES now includes gemini-3.5-pro and uses anchored
  prefix matching (exact id or "<prefix>-...") so the image-tier
  gemini-3-pro-image-preview cannot accidentally match the pro guard.
- Gemini 3 functionCall thoughtSignature is round-tripped through the
  tool_calls envelope via extra_content.google.thought_signature on
  emit, and replayed as a sibling of functionCall on the next request.
- finishReason swaps STOP -> tool_calls when any functionCall was
  emitted on the same turn so OAI clients trigger tool execution
  (matches the OpenAI Chat Completions contract).
- usageMetadata.thoughtsTokenCount is rolled into output_tokens and
  surfaced on output_tokens_details.reasoning_tokens so total_tokens
  reflects the full billable spend instead of dropping the hidden
  reasoning slice.

Registry (providers.py):
- Drop gemini-3-pro-preview from default_models. Google shut it down
  on 2026-03-09 and auto-redirects to gemini-3.1-pro-preview; we
  surface the canonical id only.
- Add model_id_deny_exact = ("gemini-3-pro-preview",) so the live
  ListModels fetch does not re-surface the redirect alias.

Route schema (models/inference.py):
- enable_prompt_caching widened to Optional[Union[bool, str]] so the
  /v1/chat/completions caller can pass a Gemini cachedContent resource
  name (e.g. cachedContents/abc123). Without this widening _stream_gemini
  s string cachedContent passthrough was unreachable from the public
  route (bool_parsing 422). stream_chat_completion signature mirrors.

Frontend (provider-capabilities.ts, chat-page.tsx, chat-adapter.ts):
- providerSupportsBuiltinImageGeneration now also recognises
  nano-banana ids (nano-banana-pro-preview was hidden from the image
  pill before).
- providerSupportsBuiltinWebSearch takes the model id so Gemini image
  models hide the Search pill (mirrors the backend skip).
- providerSupportsBuiltinCodeExecution uses the same isGeminiImageModel
  guard for nano-banana ids.
- GEMINI_THINKING_PRO_PREFIXES gains gemini-3.5-pro; gemini-3-pro
  tightened to gemini-3-pro-preview to avoid the image-id overlap.
- Updated 3 callers of providerSupportsBuiltinWebSearch to thread the
  selected model id through.

Tests (test_gemini_provider.py): 34 -> 42, all green
- test_image_models_skip_thinking_config
- test_image_models_drop_text_only_tools
- test_gemini_35_pro_recognized_as_pro_thinking
- test_legacy_openai_base_url_normalized
- test_finish_reason_swaps_to_tool_calls_when_function_call_emitted
- test_thought_signature_round_trips_into_gemini_function_call
- test_thought_signature_emitted_in_tool_call_delta
- test_usage_chunk_includes_thoughts_tokens

Verification:
- Backend pytest 1518/1519 passing (one unrelated Qwen3.5 flash-attn
  test fails on main as well; nothing in this PR touches that path).
- Frontend npx tsc -b clean.
- Live e2e 16/16 against generativelanguage.googleapis.com through the
  patched _stream_gemini code path (all 11 chat models single + multi
  turn, all 3 image models returned image bytes, web_search and
  code_execution tools both emit the expected envelope).
- Live /api/providers/models against the patched backend surfaces 16
  ids (gemini-3-pro-preview correctly filtered via deny_exact).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: address second-pass review findings on Gemini (PR #5720)

Round-2 reviewer.py flagged a phantom web_search card on image
turns (12/12 reviewers), route-layer stripping of tool_calls /
tool_call_id / name, an over-narrow image-mode tool guard, and
silent safety blocks. This patch fixes all four.

Backend (external_provider.py):
- web_search_active is now derived from the outbound tools_array
  (whether googleSearch was actually forwarded), not the raw
  enabled_tools intent. Image-mode turns dropped the tool above so
  the inbound stream no longer emits a phantom "search complete"
  tool_start / tool_end on those turns.
- text_tools_allowed now uses is_image_model (covers both `-image`
  / `nano-banana` picker models AND text models that requested
  `image_generation` via enabled_tools). Verified against the live
  Gemini API which rejects both googleSearch and codeExecution
  alongside responseModalities=["TEXT","IMAGE"] with explicit 400s
  ("Search as tool is not enabled for this model", "Code execution
  is not enabled for this model").
- promptFeedback.blockReason is surfaced as a 400 content-filter
  error chunk instead of returning an empty successful assistant
  response. The streaming loop closes the response before exiting.

Route (routes/inference.py):
- _build_external_messages now propagates tool_calls (assistant),
  tool_call_id, and name (tool result) through every code path
  (string content, multimodal content, non-vision fallback). Without
  this Gemini 3 function-call round trips lost their thoughtSignature
  + tool_call_id at the route boundary, and functionResponse.name
  arrived empty on the second turn.
- Assistant messages with content=None and tool_calls populated are
  preserved as a synthetic empty-string content turn so the
  Gemini translator can rebuild the functionCall part.

Tests (test_gemini_provider.py): 42 -> 45, all green
- test_image_models_suppress_phantom_web_search_card
- test_image_generation_tool_drops_text_tools
- test_prompt_feedback_block_reason_surfaces_as_error

Verification:
- Backend pytest 1736 / 1736 (the two pre-existing unrelated fails
  on main, test_help_output and Qwen3.5 flash-attn pin, are skipped).
- Frontend npx tsc -b clean.
- Live e2e 16/16 against generativelanguage.googleapis.com:
  11 chat models single + multi turn, 3 image models returning
  image bytes, web_search and code_execution both PASS.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: fix third-pass Gemini findings (PR #5720)

Round 3 review follow-ups:

Backend (studio/backend/core/inference/external_provider.py):
- Close response AND aiter_lines iterator in a finally so normal,
  prompt-block, and cancellation exits all clean up (eliminates the
  RuntimeWarning about aclose never being awaited).
- Pair the synthetic web_search tool_start with a tool_end on the
  promptFeedback.blockReason path so the UI does not leave a stuck
  "searching..." spinner after the error toast.
- Preserve native id and thoughtSignature on executableCode and
  codeExecutionResult tool events under google.native_part, and pair
  the tool_end on the code-exec id so multi-turn code-execution
  replays do not lose Gemini-required history.
- Carry part-level thoughtSignature on text deltas via
  delta.extra_content.google.thought_signature and on inline image
  tool_end via google.thought_signature so Gemini 3 image editing
  and tool turns round-trip the signature on the next request.
- Guess remote image_url MIME from the URL path so PNG / WebP / GIF
  inputs are not silently relabeled as JPEG.
- Roll usageMetadata.toolUsePromptTokenCount into translated input
  tokens and surface thoughtsTokenCount as
  completion_tokens_details.reasoning_tokens in _build_usage_chunk.
- Only normalize the Google-hosted /v1beta/openai legacy base URL;
  custom proxies whose paths happen to end in /openai are left
  untouched.
- Forward ChatCompletionRequest.tools and tool_choice through
  stream_chat_completion into _stream_gemini, translating to
  tools[].functionDeclarations and toolConfig.functionCallingConfig.

Frontend:
- chat-adapter: when Gemini image-generation is enabled for the turn,
  also disable Search and Code so the request, builder, and active
  pills agree with what the backend actually sends (the backend
  already strips text tools when image_generation is in enabled_tools).
- chat-adapter: consume OpenAI-shape delta.tool_calls chunks so
  Gemini function-call deltas without text surface as tool-call parts.
- shared-composer: disable Search and Code pills while Gemini image
  mode is active so the UI matches the request.

Tests (studio/backend/tests/test_gemini_provider.py): adds coverage
for proxy base-url gating, remote image MIME inference,
toolUsePromptTokenCount, reasoning_tokens propagation, prompt-block
web_search tool_end pairing, native code-exec id/thoughtSignature
metadata, inline image thoughtSignature, text-chunk extra_content,
OpenAI tools/tool_choice translation, and image-model tool drop.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: Gemini 3 thinkingLevel + image-model Search grounding (PR #5720)

Gemini 3.x migrated to a string `thinkingConfig.thinkingLevel`
(MINIMAL/LOW/MEDIUM/HIGH) and rejects `thinkingBudget`+`thinkingLevel`
in the same request. Gemini 3 also cannot turn thinking fully off, so
the lowest position is "minimal" (Flash) or "low" (Pro rejects
"minimal").

- external_provider._stream_gemini: split thinking translation by
  family. Gemini 3.x (3 / 3.1 / 3.5 + gemini-pro-latest /
  gemini-flash-latest / gemini-flash-lite-latest) emits
  thinkingConfig.thinkingLevel; effort none/off coerces to "low" on
  Pro and "minimal" on Flash. Gemini 2.5 stays on thinkingBudget.
- external_provider._stream_gemini: allow `tools: [{googleSearch: {}}]`
  on the Gemini 3 image family (gemini-3-pro-image-preview,
  gemini-3.1-flash-image-preview, nano-banana-pro). Google's docs
  document Search grounding on these. codeExecution stays blocked
  on image mode (still mutually exclusive with responseModalities).
- provider-capabilities.ts: mirror the Gemini 3 effort ladders in
  resolveGeminiReasoningCapabilities (Pro: low/medium/high; Flash:
  minimal/low/medium/high; 2.5 Flash keeps the off-position).
- provider-capabilities.ts: providerSupportsBuiltinWebSearch now
  returns true on the documented Gemini 3 image models so the pill
  is reachable; older image ids (gemini-2.5-flash-image) still hide.

Tests: splits the existing thinkingBudget cases by family (Gemini 3
checks thinkingLevel; Gemini 2.5 keeps thinkingBudget), adds positive
googleSearch coverage for Gemini 3 image models and negative
googleSearch coverage for legacy image models.

References:
- https://ai.google.dev/gemini-api/docs/thinking
- https://ai.google.dev/gemini-api/docs/gemini-3
- https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: attach Gemini code_execution inline images to the code card (PR #5720)

When a text Gemini turn wires codeExecution and the sandbox produces a
matplotlib plot, the inline image part ships right after the
codeExecutionResult. Previously this surfaced as a separate empty
image_generation card. Track the most recent code_execution
tool_call_id + result text and, when an inline image follows with
code_execution active, emit a second tool_end on the same id that
appends the image as a data: URI under the `__IMAGES__:` marker the
chat-adapter already understands.

Image-picker turns (`-image` / `nano-banana`) keep the standalone
image_generation envelope so Nano Banana outputs render the same way.

Tests: covers the merged code-execution card emission with no
standalone image_generation event when code_execution is the active
tool.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: fix fourth-pass Gemini findings (PR #5720)

Round 4 review follow-ups:

Backend:
- `_is_openai_compatible` + `_auth_headers` detect Gemini connections
  pointed at a custom OpenAI-compatible proxy (non-Google host whose
  path ends in `/openai`) and route them through the OpenAI-compat
  surface with `Authorization: Bearer ...` instead of the native
  `_stream_gemini` translator + `x-goog-api-key`. Google-hosted Gemini
  keeps the native dispatch path it migrated to in this PR.
- `_stream_gemini` thinkingLevel handling for Gemini 3 Pro now coerces
  both "minimal" and "medium" effort to "low" / "high" respectively
  (Pro tier only accepts low/high per
  https://ai.google.dev/gemini-api/docs/thinking).
- `providers.py` `default_models` restores the advertised
  `gemini-3.5-pro` and the rolling `gemini-pro-latest` /
  `gemini-flash-latest` / `gemini-flash-lite-latest` aliases that the
  allowlist already admits.

Frontend:
- chat-adapter: lean on `providerSupportsBuiltinWebSearch` (which
  already encodes the Gemini 3 image-model Search allowance) instead
  of blanket-disabling Search whenever Gemini image mode is active.
  Code execution stays blocked because Gemini image mode rejects it.
- shared-composer: mirror the same gate -- only the Code pill is
  unconditionally disabled in Gemini image mode; the Search pill is
  driven by `supportsBuiltinWebSearch`.
- provider-capabilities: Gemini 3 Pro reasoning levels now expose only
  "low" and "high" (no Medium pill) to match the API.

Tests: covers the Gemini 3 Pro medium / minimal coercion, the custom
proxy OAI-compat dispatch + Authorization Bearer auth, and the
native-vs-proxy detection. Also closes the mocked httpx.AsyncClient
inside the test event loop so the Python 3.13 `aclose was never
awaited` warning no longer fires.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: fix fifth-pass Gemini findings (PR #5720)

Round 5 review follow-ups:

Backend:
- `_is_openai_compatible` + `_auth_headers` now treat ANY non-Google
  Gemini base URL as OpenAI-compat (LiteLLM / custom OAI gateways /
  OpenAI-compat vLLM routers), not just paths ending in `/openai`.
  Pre-existing saved Gemini proxies on `/v1` keep working.
- Gemini 3 thinkingLevel coercion narrowed to the documented
  inconsistencies: only "minimal" is coerced to "low" on Pro tier.
  "medium" passes through (Gemini 3.1 Pro accepts it per
  https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-pro).
- `_stream_gemini` only flips `responseModalities=[TEXT,IMAGE]` when
  the selected model is image-capable. A stale
  `enabled_tools=["image_generation"]` on a text model is silently
  dropped instead of producing an invalid Gemini request.
- `_stream_gemini` validates the model id against
  `[A-Za-z0-9._-]+` before URL interpolation so a model like
  `../cachedContents/x` cannot redirect the request to an unintended
  endpoint with the configured API key attached.
- Empty-text Gemini parts that still carry `thoughtSignature` emit a
  content-free delta with `extra_content.google.thought_signature` so
  Gemini 3 turns that end with a signature-only fragment do not lose
  the replay state.
- ConnectError / ReadTimeout / generic HTTPError paths in
  `_stream_gemini` now close the synthetic web_search tool_start
  with a matching tool_end before the error chunk so the UI does not
  leave a stuck "searching..." card on transport failure.
- `providers.py` default_models drop the non-existent
  `gemini-3.5-pro` (Google launched only `gemini-3.5-flash` at
  I/O 2026; Pro tier remains `gemini-3.1-pro-preview`).
- `routes/inference.py` only forwards `payload.top_k` when the caller
  explicitly set it on the request (Pydantic `model_fields_set`).
  Omitted top_k stays omitted, restoring the pre-PR behavior where
  Gemini uses its server default.
- `ChatCompletionRequest.enable_prompt_caching` adds a `mode="before"`
  validator that coerces the canonical string literals "true"/"false"
  back to bool so historical opt-out callers keep working after the
  field widened to `Union[bool, str]` for Gemini cache resource names.

Frontend:
- `providerSupportsBuiltinWebSearch` / Code / Image now accept the
  saved connection `baseUrl` and return false for custom OAI-compat
  Gemini proxies. Backend skips `_stream_gemini` for those bases, so
  native tool envelopes never reach them; hiding the pills keeps the
  request, builder, and UI consistent.
- `provider-capabilities.ts` Gemini 3 Pro effort ladder restores
  `["low", "medium", "high"]` to match Google's documented levels.
- Call sites in `chat-page.tsx` and `chat-adapter.ts` pass through
  `provider.baseUrl` so the proxy gate fires.

Tests: covers Gemini 3 Pro medium pass-through, custom proxy dispatch
on `/v1` and `/openai` bases, path-traversal model id rejection,
top_k omission when not explicit, text-model image_generation drop,
empty-text + thoughtSignature surfacing, and
enable_prompt_caching string coercion.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: fix sixth-pass Gemini findings (PR #5720)

Round 6 review follow-ups:

Frontend:
- chat-adapter `delta.tool_calls` accumulates fragments by `id` /
  `index` instead of pushing a new tool-call card per chunk. The
  standard OpenAI Chat Completions stream contract sends `id`/`name`
  on the first chunk and partial `function.arguments` on subsequent
  chunks; our previous handler parsed each fragment as a standalone
  tool call. Local llama.cpp and OAI-compat providers that stream
  fragments now reassemble into a single function-call part.
- chat-adapter also preserves `extra_content` on streamed tool-call
  deltas so Gemini 3 `thoughtSignature` survives to the next turn.
- provider-capabilities Gemini 3 Pro restores "medium" in the
  reasoning-effort ladder (Google's official Gemini API thinking
  doc lists low/medium/high for Gemini 3.1 Pro; my earlier round 4
  coercion was wrong).
- provider-capabilities orders `gemini-2.5-flash-lite` ahead of the
  broader `gemini-2.5-flash` prefix so Flash-Lite falls into the
  "no native thinking knob" branch as documented.

* Studio: round-trip Gemini tool_calls and tool results (PR #5720)

Recurring round 3-6 P1: the chat-adapter renders Gemini function-call
parts and code-execution events but `toOpenAIMessage` only serialized
text + image content, so the next turn lost the assistant
`tool_calls[]` (including Gemini 3's required
`extra_content.google.thought_signature`) and the matching
`role="tool"` result. Gemini 3 multi-turn function calling and code
execution failed validation on the second turn.

Frontend:
- types/api.ts widens OpenAIChatMessage to permit `role="tool"`,
  `tool_calls`, `tool_call_id`, `name`, and `content: null`. Adds
  OpenAIToolCallPart with `extra_content` for the Gemini round-trip.
- chat-adapter: new `toOpenAIMessages` expands an assistant turn with
  tool-call parts into [assistant w/ tool_calls + extra_content,
  role=tool result, ...]. tool result content is JSON-serialized so
  the backend translator can rebuild Gemini's `functionResponse`
  shape.
- chat-adapter outbound history now uses `flatMap(toOpenAIMessages)`
  so each assistant tool-call round-trips through the standard OAI
  shape the backend's `_stream_gemini` already understands.

* Studio: replay Gemini code_execution and image native parts on history (PR #5720)

Multi-turn Gemini history previously lost the native executableCode,
codeExecutionResult, and inlineData parts because the outbound
translator regenerated a generic functionCall for every assistant
tool_call. Stow the native dict on tool_end (frontend) and replay it
verbatim with thoughtSignature (backend) so follow-up turns preserve
the prior execution and image generation state. Skip role="tool"
fan-out for server-side builtin tools so Gemini does not 400 on a
functionResponse with no matching user-declared function.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: complete Gemini built-in tool replay round-trip (PR #5720)

Round 7 follow-up to the multi-turn native-part work. Three asymmetric
storage/consume gaps remained between the backend translator and the
chat adapter, so realistic Gemini follow-up turns degraded to generic
functionCalls instead of native history.

- Frontend collectAssistantToolCalls now drops web_search outright,
  drops code_execution / image_generation when the native part is
  missing, and promotes args.google to extra_content.google so the
  backend native_part replay branch actually fires.
- Backend image_generation tool_end now emits google.native_part
  with the inlineData (mimeType + base64) and thoughtSignature so the
  follow-up image-edit turn can replay the prior image as a native
  Gemini model part.
- Backend code-execution plot tool_end now stows google.native_part
  with the inlineData so the merged code-exec card can round-trip
  executableCode + codeExecutionResult + inlineData on the same id.
- Added regression tests for image-gen native-part replay and the
  code-exec plot native_part stow.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 8 Gemini follow-ups (PR #5720)

- Text-part thoughtSignature: stow on the assistant message during
  streaming and replay onto the last text part on the next turn so
  Gemini 3 strict function-calling does not reject history.
- Function declarations: recursively strip Gemini-unsupported OpenAPI
  keys (additionalProperties, $schema, $defs, strict, etc.) so OpenAI
  strict tools stop 400ing as INVALID_ARGUMENT on Gemini.
- OpenAI-compat fallback: forward tools/tool_choice so custom Gemini
  proxies (LiteLLM, gateways) keep function-calling.
- enable_prompt_caching: cover the Pydantic v1 legacy off/on/f/n/t/y
  string set so explicit opt-outs stay opt-out (Gemini was sending
  cachedContent: "off" otherwise).
- Frontend collectAssistantToolCalls / collectToolResultMessages: use
  google.native_part + result presence to disambiguate provider
  builtins from same-named user-declared functions.
- Added regression tests for text-signature replay and schema
  sanitization.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 9 Gemini follow-ups (PR #5720)

Two round-9 convergent finds across the 12 reviewers:

- Server-side web_search was leaking onto the next turn as a fake
  user functionCall/functionResponse. The previous heuristic (skip
  builtin only when no native_part AND no result) let it through
  because the synthetic tool card has a non-empty result string.
  Always skip web_search by name on both serializers, accept that a
  user-declared function literally named "web_search" must use a
  different name.
- Assistant `extra_content` was dropped by ChatMessage validation
  before _stream_gemini could replay text-part thought signatures.
  Add the field to ChatMessage and forward it through
  _build_external_messages so the multi-turn signature path actually
  carries data.

Includes a regression test for the ChatMessage round-trip.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 10 Gemini follow-ups (PR #5720)

Three convergent round-10 reviewer findings closed:

- Tag synthetic provider-side builtins with `args._server_tool=True`
  via a central helper that runs in every `_emit_tool_event` /
  `_emit_synthetic_tool_event` path. The frontend filter now skips
  on that marker instead of on the public tool name, so local
  llama.cpp `web_search` and OpenAI function tools literally named
  `web_search` / `code_execution` / `image_generation` round-trip
  cleanly while Gemini grounding / hosted code-exec / hosted image
  cards stay skipped.
- Gate Gemini image-mode (responseModalities=[TEXT,IMAGE]) on the
  Images pill (enabled_tools containing `image_generation`).
  Selecting an image-capable model with the pill off no longer forces
  image output the UI says is disabled.
- Frontend missing-key guard now exempts custom Gemini OAI-compat
  proxies (LiteLLM, gateways) the same way the backend already
  does, so a saved Gemini connection on `http://localhost:4000/v1`
  with no API key stops being blocked.

Existing tests updated to pass `enabled_tools=["image_generation"]`
on image-mode capture paths.

* Studio: round 11 Gemini follow-ups (PR #5720)

Four round-11 findings closed:

- Kimi _stream_kimi_web_search's local _synthetic_chunk helper now
  runs through _stamp_server_tool_marker so Kimi search history is
  not replayed as a fake user functionCall on the next turn (was an
  asymmetric miss after the round-10 tagging work).
- OpenAI Responses path (/v1/responses for gpt-5.x) forwards
  caller-supplied tools / tool_choice, translating the Chat
  Completions function-tool shape into the Responses native shape.
  Without this, standard OpenAI tools silently dropped on
  Responses-routed traffic.
- Decoupled the Gemini image-tier model-id guards (text-tool /
  thinking strip) from the Images pill flip
  (responseModalities=[TEXT,IMAGE]). gemini-2.5-flash-image with
  Search/Code on and the Images pill OFF no longer forwards
  googleSearch + thinkingConfig (Gemini 400s on those for legacy
  image ids).
- Gemini-only extra_content is now forwarded by
  _build_external_messages only when provider_type=="gemini" so
  Google's thought_signature does not leak into OpenAI / Mistral /
  Kimi / OpenRouter request bodies as an unknown field.

Added a regression test for the image-tier strict-guard split and
extended the extra_content test to cover the non-Gemini suppression.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 12 Gemini follow-ups (PR #5720)

Three round-12 convergent findings closed:

- extra_content leak to custom Gemini OAI-compat proxies (8/12
  reviewers). _build_external_messages now gates extra_content on
  the native generativelanguage.googleapis.com host, not just
  provider_type=="gemini", so LiteLLM / custom gateways routed
  through /chat/completions do not get an unknown top-level field.
- OpenAI Responses function-tool round-trip (5/12 reviewers). I
  added user `tools` forwarding in round 11 but did not parse the
  matching response.output_item.done items of type=function_call.
  The parser now translates them into Chat Completions
  delta.tool_calls and the terminal chunk reports
  finish_reason="tool_calls" when the model invoked a user
  function.
- Image-tier model with Images pill OFF (2/12). Google's image
  models default to text+image when responseModalities is omitted,
  so the previous fix silently still billed image output. Force
  responseModalities=["TEXT"] when the Images pill is off and the
  selected model is image-capable.

Updated the two pre-existing tests that pinned the synthetic-tool
arguments shape to include the new `_server_tool: True` marker, and
added a regression test for the Responses function-call output
translation.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 13 Gemini/Responses follow-ups (PR #5720)

Three round-13 convergent findings closed:

- OpenAI Responses function_call indices: my round-12 translator
  hardcoded every emitted tool_calls[*].index to 0, so parallel
  function calls collapsed for index-keyed clients. Track and
  increment function_call_index per emit (mirrors the Gemini
  branch's distinct-index pattern). 10/12 reviewers flagged.
- _SERVER_SIDE_BUILTIN_TOOL_NAMES now includes web_fetch so
  Anthropic-hosted web_fetch cards carry the _server_tool marker
  and the frontend history serializer doesn't replay them as fake
  user functions. 4 reviewers flagged.
- OpenAI Responses follow-up tool results now serialize as
  Responses-shape function_call / function_call_output items keyed
  by call_id, instead of Chat Completions role="tool" content.
  Skips assistant tool_calls tagged with _server_tool so hosted
  builtins don't round-trip as user functions. 2 reviewers flagged.

Updated the Anthropic code_execution and web_fetch test argument
pins to include the new _server_tool marker, and added two
regression tests (distinct indices on parallel function_call,
function_call_output round-trip).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 14 Gemini follow-ups (PR #5720)

Three round-14 findings closed:

- Remote `image_url` translation (5 reviewers convergent). Public
  HTTPS image URLs can't be sent as `fileData.fileUri` -- Gemini
  reserves that path for Files API URIs and YouTube. Fetch the
  bytes server-side and inline them as base64 `inlineData`,
  mirroring the pre-PR OpenAI-compat behaviour. YouTube URLs and
  generativelanguage.googleapis.com/v1beta/files/* stay as
  `fileData`.
- Nullable JSON Schema type arrays. OpenAI strict tools commonly
  use `"type": ["string", "null"]`; the Gemini sanitizer now
  flattens that to `"type": "string", "nullable": true` so strict
  function tools stop 400ing.
- Parallel functionResponses now ride on one user content block
  with multiple `functionResponse` parts, matching Google's
  parallel tool docs. Consecutive `role="tool"` messages merge
  into the previous user turn instead of splitting into separate
  Gemini user turns.

Three regression tests added (remote URL fetch + inline, Files
API / YouTube fileData preservation, schema nullable flattening,
parallel-tool grouping).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: SSRF harden Gemini remote image fetch (PR #5720)

Round 15 convergent finding (12/12 reviewers). My round-14 fix to
download user-controlled image URLs for inlineData inlining was an
SSRF / data-exfiltration path: no scheme check, no private-host
guard, no size cap, no Content-Type validation, redirects could
bounce to internal services, and the full URL was logged.

Replace the inline fetch with `_safe_fetch_image_for_gemini`:

- Require https:// (reject http, file, data, ftp, etc).
- Resolve the hostname via socket.getaddrinfo and reject if ANY
  resolved address is private / loopback / link-local / multicast /
  reserved / unspecified (covers 127.0.0.0/8, 10/8, 172.16/12,
  192.168/16, ::1, 169.254/16 metadata, RFC 6890).
- Block IP-literal URLs that resolve into those same ranges.
- Cap response body at 10 MB (Content-Length pre-check + streamed
  byte counter).
- Require Content-Type to start with `image/`.
- Disable redirect following so a 302 to a private host can't slip
  past the address check.
- Use a short 15s timeout and a tiny connection pool dedicated to
  these fetches.
- Log only the host name + error class -- no full URL, no signed
  querystring leak.

If the guard rejects, the image part is silently dropped (instead
of forwarding raw bytes or a fileData fallback). Files API URIs
and YouTube URLs still ride as `fileData.fileUri` unchanged.

Tests: replaced the live-fetch test with a `_safe_fetch_image_for_gemini`
monkeypatch, added four new SSRF-guard tests (non-https rejected,
loopback / private IP literals rejected, hostnames that resolve to
private IPs rejected).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 16 Gemini follow-ups (PR #5720)

- IP-pinned image fetch (`_safe_fetch_image_for_gemini`): reuse the
  validated-once-then-pin pattern from `tools._fetch_page_text` via
  `asyncio.to_thread`, so DNS rebinding between validation and the
  HTTP connect cannot redirect us at a private/metadata address.
  Catch malformed-bracketed IPv6 urlparse errors. Follow up to 4
  redirect hops with per-hop SSRF re-validation.
- Replace contains-substring detection of Gemini Files API + YouTube
  URLs with parsed scheme/host/path checks, so attacker URLs like
  `https://evil.example/path/youtube.com/x.png` no longer skip the
  safe-fetch path and serialize as `fileData.fileUri`.
- `_build_external_messages`: strip per-tool-call `extra_content`
  for non-native-Gemini providers; the Gemini-only
  `thought_signature` payload was leaking through `tool_calls[]`
  into /chat/completions on OpenAI, Anthropic, and custom Gemini
  OAI-compat gateways.
- `_server_tool` marker now gated on the function name being one of
  the canonical builtin names (`web_search`, `web_fetch`,
  `code_execution`, `image_generation`) AND the marker being set,
  so a user function whose schema happens to define an
  `_server_tool` field is no longer dropped. Frontend filter mirrors
  the same gate, plus a backward-compat fallback for pre-PR
  persisted server-tool cards (no marker) routed via name +
  native_part / web-tool heuristic.
- Gemini schema sanitizer collapses `anyOf: [{X}, {"type":"null"}]`
  to `{X, "nullable": true}` so Optional[X] tool args from
  OpenAI/Pydantic schemas no longer 400 the Gemini request.
- Frontend tool-result serializer emits `{"result":""}` for empty
  string outputs so the ChatMessage validator does not reject
  `role="tool"` with empty content.
- Coerce `medium` thinkingLevel to `high` for legacy
  `gemini-3-pro*` / `gemini-3-pro-preview*` (only low/high
  documented; shut down 2026-03-09); 3.1+ Pro still passes through.
- Hide Gemini native thinking ladder on custom OAI-compat Gemini
  gateways by routing `getExternalReasoningCapabilities` through
  `isGeminiCustomOpenAICompatBase(baseUrl)`; thread baseUrl through
  all four call sites.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 17 Gemini follow-ups (PR #5720)

- Frontend `collectAssistantToolCalls` and `collectToolResultMessages`
  no longer drop unmarked `web_search` / `web_fetch` cards by name
  alone: a user-defined function with one of those names must
  round-trip. Pre-PR persisted `code_execution` / `image_generation`
  cards still get filtered via a shape heuristic (kind/command/code/
  prompt fields) instead of bare name.
- `_build_external_messages._filter_tool_calls` now drops marked
  server-side builtin `tool_calls` entirely for non-native-Gemini
  providers, not just their `extra_content`. An assistant turn whose
  only payload was a marked builtin is dropped completely so the
  receiving provider does not see an orphan tool_call.
- `_stream_anthropic` translates OpenAI top-level `tool_calls` into
  Anthropic native `{type:"tool_use", id, name, input}` content
  blocks, and translates `role="tool"` follow-ups into `role:"user"`
  messages carrying a `tool_result` block. Anthropic's native
  Messages API rejects the OpenAI shapes.
- `_safe_fetch_image_for_gemini_sync` factors URL validation through
  `_safe_parse_https`, so malformed `port` access (e.g.
  `https://host:bad/x.png`) and malformed redirect targets (e.g. a
  302 to `https://[bad/x.png`) drop the image instead of raising mid-
  request.
- `tool_choice="none"` now disables hosted builtins (Gemini
  googleSearch / codeExecution and OpenAI Responses web_search /
  shell / image_generation), not just user function declarations.
- Schema sanitizer handles multi-type `anyOf` with null
  (`Union[str, int, None]`): keep the slim non-null anyOf and add
  `nullable: true` so Gemini does not reject `{"type":"null"}`.
- Image fetch falls back to the caller-provided MIME (guessed from
  URL extension) when the server omits Content-Type instead of
  dropping the image as `non-image content-type=<none>`.
- Per-request aggregate caps on remote image inlining (8 images,
  20MB total) so a single chat request cannot force unbounded
  backend downloads.
- Frontend exposes the reasoning ladder for `gemini-2.5-flash-lite`
  (`none/minimal/low/medium/high/max`) so the UI can drive the
  thinkingBudget the backend already supports.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 18 Gemini follow-ups (PR #5720)

- `tool_choice="none"` now opts out of hosted builtin tools on every
  provider path, not just Gemini and OpenAI Responses. Anthropic
  web_search / web_fetch / code_execution, Kimi `$web_search` early
  return, and OpenRouter `plugins:[{id:"web"}]` are all gated on
  `tool_choice_disabled`. Passing `enabled_tools=[...]` with
  `tool_choice="none"` no longer triggers provider-side search /
  code execution for any provider.
- `_stream_anthropic` accepts `tool_choice` and threads it through;
  the dispatcher in `stream_chat_completion` forwards it.
- Frontend `isServerSideBuiltinToolPart` simplified to drop only on
  (marker) OR (canonical name + native_part). The previous shape
  heuristic on `args.kind`/`args.command`/`args.code`/`args.prompt`
  dropped real user-declared `code_execution` / `image_generation`
  functions. Pre-PR persisted hosted cards lacking the marker now
  leak to non-native providers on switch -- preferred to silently
  deleting legitimate function-call history.
- Backend `_is_marked_server_builtin_tool_call` and the OpenAI
  Responses translator's matching filter accept BOTH `_server_tool`
  marker AND `args.google.native_part` as durable provider-side
  signals so Gemini code_execution / image_generation cards are
  still dropped on a provider switch.
- Per-request remote image count cap now counts ATTEMPTS, not just
  successful inlines, so 100 failing/slow URLs cannot each consume
  the 15s fetch timeout. Data: URL images now share the same count
  and byte caps as fetched remote URLs.
- OpenAI Responses translator tracks skipped server-builtin
  `function_call` ids and drops their matching `role="tool"`
  follow-ups, preventing orphan `function_call_output` items in the
  outbound body.
- Gemini schema sanitizer preserves multi-type unions with null:
  `{"type":["string","integer","null"]}` becomes
  `anyOf:[{string},{integer}] + nullable:true` instead of being
  flattened to the first non-null type.
- Gemini model id validation moved to the top of `_stream_gemini`
  so an invalid model id rejects the request before any remote
  image fetch / message translation side effect.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 19 Gemini follow-ups (PR #5720)

- `_build_external_messages` now skips an empty assistant turn when
  `_filter_tool_calls` drops every synthetic builtin tool_call (was
  guarded only on the `content is None` branch; the string-content
  and list-content branches still forwarded
  `{"role":"assistant","content":""}` which several providers
  reject). Also tracks the dropped server-builtin tool_call ids and
  skips the matching `role="tool"` follow-ups so the receiving
  provider does not see an orphan tool_result.
- OpenRouter `web_search_active` (the synthetic tool_start /
  tool_end emitter) is now also gated on `tool_choice_disabled` so
  a request with `tool_choice="none"` does not surface a fake
  web_search card in the chat UI even though the plugin was
  correctly stripped from the outbound body.
- `_stream_anthropic` translates an OpenAI role="tool" with list
  content (`content=[{"type":"text","text":"..."}]`) into a native
  `tool_result` block on a user message; previously only the
  string-content shape was translated, so list-content tool results
  were forwarded as invalid `role:"tool"` messages.
- Gemini `data:` URL image_url parts now require an `image/*` MIME
  type; a `data:text/html;base64,...` is dropped instead of being
  forwarded as `inlineData.mimeType="text/html"` (Gemini rejects
  the malformed image part). Symmetric with the fetched-remote
  image fetch path that already rejects non-image Content-Type.
- YouTube `fileData.fileUri` now declares `video/mp4` as the
  mimeType instead of `image/jpeg` guessed from the URL path. The
  YouTube/fileData input is the documented Gemini video path; the
  guessed image MIME made valid YouTube inputs malformed.
- OpenAI Responses translator preserves `response.output` ordering
  on assistant turns that emitted both text and a function_call:
  assistant text is now serialized BEFORE the function_call item
  so the subsequent function_call_output (the matching role=tool
  follow-up) lands in the right position. Previously the order
  was function_call -> assistant text -> function_call_output,
  which can confuse multi-turn function-calling flows.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: round 20 Gemini follow-ups (PR #5720)

Convergent reviewer findings from round 20:

- tool_choice="none" no longer flips responseModalities=[TEXT,IMAGE]
  on image-tier Gemini models. Forced-function tool_choice (e.g.
  {type:function, function:{name:lookup}}) also drops hosted Search /
  code execution from the Gemini body so the caller's pinned user
  function is not silently joined by hosted builtins.

- Gemini code-execution thoughtSignature replay now uses an ordered
  parts list (native_part.parts[]) so per-part signatures stay
  attached to the exact part Gemini emitted. The previous merged
  shape fanned one top-level thoughtSignature across executableCode
  + codeExecutionResult + inlineData and tripped Gemini 3 strict
  validators. Backward-compat fallback keeps pre-round-21 persisted
  history working: a legacy native_part with a single subpart still
  replays the signature on that subpart; merged legacy objects pin
  the signature to executableCode only.

- Remote-image fetch threads the remaining per-request byte budget
  into _safe_fetch_image_for_gemini, so over-budget URLs are
  refused via Content-Length pre-check / short read instead of
  fully downloaded then discarded after the aggregate cap check.

- Gemini role=tool with OpenAI list-form content
  ([{type:text,text:result}]) now flattens text parts before
  building functionResponse.response.result; previously the parts
  arrived as the result value instead of the actual tool output.

- Frontend chat-adapter merges native_part by concatenating parts
  lists (preserving per-part thoughtSignature). Wire types expose
  enable_prompt_caching as boolean|string (Gemini cached-content
  name) and OpenAIChatDelta now carries tool_calls and extra_content.

- Test test_openrouter_no_synthetic_web_search_event_on_tool_choice_none
  reads _toolEvent from the top-level SSE payload so a backend
  regression cannot mask the assertion.

Adds 7 regression tests covering image_generation gate, forced-function
gate, native_part list replay, legacy fallback, list-content
functionResponse flattening, fetch byte-budget threading, and wire
types.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply forced-function tool_choice gate to Anthropic, OpenRouter, Kimi

Previously only the Gemini path treated `tool_choice={"type":"function",
"function":{"name":...}}` as a hosted-tool opt-out. Anthropic,
OpenRouter, and Kimi still attached hosted web_search / web_fetch /
code_execution when the caller explicitly pinned a user function plus
`enabled_tools=[...]`. That contradicts the explicit function pin and
bills the caller for unwanted server-side calls.

Mirror the Gemini gate symmetrically:
  - Anthropic web_search / web_fetch / code_execution
  - OpenRouter `plugins:[{id:"web"}]` + the synthetic web_search SSE
    event the same path emits at stream close
  - Kimi `_stream_kimi_web_search` dispatch

Adds 4 regression tests:
  - test_anthropic_forced_function_tool_choice_drops_hosted_tools
  - test_openrouter_forced_function_tool_choice_drops_web_plugin
  - test_kimi_forced_function_tool_choice_skips_web_search_helper
  - test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice

All 146 existing backend tests still pass.

* Strip Gemini-only synthetic tool history on local-GGUF dispatch

After a Gemini chat that ran code_execution / image_generation, switching
the same thread to a local GGUF model used to forward the synthetic
provider-side tool_calls (tagged with `args._server_tool` or carrying a
Gemini `args.google.native_part` payload) and the message-level
`extra_content` to llama-server. The receiving backend has no tool
declaration for those names and no use for Gemini thoughtSignature
metadata; in the worst case it can produce an orphan tool_call_id and a
confused continuation.

Add `_strip_provider_synthetic_tool_history()` and wire it through the
two local message builders:
  - `_openai_messages_for_passthrough`  (OAI-compat passthrough)
  - `_openai_messages_for_gguf_chat`    (standard GGUF chat path)

Real user-function `tool_calls` and their matching `role="tool"` replies
survive unchanged; only synthetic provider-side cards and Gemini-only
`extra_content` are stripped. If the synthetic call was the assistant
turn's only payload, the now-empty turn is dropped too so llama-server
does not reject the request.

Adds 2 regression tests:
  - test_strip_provider_synthetic_tool_history_drops_synthetic_only
  - test_strip_provider_synthetic_tool_history_drops_empty_assistant

142 existing backend tests still pass.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Disable Search/Code composer pills for Gemini image-tier models

For external Gemini image-tier models (gemini-2.5-flash-image,
gemini-3.x-image-preview, etc.), the backend unconditionally strips
code_execution and strips web_search on older image ids. Search is
still allowed on Gemini 3.x Pro/Flash image models, which
supportsBuiltinWebSearch already encodes per model.

Before this commit the composer pill gates were:
  searchDisabled = !modelLoaded || !(supportsTools || supportsBuiltinWebSearch)
  codeDisabled   = !modelLoaded || !(supportsTools || supportsBuiltinCodeExecution) || imageModeDisablesCode

`supportsTools` here is a local-runtime fallback that becomes true when
any tool-capable local model has been loaded in the session. With a
local tool-capable runtime active, switching the chat to an external
Gemini image-tier model used to leave Search/Code clickable, even
though the backend will silently drop the tool on the wire.

Detect "external provider is Gemini AND the model is image-tier" (via
supportsBuiltinImageGeneration) and gate the two pills strictly on the
provider's own builtin support in that case. Non-Gemini paths and
non-image Gemini models keep the supportsTools fallback unchanged.

* Apply forced-function tool_choice gate to OpenAI Responses path

Round 22 added the gate for Gemini / Anthropic / OpenRouter / Kimi but
missed the OpenAI Responses translator. When a caller pinned a user
function via `tool_choice={"type":"function","function":{"name":...}}`
plus `enabled_tools=["web_search","code_execution","image_generation"]`,
the Responses body still attached `{"type":"web_search"}`,
`{"type":"shell"}`, and `{"type":"image_generation"}` server tools. The
function pin should suppress those for the same privacy + billing reason
the other provider paths now do.

Compute `_responses_tool_choice_forced_function` next to
`_responses_tool_choice_none` and gate each hosted-tool append on
`_responses_hosted_builtins_allowed = not none and not forced_function`.
The fix has to be applied in TWO places: the initial body builder and
`_build_body()` (called by the container-expiry retry path). User
function declarations still flow through so the pin has something to
target, and the Responses-shape `{type:"function", name:"..."}`
`tool_choice` is forwarded unchanged.

Adds regression test `test_openai_responses_forced_function_tool_choice_drops_hosted_tools`.
All 166 existing backend tests across Gemini + Responses + image-gen +
code-exec suites still pass.

* Round 24 P1s: SSRF shared-address gap + extra_content text-only leak + custom-Gemini model list

Three convergent P1s from round 24 review:

1. SSRF: the shared SSRF validator in `tools._validate_and_resolve_host`
   used a denylist (is_private / loopback / link_local / multicast /
   reserved / unspecified). Python classifies shared address space
   (100.64.0.0/10 carrier-grade NAT, plus 240.0.0.0/4, benchmarking
   ranges, etc.) with `is_private=False` AND `is_global=False`. The new
   Gemini server-side image fetcher therefore accepts URLs whose
   hostname resolves to 100.64.0.1 in cloud/VPC deployments. Add
   `not ip.is_global` as the primary gate -- a single source of truth
   that covers every current and future non-global range.

2. _strip_provider_synthetic_tool_history previously only stripped
   message-level `extra_content` when the assistant turn had tool_calls.
   A plain text Gemini reply carrying
   `extra_content.google.thought_signature` flowed through to
   llama-server when the thread was switched to a local GGUF backend.
   Always strip message-level `extra_content` on assistant turns.

3. routes/providers.list_provider_models applied Gemini's native
   `model_id_allowlist` regex to every Gemini provider, including
   custom OAI-compatible bases (LiteLLM, deployment gateways). IDs like
   `google/gemini-2.5-flash` and team-prefixed deployment aliases got
   filtered out even though the chat-dispatch path now routes them via
   the OpenAI-compatible client. Skip registry-level model-id filters
   when the configured Gemini base_url host is not the canonical
   `generativelanguage.googleapis.com`, mirroring the chat-dispatch
   gate.

Three regression tests added:
  - test_validate_and_resolve_host_blocks_shared_address_space
  - test_strip_provider_synthetic_tool_history_drops_text_only_extra_content
  - test_gemini_custom_oai_compat_base_skips_native_allowlist

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Round 25 P1s: skip synthetic server-tool replay + inline $ref/$defs into Gemini schema

Two convergent reviewer findings on the native Gemini path:

1. _stream_gemini's tool_calls replay loop falls through to a generic
   functionCall emission whenever it sees an assistant tool_call. Marked
   server-side builtin cards (web_search / web_fetch tagged with
   _server_tool or args.google.native_part) hit that fallthrough with no
   replayable native_part, which produces an outbound functionCall whose
   name is not a declared user function. The Gemini turn 400s on the
   undeclared name. Guard the loop to drop those entries instead, while
   keeping the existing code_execution / image_generation native-part
   replay branch intact.

2. _sanitize_gemini_schema uses a strict allowlist that drops local
   $ref / $defs references. Pydantic-generated tool schemas hoist nested
   object shapes into $defs and reference them via {"$ref": "#/$defs/X"},
   so a property like address: {"$ref": "#/$defs/Address"} collapsed to
   {} on the wire and the model lost the nested fields, types, and
   required keys. Resolve local #/... pointers against the schema root
   and inline the referenced subtree, with local siblings overriding
   the reference (normal JSON Schema composition) and a seen-ref guard
   for self-referential schemas.

Added regression coverage:
- test_gemini_native_skips_synthetic_server_builtin_replay
- test_function_declarations_inline_local_refs_into_gemini_schema
- test_function_declarations_inline_local_refs_in_anyof_and_items
- test_function_declarations_self_referential_schema_terminates

All 145 Gemini provider tests pass; touched provider regression set
(OpenAI Responses, code execution, image generation, Anthropic code
execution, Anthropic web_fetch) also 43/43 green.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Round 26 P1s: drop orphan Gemini functionResponse + Anthropic /messages synthetic-history strip

Reviewer round 26 surfaced two convergent asymmetric-fix bugs.

1. _stream_gemini drops a synthetic server-tool tool_call (web_search /
   web_fetch tagged _server_tool) and also replays code_execution /
   image_generation tool_calls as Gemini-native executableCode /
   codeExecutionResult / inlineData parts. The matching role="tool"
   follow-up was still falling through to the generic functionResponse
   branch, producing either an orphan functionResponse (synthetic case)
   or a duplicate response pointing at a name with no
   functionDeclarations entry (native-part case). Both forms 400 the
   next Gemini turn. Track skipped + native-replayed tool_call_ids in
   _gemini_skip_tool_result_ids and short-circuit the role="tool"
   branch on a match.

2. The Anthropic-compatible local /v1/messages route only called
   _drop_empty_assistant_sentinels on the OpenAI-translated history,
   while the sibling /v1/chat/completions and GGUF passthrough builders
   chain that with _strip_provider_synthetic_tool_history. An Anthropic
   caller replaying a prior provider-side tool_use therefore forwarded
   fake builtin tool history straight into local llama-server. Apply
   the same strip on the Anthropic route after the
   anthropic_messages_to_openai conversion.

Regression coverage added:
- test_gemini_native_skips_orphan_function_response_for_dropped_builtin
- test_gemini_native_skips_orphan_function_response_for_native_part_replay

Gemini suite 147/147; touched provider regression set 43/43.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Round 27 P1s: native_part location fallback + Gemini image request budget for base64

Two convergent reviewer findings on the native Gemini path.

1. _stream_gemini's synthetic-builtin detector at lines 3519-3524
   recognizes args.google.native_part as a server-tool marker, but
   _native_part was only loaded from tc.extra_content.google.native_part.
   A direct OpenAI-compatible API caller or imported third-party thread
   round-trips the payload through function.arguments because
   tool_calls[].extra_content is not in the OpenAI spec. The round-25
   guard then saw a synthetic builtin with no _native_part and dropped
   the entire assistant turn, so the next native Gemini request lost
   the prior executableCode / inlineData / codeExecutionResult context.
   Fall back to args.google.native_part when extra_content path is
   missing, mirroring what the synthetic detector already accepts.

2. _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES capped DECODED bytes at 20MB.
   Gemini receives images base64-encoded inside JSON, and base64
   inflates payload size by ~4/3. With 20MB decoded the actual JSON
   body is ~26.7MB plus prompt overhead, well over Gemini's ~20MB
   request limit. Drop the decoded cap to 14MB so realistic multi-
   image turns stay safely under 20MB encoded.

Added regression test test_gemini_native_part_falls_back_to_args_google
covering an OpenAI-compat-shaped image_generation tool_call whose
native_part lives only in function.arguments.

Gemini suite 148/148.

* Fix TS build errors from main merge: restore imageParts + refusal return [] + cast image-edit ref

Three errors in chat-adapter.ts surfaced by the frontend tsc step after merging
main into feat/gemini-provider:

1. The Anthropic refusal early-return used main's  but
   toOpenAIMessages returns SerializedMessage[]; flip to .
2. Restore  -- the line
   was lost when removing main's conflict block from the function body.
3. selectedImageEditReference splice was inserting OpenAIChatMessage
   into a SerializedMessage[] array; the shapes differ on tool_calls.id
   nullability. Cast the reference message through unknown -- it carries
   no tool_calls, so the runtime payload is structurally compatible.

Reproduced locally with `tsc -b --pretty false` (now passes). Build
also failing in the in-repo `npm run build` step on PR CI; this commit
unblocks all 12 failing UI/API workflows.

* Tighten verbose comments in external_provider.py + chat-adapter.ts

Compress multi-line explanatory comments in the Gemini translator
and the chat adapter without changing any behaviour. All 148 Gemini
provider tests still pass; tsc --noEmit clean.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@users.noreply.github.com>
---
 .../core/inference/external_provider.py       | 3035 +++++++--
 studio/backend/core/inference/providers.py    |   69 +-
 studio/backend/core/inference/tools.py        |   11 +-
 studio/backend/models/inference.py            |   45 +-
 studio/backend/routes/inference.py            |  356 +-
 studio/backend/routes/providers.py            |   55 +-
 .../tests/test_anthropic_code_execution.py    |    8 +-
 .../backend/tests/test_anthropic_web_fetch.py |    7 +-
 studio/backend/tests/test_gemini_provider.py  | 5501 +++++++++++++++++
 .../tests/test_openai_code_execution.py       |   10 +-
 .../tests/test_openai_image_generation.py     |    3 +
 .../test_openai_responses_translation.py      |  248 +
 .../src/components/assistant-ui/thread.tsx    |    1 +
 .../src/features/chat/api/chat-adapter.ts     |  783 ++-
 .../frontend/src/features/chat/chat-page.tsx  |   10 +-
 .../src/features/chat/external-providers.ts   |    7 +
 .../features/chat/provider-capabilities.ts    |  245 +-
 .../src/features/chat/shared-composer.tsx     |   39 +-
 .../frontend/src/features/chat/types/api.ts   |   53 +-
 19 files changed, 9874 insertions(+), 612 deletions(-)
 create mode 100644 studio/backend/tests/test_gemini_provider.py

diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index 8f34bb23fc..8a1edd608b 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -8,10 +8,12 @@ Most registry providers expose OpenAI-compatible /v1/chat/completions endpoints;
 Anthropic uses native Messages API with translation in this client.
 """
 
+import base64
 import json as _json
+import mimetypes
 import re
 import time
-from typing import Any, AsyncGenerator, Literal, NamedTuple, Optional
+from typing import Any, AsyncGenerator, Literal, NamedTuple, Optional, Union
 from urllib.parse import urlparse
 
 import httpx
@@ -506,6 +508,250 @@ def _apply_mistral_reasoning_controls(
 _http_client = httpx.AsyncClient()
 
 
+# Cap per-image fetch well below Gemini's ~20 MB total request budget.
+_GEMINI_REMOTE_IMAGE_MAX_BYTES = 10 * 1024 * 1024
+_GEMINI_REMOTE_IMAGE_TIMEOUT_S = 15.0
+
+
+def _safe_fetch_image_for_gemini_sync(
+    url: str,
+    fallback_mime: str,
+    max_bytes: int = _GEMINI_REMOTE_IMAGE_MAX_BYTES,
+) -> Optional[tuple[str, str]]:
+    """Synchronous IP-pinned HTTPS image fetch with SSRF guards.
+
+    Uses the same pinned-IP + SNI pattern as `tools._fetch_page_text` so
+    DNS rebinding between validation and the actual connection cannot
+    redirect us to a private/metadata address. Follows up to 4 hops,
+    re-validating each redirect target. Returns (mime, base64) or None.
+
+    `max_bytes` is clamped to the per-image cap and additionally lets
+    the caller pass the remaining per-request budget so an over-budget
+    URL is rejected via Content-Length (or read short-circuit) instead
+    of being fully downloaded then discarded after the fact.
+    """
+    import urllib.error
+    import urllib.request
+    from urllib.parse import urljoin, urlunparse
+
+    # Refuse upfront if the per-request budget is already spent.
+    _byte_limit = min(max(0, int(max_bytes)), _GEMINI_REMOTE_IMAGE_MAX_BYTES)
+    if _byte_limit <= 0:
+        return None
+
+    # Share tools.py's pinned-IP hardening: validate-once-then-pin.
+    from .tools import (
+        _NoRedirect,
+        _SNIHTTPSHandler,
+        _validate_and_resolve_host,
+    )
+
+    def _safe_parse_https(raw_url: str) -> Optional[tuple[Any, str, int]]:
+        """Validate https + hostname + port. Returns (parsed, host, port) or
+        None. Handles malformed-port and malformed-bracketed-IPv6 URLs that
+        would otherwise raise ValueError mid-build.
+        """
+        try:
+            parsed_url = urlparse(raw_url)
+            host_value = parsed_url.hostname
+            port_value = parsed_url.port or 443
+        except (ValueError, UnicodeError) as _err:
+            logger.info(
+                "Gemini image fetch: refusing malformed url err=%s",
+                type(_err).__name__,
+            )
+            return None
+        scheme_value = (parsed_url.scheme or "").lower()
+        if scheme_value != "https":
+            logger.info(
+                "Gemini image fetch: refusing non-https scheme=%s",
+                scheme_value,
+            )
+            return None
+        if not host_value:
+            logger.info("Gemini image fetch: refusing url with no hostname")
+            return None
+        return parsed_url, host_value, port_value
+
+    parsed_info = _safe_parse_https(url)
+    if parsed_info is None:
+        return None
+    parsed, current_host, current_port = parsed_info
+    current_url = url
+    ok, reason, pinned_ip = _validate_and_resolve_host(current_host, current_port)
+    if not ok:
+        logger.warning(
+            "Gemini image fetch: refusing host=%s reason=%s",
+            current_host,
+            reason,
+        )
+        return None
+
+    for _hop in range(4):
+        # Pin to validated IP; SNI + cert still use hostname via _SNIHTTPSHandler.
+        cp_info = _safe_parse_https(current_url)
+        if cp_info is None:
+            return None
+        cp, _cp_host, _cp_port = cp_info
+        ip_str = f"[{pinned_ip}]" if ":" in pinned_ip else pinned_ip
+        ip_netloc = f"{ip_str}:{cp.port}" if cp.port else ip_str
+        pinned_url = urlunparse(cp._replace(netloc = ip_netloc))
+
+        opener = urllib.request.build_opener(
+            _NoRedirect,
+            _SNIHTTPSHandler(current_host),
+        )
+        req = urllib.request.Request(
+            pinned_url,
+            headers = {"Host": current_host},
+            method = "GET",
+        )
+
+        try:
+            resp = opener.open(req, timeout = _GEMINI_REMOTE_IMAGE_TIMEOUT_S)
+        except urllib.error.HTTPError as e:
+            if e.code not in (301, 302, 303, 307, 308):
+                logger.info(
+                    "Gemini image fetch: status=%d host=%s",
+                    e.code,
+                    current_host,
+                )
+                return None
+            location = e.headers.get("Location")
+            if not location:
+                return None
+            try:
+                current_url = urljoin(current_url, location)
+            except (ValueError, UnicodeError) as _err:
+                logger.info(
+                    "Gemini image fetch: refusing malformed redirect err=%s",
+                    type(_err).__name__,
+                )
+                return None
+            rp_info = _safe_parse_https(current_url)
+            if rp_info is None:
+                return None
+            _rp, current_host, current_port = rp_info
+            ok2, reason2, pinned_ip = _validate_and_resolve_host(
+                current_host, current_port
+            )
+            if not ok2:
+                logger.warning(
+                    "Gemini image fetch: refusing redirect host=%s reason=%s",
+                    current_host,
+                    reason2,
+                )
+                return None
+            continue
+        except (urllib.error.URLError, OSError) as _err:
+            logger.warning(
+                "Gemini image fetch failed host=%s err=%s",
+                current_host,
+                type(_err).__name__,
+            )
+            return None
+
+        with resp:
+            status = getattr(resp, "status", None) or resp.getcode()
+            if status != 200:
+                logger.info(
+                    "Gemini image fetch: status=%s host=%s", status, current_host
+                )
+                return None
+            _hdr_mime = (
+                (resp.headers.get("content-type") or "").split(";")[0].strip().lower()
+            )
+            # Declared non-image MIME is a refusal; missing MIME falls back to caller's.
+            if _hdr_mime and not _hdr_mime.startswith("image/"):
+                logger.info(
+                    "Gemini image fetch: non-image content-type=%s host=%s",
+                    _hdr_mime,
+                    current_host,
+                )
+                return None
+            _final_mime_pre = _hdr_mime if _hdr_mime else fallback_mime
+            if not isinstance(_final_mime_pre, str) or not _final_mime_pre.startswith(
+                "image/"
+            ):
+                logger.info(
+                    "Gemini image fetch: missing content-type and no image fallback host=%s",
+                    current_host,
+                )
+                return None
+            _hdr_len = resp.headers.get("content-length")
+            if _hdr_len and _hdr_len.isdigit() and int(_hdr_len) > _byte_limit:
+                logger.info(
+                    "Gemini image fetch: declared %s bytes exceeds cap=%s host=%s",
+                    _hdr_len,
+                    _byte_limit,
+                    current_host,
+                )
+                return None
+            # Read cap+1 to detect oversize without buffering unbounded data.
+            raw = resp.read(_byte_limit + 1)
+            if len(raw) > _byte_limit:
+                logger.info(
+                    "Gemini image fetch: streamed bytes exceed cap=%s host=%s",
+                    _byte_limit,
+                    current_host,
+                )
+                return None
+            return _final_mime_pre, base64.b64encode(raw).decode("ascii")
+
+    logger.info("Gemini image fetch: too many redirects host=%s", current_host)
+    return None
+
+
+async def _safe_fetch_image_for_gemini(
+    url: str,
+    fallback_mime: str,
+    max_bytes: int = _GEMINI_REMOTE_IMAGE_MAX_BYTES,
+) -> Optional[tuple[str, str]]:
+    """Async wrapper running the IP-pinned fetch on a worker thread.
+
+    SSRF guards (https only, pinned IP, per-hop redirect re-check, size
+    cap, image/* content-type) live in the sync helper. `max_bytes`
+    carries the remaining per-request budget so over-budget URLs are
+    rejected up front.
+    """
+    import asyncio
+
+    return await asyncio.to_thread(
+        _safe_fetch_image_for_gemini_sync, url, fallback_mime, max_bytes
+    )
+
+
+# Synthetic-tool names stamped onto outbound _toolEvent.arguments so the
+# frontend can distinguish provider-side cards from real user-declared
+# tools of the same name. Mirrored on the TS side.
+_SERVER_SIDE_BUILTIN_TOOL_NAMES = frozenset(
+    {"web_search", "web_fetch", "code_execution", "image_generation"}
+)
+
+
+def _stamp_server_tool_marker(payload: dict[str, Any]) -> None:
+    """Tag synthetic provider-side tool events so the frontend can
+    distinguish them from real user-declared / local function tools of
+    the same name. The marker rides on `arguments._server_tool` and is
+    only added for known server-side builtin names; user-supplied
+    tool calls echoed back through these helpers (e.g. Kimi
+    `$web_search`) keep their existing shape because we keep this scoped
+    to the canonical builtin names.
+    """
+    if not isinstance(payload, dict):
+        return
+    if payload.get("type") != "tool_start":
+        return
+    name = payload.get("tool_name")
+    if not isinstance(name, str) or name not in _SERVER_SIDE_BUILTIN_TOOL_NAMES:
+        return
+    args = payload.get("arguments")
+    if not isinstance(args, dict):
+        args = {}
+        payload["arguments"] = args
+    args["_server_tool"] = True
+
+
 def _build_kimi_tool_end(
     synthetic_chunk_fn: Any,
     tool_call_id: str,
@@ -546,16 +792,23 @@ class ExternalProviderClient:
     ):
         self.provider_type = provider_type
         self.base_url = base_url.rstrip("/")
+        # Strip a legacy `/openai` suffix from Google-hosted bases so
+        # configs saved before the native switch still route correctly.
+        # Custom proxy paths ending in `/openai` are left untouched.
+        if self.provider_type == "gemini":
+            _parsed_base = urlparse(self.base_url)
+            if (
+                (_parsed_base.hostname or "").lower()
+                == "generativelanguage.googleapis.com"
+                and _parsed_base.path.rstrip("/") == "/v1beta/openai"
+            ):
+                self.base_url = self.base_url[: -len("/openai")]
         self.api_key = api_key
         self._timeout = httpx.Timeout(timeout, connect = 10.0)
-        # Separate timeout for SSE streams: reasoning-heavy providers
-        # (Anthropic Opus 4.7 with adaptive thinking, OpenAI gpt-5.x via
-        # /v1/responses) can pause for tens of seconds between bytes
-        # while the model is internally thinking. httpx's read timeout is
-        # the *gap* between successive reads, not a wall clock — so
-        # disabling it lets long thinks complete without cutting the
-        # stream prematurely. connect/write/pool keep the 10s / 120s
-        # bounds so genuine network failures still surface.
+        # Disable read timeout on SSE streams: reasoning-heavy models
+        # pause tens of seconds between bytes while thinking, and httpx's
+        # read timeout is the per-byte gap, not wall clock. connect/write
+        # bounds still surface real network failures.
         self._stream_timeout = httpx.Timeout(timeout, connect = 10.0, read = None)
 
     def _auth_headers(self) -> dict[str, str]:
@@ -566,6 +819,14 @@ class ExternalProviderClient:
         auth_header = provider_info.get("auth_header", "Authorization")
         auth_prefix = provider_info.get("auth_prefix", "Bearer ")
 
+        # Non-Google Gemini bases (LiteLLM, custom gateways) use OAI-compat
+        # Bearer auth, not Google's x-goog-api-key. Override the registry default.
+        if self.provider_type == "gemini":
+            _host = (urlparse(self.base_url).hostname or "").lower()
+            if _host != "generativelanguage.googleapis.com":
+                auth_header = "Authorization"
+                auth_prefix = "Bearer "
+
         headers = {"Content-Type": "application/json"}
         # Skip auth header when api_key is empty (optional for local providers);
         # httpx rejects an empty `Bearer ` value as "Illegal header value".
@@ -580,6 +841,12 @@ class ExternalProviderClient:
         from core.inference.providers import get_provider_info
 
         info = get_provider_info(self.provider_type) or {}
+        # Google-hosted Gemini uses the native translator; non-Google
+        # bases stay on OAI-compat so LiteLLM / custom proxies still work.
+        if self.provider_type == "gemini":
+            _host = (urlparse(self.base_url).hostname or "").lower()
+            if _host != "generativelanguage.googleapis.com":
+                return True
         return info.get("openai_compatible", True)
 
     async def stream_chat_completion(
@@ -594,11 +861,13 @@ class ExternalProviderClient:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         enabled_tools: Optional[list[str]] = None,
-        enable_prompt_caching: Optional[bool] = None,
+        enable_prompt_caching: Optional[Union[bool, str]] = None,
         openai_code_exec_container_id: Optional[str] = None,
         anthropic_code_exec_container_id: Optional[str] = None,
         prompt_cache_ttl: Optional[str] = None,
         compaction_threshold: Optional[int] = None,
+        tools: Optional[list[dict[str, Any]]] = None,
+        tool_choice: Optional[Any] = None,
         fast_mode: Optional[bool] = None,
         stream: bool = True,
     ) -> AsyncGenerator[str, None]:
@@ -616,7 +885,35 @@ class ExternalProviderClient:
         ``fast_mode`` only applies to Anthropic Opus 4.6 / 4.7 (silently
         dropped elsewhere); adds the beta header and ``speed: "fast"``.
         """
+        # tool_choice="none" hard-disables hosted/builtin tools across
+        # every provider so enabled_tools cannot accidentally bill or leak.
+        tool_choice_disabled = (
+            isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
+        )
+
         if not self._is_openai_compatible():
+            # Gemini speaks its own native REST shape (contents/parts);
+            # `_stream_gemini` translates request/response into the OpenAI
+            # Chat Completions chunk format the rest of Studio expects.
+            # API reference: https://ai.google.dev/gemini-api/docs
+            if self.provider_type == "gemini":
+                async for line in self._stream_gemini(
+                    messages,
+                    model,
+                    temperature,
+                    top_p,
+                    max_tokens,
+                    top_k,
+                    presence_penalty,
+                    enabled_tools,
+                    enable_prompt_caching,
+                    enable_thinking,
+                    reasoning_effort,
+                    tools,
+                    tool_choice,
+                ):
+                    yield line
+                return
             async for line in self._stream_anthropic(
                 messages,
                 model,
@@ -631,6 +928,7 @@ class ExternalProviderClient:
                 anthropic_code_exec_container_id,
                 prompt_cache_ttl,
                 compaction_threshold,
+                tool_choice,
                 fast_mode = fast_mode,
             ):
                 yield line
@@ -654,20 +952,25 @@ class ExternalProviderClient:
                 enable_prompt_caching,
                 openai_code_exec_container_id,
                 compaction_threshold,
+                tools,
+                tool_choice,
             ):
                 yield line
             return
 
-        # Kimi's $web_search is a builtin_function that requires a client
-        # round-trip: the first call returns a tool_calls envelope with
-        # function.arguments populated; the caller echoes those arguments
-        # back as a role=tool message; the second call streams the final
-        # answer with the search incorporated. The doc also mandates
-        # disabling thinking while $web_search is active. Route to a
-        # dedicated helper so the default OAI-compat path stays single-pass.
-        #   https://platform.kimi.ai/docs/guide/use-web-search
+        # Kimi $web_search needs a 2-call round-trip + thinking off; route
+        # to a helper. Forced-function tool_choice suppresses it.
+        # https://platform.kimi.ai/docs/guide/use-web-search
+        _kimi_tool_choice_forced_function = (
+            isinstance(tool_choice, dict)
+            and tool_choice.get("type") == "function"
+            and isinstance(tool_choice.get("function"), dict)
+            and bool(tool_choice["function"].get("name"))
+        )
         if (
             self.provider_type == "kimi"
+            and not tool_choice_disabled
+            and not _kimi_tool_choice_forced_function
             and enabled_tools
             and "web_search" in enabled_tools
         ):
@@ -694,28 +997,18 @@ class ExternalProviderClient:
             else:
                 body["max_tokens"] = max_tokens
 
-        # Strip body fields a provider's registry entry declares unusable —
-        # reasoning-class models that lock these to fixed defaults (e.g.
-        # Kimi k2.5/k2.6 only accept temperature=1, top_p=1) 400 otherwise.
-        # The frontend capability map already hides the matching sliders;
-        # this is the matching guard for the pydantic default that the
-        # route layer would otherwise still fill in.
+        # Drop fields the registry flags as unusable so reasoning-class
+        # models with fixed defaults (Kimi k2.6 etc) don't 400 on pydantic
+        # default values that the route layer still fills in.
         from core.inference.providers import get_provider_info
 
         provider_info = get_provider_info(self.provider_type) or {}
         for field in provider_info.get("body_omit", ()):
             body.pop(field, None)
 
-        # Kimi (kimi-k2.6, kimi-k2-thinking) accepts a boolean thinking toggle
-        # via a top-level `thinking` field (the docs show it nested under
-        # extra_body, but that is an OpenAI Python SDK convention; on the
-        # wire it merges into the request body).
-        #   - kimi-k2.6 defaults to thinking enabled; clients can pass
-        #     {"type": "disabled"} to suppress it.
-        #   - kimi-k2-thinking is always on; we never send disabled there.
-        # `keep: all` retains every thinking chunk through the stream, which
-        # is what we need so our frontend can wrap reasoning_content into
-        # the chat reasoning panel.
+        # Kimi thinking is a top-level body field. kimi-k2-thinking is
+        # always on (ignore the toggle); kimi-k2.6 defaults on, can be
+        # disabled. `keep: all` preserves every chunk for the UI panel.
         if self.provider_type == "kimi" and enable_thinking is not None:
             if model == "kimi-k2-thinking":
                 # Always on; ignore client toggle to avoid an API-level reject.
@@ -736,17 +1029,9 @@ class ExternalProviderClient:
             tpl_kw["enable_thinking"] = bool(enable_thinking)
             body["chat_template_kwargs"] = tpl_kw
 
-        # OpenRouter exposes a unified `reasoning` parameter on every
-        # chat-completion request — the gateway routes it to whichever
-        # underlying model actually supports reasoning, and silently
-        # no-ops for ones that don't. Documented at
-        #   https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
-        # Shape: `reasoning: {enabled?: bool, effort?: low|medium|high,
-        # max_tokens?: N, exclude?: bool}` with effort and max_tokens
-        # mutually exclusive. We forward either an effort level (when
-        # the user picked one) or a bare {enabled: true}. A small set of
-        # known routes rejects explicit disable with 400 ("Reasoning is
-        # mandatory for this endpoint ..."), so only those omit "off".
+        # OpenRouter's unified `reasoning` field gates per-model thinking.
+        # Some routes (`*_MANDATORY_REASONING_MODELS`) 400 on explicit off.
+        # https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
         if self.provider_type == "openrouter":
             normalized_or_model = model.strip().lower()
             if reasoning_effort in ("low", "medium", "high"):
@@ -759,17 +1044,22 @@ class ExternalProviderClient:
                 else:
                     body["reasoning"] = {"enabled": False}
 
-            # OpenRouter web-search plugin — universal shape that works
-            # for every model id, including the `openrouter/free` and
-            # `openrouter/auto` meta-routers. Documented at
-            #   https://openrouter.ai/docs/guides/features/plugins/web-search
-            # The `:online` model-suffix shortcut is "exactly equivalent
-            # to" this plugin per the same doc, but only works on
-            # concrete model ids — meta-routers reject the suffix.
-            # `plugins: [{id: "web"}]` works everywhere, no model id
-            # rewrite needed, and idempotent if some future call site
-            # adds the entry first.
-            if enabled_tools and "web_search" in enabled_tools:
+            # OpenRouter web plugin works on every model id including
+            # meta-routers (unlike the `:online` suffix). Forced-function
+            # tool_choice suppresses it, matching Gemini/Anthropic.
+            # https://openrouter.ai/docs/guides/features/plugins/web-search
+            _or_tool_choice_forced_function = (
+                isinstance(tool_choice, dict)
+                and tool_choice.get("type") == "function"
+                and isinstance(tool_choice.get("function"), dict)
+                and bool(tool_choice["function"].get("name"))
+            )
+            if (
+                not tool_choice_disabled
+                and not _or_tool_choice_forced_function
+                and enabled_tools
+                and "web_search" in enabled_tools
+            ):
                 plugins = list(body.get("plugins") or [])
                 if not any(
                     isinstance(p, dict) and p.get("id") == "web" for p in plugins
@@ -781,6 +1071,15 @@ class ExternalProviderClient:
                     body.get("model"),
                 )
 
+        # Forward OpenAI-style function tools / tool_choice on every
+        # OAI-compat route (incl. custom Gemini OpenAI proxies like
+        # LiteLLM). Without this, callers that wire user-defined tools
+        # silently lose function-calling on non-native providers.
+        if tools:
+            body["tools"] = tools
+        if tool_choice is not None:
+            body["tool_choice"] = tool_choice
+
         url = f"{self.base_url}/chat/completions"
         logger.info(
             "Proxying chat completion to %s (provider=%s, model=%s)",
@@ -816,30 +1115,22 @@ class ExternalProviderClient:
                     )
                     return
 
-                # NOTE: manual __anext__ loop instead of `async for` is intentional.
-                # On Python 3.13 + httpcore 1.0.x, `async for` auto-calls aclose() on
-                # early exit (break/return/GeneratorExit) BEFORE our finally block runs.
-                # That propagates GeneratorExit into PoolByteStream.__aiter__() while it
-                # calls `await self.aclose()` inside `with AsyncShieldCancellation()`,
-                # triggering "RuntimeError: async generator ignored GeneratorExit".
-                # Fix: call response.aclose() FIRST (sets PoolByteStream._closed=True),
-                # then lines_gen.aclose() is a no-op and GeneratorExit re-raises cleanly.
+                # Manual __anext__ (not `async for`) so we can close
+                # the response BEFORE lines_gen, avoiding the httpcore
+                # 1.0 GeneratorExit -> RuntimeError path on Python 3.13.
                 lines_gen = response.aiter_lines().__aiter__()
-                # Best-effort diagnostics for the default OAI-compat path. Without
-                # this, OpenRouter mid-stream errors (200 OK + error event in the
-                # SSE body) and OpenRouter-router model selection were invisible
-                # in the backend logs — the user only saw "Provider returned
-                # error" in the UI with no trail on the server side.
+                # Diagnostic counters for the OAI-compat path; surfaces
+                # OpenRouter mid-stream errors that would otherwise be
+                # invisible server-side.
                 event_counts: dict[str, int] = {}
                 chosen_model: Optional[str] = None
-                # Web-search tool-card synthesis for OpenRouter. The gateway
-                # doesn't emit structured web_search_call events — citations
-                # come back as `annotations` of type=url_citation on delta /
-                # message objects. Mirror the OpenAI/Anthropic UX by yielding
-                # a synthetic tool_start at stream open and tool_end at
-                # stream close with the collected citation list.
+                # OpenRouter has no web_search_call events — citations
+                # arrive as url_citation annotations. Synthesise a
+                # tool_start/tool_end pair to match the OpenAI/Anthropic UX.
                 web_search_active = (
                     self.provider_type == "openrouter"
+                    and not tool_choice_disabled
+                    and not _or_tool_choice_forced_function
                     and bool(enabled_tools)
                     and "web_search" in (enabled_tools or [])
                 )
@@ -849,6 +1140,7 @@ class ExternalProviderClient:
                 web_search_tool_ended = False
 
                 def _emit_synthetic_tool_event(payload: dict[str, Any]) -> str:
+                    _stamp_server_tool_marker(payload)
                     chunk = {
                         "id": f"chatcmpl-{self.provider_type}-synthetic",
                         "object": "chat.completion.chunk",
@@ -1104,6 +1396,7 @@ class ExternalProviderClient:
         synthetic_id = f"chatcmpl-{self.provider_type}-synthetic"
 
         def _synthetic_chunk(payload: dict[str, Any]) -> str:
+            _stamp_server_tool_marker(payload)
             chunk = {
                 "id": synthetic_id,
                 "object": "chat.completion.chunk",
@@ -1441,6 +1734,7 @@ class ExternalProviderClient:
         anthropic_code_exec_container_id: Optional[str] = None,
         prompt_cache_ttl: Optional[str] = None,
         compaction_threshold: Optional[int] = None,
+        tool_choice: Optional[Any] = None,
         *,
         fast_mode: Optional[bool] = None,
     ) -> AsyncGenerator[str, None]:
@@ -1471,6 +1765,42 @@ class ExternalProviderClient:
                 continue
 
             content = msg.get("content")
+            # OpenAI role="tool" with list content -> Anthropic native
+            # tool_result block on a user message. Translating in the
+            # string-content branch only (below) leaves the list-content
+            # form forwarded as an invalid `role:"tool"` message that
+            # Anthropic rejects. Handle both upfront.
+            if msg.get("role") == "tool":
+                _tr_id = msg.get("tool_call_id") or ""
+                if isinstance(content, list):
+                    _flat_parts: list[str] = []
+                    for part in content:
+                        if (
+                            isinstance(part, dict)
+                            and part.get("type") == "text"
+                            and part.get("text")
+                        ):
+                            _flat_parts.append(str(part["text"]))
+                    _flat_result = "".join(_flat_parts)
+                elif content is None:
+                    _flat_result = ""
+                elif isinstance(content, str):
+                    _flat_result = content
+                else:
+                    _flat_result = _json.dumps(content)
+                filtered.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": _tr_id,
+                                "content": _flat_result,
+                            }
+                        ],
+                    }
+                )
+                continue
             if isinstance(content, list):
                 # Translate OpenAI multimodal parts -> Anthropic native shapes.
                 # - `image_url`     -> `{type:"image", source:...}`
@@ -1583,6 +1913,37 @@ class ExternalProviderClient:
                             if title:
                                 doc_block["title"] = title
                             anthropic_parts.append(doc_block)
+                # Assistant tool_calls -> Anthropic tool_use blocks
+                # appended to the same message. Anthropic native
+                # Messages API does not accept OpenAI's top-level
+                # `tool_calls` field; the call lives inside a content
+                # block with `{type:"tool_use", id, name, input}`.
+                if msg.get("role") == "assistant" and isinstance(
+                    msg.get("tool_calls"), list
+                ):
+                    for _tc in msg["tool_calls"]:
+                        if not isinstance(_tc, dict):
+                            continue
+                        _fn = _tc.get("function") or {}
+                        if not isinstance(_fn, dict) or not _fn.get("name"):
+                            continue
+                        _raw = _fn.get("arguments") or "{}"
+                        try:
+                            _input = (
+                                _json.loads(_raw) if isinstance(_raw, str) else _raw
+                            )
+                        except Exception:
+                            _input = {"_raw": _raw}
+                        if not isinstance(_input, dict):
+                            _input = {"value": _input}
+                        anthropic_parts.append(
+                            {
+                                "type": "tool_use",
+                                "id": _tc.get("id") or f"toolu_{time.time_ns()}",
+                                "name": _fn["name"],
+                                "input": _input,
+                            }
+                        )
                 # Skip whole-message append when nothing usable survived.
                 # An empty content array (e.g. user dropped only an unparseable
                 # `input_document`) would 400 the Anthropic API with
@@ -1590,6 +1951,72 @@ class ExternalProviderClient:
                 if anthropic_parts:
                     filtered.append({"role": msg["role"], "content": anthropic_parts})
             else:
+                # role="tool" follow-up -> Anthropic native tool_result
+                # block on a `user` message. The OpenAI shape
+                # (role=tool, content=string, tool_call_id) is not a
+                # valid Anthropic role.
+                if msg.get("role") == "tool":
+                    _tr_id = msg.get("tool_call_id") or ""
+                    _tr_content = msg.get("content")
+                    if _tr_content is None:
+                        _tr_content = ""
+                    filtered.append(
+                        {
+                            "role": "user",
+                            "content": [
+                                {
+                                    "type": "tool_result",
+                                    "tool_use_id": _tr_id,
+                                    "content": (
+                                        _tr_content
+                                        if isinstance(_tr_content, str)
+                                        else _json.dumps(_tr_content)
+                                    ),
+                                }
+                            ],
+                        }
+                    )
+                    continue
+                # Assistant turn whose content is a plain string but
+                # also carries OpenAI `tool_calls`: convert into a
+                # content-array message with a text block + tool_use
+                # blocks. Without this, the top-level tool_calls leaks
+                # through unchanged.
+                if (
+                    msg.get("role") == "assistant"
+                    and isinstance(msg.get("tool_calls"), list)
+                    and msg["tool_calls"]
+                ):
+                    _text_content = msg.get("content")
+                    _blocks: list[dict[str, Any]] = []
+                    if isinstance(_text_content, str) and _text_content:
+                        _blocks.append({"type": "text", "text": _text_content})
+                    for _tc in msg["tool_calls"]:
+                        if not isinstance(_tc, dict):
+                            continue
+                        _fn = _tc.get("function") or {}
+                        if not isinstance(_fn, dict) or not _fn.get("name"):
+                            continue
+                        _raw = _fn.get("arguments") or "{}"
+                        try:
+                            _input = (
+                                _json.loads(_raw) if isinstance(_raw, str) else _raw
+                            )
+                        except Exception:
+                            _input = {"_raw": _raw}
+                        if not isinstance(_input, dict):
+                            _input = {"value": _input}
+                        _blocks.append(
+                            {
+                                "type": "tool_use",
+                                "id": _tc.get("id") or f"toolu_{time.time_ns()}",
+                                "name": _fn["name"],
+                                "input": _input,
+                            }
+                        )
+                    if _blocks:
+                        filtered.append({"role": "assistant", "content": _blocks})
+                    continue
                 filtered.append(msg)
 
         # Claude 4.7 family removed temperature / top_p / top_k entirely.
@@ -1616,34 +2043,16 @@ class ExternalProviderClient:
         # same as True here (callers that don't set the flag still get
         # caching). Pass False explicitly to opt out.
         prompt_caching_enabled = enable_prompt_caching is not False
-        # Anthropic accepts an optional `ttl` on each cache_control marker
-        # (default is the 5m ephemeral pool; set "1h" to land in the 1h
-        # pool instead). Per the prompt-caching docs, 1h cache writes are
-        # billed at 2x base input vs 1.25x for 5m, but reads are 0.1x for
-        # both. The 1h pool is the right pick when conversations span
-        # multiple short bursts more than 5 minutes apart -- the read
-        # discount makes up for the 1.6x write premium after a single
-        # additional hit. Anything other than the known TTL strings is
-        # dropped to avoid sending a malformed marker.
-        #
-        # The `extended-cache-ttl-2025-04-11` beta header that originally
-        # gated 1h TTL has been promoted to GA: as of 2026-05 the live
-        # API accepts `ttl: "1h"` without any beta opt-in. Verified
-        # against api.anthropic.com on claude-opus-4-7 (status 200 +
-        # `ephemeral_1h_input_tokens` populated). The test below pins
-        # the contract by asserting the header is NOT on the wire so a
-        # future regression that reintroduces the gate would surface
-        # before users see a 400.
+        # Optional 1h cache TTL is GA as of 2026-05 (no beta header). 1h
+        # writes are 2x vs 5m's 1.25x but reads are 0.1x for both, so 1h
+        # wins after a single extra hit. Unknown TTL strings drop.
         cache_marker: dict[str, Any] = {"type": "ephemeral"}
         if prompt_cache_ttl in ("5m", "1h"):
             cache_marker["ttl"] = prompt_cache_ttl
 
         if system:
             if prompt_caching_enabled:
-                # System block is the most stable prefix across turns, so
-                # it gets its own breakpoint. Skipped when system is
-                # empty — there's nothing to cache, and an empty marker
-                # is a no-op.
+                # System is the most stable cross-turn prefix; own breakpoint.
                 body["system"] = [
                     {
                         "type": "text",
@@ -1749,19 +2158,29 @@ class ExternalProviderClient:
                 if body.get("max_tokens", 0) <= budget_tokens:
                     body["max_tokens"] = budget_tokens + 1024
 
-        # Anthropic server-side web_search — see
-        #   https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
-        # The tool type is date-pinned per model family. Newer Opus /
-        # Sonnet 4.6 + 4.7 accept `web_search_20260209` with dynamic
-        # filtering (Claude writes code to filter results before they
-        # reach context); everything else uses `web_search_20250305`.
-        # `_anthropic_web_search_version` picks the right one. Anthropic
-        # dispatches search calls server-side, returning server_tool_use
-        # + web_search_tool_result blocks in the SSE stream, plus
-        # url-citation annotations on text deltas. We translate all of
-        # that into our local _toolEvent shape so the chat UI renders
-        # web_search exactly like OpenAI's path.
-        if enabled_tools and "web_search" in enabled_tools:
+        # tool_choice="none" or pinned-function suppresses hosted tools
+        # so a stale UI toggle can't fire server-side search/code-exec.
+        _anthropic_tool_choice_disabled = (
+            isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
+        )
+        _anthropic_tool_choice_forced_function = (
+            isinstance(tool_choice, dict)
+            and tool_choice.get("type") == "function"
+            and isinstance(tool_choice.get("function"), dict)
+            and bool(tool_choice["function"].get("name"))
+        )
+        _anthropic_hosted_builtins_allowed = (
+            not _anthropic_tool_choice_disabled
+            and not _anthropic_tool_choice_forced_function
+        )
+
+        # Anthropic web_search (date-pinned per model family).
+        # https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
+        if (
+            _anthropic_hosted_builtins_allowed
+            and enabled_tools
+            and "web_search" in enabled_tools
+        ):
             anthropic_tools = list(body.get("tools") or [])
             anthropic_tools.append(
                 {
@@ -1772,14 +2191,13 @@ class ExternalProviderClient:
             )
             body["tools"] = anthropic_tools
 
-        # Anthropic server-side web_fetch reads a single URL (text/PDF)
-        # and returns a `web_fetch_tool_result` document block. Opt in
-        # via `enabled_tools=["web_fetch"]`; no beta header required.
-        # `_anthropic_web_fetch_version` picks `web_fetch_20260209`
-        # (dynamic filtering) for Opus 4.6/4.7 + Sonnet 4.6, falling
-        # back to `web_fetch_20250910` elsewhere; mismatched variants
-        # return 400 so the per-model picker is required.
-        web_fetch_enabled = bool(enabled_tools and "web_fetch" in enabled_tools)
+        # Anthropic web_fetch: only URLs already in conversation. Date-pinned.
+        # https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
+        web_fetch_enabled = bool(
+            _anthropic_hosted_builtins_allowed
+            and enabled_tools
+            and "web_fetch" in enabled_tools
+        )
         if web_fetch_enabled:
             anthropic_tools = list(body.get("tools") or [])
             anthropic_tools.append(
@@ -1792,24 +2210,13 @@ class ExternalProviderClient:
             body["tools"] = anthropic_tools
 
         # Anthropic server-side code execution — see
-        #   https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
-        # The tool type is date-pinned per model family.
-        # `_anthropic_code_execution_version` picks `code_execution_20260120`
-        # for Opus 4.5+ / Sonnet 4.5+ / Opus 4.7 / Sonnet 4.6 (adds REPL
-        # state persistence + programmatic tool calling) and falls back
-        # to `code_execution_20250825` everywhere else. Both versions
-        # run Python + bash + str_replace file edits inside a 5 GB
-        # sandboxed container per request, with no internet access, and
-        # both are unlocked by the same `code-execution-2025-08-25`
-        # `anthropic-beta` header set further down. On the SSE stream
-        # Anthropic emits two sub-tool names -- `bash_code_execution`
-        # and `text_editor_code_execution` -- wrapped in the standard
-        # server_tool_use / *_tool_result block shape.
-        # v1 wires the tool only; file uploads (container_upload
-        # content blocks and generated-file retrieval via the Files
-        # API) are a deliberate follow-up.
+        # https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
+        # Date-pinned tool type per model; both unlock via the same
+        # `code-execution-2025-08-25` beta header set below.
         code_execution_enabled = bool(
-            enabled_tools and "code_execution" in enabled_tools
+            _anthropic_hosted_builtins_allowed
+            and enabled_tools
+            and "code_execution" in enabled_tools
         )
         if code_execution_enabled:
             anthropic_tools = list(body.get("tools") or [])
@@ -1820,32 +2227,14 @@ class ExternalProviderClient:
                 }
             )
             body["tools"] = anthropic_tools
-            # Reuse the prior turn's container so filesystem state
-            # (files written, packages installed, variables set)
-            # persists across turns of the same thread. Anthropic
-            # exposes the container id on the Message object's
-            # top-level `container.id`; on the SSE stream we latch it
-            # off `message_start.message.container.id` further down
-            # and emit a `container_ready` _toolEvent so the chat
-            # adapter persists it on the thread record. A stale id
-            # (container expired / not found) surfaces as a 4xx
-            # below, where we emit `container_invalidated` and let
-            # the next turn fall back to auto-create.
+            # Reuse the thread's prior container so filesystem state
+            # persists. Stale ids 4xx and clear via container_invalidated.
             if anthropic_code_exec_container_id:
                 body["container"] = anthropic_code_exec_container_id
 
-        # Server-side context compaction — see
-        #   https://platform.claude.com/docs/en/build-with-claude/compaction
-        # Beta as of `compact-2026-01-12`. When `compaction_threshold` is
-        # provided AND the model accepts compaction (Opus 4.6+ / 4.7,
-        # Sonnet 4.6, Mythos preview), attach
-        # `context_management.edits[{type:"compact_20260112", trigger:
-        # {type:"input_tokens", value:N}}]` to the body. Anthropic runs
-        # the compaction step server-side once the rendered prompt
-        # crosses the threshold and replies with a top-level
-        # `context_management` block plus `usage.iterations[]` so we can
-        # account per-iteration. Below-min thresholds get clamped up to
-        # 50K so the request doesn't 400.
+        # Server-side compaction (beta `compact-2026-01-12`). Clamps
+        # below-min thresholds to 50K so the request doesn't 400.
+        # https://platform.claude.com/docs/en/build-with-claude/compaction
         compaction_active = (
             compaction_threshold is not None
             and compaction_threshold > 0
@@ -1878,10 +2267,8 @@ class ExternalProviderClient:
         url = f"{self.base_url}/messages"
         completion_id = f"chatcmpl-anthropic-{model.replace('/', '-')}"
 
-        # Log the outgoing config keys (not the messages themselves) so we
-        # can prove which thinking/effort fields actually reached the wire.
-        # If Anthropic skips reasoning despite a configured effort, this
-        # tells us whether we sent the field or dropped it on the floor.
+        # Log outgoing config keys (not messages) to prove which thinking /
+        # effort fields actually reached the wire.
         logger.info(
             "Anthropic request shape (model=%s, has_thinking=%s, thinking=%s, "
             "output_config=%s, temperature=%s, has_top_p=%s, has_top_k=%s, "
@@ -1896,16 +2283,10 @@ class ExternalProviderClient:
             body.get("max_tokens"),
         )
 
-        # Translate Anthropic stop reasons onto the OpenAI chat-completions
-        # `finish_reason` vocabulary. `pause_turn` maps to None so the
-        # adapter does NOT emit a finish_reason chunk: pause_turn means
-        # Claude paused a long server-tool turn (web_search / web_fetch)
-        # and will continue once the user (or our retry) sends back the
-        # partial assistant message. Forwarding it as "stop" makes the
-        # OpenAI client think the answer is done and truncates the
-        # rendered message. `refusal` maps to "content_filter" as the
-        # nearest semantic match. See
-        #   https://platform.claude.com/docs/en/api/messages#response-stop-reason
+        # Anthropic stop_reason -> OpenAI finish_reason. `pause_turn`
+        # maps to None so the UI doesn't treat a paused server-tool turn
+        # as final. `refusal` -> "content_filter" (closest match).
+        # https://platform.claude.com/docs/en/api/messages#response-stop-reason
         _finish_reason_map: dict[str, Optional[str]] = {
             "end_turn": "stop",
             "max_tokens": "length",
@@ -1918,11 +2299,7 @@ class ExternalProviderClient:
         logger.info("Proxying Anthropic Messages API to %s (model=%s)", url, model)
 
         request_headers = self._auth_headers()
-        # Anthropic accepts comma-separated beta features in a single
-        # `anthropic-beta` header. Merge our flags onto whatever the
-        # registry's extra_headers contributed (currently nothing on
-        # the beta axis, just anthropic-version) so future betas
-        # added at the registry level keep working.
+        # Merge new beta flags onto whatever the registry contributed.
         existing_beta = request_headers.get("anthropic-beta", "").strip()
         beta_parts = (
             [p.strip() for p in existing_beta.split(",") if p.strip()]
@@ -1988,27 +2365,14 @@ class ExternalProviderClient:
                 # "no thinking content" — distinguishes "Anthropic never sent
                 # thinking_delta" from "frontend didn't render the chunks".
                 event_counts: dict[str, int] = {}
-                # web_search state. Anthropic emits the query inside an
-                # `input_json_delta` stream on a `server_tool_use` content
-                # block, then a separate `web_search_tool_result` block
-                # with the URL list. Unlike OpenAI we get per-call results
-                # directly, so each tool card carries its own citations.
-                # `current_server_tool_use`: {id, name, partial_json_buffer}
-                # `current_result_block`: {tool_use_id, results}
-                # Both go to None when the matching content_block_stop fires.
+                # web_search state. Query streams via input_json_delta
+                # on a server_tool_use block; results land in a separate
+                # web_search_tool_result block. Per-call citations.
                 current_server_tool_use: Optional[dict[str, Any]] = None
                 current_result_block: Optional[dict[str, Any]] = None
                 web_search_calls: dict[str, dict[str, Any]] = {}
-                # code_execution state. Anthropic's
-                # `code_execution_20250825` tool emits the same
-                # server_tool_use → *_tool_result block shape as
-                # web_search, but the server_tool_use carries one of
-                # two sub-tool names (`bash_code_execution` or
-                # `text_editor_code_execution`) and the result block
-                # type matches (`bash_code_execution_tool_result` /
-                # `text_editor_code_execution_tool_result`). Kept
-                # parallel to web_search state so the two paths don't
-                # collide when both pills are on in the same turn.
+                # code_execution state (bash / text_editor sub-tools);
+                # kept parallel to web_search so concurrent pills don't collide.
                 current_code_exec_use: Optional[dict[str, Any]] = None
                 current_code_exec_result: Optional[dict[str, Any]] = None
                 code_execution_calls: dict[str, dict[str, Any]] = {}
@@ -2078,6 +2442,7 @@ class ExternalProviderClient:
                     return f"data: {_json.dumps(chunk)}"
 
                 def _emit_tool_event(payload: dict[str, Any]) -> str:
+                    _stamp_server_tool_marker(payload)
                     chunk = {
                         "id": completion_id,
                         "object": "chat.completion.chunk",
@@ -2335,18 +2700,8 @@ class ExternalProviderClient:
                                     "inner": inner if isinstance(inner, dict) else {},
                                 }
                             elif block_type == "compaction":
-                                # Server-side compaction emits a `compaction`
-                                # content block on the assistant message.
-                                # Anthropic may include the summary text on
-                                # this start event AND/OR stream it via
-                                # text_delta events on the same block. See
-                                #   https://platform.claude.com/docs/en/build-with-claude/compaction
-                                # Capture either form; finalize and emit
-                                # on content_block_stop. The chat-adapter
-                                # persists the block onto the assistant
-                                # message so the next turn's request
-                                # carries it back -- Anthropic then skips
-                                # re-compaction from scratch.
+                                # Summary may arrive on start AND/OR via
+                                # text_delta. Capture both; emit on stop.
                                 seed = content_block.get("content") or ""
                                 current_compaction = {
                                     "content": seed if isinstance(seed, str) else "",
@@ -2356,12 +2711,7 @@ class ExternalProviderClient:
                             delta = event.get("delta", {})
                             delta_type = delta.get("type")
                             if delta_type == "thinking_delta":
-                                # Anthropic streams extended-thinking content as
-                                # thinking_delta events on a separate content
-                                # block. Wrap as inline <think>...</think> so
-                                # the frontend's parseAssistantContent lifts it
-                                # into the reasoning panel — same pattern as
-                                # the OpenAI Responses path.
+                                # Wrap as <think>...</think> for parseAssistantContent.
                                 thinking_text = delta.get("thinking", "")
                                 if thinking_text:
                                     if not thinking_open:
@@ -2631,19 +2981,9 @@ class ExternalProviderClient:
                             delta_usage = event.get("usage")
                             if isinstance(delta_usage, dict):
                                 last_usage.update(delta_usage)
-                                # When a fresh compaction has run, Anthropic
-                                # publishes per-iteration token counts in
-                                # `usage.iterations[]`. The top-level
-                                # input_tokens / output_tokens only cover the
-                                # `message` iteration, NOT the compaction
-                                # passes — billing has to sum the whole
-                                # array. See
-                                #   https://platform.claude.com/docs/en/build-with-claude/compaction
-                                # Fold the compaction iterations into
-                                # `compaction_input_tokens` / `compaction_output_tokens`
-                                # so the cost surface can add them without
-                                # re-walking the array (and so the closing
-                                # log line names the figures).
+                                # Compaction iterations aren't in top-level
+                                # input/output_tokens; fold them into
+                                # compaction_{input,output}_tokens for billing.
                                 iterations = delta_usage.get("iterations")
                                 if isinstance(iterations, list):
                                     c_in = 0
@@ -2880,6 +3220,1722 @@ class ExternalProviderClient:
                 self.provider_type,
             )
 
+    async def _stream_gemini(
+        self,
+        messages: list[dict[str, Any]],
+        model: str,
+        temperature: float,
+        top_p: float,
+        max_tokens: Optional[int],
+        top_k: Optional[int] = None,
+        presence_penalty: float = 0.0,
+        enabled_tools: Optional[list[str]] = None,
+        enable_prompt_caching: Optional[Any] = None,
+        enable_thinking: Optional[bool] = None,
+        reasoning_effort: Optional[str] = None,
+        tools: Optional[list[dict[str, Any]]] = None,
+        tool_choice: Optional[Any] = None,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Call Google's native Gemini API and translate its streaming
+        ``streamGenerateContent`` response into OpenAI Chat Completions
+        chunk format.
+
+        Gemini does NOT speak the OpenAI Chat Completions contract on
+        its primary endpoint. The wire shape is:
+
+          POST /v1beta/models/{model}:streamGenerateContent?alt=sse
+          {
+            "contents": [{"role": "user|model", "parts": [{"text": "..."}]}],
+            "systemInstruction": {"parts": [{"text": "..."}]},
+            "generationConfig": {"temperature": 0.7, "topP": 0.95, "topK": 40,
+                                  "maxOutputTokens": 1024},
+            "tools": [{"googleSearch": {}}, {"codeExecution": {}}],
+            "cachedContent": "<cache name>"  // optional, see caching docs
+          }
+
+        Streamed responses are SSE frames carrying partial
+        ``GenerateContentResponse`` objects:
+
+          {"candidates": [{"content": {"parts": [{"text": "Hello"}]},
+                            "finishReason": "STOP"}],
+           "usageMetadata": {"promptTokenCount": 7, "candidatesTokenCount": 3}}
+
+        Image generation uses the same endpoint with model
+        ``gemini-2.5-flash-image`` (also called Nano Banana); the
+        response carries an ``inlineData`` part with the base64 PNG
+        bytes and a ``mimeType``. We surface that through the same
+        ``tool_start`` / ``tool_end`` ``image_b64`` envelope the OpenAI
+        image_generation path uses, so the chat UI renders the image
+        inline with no extra plumbing.
+
+        References:
+          - https://ai.google.dev/gemini-api/docs/text-generation
+          - https://ai.google.dev/gemini-api/docs/function-calling
+          - https://ai.google.dev/gemini-api/docs/grounding
+          - https://ai.google.dev/gemini-api/docs/caching
+          - https://ai.google.dev/gemini-api/docs/image-generation
+        """
+        import json as _json
+
+        # Validate the user-controlled model id BEFORE any message
+        # translation. A model like `../cachedContents/x` is path-
+        # traversal that lands in `/v1beta/cachedContents/...`; rejecting
+        # it here also avoids triggering user-controlled outbound fetches
+        # (remote image_url inlining) on a request we'll error out
+        # anyway. Documented catalog ids match `[A-Za-z0-9._-]+`.
+        if not re.fullmatch(r"[A-Za-z0-9._-]+", model):
+            yield _error_sse_line(
+                400,
+                f"Invalid Gemini model id: {model!r}",
+                self.provider_type,
+            )
+            return
+
+        # Translate OpenAI messages -> Gemini contents. system role
+        # promotes to top-level systemInstruction.
+        system_text_parts: list[str] = []
+        contents: list[dict[str, Any]] = []
+        # OpenAI may drop `name` from role="tool" follow-ups. Remember
+        # prior function names so functionResponse isn't sent name-less
+        # (Gemini 400s on empty names).
+        tool_call_names: dict[str, str] = {}
+        # tool_call_ids whose assistant card was dropped (synthetic
+        # builtin) or already replayed as native parts. Their role="tool"
+        # follow-up must be skipped to avoid orphan/duplicate responses.
+        _gemini_skip_tool_result_ids: set[str] = set()
+        # Per-request image caps. The byte cap counts DECODED bytes; we
+        # set it to ~14 MB because base64 expansion + prompt overhead
+        # must fit Gemini's ~20 MB request limit.
+        _GEMINI_REMOTE_IMAGE_MAX_COUNT = 8
+        _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES = 14 * 1024 * 1024
+        _remote_image_count = 0
+        _remote_image_total_bytes = 0
+        for msg in messages:
+            role = msg.get("role")
+            content = msg.get("content", "")
+            if role == "system":
+                if isinstance(content, str):
+                    if content:
+                        system_text_parts.append(content)
+                elif isinstance(content, list):
+                    for part in content:
+                        if (
+                            isinstance(part, dict)
+                            and part.get("type") == "text"
+                            and part.get("text")
+                        ):
+                            system_text_parts.append(part["text"])
+                continue
+            # Map OpenAI roles to Gemini's two-role contract.
+            gemini_role = "model" if role == "assistant" else "user"
+            parts: list[dict[str, Any]] = []
+            if isinstance(content, str):
+                if content:
+                    parts.append({"text": content})
+            elif isinstance(content, list):
+                for part in content:
+                    if not isinstance(part, dict):
+                        continue
+                    ptype = part.get("type")
+                    if ptype == "text":
+                        text = part.get("text", "")
+                        if text:
+                            parts.append({"text": text})
+                    elif ptype == "image_url":
+                        url = part.get("image_url", {}).get("url", "")
+                        if url.startswith("data:"):
+                            header, _, b64data = url.partition(",")
+                            media_type = (
+                                header.split(";")[0]
+                                .replace("data:", "")
+                                .strip()
+                                .lower()
+                                or "image/jpeg"
+                            )
+                            # Symmetry with the fetched remote image
+                            # path, which already rejects non-image
+                            # Content-Type. A `data:text/html;base64,...`
+                            # URL otherwise lands as Gemini inlineData
+                            # with mimeType="text/html" and 400s the
+                            # whole request.
+                            if not media_type.startswith("image/"):
+                                logger.info(
+                                    "Gemini inlineData: refusing non-image data URL media_type=%s",
+                                    media_type,
+                                )
+                            elif b64data:
+                                # data: URLs share the same caps as fetched
+                                # URLs so inline payloads don't bypass them.
+                                _data_approx_bytes = (len(b64data) * 3) // 4
+                                if (
+                                    _remote_image_count
+                                    >= _GEMINI_REMOTE_IMAGE_MAX_COUNT
+                                ):
+                                    logger.info(
+                                        "Gemini inlineData: per-request count cap %d reached, dropping image",
+                                        _GEMINI_REMOTE_IMAGE_MAX_COUNT,
+                                    )
+                                elif (
+                                    _remote_image_total_bytes + _data_approx_bytes
+                                    > _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES
+                                ):
+                                    logger.info(
+                                        "Gemini inlineData: per-request byte cap reached, dropping image",
+                                    )
+                                else:
+                                    _remote_image_count += 1
+                                    _remote_image_total_bytes += _data_approx_bytes
+                                    parts.append(
+                                        {
+                                            "inlineData": {
+                                                "mimeType": media_type,
+                                                "data": b64data,
+                                            }
+                                        }
+                                    )
+                        elif url:
+                            # fileData.fileUri only accepts Files-API URIs
+                            # and YouTube; everything else must be downloaded
+                            # and inlined. Parse fields explicitly so
+                            # attacker URLs like https://evil.com/youtube.com/x
+                            # aren't misclassified as YouTube.
+                            try:
+                                _parsed_image_url = urlparse(url)
+                            except (ValueError, UnicodeError):
+                                _parsed_image_url = None
+                            if _parsed_image_url is None:
+                                _img_scheme = ""
+                                _img_host = ""
+                                _img_path = ""
+                            else:
+                                _img_scheme = (_parsed_image_url.scheme or "").lower()
+                                _img_host = (_parsed_image_url.hostname or "").lower()
+                                _img_path = _parsed_image_url.path or ""
+                            _is_native_uri = (
+                                _img_scheme == "https"
+                                and _img_host == "generativelanguage.googleapis.com"
+                                and _img_path.startswith("/v1beta/files/")
+                            )
+                            _is_youtube = _img_scheme == "https" and (
+                                _img_host == "youtu.be"
+                                or _img_host == "youtube.com"
+                                or _img_host.endswith(".youtube.com")
+                            )
+                            _guessed, _ = mimetypes.guess_type(_img_path)
+                            _media_type = (
+                                _guessed
+                                if isinstance(_guessed, str)
+                                and _guessed.startswith("image/")
+                                else "image/jpeg"
+                            )
+                            if _is_youtube:
+                                # YouTube URIs must use video/mp4; the
+                                # default image/jpeg yields a 400.
+                                parts.append(
+                                    {
+                                        "fileData": {
+                                            "fileUri": url,
+                                            "mimeType": "video/mp4",
+                                        }
+                                    }
+                                )
+                            elif _is_native_uri:
+                                parts.append(
+                                    {
+                                        "fileData": {
+                                            "fileUri": url,
+                                            "mimeType": _media_type,
+                                        }
+                                    }
+                                )
+                            elif _remote_image_count >= _GEMINI_REMOTE_IMAGE_MAX_COUNT:
+                                logger.info(
+                                    "Gemini image fetch: per-request count cap %d reached, dropping image",
+                                    _GEMINI_REMOTE_IMAGE_MAX_COUNT,
+                                )
+                            else:
+                                # Refuse pre-fetch when the per-request
+                                # byte budget is spent; pass the remainder
+                                # so over-budget URLs reject on Content-Length.
+                                _remaining_bytes = (
+                                    _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES
+                                    - _remote_image_total_bytes
+                                )
+                                if _remaining_bytes <= 0:
+                                    logger.info(
+                                        "Gemini image fetch: per-request byte cap already reached, dropping image",
+                                    )
+                                else:
+                                    # Count attempts before awaiting so
+                                    # slow URLs don't each burn the timeout.
+                                    _remote_image_count += 1
+                                    _fetched = await _safe_fetch_image_for_gemini(
+                                        url,
+                                        _media_type,
+                                        max_bytes = _remaining_bytes,
+                                    )
+                                    if _fetched is not None:
+                                        _final_mime, _b64 = _fetched
+                                        # base64 expands ~4/3 — recover bytes from len(_b64).
+                                        _approx_bytes = (len(_b64) * 3) // 4
+                                        if (
+                                            _remote_image_total_bytes + _approx_bytes
+                                            > _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES
+                                        ):
+                                            logger.info(
+                                                "Gemini image fetch: per-request byte cap reached, dropping image",
+                                            )
+                                        else:
+                                            _remote_image_total_bytes += _approx_bytes
+                                            parts.append(
+                                                {
+                                                    "inlineData": {
+                                                        "mimeType": _final_mime,
+                                                        "data": _b64,
+                                                    }
+                                                }
+                                            )
+            # Gemini 3 strict function-calling requires text-part
+            # thoughtSignatures to be replayed on history; the frontend
+            # stows the latest one as
+            # extra_content.google.thought_signature on the assistant
+            # message and we pin it onto the last text part here.
+            if role == "assistant" and parts:
+                _msg_extra = msg.get("extra_content") if isinstance(msg, dict) else None
+                if isinstance(_msg_extra, dict):
+                    _msg_g = _msg_extra.get("google") or {}
+                    if isinstance(_msg_g, dict):
+                        _msg_sig = _msg_g.get("thought_signature") or _msg_g.get(
+                            "thoughtSignature"
+                        )
+                        if isinstance(_msg_sig, str) and _msg_sig:
+                            for _idx in range(len(parts) - 1, -1, -1):
+                                if "text" in parts[_idx]:
+                                    parts[_idx] = {
+                                        **parts[_idx],
+                                        "thoughtSignature": _msg_sig,
+                                    }
+                                    break
+            # Translate OpenAI tool_calls into Gemini functionCall parts.
+            # code_execution / image_generation replay their native parts
+            # (executableCode / codeExecutionResult / inlineData) stowed
+            # on extra_content.google.native_part.
+            tool_calls = msg.get("tool_calls") if isinstance(msg, dict) else None
+            if isinstance(tool_calls, list):
+                for tc in tool_calls:
+                    if not isinstance(tc, dict):
+                        continue
+                    fn = tc.get("function") or {}
+                    if not isinstance(fn, dict):
+                        continue
+                    args_raw = fn.get("arguments") or "{}"
+                    if isinstance(args_raw, str):
+                        try:
+                            args = _json.loads(args_raw)
+                        except Exception:
+                            args = {"_raw": args_raw}
+                    elif isinstance(args_raw, dict):
+                        args = args_raw
+                    else:
+                        args = {}
+                    fn_name = fn.get("name", "")
+                    tc_id = tc.get("id")
+                    if fn_name and isinstance(tc_id, str) and tc_id:
+                        tool_call_names[tc_id] = fn_name
+
+                    # Replay native Gemini code_execution / image_generation parts
+                    # from extra_content.google.native_part, with fallback to
+                    # args.google.native_part for OAI-compat round-trips.
+                    _extra = tc.get("extra_content")
+                    _native_part = None
+                    _google_extra: dict[str, Any] = {}
+                    if isinstance(_extra, dict):
+                        _ge = _extra.get("google") or {}
+                        if isinstance(_ge, dict):
+                            _google_extra = _ge
+                            _native_part = _ge.get("native_part")
+                    if _native_part is None and isinstance(args, dict):
+                        _args_google = args.get("google")
+                        if isinstance(_args_google, dict):
+                            _args_np = _args_google.get("native_part")
+                            if isinstance(_args_np, dict):
+                                _native_part = _args_np
+                                if not _google_extra:
+                                    _google_extra = _args_google
+
+                    # Synthetic builtin cards (web_search/web_fetch) must
+                    # not become fake functionCalls; drop them. Native
+                    # code_execution / image_generation replay below.
+                    _name_lc = fn_name.lower() if isinstance(fn_name, str) else ""
+                    _is_synthetic_server_builtin = (
+                        _name_lc
+                        in (
+                            "web_search",
+                            "web_fetch",
+                            "code_execution",
+                            "image_generation",
+                        )
+                        and isinstance(args, dict)
+                        and (
+                            args.get("_server_tool") is True
+                            or isinstance(
+                                (args.get("google") or {}).get("native_part"), dict
+                            )
+                        )
+                    )
+                    if _is_synthetic_server_builtin and not (
+                        _name_lc in ("code_execution", "image_generation")
+                        and isinstance(_native_part, dict)
+                    ):
+                        # No replayable Gemini native part -- skip
+                        # entirely rather than send a fake functionCall.
+                        # Also remember this tool_call_id so a matching
+                        # role="tool" follow-up does not become an
+                        # orphan functionResponse below.
+                        if isinstance(tc_id, str) and tc_id:
+                            _gemini_skip_tool_result_ids.add(tc_id)
+                            tool_call_names.pop(tc_id, None)
+                        continue
+                    if fn_name in ("code_execution", "image_generation") and isinstance(
+                        _native_part, dict
+                    ):
+                        # code_execution/image_generation history is
+                        # replayed as native parts; the matching
+                        # role="tool" must be skipped or Gemini sees a
+                        # functionResponse with no declared function
+                        # name and 400s the turn.
+                        if isinstance(tc_id, str) and tc_id:
+                            _gemini_skip_tool_result_ids.add(tc_id)
+                        # New shape: `native_part.parts` is an ordered list
+                        # of full part wrappers, each carrying its own
+                        # `thoughtSignature`. This preserves Gemini 3's
+                        # strict per-part replay requirement when the
+                        # frontend has merged executableCode +
+                        # codeExecutionResult + inlineData into the same
+                        # tool-call card.
+                        _native_parts_list = _native_part.get("parts")
+                        if isinstance(_native_parts_list, list):
+                            for _entry in _native_parts_list:
+                                if isinstance(_entry, dict):
+                                    parts.append(_entry)
+                            continue
+                        # Legacy single-object native_part: fan the shared
+                        # thoughtSignature only when one subpart exists;
+                        # for code+result, prefer executableCode and drop
+                        # the signature elsewhere.
+                        _legacy_sig = _native_part.get(
+                            "thoughtSignature"
+                        ) or _native_part.get("thought_signature")
+                        _legacy_subparts = [
+                            _k
+                            for _k in (
+                                "executableCode",
+                                "codeExecutionResult",
+                                "inlineData",
+                            )
+                            if isinstance(_native_part.get(_k), dict)
+                        ]
+                        for _native_key in (
+                            "executableCode",
+                            "codeExecutionResult",
+                            "inlineData",
+                        ):
+                            _sub = _native_part.get(_native_key)
+                            if not isinstance(_sub, dict):
+                                continue
+                            _replay_part: dict[str, Any] = {_native_key: _sub}
+                            if isinstance(_legacy_sig, str) and _legacy_sig:
+                                if len(_legacy_subparts) == 1:
+                                    _replay_part["thoughtSignature"] = _legacy_sig
+                                elif _native_key == "executableCode":
+                                    _replay_part["thoughtSignature"] = _legacy_sig
+                            parts.append(_replay_part)
+                        continue
+
+                    # Forward the OpenAI tool_call id into Gemini's
+                    # functionCall.id so a follow-up turn that issues
+                    # multiple calls to the same function (different
+                    # args, same name) can be disambiguated on the
+                    # response side. Gemini accepts the field per
+                    # https://ai.google.dev/gemini-api/docs/function-calling.
+                    function_call_part: dict[str, Any] = {
+                        "name": fn_name,
+                        "args": args,
+                    }
+                    if isinstance(tc_id, str) and tc_id:
+                        function_call_part["id"] = tc_id
+                    # Gemini 3 function-calling requires the prior
+                    # thoughtSignature to be echoed back as a sibling
+                    # of the functionCall part. The translator stows
+                    # it on the assistant tool_call via
+                    # `extra_content.google.thought_signature` (see
+                    # the inbound emit below).
+                    fc_part: dict[str, Any] = {"functionCall": function_call_part}
+                    sig = _google_extra.get("thought_signature") or _google_extra.get(
+                        "thoughtSignature"
+                    )
+                    if isinstance(sig, str) and sig:
+                        fc_part["thoughtSignature"] = sig
+                    parts.append(fc_part)
+            if role == "tool":
+                # If the matching assistant-side tool_call was either
+                # dropped (synthetic server-tool with no native part)
+                # or already replayed as Gemini-native parts
+                # (code_execution/image_generation native_part), drop
+                # the follow-up too. Emitting it as a functionResponse
+                # would be orphaned or duplicate the native result.
+                _tc_id_for_skip = msg.get("tool_call_id")
+                if (
+                    isinstance(_tc_id_for_skip, str)
+                    and _tc_id_for_skip in _gemini_skip_tool_result_ids
+                ):
+                    continue
+                # OpenAI's role="tool" follow-up carries the function
+                # result. Gemini's matching shape is a role="user" turn
+                # with a functionResponse part. When the caller dropped
+                # ``name``, recover it from the matching assistant
+                # tool_call so Gemini doesn't 400 on an empty name.
+                tool_name = msg.get("name") or msg.get("tool_name") or ""
+                if not tool_name:
+                    tc_id = msg.get("tool_call_id")
+                    if isinstance(tc_id, str) and tc_id in tool_call_names:
+                        tool_name = tool_call_names[tc_id]
+                response_payload: Any
+                if isinstance(content, list):
+                    # OpenAI tool messages may carry list-form content
+                    # (`[{"type":"text","text":"..."}]`). Forwarding the
+                    # content-part objects verbatim into Gemini's
+                    # `functionResponse.response.result` yields
+                    # `result:[{"type":"text","text":"..."}]` instead of
+                    # the actual tool output text; flatten text parts so
+                    # the result mirrors the string-content path.
+                    _flat_parts: list[str] = []
+                    for _cpart in content:
+                        if (
+                            isinstance(_cpart, dict)
+                            and _cpart.get("type") == "text"
+                            and isinstance(_cpart.get("text"), str)
+                        ):
+                            _flat_parts.append(_cpart["text"])
+                    _flat_text = "".join(_flat_parts)
+                    try:
+                        response_payload = _json.loads(_flat_text)
+                    except Exception:
+                        response_payload = {"result": _flat_text}
+                elif isinstance(content, str):
+                    try:
+                        response_payload = _json.loads(content)
+                    except Exception:
+                        response_payload = {"result": content}
+                else:
+                    response_payload = content or {}
+                function_response_part: dict[str, Any] = {
+                    "name": tool_name,
+                    "response": (
+                        response_payload
+                        if isinstance(response_payload, dict)
+                        else {"result": response_payload}
+                    ),
+                }
+                # Mirror tool_call_id onto functionResponse.id so
+                # Gemini can match the result to the originating
+                # functionCall when multiple parallel calls were made.
+                tc_id = msg.get("tool_call_id")
+                if isinstance(tc_id, str) and tc_id:
+                    function_response_part["id"] = tc_id
+                parts = [{"functionResponse": function_response_part}]
+                gemini_role = "user"
+            if parts:
+                # Gemini expects parallel functionResponses (multiple
+                # OpenAI role="tool" messages in a row) to ride on a
+                # single user content with multiple functionResponse
+                # parts -- the docs show parallel responses grouped
+                # together in the next turn. Merge consecutive
+                # functionResponse-only user blocks so realistic
+                # parallel tool loops round-trip correctly.
+                if (
+                    role == "tool"
+                    and contents
+                    and contents[-1].get("role") == "user"
+                    and all(
+                        isinstance(p, dict) and "functionResponse" in p
+                        for p in (contents[-1].get("parts") or [])
+                    )
+                ):
+                    contents[-1]["parts"].extend(parts)
+                else:
+                    contents.append({"role": gemini_role, "parts": parts})
+
+        body: dict[str, Any] = {"contents": contents}
+        if system_text_parts:
+            body["systemInstruction"] = {
+                "parts": [{"text": "\n\n".join(system_text_parts)}]
+            }
+
+        # Generation config -- temperature / topP / topK / maxOutputTokens
+        # map straight across. The frontend capability matrix restricts
+        # the sliders the UI exposes for Gemini to this set.
+        gen_config: dict[str, Any] = {}
+        if temperature is not None:
+            gen_config["temperature"] = temperature
+        if top_p is not None:
+            gen_config["topP"] = top_p
+        if top_k is not None and top_k > 0:
+            gen_config["topK"] = top_k
+        # Gemini accepts ``presencePenalty`` on generationConfig with the
+        # same sign convention as the OpenAI knob (positive discourages
+        # repetition). Forward when the caller bothers to set it.
+        if presence_penalty:
+            gen_config["presencePenalty"] = presence_penalty
+        if max_tokens is not None:
+            gen_config["maxOutputTokens"] = max_tokens
+
+        # Nano Banana image generation. Gemini only accepts
+        # `responseModalities: ["TEXT","IMAGE"]` on the image-capable
+        # model family (id contains `-image` or `nano-banana`). Text-
+        # only models such as `gemini-2.5-flash` 400 on the same body,
+        # so only force image mode when the selected model actually
+        # supports it -- a stale `enabled_tools=["image_generation"]`
+        # on a text model is silently treated as a regular turn.
+        # https://ai.google.dev/gemini-api/docs/image-generation
+        model_lc = model.lower()
+        is_image_picker_model = "-image" in model_lc or "nano-banana" in model_lc
+        # tool_choice="none" / forced-function tool_choice must also
+        # suppress the implicit image-generation hosted tool. Otherwise
+        # an explicit OpenAI-style opt-out (or an explicit user-function
+        # pin) still flips `responseModalities=["TEXT","IMAGE"]` on
+        # image-tier models and bills for image output.
+        _tool_choice_disabled = (
+            isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
+        )
+        _tool_choice_forced_function = (
+            isinstance(tool_choice, dict)
+            and tool_choice.get("type") == "function"
+            and isinstance(tool_choice.get("function"), dict)
+            and bool(tool_choice["function"].get("name"))
+        )
+        _hosted_builtins_allowed = (
+            not _tool_choice_disabled and not _tool_choice_forced_function
+        )
+        # Image-tier model IDs reject text-only tools (code_execution,
+        # user functions) and thinkingConfig regardless of whether the
+        # Images pill is on -- those are model-level constraints
+        # documented by Google. The pill only controls whether we ask
+        # Gemini to actually emit image output via
+        # `responseModalities: ["TEXT","IMAGE"]`. Decoupling the two
+        # avoids the case where Images is off + Code/Search is on
+        # forwards `tools: [{codeExecution: {}}]` plus
+        # `thinkingConfig` to an image model and 400s.
+        image_tool_requested = bool(
+            _hosted_builtins_allowed
+            and enabled_tools
+            and "image_generation" in enabled_tools
+        )
+        # Strict tool / thinking strip uses the model-id check.
+        is_image_model_strict = is_image_picker_model
+        # The actual modality flip only happens when the user opted in.
+        is_image_model = is_image_picker_model and image_tool_requested
+        if is_image_model:
+            gen_config["responseModalities"] = ["TEXT", "IMAGE"]
+        elif is_image_picker_model:
+            # Force TEXT-only so an image-capable model with Images OFF
+            # doesn't still bill for image output.
+            gen_config["responseModalities"] = ["TEXT"]
+
+        # Thinking control. Gemini 3 uses thinkingLevel (str), 2.5 uses
+        # thinkingBudget (int). Gemini 3 has no full-off; minimum is
+        # "minimal" on Flash, "low" on Pro.
+        # https://ai.google.dev/gemini-api/docs/thinking
+        _GEMINI3_THINKING_PREFIXES = (
+            "gemini-3.5-",
+            "gemini-3.1-",
+            "gemini-3-",
+            "gemini-pro-latest",
+            "gemini-flash-latest",
+            "gemini-flash-lite-latest",
+        )
+        _GEMINI3_PRO_PREFIXES = (
+            "gemini-3.5-pro",
+            "gemini-3.1-pro",
+            "gemini-3-pro",
+            "gemini-pro-latest",
+        )
+        _PRO_THINKING_PREFIXES = ("gemini-2.5-pro",)
+        is_gemini3_thinking = any(
+            model_lc.startswith(p) for p in _GEMINI3_THINKING_PREFIXES
+        )
+        is_gemini3_pro = any(model_lc.startswith(p) for p in _GEMINI3_PRO_PREFIXES)
+        _is_pro_thinking_only = any(
+            model_lc == p or model_lc.startswith(p + "-")
+            for p in _PRO_THINKING_PREFIXES
+        )
+        effort_lc = (reasoning_effort or "").strip().lower()
+        if not is_image_model_strict and is_gemini3_thinking:
+            # Gemini 3.x thinkingLevel matrix:
+            #   3.1+ Pro:    low/medium/high
+            #   3 Pro:       low/high (deprecated 2026-03-09)
+            #   3.x Flash*:  minimal/low/medium/high
+            # Coerce minimal->low on Pro; medium->high on legacy 3-Pro.
+            _G3_LEVELS = {"minimal", "low", "medium", "high"}
+            level: Optional[str] = None
+            if effort_lc in ("none", "off"):
+                level = "low" if is_gemini3_pro else "minimal"
+            elif effort_lc == "max":
+                level = "high"
+            elif effort_lc in _G3_LEVELS:
+                # Coerce legacy 3-Pro (low/high only) inputs.
+                _is_legacy_gemini3_pro = model_lc.startswith(
+                    ("gemini-3-pro-preview", "gemini-3-pro")
+                ) and not model_lc.startswith(("gemini-3.1-pro", "gemini-3.5-pro"))
+                if is_gemini3_pro and effort_lc == "minimal":
+                    level = "low"
+                elif _is_legacy_gemini3_pro and effort_lc == "medium":
+                    level = "high"
+                else:
+                    level = effort_lc
+            elif enable_thinking is True:
+                level = "high"
+            elif enable_thinking is False:
+                level = "low" if is_gemini3_pro else "minimal"
+            if level is not None:
+                gen_config["thinkingConfig"] = {"thinkingLevel": level}
+        elif not is_image_model_strict:
+            # Gemini 2.5 / older: thinkingBudget int. Effort -> budget
+            # mirrors the OpenAI minimal/low/medium/high ladder so the
+            # existing frontend picker maps cleanly.
+            # NOTE: gemini-2.5-flash-lite rejects positive budgets below
+            # 512 with HTTP 400, so minimal=512 sits at that floor.
+            _EFFORT_TO_BUDGET: dict[str, int] = {
+                "minimal": 512,
+                "low": 2048,
+                "medium": 8192,
+                "high": 24576,
+                "xhigh": -1,
+                "max": -1,
+            }
+            thinking_budget: Optional[int] = None
+            if effort_lc == "none" or enable_thinking is False:
+                # Pro-tier 2.5 rejects budget=0 (400 "only works in
+                # thinking mode"), so coerce to a small positive value.
+                thinking_budget = 128 if _is_pro_thinking_only else 0
+            elif effort_lc in _EFFORT_TO_BUDGET:
+                thinking_budget = _EFFORT_TO_BUDGET[effort_lc]
+            elif enable_thinking is True:
+                thinking_budget = -1
+            if thinking_budget is not None:
+                gen_config["thinkingConfig"] = {
+                    "thinkingBudget": thinking_budget,
+                }
+
+        if gen_config:
+            body["generationConfig"] = gen_config
+
+        # Hosted tools: googleSearch (grounding) and codeExecution.
+        # Image-mode rejects codeExecution; only Gemini 3 image models
+        # accept googleSearch.
+        # https://ai.google.dev/gemini-api/docs/grounding
+        # https://ai.google.dev/gemini-api/docs/code-execution
+        def _gemini_image_model_allows_google_search(_m: str) -> bool:
+            return (
+                _m.startswith("gemini-3-pro-image")
+                or _m.startswith("gemini-3.1-flash-image")
+                or _m.startswith("nano-banana-pro")
+                or _m.startswith("nano-banana-2")
+            )
+
+        google_search_allowed = (
+            not is_image_model_strict
+            or _gemini_image_model_allows_google_search(model_lc)
+        )
+        code_execution_allowed = not is_image_model_strict
+        text_tools_allowed = not is_image_model_strict
+        # tool_choice="none" / forced-function suppresses hosted builtins
+        # too, matching the Anthropic / OpenRouter gates.
+        tools_array: list[dict[str, Any]] = []
+        if (
+            _hosted_builtins_allowed
+            and enabled_tools
+            and "web_search" in enabled_tools
+            and google_search_allowed
+        ):
+            tools_array.append({"googleSearch": {}})
+        if (
+            _hosted_builtins_allowed
+            and enabled_tools
+            and "code_execution" in enabled_tools
+            and code_execution_allowed
+        ):
+            tools_array.append({"codeExecution": {}})
+        # OpenAI-style function declarations -> Gemini functionDeclarations.
+        # https://ai.google.dev/gemini-api/docs/function-calling#step_1
+        # Gemini's Schema accepts only the OpenAPI 3.0 subset documented
+        # at https://ai.google.dev/api/caching#Schema; OpenAI's strict
+        # tool definitions routinely include `additionalProperties`,
+        # `$schema`, `$defs`, `strict`, `examples`, and similar keys
+        # which 400 the request as INVALID_ARGUMENT. Strip them
+        # recursively before forwarding.
+        _GEMINI_ALLOWED_SCHEMA_KEYS = frozenset(
+            {
+                "type",
+                "format",
+                "title",
+                "description",
+                "nullable",
+                "enum",
+                "maxItems",
+                "minItems",
+                "properties",
+                "required",
+                "minProperties",
+                "maxProperties",
+                "items",
+                "minimum",
+                "maximum",
+                "minLength",
+                "maxLength",
+                "pattern",
+                "default",
+                "anyOf",
+                "propertyOrdering",
+            }
+        )
+
+        def _resolve_local_schema_ref(
+            root: Optional[dict[str, Any]], ref: str
+        ) -> Optional[Any]:
+            # Walk a `#/foo/bar` JSON pointer against the schema root.
+            # Returns None if the pointer doesn't resolve to a dict, so
+            # the caller can fall back to the unresolved node.
+            if not isinstance(root, dict) or not isinstance(ref, str):
+                return None
+            if not ref.startswith("#/"):
+                return None
+            node: Any = root
+            for raw_part in ref[2:].split("/"):
+                if not raw_part:
+                    continue
+                part = raw_part.replace("~1", "/").replace("~0", "~")
+                if not isinstance(node, dict) or part not in node:
+                    return None
+                node = node[part]
+            return node
+
+        def _sanitize_gemini_schema(
+            node: Any,
+            root: Optional[dict[str, Any]] = None,
+            _seen_refs: Optional[frozenset[str]] = None,
+        ) -> Any:
+            # Recursively filter to Gemini's OpenAPI 3.0 subset. At a
+            # Schema-keyword dict layer we drop keys not in the
+            # allowlist; under `properties` the keys are user-defined
+            # field names and the values are themselves Schemas; under
+            # `items` / `anyOf` the values are also Schemas.
+            # OpenAI strict tools commonly use JSON Schema's
+            # `"type": ["string", "null"]` form for nullable fields;
+            # Gemini's OpenAPI Schema uses `"type": "string"` plus
+            # `"nullable": true`. Translate that here.
+            if root is None and isinstance(node, dict):
+                root = node
+            if _seen_refs is None:
+                _seen_refs = frozenset()
+            if isinstance(node, dict):
+                # Pydantic / OpenAI strict tools commonly hoist nested
+                # object schemas into `$defs` and reference them via
+                # `{"$ref": "#/$defs/Address"}`. Gemini's OpenAPI subset
+                # has no $ref and drops anything not in the allowlist,
+                # so the referenced shape would vanish if we didn't
+                # inline it here. Recurse into the resolved target with
+                # local siblings overriding the reference (normal JSON
+                # Schema composition), guarding against ref cycles.
+                _ref = node.get("$ref")
+                if isinstance(_ref, str):
+                    if _ref in _seen_refs:
+                        return {}
+                    _target = _resolve_local_schema_ref(root, _ref)
+                    if isinstance(_target, dict):
+                        _merged = {
+                            **_target,
+                            **{k: v for k, v in node.items() if k != "$ref"},
+                        }
+                        return _sanitize_gemini_schema(
+                            _merged, root, _seen_refs | {_ref}
+                        )
+                cleaned: dict[str, Any] = {}
+                _nullable_from_union = False
+                _flattened_type: Optional[str] = None
+                _union_any_of: Optional[list[dict[str, Any]]] = None
+                _raw_type = node.get("type")
+                if isinstance(_raw_type, list):
+                    _non_null = [t for t in _raw_type if t != "null"]
+                    if len(_non_null) < len(_raw_type):
+                        _nullable_from_union = True
+                    if len(_non_null) == 1:
+                        _flattened_type = _non_null[0]
+                    elif len(_non_null) > 1:
+                        # Preserve multi-type unions as anyOf; flattening
+                        # to the first non-null type silently drops the
+                        # other branches and changes the tool contract.
+                        _union_any_of = [
+                            {"type": _t} for _t in _non_null if isinstance(_t, str)
+                        ]
+                for _k, _v in node.items():
+                    if _k == "type" and isinstance(_v, list):
+                        # Handled below via _flattened_type.
+                        continue
+                    if _k not in _GEMINI_ALLOWED_SCHEMA_KEYS:
+                        continue
+                    if _k == "properties" and isinstance(_v, dict):
+                        cleaned[_k] = {
+                            _name: _sanitize_gemini_schema(_subschema, root, _seen_refs)
+                            for _name, _subschema in _v.items()
+                        }
+                    elif _k == "items":
+                        cleaned[_k] = _sanitize_gemini_schema(_v, root, _seen_refs)
+                    elif _k == "anyOf" and isinstance(_v, list):
+                        # Optional[X] / Union[A, B, None]: Pydantic emits
+                        # `anyOf: [..., {"type":"null"}]`. Gemini's
+                        # OpenAPI subset rejects `"type": "null"` inside
+                        # anyOf, so drop the null variant and surface it
+                        # via `nullable: true`. If exactly one non-null
+                        # branch remains, collapse it inline; otherwise
+                        # keep the slim anyOf and mark the field
+                        # nullable.
+                        _saw_null = any(
+                            isinstance(_entry, dict) and _entry.get("type") == "null"
+                            for _entry in _v
+                        )
+                        _non_null_entries = [
+                            _entry
+                            for _entry in _v
+                            if not (
+                                isinstance(_entry, dict)
+                                and _entry.get("type") == "null"
+                            )
+                        ]
+                        if len(_non_null_entries) == 1 and _saw_null:
+                            _inner = _sanitize_gemini_schema(
+                                _non_null_entries[0], root, _seen_refs
+                            )
+                            if isinstance(_inner, dict):
+                                for _ik, _iv in _inner.items():
+                                    cleaned.setdefault(_ik, _iv)
+                                cleaned.setdefault("nullable", True)
+                        else:
+                            cleaned[_k] = [
+                                _sanitize_gemini_schema(_entry, root, _seen_refs)
+                                for _entry in _non_null_entries
+                            ]
+                            if _saw_null:
+                                cleaned.setdefault("nullable", True)
+                    elif _k in ("required", "enum", "propertyOrdering"):
+                        # Lists of plain strings; copy verbatim.
+                        cleaned[_k] = _v
+                    else:
+                        cleaned[_k] = _v
+                if _union_any_of is not None and "anyOf" not in cleaned:
+                    cleaned["anyOf"] = [
+                        _sanitize_gemini_schema(_s, root, _seen_refs)
+                        for _s in _union_any_of
+                    ]
+                elif _flattened_type is not None:
+                    cleaned["type"] = _flattened_type
+                if _nullable_from_union and "nullable" not in cleaned:
+                    cleaned["nullable"] = True
+                return cleaned
+            return node
+
+        function_declarations: list[dict[str, Any]] = []
+        if tools and text_tools_allowed and not _tool_choice_disabled:
+            for _tool in tools:
+                if not isinstance(_tool, dict) or _tool.get("type") != "function":
+                    continue
+                _fn = _tool.get("function")
+                if not isinstance(_fn, dict) or not _fn.get("name"):
+                    continue
+                _decl: dict[str, Any] = {
+                    "name": _fn["name"],
+                    "description": _fn.get("description") or "",
+                }
+                _params = _fn.get("parameters")
+                if isinstance(_params, dict):
+                    _decl["parameters"] = _sanitize_gemini_schema(_params)
+                function_declarations.append(_decl)
+        if function_declarations:
+            tools_array.append({"functionDeclarations": function_declarations})
+        if tools_array:
+            body["tools"] = tools_array
+        # Tool-choice mapping: OpenAI "auto"/"none"/"required"/{name=...}
+        # -> Gemini toolConfig.functionCallingConfig.mode + allowedFunctionNames.
+        if tool_choice is not None and function_declarations and text_tools_allowed:
+            _mode: Optional[str] = None
+            _allowed: Optional[list[str]] = None
+            if isinstance(tool_choice, str):
+                _tc_lc = tool_choice.strip().lower()
+                if _tc_lc == "auto":
+                    _mode = "AUTO"
+                elif _tc_lc == "none":
+                    _mode = "NONE"
+                elif _tc_lc in ("required", "any"):
+                    _mode = "ANY"
+            elif (
+                isinstance(tool_choice, dict) and tool_choice.get("type") == "function"
+            ):
+                _fn_pick = tool_choice.get("function") or {}
+                _name = _fn_pick.get("name") if isinstance(_fn_pick, dict) else None
+                if isinstance(_name, str) and _name:
+                    _mode = "ANY"
+                    _allowed = [_name]
+            if _mode is not None:
+                _fcc: dict[str, Any] = {"mode": _mode}
+                if _allowed:
+                    _fcc["allowedFunctionNames"] = _allowed
+                body["toolConfig"] = {"functionCallingConfig": _fcc}
+
+        # Prompt caching. The Gemini caching contract is "create a
+        # CachedContent resource, then pass its name on
+        # `cachedContent`". The cache itself is created out of band by
+        # the caller via POST /cachedContents; here we forward an
+        # explicit cache id when the dispatcher hands us one (a string
+        # value on enable_prompt_caching means "use this cache name").
+        # https://ai.google.dev/gemini-api/docs/caching
+        if isinstance(enable_prompt_caching, str) and enable_prompt_caching:
+            body["cachedContent"] = enable_prompt_caching
+
+        # Model id is already validated at the top of _stream_gemini so
+        # we never reach a path-traversed URL segment here.
+        url = f"{self.base_url}/models/{model}:streamGenerateContent?alt=sse"
+        completion_id = f"chatcmpl-gemini-{model.replace('/', '-')}"
+
+        logger.info(
+            "Proxying Gemini streamGenerateContent to %s (model=%s, "
+            "tools=%s, image=%s)",
+            url,
+            model,
+            [list(t.keys())[0] for t in tools_array] if tools_array else [],
+            is_image_model,
+        )
+
+        def _emit_tool_event(payload: dict[str, Any]) -> str:
+            _stamp_server_tool_marker(payload)
+            chunk = {
+                "id": completion_id,
+                "object": "chat.completion.chunk",
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": {},
+                        "finish_reason": None,
+                    }
+                ],
+                "_toolEvent": payload,
+            }
+            return f"data: {_json.dumps(chunk)}"
+
+        def _text_chunk(
+            text: str, extra_content: Optional[dict[str, Any]] = None
+        ) -> str:
+            delta: dict[str, Any] = {"content": text}
+            if extra_content:
+                delta["extra_content"] = extra_content
+            chunk = {
+                "id": completion_id,
+                "object": "chat.completion.chunk",
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": delta,
+                        "finish_reason": None,
+                    }
+                ],
+            }
+            return f"data: {_json.dumps(chunk)}"
+
+        def _gemini_part_extra(part: dict[str, Any]) -> Optional[dict[str, Any]]:
+            """Return ``{"google": {"thought_signature": ...}}`` when the
+            Gemini stream part carries a `thoughtSignature` we need to
+            replay on a follow-up turn (Gemini 3 image editing + tool
+            contexts both require an exact signature echo)."""
+            sig = part.get("thoughtSignature") or part.get("thought_signature")
+            if isinstance(sig, str) and sig:
+                return {"google": {"thought_signature": sig}}
+            return None
+
+        # Gemini finish reasons -> OpenAI vocabulary. Reference:
+        # https://ai.google.dev/api/rest/v1beta/Candidate#FinishReason
+        _finish_reason_map: dict[str, Optional[str]] = {
+            "STOP": "stop",
+            "MAX_TOKENS": "length",
+            "SAFETY": "content_filter",
+            "RECITATION": "content_filter",
+            "PROHIBITED_CONTENT": "content_filter",
+            "BLOCKLIST": "content_filter",
+            "MALFORMED_FUNCTION_CALL": "stop",
+            "OTHER": "stop",
+            "FINISH_REASON_UNSPECIFIED": None,
+        }
+
+        last_usage: Optional[dict[str, Any]] = None
+        emitted_function_call_ids: set[str] = set()
+        # True once any Gemini functionCall part has been emitted so the
+        # final finish_reason swaps STOP -> tool_calls (matches the
+        # OpenAI Chat Completions contract; an OAI client that sees a
+        # tool_calls delta followed by finish_reason="stop" never
+        # executes the tool).
+        emitted_any_function_call = False
+        # web_search_active drives the tool_start / tool_end envelope.
+        # Track on whether `googleSearch` was actually forwarded above,
+        # not the raw caller intent -- image-mode requests filter the
+        # tool out, and emitting a phantom "search complete" card on a
+        # turn where Gemini was never told to search confuses the UI.
+        web_search_active = any("googleSearch" in t for t in tools_array)
+        web_search_tool_id = "gemini_web_search"
+        web_search_tool_started = False
+        web_search_tool_ended = False
+        web_search_citations: list[dict[str, str]] = []
+        # Tracks the tool_call_id minted on the most recent
+        # executableCode part so the matching codeExecutionResult can
+        # close out the same envelope. None between rounds.
+        gemini_code_exec_pending_id: Optional[str] = None
+        # The most recently emitted code_execution id + result text. Kept
+        # *after* the tool_end so a following inline image (matplotlib
+        # plot rendered by codeExecution) can attach to the same card
+        # via a `__IMAGES__:` marker instead of spawning a separate
+        # image_generation event.
+        last_code_exec_tool_id: Optional[str] = None
+        last_code_exec_result_text: str = ""
+
+        try:
+            async with _http_client.stream(
+                "POST",
+                url,
+                json = body,
+                headers = self._auth_headers(),
+                timeout = self._stream_timeout,
+            ) as response:
+                if response.status_code != 200:
+                    error_body = await response.aread()
+                    error_text = error_body.decode("utf-8", errors = "replace")
+                    logger.error(
+                        "Gemini returned %d: %s",
+                        response.status_code,
+                        error_text[:500],
+                    )
+                    yield _error_sse_line(
+                        response.status_code, error_text, self.provider_type
+                    )
+                    return
+
+                if web_search_active:
+                    yield _emit_tool_event(
+                        {
+                            "type": "tool_start",
+                            "tool_name": "web_search",
+                            "tool_call_id": web_search_tool_id,
+                            "arguments": {},
+                        }
+                    )
+                    web_search_tool_started = True
+
+                # NOTE: same manual __anext__ loop pattern as the other
+                # streaming helpers (see stream_chat_completion for the
+                # Python 3.13 + httpcore 1.0.x GeneratorExit ordering).
+                lines_gen = response.aiter_lines().__aiter__()
+                final_finish_reason: Optional[str] = None
+                try:
+                    while True:
+                        try:
+                            line = await lines_gen.__anext__()
+                        except StopAsyncIteration:
+                            break
+                        if not line.strip():
+                            continue
+                        if not line.startswith("data:"):
+                            continue
+                        data_str = line[len("data:") :].strip()
+                        if not data_str or data_str == "[DONE]":
+                            continue
+                        try:
+                            event = _json.loads(data_str)
+                        except Exception:
+                            logger.warning(
+                                "Gemini: failed to parse SSE chunk: %s",
+                                data_str[:200],
+                            )
+                            continue
+                        if not isinstance(event, dict):
+                            continue
+
+                        # Latch usageMetadata across deltas -- the final
+                        # fragment carries the complete totals.
+                        usage_meta = event.get("usageMetadata")
+                        if isinstance(usage_meta, dict):
+                            last_usage = usage_meta
+
+                        # Prompt-level safety block: Gemini ships zero
+                        # candidates plus a `promptFeedback.blockReason`
+                        # (e.g. SAFETY). The downstream OAI client would
+                        # otherwise see an empty successful assistant
+                        # response. Surface as a content_filter error
+                        # event so the UI can render the block reason.
+                        prompt_feedback = event.get("promptFeedback")
+                        if isinstance(prompt_feedback, dict) and prompt_feedback.get(
+                            "blockReason"
+                        ):
+                            block_reason = str(prompt_feedback.get("blockReason"))
+                            # Close out the synthetic web_search start so
+                            # the UI does not show a spinner stuck on
+                            # "searching..." after the error toast lands.
+                            if (
+                                web_search_active
+                                and web_search_tool_started
+                                and not web_search_tool_ended
+                            ):
+                                yield _emit_tool_event(
+                                    {
+                                        "type": "tool_end",
+                                        "tool_call_id": web_search_tool_id,
+                                        "result": (
+                                            "(search aborted: Gemini blocked "
+                                            f"prompt: {block_reason})"
+                                        ),
+                                    }
+                                )
+                                web_search_tool_ended = True
+                            yield _error_sse_line(
+                                400,
+                                f"Gemini blocked prompt: {block_reason}",
+                                self.provider_type,
+                            )
+                            return
+
+                        candidates = event.get("candidates") or []
+                        if not isinstance(candidates, list):
+                            continue
+                        for cand in candidates:
+                            if not isinstance(cand, dict):
+                                continue
+                            # Citations / grounding metadata.
+                            # `groundingMetadata.groundingChunks[].web`
+                            # carries `uri` + `title`. Collect for the
+                            # tool_end emission at stream close.
+                            gm = cand.get("groundingMetadata")
+                            if isinstance(gm, dict) and web_search_active:
+                                chunks_list = gm.get("groundingChunks") or []
+                                if isinstance(chunks_list, list):
+                                    for ch in chunks_list:
+                                        if not isinstance(ch, dict):
+                                            continue
+                                        web = ch.get("web") or {}
+                                        if not isinstance(web, dict):
+                                            continue
+                                        u = web.get("uri") or ""
+                                        if not u or not isinstance(u, str):
+                                            continue
+                                        if any(
+                                            c["url"] == u for c in web_search_citations
+                                        ):
+                                            continue
+                                        web_search_citations.append(
+                                            {
+                                                "url": u,
+                                                "title": (web.get("title") or u),
+                                                "snippet": "",
+                                            }
+                                        )
+
+                            content_obj = cand.get("content") or {}
+                            parts = (
+                                content_obj.get("parts")
+                                if isinstance(content_obj, dict)
+                                else None
+                            )
+                            if isinstance(parts, list):
+                                for part in parts:
+                                    if not isinstance(part, dict):
+                                        continue
+                                    # Text delta. Stow part-level
+                                    # `thoughtSignature` on the delta so
+                                    # Gemini 3 turns that need an exact
+                                    # signature echo round-trip cleanly.
+                                    text = part.get("text")
+                                    _part_extra = _gemini_part_extra(part)
+                                    if isinstance(text, str) and text:
+                                        yield _text_chunk(
+                                            text,
+                                            extra_content = _part_extra,
+                                        )
+                                    elif _part_extra is not None and not any(
+                                        k in part
+                                        for k in (
+                                            "functionCall",
+                                            "executableCode",
+                                            "codeExecutionResult",
+                                            "inlineData",
+                                        )
+                                    ):
+                                        # Empty-content part carrying a
+                                        # thoughtSignature: emit an empty delta
+                                        # so the signature is preserved.
+                                        yield _text_chunk(
+                                            "",
+                                            extra_content = _part_extra,
+                                        )
+                                    # functionCall -> OpenAI tool_calls
+                                    # delta envelope.
+                                    fc = part.get("functionCall")
+                                    if isinstance(fc, dict):
+                                        fc_name = fc.get("name") or ""
+                                        fc_args = fc.get("args") or {}
+                                        fc_id = (
+                                            fc.get("id")
+                                            or f"call_{fc_name}_{time.time_ns()}"
+                                        )
+                                        if fc_id in emitted_function_call_ids:
+                                            continue
+                                        emitted_function_call_ids.add(fc_id)
+                                        # Each distinct functionCall in an
+                                        # assistant turn needs its own
+                                        # tool_calls[*].index. Consumers
+                                        # that reassemble tool_calls by
+                                        # index collapse all calls onto
+                                        # the same slot when this is
+                                        # hardcoded to 0, breaking
+                                        # parallel/multi-tool turns.
+                                        tc_index = len(emitted_function_call_ids) - 1
+                                        tool_call_delta: dict[str, Any] = {
+                                            "index": tc_index,
+                                            "id": fc_id,
+                                            "type": "function",
+                                            "function": {
+                                                "name": fc_name,
+                                                "arguments": _json.dumps(fc_args),
+                                            },
+                                        }
+                                        # Gemini 3 function-calling: the
+                                        # part-level `thoughtSignature`
+                                        # must be echoed back on the
+                                        # next turn or the model rejects
+                                        # the tool-result envelope. Stow
+                                        # it on `extra_content.google`
+                                        # so the frontend can persist it
+                                        # and our outbound translator
+                                        # (below) can replay it.
+                                        thought_sig = part.get(
+                                            "thoughtSignature"
+                                        ) or part.get("thought_signature")
+                                        if isinstance(thought_sig, str) and thought_sig:
+                                            tool_call_delta["extra_content"] = {
+                                                "google": {
+                                                    "thought_signature": thought_sig,
+                                                }
+                                            }
+                                        emitted_any_function_call = True
+                                        tool_chunk = {
+                                            "id": completion_id,
+                                            "object": "chat.completion.chunk",
+                                            "choices": [
+                                                {
+                                                    "index": 0,
+                                                    "delta": {
+                                                        "tool_calls": [tool_call_delta]
+                                                    },
+                                                    "finish_reason": None,
+                                                }
+                                            ],
+                                        }
+                                        yield f"data: {_json.dumps(tool_chunk)}"
+                                    # executableCode + codeExecutionResult
+                                    # parts surface as the standard
+                                    # code_execution tool_start/tool_end
+                                    # envelope (same shape OpenAI and
+                                    # Anthropic emit) so the chat
+                                    # adapter can render Gemini sandbox
+                                    # output through CodeExecutionToolUI.
+                                    # https://ai.google.dev/gemini-api/docs/code-execution
+                                    exec_code = part.get("executableCode")
+                                    if isinstance(exec_code, dict):
+                                        code_str = exec_code.get("code") or ""
+                                        if code_str:
+                                            code_tool_id = (
+                                                exec_code.get("id")
+                                                or f"gemini_code_exec_{time.time_ns()}"
+                                            )
+                                            gemini_code_exec_pending_id = code_tool_id
+                                            # Stow the raw Gemini part so
+                                            # follow-up turns can replay
+                                            # the native `executableCode`
+                                            # (Gemini rejects a generic
+                                            # functionCall echo for code
+                                            # execution history).
+                                            _exec_thought_sig = part.get(
+                                                "thoughtSignature"
+                                            ) or part.get("thought_signature")
+                                            # Per-part thoughtSignature stays
+                                            # bound to its own part (Gemini 3
+                                            # rejects shared signatures).
+                                            _exec_part_entry: dict[str, Any] = {
+                                                "executableCode": exec_code,
+                                            }
+                                            if (
+                                                isinstance(_exec_thought_sig, str)
+                                                and _exec_thought_sig
+                                            ):
+                                                _exec_part_entry["thoughtSignature"] = (
+                                                    _exec_thought_sig
+                                                )
+                                            _exec_native: dict[str, Any] = {
+                                                "parts": [_exec_part_entry],
+                                            }
+                                            yield _emit_tool_event(
+                                                {
+                                                    "type": "tool_start",
+                                                    "tool_name": "code_execution",
+                                                    "tool_call_id": code_tool_id,
+                                                    "arguments": {
+                                                        "kind": "code_execution",
+                                                        "language": (
+                                                            (
+                                                                exec_code.get(
+                                                                    "language"
+                                                                )
+                                                                or "PYTHON"
+                                                            ).lower()
+                                                        ),
+                                                        "code": code_str,
+                                                        "google": {
+                                                            "native_part": _exec_native,
+                                                        },
+                                                    },
+                                                }
+                                            )
+                                    exec_result = part.get("codeExecutionResult")
+                                    if isinstance(exec_result, dict):
+                                        outcome = exec_result.get("outcome") or ""
+                                        output = exec_result.get("output") or ""
+                                        # Gemini returns
+                                        # OUTCOME_OK / OUTCOME_FAILED /
+                                        # OUTCOME_DEADLINE_EXCEEDED. Treat
+                                        # non-OK outcomes as stderr so the
+                                        # UI surfaces the error.
+                                        if outcome and outcome != "OUTCOME_OK":
+                                            result_text = (
+                                                f"[{outcome}]\n{output}".rstrip()
+                                            )
+                                        else:
+                                            result_text = output
+                                        # Pair tool_end with the most recent
+                                        # executableCode tool_start; fall back
+                                        # to exec_result.id then a fresh id.
+                                        pair_id = (
+                                            gemini_code_exec_pending_id
+                                            or exec_result.get("id")
+                                            or f"gemini_code_exec_{time.time_ns()}"
+                                        )
+                                        if gemini_code_exec_pending_id is None:
+                                            yield _emit_tool_event(
+                                                {
+                                                    "type": "tool_start",
+                                                    "tool_name": "code_execution",
+                                                    "tool_call_id": pair_id,
+                                                    "arguments": {
+                                                        "kind": "code_execution",
+                                                        "code": "",
+                                                    },
+                                                }
+                                            )
+                                        _result_thought_sig = part.get(
+                                            "thoughtSignature"
+                                        ) or part.get("thought_signature")
+                                        _result_part_entry: dict[str, Any] = {
+                                            "codeExecutionResult": exec_result,
+                                        }
+                                        if (
+                                            isinstance(_result_thought_sig, str)
+                                            and _result_thought_sig
+                                        ):
+                                            _result_part_entry["thoughtSignature"] = (
+                                                _result_thought_sig
+                                            )
+                                        _result_native: dict[str, Any] = {
+                                            "parts": [_result_part_entry],
+                                        }
+                                        yield _emit_tool_event(
+                                            {
+                                                "type": "tool_end",
+                                                "tool_call_id": pair_id,
+                                                "result": result_text,
+                                                "google": {
+                                                    "native_part": _result_native,
+                                                },
+                                            }
+                                        )
+                                        last_code_exec_tool_id = pair_id
+                                        last_code_exec_result_text = result_text
+                                        gemini_code_exec_pending_id = None
+                                    # inlineData: either a Nano Banana
+                                    # generation (own card) or a sandbox
+                                    # plot attached to the code_execution
+                                    # card via the __IMAGES__: marker.
+                                    inline = part.get("inlineData")
+                                    if isinstance(inline, dict):
+                                        b64 = inline.get("data") or ""
+                                        mime = inline.get("mimeType") or "image/png"
+                                        if b64:
+                                            image_uri = f"data:{mime};base64,{b64}"
+                                            attached_to_code_exec = (
+                                                not is_image_model
+                                                and last_code_exec_tool_id is not None
+                                                and bool(enabled_tools)
+                                                and "code_execution"
+                                                in (enabled_tools or [])
+                                            )
+                                            if attached_to_code_exec:
+                                                updated_result = (
+                                                    last_code_exec_result_text
+                                                    + "\n__IMAGES__:"
+                                                    + _json.dumps([image_uri])
+                                                )
+                                                # Stow inlineData so a follow-up
+                                                # turn can replay the plot with
+                                                # its per-part thoughtSignature.
+                                                _plot_thought_sig = part.get(
+                                                    "thoughtSignature"
+                                                ) or part.get("thought_signature")
+                                                _plot_part_entry: dict[str, Any] = {
+                                                    "inlineData": {
+                                                        "mimeType": mime,
+                                                        "data": b64,
+                                                    },
+                                                }
+                                                if (
+                                                    isinstance(_plot_thought_sig, str)
+                                                    and _plot_thought_sig
+                                                ):
+                                                    _plot_part_entry[
+                                                        "thoughtSignature"
+                                                    ] = _plot_thought_sig
+                                                yield _emit_tool_event(
+                                                    {
+                                                        "type": "tool_end",
+                                                        "tool_call_id": (
+                                                            last_code_exec_tool_id
+                                                        ),
+                                                        "result": updated_result,
+                                                        "google": {
+                                                            "native_part": {
+                                                                "parts": [
+                                                                    _plot_part_entry
+                                                                ],
+                                                            },
+                                                        },
+                                                    }
+                                                )
+                                                last_code_exec_result_text = (
+                                                    updated_result
+                                                )
+                                            else:
+                                                img_id = f"img_{time.time_ns()}"
+                                                yield _emit_tool_event(
+                                                    {
+                                                        "type": "tool_start",
+                                                        "tool_name": "image_generation",
+                                                        "tool_call_id": img_id,
+                                                        "arguments": {
+                                                            "kind": "image",
+                                                            "prompt": "",
+                                                        },
+                                                    }
+                                                )
+                                                # Gemini 3 image edit needs
+                                                # the prior thoughtSignature
+                                                # echoed on the inline image part.
+                                                _img_thought_sig = part.get(
+                                                    "thoughtSignature"
+                                                ) or part.get("thought_signature")
+                                                _img_tool_end: dict[str, Any] = {
+                                                    "type": "tool_end",
+                                                    "tool_call_id": img_id,
+                                                    "result": "",
+                                                    "image_b64": b64,
+                                                    "image_mime": mime,
+                                                }
+                                                # Stow inlineData so multi-turn
+                                                # edits replay the original
+                                                # image as native history.
+                                                _img_part_entry: dict[str, Any] = {
+                                                    "inlineData": {
+                                                        "mimeType": mime,
+                                                        "data": b64,
+                                                    },
+                                                }
+                                                if (
+                                                    isinstance(_img_thought_sig, str)
+                                                    and _img_thought_sig
+                                                ):
+                                                    _img_part_entry[
+                                                        "thoughtSignature"
+                                                    ] = _img_thought_sig
+                                                _img_native: dict[str, Any] = {
+                                                    "parts": [_img_part_entry],
+                                                }
+                                                _img_google: dict[str, Any] = {
+                                                    "native_part": _img_native,
+                                                }
+                                                if (
+                                                    isinstance(_img_thought_sig, str)
+                                                    and _img_thought_sig
+                                                ):
+                                                    _img_google["thought_signature"] = (
+                                                        _img_thought_sig
+                                                    )
+                                                _img_tool_end["google"] = _img_google
+                                                yield _emit_tool_event(_img_tool_end)
+                            finish_reason = cand.get("finishReason")
+                            if isinstance(finish_reason, str):
+                                mapped = _finish_reason_map.get(finish_reason, "stop")
+                                if mapped is not None:
+                                    final_finish_reason = mapped
+
+                    # End-of-stream emission order: web_search tool_end
+                    # (with citations) -> finish_reason chunk -> usage
+                    # chunk -> [DONE]. Matches the Anthropic / OpenAI
+                    # helpers' contract so the frontend handler does
+                    # not need provider-specific ordering knowledge.
+                    if (
+                        web_search_active
+                        and web_search_tool_started
+                        and not web_search_tool_ended
+                    ):
+                        blocks: list[str] = []
+                        for cit in web_search_citations:
+                            line_out = f"Title: {cit['title']}\nURL: {cit['url']}"
+                            if cit.get("snippet"):
+                                line_out += f"\nSnippet: {cit['snippet']}"
+                            blocks.append(line_out)
+                        yield _emit_tool_event(
+                            {
+                                "type": "tool_end",
+                                "tool_call_id": web_search_tool_id,
+                                "result": (
+                                    "\n---\n".join(blocks)
+                                    if blocks
+                                    else "(search complete)"
+                                ),
+                            }
+                        )
+                        web_search_tool_ended = True
+
+                    if final_finish_reason:
+                        # OpenAI clients trigger tool execution when
+                        # finish_reason="tool_calls". Gemini emits
+                        # "STOP" even when the turn was a pure
+                        # functionCall request, so override after the
+                        # fact to match the OAI contract.
+                        if emitted_any_function_call and final_finish_reason == "stop":
+                            final_finish_reason = "tool_calls"
+                        finish_chunk = {
+                            "id": completion_id,
+                            "object": "chat.completion.chunk",
+                            "choices": [
+                                {
+                                    "index": 0,
+                                    "delta": {},
+                                    "finish_reason": final_finish_reason,
+                                }
+                            ],
+                        }
+                        yield f"data: {_json.dumps(finish_chunk)}"
+
+                    # Map Gemini usageMetadata onto OpenAI include_usage.
+                    # thoughtsTokenCount is billed output too — fold it in
+                    # so cost calculators don't undercount.
+                    if isinstance(last_usage, dict):
+                        thought_tokens = last_usage.get("thoughtsTokenCount") or 0
+                        candidate_tokens = last_usage.get("candidatesTokenCount") or 0
+                        prompt_tokens = last_usage.get("promptTokenCount") or 0
+                        # Gemini bills tool-call prompt slices separately
+                        # via `toolUsePromptTokenCount`. Fold into input
+                        # so total_tokens does not undercount tool turns.
+                        tool_use_prompt_tokens = (
+                            last_usage.get("toolUsePromptTokenCount") or 0
+                        )
+                        translated_usage = {
+                            "input_tokens": prompt_tokens + tool_use_prompt_tokens,
+                            "output_tokens": candidate_tokens + thought_tokens,
+                            "input_tokens_details": {
+                                "cached_tokens": (
+                                    last_usage.get("cachedContentTokenCount") or 0
+                                ),
+                                "tool_use_prompt_tokens": tool_use_prompt_tokens,
+                            },
+                            "output_tokens_details": {
+                                "reasoning_tokens": thought_tokens,
+                            },
+                        }
+                        usage_line = _build_usage_chunk(
+                            completion_id, "openai", translated_usage
+                        )
+                        if usage_line:
+                            yield usage_line
+
+                    yield "data: [DONE]"
+                finally:
+                    # Close response first so lines_gen.aclose() becomes
+                    # a no-op (avoids the httpcore 1.0 GeneratorExit
+                    # path and the aclose-never-awaited RuntimeWarning).
+                    await response.aclose()
+                    await lines_gen.aclose()
+
+        except httpx.ConnectError as exc:
+            logger.error("Connection error to %s: %s", self.provider_type, exc)
+            if web_search_tool_started and not web_search_tool_ended:
+                yield _emit_tool_event(
+                    {
+                        "type": "tool_end",
+                        "tool_call_id": web_search_tool_id,
+                        "result": f"(search aborted: connection error: {exc})",
+                    }
+                )
+                web_search_tool_ended = True
+            yield _error_sse_line(
+                502,
+                f"Failed to connect to {self.provider_type}: {exc}",
+                self.provider_type,
+            )
+        except httpx.ReadTimeout as exc:
+            logger.error("Read timeout from %s: %s", self.provider_type, exc)
+            if web_search_tool_started and not web_search_tool_ended:
+                yield _emit_tool_event(
+                    {
+                        "type": "tool_end",
+                        "tool_call_id": web_search_tool_id,
+                        "result": "(search aborted: read timeout)",
+                    }
+                )
+                web_search_tool_ended = True
+            yield _error_sse_line(
+                504,
+                f"Timeout waiting for {self.provider_type} response",
+                self.provider_type,
+            )
+        except httpx.HTTPError as exc:
+            logger.error("HTTP error from %s: %s", self.provider_type, exc)
+            if web_search_tool_started and not web_search_tool_ended:
+                yield _emit_tool_event(
+                    {
+                        "type": "tool_end",
+                        "tool_call_id": web_search_tool_id,
+                        "result": f"(search aborted: transport error: {exc})",
+                    }
+                )
+                web_search_tool_ended = True
+            yield _error_sse_line(
+                502,
+                f"Error communicating with {self.provider_type}: {exc}",
+                self.provider_type,
+            )
+
     async def _stream_openai_responses(
         self,
         messages: list[dict[str, Any]],
@@ -2893,6 +4949,8 @@ class ExternalProviderClient:
         enable_prompt_caching: Optional[bool] = None,
         openai_code_exec_container_id: Optional[str] = None,
         compaction_threshold: Optional[int] = None,
+        tools: Optional[list[dict[str, Any]]] = None,
+        tool_choice: Optional[Any] = None,
     ) -> AsyncGenerator[str, None]:
         """
         Call OpenAI's /v1/responses endpoint and translate its SSE stream back
@@ -2916,6 +4974,12 @@ class ExternalProviderClient:
         # translate user/assistant messages into the Responses input shape.
         instructions_parts: list[str] = []
         input_items: list[dict[str, Any]] = []
+        # When we drop a server-side builtin `function_call` here, the
+        # matching `role="tool"` follow-up must also be dropped --
+        # otherwise the outbound body contains an orphan
+        # `function_call_output` with no matching `function_call`, which
+        # OpenAI Responses can reject or mis-associate.
+        skipped_server_builtin_call_ids: set[str] = set()
         openai_replay_items: list[dict[str, Any]] = []
         previous_response_id: Optional[str] = None
         for msg in messages:
@@ -2932,6 +4996,126 @@ class ExternalProviderClient:
                             instructions_parts.append(part["text"])
                 continue
 
+            # OpenAI Responses uses item-shape history for function
+            # calling: assistant turns that invoked user tools must
+            # serialize each call as a `function_call` input item, and
+            # each role="tool" follow-up as a `function_call_output`
+            # item keyed by the matching `call_id`. Without this the
+            # second turn after a function call sends Chat Completions
+            # shape and Responses 400s the request.
+            if role == "tool":
+                _call_id = msg.get("tool_call_id") or ""
+                # If the matching assistant `function_call` was a
+                # server-side builtin we already dropped, drop the
+                # follow-up too to avoid emitting an orphan
+                # `function_call_output`.
+                if _call_id and _call_id in skipped_server_builtin_call_ids:
+                    continue
+                if isinstance(content, list):
+                    _flat_parts: list[str] = []
+                    for part in content:
+                        if part.get("type") == "text" and part.get("text"):
+                            _flat_parts.append(part["text"])
+                    _output_text = "".join(_flat_parts)
+                else:
+                    _output_text = content if isinstance(content, str) else ""
+                if _call_id:
+                    input_items.append(
+                        {
+                            "type": "function_call_output",
+                            "call_id": _call_id,
+                            "output": _output_text,
+                        }
+                    )
+                continue
+
+            # Assistant turns that returned tool_calls translate each
+            # call as a `function_call` item (carrying name + JSON
+            # arguments + call_id). Skip builtin server-side cards
+            # (canonical builtin name + `args._server_tool` marker)
+            # which never round-trip as user functions. We require both
+            # checks so a user function literally named `_server_tool`
+            # in its argument schema is not dropped.
+            _tool_calls = msg.get("tool_calls") if isinstance(msg, dict) else None
+            if role == "assistant" and isinstance(_tool_calls, list):
+                # Preserve the prior `response.output` ordering: the
+                # model's text precedes its function_call items, and
+                # the matching role=tool follow-up arrives AFTER the
+                # call. Without this guard, history replay puts
+                # function_call -> assistant text -> function_call_output,
+                # which can put the tool output after an unrelated
+                # assistant message and confuse multi-turn function
+                # calling.
+                if isinstance(content, str) and content:
+                    input_items.append({"role": "assistant", "content": content})
+                elif isinstance(content, list):
+                    _asst_parts: list[dict[str, Any]] = []
+                    for _part in content:
+                        if not isinstance(_part, dict):
+                            continue
+                        _pt = _part.get("type")
+                        if _pt == "text" and _part.get("text"):
+                            _asst_parts.append(
+                                {
+                                    "type": "input_text",
+                                    "text": _part.get("text", ""),
+                                }
+                            )
+                        elif _pt == "image_url":
+                            _u = _part.get("image_url", {}).get("url", "")
+                            if _u:
+                                _asst_parts.append(
+                                    {"type": "input_image", "image_url": _u}
+                                )
+                    if _asst_parts:
+                        input_items.append(
+                            {"role": "assistant", "content": _asst_parts}
+                        )
+
+                for _tc in _tool_calls:
+                    if not isinstance(_tc, dict):
+                        continue
+                    _fn = _tc.get("function") or {}
+                    if not isinstance(_fn, dict) or not _fn.get("name"):
+                        continue
+                    _args_raw = _fn.get("arguments") or ""
+                    if not isinstance(_args_raw, str):
+                        try:
+                            _args_raw = _json.dumps(_args_raw)
+                        except Exception:
+                            _args_raw = ""
+                    _fn_name_lc = (_fn.get("name") or "").lower()
+                    _is_server_builtin = False
+                    if _fn_name_lc in _SERVER_SIDE_BUILTIN_TOOL_NAMES:
+                        try:
+                            _args_obj = _json.loads(_args_raw) if _args_raw else {}
+                        except Exception:
+                            _args_obj = None
+                        if isinstance(_args_obj, dict):
+                            if _args_obj.get("_server_tool") is True:
+                                _is_server_builtin = True
+                            else:
+                                _g = _args_obj.get("google")
+                                if isinstance(_g, dict) and isinstance(
+                                    _g.get("native_part"), dict
+                                ):
+                                    _is_server_builtin = True
+                    _call_id_out = _tc.get("id") or f"call_{time.time_ns()}"
+                    if _is_server_builtin:
+                        skipped_server_builtin_call_ids.add(_call_id_out)
+                        continue
+                    input_items.append(
+                        {
+                            "type": "function_call",
+                            "call_id": _call_id_out,
+                            "name": _fn["name"],
+                            "arguments": _args_raw,
+                        }
+                    )
+                # Assistant text already emitted above (in order) so we
+                # don't fall through to the generic content branches.
+                continue
+
             if isinstance(content, str):
                 input_items.append({"role": role, "content": content})
                 continue
@@ -3121,44 +5305,15 @@ class ExternalProviderClient:
         if max_tokens is not None:
             body["max_output_tokens"] = max_tokens
 
-        # Prompt caching on /v1/responses is automatic and free, but the
-        # default in-memory policy only survives ~5-10 min of inactivity
-        # (up to ~1 hr). Opt into the 24-hour retention policy so a chat
-        # left idle overnight still hits the cache on the next turn.
-        # Pricing is identical to in_memory per OpenAI's docs.
-        #
-        # Gated on the base URL because ollama / llama.cpp / "custom"
-        # presets all collapse to provider_type="openai" in
-        # toExternalBackendProviderType, so they also land in this
-        # helper. Those servers expose /v1/responses-shaped routes in
-        # some configurations but don't implement
-        # prompt_cache_retention — sending the field unconditionally
-        # would 400 them. Match the public OpenAI host strictly so the
-        # field only goes to OpenAI cloud. Studio's openai model picker
-        # is registry-scoped to gpt-5.x / o3 / gpt-4.5, all of which
-        # accept this parameter (gpt-5.5+ already defaults to "24h" and
-        # rejects "in_memory", so it's a safe no-op there).
-        # OpenAI-family cloud: api.openai.com OR Azure OpenAI Foundry
-        # (*.openai.azure.com). Both expose the same Responses-API
-        # extensions used below -- prompt_cache_retention,
-        # context_management compaction, container shell tool -- so
-        # treat them uniformly. Non-cloud OpenAI-compatible servers
-        # (ollama / llama.cpp / vLLM / "custom" preset) hit /v1/responses
-        # without these extensions and would 400 on the unknown body
-        # fields, so they intentionally fall outside this gate.
+        # Opt into 24h prompt-cache retention (free, vs the default
+        # ~5-10 min). Gated on the OpenAI cloud host because ollama /
+        # llama.cpp / "custom" presets reach this code path too and
+        # would 400 on the unknown field.
         if is_openai_cloud and enable_prompt_caching is not False:
             body["prompt_cache_retention"] = "24h"
 
-        # OpenAI server-side context compaction — see
-        #   https://developers.openai.com/api/docs/guides/compaction
-        # When `compaction_threshold` is provided on a cloud OpenAI
-        # request, attach `context_management: [{type:"compaction",
-        # compact_threshold:N}]` so the API runs server-side
-        # compaction when the rendered prompt crosses the threshold.
-        # No beta header is required; no dated version pin. The field
-        # is silently dropped for non-cloud backends because ollama /
-        # llama.cpp / "custom" presets land in this helper and would
-        # 400 on an unknown body field.
+        # Server-side context compaction (OpenAI cloud only).
+        # https://developers.openai.com/api/docs/guides/compaction
         if (
             is_openai_cloud
             and compaction_threshold is not None
@@ -3171,55 +5326,92 @@ class ExternalProviderClient:
                 }
             ]
 
-        # OpenAI server-side tools — see
-        #   https://developers.openai.com/api/docs/guides/tools
-        #   https://developers.openai.com/api/docs/guides/tools-shell
-        # The frontend's Search/Code buttons map to the unified
-        # enabled_tools shorthand; translate that into the Responses-API
-        # tool schema. Other built-in tools (file_search,
-        # code_interpreter, image_generation, computer_use_preview) can
-        # be added with the same pattern when we surface their toggles.
+        # Map enabled_tools onto Responses-API server tools (cloud only;
+        # local OAI-compat backends 400 on these).
+        # https://developers.openai.com/api/docs/guides/tools
         code_execution_enabled_openai = bool(
             enabled_tools and "code_execution" in enabled_tools and is_openai_cloud
         )
-        # OpenAI's image_generation tool is a Responses-API server tool.
-        # See https://developers.openai.com/api/docs/guides/tools-image-generation
-        # The model picks size / quality / background server-side and
-        # delegates rendering to a gpt-image-* family model; the result
-        # comes back inline as an `image_generation_call` output item
-        # with a base64 image. Available on every gpt-5.x family member
-        # plus gpt-4.1 / gpt-4o / o3 per the docs; restrict to cloud
-        # OpenAI because the local llama.cpp / ollama backends don't
-        # implement it and would 400.
-        image_generation_enabled_openai = image_generation_requested
+        image_generation_enabled_openai = bool(
+            enabled_tools and "image_generation" in enabled_tools and is_openai_cloud
+        )
 
         def _openai_image_generation_tool() -> dict[str, Any]:
             tool: dict[str, Any] = {"type": "image_generation"}
             if image_generation_has_reference:
-                # OpenAI's Responses image tool defaults to `auto`. For
-                # Studio's explicit follow-up edit flow, force edit mode so
-                # the provider uses the previous response / call id as image
-                # context instead of treating the text as a fresh generation.
+                # Force edit mode so the prior call id is used as context.
                 tool["action"] = "edit"
             return tool
 
-        if enabled_tools:
-            tools_array: list[dict[str, Any]] = []
-            if "web_search" in enabled_tools:
+        # Translate Chat-Completions function tools into the Responses
+        # function-tool shape (flattened name/description/parameters).
+        responses_user_function_tools: list[dict[str, Any]] = []
+        if tools:
+            for _tool in tools:
+                if not isinstance(_tool, dict) or _tool.get("type") != "function":
+                    continue
+                _fn = _tool.get("function")
+                if not isinstance(_fn, dict) or not _fn.get("name"):
+                    continue
+                _entry: dict[str, Any] = {
+                    "type": "function",
+                    "name": _fn["name"],
+                }
+                if _fn.get("description"):
+                    _entry["description"] = _fn["description"]
+                if isinstance(_fn.get("parameters"), dict):
+                    _entry["parameters"] = _fn["parameters"]
+                responses_user_function_tools.append(_entry)
+
+        # Translate tool_choice into the Responses shape.
+        _responses_tc_string: Optional[str] = None
+        if isinstance(tool_choice, str):
+            _tc_lc = tool_choice.strip().lower()
+            if _tc_lc in ("auto", "none", "required"):
+                _responses_tc_string = _tc_lc
+        responses_tool_choice: Optional[Any] = None
+        _has_responses_tools = bool(enabled_tools or responses_user_function_tools)
+        if _responses_tc_string is not None and _has_responses_tools:
+            responses_tool_choice = _responses_tc_string
+        elif (
+            tool_choice is not None
+            and responses_user_function_tools
+            and isinstance(tool_choice, dict)
+            and tool_choice.get("type") == "function"
+        ):
+            _fn_pick = tool_choice.get("function") or {}
+            _name = _fn_pick.get("name") if isinstance(_fn_pick, dict) else None
+            if isinstance(_name, str) and _name:
+                responses_tool_choice = {"type": "function", "name": _name}
+
+        _responses_tool_choice_none = _responses_tc_string == "none"
+        # A pinned user function suppresses hosted builtins (privacy +
+        # billing), matching the Gemini / Anthropic / OpenRouter gates.
+        _responses_tool_choice_forced_function = (
+            isinstance(tool_choice, dict)
+            and tool_choice.get("type") == "function"
+            and isinstance(tool_choice.get("function"), dict)
+            and bool(tool_choice["function"].get("name"))
+        )
+        _responses_hosted_builtins_allowed = (
+            not _responses_tool_choice_none
+            and not _responses_tool_choice_forced_function
+        )
+
+        if (
+            enabled_tools or responses_user_function_tools
+        ) and not _responses_tool_choice_none:
+            tools_array: list[dict[str, Any]] = list(responses_user_function_tools)
+            if (
+                _responses_hosted_builtins_allowed
+                and enabled_tools
+                and "web_search" in enabled_tools
+            ):
                 tools_array.append({"type": "web_search"})
-            if code_execution_enabled_openai:
-                # `container_auto` lets OpenAI auto-create a fresh
-                # container per request; we capture the resulting
-                # container_id off the SSE stream and the chat-adapter
-                # persists it onto the thread record. Subsequent turns
-                # in the same thread pass it back as
-                # `openai_code_exec_container_id`, which we translate to
-                # `container_reference` here so the model sees
-                # filesystem state from prior turns. Container expires
-                # after ~20 min of inactivity per OpenAI's default
-                # policy — a stale id 400s, the chat-adapter clears it
-                # via container_invalidated, and the next turn falls
-                # back to auto-create.
+            if _responses_hosted_builtins_allowed and code_execution_enabled_openai:
+                # Reuse the thread's container so filesystem state
+                # persists; auto-create when there isn't one yet. Stale
+                # ids 400 and are cleared via container_invalidated.
                 shell_env: dict[str, Any]
                 if openai_code_exec_container_id:
                     shell_env = {
@@ -3229,10 +5421,12 @@ class ExternalProviderClient:
                 else:
                     shell_env = {"type": "container_auto"}
                 tools_array.append({"type": "shell", "environment": shell_env})
-            if image_generation_enabled_openai:
+            if _responses_hosted_builtins_allowed and image_generation_enabled_openai:
                 tools_array.append(_openai_image_generation_tool())
             if tools_array:
                 body["tools"] = tools_array
+        if responses_tool_choice is not None:
+            body["tool_choice"] = responses_tool_choice
 
         url = f"{self.base_url}/responses"
         completion_id = f"chatcmpl-openai-{model.replace('/', '-')}"
@@ -3246,11 +5440,19 @@ class ExternalProviderClient:
             first attempt.
             """
             attempt_body = dict(body)
-            if enabled_tools:
-                tools_array_attempt: list[dict[str, Any]] = []
-                if "web_search" in enabled_tools:
+            if (
+                enabled_tools or responses_user_function_tools
+            ) and not _responses_tool_choice_none:
+                tools_array_attempt: list[dict[str, Any]] = list(
+                    responses_user_function_tools
+                )
+                if (
+                    _responses_hosted_builtins_allowed
+                    and enabled_tools
+                    and "web_search" in enabled_tools
+                ):
                     tools_array_attempt.append({"type": "web_search"})
-                if code_execution_enabled_openai:
+                if _responses_hosted_builtins_allowed and code_execution_enabled_openai:
                     if container_id_for_this_attempt:
                         env_attempt: dict[str, Any] = {
                             "type": "container_reference",
@@ -3261,12 +5463,17 @@ class ExternalProviderClient:
                     tools_array_attempt.append(
                         {"type": "shell", "environment": env_attempt}
                     )
-                if image_generation_enabled_openai:
+                if (
+                    _responses_hosted_builtins_allowed
+                    and image_generation_enabled_openai
+                ):
                     tools_array_attempt.append(_openai_image_generation_tool())
                 if tools_array_attempt:
                     attempt_body["tools"] = tools_array_attempt
                 else:
                     attempt_body.pop("tools", None)
+            if responses_tool_choice is not None:
+                attempt_body["tool_choice"] = responses_tool_choice
             return attempt_body
 
         def _is_openai_container_expired_error(error_text: str) -> bool:
@@ -3328,52 +5535,26 @@ class ExternalProviderClient:
                     done_emitted = False
                     reasoning_open = False
                     reasoning_emitted = False
-                    # Latched from response.completed / response.incomplete so
-                    # the final log can surface input_tokens_details.cached_tokens —
-                    # the field that proves prompt_cache_retention="24h" is
-                    # actually hitting OpenAI's cache instead of recomputing
-                    # the prefix every turn.
+                    # Per-call function-tool indexing; distinct slots so
+                    # parallel calls don't collide on delta.tool_calls[].index.
+                    saw_function_call = False
+                    function_call_index = 0
+                    # Latched from response.completed/incomplete; surfaces
+                    # input_tokens_details.cached_tokens to prove cache hits.
                     last_usage: Optional[dict[str, Any]] = None
-                    # Per-call state for OpenAI's server-side web_search tool. Mapped
-                    # back into our local _toolEvent shape so the existing chat-UI
-                    # renderer surfaces web_search the same way it does for local
-                    # tool calls: a "Searching…" tool-call card, then a `tool_end`
-                    # carrying citations formatted as
-                    #   Title: …\nURL: …\nSnippet: …\n---\n…
-                    # blocks (which the frontend's parseSourcesFromResult lifts
-                    # into source content parts at end of stream).
-                    # web_search_calls preserves insertion order so we can apply
-                    # the aggregated citation list onto the *last* call's
-                    # tool_end — that's the one the frontend's source-pill
-                    # extraction reads (parseSourcesFromResult flatMaps every
-                    # web_search result, so a single non-empty result is enough
-                    # to surface all sources at message tail).
-                    # OpenAI emits url_citation annotations on text deltas, not
-                    # per call — there's no wire field linking a citation back
-                    # to a specific search invocation. Hence the shared list.
-                    # web_search_calls: { item_id -> {query} }
+                    # web_search state. Citations are emitted on text deltas
+                    # (not per call), so the aggregate list is shared and
+                    # applied to the LAST web_search tool_end (parseSourcesFromResult
+                    # flatmaps every call, one non-empty is enough).
                     web_search_calls: dict[str, dict[str, Any]] = {}
                     all_url_citations: list[dict[str, Any]] = []
-                    # Shell-tool (code execution) state. OpenAI emits
-                    # `shell_call` items (model requesting a command list)
-                    # paired with `shell_call_output` items (execution
-                    # results). We mirror the Anthropic code-execution UX
-                    # by emitting one `_toolEvent` tool_start per
-                    # shell_call and one tool_end per shell_call_output;
-                    # they're linked via `shell_call_output.call_id`
-                    # matching `shell_call.id`. Items are independent of
-                    # web_search (different keyed map).
-                    # shell_calls: { call_id -> {commands, output} }
+                    # shell_calls (code execution): { call_id -> {commands, output} }.
+                    # shell_call <-> shell_call_output match by call_id; emit
+                    # tool_start/tool_end like the Anthropic UX.
                     shell_calls: dict[str, dict[str, Any]] = {}
-                    # Container id captured from the response stream. When
-                    # it differs from the inbound id, emit a synthetic
-                    # `container_ready` _toolEvent so the frontend can
-                    # persist it onto the thread record for the next turn.
-                    # Where OpenAI surfaces it is documented loosely; we
-                    # probe two known fields (response.container_id on
-                    # response.completed, item.environment.container_id on
-                    # shell_call output items) and latch the first one we
-                    # see.
+                    # Container id latched from response.container_id or
+                    # item.environment.container_id; emit container_ready
+                    # when it differs from the inbound id.
                     latched_container_id: Optional[str] = None
                     container_id_emitted = False
                     current_openai_response_id: Optional[str] = None
@@ -3453,6 +5634,7 @@ class ExternalProviderClient:
                         return rendered
 
                     def _emit_tool_event(payload: dict[str, Any]) -> str:
+                        _stamp_server_tool_marker(payload)
                         chunk = {
                             "id": completion_id,
                             "object": "chat.completion.chunk",
@@ -3775,17 +5957,9 @@ class ExternalProviderClient:
                                         f"ws_{len(web_search_calls)}"
                                     )
                                     web_search_calls.setdefault(item_id, {"query": ""})
-                                # Shell-tool: register the call eagerly so
-                                # the matching shell_call_output can link
-                                # back even if `done` arrives out of order.
-                                # Also probe for container_id on the
-                                # environment field — when container_auto
-                                # auto-creates one, this is the first place
-                                # the new id might surface (OpenAI doesn't
-                                # promise this in docs, but the field is
-                                # cheap to scan and lets us emit
-                                # container_ready earlier than
-                                # response.completed).
+                                # Register shell_call eagerly so out-of-order
+                                # output links back. Probe env.container_id
+                                # to emit container_ready before response.completed.
                                 if (
                                     isinstance(item, dict)
                                     and item.get("type") == "shell_call"
@@ -3978,24 +6152,9 @@ class ExternalProviderClient:
                                         }
                                     )
                                 elif item.get("type") == "image_generation_call":
-                                    # OpenAI's image_generation tool returns
-                                    # a single output item with the base64
-                                    # PNG/WebP/JPEG on `result` (sometimes
-                                    # `b64_json` depending on output_format).
-                                    # `revised_prompt` is what the gpt-image
-                                    # backbone actually used after refinement
-                                    # of the assistant's request. Emit
-                                    # tool_start + tool_end so the chat card
-                                    # renders the prompt + the generated
-                                    # image inline. The frontend chat-adapter
-                                    # decides how to render the base64 blob
-                                    # (likely an <img src="data:image/...">)
-                                    # based on the `kind: "image"` hint we
-                                    # set on tool_start arguments.
-                                    # `time_ns()` (nanoseconds) instead of
-                                    # millisecond resolution so synthesised
-                                    # ids stay unique even when two image
-                                    # generations resolve in the same ms.
+                                    # Base64 image on `result` (or `b64_json`),
+                                    # `revised_prompt` for the rewritten prompt.
+                                    # ns-resolution id so concurrent gens stay unique.
                                     raw_item_id = item.get("id")
                                     item_id = raw_item_id or f"img_{time.time_ns()}"
                                     prompt_in = (
@@ -4034,6 +6193,54 @@ class ExternalProviderClient:
                                             "prompt": prompt_in,
                                         }
                                     )
+                                elif item.get("type") == "function_call":
+                                    # Translate to Chat-Completions delta.tool_calls.
+                                    # https://platform.openai.com/docs/guides/function-calling?api-mode=responses
+                                    fn_call_id = (
+                                        item.get("call_id")
+                                        or item.get("id")
+                                        or f"call_{time.time_ns()}"
+                                    )
+                                    fn_name = item.get("name") or ""
+                                    fn_args = item.get("arguments") or ""
+                                    if not isinstance(fn_args, str):
+                                        try:
+                                            fn_args = _json.dumps(fn_args)
+                                        except Exception:
+                                            fn_args = ""
+                                    _tc_index = function_call_index
+                                    function_call_index += 1
+                                    yield (
+                                        "data: "
+                                        + _json.dumps(
+                                            {
+                                                "id": completion_id,
+                                                "object": "chat.completion.chunk",
+                                                "choices": [
+                                                    {
+                                                        "index": 0,
+                                                        "delta": {
+                                                            "tool_calls": [
+                                                                {
+                                                                    "index": _tc_index,
+                                                                    "id": fn_call_id,
+                                                                    "type": "function",
+                                                                    "function": {
+                                                                        "name": fn_name,
+                                                                        "arguments": (
+                                                                            fn_args
+                                                                        ),
+                                                                    },
+                                                                }
+                                                            ],
+                                                        },
+                                                        "finish_reason": None,
+                                                    }
+                                                ],
+                                            }
+                                        )
+                                    )
+                                    saw_function_call = True
 
                             elif (
                                 isinstance(event_type, str)
@@ -4167,7 +6374,11 @@ class ExternalProviderClient:
                                         {
                                             "index": 0,
                                             "delta": {},
-                                            "finish_reason": "stop",
+                                            "finish_reason": (
+                                                "tool_calls"
+                                                if saw_function_call
+                                                else "stop"
+                                            ),
                                         }
                                     ],
                                 }
@@ -4448,11 +6659,70 @@ class ExternalProviderClient:
                     models = [model for model in raw_models if isinstance(model, dict)]
             if not models and self.provider_type == "ollama":
                 models = await self._list_ollama_native_models()
+            # Gemini's native /v1beta/models returns
+            # {"models": [{"name": "models/gemini-2.5-flash", ...}]}
+            # -- repackage into the OpenAI-compatible shape the rest
+            # of Studio expects so dynamic model discovery works.
+            if not models and self.provider_type == "gemini":
+                models = self._parse_gemini_models(data)
             return models
         except httpx.HTTPError as exc:
             logger.error("Failed to list models from %s: %s", self.provider_type, exc)
             raise
 
+    @staticmethod
+    def _parse_gemini_models(payload: Any) -> list[dict[str, Any]]:
+        """Translate Gemini's native /v1beta/models payload to OpenAI shape.
+
+        Native response:
+          {"models": [{"name": "models/gemini-2.5-flash",
+                       "baseModelId": "gemini-2.5-flash",
+                       "displayName": "Gemini 2.5 Flash",
+                       "supportedGenerationMethods": [...]}]}
+
+        We only keep entries that advertise
+        ``generateContent`` / ``streamGenerateContent`` so the picker
+        does not surface embedding-only models the chat path can't
+        drive.
+        """
+        if not isinstance(payload, dict):
+            return []
+        entries = payload.get("models") or []
+        if not isinstance(entries, list):
+            return []
+        out: list[dict[str, Any]] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            methods = entry.get("supportedGenerationMethods") or []
+            if (
+                isinstance(methods, list)
+                and methods
+                and not any(
+                    m in methods for m in ("generateContent", "streamGenerateContent")
+                )
+            ):
+                continue
+            base_id = entry.get("baseModelId")
+            name = entry.get("name") or ""
+            # ``name`` arrives as ``"models/gemini-2.5-flash"``; the
+            # chat path uses the bare id.
+            short_id = (
+                base_id
+                if isinstance(base_id, str) and base_id
+                else (name.split("/", 1)[1] if "/" in name else name)
+            )
+            if not short_id:
+                continue
+            out.append(
+                {
+                    "id": short_id,
+                    "owned_by": "google",
+                    "display_name": entry.get("displayName") or short_id,
+                }
+            )
+        return out
+
     async def _list_ollama_native_models(self) -> list[dict[str, Any]]:
         """Fallback when Ollama's /v1/models returns an empty or null catalog."""
         root = self.base_url.removesuffix("/v1").rstrip("/")
@@ -4757,6 +7027,17 @@ def _build_usage_chunk(
             "total_tokens": prompt_tokens + completion_tokens,
             "prompt_tokens_details": {"cached_tokens": cached},
         }
+        # Surface OpenAI Responses / Gemini reasoning-token detail. The
+        # caller pre-populates last_usage["output_tokens_details"] with
+        # at least {"reasoning_tokens": ...}; mirror it into the OAI
+        # `completion_tokens_details` shape so SDKs can render the
+        # hidden-thoughts slice.
+        out_details = last_usage.get("output_tokens_details")
+        if isinstance(out_details, dict) and out_details:
+            usage_block["completion_tokens_details"] = {
+                "reasoning_tokens": out_details.get("reasoning_tokens") or 0,
+            }
+            usage_block["output_tokens_details"] = out_details
 
     chunk = {
         "id": completion_id,
diff --git a/studio/backend/core/inference/providers.py b/studio/backend/core/inference/providers.py
index fef9ba3e12..785f1dec3b 100644
--- a/studio/backend/core/inference/providers.py
+++ b/studio/backend/core/inference/providers.py
@@ -65,28 +65,77 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     },
     "gemini": {
         "display_name": "Google Gemini",
-        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
-        # Curated lineup — Google's /v1beta/openai/models returns dozens
-        # of historical / experimental / embedding ids. Cap to the current
-        # 3.x family plus the rolling `*-latest` aliases.
+        # Native Gemini REST endpoint -- the Gemini API does NOT speak
+        # OpenAI Chat Completions on this base. Requests/responses are
+        # translated in `_stream_gemini` in external_provider.py.
+        # API reference: https://ai.google.dev/gemini-api/docs
+        "base_url": "https://generativelanguage.googleapis.com/v1beta",
+        # Curated lineup -- the live ListModels response returns dozens
+        # of historical / experimental / embedding ids. Cap to the
+        # current chat-capable Gemini families (3.5 / 3.1 / 3 Flash /
+        # 2.5) plus the Nano Banana image trio and the rolling
+        # `*-latest` aliases. Excluded on purpose:
+        #   - `gemini-2.0-flash*` (Google retired 2026-06-01; 404 on use)
+        #   - `gemini-3-pro-preview` (shut down 2026-03-09; auto-redirects
+        #     to `gemini-3.1-pro-preview` per Google's deprecation notice,
+        #     so we surface 3.1 directly and skip the redirect).
+        # The allowlist below blocks the retired ids from re-appearing
+        # via the live ListModels fetch. Verified against the live
+        # `/v1beta/models` catalog 2026-05-24.
         "default_models": [
             "gemini-3.1-pro-preview",
+            "gemini-3.5-flash",
             "gemini-3.1-flash-lite",
             "gemini-3-flash-preview",
             "gemini-pro-latest",
             "gemini-flash-latest",
             "gemini-flash-lite-latest",
+            "gemini-2.5-pro",
+            "gemini-2.5-flash",
+            "gemini-2.5-flash-lite",
+            "gemini-3-pro-image-preview",
+            "gemini-3.1-flash-image-preview",
+            "gemini-2.5-flash-image",
         ],
         "supports_streaming": True,
         "supports_vision": True,
         "supports_tool_calling": True,
-        "auth_header": "Authorization",
-        "auth_prefix": "Bearer ",
-        "notes": "OpenAI-compatible endpoint. API key from https://aistudio.google.com/apikey.",
+        # The native API takes the API key on the `x-goog-api-key`
+        # header. An empty `auth_prefix` ensures we send the bare key.
+        "auth_header": "x-goog-api-key",
+        "auth_prefix": "",
+        "openai_compatible": False,
+        "notes": (
+            "Native Gemini API. Translation lives in _stream_gemini. "
+            "API key from https://aistudio.google.com/apikey. "
+            "See https://ai.google.dev/gemini-api/docs for endpoint shapes."
+        ),
+        # Even after the regex match, drop ids that Google still
+        # returns from ListModels but routes via implicit redirect.
+        # gemini-3-pro-preview was shut down 2026-03-09 and is
+        # auto-aliased to gemini-3.1-pro-preview; we surface the
+        # canonical id only so users do not see two cards for the
+        # same underlying model.
+        "model_id_deny_exact": ("gemini-3-pro-preview",),
+        # Matches the chat-capable 3.5 / 3.1 / 3 / 2.5 families plus the
+        # rolling *-latest aliases (which Google rolls forward as new
+        # generations ship). Image-tier ids (`-image`, `-image-preview`,
+        # `nano-banana-pro-preview`) flow through the Nano Banana
+        # `responseModalities` path in `_stream_gemini`. Retired 2.0
+        # ids ARE NOT in this regex on purpose -- Google's ListModels
+        # would otherwise re-surface them and they 404 on use.
         "model_id_allowlist": re.compile(
-            r"^(gemini-3\.1-flash-lite|gemini-3-flash-preview|"
-            r"gemini-3\.1-pro-preview|gemini-pro-latest|"
-            r"gemini-flash-latest|gemini-flash-lite-latest)$"
+            r"^("
+            r"gemini-3\.5-(?:flash|pro)(?:-preview)?|"
+            r"gemini-3\.1-(?:flash|pro|flash-lite)(?:-preview)?(?:-customtools)?|"
+            r"gemini-3\.1-flash-image-preview|"
+            r"gemini-3-(?:flash|pro)(?:-preview)?|"
+            r"gemini-3-pro-image-preview|"
+            r"nano-banana-pro-preview|"
+            r"gemini-2\.5-pro|gemini-2\.5-flash|gemini-2\.5-flash-lite|"
+            r"gemini-2\.5-flash-image|"
+            r"gemini-pro-latest|gemini-flash-latest|gemini-flash-lite-latest"
+            r")$"
         ),
     },
     "deepseek": {
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 0e9cce7c3e..35d5903826 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -632,8 +632,17 @@ def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str
 
     for *_, sockaddr in infos:
         ip = ipaddress.ip_address(sockaddr[0])
+        # `not ip.is_global` rejects every category the denylist below
+        # also rejects PLUS shared address space (100.64.0.0/10 carrier-
+        # grade NAT) and benchmarking/documentation/exchange ranges that
+        # Python classifies with `is_private=False` and `is_global=False`
+        # (see https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_global).
+        # The explicit predicates after it give human-readable categories
+        # in the error message, but a single non-global check is the
+        # source of truth and prevents future ranges from leaking.
         if (
-            ip.is_private
+            not ip.is_global
+            or ip.is_private
             or ip.is_loopback
             or ip.is_link_local
             or ip.is_multicast
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 0af9425fdc..b58ca66440 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -581,6 +581,14 @@ class ChatMessage(BaseModel):
         None,
         description = "OpenAI tool-result messages: name of the tool whose result this is.",
     )
+    extra_content: Optional[dict] = Field(
+        None,
+        description = (
+            "Provider-specific extra fields the translator may read. "
+            "Gemini reads `extra_content.google.thought_signature` "
+            "from assistant messages to replay text-part signatures."
+        ),
+    )
 
     @model_validator(mode = "after")
     def _validate_role_shape(self) -> "ChatMessage":
@@ -752,17 +760,42 @@ class ChatCompletionRequest(BaseModel):
         None,
         description = "[x-unsloth] Override base URL for the external provider.",
     )
-    enable_prompt_caching: Optional[bool] = Field(
+    enable_prompt_caching: Optional[Union[bool, str]] = Field(
         None,
         description = (
             "[x-unsloth] Opt in to provider-side prompt caching. On Anthropic, "
-            "attaches cache_control={type:ephemeral} to the system block so the "
-            "static prefix is reused across turns. On OpenAI cloud, caching is "
-            "automatic for prompts >=1024 tokens and this flag is informational. "
-            "Ignored for every other provider (mistral, gemini, kimi, openrouter, "
-            "vllm, local, etc.). Treated as enabled when omitted."
+            "boolean true attaches cache_control={type:ephemeral} to the system "
+            "block so the static prefix is reused across turns. On OpenAI cloud, "
+            "caching is automatic for prompts >=1024 tokens and the boolean is "
+            "informational. On Gemini, pass a string cache resource name such "
+            "as `cachedContents/abc123` to attach `cachedContent` on the native "
+            "request (boolean true is a no-op on Gemini because creating the "
+            "cache requires a separate POST /cachedContents call). Ignored for "
+            "every other provider. Treated as enabled when omitted."
         ),
     )
+
+    @field_validator("enable_prompt_caching", mode = "before")
+    @classmethod
+    def _coerce_enable_prompt_caching(cls, value: Any) -> Any:
+        """Preserve the pre-PR coercion: the field used to be Optional[bool],
+        so callers historically sent JSON strings `"true"` / `"false"` and
+        Pydantic v1 coerced them. Widening to Optional[Union[bool, str]] for
+        Gemini cache resource names lets `"false"` slip through as a truthy
+        string. Coerce the canonical bool literals back so explicit opt-outs
+        stay opt-out."""
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            # Match Pydantic v1's BooleanField coercion table (yes/y/on/t/1
+            # and no/n/off/f/0) so opt-outs that used to parse still parse.
+            # Anything else is preserved as a string for Gemini's
+            # cachedContent resource path.
+            if lowered in ("true", "t", "1", "yes", "y", "on"):
+                return True
+            if lowered in ("false", "f", "0", "no", "n", "off"):
+                return False
+        return value
+
     prompt_cache_ttl: Optional[str] = Field(
         None,
         description = (
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index a156f2397c..92498b8a9a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -1705,6 +1705,7 @@ def _build_external_messages(
     messages: list,
     supports_vision: bool,
     provider_type: Optional[str] = None,
+    base_url: Optional[str] = None,
 ) -> list[dict]:
     """
     Convert ChatMessage list to OpenAI-compatible dicts for external providers.
@@ -1732,14 +1733,171 @@ def _build_external_messages(
     document_provider = provider_type in _INPUT_DOCUMENT_PROVIDERS
     anthropic = provider_type == "anthropic"
     openai = provider_type == "openai"
+    # `extra_content` is a Gemini-specific carrier for the assistant's
+    # text-part `thoughtSignature` round-trip on the native
+    # streamGenerateContent endpoint. Custom Gemini OpenAI-compatible
+    # gateways (LiteLLM etc.) route through /chat/completions where
+    # the field is unknown and can be rejected -- gate strictly on the
+    # Google-hosted Gemini base.
+    _native_gemini = False
+    if provider_type == "gemini" and base_url:
+        try:
+            from urllib.parse import urlparse as _urlparse
+
+            _host = (_urlparse(base_url).hostname or "").lower()
+            _native_gemini = _host == "generativelanguage.googleapis.com"
+        except Exception:
+            _native_gemini = False
+    emit_extra_content = _native_gemini
+
+    _SERVER_BUILTIN_TOOL_NAMES = frozenset(
+        {"web_search", "web_fetch", "code_execution", "image_generation"}
+    )
+
+    def _is_marked_server_builtin_tool_call(tc: Any) -> bool:
+        """Return True iff `tc` is a synthetic provider-side tool card
+        with one of the canonical builtin names and either:
+          - the new `args._server_tool` marker stamped by the backend, or
+          - a Gemini `args.google.native_part` payload (durable replay
+            signal for code_execution / image_generation that predates
+            the marker).
+        Such cards must not be forwarded to non-native providers
+        because they are not real user functions and the receiving API
+        will reject the orphan tool history. Real user functions with
+        these names normally have neither signal.
+        """
+        if not isinstance(tc, dict):
+            return False
+        fn = tc.get("function")
+        if not isinstance(fn, dict):
+            return False
+        name = (fn.get("name") or "").lower()
+        if name not in _SERVER_BUILTIN_TOOL_NAMES:
+            return False
+        raw_args = fn.get("arguments") or ""
+        try:
+            args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+        except Exception:
+            return False
+        if not isinstance(args, dict):
+            return False
+        if args.get("_server_tool") is True:
+            return True
+        google = args.get("google")
+        return isinstance(google, dict) and isinstance(google.get("native_part"), dict)
+
+    # When we drop a server-side builtin tool_call here, the matching
+    # `role="tool"` follow-up must also be dropped from the outbound
+    # history -- otherwise the provider receives an orphan
+    # tool_call_id with no matching assistant call, which OpenAI
+    # Responses and Anthropic both reject.
+    dropped_server_builtin_tool_call_ids: set[str] = set()
+
+    def _filter_tool_calls(tool_calls: Any) -> Optional[list]:
+        """Sanitize assistant `tool_calls` for non-native-Gemini providers.
+
+        Two concerns:
+          1. `tool_calls[i].extra_content` carries Gemini-only
+             thoughtSignature metadata; strip it for providers that
+             cannot parse the unknown key.
+          2. Marked server-side builtin cards (`_server_tool: true` on
+             a canonical builtin name, or a Gemini `native_part`
+             payload) are provider-internal Studio tool cards from a
+             prior native Gemini turn; forwarding them to OpenAI /
+             Anthropic / custom OAI-compat gateways sends an orphan
+             `tool_calls` entry (no matching tool declaration, often
+             no matching `role="tool"` reply) that can be rejected.
+             We record the dropped call_ids so the matching role=tool
+             message is also skipped below.
+        Native Gemini keeps both untouched so the native translator can
+        replay them via `native_part`.
+        """
+        if not tool_calls:
+            return None
+        if not isinstance(tool_calls, list):
+            return tool_calls
+        if emit_extra_content:
+            return tool_calls
+        cleaned: list = []
+        for _tc in tool_calls:
+            if _is_marked_server_builtin_tool_call(_tc):
+                _tc_id = _tc.get("id") if isinstance(_tc, dict) else None
+                if isinstance(_tc_id, str) and _tc_id:
+                    dropped_server_builtin_tool_call_ids.add(_tc_id)
+                continue
+            if not isinstance(_tc, dict):
+                cleaned.append(_tc)
+                continue
+            if "extra_content" not in _tc:
+                cleaned.append(_tc)
+                continue
+            _stripped = {k: v for k, v in _tc.items() if k != "extra_content"}
+            cleaned.append(_stripped)
+        return cleaned
+
     result = []
     for msg in messages:
+        # Drop role=tool messages whose matching server-builtin
+        # tool_call was already filtered above. Forwarding an orphan
+        # tool_result with no matching tool_call would be rejected by
+        # OpenAI Responses and Anthropic.
+        if (
+            msg.role == "tool"
+            and isinstance(msg.tool_call_id, str)
+            and msg.tool_call_id in dropped_server_builtin_tool_call_ids
+        ):
+            continue
         if isinstance(msg.content, str):
-            # Skip assistant messages with empty content (some providers reject them)
-            if msg.role == "assistant" and not msg.content.strip():
+            # Drop bare assistant messages with no content AND no
+            # tool_calls (some providers reject empty assistant turns).
+            # Preserve assistant turns whose only payload is tool_calls
+            # so multi-turn function-call loops round-trip.
+            if (
+                msg.role == "assistant"
+                and not msg.content.strip()
+                and not msg.tool_calls
+            ):
                 continue
-            result.append({"role": msg.role, "content": msg.content})
-        elif isinstance(msg.content, list):
+            out: dict[str, Any] = {"role": msg.role, "content": msg.content}
+            if msg.role == "assistant" and msg.tool_calls:
+                _tcs = _filter_tool_calls(msg.tool_calls)
+                if _tcs:
+                    out["tool_calls"] = _tcs
+                elif not msg.content.strip():
+                    # Every tool_call was a synthetic provider-side
+                    # card and was dropped; the assistant turn would
+                    # be an empty `{"role":"assistant","content":""}`
+                    # which some providers reject. Skip it entirely.
+                    continue
+            if msg.role == "tool":
+                if msg.tool_call_id:
+                    out["tool_call_id"] = msg.tool_call_id
+                if msg.name:
+                    out["name"] = msg.name
+            if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                out["extra_content"] = msg.extra_content
+            result.append(out)
+            continue
+        # Assistant messages with content=None but populated tool_calls
+        # are valid (post-tool-call assistant turn). Forward them so the
+        # provider helper can rebuild the functionCall part.
+        if msg.content is None and msg.role == "assistant" and msg.tool_calls:
+            _filtered_tcs = _filter_tool_calls(msg.tool_calls)
+            if not _filtered_tcs:
+                # Every tool_call on this turn was provider-side
+                # synthetic and dropped; skipping the whole message
+                # avoids forwarding an empty assistant turn.
+                continue
+            _assistant_only: dict[str, Any] = {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": _filtered_tcs,
+            }
+            if emit_extra_content and msg.extra_content:
+                _assistant_only["extra_content"] = msg.extra_content
+            result.append(_assistant_only)
+            continue
+        if isinstance(msg.content, list):
             if supports_vision:
                 parts = []
                 for part in msg.content:
@@ -1797,9 +1955,27 @@ def _build_external_messages(
                         # provider would 400 on the unknown part, so
                         # gate by provider_type.
                         parts.append({"type": "compaction", "content": part.content})
-                if msg.role == "assistant" and not parts:
+                entry: dict[str, Any] = {"role": msg.role, "content": parts}
+                if msg.role == "assistant" and msg.tool_calls:
+                    _tcs = _filter_tool_calls(msg.tool_calls)
+                    if _tcs:
+                        entry["tool_calls"] = _tcs
+                    elif not parts:
+                        # All tool_calls were synthetic and dropped,
+                        # and no preserved content parts survived.
+                        # Skip rather than forward an empty assistant
+                        # turn that downstream providers reject.
+                        continue
+                elif msg.role == "assistant" and not parts:
                     continue
-                result.append({"role": msg.role, "content": parts})
+                if msg.role == "tool":
+                    if msg.tool_call_id:
+                        entry["tool_call_id"] = msg.tool_call_id
+                    if msg.name:
+                        entry["name"] = msg.name
+                if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                    entry["extra_content"] = msg.extra_content
+                result.append(entry)
             else:
                 # Non-vision provider: strip images / documents, keep
                 # text, optionally keep compaction (Anthropic only --
@@ -1835,9 +2011,32 @@ def _build_external_messages(
                 if len(preserved) == 1 and preserved[0]["type"] == "text":
                     # Single text part collapses back to a string for
                     # providers that don't accept content arrays.
-                    result.append({"role": msg.role, "content": preserved[0]["text"]})
+                    entry = {"role": msg.role, "content": preserved[0]["text"]}
                 else:
-                    result.append({"role": msg.role, "content": preserved})
+                    entry = {"role": msg.role, "content": preserved}
+                if msg.role == "assistant" and msg.tool_calls:
+                    _tcs = _filter_tool_calls(msg.tool_calls)
+                    if _tcs:
+                        entry["tool_calls"] = _tcs
+                    else:
+                        # All tool_calls were synthetic and dropped;
+                        # skip if there's no surviving content either.
+                        _entry_content = entry.get("content")
+                        _has_text = (
+                            isinstance(_entry_content, str) and _entry_content.strip()
+                        ) or (
+                            isinstance(_entry_content, list) and len(_entry_content) > 0
+                        )
+                        if not _has_text:
+                            continue
+                if msg.role == "tool":
+                    if msg.tool_call_id:
+                        entry["tool_call_id"] = msg.tool_call_id
+                    if msg.name:
+                        entry["name"] = msg.name
+                if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                    entry["extra_content"] = msg.extra_content
+                result.append(entry)
     return result
 
 
@@ -1912,6 +2111,7 @@ async def _proxy_to_external_provider(
         payload.messages,
         _supports_vision,
         provider_type = provider_type,
+        base_url = base_url,
     )
 
     client = ExternalProviderClient(
@@ -1920,6 +2120,14 @@ async def _proxy_to_external_provider(
         api_key = api_key,
     )
 
+    # `top_k` defaults to 20 in ChatCompletionRequest because the local
+    # inference path expects an int, but the external-provider path
+    # should treat "field omitted from JSON" as "use provider default"
+    # so callers that send only model/messages do not silently get
+    # different sampling than before this PR. Pydantic's
+    # `model_fields_set` tracks explicit-vs-default per request.
+    _top_k_explicit = payload.top_k if "top_k" in payload.model_fields_set else None
+
     async def _stream():
         gen = client.stream_chat_completion(
             messages = chat_messages,
@@ -1928,7 +2136,7 @@ async def _proxy_to_external_provider(
             top_p = payload.top_p,
             max_tokens = payload.max_tokens,
             presence_penalty = payload.presence_penalty,
-            top_k = payload.top_k,
+            top_k = _top_k_explicit,
             enable_thinking = payload.enable_thinking,
             reasoning_effort = payload.reasoning_effort,
             enabled_tools = payload.enabled_tools,
@@ -1937,6 +2145,8 @@ async def _proxy_to_external_provider(
             anthropic_code_exec_container_id = payload.anthropic_code_exec_container_id,
             prompt_cache_ttl = payload.prompt_cache_ttl,
             compaction_threshold = payload.compaction_threshold,
+            tools = payload.tools,
+            tool_choice = payload.tool_choice,
             fast_mode = payload.fast_mode,
             stream = payload.stream,
         )
@@ -4480,7 +4690,17 @@ async def anthropic_messages(
         [m.model_dump() for m in payload.messages],
         payload.system,
     )
-    openai_messages = _drop_empty_assistant_sentinels(openai_messages)
+    # Strip synthetic provider-side builtin tool history (web_search,
+    # web_fetch, code_execution, image_generation cards tagged with
+    # _server_tool or extra_content.google.native_part) before handing
+    # off to local llama-server. The local /v1/chat/completions and
+    # GGUF passthrough builders apply the same strip; without it an
+    # Anthropic /v1/messages caller replaying a prior provider-side
+    # tool_use forwards fake builtin tool history to a backend that
+    # has no matching function declarations.
+    openai_messages = _strip_provider_synthetic_tool_history(
+        _drop_empty_assistant_sentinels(openai_messages)
+    )
 
     # Enforce vision guard + re-encode embedded images to PNG so the
     # Anthropic endpoint matches the behavior of /v1/chat/completions.
@@ -5271,6 +5491,110 @@ def _drop_empty_assistant_sentinels(messages: list[dict]) -> list[dict]:
     return out
 
 
+_LOCAL_SERVER_BUILTIN_TOOL_NAMES = frozenset(
+    {"web_search", "web_fetch", "code_execution", "image_generation"}
+)
+
+
+def _strip_provider_synthetic_tool_history(messages: list[dict]) -> list[dict]:
+    """Drop synthetic provider-side tool_calls + matching role=tool replies
+    on the local-backend (llama-server / GGUF) dispatch path.
+
+    A Gemini chat that ran code_execution / image_generation persists the
+    server-side tool card into thread history as an assistant tool_calls
+    entry tagged with ``args._server_tool`` (or a Gemini
+    ``args.google.native_part`` payload) plus a follow-up role=tool reply.
+    When the user switches the SAME thread to a local GGUF model, those
+    synthetic tool_calls are not real user functions, llama-server has no
+    matching declaration, and Gemini-only ``extra_content`` /
+    ``native_part`` payloads are meaningless. Forward only ordinary user
+    function calls; strip the matched role=tool replies too so the
+    backend does not see an orphan tool_call_id.
+    """
+    dropped_ids: set[str] = set()
+    sanitized_assistant: list[dict] = []
+    for m in messages:
+        if m.get("role") != "assistant":
+            sanitized_assistant.append(m)
+            continue
+        tool_calls = m.get("tool_calls")
+        if not isinstance(tool_calls, list) or not tool_calls:
+            # Plain text Gemini reply: still strip message-level
+            # `extra_content` (carries `google.thought_signature` replay
+            # metadata) so a text-only Gemini turn switched to a local
+            # GGUF backend does not leak Gemini-only fields to
+            # llama-server. ChatMessage previously did not have
+            # `extra_content`, so the field was implicitly dropped --
+            # round-22 added it to ChatMessage, which is what made this
+            # leak possible.
+            if "extra_content" in m:
+                m = {k: v for k, v in m.items() if k != "extra_content"}
+            sanitized_assistant.append(m)
+            continue
+        cleaned: list[dict] = []
+        for tc in tool_calls:
+            if not isinstance(tc, dict):
+                cleaned.append(tc)
+                continue
+            fn = tc.get("function")
+            name = ""
+            if isinstance(fn, dict):
+                name = (fn.get("name") or "").lower()
+            if name in _LOCAL_SERVER_BUILTIN_TOOL_NAMES:
+                raw_args = fn.get("arguments") if isinstance(fn, dict) else None
+                args_obj: Any = None
+                if isinstance(raw_args, str):
+                    try:
+                        args_obj = json.loads(raw_args) if raw_args else None
+                    except Exception:
+                        args_obj = None
+                elif isinstance(raw_args, dict):
+                    args_obj = raw_args
+                is_synthetic = False
+                if isinstance(args_obj, dict):
+                    if args_obj.get("_server_tool") is True:
+                        is_synthetic = True
+                    google = args_obj.get("google")
+                    if isinstance(google, dict) and isinstance(
+                        google.get("native_part"), dict
+                    ):
+                        is_synthetic = True
+                if is_synthetic:
+                    tc_id = tc.get("id")
+                    if isinstance(tc_id, str) and tc_id:
+                        dropped_ids.add(tc_id)
+                    continue
+            # Strip Gemini-only `extra_content` on real user tool_calls
+            # too — llama-server has no use for it and may pass it
+            # through to the model unchanged.
+            if "extra_content" in tc:
+                tc = {k: v for k, v in tc.items() if k != "extra_content"}
+            cleaned.append(tc)
+        # Drop top-level message-level `extra_content` (Gemini
+        # thoughtSignature replay metadata) on local dispatch.
+        m_clean = {k: v for k, v in m.items() if k != "extra_content"}
+        if cleaned:
+            m_clean["tool_calls"] = cleaned
+        else:
+            m_clean.pop("tool_calls", None)
+        if not m_clean.get("content") and not m_clean.get("tool_calls"):
+            continue  # assistant turn now empty, drop
+        sanitized_assistant.append(m_clean)
+
+    if not dropped_ids:
+        return sanitized_assistant
+    out: list[dict] = []
+    for m in sanitized_assistant:
+        if (
+            m.get("role") == "tool"
+            and isinstance(m.get("tool_call_id"), str)
+            and m["tool_call_id"] in dropped_ids
+        ):
+            continue
+        out.append(m)
+    return out
+
+
 def _openai_messages_for_passthrough(payload) -> list[dict]:
     """Build OpenAI-format message dicts for the /v1/chat/completions
     passthrough path.
@@ -5287,8 +5611,10 @@ def _openai_messages_for_passthrough(payload) -> list[dict]:
     ``image_url`` content part so vision + function-calling requests work
     transparently.
     """
-    messages = _drop_empty_assistant_sentinels(
-        [m.model_dump(exclude_none = True) for m in payload.messages]
+    messages = _strip_provider_synthetic_tool_history(
+        _drop_empty_assistant_sentinels(
+            [m.model_dump(exclude_none = True) for m in payload.messages]
+        )
     )
 
     if not payload.image_base64:
@@ -5337,8 +5663,10 @@ def _openai_messages_for_gguf_chat(payload, is_vision: bool) -> tuple[list[dict]
     all per-turn ``image_url`` parts so multi-image chat history keeps each
     image attached to its original turn.
     """
-    messages = _drop_empty_assistant_sentinels(
-        [m.model_dump(exclude_none = True) for m in payload.messages]
+    messages = _strip_provider_synthetic_tool_history(
+        _drop_empty_assistant_sentinels(
+            [m.model_dump(exclude_none = True) for m in payload.messages]
+        )
     )
     has_message_image = any(
         isinstance(msg.get("content"), list)
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index 2bb1de5366..5d4bd46e62 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -318,22 +318,45 @@ async def list_provider_models(
 
     try:
         models = await client.list_models()
-        allow_prefixes = info.get("model_id_allow_prefixes")
-        if allow_prefixes is not None:
-            prefix_tuple = tuple(str(p) for p in allow_prefixes if str(p))
-            if prefix_tuple:
-                models = [m for m in models if m.get("id", "").startswith(prefix_tuple)]
-        allowlist = info.get("model_id_allowlist")
-        if allowlist is not None:
-            models = [m for m in models if allowlist.match(m.get("id", ""))]
-        deny_exact = info.get("model_id_deny_exact")
-        if deny_exact is not None:
-            deny_ids = {str(m) for m in deny_exact if str(m)}
-            if deny_ids:
-                models = [m for m in models if m.get("id", "") not in deny_ids]
-        denylist = info.get("model_id_denylist")
-        if denylist is not None:
-            models = [m for m in models if not denylist.search(m.get("id", ""))]
+        # Registry-level model-id filters are scoped to the canonical
+        # native Gemini base. A custom Gemini OAI-compatible proxy
+        # (LiteLLM, deployment gateway) returns IDs like
+        # `google/gemini-2.5-flash`, `gemini/gemini-2.5-flash`, or
+        # team-prefixed deployment aliases; the native allowlist regex
+        # would strip those out and leave the picker empty even though
+        # the chat path now routes them via the OAI-compatible
+        # dispatcher (the same gate ExternalProviderClient applies for
+        # request building). Match the host check here so the model
+        # list and chat dispatch agree on what counts as "native".
+        apply_registry_model_filters = True
+        if payload.provider_type == "gemini":
+            try:
+                from urllib.parse import urlparse as _urlparse
+
+                _host = (_urlparse(base_url).hostname or "").lower()
+            except Exception:
+                _host = ""
+            apply_registry_model_filters = _host == "generativelanguage.googleapis.com"
+
+        if apply_registry_model_filters:
+            allow_prefixes = info.get("model_id_allow_prefixes")
+            if allow_prefixes is not None:
+                prefix_tuple = tuple(str(p) for p in allow_prefixes if str(p))
+                if prefix_tuple:
+                    models = [
+                        m for m in models if m.get("id", "").startswith(prefix_tuple)
+                    ]
+            allowlist = info.get("model_id_allowlist")
+            if allowlist is not None:
+                models = [m for m in models if allowlist.match(m.get("id", ""))]
+            deny_exact = info.get("model_id_deny_exact")
+            if deny_exact is not None:
+                deny_ids = {str(m) for m in deny_exact if str(m)}
+                if deny_ids:
+                    models = [m for m in models if m.get("id", "") not in deny_ids]
+            denylist = info.get("model_id_denylist")
+            if denylist is not None:
+                models = [m for m in models if not denylist.search(m.get("id", ""))]
         # Apply an optional cap after filtering so registry entries with a
         # large remote catalog (e.g. HF Inference Providers) can stay
         # picker-sized. No popularity sort happens server-side, so this is
diff --git a/studio/backend/tests/test_anthropic_code_execution.py b/studio/backend/tests/test_anthropic_code_execution.py
index 7f6fe58329..5c88437d17 100644
--- a/studio/backend/tests/test_anthropic_code_execution.py
+++ b/studio/backend/tests/test_anthropic_code_execution.py
@@ -275,7 +275,13 @@ def test_bash_code_execution_emits_tool_start_and_end(monkeypatch):
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "code_execution"
     assert start["tool_call_id"] == "srvtoolu_1"
-    assert start["arguments"] == {"kind": "bash", "command": "ls -la"}
+    # `_server_tool: True` marks this as a provider-side synthetic
+    # tool card for the frontend's history serializer.
+    assert start["arguments"] == {
+        "kind": "bash",
+        "command": "ls -la",
+        "_server_tool": True,
+    }
 
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_1"
diff --git a/studio/backend/tests/test_anthropic_web_fetch.py b/studio/backend/tests/test_anthropic_web_fetch.py
index da10d679eb..88a922e7eb 100644
--- a/studio/backend/tests/test_anthropic_web_fetch.py
+++ b/studio/backend/tests/test_anthropic_web_fetch.py
@@ -271,7 +271,12 @@ def test_web_fetch_success_emits_tool_start_and_end(monkeypatch):
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "web_fetch"
     assert start["tool_call_id"] == "srvtoolu_wf1"
-    assert start["arguments"] == {"url": "https://example.com/article"}
+    # `_server_tool: True` marks this as a provider-side synthetic
+    # tool card for the frontend's history serializer.
+    assert start["arguments"] == {
+        "url": "https://example.com/article",
+        "_server_tool": True,
+    }
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_wf1"
     # The source pill uses Title / URL / snippet as parseSourcesFromResult expects.
diff --git a/studio/backend/tests/test_gemini_provider.py b/studio/backend/tests/test_gemini_provider.py
new file mode 100644
index 0000000000..4dc97302e2
--- /dev/null
+++ b/studio/backend/tests/test_gemini_provider.py
@@ -0,0 +1,5501 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Unit tests for the native Gemini API translation layer.
+
+Gemini does NOT speak OpenAI Chat Completions on its primary endpoint
+(`streamGenerateContent`). `_stream_gemini` in
+`core/inference/external_provider.py` translates between the two shapes:
+
+  Request:
+    OpenAI messages [{role, content}]
+      -> Gemini contents [{role, parts: [{text}|{inlineData}|{functionCall}|...]}]
+        + systemInstruction.parts[].text for role=system messages
+        + generationConfig.{temperature,topP,topK,maxOutputTokens}
+        + tools[{googleSearch:{}}] for web_search
+        + tools[{codeExecution:{}}] for code_execution
+        + responseModalities=[TEXT,IMAGE] for Nano Banana (gemini-2.5-flash-image)
+        + cachedContent for prompt caching
+
+  Response:
+    Gemini SSE chunks { candidates:[{content:{parts:[...]}, finishReason}],
+                        usageMetadata:{promptTokenCount, candidatesTokenCount} }
+      -> OpenAI chat.completion.chunk frames
+        (delta.content for text, delta.tool_calls for functionCall,
+         _toolEvent for image_b64/web_search, usage block before [DONE])
+
+These tests pin the outbound body shape AND the inbound translation
+using httpx.MockTransport (no live network). Mirrors the structure of
+test_anthropic_cache_ttl.py and test_openai_image_generation.py.
+"""
+
+import asyncio
+import base64
+import json
+
+import httpx
+import pytest
+
+from core.inference import external_provider as ep_mod
+from core.inference.external_provider import ExternalProviderClient
+
+
+_active_mock_clients: list[httpx.AsyncClient] = []
+
+
+def _drive(coro):
+    # Create a fresh loop per drive so tests don't share asyncio state.
+    # Close mocked clients + shutdown async-generators inside this loop
+    # so Python 3.13 doesn't emit the
+    # `Response.aiter_*.aclose was never awaited` warning on GC.
+    loop = asyncio.new_event_loop()
+    try:
+        result = loop.run_until_complete(coro)
+        while _active_mock_clients:
+            mc = _active_mock_clients.pop()
+            loop.run_until_complete(mc.aclose())
+        return result
+    finally:
+        try:
+            loop.run_until_complete(loop.shutdown_asyncgens())
+        finally:
+            loop.close()
+
+
+def _make_gemini_client(
+    base_url: str = "https://generativelanguage.googleapis.com/v1beta",
+) -> ExternalProviderClient:
+    return ExternalProviderClient(
+        provider_type = "gemini",
+        base_url = base_url,
+        api_key = "AIza-test-key",
+    )
+
+
+def _mock_http(monkeypatch, handler):
+    mock_client = httpx.AsyncClient(transport = httpx.MockTransport(handler))
+    monkeypatch.setattr(ep_mod, "_http_client", mock_client)
+    # `_drive` will aclose this at the end of the run inside the same
+    # event loop so we do not leak an unawaited aclose() coroutine.
+    _active_mock_clients.append(mock_client)
+
+
+def _gemini_sse(events: list[dict]) -> bytes:
+    """Encode a list of dicts as Gemini-style SSE frames (`data:` lines)."""
+    chunks: list[str] = []
+    for event in events:
+        chunks.append(f"data: {json.dumps(event)}")
+        chunks.append("")
+    return ("\n".join(chunks) + "\n").encode("utf-8")
+
+
+def _capture_body(monkeypatch, **kwargs) -> dict:
+    """Drive a single stream and return the captured outbound request body."""
+    captured: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        captured["headers"] = dict(request.headers)
+        captured["url"] = str(request.url)
+        captured["method"] = request.method
+        # Minimal valid Gemini stream so the helper can complete.
+        return httpx.Response(
+            200,
+            content = _gemini_sse(
+                [
+                    {
+                        "candidates": [
+                            {
+                                "content": {
+                                    "role": "model",
+                                    "parts": [{"text": "ok"}],
+                                },
+                                "finishReason": "STOP",
+                            }
+                        ],
+                        "usageMetadata": {
+                            "promptTokenCount": 1,
+                            "candidatesTokenCount": 1,
+                        },
+                    }
+                ]
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    messages = kwargs.pop("messages", [{"role": "user", "content": "hi"}])
+    model = kwargs.pop("model", "gemini-2.5-flash")
+    temperature = kwargs.pop("temperature", 0.7)
+    top_p = kwargs.pop("top_p", 0.95)
+    max_tokens = kwargs.pop("max_tokens", 64)
+
+    async def run():
+        client = _make_gemini_client()
+        async for _ in client.stream_chat_completion(
+            messages = messages,
+            model = model,
+            temperature = temperature,
+            top_p = top_p,
+            max_tokens = max_tokens,
+            **kwargs,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    return captured
+
+
+def _collect(monkeypatch, sse_events, **kwargs) -> list[str]:
+    """Drive a stream with a custom set of SSE events and return raw lines."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = _gemini_sse(sse_events),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    messages = kwargs.pop("messages", [{"role": "user", "content": "hi"}])
+    model = kwargs.pop("model", "gemini-2.5-flash")
+    temperature = kwargs.pop("temperature", 0.7)
+    top_p = kwargs.pop("top_p", 0.95)
+    max_tokens = kwargs.pop("max_tokens", 64)
+
+    out: list[str] = []
+
+    async def run():
+        client = _make_gemini_client()
+        async for line in client.stream_chat_completion(
+            messages = messages,
+            model = model,
+            temperature = temperature,
+            top_p = top_p,
+            max_tokens = max_tokens,
+            **kwargs,
+        ):
+            out.append(line)
+        await client.close()
+
+    _drive(run())
+    return out
+
+
+def _parse_chunks(lines: list[str]) -> list[dict]:
+    out: list[dict] = []
+    for raw in lines:
+        if not raw.startswith("data:"):
+            continue
+        payload = raw[len("data:") :].strip()
+        if not payload or payload == "[DONE]":
+            continue
+        try:
+            out.append(json.loads(payload))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+# ── request body translation ─────────────────────────────────────────
+
+
+def test_request_body_uses_contents_and_parts_shape(monkeypatch):
+    """OpenAI messages must be translated to Gemini's `contents` shape."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "system", "content": "Be brief."},
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi there"},
+            {"role": "user", "content": "Follow up"},
+        ],
+    )
+    body = captured["body"]
+    # system -> systemInstruction
+    assert body["systemInstruction"] == {"parts": [{"text": "Be brief."}]}, body
+    # user/assistant -> contents with role user/model
+    assert body["contents"] == [
+        {"role": "user", "parts": [{"text": "Hello"}]},
+        {"role": "model", "parts": [{"text": "Hi there"}]},
+        {"role": "user", "parts": [{"text": "Follow up"}]},
+    ], body["contents"]
+    # generationConfig fields map across with Google's casing.
+    gc = body["generationConfig"]
+    assert gc["temperature"] == 0.7
+    assert gc["topP"] == 0.95
+    assert gc["maxOutputTokens"] == 64
+
+
+def test_request_url_targets_stream_generate_content(monkeypatch):
+    """Helper must POST to /v1beta/models/{model}:streamGenerateContent?alt=sse."""
+    captured = _capture_body(monkeypatch, model = "gemini-2.5-pro")
+    url = captured["url"]
+    assert ":streamGenerateContent" in url, url
+    assert "alt=sse" in url, url
+    assert "/v1beta/models/gemini-2.5-pro" in url, url
+    assert captured["method"] == "POST"
+
+
+def test_request_auth_header_uses_x_goog_api_key(monkeypatch):
+    """API key must be sent on `x-goog-api-key`, not Authorization."""
+    captured = _capture_body(monkeypatch)
+    hdrs = captured["headers"]
+    assert hdrs.get("x-goog-api-key") == "AIza-test-key", hdrs
+    assert "authorization" not in {k.lower() for k in hdrs}, hdrs
+
+
+def test_top_k_forwarded_only_when_positive(monkeypatch):
+    """top_k is opt-in; only positive integers reach the wire."""
+    captured = _capture_body(monkeypatch, top_k = 40)
+    assert captured["body"]["generationConfig"]["topK"] == 40
+
+    captured = _capture_body(monkeypatch, top_k = 0)
+    assert "topK" not in captured["body"]["generationConfig"]
+
+
+def test_presence_penalty_forwarded_to_generation_config(monkeypatch):
+    """A non-zero presence_penalty reaches generationConfig.presencePenalty."""
+    captured = _capture_body(monkeypatch, presence_penalty = 0.7)
+    assert captured["body"]["generationConfig"]["presencePenalty"] == 0.7
+
+    # And the default of zero is omitted, matching top_k semantics.
+    captured = _capture_body(monkeypatch, presence_penalty = 0.0)
+    assert "presencePenalty" not in captured["body"]["generationConfig"]
+
+
+# ── thinkingConfig translation ────────────────────────────────────────
+
+
+def test_gemini25_flash_thinking_disabled_sets_budget_zero(monkeypatch):
+    """Gemini 2.5 Flash still uses thinkingBudget; 0 = off."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash",
+        enable_thinking = False,
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc == {"thinkingBudget": 0}, tc
+
+
+def test_gemini3_flash_thinking_disabled_uses_minimal_level(monkeypatch):
+    """Gemini 3 Flash migrated to thinkingLevel; "off" maps to minimal
+    (Gemini 3 cannot turn thinking fully off)."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3.5-flash",
+        enable_thinking = False,
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc == {"thinkingLevel": "minimal"}, tc
+
+
+def test_gemini25_pro_thinking_disabled_uses_small_budget(monkeypatch):
+    """Gemini 2.5 Pro 400s on thinkingBudget=0 ("only works in thinking
+    mode"); coerce to a small positive budget."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-pro",
+        enable_thinking = False,
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc is not None and tc.get("thinkingBudget", 0) > 0, tc
+
+
+def test_gemini3_pro_thinking_disabled_uses_low_level(monkeypatch):
+    """Gemini 3 Pro uses thinkingLevel and rejects 'minimal' (Pro tier),
+    so 'off' coerces to 'low' (lowest the API accepts)."""
+    for model in (
+        "gemini-3.1-pro-preview",
+        "gemini-3-pro-preview",
+        "gemini-3.5-pro",
+        "gemini-pro-latest",
+    ):
+        captured = _capture_body(
+            monkeypatch,
+            model = model,
+            enable_thinking = False,
+        )
+        tc = captured["body"]["generationConfig"].get("thinkingConfig")
+        assert tc == {"thinkingLevel": "low"}, (model, tc)
+
+
+def test_gemini25_flash_effort_levels_map_to_budgets(monkeypatch):
+    """Gemini 2.5 Flash retains the integer thinkingBudget ladder."""
+    cases = {
+        "minimal": 512,
+        "low": 2048,
+        "medium": 8192,
+        "high": 24576,
+        "max": -1,
+        "xhigh": -1,
+    }
+    for effort, expected in cases.items():
+        captured = _capture_body(
+            monkeypatch,
+            model = "gemini-2.5-flash",
+            reasoning_effort = effort,
+        )
+        tc = captured["body"]["generationConfig"].get("thinkingConfig")
+        assert tc == {"thinkingBudget": expected}, (effort, tc)
+
+
+def test_gemini3_flash_effort_levels_map_to_thinking_level(monkeypatch):
+    """Gemini 3 Flash thinkingLevel ladder: minimal/low/medium/high."""
+    cases = {
+        "minimal": "minimal",
+        "low": "low",
+        "medium": "medium",
+        "high": "high",
+        "max": "high",
+    }
+    for effort, expected in cases.items():
+        captured = _capture_body(
+            monkeypatch,
+            model = "gemini-3.5-flash",
+            reasoning_effort = effort,
+        )
+        tc = captured["body"]["generationConfig"].get("thinkingConfig")
+        assert tc == {"thinkingLevel": expected}, (effort, tc)
+
+
+def test_gemini3_pro_passes_medium_through(monkeypatch):
+    """Gemini 3.1+ Pro accepts thinkingLevel="medium" per
+    https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-pro;
+    forward as-is (medium is the documented mid-tier on Gemini 3.1)."""
+    for model in (
+        "gemini-3.1-pro-preview",
+        "gemini-pro-latest",
+    ):
+        captured = _capture_body(
+            monkeypatch,
+            model = model,
+            reasoning_effort = "medium",
+        )
+        tc = captured["body"]["generationConfig"].get("thinkingConfig")
+        assert tc == {"thinkingLevel": "medium"}, (model, tc)
+
+
+def test_gemini3_pro_minimal_effort_coerces_to_low(monkeypatch):
+    """Gemini 3 Pro rejects thinkingLevel="minimal"; coerce to "low"."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3.1-pro-preview",
+        reasoning_effort = "minimal",
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc == {"thinkingLevel": "low"}, tc
+
+
+def test_gemini3_flash_effort_none_maps_to_minimal(monkeypatch):
+    """reasoning_effort='none' on Gemini 3 Flash -> thinkingLevel=minimal."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3.5-flash",
+        reasoning_effort = "none",
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc == {"thinkingLevel": "minimal"}, tc
+
+
+def test_thinking_default_omits_thinking_config(monkeypatch):
+    """When neither knob is supplied, thinkingConfig is omitted entirely
+    (Google's server-side default applies)."""
+    captured = _capture_body(monkeypatch, model = "gemini-3.5-flash")
+    gc = captured["body"]["generationConfig"]
+    assert "thinkingConfig" not in gc, gc
+
+
+def test_nano_banana_alias_routes_through_image_modalities(monkeypatch):
+    """`nano-banana-pro-preview` is an alias for the Pro image model and
+    must set responseModalities=[TEXT,IMAGE] when the Images pill is on
+    (enabled_tools includes "image_generation")."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "nano-banana-pro-preview",
+        enabled_tools = ["image_generation"],
+    )
+    gc = captured["body"]["generationConfig"]
+    assert gc.get("responseModalities") == ["TEXT", "IMAGE"], gc
+
+
+def test_image_capable_model_without_image_pill_stays_text_only(monkeypatch):
+    """When the Images pill is off (enabled_tools has no
+    image_generation), an image-capable model id (gemini-2.5-flash-image)
+    must force responseModalities=["TEXT"]. Google's image models
+    default to text+image when responseModalities is omitted, so
+    omitting it would silently bill image output the UI says is
+    disabled."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = [],
+    )
+    gc = captured["body"]["generationConfig"]
+    assert gc.get("responseModalities") == ["TEXT"], gc
+
+
+def test_image_models_skip_thinking_config(monkeypatch):
+    """Image-tier ids do not benefit from a visible thinking knob and
+    must NOT forward thinkingConfig even when stale UI state still
+    sends `reasoning_effort` or `enable_thinking=False`."""
+    for model in (
+        "gemini-2.5-flash-image",
+        "gemini-3.1-flash-image-preview",
+        "gemini-3-pro-image-preview",
+        "nano-banana-pro-preview",
+    ):
+        captured = _capture_body(
+            monkeypatch,
+            model = model,
+            reasoning_effort = "high",
+            enable_thinking = False,
+            enabled_tools = ["image_generation"],
+        )
+        gc = captured["body"]["generationConfig"]
+        assert "thinkingConfig" not in gc, (model, gc)
+
+
+def test_image_models_drop_code_execution(monkeypatch):
+    """All image-tier ids reject `tools: [{codeExecution: {}}]`; drop
+    silently. (Gemini 3 image models DO accept googleSearch -- see
+    test_gemini3_image_models_allow_google_search; older image models
+    drop everything.)"""
+    for model in (
+        "gemini-2.5-flash-image",
+        "gemini-3.1-flash-image-preview",
+        "gemini-3-pro-image-preview",
+        "nano-banana-pro-preview",
+    ):
+        captured = _capture_body(
+            monkeypatch,
+            model = model,
+            enabled_tools = ["image_generation", "code_execution"],
+        )
+        tools_arr = captured["body"].get("tools") or []
+        names = [list(t.keys())[0] for t in tools_arr]
+        assert "codeExecution" not in names, (model, tools_arr)
+
+
+def test_gemini_35_pro_uses_thinking_level(monkeypatch):
+    """`gemini-3.5-pro` is part of the Gemini 3 family and uses
+    thinkingLevel (not thinkingBudget). "Off" maps to "low" because Pro
+    tier rejects "minimal"."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3.5-pro",
+        enable_thinking = False,
+    )
+    tc = captured["body"]["generationConfig"].get("thinkingConfig")
+    assert tc == {"thinkingLevel": "low"}, tc
+
+
+def test_gemini3_image_models_allow_google_search(monkeypatch):
+    """Google documents Search grounding on the Gemini 3 image family
+    (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview,
+    nano-banana-pro). codeExecution stays blocked on image mode."""
+    for model in (
+        "gemini-3-pro-image-preview",
+        "gemini-3.1-flash-image-preview",
+        "nano-banana-pro-preview",
+    ):
+        captured = _capture_body(
+            monkeypatch,
+            model = model,
+            enabled_tools = ["image_generation", "web_search", "code_execution"],
+        )
+        tools_arr = captured["body"].get("tools") or []
+        names = [list(t.keys())[0] for t in tools_arr]
+        assert "googleSearch" in names, (model, tools_arr)
+        assert "codeExecution" not in names, (model, tools_arr)
+
+
+def test_legacy_image_models_block_google_search(monkeypatch):
+    """Older Gemini image ids (gemini-2.5-flash-image) still 400 on
+    `tools: [{googleSearch: {}}]`; backend keeps stripping it."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation", "web_search", "code_execution"],
+    )
+    assert "tools" not in captured["body"], captured["body"].get("tools")
+
+
+def test_legacy_openai_base_url_normalized(monkeypatch):
+    """Saved Gemini providers carrying the legacy `/v1beta/openai` base
+    (from the pre-PR OpenAI-compat plumbing) now point at the native
+    endpoint without the user re-saving the connection."""
+    client = ExternalProviderClient(
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta/openai",
+        api_key = "AIza-test-key",
+    )
+    assert client.base_url == "https://generativelanguage.googleapis.com/v1beta"
+
+
+def test_finish_reason_swaps_to_tool_calls_when_function_call_emitted(monkeypatch):
+    """Gemini emits finishReason="STOP" even for pure functionCall turns;
+    surface as `tool_calls` so OAI clients trigger tool execution."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {"functionCall": {"name": "lookup", "args": {"k": "v"}}}
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ]
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    finish_chunks = [
+        c for c in chunks if c.get("choices", [{}])[0].get("finish_reason") is not None
+    ]
+    assert finish_chunks, chunks
+    assert finish_chunks[-1]["choices"][0]["finish_reason"] == "tool_calls", chunks
+
+
+def test_thought_signature_round_trips_into_gemini_function_call(monkeypatch):
+    """An assistant tool_call carrying `extra_content.google.thought_signature`
+    must echo the value back as a sibling of the Gemini functionCall part."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "lookup x"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_0",
+                        "type": "function",
+                        "function": {"name": "lookup", "arguments": "{}"},
+                        "extra_content": {"google": {"thought_signature": "SIG-ABC"}},
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_0",
+                "name": "lookup",
+                "content": "{}",
+            },
+        ],
+    )
+    contents = captured["body"]["contents"]
+    fc_turn = next((c for c in contents if c["role"] == "model"), None)
+    assert fc_turn is not None, contents
+    fc_part = next(
+        (p for p in fc_turn["parts"] if "functionCall" in p),
+        None,
+    )
+    assert fc_part is not None, fc_turn
+    assert fc_part.get("thoughtSignature") == "SIG-ABC", fc_part
+
+
+def test_thought_signature_emitted_in_tool_call_delta(monkeypatch):
+    """A Gemini functionCall part with `thoughtSignature` must surface
+    that signature on the outbound OpenAI tool_calls delta via
+    `extra_content.google.thought_signature`."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "functionCall": {
+                                    "name": "lookup",
+                                    "args": {"k": "v"},
+                                    "id": "call_xyz",
+                                },
+                                "thoughtSignature": "SIG-FROM-GEMINI",
+                            }
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ]
+        }
+    ]
+    chunks = _parse_chunks(_collect(monkeypatch, sse))
+    deltas = [
+        tc
+        for c in chunks
+        for tc in (c.get("choices", [{}])[0].get("delta", {}) or {}).get(
+            "tool_calls", []
+        )
+    ]
+    assert deltas, chunks
+    sig = deltas[0].get("extra_content", {}).get("google", {}).get("thought_signature")
+    assert sig == "SIG-FROM-GEMINI", deltas
+
+
+def test_image_models_suppress_phantom_web_search_card(monkeypatch):
+    """When the image guard filters googleSearch out of the outbound
+    request, the inbound stream must NOT emit web_search tool_start /
+    tool_end (otherwise the UI shows a misleading 'Search complete'
+    card on a turn where Gemini never actually searched)."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {"role": "model", "parts": [{"text": "drawn"}]},
+                    "finishReason": "STOP",
+                }
+            ]
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation", "web_search", "code_execution"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_evs = [
+        ev
+        for c in chunks
+        for ev in [c.get("_toolEvent")]
+        if isinstance(ev, dict) and ev.get("tool_name") == "web_search"
+    ]
+    assert tool_evs == [], tool_evs
+
+
+def test_image_generation_tool_on_image_model_drops_text_tools(monkeypatch):
+    """`enabled_tools=["image_generation", "web_search", "code_execution"]`
+    on a Gemini IMAGE model flips responseModalities to TEXT+IMAGE; in
+    that mode codeExecution must NOT be forwarded (Gemini rejects text
+    code tools alongside image responseModalities). Older image
+    families also drop googleSearch."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = [
+            "image_generation",
+            "web_search",
+            "code_execution",
+        ],
+    )
+    assert "tools" not in captured["body"], captured["body"]
+    assert captured["body"]["generationConfig"].get("responseModalities") == [
+        "TEXT",
+        "IMAGE",
+    ]
+
+
+def test_prompt_feedback_block_reason_surfaces_as_error(monkeypatch):
+    """`promptFeedback.blockReason` with zero candidates must produce
+    an error chunk, not a silent empty assistant reply."""
+    sse = [
+        {
+            "promptFeedback": {"blockReason": "SAFETY"},
+        }
+    ]
+    chunks = _parse_chunks(_collect(monkeypatch, sse))
+    error_chunks = [c for c in chunks if "error" in c]
+    assert error_chunks, chunks
+    assert "SAFETY" in (
+        error_chunks[0].get("error", {}).get("message") or ""
+    ), error_chunks
+
+
+def test_usage_chunk_includes_thoughts_tokens(monkeypatch):
+    """`thoughtsTokenCount` is the hidden-reasoning slice of output;
+    roll it into `output_tokens` AND surface it on
+    `output_tokens_details.reasoning_tokens` so total_tokens reflects
+    the full billable spend."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {"role": "model", "parts": [{"text": "ok"}]},
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 10,
+                "candidatesTokenCount": 5,
+                "thoughtsTokenCount": 20,
+                "totalTokenCount": 35,
+            },
+        }
+    ]
+    chunks = _parse_chunks(_collect(monkeypatch, sse))
+    usage_chunk = next((c for c in chunks if isinstance(c.get("usage"), dict)), None)
+    assert usage_chunk is not None, chunks
+    usage = usage_chunk["usage"]
+    assert usage.get("prompt_tokens") == 10, usage
+    # candidates 5 + thoughts 20 = 25 output tokens; total = 35.
+    assert usage.get("completion_tokens") == 25, usage
+    assert usage.get("total_tokens") == 35, usage
+
+
+# ── web_search forwarded as googleSearch tool ────────────────────────
+
+
+def test_web_search_forwarded_as_google_search_tool(monkeypatch):
+    captured = _capture_body(
+        monkeypatch,
+        enabled_tools = ["web_search"],
+    )
+    tools = captured["body"].get("tools") or []
+    assert {"googleSearch": {}} in tools, tools
+
+
+def test_code_execution_forwarded_as_code_execution_tool(monkeypatch):
+    captured = _capture_body(
+        monkeypatch,
+        enabled_tools = ["code_execution"],
+    )
+    tools = captured["body"].get("tools") or []
+    assert {"codeExecution": {}} in tools, tools
+
+
+def test_omitted_tools_leaves_body_untouched(monkeypatch):
+    captured = _capture_body(monkeypatch, enabled_tools = [])
+    assert "tools" not in captured["body"], captured["body"]
+
+
+# ── prompt caching passthrough ───────────────────────────────────────
+
+
+def test_cached_content_pass_through(monkeypatch):
+    """A string cache id on enable_prompt_caching is forwarded verbatim."""
+    cache_name = "cachedContents/abc123"
+    captured = _capture_body(
+        monkeypatch,
+        enable_prompt_caching = cache_name,
+    )
+    assert captured["body"].get("cachedContent") == cache_name
+
+
+def test_boolean_caching_does_not_set_cached_content(monkeypatch):
+    """Studio's existing True/False signals shouldn't fabricate a cache id."""
+    captured = _capture_body(monkeypatch, enable_prompt_caching = True)
+    assert "cachedContent" not in captured["body"]
+
+
+# ── image generation: request modalities + response translation ──────
+
+
+def test_image_model_sets_response_modalities(monkeypatch):
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation"],
+    )
+    assert captured["body"]["generationConfig"]["responseModalities"] == [
+        "TEXT",
+        "IMAGE",
+    ]
+
+
+def test_image_generation_tool_sets_response_modalities_on_image_model(monkeypatch):
+    """`enabled_tools=["image_generation"]` flips responseModalities
+    only when the selected model is image-capable; otherwise the
+    request stays plain text (text-only models 400 on
+    responseModalities)."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation"],
+    )
+    assert captured["body"]["generationConfig"]["responseModalities"] == [
+        "TEXT",
+        "IMAGE",
+    ]
+
+
+def test_image_response_emits_image_b64_tool_event(monkeypatch):
+    """`inlineData` parts become a tool_end with image_b64 + image_mime."""
+    fake_b64 = base64.b64encode(b"PNG-BYTES").decode()
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "inlineData": {
+                                    "mimeType": "image/png",
+                                    "data": fake_b64,
+                                }
+                            }
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 5,
+                "candidatesTokenCount": 0,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        model = "gemini-2.5-flash-image",
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    starts = [e for e in tool_events if e.get("type") == "tool_start"]
+    ends = [e for e in tool_events if e.get("type") == "tool_end"]
+    image_starts = [e for e in starts if e.get("tool_name") == "image_generation"]
+    image_ends = [e for e in ends if e.get("image_b64")]
+    assert len(image_starts) == 1, tool_events
+    assert len(image_ends) == 1, tool_events
+    assert image_ends[0]["image_b64"] == fake_b64
+    assert image_ends[0]["image_mime"] == "image/png"
+
+
+# ── function calling round-trips both directions ─────────────────────
+
+
+def test_function_call_response_translates_to_tool_calls_delta(monkeypatch):
+    """Gemini `functionCall` parts become OpenAI `tool_calls` delta chunks."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "functionCall": {
+                                    "name": "get_weather",
+                                    "args": {"location": "Paris"},
+                                }
+                            }
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 12,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    tool_call_chunks = [
+        c
+        for c in chunks
+        if "_toolEvent" not in c
+        and any(
+            (isinstance(ch.get("delta"), dict) and "tool_calls" in ch["delta"])
+            for ch in c.get("choices", [])
+        )
+    ]
+    assert len(tool_call_chunks) == 1, chunks
+    tc = tool_call_chunks[0]["choices"][0]["delta"]["tool_calls"][0]
+    assert tc["function"]["name"] == "get_weather"
+    args = json.loads(tc["function"]["arguments"])
+    assert args == {"location": "Paris"}
+
+
+def test_tool_message_translates_to_function_response_part(monkeypatch):
+    """role=tool follow-ups are rewritten to functionResponse parts."""
+    messages = [
+        {"role": "user", "content": "Weather?"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "arguments": json.dumps({"location": "Paris"}),
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "name": "get_weather",
+            "content": json.dumps({"temp_c": 18, "summary": "Sunny"}),
+        },
+    ]
+    captured = _capture_body(monkeypatch, messages = messages)
+    contents = captured["body"]["contents"]
+    # Last turn must be a functionResponse part (Gemini wraps it as a
+    # role=user turn carrying the result).
+    last = contents[-1]
+    assert last["role"] == "user", last
+    fr = last["parts"][0].get("functionResponse")
+    assert fr is not None, last
+    assert fr["name"] == "get_weather"
+    assert fr["response"] == {"temp_c": 18, "summary": "Sunny"}
+    # And the assistant turn carries the original functionCall so the
+    # model sees the round-trip context.
+    assistant_turn = [c for c in contents if c["role"] == "model"][0]
+    fc_part = next(
+        (p for p in assistant_turn["parts"] if "functionCall" in p),
+        None,
+    )
+    assert fc_part is not None, assistant_turn
+    assert fc_part["functionCall"]["name"] == "get_weather"
+    assert fc_part["functionCall"]["args"] == {"location": "Paris"}
+
+
+def test_parallel_function_calls_get_distinct_tool_call_indices(monkeypatch):
+    """Each emitted functionCall in one assistant turn needs its own
+    tool_calls[*].index. Hardcoding index=0 collapses parallel calls
+    onto a single slot in OpenAI-style reassemblers."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "functionCall": {
+                                    "id": "call_alpha",
+                                    "name": "search",
+                                    "args": {"q": "alpha"},
+                                }
+                            },
+                            {
+                                "functionCall": {
+                                    "id": "call_beta",
+                                    "name": "search",
+                                    "args": {"q": "beta"},
+                                }
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 8,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    tool_call_chunks = [
+        c
+        for c in chunks
+        if "_toolEvent" not in c
+        and any(
+            (isinstance(ch.get("delta"), dict) and "tool_calls" in ch["delta"])
+            for ch in c.get("choices", [])
+        )
+    ]
+    assert len(tool_call_chunks) == 2, tool_call_chunks
+    indices = [
+        c["choices"][0]["delta"]["tool_calls"][0]["index"] for c in tool_call_chunks
+    ]
+    assert indices == [0, 1], indices
+
+
+def test_function_call_ids_forwarded_into_gemini_function_call_part(monkeypatch):
+    """OpenAI tool_call id rides functionCall.id so parallel calls disambiguate."""
+    messages = [
+        {"role": "user", "content": "x"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": "call_alpha",
+                    "type": "function",
+                    "function": {
+                        "name": "search",
+                        "arguments": json.dumps({"q": "a"}),
+                    },
+                },
+                {
+                    "id": "call_beta",
+                    "type": "function",
+                    "function": {
+                        "name": "search",
+                        "arguments": json.dumps({"q": "b"}),
+                    },
+                },
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_alpha",
+            "content": json.dumps({"hits": ["A"]}),
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_beta",
+            "content": json.dumps({"hits": ["B"]}),
+        },
+    ]
+    captured = _capture_body(monkeypatch, messages = messages)
+    contents = captured["body"]["contents"]
+    assistant_parts = next(c for c in contents if c["role"] == "model")["parts"]
+    call_ids = [p["functionCall"]["id"] for p in assistant_parts if "functionCall" in p]
+    assert call_ids == ["call_alpha", "call_beta"], assistant_parts
+    response_ids = [
+        p["functionResponse"]["id"]
+        for c in contents
+        for p in c["parts"]
+        if "functionResponse" in p
+    ]
+    assert response_ids == ["call_alpha", "call_beta"], contents
+
+
+def test_parse_gemini_models_translates_native_catalog():
+    """Gemini's native /v1beta/models payload becomes OpenAI-shape entries."""
+    payload = {
+        "models": [
+            {
+                "name": "models/gemini-2.5-flash",
+                "baseModelId": "gemini-2.5-flash",
+                "displayName": "Gemini 2.5 Flash",
+                "supportedGenerationMethods": [
+                    "generateContent",
+                    "streamGenerateContent",
+                ],
+            },
+            {
+                "name": "models/embedding-001",
+                "supportedGenerationMethods": ["embedContent"],
+            },
+            {
+                "name": "models/gemini-2.5-pro",
+            },
+        ]
+    }
+    out = ExternalProviderClient._parse_gemini_models(payload)
+    ids = [m["id"] for m in out]
+    assert "gemini-2.5-flash" in ids
+    assert "gemini-2.5-pro" in ids
+    assert "embedding-001" not in ids
+    flash = next(m for m in out if m["id"] == "gemini-2.5-flash")
+    assert flash["display_name"] == "Gemini 2.5 Flash"
+    assert flash["owned_by"] == "google"
+
+
+def test_code_execution_parts_translate_to_code_execution_tool_events(monkeypatch):
+    """executableCode + codeExecutionResult parts emit code_execution events."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "executableCode": {
+                                    "language": "PYTHON",
+                                    "code": "print(2+2)",
+                                }
+                            },
+                            {
+                                "codeExecutionResult": {
+                                    "outcome": "OUTCOME_OK",
+                                    "output": "4\n",
+                                }
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 8,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse, enabled_tools = ["code_execution"])
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    code_starts = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_start" and e.get("tool_name") == "code_execution"
+    ]
+    code_ends = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_end" and "4" in str(e.get("result", ""))
+    ]
+    assert len(code_starts) == 1, tool_events
+    assert code_starts[0]["arguments"]["code"] == "print(2+2)"
+    assert code_starts[0]["arguments"]["language"] == "python"
+    assert len(code_ends) == 1, tool_events
+    # tool_start and tool_end must share the same tool_call_id so the
+    # frontend pairs them onto a single CodeExecutionToolUI block.
+    assert code_starts[0]["tool_call_id"] == code_ends[0]["tool_call_id"]
+
+
+def test_code_execution_failure_outcome_surfaces_in_result(monkeypatch):
+    """OUTCOME_FAILED is prefixed onto the result text so the UI shows it."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "executableCode": {
+                                    "language": "PYTHON",
+                                    "code": "1/0",
+                                }
+                            },
+                            {
+                                "codeExecutionResult": {
+                                    "outcome": "OUTCOME_FAILED",
+                                    "output": "ZeroDivisionError",
+                                }
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 5,
+                "candidatesTokenCount": 2,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse, enabled_tools = ["code_execution"])
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    result_text = next(
+        (e["result"] for e in tool_events if e.get("type") == "tool_end"),
+        "",
+    )
+    assert "OUTCOME_FAILED" in result_text
+    assert "ZeroDivisionError" in result_text
+
+
+def test_tool_message_recovers_name_from_tool_call_id(monkeypatch):
+    """When name is omitted, recover it from the matching tool_call_id."""
+    messages = [
+        {"role": "user", "content": "Weather?"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": "call_xyz",
+                    "type": "function",
+                    "function": {
+                        "name": "get_weather",
+                        "arguments": json.dumps({"location": "Paris"}),
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_xyz",
+            "content": json.dumps({"temp_c": 18}),
+        },
+    ]
+    captured = _capture_body(monkeypatch, messages = messages)
+    contents = captured["body"]["contents"]
+    last = contents[-1]
+    fr = last["parts"][0].get("functionResponse")
+    assert fr is not None, last
+    assert (
+        fr["name"] == "get_weather"
+    ), "name should fall back to the prior tool_call's function name"
+
+
+# ── usage chunk surfaces promptTokenCount / candidatesTokenCount ─────
+
+
+def test_usage_chunk_translates_gemini_token_counts(monkeypatch):
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [{"text": "ok"}],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 1234,
+                "candidatesTokenCount": 56,
+                "cachedContentTokenCount": 1000,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    usage_chunks = [c for c in chunks if c.get("choices") == [] and "usage" in c]
+    assert len(usage_chunks) == 1, chunks
+    usage = usage_chunks[0]["usage"]
+    assert usage["prompt_tokens"] == 1234
+    assert usage["completion_tokens"] == 56
+    assert usage["total_tokens"] == 1290
+    assert usage["prompt_tokens_details"]["cached_tokens"] == 1000
+
+
+# ── multimodal: vision image -> inlineData ───────────────────────────
+
+
+def test_vision_data_url_translates_to_inline_data(monkeypatch):
+    fake = base64.b64encode(b"JPGBYTES").decode()
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "What is this?"},
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": f"data:image/jpeg;base64,{fake}",
+                    },
+                },
+            ],
+        }
+    ]
+    captured = _capture_body(monkeypatch, messages = messages)
+    parts = captured["body"]["contents"][0]["parts"]
+    inline_parts = [p for p in parts if "inlineData" in p]
+    assert len(inline_parts) == 1, parts
+    assert inline_parts[0]["inlineData"] == {
+        "mimeType": "image/jpeg",
+        "data": fake,
+    }
+
+
+# ── finish reason mapping ────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "gemini_reason, openai_reason",
+    [
+        ("STOP", "stop"),
+        ("MAX_TOKENS", "length"),
+        ("SAFETY", "content_filter"),
+        ("PROHIBITED_CONTENT", "content_filter"),
+    ],
+)
+def test_finish_reason_translation(monkeypatch, gemini_reason, openai_reason):
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [{"text": "x"}],
+                    },
+                    "finishReason": gemini_reason,
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 1,
+                "candidatesTokenCount": 1,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    finish_chunks = [
+        c for c in chunks if any(ch.get("finish_reason") for ch in c.get("choices", []))
+    ]
+    assert any(
+        ch["choices"][0]["finish_reason"] == openai_reason for ch in finish_chunks
+    ), finish_chunks
+
+
+# ── grounding citations surface as web_search tool_end ───────────────
+
+
+def test_grounding_metadata_surfaces_as_tool_end_citations(monkeypatch):
+    """`groundingMetadata.groundingChunks[].web` -> tool_end result block."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [{"text": "Answer with sources."}],
+                    },
+                    "groundingMetadata": {
+                        "groundingChunks": [
+                            {
+                                "web": {
+                                    "uri": "https://example.com/a",
+                                    "title": "Example A",
+                                }
+                            },
+                            {
+                                "web": {
+                                    "uri": "https://example.com/b",
+                                    "title": "Example B",
+                                }
+                            },
+                        ]
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 7,
+                "candidatesTokenCount": 3,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        enabled_tools = ["web_search"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    web_search_ends = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_end" and e.get("tool_call_id") == "gemini_web_search"
+    ]
+    assert len(web_search_ends) == 1, tool_events
+    result = web_search_ends[0]["result"]
+    assert "https://example.com/a" in result
+    assert "https://example.com/b" in result
+    assert "Example A" in result
+    assert "Example B" in result
+
+
+# ── round 3 review follow-ups ─────────────────────────────────────────
+
+
+def test_custom_gemini_proxy_base_url_not_rewritten():
+    """Only the Google-hosted /v1beta/openai base is normalized; a
+    custom gateway whose path ends in /openai must be left alone."""
+    client = ExternalProviderClient(
+        provider_type = "gemini",
+        base_url = "https://proxy.example.com/team/openai",
+        api_key = "AIza-test-key",
+    )
+    assert client.base_url == "https://proxy.example.com/team/openai"
+
+
+def test_custom_gemini_proxy_uses_openai_dispatch():
+    """Any non-Google Gemini base (LiteLLM, custom OpenAI-compat
+    routers) must route through the OpenAI-compatible forwarder, not
+    the native translator. Auth uses Authorization: Bearer ..., not
+    x-goog-api-key."""
+    for base in (
+        "https://proxy.example.com/team/openai",
+        "https://proxy.example.com/v1",
+        "https://litellm.internal.example/v1",
+    ):
+        client = ExternalProviderClient(
+            provider_type = "gemini",
+            base_url = base,
+            api_key = "AIza-test-key",
+        )
+        assert client._is_openai_compatible() is True, base
+        headers = client._auth_headers()
+        assert "x-goog-api-key" not in {k.lower() for k in headers}, (
+            base,
+            headers,
+        )
+        assert headers["Authorization"] == "Bearer AIza-test-key", (
+            base,
+            headers,
+        )
+
+
+def test_google_hosted_gemini_still_uses_native_dispatch():
+    """Google-hosted Gemini keeps native dispatch + x-goog-api-key auth."""
+    client = ExternalProviderClient(
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+        api_key = "AIza-test-key",
+    )
+    assert client._is_openai_compatible() is False
+    headers = client._auth_headers()
+    assert headers.get("x-goog-api-key") == "AIza-test-key", headers
+
+
+def test_invalid_gemini_model_id_rejected_before_request(monkeypatch):
+    """Path-traversal model ids must be rejected before the URL is
+    interpolated so the configured API key isn't sent to unintended
+    Gemini endpoints."""
+
+    captured: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.append(request)
+        return httpx.Response(
+            200,
+            content = _gemini_sse([]),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    out: list[str] = []
+
+    async def run():
+        client = _make_gemini_client()
+        async for line in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "../cachedContents/leak",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+        ):
+            out.append(line)
+        await client.close()
+
+    _drive(run())
+    # No outbound request should have been issued.
+    assert captured == [], captured
+    error_lines = [line for line in out if '"error"' in line]
+    assert error_lines, out
+
+
+def test_top_k_omitted_when_not_explicit_default_for_gemini(monkeypatch):
+    """top_k=None means "use provider default"; helper must not emit
+    `topK` in generationConfig when the caller didn't pass it."""
+    captured = _capture_body(monkeypatch, top_k = None)
+    assert "topK" not in captured["body"]["generationConfig"], captured["body"]
+
+
+def test_text_model_image_generation_tool_silently_dropped(monkeypatch):
+    """A stale `enabled_tools=["image_generation"]` on a text-only
+    Gemini model (e.g. gemini-2.5-flash) must NOT switch the request
+    into image mode -- Google's API 400s on responseModalities for
+    text models."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash",
+        enabled_tools = ["image_generation"],
+    )
+    gc = captured["body"]["generationConfig"]
+    assert "responseModalities" not in gc, gc
+
+
+def test_empty_text_part_with_thought_signature_emits_extra_content(
+    monkeypatch,
+):
+    """Gemini 3 can ship a content-free fragment whose only payload is
+    `thoughtSignature`. The translator must still surface that signature
+    on a delta.extra_content envelope so the next turn can replay it."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {"text": "answer"},
+                            {"thoughtSignature": "SIG-FINAL"},
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 2,
+                "candidatesTokenCount": 1,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    extra_carriers = [
+        c
+        for c in chunks
+        if c.get("choices")
+        and c["choices"][0]["delta"].get("extra_content")
+        == {"google": {"thought_signature": "SIG-FINAL"}}
+    ]
+    assert extra_carriers, chunks
+
+
+def test_enable_prompt_caching_false_string_coerces_to_bool():
+    """Pre-PR the field was Optional[bool]; widening to Union[bool,str]
+    must preserve historical coercion so callers sending `"false"`
+    still opt out of caching."""
+    from models.inference import ChatCompletionRequest
+
+    msg = {"role": "user", "content": "hi"}
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [msg],
+            "enable_prompt_caching": "false",
+        }
+    )
+    assert req.enable_prompt_caching is False, req.enable_prompt_caching
+
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [msg],
+            "enable_prompt_caching": "true",
+        }
+    )
+    assert req.enable_prompt_caching is True
+
+    # An actual cache resource name passes through untouched.
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [msg],
+            "enable_prompt_caching": "cachedContents/abc123",
+        }
+    )
+    assert req.enable_prompt_caching == "cachedContents/abc123"
+
+
+def test_legacy_google_openai_base_url_is_rewritten():
+    """The Google-hosted /v1beta/openai legacy base IS still rewritten."""
+    client = ExternalProviderClient(
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta/openai",
+        api_key = "AIza-test-key",
+    )
+    assert client.base_url == "https://generativelanguage.googleapis.com/v1beta"
+
+
+def test_remote_image_url_downloads_and_inlines_as_base64(monkeypatch):
+    """Round 14: arbitrary public HTTPS image URLs cannot be sent as
+    Gemini fileData (that path is reserved for Files API URIs and
+    YouTube). The translator must fetch the bytes server-side and
+    inline them as base64 inlineData."""
+    image_bytes = b"FAKEPNGBYTES"
+
+    async def fake_fetch(url, fallback_mime, max_bytes = None):
+        assert url == "https://cdn.example.com/diagram.png"
+        return ("image/png", base64.b64encode(image_bytes).decode("ascii"))
+
+    monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch)
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "what is this?"},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": "https://cdn.example.com/diagram.png",
+                        },
+                    },
+                ],
+            }
+        ],
+    )
+    parts = captured["body"]["contents"][-1]["parts"]
+    inline = next((p for p in parts if "inlineData" in p), None)
+    assert inline is not None, parts
+    assert inline["inlineData"]["mimeType"] == "image/png"
+    assert inline["inlineData"]["data"] == base64.b64encode(image_bytes).decode()
+    assert not any("fileData" in p for p in parts), parts
+
+
+def test_remote_image_url_dropped_when_fetch_returns_none(monkeypatch):
+    """Round 15: if the SSRF guard rejects the URL (private host,
+    non-https, oversize, non-image), the helper returns None and the
+    image part is silently dropped instead of forwarding raw bytes
+    or a fileData fallback."""
+
+    async def fake_fetch_reject(url, fallback_mime, max_bytes = None):
+        return None
+
+    monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch_reject)
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "what is this?"},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": "http://10.0.0.5/private.png"},
+                    },
+                ],
+            }
+        ],
+    )
+    parts = captured["body"]["contents"][-1]["parts"]
+    assert not any("inlineData" in p for p in parts), parts
+    assert not any("fileData" in p for p in parts), parts
+
+
+def test_safe_fetch_image_rejects_non_https():
+    """SSRF guard: only https URLs may be fetched."""
+    res = asyncio.new_event_loop().run_until_complete(
+        ep_mod._safe_fetch_image_for_gemini("http://cdn.example.com/x.png", "image/png")
+    )
+    assert res is None
+
+
+def test_safe_fetch_image_rejects_loopback_ip_literal():
+    """SSRF guard: refuse loopback / private IP literals before any
+    network call."""
+    for url in (
+        "https://127.0.0.1/x.png",
+        "https://[::1]/x.png",
+        "https://169.254.169.254/latest/meta-data",
+        "https://10.0.0.5/x.png",
+        "https://192.168.1.1/x.png",
+    ):
+        res = asyncio.new_event_loop().run_until_complete(
+            ep_mod._safe_fetch_image_for_gemini(url, "image/png")
+        )
+        assert res is None, url
+
+
+def test_safe_fetch_image_rejects_resolved_private_host(monkeypatch):
+    """SSRF guard: if a hostname resolves to a private IP, refuse."""
+    import socket
+
+    def fake_getaddrinfo(host, *_args, **_kwargs):
+        return [(socket.AF_INET, None, None, "", ("10.0.0.5", 0))]
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+    res = asyncio.new_event_loop().run_until_complete(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://internal.example/x.png", "image/png"
+        )
+    )
+    assert res is None
+
+
+def test_youtube_and_files_api_uris_stay_as_file_data(monkeypatch):
+    """Round 14: YouTube URLs and generativelanguage.googleapis.com
+    Files API URIs are the documented `fileData.fileUri` paths and
+    must NOT be downloaded; arbitrary public URLs do get fetched."""
+    captured: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = _gemini_sse(
+                [
+                    {
+                        "candidates": [
+                            {
+                                "content": {
+                                    "role": "model",
+                                    "parts": [{"text": "ok"}],
+                                },
+                                "finishReason": "STOP",
+                            }
+                        ],
+                        "usageMetadata": {
+                            "promptTokenCount": 1,
+                            "candidatesTokenCount": 1,
+                        },
+                    }
+                ]
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = _make_gemini_client()
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "explain"},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": "https://www.youtube.com/watch?v=abc123",
+                            },
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": "https://generativelanguage.googleapis.com/v1beta/files/abc",
+                            },
+                        },
+                    ],
+                }
+            ],
+            model = "gemini-2.5-flash",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    parts = captured["body"]["contents"][-1]["parts"]
+    file_uris = [p["fileData"]["fileUri"] for p in parts if "fileData" in p]
+    assert "https://www.youtube.com/watch?v=abc123" in file_uris, parts
+    assert (
+        "https://generativelanguage.googleapis.com/v1beta/files/abc" in file_uris
+    ), parts
+
+
+def test_tool_use_prompt_tokens_added_to_input_tokens(monkeypatch):
+    """`toolUsePromptTokenCount` must roll into the OpenAI prompt
+    total -- otherwise tool turns silently undercount input tokens."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [{"text": "result"}],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 10,
+                "toolUsePromptTokenCount": 100,
+                "candidatesTokenCount": 5,
+                "thoughtsTokenCount": 2,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    usage_chunks = [c for c in chunks if c.get("usage")]
+    assert len(usage_chunks) == 1, chunks
+    usage = usage_chunks[0]["usage"]
+    assert usage["prompt_tokens"] == 110, usage
+    assert usage["completion_tokens"] == 7, usage
+    assert usage["total_tokens"] == 117, usage
+    assert usage["completion_tokens_details"]["reasoning_tokens"] == 2, usage
+
+
+def test_usage_chunk_reasoning_tokens_surfaced(monkeypatch):
+    """thoughtsTokenCount must surface as completion_tokens_details.
+    reasoning_tokens in the emitted OpenAI usage chunk."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [{"text": "ok"}],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 8,
+                "candidatesTokenCount": 5,
+                "thoughtsTokenCount": 20,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    usage_chunks = [c for c in chunks if c.get("usage")]
+    assert len(usage_chunks) == 1, chunks
+    usage = usage_chunks[0]["usage"]
+    assert usage["completion_tokens"] == 25, usage
+    assert usage["completion_tokens_details"]["reasoning_tokens"] == 20, usage
+
+
+def test_prompt_block_pairs_web_search_tool_end(monkeypatch):
+    """When `promptFeedback.blockReason` triggers after the synthetic
+    web_search tool_start, the helper must emit a matching tool_end so
+    the UI does not leave a "searching..." spinner stuck on screen."""
+    sse = [
+        {"promptFeedback": {"blockReason": "SAFETY"}},
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        enabled_tools = ["web_search"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    starts = [e for e in tool_events if e.get("type") == "tool_start"]
+    ends = [e for e in tool_events if e.get("type") == "tool_end"]
+    assert len(starts) == 1, tool_events
+    assert len(ends) == 1, tool_events
+    assert ends[0]["tool_call_id"] == "gemini_web_search"
+    assert "aborted" in ends[0]["result"]
+    error_chunks = [c for c in chunks if c.get("error")]
+    assert error_chunks, chunks
+
+
+def test_code_execution_tool_events_stow_native_part(monkeypatch):
+    """executableCode / codeExecutionResult must round-trip native ids
+    and thoughtSignature in google.native_part so follow-up turns can
+    replay Gemini's required history shape."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "executableCode": {
+                                    "id": "code_a",
+                                    "language": "PYTHON",
+                                    "code": "print(1+1)",
+                                },
+                                "thoughtSignature": "SIG-CODE",
+                            },
+                            {
+                                "codeExecutionResult": {
+                                    "id": "result_a",
+                                    "outcome": "OUTCOME_OK",
+                                    "output": "2\n",
+                                },
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 5,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        enabled_tools = ["code_execution"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    starts = [e for e in tool_events if e.get("type") == "tool_start"]
+    ends = [e for e in tool_events if e.get("type") == "tool_end"]
+    code_start = next(
+        (e for e in starts if e.get("tool_name") == "code_execution"),
+        None,
+    )
+    code_end = next(iter(ends), None)
+    assert code_start is not None, starts
+    assert code_start["tool_call_id"] == "code_a", code_start
+    native = code_start["arguments"]["google"]["native_part"]
+    # Round 21: native_part now uses an ordered `parts` list so per-part
+    # `thoughtSignature` survives a frontend merge of executableCode +
+    # codeExecutionResult into one tool-call card.
+    start_parts = native["parts"]
+    assert start_parts[0]["executableCode"]["id"] == "code_a"
+    assert start_parts[0]["thoughtSignature"] == "SIG-CODE"
+    assert code_end is not None, ends
+    assert code_end["tool_call_id"] == "code_a", code_end
+    native_end = code_end["google"]["native_part"]
+    end_parts = native_end["parts"]
+    assert end_parts[0]["codeExecutionResult"]["id"] == "result_a"
+
+
+def test_inline_image_tool_end_carries_thought_signature(monkeypatch):
+    """Inline image parts with thoughtSignature must persist it on the
+    emitted tool_end so Gemini 3 image editing can echo it back."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "inlineData": {
+                                    "mimeType": "image/png",
+                                    "data": base64.b64encode(b"PNG").decode(),
+                                },
+                                "thoughtSignature": "SIG-IMG",
+                            }
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 4,
+                "candidatesTokenCount": 1,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        model = "gemini-2.5-flash-image",
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    image_ends = [
+        e for e in tool_events if e.get("type") == "tool_end" and e.get("image_b64")
+    ]
+    assert image_ends, tool_events
+    assert image_ends[0]["google"]["thought_signature"] == "SIG-IMG"
+    # Multi-turn image edit must replay the original inlineData part with
+    # its thoughtSignature; the outbound translator reads
+    # google.native_part.parts[].inlineData, so stow it on the tool_end
+    # too. Round 21 changed native_part to an ordered parts list so a
+    # per-part signature stays attached to inlineData only.
+    native = image_ends[0]["google"]["native_part"]
+    image_parts = native["parts"]
+    assert image_parts[0]["inlineData"]["mimeType"] == "image/png"
+    assert image_parts[0]["inlineData"]["data"] == base64.b64encode(b"PNG").decode()
+    assert image_parts[0]["thoughtSignature"] == "SIG-IMG"
+
+
+def test_code_execution_plot_attaches_inline_image_native_part(monkeypatch):
+    """A code_execution turn that returns a matplotlib plot must stow
+    the plot's inlineData on the secondary tool_end so the follow-up
+    turn can replay the image alongside executableCode and
+    codeExecutionResult."""
+    plot_data = base64.b64encode(b"PLOT").decode()
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "executableCode": {
+                                    "id": "code_a",
+                                    "language": "PYTHON",
+                                    "code": "plt.plot([0,1])",
+                                },
+                            },
+                            {
+                                "codeExecutionResult": {
+                                    "id": "result_a",
+                                    "outcome": "OUTCOME_OK",
+                                    "output": "",
+                                },
+                            },
+                            {
+                                "inlineData": {
+                                    "mimeType": "image/png",
+                                    "data": plot_data,
+                                },
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 5,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        enabled_tools = ["code_execution"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    code_ends = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_end" and e.get("tool_call_id") == "code_a"
+    ]
+    # Two tool_end events on the same id: one for codeExecutionResult,
+    # one merging in the inlineData plot. The plot one must carry the
+    # native inlineData under google.native_part so the frontend
+    # tool_end merge union joins it with the prior executableCode and
+    # codeExecutionResult parts on the same card.
+    assert len(code_ends) == 2, code_ends
+    image_end = next(
+        (e for e in code_ends if "__IMAGES__:" in (e.get("result") or "")),
+        None,
+    )
+    assert image_end is not None, code_ends
+    native = image_end["google"]["native_part"]
+    plot_parts = native["parts"]
+    assert plot_parts[0]["inlineData"]["mimeType"] == "image/png"
+    assert plot_parts[0]["inlineData"]["data"] == plot_data
+
+
+def test_text_chunk_carries_thought_signature(monkeypatch):
+    """Text parts with thoughtSignature surface it on delta.extra_content
+    so frontend persistence can replay it on the follow-up turn."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "text": "hello",
+                                "thoughtSignature": "SIG-TEXT",
+                            }
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 2,
+                "candidatesTokenCount": 1,
+            },
+        }
+    ]
+    lines = _collect(monkeypatch, sse)
+    chunks = _parse_chunks(lines)
+    text_chunks = [
+        c
+        for c in chunks
+        if c.get("choices") and c["choices"][0]["delta"].get("content") == "hello"
+    ]
+    assert text_chunks, chunks
+    extra = text_chunks[0]["choices"][0]["delta"].get("extra_content")
+    assert extra == {"google": {"thought_signature": "SIG-TEXT"}}, text_chunks
+
+
+def test_openai_tools_translated_into_function_declarations(monkeypatch):
+    """Standard ChatCompletionRequest.tools must be forwarded into
+    Gemini's tools[].functionDeclarations envelope."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_weather",
+                    "description": "Look up the weather for a city.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "city": {"type": "string"},
+                        },
+                        "required": ["city"],
+                    },
+                },
+            }
+        ],
+        tool_choice = {"type": "function", "function": {"name": "get_weather"}},
+    )
+    tools_arr = captured["body"].get("tools") or []
+    fn_decls = [t for t in tools_arr if "functionDeclarations" in t]
+    assert fn_decls, captured["body"]
+    decls = fn_decls[0]["functionDeclarations"]
+    assert decls[0]["name"] == "get_weather"
+    assert decls[0]["parameters"]["properties"]["city"]["type"] == "string"
+    tool_config = captured["body"].get("toolConfig")
+    assert tool_config is not None, captured["body"]
+    fcc = tool_config["functionCallingConfig"]
+    assert fcc["mode"] == "ANY"
+    assert fcc["allowedFunctionNames"] == ["get_weather"]
+
+
+def test_tool_choice_auto_maps_to_function_calling_mode_auto(monkeypatch):
+    """tool_choice="auto" maps to toolConfig.functionCallingConfig.mode."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "noop", "parameters": {"type": "object"}},
+            }
+        ],
+        tool_choice = "auto",
+    )
+    fcc = captured["body"]["toolConfig"]["functionCallingConfig"]
+    assert fcc["mode"] == "AUTO"
+    assert "allowedFunctionNames" not in fcc
+
+
+def test_code_exec_inline_image_attaches_to_code_execution_card(monkeypatch):
+    """A codeExecution sandbox plot (matplotlib) ships as an inline
+    image part right after the codeExecutionResult. Instead of spawning
+    a separate empty image_generation card, attach to the same
+    code_execution tool_end via the `__IMAGES__:` marker the chat
+    adapter already understands."""
+    sse = [
+        {
+            "candidates": [
+                {
+                    "content": {
+                        "role": "model",
+                        "parts": [
+                            {
+                                "executableCode": {
+                                    "id": "code_plot",
+                                    "language": "PYTHON",
+                                    "code": "import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('out.png')",
+                                },
+                            },
+                            {
+                                "codeExecutionResult": {
+                                    "outcome": "OUTCOME_OK",
+                                    "output": "saved",
+                                },
+                            },
+                            {
+                                "inlineData": {
+                                    "mimeType": "image/png",
+                                    "data": base64.b64encode(b"PNGDATA").decode(),
+                                },
+                            },
+                        ],
+                    },
+                    "finishReason": "STOP",
+                }
+            ],
+            "usageMetadata": {
+                "promptTokenCount": 5,
+                "candidatesTokenCount": 4,
+            },
+        }
+    ]
+    lines = _collect(
+        monkeypatch,
+        sse,
+        enabled_tools = ["code_execution"],
+    )
+    chunks = _parse_chunks(lines)
+    tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
+    # No standalone image_generation card should have been emitted.
+    image_starts = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_start" and e.get("tool_name") == "image_generation"
+    ]
+    assert not image_starts, tool_events
+    # The code_execution tool_end should now carry the inline image
+    # via the `__IMAGES__:` marker.
+    code_ends = [
+        e
+        for e in tool_events
+        if e.get("type") == "tool_end" and e.get("tool_call_id") == "code_plot"
+    ]
+    assert code_ends, tool_events
+    final_result = code_ends[-1]["result"]
+    assert "__IMAGES__:" in final_result, code_ends
+    assert "data:image/png;base64," in final_result, code_ends
+
+
+def test_code_execution_tool_call_replays_native_executable_code(monkeypatch):
+    """An assistant tool_call with toolName=code_execution and
+    extra_content.google.native_part containing the originally-emitted
+    `executableCode` + `codeExecutionResult` must round-trip as native
+    Gemini parts (not a generic functionCall) on the next turn."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "compute 2+2"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "code_a",
+                        "type": "function",
+                        "function": {
+                            "name": "code_execution",
+                            "arguments": "{}",
+                        },
+                        "extra_content": {
+                            "google": {
+                                "native_part": {
+                                    "executableCode": {
+                                        "id": "code_a",
+                                        "language": "PYTHON",
+                                        "code": "print(2+2)",
+                                    },
+                                    "codeExecutionResult": {
+                                        "outcome": "OUTCOME_OK",
+                                        "output": "4\n",
+                                    },
+                                    "thoughtSignature": "SIG-CODE",
+                                },
+                            },
+                        },
+                    },
+                ],
+            },
+            {"role": "user", "content": "what was that result"},
+        ],
+    )
+    assistant_turn = captured["body"]["contents"][1]
+    assert assistant_turn["role"] == "model"
+    parts = assistant_turn["parts"]
+    native_keys = [list(p.keys())[0] for p in parts if isinstance(p, dict)]
+    assert "executableCode" in native_keys, parts
+    assert "codeExecutionResult" in native_keys, parts
+    assert not any(
+        "functionCall" in p
+        and (p["functionCall"] or {}).get("name") == "code_execution"
+        for p in parts
+    ), parts
+    exec_part = next(p for p in parts if "executableCode" in p)
+    assert exec_part.get("thoughtSignature") == "SIG-CODE", exec_part
+
+
+def test_image_generation_tool_call_replays_native_inline_data(monkeypatch):
+    """An assistant tool_call with toolName=image_generation and
+    extra_content.google.native_part.inlineData must replay the prior
+    image as a native Gemini inlineData part (not a generic
+    functionCall) so multi-turn image editing keeps the image
+    context."""
+    pixel = base64.b64encode(b"PNG").decode()
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        messages = [
+            {"role": "user", "content": "make a circle"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "img_a",
+                        "type": "function",
+                        "function": {
+                            "name": "image_generation",
+                            "arguments": "{}",
+                        },
+                        "extra_content": {
+                            "google": {
+                                "native_part": {
+                                    "inlineData": {
+                                        "mimeType": "image/png",
+                                        "data": pixel,
+                                    },
+                                    "thoughtSignature": "SIG-IMG",
+                                },
+                            },
+                        },
+                    },
+                ],
+            },
+            {"role": "user", "content": "now make it blue"},
+        ],
+    )
+    assistant_turn = captured["body"]["contents"][1]
+    assert assistant_turn["role"] == "model"
+    parts = assistant_turn["parts"]
+    inline_parts = [p for p in parts if "inlineData" in p]
+    assert inline_parts, parts
+    assert inline_parts[0]["inlineData"]["mimeType"] == "image/png"
+    assert inline_parts[0]["inlineData"]["data"] == pixel
+    assert inline_parts[0].get("thoughtSignature") == "SIG-IMG", inline_parts
+    assert not any(
+        "functionCall" in p
+        and (p["functionCall"] or {}).get("name") == "image_generation"
+        for p in parts
+    ), parts
+
+
+def test_assistant_text_thought_signature_replays_on_outbound_text_part(monkeypatch):
+    """Assistant text with extra_content.google.thought_signature must
+    attach `thoughtSignature` to the LAST text part of the replayed
+    Gemini history. Gemini 3 strict function-calling rejects history
+    that drops returned signatures, so the frontend stows the latest
+    signed-text signature and the backend pins it on the next turn."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "hi"},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "text", "text": "hello"},
+                ],
+                "extra_content": {
+                    "google": {"thought_signature": "SIG-TEXT"},
+                },
+            },
+            {"role": "user", "content": "again"},
+        ],
+    )
+    assistant_turn = captured["body"]["contents"][1]
+    assert assistant_turn["role"] == "model"
+    parts = assistant_turn["parts"]
+    text_parts = [p for p in parts if "text" in p]
+    assert text_parts, parts
+    assert text_parts[-1].get("thoughtSignature") == "SIG-TEXT", text_parts
+
+
+def test_function_declarations_strip_openai_only_schema_keys(monkeypatch):
+    """OpenAI strict tools commonly include `additionalProperties`,
+    `$schema`, `$defs`, `strict`, etc. Gemini's Schema rejects those
+    with INVALID_ARGUMENT, so the translator must strip them while
+    keeping properties.<field>.type intact."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "description": "Look up a value.",
+                    "parameters": {
+                        "type": "object",
+                        "$schema": "http://json-schema.org/draft-07/schema#",
+                        "additionalProperties": False,
+                        "strict": True,
+                        "properties": {
+                            "key": {
+                                "type": "string",
+                                "additionalProperties": False,
+                            },
+                        },
+                        "required": ["key"],
+                    },
+                },
+            }
+        ],
+    )
+    tools_arr = captured["body"].get("tools") or []
+    decls = next(
+        (
+            t.get("functionDeclarations")
+            for t in tools_arr
+            if "functionDeclarations" in t
+        ),
+        None,
+    )
+    assert decls is not None, captured["body"]
+    params = decls[0]["parameters"]
+    assert "additionalProperties" not in params
+    assert "$schema" not in params
+    assert "strict" not in params
+    assert params["type"] == "object"
+    assert params["properties"]["key"]["type"] == "string"
+    assert "additionalProperties" not in params["properties"]["key"]
+    assert params["required"] == ["key"]
+
+
+def test_function_declarations_inline_local_refs_into_gemini_schema(monkeypatch):
+    """Round 25: Pydantic-generated tool schemas hoist nested object
+    shapes into `$defs` and reference them with `{"$ref": "#/$defs/..."}`.
+    Gemini's OpenAPI subset has no $ref, so a naive allowlist sanitizer
+    drops the reference and reduces the nested property to `{}`, losing
+    its type, fields, and required keys. The sanitizer must resolve
+    local `#/...` pointers and inline the referenced schema."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "set_user",
+                    "description": "Persist a user.",
+                    "parameters": {
+                        "type": "object",
+                        "$defs": {
+                            "Address": {
+                                "type": "object",
+                                "properties": {
+                                    "street": {"type": "string"},
+                                    "zip": {"type": "string"},
+                                },
+                                "required": ["street", "zip"],
+                            },
+                        },
+                        "properties": {
+                            "name": {"type": "string"},
+                            "address": {"$ref": "#/$defs/Address"},
+                        },
+                        "required": ["name", "address"],
+                    },
+                },
+            }
+        ],
+    )
+    tools_arr = captured["body"].get("tools") or []
+    decls = next(
+        (
+            t.get("functionDeclarations")
+            for t in tools_arr
+            if "functionDeclarations" in t
+        ),
+        None,
+    )
+    assert decls is not None, captured["body"]
+    params = decls[0]["parameters"]
+    assert "$defs" not in params
+    address = params["properties"]["address"]
+    assert address.get("type") == "object", address
+    assert address.get("properties", {}).get("street", {}).get("type") == "string"
+    assert address.get("properties", {}).get("zip", {}).get("type") == "string"
+    assert address.get("required") == ["street", "zip"]
+
+
+def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch):
+    """The recursive inliner must reach through `anyOf` branches and
+    `items` (array element schemas) as well, not just top-level
+    property refs."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "bulk_set",
+                    "parameters": {
+                        "type": "object",
+                        "$defs": {
+                            "Address": {
+                                "type": "object",
+                                "properties": {"zip": {"type": "string"}},
+                                "required": ["zip"],
+                            },
+                        },
+                        "properties": {
+                            "primary": {
+                                "anyOf": [
+                                    {"$ref": "#/$defs/Address"},
+                                    {"type": "null"},
+                                ],
+                            },
+                            "extras": {
+                                "type": "array",
+                                "items": {"$ref": "#/$defs/Address"},
+                            },
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    tools_arr = captured["body"].get("tools") or []
+    decls = next(
+        (
+            t.get("functionDeclarations")
+            for t in tools_arr
+            if "functionDeclarations" in t
+        ),
+        None,
+    )
+    assert decls is not None
+    params = decls[0]["parameters"]
+    primary = params["properties"]["primary"]
+    # anyOf with single non-null branch + null collapses to inline +
+    # nullable: true, and the inlined branch must contain the resolved
+    # Address shape.
+    assert primary.get("nullable") is True
+    assert primary.get("type") == "object"
+    assert primary.get("properties", {}).get("zip", {}).get("type") == "string"
+    extras = params["properties"]["extras"]
+    assert extras.get("type") == "array"
+    assert extras.get("items", {}).get("type") == "object"
+    assert (
+        extras.get("items", {}).get("properties", {}).get("zip", {}).get("type")
+        == "string"
+    )
+
+
+def test_function_declarations_self_referential_schema_terminates(monkeypatch):
+    """Self-referential / cyclic JSON Schemas (a `Node` that contains
+    `children: [Node]`) must not infinite-loop. The inliner tracks the
+    set of refs in flight and short-circuits to `{}` on a cycle."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "set_tree",
+                    "parameters": {
+                        "type": "object",
+                        "$defs": {
+                            "Node": {
+                                "type": "object",
+                                "properties": {
+                                    "value": {"type": "string"},
+                                    "children": {
+                                        "type": "array",
+                                        "items": {"$ref": "#/$defs/Node"},
+                                    },
+                                },
+                            },
+                        },
+                        "properties": {
+                            "root": {"$ref": "#/$defs/Node"},
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    tools_arr = captured["body"].get("tools") or []
+    decls = next(
+        (
+            t.get("functionDeclarations")
+            for t in tools_arr
+            if "functionDeclarations" in t
+        ),
+        None,
+    )
+    assert decls is not None
+    root = decls[0]["parameters"]["properties"]["root"]
+    assert root.get("type") == "object"
+    assert root.get("properties", {}).get("value", {}).get("type") == "string"
+
+
+def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(
+    monkeypatch,
+):
+    """Round 26: when the assistant-side synthetic web_search/web_fetch
+    tool_call is dropped from native Gemini history, the matching
+    role="tool" follow-up must also be dropped. Otherwise the outbound
+    body carries an orphan functionResponse with no preceding
+    functionCall, which 400s the Gemini turn."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [
+                {"role": "user", "content": "search please"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_s",
+                            "type": "function",
+                            "function": {
+                                "name": "web_search",
+                                "arguments": ('{"_server_tool": true, "query": "x"}'),
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_s",
+                    "content": "[search result]",
+                },
+                {"role": "user", "content": "again"},
+            ],
+            "max_tokens": 64,
+            "stream": True,
+        }
+    )
+    built = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+    )
+    captured = _capture_body(monkeypatch, messages = built)
+    contents = captured["body"].get("contents") or []
+    for entry in contents:
+        for part in entry.get("parts", []):
+            fr = part.get("functionResponse")
+            if isinstance(fr, dict):
+                assert fr.get("name") != "web_search", contents
+
+
+def test_gemini_native_skips_orphan_function_response_for_native_part_replay(
+    monkeypatch,
+):
+    """Round 26: code_execution / image_generation tool_calls are
+    replayed as Gemini-native executableCode / codeExecutionResult /
+    inlineData parts. The matching role="tool" follow-up must NOT then
+    be emitted as a functionResponse named code_execution -- there is
+    no declared user function with that name, and Gemini's history
+    rules already attribute the result to the native parts above."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "plot something"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_a",
+                        "type": "function",
+                        "function": {
+                            "name": "code_execution",
+                            "arguments": "{}",
+                        },
+                        "extra_content": {
+                            "google": {
+                                "native_part": {
+                                    "parts": [
+                                        {
+                                            "executableCode": {
+                                                "language": "PYTHON",
+                                                "code": "print(2)",
+                                            }
+                                        },
+                                        {
+                                            "codeExecutionResult": {
+                                                "outcome": "OUTCOME_OK",
+                                                "output": "2\n",
+                                            }
+                                        },
+                                    ]
+                                }
+                            }
+                        },
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_a",
+                "name": "code_execution",
+                "content": "2",
+            },
+            {"role": "user", "content": "next"},
+        ],
+    )
+    contents = captured["body"].get("contents") or []
+    saw_native = False
+    for entry in contents:
+        for part in entry.get("parts", []):
+            if "executableCode" in part or "codeExecutionResult" in part:
+                saw_native = True
+            fr = part.get("functionResponse")
+            if isinstance(fr, dict):
+                assert fr.get("name") != "code_execution", contents
+    assert saw_native, contents
+
+
+def test_gemini_native_part_falls_back_to_args_google(monkeypatch):
+    """Round 27: a direct OpenAI-compat API caller (or imported third-
+    party thread) cannot use Studio's non-standard
+    `tool_calls[].extra_content` field, so the native_part payload
+    round-trips through `function.arguments` as
+    `{"google": {"native_part": {...}}}`. The synthetic-builtin
+    detector recognizes that location, but the replay branch was only
+    reading from `tc.extra_content.google.native_part`. Result: the
+    round-25 guard saw a synthetic builtin with no _native_part and
+    dropped the entire assistant turn, losing the prior code/image
+    context. The translator must fall back to args.google.native_part
+    and still emit the native executableCode / inlineData parts."""
+    import json as _json
+
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "draw a cat"},
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_img",
+                        "type": "function",
+                        "function": {
+                            "name": "image_generation",
+                            "arguments": _json.dumps(
+                                {
+                                    "google": {
+                                        "native_part": {
+                                            "parts": [
+                                                {
+                                                    "inlineData": {
+                                                        "mimeType": "image/png",
+                                                        "data": "AAAA",
+                                                    }
+                                                }
+                                            ]
+                                        }
+                                    }
+                                }
+                            ),
+                        },
+                    }
+                ],
+            },
+            {"role": "user", "content": "now make it a dog"},
+        ],
+    )
+    contents = captured["body"].get("contents") or []
+    saw_inline = False
+    for entry in contents:
+        for part in entry.get("parts", []):
+            if "inlineData" in part:
+                saw_inline = True
+    assert saw_inline, contents
+
+
+def test_gemini_native_skips_synthetic_server_builtin_replay(monkeypatch):
+    """Round 25: Marked server-side builtin tool_calls (web_search /
+    web_fetch with `_server_tool` or `args.google.native_part`) must
+    not fall through to the generic Gemini `functionCall` replay path
+    when no replayable native part exists. Without this guard the
+    outbound body contains a fake `functionCall` whose name is not a
+    declared user function, and the Gemini turn 400s."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [
+                {"role": "user", "content": "search please"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_s",
+                            "type": "function",
+                            "function": {
+                                "name": "web_search",
+                                "arguments": ('{"_server_tool": true, "query": "x"}'),
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "tool_call_id": "call_s",
+                    "content": "[search result]",
+                },
+                {"role": "user", "content": "again"},
+            ],
+            "max_tokens": 64,
+            "stream": True,
+        }
+    )
+    built = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+    )
+    captured = _capture_body(monkeypatch, messages = built)
+    contents = captured["body"].get("contents") or []
+    for entry in contents:
+        for part in entry.get("parts", []):
+            fc = part.get("functionCall")
+            if isinstance(fc, dict):
+                assert fc.get("name") != "web_search", contents
+
+
+def test_chat_message_extra_content_round_trips_through_validation():
+    """Round 9: ChatMessage was missing `extra_content`, so Pydantic
+    discarded the field during request validation and the text-part
+    signature replay path read nothing. The field must survive
+    model_validate and pass through _build_external_messages."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    req = ChatCompletionRequest.model_validate(
+        {
+            "model": "gemini-2.5-flash",
+            "messages": [
+                {"role": "user", "content": "hi"},
+                {
+                    "role": "assistant",
+                    "content": [
+                        {"type": "text", "text": "hello"},
+                    ],
+                    "extra_content": {
+                        "google": {"thought_signature": "SIG-TEXT"},
+                    },
+                },
+                {"role": "user", "content": "again"},
+            ],
+            "max_tokens": 64,
+            "stream": True,
+        }
+    )
+    assistant_msg = req.messages[1]
+    assert assistant_msg.extra_content == {
+        "google": {"thought_signature": "SIG-TEXT"},
+    }
+    built = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+    )
+    assistant_out = built[1]
+    assert assistant_out["extra_content"] == {
+        "google": {"thought_signature": "SIG-TEXT"},
+    }
+    # Non-Gemini providers must NOT receive extra_content; Google's
+    # thought_signature field is unknown to OpenAI / Mistral / etc.
+    built_openai = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "openai",
+    )
+    assert "extra_content" not in built_openai[1], built_openai[1]
+    # Custom non-Google Gemini bases (LiteLLM / OAI-compat gateways)
+    # also must not receive Gemini-only extra_content because the
+    # backend dispatches them through /chat/completions.
+    built_custom = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://litellm.example/v1",
+    )
+    assert "extra_content" not in built_custom[1], built_custom[1]
+
+
+def test_parallel_tool_results_group_into_one_user_block(monkeypatch):
+    """Round 14: Gemini docs show parallel functionResponses grouped
+    in a single subsequent user content with multiple
+    functionResponse parts. Consecutive OpenAI role="tool" messages
+    must merge into one Gemini user block, not split into separate
+    user turns."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {"role": "user", "content": "compute"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_a",
+                        "type": "function",
+                        "function": {"name": "add", "arguments": '{"x":1}'},
+                    },
+                    {
+                        "id": "call_b",
+                        "type": "function",
+                        "function": {"name": "mul", "arguments": '{"x":2}'},
+                    },
+                ],
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_a",
+                "name": "add",
+                "content": "2",
+            },
+            {
+                "role": "tool",
+                "tool_call_id": "call_b",
+                "name": "mul",
+                "content": "4",
+            },
+        ],
+    )
+    contents = captured["body"]["contents"]
+    # Initial user, model with two functionCalls, ONE user with two
+    # functionResponses.
+    tool_result_users = [
+        c
+        for c in contents
+        if c.get("role") == "user"
+        and all(
+            isinstance(p, dict) and "functionResponse" in p
+            for p in (c.get("parts") or [])
+        )
+    ]
+    assert len(tool_result_users) == 1, contents
+    fr_parts = tool_result_users[0]["parts"]
+    assert len(fr_parts) == 2, fr_parts
+    names = [p["functionResponse"]["name"] for p in fr_parts]
+    assert names == ["add", "mul"], names
+
+
+def test_function_schema_nullable_type_array_flattens(monkeypatch):
+    """Round 14: OpenAI strict tools commonly use
+    `"type": ["string", "null"]` for optional fields. Gemini's
+    OpenAPI-style Schema rejects union types and expects
+    `"type": "string"` with `"nullable": true`. The sanitizer must
+    translate the union form."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "city": {"type": ["string", "null"]},
+                            "score": {"type": ["number", "null"]},
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    decls = next(
+        t["functionDeclarations"]
+        for t in captured["body"].get("tools") or []
+        if "functionDeclarations" in t
+    )
+    params = decls[0]["parameters"]["properties"]
+    assert params["city"]["type"] == "string"
+    assert params["city"]["nullable"] is True
+    assert params["score"]["type"] == "number"
+    assert params["score"]["nullable"] is True
+
+
+def test_image_picker_model_with_search_off_pill_strips_text_tools(monkeypatch):
+    """Round 11: image-tier model id rejects text-only tools and
+    thinkingConfig at the model level regardless of whether the Images
+    pill is on. Selecting gemini-2.5-flash-image + enabled_tools=
+    ["web_search"] with no image_generation must NOT forward
+    googleSearch or thinkingConfig (Gemini 400s on text tools for
+    legacy image ids)."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["web_search"],
+        reasoning_effort = "high",
+    )
+    body = captured["body"]
+    assert "tools" not in body, body.get("tools")
+    assert "thinkingConfig" not in body.get("generationConfig", {}), body[
+        "generationConfig"
+    ]
+
+
+def test_image_models_drop_function_declarations(monkeypatch):
+    """Image-mode requests cannot mix tools with responseModalities so
+    user-supplied function declarations must be dropped."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation"],
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "noop", "parameters": {"type": "object"}},
+            }
+        ],
+    )
+    assert captured["body"].get("tools") is None
+    assert captured["body"]["generationConfig"]["responseModalities"] == [
+        "TEXT",
+        "IMAGE",
+    ]
+
+
+def test_safe_fetch_image_rejects_malformed_bracketed_url():
+    """Round 17: bracketed IPv6 garbage like `https://[bad/x.png` makes
+    urlparse raise ValueError. The fetch helper must catch it and drop
+    the image rather than crashing the request mid-build."""
+    res = _drive(ep_mod._safe_fetch_image_for_gemini("https://[bad/x.png", "image/png"))
+    assert res is None
+
+
+def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(
+    monkeypatch,
+):
+    """Round 17: the fetch helper must pin the validated IP into the
+    outgoing request URL (with a Host header carrying the original
+    hostname). A second hostname-style getaddrinfo after the validate
+    step would be a DNS-rebinding gap, so we assert the urllib opener
+    is called with an IP-rewritten URL."""
+    import socket
+
+    captured: dict = {"requests": []}
+
+    # Public IP during validate; record every getaddrinfo call.
+    original_getaddrinfo = socket.getaddrinfo
+
+    def fake_getaddrinfo(host, *args, **kwargs):
+        captured.setdefault("dns", []).append(host)
+        if host == "cdn.example.com":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("8.8.8.8", 0),
+                )
+            ]
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    class _StubResp:
+        status = 200
+        headers = {"content-type": "image/png", "content-length": "3"}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def read(self, _n = None):
+            return b"PNG"
+
+    class _StubOpener:
+        def open(self, req, timeout = None):
+            captured["requests"].append(
+                {
+                    "url": req.full_url,
+                    "host_header": req.get_header("Host"),
+                }
+            )
+            return _StubResp()
+
+    monkeypatch.setattr(
+        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
+    )
+
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://cdn.example.com/x.png", "image/png"
+        )
+    )
+    assert res is not None
+    assert res[0] == "image/png"
+    # The outgoing URL must use the pinned IP literal, not the hostname.
+    assert any("8.8.8.8" in r["url"] for r in captured["requests"]), captured
+    assert all(
+        "cdn.example.com" not in r["url"] for r in captured["requests"]
+    ), captured
+    # Host header still carries the original hostname for vhost/SNI.
+    assert captured["requests"][0]["host_header"] == "cdn.example.com"
+
+
+def test_safe_fetch_image_redirect_to_private_host_rejected(monkeypatch):
+    """Round 17: each redirect hop must re-validate the new host. A
+    public hop that redirects to an internal address must be dropped."""
+    import socket
+    import urllib.error
+
+    original_getaddrinfo = socket.getaddrinfo
+
+    def fake_getaddrinfo(host, *args, **kwargs):
+        if host == "cdn.example.com":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("1.1.1.1", 0),
+                )
+            ]
+        if host == "internal.bad":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("10.0.0.5", 0),
+                )
+            ]
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    class _StubOpener:
+        def open(self, req, timeout = None):
+            # Simulate a 302 to a private host.
+            raise urllib.error.HTTPError(
+                req.full_url,
+                302,
+                "Found",
+                {"Location": "https://internal.bad/secret.png"},
+                None,
+            )
+
+    monkeypatch.setattr(
+        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
+    )
+
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://cdn.example.com/x.png", "image/png"
+        )
+    )
+    assert res is None
+
+
+def test_files_api_substring_url_not_misclassified_as_filedata(monkeypatch):
+    """Round 17: a CDN URL whose path/query merely contains the Files
+    API substring must NOT be sent as `fileData.fileUri`; it must be
+    routed through the safe-fetch path. Previously the substring check
+    `"generativelanguage.googleapis.com/" in url.lower()` matched any
+    URL carrying that text anywhere."""
+    captured_outbound: dict = {}
+    fetch_calls: list[str] = []
+
+    async def fake_fetch(url, fallback_mime, max_bytes = None):
+        fetch_calls.append(url)
+        return "image/png", base64.b64encode(b"DATA").decode("ascii")
+
+    monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured_outbound["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = _gemini_sse(
+                [
+                    {
+                        "candidates": [
+                            {
+                                "content": {
+                                    "role": "model",
+                                    "parts": [{"text": "ok"}],
+                                },
+                                "finishReason": "STOP",
+                            }
+                        ],
+                        "usageMetadata": {
+                            "promptTokenCount": 1,
+                            "candidatesTokenCount": 1,
+                        },
+                    }
+                ]
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = _make_gemini_client()
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "describe"},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                # Looks like a Files API URL in the path
+                                # but the host is an attacker CDN.
+                                "url": "https://evil.example/path/generativelanguage.googleapis.com/v1beta/files/abc.png",
+                            },
+                        },
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                # Looks YouTube-ish in the path.
+                                "url": "https://cdn.example.com/youtube.com/cat.png",
+                            },
+                        },
+                    ],
+                }
+            ],
+            model = "gemini-2.5-flash",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    parts = captured_outbound["body"]["contents"][-1]["parts"]
+    assert not any("fileData" in p for p in parts), parts
+    inline_count = sum(1 for p in parts if "inlineData" in p)
+    assert inline_count == 2, parts
+    assert len(fetch_calls) == 2, fetch_calls
+
+
+def test_function_schema_anyof_null_variant_flattens_to_nullable(monkeypatch):
+    """Round 17: OpenAI/Pydantic emit `anyOf: [{X}, {"type":"null"}]`
+    for Optional[X]. Gemini's OpenAPI subset rejects `"type":"null"`
+    inside anyOf. The sanitizer must collapse a singleton-plus-null
+    union back to the non-null branch with `nullable: true`."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "label": {
+                                "anyOf": [
+                                    {"type": "string"},
+                                    {"type": "null"},
+                                ]
+                            },
+                            "count": {
+                                "anyOf": [
+                                    {"type": "integer"},
+                                    {"type": "null"},
+                                ]
+                            },
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    decls = next(
+        t["functionDeclarations"]
+        for t in captured["body"].get("tools") or []
+        if "functionDeclarations" in t
+    )
+    params = decls[0]["parameters"]["properties"]
+    assert params["label"]["type"] == "string"
+    assert params["label"]["nullable"] is True
+    assert "anyOf" not in params["label"]
+    assert params["count"]["type"] == "integer"
+    assert params["count"]["nullable"] is True
+
+
+def test_legacy_gemini3_pro_medium_coerced_to_high(monkeypatch):
+    """Round 17: legacy `gemini-3-pro*` (including `-preview`, shut down
+    2026-03-09) only accepted low/high. 3.1+ Pro added medium. The
+    backend must coerce medium → high for the legacy model so stale UI
+    state does not 400 the request."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3-pro-preview",
+        reasoning_effort = "medium",
+    )
+    assert captured["body"]["generationConfig"]["thinkingConfig"] == {
+        "thinkingLevel": "high",
+    }
+
+
+def test_gemini_3_1_pro_medium_passes_through(monkeypatch):
+    """Round 17 regression: 3.1+ Pro accepts medium; coercion must NOT
+    apply when the model id is gemini-3.1-pro*."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-3.1-pro-preview",
+        reasoning_effort = "medium",
+    )
+    assert captured["body"]["generationConfig"]["thinkingConfig"] == {
+        "thinkingLevel": "medium",
+    }
+
+
+def test_tool_calls_extra_content_stripped_for_non_native_gemini():
+    """Round 17: per-tool-call `extra_content` (Gemini thoughtSignature
+    carrier) must not leak through `_build_external_messages` to
+    non-native-Gemini providers; OpenAI / Anthropic / custom Gemini
+    OAI-compat gateways would 400 on the unknown key."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "lookup", "arguments": "{}"},
+                        "extra_content": {
+                            "google": {"thought_signature": "SIG"},
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+
+    # Non-native providers (openai, custom Gemini OAI-compat proxy)
+    # must have extra_content stripped from the tool_call entry.
+    for provider_type, base_url in [
+        ("openai", None),
+        ("gemini", "https://litellm.example/v1"),
+    ]:
+        result = _build_external_messages(
+            req.messages,
+            supports_vision = True,
+            provider_type = provider_type,
+            base_url = base_url,
+        )
+        assert len(result) == 1
+        tc = result[0]["tool_calls"][0]
+        assert "extra_content" not in tc, (provider_type, tc)
+
+    # Native Gemini still receives extra_content for the round-trip.
+    result_native = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+    )
+    tc_native = result_native[0]["tool_calls"][0]
+    assert tc_native["extra_content"]["google"]["thought_signature"] == "SIG"
+
+
+def test_user_function_named_with_server_tool_arg_not_dropped(monkeypatch):
+    """Round 17: the OpenAI Responses translator must NOT drop a user
+    function whose JSON arguments happen to contain `_server_tool:
+    true` UNLESS the function name is also one of the canonical
+    builtin names. Otherwise a user schema with an `_server_tool` field
+    becomes invisible to the model."""
+    captured: dict = {"input_items": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["input_items"] = body.get("input")
+        return httpx.Response(
+            200,
+            content = b'data: {"type":"response.completed","response":{"output":[],"usage":{"input_tokens":1,"output_tokens":1}}}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "hi"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_user",
+                            "type": "function",
+                            "function": {
+                                "name": "user_function",
+                                "arguments": json.dumps(
+                                    {"_server_tool": True, "q": "x"}
+                                ),
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "content": "result",
+                    "tool_call_id": "call_user",
+                    "name": "user_function",
+                },
+                {"role": "user", "content": "continue"},
+            ],
+            model = "gpt-5.5",
+            temperature = 0.7,
+            top_p = 1.0,
+            max_tokens = 16,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    items = captured["input_items"] or []
+    fn_calls = [i for i in items if i.get("type") == "function_call"]
+    fn_outs = [i for i in items if i.get("type") == "function_call_output"]
+    # User function call must survive (matching call + output).
+    assert any(c.get("name") == "user_function" for c in fn_calls), items
+    assert len(fn_outs) == 1, items
+
+
+def test_builtin_named_with_server_tool_marker_dropped(monkeypatch):
+    """Round 17 control: a builtin (web_search) tagged with
+    `_server_tool: true` continues to be filtered from outbound
+    history."""
+    captured: dict = {"input_items": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["input_items"] = body.get("input")
+        return httpx.Response(
+            200,
+            content = b'data: {"type":"response.completed","response":{"output":[],"usage":{"input_tokens":1,"output_tokens":1}}}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "search please"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_b",
+                            "type": "function",
+                            "function": {
+                                "name": "web_search",
+                                "arguments": json.dumps(
+                                    {"_server_tool": True, "query": "x"}
+                                ),
+                            },
+                        }
+                    ],
+                },
+                {"role": "user", "content": "continue"},
+            ],
+            model = "gpt-5.5",
+            temperature = 0.7,
+            top_p = 1.0,
+            max_tokens = 16,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    items = captured["input_items"] or []
+    fn_calls = [i for i in items if i.get("type") == "function_call"]
+    # Builtin server-side tool call must be filtered out.
+    assert all(c.get("name") != "web_search" for c in fn_calls), items
+
+
+def test_gemini_tool_choice_none_disables_hosted_builtins(monkeypatch):
+    """Round 18: `tool_choice="none"` must drop hosted Google Search /
+    code execution from the outbound Gemini body, not just user
+    function declarations. Otherwise an API client that opted out of
+    tool use still triggers grounded search (privacy + billing)."""
+    captured = _capture_body(
+        monkeypatch,
+        enabled_tools = ["web_search", "code_execution"],
+        tool_choice = "none",
+    )
+    assert captured["body"].get("tools") is None, captured["body"]
+
+
+def test_gemini_tool_choice_none_disables_function_declarations(monkeypatch):
+    """Round 18: `tool_choice="none"` must drop user function
+    declarations as well as hosted builtins from the Gemini body."""
+    captured = _capture_body(
+        monkeypatch,
+        tool_choice = "none",
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "lookup", "parameters": {"type": "object"}},
+            }
+        ],
+    )
+    assert captured["body"].get("tools") is None, captured["body"]
+
+
+def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(
+    monkeypatch,
+):
+    """Round 18: multi-branch unions with null (e.g.
+    `Union[str, int, None]`) must keep the slim anyOf without the null
+    branch and add `nullable: true`; Gemini rejects
+    `{"type":"null"}` inside anyOf."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "either": {
+                                "anyOf": [
+                                    {"type": "string"},
+                                    {"type": "integer"},
+                                    {"type": "null"},
+                                ]
+                            },
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    decls = next(
+        t["functionDeclarations"]
+        for t in captured["body"].get("tools") or []
+        if "functionDeclarations" in t
+    )
+    either = decls[0]["parameters"]["properties"]["either"]
+    assert either.get("nullable") is True
+    inner = either.get("anyOf")
+    assert isinstance(inner, list) and len(inner) == 2, either
+    assert all(
+        not (isinstance(b, dict) and b.get("type") == "null") for b in inner
+    ), inner
+
+
+def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
+    """Round 18: when the upstream 302 Location is a malformed
+    bracketed-IPv6 URL, the helper must return None instead of letting
+    a urlparse ValueError abort the chat stream."""
+    import socket
+    import urllib.error
+
+    original_getaddrinfo = socket.getaddrinfo
+
+    def fake_getaddrinfo(host, *args, **kwargs):
+        if host == "cdn.example.com":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("1.1.1.1", 0),
+                )
+            ]
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    class _StubOpener:
+        def open(self, req, timeout = None):
+            raise urllib.error.HTTPError(
+                req.full_url,
+                302,
+                "Found",
+                {"Location": "https://[bad/x.png"},
+                None,
+            )
+
+    monkeypatch.setattr(
+        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
+    )
+
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://cdn.example.com/x.png", "image/png"
+        )
+    )
+    assert res is None
+
+
+def test_safe_fetch_image_malformed_port_no_crash():
+    """Round 18: a URL with a non-numeric port (`https://h:bad/x.png`)
+    must not raise; urlparse's port property lazily ValueErrors."""
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://example.com:bad/x.png", "image/png"
+        )
+    )
+    assert res is None
+
+
+def test_safe_fetch_image_missing_content_type_uses_fallback(monkeypatch):
+    """Round 18: when the server returns image bytes but no
+    Content-Type header, the helper must use the caller-provided
+    fallback MIME (guessed from URL extension) instead of dropping the
+    image as `non-image content-type=<none>`."""
+    import socket
+
+    original_getaddrinfo = socket.getaddrinfo
+
+    def fake_getaddrinfo(host, *args, **kwargs):
+        if host == "cdn.example.com":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("1.1.1.1", 0),
+                )
+            ]
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    class _StubResp:
+        status = 200
+        headers = {"content-length": "3"}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def read(self, _n = None):
+            return b"PNG"
+
+    class _StubOpener:
+        def open(self, req, timeout = None):
+            return _StubResp()
+
+    monkeypatch.setattr(
+        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
+    )
+
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://cdn.example.com/cat.png", "image/png"
+        )
+    )
+    assert res is not None
+    assert res[0] == "image/png"
+
+
+def test_anthropic_translates_openai_tool_calls_into_tool_use_blocks(monkeypatch):
+    """Round 18: an assistant turn with OpenAI-style top-level
+    `tool_calls` must be translated into Anthropic native
+    `{type:"tool_use", id, name, input}` content blocks before being
+    forwarded. The OpenAI `role="tool"` follow-up must become a
+    `role:"user"` message with a `tool_result` content block."""
+    captured: dict = {"messages": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["messages"] = body.get("messages")
+        return httpx.Response(
+            200,
+            content = b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "anthropic",
+            base_url = "https://api.anthropic.com",
+            api_key = "sk-ant-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "look up X"},
+                {
+                    "role": "assistant",
+                    "content": "let me check",
+                    "tool_calls": [
+                        {
+                            "id": "call_a",
+                            "type": "function",
+                            "function": {
+                                "name": "lookup",
+                                "arguments": '{"q":"x"}',
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "content": "result_text",
+                    "tool_call_id": "call_a",
+                    "name": "lookup",
+                },
+                {"role": "user", "content": "summarise"},
+            ],
+            model = "claude-sonnet-4-5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    msgs = captured["messages"] or []
+    # No top-level tool_calls should remain.
+    assert all("tool_calls" not in m for m in msgs), msgs
+    # The assistant turn must now have content blocks including a
+    # tool_use block.
+    asst = [m for m in msgs if m.get("role") == "assistant"]
+    assert asst and isinstance(asst[0]["content"], list), asst
+    tool_uses = [b for b in asst[0]["content"] if b.get("type") == "tool_use"]
+    assert len(tool_uses) == 1, asst[0]
+    assert tool_uses[0]["name"] == "lookup"
+    assert tool_uses[0]["input"] == {"q": "x"}
+    # The role="tool" message must become a user/tool_result message.
+    tool_results: list[dict] = []
+    for m in msgs:
+        if m.get("role") == "user" and isinstance(m.get("content"), list):
+            tool_results.extend(
+                b for b in m["content"] if b.get("type") == "tool_result"
+            )
+    assert any(
+        tr.get("tool_use_id") == "call_a" and tr.get("content") == "result_text"
+        for tr in tool_results
+    ), msgs
+
+
+def test_unmarked_user_web_search_function_survives_serialization():
+    """Round 18: a user-defined function literally named `web_search`
+    with NO `_server_tool` marker must survive `_build_external_messages`
+    when forwarded to a non-native provider; only marked synthetic
+    builtin cards may be dropped."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_user",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": '{"query": "x"}',
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    result = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "openai",
+        base_url = None,
+    )
+    assert len(result) == 1, result
+    tcs = result[0].get("tool_calls") or []
+    assert len(tcs) == 1, result
+    assert tcs[0]["function"]["name"] == "web_search"
+
+
+def test_marked_server_builtin_dropped_from_build_external_messages():
+    """Round 18: when a Gemini-native turn carrying a marked
+    `image_generation` server-tool card is forwarded to OpenAI / a
+    custom Gemini OAI-compat proxy, the tool_call must be dropped, not
+    just have its extra_content stripped. Forwarding an orphan
+    `image_generation` tool_call would 400 the receiving API."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    marked_args = json.dumps({"_server_tool": True, "kind": "image"})
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_b",
+                        "type": "function",
+                        "function": {
+                            "name": "image_generation",
+                            "arguments": marked_args,
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    # Non-native providers: marked builtin tool_call must be dropped
+    # AND if it was the only payload, the whole message disappears.
+    for provider_type, base_url in [
+        ("openai", None),
+        ("gemini", "https://litellm.example/v1"),
+    ]:
+        result = _build_external_messages(
+            req.messages,
+            supports_vision = True,
+            provider_type = provider_type,
+            base_url = base_url,
+        )
+        # Empty assistant turn with only synthetic tool_call dropped.
+        assert result == [] or all(not (m.get("tool_calls") or []) for m in result), (
+            provider_type,
+            result,
+        )
+
+    # Native Gemini preserves it (round-trips via extra_content).
+    result_native = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "gemini",
+        base_url = "https://generativelanguage.googleapis.com/v1beta",
+    )
+    assert len(result_native) == 1
+    assert result_native[0]["tool_calls"][0]["function"]["name"] == "image_generation"
+
+
+def test_openai_responses_tool_choice_none_drops_hosted_tools(monkeypatch):
+    """Round 18: `tool_choice="none"` must also drop hosted OpenAI
+    Responses builtins (web_search, code execution shell, image
+    generation), not just user function tools."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b'data: {"type":"response.completed","response":{"output":[],"usage":{"input_tokens":1,"output_tokens":1}}}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "gpt-5.5",
+            temperature = 0.7,
+            top_p = 1.0,
+            max_tokens = 16,
+            enabled_tools = ["web_search", "code_execution", "image_generation"],
+            tool_choice = "none",
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    assert body.get("tools") in (None, []), body
+
+
+def test_anthropic_tool_choice_none_drops_hosted_tools(monkeypatch):
+    """Round 19: tool_choice="none" must opt out of Anthropic hosted
+    builtins (web_search, web_fetch, code_execution) just like it does
+    for Gemini and OpenAI Responses."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "anthropic",
+            base_url = "https://api.anthropic.com",
+            api_key = "sk-ant-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "claude-sonnet-4-5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search", "web_fetch", "code_execution"],
+            tool_choice = "none",
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    assert body.get("tools") in (None, []), body
+
+
+def test_openrouter_tool_choice_none_drops_web_plugin(monkeypatch):
+    """Round 19: tool_choice="none" must drop the OpenRouter web
+    plugin so a request that opted out of tool use does not still
+    trigger hosted web search."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b"data: [DONE]\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openrouter",
+            base_url = "https://openrouter.ai/api/v1",
+            api_key = "sk-or-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "openai/gpt-5.5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = "none",
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    assert body.get("plugins") in (None, []), body
+
+
+def test_kimi_tool_choice_none_skips_web_search_helper(monkeypatch):
+    """Round 19: when tool_choice="none" plus enabled_tools=
+    ["web_search"] on Kimi, the dispatcher must NOT route into
+    `_stream_kimi_web_search`. Falling through to the generic OAI-
+    compat path is the expected behavior."""
+    routed_to_helper = {"called": False}
+
+    real_helper = ExternalProviderClient._stream_kimi_web_search
+
+    async def fake_helper(self, *args, **kwargs):  # noqa: ARG001
+        routed_to_helper["called"] = True
+        if False:
+            yield ""  # pragma: no cover
+
+    monkeypatch.setattr(
+        ExternalProviderClient,
+        "_stream_kimi_web_search",
+        fake_helper,
+    )
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = b"data: [DONE]\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "kimi",
+            base_url = "https://api.moonshot.ai/v1",
+            api_key = "sk-kimi-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "kimi-k2.6",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = "none",
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    assert routed_to_helper["called"] is False
+
+    monkeypatch.setattr(
+        ExternalProviderClient,
+        "_stream_kimi_web_search",
+        real_helper,
+    )
+
+
+def test_user_code_execution_function_not_dropped():
+    """Round 19: a user-declared function literally named
+    `code_execution` with normal `code` arguments must survive
+    `_build_external_messages` -- round 17's shape heuristic dropped
+    it, which broke function-calling round-trips."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_user",
+                        "type": "function",
+                        "function": {
+                            "name": "code_execution",
+                            "arguments": '{"code": "print(1)"}',
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    result = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "openai",
+        base_url = None,
+    )
+    assert len(result) == 1, result
+    tcs = result[0].get("tool_calls") or []
+    assert len(tcs) == 1, result
+    assert tcs[0]["function"]["name"] == "code_execution"
+
+
+def test_native_part_code_execution_treated_as_server_side():
+    """Round 19: a Gemini `code_execution` card persists its replay
+    payload at `args.google.native_part` (no `_server_tool` marker on
+    pre-PR cards). The backend filter must still drop it for non-native
+    providers because it is a synthetic card, not a real user function."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    args_with_native_part = json.dumps(
+        {
+            "google": {
+                "native_part": {
+                    "executableCode": {
+                        "language": "PYTHON",
+                        "code": "print(1)",
+                    }
+                }
+            }
+        }
+    )
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_x",
+                        "type": "function",
+                        "function": {
+                            "name": "code_execution",
+                            "arguments": args_with_native_part,
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    result = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "openai",
+        base_url = None,
+    )
+    assert result == [] or all(not (m.get("tool_calls") or []) for m in result), result
+
+
+def test_remote_image_fetch_attempt_cap_includes_failures(monkeypatch):
+    """Round 19: the per-request image fetch count cap must count
+    ATTEMPTS, not just successes. Otherwise a request with 100
+    failing/slow URLs runs 100 fetches each up to the 15s timeout."""
+    fetch_calls: list[str] = []
+
+    async def fake_fetch(url, fallback_mime, max_bytes = None):
+        fetch_calls.append(url)
+        return None
+
+    monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = _gemini_sse(
+                [
+                    {
+                        "candidates": [
+                            {
+                                "content": {
+                                    "role": "model",
+                                    "parts": [{"text": "ok"}],
+                                },
+                                "finishReason": "STOP",
+                            }
+                        ],
+                        "usageMetadata": {
+                            "promptTokenCount": 1,
+                            "candidatesTokenCount": 1,
+                        },
+                    }
+                ]
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = _make_gemini_client()
+        image_parts = [
+            {
+                "type": "image_url",
+                "image_url": {"url": f"https://cdn.example.com/img{idx}.png"},
+            }
+            for idx in range(20)
+        ]
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "describe"},
+                        *image_parts,
+                    ],
+                }
+            ],
+            model = "gemini-2.5-flash",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    assert len(fetch_calls) <= 8, len(fetch_calls)
+
+
+def test_orphan_function_call_output_dropped_when_call_skipped(monkeypatch):
+    """Round 19: when a marked server-side builtin `function_call` is
+    dropped from OpenAI Responses input items, the matching role=tool
+    follow-up must also be dropped to avoid an orphan
+    `function_call_output`."""
+    captured: dict = {"input_items": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["input_items"] = body.get("input")
+        return httpx.Response(
+            200,
+            content = b'data: {"type":"response.completed","response":{"output":[],"usage":{"input_tokens":1,"output_tokens":1}}}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "search please"},
+                {
+                    "role": "assistant",
+                    "content": "",
+                    "tool_calls": [
+                        {
+                            "id": "call_b",
+                            "type": "function",
+                            "function": {
+                                "name": "web_search",
+                                "arguments": json.dumps(
+                                    {"_server_tool": True, "query": "x"}
+                                ),
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "content": "result_text",
+                    "tool_call_id": "call_b",
+                    "name": "web_search",
+                },
+                {"role": "user", "content": "continue"},
+            ],
+            model = "gpt-5.5",
+            temperature = 0.7,
+            top_p = 1.0,
+            max_tokens = 16,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    items = captured["input_items"] or []
+    fn_calls = [i for i in items if i.get("type") == "function_call"]
+    fn_outs = [i for i in items if i.get("type") == "function_call_output"]
+    assert all(c.get("call_id") != "call_b" for c in fn_calls), items
+    assert all(o.get("call_id") != "call_b" for o in fn_outs), items
+
+
+def test_schema_multitype_union_with_null_preserves_anyof(monkeypatch):
+    """Round 19: a JSON Schema `"type": ["string","integer","null"]`
+    must be sanitized to anyOf:[{string},{integer}] + nullable:true.
+    Flattening to just `{"type":"string"}` silently drops the integer
+    branch and changes the function contract."""
+    captured = _capture_body(
+        monkeypatch,
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "lookup",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "either": {"type": ["string", "integer", "null"]},
+                        },
+                    },
+                },
+            }
+        ],
+    )
+    decls = next(
+        t["functionDeclarations"]
+        for t in captured["body"].get("tools") or []
+        if "functionDeclarations" in t
+    )
+    either = decls[0]["parameters"]["properties"]["either"]
+    assert either.get("nullable") is True
+    inner = either.get("anyOf")
+    assert isinstance(inner, list) and len(inner) == 2, either
+    types = sorted(
+        b.get("type") for b in inner if isinstance(b, dict) and b.get("type")
+    )
+    assert types == ["integer", "string"], inner
+
+
+def test_invalid_gemini_model_rejected_before_image_fetch(monkeypatch):
+    """Round 19: invalid Gemini model IDs are rejected at the top of
+    `_stream_gemini`, BEFORE any user-controlled remote image fetch
+    runs."""
+    fetch_calls: list[str] = []
+
+    async def fake_fetch(url, fallback_mime, max_bytes = None):
+        fetch_calls.append(url)
+        return None
+
+    monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = b"",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = _make_gemini_client()
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "hi"},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": "https://cdn.example.com/x.png"},
+                        },
+                    ],
+                }
+            ],
+            model = "../cachedContents/leak",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    assert fetch_calls == [], fetch_calls
+
+
+def test_empty_assistant_turn_skipped_after_synthetic_tool_calls_dropped():
+    """Round 20: when `_filter_tool_calls` drops every synthetic
+    server-builtin tool_call on an empty-content assistant turn, the
+    whole message must be skipped. Forwarding
+    `{"role":"assistant","content":""}` is rejected by several
+    providers as an empty assistant turn."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    marked_args = json.dumps({"_server_tool": True, "kind": "image"})
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_b",
+                        "type": "function",
+                        "function": {
+                            "name": "image_generation",
+                            "arguments": marked_args,
+                        },
+                    }
+                ],
+            }
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    for provider_type, base_url in [
+        ("openai", None),
+        ("gemini", "https://litellm.example/v1"),
+    ]:
+        result = _build_external_messages(
+            req.messages,
+            supports_vision = True,
+            provider_type = provider_type,
+            base_url = base_url,
+        )
+        # The empty assistant turn (only a synthetic builtin) must
+        # NOT appear in the output at all.
+        assert result == [], (provider_type, result)
+
+
+def test_role_tool_dropped_when_matching_synthetic_call_filtered():
+    """Round 20: `_build_external_messages` drops the matching role=
+    tool follow-up when its tool_call was a synthetic builtin that
+    `_filter_tool_calls` removed. Otherwise the receiving provider
+    sees an orphan tool_result with no tool_call."""
+    from models.inference import ChatCompletionRequest
+    from routes.inference import _build_external_messages
+
+    marked_args = json.dumps({"_server_tool": True, "query": "x"})
+    payload = {
+        "model": "gpt-5.5",
+        "messages": [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "call_b",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": marked_args,
+                        },
+                    }
+                ],
+            },
+            {
+                "role": "tool",
+                "content": "result_text",
+                "tool_call_id": "call_b",
+                "name": "web_search",
+            },
+            {"role": "user", "content": "continue"},
+        ],
+        "stream": True,
+    }
+    req = ChatCompletionRequest.model_validate(payload)
+    result = _build_external_messages(
+        req.messages,
+        supports_vision = True,
+        provider_type = "openai",
+        base_url = None,
+    )
+    # Only the user "continue" message survives.
+    roles = [m.get("role") for m in result]
+    assert roles == ["user"], result
+
+
+def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(
+    monkeypatch,
+):
+    """Round 20: OpenRouter dispatcher must not emit synthetic
+    web_search tool_start / tool_end events when tool_choice="none";
+    otherwise the chat UI shows a search card for a search that
+    never happened."""
+    captured_events: list[dict] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = b"data: [DONE]\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openrouter",
+            base_url = "https://openrouter.ai/api/v1",
+            api_key = "sk-or-test",
+        )
+        async for line in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "openai/gpt-5.5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = "none",
+        ):
+            if not line.startswith("data: "):
+                continue
+            payload = line[len("data: ") :].strip()
+            if not payload or payload == "[DONE]":
+                continue
+            try:
+                obj = json.loads(payload)
+            except Exception:
+                continue
+            # Backend emits synthetic tool events as a top-level
+            # `_toolEvent` on the SSE payload (not nested inside
+            # `delta`). Read both shapes so a future format change
+            # cannot mask this regression.
+            evt = obj.get("_toolEvent")
+            if isinstance(evt, dict):
+                captured_events.append(evt)
+            for ch in obj.get("choices") or []:
+                delta = ch.get("delta") or {}
+                nested = delta.get("_toolEvent") if isinstance(delta, dict) else None
+                if isinstance(nested, dict):
+                    captured_events.append(nested)
+        await client.close()
+
+    _drive(run())
+    # No synthetic web_search tool_start / tool_end emitted.
+    assert all(
+        e.get("tool_name") != "web_search" for e in captured_events
+    ), captured_events
+
+
+def test_anthropic_role_tool_list_content_translates_to_tool_result(
+    monkeypatch,
+):
+    """Round 20: an OpenAI-shape role=tool message with list content
+    (`content=[{"type":"text","text":"result"}]`) must be translated
+    into Anthropic's native tool_result block, not forwarded as an
+    invalid role=tool message."""
+    captured: dict = {"messages": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["messages"] = body.get("messages")
+        return httpx.Response(
+            200,
+            content = b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "anthropic",
+            base_url = "https://api.anthropic.com",
+            api_key = "sk-ant-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "look up X"},
+                {
+                    "role": "assistant",
+                    "content": "let me check",
+                    "tool_calls": [
+                        {
+                            "id": "call_a",
+                            "type": "function",
+                            "function": {
+                                "name": "lookup",
+                                "arguments": '{"q":"x"}',
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "content": [{"type": "text", "text": "result_text"}],
+                    "tool_call_id": "call_a",
+                    "name": "lookup",
+                },
+                {"role": "user", "content": "summarise"},
+            ],
+            model = "claude-sonnet-4-5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 64,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    msgs = captured["messages"] or []
+    assert all(m.get("role") != "tool" for m in msgs), msgs
+    tool_results: list[dict] = []
+    for m in msgs:
+        if m.get("role") == "user" and isinstance(m.get("content"), list):
+            tool_results.extend(
+                b for b in m["content"] if b.get("type") == "tool_result"
+            )
+    assert any(
+        tr.get("tool_use_id") == "call_a" and tr.get("content") == "result_text"
+        for tr in tool_results
+    ), msgs
+
+
+def test_data_url_non_image_mime_dropped(monkeypatch):
+    """Round 20: a `data:text/html;base64,...` image_url must be
+    dropped from the outbound Gemini body, not forwarded as
+    `inlineData.mimeType="text/html"` which Gemini rejects."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "look"},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": "data:text/html;base64,PGgxPmhpPC9oMT4=",
+                        },
+                    },
+                ],
+            }
+        ],
+    )
+    parts = captured["body"]["contents"][-1]["parts"]
+    assert not any("inlineData" in p for p in parts), parts
+
+
+def test_youtube_filedata_uses_video_mime(monkeypatch):
+    """Round 20: YouTube `fileData.fileUri` must declare a video
+    mimeType, not `image/jpeg` guessed from the URL path."""
+    captured = _capture_body(
+        monkeypatch,
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "summarise"},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": "https://www.youtube.com/watch?v=abc",
+                        },
+                    },
+                ],
+            }
+        ],
+    )
+    parts = captured["body"]["contents"][-1]["parts"]
+    yt = next((p for p in parts if "fileData" in p), None)
+    assert yt is not None, parts
+    assert yt["fileData"]["mimeType"].startswith("video/"), yt
+
+
+def test_openai_responses_assistant_text_serialized_before_function_call(
+    monkeypatch,
+):
+    """Round 20: in OpenAI Responses history, the assistant's
+    visible text for a turn that ALSO emitted a function_call must
+    serialize BEFORE the function_call item, matching the prior
+    response.output sequence. Otherwise function_call_output (the
+    role=tool follow-up) appears to follow an unrelated assistant
+    message."""
+    captured: dict = {"input_items": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content.decode("utf-8"))
+        captured["input_items"] = body.get("input")
+        return httpx.Response(
+            200,
+            content = b'data: {"type":"response.completed","response":{"output":[],"usage":{"input_tokens":1,"output_tokens":1}}}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [
+                {"role": "user", "content": "weather?"},
+                {
+                    "role": "assistant",
+                    "content": "Let me check that.",
+                    "tool_calls": [
+                        {
+                            "id": "call_w",
+                            "type": "function",
+                            "function": {
+                                "name": "get_weather",
+                                "arguments": "{}",
+                            },
+                        }
+                    ],
+                },
+                {
+                    "role": "tool",
+                    "content": "sunny",
+                    "tool_call_id": "call_w",
+                    "name": "get_weather",
+                },
+                {"role": "user", "content": "thanks"},
+            ],
+            model = "gpt-5.5",
+            temperature = 0.7,
+            top_p = 1.0,
+            max_tokens = 16,
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+
+    items = captured["input_items"] or []
+    types = [i.get("type") or i.get("role") for i in items]
+    # Expected order:
+    #   user ("weather?")
+    #   assistant ("Let me check that.")
+    #   function_call (get_weather)
+    #   function_call_output (sunny)
+    #   user ("thanks")
+    assert types == [
+        "user",
+        "assistant",
+        "function_call",
+        "function_call_output",
+        "user",
+    ], items
+
+
+def test_gemini_tool_choice_none_disables_image_generation(monkeypatch):
+    """Round 21: `tool_choice="none"` must also flip the implicit
+    image-generation hosted tool off on image-tier models. Otherwise
+    `responseModalities=["TEXT","IMAGE"]` still rides on the outbound
+    body and the provider can generate (and bill for) image output
+    despite the explicit OpenAI tool opt-out."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation"],
+        tool_choice = "none",
+    )
+    body = captured["body"]
+    assert body["generationConfig"].get("responseModalities") == ["TEXT"], body
+
+
+def test_gemini_forced_function_tool_choice_drops_hosted_builtins(monkeypatch):
+    """Round 21: forced-function `tool_choice` (e.g.
+    `{"type":"function","function":{"name":"lookup"}}`) must suppress
+    hosted Google Search / code execution. Gemini's toolConfig only
+    constrains function declarations, not hosted tools, so leaving
+    `googleSearch`/`codeExecution` in `tools[]` lets them fire despite
+    the caller pinning a specific user function."""
+    captured = _capture_body(
+        monkeypatch,
+        enabled_tools = ["web_search", "code_execution"],
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "lookup", "parameters": {"type": "object"}},
+            }
+        ],
+        tool_choice = {
+            "type": "function",
+            "function": {"name": "lookup"},
+        },
+    )
+    body = captured["body"]
+    tool_kinds = [list(t.keys())[0] for t in (body.get("tools") or [])]
+    assert "googleSearch" not in tool_kinds, body
+    assert "codeExecution" not in tool_kinds, body
+    # User function declaration still survives.
+    assert "functionDeclarations" in tool_kinds, body
+
+
+def test_gemini_forced_function_tool_choice_drops_image_generation(monkeypatch):
+    """Round 21: forced-function `tool_choice` must also flip the
+    implicit image-generation hosted tool off on image-tier models."""
+    captured = _capture_body(
+        monkeypatch,
+        model = "gemini-2.5-flash-image",
+        enabled_tools = ["image_generation"],
+        tool_choice = {
+            "type": "function",
+            "function": {"name": "lookup"},
+        },
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "lookup", "parameters": {"type": "object"}},
+            }
+        ],
+    )
+    body = captured["body"]
+    assert body["generationConfig"].get("responseModalities") == ["TEXT"], body
+
+
+def test_gemini_code_execution_native_part_list_replays_per_part_signatures(
+    monkeypatch,
+):
+    """Round 21: merged code-execution history must replay per-part
+    `thoughtSignature`s, not fan one top-level signature across every
+    native subpart. Gemini 3 strict validators reject a signature
+    placed on the wrong part."""
+    history = [
+        {"role": "user", "content": "plot 1+1"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_a",
+                    "type": "function",
+                    "function": {
+                        "name": "code_execution",
+                        "arguments": "{}",
+                    },
+                    "extra_content": {
+                        "google": {
+                            "native_part": {
+                                "parts": [
+                                    {
+                                        "executableCode": {
+                                            "id": "code_a",
+                                            "language": "PYTHON",
+                                            "code": "print(1+1)",
+                                        },
+                                        "thoughtSignature": "SIG-EXEC",
+                                    },
+                                    {
+                                        "codeExecutionResult": {
+                                            "id": "res_a",
+                                            "outcome": "OUTCOME_OK",
+                                            "output": "2\n",
+                                        },
+                                    },
+                                ],
+                            },
+                        },
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_a",
+            "name": "code_execution",
+            "content": "2",
+        },
+        {"role": "user", "content": "next"},
+    ]
+    captured = _capture_body(monkeypatch, messages = history)
+    contents = captured["body"]["contents"]
+    # Locate the assistant turn replayed as native code-exec parts.
+    assistant_turn = next(c for c in contents if c["role"] == "model")
+    parts = assistant_turn["parts"]
+    exec_parts = [p for p in parts if "executableCode" in p]
+    result_parts = [p for p in parts if "codeExecutionResult" in p]
+    assert exec_parts and result_parts, parts
+    assert exec_parts[0].get("thoughtSignature") == "SIG-EXEC", exec_parts[0]
+    # codeExecutionResult had no signature -- must NOT inherit one.
+    assert "thoughtSignature" not in result_parts[0], result_parts[0]
+
+
+def test_gemini_code_execution_legacy_merged_signature_only_on_executable(
+    monkeypatch,
+):
+    """Round 21: backward compatibility for pre-round-21 persisted
+    history that stored merged `native_part` as a single object plus a
+    top-level `thoughtSignature`. The replay branch must attach that
+    signature only to `executableCode` (where Gemini 3 emits it), not
+    fan it across `codeExecutionResult` / `inlineData`."""
+    history = [
+        {"role": "user", "content": "plot 1+1"},
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": "call_b",
+                    "type": "function",
+                    "function": {
+                        "name": "code_execution",
+                        "arguments": "{}",
+                    },
+                    "extra_content": {
+                        "google": {
+                            "native_part": {
+                                "executableCode": {
+                                    "id": "code_b",
+                                    "language": "PYTHON",
+                                    "code": "print(1+1)",
+                                },
+                                "codeExecutionResult": {
+                                    "id": "res_b",
+                                    "outcome": "OUTCOME_OK",
+                                    "output": "2\n",
+                                },
+                                "thoughtSignature": "LEGACY-SIG",
+                            },
+                        },
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_b",
+            "name": "code_execution",
+            "content": "2",
+        },
+        {"role": "user", "content": "next"},
+    ]
+    captured = _capture_body(monkeypatch, messages = history)
+    contents = captured["body"]["contents"]
+    assistant_turn = next(c for c in contents if c["role"] == "model")
+    exec_parts = [p for p in assistant_turn["parts"] if "executableCode" in p]
+    result_parts = [p for p in assistant_turn["parts"] if "codeExecutionResult" in p]
+    assert exec_parts[0].get("thoughtSignature") == "LEGACY-SIG", exec_parts[0]
+    assert "thoughtSignature" not in result_parts[0], result_parts[0]
+
+
+def test_gemini_role_tool_list_content_flattens_to_result_text(monkeypatch):
+    """Round 21: OpenAI-shape role=tool messages may carry list content
+    like `[{"type":"text","text":"result"}]`. Forwarding those parts
+    verbatim into `functionResponse.response.result` yields a list of
+    content-part objects instead of the actual tool output text."""
+    history = [
+        {"role": "user", "content": "look up"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {
+                        "name": "lookup",
+                        "arguments": json.dumps({"q": "x"}),
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "name": "lookup",
+            "content": [{"type": "text", "text": "answer-text"}],
+        },
+        {"role": "user", "content": "next"},
+    ]
+    captured = _capture_body(monkeypatch, messages = history)
+    contents = captured["body"]["contents"]
+    fn_response = None
+    for c in contents:
+        for p in c.get("parts") or []:
+            if isinstance(p, dict) and "functionResponse" in p:
+                fn_response = p["functionResponse"]
+                break
+        if fn_response:
+            break
+    assert fn_response is not None, contents
+    assert fn_response["response"] == {"result": "answer-text"}, fn_response
+
+
+def test_safe_fetch_image_threads_per_request_byte_budget(monkeypatch):
+    """Round 21: the aggregate per-request byte cap must be passed into
+    `_safe_fetch_image_for_gemini` so an oversize URL is refused via
+    Content-Length (short-circuit) rather than fully downloaded then
+    discarded after the fact."""
+    import socket
+
+    captured: dict = {"reads": 0, "content_length_seen": None}
+
+    original_getaddrinfo = socket.getaddrinfo
+
+    def fake_getaddrinfo(host, *args, **kwargs):
+        if host == "cdn.example.com":
+            return [
+                (
+                    socket.AF_INET,
+                    socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("8.8.8.8", 0),
+                )
+            ]
+        return original_getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
+
+    class _StubResp:
+        status = 200
+        # Declared 5 MiB, but caller passes a 1 MiB remaining budget.
+        headers = {
+            "content-type": "image/png",
+            "content-length": str(5 * 1024 * 1024),
+        }
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def read(self, _n = None):
+            captured["reads"] += 1
+            return b"\x00" * (5 * 1024 * 1024)
+
+    class _StubOpener:
+        def open(self, req, timeout = None):
+            return _StubResp()
+
+    monkeypatch.setattr(
+        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
+    )
+
+    res = _drive(
+        ep_mod._safe_fetch_image_for_gemini(
+            "https://cdn.example.com/big.png",
+            "image/png",
+            max_bytes = 1 * 1024 * 1024,
+        )
+    )
+    assert res is None
+    # Refused via Content-Length pre-check, never read.
+    assert captured["reads"] == 0
+
+
+def test_openai_chat_delta_type_includes_tool_calls_and_extra_content():
+    """Round 21: the frontend `OpenAIChatDelta` interface must expose
+    `tool_calls` and `extra_content` so TypeScript callers can consume
+    the Gemini-native stream fields without `any` casts. This test is
+    a static-string assertion against the .ts source; mirrors how other
+    frontend wire-contract tests are pinned from the backend suite."""
+    import os
+
+    here = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    types_path = os.path.join(
+        here, "frontend", "src", "features", "chat", "types", "api.ts"
+    )
+    with open(types_path, "r", encoding = "utf-8") as f:
+        src = f.read()
+    assert "tool_calls?: OpenAIToolCallPart[]" in src, src[:200]
+    assert "extra_content?: Record<string, unknown>" in src, src[:200]
+    assert "boolean | string | null" in src, src[:200]
+
+
+def test_anthropic_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
+    """Round 22: forced-function tool_choice must suppress Anthropic
+    hosted builtins the same way it does for Gemini. Pinning a user
+    function (`tool_choice={"type":"function","function":{"name":...}}`)
+    while also passing `enabled_tools=["web_search","web_fetch",
+    "code_execution"]` should not still fire those server-side."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "anthropic",
+            base_url = "https://api.anthropic.com",
+            api_key = "sk-ant-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "claude-sonnet-4-5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search", "web_fetch", "code_execution"],
+            tool_choice = {
+                "type": "function",
+                "function": {"name": "lookup_record"},
+            },
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    # No hosted tools should be in the body — only the caller's user-
+    # function declarations (which this test doesn't pass any of).
+    tools = body.get("tools") or []
+    hosted_tool_names = {"web_search", "web_fetch", "code_execution"}
+    for tool in tools:
+        assert tool.get("name") not in hosted_tool_names, body
+
+
+def test_openrouter_forced_function_tool_choice_drops_web_plugin(monkeypatch):
+    """Round 22: forced-function tool_choice must drop the OpenRouter
+    web plugin too — caller pinned a user function, OpenRouter must not
+    still attach the hosted web-search plugin."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b"data: [DONE]\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openrouter",
+            base_url = "https://openrouter.ai/api/v1",
+            api_key = "sk-or-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "openai/gpt-5.5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = {
+                "type": "function",
+                "function": {"name": "lookup_record"},
+            },
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    assert body.get("plugins") in (None, []), body
+
+
+def test_kimi_forced_function_tool_choice_skips_web_search_helper(monkeypatch):
+    """Round 22: forced-function tool_choice plus enabled_tools=
+    ["web_search"] on Kimi must NOT route into `_stream_kimi_web_search`.
+    Caller pinned a user function; hosted $web_search should be
+    suppressed for the same privacy/billing reason."""
+    routed_to_helper = {"called": False}
+
+    async def fake_helper(self, *args, **kwargs):  # noqa: ARG001
+        routed_to_helper["called"] = True
+        if False:
+            yield ""  # pragma: no cover
+
+    monkeypatch.setattr(
+        ExternalProviderClient,
+        "_stream_kimi_web_search",
+        fake_helper,
+    )
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = b"data: [DONE]\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "kimi",
+            base_url = "https://api.moonshot.ai/v1",
+            api_key = "sk-kimi-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "kimi-k2.6",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = {
+                "type": "function",
+                "function": {"name": "lookup_record"},
+            },
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    assert not routed_to_helper["called"]
+
+
+def test_openai_responses_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
+    """Round 23: forced-function tool_choice on the OpenAI Responses
+    path must suppress hosted builtins (web_search, shell,
+    image_generation) the same way it does for Gemini / Anthropic /
+    OpenRouter / Kimi. User-defined function tools still flow through
+    so the pinned function can resolve."""
+    captured: dict = {"body": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = b"event: response.completed\ndata: {}\n\n",
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openai",
+            base_url = "https://api.openai.com/v1",
+            api_key = "sk-openai-test",
+        )
+        async for _ in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "gpt-5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search", "code_execution", "image_generation"],
+            tools = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "lookup_record",
+                        "parameters": {"type": "object", "properties": {}},
+                    },
+                },
+            ],
+            tool_choice = {
+                "type": "function",
+                "function": {"name": "lookup_record"},
+            },
+        ):
+            pass
+        await client.close()
+
+    _drive(run())
+    body = captured["body"] or {}
+    tools = body.get("tools") or []
+    hosted_types = {"web_search", "shell", "image_generation"}
+    hosted_seen = {t.get("type") for t in tools if isinstance(t, dict)}
+    assert not (hosted_seen & hosted_types), body
+    # The user function declaration must still be present so the pin
+    # has something to target.
+    user_function_seen = any(
+        isinstance(t, dict) and t.get("type") == "function" for t in tools
+    )
+    assert user_function_seen, body
+    # And the forced-function tool_choice must be forwarded in Responses
+    # shape: `{type:"function", name:"..."}`.
+    tc = body.get("tool_choice")
+    assert isinstance(tc, dict) and tc.get("type") == "function", body
+    assert tc.get("name") == "lookup_record", body
+
+
+def test_strip_provider_synthetic_tool_history_drops_text_only_extra_content():
+    """Round 24: a plain text Gemini reply (no tool_calls) carrying
+    `extra_content.google.thought_signature` must still have that
+    metadata stripped before being forwarded to a local llama-server
+    backend. Without this, switching a Gemini thread mid-stream to a
+    local GGUF model leaks Gemini-only fields to llama-server."""
+    from routes.inference import _strip_provider_synthetic_tool_history
+
+    messages = [
+        {"role": "user", "content": "hi"},
+        {
+            "role": "assistant",
+            "content": "Hello!",
+            "extra_content": {"google": {"thought_signature": "SIG_ABC"}},
+        },
+        {"role": "user", "content": "now in pirate voice"},
+    ]
+    out = _strip_provider_synthetic_tool_history(messages)
+    # Same three turns, but the assistant's `extra_content` is gone.
+    assert [m["role"] for m in out] == ["user", "assistant", "user"]
+    assistant = out[1]
+    assert "extra_content" not in assistant, assistant
+    assert assistant["content"] == "Hello!"
+
+
+def test_validate_and_resolve_host_blocks_shared_address_space():
+    """Round 24 SSRF P1: 100.64.0.0/10 carrier-grade NAT addresses are
+    `is_private=False` AND `is_global=False` per Python's ipaddress
+    docs. The previous denylist (is_private/loopback/link_local/etc.)
+    missed them. Adding `not ip.is_global` as the primary gate covers
+    all non-public ranges, current and future."""
+    import socket as _socket
+    from core.inference import tools as _tools
+
+    orig_getaddrinfo = _socket.getaddrinfo
+
+    def fake_getaddrinfo(hostname, port, *args, **kwargs):
+        if hostname == "shared.example":
+            return [
+                (
+                    _socket.AF_INET,
+                    _socket.SOCK_STREAM,
+                    0,
+                    "",
+                    ("100.64.0.1", port),
+                ),
+            ]
+        return orig_getaddrinfo(hostname, port, *args, **kwargs)
+
+    _socket.getaddrinfo = fake_getaddrinfo
+    try:
+        ok, reason, _ip = _tools._validate_and_resolve_host("shared.example", 443)
+    finally:
+        _socket.getaddrinfo = orig_getaddrinfo
+    assert ok is False, (ok, reason)
+    assert "non-public" in reason.lower() or "100.64.0.1" in reason
+
+
+def test_gemini_custom_oai_compat_base_skips_native_allowlist():
+    """Round 24: a custom Gemini OAI-compatible base (LiteLLM/proxy)
+    must NOT have its model list filtered through the native Gemini
+    allowlist regex. A LiteLLM gateway returning
+    `["google/gemini-2.5-flash", "my-team/gemini", "gemini-2.5-flash"]`
+    should be passed through; the native filter would strip the
+    prefixed IDs even though the chat dispatch routes them via the
+    OpenAI-compatible client."""
+    import asyncio as _asyncio
+
+    from routes import providers as _providers
+    from routes.providers import (
+        ProviderModelsRequest,
+        list_provider_models,
+    )
+
+    captured: dict = {"base": None}
+
+    class _FakeClient:
+        def __init__(self, *, base_url, **kwargs):
+            captured["base"] = base_url
+
+        async def list_models(self):
+            return [
+                {"id": "google/gemini-2.5-flash"},
+                {"id": "my-team/gemini"},
+                {"id": "gemini-2.5-flash"},
+            ]
+
+        async def close(self):
+            return None
+
+    orig = _providers.ExternalProviderClient
+    _providers.ExternalProviderClient = _FakeClient
+    try:
+        req = ProviderModelsRequest(
+            provider_type = "gemini",
+            base_url = "https://litellm.example/v1",
+        )
+        result = _asyncio.run(list_provider_models(req, current_subject = "unsloth"))
+    finally:
+        _providers.ExternalProviderClient = orig
+    ids = {m.id for m in result}
+    # All three IDs survive — the native allowlist was bypassed.
+    assert "google/gemini-2.5-flash" in ids, ids
+    assert "my-team/gemini" in ids, ids
+    assert "gemini-2.5-flash" in ids, ids
+
+
+def test_strip_provider_synthetic_tool_history_drops_synthetic_only():
+    """Round 22: switching a thread from native Gemini (code_execution
+    / image_generation tool_cards in history) to a local GGUF backend
+    must strip the synthetic tool_calls + matching role=tool replies
+    before llama-server sees them. Real user-function tool_calls and
+    their matching tool replies must survive."""
+    from routes.inference import _strip_provider_synthetic_tool_history
+
+    messages = [
+        {"role": "user", "content": "hi"},
+        {
+            "role": "assistant",
+            "content": "let me run it",
+            "tool_calls": [
+                {
+                    "id": "synth_ce_1",
+                    "type": "function",
+                    "function": {
+                        "name": "code_execution",
+                        "arguments": json.dumps(
+                            {
+                                "_server_tool": True,
+                                "google": {"native_part": {"parts": []}},
+                            }
+                        ),
+                    },
+                    "extra_content": {"google": {"thought_signature": "abc"}},
+                },
+                {
+                    "id": "real_lookup",
+                    "type": "function",
+                    "function": {
+                        "name": "lookup_user",
+                        "arguments": json.dumps({"id": 42}),
+                    },
+                },
+            ],
+            "extra_content": {"google": {"thought_signature": "msglevel"}},
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "synth_ce_1",
+            "content": "Gemini-only result text",
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "real_lookup",
+            "content": '{"name": "alice"}',
+        },
+    ]
+    out = _strip_provider_synthetic_tool_history(messages)
+    assistant = next(m for m in out if m.get("role") == "assistant")
+    tcs = assistant["tool_calls"]
+    assert len(tcs) == 1, tcs
+    assert tcs[0]["id"] == "real_lookup"
+    assert "extra_content" not in tcs[0]
+    assert "extra_content" not in assistant
+    tool_msgs = [m for m in out if m.get("role") == "tool"]
+    assert len(tool_msgs) == 1
+    assert tool_msgs[0]["tool_call_id"] == "real_lookup"
+
+
+def test_strip_provider_synthetic_tool_history_drops_empty_assistant():
+    """If every tool_call was synthetic and the assistant turn had no
+    content, the entire turn must be dropped (llama-server rejects
+    empty assistant messages with no tool_calls)."""
+    from routes.inference import _strip_provider_synthetic_tool_history
+
+    messages = [
+        {"role": "user", "content": "draw a sloth"},
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": "synth_imggen",
+                    "type": "function",
+                    "function": {
+                        "name": "image_generation",
+                        "arguments": json.dumps(
+                            {
+                                "google": {
+                                    "native_part": {
+                                        "parts": [
+                                            {
+                                                "inlineData": {
+                                                    "mimeType": "image/png",
+                                                    "data": "Zm9v",
+                                                }
+                                            }
+                                        ]
+                                    }
+                                }
+                            }
+                        ),
+                    },
+                }
+            ],
+        },
+        {"role": "tool", "tool_call_id": "synth_imggen", "content": "(image)"},
+        {"role": "user", "content": "now try in pirate voice"},
+    ]
+    out = _strip_provider_synthetic_tool_history(messages)
+    roles = [m.get("role") for m in out]
+    # The synthetic assistant + its tool reply are both gone; only the
+    # two user turns survive.
+    assert roles == ["user", "user"], out
+
+
+def test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice(
+    monkeypatch,
+):
+    """Round 22 sibling of the round-20 `tool_choice='none'` test: when
+    the caller forces a specific function via `tool_choice={"type":
+    "function", ...}` AND passes `enabled_tools=["web_search"]`, the
+    OpenRouter path must NOT synthesize a fake `web_search` tool card.
+    The plugin was not attached upstream so the UI must not see a
+    server-tool card."""
+    captured_events: list[dict] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            content = (
+                b'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n'
+                b"data: [DONE]\n\n"
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http(monkeypatch, handler)
+
+    async def run():
+        client = ExternalProviderClient(
+            provider_type = "openrouter",
+            base_url = "https://openrouter.ai/api/v1",
+            api_key = "sk-or-test",
+        )
+        async for line in client.stream_chat_completion(
+            messages = [{"role": "user", "content": "hi"}],
+            model = "openai/gpt-5.5",
+            temperature = 0.7,
+            top_p = 0.95,
+            max_tokens = 16,
+            enabled_tools = ["web_search"],
+            tool_choice = {
+                "type": "function",
+                "function": {"name": "lookup_record"},
+            },
+        ):
+            payload = line.strip().removeprefix("data: ")
+            if payload and payload != "[DONE]":
+                try:
+                    captured_events.append(json.loads(payload))
+                except Exception:
+                    pass
+        await client.close()
+
+    _drive(run())
+    for evt in captured_events:
+        for choice in evt.get("choices") or []:
+            delta = choice.get("delta") or {}
+            extra = delta.get("extra_content") or {}
+            tool_event = extra.get("toolEvent") if isinstance(extra, dict) else None
+            if isinstance(tool_event, dict):
+                assert tool_event.get("tool_name") != "web_search", evt
diff --git a/studio/backend/tests/test_openai_code_execution.py b/studio/backend/tests/test_openai_code_execution.py
index 3d179371e3..0b1a65c69e 100644
--- a/studio/backend/tests/test_openai_code_execution.py
+++ b/studio/backend/tests/test_openai_code_execution.py
@@ -269,7 +269,15 @@ def test_shell_call_emits_tool_start_and_end(monkeypatch):
     assert len(ends) == 1
     assert starts[0]["tool_name"] == "code_execution"
     assert starts[0]["tool_call_id"] == "scall_1"
-    assert starts[0]["arguments"] == {"kind": "bash", "command": "ls -la"}
+    # `_server_tool: True` is the synthetic-builtin marker the
+    # backend stamps onto every provider-side tool_start so the
+    # frontend serializer can distinguish hosted tools from
+    # user-declared functions on history replay.
+    assert starts[0]["arguments"] == {
+        "kind": "bash",
+        "command": "ls -la",
+        "_server_tool": True,
+    }
     assert ends[0]["tool_call_id"] == "scall_1"
     assert "total 24" in ends[0]["result"]
 
diff --git a/studio/backend/tests/test_openai_image_generation.py b/studio/backend/tests/test_openai_image_generation.py
index 6d415316d4..f5dee2561a 100644
--- a/studio/backend/tests/test_openai_image_generation.py
+++ b/studio/backend/tests/test_openai_image_generation.py
@@ -207,9 +207,12 @@ def test_image_generation_done_emits_tool_event_chunks(monkeypatch):
     ends = [e for e in image_events if e.get("type") == "tool_end"]
     assert len(starts) == 1, image_events
     assert len(ends) == 1, image_events
+    # `_server_tool: True` marks this as a provider-side synthetic
+    # tool card on the frontend's history serializer.
     assert starts[0]["arguments"] == {
         "kind": "image",
         "prompt": "A photorealistic cat sitting",
+        "_server_tool": True,
         "openai_image_generation_call_id": "img_abc",
     }
     assert ends[0]["image_b64"] == "AAAA"
diff --git a/studio/backend/tests/test_openai_responses_translation.py b/studio/backend/tests/test_openai_responses_translation.py
index 22ccba7058..f177ed5ef3 100644
--- a/studio/backend/tests/test_openai_responses_translation.py
+++ b/studio/backend/tests/test_openai_responses_translation.py
@@ -215,6 +215,254 @@ def test_responses_sse_translates_to_chat_completions_chunks(monkeypatch):
     assert payloads[-1] == "[DONE]"
 
 
+def test_responses_function_call_output_translates_to_delta_tool_calls(monkeypatch):
+    """Round 12: caller-supplied function tools forwarded into /v1/responses
+    must have their `function_call` output items translated back into Chat
+    Completions delta.tool_calls, and the terminal chunk must emit
+    finish_reason="tool_calls" so the frontend's accumulator runs the
+    function instead of seeing finish_reason="stop"."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        events = [
+            {"type": "response.created"},
+            {
+                "type": "response.output_item.done",
+                "item": {
+                    "type": "function_call",
+                    "id": "fc_abc",
+                    "call_id": "call_xyz",
+                    "name": "get_weather",
+                    "arguments": '{"city":"SF"}',
+                },
+            },
+            {"type": "response.completed", "response": {}},
+        ]
+        return httpx.Response(
+            200,
+            content = _responses_sse(events),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http_client(monkeypatch, handler)
+
+    async def run():
+        client = _make_client()
+        lines = await _collect(
+            client._stream_openai_responses(
+                messages = [{"role": "user", "content": "weather?"}],
+                model = "gpt-5.5",
+                temperature = 0.7,
+                top_p = 0.95,
+                max_tokens = None,
+                enable_thinking = None,
+                reasoning_effort = None,
+                tools = [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "get_weather",
+                            "parameters": {
+                                "type": "object",
+                                "properties": {"city": {"type": "string"}},
+                            },
+                        },
+                    }
+                ],
+            )
+        )
+        await client.close()
+        return lines
+
+    lines = _drive(run())
+    payloads = [
+        json.loads(line[len("data:") :].strip())
+        for line in lines
+        if line.startswith("data:") and line[len("data:") :].strip() != "[DONE]"
+    ]
+    tool_call_deltas = [
+        p
+        for p in payloads
+        if isinstance(p, dict)
+        and p.get("choices")
+        and p["choices"][0].get("delta", {}).get("tool_calls")
+    ]
+    assert tool_call_deltas, payloads
+    tc = tool_call_deltas[0]["choices"][0]["delta"]["tool_calls"][0]
+    assert tc["id"] == "call_xyz"
+    assert tc["function"]["name"] == "get_weather"
+    assert tc["function"]["arguments"] == '{"city":"SF"}'
+    # Final chunk reports tool_calls instead of stop.
+    terminal = next(
+        p
+        for p in payloads
+        if isinstance(p, dict)
+        and p.get("choices")
+        and p["choices"][0].get("finish_reason") in ("stop", "tool_calls")
+    )
+    assert terminal["choices"][0]["finish_reason"] == "tool_calls", payloads
+
+
+def test_responses_parallel_function_calls_get_distinct_indices(monkeypatch):
+    """Round 13: parallel function_call items must land on distinct
+    delta.tool_calls[].index slots so index-keyed clients don't
+    collapse the second call into the first."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        events = [
+            {"type": "response.created"},
+            {
+                "type": "response.output_item.done",
+                "item": {
+                    "type": "function_call",
+                    "id": "fc_a",
+                    "call_id": "call_a",
+                    "name": "lookup_a",
+                    "arguments": "{}",
+                },
+            },
+            {
+                "type": "response.output_item.done",
+                "item": {
+                    "type": "function_call",
+                    "id": "fc_b",
+                    "call_id": "call_b",
+                    "name": "lookup_b",
+                    "arguments": "{}",
+                },
+            },
+            {"type": "response.completed", "response": {}},
+        ]
+        return httpx.Response(
+            200,
+            content = _responses_sse(events),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http_client(monkeypatch, handler)
+
+    async def run():
+        client = _make_client()
+        lines = await _collect(
+            client._stream_openai_responses(
+                messages = [{"role": "user", "content": "x"}],
+                model = "gpt-5.5",
+                temperature = 0.7,
+                top_p = 0.95,
+                max_tokens = None,
+                enable_thinking = None,
+                reasoning_effort = None,
+                tools = [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "lookup_a",
+                            "parameters": {"type": "object"},
+                        },
+                    },
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "lookup_b",
+                            "parameters": {"type": "object"},
+                        },
+                    },
+                ],
+            )
+        )
+        await client.close()
+        return lines
+
+    lines = _drive(run())
+    indices: list[int] = []
+    for raw in lines:
+        if not raw.startswith("data:"):
+            continue
+        payload = raw[len("data:") :].strip()
+        if payload == "[DONE]":
+            continue
+        try:
+            obj = json.loads(payload)
+        except Exception:
+            continue
+        delta = (obj.get("choices") or [{}])[0].get("delta") or {}
+        for tc in delta.get("tool_calls") or []:
+            indices.append(tc.get("index"))
+    assert indices == [0, 1], indices
+
+
+def test_responses_follow_up_tool_result_uses_function_call_output_items(monkeypatch):
+    """Round 13: a second turn after a Responses function call must
+    serialize the tool_calls history and tool result as Responses
+    `function_call` / `function_call_output` input items, not as
+    Chat Completions role="tool" content."""
+    captured: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            200,
+            content = _responses_sse(
+                [
+                    {"type": "response.created"},
+                    {"type": "response.completed", "response": {}},
+                ]
+            ),
+            headers = {"content-type": "text/event-stream"},
+        )
+
+    _mock_http_client(monkeypatch, handler)
+
+    async def run():
+        client = _make_client()
+        await _collect(
+            client._stream_openai_responses(
+                messages = [
+                    {"role": "user", "content": "weather?"},
+                    {
+                        "role": "assistant",
+                        "content": "",
+                        "tool_calls": [
+                            {
+                                "id": "call_xyz",
+                                "type": "function",
+                                "function": {
+                                    "name": "get_weather",
+                                    "arguments": '{"city":"SF"}',
+                                },
+                            }
+                        ],
+                    },
+                    {
+                        "role": "tool",
+                        "tool_call_id": "call_xyz",
+                        "content": "sunny",
+                    },
+                    {"role": "user", "content": "thanks"},
+                ],
+                model = "gpt-5.5",
+                temperature = 0.7,
+                top_p = 0.95,
+                max_tokens = None,
+                enable_thinking = None,
+                reasoning_effort = None,
+            )
+        )
+        await client.close()
+
+    _drive(run())
+    items = captured["body"]["input"]
+    types = [it.get("type") or it.get("role") for it in items]
+    assert "function_call" in types, items
+    assert "function_call_output" in types, items
+    fc = next(it for it in items if it.get("type") == "function_call")
+    assert fc["call_id"] == "call_xyz"
+    assert fc["name"] == "get_weather"
+    assert fc["arguments"] == '{"city":"SF"}'
+    fco = next(it for it in items if it.get("type") == "function_call_output")
+    assert fco["call_id"] == "call_xyz"
+    assert fco["output"] == "sunny"
+
+
 def test_responses_response_incomplete_maps_to_length_finish_reason(monkeypatch):
     def handler(request: httpx.Request) -> httpx.Response:
         events = [
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index a5bb4029d1..51cf000863 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -802,6 +802,7 @@ const ReasoningToggle: FC = () => {
           {
             isReasoningProvider:
               selectedExternalProvider?.isReasoningModel === true,
+            baseUrl: selectedExternalProvider?.baseUrl ?? null,
           },
         )
       : null;
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index ce59429762..2ef14b5326 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -25,6 +25,7 @@ import {
   getExternalMinOutputTokens,
   getExternalReasoningCapabilities,
   getProviderCapabilities,
+  isGeminiCustomOpenAICompatBase,
   providerSupportsBuiltinCodeExecution,
   providerSupportsBuiltinImageGeneration,
   providerSupportsBuiltinWebFetch,
@@ -105,6 +106,33 @@ type RunMessage = RunMessages[number];
 /** Tracks which user messages were sent with an audio file (messageId → filename). */
 export const sentAudioNames = new Map<string, string>();
 
+// Synthetic provider-side tool names; backend stamps args._server_tool
+// so user functions with the same name aren't dropped. Mirror of
+// _SERVER_SIDE_BUILTIN_TOOL_NAMES on the backend.
+const SERVER_SIDE_BUILTIN_TOOL_NAMES = new Set<string>([
+  "web_search",
+  "web_fetch",
+  "code_execution",
+  "image_generation",
+]);
+
+/**
+ * Whether a persisted tool-call part is provider-side synthetic and
+ * should be stripped from outbound history. Match on the
+ * args._server_tool marker or a Gemini native_part payload — no shape
+ * heuristic, because user functions can legitimately share a name.
+ */
+function isServerSideBuiltinToolPart(
+  toolNameLower: string,
+  _argsObj: Record<string, unknown> | null,
+  hasServerToolMarker: boolean,
+  hasNativePart: boolean,
+): boolean {
+  if (!SERVER_SIDE_BUILTIN_TOOL_NAMES.has(toolNameLower)) return false;
+  if (hasServerToolMarker) return true;
+  return hasNativePart;
+}
+
 /**
  * Match error messages that indicate the request filled or would fill
  * the KV cache, so the UI can show a dedicated toast pointing at the
@@ -508,21 +536,200 @@ function isAnthropicRefusalMessage(message: RunMessage): boolean {
   return metadata?.custom?.anthropicRefusal === true;
 }
 
-function toOpenAIMessage(message: RunMessage): {
-  role: "system" | "user" | "assistant";
-  content: OpenAIMessageContent;
-} | null {
+function collectAssistantToolCalls(
+  message: RunMessage,
+): Array<{
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+  extra_content?: unknown;
+}> {
+  const out: Array<{
+    id: string;
+    type: "function";
+    function: { name: string; arguments: string };
+    extra_content?: unknown;
+  }> = [];
+  for (const part of message.content ?? []) {
+    if (part.type !== "tool-call") continue;
+    const tc = part as ToolCallMessagePart & {
+      argsText?: string;
+      extra_content?: unknown;
+    };
+    const toolNameLower = (tc.toolName ?? "").toLowerCase();
+    const argsObj =
+      tc.args && typeof tc.args === "object"
+        ? (tc.args as Record<string, unknown>)
+        : null;
+    const argsGoogle =
+      argsObj && typeof argsObj.google === "object" && argsObj.google !== null
+        ? (argsObj.google as Record<string, unknown>)
+        : null;
+    const hasNativePart = Boolean(
+      argsGoogle &&
+        typeof argsGoogle.native_part === "object" &&
+        argsGoogle.native_part !== null,
+    );
+    const hasServerToolMarker = Boolean(
+      argsObj && (argsObj as Record<string, unknown>)._server_tool === true,
+    );
+    const isServerSideBuiltin = isServerSideBuiltinToolPart(
+      toolNameLower,
+      argsObj,
+      hasServerToolMarker,
+      hasNativePart,
+    );
+    if (isServerSideBuiltin) {
+      // Gemini code_execution / image_generation still need to round-
+      // trip the native_part payload for native replay; drop the rest.
+      if (!hasNativePart) continue;
+    }
+    const argumentsStr =
+      typeof tc.argsText === "string" && tc.argsText.length > 0
+        ? tc.argsText
+        : JSON.stringify(tc.args ?? {});
+    const entry: {
+      id: string;
+      type: "function";
+      function: { name: string; arguments: string };
+      extra_content?: unknown;
+    } = {
+      id: tc.toolCallId,
+      type: "function" as const,
+      function: {
+        name: tc.toolName ?? "",
+        arguments: argumentsStr,
+      },
+    };
+    // Promote args.google to extra_content.google so the backend
+    // native_part replay branch can find it. The backend only inspects
+    // extra_content, not function.arguments.
+    if (tc.extra_content !== undefined) {
+      entry.extra_content = tc.extra_content;
+    } else if (argsGoogle) {
+      entry.extra_content = { google: argsGoogle };
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+function collectToolResultMessages(
+  message: RunMessage,
+): Array<{
+  role: "tool";
+  content: string;
+  tool_call_id: string;
+  name?: string;
+}> {
+  const out: Array<{
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+    name?: string;
+  }> = [];
+  for (const part of message.content ?? []) {
+    if (part.type !== "tool-call") continue;
+    const tc = part as ToolCallMessagePart;
+    const result = (tc as { result?: unknown }).result;
+    // Skip provider-side builtins; see isServerSideBuiltinToolPart.
+    const argsObj =
+      tc.args && typeof tc.args === "object"
+        ? (tc.args as Record<string, unknown>)
+        : null;
+    const argsGoogle =
+      argsObj && typeof argsObj.google === "object" && argsObj.google !== null
+        ? (argsObj.google as Record<string, unknown>)
+        : null;
+    const toolNameLower = (tc.toolName ?? "").toLowerCase();
+    const hasServerToolMarker = Boolean(
+      argsObj && argsObj._server_tool === true,
+    );
+    const hasNativePart = Boolean(
+      argsGoogle &&
+        typeof argsGoogle.native_part === "object" &&
+        argsGoogle.native_part !== null,
+    );
+    if (
+      isServerSideBuiltinToolPart(
+        toolNameLower,
+        argsObj,
+        hasServerToolMarker,
+        hasNativePart,
+      )
+    ) {
+      continue;
+    }
+    if (result === undefined || result === null) continue;
+    let content: string;
+    if (typeof result === "string") {
+      // Backend ChatMessage validator rejects role="tool" with empty
+      // content; serialise a sentinel JSON so legitimately empty tool
+      // outputs still round-trip the follow-up turn to the provider.
+      content = result.length > 0 ? result : JSON.stringify({ result: "" });
+    } else {
+      try {
+        content = JSON.stringify(result);
+      } catch {
+        content = String(result);
+      }
+    }
+    out.push({
+      role: "tool",
+      content,
+      tool_call_id: tc.toolCallId,
+      ...(tc.toolName ? { name: tc.toolName } : {}),
+    });
+  }
+  return out;
+}
+
+type SerializedMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: OpenAIMessageContent | null;
+  tool_calls?: Array<{
+    id: string;
+    type: "function";
+    function: { name: string; arguments: string };
+    extra_content?: unknown;
+  }>;
+  tool_call_id?: string;
+  name?: string;
+  /**
+   * Gemini text-part thoughtSignature stashed during streaming on the
+   * last text MessagePart. Backend reads
+   * `extra_content.google.thought_signature` and attaches it to the
+   * matching Gemini text part on the outbound turn.
+   */
+  extra_content?: unknown;
+};
+
+function collectAssistantTextThoughtSignature(
+  message: RunMessage,
+): string | undefined {
+  if (!Array.isArray(message.content)) return undefined;
+  for (let i = message.content.length - 1; i >= 0; i -= 1) {
+    const part = message.content[i] as { type?: string } & Record<
+      string,
+      unknown
+    >;
+    if (part?.type !== "text") continue;
+    const sig = part._google_thought_signature;
+    if (typeof sig === "string" && sig) return sig;
+  }
+  return undefined;
+}
+
+function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
   if (
     message.role !== "system" &&
     message.role !== "user" &&
     message.role !== "assistant"
   ) {
-    return null;
+    return [];
   }
 
   let textContent = collectTextParts(message).join("\n");
-  // Strip inline audio base64 from prior assistant messages to avoid
-  // inflating token counts (e.g. audio-player responses with embedded WAV).
   if (message.role === "assistant") {
     textContent = textContent.replace(
       /data:audio\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/g,
@@ -531,25 +738,70 @@ function toOpenAIMessage(message: RunMessage): {
     if (isAnthropicRefusalMessage(message)) {
       // Prune refused assistant turn from outbound history; the
       // rendered transcript still shows the user-visible notice.
-      return null;
+      return [];
     }
   }
 
   const imageParts = collectImageParts(message);
-  if (imageParts.length > 0) {
-    return {
-      role: message.role,
-      content: [
-        ...(textContent ? [{ type: "text" as const, text: textContent }] : []),
-        ...imageParts,
-      ],
-    };
+  const toolCalls =
+    message.role === "assistant" ? collectAssistantToolCalls(message) : [];
+  const toolResults =
+    message.role === "assistant" ? collectToolResultMessages(message) : [];
+
+  const base: SerializedMessage = {
+    role: message.role,
+    content:
+      imageParts.length > 0
+        ? [{ type: "text", text: textContent }, ...imageParts]
+        : textContent,
+  };
+  if (toolCalls.length > 0) {
+    base.tool_calls = toolCalls;
+    // OpenAI requires content === null on assistant turns whose
+    // payload is entirely tool_calls (matches the wire shape Gemini
+    // expects for the next functionCall replay).
+    if (!textContent && imageParts.length === 0) {
+      base.content = null;
+    }
+  }
+  if (message.role === "assistant") {
+    const sig = collectAssistantTextThoughtSignature(message);
+    if (sig) {
+      base.extra_content = { google: { thought_signature: sig } };
+    }
   }
 
-  if (!textContent) {
+  return toolResults.length > 0 ? [base, ...toolResults] : [base];
+}
+
+// Thin singular wrapper: returns only the first serialized message
+// (without tool_calls or tool follow-ups) so the OpenAI image-edit
+// replay path can map a thread to flat OpenAI chat messages without
+// pulling in tool history.
+function toOpenAIMessage(message: RunMessage): {
+  role: "system" | "user" | "assistant";
+  content: OpenAIMessageContent;
+} | null {
+  const serialized = toOpenAIMessages(message);
+  if (serialized.length === 0) return null;
+  const first = serialized[0];
+  if (
+    first.role !== "system" &&
+    first.role !== "user" &&
+    first.role !== "assistant"
+  ) {
     return null;
   }
-  return { role: message.role, content: textContent };
+  if (first.content === null || first.content === undefined) {
+    return null;
+  }
+  if (typeof first.content === "string" && !first.content) {
+    return null;
+  }
+  return {
+    role: first.role,
+    content: first.content as OpenAIMessageContent,
+  };
 }
 
 function extractImageBase64(input: string): string | undefined {
@@ -1084,11 +1336,21 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         clearSelectedImageEditReference();
         throw new Error("Connection not found.");
       }
-      // Local providers (llama.cpp / vLLM / Ollama) allow an empty key — only block hosted providers.
+      // Local providers and custom Gemini bases allow an empty key.
       const externalProviderIsCustom = externalProvider
         ? isCustomProviderType(externalProvider.providerType)
         : false;
-      if (isExternalRequest && !externalApiKey && !externalProviderIsCustom) {
+      const externalProviderIsGeminiCustomBase = Boolean(
+        externalProvider &&
+          externalProvider.providerType === "gemini" &&
+          isGeminiCustomOpenAICompatBase(externalProvider.baseUrl),
+      );
+      if (
+        isExternalRequest &&
+        !externalApiKey &&
+        !externalProviderIsCustom &&
+        !externalProviderIsGeminiCustomBase
+      ) {
         toast.error("Missing API key for selected connection.", {
           description: "Open Settings → Connections and set the API key again.",
         });
@@ -1096,15 +1358,38 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         throw new Error("Missing connection API key.");
       }
 
+      // Image-generation flag (OpenAI cloud + Responses-capable model).
+      // Computed first so Gemini image mode can suppress Search/Code.
+      const imageGenerationEnabledForThisTurn = Boolean(
+        externalProvider &&
+          externalSelection &&
+          imageToolsEnabled &&
+          providerSupportsBuiltinImageGeneration(
+            externalProvider.providerType,
+            externalSelection.modelId,
+            externalProvider.baseUrl,
+          ),
+      );
+      // Per-model Search/Code allowances live in
+      // providerSupportsBuiltin*; this flag just signals image-mode.
+      const geminiImageModeForThisTurn =
+        externalProvider?.providerType === "gemini" &&
+        imageGenerationEnabledForThisTurn;
       const webSearchEnabledForThisTurn = Boolean(
         externalProvider &&
+          externalSelection &&
           toolsEnabled &&
-          providerSupportsBuiltinWebSearch(externalProvider.providerType),
+          providerSupportsBuiltinWebSearch(
+            externalProvider.providerType,
+            externalSelection.modelId,
+            externalProvider.baseUrl,
+          ),
       );
       const codeExecEnabledForThisTurn = Boolean(
         externalProvider &&
           externalSelection &&
           codeToolsEnabled &&
+          !geminiImageModeForThisTurn &&
           providerSupportsBuiltinCodeExecution(
             externalProvider.providerType,
             externalSelection.modelId,
@@ -1124,20 +1409,6 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         externalProvider &&
           providerSupportsBuiltinWebFetch(externalProvider.providerType),
       );
-      // OpenAI Responses-API image_generation server tool. Pill is
-      // gated on OpenAI cloud + a Responses-API model id; the backend
-      // additionally re-checks is_openai_cloud before appending
-      // {type:"image_generation"} to the request tools array.
-      const imageGenerationEnabledForThisTurn = Boolean(
-        externalProvider &&
-          externalSelection &&
-          imageToolsEnabled &&
-          providerSupportsBuiltinImageGeneration(
-            externalProvider.providerType,
-            externalSelection.modelId,
-            externalProvider.baseUrl,
-          ),
-      );
 
       if (selectedImageEditReference && !imageGenerationEnabledForThisTurn) {
         clearSelectedImageEditReference();
@@ -1148,11 +1419,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         throw new Error("Image generation edit unavailable.");
       }
 
-      // Two-pass build: a refused assistant turn also drops the user
-      // prompt that triggered it (leaving it in context re-triggers
-      // the classifier). Refusal flag rides assistant
-      // metadata.custom.anthropicRefusal, set out-of-band from the
-      // backend _toolEvent.
+      // Drop refused assistant turns + their triggering user prompt;
+      // otherwise context re-triggers the classifier.
       const survivingMessages: RunMessage[] = [];
       for (const message of messages) {
         if (isAnthropicRefusalMessage(message)) {
@@ -1165,8 +1433,11 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         survivingMessages.push(message);
       }
 
+      // toOpenAIMessages emits assistant tool_calls + role="tool"
+      // follow-ups; the backend Gemini translator rebuilds the
+      // functionCall/functionResponse parts (with thoughtSignature).
       const outboundMessages = survivingMessages
-        .map(toOpenAIMessage)
+        .flatMap(toOpenAIMessages)
         .filter((message): message is NonNullable<typeof message> =>
           Boolean(message),
         );
@@ -1189,7 +1460,15 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             break;
           }
         }
-        outboundMessages.splice(insertAt, 0, referenceMessage);
+        // OpenAIChatMessage is a structural superset of SerializedMessage
+        // for the role/content axis the outbound pipeline consumes; cast
+        // through unknown since referenceMessage carries no tool_calls
+        // (the image_edit reference is a plain assistant turn).
+        outboundMessages.splice(
+          insertAt,
+          0,
+          referenceMessage as unknown as SerializedMessage,
+        );
       }
 
       const safeSystemPrompt =
@@ -1271,7 +1550,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             outboundMessages[0] = {
               ...firstMessage,
               content: [
-                ...firstMessage.content,
+                ...(Array.isArray(firstMessage.content)
+                  ? firstMessage.content
+                  : []),
                 { type: "text", text: `\n\n${disabledToolGuard}` },
               ],
             };
@@ -1420,20 +1701,30 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       let cumulativeText = "";
       let reasoningStartAt: number | null = null;
       let reasoningDuration = 0;
-      // Tracks whether we are currently inside a `<think>` block opened by
-      // a `delta.reasoning_content` chunk. Kimi (kimi-k2.6, kimi-k2-thinking)
-      // and DeepSeek's reasoner stream their thinking as a separate
-      // `reasoning_content` field on the chat-completion delta — not as
-      // `content`, not as a structured part. We wrap those chunks with
-      // inline `<think>...</think>` so the existing parseAssistantContent
-      // lifts them into the reasoning panel the same way it does for
-      // local Harmony models. State has to live outside the SSE loop
-      // because the close tag fires when the next chunk carries content
-      // (or when the stream ends).
+      // True while wrapping a `delta.reasoning_content` stream in
+      // <think>...</think> for parseAssistantContent. Lives outside
+      // the SSE loop because the close tag fires when content arrives.
       let reasoningContentOpen = false;
-      // Tool call content parts — accumulated and yielded cumulatively.
-      // result is set directly on the tool-call part when tool_end arrives.
+      // Tool call parts, cumulative; result lands on tool_end.
       const toolCallParts: ToolCallMessagePart[] = [];
+      // Latest Gemini text-part thoughtSignature; pinned onto the final
+      // text MessagePart so next-turn replay carries it.
+      let latestTextThoughtSignature: string | undefined;
+      const pinTextThoughtSignature = <T extends { type: string }>(
+        parts: T[],
+      ): T[] => {
+        if (!latestTextThoughtSignature || parts.length === 0) return parts;
+        for (let i = parts.length - 1; i >= 0; i -= 1) {
+          if (parts[i].type === "text") {
+            parts[i] = {
+              ...parts[i],
+              _google_thought_signature: latestTextThoughtSignature,
+            } as T;
+            break;
+          }
+        }
+        return parts;
+      };
       const orderAssistantContent = (
         textParts: ReturnType<typeof parseAssistantContent>,
       ) => {
@@ -1525,6 +1816,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 {
                   isReasoningProvider:
                     externalProvider.isReasoningModel === true,
+                  baseUrl: externalProvider.baseUrl ?? null,
                 },
               )
             : {
@@ -1557,13 +1849,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
           forceRefreshPublicKey = false,
         ): Promise<OpenAIChatCompletionsRequest> => {
           if (externalSelection && externalProvider) {
-            // OpenAI shell-tool container reuse: pull the per-thread
-            // container_id (if any) so subsequent turns in the same
-            // thread reference the existing container instead of
-            // auto-creating a fresh one. Empty string / undefined →
-            // backend falls back to container_auto. Anthropic uses
-            // the parallel `anthropicCodeExecContainerId` field below
-            // (sent as `container` on /v1/messages).
+            // Per-thread container reuse; empty/undefined falls back to
+            // container_auto. Anthropic uses anthropicCodeExecContainerId.
             let openaiCodeExecContainerId: string | null = null;
             let anthropicCodeExecContainerId: string | null = null;
             if (codeExecEnabledForThisTurn && resolvedThreadId) {
@@ -1577,17 +1864,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 openaiCodeExecContainerId = null;
                 anthropicCodeExecContainerId = null;
               }
-              // Pre-send container validation (OpenAI only). The list
-              // endpoint already filters status==="expired" server-side
-              // (studio/backend/routes/inference.py — list_openai_containers),
-              // so membership in this set means "OpenAI will accept it
-              // as container_reference". A stale id silently dropped here
-              // falls through to the inheritance + lazy-create logic
-              // below, so the user never sees "Container is expired" in
-              // the chat thread. On list-call failure we leave
-              // activeContainerIds null and skip validation — the
-              // backend's transparent retry path is the safety net for
-              // that case.
+              // Pre-send container validation (OpenAI). Stale ids drop
+              // silently and fall through to lazy-create. On list-call
+              // failure, skip and rely on the backend's retry path.
               let activeContainerIds: Set<string> | null = null;
               if (externalProvider.providerType === "openai") {
                 try {
@@ -1610,15 +1889,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   openaiCodeExecContainerId = null;
                 }
               }
-              // Cross-thread inheritance: when the active thread has
-              // no container yet, default to the one most recently
-              // used on *any* other thread (provider-scoped).
-              // Matches what the Code Execution settings section
-              // shows in the picker, and keeps the user from getting
-              // a fresh container on every new thread. The picker
-              // can still be set to "Auto-create per thread"
-              // explicitly to opt into a fresh container — but
-              // that's done via the dropdown, not silently.
+              // Cross-thread inheritance: reuse the most recently used
+              // container from any other thread; opt-out via the picker.
               if (
                 !openaiCodeExecContainerId &&
                 externalProvider.providerType === "openai"
@@ -1651,13 +1923,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   /* fall through to lazy-create below */
                 }
               }
-              // Lazy pre-create when there's no inherited container.
-              // We always POST /v1/containers ourselves (rather than
-              // letting the backend send container_auto) so every
-              // container shows up in the picker with a friendly
-              // English-word name and the user's configured TTL.
-              // Falls back to container_auto only if the POST fails
-              // — keeps the chat moving in that case.
+              // Pre-create our own container (vs container_auto) so it
+              // shows up in the picker with a friendly name and the
+              // configured TTL. Falls back to container_auto on failure.
               if (
                 !openaiCodeExecContainerId &&
                 externalProvider.providerType === "openai"
@@ -1716,22 +1984,13 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   externalSelection?.modelId,
                 ),
               ),
-              // Only forward sampling knobs the provider actually accepts; the
-              // backend's external-provider proxy is param-permissive and would
-              // surface a 400 from providers that reject unknown fields (e.g.
-              // OpenAI rejects top_k, Anthropic/DeepSeek reject presence_penalty).
+              // Forward only sampling knobs the provider accepts.
               ...(externalCapabilities?.topK ? { top_k: params.topK } : {}),
               ...(externalCapabilities?.presencePenalty
                 ? { presence_penalty: params.presencePenalty }
                 : {}),
-              // Built-in tools: Search pill maps to provider-side
-              // web_search (currently OpenAI / Anthropic / OpenRouter /
-              // Kimi); Code pill maps to Anthropic's server-side
-              // code_execution_20250825 tool (Anthropic is the only
-              // external provider that ships one today). Backend
-              // translates enabled_tools into each provider's tool
-              // schema — for Anthropic that's the entries appended to
-              // body["tools"] inside _stream_anthropic.
+              // Compose the enabled_tools list from the active pills;
+              // backend maps each name to the provider's tool schema.
               ...(webSearchEnabledForThisTurn ||
               webFetchEnabledForThisTurn ||
               codeExecEnabledForThisTurn ||
@@ -1740,14 +1999,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     enable_tools: true,
                     enabled_tools: [
                       ...(webSearchEnabledForThisTurn ? ["web_search"] : []),
-                      // web_fetch has its own Fetch pill, independent
-                      // of Search. Anthropic-only today.
                       ...(webFetchEnabledForThisTurn ? ["web_fetch"] : []),
                       ...(codeExecEnabledForThisTurn ? ["code_execution"] : []),
-                      // OpenAI Responses-API only: `image_generation`
-                      // returns inline image_generation_call output
-                      // items; the backend's _stream_openai_responses
-                      // path translates them to assistant tool events.
                       ...(imageGenerationEnabledForThisTurn
                         ? ["image_generation"]
                         : []),
@@ -1783,12 +2036,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       externalProvider.enablePromptCaching ?? true,
                   }
                 : {}),
-              // Anthropic-only: pass the cache TTL the user picked in
-              // Configuration → Provider. Omitted = inherit the default
-              // 5-minute pool. The backend's `_stream_anthropic` only
-              // attaches `cache_control.ttl` when the value is one of
-              // "5m" / "1h" (see external_provider.py near line 1375),
-              // so unknown values are a no-op end-to-end.
+              // Anthropic prompt-cache TTL; unknown values no-op on backend.
               ...(supportsProviderPromptCacheTtl(
                 externalProvider.providerType,
               ) &&
@@ -1896,11 +2144,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 chunk as unknown as { _toolEvent?: Record<string, unknown> }
               )._toolEvent;
               if (toolEvent !== undefined) {
-                // OpenAI shell-tool container persistence — see
-                // ThreadRecord.openaiCodeExecContainerId. The backend
-                // emits these synthetic events on the OpenAI Responses
-                // SSE stream after capturing the container_id from a
-                // response, or detecting an expired-container error.
+                // Persist container_id onto the thread (OpenAI / Anthropic).
                 if (toolEvent.type === "container_ready") {
                   const newContainerId = toolEvent.container_id as
                     | string
@@ -1997,12 +2241,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       typeof imageB64 === "string" &&
                       imageB64
                     ) {
-                      // OpenAI Responses image_generation_call: the
-                      // backend stashes the base64 PNG/WebP/JPEG on
-                      // separate `image_b64` / `image_mime` fields on
-                      // the synthetic _toolEvent so the JSON result
-                      // string stays small enough to log. Repackage as
-                      // a structured result for the dedicated tool UI.
+                      // Backend keeps base64 on separate image_b64 /
+                      // image_mime fields so logs stay small; repackage.
                       parsedResult = {
                         image_b64: imageB64,
                         image_mime:
@@ -2029,27 +2269,104 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     } else {
                       parsedResult = rawResult;
                     }
+                    // Merge tool_end args first, then Gemini native_part.
                     const nextArgs =
                       toolEvent.arguments &&
                       typeof toolEvent.arguments === "object"
                         ? (toolEvent.arguments as ToolCallMessagePart["args"])
                         : undefined;
-                    const mergedArgs = nextArgs
-                      ? { ...(toolCallParts[idx].args ?? {}), ...nextArgs }
-                      : toolCallParts[idx].args;
+                    const mergedArgs: ToolCallMessagePart["args"] = {
+                      ...(toolCallParts[idx].args ?? {}),
+                      ...(nextArgs ?? {}),
+                    } as ToolCallMessagePart["args"];
+                    // Merge tool_end native_part into args.google so the
+                    // outbound translator replays both start (executableCode)
+                    // and end (result / inlineData) on the same turn.
+                    // Concatenate parts so each keeps its own thoughtSignature.
+                    const endGoogle = (
+                      toolEvent as { google?: { native_part?: unknown } }
+                    ).google;
+                    if (
+                      endGoogle &&
+                      typeof endGoogle === "object" &&
+                      endGoogle.native_part &&
+                      typeof endGoogle.native_part === "object"
+                    ) {
+                      const argsObj = mergedArgs as Record<string, unknown>;
+                      const existingGoogle = (argsObj.google ?? {}) as Record<
+                        string,
+                        unknown
+                      >;
+                      const existingNative =
+                        (existingGoogle.native_part as Record<
+                          string,
+                          unknown
+                        >) ?? {};
+                      const endNative = endGoogle.native_part as Record<
+                        string,
+                        unknown
+                      >;
+                      // Extract part entries from either parts:[...] or
+                      // legacy single-object native_part. Legacy
+                      // thoughtSignature always belongs on executableCode.
+                      const collectParts = (
+                        native: Record<string, unknown>,
+                      ): Record<string, unknown>[] => {
+                        if (Array.isArray(native.parts)) {
+                          return (native.parts as unknown[]).filter(
+                            (entry): entry is Record<string, unknown> =>
+                              Boolean(entry) &&
+                              typeof entry === "object" &&
+                              !Array.isArray(entry),
+                          );
+                        }
+                        const out: Record<string, unknown>[] = [];
+                        const legacySig =
+                          typeof native.thoughtSignature === "string"
+                            ? native.thoughtSignature
+                            : typeof native.thought_signature === "string"
+                              ? (native.thought_signature as string)
+                              : null;
+                        for (const key of [
+                          "executableCode",
+                          "codeExecutionResult",
+                          "inlineData",
+                        ] as const) {
+                          const sub = native[key];
+                          if (sub && typeof sub === "object") {
+                            const entry: Record<string, unknown> = {
+                              [key]: sub,
+                            };
+                            if (key === "executableCode" && legacySig) {
+                              entry.thoughtSignature = legacySig;
+                            }
+                            out.push(entry);
+                          }
+                        }
+                        return out;
+                      };
+                      const mergedParts = [
+                        ...collectParts(existingNative),
+                        ...collectParts(endNative),
+                      ];
+                      argsObj.google = {
+                        ...existingGoogle,
+                        native_part: { parts: mergedParts },
+                      };
+                    }
                     toolCallParts[idx] = {
                       ...toolCallParts[idx],
                       args: mergedArgs,
-                      argsText: mergedArgs
-                        ? JSON.stringify(mergedArgs)
-                        : toolCallParts[idx].argsText,
+                      argsText: JSON.stringify(mergedArgs ?? {}),
                       result: parsedResult,
                     };
                   }
                 }
-                // Yield cumulative state so tool UI updates. Search/code tools stay
-                // before the text, while generated images sit after the answer.
-                const textParts = parseAssistantContent(cumulativeText);
+                // Cumulative yield. orderAssistantContent puts search/
+                // code before text and generated images after.
+                const textParts = pinTextThoughtSignature(
+                  parseAssistantContent(cumulativeText),
+                );
                 yield {
                   content: orderAssistantContent(textParts),
                   metadata: {
@@ -2076,11 +2393,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               }
 
               totalChunks += 1;
-              // OpenRouter's free router (openrouter/free) picks a different
-              // underlying free model per request and reports it in every
-              // chunk's top-level `model` field. Latch the first non-empty
-              // value that differs from the requested checkpoint so the
-              // header chip can render "openrouter/free:<chosen>".
+              // Latch the chunk's `model` field so the openrouter/free
+              // chip can show the chosen underlying model.
               if (
                 isExternalRequest &&
                 externalProvider?.providerType === "openrouter" &&
@@ -2099,30 +2413,37 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 }
               }
               const rawDelta = chunk.choices?.[0]?.delta?.content;
-              // Providers like Mistral's magistral return delta.content as an
-              // array of structured parts; normalize to text (with thinking
-              // parts re-wrapped as inline <think> tags) so the rest of the
-              // accumulator stays string-based.
+              // Normalize structured delta.content (mistral magistral) to text.
               const delta = extractDeltaText(rawDelta);
-              // Kimi (kimi-k2.6, kimi-k2-thinking) and DeepSeek reasoner
-              // stream thinking via `delta.reasoning_content` as a plain
-              // string field — separate from `delta.content` which carries
-              // the answer. Wrap reasoning chunks inline as <think>...
-              // </think> so parseAssistantContent treats them like any
-              // other reasoning. The close tag fires when the next chunk
-              // brings content, or when the stream ends.
+              // Latest Gemini text-part thoughtSignature for next-turn replay.
+              const deltaExtraContent = (
+                chunk.choices?.[0]?.delta as
+                  | { extra_content?: unknown }
+                  | undefined
+              )?.extra_content;
+              if (
+                deltaExtraContent &&
+                typeof deltaExtraContent === "object"
+              ) {
+                const eGoogle = (deltaExtraContent as Record<string, unknown>)
+                  .google;
+                if (eGoogle && typeof eGoogle === "object") {
+                  const sig = (eGoogle as Record<string, unknown>)
+                    .thought_signature;
+                  if (typeof sig === "string" && sig) {
+                    latestTextThoughtSignature = sig;
+                  }
+                }
+              }
+              // Kimi / DeepSeek stream thinking via delta.reasoning_content.
+              // Wrap inline as <think>...</think> for parseAssistantContent.
               const rawReasoning = (
                 chunk.choices?.[0]?.delta as
                   | { reasoning_content?: unknown }
                   | undefined
               )?.reasoning_content;
-              // OpenRouter uses a third reasoning shape: a structured
-              // `delta.reasoning_details` array of parts (each carrying
-              // `text`). The router emits this regardless of which
-              // underlying provider it picked, so we extract here and
-              // merge into the same <think>...</think> wrap path used
-              // for Kimi / DeepSeek reasoning_content. See
-              //   https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
+              // OpenRouter ships reasoning as delta.reasoning_details[]
+              // regardless of underlying provider; merge into the same wrap path.
               const rawReasoningDetails = (
                 chunk.choices?.[0]?.delta as
                   | { reasoning_details?: unknown }
@@ -2140,6 +2461,138 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               const reasoning =
                 (typeof rawReasoning === "string" ? rawReasoning : "") +
                 reasoningFromDetails;
+              // OpenAI delta.tool_calls: streams fragments by index;
+              // accumulate into one part. extra_content carries Gemini 3
+              // thoughtSignature for next-turn replay.
+              const rawDeltaToolCalls = (
+                chunk.choices?.[0]?.delta as
+                  | { tool_calls?: unknown }
+                  | undefined
+              )?.tool_calls;
+              if (
+                Array.isArray(rawDeltaToolCalls) &&
+                rawDeltaToolCalls.length > 0
+              ) {
+                for (const tc of rawDeltaToolCalls) {
+                  if (!tc || typeof tc !== "object") continue;
+                  const call = tc as {
+                    id?: string;
+                    index?: number;
+                    function?: { name?: string; arguments?: string };
+                    extra_content?: unknown;
+                  };
+                  const idx =
+                    typeof call.index === "number" ? call.index : undefined;
+                  const stableId = call.id;
+                  // Match an existing fragment by id first (canonical),
+                  // then by index slot. Fall back to a freshly-minted
+                  // tool_call_<n> id for streams that send neither.
+                  let existing = stableId
+                    ? toolCallParts.find((p) => p.toolCallId === stableId)
+                    : undefined;
+                  if (!existing && idx !== undefined) {
+                    existing = toolCallParts.find(
+                      (p) =>
+                        (
+                          p as ToolCallMessagePart & { _delta_index?: number }
+                        )._delta_index === idx,
+                    );
+                  }
+                  const argsFragment = call.function?.arguments ?? "";
+                  if (existing) {
+                    const prevName = existing.toolName ?? "";
+                    const nextName = call.function?.name ?? prevName;
+                    const merged =
+                      (existing.argsText ?? "") + argsFragment;
+                    let parsedArgs:
+                      ToolCallMessagePart["args"] = existing.args ?? {};
+                    if (merged) {
+                      try {
+                        parsedArgs = JSON.parse(
+                          merged,
+                        ) as ToolCallMessagePart["args"];
+                      } catch {
+                        parsedArgs = {
+                          _raw: merged,
+                        } as ToolCallMessagePart["args"];
+                      }
+                    }
+                    const prevExtra = (
+                      existing as ToolCallMessagePart & {
+                        extra_content?: unknown;
+                      }
+                    ).extra_content;
+                    const updated: ToolCallMessagePart & {
+                      _delta_index?: number;
+                      extra_content?: unknown;
+                    } = {
+                      ...(existing as ToolCallMessagePart),
+                      toolName: nextName,
+                      argsText: merged,
+                      args: parsedArgs,
+                      ...(call.extra_content !== undefined
+                        ? { extra_content: call.extra_content }
+                        : prevExtra !== undefined
+                        ? { extra_content: prevExtra }
+                        : {}),
+                      ...(idx !== undefined ? { _delta_index: idx } : {}),
+                    };
+                    const replaceIdx = toolCallParts.indexOf(existing);
+                    if (replaceIdx >= 0) {
+                      toolCallParts[replaceIdx] = updated;
+                    }
+                  } else {
+                    const callId =
+                      stableId ||
+                      `tool_call_${idx ?? toolCallParts.length}`;
+                    const argsText = argsFragment;
+                    let parsedArgs: ToolCallMessagePart["args"] = {};
+                    if (argsText) {
+                      try {
+                        parsedArgs = JSON.parse(
+                          argsText,
+                        ) as ToolCallMessagePart["args"];
+                      } catch {
+                        parsedArgs = {
+                          _raw: argsText,
+                        } as ToolCallMessagePart["args"];
+                      }
+                    }
+                    const fresh: ToolCallMessagePart & {
+                      _delta_index?: number;
+                      extra_content?: unknown;
+                    } = {
+                      type: "tool-call" as const,
+                      toolCallId: callId,
+                      toolName: call.function?.name ?? "",
+                      argsText,
+                      args: parsedArgs,
+                      ...(call.extra_content !== undefined
+                        ? { extra_content: call.extra_content }
+                        : {}),
+                      ...(idx !== undefined ? { _delta_index: idx } : {}),
+                    };
+                    toolCallParts.push(fresh);
+                  }
+                }
+                yield {
+                  content: [
+                    ...toolCallParts,
+                    ...pinTextThoughtSignature(
+                      parseAssistantContent(cumulativeText),
+                    ),
+                  ],
+                  metadata: {
+                    timing: buildTiming(
+                      streamStartTime,
+                      totalChunks,
+                      firstTokenTime,
+                    ),
+                    custom: { reasoningDuration },
+                  },
+                };
+                continue;
+              }
               if (!delta && !reasoning) {
                 continue;
               }
@@ -2165,21 +2618,17 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 }
                 cumulativeText += delta;
               }
-              // Mistral's magistral occasionally emits a trailing
-              // template-literal artifact (e.g. "${response}") at the end of
-              // an otherwise complete answer. It is never part of a real
-              // reply, so strip a trailing `${...}` token from external
-              // provider streams. The regex anchors to end-of-string and is
-              // idempotent — fragments mid-stream (e.g. "${re") leave the
-              // string untouched and only collapse once the closing brace
-              // arrives. Local-model output is left alone.
+              // Strip a trailing ${...} template-literal artifact from
+              // external streams (mistral magistral occasionally emits one).
               if (isExternalRequest) {
                 cumulativeText = cumulativeText.replace(
                   /\s*\$\{[^}]*\}\s*$/,
                   "",
                 );
               }
-              const parts = parseAssistantContent(cumulativeText);
+              const parts = pinTextThoughtSignature(
+                parseAssistantContent(cumulativeText),
+              );
 
               if (
                 parts.some((part) => part.type === "reasoning") &&
@@ -2295,7 +2744,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
 
         yield {
           content: [
-            ...orderAssistantContent(parseAssistantContent(cumulativeText)),
+            ...orderAssistantContent(
+              pinTextThoughtSignature(parseAssistantContent(cumulativeText)),
+            ),
             ...sourceParts,
             ...documentCitationParts,
           ],
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 1783a08281..c4a5f34273 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -728,7 +728,10 @@ export function ChatPage(): ReactElement {
     const reasoningCaps = getExternalReasoningCapabilities(
       provider?.providerType,
       selection.modelId,
-      { isReasoningProvider: provider?.isReasoningModel === true },
+      {
+        isReasoningProvider: provider?.isReasoningModel === true,
+        baseUrl: provider?.baseUrl ?? null,
+      },
     );
     const state = useChatRuntimeStore.getState();
     const preferredEffort = state.reasoningEffort;
@@ -769,6 +772,8 @@ export function ChatPage(): ReactElement {
       : state.reasoningEffort;
     const supportsBuiltinWebSearch = providerSupportsBuiltinWebSearch(
       provider?.providerType,
+      selection.modelId,
+      provider?.baseUrl,
     );
     const supportsBuiltinCodeExecution = providerSupportsBuiltinCodeExecution(
       provider?.providerType,
@@ -968,6 +973,7 @@ export function ChatPage(): ReactElement {
           {
             isReasoningProvider:
               selectedProvider?.isReasoningModel === true,
+            baseUrl: selectedProvider?.baseUrl ?? null,
           },
         );
         const preferredEffort = store.reasoningEffort;
@@ -1009,6 +1015,8 @@ export function ChatPage(): ReactElement {
         store.setCheckpoint(value, null);
         const supportsBuiltinWebSearch = providerSupportsBuiltinWebSearch(
           selectedProvider?.providerType,
+          selectedExternal?.modelId,
+          selectedProvider?.baseUrl,
         );
         const supportsBuiltinCodeExecution = providerSupportsBuiltinCodeExecution(
           selectedProvider?.providerType,
diff --git a/studio/frontend/src/features/chat/external-providers.ts b/studio/frontend/src/features/chat/external-providers.ts
index dddf529068..b10253c280 100644
--- a/studio/frontend/src/features/chat/external-providers.ts
+++ b/studio/frontend/src/features/chat/external-providers.ts
@@ -37,6 +37,13 @@ export interface ExternalProviderConfig {
   updatedAt: number;
 }
 
+// Gemini supports prompt caching, but the wire flow requires a
+// separate POST to /v1beta/cachedContents to create the cache before
+// the generateContent call can reference it; the boolean Studio
+// currently emits on enable_prompt_caching is not enough on its own.
+// Until that two-step orchestration ships we keep the picker off so
+// the toggle does not silently no-op for Gemini users. See
+// https://ai.google.dev/gemini-api/docs/caching.
 const PROMPT_CACHING_PROVIDER_TYPES = new Set(["openai", "anthropic"]);
 
 export function supportsProviderPromptCaching(
diff --git a/studio/frontend/src/features/chat/provider-capabilities.ts b/studio/frontend/src/features/chat/provider-capabilities.ts
index 5adc01ea2b..f550279826 100644
--- a/studio/frontend/src/features/chat/provider-capabilities.ts
+++ b/studio/frontend/src/features/chat/provider-capabilities.ts
@@ -189,7 +189,27 @@ function _inferProviderFromOpenrouterId(
  */
 export function providerSupportsBuiltinWebSearch(
   providerType: string | null | undefined,
+  modelId?: string | null | undefined,
+  baseUrl?: string | null | undefined,
 ): boolean {
+  // Gemini ships grounded search via `tools: [{googleSearch: {}}]` on
+  // every chat-capable model. Most image-tier ids (`-image`,
+  // `nano-banana`) reject text-tool wiring because the
+  // responseModalities path is mutually exclusive with text tools, but
+  // Google explicitly documents Search grounding on the Gemini 3 image
+  // family (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview,
+  // nano-banana-pro). Allow Search on those; hide on older image ids.
+  // Custom Gemini OpenAI-compat proxies (non-Google bases) skip the
+  // native translator on the backend, so native tool envelopes never
+  // reach them -- hide the pill there.
+  if (providerType === "gemini") {
+    if (isGeminiCustomOpenAICompatBase(baseUrl)) return false;
+    const normalized = modelId?.trim().toLowerCase() ?? "";
+    if (normalized && isGeminiImageModel(normalized)) {
+      return geminiImageModelAllowsGoogleSearch(normalized);
+    }
+    return true;
+  }
   return (
     providerType === "openai" ||
     providerType === "anthropic" ||
@@ -319,6 +339,20 @@ export function providerSupportsBuiltinCodeExecution(
       normalized.startsWith(prefix),
     );
   }
+  if (providerType === "gemini") {
+    // Gemini's `tools: [{codeExecution: {}}]` is supported on every
+    // chat-capable model. Image-tier ids (`-image`, `nano-banana`)
+    // reject text-tool wiring because the inline-image path is
+    // mutually exclusive with codeExecution. Custom Gemini
+    // OpenAI-compat proxies skip the native translator on the
+    // backend, so native codeExecution envelopes do not reach them.
+    // Wire-up lives in `_stream_gemini` on the backend; output comes
+    // back inline as executableCode/codeExecutionResult parts. See
+    // https://ai.google.dev/gemini-api/docs/code-execution.
+    if (isGeminiCustomOpenAICompatBase(baseUrl)) return false;
+    if (isGeminiImageModel(normalized)) return false;
+    return normalized.startsWith("gemini-");
+  }
   return false;
 }
 
@@ -351,12 +385,75 @@ export function providerSupportsBuiltinImageGeneration(
   modelId: string | null | undefined,
   baseUrl?: string | null,
 ): boolean {
-  if (providerType !== "openai") return false;
-  if (!isOpenAICloudBaseUrl(baseUrl)) return false;
   const normalized = modelId?.trim().toLowerCase() ?? "";
   if (!normalized) return false;
-  return OPENAI_IMAGE_GENERATION_MODEL_PREFIXES.some((prefix) =>
-    normalized.startsWith(prefix),
+  if (providerType === "openai") {
+    if (!isOpenAICloudBaseUrl(baseUrl)) return false;
+    return OPENAI_IMAGE_GENERATION_MODEL_PREFIXES.some((prefix) =>
+      normalized.startsWith(prefix),
+    );
+  }
+  if (providerType === "gemini") {
+    // Gemini's Nano Banana image-output ids carry either `-image` (e.g.
+    // `gemini-2.5-flash-image`, `gemini-3.1-flash-image-preview`) or the
+    // `nano-banana` alias (`nano-banana-pro-preview`). The backend flips
+    // generationConfig.responseModalities to ["TEXT", "IMAGE"] when one
+    // is picked, and translates inlineData parts into the same image_b64
+    // tool_end envelope the OpenAI path emits so the chat UI renders the
+    // picture inline. Custom Gemini OpenAI-compat proxies skip the
+    // native translator on the backend, so hide the image pill there.
+    // See https://ai.google.dev/gemini-api/docs/image-generation.
+    if (isGeminiCustomOpenAICompatBase(baseUrl)) return false;
+    return normalized.includes("-image") || normalized.includes("nano-banana");
+  }
+  return false;
+}
+
+/**
+ * Whether `modelId` is a Gemini image-output id (Nano Banana family).
+ * Mirrors the backend's `is_image_picker_model` guard so the frontend
+ * hides text-only tool pills (web_search, code_execution) for these.
+ */
+function isGeminiImageModel(modelId: string): boolean {
+  const m = modelId.toLowerCase();
+  return m.includes("-image") || m.includes("nano-banana");
+}
+
+/**
+ * Whether the saved Gemini connection points at a custom
+ * OpenAI-compatible gateway (any non-Google host). The backend
+ * `_is_openai_compatible` mirrors this to route those connections
+ * through `/chat/completions` instead of the native translator, so
+ * native Gemini tool envelopes (googleSearch, codeExecution,
+ * responseModalities) never reach them. Hide the corresponding
+ * Studio pills here so the request, builder, and UI agree.
+ */
+export function isGeminiCustomOpenAICompatBase(
+  baseUrl: string | null | undefined,
+): boolean {
+  if (!baseUrl) return false;
+  try {
+    const host = new URL(baseUrl).hostname.toLowerCase();
+    return host.length > 0 && host !== "generativelanguage.googleapis.com";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the given Gemini image model supports `tools: [{googleSearch: {}}]`.
+ * Google documents Search grounding on the Gemini 3 image family
+ * (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview,
+ * "Nano Banana Pro"); older image ids (gemini-2.5-flash-image) reject
+ * it with "Search as tool is not enabled for this model".
+ */
+function geminiImageModelAllowsGoogleSearch(modelId: string): boolean {
+  const m = modelId.toLowerCase();
+  return (
+    m.startsWith("gemini-3-pro-image") ||
+    m.startsWith("gemini-3.1-flash-image") ||
+    m.startsWith("nano-banana-pro") ||
+    m.startsWith("nano-banana-2")
   );
 }
 
@@ -431,7 +528,20 @@ const PROVIDER_CAPABILITIES: Record<string, ProviderCapabilities> = {
     presencePenalty: false,
   },
   mistral: OPENAI_COMPAT_BASE,
-  gemini: OPENAI_COMPAT_BASE,
+  // Gemini's native generationConfig accepts temperature, topP, topK and
+  // presencePenalty (plus a separate frequencyPenalty we do not surface
+  // today). minP and repetitionPenalty are not part of the contract --
+  // see https://ai.google.dev/api/rest/v1beta/GenerationConfig. Backend
+  // request shaping lives in _stream_gemini in
+  // studio/backend/core/inference/external_provider.py.
+  gemini: {
+    temperature: true,
+    topP: true,
+    topK: true,
+    minP: false,
+    repetitionPenalty: false,
+    presencePenalty: true,
+  },
   // Kimi k2.5/k2.6 are reasoning-class — the API locks temperature and
   // top_p to fixed defaults and 400s on any other value:
   //   "invalid temperature: only 1 is allowed for this model".
@@ -643,6 +753,119 @@ function resolveKimiReasoningCapabilities(modelId: string): ExternalReasoningCap
   return withEnableThinkingStyle();
 }
 
+// Gemini's thinking ladder.
+//   - Gemini 3.x (3 / 3.1 / 3.5, Pro + Flash + Flash-Lite) and the
+//     gemini-pro-latest / gemini-flash-latest aliases use the new
+//     `thinkingConfig.thinkingLevel` string field (LOW/MEDIUM/HIGH/
+//     MINIMAL). Pro tier rejects MINIMAL.
+//   - Gemini 2.5 Flash + 2.5 Pro stay on the integer
+//     `thinkingConfig.thinkingBudget` (0=off on Flash, -1=dynamic,
+//     N>0=cap; Pro rejects 0).
+//   - 2.5 Flash-Lite: no native thinking surfaced; leave it off.
+//   - Image-tier ids (`*-image*`, `nano-banana-pro-preview`): image
+//     generation path -- no reasoning controls.
+const GEMINI3_PRO_PREFIXES = [
+  "gemini-3.5-pro",
+  "gemini-3.1-pro",
+  "gemini-3-pro-preview",
+  "gemini-pro-latest",
+];
+const GEMINI3_FLASH_PREFIXES = [
+  "gemini-3.5-flash",
+  "gemini-3.1-flash",
+  "gemini-3-flash",
+  "gemini-flash-latest",
+  "gemini-flash-lite-latest",
+];
+const GEMINI25_PRO_PREFIXES = [
+  "gemini-2.5-pro",
+];
+const GEMINI25_FLASH_PREFIXES = [
+  "gemini-2.5-flash",
+];
+const GEMINI_IMAGE_HINTS = [
+  "-image",
+  "nano-banana",
+];
+function resolveGeminiReasoningCapabilities(
+  modelId: string,
+): ExternalReasoningCapabilities {
+  const m = modelId.toLowerCase();
+  if (GEMINI_IMAGE_HINTS.some((h) => m.includes(h))) {
+    // Image generation; no thinking knob.
+    return withEnableThinkingStyle();
+  }
+  // Gemini 2.5 Flash-Lite supports `thinkingBudget` with `0` = off and
+  // a positive range starting at 512 (the backend maps "minimal" to
+  // that floor at external_provider._stream_gemini). Check this branch
+  // BEFORE the broader `gemini-2.5-flash` prefix.
+  // https://ai.google.dev/gemini-api/docs/thinking
+  if (m.startsWith("gemini-2.5-flash-lite")) {
+    return withReasoningEffortStyle({
+      supportsReasoning: true,
+      supportsReasoningOff: true,
+      reasoningEffortLevels: [
+        "none",
+        "minimal",
+        "low",
+        "medium",
+        "high",
+        "max",
+      ] as const,
+    });
+  }
+  if (GEMINI3_PRO_PREFIXES.some((p) => m.startsWith(p))) {
+    // Gemini 3.x Pro: thinkingLevel supports low/medium/high per
+    // https://ai.google.dev/gemini-api/docs/thinking and
+    // https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-pro.
+    // Cannot fully disable thinking; "minimal" is rejected on Pro.
+    return withReasoningEffortStyle({
+      supportsReasoning: true,
+      supportsReasoningOff: false,
+      reasoningEffortLevels: ["low", "medium", "high"] as const,
+    });
+  }
+  if (GEMINI3_FLASH_PREFIXES.some((p) => m.startsWith(p))) {
+    // Gemini 3 Flash: thinkingLevel minimal/low/medium/high. Minimal
+    // is the closest to "off" Google offers on Gemini 3.
+    return withReasoningEffortStyle({
+      supportsReasoning: true,
+      supportsReasoningOff: false,
+      reasoningEffortLevels: [
+        "minimal",
+        "low",
+        "medium",
+        "high",
+      ] as const,
+    });
+  }
+  if (GEMINI25_PRO_PREFIXES.some((p) => m.startsWith(p))) {
+    // Gemini 2.5 Pro: thinkingBudget cannot be 0 (API rejects with
+    // "only works in thinking mode"); backend coerces to a small
+    // positive budget. The picker still hides the off switch.
+    return withReasoningEffortStyle({
+      supportsReasoning: true,
+      supportsReasoningOff: false,
+      reasoningEffortLevels: ["low", "medium", "high", "max"] as const,
+    });
+  }
+  if (GEMINI25_FLASH_PREFIXES.some((p) => m.startsWith(p))) {
+    // Gemini 2.5 Flash: thinkingBudget supports 0 = off cleanly.
+    return withReasoningEffortStyle({
+      supportsReasoning: true,
+      supportsReasoningOff: true,
+      reasoningEffortLevels: [
+        "none",
+        "low",
+        "medium",
+        "high",
+        "max",
+      ] as const,
+    });
+  }
+  return withEnableThinkingStyle();
+}
+
 function resolveMistralReasoningCapabilities(modelId: string): ExternalReasoningCapabilities {
   if (modelId === "magistral-medium-latest") {
     return withReasoningEffortStyle({
@@ -665,6 +888,8 @@ function resolveMistralReasoningCapabilities(modelId: string): ExternalReasoning
 export interface ExternalReasoningResolveOptions {
   /** vLLM connection flagged as a reasoning model in provider config. */
   isReasoningProvider?: boolean;
+  /** Provider base URL; used to detect custom Gemini OAI-compat gateways. */
+  baseUrl?: string | null;
 }
 
 // vLLM has no per-model reasoning signal on OpenAI-compat — pin via user toggle.
@@ -740,6 +965,16 @@ export function getExternalReasoningCapabilities(
   }
   if (isKimiProvider) return resolveKimiReasoningCapabilities(modelForMatching);
   if (isMistralProvider) return resolveMistralReasoningCapabilities(modelForMatching);
+  if (normalizedProvider === "gemini") {
+    // Custom Gemini OAI-compat gateways (LiteLLM, proxies) route
+    // through /chat/completions which drops the Gemini-native
+    // thinkingConfig payload. Hide the native thinking ladder so the
+    // UI does not advertise a control the backend cannot honor.
+    if (isGeminiCustomOpenAICompatBase(options?.baseUrl)) {
+      return withEnableThinkingStyle();
+    }
+    return resolveGeminiReasoningCapabilities(modelForMatching);
+  }
   if (!isOpenAIProvider && !isAnthropicProvider) {
     return withEnableThinkingStyle();
   }
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index ba4a897f63..a811125a20 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -396,6 +396,7 @@ export function SharedComposer({
           {
             isReasoningProvider:
               selectedExternalProvider?.isReasoningModel === true,
+            baseUrl: selectedExternalProvider?.baseUrl ?? null,
           },
         )
       : null;
@@ -449,16 +450,36 @@ export function SharedComposer({
   const supportsBuiltinWebFetch = providerSupportsBuiltinWebFetch(
     selectedExternalProvider?.providerType,
   );
-  const searchDisabled =
-    !modelLoaded || !(supportsTools || supportsBuiltinWebSearch);
-  const codeDisabled =
-    !modelLoaded || !(supportsTools || supportsBuiltinCodeExecution);
-  // Images pill is only ever lit on OpenAI cloud's Responses-API models.
-  // No local tool runtime fallback because the only image-generation
-  // server tool we wire today is OpenAI's; local models cannot dispatch
-  // it. Hidden entirely when the active model does not advertise it so
-  // the pill row stays compact for providers without the capability.
+  // Gemini rejects codeExecution alongside image modalities. Search is
+  // blocked on older Gemini image ids but allowed on Gemini 3 image
+  // models -- supportsBuiltinWebSearch already encodes the per-model
+  // allowance, so we only disable Code unconditionally in Gemini
+  // image mode.
+  const isExternalGemini = selectedExternalProvider?.providerType === "gemini";
   const imageDisabled = !modelLoaded || !supportsBuiltinImageGeneration;
+  const imageModeDisablesCode =
+    isExternalGemini && imageToolsEnabled && !imageDisabled;
+  // Image-tier Gemini models always reject codeExecution and reject
+  // web_search on older ids (Gemini 3.x Pro/Flash allow it -- encoded
+  // in supportsBuiltinWebSearch). Don't let the local `supportsTools`
+  // runtime flag re-enable a pill the Gemini backend will silently
+  // drop. Detect "external provider is Gemini AND model is image-tier"
+  // and gate strictly on the provider builtin support.
+  const isGeminiImageTier =
+    isExternalGemini && supportsBuiltinImageGeneration;
+  const searchDisabled =
+    !modelLoaded ||
+    (isGeminiImageTier
+      ? !supportsBuiltinWebSearch
+      : !(supportsTools || supportsBuiltinWebSearch));
+  const codeDisabled =
+    !modelLoaded ||
+    (isGeminiImageTier
+      ? true
+      : !(supportsTools || supportsBuiltinCodeExecution)) ||
+    imageModeDisablesCode;
+  // Images pill is only ever lit on OpenAI cloud's Responses-API models
+  // and Gemini Nano Banana family. No local tool runtime fallback.
   const showImagePill = supportsBuiltinImageGeneration;
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 5238875b71..d313b43438 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -219,9 +219,34 @@ export type OpenAIMessageContentPart =
 
 export type OpenAIMessageContent = string | OpenAIMessageContentPart[];
 
+/**
+ * OpenAI Chat Completions tool_call shape. Assistant turns echo back
+ * function/tool calls as `tool_calls`; the matching tool result rides
+ * on a separate `role="tool"` message keyed by `tool_call_id`.
+ * `extra_content.google.thought_signature` is the Gemini-specific
+ * round-trip field the backend translator both emits (on `delta.
+ * tool_calls`) and consumes (when rebuilding the native functionCall
+ * part on the next turn).
+ */
+export interface OpenAIToolCallPart {
+  id?: string;
+  type?: "function";
+  function?: {
+    name?: string;
+    arguments?: string;
+  };
+  extra_content?: unknown;
+}
+
 export interface OpenAIChatMessage {
-  role: "system" | "user" | "assistant";
-  content: OpenAIMessageContent;
+  role: "system" | "user" | "assistant" | "tool";
+  content: OpenAIMessageContent | null;
+  /** Assistant tool-call deltas, when the turn invoked a function tool. */
+  tool_calls?: OpenAIToolCallPart[];
+  /** `role="tool"` only: id matching `assistant.tool_calls[].id`. */
+  tool_call_id?: string;
+  /** `role="tool"` only: name of the function that produced the result. */
+  name?: string;
 }
 
 export interface OpenAIChatCompletionsRequest {
@@ -262,7 +287,14 @@ export interface OpenAIChatCompletionsRequest {
   external_model?: string;
   encrypted_api_key?: string;
   provider_base_url?: string | null;
-  enable_prompt_caching?: boolean | null;
+  /**
+   * Boolean toggle for OpenAI/Anthropic ephemeral cache_control. For
+   * Gemini the backend also accepts the cached-content resource name
+   * (`cachedContents/...`) as a string, which is forwarded as
+   * `generationConfig.cachedContent` on the native streamGenerateContent
+   * request.
+   */
+  enable_prompt_caching?: boolean | string | null;
   /**
    * OpenAI shell-tool container id captured from the prior response in
    * this chat thread. When set and the Code pill is on, the backend
@@ -292,7 +324,20 @@ export interface OpenAIChatCompletionsRequest {
 
 export interface OpenAIChatDelta {
   role?: string;
-  content?: string;
+  content?: string | null;
+  /**
+   * Streamed assistant tool calls. The Gemini and OpenAI Responses
+   * translators emit incremental `tool_calls` deltas (function name +
+   * arguments fragments) so the chat-adapter can render tool cards as
+   * they arrive.
+   */
+  tool_calls?: OpenAIToolCallPart[];
+  /**
+   * Provider-specific passthrough. Gemini ships `thoughtSignature`,
+   * citations, `native_part`, etc., here so the round-trip can replay
+   * them on follow-up turns without bleeding into other providers.
+   */
+  extra_content?: Record<string, unknown>;
 }
 
 export interface OpenAIChatChunkChoice {

From 9a907a8acb1a5e62c81158b38c9b11bd670d7370 Mon Sep 17 00:00:00 2001
From: Nilay <118994073+NilayYadav@users.noreply.github.com>
Date: Wed, 27 May 2026 19:31:11 +0530
Subject: [PATCH 011/222] Studio: add remote MCP server support (#5750)

* added remote MCP server support

* trim

* added tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* increased timeout

* disabling MCP chat toggle

* Fix MCP OpenAI function-name validation + cancel propagation for PR #5750

OpenAI requires function.name to match ^[a-zA-Z0-9_-]{1,64}$ before
streaming starts. The existing 64-char length check is necessary but
not sufficient: MCP servers can return tool names containing '.', '/',
spaces, etc. that would 400 the whole chat request. Validate the
composed mcp__<server_id>__<tool> name against the regex, skip + warn
on miss, and drop duplicate tool names from the same server (which
would also 400 the request as "duplicates").

Also propagate the agentic-loop cancel_event into MCP tool execution
so a /cancel POST during a long-running MCP call (e.g. GitHub MCP
search across a large repo) actually interrupts the in-flight HTTP
call instead of waiting out the 300 s timeout. The watcher polls the
threading.Event at 50 ms cadence inside the asyncio loop (matches
routes/inference.py's existing cancel-watcher cadence) and races
against the call task with asyncio.wait FIRST_COMPLETED.

Tests added:
  - test_mcp_specs_skip_invalid_openai_function_names: drops bad chars
  - test_mcp_specs_skip_empty_tool_name
  - test_mcp_specs_drops_duplicate_names
  - test_call_tool_sync_respects_pre_set_cancel_event

Also fix test_desktop_auth.py's router stub that listed every existing
router but missed mcp_servers_router, so importing main.py fails after
this PR adds it to routes/__init__.py.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* PR #5750 round 2: OAuth cleanup on delete/url-change + mcp_enabled standalone

Round 2 of cross-platform validation surfaced two more P1 findings:

1. OAuth tokens never get cleared. fastmcp keys tokens by MCP URL, not by
   server row, and delete / URL change / use_oauth toggle only updated
   the SQLite row. Re-registering the same URL would silently reuse the
   old account's credentials. Adds clear_oauth_tokens_async() in
   mcp_client.py and calls it from the delete + put route handlers when
   the row had use_oauth=True and either the URL changes or OAuth is
   turned off.

2. mcp_enabled=true was ignored unless the caller also sent
   enable_tools=true. The frontend always sends both together so the UI
   path was fine, but a direct API caller sending only mcp_enabled would
   silently get no MCP tools, which contradicts the field's documented
   "append tools from every enabled MCP server" behavior. Loosens the
   use_tools gate in both the GGUF and safetensors paths so mcp_enabled
   opens the tool loop on its own; when the caller did not also opt
   into built-ins, the built-in list starts empty.

Tests added:
  - test_clear_oauth_tokens_async_no_op_safe
  - test_delete_server_calls_oauth_cleanup_when_oauth_was_on
  - test_delete_server_skips_oauth_cleanup_when_oauth_off
  - test_update_server_clears_oauth_on_url_change
  - test_update_server_clears_oauth_when_oauth_disabled

26 backend MCP tests pass; full studio/backend suite 1710 passed locally.
Cross-platform CI (Linux, macOS, Windows) green on staging fork.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* PR #5750 round 3: reject null bool updates + /test surfaces 400

Round 3 of cross-platform validation:

1. PUT /api/mcp/servers/<id> would 500 with TypeError when the body
   explicitly set is_enabled or use_oauth to null. Pydantic accepts
   None for an Optional[bool] and _changes_from_payload then passed
   None into mcp_servers_db.update_server, which int(None)d. Reject
   explicit null at the validation layer with 400 instead.

2. POST /api/mcp/servers/test caught HTTPException under
   "except Exception", so an invalid URL came back as HTTP 200 with
   {"ok": false, "error": "400: ..."} instead of a real 400. The
   create + update paths return 400 for the same input. Move
   validation outside the transport try/except so it surfaces 400.

Tests added:
  - test_changes_from_payload_rejects_null_is_enabled
  - test_changes_from_payload_rejects_null_use_oauth
  - test_test_endpoint_surfaces_url_validation_as_400

* PR #5750 round 4: hyphenated MCP tool names + empty-tool-list gate

Round 4 surfaces two more interaction bugs between the new MCP path
and existing safetensors tool plumbing:

1. OpenAI accepts ^[a-zA-Z0-9_-]{1,64}$ for function.name, and round 1
   widened the MCP regex to that set, so MCP tools can now be advertised
   as `mcp__srv__list-issues`. But the XML tool-call parser in
   tool_call_parser.py used `\w+` (no hyphen), so the model could call
   the tool but Studio could not parse the call. Same in
   routes/inference.py's `_TOOL_XML_RE` stripper, which would leave
   hyphenated tool-call XML in the visible content. Both regexes now
   use `[\w-]+`.

2. safetensors_agentic treats `tools=[]` as "allow all" (documented
   contract, exercised by test_empty_tools_list_does_not_enforce_allowlist).
   When a caller sends `enable_tools=true` + `enabled_tools=[]` +
   `mcp_enabled=true` and MCP discovery returns 0, the resolved tool
   list is genuinely empty and built-in tools (web_search / python /
   terminal) could execute via the model's emitted call. Fix at the
   route gate instead of breaking the documented contract: set
   `use_tools=False` when the resolved list is empty, in both GGUF and
   safetensors paths. Existing callers who omit `enabled_tools` still
   get ALL_TOOLS and are unaffected.

Tests added (32 total):
  - test_tool_xml_parser_handles_hyphenated_function_names
  - test_tool_xml_strip_handles_hyphenated_function_names
  - test_safetensors_agentic_empty_allowlist_still_means_allow_all
    (documents the contract round 4 preserved)

1716 passed locally; cross-platform CI on staging fork still green.

* PR #5750 round 5: GGUF allow-list + CLI policy + hyphenated params + cancel race

Round 5 of parallel-reviewer aggregation surfaced six additional
findings; five are real and fixed here:

1. Hyphenated MCP parameter names (`<parameter=issue-number>`) were
   dropped by the XML parser's `\w+` regex. Extended to `[\w-]+` in
   both core/inference/tool_call_parser.py and core/tool_healing.py.
   The latter is GGUF's own copy of the parser/strip patterns and was
   missed by round 4.

2. core/tool_healing.py's `strip_tool_call_markup` still used
   `<function=\w+>` so hyphenated MCP tool-call XML leaked into the
   GGUF visible content even after round 4 fixed the shared parser.

3+4. `mcp_enabled` re-opened the tool loop even when the operator
   passed `unsloth run --disable-tools` (CLI policy False). Round 2's
   `(_tools_on or payload.mcp_enabled)` gate ignored the raw process
   policy. Now reads `state.tool_policy.get_tool_policy()` and gates
   mcp_enabled on `_cli_policy is not False`. Applied to both GGUF
   and safetensors paths.

5. GGUF's agentic loop called `execute_tool(tool_name, ...)` without
   checking the model-emitted name against the per-request tool list,
   while the safetensors loop already enforces this. Added the same
   allow-list check so a model that hallucinates a filtered MCP name
   or a built-in the caller opted out of returns "not enabled" instead
   of executing.

Bonus P2 fixes:
  - `call_tool_sync` now checks `cancel_event.is_set()` BEFORE
    creating the call task, so a pre-set cancellation does not open
    the HTTP transport.
  - `clear_oauth_tokens_async` moved the OAuth import + construction
    inside the protected try block; a fastmcp.client.auth load error
    used to escape and 500 the delete / update route.

NOT fixed (verified false or out of scope):
  - finding #10 "structured_content vs structuredContent": fastmcp's
    CallToolResult dataclass uses snake_case (verified live against
    structured-only tool result; fields are
    `dict_keys(['content', 'structured_content', 'meta', 'data', 'is_error'])`).
  - finding #11 "asyncio.run from running loop": call_tool_sync is
    invoked from `asyncio.to_thread` worker threads which have no
    event loop; asyncio.run() is safe there.

Tests added (37 total): hyphenated param names, tool_healing strip,
GGUF allow-list gate, cancel pre-set short-circuit, OAuth cleanup
constructor-error swallowing. 1721 passed locally, no regressions.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <danielhanchen@gmail.com>
---
 studio/backend/core/inference/llama_cpp.py    |  31 +-
 studio/backend/core/inference/mcp_client.py   | 181 +++++
 .../core/inference/tool_call_parser.py        |  13 +-
 studio/backend/core/inference/tools.py        | 114 ++++
 studio/backend/core/tool_healing.py           |  13 +-
 studio/backend/main.py                        |   2 +
 studio/backend/models/inference.py            |   4 +
 studio/backend/models/mcp_servers.py          |  46 ++
 studio/backend/requirements/extras.txt        |   1 -
 studio/backend/requirements/studio.txt        |   1 +
 studio/backend/routes/__init__.py             |   2 +
 studio/backend/routes/inference.py            |  62 +-
 studio/backend/routes/mcp_servers.py          | 223 ++++++
 studio/backend/storage/mcp_servers_db.py      | 142 ++++
 studio/backend/tests/test_desktop_auth.py     |   1 +
 studio/backend/tests/test_mcp_servers.py      | 632 ++++++++++++++++++
 .../components/assistant-ui/tool-fallback.tsx |  15 +-
 .../src/features/chat/api/chat-adapter.ts     |   4 +-
 .../src/features/chat/api/mcp-servers-api.ts  | 116 ++++
 .../features/chat/chat-mcp-servers-dialog.tsx | 497 ++++++++++++++
 .../src/features/chat/chat-settings-sheet.tsx |  76 +++
 .../chat/stores/chat-runtime-store.ts         |   9 +
 22 files changed, 2157 insertions(+), 28 deletions(-)
 create mode 100644 studio/backend/core/inference/mcp_client.py
 create mode 100644 studio/backend/models/mcp_servers.py
 create mode 100644 studio/backend/routes/mcp_servers.py
 create mode 100644 studio/backend/storage/mcp_servers_db.py
 create mode 100644 studio/backend/tests/test_mcp_servers.py
 create mode 100644 studio/frontend/src/features/chat/api/mcp-servers-api.ts
 create mode 100644 studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 76234386aa..0325620b2d 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -5076,13 +5076,30 @@ class LlamaCppBackend:
                         _effective_timeout = (
                             None if tool_call_timeout >= 9999 else tool_call_timeout
                         )
-                        result = execute_tool(
-                            tool_name,
-                            arguments,
-                            cancel_event = cancel_event,
-                            timeout = _effective_timeout,
-                            session_id = session_id,
-                        )
+                        # Guard against the model emitting a tool not in the
+                        # per-request advertised set: filtered MCP names, a
+                        # built-in the caller opted out of, or a stale name
+                        # from a prior turn. Mirrors the safetensors loop's
+                        # allowed_tool_names check.
+                        _allowed = {
+                            (t.get("function") or {}).get("name")
+                            for t in (tools or [])
+                            if (t.get("function") or {}).get("name")
+                        }
+                        if _allowed and tool_name not in _allowed:
+                            result = (
+                                f"Error: tool '{tool_name}' is not enabled "
+                                "for this request. Use one of the enabled "
+                                "tools or provide a final answer."
+                            )
+                        else:
+                            result = execute_tool(
+                                tool_name,
+                                arguments,
+                                cancel_event = cancel_event,
+                                timeout = _effective_timeout,
+                                session_id = session_id,
+                            )
 
                     yield {
                         "type": "tool_end",
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
new file mode 100644
index 0000000000..a5e614899d
--- /dev/null
+++ b/studio/backend/core/inference/mcp_client.py
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+MCP_TOOL_PREFIX = "mcp__"
+
+_oauth_token_store = None
+
+
+def parse_server_headers(server: dict) -> Optional[dict]:
+    raw = server.get("headers_json")
+    if not raw:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _oauth_store():
+    global _oauth_token_store
+    if _oauth_token_store is None:
+        from key_value.aio._utils.sanitization import AlwaysHashStrategy
+        from key_value.aio.stores.filetree import FileTreeStore
+        from utils.paths.storage_roots import ensure_dir, studio_root
+
+        # Hash keys/collections — fastmcp uses raw URLs like https://x.com as
+        # keys and FileTreeStore would treat the "://" as nested directories.
+        _oauth_token_store = FileTreeStore(
+            data_directory = ensure_dir(studio_root() / "mcp-oauth-tokens"),
+            key_sanitization_strategy = AlwaysHashStrategy(),
+            collection_sanitization_strategy = AlwaysHashStrategy(),
+        )
+    return _oauth_token_store
+
+
+async def clear_oauth_tokens_async(url: str) -> None:
+    """Drop any persisted OAuth tokens for ``url``. fastmcp keys tokens by
+    MCP URL, so on server delete / URL change / OAuth disable we have to
+    clear the old credentials explicitly. Otherwise re-registering the
+    same URL would silently reuse the old account's token. The entire
+    body runs inside the protected block -- store / OAuth construction
+    failing must not make the delete / update route 500."""
+    try:
+        from fastmcp.client.auth import OAuth
+
+        auth = OAuth(mcp_url = url, token_storage = _oauth_store())
+        await auth.token_storage_adapter.clear()
+    except Exception as exc:  # noqa: BLE001
+        # Cleanup is best-effort; the row delete still wins.
+        logger.warning("Failed to clear OAuth tokens for %s: %s", url, exc)
+
+
+def _client(url: str, headers: Optional[dict], use_oauth: bool = False):
+    from fastmcp import Client
+    from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+    from fastmcp.mcp_config import infer_transport_type_from_url
+
+    auth = None
+    if use_oauth:
+        from fastmcp.client.auth import OAuth
+
+        auth = OAuth(mcp_url = url, token_storage = _oauth_store())
+
+    transport_cls = (
+        SSETransport
+        if infer_transport_type_from_url(url) == "sse"
+        else StreamableHttpTransport
+    )
+    return Client(transport_cls(url = url, headers = headers or None, auth = auth))
+
+
+async def list_tools_async(
+    url: str,
+    headers: Optional[dict] = None,
+    timeout: float = 5.0,
+    use_oauth: bool = False,
+) -> list[dict]:
+    async def _fetch() -> list[dict]:
+        async with _client(url, headers, use_oauth) as client:
+            tools = await client.list_tools()
+        return [t.model_dump(exclude_none = True) for t in tools]
+
+    return await asyncio.wait_for(_fetch(), timeout = timeout)
+
+
+def _flatten_result(result: Any) -> str:
+    parts = []
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if text:
+            parts.append(str(text))
+    body = "\n".join(parts)
+    if not body:
+        structured = getattr(result, "structured_content", None)
+        body = str(structured) if structured is not None else ""
+
+    if getattr(result, "is_error", False):
+        # "Error: " prefix triggers tool_call_parser's TOOL_ERROR_PREFIXES nudge.
+        return f"Error: {body}" if body else "Error: tool returned no content"
+    return body
+
+
+def call_tool_sync(
+    url: str,
+    headers: Optional[dict],
+    name: str,
+    args: dict,
+    timeout: Optional[float] = 300.0,
+    use_oauth: bool = False,
+    cancel_event = None,
+) -> str:
+    """Synchronously call an MCP tool.
+
+    ``cancel_event``: optional ``threading.Event``. When set, the in-flight
+    HTTP call is cancelled and the function returns a cancellation Error.
+    Polled in parallel with the tool call via ``asyncio.wait`` so a /cancel
+    POST from the UI interrupts even mid-network-read.
+    """
+
+    async def _call() -> Any:
+        async with _client(url, headers, use_oauth) as client:
+            return await client.call_tool(name, args)
+
+    async def _watch_cancel() -> None:
+        # 50 ms cadence keeps cancellation responsive without busy-looping;
+        # matches the cadence routes/inference.py uses for cancel watchers.
+        while cancel_event is not None and not cancel_event.is_set():
+            await asyncio.sleep(0.05)
+
+    async def _race() -> Any:
+        # Check cancellation before spawning the call task so a pre-set
+        # event short-circuits before opening the transport / HTTP
+        # connection (reviewer-reproduced race).
+        if cancel_event is not None and cancel_event.is_set():
+            raise _MCPCancelled
+        call_task = asyncio.create_task(_call())
+        if cancel_event is None:
+            return await asyncio.wait_for(call_task, timeout = timeout)
+        watch_task = asyncio.create_task(_watch_cancel())
+        try:
+            done, pending = await asyncio.wait(
+                {call_task, watch_task},
+                timeout = timeout,
+                return_when = asyncio.FIRST_COMPLETED,
+            )
+        finally:
+            for t in (call_task, watch_task):
+                if not t.done():
+                    t.cancel()
+        if not done:
+            raise asyncio.TimeoutError
+        if call_task in done:
+            return call_task.result()
+        raise _MCPCancelled
+
+    try:
+        result = asyncio.run(_race())
+    except _MCPCancelled:
+        return f"Error: MCP tool '{name}' cancelled"
+    except asyncio.TimeoutError:
+        return f"Error: MCP tool '{name}' timed out after {timeout:g}s"
+    except Exception as exc:
+        logger.exception("MCP call_tool failed for %s: %s", name, exc)
+        return f"Error: MCP tool '{name}' failed: {exc}"
+
+    return _flatten_result(result)
+
+
+class _MCPCancelled(Exception):
+    """Internal sentinel raised when cancel_event fires before the tool returns."""
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index a0ab8a2a53..2f94990623 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -13,13 +13,16 @@ import re
 
 # _TOOL_CLOSED_PATS: closed pairs only. _TOOL_ALL_PATS: also trailing
 # unclosed runs so truncated tails don't leak markup.
+# Function-name char set tracks OpenAI's ^[a-zA-Z0-9_-]{1,64}$ so MCP
+# tool names that contain a hyphen (e.g. mcp__srv__list-issues) parse
+# the same as the built-in web_search/python/terminal names.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
-    re.compile(r"<function=\w+>.*?</function>", re.DOTALL),
+    re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
 ]
 _TOOL_ALL_PATS = _TOOL_CLOSED_PATS + [
     re.compile(r"<tool_call>.*$", re.DOTALL),
-    re.compile(r"<function=\w+>.*$", re.DOTALL),
+    re.compile(r"<function=[\w-]+>.*$", re.DOTALL),
 ]
 
 
@@ -60,10 +63,12 @@ BUDGET_EXHAUSTED_NUDGE = (
 
 # Pre-compiled patterns reused by ``parse_tool_calls_from_text``.
 _TC_JSON_START_RE = re.compile(r"<tool_call>\s*\{")
-_TC_FUNC_START_RE = re.compile(r"<function=(\w+)>\s*")
+_TC_FUNC_START_RE = re.compile(r"<function=([\w-]+)>\s*")
 _TC_END_TAG_RE = re.compile(r"</tool_call>")
 _TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
-_TC_PARAM_START_RE = re.compile(r"<parameter=(\w+)>\s*")
+# Parameter names can carry hyphens too (e.g. MCP tool schemas with
+# `issue-number`, `repo-name`); using `\w+` here dropped those keys.
+_TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>\s*")
 _TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
 
 
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 35d5903826..9572a2169a 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -14,6 +14,7 @@ import signal
 
 os.environ["UNSLOTH_IS_PRESENT"] = "1"
 
+import asyncio
 import random
 import re
 import shlex
@@ -24,6 +25,14 @@ import tempfile
 import threading
 import urllib.request
 
+from core.inference.mcp_client import (
+    MCP_TOOL_PREFIX,
+    call_tool_sync,
+    list_tools_async,
+    parse_server_headers,
+)
+from storage import mcp_servers_db
+
 from loggers import get_logger
 
 logger = get_logger(__name__)
@@ -505,6 +514,92 @@ TERMINAL_TOOL = {
 ALL_TOOLS = [WEB_SEARCH_TOOL, PYTHON_TOOL, TERMINAL_TOOL]
 
 
+# OpenAI's function.name regex: ^[a-zA-Z0-9_-]{1,64}$ -- enforced before
+# streaming starts. MCP servers can return tool names containing '.', '/',
+# spaces, etc., which the prefix scheme would forward to OpenAI verbatim
+# and 400 the whole request. Validate up front and skip with a warning.
+_OPENAI_FN_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
+
+
+def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
+    """Convert an MCP server's tool list into OpenAI function specs."""
+    display = server.get("display_name") or server["id"]
+    specs: list[dict] = []
+    seen_names: set[str] = set()
+    for tool in mcp_tools:
+        raw_name = tool.get("name") or ""
+        if not raw_name:
+            logger.warning("Skipping MCP tool on '%s': empty name.", display)
+            continue
+        name = f"{MCP_TOOL_PREFIX}{server['id']}__{raw_name}"
+        # OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; bad chars
+        # (., /, spaces, etc.) or oversized names would 400 the whole
+        # request. Skip + warn so the rest of the tools still ship.
+        if not _OPENAI_FN_NAME_RE.fullmatch(name):
+            logger.warning(
+                "Skipping MCP tool '%s' on '%s': composed name '%s' is not "
+                "valid OpenAI function.name (regex ^[a-zA-Z0-9_-]{1,64}$).",
+                raw_name,
+                display,
+                name,
+            )
+            continue
+        # Same MCP server returning duplicate tool names would also 400
+        # OpenAI ("tools[N].function.name duplicates ..."). Drop dupes.
+        if name in seen_names:
+            logger.warning(
+                "Skipping duplicate MCP tool '%s' on '%s'.", raw_name, display
+            )
+            continue
+        seen_names.add(name)
+        specs.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": f"[{display}] {tool.get('description') or ''}".strip(),
+                    "parameters": tool.get("inputSchema")
+                    or {"type": "object", "properties": {}},
+                },
+            }
+        )
+    return specs
+
+
+async def get_enabled_mcp_tools() -> list[dict]:
+    servers = [s for s in mcp_servers_db.list_servers() if s.get("is_enabled")]
+    if not servers:
+        return []
+
+    # OAuth probes need minutes for first-connect/expired-token browser
+    # sign-in; non-OAuth probes fail fast. Matches routes/mcp_servers.py.
+    results = await asyncio.gather(
+        *(
+            list_tools_async(
+                url = s["url"],
+                headers = parse_server_headers(s),
+                timeout = 305.0 if s.get("use_oauth") else 8.0,
+                use_oauth = bool(s.get("use_oauth")),
+            )
+            for s in servers
+        ),
+        return_exceptions = True,
+    )
+
+    specs: list[dict] = []
+    for server, payload in zip(servers, results):
+        if isinstance(payload, BaseException):
+            logger.warning(
+                "MCP server '%s' (%s) discovery failed: %s",
+                server.get("display_name") or server["id"],
+                server.get("url"),
+                payload,
+            )
+            continue
+        specs.extend(_mcp_specs_for_server(server, payload))
+    return specs
+
+
 _TIMEOUT_UNSET = object()
 
 
@@ -525,6 +620,25 @@ def execute_tool(
         f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}"
     )
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
+    if name.startswith(MCP_TOOL_PREFIX):
+        try:
+            _, server_id, tool_name = name.split("__", 2)
+        except ValueError:
+            return f"Error: malformed MCP tool name '{name}'"
+        server = mcp_servers_db.get_server(server_id)
+        if not server:
+            return f"Error: MCP server '{server_id}' not found"
+        if not server.get("is_enabled"):
+            return f"Error: MCP server '{server_id}' is disabled"
+        return call_tool_sync(
+            url = server["url"],
+            headers = parse_server_headers(server),
+            name = tool_name,
+            args = arguments,
+            timeout = effective_timeout,
+            use_oauth = bool(server.get("use_oauth")),
+            cancel_event = cancel_event,
+        )
     if name == "web_search":
         return _web_search(
             arguments.get("query", ""),
diff --git a/studio/backend/core/tool_healing.py b/studio/backend/core/tool_healing.py
index bb61965764..e8bd7d9ea4 100644
--- a/studio/backend/core/tool_healing.py
+++ b/studio/backend/core/tool_healing.py
@@ -17,22 +17,25 @@ verifies it with AST comparison.
 import json
 import re
 
-# Pre-compiled patterns for tool XML stripping.
+# Pre-compiled patterns for tool XML stripping. Hyphen in the
+# function/parameter name char-class tracks OpenAI's allowed set so
+# MCP tool names with dashes (mcp__srv__list-issues) and parameter
+# names with dashes (`issue-number`) parse alongside the built-ins.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
-    re.compile(r"<function=\w+>.*?</function>", re.DOTALL),
+    re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
 ]
 _TOOL_ALL_PATS = _TOOL_CLOSED_PATS + [
     re.compile(r"<tool_call>.*$", re.DOTALL),
-    re.compile(r"<function=\w+>.*$", re.DOTALL),
+    re.compile(r"<function=[\w-]+>.*$", re.DOTALL),
 ]
 
 # Pre-compiled patterns for tool-call XML parsing.
 _TC_JSON_START_RE = re.compile(r"<tool_call>\s*\{")
-_TC_FUNC_START_RE = re.compile(r"<function=(\w+)>\s*")
+_TC_FUNC_START_RE = re.compile(r"<function=([\w-]+)>\s*")
 _TC_END_TAG_RE = re.compile(r"</tool_call>")
 _TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
-_TC_PARAM_START_RE = re.compile(r"<parameter=(\w+)>\s*")
+_TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>\s*")
 _TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
 
 
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 5b92e1262e..8457da0b2d 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -133,6 +133,7 @@ from routes import (
     export_router,
     inference_router,
     inference_studio_router,
+    mcp_servers_router,
     models_router,
     providers_router,
     training_history_router,
@@ -535,6 +536,7 @@ app.include_router(inference_studio_router, prefix = "/api/inference", tags = ["
 # standard /v1/chat/completions path.
 app.include_router(inference_router, prefix = "/v1", tags = ["openai-compat"])
 app.include_router(providers_router, prefix = "/api/providers", tags = ["providers"])
+app.include_router(mcp_servers_router, prefix = "/api/mcp/servers", tags = ["mcp"])
 app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"])
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
 app.include_router(export_router, prefix = "/api/export", tags = ["export"])
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index b58ca66440..bb1bd394d1 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -716,6 +716,10 @@ class ChatCompletionRequest(BaseModel):
             "all local tools are enabled and no server-side tools are forwarded."
         ),
     )
+    mcp_enabled: Optional[bool] = Field(
+        None,
+        description = "[x-unsloth] When true, append tools from every enabled MCP server to this request's tool list.",
+    )
     auto_heal_tool_calls: Optional[bool] = Field(
         True,
         description = "[x-unsloth] Auto-detect and fix malformed tool calls from model output.",
diff --git a/studio/backend/models/mcp_servers.py b/studio/backend/models/mcp_servers.py
new file mode 100644
index 0000000000..c696eb0faa
--- /dev/null
+++ b/studio/backend/models/mcp_servers.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class McpServerCreate(BaseModel):
+    display_name: str
+    url: str
+    headers: Optional[dict[str, str]] = None
+    is_enabled: bool = True
+    use_oauth: bool = False
+
+
+class McpServerUpdate(BaseModel):
+    display_name: Optional[str] = None
+    url: Optional[str] = None
+    # Absent in request body = leave as-is; null = drop all headers; dict = set.
+    headers: Optional[dict[str, str]] = None
+    is_enabled: Optional[bool] = None
+    use_oauth: Optional[bool] = None
+
+
+class McpServerResponse(BaseModel):
+    id: str
+    display_name: str
+    url: str
+    headers: dict[str, str] = Field(default_factory = dict)
+    is_enabled: bool = True
+    use_oauth: bool = False
+    created_at: str
+    updated_at: str
+
+
+class McpServerTestRequest(BaseModel):
+    url: str
+    headers: Optional[dict[str, str]] = None
+    use_oauth: bool = False
+
+
+class McpServerProbeResult(BaseModel):
+    ok: bool
+    tool_count: int = 0
+    error: Optional[str] = None
diff --git a/studio/backend/requirements/extras.txt b/studio/backend/requirements/extras.txt
index d783975a4f..daa8982ea5 100644
--- a/studio/backend/requirements/extras.txt
+++ b/studio/backend/requirements/extras.txt
@@ -52,6 +52,5 @@ addict
 easydict
 einops
 tabulate
-fastmcp>=3.0.2
 openai>=2.7.2
 websockets>=15.0.1
diff --git a/studio/backend/requirements/studio.txt b/studio/backend/requirements/studio.txt
index 96f8816b57..d6eba73245 100644
--- a/studio/backend/requirements/studio.txt
+++ b/studio/backend/requirements/studio.txt
@@ -18,3 +18,4 @@ diceware
 ddgs
 cryptography>=42.0.0
 httpx>=0.27.0
+fastmcp>=3.0.2
diff --git a/studio/backend/routes/__init__.py b/studio/backend/routes/__init__.py
index 6bb5d15e8e..ee3ab61b6e 100644
--- a/studio/backend/routes/__init__.py
+++ b/studio/backend/routes/__init__.py
@@ -16,6 +16,7 @@ from routes.export import router as export_router
 from routes.training_history import router as training_history_router
 from routes.chat_history import router as chat_history_router
 from routes.providers import router as providers_router
+from routes.mcp_servers import router as mcp_servers_router
 
 __all__ = [
     "training_router",
@@ -29,4 +30,5 @@ __all__ = [
     "training_history_router",
     "chat_history_router",
     "providers_router",
+    "mcp_servers_router",
 ]
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 92498b8a9a..259337616c 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -435,7 +435,9 @@ _TOOL_ACTION_NUDGE = (
 #   4. tail-only `</parameter>` (outer close truncated by EOS); anchored to
 #      `\Z` so mid-text `<parameter>` in user code samples survives.
 _TOOL_XML_RE = _re.compile(
-    r"<(?:tool_call|function=\w+)>.*?(?:</(?:tool_call|function)>|\Z)"
+    # Hyphen in the name char-class matches MCP tool names with dashes
+    # (mcp__srv__list-issues) which would otherwise leak past this strip.
+    r"<(?:tool_call|function=[\w-]+)>.*?(?:</(?:tool_call|function)>|\Z)"
     r"|</(?:tool_call|function)>"
     r"|</parameter>\s*\Z",
     _re.DOTALL,
@@ -2648,17 +2650,29 @@ async def openai_chat_completions(
         # ── Tool-calling path (agentic loop) ──────────────────
         # `_effective_enable_tools` lets `unsloth run --enable-tools/--disable-tools`
         # hard-override the per-request value. Without a CLI override, falls
-        # back to `payload.enable_tools` (existing behavior).
+        # back to `payload.enable_tools` (existing behavior). `mcp_enabled=true`
+        # also opens the tool loop so MCP-only callers do not have to flip a
+        # second flag, BUT must still honor a CLI `--disable-tools` policy --
+        # checking the raw policy here keeps `mcp_enabled` from re-enabling
+        # tools that the operator explicitly forbade.
+        from state.tool_policy import get_tool_policy as _get_tool_policy_g
+
+        _cli_policy = _get_tool_policy_g()
+        _tools_on = _effective_enable_tools(payload)
+        _mcp_allowed = bool(payload.mcp_enabled) and _cli_policy is not False
         use_tools = (
-            _effective_enable_tools(payload)
+            (_tools_on or _mcp_allowed)
             and llama_backend.supports_tools
             and not has_gguf_image
         )
 
         if use_tools:
-            from core.inference.tools import ALL_TOOLS
+            from core.inference.tools import ALL_TOOLS, get_enabled_mcp_tools
 
-            if payload.enabled_tools is not None:
+            if not _tools_on:
+                # MCP-only request: skip built-ins, leave room for MCP tools.
+                tools_to_use = []
+            elif payload.enabled_tools is not None:
                 tools_to_use = [
                     t
                     for t in ALL_TOOLS
@@ -2667,6 +2681,19 @@ async def openai_chat_completions(
             else:
                 tools_to_use = ALL_TOOLS
 
+            if _mcp_allowed:
+                tools_to_use = tools_to_use + await get_enabled_mcp_tools()
+
+            # Skip the tool loop when no tool actually survived, so the
+            # safetensors loop's "empty = allow all" semantic cannot reach
+            # built-in tools the caller did not opt into. Existing callers
+            # who omit enabled_tools still get ALL_TOOLS here, so this
+            # only suppresses the loop when discovery + opt-in left it
+            # genuinely empty.
+            if not tools_to_use:
+                use_tools = False
+
+        if use_tools:
             # ── Tool-use system prompt nudge ──────────────────────
             _tool_names = {t["function"]["name"] for t in tools_to_use}
             _has_web = "web_search" in _tool_names
@@ -3142,8 +3169,15 @@ async def openai_chat_completions(
         else 25
     )
 
+    # Match the GGUF path: mcp_enabled also opens the tool loop on its own
+    # but must still honor a CLI `--disable-tools` policy.
+    from state.tool_policy import get_tool_policy as _get_tool_policy_sf
+
+    _sf_cli_policy = _get_tool_policy_sf()
+    _sf_tools_on = _effective_enable_tools(payload)
+    _sf_mcp_allowed = bool(payload.mcp_enabled) and _sf_cli_policy is not False
     _sf_use_tools = (
-        _effective_enable_tools(payload)
+        (_sf_tools_on or _sf_mcp_allowed)
         and _sf_features.get("supports_tools", False)
         and image is None
         and not _sf_is_gptoss
@@ -3151,15 +3185,27 @@ async def openai_chat_completions(
     )
 
     if _sf_use_tools:
-        from core.inference.tools import ALL_TOOLS
+        from core.inference.tools import ALL_TOOLS, get_enabled_mcp_tools
 
-        if payload.enabled_tools is not None:
+        if not _sf_tools_on:
+            _sf_tools_to_use = []
+        elif payload.enabled_tools is not None:
             _sf_tools_to_use = [
                 t for t in ALL_TOOLS if t["function"]["name"] in payload.enabled_tools
             ]
         else:
             _sf_tools_to_use = ALL_TOOLS
 
+        if _sf_mcp_allowed:
+            _sf_tools_to_use = _sf_tools_to_use + await get_enabled_mcp_tools()
+
+        # Mirror the GGUF path: refuse to enter the tool loop when nothing
+        # survived, so a model-emitted built-in call cannot piggy-back on
+        # the empty allow-list.
+        if not _sf_tools_to_use:
+            _sf_use_tools = False
+
+    if _sf_use_tools:
         _sf_tool_names = {t["function"]["name"] for t in _sf_tools_to_use}
         _sf_has_web = "web_search" in _sf_tool_names
         _sf_has_code = "python" in _sf_tool_names or "terminal" in _sf_tool_names
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
new file mode 100644
index 0000000000..a7501d1691
--- /dev/null
+++ b/studio/backend/routes/mcp_servers.py
@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import json
+import uuid
+from urllib.parse import urlparse
+
+import structlog
+from fastapi import APIRouter, Depends, HTTPException
+
+from auth.authentication import get_current_subject
+from core.inference.mcp_client import (
+    clear_oauth_tokens_async,
+    list_tools_async,
+    parse_server_headers,
+)
+from models.mcp_servers import (
+    McpServerCreate,
+    McpServerProbeResult,
+    McpServerResponse,
+    McpServerTestRequest,
+    McpServerUpdate,
+)
+from storage import mcp_servers_db
+
+logger = structlog.get_logger(__name__)
+
+router = APIRouter()
+
+
+_PROBE_TIMEOUT_SECONDS = 8.0
+# When OAuth probes need to open a browser, wait long enough for the user to
+# sign in. Matches fastmcp's default OAuth callback_timeout (300 s) + slack.
+_OAUTH_PROBE_TIMEOUT_SECONDS = 305.0
+
+
+def _validate_url(url: str) -> str:
+    trimmed = (url or "").strip()
+    if not trimmed:
+        raise HTTPException(status_code = 400, detail = "url must not be empty")
+    parsed = urlparse(trimmed)
+    if parsed.scheme not in ("http", "https"):
+        raise HTTPException(
+            status_code = 400,
+            detail = "url must start with http:// or https://",
+        )
+    if not parsed.netloc:
+        raise HTTPException(status_code = 400, detail = "url is missing a host")
+    return trimmed
+
+
+def _normalize_headers(headers: dict[str, str] | None) -> dict[str, str] | None:
+    """Trim header names, drop empties, coerce values to str. None if nothing left."""
+    if not headers:
+        return None
+    out: dict[str, str] = {}
+    for raw_key, value in headers.items():
+        key = str(raw_key).strip()
+        if key:
+            out[key] = str(value)
+    return out or None
+
+
+def _row_to_response(row: dict) -> McpServerResponse:
+    return McpServerResponse(
+        id = row["id"],
+        display_name = row["display_name"],
+        url = row["url"],
+        headers = parse_server_headers(row) or {},
+        is_enabled = bool(row["is_enabled"]),
+        use_oauth = bool(row.get("use_oauth")),
+        created_at = row["created_at"],
+        updated_at = row["updated_at"],
+    )
+
+
+@router.get("/", response_model = list[McpServerResponse])
+async def list_mcp_servers(
+    current_subject: str = Depends(get_current_subject),
+):
+    return [_row_to_response(row) for row in mcp_servers_db.list_servers()]
+
+
+@router.post("/", response_model = McpServerResponse, status_code = 201)
+async def create_mcp_server(
+    payload: McpServerCreate,
+    current_subject: str = Depends(get_current_subject),
+):
+    display_name = (payload.display_name or "").strip()
+    if not display_name:
+        raise HTTPException(status_code = 400, detail = "display_name must not be empty")
+    url = _validate_url(payload.url)
+    headers = _normalize_headers(payload.headers)
+
+    server_id = uuid.uuid4().hex[:16]
+    mcp_servers_db.create_server(
+        id = server_id,
+        display_name = display_name,
+        url = url,
+        headers_json = json.dumps(headers) if headers else None,
+        is_enabled = payload.is_enabled,
+        use_oauth = payload.use_oauth,
+    )
+    return _row_to_response(mcp_servers_db.get_server(server_id))
+
+
+def _changes_from_payload(payload: McpServerUpdate) -> dict:
+    sent = payload.model_fields_set
+    changes: dict = {}
+
+    if "display_name" in sent:
+        name = (payload.display_name or "").strip()
+        if not name:
+            raise HTTPException(
+                status_code = 400, detail = "display_name must not be empty"
+            )
+        changes["display_name"] = name
+    if "url" in sent:
+        changes["url"] = _validate_url(payload.url or "")
+    if "headers" in sent:
+        headers = _normalize_headers(payload.headers)
+        changes["headers_json"] = json.dumps(headers) if headers else None
+    if "is_enabled" in sent:
+        if payload.is_enabled is None:
+            raise HTTPException(
+                status_code = 400, detail = "is_enabled must be true or false"
+            )
+        changes["is_enabled"] = payload.is_enabled
+    if "use_oauth" in sent:
+        if payload.use_oauth is None:
+            raise HTTPException(
+                status_code = 400, detail = "use_oauth must be true or false"
+            )
+        changes["use_oauth"] = payload.use_oauth
+    return changes
+
+
+@router.put("/{server_id}", response_model = McpServerResponse)
+async def update_mcp_server(
+    server_id: str,
+    payload: McpServerUpdate,
+    current_subject: str = Depends(get_current_subject),
+):
+    old = mcp_servers_db.get_server(server_id)
+    if not old:
+        raise HTTPException(status_code = 404, detail = "MCP server not found")
+    changes = _changes_from_payload(payload)
+    if not changes:
+        raise HTTPException(status_code = 400, detail = "No fields to update")
+    # Clear persisted OAuth tokens when the URL changes or OAuth is
+    # disabled; fastmcp keys tokens by URL and would otherwise let a
+    # re-pointed server silently inherit the old account's credentials.
+    if bool(old.get("use_oauth")) and (
+        ("url" in changes and changes["url"] != old["url"])
+        or changes.get("use_oauth") is False
+    ):
+        await clear_oauth_tokens_async(old["url"])
+    mcp_servers_db.update_server(server_id, changes)
+    return _row_to_response(mcp_servers_db.get_server(server_id))
+
+
+@router.delete("/{server_id}", status_code = 204)
+async def delete_mcp_server(
+    server_id: str,
+    current_subject: str = Depends(get_current_subject),
+):
+    old = mcp_servers_db.get_server(server_id)
+    if not old:
+        raise HTTPException(status_code = 404, detail = "MCP server not found")
+    if old.get("use_oauth"):
+        await clear_oauth_tokens_async(old["url"])
+    mcp_servers_db.delete_server(server_id)
+
+
+@router.post("/{server_id}/refresh", response_model = McpServerProbeResult)
+async def refresh_mcp_server_tools(
+    server_id: str,
+    current_subject: str = Depends(get_current_subject),
+):
+    server = mcp_servers_db.get_server(server_id)
+    if not server:
+        raise HTTPException(status_code = 404, detail = "MCP server not found")
+
+    use_oauth = bool(server.get("use_oauth"))
+    try:
+        tools = await list_tools_async(
+            url = server["url"],
+            headers = parse_server_headers(server),
+            timeout = _OAUTH_PROBE_TIMEOUT_SECONDS
+            if use_oauth
+            else _PROBE_TIMEOUT_SECONDS,
+            use_oauth = use_oauth,
+        )
+    except Exception as exc:  # noqa: BLE001 — surface transport+timeout errors to UI
+        logger.warning("MCP refresh failed", server_id = server_id, error = str(exc))
+        return McpServerProbeResult(ok = False, error = str(exc))
+
+    return McpServerProbeResult(ok = True, tool_count = len(tools))
+
+
+@router.post("/test", response_model = McpServerProbeResult)
+async def test_mcp_server(
+    payload: McpServerTestRequest,
+    current_subject: str = Depends(get_current_subject),
+):
+    # URL/header validation must surface as 400 like create/update so the
+    # frontend's create-form pre-flight gets the same error semantics as
+    # the actual save call. Only catch transport/timeout errors below.
+    url = _validate_url(payload.url)
+    headers = _normalize_headers(payload.headers)
+    try:
+        tools = await list_tools_async(
+            url = url,
+            headers = headers,
+            timeout = _OAUTH_PROBE_TIMEOUT_SECONDS
+            if payload.use_oauth
+            else _PROBE_TIMEOUT_SECONDS,
+            use_oauth = payload.use_oauth,
+        )
+    except Exception as exc:  # noqa: BLE001
+        return McpServerProbeResult(ok = False, error = str(exc))
+
+    return McpServerProbeResult(ok = True, tool_count = len(tools))
diff --git a/studio/backend/storage/mcp_servers_db.py b/studio/backend/storage/mcp_servers_db.py
new file mode 100644
index 0000000000..da2fa15423
--- /dev/null
+++ b/studio/backend/storage/mcp_servers_db.py
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from typing import Optional
+
+from utils.paths import studio_db_path, ensure_dir
+
+_schema_lock = threading.Lock()
+_schema_ready = False
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS mcp_servers (
+            id TEXT NOT NULL PRIMARY KEY,
+            display_name TEXT NOT NULL,
+            url TEXT NOT NULL,
+            headers_json TEXT,
+            is_enabled INTEGER NOT NULL DEFAULT 1,
+            use_oauth INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        )
+        """
+    )
+    # use_oauth was added after the first release; backfill for pre-existing DBs.
+    cols = {
+        r["name"] for r in conn.execute("PRAGMA table_info(mcp_servers)").fetchall()
+    }
+    if "use_oauth" not in cols:
+        conn.execute(
+            "ALTER TABLE mcp_servers ADD COLUMN use_oauth INTEGER NOT NULL DEFAULT 0"
+        )
+
+
+def get_connection() -> sqlite3.Connection:
+    global _schema_ready
+    db_path = studio_db_path()
+    ensure_dir(db_path.parent)
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    if not _schema_ready:
+        with _schema_lock:
+            if not _schema_ready:
+                try:
+                    _ensure_schema(conn)
+                    _schema_ready = True
+                except Exception:
+                    conn.close()
+                    raise
+    return conn
+
+
+def create_server(
+    id: str,
+    display_name: str,
+    url: str,
+    headers_json: Optional[str] = None,
+    is_enabled: bool = True,
+    use_oauth: bool = False,
+) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    conn = get_connection()
+    try:
+        conn.execute(
+            """
+            INSERT INTO mcp_servers
+                (id, display_name, url, headers_json,
+                 is_enabled, use_oauth, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                id,
+                display_name,
+                url,
+                headers_json,
+                int(is_enabled),
+                int(use_oauth),
+                now,
+                now,
+            ),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def update_server(id: str, changes: dict) -> bool:
+    """Apply column updates and bump ``updated_at``. Returns True on a hit."""
+    if not changes:
+        return False
+    bool_cols = {"is_enabled", "use_oauth"}
+    sets, params = [], []
+    for col, value in changes.items():
+        sets.append(f"{col} = ?")
+        params.append(int(value) if col in bool_cols else value)
+    sets.append("updated_at = ?")
+    params.extend([datetime.now(timezone.utc).isoformat(), id])
+
+    conn = get_connection()
+    try:
+        cursor = conn.execute(
+            f"UPDATE mcp_servers SET {', '.join(sets)} WHERE id = ?",
+            params,
+        )
+        conn.commit()
+        return cursor.rowcount > 0
+    finally:
+        conn.close()
+
+
+def delete_server(id: str) -> bool:
+    conn = get_connection()
+    try:
+        cursor = conn.execute("DELETE FROM mcp_servers WHERE id = ?", (id,))
+        conn.commit()
+        return cursor.rowcount > 0
+    finally:
+        conn.close()
+
+
+def get_server(id: str) -> Optional[dict]:
+    conn = get_connection()
+    try:
+        row = conn.execute("SELECT * FROM mcp_servers WHERE id = ?", (id,)).fetchone()
+        return dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def list_servers() -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute("SELECT * FROM mcp_servers ORDER BY created_at").fetchall()
+        return [dict(row) for row in rows]
+    finally:
+        conn.close()
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index bc8788fd90..b1522dd382 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -437,6 +437,7 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
         export_router = APIRouter(),
         inference_router = APIRouter(),
         inference_studio_router = APIRouter(),
+        mcp_servers_router = APIRouter(),
         models_router = APIRouter(),
         providers_router = APIRouter(),
         training_history_router = APIRouter(),
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
new file mode 100644
index 0000000000..10a6eb012b
--- /dev/null
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -0,0 +1,632 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import pytest
+from fastapi import HTTPException
+
+from storage import mcp_servers_db
+
+
+def _reset_db(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(mcp_servers_db, "_schema_ready", False)
+
+
+# ── storage: mcp_servers_db ─────────────────────────────────────────
+
+
+def test_create_and_get_server(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(
+        id = "srv1",
+        display_name = "GitHub",
+        url = "https://example.com/mcp",
+        headers_json = '{"Authorization": "Bearer x"}',
+        is_enabled = True,
+        use_oauth = False,
+    )
+    row = mcp_servers_db.get_server("srv1")
+    assert row["id"] == "srv1"
+    assert row["display_name"] == "GitHub"
+    assert row["url"] == "https://example.com/mcp"
+    assert row["headers_json"] == '{"Authorization": "Bearer x"}'
+    assert row["is_enabled"] == 1
+    assert row["use_oauth"] == 0
+
+
+def test_list_servers_ordered_by_created_at(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(id = "a", display_name = "A", url = "https://a/m")
+    mcp_servers_db.create_server(id = "b", display_name = "B", url = "https://b/m")
+    rows = mcp_servers_db.list_servers()
+    assert [r["id"] for r in rows] == ["a", "b"]
+
+
+def test_update_server_coerces_bools(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a/m")
+    assert mcp_servers_db.update_server(
+        "srv1", {"is_enabled": False, "use_oauth": True}
+    )
+    row = mcp_servers_db.get_server("srv1")
+    assert row["is_enabled"] == 0
+    assert row["use_oauth"] == 1
+
+
+def test_update_server_empty_changes_returns_false(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a/m")
+    assert mcp_servers_db.update_server("srv1", {}) is False
+
+
+def test_delete_server_roundtrip(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a/m")
+    assert mcp_servers_db.delete_server("srv1") is True
+    assert mcp_servers_db.delete_server("srv1") is False
+    assert mcp_servers_db.get_server("srv1") is None
+
+
+# ── routes/mcp_servers: pure helpers ────────────────────────────────
+
+
+def test_validate_url_accepts_http_and_https():
+    from routes.mcp_servers import _validate_url
+
+    assert _validate_url("http://example.com/mcp") == "http://example.com/mcp"
+    assert _validate_url("https://example.com/mcp") == "https://example.com/mcp"
+    assert _validate_url("  https://example.com/mcp  ") == "https://example.com/mcp"
+
+
+@pytest.mark.parametrize("bad", ["", "   ", "ftp://x", "http://", "noscheme.com"])
+def test_validate_url_rejects_bad(bad):
+    from routes.mcp_servers import _validate_url
+
+    with pytest.raises(HTTPException) as exc:
+        _validate_url(bad)
+    assert exc.value.status_code == 400
+
+
+def test_normalize_headers():
+    from routes.mcp_servers import _normalize_headers
+
+    assert _normalize_headers({"  Auth  ": "Bearer x", "": "ignored"}) == {
+        "Auth": "Bearer x"
+    }
+    assert _normalize_headers({"X": 42}) == {"X": "42"}
+    assert _normalize_headers({}) is None
+    assert _normalize_headers(None) is None
+    assert _normalize_headers({"   ": "x"}) is None
+
+
+def test_changes_from_payload_tristate_headers():
+    from routes.mcp_servers import _changes_from_payload
+    from models.mcp_servers import McpServerUpdate
+
+    # omitted → key absent
+    assert "headers_json" not in _changes_from_payload(
+        McpServerUpdate(display_name = "x")
+    )
+    # null → stored as None (clear all headers)
+    assert _changes_from_payload(McpServerUpdate(headers = None))["headers_json"] is None
+    # dict → serialised JSON
+    assert (
+        _changes_from_payload(McpServerUpdate(headers = {"a": "1"}))["headers_json"]
+        == '{"a": "1"}'
+    )
+
+
+# ── core/inference/tools: MCP wiring ────────────────────────────────
+
+
+def test_mcp_specs_skip_oversized_names():
+    from core.inference.tools import _mcp_specs_for_server
+
+    server = {"id": "s" * 30, "display_name": "S"}
+    tools = [
+        {"name": "ok", "description": "fine"},
+        {"name": "x" * 40, "description": "too long"},
+    ]
+    specs = _mcp_specs_for_server(server, tools)
+    assert len(specs) == 1
+    assert specs[0]["function"]["name"].endswith("__ok")
+    assert len(specs[0]["function"]["name"]) <= 64
+
+
+def test_execute_tool_malformed_mcp_name():
+    from core.inference.tools import execute_tool
+
+    out = execute_tool("mcp__no_double_underscore", {})
+    assert out.startswith("Error: malformed MCP tool name")
+
+
+def test_execute_tool_unknown_server(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    from core.inference.tools import execute_tool
+
+    assert (
+        execute_tool("mcp__missing__do_thing", {})
+        == "Error: MCP server 'missing' not found"
+    )
+
+
+def test_execute_tool_disabled_server(tmp_path, monkeypatch):
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(
+        id = "srv1",
+        display_name = "A",
+        url = "https://a/m",
+        is_enabled = False,
+    )
+    from core.inference.tools import execute_tool
+
+    assert (
+        execute_tool("mcp__srv1__do_thing", {})
+        == "Error: MCP server 'srv1' is disabled"
+    )
+
+
+def test_mcp_specs_skip_invalid_openai_function_names():
+    """OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; tools whose
+    names contain '.', '/', spaces, etc. would 400 the whole request."""
+    from core.inference.tools import _mcp_specs_for_server
+
+    server = {"id": "srv", "display_name": "S"}
+    tools = [
+        {"name": "ok"},
+        {"name": "with.dot"},
+        {"name": "weird/slash"},
+        {"name": "has space"},
+        {"name": "good-dash_ok"},
+    ]
+    specs = _mcp_specs_for_server(server, tools)
+    names = {s["function"]["name"] for s in specs}
+    assert {"mcp__srv__ok", "mcp__srv__good-dash_ok"} == names
+
+
+def test_mcp_specs_skip_empty_tool_name():
+    from core.inference.tools import _mcp_specs_for_server
+
+    server = {"id": "srv", "display_name": "S"}
+    specs = _mcp_specs_for_server(server, [{"name": "", "description": "x"}])
+    assert specs == []
+
+
+def test_mcp_specs_drops_duplicate_names():
+    """Same tool name twice from one MCP server -> OpenAI rejects the
+    request as 'duplicates'. Drop the duplicate before forwarding."""
+    from core.inference.tools import _mcp_specs_for_server
+
+    server = {"id": "srv", "display_name": "S"}
+    tools = [{"name": "echo"}, {"name": "echo"}]
+    specs = _mcp_specs_for_server(server, tools)
+    assert len(specs) == 1
+
+
+def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
+    """cancel_event already set before the call -> immediate Error: cancelled
+    without making a network round-trip."""
+    import threading
+    from core.inference import mcp_client
+
+    # Stub _client so the test doesn't need a real MCP server.
+    class _StubClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return False
+
+        async def call_tool(self, name, args):
+            import asyncio as _asyncio
+
+            await _asyncio.sleep(30)  # never finishes within the test
+
+    monkeypatch.setattr(mcp_client, "_client", lambda *a, **kw: _StubClient())
+
+    cancel = threading.Event()
+    cancel.set()
+    out = mcp_client.call_tool_sync(
+        url = "https://example/mcp",
+        headers = None,
+        name = "slow",
+        args = {},
+        timeout = 30.0,
+        cancel_event = cancel,
+    )
+    assert "cancelled" in out.lower()
+
+
+def test_clear_oauth_tokens_async_no_op_safe(tmp_path, monkeypatch):
+    """clear_oauth_tokens_async on a URL with no stored token must not raise --
+    the delete + update handlers call it best-effort regardless of prior state."""
+    import asyncio
+
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    from core.inference import mcp_client
+
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    asyncio.run(mcp_client.clear_oauth_tokens_async("https://example.com/mcp"))
+
+
+def test_delete_server_calls_oauth_cleanup_when_oauth_was_on(tmp_path, monkeypatch):
+    """delete_mcp_server route helper should invoke clear_oauth_tokens_async
+    when the deleted row had use_oauth=true."""
+    import asyncio
+
+    _reset_db(tmp_path, monkeypatch)
+    from core.inference import mcp_client
+
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    mcp_servers_db.create_server(
+        id = "oauth1",
+        display_name = "GH",
+        url = "https://gh-mcp.example/mcp",
+        is_enabled = True,
+        use_oauth = True,
+    )
+
+    calls: list[str] = []
+
+    async def fake_clear(url):
+        calls.append(url)
+
+    monkeypatch.setattr(mcp_client, "clear_oauth_tokens_async", fake_clear)
+    # Re-import the route's binding through the module so the patch is seen.
+    import routes.mcp_servers as routes_mcp
+
+    monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", fake_clear)
+    asyncio.run(routes_mcp.delete_mcp_server("oauth1", current_subject = "u"))
+    assert calls == ["https://gh-mcp.example/mcp"]
+    assert mcp_servers_db.get_server("oauth1") is None
+
+
+def test_delete_server_skips_oauth_cleanup_when_oauth_off(tmp_path, monkeypatch):
+    """No OAuth token cleanup when the deleted server never had OAuth."""
+    import asyncio
+
+    _reset_db(tmp_path, monkeypatch)
+    from core.inference import mcp_client
+    import routes.mcp_servers as routes_mcp
+
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    mcp_servers_db.create_server(
+        id = "noauth",
+        display_name = "Plain",
+        url = "https://plain/mcp",
+        is_enabled = True,
+        use_oauth = False,
+    )
+    calls: list[str] = []
+
+    async def fake_clear(url):
+        calls.append(url)
+
+    monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", fake_clear)
+    asyncio.run(routes_mcp.delete_mcp_server("noauth", current_subject = "u"))
+    assert calls == []
+
+
+def test_update_server_clears_oauth_on_url_change(tmp_path, monkeypatch):
+    """Changing the URL on an OAuth server must drop the old URL's tokens
+    so the new URL doesn't silently inherit credentials."""
+    import asyncio
+
+    _reset_db(tmp_path, monkeypatch)
+    from core.inference import mcp_client
+    from models.mcp_servers import McpServerUpdate
+    import routes.mcp_servers as routes_mcp
+
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    mcp_servers_db.create_server(
+        id = "s1",
+        display_name = "A",
+        url = "https://old/mcp",
+        is_enabled = True,
+        use_oauth = True,
+    )
+    calls: list[str] = []
+
+    async def fake_clear(url):
+        calls.append(url)
+
+    monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", fake_clear)
+    asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1",
+            McpServerUpdate(url = "https://new/mcp"),
+            current_subject = "u",
+        )
+    )
+    assert calls == ["https://old/mcp"]
+    row = mcp_servers_db.get_server("s1")
+    assert row["url"] == "https://new/mcp"
+
+
+def test_update_server_clears_oauth_when_oauth_disabled(tmp_path, monkeypatch):
+    """Flipping use_oauth false must drop the old URL's tokens."""
+    import asyncio
+
+    _reset_db(tmp_path, monkeypatch)
+    from core.inference import mcp_client
+    from models.mcp_servers import McpServerUpdate
+    import routes.mcp_servers as routes_mcp
+
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    mcp_servers_db.create_server(
+        id = "s1",
+        display_name = "A",
+        url = "https://u/mcp",
+        is_enabled = True,
+        use_oauth = True,
+    )
+    calls: list[str] = []
+
+    async def fake_clear(url):
+        calls.append(url)
+
+    monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", fake_clear)
+    asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1",
+            McpServerUpdate(use_oauth = False),
+            current_subject = "u",
+        )
+    )
+    assert calls == ["https://u/mcp"]
+
+
+def test_changes_from_payload_rejects_null_is_enabled():
+    """Explicit null for is_enabled used to hit int(None) -> TypeError 500."""
+    from routes.mcp_servers import _changes_from_payload
+    from models.mcp_servers import McpServerUpdate
+
+    with pytest.raises(HTTPException) as exc:
+        _changes_from_payload(McpServerUpdate(is_enabled = None))
+    assert exc.value.status_code == 400
+
+
+def test_changes_from_payload_rejects_null_use_oauth():
+    """Explicit null for use_oauth used to hit int(None) -> TypeError 500."""
+    from routes.mcp_servers import _changes_from_payload
+    from models.mcp_servers import McpServerUpdate
+
+    with pytest.raises(HTTPException) as exc:
+        _changes_from_payload(McpServerUpdate(use_oauth = None))
+    assert exc.value.status_code == 400
+
+
+def test_test_endpoint_surfaces_url_validation_as_400(tmp_path, monkeypatch):
+    """POST /api/mcp/servers/test must 400 on invalid URL like create/update;
+    previously the same input returned 200 with {"ok": false}."""
+    import asyncio
+
+    _reset_db(tmp_path, monkeypatch)
+    from routes.mcp_servers import test_mcp_server
+    from models.mcp_servers import McpServerTestRequest
+
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            test_mcp_server(
+                McpServerTestRequest(url = "ftp://nope"),
+                current_subject = "u",
+            )
+        )
+    assert exc.value.status_code == 400
+
+
+def test_tool_xml_parser_handles_hyphenated_parameter_names():
+    """MCP tool schemas commonly use hyphenated property names like
+    `issue-number` / `repo-name`; the XML parser's `<parameter=\\w+>` regex
+    dropped those keys. Verify hyphenated parameter names round-trip."""
+    from core.inference.tool_call_parser import parse_tool_calls_from_text
+    import json as _json
+
+    calls = parse_tool_calls_from_text(
+        "<function=mcp__srv__create-issue>"
+        "<parameter=issue-title>Bug report</parameter>"
+        "<parameter=repo-name>octocat/hello</parameter>"
+        "</function>"
+    )
+    assert len(calls) == 1
+    args = _json.loads(calls[0]["function"]["arguments"])
+    assert args == {"issue-title": "Bug report", "repo-name": "octocat/hello"}
+
+
+def test_tool_healing_strip_handles_hyphenated_function_names():
+    """GGUF's core/tool_healing.py has its own copy of the XML strip
+    regex; the round-4 fix to the shared parser missed this file."""
+    from core.tool_healing import strip_tool_call_markup
+
+    out = strip_tool_call_markup(
+        "before <function=mcp__srv__list-issues>"
+        "<parameter=q>x</parameter></function> after"
+    )
+    assert out == "before  after"
+
+
+def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
+    """When the model emits a tool call not in the per-request tool list
+    the GGUF agentic loop must refuse to dispatch -- mirroring the
+    safetensors path. Previously execute_tool ran the call regardless."""
+    from core.inference import tools as tools_mod
+
+    captured: list[str] = []
+
+    def fake_execute(name, args, **kw):
+        captured.append(name)
+        return "executed"
+
+    monkeypatch.setattr(tools_mod, "execute_tool", fake_execute)
+
+    # Re-create the allow-list check inline so we can unit-test the
+    # behavior without spinning up llama-server.
+    def _gate(tools_advertised, called_name, args):
+        allowed = {
+            (t.get("function") or {}).get("name")
+            for t in (tools_advertised or [])
+            if (t.get("function") or {}).get("name")
+        }
+        if allowed and called_name not in allowed:
+            return "Error: tool '" + called_name + "' is not enabled"
+        return fake_execute(called_name, args)
+
+    # Built-in not in advertised list -> blocked.
+    out = _gate(
+        [{"function": {"name": "mcp__srv__echo"}}],
+        "terminal",
+        {"command": "echo x"},
+    )
+    assert "not enabled" in out
+    assert captured == []
+    # Tool in advertised list -> runs.
+    out = _gate(
+        [{"function": {"name": "mcp__srv__echo"}}],
+        "mcp__srv__echo",
+        {"text": "hi"},
+    )
+    assert out == "executed"
+    assert captured == ["mcp__srv__echo"]
+
+
+def test_call_tool_sync_short_circuits_on_pre_set_cancel(monkeypatch):
+    """cancel_event set BEFORE call_tool_sync runs -> no HTTP request
+    is made. Previously the call task was created before the cancel
+    check, opening a transport that the watcher then had to cancel."""
+    from core.inference import mcp_client
+
+    opened: list[str] = []
+
+    class _StubClient:
+        async def __aenter__(self):
+            opened.append("opened")
+            return self
+
+        async def __aexit__(self, *args):
+            return False
+
+        async def call_tool(self, name, args):
+            return "ran"
+
+    monkeypatch.setattr(mcp_client, "_client", lambda *a, **kw: _StubClient())
+
+    import threading
+
+    ev = threading.Event()
+    ev.set()
+    out = mcp_client.call_tool_sync(
+        url = "https://example/mcp",
+        headers = None,
+        name = "x",
+        args = {},
+        timeout = 5.0,
+        cancel_event = ev,
+    )
+    assert "cancelled" in out.lower()
+    # The client must NOT have been opened.
+    assert opened == []
+
+
+def test_clear_oauth_tokens_swallows_constructor_errors(tmp_path, monkeypatch):
+    """clear_oauth_tokens_async is best-effort; an OAuth constructor
+    failure (e.g. missing fastmcp.client.auth) must not bubble out into
+    a 500 from the delete / update routes."""
+    import asyncio
+    from core.inference import mcp_client
+
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+
+    # Patch the OAuth import path to raise so the entire body fails.
+    class _BoomOAuth:
+        def __init__(self, *a, **kw):
+            raise RuntimeError("simulated")
+
+    import sys as _sys
+
+    fake_mod = type(_sys)("fastmcp.client.auth")
+    fake_mod.OAuth = _BoomOAuth
+    monkeypatch.setitem(_sys.modules, "fastmcp.client.auth", fake_mod)
+    # Must not raise.
+    asyncio.run(mcp_client.clear_oauth_tokens_async("https://x/mcp"))
+
+
+def test_tool_xml_parser_handles_hyphenated_function_names():
+    """MCP tool names are advertised as `mcp__srv__list-issues` (the regex
+    fix allows '-'); the XML tool-call parser must parse them too,
+    otherwise the model can call the tool but Studio cannot dispatch."""
+    from core.inference.tool_call_parser import parse_tool_calls_from_text
+
+    calls = parse_tool_calls_from_text(
+        "<function=mcp__srv__list-issues>"
+        "<parameter=repo>octocat/hello</parameter>"
+        "</function>"
+    )
+    assert len(calls) == 1
+    assert calls[0]["function"]["name"] == "mcp__srv__list-issues"
+    import json as _json
+
+    args = _json.loads(calls[0]["function"]["arguments"])
+    assert args == {"repo": "octocat/hello"}
+
+
+def test_tool_xml_strip_handles_hyphenated_function_names():
+    """routes/inference.py:_TOOL_XML_RE must strip a `<function=name-with-dash>`
+    block; otherwise hyphenated MCP tool-call XML leaks into chat history."""
+    import re as _re
+    from pathlib import Path
+
+    src = (Path(__file__).resolve().parent.parent / "routes/inference.py").read_text()
+    m = _re.search(r"_TOOL_XML_RE = _re\.compile\((.*?)\n\)", src, _re.DOTALL)
+    assert m, "could not extract _TOOL_XML_RE"
+    ns: dict = {"_re": _re}
+    exec(f"_TOOL_XML_RE = _re.compile({m.group(1)})", ns)
+    rx = ns["_TOOL_XML_RE"]
+    stripped = rx.sub(
+        "",
+        "before <function=mcp__srv__list-issues>"
+        "<parameter=q>x</parameter></function> after",
+    )
+    assert stripped == "before  after"
+
+
+def test_safetensors_agentic_empty_allowlist_still_means_allow_all():
+    """Document existing contract: at the safetensors_agentic layer,
+    tools=[] is still treated as "no constraint" (so existing callers
+    work unchanged). The real fix for the MCP-only-no-discovery case
+    lives at the route level in inference.py, which refuses to enter
+    use_tools when the resolved tool list is empty."""
+    import threading
+    from core.inference.safetensors_agentic import run_safetensors_tool_loop
+
+    calls: list[str] = []
+
+    def fake_execute(name, args, **kw):
+        calls.append(name)
+        return "ran"
+
+    iteration = {"n": 0}
+
+    def fake_single_turn(messages):
+        iteration["n"] += 1
+        if iteration["n"] == 1:
+            txt = '<tool_call>{"name":"python","arguments":{"code":"1"}}</tool_call>'
+            buf = ""
+            for ch in txt:
+                buf += ch
+                yield buf
+        else:
+            yield "done"
+
+    list(
+        run_safetensors_tool_loop(
+            single_turn = fake_single_turn,
+            messages = [{"role": "user", "content": "x"}],
+            tools = [],
+            execute_tool = fake_execute,
+            cancel_event = threading.Event(),
+            max_tool_iterations = 1,
+        )
+    )
+    # Empty allow-list = run anything (preserved contract).
+    assert calls == [("python", {"code": "1"})] or len(calls) >= 1
diff --git a/studio/frontend/src/components/assistant-ui/tool-fallback.tsx b/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
index f0d6262a45..2ea87d63f3 100644
--- a/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
@@ -101,6 +101,16 @@ const statusIconMap: Record<ToolStatus, ElementType> = {
   "requires-action": AlertCircleIcon,
 };
 
+const MCP_TOOL_PREFIX = "mcp__";
+
+function formatToolNameForDisplay(toolName: string): string {
+  if (!toolName.startsWith(MCP_TOOL_PREFIX)) return toolName;
+  const rest = toolName.slice(MCP_TOOL_PREFIX.length);
+  const sep = rest.indexOf("__");
+  if (sep <= 0) return toolName;
+  return `${rest.slice(0, sep)} · ${rest.slice(sep + 2)}`;
+}
+
 function ToolFallbackTrigger({
   toolName,
   status,
@@ -119,6 +129,7 @@ function ToolFallbackTrigger({
 
   const StatusIcon = statusIconMap[statusType];
   const label = isCancelled ? "Cancelled tool" : "Used tool";
+  const displayName = formatToolNameForDisplay(toolName);
 
   return (
     <CollapsibleTrigger
@@ -160,7 +171,7 @@ function ToolFallbackTrigger({
       >
         <span className="block truncate">
           {label}:{" "}
-          <span className="font-medium text-foreground/85">{toolName}</span>
+          <span className="font-medium text-foreground/85">{displayName}</span>
         </span>
         {isRunning && (
           <span
@@ -169,7 +180,7 @@ function ToolFallbackTrigger({
             className="aui-tool-fallback-trigger-shimmer shimmer pointer-events-none absolute inset-0 block truncate motion-reduce:animate-none"
           >
             {label}:{" "}
-            <span className="font-medium text-foreground/85">{toolName}</span>
+            <span className="font-medium text-foreground/85">{displayName}</span>
           </span>
         )}
       </span>
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 2ef14b5326..a74a4a2dea 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -1305,6 +1305,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         toolsEnabled,
         codeToolsEnabled,
         imageToolsEnabled,
+        mcpEnabledForChat,
         webFetchToolsEnabled,
       } = runtime;
       const externalSelection = parseExternalModelId(params.checkpoint);
@@ -2094,13 +2095,14 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             ...(supportsPreserveThinking
               ? { preserve_thinking: preserveThinking }
               : {}),
-            ...(supportsTools && (toolsEnabled || codeToolsEnabled)
+            ...(supportsTools && (toolsEnabled || codeToolsEnabled || mcpEnabledForChat)
               ? {
                   enable_tools: true,
                   enabled_tools: [
                     ...(toolsEnabled ? ["web_search"] : []),
                     ...(codeToolsEnabled ? ["python", "terminal"] : []),
                   ],
+                  mcp_enabled: mcpEnabledForChat,
                   auto_heal_tool_calls:
                     useChatRuntimeStore.getState().autoHealToolCalls,
                   max_tool_calls_per_message:
diff --git a/studio/frontend/src/features/chat/api/mcp-servers-api.ts b/studio/frontend/src/features/chat/api/mcp-servers-api.ts
new file mode 100644
index 0000000000..be88d12664
--- /dev/null
+++ b/studio/frontend/src/features/chat/api/mcp-servers-api.ts
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { formatFastApiDetail } from "@/lib/format-fastapi-error";
+
+export interface McpServerConfig {
+  id: string;
+  display_name: string;
+  url: string;
+  headers: Record<string, string>;
+  is_enabled: boolean;
+  use_oauth: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface McpServerProbeResult {
+  ok: boolean;
+  tool_count: number;
+  error: string | null;
+}
+
+function parseErrorText(status: number, body: unknown): string {
+  if (body && typeof body === "object") {
+    const { detail, message } = body as { detail?: unknown; message?: unknown };
+    const formatted = formatFastApiDetail(detail);
+    if (formatted) return formatted;
+    if (typeof message === "string" && message) return message;
+  }
+  return `Request failed (${status})`;
+}
+
+async function mcpRequest<T>(
+  path: string,
+  init?: { method?: string; body?: object },
+): Promise<T> {
+  const response = await authFetch(`/api/mcp/servers${path}`, {
+    method: init?.method,
+    headers: init?.body ? { "Content-Type": "application/json" } : undefined,
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+  });
+  // 204 No Content (DELETE) has no body — calling .json() would throw.
+  if (response.status === 204) return undefined as T;
+  const json = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(parseErrorText(response.status, json));
+  return json as T;
+}
+
+export function listMcpServers(): Promise<McpServerConfig[]> {
+  return mcpRequest("/");
+}
+
+export function createMcpServer(payload: {
+  displayName: string;
+  url: string;
+  headers?: Record<string, string>;
+  isEnabled?: boolean;
+  useOauth?: boolean;
+}): Promise<McpServerConfig> {
+  return mcpRequest("/", {
+    method: "POST",
+    body: {
+      display_name: payload.displayName,
+      url: payload.url,
+      headers: payload.headers ?? null,
+      is_enabled: payload.isEnabled ?? true,
+      use_oauth: payload.useOauth ?? false,
+    },
+  });
+}
+
+export function updateMcpServer(
+  serverId: string,
+  payload: {
+    displayName?: string;
+    url?: string;
+    /** null = drop stored headers; omit to leave as-is */
+    headers?: Record<string, string> | null;
+    isEnabled?: boolean;
+    useOauth?: boolean;
+  },
+): Promise<McpServerConfig> {
+  const body: Record<string, unknown> = {};
+  if (payload.displayName !== undefined) body.display_name = payload.displayName;
+  if (payload.url !== undefined) body.url = payload.url;
+  if (payload.headers !== undefined) body.headers = payload.headers;
+  if (payload.isEnabled !== undefined) body.is_enabled = payload.isEnabled;
+  if (payload.useOauth !== undefined) body.use_oauth = payload.useOauth;
+  return mcpRequest(`/${serverId}`, { method: "PUT", body });
+}
+
+export function deleteMcpServer(serverId: string): Promise<void> {
+  return mcpRequest(`/${serverId}`, { method: "DELETE" });
+}
+
+export function refreshMcpServerTools(
+  serverId: string,
+): Promise<McpServerProbeResult> {
+  return mcpRequest(`/${serverId}/refresh`, { method: "POST" });
+}
+
+export function testMcpServer(payload: {
+  url: string;
+  headers?: Record<string, string>;
+  useOauth?: boolean;
+}): Promise<McpServerProbeResult> {
+  return mcpRequest("/test", {
+    method: "POST",
+    body: {
+      url: payload.url,
+      headers: payload.headers ?? null,
+      use_oauth: payload.useOauth ?? false,
+    },
+  });
+}
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
new file mode 100644
index 0000000000..35b5aca64c
--- /dev/null
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -0,0 +1,497 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
+import { Delete02Icon, Edit03Icon, PlusSignIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { RefreshCwIcon } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Spinner } from "@/components/ui/spinner";
+import { Switch } from "@/components/ui/switch";
+import {
+  type McpServerConfig,
+  createMcpServer,
+  deleteMcpServer,
+  listMcpServers,
+  refreshMcpServerTools,
+  testMcpServer,
+  updateMcpServer,
+} from "./api/mcp-servers-api";
+type HeaderRow = { id: string; key: string; value: string };
+
+type FormState = {
+  displayName: string;
+  url: string;
+  headers: HeaderRow[];
+  useOauth: boolean;
+};
+
+const EMPTY_FORM: FormState = {
+  displayName: "",
+  url: "",
+  headers: [],
+  useOauth: false,
+};
+
+function newRowId(): string {
+  return `r_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function headersFromObject(headers: Record<string, string>): HeaderRow[] {
+  return Object.entries(headers).map(([k, v]) => ({
+    id: newRowId(),
+    key: k,
+    value: v,
+  }));
+}
+
+function headersToObject(rows: HeaderRow[]): Record<string, string> | undefined {
+  const out: Record<string, string> = {};
+  for (const row of rows) {
+    const key = row.key.trim();
+    if (!key) continue;
+    out[key] = row.value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function isValidUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function HeadersEditor({
+  rows,
+  onChange,
+}: {
+  rows: HeaderRow[];
+  onChange: (rows: HeaderRow[]) => void;
+}) {
+  const update = (id: string, patch: Partial<HeaderRow>) =>
+    onChange(rows.map((row) => (row.id === id ? { ...row, ...patch } : row)));
+  const add = () =>
+    onChange([...rows, { id: newRowId(), key: "", value: "" }]);
+  const remove = (id: string) =>
+    onChange(rows.filter((row) => row.id !== id));
+
+  return (
+    <>
+      <div className="flex items-center justify-between">
+        <Label className="text-sm">Custom headers</Label>
+        <Button type="button" variant="ghost" size="sm" onClick={add}>
+          <HugeiconsIcon icon={PlusSignIcon} size={14} />
+          Add header
+        </Button>
+      </div>
+      {rows.length === 0 ? (
+        <div className="text-xs text-muted-foreground">
+          Optional. Add an <code>Authorization</code> header here for servers
+          that require auth.
+        </div>
+      ) : (
+        <div className="flex flex-col gap-2">
+          {rows.map((row) => (
+            <div key={row.id} className="flex items-center gap-2">
+              <Input
+                value={row.key}
+                placeholder="Header name"
+                onChange={(e) => update(row.id, { key: e.target.value })}
+              />
+              <Input
+                value={row.value}
+                placeholder="Header value"
+                onChange={(e) => update(row.id, { value: e.target.value })}
+              />
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                onClick={() => remove(row.id)}
+                aria-label="Remove header"
+              >
+                <HugeiconsIcon icon={Delete02Icon} size={14} />
+              </Button>
+            </div>
+          ))}
+        </div>
+      )}
+    </>
+  );
+}
+
+export interface ChatMcpServersDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+type View =
+  | { kind: "list" }
+  | { kind: "create" }
+  | { kind: "edit"; id: string };
+
+export function ChatMcpServersDialog({
+  open,
+  onOpenChange,
+}: ChatMcpServersDialogProps) {
+  const [servers, setServers] = useState<McpServerConfig[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [view, setView] = useState<View>({ kind: "list" });
+  const [form, setForm] = useState<FormState>(EMPTY_FORM);
+  const [saving, setSaving] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [refreshingId, setRefreshingId] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      const rows = await listMcpServers();
+      setServers(rows);
+    } catch (err) {
+      toast.error("Failed to load MCP servers", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+    refresh();
+  }, [open, refresh]);
+
+  function startCreate() {
+    setView({ kind: "create" });
+    setForm(EMPTY_FORM);
+  }
+
+  function startEdit(server: McpServerConfig) {
+    setView({ kind: "edit", id: server.id });
+    setForm({
+      displayName: server.display_name,
+      url: server.url,
+      headers: headersFromObject(server.headers ?? {}),
+      useOauth: server.use_oauth ?? false,
+    });
+  }
+
+  function cancelForm() {
+    setView({ kind: "list" });
+    setForm(EMPTY_FORM);
+  }
+
+  async function testConnection() {
+    const trimmedUrl = form.url.trim();
+    if (!isValidUrl(trimmedUrl)) {
+      toast.error("Enter a valid http:// or https:// URL first");
+      return;
+    }
+    setTesting(true);
+    try {
+      const result = await testMcpServer({
+        url: trimmedUrl,
+        headers: headersToObject(form.headers),
+        useOauth: form.useOauth,
+      });
+      if (result.ok) {
+        toast.success(
+          `Connected (${result.tool_count} tool${result.tool_count === 1 ? "" : "s"})`,
+        );
+      } else {
+        toast.error("Connection failed", {
+          description: result.error ?? "Unknown error",
+        });
+      }
+    } catch (err) {
+      toast.error("Connection test failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setTesting(false);
+    }
+  }
+
+  async function submitForm() {
+    const trimmedName = form.displayName.trim();
+    const trimmedUrl = form.url.trim();
+    if (!trimmedName) {
+      toast.error("Display name is required");
+      return;
+    }
+    if (!trimmedUrl) {
+      toast.error("URL is required");
+      return;
+    }
+    if (!isValidUrl(trimmedUrl)) {
+      toast.error("URL must start with http:// or https://");
+      return;
+    }
+    setSaving(true);
+    try {
+      const headers = headersToObject(form.headers);
+      if (view.kind === "edit") {
+        await updateMcpServer(view.id, {
+          displayName: trimmedName,
+          url: trimmedUrl,
+          headers: headers ?? null,
+          useOauth: form.useOauth,
+        });
+        toast.success("MCP server updated");
+      } else {
+        await createMcpServer({
+          displayName: trimmedName,
+          url: trimmedUrl,
+          headers: headers,
+          useOauth: form.useOauth,
+        });
+        toast.success("MCP server added");
+      }
+      cancelForm();
+      await refresh();
+    } catch (err) {
+      toast.error("Save failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  async function removeServer(server: McpServerConfig) {
+    const ok = window.confirm(`Delete MCP server "${server.display_name}"?`);
+    if (!ok) return;
+    try {
+      await deleteMcpServer(server.id);
+      await refresh();
+    } catch (err) {
+      toast.error("Delete failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  async function toggleEnabled(server: McpServerConfig, next: boolean) {
+    // Optimistic update so the switch doesn't snap back during the round-trip.
+    setServers((rows) =>
+      rows.map((row) =>
+        row.id === server.id ? { ...row, is_enabled: next } : row,
+      ),
+    );
+    try {
+      await updateMcpServer(server.id, { isEnabled: next });
+    } catch (err) {
+      setServers((rows) =>
+        rows.map((row) =>
+          row.id === server.id ? { ...row, is_enabled: !next } : row,
+        ),
+      );
+      toast.error("Update failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  async function refreshTools(server: McpServerConfig) {
+    setRefreshingId(server.id);
+    try {
+      const result = await refreshMcpServerTools(server.id);
+      if (result.ok) {
+        toast.success(
+          `Refreshed "${server.display_name}" (${result.tool_count} tool${result.tool_count === 1 ? "" : "s"})`,
+        );
+      } else {
+        toast.error(`Refresh failed for "${server.display_name}"`, {
+          description: result.error ?? "Unknown error",
+        });
+      }
+    } catch (err) {
+      toast.error("Refresh failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setRefreshingId(null);
+    }
+  }
+
+  const showForm = view.kind !== "list";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>MCP Servers</DialogTitle>
+          <DialogDescription>
+            Register remote MCP servers.
+          </DialogDescription>
+        </DialogHeader>
+
+        {showForm ? (
+          <div className="flex flex-col gap-4">
+            <div className="grid gap-2">
+              <Label htmlFor="mcp-display-name">Display name</Label>
+              <Input
+                id="mcp-display-name"
+                value={form.displayName}
+                onChange={(e) =>
+                  setForm((prev) => ({ ...prev, displayName: e.target.value }))
+                }
+                placeholder="e.g. GitHub MCP"
+              />
+            </div>
+            <div className="grid gap-2">
+              <Label htmlFor="mcp-url">URL</Label>
+              <Input
+                id="mcp-url"
+                value={form.url}
+                onChange={(e) =>
+                  setForm((prev) => ({ ...prev, url: e.target.value }))
+                }
+                placeholder="https://example.com/mcp"
+              />
+            </div>
+
+            <div className="flex items-start justify-between gap-3">
+              <div className="flex flex-col gap-0.5">
+                <Label className="text-sm" htmlFor="mcp-oauth">
+                  Use OAuth sign-in
+                </Label>
+                <span className="text-xs text-muted-foreground">
+                  For servers that require browser-based authentication
+                  (GitHub, Linear, etc.). A browser window will open on first
+                  connect.
+                </span>
+              </div>
+              <Switch
+                id="mcp-oauth"
+                checked={form.useOauth}
+                onCheckedChange={(useOauth) =>
+                  setForm((prev) => ({ ...prev, useOauth }))
+                }
+              />
+            </div>
+
+            <HeadersEditor
+              rows={form.headers}
+              onChange={(headers) => setForm((prev) => ({ ...prev, headers }))}
+            />
+
+            <div className="flex items-center justify-between gap-2 pt-2">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={testConnection}
+                disabled={testing || saving || !form.url.trim()}
+              >
+                {testing ? <Spinner /> : null}
+                Test connection
+              </Button>
+              <div className="flex gap-2">
+                <Button variant="ghost" onClick={cancelForm} disabled={saving}>
+                  Cancel
+                </Button>
+                <Button onClick={submitForm} disabled={saving}>
+                  {saving ? <Spinner /> : null}
+                  {view.kind === "edit" ? "Save changes" : "Add server"}
+                </Button>
+              </div>
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-col gap-3">
+            <div className="flex justify-end">
+              <Button size="sm" onClick={startCreate}>
+                <HugeiconsIcon icon={PlusSignIcon} size={14} />
+                Add server
+              </Button>
+            </div>
+            {loading ? (
+              <div className="flex justify-center py-6">
+                <Spinner />
+              </div>
+            ) : servers.length === 0 ? (
+              <div className="rounded-md border border-dashed py-6 text-center text-sm text-muted-foreground">
+                No MCP servers configured yet.
+              </div>
+            ) : (
+              <ul className="flex flex-col divide-y rounded-md border">
+                {servers.map((server) => (
+                  <li
+                    key={server.id}
+                    className="flex items-center justify-between gap-3 px-3 py-2"
+                  >
+                    <div className="min-w-0 flex-1">
+                      <div className="truncate font-medium">
+                        {server.display_name}
+                      </div>
+                      <div className="truncate text-xs text-muted-foreground">
+                        {server.url}
+                      </div>
+                    </div>
+                    <div className="flex items-center gap-1">
+                      <Switch
+                        checked={server.is_enabled}
+                        onCheckedChange={(next) => toggleEnabled(server, next)}
+                        aria-label="Enable server"
+                      />
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={() => refreshTools(server)}
+                        aria-label="Refresh tools"
+                        title="Refresh tools from this server"
+                        disabled={refreshingId === server.id}
+                      >
+                        {refreshingId === server.id ? (
+                          <Spinner />
+                        ) : (
+                          <RefreshCwIcon size={14} />
+                        )}
+                      </Button>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={() => startEdit(server)}
+                        aria-label="Edit server"
+                      >
+                        <HugeiconsIcon icon={Edit03Icon} size={14} />
+                      </Button>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={() => removeServer(server)}
+                        aria-label="Delete server"
+                      >
+                        <HugeiconsIcon icon={Delete02Icon} size={14} />
+                      </Button>
+                    </div>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 3714fb128a..8c852b8189 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -91,6 +91,8 @@ import {
   providerSupportsFastMode,
 } from "./provider-capabilities";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
+import { ChatMcpServersDialog } from "./chat-mcp-servers-dialog";
+import { listMcpServers } from "./api/mcp-servers-api";
 import type { InferenceParams } from "./types/runtime";
 
 export { defaultInferenceParams, type Preset } from "./presets/preset-policy";
@@ -1341,6 +1343,12 @@ export function ChatSettingsPanel({
             </div>
           </CollapsibleSection>
         ) : null}
+
+        {!isExternalModel ? (
+          <CollapsibleSection label="MCP Servers">
+            <McpServersSection />
+          </CollapsibleSection>
+        ) : null}
       </div>
       </div>
       <Dialog
@@ -1504,6 +1512,74 @@ function AutoHealToolCallsToggle() {
   );
 }
 
+function McpServersSection() {
+  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  const setMcpEnabledForChat = useChatRuntimeStore(
+    (s) => s.setMcpEnabledForChat,
+  );
+  const [enabledServerCount, setEnabledServerCount] = useState<number | null>(
+    null,
+  );
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [refreshTick, setRefreshTick] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    listMcpServers()
+      .then((rows) => {
+        if (cancelled) return;
+        setEnabledServerCount(rows.filter((row) => row.is_enabled).length);
+      })
+      .catch(() => {
+        if (!cancelled) setEnabledServerCount(0);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [refreshTick]);
+
+  return (
+    <div className="flex flex-col gap-3 pt-1">
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex min-w-0 items-center gap-1.5">
+          <span className="min-w-0 text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
+            Use MCP Servers
+          </span>
+          <InfoHint>
+            When on, every server marked enabled in the manage dialog is
+            attached to this chat's tool list.
+          </InfoHint>
+        </div>
+        <Switch
+          className="panel-switch"
+          checked={mcpEnabledForChat}
+          onCheckedChange={setMcpEnabledForChat}
+          disabled={enabledServerCount === 0 && !mcpEnabledForChat}
+        />
+      </div>
+      <div className="flex items-center justify-between">
+        <span className="text-[11px] text-muted-foreground">
+          {enabledServerCount === null
+            ? "Loading…"
+            : enabledServerCount === 0
+              ? "No servers configured"
+              : `${enabledServerCount} server${enabledServerCount === 1 ? "" : "s"} enabled`}
+        </span>
+        <Button variant="ghost" size="sm" onClick={() => setDialogOpen(true)}>
+          Manage…
+        </Button>
+      </div>
+      <ChatMcpServersDialog
+        open={dialogOpen}
+        onOpenChange={(next) => {
+          setDialogOpen(next);
+          if (!next) setRefreshTick((tick) => tick + 1);
+        }}
+      />
+    </div>
+  );
+}
+
 function ChatTemplateFields() {
   const defaultTemplate = useChatRuntimeStore((s) => s.defaultChatTemplate);
   const override = useChatRuntimeStore((s) => s.chatTemplateOverride);
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index a71e4127a2..09c06f92d8 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -27,6 +27,7 @@ export const CHAT_REASONING_ENABLED_KEY = "unsloth_chat_reasoning_enabled";
 export const CHAT_TOOLS_ENABLED_KEY = "unsloth_chat_tools_enabled";
 export const CHAT_CODE_TOOLS_ENABLED_KEY = "unsloth_chat_code_tools_enabled";
 export const CHAT_IMAGE_TOOLS_ENABLED_KEY = "unsloth_chat_image_tools_enabled";
+export const CHAT_MCP_ENABLED_KEY = "unsloth_chat_mcp_enabled";
 export const CHAT_WEB_FETCH_TOOLS_ENABLED_KEY =
   "unsloth_chat_web_fetch_tools_enabled";
 
@@ -282,6 +283,7 @@ type ChatRuntimeStore = {
   toolsEnabled: boolean;
   codeToolsEnabled: boolean;
   imageToolsEnabled: boolean;
+  mcpEnabledForChat: boolean;
   /**
    * Fetch pill state, independent of `toolsEnabled` (Search). Only
    * consulted when `providerSupportsBuiltinWebFetch` is true.
@@ -349,6 +351,7 @@ type ChatRuntimeStore = {
   setToolsEnabled: (enabled: boolean, options?: { persist?: boolean }) => void;
   setCodeToolsEnabled: (enabled: boolean) => void;
   setImageToolsEnabled: (enabled: boolean) => void;
+  setMcpEnabledForChat: (enabled: boolean) => void;
   setWebFetchToolsEnabled: (enabled: boolean) => void;
   setToolStatus: (status: string | null) => void;
   setGeneratingStatus: (status: string | null) => void;
@@ -599,6 +602,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   toolsEnabled: loadBool(CHAT_TOOLS_ENABLED_KEY, false),
   codeToolsEnabled: loadBool(CHAT_CODE_TOOLS_ENABLED_KEY, false),
   imageToolsEnabled: loadBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, false),
+  mcpEnabledForChat: loadBool(CHAT_MCP_ENABLED_KEY, false),
   webFetchToolsEnabled: loadBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, false),
   toolStatus: null,
   generatingStatus: null,
@@ -875,6 +879,11 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       saveBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, imageToolsEnabled);
       return { imageToolsEnabled };
     }),
+  setMcpEnabledForChat: (mcpEnabledForChat) =>
+    set(() => {
+      saveBool(CHAT_MCP_ENABLED_KEY, mcpEnabledForChat);
+      return { mcpEnabledForChat };
+    }),
   setWebFetchToolsEnabled: (webFetchToolsEnabled) =>
     set(() => {
       saveBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, webFetchToolsEnabled);

From 015fa5772a86938f0d9a546ca1dd36d956f028a4 Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Wed, 27 May 2026 20:02:20 +0530
Subject: [PATCH 012/222] Clear MRoPE after generation for GRPO  (#5683)

* clear mrope state after generation

* move clear mrope to here

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/backend/tests/test_cpu_threads.py | 16 +++++++------
 unsloth/models/rl_replacements.py        | 30 ++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/studio/backend/tests/test_cpu_threads.py b/studio/backend/tests/test_cpu_threads.py
index 0dbcbdb74b..1224941622 100644
--- a/studio/backend/tests/test_cpu_threads.py
+++ b/studio/backend/tests/test_cpu_threads.py
@@ -63,16 +63,18 @@ def test_cpu_thread_cap_is_opt_in(raw):
 
 
 # Anything that is not a positive integer raises a clear ValueError.
-@pytest.mark.parametrize("raw", ["zero", "0", "-3", "1.5", "abc", "8a", "0x4", "1e3", "4 0"])
+@pytest.mark.parametrize(
+    "raw", ["zero", "0", "-3", "1.5", "abc", "8a", "0x4", "1e3", "4 0"]
+)
 def test_cpu_thread_cap_requires_positive_integer(raw):
-    with pytest.raises(ValueError, match="must be a positive integer"):
+    with pytest.raises(ValueError, match = "must be a positive integer"):
         configure_cpu_threads({"UNSLOTH_CPU_THREADS": raw})
 
 
 # env=None path uses real os.environ (production call from run.py / main.py).
 def test_cpu_thread_cap_uses_os_environ_when_env_is_none(monkeypatch):
     for variable in (*_THREAD_POOL_ENV_VARS, "UNSLOTH_CPU_THREADS"):
-        monkeypatch.delenv(variable, raising=False)
+        monkeypatch.delenv(variable, raising = False)
     monkeypatch.setenv("UNSLOTH_CPU_THREADS", "3")
 
     configure_cpu_threads()
@@ -84,7 +86,7 @@ def test_cpu_thread_cap_uses_os_environ_when_env_is_none(monkeypatch):
 # Calling twice must not flip any seeded value.
 def test_cpu_thread_cap_idempotent(monkeypatch):
     for variable in (*_THREAD_POOL_ENV_VARS, "UNSLOTH_CPU_THREADS"):
-        monkeypatch.delenv(variable, raising=False)
+        monkeypatch.delenv(variable, raising = False)
     monkeypatch.setenv("UNSLOTH_CPU_THREADS", "5")
 
     configure_cpu_threads()
@@ -138,9 +140,9 @@ def test_invalid_cpu_thread_cap_exits_without_traceback(entry_point):
 
     result = subprocess.run(
         [sys.executable, str(entry_point)],
-        env=env,
-        capture_output=True,
-        text=True,
+        env = env,
+        capture_output = True,
+        text = True,
     )
 
     assert result.returncode == 1
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 51d20f9ff7..31d54675c9 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -53,6 +53,23 @@ from ._utils import _get_inference_mode_context_manager
 RL_EXTRA_ARGS = defaultdict(list)
 RL_FUNCTIONS = defaultdict(list)
 RL_PRE_ITEMS = defaultdict(list)
+
+
+def _unsloth_clear_stateful_mrope(model):
+    modules = getattr(model, "modules", None)
+    if modules is None:
+        return False
+
+    cleared = False
+    for module in modules():
+        if hasattr(module, "compute_3d_position_ids") and hasattr(
+            module, "rope_deltas"
+        ):
+            module.rope_deltas = None
+            cleared = True
+    return cleared
+
+
 RL_CONFIG_CHANGES = defaultdict(list)
 RL_METRICS_CHANGES = defaultdict(list)
 RL_ADDITIONAL_FUNCTIONS = defaultdict(list)
@@ -897,6 +914,18 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
         )
         function = function.replace(string_to_find, replacement_string)
 
+    _generate_return = """        ) = self._generate(prompts)"""
+    if _generate_return in function and "_unsloth_clear_stateful_mrope" not in function:
+        function = function.replace(
+            _generate_return,
+            _generate_return
+            + """
+
+        _unsloth_clear_stateful_mrope(
+            self.accelerator.unwrap_model(self.model, keep_fp32_wrapper = False)
+        )""",
+        )
+
     if "wake_up()" not in function:
         # Sleep functionality has been added to trl in v0.23.0. We do not want to redo this.
         # https://github.com/huggingface/trl/commit/edbe8234bc7e528f72ac76607de9d3e4753e2709
@@ -1509,6 +1538,7 @@ RL_PRE_ITEMS["grpo_trainer"].append(
 )
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_get_mm_token_id))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_fix_mm_token_type_ids))
+RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_clear_stateful_mrope))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(grpo_compute_loss))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(UnslothEfficientGRPO))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(grpo_accumulated_loss))

From a62eb80f7c03f627b226795f9475b5483e2fff05 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 27 May 2026 10:37:21 -0700
Subject: [PATCH 013/222] Detect CUDA UMD Version from newer nvidia-smi output
 (fixes #5812) (#5817)

* Detect CUDA UMD Version from newer nvidia-smi output (#5812)

Newer NVIDIA drivers (e.g. 610.x on Windows) print the driver's max
CUDA capability as "CUDA UMD Version: X.Y" instead of the legacy
"CUDA Version: X.Y" header.  The installers and Studio setup scripts
were only matching the legacy spelling, so on a fresh RTX 5090
laptop with a 13.x driver they failed to detect any CUDA version
and fell through to the cu126 wheel default.

Accept both spellings everywhere we parse nvidia-smi output:

- install.ps1: Get-TorchIndexUrl regex now allows " UMD"
- install.sh: two-expression sed (POSIX BRE has no "?"); the two
  patterns are mutually exclusive per line, head -1 picks the match
- studio/setup.ps1: Get-PytorchCudaTag and the $DriverMaxCuda
  detector both relaxed
- studio/install_llama_prebuilt.py: substring scan replaced with a
  regex search using the same pattern
- tests/sh/test_get_torch_index_url.sh: new make_mock_smi_umd helper
  plus three UMD cases (13.3 -> cu130, 12.8 -> cu128, 11.8 -> cu118);
  all 30 tests pass locally

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 install.ps1                          |  5 +++-
 install.sh                           | 10 +++++--
 studio/install_llama_prebuilt.py     | 18 ++++++++----
 studio/setup.ps1                     |  9 ++++--
 tests/sh/test_get_torch_index_url.sh | 42 ++++++++++++++++++++++++++++
 5 files changed, 73 insertions(+), 11 deletions(-)

diff --git a/install.ps1 b/install.ps1
index 3bb5fb3f8c..c4e8d8d522 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1253,7 +1253,10 @@ shell.Run cmd, 0, False
         if (-not $NvidiaSmiExe) { return "$baseUrl/cpu" }
         try {
             $output = & $NvidiaSmiExe 2>&1 | Out-String
-            if ($output -match 'CUDA Version:\s+(\d+)\.(\d+)') {
+            # Newer NVIDIA drivers (e.g. 610.x on Windows) print
+            # "CUDA UMD Version: X.Y" instead of the legacy "CUDA Version: X.Y".
+            # Accept both spellings so we don't fall through to the cu126 default.
+            if ($output -match 'CUDA(?: UMD)? Version:\s+(\d+)\.(\d+)') {
                 $major = [int]$Matches[1]; $minor = [int]$Matches[2]
                 if ($major -ge 13)                    { return "$baseUrl/cu130" }
                 if ($major -eq 12 -and $minor -ge 8)  { return "$baseUrl/cu128" }
diff --git a/install.sh b/install.sh
index 0548ee2a57..a3b76a3011 100755
--- a/install.sh
+++ b/install.sh
@@ -1683,9 +1683,15 @@ get_torch_index_url() {
         fi
         echo "$_base/cpu"; return
     fi
-    # Parse CUDA version from nvidia-smi output (POSIX-safe, no grep -P)
+    # Parse CUDA version from nvidia-smi output (POSIX-safe, no grep -P).
+    # Newer NVIDIA drivers (e.g. 610.x) print "CUDA UMD Version: X.Y" instead
+    # of the legacy "CUDA Version: X.Y"; accept both with two BRE expressions
+    # (POSIX sed does not support "?" without -E).  The two patterns are
+    # mutually exclusive per line, so head -1 picks the first emitted match.
     _cuda_ver=$(LC_ALL=C $_smi 2>/dev/null \
-        | sed -n 's/.*CUDA Version:[[:space:]]*\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
+        | sed -n \
+            -e 's/.*CUDA UMD Version:[[:space:]]*\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
+            -e 's/.*CUDA Version:[[:space:]]*\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
         | head -1)
     if [ -z "$_cuda_ver" ]; then
         echo "[WARN] Could not determine CUDA version from nvidia-smi, defaulting to cu126" >&2
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 394a1c9cd8..b9d63ecee9 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -2640,12 +2640,18 @@ def detect_host() -> HostInfo:
         try:
             result = run_capture([nvidia_smi], timeout = 20)
             merged = "\n".join(part for part in (result.stdout, result.stderr) if part)
-            for line in merged.splitlines():
-                if "CUDA Version:" in line:
-                    raw = line.split("CUDA Version:", 1)[1].strip().split()[0]
-                    major, minor = raw.split(".", 1)
-                    driver_cuda_version = (int(major), int(minor))
-                    break
+            # Newer NVIDIA drivers (e.g. 610.x on Windows) print
+            # "CUDA UMD Version: X.Y" instead of the legacy
+            # "CUDA Version: X.Y"; accept both spellings.
+            cuda_match = re.search(
+                r"CUDA(?: UMD)? Version:\s*(\d+)\.(\d+)",
+                merged,
+            )
+            if cuda_match is not None:
+                driver_cuda_version = (
+                    int(cuda_match.group(1)),
+                    int(cuda_match.group(2)),
+                )
         except Exception:
             pass
 
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 16df87bbd5..8950627ae8 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -352,7 +352,10 @@ function Get-PytorchCudaTag {
         # string.  Plain 2>$null doesn't fully suppress stderr in PS 5.1 --
         # ErrorRecord objects leak into $output and break the -match.
         $output = & $smiExe 2>&1 | Out-String
-        if ($output -match 'CUDA Version:\s+(\d+)\.(\d+)') {
+        # Newer NVIDIA drivers (e.g. 610.x on Windows) print
+        # "CUDA UMD Version: X.Y" instead of the legacy "CUDA Version: X.Y".
+        # Accept both spellings so we don't fall through to the cu126 default.
+        if ($output -match 'CUDA(?: UMD)? Version:\s+(\d+)\.(\d+)') {
             $major = [int]$Matches[1]
             $minor = [int]$Matches[2]
             # PyTorch 2.10 offers: cu124, cu126, cu128, cu130
@@ -842,7 +845,9 @@ if ($HasNvidiaSmi) {
 $DriverMaxCuda = $null
 try {
     $smiOut = & $NvidiaSmiExe 2>&1 | Out-String
-    if ($smiOut -match "CUDA Version:\s+([\d]+)\.([\d]+)") {
+    # Newer NVIDIA drivers (e.g. 610.x) report the driver max CUDA as
+    # "CUDA UMD Version: X.Y" rather than "CUDA Version: X.Y"; accept both.
+    if ($smiOut -match "CUDA(?: UMD)? Version:\s+([\d]+)\.([\d]+)") {
         $DriverMaxCuda = "$($Matches[1]).$($Matches[2])"
         substep "driver supports up to CUDA $DriverMaxCuda"
     }
diff --git a/tests/sh/test_get_torch_index_url.sh b/tests/sh/test_get_torch_index_url.sh
index 7235873f53..a9fafa5359 100755
--- a/tests/sh/test_get_torch_index_url.sh
+++ b/tests/sh/test_get_torch_index_url.sh
@@ -59,6 +59,29 @@ MOCK
     echo "$_dir"
 }
 
+# Helper: create a mock nvidia-smi that prints the new "CUDA UMD Version" header
+# layout used by newer NVIDIA drivers (e.g. 610.x on Windows).  See issue #5812.
+make_mock_smi_umd() {
+    _dir=$(mktemp -d)
+    cat > "$_dir/nvidia-smi" <<MOCK
+#!/bin/sh
+case "\$1" in
+    -L)
+        echo "GPU 0: NVIDIA GeForce RTX 5090 Laptop GPU (UUID: GPU-fake-uuid)"
+        ;;
+    *)
+        cat <<'SMI_OUT'
++-----------------------------------------------------------------------------------------+
+| NVIDIA-SMI 610.47                 KMD Version: 610.47        CUDA UMD Version: $1     |
++-----------------------------------------------------------------------------------------+
+SMI_OUT
+        ;;
+esac
+MOCK
+    chmod +x "$_dir/nvidia-smi"
+    echo "$_dir"
+}
+
 # Helper: create a mock amd-smi that prints a given ROCm version string
 # Supports both "amd-smi version" and "amd-smi list" subcommands so that
 # the GPU presence check (amd-smi list) also succeeds in tests.
@@ -278,6 +301,25 @@ assert_eq "empty mirror env -> official/cpu" "https://download.pytorch.org/whl/c
 _result=$(UNSLOTH_PYTORCH_MIRROR="https://mirror.example.com/whl/" run_func "none")
 assert_eq "trailing slash stripped -> mirror/cpu" "https://mirror.example.com/whl/cpu" "$_result"
 
+# 29) "CUDA UMD Version: 13.3" header (newer NVIDIA driver layout, issue #5812)
+#     -> cu130, not the cu126 fallback.
+_dir=$(make_mock_smi_umd "13.3")
+_result=$(run_func "$_dir")
+assert_eq "CUDA UMD Version 13.3 -> cu130" "https://download.pytorch.org/whl/cu130" "$_result"
+rm -rf "$_dir"
+
+# 30) "CUDA UMD Version: 12.8" header (newer layout on a 12.x driver) -> cu128
+_dir=$(make_mock_smi_umd "12.8")
+_result=$(run_func "$_dir")
+assert_eq "CUDA UMD Version 12.8 -> cu128" "https://download.pytorch.org/whl/cu128" "$_result"
+rm -rf "$_dir"
+
+# 31) "CUDA UMD Version: 11.8" header (newer layout on an older driver) -> cu118
+_dir=$(make_mock_smi_umd "11.8")
+_result=$(run_func "$_dir")
+assert_eq "CUDA UMD Version 11.8 -> cu118" "https://download.pytorch.org/whl/cu118" "$_result"
+rm -rf "$_dir"
+
 rm -f "$_FUNC_FILE"
 rm -rf "$_FAKE_SMI_DIR"
 rm -rf "$_TOOLS_DIR"

From 99e1f67322eda126e6ed9cf83a9a64ba1076cbbb Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Wed, 27 May 2026 18:46:49 +0100
Subject: [PATCH 014/222] Studio: remove dark mode upload circle (#5813)

* style: remove dark mode upload circle

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/frontend/src/components/assistant-ui/attachment.tsx | 2 +-
 studio/frontend/src/features/chat/shared-composer.tsx      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/attachment.tsx b/studio/frontend/src/components/assistant-ui/attachment.tsx
index 3ae1c68561..d814490c1d 100644
--- a/studio/frontend/src/components/assistant-ui/attachment.tsx
+++ b/studio/frontend/src/components/assistant-ui/attachment.tsx
@@ -238,7 +238,7 @@ export const ComposerAddAttachment: FC = () => {
         side="bottom"
         variant="ghost"
         size="icon"
-        className="aui-composer-add-attachment size-8.5 rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:border-muted-foreground/15 dark:hover:bg-muted-foreground/30"
+        className="aui-composer-add-attachment size-8.5 rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:hover:bg-muted-foreground/30"
         aria-label="Add Attachment"
       >
         <PlusIcon className="aui-attachment-add-icon size-5 stroke-[1.5px]" />
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index a811125a20..70f4311957 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -914,7 +914,7 @@ export function SharedComposer({
             side="bottom"
             variant="ghost"
             size="icon"
-            className="size-8.5 rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:border-muted-foreground/15 dark:hover:bg-muted-foreground/30"
+            className="size-8.5 rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:hover:bg-muted-foreground/30"
             onClick={() => {
               // The picker accepts both image and audio. Don't gate the
               // button on image-availability — addFiles still filters

From 15d70a1d7bd2557fa42672a9e5e2672f71a9c18c Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Thu, 28 May 2026 00:34:35 -0700
Subject: [PATCH 015/222] fix: honor --ctx-size and other forwarded args from
 `unsloth studio run` in Studio's context-fit logic (#5815)

* fix: honor --ctx-size and other forwarded args from `unsloth studio run` in Studio's context-fit logic

* refactor: extract resolve_requested_ctx as single source of truth

The test helper was reimplementing the two-line
'ctx_override = parse_ctx_override(...); requested_ctx = ctx_override
if ctx_override is not None else n_ctx' pattern locally, so the test
asserted against its own reimplementation rather than production logic.
Extract the conditional into resolve_requested_ctx and have both the
production caller and the test use it.

* fix(studio): honor pass-through cache type flags in KV VRAM estimate

Studio's KV cache VRAM estimate computed from the first-class
cache_type_kv even when the user passed -ctk/--cache-type-k/-ctv/
--cache-type-v via extras. Those flags reached llama-server fine
(last-wins on the CLI) but the pre-launch estimate kept using the
default f16 bytes-per-element, so GPU placement decisions could be
off when the user lowered cache precision via pass-through.

Adds parse_cache_override + resolve_cache_type_kv in llama_server_args.py
(mirroring parse_ctx_override / resolve_requested_ctx), wires both into
load_model alongside the existing ctx resolution, and adds focused
unit tests for the parser + resolver.

Follow-up to @rolandtannous review on #5815.

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    |  34 +++++-
 .../core/inference/llama_server_args.py       | 113 ++++++++++++++++++
 .../tests/test_llama_cpp_context_fit.py       |  58 ++++++++-
 .../backend/tests/test_llama_server_args.py   |  83 +++++++++++++
 4 files changed, 278 insertions(+), 10 deletions(-)

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 0325620b2d..2d95112d6d 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -28,6 +28,12 @@ from urllib.parse import urlparse
 
 import httpx
 
+from core.inference.llama_server_args import (
+    parse_cache_override,
+    parse_ctx_override,
+    resolve_cache_type_kv,
+    resolve_requested_ctx,
+)
 from core.tool_healing import (
     _TC_END_TAG_RE,
     _TC_FUNC_CLOSE_RE,
@@ -2724,7 +2730,23 @@ class LlamaCppBackend:
                 # Select GPU(s) based on model size + estimated KV cache.
                 # Seed safe defaults before GPU probing so the except path
                 # still has valid state to publish.
-                effective_ctx = n_ctx if n_ctx > 0 else (self._context_length or 0)
+                ctx_override = parse_ctx_override(extra_args)
+                requested_ctx = resolve_requested_ctx(extra_args, n_ctx)
+                cache_override = parse_cache_override(extra_args)
+                cache_type_kv = resolve_cache_type_kv(extra_args, cache_type_kv)
+                if ctx_override is not None and ctx_override > 0:
+                    logger.info(
+                        f"User --ctx-size {ctx_override} honored; "
+                        "skipping auto-reduce"
+                    )
+                if cache_override is not None:
+                    logger.info(
+                        f"User --cache-type-k/-v {cache_override} "
+                        "honored for KV estimate"
+                    )
+                effective_ctx = (
+                    requested_ctx if requested_ctx > 0 else (self._context_length or 0)
+                )
                 max_available_ctx = self._context_length or effective_ctx
                 gpus: list[tuple[int, int]] = []
                 try:
@@ -2734,8 +2756,8 @@ class LlamaCppBackend:
                     # Resolve effective context: 0 means let llama-server use the
                     # model's native length.  Only expand to a known native length
                     # if metadata is available; otherwise preserve 0 as a sentinel.
-                    if n_ctx > 0:
-                        effective_ctx = n_ctx
+                    if requested_ctx > 0:
+                        effective_ctx = requested_ctx
                     elif self._context_length is not None:
                         effective_ctx = self._context_length
                     else:
@@ -2788,7 +2810,7 @@ class LlamaCppBackend:
                     #   since multi-GPU is slower and the user didn't ask for a
                     #   specific context length.
                     gpu_indices, use_fit = None, True
-                    explicit_ctx = n_ctx > 0
+                    explicit_ctx = requested_ctx > 0
 
                     if gpus and self._can_estimate_kv() and effective_ctx > 0:
                         # Compute the largest hardware-aware cap from the model's
@@ -2845,7 +2867,7 @@ class LlamaCppBackend:
                             gpu_indices, use_fit = self._select_gpus(
                                 requested_total, gpus
                             )
-                            # No silent shrink: effective_ctx stays == n_ctx.
+                            # No silent shrink: effective_ctx stays == requested_ctx.
                         else:
                             # Auto context: prefer fewer GPUs, cap context
                             # to fit. Same headroom threshold as
@@ -2934,7 +2956,7 @@ class LlamaCppBackend:
                 except Exception as e:
                     logger.warning(f"GPU selection failed ({e}), using --fit on")
                     gpu_indices, use_fit = None, True
-                    effective_ctx = n_ctx  # fall back to original
+                    effective_ctx = requested_ctx  # fall back to original
 
                 launch_mmproj_path = self._resolve_launch_mmproj_path(
                     model_path = model_path,
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index 4f528a689f..b299e1ee9e 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -110,6 +110,8 @@ def validate_extra_args(args: Optional[Iterable[str]]) -> list[str]:
                 f"and cannot be passed as an extra arg"
             )
         out.append(token)
+    parse_ctx_override(out)
+    parse_cache_override(out)
     return out
 
 
@@ -166,6 +168,117 @@ _BOOLEAN_SHADOWING_FLAGS: frozenset[str] = frozenset(
 )
 
 
+def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
+    """Return the last user-supplied ``-c`` / ``--ctx-size`` value.
+
+    Mirrors llama.cpp's last-wins flag parsing for the one pass-through
+    numeric knob Studio's load-time fit logic needs to see.
+    """
+    if not args:
+        return None
+
+    tokens = [str(a) for a in args]
+    override: Optional[int] = None
+    i, n = 0, len(tokens)
+    while i < n:
+        tok = tokens[i]
+        flag = _flag_name(tok)
+        if flag is None or flag not in _CONTEXT_FLAGS:
+            i += 1
+            continue
+
+        if "=" in tok:
+            raw_value = tok.split("=", 1)[1]
+            i += 1
+        else:
+            if i + 1 >= n or _flag_name(tokens[i + 1]) is not None:
+                raise ValueError(
+                    f"llama-server flag '{flag}' requires an integer value"
+                )
+            raw_value = tokens[i + 1]
+            i += 2
+
+        try:
+            value = int(str(raw_value).strip())
+        except ValueError as exc:
+            raise ValueError(
+                f"llama-server flag '{flag}' requires an integer value"
+            ) from exc
+        if value < 0:
+            raise ValueError(
+                f"llama-server flag '{flag}' requires a non-negative integer value"
+            )
+        override = value
+
+    return override
+
+
+def resolve_requested_ctx(
+    args: Optional[Iterable[str]],
+    fallback_n_ctx: int,
+) -> int:
+    """Return the context size load_model should treat as requested.
+
+    Single source of truth for the two-line ``ctx_override = parse_ctx_override(...);
+    requested_ctx = ctx_override if ctx_override is not None else n_ctx`` pattern
+    used by ``load_model`` so tests don't have to reimplement the conditional
+    locally and then assert against their own reimplementation.
+    """
+    override = parse_ctx_override(args)
+    return override if override is not None else fallback_n_ctx
+
+
+def parse_cache_override(args: Optional[Iterable[str]]) -> Optional[str]:
+    """Return the last-wins cache type if extras pass cache flags.
+
+    Mirrors parse_ctx_override but for cache type. Recognises both -ctk
+    (key) and -ctv (value). When both flags appear, returns the last-wins
+    value, treating key and value cache flags as the same setting because
+    Studio's KV estimate has a single cache_type_kv knob.
+    """
+    if not args:
+        return None
+
+    tokens = [str(a) for a in args]
+    override: Optional[str] = None
+    i, n = 0, len(tokens)
+    while i < n:
+        tok = tokens[i]
+        flag = _flag_name(tok)
+        if flag is None or flag not in _CACHE_FLAGS:
+            i += 1
+            continue
+
+        if "=" in tok:
+            raw_value = tok.split("=", 1)[1]
+            i += 1
+        else:
+            if i + 1 >= n or _flag_name(tokens[i + 1]) is not None:
+                raise ValueError(f"llama-server flag '{flag}' requires a value")
+            raw_value = tokens[i + 1]
+            i += 2
+
+        value = str(raw_value).strip()
+        if not value:
+            raise ValueError(f"llama-server flag '{flag}' requires a non-empty value")
+        override = value
+
+    return override
+
+
+def resolve_cache_type_kv(
+    args: Optional[Iterable[str]],
+    fallback_cache_type_kv: Optional[str],
+) -> Optional[str]:
+    """Return the cache type load_model should treat as requested.
+
+    Single source of truth for the cache override conditional used by
+    ``load_model``.
+    """
+    override = parse_cache_override(args)
+    return override if override is not None else fallback_cache_type_kv
+
+
 def strip_shadowing_flags(
     args: Iterable[str],
     *,
diff --git a/studio/backend/tests/test_llama_cpp_context_fit.py b/studio/backend/tests/test_llama_cpp_context_fit.py
index 1ea76edd15..6fe5372147 100644
--- a/studio/backend/tests/test_llama_cpp_context_fit.py
+++ b/studio/backend/tests/test_llama_cpp_context_fit.py
@@ -84,6 +84,7 @@ _httpx_stub.Client = type(
 sys.modules.setdefault("httpx", _httpx_stub)
 
 from core.inference.llama_cpp import LlamaCppBackend
+from core.inference.llama_server_args import parse_ctx_override, resolve_requested_ctx
 
 
 # ---------------------------------------------------------------------------
@@ -131,6 +132,7 @@ def _drive(
     native_ctx = 131072,
     kv_per_token_bytes = 325_000,
     can_estimate_kv = True,
+    extra_args = None,
 ):
     """Drive the post-metadata portion of load_model with stubbed inputs.
 
@@ -148,11 +150,16 @@ def _drive(
     inst._can_estimate_kv = lambda: can_estimate_kv
 
     context_length = inst._context_length
+    # Use the production helper instead of reimplementing the conditional
+    # locally; reimplementing makes the test pass for the test's own logic
+    # rather than production's, and silent drift won't be caught.
+    ctx_override = parse_ctx_override(extra_args)
+    requested_ctx = resolve_requested_ctx(extra_args, n_ctx)
 
-    effective_ctx = n_ctx if n_ctx > 0 else (context_length or 0)
+    effective_ctx = requested_ctx if requested_ctx > 0 else (context_length or 0)
     max_available_ctx = context_length or effective_ctx
-    if n_ctx > 0:
-        effective_ctx = n_ctx
+    if requested_ctx > 0:
+        effective_ctx = requested_ctx
     elif context_length is not None:
         effective_ctx = context_length
     else:
@@ -161,7 +168,7 @@ def _drive(
     max_available_ctx = context_length or effective_ctx
 
     gpu_indices, use_fit = None, True
-    explicit_ctx = n_ctx > 0
+    explicit_ctx = requested_ctx > 0
 
     if gpus and inst._can_estimate_kv() and effective_ctx > 0:
         native_ctx_for_cap = context_length or effective_ctx
@@ -236,6 +243,7 @@ def _drive(
         "gpu_indices": gpu_indices,
         "max_available_ctx": max_available_ctx,
         "original_ctx": original_ctx,
+        "ctx_override": ctx_override,
     }
 
 
@@ -349,6 +357,48 @@ class TestExplicitCtxRespectsUser:
         assert plan["c_arg"] == 2048
 
 
+# ---------------------------------------------------------------------------
+# Pass-through --ctx-size participates in context fit (#5676).
+# ---------------------------------------------------------------------------
+
+
+class TestExtraArgsCtxOverride:
+    def test_ctx_size_extra_honored_over_auto(self):
+        plan = _drive(
+            n_ctx = 0,
+            model_gib = 131,
+            gpus = [(0, 97_000)],
+            native_ctx = 196608,
+            extra_args = ["--ctx-size", "128000"],
+        )
+        assert plan["ctx_override"] == 128000
+        assert plan["original_ctx"] == 128000
+        assert plan["c_arg"] == 128000
+        assert plan["use_fit"] is True
+
+    def test_ctx_size_short_alias_honored_over_auto(self):
+        plan = _drive(
+            n_ctx = 0,
+            model_gib = 131,
+            gpus = [(0, 97_000)],
+            native_ctx = 196608,
+            extra_args = ["-c", "128000"],
+        )
+        assert plan["c_arg"] == 128000
+        assert plan["use_fit"] is True
+
+    def test_ctx_size_extra_wins_over_first_class_field(self):
+        plan = _drive(
+            n_ctx = 4096,
+            model_gib = 8,
+            gpus = [(0, 24_000)],
+            native_ctx = 131072,
+            extra_args = ["--ctx-size", "128000"],
+        )
+        assert plan["original_ctx"] == 128000
+        assert plan["c_arg"] == 128000
+
+
 # ---------------------------------------------------------------------------
 # Non-regression: fittable + auto still auto-picks largest fitting ctx
 # ---------------------------------------------------------------------------
diff --git a/studio/backend/tests/test_llama_server_args.py b/studio/backend/tests/test_llama_server_args.py
index 02a272ba3e..2f7431497d 100644
--- a/studio/backend/tests/test_llama_server_args.py
+++ b/studio/backend/tests/test_llama_server_args.py
@@ -30,6 +30,9 @@ _spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
 _lsa = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(_lsa)
 is_managed_flag = _lsa.is_managed_flag
+parse_cache_override = _lsa.parse_cache_override
+parse_ctx_override = _lsa.parse_ctx_override
+resolve_cache_type_kv = _lsa.resolve_cache_type_kv
 strip_shadowing_flags = _lsa.strip_shadowing_flags
 validate_extra_args = _lsa.validate_extra_args
 
@@ -410,6 +413,86 @@ def test_is_managed_flag_false_for_mtp_pass_through():
     assert is_managed_flag("--spec-ngram-mod-n-max") is False
 
 
+# ── parse_ctx_override ───────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "args,expected",
+    [
+        (None, None),
+        ([], None),
+        (["--top-k", "20"], None),
+        (["--ctx-size", "128000"], 128000),
+        (["--ctx-size=128000"], 128000),
+        (["-c", "128000"], 128000),
+        (["-c=128000"], 128000),
+        (["-c", "4096", "--ctx-size", "128000"], 128000),
+    ],
+)
+def test_parse_ctx_override(args, expected):
+    assert parse_ctx_override(args) == expected
+
+
+@pytest.mark.parametrize(
+    "args",
+    [
+        ["--ctx-size"],
+        ["--ctx-size", "--top-k"],
+        ["--ctx-size", "abc"],
+        ["--ctx-size=abc"],
+        ["-c", "-1"],
+    ],
+)
+def test_parse_ctx_override_rejects_malformed_values(args):
+    with pytest.raises(ValueError, match = "ctx-size|'-c'"):
+        parse_ctx_override(args)
+
+
+def test_validate_extra_args_rejects_malformed_ctx_override():
+    with pytest.raises(ValueError, match = "ctx-size"):
+        validate_extra_args(["--ctx-size", "abc"])
+
+
+# ── parse_cache_override ─────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "args,expected",
+    [
+        (None, None),
+        ([], None),
+        (["--top-k", "20"], None),
+        (["--cache-type-k", "q8_0"], "q8_0"),
+        (["-ctk", "q4_0"], "q4_0"),
+        (["-ctv", "q4_0"], "q4_0"),
+        (["--cache-type-k=q4_0"], "q4_0"),
+        (["-ctk", "f16", "-ctk", "q8_0"], "q8_0"),
+    ],
+)
+def test_parse_cache_override(args, expected):
+    assert parse_cache_override(args) == expected
+
+
+@pytest.mark.parametrize(
+    "args",
+    [
+        ["-ctk"],
+        ["-ctk", "-c", "4096"],
+    ],
+)
+def test_parse_cache_override_rejects_malformed_values(args):
+    with pytest.raises(ValueError, match = "cache-type|'-ctk'"):
+        parse_cache_override(args)
+
+
+def test_resolve_cache_type_kv_uses_override_when_present():
+    assert resolve_cache_type_kv(["--cache-type-k", "q8_0"], "f16") == "q8_0"
+
+
+def test_resolve_cache_type_kv_uses_fallback_without_override():
+    assert resolve_cache_type_kv(["--top-k", "20"], "f16") == "f16"
+
+
 def test_strip_shadowing_flags_boolean_does_not_consume_next_token():
     # `--spec-default` is boolean; drop just the flag, keep the next token.
     out = strip_shadowing_flags(["--spec-default", "ngram-mod"], strip_spec = True)

From 185ff00c62853c376d1a7dbeac98d0e60517b2fc Mon Sep 17 00:00:00 2001
From: alkinun <alkinunl@gmail.com>
Date: Thu, 28 May 2026 12:28:52 +0300
Subject: [PATCH 016/222] Fix non-streaming GGUF chat completion usage (#5781)

* Fix GGUF non-stream chat completion usage

* Handle nullable GGUF completion usage

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
---
 studio/backend/routes/inference.py            | 14 +++-
 .../tests/test_gguf_completion_usage.py       | 78 +++++++++++++++++++
 2 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 studio/backend/tests/test_gguf_completion_usage.py

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 259337616c..7d1c7b2488 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3091,9 +3091,12 @@ async def openai_chat_completions(
         else:
             try:
                 full_text = ""
+                completion_usage = None
                 for token in gguf_generate():
                     if isinstance(token, dict):
-                        continue  # skip metadata dict in non-streaming path
+                        if token.get("type") == "metadata":
+                            completion_usage = token.get("usage")
+                        continue
                     full_text = token
 
                 response = ChatCompletion(
@@ -3106,6 +3109,15 @@ async def openai_chat_completions(
                             finish_reason = "stop",
                         )
                     ],
+                    usage = CompletionUsage(
+                        prompt_tokens = (completion_usage or {}).get("prompt_tokens")
+                        or 0,
+                        completion_tokens = (completion_usage or {}).get(
+                            "completion_tokens"
+                        )
+                        or 0,
+                        total_tokens = (completion_usage or {}).get("total_tokens") or 0,
+                    ),
                 )
                 return JSONResponse(content = response.model_dump())
 
diff --git a/studio/backend/tests/test_gguf_completion_usage.py b/studio/backend/tests/test_gguf_completion_usage.py
new file mode 100644
index 0000000000..b8cfaee7c7
--- /dev/null
+++ b/studio/backend/tests/test_gguf_completion_usage.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Regression tests for GGUF non-streaming chat completion usage."""
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from auth.authentication import get_current_subject
+import routes.inference as inference_route
+
+
+class _GgufBackend:
+    is_loaded = True
+    model_identifier = "test/model.gguf"
+    _is_audio = False
+    is_vision = False
+    supports_tools = False
+
+    def __init__(self, usage):
+        self.usage = usage
+
+    def generate_chat_completion(self, **kwargs):
+        yield "answer"
+        yield {
+            "type": "metadata",
+            "usage": self.usage,
+            "timings": {"prompt_n": 23, "predicted_n": 1283},
+        }
+
+
+def _request_completion(monkeypatch, usage):
+    monkeypatch.setattr(
+        inference_route, "get_llama_cpp_backend", lambda: _GgufBackend(usage)
+    )
+    monkeypatch.setattr(
+        inference_route, "_effective_enable_tools", lambda payload: False
+    )
+
+    app = FastAPI()
+    app.include_router(inference_route.router)
+    app.dependency_overrides[get_current_subject] = lambda: "test-user"
+
+    return TestClient(app).post(
+        "/chat/completions",
+        json = {
+            "messages": [{"role": "user", "content": "Why is the sky blue?"}],
+            "stream": False,
+        },
+    )
+
+
+def test_non_streaming_gguf_completion_includes_generated_usage(monkeypatch):
+    response = _request_completion(
+        monkeypatch,
+        {"prompt_tokens": 23, "completion_tokens": 1283, "total_tokens": 1306},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["usage"] == {
+        "prompt_tokens": 23,
+        "completion_tokens": 1283,
+        "total_tokens": 1306,
+    }
+
+
+def test_non_streaming_gguf_completion_defaults_nullable_usage_to_zero(monkeypatch):
+    response = _request_completion(
+        monkeypatch,
+        {"prompt_tokens": None, "completion_tokens": 1283, "total_tokens": None},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["usage"] == {
+        "prompt_tokens": 0,
+        "completion_tokens": 1283,
+        "total_tokens": 0,
+    }

From ee6695118c65d7e1ce1aba4b5da95e297b75ff9e Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Fri, 29 May 2026 01:54:48 -0500
Subject: [PATCH 017/222] Fix/studio colab proxy and iframe - Unsloth Studio
 not loading in Colab (iframe "refused to connect" and wrong URL) (#5844)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(studio/colab): merge iframe+keepalive into start(), add proxy_headers to uvicorn

- Move serve_kernel_port_as_iframe and keepalive loop into colab.start()
  so both run in the same cell execution context, eliminating the race
  where the proxy URL was shown before the iframe cell had a chance to run
- Add a 2s sleep after run_server() before show_link() to give Colab's
  proxy infrastructure time to register the bound port
- Add proxy_headers=True and forwarded_allow_ips="*" to uvicorn Config
  so X-Forwarded-Proto/Host from Colab's reverse proxy are trusted
- Simplify notebook start cell (no more separate iframe cell needed)

* fix(studio/colab): fix iframe blocking and server thread crash in Colab

Two root causes for the long-standing proxy/iframe breakage:

1. SecurityHeadersMiddleware set X-Frame-Options: DENY and
   frame-ancestors 'none' unconditionally, blocking
   serve_kernel_port_as_iframe regardless of server health.
   Fix: detect Colab via COLAB_BACKEND_URL/COLAB_GPU env vars,
   relax frame-ancestors to *.prod.colab.dev and omit X-Frame-Options.

2. asyncio.run() in the daemon thread conflicted with nest_asyncio's
   global patches applied on the main thread, causing the server to
   crash silently after ready_event fired.
   Fix: use explicit new_event_loop() + run_until_complete() in the
   daemon thread to bypass nest_asyncio's asyncio.run patch.

Also replace blind time.sleep(2) with a health endpoint poll so the
link and iframe are only shown once the server is truly reachable.

* fix(studio/colab): use reliable /content + google.colab path for Colab detection

COLAB_BACKEND_URL and COLAB_GPU env vars aren't consistently set across
all Colab runtime versions. Use /content dir + google.colab package path
as a more reliable signal, computed once at module load.

* fix(studio/colab): fix port mismatch, health-check silence, and CSP framing

Four bugs causing the iframe and URL button to always fail:

1. Port not propagated back: run_server auto-increments when 8888 is taken,
   but start() kept using the original port for show_link() and
   serve_kernel_port_as_iframe() — now reads app.state.server_port.

2. Silent health-check failure: the poll loop never checked whether any
   attempt succeeded; on all-fail it continued and showed a dead link —
   now exits early with a clear error message.

3. CSP frame-ancestors too narrow: '*.prod.colab.dev' only matches one
   subdomain level; actual Colab proxy URLs are two levels deep
   (e.g. foo.region.prod.colab.dev), and the parent frame may also be
   colab.research.google.com or a sandboxed null-origin output iframe —
   changed to '*' in Colab mode (single-user sandbox, no security loss).

4. _IS_COLAB detection hardcoded python3.10/3.11 paths: Python 3.12+
   Colab runtimes wouldn't match when env vars aren't set — replaced with
   a glob over python3.*/dist-packages/google/colab.

* fix(studio/colab): harden Colab startup against every known failure mode

colab.py:
- get_colab_url: retry eval_js up to 3x (10s timeout each), validate that
  result is a real https:// URL containing the port before accepting it;
  log a clear warning when falling back to localhost
- show_link: safe short_url truncation (try/except around str.index so an
  unexpected URL shape never blocks the link card from rendering); also
  emit the URL via logger so it's visible in cell text output even if
  HTML display is suppressed
- start: detect "already running" at entry — on cell re-run Studio is
  still healthy on port 8888; skip re-launch and go straight to
  show+iframe so the user never ends up with mismatched port state
- start: wrap run_server in try/except (SystemExit + Exception) so
  startup errors surface as readable messages rather than cell crashes
- start: check frontend_path/index.html exists, not just the directory
- start: remove unused `import sys`
- start / keepalive: catch KeyboardInterrupt so interrupting the cell
  prints a clean "stopped" message instead of a raw traceback
- extract _is_studio_healthy() and _show_and_embed() helpers to
  deduplicate the fast-path and normal-path logic

main.py:
- _build_csp: in Colab mode, extend script-src to include
  *.prod.colab.dev and *.googleusercontent.com (Colab injects scripts
  from these origins into the output iframe scaffolding)
- _build_csp: in Colab mode, extend connect-src with blob:, data:,
  wss://*.prod.colab.dev, and wss://*.googleusercontent.com so
  WebSocket streams and Colab kernel traffic are not blocked by CSP

* fix(studio/colab): fix iframe width responsiveness and height sizing

Replace serve_kernel_port_as_iframe with a raw CSS iframe for two
reasons:

1. Width responsiveness: serve_kernel_port_as_iframe sets the width as
   an HTML attribute (width="100%") which Colab's output machinery can
   bake into a fixed pixel value on first render, causing the Studio to
   stop following the notebook panel width when it opens/closes or the
   window resizes. A CSS style property (style="width:100%") participates
   in normal reflow and always tracks the parent container width.

2. Height sizing: the hardcoded height=1200 was too tall on short monitors
   (forced outer-page scroll) and wasted space on tall ones. A small JS
   snippet reads screen.availHeight and sets height to ~82% of the screen,
   clamped to [600, 1100]px, with a resize listener that re-fits on zoom
   changes and panel open/close events.

Also eliminate the double eval_js call: _show_and_embed now fetches the
Colab proxy URL once and passes it to show_link via the new _url kwarg,
so google.colab.kernel.proxyPort is only called once per invocation.

Falls back to serve_kernel_port_as_iframe if IPython.display.HTML is
unavailable for any reason.

* fix(studio/colab): fix link button + add fullscreen hover button to iframe

Link button: target="_blank" is blocked by Colab's output sandbox.
Switch to onclick="window.open(url,'_blank')" which the sandbox allows.

Fullscreen: add a small button that appears on hover in the top-right
corner of the iframe. Clicking it calls requestFullscreen() on the
wrapper div and stretches the iframe to 100vh/100vw. Exits back to
normal on fullscreen change.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* revert(studio/colab): remove fullscreen button

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/colab): address review feedback

- Wrap both urlopen calls in with statements to prevent socket/fd leaks
- Replace JS resize listener with CSS height:82vh — simpler, responsive,
  and no risk of leaked window listeners on cell re-runs
- Use importlib.util.find_spec("google.colab") instead of a glob path
  to detect Colab; more robust across Python versions and venv layouts

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/colab): fall back to href navigation when window.open is blocked

window.open from a cross-origin sandboxed Colab output iframe can be
silently blocked by the browser (returns null, no exception). The old
code returned false unconditionally, so a blocked popup left the button
doing nothing. Now: if window.open succeeds the new tab opens and the
href is suppressed; if it returns null the browser follows the href,
navigating the output cell to Studio — always does something useful.

* fix(studio/colab): remove button, give iframe a branded header bar

The "Open Unsloth Studio" button was unreliable in Colab's sandboxed
output context regardless of how window.open was called. Since the
iframe already loads Studio inline, the button added no value and
confused users with a URL that 404s outside the output cell.

Replace the separate link card + bare iframe with a single block:
a slim black header bar (Unsloth logo + truncated URL) flush on top
of the full-height responsive iframe. Cleaner and removes the broken
button entirely.

* studio: gate uvicorn proxy_headers/forwarded_allow_ips behind _IS_COLAB

forwarded_allow_ips="*" was applied unconditionally, so every Studio
deployment trusted X-Forwarded-* headers from any client. Only Colab needs
that, because its reverse proxy fronts the kernel. For a normal
local/standalone Studio this is an unwanted relaxation, especially when bound
to 0.0.0.0.

Now proxy_headers/forwarded_allow_ips are only set when _IS_COLAB. Standalone
runs fall back to uvicorn's defaults (proxy_headers honored from loopback
only), restoring the prior security posture, while Colab keeps the wide trust
its proxy requires.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/Unsloth_Studio_Colab.ipynb |  23 +---
 studio/backend/colab.py           | 216 ++++++++++++++++++++++++++----
 studio/backend/main.py            |  47 ++++++-
 studio/backend/run.py             |  25 +++-
 4 files changed, 258 insertions(+), 53 deletions(-)

diff --git a/studio/Unsloth_Studio_Colab.ipynb b/studio/Unsloth_Studio_Colab.ipynb
index c3aec04820..00eecfe51d 100644
--- a/studio/Unsloth_Studio_Colab.ipynb
+++ b/studio/Unsloth_Studio_Colab.ipynb
@@ -84,26 +84,7 @@
     "id": "277e431e"
    },
    "outputs": [],
-   "source": [
-    "import sys, time\n",
-    "sys.path.insert(0, \"/content/unsloth/studio/backend\")\n",
-    "from colab import start\n",
-    "start()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "source": [
-    "from google.colab import output\n",
-    "output.serve_kernel_port_as_iframe(8888, height = 1200, width = \"100%\")\n",
-    "for _ in range(10000): time.sleep(300), print(\"=\", end = \"\")"
-   ],
-   "metadata": {
-    "id": "wb9UELh--XzX"
-   },
-   "id": "wb9UELh--XzX",
-   "execution_count": null,
-   "outputs": []
+   "source": "import sys\nsys.path.insert(0, \"/content/unsloth/studio/backend\")\nfrom colab import start\nstart()"
   },
   {
    "cell_type": "markdown",
@@ -150,4 +131,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}
\ No newline at end of file
diff --git a/studio/backend/colab.py b/studio/backend/colab.py
index 7336f8a532..1bca16359b 100644
--- a/studio/backend/colab.py
+++ b/studio/backend/colab.py
@@ -26,30 +26,68 @@ logger = get_logger(__name__)
 def get_colab_url(port: int = 8888) -> str:
     """
     Get the actual Colab proxy URL for a port.
+
+    Retries up to 3 times and validates that the result is a real HTTPS Colab
+    URL before returning.  Falls back to http://localhost:{port} only when all
+    attempts fail.
     """
+    import time as _time
+
+    fallback = f"http://localhost:{port}"
+
     try:
         from google.colab.output import eval_js
+    except ImportError:
+        return fallback
 
-        # Use Colab's proxy mechanism
-        url = eval_js(f"google.colab.kernel.proxyPort({port})", timeout_sec = 5)
-        return url if url else f"http://localhost:{port}"
-    except Exception as e:
-        logger.info(f"Note: Could not get Colab URL ({e})")
-        return f"http://localhost:{port}"
+    for attempt in range(3):
+        try:
+            url = eval_js(f"google.colab.kernel.proxyPort({port})", timeout_sec = 10)
+            # A valid Colab proxy URL starts with https:// and embeds the port.
+            if (
+                url
+                and isinstance(url, str)
+                and url.startswith("https://")
+                and str(port) in url
+            ):
+                return url.rstrip("/")
+        except Exception as e:
+            logger.info(f"Note: Could not get Colab URL (attempt {attempt + 1}/3: {e})")
+        if attempt < 2:
+            _time.sleep(1)
+
+    logger.warning(
+        f"Could not get a valid Colab proxy URL after 3 attempts — using localhost fallback. "
+        f"The link/iframe may not work from outside the runtime."
+    )
+    return fallback
 
 
-def show_link(port: int = 8888):
-    """Display a styled clickable link to the UI."""
+def show_link(port: int = 8888, *, _url: "str | None" = None):
+    """Display a styled clickable link to the UI.
+
+    *_url* is an optional pre-fetched Colab proxy URL. When omitted,
+    ``get_colab_url(port)`` is called internally. Pass it from
+    ``_show_and_embed`` to avoid a second ``eval_js`` round-trip.
+    """
     from IPython.display import display, HTML
 
-    # Get real Colab proxy URL
-    url = get_colab_url(port)
+    url = _url if _url is not None else get_colab_url(port)
+
+    # Build a truncated display URL. Wrap in try/except so an unexpected URL
+    # shape never prevents the link from rendering.
+    try:
+        port_prefix = f"{port}-"
+        idx = url.index(port_prefix)
+        next_dash = url.index("-", idx + len(port_prefix))
+        short_url = url[: next_dash + 1] + "..."
+    except (ValueError, IndexError):
+        short_url = url
+
+    # Also emit a plain-text line so the URL is visible even if HTML display
+    # is suppressed or fails.
+    logger.info(f"🌐 Unsloth Studio URL: {url}")
 
-    short_url = (
-        url[: url.index("-", url.index(f"{port}-") + len(str(port)) + 1) + 1] + "..."
-        if f"{port}-" in url
-        else url
-    )
     html = f"""
     <div style="display: inline-block; padding: 20px; background: #ffffff; border: 2px solid #000000;
                 border-radius: 12px; margin: 10px 0; font-family: system-ui, -apple-system, sans-serif;">
@@ -59,10 +97,10 @@ def show_link(port: int = 8888):
                  height="48" style="display:block;">
             Unsloth Studio is Ready!
         </h2>
-        <a href="{url}" target="_blank"
+        <a href="{url}" onclick="var w=window.open(this.href,'_blank');if(!w){{return true;}}return false;"
            style="display: inline-flex; align-items: center; gap: 10px; padding: 14px 28px;
                   background: #000000; color: white; text-decoration: none; border-radius: 8px;
-                  font-weight: 800; font-size: 16px;">
+                  font-weight: 800; font-size: 16px; cursor: pointer;">
             <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="white"><polygon points="5,3 19,12 5,21"/></svg>
             Open Unsloth Studio
         </a>
@@ -77,6 +115,75 @@ def show_link(port: int = 8888):
     display(HTML(html))
 
 
+def _is_studio_healthy(port: int, timeout: float = 2.0) -> bool:
+    """Return True if a Studio backend is already answering health checks on *port*."""
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(
+            f"http://localhost:{port}/api/health", timeout = timeout
+        ):
+            return True
+    except Exception:
+        return False
+
+
+def _show_and_embed(port: int):
+    """Embed the Studio inline for *port* with a branded header bar.
+
+    Fetches the Colab proxy URL once (registering the port with Colab's
+    reverse-proxy at the same time) then renders a header bar + full-height
+    iframe as a single HTML block.
+
+    Falls back to ``serve_kernel_port_as_iframe`` if ``IPython.display.HTML``
+    is unavailable for any reason.
+    """
+    url = get_colab_url(port)
+    logger.info(f"🌐 Unsloth Studio URL: {url}")
+
+    try:
+        from IPython.display import HTML, display
+
+        iframe_id = f"unsloth-studio-{port}"
+
+        # Truncated URL shown in the header — best-effort, falls back to full URL.
+        try:
+            port_prefix = f"{port}-"
+            idx = url.index(port_prefix)
+            next_dash = url.index("-", idx + len(port_prefix))
+            short_url = url[: next_dash + 1] + "..."
+        except (ValueError, IndexError):
+            short_url = url
+
+        display(
+            HTML(f"""
+<div style="font-family:system-ui,-apple-system,sans-serif;margin:8px 0;
+            border-radius:12px;overflow:hidden;box-shadow:0 2px 16px rgba(0,0,0,0.18);">
+  <div style="display:flex;align-items:center;gap:10px;padding:10px 16px;background:#000;">
+    <img src="https://github.com/unslothai/unsloth/raw/main/studio/frontend/public/unsloth-gem.png"
+         height="26" style="display:block;">
+    <span style="color:#fff;font-weight:700;font-size:15px;letter-spacing:-0.2px;">Unsloth Studio</span>
+    <span style="margin-left:auto;color:#666;font-size:11px;font-family:monospace;">{short_url}</span>
+  </div>
+  <iframe
+    id="{iframe_id}"
+    src="{url}"
+    style="width:100%;height:82vh;min-height:600px;max-height:1100px;border:none;display:block;box-sizing:border-box;"
+    allow="clipboard-read; clipboard-write"
+  ></iframe>
+</div>
+""")
+        )
+    except Exception:
+        # Fallback: Colab's built-in helper (less control, but always works)
+        try:
+            from google.colab import output as colab_output
+
+            colab_output.serve_kernel_port_as_iframe(port, height = 900, width = "100%")
+        except ImportError:
+            pass
+
+
 def start(port: int = 8888):
     """
     Start Unsloth Studio server in Colab and display the URL.
@@ -85,10 +192,26 @@ def start(port: int = 8888):
         from colab import start
         start()
     """
-    import sys
+    import time
 
     logger.info("🦥 Starting Unsloth Studio...")
 
+    # --- Fast path: Studio is already running (cell re-run) ---
+    # Re-launching would either collide on the port or silently shift to a new
+    # port and confuse the user.  Just re-show the link and iframe instead.
+    if _is_studio_healthy(port):
+        logger.info(
+            f"   Studio is already running on port {port} — reusing existing server."
+        )
+        _show_and_embed(port)
+        try:
+            for _ in range(10000):
+                time.sleep(300)
+                print("=", end = "", flush = True)
+        except KeyboardInterrupt:
+            logger.info("\nUnsloth Studio keepalive stopped.")
+        return
+
     logger.info("   Loading backend...")
     from run import run_server
 
@@ -96,18 +219,63 @@ def start(port: int = 8888):
     repo_root = Path(__file__).parent.parent
     frontend_path = repo_root / "frontend" / "dist"
 
-    if not frontend_path.exists():
+    if not (frontend_path / "index.html").exists():
         logger.info("❌ Frontend not built! Please run the setup cell first.")
         return
 
     logger.info("   Starting server...")
-    # Start server silently
-    run_server(host = "0.0.0.0", port = port, frontend_path = frontend_path, silent = True)
+    try:
+        app = run_server(
+            host = "0.0.0.0", port = port, frontend_path = frontend_path, silent = True
+        )
+    except SystemExit as exc:
+        logger.error(f"❌ Unsloth Studio failed to start: {exc}")
+        return
+    except Exception as exc:
+        logger.error(f"❌ Unsloth Studio failed to start: {exc}")
+        return
 
-    logger.info("   Server started!")
+    # run_server auto-increments the port when the requested one is already in
+    # use (e.g. Jupyter occupying 8888). Read back the actual bound port so the
+    # Colab proxy URL and iframe always point at the right place.
+    actual_port: int = getattr(getattr(app, "state", None), "server_port", None) or port
 
-    # Show the clickable link with real URL
-    show_link(port)
+    logger.info(f"   Server started on port {actual_port}!")
+
+    # Poll health endpoint to confirm the server is truly reachable before
+    # showing the link and registering the iframe — avoids the race where
+    # ready_event fires but the process hasn't finished binding.
+    import urllib.request
+
+    server_ready = False
+    for _ in range(40):
+        try:
+            with urllib.request.urlopen(
+                f"http://localhost:{actual_port}/api/health", timeout = 1
+            ):
+                server_ready = True
+                break
+        except Exception:
+            time.sleep(0.5)
+
+    if not server_ready:
+        logger.error(
+            f"❌ Unsloth Studio did not become healthy on port {actual_port}. "
+            "Check for errors above."
+        )
+        return
+
+    _show_and_embed(actual_port)
+
+    # Keep kernel alive so the daemon server thread stays running.
+    # Handle KeyboardInterrupt cleanly so the user gets a readable message
+    # rather than a raw traceback when they interrupt the cell.
+    try:
+        for _ in range(10000):
+            time.sleep(300)
+            print("=", end = "", flush = True)
+    except KeyboardInterrupt:
+        logger.info("\nUnsloth Studio keepalive stopped.")
 
 
 if __name__ == "__main__":
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 8457da0b2d..fbf1c31de3 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -328,20 +328,58 @@ from starlette.requests import Request as _StarletteRequest  # noqa: E402
 _CSP_SCRIPT_NONCE_HEADER = "x-internal-script-nonce"
 
 
+# /content is Colab's working directory — more reliable than env vars which
+# aren't always set depending on Colab runtime version.
+import importlib.util as _importlib_util
+
+_IS_COLAB = os.path.isdir("/content") and (
+    bool(os.environ.get("COLAB_BACKEND_URL"))
+    or bool(os.environ.get("COLAB_JUPYTER_IP"))
+    or _importlib_util.find_spec("google.colab") is not None
+)
+
+
 def _build_csp(script_nonce: "str | None" = None) -> str:
     script_src = "script-src 'self'"
     if script_nonce:
         script_src += f" 'nonce-{script_nonce}'"
+    # In Colab the parent frame can be colab.research.google.com, a multi-level
+    # *.prod.colab.dev subdomain (e.g. foo.region.prod.colab.dev — note: CSP
+    # wildcards only match one level, so *.prod.colab.dev misses these), or a
+    # sandboxed null-origin output iframe. Use '*' so any ancestor is allowed;
+    # Colab is already a sandboxed single-user environment.
+    frame_ancestors = "*" if _IS_COLAB else "'none'"
+
+    # In Colab the frontend is served over the Colab reverse-proxy at an HTTPS
+    # *.prod.colab.dev URL. Colab's kernel communication layer and the output
+    # iframe scaffolding inject scripts from *.prod.colab.dev and
+    # *.googleusercontent.com, and make fetch/WebSocket connections to those
+    # same origins. Widen script-src and connect-src in Colab mode so those
+    # requests are not blocked. 'unsafe-inline' for scripts is still omitted;
+    # our own inline script uses a nonce.
+    if _IS_COLAB:
+        script_src += " https://*.prod.colab.dev https://*.googleusercontent.com"
+        connect_src = (
+            "'self' blob: data: "
+            "https://huggingface.co https://datasets-server.huggingface.co "
+            "https://*.prod.colab.dev wss://*.prod.colab.dev "
+            "https://*.googleusercontent.com wss://*.googleusercontent.com"
+        )
+    else:
+        connect_src = (
+            "'self' https://huggingface.co https://datasets-server.huggingface.co"
+        )
+
     return (
         "default-src 'self'; "
         "img-src 'self' data: blob: https://t0.gstatic.com "
         "https://t1.gstatic.com https://t2.gstatic.com "
         "https://t3.gstatic.com https://www.google.com; "
-        "connect-src 'self' https://huggingface.co https://datasets-server.huggingface.co; "
+        f"connect-src {connect_src}; "
         "style-src 'self' 'unsafe-inline'; "
         f"{script_src}; "
         "font-src 'self' data:; "
-        "frame-ancestors 'none'; "
+        f"frame-ancestors {frame_ancestors}; "
         "form-action 'self'; "
         "base-uri 'self'"
     )
@@ -357,7 +395,10 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         if nonce is not None:
             del response.headers[_CSP_SCRIPT_NONCE_HEADER]
         response.headers.setdefault("Content-Security-Policy", _build_csp(nonce))
-        response.headers.setdefault("X-Frame-Options", "DENY")
+        # Omit X-Frame-Options in Colab — CSP frame-ancestors handles it, and
+        # DENY would block serve_kernel_port_as_iframe regardless of CSP.
+        if not _IS_COLAB:
+            response.headers.setdefault("X-Frame-Options", "DENY")
         response.headers.setdefault("X-Content-Type-Options", "nosniff")
         response.headers.setdefault("Referrer-Policy", "no-referrer")
         response.headers.setdefault(
diff --git a/studio/backend/run.py b/studio/backend/run.py
index 5ddf404370..f401bc2ec1 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -653,7 +653,7 @@ def run_server(
     from threading import Thread, Event
     import uvicorn
 
-    from main import app, setup_frontend
+    from main import app, setup_frontend, _IS_COLAB
     from utils.paths import ensure_studio_directories
 
     # Create all standard directories on startup
@@ -737,14 +737,22 @@ def run_server(
                 ready_event.set()
 
     # server_header=False suppresses uvicorn's "Server: uvicorn"; SecurityHeadersMiddleware sets its own.
-    config = uvicorn.Config(
-        app,
+    config_kwargs = dict(
         host = host,
         port = port,
         log_level = "info",
         access_log = False,
         server_header = False,
     )
+    # Only in Colab: trust X-Forwarded-* from Colab's reverse proxy so the app
+    # sees the real https origin. forwarded_allow_ips="*" is fine inside Colab's
+    # single-user sandbox, but would be an unwanted security relaxation for a
+    # normal local/standalone Studio, so leave uvicorn's safe defaults
+    # (forwarded headers trusted from loopback only) in place there.
+    if _IS_COLAB:
+        config_kwargs["proxy_headers"] = True
+        config_kwargs["forwarded_allow_ips"] = "*"
+    config = uvicorn.Config(app, **config_kwargs)
     _server = _ReadyServer(config)
     _shutdown_event = Event()
 
@@ -766,14 +774,21 @@ def run_server(
 
     app.state.trigger_shutdown = _trigger_shutdown
 
-    # Run server in a daemon thread
+    # Run server in a daemon thread.
+    # Use an explicit new_event_loop() + run_until_complete() instead of
+    # asyncio.run() to avoid nest_asyncio's global patches to asyncio.run
+    # interfering when called from a thread while Colab/IPython already has
+    # a running loop on the main thread.
     def _run():
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
         try:
-            asyncio.run(_server.serve())
+            loop.run_until_complete(_server.serve())
         except BaseException as exc:
             startup_errors.append(exc)
             startup_failed.set()
         finally:
+            loop.close()
             if not ready_event.is_set():
                 startup_failed.set()
 

From db5a9880b007c06f0a8cd6462f7ee8a373139f30 Mon Sep 17 00:00:00 2001
From: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
Date: Fri, 29 May 2026 12:46:16 +0400
Subject: [PATCH 018/222] Studio: keep web search/code pills off on model load
 if user disabled them (#5851)

* Studio: keep web search/code pills off on model load if user disabled them

* Studio: avoid redundant localStorage reads when resolving tool pills on load
---
 .../src/features/chat/api/chat-adapter.ts       | 10 ++++------
 .../chat/hooks/use-chat-model-runtime.ts        | 15 +++++++--------
 .../features/chat/stores/chat-runtime-store.ts  | 17 +++++++++++++++++
 3 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index a74a4a2dea..666a304c3e 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -34,6 +34,7 @@ import {
 } from "../provider-capabilities";
 import {
   type PendingImageEditReference,
+  resolveToolsEnabledOnLoad,
   useChatRuntimeStore,
 } from "../stores/chat-runtime-store";
 import { useExternalProvidersStore } from "../stores/external-providers-store";
@@ -1034,8 +1035,7 @@ async function autoLoadSmallestModel(): Promise<{
               supportsPreserveThinking:
                 loadResp.supports_preserve_thinking ?? false,
               supportsTools: loadResp.supports_tools ?? false,
-              toolsEnabled: loadResp.supports_tools ?? false,
-              codeToolsEnabled: loadResp.supports_tools ?? false,
+              ...resolveToolsEnabledOnLoad(loadResp.supports_tools ?? false),
               kvCacheDtype: loadResp.cache_type_kv ?? null,
               loadedKvCacheDtype: loadResp.cache_type_kv ?? null,
               defaultChatTemplate: loadResp.chat_template ?? null,
@@ -1098,8 +1098,7 @@ async function autoLoadSmallestModel(): Promise<{
               sfLoadResp.supports_preserve_thinking ?? false,
             supportsTools: sfLoadResp.supports_tools ?? false,
             // Parity with the GGUF branch above.
-            toolsEnabled: sfLoadResp.supports_tools ?? false,
-            codeToolsEnabled: sfLoadResp.supports_tools ?? false,
+            ...resolveToolsEnabledOnLoad(sfLoadResp.supports_tools ?? false),
             defaultChatTemplate: sfLoadResp.chat_template ?? null,
             chatTemplateOverride: null,
             loadedChatTemplateOverride: null,
@@ -1197,8 +1196,7 @@ async function autoLoadSmallestModel(): Promise<{
         reasoningStyle: loadResp.reasoning_style ?? "enable_thinking",
         supportsPreserveThinking: loadResp.supports_preserve_thinking ?? false,
         supportsTools: loadResp.supports_tools ?? false,
-        toolsEnabled: loadResp.supports_tools ?? false,
-        codeToolsEnabled: loadResp.supports_tools ?? false,
+        ...resolveToolsEnabledOnLoad(loadResp.supports_tools ?? false),
         kvCacheDtype: loadResp.cache_type_kv ?? null,
         loadedKvCacheDtype: loadResp.cache_type_kv ?? null,
         defaultChatTemplate: loadResp.chat_template ?? null,
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 810a769a46..47216cf93d 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -27,6 +27,7 @@ import {
   CHAT_REASONING_ENABLED_KEY,
   loadOptionalBool,
   type ReasoningEffort,
+  resolveToolsEnabledOnLoad,
   useChatRuntimeStore,
 } from "../stores/chat-runtime-store";
 import {
@@ -698,14 +699,12 @@ export function useChatModelRuntime() {
               reasoningEffort: clampedReasoningEffort,
               supportsPreserveThinking: loadResponse.supports_preserve_thinking ?? false,
               supportsTools,
-              toolsEnabled:
-                reloadingSameModel && supportsTools
-                  ? stateBeforeUnload.toolsEnabled
-                  : supportsTools,
-              codeToolsEnabled:
-                reloadingSameModel && supportsTools
-                  ? stateBeforeUnload.codeToolsEnabled
-                  : supportsTools,
+              ...(reloadingSameModel && supportsTools
+                ? {
+                    toolsEnabled: stateBeforeUnload.toolsEnabled,
+                    codeToolsEnabled: stateBeforeUnload.codeToolsEnabled,
+                  }
+                : resolveToolsEnabledOnLoad(supportsTools)),
               kvCacheDtype: loadedKv,
               loadedKvCacheDtype: loadedKv,
               speculativeType: loadedSpec,
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 09c06f92d8..8f0767b7b8 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -184,6 +184,23 @@ export function loadOptionalBool(key: string): boolean | null {
   }
 }
 
+/**
+ * Resolve the web-search / code-execution pill state to apply when a model
+ * loads. Honors the user's persisted preference so loading a tool-capable
+ * model never silently re-enables a pill the user turned off; falls back to
+ * the model's capability only when no preference has been expressed.
+ */
+export function resolveToolsEnabledOnLoad(supportsTools: boolean): {
+  toolsEnabled: boolean;
+  codeToolsEnabled: boolean;
+} {
+  if (!supportsTools) return { toolsEnabled: false, codeToolsEnabled: false };
+  return {
+    toolsEnabled: loadOptionalBool(CHAT_TOOLS_ENABLED_KEY) ?? true,
+    codeToolsEnabled: loadOptionalBool(CHAT_CODE_TOOLS_ENABLED_KEY) ?? true,
+  };
+}
+
 function saveBool(key: string, value: boolean): void {
   if (!canUseStorage()) return;
   try {

From a3a0cb1606f1041810dba339a1e91ae68d3cb5e2 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Fri, 29 May 2026 05:09:20 -0700
Subject: [PATCH 019/222] studio/setup.sh: cope with fresh CUDA toolkits like
 13.3 (#5826)

* Studio setup.sh: cope with fresh CUDA toolkits like 13.3

CUDA 13.3 shipped today. Three loose ends in studio/setup.sh surfaced
during the llama.cpp build path:

1. setup.ps1 already aborts cleanly when the CUDA toolkit is below
   llama.cpp's minimum (12.4) via #4517, but setup.sh still hit the
   generic cmake failure described in #4437. Added a min-version check
   that downgrades to a CPU build for nvcc < 12.4 with a clear message
   pointing to the toolkit archive.
2. The first day a new CUDA toolkit ships, its host-compiler whitelist
   lags whatever gcc/clang the distro is on, so nvcc rejects the host
   compiler with a wall of "#error -- unsupported GNU version" before
   any real compile runs. NVCC_PREPEND_FLAGS now carries
   -allow-unsupported-compiler so the build moves on instead.
3. The Linux CUDA/ROCm configure failure path had no symmetry with the
   macOS Metal fallback: a single nvcc failure left BUILD_OK=false and
   no llama.cpp at all. Generalised the existing Metal -> CPU fallback
   to cover any GPU_BACKEND, so a CUDA configure or build failure now
   transparently retries with the CPU args and the user still ends up
   with a working llama-server.

Pulled the version probe out into _nvcc_meets_llama_minimum so it can
be unit-tested. Added tests/sh/test_nvcc_meets_llama_minimum.sh and two
extra cases in tests/sh/test_get_torch_index_url.sh covering the legacy
"CUDA Version: 13.3" header (driver-reported) and the future 13.7
case. Wired the new test into tests/run_all.sh and the studio-backend
CI workflow.

* tests: relax pr4562 regression to allow generic GPU fallback label

* studio tests: assert setup.sh exports NVCC_PREPEND_FLAGS=-allow-unsupported-compiler

The -allow-unsupported-compiler flag is the core of the fresh-CUDA-toolkit fix
(it lets nvcc accept a host gcc/clang newer than its release-time whitelist, so
CUDA 13.3 day-one builds do not abort on '#error -- unsupported GNU version'),
but it had no automated coverage. Add a source-pattern test asserting the flag
is present, delivered via NVCC_PREPEND_FLAGS so it also covers cmake's CUDA
compiler-id probe, and kept out of CMAKE_ARGS for bash word-splitting safety.

* studio/setup.ps1: allow unsupported host compiler for CUDA build (Windows parity)

Mirror the Linux setup.sh headline fix from this PR on Windows. A freshly
released CUDA toolkit ships with a host-compiler whitelist that lags the
installed toolchain, so nvcc can reject the host with
"#error -- unsupported Microsoft Visual Studio version!" before any real
compile runs (the MSVC analogue of the gcc wall the Linux side hit on
CUDA 13.3). Set NVCC_PREPEND_FLAGS=-allow-unsupported-compiler in the CUDA
build branch so both cmake's configure-time CUDA compiler-id probe and the
cmake --build step proceed. The flag disables the host version check only and
is a no-op when the compiler is already supported.

Set via the process environment (not the $CmakeArgs array), after the
Refresh-Environment calls that re-sanitize CUDA env vars, and appended
idempotently to any value the user already set.

Validated with PowerShell 7.6.2: full setup.ps1 AST parse is clean and the
snippet is idempotent (empty -> set, existing -> append once, no duplicate).
Needs real Windows + CUDA CI to exercise the actual nvcc/MSVC build.

Adds test_setup_ps1_exports_allow_unsupported_compiler asserting the flag is
present, env-delivered, kept out of $CmakeArgs, and scoped to the CUDA-on branch.

* studio: tighten code comments added in this PR

Shorten the verbose multi-line comments and test docstrings introduced by
this PR (setup.sh, setup.ps1, and the shell/python tests) to be succinct
while preserving the rationale. No code or test-assertion changes.
---
 .github/workflows/studio-backend-ci.yml      |   1 +
 studio/setup.ps1                             |  11 ++
 studio/setup.sh                              | 123 ++++++++++++++-----
 tests/run_all.sh                             |   1 +
 tests/sh/test_get_torch_index_url.sh         |  12 ++
 tests/sh/test_nvcc_meets_llama_minimum.sh    | 121 ++++++++++++++++++
 tests/studio/install/test_pr4562_bugfixes.py |  62 ++++++++--
 7 files changed, 292 insertions(+), 39 deletions(-)
 create mode 100755 tests/sh/test_nvcc_meets_llama_minimum.sh

diff --git a/.github/workflows/studio-backend-ci.yml b/.github/workflows/studio-backend-ci.yml
index ee5bbe8633..88c7344683 100644
--- a/.github/workflows/studio-backend-ci.yml
+++ b/.github/workflows/studio-backend-ci.yml
@@ -222,6 +222,7 @@ jobs:
           for s in \
               tests/sh/test_get_torch_index_url.sh \
               tests/sh/test_mac_intel_compat.sh \
+              tests/sh/test_nvcc_meets_llama_minimum.sh \
               tests/sh/test_tauri_install_exit_order.sh \
               tests/sh/test_torch_constraint.sh; do
               echo "::group::$s"
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 8950627ae8..afa00409fb 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -2589,6 +2589,17 @@ if (-not $NeedLlamaSourceBuild) {
         # CUDA flags -- only if GPU available, otherwise explicitly disable
         if ($HasNvidiaSmi -and $NvccPath) {
             $CmakeArgs += '-DGGML_CUDA=ON'
+            # Accept a host MSVC newer than nvcc's whitelist; a fresh toolkit
+            # (e.g. CUDA 13.3) otherwise aborts with "#error -- unsupported
+            # Microsoft Visual Studio version!". Mirrors the Linux fix. Via env
+            # (covers the configure probe + build), after Refresh-Environment, idempotent.
+            $nvccAllowFlag = '-allow-unsupported-compiler'
+            if ([string]::IsNullOrEmpty($env:NVCC_PREPEND_FLAGS)) {
+                $env:NVCC_PREPEND_FLAGS = $nvccAllowFlag
+            } elseif ($env:NVCC_PREPEND_FLAGS -notlike "*$nvccAllowFlag*") {
+                $env:NVCC_PREPEND_FLAGS = "$($env:NVCC_PREPEND_FLAGS) $nvccAllowFlag"
+            }
+            substep "NVCC_PREPEND_FLAGS = $env:NVCC_PREPEND_FLAGS"
             $CmakeArgs += "-DCUDAToolkit_ROOT=$CudaToolkitRoot"
             $CmakeArgs += "-DCUDA_TOOLKIT_ROOT_DIR=$CudaToolkitRoot"
             $CmakeArgs += "-DCMAKE_CUDA_COMPILER=$NvccPath"
diff --git a/studio/setup.sh b/studio/setup.sh
index e8fc8f6f13..f2395255c0 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -130,6 +130,30 @@ run_quiet_no_exit() {
     _run_quiet return "$@"
 }
 
+_nvcc_meets_llama_minimum() {
+    # Echo "ok|too_old|unknown" then the parsed "X.Y" version, one per line.
+    # llama.cpp needs CUDA toolkit >= 12.4 (#4437; setup.ps1 aborts via #4517).
+    _nvcc_bin=$1
+    [ -n "$_nvcc_bin" ] || { echo "unknown"; echo ""; return 0; }
+    _raw=$("$_nvcc_bin" --version 2>/dev/null \
+        | sed -n 's/.*release \([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
+        | head -1)
+    if [ -z "$_raw" ]; then
+        echo "unknown"; echo ""; return 0
+    fi
+    _maj=${_raw%%.*}
+    _min_raw=${_raw#*.}
+    _min=${_min_raw%%.*}
+    if [ "$_maj" -lt 12 ] 2>/dev/null; then
+        echo "too_old"
+    elif [ "$_maj" -eq 12 ] && [ "$_min" -lt 4 ] 2>/dev/null; then
+        echo "too_old"
+    else
+        echo "ok"
+    fi
+    echo "$_raw"
+}
+
 print_llama_error_log() {
     local log_file=$1
     [ -s "$log_file" ] || return 0
@@ -1005,32 +1029,52 @@ else
                 CPU_FALLBACK_CMAKE_ARGS="$CPU_FALLBACK_CMAKE_ARGS -DGGML_METAL=OFF"
                 _TRY_METAL_CPU_FALLBACK=true
             elif [ -n "$NVCC_PATH" ]; then
-                CMAKE_ARGS="$CMAKE_ARGS -DGGML_CUDA=ON"
+                # Returns "ok|too_old|unknown\nX.Y" on stdout.
+                _NVCC_CHECK="$(_nvcc_meets_llama_minimum "$NVCC_PATH")"
+                _NVCC_STATUS="$(printf '%s\n' "$_NVCC_CHECK" | sed -n '1p')"
+                _NVCC_VER="$(printf '%s\n' "$_NVCC_CHECK" | sed -n '2p')"
 
-                CUDA_ARCHS=""
-                if command -v nvidia-smi &>/dev/null; then
-                    _raw_caps=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
-                    while IFS= read -r _cap; do
-                        _cap=$(echo "$_cap" | tr -d '[:space:]')
-                        if [[ "$_cap" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-                            _arch="${BASH_REMATCH[1]}${BASH_REMATCH[2]}"
-                            # Append if not already present
-                            case ";$CUDA_ARCHS;" in
-                                *";$_arch;"*) ;;
-                                *) CUDA_ARCHS="${CUDA_ARCHS:+$CUDA_ARCHS;}$_arch" ;;
-                            esac
-                        fi
-                    done <<< "$_raw_caps"
-                fi
-
-                if [ -n "$CUDA_ARCHS" ]; then
-                    CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_ARCHITECTURES=${CUDA_ARCHS}"
-                    _BUILD_DESC="building (CUDA, sm_${CUDA_ARCHS//;/+sm_})"
+                if [ "$_NVCC_STATUS" = "too_old" ]; then
+                    substep "CUDA toolkit $_NVCC_VER is below llama.cpp minimum (12.4)." "$C_ERR"
+                    substep "install a newer CUDA toolkit: https://developer.nvidia.com/cuda-toolkit-archive" "$C_WARN"
+                    substep "falling back to CPU llama.cpp build for this run." "$C_WARN"
+                    NVCC_PATH=""
+                    GPU_BACKEND=""
+                    _BUILD_DESC="building (CPU, CUDA toolkit < 12.4)"
                 else
-                    _BUILD_DESC="building (CUDA)"
-                fi
+                    CMAKE_ARGS="$CMAKE_ARGS -DGGML_CUDA=ON"
 
-                CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_FLAGS=--threads=0"
+                    CUDA_ARCHS=""
+                    if command -v nvidia-smi &>/dev/null; then
+                        _raw_caps=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
+                        while IFS= read -r _cap; do
+                            _cap=$(echo "$_cap" | tr -d '[:space:]')
+                            if [[ "$_cap" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+                                _arch="${BASH_REMATCH[1]}${BASH_REMATCH[2]}"
+                                # Append if not already present
+                                case ";$CUDA_ARCHS;" in
+                                    *";$_arch;"*) ;;
+                                    *) CUDA_ARCHS="${CUDA_ARCHS:+$CUDA_ARCHS;}$_arch" ;;
+                                esac
+                            fi
+                        done <<< "$_raw_caps"
+                    fi
+
+                    if [ -n "$CUDA_ARCHS" ]; then
+                        CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_ARCHITECTURES=${CUDA_ARCHS}"
+                        _BUILD_DESC="building (CUDA, sm_${CUDA_ARCHS//;/+sm_})"
+                    else
+                        _BUILD_DESC="building (CUDA)"
+                    fi
+
+                    CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_FLAGS=--threads=0"
+
+                    # Accept a host gcc/clang newer than nvcc's whitelist; a fresh
+                    # toolkit (e.g. CUDA 13.3) otherwise aborts with "#error --
+                    # unsupported GNU version". Via env, not CMAKE_ARGS, to avoid
+                    # word-splitting.
+                    export NVCC_PREPEND_FLAGS="${NVCC_PREPEND_FLAGS:+$NVCC_PREPEND_FLAGS }-allow-unsupported-compiler"
+                fi
             elif [ "$GPU_BACKEND" = "rocm" ]; then
                 # Resolve hipcc symlinks to find the real ROCm root
                 _HIPCC_REAL="$(readlink -f "$ROCM_HIPCC" 2>/dev/null || printf '%s' "$ROCM_HIPCC")"
@@ -1100,14 +1144,29 @@ else
                 CMAKE_GENERATOR_ARGS="-G Ninja"
             fi
 
-            if ! run_quiet_no_exit "cmake llama.cpp" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CMAKE_ARGS; then
+            # GPU label for the CPU-fallback message: Metal, else GPU_BACKEND
+            # (cuda/rocm). Empty on a bare CPU build (nothing to fall back from).
+            _gpu_fallback_label() {
                 if [ "$_TRY_METAL_CPU_FALLBACK" = true ]; then
+                    echo "Metal"
+                elif [ -n "$GPU_BACKEND" ]; then
+                    printf '%s' "$GPU_BACKEND" | tr '[:lower:]' '[:upper:]'
+                fi
+            }
+
+            if ! run_quiet_no_exit "cmake llama.cpp" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CMAKE_ARGS; then
+                _FB_LABEL="$(_gpu_fallback_label)"
+                if [ -n "$_FB_LABEL" ]; then
                     _TRY_METAL_CPU_FALLBACK=false
-                    substep "Metal configure failed; retrying CPU build..." "$C_WARN"
+                    substep "$_FB_LABEL configure failed; retrying CPU build..." "$C_WARN"
                     rm -rf "$_BUILD_TMP/build"
-                    run_quiet_no_exit "cmake llama.cpp (cpu fallback)" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CPU_FALLBACK_CMAKE_ARGS || BUILD_OK=false
-                    if [ "$BUILD_OK" = true ]; then
-                        _BUILD_DESC="building (CPU fallback)"
+                    if run_quiet_no_exit "cmake llama.cpp (cpu fallback)" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CPU_FALLBACK_CMAKE_ARGS; then
+                        _BUILD_DESC="building (CPU fallback after $_FB_LABEL configure failed)"
+                        # Now configured for CPU; clear GPU_BACKEND so a later
+                        # build-step failure won't re-enter fallback on this config.
+                        GPU_BACKEND=""
+                    else
+                        BUILD_OK=false
                     fi
                 else
                     BUILD_OK=false
@@ -1117,12 +1176,14 @@ else
 
         if [ "$BUILD_OK" = true ]; then
             if ! run_quiet_no_exit "build llama-server" cmake --build "$_BUILD_TMP/build" --config Release --target llama-server -j"$NCPU"; then
-                if [ "$_TRY_METAL_CPU_FALLBACK" = true ]; then
+                _FB_LABEL="$(_gpu_fallback_label)"
+                if [ -n "$_FB_LABEL" ]; then
                     _TRY_METAL_CPU_FALLBACK=false
-                    substep "Metal build failed; retrying CPU build..." "$C_WARN"
+                    substep "$_FB_LABEL build failed; retrying CPU build..." "$C_WARN"
                     rm -rf "$_BUILD_TMP/build"
                     if run_quiet_no_exit "cmake llama.cpp (cpu fallback)" cmake $CMAKE_GENERATOR_ARGS -S "$_BUILD_TMP" -B "$_BUILD_TMP/build" $CPU_FALLBACK_CMAKE_ARGS; then
-                        _BUILD_DESC="building (CPU fallback)"
+                        _BUILD_DESC="building (CPU fallback after $_FB_LABEL build failed)"
+                        GPU_BACKEND=""
                         run_quiet_no_exit "build llama-server (cpu fallback)" cmake --build "$_BUILD_TMP/build" --config Release --target llama-server -j"$NCPU" || BUILD_OK=false
                     else
                         BUILD_OK=false
diff --git a/tests/run_all.sh b/tests/run_all.sh
index 6525263d8f..d84c930392 100755
--- a/tests/run_all.sh
+++ b/tests/run_all.sh
@@ -8,6 +8,7 @@ echo "=== Bash tests ==="
 sh "$TESTS_DIR/sh/test_get_torch_index_url.sh"
 sh "$TESTS_DIR/sh/test_mac_intel_compat.sh"
 sh "$TESTS_DIR/sh/test_torch_constraint.sh"
+sh "$TESTS_DIR/sh/test_nvcc_meets_llama_minimum.sh"
 
 echo ""
 echo "=== Python tests ==="
diff --git a/tests/sh/test_get_torch_index_url.sh b/tests/sh/test_get_torch_index_url.sh
index a9fafa5359..89ec32fba5 100755
--- a/tests/sh/test_get_torch_index_url.sh
+++ b/tests/sh/test_get_torch_index_url.sh
@@ -320,6 +320,18 @@ _result=$(run_func "$_dir")
 assert_eq "CUDA UMD Version 11.8 -> cu118" "https://download.pytorch.org/whl/cu118" "$_result"
 rm -rf "$_dir"
 
+# 32) Driver-reported "CUDA Version: 13.3" (legacy header) -> cu130.
+_dir=$(make_mock_smi "13.3")
+_result=$(run_func "$_dir")
+assert_eq "CUDA Version 13.3 -> cu130" "https://download.pytorch.org/whl/cu130" "$_result"
+rm -rf "$_dir"
+
+# 33) "CUDA Version: 13.7" -> cu130 (until a cu137 wheel index exists).
+_dir=$(make_mock_smi "13.7")
+_result=$(run_func "$_dir")
+assert_eq "CUDA Version 13.7 -> cu130" "https://download.pytorch.org/whl/cu130" "$_result"
+rm -rf "$_dir"
+
 rm -f "$_FUNC_FILE"
 rm -rf "$_FAKE_SMI_DIR"
 rm -rf "$_TOOLS_DIR"
diff --git a/tests/sh/test_nvcc_meets_llama_minimum.sh b/tests/sh/test_nvcc_meets_llama_minimum.sh
new file mode 100755
index 0000000000..f614c0403a
--- /dev/null
+++ b/tests/sh/test_nvcc_meets_llama_minimum.sh
@@ -0,0 +1,121 @@
+#!/bin/bash
+# Unit tests for _nvcc_meets_llama_minimum() from studio/setup.sh.
+# llama.cpp needs CUDA toolkit >= 12.4 (#4437); setup.ps1 aborts via #4517,
+# the Linux side was silent until this fix.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SETUP_SH="$SCRIPT_DIR/../../studio/setup.sh"
+PASS=0
+FAIL=0
+
+# Extract just the helper function. The sed range is the same pattern the
+# install.sh tests use.
+_FUNC_FILE=$(mktemp)
+sed -n '/^_nvcc_meets_llama_minimum()/,/^}/p' "$SETUP_SH" > "$_FUNC_FILE"
+
+assert_eq() {
+    _label="$1"; _expected="$2"; _actual="$3"
+    if [ "$_actual" = "$_expected" ]; then
+        echo "  PASS: $_label"
+        PASS=$((PASS + 1))
+    else
+        echo "  FAIL: $_label (expected '$_expected', got '$_actual')"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+# Fake nvcc printing "release X.Y" in the canonical nvcc -V layout (the helper
+# greps for "release X.Y", stable across CUDA 9.x-13.x).
+make_mock_nvcc() {
+    _ver=$1
+    _dir=$(mktemp -d)
+    cat > "$_dir/nvcc" <<MOCK
+#!/bin/sh
+cat <<NV
+nvcc: NVIDIA (R) Cuda compiler driver
+Copyright (c) 2005-2026 NVIDIA Corporation
+Cuda compilation tools, release $_ver, V${_ver}.0
+NV
+MOCK
+    chmod +x "$_dir/nvcc"
+    echo "$_dir/nvcc"
+}
+
+run_check() {
+    _nvcc=$1
+    bash -c ". '$_FUNC_FILE'; _nvcc_meets_llama_minimum '$_nvcc'"
+}
+
+echo "=== test_nvcc_meets_llama_minimum ==="
+
+# 1) CUDA 12.4 is the minimum supported -> ok
+_bin=$(make_mock_nvcc "12.4")
+_out=$(run_check "$_bin")
+assert_eq "12.4 status" "ok" "$(echo "$_out" | sed -n '1p')"
+assert_eq "12.4 version" "12.4" "$(echo "$_out" | sed -n '2p')"
+rm -rf "$(dirname "$_bin")"
+
+# 2) CUDA 12.3 is the highest version that should be rejected.
+_bin=$(make_mock_nvcc "12.3")
+_out=$(run_check "$_bin")
+assert_eq "12.3 status" "too_old" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 3) CUDA 12.1 (matches the original bug report in #4437).
+_bin=$(make_mock_nvcc "12.1")
+_out=$(run_check "$_bin")
+assert_eq "12.1 status" "too_old" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 4) CUDA 11.8 -> too_old (anything < 12.0 is rejected).
+_bin=$(make_mock_nvcc "11.8")
+_out=$(run_check "$_bin")
+assert_eq "11.8 status" "too_old" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 5) CUDA 12.8 -> ok (mid-range supported).
+_bin=$(make_mock_nvcc "12.8")
+_out=$(run_check "$_bin")
+assert_eq "12.8 status" "ok" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 6) CUDA 13.0 -> ok.
+_bin=$(make_mock_nvcc "13.0")
+_out=$(run_check "$_bin")
+assert_eq "13.0 status" "ok" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 7) CUDA 13.3 -> ok (the freshly shipped toolkit this fix targets).
+_bin=$(make_mock_nvcc "13.3")
+_out=$(run_check "$_bin")
+assert_eq "13.3 status" "ok" "$(echo "$_out" | sed -n '1p')"
+assert_eq "13.3 version" "13.3" "$(echo "$_out" | sed -n '2p')"
+rm -rf "$(dirname "$_bin")"
+
+# 8) Future CUDA 14.0 -> ok (no upper bound).
+_bin=$(make_mock_nvcc "14.0")
+_out=$(run_check "$_bin")
+assert_eq "14.0 status" "ok" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$(dirname "$_bin")"
+
+# 9) Empty argument -> unknown (defensive; never block the build on detection).
+_out=$(run_check "")
+assert_eq "empty path status" "unknown" "$(echo "$_out" | sed -n '1p')"
+
+# 10) Mock nvcc that prints garbage -> unknown.
+_dir=$(mktemp -d)
+cat > "$_dir/nvcc" <<'MOCK'
+#!/bin/sh
+echo "totally not nvcc output"
+MOCK
+chmod +x "$_dir/nvcc"
+_out=$(run_check "$_dir/nvcc")
+assert_eq "garbage output status" "unknown" "$(echo "$_out" | sed -n '1p')"
+rm -rf "$_dir"
+
+rm -f "$_FUNC_FILE"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] || exit 1
diff --git a/tests/studio/install/test_pr4562_bugfixes.py b/tests/studio/install/test_pr4562_bugfixes.py
index 4a309036d6..34b144a905 100644
--- a/tests/studio/install/test_pr4562_bugfixes.py
+++ b/tests/studio/install/test_pr4562_bugfixes.py
@@ -727,16 +727,13 @@ class TestSourceCodePatterns:
         assert "-DCMAKE_BUILD_WITH_INSTALL_RPATH=ON" in content
 
     def test_setup_sh_macos_metal_configure_has_cpu_fallback(self):
-        """If Metal configure or build fails, setup should retry with CPU fallback."""
+        """If Metal/CUDA/ROCm configure or build fails, setup retries a CPU
+        build. PR #5826 generalised the Metal-only wording via $_FB_LABEL; this
+        check stays label-agnostic so new GPU backends don't require edits."""
         content = SETUP_SH.read_text()
         assert "_TRY_METAL_CPU_FALLBACK=true" in content
-        assert (
-            'substep "Metal configure failed; retrying CPU build..." "$C_WARN"'
-            in content
-        )
-        assert (
-            'substep "Metal build failed; retrying CPU build..." "$C_WARN"' in content
-        )
+        assert 'configure failed; retrying CPU build..." "$C_WARN"' in content
+        assert 'build failed; retrying CPU build..." "$C_WARN"' in content
         assert 'run_quiet_no_exit "cmake llama.cpp (cpu fallback)"' in content
         assert "-DGGML_METAL=OFF" in content
         # _TRY_METAL_CPU_FALLBACK must be reset to false in both fallback branches
@@ -745,6 +742,55 @@ class TestSourceCodePatterns:
             "_TRY_METAL_CPU_FALLBACK=false should appear at least 3 times "
             "(init + configure fallback + build fallback)"
         )
+        # The fallback helper must exist and Metal must reach it via the
+        # _TRY_METAL_CPU_FALLBACK shortcut so the macOS path stays covered.
+        assert "_gpu_fallback_label()" in content
+        assert 'echo "Metal"' in content
+
+    def test_setup_sh_exports_allow_unsupported_compiler(self):
+        """Headline fix for PR #5826: a fresh CUDA toolkit's host-compiler
+        whitelist lags the distro gcc/clang, so nvcc rejects the host with
+        "#error -- unsupported GNU version". setup.sh exports
+        NVCC_PREPEND_FLAGS=-allow-unsupported-compiler (via env, not CMAKE_ARGS,
+        for word-splitting safety) so the build and compiler-id probe proceed."""
+        content = SETUP_SH.read_text()
+        assert "-allow-unsupported-compiler" in content
+        # Delivered via NVCC_PREPEND_FLAGS (covers the configure-time compiler
+        # probe too), not embedded in the word-split CMAKE_ARGS string.
+        assert "export NVCC_PREPEND_FLAGS=" in content
+        cmake_args_lines = [
+            line for line in content.splitlines() if "CMAKE_ARGS=" in line
+        ]
+        assert all(
+            "-allow-unsupported-compiler" not in line for line in cmake_args_lines
+        ), "flag must stay out of CMAKE_ARGS (bash word-splitting safety)"
+
+    def test_setup_ps1_exports_allow_unsupported_compiler(self):
+        """Windows parity for the PR #5826 fix: a fresh CUDA toolkit's whitelist
+        also lags MSVC, so nvcc can reject the host with "#error -- unsupported
+        Microsoft Visual Studio version!". setup.ps1 sets
+        NVCC_PREPEND_FLAGS=-allow-unsupported-compiler in the CUDA branch (via
+        env, out of $CmakeArgs) so the configure probe + build proceed."""
+        content = SETUP_PS1.read_text()
+        assert "-allow-unsupported-compiler" in content
+        # Delivered via the process environment, not the $CmakeArgs array, so it
+        # reaches both the configure-time compiler probe and `cmake --build`.
+        assert "$env:NVCC_PREPEND_FLAGS" in content
+        cmake_args_lines = [
+            line for line in content.splitlines() if "$CmakeArgs +=" in line
+        ]
+        assert all(
+            "-allow-unsupported-compiler" not in line for line in cmake_args_lines
+        ), "flag must not be pushed into the $CmakeArgs array"
+        # Must be scoped to the CUDA branch (guarded by the GPU/nvcc check),
+        # not set unconditionally for CPU-only builds.
+        flag_idx = content.index("-allow-unsupported-compiler")
+        cuda_guard_idx = content.index("if ($HasNvidiaSmi -and $NvccPath)")
+        cuda_disable_idx = content.index("'-DGGML_CUDA=OFF'")
+        assert cuda_guard_idx < flag_idx < cuda_disable_idx, (
+            "NVCC_PREPEND_FLAGS must be set inside the CUDA-on branch, "
+            "before the GGML_CUDA=OFF (CPU) branch"
+        )
 
     def test_macos_arm64_cpu_fallback_args_exclude_rpath(self):
         """CPU fallback args must NOT contain Metal-only RPATH flags at runtime."""

From b6d5636cc06d1f34716f8a0ccca1ea9b1f95792d Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Sat, 30 May 2026 00:29:56 -0500
Subject: [PATCH 020/222] fix/strix halo and windows AMD ROCm support (#5301)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(studio): set HIP_VISIBLE_DEVICES in apply_gpu_ids for ROCm training workers

Training workers are spawned via multiprocessing spawn before detect_hardware()
runs, so IS_ROCM is still False. If the user never set HIP_VISIBLE_DEVICES in
their shell, _inherits_rocm_visibility is also False, leaving the worker with
only CUDA_VISIBLE_DEVICES set. On ROCm hosts the HIP runtime honors
HIP_VISIBLE_DEVICES over CUDA_VISIBLE_DEVICES, so the worker saw the full
device list and torch raised "no usable HIP accelerator" on some setups.

Fall back to probing torch.version.hip (a build-time attribute, safe to read
before GPU init) to detect ROCm when neither IS_ROCM nor inherited env vars
are available. Mirrors the existing fix in llama_cpp.py for llama-server
subprocess GPU pinning.

Fixes https://github.com/unslothai/unsloth/issues/5180

* test: tighten apply_gpu_ids ROCm fallback assertions

Replace loose OR chain with exact string matches, split into three
focused tests, and add a guard check for the try/except wrapper.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: detect ROCm unified memory (Strix Halo / AMD iGPU) via torch fallback

amd-smi on iGPUs with shared/unified memory (e.g. Radeon 8060S on Strix
Halo) reports only the dedicated VRAM slice (~512 MB) in its metric output,
so get_visible_gpu_utilization() was returning usable_gb ≈ 0.35 GB instead
of the full GTT pool (~128 GB).  torch.cuda.mem_get_info() already surfaces
the correct unified-pool size.

Add _reconcile_rocm_unified_memory(): after amd-smi returns a valid result
on a ROCm device, cross-check each device's vram_total_gb against
torch.cuda.mem_get_info().  When torch reports a larger total, replace the
amd-smi VRAM fields in-place.  No-op for discrete AMD GPUs where the two
sources agree.

Fixes: "Falling back to all visible GPUs -- model may not fit" on AMD iGPU
machines even when 100+ GB of unified memory is available.

* Apply unified-memory reconciliation in get_gpu_utilization too

The visible-GPU path was already corrected for AMD iGPUs with unified memory
(Strix Halo / Radeon 8060S), but get_gpu_utilization was still returning the
raw 512 MB amd-smi VRAM slice. Studio's /api/train/hardware endpoint and the
live GPU monitor read from this primary path, so users continued seeing the
wrong total even after auto_select_gpu_ids picked the right device.

Refactor to share the per-device correction:
  * _apply_unified_memory_correction(metrics, torch_info) -- the actual
    replacement logic, in-place on a single metrics dict.
  * _reconcile_rocm_unified_memory(...)                   -- multi-device,
    iterates utilization["devices"] (visible-GPU path).
  * _reconcile_primary_rocm_unified_memory(...)           -- single flat
    metrics dict (primary-GPU path), uses parent_visible_spec to pick the
    primary index, falls back to ordinal 0 when no visibility env is set.

get_gpu_utilization now calls the primary reconciler under IS_ROCM, so both
endpoints surface the real unified-memory pool on iGPUs while leaving
discrete AMD GPUs untouched (torch_total <= smi_total -> no replace).

* Use 'is not None' and log debug on torch.version.hip probe failures

Two small follow-ups to the apply_gpu_ids ROCm fallback:

1. Match detect_hardware()'s 'getattr(torch.version, "hip", None) is not None'
   form so the entire codebase has one canonical 'this torch was built with
   HIP' check. On every shipping torch wheel hip is either None or a non-empty
   version string, so the new form agrees with the old bool() form on every
   real install.

2. Log the probe failure at debug level instead of swallowing it silently.
   The broad 'except Exception' is intentional (we never want apply_gpu_ids
   to crash a worker over a probe), but the silent pass made it impossible
   to tell whether the fallback was firing or being skipped.

* fix(studio): honour HIP_VISIBLE_DEVICES in _get_parent_visible_gpu_spec before IS_ROCM is set

When a user has HIP_VISIBLE_DEVICES set in their shell (e.g. "1" to select
GPU 1) but detect_hardware() has not yet run in the Studio parent process,
IS_ROCM is still False.  _get_parent_visible_gpu_spec() was gated on IS_ROCM
so it fell through to CUDA_VISIBLE_DEVICES (unset), saw all physical GPUs,
and auto-selected index 0.  apply_gpu_ids then overwrote HIP_VISIBLE_DEVICES
with "0", making the intended GPU invisible to ROCm torch in the worker,
which triggered the "no usable HIP accelerator" error (issue #5180).

Apply the same _inherits_rocm_visibility pattern already used in
apply_gpu_ids: check for HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES in the
environment regardless of IS_ROCM so the correct GPU index is preserved.

* fix(install): harden AMD ROCm GPU detection for multi-GPU and env-filtered setups

The previous rocminfo awk pattern could miss discrete GPUs on machines
where HIP_VISIBLE_DEVICES/ROCR_VISIBLE_DEVICES is used to mask an
integrated GPU — the env vars filter rocminfo output but may not
propagate into the install script subprocess, causing detection to
fail entirely.

Two changes:
- Tighten rocminfo pattern from /gfx[0-9]/ && !/gfx000/ to
  /gfx[1-9][0-9]/ — simpler and correctly excludes the CPU agent
  (gfx000) without a negative lookahead
- Add sysfs KFD topology fallback: reads
  /sys/class/kfd/kfd/topology/nodes/*/gpu_id which is a kernel-level
  view unaffected by HIP_VISIBLE_DEVICES or ROCR_VISIBLE_DEVICES

Fixes detection failure reported in Discord by Chains (gfx1201 + iGPU
machine where env var exclusion of the iGPU caused rocminfo to return
no usable device).

* Fix KFD sysfs awk fallback to read properties file

The fallback added by this PR reads /sys/class/kfd/kfd/topology/nodes/*/gpu_id
files but matches the literal token 'gpu_id' against their content. Those
files contain only a single decimal value (e.g. '0' for CPU agents, '50432'
for GPU agents), so the regex never matches and 'found' stays 0, making the
fallback a no-op on every host. The properties file in the same directory
contains key/value lines like 'gpu_id 50432' which is what the existing awk
pattern expects.

Reproduced with a synthetic sysfs layout: against gpu_id files awk exits 1;
against properties files awk exits 0 when any node reports gpu_id > 0.

* fix(setup.ps1): detect AMD ROCm GPU on Windows, bring to parity with setup.sh

setup.ps1 only checked nvidia-smi and fell straight to "gpu: none" on AMD
machines. setup.sh already probed rocminfo/amd-smi/hipconfig/hipinfo.

Add three-tier detection mirroring install_llama_prebuilt.py's detect_host():
1. hipinfo: gcnArchName in output confirms a real HIP GPU (not just SDK)
2. amd-smi list: "GPU: <digit>" data rows as fallback
3. WMI Win32_VideoController: last resort -- detects AMD GPU even without
   HIP SDK, then guides user to install it rather than silently going CPU

Also corrects the "none" message to mention AMD ROCm alongside NVIDIA so
users with AMD hardware understand the requirement.

Fixes: rohit-style install where Strix Halo (Radeon 8060S) showed
"gpu: none" even with the HIP SDK present.

* fix(install.ps1): detect AMD ROCm GPU on Windows, bring to parity with setup.ps1

install.ps1 had the same nvidia-smi-only GPU detection as setup.ps1 before
the setup.ps1 fix. Applies the same three-tier AMD detection:
1. hipinfo: gcnArchName confirms real HIP GPU
2. amd-smi list: GPU data rows as fallback
3. WMI Win32_VideoController: detects AMD GPU without HIP SDK and guides
   user to install it

Fixes: install.ps1 showing "gpu: none" while setup.ps1 correctly showed
"AMD GPU detected" on the same machine (reported by rohit, RX 7600 XT).

* fix(install.ps1): suppress 'No NVIDIA GPU detected' when AMD GPU is present

* feat: add Windows AMD ROCm PyTorch wheel installation

install_python_stack.py:
- Add _ROCM_WINDOWS_WHEEL_BASE and _ROCM_WINDOWS_RELEASES constants
  pointing to AMD repo.radeon.com (ROCm 7.2 -> torch 2.9.1+rocm7.2.1)
- Extend _ensure_rocm_torch() with a Windows branch: detects ROCm via
  _has_rocm_gpu() / _detect_rocm_version(), requires Python 3.12 (cp312
  is the only ABI AMD publishes for Windows), installs the direct wheel
  URL from repo.radeon.com

install.ps1:
- Capture ROCmVersion during AMD detection via hipconfig --version /
  amd-smi version (needed for wheel URL selection)
- After Get-TorchIndexUrl, add an AMD wheel override block: when HasROCm
  and Python 3.12 detected, set ROCmTorchWheelUrl to AMD wheel URL
- Expand torch install branch to handle ROCmTorchWheelUrl with
  uv pip install --force-reinstall --no-cache-dir

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: also install torchvision and torchaudio from AMD Windows repo

AMD publishes matching torchvision-0.24.1+rocm7.2.1 and
torchaudio-2.9.1+rocm7.2.1 cp312 wheels at the same repo.radeon.com
release folder. Install all three in both install.ps1 and
install_python_stack.py Windows ROCm path.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* feat: add ROCm 7.1.1 Windows wheel mapping

AMD uses a different version string for 7.1.1 wheels:
2.9.0+rocmsdk20251116 (date-tagged) instead of +rocm7.1.1.
Adds the 7.1.1 release folder to both install.ps1 and
install_python_stack.py so users with ROCm 7.1 get ROCm
torch instead of falling back to CPU.

* fix: install rocm_sdk_core and rocm_sdk_libraries_custom alongside torch

The AMD Windows torch wheels declare rocm[libraries]==<ver> as a hard
dependency. Without installing rocm_sdk_core and rocm_sdk_libraries_custom
from the same AMD release folder, uv cannot resolve the dependency and
fails with 'No solution found'. Include all 5 wheels in one install call.

* fix: expand ROCm wheel array to scalars for Invoke-InstallCommand

@array splatting inside a scriptblock only works when the native command
is prefixed with '&'. Invoke-InstallCommand uses '& $Command' to run the
block, so @ROCmAllWheelUrls was not being expanded. Extract to scalar
variables $rw0-$rw4 which are captured correctly by the closure.

* fix: use --no-deps for AMD Windows torch wheel install

uv's resolver looks up rocm[libraries]==0.1.dev0 on PyPI during
dependency resolution before downloading any wheels, and fails because
the package doesn't exist on PyPI. --no-deps skips resolution entirely
and installs all 5 AMD wheels directly. The GPU runtime dependency is
satisfied by the HIP SDK, not a Python package.

* fix: setup.ps1 and install_python_stack.py now install ROCm torch on Windows

setup.ps1 was always setting CuTag='cpu' for non-NVIDIA hosts and installing
cpu-only PyTorch, overwriting the ROCm torch installed by install.ps1.
Adds the same AMD wheel selection logic (ROCm version detection, Python 3.12
check, 5-wheel install with --no-deps) to setup.ps1's torch install block.

install_python_stack.py: remove IS_WINDOWS guard from _ensure_rocm_torch()
call site so the Windows path in _ensure_rocm_torch() is reachable during
'unsloth studio update' as well.

* fix: suppress manual-install warning when ROCm torch already present; fix progress counter

- Gate the 'must be installed manually' warning on torch.version.hip being empty
  so it doesn't fire when our ROCm torch install succeeded
- Update _TOTAL counter to include the 3 ROCm steps on Windows now that
  _ensure_rocm_torch() is called there (fixes 10/9 display)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* feat: add rocm step display in setup.ps1; fix warning and progress counter

- Add 'rocm' step after 'cuda' in setup.ps1 showing ROCm version or HIP SDK missing
- Move ROCm version detection up to GPU detection block so it's available early
- Suppress 'must be installed manually' warning when torch.version.hip is set
- Fix _TOTAL counter to include ROCm steps on Windows (fixes 10/9 display)

* fix: detect AMD SDK ROCm torch via __version__ when torch.version.hip is unset

AMD's repo.radeon.com wheels (e.g. 2.9.0+rocmsdk20251116) do not set
torch.version.hip, leaving it None. All three probes that relied solely on
torch.version.hip now also check for 'rocm' in torch.__version__.lower():

- hardware.py detect_hardware(): IS_ROCM was never set, causing the studio
  to report 'Hardware detected: CPU' even after AMD wheels were installed
  and HIP DLLs were on PATH.
- install_python_stack.py _ensure_rocm_torch(): skip-if-already-installed
  probe would always reinstall on subsequent runs.
- install_python_stack.py Windows AMD warning: suppression check always
  failed, so the 'must be installed manually' note kept appearing after
  a successful AMD wheel install.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* perf: drop --no-cache-dir from AMD ROCm torch wheel installs

uv caches downloaded wheels by default; passing --no-cache-dir forced a
full redownload of the ~2 GB torch wheel on every install run. CUDA installs
never had this flag -- AMD was the only path affected.

* fix: use install-state flag instead of subprocess probe for AMD Windows warning

Replace the subprocess torch probe in the post-install warning block with a
module-level _rocm_windows_torch_installed flag set by _ensure_rocm_torch().
Subprocess re-import of torch is unnecessary and fragile -- the install
function already knows whether it succeeded.

* fix: hoist global declaration to top of _ensure_rocm_torch

Python requires the global statement to appear before any assignment
to the variable within a function. Moving it to the function top fixes
the SyntaxError on line 354.

* fix: pass AMD torch install status via env var to suppress false warning

setup.ps1 now sets UNSLOTH_ROCM_TORCH_INSTALLED=1 after a successful AMD
wheel install. install_python_stack.py reads this at the top of
_ensure_rocm_torch() to skip both the subprocess probe and the warning --
no re-import of torch needed, and the warning message now correctly says
'could not be auto-installed' rather than 'must be installed manually'.

* fix: register ROCm DLL directory before torch import on Windows

Python 3.8+ ignores PATH for extension DLL loading on Windows; amdhip64.dll
and other HIP runtime DLLs must be registered via os.add_dll_directory().
Without this, torch.cuda.is_available() always returns False on AMD ROCm
Windows even when HIP_PATH is correctly set in system environment variables.

Reads HIP_PATH / ROCM_PATH env vars first, then falls back to scanning
common ROCm install roots (C:\Program Files\AMD\ROCm, F:\ROCm, C:\ROCm).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: remove hardcoded non-standard ROCm paths from DLL directory scan

Only use HIP_PATH/ROCM_PATH (set by AMD installer) and the standard
C:\Program Files\AMD\ROCm\<version>\bin location. Custom drive paths
like F:\ROCm are user-specific and should not be hardcoded.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: prevent torchao overrides step from overwriting AMD ROCm torch

torchao==0.14.0 in overrides.txt declares torch as a dependency. Without
--no-deps, uv resolves torch from PyPI and installs 2.11.0+cpu on top of
the AMD ROCm wheels (2.9.0+rocmsdk20251116). This was the root cause of
'Hardware detected: CPU' -- the AMD wheels were installed but then
immediately overwritten by the overrides step.

When _rocm_windows_torch_installed is True, add --no-deps to the overrides
pip_install call so torchao is installed without pulling in CPU torch.

* fix: add rocm_sdk namespace tarball to Windows ROCm wheel installs

torch/_rocm_init.py calls `import rocm_sdk` at startup, which requires
the rocm namespace tarball (rocm-*.tar.gz) in addition to the SDK wheel
packages. This tarball was missing from both install.ps1 and setup.ps1,
causing ModuleNotFoundError on first torch import.

- Add rocm-0.1.dev0.tar.gz to ROCm 7.1.1 install (provides rocm_sdk namespace)
- Add rocm-7.2.1.tar.gz + rocm_sdk_devel to ROCm 7.2.1 install
- Install tarball in a dedicated step before main SDK/torch wheels
- Switch to @array splatting in install.ps1 scriptblock for dynamic wheel count
- Remove --no-cache-dir from Python-side ROCm wheel install (prevents ~2GB redownload)

* feat: enable ROCm 7.2 torch install + warn on gfx1151 with ROCm < 7.2

Chigoma333 (AMD Radeon 8060S / gfx1151, Strix Halo) confirmed that ROCm
7.1 segfaults when tensors are moved to GPU, but ROCm 7.2 + torch
2.11.0+rocm7.2 works fully including training.

Changes:
- Uncomment (7,2): "rocm7.2" in _ROCM_TORCH_INDEX (was blocked by <2.11.0)
- Add _ROCM_TORCH_PKG_SPECS dict with per-tag version bounds:
  rocm7.2 → torch>=2.11.0,<2.12.0; all older tags → <2.11.0
- Add _detect_amd_gfx_codes() helper that parses rocminfo output
- Warn on gfx1151/gfx1150 (Strix Halo) when ROCm < 7.2 is installed,
  pointing users at the known segfault and recommending upgrade
- install.sh get_torch_index_url(): enable rocm7.2 case (previously capped
  to rocm7.1), cap unknown future tags to rocm7.2
- install.sh: override TORCH_CONSTRAINT to >=2.11.0,<2.12.0 when rocm7.2
  index is selected, so pip can actually resolve torch 2.11.0

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: prefer Python 3.12 for AMD ROCm users when 3.13 is also installed

After GPU detection, if ROCm HIP SDK is found and the selected Python
is not 3.12, run a second pass to locate a 3.12 install via py.exe and
PATH (catches uv-managed installs). Switch $DetectedPython to 3.12 so
the venv is created with a compatible interpreter for the cp312-only AMD
Windows torch wheels.

NVIDIA and Intel GPU paths are unaffected -- the re-detection block only
runs when $HasROCm is true.

Fixes: #5301

* fix: also check uv-managed Python 3.12 for AMD ROCm #5301

* fix: hide amd-smi console popups on Windows, guard torch.distributed.is_initialized for ROCm #5301

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: suppress remaining console popups on Windows, patch torch.distributed.is_initialized for ROCm #5301

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: stub all missing torch.distributed attrs for ROCm Windows wheel #5301

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: inject torch.distributed stub when C backend missing in ROCm Windows wheel #5301

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(rocm/windows): pre-stub torch._C._distributed_c10d + raise amd-smi timeout

Two fixes for Windows ROCm regressions reported by electroglyph on #5301:

1. worker.py — torch.distributed stub now fires unconditionally on Windows
   The previous stub only injected sys.modules in the except branch, meaning
   it was silently skipped when `import torch.distributed` happened to succeed
   (the C backend is lazily resolved).  The crash then hit later when
   transformers/trl triggered the lazy load.  Fix: on win32 we pre-populate
   sys.modules['torch._C._distributed_c10d'] AND set the attribute on the
   torch._C extension module *before* attempting the import, covering both
   the early-ImportError and lazy-load failure modes.

2. amd.py — increase amd-smi timeout from 5 s to 30 s on Windows (10 s Linux)
   amd-smi on Windows must cold-init the ROCm runtime on first invocation;
   5 s was consistently too short, producing repeated 'Command timed out'
   warnings in the server log.  30 s gives enough headroom without blocking
   indefinitely on broken installs.

3. install.ps1 — widen Python 3.12 enforcement to ROCmGpuLabel (WMI-only path)
   Users whose HIP SDK is not on PATH were detected via WMI but not switched
   to Python 3.12 before the install started, causing a second pass.  Guard
   now fires on (HasROCm -or ROCmGpuLabel).

* fix(rocm): guard c10d stub, fix TorchIndexFamily for 7.1, clean dead code + comments

- worker.py: wrap c10d stub injection in `if _c10d_key not in sys.modules` so
  Windows NVIDIA users with a real torch.distributed are never affected
- install.ps1: fix Get-TauriTorchIndexFamily receiving hardcoded "rocm7.2"
  even when ROCm 7.1 wheels are installed; now branches on $ROCmVersion
- main.py: remove dead `import ctypes as _ctypes` (ctypes is never called)
- hardware.py, install_python_stack.py, worker.py, install.ps1: shorten
  verbose multi-line comment blocks throughout
- tests: update 4 stale assertions that expected rocm7.2 to be absent/capped

* fix(tests): match windows AMD warning assertion to actual source string

* chore: trim verbose comment blocks across all ROCm-related files

* fix: guard reconcile call against None numeric_ids; add torchvision lower bounds

* fix(install.ps1): recreate venv with Python 3.12 after ROCm switch

Venv was created with 3.13 before GPU detection ran; switching
$DetectedPython to 3.12 had no effect since $VenvPython still
pointed to the 3.13 interpreter inside the already-created venv.

* ux: detect AMD GPU before Python selection to avoid double venv creation

- Early hipinfo + WMI probe runs before Find-CompatiblePython so Python
  3.12 is selected upfront when AMD is detected; venv is now created
  exactly once instead of 3.13 then immediately 3.12.
- Post-venv recreation block replaced with a simple warning for the rare
  case where AMD was missed by the early probe.
- setup.ps1: show venv's actual Python version (e.g. 3.12) instead of
  the system Python found by the pre-activation search (was showing 3.13).

* fix(rocm/win): auto-stub all _distributed_c10d symbols via PEP-562 __getattr__

The bare ModuleType stub caused ImportError when torch._dynamo was imported
(triggered by trainer.py accessing torch._dynamo.config at load time).
torch._dynamo pulls in torch.distributed.fsdp._flat_param which does:
  from torch._C._distributed_c10d import FakeProcessGroup
and potentially other symbols. Adding module __getattr__ auto-creates a
stub class for any missing symbol so all such imports succeed without
enumerating every individual symbol. Applied to both the primary stub
and the fallback stub in the except branch.

* chore: trim c10d stub comment

* fix(rocm/win): auto-stub missing torch.distributed attrs (Store, ProcessGroup, …)

* fix(rocm/win): pre-stub fsdp submodules in sys.modules; fix __getattr__ subpackage clash

* feat(rocm/win): arch-aware wheel selector always picks newest ROCm release

Replace HIP-SDK-version-gated wheel selection with GPU arch-based logic.
Select-ROCmWheelRelease (PS) and _select_windows_rocm_release (Python) map
gcnArchName → minimum ROCm version, then pick the newest available release
that satisfies it (currently always rocm-rel-7.2.1 for any supported GPU).
Wheels bundle their own ROCm runtime so the installed HIP SDK 7.1 does not
prevent using 7.2.1 wheels on gfx1200 (RX 9060 XT) and similar RDNA 4 GPUs.

Also installs the bitsandbytes Windows ROCm continuous-release wheel and sets
BNB_ROCM_VERSION=72 in worker.py before ML imports so bnb loads the
libbitsandbytes_rocm72.dll that ships in that wheel.

* fix(rocm/win): stub class metaclass for ProcessGroup.BackendType; amd-smi circuit breaker

torchao.float8.inference accesses ProcessGroup.BackendType as a class-level
attribute.  Plain type() stubs have no __getattr__ on the metaclass so this
raises AttributeError.  Introduce _StubClassMeta whose __getattr__ returns
child stub classes, fixing the torchao import chain.

Add an amd-smi circuit breaker in amd.py: after 3 consecutive failures the
module stops spawning the process, eliminating the repeated Windows UAC /
DiskPart elevation prompts caused by polling a non-functional amd-smi.

Also guard BNB_ROCM_VERSION=72 behind a DLL existence check so bitsandbytes
fails with its own detection message rather than a harder "DLL not found" when
the Windows ROCm bnb wheel is not yet installed.

* fix: stub __members__ so torchao float8 enum check doesn't crash on ROCm Windows

torchao.float8.inference accesses ProcessGroup.BackendType.__members__
expecting a Python Enum registry dict. _StubClassMeta.__getattr__ was
blocking all dunder attributes, causing AttributeError. Return {} for
__members__ specifically so the isinstance/iteration checks pass cleanly.

* fix: stub distributed tensor/functional_collectives to prevent missing C++ op crash on ROCm Windows

torch._dynamo.trace_rules eagerly loads torch.distributed.tensor at import
time, which pulls in _functional_collectives.py. That file registers Meta
kernels for _c10d_functional C++ ops, but those ops are only registered
by torch._C._distributed_c10d — a C extension absent from ROCm Windows
wheels. Pre-stubbing the affected modules in sys.modules prevents the real
import chain from running and avoids the "operator does not exist" crash.

* fix: give mod stubs __path__ and pre-stub _tensor to fix 'not a package' import error

_make_mod_stub now sets __path__=[] so Python treats stub modules as
packages. Without it, any import of a submodule raises "is not a package".
Also pre-stub torch.distributed._tensor and its submodules so that
_tensor/__init__.py (which re-exports from torch.distributed.tensor) never
runs and torchao's `from torch.distributed._tensor import DTensor` gets a
harmless stub instead of crashing.

* fix: stub torch.ops._c10d_functional namespace with hashable op sentinels

torchao.dtypes.nf4tensor uses _c10d_functional ops as dict keys at import
time (all_gather_into_tensor.default, wait_tensor.default) and
torch.ops.c10d.scatter_.default. None of these ops are registered on ROCm
Windows because torch._C._distributed_c10d (the C extension) doesn't ship.
Replace the whole _c10d_functional namespace with a custom stub whose ops
return hashable .default objects, so dict-key construction doesn't crash.
Also inject a scatter_ stub into torch.ops.c10d if it's missing.

* fix: stub entire torchao package on ROCm Windows instead of individual ops

torchao is not supported on ROCm Windows and its import chain transitively
requires torch._C._distributed_c10d (absent from the ROCm Windows wheel).
Rather than stub each missing op one by one, stub the whole torchao package
upfront. Unsloth uses bitsandbytes for quantization, not torchao, so this
has no functional impact. transformers gracefully handles an importable-but-
empty torchao by disabling TorchAoHfQuantizer.

* fix: set __spec__ on mod stubs so importlib.util.find_spec doesn't raise

Manually-injected sys.modules entries have __spec__=None by default.
importlib.util.find_spec() raises ValueError when it finds a module in
sys.modules with __spec__=None (transformers.utils.import_utils hits this
when checking if torchao is available). Give every stub a minimal
ModuleSpec(name, loader=None, is_package=True) to satisfy find_spec.

* fix: add meta path finder to auto-stub subpackages of stub modules

`import torchao.prototype` goes through the import machinery, not
__getattr__, so an empty __path__ means ModuleNotFoundError. Rather than
list every submodule explicitly, register a MetaPathFinder that intercepts
any import whose parent is one of our stubs (detected by loader=None in the
parent's ModuleSpec). Real installed packages always have a SourceFileLoader
so they are never intercepted. Also register child stubs in sys.modules
from __getattr__ as a belt-and-suspenders measure.

* fix: use _unsloth_stub sentinel instead of loader=None for stub detection

The import machinery overwrites module.__spec__ with the spec returned by
find_spec (which has loader=_StubSubpackageLoader, not None), so the
loader=None check broke for second-level subpackages. Switch to a custom
_unsloth_stub object identity sentinel set directly on each stub module --
it survives __spec__ being replaced and correctly identifies stubs at any
depth (torchao.prototype.safetensors, etc.).

* refactor(rocm/win): switch to repo.amd.com arch-aware index, remove stubs

AMD recommends repo.amd.com/rocm/whl/{arch}/ as the Windows ROCm wheel
source. These wheels bundle their own ROCm runtime, support all Python
versions (not just cp312), and include the full torch._C extension set
(including _distributed_c10d) that the old repo.radeon.com wheel omitted.

Changes:
- install.ps1: remove Select-ROCmWheelRelease + hardcoded cp312 wheel
  URLs; remove Python 3.12 forced-preference logic; install via
  --index-url repo.amd.com/rocm/whl/{arch-family}/
- studio/setup.ps1: same -- remove Select-ROCmWheelRelease, switch to
  repo.amd.com arch-aware index URL
- studio/install_python_stack.py: replace _ROCM_WINDOWS_RELEASES /
  _select_windows_rocm_release with _windows_rocm_index_url() using the
  _GFX_TO_AMD_INDEX_ARCH map; drop Python 3.12 restriction
- studio/backend/core/training/worker.py: remove all stub machinery
  (_make_mod_stub, _StubSubpackageFinder, _StubSubpackageLoader,
  _StubClassMeta, torchao/fsdp/dtensor stubs, _c10d_functional ops
  stubs, BNB DLL detection) -- no longer needed with new wheel source

* fix(rocm/win): restore _distributed_c10d + torchao stubs; fix BNB install

repo.amd.com torch wheels also omit torch._C._distributed_c10d on Windows
(RCCL is not shipped on Windows). torch/distributed/__init__.py imports
from it unconditionally at module level, so the stub must land in
sys.modules before any torch.distributed import.

torchao (pulled in by transformers.quantizers) walks
torchao.float8.distributed_utils -> torch.distributed._functional_collectives
-> distributed_c10d at import time. Stubbing torchao up-front short-circuits
that chain.

worker.py:
- Restore _make_mod_stub / _StubSubpackageFinder / _StubSubpackageLoader
- Restore _StubClassMeta for ProcessGroup.BackendType attribute access
- Restore _distributed_c10d stub with __getattr__ (Windows only)
- Restore torchao stubs (5 modules, Windows only)

install_python_stack.py:
- BNB AMD wheel install was inside the early-return branch that fires when
  torch is already a ROCm build (installed by install.ps1). Move BNB install
  outside that branch so it always runs on Windows ROCm — the PyPI
  bitsandbytes has only CUDA DLLs and fails to load on ROCm.

* worker: remove _distributed_c10d stub; stub only torchao

The installed torch/distributed/__init__.py from repo.amd.com
(torch==2.10.0+rocm7.12.0) is now properly guarded with
`if is_available():`, so `import torch.distributed` alone is safe.

The crash only comes via torchao's import chain:
  torchao.float8.distributed_utils
    → torch.distributed._functional_collectives (unguarded import)
    → torch.distributed.distributed_c10d
    → torch._C._distributed_c10d  ← absent on Windows ROCm

Stubbing torchao short-circuits the chain entirely. No need to stub
_distributed_c10d. Remove _StubClassMeta and the _c10d stub block;
keep only _make_mod_stub + _StubSubpackageFinder + torchao seeds.

* fix: BNB AMD wheel skipped + torch.compile segfault on Windows ROCm

install_python_stack.py: the UNSLOTH_ROCM_TORCH_INSTALLED=1 early-return
path (set by setup.ps1 when it installed torch itself) returned before
ever reaching the AMD BNB prerelease wheel install.  The PyPI
bitsandbytes==0.49.x ships only CUDA DLLs, so loading it on ROCm fails
with "libbitsandbytes_rocm72.dll not found".  Now installs the AMD
Windows BNB wheel before returning on that path too.

worker.py: torch._grouped_mm crashes on gfx1200 (null HIP kernel pointer,
0xC0000005) when torch.compile's JitDecomp system dispatches it during
the first forward pass.  Detect Windows ROCm via torch.version.hip
(already in sys.modules from section 1e) and set TORCHDYNAMO_DISABLE=1
to bypass the broken kernel dispatch.

* fix: BNB AMD wheel install fails uv wheel filename check

The bitsandbytes continuous-release wheel is intentionally mismatched:
filename encodes 1.33.7.preview (= 1.33.7rc0 in PEP 440) but wheel
metadata reports 0.50.0.dev0.  uv rejects this by default.

Introduce _install_bnb_windows_rocm() helper that sets
UV_SKIP_WHEEL_FILENAME_CHECK=1 only for this specific install, then
restores the previous env value.  Both BNB install call sites (the
UNSLOTH_ROCM_TORCH_INSTALLED early-return path and the normal Windows
ROCm path) now use this helper.

* worker: patch _grouped_mm CUDA dispatch on Windows ROCm (gfx1200 null kernel)

TORCHDYNAMO_DISABLE=1 stopped the compiler frontend but not the autograd
JitDecomp system, which also dispatches _grouped_mm and hits the same
null HIP kernel crash (0xC0000005).

Verified that torch.library.Library("aten","IMPL").impl("_grouped_mm", fn,
"CUDA") successfully overrides the broken HIP kernel with a Python mm
fallback on torch==2.10.0+rocm7.12.0.

Schema: _grouped_mm(Tensor self, Tensor mat2, Tensor? offs=None,
                    Tensor? bias=None, ScalarType? out_dtype=None) -> Tensor

The fallback handles both the simple case (offs=None → torch.mm) and the
grouped case (offs provided → split self by offsets, multiply each group
against the corresponding slice of mat2, then cat results).

Keep _WINDOWS_ROCM_GROUPED_MM_LIB alive at function scope to prevent the
C++ dispatch registration from being freed by GC.

* worker: fix torchao stub — return stub classes not modules for isinstance()

peft/tuners/lora/torchao.py does:
  from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
  isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))

The stub __getattr__ was returning stub modules, which isinstance() rejects
with "arg 2 must be a type, a tuple of types, or a union".

Add _StubTypeMeta metaclass whose __instancecheck__ always returns False,
and _make_stub_type() to create stub classes via it. Change _make_mod_stub
__getattr__ to return stub classes instead of stub modules for leaf
attribute access, so isinstance() gets a valid type and returns False.

_StubSubpackageFinder still handles import-style subpackage creation
(those still need module objects in sys.modules); __getattr__ only fires
for from-import or direct attribute access, which are the isinstance paths.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* tests: add coverage for Windows ROCm install paths and worker patches

Add conftest.py to fix pre-existing sys.path issue that prevented
test_rocm_support.py from running at all (install_python_stack.py
imports from backend.utils.wheel_utils which needs studio/ on sys.path).

New test classes cover everything added in this session:
- TestWindowsRocmIndexUrl: arch → AMD pip index URL mapping (gfx120X-all,
  gfx1151, gfx1150, gfx110X-all, unknown → None, trailing slash)
- TestDetectWindowsGfxArch: hipinfo output parsing, missing/timeout/bad
  returncode/no-gcnArchName paths
- TestInstallBnbWindowsRocm: UV_SKIP_WHEEL_FILENAME_CHECK set+restored,
  env restored on exception, no-op when URL missing
- TestRocmTorchInstalledEnvVar: UNSLOTH_ROCM_TORCH_INSTALLED=1 skips
  pip_install, calls _install_bnb_windows_rocm, sets flag
- TestWorkerWindowsRocmPatches: _grouped_mm CUDA dispatch override,
  offs/grouped variant handling, GC-prevention sentinel,
  _StubTypeMeta __instancecheck__, _StubSubpackageFinder registration,
  torchao key submodule pre-stubbing, TORCHDYNAMO_DISABLE guard
- TestRocmTorchPkgSpecs: rocm7.2 torch 2.11.x spec, default <2.11 cap,
  3-tuple shape, _GFX_TO_AMD_INDEX_ARCH RDNA4/3.5/3 coverage

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* tests: fix encoding, IS_WINDOWS patching, and wrong assertion

- Add encoding="utf-8" to all read_text() calls (54 occurrences) so
  tests pass on Windows where the default codec is cp1252 and source
  files contain UTF-8 emoji (e.g. ⚠️ in install_python_stack.py)
- Add @patch.object(stack_mod, "IS_WINDOWS", False) to Linux-path
  TestEnsureRocmTorch tests so they reach the Linux code path when run
  on a Windows machine instead of short-circuiting into the Windows branch
- Fix test_grouped_mm_patch_guarded_by_windows_and_hip_check: the source
  uses getattr(_torch_for_rocm, "version", None) not torch.version, so
  check for '"version"' and '"hip"' substrings instead

137 passed, 2 skipped

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: pin BNB_ROCM_VERSION=72 for torch==2.11.0+rocm7.13.0 compatibility

AMD's pip index now ships torch==2.11.0+rocm7.13.0 (ROCm 7.13).
bitsandbytes auto-detects HIP 7.13 from torch.version.hip and looks for
libbitsandbytes_rocm713.dll, which the AMD Windows prerelease wheel does
not ship (it only ships rocm72.dll), causing a load error at training start.

Fix:
- worker.py section 1f: set BNB_ROCM_VERSION=72 (via setdefault) before
  section 2 ML imports, so bitsandbytes always loads rocm72.dll on Windows ROCm
- install_python_stack.py: set BNB_ROCM_VERSION=72 in _install_bnb_windows_rocm()
  for any post-install imports; update comment to document root cause
- tests: 4 new assertions covering the fix (141 passed, 2 skipped)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: detect BNB ROCm DLL suffix dynamically instead of hardcoding '72'

BNB_ROCM_VERSION was pinned to '72' which works today (AMD wheel ships
rocm72.dll) but would break again if AMD ships a future wheel with a
different DLL suffix (e.g. rocm713.dll).

Add _detect_bnb_rocm_dll_ver() to install_python_stack.py: scans the
installed bitsandbytes package dir for libbitsandbytes_rocm{VER}.dll
using importlib.util.find_spec (no BNB import needed) and returns the
suffix.  '72' remains the fallback when detection fails.

Apply the same detection inline in worker.py section 1f.  Both paths
still respect a pre-set BNB_ROCM_VERSION (caller override wins).

Tests: +8 cases covering detection logic and fallback (147 passed, 2 skipped).

* fix: patch torch.distributed stubs in server process for Windows ROCm

On Windows ROCm, torch.distributed ships without process-group helpers
(is_initialized, is_available, get_rank, get_world_size).  The worker
subprocess already patches these in section 1e, but the main server
process calls _determine_attention_impl_for_gpu_estimate() which calls
unsloth's resolve_attention_implementation() → is_initialized(), causing:

  "Could not resolve attention implementation for '...':
   module 'torch.distributed' has no attribute 'is_initialized'"

Fix: patch the missing attrs onto torch.distributed at the top of
_determine_attention_impl_for_gpu_estimate, matching the same stubs
already applied in worker.py section 1e.  No-ops on Linux/CUDA where
torch.distributed is fully populated.

* fix: gate _grouped_mm dispatch patch on HIP < 7.13

AMD fixed the gfx1200 null HIP kernel in ROCm 7.13 (torch 2.11+).
Users on the new wheel now get the real GPU _grouped_mm kernel for
MoE workloads instead of the Python mm fallback.

Changes:
- worker.py: add _hip_ver_at_least() helper; wrap full _grouped_mm
  patch in `if not _hip_ver_at_least(7, 13):` with else branch that
  logs the skip reason; update section-1f comment to document the fix
- test_rocm_support.py: add 5 tests covering the helper definition,
  the (7, 13) gate expression, the else branch, the skip log message,
  and the AMD-format version string parsing (.split(".")[:2])

Verified: torch==2.11.0+rocm7.13.0 — 3D batch and grouped (offs)
variants both succeed; null crash only present on rocm7.12 and earlier.

* fix: stub is_torchelastic_launched on torch.distributed for Windows ROCm

resolve_attention_implementation calls is_torchelastic_launched() which
does not exist in the incomplete torch.distributed shipped with the
Windows ROCm wheel, causing a warning on every model config load in the
server process. Add it to the stub table alongside the four helpers
already patched in _determine_attention_impl_for_gpu_estimate.

Also adds two tests: one confirming the new stub and one confirming all
five core distributed helpers are covered.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: explicit warnings on AMD ROCm arch/version fallbacks + Fast-Install arg order

setup.ps1:
- Fix Fast-Install argument order: packages before flags, consistent with
  all other Fast-Install calls in the file
  (was: Fast-Install --force-reinstall --index-url $url torch ...)
  (now: Fast-Install torch torchvision torchaudio --force-reinstall --index-url $url)
- Add explicit [WARN] substep when $HasROCm is true but arch mapping fails:
  - GPU arch detected but not in supported wheel list → names the arch and
    lists supported families so user knows exactly what to report
  - HIP SDK present (amd-smi path) but gcnArchName unreadable → instructs
    user to re-install the HIP SDK; previously fell back silently to CPU

install.sh:
- Add [WARN] to stderr before silent CPU fallback when AMD GPU is confirmed
  (rocminfo/amd-smi) but ROCm version cannot be read from any source
  (amd-smi, /opt/rocm/.info/version, hipconfig, dpkg, rpm)
- Add [WARN] to stderr when ROCm version is too old (< 6.0) with upgrade link

install.ps1 and setup.sh: no changes needed (already handle these paths correctly)

* fix: robust gfx arch detection for Strix Halo / HIP-runtime-only installs

Covers users who have the HIP runtime (amd-smi available) but not the
full HIP SDK (no hipinfo), which is common on Strix Halo iGPU systems.
Without this, $ROCmGfxArch stays null and the installer silently falls
back to CPU-only PyTorch despite a working GPU.

Detection waterfall (setup.ps1 + install.ps1):
  1. hipinfo gcnArchName          -- full HIP SDK (existing, unchanged)
  2. amd-smi list gfx pattern     -- newer amd-smi versions embed arch
  3. amd-smi static --asic        -- ROCm 6+ ASIC details with GFX target
  4. UNSLOTH_ROCM_GFX_ARCH env    -- manual override escape hatch
  5. GPU name → arch table        -- best-effort from marketing name:
       890M / Strix Halo  → gfx1151 (RDNA 3.5 iGPU, Strix Halo)
       880M / Strix Point → gfx1150 (RDNA 3.5 iGPU, Strix Point)
       780M / Phoenix     → gfx1103 (RDNA 3 iGPU)
       RX 7900/7800/7700  → gfx1100 (RDNA 3 desktop)
       RX 9070 XT / 9080  → gfx1201 (RDNA 4)
       RX 9070 / 9060 XT  → gfx1200 (RDNA 4)

When arch is inferred from name, a Cyan substep tells the user to set
UNSLOTH_ROCM_GFX_ARCH to skip inference on future installs.
WMI block intentionally does not set $HasROCm (no runtime confirmation).

Tests: 11 new tests in TestStrixHaloGfxArchDetection covering all five
detection levels, WMI safety, and gfx regex in both ps1 files.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: resolve hipinfo/hipconfig via HIP_PATH/ROCM_PATH when not on PATH

AMD HIP SDK sets HIP_PATH on Windows but does not always add the bin
directory to PATH.  Get-Command hipinfo therefore silently fails and
detection falls through to WMI, which cannot provide a gfx arch, leaving
the user with a CPU-only PyTorch install and no warning.

Changes:
- setup.ps1 / install.ps1: before falling through to amd-smi, attempt to
  locate hipinfo.exe and hipconfig.exe under $env:HIP_PATH\bin (then
  $env:ROCM_PATH\bin) when Get-Command returns nothing
- Emit a [WARN] with the resolved path and a one-liner to permanently fix
  PATH via SetEnvironmentVariable
- Emit a [WARN] when HIP_PATH/ROCM_PATH is set but the exe is still not
  found (incomplete SDK install)
- Emit a [WARN] with the first hipinfo output line when hipinfo runs but
  returns a non-zero exit code (e.g. "no ROCm-capable device detected")
- 18 new tests in TestHipSdkEnvPathResolution; total 183 passed, 2 skipped

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* feat: print HIP SDK path and full hipconfig version in terminal on AMD detection

Both install.ps1 and setup.ps1 now emit substeps under the gpu step when
AMD ROCm is detected:

  gpu  AMD ROCm (gfx1200)
       HIP SDK: C:\Program Files\AMD\ROCm\7.1
       hipconfig: 7.1.51803-d3a86bd04

Previously only the gpu label (e.g. "AMD ROCm (gfx1200)") was shown with
no indication of where the SDK was found or which exact build was active.
The full hipconfig build string (e.g. 7.1.51803-d3a86bd04 instead of just
7.1) is now stored in ROCmVersionFull and also used in setup.ps1's
'rocm' step label.

9 new tests in TestHipSdkDetectedSubstep; total 192 passed, 2 skipped

* fix: Strix rocm7.1 segfault bypass + Ubuntu 24.04 HIP gcc-install-dir

Issue 1 (install.sh): gfx1151/gfx1150 + ROCm 7.1 causes a segfault in
torch._grouped_mm (moe_utils.py:167). The Radeon repo now ships cp313
wheels for rocm-rel-7.1, so _amd_gpu_radeon=true silently lands on the
broken combo. When Strix Halo/Point is detected and TORCH_INDEX_URL is
rocm7.1, override to rocm7.2 PyTorch index, update TORCH_CONSTRAINT, and
set _amd_gpu_radeon=false to bypass the Radeon repo entirely. Emits a
clear [WARN] explaining the segfault and linking to the ROCm upgrade docs.

Issue 2 (setup.sh): ROCm 7.x ships clang-20 which on Ubuntu 24.04+ picks
/usr/lib/gcc/x86_64-linux-gnu/14/ (runtime dir, no C++ headers), causing
'cstdlib file not found' and a failed llama.cpp HIP build. Iterate gcc
versions 14→11 to find the first install dir that has both runtime and
/usr/include/c++/<ver> headers, then pass --gcc-install-dir to clang via
CMAKE_HIP_FLAGS. Fix confirmed by h34v3nzc0dex (llama.cpp 417/417 clean).

11 new tests across TestStrixRocm71Override and TestSetupShGccInstallDir;
total 203 passed, 2 skipped

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: BNB_ROCM_VERSION in server process + torch._C._distributed_c10d stubs

Two errors visible in training logs on Windows ROCm:

1. Server process bitsandbytes crash:
   "Configured ROCm binary not found at libbitsandbytes_rocm713.dll"
   The installed BNB wheel ships rocm72.dll (not rocm713.dll). The
   training worker already sets BNB_ROCM_VERSION=72 via DLL detection
   but the server process (main.py) imported bitsandbytes before that
   ran. Fix: add the same DLL-scan + BNB_ROCM_VERSION assignment to
   main.py inside the existing win32 guard, before any downstream
   import can pull in bitsandbytes.

2. torch.distributed import failure:
   "No module named 'torch._C._distributed_c10d'; torch._C is not a package"
   torch._C is a C extension on Windows ROCm — Python cannot do
   submodule imports from it, so torch.distributed fails to import
   before our attribute stubs could ever run. Fix: inject empty
   ModuleType stubs for _distributed_c10d, _distributed_autograd and
   _distributed_rpc into sys.modules inside the win32 guard in
   hardware.py BEFORE importing torch.distributed, so the import
   succeeds and our attribute stubs take effect.

9 new tests in TestServerStartupRocmFixes; total 212 passed, 2 skipped

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(win32): populate distributed c10d stub with dummy symbols

torch.distributed tries to `from torch._C._distributed_c10d import
FakeProcessGroup` (and ProcessGroup, Work, Store, etc.).  The previous
empty ModuleType stub caused an AttributeError on those names.

Populate every stub with a _Dummy class for each known symbol so the
import chain completes silently on Windows ROCm where torch._C is a
compiled extension and its _distributed_c10d submodule doesn't exist.

Adds four new tests in TestServerStartupRocmFixes covering FakeProcessGroup,
ProcessGroup, setattr population, and all three _distributed_* siblings.

* fix(win32): distinguish HIP SDK installed vs GPU not ROCm-accessible

Previously, when hipinfo was found but exited non-zero (e.g. "no
ROCm-capable device detected"), both install.ps1 and setup.ps1 fell
through to the WMI-label-only branch and printed "AMD GPU detected --
HIP SDK not found" -- factually wrong since the SDK binary is present.

Add $HipSdkInstalled flag (set true when hipinfo binary is found,
regardless of exit code). When HipSdkInstalled && !HasROCm:
- Show "AMD GPU detected -- not ROCm-accessible (HIP <ver>)" instead
- Explain this is a driver issue, not an SDK issue, with a link
- Still run hipconfig version capture so version shows in output
- CPU-only hint now says "GPU not ROCm-accessible" not "require HIP SDK"

Also applies to setup.ps1 (same detection block, same branches).

Adds TestHipSdkInstalledButDeviceInaccessible (11 tests).

* fix(win32): scope ROCm workarounds to AMD hosts only

Three Codex-flagged issues where Windows ROCm workarounds incorrectly
applied to Windows CUDA (NVIDIA) machines:

main.py (P1): BNB_ROCM_VERSION was set unconditionally on all win32
hosts. On NVIDIA, bitsandbytes sees BNB_ROCM_VERSION and looks for a
ROCm DLL that doesn't exist, breaking bitsandbytes initialisation.
Fix: gate the block on HIP_PATH/ROCM_PATH being present (ROCm hosts only).

worker.py (P2): torchao stubs were seeded for all win32 runs, shadowing
real torchao on Windows CUDA and silently disabling torchao quantization
for NVIDIA users. Fix: gate on HIP_PATH/ROCM_PATH (win32 ROCm only).

install_python_stack.py (P1): _detect_windows_gfx_arch() only checked
shutil.which("hipinfo"), skipping the HIP_PATH/ROCM_PATH fallback that
the PowerShell installers use. On installs where the HIP SDK bin dir is
not on PATH, _ensure_rocm_torch() returned early without installing
ROCm wheels or bitsandbytes. Fix: mirror the env-var fallback.

* fix(linux): route Strix + ROCm 7.1 to AMD arch-specific index

Instead of falling back to pytorch.org/rocm7.2, the Strix override now
routes to repo.amd.com/rocm/whl/gfx1151/ (or gfx1150/) which serves
torch 2.11.0+rocm7.13.0 -- AMD's build containing the actual _grouped_mm
kernel fix, verified on real gfx1151 hardware by h34v3nzc0dex.

This exercises the real GPU kernel path rather than the rocm7.2 workaround.
UNSLOTH_AMD_ROCM_MIRROR can override the base URL for air-gapped installs.

Also teaches _tauri_torch_index_family to recognise AMD arch-specific URLs
(repo.amd.com/rocm/whl/gfx*) and return the rocm7.13 family label so
_tauri_gpu_branch correctly classifies these installs as rocm.

Suggested by h34v3nzc0dex based on hardware-verified probe results.

* fix(studio/rocm): gate ROCm-only side-effects on active torch runtime

Address five edge cases flagged during PR review:

1. studio/backend/main.py: BNB_ROCM_VERSION was set whenever HIP_PATH or
   ROCM_PATH was present in the environment. A Windows CUDA user who once
   installed the HIP SDK and reverted to a CUDA torch wheel still has those
   env vars set, so bitsandbytes would try to load libbitsandbytes_rocm72.dll
   against a CUDA torch and crash. Now probe torch.version.hip inside the
   env-var guard (worker.py already does this).

2. studio/backend/main.py: os.add_dll_directory returned handles were
   discarded. Per CPython docs, the directory leaves the DLL search list when
   the handle is garbage collected. Retain handles in module-level
   _ROCM_DLL_HANDLES list so they survive process lifetime.

3. studio/install_python_stack.py: _install_bnb_windows_rocm() returned None
   regardless of pip_install_try outcome, and the caller flipped
   _rocm_windows_torch_installed to True unconditionally. On a failed BNB
   install the post-install "manual install may be required" warning was
   suppressed and the user was misled. Helper now returns bool; caller gates
   on it.

4. studio/install_python_stack.py: _detect_windows_gfx_arch returned the raw
   capture group, so mixed-case hipinfo output ("Gfx1151") missed the
   lowercase keys in _GFX_TO_AMD_INDEX_ARCH and silently fell back to CPU
   torch. Lowercase the token.

5. studio/install_python_stack.py: UNSLOTH_ROCM_TORCH_INSTALLED=1 early-
   return trusted the env var even when the venv was wiped between runs.
   Subprocess-probe torch importability first; fall through to the full
   install path if the probe fails.

Tests: 231 passed, 1 skipped in tests/studio/install/test_rocm_support.py
(adds one new test for case 5 fall-through).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): worker.py parity + don't roll back ROCm torch on bnb failure

Addresses findings from a 10x reviewer pass on the prior fix commit:

1. studio/backend/core/training/worker.py (parity with main.py):
   - Gate the torchao stub block on torch.version.hip / 'rocm' in
     torch.__version__ instead of HIP_PATH / ROCM_PATH env-var presence.
     Same root cause as main.py: HIP SDK env vars stick around on CUDA hosts.
   - Add module-level Windows ROCm DLL registration block. Worker subprocesses
     inherit env vars but not the parent's add_dll_directory handles, so the
     first `import torch` in the worker could fail to find amdhip64.dll when
     HIP_PATH\bin is not on PATH. Mirrors main.py setup. Handles retained at
     module scope via _ROCM_DLL_HANDLES.
   - Promote _WINDOWS_ROCM_GROUPED_MM_LIB to module scope with `global` in
     run_training_process so the torch.library.Library registration survives
     past function return / mid-run garbage collection.
   - Harden _torch_has_hip() to also accept 'rocm' in torch.__version__
     (AMD SDK / Radeon wheels may not set torch.version.hip).

2. studio/install_python_stack.py:
   - Don't roll back ROCm torch when bitsandbytes install fails. The prior
     commit gated _rocm_windows_torch_installed on _install_bnb_windows_rocm()
     returning True; if torch installed successfully but bnb failed, the flag
     stayed False and later install steps could overwrite ROCm torch with the
     generic CPU torch wheel. Set the flag after torch install; surface bnb
     failure as a separate warning instead.
   - _detect_windows_gfx_arch now probes in three tiers: UNSLOTH_ROCM_GFX_ARCH
     env-var override (matches the PowerShell installer), then hipinfo (PATH
     or HIP_PATH\bin), then amd-smi (`static --asic`, `list`). Without the
     amd-smi fallback, runtime-only Radeon installs without hipinfo on PATH
     made `studio update` return early and leave the venv on CPU torch.
   - Linux torch-already-rocm probe in _ensure_rocm_torch now matches the
     Windows probe shape: accepts torch.version.hip OR 'rocm' in
     torch.__version__ to cover AMD SDK / Radeon Linux wheels.

3. studio/backend/utils/hardware/hardware.py:
   - apply_gpu_ids() final-fallback torch probe accepts 'rocm' in
     torch.__version__ in addition to torch.version.hip, matching
     detect_hardware(). AMD SDK wheels could otherwise leak through with
     CUDA-only visibility masks on a spawned ROCm worker.

Tests: 231 passed, 1 skipped in tests/studio/install/test_rocm_support.py
(no test changes needed; the probe shape that prints the hip version (or
'rocm' sentinel) preserves the existing non-empty-string contract).

Not addressed in this commit (deferred or out of scope):
- Tag drift / lemonade checksum (PR 5303 surface, not this PR).
- install.sh rocm7.2.1 URL: small fix, separate.
- install.ps1 / setup.ps1 'Radeon 8060S' marketing-name fallback table.
- Strix Halo + ROCm 7.1 routing asymmetry in Python update path.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): robustness pass - rocm tag normalisation, Strix routing parity, hardened detection

Robustness pass on top of 76137b2d. Four targeted fixes:

1. install.sh ROCm-tag routing normalisation.
   `rocm7.2.1` would route to https://download.pytorch.org/whl/rocm7.2.1
   which does not exist (PyTorch publishes major.minor URLs only). Same
   for any future patch-level tag. Normalise every rocm{maj.min}* pattern
   to the bare {maj.min} index URL.

2. install.ps1 + studio/setup.ps1 marketing-name fallback.
   The gfx1151 row matched 890M / Strix Halo / HX 37x / HX 38x / AI 9 HX
   but not the actual retail name 'AMD Radeon 8060S Graphics' shipped by
   OEMs (Ryzen AI MAX+ 395). Add '8060S' to the regex.

3. install_python_stack.py Strix + ROCm 7.1 routing parity with install.sh.
   The shell installer reroutes Strix Halo / Point + ROCm 7.1 to
   repo.amd.com/rocm/whl/{gfx}/ (which serves torch 2.11.0+rocm7.13.0
   with the upstream _grouped_mm fix). The Python `studio update` path
   only warned and still installed the broken generic rocm7.1 wheel.
   Mirror the override: detect gfx1151/gfx1150 on ROCm 7.1, route to
   the AMD per-gfx index, honour UNSLOTH_AMD_ROCM_MIRROR override.

4. _detect_windows_gfx_arch amd-smi parsing tightened.
   The amd-smi fallback added in the prior commit used a bare
   `\bgfx[1-9][0-9a-z]{2,3}\b` match against the lowercased stdout,
   which could pick up stray gfx references in warnings / device-name
   strings. Anchor on labelled lines first (Target_Graphics_Version,
   ASIC, Arch, gfx) and fall back to the bare match only when no
   labelled line is present.

Tests: 231 passed, 1 skipped in tests/studio/install/test_rocm_support.py;
sim_5301 23 cases pass (6 new sims for the Strix override + amd-smi parsing).

* fix(studio/rocm): multi-GPU selection, Strix sibling handling, defensive cleanups

Round 4 robustness pass based on 5 parallel Opus reviewers of head 21773215.
Seven items from across regression / edge-case / error-paths / architecture
reviews:

1. studio/backend/main.py BNB gate: aligned with the broad ROCm check used
   everywhere else in this PR (torch.version.hip OR 'rocm' in __version__).
   AMD SDK / Radeon Linux wheels do not always populate torch.version.hip;
   without this, main.py would silently skip BNB_ROCM_VERSION while worker.py
   set it.

2. studio/install_python_stack.py _install_bnb_windows_rocm: init _ok = False
   before the try block. Without this, if pip_install_try itself raises
   (e.g. OSError on uv binary missing), the finally block restored env vars
   correctly but the subsequent `if not _ok:` raised UnboundLocalError,
   masking the original exception.

3. studio/install_python_stack.py _detect_windows_gfx_arch:
   - Rewrote to use re.findall (not re.search) on both hipinfo and amd-smi
     output, dedup tokens preserving order, and select via new
     _pick_visible_index() helper.
   - HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES (first comma entry, integer)
     now picks the right GPU on multi-AMD-GPU hosts. Out-of-range or non-int
     values fall back to the first GPU (matches detect_host behaviour in
     install_llama_prebuilt.py).

4. studio/install_python_stack.py Strix override now consults the runtime
   target before flipping:
   - Previous behaviour intersected gfx_codes with {gfx1151, gfx1150} and
     picked the first Strix arch, ignoring whether HIP_VISIBLE_DEVICES
     selected a non-Strix sibling (e.g. discrete RX 7900 in a mixed APU+dGPU
     box). Could install Strix-specific wheels onto a gfx1100 dGPU.
   - Now resolves the runtime gfx via _pick_visible_index() and only
     overrides when that runtime target is in the Strix set.

5. studio/backend/main.py + studio/backend/core/training/worker.py: ROCm
   version dir scan no longer sorts lexically. Previous sort placed "10.0"
   before "7.0" alphabetically, which would mis-prioritise ROCm 10.x bin
   dirs once AMD ships them. New _ver_key() splits on "." and sorts
   numerically with a string fallback.

6. install.sh Strix override URL: replaced ${var%/} (strips one trailing
   slash) with a while-loop that strips all trailing slashes, matching
   Python's .rstrip("/"). A user setting UNSLOTH_AMD_ROCM_MIRROR with
   "http://corp/whl///" no longer ends up with "http://corp/whl///gfx1151/"
   which strict pip proxies (artifactory, sonatype) 404 on.

7. studio/install_python_stack.py: bumped torch import probe timeout from
   30s to 90s. PyTorch's lazy .so loading can take 60-90s on cold NFS or
   USB-backed venvs. The shorter timeout was producing a false "torch
   missing" classification and reinstalling a working ROCm torch.

Tests: 231 passed, 1 skipped. sim_5301 30 cases pass (added 7 new sims for
multi-GPU detection, Strix sibling handling, and _ok-init regression).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): worker BNB/grouped_mm broad gate, install.sh Strix visibility, runtime-only ROCm detection

Round-5 robustness pass based on 20 parallel reviewers of head 96b9e465.

1. studio/backend/core/training/worker.py - BNB version pin / dynamo disable
   / _grouped_mm fallback block was still gated on torch.version.hip alone
   despite the torchao stub block above already using the broad check. AMD
   SDK / Radeon Windows wheels (torch.__version__ contains "rocm" but
   torch.version.hip is None) silently skipped the Windows ROCm runtime
   patches. Aligned to the same broad check (8/20 reviewers).

2. studio/backend/core/training/worker.py - _hip_ver_at_least() now also
   parses the ROCm version out of torch.__version__ (e.g. "2.11.0+rocm7.13.0")
   when torch.version.hip is missing, so the kernel-fix gate is correct for
   SDK / Radeon wheels too.

3. studio/backend/core/training/worker.py - _grouped_mm_safe_impl with
   offs=None now picks torch.bmm/matmul for 3-D inputs instead of always
   calling torch.mm. The real _grouped_mm accepts 3-D batched matmul; the
   prior fallback raised "self must be a matrix" on MoE workloads (2/20).

4. studio/backend/main.py - dropped the HIP_PATH / ROCM_PATH env-var gate
   from the BNB block; probe torch directly. Runtime-only Radeon / AMD SDK
   Windows installs do not set those SDK env vars but still ship ROCm torch
   (5/20 reviewers).

5. install.sh - Strix override now collects every gfx token from
   rocminfo / amd-smi (in enumeration order), then indexes by
   HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES so a mixed Strix iGPU + non-
   Strix dGPU host where the user selected the dGPU does NOT get rerouted
   to the Strix per-gfx index. Mirrors the Python update path (5/20 reviewers).

6. install.sh - Strix detection chain now also probes `amd-smi static --asic`,
   matching the PowerShell installer (1/20). Closes the gap on runtime-only
   Strix hosts where `amd-smi list` does not surface a gfx token.

7. studio/install_python_stack.py - _has_rocm_gpu() now has the sysfs KFD
   topology fallback (/sys/class/kfd/kfd/topology/nodes/*/gpu_id), matching
   install.sh. On minimal package-managed installs without rocminfo /
   amd-smi GUI tools, `studio update` can now detect the GPU and repair the
   venv instead of returning early (2/20).

8. studio/install_python_stack.py - _detect_amd_gfx_codes() now falls back
   to `amd-smi list` and `amd-smi static --asic` when rocminfo is missing
   (2/20). Strix routing on runtime-only Radeon hosts now matches what
   install.sh has done for a while.

9. studio/install_python_stack.py - Strix override now applies even when
   has_hip_torch is True. The whole point of the override is to repair an
   existing broken torch.version.hip == "7.1" install; skipping the
   reinstall left users on the known _grouped_mm segfaulting stack (3/20).

Tests: 231 passed, 1 skipped. sim_5301 30 cases pass. sim_cross 12 pass.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): code review hardening pass

- main.py: numeric DLL sort (string sort picked rocm72 over rocm713);
  add basename() to regex; log warning on detection failure; log info
  when BNB_ROCM_VERSION is set (mirrors worker.py)
- worker.py: explicit len-guard in _hip_ver_at_least() with warning
  logs instead of silent IndexError/ValueError swallow
- hardware.py: isinstance(result, dict) guard before result.get() in
  _smi_query() to prevent AttributeError on non-dict backend returns
- amd.py: round() before int() on parsed GPU IDs; log warning when
  truncation occurs (defensive against malformed amd-smi output)
- setup.sh: quote --gcc-install-dir value in CMAKE_HIP_FLAGS so paths
  with spaces do not break the CMake argument
- install.ps1, setup.ps1: apply colon-split + ToLower() to hipinfo
  gcnArchName match (consistent with each other and with setup.sh)
- install.sh: tighten ROCm tag case patterns to explicit
  rocmX.Y|rocmX.Y.* to avoid unintended prefix matches

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/training): GPU OOM guard to prevent system freeze on VRAM exhaustion

On RDNA 4 (gfx1200/gfx1201) and other ROCm GPUs, exhausting VRAM can
cause a HIP driver hang that freezes the entire system rather than
raising a recoverable Python exception.

Two-part fix:
- set_per_process_memory_fraction(0.90) caps the HIP/CUDA allocator at
  90% of VRAM so PyTorch raises OutOfMemoryError before hitting the
  hardware limit, keeping the driver alive and the system responsive
- top-level exception handler detects OOM errors by type and message
  and surfaces a clear actionable message to the UI (reduce
  max_seq_length, enable gradient_checkpointing, lower batch size)
  instead of the raw CUDA/HIP error string

* fix(studio/rocm): OOM guard ROCm-only + unified memory, multi-GPU arch selection

OOM guard (worker.py):
- Scope to _hw.IS_ROCM only -- NVIDIA CUDA has a graceful OOM path and
  does not need the allocator cap
- Detect unified memory by comparing torch VRAM against psutil system RAM;
  use 0.80 on unified-memory APUs (gfx1151 Strix Halo) where the GPU pool
  is carved from host RAM, 0.90 on discrete cards

Multi-GPU arch selection:
- install.ps1 / setup.ps1: replace -match (first hit only) with
  [regex]::Matches() to collect all gcnArchName entries, then index by
  HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES
- install_python_stack.py: index into full token list before dedup so
  HIP_VISIBLE_DEVICES=2 on [gfx1100, gfx1100, gfx1151] resolves gfx1151
- install.sh: remove awk dedup from gfx token collection for same reason

GCC multiarch (setup.sh):
- Only append -linux-gnu when gcc -print-multiarch does not already return
  the full triple, fixing double-suffix on Ubuntu 24.04

* fix(tests): update ROCm version cap expectations from rocm7.1 to rocm7.2

Daniel's normalisation commit updated the cap from rocm7.1 to rocm7.2
since PyTorch now publishes that index and rocm7.2 ships torch 2.11.0.
Test expectations were stale.

* fix(tests): correct MLX smoke test losses_per_step assertion

logging_steps=1 with max_steps=30 produces 30 loss entries, not 7.
The assertion was stale from a previous config.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/worker): detect unified-memory APU by GPU name not VRAM/RAM ratio

The previous heuristic (VRAM > 50 % of system RAM) false-positived on discrete
cards in low-RAM systems — e.g. RX 9060 XT 16 GB on a 16 GB or 24 GB machine
would trip the unified-memory path and log "unified memory host" when it should
say "discrete".

AMD iGPUs (gfx1150/gfx1151 Strix Halo, Strix Point, etc.) expose names with a
digit+M suffix ("AMD Radeon 890M"), while discrete cards use "RX NNNN [XT|XTX]"
naming.  Matching that suffix is reliable across all current ROCm-capable AMD
consumer GPUs and does not require psutil.

Also includes the device name in the log line to ease future debugging.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(install/setup.ps1): force array on hipinfo gcnArchName parse to fix single-GPU arch truncation

When [regex]::Matches() finds exactly one match, PowerShell's pipeline
unwraps the result to a scalar string.  Indexing a scalar string with [0]
returns the first *character*, so a one-GPU system would parse
gcnArchName "gfx1200" as "g", which is not in the supported arch map
and triggers the CPU-only fallback.

Wrapping with @() forces the result to remain an array regardless of
match count.  On a single-GPU machine the arch is now correctly read as
"gfx1200" (or whatever the full name is) so the ROCm wheel index is
selected.

Reproducer: hipinfo exits 0 and outputs exactly one gcnArchName line.
Without @(), $_hipAllArches = "gfx1200" (String); $_hipAllArches[0] = 'g'.
With @(), $_hipAllArches = @("gfx1200") (Object[]); $_hipAllArches[0] = "gfx1200".

* fix(studio/rocm): classify unified-memory APU via VRAM/RAM ratio, not arch list

Replace the gcnArchName allowlist {gfx1150, gfx1151} with a
psutil-based heuristic: unified APUs expose the entire system RAM
as the HIP pool (ratio ≥ 0.90), discrete cards are well below that.
No arch name required — future APUs classify correctly without code changes.

Also removes the stale import re / \d[Mm]\b device-name regex that
5d84704 left behind, and logs vram/sys GiB for easier on-hardware
verification.

Addresses h34v3nzc0dex review: Radeon 8060S (gfx1151, 128 GiB
unified) now correctly gets 0.80 cap instead of 0.90.

* fix(studio/rocm): revert to gcnArchName for unified-memory APU classification

VRAM/RAM ratio >= 0.90 false-positives on machines where discrete VRAM
equals system RAM (e.g. RX 9060 XT 16 GB + 16 GB system RAM → ratio 1.0,
incorrectly classified as unified → wrong 0.80 cap applied).

gcnArchName is the correct signal: naming-independent, stable within a
product family, and already parsed throughout this PR. Unified set is
{gfx1150, gfx1151} (Strix Point + Strix Halo).

* fix(studio/llama-prebuilt): resolve hipinfo via HIP_PATH/ROCM_PATH on Windows

shutil.which("hipinfo") returns None when the HIP SDK bin dir is not on
PATH -- the HIP SDK installer sets HIP_PATH/ROCM_PATH but does not always
add the bin dir to PATH. This caused has_rocm=False in the prebuilt asset
selector, so AMD ROCm machines got the CPU llama.cpp zip instead of the
HIP one, silently running all chat inference on CPU.

Add _resolve_exe() that falls back to %HIP_PATH%\bin and %ROCM_PATH%\bin
when shutil.which() finds nothing, mirroring the same fallback already
present in setup.ps1.

* fix(studio/llama-prebuilt): pass --has-rocm from setup.ps1 to skip re-detection

The Python prebuilt installer re-detects ROCm independently via
shutil.which("hipinfo"), which fails when hipinfo is not on PATH
(HIP SDK sets HIP_PATH but doesn't always add the bin dir to PATH).
This caused has_rocm=False and downloaded the CPU llama.cpp zip even
on confirmed AMD ROCm machines.

setup.ps1 already performs reliable ROCm detection with its own
HIP_PATH/ROCM_PATH fallback. Add --has-rocm flag to
install_llama_prebuilt.py so setup.ps1 can forward its result directly,
and pass it whenever $HasROCm is true. The Python script then overrides
has_rocm=True in the HostInfo without re-probing.

* fix(studio/llama-prebuilt): add HIP asset to simple-policy Windows path

direct_upstream_release_plan (used by --simple-policy, which setup.ps1
always passes) only checked has_usable_nvidia on Windows and fell
straight to CPU for AMD ROCm machines, ignoring has_rocm entirely.
The --has-rocm override had no effect because the simple-policy code
path never reached resolve_asset_choice where has_rocm was checked.

Add an elif branch for has_rocm that tries the upstream HIP asset
(llama-TAG-bin-win-hip-radeon-x64.zip) before falling through to the
CPU fallback, consistent with the non-simple-policy path.

* fix(studio/setup.ps1): auto-remove mismatched llama.cpp install kind

When an existing llama.cpp install is the wrong kind for the current
GPU (e.g. windows-cpu on an AMD ROCm machine that should have
windows-hip), the prebuilt installer skips on tag match and never
upgrades. Read install_kind from UNSLOTH_PREBUILT_INFO.json before
invoking the installer and remove the directory if the kind doesn't
match, forcing a fresh download of the correct variant.

* fix(studio/setup.ps1): show live PyTorch install output in verbose mode for ROCm

The ROCm torch reinstall (setup.ps1 phase) always silently captured
output, so in --verbose mode the torch downgrade mid-install
(2.11.0+rocm → 2.10.0 → 2.11.0+rocm) looked like the final state was
2.10.0. Match the CPU/CUDA blocks which show live uv output when
$script:UnslothVerbose is set.

* fix(rocm/windows): set ROCBLAS_TENSILE_LIBPATH for bundled rocblas.dll

The llama.cpp ROCm prebuilt bundles rocblas.dll next to the binary but
not the Tensile kernel library files it depends on at runtime
(rocblas/library/TensileLibrary*.dat + *.hsaco).  The bundled DLL
searches for these files relative to its own location by default, i.e.
<binary_dir>/rocblas/library/, which does not exist in the prebuilt
install tree.  This causes a silent crash on the very first GEMM
(prefill) with no output from llama-server, seen by the caller as
WinError 10054 / 10061.  Model load and the single-token warmup pass
because they use simpler code paths that do not trigger rocBLAS GEMM.

Fix: set ROCBLAS_TENSILE_LIBPATH in the subprocess env to
<HIP_PATH>/bin/rocblas/library so the bundled DLL finds the kernel
files from the system ROCm installation.  Uses setdefault so a user-
supplied env var is never overwritten.  No-ops on CUDA and CPU (no
HIP_PATH) and on Linux (win32 branch only).

Reproducer log:
  rocBLAS error: Cannot read .../Release/rocblas/library/TensileLibrary.dat
  rocBLAS error: Could not initialize Tensile host:
  directory_iterator: The system cannot find the path specified.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(install.sh): restore gfx token dedup in Strix multi-GPU awk indexer

536a54df removed the per-source `| awk '!seen[$0]++'` dedup from the
_gfx_all collection step but left the indexer awk as bare NF, so on a
mixed-arch host (e.g. dGPU gfx1100 + Strix iGPU gfx1151) where
rocminfo emits each gfx token twice (Name: field + ISA triple),
HIP_VISIBLE_DEVICES=1 indexed vals[1] = the second gfx1100 occurrence
instead of gfx1151, triggering the Strix routing on the wrong GPU.

Add !seen[$0]++ to the indexer awk so duplicate tokens from the same
GPU collapse to one entry before the HIP_VISIBLE_DEVICES index is
applied -- matching exactly what the Python side does with dict.fromkeys()
in _detect_amd_gfx_codes(). The comment above the block ("skip
duplicates") already documented this as the intended behaviour.

* fix(studio/install): correct _TOTAL progress count on Windows

base_total += 3 fired for all non-macOS platforms including Windows,
but flash-attn (line 1620) and ROCm torch final (line 1705) are both
guarded by 'not IS_WINDOWS and not IS_MACOS', so on Windows with torch
enabled _TOTAL was 13 while only 11 _progress() calls actually execute.

Split into +1 for the ROCm torch check (all non-macOS) and +2 for the
two Linux-only steps, so Windows gets _TOTAL=11 and Linux gets 14.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(install.ps1): enforce torch>=2.11.0 for gfx120X and Strix on Windows

The AMD arch-specific index (repo.amd.com/rocm/whl/gfx120X-all/ and
gfx1151/) publishes torch wheels from 2.7.1 through 2.11.0. Without a
version floor pip can resolve to torch 2.10.0+rocm7.12 on RDNA 4
(gfx120X) or torch 2.10.0+rocm7.1 on Strix (gfx1151/gfx1150), both of
which have a null-pointer crash in torch._C._grouped_mm (TheRock
issues #5284 / #3284). torch 2.11.0+rocm7.13 contains the fix.

Add $ROCmTorchFloor alongside $ROCmIndexUrl: set to torch>=2.11.0 for
the two affected arch families, null for all others. Wire it into the
uv pip install call so the broken wheels are never selected.

* fix(rocm/windows): address Codex nits - deterministic DLL suffix, CUDA llama.cpp kind, HIP_VISIBLE_DEVICES arch indexing

- install_python_stack.py / worker.py: _detect_bnb_rocm_dll_ver() and the
  inline worker probe now collect ALL libbitsandbytes_rocm*.dll suffixes and
  return max() by numeric value instead of stopping at the first glob hit.
  Filesystem glob order is not guaranteed; this ensures '713' always wins
  over '72' when both variants are present in the wheel.

- setup.ps1 (expectedKind): add 'windows-cuda' branch so NVIDIA hosts are
  not treated as 'windows-cpu'. Previously an existing windows-cuda prebuilt
  was always considered a mismatch on non-ROCm machines, forcing an
  unnecessary re-download on every update.

- setup.ps1 (amd-smi gfx arch): collect ALL gfx tokens from amd-smi list
  output in GPU order and honour HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES
  when selecting which arch to use. On mixed-arch AMD systems where the
  visible GPU is not the first enumerated one, this prevents installing an
  incompatible wheel index. Falls back to index 0 (same as before) when the
  visibility var is unset or is a comma-separated list.

- test_rocm_support.py: add test_picks_highest_suffix_when_multiple_dlls to
  cover the multi-DLL case that was previously untested.

* fix(rocm): misleading amd-smi log, BNB spec consistency, torch ceiling for AMD index

amd.py: split 'returncode != 0 or not stdout' into two separate branches.
Previously, exit-0 with empty output logged 'amd-smi returned code 0' (which
reads as success, not a warning) and incorrectly incremented the circuit-breaker
counter. Now: non-zero exit logs the code and counts toward the limit as before;
empty stdout on exit 0 logs at DEBUG level and does not penalise the counter
(amd-smi --json always emits at least [] on exit 0, so this branch is rare and
is not a tool failure).

main.py: replace spec.origin / os.path.dirname() with
spec.submodule_search_locations to match install_python_stack.py and worker.py.
For normal wheel installs both approaches reach the same directory, but using
submodule_search_locations is the canonical way and handles editable bitsandbytes
installs correctly. Also use max() by numeric suffix (same as the other two sites)
instead of a sort-then-break loop.

install.ps1: add <2.12.0 ceiling to the torch constraint for gfx120X (RDNA 4)
and gfx1151/gfx1150 (Strix). AMD actively publishes new versions on their
per-arch index; without a ceiling, a future 2.12.0+rocmX.Y wheel would be
pulled in automatically before being validated on these architectures. The
ceiling matches the existing Linux install_python_stack.py constraint for the
same arches. Bump both when 2.12.x is confirmed working.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(rocm): torch floor in setup.ps1, torchvision pin for Strix, rocmsdk in _hip_ver_at_least

setup.ps1: add \ (mirrors install.ps1) and derive \
from it. Previously the AMD index install called 'Fast-Install torch torchvision
torchaudio --force-reinstall --index-url \' with no version
constraint, so pip could resolve torch 2.10.0+rocm7.12 for gfx1151/gfx1200 --
the exact broken wheel the PR is meant to avoid. Now gfx120X and Strix enforce
'torch>=2.11.0,<2.12.0', matching install.ps1 and the Linux constraint.

install_python_stack.py: pin torchvision and torchaudio in _strix_override_pkgs.
The Strix Linux override uses --index-url (exclusive, no PyPI fallback); bare
unversioned 'torchvision' and 'torchaudio' could resolve a build from AMD's
index targeting a different torch major, causing ABI/version mismatches at
runtime. Now pinned to '>=0.26.0,<0.27.0' and '>=2.11.0,<2.12.0' respectively,
matching _ROCM_TORCH_CONSTRAINT['rocm7.2'].

worker.py: extend _hip_ver_at_least to handle AMD SDK wheel version strings.
The fallback regex r'rocm(\d+)\.(\d+)' cannot match '2.9.0+rocmsdk20251116'
(no rocmX.Y component), so the function always returned False on SDK/Radeon
wheels -- installing the Python _grouped_mm workaround on wheels that already
have the working HIP kernel. Added a second check: if the version string
contains '+rocmsdk', assume >= 7.13 (the rocmsdk format post-dates the
gfx120X null-kernel fix) and skip the fallback.

* fix(rocm): warn on OOB HIP_VISIBLE_DEVICES, bail on empty numeric_ids mask

- setup.ps1: when HIP/ROCR_VISIBLE_DEVICES names an index beyond the
  detected GPU count, emit a yellow warning and fall back to GPU 0
  instead of silently reading allGfxArches[-1] (wrong arch)
- hardware.py _reconcile_primary_rocm_unified_memory: distinguish
  numeric_ids=None (no env var, use torch ordinal 0) from numeric_ids=[]
  (empty mask / HIP_VISIBLE_DEVICES=-1, no GPU visible); bail out early
  in the empty case to avoid querying torch.device(0) incorrectly

* fix(rocm): gate StubSubpackageFinder on win32 ROCm, add gcnArchName fallbacks

- worker.py _StubSubpackageFinder: the meta_path append was running on
  every platform on every call to run_training_process; moved it inside
  the if _is_win32_rocm: block since stubs are only seeded there and the
  finder is a pure accumulation on Linux/Windows CUDA
- worker.py OOM guard: AMD SDK / Radeon wheels may not populate
  gcnArchName, causing Strix Halo to be misclassified as discrete and
  get the 0.90 cap (12.8 GB OS headroom) instead of 0.80 (25.6 GB);
  now tries gcn_arch_name / arch_name / gfx_arch_name variants first,
  then falls back to device-name matching (890M -> Strix Halo,
  880M -> Strix Point) with a debug log when the fallback fires

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(rocm): pin torchvision/torchaudio in setup.ps1, remove -Unique from arch array

- setup.ps1 ROCm torch install: torchvision and torchaudio were passed
  bare alongside pinned torch>=2.11.0,<2.12.0 for gfx1151/gfx1200 arches.
  AMD publishes packages independently so a future torchvision 0.27 (for
  torch 2.12) on the same arch index would cause pip ResolutionImpossible
  or an ABI-incompatible install. Added torchvisionFloorMap and
  torchaudioFloorMap mirroring install_python_stack.py's strix override
  (torchvision>=0.26.0,<0.27.0, torchaudio>=2.11.0,<2.12.0) and derived
  ROCmVisionSpec/ROCmAudioSpec used in all three Fast-Install call sites.

- setup.ps1 amd-smi arch detection: Select-Object -Unique was collapsing
  same-arch multi-GPU arrays (e.g. two gfx1151 APUs -> 1-element array)
  causing HIP_VISIBLE_DEVICES=1 to trigger a false out-of-range warning
  and fall back to GPU 0 even though the correct GPU would have been at
  index 1. Removed -Unique; added comment noting the positional-index
  assumption and its non-contiguous-GPU limitation.

* fix(rocm): add 8060s/8050s to OOM guard device-name fallback, extract classifier helper

Path 3 of the OOM guard device-name fallback only checked for 890m/880m
(gfx1150 Strix Point SKU names). Strix Halo (gfx1151) ships as Radeon 8060S
(Ryzen AI MAX+ 395) and Radeon 8050S (cut-down SKU) -- neither matches, so
the fallback returned is_unified=False and applied the 0.90 fraction instead
of 0.80, leaving ~12.8 GiB OS headroom on a 128 GiB pool instead of ~25.6 GiB.

Fix: add 8060s and 8050s to the name-match set. Also correct the comment that
mislabelled 890M as a Strix Halo name (it is Strix Point).

Refactor: extract the three-path classifier into _rocm_classify_unified_memory()
so it can be unit-tested directly. Add 31 test cases in test_rocm_oom_guard.py
covering all three paths and the regression case (Radeon 8060S Graphics).

Reported-by: h34v3nzc0dex

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(rocm): pass explicit dtype on bf16-unsupported hardware (RDNA2)

dtype=None lets unsloth auto-detect the model dtype. On RDNA2 (gfx103x,
e.g. RX 6600) is_bfloat16_supported() incorrectly returns True, so unsloth
picks bf16 and the first bf16 kernel dispatch triggers:

  LLVM ERROR: Cannot select: intrinsic %llvm.amdgcn.fdot2.bf16.bf16

Replace every dtype=None in load_model() with _auto_dtype which resolves
to None when bf16 is supported (all modern NVIDIA + RDNA3+) and
torch.float16 otherwise. This gives RDNA2 users a working float16
training path without touching NVIDIA behaviour at all.

Fixes: https://github.com/unslothai/unsloth/issues/5337

* fix: reduce log noise for expected non-issues on Windows ROCm

Three log lines fired at warning/error level for conditions that are
completely expected on a Windows HIP SDK-only setup:

amd.py
- amd-smi WinError 2 (FileNotFoundError): downgrade warning -> debug.
  amd-smi ships with Adrenalin, not the HIP SDK; absence is normal.
- 'disabling' message: downgrade warning -> info with clearer text
  'not available (not installed; expected on HIP SDK-only systems);
  GPU VRAM polling disabled'

hardware.py
- torch.distributed.Store missing: downgrade warning -> debug.
  The distributed stub added in this PR intentionally omits Store; the
  attention-impl fallback to eager is expected and non-actionable.

worker.py
- causal-conv1d: add early Windows exit (info) in both
  _ensure_causal_conv1d_fast_path and _causal_conv1d_install hook;
  no cp313/win_amd64 wheel exists, so the install always fails.
- FLA: add early Windows exit (info) in
  _ensure_flash_linear_attention_unconditional; triton dependency has
  no cp313/win_amd64 wheel.
- Defense-in-depth: _install_package_wheel_first non-HIP PyPI failure
  logs info+debug on Windows instead of error; FLA failure logs
  info+debug on Windows instead of warning.

* [AMD] FIx installation of bitsandbytes when it's from .dev and skip rebuilding llama.cpp if we build it manually.

* fix: use force_pip for Windows ROCm bitsandbytes prebuilt wheel install

uv rejects the bnb continuous-release wheel due to filename/metadata
version mismatch (1.33.7.preview vs 0.50.0.dev0). Switch to force_pip=True
(pip bypass) instead of the UV_SKIP_WHEEL_FILENAME_CHECK env var workaround
-- cleaner and consistent with how the Linux path handles it.

BNB_ROCM_VERSION is still set post-install to the detected DLL suffix so
the worker subprocess loads the correct libbitsandbytes_rocm{VER}.dll even
when torch.version.hip reports a newer HIP version than the wheel ships.

* fix: three small correctness fixes found in PR review

- _install_bnb_windows_rocm: use UV_SKIP_WHEEL_FILENAME_CHECK=1 with
  try/finally instead of force_pip=True so the env var is always
  restored and the failing CI test passes
- _determine_attention_impl_for_gpu_estimate: gate torch._C distributed
  stubs on IS_ROCM so Windows CUDA users keep the real extension
- install.ps1 amd-smi fallback: collect all gfx tokens and index by
  HIP_VISIBLE_DEVICES, matching the hipinfo path on multi-GPU hosts

* fix: stub torchao in export subprocess on Windows ROCm

On Windows, the ROCm build of PyTorch ships without the distributed
C extension (torch._C._distributed_c10d). torchao, which is pulled in
transitively by transformers.quantizers at import time, walks into
torch.distributed._functional_collectives -> distributed_c10d and
crashes with:

  No module named 'torch._C._distributed_c10d'; 'torch._C' is not a package

This only affected the export subprocess because the training subprocess
already applied an identical torchao stub (introduced separately to fix
the same root cause). The export subprocess had no such guard and died
during 'Importing Unsloth...' before any model loading could happen.

Fix: apply the same _StubSubpackageFinder / torchao stub pattern to the
export subprocess entry point, gated on Windows ROCm detection, before
any import of transformers or unsloth_zoo.

Root cause tracked in ROCm/TheRock#3284 (libuv / torch.distributed
missing on Windows ROCm builds).

Ref: https://github.com/ROCm/TheRock/issues/3284

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* install.sh, setup.sh: add GPU arch step logging to match PS1 scripts

Both shell scripts were missing the step "gpu" terminal log block that
install.ps1 and setup.ps1 emit. This adds equivalent output: GPU label
with gfx arch (e.g. "AMD ROCm (gfx1151)"), ROCm root path, hipconfig
version, and marketing name substep. Includes the same gfx arch detection
chain (rocminfo → amd-smi list → amd-smi static --asic), UNSLOTH_ROCM_GFX_ARCH
env override, and name-based arch inference table (Strix Halo/Point, RDNA 3/4)
as the PS1 versions. install.sh also replaces bare echo blocks for the AMD
ROCm and CPU-only cases with formatted substep output.

* Fix BNB_ROCM_VERSION gate, ROCm GPU mask preference, APU unified memory and Release build for PR #5301

- main.py: gate BNB_ROCM_VERSION on the rocm bnb DLL or HIP_PATH/ROCM_PATH instead of importing torch on every Windows host
- hardware.py: prefer HIP/ROCR visible-device masks only on ROCm hosts so a stale mask cannot override CUDA_VISIBLE_DEVICES on NVIDIA
- llama_cpp.py: set GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 only for unified-memory APUs (gfx1150/gfx1151)
- setup.sh: pass -DCMAKE_BUILD_TYPE=Release for the HIP source build
- add test_amd_apu_unified_memory.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: guard recompile_limit + fix AMD VRAM monitor fallback

trainer.py: torch._dynamo.config.recompile_limit does not exist in
some ROCm torch builds (e.g. pytorch.org/whl/rocm6.2 wheels). Guard
the assignment so training doesn't crash on RDNA2/RDNA3.

hardware.py: when amd-smi/nvidia-smi is unavailable or returns no
usable data (HIP SDK-only Windows, Docker, unexpected JSON format),
the existing fallback used torch.cuda.memory_allocated() which is
process-specific and reads near-zero even with a fully loaded model.
Switch to torch.cuda.mem_get_info() via _torch_get_per_device_info()
which reports system-wide VRAM occupancy so the GPU monitor shows
real usage on all AMD systems without requiring amd-smi.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: Windows VRAM monitor via Performance Counter API

When amd-smi/nvidia-smi is unavailable on Windows, query dedicated GPU
VRAM via Windows Performance Counters (same source as Task Manager).
This gives system-wide cross-process usage, fixing the near-zero reading
caused by torch.cuda.mem_get_info only seeing the Studio server process.

Linux fallback path unchanged (mem_get_info is system-wide on ROCm).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: rename to _rocm_windows_perf_counter_vram_gb, scope to IS_ROCM

Function is AMD ROCm specific — amd-smi absent on Windows when only the
HIP SDK is installed. Scoped to IS_ROCM so NVIDIA Windows path is
untouched (nvidia-smi handles that case).

* fix: AMD VRAM monitor — Linux DRM sysfs + Windows perf counter

Linux: read /sys/class/drm/card*/device/mem_info_vram_used|total for
system-wide GPU memory across all processes. No tools required, always
present on Linux AMD systems.

Windows: Windows Performance Counter API (already added).

Both paths are gated on IS_ROCM and only fire when amd-smi is absent.
torch mem_get_info remains as last resort (process-local).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: AMD GPU monitor — utilization, temperature, and power for Windows and Linux fallback paths

- Windows: GPU utilization via \GPU Engine(*engtype_3D*)\Utilization Percentage perf counter
- Windows: temperature and power via ADL (atiadlxx.dll, ships with Adrenalin)
- Linux: GPU utilization via DRM sysfs gpu_busy_percent
- Linux: temperature via hwmon temp1_input (millidegrees C)
- Linux: power via hwmon power1_average / power1_input (microwatts)

All paths are no-op fallbacks (None) when the source is unavailable.
Mirrors what nvidia-smi provides on the CUDA path.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: remove ADL ctypes — does not support AMD iGPU (Strix Halo)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: Erland366 <erland.pg366@gmail.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 install.ps1                                   |  264 +++-
 install.sh                                    |  237 +++-
 studio/backend/core/export/worker.py          |   97 ++
 studio/backend/core/inference/llama_cpp.py    |   53 +
 studio/backend/core/training/trainer.py       |   26 +-
 studio/backend/core/training/worker.py        |  632 ++++++++-
 studio/backend/main.py                        |  104 ++
 .../tests/test_amd_apu_unified_memory.py      |   52 +
 .../tests/test_log_filter_no_truncation.py    |   24 +-
 studio/backend/tests/test_rocm_oom_guard.py   |  176 +++
 studio/backend/utils/hardware/amd.py          |   62 +-
 studio/backend/utils/hardware/hardware.py     |  392 +++++-
 studio/backend/utils/wheel_utils.py           |    2 +
 studio/install_llama_prebuilt.py              |   53 +-
 studio/install_python_stack.py                |  553 +++++++-
 studio/setup.ps1                              |  343 ++++-
 studio/setup.sh                               |  120 +-
 tests/sh/test_get_torch_index_url.sh          |    8 +-
 tests/studio/install/conftest.py              |   20 +
 tests/studio/install/test_rocm_support.py     | 1248 ++++++++++++++++-
 unsloth/models/loader_utils.py                |    5 +-
 21 files changed, 4272 insertions(+), 199 deletions(-)
 create mode 100644 studio/backend/tests/test_amd_apu_unified_memory.py
 create mode 100644 studio/backend/tests/test_rocm_oom_guard.py
 create mode 100644 tests/studio/install/conftest.py

diff --git a/install.ps1 b/install.ps1
index c4e8d8d522..cab66f5ae1 100644
--- a/install.ps1
+++ b/install.ps1
@@ -976,6 +976,7 @@ shell.Run cmd, 0, False
     # Find-CompatiblePython returns @{ Version = "3.13"; Path = "C:\...\python.exe" } or $null.
     Write-TauriLog "STEP" "Installing Python"
     $DetectedPython = Find-CompatiblePython
+
     if ($DetectedPython) {
         step "python" "Python $($DetectedPython.Version) already installed"
     }
@@ -1239,11 +1240,196 @@ shell.Run cmd, 0, False
             }
         }
     }
+    # ── AMD ROCm detection (Windows) — mirrors setup.ps1 ──
+    $HasROCm = $false
+    $HipSdkInstalled = $false   # HIP SDK binary found (independent of device accessibility)
+    $ROCmGpuLabel = $null
+    $ROCmVersion = $null
+    $ROCmGfxArch = $null
+    if (-not $HasNvidiaSmi) {
+        # hipinfo: PATH first, then HIP_PATH/ROCM_PATH bin fallback (mirrors NVIDIA smi path resolution).
+        # AMD HIP SDK sets HIP_PATH but may not add the bin dir to PATH depending on install type.
+        $hipinfoExe = Get-Command hipinfo -ErrorAction SilentlyContinue
+        if (-not $hipinfoExe) {
+            $hipRoot     = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
+            $hipEnvLabel = if ($env:HIP_PATH) { "HIP_PATH"    } else                    { "ROCM_PATH"    }
+            if ($hipRoot) {
+                $hipinfoCandidate = Join-Path $hipRoot "bin\hipinfo.exe"
+                if (Test-Path $hipinfoCandidate) {
+                    Write-Host "  [WARN] hipinfo not on PATH -- located via ${hipEnvLabel}: $hipinfoCandidate" -ForegroundColor Yellow
+                    Write-Host "         Add '$(Join-Path $hipRoot 'bin')' to your PATH to suppress this warning" -ForegroundColor Yellow
+                    Write-Host "         Quick fix: [Environment]::SetEnvironmentVariable('PATH',`$env:PATH+';$(Join-Path $hipRoot 'bin')','User')" -ForegroundColor Yellow
+                    $hipinfoExe = [PSCustomObject]@{ Source = $hipinfoCandidate }
+                } else {
+                    Write-Host "  [WARN] ${hipEnvLabel}=$hipRoot is set but hipinfo.exe not found at $hipinfoCandidate" -ForegroundColor Yellow
+                    Write-Host "         HIP SDK install may be incomplete -- re-install from:" -ForegroundColor Yellow
+                    Write-Host "         https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" -ForegroundColor Yellow
+                }
+            }
+        }
+        if ($hipinfoExe) {
+            $HipSdkInstalled = $true   # binary found → SDK is installed regardless of device state
+            try {
+                $hipOut = & $hipinfoExe.Source 2>&1 | Out-String
+                if ($LASTEXITCODE -eq 0 -and $hipOut -match "(?i)gcnArchName") {
+                    $HasROCm = $true
+                    $_hipAllArches = @([regex]::Matches($hipOut, "(?im)^\s*gcnArchName\s*:\s*(\S+)") | ForEach-Object { ($_.Groups[1].Value -split ':')[0].Trim().ToLower() })
+                    $_hipVisIdx = if ($env:HIP_VISIBLE_DEVICES -match '^\d') { [int]($env:HIP_VISIBLE_DEVICES -split ',')[0] } elseif ($env:ROCR_VISIBLE_DEVICES -match '^\d') { [int]($env:ROCR_VISIBLE_DEVICES -split ',')[0] } else { 0 }
+                    if ($_hipAllArches.Count -gt 0) {
+                        $ROCmGfxArch  = if ($_hipVisIdx -lt $_hipAllArches.Count) { $_hipAllArches[$_hipVisIdx] } else { $_hipAllArches[0] }
+                        $ROCmGpuLabel = "AMD ROCm ($ROCmGfxArch)"
+                    } else {
+                        $ROCmGpuLabel = "AMD ROCm"
+                    }
+                } elseif ($LASTEXITCODE -ne 0) {
+                    # hipinfo ran but returned a HIP runtime error (e.g. "no ROCm-capable device detected")
+                    $firstLine = ($hipOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1)
+                    Write-Host "  [WARN] hipinfo returned a HIP runtime error (exit $LASTEXITCODE)" -ForegroundColor Yellow
+                    Write-Host "         $firstLine" -ForegroundColor Yellow
+                    Write-Host "         Ensure ROCm drivers are installed: https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" -ForegroundColor Yellow
+                }
+            } catch {}
+        }
+        if (-not $HasROCm) {
+            $amdSmiExe = Get-Command "amd-smi" -ErrorAction SilentlyContinue
+            if ($amdSmiExe) {
+                try {
+                    $smiOut = & $amdSmiExe.Source list 2>&1 | Out-String
+                    if ($LASTEXITCODE -eq 0 -and $smiOut -match "(?im)^GPU\s*[:\[]\s*\d") {
+                        $HasROCm = $true
+                        # Mirror the hipinfo path: collect all gfx tokens in enumeration
+                        # order and pick the runtime-visible one via HIP_VISIBLE_DEVICES.
+                        $_smiVisIdx = if ($env:HIP_VISIBLE_DEVICES -match '^\d') { [int]($env:HIP_VISIBLE_DEVICES -split ',')[0] } elseif ($env:ROCR_VISIBLE_DEVICES -match '^\d') { [int]($env:ROCR_VISIBLE_DEVICES -split ',')[0] } else { 0 }
+                        # Attempt 1: newer amd-smi versions embed the gfx arch in list output.
+                        $_smiGfxTokens = @([regex]::Matches($smiOut, "(?i)\b(gfx\d+[a-z]?)\b") | ForEach-Object { $_.Groups[1].Value.ToLower() })
+                        if ($_smiGfxTokens.Count -gt 0) {
+                            $ROCmGfxArch = if ($_smiVisIdx -lt $_smiGfxTokens.Count) { $_smiGfxTokens[$_smiVisIdx] } else { $_smiGfxTokens[0] }
+                            $ROCmGpuLabel = "AMD ROCm ($ROCmGfxArch)"
+                        } else {
+                            # Attempt 2: 'static --asic' exposes ASIC details on ROCm 6+,
+                            # including the GFX target needed for wheel index selection.
+                            $smiAsicOut = ""
+                            try { $smiAsicOut = & $amdSmiExe.Source static --asic 2>&1 | Out-String } catch {}
+                            $_asicGfxTokens = @([regex]::Matches($smiAsicOut, "(?i)\b(gfx\d+[a-z]?)\b") | ForEach-Object { $_.Groups[1].Value.ToLower() })
+                            if ($_asicGfxTokens.Count -gt 0) {
+                                $ROCmGfxArch = if ($_smiVisIdx -lt $_asicGfxTokens.Count) { $_asicGfxTokens[$_smiVisIdx] } else { $_asicGfxTokens[0] }
+                                $ROCmGpuLabel = "AMD ROCm ($ROCmGfxArch)"
+                            } elseif ($smiAsicOut -match "(?im)Market.?Name\s*[:\|]\s*([^\r\n]+)") {
+                                $ROCmGpuLabel = "AMD ROCm ($($Matches[1].Trim()))"
+                            } else {
+                                $ROCmGpuLabel = "AMD ROCm"
+                            }
+                        }
+                    }
+                } catch {}
+            }
+        }
+        if (-not $HasROCm) {
+            try {
+                $wmiGpu = Get-WmiObject Win32_VideoController -ErrorAction SilentlyContinue |
+                    Where-Object { $_.Name -match "AMD|Radeon" } |
+                    Select-Object -First 1
+                if ($wmiGpu) { $ROCmGpuLabel = $wmiGpu.Name }
+            } catch {}
+        }
+        # ── Arch resolution: env-var override → name inference ──────────────
+        # Covers users whose amd-smi is too old to report the GFX target and
+        # who don't have hipinfo (HIP-runtime-only, common on Strix Halo / iGPU).
+        if ($HasROCm -and -not $ROCmGfxArch) {
+            # 1. Manual override: set UNSLOTH_ROCM_GFX_ARCH=gfx1151 before running.
+            if ($env:UNSLOTH_ROCM_GFX_ARCH) {
+                $ROCmGfxArch = $env:UNSLOTH_ROCM_GFX_ARCH.Trim().ToLower()
+                $ROCmGpuLabel = "AMD ROCm ($ROCmGfxArch)"
+                substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $ROCmGfxArch" "Cyan"
+            }
+            # 2. Best-effort name → arch lookup from marketing name (amd-smi / WMI).
+            elseif ($ROCmGpuLabel) {
+                $nameArchTable = @(
+                    @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4
+                    @{ P = "9070|9060";                                            A = "gfx1200" }  # RDNA 4
+                    @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";  A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
+                    @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" } # RDNA 3.5 iGPU (Strix Point)
+                    @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                       A = "gfx1100" }  # RDNA 3 desktop
+                    @{ P = "RX 7600";                                              A = "gfx1102" }  # RDNA 3
+                    @{ P = "780M|760M|740M|Phoenix";                               A = "gfx1103" }  # RDNA 3 iGPU (Phoenix)
+                )
+                foreach ($row in $nameArchTable) {
+                    if ($ROCmGpuLabel -match $row.P) {
+                        $ROCmGfxArch = $row.A
+                        $ROCmGpuLabel = "AMD ROCm ($ROCmGfxArch)"
+                        substep "gfx arch inferred from GPU name: $ROCmGfxArch" "Cyan"
+                        substep "Tip: set UNSLOTH_ROCM_GFX_ARCH=$ROCmGfxArch to skip inference next time" "Cyan"
+                        break
+                    }
+                }
+            }
+        }
+        # Capture ROCm version for wheel selection (hipconfig, then amd-smi).
+        # Run whenever the HIP SDK binary is present, not just when the device is accessible --
+        # hipconfig --version works even when hipinfo reports no ROCm device (driver issue).
+        if ($HasROCm -or $HipSdkInstalled) {
+            $hipConfigExe = Get-Command hipconfig -ErrorAction SilentlyContinue
+            if (-not $hipConfigExe) {
+                $hipRoot = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
+                if ($hipRoot) {
+                    $hipConfigCandidate = Join-Path $hipRoot "bin\hipconfig.exe"
+                    if (Test-Path $hipConfigCandidate) {
+                        $hipConfigEnvLabel = if ($env:HIP_PATH) { "HIP_PATH" } else { "ROCM_PATH" }
+                        Write-Host "  [WARN] hipconfig not on PATH -- located via ${hipConfigEnvLabel}: $hipConfigCandidate" -ForegroundColor Yellow
+                        $hipConfigExe = [PSCustomObject]@{ Source = $hipConfigCandidate }
+                    }
+                }
+            }
+            if ($hipConfigExe) {
+                try {
+                    $hipVerOut = & $hipConfigExe.Source --version 2>&1 | Out-String
+                    if ($LASTEXITCODE -eq 0) {
+                        $hipVerLine = ($hipVerOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1).Trim()
+                        if ($hipVerLine -match '(\d+\.\d+)') {
+                            $ROCmVersion     = $Matches[1]
+                            $ROCmVersionFull = $hipVerLine
+                        }
+                    }
+                } catch {}
+            }
+            if (-not $ROCmVersion) {
+                $amdSmiVer = Get-Command "amd-smi" -ErrorAction SilentlyContinue
+                if ($amdSmiVer) {
+                    try {
+                        $smiVerOut = & $amdSmiVer.Source version 2>&1 | Out-String
+                        if ($LASTEXITCODE -eq 0 -and $smiVerOut -match 'ROCm version:\s*(\d+\.\d+)') {
+                            $ROCmVersion = $Matches[1]
+                        }
+                    } catch {}
+                }
+            }
+        }
+    }
+
     if ($HasNvidiaSmi) {
         step "gpu" "NVIDIA GPU detected"
+    } elseif ($HasROCm) {
+        step "gpu" $ROCmGpuLabel
+        $hipSdkPath = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { "on system PATH" }
+        substep "HIP SDK: $hipSdkPath"
+        if ($ROCmVersionFull) { substep "hipconfig: $ROCmVersionFull" }
+    } elseif ($HipSdkInstalled -and $ROCmGpuLabel) {
+        # HIP SDK is installed but ROCm can't see the device (driver issue, not SDK issue)
+        $sdkVer = if ($ROCmVersionFull) { " (HIP $ROCmVersionFull)" } else { "" }
+        step "gpu" "AMD GPU detected -- not ROCm-accessible$sdkVer" "Yellow"
+        substep "Detected: $ROCmGpuLabel" "Yellow"
+        substep "[WARN] HIP SDK is installed but hipinfo reports no ROCm-capable device." "Yellow"
+        substep "       This is a driver issue, not an SDK issue." "Yellow"
+        substep "       Ensure the ROCm compute driver is installed alongside the display driver:" "Yellow"
+        substep "       https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+    } elseif ($ROCmGpuLabel) {
+        step "gpu" "AMD GPU detected -- HIP SDK not found" "Yellow"
+        substep "Detected: $ROCmGpuLabel" "Yellow"
+        substep "Install the HIP SDK for ROCm GPU inference:" "Yellow"
+        substep "https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
     } else {
         step "gpu" "none (chat-only / GGUF)" "Yellow"
-        substep "Training and GPU inference require an NVIDIA GPU with drivers installed." "Yellow"
+        substep "Training and GPU inference require an NVIDIA or AMD ROCm GPU." "Yellow"
     }
 
     # ── Choose the correct PyTorch index URL based on driver CUDA version ──
@@ -1270,14 +1456,73 @@ shell.Run cmd, 0, False
         return "$baseUrl/cu126"
     }
     $TorchIndexUrl = Get-TorchIndexUrl
-    $TorchIndexFamily = Get-TauriTorchIndexFamily $TorchIndexUrl
+
+    # ── GPU arch → newest compatible Windows ROCm wheel release ──
+    # Wheels bundle their own ROCm runtime; the installed HIP SDK version does
+    # not constrain which release to use.  Always picks the newest release that
+    # supports the GPU architecture.
+    # ── AMD Windows ROCm: arch-aware pip index (repo.amd.com) ──
+    # Wheels bundle their own ROCm runtime and support all Python versions.
+    # Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped / mirror installs.
+    $ROCmIndexUrl = $null
+    $ROCmTorchFloor = $null
+    if ($HasROCm -and $TorchIndexUrl -like "*/cpu" -and -not $SkipTorch) {
+        $amdIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl" }
+        $archFamilyMap = @{
+            "gfx1201" = "gfx120X-all"; "gfx1200" = "gfx120X-all"  # RDNA 4
+            "gfx1151" = "gfx1151";     "gfx1150" = "gfx1150"       # RDNA 3.5 (Strix Halo/Point)
+            "gfx1103" = "gfx110X-all"; "gfx1102" = "gfx110X-all"   # RDNA 3
+            "gfx1101" = "gfx110X-all"; "gfx1100" = "gfx110X-all"
+            "gfx90a"  = "gfx90a";      "gfx908"  = "gfx908"        # MI200/MI100
+        }
+        # gfx120X (RDNA 4) and gfx1151/gfx1150 (Strix) have a null-pointer bug in
+        # torch._C._grouped_mm on torch <2.11.0 (rocm7.12 and rocm7.1 respectively).
+        # TheRock issues #5284 and #3284. Force torch>=2.11.0 so pip never resolves
+        # to the broken 2.10.0 wheels even though they exist on the AMD index.
+        # The <2.12.0 ceiling matches the Linux install_python_stack.py constraint
+        # for the same arches: AMD actively publishes new versions on their index,
+        # so without a ceiling a future 2.12.0+rocmX.Y wheel would be pulled in
+        # automatically before it has been validated on these architectures.
+        # Bump the ceiling here (and in install_python_stack.py) when 2.12.x is
+        # confirmed working on gfx120X / Strix.
+        $torchFloorMap = @{
+            "gfx1201" = "torch>=2.11.0,<2.12.0"; "gfx1200" = "torch>=2.11.0,<2.12.0"
+            "gfx1151" = "torch>=2.11.0,<2.12.0"; "gfx1150" = "torch>=2.11.0,<2.12.0"
+        }
+        $archFamily = if ($ROCmGfxArch -and $archFamilyMap.ContainsKey($ROCmGfxArch)) { $archFamilyMap[$ROCmGfxArch] } else { $null }
+        if ($archFamily) {
+            $ROCmIndexUrl = "$amdIndexBase/$archFamily/"
+            $ROCmTorchFloor = if ($ROCmGfxArch -and $torchFloorMap.ContainsKey($ROCmGfxArch)) { $torchFloorMap[$ROCmGfxArch] } else { $null }
+            $archLabel = if ($ROCmGfxArch) { $ROCmGfxArch } else { "AMD GPU" }
+            substep "$archLabel -- AMD repo.amd.com index selected" "Cyan"
+            if ($ROCmTorchFloor) {
+                substep "  enforcing $ROCmTorchFloor (known _grouped_mm bug in older wheels)" "Cyan"
+            }
+        } elseif ($ROCmGfxArch) {
+            substep "AMD GPU ($ROCmGfxArch) not in supported arch list -- falling back to CPU-only PyTorch" "Yellow"
+        } else {
+            substep "AMD GPU detected but arch unknown -- falling back to CPU-only PyTorch" "Yellow"
+        }
+    }
+
+    if ($ROCmIndexUrl) {
+        $TorchIndexFamily = "rocm"
+    } else {
+        $TorchIndexFamily = Get-TauriTorchIndexFamily $TorchIndexUrl
+    }
     $GpuBranch = Get-TauriGpuBranch $TorchIndexFamily
     Write-TauriDiag -GpuBranch $GpuBranch -TorchIndexFamily $TorchIndexFamily -PythonVersionForDiag $DetectedPython.Version
 
     # ── Print CPU-only hint when no GPU detected ──
-    if (-not $SkipTorch -and $TorchIndexUrl -like "*/cpu") {
+    if (-not $SkipTorch -and -not $ROCmIndexUrl -and $TorchIndexUrl -like "*/cpu") {
         Write-Host ""
-        substep "No NVIDIA GPU detected." "Yellow"
+        if ($HipSdkInstalled -and -not $HasROCm) {
+            substep "Installing CPU-only PyTorch (HIP SDK found but GPU not ROCm-accessible)." "Yellow"
+        } elseif ($ROCmGpuLabel) {
+            substep "Installing CPU-only PyTorch (ROCm wheels require the HIP SDK)." "Yellow"
+        } else {
+            substep "No NVIDIA GPU detected." "Yellow"
+        }
         substep "Installing CPU-only PyTorch. If you only need GGUF chat/inference," "Yellow"
         substep "re-run with --no-torch for a faster, lighter install:" "Yellow"
         substep ".\install.ps1 --no-torch" "Yellow"
@@ -1355,9 +1600,18 @@ shell.Run cmd, 0, False
                 return (Exit-InstallFailure "Failed to overlay unsloth-zoo (exit code $zooOverlayExit)" $zooOverlayExit)
             }
         }
-    } elseif ($TorchIndexUrl) {
+    } elseif ($TorchIndexUrl -or $ROCmIndexUrl) {
         if ($SkipTorch) {
             substep "skipping PyTorch (--no-torch flag set)." "Yellow"
+        } elseif ($ROCmIndexUrl) {
+            Write-TauriLog "STEP" "Installing PyTorch (AMD ROCm Windows)"
+            substep "installing PyTorch from $ROCmIndexUrl..."
+            $torchSpec = if ($ROCmTorchFloor) { $ROCmTorchFloor } else { "torch" }
+            $torchInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --force-reinstall --index-url $ROCmIndexUrl $torchSpec torchvision torchaudio }
+            if ($torchInstallExit -ne 0) {
+                Write-Host "[ERROR] Failed to install AMD ROCm PyTorch (exit code $torchInstallExit)" -ForegroundColor Red
+                return (Exit-InstallFailure "Failed to install AMD ROCm PyTorch (exit code $torchInstallExit)" $torchInstallExit)
+            }
         } else {
             Write-TauriLog "STEP" "Installing PyTorch"
             substep "installing PyTorch ($TorchIndexUrl)..."
diff --git a/install.sh b/install.sh
index a3b76a3011..91fdad8fb4 100755
--- a/install.sh
+++ b/install.sh
@@ -183,10 +183,21 @@ _install_bnb_rocm() {
     fi
     if [ -n "$_bnb_whl_url" ]; then
         substep "installing bitsandbytes for AMD ROCm (pre-release, PR #1887)..."
-        if run_install_cmd "$_label (pre-release)" "$_venv_py" -m pip install \
-            --force-reinstall --no-cache-dir --no-deps "$_bnb_whl_url"; then
+        _bnb_log=$(mktemp)
+        if "$_venv_py" -m pip install \
+            --disable-pip-version-check \
+            --force-reinstall --no-cache-dir --no-deps \
+            --retries 8 --timeout 90 \
+            "$_bnb_whl_url" >"$_bnb_log" 2>&1; then
+            rm -f "$_bnb_log"
             return 0
         fi
+        _bnb_rc=$?
+        if _is_verbose; then
+            cat "$_bnb_log" >&2
+        fi
+        rm -f "$_bnb_log"
+        step "warning" "$_label (pre-release) failed (exit code $_bnb_rc)" "$C_WARN" >&2
         substep "[WARN] bnb pre-release install failed; falling back to PyPI (4-bit decode broken on ROCm)" "$C_WARN"
     fi
     run_install_cmd "$_label (pypi fallback)" "$_venv_py" -m pip install \
@@ -245,6 +256,9 @@ _tauri_torch_index_family() {
                 rocm[0-9]*.[0-9]*) echo "$_diag_family" ;;
                 *) echo "auto" ;;
             esac ;;
+        # AMD arch-specific index (e.g. repo.amd.com/rocm/whl/gfx1151/) --
+        # used for Strix Halo/Point where torch 2.11+rocm7.13 has the real fix.
+        *repo.amd.com/rocm/whl/gfx*|*rocm/whl/gfx*) echo "rocm7.13" ;;
         "") echo "none" ;;
         *) echo "auto" ;;
     esac
@@ -1568,16 +1582,19 @@ _find_no_torch_runtime() {
 }
 
 # ── AMD ROCm GPU detection helper ──
-# Returns 0 (true) if an actual AMD GPU is present, 1 (false) otherwise.
-# Checks rocminfo for gfx[1-9]* (excludes gfx000 CPU agent) and
-# amd-smi list for GPU data rows (excludes header-only output).
+# Returns 0 if an AMD GPU is present. Checks rocminfo, amd-smi, then sysfs
+# KFD topology (env-var-independent fallback for when HIP/ROCR_VISIBLE_DEVICES hides devices).
 _has_amd_rocm_gpu() {
     if command -v rocminfo >/dev/null 2>&1 && \
-       rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[0-9]/ && !/Name:[[:space:]]*gfx000/{found=1} END{exit !found}'; then
+       rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
         return 0
     elif command -v amd-smi >/dev/null 2>&1 && \
          amd-smi list 2>/dev/null | awk '/^GPU[[:space:]]*[:\[][[:space:]]*[0-9]/{ found=1 } END{ exit !found }'; then
         return 0
+    elif [ -e /dev/kfd ] && \
+         awk '/gpu_id/{ if ($2+0 > 0) found=1 } END{ exit !found }' \
+             /sys/class/kfd/kfd/topology/nodes/*/properties 2>/dev/null; then
+        return 0
     fi
     return 1
 }
@@ -1656,31 +1673,39 @@ get_torch_index_url() {
         if [ -n "$_rocm_tag" ]; then
             # Minimum supported: ROCm 6.0 (no PyTorch wheels exist for older)
             case "$_rocm_tag" in
-                rocm[1-5].*) echo "$_base/cpu"; return ;;
+                rocm[1-5].*)
+                    echo "[WARN] ROCm $_rocm_tag detected but PyTorch ROCm wheels require ROCm 6.0+ -- falling back to CPU-only PyTorch" >&2
+                    echo "[WARN] Upgrade ROCm: https://rocm.docs.amd.com/en/latest/deploy/linux/index.html" >&2
+                    echo "$_base/cpu"; return ;;
             esac
-            # ROCm 7.2 only has torch 2.11.0 which exceeds current bounds
-            # (<2.11.0).  Fall back to rocm7.1 index which has torch 2.10.0.
-            # Enumerate explicit versions rather than matching rocm6.* so
-            # a host on ROCm 6.5 or 6.6 (no PyTorch wheels published) is
-            # clipped down to the last supported 6.x (rocm6.4) instead of
-            # constructing https://download.pytorch.org/whl/rocm6.5 which
-            # returns HTTP 403. PyTorch only ships: rocm5.7, 6.0, 6.1, 6.2,
-            # 6.3, 6.4, 7.0, 7.1, 7.2 (and 5.7 is below our minimum).
-            # TODO: uncomment rocm7.2 when the torch upper bound is bumped
-            # to >=2.11.0.
+            # Supported tags; 6.5+ clips to rocm6.4, 7.3+ caps to rocm7.2.
+            # PyTorch publishes major.minor URLs only (no patch level), so
+            # rocm7.2.1 / rocm6.0.2 / etc. must normalise to rocm7.2 / rocm6.0.
             case "$_rocm_tag" in
-                rocm6.0|rocm6.0.*|rocm6.1|rocm6.1.*|rocm6.2|rocm6.2.*|rocm6.3|rocm6.3.*|rocm6.4|rocm6.4.*|rocm7.0|rocm7.0.*|rocm7.1|rocm7.1.*)
-                    echo "$_base/$_rocm_tag" ;;
+                rocm6.0|rocm6.0.*) echo "$_base/rocm6.0" ;;
+                rocm6.1|rocm6.1.*) echo "$_base/rocm6.1" ;;
+                rocm6.2|rocm6.2.*) echo "$_base/rocm6.2" ;;
+                rocm6.3|rocm6.3.*) echo "$_base/rocm6.3" ;;
+                rocm6.4|rocm6.4.*) echo "$_base/rocm6.4" ;;
+                rocm7.0|rocm7.0.*) echo "$_base/rocm7.0" ;;
+                rocm7.1|rocm7.1.*) echo "$_base/rocm7.1" ;;
+                rocm7.2|rocm7.2.*) echo "$_base/rocm7.2" ;;
                 rocm6.*)
                     # ROCm 6.5+ (no published PyTorch wheels): clip down
                     # to the last supported 6.x wheel set.
                     echo "$_base/rocm6.4" ;;
                 *)
-                    # ROCm 7.2+ (including future 10.x+): cap to rocm7.1
-                    echo "$_base/rocm7.1" ;;
+                    # ROCm 7.3+ (future): cap to rocm7.2 (latest known)
+                    echo "$_base/rocm7.2" ;;
             esac
             return
         fi
+        # AMD GPU confirmed by rocminfo/amd-smi but ROCm version could not be
+        # read from any source (amd-smi, /opt/rocm/.info/version, hipconfig,
+        # dpkg, rpm).  Warn explicitly rather than silently installing CPU PyTorch.
+        echo "[WARN] AMD GPU detected but ROCm version could not be determined -- falling back to CPU-only PyTorch" >&2
+        echo "[WARN] Ensure one of the following is accessible: amd-smi, hipconfig, /opt/rocm/.info/version, rocm-core package" >&2
+        echo "[WARN] To install ROCm: https://rocm.docs.amd.com/en/latest/deploy/linux/index.html" >&2
         echo "$_base/cpu"; return
     fi
     # Parse CUDA version from nvidia-smi output (POSIX-safe, no grep -P).
@@ -1822,6 +1847,12 @@ _pick_radeon_wheel() {
 
 TORCH_INDEX_URL=$(get_torch_index_url)
 
+# rocm7.2 ships torch 2.11.0 -- adjust the constraint to allow it.
+# All other ROCm tags and CUDA stay within <2.11.0.
+case "$TORCH_INDEX_URL" in
+    */rocm7.2) TORCH_CONSTRAINT="torch>=2.11.0,<2.12.0" ;;
+esac
+
 # Auto-detect GPU for AMD ROCm based
 # get_torch_index_url must have chosen */rocm*
 # (gfx in rocminfo or amd-smi list). Then require rocminfo "Marketing Name:.*Radeon".
@@ -1834,6 +1865,78 @@ case "$TORCH_INDEX_URL" in
         fi
         ;;
 esac
+# ── Strix Halo / Strix Point: force rocm7.2 wheels, bypass Radeon repo ───────
+# gfx1151 (Strix Halo) and gfx1150 (Strix Point) have a ROCm 7.1 driver bug
+# that causes a segfault in torch._grouped_mm (moe_utils.py line 167).
+# The Radeon repo now ships cp313 wheels for rocm-rel-7.1, so when
+# _amd_gpu_radeon=true the installer silently lands on the broken combo.
+# Detect these GPUs when TORCH_INDEX_URL is rocm7.1 and override to rocm7.2.
+case "$TORCH_INDEX_URL" in
+    */rocm7.1|*/rocm7.1.*)
+        # Collect every gfx token in rocminfo / amd-smi enumeration order
+        # (skip duplicates), then index by HIP_VISIBLE_DEVICES /
+        # ROCR_VISIBLE_DEVICES so a mixed Strix iGPU + non-Strix dGPU box
+        # where the user selected the dGPU does NOT get rerouted to the
+        # Strix per-gfx index.
+        _gfx_all=""
+        if command -v rocminfo >/dev/null 2>&1; then
+            _gfx_all=$(rocminfo 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}')
+        fi
+        if [ -z "$_gfx_all" ] && command -v amd-smi >/dev/null 2>&1; then
+            _gfx_all=$(amd-smi list 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}')
+            # PowerShell paths also probe `amd-smi static --asic`; mirror it
+            # so a host with hipinfo-less amd-smi reports the gfx target.
+            if [ -z "$_gfx_all" ]; then
+                _gfx_all=$(amd-smi static --asic 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}')
+            fi
+        fi
+        _runtime_gfx=""
+        if [ -n "$_gfx_all" ]; then
+            _vis="${HIP_VISIBLE_DEVICES:-${ROCR_VISIBLE_DEVICES:-}}"
+            _idx=0
+            if [ -n "$_vis" ] && [ "$_vis" != "-1" ]; then
+                _first=${_vis%%,*}
+                case "$_first" in
+                    ''|*[!0-9]*) _idx=0 ;;
+                    *) _idx=$_first ;;
+                esac
+            fi
+            _runtime_gfx=$(printf '%s\n' "$_gfx_all" | awk -v idx="$_idx" '
+                NF && !seen[$0]++ { vals[n++] = $0 }
+                END {
+                    if (idx < 0 || idx >= n) idx = 0
+                    if (n > 0) print vals[idx]
+                }')
+        fi
+        _strix_gfx=""
+        case "$_runtime_gfx" in
+            gfx1151|gfx1150) _strix_gfx="$_runtime_gfx" ;;
+        esac
+        if [ -n "$_strix_gfx" ]; then
+            echo "" >&2
+            echo "  [WARN] $_strix_gfx (Strix) + ROCm 7.1 detected -- known _grouped_mm segfault" >&2
+            echo "  [WARN] ROCm 7.1 wheels are broken for gfx1150/gfx1151 (moe_utils.py:167)" >&2
+            echo "  [WARN] Routing to AMD arch-specific index (torch 2.11+rocm7.13 has the real fix)" >&2
+            echo "  [WARN] Upgrade ROCm to 7.2+ to use the standard index:" >&2
+            echo "  [WARN]   https://rocm.docs.amd.com/en/latest/deploy/linux/index.html" >&2
+            echo "" >&2
+            # AMD's arch-specific index serves torch 2.11.0+rocm7.13.0 which has AMD's
+            # actual fix for the gfx1151/gfx1150 _grouped_mm kernel bug -- preferred
+            # over the pytorch.org rocm7.2 fallback because it exercises the real GPU
+            # kernel path. Set UNSLOTH_AMD_ROCM_MIRROR to override for air-gapped installs.
+            _amd_strix_base="${UNSLOTH_AMD_ROCM_MIRROR:-https://repo.amd.com/rocm/whl}"
+            # Strip ALL trailing slashes to match Python's .rstrip("/") -- a
+            # double-/triple-slash mirror URL would otherwise produce 404s on
+            # strict pip proxies (artifactory, sonatype).
+            while [ "${_amd_strix_base%/}" != "$_amd_strix_base" ]; do
+                _amd_strix_base="${_amd_strix_base%/}"
+            done
+            TORCH_INDEX_URL="${_amd_strix_base}/${_strix_gfx}/"
+            TORCH_CONSTRAINT="torch>=2.11.0,<2.12.0"
+            _amd_gpu_radeon=false
+        fi
+        ;;
+esac
 _TAURI_TORCH_INDEX_FAMILY=$(_tauri_torch_index_family "$TORCH_INDEX_URL")
 if [ "$_amd_gpu_radeon" = true ] && [ "$SKIP_TORCH" = false ]; then
     _TAURI_TORCH_INDEX_FAMILY="radeon"
@@ -1841,27 +1944,93 @@ fi
 _TAURI_GPU_BRANCH=$(_tauri_gpu_branch "$_TAURI_TORCH_INDEX_FAMILY" "$_amd_gpu_radeon")
 tauri_diag_marker "$_TAURI_GPU_BRANCH" "$_TAURI_TORCH_INDEX_FAMILY"
 
-# ── Print CPU-only hint when no GPU detected ──
+# ── GPU detection summary (mirrors install.ps1 step "gpu" block) ──
+if _has_usable_nvidia_gpu; then
+    step "gpu" "NVIDIA GPU detected"
+elif case "$TORCH_INDEX_URL" in */rocm*|*/gfx*) true ;; *) false ;; esac; then
+    # Probe gfx arch for the display label, honouring HIP_VISIBLE_DEVICES
+    _gpu_disp_gfx_all=""
+    _gpu_disp_mkt=""
+    if command -v rocminfo >/dev/null 2>&1; then
+        _gpu_disp_gfx_all=$(rocminfo 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+        _gpu_disp_mkt=$(rocminfo 2>/dev/null | awk -F': ' \
+            '/Marketing Name:/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+    fi
+    if [ -z "$_gpu_disp_gfx_all" ] && command -v amd-smi >/dev/null 2>&1; then
+        _gpu_disp_gfx_all=$(amd-smi list 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+        [ -z "$_gpu_disp_gfx_all" ] && \
+            _gpu_disp_gfx_all=$(amd-smi static --asic 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+    fi
+    if [ -z "$_gpu_disp_mkt" ] && command -v amd-smi >/dev/null 2>&1; then
+        _gpu_disp_mkt=$(amd-smi static --asic 2>/dev/null | awk -F'[:|]' \
+            '/[Mm]arket.?[Nn]ame/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+    fi
+    _gpu_vis="${HIP_VISIBLE_DEVICES:-${ROCR_VISIBLE_DEVICES:-}}"
+    _gpu_vis_idx=0
+    if [ -n "$_gpu_vis" ] && [ "$_gpu_vis" != "-1" ]; then
+        _gpu_first="${_gpu_vis%%,*}"
+        case "$_gpu_first" in ''|*[!0-9]*) ;; *) _gpu_vis_idx=$_gpu_first ;; esac
+    fi
+    _gpu_disp_gfx=$(printf '%s\n' "$_gpu_disp_gfx_all" | awk -v idx="$_gpu_vis_idx" \
+        'NF && !seen[$0]++ { a[n++]=$0 } END { if(idx>=n) idx=0; if(n>0) print a[idx] }')
+    # UNSLOTH_ROCM_GFX_ARCH env override (mirrors install.ps1)
+    if [ -n "${UNSLOTH_ROCM_GFX_ARCH:-}" ]; then
+        _gpu_disp_gfx="${UNSLOTH_ROCM_GFX_ARCH}"
+        substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $_gpu_disp_gfx"
+    # Name-based arch inference when tools don't report gfx (mirrors install.ps1 nameArchTable)
+    elif [ -z "$_gpu_disp_gfx" ] && [ -n "$_gpu_disp_mkt" ]; then
+        case "$_gpu_disp_mkt" in
+            *"9070 XT"*|*9080*)                                                     _gpu_disp_gfx="gfx1201" ;;  # RDNA 4
+            *9070*|*9060*)                                                          _gpu_disp_gfx="gfx1200" ;;  # RDNA 4
+            *"8060S"*|*"890M"*|*"Strix Halo"*|*"HX 37"*|*"HX 38"*|*"AI 9 HX"*)  _gpu_disp_gfx="gfx1151" ;;  # RDNA 3.5 iGPU
+            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)        _gpu_disp_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
+            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                  _gpu_disp_gfx="gfx1100" ;;  # RDNA 3 desktop
+            *"RX 7600"*)                                                           _gpu_disp_gfx="gfx1102" ;;  # RDNA 3
+            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                               _gpu_disp_gfx="gfx1103" ;;  # RDNA 3 iGPU
+        esac
+        if [ -n "$_gpu_disp_gfx" ]; then
+            substep "gfx arch inferred from GPU name: $_gpu_disp_gfx"
+            substep "Tip: set UNSLOTH_ROCM_GFX_ARCH=$_gpu_disp_gfx to skip inference next time"
+        fi
+    fi
+    # ROCm version via hipconfig, then amd-smi
+    _gpu_rocm_ver=""
+    if command -v hipconfig >/dev/null 2>&1; then
+        _gpu_rocm_ver=$(hipconfig --version 2>/dev/null | awk 'NR==1 && /^[0-9]/{print; exit}' || true)
+    fi
+    if [ -z "$_gpu_rocm_ver" ] && command -v amd-smi >/dev/null 2>&1; then
+        _gpu_rocm_ver=$(amd-smi version 2>/dev/null | awk -F'ROCm version: ' \
+            'NF>1{gsub(/[[:space:]]/,"", $2); print $2; exit}' || true)
+    fi
+    if [ -n "$_gpu_disp_gfx" ]; then
+        step "gpu" "AMD ROCm ($_gpu_disp_gfx)"
+    else
+        step "gpu" "AMD ROCm"
+    fi
+    _rocm_root="${ROCM_PATH:-${HIP_PATH:-/opt/rocm}}"
+    substep "ROCm: $_rocm_root"
+    [ -n "$_gpu_rocm_ver" ] && substep "hipconfig: $_gpu_rocm_ver"
+    [ -n "$_gpu_disp_mkt" ] && [ -n "$_gpu_disp_gfx" ] && substep "GPU: $_gpu_disp_mkt"
+else
+    step "gpu" "none (CPU-only)" "$C_WARN"
+fi
+
+# ── PyTorch wheel index note ──
 case "$TORCH_INDEX_URL" in
     */cpu)
         if [ "$SKIP_TORCH" = false ] && [ "$OS" != "macos" ]; then
-            echo ""
-            echo "  NOTE: No GPU detected (nvidia-smi and ROCm not found)."
-            echo "  Installing CPU-only PyTorch. If you only need GGUF chat/inference,"
-            echo "  re-run with --no-torch for a faster, lighter install:"
-            echo "    curl -fsSL https://unsloth.ai/install.sh | sh -s -- --no-torch"
-            echo "  AMD ROCm users: see https://docs.unsloth.ai/get-started/install-and-update/amd"
-            echo ""
+            substep "No GPU detected -- installing CPU-only PyTorch." "$C_WARN"
+            substep "AMD ROCm users: see https://docs.unsloth.ai/get-started/install-and-update/amd"
+            substep "Re-run with --no-torch for GGUF-only (faster, no PyTorch):"
+            substep "  curl -fsSL https://unsloth.ai/install.sh | sh -s -- --no-torch"
         fi
         ;;
-    */rocm*)
-        echo ""
+    */rocm*|*/gfx*)
         if [ "$_amd_gpu_radeon" = true ]; then
-            echo "  AMD Radeon + ROCm detected -- installing PyTorch wheels from repo.radeon.com"
+            substep "wheels: repo.radeon.com (Radeon)"
         else
-            echo "  AMD ROCm detected -- installing ROCm-enabled PyTorch ($TORCH_INDEX_URL)"
+            substep "wheels: $TORCH_INDEX_URL"
         fi
-        echo ""
         ;;
 esac
 
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index f77b1966c4..77205bc298 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -439,6 +439,103 @@ def run_export_process(
                 'Install for better performance: pip install "triton-windows<3.7"'
             )
 
+    # ── 1c. Stub torchao on Windows ROCm ──
+    # torchao (pulled in by transformers.quantizers) imports
+    # torch.distributed._functional_collectives at module level, which imports
+    # distributed_c10d.py unconditionally — that file crashes on Windows ROCm
+    # because torch._C._distributed_c10d (the RCCL backend) is absent.
+    # Stubbing torchao short-circuits the crash entirely.
+    # Must run before any import of transformers / unsloth_zoo.
+    import types as _types
+    import importlib.machinery as _ilm
+    import importlib.abc as _ilabc
+
+    _STUB_SENTINEL = object()
+
+    class _StubTypeMeta(type):
+        def __instancecheck__(cls, instance):
+            return False
+
+        def __subclasscheck__(cls, subclass):
+            return False
+
+        def __getattr__(cls, attr):
+            if attr.startswith("__"):
+                raise AttributeError(attr)
+            child = _StubTypeMeta(attr, (), {})
+            setattr(cls, attr, child)
+            return child
+
+        def __call__(cls, *args, **kwargs):
+            return None
+
+    def _make_stub_type(name):
+        return _StubTypeMeta(name, (), {})
+
+    def _make_mod_stub(mod_name):
+        m = _types.ModuleType(mod_name)
+        m.__path__ = []
+        m.__package__ = mod_name
+        m._unsloth_stub = _STUB_SENTINEL
+        m.__spec__ = _ilm.ModuleSpec(mod_name, loader = None, is_package = True)
+
+        def _ga(attr, _m = m, _n = mod_name):
+            if attr.startswith("__"):
+                raise AttributeError(attr)
+            child = _make_stub_type(f"{_n}.{attr}")
+            setattr(_m, attr, child)
+            return child
+
+        m.__getattr__ = _ga
+        return m
+
+    class _StubSubpackageLoader(_ilabc.Loader):
+        def __init__(self, mod_name):
+            self._mod_name = mod_name
+
+        def create_module(self, spec):
+            return _make_mod_stub(self._mod_name)
+
+        def exec_module(self, module):
+            pass
+
+    class _StubSubpackageFinder(_ilabc.MetaPathFinder):
+        def find_spec(self, fullname, path, target = None):
+            if "." not in fullname:
+                return None
+            parent = sys.modules.get(fullname.rsplit(".", 1)[0])
+            if parent is None:
+                return None
+            if getattr(parent, "_unsloth_stub", None) is not _STUB_SENTINEL:
+                return None
+            return _ilm.ModuleSpec(
+                fullname, _StubSubpackageLoader(fullname), is_package = True
+            )
+
+    _is_win32_rocm = False
+    if sys.platform == "win32":
+        try:
+            import torch as _torch_probe
+
+            _is_win32_rocm = bool(
+                getattr(getattr(_torch_probe, "version", None), "hip", None)
+                or "rocm" in getattr(_torch_probe, "__version__", "").lower()
+            )
+            del _torch_probe
+        except Exception:
+            pass
+    if _is_win32_rocm:
+        sys.meta_path.append(_StubSubpackageFinder())
+        for _tao_name in (
+            "torchao",
+            "torchao.quantization",
+            "torchao.dtypes",
+            "torchao.float8",
+            "torchao.utils",
+        ):
+            if _tao_name not in sys.modules:
+                sys.modules[_tao_name] = _make_mod_stub(_tao_name)
+
     # ── 2. Import ML libraries (fresh in this clean process) ──
     try:
         _send_response(
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 2d95112d6d..83c4b4f4da 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -1238,6 +1238,33 @@ class LlamaCppBackend:
 
         return total
 
+    @staticmethod
+    def _amd_apu_wants_unified_memory() -> bool:
+        """True only for AMD unified-memory APUs (gfx1150/gfx1151), where
+        GGML_CUDA_ENABLE_UNIFIED_MEMORY lets llama.cpp use shared system RAM.
+        False for discrete AMD, NVIDIA, CPU and macOS (the env hurts discrete
+        GPUs). ROCm reuses torch.cuda.*; the gcnArchName suffix is stripped."""
+        try:
+            import torch
+
+            if getattr(torch.version, "hip", None) is None:
+                return False
+            if not (hasattr(torch, "cuda") and torch.cuda.is_available()):
+                return False
+            for _i in range(torch.cuda.device_count()):
+                try:
+                    _arch = (
+                        getattr(torch.cuda.get_device_properties(_i), "gcnArchName", "")
+                        or ""
+                    )
+                except Exception:
+                    continue
+                if _arch.split(":")[0].strip().lower() in {"gfx1150", "gfx1151"}:
+                    return True
+        except Exception:
+            return False
+        return False
+
     @staticmethod
     def _get_gpu_free_memory() -> list[tuple[int, int]]:
         """Query free memory per GPU.
@@ -3158,6 +3185,14 @@ class LlamaCppBackend:
                 env = child_env_without_native_path_secret()
                 binary_dir = str(Path(binary).parent)
 
+                # AMD unified-memory APUs (gfx1150/gfx1151): let llama.cpp use
+                # shared system RAM. setdefault so a user value wins.
+                if self._amd_apu_wants_unified_memory():
+                    env.setdefault("GGML_CUDA_ENABLE_UNIFIED_MEMORY", "1")
+                    logger.info(
+                        "AMD unified-memory APU: set GGML_CUDA_ENABLE_UNIFIED_MEMORY=1"
+                    )
+
                 if sys.platform == "win32":
                     # See _build_windows_path_dirs for ordering. #5106.
                     path_dirs = self._build_windows_path_dirs(
@@ -3167,6 +3202,24 @@ class LlamaCppBackend:
                     )
                     existing_path = env.get("PATH", "")
                     env["PATH"] = ";".join(path_dirs) + ";" + existing_path
+
+                    # ROCm: the llama.cpp prebuilt bundles its own rocblas.dll
+                    # but NOT the Tensile kernel library files it needs
+                    # (rocblas/library/TensileLibrary*.dat + *.hsaco).  The
+                    # bundled DLL searches relative to its own location by
+                    # default (i.e. <binary_dir>/rocblas/library/) which does
+                    # not exist, causing a silent crash on the first GEMM.
+                    # ROCBLAS_TENSILE_LIBPATH overrides that search to point at
+                    # the ROCm installation where the kernel files actually are.
+                    _hip_path = os.environ.get(
+                        "HIP_PATH", os.environ.get("ROCM_PATH", "")
+                    )
+                    if _hip_path:
+                        _rocblas_lib = os.path.join(
+                            _hip_path, "bin", "rocblas", "library"
+                        )
+                        if os.path.isdir(_rocblas_lib):
+                            env.setdefault("ROCBLAS_TENSILE_LIBPATH", _rocblas_lib)
                 else:
                     # Linux: set LD_LIBRARY_PATH for shared libs next to the binary
                     # and CUDA runtime libs (libcudart, libcublas, etc.)
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index b9643cac6a..f1faaee4fb 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -42,7 +42,10 @@ from utils.hardware import (
     get_visible_gpu_count,
 )
 
-torch._dynamo.config.recompile_limit = 64
+# recompile_limit was removed in some ROCm torch builds (e.g. pytorch.org/whl/rocm6.2).
+# Guard so training doesn't crash on RDNA2/RDNA3 with older ROCm torch wheels.
+if hasattr(torch._dynamo.config, "recompile_limit"):
+    torch._dynamo.config.recompile_limit = 64
 from unsloth import FastLanguageModel, FastVisionModel, is_bfloat16_supported
 from unsloth.chat_templates import get_chat_template
 
@@ -657,6 +660,15 @@ class UnslothTrainer:
                 f"Using device_map='{device_map}' ({get_visible_gpu_count()} GPU(s) visible)"
             )
 
+            # On hardware without native bfloat16 support (e.g. RDNA2 / gfx103x),
+            # passing dtype=None lets unsloth auto-detect and incorrectly choose
+            # bf16, triggering an LLVM error at the first bf16 kernel dispatch.
+            # Explicitly pass float16 as the fallback so unsloth never reaches
+            # that path. Modern NVIDIA (Ampere+) and RDNA3+ return True here so
+            # they are unaffected — dtype stays None and unsloth picks bf16 as
+            # before.
+            _auto_dtype = None if is_bfloat16_supported() else torch.float16
+
             # Branch based on model type
             if self._audio_type == "csm":
                 # CSM: FastModel + auto_model=CsmForConditionalGeneration + load_in_4bit=False
@@ -666,7 +678,7 @@ class UnslothTrainer:
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
-                    dtype = None,
+                    dtype = _auto_dtype,
                     auto_model = CsmForConditionalGeneration,
                     load_in_4bit = False,
                     device_map = device_map,
@@ -683,7 +695,7 @@ class UnslothTrainer:
 
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name = model_name,
-                    dtype = None,
+                    dtype = _auto_dtype,
                     load_in_4bit = False,
                     device_map = device_map,
                     full_finetuning = full_finetuning,
@@ -705,7 +717,7 @@ class UnslothTrainer:
                 self.model, self.tokenizer = FastLanguageModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
-                    dtype = None,
+                    dtype = _auto_dtype,
                     load_in_4bit = load_in_4bit,
                     device_map = device_map,
                     full_finetuning = full_finetuning,
@@ -777,7 +789,7 @@ class UnslothTrainer:
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
-                    dtype = None,
+                    dtype = _auto_dtype,
                     load_in_4bit = load_in_4bit,
                     device_map = device_map,
                     full_finetuning = full_finetuning,
@@ -791,7 +803,7 @@ class UnslothTrainer:
                 self.model, self.tokenizer = FastVisionModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
-                    dtype = None,  # Auto-detect
+                    dtype = _auto_dtype,
                     load_in_4bit = load_in_4bit,
                     device_map = device_map,
                     full_finetuning = full_finetuning,
@@ -824,7 +836,7 @@ class UnslothTrainer:
                 self.model, self.tokenizer = FastLanguageModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
-                    dtype = None,  # Auto-detect
+                    dtype = _auto_dtype,
                     load_in_4bit = load_in_4bit,
                     device_map = device_map,
                     full_finetuning = full_finetuning,
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 632b38d75a..a59def8751 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -70,6 +70,58 @@ _TILELANG_INSTALL_TIMEOUT_S = 600
 _TVM_FFI_BROKEN_VERSIONS = ("0.1.10", "0.1.11")
 _FAST_PATH_HOOKS_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS"
 
+# Module-level handle so the torch.library.Library registration survives past
+# run_training_process() and is not garbage collected mid-run.
+_WINDOWS_ROCM_GROUPED_MM_LIB = None
+
+# Worker subprocesses inherit the parent env but not the parent's
+# os.add_dll_directory registrations. Replicate main.py's Windows ROCm DLL
+# setup at module load so the first `import torch` can find amdhip64.dll even
+# when HIP_PATH\bin is not on the system PATH. Handles retained at module
+# scope so they are not garbage collected.
+_ROCM_DLL_HANDLES: list = []
+if sys.platform == "win32":
+
+    def _add_rocm_dll_dirs_worker() -> None:
+        _candidates: list[str] = []
+        for _var in ("HIP_PATH", "ROCM_PATH"):
+            _val = os.environ.get(_var)
+            if _val:
+                _candidates.append(os.path.join(_val, "bin"))
+        _default_root = os.path.join(
+            os.environ.get("ProgramFiles", r"C:\Program Files"), "AMD", "ROCm"
+        )
+
+        def _ver_key(name: str) -> tuple:
+            # Numeric tuple key so "10.0" sorts after "7.0"; non-numeric chunks fall back to string.
+            parts = []
+            for chunk in name.split("."):
+                try:
+                    parts.append((0, int(chunk)))
+                except ValueError:
+                    parts.append((1, chunk))
+            return tuple(parts)
+
+        try:
+            if os.path.isdir(_default_root):
+                for _ver in sorted(
+                    os.listdir(_default_root), key = _ver_key, reverse = True
+                ):
+                    _bin = os.path.join(_default_root, _ver, "bin")
+                    if os.path.isdir(_bin):
+                        _candidates.append(_bin)
+        except OSError:
+            pass
+        for _d in _candidates:
+            if os.path.isdir(_d):
+                try:
+                    _ROCM_DLL_HANDLES.append(os.add_dll_directory(_d))
+                except (OSError, AttributeError):
+                    pass
+
+    _add_rocm_dll_dirs_worker()
+    del _add_rocm_dll_dirs_worker
+
 
 def _model_wants_causal_conv1d(model_name: str) -> bool:
     name = model_name.lower()
@@ -320,11 +372,21 @@ def _install_package_wheel_first(
                 f"{snippet}",
             )
         else:
-            logger.error(
-                "Failed to install %s from PyPI:\n%s",
-                display_name,
-                result.stdout,
-            )
+            if sys.platform == "win32":
+                # No prebuilt wheel and no source build toolchain on Windows --
+                # this is expected for packages like causal-conv1d.  Log at
+                # info so users aren't alarmed by what looks like an error.
+                logger.info(
+                    "%s is not available on Windows (no prebuilt wheel); skipping",
+                    display_name,
+                )
+                logger.debug("Install output:\n%s", result.stdout)
+            else:
+                logger.error(
+                    "Failed to install %s from PyPI:\n%s",
+                    display_name,
+                    result.stdout,
+                )
         return False
 
     if is_hip:
@@ -337,6 +399,9 @@ def _install_package_wheel_first(
 def _ensure_causal_conv1d_fast_path(event_queue: Any, model_name: str) -> None:
     if not _model_wants_causal_conv1d(model_name):
         return
+    if sys.platform == "win32":
+        logger.info("causal-conv1d: no prebuilt wheel for Windows; skipping")
+        return
 
     _install_package_wheel_first(
         event_queue = event_queue,
@@ -404,6 +469,11 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
     """Install pinned FLA + fla-core with --no-deps. Returns True iff importable post-call."""
     if os.getenv(_FLA_SKIP_ENV) == "1":
         return False
+    if sys.platform == "win32":
+        logger.info(
+            "Skipping flash-linear-attention install: no prebuilt wheel for Windows"
+        )
+        return False
     if sys.version_info < _FLA_MIN_PYTHON:
         logger.info(
             "Skipping flash-linear-attention install: requires Python >= %d.%d, have %s",
@@ -483,10 +553,17 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
         return False
 
     if result.returncode != 0:
-        logger.warning(
-            "flash-linear-attention install failed (continuing on torch fallback):\n%s",
-            result.stdout,
-        )
+        if sys.platform == "win32":
+            logger.info(
+                "flash-linear-attention not available on Windows (no prebuilt wheel); "
+                "continuing on torch fallback"
+            )
+            logger.debug("Install output:\n%s", result.stdout)
+        else:
+            logger.warning(
+                "flash-linear-attention install failed (continuing on torch fallback):\n%s",
+                result.stdout,
+            )
         _send_status(
             event_queue,
             "flash-linear-attention install failed; continuing without it",
@@ -607,15 +684,61 @@ def _tilelang_importable() -> bool:
 
 
 def _torch_has_hip() -> bool:
-    """True iff torch is a ROCm build; `torch.version.hip` is the only reliable signal on x86_64 ROCm."""
+    """True iff torch is a ROCm build.
+
+    `torch.version.hip` covers official PyTorch ROCm wheels; AMD SDK / Radeon
+    wheels can leave it unset but still encode "rocm" in `torch.__version__`.
+    """
     try:
         import torch as _torch
 
-        return getattr(_torch.version, "hip", None) is not None
+        return bool(
+            getattr(_torch.version, "hip", None)
+            or "rocm" in getattr(_torch, "__version__", "").lower()
+        )
     except Exception:
         return False
 
 
+def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
+    """Classify a ROCm device as unified-memory (APU) or discrete.
+
+    Returns ``(gcn_arch, is_unified)`` where:
+    - ``gcn_arch`` is the canonical arch string (e.g. ``"gfx1151"``) when a
+      known attribute is present, or ``""`` when all arch attrs are absent.
+    - ``is_unified`` is ``True`` for AMD APUs with a shared GPU/system-RAM pool
+      (gfx1150 Strix Point, gfx1151 Strix Halo) — these need a lower
+      ``set_per_process_memory_fraction`` cap to leave headroom for the OS.
+
+    Classification priority:
+    1. ``gcnArchName`` / variant spellings (stable, naming-independent).
+    2. Device-name substring match as a last-resort fallback when all arch
+       attrs are absent (AMD SDK / Radeon wheels may not populate them):
+         - gfx1150 Strix Point: ``Radeon 890M``, ``Radeon 880M``
+         - gfx1151 Strix Halo:  ``Radeon 8060S`` (Ryzen AI MAX+ 395),
+                                ``Radeon 8050S`` (cut-down SKU)
+    """
+    gcn_arch = ""
+    for _attr in ("gcnArchName", "gcn_arch_name", "arch_name", "gfx_arch_name"):
+        _v = (getattr(props, _attr, "") or "").split(":")[0].strip()
+        if _v:
+            gcn_arch = _v
+            break
+
+    if gcn_arch:
+        return gcn_arch, gcn_arch in {"gfx1150", "gfx1151"}
+
+    # Arch attrs absent — fall back to device-name matching.
+    dev_lower = (getattr(props, "name", "") or "").lower()
+    is_unified = (
+        "890m" in dev_lower
+        or "880m" in dev_lower
+        or "8060s" in dev_lower
+        or "8050s" in dev_lower
+    )
+    return gcn_arch, is_unified
+
+
 def _tilelang_platform_supported() -> bool:
     """True iff a tilelang 0.1.8 wheel will load: Linux x86_64/aarch64, non-HIP torch.
 
@@ -881,6 +1004,9 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
         _ensure_tilelang_backend_unconditional(eq)
 
     def _causal_conv1d_install(eq: Any) -> bool:
+        if sys.platform == "win32":
+            logger.info("causal-conv1d: no prebuilt wheel for Windows; skipping")
+            return False
         ok = _install_package_wheel_first(
             event_queue = eq,
             import_name = "causal_conv1d",
@@ -1893,6 +2019,452 @@ def run_training_process(
                 'Install for better performance: pip install "triton-windows<3.7"'
             )
 
+    # ── 1d. Stub torchao on Windows ROCm ──
+    # torchao (pulled in by transformers.quantizers) imports
+    # torch.distributed._functional_collectives at module level, which imports
+    # distributed_c10d.py unconditionally — that file crashes on Windows ROCm
+    # because torch._C._distributed_c10d (the RCCL backend) is absent.
+    # torch/distributed/__init__.py itself is guarded by `if is_available()`
+    # so `import torch.distributed` alone is safe; the crash only comes via
+    # torchao's import chain.  Stubbing torchao short-circuits it entirely.
+    # _StubSubpackageFinder handles any depth of torchao.xxx.yyy imports.
+    import types as _types
+    import importlib.machinery as _ilm
+    import importlib.abc as _ilabc
+
+    _STUB_SENTINEL = object()
+
+    # Metaclass for stub types so that isinstance(x, StubClass) returns False
+    # instead of raising TypeError ("arg 2 must be a type").
+    # peft/tuners/lora/torchao.py does:
+    #   from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
+    #   isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))
+    # If those names resolve to stub modules rather than types, isinstance() raises.
+    class _StubTypeMeta(type):
+        def __instancecheck__(cls, instance):
+            return False
+
+        def __subclasscheck__(cls, subclass):
+            return False
+
+        def __getattr__(cls, attr):
+            if attr.startswith("__"):
+                raise AttributeError(attr)
+            child = _StubTypeMeta(attr, (), {})
+            setattr(cls, attr, child)
+            return child
+
+        def __call__(cls, *args, **kwargs):
+            return None
+
+    def _make_stub_type(name):
+        """Stub class: accepted by isinstance() (always False), supports attr access."""
+        return _StubTypeMeta(name, (), {})
+
+    def _make_mod_stub(mod_name):
+        m = _types.ModuleType(mod_name)
+        m.__path__ = []
+        m.__package__ = mod_name
+        m._unsloth_stub = _STUB_SENTINEL
+        m.__spec__ = _ilm.ModuleSpec(mod_name, loader = None, is_package = True)
+
+        def _ga(attr, _m = m, _n = mod_name):
+            if attr.startswith("__"):
+                raise AttributeError(attr)
+            # Return a stub CLASS (not a module) so that isinstance(x, attr)
+            # works and returns False instead of raising TypeError.
+            child = _make_stub_type(f"{_n}.{attr}")
+            setattr(_m, attr, child)
+            return child
+
+        m.__getattr__ = _ga
+        return m
+
+    class _StubSubpackageLoader(_ilabc.Loader):
+        def __init__(self, mod_name):
+            self._mod_name = mod_name
+
+        def create_module(self, spec):
+            return _make_mod_stub(self._mod_name)
+
+        def exec_module(self, module):
+            pass
+
+    class _StubSubpackageFinder(_ilabc.MetaPathFinder):
+        def find_spec(self, fullname, path, target = None):
+            if "." not in fullname:
+                return None
+            parent = sys.modules.get(fullname.rsplit(".", 1)[0])
+            if parent is None:
+                return None
+            if getattr(parent, "_unsloth_stub", None) is not _STUB_SENTINEL:
+                return None
+            return _ilm.ModuleSpec(
+                fullname, _StubSubpackageLoader(fullname), is_package = True
+            )
+
+    # Only stub torchao on Windows ROCm hosts -- on Windows CUDA (NVIDIA) torchao
+    # is real and shadowing it breaks torchao-based quantization paths.
+    # Gate on the active torch runtime, not env-var presence -- HIP_PATH /
+    # ROCM_PATH stay set after a user installs the HIP SDK and reverts to a
+    # CUDA torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
+    # but still encode "rocm" in torch.__version__, so accept either.
+    _is_win32_rocm = False
+    if sys.platform == "win32":
+        try:
+            import torch as _torch_probe
+
+            _is_win32_rocm = bool(
+                getattr(getattr(_torch_probe, "version", None), "hip", None)
+                or "rocm" in getattr(_torch_probe, "__version__", "").lower()
+            )
+            del _torch_probe
+        except Exception:
+            pass
+    if _is_win32_rocm:
+        # Register the finder only on Windows ROCm -- on other platforms there
+        # are no stub modules seeded, so appending is a pure accumulation.
+        sys.meta_path.append(_StubSubpackageFinder())
+        # Seed torchao top-level + key submodules; the finder handles the rest.
+        for _tao_name in (
+            "torchao",
+            "torchao.quantization",
+            "torchao.dtypes",
+            "torchao.float8",
+            "torchao.utils",
+        ):
+            if _tao_name not in sys.modules:
+                sys.modules[_tao_name] = _make_mod_stub(_tao_name)
+
+    # ── 1e. Ensure torch.distributed helper attrs are present ──
+    # Single-GPU training never initialises the process group, so these helpers
+    # are never called — but transformers/trl import them unconditionally.
+    _td_stubs = {
+        "is_initialized": lambda: False,
+        "is_available": lambda: False,
+        "is_torchelastic_launched": lambda: False,
+        "get_rank": lambda: 0,
+        "get_world_size": lambda: 1,
+        "barrier": lambda: None,
+    }
+
+    try:
+        import torch.distributed as _td
+
+        for _name, _stub in _td_stubs.items():
+            if not hasattr(_td, _name):
+                setattr(_td, _name, _stub)
+    except Exception:
+        _td_mock = _types.ModuleType("torch.distributed")
+        for _name, _stub in _td_stubs.items():
+            setattr(_td_mock, _name, _stub)
+        sys.modules["torch.distributed"] = _td_mock
+        try:
+            import torch as _torch
+
+            _torch.distributed = _td_mock
+        except Exception:
+            pass
+
+    # ── 1f. Windows ROCm runtime patches ──
+    # torch._grouped_mm has a null HIP kernel on gfx1200 (ROCm ≤ 7.12 Windows),
+    # causing 0xC0000005 (access violation) during training.
+    #
+    # Root cause: the JitDecomp autograd decomposition system (NOT torch.compile)
+    # dispatches _grouped_mm → _fused_adagrad_ → _grouped_mm HIP → null crash.
+    # TORCHDYNAMO_DISABLE=1 stops the compiler frontend but does NOT stop
+    # JitDecomp, so we must also override the CUDA dispatch key for _grouped_mm
+    # with a safe Python fallback.
+    #
+    # Fixed in AMD's wheel: torch==2.11.0+rocm7.13.0 — the 3-D batch and grouped
+    # (with offs) variants of _grouped_mm now have working HIP kernels on gfx1200.
+    # We gate the dispatch override on HIP < 7.13 so users on the fixed wheel get
+    # the real GPU kernel rather than our Python fallback.
+    #
+    # Verified: null on torch==2.10.0+rocm7.12.0; fixed on torch==2.11.0+rocm7.13.0.
+    #
+    # Schema: _grouped_mm(Tensor self, Tensor mat2, Tensor? offs=None,
+    #                     Tensor? bias=None, ScalarType? out_dtype=None) -> Tensor
+    #   offs: optional group-split offsets (MoE-style variable-size batches)
+    #
+    # torch is already in sys.modules from section 1e's `import torch.distributed`.
+    # Module-level _WINDOWS_ROCM_GROUPED_MM_LIB keeps the registration alive past
+    # function return / mid-run GC.
+    global _WINDOWS_ROCM_GROUPED_MM_LIB
+    if sys.platform == "win32":
+        _torch_for_rocm = sys.modules.get("torch")
+        # Broad check: torch.version.hip OR "rocm" in torch.__version__.
+        # AMD SDK / Radeon Windows wheels do not always populate
+        # torch.version.hip; without the broad check the BNB version pin,
+        # dynamo-disable, and _grouped_mm fallback below silently skip
+        # (matches the torchao stub gate above and main.py).
+        _build_version_for_rocm = (
+            getattr(_torch_for_rocm, "__version__", "").lower()
+            if _torch_for_rocm is not None
+            else ""
+        )
+        _is_win_rocm_torch = bool(
+            _torch_for_rocm is not None
+            and (
+                getattr(getattr(_torch_for_rocm, "version", None), "hip", None)
+                or "rocm" in _build_version_for_rocm
+            )
+        )
+        if _is_win_rocm_torch:
+            # Disable dynamo (belt-and-suspenders; JitDecomp patch below is the
+            # real fix, but keeping dynamo off avoids any other compile paths).
+            if "TORCHDYNAMO_DISABLE" not in os.environ:
+                os.environ["TORCHDYNAMO_DISABLE"] = "1"
+                logger.info("Windows ROCm: torch.compile (dynamo) disabled")
+
+            # BNB auto-detects the HIP version from torch.version.hip and uses
+            # it to choose which DLL to load (e.g. "7.13" → rocm713.dll).
+            # AMD's Windows BNB prerelease wheel ships only one rocm DLL, and its
+            # version suffix does not always match the torch HIP version (e.g.
+            # torch==2.11.0+rocm7.13.0 ships HIP 7.13, but the BNB wheel still
+            # ships rocm72.dll).  We detect the actual DLL name from the installed
+            # package and override BNB's auto-detection.  "72" is a safe fallback
+            # if detection fails.  Callers may override by pre-setting the var.
+            if "BNB_ROCM_VERSION" not in os.environ:
+                _bnb_rocm_ver = None
+                try:
+                    import glob as _glob
+                    import importlib.util as _ilu
+                    import re as _re
+
+                    _bnb_spec = _ilu.find_spec("bitsandbytes")
+                    if _bnb_spec and _bnb_spec.submodule_search_locations:
+                        _all_vers: list[str] = []
+                        for _pkg_dir in _bnb_spec.submodule_search_locations:
+                            for _dll in _glob.glob(
+                                os.path.join(_pkg_dir, "libbitsandbytes_rocm*.dll")
+                            ):
+                                _m = _re.search(
+                                    r"libbitsandbytes_rocm(\d+)\.dll",
+                                    os.path.basename(_dll),
+                                )
+                                if _m:
+                                    _all_vers.append(_m.group(1))
+                        # Pick the highest numeric suffix so that e.g. "713"
+                        # wins over "72" when both variants are present.
+                        # Filesystem glob order is not guaranteed, so always
+                        # sort rather than stopping at the first match.
+                        if _all_vers:
+                            _bnb_rocm_ver = max(_all_vers, key = lambda v: int(v))
+                except Exception:
+                    pass
+                _bnb_rocm_ver = _bnb_rocm_ver or "72"
+                os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver
+                logger.info(
+                    "Windows ROCm: set BNB_ROCM_VERSION=%s "
+                    "(detected from installed BNB wheel; "
+                    "overrides torch.version.hip auto-detection)",
+                    _bnb_rocm_ver,
+                )
+
+            # Parse HIP version for the kernel-fix gate below.
+            # torch.version.hip can be "7.13.99004", "7.2.0", etc.
+            # AMD SDK / Radeon wheels may leave torch.version.hip unset and
+            # encode the ROCm version in torch.__version__ instead
+            # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back
+            # to that string when version.hip is missing.
+            def _hip_ver_at_least(major: int, minor: int) -> bool:
+                import re as _re_ver
+
+                _hip_str = getattr(
+                    getattr(_torch_for_rocm, "version", None), "hip", None
+                )
+                if not _hip_str:
+                    # Try the standard "+rocmX.Y.Z" embedded version first
+                    # (e.g. "2.11.0+rocm7.13.0").
+                    _ver_match = _re_ver.search(
+                        r"rocm(\d+)\.(\d+)", _build_version_for_rocm
+                    )
+                    if _ver_match:
+                        return (
+                            int(_ver_match.group(1)),
+                            int(_ver_match.group(2)),
+                        ) >= (major, minor)
+                    # AMD SDK / Radeon Windows wheels encode the build as
+                    # "+rocmsdk<date>" (e.g. "2.9.0+rocmsdk20251116") with no
+                    # explicit rocmX.Y component. The rocmsdk format was
+                    # introduced after the gfx120X null-kernel fix landed in
+                    # ROCm 7.13, so any wheel with this suffix is new enough to
+                    # have working HIP kernels. Treat as >= 7.13 rather than
+                    # falling back to False and installing the Python workaround
+                    # on a wheel that doesn't need it.
+                    if "rocmsdk" in _build_version_for_rocm:
+                        logger.debug(
+                            "Windows ROCm: AMD SDK wheel detected (%r); "
+                            "assuming HIP >= %d.%d (rocmsdk wheels post-date "
+                            "the gfx120X null-kernel fix)",
+                            _build_version_for_rocm,
+                            major,
+                            minor,
+                        )
+                        return True
+                    return False
+                try:
+                    _parts = [int(x) for x in str(_hip_str).split(".")[:2]]
+                    if len(_parts) < 2:
+                        logger.warning(
+                            "Windows ROCm: torch.version.hip %r has fewer than "
+                            "two components; cannot compare against %d.%d",
+                            _hip_str,
+                            major,
+                            minor,
+                        )
+                        return False
+                    return (_parts[0], _parts[1]) >= (major, minor)
+                except ValueError:
+                    logger.warning(
+                        "Windows ROCm: could not parse torch.version.hip %r as "
+                        "a version number; assuming HIP < %d.%d",
+                        _hip_str,
+                        major,
+                        minor,
+                    )
+                    return False
+
+            # _grouped_mm HIP kernel was null on gfx1200 in ROCm ≤ 7.12,
+            # causing 0xC0000005.  AMD fixed it in ROCm 7.13 (torch 2.11+).
+            # Only install the Python fallback on the affected versions so users
+            # on 7.13+ get the real GPU kernel for MoE workloads.
+            if not _hip_ver_at_least(7, 13):
+                try:
+                    import warnings as _warnings
+
+                    _gm_lib = _torch_for_rocm.library.Library("aten", "IMPL")
+
+                    def _grouped_mm_safe_impl(
+                        self, mat2, offs = None, bias = None, out_dtype = None
+                    ):
+                        """Python mm/bmm fallback for _grouped_mm on gfx1200 (null HIP kernel, ROCm ≤ 7.12)."""
+                        _t = _torch_for_rocm
+                        if offs is None:
+                            # No offsets: behave like the real op, which
+                            # accepts either (M, K) x (K, N) -> mm, or 3-D
+                            # batched inputs -> bmm. Picking torch.mm
+                            # unconditionally previously raised "self must be
+                            # a matrix" on 3-D MoE workloads.
+                            if self.dim() == 3 and mat2.dim() == 3:
+                                result = _t.bmm(self.contiguous(), mat2.contiguous())
+                            elif self.dim() == 3 and mat2.dim() == 2:
+                                # Broadcast 2-D mat2 across the batch dim.
+                                result = _t.matmul(self.contiguous(), mat2.contiguous())
+                            elif self.dim() == 2 and mat2.dim() == 3:
+                                # Broadcast 2-D self across batch via matmul semantics.
+                                result = _t.matmul(self.contiguous(), mat2.contiguous())
+                            else:
+                                result = _t.mm(self.contiguous(), mat2.contiguous())
+                        else:
+                            # Grouped case: offs[i] is the exclusive end-row of
+                            # group i in `self`; mat2 may be 3-D or 2-D.
+                            offs_list = offs.tolist()
+                            pieces = []
+                            prev = 0
+                            for idx, end in enumerate(offs_list):
+                                end = int(end)
+                                a_part = self[prev:end].contiguous()
+                                if mat2.dim() == 3:
+                                    b_part = mat2[idx].contiguous()
+                                else:
+                                    b_part = mat2.contiguous()
+                                pieces.append(_t.mm(a_part, b_part))
+                                prev = end
+                            # Include any trailing rows not covered by offs
+                            if prev < self.shape[0]:
+                                a_tail = self[prev:].contiguous()
+                                b_tail = (
+                                    mat2[-1].contiguous()
+                                    if mat2.dim() == 3
+                                    else mat2.contiguous()
+                                )
+                                pieces.append(_t.mm(a_tail, b_tail))
+                            result = (
+                                _t.cat(pieces, dim = 0)
+                                if pieces
+                                else _t.zeros(
+                                    0,
+                                    mat2.shape[-1],
+                                    device = self.device,
+                                    dtype = self.dtype,
+                                )
+                            )
+                        if bias is not None:
+                            result = result + bias
+                        if out_dtype is not None:
+                            result = result.to(out_dtype)
+                        elif result.dtype != self.dtype:
+                            result = result.to(self.dtype)
+                        return result
+
+                    with _warnings.catch_warnings():
+                        _warnings.simplefilter("ignore")
+                        _gm_lib.impl("_grouped_mm", _grouped_mm_safe_impl, "CUDA")
+
+                    _WINDOWS_ROCM_GROUPED_MM_LIB = _gm_lib  # prevent GC
+                    logger.info(
+                        "Windows ROCm: patched _grouped_mm CUDA dispatch "
+                        "(null HIP kernel on gfx1200, ROCm ≤ 7.12 — "
+                        "bypassed with Python mm fallback)"
+                    )
+                except Exception as _patch_exc:
+                    logger.warning(
+                        "Windows ROCm: could not patch _grouped_mm — "
+                        "training may crash with 0xC0000005: %s",
+                        _patch_exc,
+                    )
+            else:
+                logger.info(
+                    "Windows ROCm: HIP >= 7.13 — _grouped_mm kernel is functional, "
+                    "skipping Python fallback (AMD fixed gfx1200 null kernel in ROCm 7.13)"
+                )
+
+    # ── 1g. ROCm OOM guard ──
+    # On RDNA 4 (gfx1200/gfx1201) and other ROCm GPUs, exhausting VRAM can
+    # cause a HIP driver hang that freezes the entire system rather than
+    # raising a Python exception.  set_per_process_memory_fraction caps the
+    # HIP allocator so PyTorch raises OutOfMemoryError before hitting the
+    # hardware limit, giving the UI a clean error instead of a system freeze.
+    # Only applied on ROCm -- NVIDIA CUDA has a graceful OOM path and does
+    # not need this cap.
+    # Unified-memory APUs (gfx1150 Strix Point / gfx1151 Strix Halo) share GPU
+    # and system RAM in one pool: 0.90 of 128 GB starves the OS. Use 0.80 there.
+    # Primary classifier: gcnArchName from device properties — stable within a
+    # product family and naming-independent.  AMD SDK / Radeon wheels may omit
+    # gcnArchName or expose it under a variant spelling, so we try several attr
+    # names then fall back to known device-name markers as a last resort.
+    # Non-fatal: silently skipped if torch is not importable.
+    if _hw.IS_ROCM:
+        try:
+            import torch as _torch_mem
+
+            if _torch_mem.cuda.is_available():
+                # Classify unified vs discrete via _rocm_classify_unified_memory.
+                # See that function's docstring for classification priority.
+                _props = _torch_mem.cuda.get_device_properties(0)
+                _dev_name = _props.name
+                _gcn_arch, _is_unified = _rocm_classify_unified_memory(_props)
+                if _is_unified and not _gcn_arch:
+                    logger.debug(
+                        "ROCm OOM guard: gcnArchName absent -- inferred "
+                        "unified memory from device name %r; applying 0.80 cap",
+                        _dev_name,
+                    )
+                _mem_fraction = 0.80 if _is_unified else 0.90
+                _torch_mem.cuda.set_per_process_memory_fraction(_mem_fraction)
+                logger.info(
+                    "ROCm OOM guard: set_per_process_memory_fraction(%.2f) — "
+                    "%s memory host (%s, %s)",
+                    _mem_fraction,
+                    "unified" if _is_unified else "discrete",
+                    _dev_name,
+                    _gcn_arch or "unknown arch",
+                )
+        except Exception as _oom_guard_err:
+            logger.debug("Could not set GPU memory fraction: %s", _oom_guard_err)
+
     # ── 2. Now import ML libraries (fresh in this clean process) ──
     try:
         _send_status(event_queue, "Importing Unsloth...")
@@ -2347,14 +2919,38 @@ def run_training_process(
             )
 
     except Exception as exc:
-        event_queue.put(
-            {
-                "type": "error",
-                "error": str(exc),
-                "stack": traceback.format_exc(limit = 20),
-                "ts": time.time(),
-            }
+        _exc_str = str(exc).lower()
+        _is_oom = (
+            "out of memory" in _exc_str
+            or "hip out of memory" in _exc_str
+            or "cuda out of memory" in _exc_str
+            or type(exc).__name__ == "OutOfMemoryError"
         )
+        if _is_oom:
+            _oom_msg = (
+                "GPU ran out of VRAM during training.\n"
+                "To fix: reduce max_seq_length (e.g. 2048–4096), enable "
+                "gradient_checkpointing=True, lower per_device_train_batch_size, "
+                "or use a smaller model / higher quantization."
+            )
+            logger.error("Training stopped: GPU OOM — %s", exc)
+            event_queue.put(
+                {
+                    "type": "error",
+                    "error": _oom_msg,
+                    "stack": traceback.format_exc(limit = 20),
+                    "ts": time.time(),
+                }
+            )
+        else:
+            event_queue.put(
+                {
+                    "type": "error",
+                    "error": str(exc),
+                    "stack": traceback.format_exc(limit = 20),
+                    "ts": time.time(),
+                }
+            )
 
 
 def _send_status(event_queue: Any, message: str) -> None:
diff --git a/studio/backend/main.py b/studio/backend/main.py
index fbf1c31de3..be327bc5a8 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -12,6 +12,110 @@ from pathlib import Path as _Path
 # Suppress annoying C-level dependency warnings globally
 os.environ["PYTHONWARNINGS"] = "ignore"
 
+# ── Windows AMD ROCm DLL injection ──────────────────────────────────────────
+# Python 3.8+ ignores PATH for extension modules; register ROCm bin dirs with
+# os.add_dll_directory() so amdhip64.dll etc. are found before any torch import.
+if sys.platform == "win32":
+    # Retained at module scope -- os.add_dll_directory returns a handle that
+    # removes the search-path entry when garbage collected.
+    _ROCM_DLL_HANDLES: list = []
+
+    def _add_rocm_dll_dirs() -> None:
+        candidates = []
+        # 1. HIP_PATH / ROCM_PATH -- set by the AMD HIP SDK installer
+        for _var in ("HIP_PATH", "ROCM_PATH"):
+            _val = os.environ.get(_var)
+            if _val:
+                candidates.append(os.path.join(_val, "bin"))
+        # 2. Standard AMD installer location: C:\Program Files\AMD\ROCm\<ver>\bin
+        #    Scan all installed versions, newest first.
+        _default_root = os.path.join(
+            os.environ.get("ProgramFiles", r"C:\Program Files"), "AMD", "ROCm"
+        )
+
+        def _ver_key(name: str) -> tuple:
+            # Numeric tuple key so "10.0" sorts after "7.0"; non-numeric chunks fall back to string.
+            parts = []
+            for chunk in name.split("."):
+                try:
+                    parts.append((0, int(chunk)))
+                except ValueError:
+                    parts.append((1, chunk))
+            return tuple(parts)
+
+        try:
+            if os.path.isdir(_default_root):
+                for _ver in sorted(
+                    os.listdir(_default_root), key = _ver_key, reverse = True
+                ):
+                    _bin = os.path.join(_default_root, _ver, "bin")
+                    if os.path.isdir(_bin):
+                        candidates.append(_bin)
+        except OSError:
+            pass
+        for _d in candidates:
+            if os.path.isdir(_d):
+                try:
+                    _ROCM_DLL_HANDLES.append(os.add_dll_directory(_d))
+                except (OSError, AttributeError):
+                    pass
+
+    _add_rocm_dll_dirs()
+    del _add_rocm_dll_dirs
+
+    # ── Windows AMD ROCm: set BNB_ROCM_VERSION before any bitsandbytes import ─
+    # bitsandbytes on Windows ROCm tries to load libbitsandbytes_rocm<ver>.dll
+    # where <ver> comes from torch.version.hip (e.g. "7.13..." → "713").
+    # The installed BNB wheel ships rocm72.dll (not rocm713.dll), so without
+    # this the server process crashes with "Configured ROCm binary not found".
+    # Detect the available DLL, fall back to "72", and set BNB_ROCM_VERSION
+    # before any import that pulls in bitsandbytes (mirrors worker.py logic).
+    # Gate on the rocm bnb DLL (the exact file this configures) or HIP_PATH/
+    # ROCM_PATH, not on torch.version.hip: that needed importing torch on every
+    # Windows host (NVIDIA/CPU included), adding seconds to startup. Radeon
+    # wheels without HIP_PATH still ship the rocm bnb DLL, so they are covered.
+    if "BNB_ROCM_VERSION" not in os.environ:
+        import glob as _glob
+        import logging as _logging
+
+        _hip_env = bool(os.environ.get("HIP_PATH") or os.environ.get("ROCM_PATH"))
+        _bnb_rocm_ver = None
+        _found_rocm_bnb = False
+        try:
+            import importlib.util as _ilu
+
+            _bnb_spec = _ilu.find_spec("bitsandbytes")
+            # submodule_search_locations (not spec.origin) handles editable installs.
+            if _bnb_spec and _bnb_spec.submodule_search_locations:
+                import re as _re_bnb
+
+                _all_vers_main: list[str] = []
+                for _pkg_dir in _bnb_spec.submodule_search_locations:
+                    for _dll in _glob.glob(
+                        os.path.join(_pkg_dir, "libbitsandbytes_rocm*.dll")
+                    ):
+                        _found_rocm_bnb = True
+                        _km = _re_bnb.search(
+                            r"libbitsandbytes_rocm(\d+)\.dll", os.path.basename(_dll)
+                        )
+                        if _km:
+                            _all_vers_main.append(_km.group(1))
+                if _all_vers_main:
+                    _bnb_rocm_ver = max(_all_vers_main, key = lambda v: int(v))
+        except Exception as _e:
+            _logging.getLogger(__name__).warning(
+                "Windows ROCm: BNB DLL detection failed (%s); falling back to version '72'",
+                _e,
+            )
+        # rocm bnb DLL present, or HIP_PATH/ROCM_PATH set (DLL unparsable -> "72").
+        if _found_rocm_bnb or _hip_env:
+            _bnb_rocm_ver_final = _bnb_rocm_ver or "72"
+            os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver_final
+            _logging.getLogger(__name__).info(
+                "Windows ROCm: set BNB_ROCM_VERSION=%s (from installed BNB wheel)",
+                _bnb_rocm_ver_final,
+            )
+
 # Ensure backend dir is on sys.path so _platform_compat is importable when
 # main.py is launched directly (e.g. `uvicorn main:app`).
 _backend_dir = str(_Path(__file__).parent)
diff --git a/studio/backend/tests/test_amd_apu_unified_memory.py b/studio/backend/tests/test_amd_apu_unified_memory.py
new file mode 100644
index 0000000000..e0b819d54b
--- /dev/null
+++ b/studio/backend/tests/test_amd_apu_unified_memory.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGML_CUDA_ENABLE_UNIFIED_MEMORY must be set only for AMD unified-memory APUs
+(gfx1150/gfx1151), never for discrete AMD, NVIDIA, CPU or macOS."""
+
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+from core.inference.llama_cpp import LlamaCppBackend
+
+
+def _fake_torch(hip, archs, *, cuda_ok = True):
+    t = types.ModuleType("torch")
+    t.version = types.SimpleNamespace(hip = hip)
+    t.cuda = types.SimpleNamespace(
+        is_available = lambda: cuda_ok,
+        device_count = lambda: len(archs),
+        get_device_properties = lambda i: types.SimpleNamespace(gcnArchName = archs[i]),
+    )
+    return t
+
+
+@pytest.mark.parametrize(
+    "hip,archs,expected",
+    [
+        ("6.2.0", ["gfx1151:xnack-"], True),  # Strix Halo APU (suffix stripped)
+        ("6.2.0", ["gfx1150"], True),  # Strix Point APU
+        ("6.2.0", ["gfx1100"], False),  # discrete RDNA3
+        ("6.2.0", ["gfx1201"], False),  # discrete RDNA4
+        ("6.2.0", ["gfx942"], False),  # MI300X (data center)
+        (None, ["sm_90"], False),  # NVIDIA (no torch.version.hip)
+        ("6.2.0", ["gfx1100", "gfx1151"], True),  # mixed dGPU + APU
+    ],
+)
+def test_apu_unified_memory_gating(monkeypatch, hip, archs, expected):
+    monkeypatch.setitem(sys.modules, "torch", _fake_torch(hip, archs))
+    assert LlamaCppBackend._amd_apu_wants_unified_memory() is expected
+
+
+def test_cpu_no_cuda_returns_false(monkeypatch):
+    monkeypatch.setitem(sys.modules, "torch", _fake_torch("6.2.0", [], cuda_ok = False))
+    assert LlamaCppBackend._amd_apu_wants_unified_memory() is False
+
+
+def test_missing_torch_returns_false(monkeypatch):
+    monkeypatch.setitem(sys.modules, "torch", None)
+    assert LlamaCppBackend._amd_apu_wants_unified_memory() is False
diff --git a/studio/backend/tests/test_log_filter_no_truncation.py b/studio/backend/tests/test_log_filter_no_truncation.py
index d78643f5b9..d9a6e2bc4a 100644
--- a/studio/backend/tests/test_log_filter_no_truncation.py
+++ b/studio/backend/tests/test_log_filter_no_truncation.py
@@ -2,27 +2,11 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Regression tests for studio.backend.loggers.handlers.filter_sensitive_data.
+Regression tests for loggers.handlers.filter_sensitive_data.
 
-Context: filter_sensitive_data was originally written with a base64-detection
-heuristic that truncated any string >100 chars containing ',' or '/' down to
-20 chars + '...'. The block was dormant until PR #5246 wired the processor
-into the structlog chain to redact native-path leases. Once active, the
-heuristic ate normal log lines emitted by llama_cpp_backend (GGUF size
-summary, mmproj selection, the full llama-server command line) and any
-exception traceback that happened to contain a file path.
-
-These tests pin two properties:
-
-1. Long, comma- or slash-bearing log messages flow through filter_sensitive_data
-   unchanged. The exact strings exercised match the call sites at
-   studio/backend/core/inference/llama_cpp.py:2117, :2283, and :2312 that
-   were truncated in the original bug report.
-
-2. PR #5246's native-path lease redaction still fires for both the inline
-   ``native_path_lease=...`` regex form and the ``nativePathLease`` dict-key
-   form. This guards against future regressions that strip redaction along
-   with the truncation block.
+Pins two properties: (1) long strings with commas/slashes pass through
+unchanged (the base64-truncation heuristic from PR #5246 was too aggressive),
+and (2) native-path lease redaction still fires for both inline and dict-key forms.
 """
 
 from loggers.handlers import filter_sensitive_data
diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.py
new file mode 100644
index 0000000000..2ce9b55789
--- /dev/null
+++ b/studio/backend/tests/test_rocm_oom_guard.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Unit tests for _rocm_classify_unified_memory (ROCm OOM-guard classifier).
+
+Covers the three classification paths:
+  Path 1 – canonical gcnArchName attribute present.
+  Path 2 – gcnArchName absent, alternate-spelling attribute present.
+  Path 3 – ALL arch attrs absent; falls back to device-name substring match.
+
+Regression for: Strix Halo (gfx1151) misclassified as discrete on AMD SDK /
+Radeon wheels that populate props.name = "Radeon 8060S Graphics" but do NOT
+set any gcnArchName attribute.  Without the 8060s/8050s name patterns the
+fallback returned is_unified=False, applying the 0.90 fraction instead of
+0.80 and leaving only ~12.8 GiB OS headroom on a 128 GiB unified-memory pool.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from core.training.worker import _rocm_classify_unified_memory
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+
+def _props(**kwargs) -> SimpleNamespace:
+    """Build a fake device-properties object with the given attributes."""
+    return SimpleNamespace(**kwargs)
+
+
+# ── Path 1: canonical gcnArchName ────────────────────────────────────────────
+
+
+class TestCanonicalGcnArchName:
+    """gcnArchName is present and populated."""
+
+    @pytest.mark.parametrize(
+        "arch, expected_unified",
+        [
+            ("gfx1150", True),  # Strix Point
+            ("gfx1151", True),  # Strix Halo
+            ("gfx1100", False),  # Navi 31 (RX 7900 XTX) — discrete
+            ("gfx906", False),  # MI50 — discrete server GPU
+            ("gfx1201", False),  # RX 9070 XT — discrete
+        ],
+    )
+    def test_canonical_attr(self, arch: str, expected_unified: bool) -> None:
+        props = _props(gcnArchName = arch, name = "irrelevant")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == arch
+        assert is_unified is expected_unified
+
+    def test_arch_with_colon_suffix_stripped(self) -> None:
+        """gcnArchName can carry xnack/sramecc suffix; only the base is kept."""
+        props = _props(gcnArchName = "gfx1151:xnack-", name = "irrelevant")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1151"
+        assert is_unified is True
+
+    def test_canonical_attr_wins_over_name(self) -> None:
+        """Arch attr takes priority; device name should be ignored."""
+        # Discrete arch, but name looks like a unified SKU — arch must win.
+        props = _props(gcnArchName = "gfx1100", name = "Radeon 890M")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1100"
+        assert is_unified is False
+
+
+# ── Path 2: alternate-spelling fallback ──────────────────────────────────────
+
+
+class TestAlternateSpellingFallback:
+    """gcnArchName is missing but an alternate attr spelling is present."""
+
+    @pytest.mark.parametrize(
+        "attr_name",
+        ["gcn_arch_name", "arch_name", "gfx_arch_name"],
+    )
+    def test_alternate_attr_unified(self, attr_name: str) -> None:
+        props = _props(**{attr_name: "gfx1151"}, name = "Radeon 8060S Graphics")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1151"
+        assert is_unified is True
+
+    @pytest.mark.parametrize(
+        "attr_name",
+        ["gcn_arch_name", "arch_name", "gfx_arch_name"],
+    )
+    def test_alternate_attr_discrete(self, attr_name: str) -> None:
+        props = _props(**{attr_name: "gfx1201"}, name = "Radeon RX 9070 XT")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1201"
+        assert is_unified is False
+
+    def test_first_non_empty_attr_wins(self) -> None:
+        """When multiple alternate attrs are present the first non-empty one wins."""
+        props = _props(gcn_arch_name = "gfx1151", arch_name = "gfx1100", name = "irrelevant")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1151"
+        assert is_unified is True
+
+
+# ── Path 3: device-name fallback ─────────────────────────────────────────────
+
+
+class TestDeviceNameFallback:
+    """ALL arch attrs absent — classifier must rely solely on device name."""
+
+    # --- unified-memory devices that MUST be detected ---
+
+    @pytest.mark.parametrize(
+        "device_name",
+        [
+            # gfx1150 Strix Point
+            "Radeon 890M",
+            "AMD Radeon 890M Graphics",
+            "RADEON 890M",  # case-insensitive
+            "Radeon 880M",
+            "AMD Radeon 880M Graphics",
+            # gfx1151 Strix Halo — the regression case from the review
+            "Radeon 8060S Graphics",  # Ryzen AI MAX+ 395 (as returned by torch)
+            "AMD Radeon 8060S",
+            "Radeon 8050S Graphics",  # cut-down Strix Halo SKU
+            "AMD Radeon 8050S",
+            # case variants
+            "RADEON 8060S GRAPHICS",
+            "radeon 8050s",
+        ],
+    )
+    def test_unified_memory_detected(self, device_name: str) -> None:
+        props = _props(name = device_name)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "", f"expected empty gcn_arch, got {gcn!r}"
+        assert (
+            is_unified is True
+        ), f"device {device_name!r} should be classified as unified-memory"
+
+    # --- discrete devices that must NOT be mis-classified ---
+
+    @pytest.mark.parametrize(
+        "device_name",
+        [
+            "Radeon RX 9070 XT",
+            "AMD Radeon RX 7900 XTX",
+            "Radeon RX 6900 XT",
+            "Radeon Pro W7900",
+            "AMD Instinct MI300X",
+            # Names that contain superficially similar substrings but are discrete
+            "Radeon RX 580",
+            "Radeon VII",
+        ],
+    )
+    def test_discrete_not_misclassified(self, device_name: str) -> None:
+        props = _props(name = device_name)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == ""
+        assert (
+            is_unified is False
+        ), f"discrete device {device_name!r} should NOT be classified as unified-memory"
+
+    def test_empty_name_returns_false(self) -> None:
+        """Completely absent name must not crash and must default to discrete."""
+        props = _props()  # no 'name' attr at all
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == ""
+        assert is_unified is False
+
+    def test_none_name_returns_false(self) -> None:
+        props = _props(name = None)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == ""
+        assert is_unified is False
diff --git a/studio/backend/utils/hardware/amd.py b/studio/backend/utils/hardware/amd.py
index fdb1ab4520..48d5890399 100644
--- a/studio/backend/utils/hardware/amd.py
+++ b/studio/backend/utils/hardware/amd.py
@@ -11,18 +11,35 @@ nvidia.py counterparts.
 import json
 import math
 import os
+import platform
 import re
 import subprocess
+import sys
 from typing import Any, Optional
 
 from loggers import get_logger
 from utils.native_path_leases import child_env_without_native_path_secret
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
 
 logger = get_logger(__name__)
 
+# amd-smi on Windows must initialise the full ROCm runtime on first call, which
+# can take 15-25 s on cold hardware.  Linux is consistently < 2 s.
+_AMD_SMI_DEFAULT_TIMEOUT = 30 if platform.system() == "Windows" else 10
 
-def _run_amd_smi(*args: str, timeout: int = 5) -> Optional[Any]:
+# Circuit breaker: stop calling amd-smi after this many consecutive failures.
+# On Windows, each failed call spawns a process that may show a UAC/DiskPart
+# elevation prompt.  Once we know amd-smi doesn't work we stop polling it.
+_AMD_SMI_FAILURE_LIMIT = 3
+_amd_smi_consecutive_failures = 0
+_amd_smi_disabled = False
+
+
+def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optional[Any]:
     """Run amd-smi with the given arguments and return parsed JSON, or None."""
+    global _amd_smi_consecutive_failures, _amd_smi_disabled
+    if _amd_smi_disabled:
+        return None
     try:
         result = subprocess.run(
             ["amd-smi", *args, "--json"],
@@ -30,13 +47,40 @@ def _run_amd_smi(*args: str, timeout: int = 5) -> Optional[Any]:
             text = True,
             timeout = timeout,
             env = child_env_without_native_path_secret(),
+            **windows_hidden_subprocess_kwargs(),
         )
     except (OSError, subprocess.TimeoutExpired) as e:
-        logger.warning("amd-smi query failed: %s", e)
+        if isinstance(e, FileNotFoundError):
+            # amd-smi ships with Adrenalin, not the HIP SDK -- absence is
+            # expected on HIP SDK-only Windows setups.  Log at debug only.
+            logger.debug("amd-smi not found (not in PATH): %s", e)
+        else:
+            logger.warning("amd-smi query failed: %s", e)
+        _amd_smi_consecutive_failures += 1
+        if _amd_smi_consecutive_failures >= _AMD_SMI_FAILURE_LIMIT:
+            logger.info(
+                "amd-smi not available (not installed; expected on HIP SDK-only systems); "
+                "GPU VRAM polling disabled"
+            )
+            _amd_smi_disabled = True
         return None
-    if result.returncode != 0 or not result.stdout.strip():
+    if result.returncode != 0:
         logger.warning("amd-smi returned code %d", result.returncode)
+        _amd_smi_consecutive_failures += 1
+        if _amd_smi_consecutive_failures >= _AMD_SMI_FAILURE_LIMIT:
+            logger.info(
+                "amd-smi not available (not installed; expected on HIP SDK-only systems); "
+                "GPU VRAM polling disabled"
+            )
+            _amd_smi_disabled = True
         return None
+    if not result.stdout.strip():
+        # amd-smi exited successfully but produced no output (e.g. no GPUs
+        # visible on this query, or a version that emits nothing for --json).
+        # This is not a tool failure, so don't count against the circuit breaker.
+        logger.debug("amd-smi exited 0 but returned no output")
+        return None
+    _amd_smi_consecutive_failures = 0  # reset on success
     try:
         return json.loads(result.stdout)
     except json.JSONDecodeError:
@@ -352,7 +396,7 @@ def get_visible_gpu_utilization(
         )
         parsed_id = _parse_numeric(raw_id)
         if parsed_id is None:
-            logger.debug(
+            logger.warning(
                 "amd-smi GPU id %r could not be parsed; falling back to "
                 "enumeration index %d",
                 raw_id,
@@ -360,7 +404,15 @@ def get_visible_gpu_utilization(
             )
             idx = fallback_idx
         else:
-            idx = int(parsed_id)
+            rounded = round(parsed_id)
+            if rounded != parsed_id:
+                logger.warning(
+                    "amd-smi GPU id %r parsed as non-integer %r; truncating to %d",
+                    raw_id,
+                    parsed_id,
+                    rounded,
+                )
+            idx = int(rounded)
         if idx not in visible_set:
             continue
         metrics = _extract_gpu_metrics(gpu_data)
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index ede37e2953..ebac6a357c 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -120,11 +120,13 @@ def detect_hardware() -> DeviceType:
 
             # Distinguish AMD ROCm (HIP) from NVIDIA CUDA for display purposes.
             # DeviceType stays CUDA since torch.cuda.* works on ROCm via HIP.
-            if getattr(torch.version, "hip", None) is not None:
+            # AMD's repo.radeon.com SDK wheels (e.g. 2.9.0+rocmsdk20251116) do
+            # not set torch.version.hip, so fall back to checking __version__.
+            _hip_ver = getattr(torch.version, "hip", None)
+            if _hip_ver is not None or "rocm" in torch.__version__.lower():
                 IS_ROCM = True
-                print(
-                    f"Hardware detected: ROCm (HIP {torch.version.hip}) -- {device_name}"
-                )
+                _hip_label = _hip_ver or torch.__version__
+                print(f"Hardware detected: ROCm (HIP {_hip_label}) -- {device_name}")
             else:
                 print(f"Hardware detected: CUDA -- {device_name}")
             return DEVICE
@@ -466,7 +468,7 @@ def _smi_query(func_name: str, *args, **kwargs) -> Optional[Dict[str, Any]]:
     try:
         func = getattr(_backend, func_name)
         result = func(*args, **kwargs)
-        if result.get("available"):
+        if isinstance(result, dict) and result.get("available"):
             return result
     except Exception as e:
         logger.warning("%s %s query failed: %s", backend_name, func_name, e)
@@ -506,6 +508,145 @@ def _read_apple_gpu_stats() -> Dict[str, Any]:
     }
 
 
+def _rocm_linux_sysfs_gpu_busy_pct() -> Optional[float]:
+    """Query AMD GPU compute utilization via Linux DRM sysfs gpu_busy_percent."""
+    import glob as _glob
+
+    if platform.system() != "Linux":
+        return None
+    try:
+        files = _glob.glob("/sys/class/drm/card*/device/gpu_busy_percent")
+        if not files:
+            return None
+        values = [int(open(f).read().strip()) for f in files]
+        return round(sum(values) / len(values), 1)
+    except Exception:
+        return None
+
+
+def _rocm_linux_sysfs_temp_c() -> Optional[float]:
+    """Query AMD GPU edge temperature via Linux DRM hwmon sysfs (temp1_input, millidegrees C)."""
+    import glob as _glob
+
+    if platform.system() != "Linux":
+        return None
+    try:
+        files = _glob.glob("/sys/class/drm/card*/device/hwmon/hwmon*/temp1_input")
+        if not files:
+            return None
+        temps = [int(open(f).read().strip()) / 1000.0 for f in files]
+        return round(max(temps), 1)
+    except Exception:
+        return None
+
+
+def _rocm_linux_sysfs_power_w() -> Optional[float]:
+    """Query AMD GPU average power draw via Linux DRM hwmon sysfs (microwatts)."""
+    import glob as _glob
+
+    if platform.system() != "Linux":
+        return None
+    try:
+        for pattern in (
+            "/sys/class/drm/card*/device/hwmon/hwmon*/power1_average",
+            "/sys/class/drm/card*/device/hwmon/hwmon*/power1_input",
+        ):
+            files = _glob.glob(pattern)
+            if files:
+                watts = sum(int(open(f).read().strip()) / 1_000_000.0 for f in files)
+                return round(watts, 1)
+        return None
+    except Exception:
+        return None
+
+
+def _rocm_windows_perf_counter_gpu_util_pct() -> Optional[float]:
+    """Query AMD GPU compute utilization via Windows Performance Counters (3D engine nodes)."""
+    import subprocess as _sp
+
+    if platform.system() != "Windows":
+        return None
+    try:
+        ps = (
+            "$s=(Get-Counter '\\GPU Engine(*engtype_3D*)\\Utilization Percentage'"
+            " -ErrorAction SilentlyContinue).CounterSamples;"
+            "if($s){[math]::Min(($s|Measure-Object CookedValue -Sum).Sum,100)}else{-1}"
+        )
+        r = _sp.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
+            capture_output = True,
+            text = True,
+            timeout = 5,
+        )
+        if r.returncode != 0 or not r.stdout.strip():
+            return None
+        val = float(r.stdout.strip())
+        return round(val, 1) if val >= 0 else None
+    except Exception:
+        return None
+
+
+def _rocm_linux_sysfs_vram_gb() -> tuple[Optional[float], Optional[float]]:
+    """Query system-wide AMD GPU VRAM via Linux DRM sysfs.
+
+    Reads /sys/class/drm/card*/device/mem_info_vram_* which the kernel
+    updates in real-time across all processes. No tools required.
+    Returns (used_gb, total_gb) or (None, None) on failure.
+    """
+    import glob as _glob
+
+    if platform.system() != "Linux":
+        return None, None
+    try:
+        used_files = _glob.glob("/sys/class/drm/card*/device/mem_info_vram_used")
+        total_files = _glob.glob("/sys/class/drm/card*/device/mem_info_vram_total")
+        if not used_files or not total_files:
+            return None, None
+        used_bytes = sum(int(open(f).read().strip()) for f in used_files)
+        total_bytes = sum(int(open(f).read().strip()) for f in total_files)
+        if total_bytes == 0:
+            return None, None
+        return round(used_bytes / (1024**3), 2), round(total_bytes / (1024**3), 2)
+    except Exception:
+        return None, None
+
+
+def _rocm_windows_perf_counter_vram_gb() -> tuple[Optional[float], Optional[float]]:
+    """Query system-wide dedicated GPU VRAM via Windows Performance Counters.
+
+    Uses the same data source as Task Manager so it reflects cross-process
+    usage accurately. Works for any GPU vendor without amd-smi or nvidia-smi.
+    Returns (used_gb, total_gb) or (None, None) on failure.
+    """
+    import subprocess as _sp
+
+    if platform.system() != "Windows":
+        return None, None
+    try:
+        ps = (
+            "$s=(Get-Counter '\\GPU Adapter Memory(*)\\Dedicated Usage'"
+            " -ErrorAction SilentlyContinue).CounterSamples;"
+            "if($s){($s|Measure-Object CookedValue -Sum).Sum}else{-1}"
+        )
+        r = _sp.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
+            capture_output = True,
+            text = True,
+            timeout = 5,
+        )
+        if r.returncode != 0 or not r.stdout.strip():
+            return None, None
+        used_bytes = float(r.stdout.strip())
+        if used_bytes < 0:
+            return None, None
+        import torch as _torch
+
+        total_bytes = _torch.cuda.get_device_properties(0).total_memory
+        return round(used_bytes / (1024**3), 2), round(total_bytes / (1024**3), 2)
+    except Exception:
+        return None, None
+
+
 def get_gpu_utilization() -> Dict[str, Any]:
     """Return a live snapshot of device utilization information."""
     device = get_device()
@@ -514,7 +655,78 @@ def get_gpu_utilization() -> Dict[str, Any]:
         result = _smi_query("get_primary_gpu_utilization")
         if result is not None:
             result["backend"] = _backend_label(device)
+            if IS_ROCM:
+                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
+                _reconcile_primary_rocm_unified_memory(
+                    result, _get_parent_visible_gpu_spec()
+                )
             return result
+        # SMI tool unavailable or returned no usable data. On Windows, query
+        # the Performance Counter API (same source as Task Manager) for
+        # system-wide dedicated VRAM — covers cross-process usage that
+        # torch.cuda.mem_get_info cannot see from the Studio server process.
+        if IS_ROCM and platform.system() == "Windows":
+            _win_used, _win_total = _rocm_windows_perf_counter_vram_gb()
+            if _win_used is not None and _win_total is not None:
+                _win_util = _rocm_windows_perf_counter_gpu_util_pct()
+                return {
+                    "available": True,
+                    "backend": _backend_label(device),
+                    "gpu_utilization_pct": _win_util,
+                    "temperature_c": None,
+                    "vram_used_gb": _win_used,
+                    "vram_total_gb": _win_total,
+                    "vram_utilization_pct": round((_win_used / _win_total) * 100, 1)
+                    if _win_total > 0
+                    else None,
+                    "power_draw_w": None,
+                    "power_limit_w": None,
+                    "power_utilization_pct": None,
+                }
+        # Linux: DRM sysfs gives system-wide VRAM across all processes, no tools needed.
+        if IS_ROCM and platform.system() == "Linux":
+            _linux_used, _linux_total = _rocm_linux_sysfs_vram_gb()
+            if _linux_used is not None and _linux_total is not None:
+                _linux_util = _rocm_linux_sysfs_gpu_busy_pct()
+                _linux_temp = _rocm_linux_sysfs_temp_c()
+                _linux_power = _rocm_linux_sysfs_power_w()
+                return {
+                    "available": True,
+                    "backend": _backend_label(device),
+                    "gpu_utilization_pct": _linux_util,
+                    "temperature_c": _linux_temp,
+                    "vram_used_gb": _linux_used,
+                    "vram_total_gb": _linux_total,
+                    "vram_utilization_pct": round((_linux_used / _linux_total) * 100, 1)
+                    if _linux_total > 0
+                    else None,
+                    "power_draw_w": _linux_power,
+                    "power_limit_w": None,
+                    "power_utilization_pct": None,
+                }
+        # Last resort: torch mem_get_info (process-local).
+        _visible_spec = _get_parent_visible_gpu_spec()
+        _numeric_ids = _visible_spec.get("numeric_ids") or [0]
+        _primary_idx = [_numeric_ids[0]] if _numeric_ids else [0]
+        _torch_devices = _torch_get_per_device_info(_primary_idx)
+        if _torch_devices:
+            _td = _torch_devices[0]
+            _total = _td["total_gb"]
+            _used = _td["used_gb"]
+            return {
+                "available": True,
+                "backend": _backend_label(device),
+                "gpu_utilization_pct": None,
+                "temperature_c": None,
+                "vram_used_gb": _used,
+                "vram_total_gb": _total,
+                "vram_utilization_pct": round((_used / _total) * 100, 1)
+                if _total > 0
+                else None,
+                "power_draw_w": None,
+                "power_limit_w": None,
+                "power_utilization_pct": None,
+            }
 
     # MLX path: single _read_apple_gpu_stats() call carries both VRAM-used
     # bytes and GPU utilization %. psutil for unified-memory total is cheap.
@@ -578,6 +790,77 @@ def get_gpu_utilization() -> Dict[str, Any]:
     return {"available": False, "backend": _backend_label(device)}
 
 
+def _apply_unified_memory_correction(
+    device_metrics: Dict[str, Any], torch_info: Dict[str, Any]
+) -> None:
+    """Per-device reconciliation: when torch reports a larger memory total
+    than amd-smi, overwrite the smi VRAM fields in place.
+
+    Used by both the multi-device and primary-device reconciliation helpers
+    so the two endpoints stay in sync on AMD iGPUs with unified memory.
+    """
+    torch_total_gb = torch_info["total_gb"]
+    smi_total_gb = device_metrics.get("vram_total_gb") or 0.0
+    if torch_total_gb > smi_total_gb:
+        torch_used_gb = torch_info["used_gb"]
+        device_metrics["vram_total_gb"] = torch_total_gb
+        device_metrics["vram_used_gb"] = torch_used_gb
+        device_metrics["vram_utilization_pct"] = (
+            round((torch_used_gb / torch_total_gb) * 100, 1)
+            if torch_total_gb > 0
+            else None
+        )
+        logger.debug(
+            "ROCm unified memory: replaced amd-smi VRAM (%.2f GB) with "
+            "torch mem_get_info total (%.2f GB) for device %s",
+            smi_total_gb,
+            torch_total_gb,
+            torch_info.get("index"),
+        )
+
+
+def _reconcile_rocm_unified_memory(
+    utilization: Dict[str, Any], device_indices: list[int]
+) -> None:
+    """Fix amd-smi VRAM for ROCm unified-memory GPUs (e.g. Strix Halo).
+
+    amd-smi reports only the dedicated slice (~512 MB); torch sees the full
+    GTT pool (~128 GB). When torch total > smi total, overwrite per-device
+    VRAM fields so GPU selection uses the real available memory.
+    """
+    torch_devices = _torch_get_per_device_info(device_indices)
+    if not torch_devices:
+        return
+    torch_by_index = {td["index"]: td for td in torch_devices}
+    for dev in utilization.get("devices", []):
+        td = torch_by_index.get(dev.get("index"))
+        if td is None:
+            continue
+        _apply_unified_memory_correction(dev, td)
+
+
+def _reconcile_primary_rocm_unified_memory(
+    utilization: Dict[str, Any], parent_visible_spec: Dict[str, Any]
+) -> None:
+    """Same fix as _reconcile_rocm_unified_memory for the flat primary-GPU dict."""
+    numeric_ids = parent_visible_spec.get("numeric_ids")
+    if numeric_ids is None:
+        # No visibility env var set: torch ordinal 0 is the primary device.
+        primary_idx = [0]
+    elif len(numeric_ids) == 0:
+        # Empty mask (HIP_VISIBLE_DEVICES="" or "-1"): no GPU is visible to
+        # this process. Querying torch device 0 would raise a RuntimeError or
+        # return stale/wrong data, so bail out rather than writing bad values
+        # into the utilization dict.
+        return
+    else:
+        primary_idx = [int(numeric_ids[0])]
+    torch_devices = _torch_get_per_device_info(primary_idx)
+    if not torch_devices:
+        return
+    _apply_unified_memory_correction(utilization, torch_devices[0])
+
+
 def get_visible_gpu_utilization() -> Dict[str, Any]:
     device = get_device()
 
@@ -590,6 +873,10 @@ def get_visible_gpu_utilization() -> Dict[str, Any]:
         )
         if result is not None:
             result["backend"] = _backend_label(device)
+            numeric_ids = parent_visible_spec.get("numeric_ids")
+            if IS_ROCM and numeric_ids is not None:
+                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
+                _reconcile_rocm_unified_memory(result, numeric_ids)
             return result
 
     # Torch-based fallback for CUDA (nvidia-smi unavailable, AMD ROCm) and XPU (Intel)
@@ -689,7 +976,15 @@ def _get_parent_visible_gpu_spec() -> Dict[str, Any]:
     # Use explicit None checks (not `or`) so empty string "" is honoured
     # as "no visible GPUs" rather than falling through to CUDA_VISIBLE_DEVICES.
     cuda_visible = None
-    if IS_ROCM:
+    # Prefer ROCm masks only on a ROCm host, or when no CUDA mask is set, so a
+    # stale HIP_VISIBLE_DEVICES on an NVIDIA host can't override CUDA_VISIBLE_DEVICES.
+    _is_rocm_spec = IS_ROCM or (
+        "CUDA_VISIBLE_DEVICES" not in os.environ
+        and (
+            "HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ
+        )
+    )
+    if _is_rocm_spec:
         hip_vis = os.environ.get("HIP_VISIBLE_DEVICES")
         rocr_vis = os.environ.get("ROCR_VISIBLE_DEVICES")
         if hip_vis is not None:
@@ -867,6 +1162,61 @@ def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = Non
 def _determine_attention_impl_for_gpu_estimate(config) -> str:
     import copy as _copy
 
+    # torch.distributed is incomplete on Windows ROCm — torch._C is a C
+    # extension (not a package), so Python cannot import the submodule
+    # torch._C._distributed_c10d that torch.distributed depends on.
+    # Inject an empty stub into sys.modules BEFORE importing torch.distributed
+    # so the import succeeds, then patch the missing process-group helpers.
+    import sys as _sys
+    import types as _types
+
+    if _sys.platform == "win32" and IS_ROCM:
+        # Dummy class for any name torch.distributed tries to import from these stubs
+        class _Dummy:
+            pass
+
+        for _c10d_name in (
+            "torch._C._distributed_c10d",
+            "torch._C._distributed_autograd",
+            "torch._C._distributed_rpc",
+        ):
+            if _c10d_name not in _sys.modules:
+                _stub = _types.ModuleType(_c10d_name)
+                # torch.distributed imports these names from _distributed_c10d;
+                # provide no-op dummies so the import doesn't raise AttributeError.
+                for _sym in (
+                    "FakeProcessGroup",
+                    "ProcessGroup",
+                    "Work",
+                    "Store",
+                    "PrefixStore",
+                    "FileStore",
+                    "TCPStore",
+                    "HashStore",
+                    "Reducer",
+                    "Logger",
+                    "DistributedDebugLevel",
+                    "GradBucket",
+                    "BuiltinCommHookType",
+                ):
+                    setattr(_stub, _sym, _Dummy)
+                _sys.modules[_c10d_name] = _stub
+
+    try:
+        import torch.distributed as _td
+
+        for _attr, _stub in (
+            ("is_initialized", lambda: False),
+            ("is_available", lambda: False),
+            ("get_rank", lambda: 0),
+            ("get_world_size", lambda: 1),
+            ("is_torchelastic_launched", lambda: False),
+        ):
+            if not hasattr(_td, _attr):
+                setattr(_td, _attr, _stub)
+    except ImportError:
+        pass
+
     from unsloth.models._utils import resolve_attention_implementation
     from transformers import AutoModel, AutoModelForCausalLM
 
@@ -1062,7 +1412,10 @@ def estimate_required_model_memory_gb(
                 _determine_attention_impl_for_gpu_estimate(config)
             )
         except Exception as e:
-            logger.warning(
+            # Log at debug: on Windows ROCm the torch.distributed stub does
+            # not implement Store, so this fires on every estimate call.
+            # It is expected and non-actionable -- eager is the safe fallback.
+            logger.debug(
                 "Could not resolve attention implementation for '%s': %s",
                 estimate_model,
                 e,
@@ -1552,14 +1905,35 @@ def apply_gpu_ids(gpu_ids) -> None:
     # parent process already set a ROCm visibility variable -- that
     # way a downstream ROCm process inherits the narrowed mask even
     # before Studio's hardware detection has classified the host.
+    # Final fallback: probe torch.version.hip so AMD workers without
+    # HIP_VISIBLE_DEVICES still get the correct ROCm visibility mask.
     _inherits_rocm_visibility = (
         "HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ
     )
-    if IS_ROCM or _inherits_rocm_visibility:
+    _is_rocm = IS_ROCM or _inherits_rocm_visibility
+    if not _is_rocm:
+        # torch.version.hip is a non-empty string on ROCm, None on CUDA.
+        # AMD SDK / Radeon ROCm wheels can leave torch.version.hip unset but
+        # still encode "rocm" in torch.__version__, matching detect_hardware().
+        # Broad except: a probe failure must never crash a training worker.
+        try:
+            import torch as _torch
+
+            _is_rocm = (
+                getattr(_torch.version, "hip", None) is not None
+                or "rocm" in getattr(_torch, "__version__", "").lower()
+            )
+        except Exception as e:
+            logger.debug(
+                "apply_gpu_ids: torch ROCm probe skipped (%s: %s)",
+                type(e).__name__,
+                e,
+            )
+    if _is_rocm:
         os.environ["HIP_VISIBLE_DEVICES"] = value
         os.environ["ROCR_VISIBLE_DEVICES"] = value
     _visible_gpu_count = None
-    if IS_ROCM or _inherits_rocm_visibility:
+    if _is_rocm:
         logger.info("Applied gpu_ids: CUDA_VISIBLE_DEVICES='%s' (rocm)", value)
     else:
         logger.info("Applied gpu_ids: CUDA_VISIBLE_DEVICES='%s'", value)
diff --git a/studio/backend/utils/wheel_utils.py b/studio/backend/utils/wheel_utils.py
index 5c42e890d1..e0ce02261b 100644
--- a/studio/backend/utils/wheel_utils.py
+++ b/studio/backend/utils/wheel_utils.py
@@ -15,6 +15,7 @@ import urllib.request
 from typing import Callable
 
 from utils.native_path_leases import child_env_without_native_path_secret
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
 
 _logger = logging.getLogger(__name__)
 
@@ -106,6 +107,7 @@ def probe_torch_wheel_env(*, timeout: int | None = None) -> dict[str, str] | Non
             text = True,
             timeout = timeout,
             env = child_env_without_native_path_secret(),
+            **windows_hidden_subprocess_kwargs(),
         )
     except subprocess.TimeoutExpired:
         return None
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index b9d63ecee9..31fb841414 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -29,7 +29,7 @@ import urllib.parse
 import urllib.request
 import zipfile
 from contextlib import contextmanager
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace as dataclasses_replace
 
 try:
     from filelock import FileLock, Timeout as FileLockTimeout
@@ -1336,6 +1336,20 @@ def direct_upstream_release_plan(
                     torch_preference.selection_log,
                 )
             )
+        elif host.has_rocm:
+            hip_asset = f"llama-{release_tag}-bin-win-hip-radeon-x64.zip"
+            hip_url = assets.get(hip_asset)
+            if hip_url:
+                attempts.append(
+                    AssetChoice(
+                        repo = repo,
+                        tag = release_tag,
+                        name = hip_asset,
+                        url = hip_url,
+                        source_label = "upstream",
+                        install_kind = "windows-hip",
+                    )
+                )
         cpu_asset = f"llama-{release_tag}-bin-win-cpu-x64.zip"
         cpu_url = assets.get(cpu_asset)
         if cpu_url:
@@ -2731,12 +2745,30 @@ def detect_host() -> HostInfo:
                     has_rocm = True
                     break
     elif is_windows:
-        # Windows: prefer active probes that validate GPU presence
+        # Windows: prefer active probes that validate GPU presence.
+        # hipinfo / amd-smi are often NOT on PATH -- the HIP SDK installer
+        # sets HIP_PATH / ROCM_PATH but does not always add the bin dir to
+        # the system PATH.  Mirror setup.ps1's fallback: check the env-var
+        # bin dirs before giving up so that `has_rocm` is not silently False
+        # on machines where the PATH is not yet updated.
+        def _resolve_exe(name: str) -> str | None:
+            """Return full path to `name`, checking PATH then HIP_PATH/ROCM_PATH bin."""
+            found = shutil.which(name)
+            if found:
+                return found
+            for _env in ("HIP_PATH", "ROCM_PATH"):
+                _root = os.environ.get(_env)
+                if _root:
+                    _candidate = os.path.join(_root, "bin", f"{name}.exe")
+                    if os.path.isfile(_candidate):
+                        return _candidate
+            return None
+
         for _cmd, _check in (
             (["hipinfo"], lambda out: "gcnarchname" in out.lower()),
             (["amd-smi", "list"], _amd_smi_has_gpu),
         ):
-            _exe = shutil.which(_cmd[0])
+            _exe = _resolve_exe(_cmd[0])
             if not _exe:
                 continue
             try:
@@ -5565,8 +5597,11 @@ def install_prebuilt(
     published_release_tag: str,
     *,
     simple_policy: bool = False,
+    override_has_rocm: bool = False,
 ) -> None:
     host = detect_host()
+    if override_has_rocm and not host.has_rocm:
+        host = dataclasses_replace(host, has_rocm = True)
     choice: AssetChoice | None = None
     try:
         with install_lock(install_lock_path(install_dir)):
@@ -5700,6 +5735,17 @@ def parse_args() -> argparse.Namespace:
         action = "store_true",
         help = "Use the simplified platform-specific prebuilt selection policy.",
     )
+    parser.add_argument(
+        "--has-rocm",
+        action = "store_true",
+        default = False,
+        help = (
+            "Assert that an AMD ROCm GPU is present. When set, skips the internal "
+            "hipinfo/amd-smi probe and forces has_rocm=True in the host profile. "
+            "Used by setup.ps1/setup.sh to forward their own ROCm detection result "
+            "so the HIP llama.cpp prebuilt is selected even when hipinfo is not on PATH."
+        ),
+    )
     resolve_group = parser.add_mutually_exclusive_group()
     resolve_group.add_argument(
         "--resolve-llama-tag",
@@ -5820,6 +5866,7 @@ def main() -> int:
         published_repo = args.published_repo,
         published_release_tag = args.published_release_tag or "",
         simple_policy = args.simple_policy,
+        override_has_rocm = args.has_rocm,
     )
     return EXIT_SUCCESS
 
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index c4524b06f5..786b668e7b 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -54,12 +54,9 @@ PLATFORM_LACKS_TORCHCODEC_WHEEL = (
 # ── ROCm / AMD GPU support ─────────────────────────────────────────────────────
 # Mapping from detected ROCm (major, minor) to the best PyTorch wheel tag on
 # download.pytorch.org.  Entries are checked newest-first (>=).
-# ROCm 7.2 only has torch 2.11.0 on download.pytorch.org, which exceeds the
-# current torch upper bound (<2.11.0).  Fall back to rocm7.1 (torch 2.10.0).
-# TODO: uncomment rocm7.2 when torch upper bound is bumped to >=2.11.0
 _ROCM_TORCH_INDEX: dict[tuple[int, int], str] = {
-    # (7, 2): "rocm7.2",  # torch 2.11.0 -- requires torch>=2.11
-    (7, 1): "rocm7.1",
+    (7, 2): "rocm7.2",  # torch 2.11.0
+    (7, 1): "rocm7.1",  # torch 2.10.0
     (7, 0): "rocm7.0",
     (6, 4): "rocm6.4",
     (6, 3): "rocm6.3",
@@ -67,10 +64,47 @@ _ROCM_TORCH_INDEX: dict[tuple[int, int], str] = {
     (6, 1): "rocm6.1",
     (6, 0): "rocm6.0",
 }
+
+# Per-tag pip specs; rocm7.2 ships torch 2.11.0 (older tags cap at 2.10.x).
+_ROCM_TORCH_PKG_SPECS: dict[str, tuple[str, str, str]] = {
+    "rocm7.2": (
+        "torch>=2.11.0,<2.12.0",
+        "torchvision>=0.26.0,<0.27.0",
+        "torchaudio>=2.11.0,<2.12.0",
+    ),
+    # Default for rocm7.1 and earlier: torch 2.x below 2.11
+    "_default": (
+        "torch>=2.4,<2.11.0",
+        "torchvision>=0.19,<0.26.0",
+        "torchaudio>=2.4,<2.11.0",
+    ),
+}
 _PYTORCH_WHL_BASE = (
     os.environ.get("UNSLOTH_PYTORCH_MIRROR") or "https://download.pytorch.org/whl"
 ).rstrip("/")
 
+# AMD Windows ROCm wheels — repo.amd.com (arch-specific pip index)
+# Format: https://repo.amd.com/rocm/whl/{arch_family}/
+# Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped / mirror installs.
+_ROCM_WINDOWS_INDEX_BASE = (
+    os.environ.get("UNSLOTH_ROCM_WINDOWS_MIRROR") or "https://repo.amd.com/rocm/whl"
+).rstrip("/")
+
+# Maps gfx arch → AMD index arch-family suffix.
+# Each family is a separate pip index on repo.amd.com.
+_GFX_TO_AMD_INDEX_ARCH: dict[str, str] = {
+    "gfx1201": "gfx120X-all",
+    "gfx1200": "gfx120X-all",  # RDNA 4
+    "gfx1151": "gfx1151",
+    "gfx1150": "gfx1150",  # RDNA 3.5 (Strix Halo/Point)
+    "gfx1103": "gfx110X-all",
+    "gfx1102": "gfx110X-all",  # RDNA 3
+    "gfx1101": "gfx110X-all",
+    "gfx1100": "gfx110X-all",
+    "gfx90a": "gfx90a",
+    "gfx908": "gfx908",  # MI200/MI100
+}
+
 # bitsandbytes continuous-release_main wheels with the ROCm 4-bit GEMV fix
 # (bnb PR #1887, post-0.49.2). bnb <= 0.49.2 NaNs at decode shape on every
 # AMD GPU. Drop the pin once bnb 0.50+ ships on PyPI.
@@ -85,6 +119,16 @@ _BNB_ROCM_PRERELEASE_URLS: dict[str, str] = {
         "download/continuous-release_main/"
         "bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_aarch64.whl"
     ),
+    # Windows ROCm wheel — ships libbitsandbytes_rocm{VER}.dll.
+    # BNB auto-detects HIP version from torch.version.hip, which does not always
+    # match the DLL suffix in this prerelease wheel (e.g. torch 7.13 with a rocm72
+    # DLL).  We scan the installed wheel for the actual DLL name and set
+    # BNB_ROCM_VERSION accordingly in _install_bnb_windows_rocm() and worker.py.
+    "win_amd64": (
+        "https://github.com/bitsandbytes-foundation/bitsandbytes/releases/"
+        "download/continuous-release_main/"
+        "bitsandbytes-1.33.7.preview-py3-none-win_amd64.whl"
+    ),
 }
 _BNB_ROCM_PYPI_FALLBACK = "bitsandbytes>=0.49.1"
 
@@ -196,6 +240,151 @@ def _detect_rocm_version() -> tuple[int, int] | None:
     return None
 
 
+def _pick_visible_index(num_tokens: int) -> int:
+    """Resolve HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES to an integer
+    index into a list of length num_tokens. Returns 0 (first GPU) for
+    unset, empty, '-1', UUID-style, or out-of-range values."""
+    for _env in ("HIP_VISIBLE_DEVICES", "ROCR_VISIBLE_DEVICES"):
+        _val = os.environ.get(_env)
+        if _val is None:
+            continue
+        _val = _val.strip()
+        if _val == "" or _val == "-1":
+            return 0
+        _first = _val.split(",")[0].strip()
+        try:
+            _idx = int(_first)
+            if 0 <= _idx < num_tokens:
+                return _idx
+        except ValueError:
+            pass
+        return 0
+    return 0
+
+
+def _detect_windows_gfx_arch() -> str | None:
+    """Return the gcnArchName on Windows (e.g. 'gfx1200'), or None.
+
+    Probe order matches the PowerShell installer: env-var override first,
+    then hipinfo (PATH or HIP_PATH / ROCM_PATH bin), then amd-smi. Without
+    the amd-smi fallback, runtime-only AMD installs without hipinfo on PATH
+    return early and `studio update` cannot repair a CPU-only venv.
+
+    On multi-GPU hosts, all detected gfx tokens are deduplicated (preserving
+    enumeration order) and HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES selects
+    which one to install for. The first GPU is used when no env var is set.
+    """
+    import re
+
+    # 1. Explicit override (matches PowerShell installer's env-var path).
+    _override = os.environ.get("UNSLOTH_ROCM_GFX_ARCH")
+    if _override and _override.strip():
+        return _override.strip().lower()
+
+    def _dedup_pick(tokens: list[str]) -> "str | None":
+        if not tokens:
+            return None
+        # Index into the full (ordered) list first so HIP_VISIBLE_DEVICES
+        # correctly addresses GPU N on mixed-arch hosts, then return that arch.
+        return tokens[_pick_visible_index(len(tokens))]
+
+    # 2. hipinfo via PATH, then HIP_PATH\bin / ROCM_PATH\bin.
+    hipinfo = shutil.which("hipinfo")
+    if not hipinfo:
+        for _env_var in ("HIP_PATH", "ROCM_PATH"):
+            _root = os.environ.get(_env_var)
+            if _root:
+                _candidate = os.path.join(_root, "bin", "hipinfo.exe")
+                if os.path.isfile(_candidate):
+                    hipinfo = _candidate
+                    break
+    if hipinfo:
+        try:
+            result = subprocess.run(
+                [hipinfo],
+                stdout = subprocess.PIPE,
+                stderr = subprocess.DEVNULL,
+                timeout = 10,
+            )
+            if result.returncode == 0:
+                text = result.stdout.decode(errors = "replace")
+                # findall picks every gcnArchName line so multi-GPU hosts
+                # are enumerable and HIP_VISIBLE_DEVICES selects correctly.
+                _tokens = [
+                    t.strip().lower()
+                    for t in re.findall(r"(?im)^\s*gcnArchName\s*:\s*(\S+)", text)
+                ]
+                _pick = _dedup_pick(_tokens)
+                if _pick:
+                    return _pick
+        except Exception:
+            pass
+
+    # 3. amd-smi fallback -- runtime-only Radeon installs ship amd-smi but no hipinfo.
+    amd_smi = shutil.which("amd-smi")
+    if amd_smi:
+        for _args in (("static", "--asic"), ("list",)):
+            try:
+                result = subprocess.run(
+                    [amd_smi, *_args],
+                    stdout = subprocess.PIPE,
+                    stderr = subprocess.DEVNULL,
+                    timeout = 10,
+                )
+                if result.returncode != 0:
+                    continue
+                text = result.stdout.decode(errors = "replace")
+                # Prefer labelled gfx lines; fall back to bare tokens.
+                _labelled = re.findall(
+                    r"(?im)^\s*(?:target_graphics_version|gfx|arch|asic)\b[^:\r\n]*:\s*(gfx[1-9][0-9a-z]{2,3})\b",
+                    text,
+                )
+                _tokens = [t.lower() for t in _labelled]
+                if not _tokens:
+                    _tokens = re.findall(r"\bgfx[1-9][0-9a-z]{2,3}\b", text.lower())
+                _pick = _dedup_pick(_tokens)
+                if _pick:
+                    return _pick
+            except Exception:
+                continue
+    return None
+
+
+def _windows_rocm_index_url(gfx_arch: str | None) -> str | None:
+    """Return the AMD pip index URL for the given GPU arch, or None if unsupported."""
+    arch_family = _GFX_TO_AMD_INDEX_ARCH.get(gfx_arch or "")
+    if arch_family is None:
+        return None
+    return f"{_ROCM_WINDOWS_INDEX_BASE}/{arch_family}/"
+
+
+def _detect_bnb_rocm_dll_ver() -> str | None:
+    """Scan the installed bitsandbytes package for libbitsandbytes_rocm{VER}.dll.
+
+    Returns the version suffix string (e.g. ``"72"``, ``"713"``) or ``None``
+    if bitsandbytes is not installed or no ROCm DLL is found.  Does NOT import
+    bitsandbytes — uses importlib.util.find_spec so it is safe to call before
+    BNB is imported.
+    """
+    import glob
+    import importlib.util
+    import re
+
+    spec = importlib.util.find_spec("bitsandbytes")
+    if spec is None or not spec.submodule_search_locations:
+        return None
+    all_vers: list[str] = []
+    for pkg_dir in spec.submodule_search_locations:
+        for dll in glob.glob(os.path.join(pkg_dir, "libbitsandbytes_rocm*.dll")):
+            m = re.search(r"libbitsandbytes_rocm(\d+)\.dll", os.path.basename(dll))
+            if m:
+                all_vers.append(m.group(1))
+    # Pick the highest numeric suffix so that e.g. "713" wins over "72" when
+    # both variants are present in the wheel.  Filesystem glob order is not
+    # guaranteed, so always sort rather than stopping at the first match.
+    return max(all_vers, key = lambda v: int(v)) if all_vers else None
+
+
 def _has_rocm_gpu() -> bool:
     """Return True only if an actual AMD GPU is visible (not just ROCm tools installed)."""
     import re
@@ -231,6 +420,26 @@ def _has_rocm_gpu() -> bool:
         if result.returncode == 0 and result.stdout.strip():
             if check_fn(result.stdout):
                 return True
+    # sysfs KFD topology fallback (Linux only) -- matches install.sh's
+    # runtime-only detection. On minimal package-managed installs (no
+    # rocminfo / no amd-smi GUI tools), the kernel exposes AMD GPUs via
+    # /sys/class/kfd so `studio update` can still detect the GPU and
+    # repair the venv.
+    if sys.platform != "win32":
+        try:
+            kfd_nodes = "/sys/class/kfd/kfd/topology/nodes"
+            if os.path.isdir(kfd_nodes):
+                for entry in os.listdir(kfd_nodes):
+                    gpu_id_path = os.path.join(kfd_nodes, entry, "gpu_id")
+                    try:
+                        with open(gpu_id_path) as fh:
+                            gpu_id = fh.read().strip()
+                    except OSError:
+                        continue
+                    if gpu_id and gpu_id != "0":  # gpu_id 0 = CPU node
+                        return True
+        except OSError:
+            pass
     return False
 
 
@@ -252,23 +461,199 @@ def _has_usable_nvidia_gpu() -> bool:
     return result.returncode == 0 and "GPU " in result.stdout
 
 
+def _detect_amd_gfx_codes() -> list[str]:
+    """Return the list of AMD gfx ISA strings visible to ROCm (e.g. ['gfx1151']).
+
+    Probes rocminfo first, then falls back to ``amd-smi list`` and
+    ``amd-smi static --asic`` for runtime-only Radeon hosts that ship
+    amd-smi but no rocminfo. Returns an empty list when no probe yields
+    a gfx target.
+    """
+    import re
+
+    def _extract(text: str) -> list[str]:
+        codes = re.findall(r"gfx([1-9][0-9a-z]{2,3})", text.lower())
+        return list(dict.fromkeys(f"gfx{c}" for c in codes))
+
+    probes: list[list[str]] = []
+    if shutil.which("rocminfo"):
+        probes.append(["rocminfo"])
+    if shutil.which("amd-smi"):
+        probes.append(["amd-smi", "list"])
+        probes.append(["amd-smi", "static", "--asic"])
+    for cmd in probes:
+        try:
+            result = subprocess.run(
+                cmd,
+                stdout = subprocess.PIPE,
+                stderr = subprocess.DEVNULL,
+                text = True,
+                timeout = 15,
+            )
+        except Exception:
+            continue
+        if result.returncode != 0 or not result.stdout.strip():
+            continue
+        codes = _extract(result.stdout)
+        if codes:
+            return codes
+    return []
+
+
+# Set by _ensure_rocm_torch() on success; suppresses the post-install AMD warning.
+_rocm_windows_torch_installed: bool = False
+
+
+def _install_bnb_windows_rocm() -> bool:
+    """Install the AMD Windows BNB prerelease wheel. Returns True on success.
+
+    The continuous-release wheel is intentionally mismatched: the filename
+    encodes version 1.33.7.preview (parsed as 1.33.7rc0 by PEP 440) while the
+    wheel metadata reports 0.50.0.dev0.  uv rejects this filename/metadata
+    mismatch; set UV_SKIP_WHEEL_FILENAME_CHECK=1 to bypass that check, then
+    restore the previous value (or remove the var) when done.
+    """
+    _bnb_win_url = _BNB_ROCM_PRERELEASE_URLS.get("win_amd64")
+    if _bnb_win_url is None:
+        return False
+    _old = os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK")
+    os.environ["UV_SKIP_WHEEL_FILENAME_CHECK"] = "1"
+    try:
+        _ok = pip_install_try(
+            "bitsandbytes (AMD Windows, pre-release main)",
+            "--force-reinstall",
+            "--no-cache-dir",
+            "--no-deps",
+            _bnb_win_url,
+            constrain = False,
+        )
+    finally:
+        if _old is None:
+            os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
+        else:
+            os.environ["UV_SKIP_WHEEL_FILENAME_CHECK"] = _old
+    if not _ok:
+        return False
+    # After install: detect the actual ROCm DLL suffix shipped in the wheel and
+    # set BNB_ROCM_VERSION so bitsandbytes loads the correct DLL regardless of
+    # what torch.version.hip reports.  The wheel may ship an older suffix (e.g.
+    # "72") while torch reports a newer HIP version (e.g. 7.13); the env var
+    # override ensures bitsandbytes does not fail looking for a non-existent DLL.
+    # The worker subprocess inherits this env var automatically.
+    # Fall back to "72" if detection fails (e.g. install was a no-op / dry-run).
+    if "BNB_ROCM_VERSION" not in os.environ:
+        _ver = _detect_bnb_rocm_dll_ver() or "72"
+        os.environ["BNB_ROCM_VERSION"] = _ver
+    return True
+
+
 def _ensure_rocm_torch() -> None:
     """Reinstall torch with ROCm wheels when the venv received CPU-only torch.
 
-    Runs only on Linux x86_64 hosts where an AMD GPU is present and the
-    ROCm runtime is detectable (rocminfo / amd-smi / hipconfig /
-    rocm-core package).  No-op when torch already links against HIP
-    (ROCm), on Windows / macOS, on non-x86_64 Linux (PyTorch does not
-    publish ROCm wheels for aarch64 / arm64), or on mixed AMD+NVIDIA
-    hosts (NVIDIA takes precedence).
+    On Linux x86_64: uses pytorch.org ROCm wheel index tags.
+    On Windows: uses AMD's repo.amd.com arch-specific pip index.
+    No-op on macOS, non-x86_64 Linux, NVIDIA-primary hosts, or when torch
+    already links against HIP.
     Uses pip_install() to respect uv, constraints, and --python targeting.
     """
-    # Explicit OS / architecture guards so the helper is safe to call
-    # from any context -- PyTorch only publishes ROCm wheels for
-    # linux_x86_64, so aarch64 / arm64 hosts must skip this repair path
-    # instead of failing the update with a missing-wheel error.
-    if IS_WINDOWS or IS_MACOS:
+    global _rocm_windows_torch_installed
+    # setup.ps1 sets this when it already installed AMD wheels; skip the probe
+    # only when torch is actually importable as ROCm. If the venv was wiped
+    # between runs, the stale env-var would suppress a needed reinstall.
+    if os.environ.get("UNSLOTH_ROCM_TORCH_INSTALLED") == "1":
+        _torch_ok = False
+        try:
+            _probe = subprocess.run(
+                [
+                    sys.executable,
+                    "-c",
+                    (
+                        "import torch; "
+                        "hip=getattr(torch.version,'hip','') or ''; "
+                        "import sys; "
+                        "sys.exit(0 if (hip or 'rocm' in torch.__version__.lower()) else 1)"
+                    ),
+                ],
+                stdout = subprocess.DEVNULL,
+                stderr = subprocess.DEVNULL,
+                timeout = 90,
+            )
+            _torch_ok = _probe.returncode == 0
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        if _torch_ok:
+            _rocm_windows_torch_installed = True
+            # setup.ps1 already installed ROCm torch, but we still need to install
+            # the AMD Windows BNB wheel here -- the PyPI bitsandbytes wheel ships
+            # only CUDA DLLs and will fail to load on ROCm.
+            _install_bnb_windows_rocm()
+            return
+        # torch was wiped between runs; fall through to the full install path
+    if IS_MACOS:
         return
+
+    if IS_WINDOWS:
+        if _has_usable_nvidia_gpu():
+            return
+        gfx_arch = _detect_windows_gfx_arch()
+        if not gfx_arch:
+            return  # no AMD GPU visible via hipinfo
+        # Probe whether torch already links against HIP.
+        _torch_already_rocm = False
+        try:
+            probe = subprocess.run(
+                [
+                    sys.executable,
+                    "-c",
+                    (
+                        "import torch; "
+                        "hip=getattr(torch.version,'hip','') or ''; "
+                        "ver=torch.__version__; "
+                        "print('yes' if hip or 'rocm' in ver.lower() else '')"
+                    ),
+                ],
+                stdout = subprocess.PIPE,
+                stderr = subprocess.DEVNULL,
+                timeout = 90,
+            )
+            if probe.returncode == 0 and probe.stdout.decode().strip() == "yes":
+                _torch_already_rocm = True
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        if not _torch_already_rocm:
+            index_url = _windows_rocm_index_url(gfx_arch)
+            if index_url is None:
+                print(
+                    f"   No AMD Windows torch index for GPU arch {gfx_arch} -- skipping"
+                )
+                return
+            print(f"   {gfx_arch} (Windows) -- installing torch from {index_url}")
+            pip_install(
+                f"ROCm torch (Windows, {gfx_arch})",
+                "--force-reinstall",
+                "--index-url",
+                index_url,
+                "torch",
+                "torchvision",
+                "torchaudio",
+                constrain = False,
+            )
+        # ROCm torch is installed (or already was); flag it so later install
+        # phases do not overwrite it with the generic CPU torch wheel. BNB is
+        # a separate dependency -- a BNB install failure must NOT roll the
+        # torch ROCm install back.
+        _rocm_windows_torch_installed = True
+        # Always install AMD Windows bitsandbytes -- the PyPI wheel ships only
+        # CUDA DLLs and will fail to load on ROCm.  Install even when torch was
+        # already a ROCm build so that `studio update` repairs a broken bnb.
+        if not _install_bnb_windows_rocm():
+            print(
+                "   Warning: AMD Windows bitsandbytes install failed; "
+                "ROCm torch is installed but bitsandbytes may need manual install"
+            )
+        return
+
+    # ── Linux x86_64 only: PyTorch ROCm wheels are not published for aarch64 ──
     if platform.machine().lower() not in {"x86_64", "amd64"}:
         return
     # NVIDIA takes precedence on mixed hosts -- but only if an actual GPU is usable
@@ -297,11 +682,19 @@ def _ensure_rocm_torch() -> None:
             [
                 sys.executable,
                 "-c",
-                "import torch; print(getattr(torch.version,'hip','') or '')",
+                (
+                    "import torch; "
+                    "hip=getattr(torch.version,'hip','') or ''; "
+                    "ver=getattr(torch,'__version__','').lower(); "
+                    # Print the HIP version when present (back-compat), else
+                    # "rocm" sentinel when only torch.__version__ flags ROCm
+                    # (AMD SDK / Radeon wheels). Empty string = CPU/CUDA.
+                    "print(hip if hip else ('rocm' if 'rocm' in ver else ''))"
+                ),
             ],
             stdout = subprocess.PIPE,
             stderr = subprocess.DEVNULL,
-            timeout = 30,
+            timeout = 90,
         )
     except (OSError, subprocess.TimeoutExpired):
         probe = None
@@ -313,7 +706,83 @@ def _ensure_rocm_torch() -> None:
 
     rocm_torch_ready = has_hip_torch
 
-    if not has_hip_torch:
+    # Strix Halo / Strix Point (gfx1151 / gfx1150) segfault under ROCm 7.1
+    # in torch._grouped_mm. AMD's per-gfx repo ships torch 2.11.0+rocm7.13.0
+    # with the real fix, so route those hosts there instead of the generic
+    # pytorch.org rocm7.1 wheel. Mirrors install.sh's Strix override.
+    # On mixed hosts (Strix iGPU + non-Strix dGPU), only route to the AMD
+    # per-gfx index when the GPU HIP will actually run on is the Strix one --
+    # otherwise the dGPU would get an incompatible wheel. Use HIP_VISIBLE_DEVICES
+    # to determine the runtime target.
+    _strix_override_url: "str | None" = None
+    _strix_override_pkgs: "tuple[str, str, str] | None" = None
+    if ver < (7, 2):
+        gfx_codes = _detect_amd_gfx_codes()
+        _strix_gfx = {"gfx1151", "gfx1150"}
+        _detected_strix = _strix_gfx.intersection(gfx_codes)
+        if _detected_strix:
+            # Pick the runtime-visible GPU. If HIP_VISIBLE_DEVICES selects a
+            # specific index into gfx_codes, use that gfx; else default to the
+            # first listed GPU. Skip the override unless the resolved GPU is
+            # Strix.
+            _runtime_gfx = (
+                gfx_codes[_pick_visible_index(len(gfx_codes))] if gfx_codes else None
+            )
+            if _runtime_gfx in _strix_gfx:
+                _selected_gfx = _runtime_gfx
+                _amd_mirror = (
+                    os.environ.get("UNSLOTH_AMD_ROCM_MIRROR")
+                    or "https://repo.amd.com/rocm/whl"
+                ).rstrip("/")
+                _strix_override_url = f"{_amd_mirror}/{_selected_gfx}/"
+                _strix_override_pkgs = (
+                    "torch>=2.11.0,<2.12.0",
+                    # Pin torchvision/torchaudio to the 2.11.x-compatible range.
+                    # The install uses --index-url (exclusive, no PyPI fallback),
+                    # so bare unversioned names risk resolving a build from AMD's
+                    # index that targets a different torch major (e.g. 0.27 built
+                    # against torch 2.12), which would fail at runtime with an
+                    # ABI/version mismatch. Matches _ROCM_TORCH_CONSTRAINT["rocm7.2"].
+                    "torchvision>=0.26.0,<0.27.0",
+                    "torchaudio>=2.11.0,<2.12.0",
+                )
+                print(
+                    f"\n   {_selected_gfx} (AMD Strix) is the runtime target with ROCm "
+                    f"{ver[0]}.{ver[1]}.\n"
+                    f"   ROCm 7.1 has a known _grouped_mm segfault on this GPU;\n"
+                    f"   routing torch install to AMD's arch-specific index\n"
+                    f"   ({_strix_override_url}) which serves torch 2.11.0+rocm7.13.0\n"
+                    f"   with the upstream fix.\n"
+                )
+            else:
+                _gfx_str = ", ".join(sorted(_detected_strix))
+                print(
+                    f"\n   Strix GPU ({_gfx_str}) present but HIP_VISIBLE_DEVICES "
+                    f"selects a non-Strix runtime target ({_runtime_gfx});\n"
+                    f"   skipping AMD per-gfx index override.\n"
+                )
+
+    # Strix override on ROCm 7.1 must fire even when has_hip_torch is True --
+    # an existing torch with `torch.version.hip == "7.1"` is exactly the broken
+    # combo the override is meant to repair, so skipping it leaves users on
+    # the known _grouped_mm segfault.
+    if _strix_override_url is not None and _strix_override_pkgs is not None:
+        index_url = _strix_override_url
+        _torch_pkg, _vision_pkg, _audio_pkg = _strix_override_pkgs
+        print(f"   Strix ROCm 7.1 override -- installing torch from {index_url}")
+        pip_install(
+            "ROCm torch (Strix arch-specific)",
+            "--force-reinstall",
+            "--no-cache-dir",
+            _torch_pkg,
+            _vision_pkg,
+            _audio_pkg,
+            "--index-url",
+            index_url,
+            constrain = False,
+        )
+        rocm_torch_ready = True
+    elif not has_hip_torch:
         # Select best matching wheel tag (newest ROCm version <= installed)
         tag = next(
             (
@@ -331,13 +800,16 @@ def _ensure_rocm_torch() -> None:
         else:
             index_url = f"{_PYTORCH_WHL_BASE}/{tag}"
             print(f"   ROCm {ver[0]}.{ver[1]} -- installing torch from {index_url}")
+            _torch_pkg, _vision_pkg, _audio_pkg = _ROCM_TORCH_PKG_SPECS.get(
+                tag, _ROCM_TORCH_PKG_SPECS["_default"]
+            )
             pip_install(
                 f"ROCm torch ({tag})",
                 "--force-reinstall",
                 "--no-cache-dir",
-                "torch>=2.4,<2.11.0",
-                "torchvision<0.26.0",
-                "torchaudio<2.11.0",
+                _torch_pkg,
+                _vision_pkg,
+                _audio_pkg,
                 "--index-url",
                 index_url,
                 constrain = False,
@@ -346,7 +818,9 @@ def _ensure_rocm_torch() -> None:
 
     # Install bitsandbytes only when torch links against ROCm. Prefers the
     # continuous-release_main wheel (bnb PR #1887 4-bit GEMV fix) and falls
-    # back to PyPI when the pre-release URL is unreachable.
+    # back to PyPI when the pre-release wheel cannot be installed. Use pip for
+    # the pre-release wheel because uv rejects the wheel's filename/metadata
+    # version mismatch.
     if rocm_torch_ready:
         _bnb_url = _bnb_rocm_prerelease_url()
         _bnb_installed = False
@@ -358,11 +832,12 @@ def _ensure_rocm_torch() -> None:
                 "--no-deps",
                 _bnb_url,
                 constrain = False,
+                force_pip = True,
             )
             if not _bnb_installed:
                 print(
                     _red(
-                        "   bnb pre-release unreachable; falling back to PyPI "
+                        "   bnb pre-release install failed; falling back to PyPI "
                         "(4-bit decode will be broken on ROCm)"
                     )
                 )
@@ -809,6 +1284,7 @@ def pip_install_try(
     label: str,
     *args: str,
     constrain: bool = True,
+    force_pip: bool = False,
 ) -> bool:
     """Like pip_install but returns False on failure instead of exiting.
     For optional installs with a follow-up fallback.
@@ -819,7 +1295,7 @@ def pip_install_try(
         constraint_args_pip = ["-c", str(CONSTRAINTS)]
         constraint_args_uv = ["-c", _uv_safe_path(CONSTRAINTS)]
 
-    if USE_UV:
+    if USE_UV and not force_pip:
         cmd = _build_uv_cmd(args) + constraint_args_uv
     else:
         cmd = _build_pip_cmd(args) + constraint_args_pip
@@ -948,8 +1424,12 @@ def install_python_stack() -> int:
     base_total = 10 if IS_WINDOWS else 11
     if IS_MACOS:
         base_total -= 1  # triton step is skipped on macOS
-    if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:
-        base_total += 3
+    if not IS_MACOS and not NO_TORCH:
+        base_total += 1  # ROCm torch check (line 1526) -- all non-macOS platforms
+        if not IS_WINDOWS:
+            base_total += (
+                2  # flash-attn (line 1620) + ROCm torch final (line 1705) -- Linux only
+            )
     _TOTAL = (base_total - 1) if skip_base else base_total
 
     # 1. Try to use uv for faster installs (must happen before pip upgrade
@@ -1121,12 +1601,12 @@ def install_python_stack() -> int:
     # 2b. AMD ROCm: reinstall torch with HIP wheels if the host has ROCm but the
     #     venv received CPU-only torch (common when pip resolves torch from PyPI).
     #     Must come immediately after base packages so torch is present for inspection.
-    if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:
+    if not IS_MACOS and not NO_TORCH:
         _progress("ROCm torch check")
         _ensure_rocm_torch()
 
-    # Windows + AMD GPU: PyTorch does not publish ROCm wheels for Windows.
-    # Detect and warn so users know manual steps are needed for GPU training.
+    # Windows + AMD GPU: if ROCm torch was not installed (wrong Python version
+    # or unknown ROCm version), warn the user.
     if IS_WINDOWS and not NO_TORCH and not _has_usable_nvidia_gpu():
         # Validate actual AMD GPU presence (not just tool existence)
         import re as _re_win
@@ -1155,14 +1635,14 @@ def install_python_stack() -> int:
             if _wr.returncode == 0 and _check_fn(_wr.stdout):
                 _win_amd_gpu = True
                 break
-        if _win_amd_gpu:
+        if _win_amd_gpu and not _rocm_windows_torch_installed:
             _safe_print(
                 _dim("  Note:"),
-                "AMD GPU detected on Windows. ROCm-enabled PyTorch must be",
+                "AMD GPU detected but ROCm PyTorch could not be auto-installed.",
             )
             _safe_print(
                 " " * 8,
-                "installed manually. See: https://docs.unsloth.ai/get-started/install-and-update/amd",
+                "Manual install may be required. See: https://docs.unsloth.ai/get-started/install-and-update/amd",
             )
 
     # 3. Extra dependencies
@@ -1189,10 +1669,17 @@ def install_python_stack() -> int:
         _progress("dependency overrides (skipped, no torch)")
     else:
         _progress("dependency overrides")
+        _override_extra_args: tuple[str, ...] = ()
+        if _rocm_windows_torch_installed:
+            # torchao in overrides.txt declares torch as a dependency; without
+            # --no-deps uv would resolve and install CPU torch from PyPI,
+            # overwriting the AMD ROCm wheels we just installed.
+            _override_extra_args = ("--no-deps",)
         pip_install(
             "Installing dependency overrides",
             "--force-reinstall",
             "--no-cache-dir",
+            *_override_extra_args,
             req = REQ_ROOT / "overrides.txt",
         )
 
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index afa00409fb..e276b2151d 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -685,13 +685,228 @@ if (-not $HasNvidiaSmi) {
         }
     }
 }
+# ── AMD ROCm detection (Windows): probe hipinfo/amd-smi for actual GPU ──
+$HasROCm = $false
+$HipSdkInstalled = $false   # HIP SDK binary found (independent of device accessibility)
+$ROCmGpuLabel = $null
+$script:ROCmGfxArch = $null
 if (-not $HasNvidiaSmi) {
+    # hipinfo: PATH first, then HIP_PATH/ROCM_PATH bin fallback (mirrors NVIDIA smi path resolution).
+    # AMD HIP SDK sets HIP_PATH but may not add the bin dir to PATH depending on install type.
+    $hipinfoExe = Get-Command hipinfo -ErrorAction SilentlyContinue
+    if (-not $hipinfoExe) {
+        $hipRoot     = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
+        $hipEnvLabel = if ($env:HIP_PATH) { "HIP_PATH"    } else                    { "ROCM_PATH"    }
+        if ($hipRoot) {
+            $hipinfoCandidate = Join-Path $hipRoot "bin\hipinfo.exe"
+            if (Test-Path $hipinfoCandidate) {
+                substep "[WARN] hipinfo not on PATH -- located via ${hipEnvLabel}: $hipinfoCandidate" "Yellow"
+                substep "       Add '$(Join-Path $hipRoot 'bin')' to your PATH to suppress this warning" "Yellow"
+                substep "       Quick fix: [Environment]::SetEnvironmentVariable('PATH',`$env:PATH+';$(Join-Path $hipRoot 'bin')','User')" "Yellow"
+                $hipinfoExe = [PSCustomObject]@{ Source = $hipinfoCandidate }
+            } else {
+                substep "[WARN] ${hipEnvLabel}=$hipRoot is set but hipinfo.exe not found at $hipinfoCandidate" "Yellow"
+                substep "       HIP SDK install may be incomplete -- re-install from:" "Yellow"
+                substep "       https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+            }
+        }
+    }
+    if ($hipinfoExe) {
+        $HipSdkInstalled = $true   # binary found → SDK is installed regardless of device state
+        try {
+            $hipOut = & $hipinfoExe.Source 2>&1 | Out-String
+            if ($LASTEXITCODE -eq 0 -and $hipOut -match "(?i)gcnArchName") {
+                $HasROCm = $true
+                $_hipAllArches = @([regex]::Matches($hipOut, "(?im)^\s*gcnArchName\s*:\s*(\S+)") | ForEach-Object { ($_.Groups[1].Value -split ':')[0].Trim().ToLower() })
+                $_hipVisIdx = if ($env:HIP_VISIBLE_DEVICES -match '^\d') { [int]($env:HIP_VISIBLE_DEVICES -split ',')[0] } elseif ($env:ROCR_VISIBLE_DEVICES -match '^\d') { [int]($env:ROCR_VISIBLE_DEVICES -split ',')[0] } else { 0 }
+                if ($_hipAllArches.Count -gt 0) {
+                    $script:ROCmGfxArch = if ($_hipVisIdx -lt $_hipAllArches.Count) { $_hipAllArches[$_hipVisIdx] } else { $_hipAllArches[0] }
+                    $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
+                } else {
+                    $ROCmGpuLabel = "AMD ROCm"
+                }
+            } elseif ($LASTEXITCODE -ne 0) {
+                # hipinfo ran but returned a HIP runtime error (e.g. "no ROCm-capable device detected")
+                $firstLine = ($hipOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1)
+                substep "[WARN] hipinfo returned a HIP runtime error (exit $LASTEXITCODE)" "Yellow"
+                substep "       $firstLine" "Yellow"
+                substep "       Ensure ROCm drivers are installed: https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+            }
+        } catch {}
+    }
+    # amd-smi fallback: HIP runtime present but hipinfo unavailable (no full HIP SDK).
+    # Confirms GPU visibility via 'list', then attempts 'static --asic' to extract
+    # the gfx arch that hipinfo would have provided.  Critical for Strix Halo
+    # (gfx1151) and other iGPUs where only the HIP runtime is installed.
+    if (-not $HasROCm) {
+        $amdSmiExe = Get-Command "amd-smi" -ErrorAction SilentlyContinue
+        if ($amdSmiExe) {
+            try {
+                $smiOut = & $amdSmiExe.Source list 2>&1 | Out-String
+                if ($LASTEXITCODE -eq 0 -and $smiOut -match "(?im)^GPU\s*[:\[]\s*\d") {
+                    $HasROCm = $true
+                    # Attempt 1: newer amd-smi versions embed the gfx arch in list output.
+                    # Collect ALL gfx tokens in output order so that on mixed-arch systems
+                    # we can honour HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES and pick the
+                    # arch for the *runtime-visible* GPU rather than always the first one.
+                    # Do NOT deduplicate: a dual same-arch system (e.g. two gfx1151 APUs)
+                    # must produce a 2-element array so HIP_VISIBLE_DEVICES=1 selects the
+                    # second GPU rather than triggering a false out-of-range warning.
+                    # Note: this mapping assumes amd-smi lists GPUs in the same order as
+                    # HIP enumerates them (both follow PCI bus order in practice); it may
+                    # give the wrong arch when GPU indices are non-contiguous (very rare).
+                    $allGfxArches = @([regex]::Matches($smiOut, '(?i)\b(gfx\d+[a-z]?)\b') |
+                        ForEach-Object { $_.Groups[1].Value.ToLower() })
+                    if ($allGfxArches.Count -gt 0) {
+                        # Resolve which GPU index is runtime-visible.  When a single
+                        # integer index is set, use it; fall back to index 0 otherwise
+                        # (comma-separated lists or unset → first GPU, same as before).
+                        $visGpu = if ($env:HIP_VISIBLE_DEVICES) { $env:HIP_VISIBLE_DEVICES }
+                                  elseif ($env:ROCR_VISIBLE_DEVICES) { $env:ROCR_VISIBLE_DEVICES }
+                                  else { $null }
+                        $gpuIdx = 0
+                        if ($visGpu -match '^\s*(\d+)\s*$') { $gpuIdx = [int]$Matches[1] }
+                        if ($gpuIdx -ge $allGfxArches.Count) {
+                            substep "[WARN] HIP/ROCR_VISIBLE_DEVICES index $gpuIdx is out of range ($($allGfxArches.Count) GPU(s) detected); defaulting to GPU 0 for arch selection" "Yellow"
+                            $gpuIdx = 0
+                        }
+                        $script:ROCmGfxArch = $allGfxArches[$gpuIdx]
+                        $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
+                    } else {
+                        # Attempt 2: 'static --asic' exposes ASIC details on ROCm 6+,
+                        # including the GFX target needed for wheel index selection.
+                        $smiAsicOut = ""
+                        try { $smiAsicOut = & $amdSmiExe.Source static --asic 2>&1 | Out-String } catch {}
+                        if ($smiAsicOut -match "(?i)\b(gfx\d+[a-z]?)\b") {
+                            $script:ROCmGfxArch = $Matches[1].ToLower()
+                            $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
+                        } elseif ($smiAsicOut -match "(?im)Market.?Name\s*[:\|]\s*([^\r\n]+)") {
+                            $ROCmGpuLabel = "AMD ROCm ($($Matches[1].Trim()))"
+                        } else {
+                            $ROCmGpuLabel = "AMD ROCm"
+                        }
+                    }
+                }
+            } catch {}
+        }
+    }
+    # WMI fallback: AMD GPU in device list but no HIP SDK → guide the user.
+    # WMI gives a marketing name (e.g. "AMD Radeon 890M") but never a gfx arch.
+    # $HasROCm is intentionally NOT set here — we cannot confirm ROCm runtime
+    # support without hipinfo or amd-smi.  The name is saved to $ROCmGpuLabel
+    # so the name-based inference below can still attempt an arch lookup.
+    if (-not $HasROCm) {
+        try {
+            $wmiGpu = Get-WmiObject Win32_VideoController -ErrorAction SilentlyContinue |
+                Where-Object { $_.Name -match "AMD|Radeon" } |
+                Select-Object -First 1
+            if ($wmiGpu) { $ROCmGpuLabel = $wmiGpu.Name }
+        } catch {}
+    }
+    # ── Arch resolution: env-var override → name inference ──────────────────
+    # Runs after all probe methods.  Covers users whose amd-smi version is too
+    # old to report the GFX target and who don't have hipinfo (HIP-runtime-only
+    # installs, common on Strix Halo / iGPU systems).
+    if ($HasROCm -and -not $script:ROCmGfxArch) {
+        # 1. Manual override: set UNSLOTH_ROCM_GFX_ARCH=gfx1151 before running.
+        if ($env:UNSLOTH_ROCM_GFX_ARCH) {
+            $script:ROCmGfxArch = $env:UNSLOTH_ROCM_GFX_ARCH.Trim().ToLower()
+            $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
+            substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $script:ROCmGfxArch" "Cyan"
+        }
+        # 2. Best-effort name → arch lookup from marketing name (amd-smi / WMI).
+        #    Ordered most-specific first; first match wins.
+        elseif ($ROCmGpuLabel) {
+            $nameArchTable = @(
+                @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4
+                @{ P = "9070|9060";                                            A = "gfx1200" }  # RDNA 4
+                @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";  A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
+                @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" } # RDNA 3.5 iGPU (Strix Point)
+                @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                       A = "gfx1100" }  # RDNA 3 desktop
+                @{ P = "RX 7600";                                              A = "gfx1102" }  # RDNA 3
+                @{ P = "780M|760M|740M|Phoenix";                               A = "gfx1103" }  # RDNA 3 iGPU (Phoenix)
+            )
+            foreach ($row in $nameArchTable) {
+                if ($ROCmGpuLabel -match $row.P) {
+                    $script:ROCmGfxArch = $row.A
+                    $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
+                    substep "gfx arch inferred from GPU name: $script:ROCmGfxArch" "Cyan"
+                    substep "Tip: set UNSLOTH_ROCM_GFX_ARCH=$script:ROCmGfxArch to skip inference next time" "Cyan"
+                    break
+                }
+            }
+        }
+    }
+    # Capture ROCm version early for display and wheel selection.
+    # Run whenever the HIP SDK binary is present, not just when the device is accessible --
+    # hipconfig --version works even when hipinfo reports no ROCm device (driver issue).
+    if ($HasROCm -or $HipSdkInstalled) {
+        $script:ROCmVersion = $null
+        $hipConfigExe = Get-Command hipconfig -ErrorAction SilentlyContinue
+        if (-not $hipConfigExe) {
+            $hipRoot = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { $null }
+            if ($hipRoot) {
+                $hipConfigCandidate = Join-Path $hipRoot "bin\hipconfig.exe"
+                if (Test-Path $hipConfigCandidate) {
+                    $hipConfigEnvLabel = if ($env:HIP_PATH) { "HIP_PATH" } else { "ROCM_PATH" }
+                    substep "[WARN] hipconfig not on PATH -- located via ${hipConfigEnvLabel}: $hipConfigCandidate" "Yellow"
+                    $hipConfigExe = [PSCustomObject]@{ Source = $hipConfigCandidate }
+                }
+            }
+        }
+        if ($hipConfigExe) {
+            try {
+                $hipVerOut = & $hipConfigExe.Source --version 2>&1 | Out-String
+                if ($LASTEXITCODE -eq 0) {
+                    $hipVerLine = ($hipVerOut -split '\r?\n' | Where-Object { $_.Trim() } | Select-Object -First 1).Trim()
+                    if ($hipVerLine -match '(\d+\.\d+)') {
+                        $script:ROCmVersion     = $Matches[1]
+                        $script:ROCmVersionFull = $hipVerLine
+                    }
+                }
+            } catch {}
+        }
+        if (-not $script:ROCmVersion) {
+            $amdSmiVer = Get-Command "amd-smi" -ErrorAction SilentlyContinue
+            if ($amdSmiVer) {
+                try {
+                    $smiVerOut = & $amdSmiVer.Source version 2>&1 | Out-String
+                    if ($LASTEXITCODE -eq 0 -and $smiVerOut -match 'ROCm version:\s*(\d+\.\d+)') { $script:ROCmVersion = $Matches[1] }
+                } catch {}
+            }
+        }
+    }
+}
+
+if ($HasNvidiaSmi) {
+    step "gpu" "NVIDIA GPU detected"
+} elseif ($HasROCm) {
+    step "gpu" $ROCmGpuLabel
+    $hipSdkPath = if ($env:HIP_PATH) { $env:HIP_PATH } elseif ($env:ROCM_PATH) { $env:ROCM_PATH } else { "on system PATH" }
+    substep "HIP SDK: $hipSdkPath"
+    if ($script:ROCmVersionFull) { substep "hipconfig: $script:ROCmVersionFull" }
+} elseif ($HipSdkInstalled -and $ROCmGpuLabel) {
+    # HIP SDK is installed but ROCm can't see the device (driver issue, not SDK issue)
+    $sdkVer = if ($script:ROCmVersionFull) { " (HIP $script:ROCmVersionFull)" } else { "" }
     Write-Host ""
-    step "gpu" "none (chat-only / GGUF)" "Yellow"
-    substep "Training and GPU inference require an NVIDIA GPU with drivers installed." "Yellow"
+    step "gpu" "AMD GPU detected -- not ROCm-accessible$sdkVer" "Yellow"
+    substep "Detected: $ROCmGpuLabel" "Yellow"
+    substep "[WARN] HIP SDK is installed but hipinfo reports no ROCm-capable device." "Yellow"
+    substep "       This is a driver issue, not an SDK issue." "Yellow"
+    substep "       Ensure the ROCm compute driver is installed alongside the display driver:" "Yellow"
+    substep "       https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+} elseif ($ROCmGpuLabel) {
+    Write-Host ""
+    step "gpu" "AMD GPU detected -- HIP SDK not found" "Yellow"
+    substep "Detected: $ROCmGpuLabel" "Yellow"
+    substep "Install the HIP SDK for ROCm GPU inference:" "Yellow"
+    substep "https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
     Write-Host ""
 } else {
-    step "gpu" "NVIDIA GPU detected"
+    Write-Host ""
+    step "gpu" "none (chat-only / GGUF)" "Yellow"
+    substep "Training and GPU inference require an NVIDIA or AMD ROCm GPU." "Yellow"
+    Write-Host ""
 }
 
 # ============================================
@@ -1102,6 +1317,13 @@ if (-not $CudaArch) {
     step "cuda" "skipped (no NVIDIA GPU detected)" "Yellow"
 }
 
+if ($HasROCm) {
+    $rocmVerLabel = if ($script:ROCmVersionFull) { "ROCm $script:ROCmVersionFull" } elseif ($script:ROCmVersion) { "ROCm $script:ROCmVersion" } else { "ROCm (version unknown)" }
+    step "rocm" $rocmVerLabel
+} elseif ($ROCmGpuLabel) {
+    step "rocm" "HIP SDK not found -- GPU-accelerated training unavailable" "Yellow"
+}
+
 # ============================================
 # 1f. Node.js / npm (skip if pip-installed or Tauri -- only needed for frontend build)
 # ============================================
@@ -1516,7 +1738,7 @@ if (-not $PythonCmd) {
     exit 1
 }
 
-substep "Using $PythonCmd ($(& $PythonCmd --version 2>&1))"
+substep "Python found: $PythonCmd"
 
 # The venv must already exist (created by install.ps1); this script only
 # updates packages. UNSLOTH_STUDIO_HOME (or STUDIO_HOME alias) overrides the
@@ -1684,6 +1906,13 @@ if (-not (Test-Path -LiteralPath $VenvDir)) {
     exit 1
 } else {
     substep "reusing existing virtual environment at $VenvDir"
+    $_venvPyExe = Join-Path $VenvDir "Scripts\python.exe"
+    if (Test-Path -LiteralPath $_venvPyExe) {
+        try {
+            $_venvPyVer = (& $_venvPyExe --version 2>&1 | Out-String).Trim()
+            if ($_venvPyVer) { substep $_venvPyVer }
+        } catch {}
+    }
 }
 
 # pip and python write to stderr even on success (progress bars, warnings).
@@ -1795,9 +2024,91 @@ if ($HasNvidiaSmi) {
     $CuTag = "cpu"
 }
 
+# ── GPU arch → newest compatible Windows ROCm wheel release ──
+# Wheels bundle their own ROCm runtime; the installed HIP SDK version does
+# not constrain which release to use.  Always picks the newest release that
+# supports the GPU architecture.
+# ── AMD Windows ROCm torch override ──────────────────────────────────────────
+# Uses AMD's arch-specific pip index (repo.amd.com/rocm/whl/{arch}/).
+# Wheels bundle their own ROCm runtime; HIP SDK version is irrelevant.
+$ROCmGfxArch = $script:ROCmGfxArch
+$ROCmIndexUrl = $null
+if ($HasROCm -and $CuTag -eq "cpu") {
+    $amdIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl" }
+    $archFamilyMap = @{
+        "gfx1201" = "gfx120X-all"; "gfx1200" = "gfx120X-all"  # RDNA 4
+        "gfx1151" = "gfx1151";     "gfx1150" = "gfx1150"       # RDNA 3.5 (Strix Halo/Point)
+        "gfx1103" = "gfx110X-all"; "gfx1102" = "gfx110X-all"   # RDNA 3
+        "gfx1101" = "gfx110X-all"; "gfx1100" = "gfx110X-all"
+        "gfx90a"  = "gfx90a";      "gfx908"  = "gfx908"        # MI200/MI100
+    }
+    # gfx120X and Strix have a null _grouped_mm kernel on torch <2.11.0.
+    # Mirrors the $torchFloorMap in install.ps1 so both installers enforce
+    # the same floor and ceiling when pulling from AMD's per-arch index.
+    $torchFloorMap = @{
+        "gfx1201" = "torch>=2.11.0,<2.12.0"; "gfx1200" = "torch>=2.11.0,<2.12.0"
+        "gfx1151" = "torch>=2.11.0,<2.12.0"; "gfx1150" = "torch>=2.11.0,<2.12.0"
+    }
+    # Companion ranges for torchvision/torchaudio -- must stay in sync with the
+    # torch ceiling so pip can always find a consistent trio on AMD's per-arch
+    # index.  AMD publishes each package independently and may add a newer
+    # torchvision (e.g. 0.27 for torch 2.12) before removing 0.26, which would
+    # cause pip to resolve an ABI-incompatible set if these are left bare.
+    # Matches _ROCM_TORCH_PKG_SPECS["rocm7.2"] in install_python_stack.py.
+    # Bump all three ceilings together when torch 2.12.x is validated.
+    $torchvisionFloorMap = @{
+        "gfx1201" = "torchvision>=0.26.0,<0.27.0"; "gfx1200" = "torchvision>=0.26.0,<0.27.0"
+        "gfx1151" = "torchvision>=0.26.0,<0.27.0"; "gfx1150" = "torchvision>=0.26.0,<0.27.0"
+    }
+    $torchaudioFloorMap = @{
+        "gfx1201" = "torchaudio>=2.11.0,<2.12.0"; "gfx1200" = "torchaudio>=2.11.0,<2.12.0"
+        "gfx1151" = "torchaudio>=2.11.0,<2.12.0"; "gfx1150" = "torchaudio>=2.11.0,<2.12.0"
+    }
+    $archFamily = if ($ROCmGfxArch -and $archFamilyMap.ContainsKey($ROCmGfxArch)) { $archFamilyMap[$ROCmGfxArch] } else { $null }
+    $ROCmTorchSpec  = if ($ROCmGfxArch -and $torchFloorMap.ContainsKey($ROCmGfxArch))        { $torchFloorMap[$ROCmGfxArch]        } else { "torch" }
+    $ROCmVisionSpec = if ($ROCmGfxArch -and $torchvisionFloorMap.ContainsKey($ROCmGfxArch))  { $torchvisionFloorMap[$ROCmGfxArch]  } else { "torchvision" }
+    $ROCmAudioSpec  = if ($ROCmGfxArch -and $torchaudioFloorMap.ContainsKey($ROCmGfxArch))   { $torchaudioFloorMap[$ROCmGfxArch]   } else { "torchaudio" }
+    if ($archFamily) {
+        $ROCmIndexUrl = "$amdIndexBase/$archFamily/"
+    } elseif ($ROCmGfxArch) {
+        # GPU arch detected but not in the supported wheel map — warn explicitly
+        # so the user knows why they are getting CPU PyTorch instead of ROCm.
+        substep "[WARN] AMD GPU ($ROCmGfxArch) not in supported arch list -- falling back to CPU-only PyTorch" "Yellow"
+        substep "       Supported: gfx1200/1201 (RDNA 4), gfx1150/1151 (RDNA 3.5), gfx1100-1103 (RDNA 3), gfx90a, gfx908" "Yellow"
+    } else {
+        # HIP SDK present ($HasROCm=true via amd-smi) but gcnArchName was not
+        # readable — warn rather than silently falling back to CPU PyTorch.
+        substep "[WARN] AMD GPU detected (HIP SDK present) but GPU arch could not be read -- falling back to CPU-only PyTorch" "Yellow"
+        substep "       Arch detection requires hipinfo to report gcnArchName. Re-install the HIP SDK if this is unexpected." "Yellow"
+    }
+}
+
 $PyTorchWhlBase = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
 
-if ($CuTag -eq "cpu") {
+if ($ROCmIndexUrl) {
+    substep "installing PyTorch (AMD ROCm, $ROCmGfxArch)..."
+    if ($ROCmTorchSpec -ne "torch") {
+        substep "  enforcing $ROCmTorchSpec $ROCmVisionSpec $ROCmAudioSpec (known _grouped_mm bug in older wheels)" "Cyan"
+    }
+    if ($script:UnslothVerbose) {
+        Fast-Install $ROCmTorchSpec $ROCmVisionSpec $ROCmAudioSpec --force-reinstall --index-url $ROCmIndexUrl
+        $torchInstallExit = $LASTEXITCODE
+        $output = ""
+    } else {
+        $output = Fast-Install $ROCmTorchSpec $ROCmVisionSpec $ROCmAudioSpec --force-reinstall --index-url $ROCmIndexUrl | Out-String
+        $torchInstallExit = $LASTEXITCODE
+    }
+    if ($torchInstallExit -ne 0) {
+        Write-Host "[WARN] AMD ROCm PyTorch install failed -- falling back to CPU" -ForegroundColor Yellow
+        Write-Host $output -ForegroundColor Yellow
+        $ROCmIndexUrl = $null
+    } else {
+        # Tell install_python_stack.py to skip probe + suppress manual-install warning.
+        $env:UNSLOTH_ROCM_TORCH_INSTALLED = "1"
+    }
+}
+
+if (-not $ROCmIndexUrl -and $CuTag -eq "cpu") {
     substep "installing PyTorch (CPU-only)..."
     if ($script:UnslothVerbose) {
         Fast-Install torch torchvision torchaudio --index-url "$PyTorchWhlBase/cpu"
@@ -1812,7 +2123,7 @@ if ($CuTag -eq "cpu") {
         Write-Host $output -ForegroundColor Red
         exit 1
     }
-} else {
+} elseif (-not $ROCmIndexUrl) {
     substep "installing PyTorch with CUDA support ($CuTag)..."
     substep "(This download is ~2.8 GB -- may take a few minutes)"
     if ($script:UnslothVerbose) {
@@ -2115,6 +2426,23 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
     substep "installing prebuilt llama.cpp bundle (preferred path)..."
     if (Test-Path -LiteralPath $LlamaCppDir) {
         substep "Existing llama.cpp install detected -- validating staged prebuilt update before replacement"
+        # If the existing install is the wrong kind (e.g. windows-cpu on a ROCm
+        # machine that should have windows-hip), remove it so the installer is
+        # forced to download the correct variant rather than skipping on tag match.
+        $existingMetaPath = Join-Path $LlamaCppDir "UNSLOTH_PREBUILT_INFO.json"
+        if (Test-Path $existingMetaPath) {
+            try {
+                $existingMeta = Get-Content $existingMetaPath -Raw | ConvertFrom-Json
+                $existingKind = $existingMeta.install_kind
+                $expectedKind = if ($HasROCm) { "windows-hip" } elseif ($HasNvidiaSmi) { "windows-cuda" } else { "windows-cpu" }
+                if ($existingKind -and $existingKind -ne $expectedKind) {
+                    substep "Removing mismatched llama.cpp install (found '$existingKind', need '$expectedKind')..."
+                    Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
+                }
+            } catch {
+                # unreadable metadata -- let the installer handle it
+            }
+        }
     }
     # why: install_llama_prebuilt.py uses os.replace(), which would displace
     # an unrelated $env:UNSLOTH_STUDIO_HOME\llama.cpp before the source-build
@@ -2129,6 +2457,9 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
             "--published-repo", $HelperReleaseRepo,
             "--simple-policy"
         )
+        if ($HasROCm) {
+            $prebuiltArgs += "--has-rocm"
+        }
         if ($env:UNSLOTH_LLAMA_RELEASE_TAG) {
             $prebuiltArgs += @("--published-release-tag", $env:UNSLOTH_LLAMA_RELEASE_TAG)
         }
diff --git a/studio/setup.sh b/studio/setup.sh
index f2395255c0..f178a5e5d7 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -659,6 +659,81 @@ if [ "$_NEED_T5_INSTALL" = true ]; then
 fi
 fi
 
+# ── GPU detection summary (mirrors setup.ps1 step "gpu" block) ──
+_setup_amd_detected=false
+_setup_gfx_all=""
+_setup_mkt=""
+if command -v rocminfo >/dev/null 2>&1 && \
+   rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
+    _setup_amd_detected=true
+    _setup_gfx_all=$(rocminfo 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+    _setup_mkt=$(rocminfo 2>/dev/null | awk -F': ' \
+        '/Marketing Name:/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+elif command -v amd-smi >/dev/null 2>&1 && \
+     amd-smi list 2>/dev/null | awk '/^GPU[[:space:]]*[:\[][[:space:]]*[0-9]/{ found=1 } END{ exit !found }'; then
+    _setup_amd_detected=true
+    _setup_gfx_all=$(amd-smi list 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+    [ -z "$_setup_gfx_all" ] && \
+        _setup_gfx_all=$(amd-smi static --asic 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+    _setup_mkt=$(amd-smi static --asic 2>/dev/null | awk -F'[:|]' \
+        '/[Mm]arket.?[Nn]ame/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+fi
+
+if command -v nvidia-smi >/dev/null 2>&1 && \
+   nvidia-smi -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
+    step "gpu" "NVIDIA GPU detected"
+elif [ "$_setup_amd_detected" = true ]; then
+    _setup_vis="${HIP_VISIBLE_DEVICES:-${ROCR_VISIBLE_DEVICES:-}}"
+    _setup_vis_idx=0
+    if [ -n "$_setup_vis" ] && [ "$_setup_vis" != "-1" ]; then
+        _setup_first="${_setup_vis%%,*}"
+        case "$_setup_first" in ''|*[!0-9]*) ;; *) _setup_vis_idx=$_setup_first ;; esac
+    fi
+    _setup_gfx=$(printf '%s\n' "$_setup_gfx_all" | awk -v idx="$_setup_vis_idx" \
+        'NF && !seen[$0]++ { a[n++]=$0 } END { if(idx>=n) idx=0; if(n>0) print a[idx] }')
+    # UNSLOTH_ROCM_GFX_ARCH env override (mirrors setup.ps1)
+    if [ -n "${UNSLOTH_ROCM_GFX_ARCH:-}" ]; then
+        _setup_gfx="${UNSLOTH_ROCM_GFX_ARCH}"
+        substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $_setup_gfx"
+    # Name-based arch inference when tools don't report gfx (mirrors setup.ps1 nameArchTable)
+    elif [ -z "$_setup_gfx" ] && [ -n "$_setup_mkt" ]; then
+        case "$_setup_mkt" in
+            *"9070 XT"*|*9080*)                                                     _setup_gfx="gfx1201" ;;  # RDNA 4
+            *9070*|*9060*)                                                          _setup_gfx="gfx1200" ;;  # RDNA 4
+            *"8060S"*|*"890M"*|*"Strix Halo"*|*"HX 37"*|*"HX 38"*|*"AI 9 HX"*)  _setup_gfx="gfx1151" ;;  # RDNA 3.5 iGPU
+            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)        _setup_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
+            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                  _setup_gfx="gfx1100" ;;  # RDNA 3 desktop
+            *"RX 7600"*)                                                           _setup_gfx="gfx1102" ;;  # RDNA 3
+            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                               _setup_gfx="gfx1103" ;;  # RDNA 3 iGPU
+        esac
+        if [ -n "$_setup_gfx" ]; then
+            substep "gfx arch inferred from GPU name: $_setup_gfx"
+            substep "Tip: set UNSLOTH_ROCM_GFX_ARCH=$_setup_gfx to skip inference next time"
+        fi
+    fi
+    # ROCm version via hipconfig, then amd-smi
+    _setup_rocm_ver=""
+    if command -v hipconfig >/dev/null 2>&1; then
+        _setup_rocm_ver=$(hipconfig --version 2>/dev/null | awk 'NR==1 && /^[0-9]/{print; exit}' || true)
+    fi
+    if [ -z "$_setup_rocm_ver" ] && command -v amd-smi >/dev/null 2>&1; then
+        _setup_rocm_ver=$(amd-smi version 2>/dev/null | awk -F'ROCm version: ' \
+            'NF>1{gsub(/[[:space:]]/,"", $2); print $2; exit}' || true)
+    fi
+    if [ -n "$_setup_gfx" ]; then
+        step "gpu" "AMD ROCm ($_setup_gfx)"
+    else
+        step "gpu" "AMD ROCm"
+    fi
+    _setup_rocm_root="${ROCM_PATH:-${HIP_PATH:-/opt/rocm}}"
+    substep "ROCm: $_setup_rocm_root"
+    [ -n "$_setup_rocm_ver" ] && substep "hipconfig: $_setup_rocm_ver"
+    [ -n "$_setup_mkt" ] && [ -n "$_setup_gfx" ] && substep "GPU: $_setup_mkt"
+else
+    step "gpu" "none (chat-only / GGUF)" "$C_WARN"
+    substep "Training and GPU inference require an NVIDIA or AMD ROCm GPU."
+fi
+
 # ── 7. Prefer prebuilt llama.cpp bundles before any source build path ──
 # Nest llama.cpp under $STUDIO_HOME only for real env-overrides; legacy
 # default keeps ~/.unsloth/llama.cpp so pre-PR builds are still discovered.
@@ -817,6 +892,22 @@ else
     fi
 fi
 
+# Source-built llama.cpp installs do not have the prebuilt metadata used above
+# for exact release matching. Reuse a complete local source build unless the
+# caller explicitly requested a rebuild or a PR-specific llama.cpp checkout.
+if [ "$_NEED_LLAMA_SOURCE_BUILD" = true ] && \
+   [ "$_LLAMA_FORCE_COMPILE" != "1" ] && \
+   [ -z "$_LLAMA_PR" ] && \
+   [ -x "$LLAMA_CPP_DIR/build/bin/llama-server" ] && \
+   [ -x "$LLAMA_CPP_DIR/build/bin/llama-quantize" ]; then
+    step "llama.cpp" "existing source build found; skipping rebuild"
+    ln -sf build/bin/llama-quantize "$LLAMA_CPP_DIR/llama-quantize"
+    if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then
+        : > "$LLAMA_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || true
+    fi
+    _NEED_LLAMA_SOURCE_BUILD=false
+fi
+
 # ── 8. WSL: pre-install GGUF build dependencies for fallback source builds ──
 # On WSL, sudo requires a password and can't be entered during GGUF export
 # (runs in a non-interactive subprocess). Install build deps here instead.
@@ -974,7 +1065,8 @@ else
         fi
 
         if [ "$BUILD_OK" = true ]; then
-            CMAKE_ARGS="-DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF -DLLAMA_BUILD_SERVER=ON -DGGML_NATIVE=ON"
+            # Set Release explicitly (llama.cpp only defaults to it on non-MSVC/Xcode).
+            CMAKE_ARGS="-DCMAKE_BUILD_TYPE=Release -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF -DLLAMA_BUILD_SERVER=ON -DGGML_NATIVE=ON"
             _TRY_METAL_CPU_FALLBACK=false
             _HOST_SYSTEM="$(uname -s 2>/dev/null || true)"
             _HOST_MACHINE="$(uname -m 2>/dev/null || true)"
@@ -1088,6 +1180,32 @@ else
 
                 _BUILD_DESC="building (ROCm)"
                 CMAKE_ARGS="$CMAKE_ARGS -DGGML_HIP=ON"
+
+                # ROCm 7.x ships clang-20 which on Ubuntu 24.04+ defaults to the
+                # highest-numbered gcc lib dir (/usr/lib/gcc/x86_64-linux-gnu/14/)
+                # which contains runtime objects but NOT C++ headers, causing:
+                #   fatal error: 'cstdlib' file not found
+                # Find the newest gcc install dir that actually has both the
+                # runtime dir AND /usr/include/c++/<ver> headers, then pass it
+                # to clang via --gcc-install-dir so HIP builds succeed.
+                _GCC_INSTALL_DIR=""
+                _gcc_pm="$(gcc -print-multiarch 2>/dev/null)"
+                case "$_gcc_pm" in
+                    *-linux-gnu*) _GCC_MULTIARCH="$_gcc_pm" ;;
+                    *) _GCC_MULTIARCH="$(uname -m)-linux-gnu" ;;
+                esac
+                for _gcc_ver in 14 13 12 11; do
+                    if [ -d "/usr/lib/gcc/$_GCC_MULTIARCH/$_gcc_ver/include" ] && \
+                       [ -d "/usr/include/c++/$_gcc_ver" ]; then
+                        _GCC_INSTALL_DIR="/usr/lib/gcc/$_GCC_MULTIARCH/$_gcc_ver"
+                        break
+                    fi
+                done
+                if [ -n "$_GCC_INSTALL_DIR" ]; then
+                    CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_HIP_FLAGS=--gcc-install-dir=\"$_GCC_INSTALL_DIR\""
+                    substep "ROCm HIP gcc install dir: $_GCC_INSTALL_DIR"
+                fi
+
                 export ROCM_PATH="$ROCM_ROOT"
                 export HIP_PATH="$ROCM_ROOT"
 
diff --git a/tests/sh/test_get_torch_index_url.sh b/tests/sh/test_get_torch_index_url.sh
index 89ec32fba5..e20fd1ca86 100755
--- a/tests/sh/test_get_torch_index_url.sh
+++ b/tests/sh/test_get_torch_index_url.sh
@@ -193,10 +193,10 @@ _result=$(run_func "$_dir")
 assert_eq "ROCm 7.1 -> rocm7.1" "https://download.pytorch.org/whl/rocm7.1" "$_result"
 rm -rf "$_dir"
 
-# 11) ROCm 7.2 (no nvidia-smi) -> rocm7.1 (capped due to torch <2.11.0)
+# 11) ROCm 7.2 (no nvidia-smi) -> rocm7.2
 _dir=$(make_mock_amd_smi "7.2")
 _result=$(run_func "$_dir")
-assert_eq "ROCm 7.2 -> rocm7.1 (capped)" "https://download.pytorch.org/whl/rocm7.1" "$_result"
+assert_eq "ROCm 7.2 -> rocm7.2" "https://download.pytorch.org/whl/rocm7.2" "$_result"
 rm -rf "$_dir"
 
 # 12) Both nvidia-smi and amd-smi present -> CUDA takes precedence
@@ -231,10 +231,10 @@ _result=$(run_func "$_dir")
 assert_eq "ROCm 7.0 -> rocm7.0" "https://download.pytorch.org/whl/rocm7.0" "$_result"
 rm -rf "$_dir"
 
-# 17) ROCm 8.0 (future, no nvidia-smi) -> rocm7.1 (capped)
+# 17) ROCm 8.0 (future, no nvidia-smi) -> rocm7.2 (capped to latest known)
 _dir=$(make_mock_amd_smi "8.0")
 _result=$(run_func "$_dir")
-assert_eq "ROCm 8.0 -> rocm7.1 (capped)" "https://download.pytorch.org/whl/rocm7.1" "$_result"
+assert_eq "ROCm 8.0 -> rocm7.2 (capped)" "https://download.pytorch.org/whl/rocm7.2" "$_result"
 rm -rf "$_dir"
 
 # 18) Malformed amd-smi output (empty version field) -> cpu
diff --git a/tests/studio/install/conftest.py b/tests/studio/install/conftest.py
new file mode 100644
index 0000000000..8738ef2319
--- /dev/null
+++ b/tests/studio/install/conftest.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Pytest configuration for studio/install tests.
+
+install_python_stack.py does ``from backend.utils.wheel_utils import ...``
+which requires the ``studio/`` directory to be on sys.path.  When tests are
+run from the repo root (the normal case), the studio package is not
+automatically importable, so we add it here.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# <repo-root>/studio  →  makes `backend` importable as a package
+_STUDIO_DIR = Path(__file__).resolve().parents[3] / "studio"
+if str(_STUDIO_DIR) not in sys.path:
+    sys.path.insert(0, str(_STUDIO_DIR))
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index e6f1ae1c65..ecb1b9be15 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -51,6 +51,9 @@ _ensure_rocm_torch = stack_mod._ensure_rocm_torch
 _has_rocm_gpu = stack_mod._has_rocm_gpu
 _has_usable_nvidia_gpu = stack_mod._has_usable_nvidia_gpu
 _ROCM_TORCH_INDEX = stack_mod._ROCM_TORCH_INDEX
+_windows_rocm_index_url = stack_mod._windows_rocm_index_url
+_detect_windows_gfx_arch = stack_mod._detect_windows_gfx_arch
+_install_bnb_windows_rocm = stack_mod._install_bnb_windows_rocm
 
 
 def _extract_sh_function_body(source: str, name: str) -> str:
@@ -596,6 +599,7 @@ class TestEnsureRocmTorch:
                 _ensure_rocm_torch()
         mock_pip.assert_not_called()
 
+    @patch.object(stack_mod, "IS_WINDOWS", False)
     @patch.object(stack_mod, "pip_install_try", return_value = True)
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
@@ -616,7 +620,9 @@ class TestEnsureRocmTorch:
         assert "rocm7.1" in str(mock_pip.call_args_list[0])
         assert mock_pip_try.call_count >= 1
         assert "bitsandbytes" in str(mock_pip_try.call_args_list[0])
+        assert mock_pip_try.call_args.kwargs["force_pip"] is True
 
+    @patch.object(stack_mod, "IS_WINDOWS", False)
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
@@ -648,6 +654,7 @@ class TestEnsureRocmTorch:
                 _ensure_rocm_torch()
         mock_pip.assert_not_called()
 
+    @patch.object(stack_mod, "IS_WINDOWS", False)
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
@@ -662,12 +669,13 @@ class TestEnsureRocmTorch:
         captured = capsys.readouterr()
         assert "unreadable" in captured.out
 
+    @patch.object(stack_mod, "IS_WINDOWS", False)
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
     @patch.object(stack_mod, "_detect_rocm_version", return_value = (7, 2))
-    def test_rocm_72_selects_71_tag(self, mock_ver, mock_gpu, mock_nvidia, mock_pip):
-        """ROCm 7.2 should select rocm7.1 tag (capped, not in mapping)."""
+    def test_rocm_72_selects_72_tag(self, mock_ver, mock_gpu, mock_nvidia, mock_pip):
+        """ROCm 7.2 should select rocm7.2 tag (now in mapping with torch 2.11.0)."""
         mock_probe = MagicMock()
         mock_probe.returncode = 0
         mock_probe.stdout = b"\n"
@@ -675,8 +683,9 @@ class TestEnsureRocmTorch:
             with patch("subprocess.run", return_value = mock_probe):
                 _ensure_rocm_torch()
         torch_call = mock_pip.call_args_list[0]
-        assert "rocm7.1" in str(torch_call)
+        assert "rocm7.2" in str(torch_call)
 
+    @patch.object(stack_mod, "IS_WINDOWS", False)
     @patch.object(stack_mod, "pip_install_try", return_value = True)
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
@@ -696,6 +705,7 @@ class TestEnsureRocmTorch:
         assert mock_pip.call_count == 1
         assert "rocm7.1" in str(mock_pip.call_args_list[0])
         assert mock_pip_try.call_count >= 1
+        assert mock_pip_try.call_args.kwargs["force_pip"] is True
 
     @patch.object(stack_mod, "pip_install")
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
@@ -720,9 +730,10 @@ class TestRocmTorchIndex:
         keys = list(_ROCM_TORCH_INDEX.keys())
         assert keys == sorted(keys, reverse = True)
 
-    def test_rocm_72_not_in_mapping(self):
-        """ROCm 7.2 should NOT be in the active mapping (torch 2.11.0 exceeds bound)."""
-        assert (7, 2) not in _ROCM_TORCH_INDEX
+    def test_rocm_72_in_mapping(self):
+        """ROCm 7.2 should be in the active mapping (torch 2.11.0 now supported)."""
+        assert (7, 2) in _ROCM_TORCH_INDEX
+        assert _ROCM_TORCH_INDEX[(7, 2)] == "rocm7.2"
 
     def test_rocm_71_maps_correctly(self):
         assert _ROCM_TORCH_INDEX[(7, 1)] == "rocm7.1"
@@ -740,7 +751,7 @@ class TestRocmTorchIndex:
             assert "radeon" not in tag
 
     def test_newer_rocm_selects_best_match(self):
-        """ROCm 7.2 (not in map) should select rocm7.1 via >= comparison."""
+        """ROCm 7.2 (now in map) should select rocm7.2 directly."""
         ver = (7, 2)
         tag = next(
             (
@@ -750,7 +761,7 @@ class TestRocmTorchIndex:
             ),
             None,
         )
-        assert tag == "rocm7.1"
+        assert tag == "rocm7.2"
 
     def test_rocm_64_selects_64(self):
         ver = (6, 4)
@@ -778,7 +789,7 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         assert "IS_ROCM: bool" in source and "False" in source
 
     def test_hardware_py_sets_is_rocm_on_hip(self):
@@ -786,7 +797,7 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         assert 'torch.version, "hip"' in source or "torch.version.hip" in source
 
     def test_hardware_py_still_returns_cuda_for_rocm(self):
@@ -794,7 +805,7 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         # Ensure ROCM is NOT a DeviceType member
         enum_section = source.split("class DeviceType")[1].split("\n\n")[0]
         assert "ROCM" not in enum_section
@@ -804,7 +815,7 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         assert '"rocm"' in source
 
     def test_hardware_py_device_type_cuda_references_intact(self):
@@ -812,7 +823,7 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         # Key functions that must still reference DeviceType.CUDA
         assert "DeviceType.CUDA" in source
         assert "DEVICE = DeviceType.CUDA" in source
@@ -822,7 +833,7 @@ class TestHardwareRocmFlag:
         init_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
         )
-        source = init_path.read_text()
+        source = init_path.read_text(encoding = "utf-8")
         assert "IS_ROCM" in source
 
     def test_is_rocm_in_all_list(self):
@@ -830,7 +841,7 @@ class TestHardwareRocmFlag:
         init_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
         )
-        source = init_path.read_text()
+        source = init_path.read_text(encoding = "utf-8")
         # Extract __all__ section
         assert '"IS_ROCM"' in source
 
@@ -839,13 +850,37 @@ class TestHardwareRocmFlag:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         # Find the get_package_versions function body
         func_start = source.find("def get_package_versions")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert '"cuda"' in func_body
         assert '"rocm"' in func_body
 
+    def test_distributed_stubs_cover_is_torchelastic_launched(self):
+        """_determine_attention_impl_for_gpu_estimate must stub is_torchelastic_launched.
+
+        resolve_attention_implementation calls is_torchelastic_launched() on
+        Windows ROCm where torch.distributed ships without that helper, causing
+        a warning: 'module torch.distributed has no attribute is_torchelastic_launched'.
+        """
+        hw_path = (
+            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+        )
+        source = hw_path.read_text(encoding = "utf-8")
+        assert "is_torchelastic_launched" in source
+
+    def test_distributed_stubs_cover_core_helpers(self):
+        """_determine_attention_impl_for_gpu_estimate must stub the four core distributed helpers."""
+        hw_path = (
+            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+        )
+        source = hw_path.read_text(encoding = "utf-8")
+        for attr in ("is_initialized", "is_available", "get_rank", "get_world_size"):
+            assert (
+                attr in source
+            ), f"distributed stub for '{attr}' missing from hardware.py"
+
 
 # =============================================================================
 # TEST: tokenizer_utils.py -- error message
@@ -858,13 +893,13 @@ class TestTokenizerErrorMessage:
     def test_no_old_amd_message(self):
         """Old 'We do not support AMD' message should be gone."""
         tu_path = PACKAGE_ROOT / "unsloth" / "tokenizer_utils.py"
-        source = tu_path.read_text()
+        source = tu_path.read_text(encoding = "utf-8")
         assert "We do not support AMD" not in source
 
     def test_new_message_has_docs_link(self):
         """New message should point to Unsloth AMD docs."""
         tu_path = PACKAGE_ROOT / "unsloth" / "tokenizer_utils.py"
-        source = tu_path.read_text()
+        source = tu_path.read_text(encoding = "utf-8")
         assert "docs.unsloth.ai" in source or "No GPU detected" in source
 
 
@@ -879,7 +914,7 @@ class TestInstallShStructure:
     def test_no_here_strings(self):
         """install.sh must not use <<< (not POSIX)."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         # <<< is bash-only; breaks dash
         for i, line in enumerate(source.splitlines(), 1):
             stripped = line.lstrip()
@@ -890,7 +925,7 @@ class TestInstallShStructure:
     def test_rocm_detection_present(self):
         """install.sh should have ROCm detection in get_torch_index_url."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         assert "amd-smi" in source
         assert "rocm" in source.lower()
 
@@ -905,7 +940,7 @@ class TestInstallShStructure:
         block.
         """
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         body = _extract_sh_function_body(source, "get_torch_index_url")
         nvidia_call = body.find("_has_usable_nvidia_gpu")
         no_nvidia_branch = body.find('if [ -z "$_smi" ]')
@@ -926,44 +961,45 @@ class TestInstallShStructure:
     def test_bitsandbytes_amd_install(self):
         """install.sh should install bitsandbytes for AMD when ROCm detected."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         assert "bitsandbytes" in source
         assert "rocm*)" in source  # case pattern for ROCm URLs
 
     def test_cpu_hint_mentions_amd(self):
         """CPU-only hint should mention AMD ROCm."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         assert "ROCm" in source
 
-    def test_rocm72_capped_to_71(self):
-        """ROCm 7.2+ should fall back to rocm7.1 index."""
+    def test_rocm72_supported_future_capped(self):
+        """ROCm 7.2 should pass through directly; 7.3+ falls back to rocm7.2."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
-        assert 'echo "$_base/rocm7.1"' in source  # fallback for unknown versions
+        source = sh_path.read_text(encoding = "utf-8")
+        assert 'echo "$_base/rocm7.2"' in source  # fallback for unknown future versions
         # Allowlisted versions should pass through directly
         assert "rocm6.*" in source
         assert "rocm7.0" in source
         assert "rocm7.1" in source
+        assert "rocm7.2" in source
 
     def test_rocm_tag_validation_guard_exists(self):
         """install.sh should validate _rocm_tag with a case guard."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         assert "rocm[1-9]*.[0-9]*)" in source
         assert '_rocm_tag=""' in source  # rejection path
 
     def test_dpkg_epoch_handling(self):
         """install.sh should strip Debian epoch prefix from dpkg-query output."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         assert "sed 's/^[0-9]*://' " in source or "sed 's/^[0-9]*://'" in source
 
     def test_no_double_bracket_in_rocm_block(self):
         """ROCm detection block should not use [[ ]] (bash-only, not POSIX).
         Note: [[:space:]], [[:digit:]] etc. are valid POSIX character classes, not bash [[ ]]."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         func_start = source.find("get_torch_index_url()")
         func_end = source.find("\n}", func_start)
         func_body = source[func_start:func_end]
@@ -982,7 +1018,7 @@ class TestInstallShStructure:
     def test_no_arithmetic_expansion_in_rocm_block(self):
         """ROCm detection block should not use (( )) (bash-only)."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         func_start = source.find("get_torch_index_url()")
         func_end = source.find("\n}", func_start)
         func_body = source[func_start:func_end]
@@ -997,7 +1033,7 @@ class TestInstallShStructure:
     def test_macos_returns_cpu_before_rocm_check(self):
         """macOS should return CPU immediately (before any ROCm check)."""
         sh_path = PACKAGE_ROOT / "install.sh"
-        source = sh_path.read_text()
+        source = sh_path.read_text(encoding = "utf-8")
         func_start = source.find("get_torch_index_url()")
         func_body = source[func_start:]
         darwin_pos = func_body.find("Darwin")
@@ -1071,12 +1107,12 @@ class TestWorkerRocmMambaSsm:
     def test_probe_returns_hip_version_field(self):
         """The wheel probe should include hip_version, and worker.py should
         consume it."""
-        assert "hip_version" in _WHEEL_UTILS_PATH.read_text()
-        assert "hip_version" in _WORKER_PATH.read_text()
+        assert "hip_version" in _WHEEL_UTILS_PATH.read_text(encoding = "utf-8")
+        assert "hip_version" in _WORKER_PATH.read_text(encoding = "utf-8")
 
     def test_probe_script_has_getattr_hip(self):
         """Probe script should use getattr for torch.version.hip (safe on CUDA)."""
-        source = _WHEEL_UTILS_PATH.read_text()
+        source = _WHEEL_UTILS_PATH.read_text(encoding = "utf-8")
         assert "getattr(torch.version, 'hip', None)" in source
 
     def test_direct_wheel_url_returns_none_without_cuda_major(self):
@@ -1118,22 +1154,22 @@ class TestWorkerRocmMambaSsm:
 
     def test_hipcc_check_exists_in_source(self):
         """worker.py should check for hipcc before ROCm source builds."""
-        source = _WORKER_PATH.read_text()
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
         assert "hipcc" in source
 
     def test_rocm_source_build_status_message(self):
         """worker.py should send a specific status for ROCm source compilation."""
-        source = _WORKER_PATH.read_text()
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
         assert "Compiling" in source and "from source for ROCm" in source
 
     def test_rocm_build_failure_message(self):
         """worker.py should send a clear error on ROCm build failure."""
-        source = _WORKER_PATH.read_text()
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
         assert "Failed to compile" in source and "for ROCm" in source
 
     def test_timeout_on_install(self):
         """worker.py should have a timeout on pip install subprocess."""
-        source = _WORKER_PATH.read_text()
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
         assert "TimeoutExpired" in source
         assert "timeout" in source
 
@@ -1154,7 +1190,7 @@ class TestAmdGpuMonitoring:
     def test_amd_py_has_required_functions(self):
         """amd.py should export the same function signatures as nvidia.py."""
         amd_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "amd.py"
-        source = amd_path.read_text()
+        source = amd_path.read_text(encoding = "utf-8")
         assert "def get_physical_gpu_count" in source
         assert "def get_primary_gpu_utilization" in source
         assert "def get_visible_gpu_utilization" in source
@@ -1299,7 +1335,7 @@ class TestHardwareAmdBranching:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         assert "from . import amd" in source
 
     def test_hardware_branches_on_is_rocm_for_utilization(self):
@@ -1309,7 +1345,7 @@ class TestHardwareAmdBranching:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_gpu_utilization")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert '_smi_query("get_primary_gpu_utilization"' in func_body
@@ -1327,7 +1363,7 @@ class TestHardwareAmdBranching:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_visible_gpu_utilization")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         # The dispatcher call may wrap onto multiple lines; allow whitespace
@@ -1348,13 +1384,55 @@ class TestHardwareAmdBranching:
         hw_path = (
             PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         )
-        source = hw_path.read_text()
+        source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_physical_gpu_count")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "IS_ROCM" in func_body
         assert "from . import amd" in func_body
 
 
+# =============================================================================
+# TEST: hardware.py -- apply_gpu_ids ROCm fallback (issue #5180)
+# =============================================================================
+
+
+class TestApplyGpuIdsRocmFallback:
+    """Verify apply_gpu_ids sets HIP_VISIBLE_DEVICES on ROCm hosts even when
+    IS_ROCM is still False (worker subprocess before detect_hardware runs)."""
+
+    def test_apply_gpu_ids_falls_back_to_torch_version_hip(self):
+        """apply_gpu_ids should probe torch.version.hip when IS_ROCM is False and no ROCm env vars are set."""
+        hw_path = (
+            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+        )
+        source = hw_path.read_text(encoding = "utf-8")
+        func_start = source.find("def apply_gpu_ids")
+        func_body = source[func_start : source.find("\ndef ", func_start + 1)]
+        assert 'getattr(_torch.version, "hip", None)' in func_body
+
+    def test_apply_gpu_ids_sets_hip_and_rocr_visible_devices(self):
+        """apply_gpu_ids should set both HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES on ROCm."""
+        hw_path = (
+            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+        )
+        source = hw_path.read_text(encoding = "utf-8")
+        func_start = source.find("def apply_gpu_ids")
+        func_body = source[func_start : source.find("\ndef ", func_start + 1)]
+        assert 'os.environ["HIP_VISIBLE_DEVICES"] = value' in func_body
+        assert 'os.environ["ROCR_VISIBLE_DEVICES"] = value' in func_body
+
+    def test_apply_gpu_ids_rocm_fallback_is_guarded_by_try_except(self):
+        """torch import in apply_gpu_ids must be wrapped in try/except so a missing torch never crashes."""
+        hw_path = (
+            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+        )
+        source = hw_path.read_text(encoding = "utf-8")
+        func_start = source.find("def apply_gpu_ids")
+        func_body = source[func_start : source.find("\ndef ", func_start + 1)]
+        assert "import torch as _torch" in func_body
+        assert "except Exception" in func_body
+
+
 # =============================================================================
 # TEST: install_python_stack.py -- Windows AMD warning
 # =============================================================================
@@ -1365,18 +1443,18 @@ class TestWindowsRocmWarning:
 
     def test_windows_amd_warning_in_source(self):
         """install_python_stack.py should warn Windows AMD users."""
-        source = _STACK_PATH.read_text()
-        assert "AMD GPU detected on Windows" in source
+        source = _STACK_PATH.read_text(encoding = "utf-8")
+        assert "AMD GPU detected" in source
 
     def test_windows_amd_warning_checks_hipinfo_or_amdsmi(self):
         """Warning should check for hipinfo or amd-smi."""
-        source = _STACK_PATH.read_text()
+        source = _STACK_PATH.read_text(encoding = "utf-8")
         assert "hipinfo" in source
         assert "amd-smi" in source
 
     def test_windows_amd_warning_has_docs_link(self):
         """Warning should include AMD docs link."""
-        source = _STACK_PATH.read_text()
+        source = _STACK_PATH.read_text(encoding = "utf-8")
         assert "docs.unsloth.ai/get-started/install-and-update/amd" in source
 
 
@@ -1391,7 +1469,7 @@ class TestIsRdnaExpansion:
     def test_is_rdna_source_has_rdna2(self):
         """is_rdna() should include RDNA2 architectures."""
         utils_path = PACKAGE_ROOT / "unsloth" / "kernels" / "utils.py"
-        source = utils_path.read_text()
+        source = utils_path.read_text(encoding = "utf-8")
         func_start = source.find("def is_rdna()")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "gfx1030" in func_body
@@ -1405,7 +1483,7 @@ class TestIsRdnaExpansion:
     def test_is_rdna_source_has_rdna3(self):
         """is_rdna() should include RDNA3 architectures."""
         utils_path = PACKAGE_ROOT / "unsloth" / "kernels" / "utils.py"
-        source = utils_path.read_text()
+        source = utils_path.read_text(encoding = "utf-8")
         func_start = source.find("def is_rdna()")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "gfx1100" in func_body
@@ -1416,7 +1494,7 @@ class TestIsRdnaExpansion:
     def test_is_rdna_source_has_rdna35(self):
         """is_rdna() should include RDNA3.5 architectures."""
         utils_path = PACKAGE_ROOT / "unsloth" / "kernels" / "utils.py"
-        source = utils_path.read_text()
+        source = utils_path.read_text(encoding = "utf-8")
         func_start = source.find("def is_rdna()")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "gfx1150" in func_body
@@ -1426,7 +1504,7 @@ class TestIsRdnaExpansion:
     def test_is_rdna_source_has_rdna4(self):
         """is_rdna() should include RDNA4 architectures."""
         utils_path = PACKAGE_ROOT / "unsloth" / "kernels" / "utils.py"
-        source = utils_path.read_text()
+        source = utils_path.read_text(encoding = "utf-8")
         func_start = source.find("def is_rdna()")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "gfx1200" in func_body
@@ -1435,7 +1513,7 @@ class TestIsRdnaExpansion:
     def test_is_cdna_not_changed(self):
         """is_cdna() should remain unchanged (no RDNA architectures added)."""
         utils_path = PACKAGE_ROOT / "unsloth" / "kernels" / "utils.py"
-        source = utils_path.read_text()
+        source = utils_path.read_text(encoding = "utf-8")
         func_start = source.find("def is_cdna()")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert "gfx940" in func_body
@@ -1447,5 +1525,1069 @@ class TestIsRdnaExpansion:
         assert "gfx1100" not in func_body
 
 
+# =============================================================================
+# TEST: install_python_stack.py -- _windows_rocm_index_url arch mapping
+# =============================================================================
+
+
+class TestWindowsRocmIndexUrl:
+    """Verify GPU arch → AMD pip index URL mapping."""
+
+    def test_gfx1200_maps_to_gfx120x_all(self):
+        url = stack_mod._windows_rocm_index_url("gfx1200")
+        assert url is not None
+        assert "gfx120X-all" in url
+
+    def test_gfx1201_maps_to_gfx120x_all(self):
+        url = stack_mod._windows_rocm_index_url("gfx1201")
+        assert url is not None
+        assert "gfx120X-all" in url
+
+    def test_gfx1151_maps_to_gfx1151(self):
+        url = stack_mod._windows_rocm_index_url("gfx1151")
+        assert url is not None
+        assert "gfx1151" in url
+
+    def test_gfx1150_maps_to_gfx1150(self):
+        url = stack_mod._windows_rocm_index_url("gfx1150")
+        assert url is not None
+        assert "gfx1150" in url
+
+    def test_gfx1100_maps_to_gfx110x_all(self):
+        url = stack_mod._windows_rocm_index_url("gfx1100")
+        assert url is not None
+        assert "gfx110X-all" in url
+
+    def test_unknown_arch_returns_none(self):
+        assert stack_mod._windows_rocm_index_url("gfx9999") is None
+
+    def test_none_arch_returns_none(self):
+        assert stack_mod._windows_rocm_index_url(None) is None
+
+    def test_url_ends_with_slash(self):
+        """AMD pip index URLs must end with / for --index-url compatibility."""
+        url = stack_mod._windows_rocm_index_url("gfx1200")
+        assert url is not None
+        assert url.endswith("/")
+
+    def test_base_url_uses_repo_amd_com_by_default(self):
+        url = stack_mod._windows_rocm_index_url("gfx1200")
+        assert url is not None
+        assert "repo.amd.com" in url
+
+    def test_mirror_env_var_overrides_base(self, monkeypatch):
+        monkeypatch.setenv(
+            "UNSLOTH_ROCM_WINDOWS_MIRROR", "https://my-mirror.example.com/rocm/whl"
+        )
+        # Reload module-level constant by calling helper directly
+        url = stack_mod._windows_rocm_index_url("gfx1200")
+        # The env var is read at module load time for _ROCM_WINDOWS_INDEX_BASE,
+        # so just verify the helper itself doesn't error.
+        assert url is not None
+
+
+# =============================================================================
+# TEST: install_python_stack.py -- _detect_windows_gfx_arch
+# =============================================================================
+
+
+class TestDetectWindowsGfxArch:
+    """Verify hipinfo parsing for GPU arch detection on Windows."""
+
+    def test_returns_none_when_hipinfo_not_on_path(self):
+        with patch("shutil.which", return_value = None):
+            result = stack_mod._detect_windows_gfx_arch()
+        assert result is None
+
+    def test_parses_gcnarchname_from_hipinfo_output(self):
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = b"gcnArchName : gfx1200\nsome other line\n"
+        with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
+            with patch("subprocess.run", return_value = mock_result):
+                result = stack_mod._detect_windows_gfx_arch()
+        assert result == "gfx1200"
+
+    def test_returns_none_on_nonzero_returncode(self):
+        mock_result = MagicMock()
+        mock_result.returncode = 1
+        mock_result.stdout = b"gcnArchName : gfx1200\n"
+        with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
+            with patch("subprocess.run", return_value = mock_result):
+                result = stack_mod._detect_windows_gfx_arch()
+        assert result is None
+
+    def test_returns_none_when_no_gcnarchname_in_output(self):
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = b"deviceName : Radeon RX 9060 XT\n"
+        with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
+            with patch("subprocess.run", return_value = mock_result):
+                result = stack_mod._detect_windows_gfx_arch()
+        assert result is None
+
+    def test_returns_none_on_timeout(self):
+        with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
+            with patch(
+                "subprocess.run",
+                side_effect = subprocess.TimeoutExpired("hipinfo", 10),
+            ):
+                result = stack_mod._detect_windows_gfx_arch()
+        assert result is None
+
+    def test_strips_whitespace_from_arch(self):
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = b"  gcnArchName :   gfx1201  \n"
+        with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
+            with patch("subprocess.run", return_value = mock_result):
+                result = stack_mod._detect_windows_gfx_arch()
+        assert result == "gfx1201"
+
+
+# =============================================================================
+# TEST: install_python_stack.py -- _install_bnb_windows_rocm
+# =============================================================================
+
+
+class TestInstallBnbWindowsRocm:
+    """Verify AMD Windows BNB wheel install helper."""
+
+    def test_calls_pip_install_try_with_win_amd64_url(self):
+        """Should call pip_install_try with the win_amd64 wheel URL."""
+        with patch.object(stack_mod, "pip_install_try", return_value = True) as mock_pip:
+            stack_mod._install_bnb_windows_rocm()
+        assert mock_pip.call_count == 1
+        call_args = str(mock_pip.call_args_list[0])
+        assert "bitsandbytes" in call_args
+        assert "win_amd64" in call_args
+
+    def test_sets_uv_skip_env_var_during_install(self):
+        """UV_SKIP_WHEEL_FILENAME_CHECK must be '1' when pip_install_try runs."""
+        observed = {}
+
+        def _capture(*args, **kwargs):
+            observed["val"] = os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK")
+            return True
+
+        with patch.object(stack_mod, "pip_install_try", side_effect = _capture):
+            stack_mod._install_bnb_windows_rocm()
+        assert observed.get("val") == "1"
+
+    def test_restores_uv_skip_env_var_after_install(self):
+        """UV_SKIP_WHEEL_FILENAME_CHECK should be removed after install if it wasn't set before."""
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                stack_mod._install_bnb_windows_rocm()
+            assert "UV_SKIP_WHEEL_FILENAME_CHECK" not in os.environ
+
+    def test_restores_previous_uv_skip_value(self):
+        """If UV_SKIP_WHEEL_FILENAME_CHECK was already set, restore it afterwards."""
+        with patch.dict(os.environ, {"UV_SKIP_WHEEL_FILENAME_CHECK": "0"}):
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                stack_mod._install_bnb_windows_rocm()
+            assert os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK") == "0"
+
+    def test_restores_env_even_if_install_raises(self):
+        """UV_SKIP_WHEEL_FILENAME_CHECK must be cleaned up even on pip failure."""
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
+            with patch.object(
+                stack_mod, "pip_install_try", side_effect = RuntimeError("pip failed")
+            ):
+                try:
+                    stack_mod._install_bnb_windows_rocm()
+                except RuntimeError:
+                    pass
+            assert "UV_SKIP_WHEEL_FILENAME_CHECK" not in os.environ
+
+    def test_no_op_when_win_amd64_url_missing(self):
+        """Should be silent no-op if win_amd64 key absent from _BNB_ROCM_PRERELEASE_URLS."""
+        with patch.object(stack_mod, "_BNB_ROCM_PRERELEASE_URLS", {}):
+            with patch.object(stack_mod, "pip_install_try") as mock_pip:
+                stack_mod._install_bnb_windows_rocm()
+        mock_pip.assert_not_called()
+
+    def test_sets_bnb_rocm_version_from_detected_dll(self):
+        """BNB_ROCM_VERSION is set from the DLL detected after install."""
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(
+                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "72"
+                ):
+                    stack_mod._install_bnb_windows_rocm()
+            assert os.environ.get("BNB_ROCM_VERSION") == "72"
+
+    def test_sets_bnb_rocm_version_from_newer_dll(self):
+        """If AMD ships a newer DLL (e.g. rocm713.dll), that version is used."""
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(
+                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "713"
+                ):
+                    stack_mod._install_bnb_windows_rocm()
+            assert os.environ.get("BNB_ROCM_VERSION") == "713"
+
+    def test_falls_back_to_72_when_detection_fails(self):
+        """Falls back to '72' when DLL detection returns None."""
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(
+                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = None
+                ):
+                    stack_mod._install_bnb_windows_rocm()
+            assert os.environ.get("BNB_ROCM_VERSION") == "72"
+
+    def test_does_not_override_existing_bnb_rocm_version(self):
+        """An explicit BNB_ROCM_VERSION in the caller's env must not be clobbered."""
+        with patch.dict(os.environ, {"BNB_ROCM_VERSION": "60"}):
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                stack_mod._install_bnb_windows_rocm()
+            assert os.environ.get("BNB_ROCM_VERSION") == "60"
+
+
+class TestDetectBnbRocmDllVer:
+    """Unit tests for _detect_bnb_rocm_dll_ver()."""
+
+    def test_returns_none_when_bnb_not_installed(self):
+        """Returns None if bitsandbytes is not importable."""
+        import importlib.util
+
+        with patch.object(importlib.util, "find_spec", return_value = None):
+            assert stack_mod._detect_bnb_rocm_dll_ver() is None
+
+    def test_detects_rocm72_dll(self, tmp_path):
+        """Returns '72' when libbitsandbytes_rocm72.dll is present."""
+        (tmp_path / "libbitsandbytes_rocm72.dll").write_text("")
+        mock_spec = MagicMock()
+        mock_spec.submodule_search_locations = [str(tmp_path)]
+        import importlib.util
+
+        with patch.object(importlib.util, "find_spec", return_value = mock_spec):
+            assert stack_mod._detect_bnb_rocm_dll_ver() == "72"
+
+    def test_detects_rocm713_dll(self, tmp_path):
+        """Returns '713' when libbitsandbytes_rocm713.dll is present."""
+        (tmp_path / "libbitsandbytes_rocm713.dll").write_text("")
+        mock_spec = MagicMock()
+        mock_spec.submodule_search_locations = [str(tmp_path)]
+        import importlib.util
+
+        with patch.object(importlib.util, "find_spec", return_value = mock_spec):
+            assert stack_mod._detect_bnb_rocm_dll_ver() == "713"
+
+    def test_returns_none_when_only_cuda_dlls(self, tmp_path):
+        """Returns None when only CUDA DLLs are present (no ROCm DLL)."""
+        (tmp_path / "libbitsandbytes_cuda121.dll").write_text("")
+        mock_spec = MagicMock()
+        mock_spec.submodule_search_locations = [str(tmp_path)]
+        import importlib.util
+
+        with patch.object(importlib.util, "find_spec", return_value = mock_spec):
+            assert stack_mod._detect_bnb_rocm_dll_ver() is None
+
+    def test_picks_highest_suffix_when_multiple_dlls(self, tmp_path):
+        """Returns the highest numeric suffix when multiple ROCm DLL variants exist.
+
+        Filesystem glob order is not guaranteed, so the function must not stop
+        at the first match — it must always return the highest one.
+        """
+        (tmp_path / "libbitsandbytes_rocm72.dll").write_text("")
+        (tmp_path / "libbitsandbytes_rocm713.dll").write_text("")
+        mock_spec = MagicMock()
+        mock_spec.submodule_search_locations = [str(tmp_path)]
+        import importlib.util
+
+        with patch.object(importlib.util, "find_spec", return_value = mock_spec):
+            assert stack_mod._detect_bnb_rocm_dll_ver() == "713"
+
+
+# =============================================================================
+# TEST: install_python_stack.py -- UNSLOTH_ROCM_TORCH_INSTALLED early-return path
+# =============================================================================
+
+
+class TestRocmTorchInstalledEnvVar:
+    """Verify UNSLOTH_ROCM_TORCH_INSTALLED=1 skips main install but still installs BNB."""
+
+    @staticmethod
+    def _ok_torch_probe(*a, **kw):
+        # subprocess.run probe returns 0 when torch imports as ROCm
+        rv = MagicMock()
+        rv.returncode = 0
+        return rv
+
+    @patch.object(stack_mod, "_install_bnb_windows_rocm")
+    @patch.object(stack_mod, "pip_install")
+    def test_env_var_skips_main_pip_install(self, mock_pip, mock_bnb):
+        """UNSLOTH_ROCM_TORCH_INSTALLED=1 should not trigger torch pip_install."""
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ROCM_TORCH_INSTALLED": "1"}),
+            patch.object(stack_mod.subprocess, "run", side_effect = self._ok_torch_probe),
+        ):
+            stack_mod._ensure_rocm_torch()
+        mock_pip.assert_not_called()
+
+    @patch.object(stack_mod, "_install_bnb_windows_rocm")
+    @patch.object(stack_mod, "pip_install")
+    def test_env_var_calls_bnb_install(self, mock_pip, mock_bnb):
+        """UNSLOTH_ROCM_TORCH_INSTALLED=1 should still call _install_bnb_windows_rocm."""
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ROCM_TORCH_INSTALLED": "1"}),
+            patch.object(stack_mod.subprocess, "run", side_effect = self._ok_torch_probe),
+        ):
+            stack_mod._ensure_rocm_torch()
+        mock_bnb.assert_called_once()
+
+    @patch.object(stack_mod, "_install_bnb_windows_rocm")
+    @patch.object(stack_mod, "pip_install")
+    def test_env_var_sets_rocm_windows_flag(self, mock_pip, mock_bnb):
+        """UNSLOTH_ROCM_TORCH_INSTALLED=1 should set _rocm_windows_torch_installed."""
+        stack_mod._rocm_windows_torch_installed = False
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ROCM_TORCH_INSTALLED": "1"}),
+            patch.object(stack_mod.subprocess, "run", side_effect = self._ok_torch_probe),
+        ):
+            stack_mod._ensure_rocm_torch()
+        assert stack_mod._rocm_windows_torch_installed is True
+
+    @patch.object(stack_mod, "_install_bnb_windows_rocm")
+    @patch.object(stack_mod, "pip_install")
+    def test_env_var_falls_through_when_torch_missing(self, mock_pip, mock_bnb):
+        """If the venv was wiped between runs, the stale env-var must not suppress reinstall."""
+        stack_mod._rocm_windows_torch_installed = False
+
+        def _bad_probe(*a, **kw):
+            rv = MagicMock()
+            rv.returncode = 1
+            return rv
+
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ROCM_TORCH_INSTALLED": "1"}),
+            patch.object(stack_mod.subprocess, "run", side_effect = _bad_probe),
+            patch.object(stack_mod, "IS_WINDOWS", False),
+            patch.object(stack_mod, "IS_MACOS", True),
+        ):
+            stack_mod._ensure_rocm_torch()
+        # macOS branch is the next exit -- but the point is the early-return did NOT fire.
+        mock_bnb.assert_not_called()
+
+
+# =============================================================================
+# TEST: worker.py -- Windows ROCm patches (source-level checks)
+# =============================================================================
+
+
+class TestWorkerWindowsRocmPatches:
+    """Verify worker.py contains the required Windows ROCm runtime patches."""
+
+    def test_grouped_mm_dispatch_patch_present(self):
+        """worker.py must register a _grouped_mm CUDA dispatch override."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert '_gm_lib.impl("_grouped_mm"' in source
+
+    def test_grouped_mm_patch_targets_cuda_dispatch_key(self):
+        """The dispatch override must target the CUDA key (not CompositeImplicitAutograd)."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert '"_grouped_mm", _grouped_mm_safe_impl, "CUDA"' in source
+
+    def test_grouped_mm_lib_kept_alive(self):
+        """The Library object must be stored to prevent GC clearing the registration."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "_WINDOWS_ROCM_GROUPED_MM_LIB" in source
+
+    def test_grouped_mm_handles_offs_grouped_case(self):
+        """_grouped_mm fallback must handle the grouped (offs!=None) variant."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "offs_list" in source
+        assert "offs.tolist()" in source
+
+    def test_torchao_stub_uses_stub_type_meta(self):
+        """Torchao stub must use _StubTypeMeta so isinstance() returns False not TypeError."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "_StubTypeMeta" in source
+
+    def test_stub_type_meta_has_instancecheck(self):
+        """_StubTypeMeta must define __instancecheck__ returning False."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "__instancecheck__" in source
+
+    def test_stub_subpackage_finder_registered(self):
+        """_StubSubpackageFinder must be appended to sys.meta_path."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "sys.meta_path.append(_StubSubpackageFinder())" in source
+
+    def test_torchao_key_submodules_pre_stubbed(self):
+        """Key torchao submodules (dtypes, quantization) must be pre-stubbed."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "torchao.dtypes" in source
+        assert "torchao.quantization" in source
+
+    def test_torchdynamo_disabled_on_windows_rocm(self):
+        """worker.py should disable dynamo on Windows ROCm as belt-and-suspenders."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "TORCHDYNAMO_DISABLE" in source
+
+    def test_bnb_rocm_version_set_on_windows_rocm(self):
+        """worker.py must set BNB_ROCM_VERSION in the Windows ROCm section.
+
+        BNB auto-detects HIP version from torch.version.hip, which can mismatch
+        the DLL suffix in the AMD prerelease wheel.  The worker must detect the
+        actual DLL suffix and override BNB's auto-detection before ML imports.
+        """
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        # Env var must be set
+        assert "BNB_ROCM_VERSION" in source
+        # Detection helper must be used
+        assert "_detect_bnb_rocm_dll_ver" in source or "libbitsandbytes_rocm" in source
+        # "72" must appear as the safe fallback
+        assert '"72"' in source or "'72'" in source
+
+    def test_bnb_rocm_version_set_before_ml_imports(self):
+        """BNB_ROCM_VERSION must appear in section 1f, before section 2 ML imports."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        idx_bnb = source.find("BNB_ROCM_VERSION")
+        # Use the specific section-2 marker that appears in the worker process
+        # entry-point function (not the trainer helper which has its own "# ── 2.").
+        idx_sec2 = source.find("# ── 2. Now import ML libraries")
+        assert idx_bnb != -1, "BNB_ROCM_VERSION not found in worker.py"
+        assert (
+            idx_sec2 != -1
+        ), "'# ── 2. Now import ML libraries' marker not found in worker.py"
+        assert idx_bnb < idx_sec2, (
+            "BNB_ROCM_VERSION must be set before section 2 ML imports "
+            f"(found at {idx_bnb}, section 2 at {idx_sec2})"
+        )
+
+    def test_grouped_mm_patch_guarded_by_windows_and_hip_check(self):
+        """_grouped_mm patch must only apply on Windows + HIP torch."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        # Must check sys.platform == "win32"
+        assert 'sys.platform == "win32"' in source
+        # Must gate on HIP version — code uses getattr chain: "version" and "hip"
+        assert '"version"' in source and '"hip"' in source
+
+    def test_hip_ver_at_least_helper_defined(self):
+        """_hip_ver_at_least helper must be defined inside the Windows ROCm block."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "def _hip_ver_at_least(major: int, minor: int)" in source
+
+    def test_grouped_mm_patch_gated_on_hip_lt_713(self):
+        """_grouped_mm patch must be skipped on HIP >= 7.13 (AMD fixed the bug in ROCm 7.13)."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        # The guard must call _hip_ver_at_least with exactly (7, 13)
+        assert "_hip_ver_at_least(7, 13)" in source
+        # The patch must be inside the `if not` branch (negated guard)
+        assert "if not _hip_ver_at_least(7, 13):" in source
+
+    def test_grouped_mm_hip_713_skip_message_present(self):
+        """worker.py must log a message when skipping the patch on HIP >= 7.13."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "HIP >= 7.13" in source
+        assert "7.13" in source
+
+    def test_grouped_mm_patch_else_branch_present(self):
+        """An else branch must follow the _hip_ver_at_least gate (skip path for 7.13+)."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        # There must be an else: after the if not _hip_ver_at_least(7, 13): block
+        gate_idx = source.find("if not _hip_ver_at_least(7, 13):")
+        assert gate_idx != -1, "Version gate not found in worker.py"
+        # The else: branch must appear after the gate
+        else_idx = source.find("else:", gate_idx)
+        assert else_idx != -1, "else: branch after _hip_ver_at_least gate not found"
+
+    def test_hip_ver_at_least_handles_amd_version_format(self):
+        """_hip_ver_at_least must split on '.' and compare only major.minor (handles '7.13.99004')."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        # Must split the version string and take the first two parts
+        assert 'split(".")[:2]' in source or ".split('.')[:2]" in source
+
+
+# =============================================================================
+# TEST: install_python_stack.py -- _ROCM_TORCH_PKG_SPECS mapping
+# =============================================================================
+
+
+class TestRocmTorchPkgSpecs:
+    """Verify per-tag torch version specs are correct."""
+
+    def test_rocm72_has_torch_211(self):
+        """rocm7.2 should specify torch 2.11.x."""
+        specs = stack_mod._ROCM_TORCH_PKG_SPECS.get("rocm7.2")
+        assert specs is not None
+        torch_spec = specs[0]
+        assert "2.11" in torch_spec
+
+    def test_default_caps_below_211(self):
+        """Default spec (rocm7.1 and earlier) should cap below 2.11."""
+        specs = stack_mod._ROCM_TORCH_PKG_SPECS.get("_default")
+        assert specs is not None
+        torch_spec = specs[0]
+        assert "<2.11" in torch_spec
+
+    def test_specs_have_torch_vision_audio(self):
+        """Each entry should be a 3-tuple: torch, torchvision, torchaudio."""
+        for tag, specs in stack_mod._ROCM_TORCH_PKG_SPECS.items():
+            assert len(specs) == 3, f"{tag}: expected (torch, torchvision, torchaudio)"
+            assert "torch" in specs[0]
+            assert "torchvision" in specs[1]
+            assert "torchaudio" in specs[2]
+
+    def test_gfx_to_amd_index_covers_rdna4(self):
+        """_GFX_TO_AMD_INDEX_ARCH must cover gfx1200 and gfx1201 (RDNA 4)."""
+        mapping = stack_mod._GFX_TO_AMD_INDEX_ARCH
+        assert mapping.get("gfx1200") == "gfx120X-all"
+        assert mapping.get("gfx1201") == "gfx120X-all"
+
+    def test_gfx_to_amd_index_covers_strix_halo(self):
+        """_GFX_TO_AMD_INDEX_ARCH must cover gfx1151 and gfx1150 (RDNA 3.5)."""
+        mapping = stack_mod._GFX_TO_AMD_INDEX_ARCH
+        assert mapping.get("gfx1151") == "gfx1151"
+        assert mapping.get("gfx1150") == "gfx1150"
+
+    def test_gfx_to_amd_index_covers_rdna3(self):
+        """_GFX_TO_AMD_INDEX_ARCH must cover gfx1100-gfx1103 (RDNA 3)."""
+        mapping = stack_mod._GFX_TO_AMD_INDEX_ARCH
+        for arch in ("gfx1100", "gfx1101", "gfx1102", "gfx1103"):
+            assert mapping.get(arch) == "gfx110X-all", f"{arch} missing from mapping"
+
+
+# =============================================================================
+# TEST: setup.ps1 / install.ps1 -- Strix Halo gfx arch detection
+# =============================================================================
+
+_SETUP_PS1_PATH = PACKAGE_ROOT / "studio" / "setup.ps1"
+_INSTALL_PS1_PATH = PACKAGE_ROOT / "install.ps1"
+
+
+class TestStrixHaloGfxArchDetection:
+    """Verify that setup.ps1 and install.ps1 have robust gfx arch detection
+    for Strix Halo / iGPU users who only have the HIP runtime (no hipinfo)."""
+
+    def test_amd_smi_static_asic_attempted_in_setup(self):
+        """setup.ps1 must try 'amd-smi static --asic' when list output lacks gfx arch."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "static --asic" in source
+
+    def test_amd_smi_static_asic_attempted_in_install(self):
+        """install.ps1 must try 'amd-smi static --asic' when list output lacks gfx arch."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "static --asic" in source
+
+    def test_env_var_override_in_setup(self):
+        """setup.ps1 must honour UNSLOTH_ROCM_GFX_ARCH as a manual arch override."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "UNSLOTH_ROCM_GFX_ARCH" in source
+
+    def test_env_var_override_in_install(self):
+        """install.ps1 must honour UNSLOTH_ROCM_GFX_ARCH as a manual arch override."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "UNSLOTH_ROCM_GFX_ARCH" in source
+
+    def test_name_arch_table_covers_strix_halo_in_setup(self):
+        """setup.ps1 name→arch table must map 890M / Strix Halo to gfx1151."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "gfx1151" in source
+        assert "890M" in source or "Strix Halo" in source
+
+    def test_name_arch_table_covers_strix_halo_in_install(self):
+        """install.ps1 name→arch table must map 890M / Strix Halo to gfx1151."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "gfx1151" in source
+        assert "890M" in source or "Strix Halo" in source
+
+    def test_name_arch_table_covers_strix_point_in_setup(self):
+        """setup.ps1 name→arch table must map 880M / Strix Point to gfx1150."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "gfx1150" in source
+        assert "880M" in source or "Strix Point" in source
+
+    def test_name_arch_table_covers_strix_point_in_install(self):
+        """install.ps1 name→arch table must map 880M / Strix Point to gfx1150."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "gfx1150" in source
+        assert "880M" in source or "Strix Point" in source
+
+    def test_name_arch_table_covers_rdna3_phoenix_in_setup(self):
+        """setup.ps1 name→arch table must map 780M / Phoenix to gfx1103."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "gfx1103" in source
+        assert "780M" in source or "Phoenix" in source
+
+    def test_wmi_does_not_set_hasrocm_in_setup(self):
+        """WMI block in setup.ps1 must NOT set $HasROCm = $true (no runtime confirmation)."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        # Find the WMI block and confirm HasROCm is not set inside it
+        wmi_idx = source.find("Win32_VideoController")
+        assert wmi_idx != -1, "WMI block not found in setup.ps1"
+        # The nearest HasROCm = $true must not appear between the WMI block
+        # and the closing brace of that if-block.  We check by confirming
+        # $HasROCm = $true does NOT appear within 300 chars of the WMI call.
+        wmi_context = source[wmi_idx : wmi_idx + 300]
+        assert "$HasROCm = $true" not in wmi_context
+
+    def test_gfx_arch_regex_parses_from_amd_smi_output(self):
+        """Both files must use the gfx\\d+[a-z]? regex to parse arch from amd-smi output."""
+        for path in (_SETUP_PS1_PATH, _INSTALL_PS1_PATH):
+            source = path.read_text(encoding = "utf-8")
+            # The regex pattern used to match gfx arches
+            assert (
+                "gfx\\d+" in source or r"gfx\d+" in source
+            ), f"gfx arch regex not found in {path.name}"
+
+
+# =============================================================================
+# TEST: HIP SDK tool path resolution via HIP_PATH / ROCM_PATH env vars
+# =============================================================================
+
+
+class TestHipSdkEnvPathResolution:
+    """Verify that both install scripts resolve hipinfo/hipconfig via HIP_PATH
+    and ROCM_PATH when the tools are not on $PATH, and emit explicit warnings."""
+
+    # ── hipinfo resolution ────────────────────────────────────────────────────
+
+    def test_setup_checks_hip_path_for_hipinfo(self):
+        """setup.ps1 must reference HIP_PATH when resolving hipinfo."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP_PATH" in source
+        assert "hipinfo" in source
+
+    def test_install_checks_hip_path_for_hipinfo(self):
+        """install.ps1 must reference HIP_PATH when resolving hipinfo."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP_PATH" in source
+        assert "hipinfo" in source
+
+    def test_setup_checks_rocm_path_as_hipinfo_fallback(self):
+        """setup.ps1 must also check ROCM_PATH as a secondary hipinfo fallback."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCM_PATH" in source
+        # Confirm the fallback pattern: HIP_PATH ?? ROCM_PATH (or equivalent elseif)
+        assert "ROCM_PATH" in source and "HIP_PATH" in source
+
+    def test_install_checks_rocm_path_as_hipinfo_fallback(self):
+        """install.ps1 must also check ROCM_PATH as a secondary hipinfo fallback."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCM_PATH" in source
+        assert "ROCM_PATH" in source and "HIP_PATH" in source
+
+    def test_setup_resolves_hipinfo_via_bin_subdir(self):
+        """setup.ps1 must join the env var root with 'bin\\hipinfo.exe'."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert r"bin\hipinfo.exe" in source
+
+    def test_install_resolves_hipinfo_via_bin_subdir(self):
+        """install.ps1 must join the env var root with 'bin\\hipinfo.exe'."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert r"bin\hipinfo.exe" in source
+
+    # ── hipinfo not-on-PATH warning ───────────────────────────────────────────
+
+    def test_setup_warns_when_hipinfo_not_on_path(self):
+        """setup.ps1 must warn when hipinfo is found via env var but not on PATH."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "hipinfo not on PATH" in source
+
+    def test_install_warns_when_hipinfo_not_on_path(self):
+        """install.ps1 must warn when hipinfo is found via env var but not on PATH."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "hipinfo not on PATH" in source
+
+    # ── warn when HIP_PATH set but exe missing ────────────────────────────────
+
+    def test_setup_warns_when_hip_path_set_but_exe_missing(self):
+        """setup.ps1 must warn when HIP_PATH is set but hipinfo.exe is not present."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        # The warning must mention that the SDK install may be incomplete
+        assert "incomplete" in source or "not found at" in source
+
+    def test_install_warns_when_hip_path_set_but_exe_missing(self):
+        """install.ps1 must warn when HIP_PATH is set but hipinfo.exe is not present."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "incomplete" in source or "not found at" in source
+
+    # ── hipinfo runtime error warning ─────────────────────────────────────────
+
+    def test_setup_warns_on_hipinfo_nonzero_exit(self):
+        """setup.ps1 must warn when hipinfo runs but returns a non-zero exit code."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP runtime error" in source or "runtime error" in source.lower()
+
+    def test_install_warns_on_hipinfo_nonzero_exit(self):
+        """install.ps1 must warn when hipinfo runs but returns a non-zero exit code."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP runtime error" in source or "runtime error" in source.lower()
+
+    # ── hipconfig resolution ──────────────────────────────────────────────────
+
+    def test_setup_resolves_hipconfig_via_bin_subdir(self):
+        """setup.ps1 must also fall back to HIP_PATH/bin/hipconfig.exe for version detection."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert r"bin\hipconfig.exe" in source
+
+    def test_install_resolves_hipconfig_via_bin_subdir(self):
+        """install.ps1 must also fall back to HIP_PATH/bin/hipconfig.exe for version detection."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert r"bin\hipconfig.exe" in source
+
+    def test_setup_warns_when_hipconfig_not_on_path(self):
+        """setup.ps1 must warn when hipconfig is found via env var but not on PATH."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "hipconfig not on PATH" in source
+
+    def test_install_warns_when_hipconfig_not_on_path(self):
+        """install.ps1 must warn when hipconfig is found via env var but not on PATH."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "hipconfig not on PATH" in source
+
+    # ── PATH fix hint ─────────────────────────────────────────────────────────
+
+    def test_setup_provides_path_fix_hint(self):
+        """setup.ps1 must tell the user how to add the HIP bin dir to PATH."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        # Should mention adding to PATH or SetEnvironmentVariable
+        assert "PATH" in source and (
+            "SetEnvironmentVariable" in source or "Add" in source
+        )
+
+    def test_install_provides_path_fix_hint(self):
+        """install.ps1 must tell the user how to add the HIP bin dir to PATH."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "PATH" in source and (
+            "SetEnvironmentVariable" in source or "Add" in source
+        )
+
+
+# =============================================================================
+# TEST: HIP SDK detected substep -- path + hipconfig version shown in terminal
+# =============================================================================
+
+
+class TestHipSdkDetectedSubstep:
+    """Verify that both scripts print HIP SDK path and full hipconfig version
+    as substeps under the gpu step when AMD ROCm is successfully detected."""
+
+    def test_setup_prints_hip_sdk_path_substep(self):
+        """setup.ps1 must print an 'HIP SDK:' substep showing the resolved path."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP SDK:" in source
+
+    def test_install_prints_hip_sdk_path_substep(self):
+        """install.ps1 must print an 'HIP SDK:' substep showing the resolved path."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP SDK:" in source
+
+    def test_setup_shows_hipconfig_full_version(self):
+        """setup.ps1 must capture and display the full hipconfig version string."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCmVersionFull" in source or "hipconfig:" in source
+
+    def test_install_shows_hipconfig_full_version(self):
+        """install.ps1 must capture and display the full hipconfig version string."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCmVersionFull" in source or "hipconfig:" in source
+
+    def test_setup_captures_full_version_not_just_major_minor(self):
+        """setup.ps1 must store the raw hipconfig output line, not just major.minor."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCmVersionFull" in source
+
+    def test_install_captures_full_version_not_just_major_minor(self):
+        """install.ps1 must store the raw hipconfig output line, not just major.minor."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCmVersionFull" in source
+
+    def test_setup_uses_hip_path_or_rocm_path_for_sdk_display(self):
+        """setup.ps1 HIP SDK path substep must check HIP_PATH then ROCM_PATH."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP_PATH" in source and "ROCM_PATH" in source
+
+    def test_install_uses_hip_path_or_rocm_path_for_sdk_display(self):
+        """install.ps1 HIP SDK path substep must check HIP_PATH then ROCM_PATH."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HIP_PATH" in source and "ROCM_PATH" in source
+
+    def test_setup_rocm_step_uses_full_version(self):
+        """setup.ps1 'rocm' step label must prefer the full version string."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "ROCmVersionFull" in source and "rocm" in source
+
+
+# =============================================================================
+# TEST: install.sh -- Strix Halo rocm7.1 → rocm7.2 override
+# =============================================================================
+
+_INSTALL_SH_PATH = PACKAGE_ROOT / "install.sh"
+_SETUP_SH_PATH = PACKAGE_ROOT / "studio" / "setup.sh"
+
+
+class TestStrixRocm71Override:
+    """Verify install.sh skips Radeon repo and routes to AMD arch-specific index
+    for gfx1151/gfx1150 when ROCm 7.1 would otherwise be selected (known _grouped_mm segfault).
+    AMD's repo.amd.com/rocm/whl/gfx1151/ serves torch 2.11+rocm7.13 which has the real fix."""
+
+    def test_strix_gfx_detection_in_install_sh(self):
+        """install.sh must detect gfx1151 and gfx1150 for the override."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        assert "gfx1151" in source and "gfx1150" in source
+
+    def test_rocm71_override_to_amd_arch_index_in_install_sh(self):
+        """install.sh must override TORCH_INDEX_URL to AMD arch-specific index for Strix."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        # The override must route to AMD's arch-specific index (repo.amd.com/rocm/whl)
+        assert "repo.amd.com/rocm/whl" in source
+        assert "_strix_gfx" in source
+        # The URL must incorporate the detected gfx arch so gfx1151 → .../gfx1151/
+        strix_idx = source.find("_amd_strix_base")
+        assert strix_idx != -1
+        ctx = source[strix_idx : strix_idx + 500]
+        assert "_strix_gfx" in ctx
+
+    def test_radeon_repo_bypassed_for_strix_in_install_sh(self):
+        """install.sh must set _amd_gpu_radeon=false when Strix + ROCm 7.1 detected."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        assert "_amd_gpu_radeon=false" in source
+
+    def test_strix_override_warns_with_moe_utils_reference(self):
+        """install.sh must emit a [WARN] mentioning the moe_utils segfault."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        assert "moe_utils" in source or "_grouped_mm" in source
+
+    def test_strix_override_only_fires_on_rocm71(self):
+        """install.sh must scope the Strix override to rocm7.1 only (not rocm7.2+)."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        strix_idx = source.find("_strix_gfx")
+        assert strix_idx != -1
+        # Look back for the rocm7.1 pattern within 600 chars before _strix_gfx
+        context_before = source[max(0, strix_idx - 2400) : strix_idx]
+        assert "rocm7.1" in context_before
+
+    def test_torch_constraint_updated_for_strix_amd_index(self):
+        """install.sh must set TORCH_CONSTRAINT>=2.11 when routing Strix to AMD index."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        assert "TORCH_CONSTRAINT" in source and "2.11" in source
+
+    def test_amd_rocm_mirror_env_var_respected(self):
+        """install.sh must honour UNSLOTH_AMD_ROCM_MIRROR for air-gapped installs."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        assert "UNSLOTH_AMD_ROCM_MIRROR" in source
+
+    def test_tauri_family_recognises_amd_arch_url(self):
+        """_tauri_torch_index_family must return a rocm* family for AMD arch-specific URLs."""
+        source = _INSTALL_SH_PATH.read_text(encoding = "utf-8")
+        # The function must have a case branch for repo.amd.com/rocm/whl/gfx* URLs
+        assert "rocm/whl/gfx" in source
+
+
+# =============================================================================
+# TEST: setup.sh -- gcc-install-dir fix for Ubuntu 24.04 + ROCm 7.x clang-20
+# =============================================================================
+
+
+class TestSetupShGccInstallDir:
+    """Verify setup.sh applies the --gcc-install-dir flag when building llama.cpp
+    with HIP on Ubuntu 24.04+ to work around ROCm 7.x clang-20 header path bug."""
+
+    def test_gcc_install_dir_search_loop_present(self):
+        """setup.sh must iterate gcc versions 14→11 to find one with C++ headers."""
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "_GCC_INSTALL_DIR" in source
+        assert "/usr/lib/gcc/x86_64-linux-gnu" in source
+
+    def test_gcc_install_dir_checks_include_dir(self):
+        """setup.sh must check that the gcc dir has an 'include' subdirectory."""
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "include" in source and "_GCC_INSTALL_DIR" in source
+
+    def test_gcc_install_dir_appended_to_cmake_hip_flags(self):
+        """setup.sh must pass --gcc-install-dir via CMAKE_HIP_FLAGS."""
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "CMAKE_HIP_FLAGS" in source
+        assert "gcc-install-dir" in source
+
+    def test_gcc_install_dir_only_applied_in_hip_build_block(self):
+        """The --gcc-install-dir fix must only apply in the HIP/ROCm build branch."""
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        # GGML_HIP=ON must appear before gcc-install-dir in the source
+        hip_idx = source.find("GGML_HIP=ON")
+        gcc_idx = source.find("gcc-install-dir")
+        assert hip_idx != -1 and gcc_idx != -1
+        assert hip_idx < gcc_idx
+
+    def test_gcc_install_dir_logs_substep(self):
+        """setup.sh must print a substep when the gcc install dir is resolved."""
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "gcc install dir" in source or "GCC_INSTALL_DIR" in source
+
+
+# =============================================================================
+# TEST: main.py -- BNB_ROCM_VERSION server startup + distributed stubs
+# =============================================================================
+
+_MAIN_PY_PATH = PACKAGE_ROOT / "studio" / "backend" / "main.py"
+_HARDWARE_PY_PATH = (
+    PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
+)
+
+
+class TestServerStartupRocmFixes:
+    """Verify main.py sets BNB_ROCM_VERSION before any bitsandbytes import and
+    hardware.py injects torch._C._distributed_c10d stubs before torch.distributed."""
+
+    # ── BNB_ROCM_VERSION in server process ────────────────────────────────────
+
+    def test_main_py_sets_bnb_rocm_version(self):
+        """main.py must set BNB_ROCM_VERSION in the server process before imports."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert "BNB_ROCM_VERSION" in source
+
+    def test_main_py_bnb_detection_scoped_to_win32(self):
+        """main.py BNB_ROCM_VERSION logic must be inside the win32 platform guard."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        win32_idx = source.find('sys.platform == "win32"')
+        bnb_idx = source.find("BNB_ROCM_VERSION")
+        assert win32_idx != -1 and bnb_idx != -1
+        assert win32_idx < bnb_idx
+
+    def test_main_py_bnb_dll_detection_uses_glob(self):
+        """main.py must scan for libbitsandbytes_rocm*.dll to find the right version."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert "libbitsandbytes_rocm" in source
+
+    def test_main_py_bnb_falls_back_to_72(self):
+        """main.py must fall back to BNB_ROCM_VERSION='72' when no DLL is found."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert '"72"' in source or "'72'" in source
+
+    def test_main_py_bnb_only_set_when_not_already_in_env(self):
+        """main.py must not override an existing BNB_ROCM_VERSION env var."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert '"BNB_ROCM_VERSION" not in os.environ' in source
+
+    # ── torch._C._distributed_c10d stubs in hardware.py ──────────────────────
+
+    def test_hardware_py_injects_distributed_c10d_stub(self):
+        """hardware.py must inject torch._C._distributed_c10d into sys.modules."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "_distributed_c10d" in source
+
+    def test_hardware_py_stub_injected_before_distributed_import(self):
+        """The sys.modules stub must be injected BEFORE import torch.distributed."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        c10d_idx = source.find("_distributed_c10d")
+        dist_idx = source.find("import torch.distributed")
+        assert c10d_idx != -1 and dist_idx != -1
+        assert c10d_idx < dist_idx
+
+    def test_hardware_py_stub_uses_types_moduletype(self):
+        """hardware.py must create the stub with types.ModuleType."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "ModuleType" in source
+
+    def test_hardware_py_stub_scoped_to_win32(self):
+        """hardware.py distributed stub injection must be gated on win32."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert 'platform == "win32"' in source or "win32" in source
+
+    def test_hardware_py_stub_exposes_fake_process_group(self):
+        """hardware.py stub must set FakeProcessGroup so torch.distributed doesn't raise AttributeError."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "FakeProcessGroup" in source
+
+    def test_hardware_py_stub_exposes_process_group(self):
+        """hardware.py stub must set ProcessGroup on the c10d stub."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "ProcessGroup" in source
+
+    def test_hardware_py_stub_uses_setattr_for_symbols(self):
+        """hardware.py must use setattr to populate stub symbols dynamically."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "setattr" in source
+
+    def test_hardware_py_stub_all_c10d_siblings_covered(self):
+        """hardware.py must stub all three torch._C._distributed_* submodules."""
+        source = _HARDWARE_PY_PATH.read_text(encoding = "utf-8")
+        assert "_distributed_c10d" in source
+        assert "_distributed_autograd" in source
+        assert "_distributed_rpc" in source
+
+
+# =============================================================================
+# TEST: install.ps1 / setup.ps1 -- HipSdkInstalled flag (SDK found, device inaccessible)
+# =============================================================================
+
+
+class TestHipSdkInstalledButDeviceInaccessible:
+    """Verify that when hipinfo is found but exits non-zero (device not ROCm-accessible),
+    both scripts distinguish this from 'HIP SDK not found' and emit the correct message."""
+
+    def test_install_ps1_has_hip_sdk_installed_flag(self):
+        """install.ps1 must track HipSdkInstalled separately from HasROCm."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HipSdkInstalled" in source
+
+    def test_setup_ps1_has_hip_sdk_installed_flag(self):
+        """setup.ps1 must track HipSdkInstalled separately from HasROCm."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HipSdkInstalled" in source
+
+    def test_install_ps1_sets_flag_when_hipinfo_binary_found(self):
+        """install.ps1 must set HipSdkInstalled=true inside the 'if ($hipinfoExe)' block."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        # HipSdkInstalled must be assigned inside the hipinfoExe block
+        hipinfo_block_idx = source.find("if ($hipinfoExe)")
+        sdk_flag_idx = source.find("$HipSdkInstalled = $true", hipinfo_block_idx)
+        assert hipinfo_block_idx != -1 and sdk_flag_idx != -1
+        assert sdk_flag_idx > hipinfo_block_idx
+
+    def test_setup_ps1_sets_flag_when_hipinfo_binary_found(self):
+        """setup.ps1 must set HipSdkInstalled=true inside the 'if ($hipinfoExe)' block."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        hipinfo_block_idx = source.find("if ($hipinfoExe)")
+        sdk_flag_idx = source.find("$HipSdkInstalled = $true", hipinfo_block_idx)
+        assert hipinfo_block_idx != -1 and sdk_flag_idx != -1
+        assert sdk_flag_idx > hipinfo_block_idx
+
+    def test_install_ps1_version_capture_runs_when_sdk_installed(self):
+        """install.ps1 must capture hipconfig version when HipSdkInstalled even if HasROCm is false."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HasROCm -or $HipSdkInstalled" in source or "$HipSdkInstalled" in source
+
+    def test_setup_ps1_version_capture_runs_when_sdk_installed(self):
+        """setup.ps1 must capture hipconfig version when HipSdkInstalled even if HasROCm is false."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "HasROCm -or $HipSdkInstalled" in source or "$HipSdkInstalled" in source
+
+    def test_install_ps1_distinct_message_for_sdk_found_but_device_inaccessible(self):
+        """install.ps1 must show 'not ROCm-accessible' message (not 'HIP SDK not found') when SDK present."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "not ROCm-accessible" in source
+
+    def test_setup_ps1_distinct_message_for_sdk_found_but_device_inaccessible(self):
+        """setup.ps1 must show 'not ROCm-accessible' message (not 'HIP SDK not found') when SDK present."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "not ROCm-accessible" in source
+
+    def test_install_ps1_driver_guidance_in_sdk_found_branch(self):
+        """install.ps1 must tell user this is a driver issue, not an SDK issue."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "driver issue" in source
+
+    def test_setup_ps1_driver_guidance_in_sdk_found_branch(self):
+        """setup.ps1 must tell user this is a driver issue, not an SDK issue."""
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "driver issue" in source
+
+    def test_install_ps1_cpu_hint_distinguishes_driver_vs_no_sdk(self):
+        """install.ps1 CPU-only hint must say 'GPU not ROCm-accessible' not 'require the HIP SDK' when SDK found."""
+        source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
+        assert "GPU not ROCm-accessible" in source
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index 99da5f799e..c0c6455a2e 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -68,7 +68,10 @@ def _get_env_int(keys):
 
 
 def _infer_distributed_ranks():
-    if torch.distributed.is_available() and torch.distributed.is_initialized():
+    if (
+        torch.distributed.is_available()
+        and getattr(torch.distributed, "is_initialized", lambda: False)()
+    ):
         try:
             return torch.distributed.get_rank(), torch.distributed.get_world_size()
         except Exception:

From 187c81f4091fba80551345f896984e2c4bccd9bb Mon Sep 17 00:00:00 2001
From: Jaeic Lee <2484055+jaeiclee@users.noreply.github.com>
Date: Sat, 30 May 2026 14:30:09 +0900
Subject: [PATCH 021/222] Version downpairing for Radeon+ROCm PyTorch wheels
 (#5353)

* Version downpairing for Radeon+ROCm PyTorch wheels

The radeon repo has often published the absolute highest version for torch, torchvision, and torchaudio independently without forming a proper "trio" of versions that matches the usual "law of five," which can result in a mismatched trio that fails the sanity check, forcing an unnecessary fallback to the standard ROCm index.

To prevent this issue, this commit:
- Refactors _pick_radeon_wheel to support optional version prefix filtering.
- Implements a two-pass resolution:
  1. Identifies the highest available versions for all packages.
  2. Calculates the lowest common denominator minor version.
  3. Re-picks wheels to ensure torch/audio match and vision is +15.
- Prevents silent fallbacks when compatible sets exist but are not the absolute latest entries in the listing.

* Apply Codex + Gemini suggestions

From Codex:

When the computed target minor is not actually present for one of the packages, _pick_radeon_wheel returns non-zero and this assignment runs under the script's top-level set -e, so the installer exits immediately instead of reaching the existing fallback path. This can happen with gapped Radeon listings, e.g. latest torch/vision imply minor 11, latest torchaudio implies minor 10, but the listing only has a complete older 2.9 trio or no torch 2.10 wheel; the new downpair code then aborts on this line rather than warning and falling back.

From Gemini:
medium
The local keyword is not part of the POSIX shell standard. While many modern shells like bash, zsh, and dash support it, this script uses #!/bin/sh and explicitly aims for POSIX compliance (as noted in the comments around line 1671) to ensure portability across different environments like minimal Docker images, BSD, or BusyBox.

Since the _extract_version function is called within a command substitution subshell (e.g., _torch_ver=$(_extract_version ...)), the variables defined inside it are already isolated from the parent shell's environment. Therefore, local is redundant here and should be removed to maintain portability and consistency with the rest of the script.

* Better implementation of Codex's suggestion

When the first computed target minor is not present for a package, this now clears the wheel and the final check falls back immediately, even if the listing contains a complete older trio. For example, with latest torch/vision implying minor 11, latest torchaudio implying 10, but no torch 2.10/vision 0.25 wheels and a complete 2.9/0.24/2.9 set, the new || _torch_whl="" avoids the earlier abort but still never searches below minor 10, so Radeon installs are skipped despite a compatible set being available.

* Second attempt to better implement Codex's suggestion

When the latest package set is mismatched but the downpair loop finds a lower minor, this accepts any nonempty torch/vision/audio wheels for that minor without verifying the full public versions. In a listing such as torch 2.10.1 plus torchaudio 2.10.0 and torchvision 0.25.0, the new loop marks the trio compatible and installs it, even though the change is meant to avoid unsupported torch/audio mismatches; compare the versions after repicking before setting _radeon_versions_match=true.

* Fix regression from trying to implement Codex

* Apply suggestion from @gemini-code-assist[bot]

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Clear triton when accepting a downpaired set

From Codex:

When this loop downpairs torch/vision/audio to an older minor, _tri_whl remains the absolute newest triton selected before the loop. In the multi-generation Radeon listings this block is meant to handle, that can skip a newer torch generation but still install its newer triton wheel via the later install triton + PyTorch command, producing a mismatched triton/PyTorch set instead of the lower generation's matching triton. Re-pick or clear triton when accepting the downpaired trio.

* Remove trailing whitespace on blank lines for PR #5353

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 install.sh | 117 +++++++++++++++++++++++++++++++++++------------------
 1 file changed, 77 insertions(+), 40 deletions(-)

diff --git a/install.sh b/install.sh
index 91fdad8fb4..f0af60e2d6 100755
--- a/install.sh
+++ b/install.sh
@@ -1785,9 +1785,9 @@ print('cp{}{}'.format(sys.version_info.major, sys.version_info.minor))
 }
 
 _pick_radeon_wheel() {
-    # Usage: _pick_radeon_wheel PACKAGE_NAME
+    # Usage: _pick_radeon_wheel PACKAGE_NAME [VERSION_PREFIX]
     # Scans $_RADEON_LISTING for the newest wheel whose filename starts exactly
-    # with PACKAGE_NAME- and matches _RADEON_PYTAG + linux_x86_64.
+    # with PACKAGE_NAME- (and optionally VERSION_PREFIX) and matches _RADEON_PYTAG + linux_x86_64.
     # Prints the full URL (resolving relative hrefs against _RADEON_BASE_URL).
     #
     # POSIX-compliant pipeline: all href parsing, filtering, and version
@@ -1795,11 +1795,12 @@ _pick_radeon_wheel() {
     # for GNU extensions (grep -o, sort -V) that would break under BSD
     # or BusyBox coreutils.
     _pkg="$1"
+    _ver_prefix="${2:-}"
     [ -n "$_RADEON_LISTING" ] || return 1
     [ -n "$_RADEON_PYTAG"   ] || return 1
     _tag="$_RADEON_PYTAG"
     _href=$(printf '%s\n' "$_RADEON_LISTING" \
-        | awk -v pkg="$_pkg" -v tag="$_tag" '
+        | awk -v pkg="$_pkg" -v tag="$_tag" -v ver_prefix="$_ver_prefix" '
             BEGIN { max_pad = ""; max_url = "" }
             {
                 line = $0
@@ -1813,7 +1814,7 @@ _pick_radeon_wheel() {
                     base = p[n]
                     sub(/[?#].*/, "", base)
 
-                    prefix = pkg "-"
+                    prefix = pkg "-" ver_prefix
                     # Match cpXY-cpXY or cpXY-abi3 with any linux x86_64
                     # platform tag (linux_x86_64, manylinux_2_28_x86_64,
                     # manylinux2014_x86_64, etc.)
@@ -2112,24 +2113,23 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
 
             if [ "$_radeon_listing_ok" = true ]; then
                 # Require torch, torchvision, torchaudio wheels to all resolve
-                # from the Radeon listing. If any is missing for this Python
-                # tag, fall through to the standard ROCm index instead of
-                # silently mixing Radeon wheels with PyPI defaults.
+                # from the Radeon listing. The repo often publishes multiple
+                # generations simultaneously, so picking the highest-version
+                # for each package independently can assemble a mismatched trio
+                # (e.g. torch 2.10 + torchvision 0.24). To prevent this,
+                # we identify the highest common minor version and downpair
+                # wheels if necessary to ensure a compatible set.
                 _torch_whl=$(_pick_radeon_wheel "torch"       2>/dev/null) || _torch_whl=""
                 _tv_whl=$(_pick_radeon_wheel    "torchvision" 2>/dev/null) || _tv_whl=""
                 _ta_whl=$(_pick_radeon_wheel    "torchaudio"  2>/dev/null) || _ta_whl=""
                 _tri_whl=$(_pick_radeon_wheel   "triton"      2>/dev/null) || _tri_whl=""
-                # Sanity-check torch / torchvision / torchaudio are a
-                # matching release. The Radeon repo publishes multiple
-                # generations simultaneously, so picking the highest-version
-                # wheel for each package independently can assemble a
-                # mismatched trio (e.g. torch 2.9.1 + torchvision 0.23.0 +
-                # torchaudio 2.9.0 from the current rocm-rel-7.2.1 index).
+
                 # Check that torch and torchaudio share the same X.Y public
                 # version prefix, and that torchvision's minor correctly
-                # pairs with torch's minor (torchvision = torch.minor - 5
+                # pairs with torch's minor (torchvision = torch.minor + 15
                 # since torch 2.4 -> torchvision 0.19 -> torch 2.9 ->
                 # torchvision 0.24).
+                #
                 # URL-decode each wheel name so %2B -> + before version
                 # extraction. Real Radeon wheel hrefs are percent-encoded
                 # (torch-2.10.0%2Brocm7.2.0...), so a plain [+-] terminator
@@ -2137,38 +2137,75 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
                 # _radeon_versions_match would stay false for every real
                 # listing, silently forcing a fallback to the generic
                 # ROCm index.
-                _torch_ver=""
-                _tv_ver=""
-                _ta_ver=""
-                if [ -n "$_torch_whl" ]; then
-                    _torch_name=$(printf '%s' "${_torch_whl##*/}" | sed 's/%2[Bb]/+/g')
-                    _torch_ver=$(printf '%s\n' "$_torch_name" | sed -n 's|^torch-\([0-9][0-9]*\.[0-9][0-9]*\)\(\.[0-9][0-9]*\)\{0,1\}[+-].*|\1|p')
-                fi
-                if [ -n "$_tv_whl" ]; then
-                    _tv_name=$(printf '%s' "${_tv_whl##*/}" | sed 's/%2[Bb]/+/g')
-                    _tv_ver=$(printf '%s\n' "$_tv_name" | sed -n 's|^torchvision-\([0-9][0-9]*\.[0-9][0-9]*\)\(\.[0-9][0-9]*\)\{0,1\}[+-].*|\1|p')
-                fi
-                if [ -n "$_ta_whl" ]; then
-                    _ta_name=$(printf '%s' "${_ta_whl##*/}" | sed 's/%2[Bb]/+/g')
-                    _ta_ver=$(printf '%s\n' "$_ta_name" | sed -n 's|^torchaudio-\([0-9][0-9]*\.[0-9][0-9]*\)\(\.[0-9][0-9]*\)\{0,1\}[+-].*|\1|p')
-                fi
+                _extract_version() {
+                    _whl=$1
+                    _pkg=$2
+                    if [ -n "$_whl" ]; then
+                        _name=$(printf '%s' "${_whl##*/}" | sed 's/%2[Bb]/+/g')
+                        printf '%s\n' "$_name" | sed -n "s|^${_pkg}-\([0-9][0-9]*\.[0-9][0-9]*\)\(\.[0-9][0-9]*\)\{0,1\}[+-].*|\1|p"
+                    fi
+                }
+
+                _torch_ver=$(_extract_version "$_torch_whl" "torch")
+                _tv_ver=$(_extract_version "$_tv_whl" "torchvision")
+                _ta_ver=$(_extract_version "$_ta_whl" "torchaudio")
+
                 _radeon_versions_match=false
                 if [ -n "$_torch_ver" ] && [ -n "$_tv_ver" ] && [ -n "$_ta_ver" ]; then
-                    _torch_major=${_torch_ver%%.*}
                     _torch_minor=${_torch_ver#*.}
-                    _ta_major=${_ta_ver%%.*}
                     _ta_minor=${_ta_ver#*.}
-                    _tv_major=${_tv_ver%%.*}
                     _tv_minor=${_tv_ver#*.}
-                    # torchvision expected minor (e.g. torch 2.9 -> 0.24)
-                    _expected_tv_minor=$((_torch_minor + 15))
-                    if [ "$_torch_major" = "$_ta_major" ] && \
-                       [ "$_torch_minor" = "$_ta_minor" ] && \
-                       [ "$_tv_major" = "0" ] && \
-                       [ "$_tv_minor" = "$_expected_tv_minor" ]; then
-                        _radeon_versions_match=true
-                    fi
+                    _tv_equiv_minor=$((_tv_minor - 15))
+
+                    # Determine initial target minor (lowest common denominator)
+                    _target_minor=$_torch_minor
+                    [ "$_tv_equiv_minor" -lt "$_target_minor" ] && _target_minor=$_tv_equiv_minor
+                    [ "$_ta_minor" -lt "$_target_minor" ] && _target_minor=$_ta_minor
+
+                    # Loop downwards to find the first complete matching trio.
+                    # This avoids aborting if the repo has gaps.
+                    _attempts=0
+                    while [ "$_attempts" -lt 5 ] && [ "$_target_minor" -ge 0 ]; do
+                        _expected_tv_minor=$((_target_minor + 15))
+
+                        _curr_torch=$(_pick_radeon_wheel "torch"       "2.${_target_minor}." 2>/dev/null) || _curr_torch=""
+                        _curr_tv=$(_pick_radeon_wheel    "torchvision" "0.${_expected_tv_minor}." 2>/dev/null) || _curr_tv=""
+                        _curr_ta=$(_pick_radeon_wheel    "torchaudio"  "2.${_target_minor}." 2>/dev/null) || _curr_ta=""
+
+                        if [ -n "$_curr_torch" ] && [ -n "$_curr_tv" ] && [ -n "$_curr_ta" ]; then
+                            # Extract versions from the wheels found in this iteration
+                            _c_torch_ver=$(_extract_version "$_curr_torch" "torch")
+                            _c_tv_ver=$(_extract_version "$_curr_tv" "torchvision")
+                            _c_ta_ver=$(_extract_version "$_curr_ta" "torchaudio")
+
+                            # Parse Major.Minor for validation
+                            _c_torch_major=${_c_torch_ver%%.*}
+                            _c_torch_minor=${_c_torch_ver#*.}
+                            _c_ta_major=${_c_ta_ver%%.*}
+                            _c_ta_minor=${_c_ta_ver#*.}
+                            _c_tv_major=${_c_tv_ver%%.*}
+                            _c_tv_minor=${_c_tv_ver#*.}
+
+                            # Strict X.Y validation: allow patch versions to differ (e.g. torch 2.9.1 + vision 0.24.0)
+                            # as long as the Major and Minor pairing is correct.
+                            if [ "$_c_torch_major" = "$_c_ta_major" ] && \
+                               [ "$_c_torch_minor" = "$_c_ta_minor" ] && \
+                               [ "$_c_tv_major" = "0" ] && \
+                               [ "$_c_tv_minor" = "$((_c_torch_minor + 15))" ]; then
+
+                                _torch_whl=$_curr_torch
+                                _tv_whl=$_curr_tv
+                                _ta_whl=$_curr_ta
+                                _tri_whl=""
+                                _radeon_versions_match=true
+                                break
+                            fi
+                        fi
+                        _target_minor=$((_target_minor - 1))
+                        _attempts=$((_attempts + 1))
+                    done
                 fi
+
                 if [ -z "$_torch_whl" ] || [ -z "$_tv_whl" ] || [ -z "$_ta_whl" ] || \
                    [ "$_radeon_versions_match" != true ]; then
                     substep "[WARN] Radeon repo lacks a compatible wheel set for this Python; falling back to ROCm index ($TORCH_INDEX_URL)" "$C_WARN"

From 61df3aaef00bdb54dde443b358a6001bc9b5d33f Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Sat, 30 May 2026 00:46:03 -0500
Subject: [PATCH 022/222] feature/use lemonade-sdk llamacpp-rocm binaries
 (#5303)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(studio): use lemonade-sdk/llamacpp-rocm per-GPU prebuilts for ROCm hosts

For AMD GPUs that rocminfo/hipinfo reports a recognised gfx target
(gfx103X / gfx110X / gfx1150 / gfx1151 / gfx120X), resolve_lemonade_rocm_choice()
now fetches the latest lemonade-sdk/llamacpp-rocm release and returns the
matching per-architecture zip, bundling all required ROCm runtime libs.

This runs before the existing upstream ggml-org combined-ROCm tarball fallback
on Linux and before the upstream HIP zip on Windows, so both platforms benefit
from the more targeted build when available.

Changes:
- Add LEMONADE_ROCM_REPO / LEMONADE_ROCM_RELEASES_API constants
- Add HostInfo.rocm_gfx_target populated from rocminfo (Linux) / hipinfo (Windows)
- Add _LEMONADE_GFX_FAMILIES prefix map and _lemonade_gfx_family() helper
- Add resolve_lemonade_rocm_choice() that fetches latest lemonade release and
  constructs the llama-{tag}-{os}-rocm-{gfxFamily}-x64.zip asset URL
- Wire into resolve_upstream_asset_choice() for both Linux (ubuntu) and Windows paths

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Honor pinned llama.cpp tag in lemonade ROCm resolver

The resolver always fetched lemonade-sdk/llamacpp-rocm's /releases/latest,
ignoring the upstream llama.cpp tag the caller had pinned. On a reproducible
install where the user requested 'b1260' that meant we would silently pick
up whatever lemonade had published as latest at install time, with no way
to roll back to the matching tag.

Lemonade tags llama.cpp upstream tags 1:1, so:
  - When llama_tag is unset or 'latest', keep hitting /releases/latest.
  - When llama_tag is pinned (e.g. 'b1260'), hit /releases/tags/b1260.
  - When the pinned tag is not published by lemonade (404), skip silently
    and let the caller fall through to the upstream tarball -- this keeps
    pinned installs reproducible instead of drifting.

resolve_lemonade_rocm_choice now takes llama_tag (default 'latest' for
backward compatibility) and both call sites in resolve_upstream_asset_choice
forward the upstream llama_tag to it.

Note: this PR still has open integration concerns flagged in review --
the simple-policy planner and approved-checksum manifest don't yet route
or accept lemonade assets. Those are larger changes and not in scope for
this commit; addressing the pinned-tag drift independently because it is
small, localized, and self-contained.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add mock test for lemonade ROCm prebuilt asset resolution

Validates GPU family mapping and that resolve_lemonade_rocm_choice
returns real lemonade release URLs for all supported gfx targets on
both Linux and Windows, without requiring AMD hardware.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Wire lemonade ROCm prebuilts into the simple-policy install path

setup.sh invokes install_llama_prebuilt.py with --simple-policy, which
dispatches through resolve_simple_install_release_plans -> direct_linux_release_plan
(or direct_upstream_release_plan on Windows). Those planners only
handled CUDA + CPU attempts, so ROCm-only hosts (e.g. gfx1151 Strix
Halo) had no compatible prebuilt asset and silently fell through to
source build, even though resolve_lemonade_rocm_choice already knew
how to fetch a per-GPU lemonade-sdk binary.

Add a lemonade ROCm/HIP attempt to both simple-policy planners for
ROCm-only hosts, and add regression tests that drive the dispatchers
end-to-end so this can't be skipped silently again.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Document that lemonade ROCm prebuilts work on any glibc Linux

The lemonade-sdk asset filename uses "ubuntu" as a label, but the binary
is a manylinux-style glibc build with no Ubuntu-specific dependencies.
It runs on Arch, Fedora, openSUSE, Debian, etc. as long as the host
glibc is recent enough.

No behavior change -- the dispatch already runs for any Linux ROCm
host. This commit only clarifies the comment, docstring, and log
message so users on non-Ubuntu distros (e.g. Strix Halo on Arch) don't
mistake the asset name for distro gating.

* Pattern matching fix for libggml-cpu*.so*

* fix(lemonade): pass resolved tag to lemonade resolver; add upstream HIP fallback; stub API in tests

- direct_linux_release_plan: pass bundle.upstream_tag (not requested_tag)
  to resolve_lemonade_rocm_choice so a "latest" request doesn't mix a
  newer lemonade binary with an older planned unsloth release (Codex P2)

- direct_upstream_release_plan: same fix on the Windows path (release_tag
  instead of requested_tag); also add the upstream HIP asset
  (llama-<tag>-bin-win-hip-radeon-x64.zip) as a fallback between lemonade
  and CPU so unsupported GPUs or transient lemonade failures don't silently
  downgrade to CPU when an upstream ROCm prebuilt exists (Codex P2)

- test file: stub fetch_json with a synthetic lemonade release payload so
  the suite is hermetic and not subject to GitHub API rate limits (Codex P1);
  add test_simple_policy_windows_hip_falls_back_to_upstream_when_lemonade_unavailable
  to cover the new HIP fallback path

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(lemonade): revert bad tag fix; keep upstream HIP fallback + hermetic tests

The previous commit wrongly passed bundle.upstream_tag / release_tag to
resolve_lemonade_rocm_choice. Lemonade uses its own versioning (b1262,
b1264, …) completely independent of unslothai's tags (b9186, …), so
passing a resolved unslothai tag caused a 404 and silently skipped the
lemonade binary entirely. Revert both call sites to requested_tag.

Keep the two valid fixes from the prior commit:
- Upstream HIP fallback (llama-<tag>-bin-win-hip-radeon-x64.zip) between
  lemonade and CPU in direct_upstream_release_plan, so unsupported GPUs
  or transient lemonade failures don't silently downgrade to CPU (Codex P2)
- Stub fetch_json in tests so the suite is hermetic (Codex P1)

* fix(studio/rocm): respect HIP_VISIBLE_DEVICES when picking lemonade gfx target

The rocminfo / hipinfo regex took the first gfx match in the agent listing.
On mixed APU + dGPU hosts (e.g. Strix Halo gfx1151 + discrete RX 7900 gfx1100)
this picked whichever GPU appeared first in the tool's stdout, not the one
HIP actually runs on. The downloaded lemonade asset could then be a binary
for a different arch than the active device.

Extracted a module-level _pick_rocm_gfx_target() helper that:
- collects every gfx token in order via re.findall (skips gfx000 / generic ISAs)
- if HIP_VISIBLE_DEVICES or ROCR_VISIBLE_DEVICES is set, parses the first
  comma-separated entry as an integer index into that list
- falls back to the first GPU for non-integer (UUID-style) or out-of-range
  values, matching the previous default behaviour

Both Linux (rocminfo) and Windows (hipinfo) branches use the helper.
Existing 18 lemonade tests pass; no behavioural change for single-GPU hosts.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): dedup rocminfo gfx tokens and honor disabled visibility

Follow-up to 8793aef0. rocminfo / hipinfo emit each gfx target multiple
times per GPU (Name, ISA triple, marketing name), so the prior re.findall
indexing returned the wrong device when HIP_VISIBLE_DEVICES picked GPU 1
on a mixed-arch host -- the helper picked the second occurrence of GPU 0
instead. Collapse to unique tokens (insertion-ordered) before indexing.

Also handle HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES values of '' and
'-1' as "no AMD visible" (matches the rest of Studio's visibility code),
returning None so the planner does not pick a Lemonade asset for a
hidden GPU.

* fix(studio/rocm): memoise lemonade release lookup + HIP_PATH hipinfo fallback

Robustness pass on top of 25d4ab63:

1. resolve_lemonade_rocm_choice() is called twice per install (planner +
   resolve_upstream_asset_choice), so every install previously hit
   api.github.com twice with identical args -- doubling the 403/rate-limit
   failure surface on busy CI runners. Extract the fetch into a
   functools.lru_cache(maxsize=8) helper keyed on (api_url, llama_tag).
   The cached helper also owns the error-path logging the resolver was
   doing inline. Tests that need to vary fetch_json output across
   invocations should call _fetch_lemonade_release_cached.cache_clear().

2. Windows detect_host probe for hipinfo / amd-smi only used
   shutil.which(), so HIP SDK installs that set HIP_PATH but do not put
   %HIP_PATH%\bin on system PATH classified the host as non-ROCm. The
   PowerShell installer and studio/install_python_stack.py already
   resolve HIP_PATH\bin\hipinfo.exe as a fallback; mirror that here so
   the install planner agrees with the rest of Studio on what counts as
   a ROCm host.

Tests: 18 passed (shipped); 52 extra sim cases pass (added 2 for the
lru_cache deduplication path).

* fix(studio/rocm): lemonade URL trust pinning, runtime overlay covers HIP libs, opt-out env

Robustness pass driven by 5 parallel reviewers of head c08b15e6:

1. URL trust pinning. AssetChoice.url comes from the GitHub API response's
   browser_download_url field. Lemonade attempts are not in the approved-hash
   manifest, so a compromised API response could redirect the download to an
   attacker-chosen host without the integrity gate catching it. New
   _is_trusted_github_release_url() validates https + github.com/<expected_repo>
   release path OR objects.githubusercontent.com (GitHub's CDN). Resolver
   refuses to download otherwise.

2. UNSLOTH_DISABLE_LEMONADE_ROCM opt-out. Users who prefer the upstream HIP
   build path can set this env var to skip lemonade outright (e.g. for
   air-gapped installs or stricter trust requirements). The install log
   already prints a NOTE explaining that lemonade lacks approved-hash
   coverage so users know the trust model.

3. linux-rocm runtime overlay patterns extended to cover lemonade's bundled
   HIP/ROCm runtime libs (libamdhip64.so*, libhsa-runtime64.so*, libhipblas*,
   librocblas*, librocsolver*, librocsparse*, librocrand*, libMIOpen*,
   libmagma*). The upstream tarball does not ship these (links against
   system /opt/rocm), so the new glob entries are no-op for upstream and
   load-bearing for lemonade. Without this, install_from_archives would
   drop the bundled runtime libs from the lemonade ZIP and llama-server's
   RPATH would fail to load amdhip64 at first inference.

4. _lemonade_release_api_for now URL-encodes llama_tag with quote(safe="").
   Defence in depth: a tag containing /, ?, #, or whitespace cannot reshape
   the request URL. Tags come from internal resolution today, but this
   removes the risk if a future caller passes user-controlled input.

5. Empty browser_download_url skipped explicitly in the resolver. The
   release_asset_map helper defaults missing URLs to "". Previously this
   would have been passed to download_file("") which raises a less obvious
   error than the new clean log + return None.

6. Docstring on _lemonade_release_api_for clarified: lemonade tags match
   ggml-org/llama.cpp tags 1:1, NOT unslothai/llama.cpp fork tags. The
   earlier P1 review report misread this and re-asked for the tag-drift
   fix that the author intentionally reverted in f256cea950.

7. Autouse pytest fixture in test_lemonade_llamacpp_rocm_bins_mock.py
   clears _fetch_lemonade_release_cached between tests. Today's tests all
   mock the same payload so no pollution surfaces, but the lru_cache
   becomes a footgun the moment any future test parametrises return values.

Tests: 28 passed (was 18, added 10 covering URL pinning, opt-out env,
pinned-tag helper, URL encoding, empty URL, runtime patterns).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(studio/rocm): complete lemonade runtime overlay + honor CUDA_VISIBLE_DEVICES

runtime_patterns_for_choice("linux-rocm") was missing libamd_comgr.so*,
librocm_kpack.so*, and librocm_sysdeps_*.so*, which are direct NEEDED
entries of libamdhip64.so.7 in every lemonade bundle. install_from_archives
did not copy them, so the preflight ldd walk failed on llama-server and every
lemonade attempt fell back to source build. Confirmed on gfx1151 b1272 by
h34v3nzc0dex; manually staging the full bundle with the three missing
patterns restored the install and preserved bench parity.

Also extend _pick_rocm_gfx_target to check CUDA_VISIBLE_DEVICES after
HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES: AMD's HIP runtime honours
all three with identical semantics, so mixed-arch hosts where users set
only CUDA_VISIBLE_DEVICES were still picking the first gfx token instead
of the user-selected device.

Tests: 30 passed (was 28); added 2 for CUDA_VISIBLE_DEVICES (multi-GPU
pick + -1 opt-out) and extended the runtime-patterns test to assert the
three newly added lib globs are present.

* fix: tighten CDN trust check and fix multi-GPU arch selection

- _is_trusted_github_release_url: require /github-production-release-asset-
  path prefix so only real GitHub release CDN URLs are accepted
- _pick_rocm_gfx_target: parse rocminfo Agent N section boundaries to build
  a per-physical-GPU arch list; same arch across multiple GPUs no longer
  collapses to a single token, so HIP_VISIBLE_DEVICES indexing works correctly
- tests: update CDN test to use realistic path prefix, add rejection test for
  arbitrary CDN path, add regression test for same-arch multi-GPU case

* fix: use broad lib*.so* glob for linux-rocm runtime overlay

Replace the explicit lib allowlist in runtime_patterns_for_choice with
lib*.so* for the linux-rocm path.

The lemonade ROCm ZIPs carry a full HIP/ROCm runtime including transitive
deps like libLLVM.so.23.0git and libclang-cpp.so.23.0git (pulled in by
libamd_comgr.so.3). These names change across ROCm releases and were not
in the allowlist, so preflight would see them as unresolved NEEDED entries
and fall back to a source build. The broad glob catches everything in the
bundle now and in future releases without needing to enumerate each library.

* fix: show lemonade binary tag in install summary log line

Store binary_repo and binary_release_tag in UNSLOTH_PREBUILT_INFO.json
so the setup.sh summary can distinguish the source tree (unslothai/llama.cpp)
from the actual binary origin (lemonade-sdk/llamacpp-rocm).

Before: 'installed release: unslothai/llama.cpp@b9334'
After:  'installed release: unslothai/llama.cpp@b9334 + lemonade@b1280'

Upstream installs are unchanged (binary_repo == published_repo).

* fix(merge-compat): align Windows ROCm guard and helper name with strix branch

- elif host.has_rocm instead of if...not to match fix/rocm-strix-halo-unified-memory
- _resolve_exe instead of _resolve_amd_exe with identical body/docstring

Eliminates the two conflict hunks that would otherwise block a clean bot merge
of feature/lemonade-rocm-prebuilts on top of fix/rocm-strix-halo-unified-memory.

* fix: three PR review corrections for lemonade ROCm prebuilt integration

- _lemonade_release_api_for: fix docstring claiming lemonade tags match
  ggml-org 1:1 -- lemonade may be several builds behind ggml-org (noted
  by oobabooga, confirmed: lemonade b1281 vs ggml-org b9370)
- direct_linux_release_plan: move cpu_choice into else-branch so ROCm-only
  hosts never get a CPU fallback in the attempts list -- a failed lemonade
  binary now raises PrebuiltFallback and triggers the HIP source build
  instead of silently installing a CPU-only binary
- apply_approved_hashes: pass lemonade attempts through without requiring
  a manifest entry; lemonade is explicitly documented as relying on
  functional validation only, so rejecting it here caused PrebuiltFallback
  on the non-simple-policy path before the upstream ROCm/HIP fallback
  could be considered

* fix: copy hipblaslt/rocblas library subdirs from lemonade ROCm archives

copy_globs matches filenames only and copies flat, so it cannot
preserve the hipblaslt/library/<gfx>/ and rocblas/library/<gfx>/
Tensile kernel catalog trees that lemonade ROCm zips ship alongside
the .so files. Add runtime_subdirs_for_choice() and call shutil.copytree
for each named subdir after the copy_globs pass in install_from_archives.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
Co-authored-by: Jaeic Lee <jaeiclee@users.noreply.github.com>
---
 .../test_lemonade_llamacpp_rocm_bins_mock.py  | 430 ++++++++++++++++++
 studio/install_llama_prebuilt.py              | 371 ++++++++++++++-
 studio/setup.sh                               |  15 +-
 3 files changed, 806 insertions(+), 10 deletions(-)
 create mode 100644 studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py

diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
new file mode 100644
index 0000000000..5d2d672890
--- /dev/null
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -0,0 +1,430 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Validates that the installer correctly resolves lemonade ROCm prebuilt assets.
+
+Uses a faked HostInfo so no AMD GPU is needed. Network calls to the lemonade
+GitHub API are stubbed out so the suite runs without internet access and is
+not subject to rate limits.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_studio = Path(__file__).resolve().parent.parent.parent
+if str(_studio) not in sys.path:
+    sys.path.insert(0, str(_studio))
+
+_mod = importlib.import_module("install_llama_prebuilt")
+HostInfo = _mod.HostInfo
+resolve_lemonade_rocm_choice = getattr(_mod, "resolve_lemonade_rocm_choice", None)
+_LEMONADE_GFX_FAMILIES = getattr(_mod, "_LEMONADE_GFX_FAMILIES", None)
+
+if resolve_lemonade_rocm_choice is None or _LEMONADE_GFX_FAMILIES is None:
+    pytest.skip("PR symbols not present - check branch", allow_module_level = True)
+
+
+@pytest.fixture(autouse = True)
+def _clear_lemonade_release_cache():
+    """Prevent cross-test pollution of the lemonade release lru_cache when
+    future tests vary the fetch_json mock return value."""
+    _cache = getattr(_mod, "_fetch_lemonade_release_cached", None)
+    if _cache is not None and hasattr(_cache, "cache_clear"):
+        _cache.cache_clear()
+    yield
+    if _cache is not None and hasattr(_cache, "cache_clear"):
+        _cache.cache_clear()
+
+
+_STUB_TAG = "b1262"
+_STUB_OS_PREFIXES = ("ubuntu", "windows")
+_STUB_FAMILIES = ("gfx1151", "gfx1150", "gfx120X", "gfx110X", "gfx103X")
+
+
+def _stub_lemonade_release() -> dict:
+    """Minimal lemonade release payload covering all supported GPU/OS combinations."""
+    assets = [
+        {
+            "name": f"llama-{_STUB_TAG}-{prefix}-rocm-{family}-x64.zip",
+            "browser_download_url": (
+                f"https://github.com/lemonade-sdk/llamacpp-rocm/releases/download/"
+                f"{_STUB_TAG}/llama-{_STUB_TAG}-{prefix}-rocm-{family}-x64.zip"
+            ),
+        }
+        for prefix in _STUB_OS_PREFIXES
+        for family in _STUB_FAMILIES
+    ]
+    return {"tag_name": _STUB_TAG, "assets": assets}
+
+
+def _make_rocm_host(gfx_target: str, *, windows: bool = False) -> HostInfo:
+    return HostInfo(
+        system = "Windows" if windows else "Linux",
+        machine = "amd64" if windows else "x86_64",
+        is_windows = windows,
+        is_linux = not windows,
+        is_macos = False,
+        is_x86_64 = True,
+        is_arm64 = False,
+        nvidia_smi = None,
+        driver_cuda_version = None,
+        compute_caps = [],
+        visible_cuda_devices = None,
+        has_physical_nvidia = False,
+        has_usable_nvidia = False,
+        has_rocm = True,
+        rocm_gfx_target = gfx_target,
+    )
+
+
+def _lookup_family(gfx: str) -> str | None:
+    for prefix, family in _LEMONADE_GFX_FAMILIES:
+        if gfx.startswith(prefix):
+            return family
+    return None
+
+
+# ---------------------------------------------------------------------------
+# GPU family mapping
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "gfx,expected_family",
+    [
+        ("gfx1151", "gfx1151"),
+        ("gfx1150", "gfx1150"),
+        ("gfx1201", "gfx120X"),
+        ("gfx1200", "gfx120X"),
+        ("gfx1100", "gfx110X"),
+        ("gfx1030", "gfx103X"),
+    ],
+)
+def test_gpu_family_mapping(gfx, expected_family):
+    assert _lookup_family(gfx) == expected_family
+
+
+def test_unknown_gpu_not_in_families():
+    assert _lookup_family("gfx999") is None
+
+
+# ---------------------------------------------------------------------------
+# Asset resolution - hits real lemonade GitHub API
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "gfx,os_prefix,windows",
+    [
+        ("gfx1151", "ubuntu", False),
+        ("gfx1150", "ubuntu", False),
+        ("gfx1201", "ubuntu", False),
+        ("gfx1100", "ubuntu", False),
+        ("gfx1030", "ubuntu", False),
+        ("gfx1151", "windows", True),
+        ("gfx1100", "windows", True),
+    ],
+)
+def test_asset_resolves_for_known_gpu(gfx, os_prefix, windows):
+    host = _make_rocm_host(gfx, windows = windows)
+    with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
+        result = resolve_lemonade_rocm_choice(
+            host, os_prefix, "default", llama_tag = "latest"
+        )
+    assert (
+        result is not None
+    ), f"Installer will NOT fetch lemonade binary for {gfx} ({os_prefix})"
+    assert _lookup_family(gfx) in result.name
+    assert result.url.startswith("https://github.com/lemonade-sdk/llamacpp-rocm")
+
+
+def test_unknown_gpu_falls_through_to_upstream():
+    host = _make_rocm_host("gfx999")
+    result = resolve_lemonade_rocm_choice(host, "ubuntu", "default", llama_tag = "latest")
+    assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Simple-policy dispatcher must plan a lemonade ROCm attempt for AMD-only hosts.
+# This is the path setup.sh actually invokes (via --simple-policy), so the
+# lemonade integration is useless if it isn't wired in here.
+# ---------------------------------------------------------------------------
+
+direct_linux_release_plan = getattr(_mod, "direct_linux_release_plan", None)
+direct_upstream_release_plan = getattr(_mod, "direct_upstream_release_plan", None)
+
+
+def _stub_unsloth_release(release_tag: str = "b9022") -> dict:
+    # Minimal payload that parse_direct_linux_release_bundle accepts. It
+    # requires at least one `app-{label}-linux-x64*.tar.gz` asset for the
+    # bundle to be recognised; we ship a bare CPU one so the planner has a
+    # baseline non-ROCm attempt to fall through to.
+    asset_name = f"app-{release_tag}-linux-x64.tar.gz"
+    return {
+        "tag_name": release_tag,
+        "name": release_tag,
+        "assets": [
+            {
+                "name": asset_name,
+                "browser_download_url": f"https://example.invalid/{asset_name}",
+            },
+        ],
+    }
+
+
+@pytest.mark.skipif(
+    direct_linux_release_plan is None,
+    reason = "simple-policy dispatcher not present on this branch",
+)
+def test_simple_policy_plans_lemonade_for_rocm_host():
+    host = _make_rocm_host("gfx1151")
+    with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
+        plan = direct_linux_release_plan(
+            _stub_unsloth_release(),
+            host,
+            "unslothai/llama.cpp",
+            "latest",
+        )
+    assert plan is not None, "ROCm host should not be skipped by simple-policy planner"
+    kinds = [a.install_kind for a in plan.attempts]
+    assert (
+        "linux-rocm" in kinds
+    ), f"simple-policy planner did not include a lemonade ROCm attempt; got {kinds}"
+    rocm_attempt = next(a for a in plan.attempts if a.install_kind == "linux-rocm")
+    assert rocm_attempt.source_label == "lemonade"
+    assert "gfx1151" in rocm_attempt.name
+
+
+@pytest.mark.skipif(
+    direct_upstream_release_plan is None,
+    reason = "simple-policy dispatcher not present on this branch",
+)
+def test_simple_policy_plans_lemonade_for_windows_hip_host():
+    host = _make_rocm_host("gfx1151", windows = True)
+    release = {
+        "tag_name": "b9022",
+        "name": "b9022",
+        "assets": [],
+    }
+    with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
+        plan = direct_upstream_release_plan(
+            release, host, "ggml-org/llama.cpp", "latest"
+        )
+    assert plan is not None, "Windows ROCm host should plan a lemonade HIP attempt"
+    kinds = [a.install_kind for a in plan.attempts]
+    assert (
+        "windows-hip" in kinds
+    ), f"simple-policy planner did not include a lemonade HIP attempt; got {kinds}"
+
+
+@pytest.mark.skipif(
+    direct_upstream_release_plan is None,
+    reason = "simple-policy dispatcher not present on this branch",
+)
+def test_simple_policy_windows_hip_falls_back_to_upstream_when_lemonade_unavailable():
+    """If lemonade returns None (e.g. gfx999 or transient API failure), the planner
+    must still include the upstream HIP asset rather than silently downgrading to CPU."""
+    host = _make_rocm_host("gfx999", windows = True)
+    hip_asset = "llama-b9022-bin-win-hip-radeon-x64.zip"
+    release = {
+        "tag_name": "b9022",
+        "name": "b9022",
+        "assets": [
+            {
+                "name": hip_asset,
+                "browser_download_url": f"https://example.invalid/{hip_asset}",
+            },
+        ],
+    }
+    plan = direct_upstream_release_plan(release, host, "ggml-org/llama.cpp", "latest")
+    assert plan is not None
+    kinds = [a.install_kind for a in plan.attempts]
+    assert (
+        "windows-hip" in kinds
+    ), f"upstream HIP asset not included as fallback; got {kinds}"
+    hip_attempt = next(a for a in plan.attempts if a.install_kind == "windows-hip")
+    assert hip_attempt.source_label == "upstream"
+
+
+# ── Follow-up: pinned-tag URL helper, URL trust pinning, opt-out env, autouse cache clear ──
+
+
+def test_lemonade_release_api_url_pinned_tag():
+    """A pinned llama_tag must produce the /releases/tags/<tag> URL."""
+    assert _mod._lemonade_release_api_for("b1262").endswith("/releases/tags/b1262")
+    assert _mod._lemonade_release_api_for("latest").endswith("/releases/latest")
+    assert _mod._lemonade_release_api_for("").endswith("/releases/latest")
+
+
+def test_lemonade_release_api_url_encodes_tag():
+    """Unexpected slashes / hashes in the tag must be URL-encoded so the URL
+    cannot be reshaped (defence in depth -- tags should already be sanitised
+    upstream)."""
+    url = _mod._lemonade_release_api_for("b1260/../latest")
+    assert "/releases/tags/b1260%2F..%2Flatest" in url
+    assert "//latest" not in url.split("/releases/tags/", 1)[1]
+
+
+def test_lemonade_resolver_skipped_by_opt_out_env(monkeypatch):
+    """UNSLOTH_DISABLE_LEMONADE_ROCM=1 must short-circuit the resolver."""
+    monkeypatch.setenv("UNSLOTH_DISABLE_LEMONADE_ROCM", "1")
+    host = _make_rocm_host("gfx1151")
+    res = resolve_lemonade_rocm_choice(host, "ubuntu", "linux-rocm", llama_tag = "latest")
+    assert res is None
+
+
+def test_lemonade_resolver_rejects_non_github_url(monkeypatch):
+    """If the GitHub API response somehow contained an off-host download URL,
+    the resolver must refuse to use it (lemonade assets are not in the
+    approved-hash manifest)."""
+    bad_release = {
+        "tag_name": _STUB_TAG,
+        "assets": [
+            {
+                "name": f"llama-{_STUB_TAG}-ubuntu-rocm-gfx1151-x64.zip",
+                "browser_download_url": "https://attacker.invalid/llama.zip",
+            },
+        ],
+    }
+    host = _make_rocm_host("gfx1151")
+    with patch.object(_mod, "fetch_json", return_value = bad_release):
+        res = resolve_lemonade_rocm_choice(
+            host, "ubuntu", "linux-rocm", llama_tag = "latest"
+        )
+    assert res is None
+
+
+def test_lemonade_resolver_rejects_http_scheme():
+    assert not _mod._is_trusted_github_release_url(
+        "http://github.com/lemonade-sdk/llamacpp-rocm/releases/download/x/y.zip",
+        "lemonade-sdk/llamacpp-rocm",
+    )
+
+
+def test_lemonade_resolver_accepts_github_cdn():
+    # Real GitHub release CDN URLs carry the /github-production-release-asset- prefix.
+    assert _mod._is_trusted_github_release_url(
+        "https://objects.githubusercontent.com/github-production-release-asset-abc123/456/789?token=x",
+        "lemonade-sdk/llamacpp-rocm",
+    )
+
+
+def test_lemonade_resolver_rejects_arbitrary_cdn_path():
+    # A CDN URL without the release-asset path prefix must be rejected.
+    assert not _mod._is_trusted_github_release_url(
+        "https://objects.githubusercontent.com/abc/def",
+        "lemonade-sdk/llamacpp-rocm",
+    )
+
+
+def test_lemonade_resolver_accepts_release_path():
+    url = "https://github.com/lemonade-sdk/llamacpp-rocm/releases/download/b1262/llama-b1262-ubuntu-rocm-gfx1151-x64.zip"
+    assert _mod._is_trusted_github_release_url(url, "lemonade-sdk/llamacpp-rocm")
+
+
+def test_lemonade_resolver_rejects_wrong_repo():
+    """A github.com release URL for a different repo must be rejected."""
+    assert not _mod._is_trusted_github_release_url(
+        "https://github.com/attacker/llamacpp-rocm/releases/download/x/y.zip",
+        "lemonade-sdk/llamacpp-rocm",
+    )
+
+
+def test_lemonade_resolver_rejects_empty_browser_download_url():
+    """An asset entry with an empty browser_download_url must fall through."""
+    release = {
+        "tag_name": _STUB_TAG,
+        "assets": [
+            {
+                "name": f"llama-{_STUB_TAG}-ubuntu-rocm-gfx1151-x64.zip",
+                "browser_download_url": "",
+            },
+        ],
+    }
+    host = _make_rocm_host("gfx1151")
+    with patch.object(_mod, "fetch_json", return_value = release):
+        res = resolve_lemonade_rocm_choice(
+            host, "ubuntu", "linux-rocm", llama_tag = "latest"
+        )
+    assert res is None
+
+
+def test_lemonade_runtime_patterns_include_hip_runtime():
+    """linux-rocm overlay must use a broad lib glob to catch all bundled .so files.
+
+    Lemonade ZIPs carry transitive deps (libamd_comgr, libLLVM, libclang-cpp,
+    ...) whose names change across ROCm releases. A broad ``lib*.so*`` glob
+    avoids having to enumerate every transitive dependency by name.
+    """
+    from install_llama_prebuilt import runtime_patterns_for_choice, AssetChoice
+
+    choice = AssetChoice(
+        repo = "lemonade-sdk/llamacpp-rocm",
+        tag = "b1262",
+        name = "llama-b1262-ubuntu-rocm-gfx1151-x64.zip",
+        url = "https://github.com/lemonade-sdk/llamacpp-rocm/releases/download/b1262/x.zip",
+        source_label = "lemonade",
+        install_kind = "linux-rocm",
+    )
+    pats = runtime_patterns_for_choice(choice)
+    # The broad glob must be present so every .so in the lemonade bundle
+    # (including transitive deps added in future ROCm releases) gets overlaid.
+    assert "lib*.so*" in pats, f"'lib*.so*' missing from linux-rocm patterns: {pats}"
+
+
+_pick_rocm_gfx_target = getattr(_mod, "_pick_rocm_gfx_target", None)
+
+
+@pytest.mark.skipif(
+    _pick_rocm_gfx_target is None,
+    reason = "_pick_rocm_gfx_target not present on this branch",
+)
+def test_pick_rocm_gfx_target_honors_cuda_visible_devices(monkeypatch):
+    """AMD HIP honours CUDA_VISIBLE_DEVICES identically to HIP_VISIBLE_DEVICES;
+    on a gfx1151 + gfx1100 mixed host, CUDA_VISIBLE_DEVICES=1 must select gfx1100."""
+    # Two GPUs; rocminfo reports each token twice (as in the real tool output).
+    probe_out = "gfx1151\ngfx1151\ngfx1100\ngfx1100"
+    monkeypatch.delenv("HIP_VISIBLE_DEVICES", raising = False)
+    monkeypatch.delenv("ROCR_VISIBLE_DEVICES", raising = False)
+    monkeypatch.setenv("CUDA_VISIBLE_DEVICES", "1")
+    assert _pick_rocm_gfx_target(probe_out) == "gfx1100"
+
+
+@pytest.mark.skipif(
+    _pick_rocm_gfx_target is None,
+    reason = "_pick_rocm_gfx_target not present on this branch",
+)
+def test_pick_rocm_gfx_target_cuda_visible_devices_minus_one_returns_none(monkeypatch):
+    """CUDA_VISIBLE_DEVICES=-1 means no GPU visible; resolver must return None."""
+    probe_out = "gfx1151\ngfx1100"
+    monkeypatch.delenv("HIP_VISIBLE_DEVICES", raising = False)
+    monkeypatch.delenv("ROCR_VISIBLE_DEVICES", raising = False)
+    monkeypatch.setenv("CUDA_VISIBLE_DEVICES", "-1")
+    assert _pick_rocm_gfx_target(probe_out) is None
+
+
+@pytest.mark.skipif(
+    _pick_rocm_gfx_target is None,
+    reason = "_pick_rocm_gfx_target not present on this branch",
+)
+def test_pick_rocm_gfx_target_same_arch_multi_gpu(monkeypatch):
+    """Regression: [gfx1100, gfx1100, gfx1151] with HIP_VISIBLE_DEVICES=2 must
+    return gfx1151, not fall back to GPU 0 due to dict.fromkeys collapsing the
+    two gfx1100 entries into one and making index 2 out of range."""
+    # Simulate rocminfo output for 3 GPUs (2x gfx1100 dGPU + 1x gfx1151 APU).
+    # Each GPU gets its own Agent section with a few token mentions.
+    probe_out = (
+        "***\nAgent 1\n***\n  gfx1100 some info\n  gfx1100\n"
+        "***\nAgent 2\n***\n  gfx1100 some info\n  gfx1100\n"
+        "***\nAgent 3\n***\n  gfx1151 some info\n  gfx1151\n"
+    )
+    monkeypatch.delenv("ROCR_VISIBLE_DEVICES", raising = False)
+    monkeypatch.delenv("CUDA_VISIBLE_DEVICES", raising = False)
+    monkeypatch.setenv("HIP_VISIBLE_DEVICES", "2")
+    assert _pick_rocm_gfx_target(probe_out) == "gfx1151"
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 31fb841414..9443b13fd7 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -9,6 +9,7 @@ from __future__ import annotations
 import argparse
 import errno
 import fnmatch
+import functools
 import hashlib
 import json
 import os
@@ -100,6 +101,39 @@ DEFAULT_PUBLISHED_SHA256_ASSET = os.environ.get(
 )
 UPSTREAM_REPO = "ggml-org/llama.cpp"
 UPSTREAM_RELEASES_API = f"https://api.github.com/repos/{UPSTREAM_REPO}/releases/latest"
+
+LEMONADE_ROCM_REPO = "lemonade-sdk/llamacpp-rocm"
+LEMONADE_ROCM_RELEASES_API = (
+    f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}/releases/latest"
+)
+
+
+def _lemonade_release_api_for(llama_tag: str) -> str:
+    """Return the GitHub API URL for the lemonade release that matches a
+    requested llama.cpp tag.
+
+    When llama_tag is unset or "latest", point at /releases/latest. When the
+    caller has pinned a specific tag (e.g. "b1260"), point at the same tag in
+    lemonade. Lemonade tracks `ggml-org/llama.cpp` build tags (e.g. "b1260")
+    but is NOT guaranteed to publish every upstream build -- lemonade may be
+    several builds behind ggml-org. Pinning to a specific tag that lemonade
+    skipped will produce a 404 and the caller falls through to the upstream
+    tarball; that is intentional so pinned installs stay reproducible.
+    Do NOT pass a `unslothai/llama.cpp` fork tag -- the fork uses its own
+    namespace and will always 404 against lemonade.
+
+    The tag is URL-encoded with `safe=""` so an unexpected slash / hash / query
+    character cannot reshape the URL.
+    """
+    normalized = (llama_tag or "").strip()
+    if not normalized or normalized.lower() == "latest":
+        return LEMONADE_ROCM_RELEASES_API
+    return (
+        f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}/releases/tags/"
+        f"{urllib.parse.quote(normalized, safe = '')}"
+    )
+
+
 TEST_MODEL_URL = (
     "https://huggingface.co/ggml-org/models/resolve/main/tinyllamas/stories260K.gguf"
 )
@@ -196,6 +230,7 @@ class HostInfo:
     has_physical_nvidia: bool
     has_usable_nvidia: bool
     has_rocm: bool = False
+    rocm_gfx_target: str | None = None
 
 
 @dataclass
@@ -1268,9 +1303,26 @@ def direct_linux_release_plan(
         selection = linux_cuda_choice_from_release(host, bundle)
         if selection is not None:
             attempts.extend(selection.attempts)
-    cpu_choice = published_asset_choice_for_kind(bundle, "linux-cpu")
-    if cpu_choice is not None:
-        attempts.append(cpu_choice)
+    if host.has_rocm and not host.has_usable_nvidia:
+        # Per-GPU lemonade prebuilts ship the ROCm runtime libs alongside
+        # llama.cpp, so they install cleanly even on hosts (e.g. gfx1151
+        # Strix Halo) that the upstream combined-ROCm tarball doesn't cover.
+        # The "ubuntu" label is lemonade's asset naming convention only --
+        # the binary is a manylinux-style glibc build that runs on Arch,
+        # Fedora, openSUSE, etc. as long as the host glibc is recent enough.
+        # Do NOT append the CPU asset for ROCm-only hosts: if lemonade fails
+        # validation we want validate_prebuilt_attempts to raise PrebuiltFallback
+        # so the caller triggers the HIP source build, not silently install a
+        # CPU-only binary.
+        lemonade_choice = resolve_lemonade_rocm_choice(
+            host, "ubuntu", "linux-rocm", llama_tag = requested_tag
+        )
+        if lemonade_choice is not None:
+            attempts.append(lemonade_choice)
+    else:
+        cpu_choice = published_asset_choice_for_kind(bundle, "linux-cpu")
+        if cpu_choice is not None:
+            attempts.append(cpu_choice)
     if not attempts:
         raise PrebuiltFallback("no compatible Linux prebuilt asset was found")
     approved_checksums = synthetic_checksums_for_release(
@@ -1337,6 +1389,11 @@ def direct_upstream_release_plan(
                 )
             )
         elif host.has_rocm:
+            lemonade_choice = resolve_lemonade_rocm_choice(
+                host, "windows", "windows-hip", llama_tag = requested_tag
+            )
+            if lemonade_choice is not None:
+                attempts.append(lemonade_choice)
             hip_asset = f"llama-{release_tag}-bin-win-hip-radeon-x64.zip"
             hip_url = assets.get(hip_asset)
             if hip_url:
@@ -2618,6 +2675,72 @@ def run_capture(
     return result
 
 
+def _pick_rocm_gfx_target(out: str) -> str | None:
+    """Choose the gfx target rocminfo / hipinfo report for the active GPU.
+
+    A bare first-match picked the wrong device on mixed APU + dGPU hosts
+    (e.g. Strix Halo gfx1151 + discrete RX 7900 gfx1100). Respect
+    HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES / CUDA_VISIBLE_DEVICES so the
+    asset matches what HIP actually runs on. Falls back to the first GPU when
+    no env var is set.
+
+    rocminfo / hipinfo print the same gfx token multiple times per GPU (Name,
+    ISA, marketing-name). We first try to split the output on per-GPU section
+    headers (rocminfo: "Agent N" blocks, hipinfo: "device#N" entries) and take
+    exactly one gfx token per section. This gives the correct per-GPU list even
+    on same-arch multi-GPU hosts (e.g. two RX 7900 XTX cards) where global
+    dict.fromkeys dedup would collapse both cards to a single entry and make
+    HIP_VISIBLE_DEVICES=1 point out of range.
+
+    Falls back to insertion-order dedup when the output has no recognisable
+    section markers (flat gfx-string inputs, unit-test stubs, etc.).
+
+    Empty / "-1" env values mean no AMD GPU is visible to HIP: return None.
+    """
+    # Try to build a per-GPU token list by splitting on section boundaries.
+    # rocminfo sections are introduced by "Agent N" lines (optionally between
+    # rows of asterisks). hipinfo sections start with "device#N".
+    _sections = re.split(
+        r"(?mi)^\s*\*+\s*$\s*agent\s+\d+\s*$|\bdevice\s*#\s*\d+\b",
+        out,
+    )
+    if len(_sections) > 1:
+        # Section-based: one gfx token per GPU section preserves physical order.
+        _tokens: list[str] = []
+        for _sec in _sections[1:]:
+            _m = re.search(r"gfx[1-9][0-9a-z]{2,3}", _sec.lower())
+            if _m:
+                _tokens.append(_m.group(0))
+    else:
+        # Fallback: insertion-order dedup (handles flat strings / unknown formats).
+        _raw = re.findall(r"gfx[1-9][0-9a-z]{2,3}", out.lower())
+        _tokens = list(dict.fromkeys(_raw))
+
+    if not _tokens:
+        return None
+
+    _vis_raw = None
+    # AMD's HIP runtime honours all three env vars with identical semantics.
+    for _env in ("HIP_VISIBLE_DEVICES", "ROCR_VISIBLE_DEVICES", "CUDA_VISIBLE_DEVICES"):
+        _val = os.environ.get(_env)
+        if _val is not None:
+            _vis_raw = _val
+            break
+    if _vis_raw is not None:
+        _vis = _vis_raw.strip()
+        # Empty or "-1" means "no AMD GPU visible" (matches the rest of Studio).
+        if _vis == "" or _vis == "-1":
+            return None
+        _first = _vis.split(",")[0].strip()
+        try:
+            _idx = int(_first)
+            if 0 <= _idx < len(_tokens):
+                return _tokens[_idx]
+        except ValueError:
+            pass
+    return _tokens[0]
+
+
 def detect_host() -> HostInfo:
     system = platform.system()
     machine = platform.machine().lower()
@@ -2721,6 +2844,7 @@ def detect_host() -> HostInfo:
         return bool(re.search(r"(?im)^gpu\s*[:\[]\s*\d", stdout))
 
     has_rocm = False
+    rocm_gfx_target: str | None = None
     if is_linux:
         for _cmd, _check in (
             # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
@@ -2743,6 +2867,7 @@ def detect_host() -> HostInfo:
             if _result.returncode == 0 and _result.stdout.strip():
                 if _check(_result.stdout):
                     has_rocm = True
+                    rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
     elif is_windows:
         # Windows: prefer active probes that validate GPU presence.
@@ -2778,6 +2903,8 @@ def detect_host() -> HostInfo:
             if _result.returncode == 0 and _result.stdout.strip():
                 if _check(_result.stdout):
                     has_rocm = True
+                    # hipinfo reports "gcnArchName: gfx1100" -- extract if present
+                    rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
         # Note: amdhip64.dll presence alone is NOT treated as GPU evidence
         # since the HIP SDK can be installed without an AMD GPU.
@@ -2797,6 +2924,7 @@ def detect_host() -> HostInfo:
         has_physical_nvidia = has_physical_nvidia,
         has_usable_nvidia = has_usable_nvidia,
         has_rocm = has_rocm,
+        rocm_gfx_target = rocm_gfx_target,
     )
 
 
@@ -3295,6 +3423,185 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
     return None
 
 
+# Map detected gfx IDs to lemonade-sdk asset family suffixes.
+# More-specific prefixes must come before shorter ones (e.g. gfx1151 before gfx110).
+_LEMONADE_GFX_FAMILIES: list[tuple[str, str]] = [
+    ("gfx1151", "gfx1151"),
+    ("gfx1150", "gfx1150"),
+    ("gfx120", "gfx120X"),
+    ("gfx110", "gfx110X"),
+    ("gfx103", "gfx103X"),
+]
+
+
+def _lemonade_gfx_family(gfx_id: str) -> str | None:
+    gfx_id = gfx_id.lower().strip()
+    for prefix, family in _LEMONADE_GFX_FAMILIES:
+        if gfx_id.startswith(prefix):
+            return family
+    return None
+
+
+def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
+    """Validate a release asset URL points at GitHub's expected hosts.
+
+    Accepts:
+      https://github.com/{expected_repo}/releases/download/...
+      https://objects.githubusercontent.com/...   (GitHub's release CDN)
+    Anything else (including http://, raw.githubusercontent.com, gist, etc.)
+    is rejected so a malicious API response cannot redirect downloads to an
+    attacker-chosen host.
+    """
+    if not isinstance(url, str) or not url:
+        return False
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except Exception:
+        return False
+    if parsed.scheme != "https":
+        return False
+    host = (parsed.netloc or "").lower()
+    if host == "objects.githubusercontent.com":
+        # GitHub's release CDN. Restrict to release-asset paths so a tampered
+        # API response pointing at an arbitrary CDN object is still rejected.
+        # Real release asset URLs carry the "/github-production-release-asset-"
+        # prefix; gist / raw / avatar CDN paths do not.
+        return parsed.path.startswith("/github-production-release-asset-")
+    if host == "github.com":
+        return parsed.path.startswith(f"/{expected_repo}/releases/download/")
+    return False
+
+
+@functools.lru_cache(maxsize = 8)
+def _fetch_lemonade_release_cached(api_url: str, llama_tag: str) -> "dict | None":
+    """Cached wrapper around fetch_json for lemonade release lookups.
+
+    resolve_lemonade_rocm_choice() is called twice per install (once from the
+    direct planner, once from resolve_upstream_asset_choice) with identical
+    arguments. Without memoisation, each install hits api.github.com twice,
+    doubling the rate-limit failure surface on busy CI runners. Cache is
+    process-scoped; tests that need to vary fetch_json's return value across
+    invocations should call cache_clear().
+    """
+    try:
+        return fetch_json(api_url)
+    except Exception as exc:
+        normalized = (llama_tag or "").strip().lower()
+        if normalized and normalized != "latest":
+            log(
+                f"Could not fetch {LEMONADE_ROCM_REPO} release for "
+                f"llama_tag={llama_tag!r} ({exc}); skipping lemonade prebuilt"
+            )
+        else:
+            log(f"Could not fetch {LEMONADE_ROCM_REPO} latest release: {exc}")
+        return None
+
+
+def resolve_lemonade_rocm_choice(
+    host: HostInfo,
+    os_prefix: str,
+    install_kind: str,
+    llama_tag: str = "latest",
+) -> "AssetChoice | None":
+    """Return an AssetChoice from lemonade-sdk/llamacpp-rocm for the detected GPU, or None.
+
+    os_prefix:   lemonade's asset filename label, NOT a host-distro filter.
+                 Pass "ubuntu" for any Linux host (Arch, Fedora, openSUSE,
+                 Debian, ...) -- lemonade only publishes one Linux variant
+                 and it is a manylinux-style glibc build that runs on any
+                 distro with a recent-enough glibc. Pass "windows" for
+                 Windows hosts.
+    install_kind: "linux-rocm" or "windows-hip"
+    llama_tag:   the requested upstream llama.cpp tag ("latest" or a pinned
+                 release like "b1260"). When pinned, the resolver fetches
+                 the matching lemonade release. When the pinned tag is not
+                 published by lemonade we skip silently (and the caller
+                 falls through to upstream) rather than drift to whatever
+                 lemonade ships as latest.
+    """
+    if not host.rocm_gfx_target:
+        return None
+    # Opt-out for users who want the upstream HIP build path only -- lemonade
+    # binaries are downloaded without entries in the approved-hash manifest, so
+    # the integrity gate is functional validation only.
+    if os.environ.get("UNSLOTH_DISABLE_LEMONADE_ROCM", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    ):
+        log("UNSLOTH_DISABLE_LEMONADE_ROCM is set; skipping lemonade-sdk prebuilt")
+        return None
+    gfx_family = _lemonade_gfx_family(host.rocm_gfx_target)
+    if gfx_family is None:
+        log(
+            f"AMD GPU {host.rocm_gfx_target!r} is not covered by lemonade-sdk ROCm prebuilts; "
+            "skipping lemonade prebuilt"
+        )
+        return None
+    api_url = _lemonade_release_api_for(llama_tag)
+    release = _fetch_lemonade_release_cached(api_url, llama_tag)
+    if release is None:
+        return None
+    release_tag = release.get("tag_name") if isinstance(release, dict) else None
+    if not isinstance(release_tag, str) or not release_tag:
+        log(
+            f"Unexpected {LEMONADE_ROCM_REPO} release payload; skipping lemonade prebuilt"
+        )
+        return None
+    assets = release_asset_map(release)
+    asset_name = f"llama-{release_tag}-{os_prefix}-rocm-{gfx_family}-x64.zip"
+    if asset_name not in assets:
+        log(
+            f"{LEMONADE_ROCM_REPO}@{release_tag} has no asset {asset_name!r}; "
+            "skipping lemonade prebuilt"
+        )
+        return None
+    asset_url = assets[asset_name]
+    if not asset_url:
+        # release_asset_map defaults to "" when an asset row is missing
+        # browser_download_url; skip cleanly instead of letting
+        # download_file("") raise a less obvious error downstream.
+        log(
+            f"{LEMONADE_ROCM_REPO}@{release_tag} asset {asset_name!r} has no "
+            "browser_download_url; skipping lemonade prebuilt"
+        )
+        return None
+    # Defence in depth: lemonade browser_download_url should be on github.com
+    # or githubusercontent.com. A compromised GitHub API response that
+    # redirects to an attacker-chosen host would otherwise be honoured
+    # silently (lemonade assets are not in the approved-hash manifest).
+    if not _is_trusted_github_release_url(asset_url, LEMONADE_ROCM_REPO):
+        log(
+            f"{LEMONADE_ROCM_REPO}@{release_tag} asset {asset_name!r} points "
+            f"to an unexpected host ({asset_url!r}); refusing to download "
+            "lemonade prebuilt"
+        )
+        return None
+    # Note: lemonade tags Linux assets with "ubuntu" but the binary is a
+    # generic glibc build that runs on any distro (Arch, Fedora, ...), so
+    # this attempt is selected for all Linux ROCm hosts, not just Ubuntu.
+    log(
+        f"AMD GPU {host.rocm_gfx_target!r} ({gfx_family}) -- "
+        f"trying lemonade-sdk ROCm prebuilt {asset_name} "
+        f"(works on any glibc Linux, not just Ubuntu)"
+    )
+    log(
+        f"NOTE: lemonade-sdk/llamacpp-rocm releases are not covered by the "
+        f"Unsloth approved-hash manifest; download integrity relies on "
+        f"functional validation (llama-bench / llama-server smoke tests) "
+        f"after extraction. Set UNSLOTH_DISABLE_LEMONADE_ROCM=1 to skip "
+        f"lemonade and fall back to the upstream HIP build path."
+    )
+    return AssetChoice(
+        repo = LEMONADE_ROCM_REPO,
+        tag = release_tag,
+        name = asset_name,
+        url = asset_url,
+        source_label = "lemonade",
+        install_kind = install_kind,
+    )
+
+
 def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice:
     upstream_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
     if host.is_linux and host.is_x86_64:
@@ -3303,6 +3610,15 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
         # the exact GPU target via rocminfo, which is more reliable for consumer
         # GPUs (e.g. gfx1151) that may not be in the prebuilt.
         if host.has_rocm and not host.has_usable_nvidia:
+            # Try lemonade-sdk per-GPU prebuilt first: these are built against
+            # specific gfx targets and bundle all required ROCm runtime libs.
+            lemonade_choice = resolve_lemonade_rocm_choice(
+                host, "ubuntu", "linux-rocm", llama_tag = llama_tag
+            )
+            if lemonade_choice is not None:
+                return lemonade_choice
+
+            # Fall back to upstream combined ROCm tarball.
             # Scan upstream assets for any rocm-<version> prebuilt. When the
             # host ROCm runtime version is known, pick the newest candidate
             # whose major.minor is <= host version -- otherwise a ROCm 6.4
@@ -3382,8 +3698,14 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                 return attempts[0]
             raise PrebuiltFallback("no compatible Windows CUDA asset was found")
 
-        # AMD ROCm on Windows: try HIP prebuilt
+        # AMD ROCm on Windows: try lemonade per-GPU prebuilt first, then upstream HIP
         if host.has_rocm:
+            lemonade_choice = resolve_lemonade_rocm_choice(
+                host, "windows", "windows-hip", llama_tag = llama_tag
+            )
+            if lemonade_choice is not None:
+                return lemonade_choice
+
             hip_name = f"llama-{llama_tag}-bin-win-hip-radeon-x64.zip"
             if hip_name in upstream_assets:
                 log(
@@ -3924,6 +4246,22 @@ def runtime_patterns_for_choice(choice: AssetChoice) -> list[str]:
     )
 
 
+def runtime_subdirs_for_choice(choice: AssetChoice) -> list[str]:
+    """Subdirectory names within the archive root that must be copied into
+    the overlay directory alongside the flat shared libraries.
+
+    hipBLASLt and rocBLAS expect their Tensile kernel catalog trees
+    (hipblaslt/library/<gfx>/ and rocblas/library/<gfx>/) to sit next to
+    their shared libraries at runtime.  These trees are multi-level and
+    cannot be handled by copy_globs (filename-only matching, flat copy)."""
+    if choice.source_label == "lemonade" and choice.install_kind in {
+        "linux-rocm",
+        "windows-hip",
+    }:
+        return ["hipblaslt", "rocblas"]
+    return []
+
+
 def metadata_patterns_for_choice(choice: AssetChoice) -> list[str]:
     patterns = ["BUILD_INFO.txt", "THIRD_PARTY_LICENSES.txt"]
     if choice.install_kind.startswith("windows"):
@@ -4248,6 +4586,10 @@ def install_from_archives(
         copy_globs(
             source_dir, overlay_dir, runtime_patterns_for_choice(choice), required = True
         )
+        for _subdir in runtime_subdirs_for_choice(choice):
+            _src_subdir = source_dir / _subdir
+            if _src_subdir.is_dir():
+                shutil.copytree(_src_subdir, overlay_dir / _subdir, dirs_exist_ok = True)
         if runtime_extract_dir is not None:
             # The runtime archive only contributes the CUDA DLLs.
             # Restrict the overlay to the cudart bundle's known
@@ -4996,6 +5338,15 @@ def apply_approved_hashes(
     approved_attempts: list[AssetChoice] = []
     missing_assets: list[str] = []
     for attempt in attempts:
+        # External prebuilts (e.g. lemonade-sdk) are not listed in the
+        # approved-hash manifest; they are explicitly documented as relying
+        # on functional validation only (llama-bench / smoke tests).
+        # Passing them through here lets the caller include both a lemonade
+        # attempt and a hash-approved upstream fallback in the same list
+        # without apply_approved_hashes discarding the lemonade entry.
+        if attempt.source_label == "lemonade":
+            approved_attempts.append(attempt)
+            continue
         approved = approved_hash_for_attempt(attempt)
         if approved is None:
             missing_assets.append(attempt.name)
@@ -5196,6 +5547,12 @@ def write_prebuilt_metadata(
         "asset": choice.name,
         "asset_sha256": choice.expected_sha256,
         "source": choice.source_label,
+        # Binary-side repo/tag for non-upstream sources (e.g. lemonade).
+        # published_repo/release_tag always refer to the unsloth source tree;
+        # these capture where the actual binaries came from so the install
+        # summary can show both (e.g. "unslothai/llama.cpp@b9334 + lemonade@b1280").
+        "binary_repo": choice.repo,
+        "binary_release_tag": choice.tag,
         "source_asset": source_asset_name,
         "source_sha256": source_sha256,
         "source_commit": approved_checksums.source_commit,
@@ -5274,7 +5631,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             ["libllama.so*"],
             ["libggml.so*"],
             ["libggml-base.so*"],
-            ["libggml-cpu-*.so*"],
+            ["libggml-cpu*.so*"],
             ["libmtmd.so*"],
         ]
     if choice.install_kind == "linux-cuda":
@@ -5283,7 +5640,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             ["libllama.so*"],
             ["libggml.so*"],
             ["libggml-base.so*"],
-            ["libggml-cpu-*.so*"],
+            ["libggml-cpu*.so*"],
             ["libmtmd.so*"],
             ["libggml-cuda.so*"],
         ]
@@ -5299,7 +5656,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             ["libllama.so*"],
             ["libggml.so*"],
             ["libggml-base.so*"],
-            ["libggml-cpu-*.so*"],
+            ["libggml-cpu*.so*"],
             ["libmtmd.so*"],
             ["libggml-hip.so*"],
         ]
diff --git a/studio/setup.sh b/studio/setup.sh
index f178a5e5d7..3b263a08da 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -181,12 +181,21 @@ if not isinstance(payload, dict):
 repo = str(payload.get("published_repo") or "").strip()
 release_tag = str(payload.get("release_tag") or "").strip()
 llama_tag = str(payload.get("tag") or "").strip()
+source = str(payload.get("source") or "").strip()
+binary_repo = str(payload.get("binary_repo") or "").strip()
+binary_tag = str(payload.get("binary_release_tag") or "").strip()
 if not repo or not release_tag:
     raise SystemExit(0)
 
-message = f"installed release: {repo}@{release_tag}"
-if llama_tag and llama_tag != release_tag:
-    message += f" (tag {llama_tag})"
+# For non-upstream sources (e.g. lemonade) the published_repo/release_tag
+# refer to the unsloth source tree while the actual binaries came from a
+# different repo. Show both so the log is unambiguous.
+if source and source != "upstream" and binary_repo and binary_tag and binary_repo != repo:
+    message = f"installed release: {repo}@{release_tag} + {source}@{binary_tag}"
+else:
+    message = f"installed release: {repo}@{release_tag}"
+    if llama_tag and llama_tag != release_tag:
+        message += f" (tag {llama_tag})"
 print(message)
 PY
 }

From 8ec9a74fd35afe410b943b504470d4bcd089ec97 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sat, 30 May 2026 03:06:47 -0700
Subject: [PATCH 023/222] studio: ROCm cleanups follow-up to #5301 (#5874)

Follow-up cleanups to the merged AMD ROCm support PR #5301:

1. De-duplicate the torchao Windows-ROCm import stub into a single shared
   module (studio/backend/core/_torchao_stub.py); both workers call one
   install_torchao_windows_rocm_stub() entrypoint.
2. Align the gfx name/arch comment columns in setup.sh and setup.ps1.
3. Isolate the float16 dtype fallback to AMD without native bf16; NVIDIA
   keeps dtype=None so unsloth's own bf16/fp16/FORCE_FLOAT32 detection is
   honored.
4. Hoist unconditional stdlib imports (gc, glob, re, subprocess, copy,
   types, sys, importlib.metadata) from function bodies to module top
   across the PR #5301-touched files; heavy/optional/relative imports stay
   lazy.
5. bitsandbytes Windows-ROCm install now uses plain pip (force_pip=True)
   instead of UV_SKIP_WHEEL_FILENAME_CHECK, per the AMD hackathon docs.

Also adds scripts/verify_import_hoist.py (a scope-aware LEGB AST resolver
that catches dangling-alias and rename-clash bugs in import-hoist
refactors) and wires it into the Lint CI source-lint job as a self-test
plus a pull_request compare gate.
---
 .github/workflows/lint-ci.yml              |  50 ++
 scripts/verify_import_hoist.py             | 854 +++++++++++++++++++++
 studio/backend/core/_torchao_stub.py       | 142 ++++
 studio/backend/core/export/worker.py       |  98 +--
 studio/backend/core/inference/llama_cpp.py |  10 +-
 studio/backend/core/training/trainer.py    |  47 +-
 studio/backend/core/training/worker.py     | 132 +---
 studio/backend/main.py                     |   2 -
 studio/backend/utils/hardware/hardware.py  |  60 +-
 studio/install_python_stack.py             |  47 +-
 studio/setup.ps1                           |  14 +-
 studio/setup.sh                            |  12 +-
 tests/studio/install/test_rocm_support.py  |  75 +-
 13 files changed, 1179 insertions(+), 364 deletions(-)
 create mode 100644 scripts/verify_import_hoist.py
 create mode 100644 studio/backend/core/_torchao_stub.py

diff --git a/.github/workflows/lint-ci.yml b/.github/workflows/lint-ci.yml
index 00e6e357e2..8cb3535075 100644
--- a/.github/workflows/lint-ci.yml
+++ b/.github/workflows/lint-ci.yml
@@ -79,6 +79,56 @@ jobs:
         run: |
           ruff check unsloth unsloth_cli studio tests cli.py unsloth-cli.py
 
+      - name: Import-hoist verifier self-test
+        # scripts/verify_import_hoist.py is a scope-aware (LEGB) AST
+        # resolver that gates import-hoisting / alias-rename refactors
+        # against two bugs ruff and pyflakes both miss:
+        #   1. dangling alias  -- `from a import b as _b` hoisted to
+        #      `from a import b` but a leftover `_b` reference now
+        #      resolves to nothing (or to some other module-level `_b`).
+        #   2. rename clash    -- `_b -> b` silently re-points at a
+        #      different object already named `b` in that scope.
+        # This step runs the tool's 8 negative-control cases so a
+        # regression in the verifier itself fails before we trust it on
+        # a diff. Hermetic, stdlib-only, sub-second. Hard gate.
+        run: |
+          python scripts/verify_import_hoist.py --self-test
+
+      - name: Import-hoist / alias-rename safety (changed Python files)
+        # Runs the verifier in compare mode on every in-place-modified
+        # .py in the PR: parses each file BEFORE (base branch) and AFTER
+        # (this diff), resolves every name load, and fails on a BLOCKER
+        # (dangling alias / rename clash / re-pointed import). INFO
+        # findings (a helper relocated to another file) do not fail.
+        #
+        # --diff-filter=M (in-place edits only) is deliberate: that is
+        # exactly where a hoist refactor lives, and it skips brand-new
+        # files whose re-export imports would otherwise look "unused".
+        #
+        # actions/checkout uses fetch-depth: 1, so the base branch is not
+        # present locally. Fetch the single base commit with an explicit
+        # refspec so origin/<base> is reliably created (a bare
+        # `git fetch origin <ref>` only updates FETCH_HEAD in some
+        # configs). Two-dot diff avoids needing a merge-base on a shallow
+        # clone.
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch --no-tags --depth=1 origin \
+            "${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"
+          mapfile -t CHANGED < <(
+            git diff --name-only --diff-filter=M \
+              "origin/${{ github.base_ref }}" HEAD -- '*.py' \
+              | grep -vE '(^|/)(unsloth_compiled_cache|node_modules|build|dist)/' || true
+          )
+          if [ "${#CHANGED[@]}" -eq 0 ]; then
+            echo "no in-place-modified Python files to check"
+            exit 0
+          fi
+          printf 'checking %d file(s):\n' "${#CHANGED[@]}"
+          printf '  %s\n' "${CHANGED[@]}"
+          python scripts/verify_import_hoist.py \
+            --before "origin/${{ github.base_ref }}" --after HEAD "${CHANGED[@]}"
+
       - name: No leftover debugger / pdb / breakpoint calls
         # Catches the "I'll just stick a breakpoint() here" mistake
         # before it ships. AST-based so commented-out debugger
diff --git a/scripts/verify_import_hoist.py b/scripts/verify_import_hoist.py
new file mode 100644
index 0000000000..606488cc7f
--- /dev/null
+++ b/scripts/verify_import_hoist.py
@@ -0,0 +1,854 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+"""Deterministic, scope-aware verifier for import-hoisting / alias-rename refactors.
+
+The risk when moving `from a import b as _b` (or `import b as _b`) to module top
+and normalizing `_b` -> `b` is twofold:
+
+  1. DANGLING ALIAS  - a `_b` reference is left un-normalized; it now resolves to
+     nothing (NameError) or, worse, to some *other* module-level `_b`.
+  2. RENAME CLASH    - `_b` was an alias on purpose because `b` already meant
+     something else in that scope; normalizing `_b` -> `b` silently re-points the
+     reference at the wrong object (no NameError, no pyflakes warning).
+
+This tool parses BEFORE (a git ref, default origin/main) and AFTER (default HEAD)
+for each file, builds a real LEGB scope model (functions, classes, lambdas,
+comprehensions, global/nonlocal, args, walrus, star-imports), and resolves every
+Name load to its binding. It then compares, PER SCOPE:
+
+  * UNRESOLVED-NEW   : loads that resolve to nothing in AFTER but did in BEFORE
+                       (or are newly present) -> catches dangling aliases.
+  * TARGET-MISSING   : an import *target* (e.g. module `glob`, or
+                       `importlib.metadata.version`) that a function resolved to
+                       in BEFORE but no longer resolves to in AFTER -> catches a
+                       function that lost access to a module it still uses.
+                       Robust to alias renames because it compares the *target*,
+                       not the local name.
+  * TARGET-CHANGED   : a load whose resolved import target differs BEFORE vs
+                       AFTER -> catches a rename that re-points to a different
+                       module (the clash case).
+  * AMBIGUOUS-BIND   : a name bound by BOTH an import and a non-import in the same
+                       scope in AFTER (and not in BEFORE) -> the "alias was on
+                       purpose / now collides" smell.
+  * MODULE-DUP-IMPORT: a module-level name imported and also defined/assigned at
+                       module level (introduced by the change).
+  * NEW-UNUSED-IMPORT: a module-level import added in AFTER that nothing resolves
+                       to (informational; re-exports are a known false positive).
+
+Usage:
+  verify_import_hoist.py [--before REF] [--after REF] <file>...   # compare
+  verify_import_hoist.py --self-test                              # prove it catches bugs
+Exit code 1 if any non-informational finding.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import builtins
+import re as _re_mod
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+_BUILTINS = set(dir(builtins)) | {
+    "__file__",
+    "__name__",
+    "__doc__",
+    "__package__",
+    "__spec__",
+    "__loader__",
+    "__builtins__",
+    "__class__",
+    "__annotations__",
+    "__dict__",
+    "__qualname__",
+    "__module__",
+    "__path__",
+    "__debug__",
+    "__import__",
+    "NotImplemented",
+    "Ellipsis",
+    "copyright",
+    "credits",
+    "license",
+    "help",
+    "exit",
+    "quit",
+    "__build_class__",
+    "__cached__",
+    "reveal_type",
+    "reveal_locals",
+}
+
+
+# ---------------------------------------------------------------- scope model
+
+
+@dataclass
+class Binding:
+    kind: str  # 'import' | 'importfrom' | 'def' | 'class' | 'other'
+    target: str | None = None  # canonical import target id, else None
+
+
+@dataclass
+class Scope:
+    kind: str  # 'module' | 'function' | 'class' | 'lambda' | 'comp'
+    qualname: str
+    parent: "Scope | None"
+    bindings: dict[str, list[Binding]] = field(default_factory = dict)
+    globals: set[str] = field(default_factory = set)
+    nonlocals: set[str] = field(default_factory = set)
+    star_import: bool = False
+
+    def add(self, name: str, b: Binding) -> None:
+        self.bindings.setdefault(name, []).append(b)
+
+
+def _import_target(node: ast.AST, alias: ast.alias) -> tuple[str, str]:
+    """Return (bound_name, canonical_target_id) for one import alias."""
+    if isinstance(node, ast.Import):
+        bound = alias.asname or alias.name.split(".")[0]
+        return bound, f"import:{alias.name}"
+    # ImportFrom
+    bound = alias.asname or alias.name
+    mod = ("." * (node.level or 0)) + (node.module or "")
+    return bound, f"from:{mod}:{alias.name}"
+
+
+class _Builder(ast.NodeVisitor):
+    """Builds the scope tree + bindings, and records every (scope, Name-load)."""
+
+    def __init__(self):
+        self.module = Scope("module", "<module>", None)
+        self.uses: list[tuple[Scope, str, int]] = []  # (scope, name, lineno) hard loads
+        self.soft_uses: list[
+            tuple[Scope, str, int]
+        ] = []  # annotations: count as "used"
+        #                                                     but never as "unresolved"
+        #                                                     (forward refs / string annos)
+
+    def _visit_annotation(self, node, scope: Scope) -> None:
+        """Annotation context: with `from __future__ import annotations` these are
+        never evaluated (strings), and even otherwise they routinely contain forward
+        references. Record contained names as SOFT uses so an import used only in an
+        annotation still counts as used, but a forward-ref name is never 'unresolved'."""
+        if node is None:
+            return
+        for n in ast.walk(node):
+            if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load):
+                self.soft_uses.append((scope, n.id, n.lineno))
+
+    # -- binding helpers --
+    def _bind_targets(self, scope: Scope, target: ast.AST) -> None:
+        for n in ast.walk(target):
+            if isinstance(n, ast.Name) and isinstance(n.ctx, (ast.Store, ast.Del)):
+                self._bind_name(scope, n.id, Binding("other"))
+            elif isinstance(n, ast.Starred):
+                pass
+
+    def _bind_name(self, scope: Scope, name: str, b: Binding) -> None:
+        if name in scope.globals:
+            self.module.add(name, b)
+        elif name in scope.nonlocals:
+            p = scope.parent
+            while p is not None and p.kind not in ("function", "lambda"):
+                p = p.parent
+            (p or self.module).add(name, b)
+        else:
+            scope.add(name, b)
+
+    # -- generic dispatch within a scope --
+    def _visit_body(self, stmts, scope: Scope) -> None:
+        for s in stmts:
+            self._visit_stmt(s, scope)
+
+    def _visit_stmt(self, node: ast.AST, scope: Scope) -> None:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            star = isinstance(node, ast.ImportFrom) and any(
+                a.name == "*" for a in node.names
+            )
+            if star:
+                scope.star_import = True
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                bound, target = _import_target(node, alias)
+                kind = "import" if isinstance(node, ast.Import) else "importfrom"
+                self._bind_name(scope, bound, Binding(kind, target))
+            return
+        if isinstance(node, ast.Global):
+            scope.globals.update(node.names)
+            return
+        if isinstance(node, ast.Nonlocal):
+            scope.nonlocals.update(node.names)
+            return
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            self._bind_name(scope, node.name, Binding("def"))
+            # decorators / defaults evaluate in the ENCLOSING scope
+            for d in node.decorator_list:
+                self._visit_expr(d, scope)
+            self._visit_arg_defaults(node.args, scope)
+            child = Scope("function", f"{scope.qualname}.{node.name}", scope)
+            self._bind_type_params(node, child)
+            self._bind_args(node.args, child)
+            # arg + return annotations: soft uses (may be strings / forward refs)
+            for a in self._all_args(node.args):
+                self._visit_annotation(a.annotation, child)
+            self._visit_annotation(getattr(node, "returns", None), child)
+            self._visit_body(node.body, child)
+            return
+        if isinstance(node, ast.ClassDef):
+            self._bind_name(scope, node.name, Binding("class"))
+            for d in node.decorator_list:
+                self._visit_expr(d, scope)
+            for b in node.bases:
+                self._visit_expr(b, scope)
+            for kw in node.keywords:
+                self._visit_expr(kw.value, scope)
+            child = Scope("class", f"{scope.qualname}.{node.name}", scope)
+            self._bind_type_params(node, child)
+            self._visit_body(node.body, child)
+            return
+        if isinstance(node, ast.Match):
+            self._visit_expr(node.subject, scope)
+            for case in node.cases:
+                self._bind_pattern(case.pattern, scope)
+                if case.guard is not None:
+                    self._visit_expr(case.guard, scope)
+                self._visit_body(case.body, scope)
+            return
+        if isinstance(node, getattr(ast, "TryStar", ())):  # py3.11 except*
+            self._visit_body(node.body, scope)
+            for h in node.handlers:
+                if h.type is not None:
+                    self._visit_expr(h.type, scope)
+                if h.name:
+                    self._bind_name(scope, h.name, Binding("other"))
+                self._visit_body(h.body, scope)
+            self._visit_body(node.orelse, scope)
+            self._visit_body(node.finalbody, scope)
+            return
+        if isinstance(node, getattr(ast, "TypeAlias", ())):  # py3.12 `type X = ...`
+            if isinstance(node.name, ast.Name):
+                self._bind_name(scope, node.name.id, Binding("other"))
+            self._visit_annotation(node.value, scope)
+            return
+        if isinstance(node, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            val = node.value
+            if val is not None:
+                self._visit_expr(val, scope)
+            if isinstance(node, ast.AnnAssign) and node.annotation is not None:
+                self._visit_annotation(node.annotation, scope)
+            for t in targets:
+                self._bind_targets(scope, t)
+                # AugAssign target is also a load
+                if isinstance(node, ast.AugAssign):
+                    self._record_loads(t, scope)
+            return
+        if isinstance(node, (ast.For, ast.AsyncFor)):
+            self._visit_expr(node.iter, scope)
+            self._bind_targets(scope, node.target)
+            self._visit_body(node.body, scope)
+            self._visit_body(node.orelse, scope)
+            return
+        if isinstance(node, (ast.With, ast.AsyncWith)):
+            for item in node.items:
+                self._visit_expr(item.context_expr, scope)
+                if item.optional_vars is not None:
+                    self._bind_targets(scope, item.optional_vars)
+            self._visit_body(node.body, scope)
+            return
+        if isinstance(node, ast.Try):
+            self._visit_body(node.body, scope)
+            for h in node.handlers:
+                if h.type is not None:
+                    self._visit_expr(h.type, scope)
+                if h.name:
+                    self._bind_name(scope, h.name, Binding("other"))
+                self._visit_body(h.body, scope)
+            self._visit_body(node.orelse, scope)
+            self._visit_body(node.finalbody, scope)
+            return
+        # generic statement: visit all child expressions/stmts in same scope
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.stmt):
+                self._visit_stmt(child, scope)
+            else:
+                self._visit_expr(child, scope)
+
+    # -- expressions --
+    def _visit_arg_defaults(self, args: ast.arguments, scope: Scope) -> None:
+        for d in list(args.defaults) + [d for d in args.kw_defaults if d is not None]:
+            self._visit_expr(d, scope)
+
+    def _all_args(self, args: ast.arguments) -> list[ast.arg]:
+        out = list(args.posonlyargs) + list(args.args) + list(args.kwonlyargs)
+        if args.vararg:
+            out.append(args.vararg)
+        if args.kwarg:
+            out.append(args.kwarg)
+        return out
+
+    def _bind_args(self, args: ast.arguments, scope: Scope) -> None:
+        for a in self._all_args(args):
+            scope.add(a.arg, Binding("other"))
+
+    def _bind_type_params(self, node, scope: Scope) -> None:
+        for tp in getattr(node, "type_params", []) or []:
+            name = getattr(tp, "name", None)
+            if isinstance(name, str):
+                scope.add(name, Binding("other"))
+            self._visit_annotation(getattr(tp, "bound", None), scope)
+            self._visit_annotation(getattr(tp, "default_value", None), scope)
+
+    def _bind_pattern(self, pat, scope: Scope) -> None:
+        if pat is None:
+            return
+        if isinstance(pat, ast.MatchValue):
+            self._visit_expr(pat.value, scope)
+        elif isinstance(pat, ast.MatchSingleton):
+            pass
+        elif isinstance(pat, ast.MatchSequence):
+            for p in pat.patterns:
+                self._bind_pattern(p, scope)
+        elif isinstance(pat, ast.MatchStar):
+            if pat.name:
+                self._bind_name(scope, pat.name, Binding("other"))
+        elif isinstance(pat, ast.MatchMapping):
+            for k in pat.keys:
+                self._visit_expr(k, scope)
+            for p in pat.patterns:
+                self._bind_pattern(p, scope)
+            if pat.rest:
+                self._bind_name(scope, pat.rest, Binding("other"))
+        elif isinstance(pat, ast.MatchClass):
+            self._visit_expr(pat.cls, scope)
+            for p in pat.patterns:
+                self._bind_pattern(p, scope)
+            for p in pat.kwd_patterns:
+                self._bind_pattern(p, scope)
+        elif isinstance(pat, ast.MatchAs):
+            self._bind_pattern(pat.pattern, scope)
+            if pat.name:
+                self._bind_name(scope, pat.name, Binding("other"))
+        elif isinstance(pat, ast.MatchOr):
+            for p in pat.patterns:
+                self._bind_pattern(p, scope)
+
+    def _record_loads(self, node: ast.AST, scope: Scope) -> None:
+        for n in ast.walk(node):
+            if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load):
+                self.uses.append((scope, n.id, n.lineno))
+
+    def _visit_expr(self, node: ast.AST, scope: Scope) -> None:
+        if isinstance(node, ast.Name):
+            if isinstance(node.ctx, ast.Load):
+                self.uses.append((scope, node.id, node.lineno))
+            elif isinstance(node.ctx, (ast.Store, ast.Del)):
+                self._bind_name(scope, node.id, Binding("other"))
+            return
+        if isinstance(node, ast.Lambda):
+            self._visit_arg_defaults(node.args, scope)
+            child = Scope("lambda", f"{scope.qualname}.<lambda>", scope)
+            self._bind_args(node.args, child)
+            self._visit_expr(node.body, child)
+            return
+        if isinstance(
+            node, (ast.ListComp, ast.SetComp, ast.GeneratorExp, ast.DictComp)
+        ):
+            child = Scope("comp", f"{scope.qualname}.<comp>", scope)
+            for i, gen in enumerate(node.generators):
+                # first iterable is evaluated in the enclosing scope
+                self._visit_expr(gen.iter, scope if i == 0 else child)
+                self._bind_targets(child, gen.target)
+                for cond in gen.ifs:
+                    self._visit_expr(cond, child)
+            if isinstance(node, ast.DictComp):
+                self._visit_expr(node.key, child)
+                self._visit_expr(node.value, child)
+            else:
+                self._visit_expr(node.elt, child)
+            return
+        if isinstance(node, ast.NamedExpr):  # walrus binds in enclosing scope
+            self._visit_expr(node.value, scope)
+            if isinstance(node.target, ast.Name):
+                self._bind_name(scope, node.target.id, Binding("other"))
+            return
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.stmt):
+                self._visit_stmt(child, scope)
+            else:
+                self._visit_expr(child, scope)
+
+    def run(self, tree: ast.Module) -> None:
+        self._visit_body(tree.body, self.module)
+
+
+# ---------------------------------------------------------------- resolution
+
+
+def _any_star(scope: Scope) -> bool:
+    c = scope
+    while c is not None:
+        if c.star_import:
+            return True
+        c = c.parent
+    return False
+
+
+def _resolve(scope: Scope, name: str):
+    """LEGB resolution. Returns (status, bindings) where status in
+    {'local','import','other','builtin','star','unresolved'}."""
+    # global / nonlocal redirection
+    start = scope
+    if name in scope.globals:
+        chain = [_module_of(scope)]
+    elif name in scope.nonlocals:
+        chain = _enclosing_functions(scope)
+    else:
+        chain = _legb_chain(scope)
+    for i, sc in enumerate(chain):
+        if sc is None:
+            continue
+        if name in sc.bindings:
+            binds = sc.bindings[name]
+            if any(b.kind in ("import", "importfrom") for b in binds):
+                return "import", binds
+            return "other", binds
+    if name in _BUILTINS:
+        return "builtin", []
+    if _any_star(start):
+        return "star", []
+    return "unresolved", []
+
+
+def _module_of(scope: Scope) -> Scope:
+    while scope.parent is not None:
+        scope = scope.parent
+    return scope
+
+
+def _enclosing_functions(scope: Scope) -> list[Scope]:
+    out = []
+    p = scope.parent
+    while p is not None:
+        if p.kind in ("function", "lambda"):
+            out.append(p)
+        p = p.parent
+    out.append(_module_of(scope))
+    return out
+
+
+def _legb_chain(scope: Scope) -> list[Scope]:
+    """Immediate scope, then enclosing scopes skipping class scopes, then module."""
+    chain = [scope]
+    p = scope.parent
+    while p is not None:
+        if (
+            p.kind != "class" or p.parent is None
+        ):  # module-level class never happens; keep module
+            if p.kind != "class":
+                chain.append(p)
+        p = p.parent
+    return chain
+
+
+# ---------------------------------------------------------------- analysis
+
+
+def _analyze(src: str):
+    tree = ast.parse(src)
+    b = _Builder()
+    b.run(tree)
+    # Per-scope: unresolved load names, and import targets it resolves to.
+    unresolved: dict[str, set[str]] = {}
+    targets_by_scope: dict[str, set[str]] = {}
+    target_by_use: dict[tuple[str, str], set[str]] = {}
+    for scope, name, _ln in b.uses:
+        status, binds = _resolve(scope, name)
+        if status == "unresolved":
+            unresolved.setdefault(scope.qualname, set()).add(name)
+        elif status == "import":
+            tids = {bd.target for bd in binds if bd.target}
+            targets_by_scope.setdefault(scope.qualname, set()).update(tids)
+            target_by_use.setdefault((scope.qualname, name), set()).update(tids)
+    # soft uses (annotations): only contribute to "used", never to "unresolved"
+    for scope, name, _ln in b.soft_uses:
+        status, binds = _resolve(scope, name)
+        if status == "import":
+            tids = {bd.target for bd in binds if bd.target}
+            targets_by_scope.setdefault(scope.qualname, set()).update(tids)
+    # module-level binding info for clash checks
+    module = b.module
+    module_imports = {
+        n: bs
+        for n, bs in module.bindings.items()
+        if any(x.kind in ("import", "importfrom") for x in bs)
+    }
+    module_dup = {
+        n
+        for n, bs in module.bindings.items()
+        if any(x.kind in ("import", "importfrom") for x in bs)
+        and any(x.kind not in ("import", "importfrom") for x in bs)
+    }
+    # ambiguous: any scope where a name is bound by import AND non-import
+    ambiguous: dict[str, set[str]] = {}
+
+    def walk_scopes(scope: Scope):
+        for n, bs in scope.bindings.items():
+            if any(x.kind in ("import", "importfrom") for x in bs) and any(
+                x.kind not in ("import", "importfrom") for x in bs
+            ):
+                ambiguous.setdefault(scope.qualname, set()).add(n)
+        # scope tree isn't stored; rebuild via uses is hard. We approximate with module only.
+
+    walk_scopes(module)
+    return {
+        "unresolved": unresolved,
+        "targets_by_scope": targets_by_scope,
+        "target_by_use": target_by_use,
+        "module_import_targets": {
+            n: {x.target for x in bs if x.target} for n, bs in module_imports.items()
+        },
+        "module_dup": module_dup,
+        "ambiguous": ambiguous,
+    }
+
+
+def _git_show(ref: str, path: str) -> str | None:
+    try:
+        return subprocess.run(
+            ["git", "show", f"{ref}:{path}"], capture_output = True, text = True, check = True
+        ).stdout
+    except subprocess.CalledProcessError:
+        return None
+
+
+def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]:
+    """Return list of (severity, message). severity in BLOCKER/WARN/INFO.
+
+    Blocker signals (precise, no relocation false-positives):
+      UNRESOLVED-NEW    - a load became undefined (dangling alias / removed import).
+      NEW-UNUSED-HOIST  - a module-level import added by THIS change is resolved by
+                          NO load. A correct hoist always wires its new import to a
+                          reference; if the alias was left un-normalized OR renamed
+                          to the wrong name, the hoisted import ends up unused. This
+                          single signal catches BOTH user-described failure modes and
+                          does NOT fire for code merely relocated to another file
+                          (that removes the import, it doesn't add an unused one).
+      TARGET-CHANGED    - the same (scope, name) load resolves to a different import
+                          target before vs after (a same-name re-point).
+    """
+    a = _analyze(before_src)
+    b = _analyze(after_src)
+    findings: list[tuple[str, str]] = []
+
+    def used_targets(analysis) -> set[str]:
+        out: set[str] = set()
+        for tids in analysis["targets_by_scope"].values():
+            out |= tids
+        return out
+
+    before_used = used_targets(a)
+    after_used = used_targets(b)
+    before_module_targets: set[str] = set()
+    for tids in a["module_import_targets"].values():
+        before_module_targets |= tids
+    after_module_targets: set[str] = set()
+    for tids in b["module_import_targets"].values():
+        after_module_targets |= tids
+    added_module_targets = after_module_targets - before_module_targets
+
+    # 1. UNRESOLVED-NEW
+    for scope, names in b["unresolved"].items():
+        new = names - a["unresolved"].get(scope, set())
+        for n in sorted(new):
+            findings.append(
+                (
+                    "BLOCKER",
+                    f"{path}: UNRESOLVED-NEW '{n}' in scope {scope} "
+                    f"(undefined after change -> dangling alias / removed import)",
+                )
+            )
+
+    # 2. HOISTED-IMPORT-UNUSED  (the core botched-hoist / wrong-rename signal)
+    #    A module-level import in AFTER that NO load resolves to, and which was
+    #    either newly added by this change OR was actually used before. Excludes:
+    #      - relocation (the import is REMOVED, so it's not in after at all)
+    #      - stable pre-existing re-exports (unused before AND after, not newly added)
+    for n, tids in b["module_import_targets"].items():
+        if tids & after_used:
+            continue  # resolved by something -> fine
+        newly_added = bool(tids - before_module_targets)
+        was_used_before = bool(tids & before_used)
+        if newly_added or was_used_before:
+            why = (
+                "added but unused"
+                if newly_added
+                else "was used before, now unused (references re-pointed)"
+            )
+            findings.append(
+                (
+                    "BLOCKER",
+                    f"{path}: HOISTED-IMPORT-UNUSED '{n}' ({sorted(tids)}) "
+                    f"{why} -> un-normalized alias or wrong rename target?",
+                )
+            )
+
+    # 3. TARGET-CHANGED (same scope+name resolves to a different import target)
+    for key, tafter in b["target_by_use"].items():
+        tbefore = a["target_by_use"].get(key)
+        if tbefore and tbefore != tafter:
+            findings.append(
+                (
+                    "BLOCKER",
+                    f"{path}: TARGET-CHANGED name '{key[1]}' in {key[0]} "
+                    f"{sorted(tbefore)} -> {sorted(tafter)} (rename re-points module)",
+                )
+            )
+
+    # 4. MODULE-DUP-IMPORT introduced
+    for n in sorted(b["module_dup"] - a["module_dup"]):
+        findings.append(
+            (
+                "WARN",
+                f"{path}: MODULE-DUP-IMPORT '{n}' bound by import AND non-import "
+                f"at module level (possible clash)",
+            )
+        )
+
+    # 5. AMBIGUOUS-BIND introduced (module scope)
+    for scope, names in b["ambiguous"].items():
+        new = names - a["ambiguous"].get(scope, set())
+        for n in sorted(new):
+            findings.append(
+                ("WARN", f"{path}: AMBIGUOUS-BIND '{n}' import+non-import in {scope}")
+            )
+
+    # 6. TARGET-MISSING (informational): a scope stopped resolving to an import
+    #    target. Real bugs are already covered above; remaining cases are code
+    #    relocated to another file (e.g. a moved helper). Shown for transparency.
+    for scope, tbefore in a["targets_by_scope"].items():
+        tafter = b["targets_by_scope"].get(scope, set())
+        for t in sorted(tbefore - tafter):
+            relocated = (
+                ""
+                if t in added_module_targets
+                else "  [target not re-added here -> likely relocated/deleted]"
+            )
+            findings.append(
+                ("INFO", f"{path}: TARGET-MISSING {t} in scope {scope}{relocated}")
+            )
+    return findings
+
+
+# ---------------------------------------------------------------- self-test
+
+_SELF_TESTS = {
+    "dangling_alias": (
+        # before: inline aliased import, used as _b
+        "import os\n"
+        "def f():\n"
+        "    import glob as _b\n"
+        "    return _b.glob('*')\n",
+        # after: hoisted to canonical, but reference NOT normalized -> _b dangles
+        "import os\n" "import glob\n" "def f():\n" "    return _b.glob('*')\n",
+        "BLOCKER",
+    ),
+    "rename_clash": (
+        # before: _b is a deliberate alias; `b` already means something else
+        "import re as _b\n" "b = 123\n" "def f():\n" "    return _b.compile('x'), b\n",
+        # after: someone normalized _b -> b ; now f().b is the int, re is lost
+        "import re\n" "b = 123\n" "def f():\n" "    return b.compile('x'), b\n",
+        "BLOCKER",  # TARGET-MISSING from:.. or import:re in f
+    ),
+    "clean_rename": (
+        "def f():\n" "    import glob as _g\n" "    return _g.glob('*')\n",
+        "import glob\n" "def f():\n" "    return glob.glob('*')\n",
+        None,  # expect NO blocker
+    ),
+    "clean_dedup_redundant": (
+        "import sys\n" "def f():\n" "    import sys\n" "    return sys.argv\n",
+        "import sys\n" "def f():\n" "    return sys.argv\n",
+        None,
+    ),
+    "from_import_dangling": (
+        # from-import alias left un-normalized
+        "def f():\n"
+        "    from importlib.metadata import version as _v\n"
+        "    return _v('x')\n",
+        "from importlib.metadata import version\n" "def f():\n" "    return _v('x')\n",
+        "BLOCKER",
+    ),
+    "local_var_clash": (
+        # _b renamed to b, but b is a LOCAL variable in f -> import silently unused
+        "def f(b):\n" "    import re as _b\n" "    return _b.compile(b)\n",
+        "import re\n"
+        "def f(b):\n"
+        "    return b.compile(b)\n",  # 'b' is the param, not the module
+        "BLOCKER",
+    ),
+    "substring_safe": (
+        # correct _copy->copy rename while a config_copy var exists: NO false positive
+        "def f(config):\n"
+        "    import copy as _copy\n"
+        "    config_copy = _copy.deepcopy(config)\n"
+        "    return config_copy\n",
+        "import copy\n"
+        "def f(config):\n"
+        "    config_copy = copy.deepcopy(config)\n"
+        "    return config_copy\n",
+        None,
+    ),
+    "attr_access_not_a_use": (
+        # x._b is attribute access, not a use of name _b; removing import _b is fine
+        "import os\n"
+        "def f(x):\n"
+        "    import sys as _b\n"
+        "    return x._b + _b.argv[0]\n",
+        "import os\n" "import sys\n" "def f(x):\n" "    return x._b + sys.argv[0]\n",
+        None,
+    ),
+}
+
+
+def _self_test() -> int:
+    ok = True
+    for name, (before, after, expect) in _SELF_TESTS.items():
+        findings = compare(before, after, f"<{name}>")
+        blockers = [m for sev, m in findings if sev == "BLOCKER"]
+        got = "BLOCKER" if blockers else None
+        passed = got == expect
+        ok = ok and passed
+        print(f"[{'PASS' if passed else 'FAIL'}] {name}: expect={expect} got={got}")
+        for sev, m in findings:
+            print(f"        ({sev}) {m}")
+    print("\nSELF-TEST:", "ALL PASS" if ok else "FAILURES")
+    return 0 if ok else 1
+
+
+def _pyflakes_undefined(path: str) -> set[str] | None:
+    """Return the set of names pyflakes reports as 'undefined name' for `path`,
+    or None if pyflakes failed to run/parse the file."""
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-m", "pyflakes", path], capture_output = True, text = True
+        )
+    except Exception:
+        return None
+    if "syntax error" in (proc.stdout + proc.stderr).lower():
+        return None
+    names = set()
+    for line in proc.stdout.splitlines():
+        m = _re_mod.search(r"undefined name '([^']+)'", line)
+        if m:
+            names.add(m.group(1))
+    return names
+
+
+def audit_files(paths: list[str]) -> int:
+    """Single-version robustness audit. For every file: confirm the analyzer does
+    not crash, then cross-check its 'unresolved' names against pyflakes. Any name
+    the resolver flags that pyflakes does NOT call undefined is a tool FALSE
+    POSITIVE (a resolver gap to fix)."""
+    n_files = n_err = n_fp = n_syntax = 0
+    fp_detail: dict[str, set[str]] = {}
+    err_detail: dict[str, str] = {}
+    for path in paths:
+        n_files += 1
+        try:
+            src = open(path, encoding = "utf-8").read()
+        except Exception as e:  # unreadable
+            n_err += 1
+            err_detail[path] = f"read: {e}"
+            continue
+        try:
+            res = _analyze(src)
+        except SyntaxError:
+            n_syntax += 1
+            continue
+        except Exception as e:  # analyzer crash -> robustness bug
+            n_err += 1
+            err_detail[path] = f"{type(e).__name__}: {e}"
+            continue
+        tool_unresolved = set()
+        for names in res["unresolved"].values():
+            tool_unresolved |= names
+        if not tool_unresolved:
+            continue
+        pf = _pyflakes_undefined(path)
+        if pf is None:
+            continue  # pyflakes couldn't adjudicate; skip cross-check
+        false_pos = tool_unresolved - pf
+        if false_pos:
+            n_fp += 1
+            fp_detail[path] = false_pos
+    print(f"audited files      : {n_files}")
+    print(f"syntax-skipped     : {n_syntax}")
+    print(f"analyzer errors    : {n_err}")
+    for p, e in sorted(err_detail.items()):
+        print(f"    ERROR {p}: {e}")
+    print(f"false-positive files: {n_fp}  (resolver flagged a name pyflakes accepts)")
+    for p, names in sorted(fp_detail.items()):
+        print(f"    FP {p}: {sorted(names)}")
+    ok = n_err == 0 and n_fp == 0
+    print(
+        "\nAUDIT:",
+        "ROBUST (no crashes, no false positives vs pyflakes)"
+        if ok
+        else "NEEDS WORK (see above)",
+    )
+    return 0 if ok else 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--before", default = "origin/main")
+    ap.add_argument("--after", default = "HEAD")
+    ap.add_argument("--self-test", action = "store_true")
+    ap.add_argument(
+        "--audit",
+        action = "store_true",
+        help = "single-version robustness audit on filesystem paths",
+    )
+    ap.add_argument("files", nargs = "*")
+    args = ap.parse_args()
+
+    if args.self_test:
+        return _self_test()
+    if args.audit:
+        return audit_files(args.files)
+
+    any_blocker = False
+    for path in args.files:
+        before = _git_show(args.before, path)
+        after = _git_show(args.after, path)
+        if after is None:
+            print(f"SKIP {path}: not found at {args.after}")
+            continue
+        if before is None:
+            before = ""  # new file
+        findings = compare(before, after, path)
+        blockers = [f for f in findings if f[0] == "BLOCKER"]
+        warns = [f for f in findings if f[0] == "WARN"]
+        infos = [f for f in findings if f[0] == "INFO"]
+        status = (
+            "CLEAN"
+            if not blockers and not warns
+            else ("BLOCKERS" if blockers else "WARNINGS")
+        )
+        print(f"\n=== {path}: {status} ===")
+        for sev, m in blockers + warns + infos:
+            print(f"  [{sev}] {m}")
+        any_blocker = any_blocker or bool(blockers)
+    print(
+        "\nOVERALL:", "FAIL (blockers found)" if any_blocker else "PASS (no blockers)"
+    )
+    return 1 if any_blocker else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/studio/backend/core/_torchao_stub.py b/studio/backend/core/_torchao_stub.py
new file mode 100644
index 0000000000..5650a60ee2
--- /dev/null
+++ b/studio/backend/core/_torchao_stub.py
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared torchao Windows-ROCm import stub.
+
+torchao (pulled in by transformers.quantizers) imports
+torch.distributed._functional_collectives at module level, which imports
+distributed_c10d.py unconditionally — that file crashes on Windows ROCm because
+torch._C._distributed_c10d (the RCCL backend) is absent.
+torch/distributed/__init__.py itself is guarded by `if is_available()` so
+`import torch.distributed` alone is safe; the crash only comes via torchao's
+import chain.  Stubbing torchao short-circuits it entirely.
+_StubSubpackageFinder handles any depth of torchao.xxx.yyy imports.
+
+This logic used to be duplicated inline inside run_export_process() and
+run_training_process(); it now lives here so both worker subprocesses call the
+single `install_torchao_windows_rocm_stub()` entrypoint before importing
+transformers / unsloth_zoo.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+import importlib.abc
+import importlib.machinery
+
+_STUB_SENTINEL = object()
+
+
+# Metaclass for stub types so that isinstance(x, StubClass) returns False
+# instead of raising TypeError ("arg 2 must be a type").
+# peft/tuners/lora/torchao.py does:
+#   from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
+#   isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))
+# If those names resolve to stub modules rather than types, isinstance() raises.
+class _StubTypeMeta(type):
+    def __instancecheck__(cls, instance):
+        return False
+
+    def __subclasscheck__(cls, subclass):
+        return False
+
+    def __getattr__(cls, attr):
+        if attr.startswith("__"):
+            raise AttributeError(attr)
+        child = _StubTypeMeta(attr, (), {})
+        setattr(cls, attr, child)
+        return child
+
+    def __call__(cls, *args, **kwargs):
+        return None
+
+
+def _make_stub_type(name):
+    """Stub class: accepted by isinstance() (always False), supports attr access."""
+    return _StubTypeMeta(name, (), {})
+
+
+def _make_mod_stub(mod_name):
+    m = types.ModuleType(mod_name)
+    m.__path__ = []
+    m.__package__ = mod_name
+    m._unsloth_stub = _STUB_SENTINEL
+    m.__spec__ = importlib.machinery.ModuleSpec(mod_name, loader = None, is_package = True)
+
+    def _ga(attr, _m = m, _n = mod_name):
+        if attr.startswith("__"):
+            raise AttributeError(attr)
+        # Return a stub CLASS (not a module) so that isinstance(x, attr)
+        # works and returns False instead of raising TypeError.
+        child = _make_stub_type(f"{_n}.{attr}")
+        setattr(_m, attr, child)
+        return child
+
+    m.__getattr__ = _ga
+    return m
+
+
+class _StubSubpackageLoader(importlib.abc.Loader):
+    def __init__(self, mod_name):
+        self._mod_name = mod_name
+
+    def create_module(self, spec):
+        return _make_mod_stub(self._mod_name)
+
+    def exec_module(self, module):
+        pass
+
+
+class _StubSubpackageFinder(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path, target = None):
+        if "." not in fullname:
+            return None
+        parent = sys.modules.get(fullname.rsplit(".", 1)[0])
+        if parent is None:
+            return None
+        if getattr(parent, "_unsloth_stub", None) is not _STUB_SENTINEL:
+            return None
+        return importlib.machinery.ModuleSpec(
+            fullname, _StubSubpackageLoader(fullname), is_package = True
+        )
+
+
+def install_torchao_windows_rocm_stub() -> None:
+    """Pre-stub torchao on Windows ROCm so transformers/peft imports don't crash.
+
+    No-op on every other platform (Windows CUDA included — there torchao is real
+    and shadowing it would break torchao-based quantization paths). Must run
+    before any import of transformers / unsloth_zoo. Safe to call once per worker
+    process.
+    """
+    # Gate on the active torch runtime, not env-var presence -- HIP_PATH /
+    # ROCM_PATH stay set after a user installs the HIP SDK and reverts to a
+    # CUDA torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
+    # but still encode "rocm" in torch.__version__, so accept either.
+    _is_win32_rocm = False
+    if sys.platform == "win32":
+        try:
+            import torch as _torch_probe
+
+            _is_win32_rocm = bool(
+                getattr(getattr(_torch_probe, "version", None), "hip", None)
+                or "rocm" in getattr(_torch_probe, "__version__", "").lower()
+            )
+            del _torch_probe
+        except Exception:
+            pass
+    if _is_win32_rocm:
+        # Register the finder only on Windows ROCm -- on other platforms there
+        # are no stub modules seeded, so appending is a pure accumulation.
+        sys.meta_path.append(_StubSubpackageFinder())
+        # Seed torchao top-level + key submodules; the finder handles the rest.
+        for _tao_name in (
+            "torchao",
+            "torchao.quantization",
+            "torchao.dtypes",
+            "torchao.float8",
+            "torchao.utils",
+        ):
+            if _tao_name not in sys.modules:
+                sys.modules[_tao_name] = _make_mod_stub(_tao_name)
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index 77205bc298..defcff924b 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -440,101 +440,13 @@ def run_export_process(
             )
 
     # ── 1c. Stub torchao on Windows ROCm ──
-    # torchao (pulled in by transformers.quantizers) imports
-    # torch.distributed._functional_collectives at module level, which imports
-    # distributed_c10d.py unconditionally — that file crashes on Windows ROCm
-    # because torch._C._distributed_c10d (the RCCL backend) is absent.
-    # Stubbing torchao short-circuits the crash entirely.
+    # Shared with the training worker; see core/_torchao_stub.py for the full
+    # rationale (torchao -> torch.distributed._functional_collectives crashes on
+    # Windows ROCm because the RCCL backend is absent). No-op off Windows ROCm.
     # Must run before any import of transformers / unsloth_zoo.
-    import types as _types
-    import importlib.machinery as _ilm
-    import importlib.abc as _ilabc
+    from core._torchao_stub import install_torchao_windows_rocm_stub
 
-    _STUB_SENTINEL = object()
-
-    class _StubTypeMeta(type):
-        def __instancecheck__(cls, instance):
-            return False
-
-        def __subclasscheck__(cls, subclass):
-            return False
-
-        def __getattr__(cls, attr):
-            if attr.startswith("__"):
-                raise AttributeError(attr)
-            child = _StubTypeMeta(attr, (), {})
-            setattr(cls, attr, child)
-            return child
-
-        def __call__(cls, *args, **kwargs):
-            return None
-
-    def _make_stub_type(name):
-        return _StubTypeMeta(name, (), {})
-
-    def _make_mod_stub(mod_name):
-        m = _types.ModuleType(mod_name)
-        m.__path__ = []
-        m.__package__ = mod_name
-        m._unsloth_stub = _STUB_SENTINEL
-        m.__spec__ = _ilm.ModuleSpec(mod_name, loader = None, is_package = True)
-
-        def _ga(attr, _m = m, _n = mod_name):
-            if attr.startswith("__"):
-                raise AttributeError(attr)
-            child = _make_stub_type(f"{_n}.{attr}")
-            setattr(_m, attr, child)
-            return child
-
-        m.__getattr__ = _ga
-        return m
-
-    class _StubSubpackageLoader(_ilabc.Loader):
-        def __init__(self, mod_name):
-            self._mod_name = mod_name
-
-        def create_module(self, spec):
-            return _make_mod_stub(self._mod_name)
-
-        def exec_module(self, module):
-            pass
-
-    class _StubSubpackageFinder(_ilabc.MetaPathFinder):
-        def find_spec(self, fullname, path, target = None):
-            if "." not in fullname:
-                return None
-            parent = sys.modules.get(fullname.rsplit(".", 1)[0])
-            if parent is None:
-                return None
-            if getattr(parent, "_unsloth_stub", None) is not _STUB_SENTINEL:
-                return None
-            return _ilm.ModuleSpec(
-                fullname, _StubSubpackageLoader(fullname), is_package = True
-            )
-
-    _is_win32_rocm = False
-    if sys.platform == "win32":
-        try:
-            import torch as _torch_probe
-
-            _is_win32_rocm = bool(
-                getattr(getattr(_torch_probe, "version", None), "hip", None)
-                or "rocm" in getattr(_torch_probe, "__version__", "").lower()
-            )
-            del _torch_probe
-        except Exception:
-            pass
-    if _is_win32_rocm:
-        sys.meta_path.append(_StubSubpackageFinder())
-        for _tao_name in (
-            "torchao",
-            "torchao.quantization",
-            "torchao.dtypes",
-            "torchao.float8",
-            "torchao.utils",
-        ):
-            if _tao_name not in sys.modules:
-                sys.modules[_tao_name] = _make_mod_stub(_tao_name)
+    install_torchao_windows_rocm_stub()
 
     # ── 2. Import ML libraries (fresh in this clean process) ──
     try:
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 83c4b4f4da..4b17f495ea 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -17,6 +17,7 @@ import struct
 import structlog
 from loggers import get_logger
 import shutil
+import signal
 import socket
 import subprocess
 import sys
@@ -965,9 +966,6 @@ class LlamaCppBackend:
         7.  llama-server on PATH                     (system install)
         8.  ./bin/llama-server                       (legacy: extracted binary)
         """
-        import os
-        import sys
-
         binary_name = "llama-server.exe" if sys.platform == "win32" else "llama-server"
 
         # 1. Env var — direct path to binary
@@ -1282,8 +1280,6 @@ class LlamaCppBackend:
         Returns list of (gpu_index, free_mib) sorted by index. Empty
         list if no supported GPU is reachable.
         """
-        import os
-
         # ── NVIDIA via nvidia-smi ────────────────────────────────────
         try:
             result = subprocess.run(
@@ -3928,10 +3924,6 @@ class LlamaCppBackend:
         Falls back to pgrep + /proc/<pid>/exe on Linux when psutil is
         not installed.
         """
-        import os
-        import signal
-        import sys
-
         try:
             # -- Build the ownership allowlist --------------------------------
             # Two kinds of matches:
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index f1faaee4fb..0365b3ffd8 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -6,8 +6,10 @@ Unsloth Training Backend
 Integrates Unsloth training capabilities with the FastAPI backend
 """
 
+import gc
 import os
 import sys
+import types
 
 # Prevent tokenizer parallelism deadlocks when datasets uses multiprocessing fork
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
@@ -420,8 +422,6 @@ class UnslothTrainer:
         in sys.modules. When the next training run calls dataset.map(num_proc=N),
         forked child processes inherit this stale state and deadlock.
         """
-        import sys as _sys
-
         # Remove cloned audio repo paths from sys.path
         base_dir = os.path.dirname(os.path.abspath(__file__))
         audio_paths = [
@@ -436,15 +436,15 @@ class UnslothTrainer:
 
         removed_paths = []
         for path in audio_paths:
-            if path in _sys.path:
-                _sys.path.remove(path)
+            if path in sys.path:
+                sys.path.remove(path)
                 removed_paths.append(path)
 
         # Remove stale audio modules from sys.modules
         prefixes = ("snac", "whisper", "sparktts", "outetts")
-        removed_modules = [key for key in _sys.modules if key.startswith(prefixes)]
+        removed_modules = [key for key in sys.modules if key.startswith(prefixes)]
         for key in removed_modules:
-            del _sys.modules[key]
+            del sys.modules[key]
 
         if removed_paths or removed_modules:
             logger.info(
@@ -541,10 +541,9 @@ class UnslothTrainer:
             # clear_unsloth_compiled_cache() deletes the disk cache, but the flag
             # prevents re-compilation — leaving missing cache files. Reloading
             # restores original class definitions so Unsloth can re-compile cleanly.
-            import sys as _sys
             import importlib
 
-            for _key, _mod in list(_sys.modules.items()):
+            for _key, _mod in list(sys.modules.items()):
                 if "transformers.models." in _key and ".modeling_" in _key:
                     if hasattr(_mod, "__UNSLOTH_PATCHED__"):
                         try:
@@ -660,14 +659,22 @@ class UnslothTrainer:
                 f"Using device_map='{device_map}' ({get_visible_gpu_count()} GPU(s) visible)"
             )
 
-            # On hardware without native bfloat16 support (e.g. RDNA2 / gfx103x),
-            # passing dtype=None lets unsloth auto-detect and incorrectly choose
-            # bf16, triggering an LLVM error at the first bf16 kernel dispatch.
-            # Explicitly pass float16 as the fallback so unsloth never reaches
-            # that path. Modern NVIDIA (Ampere+) and RDNA3+ return True here so
-            # they are unaffected — dtype stays None and unsloth picks bf16 as
-            # before.
-            _auto_dtype = None if is_bfloat16_supported() else torch.float16
+            # AMD ROCm hardware without native bfloat16 (e.g. RDNA2 / gfx103x)
+            # crashes with an LLVM error at the first bf16 kernel dispatch if
+            # dtype=None lets unsloth auto-pick bf16. Force float16 there so that
+            # path is never reached. NVIDIA keeps dtype=None so unsloth's own
+            # bf16/fp16/float32 auto-detection (including FORCE_FLOAT32 models) is
+            # honored -- older NVIDIA without bf16 (T4/V100) must NOT be coerced to
+            # float16 here, which the previous unconditional branch did wrongly.
+            # Derive ROCm inline (not hardware.IS_ROCM) because that flag is unset
+            # until detect_hardware() runs, which isn't guaranteed in this subprocess.
+            _is_rocm = (
+                bool(getattr(torch.version, "hip", None))
+                or "rocm" in torch.__version__.lower()
+            )
+            _auto_dtype = (
+                torch.float16 if (_is_rocm and not is_bfloat16_supported()) else None
+            )
 
             # Branch based on model type
             if self._audio_type == "csm":
@@ -1200,7 +1207,6 @@ class UnslothTrainer:
         We patch at both instance AND class level for maximum reliability,
         and strip non-TransformersKwargs params that Unsloth/PEFT inject.
         """
-        import types
         import torch
         import torch.nn as nn
         from transformers.models.csm.modeling_csm import (
@@ -1742,7 +1748,6 @@ class UnslothTrainer:
         logger.info("Freeing SNAC codec model from GPU...\n")
         snac_model.to("cpu")
         del snac_model
-        import gc
 
         gc.collect()
         torch.cuda.empty_cache()
@@ -1766,13 +1771,10 @@ class UnslothTrainer:
         Mirrors Spark_TTS_(0_5B).ipynb: encode audio with BiCodec (semantic + global tokens),
         format as special-token text strings for SFTTrainer with dataset_text_field="text".
         """
-        import sys
         import torch
         import numpy as np
         import torchaudio.transforms as T
 
-        import subprocess
-
         device = "cuda" if torch.cuda.is_available() else "cpu"
 
         # The sparktts Python package lives in the SparkAudio/Spark-TTS GitHub repo,
@@ -1972,7 +1974,6 @@ class UnslothTrainer:
         audio_tokenizer.model.cpu()
         audio_tokenizer.feature_extractor.cpu()
         del audio_tokenizer
-        import gc
 
         gc.collect()
         torch.cuda.empty_cache()
@@ -2001,7 +2002,6 @@ class UnslothTrainer:
         OuteTTS AudioProcessor for speaker representations, PromptProcessor for
         training prompts. Outputs text strings for SFTTrainer with dataset_text_field="text".
         """
-        import sys
         import io
         import tempfile
         import torch
@@ -2185,7 +2185,6 @@ class UnslothTrainer:
         del whisper_model
         del audio_processor
         del prompt_processor
-        import gc
 
         gc.collect()
         torch.cuda.empty_cache()
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index a59def8751..a825321597 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -21,6 +21,9 @@ import shutil
 import sys
 import time
 import traceback
+import gc
+import re
+import types
 import subprocess as _sp
 from pathlib import Path
 from typing import Any, Callable
@@ -1259,7 +1262,6 @@ def _run_mlx_training(event_queue, stop_queue, config):
     Mirrors the event_queue protocol so the parent process pump works unchanged.
     """
     import time
-    import gc
     import math
     import threading
     import queue as _queue
@@ -2020,121 +2022,13 @@ def run_training_process(
             )
 
     # ── 1d. Stub torchao on Windows ROCm ──
-    # torchao (pulled in by transformers.quantizers) imports
-    # torch.distributed._functional_collectives at module level, which imports
-    # distributed_c10d.py unconditionally — that file crashes on Windows ROCm
-    # because torch._C._distributed_c10d (the RCCL backend) is absent.
-    # torch/distributed/__init__.py itself is guarded by `if is_available()`
-    # so `import torch.distributed` alone is safe; the crash only comes via
-    # torchao's import chain.  Stubbing torchao short-circuits it entirely.
-    # _StubSubpackageFinder handles any depth of torchao.xxx.yyy imports.
-    import types as _types
-    import importlib.machinery as _ilm
-    import importlib.abc as _ilabc
+    # Shared with the export worker; see core/_torchao_stub.py for the full
+    # rationale (torchao -> torch.distributed._functional_collectives crashes on
+    # Windows ROCm because the RCCL backend is absent). No-op off Windows ROCm.
+    # Must run before any import of transformers / unsloth_zoo.
+    from core._torchao_stub import install_torchao_windows_rocm_stub
 
-    _STUB_SENTINEL = object()
-
-    # Metaclass for stub types so that isinstance(x, StubClass) returns False
-    # instead of raising TypeError ("arg 2 must be a type").
-    # peft/tuners/lora/torchao.py does:
-    #   from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
-    #   isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))
-    # If those names resolve to stub modules rather than types, isinstance() raises.
-    class _StubTypeMeta(type):
-        def __instancecheck__(cls, instance):
-            return False
-
-        def __subclasscheck__(cls, subclass):
-            return False
-
-        def __getattr__(cls, attr):
-            if attr.startswith("__"):
-                raise AttributeError(attr)
-            child = _StubTypeMeta(attr, (), {})
-            setattr(cls, attr, child)
-            return child
-
-        def __call__(cls, *args, **kwargs):
-            return None
-
-    def _make_stub_type(name):
-        """Stub class: accepted by isinstance() (always False), supports attr access."""
-        return _StubTypeMeta(name, (), {})
-
-    def _make_mod_stub(mod_name):
-        m = _types.ModuleType(mod_name)
-        m.__path__ = []
-        m.__package__ = mod_name
-        m._unsloth_stub = _STUB_SENTINEL
-        m.__spec__ = _ilm.ModuleSpec(mod_name, loader = None, is_package = True)
-
-        def _ga(attr, _m = m, _n = mod_name):
-            if attr.startswith("__"):
-                raise AttributeError(attr)
-            # Return a stub CLASS (not a module) so that isinstance(x, attr)
-            # works and returns False instead of raising TypeError.
-            child = _make_stub_type(f"{_n}.{attr}")
-            setattr(_m, attr, child)
-            return child
-
-        m.__getattr__ = _ga
-        return m
-
-    class _StubSubpackageLoader(_ilabc.Loader):
-        def __init__(self, mod_name):
-            self._mod_name = mod_name
-
-        def create_module(self, spec):
-            return _make_mod_stub(self._mod_name)
-
-        def exec_module(self, module):
-            pass
-
-    class _StubSubpackageFinder(_ilabc.MetaPathFinder):
-        def find_spec(self, fullname, path, target = None):
-            if "." not in fullname:
-                return None
-            parent = sys.modules.get(fullname.rsplit(".", 1)[0])
-            if parent is None:
-                return None
-            if getattr(parent, "_unsloth_stub", None) is not _STUB_SENTINEL:
-                return None
-            return _ilm.ModuleSpec(
-                fullname, _StubSubpackageLoader(fullname), is_package = True
-            )
-
-    # Only stub torchao on Windows ROCm hosts -- on Windows CUDA (NVIDIA) torchao
-    # is real and shadowing it breaks torchao-based quantization paths.
-    # Gate on the active torch runtime, not env-var presence -- HIP_PATH /
-    # ROCM_PATH stay set after a user installs the HIP SDK and reverts to a
-    # CUDA torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
-    # but still encode "rocm" in torch.__version__, so accept either.
-    _is_win32_rocm = False
-    if sys.platform == "win32":
-        try:
-            import torch as _torch_probe
-
-            _is_win32_rocm = bool(
-                getattr(getattr(_torch_probe, "version", None), "hip", None)
-                or "rocm" in getattr(_torch_probe, "__version__", "").lower()
-            )
-            del _torch_probe
-        except Exception:
-            pass
-    if _is_win32_rocm:
-        # Register the finder only on Windows ROCm -- on other platforms there
-        # are no stub modules seeded, so appending is a pure accumulation.
-        sys.meta_path.append(_StubSubpackageFinder())
-        # Seed torchao top-level + key submodules; the finder handles the rest.
-        for _tao_name in (
-            "torchao",
-            "torchao.quantization",
-            "torchao.dtypes",
-            "torchao.float8",
-            "torchao.utils",
-        ):
-            if _tao_name not in sys.modules:
-                sys.modules[_tao_name] = _make_mod_stub(_tao_name)
+    install_torchao_windows_rocm_stub()
 
     # ── 1e. Ensure torch.distributed helper attrs are present ──
     # Single-GPU training never initialises the process group, so these helpers
@@ -2155,7 +2049,7 @@ def run_training_process(
             if not hasattr(_td, _name):
                 setattr(_td, _name, _stub)
     except Exception:
-        _td_mock = _types.ModuleType("torch.distributed")
+        _td_mock = types.ModuleType("torch.distributed")
         for _name, _stub in _td_stubs.items():
             setattr(_td_mock, _name, _stub)
         sys.modules["torch.distributed"] = _td_mock
@@ -2269,17 +2163,13 @@ def run_training_process(
             # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back
             # to that string when version.hip is missing.
             def _hip_ver_at_least(major: int, minor: int) -> bool:
-                import re as _re_ver
-
                 _hip_str = getattr(
                     getattr(_torch_for_rocm, "version", None), "hip", None
                 )
                 if not _hip_str:
                     # Try the standard "+rocmX.Y.Z" embedded version first
                     # (e.g. "2.11.0+rocm7.13.0").
-                    _ver_match = _re_ver.search(
-                        r"rocm(\d+)\.(\d+)", _build_version_for_rocm
-                    )
+                    _ver_match = re.search(r"rocm(\d+)\.(\d+)", _build_version_for_rocm)
                     if _ver_match:
                         return (
                             int(_ver_match.group(1)),
diff --git a/studio/backend/main.py b/studio/backend/main.py
index be327bc5a8..6b8ac438c0 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -866,8 +866,6 @@ def _strip_crossorigin(html_bytes: bytes) -> bytes:
     @font-face downloads to fail silently.  Stripping the attribute
     makes them regular same-origin fetches that work on any protocol.
     """
-    import re as _re
-
     html = html_bytes.decode("utf-8")
     html = _re.sub(r'\s+crossorigin(?:="[^"]*")?', "", html)
     return html.encode("utf-8")
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index ebac6a357c..180fde8f13 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -16,8 +16,16 @@ Usage:
         ...
 """
 
+import copy
+import gc
+import glob
 import os
 import platform
+import re
+import subprocess
+import sys
+import types
+from importlib.metadata import PackageNotFoundError, version as pkg_version
 import structlog
 from loggers import get_logger
 from enum import Enum
@@ -178,8 +186,6 @@ def clear_gpu_cache():
     Clear GPU memory cache for the current device.
     Safe to call on any platform — no-ops gracefully.
     """
-    import gc
-
     gc.collect()
 
     device = get_device()
@@ -361,8 +367,6 @@ def get_package_versions() -> Dict[str, Optional[str]]:
     Returns dict with keys: unsloth, torch, transformers, cuda.
     Missing packages yield None.
     """
-    from importlib.metadata import version as pkg_version, PackageNotFoundError
-
     packages = ("unsloth", "torch", "transformers")
     versions: Dict[str, Optional[str]] = {}
 
@@ -481,9 +485,6 @@ def _read_apple_gpu_stats() -> Dict[str, Any]:
     Returns dict with utilization_pct, vram_used_bytes (system-wide GPU memory).
     Returns empty dict on failure.
     """
-    import subprocess
-    import re
-
     try:
         result = subprocess.run(
             ["ioreg", "-r", "-c", "AGXAccelerator"],
@@ -510,12 +511,10 @@ def _read_apple_gpu_stats() -> Dict[str, Any]:
 
 def _rocm_linux_sysfs_gpu_busy_pct() -> Optional[float]:
     """Query AMD GPU compute utilization via Linux DRM sysfs gpu_busy_percent."""
-    import glob as _glob
-
     if platform.system() != "Linux":
         return None
     try:
-        files = _glob.glob("/sys/class/drm/card*/device/gpu_busy_percent")
+        files = glob.glob("/sys/class/drm/card*/device/gpu_busy_percent")
         if not files:
             return None
         values = [int(open(f).read().strip()) for f in files]
@@ -526,12 +525,10 @@ def _rocm_linux_sysfs_gpu_busy_pct() -> Optional[float]:
 
 def _rocm_linux_sysfs_temp_c() -> Optional[float]:
     """Query AMD GPU edge temperature via Linux DRM hwmon sysfs (temp1_input, millidegrees C)."""
-    import glob as _glob
-
     if platform.system() != "Linux":
         return None
     try:
-        files = _glob.glob("/sys/class/drm/card*/device/hwmon/hwmon*/temp1_input")
+        files = glob.glob("/sys/class/drm/card*/device/hwmon/hwmon*/temp1_input")
         if not files:
             return None
         temps = [int(open(f).read().strip()) / 1000.0 for f in files]
@@ -542,8 +539,6 @@ def _rocm_linux_sysfs_temp_c() -> Optional[float]:
 
 def _rocm_linux_sysfs_power_w() -> Optional[float]:
     """Query AMD GPU average power draw via Linux DRM hwmon sysfs (microwatts)."""
-    import glob as _glob
-
     if platform.system() != "Linux":
         return None
     try:
@@ -551,7 +546,7 @@ def _rocm_linux_sysfs_power_w() -> Optional[float]:
             "/sys/class/drm/card*/device/hwmon/hwmon*/power1_average",
             "/sys/class/drm/card*/device/hwmon/hwmon*/power1_input",
         ):
-            files = _glob.glob(pattern)
+            files = glob.glob(pattern)
             if files:
                 watts = sum(int(open(f).read().strip()) / 1_000_000.0 for f in files)
                 return round(watts, 1)
@@ -562,8 +557,6 @@ def _rocm_linux_sysfs_power_w() -> Optional[float]:
 
 def _rocm_windows_perf_counter_gpu_util_pct() -> Optional[float]:
     """Query AMD GPU compute utilization via Windows Performance Counters (3D engine nodes)."""
-    import subprocess as _sp
-
     if platform.system() != "Windows":
         return None
     try:
@@ -572,7 +565,7 @@ def _rocm_windows_perf_counter_gpu_util_pct() -> Optional[float]:
             " -ErrorAction SilentlyContinue).CounterSamples;"
             "if($s){[math]::Min(($s|Measure-Object CookedValue -Sum).Sum,100)}else{-1}"
         )
-        r = _sp.run(
+        r = subprocess.run(
             ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
             capture_output = True,
             text = True,
@@ -593,13 +586,11 @@ def _rocm_linux_sysfs_vram_gb() -> tuple[Optional[float], Optional[float]]:
     updates in real-time across all processes. No tools required.
     Returns (used_gb, total_gb) or (None, None) on failure.
     """
-    import glob as _glob
-
     if platform.system() != "Linux":
         return None, None
     try:
-        used_files = _glob.glob("/sys/class/drm/card*/device/mem_info_vram_used")
-        total_files = _glob.glob("/sys/class/drm/card*/device/mem_info_vram_total")
+        used_files = glob.glob("/sys/class/drm/card*/device/mem_info_vram_used")
+        total_files = glob.glob("/sys/class/drm/card*/device/mem_info_vram_total")
         if not used_files or not total_files:
             return None, None
         used_bytes = sum(int(open(f).read().strip()) for f in used_files)
@@ -618,8 +609,6 @@ def _rocm_windows_perf_counter_vram_gb() -> tuple[Optional[float], Optional[floa
     usage accurately. Works for any GPU vendor without amd-smi or nvidia-smi.
     Returns (used_gb, total_gb) or (None, None) on failure.
     """
-    import subprocess as _sp
-
     if platform.system() != "Windows":
         return None, None
     try:
@@ -628,7 +617,7 @@ def _rocm_windows_perf_counter_vram_gb() -> tuple[Optional[float], Optional[floa
             " -ErrorAction SilentlyContinue).CounterSamples;"
             "if($s){($s|Measure-Object CookedValue -Sum).Sum}else{-1}"
         )
-        r = _sp.run(
+        r = subprocess.run(
             ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
             capture_output = True,
             text = True,
@@ -1160,17 +1149,12 @@ def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = Non
 
 
 def _determine_attention_impl_for_gpu_estimate(config) -> str:
-    import copy as _copy
-
     # torch.distributed is incomplete on Windows ROCm — torch._C is a C
     # extension (not a package), so Python cannot import the submodule
     # torch._C._distributed_c10d that torch.distributed depends on.
     # Inject an empty stub into sys.modules BEFORE importing torch.distributed
     # so the import succeeds, then patch the missing process-group helpers.
-    import sys as _sys
-    import types as _types
-
-    if _sys.platform == "win32" and IS_ROCM:
+    if sys.platform == "win32" and IS_ROCM:
         # Dummy class for any name torch.distributed tries to import from these stubs
         class _Dummy:
             pass
@@ -1180,8 +1164,8 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
             "torch._C._distributed_autograd",
             "torch._C._distributed_rpc",
         ):
-            if _c10d_name not in _sys.modules:
-                _stub = _types.ModuleType(_c10d_name)
+            if _c10d_name not in sys.modules:
+                _stub = types.ModuleType(_c10d_name)
                 # torch.distributed imports these names from _distributed_c10d;
                 # provide no-op dummies so the import doesn't raise AttributeError.
                 for _sym in (
@@ -1200,7 +1184,7 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
                     "BuiltinCommHookType",
                 ):
                     setattr(_stub, _sym, _Dummy)
-                _sys.modules[_c10d_name] = _stub
+                sys.modules[_c10d_name] = _stub
 
     try:
         import torch.distributed as _td
@@ -1225,7 +1209,7 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
     # `sub_configs` and propagates to nested text_config / sub-configs, so a
     # shallow copy still mutates those shared inner objects on the cached
     # config returned by _load_config_for_gpu_estimate. Deepcopy isolates them.
-    config_copy = _copy.deepcopy(config)
+    config_copy = copy.deepcopy(config)
 
     model_class = None
     for auto_model in (AutoModelForCausalLM, AutoModel):
@@ -2026,8 +2010,6 @@ def safe_num_proc(desired: Optional[int] = None) -> int:
     Returns:
         A safe integer ≥ 1.
     """
-    import sys
-
     # Windows and macOS use 'spawn' for multiprocessing -- the overhead of
     # re-importing torch/transformers/unsloth per worker is typically slower
     # than single-process.
@@ -2078,8 +2060,6 @@ def dataset_map_num_proc(desired: Optional[int] = None) -> Optional[int]:
     ``datasets`` treats ``num_proc=1`` as multiprocessing (creates ``Pool(1)``).
     Only ``num_proc=None`` guarantees in-process execution.
     """
-    import sys
-
     if sys.platform in ("win32", "darwin"):
         return None
     return safe_num_proc(desired)
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 786b668e7b..5e785c934d 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -12,8 +12,10 @@ PATH to point at the venv.
 
 from __future__ import annotations
 
+import glob
 import os
 import platform
+import re
 import shutil
 import subprocess
 import sys
@@ -209,8 +211,6 @@ def _detect_rocm_version() -> tuple[int, int] | None:
     # for the rocm-core package version. Matches the chain in
     # install.sh::get_torch_index_url so `unsloth studio update` behaves
     # the same as a fresh `curl | sh` install.
-    import re as _re_pkg
-
     for cmd in (
         ["dpkg-query", "-W", "-f=${Version}\n", "rocm-core"],
         ["rpm", "-q", "--qf", "%{VERSION}\n", "rocm-core"],
@@ -232,8 +232,8 @@ def _detect_rocm_version() -> tuple[int, int] | None:
             continue
         raw = result.stdout.strip()
         # dpkg can prepend an epoch ("1:6.3.0-1"); strip it before parsing.
-        raw = _re_pkg.sub(r"^\d+:", "", raw)
-        m = _re_pkg.match(r"(\d+)[.-](\d+)", raw)
+        raw = re.sub(r"^\d+:", "", raw)
+        m = re.match(r"(\d+)[.-](\d+)", raw)
         if m:
             return int(m.group(1)), int(m.group(2))
 
@@ -274,8 +274,6 @@ def _detect_windows_gfx_arch() -> str | None:
     enumeration order) and HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES selects
     which one to install for. The first GPU is used when no env var is set.
     """
-    import re
-
     # 1. Explicit override (matches PowerShell installer's env-var path).
     _override = os.environ.get("UNSLOTH_ROCM_GFX_ARCH")
     if _override and _override.strip():
@@ -366,9 +364,7 @@ def _detect_bnb_rocm_dll_ver() -> str | None:
     bitsandbytes — uses importlib.util.find_spec so it is safe to call before
     BNB is imported.
     """
-    import glob
     import importlib.util
-    import re
 
     spec = importlib.util.find_spec("bitsandbytes")
     if spec is None or not spec.submodule_search_locations:
@@ -387,8 +383,6 @@ def _detect_bnb_rocm_dll_ver() -> str | None:
 
 def _has_rocm_gpu() -> bool:
     """Return True only if an actual AMD GPU is visible (not just ROCm tools installed)."""
-    import re
-
     for cmd, check_fn in (
         # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
         # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines like
@@ -469,7 +463,6 @@ def _detect_amd_gfx_codes() -> list[str]:
     amd-smi but no rocminfo. Returns an empty list when no probe yields
     a gfx target.
     """
-    import re
 
     def _extract(text: str) -> list[str]:
         codes = re.findall(r"gfx([1-9][0-9a-z]{2,3})", text.lower())
@@ -510,28 +503,24 @@ def _install_bnb_windows_rocm() -> bool:
     The continuous-release wheel is intentionally mismatched: the filename
     encodes version 1.33.7.preview (parsed as 1.33.7rc0 by PEP 440) while the
     wheel metadata reports 0.50.0.dev0.  uv rejects this filename/metadata
-    mismatch; set UV_SKIP_WHEEL_FILENAME_CHECK=1 to bypass that check, then
-    restore the previous value (or remove the var) when done.
+    mismatch -- and bypassing it with UV_SKIP_WHEEL_FILENAME_CHECK still leaves
+    uv mangling the bitsandbytes install. Per the AMD install guide
+    (https://unsloth.ai/docs/get-started/install/amd/amd-hackathon) the wheel
+    must be installed with plain pip, not uv, so we force pip here
+    (force_pip=True). plain pip performs no wheel filename/metadata check.
     """
     _bnb_win_url = _BNB_ROCM_PRERELEASE_URLS.get("win_amd64")
     if _bnb_win_url is None:
         return False
-    _old = os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK")
-    os.environ["UV_SKIP_WHEEL_FILENAME_CHECK"] = "1"
-    try:
-        _ok = pip_install_try(
-            "bitsandbytes (AMD Windows, pre-release main)",
-            "--force-reinstall",
-            "--no-cache-dir",
-            "--no-deps",
-            _bnb_win_url,
-            constrain = False,
-        )
-    finally:
-        if _old is None:
-            os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
-        else:
-            os.environ["UV_SKIP_WHEEL_FILENAME_CHECK"] = _old
+    _ok = pip_install_try(
+        "bitsandbytes (AMD Windows, pre-release main)",
+        "--force-reinstall",
+        "--no-cache-dir",
+        "--no-deps",
+        _bnb_win_url,
+        constrain = False,
+        force_pip = True,
+    )
     if not _ok:
         return False
     # After install: detect the actual ROCm DLL suffix shipped in the wheel and
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index e276b2151d..6c5f4171c4 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -818,11 +818,11 @@ if (-not $HasNvidiaSmi) {
         #    Ordered most-specific first; first match wins.
         elseif ($ROCmGpuLabel) {
             $nameArchTable = @(
-                @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4
+                @{ P = "9070 XT|9080";                                         A = "gfx1201" }  # RDNA 4
                 @{ P = "9070|9060";                                            A = "gfx1200" }  # RDNA 4
-                @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";  A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
-                @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" } # RDNA 3.5 iGPU (Strix Point)
-                @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                       A = "gfx1100" }  # RDNA 3 desktop
+                @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";    A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
+                @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" }  # RDNA 3.5 iGPU (Strix Point)
+                @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                        A = "gfx1100" }  # RDNA 3 desktop
                 @{ P = "RX 7600";                                              A = "gfx1102" }  # RDNA 3
                 @{ P = "780M|760M|740M|Phoenix";                               A = "gfx1103" }  # RDNA 3 iGPU (Phoenix)
             )
@@ -2037,10 +2037,10 @@ if ($HasROCm -and $CuTag -eq "cpu") {
     $amdIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl" }
     $archFamilyMap = @{
         "gfx1201" = "gfx120X-all"; "gfx1200" = "gfx120X-all"  # RDNA 4
-        "gfx1151" = "gfx1151";     "gfx1150" = "gfx1150"       # RDNA 3.5 (Strix Halo/Point)
-        "gfx1103" = "gfx110X-all"; "gfx1102" = "gfx110X-all"   # RDNA 3
+        "gfx1151" = "gfx1151";     "gfx1150" = "gfx1150"      # RDNA 3.5 (Strix Halo/Point)
+        "gfx1103" = "gfx110X-all"; "gfx1102" = "gfx110X-all"  # RDNA 3
         "gfx1101" = "gfx110X-all"; "gfx1100" = "gfx110X-all"
-        "gfx90a"  = "gfx90a";      "gfx908"  = "gfx908"        # MI200/MI100
+        "gfx90a"  = "gfx90a";      "gfx908"  = "gfx908"       # MI200/MI100
     }
     # gfx120X and Strix have a null _grouped_mm kernel on torch <2.11.0.
     # Mirrors the $torchFloorMap in install.ps1 so both installers enforce
diff --git a/studio/setup.sh b/studio/setup.sh
index 3b263a08da..89489f38b0 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -707,13 +707,13 @@ elif [ "$_setup_amd_detected" = true ]; then
     # Name-based arch inference when tools don't report gfx (mirrors setup.ps1 nameArchTable)
     elif [ -z "$_setup_gfx" ] && [ -n "$_setup_mkt" ]; then
         case "$_setup_mkt" in
-            *"9070 XT"*|*9080*)                                                     _setup_gfx="gfx1201" ;;  # RDNA 4
-            *9070*|*9060*)                                                          _setup_gfx="gfx1200" ;;  # RDNA 4
+            *"9070 XT"*|*9080*)                                                 _setup_gfx="gfx1201" ;;  # RDNA 4
+            *9070*|*9060*)                                                      _setup_gfx="gfx1200" ;;  # RDNA 4
             *"8060S"*|*"890M"*|*"Strix Halo"*|*"HX 37"*|*"HX 38"*|*"AI 9 HX"*)  _setup_gfx="gfx1151" ;;  # RDNA 3.5 iGPU
-            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)        _setup_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
-            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                  _setup_gfx="gfx1100" ;;  # RDNA 3 desktop
-            *"RX 7600"*)                                                           _setup_gfx="gfx1102" ;;  # RDNA 3
-            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                               _setup_gfx="gfx1103" ;;  # RDNA 3 iGPU
+            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)       _setup_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
+            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                _setup_gfx="gfx1100" ;;  # RDNA 3 desktop
+            *"RX 7600"*)                                                        _setup_gfx="gfx1102" ;;  # RDNA 3
+            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                             _setup_gfx="gfx1103" ;;  # RDNA 3 iGPU
         esac
         if [ -n "$_setup_gfx" ]; then
             substep "gfx arch inferred from GPU name: $_setup_gfx"
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index ecb1b9be15..ec99e9a8d9 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -1096,6 +1096,12 @@ class TestLiveRegression:
 
 # Load worker.py module
 _WORKER_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "training" / "worker.py"
+_EXPORT_WORKER_PATH = (
+    PACKAGE_ROOT / "studio" / "backend" / "core" / "export" / "worker.py"
+)
+# The torchao Windows-ROCm stub was de-duplicated out of the export/training
+# workers into a shared module; both workers now call into it.
+_TORCHAO_STUB_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "_torchao_stub.py"
 # The wheel-probe subprocess was hoisted out of worker.py into wheel_utils
 # during the wheel-resolver refactor; the probe script literal lives there.
 _WHEEL_UTILS_PATH = PACKAGE_ROOT / "studio" / "backend" / "utils" / "wheel_utils.py"
@@ -1654,53 +1660,46 @@ class TestInstallBnbWindowsRocm:
     """Verify AMD Windows BNB wheel install helper."""
 
     def test_calls_pip_install_try_with_win_amd64_url(self):
-        """Should call pip_install_try with the win_amd64 wheel URL."""
+        """Should call pip_install_try with the win_amd64 wheel URL via plain pip."""
         with patch.object(stack_mod, "pip_install_try", return_value = True) as mock_pip:
             stack_mod._install_bnb_windows_rocm()
         assert mock_pip.call_count == 1
         call_args = str(mock_pip.call_args_list[0])
         assert "bitsandbytes" in call_args
         assert "win_amd64" in call_args
+        # Must force plain pip (uv mangles the bitsandbytes wheel) -- see
+        # https://unsloth.ai/docs/get-started/install/amd/amd-hackathon
+        assert mock_pip.call_args.kwargs.get("force_pip") is True
 
-    def test_sets_uv_skip_env_var_during_install(self):
-        """UV_SKIP_WHEEL_FILENAME_CHECK must be '1' when pip_install_try runs."""
+    def test_forces_plain_pip_not_uv(self):
+        """The bnb wheel must be installed with plain pip, never uv."""
+        with patch.object(stack_mod, "pip_install_try", return_value = True) as mock_pip:
+            stack_mod._install_bnb_windows_rocm()
+        assert mock_pip.call_args.kwargs.get("force_pip") is True
+
+    def test_does_not_touch_uv_skip_env_var(self):
+        """The UV_SKIP_WHEEL_FILENAME_CHECK hack is gone; the env must be untouched."""
         observed = {}
 
         def _capture(*args, **kwargs):
-            observed["val"] = os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK")
+            observed["during"] = os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK")
             return True
 
-        with patch.object(stack_mod, "pip_install_try", side_effect = _capture):
-            stack_mod._install_bnb_windows_rocm()
-        assert observed.get("val") == "1"
-
-    def test_restores_uv_skip_env_var_after_install(self):
-        """UV_SKIP_WHEEL_FILENAME_CHECK should be removed after install if it wasn't set before."""
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
-            with patch.object(stack_mod, "pip_install_try", return_value = True):
+            with patch.object(stack_mod, "pip_install_try", side_effect = _capture):
                 stack_mod._install_bnb_windows_rocm()
+            assert observed.get("during") is None
             assert "UV_SKIP_WHEEL_FILENAME_CHECK" not in os.environ
 
-    def test_restores_previous_uv_skip_value(self):
-        """If UV_SKIP_WHEEL_FILENAME_CHECK was already set, restore it afterwards."""
-        with patch.dict(os.environ, {"UV_SKIP_WHEEL_FILENAME_CHECK": "0"}):
-            with patch.object(stack_mod, "pip_install_try", return_value = True):
-                stack_mod._install_bnb_windows_rocm()
-            assert os.environ.get("UV_SKIP_WHEEL_FILENAME_CHECK") == "0"
-
-    def test_restores_env_even_if_install_raises(self):
-        """UV_SKIP_WHEEL_FILENAME_CHECK must be cleaned up even on pip failure."""
+    def test_returns_false_on_pip_failure(self):
+        """A failed pip_install_try must surface as a False return, not BNB_ROCM_VERSION."""
         with patch.dict(os.environ, {}, clear = False):
-            os.environ.pop("UV_SKIP_WHEEL_FILENAME_CHECK", None)
-            with patch.object(
-                stack_mod, "pip_install_try", side_effect = RuntimeError("pip failed")
-            ):
-                try:
-                    stack_mod._install_bnb_windows_rocm()
-                except RuntimeError:
-                    pass
-            assert "UV_SKIP_WHEEL_FILENAME_CHECK" not in os.environ
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            with patch.object(stack_mod, "pip_install_try", return_value = False):
+                result = stack_mod._install_bnb_windows_rocm()
+            assert result is False
+            assert "BNB_ROCM_VERSION" not in os.environ
 
     def test_no_op_when_win_amd64_url_missing(self):
         """Should be silent no-op if win_amd64 key absent from _BNB_ROCM_PRERELEASE_URLS."""
@@ -1906,24 +1905,34 @@ class TestWorkerWindowsRocmPatches:
         assert "offs_list" in source
         assert "offs.tolist()" in source
 
+    def test_worker_calls_shared_torchao_stub(self):
+        """worker.py must invoke the shared torchao stub entrypoint."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "install_torchao_windows_rocm_stub()" in source
+
+    def test_export_worker_calls_shared_torchao_stub(self):
+        """export/worker.py must invoke the same shared torchao stub entrypoint."""
+        source = _EXPORT_WORKER_PATH.read_text(encoding = "utf-8")
+        assert "install_torchao_windows_rocm_stub()" in source
+
     def test_torchao_stub_uses_stub_type_meta(self):
         """Torchao stub must use _StubTypeMeta so isinstance() returns False not TypeError."""
-        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        source = _TORCHAO_STUB_PATH.read_text(encoding = "utf-8")
         assert "_StubTypeMeta" in source
 
     def test_stub_type_meta_has_instancecheck(self):
         """_StubTypeMeta must define __instancecheck__ returning False."""
-        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        source = _TORCHAO_STUB_PATH.read_text(encoding = "utf-8")
         assert "__instancecheck__" in source
 
     def test_stub_subpackage_finder_registered(self):
         """_StubSubpackageFinder must be appended to sys.meta_path."""
-        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        source = _TORCHAO_STUB_PATH.read_text(encoding = "utf-8")
         assert "sys.meta_path.append(_StubSubpackageFinder())" in source
 
     def test_torchao_key_submodules_pre_stubbed(self):
         """Key torchao submodules (dtypes, quantization) must be pre-stubbed."""
-        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        source = _TORCHAO_STUB_PATH.read_text(encoding = "utf-8")
         assert "torchao.dtypes" in source
         assert "torchao.quantization" in source
 

From faea796c35e6ff1d1e522267bfd7ca62aa567bb3 Mon Sep 17 00:00:00 2001
From: mervivian <120740928+mervivian@users.noreply.github.com>
Date: Sat, 30 May 2026 21:15:40 -0700
Subject: [PATCH 024/222] fix: wrong code block language for nightly Windows
 install (#5877)

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ecf0f8a7a3..948d84a789 100644
--- a/README.md
+++ b/README.md
@@ -202,7 +202,7 @@ unsloth studio -p 8888
 
 #### Nightly: Windows:
 Run in Windows Powershell:
-```bash
+```powershell
 git clone https://github.com/unslothai/unsloth.git
 cd unsloth
 git checkout nightly

From 109a6662602ff4c295306ee53ece6f364c94e9ec Mon Sep 17 00:00:00 2001
From: OrbisAI Security <mediratta01.pally@gmail.com>
Date: Sun, 31 May 2026 12:02:54 +0530
Subject: [PATCH 025/222] fix: bump openssl, rand, rustls-webpki, tar in Studio
 src-tauri for security advisories (#5866)

Lockfile-only security bumps in studio/src-tauri:

- openssl 0.10.76 -> 0.10.80 (CVE-2026-41676)
- rand 0.8.5 -> 0.8.6 and 0.10.0 -> 0.10.1 (RUSTSEC-2026-0097)
- rustls-webpki 0.103.10 -> 0.103.13 (RUSTSEC-2026-0098/0099/0104)
- tar 0.4.45 -> 0.4.46 (GHSA-3pv8-6f4r-ffg2)

Verified with a Tauri Linux debug build and the lockfile supply-chain audit.
---
 studio/src-tauri/Cargo.lock | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/studio/src-tauri/Cargo.lock b/studio/src-tauri/Cargo.lock
index c73d7cc0c5..df350e4011 100644
--- a/studio/src-tauri/Cargo.lock
+++ b/studio/src-tauri/Cargo.lock
@@ -2731,15 +2731,14 @@ dependencies = [
 
 [[package]]
 name = "openssl"
-version = "0.10.76"
+version = "0.10.80"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "951c002c75e16ea2c65b8c7e4d3d51d5530d8dfa7d060b4776828c88cfb18ecf"
+checksum = "a45fa2aa886c42762255da344f0a0d313e254066c46aad76f300c3d3da62d967"
 dependencies = [
  "bitflags 2.11.0",
  "cfg-if",
  "foreign-types 0.3.2",
  "libc",
- "once_cell",
  "openssl-macros",
  "openssl-sys",
 ]
@@ -2763,9 +2762,9 @@ checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
 [[package]]
 name = "openssl-sys"
-version = "0.9.112"
+version = "0.9.116"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57d55af3b3e226502be1526dfdba67ab0e9c96fc293004e79576b2b9edb0dbdb"
+checksum = "f28a22dc7140cda5f096e5e7724a6962ca81a7f8bfd2979f9b18c11af56318c4"
 dependencies = [
  "cc",
  "libc",
@@ -2978,7 +2977,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d5285893bb5eb82e6aaf5d59ee909a06a16737a8970984dd7746ba9283498d6"
 dependencies = [
  "phf_shared 0.10.0",
- "rand 0.8.5",
+ "rand 0.8.6",
 ]
 
 [[package]]
@@ -2988,7 +2987,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
 dependencies = [
  "phf_shared 0.11.3",
- "rand 0.8.5",
+ "rand 0.8.6",
 ]
 
 [[package]]
@@ -3361,9 +3360,9 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.8.5"
+version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
  "libc",
  "rand_chacha 0.3.1",
@@ -3382,9 +3381,9 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
 dependencies = [
  "chacha20",
  "getrandom 0.4.2",
@@ -3765,9 +3764,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.10"
+version = "0.103.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df33b2b81ac578cabaf06b89b0631153a3f416b0a886e8a7a1707fb51abbd1ef"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
 dependencies = [
  "ring",
  "rustls-pki-types",
@@ -4450,9 +4449,9 @@ dependencies = [
 
 [[package]]
 name = "tar"
-version = "0.4.45"
+version = "0.4.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22692a6476a21fa75fdfc11d452fda482af402c008cdbaf3476414e122040973"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
 dependencies = [
  "filetime",
  "libc",
@@ -5380,7 +5379,7 @@ dependencies = [
  "log",
  "open",
  "process-wrap",
- "rand 0.10.0",
+ "rand 0.10.1",
  "regex",
  "reqwest 0.12.28",
  "serde",

From 87ee06a9932fed77bb78093b24cf3c3c0d390fe5 Mon Sep 17 00:00:00 2001
From: Suyadi <104284194+afsuyadi@users.noreply.github.com>
Date: Sun, 31 May 2026 14:05:42 +0700
Subject: [PATCH 026/222] Fix error when context-resizing (#5860)

Harden local GGUF detection so a .gguf path is not misrouted to the transformers backend during the brief Windows lock window after llama-server is killed. Catch OSError from stat() and treat the path as the file, while a directory named *.gguf still falls through to the directory scan. Adds regression tests for the lock-window and directory cases.
---
 studio/backend/tests/test_gguf_routing.py   | 102 ++++++++++++++++++++
 studio/backend/utils/models/model_config.py |  15 ++-
 2 files changed, 112 insertions(+), 5 deletions(-)
 create mode 100644 studio/backend/tests/test_gguf_routing.py

diff --git a/studio/backend/tests/test_gguf_routing.py b/studio/backend/tests/test_gguf_routing.py
new file mode 100644
index 0000000000..1b299cba19
--- /dev/null
+++ b/studio/backend/tests/test_gguf_routing.py
@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""
+Tests for GGUF routing in detect_gguf_model.
+
+Regression test for the bug where a .gguf file temporarily appears
+inaccessible on Windows during llama-server process teardown, causing
+is_file() to return False and the model to be routed to the transformers
+backend instead of llama-server.
+"""
+
+import sys
+import os
+import types
+from pathlib import Path
+from unittest.mock import patch
+
+# Stub structlog before importing backend modules (mirrors other tests in this suite)
+if "structlog" not in sys.modules:
+
+    class _DummyLogger:
+        def __getattr__(self, _):
+            return lambda *a, **k: None
+
+    sys.modules["structlog"] = types.SimpleNamespace(
+        get_logger = lambda *a, **k: _DummyLogger(),
+        BoundLogger = _DummyLogger,
+    )
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from utils.models.model_config import detect_gguf_model
+
+
+def test_detects_gguf_file_normally(tmp_path):
+    """Normal case: .gguf file exists and is accessible."""
+    gguf = tmp_path / "gpt-oss-20b-MXFP4.gguf"
+    gguf.write_bytes(b"")
+    result = detect_gguf_model(str(gguf))
+    assert result is not None
+    assert result.endswith("gpt-oss-20b-MXFP4.gguf")
+
+
+def test_detects_gguf_when_stat_raises_oserror(tmp_path):
+    """
+    Regression: on Windows, both is_file() and exists() call stat() internally.
+    During the brief lock window after llama-server is killed, stat() raises
+    OSError, causing both to return False. detect_gguf_model must still route
+    to llama-server based on the file extension alone.
+    """
+    gguf = tmp_path / "gpt-oss-20b-MXFP4.gguf"
+    gguf.write_bytes(b"")
+
+    original_stat = Path.stat
+
+    def flaky_stat(self, **kwargs):
+        if self.suffix.lower() == ".gguf":
+            raise OSError("file temporarily inaccessible (Windows lock window)")
+        return original_stat(self, **kwargs)
+
+    with patch.object(Path, "stat", flaky_stat):
+        result = detect_gguf_model(str(gguf))
+
+    assert result is not None, (
+        "detect_gguf_model returned None when stat() raised OSError. "
+        "This causes the model to fall through to the transformers backend."
+    )
+
+
+def test_does_not_detect_mmproj_as_main_model(tmp_path):
+    """mmproj files must never be returned as the primary model."""
+    mmproj = tmp_path / "mmproj-model-f16.gguf"
+    mmproj.write_bytes(b"")
+    result = detect_gguf_model(str(mmproj))
+    assert result is None
+
+
+def test_detects_gguf_in_directory(tmp_path):
+    """Directory containing a .gguf file is resolved to that file."""
+    gguf = tmp_path / "model-Q4_K_M.gguf"
+    gguf.write_bytes(b"")
+    result = detect_gguf_model(str(tmp_path))
+    assert result is not None
+    assert result.endswith("model-Q4_K_M.gguf")
+
+
+def test_directory_named_like_gguf_scans_inside(tmp_path):
+    """A directory named *.gguf resolves the real .gguf inside, not itself."""
+    gguf_dir = tmp_path / "mymodel.gguf"
+    gguf_dir.mkdir()
+    inner = gguf_dir / "model-Q4_K_M.gguf"
+    inner.write_bytes(b"")
+    result = detect_gguf_model(str(gguf_dir))
+    assert result is not None
+    assert result.endswith("model-Q4_K_M.gguf")
+
+
+def test_returns_none_for_non_gguf_path(tmp_path):
+    """Non-.gguf paths with no .gguf files inside return None."""
+    result = detect_gguf_model(str(tmp_path))
+    assert result is None
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 993995ee57..dc34444ccb 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -1156,13 +1156,18 @@ def detect_gguf_model(path: str) -> Optional[str]:
     p = Path(path)
 
     # Case 1: direct .gguf file
-    if p.suffix.lower() == ".gguf" and p.is_file():
+    if p.suffix.lower() == ".gguf":
         if _is_mmproj(p.name):
             return None
-        # Use absolute (not resolve) to preserve symlink names -- e.g.
-        # Ollama .studio_links/model.gguf -> blobs/sha256-... should
-        # keep the readable symlink name, not the opaque blob hash.
-        return str(p.absolute())
+        # Extension is authoritative: don't gate on is_file()/exists(), which
+        # can fail in the Windows lock window after llama-server is killed.
+        try:
+            is_dir = p.is_dir()
+        except OSError:
+            is_dir = False  # stat() unavailable in the lock window
+        if not is_dir:
+            return str(p.absolute())  # absolute() keeps symlink names readable
+        # Directory named "*.gguf": fall through to the dir scan below.
 
     # Case 2: directory containing .gguf files (skip mmproj)
     if p.is_dir():

From 1016fff1d6e13d2d61afb0c815a89dbb7a6ef19d Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 31 May 2026 00:53:40 -0700
Subject: [PATCH 027/222] Update Studio sidebar logout icon to logout-05
 (#5878)

Co-authored-by: Unsloth <michaelhan@Michaels-MacBook-Pro.local>
---
 studio/frontend/src/components/app-sidebar.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 849e017ea8..4e4a6130cd 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -49,7 +49,7 @@ import {
   Edit03Icon,
   Globe02Icon,
   HelpCircleIcon,
-  Logout01Icon,
+  Logout05Icon,
   Search01Icon,
   PowerIcon,
   PencilEdit02Icon,
@@ -796,7 +796,7 @@ export function AppSidebar() {
                     void navigate({ to: "/login" });
                   }}
                 >
-                  <HugeiconsIcon icon={Logout01Icon} strokeWidth={1.75} className="size-icon" />
+                  <HugeiconsIcon icon={Logout05Icon} strokeWidth={1.75} className="size-icon" />
                   <span>{t("shell.navigation.logOut")}</span>
                 </DropdownMenuItem>
                 <DropdownMenuItem onSelect={() => setShutdownOpen(true)}>

From 366937de44ded599b569f9a90521ee9da32dcdee Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 00:59:25 -0700
Subject: [PATCH 028/222] studio: pick a macOS llama.cpp prebuilt that loads on
 the host OS (#5883)

Make macOS llama.cpp prebuilt selection host-OS-version aware: skip a prebuilt whose minimum-OS exceeds the host and walk back to the newest release that loads (macOS 26 keeps latest; 14/15 land on a compatible older release). Source-build fallback pins CMAKE_OSX_DEPLOYMENT_TARGET=13.3. CI: binary-load assertion plus a macos-14/15/26 install matrix. No change to Linux/Windows or CUDA selection.
---
 .github/scripts/assert-llama-loads.sh         |  57 ++++
 .github/workflows/studio-mac-api-smoke.yml    |   9 +-
 .../workflows/studio-mac-inference-smoke.yml  |  27 +-
 .../workflows/studio-mac-install-matrix.yml   |  80 +++++
 .github/workflows/studio-mac-ui-smoke.yml     |   9 +-
 .github/workflows/studio-mac-update-smoke.yml |  17 +-
 studio/install_llama_prebuilt.py              | 228 ++++++++++++-
 studio/setup.sh                               |   9 +
 .../install/test_macos_version_compat.py      | 322 ++++++++++++++++++
 9 files changed, 705 insertions(+), 53 deletions(-)
 create mode 100755 .github/scripts/assert-llama-loads.sh
 create mode 100644 .github/workflows/studio-mac-install-matrix.yml
 create mode 100644 tests/studio/install/test_macos_version_compat.py

diff --git a/.github/scripts/assert-llama-loads.sh b/.github/scripts/assert-llama-loads.sh
new file mode 100755
index 0000000000..c2ffe27469
--- /dev/null
+++ b/.github/scripts/assert-llama-loads.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+#
+# Assert Studio installed a llama.cpp that loads and runs on THIS macOS. Tests
+# the contract that matters (binaries load and their minimum-OS is <= this host)
+# instead of the old "did install.sh fall back to a source build?" grep, since a
+# source build with a correct deployment target is a valid outcome.
+set -uo pipefail
+
+UNSLOTH_HOME="${STUDIO_HOME:-$HOME/.unsloth}"
+LLAMA_DIR="${LLAMA_CPP_DIR:-$UNSLOTH_HOME/llama.cpp}"
+BIN_DIR="$LLAMA_DIR/build/bin"
+
+fail() {
+  echo "::error::$*"
+  if [ -f logs/install.log ]; then
+    echo "---- install.log (llama.cpp lines) ----"
+    grep -E "llama-prebuilt|llama\.cpp|macos prebuilt|falling back" logs/install.log | tail -80 || true
+  fi
+  exit 1
+}
+
+SERVER="$(find "$LLAMA_DIR" -type f -name 'llama-server' 2>/dev/null | head -1)"
+QUANT="$(find "$LLAMA_DIR" -type f -name 'llama-quantize' 2>/dev/null | head -1)"
+[ -n "$SERVER" ] || fail "llama-server not found under $LLAMA_DIR after install"
+[ -n "$QUANT" ]  || fail "llama-quantize not found under $LLAMA_DIR after install"
+
+HOST_VER="$(sw_vers -productVersion 2>/dev/null || echo '0')"
+HOST_MAJOR="${HOST_VER%%.*}"
+
+# Static minimum-OS check on every Mach-O we ship. vtool ships with the Xcode
+# command line tools, which GitHub macOS runners always have; if it is somehow
+# missing we skip the static check and rely on the runtime launch below.
+if command -v vtool >/dev/null 2>&1; then
+  while IFS= read -r macho; do
+    [ -n "$macho" ] || continue
+    minos="$(vtool -show-build "$macho" 2>/dev/null | awk '/minos/{print $2; exit}')"
+    [ -n "$minos" ] || continue
+    min_major="${minos%%.*}"
+    if [ "$min_major" -gt "$HOST_MAJOR" ] 2>/dev/null; then
+      fail "$(basename "$macho") is built for macOS $minos but this runner is macOS $HOST_VER (prebuilt is newer than the host)"
+    fi
+  done < <(find "$BIN_DIR" -type f \( -name '*.dylib' -o -name 'llama-server' -o -name 'llama-quantize' \) 2>/dev/null)
+fi
+
+# Runtime launch: --version forces dyld to load every linked dylib (including
+# libggml-metal.dylib). A missing Metal symbol or too-new binary fails here.
+if ! "$SERVER" --version >/tmp/llama-server-version.txt 2>&1; then
+  echo "---- llama-server --version output ----"
+  cat /tmp/llama-server-version.txt || true
+  fail "llama-server failed to launch on macOS $HOST_VER (dyld load / symbol error)"
+fi
+
+echo "llama.cpp load validation passed on macOS $HOST_VER"
+echo "  server: $SERVER"
+sed -n '1,4p' /tmp/llama-server-version.txt 2>/dev/null || true
diff --git a/.github/workflows/studio-mac-api-smoke.yml b/.github/workflows/studio-mac-api-smoke.yml
index b4e274155e..8839b559fd 100644
--- a/.github/workflows/studio-mac-api-smoke.yml
+++ b/.github/workflows/studio-mac-api-smoke.yml
@@ -89,13 +89,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: Install pyjwt for the JWT-expiry forge test
         run: pip install 'pyjwt>=2.6'
diff --git a/.github/workflows/studio-mac-inference-smoke.yml b/.github/workflows/studio-mac-inference-smoke.yml
index fab0a36bd1..1096b1abb4 100644
--- a/.github/workflows/studio-mac-inference-smoke.yml
+++ b/.github/workflows/studio-mac-inference-smoke.yml
@@ -114,13 +114,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: Install OpenAI + Anthropic Python SDKs
         run: pip install 'openai>=1.50' 'anthropic>=0.40'
@@ -369,13 +364,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: Reset auth + boot Studio (API-only, default tool policy)
         # We deliberately use the API-only mode rather than
@@ -760,13 +750,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: Install OpenAI + Anthropic Python SDKs
         run: pip install 'openai>=1.50' 'anthropic>=0.40'
diff --git a/.github/workflows/studio-mac-install-matrix.yml b/.github/workflows/studio-mac-install-matrix.yml
new file mode 100644
index 0000000000..4e2722d1cd
--- /dev/null
+++ b/.github/workflows/studio-mac-install-matrix.yml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+# Proves Studio's llama.cpp install loads on every supported macOS. The heavy
+# app smokes stay single-OS; this matrix covers the OS-version dimension cheaply
+# (install.sh + binary-load assert). Regression guard for the macOS-version
+# selection in studio/install_llama_prebuilt.py.
+
+name: Mac Studio Install Matrix CI
+
+on:
+  pull_request:
+    paths:
+      - 'studio/install_llama_prebuilt.py'
+      - 'studio/setup.sh'
+      - 'install.sh'
+      - '.github/scripts/assert-llama-loads.sh'
+      - '.github/workflows/studio-mac-install-matrix.yml'
+  push:
+    branches: [main, pip]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  install-load:
+    name: Install + load (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-14        # Apple Silicon, macOS 14 Sonoma
+            experimental: false
+          - os: macos-15        # Apple Silicon, macOS 15 Sequoia
+            experimental: false
+          - os: macos-26        # Apple Silicon, macOS 26 Tahoe
+            experimental: false
+          - os: macos-15-intel  # Intel x86_64, macOS 15 (informational)
+            experimental: true
+          - os: macos-26-intel  # Intel x86_64, macOS 26 (last Intel macOS)
+            experimental: true
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: '22'
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.12'
+
+      - name: Install Studio (--local, --no-torch)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p logs
+          set -o pipefail
+          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
+
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
+
+      - name: Upload install log
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: mac-install-matrix-${{ matrix.os }}-log
+          path: logs/install.log
+          retention-days: 7
diff --git a/.github/workflows/studio-mac-ui-smoke.yml b/.github/workflows/studio-mac-ui-smoke.yml
index b353f0ec83..0176b0a168 100644
--- a/.github/workflows/studio-mac-ui-smoke.yml
+++ b/.github/workflows/studio-mac-ui-smoke.yml
@@ -89,13 +89,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: Install Playwright + Chromium
         # No --with-deps on Mac: that flag installs Linux apt packages.
diff --git a/.github/workflows/studio-mac-update-smoke.yml b/.github/workflows/studio-mac-update-smoke.yml
index b65439f174..1eca227096 100644
--- a/.github/workflows/studio-mac-update-smoke.yml
+++ b/.github/workflows/studio-mac-update-smoke.yml
@@ -67,21 +67,8 @@ jobs:
           set -o pipefail
           bash install.sh --local --no-torch 2>&1 | tee logs/install.log
 
-      - name: Assert install.sh used the Mac llama.cpp prebuilt
-        run: |
-          # Mac install must take the prebuilt path. Source-build
-          # fallback here is an Unsloth bug.
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.sh fell back to source-build llama.cpp on Mac. Studio must install the prebuilt llama-bNNNN-bin-macos-arm64 on Apple Silicon."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
-          if ! grep -qE "prebuilt installed and validated|prebuilt up to date and validated|bin-macos-arm64" logs/install.log; then
-            echo "::error::no Mac prebuilt llama.cpp marker in install.log."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
-          echo "install.sh installed the Mac prebuilt llama.cpp"
+      - name: Assert llama.cpp loads on this macOS
+        run: bash .github/scripts/assert-llama-loads.sh
 
       - name: First update should be a no-op (prebuilt already validated)
         env:
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 9443b13fd7..38fa31fff8 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -19,6 +19,7 @@ import re
 import shutil
 import site
 import socket
+import struct
 import subprocess
 import sys
 import tarfile
@@ -160,6 +161,14 @@ DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS = env_int(
     2,
     minimum = 1,
 )
+# Deeper macOS-only walk-back: upstream can ship a run of prebuilts built for a
+# newer macOS than the host, only caught at validate time, so an older host must
+# skip the whole run. Free on new hosts (first plan validates, extras unused).
+DEFAULT_MAX_MACOS_RELEASE_FALLBACKS = env_int(
+    "UNSLOTH_LLAMA_MAX_MACOS_RELEASE_FALLBACKS",
+    16,
+    minimum = 1,
+)
 FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master")
 
 DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
@@ -231,6 +240,9 @@ class HostInfo:
     has_usable_nvidia: bool
     has_rocm: bool = False
     rocm_gfx_target: str | None = None
+    # (major, minor) from platform.mac_ver(); None off macOS or if unparseable.
+    # Skips a macos prebuilt whose minimum-OS exceeds this host.
+    macos_version: tuple[int, int] | None = None
 
 
 @dataclass
@@ -1528,6 +1540,14 @@ def resolve_simple_install_release_plans(
         requested_tag == "latest" and not published_release_tag
     )
     release_limit = max(1, max_release_fallbacks)
+    # macOS may need to walk past a run of too-new prebuilts. Only when the host
+    # version is known; otherwise keep the default (cannot tell up front).
+    if (
+        host.is_macos
+        and allow_older_release_fallback
+        and host.macos_version is not None
+    ):
+        release_limit = max(release_limit, DEFAULT_MAX_MACOS_RELEASE_FALLBACKS)
     plans: list[InstallReleasePlan] = []
     last_error: PrebuiltFallback | None = None
 
@@ -2750,6 +2770,8 @@ def detect_host() -> HostInfo:
     is_x86_64 = machine in {"x86_64", "amd64"}
     is_arm64 = machine in {"arm64", "aarch64"}
 
+    macos_version = parse_macos_version(platform.mac_ver()[0]) if is_macos else None
+
     nvidia_smi = shutil.which("nvidia-smi")
     driver_cuda_version = None
     compute_caps: list[str] = []
@@ -2925,6 +2947,7 @@ def detect_host() -> HostInfo:
         has_usable_nvidia = has_usable_nvidia,
         has_rocm = has_rocm,
         rocm_gfx_target = rocm_gfx_target,
+        macos_version = macos_version,
     )
 
 
@@ -4872,6 +4895,189 @@ def linux_runtime_dirs(binary_path: Path) -> list[str]:
     return linux_runtime_dirs_for_required_libraries(missing)
 
 
+# macOS prebuilt compatibility. Upstream macos prebuilts built on a newer macOS
+# (e.g. minos=26, referencing Metal-4 symbols) fail dyld load on macOS 14/15. We
+# read the host macOS version and each binary's minimum-OS so selection can skip
+# a too-new prebuilt and walk back to the newest release that runs on this host.
+# Mach-O constants (Apple mach-o/fat.h, mach-o/loader.h, mach/machine.h).
+_MACHO_FAT_MAGICS = {0xCAFEBABE, 0xCAFEBABF}  # universal binary (32/64-bit fat)
+_LC_VERSION_MIN_MACOSX = 0x24  # legacy min-macOS load command
+_LC_BUILD_VERSION = 0x32  # modern platform+minos+sdk load command
+_MACHO_PLATFORM_MACOS = 1  # LC_BUILD_VERSION platform id for macOS (iOS=2, ...)
+# CPU types (base | ABI64); used to pick the host slice in a fat binary.
+_CPU_TYPE_X86_64 = 0x01000007
+_CPU_TYPE_ARM64 = 0x0100000C
+
+
+def parse_macos_version(value: str | None) -> tuple[int, int] | None:
+    """Parse a macOS product version string into (major, minor).
+
+    Handles "14.7.1", "15.5", "26.0" and bare "26". Returns None when the
+    value is empty or cannot be parsed (callers then defer to runtime
+    validation rather than rejecting every prebuilt)."""
+    if not value:
+        return None
+    match = re.match(r"\s*(\d+)(?:\.(\d+))?", str(value))
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2) or 0)
+
+
+def host_supports_macos_minos(host: HostInfo, minos: tuple[int, int] | None) -> bool:
+    """True if a prebuilt requiring `minos` can load on this host. Unknown host
+    version or unknown minos -> True: let runtime validation decide instead of
+    rejecting a binary we cannot reason about."""
+    if minos is None or host.macos_version is None:
+        return True
+    return host.macos_version >= minos
+
+
+def _macho_slice_minos(data: bytes, offset: int) -> tuple[int, int] | None:
+    """Minimum macOS for a single thin Mach-O at `offset`, via LC_BUILD_VERSION
+    (platform macOS) or the legacy LC_VERSION_MIN_MACOSX. None if absent."""
+    if offset + 4 > len(data):
+        return None
+    magic = struct.unpack_from(">I", data, offset)[0]
+    if magic in (0xFEEDFACE, 0xFEEDFACF):
+        endian, is64 = ">", magic == 0xFEEDFACF
+    elif magic in (0xCEFAEDFE, 0xCFFAEDFE):
+        endian, is64 = "<", magic == 0xCFFAEDFE
+    else:
+        return None
+    header_size = 32 if is64 else 28
+    if offset + header_size > len(data):
+        return None
+    ncmds = struct.unpack_from(endian + "I", data, offset + 16)[0]
+    cursor = offset + header_size
+    for _ in range(ncmds):
+        if cursor + 8 > len(data):
+            break
+        cmd, cmdsize = struct.unpack_from(endian + "II", data, cursor)
+        if cmdsize < 8:
+            break
+        if cmd == _LC_BUILD_VERSION and cursor + 16 <= len(data):
+            platform_id, minos = struct.unpack_from(endian + "II", data, cursor + 8)
+            if platform_id == _MACHO_PLATFORM_MACOS:
+                return (minos >> 16) & 0xFFFF, (minos >> 8) & 0xFF
+        elif cmd == _LC_VERSION_MIN_MACOSX and cursor + 12 <= len(data):
+            version = struct.unpack_from(endian + "I", data, cursor + 8)[0]
+            return (version >> 16) & 0xFFFF, (version >> 8) & 0xFF
+        cursor += cmdsize
+    return None
+
+
+def macho_minimum_macos(
+    path: Path, host: HostInfo | None = None
+) -> tuple[int, int] | None:
+    """Minimum macOS (major, minor) a Mach-O binary or dylib requires.
+
+    Pure-Python so it works on consumer Macs without the Xcode command line
+    tools (otool/vtool). For universal binaries it prefers the host-arch slice,
+    else the highest minos found. Returns None for non-Mach-O files or when no
+    version load command is present."""
+    try:
+        data = path.read_bytes()
+    except Exception:
+        return None
+    if len(data) < 8:
+        return None
+    magic = struct.unpack_from(">I", data, 0)[0]
+    if magic in _MACHO_FAT_MAGICS:
+        is64 = magic == 0xCAFEBABF
+        nfat = struct.unpack_from(">I", data, 4)[0]
+        entry = 8
+        slices: list[tuple[int, tuple[int, int]]] = []
+        for _ in range(nfat):
+            if is64:
+                if entry + 32 > len(data):
+                    break
+                cputype = struct.unpack_from(">I", data, entry)[0]
+                slice_offset = struct.unpack_from(">Q", data, entry + 8)[0]
+                entry += 32
+            else:
+                if entry + 20 > len(data):
+                    break
+                cputype = struct.unpack_from(">I", data, entry)[0]
+                slice_offset = struct.unpack_from(">I", data, entry + 8)[0]
+                entry += 20
+            minos = _macho_slice_minos(data, slice_offset)
+            if minos is not None:
+                slices.append((cputype, minos))
+        if not slices:
+            return None
+        if host is not None:
+            want = (
+                _CPU_TYPE_ARM64
+                if host.is_arm64
+                else (_CPU_TYPE_X86_64 if host.is_x86_64 else None)
+            )
+            for cputype, minos in slices:
+                if cputype == want:
+                    return minos
+        return max(minos for _cputype, minos in slices)
+    return _macho_slice_minos(data, 0)
+
+
+def looks_like_macos_incompatibility(text: str) -> bool:
+    """True when dyld output means a prebuilt needs a newer macOS than the host
+    (the runtime backstop for cases the static minos scan cannot read)."""
+    if not text:
+        return False
+    if "built for macOS" in text and "newer than running OS" in text:
+        return True
+    return "Symbol not found" in text and "MTLResidency" in text
+
+
+def macos_binary_minos_issues(
+    binaries: Iterable[Path],
+    install_dir: Path,
+    host: HostInfo,
+) -> list[str]:
+    """Issue strings for every installed Mach-O whose minimum macOS exceeds the
+    host. Scans the given executables plus every bundled .dylib next to them --
+    the dyld failure originates in libggml-metal.dylib, not the executable."""
+    candidates: list[Path] = list(binaries)
+    bin_dir = install_dir / "build" / "bin"
+    if bin_dir.is_dir():
+        candidates.extend(sorted(bin_dir.rglob("*.dylib")))
+
+    issues: list[str] = []
+    seen: set[Path] = set()
+    for path in candidates:
+        try:
+            resolved = path.resolve()
+        except Exception:
+            resolved = path
+        if resolved in seen or not path.exists():
+            continue
+        seen.add(resolved)
+        minos = macho_minimum_macos(path, host)
+        if minos is not None and not host_supports_macos_minos(host, minos):
+            issues.append(
+                f"{path.name}: built for macOS {minos[0]}.{minos[1]} > "
+                f"host macOS {host.macos_version[0]}.{host.macos_version[1]}"
+            )
+    return issues
+
+
+def preflight_macos_installed_binaries(
+    binaries: Iterable[Path],
+    install_dir: Path,
+    host: HostInfo,
+) -> None:
+    """Reject a macos prebuilt whose minimum-OS is newer than the host so the
+    release walk-back advances to the newest compatible release. No-op when the
+    host macOS version is unknown (runtime validation remains the backstop)."""
+    if not host.is_macos or host.macos_version is None:
+        return
+    issues = macos_binary_minos_issues(binaries, install_dir, host)
+    if issues:
+        raise PrebuiltFallback(
+            "macos prebuilt requires a newer macOS than this host:\n"
+            + "\n".join(issues)
+        )
+
+
 def preflight_linux_installed_binaries(
     binaries: Iterable[Path],
     install_dir: Path,
@@ -5030,10 +5236,17 @@ def validate_quantize(
         or not quantized_path.exists()
         or quantized_path.stat().st_size == 0
     ):
+        combined = result.stdout + ("\n" + result.stderr if result.stderr else "")
+        # Backstop for prebuilts the static minos scan could not read: a dyld
+        # "built for macOS N" / missing Metal symbol failure means this binary
+        # needs a newer macOS than the host, so fall back to an older release.
+        prefix = (
+            "macos prebuilt requires a newer macOS than this host: "
+            if looks_like_macos_incompatibility(combined)
+            else ""
+        )
         raise PrebuiltFallback(
-            "llama-quantize validation failed:\n"
-            + result.stdout
-            + ("\n" + result.stderr if result.stderr else "")
+            prefix + "llama-quantize validation failed:\n" + combined
         )
 
 
@@ -5451,6 +5664,14 @@ def resolve_install_release_plans(
         requested_tag == "latest" and not published_release_tag
     )
     release_limit = max(1, max_release_fallbacks)
+    # macOS may need to walk past a run of too-new prebuilts. Only when the host
+    # version is known; otherwise keep the default (cannot tell up front).
+    if (
+        host.is_macos
+        and allow_older_release_fallback
+        and host.macos_version is not None
+    ):
+        release_limit = max(release_limit, DEFAULT_MAX_MACOS_RELEASE_FALLBACKS)
     plans: list[InstallReleasePlan] = []
     last_error: PrebuiltFallback | None = None
 
@@ -5835,6 +6056,7 @@ def validate_prebuilt_choice(
         choice, host, install_dir, work_dir
     )
     preflight_linux_installed_binaries((server_path, quantize_path), install_dir, host)
+    preflight_macos_installed_binaries((server_path, quantize_path), install_dir, host)
     ensure_repo_shape(install_dir)
     write_prebuilt_metadata(
         install_dir,
diff --git a/studio/setup.sh b/studio/setup.sh
index 89489f38b0..3a149d465f 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -1084,6 +1084,15 @@ else
                 _IS_MACOS_ARM64=true
             fi
 
+            # macOS: pin a low deployment target so the source build loads on
+            # older macOS too (else a macOS 26 host stamps minos=26). Set before
+            # CPU_FALLBACK_CMAKE_ARGS copies CMAKE_ARGS so both paths inherit it.
+            if [ "$_HOST_SYSTEM" = "Darwin" ]; then
+                _MACOS_DEPLOYMENT_TARGET="${UNSLOTH_MACOS_DEPLOYMENT_TARGET:-13.3}"
+                CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_OSX_DEPLOYMENT_TARGET=${_MACOS_DEPLOYMENT_TARGET}"
+                export MACOSX_DEPLOYMENT_TARGET="${_MACOS_DEPLOYMENT_TARGET}"
+            fi
+
             if command -v ccache &>/dev/null; then
                 CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache"
             fi
diff --git a/tests/studio/install/test_macos_version_compat.py b/tests/studio/install/test_macos_version_compat.py
new file mode 100644
index 0000000000..0adc91a622
--- /dev/null
+++ b/tests/studio/install/test_macos_version_compat.py
@@ -0,0 +1,322 @@
+"""Tests for the host-macOS-version-aware llama.cpp prebuilt selection added
+for the Mac "Failing CI" fix.
+
+Covers: parse_macos_version, host_supports_macos_minos, the pure-Python Mach-O
+minimum-OS parser (macho_minimum_macos), the dyld-incompatibility classifier,
+the install preflight that rejects a too-new prebuilt, and the deeper macOS
+release walk-back in resolve_simple_install_release_plans.
+
+No GPU, no network, no torch, no real Mach-O toolchain required -- the Mach-O
+samples are synthesized in-process and all I/O is monkeypatched.
+"""
+
+import importlib.util
+import struct
+import sys
+from pathlib import Path
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+SPEC = importlib.util.spec_from_file_location(
+    "studio_install_llama_prebuilt_macos", MODULE_PATH
+)
+assert SPEC is not None and SPEC.loader is not None
+ILP = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = ILP
+SPEC.loader.exec_module(ILP)
+
+HostInfo = ILP.HostInfo
+PrebuiltFallback = ILP.PrebuiltFallback
+
+_CPU_TYPE_ARM64 = 0x0100000C
+_CPU_TYPE_X86_64 = 0x01000007
+
+
+def make_macos_host(macos_version, *, arm64 = True):
+    return HostInfo(
+        system = "Darwin",
+        machine = "arm64" if arm64 else "x86_64",
+        is_windows = False,
+        is_linux = False,
+        is_macos = True,
+        is_x86_64 = not arm64,
+        is_arm64 = arm64,
+        nvidia_smi = None,
+        driver_cuda_version = None,
+        compute_caps = [],
+        visible_cuda_devices = None,
+        has_physical_nvidia = False,
+        has_usable_nvidia = False,
+        macos_version = macos_version,
+    )
+
+
+def thin_macho(minos = (14, 0), *, cputype = _CPU_TYPE_ARM64, build_version = True):
+    """Synthesize a minimal little-endian 64-bit Mach-O carrying a macOS
+    minimum-version load command."""
+    encoded = (minos[0] << 16) | (minos[1] << 8)
+    if build_version:
+        # LC_BUILD_VERSION: cmd, cmdsize, platform(=1 macOS), minos, sdk, ntools
+        load_command = struct.pack("<6I", 0x32, 24, 1, encoded, encoded, 0)
+    else:
+        # LC_VERSION_MIN_MACOSX: cmd, cmdsize, version, sdk
+        load_command = struct.pack("<4I", 0x24, 16, encoded, encoded)
+    header = struct.pack("<8I", 0xFEEDFACF, cputype, 0, 0x2, 1, len(load_command), 0, 0)
+    return header + load_command
+
+
+def fat_macho(slices):
+    """Synthesize a big-endian universal binary from (cputype, thin_bytes)."""
+    header = struct.pack(">2I", 0xCAFEBABE, len(slices))
+    data_offset = 8 + 20 * len(slices)
+    arch_entries = b""
+    body = b""
+    for cputype, thin in slices:
+        offset = data_offset + len(body)
+        arch_entries += struct.pack(">5I", cputype, 0, offset, len(thin), 0)
+        body += thin
+    return header + arch_entries + body
+
+
+class TestParseMacosVersion:
+    @pytest.mark.parametrize(
+        "value, expected",
+        [
+            ("14.7.1", (14, 7)),
+            ("15.5", (15, 5)),
+            ("26.0", (26, 0)),
+            ("26", (26, 0)),
+            ("13", (13, 0)),
+            ("", None),
+            (None, None),
+            ("not-a-version", None),
+        ],
+    )
+    def test_parse(self, value, expected):
+        assert ILP.parse_macos_version(value) == expected
+
+
+class TestHostSupportsMacosMinos:
+    def test_older_host_rejects_newer_prebuilt(self):
+        assert not ILP.host_supports_macos_minos(make_macos_host((14, 0)), (26, 0))
+
+    def test_same_version_supported(self):
+        assert ILP.host_supports_macos_minos(make_macos_host((26, 0)), (26, 0))
+
+    def test_newer_host_supports_older_prebuilt(self):
+        assert ILP.host_supports_macos_minos(make_macos_host((15, 5)), (14, 0))
+
+    def test_unknown_host_defers_to_runtime(self):
+        assert ILP.host_supports_macos_minos(make_macos_host(None), (26, 0))
+
+    def test_unknown_minos_defers_to_runtime(self):
+        assert ILP.host_supports_macos_minos(make_macos_host((14, 0)), None)
+
+
+class TestMachoMinimumMacos:
+    def test_build_version_thin(self, tmp_path):
+        path = tmp_path / "lib.dylib"
+        path.write_bytes(thin_macho((26, 0)))
+        assert ILP.macho_minimum_macos(path) == (26, 0)
+
+    def test_legacy_version_min_thin(self, tmp_path):
+        path = tmp_path / "lib.dylib"
+        path.write_bytes(thin_macho((14, 0), build_version = False))
+        assert ILP.macho_minimum_macos(path) == (14, 0)
+
+    def test_universal_prefers_host_arch_slice(self, tmp_path):
+        # arm64 slice needs macOS 14, x86_64 slice needs macOS 26.
+        path = tmp_path / "fat"
+        path.write_bytes(
+            fat_macho(
+                [
+                    (_CPU_TYPE_ARM64, thin_macho((14, 0), cputype = _CPU_TYPE_ARM64)),
+                    (_CPU_TYPE_X86_64, thin_macho((26, 0), cputype = _CPU_TYPE_X86_64)),
+                ]
+            )
+        )
+        assert ILP.macho_minimum_macos(path, make_macos_host((14, 0))) == (14, 0)
+        assert ILP.macho_minimum_macos(path, make_macos_host((26, 0), arm64 = False)) == (
+            26,
+            0,
+        )
+
+    def test_non_macho_returns_none(self, tmp_path):
+        path = tmp_path / "script.sh"
+        path.write_bytes(b'#!/bin/sh\nexec real "$@"\n')
+        assert ILP.macho_minimum_macos(path) is None
+
+    def test_missing_file_returns_none(self, tmp_path):
+        assert ILP.macho_minimum_macos(tmp_path / "nope") is None
+
+
+class TestLooksLikeMacosIncompatibility:
+    def test_built_for_newer_os(self):
+        assert ILP.looks_like_macos_incompatibility(
+            "dyld: ... (built for macOS 26.0 which is newer than running OS)"
+        )
+
+    def test_metal_residency_symbol(self):
+        assert ILP.looks_like_macos_incompatibility(
+            "Symbol not found: _OBJC_CLASS_$_MTLResidencySetDescriptor"
+        )
+
+    def test_benign_error(self):
+        assert not ILP.looks_like_macos_incompatibility("some unrelated failure")
+
+    def test_empty(self):
+        assert not ILP.looks_like_macos_incompatibility("")
+
+
+class TestPreflightMacosInstalledBinaries:
+    def _install_dir(self, tmp_path, dylib_minos):
+        bin_dir = tmp_path / "build" / "bin"
+        bin_dir.mkdir(parents = True)
+        (bin_dir / "libggml-metal.dylib").write_bytes(thin_macho(dylib_minos))
+        server = tmp_path / "llama-server"
+        server.write_bytes(thin_macho(dylib_minos))
+        quantize = tmp_path / "llama-quantize"
+        quantize.write_bytes(thin_macho(dylib_minos))
+        return tmp_path, (server, quantize)
+
+    def test_rejects_too_new_dylib(self, tmp_path):
+        install_dir, binaries = self._install_dir(tmp_path, (26, 0))
+        with pytest.raises(PrebuiltFallback, match = "newer macOS"):
+            ILP.preflight_macos_installed_binaries(
+                binaries, install_dir, make_macos_host((14, 0))
+            )
+
+    def test_accepts_compatible_prebuilt(self, tmp_path):
+        install_dir, binaries = self._install_dir(tmp_path, (14, 0))
+        # Must not raise on a macOS 15 host.
+        ILP.preflight_macos_installed_binaries(
+            binaries, install_dir, make_macos_host((15, 5))
+        )
+
+    def test_skips_when_host_version_unknown(self, tmp_path):
+        install_dir, binaries = self._install_dir(tmp_path, (26, 0))
+        # Unknown host version -> defer to runtime validation, do not raise.
+        ILP.preflight_macos_installed_binaries(
+            binaries, install_dir, make_macos_host(None)
+        )
+
+    def test_noop_on_non_macos_host(self, tmp_path):
+        install_dir, binaries = self._install_dir(tmp_path, (26, 0))
+        linux_host = HostInfo(
+            system = "Linux",
+            machine = "x86_64",
+            is_windows = False,
+            is_linux = True,
+            is_macos = False,
+            is_x86_64 = True,
+            is_arm64 = False,
+            nvidia_smi = None,
+            driver_cuda_version = None,
+            compute_caps = [],
+            visible_cuda_devices = None,
+            has_physical_nvidia = False,
+            has_usable_nvidia = False,
+        )
+        ILP.preflight_macos_installed_binaries(binaries, install_dir, linux_host)
+
+
+def _fake_macos_releases(tags):
+    return [
+        {
+            "tag_name": tag,
+            "assets": [
+                {
+                    "name": f"llama-{tag}-bin-macos-arm64.tar.gz",
+                    "browser_download_url": f"https://example.com/{tag}.tar.gz",
+                }
+            ],
+        }
+        for tag in tags
+    ]
+
+
+class TestMacosReleaseWalkback:
+    """A known-version macOS host must generate enough older-release plans to
+    walk back past a run of too-new prebuilts; unknown-version and non-macOS
+    hosts keep the conservative 2-release default."""
+
+    TAGS = [f"b{n}" for n in range(9437, 9400, -1)]  # 37 newest-first releases
+
+    def _patch_releases(self, monkeypatch):
+        monkeypatch.setattr(
+            ILP,
+            "iter_release_payloads_by_time",
+            lambda repo, published_release_tag, requested_tag: _fake_macos_releases(
+                self.TAGS
+            ),
+        )
+
+    def test_known_macos_host_walks_back_deeper(self, monkeypatch):
+        self._patch_releases(monkeypatch)
+        _tag, plans = ILP.resolve_simple_install_release_plans(
+            "latest",
+            make_macos_host((14, 0)),
+            "ggml-org/llama.cpp",
+            "",
+        )
+        assert len(plans) == ILP.DEFAULT_MAX_MACOS_RELEASE_FALLBACKS
+        assert len(plans) > ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS
+
+    def test_unknown_macos_host_uses_default(self, monkeypatch):
+        self._patch_releases(monkeypatch)
+        _tag, plans = ILP.resolve_simple_install_release_plans(
+            "latest",
+            make_macos_host(None),
+            "ggml-org/llama.cpp",
+            "",
+        )
+        assert len(plans) == ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS
+
+
+class TestForwardsBackwardsCompat:
+    """The gate is host >= prebuilt minos with no hardcoded version, so it holds
+    for older and future macOS alike. Emulate the walk-back over a release set
+    spanning several minos tiers and assert each host takes the newest release
+    it can load."""
+
+    # Newest first: future 27 builds, current 26 builds, an old 14 tier, a 13.
+    RELEASES = [
+        ("b9600", (27, 0)),
+        ("b9450", (26, 0)),
+        ("b9415", (14, 0)),
+        ("b8300", (13, 0)),
+    ]
+
+    def _select(self, tmp_path, host_version):
+        for tag, minos in self.RELEASES:
+            bin_dir = tmp_path / tag / "build" / "bin"
+            bin_dir.mkdir(parents = True)
+            (bin_dir / "libggml-metal.dylib").write_bytes(thin_macho(minos))
+            try:
+                ILP.preflight_macos_installed_binaries(
+                    (), tmp_path / tag, make_macos_host(host_version)
+                )
+                return tag
+            except PrebuiltFallback:
+                continue
+        return None
+
+    @pytest.mark.parametrize(
+        "host_version, expected",
+        [
+            ((13, 0), "b8300"),  # older host takes the older prebuilt
+            ((14, 7), "b9415"),  # backwards: skip 26/27, take newest that loads
+            ((15, 5), "b9415"),
+            ((26, 0), "b9450"),  # unchanged: newest <= host
+            ((27, 1), "b9600"),  # forwards: future host takes the future build
+        ],
+    )
+    def test_selects_newest_loadable(self, tmp_path, host_version, expected):
+        assert self._select(tmp_path, host_version) == expected
+
+    def test_host_below_prebuilt_floor_falls_through(self, tmp_path):
+        # macOS 12 is below every prebuilt -> nothing matches -> source build.
+        assert self._select(tmp_path, (12, 0)) is None

From 5076837cf04b13fc81fd08d134a1aea9be28b39a Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 01:15:02 -0700
Subject: [PATCH 029/222] studio: make NVIDIA prebuilt selection track CUDA
 version bumps (Windows + Linux) (#5879)

Make the NVIDIA prebuilt selection version-dynamic and driver-gated on both the
Windows (ggml-org) and Linux (unslothai/llama.cpp) paths, so CUDA version bumps
are handled with no code change while staying safe across driver versions.

- Derive candidate CUDA runtime lines from the driver major; pick the highest
  upstream-published minor the driver can actually run, so a sub-13.3 driver is
  never handed an unguaranteed 13.3 build.
- Pin b9360's cuda-13.1 build (immutable, hash-verified) as a GPU fallback for a
  Blackwell host on a 13.1/13.2 driver that the in-release 13.3 build gates off,
  on both the simple and published install paths. Dormant for every other host
  and self-disabling once upstream ships a driver-runnable build again.
- Seed the published-path ordering from the release's real published minors so a
  future CUDA major is selectable with no code change.

Refs #5861, #5817, #5807, #5858, #5854, #5826, #5887.
---
 studio/install_llama_prebuilt.py             | 304 +++++++++--
 tests/studio/install/test_selection_logic.py | 526 ++++++++++++++++++-
 2 files changed, 795 insertions(+), 35 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 38fa31fff8..861a501570 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -222,6 +222,71 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     },
 }
 
+# Lowest CUDA major we ship prebuilts for, and the highest major we probe for
+# installed runtime libraries. Detection and runtime-line derivation are
+# generated per major so a new toolkit (cuda14, ...) needs no code change while
+# llama.cpp keeps the cudart64_<major>.dll / libcudart.so.<major> naming.
+_MIN_CUDA_MAJOR = 12
+_MAX_PROBE_CUDA_MAJOR = 19
+
+# Last ggml-org release whose Windows win-cuda-13 build is still sub-13.3
+# (cuda-13.1, b9360, 2026-05-27). Upstream bumped win-cuda-13 to 13.3 at b9365
+# and now ships only cuda-12.4 + cuda-13.3. cuda-12.4 predates Blackwell (ggml
+# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a 13.1/13.2
+# driver is gated off 13.3 and would drop to a CPU-only 12.4 build. b9360 is
+# immutable, so we pin its cuda-13.1 build (plus paired cudart) as a GPU
+# fallback for exactly those hosts. See unslothai/unsloth#5887.
+_PINNED_BLACKWELL_FALLBACK_TAG = "b9360"
+_PINNED_BLACKWELL_FALLBACK_RUNTIME = "13.1"
+_PINNED_BLACKWELL_DRIVER_FLOOR = (13, 1)
+_BLACKWELL_MIN_SM = 120
+# ggml compiles Blackwell sm_120 only at toolkit >= 12.8, so an in-release
+# windows-cuda build at or above this already covers Blackwell and makes the
+# older pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
+_BLACKWELL_MIN_TOOLKIT = (12, 8)
+_PINNED_BLACKWELL_LLAMA_SHA256 = (
+    "31ddb8b42d7ab4a47cab8c48c397519f580ca502df7e73f3ab396eacc16c8e8d"
+)
+_PINNED_BLACKWELL_CUDART_SHA256 = (
+    "f96935e7e385e3b2d0189239077c10fe8fd7e95690fea4afec455b1b6c7e3f18"
+)
+
+
+def _cuda_runtime_lines_for_major(major: int) -> list[str]:
+    """Runtime lines a driver of this CUDA major can use, newest major first
+    down to the minimum we ship. A driver runs its own major and any older one
+    (backward compatibility)."""
+    return [f"cuda{m}" for m in range(major, _MIN_CUDA_MAJOR - 1, -1)]
+
+
+def _resolve_linux_bundle_profile(bundle_profile: str) -> "dict[str, Any] | None":
+    """Profile (runtime line + sm coverage) for a linux-x64-cuda<major>-<class>
+    bundle. Known majors use their published coverage; an unknown future major
+    reuses the newest known major's coverage for the same class as a forward
+    default, with the post-build GPU smoke test as the backstop."""
+    known = DIRECT_LINUX_BUNDLE_PROFILES.get(bundle_profile)
+    if known is not None:
+        return known
+    m = re.fullmatch(
+        r"cuda(?P<major>\d+)-(?P<klass>older|newer|portable)", bundle_profile
+    )
+    if not m:
+        return None
+    base_key = max(
+        (
+            k
+            for k, v in DIRECT_LINUX_BUNDLE_PROFILES.items()
+            if v["coverage_class"] == m.group("klass")
+        ),
+        key = lambda k: int(re.match(r"cuda(\d+)-", k).group(1)),
+        default = None,
+    )
+    if base_key is None:
+        return None
+    profile = dict(DIRECT_LINUX_BUNDLE_PROFILES[base_key])
+    profile["runtime_line"] = f"cuda{m.group('major')}"
+    return profile
+
 
 @dataclass
 class HostInfo:
@@ -769,6 +834,26 @@ def windows_cuda_asset_aliases(
     return aliases
 
 
+def _published_windows_cuda_runtime(
+    upstream_assets: dict[str, str], major: int, driver: tuple[int, int] | None
+) -> str | None:
+    """Highest cuda-<major>.<minor> published upstream that `driver` can run by
+    default CUDA compatibility, i.e. (major, minor) <= driver. None if nothing
+    qualifies. Gating on the driver (not just the major) keeps a 13.3 build off
+    a driver that only advertises 13.1, where it would otherwise rely on the
+    unguaranteed minor-version-compatibility path."""
+    if driver is None:
+        return None
+    best: int | None = None
+    for name in upstream_assets:
+        m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", name)
+        if m and int(m.group(1)) == major:
+            minor = int(m.group(2))
+            if (major, minor) <= driver and (best is None or minor > best):
+                best = minor
+    return f"{major}.{best}" if best is not None else None
+
+
 def format_byte_count(num_bytes: float) -> str:
     units = ["B", "KiB", "MiB", "GiB", "TiB"]
     value = float(num_bytes)
@@ -1225,7 +1310,7 @@ def parse_direct_linux_release_bundle(
     inferred_labels: list[str] = []
 
     linux_asset_re = re.compile(
-        r"^app-(?P<label>.+)-(?P<target>linux-x64(?:-cpu)?|linux-x64-(?:cuda12|cuda13)-(?:older|newer|portable))\.tar\.gz$"
+        r"^app-(?P<label>.+)-(?P<target>linux-x64(?:-cpu)?|linux-x64-cuda\d+-(?:older|newer|portable))\.tar\.gz$"
     )
     for asset_name in sorted(assets):
         match = linux_asset_re.fullmatch(asset_name)
@@ -1250,7 +1335,7 @@ def parse_direct_linux_release_bundle(
             continue
 
         bundle_profile = target.removeprefix("linux-x64-")
-        profile = DIRECT_LINUX_BUNDLE_PROFILES.get(bundle_profile)
+        profile = _resolve_linux_bundle_profile(bundle_profile)
         if profile is None:
             continue
         artifacts.append(
@@ -1400,6 +1485,11 @@ def direct_upstream_release_plan(
                     torch_preference.selection_log,
                 )
             )
+            # Blackwell on a 13.1/13.2 driver: prefer the pinned cuda-13.1 GPU
+            # build over the CPU-only cuda-12.4 the in-release gating leaves.
+            pinned = _pinned_windows_cuda_fallback(host, attempts)
+            if pinned is not None:
+                attempts.insert(0, pinned)
         elif host.has_rocm:
             lemonade_choice = resolve_lemonade_rocm_choice(
                 host, "windows", "windows-hip", llama_tag = requested_tag
@@ -1767,8 +1857,8 @@ def linux_runtime_dirs_for_required_libraries(
 
 def detected_linux_runtime_lines() -> tuple[list[str], dict[str, list[str]]]:
     line_requirements = {
-        "cuda13": ["libcudart.so.13", "libcublas.so.13"],
-        "cuda12": ["libcudart.so.12", "libcublas.so.12"],
+        f"cuda{m}": [f"libcudart.so.{m}", f"libcublas.so.{m}"]
+        for m in range(_MAX_PROBE_CUDA_MAJOR, _MIN_CUDA_MAJOR - 1, -1)
     }
     detected: list[str] = []
     runtime_dirs: dict[str, list[str]] = {}
@@ -2966,17 +3056,21 @@ def compatible_linux_runtime_lines(host: HostInfo) -> list[str]:
     if not host.driver_cuda_version:
         return []
     major, _minor = host.driver_cuda_version
-    if major >= 13:
-        return ["cuda13", "cuda12"]
-    if major >= 12:
-        return ["cuda12"]
-    return []
+    if major < _MIN_CUDA_MAJOR:
+        return []
+    return _cuda_runtime_lines_for_major(major)
 
 
 def windows_runtime_line_info() -> dict[str, tuple[str, ...]]:
+    # Generated per CUDA major (newest first) so a new toolkit is detected
+    # without a code change while the cudart64_<major>.dll naming holds.
     return {
-        "cuda13": ("cudart64_13*.dll", "cublas64_13*.dll", "cublasLt64_13*.dll"),
-        "cuda12": ("cudart64_12*.dll", "cublas64_12*.dll", "cublasLt64_12*.dll"),
+        f"cuda{m}": (
+            f"cudart64_{m}*.dll",
+            f"cublas64_{m}*.dll",
+            f"cublasLt64_{m}*.dll",
+        )
+        for m in range(_MAX_PROBE_CUDA_MAJOR, _MIN_CUDA_MAJOR - 1, -1)
     }
 
 
@@ -2993,12 +3087,13 @@ def detected_windows_runtime_lines() -> tuple[list[str], dict[str, list[str]]]:
 
 
 def compatible_windows_runtime_lines(host: HostInfo) -> list[str]:
-    driver_runtime = pick_windows_cuda_runtime(host)
-    if driver_runtime == "13.1":
-        return ["cuda13", "cuda12"]
-    if driver_runtime == "12.4":
-        return ["cuda12"]
-    return []
+    if not host.driver_cuda_version:
+        return []
+    major, minor = host.driver_cuda_version
+    # cuda12 prebuilts need a 12.4+ driver; cuda13+ any minor of the major.
+    if major < _MIN_CUDA_MAJOR or (major == _MIN_CUDA_MAJOR and minor < 4):
+        return []
+    return _cuda_runtime_lines_for_major(major)
 
 
 def runtime_line_from_cuda_version(cuda_version: str | None) -> str | None:
@@ -3075,7 +3170,6 @@ def windows_cuda_attempts(
     selection_preamble: Iterable[str] = (),
 ) -> list[AssetChoice]:
     selection_log = list(selection_preamble)
-    runtime_by_line = {"cuda12": "12.4", "cuda13": "13.1"}
     driver_runtime = pick_windows_cuda_runtime(host)
     detected_runtime_lines, runtime_dirs = detected_windows_runtime_lines()
     compatible_runtime_lines = compatible_windows_runtime_lines(host)
@@ -3118,12 +3212,7 @@ def windows_cuda_attempts(
             selection_log.append(
                 "windows_cuda_selection: detected CUDA runtime DLLs were incompatible with the reported driver"
             )
-        fallback_runtime_lines = (
-            ["cuda13", "cuda12"]
-            if driver_runtime == "13.1"
-            else (["cuda12"] if driver_runtime == "12.4" else [])
-        )
-        normal_runtime_lines = fallback_runtime_lines
+        normal_runtime_lines = compatible_runtime_lines
 
     runtime_order: list[str] = []
     if preferred_runtime_line and preferred_runtime_line in normal_runtime_lines:
@@ -3147,6 +3236,13 @@ def windows_cuda_attempts(
         for runtime_line in normal_runtime_lines
         if runtime_line not in runtime_order
     )
+    # Keep every driver-compatible line reachable as a fallback, so a line gated
+    # out by the driver version still drops to an older major (cuda13 -> cuda12).
+    runtime_order.extend(
+        runtime_line
+        for runtime_line in compatible_runtime_lines
+        if runtime_line not in runtime_order
+    )
     selection_log.append(
         "windows_cuda_selection: normal_runtime_order="
         + (",".join(normal_runtime_lines) if normal_runtime_lines else "none")
@@ -3158,7 +3254,18 @@ def windows_cuda_attempts(
 
     attempts: list[AssetChoice] = []
     for runtime_line in runtime_order:
-        runtime = runtime_by_line[runtime_line]
+        major = int(runtime_line.removeprefix("cuda"))
+        # Track whatever minor llama.cpp actually ships for this major
+        # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release has no
+        # matching asset instead of guessing a now-missing name.
+        runtime = _published_windows_cuda_runtime(
+            upstream_assets, major, host.driver_cuda_version
+        )
+        if runtime is None:
+            selection_log.append(
+                f"windows_cuda_selection: no driver-supported asset for {runtime_line}"
+            )
+            continue
         selected_name = None
         asset_url = None
         for candidate_name in windows_cuda_upstream_asset_names(llama_tag, runtime):
@@ -3213,6 +3320,110 @@ def windows_cuda_attempts(
     return attempts
 
 
+def _windows_cuda_attempt_covers_blackwell(attempt: AssetChoice) -> bool:
+    """True if an in-release windows-cuda attempt is built with a toolkit that
+    covers Blackwell sm_120 (>= 12.8), read from its asset name's CUDA minor."""
+    if attempt.install_kind != "windows-cuda":
+        return False
+    m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
+    return (
+        m is not None and (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
+    )
+
+
+def _pinned_windows_cuda_fallback(
+    host: HostInfo, existing_cuda_attempts: list[AssetChoice]
+) -> AssetChoice | None:
+    """Pinned GPU fallback for a Blackwell host the in-release build gates off.
+    Upstream stopped publishing a sub-13.3 Windows cuda13 build after b9360, and
+    cuda-12.4 cannot offload sm_120, so a 13.1/13.2 driver would land on CPU.
+    b9360's cuda-13.1 build is immutable and runs on those drivers. Returns None
+    (dormant) whenever the in-release selection already offers a Blackwell-capable
+    build (toolkit >= 12.8, e.g. a runnable cuda13/cuda14), so it self-disables
+    once upstream ships a driver-runnable build again.
+
+    The b9360 binary reuses the current release's source tree and convert scripts
+    and is recorded via binary_release_tag, the same binary/source split used for
+    the lemonade prebuilt."""
+    if not (host.is_windows and host.is_x86_64 and host.has_usable_nvidia):
+        return None
+    driver = host.driver_cuda_version
+    if driver is None or driver < _PINNED_BLACKWELL_DRIVER_FLOOR:
+        return None
+    caps = normalize_compute_caps(host.compute_caps)
+    if not caps or int(caps[-1]) < _BLACKWELL_MIN_SM:
+        return None
+    if any(
+        _windows_cuda_attempt_covers_blackwell(attempt)
+        for attempt in existing_cuda_attempts
+    ):
+        return None
+    tag = _PINNED_BLACKWELL_FALLBACK_TAG
+    runtime = _PINNED_BLACKWELL_FALLBACK_RUNTIME
+    base = (
+        f"https://github.com/{UPSTREAM_REPO}/releases/download/"
+        f"{urllib.parse.quote(tag, safe = '')}"
+    )
+    name = f"llama-{tag}-bin-win-cuda-{runtime}-x64.zip"
+    cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
+    return AssetChoice(
+        repo = UPSTREAM_REPO,
+        tag = tag,
+        name = name,
+        url = f"{base}/{name}",
+        source_label = "upstream",
+        install_kind = "windows-cuda",
+        runtime_line = "cuda13",
+        runtime_name = cudart_name,
+        runtime_url = f"{base}/{cudart_name}",
+        expected_sha256 = _PINNED_BLACKWELL_LLAMA_SHA256,
+        runtime_sha256 = _PINNED_BLACKWELL_CUDART_SHA256,
+        selection_log = [
+            f"windows_cuda_selection: pinned {tag} cuda-{runtime} Blackwell GPU "
+            f"fallback (in-release cuda13 gated off by driver "
+            f"{driver[0]}.{driver[1]})"
+        ],
+    )
+
+
+def _augment_checksums_with_pin(
+    checksums: ApprovedReleaseChecksums, pin: AssetChoice
+) -> ApprovedReleaseChecksums:
+    """Add the pin's own verified hashes to a copy of the approved checksums so
+    apply_approved_hashes keeps it on the published path (b9360 is not in the
+    release manifest)."""
+    artifacts = dict(checksums.artifacts)
+    if pin.expected_sha256:
+        artifacts[pin.name] = ApprovedArtifactHash(
+            asset_name = pin.name,
+            sha256 = pin.expected_sha256,
+            repo = pin.repo,
+            kind = "prebuilt",
+        )
+    if pin.runtime_name and pin.runtime_sha256:
+        artifacts[pin.runtime_name] = ApprovedArtifactHash(
+            asset_name = pin.runtime_name,
+            sha256 = pin.runtime_sha256,
+            repo = pin.repo,
+            kind = "prebuilt",
+        )
+    return dataclasses_replace(checksums, artifacts = artifacts)
+
+
+def _with_pinned_windows_cuda_fallback(
+    host: HostInfo,
+    attempts: list[AssetChoice],
+    checksums: ApprovedReleaseChecksums,
+) -> tuple[list[AssetChoice], ApprovedReleaseChecksums]:
+    """Insert the Blackwell pin ahead of the Windows CUDA attempts and keep it
+    through apply_approved_hashes, or return the inputs unchanged when dormant.
+    Gives the published install path the same GPU fallback as the simple path."""
+    pin = _pinned_windows_cuda_fallback(host, attempts)
+    if pin is None:
+        return attempts, checksums
+    return [pin, *attempts], _augment_checksums_with_pin(checksums, pin)
+
+
 def published_windows_cuda_attempts(
     host: HostInfo,
     release: PublishedReleaseBundle,
@@ -3220,13 +3431,26 @@ def published_windows_cuda_attempts(
     selection_preamble: Iterable[str] = (),
 ) -> list[AssetChoice]:
     selection_log = list(release.selection_log) + list(selection_preamble)
-    runtime_by_line = {"cuda12": "12.4", "cuda13": "13.1"}
+    # Seed the runtime-line ordering from the real published windows-cuda minors
+    # (their names encode the minor), so a future CUDA major published here is
+    # ordered too instead of a hardcoded cuda12/cuda13 pair. Keys mirror the
+    # upstream naming so windows_cuda_attempts can match them; fall back to the
+    # long-standing default when the release lists no windows-cuda asset.
+    published_minors: list[str] = []
+    for artifact in release.artifacts:
+        if artifact.install_kind != "windows-cuda":
+            continue
+        m = re.search(r"-bin-win-cuda-(\d+\.\d+)-x64\.zip$", artifact.asset_name)
+        if m:
+            published_minors.append(m.group(1))
+    if not published_minors:
+        published_minors = ["12.4", "13.1"]
     runtime_order = windows_cuda_attempts(
         host,
         release.upstream_tag,
         {
-            f"llama-{release.upstream_tag}-bin-win-cuda-{runtime}-x64.zip": "published"
-            for runtime in runtime_by_line.values()
+            f"llama-{release.upstream_tag}-bin-win-cuda-{minor}-x64.zip": "published"
+            for minor in published_minors
         },
         preferred_runtime_line,
         selection_log,
@@ -3255,11 +3479,20 @@ def published_windows_cuda_attempts(
             asset_url = release.assets.get(artifact.asset_name)
             if not asset_url:
                 continue
-            # See windows_cuda_attempts: pair the cudart bundle.
+            am = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", artifact.asset_name)
+            # Gate the real published minor against the driver, so a published
+            # windows-cuda artifact can never bypass the driver-version gate.
+            if (
+                am is not None
+                and host.driver_cuda_version is not None
+                and (int(am.group(1)), int(am.group(2))) > host.driver_cuda_version
+            ):
+                continue
+            # See windows_cuda_attempts: pair the cudart bundle for the real minor.
             runtime_archive_name: str | None = None
             runtime_archive_url: str | None = None
-            if artifact.asset_name.startswith("llama-"):
-                runtime = runtime_by_line[runtime_line]
+            if am is not None and artifact.asset_name.startswith("llama-"):
+                runtime = f"{am.group(1)}.{am.group(2)}"
                 cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
                 cudart_url = release.assets.get(cudart_name)
                 if cudart_url and cudart_url != asset_url:
@@ -3812,18 +4045,23 @@ def resolve_release_asset_choice(
             torch_preference.selection_log,
         )
         if published_attempts:
+            pin_attempts, pin_checksums = _with_pinned_windows_cuda_fallback(
+                host, published_attempts, checksums
+            )
             try:
-                return apply_approved_hashes(published_attempts, checksums)
+                return apply_approved_hashes(pin_attempts, pin_checksums)
             except PrebuiltFallback as exc:
                 log(
                     "published Windows CUDA assets ignored for install planning: "
                     f"{release.repo}@{release.release_tag} ({exc})"
                 )
         upstream_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
-        return apply_approved_hashes(
+        upstream_attempts, upstream_checksums = _with_pinned_windows_cuda_fallback(
+            host,
             resolve_windows_cuda_choices(host, llama_tag, upstream_assets),
             checksums,
         )
+        return apply_approved_hashes(upstream_attempts, upstream_checksums)
 
     published_choice: AssetChoice | None = None
     if host.is_windows and host.is_x86_64:
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 713af51e19..16f47fa410 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -52,6 +52,9 @@ compatible_windows_runtime_lines = (
 runtime_line_from_cuda_version = INSTALL_LLAMA_PREBUILT.runtime_line_from_cuda_version
 apply_approved_hashes = INSTALL_LLAMA_PREBUILT.apply_approved_hashes
 linux_cuda_choice_from_release = INSTALL_LLAMA_PREBUILT.linux_cuda_choice_from_release
+parse_direct_linux_release_bundle = (
+    INSTALL_LLAMA_PREBUILT.parse_direct_linux_release_bundle
+)
 windows_cuda_attempts = INSTALL_LLAMA_PREBUILT.windows_cuda_attempts
 resolve_upstream_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_upstream_asset_choice
 resolve_requested_install_tag = INSTALL_LLAMA_PREBUILT.resolve_requested_install_tag
@@ -74,6 +77,14 @@ windows_cuda_upstream_asset_names = (
     INSTALL_LLAMA_PREBUILT.windows_cuda_upstream_asset_names
 )
 env_int = INSTALL_LLAMA_PREBUILT.env_int
+direct_upstream_release_plan = INSTALL_LLAMA_PREBUILT.direct_upstream_release_plan
+_pinned_windows_cuda_fallback = INSTALL_LLAMA_PREBUILT._pinned_windows_cuda_fallback
+CudaRuntimePreference = INSTALL_LLAMA_PREBUILT.CudaRuntimePreference
+published_windows_cuda_attempts = INSTALL_LLAMA_PREBUILT.published_windows_cuda_attempts
+_windows_cuda_attempt_covers_blackwell = (
+    INSTALL_LLAMA_PREBUILT._windows_cuda_attempt_covers_blackwell
+)
+resolve_release_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_release_asset_choice
 
 
 # ---------------------------------------------------------------------------
@@ -397,6 +408,44 @@ class TestCompatibleLinuxRuntimeLines:
         host = make_host(driver_cuda_version = (13, 0))
         assert compatible_linux_runtime_lines(host) == ["cuda13", "cuda12"]
 
+    def test_future_major_derives_lines(self):
+        # A future major (14.x) offers cuda14 first, then older majors.
+        host = make_host(driver_cuda_version = (14, 0))
+        assert compatible_linux_runtime_lines(host) == ["cuda14", "cuda13", "cuda12"]
+
+
+class TestParseDirectLinuxReleaseBundle:
+    def _release(self, *targets):
+        names = [f"app-bTEST-linux-x64-{t}.tar.gz" for t in targets]
+        return {
+            "tag_name": "bTEST",
+            "assets": [
+                {"name": n, "browser_download_url": "https://x/" + n} for n in names
+            ],
+        }
+
+    def _cuda_artifact(self, bundle):
+        return [a for a in bundle.artifacts if a.install_kind == "linux-cuda"][0]
+
+    def test_parses_known_cuda13_bundle(self):
+        bundle = parse_direct_linux_release_bundle(
+            "unslothai/llama.cpp", self._release("cuda13-newer")
+        )
+        assert bundle is not None
+        assert self._cuda_artifact(bundle).runtime_line == "cuda13"
+
+    def test_parses_future_cuda_major_with_forward_profile(self):
+        # A future major name parses and inherits the newest known major's
+        # coverage for the same class as a forward default.
+        bundle = parse_direct_linux_release_bundle(
+            "unslothai/llama.cpp", self._release("cuda14-newer")
+        )
+        assert bundle is not None
+        art = self._cuda_artifact(bundle)
+        assert art.runtime_line == "cuda14"
+        assert art.coverage_class == "newer"
+        assert art.max_sm == 120  # inherited from cuda13-newer
+
 
 # ===========================================================================
 # G. pick_windows_cuda_runtime + compatible_windows_runtime_lines
@@ -442,6 +491,10 @@ class TestCompatibleWindowsRuntimeLines:
         host = make_host(driver_cuda_version = (13, 0))
         assert compatible_windows_runtime_lines(host) == ["cuda13", "cuda12"]
 
+    def test_future_major_derives_lines(self):
+        host = make_host(driver_cuda_version = (14, 0))
+        assert compatible_windows_runtime_lines(host) == ["cuda14", "cuda13", "cuda12"]
+
 
 # ===========================================================================
 # H. runtime_line_from_cuda_version
@@ -1777,12 +1830,23 @@ class TestWindowsCudaAttempts:
         assert result[0].runtime_line == "cuda13"
         assert result[1].runtime_line == "cuda12"
 
-    def test_driver_13_0_cuda13_dlls_selects_cuda13_asset(self, monkeypatch):
+    def test_driver_below_published_minor_is_gated_to_cuda12(self, monkeypatch):
+        # A 13.0 driver cannot run a 13.1 build (forward minor), so it is gated
+        # out of cuda13 and falls back to the cuda12 build it can run, even when
+        # only the cuda13 runtime libs are detected.
         mock_windows_runtime(monkeypatch, ["cuda13"])
         host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 0))
         assets = self._upstream("13.1", "12.4")
         result = windows_cuda_attempts(host, self.TAG, assets, None)
-        assert len(result) == 1
+        assert result[0].runtime_line == "cuda12"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip"
+
+    def test_driver_at_published_minor_selects_cuda13(self, monkeypatch):
+        # A 13.1 driver matches the published 13.1 build exactly.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 1))
+        assets = self._upstream("13.1", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
         assert result[0].runtime_line == "cuda13"
         assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.1-x64.zip"
 
@@ -1885,6 +1949,464 @@ class TestWindowsCudaAttempts:
             assert attempt.runtime_url is None
             assert attempt.runtime_name is None
 
+    def test_tracks_upstream_cuda13_minor_bump(self, monkeypatch):
+        # ggml-org bumped the published Windows cuda13 build 13.1 -> 13.3; the
+        # selector must follow it instead of the old hardcoded 13.1 (#5861).
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 3))
+        assets = self._upstream("13.3", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].runtime_line == "cuda13"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+
+    def test_cuda13_minor_bump_pairs_matching_cudart(self, monkeypatch):
+        # The paired cudart bundle must track the same bumped minor.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 3))
+        assets = {
+            f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip": "https://example.com/llama-13.3",
+            "cudart-llama-bin-win-cuda-13.3-x64.zip": "https://example.com/cudart-13.3",
+            f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip": "https://example.com/llama-12.4",
+            "cudart-llama-bin-win-cuda-12.4-x64.zip": "https://example.com/cudart-12.4",
+        }
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+        assert result[0].runtime_name == "cudart-llama-bin-win-cuda-13.3-x64.zip"
+
+    def test_driver_below_published_minor_does_not_get_newer_build(self, monkeypatch):
+        # ggml-org ships only cuda-13.3; a 13.1 driver cannot run it (forward
+        # minor), so it is gated to the cuda-12.4 build instead of an
+        # unguaranteed 13.3. A 13.3 driver still gets 13.3 (see other tests).
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 1))
+        assets = self._upstream("13.3", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].runtime_line == "cuda12"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip"
+
+    def test_tracks_future_cuda13_minor(self, monkeypatch):
+        # A later within-major bump (13.4) is tracked the same as 13.3.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (13, 4))
+        assets = self._upstream("13.4", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.4-x64.zip"
+
+    def test_new_cuda_major_selected_when_published(self, monkeypatch):
+        # A new CUDA major (14.x) driver picks the published cuda14 build.
+        mock_windows_runtime(monkeypatch, ["cuda14", "cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (14, 0))
+        assets = self._upstream("14.0", "13.3", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].runtime_line == "cuda14"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-14.0-x64.zip"
+
+    def test_new_cuda_major_degrades_to_published_cuda13(self, monkeypatch):
+        # A 14.x driver with no cuda14 build runs the newest published cuda13
+        # build via backward compatibility.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = make_host(system = "Windows", machine = "AMD64", driver_cuda_version = (14, 0))
+        assets = self._upstream("13.3", "12.4")
+        result = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+
+
+# ===========================================================================
+# N.1b. _pinned_windows_cuda_fallback -- pinned b9360 cuda-13.1 Blackwell fallback
+# ===========================================================================
+
+
+class TestPinnedBlackwellCudaFallback:
+    """A Blackwell host on a 13.1/13.2 driver, gated off the in-release 13.3
+    build, gets the pinned immutable b9360 cuda-13.1 GPU build instead of the
+    CPU-only cuda-12.4 drop. The pin is dormant for everyone else."""
+
+    TAG = "b8508"
+
+    def _win_host(self, driver, caps):
+        return make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = driver,
+            compute_caps = caps,
+        )
+
+    def test_pin_offered_for_driver_13_1_blackwell(self):
+        pin = _pinned_windows_cuda_fallback(self._win_host((13, 1), ["120"]), [])
+        assert pin is not None
+        assert pin.tag == "b9360"
+        assert pin.runtime_line == "cuda13"
+        assert pin.name == "llama-b9360-bin-win-cuda-13.1-x64.zip"
+        assert pin.runtime_name == "cudart-llama-bin-win-cuda-13.1-x64.zip"
+        assert pin.url.endswith("/b9360/llama-b9360-bin-win-cuda-13.1-x64.zip")
+        assert pin.runtime_url.endswith("/b9360/cudart-llama-bin-win-cuda-13.1-x64.zip")
+        assert pin.install_kind == "windows-cuda"
+        assert pin.expected_sha256 and len(pin.expected_sha256) == 64
+        assert pin.runtime_sha256 and len(pin.runtime_sha256) == 64
+
+    def test_pin_offered_for_driver_13_2(self):
+        assert (
+            _pinned_windows_cuda_fallback(self._win_host((13, 2), ["120"]), [])
+            is not None
+        )
+
+    def test_pin_offered_for_sm121_variant(self):
+        # sm_121 is Blackwell-family and also needs toolkit >= 12.8.
+        assert (
+            _pinned_windows_cuda_fallback(self._win_host((13, 1), ["121"]), [])
+            is not None
+        )
+
+    def test_pin_uses_max_of_multi_gpu_caps(self):
+        assert (
+            _pinned_windows_cuda_fallback(self._win_host((13, 1), ["86", "120"]), [])
+            is not None
+        )
+
+    @pytest.mark.parametrize("sm", ["89", "90", "100"])
+    def test_pin_not_offered_to_non_blackwell(self, sm):
+        # Ada/Hopper run the cuda-12.4 build fine; the pin must not fire.
+        assert _pinned_windows_cuda_fallback(self._win_host((13, 1), [sm]), []) is None
+
+    def test_pin_not_offered_to_driver_13_0(self):
+        # 13.0 cannot run the 13.1 build (forward minor); residual CPU gap.
+        assert (
+            _pinned_windows_cuda_fallback(self._win_host((13, 0), ["120"]), []) is None
+        )
+
+    def test_pin_not_offered_below_floor(self):
+        assert (
+            _pinned_windows_cuda_fallback(self._win_host((12, 8), ["120"]), []) is None
+        )
+
+    def test_pin_not_offered_without_driver(self):
+        assert _pinned_windows_cuda_fallback(self._win_host(None, ["120"]), []) is None
+
+    def test_pin_not_offered_on_linux(self):
+        host = make_host(
+            system = "Linux",
+            machine = "x86_64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["120"],
+        )
+        assert _pinned_windows_cuda_fallback(host, []) is None
+
+    def test_pin_dormant_when_cuda13_attempt_present(self, monkeypatch):
+        # A runnable in-release cuda13 build makes the pin unnecessary.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        host = self._win_host((13, 1), ["120"])
+        assets = {
+            f"llama-{self.TAG}-bin-win-cuda-13.1-x64.zip": "https://example.com/13.1",
+            f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip": "https://example.com/12.4",
+        }
+        existing = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert any(a.runtime_line == "cuda13" for a in existing)
+        assert _pinned_windows_cuda_fallback(host, existing) is None
+
+    def _win_cuda_attempt(self, minor):
+        major = minor.split(".")[0]
+        return AssetChoice(
+            repo = UPSTREAM_REPO,
+            tag = self.TAG,
+            name = f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip",
+            url = "https://example.com/x",
+            source_label = "upstream",
+            install_kind = "windows-cuda",
+            runtime_line = f"cuda{major}",
+        )
+
+    def test_pin_dormant_when_runnable_cuda14_present(self, monkeypatch):
+        # A future Blackwell host with an in-release cuda14 build (no cuda13)
+        # must not get the older b9360 13.1 pin ahead of the runnable cuda14.
+        mock_windows_runtime(monkeypatch, ["cuda14", "cuda12"])
+        host = self._win_host((14, 0), ["120"])
+        assets = {
+            f"llama-{self.TAG}-bin-win-cuda-14.0-x64.zip": "https://example.com/14.0",
+            f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip": "https://example.com/12.4",
+        }
+        existing = windows_cuda_attempts(host, self.TAG, assets, None)
+        assert any(a.runtime_line == "cuda14" for a in existing)
+        assert _pinned_windows_cuda_fallback(host, existing) is None
+
+    def test_pin_dormant_when_runnable_cuda12_8_present(self):
+        # A cuda-12.8 build also covers Blackwell, so the pin defers to it.
+        host = self._win_host((13, 1), ["120"])
+        existing = [self._win_cuda_attempt("12.8")]
+        assert _pinned_windows_cuda_fallback(host, existing) is None
+
+    def test_pin_fires_when_only_cuda12_4_present(self):
+        # cuda-12.4 does not cover Blackwell, so the pin still fires.
+        host = self._win_host((13, 1), ["120"])
+        existing = [self._win_cuda_attempt("12.4")]
+        assert _pinned_windows_cuda_fallback(host, existing) is not None
+
+    @pytest.mark.parametrize(
+        "minor, covers",
+        [
+            ("12.4", False),
+            ("12.8", True),
+            ("13.1", True),
+            ("13.3", True),
+            ("14.0", True),
+        ],
+    )
+    def test_attempt_covers_blackwell(self, minor, covers):
+        assert (
+            _windows_cuda_attempt_covers_blackwell(self._win_cuda_attempt(minor))
+            is covers
+        )
+
+    def test_attempt_covers_blackwell_ignores_non_cuda_kind(self):
+        cpu = AssetChoice(
+            repo = UPSTREAM_REPO,
+            tag = self.TAG,
+            name = f"llama-{self.TAG}-bin-win-cpu-x64.zip",
+            url = "https://example.com/x",
+            source_label = "upstream",
+            install_kind = "windows-cpu",
+        )
+        assert _windows_cuda_attempt_covers_blackwell(cpu) is False
+
+
+# ===========================================================================
+# N.1c. direct_upstream_release_plan -- pinned Blackwell fallback ordering
+# ===========================================================================
+
+
+class TestDirectUpstreamBlackwellPin:
+    """End to end: the pin lands ahead of cuda-12.4 on the simple/upstream path
+    a Blackwell Windows host actually uses, and stays absent once a runnable
+    in-release cuda13 build exists."""
+
+    TAG = "b9365"
+
+    def _release(self):
+        names = [
+            f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip",
+            "cudart-llama-bin-win-cuda-13.3-x64.zip",
+            f"llama-{self.TAG}-bin-win-cuda-12.4-x64.zip",
+            "cudart-llama-bin-win-cuda-12.4-x64.zip",
+            f"llama-{self.TAG}-bin-win-cpu-x64.zip",
+        ]
+        return {
+            "tag_name": self.TAG,
+            "assets": [
+                {"name": n, "browser_download_url": f"https://example.com/{n}"}
+                for n in names
+            ],
+        }
+
+    def _no_torch(self, monkeypatch):
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "detect_torch_cuda_runtime_preference",
+            lambda host: CudaRuntimePreference(runtime_line = None, selection_log = []),
+        )
+
+    def test_blackwell_13_1_prepends_pin(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        self._no_torch(monkeypatch)
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["120"],
+        )
+        plan = direct_upstream_release_plan(
+            self._release(), host, UPSTREAM_REPO, "latest"
+        )
+        order = [(a.tag, a.runtime_line or a.install_kind) for a in plan.attempts]
+        assert order == [
+            ("b9360", "cuda13"),
+            (self.TAG, "cuda12"),
+            (self.TAG, "windows-cpu"),
+        ]
+        assert plan.attempts[0].name == "llama-b9360-bin-win-cuda-13.1-x64.zip"
+        # Direct/upstream path stays unverified-by-manifest (no approved hashes).
+        assert plan.approved_checksums.artifacts == {}
+
+    def test_blackwell_13_3_no_pin(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        self._no_torch(monkeypatch)
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 3),
+            compute_caps = ["120"],
+        )
+        plan = direct_upstream_release_plan(
+            self._release(), host, UPSTREAM_REPO, "latest"
+        )
+        assert "b9360" not in [a.tag for a in plan.attempts]
+        assert plan.attempts[0].tag == self.TAG
+        assert plan.attempts[0].runtime_line == "cuda13"
+        assert plan.attempts[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+
+
+# ===========================================================================
+# N.1d. published_windows_cuda_attempts -- version-dynamic ordering seed
+# ===========================================================================
+
+
+class TestPublishedWindowsCudaAttemptsDynamicMajor:
+    """The published-path ordering seed is derived from the release's real
+    published minors, so a future CUDA major published here is selectable
+    instead of being hidden by a hardcoded cuda12/cuda13 seed."""
+
+    TAG = "b8508"
+
+    def _win_cuda_artifact(self, minor, runtime_line):
+        return make_artifact(
+            f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip",
+            install_kind = "windows-cuda",
+            runtime_line = runtime_line,
+            max_sm = 120,
+        )
+
+    def _release(self, minors_lines):
+        artifacts = [self._win_cuda_artifact(m, line) for m, line in minors_lines]
+        return make_release(artifacts, upstream_tag = self.TAG)
+
+    def test_future_cuda14_published_is_selected(self, monkeypatch):
+        # With the dynamic seed a 14.x driver reaches a published cuda14 build;
+        # the old hardcoded cuda12/cuda13 seed would never order it (the cuda14
+        # line would be skipped for want of a 14.x asset in the seed).
+        mock_windows_runtime(monkeypatch, ["cuda14", "cuda13", "cuda12"])
+        release = self._release(
+            [("14.0", "cuda14"), ("13.3", "cuda13"), ("12.4", "cuda12")]
+        )
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (14, 0),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, None)
+        assert result[0].runtime_line == "cuda14"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-14.0-x64.zip"
+
+    def test_cuda13_minor_selected_for_13_3_driver(self, monkeypatch):
+        # Existing behavior unchanged: a 13.3 driver gets the real 13.3 build.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        release = self._release([("13.3", "cuda13"), ("12.4", "cuda12")])
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 3),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, None)
+        assert result[0].runtime_line == "cuda13"
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+
+    def test_below_minor_driver_gated_to_cuda12(self, monkeypatch):
+        # A 13.1 driver is gated off a published 13.3 and falls to cuda12.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        release = self._release([("13.3", "cuda13"), ("12.4", "cuda12")])
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, None)
+        assert result[0].runtime_line == "cuda12"
+
+
+# ===========================================================================
+# N.1e. resolve_release_asset_choice -- pin on the published install path
+# ===========================================================================
+
+
+class TestResolveReleaseAssetChoicePin:
+    """The published (non --simple-policy) install path reaches the same b9360
+    Blackwell pin as the simple path, with its verified hash threaded."""
+
+    TAG = "b8508"
+
+    def _release(self, minors_lines):
+        artifacts = [
+            make_artifact(
+                f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip",
+                install_kind = "windows-cuda",
+                runtime_line = line,
+                max_sm = 120,
+            )
+            for minor, line in minors_lines
+        ]
+        assets = {}
+        for minor, _line in minors_lines:
+            assets[f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip"] = (
+                f"https://example.com/llama-{minor}"
+            )
+            assets[f"cudart-llama-bin-win-cuda-{minor}-x64.zip"] = (
+                f"https://example.com/cudart-{minor}"
+            )
+        return make_release(artifacts, upstream_tag = self.TAG, assets = assets)
+
+    def _checksums(self, minors):
+        names = []
+        for minor in minors:
+            names.append(f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip")
+            names.append(f"cudart-llama-bin-win-cuda-{minor}-x64.zip")
+        return make_checksums(names)
+
+    def _no_torch(self, monkeypatch):
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "detect_torch_cuda_runtime_preference",
+            lambda host: CudaRuntimePreference(runtime_line = None, selection_log = []),
+        )
+
+    def test_pin_applied_on_published_path_for_13_1(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        self._no_torch(monkeypatch)
+        release = self._release([("13.3", "cuda13"), ("12.4", "cuda12")])
+        checksums = self._checksums(["12.4"])  # 13.3 gated off for a 13.1 driver
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["120"],
+        )
+        result = resolve_release_asset_choice(host, self.TAG, release, checksums)
+        assert result[0].tag == "b9360"
+        assert result[0].name == "llama-b9360-bin-win-cuda-13.1-x64.zip"
+        # apply_approved_hashes threaded the pin's verified hash from the
+        # augmented checksums (the pin survives the approved-hash gate).
+        assert result[0].expected_sha256 and len(result[0].expected_sha256) == 64
+        assert result[0].runtime_sha256 and len(result[0].runtime_sha256) == 64
+        assert any(a.runtime_line == "cuda12" for a in result)
+
+    def test_pin_dormant_on_published_path_for_13_3(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        self._no_torch(monkeypatch)
+        release = self._release([("13.3", "cuda13"), ("12.4", "cuda12")])
+        checksums = self._checksums(["13.3", "12.4"])
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 3),
+            compute_caps = ["120"],
+        )
+        result = resolve_release_asset_choice(host, self.TAG, release, checksums)
+        assert "b9360" not in [a.tag for a in result]
+        assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
+
+    def test_pin_not_applied_for_non_blackwell(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        self._no_torch(monkeypatch)
+        release = self._release([("13.3", "cuda13"), ("12.4", "cuda12")])
+        checksums = self._checksums(["12.4"])
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["89"],
+        )
+        result = resolve_release_asset_choice(host, self.TAG, release, checksums)
+        assert "b9360" not in [a.tag for a in result]
+
 
 # ===========================================================================
 # N.1. apply_approved_hashes -- runtime archive checksum threading

From a2d77fb0f98fef2b8d651858d10c7b1229d5117e Mon Sep 17 00:00:00 2001
From: Trishanu Das <92977042+Rahul007007@users.noreply.github.com>
Date: Sun, 31 May 2026 13:51:38 +0530
Subject: [PATCH 030/222] Remove dead top-level bitsandbytes import from
 models/_utils.py (#5875)

---
 unsloth/models/_utils.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 8965a88fae..67b3468425 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -1216,8 +1216,6 @@ if is_openai_available():
 
 # =============================================
 # Get Flash Attention v2 if Ampere (RTX 30xx, A100)
-import bitsandbytes as bnb
-
 from transformers import AutoTokenizer
 from transformers.utils.import_utils import _is_package_available
 

From f213663d5b161fedd7c90b8b0e2c193433540cb9 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 01:46:55 -0700
Subject: [PATCH 031/222] ci(security-audit): make package installs
 network-resilient (#5853)

Make the network-touching install and download steps in the security-audit workflow resilient to transient failures without relaxing any integrity check.

- Add top-level retry and backoff env knobs for pip, cargo, and npm.
- Wrap the pip-audit + cargo install and npm ci steps in an exponential-backoff retry helper, preserving --locked and --ignore-scripts.
- Re-pin swatinem/rust-cache to the v2.9.1 commit so the SHA matches its comment.
- Split the OSV-Scanner download and SHA-256 verification into a hard-gated step: a checksum mismatch fails the job, while a transient download failure skips the scan; the advisory scan stays non-blocking.
---
 .github/workflows/security-audit.yml | 126 ++++++++++++++++++++++-----
 1 file changed, 105 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/security-audit.yml b/.github/workflows/security-audit.yml
index a1e7b2efa6..33ac3b9bd8 100644
--- a/.github/workflows/security-audit.yml
+++ b/.github/workflows/security-audit.yml
@@ -72,6 +72,31 @@ concurrency:
 permissions:
   contents: read
 
+# ──────────────────────────────────────────────────────────────────────
+# Network-resilience knobs, applied to every job/step. These add retries
+# and backoff ONLY; they do not relax a single integrity check. cargo
+# still resolves against Cargo.lock (--locked), pip still verifies the
+# wheels it downloads, npm still enforces package-lock integrity, the
+# harden-runner egress allowlists below are unchanged, and every action
+# stays SHA-pinned. The advisory-audit run on 2026-05-29 red-failed when
+# one crates.io tarball fetch hit "Recv failure: Connection reset by
+# peer" (curl 56); cargo's default of 3 retries over an HTTP/2-multiplexed
+# connection did not recover. The settings below make that class of
+# transient fault self-heal instead of failing the whole run.
+env:
+  # pip: raise the built-in retry count and per-connection timeout.
+  PIP_RETRIES: "10"
+  PIP_DEFAULT_TIMEOUT: "60"
+  # cargo: retry network ops and disable HTTP/2 multiplexing -- the
+  # documented mitigation for the curl-56 connection resets above.
+  CARGO_NET_RETRY: "10"
+  CARGO_HTTP_MULTIPLEXING: "false"
+  CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+  # npm: retry registry fetches with capped exponential backoff.
+  NPM_CONFIG_FETCH_RETRIES: "5"
+  NPM_CONFIG_FETCH_RETRY_MINTIMEOUT: "2000"
+  NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT: "60000"
+
 jobs:
   # ─────────────────────────────────────────────────────────────────────
   # Combined advisory-DB audit: pip-audit + npm audit + cargo audit
@@ -140,7 +165,7 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8  # stable @ 2026-03-27
 
-      - uses: swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32  # v2.9.1
+      - uses: swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4  # v2.9.1
         with:
           workspaces: studio/src-tauri -> target
 
@@ -153,8 +178,23 @@ jobs:
         # crashes with a TOML parse error on that file.
         # npm audit is bundled with the node toolchain, no install.
         run: |
-          python -m pip install --upgrade pip 'pip-audit>=2.7'
-          cargo install --locked --version '^0.22' cargo-audit
+          retry() {  # retry <max-attempts> <command...> with exponential backoff
+            local max="$1"; shift
+            local n=1 delay=5
+            until "$@"; do
+              if [ "$n" -ge "$max" ]; then
+                echo "::error::command failed after ${n} attempts: $*" >&2
+                return 1
+              fi
+              echo "attempt ${n}/${max} failed; retrying in ${delay}s: $*" >&2
+              sleep "$delay"; n=$((n + 1)); delay=$((delay * 2))
+            done
+          }
+          retry 5 python -m pip install --upgrade pip 'pip-audit>=2.7'
+          # --locked keeps the resolved tree identical to Cargo.lock; the
+          # CARGO_NET_* env above plus this outer loop survive transient
+          # crates.io connection resets without weakening that guarantee.
+          retry 5 cargo install --locked --version '^0.22' cargo-audit
 
       # ─────────────────────────────────────────────────────────────
       # Python: pip-audit
@@ -330,32 +370,60 @@ jobs:
       # ─────────────────────────────────────────────────────────────
       # OSV-Scanner: cross-ecosystem advisory DB (PyPI + npm + cargo)
       # ─────────────────────────────────────────────────────────────
+      - name: Download + verify OSV-Scanner
+        # Split out from the scan below so binary integrity is a HARD gate:
+        # a checksum mismatch (swapped release asset, the Trivy-style pivot
+        # this workflow refuses) fails the job instead of being swallowed by
+        # the scan step's continue-on-error. A download still failing after
+        # retries is transient, so we skip the scan rather than red-fail.
+        # SHA-256 verified BEFORE chmod +x / exec. Bump OSV_SHA256 in lockstep
+        # with OSV_VERSION (value from the release's osv-scanner_SHA256SUMS).
+        run: |
+          set -euo pipefail
+          OSV_VERSION="v2.0.2"
+          OSV_SHA256="3abcfd7126c453a00421487e721b296e0cb68085bd431d6cef60872774170fc8"
+          if ! curl --proto '=https' --tlsv1.2 -fsSL \
+            --retry 5 --retry-delay 3 --retry-connrefused --retry-all-errors \
+            -o /tmp/osv-scanner \
+            "https://github.com/google/osv-scanner/releases/download/${OSV_VERSION}/osv-scanner_linux_amd64"; then
+            echo "::warning::osv-scanner download failed after retries; skipping scan" >&2
+            rm -f /tmp/osv-scanner
+            exit 0   # transient availability: do not red-fail the job
+          fi
+          if ! echo "${OSV_SHA256}  /tmp/osv-scanner" | sha256sum -c -; then
+            echo "::error::osv-scanner checksum mismatch; refusing to execute" >&2
+            rm -f /tmp/osv-scanner
+            exit 1   # integrity failure: hard-fail
+          fi
+          chmod +x /tmp/osv-scanner
+          /tmp/osv-scanner --version
+
       - name: OSV-Scanner (PyPI + npm + cargo, cross-ecosystem advisories)
         # OSV's advisory feed is a superset of GitHub-Advisory + RustSec
         # + npm advisories; running it alongside the per-ecosystem audit
         # tools catches CVEs that haven't propagated to the per-ecosystem
         # DBs yet (e.g. langchain-core CVE-2025-68664 was on OSV before
         # GitHub Advisory). Single binary, one transitive resolver, all
-        # three lockfile types in one pass. Non-blocking until baselines
-        # close.
+        # three lockfile types in one pass. Binary is checksum-verified in
+        # the step above; only the advisory scan stays non-blocking until
+        # baselines close.
         continue-on-error: true
         run: |
           set +e
-          # OSV-Scanner ships a raw binary (no tarball) in v2.x.
-          curl -fsSL -o /tmp/osv-scanner \
-            https://github.com/google/osv-scanner/releases/download/v2.0.2/osv-scanner_linux_amd64
-          chmod +x /tmp/osv-scanner
-          /tmp/osv-scanner --version
-          /tmp/osv-scanner scan source \
-            --lockfile=studio/frontend/package-lock.json \
-            --lockfile=studio/src-tauri/Cargo.lock \
-            --lockfile=requirements.txt:audit-reqs/unsloth-deps.txt \
-            --lockfile=requirements.txt:audit-reqs/studio.txt \
-            --lockfile=requirements.txt:audit-reqs/no-torch-runtime.txt \
-            --lockfile=requirements.txt:audit-reqs/overrides.txt \
-            --lockfile=requirements.txt:audit-reqs/extras.txt \
-            --lockfile=requirements.txt:audit-reqs/extras-no-deps.txt \
-            --format=table 2>&1 | tee logs-osv-scanner.txt
+          if [ ! -x /tmp/osv-scanner ]; then
+            echo "osv-scanner unavailable this run; skipping scan" | tee logs-osv-scanner.txt
+          else
+            /tmp/osv-scanner scan source \
+              --lockfile=studio/frontend/package-lock.json \
+              --lockfile=studio/src-tauri/Cargo.lock \
+              --lockfile=requirements.txt:audit-reqs/unsloth-deps.txt \
+              --lockfile=requirements.txt:audit-reqs/studio.txt \
+              --lockfile=requirements.txt:audit-reqs/no-torch-runtime.txt \
+              --lockfile=requirements.txt:audit-reqs/overrides.txt \
+              --lockfile=requirements.txt:audit-reqs/extras.txt \
+              --lockfile=requirements.txt:audit-reqs/extras-no-deps.txt \
+              --format=table 2>&1 | tee logs-osv-scanner.txt
+          fi
           {
             echo "## OSV-Scanner (cross-ecosystem)"
             echo
@@ -1075,7 +1143,23 @@ jobs:
         # new-install-script gate below protects against, and we must
         # not run any third-party hook to set up the audit.
         working-directory: studio/frontend
-        run: npm ci --ignore-scripts
+        run: |
+          retry() {  # retry <max-attempts> <command...> with exponential backoff
+            local max="$1"; shift
+            local n=1 delay=5
+            until "$@"; do
+              if [ "$n" -ge "$max" ]; then
+                echo "::error::command failed after ${n} attempts: $*" >&2
+                return 1
+              fi
+              echo "attempt ${n}/${max} failed; retrying in ${delay}s: $*" >&2
+              sleep "$delay"; n=$((n + 1)); delay=$((delay * 2))
+            done
+          }
+          # --ignore-scripts is mandatory here (no third-party hook runs);
+          # the retry only re-attempts the registry fetch, it never relaxes
+          # that flag or the package-lock integrity check npm ci enforces.
+          retry 5 npm ci --ignore-scripts
 
       - name: npm audit signatures (informational)
         # Surfaces unsigned / mis-signed packages from the npm

From ff00fdd155910801f35ec5a6b616cff8cdd726e8 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Sun, 31 May 2026 05:54:46 -0300
Subject: [PATCH 032/222] Studio: add stdio MCP server support (#5863)

* Studio: add stdio MCP server support

* Fix stdio command validation and Windows quoting
---
 studio/backend/core/inference/mcp_client.py   |  64 +++++++++
 studio/backend/core/inference/tools.py        |  13 +-
 studio/backend/main.py                        |   5 +
 studio/backend/routes/mcp_servers.py          |  36 +++--
 .../features/chat/chat-mcp-servers-dialog.tsx | 129 ++++++++++++------
 5 files changed, 192 insertions(+), 55 deletions(-)

diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index a5e614899d..1a38bc8c49 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -5,6 +5,9 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
+import shlex
+import sys
 from typing import Any, Optional
 
 from loggers import get_logger
@@ -16,7 +19,55 @@ MCP_TOOL_PREFIX = "mcp__"
 _oauth_token_store = None
 
 
+def is_stdio(address: str) -> bool:
+    """A non-HTTP address is a local stdio command, e.g.
+    'npx -y @modelcontextprotocol/server-filesystem /path'."""
+    return not address.strip().lower().startswith(("http://", "https://"))
+
+
+def parse_stdio_command(address: str) -> list[str]:
+    """Split a stdio command line into argv. Shared by route validation and the
+    transport so both agree on quoting (notably Windows backslash paths)."""
+    posix = sys.platform != "win32"
+    parts = shlex.split(address, posix = posix)
+    if not posix:
+        # posix=False keeps backslash paths intact but also keeps the surrounding
+        # quotes on a token. Strip a matched pair so the argv reaches the
+        # subprocess clean ('"C:\\Program Files\\node"' -> C:\\Program Files\\node).
+        parts = [
+            p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p
+            for p in parts
+        ]
+    return parts
+
+
+def stdio_mcp_enabled() -> bool:
+    """stdio MCP servers spawn local processes as the backend user (and bypass
+    the python/terminal sandbox), so they are only allowed when the backend
+    host is the user's own machine. The Tauri desktop app sets
+    UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 (see main.py); advanced localhost /
+    self-hosted users can opt in with the same variable. It stays off for
+    Colab and any network (0.0.0.0) bind."""
+    return os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") == "1"
+
+
+# Probe timeouts for discovering a server's tool list. OAuth needs minutes for
+# first-connect/expired-token browser sign-in; stdio allows for first-run
+# package download (e.g. `npx -y ...`); HTTP fails fast.
+_HTTP_PROBE_TIMEOUT = 8.0
+_OAUTH_PROBE_TIMEOUT = 305.0
+_STDIO_PROBE_TIMEOUT = 60.0
+
+
+def probe_timeout(address: str, use_oauth: bool) -> float:
+    if use_oauth:
+        return _OAUTH_PROBE_TIMEOUT
+    return _STDIO_PROBE_TIMEOUT if is_stdio(address) else _HTTP_PROBE_TIMEOUT
+
+
 def parse_server_headers(server: dict) -> Optional[dict]:
+    """Parsed headers_json. For stdio servers this dict is the process
+    environment instead of HTTP headers (see _client)."""
     raw = server.get("headers_json")
     if not raw:
         return None
@@ -63,6 +114,19 @@ async def clear_oauth_tokens_async(url: str) -> None:
 
 def _client(url: str, headers: Optional[dict], use_oauth: bool = False):
     from fastmcp import Client
+
+    if is_stdio(url):
+        from fastmcp.client.transports import StdioTransport
+
+        parts = parse_stdio_command(url)
+        if not parts:
+            raise ValueError(f"Empty stdio command: {url!r}")
+        # stdio env vars ride the (HTTP-only) headers field. The MCP SDK merges
+        # them over its default safe env (PATH etc.), so pass them through as-is.
+        return Client(
+            StdioTransport(command = parts[0], args = parts[1:], env = headers or None)
+        )
+
     from fastmcp.client.transports import SSETransport, StreamableHttpTransport
     from fastmcp.mcp_config import infer_transport_type_from_url
 
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 9572a2169a..baf1236456 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -28,8 +28,11 @@ import urllib.request
 from core.inference.mcp_client import (
     MCP_TOOL_PREFIX,
     call_tool_sync,
+    is_stdio,
     list_tools_async,
     parse_server_headers,
+    probe_timeout,
+    stdio_mcp_enabled,
 )
 from storage import mcp_servers_db
 
@@ -568,17 +571,19 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
 
 async def get_enabled_mcp_tools() -> list[dict]:
     servers = [s for s in mcp_servers_db.list_servers() if s.get("is_enabled")]
+    # Never spawn stdio servers when stdio is disabled on this host (e.g. a DB
+    # carried over from a desktop install onto a Colab / network deployment).
+    if not stdio_mcp_enabled():
+        servers = [s for s in servers if not is_stdio(s["url"])]
     if not servers:
         return []
 
-    # OAuth probes need minutes for first-connect/expired-token browser
-    # sign-in; non-OAuth probes fail fast. Matches routes/mcp_servers.py.
     results = await asyncio.gather(
         *(
             list_tools_async(
                 url = s["url"],
                 headers = parse_server_headers(s),
-                timeout = 305.0 if s.get("use_oauth") else 8.0,
+                timeout = probe_timeout(s["url"], bool(s.get("use_oauth"))),
                 use_oauth = bool(s.get("use_oauth")),
             )
             for s in servers
@@ -630,6 +635,8 @@ def execute_tool(
             return f"Error: MCP server '{server_id}' not found"
         if not server.get("is_enabled"):
             return f"Error: MCP server '{server_id}' is disabled"
+        if is_stdio(server["url"]) and not stdio_mcp_enabled():
+            return f"Error: stdio MCP server '{server_id}' is disabled on this host"
         return call_tool_sync(
             url = server["url"],
             headers = parse_server_headers(server),
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 6b8ac438c0..b6cf58a02c 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -297,6 +297,11 @@ def _load_desktop_owner() -> dict[str, str] | None:
 
 _DESKTOP_OWNER = _load_desktop_owner()
 
+# The Tauri desktop app runs the backend on the owner's own machine, so local
+# stdio MCP servers are safe there. setdefault lets an explicit "0" opt out.
+if _DESKTOP_OWNER:
+    os.environ.setdefault("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", "1")
+
 
 def _desktop_owner() -> dict[str, str] | None:
     return _DESKTOP_OWNER
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index a7501d1691..04b776776a 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -11,8 +11,12 @@ from fastapi import APIRouter, Depends, HTTPException
 from auth.authentication import get_current_subject
 from core.inference.mcp_client import (
     clear_oauth_tokens_async,
+    is_stdio,
     list_tools_async,
     parse_server_headers,
+    parse_stdio_command,
+    probe_timeout,
+    stdio_mcp_enabled,
 )
 from models.mcp_servers import (
     McpServerCreate,
@@ -28,16 +32,22 @@ logger = structlog.get_logger(__name__)
 router = APIRouter()
 
 
-_PROBE_TIMEOUT_SECONDS = 8.0
-# When OAuth probes need to open a browser, wait long enough for the user to
-# sign in. Matches fastmcp's default OAuth callback_timeout (300 s) + slack.
-_OAUTH_PROBE_TIMEOUT_SECONDS = 305.0
-
-
 def _validate_url(url: str) -> str:
     trimmed = (url or "").strip()
     if not trimmed:
         raise HTTPException(status_code = 400, detail = "url must not be empty")
+    # When stdio is enabled on this host, a non-HTTP value is a local command.
+    # Reuse this field so stdio servers ride the existing CRUD/storage with no
+    # schema change. When stdio is disabled the value falls through to the
+    # http-only validation below, so non-HTTP input is just a bad URL (400).
+    if stdio_mcp_enabled() and is_stdio(trimmed):
+        try:
+            parts = parse_stdio_command(trimmed)
+        except ValueError as exc:
+            raise HTTPException(status_code = 400, detail = f"Invalid command: {exc}")
+        if not parts or not parts[0].strip():
+            raise HTTPException(status_code = 400, detail = "command must not be empty")
+        return trimmed
     parsed = urlparse(trimmed)
     if parsed.scheme not in ("http", "https"):
         raise HTTPException(
@@ -180,15 +190,19 @@ async def refresh_mcp_server_tools(
     server = mcp_servers_db.get_server(server_id)
     if not server:
         raise HTTPException(status_code = 404, detail = "MCP server not found")
+    # Refresh uses the stored address, so re-check the stdio gate here too: a
+    # stdio row from a desktop DB must not spawn on a hosted/network host.
+    if is_stdio(server["url"]) and not stdio_mcp_enabled():
+        raise HTTPException(
+            status_code = 400, detail = "stdio MCP servers are disabled on this host"
+        )
 
     use_oauth = bool(server.get("use_oauth"))
     try:
         tools = await list_tools_async(
             url = server["url"],
             headers = parse_server_headers(server),
-            timeout = _OAUTH_PROBE_TIMEOUT_SECONDS
-            if use_oauth
-            else _PROBE_TIMEOUT_SECONDS,
+            timeout = probe_timeout(server["url"], use_oauth),
             use_oauth = use_oauth,
         )
     except Exception as exc:  # noqa: BLE001 — surface transport+timeout errors to UI
@@ -212,9 +226,7 @@ async def test_mcp_server(
         tools = await list_tools_async(
             url = url,
             headers = headers,
-            timeout = _OAUTH_PROBE_TIMEOUT_SECONDS
-            if payload.use_oauth
-            else _PROBE_TIMEOUT_SECONDS,
+            timeout = probe_timeout(url, payload.use_oauth),
             use_oauth = payload.use_oauth,
         )
     except Exception as exc:  # noqa: BLE001
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index 35b5aca64c..dfb50b5bc2 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -66,23 +66,40 @@ function headersToObject(rows: HeaderRow[]): Record<string, string> | undefined
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
-function isValidUrl(url: string): boolean {
-  const trimmed = url.trim();
+// A non-HTTP address is a local stdio command. Case-insensitive to match the
+// backend's is_stdio(), so all layers split http-vs-command identically.
+function isHttpAddress(value: string): boolean {
+  const trimmed = value.trim().toLowerCase();
+  return trimmed.startsWith("http://") || trimmed.startsWith("https://");
+}
+
+function isValidAddress(value: string): boolean {
+  const trimmed = value.trim();
   if (!trimmed) return false;
-  try {
-    const parsed = new URL(trimmed);
-    return parsed.protocol === "http:" || parsed.protocol === "https:";
-  } catch {
-    return false;
+  if (isHttpAddress(trimmed)) {
+    try {
+      const parsed = new URL(trimmed);
+      return parsed.protocol === "http:" || parsed.protocol === "https:";
+    } catch {
+      return false;
+    }
   }
+  // Anything else is treated as a local command (stdio); the backend gates
+  // whether stdio servers are allowed on this host. Reject other URL schemes
+  // only when the command itself is a URL; "://" is fine inside an argument
+  // (e.g. a database connection string passed to the server).
+  return !trimmed.split(/\s+/)[0].includes("://");
 }
 
 function HeadersEditor({
   rows,
   onChange,
+  stdio,
 }: {
   rows: HeaderRow[];
   onChange: (rows: HeaderRow[]) => void;
+  // stdio servers reuse this editor for environment variables instead of headers.
+  stdio: boolean;
 }) {
   const update = (id: string, patch: Partial<HeaderRow>) =>
     onChange(rows.map((row) => (row.id === id ? { ...row, ...patch } : row)));
@@ -91,19 +108,41 @@ function HeadersEditor({
   const remove = (id: string) =>
     onChange(rows.filter((row) => row.id !== id));
 
+  const copy = stdio
+    ? {
+        label: "Environment variables",
+        add: "Add variable",
+        keyPlaceholder: "Variable name",
+        valuePlaceholder: "Variable value",
+        remove: "Remove variable",
+      }
+    : {
+        label: "Custom headers",
+        add: "Add header",
+        keyPlaceholder: "Header name",
+        valuePlaceholder: "Header value",
+        remove: "Remove header",
+      };
+
   return (
     <>
       <div className="flex items-center justify-between">
-        <Label className="text-sm">Custom headers</Label>
+        <Label className="text-sm">{copy.label}</Label>
         <Button type="button" variant="ghost" size="sm" onClick={add}>
           <HugeiconsIcon icon={PlusSignIcon} size={14} />
-          Add header
+          {copy.add}
         </Button>
       </div>
       {rows.length === 0 ? (
         <div className="text-xs text-muted-foreground">
-          Optional. Add an <code>Authorization</code> header here for servers
-          that require auth.
+          {stdio ? (
+            "Optional. Environment variables passed to the server process."
+          ) : (
+            <>
+              Optional. Add an <code>Authorization</code> header here for servers
+              that require auth.
+            </>
+          )}
         </div>
       ) : (
         <div className="flex flex-col gap-2">
@@ -111,12 +150,12 @@ function HeadersEditor({
             <div key={row.id} className="flex items-center gap-2">
               <Input
                 value={row.key}
-                placeholder="Header name"
+                placeholder={copy.keyPlaceholder}
                 onChange={(e) => update(row.id, { key: e.target.value })}
               />
               <Input
                 value={row.value}
-                placeholder="Header value"
+                placeholder={copy.valuePlaceholder}
                 onChange={(e) => update(row.id, { value: e.target.value })}
               />
               <Button
@@ -124,7 +163,7 @@ function HeadersEditor({
                 variant="ghost"
                 size="icon"
                 onClick={() => remove(row.id)}
-                aria-label="Remove header"
+                aria-label={copy.remove}
               >
                 <HugeiconsIcon icon={Delete02Icon} size={14} />
               </Button>
@@ -199,8 +238,8 @@ export function ChatMcpServersDialog({
 
   async function testConnection() {
     const trimmedUrl = form.url.trim();
-    if (!isValidUrl(trimmedUrl)) {
-      toast.error("Enter a valid http:// or https:// URL first");
+    if (!isValidAddress(trimmedUrl)) {
+      toast.error("Enter an http(s):// URL or a local command first");
       return;
     }
     setTesting(true);
@@ -236,11 +275,11 @@ export function ChatMcpServersDialog({
       return;
     }
     if (!trimmedUrl) {
-      toast.error("URL is required");
+      toast.error("URL or command is required");
       return;
     }
-    if (!isValidUrl(trimmedUrl)) {
-      toast.error("URL must start with http:// or https://");
+    if (!isValidAddress(trimmedUrl)) {
+      toast.error("Enter an http(s):// URL or a local command");
       return;
     }
     setSaving(true);
@@ -331,6 +370,9 @@ export function ChatMcpServersDialog({
   }
 
   const showForm = view.kind !== "list";
+  // A local stdio command uses env vars, not headers or OAuth.
+  const addressIsCommand =
+    form.url.trim() !== "" && !isHttpAddress(form.url);
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
@@ -338,7 +380,7 @@ export function ChatMcpServersDialog({
         <DialogHeader>
           <DialogTitle>MCP Servers</DialogTitle>
           <DialogDescription>
-            Register remote MCP servers.
+            Register remote (HTTP) or local (stdio command) MCP servers.
           </DialogDescription>
         </DialogHeader>
 
@@ -356,40 +398,47 @@ export function ChatMcpServersDialog({
               />
             </div>
             <div className="grid gap-2">
-              <Label htmlFor="mcp-url">URL</Label>
+              <Label htmlFor="mcp-url">URL or command</Label>
               <Input
                 id="mcp-url"
                 value={form.url}
                 onChange={(e) =>
                   setForm((prev) => ({ ...prev, url: e.target.value }))
                 }
-                placeholder="https://example.com/mcp"
+                placeholder="https://example.com/mcp or npx -y @modelcontextprotocol/server-filesystem /tmp"
               />
+              <span className="text-xs text-muted-foreground">
+                An http(s) URL for a remote server, or a local command to run an
+                stdio server (desktop app only).
+              </span>
             </div>
 
-            <div className="flex items-start justify-between gap-3">
-              <div className="flex flex-col gap-0.5">
-                <Label className="text-sm" htmlFor="mcp-oauth">
-                  Use OAuth sign-in
-                </Label>
-                <span className="text-xs text-muted-foreground">
-                  For servers that require browser-based authentication
-                  (GitHub, Linear, etc.). A browser window will open on first
-                  connect.
-                </span>
+            {!addressIsCommand && (
+              <div className="flex items-start justify-between gap-3">
+                <div className="flex flex-col gap-0.5">
+                  <Label className="text-sm" htmlFor="mcp-oauth">
+                    Use OAuth sign-in
+                  </Label>
+                  <span className="text-xs text-muted-foreground">
+                    For servers that require browser-based authentication
+                    (GitHub, Linear, etc.). A browser window will open on first
+                    connect.
+                  </span>
+                </div>
+                <Switch
+                  id="mcp-oauth"
+                  checked={form.useOauth}
+                  onCheckedChange={(useOauth) =>
+                    setForm((prev) => ({ ...prev, useOauth }))
+                  }
+                />
               </div>
-              <Switch
-                id="mcp-oauth"
-                checked={form.useOauth}
-                onCheckedChange={(useOauth) =>
-                  setForm((prev) => ({ ...prev, useOauth }))
-                }
-              />
-            </div>
+            )}
 
             <HeadersEditor
               rows={form.headers}
               onChange={(headers) => setForm((prev) => ({ ...prev, headers }))}
+              stdio={addressIsCommand}
             />
 
             <div className="flex items-center justify-between gap-2 pt-2">

From 76574fb8da5814fd7ca60c9fc5548151501e0c03 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Sun, 31 May 2026 05:55:09 -0300
Subject: [PATCH 033/222] studio/frontend: fix MCP dialog overflow on long URLs
 (#5864)

---
 studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index dfb50b5bc2..b377e7a88e 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -464,7 +464,7 @@ export function ChatMcpServersDialog({
             </div>
           </div>
         ) : (
-          <div className="flex flex-col gap-3">
+          <div className="flex min-w-0 flex-col gap-3">
             <div className="flex justify-end">
               <Button size="sm" onClick={startCreate}>
                 <HugeiconsIcon icon={PlusSignIcon} size={14} />

From 6cc2220e7829b4975573ed206dfd6d9341cd6b30 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 02:23:58 -0700
Subject: [PATCH 034/222] Studio: clearer error for diffusion GGUFs loaded as
 chat models (#5857)

Classify llama-server startup failures so diffusion/image GGUFs (FLUX, Qwen-Image, LTX, ERNIE-Image, Z-Image, ...) point users to the Images page instead of a misleading out-of-memory error. Other unknown architectures get a precise unsupported message; Ollama and OOM fallbacks are preserved.

Architecture is matched exactly against general.architecture, covering the arches Unsloth ships as GGUF: flux, qwen_image, ltxv, wan, lumina2.

Fixes #5842.
---
 studio/backend/core/inference/llama_cpp.py    | 128 +++++++++++++---
 ..._llama_cpp_start_failure_classification.py | 144 ++++++++++++++++++
 2 files changed, 248 insertions(+), 24 deletions(-)
 create mode 100644 studio/backend/tests/test_llama_cpp_start_failure_classification.py

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 4b17f495ea..cce95fc34c 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -2591,6 +2591,105 @@ class LlamaCppBackend:
 
     # ── Lifecycle ─────────────────────────────────────────────────
 
+    # GGUF ``general.architecture`` values for diffusion / image models.
+    # llama.cpp proper has no such architectures, so loading one as a chat
+    # model dies with "unknown model architecture: '<arch>'". These match
+    # the patched stable-diffusion.cpp / ComfyUI-GGUF enums (LLM_ARCH_FLUX,
+    # LLM_ARCH_QWEN_IMAGE, ...). Unsloth publishes FLUX and Qwen-Image GGUFs
+    # under https://huggingface.co/collections/unsloth/unsloth-diffusion-ggufs.
+    # Matched exactly (not as a substring) so a chat arch merely containing a
+    # short token like "wan"/"sd1" (e.g. "taiwan") is not misrouted to Images.
+    _DIFFUSION_ARCHES = frozenset(
+        (
+            "qwen_image",
+            "flux",
+            "sd1",
+            "sdxl",
+            "sd3",
+            "aura",
+            "hidream",
+            "cosmos",
+            "ltxv",
+            "hyvid",
+            "wan",
+            "lumina2",
+        )
+    )
+
+    @staticmethod
+    def _classify_llama_start_failure(
+        output: str,
+        gguf_path: Optional[str],
+        model_identifier: Optional[str],
+    ) -> str:
+        """Explain *why* llama-server failed to start, from its output.
+
+        Several distinct failures all otherwise collapse into the same
+        opaque "invalid GGUF or out of memory" message. The worst case is
+        a diffusion / image GGUF (FLUX, Qwen-Image, ...) loaded as a chat
+        model: the file is perfectly valid and there is plenty of memory,
+        but llama.cpp has no such architecture, so the user is told to free
+        memory that was never the problem (issue #5842). Pick the most
+        specific message the captured output supports.
+        """
+        lowered = (output or "").lower()
+
+        # Detect Ollama source up front so the arch branch can keep the
+        # Ollama hint instead of the generic "unsupported arch" message.
+        gguf = gguf_path or ""
+        is_ollama = (
+            ".studio_links" in gguf
+            or os.sep + "ollama_links" + os.sep in gguf
+            or os.sep + ".cache" + os.sep + "ollama" + os.sep in gguf
+            or (model_identifier or "").startswith("ollama/")
+        )
+
+        # "unknown model architecture: '<arch>'": diffusion -> Images page,
+        # Ollama -> Ollama hint, else a precise "unsupported" message. Exact
+        # match so chat archs are never misrouted.
+        arch_match = re.search(r"unknown model architecture:\s*'([^']+)'", lowered)
+        if arch_match:
+            arch = arch_match.group(1)
+            if arch in LlamaCppBackend._DIFFUSION_ARCHES:
+                return (
+                    f"'{arch}' is a diffusion (image-generation) GGUF, which "
+                    "llama-server cannot run as a chat/completion model. Use "
+                    "Studio's Images page to generate with local diffusion "
+                    "GGUFs such as FLUX and Qwen-Image."
+                )
+            if is_ollama:
+                return (
+                    "Some Ollama models do not work with llama.cpp. Try a "
+                    "different model, or use this model directly through "
+                    "Ollama instead."
+                )
+            return (
+                f"llama.cpp does not support this GGUF's model architecture "
+                f"('{arch}'). The file is valid, but this model type cannot "
+                "be run with llama-server."
+            )
+
+        # Other Ollama compat failures that do not name an arch. Only when
+        # the output shows a GGUF compat issue, not OOM / missing binaries.
+        if is_ollama:
+            gguf_compat_hints = (
+                "key not found",
+                "unknown model architecture",
+                "failed to load model",
+            )
+            if any(h in lowered for h in gguf_compat_hints):
+                return (
+                    "Some Ollama models do not work with llama.cpp. Try a "
+                    "different model, or use this model directly through "
+                    "Ollama instead."
+                )
+
+        # Fallback: genuinely unknown failure (OOM, missing binary, ...).
+        return (
+            "llama-server failed to start. "
+            "Check that the GGUF file is valid and you have enough memory."
+        )
+
     def load_model(
         self,
         *,
@@ -3383,31 +3482,12 @@ class LlamaCppBackend:
                 # Wait for llama-server to become healthy
                 if not self._wait_for_health(timeout = 600.0):
                     self._kill_process()
-                    _gguf = gguf_path or ""
-                    _is_ollama = (
-                        ".studio_links" in _gguf
-                        or os.sep + "ollama_links" + os.sep in _gguf
-                        or os.sep + ".cache" + os.sep + "ollama" + os.sep in _gguf
-                        or (self._model_identifier or "").startswith("ollama/")
-                    )
-                    # Only show the Ollama-specific message when the server
-                    # output indicates a GGUF compatibility issue, not for
-                    # unrelated failures like OOM or missing binaries.
-                    if _is_ollama:
-                        _output = "\n".join(self._stdout_lines[-50:]).lower()
-                        _gguf_compat_hints = (
-                            "key not found",
-                            "unknown model architecture",
-                            "failed to load model",
-                        )
-                        if any(h in _output for h in _gguf_compat_hints):
-                            raise RuntimeError(
-                                "Some Ollama models do not work with llama.cpp. "
-                                "Try a different model, or use this model directly through Ollama instead."
-                            )
                     raise RuntimeError(
-                        "llama-server failed to start. "
-                        "Check that the GGUF file is valid and you have enough memory."
+                        self._classify_llama_start_failure(
+                            "\n".join(self._stdout_lines[-50:]),
+                            gguf_path,
+                            self._model_identifier,
+                        )
                     )
 
                 self._healthy = True
diff --git a/studio/backend/tests/test_llama_cpp_start_failure_classification.py b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
new file mode 100644
index 0000000000..e647ff2c7d
--- /dev/null
+++ b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for LlamaCppBackend._classify_llama_start_failure.
+
+When llama-server exits before becoming healthy, load_model turns its
+captured stdout/stderr into a user-facing reason. A diffusion / image
+GGUF (FLUX, Qwen-Image, ...) is a valid file with plenty of memory, so
+the generic "invalid file or out of memory" message is actively
+misleading (issue #5842). These tests pin the classification.
+"""
+
+from __future__ import annotations
+
+import sys
+import types as _types
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+# Match the stubbing pattern in sibling tests so the module imports in a
+# lightweight env without fastapi.
+_loggers_stub = _types.ModuleType("loggers")
+_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
+sys.modules.setdefault("loggers", _loggers_stub)
+# Give the structlog stub a real get_logger: a bare ModuleType poisons
+# sys.modules for later tests that call structlog.get_logger at import time.
+_structlog_stub = _types.ModuleType("structlog")
+_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger(
+    "structlog"
+)
+sys.modules.setdefault("structlog", _structlog_stub)
+if not hasattr(sys.modules["structlog"], "get_logger"):
+    sys.modules["structlog"].get_logger = _structlog_stub.get_logger
+
+from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
+
+_classify = LlamaCppBackend._classify_llama_start_failure
+
+# Real llama-server failure lines (lower-cased downstream anyway).
+_QWEN_IMAGE_OUT = (
+    "load_model: loading model 'qwen-image-edit-2511-Q4_K_M.gguf'\n"
+    "llama_model_load: error loading model: unknown model architecture: 'qwen_image'\n"
+    "llama_model_load_from_file_impl: failed to load model"
+)
+_OOM_OUT = (
+    "ggml_backend_cuda_buffer_type_alloc_buffer: allocating 12000.00 MiB on "
+    "device 0: cudaMalloc failed: out of memory"
+)
+
+
+class TestDiffusionArchitectures:
+    def test_qwen_image_routes_to_images_page(self):
+        msg = _classify(_QWEN_IMAGE_OUT, "/models/qwen-image.gguf", "local/qwen-image")
+        assert "diffusion" in msg.lower()
+        assert "Images page" in msg
+        assert "qwen_image" in msg
+        # Must NOT keep blaming memory / file validity.
+        assert "out of memory" not in msg.lower()
+        assert "enough memory" not in msg.lower()
+
+    # Parametrize over the production set so new arches are auto-covered.
+    @pytest.mark.parametrize("arch", sorted(LlamaCppBackend._DIFFUSION_ARCHES))
+    def test_every_diffusion_arch_is_recognised(self, arch):
+        out = f"error loading model: unknown model architecture: '{arch}'"
+        msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
+        assert "diffusion" in msg.lower()
+        assert "Images page" in msg
+        assert arch in msg
+
+
+class TestUnsupportedNonDiffusionArchitecture:
+    def test_unknown_llm_arch_says_unsupported_not_oom(self):
+        out = "error loading model: unknown model architecture: 'some_new_llm'"
+        msg = _classify(out, "/models/x.gguf", "local/x")
+        assert "some_new_llm" in msg
+        assert "architecture" in msg.lower()
+        # Specific, not the misleading memory message.
+        assert "enough memory" not in msg.lower()
+        assert "diffusion" not in msg.lower()
+
+    # Exact match: a chat arch merely containing a diffusion token (wan,
+    # sd1, flux, ...) must not be routed to the Images page.
+    @pytest.mark.parametrize(
+        "arch",
+        [
+            "taiwan",  # contains "wan"
+            "swan_llm",  # contains "wan"
+            "fluxion",  # contains "flux"
+            "sd1234",  # contains "sd1"
+            "sd3_chat",  # contains "sd3"
+            "aura2_text",  # contains "aura"
+            "cosmos_reason",  # contains "cosmos"
+            "qwen_image_text",  # contains "qwen_image"
+        ],
+    )
+    def test_arch_containing_diffusion_token_is_not_misrouted(self, arch):
+        out = f"error loading model: unknown model architecture: '{arch}'"
+        msg = _classify(out, f"/models/{arch}.gguf", f"local/{arch}")
+        assert arch in msg
+        assert "does not support" in msg.lower()
+        assert "diffusion" not in msg.lower()
+        assert "Images page" not in msg
+
+
+class TestOllamaAndFallback:
+    _OLLAMA_GGUF = (
+        f"/home/u/.ollama{__import__('os').sep}ollama_links"
+        f"{__import__('os').sep}m.gguf"
+    )
+
+    def test_ollama_compat_message_still_works(self):
+        out = "llama_model_load: error loading model: key not found"
+        msg = _classify(out, self._OLLAMA_GGUF, "ollama/llama3")
+        assert "Ollama" in msg
+
+    def test_ollama_unknown_arch_keeps_ollama_guidance(self):
+        # Ollama + non-diffusion unknown arch keeps the Ollama hint, not the
+        # generic llama.cpp "unsupported" message.
+        out = "error loading model: unknown model architecture: 'some_new_llm'"
+        msg = _classify(out, self._OLLAMA_GGUF, "ollama/some-new")
+        assert "Ollama" in msg
+        assert "directly through Ollama" in msg
+        assert "does not support" not in msg.lower()
+
+    def test_ollama_diffusion_arch_still_routes_to_images(self):
+        # Diffusion routing wins over the Ollama hint.
+        out = "error loading model: unknown model architecture: 'flux'"
+        msg = _classify(out, self._OLLAMA_GGUF, "ollama/flux")
+        assert "diffusion" in msg.lower()
+        assert "Images page" in msg
+
+    def test_generic_oom_keeps_memory_message(self):
+        msg = _classify(_OOM_OUT, "/models/big.gguf", "local/big")
+        assert "enough memory" in msg.lower()
+        assert "diffusion" not in msg.lower()
+
+    def test_empty_output_is_safe(self):
+        msg = _classify("", None, None)
+        assert "llama-server failed to start" in msg

From 4b6a733fc3b7e38794a4e5d58de4694163add7d1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 04:38:52 -0700
Subject: [PATCH 035/222] Studio: harden stdio MCP gating and fix transport
 edge cases (#5892)

* Studio: harden stdio MCP gating and fix transport edge cases

- Gate the Data Recipe stdio path behind UNSLOTH_STUDIO_ALLOW_STDIO_MCP so a hosted deployment cannot spawn local processes through recipes
- Enforce the gate inside _client() so the transport sink cannot spawn when disabled
- keep_alive=False so stdio probes/calls do not leave orphan subprocesses
- Force OAuth off for stdio servers on create and update
- Drop stored headers when a server switches transport type
- Reject a command whose first token is a URL scheme
- Add MCP gate and improvement tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* tests: skip Data Recipe stdio tests when data_designer is absent

The data_designer plugin is only installed in the Studio test job, so guard
the two build_mcp_providers tests with importorskip so the core matrix skips
them instead of failing on ModuleNotFoundError.

---------

Co-authored-by: Daniel Han <michaelhan2050@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/data_recipe/service.py    |   9 +
 studio/backend/core/inference/mcp_client.py   |  15 +-
 studio/backend/routes/data_recipe/mcp.py      |  10 +
 studio/backend/routes/mcp_servers.py          |  25 +-
 .../tests/test_mcp_stdio_improvements.py      | 236 +++++++++++
 studio/backend/tests/test_mcp_stdio_pr5863.py | 367 ++++++++++++++++++
 6 files changed, 658 insertions(+), 4 deletions(-)
 create mode 100644 studio/backend/tests/test_mcp_stdio_improvements.py
 create mode 100644 studio/backend/tests/test_mcp_stdio_pr5863.py

diff --git a/studio/backend/core/data_recipe/service.py b/studio/backend/core/data_recipe/service.py
index b4ec0ccd94..85b567885f 100644
--- a/studio/backend/core/data_recipe/service.py
+++ b/studio/backend/core/data_recipe/service.py
@@ -176,12 +176,21 @@ def build_mcp_providers(
 ) -> list:
     from data_designer.config.mcp import LocalStdioMCPProvider, MCPProvider  # pyright: ignore[reportMissingImports]
 
+    # Same gate as the chat MCP path: stdio providers spawn a local subprocess,
+    # so only build them when this host allows it (desktop / explicit opt-in).
+    # Skip them otherwise so a recipe carried onto a hosted host cannot spawn.
+    from core.inference.mcp_client import stdio_mcp_enabled
+
+    stdio_allowed = stdio_mcp_enabled()
+
     providers: list[MCPProvider | LocalStdioMCPProvider] = []
     for provider in recipe.get("mcp_providers", []):
         if not isinstance(provider, dict):
             continue
         provider_type = provider.get("provider_type")
         if provider_type == "stdio":
+            if not stdio_allowed:
+                continue
             env = provider.get("env")
             if not isinstance(env, dict):
                 env = {}
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index 1a38bc8c49..2ed1a630dc 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -116,15 +116,24 @@ def _client(url: str, headers: Optional[dict], use_oauth: bool = False):
     from fastmcp import Client
 
     if is_stdio(url):
+        # Belt-and-suspenders: never spawn unless stdio is enabled on this host.
+        if not stdio_mcp_enabled():
+            raise PermissionError("stdio MCP servers are disabled on this host")
         from fastmcp.client.transports import StdioTransport
 
         parts = parse_stdio_command(url)
         if not parts:
             raise ValueError(f"Empty stdio command: {url!r}")
-        # stdio env vars ride the (HTTP-only) headers field. The MCP SDK merges
-        # them over its default safe env (PATH etc.), so pass them through as-is.
+        # env vars ride the headers field (merged over the SDK's safe default env).
+        # keep_alive=False tears the subprocess down on exit, so a one-shot
+        # probe/tool call never leaves an orphan process.
         return Client(
-            StdioTransport(command = parts[0], args = parts[1:], env = headers or None)
+            StdioTransport(
+                command = parts[0],
+                args = parts[1:],
+                env = headers or None,
+                keep_alive = False,
+            )
         )
 
     from fastmcp.client.transports import SSETransport, StreamableHttpTransport
diff --git a/studio/backend/routes/data_recipe/mcp.py b/studio/backend/routes/data_recipe/mcp.py
index 1f5c0f34e0..7184934ce9 100644
--- a/studio/backend/routes/data_recipe/mcp.py
+++ b/studio/backend/routes/data_recipe/mcp.py
@@ -36,8 +36,18 @@ def list_mcp_tools(payload: McpToolsListRequest) -> McpToolsListResponse:
     providers: list[McpToolsProviderResult] = []
     tool_to_providers: dict[str, list[str]] = defaultdict(list)
 
+    from core.inference.mcp_client import stdio_mcp_enabled
+
     for provider_payload in payload.mcp_providers:
         provider_name = str(provider_payload.get("name", "")).strip()
+        if provider_payload.get("provider_type") == "stdio" and not stdio_mcp_enabled():
+            providers.append(
+                McpToolsProviderResult(
+                    name = provider_name,
+                    error = "Local (stdio) MCP servers are disabled on this host.",
+                )
+            )
+            continue
         built = build_mcp_providers({"mcp_providers": [provider_payload]})
         if len(built) != 1:
             providers.append(
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 04b776776a..6c63bc20ca 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -47,6 +47,14 @@ def _validate_url(url: str) -> str:
             raise HTTPException(status_code = 400, detail = f"Invalid command: {exc}")
         if not parts or not parts[0].strip():
             raise HTTPException(status_code = 400, detail = "command must not be empty")
+        if "://" in parts[0]:
+            # A URL-scheme first token is a mistyped URL, not a command. Reject
+            # it cleanly instead of exec-ing it (mirrors the frontend check).
+            raise HTTPException(
+                status_code = 400,
+                detail = "Enter an http(s):// URL, or a local command whose "
+                "first token is an executable (not a URL).",
+            )
         return trimmed
     parsed = urlparse(trimmed)
     if parsed.scheme not in ("http", "https"):
@@ -101,6 +109,9 @@ async def create_mcp_server(
         raise HTTPException(status_code = 400, detail = "display_name must not be empty")
     url = _validate_url(payload.url)
     headers = _normalize_headers(payload.headers)
+    # OAuth is HTTP-only; force it off for stdio commands so a stale flag can't
+    # push the probe onto the 305s OAuth timeout. Backend is the enforcer.
+    use_oauth = payload.use_oauth and not is_stdio(url)
 
     server_id = uuid.uuid4().hex[:16]
     mcp_servers_db.create_server(
@@ -109,7 +120,7 @@ async def create_mcp_server(
         url = url,
         headers_json = json.dumps(headers) if headers else None,
         is_enabled = payload.is_enabled,
-        use_oauth = payload.use_oauth,
+        use_oauth = use_oauth,
     )
     return _row_to_response(mcp_servers_db.get_server(server_id))
 
@@ -142,6 +153,9 @@ def _changes_from_payload(payload: McpServerUpdate) -> dict:
                 status_code = 400, detail = "use_oauth must be true or false"
             )
         changes["use_oauth"] = payload.use_oauth
+    # stdio is OAuth-less: drop a stale OAuth flag when switching to a command.
+    if "url" in changes and is_stdio(changes["url"]):
+        changes["use_oauth"] = False
     return changes
 
 
@@ -157,6 +171,15 @@ async def update_mcp_server(
     changes = _changes_from_payload(payload)
     if not changes:
         raise HTTPException(status_code = 400, detail = "No fields to update")
+    # headers == HTTP headers (remote) or env vars (stdio). On a transport-type
+    # switch with no new headers, drop the old ones so env secrets are not
+    # re-sent as HTTP headers (or vice versa).
+    if (
+        "url" in changes
+        and is_stdio(changes["url"]) != is_stdio(old["url"])
+        and "headers_json" not in changes
+    ):
+        changes["headers_json"] = None
     # Clear persisted OAuth tokens when the URL changes or OAuth is
     # disabled; fastmcp keys tokens by URL and would otherwise let a
     # re-pointed server silently inherit the old account's credentials.
diff --git a/studio/backend/tests/test_mcp_stdio_improvements.py b/studio/backend/tests/test_mcp_stdio_improvements.py
new file mode 100644
index 0000000000..e980e6a057
--- /dev/null
+++ b/studio/backend/tests/test_mcp_stdio_improvements.py
@@ -0,0 +1,236 @@
+"""Tests for the proposed PR #5863 improvements.
+
+Covers: _client() self-gating + keep_alive, OAuth normalised off for stdio
+(create + update), env/header dropped on a transport-type switch, and the
+backend rejecting a command whose first token is a URL scheme.
+
+Run from studio/backend:  python -m pytest tests/test_mcp_stdio_improvements.py -q
+"""
+
+import asyncio
+
+import pytest
+from fastapi import HTTPException
+
+from core.inference import mcp_client
+from storage import mcp_servers_db
+
+
+def _reset_db(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(mcp_servers_db, "_schema_ready", False)
+
+
+def _enable(monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", "1")
+
+
+def _disable(monkeypatch):
+    monkeypatch.delenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", raising = False)
+
+
+# ── P1: _client() self-gates the stdio sink ─────────────────────────
+
+
+def test_client_refuses_stdio_when_disabled(monkeypatch):
+    _disable(monkeypatch)
+    with pytest.raises(PermissionError):
+        mcp_client._client("npx -y server /tmp", None)
+
+
+def test_client_builds_stdio_when_enabled_without_spawning(monkeypatch):
+    _enable(monkeypatch)
+    # Constructing the Client must not spawn the subprocess (spawn happens on
+    # __aenter__); we only assert it builds.
+    client = mcp_client._client("npx -y server /tmp", {"K": "v"})
+    assert client is not None
+
+
+def test_client_http_unaffected_by_gate(monkeypatch):
+    _disable(monkeypatch)
+    assert mcp_client._client("https://example.com/mcp", None) is not None
+
+
+# ── P3: OAuth normalised off for stdio (create + update) ────────────
+
+
+def test_create_forces_oauth_off_for_stdio(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerCreate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    resp = asyncio.run(
+        routes_mcp.create_mcp_server(
+            McpServerCreate(
+                display_name = "FS", url = "npx -y server /tmp", use_oauth = True
+            ),
+            current_subject = "u",
+        )
+    )
+    assert resp.use_oauth is False
+    assert mcp_servers_db.get_server(resp.id)["use_oauth"] == 0
+
+
+def test_create_keeps_oauth_for_http(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerCreate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    resp = asyncio.run(
+        routes_mcp.create_mcp_server(
+            McpServerCreate(display_name = "GH", url = "https://gh/mcp", use_oauth = True),
+            current_subject = "u",
+        )
+    )
+    assert resp.use_oauth is True
+
+
+def test_update_url_to_stdio_clears_oauth(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerUpdate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
+    monkeypatch.setattr(
+        routes_mcp, "clear_oauth_tokens_async", lambda *a, **k: asyncio.sleep(0)
+    )
+    mcp_servers_db.create_server(
+        id = "s1", display_name = "A", url = "https://a/mcp", use_oauth = True
+    )
+    resp = asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1", McpServerUpdate(url = "npx -y server /tmp"), current_subject = "u"
+        )
+    )
+    assert resp.use_oauth is False
+
+
+# ── P4: env/headers dropped on a transport-type switch ──────────────
+
+
+def test_switch_stdio_to_http_drops_env(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerUpdate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    mcp_servers_db.create_server(
+        id = "s1",
+        display_name = "A",
+        url = "npx server",
+        headers_json = '{"API_KEY": "secret"}',
+    )
+    resp = asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1", McpServerUpdate(url = "https://remote/mcp"), current_subject = "u"
+        )
+    )
+    # the stdio env must NOT survive as HTTP headers on the remote endpoint
+    assert resp.headers == {}
+    assert mcp_servers_db.get_server("s1")["headers_json"] is None
+
+
+def test_switch_keeps_explicitly_supplied_headers(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerUpdate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    mcp_servers_db.create_server(
+        id = "s1",
+        display_name = "A",
+        url = "npx server",
+        headers_json = '{"API_KEY": "secret"}',
+    )
+    resp = asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1",
+            McpServerUpdate(
+                url = "https://remote/mcp", headers = {"Authorization": "Bearer new"}
+            ),
+            current_subject = "u",
+        )
+    )
+    assert resp.headers == {"Authorization": "Bearer new"}
+
+
+def test_same_transport_edit_keeps_headers(tmp_path, monkeypatch):
+    import routes.mcp_servers as routes_mcp
+    from models.mcp_servers import McpServerUpdate
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    mcp_servers_db.create_server(
+        id = "s1",
+        display_name = "A",
+        url = "npx server",
+        headers_json = '{"API_KEY": "secret"}',
+    )
+    # editing only the display name (still stdio) must not wipe env vars
+    resp = asyncio.run(
+        routes_mcp.update_mcp_server(
+            "s1", McpServerUpdate(display_name = "B"), current_subject = "u"
+        )
+    )
+    assert resp.headers == {"API_KEY": "secret"}
+
+
+# ── P5: reject a command whose first token is a URL scheme ───────────
+
+
+def test_validate_url_rejects_url_scheme_command_when_enabled(monkeypatch):
+    from routes.mcp_servers import _validate_url
+
+    _enable(monkeypatch)
+    for bad in ["ftp://host/x", "file:///etc/passwd", "ws://h/y"]:
+        with pytest.raises(HTTPException) as exc:
+            _validate_url(bad)
+        assert exc.value.status_code == 400
+
+
+def test_validate_url_allows_url_in_argument(monkeypatch):
+    from routes.mcp_servers import _validate_url
+
+    _enable(monkeypatch)
+    # :// inside an ARGUMENT (not the first token) is still a valid command
+    assert _validate_url("npx server --url https://x/mcp") == (
+        "npx server --url https://x/mcp"
+    )
+
+
+# ── P6: Data Recipe stdio path obeys the same host gate ─────────────
+# build_mcp_providers needs the data_designer plugin, which is only installed in
+# the Studio test job; skip there rather than fail the core matrix.
+
+_STDIO_RECIPE = {
+    "mcp_providers": [
+        {
+            "provider_type": "stdio",
+            "name": "fs",
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+            "env": {},
+        }
+    ]
+}
+
+
+def test_data_recipe_skips_stdio_when_disabled(monkeypatch):
+    pytest.importorskip("data_designer")
+    _disable(monkeypatch)
+    from core.data_recipe.service import build_mcp_providers
+
+    # gate off -> the stdio provider is dropped (no subprocess can be spawned)
+    assert build_mcp_providers(_STDIO_RECIPE) == []
+
+
+def test_data_recipe_builds_stdio_when_enabled(monkeypatch):
+    pytest.importorskip("data_designer")
+    _enable(monkeypatch)
+    from core.data_recipe.service import build_mcp_providers
+
+    built = build_mcp_providers(_STDIO_RECIPE)
+    assert len(built) == 1  # constructed (not spawned) only when enabled
diff --git a/studio/backend/tests/test_mcp_stdio_pr5863.py b/studio/backend/tests/test_mcp_stdio_pr5863.py
new file mode 100644
index 0000000000..d9a9510378
--- /dev/null
+++ b/studio/backend/tests/test_mcp_stdio_pr5863.py
@@ -0,0 +1,367 @@
+"""Verification tests for PR #5863 (stdio MCP server support).
+
+Covers the pure helpers (is_stdio / parse_stdio_command / stdio_mcp_enabled /
+probe_timeout), the route-level _validate_url gate, and - most importantly -
+that the UNSLOTH_STUDIO_ALLOW_STDIO_MCP gate blocks the stdio transport at all
+five enforcement points (create, update, test, refresh, discovery, execute)
+when disabled, and reaches it when enabled. The transport (_client) is stubbed
+so no real subprocess is spawned; a recorder asserts whether it was reached.
+
+Run from studio/backend:  python -m pytest tests/test_mcp_stdio_pr5863.py -q
+"""
+
+import sys
+
+import pytest
+from fastapi import HTTPException
+
+from core.inference import mcp_client
+from storage import mcp_servers_db
+
+
+def _reset_db(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(mcp_servers_db, "_schema_ready", False)
+
+
+def _enable(monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", "1")
+
+
+def _disable(monkeypatch):
+    monkeypatch.delenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", raising = False)
+
+
+# ── transport stub + recorder ───────────────────────────────────────
+
+
+class _FakeTool:
+    def __init__(self, name):
+        self._name = name
+
+    def model_dump(self, exclude_none = True):
+        return {"name": self._name, "description": f"{self._name} tool"}
+
+
+class _Block:
+    def __init__(self, text):
+        self.type = "text"
+        self.text = text
+
+
+class _FakeResult:
+    is_error = False
+
+    def __init__(self, text):
+        self.content = [_Block(text)]
+
+
+class _RecordingClient:
+    """Stands in for fastmcp.Client; records that the transport was opened."""
+
+    def __init__(self, url, headers, use_oauth, recorder):
+        recorder.append({"url": url, "headers": headers, "use_oauth": use_oauth})
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *a):
+        return False
+
+    async def list_tools(self):
+        return [_FakeTool("list_directory"), _FakeTool("write_file")]
+
+    async def call_tool(self, name, args):
+        return _FakeResult(f"called {name}")
+
+
+@pytest.fixture
+def transport(monkeypatch):
+    """Patch mcp_client._client with a recorder. Returns the recorder list;
+    empty == the stdio transport was never reached."""
+    recorder = []
+    monkeypatch.setattr(
+        mcp_client,
+        "_client",
+        lambda url, headers, use_oauth = False: _RecordingClient(
+            url, headers, use_oauth, recorder
+        ),
+    )
+    return recorder
+
+
+# ── 1. is_stdio ─────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "addr",
+    [
+        "http://localhost:8000/mcp",
+        "https://example.com/mcp",
+        "  https://example.com/mcp  ",
+        "HTTPS://EXAMPLE.COM/mcp",
+    ],
+)
+def test_is_stdio_false_for_http(addr):
+    assert mcp_client.is_stdio(addr) is False
+
+
+@pytest.mark.parametrize(
+    "addr",
+    [
+        "npx -y @modelcontextprotocol/server-filesystem /tmp",
+        "python -m some.module",
+        "uvx some-server --flag",
+        "/usr/local/bin/my-server",
+    ],
+)
+def test_is_stdio_true_for_commands(addr):
+    assert mcp_client.is_stdio(addr) is True
+
+
+# ── 2. parse_stdio_command ──────────────────────────────────────────
+
+
+def test_parse_basic_argv():
+    assert mcp_client.parse_stdio_command(
+        "npx -y @modelcontextprotocol/server-filesystem /tmp"
+    ) == ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+
+def test_parse_keeps_url_argument_as_one_command():
+    # gemini "high": a :// inside an ARGUMENT must not break the command.
+    assert mcp_client.parse_stdio_command(
+        "npx server --endpoint https://example.com/mcp"
+    ) == ["npx", "server", "--endpoint", "https://example.com/mcp"]
+
+
+def test_parse_quoted_arg():
+    assert mcp_client.parse_stdio_command('python -m mod --name "a b"') == [
+        "python",
+        "-m",
+        "mod",
+        "--name",
+        "a b",
+    ]
+
+
+def test_parse_empty_returns_empty_list():
+    assert mcp_client.parse_stdio_command("   ") == []
+
+
+def test_parse_unclosed_quote_raises_valueerror():
+    with pytest.raises(ValueError):
+        mcp_client.parse_stdio_command('npx "unclosed')
+
+
+def test_parse_windows_strips_wrapping_quotes(monkeypatch):
+    # gemini "medium": posix=False keeps backslash paths but also the wrapping
+    # quotes; the PR strips a matched pair so argv[0] reaches the OS clean.
+    monkeypatch.setattr(sys, "platform", "win32")
+    parts = mcp_client.parse_stdio_command(
+        r'"C:\Program Files\node\node.exe" server.js'
+    )
+    assert parts[0] == r"C:\Program Files\node\node.exe"
+    assert parts[1] == "server.js"
+
+
+# ── 3. stdio_mcp_enabled ────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("val", ["0", "false", "true", "", " 1 ", "yes", "2"])
+def test_stdio_disabled_for_non_exact_one(monkeypatch, val):
+    monkeypatch.setenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", val)
+    assert mcp_client.stdio_mcp_enabled() is False
+
+
+def test_stdio_enabled_only_for_exact_one(monkeypatch):
+    _disable(monkeypatch)
+    assert mcp_client.stdio_mcp_enabled() is False
+    monkeypatch.setenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", "1")
+    assert mcp_client.stdio_mcp_enabled() is True
+
+
+# ── 4. probe_timeout ────────────────────────────────────────────────
+
+
+def test_probe_timeout_matrix():
+    assert mcp_client.probe_timeout("https://x/mcp", False) == 8.0
+    assert mcp_client.probe_timeout("https://x/mcp", True) == 305.0
+    assert mcp_client.probe_timeout("npx server", False) == 60.0
+    # oauth wins regardless of address kind (documented behaviour)
+    assert mcp_client.probe_timeout("npx server", True) == 305.0
+
+
+# ── 5. _validate_url gate ───────────────────────────────────────────
+
+
+def test_validate_url_gate_off_rejects_stdio(monkeypatch):
+    _disable(monkeypatch)
+    from routes.mcp_servers import _validate_url
+
+    assert _validate_url("https://example.com/mcp") == "https://example.com/mcp"
+    for bad in ["npx server", "python -m mod", "ftp://host"]:
+        with pytest.raises(HTTPException) as exc:
+            _validate_url(bad)
+        assert exc.value.status_code == 400
+
+
+def test_validate_url_gate_on_accepts_stdio(monkeypatch):
+    _enable(monkeypatch)
+    from routes.mcp_servers import _validate_url
+
+    assert _validate_url("npx -y server /tmp") == "npx -y server /tmp"
+    # http still works when stdio is on
+    assert _validate_url("https://x/mcp") == "https://x/mcp"
+    # url-bearing argument accepted as a command
+    assert _validate_url("npx server --url https://x/mcp") == (
+        "npx server --url https://x/mcp"
+    )
+    # empty / unparseable still rejected
+    for bad in ["   ", '"unclosed']:
+        with pytest.raises(HTTPException) as exc:
+            _validate_url(bad)
+        assert exc.value.status_code == 400
+
+
+# ── 6. gate enforcement at every spawn path (mocked transport) ──────
+
+
+def test_create_route_gate(tmp_path, monkeypatch, transport):
+    import asyncio
+
+    from models.mcp_servers import McpServerCreate
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    payload = McpServerCreate(display_name = "FS", url = "npx -y server /tmp")
+
+    _disable(monkeypatch)
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(routes_mcp.create_mcp_server(payload, current_subject = "u"))
+    assert exc.value.status_code == 400
+
+    _enable(monkeypatch)
+    resp = asyncio.run(routes_mcp.create_mcp_server(payload, current_subject = "u"))
+    assert resp.url == "npx -y server /tmp"
+
+
+def test_update_http_to_stdio_blocked_when_off(tmp_path, monkeypatch):
+    import asyncio
+
+    from models.mcp_servers import McpServerUpdate
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    _disable(monkeypatch)
+    mcp_servers_db.create_server(id = "s1", display_name = "A", url = "https://a/mcp")
+    # editing url -> stdio command must 400 (http->stdio edit bypass closed)
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            routes_mcp.update_mcp_server(
+                "s1", McpServerUpdate(url = "npx server"), current_subject = "u"
+            )
+        )
+    assert exc.value.status_code == 400
+
+
+def test_test_route_gate(tmp_path, monkeypatch, transport):
+    import asyncio
+
+    from models.mcp_servers import McpServerTestRequest
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    req = McpServerTestRequest(url = "npx -y server /tmp")
+
+    _disable(monkeypatch)
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(routes_mcp.test_mcp_server(req, current_subject = "u"))
+    assert exc.value.status_code == 400
+    assert transport == []  # transport never opened
+
+    _enable(monkeypatch)
+    res = asyncio.run(routes_mcp.test_mcp_server(req, current_subject = "u"))
+    assert res.ok and res.tool_count == 2
+    assert len(transport) == 1
+
+
+def test_refresh_route_gate(tmp_path, monkeypatch, transport):
+    import asyncio
+
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    # a stdio row as if carried over from a desktop DB
+    mcp_servers_db.create_server(id = "stdio1", display_name = "FS", url = "npx server")
+
+    _disable(monkeypatch)
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(routes_mcp.refresh_mcp_server_tools("stdio1", current_subject = "u"))
+    assert exc.value.status_code == 400
+    assert transport == []
+
+    _enable(monkeypatch)
+    res = asyncio.run(
+        routes_mcp.refresh_mcp_server_tools("stdio1", current_subject = "u")
+    )
+    assert res.ok and res.tool_count == 2
+    assert len(transport) == 1
+
+
+def test_discovery_gate(tmp_path, monkeypatch, transport):
+    import asyncio
+
+    from core.inference.tools import get_enabled_mcp_tools
+
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(
+        id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True
+    )
+
+    _disable(monkeypatch)
+    assert asyncio.run(get_enabled_mcp_tools()) == []
+    assert transport == []  # filtered out before any probe
+
+    _enable(monkeypatch)
+    specs = asyncio.run(get_enabled_mcp_tools())
+    assert len(specs) == 2
+    assert len(transport) == 1
+
+
+def test_execute_gate(tmp_path, monkeypatch, transport):
+    from core.inference.tools import execute_tool
+
+    _reset_db(tmp_path, monkeypatch)
+    mcp_servers_db.create_server(
+        id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True
+    )
+
+    _disable(monkeypatch)
+    out = execute_tool("mcp__stdio1__list_directory", {"path": "/tmp"})
+    assert "disabled on this host" in out
+    assert transport == []
+
+    _enable(monkeypatch)
+    out = execute_tool("mcp__stdio1__list_directory", {"path": "/tmp"})
+    assert out == "called list_directory"
+    assert len(transport) == 1
+
+
+# ── 7. env vars ride headers_json as the subprocess env ─────────────
+
+
+def test_stdio_env_passed_through(tmp_path, monkeypatch, transport):
+    from core.inference.tools import execute_tool
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    mcp_servers_db.create_server(
+        id = "stdio1",
+        display_name = "FS",
+        url = "npx server",
+        headers_json = '{"API_KEY": "sk-test"}',
+        is_enabled = True,
+    )
+    execute_tool("mcp__stdio1__list_directory", {})
+    assert transport[-1]["headers"] == {"API_KEY": "sk-test"}

From b66d35b425d3a78343f73076bc51bf590703f277 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 05:55:00 -0700
Subject: [PATCH 036/222] Studio: stop hidden source badges from inflating chat
 scroll height (#5822)

The SourcesGroup measurement container renders every citation badge
off-screen with `invisible absolute` so we can measure how many fit in
two rows. Absolute descendants still contribute to the parent's
scrollable overflow region, so long source lists added hundreds of
pixels of phantom scroll space below the assistant message that the
user could scroll into.

Wrap the measurement container in an absolute, `h-0`, `overflow-hidden`
box so the off-screen pills are clipped out of the scrollable overflow
region. Measurement still works because offsetTop is read relative to
the positioned wrapper.
---
 .../src/components/assistant-ui/sources.tsx   | 36 +++++++++++++------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/sources.tsx b/studio/frontend/src/components/assistant-ui/sources.tsx
index 140b61f932..5593369bf9 100644
--- a/studio/frontend/src/components/assistant-ui/sources.tsx
+++ b/studio/frontend/src/components/assistant-ui/sources.tsx
@@ -263,20 +263,34 @@ const SourcesGroup: FC = () => {
 
   return (
     <div className="relative mt-2 mb-3">
-      {/* Hidden measurement container — renders all badges to measure row positions */}
+      {/* Hidden measurement container. Renders all badges off-screen so we
+          can read each child's offsetTop and decide how many fit in two
+          rows. Wrapped in an absolute, h-0, overflow-hidden box so the
+          measurement pills do NOT contribute to the viewport's scrollable
+          overflow region. Without this clip, every hidden source row
+          adds ~30px to scrollHeight, producing a phantom empty scroll
+          area below the message: visible to users as unbounded blank
+          space below the assistant action bar. The inner div still
+          flex-wraps its children for measurement; offsetTop reads
+          correctly because the wrapper is positioned (absolute) and the
+          children's offsetTop is measured relative to it. */}
       <div
-        ref={containerRef}
         aria-hidden
-        className="flex w-full flex-wrap gap-1 invisible absolute pointer-events-none"
+        className="absolute pointer-events-none overflow-hidden h-0 w-full left-0 top-0"
       >
-        {sources.map((source) => (
-          <span key={source.id} className="inline-block">
-            <Source href={source.url}>
-              <SourceIcon url={source.url} />
-              <SourceTitle>{source.title || extractDomain(source.url)}</SourceTitle>
-            </Source>
-          </span>
-        ))}
+        <div
+          ref={containerRef}
+          className="flex w-full flex-wrap gap-1 invisible"
+        >
+          {sources.map((source) => (
+            <span key={source.id} className="inline-block">
+              <Source href={source.url}>
+                <SourceIcon url={source.url} />
+                <SourceTitle>{source.title || extractDomain(source.url)}</SourceTitle>
+              </Source>
+            </span>
+          ))}
+        </div>
       </div>
 
       {/* Visible container */}

From dad2695fdea49c2318ce27ff6307892b77f6f533 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 06:18:30 -0700
Subject: [PATCH 037/222] Studio: pin the last pre-macOS-26 llama.cpp prebuilt
 instead of walking back (#5896)

* Studio: pin the last pre-macOS-26 llama.cpp prebuilt instead of walking back

ggml-org moved their macOS build runner to macOS 26 (Tahoe) at b9428, so
b9428 and every newer upstream prebuilt is stamped minos 26 and fails to
dyld-load on macOS 14 / 15. #5883 handled this by walking back release by
release at install time.

Replace that with a deterministic pin: a host below macOS 26 selects b9415
directly (the last upstream build stamped below 26: arm64 minos 14, x64
minos 13.3), so it loads on macOS 13.3 / 14 / 15 / 26. Hosts on macOS 26+
and unknown-version hosts keep latest selection unchanged.

Only the ggml-org upstream path is pinned; the unslothai/llama.cpp fork
ships its own minos-13.3 prebuilts (#5893), so the pin is a no-op there and
goes dormant once macOS routes to the fork. The Mach-O minos preflight from
#5883 stays as a post-download backstop.

Refs #5883, #5893.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* docs: fork ships arm64 minos 14 / x64 minos 13.3, not uniform 13.3

The per-slice fork producer pins arm64 to 14.0 and x64 to 13.3; update the
pinned_macos_release_tag docstring to match. No behavior change.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 studio/install_llama_prebuilt.py              |  46 +++++--
 .../install/test_macos_version_compat.py      |  46 ++++---
 tests/studio/install/test_selection_logic.py  | 127 ++++++++++++++++++
 3 files changed, 192 insertions(+), 27 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 861a501570..2afd54bec9 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -169,6 +169,11 @@ DEFAULT_MAX_MACOS_RELEASE_FALLBACKS = env_int(
     16,
     minimum = 1,
 )
+# Deterministic macOS pin. At b9428 ggml-org's macOS runner moved to macOS 26
+# (Tahoe), so b9428+ prebuilts only load on macOS 26+. b9415 is the last build
+# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on macOS 13.3/14/15/26.
+_PINNED_MACOS_FALLBACK_TAG = "b9415"
+_PINNED_MACOS_LATEST_FLOOR = (26, 0)
 FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master")
 
 DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
@@ -1616,6 +1621,24 @@ def direct_upstream_release_plan(
     )
 
 
+def pinned_macos_release_tag(host: HostInfo, repo: str) -> str | None:
+    """Pin b9415 (the last upstream macOS build that loads below macOS 26) for a
+    known pre-26 host on ggml-org upstream; return None to keep latest selection.
+    The unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64
+    minos 13.3) and needs no pin, so this is a no-op there and for macOS 26+,
+    unknown version, non-macOS."""
+    if repo != UPSTREAM_REPO:
+        return None
+    if not host.is_macos:
+        return None
+    version = host.macos_version
+    if version is None:
+        return None
+    if version >= _PINNED_MACOS_LATEST_FLOOR:
+        return None
+    return _PINNED_MACOS_FALLBACK_TAG
+
+
 def resolve_simple_install_release_plans(
     llama_tag: str,
     host: HostInfo,
@@ -1629,15 +1652,15 @@ def resolve_simple_install_release_plans(
     allow_older_release_fallback = (
         requested_tag == "latest" and not published_release_tag
     )
+    # macOS: pin the last upstream build that loads on a pre-26 host instead of
+    # fetching the latest (macOS 26 only) build and walking back release by
+    # release. No-op on macOS 26+, unknown version, non-macOS, and the fork.
+    if allow_older_release_fallback:
+        pinned_macos = pinned_macos_release_tag(host, repo)
+        if pinned_macos is not None:
+            requested_tag = pinned_macos
+            allow_older_release_fallback = False
     release_limit = max(1, max_release_fallbacks)
-    # macOS may need to walk past a run of too-new prebuilts. Only when the host
-    # version is known; otherwise keep the default (cannot tell up front).
-    if (
-        host.is_macos
-        and allow_older_release_fallback
-        and host.macos_version is not None
-    ):
-        release_limit = max(release_limit, DEFAULT_MAX_MACOS_RELEASE_FALLBACKS)
     plans: list[InstallReleasePlan] = []
     last_error: PrebuiltFallback | None = None
 
@@ -5303,9 +5326,10 @@ def preflight_macos_installed_binaries(
     install_dir: Path,
     host: HostInfo,
 ) -> None:
-    """Reject a macos prebuilt whose minimum-OS is newer than the host so the
-    release walk-back advances to the newest compatible release. No-op when the
-    host macOS version is unknown (runtime validation remains the backstop)."""
+    """Reject a macos prebuilt whose minimum-OS is newer than the host. The
+    upstream selector pins a loadable release up front, so here this is the
+    post-download backstop; the published/fork path also uses it to advance the
+    walk-back. No-op when the host macOS version is unknown (runtime validates)."""
     if not host.is_macos or host.macos_version is None:
         return
     issues = macos_binary_minos_issues(binaries, install_dir, host)
diff --git a/tests/studio/install/test_macos_version_compat.py b/tests/studio/install/test_macos_version_compat.py
index 0adc91a622..1b87e5af65 100644
--- a/tests/studio/install/test_macos_version_compat.py
+++ b/tests/studio/install/test_macos_version_compat.py
@@ -238,32 +238,46 @@ def _fake_macos_releases(tags):
     ]
 
 
-class TestMacosReleaseWalkback:
-    """A known-version macOS host must generate enough older-release plans to
-    walk back past a run of too-new prebuilts; unknown-version and non-macOS
-    hosts keep the conservative 2-release default."""
+class TestMacosReleasePin:
+    """A known pre-26 macOS host deterministically pins the last upstream release
+    whose prebuilt loads on it (b9415) instead of walking back release by release;
+    macOS 26+ and unknown-version hosts keep normal latest selection with the
+    conservative 2-release default."""
 
-    TAGS = [f"b{n}" for n in range(9437, 9400, -1)]  # 37 newest-first releases
+    TAGS = [f"b{n}" for n in range(9442, 9400, -1)]  # newest-first, includes b9415
 
     def _patch_releases(self, monkeypatch):
-        monkeypatch.setattr(
-            ILP,
-            "iter_release_payloads_by_time",
-            lambda repo, published_release_tag, requested_tag: _fake_macos_releases(
-                self.TAGS
-            ),
-        )
+        def fake_iter(repo, published_release_tag, requested_tag):
+            # The real iterator yields only the requested tag when one is pinned.
+            if requested_tag and requested_tag != "latest":
+                return _fake_macos_releases([requested_tag])
+            return _fake_macos_releases(self.TAGS)
 
-    def test_known_macos_host_walks_back_deeper(self, monkeypatch):
+        monkeypatch.setattr(ILP, "iter_release_payloads_by_time", fake_iter)
+
+    def test_pre26_host_pins_b9415(self, monkeypatch):
         self._patch_releases(monkeypatch)
-        _tag, plans = ILP.resolve_simple_install_release_plans(
+        tag, plans = ILP.resolve_simple_install_release_plans(
             "latest",
             make_macos_host((14, 0)),
             "ggml-org/llama.cpp",
             "",
         )
-        assert len(plans) == ILP.DEFAULT_MAX_MACOS_RELEASE_FALLBACKS
-        assert len(plans) > ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS
+        assert tag == ILP._PINNED_MACOS_FALLBACK_TAG == "b9415"
+        assert len(plans) == 1
+        assert plans[0].release_tag == "b9415"
+
+    def test_tahoe_host_takes_latest(self, monkeypatch):
+        self._patch_releases(monkeypatch)
+        tag, plans = ILP.resolve_simple_install_release_plans(
+            "latest",
+            make_macos_host((26, 0)),
+            "ggml-org/llama.cpp",
+            "",
+        )
+        assert tag == "latest"
+        assert plans[0].release_tag == self.TAGS[0]  # newest release
+        assert len(plans) == ILP.DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS
 
     def test_unknown_macos_host_uses_default(self, monkeypatch):
         self._patch_releases(monkeypatch)
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 16f47fa410..78aa9c480e 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -85,6 +85,10 @@ _windows_cuda_attempt_covers_blackwell = (
     INSTALL_LLAMA_PREBUILT._windows_cuda_attempt_covers_blackwell
 )
 resolve_release_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_release_asset_choice
+pinned_macos_release_tag = INSTALL_LLAMA_PREBUILT.pinned_macos_release_tag
+resolve_simple_install_release_plans = (
+    INSTALL_LLAMA_PREBUILT.resolve_simple_install_release_plans
+)
 
 
 # ---------------------------------------------------------------------------
@@ -2631,3 +2635,126 @@ class TestResolveUpstreamAssetChoice:
         result = resolve_upstream_asset_choice(host, self.TAG)
         assert result.install_kind == "windows-cuda"
         assert result.name == cuda_name
+
+
+# ===========================================================================
+# N.2. Deterministic macOS prebuilt pin (b9415)
+# ===========================================================================
+
+
+def _macos_host(machine = "arm64", version = (15, 5)):
+    return make_host(
+        system = "Darwin",
+        machine = machine,
+        nvidia_smi = None,
+        driver_cuda_version = None,
+        compute_caps = [],
+        has_physical_nvidia = False,
+        has_usable_nvidia = False,
+        macos_version = version,
+    )
+
+
+class TestPinnedMacosReleaseTag:
+    """pinned_macos_release_tag: pin b9415 only for ggml-org upstream macOS hosts
+    below macOS 26; latest (None) for 26+, unknown version, the fork, non-macOS."""
+
+    def test_arm64_sequoia_pins_b9415(self):
+        host = _macos_host("arm64", (15, 5))
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415"
+
+    def test_arm64_sonoma_pins_b9415(self):
+        host = _macos_host("arm64", (14, 7))
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415"
+
+    def test_x64_ventura_13_3_pins_b9415(self):
+        # b9415's Intel slice is minos 13.3, so 13.3 Intel hosts still load it.
+        host = _macos_host("x86_64", (13, 3))
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) == "b9415"
+
+    def test_tahoe_26_0_takes_latest(self):
+        host = _macos_host("arm64", (26, 0))
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None
+
+    def test_tahoe_26_1_takes_latest(self):
+        host = _macos_host("arm64", (26, 1))
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None
+
+    def test_unknown_version_takes_latest(self):
+        host = _macos_host("arm64", None)
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None
+
+    def test_fork_repo_is_dormant(self):
+        # The unslothai/llama.cpp fork publishes its own minos-13.3 prebuilts.
+        host = _macos_host("arm64", (15, 5))
+        fork = INSTALL_LLAMA_PREBUILT.DEFAULT_PUBLISHED_REPO
+        assert pinned_macos_release_tag(host, fork) is None
+
+    def test_non_macos_host_is_dormant(self):
+        host = make_host(system = "Linux", machine = "x86_64")
+        assert pinned_macos_release_tag(host, UPSTREAM_REPO) is None
+
+
+class TestResolveSimpleMacosPin:
+    """End to end on the simple/upstream path macOS actually uses: a pre-26 host
+    deterministically resolves b9415 (no walk-back); a macOS 26 host takes the
+    latest release. Mirrors how setup.sh routes Darwin to ggml-org/llama.cpp."""
+
+    TAGS = ["b9442", "b9430", "b9428", "b9415"]  # newest-first feed
+
+    def _feed(self, monkeypatch):
+        calls = []
+
+        def _release(tag):
+            name = f"llama-{tag}-bin-macos-arm64.tar.gz"
+            return {
+                "tag_name": tag,
+                "assets": [
+                    {
+                        "name": name,
+                        "browser_download_url": f"https://example.com/{name}",
+                    }
+                ],
+            }
+
+        def fake_iter(repo, published_release_tag = "", requested_tag = ""):
+            calls.append((repo, published_release_tag, requested_tag))
+            # Emulate the real iterator: a specific tag yields only that release.
+            if requested_tag and requested_tag != "latest":
+                yield _release(requested_tag)
+                return
+            for tag in self.TAGS:
+                yield _release(tag)
+
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", fake_iter
+        )
+        return calls
+
+    def test_pre26_host_pins_b9415_without_walkback(self, monkeypatch):
+        calls = self._feed(monkeypatch)
+        host = _macos_host("arm64", (15, 5))
+        requested_tag, plans = resolve_simple_install_release_plans(
+            "latest", host, "ggml-org/llama.cpp", ""
+        )
+        assert requested_tag == "b9415"
+        assert len(plans) == 1
+        assert plans[0].release_tag == "b9415"
+        assert plans[0].llama_tag == "b9415"
+        assert plans[0].attempts[0].install_kind == "macos-arm64"
+        assert plans[0].attempts[0].name == "llama-b9415-bin-macos-arm64.tar.gz"
+        # The pin overrode the requested tag before any release was fetched.
+        assert calls[0][2] == "b9415"
+        # Simple/upstream path stays unverified-by-manifest, exactly as before.
+        assert plans[0].approved_checksums.artifacts == {}
+
+    def test_tahoe_host_takes_latest_release(self, monkeypatch):
+        calls = self._feed(monkeypatch)
+        host = _macos_host("arm64", (26, 0))
+        requested_tag, plans = resolve_simple_install_release_plans(
+            "latest", host, "ggml-org/llama.cpp", ""
+        )
+        assert requested_tag == "latest"
+        assert plans[0].release_tag == "b9442"
+        # No pin: the iterator was asked for latest, not a specific tag.
+        assert calls[0][2] == "latest"

From 2e1580f70bd9f1b9a8b2d35112f89047a4217e1d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 06:29:11 -0700
Subject: [PATCH 038/222] Versioning

---
 pyproject.toml           | 6 +++---
 unsloth/models/_utils.py | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index aef88d90f5..acc65f12cf 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,7 +69,7 @@ triton = [
 ]
 
 huggingfacenotorch = [
-    "unsloth_zoo>=2026.5.4",
+    "unsloth_zoo>=2026.5.5",
     "wheel>=0.42.0",
     "packaging",
     "numpy",
@@ -90,7 +90,7 @@ huggingfacenotorch = [
 ]
 huggingface = [
     "unsloth[huggingfacenotorch]",
-    "unsloth_zoo>=2026.5.4",
+    "unsloth_zoo>=2026.5.5",
     "torchvision",
     "unsloth[triton]",
 ]
@@ -580,7 +580,7 @@ colab-ampere-torch220 = [
     "flash-attn>=2.6.3 ; ('linux' in sys_platform)",
 ]
 colab-new = [
-    "unsloth_zoo>=2026.5.4",
+    "unsloth_zoo>=2026.5.5",
     "packaging",
     "tyro",
     "transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 67b3468425..59d7305a79 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2026.5.8"
+__version__ = "2026.5.9"
 
 __all__ = [
     "SUPPORTS_BFLOAT16",

From 70394e1f85cf41c3b18e0731cab921ad8b25dcf1 Mon Sep 17 00:00:00 2001
From: Ramakrishna Bachu <ramankrishna10@gmail.com>
Date: Sun, 31 May 2026 13:30:36 +0000
Subject: [PATCH 039/222] fix(install): detect x86_64 Python venv on Apple
 Silicon and rebuild as arm64

On Apple Silicon, uv can create the venv from a cached x86_64 (Rosetta)
Python, so the venv reports x86_64 to wheel resolvers and the torch install
never resolves (the CPU index ships no macOS wheels). Detect an x86_64 venv
on an arm64 host and recreate it with an arch-explicit arm64 CPython,
re-inspecting before the existing 3.13.8 check so both invariants hold.
Skipped when --python is set; non-macOS, Intel, and healthy arm64 venvs are
unaffected.

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 install.sh | 44 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/install.sh b/install.sh
index f0af60e2d6..532203a51a 100755
--- a/install.sh
+++ b/install.sh
@@ -1530,17 +1530,51 @@ if [ -x "$VENV_DIR/bin/python" ]; then
     : > "$VENV_DIR/.unsloth-studio-owned" 2>/dev/null || true
 fi
 
-# Guard against Python 3.13.8 torch import bug on Apple Silicon
-# (skip when the user explicitly chose a version via --python)
+# Guard against two independent Apple Silicon venv problems, in order:
+#   1. uv may create the venv from a cached x86_64 (Rosetta) Python when a
+#      same-version x86_64 build is already cached (often because uv itself
+#      is an x86_64 build). That venv reports x86_64 to wheel resolvers, and
+#      PyTorch ships no macOS wheels on the CPU index for any architecture,
+#      so the torch install can never resolve. Recreate it with an
+#      arch-explicit arm64 CPython.
+#   2. Python 3.13.8 has a known torch import bug.
+# The two are independent: a venv may be x86_64 and, once recreated, still
+# land on 3.13.8. So we re-inspect the interpreter between the checks instead
+# of chaining them with elif, guaranteeing both invariants hold on whatever
+# venv we end up with. Skip both when the user explicitly chose an interpreter
+# via --python.
 if [ -z "$_USER_PYTHON" ] && [ "$OS" = "macos" ] && [ "$_ARCH" = "arm64" ]; then
-    _PY_VER=$("$VENV_DIR/bin/python" -c \
-        "import sys; print('{}.{}.{}'.format(*sys.version_info[:3]))" 2>/dev/null || echo "")
+    _inspect_venv() {
+        "$VENV_DIR/bin/python" -c \
+            "import platform, sys; print(platform.machine(), '{}.{}.{}'.format(*sys.version_info[:3]))" \
+            2>/dev/null || echo " "
+    }
+    _info=$(_inspect_venv)
+    _VENV_ARCH=${_info%% *}
+    _PY_VER=${_info##* }
+
+    if [ "$_VENV_ARCH" = "x86_64" ]; then
+        echo "  WARNING: venv was created with an x86_64 (Rosetta) Python on Apple Silicon."
+        echo "  Recreating venv with native arm64 Python ${PYTHON_VERSION}..."
+        rm -rf "$VENV_DIR"
+        run_install_cmd "recreate venv (arm64)" uv venv "$VENV_DIR" \
+            --python "cpython-${PYTHON_VERSION}-macos-aarch64-none"
+        if [ -x "$VENV_DIR/bin/python" ]; then
+            : > "$VENV_DIR/.unsloth-studio-owned" 2>/dev/null || true
+        fi
+        # Re-inspect: the recreated arm64 venv may still be 3.13.8.
+        _info=$(_inspect_venv)
+        _VENV_ARCH=${_info%% *}
+        _PY_VER=${_info##* }
+    fi
+
     if [ "$_PY_VER" = "3.13.8" ]; then
         echo "  WARNING: Python 3.13.8 has a known torch import bug."
         echo "  Recreating venv with Python 3.12..."
         rm -rf "$VENV_DIR"
         PYTHON_VERSION="3.12"
-        run_install_cmd "recreate venv" uv venv "$VENV_DIR" --python "$PYTHON_VERSION"
+        run_install_cmd "recreate venv" uv venv "$VENV_DIR" \
+            --python "cpython-${PYTHON_VERSION}-macos-aarch64-none"
         if [ -x "$VENV_DIR/bin/python" ]; then
             : > "$VENV_DIR/.unsloth-studio-owned" 2>/dev/null || true
         fi

From e04ea3347e7767abef5f2896c71e04419008caab Mon Sep 17 00:00:00 2001
From: danielhanchen <michaelhan2050@gmail.com>
Date: Sun, 31 May 2026 13:30:36 +0000
Subject: [PATCH 040/222] test(install): cover the Apple Silicon venv arch
 rebuild guard

Extracts the real guard block from install.sh and asserts: clean arm64 venv
untouched, x86_64 venv rebuilt as arm64, the x86_64-then-3.13.8 corner case,
arm64 3.13.8 downgrade preserved, --python skip, and Intel/Rosetta no-op.

Co-authored-by: Ramakrishna Bachu <ramankrishna10@gmail.com>
---
 tests/sh/test_mac_intel_compat.sh | 74 +++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/tests/sh/test_mac_intel_compat.sh b/tests/sh/test_mac_intel_compat.sh
index be9f756f90..673fd58cd6 100644
--- a/tests/sh/test_mac_intel_compat.sh
+++ b/tests/sh/test_mac_intel_compat.sh
@@ -563,6 +563,80 @@ else
     FAIL=$((FAIL + 1))
 fi
 
+echo ""
+echo "=== Apple Silicon x86_64 (Rosetta) venv rebuild ==="
+
+# Extract the real guard block from install.sh so we exercise the shipped logic
+# (comment header down to its column-0 closing fi).
+_GUARD_FILE=$(mktemp)
+awk '/Guard against two independent Apple Silicon venv problems/{f=1} f{print} f&&/^fi$/{exit}' \
+    "$INSTALL_SH" > "$_GUARD_FILE"
+
+if [ ! -s "$_GUARD_FILE" ]; then
+    echo "  FAIL: could not extract Apple Silicon venv guard from install.sh"
+    FAIL=$((FAIL + 1))
+else
+    # Runner: stub uv (via run_install_cmd) + a fake venv python, source the
+    # guard, then print "<final_arch> <final_ver> | <recreate_selectors>".
+    # The stub maps a uv arm64 selector to the interpreter uv would produce:
+    # cpython-3.12-* -> arm64 3.12.7, cpython-3.13-* -> arm64 $REBUILD_313_VERSION.
+    _RUNNER=$(mktemp)
+    cat > "$_RUNNER" << 'RUNNER_EOF'
+GUARD="$1"; VENV_DIR="$2"
+make_python() {  # dir machine version
+    mkdir -p "$1/bin"
+    printf '#!/usr/bin/env bash\necho "%s %s"\n' "$2" "$3" > "$1/bin/python"
+    chmod +x "$1/bin/python"
+}
+RECREATE_LOG=$(mktemp); : > "$RECREATE_LOG"
+run_install_cmd() {
+    shift  # drop the human label
+    if [ "$1" = "uv" ] && [ "$2" = "venv" ]; then
+        dir="$3"; sel=""; shift 3
+        while [ $# -gt 0 ]; do [ "$1" = "--python" ] && { sel="$2"; shift; }; shift; done
+        echo "$sel" >> "$RECREATE_LOG"
+        case "$sel" in
+            *3.12-macos-aarch64*) make_python "$dir" arm64 "3.12.7" ;;
+            *3.13-macos-aarch64*) make_python "$dir" arm64 "${REBUILD_313_VERSION:-3.13.3}" ;;
+            *)                    make_python "$dir" arm64 "$sel" ;;
+        esac
+    fi
+}
+[ "$INIT_ARCH" != none ] && make_python "$VENV_DIR" "$INIT_ARCH" "$INIT_VER"
+PYTHON_VERSION="3.13"
+. "$GUARD" >&2  # guard's user-facing echoes go to stderr; keep stdout clean
+final="none"; [ -x "$VENV_DIR/bin/python" ] && final="$("$VENV_DIR/bin/python" -c x)"
+printf '%s | %s\n' "$final" "$(paste -sd, "$RECREATE_LOG" 2>/dev/null)"
+rm -f "$RECREATE_LOG"
+RUNNER_EOF
+
+    _run_guard() {  # _USER_PYTHON OS _ARCH INIT_ARCH INIT_VER REBUILD_313_VERSION
+        _vd=$(mktemp -d)
+        env _USER_PYTHON="$1" OS="$2" _ARCH="$3" INIT_ARCH="$4" INIT_VER="$5" \
+            REBUILD_313_VERSION="$6" bash "$_RUNNER" "$_GUARD_FILE" "$_vd/venv"
+        rm -rf "$_vd"
+    }
+
+    assert_eq "clean arm64 venv left untouched" \
+        "arm64 3.13.3 | " "$(_run_guard '' macos arm64 arm64 3.13.3 '')"
+    assert_eq "x86_64 venv rebuilt as arm64" \
+        "arm64 3.13.3 | cpython-3.13-macos-aarch64-none" \
+        "$(_run_guard '' macos arm64 x86_64 3.13.3 '')"
+    assert_eq "x86_64 venv that lands on 3.13.8 is rebuilt then downgraded to 3.12" \
+        "arm64 3.12.7 | cpython-3.13-macos-aarch64-none,cpython-3.12-macos-aarch64-none" \
+        "$(_run_guard '' macos arm64 x86_64 3.13.3 3.13.8)"
+    assert_eq "arm64 3.13.8 venv downgraded to 3.12" \
+        "arm64 3.12.7 | cpython-3.12-macos-aarch64-none" \
+        "$(_run_guard '' macos arm64 arm64 3.13.8 '')"
+    assert_eq "--python override skips the guard entirely" \
+        "x86_64 3.13.3 | " "$(_run_guard 3.11 macos arm64 x86_64 3.13.3 '')"
+    assert_eq "x86_64 host (Intel/Rosetta shell) is a no-op here" \
+        "x86_64 3.13.3 | " "$(_run_guard '' macos x86_64 x86_64 3.13.3 '')"
+
+    rm -f "$_RUNNER"
+fi
+rm -f "$_GUARD_FILE"
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ] || exit 1

From 5b1a8218e05f8270795958681ec5dc48f94a2669 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 14:23:14 +0000
Subject: [PATCH 041/222] Bump install.sh / install.ps1 pin to
 unsloth>=2026.5.9

---
 install.ps1 | 10 +++++-----
 install.sh  | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/install.ps1 b/install.ps1
index cab66f5ae1..d3942bf2fc 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1566,7 +1566,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.8" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Resolve pydantic WITH deps so pip pins pydantic-core
                 # to the matching version (no-torch-runtime.txt below
@@ -1580,7 +1580,7 @@ shell.Run cmd, 0, False
                 }
             }
         } else {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.8" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
         }
         if ($baseInstallExit -ne 0) {
             Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
@@ -1627,7 +1627,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.5.8" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Same pydantic-with-deps trick as the migrated branch.
                 $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython pydantic }
@@ -1639,7 +1639,7 @@ shell.Run cmd, 0, False
                 }
             }
         } elseif ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.5.8" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.5.9" unsloth-zoo }
         } else {
             $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth -- "$PackageName" }
         }
@@ -1667,7 +1667,7 @@ shell.Run cmd, 0, False
         Write-TauriLog "STEP" "Installing unsloth"
         substep "installing unsloth (this may take a few minutes)..."
         if ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.5.8" --torch-backend=auto }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.5.9" --torch-backend=auto }
             if ($baseInstallExit -ne 0) {
                 Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
                 return (Exit-InstallFailure "Failed to install unsloth (exit code $baseInstallExit)" $baseInstallExit)
diff --git a/install.sh b/install.sh
index 532203a51a..89c506bc9d 100755
--- a/install.sh
+++ b/install.sh
@@ -2083,7 +2083,7 @@ if [ "$_MIGRATED" = true ]; then
         # to prevent transitive torch resolution.
         run_install_cmd "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.8" unsloth-zoo
+            "unsloth>=2026.5.9" unsloth-zoo
         # Resolve pydantic WITH deps so pip pins pydantic-core to the
         # matching version (no-torch-runtime.txt below is --no-deps).
         # All transitive deps are torch-free.
@@ -2096,7 +2096,7 @@ if [ "$_MIGRATED" = true ]; then
     else
         run_install_cmd "install unsloth (migrated)" uv pip install --python "$_VENV_PY" \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.8" unsloth-zoo
+            "unsloth>=2026.5.9" unsloth-zoo
     fi
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         substep "overlaying local repo (editable)..."
@@ -2300,7 +2300,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
         run_install_cmd "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --upgrade-package unsloth --upgrade-package unsloth-zoo \
-            "unsloth>=2026.5.8" unsloth-zoo
+            "unsloth>=2026.5.9" unsloth-zoo
         # Same pydantic-with-deps trick as the migrated branch.
         run_install_cmd "install pydantic (with deps for compatible core)" \
             uv pip install --python "$_VENV_PY" pydantic
@@ -2318,7 +2318,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         fi
     elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         run_install_cmd "install unsloth (local)" uv pip install --python "$_VENV_PY" \
-            --upgrade-package unsloth "unsloth>=2026.5.8" unsloth-zoo
+            --upgrade-package unsloth "unsloth>=2026.5.9" unsloth-zoo
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."
@@ -2350,7 +2350,7 @@ else
     tauri_log "STEP" "Installing Unsloth"
     substep "installing unsloth (this may take a few minutes)..."
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
-        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.5.8" --torch-backend=auto
+        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.5.9" --torch-backend=auto
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."

From 998feaf9d01fcd13b7dc1827bf5321183fa6363e Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 31 May 2026 07:29:11 -0700
Subject: [PATCH 042/222] Update README.md

---
 README.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 948d84a789..ce1c2bb533 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ unsloth studio -p 8888
 For cloud or global access, add `-H 0.0.0.0`. By default, Unsloth is accessible only locally.
 
 #### Update
-To update, use the same install commands above or use `unsloth studio update`.
+To update, use the same install commands above so `curl -fsSL https://unsloth.ai/install.sh | sh` or `irm https://unsloth.ai/install.ps1 | iex`
 
 #### Docker
 Use our [Docker image](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` container. Run:
@@ -171,7 +171,9 @@ unsloth studio -p 8888
 ```
 Then to update :
 ```bash
-unsloth studio update
+cd unsloth && git pull
+./install.sh --local
+unsloth studio -p 8888
 ```
 
 #### Developer installs: Windows PowerShell:
@@ -184,7 +186,9 @@ unsloth studio -p 8888
 ```
 Then to update :
 ```bash
-unsloth studio update
+cd unsloth && git pull
+./install.sh --local
+unsloth studio -p 8888
 ```
 
 #### Nightly: MacOS, Linux, WSL:

From 6bf101107a7b1fd599d2a829241d93d95488bf94 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 31 May 2026 07:31:27 -0700
Subject: [PATCH 043/222] Removing unsloth studio update.md

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ce1c2bb533..562c35ff1a 100644
--- a/README.md
+++ b/README.md
@@ -72,10 +72,13 @@ Unsloth Studio (Beta) works on **Windows, Linux, WSL** and **macOS**.
 ```bash
 curl -fsSL https://unsloth.ai/install.sh | sh
 ```
+Use the same command to update.
+
 #### Windows:
 ```powershell
 irm https://unsloth.ai/install.ps1 | iex
 ```
+Use the same command to update.
 
 #### Launch
 ```bash
@@ -83,9 +86,6 @@ unsloth studio -p 8888
 ```
 For cloud or global access, add `-H 0.0.0.0`. By default, Unsloth is accessible only locally.
 
-#### Update
-To update, use the same install commands above so `curl -fsSL https://unsloth.ai/install.sh | sh` or `irm https://unsloth.ai/install.ps1 | iex`
-
 #### Docker
 Use our [Docker image](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` container. Run:
 ```bash

From e3b52eb98a2ed577714fca382268f75cdd1189ad Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 31 May 2026 21:15:34 -0700
Subject: [PATCH 044/222] Use remove-circle icon for eject model button (#5906)

Co-authored-by: Unsloth <michaelhan@Michaels-MacBook-Pro.local>
---
 .../frontend/src/components/assistant-ui/model-selector.tsx   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/model-selector.tsx b/studio/frontend/src/components/assistant-ui/model-selector.tsx
index 8058a4d322..0fcbefdabd 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector.tsx
@@ -17,7 +17,7 @@ import {
   CloudIcon,
   DashboardSquare01Icon,
   FolderSearchIcon,
-  Logout01Icon,
+  RemoveCircleIcon,
   Search01Icon,
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
@@ -326,7 +326,7 @@ function ModelSelectorContent({
             className="flex w-full items-center justify-center gap-1.5 rounded-md px-2 py-1.5 text-xs text-destructive transition-colors hover:bg-destructive/10"
             title="Eject model"
           >
-            <HugeiconsIcon icon={Logout01Icon} className="size-3.5" />
+            <HugeiconsIcon icon={RemoveCircleIcon} className="size-3.5" />
             Eject loaded model
           </button>
         </div>

From dfba4cc5cae7c95871c0faced86b9cefd5808b28 Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Mon, 1 Jun 2026 08:35:18 +0200
Subject: [PATCH 045/222] Studio: add HTML artifacts to chat (#5772)

* Studio: add chat HTML artifact primitives

* Studio: add local render_html tool support

* Studio: wire render_html artifacts in chat UI

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: add chat artifact surface

* Studio: mount chat artifact panel and overlay

* Studio: fix chat artifact review regressions

* Studio: fix chat artifact panel and sandbox previews

* Studio: address chat artifact review follow-ups

* Studio: polish chat artifact UI affordances

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: scope artifact IDs by message to prevent cross-turn collisions

* Studio: fix artifact panel for local threads and surface tool errors

* Studio: restrict artifact frame embedding to same-origin

* Studio: stop local chat thread remount loop

* Studio: fix chat artifact store cleanup regressions

* Studio: shim artifact preview storage in sandbox

* feat(chat): add artifact rendering controls

* fix(chat): show artifact progress during tool calls

* fix(chat): refine artifact preview behavior

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(chat): ignore tool markers inside arguments

* feat(chat): polish artifact preview panel

* fix(chat): stabilize artifact panel behavior

* fix(inference): merge duplicate Anthropic tool starts

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .../core/inference/anthropic_compat.py        |  70 ++-
 studio/backend/core/inference/llama_cpp.py    |  88 +++-
 .../core/inference/safetensors_agentic.py     | 112 +++-
 .../core/inference/tool_call_parser.py        |  26 +-
 studio/backend/core/inference/tools.py        |  51 +-
 studio/backend/main.py                        |   6 +-
 studio/backend/models/inference.py            |  11 +-
 studio/backend/routes/chat_history.py         |   2 +
 studio/backend/routes/inference.py            | 287 ++++++++---
 .../backend/tests/test_anthropic_messages.py  |  92 ++++
 .../tests/test_safetensors_tool_loop.py       | 126 ++++-
 .../components/assistant-ui/markdown-text.tsx | 181 +++----
 .../src/components/assistant-ui/thread.tsx    |  27 +
 .../components/assistant-ui/tool-group.tsx    |  16 +-
 .../assistant-ui/tool-ui-render-html.tsx      | 142 ++++++
 .../frontend/src/components/ui/resizable.tsx  | 102 ++--
 .../src/features/chat/api/chat-adapter.ts     | 117 +++--
 .../features/chat/api/chat-settings-api.ts    |   2 +
 .../features/chat/artifacts/artifact-card.tsx | 141 +++++
 .../chat/artifacts/artifact-surface.tsx       | 362 +++++++++++++
 .../features/chat/artifacts/html-frame.tsx    | 100 ++++
 .../src/features/chat/artifacts/store.ts      | 107 ++++
 .../src/features/chat/artifacts/types.ts      |  84 +++
 .../frontend/src/features/chat/chat-page.tsx  | 337 ++++++++++--
 .../src/features/chat/chat-settings-sheet.tsx |  11 -
 .../chat/hooks/use-chat-model-runtime.ts      |  12 +-
 .../chat/hooks/use-chat-sidebar-items.ts      |   5 +
 studio/frontend/src/features/chat/index.ts    |   5 +
 .../src/features/chat/shared-composer.tsx     | 481 +++++++++++-------
 .../chat/stores/chat-runtime-store.ts         |  56 ++
 .../chat/utils/chat-settings-storage.ts       |  23 +
 .../src/features/native-intents/index.ts      |  11 +
 .../src/features/settings/tabs/chat-tab.tsx   |  45 +-
 studio/frontend/src/i18n/locales/en.ts        |   9 +
 studio/frontend/src/index.css                 | 143 ++++++
 35 files changed, 2800 insertions(+), 590 deletions(-)
 create mode 100644 studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
 create mode 100644 studio/frontend/src/features/chat/artifacts/artifact-card.tsx
 create mode 100644 studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
 create mode 100644 studio/frontend/src/features/chat/artifacts/html-frame.tsx
 create mode 100644 studio/frontend/src/features/chat/artifacts/store.ts
 create mode 100644 studio/frontend/src/features/chat/artifacts/types.ts
 create mode 100644 studio/frontend/src/features/native-intents/index.ts

diff --git a/studio/backend/core/inference/anthropic_compat.py b/studio/backend/core/inference/anthropic_compat.py
index bc792c3b99..cdb0fdebff 100644
--- a/studio/backend/core/inference/anthropic_compat.py
+++ b/studio/backend/core/inference/anthropic_compat.py
@@ -218,6 +218,8 @@ class AnthropicStreamEmitter:
     def __init__(self) -> None:
         self.block_index: int = 0
         self._text_block_open: bool = False
+        self._open_tool_call_id: Optional[str] = None
+        self._open_tool_args_sent: bool = False
         self._prev_text: str = ""
         self._usage: dict = {}
 
@@ -263,8 +265,10 @@ class AnthropicStreamEmitter:
     def finish(self, stop_reason: str = "end_turn") -> list[str]:
         """Close any open block and emit message_delta + message_stop."""
         events = []
-        if self._text_block_open:
+        if self._text_block_open or self._open_tool_call_id is not None:
             events.append(self._close_block())
+            self._open_tool_call_id = None
+            self._open_tool_args_sent = False
         events.append(
             build_anthropic_sse_event(
                 "message_delta",
@@ -310,12 +314,26 @@ class AnthropicStreamEmitter:
         return events
 
     def _handle_tool_start(self, event: dict) -> list[str]:
+        tool_call_id = event.get("tool_call_id", "")
+        args = event.get("arguments", {})
+        if tool_call_id and self._open_tool_call_id == tool_call_id:
+            return self._tool_arguments_delta(args)
+
         events = []
-        # Close current text block if open
+        # Close current text block if open.
         if self._text_block_open:
             events.append(self._close_block())
-        # Open a tool_use block
+        # Defensive: if a replacement/different tool_start arrives while a
+        # tool_use block is open, close the stale block before starting another.
+        elif self._open_tool_call_id is not None:
+            events.append(self._close_block())
+            self._open_tool_call_id = None
+            self._open_tool_args_sent = False
+
+        # Open a tool_use block.
         self.block_index += 1
+        self._open_tool_call_id = tool_call_id
+        self._open_tool_args_sent = False
         events.append(
             build_anthropic_sse_event(
                 "content_block_start",
@@ -324,35 +342,43 @@ class AnthropicStreamEmitter:
                     "index": self.block_index,
                     "content_block": {
                         "type": "tool_use",
-                        "id": event.get("tool_call_id", ""),
+                        "id": tool_call_id,
                         "name": event.get("tool_name", ""),
                         "input": {},
                     },
                 },
             )
         )
-        # Emit the arguments as input_json_delta
-        args = event.get("arguments", {})
-        if args:
-            events.append(
-                build_anthropic_sse_event(
-                    "content_block_delta",
-                    {
-                        "type": "content_block_delta",
-                        "index": self.block_index,
-                        "delta": {
-                            "type": "input_json_delta",
-                            "partial_json": json.dumps(args),
-                        },
-                    },
-                )
-            )
+        events.extend(self._tool_arguments_delta(args))
         return events
 
+    def _tool_arguments_delta(self, args: dict) -> list[str]:
+        if not args:
+            return []
+        if self._open_tool_args_sent:
+            return []
+        self._open_tool_args_sent = True
+        return [
+            build_anthropic_sse_event(
+                "content_block_delta",
+                {
+                    "type": "content_block_delta",
+                    "index": self.block_index,
+                    "delta": {
+                        "type": "input_json_delta",
+                        "partial_json": json.dumps(args),
+                    },
+                },
+            )
+        ]
+
     def _handle_tool_end(self, event: dict) -> list[str]:
         events = []
-        # Close the tool_use block
-        events.append(self._close_block())
+        # Close the tool_use block.
+        if self._open_tool_call_id is not None or self._text_block_open:
+            events.append(self._close_block())
+        self._open_tool_call_id = None
+        self._open_tool_args_sent = False
         # Emit custom tool_result event (non-standard, ignored by SDKs)
         events.append(
             build_anthropic_sse_event(
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index cce95fc34c..7bcf02dc35 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -52,6 +52,7 @@ from utils.subprocess_compat import (
     windows_hidden_subprocess_kwargs as _windows_hidden_subprocess_kwargs,
 )
 from core.inference.tool_call_parser import (
+    RENDER_HTML_REPEAT_NUDGE,
     parse_tool_calls_from_text as _shared_parse_tool_calls_from_text,
 )
 
@@ -4616,6 +4617,7 @@ class LlamaCppBackend:
         # a transient failure are allowed (only block when the previous
         # identical call succeeded).
         _tool_call_history: list[tuple[str, bool]] = []  # (key, failed)
+        _render_html_succeeded = False
 
         # ── Re-prompt on plan-without-action ─────────────────
         # When the model describes what it intends to do (forward-looking
@@ -4690,6 +4692,7 @@ class LlamaCppBackend:
                 _iter_timings = None
                 _stream_done = False
                 _last_emitted = ""
+                provisional_render_html_tool_call_ids = set()
 
                 stream_timeout = httpx.Timeout(
                     connect = 10,
@@ -4799,6 +4802,33 @@ class LlamaCppBackend:
                                                 tool_calls_acc[idx]["function"][
                                                     "arguments"
                                                 ] += func["arguments"]
+                                            current_name = tool_calls_acc[idx][
+                                                "function"
+                                            ].get("name", "")
+                                            fallback_id = f"call_{idx}"
+                                            current_id = tool_calls_acc[idx].get(
+                                                "id", fallback_id
+                                            )
+                                            already_started = (
+                                                current_id
+                                                in provisional_render_html_tool_call_ids
+                                            )
+                                            has_real_id = current_id != fallback_id
+                                            if (
+                                                current_name == "render_html"
+                                                and not _render_html_succeeded
+                                                and not already_started
+                                                and has_real_id
+                                            ):
+                                                provisional_render_html_tool_call_ids.add(
+                                                    current_id
+                                                )
+                                                yield {
+                                                    "type": "tool_start",
+                                                    "tool_name": "render_html",
+                                                    "tool_call_id": current_id,
+                                                    "arguments": {},
+                                                }
                                         continue
 
                                     # ── Reasoning tokens ──
@@ -4980,13 +5010,25 @@ class LlamaCppBackend:
                                     "content": _stripped,
                                 }
                             )
+                            available_tool_names = [
+                                tool.get("function", {}).get("name")
+                                for tool in tools
+                                if isinstance(tool, dict)
+                                and isinstance(tool.get("function"), dict)
+                            ]
+                            available_tool_names = [
+                                name for name in available_tool_names if name
+                            ]
+                            tool_hint = (
+                                " or ".join(available_tool_names) or "an available tool"
+                            )
                             conversation.append(
                                 {
                                     "role": "user",
                                     "content": (
                                         "STOP. Do NOT write code or explain. "
                                         "You MUST call a tool NOW. "
-                                        "Call web_search or python immediately."
+                                        f"Call {tool_hint} immediately."
                                     ),
                                 }
                             )
@@ -5158,7 +5200,12 @@ class LlamaCppBackend:
                             arguments = json.loads(raw_args)
                         except (json.JSONDecodeError, ValueError):
                             if auto_heal_tool_calls:
-                                arguments = {"query": raw_args}
+                                heal_key = {
+                                    "python": "code",
+                                    "terminal": "command",
+                                    "render_html": "code",
+                                }.get(tool_name, "query")
+                                arguments = {heal_key: raw_args}
                             else:
                                 arguments = {"raw": raw_args}
                     else:
@@ -5195,14 +5242,18 @@ class LlamaCppBackend:
                         )
                     else:
                         status_text = f"Calling: {tool_name}"
-                    yield {"type": "status", "text": status_text}
+                    _repeat_render_html = (
+                        tool_name == "render_html" and _render_html_succeeded
+                    )
+                    if not _repeat_render_html:
+                        yield {"type": "status", "text": status_text}
 
-                    yield {
-                        "type": "tool_start",
-                        "tool_name": tool_name,
-                        "tool_call_id": tc.get("id", ""),
-                        "arguments": arguments,
-                    }
+                        yield {
+                            "type": "tool_start",
+                            "tool_name": tool_name,
+                            "tool_call_id": tc.get("id", ""),
+                            "arguments": arguments,
+                        }
 
                     # ── Duplicate call detection ──────────────
                     # str(dict) is stable here: arguments always comes from
@@ -5210,7 +5261,9 @@ class LlamaCppBackend:
                     # so insertion order is deterministic (Python 3.7+).
                     _tc_key = tool_name + str(arguments)
                     _prev = _tool_call_history[-1] if _tool_call_history else None
-                    if _prev and _prev[0] == _tc_key and not _prev[1]:
+                    if _repeat_render_html:
+                        result = RENDER_HTML_REPEAT_NUDGE
+                    elif _prev and _prev[0] == _tc_key and not _prev[1]:
                         result = (
                             "You already made this exact call. "
                             "Do not repeat the same tool call. "
@@ -5248,12 +5301,13 @@ class LlamaCppBackend:
                                 session_id = session_id,
                             )
 
-                    yield {
-                        "type": "tool_end",
-                        "tool_name": tool_name,
-                        "tool_call_id": tc.get("id", ""),
-                        "result": result,
-                    }
+                    if not _repeat_render_html:
+                        yield {
+                            "type": "tool_end",
+                            "tool_name": tool_name,
+                            "tool_call_id": tc.get("id", ""),
+                            "result": result,
+                        }
 
                     # Nudge model to try a different approach on errors
                     _error_prefixes = (
@@ -5269,6 +5323,8 @@ class LlamaCppBackend:
                     _is_error = isinstance(result, str) and result.lstrip().startswith(
                         _error_prefixes
                     )
+                    if tool_name == "render_html" and not _is_error:
+                        _render_html_succeeded = True
                     _tool_call_history.append((_tc_key, _is_error))
                     # Strip image sentinel before feeding result to the LLM
                     # (the full result with sentinel is still yielded via
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index 73bb3d090a..94e9e303ab 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -18,6 +18,7 @@ cumulative text and dispatches them via ``core.inference.tools``.
 """
 
 import json
+import re
 import threading
 from typing import Callable, Generator, Optional
 from urllib.parse import urlparse
@@ -27,6 +28,7 @@ from loggers import get_logger
 from core.inference.tool_call_parser import (
     BUDGET_EXHAUSTED_NUDGE,
     DUPLICATE_CALL_NUDGE,
+    RENDER_HTML_REPEAT_NUDGE,
     TOOL_ERROR_NUDGE,
     TOOL_ERROR_PREFIXES,
     TOOL_XML_SIGNALS,
@@ -66,7 +68,34 @@ def _status_for_tool(tool_name: str, arguments: dict) -> str:
     return f"Calling: {tool_name}"
 
 
-_CANONICAL_HEAL_ARG = {"python": "code", "terminal": "command"}
+_CANONICAL_HEAL_ARG = {
+    "python": "code",
+    "terminal": "command",
+    "render_html": "code",
+}
+
+
+_FUNCTION_SIGNAL_RE = re.compile(r"<function=([\w-]+)>")
+_TOOL_CALL_NAME_RE = re.compile(r'"name"\s*:\s*"([\w-]+)"')
+
+
+def _detect_render_html_tool_start(content: str) -> bool:
+    """Return True when the first drained tool call is clearly render_html."""
+    function_match = _FUNCTION_SIGNAL_RE.search(content)
+    tool_call_index = content.find("<tool_call>")
+    if not function_match and tool_call_index < 0:
+        return False
+
+    if function_match and (
+        tool_call_index < 0 or function_match.start() < tool_call_index
+    ):
+        return function_match.group(1) == "render_html"
+
+    if tool_call_index >= 0:
+        name_match = _TOOL_CALL_NAME_RE.search(content[tool_call_index:])
+        return bool(name_match and name_match.group(1) == "render_html")
+
+    return False
 
 
 def _coerce_arguments(raw_args, *, heal: bool, tool_name: str = "") -> dict:
@@ -135,6 +164,7 @@ def run_safetensors_tool_loop(
     """
     conversation = list(messages)
     tool_call_history: list[tuple[str, bool]] = []
+    render_html_succeeded = False
     final_attempt_done = False
     allowed_tool_names = {
         (tool.get("function") or {}).get("name")
@@ -161,6 +191,8 @@ def run_safetensors_tool_loop(
         content_accum = ""
         cumulative_display = ""
         last_emitted = ""
+        provisional_render_html_started = False
+        provisional_render_html_id = f"call_{next_call_id}"
 
         gen = single_turn(conversation)
         prev_cumulative = ""
@@ -179,6 +211,18 @@ def run_safetensors_tool_loop(
             content_accum += delta
 
             if detect_state == _state_draining:
+                if (
+                    not render_html_succeeded
+                    and not provisional_render_html_started
+                    and _detect_render_html_tool_start(content_accum)
+                ):
+                    provisional_render_html_started = True
+                    yield {
+                        "type": "tool_start",
+                        "tool_name": "render_html",
+                        "tool_call_id": provisional_render_html_id,
+                        "arguments": {},
+                    }
                 continue
 
             if detect_state == _state_streaming:
@@ -196,6 +240,18 @@ def run_safetensors_tool_loop(
                         yield {"type": "content", "text": cleaned_before}
                     cumulative_display = candidate
                     detect_state = _state_draining
+                    if (
+                        not render_html_succeeded
+                        and not provisional_render_html_started
+                        and _detect_render_html_tool_start(content_accum)
+                    ):
+                        provisional_render_html_started = True
+                        yield {
+                            "type": "tool_start",
+                            "tool_name": "render_html",
+                            "tool_call_id": provisional_render_html_id,
+                            "arguments": {},
+                        }
                     continue
                 cumulative_display = candidate
                 cleaned = strip_tool_markup(cumulative_display)
@@ -222,6 +278,18 @@ def run_safetensors_tool_loop(
 
             if is_match:
                 detect_state = _state_draining
+                if (
+                    not render_html_succeeded
+                    and not provisional_render_html_started
+                    and _detect_render_html_tool_start(content_accum)
+                ):
+                    provisional_render_html_started = True
+                    yield {
+                        "type": "tool_start",
+                        "tool_name": "render_html",
+                        "tool_call_id": provisional_render_html_id,
+                        "arguments": {},
+                    }
             elif is_prefix and len(stripped) < _MAX_BUFFER_CHARS:
                 continue
             else:
@@ -282,6 +350,13 @@ def run_safetensors_tool_loop(
                 # literal "<tool_call>" prose is preserved.
                 if content_accum:
                     yield {"type": "content", "text": content_accum}
+                if provisional_render_html_started:
+                    yield {
+                        "type": "tool_end",
+                        "tool_name": "render_html",
+                        "tool_call_id": provisional_render_html_id,
+                        "result": "Error: render_html tool call could not be parsed.",
+                    }
                 yield {"type": "status", "text": ""}
                 return
             content_text = strip_tool_markup(content_accum, final = True)
@@ -308,16 +383,20 @@ def run_safetensors_tool_loop(
                 tool_name = tool_name,
             )
 
-            yield {"type": "status", "text": _status_for_tool(tool_name, arguments)}
-            yield {
-                "type": "tool_start",
-                "tool_name": tool_name,
-                "tool_call_id": tc.get("id", ""),
-                "arguments": arguments,
-            }
+            repeat_render_html = tool_name == "render_html" and render_html_succeeded
+            if not repeat_render_html:
+                yield {"type": "status", "text": _status_for_tool(tool_name, arguments)}
+                yield {
+                    "type": "tool_start",
+                    "tool_name": tool_name,
+                    "tool_call_id": tc.get("id", ""),
+                    "arguments": arguments,
+                }
 
             tc_key = tool_name + str(arguments)
-            if allowed_tool_names and tool_name not in allowed_tool_names:
+            if repeat_render_html:
+                result = RENDER_HTML_REPEAT_NUDGE
+            elif allowed_tool_names and tool_name not in allowed_tool_names:
                 result = (
                     f"Error: tool '{tool_name}' is not enabled for this "
                     "request. Use one of the enabled tools or provide a "
@@ -345,16 +424,19 @@ def run_safetensors_tool_loop(
                         logger.exception("Tool %s raised: %s", tool_name, exc)
                         result = f"Error: tool raised an exception: {exc}"
 
-            yield {
-                "type": "tool_end",
-                "tool_name": tool_name,
-                "tool_call_id": tc.get("id", ""),
-                "result": result,
-            }
+            if not repeat_render_html:
+                yield {
+                    "type": "tool_end",
+                    "tool_name": tool_name,
+                    "tool_call_id": tc.get("id", ""),
+                    "result": result,
+                }
 
             is_error = isinstance(result, str) and result.lstrip().startswith(
                 TOOL_ERROR_PREFIXES
             )
+            if tool_name == "render_html" and not is_error:
+                render_html_succeeded = True
             tool_call_history.append((tc_key, is_error))
 
             # Strip frontend image sentinel from the model's view.
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index 2f94990623..dacbc19ac0 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -49,6 +49,12 @@ DUPLICATE_CALL_NUDGE = (
     "provide your final answer now."
 )
 
+RENDER_HTML_REPEAT_NUDGE = (
+    "Error: render_html was already called for this response. Do not call "
+    "render_html again in this response unless the user asks for changes. "
+    "Provide the final answer now."
+)
+
 TOOL_ERROR_NUDGE = (
     "\n\nThe tool call encountered an issue. Please try a different "
     "approach or rephrase your request."
@@ -70,6 +76,20 @@ _TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
 # `issue-number`, `repo-name`); using `\w+` here dropped those keys.
 _TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>\s*")
 _TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
+_PARAM_CLOSE_TAG = "</parameter>"
+_FUNC_CLOSE_TAG = "</function>"
+
+
+def _inside_open_parameter(content: str, pos: int) -> bool:
+    """Return True when ``pos`` falls inside an unclosed parameter value."""
+    last_param_start = -1
+    for match in _TC_PARAM_START_RE.finditer(content, 0, pos):
+        last_param_start = match.start()
+    if last_param_start < 0:
+        return False
+    last_param_close = content.rfind(_PARAM_CLOSE_TAG, 0, pos)
+    last_func_close = content.rfind(_FUNC_CLOSE_TAG, 0, pos)
+    return last_param_start > max(last_param_close, last_func_close)
 
 
 def strip_tool_markup(text: str, *, final: bool = False) -> str:
@@ -151,7 +171,11 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
     # optional; don't use </function> as body boundary because code
     # values can contain that literal.
     if not tool_calls:
-        func_starts = list(_TC_FUNC_START_RE.finditer(content))
+        func_starts = [
+            fm
+            for fm in _TC_FUNC_START_RE.finditer(content)
+            if not _inside_open_parameter(content, fm.start())
+        ]
         for idx, fm in enumerate(func_starts):
             func_name = fm.group(1)
             body_start = fm.end()
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index baf1236456..eecb84ca27 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -514,7 +514,35 @@ TERMINAL_TOOL = {
     },
 }
 
-ALL_TOOLS = [WEB_SEARCH_TOOL, PYTHON_TOOL, TERMINAL_TOOL]
+RENDER_HTML_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "render_html",
+        "description": (
+            "Render a self-contained HTML/CSS/JavaScript artifact for the user. "
+            "Call this at most once per assistant response unless the user "
+            "explicitly asks for changes in that response. Future user requests "
+            "for new artifacts may call render_html once. Put the entire document "
+            "in code, including any CSS in <style> tags and JavaScript in <script> tags."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "A complete self-contained HTML document.",
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Short display title for the artifact.",
+                },
+            },
+            "required": ["code"],
+        },
+    },
+}
+
+ALL_TOOLS = [WEB_SEARCH_TOOL, PYTHON_TOOL, TERMINAL_TOOL, RENDER_HTML_TOOL]
 
 
 # OpenAI's function.name regex: ^[a-zA-Z0-9_-]{1,64}$ -- enforced before
@@ -608,6 +636,25 @@ async def get_enabled_mcp_tools() -> list[dict]:
 _TIMEOUT_UNSET = object()
 
 
+def _render_html_result(arguments: dict) -> str:
+    code = arguments.get("code")
+    if not isinstance(code, str) or not code.strip():
+        return "Error: render_html requires a non-empty code string."
+    title = arguments.get("title")
+    if isinstance(title, str) and title.strip():
+        safe_title = title.strip()[:120]
+        return (
+            f"Rendered HTML artifact: {safe_title}. Do not call render_html "
+            "again in this response unless the user asks for changes. For a later "
+            "user request for a new artifact, call render_html once."
+        )
+    return (
+        "Rendered HTML artifact. Do not call render_html again in this response "
+        "unless the user asks for changes. For a later user request for a new "
+        "artifact, call render_html once."
+    )
+
+
 def execute_tool(
     name: str,
     arguments: dict,
@@ -625,6 +672,8 @@ def execute_tool(
         f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}"
     )
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
+    if name == "render_html":
+        return _render_html_result(arguments)
     if name.startswith(MCP_TOOL_PREFIX):
         try:
             _, server_id, tool_name = name.split("__", 2)
diff --git a/studio/backend/main.py b/studio/backend/main.py
index b6cf58a02c..2768f56f49 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -435,6 +435,7 @@ from starlette.requests import Request as _StarletteRequest  # noqa: E402
 
 
 _CSP_SCRIPT_NONCE_HEADER = "x-internal-script-nonce"
+_ARTIFACT_PREVIEW_FRAME_PATH = "/api/inference/artifact-preview-frame"
 
 
 # /content is Colab's working directory — more reliable than env vars which
@@ -488,6 +489,7 @@ def _build_csp(script_nonce: "str | None" = None) -> str:
         "style-src 'self' 'unsafe-inline'; "
         f"{script_src}; "
         "font-src 'self' data:; "
+        "frame-src 'self'; "
         f"frame-ancestors {frame_ancestors}; "
         "form-action 'self'; "
         "base-uri 'self'"
@@ -506,13 +508,13 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         response.headers.setdefault("Content-Security-Policy", _build_csp(nonce))
         # Omit X-Frame-Options in Colab — CSP frame-ancestors handles it, and
         # DENY would block serve_kernel_port_as_iframe regardless of CSP.
-        if not _IS_COLAB:
+        if not _IS_COLAB and request.url.path != _ARTIFACT_PREVIEW_FRAME_PATH:
             response.headers.setdefault("X-Frame-Options", "DENY")
         response.headers.setdefault("X-Content-Type-Options", "nosniff")
         response.headers.setdefault("Referrer-Policy", "no-referrer")
         response.headers.setdefault(
             "Permissions-Policy",
-            "camera=(), microphone=(), geolocation=(), interest-cohort=()",
+            "camera=(), microphone=(), geolocation=()",
         )
         response.headers["server"] = "unsloth-studio"
         return response
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index bb1bd394d1..9c3572bd3a 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -709,11 +709,12 @@ class ChatCompletionRequest(BaseModel):
     enabled_tools: Optional[list[str]] = Field(
         None,
         description = (
-            "[x-unsloth] List of enabled tool names. Local GGUF models accept "
-            "['web_search', 'python', 'terminal']. External providers accept "
-            "['web_search', 'web_fetch', 'code_execution'] for Anthropic and "
-            "['web_search', 'code_execution'] for OpenAI Responses. If None, "
-            "all local tools are enabled and no server-side tools are forwarded."
+            "[x-unsloth] List of enabled tool names. Local GGUF/safetensors models "
+            "accept ['web_search', 'python', 'terminal', 'render_html']. External "
+            "providers accept ['web_search', 'web_fetch', 'code_execution'] for "
+            "Anthropic and ['web_search', 'code_execution', 'image_generation'] for "
+            "OpenAI Responses. If None, all local tools are enabled and no "
+            "server-side tools are forwarded."
         ),
     )
     mcp_enabled: Optional[bool] = Field(
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index ed808040d2..e64e5ca5c7 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -134,6 +134,8 @@ class ChatSettingsPayload(BaseModel):
         Literal["none", "minimal", "low", "medium", "high", "max", "xhigh"]
     ] = None
     preserveThinking: Optional[bool] = None
+    collapseHtmlArtifacts: Optional[bool] = None
+    allowArtifactNetworkAccess: Optional[bool] = None
     autoHealToolCalls: Optional[bool] = None
     maxToolCallsPerMessage: Optional[int] = Field(default = None, ge = 1)
     toolCallTimeout: Optional[int] = Field(default = None, ge = 1)
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 7d1c7b2488..fbe8cf6a92 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -239,6 +239,135 @@ router = APIRouter()
 studio_router = APIRouter()
 
 
+_ARTIFACT_PREVIEW_FRAME_ANCESTORS = "'self' tauri://localhost http://tauri.localhost"
+_ARTIFACT_PREVIEW_FRAME_STRICT_CSP = (
+    "default-src 'none'; "
+    "script-src 'unsafe-inline'; "
+    "style-src 'unsafe-inline'; "
+    "img-src data: blob:; "
+    "font-src data:; "
+    "media-src data: blob:; "
+    "connect-src 'none'; "
+    "object-src 'none'; "
+    "base-uri 'none'; "
+    "form-action 'none'; "
+    f"frame-ancestors {_ARTIFACT_PREVIEW_FRAME_ANCESTORS}; "
+    "sandbox allow-scripts"
+)
+_ARTIFACT_PREVIEW_FRAME_NETWORK_CSP = (
+    "default-src http: https: data: blob:; "
+    "script-src 'unsafe-inline' 'unsafe-eval' http: https: data: blob:; "
+    "script-src-elem 'unsafe-inline' http: https: data: blob:; "
+    "style-src 'unsafe-inline' http: https: data: blob:; "
+    "style-src-elem 'unsafe-inline' http: https: data: blob:; "
+    "img-src http: https: data: blob:; "
+    "font-src http: https: data: blob:; "
+    "media-src http: https: data: blob:; "
+    "connect-src http: https: ws: wss: data: blob:; "
+    "worker-src http: https: blob:; "
+    "object-src 'none'; "
+    "base-uri 'none'; "
+    "form-action 'none'; "
+    f"frame-ancestors {_ARTIFACT_PREVIEW_FRAME_ANCESTORS}; "
+    "sandbox allow-scripts"
+)
+_ARTIFACT_PREVIEW_FRAME_HTML = """<!doctype html>
+<html>
+  <head><meta charset=\"utf-8\" /></head>
+  <body>
+    <script>
+      (() => {
+        const createMemoryStorage = () => {
+          const data = new Map();
+          return {
+            get length() { return data.size; },
+            key: (index) => Array.from(data.keys())[index] ?? null,
+            getItem: (key) => data.has(String(key)) ? data.get(String(key)) : null,
+            setItem: (key, value) => data.set(String(key), String(value)),
+            removeItem: (key) => data.delete(String(key)),
+            clear: () => data.clear(),
+          };
+        };
+        const installStorageFallback = (name) => {
+          try {
+            void window[name];
+            return;
+          } catch {
+            // Opaque-origin sandboxed frames throw SecurityError for Web Storage.
+          }
+          try {
+            Object.defineProperty(window, name, {
+              value: createMemoryStorage(),
+              configurable: true,
+            });
+          } catch {
+            // Leave the sandbox failure contained in the artifact if the
+            // browser refuses to shadow the Web Storage accessor.
+          }
+        };
+        const installStorageFallbacks = () => {
+          installStorageFallback("localStorage");
+          installStorageFallback("sessionStorage");
+        };
+        const render = (html) => {
+          installStorageFallbacks();
+          document.open();
+          document.write(html);
+          document.close();
+        };
+        installStorageFallbacks();
+        window.addEventListener("message", (event) => {
+          const data = event.data;
+          if (!data || data.type !== "unsloth:artifact-html" || typeof data.html !== "string") return;
+          render(data.html);
+        });
+      })();
+    </script>
+  </body>
+</html>"""
+
+
+@studio_router.get("/artifact-preview-frame", include_in_schema = False)
+async def artifact_preview_frame(
+    request: Request,
+    allow_network: bool = False,
+    token: Optional[str] = None,
+):
+    """Serve the opaque sandbox shell used for client-side HTML artifacts."""
+
+    if allow_network:
+        auth_header = request.headers.get("authorization")
+        if auth_header and auth_header.lower().startswith("bearer "):
+            jwt_token = auth_header[7:]
+        elif token:
+            jwt_token = token
+        else:
+            raise HTTPException(
+                status_code = status.HTTP_401_UNAUTHORIZED,
+                detail = "Missing authentication token",
+            )
+        from fastapi.security import HTTPAuthorizationCredentials
+
+        creds = HTTPAuthorizationCredentials(scheme = "Bearer", credentials = jwt_token)
+        await get_current_subject(creds)
+
+    csp = (
+        _ARTIFACT_PREVIEW_FRAME_NETWORK_CSP
+        if allow_network
+        else _ARTIFACT_PREVIEW_FRAME_STRICT_CSP
+    )
+    return Response(
+        content = _ARTIFACT_PREVIEW_FRAME_HTML,
+        media_type = "text/html; charset=utf-8",
+        headers = {
+            "Cache-Control": "no-store",
+            "Content-Security-Policy": csp,
+            "Referrer-Policy": "no-referrer",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
 def _detect_safetensors_features(backend, chat_template: Optional[str]) -> dict:
     """Classify reasoning/tool capabilities via the GGUF classifier so
     flags match across backends. gpt-oss is overridden because Harmony
@@ -419,13 +548,28 @@ async def _await_cancel_then_close(cancel_event, resp) -> None:
         return
 
 
-# Appended to tool-use nudge to discourage plan-without-action
+# Appended to tool-use nudge to discourage plan-without-action.
+# Keep render_html guidance gated to turns where the artifact tool is actually
+# present in the tool schema; otherwise small local models can hallucinate a
+# missing tool call instead of following the fenced-HTML fallback prompt.
 _TOOL_ACTION_NUDGE = (
     " IMPORTANT: Always call tools directly -- never write code yourself."
     " Never describe what you plan to do -- just call the tool immediately."
-    " For any code request, call the python tool. For any factual question, call web_search."
-    " Do NOT output code blocks -- use the python tool instead."
+    " For non-artifact code requests, call the python tool when it is available."
+    " For factual questions that require current information, call web_search when it is available."
+    " Do NOT output raw code blocks when an enabled tool can satisfy the request."
 )
+_ARTIFACT_TOOL_ACTION_NUDGE = (
+    " For HTML, CSS, or JavaScript artifact requests, call render_html once when "
+    "it is available. After render_html succeeds, do not call it again in the "
+    "same response unless the user asks for changes. Future user requests for "
+    "new artifacts may call render_html once."
+)
+
+
+def _tool_action_nudge(has_artifact: bool) -> str:
+    return _TOOL_ACTION_NUDGE + (_ARTIFACT_TOOL_ACTION_NUDGE if has_artifact else "")
+
 
 # Strip tool-call XML the speculative buffer in core/inference/llama_cpp.py
 # split across the visible/DRAIN boundary. Four leak shapes:
@@ -2698,6 +2842,7 @@ async def openai_chat_completions(
             _tool_names = {t["function"]["name"] for t in tools_to_use}
             _has_web = "web_search" in _tool_names
             _has_code = "python" in _tool_names or "terminal" in _tool_names
+            _has_artifact = "render_html" in _tool_names
 
             _date_line = f"The current date is {_date.today().isoformat()}."
 
@@ -2719,34 +2864,34 @@ async def openai_chat_completions(
                 "Use code execution for math, calculations, data processing, "
                 "or to parse and analyze information from tool results."
             )
+            _artifact_tips = (
+                "Use render_html for HTML, CSS, or JavaScript artifact requests "
+                "with one complete self-contained HTML document in the code argument. "
+                "Call it once, then do not call it again in the same response unless "
+                "the user asks for changes. Future user requests for new artifacts may "
+                "call render_html once."
+            )
 
-            if _has_web and _has_code:
+            _tool_tip_parts = []
+            if _has_web:
+                _tool_tip_parts.append(_web_tips)
+            if _has_code:
+                _tool_tip_parts.append(_code_tips)
+            if _has_artifact:
+                _tool_tip_parts.append(_artifact_tips)
+
+            if _tool_tip_parts:
                 _nudge = (
                     _date_line + " "
                     "You have access to tools. When appropriate, prefer using "
                     "tools rather than answering from memory. "
-                    + _web_tips
-                    + " "
-                    + _code_tips
-                )
-            elif _has_code:
-                _nudge = (
-                    _date_line + " "
-                    "You have access to tools. When appropriate, prefer using "
-                    "code execution rather than answering from memory. " + _code_tips
-                )
-            elif _has_web:
-                _nudge = (
-                    _date_line + " "
-                    "You have access to tools. When appropriate, prefer using "
-                    "web search for up-to-date or uncertain factual "
-                    "information rather than answering from memory. " + _web_tips
+                    + " ".join(_tool_tip_parts)
                 )
             else:
                 _nudge = ""
 
             if _nudge:
-                _nudge += _TOOL_ACTION_NUDGE
+                _nudge += _tool_action_nudge(_has_artifact)
                 # Append nudge to system prompt (preserve user's prompt)
                 if system_prompt:
                     system_prompt = system_prompt.rstrip() + "\n\n" + _nudge
@@ -3221,6 +3366,7 @@ async def openai_chat_completions(
         _sf_tool_names = {t["function"]["name"] for t in _sf_tools_to_use}
         _sf_has_web = "web_search" in _sf_tool_names
         _sf_has_code = "python" in _sf_tool_names or "terminal" in _sf_tool_names
+        _sf_has_artifact = "render_html" in _sf_tool_names
 
         _sf_date_line = f"The current date is {_date.today().isoformat()}."
         _sf_model_size_b = _extract_model_size_b(model_name)
@@ -3239,35 +3385,35 @@ async def openai_chat_completions(
             "Use code execution for math, calculations, data processing, "
             "or to parse and analyze information from tool results."
         )
+        _sf_artifact_tips = (
+            "Use render_html for HTML, CSS, or JavaScript artifact requests "
+            "with one complete self-contained HTML document in the code argument. "
+            "Call it once, then do not call it again in the same response unless "
+            "the user asks for changes. Future user requests for new artifacts may "
+            "call render_html once."
+        )
 
-        if _sf_has_web and _sf_has_code:
+        _sf_tool_tip_parts = []
+        if _sf_has_web:
+            _sf_tool_tip_parts.append(_sf_web_tips)
+        if _sf_has_code:
+            _sf_tool_tip_parts.append(_sf_code_tips)
+        if _sf_has_artifact:
+            _sf_tool_tip_parts.append(_sf_artifact_tips)
+
+        if _sf_tool_tip_parts:
             _sf_nudge = (
                 _sf_date_line + " "
                 "You have access to tools. When appropriate, prefer using "
                 "tools rather than answering from memory. "
-                + _sf_web_tips
-                + " "
-                + _sf_code_tips
-            )
-        elif _sf_has_code:
-            _sf_nudge = (
-                _sf_date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "code execution rather than answering from memory. " + _sf_code_tips
-            )
-        elif _sf_has_web:
-            _sf_nudge = (
-                _sf_date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "web search for up-to-date or uncertain factual "
-                "information rather than answering from memory. " + _sf_web_tips
+                + " ".join(_sf_tool_tip_parts)
             )
         else:
             _sf_nudge = ""
 
         _sf_system_prompt = system_prompt
         if _sf_nudge:
-            _sf_nudge += _TOOL_ACTION_NUDGE
+            _sf_nudge += _tool_action_nudge(_sf_has_artifact)
             if _sf_system_prompt:
                 _sf_system_prompt = _sf_system_prompt.rstrip() + "\n\n" + _sf_nudge
             else:
@@ -4914,6 +5060,7 @@ async def anthropic_messages(
         _tool_names = {t["function"]["name"] for t in openai_tools}
         _has_web = "web_search" in _tool_names
         _has_code = "python" in _tool_names or "terminal" in _tool_names
+        _has_artifact = "render_html" in _tool_names
 
         _date_line = f"The current date is {_date.today().isoformat()}."
         _model_size_b = _extract_model_size_b(model_name)
@@ -4932,34 +5079,33 @@ async def anthropic_messages(
             "Use code execution for math, calculations, data processing, "
             "or to parse and analyze information from tool results."
         )
+        _artifact_tips = (
+            "Use render_html for HTML, CSS, or JavaScript artifact requests "
+            "with one complete self-contained HTML document in the code argument. "
+            "Call it once, then do not call it again in the same response unless "
+            "the user asks for changes. Future user requests for new artifacts may "
+            "call render_html once."
+        )
 
-        if _has_web and _has_code:
+        _tool_tip_parts = []
+        if _has_web:
+            _tool_tip_parts.append(_web_tips)
+        if _has_code:
+            _tool_tip_parts.append(_code_tips)
+        if _has_artifact:
+            _tool_tip_parts.append(_artifact_tips)
+
+        if _tool_tip_parts:
             _nudge = (
                 _date_line + " "
                 "You have access to tools. When appropriate, prefer using "
-                "tools rather than answering from memory. "
-                + _web_tips
-                + " "
-                + _code_tips
-            )
-        elif _has_code:
-            _nudge = (
-                _date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "code execution rather than answering from memory. " + _code_tips
-            )
-        elif _has_web:
-            _nudge = (
-                _date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "web search for up-to-date or uncertain factual "
-                "information rather than answering from memory. " + _web_tips
+                "tools rather than answering from memory. " + " ".join(_tool_tip_parts)
             )
         else:
             _nudge = ""
 
         if _nudge:
-            _nudge += _TOOL_ACTION_NUDGE
+            _nudge += _tool_action_nudge(_has_artifact)
             # Inject into system prompt
             if openai_messages and openai_messages[0].get("role") == "system":
                 openai_messages[0]["content"] = (
@@ -5147,6 +5293,7 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
     baseline, not against turn N's final length.
     """
     content_blocks: list = []
+    tool_blocks_by_id: dict[str, AnthropicResponseToolUseBlock] = {}
     usage = {}
     prev_text = ""
 
@@ -5165,13 +5312,25 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
                 else:
                     content_blocks.append(AnthropicResponseTextBlock(text = new))
         elif etype == "tool_start":
-            content_blocks.append(
-                AnthropicResponseToolUseBlock(
-                    id = event["tool_call_id"],
-                    name = event["tool_name"],
-                    input = event.get("arguments", {}),
-                )
+            tool_call_id = event["tool_call_id"]
+            arguments = event.get("arguments", {})
+            existing_tool_block = (
+                tool_blocks_by_id.get(tool_call_id) if tool_call_id else None
             )
+            if existing_tool_block is not None:
+                if arguments or not existing_tool_block.input:
+                    existing_tool_block.input = arguments
+                if event.get("tool_name") and not existing_tool_block.name:
+                    existing_tool_block.name = event["tool_name"]
+            else:
+                tool_block = AnthropicResponseToolUseBlock(
+                    id = tool_call_id,
+                    name = event["tool_name"],
+                    input = arguments,
+                )
+                if tool_call_id:
+                    tool_blocks_by_id[tool_call_id] = tool_block
+                content_blocks.append(tool_block)
         elif etype == "tool_end":
             prev_text = ""
         elif etype == "metadata":
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index 842429d5af..634d02ad6c 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -38,6 +38,7 @@ from routes.inference import (
     _normalize_anthropic_openai_images,
     _select_anthropic_server_tools,
     _anthropic_requested_studio_tools,
+    _anthropic_tool_non_streaming,
     anthropic_messages,
 )
 from state.tool_policy import reset_tool_policy, set_tool_policy
@@ -551,6 +552,54 @@ class TestAnthropicStreamEmitter:
         assert "tool_use" in events[1]
         assert "input_json_delta" in events[2]
 
+    def test_duplicate_tool_start_merges_into_open_tool_block(self):
+        e = AnthropicStreamEmitter()
+        e.start("msg_1", "m")
+        first_events = e.feed(
+            {
+                "type": "tool_start",
+                "tool_name": "render_html",
+                "tool_call_id": "call_0",
+                "arguments": {},
+            }
+        )
+        second_events = e.feed(
+            {
+                "type": "tool_start",
+                "tool_name": "render_html",
+                "tool_call_id": "call_0",
+                "arguments": {"code": "<!doctype html><html></html>"},
+            }
+        )
+
+        first_payloads = [
+            json.loads(event.split("data: ")[1]) for event in first_events
+        ]
+        second_payloads = [
+            json.loads(event.split("data: ")[1]) for event in second_events
+        ]
+
+        tool_starts = [
+            payload
+            for payload in first_payloads + second_payloads
+            if payload["type"] == "content_block_start"
+            and payload["content_block"]["type"] == "tool_use"
+        ]
+        assert len(tool_starts) == 1
+        assert tool_starts[0]["content_block"]["id"] == "call_0"
+        assert second_payloads == [
+            {
+                "type": "content_block_delta",
+                "index": tool_starts[0]["index"],
+                "delta": {
+                    "type": "input_json_delta",
+                    "partial_json": json.dumps(
+                        {"code": "<!doctype html><html></html>"}
+                    ),
+                },
+            }
+        ]
+
     def test_tool_end_closes_tool_opens_new_text_block(self):
         e = AnthropicStreamEmitter()
         e.start("msg_1", "m")
@@ -674,6 +723,49 @@ class TestAnthropicStreamEmitter:
         assert parsed["delta"]["text"] == "After tool"
 
 
+# =====================================================================
+# Non-streaming tool response tests
+# =====================================================================
+
+
+class TestAnthropicToolNonStreaming:
+    def test_duplicate_tool_start_replaces_provisional_tool_block(self):
+        def _run_gen():
+            yield {
+                "type": "tool_start",
+                "tool_name": "render_html",
+                "tool_call_id": "call_0",
+                "arguments": {},
+            }
+            yield {
+                "type": "tool_start",
+                "tool_name": "render_html",
+                "tool_call_id": "call_0",
+                "arguments": {"code": "<!doctype html><html></html>"},
+            }
+            yield {
+                "type": "tool_end",
+                "tool_name": "render_html",
+                "tool_call_id": "call_0",
+                "result": "Rendered HTML artifact.",
+            }
+
+        response = asyncio.run(_anthropic_tool_non_streaming(_run_gen, "msg_1", "m"))
+        body = json.loads(response.body)
+        tool_blocks = [
+            block for block in body["content"] if block["type"] == "tool_use"
+        ]
+
+        assert tool_blocks == [
+            {
+                "type": "tool_use",
+                "id": "call_0",
+                "name": "render_html",
+                "input": {"code": "<!doctype html><html></html>"},
+            }
+        ]
+
+
 # =====================================================================
 # Pass-through emitter tests (client-side tool execution path)
 # =====================================================================
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index 923af87c4f..50f6011959 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -28,12 +28,14 @@ Edge cases under coverage:
 """
 
 import threading
+from typing import cast
 
 import pytest
 
 from core.inference import safetensors_agentic
 from core.inference.safetensors_agentic import (
     _coerce_arguments,
+    _detect_render_html_tool_start,
     run_safetensors_tool_loop,
 )
 from core.inference.tool_call_parser import (
@@ -97,6 +99,17 @@ class TestParser:
         assert len(result) == 1
         assert "print('hi')" in result[0]["function"]["arguments"]
 
+    def test_function_signal_inside_parameter_is_literal(self):
+        text = (
+            "<function=python>"
+            "<parameter=code>print('<function=render_html>')</parameter>"
+            "</function>"
+        )
+        result = parse_tool_calls_from_text(text)
+        assert len(result) == 1
+        assert result[0]["function"]["name"] == "python"
+        assert "<function=render_html>" in result[0]["function"]["arguments"]
+
     def test_multiple_calls(self):
         text = (
             '<tool_call>{"name":"web_search","arguments":{"query":"a"}}</tool_call>'
@@ -118,6 +131,18 @@ class TestParser:
         assert has_tool_signal("hi <function=foo>...")
         assert not has_tool_signal("hello world")
 
+    def test_render_html_start_detector_uses_first_tool(self):
+        assert _detect_render_html_tool_start("<function=render_html>")
+        assert _detect_render_html_tool_start(
+            '<tool_call>{"name":"render_html","arguments":{"code":"<html>"}'
+        )
+        assert not _detect_render_html_tool_start(
+            "<function=python><parameter=code>'<function=render_html>'"
+        )
+        assert not _detect_render_html_tool_start(
+            '<tool_call>{"name":"python","arguments":{"code":"<function=render_html>"}}'
+        )
+
     def test_strip_markup_closed(self):
         text = "before <tool_call>{}</tool_call> after"
         assert strip_tool_markup(text) == "before  after"
@@ -280,6 +305,104 @@ class TestLoopBasic:
         contents = [e for e in events if e["type"] == "content"]
         assert "Result: 1" in contents[-1]["text"]
 
+    def test_render_html_emits_provisional_tool_start(self):
+        exec_fn = FakeExecuteTool(["Rendered HTML artifact."])
+        turn_iter = iter(
+            [
+                [
+                    "<function=render_html>",
+                    "<parameter=code><!doctype html><html>",
+                    "<body>Hi</body></html></parameter></function>",
+                ],
+                ["Done."],
+            ]
+        )
+
+        def _gen(_messages):
+            chunks = next(turn_iter)
+            acc = ""
+            for chunk in chunks:
+                acc += chunk
+                yield acc
+
+        loop = run_safetensors_tool_loop(
+            single_turn = _gen,
+            messages = [{"role": "user", "content": "make html"}],
+            tools = [{"type": "function", "function": {"name": "render_html"}}],
+            execute_tool = exec_fn,
+        )
+        events = _collect_events(loop)
+        tool_starts = [e for e in events if e["type"] == "tool_start"]
+
+        assert len(tool_starts) == 2
+        assert tool_starts[0]["tool_name"] == "render_html"
+        assert tool_starts[0]["arguments"] == {}
+        assert tool_starts[1]["tool_name"] == "render_html"
+        assert "<!doctype html>" in tool_starts[1]["arguments"]["code"]
+        assert exec_fn.calls[0][0] == "render_html"
+        assert "<!doctype html>" in exec_fn.calls[0][1]["code"]
+
+    def test_python_tool_containing_render_html_signal_does_not_emit_provisional_start(
+        self,
+    ):
+        loop, exec_fn = _make_loop(
+            turns = [
+                [
+                    "<function=python>",
+                    "<parameter=code>print('<function=render_html>')",
+                    "</parameter></function>",
+                ],
+                ["Done."],
+            ],
+            exec_results = ["ok"],
+        )
+        events = _collect_events(loop)
+        tool_starts = [e for e in events if e["type"] == "tool_start"]
+
+        assert len(tool_starts) == 1
+        assert tool_starts[0]["tool_name"] == "python"
+        assert exec_fn.calls == [
+            ("python", {"code": "print('<function=render_html>')"})
+        ]
+
+    def test_render_html_success_blocks_second_artifact_call(self):
+        exec_fn = FakeExecuteTool(["Rendered HTML artifact."])
+        turn_iter = iter(
+            [
+                [
+                    '<tool_call>{"name":"render_html",',
+                    '"arguments":{"code":"<html>one</html>"}}',
+                ],
+                [
+                    '<tool_call>{"name":"render_html",',
+                    '"arguments":{"code":"<html>two</html>"}}',
+                ],
+                ["Done."],
+            ]
+        )
+
+        def _gen(_messages):
+            chunks = next(turn_iter)
+            acc = ""
+            for chunk in chunks:
+                acc += chunk
+                yield acc
+
+        loop = run_safetensors_tool_loop(
+            single_turn = _gen,
+            messages = [{"role": "user", "content": "make html"}],
+            tools = [{"type": "function", "function": {"name": "render_html"}}],
+            execute_tool = exec_fn,
+        )
+        events = _collect_events(loop)
+        tool_starts = [e for e in events if e["type"] == "tool_start"]
+
+        assert exec_fn.calls == [("render_html", {"code": "<html>one</html>"})]
+        assert [e["arguments"] for e in tool_starts] == [
+            {},
+            {"code": "<html>one</html>"},
+        ]
+
     def test_truncated_unclosed_tool_call(self):
         loop, exec_fn = _make_loop(
             turns = [
@@ -595,6 +718,7 @@ class TestChatTemplateHelper:
         tok = self._Tok({"tools", "enable_thinking"})
         self.apply(tok, [], tools = [{}], enable_thinking = True)
         assert tok.call_count == 1
+        assert tok.last_kwargs is not None
         assert "tools" in tok.last_kwargs
         assert "enable_thinking" in tok.last_kwargs
 
@@ -781,7 +905,7 @@ class TestGptOssNameDetection:
 
     def test_empty_or_none_returns_false(self):
         assert is_gpt_oss_model_name("") is False
-        assert is_gpt_oss_model_name(None) is False
+        assert is_gpt_oss_model_name(cast(str, None)) is False
 
 
 if __name__ == "__main__":
diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index d2c6208fda..8e1d0f03b7 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -3,18 +3,19 @@
 
 "use client";
 
+import { ArtifactCard, useChatRuntimeStore } from "@/features/chat";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { preprocessLaTeX } from "@/lib/latex";
 import { openLink } from "@/lib/open-link";
-import { INTERNAL, useMessagePartText } from "@assistant-ui/react";
+import { INTERNAL, useAuiState, useMessagePartText } from "@assistant-ui/react";
 import { Copy01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { createCodePlugin } from "./code-plugin";
 import { createMathPlugin } from "@streamdown/math";
 import { mermaid } from "@streamdown/mermaid";
-import { DownloadIcon, Maximize2Icon, Minimize2Icon } from "lucide-react";
+import { DownloadIcon } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Block, type BlockProps, Streamdown } from "streamdown";
+import { createCodePlugin } from "./code-plugin";
 import "katex/dist/katex.min.css";
 import { AudioPlayer } from "./audio-player";
 import { unslothDarkTheme, unslothLightTheme } from "./code-themes";
@@ -26,11 +27,7 @@ const code = createCodePlugin({
 const { withSmoothContextProvider } = INTERNAL;
 
 const STREAMDOWN_COMPONENTS = {
-  a: ({
-    href,
-    children,
-    ...props
-  }: React.ComponentProps<"a">) => (
+  a: ({ href, children, ...props }: React.ComponentProps<"a">) => (
     <a
       href={href}
       rel="noopener noreferrer"
@@ -59,6 +56,34 @@ type CodeFence = {
   source: string;
 };
 
+type ToolCallPartLike = {
+  type?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: unknown;
+};
+
+function isRenderableRenderHtmlToolPart(part: unknown): boolean {
+  const toolPart = part as ToolCallPartLike;
+  if (toolPart.type !== "tool-call" || toolPart.toolName !== "render_html") {
+    return false;
+  }
+  if (
+    typeof toolPart.result === "string" &&
+    toolPart.result.startsWith("Error:")
+  ) {
+    return false;
+  }
+  if (
+    typeof toolPart.result === "string" &&
+    toolPart.result.startsWith("Rendered HTML artifact")
+  ) {
+    return true;
+  }
+  const args = toolPart.args as { code?: unknown } | undefined;
+  return typeof args?.code === "string" && args.code.trim().length > 0;
+}
+
 function getMermaidSource(blockContent: string): string | null {
   const source = blockContent.match(MERMAID_SOURCE_RE)?.[1]?.trim();
   return source && source.length > 0 ? source : null;
@@ -123,7 +148,13 @@ function isHtmlFence(codeFence: CodeFence): boolean {
   return lang === "html" && !isSvgFence(codeFence);
 }
 
-const UNSAFE_SVG_RE = /<script[\s>]|on\w+\s*=|javascript:|<foreignObject[\s>]|<iframe[\s>]|<embed[\s>]|<object[\s>]/i;
+function isFullHtmlDocument(source: string): boolean {
+  const trimmed = source.trimStart();
+  return /^<!doctype\s+html\b/i.test(trimmed) || /^<html[\s>]/i.test(trimmed);
+}
+
+const UNSAFE_SVG_RE =
+  /<script[\s>]|on\w+\s*=|javascript:|<foreignObject[\s>]|<iframe[\s>]|<embed[\s>]|<object[\s>]/i;
 
 function sanitizeSvg(source: string): string | null {
   if (UNSAFE_SVG_RE.test(source)) return null;
@@ -145,96 +176,6 @@ function SvgPreview({ source }: { source: string }) {
   );
 }
 
-const HTML_PREVIEW_DEFAULT_HEIGHT = 400;
-const HTML_PREVIEW_MAX_HEIGHT = 800;
-
-function HtmlPreview({ source }: { source: string }) {
-  const iframeRef = useRef<HTMLIFrameElement>(null);
-  const [height, setHeight] = useState(HTML_PREVIEW_DEFAULT_HEIGHT);
-  const [enlarged, setEnlarged] = useState(false);
-
-  useEffect(() => {
-    const handler = (e: MessageEvent) => {
-      if (e.source !== iframeRef.current?.contentWindow) return;
-      if (typeof e.data?.htmlPreviewHeight === "number") {
-        setHeight(Math.min(Math.max(e.data.htmlPreviewHeight, 100), HTML_PREVIEW_MAX_HEIGHT));
-      }
-    };
-    window.addEventListener("message", handler);
-    return () => window.removeEventListener("message", handler);
-  }, []);
-
-  useEffect(() => {
-    if (!enlarged) return;
-    const handler = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setEnlarged(false);
-    };
-    window.addEventListener("keydown", handler);
-    return () => window.removeEventListener("keydown", handler);
-  }, [enlarged]);
-
-  const resizeScript = `<script>new ResizeObserver(()=>{
-parent.postMessage({htmlPreviewHeight:document.documentElement.scrollHeight},"*");
-}).observe(document.documentElement);</script>`;
-
-  const srcDoc = source + resizeScript;
-
-  if (enlarged) {
-    return (
-      <>
-        <div className="mt-2 overflow-hidden rounded-lg border border-border" style={{ height }}>
-          {/* Placeholder keeps layout stable while overlay is shown */}
-        </div>
-        <div
-          className="fixed inset-0 z-50 flex flex-col bg-background/80 backdrop-blur-sm"
-          onClick={(e) => { if (e.target === e.currentTarget) setEnlarged(false); }}
-        >
-          <div className="flex items-center justify-end gap-2 px-4 py-2">
-            <button
-              type="button"
-              className="flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-              onClick={() => setEnlarged(false)}
-              title="Exit fullscreen (Esc)"
-            >
-              <Minimize2Icon className="size-4" />
-              Exit fullscreen
-            </button>
-          </div>
-          <div className="mx-4 mb-4 flex-1 overflow-hidden rounded-lg border border-border bg-background">
-            <iframe
-              ref={iframeRef}
-              srcDoc={srcDoc}
-              sandbox="allow-scripts"
-              style={{ width: "100%", height: "100%", border: "none", display: "block" }}
-              title="HTML preview"
-            />
-          </div>
-        </div>
-      </>
-    );
-  }
-
-  return (
-    <div className="group/html-preview relative mt-2 overflow-hidden rounded-lg border border-border">
-      <button
-        type="button"
-        className="absolute top-2 right-2 z-10 rounded-md border border-border bg-background/80 p-1.5 text-muted-foreground opacity-0 transition-all hover:bg-muted hover:text-foreground group-hover/html-preview:opacity-100 supports-[backdrop-filter]:backdrop-blur"
-        onClick={() => setEnlarged(true)}
-        title="Enlarge preview"
-      >
-        <Maximize2Icon className="size-4" />
-      </button>
-      <iframe
-        ref={iframeRef}
-        srcDoc={srcDoc}
-        sandbox="allow-scripts"
-        style={{ width: "100%", height, border: "none", display: "block" }}
-        title="HTML preview"
-      />
-    </div>
-  );
-}
-
 function downloadTextFile(filename: string, text: string): void {
   const blob = new Blob([text], { type: "text/plain;charset=utf-8" });
   const url = URL.createObjectURL(blob);
@@ -346,6 +287,12 @@ function CodeBlockActions({
 }
 
 function StreamdownBlock(props: BlockProps) {
+  const shouldCollapseHtmlArtifacts = useChatRuntimeStore(
+    (state) => state.artifactsEnabled || state.collapseHtmlArtifacts,
+  );
+  const messageHasRenderableRenderHtmlTool = useAuiState(({ message }) =>
+    message.parts.some(isRenderableRenderHtmlToolPart),
+  );
   const hasMermaidFence = props.content.includes("```mermaid");
   const mermaidSource = getMermaidSource(props.content);
   const codeFence = getCodeFence(props.content);
@@ -362,7 +309,9 @@ function StreamdownBlock(props: BlockProps) {
     return (
       <div className="relative isolate">
         <div className="my-4 rounded-xl border border-border bg-muted/30 p-4">
-          <div className="mb-2 text-xs font-medium text-muted-foreground">svg</div>
+          <div className="mb-2 text-xs font-medium text-muted-foreground">
+            svg
+          </div>
           <pre className="overflow-x-auto text-xs text-muted-foreground whitespace-pre-wrap break-all">
             <code>{codeFence.source}</code>
           </pre>
@@ -371,10 +320,17 @@ function StreamdownBlock(props: BlockProps) {
     );
   }
 
-  if (props.isIncomplete && codeFence && isHtmlFence(codeFence)) {
+  if (
+    shouldCollapseHtmlArtifacts &&
+    !messageHasRenderableRenderHtmlTool &&
+    props.isIncomplete &&
+    codeFence &&
+    isHtmlFence(codeFence) &&
+    isFullHtmlDocument(codeFence.source)
+  ) {
     return (
       <div className="my-4 flex h-48 items-center justify-center rounded-xl border border-border bg-muted/30 text-sm text-muted-foreground animate-pulse">
-        Loading preview...
+        Loading artifact preview...
       </div>
     );
   }
@@ -389,8 +345,24 @@ function StreamdownBlock(props: BlockProps) {
   }
 
   if (codeFence) {
-    const svgSource = !props.isIncomplete && isSvgFence(codeFence) ? sanitizeSvg(codeFence.source) : null;
-    const htmlSource = !props.isIncomplete && isHtmlFence(codeFence) ? codeFence.source : null;
+    const svgSource =
+      !props.isIncomplete && isSvgFence(codeFence)
+        ? sanitizeSvg(codeFence.source)
+        : null;
+    const htmlSource =
+      shouldCollapseHtmlArtifacts &&
+      !messageHasRenderableRenderHtmlTool &&
+      !props.isIncomplete &&
+      isHtmlFence(codeFence) &&
+      isFullHtmlDocument(codeFence.source)
+        ? codeFence.source
+        : null;
+    if (htmlSource) {
+      return (
+        <ArtifactCard code={htmlSource} title="HTML preview" source="fence" />
+      );
+    }
+
     return (
       <>
         <div className="relative isolate">
@@ -402,7 +374,6 @@ function StreamdownBlock(props: BlockProps) {
           />
         </div>
         {svgSource && <SvgPreview source={svgSource} />}
-        {htmlSource && <HtmlPreview source={htmlSource} />}
       </>
     );
   }
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 51cf000863..26fc60d972 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -24,6 +24,7 @@ import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
 import { ToolGroup } from "@/components/assistant-ui/tool-group";
 import { CodeExecutionToolUI } from "@/components/assistant-ui/tool-ui-code-execution";
 import { ImageGenerationToolUI } from "@/components/assistant-ui/tool-ui-image-generation";
+import { RenderHtmlToolUI } from "@/components/assistant-ui/tool-ui-render-html";
 import { PythonToolUI } from "@/components/assistant-ui/tool-ui-python";
 import { TerminalToolUI } from "@/components/assistant-ui/tool-ui-terminal";
 import { WebSearchToolUI } from "@/components/assistant-ui/tool-ui-web-search";
@@ -73,6 +74,7 @@ import {
   ChevronLeftIcon,
   ChevronRightIcon,
   DownloadIcon,
+  FileTextIcon,
   GlobeIcon,
   HeadphonesIcon,
   LightbulbIcon,
@@ -1117,6 +1119,29 @@ const ImagesToggle: FC = () => {
   );
 };
 
+const ArtifactsToggle: FC = () => {
+  const modelLoaded = useChatRuntimeStore(
+    (s) => !!s.params.checkpoint && !s.modelLoading,
+  );
+  const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
+  const setArtifactsEnabled = useChatRuntimeStore((s) => s.setArtifactsEnabled);
+  const disabled = !modelLoaded;
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={() => setArtifactsEnabled(!artifactsEnabled)}
+      className="composer-pill-btn"
+      data-active={artifactsEnabled && !disabled ? "true" : "false"}
+      aria-label={artifactsEnabled ? "Disable artifacts" : "Enable artifacts"}
+    >
+      <FileTextIcon className="size-3.5" />
+      <span>Artifacts</span>
+    </button>
+  );
+};
+
 const ToolStatusDisplay: FC = () => {
   const toolStatus = useChatRuntimeStore((s) => s.toolStatus);
   const isThreadRunning = useAuiState(({ thread }) => thread.isRunning);
@@ -1189,6 +1214,7 @@ const ComposerAction: FC<{
         <WebSearchToggle />
         <CodeToolsToggle />
         <ImagesToggle />
+        <ArtifactsToggle />
       </div>
       <div className="flex items-center gap-1">
         <ComposerPrimitive.If dictation={false}>
@@ -1316,6 +1342,7 @@ const AssistantMessage: FC = () => {
                 terminal: TerminalToolUI,
                 code_execution: CodeExecutionToolUI,
                 image_generation: ImageGenerationToolUI,
+                render_html: RenderHtmlToolUI,
               },
               Fallback: ToolFallback,
             },
diff --git a/studio/frontend/src/components/assistant-ui/tool-group.tsx b/studio/frontend/src/components/assistant-ui/tool-group.tsx
index e91da4cee2..47d2b6cd0e 100644
--- a/studio/frontend/src/components/assistant-ui/tool-group.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-group.tsx
@@ -8,6 +8,7 @@ import {
   type FC,
   type PropsWithChildren,
 } from "react";
+import { useAuiState } from "@assistant-ui/react";
 import { ChevronDownIcon, LoaderIcon } from "lucide-react";
 import { Wrench01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
@@ -27,7 +28,8 @@ const toolGroupVariants = cva("aui-tool-group-root group/tool-group w-full", {
     variant: {
       outline: "corner-squircle rounded-lg border py-3",
       ghost: "rounded-lg bg-muted/10 py-2",
-      muted: "corner-squircle rounded-lg border border-muted-foreground/30 bg-muted/30 py-3",
+      muted:
+        "corner-squircle rounded-lg border border-muted-foreground/30 bg-muted/30 py-3",
     },
   },
   defaultVariants: { variant: "ghost" },
@@ -209,9 +211,17 @@ const ToolGroupImpl: FC<
   PropsWithChildren<{ startIndex: number; endIndex: number }>
 > = ({ children, startIndex, endIndex }) => {
   const toolCount = endIndex - startIndex + 1;
+  const containsArtifactTool = useAuiState(({ message }) =>
+    message.parts
+      .slice(startIndex, endIndex + 1)
+      .some(
+        (part) => part.type === "tool-call" && part.toolName === "render_html",
+      ),
+  );
 
-  // Single tool call — render directly without wrapper
-  if (toolCount <= 1) {
+  // Single tool calls and artifacts render directly so cards never hide inside
+  // a collapsed tool group.
+  if (toolCount <= 1 || containsArtifactTool) {
     return <>{children}</>;
   }
 
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
new file mode 100644
index 0000000000..d5b72e06ea
--- /dev/null
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import {
+  ArtifactCard,
+  useChatArtifactsStore,
+  useSelectedChatArtifact,
+} from "@/features/chat";
+import {
+  type ToolCallMessagePartComponent,
+  useAuiState,
+  useToolArgsStatus,
+} from "@assistant-ui/react";
+import { BrowserIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { memo, useEffect } from "react";
+
+// Context7 assistant-ui docs: tool UIs can read streaming args via
+// useToolArgsStatus, so render_html does not need to wait for tool completion.
+type RenderHtmlArgs = Record<string, unknown> & {
+  code?: string;
+  title?: string;
+};
+
+const RENDER_HTML_SESSION_STARTED_AT = Date.now();
+
+const RenderHtmlToolUIImpl: ToolCallMessagePartComponent = ({
+  args,
+  result,
+  status,
+  toolCallId,
+}) => {
+  const { propStatus } = useToolArgsStatus<RenderHtmlArgs>();
+  const parsedArgs = (args as RenderHtmlArgs) ?? {};
+  const code = typeof parsedArgs.code === "string" ? parsedArgs.code : "";
+  const hasCode = code.trim().length > 0;
+  const title =
+    typeof parsedArgs.title === "string" ? parsedArgs.title : "HTML artifact";
+  const isRunning = status?.type === "running";
+  const codeIsStreaming = propStatus.code === "streaming";
+
+  // Surface the backend error when the tool call completed with invalid
+  // args.  Backend success results start with "Rendered HTML artifact";
+  // error results start with "Error:".
+  const errorText =
+    status?.type === "complete" &&
+    typeof result === "string" &&
+    result.startsWith("Error:")
+      ? result
+      : null;
+  const messageId = useAuiState(({ message }) => message.id) ?? null;
+  const isMessageRunning = useAuiState(
+    ({ message }) => message.status?.type === "running",
+  );
+  const messageCreatedAtMs = useAuiState(({ message }) =>
+    message.createdAt instanceof Date ? message.createdAt.getTime() : null,
+  );
+  const isThreadRunning = useAuiState(({ thread }) => thread.isRunning);
+  const isLiveGeneratingArtifact =
+    isThreadRunning && isMessageRunning && (isRunning || codeIsStreaming);
+  const isStaleGeneratingArtifact =
+    !(isThreadRunning && isMessageRunning) && (isRunning || codeIsStreaming);
+  const messageCreatedThisSession =
+    messageCreatedAtMs != null &&
+    messageCreatedAtMs >= RENDER_HTML_SESSION_STARTED_AT - 1000;
+  const shouldAutoOpenArtifact =
+    (isLiveGeneratingArtifact && (hasCode || isRunning || codeIsStreaming)) ||
+    (hasCode && messageCreatedThisSession);
+  const selectedArtifact = useSelectedChatArtifact();
+  const closeArtifactSurface = useChatArtifactsStore(
+    (state) => state.closeArtifactSurface,
+  );
+
+  useEffect(() => {
+    if (!errorText) {
+      return;
+    }
+    if (!(messageId && toolCallId)) {
+      return;
+    }
+    if (selectedArtifact?.sourceToolCallId !== toolCallId) {
+      return;
+    }
+    if (selectedArtifact?.sourceMessageId !== messageId) {
+      return;
+    }
+    closeArtifactSurface();
+  }, [
+    closeArtifactSurface,
+    errorText,
+    messageId,
+    selectedArtifact,
+    toolCallId,
+  ]);
+
+  if (hasCode || (isLiveGeneratingArtifact && !errorText)) {
+    return (
+      <ArtifactCard
+        code={code}
+        title={title}
+        source="tool"
+        sourceToolCallId={toolCallId}
+        autoOpen={!errorText && shouldAutoOpenArtifact}
+        isStreaming={!errorText && isLiveGeneratingArtifact}
+      />
+    );
+  }
+
+  return (
+    <div className="relative my-2 flex min-h-[52px] w-full max-w-md items-center overflow-hidden rounded-lg border border-border/70 bg-muted/15 px-3 py-2 text-left dark:bg-muted/10">
+      <div className="relative z-10 flex min-w-0 flex-1 items-center gap-2.5">
+        <HugeiconsIcon
+          icon={BrowserIcon}
+          strokeWidth={1.75}
+          className="size-5 shrink-0 text-muted-foreground"
+        />
+        <span className="grid min-w-0 flex-1 gap-1">
+          <span className="truncate text-sm font-medium leading-tight text-foreground">
+            {errorText
+              ? "Artifact error"
+              : isStaleGeneratingArtifact
+                ? "Artifact interrupted"
+                : "Artifact unavailable"}
+          </span>
+          <span className="truncate text-[11px] leading-none text-muted-foreground">
+            {errorText ??
+              (isStaleGeneratingArtifact
+                ? "Refresh stopped this preview"
+                : "HTML artifact")}
+          </span>
+        </span>
+      </div>
+    </div>
+  );
+};
+
+export const RenderHtmlToolUI = memo(
+  RenderHtmlToolUIImpl,
+) as unknown as ToolCallMessagePartComponent;
+RenderHtmlToolUI.displayName = "RenderHtmlToolUI";
diff --git a/studio/frontend/src/components/ui/resizable.tsx b/studio/frontend/src/components/ui/resizable.tsx
index 519a1192da..de6309cae9 100644
--- a/studio/frontend/src/components/ui/resizable.tsx
+++ b/studio/frontend/src/components/ui/resizable.tsx
@@ -1,54 +1,54 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import type * as React from "react";
-import * as ResizablePrimitive from "react-resizable-panels";
-
-import { cn } from "@/lib/utils";
-
-function ResizablePanelGroup({
-  className,
-  ...props
-}: React.ComponentProps<typeof ResizablePrimitive.Group>): React.ReactElement {
-  return (
-    <ResizablePrimitive.Group
-      data-slot="resizable-panel-group"
-      className={cn(
-        "flex h-full w-full data-[panel-group-direction=vertical]:flex-col",
-        className,
-      )}
-      {...props}
-    />
-  );
-}
-
-function ResizablePanel({
-  ...props
-}: React.ComponentProps<typeof ResizablePrimitive.Panel>): React.ReactElement {
-  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
-}
-
-function ResizableHandle({
-  withHandle,
-  className,
-  ...props
-}: React.ComponentProps<typeof ResizablePrimitive.Separator> & {
-  withHandle?: boolean;
-}): React.ReactElement {
-  return (
-    <ResizablePrimitive.Separator
-      data-slot="resizable-handle"
-      className={cn(
-        "bg-border focus-visible:ring-ring relative flex w-px items-center justify-center after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-offset-1 focus-visible:outline-hidden data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-1 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:translate-x-0 data-[panel-group-direction=vertical]:after:-translate-y-1/2 [&[data-panel-group-direction=vertical]>div]:rotate-90",
-        className,
-      )}
-      {...props}
-    >
-      {withHandle && (
-        <div className="bg-border h-6 w-1 rounded-lg z-10 flex shrink-0" />
-      )}
-    </ResizablePrimitive.Separator>
-  );
-}
-
-export { ResizablePanelGroup, ResizablePanel, ResizableHandle };
+import type * as React from "react";
+import * as ResizablePrimitive from "react-resizable-panels";
+
+import { cn } from "@/lib/utils";
+
+function ResizablePanelGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.Group>): React.ReactElement {
+  return (
+    <ResizablePrimitive.Group
+      data-slot="resizable-panel-group"
+      className={cn(
+        "flex h-full w-full data-[panel-group-direction=vertical]:flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function ResizablePanel({
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.Panel>): React.ReactElement {
+  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
+}
+
+function ResizableHandle({
+  withHandle,
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.Separator> & {
+  withHandle?: boolean;
+}): React.ReactElement {
+  return (
+    <ResizablePrimitive.Separator
+      data-slot="resizable-handle"
+      className={cn(
+        "group bg-border/80 relative z-10 flex w-px cursor-col-resize items-center justify-center transition-[background-color,box-shadow] duration-150 ease-out after:absolute after:inset-y-0 after:left-1/2 after:w-2 after:-translate-x-1/2 hover:bg-primary/80 hover:shadow-[0_0_16px_rgba(23,184,139,0.55)] active:bg-primary/90 active:shadow-[0_0_18px_rgba(23,184,139,0.7)] focus-visible:bg-primary/80 focus-visible:ring-1 focus-visible:ring-primary/50 focus-visible:ring-offset-1 focus-visible:outline-hidden data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:cursor-row-resize data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-2 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:translate-x-0 data-[panel-group-direction=vertical]:after:-translate-y-1/2 [&[data-panel-group-direction=vertical]>div]:rotate-90",
+        className,
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="z-10 flex h-6 w-1 shrink-0 rounded-lg bg-border transition-[background-color,box-shadow,transform] duration-150 ease-out group-hover:scale-y-110 group-hover:bg-primary/80 group-hover:shadow-[0_0_12px_rgba(23,184,139,0.65)] group-active:bg-primary" />
+      )}
+    </ResizablePrimitive.Separator>
+  );
+}
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle };
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 666a304c3e..fc77fecaeb 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -19,7 +19,6 @@ import {
 } from "../external-providers";
 import { pickFriendlyContainerName } from "../lib/friendly-names";
 import {
-  EXTERNAL_MAX_OUTPUT_TOKENS,
   clampReasoningEffortToLevels,
   getExternalMaxOutputTokens,
   getExternalMinOutputTokens,
@@ -46,12 +45,12 @@ import type {
   OpenAIReasoningContentPart,
 } from "../types/api";
 import type { ChatModelSummary } from "../types/runtime";
-import { getImageInputUnavailableReason } from "../utils/image-input-support";
 import {
   getStoredChatThread,
   listStoredChatThreads,
   updateStoredChatThread,
 } from "../utils/chat-history-storage";
+import { getImageInputUnavailableReason } from "../utils/image-input-support";
 import {
   hasClosedThinkTag,
   parseAssistantContent,
@@ -775,36 +774,6 @@ function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
   return toolResults.length > 0 ? [base, ...toolResults] : [base];
 }
 
-// Thin singular wrapper: returns only the first serialized message
-// (without tool_calls or tool follow-ups) so the OpenAI image-edit
-// replay path can map a thread to flat OpenAI chat messages without
-// pulling in tool history.
-function toOpenAIMessage(message: RunMessage): {
-  role: "system" | "user" | "assistant";
-  content: OpenAIMessageContent;
-} | null {
-  const serialized = toOpenAIMessages(message);
-  if (serialized.length === 0) return null;
-  const first = serialized[0];
-  if (
-    first.role !== "system" &&
-    first.role !== "user" &&
-    first.role !== "assistant"
-  ) {
-    return null;
-  }
-  if (first.content === null || first.content === undefined) {
-    return null;
-  }
-  if (typeof first.content === "string" && !first.content) {
-    return null;
-  }
-  return {
-    role: first.role,
-    content: first.content as OpenAIMessageContent,
-  };
-}
-
 function extractImageBase64(input: string): string | undefined {
   if (!input) {
     return undefined;
@@ -1303,6 +1272,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         toolsEnabled,
         codeToolsEnabled,
         imageToolsEnabled,
+        artifactsEnabled,
         mcpEnabledForChat,
         webFetchToolsEnabled,
       } = runtime;
@@ -1537,36 +1507,62 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             "Do not return tool-call syntax inside your response.";
         }
       }
-      if (disabledToolGuard) {
-        const firstMessage = outboundMessages[0];
+      type OutboundMessage = (typeof outboundMessages)[number];
+      function addSystemInstruction(
+        targetMessages: OutboundMessage[],
+        text: string | null,
+      ): void {
+        if (!text) return;
+        const firstMessage = targetMessages[0];
         if (firstMessage?.role === "system") {
           if (typeof firstMessage.content === "string") {
-            outboundMessages[0] = {
+            targetMessages[0] = {
               ...firstMessage,
-              content: `${firstMessage.content}\n\n${disabledToolGuard}`,
+              content: `${firstMessage.content}\n\n${text}`,
             };
           } else {
-            outboundMessages[0] = {
+            targetMessages[0] = {
               ...firstMessage,
               content: [
                 ...(Array.isArray(firstMessage.content)
                   ? firstMessage.content
                   : []),
-                { type: "text", text: `\n\n${disabledToolGuard}` },
+                { type: "text", text: `\n\n${text}` },
               ],
             };
           }
-        } else {
-          outboundMessages.unshift({
-            role: "system",
-            content: disabledToolGuard,
-          });
+          return;
         }
+        targetMessages.unshift({ role: "system", content: text });
       }
+
       // Scan post-prune history so a refused user turn's image/audio
       // doesn't gate or mis-attribute the next non-refused turn.
       const imageBase64 = findLatestUserImageBase64(survivingMessages);
       const audioBase64 = findLatestUserAudioBase64(survivingMessages);
+      const hasOutboundImage = Boolean(imageBase64);
+
+      // Keep render_html local-only and mirror the backend image-turn gate.
+      // Artifacts are independent of Search/Code: if a local tool-capable
+      // model has Artifacts enabled, expose render_html even when no other
+      // tool pills are active.
+      const renderHtmlToolEnabledForThisTurn = Boolean(
+        !isExternalRequest &&
+          supportsTools &&
+          artifactsEnabled &&
+          !hasOutboundImage,
+      );
+      const artifactInstruction = artifactsEnabled
+        ? renderHtmlToolEnabledForThisTurn
+          ? "When the user asks for an HTML, CSS, or JavaScript artifact, call render_html once with one complete self-contained HTML document in the code argument. Embed CSS and JavaScript inside the document. After render_html succeeds, do not call it again in the same response unless the user asks for changes. Future user requests for new artifacts may call render_html once."
+          : "When the user asks for an HTML, CSS, or JavaScript artifact, return one complete self-contained fenced html code block. Embed CSS and JavaScript inside the document. Do not emit tool-call syntax."
+        : null;
+      const effectiveDisabledToolGuard =
+        disabledToolGuard && artifactsEnabled
+          ? `${disabledToolGuard} HTML, CSS, or JavaScript artifact requests can still be answered by following the artifact fallback instruction.`
+          : disabledToolGuard;
+      addSystemInstruction(outboundMessages, effectiveDisabledToolGuard);
+      addSystemInstruction(outboundMessages, artifactInstruction);
 
       // Block when ANY image is in the outbound payload (current or
       // prior turns) and the loaded model can't process images. Keeps
@@ -2093,12 +2089,19 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             ...(supportsPreserveThinking
               ? { preserve_thinking: preserveThinking }
               : {}),
-            ...(supportsTools && (toolsEnabled || codeToolsEnabled || mcpEnabledForChat)
+            ...(supportsTools &&
+            (toolsEnabled ||
+              codeToolsEnabled ||
+              renderHtmlToolEnabledForThisTurn ||
+              mcpEnabledForChat)
               ? {
                   enable_tools: true,
                   enabled_tools: [
                     ...(toolsEnabled ? ["web_search"] : []),
                     ...(codeToolsEnabled ? ["python", "terminal"] : []),
+                    ...(renderHtmlToolEnabledForThisTurn
+                      ? ["render_html"]
+                      : []),
                   ],
                   mcp_enabled: mcpEnabledForChat,
                   auto_heal_tool_calls:
@@ -2205,13 +2208,25 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     `${toolEvent.tool_name}_${Date.now()}`;
                   const toolArgs = (toolEvent.arguments ??
                     {}) as ToolCallMessagePart["args"];
-                  toolCallParts.push({
-                    type: "tool-call" as const,
-                    toolCallId: id,
-                    toolName: toolEvent.tool_name as string,
-                    argsText: JSON.stringify(toolArgs),
-                    args: toolArgs,
-                  });
+                  const idx = toolCallParts.findIndex(
+                    (p) => p.toolCallId === id,
+                  );
+                  if (idx !== -1) {
+                    toolCallParts[idx] = {
+                      ...toolCallParts[idx],
+                      toolName: toolEvent.tool_name as string,
+                      argsText: JSON.stringify(toolArgs),
+                      args: toolArgs,
+                    };
+                  } else {
+                    toolCallParts.push({
+                      type: "tool-call" as const,
+                      toolCallId: id,
+                      toolName: toolEvent.tool_name as string,
+                      argsText: JSON.stringify(toolArgs),
+                      args: toolArgs,
+                    });
+                  }
                 } else if (toolEvent.type === "tool_end") {
                   const id =
                     (toolEvent.tool_call_id as string) ||
diff --git a/studio/frontend/src/features/chat/api/chat-settings-api.ts b/studio/frontend/src/features/chat/api/chat-settings-api.ts
index 4208c90c76..1ac569efc7 100644
--- a/studio/frontend/src/features/chat/api/chat-settings-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-settings-api.ts
@@ -23,6 +23,8 @@ export interface PersistedChatSettings {
   autoTitle?: boolean;
   reasoningEffort?: ReasoningEffort;
   preserveThinking?: boolean;
+  collapseHtmlArtifacts?: boolean;
+  allowArtifactNetworkAccess?: boolean;
   autoHealToolCalls?: boolean;
   maxToolCallsPerMessage?: number;
   toolCallTimeout?: number;
diff --git a/studio/frontend/src/features/chat/artifacts/artifact-card.tsx b/studio/frontend/src/features/chat/artifacts/artifact-card.tsx
new file mode 100644
index 0000000000..76973e6e06
--- /dev/null
+++ b/studio/frontend/src/features/chat/artifacts/artifact-card.tsx
@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { cn } from "@/lib/utils";
+import { useAuiState } from "@assistant-ui/react";
+import { LayoutTwoColumnIcon as Layout2ColumnIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useLayoutEffect, useMemo } from "react";
+import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+import {
+  hasAutoOpenedArtifact,
+  rememberAutoOpenedArtifact,
+  useChatArtifactsStore,
+} from "./store";
+import {
+  type ChatArtifact,
+  type ChatArtifactSource,
+  createChatArtifact,
+} from "./types";
+
+export function ArtifactCard({
+  code,
+  title,
+  source,
+  sourceToolCallId,
+  sourceMessageId,
+  className,
+  autoOpen = false,
+  isStreaming = false,
+}: {
+  code: string;
+  title?: string | null;
+  source: ChatArtifactSource;
+  sourceToolCallId?: string | null;
+  sourceMessageId?: string | null;
+  className?: string;
+  autoOpen?: boolean;
+  isStreaming?: boolean;
+}) {
+  const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const messageIdFromContext = useAuiState(({ message }) => message.id);
+  const threadIdFromContext = useAuiState(
+    ({ threads }) => threads.mainThreadId,
+  );
+  const artifactThreadId = threadIdFromContext ?? activeThreadId ?? null;
+  const openArtifact = useChatArtifactsStore((state) => state.openArtifact);
+  const updateArtifact = useChatArtifactsStore((state) => state.updateArtifact);
+  const selectedArtifactId = useChatArtifactsStore(
+    (state) => state.selectedArtifactId,
+  );
+  const artifact = useMemo<ChatArtifact>(
+    () =>
+      createChatArtifact({
+        code,
+        title,
+        source,
+        sourceMessageId: sourceMessageId ?? messageIdFromContext ?? null,
+        sourceToolCallId: sourceToolCallId ?? null,
+        threadId: artifactThreadId,
+        isStreaming,
+      }),
+    [
+      artifactThreadId,
+      code,
+      isStreaming,
+      messageIdFromContext,
+      source,
+      sourceMessageId,
+      sourceToolCallId,
+      title,
+    ],
+  );
+  const surface = artifactThreadId ? "panel" : "overlay";
+
+  useLayoutEffect(() => {
+    if (selectedArtifactId === artifact.id) {
+      updateArtifact(artifact);
+    }
+
+    if (!autoOpen) {
+      return;
+    }
+    if (hasAutoOpenedArtifact(artifact.id)) {
+      return;
+    }
+
+    rememberAutoOpenedArtifact(artifact.id);
+    openArtifact(artifact, { surface });
+  }, [
+    artifact,
+    autoOpen,
+    openArtifact,
+    selectedArtifactId,
+    surface,
+    updateArtifact,
+  ]);
+
+  return (
+    <button
+      type="button"
+      className={cn(
+        "group/artifact-card relative my-2 flex min-h-[52px] w-full max-w-md cursor-pointer items-center overflow-hidden rounded-lg border border-border/70 bg-muted/15 px-3 py-2 text-left transition-colors hover:bg-muted/25 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "dark:bg-muted/10 dark:hover:bg-muted/20",
+        isStreaming &&
+          "border-border/80 bg-muted/20 dark:border-border/70 dark:bg-muted/15",
+        className,
+      )}
+      onClick={() => openArtifact(artifact, { surface })}
+      aria-label={`Open ${artifact.title}`}
+    >
+      {isStreaming ? (
+        <span
+          aria-hidden={true}
+          className="artifact-card-shimmer pointer-events-none absolute inset-0 z-0 motion-reduce:hidden"
+        />
+      ) : null}
+      <div className="relative z-10 flex min-w-0 flex-1 items-center gap-2.5">
+        <HugeiconsIcon
+          icon={Layout2ColumnIcon}
+          strokeWidth={1.75}
+          className="size-5 shrink-0 text-muted-foreground"
+        />
+        <span className="grid min-w-0 flex-1 gap-1">
+          <span className="truncate text-sm font-medium leading-tight text-foreground">
+            {artifact.title}
+          </span>
+          <span className="truncate text-[11px] leading-none text-muted-foreground">
+            HTML artifact
+          </span>
+        </span>
+        {isStreaming ? (
+          <span className="shimmer shrink-0 rounded-full bg-primary/10 px-2 py-0.5 text-[10px] font-medium text-primary motion-reduce:animate-none">
+            Generating
+          </span>
+        ) : null}
+      </div>
+    </button>
+  );
+}
diff --git a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
new file mode 100644
index 0000000000..b32d24469b
--- /dev/null
+++ b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
@@ -0,0 +1,362 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { createCodePlugin } from "@/components/assistant-ui/code-plugin";
+import { CodeToggleIcon } from "@/components/assistant-ui/code-toggle-icon";
+import {
+  unslothDarkTheme,
+  unslothLightTheme,
+} from "@/components/assistant-ui/code-themes";
+import { Button } from "@/components/ui/button";
+import { copyToClipboard } from "@/lib/copy-to-clipboard";
+import { cn } from "@/lib/utils";
+import {
+  CheckIcon,
+  CopyIcon,
+  DownloadIcon,
+  EyeIcon,
+  Maximize2Icon,
+  XIcon,
+} from "lucide-react";
+import {
+  type KeyboardEvent,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { Streamdown } from "streamdown";
+import { ArtifactHtmlFrame, type ArtifactViewMode } from "./html-frame";
+import type { ChatArtifact } from "./types";
+import { getArtifactFilename } from "./types";
+
+const COPY_RESET_MS = 2000;
+const artifactSourceCodePlugin = createCodePlugin({
+  themes: [unslothLightTheme, unslothDarkTheme],
+});
+
+function buildHtmlFence(source: string): string {
+  const longestBacktickRun = Math.max(
+    2,
+    ...(source.match(/`+/g) ?? []).map((match) => match.length),
+  );
+  const fence = "`".repeat(longestBacktickRun + 1);
+  return `${fence}html\n${source}\n${fence}`;
+}
+// Sandboxed artifact iframes are intentionally excluded from the overlay focus
+// trap. Granting same-origin sandbox privileges would weaken isolation, so
+// keyboard users can reach Studio controls here while fully interactive artifact
+// content remains a known sandbox limitation.
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ).filter(
+    (element) =>
+      !element.hasAttribute("disabled") &&
+      element.getAttribute("aria-hidden") !== "true" &&
+      element.tabIndex !== -1,
+  );
+}
+
+function ArtifactLoadingLine() {
+  return (
+    <div className="absolute inset-x-0 bottom-0 h-[2.5px] overflow-hidden bg-border/45">
+      <span
+        aria-hidden={true}
+        className="artifact-loading-line block h-full rounded-full motion-reduce:hidden"
+      />
+    </div>
+  );
+}
+
+function ArtifactGeneratingPanel() {
+  return (
+    <div className="flex h-full min-h-0 flex-col items-center justify-center bg-muted/10 px-6 text-center">
+      <div className="max-w-[30ch] space-y-1.5">
+        <img
+          src="/Sloth%20emojis/sloth%20w%20pc%20transparent.png"
+          alt=""
+          aria-hidden={true}
+          className="mx-auto mb-3 size-20 object-contain"
+        />
+        <p className="text-sm font-medium text-foreground">
+          Building artifact preview…
+        </p>
+        <p className="text-xs leading-relaxed text-muted-foreground">
+          The preview will appear here when the HTML is ready.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function downloadTextFile(filename: string, text: string): void {
+  const blob = new Blob([text], { type: "text/html;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+  window.setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+export function ArtifactSurface({
+  artifact,
+  variant,
+  onClose,
+  onOpenFullscreen,
+}: {
+  artifact: ChatArtifact;
+  variant: "panel" | "overlay";
+  onClose: () => void;
+  onOpenFullscreen?: () => void;
+}) {
+  const [viewMode, setViewMode] = useState<ArtifactViewMode>("preview");
+  const [copied, setCopied] = useState(false);
+  const copyResetRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const surfaceRef = useRef<HTMLElement>(null);
+  const previousFocusRef = useRef<Element | null>(null);
+  const filename = getArtifactFilename(artifact);
+  const sourceMarkdown = useMemo(
+    () => buildHtmlFence(artifact.code),
+    [artifact.code],
+  );
+  const hasArtifactCode = artifact.code.trim().length > 0;
+  const isLoadingArtifact = Boolean(artifact.isStreaming);
+  const effectiveViewMode = isLoadingArtifact ? "preview" : viewMode;
+
+  useEffect(() => {
+    return () => {
+      if (copyResetRef.current) clearTimeout(copyResetRef.current);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (variant !== "overlay") return;
+    previousFocusRef.current = document.activeElement;
+    const timeoutId = window.setTimeout(() => {
+      const surface = surfaceRef.current;
+      if (!surface) return;
+      const firstFocusable = getFocusableElements(surface)[0];
+      if (firstFocusable) {
+        firstFocusable.focus();
+      } else {
+        surface.focus();
+      }
+    }, 0);
+    return () => {
+      window.clearTimeout(timeoutId);
+      const previousFocus = previousFocusRef.current;
+      if (previousFocus instanceof HTMLElement) previousFocus.focus();
+    };
+  }, [variant]);
+
+  const handleCopy = async () => {
+    if (!(await copyToClipboard(artifact.code))) return;
+    setCopied(true);
+    if (copyResetRef.current) clearTimeout(copyResetRef.current);
+    copyResetRef.current = setTimeout(() => {
+      setCopied(false);
+      copyResetRef.current = null;
+    }, COPY_RESET_MS);
+  };
+
+  const handleDialogKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if (variant !== "overlay") return;
+    if (event.key === "Escape") {
+      event.preventDefault();
+      onClose();
+      return;
+    }
+    if (event.key !== "Tab") return;
+    const focusable = getFocusableElements(event.currentTarget);
+    if (focusable.length === 0) {
+      event.preventDefault();
+      event.currentTarget.focus();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  const content = (
+    <section
+      ref={surfaceRef}
+      role={variant === "overlay" ? "dialog" : undefined}
+      aria-modal={variant === "overlay" ? true : undefined}
+      tabIndex={variant === "overlay" ? -1 : undefined}
+      onKeyDown={handleDialogKeyDown}
+      className={cn(
+        "relative flex min-h-0 flex-col border border-border bg-background",
+        variant === "panel"
+          ? "artifact-panel-shell mx-2 mt-[72px] mb-8 h-[calc(100%_-_104px)] overflow-visible rounded-[28px] border-border/70 bg-card/95 [box-shadow:rgba(0,0,0,0.16)_0px_2px_8px_-2px]"
+          : "h-[min(92vh,900px)] w-[min(96vw,1200px)] overflow-hidden rounded-2xl shadow-xl",
+      )}
+      aria-label={`${artifact.title} artifact`}
+    >
+      <header
+        className={cn(
+          "relative flex shrink-0 items-center justify-between gap-3 px-2.5 py-2",
+          variant === "panel" && "rounded-t-[28px]",
+        )}
+      >
+        <div
+          className="flex items-center gap-1 rounded-full bg-muted/40 p-0.5"
+          role="tablist"
+          aria-label="Artifact view"
+        >
+          {(["preview", "source"] as const).map((mode) => {
+            const isPreview = mode === "preview";
+            const Icon = isPreview ? EyeIcon : CodeToggleIcon;
+            return (
+              <button
+                key={mode}
+                type="button"
+                role="tab"
+                disabled={isLoadingArtifact && !isPreview}
+                onClick={() => setViewMode(mode)}
+                className={cn(
+                  "flex size-8 items-center justify-center rounded-full text-muted-foreground transition-colors",
+                  effectiveViewMode === mode
+                    ? "bg-background text-foreground shadow-sm"
+                    : "hover:bg-background/70 hover:text-foreground",
+                  isLoadingArtifact &&
+                    !isPreview &&
+                    "cursor-not-allowed opacity-50",
+                )}
+                aria-label={
+                  isPreview ? "Preview artifact" : "View artifact source"
+                }
+                aria-selected={effectiveViewMode === mode}
+                aria-pressed={effectiveViewMode === mode}
+                title={
+                  isPreview
+                    ? "Preview"
+                    : isLoadingArtifact
+                      ? "Source available when generation finishes"
+                      : "Source"
+                }
+              >
+                <Icon className="size-4" />
+              </button>
+            );
+          })}
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="size-8"
+            disabled={isLoadingArtifact || !hasArtifactCode}
+            onClick={() => downloadTextFile(filename, artifact.code)}
+            aria-label="Download artifact HTML"
+          >
+            <DownloadIcon className="size-4" />
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="size-8"
+            disabled={isLoadingArtifact || !hasArtifactCode}
+            onClick={handleCopy}
+            aria-label="Copy artifact HTML"
+          >
+            {copied ? (
+              <CheckIcon className="size-4" />
+            ) : (
+              <CopyIcon className="size-4" />
+            )}
+          </Button>
+          {variant === "panel" && onOpenFullscreen ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="size-8"
+              onClick={onOpenFullscreen}
+              aria-label="Open artifact fullscreen"
+            >
+              <Maximize2Icon className="size-4" />
+            </Button>
+          ) : null}
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="size-8"
+            onClick={onClose}
+            aria-label="Close artifact"
+          >
+            <XIcon className="size-4" />
+          </Button>
+        </div>
+        {isLoadingArtifact ? (
+          <ArtifactLoadingLine />
+        ) : (
+          <div className="absolute inset-x-0 bottom-0 h-px bg-border" />
+        )}
+      </header>
+
+      <div
+        className={cn(
+          "min-h-0 flex-1 overflow-hidden bg-background",
+          variant === "panel" && "rounded-b-[28px]",
+        )}
+      >
+        {isLoadingArtifact ? (
+          <ArtifactGeneratingPanel />
+        ) : effectiveViewMode === "preview" ? (
+          <ArtifactHtmlFrame
+            key={artifact.id}
+            code={artifact.code}
+            title={artifact.title}
+            fill={true}
+            className="h-full"
+          />
+        ) : (
+          <div className="h-full overflow-auto text-xs leading-relaxed [&_[data-streamdown=code-block]]:!rounded-none [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:text-xs [&_pre]:leading-relaxed [&_code]:text-xs">
+            <Streamdown
+              mode="streaming"
+              plugins={{ code: artifactSourceCodePlugin }}
+              controls={{ code: false }}
+              shikiTheme={[unslothLightTheme, unslothDarkTheme]}
+            >
+              {sourceMarkdown}
+            </Streamdown>
+          </div>
+        )}
+      </div>
+    </section>
+  );
+
+  if (variant === "overlay") {
+    return (
+      <div
+        className="fixed inset-0 z-50 flex items-center justify-center bg-background/80 p-4 backdrop-blur-sm"
+        onMouseDown={(event) => {
+          if (event.target === event.currentTarget) onClose();
+        }}
+      >
+        {content}
+      </div>
+    );
+  }
+
+  return content;
+}
diff --git a/studio/frontend/src/features/chat/artifacts/html-frame.tsx b/studio/frontend/src/features/chat/artifacts/html-frame.tsx
new file mode 100644
index 0000000000..dc8c14c0ed
--- /dev/null
+++ b/studio/frontend/src/features/chat/artifacts/html-frame.tsx
@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { getAuthToken } from "@/features/auth";
+import { apiUrl } from "@/lib/api-base";
+import { cn } from "@/lib/utils";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+import { hashArtifactCode } from "./types";
+
+const HTML_FRAME_DEFAULT_HEIGHT = 400;
+const HTML_FRAME_MAX_HEIGHT = 900;
+
+export type ArtifactViewMode = "preview" | "source";
+export const ARTIFACT_VIEW_MODES: readonly ArtifactViewMode[] = [
+  "preview",
+  "source",
+];
+
+export function isArtifactViewMode(value: string): value is ArtifactViewMode {
+  return (ARTIFACT_VIEW_MODES as readonly string[]).includes(value);
+}
+
+export function buildArtifactSrcDoc(code: string): string {
+  const resizeScript = `<script>(()=>{const post=()=>parent.postMessage({chatArtifactHeight:document.documentElement.scrollHeight},"*");new ResizeObserver(post).observe(document.documentElement);window.addEventListener("load",post);post();})();</script>`;
+  return `${code}\n${resizeScript}`;
+}
+
+// Preview iframes intentionally omit allow-downloads: generated artifacts can
+// offer their own UI, but downloads must go through Studio's explicit
+// copy/download controls outside the no-same-origin sandbox.
+export function ArtifactHtmlFrame({
+  code,
+  title = "HTML artifact preview",
+  className,
+  fill = false,
+}: {
+  code: string;
+  title?: string;
+  className?: string;
+  fill?: boolean;
+}) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const allowNetworkAccess = useChatRuntimeStore(
+    (state) => state.allowArtifactNetworkAccess,
+  );
+  const [height, setHeight] = useState(HTML_FRAME_DEFAULT_HEIGHT);
+  const artifactHtml = useMemo(() => buildArtifactSrcDoc(code), [code]);
+  const src = useMemo(() => {
+    const query = new URLSearchParams({ v: hashArtifactCode(code) });
+    if (allowNetworkAccess) {
+      const token = getAuthToken();
+      if (token) {
+        query.set("allow_network", "1");
+        query.set("token", token);
+      }
+    }
+    return apiUrl(`/api/inference/artifact-preview-frame?${query.toString()}`);
+  }, [allowNetworkAccess, code]);
+  const postArtifactHtml = useCallback(() => {
+    // The sandboxed frame intentionally has an opaque origin ("null").
+    // A wildcard target is required here;
+    // the payload is sent only to this iframe's contentWindow.
+    iframeRef.current?.contentWindow?.postMessage(
+      { type: "unsloth:artifact-html", html: artifactHtml },
+      "*",
+    );
+  }, [artifactHtml]);
+
+  useEffect(() => {
+    const handler = (event: MessageEvent) => {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      if (event.origin !== "null") return;
+      if (typeof event.data?.chatArtifactHeight !== "number") return;
+      setHeight(
+        Math.min(
+          Math.max(event.data.chatArtifactHeight, 160),
+          HTML_FRAME_MAX_HEIGHT,
+        ),
+      );
+    };
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, [postArtifactHtml]);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={src}
+      sandbox="allow-scripts"
+      referrerPolicy="no-referrer"
+      onLoad={postArtifactHtml}
+      className={cn("block w-full border-0 bg-background", className)}
+      style={{ height: fill ? "100%" : height }}
+      title={title}
+    />
+  );
+}
diff --git a/studio/frontend/src/features/chat/artifacts/store.ts b/studio/frontend/src/features/chat/artifacts/store.ts
new file mode 100644
index 0000000000..6c47959822
--- /dev/null
+++ b/studio/frontend/src/features/chat/artifacts/store.ts
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+import type { ChatArtifact, ChatArtifactSurface } from "./types";
+
+const autoOpenedArtifactIds = new Set<string>();
+
+export function hasAutoOpenedArtifact(artifactId: string): boolean {
+  return autoOpenedArtifactIds.has(artifactId);
+}
+
+export function rememberAutoOpenedArtifact(artifactId: string): void {
+  autoOpenedArtifactIds.add(artifactId);
+}
+
+export function clearAutoOpenedArtifacts(): void {
+  autoOpenedArtifactIds.clear();
+}
+
+type ChatArtifactsState = {
+  artifactsById: Record<string, ChatArtifact>;
+  selectedArtifactId: string | null;
+  surface: ChatArtifactSurface;
+  openArtifact: (
+    artifact: ChatArtifact,
+    options?: { surface?: ChatArtifactSurface },
+  ) => void;
+  updateArtifact: (artifact: ChatArtifact) => void;
+  closeArtifactSurface: () => void;
+  clearArtifactsForThread: (threadId: string | null | undefined) => void;
+  clearOrphanedArtifacts: () => void;
+  resetArtifacts: () => void;
+};
+
+export const useChatArtifactsStore = create<ChatArtifactsState>((set) => ({
+  artifactsById: {},
+  selectedArtifactId: null,
+  surface: "panel",
+  openArtifact: (artifact, options) =>
+    set((state) => ({
+      artifactsById: {
+        ...state.artifactsById,
+        [artifact.id]: artifact,
+      },
+      selectedArtifactId: artifact.id,
+      surface: options?.surface ?? state.surface,
+    })),
+  updateArtifact: (artifact) =>
+    set((state) =>
+      state.artifactsById[artifact.id]
+        ? {
+            artifactsById: {
+              ...state.artifactsById,
+              [artifact.id]: artifact,
+            },
+          }
+        : state,
+    ),
+  closeArtifactSurface: () =>
+    set({ selectedArtifactId: null, surface: "panel" }),
+  clearArtifactsForThread: (threadId) =>
+    set((state) => {
+      if (!threadId) return state;
+      const artifactsById = Object.fromEntries(
+        Object.entries(state.artifactsById).filter(
+          ([, artifact]) => artifact.threadId !== threadId,
+        ),
+      );
+      const selected = state.selectedArtifactId
+        ? artifactsById[state.selectedArtifactId]
+        : null;
+      return {
+        artifactsById,
+        selectedArtifactId: selected ? selected.id : null,
+      };
+    }),
+  clearOrphanedArtifacts: () =>
+    set((state) => {
+      const artifactsById = Object.fromEntries(
+        Object.entries(state.artifactsById).filter(
+          ([, artifact]) => artifact.threadId != null,
+        ),
+      );
+      const selected = state.selectedArtifactId
+        ? artifactsById[state.selectedArtifactId]
+        : null;
+      return {
+        artifactsById,
+        selectedArtifactId: selected ? selected.id : null,
+      };
+    }),
+  resetArtifacts: () =>
+    set({
+      artifactsById: {},
+      selectedArtifactId: null,
+      surface: "panel",
+    }),
+}));
+
+export function useSelectedChatArtifact(): ChatArtifact | null {
+  return useChatArtifactsStore((state) =>
+    state.selectedArtifactId
+      ? (state.artifactsById[state.selectedArtifactId] ?? null)
+      : null,
+  );
+}
diff --git a/studio/frontend/src/features/chat/artifacts/types.ts b/studio/frontend/src/features/chat/artifacts/types.ts
new file mode 100644
index 0000000000..86d42fd733
--- /dev/null
+++ b/studio/frontend/src/features/chat/artifacts/types.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export type ChatArtifactSource = "tool" | "fence";
+export type ChatArtifactSurface = "panel" | "overlay";
+
+export interface ChatArtifact {
+  id: string;
+  title: string;
+  code: string;
+  source: ChatArtifactSource;
+  sourceMessageId?: string | null;
+  sourceToolCallId?: string | null;
+  threadId?: string | null;
+  isStreaming?: boolean;
+  createdAt: number;
+}
+
+export interface ChatArtifactInput {
+  title?: string | null;
+  code: string;
+  source: ChatArtifactSource;
+  sourceMessageId?: string | null;
+  sourceToolCallId?: string | null;
+  threadId?: string | null;
+  isStreaming?: boolean;
+}
+
+const DEFAULT_ARTIFACT_TITLE = "HTML artifact";
+
+export function normalizeArtifactTitle(title?: string | null): string {
+  const trimmed = title?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ARTIFACT_TITLE;
+}
+
+export function hashArtifactCode(code: string): string {
+  let hash = 5381;
+  for (let i = 0; i < code.length; i += 1) {
+    hash = ((hash << 5) + hash) ^ code.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+export function createArtifactId(input: ChatArtifactInput): string {
+  const threadSegment = input.threadId || "no-thread";
+  const messageSegment = input.sourceMessageId || "transient";
+  // Backend tool call IDs (call_0, call_1, …) reset per request, so
+  // the message ID is needed to scope them to a specific turn.
+  const parts = [input.source, threadSegment, messageSegment];
+
+  if (input.source === "tool" && input.sourceToolCallId) {
+    parts.push(input.sourceToolCallId);
+  } else {
+    parts.push(hashArtifactCode(input.code));
+  }
+
+  return parts.join(":");
+}
+
+export function createChatArtifact(input: ChatArtifactInput): ChatArtifact {
+  return {
+    id: createArtifactId(input),
+    title: normalizeArtifactTitle(input.title),
+    code: input.code,
+    source: input.source,
+    sourceMessageId: input.sourceMessageId ?? null,
+    sourceToolCallId: input.sourceToolCallId ?? null,
+    threadId: input.threadId ?? null,
+    isStreaming: input.isStreaming,
+    createdAt: Date.now(),
+  };
+}
+
+export function getArtifactFilename(
+  artifact: Pick<ChatArtifact, "title">,
+): string {
+  const slug = artifact.title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return `${slug || "artifact"}.html`;
+}
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index c4a5f34273..9133cdf102 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -10,15 +10,22 @@ import {
   ModelSelector,
 } from "@/components/assistant-ui/model-selector";
 import { Thread } from "@/components/assistant-ui/thread";
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable";
 import { useSidebar } from "@/components/ui/sidebar";
 import { Tooltip, TooltipContent } from "@/components/ui/tooltip";
-import { NativeModelChip } from "@/features/native-intents/components/native-model-chip";
-import { NativeModelDropOverlay } from "@/features/native-intents/components/native-model-drop-overlay";
-import { useNativeIntentStore } from "@/features/native-intents/store";
-import type { NativeIntent } from "@/features/native-intents/types";
-import { useChooseNativeModel } from "@/features/native-intents/use-native-dialogs";
-import { useNativeModelDrop } from "@/features/native-intents/use-native-drop";
-import { useNativePathLeasesSupported } from "@/features/native-intents/use-native-readiness";
+import {
+  NativeModelChip,
+  NativeModelDropOverlay,
+  type NativeIntent,
+  useChooseNativeModel,
+  useNativeIntentStore,
+  useNativeModelDrop,
+  useNativePathLeasesSupported,
+} from "@/features/native-intents";
 import { GuidedTour, useGuidedTourController } from "@/features/tour";
 import { isTauri } from "@/lib/api-base";
 import { cn } from "@/lib/utils";
@@ -26,6 +33,7 @@ import { CustomizeIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useNavigate, useSearch } from "@tanstack/react-router";
 import { Tooltip as TooltipPrimitive } from "radix-ui";
+import type { PanelImperativeHandle } from "react-resizable-panels";
 import {
   type ReactElement,
   memo,
@@ -78,6 +86,13 @@ import {
 } from "./stores/chat-runtime-store";
 import { useExternalProvidersStore } from "./stores/external-providers-store";
 import { buildChatTourSteps } from "./tour";
+import { ArtifactSurface } from "./artifacts/artifact-surface";
+import {
+  clearAutoOpenedArtifacts,
+  useChatArtifactsStore,
+  useSelectedChatArtifact,
+} from "./artifacts/store";
+import type { ChatArtifact, ChatArtifactSurface } from "./artifacts/types";
 import type { ChatView, MessageRecord } from "./types";
 import {
   getStoredChatThread,
@@ -134,6 +149,12 @@ function pickBestLoraForBase(
   return partial ?? sorted[0] ?? null;
 }
 
+function isAssistantLocalThreadId(
+  threadId: string | null | undefined,
+): boolean {
+  return Boolean(threadId?.startsWith("__LOCALID_"));
+}
+
 function messageHasImage(message: MessageRecord): boolean {
   const contentParts = Array.isArray(message.content) ? message.content : [];
   if (contentParts.some((part) => part.type === "image")) {
@@ -153,19 +174,161 @@ function messageHasImage(message: MessageRecord): boolean {
   return false;
 }
 
+const ARTIFACT_PANEL_DEFAULT_SIZE = "38%";
+const ARTIFACT_PANEL_TRANSITION_MS = 260;
+const ARTIFACT_SURFACE_POP_DELAY_MS = 150;
+
 const SingleContent = memo(function SingleContent({
   threadId,
   newThreadNonce,
-}: { threadId?: string; newThreadNonce?: string }): ReactElement {
+  artifact,
+  artifactSurface,
+  onCloseArtifact,
+}: {
+  threadId?: string;
+  newThreadNonce?: string;
+  artifact?: ChatArtifact | null;
+  artifactSurface: ChatArtifactSurface;
+  onCloseArtifact: () => void;
+}): ReactElement {
+  const openArtifact = useChatArtifactsStore((state) => state.openArtifact);
+  const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const artifactPanelRef = useRef<PanelImperativeHandle | null>(null);
+  const hasInitializedArtifactPanelRef = useRef(false);
+  const [isArtifactLayoutAnimating, setIsArtifactLayoutAnimating] =
+    useState(false);
+  const [isArtifactPanelLayoutActive, setIsArtifactPanelLayoutActive] =
+    useState(false);
+  const [isArtifactSurfaceVisible, setIsArtifactSurfaceVisible] =
+    useState(false);
+  const showArtifactPanel = Boolean(
+    artifact &&
+      artifactSurface === "panel" &&
+      (threadId
+        ? !artifact.threadId || artifact.threadId === threadId
+        : Boolean(newThreadNonce) ||
+          Boolean(artifact.threadId && artifact.threadId === activeThreadId)),
+  );
+
+  const artifactLayoutActive = showArtifactPanel || isArtifactPanelLayoutActive;
+  const artifactPanelSettledOpen =
+    showArtifactPanel &&
+    isArtifactPanelLayoutActive &&
+    !isArtifactLayoutAnimating;
+
+  useEffect(() => {
+    const panel = artifactPanelRef.current;
+    if (!panel) return;
+
+    setIsArtifactSurfaceVisible(false);
+
+    if (!hasInitializedArtifactPanelRef.current) {
+      hasInitializedArtifactPanelRef.current = true;
+      if (!showArtifactPanel) {
+        panel.resize("0%");
+        return;
+      }
+    }
+
+    setIsArtifactPanelLayoutActive(true);
+    setIsArtifactLayoutAnimating(true);
+    let resizeFrameId = 0;
+    const prepFrameId = window.requestAnimationFrame(() => {
+      resizeFrameId = window.requestAnimationFrame(() => {
+        panel.resize(showArtifactPanel ? ARTIFACT_PANEL_DEFAULT_SIZE : "0%");
+      });
+    });
+    const surfaceTimerId = showArtifactPanel
+      ? window.setTimeout(() => {
+          setIsArtifactSurfaceVisible(true);
+        }, ARTIFACT_SURFACE_POP_DELAY_MS)
+      : 0;
+    const timeoutId = window.setTimeout(() => {
+      setIsArtifactLayoutAnimating(false);
+      if (!showArtifactPanel) {
+        setIsArtifactPanelLayoutActive(false);
+      }
+    }, ARTIFACT_PANEL_TRANSITION_MS + 60);
+    return () => {
+      window.cancelAnimationFrame(prepFrameId);
+      if (resizeFrameId) {
+        window.cancelAnimationFrame(resizeFrameId);
+      }
+      if (surfaceTimerId) {
+        window.clearTimeout(surfaceTimerId);
+      }
+      window.clearTimeout(timeoutId);
+    };
+  }, [showArtifactPanel]);
+
+  const threadPane = (
+    <div className="flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
+      <Thread hideWelcome={Boolean(threadId)} targetThreadId={threadId} />
+    </div>
+  );
+
   return (
     <ChatRuntimeProvider
       modelType="base"
       initialThreadId={threadId}
       newThreadNonce={newThreadNonce}
     >
-      <div className="flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
-        <Thread hideWelcome={Boolean(threadId)} targetThreadId={threadId} />
-      </div>
+      <ResizablePanelGroup
+        orientation="horizontal"
+        data-artifact-layout-animating={
+          isArtifactLayoutAnimating ? "true" : "false"
+        }
+        className="chat-artifact-split min-h-0 min-w-0 flex-1 basis-0 overflow-hidden"
+      >
+        <ResizablePanel
+          id="chat-thread"
+          defaultSize="100%"
+          minSize={artifactLayoutActive ? "42%" : "100%"}
+          className="h-full min-h-0 min-w-0 overflow-hidden"
+        >
+          <div className="flex h-full min-h-0 min-w-0 flex-col overflow-hidden">
+            {threadPane}
+          </div>
+        </ResizablePanel>
+        <ResizableHandle
+          withHandle={false}
+          className={cn(
+            "relative z-30 -ml-1 -mr-4 w-5 bg-transparent transition-[width,margin] duration-[260ms] ease-[var(--ease-out-cubic)] hover:bg-transparent hover:shadow-none active:bg-transparent active:shadow-none focus-visible:bg-transparent focus-visible:shadow-none focus-visible:ring-0 focus-visible:ring-offset-0 focus-visible:outline-none",
+            !artifactLayoutActive && "pointer-events-none -ml-0 -mr-0 w-0",
+          )}
+        />
+        <ResizablePanel
+          panelRef={artifactPanelRef}
+          id="chat-artifact"
+          defaultSize="0%"
+          minSize={artifactPanelSettledOpen ? "30%" : "0%"}
+          maxSize={artifactLayoutActive ? "58%" : "0%"}
+          collapsible={true}
+          collapsedSize="0%"
+          className={cn(
+            "h-full min-h-0 min-w-0 overflow-visible",
+            !showArtifactPanel && "pointer-events-none",
+          )}
+        >
+          <div
+            data-artifact-surface-visible={
+              isArtifactSurfaceVisible ? "true" : "false"
+            }
+            className="chat-artifact-pop-surface flex h-full min-h-0 min-w-0 flex-col overflow-visible"
+          >
+            {showArtifactPanel && artifact ? (
+              <ArtifactSurface
+                artifact={artifact}
+                variant="panel"
+                onClose={onCloseArtifact}
+                onOpenFullscreen={() =>
+                  openArtifact(artifact, { surface: "overlay" })
+                }
+              />
+            ) : null}
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
     </ChatRuntimeProvider>
   );
 });
@@ -331,15 +494,17 @@ const LoraCompareContent = memo(function LoraCompareContent({
 
   useEffect(() => {
     let isActive = true;
-    listStoredChatThreads({ pairId }).then((threads) => {
-      if (!isActive) return;
-      setBaseThreadId(threads.find((t) => t.modelType === "base")?.id);
-      setLoraThreadId(threads.find((t) => t.modelType === "lora")?.id);
-    }).catch((error) => {
-      if (!isExpectedBackgroundChatStorageError(error)) {
-        throw error;
-      }
-    });
+    listStoredChatThreads({ pairId })
+      .then((threads) => {
+        if (!isActive) return;
+        setBaseThreadId(threads.find((t) => t.modelType === "base")?.id);
+        setLoraThreadId(threads.find((t) => t.modelType === "lora")?.id);
+      })
+      .catch((error) => {
+        if (!isExpectedBackgroundChatStorageError(error)) {
+          throw error;
+        }
+      });
     return () => {
       isActive = false;
     };
@@ -480,21 +645,25 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
 
   useEffect(() => {
     let isActive = true;
-    listStoredChatThreads({ pairId }).then((threads) => {
-      if (!isActive) return;
-      setModel1ThreadId(
-        threads.find((t) => t.modelType === "model1" || t.modelType === "base")
-          ?.id,
-      );
-      setModel2ThreadId(
-        threads.find((t) => t.modelType === "model2" || t.modelType === "lora")
-          ?.id,
-      );
-    }).catch((error) => {
-      if (!isExpectedBackgroundChatStorageError(error)) {
-        throw error;
-      }
-    });
+    listStoredChatThreads({ pairId })
+      .then((threads) => {
+        if (!isActive) return;
+        setModel1ThreadId(
+          threads.find(
+            (t) => t.modelType === "model1" || t.modelType === "base",
+          )?.id,
+        );
+        setModel2ThreadId(
+          threads.find(
+            (t) => t.modelType === "model2" || t.modelType === "lora",
+          )?.id,
+        );
+      })
+      .catch((error) => {
+        if (!isExpectedBackgroundChatStorageError(error)) {
+          throw error;
+        }
+      });
     return () => {
       isActive = false;
     };
@@ -632,7 +801,11 @@ export function ChatPage(): ReactElement {
   const modelsError = useChatRuntimeStore((state) => state.modelsError);
   const modelLoading = useChatRuntimeStore((state) => state.modelLoading);
   const clearCheckpoint = useChatRuntimeStore((state) => state.clearCheckpoint);
+  const resetArtifacts = useChatArtifactsStore((state) => state.resetArtifacts);
   const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const persistedActiveThreadId = isAssistantLocalThreadId(activeThreadId)
+    ? null
+    : activeThreadId;
   const modelOperationInProgress = useChatRuntimeStore(
     (state) => state.modelLoading,
   );
@@ -647,9 +820,9 @@ export function ChatPage(): ReactElement {
   } = useChatModelRuntime();
   const prevConnectionsEnabledRef = useRef(connectionsEnabled);
   useEffect(() => {
-    const turnedOff =
-      prevConnectionsEnabledRef.current && !connectionsEnabled;
+    const turnedOff = prevConnectionsEnabledRef.current && !connectionsEnabled;
     if (!connectionsEnabled && isExternalModelId(inferenceParams.checkpoint)) {
+      resetArtifacts();
       clearCheckpoint();
       if (turnedOff) {
         toast.info("Connections disabled", {
@@ -662,6 +835,7 @@ export function ChatPage(): ReactElement {
     clearCheckpoint,
     connectionsEnabled,
     inferenceParams.checkpoint,
+    resetArtifacts,
   ]);
   const pendingNativeModelIntent = useNativeIntentStore(
     (state) => state.pendingModelIntent,
@@ -681,17 +855,19 @@ export function ChatPage(): ReactElement {
   const reasoningEnabled = useChatRuntimeStore((s) => s.reasoningEnabled);
   const reasoningStyle = useChatRuntimeStore((s) => s.reasoningStyle);
   const reasoningEffort = useChatRuntimeStore((s) => s.reasoningEffort);
-  const supportsReasoningOff = useChatRuntimeStore((s) => s.supportsReasoningOff);
+  const supportsReasoningOff = useChatRuntimeStore(
+    (s) => s.supportsReasoningOff,
+  );
   const activeExternalProvider = useMemo(() => {
     const selection = parseExternalModelId(inferenceParams.checkpoint);
     if (!selection) return null;
     return (
-      externalProvidersForChat.find(
-        (p) => p.id === selection.providerId,
-      ) ?? null
+      externalProvidersForChat.find((p) => p.id === selection.providerId) ??
+      null
     );
   }, [externalProvidersForChat, inferenceParams.checkpoint]);
-  const activeExternalProviderType = activeExternalProvider?.providerType ?? null;
+  const activeExternalProviderType =
+    activeExternalProvider?.providerType ?? null;
   const activeProviderCapabilities = useMemo(() => {
     const selection = parseExternalModelId(inferenceParams.checkpoint);
     if (!selection) return null;
@@ -807,7 +983,9 @@ export function ChatPage(): ReactElement {
       (provider?.providerType === "anthropic" ||
         provider?.providerType === "openai");
     const storedToolsEnabled = loadOptionalBool(CHAT_TOOLS_ENABLED_KEY);
-    const storedCodeToolsEnabled = loadOptionalBool(CHAT_CODE_TOOLS_ENABLED_KEY);
+    const storedCodeToolsEnabled = loadOptionalBool(
+      CHAT_CODE_TOOLS_ENABLED_KEY,
+    );
     const storedImageToolsEnabled = loadOptionalBool(
       CHAT_IMAGE_TOOLS_ENABLED_KEY,
     );
@@ -876,14 +1054,43 @@ export function ChatPage(): ReactElement {
     if (search.thread) {
       return { mode: "single", threadId: search.thread };
     }
-    if (activeThreadId && !activeThreadId.startsWith("__LOCALID_")) {
-      return { mode: "single", threadId: activeThreadId };
+    if (persistedActiveThreadId) {
+      return { mode: "single", threadId: persistedActiveThreadId };
     }
     if (search.new) {
       return { mode: "single", newThreadNonce: search.new };
     }
     return { mode: "single" };
-  }, [search.thread, search.compare, search.new, activeThreadId]);
+  }, [search.thread, search.compare, search.new, persistedActiveThreadId]);
+
+  const selectedArtifact = useSelectedChatArtifact();
+  const artifactSurface = useChatArtifactsStore((state) => state.surface);
+  const closeArtifactSurface = useChatArtifactsStore(
+    (state) => state.closeArtifactSurface,
+  );
+  const artifactViewKey =
+    view.mode === "single"
+      ? `single:${view.threadId ?? view.newThreadNonce ?? "new"}`
+      : `compare:${view.pairId}`;
+
+  useEffect(() => {
+    clearAutoOpenedArtifacts();
+    closeArtifactSurface();
+  }, [artifactViewKey, closeArtifactSurface]);
+
+  useEffect(() => {
+    if (view.mode !== "single") return;
+    if (view.threadId || view.newThreadNonce || !selectedArtifact) return;
+    // view intentionally excludes __LOCALID_ threads (they fall through to
+    // { mode: "single" } with no threadId/nonce).  Don't close an artifact
+    // whose thread is the currently active local thread.
+    if (
+      selectedArtifact.threadId &&
+      selectedArtifact.threadId === activeThreadId
+    )
+      return;
+    closeArtifactSurface();
+  }, [activeThreadId, closeArtifactSurface, selectedArtifact, view]);
 
   const hasActiveModel = Boolean(inferenceParams.checkpoint);
   const loadNativeModelIntent = useCallback(
@@ -1018,11 +1225,12 @@ export function ChatPage(): ReactElement {
           selectedExternal?.modelId,
           selectedProvider?.baseUrl,
         );
-        const supportsBuiltinCodeExecution = providerSupportsBuiltinCodeExecution(
-          selectedProvider?.providerType,
-          selectedExternal?.modelId,
-          selectedProvider?.baseUrl,
-        );
+        const supportsBuiltinCodeExecution =
+          providerSupportsBuiltinCodeExecution(
+            selectedProvider?.providerType,
+            selectedExternal?.modelId,
+            selectedProvider?.baseUrl,
+          );
         const supportsBuiltinImageGeneration =
           providerSupportsBuiltinImageGeneration(
             selectedProvider?.providerType,
@@ -1153,8 +1361,12 @@ export function ChatPage(): ReactElement {
     ],
   );
   const handleEject = useCallback(() => {
-    void ejectModel();
-  }, [ejectModel]);
+    void (async () => {
+      if (await ejectModel()) {
+        resetArtifacts();
+      }
+    })();
+  }, [ejectModel, resetArtifacts]);
 
   const openModelSelector = useCallback(() => {
     setModelSelectorLocked(true);
@@ -1438,6 +1650,7 @@ export function ChatPage(): ReactElement {
 
   const tourSteps = useMemo(
     () =>
+      // eslint-disable-next-line react-hooks/refs -- buildChatTourSteps stores callbacks without invoking them during render.
       buildChatTourSteps({
         canCompare,
         openModelSelector,
@@ -1475,6 +1688,11 @@ export function ChatPage(): ReactElement {
     return () => window.clearTimeout(timeoutId);
   }, [modelSelectorLocked, tour.open]);
 
+  const showArtifactOverlay = Boolean(
+    selectedArtifact &&
+      (view.mode === "compare" || artifactSurface === "overlay"),
+  );
+
   return (
     <div className="flex min-h-0 min-w-0 flex-1 basis-0 bg-background overflow-hidden">
       <GuidedTour {...tour.tourProps} />
@@ -1593,9 +1811,12 @@ export function ChatPage(): ReactElement {
 
         {view.mode === "single" ? (
           <SingleContent
-            key={view.threadId ?? "single"}
+            key={view.threadId ?? view.newThreadNonce ?? "single"}
             threadId={view.threadId}
             newThreadNonce={view.newThreadNonce}
+            artifact={selectedArtifact}
+            artifactSurface={artifactSurface}
+            onCloseArtifact={closeArtifactSurface}
           />
         ) : (
           <CompareContent
@@ -1608,6 +1829,14 @@ export function ChatPage(): ReactElement {
             deleteDisabled={modelOperationInProgress}
           />
         )}
+
+        {showArtifactOverlay && selectedArtifact ? (
+          <ArtifactSurface
+            artifact={selectedArtifact}
+            variant="overlay"
+            onClose={closeArtifactSurface}
+          />
+        ) : null}
       </div>
 
       <ChatSettingsPanel
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 8c852b8189..b19aa68551 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -83,7 +83,6 @@ import {
   toPresetParams,
 } from "./presets/preset-policy";
 import {
-  EXTERNAL_MAX_OUTPUT_TOKENS,
   type ProviderCapabilities,
   getExternalMaxOutputTokens,
   getExternalMinOutputTokens,
@@ -438,16 +437,6 @@ export function ChatSettingsPanel({
     (s) => s.modelRequiresTrustRemoteCode,
   );
   const currentCheckpoint = params.checkpoint;
-  const currentModelIsMultimodal = useChatRuntimeStore((s) => {
-    if (s.loadedIsMultimodal) return true;
-    const m = s.models.find((m) => m.id === currentCheckpoint);
-    return (
-      Boolean(m?.isVision) ||
-      Boolean(m?.isAudio) ||
-      Boolean(m?.hasAudioInput) ||
-      m?.audioType === "audio_vlm"
-    );
-  });
   const ggufContextLength = useChatRuntimeStore((s) => s.ggufContextLength);
   const ggufMaxContextLength = useChatRuntimeStore(
     (s) => s.ggufMaxContextLength,
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 47216cf93d..1cac12ab13 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -1118,15 +1118,15 @@ export function useChatModelRuntime() {
     ],
   );
 
-  const ejectModel = useCallback(async () => {
+  const ejectModel = useCallback(async (): Promise<boolean> => {
     if (!params.checkpoint) {
-      return;
+      return false;
     }
     setModelsError(null);
     if (isExternalModelId(params.checkpoint)) {
       clearCheckpoint();
       await refresh();
-      return;
+      return true;
     }
     try {
       async function performUnload(): Promise<void> {
@@ -1135,17 +1135,21 @@ export function useChatModelRuntime() {
         await refresh();
       }
 
-      await toast.promise(performUnload(), {
+      const unloadPromise = performUnload();
+      toast.promise(unloadPromise, {
         loading: "Unloading model",
         success: { message: "Model unloaded", duration: 1200 },
         error: (err) =>
           err instanceof Error ? err.message : "Failed to unload model",
         description: "Releases VRAM and resets inference state.",
       });
+      await unloadPromise;
+      return true;
     } catch (error) {
       const message =
         error instanceof Error ? error.message : "Failed to unload model";
       setModelsError(message);
+      return false;
     }
   }, [clearCheckpoint, params.checkpoint, refresh, setModelsError]);
 
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
index 4d98678bd6..87a32dcd36 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
@@ -4,6 +4,7 @@
 import { useEffect, useState } from "react";
 import { CHAT_HISTORY_UPDATED_EVENT } from "../api/chat-api";
 import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+import { useChatArtifactsStore } from "../artifacts/store";
 import type { ThreadRecord } from "../types";
 import {
   deleteStoredChatThreads,
@@ -157,6 +158,10 @@ export async function deleteChatItem(
   // generating against a thread that no longer exists.
   for (const id of threadIds) cancelIfRunning(id);
 
+  const artifactStore = useChatArtifactsStore.getState();
+  for (const id of threadIds) artifactStore.clearArtifactsForThread(id);
+  artifactStore.clearOrphanedArtifacts();
+
   // Optimistic tombstone: hide immediately; roll back on backend error.
   markChatThreadsDeleted(threadIds);
   notifyChatHistoryUpdated();
diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.ts
index 883dea3f3a..063def91ae 100644
--- a/studio/frontend/src/features/chat/index.ts
+++ b/studio/frontend/src/features/chat/index.ts
@@ -22,6 +22,11 @@ export { useChatModelRuntime } from "./hooks/use-chat-model-runtime";
 export { ChatSearchDialog } from "./components/chat-search-dialog";
 export { setTrainingCompareHandoff } from "./lib/training-compare-handoff";
 export { clearAllChats, countAllChats } from "./utils/clear-all-chats";
+export { ArtifactCard } from "./artifacts/artifact-card";
+export {
+  useChatArtifactsStore,
+  useSelectedChatArtifact,
+} from "./artifacts/store";
 export { downloadChatExport } from "./utils/export-chat-history";
 export {
   deleteChatItem,
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 70f4311957..5ee98e230c 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -24,6 +24,7 @@ import { useAui } from "@assistant-ui/react";
 import {
   ArrowUpIcon,
   DownloadIcon,
+  FileTextIcon,
   GlobeIcon,
   HeadphonesIcon,
   LightbulbIcon,
@@ -37,7 +38,10 @@ import { Image03Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { toast } from "@/lib/toast";
 import { loadModel, validateModel } from "./api/chat-api";
-import { parseExternalModelId, providerTypeSupportsVision } from "./external-providers";
+import {
+  parseExternalModelId,
+  providerTypeSupportsVision,
+} from "./external-providers";
 import { useExternalProvidersStore } from "./stores/external-providers-store";
 import {
   type ReasoningEffort,
@@ -101,7 +105,10 @@ function fileToBase64DataURL(file: File): Promise<string> {
   });
 }
 
-function formatReasoningEffortLabel(level: ReasoningEffort, modelId?: string): string {
+function formatReasoningEffortLabel(
+  level: ReasoningEffort,
+  modelId?: string,
+): string {
   if (level === "max") return "Max";
   if (level === "xhigh") {
     const normalized = modelId?.trim().toLowerCase() ?? "";
@@ -137,7 +144,12 @@ function useDictation(
   const start = useCallback(() => {
     const SpeechRecognitionAPI =
       typeof window !== "undefined" &&
-      (window.SpeechRecognition ?? (window as unknown as { webkitSpeechRecognition?: typeof SpeechRecognition }).webkitSpeechRecognition);
+      (window.SpeechRecognition ??
+        (
+          window as unknown as {
+            webkitSpeechRecognition?: typeof SpeechRecognition;
+          }
+        ).webkitSpeechRecognition);
     if (!SpeechRecognitionAPI) {
       return;
     }
@@ -183,7 +195,11 @@ function useDictation(
 
   const supported =
     typeof window !== "undefined" &&
-    !!(window.SpeechRecognition ?? (window as unknown as { webkitSpeechRecognition?: unknown }).webkitSpeechRecognition);
+    !!(
+      window.SpeechRecognition ??
+      (window as unknown as { webkitSpeechRecognition?: unknown })
+        .webkitSpeechRecognition
+    );
 
   return { isDictating, start, stop, supported };
 }
@@ -222,9 +238,18 @@ export function RegisterCompareHandle({
     currentHandles[name] = {
       // fixes occasional reorder on reload.
       append: (content) =>
-        aui.thread().append({ role: "user", content, createdAt: new Date() } as never),
+        aui
+          .thread()
+          .append({ role: "user", content, createdAt: new Date() } as never),
       appendMessage: (content) =>
-        aui.thread().append({ role: "user", content, createdAt: new Date(), startRun: false } as never),
+        aui
+          .thread()
+          .append({
+            role: "user",
+            content,
+            createdAt: new Date(),
+            startRun: false,
+          } as never),
       startRun: () => {
         const msgs = aui.thread().getState().messages;
         const lastId = msgs.length > 0 ? msgs[msgs.length - 1].id : null;
@@ -268,7 +293,8 @@ function PendingImageThumb({
     setSrc(url);
     return () => URL.revokeObjectURL(url);
   }, [file]);
-  if (!src) return <div className="size-14 animate-pulse rounded-[14px] bg-muted" />;
+  if (!src)
+    return <div className="size-14 animate-pulse rounded-[14px] bg-muted" />;
   return (
     <div className="relative size-14 shrink-0 overflow-hidden rounded-[14px] border border-foreground/20 bg-muted">
       <img src={src} alt={file.name} className="h-full w-full object-cover" />
@@ -303,7 +329,10 @@ export function SharedComposer({
   const [running, setRunning] = useState(false);
   const [comparing, setComparing] = useState(false);
   const [pendingImages, setPendingImages] = useState<PendingImage[]>([]);
-  const [pendingAudio, setPendingAudio] = useState<{ name: string; base64: string } | null>(null);
+  const [pendingAudio, setPendingAudio] = useState<{
+    name: string;
+    base64: string;
+  } | null>(null);
   const [dragging, setDragging] = useState(false);
   const [isComposing, setIsComposing] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -332,10 +361,16 @@ export function SharedComposer({
   const setReasoningEnabled = useChatRuntimeStore((s) => s.setReasoningEnabled);
   const reasoningStyle = useChatRuntimeStore((s) => s.reasoningStyle);
   const reasoningEffort = useChatRuntimeStore((s) => s.reasoningEffort);
-  const supportsReasoningOff = useChatRuntimeStore((s) => s.supportsReasoningOff);
-  const reasoningEffortLevels = useChatRuntimeStore((s) => s.reasoningEffortLevels);
+  const supportsReasoningOff = useChatRuntimeStore(
+    (s) => s.supportsReasoningOff,
+  );
+  const reasoningEffortLevels = useChatRuntimeStore(
+    (s) => s.reasoningEffortLevels,
+  );
   const setReasoningEffort = useChatRuntimeStore((s) => s.setReasoningEffort);
-  const supportsPreserveThinking = useChatRuntimeStore((s) => s.supportsPreserveThinking);
+  const supportsPreserveThinking = useChatRuntimeStore(
+    (s) => s.supportsPreserveThinking,
+  );
   const preserveThinking = useChatRuntimeStore((s) => s.preserveThinking);
   const setPreserveThinking = useChatRuntimeStore((s) => s.setPreserveThinking);
   const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
@@ -350,6 +385,8 @@ export function SharedComposer({
   const setImageToolsEnabled = useChatRuntimeStore(
     (s) => s.setImageToolsEnabled,
   );
+  const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
+  const setArtifactsEnabled = useChatRuntimeStore((s) => s.setArtifactsEnabled);
   const webFetchToolsEnabled = useChatRuntimeStore(
     (s) => s.webFetchToolsEnabled,
   );
@@ -481,6 +518,7 @@ export function SharedComposer({
   // Images pill is only ever lit on OpenAI cloud's Responses-API models
   // and Gemini Nano Banana family. No local tool runtime fallback.
   const showImagePill = supportsBuiltinImageGeneration;
+  const artifactDisabled = !modelLoaded;
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
   const showWebFetchPill = supportsBuiltinWebFetch;
@@ -488,12 +526,17 @@ export function SharedComposer({
   // reference `toolsDisabled` (rare; both pills used it before).
   const toolsDisabled = codeDisabled;
   const setPendingAudioStore = useChatRuntimeStore((s) => s.setPendingAudio);
-  const clearPendingAudioStore = useChatRuntimeStore((s) => s.clearPendingAudio);
-
-  const { isDictating, start: startDictation, stop: stopDictation, supported: dictationSupported } = useDictation(
-    setText,
+  const clearPendingAudioStore = useChatRuntimeStore(
+    (s) => s.clearPendingAudio,
   );
 
+  const {
+    isDictating,
+    start: startDictation,
+    stop: stopDictation,
+    supported: dictationSupported,
+  } = useDictation(setText);
+
   useEffect(() => {
     const id = setInterval(() => {
       const handles = handlesRef.current;
@@ -510,43 +553,48 @@ export function SharedComposer({
     ta.style.height = "auto";
     const styles = window.getComputedStyle(ta);
     const lineHeight = parseFloat(styles.lineHeight) || 20;
-    const paddingY = parseFloat(styles.paddingTop) + parseFloat(styles.paddingBottom);
-    const borderY = parseFloat(styles.borderTopWidth) + parseFloat(styles.borderBottomWidth);
+    const paddingY =
+      parseFloat(styles.paddingTop) + parseFloat(styles.paddingBottom);
+    const borderY =
+      parseFloat(styles.borderTopWidth) + parseFloat(styles.borderBottomWidth);
     const maxHeight = lineHeight * 6 + paddingY + borderY;
     const next = Math.min(ta.scrollHeight, maxHeight);
     ta.style.height = `${next}px`;
     ta.style.overflowY = ta.scrollHeight > maxHeight ? "auto" : "hidden";
   }, [text]);
 
-  const addFiles = useCallback((files: FileList | null) => {
-    if (!files?.length) return;
-    const next: PendingImage[] = [];
-    let droppedImageForUnavailable = false;
-    for (let i = 0; i < files.length; i++) {
-      const file = files[i];
-      if (!file) continue;
-      // Handle audio files
-      if (file.type.match(/^audio\//i) && file.size <= MAX_AUDIO_SIZE) {
-        fileToBase64(file).then((base64) => {
-          setPendingAudio({ name: file.name, base64 });
-          setPendingAudioStore(base64, file.name);
-        });
-        continue;
+  const addFiles = useCallback(
+    (files: FileList | null) => {
+      if (!files?.length) return;
+      const next: PendingImage[] = [];
+      let droppedImageForUnavailable = false;
+      for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        if (!file) continue;
+        // Handle audio files
+        if (file.type.match(/^audio\//i) && file.size <= MAX_AUDIO_SIZE) {
+          fileToBase64(file).then((base64) => {
+            setPendingAudio({ name: file.name, base64 });
+            setPendingAudioStore(base64, file.name);
+          });
+          continue;
+        }
+        // Handle image files
+        if (!file.type.match(/^image\/(jpeg|png|webp|gif)$/i)) continue;
+        if (file.size > MAX_IMAGE_SIZE) continue;
+        if (attachUnavailableReason) {
+          droppedImageForUnavailable = true;
+          continue;
+        }
+        next.push({ id: crypto.randomUUID(), file });
       }
-      // Handle image files
-      if (!file.type.match(/^image\/(jpeg|png|webp|gif)$/i)) continue;
-      if (file.size > MAX_IMAGE_SIZE) continue;
-      if (attachUnavailableReason) {
-        droppedImageForUnavailable = true;
-        continue;
+      if (droppedImageForUnavailable && attachUnavailableReason) {
+        toast.error(attachUnavailableReason);
       }
-      next.push({ id: crypto.randomUUID(), file });
-    }
-    if (droppedImageForUnavailable && attachUnavailableReason) {
-      toast.error(attachUnavailableReason);
-    }
-    setPendingImages((prev) => [...prev, ...next]);
-  }, [setPendingAudioStore, attachUnavailableReason]);
+      setPendingImages((prev) => [...prev, ...next]);
+    },
+    [setPendingAudioStore, attachUnavailableReason],
+  );
 
   const removePendingImage = useCallback((id: string) => {
     setPendingImages((prev) => prev.filter((p) => p.id !== id));
@@ -604,12 +652,17 @@ export function SharedComposer({
     // LoraCompare and single-pane chats are unaffected.
     if (hasCompareHandles && !isGeneralizedCompare) {
       toast.error("Pick a model in each pane to compare", {
-        description: "Use the model dropdown above each pane, then send your prompt.",
+        description:
+          "Use the model dropdown above each pane, then send your prompt.",
       });
       return;
     }
 
-    if (pendingImages.length > 0 && !isGeneralizedCompare && imageUnavailableReason) {
+    if (
+      pendingImages.length > 0 &&
+      !isGeneralizedCompare &&
+      imageUnavailableReason
+    ) {
       // Single mode: the loaded model's runtime capability is known
       // here. Compare mode defers — each ensureModelLoaded below sets
       // loadedIsMultimodal for its side, and the chat-adapter's
@@ -647,8 +700,9 @@ export function SharedComposer({
       const maxSeqLength = store.params.maxSeqLength;
       const trustRemoteCode = store.params.trustRemoteCode ?? false;
       const chatTemplateOverride = store.chatTemplateOverride;
-      const effectiveChatTemplateOverride =
-        chatTemplateOverride?.trim() ? chatTemplateOverride : null;
+      const effectiveChatTemplateOverride = chatTemplateOverride?.trim()
+        ? chatTemplateOverride
+        : null;
 
       function modelDisplayName(id: string): string {
         const parts = id.split("/");
@@ -656,11 +710,14 @@ export function SharedComposer({
       }
 
       // Helper: load a model and update store checkpoint
-      async function ensureModelLoaded(sel: CompareModelSelection): Promise<string> {
+      async function ensureModelLoaded(
+        sel: CompareModelSelection,
+      ): Promise<string> {
         const currentStore = useChatRuntimeStore.getState();
         const isAlreadyActive =
           currentStore.params.checkpoint === sel.id &&
-          (currentStore.activeGgufVariant ?? null) === (sel.ggufVariant ?? null);
+          (currentStore.activeGgufVariant ?? null) ===
+            (sel.ggufVariant ?? null);
         if (!isAlreadyActive) {
           const validation = await validateModel({
             model_path: sel.id,
@@ -750,9 +807,17 @@ export function SharedComposer({
       try {
         // Side 1: load → generate → wait
         if (handle1 && model1?.id) {
-          toast("Loading Model 1…", { id: toastId, description: name1, duration: Infinity });
+          toast("Loading Model 1…", {
+            id: toastId,
+            description: name1,
+            duration: Infinity,
+          });
           const status1 = await ensureModelLoaded(model1);
-          toast("Generating with Model 1…", { id: toastId, description: `${name1} (${status1})`, duration: Infinity });
+          toast("Generating with Model 1…", {
+            id: toastId,
+            description: `${name1} (${status1})`,
+            duration: Infinity,
+          });
           const done = handle1.waitForRunEnd();
           handle1.startRun();
           await done;
@@ -760,13 +825,22 @@ export function SharedComposer({
 
         // Side 2: load → generate → wait
         if (handle2 && model2?.id) {
-          const needsLoad = model2.id.toLowerCase() !== (model1?.id || "").toLowerCase()
-            || (model2.ggufVariant ?? "") !== (model1?.ggufVariant ?? "");
+          const needsLoad =
+            model2.id.toLowerCase() !== (model1?.id || "").toLowerCase() ||
+            (model2.ggufVariant ?? "") !== (model1?.ggufVariant ?? "");
           if (needsLoad) {
-            toast("Loading Model 2…", { id: toastId, description: name2, duration: Infinity });
+            toast("Loading Model 2…", {
+              id: toastId,
+              description: name2,
+              duration: Infinity,
+            });
           }
           const status2 = await ensureModelLoaded(model2);
-          toast("Generating with Model 2…", { id: toastId, description: `${name2} (${status2})`, duration: Infinity });
+          toast("Generating with Model 2…", {
+            id: toastId,
+            description: `${name2} (${status2})`,
+            duration: Infinity,
+          });
           const done = handle2.waitForRunEnd();
           handle2.startRun();
           await done;
@@ -820,7 +894,12 @@ export function SharedComposer({
     }
   }
 
-  const canSend = (text.trim().length > 0 || pendingImages.length > 0 || pendingAudio !== null) && !busy && !isComposing;
+  const canSend =
+    (text.trim().length > 0 ||
+      pendingImages.length > 0 ||
+      pendingAudio !== null) &&
+    !busy &&
+    !isComposing;
 
   return (
     <div
@@ -855,7 +934,10 @@ export function SharedComposer({
               <span className="max-w-48 truncate">{pendingAudio.name}</span>
               <button
                 type="button"
-                onClick={() => { setPendingAudio(null); clearPendingAudioStore(); }}
+                onClick={() => {
+                  setPendingAudio(null);
+                  clearPendingAudioStore();
+                }}
                 className="flex size-4 items-center justify-center rounded-full hover:bg-destructive hover:text-destructive-foreground"
                 aria-label="Remove audio"
               >
@@ -953,130 +1035,136 @@ export function SharedComposer({
           )}
           {showReasoningControl ? (
             effectiveReasoningStyle === "reasoning_effort" ? (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild={true}>
-                <button
-                  type="button"
-                  disabled={reasoningDisabled}
-                  className={cn(
-                    "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-                    reasoningDisabled
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild={true}>
+                  <button
+                    type="button"
+                    disabled={reasoningDisabled}
+                    className={cn(
+                      "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
+                      reasoningDisabled
+                        ? "cursor-not-allowed opacity-40"
+                        : effectiveReasoningVisualEnabled
+                          ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
+                          : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
+                    )}
+                    aria-label={thinkEffortAriaLabel({
+                      modelLoaded,
+                      reasoningDisabled,
+                      reasoningEffort,
+                    })}
+                  >
+                    {effectiveReasoningVisualEnabled ? (
+                      <LightbulbIcon className="size-3.5" />
+                    ) : (
+                      <LightbulbOffIcon className="size-3.5" />
+                    )}
+                    <span>
+                      Think:{" "}
+                      {effectiveReasoningVisualEnabled
+                        ? formatReasoningEffortLabel(
+                            reasoningEffort,
+                            externalSelection?.modelId,
+                          )
+                        : formatReasoningDisabledLabel(
+                            effectiveSupportsReasoningOff,
+                            isExternalOpenAIReasoning,
+                            checkpoint,
+                          )}
+                    </span>
+                  </button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end">
+                  {effectiveSupportsReasoningOff && (
+                    <DropdownMenuItem
+                      onSelect={() => {
+                        setReasoningEnabled(false);
+                        applyQwenThinkingParams(false);
+                      }}
+                    >
+                      {formatReasoningDisabledLabel(
+                        effectiveSupportsReasoningOff,
+                        isExternalOpenAIReasoning,
+                        checkpoint,
+                      )}
+                      {!effectiveReasoningVisualEnabled ? " \u2713" : ""}
+                    </DropdownMenuItem>
+                  )}
+                  {effectiveReasoningEffortLevels
+                    .filter((level) => level !== "none")
+                    .map((level) => (
+                      <DropdownMenuItem
+                        key={level}
+                        onSelect={() => {
+                          setReasoningEffort(level);
+                          setReasoningEnabled(true);
+                          applyQwenThinkingParams(true);
+                          // Mutual exclusion: turning thinking on for a
+                          // Kimi model forces the web_search builtin off.
+                          if (isKimiExternal && toolsEnabled) {
+                            setToolsEnabled(false, { persist: false });
+                          }
+                        }}
+                      >
+                        {formatReasoningEffortLabel(
+                          level,
+                          externalSelection?.modelId,
+                        )}
+                        {effectiveReasoningVisualEnabled &&
+                        reasoningEffort === level
+                          ? " \u2713"
+                          : ""}
+                      </DropdownMenuItem>
+                    ))}
+                </DropdownMenuContent>
+              </DropdownMenu>
+            ) : (
+              <button
+                type="button"
+                disabled={reasoningDisabled || reasoningLockedOn}
+                aria-disabled={reasoningDisabled || reasoningLockedOn}
+                title={
+                  reasoningLockedOn
+                    ? "This model requires reasoning to stay on."
+                    : undefined
+                }
+                onClick={() => {
+                  if (reasoningLockedOn) return;
+                  const next = !reasoningEnabled;
+                  setReasoningEnabled(next);
+                  applyQwenThinkingParams(next);
+                  // Mutual exclusion: Kimi's $web_search builtin
+                  // requires thinking off, so turning thinking on flips
+                  // the Search pill off (and vice versa).
+                  if (isKimiExternal && next && toolsEnabled) {
+                    setToolsEnabled(false, { persist: false });
+                  }
+                }}
+                className={cn(
+                  "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
+                  reasoningLockedOn
+                    ? "cursor-not-allowed text-primary"
+                    : reasoningDisabled
                       ? "cursor-not-allowed opacity-40"
-                      : effectiveReasoningVisualEnabled
+                      : effectiveReasoningEnabled
                         ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
                         : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-                  )}
-                  aria-label={thinkEffortAriaLabel({
-                    modelLoaded,
-                    reasoningDisabled,
-                    reasoningEffort,
-                  })}
-                >
-                  {effectiveReasoningVisualEnabled ? (
-                    <LightbulbIcon className="size-3.5" />
-                  ) : (
-                    <LightbulbOffIcon className="size-3.5" />
-                  )}
-                  <span>
-                    Think:{" "}
-                    {effectiveReasoningVisualEnabled
-                      ? formatReasoningEffortLabel(
-                          reasoningEffort,
-                          externalSelection?.modelId,
-                        )
-                      : formatReasoningDisabledLabel(
-                          effectiveSupportsReasoningOff,
-                          isExternalOpenAIReasoning,
-                          checkpoint,
-                        )}
-                  </span>
-                </button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end">
-                {effectiveSupportsReasoningOff && (
-                  <DropdownMenuItem
-                    onSelect={() => {
-                      setReasoningEnabled(false);
-                      applyQwenThinkingParams(false);
-                    }}
-                  >
-                    {formatReasoningDisabledLabel(
-                      effectiveSupportsReasoningOff,
-                      isExternalOpenAIReasoning,
-                      checkpoint,
-                    )}
-                    {!effectiveReasoningVisualEnabled ? " \u2713" : ""}
-                  </DropdownMenuItem>
                 )}
-                {effectiveReasoningEffortLevels
-                  .filter((level) => level !== "none")
-                  .map((level) => (
-                  <DropdownMenuItem
-                    key={level}
-                    onSelect={() => {
-                      setReasoningEffort(level);
-                      setReasoningEnabled(true);
-                      applyQwenThinkingParams(true);
-                      // Mutual exclusion: turning thinking on for a
-                      // Kimi model forces the web_search builtin off.
-                      if (isKimiExternal && toolsEnabled) {
-                        setToolsEnabled(false, { persist: false });
-                      }
-                    }}
-                  >
-                    {formatReasoningEffortLabel(level, externalSelection?.modelId)}
-                    {effectiveReasoningVisualEnabled && reasoningEffort === level ? " \u2713" : ""}
-                  </DropdownMenuItem>
-                ))}
-              </DropdownMenuContent>
-            </DropdownMenu>
-          ) : (
-            <button
-              type="button"
-              disabled={reasoningDisabled || reasoningLockedOn}
-              aria-disabled={reasoningDisabled || reasoningLockedOn}
-              title={
-                reasoningLockedOn
-                  ? "This model requires reasoning to stay on."
-                  : undefined
-              }
-              onClick={() => {
-                if (reasoningLockedOn) return;
-                const next = !reasoningEnabled;
-                setReasoningEnabled(next);
-                applyQwenThinkingParams(next);
-                // Mutual exclusion: Kimi's $web_search builtin
-                // requires thinking off, so turning thinking on flips
-                // the Search pill off (and vice versa).
-                if (isKimiExternal && next && toolsEnabled) {
-                  setToolsEnabled(false, { persist: false });
-                }
-              }}
-              className={cn(
-                "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-                reasoningLockedOn
-                  ? "cursor-not-allowed text-primary"
-                  : reasoningDisabled
-                    ? "cursor-not-allowed opacity-40"
-                    : effectiveReasoningEnabled
-                      ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                      : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-              )}
-              aria-label={thinkToggleAriaLabel({
-                reasoningLockedOn,
-                modelLoaded,
-                reasoningDisabled,
-                effectiveReasoningEnabled,
-              })}
-            >
-              {reasoningLockedOn ||
-              (effectiveReasoningEnabled && !reasoningDisabled) ? (
-                <LightbulbIcon className="size-3.5" />
-              ) : (
-                <LightbulbOffIcon className="size-3.5" />
-              )}
-              <span>Think</span>
-            </button>
+                aria-label={thinkToggleAriaLabel({
+                  reasoningLockedOn,
+                  modelLoaded,
+                  reasoningDisabled,
+                  effectiveReasoningEnabled,
+                })}
+              >
+                {reasoningLockedOn ||
+                (effectiveReasoningEnabled && !reasoningDisabled) ? (
+                  <LightbulbIcon className="size-3.5" />
+                ) : (
+                  <LightbulbOffIcon className="size-3.5" />
+                )}
+                <span>Think</span>
+              </button>
             )
           ) : null}
           {supportsPreserveThinking && (
@@ -1093,7 +1181,9 @@ export function SharedComposer({
                     : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
               )}
               aria-label={
-                preserveThinking ? "Disable preserve think" : "Enable preserve think"
+                preserveThinking
+                  ? "Disable preserve think"
+                  : "Enable preserve think"
               }
             >
               {preserveThinking && modelLoaded ? (
@@ -1122,7 +1212,9 @@ export function SharedComposer({
             }}
             className="composer-pill-btn"
             data-active={toolsEnabled && !searchDisabled ? "true" : "false"}
-            aria-label={toolsEnabled ? "Disable web search" : "Enable web search"}
+            aria-label={
+              toolsEnabled ? "Disable web search" : "Enable web search"
+            }
           >
             <GlobeIcon className="size-3.5" />
             <span>Search</span>
@@ -1133,7 +1225,11 @@ export function SharedComposer({
             onClick={() => setCodeToolsEnabled(!codeToolsEnabled)}
             className="composer-pill-btn"
             data-active={codeToolsEnabled && !codeDisabled ? "true" : "false"}
-            aria-label={codeToolsEnabled ? "Disable code execution" : "Enable code execution"}
+            aria-label={
+              codeToolsEnabled
+                ? "Disable code execution"
+                : "Enable code execution"
+            }
           >
             <CodeToggleIcon className="size-3.5" />
             <span>Code</span>
@@ -1144,9 +1240,13 @@ export function SharedComposer({
               disabled={imageDisabled}
               onClick={() => setImageToolsEnabled(!imageToolsEnabled)}
               className="composer-pill-btn"
-              data-active={imageToolsEnabled && !imageDisabled ? "true" : "false"}
+              data-active={
+                imageToolsEnabled && !imageDisabled ? "true" : "false"
+              }
               aria-label={
-                imageToolsEnabled ? "Disable image generation" : "Enable image generation"
+                imageToolsEnabled
+                  ? "Disable image generation"
+                  : "Enable image generation"
               }
             >
               <HugeiconsIcon
@@ -1157,6 +1257,21 @@ export function SharedComposer({
               <span>Images</span>
             </button>
           )}
+          <button
+            type="button"
+            disabled={artifactDisabled}
+            onClick={() => setArtifactsEnabled(!artifactsEnabled)}
+            className="composer-pill-btn"
+            data-active={
+              artifactsEnabled && !artifactDisabled ? "true" : "false"
+            }
+            aria-label={
+              artifactsEnabled ? "Disable artifacts" : "Enable artifacts"
+            }
+          >
+            <FileTextIcon className="size-3.5" />
+            <span>Artifacts</span>
+          </button>
           {showWebFetchPill && (
             <button
               type="button"
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 8f0767b7b8..5a5928d311 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -27,6 +27,11 @@ export const CHAT_REASONING_ENABLED_KEY = "unsloth_chat_reasoning_enabled";
 export const CHAT_TOOLS_ENABLED_KEY = "unsloth_chat_tools_enabled";
 export const CHAT_CODE_TOOLS_ENABLED_KEY = "unsloth_chat_code_tools_enabled";
 export const CHAT_IMAGE_TOOLS_ENABLED_KEY = "unsloth_chat_image_tools_enabled";
+export const CHAT_ARTIFACTS_ENABLED_KEY = "unsloth_chat_artifacts_enabled";
+export const CHAT_COLLAPSE_HTML_ARTIFACTS_KEY =
+  "unsloth_chat_collapse_html_artifacts";
+export const CHAT_ALLOW_ARTIFACT_NETWORK_ACCESS_KEY =
+  "unsloth_chat_allow_artifact_network_access";
 export const CHAT_MCP_ENABLED_KEY = "unsloth_chat_mcp_enabled";
 export const CHAT_WEB_FETCH_TOOLS_ENABLED_KEY =
   "unsloth_chat_web_fetch_tools_enabled";
@@ -300,6 +305,9 @@ type ChatRuntimeStore = {
   toolsEnabled: boolean;
   codeToolsEnabled: boolean;
   imageToolsEnabled: boolean;
+  artifactsEnabled: boolean;
+  collapseHtmlArtifacts: boolean;
+  allowArtifactNetworkAccess: boolean;
   mcpEnabledForChat: boolean;
   /**
    * Fetch pill state, independent of `toolsEnabled` (Search). Only
@@ -368,6 +376,12 @@ type ChatRuntimeStore = {
   setToolsEnabled: (enabled: boolean, options?: { persist?: boolean }) => void;
   setCodeToolsEnabled: (enabled: boolean) => void;
   setImageToolsEnabled: (enabled: boolean) => void;
+  setArtifactsEnabled: (
+    enabled: boolean,
+    options?: { persist?: boolean },
+  ) => void;
+  setCollapseHtmlArtifacts: (enabled: boolean) => void;
+  setAllowArtifactNetworkAccess: (enabled: boolean) => void;
   setMcpEnabledForChat: (enabled: boolean) => void;
   setWebFetchToolsEnabled: (enabled: boolean) => void;
   setToolStatus: (status: string | null) => void;
@@ -400,6 +414,8 @@ type ScalarSettingKey =
   | "autoTitle"
   | "reasoningEffort"
   | "preserveThinking"
+  | "collapseHtmlArtifacts"
+  | "allowArtifactNetworkAccess"
   | "autoHealToolCalls"
   | "maxToolCallsPerMessage"
   | "toolCallTimeout";
@@ -434,6 +450,8 @@ const SCALAR_SETTING_KEYS = [
   "autoTitle",
   "reasoningEffort",
   "preserveThinking",
+  "collapseHtmlArtifacts",
+  "allowArtifactNetworkAccess",
   "autoHealToolCalls",
   "maxToolCallsPerMessage",
   "toolCallTimeout",
@@ -619,6 +637,12 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   toolsEnabled: loadBool(CHAT_TOOLS_ENABLED_KEY, false),
   codeToolsEnabled: loadBool(CHAT_CODE_TOOLS_ENABLED_KEY, false),
   imageToolsEnabled: loadBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, false),
+  artifactsEnabled: loadBool(CHAT_ARTIFACTS_ENABLED_KEY, false),
+  collapseHtmlArtifacts: loadBool(CHAT_COLLAPSE_HTML_ARTIFACTS_KEY, false),
+  allowArtifactNetworkAccess: loadBool(
+    CHAT_ALLOW_ARTIFACT_NETWORK_ACCESS_KEY,
+    false,
+  ),
   mcpEnabledForChat: loadBool(CHAT_MCP_ENABLED_KEY, false),
   webFetchToolsEnabled: loadBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, false),
   toolStatus: null,
@@ -835,6 +859,8 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       toolsEnabled: false,
       codeToolsEnabled: false,
       imageToolsEnabled: false,
+      artifactsEnabled: false,
+      mcpEnabledForChat: false,
       webFetchToolsEnabled: false,
       toolStatus: null,
       kvCacheDtype: null,
@@ -896,6 +922,36 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       saveBool(CHAT_IMAGE_TOOLS_ENABLED_KEY, imageToolsEnabled);
       return { imageToolsEnabled };
     }),
+  setArtifactsEnabled: (artifactsEnabled, options) =>
+    set(() => {
+      if (options?.persist !== false) {
+        saveBool(CHAT_ARTIFACTS_ENABLED_KEY, artifactsEnabled);
+      }
+      return { artifactsEnabled };
+    }),
+  setCollapseHtmlArtifacts: (collapseHtmlArtifacts) =>
+    set((state) => {
+      saveBool(CHAT_COLLAPSE_HTML_ARTIFACTS_KEY, collapseHtmlArtifacts);
+      setScalarSettingVersion(
+        "collapseHtmlArtifacts",
+        collapseHtmlArtifacts,
+        state.collapseHtmlArtifacts,
+      );
+      return { collapseHtmlArtifacts };
+    }),
+  setAllowArtifactNetworkAccess: (allowArtifactNetworkAccess) =>
+    set((state) => {
+      saveBool(
+        CHAT_ALLOW_ARTIFACT_NETWORK_ACCESS_KEY,
+        allowArtifactNetworkAccess,
+      );
+      setScalarSettingVersion(
+        "allowArtifactNetworkAccess",
+        allowArtifactNetworkAccess,
+        state.allowArtifactNetworkAccess,
+      );
+      return { allowArtifactNetworkAccess };
+    }),
   setMcpEnabledForChat: (mcpEnabledForChat) =>
     set(() => {
       saveBool(CHAT_MCP_ENABLED_KEY, mcpEnabledForChat);
diff --git a/studio/frontend/src/features/chat/utils/chat-settings-storage.ts b/studio/frontend/src/features/chat/utils/chat-settings-storage.ts
index 4e93a20bff..309cf3df64 100644
--- a/studio/frontend/src/features/chat/utils/chat-settings-storage.ts
+++ b/studio/frontend/src/features/chat/utils/chat-settings-storage.ts
@@ -28,6 +28,9 @@ const CHAT_ACTIVE_PRESET_KEY = "unsloth_chat_active_preset";
 const CHAT_ACTIVE_PRESET_SOURCE_KEY = "unsloth_chat_active_preset_source";
 const REASONING_EFFORT_KEY = "unsloth_reasoning_effort";
 const PRESERVE_THINKING_KEY = "unsloth_preserve_thinking";
+const COLLAPSE_HTML_ARTIFACTS_KEY = "unsloth_chat_collapse_html_artifacts";
+const ALLOW_ARTIFACT_NETWORK_ACCESS_KEY =
+  "unsloth_chat_allow_artifact_network_access";
 const CHAT_PRESETS_KEY = "unsloth_chat_custom_presets";
 const LEGACY_CHAT_SYSTEM_PROMPTS_KEY = "unsloth_chat_system_prompts";
 const LEGACY_CHAT_SETTINGS_IMPORT_KEY =
@@ -216,6 +219,10 @@ function sanitizeChatSettings(value: unknown): PersistedChatSettings {
   const reasoningEffort = sanitizeReasoningEffort(value.reasoningEffort);
   const autoTitle = sanitizeBool(value.autoTitle);
   const preserveThinking = sanitizeBool(value.preserveThinking);
+  const collapseHtmlArtifacts = sanitizeBool(value.collapseHtmlArtifacts);
+  const allowArtifactNetworkAccess = sanitizeBool(
+    value.allowArtifactNetworkAccess,
+  );
   const autoHealToolCalls = sanitizeBool(value.autoHealToolCalls);
   const maxToolCallsPerMessage = sanitizeInt(value.maxToolCallsPerMessage, 1);
   const toolCallTimeout = sanitizeInt(value.toolCallTimeout, 1);
@@ -230,6 +237,12 @@ function sanitizeChatSettings(value: unknown): PersistedChatSettings {
   if (reasoningEffort) settings.reasoningEffort = reasoningEffort;
   if (preserveThinking !== undefined)
     settings.preserveThinking = preserveThinking;
+  if (collapseHtmlArtifacts !== undefined) {
+    settings.collapseHtmlArtifacts = collapseHtmlArtifacts;
+  }
+  if (allowArtifactNetworkAccess !== undefined) {
+    settings.allowArtifactNetworkAccess = allowArtifactNetworkAccess;
+  }
   if (autoHealToolCalls !== undefined) {
     settings.autoHealToolCalls = autoHealToolCalls;
   }
@@ -290,6 +303,8 @@ export function isEmptyChatSettings(settings: PersistedChatSettings): boolean {
     settings.autoTitle === undefined &&
     settings.reasoningEffort === undefined &&
     settings.preserveThinking === undefined &&
+    settings.collapseHtmlArtifacts === undefined &&
+    settings.allowArtifactNetworkAccess === undefined &&
     settings.autoHealToolCalls === undefined &&
     settings.maxToolCallsPerMessage === undefined &&
     settings.toolCallTimeout === undefined
@@ -318,6 +333,8 @@ export function loadLegacyChatSettings(): PersistedChatSettings {
   );
   const autoTitle = loadBool(AUTO_TITLE_KEY);
   const preserveThinking = loadBool(PRESERVE_THINKING_KEY);
+  const collapseHtmlArtifacts = loadBool(COLLAPSE_HTML_ARTIFACTS_KEY);
+  const allowArtifactNetworkAccess = loadBool(ALLOW_ARTIFACT_NETWORK_ACCESS_KEY);
   const autoHealToolCalls = loadBool(AUTO_HEAL_TOOL_CALLS_KEY);
   const maxToolCallsPerMessage = loadInt(MAX_TOOL_CALLS_KEY, 1);
   const toolCallTimeout = loadInt(TOOL_CALL_TIMEOUT_KEY, 1);
@@ -336,6 +353,12 @@ export function loadLegacyChatSettings(): PersistedChatSettings {
   if (reasoningEffort) settings.reasoningEffort = reasoningEffort;
   if (preserveThinking !== undefined)
     settings.preserveThinking = preserveThinking;
+  if (collapseHtmlArtifacts !== undefined) {
+    settings.collapseHtmlArtifacts = collapseHtmlArtifacts;
+  }
+  if (allowArtifactNetworkAccess !== undefined) {
+    settings.allowArtifactNetworkAccess = allowArtifactNetworkAccess;
+  }
   if (autoHealToolCalls !== undefined) {
     settings.autoHealToolCalls = autoHealToolCalls;
   }
diff --git a/studio/frontend/src/features/native-intents/index.ts b/studio/frontend/src/features/native-intents/index.ts
new file mode 100644
index 0000000000..1e62dc26e5
--- /dev/null
+++ b/studio/frontend/src/features/native-intents/index.ts
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export { NativeModelChip } from "./components/native-model-chip";
+export { NativeModelDropOverlay } from "./components/native-model-drop-overlay";
+export { useNativeIntentStore } from "./store";
+export type { NativeIntent } from "./types";
+export { useChooseNativeModel } from "./use-native-dialogs";
+export { useNativeModelDrop } from "./use-native-drop";
+export type { NativeModelDropState } from "./use-native-drop";
+export { useNativePathLeasesSupported } from "./use-native-readiness";
diff --git a/studio/frontend/src/features/settings/tabs/chat-tab.tsx b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
index 997b342bea..4e528eabb1 100644
--- a/studio/frontend/src/features/settings/tabs/chat-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
@@ -2,6 +2,7 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
 import { toast } from "@/lib/toast";
 import {
   Dialog,
@@ -15,6 +16,7 @@ import {
   clearAllChats,
   countAllChats,
   downloadChatExport,
+  useChatRuntimeStore,
 } from "@/features/chat";
 import { useT } from "@/i18n";
 import { Delete02Icon, Download02Icon } from "@hugeicons/core-free-icons";
@@ -29,10 +31,26 @@ export function ChatTab() {
   const [count, setCount] = useState<number | null>(null);
   const [exporting, setExporting] = useState(false);
   const [clearing, setClearing] = useState(false);
+  const collapseHtmlArtifacts = useChatRuntimeStore(
+    (state) => state.collapseHtmlArtifacts,
+  );
+  const setCollapseHtmlArtifacts = useChatRuntimeStore(
+    (state) => state.setCollapseHtmlArtifacts,
+  );
+  const allowArtifactNetworkAccess = useChatRuntimeStore(
+    (state) => state.allowArtifactNetworkAccess,
+  );
+  const setAllowArtifactNetworkAccess = useChatRuntimeStore(
+    (state) => state.setAllowArtifactNetworkAccess,
+  );
+  const hydratePersistedSettings = useChatRuntimeStore(
+    (state) => state.hydratePersistedSettings,
+  );
 
   useEffect(() => {
     void countAllChats().then(setCount);
-  }, []);
+    void hydratePersistedSettings();
+  }, [hydratePersistedSettings]);
 
   const handleExport = async () => {
     setExporting(true);
@@ -111,6 +129,31 @@ export function ChatTab() {
         </p>
       </header>
 
+      <SettingsSection title={t("settings.chat.artifacts.title")}>
+        <SettingsRow
+          label={t("settings.chat.artifacts.collapseHtmlBlocks")}
+          description={t(
+            "settings.chat.artifacts.collapseHtmlBlocksDescription",
+          )}
+        >
+          <Switch
+            checked={collapseHtmlArtifacts}
+            onCheckedChange={setCollapseHtmlArtifacts}
+          />
+        </SettingsRow>
+        <SettingsRow
+          label={t("settings.chat.artifacts.allowNetworkAccess")}
+          description={t(
+            "settings.chat.artifacts.allowNetworkAccessDescription",
+          )}
+        >
+          <Switch
+            checked={allowArtifactNetworkAccess}
+            onCheckedChange={setAllowArtifactNetworkAccess}
+          />
+        </SettingsRow>
+      </SettingsSection>
+
       <SettingsSection title={t("settings.chat.data")}>
         <SettingsRow
           label={t("settings.chat.exportHistory")}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index b94f3aa105..bb76f1ebb5 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -165,6 +165,15 @@ export const en = {
     chat: {
       title: "Chat",
       description: "Manage your chat history stored on this device.",
+      artifacts: {
+        title: "Artifacts",
+        collapseHtmlBlocks: "Collapse HTML blocks",
+        collapseHtmlBlocksDescription:
+          "Artifacts mode collapses full HTML fallback automatically. Turn this on to also collapse full fenced HTML documents when Artifacts is off.",
+        allowNetworkAccess: "Allow artifact network access",
+        allowNetworkAccessDescription:
+          "Let artifact previews load scripts, styles, fonts, media, fetch, and WebSocket resources from HTTP(S) CDNs. Keep off for fully offline previews.",
+      },
       data: "Data",
       exportHistory: "Export chat history",
       exportHistoryDescription:
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index a3a1e8dad0..2f5f20252e 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -818,6 +818,149 @@
 		font-family: var(--font-sans);
 	}
 
+	.chat-artifact-split[data-artifact-layout-animating="true"] > [data-panel] {
+		transition:
+			flex-basis 260ms var(--ease-out-cubic),
+			flex-grow 260ms var(--ease-out-cubic),
+			flex-shrink 260ms var(--ease-out-cubic);
+		will-change: flex-basis, flex-grow;
+	}
+
+	.chat-artifact-pop-surface {
+		pointer-events: none;
+		opacity: 0;
+		transform: scale(0.965) translateY(8px);
+		transform-origin: center center;
+		transition:
+			opacity 180ms var(--ease-out-cubic),
+			transform 220ms var(--ease-out-cubic);
+		will-change: opacity, transform;
+	}
+
+	.chat-artifact-pop-surface[data-artifact-surface-visible="true"] {
+		pointer-events: auto;
+		opacity: 1;
+		transform: scale(1) translateY(0);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.chat-artifact-pop-surface {
+			transition: none;
+			transform: none;
+		}
+	}
+
+	.artifact-card-shimmer {
+		background: linear-gradient(
+			105deg,
+			transparent 0%,
+			color-mix(in oklch, var(--muted-foreground) 4%, transparent) 40%,
+			color-mix(in oklch, var(--muted-foreground) 8%, transparent) 50%,
+			color-mix(in oklch, var(--muted-foreground) 4%, transparent) 60%,
+			transparent 100%
+		);
+		transform: translateX(-120%);
+		animation: artifact-card-shimmer 1.55s var(--ease-out-cubic) infinite;
+	}
+
+	.artifact-loading-line {
+		width: 48%;
+		background: color-mix(in oklch, var(--primary) 88%, transparent);
+		transform: translate3d(-125%, 0, 0) scaleX(0.78);
+		transform-origin: center center;
+		animation: artifact-loading-line 1.7s linear infinite;
+	}
+
+	.artifact-panel-shell::before,
+	.artifact-panel-shell::after {
+		content: "";
+		position: absolute;
+		z-index: 20;
+		pointer-events: none;
+		transition:
+			border-color 150ms var(--ease-out-cubic),
+			background-color 150ms var(--ease-out-cubic),
+			box-shadow 150ms var(--ease-out-cubic),
+			transform 150ms var(--ease-out-cubic);
+	}
+
+	.artifact-panel-shell::before {
+		inset: 0;
+		border: 2px solid transparent;
+		border-radius: inherit;
+		-webkit-mask: linear-gradient(90deg, #000 0 24px, transparent 24px);
+		mask: linear-gradient(90deg, #000 0 24px, transparent 24px);
+	}
+
+	.artifact-panel-shell::after {
+		top: 50%;
+		left: -2px;
+		height: 28px;
+		width: 4px;
+		border-radius: 999px;
+		background: transparent;
+		transform: translateY(-50%);
+	}
+
+	[data-slot="resizable-handle"]:hover
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::before,
+	[data-slot="resizable-handle"]:active
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::before,
+	[data-slot="resizable-handle"][data-resize-handle-state="hover"]
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::before,
+	[data-slot="resizable-handle"][data-resize-handle-state="drag"]
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::before {
+		border-color: color-mix(in oklch, var(--primary) 58%, var(--border));
+	}
+
+	[data-slot="resizable-handle"]:hover
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::after,
+	[data-slot="resizable-handle"]:active
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::after,
+	[data-slot="resizable-handle"][data-resize-handle-state="hover"]
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::after,
+	[data-slot="resizable-handle"][data-resize-handle-state="drag"]
+		+ [data-slot="resizable-panel"]
+		.artifact-panel-shell::after {
+		background: color-mix(in oklch, var(--primary) 58%, var(--border));
+		box-shadow: none;
+		transform: translateY(-50%) scaleY(1.06);
+	}
+
+	@keyframes artifact-card-shimmer {
+		to {
+			transform: translateX(120%);
+		}
+	}
+
+	@keyframes artifact-loading-line {
+		0% {
+			transform: translate3d(-125%, 0, 0) scaleX(0.78);
+		}
+		35% {
+			transform: translate3d(-18%, 0, 0) scaleX(0.96);
+		}
+		62% {
+			transform: translate3d(72%, 0, 0) scaleX(1.12);
+		}
+		82% {
+			transform: translate3d(132%, 0, 0) scaleX(1.26);
+		}
+		94% {
+			transform: translate3d(188%, 0, 0) scaleX(1.36);
+		}
+		100% {
+			transform: translate3d(220%, 0, 0) scaleX(1.42);
+		}
+	}
+
 	/* Fine-tuning Studio: equal default height, expandable when needed (md+) */
 	.min-h-studio-config-column {
 		@apply md:min-h-[470px];

From a895d1cab6c83ba8ce9498cb344af53aba408411 Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Mon, 1 Jun 2026 10:06:47 +0200
Subject: [PATCH 046/222] Use natural generated image frame (#5794)

* Use natural generated image frame

* Refine generated image caption clamp

* Fix generated image caption width

* Fix generated image natural frame sizing
---
 .../assistant-ui/tool-ui-image-generation.tsx | 78 +++++++++++++++----
 1 file changed, 61 insertions(+), 17 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
index 7dfdd903fe..a9919708d0 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
@@ -10,7 +10,7 @@ import { DownloadIcon, ImageIcon, PencilIcon } from "lucide-react";
 import type { CSSProperties, MouseEvent } from "react";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { useGeneratedImageOverlay } from "./generated-image-overlay-context";
-import { Image, downloadImagePart } from "./image";
+import { downloadImagePart } from "./image";
 import {
   ToolFallbackContent,
   ToolFallbackRoot,
@@ -64,6 +64,8 @@ type GeneratedImagePart = {
 };
 
 const CAPTION_COLLAPSED_LINES = 4;
+const INLINE_IMAGE_MAX_WIDTH = 520;
+const INLINE_IMAGE_MAX_HEIGHT = 620;
 
 const extensionForMime = (mime: string): string => {
   switch (mime.toLowerCase()) {
@@ -100,6 +102,31 @@ const formatGeneratedImageLabel = (prompt: string): string => {
     : `Generated image: ${prompt}`;
 };
 
+const parseImageSize = (
+  size?: string,
+): { width: number; height: number } | null => {
+  const match = size?.match(/^(\d+)x(\d+)$/i);
+  if (!match) return null;
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  return width > 0 && height > 0 ? { width, height } : null;
+};
+
+const getInlineImageFrameWidth = ({
+  width,
+  height,
+}: {
+  width: number;
+  height: number;
+}): number =>
+  Math.round(
+    Math.min(
+      width,
+      INLINE_IMAGE_MAX_WIDTH,
+      (INLINE_IMAGE_MAX_HEIGHT * width) / height,
+    ),
+  );
+
 const loadingDots = Array.from({ length: 64 }, (_, index) => {
   const row = Math.floor(index / 8);
   const col = index % 8;
@@ -150,6 +177,16 @@ const ImageGenerationToolUIImpl: ToolCallMessagePartComponent = ({
     typeof result === "object" &&
     typeof (result as ImageGenerationResult).image_b64 === "string";
   const imageResult = isImageResult ? (result as ImageGenerationResult) : null;
+  const imageDimensions = parseImageSize(imageResult?.size);
+  const imageFrameStyle: CSSProperties = {
+    width: imageDimensions
+      ? getInlineImageFrameWidth(imageDimensions)
+      : INLINE_IMAGE_MAX_WIDTH,
+    maxWidth: "100%",
+  };
+  const imageBoxStyle: CSSProperties | undefined = imageDimensions
+    ? { aspectRatio: `${imageDimensions.width} / ${imageDimensions.height}` }
+    : undefined;
   const mime = imageResult?.image_mime || "image/png";
   const imageSrc = imageResult?.image_b64
     ? `data:${mime};base64,${imageResult.image_b64}`
@@ -202,8 +239,7 @@ const ImageGenerationToolUIImpl: ToolCallMessagePartComponent = ({
     const computedStyle = window.getComputedStyle(captionElement);
     const lineHeight = Number.parseFloat(computedStyle.lineHeight);
     const collapsedHeight =
-      (Number.isFinite(lineHeight) ? lineHeight : 20) *
-      CAPTION_COLLAPSED_LINES;
+      (Number.isFinite(lineHeight) ? lineHeight : 20) * CAPTION_COLLAPSED_LINES;
     const hasOverflow = captionElement.scrollHeight > collapsedHeight + 1;
     setPromptOverflow((current) =>
       current?.prompt === captionPrompt && current.canExpand === hasOverflow
@@ -289,26 +325,34 @@ const ImageGenerationToolUIImpl: ToolCallMessagePartComponent = ({
       />
       <ToolFallbackContent>
         {imagePart ? (
-          <figure className="m-0 flex flex-col gap-2">
-            <div className="group/generated-image relative aspect-square w-[480px] max-w-full overflow-hidden rounded-2xl bg-muted/25 shadow-lg shadow-foreground/5 dark:shadow-black/25">
-              <img
-                src={imagePart.image}
-                alt=""
-                aria-hidden={true}
-                className="pointer-events-none absolute inset-0 size-full scale-110 object-cover opacity-25 blur-2xl saturate-125"
-              />
-              <div className="pointer-events-none absolute inset-0 bg-background/45" />
+          <figure
+            className="m-0 flex max-w-full flex-col items-start gap-2 align-top"
+            style={imageFrameStyle}
+          >
+            <div
+              className="group/generated-image relative w-full overflow-hidden rounded-2xl align-top"
+              style={imageBoxStyle}
+            >
               <button
                 type="button"
-                className="relative z-10 block size-full cursor-zoom-in overflow-hidden rounded-2xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+                className={cn(
+                  "block cursor-zoom-in rounded-2xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+                  imageDimensions ? "size-full" : "max-w-full",
+                )}
                 onClick={showPreview}
                 aria-label="Open generated image preview"
               >
-                <Image.Preview
+                <img
                   src={imagePart.image}
                   alt={imageTitle}
-                  containerClassName="flex size-full min-h-0 items-center justify-center bg-transparent"
-                  className="size-full object-contain"
+                  width={imageDimensions?.width}
+                  height={imageDimensions?.height}
+                  className={cn(
+                    "block rounded-2xl object-contain",
+                    imageDimensions
+                      ? "size-full"
+                      : "h-auto max-h-[min(70vh,620px)] max-w-full",
+                  )}
                 />
               </button>
               <div className="pointer-events-none absolute inset-x-0 bottom-0 z-20 flex items-end justify-between gap-2 bg-gradient-to-t from-black/55 via-black/20 to-transparent p-3 opacity-100 transition-opacity sm:opacity-0 sm:group-hover/generated-image:opacity-100 sm:group-focus-within/generated-image:opacity-100">
@@ -335,7 +379,7 @@ const ImageGenerationToolUIImpl: ToolCallMessagePartComponent = ({
               </div>
             </div>
             {captionPrompt ? (
-              <figcaption className="max-w-[480px] text-xs leading-5 text-muted-foreground">
+              <figcaption className="w-full text-xs leading-5 text-muted-foreground">
                 <div
                   ref={captionRef}
                   className={cn(

From fc09d8f343006f4cad4ae13d2e088ef371e15561 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 02:55:51 -0700
Subject: [PATCH 047/222] Studio: defer the Windows CUDA Toolkit check so
 prebuilt users are not blocked (#5912)

* Studio: defer the Windows CUDA Toolkit check so prebuilt users are not blocked

setup.ps1 section 1e validated the installed CUDA Toolkit against the driver in
Phase 1 and hard-exited when the toolkit was newer than the driver supports.
That ran before the prebuilt llama.cpp install (Phase 3.4), which is
self-contained and needs no local toolkit. A Blackwell host (sm_120) on a driver
that advertises CUDA 13.2 with CUDA Toolkit 13.3 installed was blocked entirely,
even though the prebuilt selector would have given it a working GPU build.

The toolkit (nvcc) is only consumed by the Phase 4 source build. Move section 1e
into a Resolve-CudaToolkit function and call it lazily at the source-compile
branch, gated on $HasNvidiaSmi. The prebuilt path no longer touches the toolkit;
forced/source builds keep the identical requirement, winget auto-install, and
error text via -RequireOrExit.

Add a pwsh unit test that extracts the real function and runs it against a
spoofed Blackwell sm_120 / driver 13.2 / toolkit 13.3 host: the prebuilt path
defers, the forced build still fails fast.

Refs #5879.

* Studio: correct a stale Phase-1 prerequisites comment (CUDA Toolkit is now resolved lazily)

* Studio: retrigger Windows GGUF CI (artifact upload flake)
---
 studio/setup.ps1                           |  41 ++++++-
 tests/studio/test_resolve_cuda_toolkit.ps1 | 121 +++++++++++++++++++++
 2 files changed, 156 insertions(+), 6 deletions(-)
 create mode 100644 tests/studio/test_resolve_cuda_toolkit.ps1

diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 6c5f4171c4..70e2fee334 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -50,6 +50,12 @@ if ($script:UnslothVerbose) {
     $env:UNSLOTH_VERBOSE = '1'
 }
 $script:LlamaCppDegraded = $false
+# CUDA toolkit state, published by Resolve-CudaToolkit. Only the Phase 4 source
+# build consumes these; the prebuilt path leaves them at these defaults.
+$script:CudaToolkitReady = $false
+$script:NvccPath = $null
+$script:CudaToolkitRoot = $null
+$script:CudaArch = $null
 
 # Detect if running from pip install (no frontend/ dir in studio)
 $FrontendDir = Join-Path $ScriptDir "frontend"
@@ -1050,7 +1056,12 @@ if ($vsResult) {
 # ============================================
 # 1e. CUDA Toolkit (nvcc for llama.cpp build + env vars)
 # ============================================
-if ($HasNvidiaSmi) {
+# Defined here but invoked lazily right before a Phase 4 source build; the
+# prebuilt llama.cpp path needs no local toolkit. With -RequireOrExit a source
+# build is committed, so hard-fail if no driver-compatible toolkit can be found
+# or installed. Without it, detection is best-effort and only sets the flag.
+function Resolve-CudaToolkit {
+    param([switch]$RequireOrExit)
 # IMPORTANT: The CUDA Toolkit version must be <= the max CUDA version the
 # NVIDIA driver supports.  nvidia-smi reports this as "CUDA Version: X.Y".
 # If we install a toolkit newer than the driver supports, llama-server will
@@ -1146,6 +1157,11 @@ if ($DriverMaxCuda) {
 
 # -- If incompatible toolkit is blocking, tell user to uninstall it --
 if (-not $NvccPath -and $IncompatibleToolkit) {
+    if (-not $RequireOrExit) {
+        substep "CUDA Toolkit $IncompatibleToolkit exceeds driver max $DriverMaxCuda -- skipping; prebuilt llama.cpp needs no local toolkit" "Yellow"
+        $script:CudaToolkitReady = $false
+        return
+    }
     Write-Host "" -ForegroundColor Red
     Write-Host "========================================================================" -ForegroundColor Red
     Write-Host "[ERROR] CUDA Toolkit $IncompatibleToolkit is installed but INCOMPATIBLE" -ForegroundColor Red
@@ -1163,8 +1179,8 @@ if (-not $NvccPath -and $IncompatibleToolkit) {
     exit 1
 }
 
-# -- No toolkit at all: install via winget --
-if (-not $NvccPath) {
+# -- No toolkit at all: install via winget (only when a source build needs it) --
+if (-not $NvccPath -and $RequireOrExit) {
     Write-Host "CUDA toolkit (nvcc) not found -- installing via winget..." -ForegroundColor Yellow
     $HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
     if ($HasWinget) {
@@ -1223,6 +1239,11 @@ if (-not $NvccPath) {
 }
 
 if (-not $NvccPath) {
+    if (-not $RequireOrExit) {
+        substep "no driver-compatible CUDA Toolkit found -- skipping; prebuilt llama.cpp needs no local toolkit" "Yellow"
+        $script:CudaToolkitReady = $false
+        return
+    }
     Write-Host "[ERROR] CUDA Toolkit (nvcc) is required but could not be found or installed." -ForegroundColor Red
     if ($DriverMaxCuda) {
         Write-Host "        Install CUDA Toolkit $DriverMaxCuda from https://developer.nvidia.com/cuda-toolkit-archive" -ForegroundColor Yellow
@@ -1313,8 +1334,11 @@ substep "CudaToolkitDir = $CudaToolkitRoot\"
 if (-not $CudaArch) {
     substep "could not detect compute capability -- cmake will use defaults" "Yellow"
 }
-} else {
-    step "cuda" "skipped (no NVIDIA GPU detected)" "Yellow"
+# Publish the resolved toolkit to script scope for the Phase 4 build.
+$script:NvccPath = $NvccPath
+$script:CudaToolkitRoot = $CudaToolkitRoot
+$script:CudaArch = $CudaArch
+$script:CudaToolkitReady = $true
 }
 
 if ($HasROCm) {
@@ -2581,7 +2605,8 @@ if ($NeedLlamaSourceBuild) {
 # We build:
 #   - llama-server:   for GGUF model inference (with HTTPS if OpenSSL available)
 #   - llama-quantize: for GGUF export quantization
-# Prerequisites (git, cmake, VS Build Tools, CUDA Toolkit) already installed in Phase 1.
+# Prerequisites git, cmake, VS Build Tools were installed in Phase 1; the CUDA
+# Toolkit is resolved lazily just below via Resolve-CudaToolkit (source build only).
 $OriginalLlamaCppDir = $LlamaCppDir
 $BuildDir = Join-Path $LlamaCppDir "build"
 $LlamaServerBin = Join-Path $BuildDir "bin\Release\llama-server.exe"
@@ -2627,6 +2652,10 @@ if (-not $NeedLlamaSourceBuild) {
     substep "Install CMake from https://cmake.org/download/ and re-run setup." "Yellow"
     $script:LlamaCppDegraded = $true
 } else {
+    # A source build is committed here. The CUDA toolkit is only needed now, so
+    # resolve (and winget-install if needed) it lazily, failing fast if no
+    # driver-compatible toolkit exists. The prebuilt path never reaches this.
+    if ($HasNvidiaSmi) { Resolve-CudaToolkit -RequireOrExit }
     Write-Host ""
     if ($HasNvidiaSmi) {
         substep "building llama.cpp with CUDA support..."
diff --git a/tests/studio/test_resolve_cuda_toolkit.ps1 b/tests/studio/test_resolve_cuda_toolkit.ps1
new file mode 100644
index 0000000000..42076cdfe0
--- /dev/null
+++ b/tests/studio/test_resolve_cuda_toolkit.ps1
@@ -0,0 +1,121 @@
+#!/usr/bin/env pwsh
+# Unit test for Resolve-CudaToolkit in studio/setup.ps1. No GPU required: the
+# detection helpers (nvidia-smi, nvcc, Find-Nvcc, ...) are stubbed so the real
+# function logic runs against a spoofed Blackwell sm_120 / driver 13.2 host.
+#
+# The function is extracted via AST and run in a child pwsh per scenario, because
+# the -RequireOrExit path calls `exit` (which would otherwise kill this harness).
+#
+# Run: pwsh -NoProfile -File tests/studio/test_resolve_cuda_toolkit.ps1
+
+$ErrorActionPreference = "Stop"
+$setupPath = [System.IO.Path]::Combine($PSScriptRoot, "..", "..", "studio", "setup.ps1")
+$setupPath = (Resolve-Path $setupPath).Path
+
+# --- Extract the function source (not the whole installer) ---
+$tokens = $null; $errors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseFile($setupPath, [ref]$tokens, [ref]$errors)
+if ($errors) { $errors | ForEach-Object { $_.ToString() }; throw "setup.ps1 has parse errors" }
+$fn = $ast.FindAll({ param($n)
+    $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq "Resolve-CudaToolkit"
+}, $true)
+if ($fn.Count -ne 1) { throw "expected exactly one Resolve-CudaToolkit, found $($fn.Count)" }
+$fnText = $fn[0].Extent.Text
+
+# --- Spoof executables: nvidia-smi reports driver max CUDA 13.2; nvcc 13.3 ---
+$work = Join-Path ([System.IO.Path]::GetTempPath()) ("rct_" + [guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Force -Path $work | Out-Null
+$smiFake  = Join-Path $work "nvidia-smi.ps1"
+$nvccFake = Join-Path $work "nvcc.ps1"
+Set-Content -LiteralPath $smiFake  -Value "'CUDA Version: 13.2'"
+Set-Content -LiteralPath $nvccFake -Value "'Cuda compilation tools, release 13.3, V13.3.0'"
+
+$failures = 0
+function Check($name, $cond) {
+    if ($cond) { Write-Host "  PASS  $name" }
+    else { Write-Host "  FAIL  $name" -ForegroundColor Red; $script:failures++ }
+}
+
+# Build + run one scenario in a child pwsh; returns @{ Exit; Out }.
+function Run-Case {
+    param([string]$FindMode, [bool]$Require)
+    $requireLit = if ($Require) { '$true' } else { '$false' }
+    $child = @"
+`$ErrorActionPreference = 'Continue'
+[Environment]::SetEnvironmentVariable('CUDA_PATH', `$null, 'Process')
+`$FindNvccMode = '$FindMode'
+`$NvccFake = '$nvccFake'
+function substep { param(`$m, `$c) Write-Host "  `$m" }
+function step    { param(`$l, `$v, `$c) Write-Host "[`$l] `$v" }
+function Add-ToUserPath { param(`$Directory, `$Position) `$true }
+function Refresh-Environment { }
+function Get-CudaComputeCapability { '120' }
+function Test-NvccArchSupport { param(`$NvccExe, `$Arch) `$true }
+function Get-NvccMaxArch { param(`$NvccExe) '120' }
+`$script:WingetCalled = `$false
+function winget { `$script:WingetCalled = `$true; 'no matching versions' }
+function Find-Nvcc {
+    param([string]`$MaxVersion = '')
+    switch (`$FindNvccMode) {
+        'compatible'   { return `$NvccFake }
+        'incompatible' { if (`$MaxVersion) { return `$null } else { return `$NvccFake } }
+        default        { return `$null }
+    }
+}
+`$NvidiaSmiExe  = '$smiFake'
+`$VsInstallPath = `$null
+`$HasNvidiaSmi  = `$true
+`$script:CudaToolkitReady = `$false
+`$script:NvccPath = `$null; `$script:CudaToolkitRoot = `$null; `$script:CudaArch = `$null
+
+$fnText
+
+if ($requireLit) { Resolve-CudaToolkit -RequireOrExit } else { Resolve-CudaToolkit }
+Write-Host ("RESULT ready={0} nvcc={1} winget={2}" -f `$script:CudaToolkitReady, `$script:NvccPath, `$script:WingetCalled)
+"@
+    $childFile = Join-Path $work ("case_" + [guid]::NewGuid().ToString("N") + ".ps1")
+    Set-Content -LiteralPath $childFile -Value $child
+    $out = & pwsh -NoProfile -File $childFile 2>&1 | Out-String
+    return @{ Exit = $LASTEXITCODE; Out = $out }
+}
+
+try {
+    Write-Host "Scenario 1: prebuilt path, too-new toolkit (no -RequireOrExit) -> defers, no exit"
+    $r = Run-Case -FindMode "incompatible" -Require $false
+    Check "exits 0 (not blocked)"        ($r.Exit -eq 0)
+    Check "CudaToolkitReady = false"     ($r.Out -match "ready=False")
+    Check "winget NOT called"            ($r.Out -match "winget=False")
+    Check "no INCOMPATIBLE error text"   (-not ($r.Out -match "INCOMPATIBLE"))
+
+    Write-Host "Scenario 2: forced source build, too-new toolkit (-RequireOrExit) -> hard exit"
+    $r = Run-Case -FindMode "incompatible" -Require $true
+    Check "exits non-zero"               ($r.Exit -ne 0)
+    Check "preserved INCOMPATIBLE error" ($r.Out -match "is installed but INCOMPATIBLE")
+
+    Write-Host "Scenario 3: compatible toolkit (-RequireOrExit) -> resolves, env set"
+    $r = Run-Case -FindMode "compatible" -Require $true
+    Check "exits 0"                      ($r.Exit -eq 0)
+    Check "CudaToolkitReady = true"      ($r.Out -match "ready=True")
+    Check "NvccPath published"           ($r.Out -match "nvcc=.*nvcc")
+
+    Write-Host "Scenario 4: no toolkit, prebuilt path (no -RequireOrExit) -> defers, no winget"
+    $r = Run-Case -FindMode "none" -Require $false
+    Check "exits 0"                      ($r.Exit -eq 0)
+    Check "CudaToolkitReady = false"     ($r.Out -match "ready=False")
+    Check "winget NOT called"            ($r.Out -match "winget=False")
+
+    Write-Host "Scenario 5: no toolkit, forced (-RequireOrExit) -> winget attempted then exit"
+    # The function exits before the RESULT line here, so assert on the winget-block
+    # marker in output rather than the flag.
+    $r = Run-Case -FindMode "none" -Require $true
+    Check "winget attempted"             ($r.Out -match "installing via winget")
+    Check "exits non-zero"               ($r.Exit -ne 0)
+    Check "preserved nvcc-required error" ($r.Out -match "CUDA Toolkit \(nvcc\) is required")
+}
+finally {
+    Remove-Item -Recurse -Force -LiteralPath $work -ErrorAction SilentlyContinue
+}
+
+Write-Host ""
+if ($failures -gt 0) { Write-Host "$failures check(s) FAILED" -ForegroundColor Red; exit 1 }
+Write-Host "All checks passed" -ForegroundColor Green

From 0091b72a90afe6ee33a70b8696f480bc6eef9f44 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 02:55:54 -0700
Subject: [PATCH 048/222] Studio CI: tolerate transient artifact-upload flakes
 on diagnostic log steps (#5913)

---
 .github/workflows/studio-inference-smoke.yml         | 6 ++++++
 .github/workflows/studio-mac-inference-smoke.yml     | 6 ++++++
 .github/workflows/studio-windows-inference-smoke.yml | 6 ++++++
 3 files changed, 18 insertions(+)

diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.yml
index 6def56f769..c1297b84cc 100644
--- a/.github/workflows/studio-inference-smoke.yml
+++ b/.github/workflows/studio-inference-smoke.yml
@@ -296,6 +296,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: openai-anthropic-log
@@ -771,6 +773,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: tool-calling-log
@@ -1043,6 +1047,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: json-images-log
diff --git a/.github/workflows/studio-mac-inference-smoke.yml b/.github/workflows/studio-mac-inference-smoke.yml
index 1096b1abb4..e08ac6ca68 100644
--- a/.github/workflows/studio-mac-inference-smoke.yml
+++ b/.github/workflows/studio-mac-inference-smoke.yml
@@ -289,6 +289,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: openai-anthropic-log
@@ -649,6 +651,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: tool-calling-log
@@ -1025,6 +1029,8 @@ jobs:
       - name: Upload logs
         # Always upload so green runs are still reviewable.
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: json-images-log
diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 6253b9d213..98e8da8a29 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -373,6 +373,8 @@ jobs:
 
       - name: Upload logs
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: windows-openai-anthropic-log
@@ -801,6 +803,8 @@ jobs:
 
       - name: Upload logs
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: windows-tool-calling-log
@@ -1199,6 +1203,8 @@ jobs:
 
       - name: Upload logs
         if: always()
+        # Diagnostic only: a transient artifact-service drop must not fail a green job.
+        continue-on-error: true
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: windows-json-images-log

From ab7a7f9f1c97d99d5dd13da0ef371904c5cc5e6b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 02:55:57 -0700
Subject: [PATCH 049/222] Studio: match the Linux llama.cpp prebuilt to the
 runtime cudart major (#5914)

* Studio: match the Linux llama.cpp prebuilt to the runtime cudart major

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/install_llama_prebuilt.py              | 11 ++-
 .../test_install_llama_prebuilt_logic.py      | 74 +++++++++++++++++++
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 2afd54bec9..77d0905020 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -1402,7 +1402,16 @@ def direct_linux_release_plan(
 
     attempts: list[AssetChoice] = []
     if host.has_usable_nvidia:
-        selection = linux_cuda_choice_from_release(host, bundle)
+        # Prefer the cudart major Studio loads at runtime (torch's bundled
+        # libcudart), not the newest detected on disk. Without this a stray
+        # cuda13 runtime outranks the torch cuda12 the binary links against.
+        torch_preference = detect_torch_cuda_runtime_preference(host)
+        selection = linux_cuda_choice_from_release(
+            host,
+            bundle,
+            preferred_runtime_line = torch_preference.runtime_line,
+            selection_preamble = torch_preference.selection_log,
+        )
         if selection is not None:
             attempts.extend(selection.attempts)
     if host.has_rocm and not host.has_usable_nvidia:
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 49ad6da177..4a427d6f54 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -438,6 +438,80 @@ def test_simple_linux_direct_release_uses_published_source_checksums_for_branch(
     assert exact_source is True
 
 
+def test_simple_linux_direct_release_honors_torch_cudart_preference(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    # Regression: a Blackwell host (sm_120, driver 13.0) with BOTH cudart majors
+    # visible -- a stray cuda13 wheel plus torch's cuda12 -- must install the
+    # cuda12 build that matches the runtime torch, not the newest-major cuda13
+    # build (which loads no GPU and silently falls back to CPU).
+    release = {
+        "tag_name": "b9334",
+        "assets": [
+            {
+                "name": f"app-b9334-linux-x64-{profile}.tar.gz",
+                "browser_download_url": f"https://example.test/app-b9334-linux-x64-{profile}.tar.gz",
+            }
+            for profile in (
+                "cuda12-newer",
+                "cuda12-portable",
+                "cuda13-newer",
+                "cuda13-portable",
+            )
+        ],
+    }
+    # cuda13 detected first (newest-major order); both compatible with driver 13.0.
+    monkeypatch.setattr(
+        INSTALL_LLAMA_PREBUILT,
+        "detected_linux_runtime_lines",
+        lambda: (
+            ["cuda13", "cuda12"],
+            {
+                "cuda13": ["/usr/local/lib/python3.13/site-packages/nvidia/cu13/lib"],
+                "cuda12": [
+                    "/venv/lib/python3.13/site-packages/nvidia/cuda_runtime/lib"
+                ],
+            },
+        ),
+    )
+    host = HostInfo(
+        system = "Linux",
+        machine = "x86_64",
+        is_windows = False,
+        is_linux = True,
+        is_macos = False,
+        is_x86_64 = True,
+        is_arm64 = False,
+        nvidia_smi = "nvidia-smi",
+        driver_cuda_version = (13, 0),
+        compute_caps = ["120"],
+        visible_cuda_devices = None,
+        has_physical_nvidia = True,
+        has_usable_nvidia = True,
+    )
+
+    def first_asset_for_torch(line):
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "detect_torch_cuda_runtime_preference",
+            lambda h: INSTALL_LLAMA_PREBUILT.CudaRuntimePreference(
+                runtime_line = line, selection_log = []
+            ),
+        )
+        plan = INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
+            release, host, "unslothai/llama.cpp", "latest"
+        )
+        return plan.attempts[0]
+
+    # torch reports cuda12 (the cu128 runtime) -> install the cuda12 build.
+    primary = first_asset_for_torch("cuda12")
+    assert primary.name == "app-b9334-linux-x64-cuda12-newer.tar.gz"
+    assert primary.runtime_line == "cuda12"
+
+    # torch unavailable -> unchanged newest-major fallback (documents the residual).
+    assert first_asset_for_torch(None).name == "app-b9334-linux-x64-cuda13-newer.tar.gz"
+
+
 @pytest.mark.parametrize(
     "mutate, expected_match",
     [

From f695fbd0fe35df3647836931cdeeda9db4d4336b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 06:35:28 -0700
Subject: [PATCH 050/222] Studio: extend the pinned Blackwell GPU fallback to
 CUDA 13.0 drivers (#5920)

The pinned b9360 cuda-13.1 Windows fallback for Blackwell (sm_120) only fired
when the driver advertised CUDA >= 13.1. The mainstream Blackwell branch ships
the r580 driver that reports CUDA 13.0, so those hosts missed the pin, were
gated off the in-release 13.3 build, and dropped to the CPU-only cuda-12.4
build.

b9360's binary is native sm_120a SASS (no PTX, so no JIT) and its bundled
runtime is cuda-13.1 cudart; both run on a 13.0 r580+ driver under CUDA
minor-version compatibility. Lower _PINNED_BLACKWELL_DRIVER_FLOOR to (13, 0) so
the pin covers the 13.0 branch too. The generic published-runtime gate stays
conservative (an unverified in-release 13.1 build is still gated off 13.0); only
the specific, hash-pinned, SASS-verified b9360 build is extended.

Refs #5887.
---
 studio/install_llama_prebuilt.py             |  7 +++++--
 tests/studio/install/test_selection_logic.py | 14 +++++++++-----
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 77d0905020..b0af64fc8d 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -237,13 +237,16 @@ _MAX_PROBE_CUDA_MAJOR = 19
 # Last ggml-org release whose Windows win-cuda-13 build is still sub-13.3
 # (cuda-13.1, b9360, 2026-05-27). Upstream bumped win-cuda-13 to 13.3 at b9365
 # and now ships only cuda-12.4 + cuda-13.3. cuda-12.4 predates Blackwell (ggml
-# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a 13.1/13.2
+# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a 13.0/13.1/13.2
 # driver is gated off 13.3 and would drop to a CPU-only 12.4 build. b9360 is
 # immutable, so we pin its cuda-13.1 build (plus paired cudart) as a GPU
 # fallback for exactly those hosts. See unslothai/unsloth#5887.
 _PINNED_BLACKWELL_FALLBACK_TAG = "b9360"
 _PINNED_BLACKWELL_FALLBACK_RUNTIME = "13.1"
-_PINNED_BLACKWELL_DRIVER_FLOOR = (13, 1)
+# Floor at 13.0: b9360 ships native sm_120a SASS (no PTX/JIT) and a bundled
+# cuda-13.1 cudart, both of which run on a CUDA 13.0 r580+ driver via CUDA
+# minor-version compatibility, so the mainstream 13.0 Blackwell branch is covered.
+_PINNED_BLACKWELL_DRIVER_FLOOR = (13, 0)
 _BLACKWELL_MIN_SM = 120
 # ggml compiles Blackwell sm_120 only at toolkit >= 12.8, so an in-release
 # windows-cuda build at or above this already covers Blackwell and makes the
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 78aa9c480e..8cb53d1aeb 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -2021,7 +2021,7 @@ class TestWindowsCudaAttempts:
 
 
 class TestPinnedBlackwellCudaFallback:
-    """A Blackwell host on a 13.1/13.2 driver, gated off the in-release 13.3
+    """A Blackwell host on a 13.0/13.1/13.2 driver, gated off the in-release 13.3
     build, gets the pinned immutable b9360 cuda-13.1 GPU build instead of the
     CPU-only cuda-12.4 drop. The pin is dormant for everyone else."""
 
@@ -2072,15 +2072,19 @@ class TestPinnedBlackwellCudaFallback:
         # Ada/Hopper run the cuda-12.4 build fine; the pin must not fire.
         assert _pinned_windows_cuda_fallback(self._win_host((13, 1), [sm]), []) is None
 
-    def test_pin_not_offered_to_driver_13_0(self):
-        # 13.0 cannot run the 13.1 build (forward minor); residual CPU gap.
+    def test_pin_offered_for_driver_13_0(self):
+        # b9360 is native sm_120a SASS (no JIT) and ships a cuda-13.1 cudart,
+        # both of which run on a 13.0 r580+ driver via CUDA minor-version
+        # compatibility. 13.0 is the mainstream Blackwell branch, so it must fire.
         assert (
-            _pinned_windows_cuda_fallback(self._win_host((13, 0), ["120"]), []) is None
+            _pinned_windows_cuda_fallback(self._win_host((13, 0), ["120"]), [])
+            is not None
         )
 
     def test_pin_not_offered_below_floor(self):
+        # 12.x predates Blackwell entirely; the pin stays dormant below 13.0.
         assert (
-            _pinned_windows_cuda_fallback(self._win_host((12, 8), ["120"]), []) is None
+            _pinned_windows_cuda_fallback(self._win_host((12, 9), ["120"]), []) is None
         )
 
     def test_pin_not_offered_without_driver(self):

From 172d9d1c8e98b136d2fa124bf7f76ece39ee5335 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 06:35:43 -0700
Subject: [PATCH 051/222] Studio: source-build arm64 Linux GPU hosts, with a
 CPU prebuilt fallback (#5924)

* Studio: fall back to source build for arm64 Linux GPU hosts

setup.sh routes a Linux host with any GPU tool to the unslothai/llama.cpp fork,
which publishes only linux-x64 bundles. On an arm64 host with a GPU (GH200,
GB200, DGX Spark) the resolver then selected an x64 CUDA bundle, which cannot run
on aarch64. Routing those hosts to ggml-org instead would install a CPU-only
arm64 build, silently losing the GPU.

Guard resolve_simple_install_release_plans so an arm64 Linux host on the fork
raises PrebuiltFallback before any release is fetched, letting setup.sh do a
source build that actually targets the GPU. x86_64 hosts and arm64 CPU hosts
(which route to ggml-org) are unaffected.

Add tests covering the arm64 fork raise, the x86_64 pass-through, and the arm64
CPU ggml-org path.

* Studio: install ggml-org arm64 CPU prebuilt when the arm64 GPU source build fails

Per review of #5924: arm64 Linux GPU hosts have no CUDA prebuilt anywhere (the
unslothai fork is x64 only, ggml-org ships no Linux CUDA build), so they source
build for the GPU. If that build produces no binary, the host was left without
llama.cpp.

Add a --cpu-fallback flag to install_llama_prebuilt.py that drops the host GPU
attributes so the CPU prebuilt for the host arch is selected (a GPU host cannot
otherwise pick the CPU bundle). setup.sh calls it against ggml-org as a last
resort for arm64 Linux when the source build degraded, installing the
ubuntu-arm64 CPU build instead of leaving the host with no llama.cpp.

Add tests: force_cpu drops GPU attrs before planning, a CPU-forced arm64 host
selects the ggml-org ubuntu-arm64 bundle, and setup.sh wires the fallback.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/install_llama_prebuilt.py             |  32 ++++
 studio/setup.sh                              |  26 +++
 tests/studio/install/test_selection_logic.py | 162 +++++++++++++++++++
 3 files changed, 220 insertions(+)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index b0af64fc8d..ca26a112bc 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -1661,6 +1661,15 @@ def resolve_simple_install_release_plans(
 ) -> tuple[str, list[InstallReleasePlan]]:
     repo = published_repo or DEFAULT_PUBLISHED_REPO
     requested_tag = normalized_requested_llama_tag(llama_tag)
+    # The unslothai/llama.cpp fork ships only linux-x64 bundles. An arm64 Linux
+    # host with a GPU (GH200/GB200/DGX Spark) routes here; it must not install an
+    # x64 binary, so fall back to a source build that targets the GPU rather than
+    # selecting the wrong arch (or silently dropping to a CPU arm64 build).
+    if host.is_linux and not host.is_x86_64 and repo == DEFAULT_PUBLISHED_REPO:
+        raise PrebuiltFallback(
+            f"{repo} ships only linux-x64 prebuilts; "
+            f"{host.machine or 'non-x64'} Linux falls back to source build"
+        )
     allow_older_release_fallback = (
         requested_tag == "latest" and not published_release_tag
     )
@@ -6451,10 +6460,22 @@ def install_prebuilt(
     *,
     simple_policy: bool = False,
     override_has_rocm: bool = False,
+    force_cpu: bool = False,
 ) -> None:
     host = detect_host()
     if override_has_rocm and not host.has_rocm:
         host = dataclasses_replace(host, has_rocm = True)
+    if force_cpu:
+        # Explicit CPU fallback: drop GPU attributes so the CPU prebuilt for this
+        # OS/arch is selected. setup.sh uses this for arm64 Linux GPU hosts whose
+        # source build failed, where no arm64 CUDA prebuilt exists anywhere.
+        host = dataclasses_replace(
+            host,
+            has_usable_nvidia = False,
+            has_physical_nvidia = False,
+            has_rocm = False,
+            rocm_gfx_target = None,
+        )
     choice: AssetChoice | None = None
     try:
         with install_lock(install_lock_path(install_dir)):
@@ -6599,6 +6620,16 @@ def parse_args() -> argparse.Namespace:
             "so the HIP llama.cpp prebuilt is selected even when hipinfo is not on PATH."
         ),
     )
+    parser.add_argument(
+        "--cpu-fallback",
+        action = "store_true",
+        default = False,
+        help = (
+            "Select the CPU prebuilt for this OS/arch even when a GPU is present. "
+            "setup.sh uses this as a last resort for arm64 Linux GPU hosts whose "
+            "source build failed (no arm64 CUDA prebuilt exists anywhere)."
+        ),
+    )
     resolve_group = parser.add_mutually_exclusive_group()
     resolve_group.add_argument(
         "--resolve-llama-tag",
@@ -6720,6 +6751,7 @@ def main() -> int:
         published_release_tag = args.published_release_tag or "",
         simple_policy = args.simple_policy,
         override_has_rocm = args.has_rocm,
+        force_cpu = args.cpu_fallback,
     )
     return EXIT_SUCCESS
 
diff --git a/studio/setup.sh b/studio/setup.sh
index 3a149d465f..77013f0e6d 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -1363,6 +1363,32 @@ else
 }
 fi  # end _SKIP_GGUF_BUILD check
 
+# ── arm64 Linux GPU: CPU prebuilt as a last resort ──
+# arm64 Linux with a GPU has no CUDA prebuilt anywhere (the unslothai fork is
+# x64 only; ggml-org ships no Linux CUDA build), so it source-builds for the
+# GPU above. If that produced no binary, install ggml-org's arm64 CPU prebuilt
+# instead of leaving the host without llama.cpp.
+if [ "$_LLAMA_CPP_DEGRADED" = true ] \
+        && [ "$_HOST_SYSTEM" = "Linux" ] \
+        && { [ "$_HOST_MACHINE" = "aarch64" ] || [ "$_HOST_MACHINE" = "arm64" ]; }; then
+    substep "GPU source build unavailable; trying ggml-org arm64 CPU prebuilt..."
+    _ARM64_CPU_CMD=(
+        python "$SCRIPT_DIR/install_llama_prebuilt.py"
+        --install-dir "$LLAMA_CPP_DIR"
+        --llama-tag "$_REQUESTED_LLAMA_TAG"
+        --published-repo "ggml-org/llama.cpp"
+        --simple-policy
+        --cpu-fallback
+    )
+    # Trust the installer's exit code: it validates the server before exiting 0,
+    # the same signal the primary prebuilt path above relies on.
+    if run_quiet_no_exit "arm64 CPU prebuilt" "${_ARM64_CPU_CMD[@]}"; then
+        step "llama.cpp" "arm64 CPU prebuilt installed (GPU build unavailable)" "$C_WARN"
+        _LLAMA_CPP_DEGRADED=false
+        print_installed_llama_prebuilt_release "$LLAMA_CPP_DIR"
+    fi
+fi
+
 # ── Footer ──
 if [ "$_LLAMA_ONLY" = "1" ]; then
     echo ""
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 8cb53d1aeb..30ad3dd88b 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -2762,3 +2762,165 @@ class TestResolveSimpleMacosPin:
         assert plans[0].release_tag == "b9442"
         # No pin: the iterator was asked for latest, not a specific tag.
         assert calls[0][2] == "latest"
+
+
+# ===========================================================================
+# Linux arm64 + GPU must not install the x64-only fork bundle
+# ===========================================================================
+
+
+class TestLinuxArm64ForkFallsBackToSource:
+    """The unslothai/llama.cpp fork ships only linux-x64 bundles. An arm64
+    Linux host with a GPU (GH200/GB200/DGX Spark) routes to the fork and must
+    fall back to a source build instead of selecting an x64 binary."""
+
+    def test_arm64_nvidia_fork_raises_before_fetching_releases(self, monkeypatch):
+        # Guard fires before any release is fetched: poison the iterator to prove
+        # it is never called.
+        def _boom(*_a, **_k):
+            raise AssertionError("iterator must not run for arm64 fork hosts")
+
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", _boom
+        )
+        host = make_host(system = "Linux", machine = "aarch64")
+        with pytest.raises(PrebuiltFallback, match = "linux-x64 prebuilts"):
+            resolve_simple_install_release_plans(
+                "latest", host, "unslothai/llama.cpp", ""
+            )
+
+    def test_x86_64_fork_is_not_blocked_by_the_arch_guard(self, monkeypatch):
+        # x64 host must pass the guard and reach the iterator (here empty, so it
+        # raises the generic message, not the arch one).
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "iter_release_payloads_by_time",
+            lambda *_a, **_k: iter(()),
+        )
+        host = make_host(system = "Linux", machine = "x86_64")
+        with pytest.raises(PrebuiltFallback) as exc:
+            resolve_simple_install_release_plans(
+                "latest", host, "unslothai/llama.cpp", ""
+            )
+        assert "linux-x64 prebuilts" not in str(exc.value)
+
+    def test_arm64_cpu_on_ggml_org_is_not_blocked(self, monkeypatch):
+        # CPU-only arm64 routes to ggml-org (not the fork), so the guard must not
+        # fire; it reaches the iterator (empty here -> generic message).
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "iter_release_payloads_by_time",
+            lambda *_a, **_k: iter(()),
+        )
+        host = make_host(
+            system = "Linux",
+            machine = "aarch64",
+            nvidia_smi = None,
+            driver_cuda_version = None,
+            compute_caps = [],
+            has_physical_nvidia = False,
+            has_usable_nvidia = False,
+        )
+        with pytest.raises(PrebuiltFallback) as exc:
+            resolve_simple_install_release_plans(
+                "latest", host, "ggml-org/llama.cpp", ""
+            )
+        assert "linux-x64 prebuilts" not in str(exc.value)
+
+
+# ===========================================================================
+# arm64 Linux GPU: CPU prebuilt fallback after a failed source build (--cpu-fallback)
+# ===========================================================================
+
+
+class TestCpuFallback:
+    """--cpu-fallback drops GPU attributes so the CPU prebuilt for the host's
+    OS/arch is selected, letting an arm64 GPU host install ggml-org's arm64 CPU
+    build as a last resort when its source build produced no binary."""
+
+    _SETUP_SH = PACKAGE_ROOT / "studio" / "setup.sh"
+
+    def _arm64_nvidia(self):
+        return make_host(
+            system = "Linux",
+            machine = "aarch64",
+            driver_cuda_version = (13, 0),
+            compute_caps = ["90"],
+            has_physical_nvidia = True,
+            has_usable_nvidia = True,
+        )
+
+    def test_force_cpu_drops_gpu_attrs_before_planning(self, monkeypatch, tmp_path):
+        captured = {}
+
+        def _capture(llama_tag, host, *a, **k):
+            captured["host"] = host
+            raise PrebuiltFallback("stop after capture")
+
+        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", self._arm64_nvidia)
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "resolve_simple_install_release_plans",
+            _capture,
+        )
+        # install_prebuilt exits EXIT_FALLBACK on PrebuiltFallback; we only care
+        # about the host it handed to the resolver before that.
+        with pytest.raises(SystemExit):
+            INSTALL_LLAMA_PREBUILT.install_prebuilt(
+                install_dir = tmp_path / "llama",
+                llama_tag = "latest",
+                published_repo = "ggml-org/llama.cpp",
+                published_release_tag = "",
+                simple_policy = True,
+                force_cpu = True,
+            )
+        host = captured["host"]
+        assert host.has_usable_nvidia is False
+        assert host.has_physical_nvidia is False
+        assert host.has_rocm is False
+        # Arch is preserved so the arm64 CPU bundle (not x64) is chosen.
+        assert host.is_arm64 is True
+
+    def test_cpu_forced_arm64_selects_ubuntu_arm64(self):
+        tag = "b9444"
+        release = {
+            "tag_name": tag,
+            "assets": [
+                {
+                    "name": f"llama-{tag}-bin-ubuntu-arm64.tar.gz",
+                    "browser_download_url": f"https://x/llama-{tag}-bin-ubuntu-arm64.tar.gz",
+                },
+                {
+                    "name": f"llama-{tag}-bin-ubuntu-x64.tar.gz",
+                    "browser_download_url": f"https://x/llama-{tag}-bin-ubuntu-x64.tar.gz",
+                },
+            ],
+        }
+        # A GPU arm64 host cannot pick the CPU arm64 bundle on its own.
+        with pytest.raises(PrebuiltFallback):
+            direct_upstream_release_plan(
+                release, self._arm64_nvidia(), "ggml-org/llama.cpp", "latest"
+            )
+        # force_cpu drops the GPU attributes, so the CPU arm64 bundle is selected.
+        cpu_host = make_host(
+            system = "Linux",
+            machine = "aarch64",
+            nvidia_smi = None,
+            driver_cuda_version = None,
+            compute_caps = [],
+            has_physical_nvidia = False,
+            has_usable_nvidia = False,
+        )
+        plan = direct_upstream_release_plan(
+            release, cpu_host, "ggml-org/llama.cpp", "latest"
+        )
+        assert plan.attempts[0].install_kind == "linux-arm64"
+        assert plan.attempts[0].name == f"llama-{tag}-bin-ubuntu-arm64.tar.gz"
+
+    def test_setup_sh_has_arm64_cpu_prebuilt_fallback(self):
+        source = self._SETUP_SH.read_text(encoding = "utf-8")
+        assert "--cpu-fallback" in source
+        # Fallback targets ggml-org (the only repo with an arm64 Linux build) and
+        # is gated on a degraded source build for arm64.
+        assert "ggml-org/llama.cpp" in source
+        assert "_LLAMA_CPP_DEGRADED" in source

From ef43b5f450a4d4317b4b32f7e6ad6058b6e02e92 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 06:35:58 -0700
Subject: [PATCH 052/222] Studio CI: run the Resolve-CudaToolkit unit test in
 the Windows GGUF job (#5921)

The deferred Windows CUDA Toolkit check (Resolve-CudaToolkit in setup.ps1) has a
pwsh unit test but nothing ran it. Rather than add a separate workflow, fold a
fast GPU-free gate into the existing Windows GGUF CI: parse setup.ps1 and run
tests/studio/test_resolve_cuda_toolkit.ps1 right after checkout, before the heavy
GGUF smoke, so a setup.ps1 regression fails fast on the runner that is already
spun up.

Refs #5912.
---
 .github/workflows/studio-windows-inference-smoke.yml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 98e8da8a29..10caac3940 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -65,6 +65,18 @@ jobs:
         with:
           persist-credentials: false
 
+      # Fast GPU-free gate: parse setup.ps1 and run the Resolve-CudaToolkit unit
+      # test (deferred Windows CUDA Toolkit check) before the heavy GGUF smoke.
+      - name: setup.ps1 unit test (Resolve-CudaToolkit)
+        shell: pwsh
+        run: |
+          $errs = $null
+          [void][System.Management.Automation.Language.Parser]::ParseFile(
+            (Resolve-Path studio/setup.ps1).Path, [ref]$null, [ref]$errs)
+          if ($errs) { $errs | ForEach-Object { $_.ToString() }; exit 1 }
+          Write-Host "setup.ps1 parsed with no errors"
+          pwsh -NoProfile -File tests/studio/test_resolve_cuda_toolkit.ps1
+
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: '22'

From 86b1918056eb23dae321c22d85d66a4de506da77 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 06:55:35 -0700
Subject: [PATCH 053/222] Studio: forward the resolved AMD gfx arch to the
 prebuilt installer (#5923)

setup.sh and setup.ps1 resolve the AMD gfx target (rocminfo/hipinfo/amd-smi,
name inference, or UNSLOTH_ROCM_GFX_ARCH) but never passed it to
install_llama_prebuilt.py. The installer re-probed on its own and, on hosts where
hipinfo/amd-smi cannot report the arch (amd-smi-only Linux, HIP-runtime-only
Strix Halo, name-inferred GPUs), left rocm_gfx_target unset. The lemonade HIP
prebuilt selection needs that arch, so those hosts got no GPU prebuilt and fell
back to a source build.

Add a --rocm-gfx argument (defaulting to UNSLOTH_ROCM_GFX_ARCH) and fold it into
the host profile via _apply_host_overrides: a forwarded gfx is authoritative
(setup already applied visible-device selection) and implies has_rocm. setup.sh
and setup.ps1 now forward their resolved arch.

Add unit tests for _normalize_forwarded_gfx and _apply_host_overrides, plus
source checks that both setup scripts forward --rocm-gfx.
---
 studio/install_llama_prebuilt.py          | 71 ++++++++++++++----
 studio/setup.ps1                          |  6 ++
 studio/setup.sh                           |  6 ++
 tests/studio/install/test_rocm_support.py | 90 +++++++++++++++++++++++
 4 files changed, 160 insertions(+), 13 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index ca26a112bc..9c0a1bd1c1 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -3085,6 +3085,46 @@ def detect_host() -> HostInfo:
     )
 
 
+def _normalize_forwarded_gfx(value: str | None) -> str | None:
+    """Extract a single gfx token from a forwarded --rocm-gfx / env value.
+    setup.sh/setup.ps1 already picked the active GPU, so take the token as-is
+    without re-applying visible-device selection. Ignore anything malformed."""
+    if not value:
+        return None
+    m = re.search(r"gfx[1-9][0-9a-z]{2,3}", value.lower())
+    return m.group(0) if m else None
+
+
+def _apply_host_overrides(
+    host: HostInfo,
+    *,
+    override_has_rocm: bool = False,
+    override_rocm_gfx: str | None = None,
+    force_cpu: bool = False,
+) -> HostInfo:
+    """Fold setup.sh/setup.ps1's forwarded detection into the host profile.
+    A forwarded gfx (--rocm-gfx or UNSLOTH_ROCM_GFX_ARCH) is authoritative and
+    implies ROCm: the installer's own hipinfo/amd-smi probe can miss the arch on
+    amd-smi-only hosts or when setup inferred it from the GPU name, leaving
+    rocm_gfx_target None and no lemonade prebuilt selected. force_cpu is the
+    opposite explicit signal (arm64 Linux GPU host whose source build failed):
+    drop GPU attributes so the CPU prebuilt for this OS/arch is selected."""
+    if force_cpu:
+        return dataclasses_replace(
+            host,
+            has_usable_nvidia = False,
+            has_physical_nvidia = False,
+            has_rocm = False,
+            rocm_gfx_target = None,
+        )
+    gfx = _normalize_forwarded_gfx(override_rocm_gfx)
+    if gfx:
+        return dataclasses_replace(host, has_rocm = True, rocm_gfx_target = gfx)
+    if override_has_rocm and not host.has_rocm:
+        return dataclasses_replace(host, has_rocm = True)
+    return host
+
+
 def pick_windows_cuda_runtime(host: HostInfo) -> str | None:
     if not host.driver_cuda_version:
         return None
@@ -6460,22 +6500,16 @@ def install_prebuilt(
     *,
     simple_policy: bool = False,
     override_has_rocm: bool = False,
+    override_rocm_gfx: str | None = None,
     force_cpu: bool = False,
 ) -> None:
     host = detect_host()
-    if override_has_rocm and not host.has_rocm:
-        host = dataclasses_replace(host, has_rocm = True)
-    if force_cpu:
-        # Explicit CPU fallback: drop GPU attributes so the CPU prebuilt for this
-        # OS/arch is selected. setup.sh uses this for arm64 Linux GPU hosts whose
-        # source build failed, where no arm64 CUDA prebuilt exists anywhere.
-        host = dataclasses_replace(
-            host,
-            has_usable_nvidia = False,
-            has_physical_nvidia = False,
-            has_rocm = False,
-            rocm_gfx_target = None,
-        )
+    host = _apply_host_overrides(
+        host,
+        override_has_rocm = override_has_rocm,
+        override_rocm_gfx = override_rocm_gfx,
+        force_cpu = force_cpu,
+    )
     choice: AssetChoice | None = None
     try:
         with install_lock(install_lock_path(install_dir)):
@@ -6620,6 +6654,16 @@ def parse_args() -> argparse.Namespace:
             "so the HIP llama.cpp prebuilt is selected even when hipinfo is not on PATH."
         ),
     )
+    parser.add_argument(
+        "--rocm-gfx",
+        default = os.environ.get("UNSLOTH_ROCM_GFX_ARCH"),
+        help = (
+            "Forward the AMD gfx target (e.g. gfx1151) that setup.ps1/setup.sh "
+            "resolved, so the lemonade HIP prebuilt is selected even when the "
+            "installer's own hipinfo/amd-smi probe cannot report it. Implies "
+            "--has-rocm. Defaults to the UNSLOTH_ROCM_GFX_ARCH environment variable."
+        ),
+    )
     parser.add_argument(
         "--cpu-fallback",
         action = "store_true",
@@ -6751,6 +6795,7 @@ def main() -> int:
         published_release_tag = args.published_release_tag or "",
         simple_policy = args.simple_policy,
         override_has_rocm = args.has_rocm,
+        override_rocm_gfx = args.rocm_gfx,
         force_cpu = args.cpu_fallback,
     )
     return EXIT_SUCCESS
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 70e2fee334..28ad512690 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -2483,6 +2483,12 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
         )
         if ($HasROCm) {
             $prebuiltArgs += "--has-rocm"
+            # Forward the resolved gfx arch so the lemonade HIP prebuilt is picked
+            # even when the installer's own probe cannot report it (amd-smi-only
+            # hosts, name-inferred arch).
+            if ($script:ROCmGfxArch) {
+                $prebuiltArgs += @("--rocm-gfx", $script:ROCmGfxArch)
+            }
         }
         if ($env:UNSLOTH_LLAMA_RELEASE_TAG) {
             $prebuiltArgs += @("--published-release-tag", $env:UNSLOTH_LLAMA_RELEASE_TAG)
diff --git a/studio/setup.sh b/studio/setup.sh
index 77013f0e6d..b5c60030c3 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -857,6 +857,12 @@ else
     if [ -n "${UNSLOTH_LLAMA_RELEASE_TAG:-}" ]; then
         _PREBUILT_CMD+=(--published-release-tag "$UNSLOTH_LLAMA_RELEASE_TAG")
     fi
+    # Forward the gfx arch resolved above so the lemonade HIP prebuilt is picked
+    # even when the installer's own probe cannot report it (amd-smi-only hosts,
+    # name-inferred arch). Implies --has-rocm on the installer side.
+    if [ -n "${_setup_gfx:-}" ]; then
+        _PREBUILT_CMD+=(--rocm-gfx "$_setup_gfx")
+    fi
     _PREBUILT_LOG="$(mktemp)"
     set +e
     if _is_verbose; then
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index ec99e9a8d9..5b6586f9c9 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -35,6 +35,8 @@ AssetChoice = prebuilt_mod.AssetChoice
 PrebuiltFallback = prebuilt_mod.PrebuiltFallback
 resolve_upstream_asset_choice = prebuilt_mod.resolve_upstream_asset_choice
 runtime_patterns_for_choice = prebuilt_mod.runtime_patterns_for_choice
+_apply_host_overrides = prebuilt_mod._apply_host_overrides
+_normalize_forwarded_gfx = prebuilt_mod._normalize_forwarded_gfx
 
 # install_python_stack.py
 _STACK_PATH = PACKAGE_ROOT / "studio" / "install_python_stack.py"
@@ -2598,5 +2600,93 @@ class TestHipSdkInstalledButDeviceInaccessible:
         assert "GPU not ROCm-accessible" in source
 
 
+# =============================================================================
+# TEST: --rocm-gfx forwarding -- setup.sh/setup.ps1 hand their resolved gfx arch
+# to install_llama_prebuilt.py so the lemonade HIP prebuilt is selected even when
+# the installer's own hipinfo/amd-smi probe cannot report it.
+# =============================================================================
+
+_SETUP_SH_PATH = PACKAGE_ROOT / "studio" / "setup.sh"
+
+
+class TestNormalizeForwardedGfx:
+    """A forwarded gfx string is reduced to a single clean gfx token."""
+
+    def test_plain_token(self):
+        assert _normalize_forwarded_gfx("gfx1151") == "gfx1151"
+
+    def test_uppercase_normalized(self):
+        assert _normalize_forwarded_gfx("GFX1151") == "gfx1151"
+
+    def test_extracts_from_noise(self):
+        assert _normalize_forwarded_gfx("gcnArchName: gfx942") == "gfx942"
+
+    def test_malformed_is_ignored(self):
+        assert _normalize_forwarded_gfx("not-a-gpu") is None
+
+    def test_empty_and_none(self):
+        assert _normalize_forwarded_gfx("") is None
+        assert _normalize_forwarded_gfx(None) is None
+
+
+class TestApplyHostOverrides:
+    """Forwarded ROCm detection is folded into the host profile correctly."""
+
+    def test_forwarded_gfx_fills_empty_probe(self):
+        # amd-smi-only / name-inferred host: installer probe found no gfx.
+        host = rocm_host(rocm_gfx_target = None)
+        out = _apply_host_overrides(host, override_rocm_gfx = "gfx1151")
+        assert out.has_rocm is True
+        assert out.rocm_gfx_target == "gfx1151"
+
+    def test_forwarded_gfx_implies_rocm(self):
+        # A CPU-looking host with a forwarded gfx is an AMD host.
+        out = _apply_host_overrides(cpu_host(), override_rocm_gfx = "gfx1200")
+        assert out.has_rocm is True
+        assert out.rocm_gfx_target == "gfx1200"
+
+    def test_forwarded_gfx_is_authoritative(self):
+        # setup already applied visible-device selection; its value wins.
+        host = rocm_host(rocm_gfx_target = "gfx1100")
+        out = _apply_host_overrides(host, override_rocm_gfx = "gfx1151")
+        assert out.rocm_gfx_target == "gfx1151"
+
+    def test_has_rocm_only_keeps_probe_gfx(self):
+        out = _apply_host_overrides(cpu_host(), override_has_rocm = True)
+        assert out.has_rocm is True
+        assert out.rocm_gfx_target is None
+
+    def test_malformed_forwarded_gfx_falls_back_to_has_rocm(self):
+        out = _apply_host_overrides(
+            cpu_host(), override_has_rocm = True, override_rocm_gfx = "junk"
+        )
+        assert out.has_rocm is True
+        assert out.rocm_gfx_target is None
+
+    def test_no_overrides_leaves_host_unchanged(self):
+        host = nvidia_host()
+        assert _apply_host_overrides(host) is host
+
+
+class TestRocmGfxForwarding:
+    """setup.sh / setup.ps1 forward their resolved gfx; the installer accepts it."""
+
+    def test_installer_exposes_rocm_gfx_arg(self):
+        source = _PREBUILT_PATH.read_text(encoding = "utf-8")
+        assert '"--rocm-gfx"' in source
+        # Defaults to the env override so a standalone run still works.
+        assert 'os.environ.get("UNSLOTH_ROCM_GFX_ARCH")' in source
+
+    def test_setup_sh_forwards_rocm_gfx(self):
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "--rocm-gfx" in source
+        assert '"$_setup_gfx"' in source
+
+    def test_setup_ps1_forwards_rocm_gfx(self):
+        source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
+        assert "--rocm-gfx" in source
+        assert "$script:ROCmGfxArch" in source
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

From 52612d6ed369aed19b36b24369e38ca4cb50c546 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 07:24:09 -0700
Subject: [PATCH 054/222] Studio CI: tolerate transient runner crashes in the
 llama-server log collection step (#5925)

The 'Collect llama-server logs' diagnostic step copies llama-server stdout into
the workspace for debugging. On the Windows runners it intermittently dies with
exit code -1073741502 (0xC0000142, STATUS_DLL_INIT_FAILED) when spawning the
copy, which failed the whole Tool calling Tests job even though the tests had
already run.

It is a diagnostic-only step, so mark it continue-on-error in all three jobs, the
same treatment #5913 gave the artifact-upload steps. A transient log-collection
crash no longer turns a green job red.

Refs #5913.
---
 .github/workflows/studio-windows-inference-smoke.yml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 10caac3940..bbe6b9e33a 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -372,6 +372,9 @@ jobs:
 
       - name: Collect llama-server logs
         if: always()
+        # A transient Windows DLL-init crash (0xC0000142) in this diagnostic
+        # copy must not fail an otherwise-green job.
+        continue-on-error: true
         shell: bash
         # Copy llama-server's own stdout/stderr (teed by Studio under
         # ~/.unsloth/studio/logs/llama-server/) into the workspace so
@@ -802,6 +805,9 @@ jobs:
 
       - name: Collect llama-server logs
         if: always()
+        # A transient Windows DLL-init crash (0xC0000142) in this diagnostic
+        # copy must not fail an otherwise-green job.
+        continue-on-error: true
         shell: bash
         # Copy llama-server's own stdout/stderr (teed by Studio under
         # ~/.unsloth/studio/logs/llama-server/) into the workspace so
@@ -1202,6 +1208,9 @@ jobs:
 
       - name: Collect llama-server logs
         if: always()
+        # A transient Windows DLL-init crash (0xC0000142) in this diagnostic
+        # copy must not fail an otherwise-green job.
+        continue-on-error: true
         shell: bash
         # Copy llama-server's own stdout/stderr (teed by Studio under
         # ~/.unsloth/studio/logs/llama-server/) into the workspace so

From f1a0581078a0ff908d5084b133fc48de171ee6de Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Mon, 1 Jun 2026 09:32:48 -0500
Subject: [PATCH 055/222] Studio: forward --has-rocm from setup.sh when gfx
 resolution fails (#5927)

setup.ps1 already forwards --has-rocm whenever AMD is detected regardless
of whether gfx resolved. setup.sh only forwarded --rocm-gfx, so a Linux
host where AMD was detected but gfx resolution failed would forward nothing,
leaving the installer with has_rocm=False and falling back to a source build.

Add the elif branch to forward --has-rocm when _setup_amd_detected is true
but _setup_gfx is empty, matching setup.ps1 parity. Add a source-level test
to verify both flags are present in setup.sh.
---
 studio/setup.sh                           | 4 ++++
 tests/studio/install/test_rocm_support.py | 7 +++++++
 2 files changed, 11 insertions(+)

diff --git a/studio/setup.sh b/studio/setup.sh
index b5c60030c3..9b29def859 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -862,6 +862,10 @@ else
     # name-inferred arch). Implies --has-rocm on the installer side.
     if [ -n "${_setup_gfx:-}" ]; then
         _PREBUILT_CMD+=(--rocm-gfx "$_setup_gfx")
+    elif [ "$_setup_amd_detected" = true ]; then
+        # AMD was detected but gfx resolution failed; tell the installer ROCm is
+        # present so it can still attempt a prebuilt. Mirrors setup.ps1 behaviour.
+        _PREBUILT_CMD+=(--has-rocm)
     fi
     _PREBUILT_LOG="$(mktemp)"
     set +e
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 5b6586f9c9..1d6e4f4c51 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -2682,6 +2682,13 @@ class TestRocmGfxForwarding:
         assert "--rocm-gfx" in source
         assert '"$_setup_gfx"' in source
 
+    def test_setup_sh_forwards_has_rocm(self):
+        # When AMD is detected but gfx resolution fails, setup.sh must still
+        # forward --has-rocm so the installer knows ROCm is present.
+        source = _SETUP_SH_PATH.read_text(encoding = "utf-8")
+        assert "--has-rocm" in source
+        assert "_setup_amd_detected" in source
+
     def test_setup_ps1_forwards_rocm_gfx(self):
         source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
         assert "--rocm-gfx" in source

From 029698479e70a8bebce6249cb581c611d8f9c7a5 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 08:06:22 -0700
Subject: [PATCH 056/222] Update _utils.py

---
 unsloth/models/_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 59d7305a79..abb6969a7e 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2026.5.9"
+__version__ = "2026.5.10"
 
 __all__ = [
     "SUPPORTS_BFLOAT16",

From ae5d60728bdbe95457c39e5922260aa686c9cca1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 08:17:50 -0700
Subject: [PATCH 057/222] Studio: cover B300 (sm_103) with the Linux prebuilt
 bundles (#5930)

* Studio: cover B300 (sm_103) with the Linux prebuilt bundles

sm_103 (B300 / GB300 Blackwell Ultra) was in no bundle's supported_sms,
so those hosts fell through to a slow source compile. The newer and
portable bundles already ship base compute_100 PTX, which the driver
JIT-compiles forward to sm_103, so list sm_103 alongside sm_100 in those
bundles and let B300 install the prebuilt.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/install_llama_prebuilt.py             | 12 ++--
 tests/studio/install/test_selection_logic.py | 73 ++++++++++++++++++++
 2 files changed, 81 insertions(+), 4 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 9c0a1bd1c1..62b7b2b290 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -176,6 +176,10 @@ _PINNED_MACOS_FALLBACK_TAG = "b9415"
 _PINNED_MACOS_LATEST_FLOOR = (26, 0)
 FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master")
 
+# sm_103 (B300 / GB300 Blackwell Ultra) is not built natively but runs on the
+# bundled base compute_100 PTX, which the driver JIT-compiles forward to sm_103.
+# It is listed in every bundle that ships the sm_100 build (the "newer" and
+# "portable" classes) so those hosts get a prebuilt instead of a source compile.
 DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda12-older": {
         "runtime_line": "cuda12",
@@ -188,7 +192,7 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda12-newer": {
         "runtime_line": "cuda12",
         "coverage_class": "newer",
-        "supported_sms": ["86", "89", "90", "100", "120"],
+        "supported_sms": ["86", "89", "90", "100", "103", "120"],
         "min_sm": 86,
         "max_sm": 120,
         "rank": 20,
@@ -196,7 +200,7 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda12-portable": {
         "runtime_line": "cuda12",
         "coverage_class": "portable",
-        "supported_sms": ["70", "75", "80", "86", "89", "90", "100", "120"],
+        "supported_sms": ["70", "75", "80", "86", "89", "90", "100", "103", "120"],
         "min_sm": 70,
         "max_sm": 120,
         "rank": 30,
@@ -212,7 +216,7 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda13-newer": {
         "runtime_line": "cuda13",
         "coverage_class": "newer",
-        "supported_sms": ["86", "89", "90", "100", "120"],
+        "supported_sms": ["86", "89", "90", "100", "103", "120"],
         "min_sm": 86,
         "max_sm": 120,
         "rank": 50,
@@ -220,7 +224,7 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda13-portable": {
         "runtime_line": "cuda13",
         "coverage_class": "portable",
-        "supported_sms": ["75", "80", "86", "89", "90", "100", "120"],
+        "supported_sms": ["75", "80", "86", "89", "90", "100", "103", "120"],
         "min_sm": 75,
         "max_sm": 120,
         "rank": 60,
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 30ad3dd88b..2a94039018 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -1252,6 +1252,79 @@ class TestLinuxCudaChoiceFromRelease:
         assert result is None
 
 
+def make_profile_artifact(asset_name, profile_name, **overrides):
+    profile = INSTALL_LLAMA_PREBUILT.DIRECT_LINUX_BUNDLE_PROFILES[profile_name]
+    defaults = dict(
+        runtime_line = profile["runtime_line"],
+        coverage_class = profile["coverage_class"],
+        supported_sms = [str(value) for value in profile["supported_sms"]],
+        min_sm = int(profile["min_sm"]),
+        max_sm = int(profile["max_sm"]),
+        bundle_profile = profile_name,
+        rank = int(profile["rank"]),
+    )
+    defaults.update(overrides)
+    return make_artifact(asset_name, **defaults)
+
+
+class TestBlackwellUltraSm103Coverage:
+    """sm_103 (B300 / GB300) runs on the bundled base compute_100 PTX via JIT."""
+
+    def test_profiles_list_sm103_wherever_sm100_is_shipped(self):
+        for (
+            name,
+            profile,
+        ) in INSTALL_LLAMA_PREBUILT.DIRECT_LINUX_BUNDLE_PROFILES.items():
+            sms = {str(value) for value in profile["supported_sms"]}
+            if "100" in sms:
+                assert "103" in sms, name
+            else:
+                assert "103" not in sms, name
+
+    def test_b300_selects_cuda13_newer_prebuilt(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda13"])
+        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
+        art = make_profile_artifact("cuda13-newer.tar.gz", "cuda13-newer")
+        release = make_release([art])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is not None
+        assert result.primary.name == "cuda13-newer.tar.gz"
+
+    def test_b300_selects_cuda12_newer_prebuilt(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda12"])
+        host = make_host(compute_caps = ["103"], driver_cuda_version = (12, 8))
+        art = make_profile_artifact("cuda12-newer.tar.gz", "cuda12-newer")
+        release = make_release([art])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is not None
+        assert result.primary.name == "cuda12-newer.tar.gz"
+
+    def test_b300_reported_as_decimal_normalizes_and_matches(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda13"])
+        host = make_host(compute_caps = ["10.3"], driver_cuda_version = (13, 0))
+        art = make_profile_artifact("cuda13-portable.tar.gz", "cuda13-portable")
+        release = make_release([art])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is not None
+
+    def test_b300_falls_back_to_portable_when_only_portable_present(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda13"])
+        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
+        art = make_profile_artifact("cuda13-portable.tar.gz", "cuda13-portable")
+        release = make_release([art])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is not None
+        assert result.primary.name == "cuda13-portable.tar.gz"
+
+    def test_older_bundle_still_rejects_b300(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda13"])
+        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
+        art = make_profile_artifact("cuda13-older.tar.gz", "cuda13-older")
+        release = make_release([art])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is None
+
+
 # ===========================================================================
 # L. resolve_install_attempts
 # ===========================================================================

From a0b85bcc1d92e54d336390bbddd5909f0aeb50ce Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 08:18:12 -0700
Subject: [PATCH 058/222] Studio: move MCP to a composer button with presets
 (#5926)

Move MCP from the chat settings sidebar to a composer pill next to Artifacts. The dropdown lists keyless presets (Context7, Exa, Hugging Face), all off by default, created on first enable and deduped by URL. Add custom MCP opens the existing manage dialog. Enabled rows show a green underlay and a tick that becomes an X on hover to remove; enabling Exa turns off the built-in Web Search and shows a hover tooltip. Reconciles the per-chat MCP flag on load so already-enabled servers activate the pill. No backend changes.
---
 .../src/components/assistant-ui/thread.tsx    |   2 +
 .../features/chat/chat-mcp-servers-dialog.tsx |  10 +-
 .../src/features/chat/chat-settings-sheet.tsx |  76 ----
 .../src/features/chat/mcp-composer-button.tsx | 355 ++++++++++++++++++
 .../src/features/chat/shared-composer.tsx     |   2 +
 5 files changed, 368 insertions(+), 77 deletions(-)
 create mode 100644 studio/frontend/src/features/chat/mcp-composer-button.tsx

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 26fc60d972..b7e0f35d35 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -44,6 +44,7 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { sentAudioNames } from "@/features/chat/api/chat-adapter";
 import { parseExternalModelId } from "@/features/chat/external-providers";
+import { McpComposerButton } from "@/features/chat/mcp-composer-button";
 import { getExternalReasoningCapabilities } from "@/features/chat/provider-capabilities";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
 import { useExternalProvidersStore } from "@/features/chat/stores/external-providers-store";
@@ -1215,6 +1216,7 @@ const ComposerAction: FC<{
         <CodeToolsToggle />
         <ImagesToggle />
         <ArtifactsToggle />
+        <McpComposerButton />
       </div>
       <div className="flex items-center gap-1">
         <ComposerPrimitive.If dictation={false}>
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index b377e7a88e..93c4c8972c 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -178,6 +178,8 @@ function HeadersEditor({
 export interface ChatMcpServersDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  /** Open straight into the "add server" form instead of the list view. */
+  openToCreate?: boolean;
 }
 
 type View =
@@ -188,6 +190,7 @@ type View =
 export function ChatMcpServersDialog({
   open,
   onOpenChange,
+  openToCreate = false,
 }: ChatMcpServersDialogProps) {
   const [servers, setServers] = useState<McpServerConfig[]>([]);
   const [loading, setLoading] = useState(false);
@@ -214,7 +217,12 @@ export function ChatMcpServersDialog({
   useEffect(() => {
     if (!open) return;
     refresh();
-  }, [open, refresh]);
+    // Land on the create form when opened via "Add custom MCP".
+    if (openToCreate) {
+      setView({ kind: "create" });
+      setForm(EMPTY_FORM);
+    }
+  }, [open, openToCreate, refresh]);
 
   function startCreate() {
     setView({ kind: "create" });
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index b19aa68551..a6e42d18fc 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -90,8 +90,6 @@ import {
   providerSupportsFastMode,
 } from "./provider-capabilities";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
-import { ChatMcpServersDialog } from "./chat-mcp-servers-dialog";
-import { listMcpServers } from "./api/mcp-servers-api";
 import type { InferenceParams } from "./types/runtime";
 
 export { defaultInferenceParams, type Preset } from "./presets/preset-policy";
@@ -1332,12 +1330,6 @@ export function ChatSettingsPanel({
             </div>
           </CollapsibleSection>
         ) : null}
-
-        {!isExternalModel ? (
-          <CollapsibleSection label="MCP Servers">
-            <McpServersSection />
-          </CollapsibleSection>
-        ) : null}
       </div>
       </div>
       <Dialog
@@ -1501,74 +1493,6 @@ function AutoHealToolCallsToggle() {
   );
 }
 
-function McpServersSection() {
-  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
-  const setMcpEnabledForChat = useChatRuntimeStore(
-    (s) => s.setMcpEnabledForChat,
-  );
-  const [enabledServerCount, setEnabledServerCount] = useState<number | null>(
-    null,
-  );
-  const [dialogOpen, setDialogOpen] = useState(false);
-  const [refreshTick, setRefreshTick] = useState(0);
-
-  useEffect(() => {
-    let cancelled = false;
-    listMcpServers()
-      .then((rows) => {
-        if (cancelled) return;
-        setEnabledServerCount(rows.filter((row) => row.is_enabled).length);
-      })
-      .catch(() => {
-        if (!cancelled) setEnabledServerCount(0);
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [refreshTick]);
-
-  return (
-    <div className="flex flex-col gap-3 pt-1">
-      <div className="flex items-center justify-between gap-3">
-        <div className="flex min-w-0 items-center gap-1.5">
-          <span className="min-w-0 text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
-            Use MCP Servers
-          </span>
-          <InfoHint>
-            When on, every server marked enabled in the manage dialog is
-            attached to this chat's tool list.
-          </InfoHint>
-        </div>
-        <Switch
-          className="panel-switch"
-          checked={mcpEnabledForChat}
-          onCheckedChange={setMcpEnabledForChat}
-          disabled={enabledServerCount === 0 && !mcpEnabledForChat}
-        />
-      </div>
-      <div className="flex items-center justify-between">
-        <span className="text-[11px] text-muted-foreground">
-          {enabledServerCount === null
-            ? "Loading…"
-            : enabledServerCount === 0
-              ? "No servers configured"
-              : `${enabledServerCount} server${enabledServerCount === 1 ? "" : "s"} enabled`}
-        </span>
-        <Button variant="ghost" size="sm" onClick={() => setDialogOpen(true)}>
-          Manage…
-        </Button>
-      </div>
-      <ChatMcpServersDialog
-        open={dialogOpen}
-        onOpenChange={(next) => {
-          setDialogOpen(next);
-          if (!next) setRefreshTick((tick) => tick + 1);
-        }}
-      />
-    </div>
-  );
-}
-
 function ChatTemplateFields() {
   const defaultTemplate = useChatRuntimeStore((s) => s.defaultChatTemplate);
   const override = useChatRuntimeStore((s) => s.chatTemplateOverride);
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
new file mode 100644
index 0000000000..b98be8bf69
--- /dev/null
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Cancel01Icon,
+  McpServerIcon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+
+import {
+  type McpServerConfig,
+  createMcpServer,
+  listMcpServers,
+  updateMcpServer,
+} from "./api/mcp-servers-api";
+import { ChatMcpServersDialog } from "./chat-mcp-servers-dialog";
+import { useChatRuntimeStore } from "./stores/chat-runtime-store";
+
+type McpPreset = {
+  id: string;
+  displayName: string; // stored row name
+  url: string;
+  label?: string; // dropdown text, if different from displayName
+  hint?: string; // shown when the row is highlighted
+  disablesWebSearch?: boolean; // turn the built-in Search pill off when enabled
+};
+
+// Keyless remote MCP presets (rate-limited free tiers, no API key).
+// Hugging Face runs anonymously; add a token via "Add custom MCP".
+const MCP_PRESETS: readonly McpPreset[] = [
+  {
+    id: "context7",
+    displayName: "Context7",
+    url: "https://mcp.context7.com/mcp",
+    label: "Context7 (Realtime Docs)",
+  },
+  {
+    id: "exa",
+    displayName: "Exa",
+    url: "https://mcp.exa.ai/mcp",
+    label: "Exa (Semantic Search)",
+    hint: "Enabling Exa will disable default search",
+    disablesWebSearch: true,
+  },
+  {
+    id: "huggingface",
+    displayName: "Hugging Face",
+    url: "https://huggingface.co/mcp",
+  },
+] as const;
+
+// mcp_servers has no UNIQUE(url); dedupe by normalized URL so a preset
+// toggle reuses its row instead of creating duplicates.
+function normalizeMcpUrl(url: string): string {
+  return (url || "").trim().toLowerCase().replace(/\/+$/, "");
+}
+
+// Static, so it is not rebuilt on every render.
+const PRESET_URLS = new Set(MCP_PRESETS.map((p) => normalizeMcpUrl(p.url)));
+
+export function McpComposerButton() {
+  const modelLoaded = useChatRuntimeStore(
+    (s) => !!s.params.checkpoint && !s.modelLoading,
+  );
+  const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
+  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  const setMcpEnabledForChat = useChatRuntimeStore(
+    (s) => s.setMcpEnabledForChat,
+  );
+  const setToolsEnabled = useChatRuntimeStore((s) => s.setToolsEnabled);
+
+  const [servers, setServers] = useState<McpServerConfig[]>([]);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
+  const [hintKey, setHintKey] = useState<string | null>(null);
+
+  // mcp_enabled only applies on the local tool-capable send path; grey out otherwise.
+  const usable = modelLoaded && supportsTools;
+
+  // Keep the per-chat flag in step with whether any server is enabled. Reads the
+  // store directly so the callback stays stable (no refetch loop on mount).
+  const reconcileFlag = useCallback(
+    (rows: McpServerConfig[]) => {
+      const anyEnabled = rows.some((s) => s.is_enabled);
+      const current = useChatRuntimeStore.getState().mcpEnabledForChat;
+      if (anyEnabled && !current) setMcpEnabledForChat(true);
+      else if (!anyEnabled && current) setMcpEnabledForChat(false);
+    },
+    [setMcpEnabledForChat],
+  );
+
+  const refresh = useCallback(async () => {
+    try {
+      const rows = await listMcpServers();
+      setServers(rows);
+      reconcileFlag(rows);
+    } catch {
+      // Keep prior state if the list call fails.
+    }
+  }, [reconcileFlag]);
+
+  // Initial load reconciles the pill with already-enabled servers (also on open).
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const enabledUrls = new Set(
+    servers.filter((s) => s.is_enabled).map((s) => normalizeMcpUrl(s.url)),
+  );
+  // Non-preset servers, shown below the presets so they stay toggleable.
+  const customServers = servers.filter(
+    (s) => !PRESET_URLS.has(normalizeMcpUrl(s.url)),
+  );
+  const enabledCount = servers.filter((s) => s.is_enabled).length;
+  const active = mcpEnabledForChat && enabledCount > 0;
+
+  async function toggleServer(args: {
+    url: string;
+    displayName: string;
+    checked: boolean;
+    existing?: McpServerConfig;
+    disablesWebSearch?: boolean;
+  }) {
+    const norm = normalizeMcpUrl(args.url);
+    if (pendingUrl === norm) return; // guard rapid double-clicks
+    setPendingUrl(norm);
+    try {
+      if (args.checked) {
+        // Reuse the already-loaded row, else create one.
+        if (args.existing) {
+          if (!args.existing.is_enabled) {
+            await updateMcpServer(args.existing.id, { isEnabled: true });
+          }
+        } else {
+          await createMcpServer({
+            displayName: args.displayName,
+            url: args.url,
+            isEnabled: true,
+          });
+        }
+        setMcpEnabledForChat(true);
+        // Exa is a search server; turn off the built-in Web Search to avoid overlap.
+        if (args.disablesWebSearch) setToolsEnabled(false);
+      } else if (args.existing) {
+        await updateMcpServer(args.existing.id, { isEnabled: false });
+      }
+      await refresh();
+    } catch (err) {
+      toast.error("Failed to update MCP server", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setPendingUrl(null);
+    }
+  }
+
+  // One dropdown row. Enabled rows get a green underlay and a tick that
+  // becomes an X on hover so a click removes them. A hint shows as a tooltip
+  // driven by row hover; the tooltip anchor is pointer-events-none so the whole
+  // row stays clickable (a Radix TooltipTrigger would swallow the select).
+  const renderRow = (opts: {
+    key: string;
+    label: string;
+    url: string;
+    displayName: string;
+    enabled: boolean;
+    existing?: McpServerConfig;
+    hint?: string;
+    disablesWebSearch?: boolean;
+  }) => (
+    <DropdownMenuItem
+      key={opts.key}
+      disabled={pendingUrl === normalizeMcpUrl(opts.url)}
+      onSelect={(e) => {
+        e.preventDefault();
+        void toggleServer({
+          url: opts.url,
+          displayName: opts.displayName,
+          checked: !opts.enabled,
+          existing: opts.existing,
+          disablesWebSearch: opts.disablesWebSearch,
+        });
+      }}
+      onPointerEnter={opts.hint ? () => setHintKey(opts.key) : undefined}
+      onPointerLeave={
+        opts.hint
+          ? () => setHintKey((k) => (k === opts.key ? null : k))
+          : undefined
+      }
+      className={cn(
+        "group/mcp relative flex items-center justify-between gap-2",
+        opts.enabled &&
+          "bg-emerald-500/10 data-[highlighted]:bg-emerald-500/20",
+      )}
+    >
+      <span className="truncate">{opts.label}</span>
+      {opts.enabled ? (
+        <span className="flex size-4 shrink-0 items-center justify-center text-emerald-600 dark:text-emerald-400">
+          <HugeiconsIcon
+            icon={Tick02Icon}
+            className="size-4 group-data-[highlighted]/mcp:hidden"
+            strokeWidth={2}
+          />
+          <HugeiconsIcon
+            icon={Cancel01Icon}
+            className="hidden size-4 text-foreground group-data-[highlighted]/mcp:block"
+            strokeWidth={2}
+          />
+        </span>
+      ) : null}
+      {opts.hint ? (
+        <Tooltip open={hintKey === opts.key}>
+          <TooltipTrigger asChild={true}>
+            <span
+              aria-hidden={true}
+              className="pointer-events-none absolute inset-y-0 right-0 w-0"
+            />
+          </TooltipTrigger>
+          <TooltipContent side="right">{opts.hint}</TooltipContent>
+        </Tooltip>
+      ) : null}
+    </DropdownMenuItem>
+  );
+
+  return (
+    <>
+      {usable ? (
+        <DropdownMenu
+          open={menuOpen}
+          onOpenChange={(open) => {
+            setMenuOpen(open);
+            if (open) void refresh();
+          }}
+        >
+          <DropdownMenuTrigger asChild={true}>
+            <button
+              type="button"
+              className="composer-pill-btn"
+              data-active={active ? "true" : "false"}
+              aria-label="MCP servers"
+            >
+              <HugeiconsIcon
+                icon={McpServerIcon}
+                className="size-3.5"
+                strokeWidth={2}
+              />
+              <span>MCP</span>
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start" className="w-64">
+            <div className="flex items-center justify-between pr-1">
+              <DropdownMenuLabel>MCP Servers</DropdownMenuLabel>
+              <button
+                type="button"
+                aria-label="Close"
+                onClick={() => setMenuOpen(false)}
+                className="rounded-md p-1 text-muted-foreground hover:bg-accent hover:text-foreground"
+              >
+                <HugeiconsIcon
+                  icon={Cancel01Icon}
+                  className="size-3.5"
+                  strokeWidth={2}
+                />
+              </button>
+            </div>
+            {MCP_PRESETS.map((preset) => {
+              const norm = normalizeMcpUrl(preset.url);
+              return renderRow({
+                key: preset.id,
+                label: preset.label ?? preset.displayName,
+                url: preset.url,
+                displayName: preset.displayName,
+                enabled: enabledUrls.has(norm),
+                existing: servers.find((s) => normalizeMcpUrl(s.url) === norm),
+                hint: preset.hint,
+                disablesWebSearch: preset.disablesWebSearch,
+              });
+            })}
+            {customServers.length > 0 ? <DropdownMenuSeparator /> : null}
+            {customServers.map((server) =>
+              renderRow({
+                key: server.id,
+                label: server.display_name,
+                url: server.url,
+                displayName: server.display_name,
+                enabled: server.is_enabled,
+                existing: server,
+              }),
+            )}
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              onSelect={() => {
+                setMenuOpen(false);
+                setDialogOpen(true);
+              }}
+            >
+              Add custom MCP
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : (
+        <Tooltip>
+          <TooltipTrigger asChild={true}>
+            {/* Not disabled, so the tooltip still fires on hover. */}
+            <button
+              type="button"
+              className="composer-pill-btn cursor-not-allowed opacity-40"
+              data-active="false"
+              aria-disabled={true}
+              aria-label="MCP servers"
+            >
+              <HugeiconsIcon
+                icon={McpServerIcon}
+                className="size-3.5"
+                strokeWidth={2}
+              />
+              <span>MCP</span>
+            </button>
+          </TooltipTrigger>
+          <TooltipContent>
+            MCP works with local tool-capable models
+          </TooltipContent>
+        </Tooltip>
+      )}
+      <ChatMcpServersDialog
+        open={dialogOpen}
+        onOpenChange={(next) => {
+          setDialogOpen(next);
+          // Resync after managing servers.
+          if (!next) void refresh();
+        }}
+        openToCreate={true}
+      />
+    </>
+  );
+}
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 5ee98e230c..b6dbffd5d0 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -43,6 +43,7 @@ import {
   providerTypeSupportsVision,
 } from "./external-providers";
 import { useExternalProvidersStore } from "./stores/external-providers-store";
+import { McpComposerButton } from "./mcp-composer-button";
 import {
   type ReasoningEffort,
   useChatRuntimeStore,
@@ -1272,6 +1273,7 @@ export function SharedComposer({
             <FileTextIcon className="size-3.5" />
             <span>Artifacts</span>
           </button>
+          <McpComposerButton />
           {showWebFetchPill && (
             <button
               type="button"

From 0cbf641a1e36ada93fd7cd35a82b727bfca9fae5 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Mon, 1 Jun 2026 12:19:20 -0300
Subject: [PATCH 059/222] Studio: clearer MCP server validation when stdio is
 disabled (#5928)

Improve the rejection message when an MCP server address is not an http(s) URL. It now points to the expected http(s):// form with an example, and only mentions that local commands are disabled when the value contains whitespace (a reliable command signal), since a lone token may just be a scheme-less URL. Wording is host-scoped rather than desktop-only because self-hosted hosts can opt in via an env var. Backend only, with tests; accepted input is unchanged.
---
 studio/backend/routes/mcp_servers.py          | 22 +++++++++---
 studio/backend/tests/test_mcp_stdio_pr5863.py | 36 ++++++++++++++++++-
 2 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 6c63bc20ca..200c0ed452 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -32,14 +32,21 @@ logger = structlog.get_logger(__name__)
 router = APIRouter()
 
 
+def _looks_like_command(value: str) -> bool:
+    """Whitespace is a one-way signal: a URL can't hold an unencoded space, so a
+    value with whitespace is definitely a command. No whitespace proves nothing
+    (a lone token may be a single-arg command or a scheme-less URL)."""
+    return any(ch.isspace() for ch in value)
+
+
 def _validate_url(url: str) -> str:
     trimmed = (url or "").strip()
     if not trimmed:
         raise HTTPException(status_code = 400, detail = "url must not be empty")
     # When stdio is enabled on this host, a non-HTTP value is a local command.
     # Reuse this field so stdio servers ride the existing CRUD/storage with no
-    # schema change. When stdio is disabled the value falls through to the
-    # http-only validation below, so non-HTTP input is just a bad URL (400).
+    # schema change. A lone token (example.com, /usr/bin/srv) is ambiguous, so we
+    # keep the existing behaviour and treat any non-HTTP value as a command here.
     if stdio_mcp_enabled() and is_stdio(trimmed):
         try:
             parts = parse_stdio_command(trimmed)
@@ -58,10 +65,15 @@ def _validate_url(url: str) -> str:
         return trimmed
     parsed = urlparse(trimmed)
     if parsed.scheme not in ("http", "https"):
-        raise HTTPException(
-            status_code = 400,
-            detail = "url must start with http:// or https://",
+        detail = (
+            "MCP server address must start with http:// or https:// "
+            "(for example https://example.com/mcp)."
         )
+        # Host-scoped wording ("this server"), not "desktop only": self-hosted
+        # hosts can opt in via the env var.
+        if _looks_like_command(trimmed):
+            detail += " Running a local command is not enabled on this server."
+        raise HTTPException(status_code = 400, detail = detail)
     if not parsed.netloc:
         raise HTTPException(status_code = 400, detail = "url is missing a host")
     return trimmed
diff --git a/studio/backend/tests/test_mcp_stdio_pr5863.py b/studio/backend/tests/test_mcp_stdio_pr5863.py
index d9a9510378..f49edcdaae 100644
--- a/studio/backend/tests/test_mcp_stdio_pr5863.py
+++ b/studio/backend/tests/test_mcp_stdio_pr5863.py
@@ -200,12 +200,40 @@ def test_validate_url_gate_off_rejects_stdio(monkeypatch):
     from routes.mcp_servers import _validate_url
 
     assert _validate_url("https://example.com/mcp") == "https://example.com/mcp"
-    for bad in ["npx server", "python -m mod", "ftp://host"]:
+    # urlparse reads "localhost:8000" scheme as "localhost", so it lands here too.
+    for bad in [
+        "npx server",
+        "python -m mod",
+        "ftp://host",
+        "example.com",
+        "localhost:8000",
+        r"C:\node\node.exe server.js",
+    ]:
         with pytest.raises(HTTPException) as exc:
             _validate_url(bad)
         assert exc.value.status_code == 400
 
 
+def test_validate_url_gate_off_message_depends_on_whitespace(monkeypatch):
+    # The message names a command only when the value has whitespace, and never
+    # says "desktop app only" (self-hosted hosts can opt in via the env var).
+    _disable(monkeypatch)
+    from routes.mcp_servers import _validate_url
+
+    with pytest.raises(HTTPException) as exc:
+        _validate_url("npx -y @modelcontextprotocol/server-filesystem /tmp")
+    cmd = exc.value.detail.lower()
+    assert "http://" in cmd and "https://" in cmd
+    assert "local command" in cmd
+    assert "desktop app" not in cmd
+
+    with pytest.raises(HTTPException) as exc:
+        _validate_url("example.com")
+    lone = exc.value.detail.lower()
+    assert "http://" in lone and "https://" in lone
+    assert "local command" not in lone
+
+
 def test_validate_url_gate_on_accepts_stdio(monkeypatch):
     _enable(monkeypatch)
     from routes.mcp_servers import _validate_url
@@ -217,6 +245,12 @@ def test_validate_url_gate_on_accepts_stdio(monkeypatch):
     assert _validate_url("npx server --url https://x/mcp") == (
         "npx server --url https://x/mcp"
     )
+    # A lone token is ambiguous; keep the prior behaviour and accept it as a
+    # command rather than guessing it's a URL (no regression for single binaries).
+    assert (
+        _validate_url("/usr/local/bin/my-mcp-server") == "/usr/local/bin/my-mcp-server"
+    )
+    assert _validate_url("mcp-server-sqlite") == "mcp-server-sqlite"
     # empty / unparseable still rejected
     for bad in ["   ", '"unclosed']:
         with pytest.raises(HTTPException) as exc:

From e94490ecbcfd09d379c6cac584df2e08fd0dc379 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 1 Jun 2026 08:27:34 -0700
Subject: [PATCH 060/222] Bump install.sh / install.ps1 pin to
 unsloth>=2026.5.10 (#5931)

Co-authored-by: Daniel Han <michaelhan2050@gmail.com>
---
 install.ps1 | 10 +++++-----
 install.sh  | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/install.ps1 b/install.ps1
index d3942bf2fc..47c72bcdc1 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1566,7 +1566,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Resolve pydantic WITH deps so pip pins pydantic-core
                 # to the matching version (no-torch-runtime.txt below
@@ -1580,7 +1580,7 @@ shell.Run cmd, 0, False
                 }
             }
         } else {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
         }
         if ($baseInstallExit -ne 0) {
             Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
@@ -1627,7 +1627,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.5.9" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Same pydantic-with-deps trick as the migrated branch.
                 $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython pydantic }
@@ -1639,7 +1639,7 @@ shell.Run cmd, 0, False
                 }
             }
         } elseif ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.5.9" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.5.10" unsloth-zoo }
         } else {
             $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth -- "$PackageName" }
         }
@@ -1667,7 +1667,7 @@ shell.Run cmd, 0, False
         Write-TauriLog "STEP" "Installing unsloth"
         substep "installing unsloth (this may take a few minutes)..."
         if ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.5.9" --torch-backend=auto }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.5.10" --torch-backend=auto }
             if ($baseInstallExit -ne 0) {
                 Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
                 return (Exit-InstallFailure "Failed to install unsloth (exit code $baseInstallExit)" $baseInstallExit)
diff --git a/install.sh b/install.sh
index 89c506bc9d..15755c589f 100755
--- a/install.sh
+++ b/install.sh
@@ -2083,7 +2083,7 @@ if [ "$_MIGRATED" = true ]; then
         # to prevent transitive torch resolution.
         run_install_cmd "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.9" unsloth-zoo
+            "unsloth>=2026.5.10" unsloth-zoo
         # Resolve pydantic WITH deps so pip pins pydantic-core to the
         # matching version (no-torch-runtime.txt below is --no-deps).
         # All transitive deps are torch-free.
@@ -2096,7 +2096,7 @@ if [ "$_MIGRATED" = true ]; then
     else
         run_install_cmd "install unsloth (migrated)" uv pip install --python "$_VENV_PY" \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.9" unsloth-zoo
+            "unsloth>=2026.5.10" unsloth-zoo
     fi
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         substep "overlaying local repo (editable)..."
@@ -2300,7 +2300,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
         run_install_cmd "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --upgrade-package unsloth --upgrade-package unsloth-zoo \
-            "unsloth>=2026.5.9" unsloth-zoo
+            "unsloth>=2026.5.10" unsloth-zoo
         # Same pydantic-with-deps trick as the migrated branch.
         run_install_cmd "install pydantic (with deps for compatible core)" \
             uv pip install --python "$_VENV_PY" pydantic
@@ -2318,7 +2318,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         fi
     elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         run_install_cmd "install unsloth (local)" uv pip install --python "$_VENV_PY" \
-            --upgrade-package unsloth "unsloth>=2026.5.9" unsloth-zoo
+            --upgrade-package unsloth "unsloth>=2026.5.10" unsloth-zoo
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."
@@ -2350,7 +2350,7 @@ else
     tauri_log "STEP" "Installing Unsloth"
     substep "installing unsloth (this may take a few minutes)..."
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
-        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.5.9" --torch-backend=auto
+        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.5.10" --torch-backend=auto
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."

From 21865773a61b37aa5b308376dcbaab2338caad31 Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:49:27 +0100
Subject: [PATCH 061/222] Studio: support connected models in compare mode
 (#5824)

* fix: support connected models in compare mode

* fix: support connected models in compare mode

* studio/frontend: wait for compare prompt append

---------

Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
---
 .../frontend/src/features/chat/chat-page.tsx  |  11 ++
 .../features/chat/chat-providers-dialog.tsx   |  17 +-
 .../src/features/chat/shared-composer.tsx     | 184 ++++++++++++++++--
 3 files changed, 191 insertions(+), 21 deletions(-)

diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 9133cdf102..f727b3dfd3 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -367,6 +367,7 @@ const CompareContent = memo(function CompareContent({
   pairId,
   models,
   loraModels,
+  externalModels,
   onFoldersChange,
   onModelsChange,
   deleteDisabled,
@@ -374,6 +375,7 @@ const CompareContent = memo(function CompareContent({
   pairId: string;
   models: ModelOption[];
   loraModels: LoraModelOption[];
+  externalModels: ExternalModelOption[];
   onFoldersChange?: () => void;
   onModelsChange?: (deletedModel?: DeletedModelRef) => void;
   deleteDisabled?: boolean;
@@ -387,6 +389,7 @@ const CompareContent = memo(function CompareContent({
       pairId={pairId}
       models={models}
       loraModels={loraModels}
+      externalModels={externalModels}
       onFoldersChange={onFoldersChange}
       onModelsChange={onModelsChange}
       deleteDisabled={deleteDisabled}
@@ -557,6 +560,7 @@ const LoraCompareContent = memo(function LoraCompareContent({
 function GeneralCompareHeader({
   models,
   loraModels,
+  externalModels,
   value,
   onValueChange,
   onFoldersChange,
@@ -566,6 +570,7 @@ function GeneralCompareHeader({
 }: {
   models: ModelOption[];
   loraModels: LoraModelOption[];
+  externalModels: ExternalModelOption[];
   value: string;
   onValueChange: (
     id: string,
@@ -586,6 +591,7 @@ function GeneralCompareHeader({
       <ModelSelector
         models={models}
         loraModels={loraModels}
+        externalModels={externalModels}
         value={value}
         onValueChange={onValueChange}
         onFoldersChange={onFoldersChange}
@@ -603,6 +609,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   pairId,
   models,
   loraModels,
+  externalModels,
   onFoldersChange,
   onModelsChange,
   deleteDisabled,
@@ -610,6 +617,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   pairId: string;
   models: ModelOption[];
   loraModels: LoraModelOption[];
+  externalModels: ExternalModelOption[];
   onFoldersChange?: () => void;
   onModelsChange?: (deletedModel?: DeletedModelRef) => void;
   deleteDisabled?: boolean;
@@ -691,6 +699,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
               side="left"
               models={models}
               loraModels={loraModels}
+              externalModels={externalModels}
               value={model1.id}
               onValueChange={(id, meta) =>
                 setModel1({
@@ -716,6 +725,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
               side="right"
               models={models}
               loraModels={loraModels}
+              externalModels={externalModels}
               value={model2.id}
               onValueChange={(id, meta) =>
                 setModel2({
@@ -1824,6 +1834,7 @@ export function ChatPage(): ReactElement {
             pairId={view.pairId}
             models={models}
             loraModels={loraModels}
+            externalModels={externalModels}
             onFoldersChange={refreshLocalModels}
             onModelsChange={refreshModelLists}
             deleteDisabled={modelOperationInProgress}
diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
index 3ffb3a1441..c2e4eaab79 100644
--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
@@ -391,9 +391,22 @@ export function ChatProvidersSettings({
             const updatedAt = Number.isFinite(Date.parse(config.updated_at))
               ? Date.parse(config.updated_at)
               : Date.now();
+            const registryEntry =
+              registryRows.find((entry) => entry.provider_type === uiProviderType) ??
+              registryRows.find((entry) => entry.provider_type === config.provider_type);
+            const defaultModels = pruneProviderModelIds(
+              uiProviderType,
+              registryEntry?.default_models ?? [],
+            );
+            const savedModels = existing?.models ?? [];
+            const savedAvailableModels = existing?.availableModels ?? [];
             const existingModels = pruneProviderModelIds(
               uiProviderType,
-              existing?.models ?? [],
+              savedModels.length > 0 ? savedModels : defaultModels,
+            );
+            const existingAvailableModels = pruneProviderModelIds(
+              uiProviderType,
+              savedAvailableModels.length > 0 ? savedAvailableModels : defaultModels,
             );
             return {
               id: config.id,
@@ -401,7 +414,7 @@ export function ChatProvidersSettings({
               name: config.display_name,
               baseUrl: config.base_url ?? "",
               models: existingModels,
-              availableModels: existing?.availableModels ?? [],
+              availableModels: existingAvailableModels,
               enablePromptCaching: supportsProviderPromptCaching(uiProviderType)
                 ? (existing?.enablePromptCaching ?? true)
                 : undefined,
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index b6dbffd5d0..772b217117 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -52,6 +52,7 @@ import {
   getExternalReasoningCapabilities,
   providerSupportsBuiltinCodeExecution,
   providerSupportsBuiltinImageGeneration,
+  providerSupportsBuiltinWebSearch,
   providerSupportsBuiltinWebFetch,
 } from "./provider-capabilities";
 import {
@@ -76,9 +77,9 @@ export type CompareMessagePart =
 export interface CompareHandle {
   append: (content: CompareMessagePart[]) => void;
   /** Append a user message without triggering generation. */
-  appendMessage: (content: CompareMessagePart[]) => void;
+  appendMessage: (content: CompareMessagePart[]) => Promise<string | null>;
   /** Trigger generation on the current thread (after appendMessage). */
-  startRun: () => void;
+  startRun: (parentId?: string | null) => void;
   cancel: () => void;
   isRunning: () => boolean;
   /** Returns a promise that resolves when the current or next run finishes. */
@@ -87,6 +88,7 @@ export interface CompareHandle {
 
 const IMAGE_ACCEPT = "image/jpeg,image/png,image/webp,image/gif";
 const MAX_IMAGE_SIZE = 20 * 1024 * 1024;
+const COMPARE_APPEND_MESSAGE_TIMEOUT_MS = 10_000;
 
 function isNativeComposing(event: Event) {
   return "isComposing" in event && (event as InputEvent).isComposing === true;
@@ -230,6 +232,7 @@ export function RegisterCompareHandle({
 }): ReactElement | null {
   const handlesRef = useContext(CompareHandlesContext);
   const aui = useAui();
+  const pendingAppendWaitersRef = useRef<Set<() => void>>(new Set());
 
   useEffect(() => {
     if (!handlesRef) {
@@ -242,19 +245,76 @@ export function RegisterCompareHandle({
         aui
           .thread()
           .append({ role: "user", content, createdAt: new Date() } as never),
-      appendMessage: (content) =>
-        aui
-          .thread()
-          .append({
-            role: "user",
-            content,
-            createdAt: new Date(),
-            startRun: false,
-          } as never),
-      startRun: () => {
+      appendMessage: (content) => {
+        const thread = aui.thread();
+        const beforeIds = new Set(
+          thread.getState().messages.map((message) => message.id),
+        );
+        thread.append({
+          role: "user",
+          content,
+          createdAt: new Date(),
+          startRun: false,
+        } as never);
+
+        const findAppendedUserMessageId = () => {
+          const messages = thread.getState().messages;
+          for (let index = messages.length - 1; index >= 0; index -= 1) {
+            const message = messages[index];
+            if (beforeIds.has(message.id) || message.role !== "user") {
+              continue;
+            }
+            return message.id;
+          }
+          return null;
+        };
+
+        const appendedId = findAppendedUserMessageId();
+        if (appendedId) {
+          return Promise.resolve(appendedId);
+        }
+
+        return new Promise<string | null>((resolve) => {
+          const startedAt = Date.now();
+          let settled = false;
+          let timer: number | null = null;
+          let cancel: (() => void) | null = null;
+          const cleanup = () => {
+            if (timer !== null) {
+              window.clearTimeout(timer);
+              timer = null;
+            }
+            if (cancel) {
+              pendingAppendWaitersRef.current.delete(cancel);
+            }
+          };
+          const finish = (messageId: string | null) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            resolve(messageId);
+          };
+          cancel = () => finish(null);
+          const poll = () => {
+            timer = null;
+            const messageId = findAppendedUserMessageId();
+            if (
+              messageId ||
+              Date.now() - startedAt >= COMPARE_APPEND_MESSAGE_TIMEOUT_MS
+            ) {
+              finish(messageId);
+              return;
+            }
+            timer = window.setTimeout(poll, 16);
+          };
+          pendingAppendWaitersRef.current.add(cancel);
+          timer = window.setTimeout(poll, 0);
+        });
+      },
+      startRun: (parentId) => {
         const msgs = aui.thread().getState().messages;
-        const lastId = msgs.length > 0 ? msgs[msgs.length - 1].id : null;
-        aui.thread().startRun({ parentId: lastId });
+        const fallbackId = msgs.length > 0 ? msgs[msgs.length - 1].id : null;
+        aui.thread().startRun({ parentId: parentId ?? fallbackId });
       },
       cancel: () => aui.thread().cancelRun(),
       isRunning: () => aui.thread().getState().isRunning,
@@ -272,6 +332,10 @@ export function RegisterCompareHandle({
         }),
     };
     return () => {
+      for (const cancel of pendingAppendWaitersRef.current) {
+        cancel();
+      }
+      pendingAppendWaitersRef.current.clear();
       delete currentHandles[name];
     };
   }, [handlesRef, name, aui]);
@@ -706,6 +770,8 @@ export function SharedComposer({
         : null;
 
       function modelDisplayName(id: string): string {
+        const external = parseExternalModelId(id);
+        if (external) return external.modelId;
         const parts = id.split("/");
         return parts[parts.length - 1] || id;
       }
@@ -714,6 +780,76 @@ export function SharedComposer({
       async function ensureModelLoaded(
         sel: CompareModelSelection,
       ): Promise<string> {
+        const external = parseExternalModelId(sel.id);
+        if (external) {
+          const externalStore = useExternalProvidersStore.getState();
+          if (!externalStore.connectionsEnabled) {
+            throw new Error(
+              "Connections are disabled. Turn on Enable connections in Settings -> Connections to use hosted models.",
+            );
+          }
+          const provider = externalStore.providers.find(
+            (p) => p.id === external.providerId,
+          );
+          if (!provider) {
+            throw new Error(
+              "Connection not found. Open Settings -> Connections and add it again.",
+            );
+          }
+
+          const reasoningCaps = getExternalReasoningCapabilities(
+            provider.providerType,
+            external.modelId,
+            {
+              isReasoningProvider: provider.isReasoningModel === true,
+              baseUrl: provider.baseUrl ?? null,
+            },
+          );
+          const supportsBuiltinWebSearch = providerSupportsBuiltinWebSearch(
+            provider.providerType,
+            external.modelId,
+            provider.baseUrl,
+          );
+          const supportsBuiltinCodeExecution =
+            providerSupportsBuiltinCodeExecution(
+              provider.providerType,
+              external.modelId,
+              provider.baseUrl,
+            );
+          const supportsBuiltinImageGeneration =
+            providerSupportsBuiltinImageGeneration(
+              provider.providerType,
+              external.modelId,
+              provider.baseUrl,
+            );
+          const supportsBuiltinWebFetch = providerSupportsBuiltinWebFetch(
+            provider.providerType,
+          );
+          const currentStore = useChatRuntimeStore.getState();
+          currentStore.setCheckpoint(sel.id, null);
+          useChatRuntimeStore.setState({
+            activeGgufVariant: null,
+            ggufContextLength: null,
+            ggufMaxContextLength: null,
+            ggufNativeContextLength: null,
+            activeNativePathToken: null,
+            supportsReasoning: reasoningCaps.supportsReasoning,
+            reasoningAlwaysOn: reasoningCaps.reasoningAlwaysOn,
+            reasoningStyle: reasoningCaps.reasoningStyle,
+            supportsReasoningOff: reasoningCaps.supportsReasoningOff,
+            reasoningEffortLevels: reasoningCaps.reasoningEffortLevels,
+            supportsPreserveThinking: false,
+            supportsTools: false,
+            supportsBuiltinWebSearch,
+            supportsBuiltinCodeExecution,
+            supportsBuiltinImageGeneration,
+            supportsBuiltinWebFetch,
+            loadedIsMultimodal:
+              providerTypeSupportsVision(provider.providerType) === true,
+          });
+          return "external";
+        }
+
         const currentStore = useChatRuntimeStore.getState();
         const isAlreadyActive =
           currentStore.params.checkpoint === sel.id &&
@@ -796,9 +932,19 @@ export function SharedComposer({
       const handle1 = handlesRef.current["model1"];
       const handle2 = handlesRef.current["model2"];
 
-      // Show user messages immediately on both sides
-      if (handle1) handle1.appendMessage(content);
-      if (handle2) handle2.appendMessage(content);
+      // Show user messages immediately on both sides and keep the ids
+      // so delayed model loads can start the run from the intended turn.
+      const [parentId1, parentId2] = await Promise.all([
+        handle1 ? handle1.appendMessage(content) : Promise.resolve(null),
+        handle2 ? handle2.appendMessage(content) : Promise.resolve(null),
+      ]);
+      if ((handle1 && !parentId1) || (handle2 && !parentId2)) {
+        toast.error("Compare failed", {
+          description:
+            "The prompt could not be added to both compare panes. Try sending it again.",
+        });
+        return;
+      }
 
       const name1 = model1?.id ? modelDisplayName(model1.id) : "";
       const name2 = model2?.id ? modelDisplayName(model2.id) : "";
@@ -820,7 +966,7 @@ export function SharedComposer({
             duration: Infinity,
           });
           const done = handle1.waitForRunEnd();
-          handle1.startRun();
+          handle1.startRun(parentId1);
           await done;
         }
 
@@ -843,7 +989,7 @@ export function SharedComposer({
             duration: Infinity,
           });
           const done = handle2.waitForRunEnd();
-          handle2.startRun();
+          handle2.startRun(parentId2);
           await done;
         }
 

From e0ff6a1404e92f91d483a0e48e8785700814a97b Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Mon, 1 Jun 2026 19:09:16 +0100
Subject: [PATCH 062/222] Studio: manage chat history with projects (#5725)

* feat: align project sidebar UX with ChatGPT

* feat: align project sidebar UX with ChatGPT

* feat(chat): load stored project list

* feat(chat): add project sidebar workflows

* fix: stabilize project page navigation

* fix: projects chat loading

* fix: show project chat thread

* style: sidebar project spacing and hover clipping

* style: add expandable project chat history and move-to-project submenu

* feat: polish project sidebar

* feat: persist project sandbox paths

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: only create sandbox project workspace dir

* feat: add optional project workspace deletion from delete dialog

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: stabilize chat projects CI failures

* fix: polish project chat navigation

* Studio: manage chat history with projects

Group chats into projects with a dedicated projects page and route.
Sidebar shows recents with per-row actions and a vertical more-vertical
menu, and the sidebar scrollbar stays hidden so rows never shift on
hover. Includes chat settings and composer refinements.

* Studio: projects sidebar and breadcrumb polish

Sidebar:
- Remove the Compare nav item.
- Widen the sidebar to match the projects layout.
- Replace the scroll-gated bottom fade with a static fade pinned above
  the profile box, so it no longer attaches to Recents or lags the
  collapse and expand animation.

Topbar breadcrumb (chat-page):
- On a project landing show "Projects" linking to the projects list.
- Inside a project chat show the project name and chat title, with the
  project name linking back to that specific project page.
- Drop the divider between the model selector and the breadcrumb.

* Studio: make project workspace delete test cross-platform

test_chat_project_delete_files_removes_workspace rooted the project under
pytest tmp_path, which resolves to /private/tmp on macOS. The workspace
delete guard refuses paths under the system denylist by design, so the
test passed on Linux CI but failed on macOS.

Add a workspace_projects_home fixture that keeps tmp_path on Linux and
Windows (CI unchanged) and falls back to a home subdir only when the temp
root is on the platform denylist. Derive the workspace path from the
created project so it tracks the projects home.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: satisfy import-hoist check for new path re-exports

documents_root and project_workspaces_root are re-exported from
utils.paths but only referenced as __all__ string literals, which the
import-hoist safety net does not count as a use. It flagged the two newly
added re-exports as unused imports and failed Source lint.

Name-load both via a module-level _REEXPORTED tuple so the check sees
them used. No behaviour change; consumers still import them from
utils.paths.

* fix: avoid projects empty-state flash

* fix: batch chat search indexing

* Studio: polish chat sidebar, run settings, and search

- Use the native OS scrollbar for the chat sidebar, Run settings panel, and chat search list instead of a custom scrollbar
- Highlight the active run in the sidebar and keep chat search available during training
- Stop the training log view from replaying when navigating back to a run
- Rename the chat settings panel to Run settings and align its toggle icon and position
- Tighten heading and sidebar letter spacing and lighten the Train and Recents labels
- Match the search dialog corner style across light and dark and drop the stray border
- Make the MCP Servers section header plain text instead of a link
- Remove a stray .orig backup file

* studio/frontend: restore Compare entry point in the sidebar

The chat-projects sidebar redesign dropped the Compare nav item and moved
it to thread-sidebar.tsx, which is not imported or rendered anywhere. That
left no way for a user to start a new model comparison (enterCompare only
fired from the guided tour and the training handoff), and broke the
Compare/Recipes/Export UI smoke test that clicks [data-tour="chat-compare"].

Re-add the Compare NavItem to the New Chat / Search group, carrying
data-tour="chat-compare" and the same new-comparison navigation as before.

* studio/frontend: use Unsloth green for the fallback profile avatar

Switch the initials-avatar background from blue to #14b789 so the sidebar
and edit-profile avatar match the Unsloth brand colour.

* studio/frontend: turn project breadcrumb into a project switcher dropdown

* studio/frontend: stop project card kebab clicks from opening the project

* studio/frontend: hide project switcher outside projects

* studio/frontend: stabilize project switcher loading

* style: project switcher alignment

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: shimmyshimmer <107991372+shimmyshimmer@users.noreply.github.com>
Co-authored-by: Unsloth <michaelhan@Michaels-MacBook-Pro.local>
Co-authored-by: Roland Tannous <rolandtannous@gravityq.ai>
Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
---
 studio/backend/core/inference/tools.py        |  42 +-
 studio/backend/routes/chat_history.py         | 117 +++
 studio/backend/routes/inference.py            |  13 +-
 studio/backend/storage/studio_db.py           | 263 ++++++-
 .../tests/test_chat_history_storage.py        |  91 ++-
 studio/backend/utils/paths/__init__.py        |   8 +
 studio/backend/utils/paths/storage_roots.py   |  32 +
 studio/frontend/package-lock.json             |   6 +-
 studio/frontend/package.json                  |   2 +-
 studio/frontend/src/app/router.tsx            |   2 +
 studio/frontend/src/app/routes/__root.tsx     |   9 +
 studio/frontend/src/app/routes/chat.tsx       |   2 +
 studio/frontend/src/app/routes/projects.tsx   |  21 +
 .../frontend/src/components/app-sidebar.tsx   | 709 ++++++++++++++----
 .../src/components/assistant-ui/thread.tsx    |  33 +-
 .../src/components/ui/dropdown-menu.tsx       |   8 +-
 studio/frontend/src/components/ui/sidebar.tsx |   4 +-
 .../frontend/src/components/ui/terminal.tsx   |  34 +-
 .../src/features/chat/api/chat-adapter.ts     |  61 +-
 .../src/features/chat/api/chat-api.ts         |  78 +-
 .../frontend/src/features/chat/chat-page.tsx  | 460 +++++++++++-
 .../src/features/chat/chat-settings-sheet.tsx | 101 ++-
 .../chat/components/chat-search-dialog.tsx    |  20 +-
 .../chat/components/project-switcher.tsx      | 120 +++
 .../features/chat/hooks/use-chat-projects.ts  |  97 +++
 .../chat/hooks/use-chat-search-index.ts       |  38 +-
 .../chat/hooks/use-chat-sidebar-items.ts      |  23 +-
 studio/frontend/src/features/chat/index.ts    |   9 +
 .../src/features/chat/projects-page.tsx       | 401 ++++++++++
 .../src/features/chat/runtime-provider.tsx    |  95 ++-
 .../src/features/chat/shared-composer.tsx     |   8 +-
 .../chat/stores/chat-runtime-store.ts         |   4 +
 .../src/features/chat/thread-sidebar.tsx      |   6 +-
 studio/frontend/src/features/chat/types.ts    |  25 +-
 .../chat/utils/chat-history-storage.ts        |  83 +-
 .../features/profile/utils/avatar-initials.ts |   4 +-
 .../src/features/studio/studio-page.tsx       |  11 +
 .../studio/training-start-overlay.tsx         |  20 +-
 .../training/stores/training-runtime-store.ts |   4 +
 .../src/features/training/types/runtime.ts    |   4 +
 studio/frontend/src/index.css                 | 154 ++--
 41 files changed, 2865 insertions(+), 357 deletions(-)
 create mode 100644 studio/frontend/src/app/routes/projects.tsx
 create mode 100644 studio/frontend/src/features/chat/components/project-switcher.tsx
 create mode 100644 studio/frontend/src/features/chat/hooks/use-chat-projects.ts
 create mode 100644 studio/frontend/src/features/chat/projects-page.tsx

diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index eecb84ca27..0f5dbfa237 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -421,6 +421,35 @@ _workdirs: dict[str, str] = {}
 
 # Non-matching session_ids collapse to ``_invalid`` to block cross-session escapes.
 _SESSION_ID_RE = re.compile(r"\A[A-Za-z0-9_\-]{1,64}\Z")
+_PROJECT_SESSION_PREFIX = "project-"
+
+
+def _get_project_workdir(session_id: str) -> str | None:
+    if not session_id.startswith(_PROJECT_SESSION_PREFIX):
+        return None
+    project_id = session_id[len(_PROJECT_SESSION_PREFIX) :]
+    if not project_id or not _SESSION_ID_RE.match(project_id):
+        return None
+    try:
+        from storage.studio_db import ensure_chat_project_workspace
+
+        project = ensure_chat_project_workspace(project_id)
+    except Exception:
+        logger.warning(
+            "Failed to resolve project sandbox for %s", session_id, exc_info = True
+        )
+        return None
+    if not project:
+        return None
+    root_path = project.get("rootPath")
+    sandbox_path = project.get("sandboxPath")
+    if not root_path or not sandbox_path:
+        return None
+    root_real = os.path.realpath(root_path)
+    sandbox_real = os.path.realpath(sandbox_path)
+    if sandbox_real != root_real and not sandbox_real.startswith(root_real + os.sep):
+        return None
+    return sandbox_real
 
 
 def _get_workdir(session_id: str | None = None) -> str:
@@ -430,7 +459,14 @@ def _get_workdir(session_id: str | None = None) -> str:
     if key not in _workdirs or not os.path.isdir(_workdirs[key]):
         home = os.path.expanduser("~")
         sandbox_root = os.path.join(home, "studio_sandbox")
-        if session_id and _SESSION_ID_RE.match(session_id):
+        project_workdir = (
+            _get_project_workdir(session_id)
+            if session_id and _SESSION_ID_RE.match(session_id)
+            else None
+        )
+        if project_workdir:
+            workdir = project_workdir
+        elif session_id and _SESSION_ID_RE.match(session_id):
             workdir = os.path.join(sandbox_root, session_id)
             if not os.path.realpath(workdir).startswith(
                 os.path.realpath(sandbox_root) + os.sep
@@ -453,6 +489,10 @@ def _get_workdir(session_id: str | None = None) -> str:
     return _workdirs[key]
 
 
+def get_sandbox_workdir(session_id: str | None = None) -> str:
+    return _get_workdir(session_id)
+
+
 WEB_SEARCH_TOOL = {
     "type": "function",
     "function": {
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index e64e5ca5c7..8e24096233 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -17,15 +17,21 @@ from storage.studio_db import (
     clear_chat_history,
     count_chat_threads,
     delete_chat_threads,
+    delete_chat_project,
+    ensure_chat_project_workspace,
+    get_chat_project,
     get_chat_thread,
     get_chat_message,
+    list_chat_projects,
     list_chat_legacy_imports,
     list_chat_settings,
     list_chat_messages,
     list_chat_messages_for_threads,
     list_chat_threads,
     sync_chat_messages,
+    update_chat_project,
     update_chat_thread,
+    upsert_chat_project,
     upsert_chat_legacy_imports,
     upsert_chat_message,
     upsert_chat_settings_merge,
@@ -41,6 +47,7 @@ class ChatThread(BaseModel):
     modelType: Literal["base", "lora", "model1", "model2"]
     modelId: str = ""
     pairId: Optional[str] = None
+    projectId: Optional[str] = None
     archived: bool = False
     createdAt: int
     openaiCodeExecContainerId: Optional[str] = None
@@ -52,6 +59,7 @@ class ChatThreadPatch(BaseModel):
     modelType: Optional[Literal["base", "lora", "model1", "model2"]] = None
     modelId: Optional[str] = None
     pairId: Optional[str] = None
+    projectId: Optional[str] = None
     archived: Optional[bool] = None
     createdAt: Optional[int] = None
     openaiCodeExecContainerId: Optional[str] = None
@@ -69,10 +77,33 @@ class ChatMessage(BaseModel):
     createdAt: int
 
 
+class ChatProject(BaseModel):
+    id: str
+    name: str
+    instructions: str = ""
+    rootPath: Optional[str] = None
+    sandboxPath: Optional[str] = None
+    archived: bool = False
+    createdAt: int
+    updatedAt: int
+
+
+class ChatProjectPatch(BaseModel):
+    name: Optional[str] = None
+    instructions: Optional[str] = None
+    archived: Optional[bool] = None
+    createdAt: Optional[int] = None
+    updatedAt: Optional[int] = None
+
+
 class ChatThreadListResponse(BaseModel):
     threads: list[ChatThread]
 
 
+class ChatProjectListResponse(BaseModel):
+    projects: list[ChatProject]
+
+
 class ChatMessageListResponse(BaseModel):
     messages: list[ChatMessage]
 
@@ -94,6 +125,7 @@ class ChatExportResponse(BaseModel):
     exportedAt: str
     version: int
     threadCount: int
+    projects: list[ChatProject] = Field(default_factory = list)
     threads: list[ChatThread]
     messages: list[ChatMessage]
 
@@ -177,12 +209,14 @@ class ChatImportLedgerRecordResponse(BaseModel):
 async def list_threads(
     model_type: Optional[str] = Query(None),
     pair_id: Optional[str] = Query(None),
+    project_id: Optional[str] = Query(None),
     include_archived: bool = Query(True),
     current_subject: str = Depends(get_current_subject),
 ):
     threads = list_chat_threads(
         model_type = model_type,
         pair_id = pair_id,
+        project_id = project_id,
         include_archived = include_archived,
     )
     return ChatThreadListResponse(threads = [ChatThread(**t) for t in threads])
@@ -193,6 +227,11 @@ async def save_thread(
     payload: ChatThread,
     current_subject: str = Depends(get_current_subject),
 ):
+    if payload.projectId and get_chat_project(payload.projectId) is None:
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Project {payload.projectId} not found",
+        )
     return ChatThread(**upsert_chat_thread(payload.model_dump()))
 
 
@@ -217,6 +256,11 @@ async def patch_thread(
     for field in ("title", "modelType", "modelId", "archived", "createdAt"):
         if field in patch and patch[field] is None:
             raise HTTPException(status_code = 400, detail = f"{field} cannot be null")
+    if patch.get("projectId") and get_chat_project(patch["projectId"]) is None:
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Project {patch['projectId']} not found",
+        )
     thread = update_chat_thread(
         thread_id,
         patch,
@@ -235,6 +279,77 @@ async def delete_threads(
     return {"status": "deleted"}
 
 
+@router.get("/projects", response_model = ChatProjectListResponse)
+async def list_projects(
+    include_archived: bool = Query(False),
+    current_subject: str = Depends(get_current_subject),
+):
+    return ChatProjectListResponse(
+        projects = [
+            ChatProject(**(ensure_chat_project_workspace(project["id"]) or project))
+            for project in list_chat_projects(include_archived = include_archived)
+        ]
+    )
+
+
+@router.post("/projects", response_model = ChatProject)
+async def save_project(
+    payload: ChatProject,
+    current_subject: str = Depends(get_current_subject),
+):
+    return ChatProject(**upsert_chat_project(payload.model_dump()))
+
+
+@router.get("/projects/{project_id}", response_model = ChatProject)
+async def get_project(
+    project_id: str,
+    current_subject: str = Depends(get_current_subject),
+):
+    project = ensure_chat_project_workspace(project_id)
+    if project is None:
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Project {project_id} not found",
+        )
+    return ChatProject(**project)
+
+
+@router.patch("/projects/{project_id}", response_model = ChatProject)
+async def patch_project(
+    project_id: str,
+    payload: ChatProjectPatch,
+    current_subject: str = Depends(get_current_subject),
+):
+    patch = payload.model_dump(exclude_unset = True)
+    for field in ("name", "archived", "createdAt", "updatedAt"):
+        if field in patch and patch[field] is None:
+            raise HTTPException(status_code = 400, detail = f"{field} cannot be null")
+    project = update_chat_project(project_id, patch)
+    if project is not None:
+        project = ensure_chat_project_workspace(project_id)
+    if project is None:
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Project {project_id} not found",
+        )
+    return ChatProject(**project)
+
+
+@router.delete("/projects/{project_id}", response_model = ChatProject)
+async def delete_project(
+    project_id: str,
+    delete_files: bool = Query(False),
+    current_subject: str = Depends(get_current_subject),
+):
+    project = delete_chat_project(project_id, delete_files = delete_files)
+    if project is None:
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Project {project_id} not found",
+        )
+    return ChatProject(**project)
+
+
 @router.get("/threads/{thread_id}/messages", response_model = ChatMessageListResponse)
 async def get_thread_messages(
     thread_id: str,
@@ -389,11 +504,13 @@ async def export_history(current_subject: str = Depends(get_current_subject)):
     from datetime import datetime, timezone
 
     threads = list_chat_threads(include_archived = True)
+    projects = list_chat_projects(include_archived = True)
     messages = list_chat_messages_for_threads([thread["id"] for thread in threads])
     return ChatExportResponse(
         exportedAt = datetime.now(timezone.utc).isoformat(),
         version = 1,
         threadCount = len(threads),
+        projects = [ChatProject(**project) for project in projects],
         threads = [ChatThread(**thread) for thread in threads],
         messages = [ChatMessage(**message) for message in messages],
     )
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index fbe8cf6a92..2964a0801f 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3837,16 +3837,11 @@ async def serve_sandbox_file(
         )
 
     # ── Path containment check ──────────────────────────────────
-    home = os.path.expanduser("~")
-    sandbox_root = os.path.realpath(os.path.join(home, "studio_sandbox"))
-    safe_session = os.path.basename(session_id.replace("..", ""))
-    if not safe_session:
-        raise HTTPException(status_code = 404, detail = "Not found")
+    from core.inference.tools import get_sandbox_workdir
 
-    file_path = os.path.realpath(
-        os.path.join(sandbox_root, safe_session, safe_filename)
-    )
-    if not file_path.startswith(sandbox_root + os.sep):
+    sandbox_dir = os.path.realpath(get_sandbox_workdir(session_id))
+    file_path = os.path.realpath(os.path.join(sandbox_dir, safe_filename))
+    if file_path != sandbox_dir and not file_path.startswith(sandbox_dir + os.sep):
         raise HTTPException(
             status_code = status.HTTP_403_FORBIDDEN,
             detail = "Access denied",
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index de89b6cbd2..0887eb9ceb 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -14,15 +14,18 @@ import json
 import logging
 import os
 import platform
+import re
+import shutil
 import sqlite3
 import threading
 from datetime import datetime, timezone
+from pathlib import Path
 
 logger = logging.getLogger(__name__)
 from typing import Any, Iterable, Optional
 
 
-from utils.paths import studio_db_path, ensure_dir
+from utils.paths import project_workspaces_root, studio_db_path, ensure_dir
 
 
 def _denied_path_prefixes() -> list[str]:
@@ -55,6 +58,77 @@ def _denied_path_prefixes() -> list[str]:
 _schema_lock = threading.Lock()
 _schema_ready = False
 _SQLITE_IN_CHUNK_SIZE = 900
+_PROJECT_WORKSPACE_SUBDIRS = ("sandbox",)
+
+
+def _project_slug(name: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", name.strip()).strip(".-_")
+    return slug[:48] or "project"
+
+
+def _default_project_root(project: dict) -> str:
+    project_id = str(project["id"])
+    suffix = re.sub(r"[^A-Za-z0-9_-]+", "-", project_id)[:8].strip("-_") or "project"
+    folder_name = f"{_project_slug(str(project.get('name') or 'Project'))}-{suffix}"
+    return str(project_workspaces_root() / folder_name)
+
+
+def _ensure_project_workspace(root_path: str) -> str:
+    root = Path(root_path).expanduser()
+    root_resolved = ensure_dir(root).resolve()
+    for subdir in _PROJECT_WORKSPACE_SUBDIRS:
+        ensure_dir(root_resolved / subdir)
+    return str(root_resolved)
+
+
+def _delete_project_workspace(project: dict) -> None:
+    root_path = project.get("rootPath")
+    if not root_path:
+        return
+    root = Path(root_path).expanduser()
+    try:
+        root_resolved = root.resolve(strict = False)
+    except (OSError, RuntimeError, ValueError):
+        logger.warning(
+            "Skipping project workspace delete for invalid path %r", root_path
+        )
+        return
+
+    project_id = str(project["id"])
+    suffix = re.sub(r"[^A-Za-z0-9_-]+", "-", project_id)[:8].strip("-_") or "project"
+    if not root_resolved.name.endswith(f"-{suffix}"):
+        logger.warning(
+            "Skipping project workspace delete for unexpected project path %s",
+            root_resolved,
+        )
+        return
+    if root_resolved.parent == root_resolved or root_resolved == Path.home().resolve():
+        logger.warning(
+            "Skipping project workspace delete for unsafe project path %s",
+            root_resolved,
+        )
+        return
+    check = (
+        os.path.normcase(str(root_resolved))
+        if platform.system() == "Windows"
+        else str(root_resolved)
+    )
+    for prefix in _denied_path_prefixes():
+        if check == prefix or check.startswith(prefix + os.sep):
+            logger.warning(
+                "Skipping project workspace delete under denied path %s",
+                root_resolved,
+            )
+            return
+    if not root_resolved.exists():
+        return
+    if root_resolved.is_symlink() or not root_resolved.is_dir():
+        logger.warning(
+            "Skipping project workspace delete for non-directory path %s",
+            root_resolved,
+        )
+        return
+    shutil.rmtree(root_resolved)
 
 
 def _ensure_schema(conn: sqlite3.Connection) -> None:
@@ -119,6 +193,27 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS chat_projects (
+            id TEXT NOT NULL PRIMARY KEY,
+            name TEXT NOT NULL,
+            instructions TEXT,
+            root_path TEXT,
+            archived INTEGER NOT NULL DEFAULT 0,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+    chat_project_cols = {
+        row[1] for row in conn.execute("PRAGMA table_info(chat_projects)").fetchall()
+    }
+    if "root_path" not in chat_project_cols:
+        conn.execute("ALTER TABLE chat_projects ADD COLUMN root_path TEXT")
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_chat_projects_archived_updated_at ON chat_projects(archived, updated_at)"
+    )
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS chat_threads (
@@ -127,16 +222,20 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
             model_type TEXT NOT NULL,
             model_id TEXT,
             pair_id TEXT,
+            project_id TEXT,
             archived INTEGER NOT NULL DEFAULT 0,
             created_at INTEGER NOT NULL,
             openai_code_exec_container_id TEXT,
-            anthropic_code_exec_container_id TEXT
+            anthropic_code_exec_container_id TEXT,
+            FOREIGN KEY(project_id) REFERENCES chat_projects(id) ON DELETE CASCADE
         )
         """
     )
     chat_thread_cols = {
         row[1] for row in conn.execute("PRAGMA table_info(chat_threads)").fetchall()
     }
+    if "project_id" not in chat_thread_cols:
+        conn.execute("ALTER TABLE chat_threads ADD COLUMN project_id TEXT")
     if "openai_code_exec_container_id" not in chat_thread_cols:
         conn.execute(
             "ALTER TABLE chat_threads ADD COLUMN openai_code_exec_container_id TEXT"
@@ -165,6 +264,9 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_chat_threads_pair_id ON chat_threads(pair_id)"
     )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_chat_threads_project_id ON chat_threads(project_id)"
+    )
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_chat_messages_thread_id_created_at ON chat_messages(thread_id, created_at)"
     )
@@ -681,6 +783,7 @@ def _chat_thread_from_row(row: sqlite3.Row) -> dict:
         "modelType": data["model_type"],
         "modelId": data.get("model_id") or "",
         "pairId": data.get("pair_id") or None,
+        "projectId": data.get("project_id") or None,
         "archived": bool(data["archived"]),
         "createdAt": data["created_at"],
         "openaiCodeExecContainerId": data.get("openai_code_exec_container_id"),
@@ -688,6 +791,21 @@ def _chat_thread_from_row(row: sqlite3.Row) -> dict:
     }
 
 
+def _chat_project_from_row(row: sqlite3.Row) -> dict:
+    data = dict(row)
+    root_path = data.get("root_path")
+    return {
+        "id": data["id"],
+        "name": data["name"],
+        "instructions": data.get("instructions") or "",
+        "rootPath": root_path or None,
+        "sandboxPath": os.path.join(root_path, "sandbox") if root_path else None,
+        "archived": bool(data["archived"]),
+        "createdAt": data["created_at"],
+        "updatedAt": data["updated_at"],
+    }
+
+
 def _chat_message_from_row(row: sqlite3.Row) -> dict:
     data = dict(row)
     message = {
@@ -713,13 +831,14 @@ def upsert_chat_thread(thread: dict) -> dict:
         conn.execute(
             """
             INSERT INTO chat_threads
-                (id, title, model_type, model_id, pair_id, archived, created_at, openai_code_exec_container_id, anthropic_code_exec_container_id)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                (id, title, model_type, model_id, pair_id, project_id, archived, created_at, openai_code_exec_container_id, anthropic_code_exec_container_id)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             ON CONFLICT(id) DO UPDATE SET
                 title = excluded.title,
                 model_type = excluded.model_type,
                 model_id = excluded.model_id,
                 pair_id = excluded.pair_id,
+                project_id = excluded.project_id,
                 archived = excluded.archived,
                 created_at = excluded.created_at,
                 openai_code_exec_container_id = excluded.openai_code_exec_container_id,
@@ -731,6 +850,7 @@ def upsert_chat_thread(thread: dict) -> dict:
                 thread["modelType"],
                 thread.get("modelId") or "",
                 thread.get("pairId"),
+                thread.get("projectId"),
                 1 if thread.get("archived") else 0,
                 int(thread["createdAt"]),
                 thread.get("openaiCodeExecContainerId"),
@@ -749,6 +869,7 @@ def update_chat_thread(id: str, patch: dict) -> Optional[dict]:
         "modelType": ("model_type", patch.get("modelType")),
         "modelId": ("model_id", patch.get("modelId")),
         "pairId": ("pair_id", patch.get("pairId")),
+        "projectId": ("project_id", patch.get("projectId")),
         "archived": ("archived", 1 if patch.get("archived") else 0),
         "createdAt": ("created_at", patch.get("createdAt")),
         "openaiCodeExecContainerId": (
@@ -794,6 +915,7 @@ def get_chat_thread(id: str) -> Optional[dict]:
 def list_chat_threads(
     model_type: str | None = None,
     pair_id: str | None = None,
+    project_id: str | None = None,
     include_archived: bool = True,
 ) -> list[dict]:
     clauses = []
@@ -804,6 +926,9 @@ def list_chat_threads(
     if pair_id is not None:
         clauses.append("pair_id = ?")
         values.append(pair_id)
+    if project_id is not None:
+        clauses.append("project_id = ?")
+        values.append(project_id)
     if not include_archived:
         clauses.append("archived = 0")
     where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
@@ -846,6 +971,136 @@ def count_chat_threads() -> int:
         conn.close()
 
 
+def upsert_chat_project(project: dict) -> dict:
+    existing = get_chat_project(project["id"])
+    root_path = existing.get("rootPath") if existing else None
+    if not root_path:
+        root_path = _default_project_root(project)
+    root_path = _ensure_project_workspace(root_path)
+    conn = get_connection()
+    try:
+        conn.execute(
+            """
+            INSERT INTO chat_projects
+                (id, name, instructions, root_path, archived, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                name = excluded.name,
+                instructions = excluded.instructions,
+                root_path = COALESCE(chat_projects.root_path, excluded.root_path),
+                archived = excluded.archived,
+                created_at = excluded.created_at,
+                updated_at = excluded.updated_at
+            """,
+            (
+                project["id"],
+                project["name"],
+                project.get("instructions") or "",
+                root_path,
+                1 if project.get("archived") else 0,
+                int(project["createdAt"]),
+                int(project["updatedAt"]),
+            ),
+        )
+        conn.commit()
+        return get_chat_project(project["id"]) or project
+    finally:
+        conn.close()
+
+
+def update_chat_project(id: str, patch: dict) -> Optional[dict]:
+    allowed = {
+        "name": ("name", patch.get("name")),
+        "instructions": ("instructions", patch.get("instructions")),
+        "archived": ("archived", 1 if patch.get("archived") else 0),
+        "createdAt": ("created_at", patch.get("createdAt")),
+        "updatedAt": ("updated_at", patch.get("updatedAt")),
+    }
+    assignments = []
+    values = []
+    for key, (column, value) in allowed.items():
+        if key in patch:
+            assignments.append(f"{column} = ?")
+            values.append(value)
+    if not assignments:
+        return get_chat_project(id)
+
+    conn = get_connection()
+    try:
+        conn.execute(
+            f"UPDATE chat_projects SET {', '.join(assignments)} WHERE id = ?",
+            (*values, id),
+        )
+        conn.commit()
+        row = conn.execute("SELECT * FROM chat_projects WHERE id = ?", (id,)).fetchone()
+        return _chat_project_from_row(row) if row is not None else None
+    finally:
+        conn.close()
+
+
+def ensure_chat_project_workspace(id: str) -> Optional[dict]:
+    project = get_chat_project(id)
+    if project is None:
+        return None
+    root_path = project.get("rootPath") or _default_project_root(project)
+    root_path = _ensure_project_workspace(root_path)
+    if project.get("rootPath") == root_path:
+        return project
+    conn = get_connection()
+    try:
+        conn.execute(
+            "UPDATE chat_projects SET root_path = ? WHERE id = ?",
+            (root_path, id),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    return get_chat_project(id)
+
+
+def get_chat_project(id: str) -> Optional[dict]:
+    conn = get_connection()
+    try:
+        row = conn.execute("SELECT * FROM chat_projects WHERE id = ?", (id,)).fetchone()
+        return _chat_project_from_row(row) if row is not None else None
+    finally:
+        conn.close()
+
+
+def list_chat_projects(include_archived: bool = False) -> list[dict]:
+    conn = get_connection()
+    try:
+        where = "" if include_archived else "WHERE archived = 0"
+        rows = conn.execute(
+            f"SELECT * FROM chat_projects {where} ORDER BY updated_at DESC"
+        ).fetchall()
+        return [_chat_project_from_row(row) for row in rows]
+    finally:
+        conn.close()
+
+
+def delete_chat_project(id: str, delete_files: bool = False) -> Optional[dict]:
+    conn = get_connection()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        row = conn.execute("SELECT * FROM chat_projects WHERE id = ?", (id,)).fetchone()
+        if row is None:
+            conn.rollback()
+            return None
+        project = _chat_project_from_row(row)
+        conn.execute("DELETE FROM chat_threads WHERE project_id = ?", (id,))
+        conn.execute("DELETE FROM chat_projects WHERE id = ?", (id,))
+        conn.commit()
+        if delete_files:
+            _delete_project_workspace(project)
+        return project
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
 class ChatMessageConflictError(RuntimeError):
     """Raised when a chat message id already belongs to another thread."""
 
diff --git a/studio/backend/tests/test_chat_history_storage.py b/studio/backend/tests/test_chat_history_storage.py
index 123dbf1b96..e88cac3276 100644
--- a/studio/backend/tests/test_chat_history_storage.py
+++ b/studio/backend/tests/test_chat_history_storage.py
@@ -1,18 +1,49 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
+import os
+import platform
+import shutil
 import threading
+import uuid
+from pathlib import Path
 
 import pytest
 
 from storage import studio_db
 
 
-def _reset_studio_db(tmp_path, monkeypatch):
+def _reset_studio_db(tmp_path, monkeypatch, projects_home = None):
     monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setenv(
+        "UNSLOTH_STUDIO_PROJECTS_HOME",
+        str(projects_home if projects_home is not None else tmp_path / "Projects"),
+    )
     monkeypatch.setattr(studio_db, "_schema_ready", False)
 
 
+@pytest.fixture
+def workspace_projects_home(tmp_path):
+    """Projects root outside the platform delete denylist.
+
+    tmp_path resolves under /private/tmp on macOS, which the workspace
+    delete guard refuses by design. Linux/Windows tmp is not denied and is
+    used as-is; only the denied case falls back to a home subdir.
+    """
+    candidate = tmp_path / "Projects"
+    resolved = str(candidate.resolve())
+    check = os.path.normcase(resolved) if platform.system() == "Windows" else resolved
+    denied = studio_db._denied_path_prefixes()
+    if any(check == p or check.startswith(p + os.sep) for p in denied):
+        candidate = Path.home() / ".unsloth-studio-tests" / uuid.uuid4().hex
+    candidate.mkdir(parents = True, exist_ok = True)
+    try:
+        yield candidate
+    finally:
+        if ".unsloth-studio-tests" in candidate.parts:
+            shutil.rmtree(candidate, ignore_errors = True)
+
+
 def _thread(thread_id: str = "thread-1") -> dict:
     return {
         "id": thread_id,
@@ -41,6 +72,17 @@ def _message(
     }
 
 
+def _project(project_id: str = "project-1") -> dict:
+    return {
+        "id": project_id,
+        "name": "Research",
+        "instructions": "Use terse answers.",
+        "archived": False,
+        "createdAt": 1_700_000_000_000,
+        "updatedAt": 1_700_000_000_000,
+    }
+
+
 def test_sync_chat_messages_upserts_without_pruning(tmp_path, monkeypatch):
     _reset_studio_db(tmp_path, monkeypatch)
     studio_db.upsert_chat_thread(_thread())
@@ -63,6 +105,53 @@ def test_sync_chat_messages_upserts_without_pruning(tmp_path, monkeypatch):
     assert by_id["msg-2"]["content"] == [{"type": "text", "text": "updated text"}]
 
 
+def test_chat_projects_delete_cascades_threads_and_messages(
+    tmp_path,
+    monkeypatch,
+):
+    _reset_studio_db(tmp_path, monkeypatch)
+    project = studio_db.upsert_chat_project(_project())
+    assert project["rootPath"].startswith(str(tmp_path / "Projects"))
+    assert (tmp_path / "Projects" / "Research-project").exists()
+    assert (tmp_path / "Projects" / "Research-project" / "sandbox").is_dir()
+    assert not (tmp_path / "Projects" / "Research-project" / "chats").exists()
+    assert not (tmp_path / "Projects" / "Research-project" / "files").exists()
+    assert not (tmp_path / "Projects" / "Research-project" / "exports").exists()
+    studio_db.upsert_chat_thread({**_thread(), "projectId": "project-1"})
+    studio_db.upsert_chat_message(_message("msg-1", 1, "delete with project"))
+
+    [thread] = studio_db.list_chat_threads(project_id = "project-1")
+    assert thread["projectId"] == "project-1"
+
+    deleted = studio_db.delete_chat_project("project-1")
+
+    assert deleted is not None
+    assert deleted["id"] == "project-1"
+    assert studio_db.get_chat_project("project-1") is None
+    assert studio_db.list_chat_threads(project_id = "project-1") == []
+    assert studio_db.get_chat_thread("thread-1") is None
+    assert studio_db.list_chat_messages("thread-1") == []
+    assert (tmp_path / "Projects" / "Research-project").exists()
+
+
+def test_chat_project_delete_files_removes_workspace(
+    tmp_path, monkeypatch, workspace_projects_home
+):
+    _reset_studio_db(tmp_path, monkeypatch, projects_home = workspace_projects_home)
+    project = studio_db.upsert_chat_project(_project())
+    # Derive root from the created project so it tracks the projects home.
+    root = Path(project["rootPath"])
+    marker = root / "sandbox" / "marker.txt"
+    marker.write_text("created by code execution", encoding = "utf-8")
+
+    deleted = studio_db.delete_chat_project(project["id"], delete_files = True)
+
+    assert deleted is not None
+    assert deleted["rootPath"] == project["rootPath"]
+    assert not root.exists()
+    assert studio_db.get_chat_project(project["id"]) is None
+
+
 def test_sync_chat_messages_prunes_when_requested(tmp_path, monkeypatch):
     _reset_studio_db(tmp_path, monkeypatch)
     studio_db.upsert_chat_thread(_thread())
diff --git a/studio/backend/utils/paths/__init__.py b/studio/backend/utils/paths/__init__.py
index 92191dccdd..eba7a9de6c 100644
--- a/studio/backend/utils/paths/__init__.py
+++ b/studio/backend/utils/paths/__init__.py
@@ -25,6 +25,8 @@ from .storage_roots import (
     auth_root,
     auth_db_path,
     studio_db_path,
+    documents_root,
+    project_workspaces_root,
     tmp_root,
     seed_uploads_root,
     unstructured_seed_cache_root,
@@ -44,6 +46,10 @@ from .storage_roots import (
     resolve_dataset_path,
 )
 
+# Re-export shim: name-load the project-path helpers so the import-hoist
+# safety net sees them used here, not just listed in __all__ as strings.
+_REEXPORTED = (documents_root, project_workspaces_root)
+
 __all__ = [
     "normalize_path",
     "is_local_path",
@@ -62,6 +68,8 @@ __all__ = [
     "auth_root",
     "auth_db_path",
     "studio_db_path",
+    "documents_root",
+    "project_workspaces_root",
     "tmp_root",
     "seed_uploads_root",
     "unstructured_seed_cache_root",
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index 763d18bf3e..6319452ed2 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -96,6 +96,38 @@ def studio_db_path() -> Path:
     return studio_root() / "studio.db"
 
 
+def _xdg_user_dir(key: str) -> Path | None:
+    config = Path.home() / ".config" / "user-dirs.dirs"
+    try:
+        lines = config.read_text(encoding = "utf-8").splitlines()
+    except OSError:
+        return None
+    prefix = f"{key}="
+    for line in lines:
+        line = line.strip()
+        if not line.startswith(prefix):
+            continue
+        value = line[len(prefix) :].strip().strip('"')
+        if not value:
+            return None
+        return Path(value.replace("$HOME", str(Path.home()))).expanduser()
+    return None
+
+
+def documents_root() -> Path:
+    override = (os.environ.get("UNSLOTH_STUDIO_DOCUMENTS_HOME") or "").strip()
+    if override:
+        return Path(override).expanduser()
+    return _xdg_user_dir("XDG_DOCUMENTS_DIR") or (Path.home() / "Documents")
+
+
+def project_workspaces_root() -> Path:
+    override = (os.environ.get("UNSLOTH_STUDIO_PROJECTS_HOME") or "").strip()
+    if override:
+        return Path(override).expanduser()
+    return documents_root() / "Unsloth Studio" / "Projects"
+
+
 def tmp_root() -> Path:
     return Path(tempfile.gettempdir()) / "unsloth-studio"
 
diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index 80f5d0a701..4afee8a916 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -13229,9 +13229,9 @@
       }
     },
     "node_modules/react-is": {
-      "version": "19.2.5",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.5.tgz",
-      "integrity": "sha512-Dn0t8IQhCmeIT3wu+Apm1/YVsJXsGWi6k4sPdnBIdqMVtHtv0IGi6dcpNpNkNac0zB2uUAqNX3MHzN8c+z2rwQ==",
+      "version": "19.2.6",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.6.tgz",
+      "integrity": "sha512-XjBR15BhXuylgWGuslhDKqlSayuqvqBX91BP8pauG8kd1zY8kotkNWbXksTCNRarse4kuGbe2kIY05ARtwNIvw==",
       "license": "MIT",
       "peer": true
     },
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index b43e174889..66b821d6c7 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -88,8 +88,8 @@
     "@eslint/js": "^9.39.1",
     "@types/canvas-confetti": "^1.9.0",
     "@types/js-yaml": "^4.0.9",
-    "@types/node-forge": "^1.3.14",
     "@types/node": "^25.5.2",
+    "@types/node-forge": "^1.3.14",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
diff --git a/studio/frontend/src/app/router.tsx b/studio/frontend/src/app/router.tsx
index f0a417638d..a0ca1e8cdb 100644
--- a/studio/frontend/src/app/router.tsx
+++ b/studio/frontend/src/app/router.tsx
@@ -13,6 +13,7 @@ import { Route as gridTestRoute } from "./routes/grid-test";
 import { Route as indexRoute } from "./routes/index";
 import { Route as loginRoute } from "./routes/login";
 import { Route as onboardingRoute } from "./routes/onboarding";
+import { Route as projectsRoute } from "./routes/projects";
 import { Route as changePasswordRoute } from "./routes/change-password";
 import { Route as settingsRoute } from "./routes/settings";
 import { Route as studioRoute } from "./routes/studio";
@@ -26,6 +27,7 @@ const routeTree = rootRoute.addChildren([
   settingsRoute,
   studioRoute,
   chatRoute,
+  projectsRoute,
   exportRoute,
   dataRecipesRoute,
   dataRecipeRoute,
diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index 57ed233d51..da74a9e8a7 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -6,6 +6,7 @@ import { Navbar } from "@/components/navbar";
 import { fetchDeviceType, usePlatformStore } from "@/config/env";
 import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
 import { SettingsDialog, useSettingsDialogStore } from "@/features/settings";
+import { useChatRuntimeStore } from "@/features/chat";
 import { useTrainingUnloadGuard } from "@/features/training";
 import { useSidebarPin } from "@/hooks/use-sidebar-pin";
 import { useT, type TranslationKey } from "@/i18n";
@@ -40,6 +41,7 @@ function RouteFallback() {
 const CHAT_ONLY_ALLOWED = new Set([
   "/",
   "/chat",
+  "/projects",
   "/login",
   "/signup",
   "/change-password",
@@ -110,6 +112,13 @@ function RootLayout() {
     return () => window.removeEventListener("keydown", handler);
   }, []);
 
+  useEffect(() => {
+    if (isChatRoute) return;
+    const chatRuntime = useChatRuntimeStore.getState();
+    chatRuntime.setActiveProjectId(null);
+    chatRuntime.setActiveThreadId(null);
+  }, [isChatRoute]);
+
   return (
     <AppProvider>
       <SettingsDialog />
diff --git a/studio/frontend/src/app/routes/chat.tsx b/studio/frontend/src/app/routes/chat.tsx
index 98c73aa7e0..a5514cdee1 100644
--- a/studio/frontend/src/app/routes/chat.tsx
+++ b/studio/frontend/src/app/routes/chat.tsx
@@ -10,6 +10,7 @@ export type ChatSearch = {
   thread?: string;
   compare?: string;
   new?: string;
+  project?: string;
 };
 
 export const Route = createRoute({
@@ -21,6 +22,7 @@ export const Route = createRoute({
     thread: typeof search.thread === "string" ? search.thread : undefined,
     compare: typeof search.compare === "string" ? search.compare : undefined,
     new: typeof search.new === "string" ? search.new : undefined,
+    project: typeof search.project === "string" ? search.project : undefined,
   }),
   component: ChatPage,
 });
diff --git a/studio/frontend/src/app/routes/projects.tsx b/studio/frontend/src/app/routes/projects.tsx
new file mode 100644
index 0000000000..c63b1d5838
--- /dev/null
+++ b/studio/frontend/src/app/routes/projects.tsx
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { createRoute } from "@tanstack/react-router";
+import { lazy } from "react";
+import { requireAuth } from "../auth-guards";
+import { Route as rootRoute } from "./__root";
+
+const ProjectsPage = lazy(() =>
+  import("@/features/chat/projects-page").then((m) => ({
+    default: m.ProjectsPage,
+  })),
+);
+
+export const Route = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/projects",
+  staticData: { title: "Projects" },
+  beforeLoad: () => requireAuth(),
+  component: ProjectsPage,
+});
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 4e4a6130cd..16292bd6e4 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -26,6 +26,9 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
   DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import {
@@ -38,6 +41,7 @@ import {
 } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
 import { useAnimatedThemeToggle } from "@/components/ui/animated-theme-toggler";
 import { cn } from "@/lib/utils";
 import {
@@ -47,9 +51,12 @@ import {
   Delete02Icon,
   DownloadSquare01Icon,
   Edit03Icon,
+  FolderAddIcon,
+  Folder01Icon,
   Globe02Icon,
   HelpCircleIcon,
   Logout05Icon,
+  MoreVerticalIcon,
   Search01Icon,
   PowerIcon,
   PencilEdit02Icon,
@@ -68,11 +75,17 @@ import { ChevronDown, ChevronsUpDown, MoreHorizontalIcon, Moon, Sun } from "luci
 import { Link, useNavigate, useRouterState } from "@tanstack/react-router";
 import {
   ChatSearchDialog,
+  createChatProject,
+  deleteChatProject,
   deleteChatItem,
+  moveChatItemToProject,
   renameChatItem,
+  renameChatProject,
   useChatRuntimeStore,
+  useChatProjects,
   useChatSearchStore,
   useChatSidebarItems,
+  type ProjectRecord,
   type SidebarItem,
 } from "@/features/chat";
 import { useSettingsDialogStore } from "@/features/settings";
@@ -90,7 +103,7 @@ import {
   useTrainingRuntimeStore,
 } from "@/features/training";
 import type { TrainingRunSummary } from "@/features/training";
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { toast } from "@/lib/toast";
 import { ShutdownDialog } from "@/components/shutdown-dialog";
 import { translate, useT, type TranslationKey } from "@/i18n";
@@ -185,7 +198,7 @@ function NavItem({
   active: boolean;
   disabled?: boolean;
   onClick: () => void;
-  children?: React.ReactNode;
+  children?: ReactNode;
   dataTour?: string;
 }) {
   return (
@@ -197,7 +210,7 @@ function NavItem({
           onClick={onClick}
           isActive={active}
           data-tour={dataTour}
-          className="sidebar-nav-btn h-[35px] rounded-[10px] gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-[10px] group-data-[collapsible=icon]:mx-auto"
+          className="sidebar-nav-btn h-[33px] rounded-[10px] gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-[10px] group-data-[collapsible=icon]:mx-auto"
         >
           <HugeiconsIcon icon={icon} strokeWidth={1.75} className="size-icon! shrink-0 group-hover/menu-button:animate-icon-pop" />
           <span className="text-[14.5px] leading-[19px] tracking-nav">{label}</span>
@@ -231,22 +244,53 @@ export function AppSidebar() {
 
   const isChatRoute = pathname.startsWith("/chat");
   const isStudioRoute = pathname === "/studio" || pathname.startsWith("/studio/");
+  const [chatOpen, setChatOpen] = useState(true);
+  const [trainOpen, setTrainOpen] = useState(true);
+  const [runsOpen, setRunsOpen] = useState(true);
+
+  useEffect(() => {
+    if (!isChatRoute) return;
+    queueMicrotask(() => setChatOpen(true));
+  }, [isChatRoute]);
+  useEffect(() => {
+    if (!isStudioRoute) return;
+    queueMicrotask(() => setRunsOpen(true));
+  }, [isStudioRoute]);
 
   const scrollRef = useRef<HTMLDivElement | null>(null);
   const [scrolled, setScrolled] = useState(false);
-  useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    const handler = () => setScrolled(el.scrollTop > 0);
-    handler();
-    el.addEventListener("scroll", handler, { passive: true });
-    return () => el.removeEventListener("scroll", handler);
-  }, []);
+  // Bottom fade hides at the very bottom (and for short, non-scrolling lists)
+  // so the last row isn't washed out - Gemini-style.
+  const [canScrollDown, setCanScrollDown] = useState(false);
+  // Driven only from onScroll + a content-change effect below. Deliberately NO
+  // ResizeObserver: its callback-driven setState created a render loop (React
+  // #185). Both setters bail out when unchanged, so neither path can loop.
+  const syncScrollState = (el: HTMLDivElement) => {
+    const nextScrolled = el.scrollTop > 0;
+    setScrolled((prev) => (prev === nextScrolled ? prev : nextScrolled));
+    const nextCanScrollDown =
+      el.scrollHeight - el.scrollTop - el.clientHeight > 1;
+    setCanScrollDown((prev) =>
+      prev === nextCanScrollDown ? prev : nextCanScrollDown,
+    );
+  };
 
   const isRecipesRoute = pathname.startsWith("/data-recipes");
   const { displayTitle, avatarDataUrl } = useEffectiveProfile();
 
-  const { items: chatItems } = useChatSidebarItems();
+  const { projects } = useChatProjects();
+  const activeProjectId = isChatRoute
+    ? ((search.project as string | undefined) ?? null)
+    : null;
+  const { items: allChatItems } = useChatSidebarItems({
+    enabled: !isStudioRoute,
+    requireMessages: false,
+  });
+  const recentChatItems = useMemo(
+    () => allChatItems.filter((item) => !item.projectId),
+    [allChatItems],
+  );
+  const chatItems = allChatItems;
   const storeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const setActiveThreadId = useChatRuntimeStore((s) => s.setActiveThreadId);
   const activeThreadId = isChatRoute
@@ -261,33 +305,87 @@ export function AppSidebar() {
     !chatOnly && isStudioRoute,
   );
   const activeJobId = useTrainingRuntimeStore((s) => s.jobId);
+  const currentRunViewActive = useTrainingRuntimeStore((s) => s.currentRunViewActive);
   const selectedHistoryRunId = useTrainingRuntimeStore((s) => s.selectedHistoryRunId);
   const setSelectedHistoryRunId = useTrainingRuntimeStore((s) => s.setSelectedHistoryRunId);
 
+  // Recompute the bottom-fade state on mount and whenever the list height can
+  // change (items load, sections collapse/expand, route switches the visible
+  // list) - onScroll never fires for short, non-scrolling lists. Guarded
+  // setState below means this can't loop even if a dep is a fresh reference.
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const next = el.scrollHeight - el.scrollTop - el.clientHeight > 1;
+    setCanScrollDown((prev) => (prev === next ? prev : next));
+  }, [
+    recentChatItems.length,
+    runItems.length,
+    projects.length,
+    chatOpen,
+    trainOpen,
+    runsOpen,
+    isStudioRoute,
+  ]);
+
   const chatDisabled = isTrainingRunning;
 
+  function chatSearchForProject(projectId: string | null) {
+    if (projectId) {
+      return { project: projectId };
+    }
+    return {
+      new: createNavigationNonce(),
+    };
+  }
+
+  function openNewChat(projectId = activeProjectId) {
+    if (chatDisabled) return;
+    setActiveThreadId(null);
+    useChatRuntimeStore.getState().setActiveProjectId(projectId);
+    navigate({ to: "/chat", search: chatSearchForProject(projectId) });
+    closeMobileIfOpen();
+  }
+
+  function openProject(projectId: string) {
+    if (chatDisabled) return;
+    setActiveThreadId(null);
+    useChatRuntimeStore.getState().setActiveProjectId(projectId);
+    navigate({ to: "/chat", search: { project: projectId } });
+    closeMobileIfOpen();
+  }
+
   async function handleDeleteThread(item: Parameters<typeof deleteChatItem>[0]) {
     await deleteChatItem(item, activeThreadId, (view) => {
       navigate({
         to: "/chat",
-        search: { new: view.newThreadNonce },
+        search: item.projectId
+          ? { project: item.projectId }
+          : { new: view.newThreadNonce },
       });
     });
   }
 
   type RenameTarget =
     | { kind: "chat"; item: SidebarItem; current: string }
+    | { kind: "project"; project: ProjectRecord; current: string }
     | { kind: "run"; run: TrainingRunSummary; current: string };
   const [renamingTarget, setRenamingTarget] = useState<RenameTarget | null>(
     null,
   );
   const [renameDraft, setRenameDraft] = useState("");
+  const [creatingProject, setCreatingProject] = useState(false);
+  const [projectNameDraft, setProjectNameDraft] = useState("");
+  const [projectCreateMoveTarget, setProjectCreateMoveTarget] =
+    useState<SidebarItem | null>(null);
   const renameTrimmed = renameDraft.trim();
   const nextRunDisplayName = renameTrimmed.length > 0 ? renameTrimmed : null;
   const renameDirty =
     renamingTarget !== null &&
     (renamingTarget.kind === "chat"
       ? renameTrimmed.length > 0 && renameTrimmed !== renamingTarget.current
+      : renamingTarget.kind === "project"
+        ? renameTrimmed.length > 0 && renameTrimmed !== renamingTarget.current
       : renameTrimmed.length > 0
         ? renameTrimmed !== renamingTarget.current
         : renamingTarget.run.display_name != null);
@@ -315,6 +413,16 @@ export function AppSidebar() {
       }
       return;
     }
+    if (target.kind === "project") {
+      try {
+        await renameChatProject(target.project.id, renameTrimmed);
+      } catch (err) {
+        toast.error("Failed to rename project", {
+          description: err instanceof Error ? err.message : undefined,
+        });
+      }
+      return;
+    }
     try {
       const updated = await renameTrainingRun(target.run.id, nextRunDisplayName);
       emitTrainingRunUpdated(updated);
@@ -327,13 +435,23 @@ export function AppSidebar() {
 
   type DeleteTarget =
     | { kind: "chat"; item: SidebarItem }
+    | { kind: "project"; project: ProjectRecord }
     | { kind: "run"; run: TrainingRunSummary };
   const [confirmingDelete, setConfirmingDelete] =
     useState<DeleteTarget | null>(null);
+  const [deleteProjectFiles, setDeleteProjectFiles] = useState(false);
+
+  useEffect(() => {
+    if (confirmingDelete?.kind !== "project") {
+      setDeleteProjectFiles(false);
+    }
+  }, [confirmingDelete]);
 
   async function commitDelete() {
     const target = confirmingDelete;
     if (!target) return;
+    const shouldDeleteProjectFiles =
+      target.kind === "project" && deleteProjectFiles;
     setConfirmingDelete(null);
     if (target.kind === "chat") {
       try {
@@ -345,6 +463,22 @@ export function AppSidebar() {
       }
       return;
     }
+    if (target.kind === "project") {
+      try {
+        await deleteChatProject(target.project.id, {
+          deleteFiles: shouldDeleteProjectFiles,
+        });
+        if (activeProjectId === target.project.id) {
+          useChatRuntimeStore.getState().setActiveProjectId(null);
+          navigate({ to: "/chat", search: { new: createNavigationNonce() } });
+        }
+      } catch (err) {
+        toast.error("Failed to delete project", {
+          description: err instanceof Error ? err.message : undefined,
+        });
+      }
+      return;
+    }
     if (target.run.status === "running") {
       toast.error(t("shell.toast.cannotDeleteRunningRun"));
       return;
@@ -362,6 +496,168 @@ export function AppSidebar() {
     }
   }
 
+  async function commitCreateProject() {
+    const name = projectNameDraft.trim();
+    if (!name) return;
+    const moveTarget = projectCreateMoveTarget;
+    try {
+      const project = await createChatProject(name);
+      if (moveTarget) {
+        await moveChatItemToProject(moveTarget, project.id);
+        if (activeThreadId === moveTarget.id) {
+          useChatRuntimeStore.getState().setActiveProjectId(project.id);
+        }
+      }
+      setCreatingProject(false);
+      setProjectNameDraft("");
+      setProjectCreateMoveTarget(null);
+      if (moveTarget) {
+        return;
+      } else {
+        openProject(project.id);
+      }
+    } catch (err) {
+      toast.error(moveTarget ? "Failed to create and move chat" : "Failed to create project", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  async function moveChatToProject(item: SidebarItem, projectId: string | null) {
+    if (item.projectId === projectId) return;
+    try {
+      await moveChatItemToProject(item, projectId);
+      if (activeThreadId === item.id) {
+        useChatRuntimeStore.getState().setActiveProjectId(projectId);
+      }
+    } catch (err) {
+      toast.error("Failed to move chat", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  function renderChatSidebarItem(
+    item: SidebarItem,
+    variant: "project" | "recent",
+  ) {
+    const itemClass =
+      variant === "project"
+        ? "group/project-chat-item relative"
+        : "group/recent-item relative";
+    const actionClass =
+      variant === "project"
+        ? "sidebar-row-action group-hover/project-chat-item:opacity-100 group-hover/project-chat-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
+        : "sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto";
+    const buttonClass = cn(
+      "sidebar-nav-btn h-[33px] cursor-pointer rounded-[10px] pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
+      variant === "project" ? "pl-[37px]" : "pl-2.5",
+      variant === "project"
+        ? "group-hover/project-chat-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/project-chat-item:pr-8"
+        : "group-hover/recent-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/recent-item:pr-8",
+    );
+
+    return (
+      <SidebarMenuItem key={item.id} className={itemClass}>
+        <SidebarMenuButton
+          data-testid="recent-thread"
+          data-thread-type={item.type}
+          data-thread-id={item.id}
+          isActive={activeThreadId === item.id}
+          className={buttonClass}
+          onClick={() => {
+            navigate({
+              to: "/chat",
+              search:
+                item.type === "single"
+                  ? {
+                      thread: item.id,
+                      ...(item.projectId ? { project: item.projectId } : {}),
+                    }
+                  : {
+                      compare: item.id,
+                      ...(item.projectId ? { project: item.projectId } : {}),
+                    },
+            });
+            closeMobileIfOpen();
+          }}
+        >
+          <span className="truncate">{item.title}</span>
+        </SidebarMenuButton>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button
+              type="button"
+              onClick={(e) => e.stopPropagation()}
+              aria-label="Chat options"
+              className={actionClass}
+            >
+              <span className="sidebar-row-action-glyph">
+                <HugeiconsIcon icon={MoreVerticalIcon} strokeWidth={1.75} className="size-icon" />
+              </span>
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            side="bottom"
+            align="end"
+            sideOffset={4}
+            className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
+          >
+            <DropdownMenuItem onSelect={() => openRenameChat(item)}>
+              <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
+              <span>Rename</span>
+            </DropdownMenuItem>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger>
+                <HugeiconsIcon icon={Folder01Icon} strokeWidth={1.75} className="size-icon" />
+                <span>Move to project</span>
+              </DropdownMenuSubTrigger>
+              <DropdownMenuSubContent
+                sideOffset={8}
+                alignOffset={-4}
+                className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-56 py-2 font-heading rounded-[14px] border-0"
+              >
+                <DropdownMenuItem
+                  onSelect={() => {
+                    setProjectCreateMoveTarget(item);
+                    setProjectNameDraft("");
+                    setCreatingProject(true);
+                  }}
+                >
+                  <HugeiconsIcon icon={FolderAddIcon} strokeWidth={1.75} className="size-icon" />
+                  <span>New project</span>
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  disabled={!item.projectId}
+                  onSelect={() => void moveChatToProject(item, null)}
+                >
+                  <span>Recents</span>
+                </DropdownMenuItem>
+                {projects.map((project) => (
+                  <DropdownMenuItem
+                    key={project.id}
+                    disabled={item.projectId === project.id}
+                    onSelect={() => void moveChatToProject(item, project.id)}
+                  >
+                    <HugeiconsIcon icon={Folder01Icon} strokeWidth={1.75} className="size-icon" />
+                    <span className="truncate">{project.name}</span>
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
+            <DropdownMenuItem
+              variant="destructive"
+              onSelect={() => setConfirmingDelete({ kind: "chat", item })}
+            >
+              <HugeiconsIcon icon={Delete02Icon} strokeWidth={1.75} className="size-icon" />
+              <span>Delete</span>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    );
+  }
+
   return (
     <>
     <Sidebar
@@ -369,7 +665,7 @@ export function AppSidebar() {
       variant="sidebar"
       className="font-heading group-data-[collapsible=icon]:[&_[data-sidebar=sidebar]]:bg-white dark:group-data-[collapsible=icon]:[&_[data-sidebar=sidebar]]:bg-background"
     >
-      <SidebarHeader className="pl-[17px] pr-3 pt-[12px] pb-[8px] group-data-[collapsible=icon]:px-0">
+      <SidebarHeader className="pl-[17px] pr-3 pt-[14px] pb-[8px] group-data-[collapsible=icon]:px-0">
         {/* Expanded: compact logo + close toggle */}
         <div className="flex items-center justify-between gap-[8.5px] group-data-[collapsible=icon]:hidden">
           <Link
@@ -377,12 +673,7 @@ export function AppSidebar() {
             onClick={(event) => {
               event.preventDefault();
               if (chatDisabled) return;
-              setActiveThreadId(null);
-              closeMobileIfOpen();
-              void navigate({
-                to: "/chat",
-                search: { new: createNavigationNonce() },
-              });
+              openNewChat(null);
             }}
             className="flex items-center gap-[6px] select-none"
             aria-label={t("shell.aria.home")}
@@ -392,7 +683,7 @@ export function AppSidebar() {
               alt="Unsloth"
               className="h-[34px] w-[34px] rounded-full object-cover"
             />
-            <span className="font-heading text-[21px] font-semibold tracking-[-0.01em] dark:tracking-[0.02em] leading-none text-black dark:text-white">
+            <span className="font-heading text-[21px] font-semibold tracking-[0em] dark:tracking-[0.02em] leading-none text-black dark:text-white">
               unsloth
             </span>
             <span className="nav-badge ml-0.5 inline-flex items-center justify-center rounded-full border border-nav-beta-border px-[5px] pt-[3px] pb-[2px] text-[8px] font-medium leading-none tracking-[0.04em] text-nav-fg-muted antialiased subpixel-antialiased shadow-[0_1px_2px_rgba(0,0,0,0.06)] dark:shadow-[0_1px_2px_rgba(0,0,0,0.35)]">
@@ -405,7 +696,7 @@ export function AppSidebar() {
                 <button
                   type="button"
                   onClick={togglePinned}
-                  className="inline-flex h-[35px] w-[32px] items-center justify-center rounded-[10px] text-nav-icon-idle dark:text-nav-fg-muted transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  className="inline-flex h-[33px] w-[32px] cursor-pointer items-center justify-center rounded-[10px] text-nav-icon-idle dark:text-nav-fg-muted transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                   aria-label={t("shell.aria.closeSidebar")}
                 >
                   <HugeiconsIcon icon={LayoutAlignLeftIcon} strokeWidth={1.75} className="size-icon" />
@@ -424,13 +715,13 @@ export function AppSidebar() {
 
         {/* Collapsed: panel icon doubles as expand trigger */}
         {!isMobile && (
-          <div className="hidden group-data-[collapsible=icon]:flex h-[35px] items-center justify-center w-full">
+          <div className="hidden group-data-[collapsible=icon]:flex h-[33px] items-center justify-center w-full">
             <Tooltip>
               <TooltipPrimitive.Trigger asChild>
                 <button
                   type="button"
                   onClick={togglePinned}
-                  className="inline-flex h-[35px] w-[32px] items-center justify-center rounded-[10px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  className="inline-flex h-[33px] w-[32px] cursor-pointer items-center justify-center rounded-[10px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                   aria-label={t("shell.aria.openSidebar")}
                 >
                   <HugeiconsIcon icon={LayoutAlignLeftIcon} strokeWidth={1.75} className="size-icon" />
@@ -448,31 +739,37 @@ export function AppSidebar() {
         )}
       </SidebarHeader>
 
-      <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-2 pt-[9px] pb-[8px] shrink-0">
+      <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-2 pt-[9px] pb-px shrink-0">
         <SidebarGroupContent>
           <SidebarMenu>
             <NavItem
               icon={PencilEdit02Icon}
               label={t("shell.navigation.newChat")}
-              active={false}
+              active={
+                isChatRoute &&
+                !search.thread &&
+                !search.compare &&
+                !search.project
+              }
               disabled={chatDisabled}
-              onClick={() => {
-                if (chatDisabled) return;
-                setActiveThreadId(null);
-                navigate({ to: "/chat", search: { new: createNavigationNonce() } });
-                closeMobileIfOpen();
-              }}
+              onClick={() => openNewChat(null)}
             />
             <NavItem
               icon={ColumnInsertIcon}
               label={t("shell.navigation.compare")}
-              active={!!search.compare && !chatItems.some((i) => i.id === search.compare)}
+              active={
+                !!search.compare &&
+                !chatItems.some((i) => i.id === search.compare)
+              }
               disabled={chatDisabled}
               dataTour="chat-compare"
               onClick={() => {
                 if (chatDisabled) return;
                 setActiveThreadId(null);
-                navigate({ to: "/chat", search: { compare: createNavigationNonce() } });
+                navigate({
+                  to: "/chat",
+                  search: { compare: createNavigationNonce() },
+                });
                 closeMobileIfOpen();
               }}
             />
@@ -480,9 +777,10 @@ export function AppSidebar() {
               icon={Search01Icon}
               label={t("shell.navigation.search")}
               active={false}
-              disabled={chatDisabled}
               onClick={() => {
-                if (chatDisabled) return;
+                // Search is read-only over chat history and never runs
+                // inference, so it stays available while training (unlike
+                // New chat, which is gated on `chatDisabled`).
                 useChatSearchStore.getState().open();
                 closeMobileIfOpen();
               }}
@@ -491,140 +789,127 @@ export function AppSidebar() {
         </SidebarGroupContent>
       </SidebarGroup>
 
-      <SidebarGroup data-tour="navbar" className="group-data-[collapsible=icon]:px-0 px-2 pt-[9px] pb-[20px] shrink-0">
-        <SidebarGroupContent>
-          <SidebarMenu>
-            <NavItem
-              icon={TestTubeOutlineIcon}
-              label={t("shell.navigation.train")}
-              active={pathname === "/studio" || pathname.startsWith("/studio/")}
-              disabled={chatOnly}
-              onClick={() => {
-                if (chatOnly) return;
-                navigate({ to: "/studio" });
-                closeMobileIfOpen();
-              }}
-            />
+      <SidebarContent
+        ref={scrollRef}
+        onScroll={(e) => syncScrollState(e.currentTarget)}
+        className={cn(
+          // pb-2 keeps the last row's rounded highlight clear of the
+          // overflow clip edge so its bottom corners aren't shaved off.
+          "sidebar-scroll-fade gap-0 overflow-y-auto overscroll-contain min-h-0 pb-2",
+          scrolled && "is-scrolled",
+        )}
+      >
+        <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-2 py-0 shrink-0">
+          <SidebarGroupContent>
+            <SidebarMenu>
+              <NavItem
+                icon={Folder01Icon}
+                label="Projects"
+                active={
+                  pathname === "/projects" || pathname.startsWith("/projects/")
+                }
+                onClick={() => {
+                  navigate({ to: "/projects" });
+                  closeMobileIfOpen();
+                }}
+              />
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
 
-            <NavItem
-              icon={ChefHatIcon}
-              label={t("shell.navigation.recipes")}
-              active={isRecipesRoute}
-              onClick={() => {
-                navigate({ to: "/data-recipes" });
-                closeMobileIfOpen();
-              }}
-            />
-
-            <NavItem
-              icon={DownloadSquare01Icon}
-              label={t("shell.navigation.export")}
-              active={pathname === "/export" || pathname.startsWith("/export/")}
-              disabled={chatOnly}
-              onClick={() => {
-                if (chatOnly) return;
-                navigate({ to: "/export" });
-                closeMobileIfOpen();
-              }}
-            />
-          </SidebarMenu>
-        </SidebarGroupContent>
-      </SidebarGroup>
-
-      <SidebarContent ref={scrollRef} className="gap-0 overflow-y-auto overscroll-contain min-h-0">
-        {!isStudioRoute && chatItems.length > 0 && (
-          <Collapsible
-            key={isChatRoute ? "chat-route" : "non-chat-route"}
-            defaultOpen
-            asChild
-          >
-          <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
-            <SidebarGroupLabel className={cn("sidebar-sticky-label", scrolled && "is-scrolled")} asChild>
-              <CollapsibleTrigger className="cursor-pointer flex w-full items-center justify-between">
-                {t("shell.navigation.recents")}
-                <ChevronDown className="size-3.5 transition-transform duration-200 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+        <Collapsible open={trainOpen} onOpenChange={setTrainOpen} asChild>
+          <SidebarGroup data-tour="navbar" className="group-data-[collapsible=icon]:hidden px-0 py-0">
+            <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
+              <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
+                {t("shell.navigation.train")}
+                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
             <CollapsibleContent>
-            <SidebarGroupContent className="px-2">
-              <SidebarMenu>
-                {chatItems.map((item) => (
-                  <SidebarMenuItem key={item.id} className="group/recent-item relative">
-                    <SidebarMenuButton
-                      data-testid="recent-thread"
-                      data-thread-type={item.type}
-                      data-thread-id={item.id}
-                      isActive={activeThreadId === item.id}
-                      className="sidebar-nav-btn h-[32px] rounded-[10px] pl-2.5 pr-2.5 group-hover/recent-item:pr-10 group-has-[.sidebar-row-action[data-state=open]]/recent-item:pr-10 text-[14.5px] leading-[19px] tracking-nav font-medium"
-                      onClick={() => {
-                        navigate({
-                          to: "/chat",
-                          search:
-                            item.type === "single"
-                              ? { thread: item.id }
-                              : { compare: item.id },
-                        });
-                        closeMobileIfOpen();
-                      }}
-                    >
-                      <span className="truncate">{item.title}</span>
-                    </SidebarMenuButton>
-                    <DropdownMenu>
-                      <DropdownMenuTrigger asChild>
-                        <button
-                          type="button"
-                          onClick={(e) => e.stopPropagation()}
-                          aria-label={t("shell.aria.chatOptions")}
-                          className="sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
-                        >
-                          <span className="sidebar-row-action-glyph">
-                            <MoreHorizontalIcon strokeWidth={1.75} className="size-icon" />
-                          </span>
-                        </button>
-                      </DropdownMenuTrigger>
-                      <DropdownMenuContent
-                        side="bottom"
-                        align="end"
-                        sideOffset={4}
-                        className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
-                      >
-                        <DropdownMenuItem onSelect={() => openRenameChat(item)}>
-                          <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
-                          <span>{t("common.rename")}</span>
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          variant="destructive"
-                          onSelect={() => setConfirmingDelete({ kind: "chat", item })}
-                        >
-                          <HugeiconsIcon icon={Delete02Icon} strokeWidth={1.75} className="size-icon" />
-                          <span>{t("common.delete")}</span>
-                        </DropdownMenuItem>
-                      </DropdownMenuContent>
-                    </DropdownMenu>
-                  </SidebarMenuItem>
-                ))}
-              </SidebarMenu>
-            </SidebarGroupContent>
+              <SidebarGroupContent className="px-2">
+                <SidebarMenu>
+                  <NavItem
+                    icon={TestTubeOutlineIcon}
+                    label={t("shell.navigation.train")}
+                    active={pathname === "/studio" || pathname.startsWith("/studio/")}
+                    disabled={chatOnly}
+                    onClick={() => {
+                      if (chatOnly) return;
+                      navigate({ to: "/studio" });
+                      closeMobileIfOpen();
+                    }}
+                  />
+                  <NavItem
+                    icon={ChefHatIcon}
+                    label={t("shell.navigation.recipes")}
+                    active={isRecipesRoute}
+                    onClick={() => {
+                      navigate({ to: "/data-recipes" });
+                      closeMobileIfOpen();
+                    }}
+                  />
+                  <NavItem
+                    icon={DownloadSquare01Icon}
+                    label={t("shell.navigation.export")}
+                    active={pathname === "/export" || pathname.startsWith("/export/")}
+                    disabled={chatOnly}
+                    onClick={() => {
+                      if (chatOnly) return;
+                      navigate({ to: "/export" });
+                      closeMobileIfOpen();
+                    }}
+                  />
+                </SidebarMenu>
+              </SidebarGroupContent>
             </CollapsibleContent>
           </SidebarGroup>
+        </Collapsible>
+
+        {!isStudioRoute && (
+          <Collapsible open={chatOpen} onOpenChange={setChatOpen} asChild>
+            <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
+              <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
+                <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
+                  {t("shell.navigation.recents")}
+                  <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+                </CollapsibleTrigger>
+              </SidebarGroupLabel>
+              <CollapsibleContent>
+                <SidebarGroupContent className="px-2">
+                  <SidebarMenu>
+                    {recentChatItems.map((item) =>
+                      renderChatSidebarItem(item, "recent"),
+                    )}
+                  </SidebarMenu>
+                </SidebarGroupContent>
+              </CollapsibleContent>
+            </SidebarGroup>
           </Collapsible>
         )}
 
         {isStudioRoute && runItems.length > 0 && !chatOnly && (
-          <Collapsible key="studio-runs-route" defaultOpen asChild>
+          <Collapsible open={runsOpen} onOpenChange={setRunsOpen} asChild>
           <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
-            <SidebarGroupLabel className={cn("sidebar-sticky-label", scrolled && "is-scrolled")} asChild>
-              <CollapsibleTrigger className="cursor-pointer flex w-full items-center justify-between">
+            <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
+              <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
                 {t("shell.navigation.recents")}
-                <ChevronDown className="size-3.5 transition-transform duration-200 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
             <CollapsibleContent>
               <SidebarGroupContent className="px-2">
                 <SidebarMenu>
                   {runItems.map((run) => {
+                    // An explicit sidebar selection wins. Otherwise highlight
+                    // the active job only while the "Current Run" tab is the
+                    // view - that covers a live run (it auto-switches there) and
+                    // a just-finished/errored run you're still viewing, while
+                    // keeping the Configure tab unhighlighted even though
+                    // `activeJobId` stays pinned to the last job.
                     const isActiveRun =
-                      selectedHistoryRunId === run.id || activeJobId === run.id;
+                      selectedHistoryRunId != null
+                        ? run.id === selectedHistoryRunId
+                        : currentRunViewActive && run.id === activeJobId;
                     return (
                       <SidebarMenuItem
                         key={run.id}
@@ -703,7 +988,18 @@ export function AppSidebar() {
         )}
       </SidebarContent>
 
-      <SidebarFooter className="border-t border-sidebar-border group-data-[collapsible=icon]:border-transparent group-data-[collapsible=icon]:px-0">
+      <SidebarFooter className="relative group-data-[collapsible=icon]:px-0">
+        {/* Fade above the profile box, shown only while there's more list below
+            the fold; at the very bottom (or for short lists) it fades out so the
+            last row shows fully (Gemini-style). `right-2` keeps it clear of the
+            8px scrollbar gutter so the scrollbar isn't faded out. */}
+        <div
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute left-0 right-2 bottom-full h-10 bg-gradient-to-t from-[var(--sidebar)] to-transparent transition-opacity duration-200",
+            canScrollDown ? "opacity-100" : "opacity-0",
+          )}
+        />
         <SidebarMenu>
           <SidebarMenuItem>
             <DropdownMenu>
@@ -711,14 +1007,14 @@ export function AppSidebar() {
                 <SidebarMenuButton
                   size="lg"
                   aria-label={t("shell.accountMenu", { name: displayTitle })}
-                  className="sidebar-nav-btn !h-[50px] gap-[8px] px-2 py-[9px] rounded-[10px]"
+                  className="sidebar-nav-btn !h-[40px] gap-[8px] px-2 py-[5px] rounded-[10px]"
                 >
                   <div className="shrink-0">
                     <UserAvatar
                       name={displayTitle}
                       imageUrl={avatarDataUrl}
                       size="sm"
-                      className="!size-8"
+                      className="!size-[30px]"
                     />
                   </div>
                   <div className="flex flex-col gap-0.5 leading-tight group-data-[collapsible=icon]:hidden">
@@ -818,7 +1114,10 @@ export function AppSidebar() {
     <Dialog
       open={confirmingDelete !== null}
       onOpenChange={(open) => {
-        if (!open) setConfirmingDelete(null);
+        if (!open) {
+          setConfirmingDelete(null);
+          setDeleteProjectFiles(false);
+        }
       }}
     >
       <DialogContent className="menu-flat-destructive corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
@@ -826,7 +1125,9 @@ export function AppSidebar() {
           <DialogTitle>
             {confirmingDelete?.kind === "run"
               ? t("shell.dialog.deleteRun.title")
-              : t("shell.dialog.deleteChat.title")}
+              : confirmingDelete?.kind === "project"
+                ? "Delete project"
+                : t("shell.dialog.deleteChat.title")}
           </DialogTitle>
           <DialogDescription>
             {confirmingDelete?.kind === "run" ? (
@@ -842,9 +1143,37 @@ export function AppSidebar() {
                 "shell.dialog.deleteChat.description",
                 confirmingDelete.item.title,
               )
+            ) : confirmingDelete?.kind === "project" ? (
+              <>
+                Delete{" "}
+                <span className="font-medium text-foreground">
+                  &quot;{confirmingDelete.project.name}&quot;
+                </span>
+                ? Its chats will be permanently deleted.
+              </>
             ) : null}
           </DialogDescription>
         </DialogHeader>
+        {confirmingDelete?.kind === "project" ? (
+          <div className="flex items-start justify-between gap-4 rounded-md border border-border/60 bg-muted/35 px-3 py-2.5">
+            <label htmlFor="delete-project-files" className="min-w-0 space-y-1">
+              <span className="block text-sm font-medium text-foreground">
+                Delete files and sandbox folder
+              </span>
+              <span className="block break-words text-xs leading-5 text-muted-foreground">
+                {confirmingDelete.project.rootPath
+                  ? confirmingDelete.project.rootPath
+                  : "The project workspace folder will be removed from disk."}
+              </span>
+            </label>
+            <Switch
+              id="delete-project-files"
+              checked={deleteProjectFiles}
+              onCheckedChange={setDeleteProjectFiles}
+              aria-label="Delete project files and sandbox folder"
+            />
+          </div>
+        ) : null}
         <DialogFooter className="flex-wrap gap-2 sm:justify-end">
           <Button
             type="button"
@@ -858,7 +1187,9 @@ export function AppSidebar() {
             variant="destructive"
             onClick={() => void commitDelete()}
           >
-            {t("common.delete")}
+            {confirmingDelete?.kind === "project" && deleteProjectFiles
+              ? "Delete all"
+              : t("common.delete")}
           </Button>
         </DialogFooter>
       </DialogContent>
@@ -874,7 +1205,9 @@ export function AppSidebar() {
           <DialogTitle>
             {renamingTarget?.kind === "run"
               ? t("shell.dialog.renameRun.title")
-              : t("shell.dialog.renameChat.title")}
+              : renamingTarget?.kind === "project"
+                ? "Rename project"
+                : t("shell.dialog.renameChat.title")}
           </DialogTitle>
         </DialogHeader>
         <Input
@@ -891,12 +1224,16 @@ export function AppSidebar() {
           placeholder={
             renamingTarget?.kind === "run"
               ? t("shell.dialog.renameRun.placeholder")
-              : t("shell.dialog.renameChat.placeholder")
+              : renamingTarget?.kind === "project"
+                ? "Project name"
+                : t("shell.dialog.renameChat.placeholder")
           }
           aria-label={
             renamingTarget?.kind === "run"
               ? t("shell.dialog.renameRun.placeholder")
-              : t("shell.dialog.renameChat.placeholder")
+              : renamingTarget?.kind === "project"
+                ? "Project name"
+                : t("shell.dialog.renameChat.placeholder")
           }
           className="focus-visible:border-input focus-visible:ring-0"
         />
@@ -918,6 +1255,58 @@ export function AppSidebar() {
         </DialogFooter>
       </DialogContent>
     </Dialog>
+    <Dialog
+      open={creatingProject}
+      onOpenChange={(open) => {
+        setCreatingProject(open);
+        if (!open) {
+          setProjectNameDraft("");
+          setProjectCreateMoveTarget(null);
+        }
+      }}
+    >
+      <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>
+            {projectCreateMoveTarget ? "Move to new project" : "New project"}
+          </DialogTitle>
+        </DialogHeader>
+        <Input
+          value={projectNameDraft}
+          onChange={(event) => setProjectNameDraft(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              void commitCreateProject();
+            }
+          }}
+          autoFocus
+          maxLength={120}
+          placeholder="Project name"
+          aria-label="Project name"
+          className="focus-visible:border-input focus-visible:ring-0"
+        />
+        <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+          <Button
+            type="button"
+            variant="ghost"
+            onClick={() => {
+              setCreatingProject(false);
+              setProjectCreateMoveTarget(null);
+            }}
+          >
+            Cancel
+          </Button>
+          <Button
+            type="button"
+            onClick={() => void commitCreateProject()}
+            disabled={!projectNameDraft.trim()}
+          >
+            Create
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
     </>
   );
 }
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index b7e0f35d35..b323996072 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -374,7 +374,7 @@ const ThreadWelcome: FC<{
         <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-6 px-4">
           <div className="flex flex-col items-center gap-2 text-center">
             <img src={currentEmojiSrc} alt="Sloth mascot" className="size-20" />
-            <h1 className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in font-heading font-semibold text-2xl tracking-[-0.02em] duration-200">
+            <h1 className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in font-heading font-semibold text-2xl tracking-[0em] duration-200">
               Chat with your model
             </h1>
             <p className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 -mt-1 animate-in font-heading font-normal text-muted-foreground text-sm delay-75 duration-200">
@@ -388,14 +388,30 @@ const ThreadWelcome: FC<{
   );
 };
 
+export const ProjectComposer: FC<{
+  disabled?: boolean;
+  placeholder?: string;
+}> = ({ disabled, placeholder }) => {
+  return (
+    <GeneratedImageOverlayProvider>
+      <ComposerAnimated disabled={disabled} placeholder={placeholder} />
+    </GeneratedImageOverlayProvider>
+  );
+};
+
 const ComposerAnimated: FC<{
   disabled?: boolean;
+  placeholder?: string;
   threadId?: string | null;
-}> = ({ disabled, threadId }) => {
+}> = ({ disabled, placeholder, threadId }) => {
   return (
     <div className="relative mx-auto min-w-0 w-full max-w-(--thread-max-width)">
       <div className="relative z-10 w-full">
-        <Composer disabled={disabled} threadId={threadId} />
+        <Composer
+          disabled={disabled}
+          placeholder={placeholder}
+          threadId={threadId}
+        />
       </div>
     </div>
   );
@@ -427,8 +443,9 @@ const PendingAudioChip: FC = () => {
 
 const Composer: FC<{
   disabled?: boolean;
+  placeholder?: string;
   threadId?: string | null;
-}> = ({ disabled, threadId }) => {
+}> = ({ disabled, placeholder = "Send a message...", threadId }) => {
   const aui = useAui();
   const { overlay, closeOverlay } = useGeneratedImageOverlay();
   const setImageToolsEnabled = useChatRuntimeStore(
@@ -529,9 +546,7 @@ const Composer: FC<{
       <PendingAudioChip />
       <ToolStatusDisplay />
       <ComposerPrimitive.Input
-        placeholder={
-          overlay ? "Type your edits for your image" : "Send a message..."
-        }
+        placeholder={overlay ? "Type your edits for your image" : placeholder}
         className="aui-composer-input composer-input"
         minRows={1}
         maxRows={12}
@@ -975,8 +990,8 @@ const PreserveThinkingToggle: FC = () => {
         disabled
           ? "cursor-not-allowed opacity-40"
           : preserveThinking
-            ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-            : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
+            ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
+            : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
       )}
       aria-label={
         preserveThinking ? "Disable preserve think" : "Enable preserve think"
diff --git a/studio/frontend/src/components/ui/dropdown-menu.tsx b/studio/frontend/src/components/ui/dropdown-menu.tsx
index e2f1c5fc6d..9102e5c945 100644
--- a/studio/frontend/src/components/ui/dropdown-menu.tsx
+++ b/studio/frontend/src/components/ui/dropdown-menu.tsx
@@ -78,7 +78,7 @@ function DropdownMenuItem({
       data-inset={inset}
       data-variant={variant}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 group/dropdown-menu-item relative flex cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 group/dropdown-menu-item relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
@@ -96,7 +96,7 @@ function DropdownMenuCheckboxItem({
     <DropdownMenuPrimitive.CheckboxItem
       data-slot="dropdown-menu-checkbox-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       checked={checked}
@@ -135,7 +135,7 @@ function DropdownMenuRadioItem({
     <DropdownMenuPrimitive.RadioItem
       data-slot="dropdown-menu-radio-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
@@ -221,7 +221,7 @@ function DropdownMenuSubTrigger({
       data-slot="dropdown-menu-sub-trigger"
       data-inset={inset}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-default items-center outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-pointer items-center outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
diff --git a/studio/frontend/src/components/ui/sidebar.tsx b/studio/frontend/src/components/ui/sidebar.tsx
index 6be77d01b9..b3bae96ce7 100644
--- a/studio/frontend/src/components/ui/sidebar.tsx
+++ b/studio/frontend/src/components/ui/sidebar.tsx
@@ -30,7 +30,7 @@ import { LayoutAlignLeftIcon } from "@hugeicons/core-free-icons"
 
 const noop = () => {}
 
-const SIDEBAR_WIDTH = "16rem"
+const SIDEBAR_WIDTH = "17.5rem"
 const SIDEBAR_WIDTH_ICON = "3rem"
 const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
@@ -472,7 +472,7 @@ function SidebarGroupLabel({
       data-slot="sidebar-group-label"
       data-sidebar="group-label"
       className={cn(
-        "text-[#94a3b8] dark:text-[#666] ring-sidebar-ring h-auto pt-3 pb-2 px-4 rounded-md text-[10px] font-semibold uppercase tracking-[0.08em] group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-3 flex shrink-0 items-center outline-hidden [&>svg]:shrink-0",
+        "text-[#94a3b8] dark:text-[#666] ring-sidebar-ring h-auto pt-3 pb-2 px-4 rounded-md text-[10px] font-semibold uppercase tracking-[0em] group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-3 flex shrink-0 items-center outline-hidden [&>svg]:shrink-0",
         className
       )}
       {...props}
diff --git a/studio/frontend/src/components/ui/terminal.tsx b/studio/frontend/src/components/ui/terminal.tsx
index 9c8da23326..e7a05bd1aa 100644
--- a/studio/frontend/src/components/ui/terminal.tsx
+++ b/studio/frontend/src/components/ui/terminal.tsx
@@ -17,12 +17,20 @@ type TerminalProps = {
   className?: string
   sequence?: boolean
   startOnView?: boolean
+  /**
+   * Render every line in its final state immediately, skipping the typing /
+   * fade-in animations. Used when the terminal re-mounts for a run whose intro
+   * already played (e.g. navigating away from the training page and back), so
+   * the logs don't visually "restart" while the run itself keeps going.
+   */
+  instant?: boolean
 }
 
 type InternalLineProps = {
   __isActive?: boolean
   __onDone?: () => void
   __sequence?: boolean
+  __instant?: boolean
 }
 
 function useStartOnView(enabled: boolean): {
@@ -65,15 +73,18 @@ export function Terminal({
   className,
   sequence = true,
   startOnView = true,
+  instant = false,
 }: TerminalProps): ReactElement {
   const { ref, started } = useStartOnView(startOnView)
   const childElements = Children.toArray(children).filter(isValidElement)
   const [activeIndex, setActiveIndex] = useState(0)
-  const visibleIndex = sequence
-    ? started
-      ? activeIndex
-      : -1
-    : Number.MAX_SAFE_INTEGER
+  const visibleIndex = instant
+    ? Number.MAX_SAFE_INTEGER
+    : sequence
+      ? started
+        ? activeIndex
+        : -1
+      : Number.MAX_SAFE_INTEGER
 
   function handleLineDone(index: number): void {
     if (!sequence) {
@@ -99,7 +110,8 @@ export function Terminal({
       {childElements.map((child, index) =>
         cloneElement(child, {
           __sequence: sequence,
-          __isActive: !sequence || visibleIndex >= index,
+          __isActive: instant || !sequence || visibleIndex >= index,
+          __instant: instant,
           __onDone: () => handleLineDone(index),
           key: child.key ?? index,
         } as InternalLineProps)
@@ -122,11 +134,12 @@ export function AnimatedSpan({
   startOnView = false,
   __isActive,
   __sequence,
+  __instant,
   __onDone,
 }: AnimatedSpanProps): ReactElement {
   const { ref, started } = useStartOnView(startOnView)
-  const [visible, setVisible] = useState(false)
-  const doneRef = useRef(false)
+  const [visible, setVisible] = useState(Boolean(__instant))
+  const doneRef = useRef(Boolean(__instant))
   const onDoneRef = useRef(__onDone)
   const shouldStart = __sequence ? __isActive : started
 
@@ -180,11 +193,12 @@ export function TypingAnimation({
   startOnView = true,
   __isActive,
   __sequence,
+  __instant,
   __onDone,
 }: TypingAnimationProps): ReactElement {
   const { ref, started } = useStartOnView(startOnView)
-  const [typed, setTyped] = useState("")
-  const doneRef = useRef(false)
+  const [typed, setTyped] = useState(__instant ? children : "")
+  const doneRef = useRef(Boolean(__instant))
   const onDoneRef = useRef(__onDone)
   const shouldStart = __sequence ? __isActive : started
 
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index fc77fecaeb..1fcbe7ff70 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -47,6 +47,7 @@ import type {
 import type { ChatModelSummary } from "../types/runtime";
 import {
   getStoredChatThread,
+  getStoredChatProject,
   listStoredChatThreads,
   updateStoredChatThread,
 } from "../utils/chat-history-storage";
@@ -866,6 +867,45 @@ async function resolveUseAdapter(
   }
 }
 
+async function resolveProjectInstructions(
+  threadId: string | undefined,
+): Promise<string> {
+  const projectId = await resolveProjectId(threadId);
+  if (!projectId) {
+    return "";
+  }
+
+  const project = await getStoredChatProject(projectId).catch(() => null);
+  if (!project || project.archived) {
+    return "";
+  }
+  return project.instructions?.trim() ?? "";
+}
+
+async function resolveProjectId(
+  threadId: string | undefined,
+): Promise<string | null> {
+  let projectId: string | null | undefined;
+  if (threadId) {
+    const thread = await getStoredChatThread(threadId).catch(() => null);
+    projectId = thread?.projectId ?? null;
+  }
+  if (!projectId) {
+    projectId = useChatRuntimeStore.getState().activeProjectId;
+  }
+  if (!projectId) {
+    return null;
+  }
+  return projectId;
+}
+
+async function resolveSandboxSessionId(
+  threadId: string | undefined,
+): Promise<string | undefined> {
+  const projectId = await resolveProjectId(threadId);
+  return projectId ? `project-${projectId}` : threadId;
+}
+
 /** Wait for an in-progress model load to finish (polls store every 500ms). */
 function waitForModelReady(abortSignal?: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -1202,6 +1242,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       // the user switches chats while waiting for model load / auto-load.
       const resolvedThreadId =
         (unstable_threadId ?? runtime.activeThreadId) || undefined;
+      const sandboxSessionId = await resolveSandboxSessionId(resolvedThreadId);
       const resolvedThreadKey = resolvedThreadId ?? null;
       const pendingImageEditReferenceForRun = runtime.pendingImageEditReference;
       const selectedImageEditReference =
@@ -1442,10 +1483,20 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
 
       const safeSystemPrompt =
         typeof params.systemPrompt === "string" ? params.systemPrompt : "";
-      if (safeSystemPrompt.trim()) {
+      const projectInstructions =
+        await resolveProjectInstructions(resolvedThreadId);
+      const combinedSystemPrompt = [
+        projectInstructions
+          ? `<project_instructions>\n${projectInstructions}\n</project_instructions>`
+          : "",
+        safeSystemPrompt.trim(),
+      ]
+        .filter(Boolean)
+        .join("\n\n");
+      if (combinedSystemPrompt) {
         outboundMessages.unshift({
           role: "system",
-          content: safeSystemPrompt.trim(),
+          content: combinedSystemPrompt,
         });
       }
       let disabledToolGuard: string | null = null;
@@ -1762,7 +1813,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       // /inference/cancel explicitly on abort.
       const onAbortCancel = () => {
         const body: Record<string, string> = { cancel_id: cancelId };
-        if (resolvedThreadId) body.session_id = resolvedThreadId;
+        if (sandboxSessionId) body.session_id = sandboxSessionId;
         // Plain fetch, not authFetch: authFetch redirects to login on
         // 401, which would kick the user out mid-stop.
         const token = getAuthToken();
@@ -2077,7 +2128,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             image_base64: imageBase64,
             audio_base64: audioBase64,
             cancel_id: cancelId,
-            ...(resolvedThreadId ? { session_id: resolvedThreadId } : {}),
+            ...(sandboxSessionId ? { session_id: sandboxSessionId } : {}),
             ...(useAdapter === undefined ? {} : { use_adapter: useAdapter }),
             ...(supportsReasoning
               ? reasoningStyle === "reasoning_effort"
@@ -2272,7 +2323,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       const text = rawResult.slice(0, imgIdx);
                       // Fall back to "_default" to match the backend sandbox directory
                       // used when no session_id is provided (see tools.py _get_workdir).
-                      const sessionId = resolvedThreadId || "_default";
+                      const sessionId = sandboxSessionId || "_default";
                       try {
                         const images = JSON.parse(
                           rawResult.slice(imgIdx + imgMarker.length),
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 81303d9311..85b3be7dea 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -3,7 +3,12 @@
 
 import { authFetch } from "@/features/auth";
 import { formatFastApiDetail } from "@/lib/format-fastapi-error";
-import type { MessageRecord, ModelType, ThreadRecord } from "../types";
+import type {
+  MessageRecord,
+  ModelType,
+  ProjectRecord,
+  ThreadRecord,
+} from "../types";
 import type {
   AudioGenerationResponse,
   GgufVariantsResponse,
@@ -287,12 +292,14 @@ export async function listChatThreads(
   args: {
     modelType?: ModelType;
     pairId?: string;
+    projectId?: string | null;
     includeArchived?: boolean;
   } = {},
 ): Promise<ThreadRecord[]> {
   const params = new URLSearchParams();
   if (args.modelType) params.set("model_type", args.modelType);
   if (args.pairId) params.set("pair_id", args.pairId);
+  if (args.projectId) params.set("project_id", args.projectId);
   if (args.includeArchived !== undefined) {
     params.set("include_archived", String(args.includeArchived));
   }
@@ -353,6 +360,74 @@ export async function deleteChatThreads(threadIds: string[]): Promise<void> {
   notifyChatHistoryUpdated();
 }
 
+export async function listChatProjects(
+  args: { includeArchived?: boolean } = {},
+): Promise<ProjectRecord[]> {
+  const params = new URLSearchParams();
+  if (args.includeArchived !== undefined) {
+    params.set("include_archived", String(args.includeArchived));
+  }
+  const qs = params.toString();
+  const response = await authFetch(`/api/chat/projects${qs ? `?${qs}` : ""}`);
+  const data = await parseJsonOrThrow<{ projects: ProjectRecord[] }>(response);
+  return data.projects;
+}
+
+export async function getChatProject(
+  projectId: string,
+): Promise<ProjectRecord | null> {
+  const response = await authFetch(
+    `/api/chat/projects/${encodeURIComponent(projectId)}`,
+  );
+  if (response.status === 404) return null;
+  return parseJsonOrThrow<ProjectRecord>(response);
+}
+
+export async function saveChatProject(
+  project: ProjectRecord,
+): Promise<ProjectRecord> {
+  const response = await authFetch("/api/chat/projects", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(project),
+  });
+  const saved = await parseJsonOrThrow<ProjectRecord>(response);
+  notifyChatHistoryUpdated();
+  return saved;
+}
+
+export async function updateChatProject(
+  projectId: string,
+  patch: Partial<ProjectRecord>,
+): Promise<ProjectRecord> {
+  const response = await authFetch(
+    `/api/chat/projects/${encodeURIComponent(projectId)}`,
+    {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(patch),
+    },
+  );
+  const project = await parseJsonOrThrow<ProjectRecord>(response);
+  notifyChatHistoryUpdated();
+  return project;
+}
+
+export async function deleteChatProject(
+  projectId: string,
+  args: { deleteFiles?: boolean } = {},
+): Promise<void> {
+  const params = new URLSearchParams();
+  if (args.deleteFiles) params.set("delete_files", "true");
+  const qs = params.toString();
+  const response = await authFetch(
+    `/api/chat/projects/${encodeURIComponent(projectId)}${qs ? `?${qs}` : ""}`,
+    { method: "DELETE" },
+  );
+  await parseJsonOrThrow<ProjectRecord>(response);
+  notifyChatHistoryUpdated();
+}
+
 export async function listChatMessages(
   threadId: string,
 ): Promise<MessageRecord[]> {
@@ -464,6 +539,7 @@ export async function buildBackendChatExport(): Promise<{
   exportedAt: string;
   version: number;
   threadCount: number;
+  projects?: ProjectRecord[];
   threads: ThreadRecord[];
   messages: MessageRecord[];
 }> {
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index f727b3dfd3..d793b7697b 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -9,13 +9,14 @@ import {
   type ModelOption,
   ModelSelector,
 } from "@/components/assistant-ui/model-selector";
-import { Thread } from "@/components/assistant-ui/thread";
+import { ProjectComposer, Thread } from "@/components/assistant-ui/thread";
 import {
   ResizableHandle,
   ResizablePanel,
   ResizablePanelGroup,
 } from "@/components/ui/resizable";
 import { useSidebar } from "@/components/ui/sidebar";
+import { Button } from "@/components/ui/button";
 import { Tooltip, TooltipContent } from "@/components/ui/tooltip";
 import {
   NativeModelChip,
@@ -29,12 +30,17 @@ import {
 import { GuidedTour, useGuidedTourController } from "@/features/tour";
 import { isTauri } from "@/lib/api-base";
 import { cn } from "@/lib/utils";
-import { CustomizeIcon } from "@hugeicons/core-free-icons";
+import {
+  Folder02Icon,
+  FolderAddIcon,
+  LayoutAlignRightIcon,
+} from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { useNavigate, useSearch } from "@tanstack/react-router";
+import { useNavigate, useRouterState, useSearch } from "@tanstack/react-router";
 import { Tooltip as TooltipPrimitive } from "radix-ui";
 import type { PanelImperativeHandle } from "react-resizable-panels";
 import {
+  type CSSProperties,
   type ReactElement,
   memo,
   useCallback,
@@ -49,12 +55,18 @@ import { ChatSettingsPanel } from "./chat-settings-sheet";
 import { CopyableErrorChip } from "@/components/ui/copyable-error-chip";
 import { ContextUsageBar } from "./components/context-usage-bar";
 import { ModelLoadInlineStatus } from "./components/model-load-status";
+import { ProjectSwitcher } from "./components/project-switcher";
 import {
   buildExternalModelId,
   isExternalModelId,
   parseExternalModelId,
 } from "./external-providers";
 import { useChatModelRuntime } from "./hooks/use-chat-model-runtime";
+import { useChatProjects } from "./hooks/use-chat-projects";
+import {
+  type SidebarItem,
+  useChatSidebarItems,
+} from "./hooks/use-chat-sidebar-items";
 import {
   clearTrainingCompareHandoff,
   getTrainingCompareHandoff,
@@ -181,12 +193,14 @@ const ARTIFACT_SURFACE_POP_DELAY_MS = 150;
 const SingleContent = memo(function SingleContent({
   threadId,
   newThreadNonce,
+  projectId,
   artifact,
   artifactSurface,
   onCloseArtifact,
 }: {
   threadId?: string;
   newThreadNonce?: string;
+  projectId?: string | null;
   artifact?: ChatArtifact | null;
   artifactSurface: ChatArtifactSurface;
   onCloseArtifact: () => void;
@@ -272,6 +286,8 @@ const SingleContent = memo(function SingleContent({
       modelType="base"
       initialThreadId={threadId}
       newThreadNonce={newThreadNonce}
+      projectId={projectId}
+      listThreads={false}
     >
       <ResizablePanelGroup
         orientation="horizontal"
@@ -365,6 +381,7 @@ function useIsLoraCompare(): boolean {
 
 const CompareContent = memo(function CompareContent({
   pairId,
+  projectId,
   models,
   loraModels,
   externalModels,
@@ -373,6 +390,7 @@ const CompareContent = memo(function CompareContent({
   deleteDisabled,
 }: {
   pairId: string;
+  projectId?: string | null;
   models: ModelOption[];
   loraModels: LoraModelOption[];
   externalModels: ExternalModelOption[];
@@ -383,10 +401,11 @@ const CompareContent = memo(function CompareContent({
   const isLoraCompare = useIsLoraCompare();
 
   return isLoraCompare ? (
-    <LoraCompareContent pairId={pairId} />
+    <LoraCompareContent pairId={pairId} projectId={projectId} />
   ) : (
     <GeneralCompareContent
       pairId={pairId}
+      projectId={projectId}
       models={models}
       loraModels={loraModels}
       externalModels={externalModels}
@@ -411,6 +430,7 @@ const CompareContent = memo(function CompareContent({
 function ComparePane({
   modelType,
   pairId,
+  projectId,
   initialThreadId,
   handleName,
   header,
@@ -418,6 +438,7 @@ function ComparePane({
 }: {
   modelType: "base" | "lora" | "model1" | "model2";
   pairId: string;
+  projectId?: string | null;
   initialThreadId: string | undefined;
   handleName: string;
   header: ReactElement;
@@ -435,6 +456,7 @@ function ComparePane({
         <ChatRuntimeProvider
           modelType={modelType}
           pairId={pairId}
+          projectId={projectId}
           initialThreadId={initialThreadId}
           syncActiveThreadId={false}
         >
@@ -490,7 +512,8 @@ function CompareShell({
 /** Fast path: same model, adapter on/off, simultaneous generation. */
 const LoraCompareContent = memo(function LoraCompareContent({
   pairId,
-}: { pairId: string }): ReactElement {
+  projectId,
+}: { pairId: string; projectId?: string | null }): ReactElement {
   const handlesRef = useRef<Record<string, CompareHandle>>({});
   const [baseThreadId, setBaseThreadId] = useState<string>();
   const [loraThreadId, setLoraThreadId] = useState<string>();
@@ -522,6 +545,7 @@ const LoraCompareContent = memo(function LoraCompareContent({
         <ComparePane
           modelType="base"
           pairId={pairId}
+          projectId={projectId}
           initialThreadId={baseThreadId}
           handleName="base"
           header={
@@ -535,6 +559,7 @@ const LoraCompareContent = memo(function LoraCompareContent({
         <ComparePane
           modelType="lora"
           pairId={pairId}
+          projectId={projectId}
           initialThreadId={loraThreadId}
           handleName="lora"
           borderClassName="border-t border-border/60 md:border-t-0 md:border-l"
@@ -607,6 +632,7 @@ function GeneralCompareHeader({
 /** General path: any two models, sequential load → generate. */
 const GeneralCompareContent = memo(function GeneralCompareContent({
   pairId,
+  projectId,
   models,
   loraModels,
   externalModels,
@@ -615,6 +641,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   deleteDisabled,
 }: {
   pairId: string;
+  projectId?: string | null;
   models: ModelOption[];
   loraModels: LoraModelOption[];
   externalModels: ExternalModelOption[];
@@ -692,6 +719,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
         <ComparePane
           modelType="model1"
           pairId={pairId}
+          projectId={projectId}
           initialThreadId={model1ThreadId}
           handleName="model1"
           header={
@@ -717,6 +745,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
         <ComparePane
           modelType="model2"
           pairId={pairId}
+          projectId={projectId}
           initialThreadId={model2ThreadId}
           handleName="model2"
           borderClassName="border-t border-sidebar-border md:border-t-0 md:border-l"
@@ -745,9 +774,248 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   );
 });
 
+function formatProjectChatDate(timestamp: number): string {
+  return new Intl.DateTimeFormat(undefined, {
+    month: "short",
+    day: "numeric",
+  }).format(new Date(timestamp));
+}
+
+function extractMessageText(content: MessageRecord["content"]): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .map((part) => {
+      if (part.type === "text") {
+        return part.text;
+      }
+      if (part.type === "image") {
+        return "Image";
+      }
+      if (part.type === "audio") {
+        return "Audio";
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join(" ");
+}
+
+function ProjectLanding({
+  projectId,
+  projectName,
+  items,
+}: {
+  projectId: string;
+  projectName: string;
+  items: SidebarItem[];
+}): ReactElement {
+  const navigate = useNavigate();
+  const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
+  const initialActiveThreadRef = useRef<string | null>(null);
+  const [projectTab, setProjectTab] = useState<"chats" | "sources">("chats");
+  const [pendingNewThreadId, setPendingNewThreadId] = useState<string | null>(
+    null,
+  );
+  const [newThreadNonce, setNewThreadNonce] = useState(() =>
+    crypto.randomUUID(),
+  );
+  const [previews, setPreviews] = useState<
+    Record<string, { snippet: string; date: string }>
+  >({});
+
+  useEffect(() => {
+    initialActiveThreadRef.current =
+      useChatRuntimeStore.getState().activeThreadId;
+    useChatRuntimeStore.getState().setActiveThreadId(null);
+    useChatRuntimeStore.getState().setContextUsage(null);
+    setPendingNewThreadId(null);
+    setNewThreadNonce(crypto.randomUUID());
+  }, [projectId]);
+
+  useEffect(() => {
+    if (!activeThreadId) {
+      setPendingNewThreadId(null);
+      return;
+    }
+    if (activeThreadId === initialActiveThreadRef.current) {
+      return;
+    }
+    setPendingNewThreadId(activeThreadId);
+  }, [activeThreadId]);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadPreviews(): Promise<void> {
+      const entries = await Promise.all(
+        items.map(async (item) => {
+          if (item.type !== "single") {
+            return [
+              item.id,
+              {
+                snippet: "Compare chat",
+                date: formatProjectChatDate(item.createdAt),
+              },
+            ] as const;
+          }
+          const messages = await listStoredChatMessages(item.id).catch(() => []);
+          const firstUserMessage =
+            messages.find((message) => message.role === "user") ?? messages[0];
+          return [
+            item.id,
+            {
+              snippet: firstUserMessage
+                ? extractMessageText(firstUserMessage.content)
+                : "",
+              date: formatProjectChatDate(item.createdAt),
+            },
+          ] as const;
+        }),
+      );
+      if (!cancelled) {
+        setPreviews(Object.fromEntries(entries));
+      }
+    }
+
+    void loadPreviews();
+    return () => {
+      cancelled = true;
+    };
+  }, [items]);
+
+  return (
+    <ChatRuntimeProvider
+      key={projectId}
+      projectId={projectId}
+      newThreadNonce={newThreadNonce}
+      listThreads={false}
+    >
+      {pendingNewThreadId ? (
+        <div className="flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
+          <Thread hideWelcome={true} targetThreadId={pendingNewThreadId} />
+        </div>
+      ) : (
+        <div
+          className="flex min-h-0 min-w-0 flex-1 basis-0 overflow-y-auto px-5"
+          style={
+            {
+              ["--thread-max-width" as string]: "48rem",
+            } as CSSProperties
+          }
+        >
+          <div className="mx-auto flex w-full max-w-[48rem] flex-col pt-[120px] pb-14">
+            <div className="mb-12 flex items-center gap-3">
+              <HugeiconsIcon
+                icon={Folder02Icon}
+                strokeWidth={1.75}
+                className="size-9 shrink-0 text-foreground"
+              />
+              <h1 className="truncate font-sans text-[30px] font-medium leading-tight tracking-normal text-foreground">
+                {projectName}
+              </h1>
+            </div>
+
+            <ProjectComposer
+              disabled={Boolean(pendingNewThreadId)}
+              placeholder={`New chat in ${projectName}`}
+            />
+
+            <div className="mt-9 flex items-center gap-2">
+              <button
+                type="button"
+                onClick={() => setProjectTab("chats")}
+                data-active={projectTab === "chats"}
+                className="h-10 rounded-full border px-5 text-[14px] font-semibold transition-colors data-[active=true]:border-border data-[active=true]:bg-muted data-[active=true]:text-foreground data-[active=false]:border-transparent data-[active=false]:text-muted-foreground data-[active=false]:hover:bg-nav-surface-hover"
+              >
+                Chats
+              </button>
+              <button
+                type="button"
+                onClick={() => setProjectTab("sources")}
+                data-active={projectTab === "sources"}
+                className="h-10 rounded-full border px-5 text-[14px] font-semibold transition-colors data-[active=true]:border-border data-[active=true]:bg-muted data-[active=true]:text-foreground data-[active=false]:border-transparent data-[active=false]:text-muted-foreground data-[active=false]:hover:bg-nav-surface-hover"
+              >
+                Sources
+              </button>
+            </div>
+
+            {projectTab === "sources" ? (
+              <div className="mt-8 flex flex-col items-center justify-center gap-3 rounded-[16px] border border-dashed border-border/70 bg-muted/30 px-6 py-16 text-center">
+                <span className="flex size-12 items-center justify-center rounded-full bg-muted text-muted-foreground">
+                  <HugeiconsIcon
+                    icon={FolderAddIcon}
+                    strokeWidth={1.75}
+                    className="size-6"
+                  />
+                </span>
+                <div className="space-y-1">
+                  <p className="text-[15px] font-semibold text-foreground">
+                    Give this project context
+                  </p>
+                  <p className="max-w-sm text-sm text-muted-foreground">
+                    Upload PDFs, documents, or other text. The model can
+                    reference them in every chat in this project.
+                  </p>
+                </div>
+                <Button type="button" className="mt-1" disabled>
+                  Add sources
+                </Button>
+                <p className="text-[11px] text-muted-foreground">Coming soon</p>
+              </div>
+            ) : (
+            <div className="mt-8 flex flex-col gap-1">
+              {items.map((item) => {
+                const preview = previews[item.id];
+                return (
+                  <button
+                    key={`${item.type}:${item.id}`}
+                    type="button"
+                    onClick={() => {
+                      navigate({
+                        to: "/chat",
+                        search:
+                          item.type === "single"
+                            ? { thread: item.id, project: projectId }
+                            : { compare: item.id, project: projectId },
+                      });
+                    }}
+                    className="group flex min-h-[58px] w-full items-center gap-4 rounded-[10px] px-4 py-2 text-left transition-colors hover:bg-nav-surface-hover"
+                  >
+                    <div className="min-w-0 flex-1">
+                      <div className="truncate text-[15px] font-semibold leading-5 text-foreground">
+                        {item.title}
+                      </div>
+                      {preview?.snippet ? (
+                        <div className="mt-0.5 truncate text-[14px] leading-5 text-muted-foreground">
+                          {preview.snippet}
+                        </div>
+                      ) : null}
+                    </div>
+                    <span className="shrink-0 text-[14px] text-muted-foreground">
+                      {preview?.date ?? formatProjectChatDate(item.createdAt)}
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+            )}
+          </div>
+        </div>
+      )}
+    </ChatRuntimeProvider>
+  );
+}
+
 export function ChatPage(): ReactElement {
   const search = useSearch({ from: "/chat" });
   const navigate = useNavigate();
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const isCurrentChatRoute = pathname.startsWith("/chat");
 
   const settingsOpen = useChatRuntimeStore((s) => s.settingsPanelOpen);
   const setSettingsOpen = useChatRuntimeStore((s) => s.setSettingsPanelOpen);
@@ -779,7 +1047,9 @@ export function ChatPage(): ReactElement {
         });
         navigate({
           to: "/chat",
-          search: { new: crypto.randomUUID() },
+          search: search.project
+            ? { project: search.project }
+            : { new: crypto.randomUUID() },
           replace: true,
         });
       })
@@ -813,6 +1083,30 @@ export function ChatPage(): ReactElement {
   const clearCheckpoint = useChatRuntimeStore((state) => state.clearCheckpoint);
   const resetArtifacts = useChatArtifactsStore((state) => state.resetArtifacts);
   const activeThreadId = useChatRuntimeStore((state) => state.activeThreadId);
+  const [currentProjectId, setCurrentProjectId] = useState<string | null>(
+    search.project ?? null,
+  );
+  const { projects, isLoading: projectsLoading } = useChatProjects();
+  const currentProject = currentProjectId
+    ? (projects.find((project) => project.id === currentProjectId) ?? null)
+    : null;
+  const { items: currentProjectItems } = useChatSidebarItems({
+    projectId: currentProjectId ?? "__no_project_selected__",
+  });
+  const currentChatTitle = activeThreadId
+    ? currentProjectItems.find((item) => item.id === activeThreadId)?.title
+    : undefined;
+  const openProjectLanding = useCallback(
+    (projectId: string) => {
+      useChatRuntimeStore.getState().setActiveThreadId(null);
+      useChatRuntimeStore.getState().setActiveProjectId(projectId);
+      navigate({ to: "/chat", search: { project: projectId } });
+    },
+    [navigate],
+  );
+  const openProjectsList = useCallback(() => {
+    navigate({ to: "/projects" });
+  }, [navigate]);
   const persistedActiveThreadId = isAssistantLocalThreadId(activeThreadId)
     ? null
     : activeThreadId;
@@ -1053,25 +1347,94 @@ export function ChatPage(): ReactElement {
     return Boolean(inferenceParams.checkpoint) && !isExternalModel;
   }, [inferenceParams.checkpoint, isExternalModel]);
 
+  useEffect(() => {
+    let canceled = false;
+
+    async function resolveProjectId(): Promise<void> {
+      if (search.project) {
+        setCurrentProjectId(search.project);
+        useChatRuntimeStore.getState().setActiveProjectId(search.project);
+        return;
+      }
+
+      if (search.thread) {
+        const thread = await getStoredChatThread(search.thread).catch(() => null);
+        if (!canceled) {
+          const projectId = thread?.projectId ?? null;
+          setCurrentProjectId(projectId);
+          useChatRuntimeStore.getState().setActiveProjectId(projectId);
+        }
+        return;
+      }
+
+      if (search.compare) {
+        const threads = await listStoredChatThreads({
+          pairId: search.compare,
+          includeArchived: true,
+        }).catch(() => []);
+        if (!canceled) {
+          const projectId = threads[0]?.projectId ?? null;
+          setCurrentProjectId(projectId);
+          useChatRuntimeStore.getState().setActiveProjectId(projectId);
+        }
+        return;
+      }
+
+      setCurrentProjectId(null);
+      useChatRuntimeStore.getState().setActiveProjectId(null);
+    }
+
+    void resolveProjectId();
+    return () => {
+      canceled = true;
+    };
+  }, [search.compare, search.project, search.thread]);
+
   // Derive view from URL search params
   const view = useMemo<ChatView>(() => {
     if (search.compare) {
       return {
         mode: "compare",
         pairId: search.compare,
+        projectId: currentProjectId,
       };
     }
     if (search.thread) {
-      return { mode: "single", threadId: search.thread };
-    }
-    if (persistedActiveThreadId) {
-      return { mode: "single", threadId: persistedActiveThreadId };
+      return {
+        mode: "single",
+        threadId: search.thread,
+        projectId: currentProjectId,
+      };
     }
     if (search.new) {
-      return { mode: "single", newThreadNonce: search.new };
+      return {
+        mode: "single",
+        newThreadNonce: search.new,
+        projectId: currentProjectId,
+      };
     }
-    return { mode: "single" };
-  }, [search.thread, search.compare, search.new, persistedActiveThreadId]);
+    if (search.project) {
+      return {
+        mode: "project",
+        projectId: search.project,
+      };
+    }
+    if (persistedActiveThreadId) {
+      return {
+        mode: "single",
+        threadId: persistedActiveThreadId,
+        projectId: currentProjectId,
+      };
+    }
+    return { mode: "single", projectId: currentProjectId };
+  }, [
+    search.thread,
+    search.compare,
+    search.new,
+    search.project,
+    persistedActiveThreadId,
+    currentProjectId,
+  ]);
 
   const selectedArtifact = useSelectedChatArtifact();
   const artifactSurface = useChatArtifactsStore((state) => state.surface);
@@ -1081,7 +1444,9 @@ export function ChatPage(): ReactElement {
   const artifactViewKey =
     view.mode === "single"
       ? `single:${view.threadId ?? view.newThreadNonce ?? "new"}`
-      : `compare:${view.pairId}`;
+      : view.mode === "compare"
+        ? `compare:${view.pairId}`
+        : `project:${view.projectId}`;
 
   useEffect(() => {
     clearAutoOpenedArtifacts();
@@ -1410,8 +1775,14 @@ export function ChatPage(): ReactElement {
     viewBeforeCompareRef.current = { ...search };
     useChatRuntimeStore.getState().setActiveThreadId(null);
     useChatRuntimeStore.getState().setContextUsage(null);
-    navigate({ to: "/chat", search: { compare: crypto.randomUUID() } });
-  }, [navigate, search]);
+    navigate({
+      to: "/chat",
+      search: {
+        compare: crypto.randomUUID(),
+        ...(currentProjectId ? { project: currentProjectId } : {}),
+      },
+    });
+  }, [currentProjectId, navigate, search]);
 
   const exitCompare = useCallback(() => {
     const saved = viewBeforeCompareRef.current;
@@ -1703,11 +2074,25 @@ export function ChatPage(): ReactElement {
       (view.mode === "compare" || artifactSurface === "overlay"),
   );
 
+  if (!isCurrentChatRoute) {
+    return (
+      <div className="flex min-h-0 min-w-0 flex-1 basis-0 bg-background" />
+    );
+  }
+
   return (
     <div className="flex min-h-0 min-w-0 flex-1 basis-0 bg-background overflow-hidden">
       <GuidedTour {...tour.tourProps} />
       <div className="relative flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
         <NativeModelDropOverlay state={nativeModelDropState} />
+        {/* Bottom fade under the top bar so messages dissolve as they scroll
+            beneath it (Gemini / unsloth-sidebar style), instead of a hard cut. */}
+        {view.mode !== "compare" && (
+          <div
+            aria-hidden
+            className="pointer-events-none absolute left-0 right-[10px] top-[48px] z-20 h-6 bg-gradient-to-b from-background to-transparent"
+          />
+        )}
         <div
           className={cn(
             "absolute top-0 left-0 right-[10px] z-30 flex h-[48px] shrink-0 items-start pt-[11px] pr-2 bg-background",
@@ -1739,6 +2124,30 @@ export function ChatPage(): ReactElement {
                 className="max-w-[62vw] !pr-3 sm:max-w-none !h-[34px]"
               />
             )}
+            {view.mode !== "compare" && currentProjectId && (
+              <nav
+                aria-label="Project location"
+                className="flex h-[34px] min-w-0 items-center gap-1.5 self-center text-[13.5px] tracking-nav text-muted-foreground"
+              >
+                <ProjectSwitcher
+                  currentProject={currentProject}
+                  projects={projects}
+                  isLoading={projectsLoading}
+                  onSelectProject={openProjectLanding}
+                  onViewAllProjects={openProjectsList}
+                />
+                {currentProject && activeThreadId ? (
+                  <>
+                    <span className="shrink-0" aria-hidden>
+                      /
+                    </span>
+                    <span className="min-w-0 truncate">
+                      {currentChatTitle ?? "New chat"}
+                    </span>
+                  </>
+                ) : null}
+              </nav>
+            )}
             {pendingNativeModelIntent && view.mode !== "compare" ? (
               <NativeModelChip
                 intent={pendingNativeModelIntent}
@@ -1796,12 +2205,12 @@ export function ChatPage(): ReactElement {
                   <button
                     type="button"
                     onClick={() => setSettingsOpen(true)}
-                    className="flex h-[34px] w-[34px] items-center justify-center rounded-[12px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                    aria-label="Open configuration"
+                    className="flex h-[34px] w-[34px] translate-x-[2px] cursor-pointer items-center justify-center rounded-[12px] text-nav-fg transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    aria-label="Open run settings"
                     data-tour="chat-settings"
                   >
                     <HugeiconsIcon
-                      icon={CustomizeIcon}
+                      icon={LayoutAlignRightIcon}
                       strokeWidth={1.75}
                       className="size-icon"
                     />
@@ -1812,18 +2221,26 @@ export function ChatPage(): ReactElement {
                   sideOffset={6}
                   className="tooltip-compact"
                 >
-                  Open configuration
+                  Open run settings
                 </TooltipContent>
               </Tooltip>
             )}
           </div>
         </div>
 
-        {view.mode === "single" ? (
+        {view.mode === "project" ? (
+          <ProjectLanding
+            key={view.projectId}
+            projectId={view.projectId}
+            projectName={currentProject?.name ?? "Project"}
+            items={currentProjectItems}
+          />
+        ) : view.mode === "single" ? (
           <SingleContent
             key={view.threadId ?? view.newThreadNonce ?? "single"}
             threadId={view.threadId}
             newThreadNonce={view.newThreadNonce}
+            projectId={view.projectId}
             artifact={selectedArtifact}
             artifactSurface={artifactSurface}
             onCloseArtifact={closeArtifactSurface}
@@ -1832,6 +2249,7 @@ export function ChatPage(): ReactElement {
           <CompareContent
             key={view.pairId}
             pairId={view.pairId}
+            projectId={view.projectId}
             models={models}
             loraModels={loraModels}
             externalModels={externalModels}
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index a6e42d18fc..90c2185db3 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -58,7 +58,7 @@ import {
   LayoutAlignRightIcon,
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, ExternalLink } from "lucide-react";
 import { Tooltip as TooltipPrimitive } from "radix-ui";
 import { Fragment, type ReactNode } from "react";
 import { useEffect, useMemo, useRef, useState } from "react";
@@ -324,11 +324,19 @@ function saveCollapsibleOpen(label: string, open: boolean) {
 
 function CollapsibleSection({
   label,
+  labelHref,
   children,
   defaultOpen = false,
   first = false,
 }: {
   label: string;
+  /**
+   * When set, the label text becomes an external link (e.g. to the feature's
+   * GitHub PR) instead of part of the collapse toggle. The chevron still
+   * toggles open/close, so we render the two as siblings rather than nesting
+   * an <a> inside the <button> (invalid HTML).
+   */
+  labelHref?: string;
   children?: ReactNode;
   defaultOpen?: boolean;
   first?: boolean;
@@ -338,6 +346,17 @@ function CollapsibleSection({
     return Object.hasOwn(saved, label) ? saved[label] : defaultOpen;
   });
 
+  const toggle = () => {
+    const next = !open;
+    setOpen(next);
+    saveCollapsibleOpen(label, next);
+  };
+
+  const headerClasses = cn(
+    "flex w-full items-center justify-between text-[12px] font-medium normal-case tracking-[0.04em] text-nav-fg-muted transition-colors focus-visible:outline-none focus-visible:ring-0",
+    first ? "pt-4 pb-5" : "py-5",
+  );
+
   return (
     <div
       className={cn(
@@ -345,25 +364,42 @@ function CollapsibleSection({
           "border-t border-black/[0.13] dark:border-white/[0.09]",
       )}
     >
-      <button
-        type="button"
-        onClick={() => {
-          const next = !open;
-          setOpen(next);
-          saveCollapsibleOpen(label, next);
-        }}
-        className={cn(
-          "flex w-full cursor-pointer items-center justify-between text-[12px] font-medium normal-case tracking-[0.04em] text-nav-fg-muted transition-colors hover:text-nav-fg focus-visible:outline-none focus-visible:ring-0",
-          first ? "pt-4 pb-5" : "py-5",
-        )}
-      >
-        <span className="leading-none">{label}</span>
-        <span className="flex shrink-0 items-center leading-none">
-          <ChevronDown
-            className={cn("size-3.5", open ? "rotate-0" : "-rotate-90")}
-          />
-        </span>
-      </button>
+      {labelHref ? (
+        <div className={headerClasses}>
+          <a
+            href={labelHref}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex cursor-pointer items-center gap-1 leading-none transition-colors hover:text-nav-fg"
+          >
+            <span>{label}</span>
+            <ExternalLink className="size-3" />
+          </a>
+          <button
+            type="button"
+            onClick={toggle}
+            aria-label={open ? `Collapse ${label}` : `Expand ${label}`}
+            className="flex shrink-0 cursor-pointer items-center leading-none transition-colors hover:text-nav-fg"
+          >
+            <ChevronDown
+              className={cn("size-3.5", open ? "rotate-0" : "-rotate-90")}
+            />
+          </button>
+        </div>
+      ) : (
+        <button
+          type="button"
+          onClick={toggle}
+          className={cn("cursor-pointer hover:text-nav-fg", headerClasses)}
+        >
+          <span className="leading-none">{label}</span>
+          <span className="flex shrink-0 items-center leading-none">
+            <ChevronDown
+              className={cn("size-3.5", open ? "rotate-0" : "-rotate-90")}
+            />
+          </span>
+        </button>
+      )}
       {open && <div className="pb-7">{children}</div>}
     </div>
   );
@@ -683,26 +719,31 @@ export function ChatSettingsPanel({
     }
   }, [open]);
 
+  const settingsScrollRef = useRef<HTMLDivElement>(null);
+
   const settingsContent = (
     <>
-      <div className="aui-thread-viewport relative h-full overflow-y-auto">
-      <div className="sticky top-0 z-10 flex h-[48px] items-start gap-2 bg-panel-surface pl-[18px] pr-[14px] pt-[11px]">
+      <div
+        ref={settingsScrollRef}
+        className="relative h-full overflow-y-auto"
+      >
+      <div className="sticky top-0 z-10 flex h-[48px] items-start gap-2 bg-panel-surface pl-[18px] pr-[16px] pt-[11px]">
         {isMobile ? (
-          <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[-0.01em] dark:tracking-[0.015em] text-nav-fg">
-            Configuration
+          <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
+            Run settings
           </span>
         ) : (
           <>
-            <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[-0.01em] dark:tracking-[0.015em] text-nav-fg">
-              Configuration
+            <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
+              Run settings
             </span>
             <Tooltip>
               <TooltipPrimitive.Trigger asChild>
                 <button
                   type="button"
                   onClick={() => onOpenChange?.(false)}
-                  className="flex h-[34px] w-[34px] items-center justify-center rounded-[12px] text-nav-icon-idle dark:text-nav-fg-muted transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  aria-label="Close configuration"
+                  className="flex h-[34px] w-[34px] cursor-pointer items-center justify-center rounded-[12px] text-nav-icon-idle dark:text-nav-fg-muted transition-colors hover:bg-nav-surface-hover hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  aria-label="Close run settings"
                 >
                   <HugeiconsIcon
                     icon={LayoutAlignRightIcon}
@@ -716,7 +757,7 @@ export function ChatSettingsPanel({
                 sideOffset={6}
                 className="tooltip-compact"
               >
-                Close configuration
+                Close run settings
               </TooltipContent>
             </Tooltip>
           </>
@@ -1395,7 +1436,7 @@ export function ChatSettingsPanel({
       <Sheet open={open} onOpenChange={onOpenChange}>
         <SheetContent side="right" className="w-[18rem] p-0 font-heading">
           <SheetHeader className="sr-only">
-            <SheetTitle>Configuration</SheetTitle>
+            <SheetTitle>Run settings</SheetTitle>
             <SheetDescription>Chat inference settings</SheetDescription>
           </SheetHeader>
           <div className="flex h-full flex-col">{settingsContent}</div>
diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index eca3b4bd9f..85480359b4 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -8,7 +8,6 @@ import {
   CommandGroup,
   CommandList,
 } from "@/components/ui/command";
-import { useTrainingRuntimeStore } from "@/features/training";
 import { Cancel01Icon, Message01Icon, SearchIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useNavigate } from "@tanstack/react-router";
@@ -36,7 +35,6 @@ export function ChatSearchDialog() {
   useEffect(() => {
     const handler = (e: KeyboardEvent) => {
       if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== "k") return;
-      if (useTrainingRuntimeStore.getState().isTrainingRunning) return;
       const el = document.activeElement as HTMLElement | null;
       const tag = el?.tagName;
       if (tag === "INPUT" || tag === "TEXTAREA" || el?.isContentEditable) return;
@@ -51,10 +49,10 @@ export function ChatSearchDialog() {
     <CommandDialog
       open={isOpen}
       onOpenChange={setOpen}
-      className="shadow-border corner-squircle w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px]"
+      className="corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px] border-0 ring-0 shadow-[0_10px_34px_rgba(0,0,0,0.12)] dark:border dark:border-border dark:ring-0 dark:shadow-none"
       overlayClassName="bg-transparent"
     >
-      <Command className="rounded-none p-0">
+      <Command className="rounded-4xl p-0">
         <div className="flex items-center gap-3 border-b border-border/40 px-4 py-3">
           <HugeiconsIcon
             icon={SearchIcon}
@@ -74,7 +72,7 @@ export function ChatSearchDialog() {
             <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="size-4" />
           </button>
         </div>
-        <CommandList className="max-h-[420px] p-1">
+        <CommandList className="cmd-native-scrollbar max-h-[420px] p-1">
           <CommandEmpty className="py-6 text-center text-xs text-muted-foreground">
             {loading
               ? "Loading…"
@@ -92,12 +90,18 @@ export function ChatSearchDialog() {
                     to: "/chat",
                     search:
                       item.type === "single"
-                        ? { thread: item.id }
-                        : { compare: item.id },
+                        ? {
+                            thread: item.id,
+                            ...(item.projectId ? { project: item.projectId } : {}),
+                          }
+                        : {
+                            compare: item.id,
+                            ...(item.projectId ? { project: item.projectId } : {}),
+                          },
                   });
                   close();
                 }}
-                className="relative flex cursor-default select-none items-center gap-3 rounded-lg px-3 py-2.5 text-sm outline-hidden data-selected:bg-muted data-selected:text-foreground"
+                className="relative flex cursor-pointer select-none items-center gap-3 rounded-lg px-3 py-2.5 text-sm outline-hidden data-selected:bg-muted data-selected:text-foreground"
               >
                 <HugeiconsIcon
                   icon={Message01Icon}
diff --git a/studio/frontend/src/features/chat/components/project-switcher.tsx b/studio/frontend/src/features/chat/components/project-switcher.tsx
new file mode 100644
index 0000000000..3deaf4701d
--- /dev/null
+++ b/studio/frontend/src/features/chat/components/project-switcher.tsx
@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  ArrowDown01Icon,
+  Folder01Icon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { ReactElement } from "react";
+import type { ProjectRecord } from "../types";
+
+export function ProjectSwitcher({
+  currentProject,
+  projects,
+  isLoading,
+  onSelectProject,
+  onViewAllProjects,
+}: {
+  currentProject: ProjectRecord | null;
+  projects: ProjectRecord[];
+  isLoading: boolean;
+  onSelectProject: (projectId: string) => void;
+  onViewAllProjects: () => void;
+}): ReactElement {
+  const showLoadingRow = isLoading && projects.length === 0;
+  const showEmptyRow = !isLoading && projects.length === 0;
+  const label = currentProject?.name ?? (isLoading ? "Project" : "Projects");
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild={true}>
+        <button
+          type="button"
+          aria-label={
+            currentProject
+              ? `Project: ${currentProject.name}. Switch project`
+              : isLoading
+                ? "Loading project"
+                : "Pick a project"
+          }
+          className="-mx-1 flex h-[34px] shrink-0 items-center gap-2 rounded-[10px] px-1.5 transition-colors hover:bg-[#ececec] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring dark:hover:bg-[#2d2e32]"
+        >
+          <HugeiconsIcon
+            icon={Folder01Icon}
+            strokeWidth={1.75}
+            className="size-icon shrink-0 text-foreground/70"
+          />
+          <span className="flex min-w-0 flex-1 items-baseline">
+            <span className="min-w-0 flex max-w-[150px] flex-1 items-baseline truncate font-heading text-[16px] font-medium leading-tight text-black dark:text-white">
+              {label}
+            </span>
+          </span>
+          <span className="flex size-4 shrink-0 items-center justify-center">
+            <HugeiconsIcon
+              icon={ArrowDown01Icon}
+              strokeWidth={1.75}
+              className="relative top-0.5 size-3.5 text-muted-foreground"
+              aria-hidden={true}
+            />
+          </span>
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        side="bottom"
+        align="start"
+        sideOffset={6}
+        className="app-user-menu menu-soft-surface ring-0 min-w-56 max-w-72 max-h-72 py-2 font-heading rounded-[14px] border-0"
+      >
+        {showLoadingRow ? (
+          <DropdownMenuItem disabled={true} className="text-muted-foreground">
+            Loading…
+          </DropdownMenuItem>
+        ) : null}
+        {showEmptyRow ? (
+          <DropdownMenuItem disabled={true} className="text-muted-foreground">
+            No projects yet
+          </DropdownMenuItem>
+        ) : null}
+        {projects.map((project) => {
+          const isActive = currentProject?.id === project.id;
+          return (
+            <DropdownMenuItem
+              key={project.id}
+              onSelect={() => onSelectProject(project.id)}
+              className="justify-between"
+            >
+              <span className="flex min-w-0 items-center gap-2">
+                <HugeiconsIcon
+                  icon={Folder01Icon}
+                  strokeWidth={1.75}
+                  className="size-icon shrink-0 text-foreground/70"
+                />
+                <span className="truncate">{project.name}</span>
+              </span>
+              {isActive ? (
+                <HugeiconsIcon
+                  icon={Tick02Icon}
+                  strokeWidth={2}
+                  className="size-icon shrink-0 text-foreground/80"
+                />
+              ) : null}
+            </DropdownMenuItem>
+          );
+        })}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onSelect={onViewAllProjects}>
+          View all projects
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-projects.ts b/studio/frontend/src/features/chat/hooks/use-chat-projects.ts
new file mode 100644
index 0000000000..fe0dfa9e65
--- /dev/null
+++ b/studio/frontend/src/features/chat/hooks/use-chat-projects.ts
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useEffect, useState } from "react";
+import { CHAT_HISTORY_UPDATED_EVENT } from "../api/chat-api";
+import type { ProjectRecord } from "../types";
+import {
+  createStoredChatProject,
+  deleteStoredChatProject,
+  isExpectedBackgroundChatStorageError,
+  listStoredChatProjects,
+  moveStoredChatItemToProject,
+  updateStoredChatProject,
+} from "../utils/chat-history-storage";
+import type { SidebarItem } from "./use-chat-sidebar-items";
+
+let cachedProjects: ProjectRecord[] = [];
+
+export function useChatProjects(): {
+  projects: ProjectRecord[];
+  isLoading: boolean;
+  hasLoaded: boolean;
+} {
+  const [projects, setProjects] = useState<ProjectRecord[]>(cachedProjects);
+  const [isLoading, setIsLoading] = useState(cachedProjects.length === 0);
+  const [hasLoaded, setHasLoaded] = useState(cachedProjects.length > 0);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      if (!cancelled) setIsLoading(true);
+      try {
+        const next = await listStoredChatProjects({ includeArchived: false });
+        cachedProjects = next;
+        if (!cancelled) setProjects(next);
+      } catch (error) {
+        if (isExpectedBackgroundChatStorageError(error)) {
+          return;
+        }
+        if (!cancelled) throw error;
+      } finally {
+        if (!cancelled) {
+          setHasLoaded(true);
+          setIsLoading(false);
+        }
+      }
+    }
+
+    const onHistoryUpdated = () => {
+      void load();
+    };
+
+    void load();
+    window.addEventListener(CHAT_HISTORY_UPDATED_EVENT, onHistoryUpdated);
+    return () => {
+      cancelled = true;
+      window.removeEventListener(CHAT_HISTORY_UPDATED_EVENT, onHistoryUpdated);
+    };
+  }, []);
+
+  return { projects, isLoading, hasLoaded };
+}
+
+export async function createChatProject(name: string): Promise<ProjectRecord> {
+  return createStoredChatProject(name);
+}
+
+export async function renameChatProject(
+  projectId: string,
+  name: string,
+): Promise<void> {
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error("Project name is required.");
+  await updateStoredChatProject(projectId, { name: trimmed });
+}
+
+export async function updateChatProjectInstructions(
+  projectId: string,
+  instructions: string,
+): Promise<void> {
+  await updateStoredChatProject(projectId, { instructions: instructions.trim() });
+}
+
+export async function deleteChatProject(
+  projectId: string,
+  args: { deleteFiles?: boolean } = {},
+): Promise<void> {
+  await deleteStoredChatProject(projectId, args);
+}
+
+export async function moveChatItemToProject(
+  item: SidebarItem,
+  projectId: string | null,
+): Promise<void> {
+  await moveStoredChatItemToProject(item, projectId);
+}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts b/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
index 9fecf99986..f8e1535e04 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
@@ -2,7 +2,7 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { useEffect, useRef, useState } from "react";
-import { CHAT_HISTORY_UPDATED_EVENT } from "../api/chat-api";
+import { batchListChatMessages, CHAT_HISTORY_UPDATED_EVENT } from "../api/chat-api";
 import type { MessageRecord } from "../types";
 import {
   listStoredChatMessages,
@@ -15,6 +15,7 @@ export interface ChatSearchItem {
   title: string;
   preview: string;
   createdAt: number;
+  projectId?: string | null;
 }
 
 const THREAD_LIMIT = 200;
@@ -68,6 +69,7 @@ async function buildIndex(): Promise<ChatSearchItem[]> {
           id: t.pairId,
           title: t.title,
           createdAt: t.createdAt,
+          projectId: t.projectId ?? null,
         },
         threadIds: [t.id],
       });
@@ -78,6 +80,7 @@ async function buildIndex(): Promise<ChatSearchItem[]> {
           id: t.id,
           title: t.title,
           createdAt: t.createdAt,
+          projectId: t.projectId ?? null,
         },
         threadIds: [t.id],
       });
@@ -87,26 +90,34 @@ async function buildIndex(): Promise<ChatSearchItem[]> {
   const allThreadIds = Array.from(itemThreadIds.values()).flatMap(
     (e) => e.threadIds,
   );
-  const storedMessagesByThread = await Promise.all(
-    allThreadIds.map(async (threadId) => ({
-      threadId,
-      messages: await listStoredChatMessages(threadId),
-    })),
+  let messagesByThread = await batchListChatMessages(allThreadIds).catch(
+    () => new Map<string, MessageRecord[]>(),
   );
-  const messages = storedMessagesByThread.flatMap((entry) => entry.messages);
 
-  const byThreadId = new Map<string, MessageRecord[]>();
-  for (const m of messages) {
-    const arr = byThreadId.get(m.threadId);
-    if (arr) arr.push(m);
-    else byThreadId.set(m.threadId, [m]);
+  // Legacy-only chats can exist before server-side history import finishes.
+  // Fill just the missing ids from the legacy-aware path instead of issuing
+  // one request per thread up front.
+  const missingThreadIds = allThreadIds.filter(
+    (threadId) => !messagesByThread.has(threadId),
+  );
+  if (missingThreadIds.length > 0) {
+    const legacyEntries = await Promise.all(
+      missingThreadIds.map(async (threadId) => [
+        threadId,
+        await listStoredChatMessages(threadId).catch(() => []),
+      ] as const),
+    );
+    messagesByThread = new Map(messagesByThread);
+    for (const [threadId, messages] of legacyEntries) {
+      messagesByThread.set(threadId, messages);
+    }
   }
 
   const results: ChatSearchItem[] = [];
   for (const { item, threadIds } of itemThreadIds.values()) {
     const merged: MessageRecord[] = [];
     for (const tid of threadIds) {
-      const arr = byThreadId.get(tid);
+      const arr = messagesByThread.get(tid);
       if (arr) merged.push(...arr);
     }
     if (merged.length === 0) {
@@ -141,6 +152,7 @@ export function useChatSearchIndex(enabled: boolean): {
     if (!enabled) {
       // Clear stale results so the next open doesn't flash old items.
       setItems([]);
+      setLoading(false);
       return;
     }
     let cancelled = false;
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
index 87a32dcd36..54aa5d82dc 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
@@ -24,6 +24,7 @@ export interface SidebarItem {
   id: string;
   title: string;
   createdAt: number;
+  projectId?: string | null;
 }
 
 export function groupThreads(threads: ThreadRecord[]): SidebarItem[] {
@@ -44,6 +45,7 @@ export function groupThreads(threads: ThreadRecord[]): SidebarItem[] {
         id: t.pairId,
         title: t.title,
         createdAt: t.createdAt,
+        projectId: t.projectId ?? null,
       });
     } else if (!t.pairId) {
       items.push({
@@ -51,6 +53,7 @@ export function groupThreads(threads: ThreadRecord[]): SidebarItem[] {
         id: t.id,
         title: t.title,
         createdAt: t.createdAt,
+        projectId: t.projectId ?? null,
       });
     }
   }
@@ -63,18 +66,32 @@ export function groupThreads(threads: ThreadRecord[]): SidebarItem[] {
 // discards stale responses.
 const SIDEBAR_REFRESH_DEBOUNCE_MS = 300;
 
-export function useChatSidebarItems() {
+export function useChatSidebarItems(options?: {
+  projectId?: string | null;
+  enabled?: boolean;
+  requireMessages?: boolean;
+}) {
   const [allThreads, setAllThreads] = useState<ThreadRecord[]>([]);
+  const enabled = options?.enabled ?? true;
+  const requireMessages = options?.requireMessages ?? true;
 
   useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
     let cancelled = false;
     let pendingTimer: ReturnType<typeof setTimeout> | null = null;
     let requestSeq = 0;
 
     async function doLoad(seq: number) {
       try {
-        const threads = await listStoredChatThreadsWithMessages({
+        const listThreads = requireMessages
+          ? listStoredChatThreadsWithMessages
+          : listStoredChatThreads;
+        const threads = await listThreads({
           includeArchived: false,
+          projectId: options?.projectId,
         });
         // Discard the response if a newer request was scheduled while we
         // were in flight, or if the effect was torn down.
@@ -107,7 +124,7 @@ export function useChatSidebarItems() {
       if (pendingTimer !== null) clearTimeout(pendingTimer);
       window.removeEventListener(CHAT_HISTORY_UPDATED_EVENT, load);
     };
-  }, []);
+  }, [enabled, options?.projectId, requireMessages]);
 
   const items = groupThreads(allThreads ?? []);
   const canCompare = useChatRuntimeStore((s) => Boolean(s.params.checkpoint));
diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.ts
index 063def91ae..ac05c8c089 100644
--- a/studio/frontend/src/features/chat/index.ts
+++ b/studio/frontend/src/features/chat/index.ts
@@ -21,6 +21,7 @@ export { useChatSearchStore } from "./stores/chat-search-store";
 export { useChatModelRuntime } from "./hooks/use-chat-model-runtime";
 export { ChatSearchDialog } from "./components/chat-search-dialog";
 export { setTrainingCompareHandoff } from "./lib/training-compare-handoff";
+export type { ProjectRecord } from "./types";
 export { clearAllChats, countAllChats } from "./utils/clear-all-chats";
 export { ArtifactCard } from "./artifacts/artifact-card";
 export {
@@ -34,3 +35,11 @@ export {
   useChatSidebarItems,
   type SidebarItem,
 } from "./hooks/use-chat-sidebar-items";
+export {
+  createChatProject,
+  deleteChatProject,
+  moveChatItemToProject,
+  renameChatProject,
+  updateChatProjectInstructions,
+  useChatProjects,
+} from "./hooks/use-chat-projects";
diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsx
new file mode 100644
index 0000000000..8c92526b63
--- /dev/null
+++ b/studio/frontend/src/features/chat/projects-page.tsx
@@ -0,0 +1,401 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Input } from "@/components/ui/input";
+import { Skeleton } from "@/components/ui/skeleton";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { toast } from "@/lib/toast";
+import {
+  createChatProject,
+  deleteChatProject,
+  renameChatProject,
+  useChatProjects,
+  useChatRuntimeStore,
+  type ProjectRecord,
+} from "@/features/chat";
+import {
+  Delete02Icon,
+  Edit03Icon,
+  FolderAddIcon,
+  Search01Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { MoreHorizontalIcon } from "lucide-react";
+import { useNavigate } from "@tanstack/react-router";
+import { useMemo, useState } from "react";
+
+type SortMode = "activity" | "name";
+
+function formatUpdatedAgo(ts: number): string {
+  const diff = Date.now() - ts;
+  if (!Number.isFinite(diff) || diff < 0) return "just now";
+  const s = Math.floor(diff / 1000);
+  if (s < 60) return "just now";
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m} minute${m === 1 ? "" : "s"} ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h} hour${h === 1 ? "" : "s"} ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d} day${d === 1 ? "" : "s"} ago`;
+  const mo = Math.floor(d / 30);
+  if (mo < 12) return `${mo} month${mo === 1 ? "" : "s"} ago`;
+  const y = Math.floor(mo / 12);
+  return `${y} year${y === 1 ? "" : "s"} ago`;
+}
+
+export function ProjectsPage() {
+  const navigate = useNavigate();
+  const { projects, hasLoaded } = useChatProjects();
+
+  const [query, setQuery] = useState("");
+  const [sortMode, setSortMode] = useState<SortMode>("activity");
+
+  const [creating, setCreating] = useState(false);
+  const [nameDraft, setNameDraft] = useState("");
+  const [renaming, setRenaming] = useState<ProjectRecord | null>(null);
+  const [renameDraft, setRenameDraft] = useState("");
+  const [deleting, setDeleting] = useState<ProjectRecord | null>(null);
+
+  const visibleProjects = useMemo(() => {
+    const trimmed = query.trim().toLowerCase();
+    const filtered = trimmed
+      ? projects.filter((p) => p.name.toLowerCase().includes(trimmed))
+      : projects.slice();
+    filtered.sort((a, b) =>
+      sortMode === "name"
+        ? a.name.localeCompare(b.name)
+        : b.updatedAt - a.updatedAt,
+    );
+    return filtered;
+  }, [projects, query, sortMode]);
+
+  function openProject(projectId: string) {
+    const runtime = useChatRuntimeStore.getState();
+    runtime.setActiveThreadId(null);
+    runtime.setActiveProjectId(projectId);
+    navigate({ to: "/chat", search: { project: projectId } });
+  }
+
+  async function commitCreate() {
+    const name = nameDraft.trim();
+    if (!name) return;
+    try {
+      const project = await createChatProject(name);
+      setCreating(false);
+      setNameDraft("");
+      openProject(project.id);
+    } catch (err) {
+      toast.error("Failed to create project", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  async function commitRename() {
+    const target = renaming;
+    const name = renameDraft.trim();
+    if (!target || !name || name === target.name) {
+      setRenaming(null);
+      return;
+    }
+    setRenaming(null);
+    try {
+      await renameChatProject(target.id, name);
+    } catch (err) {
+      toast.error("Failed to rename project", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  async function commitDelete() {
+    const target = deleting;
+    if (!target) return;
+    setDeleting(null);
+    try {
+      await deleteChatProject(target.id);
+    } catch (err) {
+      toast.error("Failed to delete project", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  return (
+    <main className="mx-auto w-full max-w-7xl px-4 py-8 font-heading sm:px-6">
+      <div className="flex flex-wrap items-center justify-between gap-4">
+        <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+          Projects
+        </h1>
+        <div className="flex items-center gap-3">
+          <div className="flex items-center gap-2">
+            <span className="text-sm text-muted-foreground">Sort by</span>
+            <Select
+              value={sortMode}
+              onValueChange={(v) => setSortMode(v as SortMode)}
+            >
+              <SelectTrigger className="h-9 w-[130px]">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="activity">Activity</SelectItem>
+                <SelectItem value="name">Name</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+          <Button
+            onClick={() => {
+              setNameDraft("");
+              setCreating(true);
+            }}
+          >
+            New project
+          </Button>
+        </div>
+      </div>
+
+      <div className="relative mt-6">
+        <span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground">
+          <HugeiconsIcon icon={Search01Icon} strokeWidth={1.75} className="size-icon" />
+        </span>
+        <Input
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Search projects..."
+          className="h-11 pl-10"
+          aria-label="Search projects"
+        />
+      </div>
+
+      {!hasLoaded ? (
+        <div className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {Array.from({ length: 6 }).map((_, index) => (
+            <div
+              key={index}
+              className="min-h-[160px] rounded-[14px] border border-border/70 bg-card p-5"
+            >
+              <Skeleton className="h-5 w-2/3 rounded-[6px]" />
+              <Skeleton className="mt-3 h-4 w-full rounded-[6px]" />
+              <Skeleton className="mt-2 h-4 w-4/5 rounded-[6px]" />
+              <Skeleton className="mt-12 h-3 w-24 rounded-[6px]" />
+            </div>
+          ))}
+        </div>
+      ) : visibleProjects.length === 0 ? (
+        <div className="mt-16 flex flex-col items-center justify-center gap-2 text-center text-muted-foreground">
+          <p className="text-sm">
+            {projects.length === 0
+              ? "No projects yet."
+              : "No projects match your search."}
+          </p>
+          {projects.length === 0 && (
+            <Button
+              variant="outline"
+              className="mt-2"
+              onClick={() => {
+                setNameDraft("");
+                setCreating(true);
+              }}
+            >
+              <HugeiconsIcon icon={FolderAddIcon} strokeWidth={1.75} className="size-icon" />
+              Create your first project
+            </Button>
+          )}
+        </div>
+      ) : (
+        <div className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {visibleProjects.map((project) => (
+            <div
+              key={project.id}
+              role="button"
+              tabIndex={0}
+              onClick={() => openProject(project.id)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" || e.key === " ") {
+                  e.preventDefault();
+                  openProject(project.id);
+                }
+              }}
+              className="group/project-card relative flex min-h-[160px] cursor-pointer flex-col rounded-[14px] border border-border/70 bg-card p-5 text-left transition-colors hover:border-border hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <div className="flex items-start justify-between gap-2">
+                <h2 className="truncate pr-2 text-[16px] font-semibold text-foreground">
+                  {project.name}
+                </h2>
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <button
+                      type="button"
+                      onClick={(e) => e.stopPropagation()}
+                      aria-label="Project options"
+                      className="-mr-1 -mt-1 inline-flex size-7 shrink-0 items-center justify-center rounded-[8px] text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground focus-visible:opacity-100 group-hover/project-card:opacity-100"
+                    >
+                      <MoreHorizontalIcon strokeWidth={1.75} className="size-icon" />
+                    </button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent
+                    side="bottom"
+                    align="end"
+                    sideOffset={4}
+                    onClick={(e) => e.stopPropagation()}
+                    onKeyDown={(e) => e.stopPropagation()}
+                    className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
+                  >
+                    <DropdownMenuItem
+                      onSelect={() => {
+                        setRenameDraft(project.name);
+                        setRenaming(project);
+                      }}
+                    >
+                      <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
+                      <span>Rename</span>
+                    </DropdownMenuItem>
+                    <DropdownMenuItem
+                      variant="destructive"
+                      onSelect={() => setDeleting(project)}
+                    >
+                      <HugeiconsIcon icon={Delete02Icon} strokeWidth={1.75} className="size-icon" />
+                      <span>Delete</span>
+                    </DropdownMenuItem>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </div>
+              {project.instructions ? (
+                <p className="mt-2 line-clamp-3 text-sm text-muted-foreground">
+                  {project.instructions}
+                </p>
+              ) : null}
+              <span className="mt-auto pt-4 text-xs text-muted-foreground">
+                Updated {formatUpdatedAgo(project.updatedAt)}
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Create project */}
+      <Dialog
+        open={creating}
+        onOpenChange={(open) => {
+          if (!open) setCreating(false);
+        }}
+      >
+        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>New project</DialogTitle>
+          </DialogHeader>
+          <Input
+            value={nameDraft}
+            onChange={(e) => setNameDraft(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") {
+                e.preventDefault();
+                void commitCreate();
+              }
+            }}
+            autoFocus
+            maxLength={120}
+            placeholder="Project name"
+            aria-label="Project name"
+            className="focus-visible:border-input focus-visible:ring-0"
+          />
+          <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+            <Button type="button" variant="ghost" onClick={() => setCreating(false)}>
+              Cancel
+            </Button>
+            <Button type="button" onClick={() => void commitCreate()} disabled={!nameDraft.trim()}>
+              Create
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Rename project */}
+      <Dialog
+        open={renaming !== null}
+        onOpenChange={(open) => {
+          if (!open) setRenaming(null);
+        }}
+      >
+        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Rename project</DialogTitle>
+          </DialogHeader>
+          <Input
+            value={renameDraft}
+            onChange={(e) => setRenameDraft(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") {
+                e.preventDefault();
+                void commitRename();
+              }
+            }}
+            autoFocus
+            maxLength={120}
+            placeholder="Project name"
+            aria-label="Project name"
+            className="focus-visible:border-input focus-visible:ring-0"
+          />
+          <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+            <Button type="button" variant="ghost" onClick={() => setRenaming(null)}>
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              onClick={() => void commitRename()}
+              disabled={!renameDraft.trim() || renameDraft.trim() === renaming?.name}
+            >
+              Save
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Delete project */}
+      <Dialog
+        open={deleting !== null}
+        onOpenChange={(open) => {
+          if (!open) setDeleting(null);
+        }}
+      >
+        <DialogContent className="menu-flat-destructive corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Delete project</DialogTitle>
+          </DialogHeader>
+          <p className="text-sm text-muted-foreground">
+            Are you sure you want to delete <em>{deleting?.name}</em>? Chats in this
+            project will be moved back to Recents.
+          </p>
+          <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+            <Button type="button" variant="ghost" onClick={() => setDeleting(null)}>
+              Cancel
+            </Button>
+            <Button type="button" variant="destructive" onClick={() => void commitDelete()}>
+              Delete
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </main>
+  );
+}
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 21be5f6e3e..32b591d880 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -66,6 +66,7 @@ import { syncExportedRepositoryToBackend } from "./utils/delete-thread-message";
 import { getImageInputUnavailableReason } from "./utils/image-input-support";
 
 const pendingHistoryAppendByMessageId = new Map<string, Promise<void>>();
+const pendingRunStartReadyByMessageId = new Map<string, Promise<void>>();
 
 type TitleResponse = {
   choices?: Array<{
@@ -534,10 +535,12 @@ export async function ensureThreadRecord({
   threadId,
   modelType,
   pairId,
+  projectId,
 }: {
   threadId: string;
   modelType: ModelType;
   pairId?: string;
+  projectId?: string | null;
 }): Promise<void> {
   if (isChatThreadDeleted(threadId)) {
     return;
@@ -556,6 +559,7 @@ export async function ensureThreadRecord({
     modelType,
     modelId: currentModelId,
     pairId,
+    projectId: projectId ?? null,
     archived: false,
     createdAt: Date.now(),
   };
@@ -579,6 +583,8 @@ export async function ensureThreadRecord({
 function createStudioDbAdapter(
   modelType: ModelType,
   pairId?: string,
+  projectId?: string | null,
+  listThreads = true,
 ): unstable_RemoteThreadListAdapter {
   return {
     async fetch(remoteId: string) {
@@ -594,9 +600,16 @@ function createStudioDbAdapter(
     },
 
     async list() {
+      if (!listThreads) {
+        return { threads: [] };
+      }
       let threads: ThreadRecord[];
       try {
-        threads = await listStoredChatThreads({ modelType, pairId });
+        threads = await listStoredChatThreads({
+          modelType,
+          pairId,
+          ...(projectId !== undefined ? { projectId } : {}),
+        });
       } catch (error) {
         if (!isExpectedBackgroundChatStorageError(error)) {
           throw error;
@@ -615,7 +628,7 @@ function createStudioDbAdapter(
     },
 
     async initialize(threadId: string) {
-      await ensureThreadRecord({ threadId, modelType, pairId });
+      await ensureThreadRecord({ threadId, modelType, pairId, projectId });
       return { remoteId: threadId, externalId: undefined };
     },
 
@@ -696,7 +709,7 @@ function createStudioDbAdapter(
           const running = useChatRuntimeStore.getState().runningByThreadId;
           if (running[paired.id]) {
             setTimeout(() => {
-              void createStudioDbAdapter(modelType, pairId).generateTitle(
+              void createStudioDbAdapter(modelType, pairId, projectId).generateTitle(
                 remoteId,
                 messages,
               );
@@ -740,6 +753,22 @@ function trackHistoryAppend(
   return write;
 }
 
+function trackRunStartReady(
+  messageId: string,
+  ready: Promise<void>,
+): Promise<void> {
+  pendingRunStartReadyByMessageId.set(messageId, ready);
+  const cleanup = () => {
+    setTimeout(() => {
+      if (pendingRunStartReadyByMessageId.get(messageId) === ready) {
+        pendingRunStartReadyByMessageId.delete(messageId);
+      }
+    }, 30_000);
+  };
+  ready.then(cleanup, cleanup);
+  return ready;
+}
+
 async function waitForRunStartHistoryAppend(
   messages: Parameters<ChatModelAdapter["run"]>[0]["messages"],
 ): Promise<void> {
@@ -747,20 +776,22 @@ async function waitForRunStartHistoryAppend(
   if (!lastMessage || lastMessage.role !== "user") {
     return;
   }
-  const write = pendingHistoryAppendByMessageId.get(lastMessage.id);
-  if (!write) {
+  const ready =
+    pendingRunStartReadyByMessageId.get(lastMessage.id) ??
+    pendingHistoryAppendByMessageId.get(lastMessage.id);
+  if (!ready) {
     return;
   }
-  let didPersist = false;
+  let didBecomeReady = false;
   try {
-    await write;
-    didPersist = true;
+    await ready;
+    didBecomeReady = true;
   } finally {
     if (
-      didPersist &&
-      pendingHistoryAppendByMessageId.get(lastMessage.id) === write
+      didBecomeReady &&
+      pendingRunStartReadyByMessageId.get(lastMessage.id) === ready
     ) {
-      pendingHistoryAppendByMessageId.delete(lastMessage.id);
+      pendingRunStartReadyByMessageId.delete(lastMessage.id);
     }
   }
 }
@@ -783,7 +814,10 @@ function createPersistedRunAdapter(adapter: ChatModelAdapter): ChatModelAdapter
   };
 }
 
-function useStudioRuntimeAdapters(): StudioRuntimeAdapters {
+function useStudioRuntimeAdapters(
+  modelType: ModelType,
+  pairId?: string,
+): StudioRuntimeAdapters {
   const aui = useAui();
 
   const history = useMemo<ThreadHistoryAdapter>(
@@ -871,14 +905,22 @@ function useStudioRuntimeAdapters(): StudioRuntimeAdapters {
       },
 
       append({ parentId, message }: ExportedMessageRepositoryItem) {
+        const initializeThread = aui.threadListItem().initialize();
+        trackRunStartReady(message.id, initializeThread.then(() => undefined));
         const write = (async () => {
-          const { remoteId } = await aui.threadListItem().initialize();
+          const { remoteId } = await initializeThread;
           if (isChatThreadDeleted(remoteId)) {
             await deleteStoredChatThreads([remoteId]);
             return;
           }
           // Keep single-chat runtime state in sync once a new chat is first
           // persisted. Compare panes intentionally do not write global activeThreadId.
+          if (modelType === "base" && !pairId) {
+            const store = useChatRuntimeStore.getState();
+            if (store.activeThreadId !== remoteId) {
+              store.setActiveThreadId(remoteId);
+            }
+          }
           const thread = await getStoredChatThread(remoteId);
           if (thread) {
             await ensureStoredChatThread(remoteId, thread);
@@ -915,7 +957,7 @@ function useStudioRuntimeAdapters(): StudioRuntimeAdapters {
         return trackHistoryAppend(message.id, write);
       },
     }),
-    [aui],
+    [aui, modelType, pairId],
   );
 
   const dictation = useMemo(
@@ -947,8 +989,11 @@ function useStudioRuntimeAdapters(): StudioRuntimeAdapters {
 
 const chatAdapter = createOpenAIStreamAdapter();
 
-function useRuntimeHook(): ReturnType<typeof useLocalRuntime> {
-  const adapters = useStudioRuntimeAdapters();
+function useRuntimeHook(
+  modelType: ModelType,
+  pairId?: string,
+): ReturnType<typeof useLocalRuntime> {
+  const adapters = useStudioRuntimeAdapters(modelType, pairId);
   const persistedChatAdapter = useMemo(
     () => createPersistedRunAdapter(chatAdapter),
     [],
@@ -956,6 +1001,12 @@ function useRuntimeHook(): ReturnType<typeof useLocalRuntime> {
   return useLocalRuntime(persistedChatAdapter, { adapters });
 }
 
+function createRuntimeHook(modelType: ModelType, pairId?: string) {
+  return function useConfiguredRuntimeHook(): ReturnType<typeof useLocalRuntime> {
+    return useRuntimeHook(modelType, pairId);
+  };
+}
+
 function ThreadAutoSwitch({
   threadId,
   syncActiveThreadId = true,
@@ -1133,20 +1184,28 @@ export function ChatRuntimeProvider({
   children,
   modelType = "base",
   pairId,
+  projectId,
   initialThreadId,
   newThreadNonce,
   syncActiveThreadId = true,
+  listThreads = true,
 }: {
   children: ReactNode;
   modelType?: ModelType;
   pairId?: string;
+  projectId?: string | null;
   initialThreadId?: string;
   newThreadNonce?: string;
   syncActiveThreadId?: boolean;
+  listThreads?: boolean;
 }): ReactElement {
+  const runtimeHook = useMemo(
+    () => createRuntimeHook(modelType, pairId),
+    [modelType, pairId],
+  );
   const runtime = useRemoteThreadListRuntime({
-    runtimeHook: useRuntimeHook,
-    adapter: createStudioDbAdapter(modelType, pairId),
+    runtimeHook,
+    adapter: createStudioDbAdapter(modelType, pairId, projectId, listThreads),
   });
 
   const aui = useAui({});
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 772b217117..0165a3930e 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -1294,8 +1294,8 @@ export function SharedComposer({
                     : reasoningDisabled
                       ? "cursor-not-allowed opacity-40"
                       : effectiveReasoningEnabled
-                        ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                        : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
+                        ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
+                        : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
                 )}
                 aria-label={thinkToggleAriaLabel({
                   reasoningLockedOn,
@@ -1324,8 +1324,8 @@ export function SharedComposer({
                 !modelLoaded
                   ? "cursor-not-allowed opacity-40"
                   : preserveThinking
-                    ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                    : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
+                    ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
+                    : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
               )}
               aria-label={
                 preserveThinking
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 5a5928d311..ebcd1892d1 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -332,6 +332,7 @@ type ChatRuntimeStore = {
   chatTemplateOverride: string | null;
   loadedChatTemplateOverride: string | null;
   activeThreadId: string | null;
+  activeProjectId: string | null;
   settingsPanelOpen: boolean;
   pendingAudioBase64: string | null;
   pendingAudioName: string | null;
@@ -363,6 +364,7 @@ type ChatRuntimeStore = {
   setModelsError: (error: string | null) => void;
   setCheckpoint: (modelId: string, ggufVariant?: string | null) => void;
   setActiveThreadId: (threadId: string | null) => void;
+  setActiveProjectId: (projectId: string | null) => void;
   setSettingsPanelOpen: (open: boolean) => void;
   clearCheckpoint: () => void;
   setReasoningEnabled: (
@@ -662,6 +664,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   chatTemplateOverride: null,
   loadedChatTemplateOverride: null,
   activeThreadId: null,
+  activeProjectId: null,
   settingsPanelOpen: false,
   pendingAudioBase64: null,
   pendingAudioName: null,
@@ -825,6 +828,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
     }),
   setActiveThreadId: (activeThreadId) =>
     set({ activeThreadId, contextUsage: null }),
+  setActiveProjectId: (activeProjectId) => set({ activeProjectId }),
   setSettingsPanelOpen: (settingsPanelOpen) => set({ settingsPanelOpen }),
   clearCheckpoint: () => {
     // Mirror setCheckpoint's persistence behavior: dropping the
diff --git a/studio/frontend/src/features/chat/thread-sidebar.tsx b/studio/frontend/src/features/chat/thread-sidebar.tsx
index b15c16297e..320668a61c 100644
--- a/studio/frontend/src/features/chat/thread-sidebar.tsx
+++ b/studio/frontend/src/features/chat/thread-sidebar.tsx
@@ -42,7 +42,11 @@ export function ThreadSidebar({
   const { items } = useChatSidebarItems();
   const storeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const activeId =
-    view.mode === "single" ? (view.threadId ?? storeThreadId) : view.pairId;
+    view.mode === "single"
+      ? (view.threadId ?? storeThreadId)
+      : view.mode === "compare"
+        ? view.pairId
+        : view.projectId;
 
   function viewForItem(item: SidebarItem): ChatView {
     return item.type === "single"
diff --git a/studio/frontend/src/features/chat/types.ts b/studio/frontend/src/features/chat/types.ts
index d0c4e22870..a2bd395065 100644
--- a/studio/frontend/src/features/chat/types.ts
+++ b/studio/frontend/src/features/chat/types.ts
@@ -4,8 +4,28 @@
 export type ModelType = "base" | "lora" | "model1" | "model2";
 
 export type ChatView =
-  | { mode: "single"; threadId?: string; newThreadNonce?: string }
-  | { mode: "compare"; pairId: string };
+  | {
+      mode: "project";
+      projectId: string;
+    }
+  | {
+      mode: "single";
+      threadId?: string;
+      newThreadNonce?: string;
+      projectId?: string | null;
+    }
+  | { mode: "compare"; pairId: string; projectId?: string | null };
+
+export interface ProjectRecord {
+  id: string;
+  name: string;
+  instructions?: string;
+  rootPath?: string | null;
+  sandboxPath?: string | null;
+  archived: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
 
 export interface ThreadRecord {
   id: string;
@@ -13,6 +33,7 @@ export interface ThreadRecord {
   modelType: ModelType;
   modelId?: string;
   pairId?: string;
+  projectId?: string | null;
   archived: boolean;
   createdAt: number;
   /**
diff --git a/studio/frontend/src/features/chat/utils/chat-history-storage.ts b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
index 57b303b7af..6dc53cf48e 100644
--- a/studio/frontend/src/features/chat/utils/chat-history-storage.ts
+++ b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
@@ -4,22 +4,32 @@
 import {
   buildBackendChatExport,
   clearBackendChats,
+  deleteChatProject,
   deleteChatThreads,
+  getChatProject,
   getChatMessage,
   getChatThread,
   batchListChatMessages,
+  listChatProjects,
   listChatImportLedger,
   listChatMessages,
   listChatThreads,
   notifyChatHistoryUpdated,
   recordChatImportLedger,
+  saveChatProject,
   saveChatMessage,
   saveChatThread,
   syncChatMessages,
+  updateChatProject,
   updateChatThread,
 } from "../api/chat-api";
 import { db, DEXIE_DB_NAME } from "../db";
-import type { MessageRecord, ModelType, ThreadRecord } from "../types";
+import type {
+  MessageRecord,
+  ModelType,
+  ProjectRecord,
+  ThreadRecord,
+} from "../types";
 import {
   isChatThreadDeleted,
   markChatThreadsDeleted,
@@ -28,6 +38,7 @@ import {
 type ThreadListArgs = {
   modelType?: ModelType;
   pairId?: string;
+  projectId?: string | null;
   includeArchived?: boolean;
 };
 
@@ -45,6 +56,7 @@ interface ExportedChat {
   exportedAt: string;
   version: 1;
   threadCount: number;
+  projects?: unknown[];
   threads: unknown[];
   messages: unknown[];
 }
@@ -82,6 +94,8 @@ function matchesThreadListArgs(
   return (
     !isChatThreadDeleted(thread.id) &&
     (!args.pairId || thread.pairId === args.pairId) &&
+    (args.projectId === undefined ||
+      (thread.projectId ?? null) === args.projectId) &&
     (!args.modelType || thread.modelType === args.modelType) &&
     (args.includeArchived !== false || !thread.archived)
   );
@@ -584,6 +598,72 @@ export async function listStoredChatThreadsWithMessages(
   return entries.filter((e) => e.hasContent).map((e) => e.thread);
 }
 
+export async function listStoredChatProjects(
+  args: { includeArchived?: boolean } = {},
+): Promise<ProjectRecord[]> {
+  return listChatProjects(args);
+}
+
+export async function getStoredChatProject(
+  projectId: string,
+): Promise<ProjectRecord | null> {
+  return getChatProject(projectId);
+}
+
+export async function createStoredChatProject(
+  name: string,
+): Promise<ProjectRecord> {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error("Project name is required.");
+  }
+  const now = Date.now();
+  return saveChatProject({
+    id: crypto.randomUUID(),
+    name: trimmed,
+    instructions: "",
+    archived: false,
+    createdAt: now,
+    updatedAt: now,
+  });
+}
+
+export async function updateStoredChatProject(
+  projectId: string,
+  patch: Partial<ProjectRecord>,
+): Promise<ProjectRecord> {
+  return updateChatProject(projectId, {
+    ...patch,
+    updatedAt: patch.updatedAt ?? Date.now(),
+  });
+}
+
+export async function deleteStoredChatProject(
+  projectId: string,
+  args: { deleteFiles?: boolean } = {},
+): Promise<void> {
+  await deleteChatProject(projectId, args);
+}
+
+export async function moveStoredChatItemToProject(
+  item: { type: "single" | "compare"; id: string },
+  projectId: string | null,
+): Promise<void> {
+  const threadIds =
+    item.type === "single"
+      ? [item.id]
+      : (await listStoredChatThreads({
+          pairId: item.id,
+          includeArchived: true,
+        })).map((thread) => thread.id);
+
+  await Promise.all(
+    Array.from(new Set(threadIds)).map((threadId) =>
+      updateStoredChatThread(threadId, { projectId }),
+    ),
+  );
+}
+
 export async function saveStoredChatMessage(
   message: MessageRecord,
 ): Promise<MessageRecord> {
@@ -767,6 +847,7 @@ export async function buildStoredChatExport(): Promise<ExportedChat> {
     exportedAt: new Date().toISOString(),
     version: 1,
     threadCount: threads.length,
+    projects: backend?.projects ?? [],
     threads,
     messages,
   };
diff --git a/studio/frontend/src/features/profile/utils/avatar-initials.ts b/studio/frontend/src/features/profile/utils/avatar-initials.ts
index 926f57f3b5..254a50719b 100644
--- a/studio/frontend/src/features/profile/utils/avatar-initials.ts
+++ b/studio/frontend/src/features/profile/utils/avatar-initials.ts
@@ -7,7 +7,7 @@ export function initialsFromName(name: string): string {
   return trimmed[0]!.toUpperCase();
 }
 
-/** Default blue background for avatar fallback (readable white text). */
+/** Default Unsloth-green background for avatar fallback (readable white text). */
 export function avatarBgStyle(): { backgroundColor: string } {
-  return { backgroundColor: "hsl(217 58% 48%)" };
+  return { backgroundColor: "#14b789" };
 }
diff --git a/studio/frontend/src/features/studio/studio-page.tsx b/studio/frontend/src/features/studio/studio-page.tsx
index b13ecbd1c4..53191fa305 100644
--- a/studio/frontend/src/features/studio/studio-page.tsx
+++ b/studio/frontend/src/features/studio/studio-page.tsx
@@ -53,6 +53,10 @@ export function StudioPage(): ReactElement {
   const selectedHistoryRunId = useTrainingRuntimeStore((s) => s.selectedHistoryRunId);
   const setSelectedHistoryRunId = useTrainingRuntimeStore((s) => s.setSelectedHistoryRunId);
 
+  const setCurrentRunViewActive = useTrainingRuntimeStore(
+    (s) => s.setCurrentRunViewActive,
+  );
+
   useEffect(() => {
     return () => setSelectedHistoryRunId(null);
   }, [setSelectedHistoryRunId]);
@@ -67,6 +71,13 @@ export function StudioPage(): ReactElement {
         ? "configure"
         : requestedTab;
 
+  // Mirror "Current Run" tab state into the store so the sidebar can highlight
+  // the run this view refers to. Cleared on unmount (leaving the studio page).
+  useEffect(() => {
+    setCurrentRunViewActive(activeTab === "current-run");
+    return () => setCurrentRunViewActive(false);
+  }, [activeTab, setCurrentRunViewActive]);
+
   const { setPinned } = useSidebar();
   const pinSidebar = useCallback(() => setPinned(true), [setPinned]);
 
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index 8ecd3bb7e9..0205394a53 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -37,6 +37,12 @@ import { useT } from "@/i18n";
 
 const HF_REPO_REGEX = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 
+// Tracks which jobs have already played the terminal intro animation. The
+// overlay unmounts when you navigate away from the training page, so without
+// this its typing/fade-in would replay on every return even though the run
+// itself is still going. Module-level so it survives remounts.
+const animatedJobs = new Set<string>();
+
 function formatBytes(n: number): string {
   if (n <= 0) return "0 B";
   if (n < 1024) return `${n} B`;
@@ -254,6 +260,7 @@ export function TrainingStartOverlay({
   const { stopTrainingRun, dismissTrainingRun } = useTrainingActions();
   const isStarting = useTrainingRuntimeStore((s) => s.isStarting);
   const phase = useTrainingRuntimeStore((s) => s.phase);
+  const jobId = useTrainingRuntimeStore((s) => s.jobId);
   const startModelName = useTrainingRuntimeStore((s) => s.startModelName);
   const startDatasetName = useTrainingRuntimeStore((s) => s.startDatasetName);
   const startFromResume = useTrainingRuntimeStore((s) => s.startFromResume);
@@ -298,6 +305,16 @@ export function TrainingStartOverlay({
     }
   }, [isStarting]);
 
+  // Play the intro animation only the first time we mount for a given job.
+  // On later remounts (e.g. leaving the training page and coming back) the
+  // terminal renders its final state instantly so the logs don't restart.
+  const alreadyAnimated = jobId != null && animatedJobs.has(jobId);
+  useEffect(() => {
+    if (jobId != null) {
+      animatedJobs.add(jobId);
+    }
+  }, [jobId]);
+
   return (
     <div className="pointer-events-none absolute inset-0 z-30 flex items-center justify-center rounded-2xl bg-background/45 backdrop-blur-[1px]">
       <div className="pointer-events-auto relative flex w-[860px] max-w-[calc(100%-2rem)] flex-col items-center gap-4">
@@ -311,7 +328,7 @@ export function TrainingStartOverlay({
             <Button
               variant="ghost"
               size="icon"
-              className="absolute right-3 top-3 z-10 size-7 cursor-pointer rounded-full text-muted-foreground/60 hover:bg-destructive/10 hover:text-destructive"
+              className="absolute right-3 top-3 z-10 size-7 cursor-pointer rounded-full text-muted-foreground/90 hover:bg-destructive/10 hover:text-destructive"
               onClick={() => setCancelDialogOpen(true)}
               disabled={cancelRequested}
             >
@@ -349,6 +366,7 @@ export function TrainingStartOverlay({
           <Terminal
             className="w-full min-h-[390px] rounded-2xl px-7 py-6 text-left"
             startOnView={false}
+            instant={alreadyAnimated}
           >
           <TypingAnimation
             duration={36}
diff --git a/studio/frontend/src/features/training/stores/training-runtime-store.ts b/studio/frontend/src/features/training/stores/training-runtime-store.ts
index da496be002..f1966f03fb 100644
--- a/studio/frontend/src/features/training/stores/training-runtime-store.ts
+++ b/studio/frontend/src/features/training/stores/training-runtime-store.ts
@@ -46,6 +46,7 @@ const initialState: TrainingRuntimeState = {
   resetGeneration: 0,
   stopRequested: false,
   selectedHistoryRunId: null,
+  currentRunViewActive: false,
 };
 
 function sortSeries(points: TrainingSeriesPoint[]): TrainingSeriesPoint[] {
@@ -182,6 +183,9 @@ export const useTrainingRuntimeStore = create<TrainingRuntimeStore>()((set) => (
   setSelectedHistoryRunId: (selectedHistoryRunId) =>
     set({ selectedHistoryRunId }),
 
+  setCurrentRunViewActive: (currentRunViewActive) =>
+    set({ currentRunViewActive }),
+
   applyStatus: (payload) =>
     set((state) => {
       const metricHistory = applyMetricHistoryFromStatus(payload);
diff --git a/studio/frontend/src/features/training/types/runtime.ts b/studio/frontend/src/features/training/types/runtime.ts
index a62ef9ef26..d30c3f75c2 100644
--- a/studio/frontend/src/features/training/types/runtime.ts
+++ b/studio/frontend/src/features/training/types/runtime.ts
@@ -105,6 +105,9 @@ export interface TrainingRuntimeState {
   resetGeneration: number;
   stopRequested: boolean;
   selectedHistoryRunId: string | null;
+  // True while the studio "Current Run" tab is the active view, so the sidebar
+  // can highlight which run row the current run refers to (the active job).
+  currentRunViewActive: boolean;
 }
 
 export interface TrainingRuntimeActions {
@@ -127,6 +130,7 @@ export interface TrainingRuntimeActions {
   setStartQueued: (jobId: string, message: string) => void;
   setRuntimeError: (message: string) => void;
   setSelectedHistoryRunId: (id: string | null) => void;
+  setCurrentRunViewActive: (value: boolean) => void;
 }
 
 export type TrainingRuntimeStore = TrainingRuntimeState & TrainingRuntimeActions;
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 2f5f20252e..c60dfc6bd7 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -14,6 +14,51 @@
 
 @custom-variant dark (&:is(.dark *));
 
+@layer components {
+	/* Sidebar scroll area (Gemini-style). The BOTTOM edge always fades so the
+	   last rows dissolve into the profile footer (no divider line). Once
+	   scrolled, the TOP edge also fades so rows dissolve as they pass under the
+	   pinned New Chat / Search header. */
+	/* Top edge: when scrolled, rows dissolve as they pass under the pinned
+	   New Chat / Search header (mask — fades content to transparent). */
+	.sidebar-scroll-fade.is-scrolled {
+		-webkit-mask-image: linear-gradient(to bottom, transparent 0, #000 14px);
+		mask-image: linear-gradient(to bottom, transparent 0, #000 14px);
+	}
+	/* Bottom edge: Gemini-style sticky gradient OVERLAY painted in the sidebar
+	   background colour, so the last rows wash into the profile footer. Uses a
+	   zero-height sticky anchor with an absolutely-positioned gradient so it
+	   never takes layout space. */
+	.sidebar-bottom-fade {
+		position: sticky;
+		bottom: 0;
+		height: 0;
+		z-index: 1;
+		pointer-events: none;
+	}
+	.sidebar-bottom-fade::after {
+		content: "";
+		position: absolute;
+		inset-inline: 0;
+		bottom: 0;
+		height: 40px;
+		background: linear-gradient(to top, var(--sidebar), transparent);
+	}
+}
+
+@layer base {
+	h1,
+	h2,
+	h3,
+	[data-slot="dialog-title"],
+	[data-slot="alert-dialog-title"] {
+		font-family: "Hellix", "Space Grotesk Variable", var(--font-sans) !important;
+		font-weight: 500 !important;
+	}
+}
+
+
+
 @font-face {
 	font-family: "Hellix";
 	src: url("/fonts/Hellix-Regular.woff") format("woff");
@@ -81,13 +126,15 @@
 	--chart-4: oklch(0.6926 0.1112 346.5775);
 	--chart-5: oklch(0.7497 0.1003 85.0057);
 	--radius: 1.1rem;
-	--sidebar: #f9faf9;
+	/* Match the page background so the sidebar reads as one surface with the
+	   content; the faint --sidebar-border on its right edge is the separator. */
+	--sidebar: oklch(1 0 0);
 	--sidebar-foreground: oklch(0.1281 0.0179 169.2764);
 	--sidebar-primary: #17b88b;
 	--sidebar-primary-foreground: oklch(1 0 0);
 	--sidebar-accent: oklch(0.96 0.0279 166.55);
 	--sidebar-accent-foreground: oklch(0.2868 0.0649 159.9823);
-	--sidebar-border: oklch(0.945 0.0101 164.8536);
+	--sidebar-border: oklch(0.92 0 0);
 	--sidebar-ring: #17b88b;
 	--destructive-foreground: oklch(1 0 0);
 	--font-sans: "Inter Variable", ui-sans-serif, sans-serif, system-ui;
@@ -120,7 +167,7 @@
 	/*    0px 0px 0px 0px hsl(0 0% 0% / 0),*/
 	/*    0px 8px 10px 0px hsl(0 0% 0% / 0);*/
 	/*--shadow-2xl: 0px 0px 0px 0px hsl(0 0% 0% / 0);*/
-	--tracking-normal: -0.01em;
+	--tracking-normal: 0em;
 
 	/* Hex (not OKLCH) so the rendered surface matches the design mockup pixel-for-pixel. */
 	--nav-fg: #383835;
@@ -201,7 +248,8 @@
 	--chart-3: oklch(0.7554 0.1285 197.339);
 	--chart-4: oklch(0.7503 0.1199 346.7805);
 	--chart-5: oklch(0.799 0.1196 84.6633);
-	--sidebar: #18181a;
+	/* Match the page background (dark); --sidebar-border is the right-edge separator. */
+	--sidebar: #1f2023;
 	--sidebar-foreground: #ececee;
 	--sidebar-primary: #17b88b;
 	--sidebar-primary-foreground: oklch(1 0 0);
@@ -305,8 +353,8 @@
 	--font-mono: JetBrains Mono, monospace;
 	--font-serif: Source Serif 4, serif;
 	--radius: 1.1rem;
-	--tracking-tighter: calc(var(--tracking-normal) - 0.05em);
-	--tracking-tight: calc(var(--tracking-normal) - 0.025em);
+	--tracking-tighter: 0em;
+	--tracking-tight: 0em;
 	--tracking-wide: calc(var(--tracking-normal) + 0.025em);
 	--tracking-wider: calc(var(--tracking-normal) + 0.05em);
 	--tracking-widest: calc(var(--tracking-normal) + 0.1em);
@@ -438,7 +486,7 @@
 	h5,
 	h6 {
 		font-family: var(--font-sans);
-		letter-spacing: -0.02em;
+		letter-spacing: 0;
 	}
 }
 
@@ -450,15 +498,14 @@
 	   on global antialiased font-smoothing to neutralize the bloom. */
 	.font-heading {
 		font-family: var(--font-heading);
-		letter-spacing: -0.01em;
+		letter-spacing: 0;
 	}
 
-	/* Dark mode loosens tracking to offset optical bloom on dark surfaces. */
 	.tracking-nav {
-		letter-spacing: 0.015em;
+		letter-spacing: 0;
 	}
 	.dark .tracking-nav {
-		letter-spacing: 0.03em;
+		letter-spacing: 0;
 	}
 
 	.nav-icon-btn {
@@ -485,6 +532,10 @@
 	.sidebar-nav-btn:hover,
 	.sidebar-nav-btn[data-active="true"],
 	.sidebar-nav-btn[data-state="open"],
+	.group\/project-item:hover .sidebar-nav-btn,
+	.group\/project-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
+	.group\/project-chat-item:hover .sidebar-nav-btn,
+	.group\/project-chat-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
 	.group\/recent-item:hover .sidebar-nav-btn,
 	.group\/recent-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
 	.group\/run-item:hover .sidebar-nav-btn,
@@ -495,6 +546,10 @@
 	.dark .sidebar-nav-btn:hover,
 	.dark .sidebar-nav-btn[data-active="true"],
 	.dark .sidebar-nav-btn[data-state="open"],
+	.dark .group\/project-item:hover .sidebar-nav-btn,
+	.dark .group\/project-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
+	.dark .group\/project-chat-item:hover .sidebar-nav-btn,
+	.dark .group\/project-chat-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
 	.dark .group\/recent-item:hover .sidebar-nav-btn,
 	.dark .group\/recent-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
 	.dark .group\/run-item:hover .sidebar-nav-btn,
@@ -503,7 +558,7 @@
 	}
 
 	.sidebar-row-action {
-		@apply absolute top-0 bottom-0 right-0 inline-flex items-center justify-end pl-2 pr-1.5 opacity-0 pointer-events-none outline-none;
+		@apply absolute top-0 bottom-0 right-0 inline-flex cursor-pointer items-center justify-end pl-2 pr-1.5 opacity-0 pointer-events-none outline-none;
 	}
 	.sidebar-row-action[data-state="open"] {
 		@apply opacity-100 pointer-events-auto;
@@ -529,12 +584,22 @@
 	}
 
 	.sidebar-sticky-label {
-		@apply sticky top-0 z-20 rounded-none bg-sidebar pt-0 pb-1.5 pl-[18px] pr-4 text-[13px]! font-medium normal-case tracking-[0.04em] text-nav-fg-muted focus-visible:ring-0! focus-visible:outline-none shadow-[0_-8px_0_0_var(--sidebar)] transition-shadow duration-150;
+		@apply rounded-none bg-sidebar pt-0 pb-[8px] pl-[18px] pr-4 text-[14.5px]! leading-[17px] font-medium normal-case focus-visible:ring-0! focus-visible:outline-none transition-shadow duration-150;
+		/* Muted section-header gray, matching Gemini's "Notebooks"/"Recents".
+		   Lightened from #5f6368 so the label reads as a header, clearly
+		   lighter than the near-black nav items. */
+		color: #80868b;
+		letter-spacing: 0;
 	}
-	.sidebar-sticky-label.is-scrolled {
-		@apply shadow-[0_-8px_0_0_var(--sidebar),0_0.5px_0_0_var(--sidebar-border)];
+	.sidebar-sticky-label-following {
+		@apply pt-[21px];
+	}
+	.dark .sidebar-sticky-label {
+		/* Muted gray, clearly dimmer than the near-white nav items (#ececee) so
+		   "Train"/"Recents" read as section headers — like Gemini's dark mode. */
+		color: #9aa0a6;
+		letter-spacing: 0;
 	}
-
 	/* Neutral panel input surface — sidesteps the green cast on
 	   `--input` / `--border` (both have a small chroma at hue ~165 in
 	   light mode). Same value drives the preset input pill, the system
@@ -697,7 +762,8 @@
 		border-color: rgb(255 255 255 / 0.12) !important;
 	}
 
-	.app-user-menu [data-slot="dropdown-menu-item"] {
+	.app-user-menu [data-slot="dropdown-menu-item"],
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"] {
 		height: 32px;
 		padding: 0 0.625rem !important;
 		gap: 8.5px !important;
@@ -705,28 +771,38 @@
 		font-weight: 500;
 		font-size: 14.5px;
 		line-height: 19px;
-		letter-spacing: 0.015em;
+		letter-spacing: 0;
 		color: var(--nav-fg);
 	}
-	.dark .app-user-menu [data-slot="dropdown-menu-item"] {
-		letter-spacing: 0.03em;
+	.dark .app-user-menu [data-slot="dropdown-menu-item"],
+	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"] {
+		letter-spacing: 0;
 	}
-	.app-user-menu [data-slot="dropdown-menu-item"] svg {
+	.app-user-menu [data-slot="dropdown-menu-item"] svg,
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"] svg {
 		width: 19px !important;
 		height: 19px !important;
 		flex-shrink: 0;
 	}
-	.app-user-menu [data-slot="dropdown-menu-item"]:focus {
+	.app-user-menu [data-slot="dropdown-menu-item"]:focus,
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"]:focus,
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"][data-state="open"] {
 		background-color: var(--nav-surface-hover);
 		color: #000;
 	}
-	.dark .app-user-menu [data-slot="dropdown-menu-item"]:focus {
+	.dark .app-user-menu [data-slot="dropdown-menu-item"]:focus,
+	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"]:focus,
+	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"][data-state="open"] {
 		color: #fff;
 	}
-	.app-user-menu [data-slot="dropdown-menu-item"]:focus * {
+	.app-user-menu [data-slot="dropdown-menu-item"]:focus *,
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"]:focus *,
+	.app-user-menu [data-slot="dropdown-menu-sub-trigger"][data-state="open"] * {
 		color: #000 !important;
 	}
-	.dark .app-user-menu [data-slot="dropdown-menu-item"]:focus * {
+	.dark .app-user-menu [data-slot="dropdown-menu-item"]:focus *,
+	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"]:focus *,
+	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"][data-state="open"] * {
 		color: #fff !important;
 	}
 
@@ -799,7 +875,7 @@
 	}
 
 	.composer-pill-btn {
-		@apply flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
+		@apply flex cursor-pointer items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
 	}
 	.composer-pill-btn[data-active="true"] {
 		color: var(--primary);
@@ -814,7 +890,7 @@
 	}
 
 	.composer-footer-note {
-		@apply mt-1.5 text-center text-[11px] tracking-[0.04em] text-muted-foreground;
+		@apply mt-1.5 text-center text-[11px] tracking-[0em] text-muted-foreground;
 		font-family: var(--font-sans);
 	}
 
@@ -1277,24 +1353,16 @@
 	background: #23252a;
 }
 
-[data-sidebar="content"] {
-	scrollbar-color: oklch(0.5 0 0 / 0.22) var(--sidebar);
-}
 
-.dark [data-sidebar="content"] {
-	scrollbar-color: oklch(0.72 0 0 / 0.25) var(--sidebar);
+/* Search list: re-enable the native scrollbar (CommandList defaults to no-scrollbar). */
+.cmd-native-scrollbar {
+	scrollbar-width: thin;
+	-ms-overflow-style: auto;
 }
-
-[data-sidebar="content"]::-webkit-scrollbar-track {
-	background: var(--sidebar);
-}
-
-[data-sidebar="content"]::-webkit-scrollbar-thumb {
-	background: oklch(0.5 0 0 / 0.22);
-}
-
-.dark [data-sidebar="content"]::-webkit-scrollbar-thumb {
-	background: oklch(0.72 0 0 / 0.25);
+.cmd-native-scrollbar::-webkit-scrollbar {
+	display: block;
+	width: 8px;
+	height: 8px;
 }
 
 /*---break---*/

From aee06576403b38f966dc7e6a47f9cc957c56610f Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Mon, 1 Jun 2026 23:52:53 +0200
Subject: [PATCH 063/222] fix(chat): refine artifact panel styling (#5922)

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 .../src/features/chat/artifacts/artifact-surface.tsx      | 8 ++++----
 studio/frontend/src/index.css                             | 8 ++++++++
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
index b32d24469b..8de3f7861d 100644
--- a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
+++ b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
@@ -201,10 +201,10 @@ export function ArtifactSurface({
       tabIndex={variant === "overlay" ? -1 : undefined}
       onKeyDown={handleDialogKeyDown}
       className={cn(
-        "relative flex min-h-0 flex-col border border-border bg-background",
+        "relative flex min-h-0 flex-col bg-background",
         variant === "panel"
-          ? "artifact-panel-shell mx-2 mt-[72px] mb-8 h-[calc(100%_-_104px)] overflow-visible rounded-[28px] border-border/70 bg-card/95 [box-shadow:rgba(0,0,0,0.16)_0px_2px_8px_-2px]"
-          : "h-[min(92vh,900px)] w-[min(96vw,1200px)] overflow-hidden rounded-2xl shadow-xl",
+          ? "artifact-panel-shell mx-2 mt-[72px] mb-8 h-[calc(100%_-_104px)] overflow-visible rounded-[28px] border-t border-border/70 bg-card/95"
+          : "h-[min(92vh,900px)] w-[min(96vw,1200px)] overflow-hidden rounded-2xl border border-border shadow-xl",
       )}
       aria-label={`${artifact.title} artifact`}
     >
@@ -330,7 +330,7 @@ export function ArtifactSurface({
             className="h-full"
           />
         ) : (
-          <div className="h-full overflow-auto text-xs leading-relaxed [&_[data-streamdown=code-block]]:!rounded-none [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:text-xs [&_pre]:leading-relaxed [&_code]:text-xs">
+          <div className="h-full overflow-auto text-xs leading-relaxed [&_[data-streamdown=code-block]]:!my-0 [&_[data-streamdown=code-block]]:!gap-0 [&_[data-streamdown=code-block]]:!rounded-none [&_[data-streamdown=code-block]]:!border-0 [&_[data-streamdown=code-block]]:!bg-transparent [&_[data-streamdown=code-block]]:!p-0 [&_[data-streamdown=code-block-body]]:!border-0 [&_[data-streamdown=code-block-body]]:!bg-transparent [&_[data-streamdown=code-block-body]]:!p-0 [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:text-xs [&_pre]:leading-relaxed [&_code]:text-xs">
             <Streamdown
               mode="streaming"
               plugins={{ code: artifactSourceCodePlugin }}
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index c60dfc6bd7..28c4cd0948 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -894,6 +894,14 @@
 		font-family: var(--font-sans);
 	}
 
+	.artifact-panel-shell {
+		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
+	}
+
+	.dark .artifact-panel-shell {
+		box-shadow: none;
+	}
+
 	.chat-artifact-split[data-artifact-layout-animating="true"] > [data-panel] {
 		transition:
 			flex-basis 260ms var(--ease-out-cubic),

From 07f0eddb0b5e1833e0374f5301d132eb3688fde5 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Tue, 2 Jun 2026 01:22:00 -0300
Subject: [PATCH 064/222] studio/frontend: pad Python tool code block to fix
 corner clipping (#5938)

---
 studio/frontend/src/components/assistant-ui/tool-ui-python.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
index bab735104c..ce15d3e440 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
@@ -78,7 +78,7 @@ function HighlightedCode({ code: source, language }: { code: string; language: s
     [source, language],
   );
   return (
-    <div className="max-h-48 overflow-auto text-xs [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:!text-xs [&_[data-streamdown=code-block]]:!my-0 [&_[data-streamdown=code-block]]:!p-0 [&_[data-streamdown=code-block]]:!border-0">
+    <div className="max-h-48 overflow-auto text-xs [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:!text-xs [&_[data-streamdown=code-block]]:!my-0 [&_[data-streamdown=code-block]]:!p-3 [&_[data-streamdown=code-block]]:!border-0">
       <Streamdown
         mode="static"
         plugins={{ code: codePlugin }}

From a05944ab751e713dcb4f04bcf832cf7feee273f2 Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Tue, 2 Jun 2026 07:40:56 +0100
Subject: [PATCH 065/222] Studio: polish model load toast styling (#5648)

* fix: toast cancel and style

* fix: align model load toast Cancel and dismiss on the right

* fix: show short cased model name in loaded toast and removed prefix org

* revert: chat load toast refactor to visual-only changes

* fix: align model load toast close button

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: guard empty toast label and dedupe toast padding CSS

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Roland Tannous <rolandtannous@gravityq.ai>
Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
---
 studio/frontend/src/components/ui/sonner.tsx  |  13 +-
 .../chat/components/model-load-status.tsx     |  16 +--
 .../chat/hooks/use-chat-model-runtime.ts      | 123 ++++++++++--------
 studio/frontend/src/index.css                 |  38 +++++-
 4 files changed, 112 insertions(+), 78 deletions(-)

diff --git a/studio/frontend/src/components/ui/sonner.tsx b/studio/frontend/src/components/ui/sonner.tsx
index 5bd3078761..bf6d4970b0 100644
--- a/studio/frontend/src/components/ui/sonner.tsx
+++ b/studio/frontend/src/components/ui/sonner.tsx
@@ -65,13 +65,12 @@ const Toaster = ({ ...props }: ToasterProps) => {
           "--normal-text": "var(--popover-foreground)",
           "--normal-border": "var(--border)",
           "--border-radius": "var(--radius)",
-          // Pin close button to the top-right corner inside the toast.
-          // Overrides sonner's default left placement and outside-corner
-          // translate; top offset is set via a rule in index.css since sonner
-          // hardcodes `top: 0` (not a CSS variable).
-          "--toast-close-button-start": "unset",
-          "--toast-close-button-end": "8px",
-          "--toast-close-button-transform": "none",
+          // Pin the close button inside the toast's top-right corner.
+          // Sonner defaults to the left/outside edge, so keep the horizontal
+          // override here and the top offset in index.css.
+          "--toast-close-button-start": "unset",
+          "--toast-close-button-end": "8px",
+          "--toast-close-button-transform": "none",
         } as React.CSSProperties
       }
       // No swipe gestures; keeps toast text selectable.
diff --git a/studio/frontend/src/features/chat/components/model-load-status.tsx b/studio/frontend/src/features/chat/components/model-load-status.tsx
index 381f58fbbf..75d92f4581 100644
--- a/studio/frontend/src/features/chat/components/model-load-status.tsx
+++ b/studio/frontend/src/features/chat/components/model-load-status.tsx
@@ -10,7 +10,6 @@ type ModelLoadDescriptionProps = {
   message?: string | null;
   progressPercent?: number | null;
   progressLabel?: string | null;
-  onStop?: () => void;
 };
 
 function clampProgress(value: number): number {
@@ -45,7 +44,6 @@ export function ModelLoadDescription({
   message,
   progressPercent,
   progressLabel,
-  onStop,
 }: ModelLoadDescriptionProps) {
   const hasProgress = typeof progressPercent === "number";
   // Split once at the top of the render so the JSX below stays flat --
@@ -58,7 +56,7 @@ export function ModelLoadDescription({
       <div className="flex h-full shrink-0 items-center self-center">
         <Spinner className="size-3.5 text-muted-foreground" />
       </div>
-      <div className="min-w-0 flex-1 pr-5">
+      <div className="min-w-0 flex-1">
         {title ? <p className="text-foreground leading-5 font-semibold">{title}</p> : null}
         {hasProgress ? (
           <div className="w-full pt-1">
@@ -82,18 +80,6 @@ export function ModelLoadDescription({
           <p className="pt-1 text-xs leading-relaxed text-muted-foreground">{message}</p>
         ) : null}
       </div>
-      {onStop ? (
-        <Button
-          type="button"
-          size="xs"
-          variant="ghost"
-          aria-label="Stop model loading"
-          className="h-auto self-stretch shrink-0 !rounded-none !border-0 bg-transparent px-1 text-[10px] text-muted-foreground hover:bg-transparent hover:text-destructive focus-visible:text-destructive"
-          onClick={onStop}
-        >
-          Cancel
-        </Button>
-      ) : null}
     </div>
   );
 }
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 1cac12ab13..8771bc888a 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -56,10 +56,16 @@ type SelectedModelInput = {
 };
 
 const MODEL_LOAD_TOAST_CLASSNAMES = {
-  toast: "items-start gap-2.5",
+  toast: "chat-model-load-toast items-center gap-2.5",
   content: "gap-0.5 flex-1 min-w-0",
   title: "leading-5",
   description: "mt-0 w-full",
+  cancelButton:
+    "!h-auto !rounded-none !border-0 !bg-transparent !px-1 !text-[11px] !font-normal !text-muted-foreground hover:!bg-transparent hover:!text-destructive focus-visible:!text-destructive",
+} as const;
+
+const MODEL_LOADED_TOAST_CLASSNAMES = {
+  toast: "chat-model-loaded-toast items-center gap-2.5",
 } as const;
 
 const LORA_SUFFIX_RE = /_(\d{9,})$/;
@@ -78,6 +84,12 @@ function stripTrailingEpoch(input: string): string {
   return cleaned || input;
 }
 
+function shortModelLabel(idOrName: string): string {
+  const slash = idOrName.lastIndexOf("/");
+  const label = slash >= 0 ? idOrName.slice(slash + 1) : idOrName;
+  return label || idOrName;
+}
+
 function describeModel(model: {
   is_lora?: boolean;
   is_vision?: boolean;
@@ -233,14 +245,12 @@ export function useChatModelRuntime() {
       message: string,
       progressPercent?: number | null,
       progressLabel?: string | null,
-      onStop?: () => void,
     ) =>
       createElement(ModelLoadDescription, {
         title,
         message,
         progressPercent,
         progressLabel,
-        onStop,
       }),
     [],
   );
@@ -471,10 +481,11 @@ export function useChatModelRuntime() {
       const isLora =
         explicitIsLora ?? model?.isLora ?? loraIsAdapter ?? false;
       const displayName = model?.name || lora?.name || modelId;
+      const toastDisplayName = shortModelLabel(displayName);
       const loadAttemptId = ++loadAttemptRef.current;
       primeNativeNotificationPermission().catch(() => undefined);
       const notificationModelKey = `${modelId}:${ggufVariant ?? ""}:${loadAttemptId}`;
-      const safeModelName = safeNotificationLabel(displayName, "The model");
+      const safeModelName = safeNotificationLabel(toastDisplayName, "The model");
       const currentCheckpoint =
         useChatRuntimeStore.getState().params.checkpoint;
       const previousCheckpoint = currentCheckpoint;
@@ -794,25 +805,32 @@ export function useChatModelRuntime() {
 
         const isCachedLoad = isDownloaded || isCachedLora;
         const toastTitle = isCachedLoad ? "Starting model…" : "Downloading model…";
+        const modelLoadToastOptions = (description: ReturnType<typeof renderLoadDescription>) => ({
+          description,
+          duration: Infinity,
+          closeButton: true,
+          cancel: {
+            label: "Cancel",
+            onClick: cancelLoading,
+          },
+          classNames: MODEL_LOAD_TOAST_CLASSNAMES,
+          onDismiss: (dismissedToast: { id: string | number }) => {
+            if (loadToastIdRef.current !== dismissedToast.id) {
+              return;
+            }
+            setLoadToastDismissedState(true);
+          },
+        });
         const toastId = toast(
           null,
-          {
-            description: renderLoadDescription(
+          modelLoadToastOptions(
+            renderLoadDescription(
               toastTitle,
               loadingDescription,
               isCachedLoad ? null : 0,
               isCachedLoad ? null : "Preparing download",
-              cancelLoading,
             ),
-            duration: Infinity,
-            classNames: MODEL_LOAD_TOAST_CLASSNAMES,
-            onDismiss: (dismissedToast) => {
-              if (loadToastIdRef.current !== dismissedToast.id) {
-                return;
-              }
-              setLoadToastDismissedState(true);
-            },
-          },
+          ),
         );
         loadToastIdRef.current = toastId;
 
@@ -919,19 +937,14 @@ export function useChatModelRuntime() {
               if (loadToastDismissedRef.current) return;
               toast(null, {
                 id: toastId,
-                description: renderLoadDescription(
-                  "Downloading model…",
-                  loadingDescription,
-                  pct,
-                  progressLabel,
-                  cancelLoading,
+                ...modelLoadToastOptions(
+                  renderLoadDescription(
+                    "Downloading model…",
+                    loadingDescription,
+                    pct,
+                    progressLabel,
+                  ),
                 ),
-                duration: Infinity,
-                classNames: MODEL_LOAD_TOAST_CLASSNAMES,
-                onDismiss: (dismissedToast) => {
-                  if (loadToastIdRef.current !== dismissedToast.id) return;
-                  setLoadToastDismissedState(true);
-                },
               });
             } else if (
               prog.downloaded_bytes > 0 &&
@@ -958,19 +971,14 @@ export function useChatModelRuntime() {
               if (!loadToastDismissedRef.current) {
                 toast(null, {
                   id: toastId,
-                  description: renderLoadDescription(
-                    "Starting model…",
-                    "Download complete. Loading the model into memory.",
-                    100,
-                    "Download complete",
-                    cancelLoading,
+                  ...modelLoadToastOptions(
+                    renderLoadDescription(
+                      "Starting model…",
+                      "Download complete. Loading the model into memory.",
+                      100,
+                      "Download complete",
+                    ),
                   ),
-                  duration: Infinity,
-                  classNames: MODEL_LOAD_TOAST_CLASSNAMES,
-                  onDismiss: (dismissedToast) => {
-                    if (loadToastIdRef.current !== dismissedToast.id) return;
-                    setLoadToastDismissedState(true);
-                  },
                 });
               }
               notifyNative({
@@ -1020,19 +1028,14 @@ export function useChatModelRuntime() {
             if (loadToastDismissedRef.current) return;
             toast(null, {
               id: toastId,
-              description: renderLoadDescription(
-                "Starting model…",
-                "Paging weights into memory.",
-                pct,
-                label,
-                cancelLoading,
+              ...modelLoadToastOptions(
+                renderLoadDescription(
+                  "Starting model…",
+                  "Paging weights into memory.",
+                  pct,
+                  label,
+                ),
               ),
-              duration: Infinity,
-              classNames: MODEL_LOAD_TOAST_CLASSNAMES,
-              onDismiss: (dismissedToast) => {
-                if (loadToastIdRef.current !== dismissedToast.id) return;
-                setLoadToastDismissedState(true);
-              },
             });
           } catch {
             // Ignore polling errors.
@@ -1054,12 +1057,20 @@ export function useChatModelRuntime() {
         try {
           await performLoad();
           if (loadToastDismissedRef.current) {
-            toast.success(`${displayName} loaded`);
+            toast.success(`${toastDisplayName} loaded`, {
+              classNames: MODEL_LOADED_TOAST_CLASSNAMES,
+              closeButton: true,
+              duration: 8000,
+            });
           } else {
-            toast.success(`${displayName} loaded`, {
+            toast.success(`${toastDisplayName} loaded`, {
               id: toastId,
               description: undefined,
+              cancel: undefined,
+              classNames: MODEL_LOADED_TOAST_CLASSNAMES,
+              closeButton: true,
               duration: 8000,
+              onDismiss: undefined,
             });
           }
           notifyNative({
@@ -1078,7 +1089,11 @@ export function useChatModelRuntime() {
               toast.error(message, {
                 id: toastId,
                 description: undefined,
+                cancel: undefined,
+                classNames: undefined,
+                closeButton: true,
                 duration: 8000,
+                onDismiss: undefined,
               });
             }
             notifyNative({
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 28c4cd0948..12d63aac88 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -1225,10 +1225,42 @@
 
 /* Lighter shadow + tighter vertical padding than Sonner's defaults; !important because Sonner injects its base rules at runtime. */
 [data-sonner-toast][data-styled='true'] {
-	padding: 10px 16px !important;
+	padding: 12px 18px !important;
 	box-shadow: 0 2px 6px rgba(0, 0, 0, 0.08) !important;
 }
 
+[data-sonner-toast][data-styled='true']:has([data-close-button]):not(:has([data-cancel])) {
+	padding-right: 48px !important;
+}
+
+[data-sonner-toast][data-styled='true']:has([data-cancel]):has([data-close-button]) {
+	padding-right: 88px !important;
+}
+
+[data-sonner-toast][data-styled='true'].chat-model-load-toast,
+[data-sonner-toast][data-styled='true'].chat-model-loaded-toast {
+	padding-top: 14px !important;
+	padding-bottom: 14px !important;
+}
+
+[data-sonner-toast][data-styled='true'].chat-model-loaded-toast [data-close-button] {
+	top: calc(50% - 0.25px) !important;
+	transform: translateY(-50%) !important;
+}
+
+[data-sonner-toast][data-styled='true'].chat-model-load-toast:not(:has([data-cancel])) [data-close-button] {
+	top: calc(50% - 0.25px) !important;
+	transform: translateY(-50%) !important;
+}
+
+[data-sonner-toast][data-styled="true"]:has([data-cancel]) [data-cancel] {
+	position: absolute !important;
+	right: 36px !important;
+	top: 50% !important;
+	transform: translateY(-50%) !important;
+	margin: 0 !important;
+}
+
 /* Boost shadow on dark surfaces; mirrors .shadow-border / .menu-soft-surface pattern. */
 .dark [data-sonner-toast][data-styled='true'] {
 	box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3) !important;
@@ -1391,13 +1423,15 @@
 	mix-blend-mode: normal;
 }
 
-/* Override sonner top: 0 and pin to theme tokens (--gray2 hover ignores data-sonner-theme). */
+/* Keep Sonner close button inside the toast and pin to theme tokens (--gray2 hover ignores data-sonner-theme). */
 [data-sonner-toast][data-styled="true"] [data-close-button] {
 	top: 8px !important;
+	transform: none !important;
 	background: var(--popover) !important;
 	color: var(--popover-foreground) !important;
 	border-color: var(--border) !important;
 }
+
 [data-sonner-toast][data-styled="true"] [data-close-button] svg {
 	stroke-width: 2.25;
 }

From de21723a0daaed3268bbbe78d781802afb577831 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Tue, 2 Jun 2026 08:27:04 -0300
Subject: [PATCH 066/222] Studio: optimize chat streaming by batching renders
 to one per animation frame (#5788)

* Studio: optimize chat streaming by batching renders to one per animation frame

* Fix dev-mode streaming edge case

* Studio: harden streaming markdown coalescing

---------

Co-authored-by: Wasim Yousef Said <wasimysdev@gmail.com>
---
 .../components/assistant-ui/markdown-text.tsx | 53 ++++++++++++++++++-
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index 8e1d0f03b7..8cb33d0ed2 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -382,11 +382,60 @@ function StreamdownBlock(props: BlockProps) {
 }
 const AUDIO_PLAYER_RE = /<audio-player\s+src="([^"]+)"\s*\/>/;
 
+// Coalesce markdown re-parses to one per animation frame while streaming: the
+// runtime notifies on every token (hundreds/sec) and the monitor can't paint
+// that fast. When not streaming we return live text rather than the throttled
+// state, so the final text never lags and a reused instance (parts are keyed by
+// index) shows a completed message's text immediately instead of a stale frame.
+function useRafCoalescedText(text: string, isStreaming: boolean): string {
+  const [displayed, setDisplayed] = useState(text);
+  const pendingRef = useRef(text);
+  const rafRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    pendingRef.current = text;
+    if (!isStreaming) {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+      return;
+    }
+    if (rafRef.current === null) {
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = null;
+        setDisplayed(pendingRef.current);
+      });
+    }
+  }, [text, isStreaming]);
+
+  // Unmount cleanup. Cancel the in-flight rAF and null the handle so a
+  // StrictMode remount isn't gated out by a stale id. Kept separate from the
+  // scheduling effect so it doesn't cancel mid-stream and defeat the throttle.
+  useEffect(() => {
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    };
+  }, []);
+
+  if (isStreaming && text.startsWith(displayed)) {
+    return displayed;
+  }
+  return text;
+}
+
 const MarkdownTextImpl = () => {
   const { text, status } = useMessagePartText();
-  const processedText = useMemo(() => preprocessLaTeX(text), [text]);
+  const displayText = useRafCoalescedText(text, status.type === "running");
+  const processedText = useMemo(
+    () => preprocessLaTeX(displayText),
+    [displayText],
+  );
 
-  const audioMatch = text.match(AUDIO_PLAYER_RE);
+  const audioMatch = displayText.match(AUDIO_PLAYER_RE);
   if (audioMatch) {
     return <AudioPlayer src={audioMatch[1]} />;
   }

From 7381958225d194017ddc768dd36d0d9eca44c5d3 Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Tue, 2 Jun 2026 17:52:19 +0200
Subject: [PATCH 067/222] Configurable upload Cap studio (for training) (#5808)

* studio: cap training dataset uploads

* studio: clean up failed dataset uploads

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* studio: raise upload limits to 500MB

* studio: make upload limit configurable

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* studio: stream upload routes

* studio: split recipe upload caps

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* studio: tighten upload limit handling

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* studio: import settings router directly

* studio: polish upload cap setting control

* studio: cap settings request bodies

* studio: stub settings route in desktop auth test

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/main.py                        | 102 ++++++++++--
 studio/backend/routes/data_recipe/seed.py     |  44 ++---
 studio/backend/routes/datasets.py             |  31 +++-
 studio/backend/routes/settings.py             |  59 +++++++
 studio/backend/storage/studio_db.py           |  47 ++++++
 .../tests/test_dataset_upload_limits.py       |  67 ++++++++
 studio/backend/tests/test_desktop_auth.py     |  42 +++--
 studio/backend/tests/test_middleware.py       |  92 ++++++++++-
 studio/backend/tests/test_sandbox_tools.py    |   5 +-
 studio/backend/utils/upload_limits.py         |  97 +++++++++++
 .../src/features/recipe-studio/api/index.ts   |  15 +-
 .../dialogs/seed/seed-dialog.tsx              |  13 +-
 .../dialogs/seed/unstructured-drop-zone.tsx   |  81 ++++++---
 .../dialogs/seed/upload-limits.ts             |   9 +
 .../src/features/settings/api/upload-limit.ts | 117 +++++++++++++
 .../features/settings/tabs/general-tab.tsx    | 108 +++++++++++-
 .../studio/sections/dataset-section.tsx       | 154 +++++++++++++++---
 .../frontend/src/features/training/index.ts   |   3 +-
 studio/frontend/src/i18n/locales/en.ts        |  55 ++++---
 studio/frontend/src/i18n/locales/zh-CN.ts     |  21 ++-
 20 files changed, 1015 insertions(+), 147 deletions(-)
 create mode 100644 studio/backend/routes/settings.py
 create mode 100644 studio/backend/tests/test_dataset_upload_limits.py
 create mode 100644 studio/backend/utils/upload_limits.py
 create mode 100644 studio/frontend/src/features/recipe-studio/dialogs/seed/upload-limits.ts
 create mode 100644 studio/frontend/src/features/settings/api/upload-limit.ts

diff --git a/studio/backend/main.py b/studio/backend/main.py
index 2768f56f49..d5016980ba 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -243,6 +243,7 @@ from routes import (
     training_history_router,
     training_router,
 )
+from routes.settings import router as settings_router
 from auth import storage
 from auth.authentication import get_current_subject
 from utils.hardware import (
@@ -523,11 +524,15 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
 app.add_middleware(SecurityHeadersMiddleware)
 
 
-# Cap upload body on protected POSTs; default 500 MB, env-tunable.
+# Cap request bodies on protected POSTs. Upload routes get explicit multipart
+# headroom, while non-upload routes keep the default body cap.
 import json as _json_for_413  # noqa: E402
+from utils.upload_limits import (  # noqa: E402
+    UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES,
+    default_request_body_limit_bytes,
+    upload_request_limit_bytes,
+)
 
-
-_MAX_BODY_BYTES = int(os.environ.get("UNSLOTH_STUDIO_MAX_BODY_MB", "500")) * 1024 * 1024
 _BODY_PROTECTED_PREFIXES = (
     "/v1/chat/completions",
     "/v1/completions",
@@ -535,17 +540,50 @@ _BODY_PROTECTED_PREFIXES = (
     "/api/data-recipe",
     "/api/datasets",
     "/api/chat",
+    "/api/settings",
     "/api/train",
     "/api/export",
 )
+_DATASET_UPLOAD_PASSTHROUGH_PREFIX = "/api/datasets/upload"
+_DATA_RECIPE_UNSTRUCTURED_UPLOAD_PASSTHROUGH_PREFIX = (
+    "/api/data-recipe/seed/upload-unstructured-file"
+)
+_BODY_UPLOAD_PASSTHROUGH_PREFIXES = (
+    _DATASET_UPLOAD_PASSTHROUGH_PREFIX,
+    _DATA_RECIPE_UNSTRUCTURED_UPLOAD_PASSTHROUGH_PREFIX,
+)
 
 
-async def _send_413(send, total_bytes: int) -> None:
+def _get_upload_passthrough_request_max_bytes(path: str) -> int:
+    if path.startswith(_DATA_RECIPE_UNSTRUCTURED_UPLOAD_PASSTHROUGH_PREFIX):
+        return upload_request_limit_bytes(UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES)
+    if path.startswith(_DATASET_UPLOAD_PASSTHROUGH_PREFIX):
+        return upload_request_limit_bytes()
+    return default_request_body_limit_bytes()
+
+
+async def _send_411(send) -> None:
+    payload = _json_for_413.dumps(
+        {"detail": "Content-Length required for upload requests."},
+    ).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 411,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(payload)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": payload, "more_body": False})
+
+
+async def _send_413(send, total_bytes: int, max_bytes: int) -> None:
     payload = _json_for_413.dumps(
         {
             "detail": (
-                f"Request body too large "
-                f"({total_bytes:,} bytes; max {_MAX_BODY_BYTES:,})."
+                f"Request body too large ({total_bytes:,} bytes; max {max_bytes:,})."
             )
         },
     ).encode("utf-8")
@@ -565,10 +603,32 @@ async def _send_413(send, total_bytes: int) -> None:
 class MaxBodyMiddleware:
     """Reject oversized bodies on protected POST/PUT/PATCH; raw ASGI so chunked uploads cannot bypass the cap."""
 
-    def __init__(self, app, max_bytes: int, protected_prefixes: tuple):
+    def __init__(
+        self,
+        app,
+        max_bytes_getter,
+        protected_prefixes: tuple,
+        upload_passthrough_prefixes: tuple = (),
+        upload_passthrough_max_bytes_getter = None,
+    ):
         self.app = app
-        self.max_bytes = max_bytes
+        self.max_bytes_getter = max_bytes_getter
         self.protected_prefixes = protected_prefixes
+        self.upload_passthrough_prefixes = upload_passthrough_prefixes
+        self.upload_passthrough_max_bytes_getter = upload_passthrough_max_bytes_getter
+
+    def _upload_passthrough_max_bytes(self, path: str) -> int:
+        if self.upload_passthrough_max_bytes_getter is None:
+            return int(self.max_bytes_getter())
+        try:
+            return int(self.upload_passthrough_max_bytes_getter(path))
+        except TypeError:
+            try:
+                return int(self.upload_passthrough_max_bytes_getter())
+            except Exception:
+                return int(self.max_bytes_getter())
+        except Exception:
+            return int(self.max_bytes_getter())
 
     async def __call__(self, scope, receive, send):
         if scope["type"] != "http":
@@ -582,6 +642,7 @@ class MaxBodyMiddleware:
             await self.app(scope, receive, send)
             return
 
+        max_bytes = int(self.max_bytes_getter())
         declared = None
         for name, value in scope.get("headers", []):
             if name == b"content-length":
@@ -590,8 +651,20 @@ class MaxBodyMiddleware:
                 except (ValueError, UnicodeDecodeError):
                     declared = None
                 break
-        if declared is not None and declared > self.max_bytes:
-            await _send_413(send, declared)
+
+        if any(path.startswith(p) for p in self.upload_passthrough_prefixes):
+            upload_max_bytes = self._upload_passthrough_max_bytes(path)
+            if declared is None:
+                await _send_411(send)
+                return
+            if declared > upload_max_bytes:
+                await _send_413(send, declared, upload_max_bytes)
+                return
+            await self.app(scope, receive, send)
+            return
+
+        if declared is not None and declared > max_bytes:
+            await _send_413(send, declared, max_bytes)
             return
 
         chunks: list = []
@@ -607,8 +680,8 @@ class MaxBodyMiddleware:
             body = msg.get("body", b"") or b""
             if body:
                 total += len(body)
-                if total > self.max_bytes:
-                    await _send_413(send, total)
+                if total > max_bytes:
+                    await _send_413(send, total, max_bytes)
                     return
                 chunks.append(body)
             if not msg.get("more_body", False):
@@ -632,8 +705,10 @@ class MaxBodyMiddleware:
 
 app.add_middleware(
     MaxBodyMiddleware,
-    max_bytes = _MAX_BODY_BYTES,
+    max_bytes_getter = default_request_body_limit_bytes,
     protected_prefixes = _BODY_PROTECTED_PREFIXES,
+    upload_passthrough_prefixes = _BODY_UPLOAD_PASSTHROUGH_PREFIXES,
+    upload_passthrough_max_bytes_getter = _get_upload_passthrough_request_max_bytes,
 )
 
 
@@ -688,6 +763,7 @@ app.include_router(inference_studio_router, prefix = "/api/inference", tags = ["
 # standard /v1/chat/completions path.
 app.include_router(inference_router, prefix = "/v1", tags = ["openai-compat"])
 app.include_router(providers_router, prefix = "/api/providers", tags = ["providers"])
+app.include_router(settings_router, prefix = "/api/settings", tags = ["settings"])
 app.include_router(mcp_servers_router, prefix = "/api/mcp/servers", tags = ["mcp"])
 app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"])
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index 91cf718e6e..a18f8f3e32 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -31,6 +31,14 @@ except ImportError:
     resolve_chunking = None
 from core.data_recipe.jsonable import to_preview_jsonable
 from utils.paths import ensure_dir, seed_uploads_root, unstructured_uploads_root
+from utils.upload_limits import (
+    LOCAL_SEED_UPLOAD_MAX_BYTES,
+    LOCAL_SEED_UPLOAD_MAX_LABEL,
+    UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES,
+    UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL,
+    UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES,
+    UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL,
+)
 
 from models.data_recipe import (
     SeedInspectRequest,
@@ -47,9 +55,6 @@ LOCAL_UPLOAD_EXTS = {".csv", ".json", ".jsonl"}
 UNSTRUCTURED_ALLOWED_EXTS = {".pdf", ".docx", ".txt", ".md"}
 SEED_UPLOAD_DIR = seed_uploads_root()
 UNSTRUCTURED_UPLOAD_ROOT = unstructured_uploads_root()
-MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
-MAX_TOTAL_SIZE = 100 * 1024 * 1024  # 100MB
-
 _SAFE_ID_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
 
 
@@ -405,20 +410,17 @@ def _extract_text_from_file(file_path: Path, ext: str) -> str:
     return normalize_unstructured_text(raw)
 
 
-def _get_block_total_size(block_dir: Path, file_ids: list[str]) -> int:
-    """Sum raw upload sizes for tracked file IDs only."""
-    if not block_dir.exists() or not file_ids:
+def _get_block_total_size(block_dir: Path) -> int:
+    """Sum raw upload sizes for the whole block from server-owned files."""
+    if not block_dir.exists():
         return 0
-    id_set = set(file_ids)
     total = 0
     for f in block_dir.iterdir():
         if not f.is_file():
             continue
         if f.name.endswith(".extracted.txt") or f.name.endswith(".meta.json"):
             continue
-        stem = f.name.split(".")[0]
-        if stem in id_set:
-            total += f.stat().st_size
+        total += f.stat().st_size
     return total
 
 
@@ -426,12 +428,9 @@ def _get_block_total_size(block_dir: Path, file_ids: list[str]) -> int:
 async def upload_unstructured_file(
     file: UploadFile = FastAPIFile(...),
     block_id: str = Form(...),
-    existing_file_ids: str = Form(""),
 ) -> UnstructuredFileUploadResponse:
     _validate_safe_id(block_id, "block_id")
 
-    tracked_ids = [fid.strip() for fid in existing_file_ids.split(",") if fid.strip()]
-
     original_filename = file.filename or "upload"
     ext = Path(original_filename).suffix.lower()
     if ext not in UNSTRUCTURED_ALLOWED_EXTS:
@@ -446,17 +445,19 @@ async def upload_unstructured_file(
     if size_bytes == 0:
         raise HTTPException(400, "Empty file not allowed")
 
-    if size_bytes > MAX_FILE_SIZE:
+    if size_bytes > UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES:
         raise HTTPException(
-            413, f"File too large ({size_bytes} bytes). Maximum is 50MB."
+            413,
+            f"File too large ({size_bytes} bytes). Maximum is {UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL}.",
         )
 
     block_dir = UNSTRUCTURED_UPLOAD_ROOT / block_id
     ensure_dir(block_dir)
-    current_total = _get_block_total_size(block_dir, file_ids = tracked_ids)
-    if current_total + size_bytes > MAX_TOTAL_SIZE:
+    current_total = _get_block_total_size(block_dir)
+    if current_total + size_bytes > UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES:
         raise HTTPException(
-            413, f"Total upload limit ({MAX_TOTAL_SIZE // (1024 * 1024)}MB) exceeded"
+            413,
+            f"Total upload limit ({UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL}) exceeded",
         )
 
     file_id = uuid4().hex
@@ -594,8 +595,11 @@ def inspect_seed_upload(payload: SeedInspectUploadRequest) -> SeedInspectRespons
     file_bytes = _decode_base64_payload(payload.content_base64)
     if not file_bytes:
         raise HTTPException(status_code = 400, detail = "empty upload payload")
-    if len(file_bytes) > MAX_FILE_SIZE:
-        raise HTTPException(status_code = 413, detail = "file too large (max 50MB)")
+    if len(file_bytes) > LOCAL_SEED_UPLOAD_MAX_BYTES:
+        raise HTTPException(
+            status_code = 413,
+            detail = f"file too large (max {LOCAL_SEED_UPLOAD_MAX_LABEL})",
+        )
 
     ensure_dir(SEED_UPLOAD_DIR)
     stored_name = f"{uuid4().hex}_{filename}"
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 206af2a66f..c34d6d8732 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -9,6 +9,7 @@ import base64
 import io
 import json
 import sys
+from contextlib import suppress
 from pathlib import Path
 from uuid import uuid4
 from typing import Optional
@@ -67,6 +68,7 @@ if str(backend_path) not in sys.path:
 
 # Import dataset utilities
 from utils.datasets import check_dataset_format
+from utils.upload_limits import get_upload_limit_bytes, get_upload_limit_label
 from auth.authentication import get_current_subject
 
 router = APIRouter()
@@ -138,6 +140,7 @@ _ARCHIVE_EXTS = (".tar", ".tar.gz", ".tgz", ".gz", ".zst", ".zip", ".txt")
 DATA_EXTS = _TABULAR_EXTS + _ARCHIVE_EXTS
 LOCAL_FILE_EXTS = (".json", ".jsonl", ".csv", ".parquet")
 LOCAL_UPLOAD_EXTS = {".csv", ".json", ".jsonl", ".parquet"}
+# sync: training dataset upload limits are exposed by /api/settings/upload-limit
 LOCAL_DATASETS_ROOT = recipe_datasets_root()
 DATASET_UPLOAD_DIR = dataset_uploads_root()
 
@@ -334,10 +337,30 @@ async def upload_dataset(
     stored_name = f"{uuid4().hex}_{stem}{ext}"
     stored_path = DATASET_UPLOAD_DIR / stored_name
 
-    # Stream file to disk in chunks to avoid holding entire file in memory
-    with open(stored_path, "wb") as f:
-        while chunk := await file.read(1024 * 1024):
-            f.write(chunk)
+    # Stream file to disk in chunks to avoid holding entire file in memory.
+    # Keep a route-level cap so users get a clear training-dataset-specific
+    # error and oversized partial files are not left in the Studio uploads directory.
+    upload_limit_bytes = get_upload_limit_bytes()
+    total_bytes = 0
+    upload_complete = False
+    try:
+        with open(stored_path, "wb") as f:
+            while chunk := await file.read(1024 * 1024):
+                total_bytes += len(chunk)
+                if total_bytes > upload_limit_bytes:
+                    raise HTTPException(
+                        status_code = 413,
+                        detail = (
+                            "Training dataset upload too large. "
+                            f"Maximum is {get_upload_limit_label()}."
+                        ),
+                    )
+                f.write(chunk)
+        upload_complete = True
+    finally:
+        if not upload_complete:
+            with suppress(OSError):
+                stored_path.unlink(missing_ok = True)
 
     if stored_path.stat().st_size == 0:
         stored_path.unlink(missing_ok = True)
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
new file mode 100644
index 0000000000..275fbb678b
--- /dev/null
+++ b/studio/backend/routes/settings.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from auth.authentication import get_current_subject
+from utils.upload_limits import (
+    MAX_UPLOAD_LIMIT_MB,
+    MIN_UPLOAD_LIMIT_MB,
+    default_upload_limit_mb,
+    get_upload_limit_mb,
+    set_upload_limit_mb,
+    upload_limit_bytes,
+    upload_limit_label,
+)
+
+router = APIRouter()
+
+
+class UploadLimitPayload(BaseModel):
+    max_upload_size_mb: int = Field(..., ge = MIN_UPLOAD_LIMIT_MB, le = MAX_UPLOAD_LIMIT_MB)
+
+
+class UploadLimitResponse(BaseModel):
+    max_upload_size_mb: int
+    max_upload_size_bytes: int
+    max_upload_size_label: str
+    default_upload_size_mb: int
+    min_upload_size_mb: int = MIN_UPLOAD_LIMIT_MB
+    max_allowed_upload_size_mb: int = MAX_UPLOAD_LIMIT_MB
+
+
+def _upload_limit_response(limit_mb: int) -> UploadLimitResponse:
+    return UploadLimitResponse(
+        max_upload_size_mb = limit_mb,
+        max_upload_size_bytes = upload_limit_bytes(limit_mb),
+        max_upload_size_label = upload_limit_label(limit_mb),
+        default_upload_size_mb = default_upload_limit_mb(),
+    )
+
+
+@router.get("/upload-limit", response_model = UploadLimitResponse)
+def get_upload_limit(
+    current_subject: str = Depends(get_current_subject),
+) -> UploadLimitResponse:
+    return _upload_limit_response(get_upload_limit_mb())
+
+
+@router.put("/upload-limit", response_model = UploadLimitResponse)
+def update_upload_limit(
+    payload: UploadLimitPayload,
+    current_subject: str = Depends(get_current_subject),
+) -> UploadLimitResponse:
+    try:
+        limit_mb = set_upload_limit_mb(payload.max_upload_size_mb)
+    except ValueError as exc:
+        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+    return _upload_limit_response(limit_mb)
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index 0887eb9ceb..0175e54b35 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -279,6 +279,15 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS app_settings (
+            key TEXT NOT NULL PRIMARY KEY,
+            value_json TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        )
+        """
+    )
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS chat_settings_quarantine (
@@ -1343,6 +1352,44 @@ def list_chat_messages_for_threads(thread_ids: list[str]) -> list[dict]:
         conn.close()
 
 
+def get_app_setting(key: str, fallback = None):
+    conn = get_connection()
+    try:
+        row = conn.execute(
+            "SELECT value_json FROM app_settings WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return fallback
+        return _json_loads(row["value_json"], fallback)
+    finally:
+        conn.close()
+
+
+def upsert_app_settings(settings: dict[str, Any]) -> dict[str, Any]:
+    if not settings:
+        return {}
+    conn = get_connection()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        conn.executemany(
+            """
+            INSERT INTO app_settings (key, value_json, updated_at)
+            VALUES (?, ?, ?)
+            ON CONFLICT(key) DO UPDATE SET
+                value_json = excluded.value_json,
+                updated_at = excluded.updated_at
+            """,
+            [(key, json.dumps(value), now) for key, value in settings.items()],
+        )
+        conn.commit()
+        rows = conn.execute(
+            "SELECT key, value_json FROM app_settings ORDER BY key"
+        ).fetchall()
+        return {row["key"]: _json_loads(row["value_json"], None) for row in rows}
+    finally:
+        conn.close()
+
+
 def list_chat_settings() -> dict[str, Any]:
     conn = get_connection()
     try:
diff --git a/studio/backend/tests/test_dataset_upload_limits.py b/studio/backend/tests/test_dataset_upload_limits.py
new file mode 100644
index 0000000000..0991059318
--- /dev/null
+++ b/studio/backend/tests/test_dataset_upload_limits.py
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for training dataset upload limits and cleanup."""
+
+import asyncio
+import sys
+from pathlib import Path
+from typing import cast
+
+import pytest
+from fastapi import HTTPException, UploadFile
+
+_BACKEND_ROOT = Path(__file__).resolve().parents[1]
+if str(_BACKEND_ROOT) not in sys.path:
+    sys.path.insert(0, str(_BACKEND_ROOT))
+
+from routes import datasets as datasets_route  # noqa: E402
+
+
+class FakeUploadFile:
+    def __init__(self, filename: str, chunks: list[bytes]):
+        self.filename = filename
+        self._chunks = list(chunks)
+
+    async def read(self, _size: int = -1) -> bytes:
+        if not self._chunks:
+            return b""
+        return self._chunks.pop(0)
+
+
+@pytest.fixture(autouse = True)
+def isolate_upload_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(datasets_route, "DATASET_UPLOAD_DIR", tmp_path)
+    monkeypatch.setattr(datasets_route, "get_upload_limit_bytes", lambda: 1024 * 1024)
+    monkeypatch.setattr(datasets_route, "get_upload_limit_label", lambda: "1MB")
+    return tmp_path
+
+
+def test_dataset_upload_under_configured_cap_succeeds(isolate_upload_dir):
+    upload = FakeUploadFile("sample.csv", [b"a,b\n1,2\n"])
+    response = asyncio.run(
+        datasets_route.upload_dataset(
+            cast(UploadFile, upload), current_subject = "test-user"
+        )
+    )
+    stored = Path(response.stored_path)
+    assert response.filename == "sample.csv"
+    assert stored.exists()
+    assert stored.parent == isolate_upload_dir
+    assert stored.read_bytes() == b"a,b\n1,2\n"
+
+
+def test_dataset_upload_over_configured_cap_removes_partial_file(isolate_upload_dir):
+    upload = FakeUploadFile(
+        "sample.csv",
+        [b"x" * (1024 * 1024), b"y"],
+    )
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            datasets_route.upload_dataset(
+                cast(UploadFile, upload), current_subject = "test-user"
+            )
+        )
+    assert exc.value.status_code == 413
+    assert "Maximum is 1MB" in exc.value.detail
+    assert list(isolate_upload_dir.iterdir()) == []
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index b1522dd382..3d01342a5c 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -9,7 +9,7 @@ import sqlite3
 import subprocess
 import sys
 from pathlib import Path
-from types import SimpleNamespace
+from types import ModuleType, SimpleNamespace
 
 import jwt
 import pytest
@@ -429,21 +429,31 @@ def test_desktop_capabilities_json_reports_rollout_safe_flags():
 
 
 def test_health_response_reports_desktop_capability_fields(monkeypatch):
-    router_stub = SimpleNamespace(
-        auth_router = APIRouter(),
-        chat_history_router = APIRouter(),
-        data_recipe_router = APIRouter(),
-        datasets_router = APIRouter(),
-        export_router = APIRouter(),
-        inference_router = APIRouter(),
-        inference_studio_router = APIRouter(),
-        mcp_servers_router = APIRouter(),
-        models_router = APIRouter(),
-        providers_router = APIRouter(),
-        training_history_router = APIRouter(),
-        training_router = APIRouter(),
-    )
-    monkeypatch.setitem(sys.modules, "routes", router_stub)
+    routes_module = ModuleType("routes")
+    routes_module.__path__ = []
+    settings_module = ModuleType("routes.settings")
+    settings_module.router = APIRouter()
+
+    for name, router in {
+        "auth_router": APIRouter(),
+        "chat_history_router": APIRouter(),
+        "data_recipe_router": APIRouter(),
+        "datasets_router": APIRouter(),
+        "export_router": APIRouter(),
+        "inference_router": APIRouter(),
+        "inference_studio_router": APIRouter(),
+        "mcp_servers_router": APIRouter(),
+        "models_router": APIRouter(),
+        "providers_router": APIRouter(),
+        "settings_router": settings_module.router,
+        "training_history_router": APIRouter(),
+        "training_router": APIRouter(),
+    }.items():
+        setattr(routes_module, name, router)
+    routes_module.settings = settings_module
+
+    monkeypatch.setitem(sys.modules, "routes", routes_module)
+    monkeypatch.setitem(sys.modules, "routes.settings", settings_module)
 
     import studio.backend.main as backend_main
 
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index bbaf20298d..85b82f1011 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -33,12 +33,19 @@ def main_module():
 # =====================================================================
 
 
-def _make_protected_app(max_bytes: int, main_module):
+def _make_protected_app(
+    max_bytes: int,
+    main_module,
+    upload_passthrough_prefixes: tuple = (),
+    upload_passthrough_max_bytes_getter = None,
+):
     app = FastAPI()
     app.add_middleware(
         main_module.MaxBodyMiddleware,
-        max_bytes = max_bytes,
-        protected_prefixes = ("/v1/chat/completions", "/api/train"),
+        max_bytes_getter = lambda: max_bytes,
+        protected_prefixes = ("/v1/chat/completions", "/api/settings", "/api/train"),
+        upload_passthrough_prefixes = upload_passthrough_prefixes,
+        upload_passthrough_max_bytes_getter = upload_passthrough_max_bytes_getter,
     )
 
     @app.post("/v1/chat/completions")
@@ -49,6 +56,20 @@ def _make_protected_app(max_bytes: int, main_module):
     async def other(payload: dict):
         return {"ok": True, "unprotected": True}
 
+    @app.put("/api/settings/upload-limit")
+    async def update_upload_limit(payload: dict):
+        return {"ok": True, "limit": payload.get("max_upload_size_mb")}
+
+    @app.post("/api/train/upload")
+    async def upload(request: Request):
+        total = 0
+        chunks = 0
+        async for chunk in request.stream():
+            if chunk:
+                chunks += 1
+                total += len(chunk)
+        return {"ok": True, "chunks": chunks, "total": total}
+
     @app.get("/api/train/status")
     async def status_get():
         return {"ok": True, "get": True}
@@ -78,6 +99,16 @@ class TestMaxBodyMiddleware:
         assert r.status_code == 200
         assert r.json()["unprotected"] is True
 
+    def test_settings_put_body_over_cap_rejected(self, main_module):
+        app = _make_protected_app(1024, main_module)
+        c = TestClient(app)
+        r = c.put(
+            "/api/settings/upload-limit",
+            json = {"max_upload_size_mb": 500, "padding": "x" * 5000},
+        )
+        assert r.status_code == 413
+        assert "too large" in r.json()["detail"].lower()
+
     def test_chunked_upload_over_cap_rejected(self, main_module):
         # Regression: declared-Content-Length-only check could be bypassed
         # by chunked transfer-encoding.
@@ -121,6 +152,61 @@ class TestMaxBodyMiddleware:
         r = c.get("/api/train/status")
         assert r.status_code == 200
 
+    def test_upload_passthrough_uses_dedicated_declared_cap(self, main_module):
+        app = _make_protected_app(
+            128,
+            main_module,
+            upload_passthrough_prefixes = ("/api/train/upload",),
+            upload_passthrough_max_bytes_getter = lambda: 1024,
+        )
+        c = TestClient(app)
+        r = c.post(
+            "/api/train/upload",
+            content = b"x" * 512,
+            headers = {"content-type": "application/octet-stream"},
+        )
+        assert r.status_code == 200
+        assert r.json()["total"] == 512
+
+    def test_upload_passthrough_rejects_declared_body_over_dedicated_cap(
+        self, main_module
+    ):
+        app = _make_protected_app(
+            128,
+            main_module,
+            upload_passthrough_prefixes = ("/api/train/upload",),
+            upload_passthrough_max_bytes_getter = lambda: 256,
+        )
+        c = TestClient(app)
+        r = c.post(
+            "/api/train/upload",
+            content = b"x" * 512,
+            headers = {"content-type": "application/octet-stream"},
+        )
+        assert r.status_code == 413
+        assert "256" in r.json()["detail"]
+
+    def test_upload_passthrough_requires_content_length(self, main_module):
+        app = _make_protected_app(
+            128,
+            main_module,
+            upload_passthrough_prefixes = ("/api/train/upload",),
+            upload_passthrough_max_bytes_getter = lambda: 1024,
+        )
+        c = TestClient(app)
+
+        def gen():
+            yield b"x" * 64
+            yield b"y" * 64
+
+        r = c.post(
+            "/api/train/upload",
+            content = gen(),
+            headers = {"content-type": "application/octet-stream"},
+        )
+        assert r.status_code == 411
+        assert "Content-Length" in r.json()["detail"]
+
 
 # =====================================================================
 # SecurityHeadersMiddleware / CSP
diff --git a/studio/backend/tests/test_sandbox_tools.py b/studio/backend/tests/test_sandbox_tools.py
index 57007a5f66..cd8957c3dd 100644
--- a/studio/backend/tests/test_sandbox_tools.py
+++ b/studio/backend/tests/test_sandbox_tools.py
@@ -345,8 +345,9 @@ class TestSandboxCpuRlimitDefault:
 
 class TestMaxBodyDefault:
     def test_default_is_500_mb(self):
-        src = (_BACKEND_ROOT / "main.py").read_text()
-        assert 'UNSLOTH_STUDIO_MAX_BODY_MB", "500"' in src
+        src = (_BACKEND_ROOT / "utils" / "upload_limits.py").read_text()
+        assert "DEFAULT_UPLOAD_LIMIT_MB = 500" in src
+        assert "UNSLOTH_STUDIO_MAX_BODY_MB" in src
 
 
 class TestBashBlocklistPosition:
diff --git a/studio/backend/utils/upload_limits.py b/studio/backend/utils/upload_limits.py
new file mode 100644
index 0000000000..b8a6a2474b
--- /dev/null
+++ b/studio/backend/utils/upload_limits.py
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared Studio upload/request size limits."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+UPLOAD_LIMIT_SETTING_KEY = "max_upload_size_mb"
+DEFAULT_UPLOAD_LIMIT_MB = 500
+MIN_UPLOAD_LIMIT_MB = 1
+MAX_UPLOAD_LIMIT_MB = 8192
+_BYTES_PER_MB = 1024 * 1024
+MULTIPART_OVERHEAD_BYTES = 10 * _BYTES_PER_MB
+
+LOCAL_SEED_UPLOAD_MAX_BYTES = 100 * _BYTES_PER_MB
+LOCAL_SEED_UPLOAD_MAX_LABEL = "100MB"
+UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES = 500 * _BYTES_PER_MB
+UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL = "500MB"
+UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES = 1024 * _BYTES_PER_MB
+UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL = "1GB"
+
+
+def _coerce_upload_limit_mb(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed < MIN_UPLOAD_LIMIT_MB or parsed > MAX_UPLOAD_LIMIT_MB:
+        return None
+    return parsed
+
+
+def default_upload_limit_mb() -> int:
+    env_value = _coerce_upload_limit_mb(os.environ.get("UNSLOTH_STUDIO_MAX_BODY_MB"))
+    return env_value or DEFAULT_UPLOAD_LIMIT_MB
+
+
+def validate_upload_limit_mb(value: Any) -> int:
+    parsed = _coerce_upload_limit_mb(value)
+    if parsed is None:
+        raise ValueError(
+            f"Upload limit must be a whole number from {MIN_UPLOAD_LIMIT_MB} to {MAX_UPLOAD_LIMIT_MB} MB."
+        )
+    return parsed
+
+
+def get_upload_limit_mb() -> int:
+    try:
+        from storage.studio_db import get_app_setting
+
+        stored = get_app_setting(UPLOAD_LIMIT_SETTING_KEY, None)
+    except Exception:
+        stored = None
+    return _coerce_upload_limit_mb(stored) or default_upload_limit_mb()
+
+
+def set_upload_limit_mb(value: Any) -> int:
+    parsed = validate_upload_limit_mb(value)
+    from storage.studio_db import upsert_app_settings
+
+    upsert_app_settings({UPLOAD_LIMIT_SETTING_KEY: parsed})
+    return parsed
+
+
+def upload_limit_bytes(limit_mb: int | None = None) -> int:
+    return (limit_mb if limit_mb is not None else get_upload_limit_mb()) * _BYTES_PER_MB
+
+
+def get_upload_limit_bytes() -> int:
+    return upload_limit_bytes()
+
+
+def upload_limit_label(limit_mb: int | None = None) -> str:
+    return f"{limit_mb if limit_mb is not None else get_upload_limit_mb()}MB"
+
+
+def get_upload_limit_label() -> str:
+    return upload_limit_label()
+
+
+def default_request_body_limit_bytes() -> int:
+    """Default protected-route body cap for non-upload requests."""
+
+    return default_upload_limit_mb() * _BYTES_PER_MB
+
+
+def upload_request_limit_bytes(file_limit_bytes: int | None = None) -> int:
+    """Request cap for upload routes, including multipart field overhead."""
+
+    return (
+        file_limit_bytes if file_limit_bytes is not None else get_upload_limit_bytes()
+    ) + MULTIPART_OVERHEAD_BYTES
diff --git a/studio/frontend/src/features/recipe-studio/api/index.ts b/studio/frontend/src/features/recipe-studio/api/index.ts
index 06b4bc1f8b..b227b960d1 100644
--- a/studio/frontend/src/features/recipe-studio/api/index.ts
+++ b/studio/frontend/src/features/recipe-studio/api/index.ts
@@ -2,7 +2,10 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { authFetch } from "@/features/auth";
-import { formatFastApiDetail, readFastApiError } from "@/lib/format-fastapi-error";
+import {
+  formatFastApiDetail,
+  readFastApiError,
+} from "@/lib/format-fastapi-error";
 
 const DEFAULT_BASE = "/api/data-recipe";
 
@@ -212,8 +215,10 @@ async function parseErrorResponse(response: Response): Promise<string> {
     // formatFastApiDetail returns null when it cannot flatten the value.
     const formatted = formatFastApiDetail(parsed.detail);
     if (formatted) return formatted;
-    if (typeof parsed.message === "string" && parsed.message) return parsed.message;
-    if (typeof parsed.raw_detail === "string" && parsed.raw_detail) return parsed.raw_detail;
+    if (typeof parsed.message === "string" && parsed.message)
+      return parsed.message;
+    if (typeof parsed.raw_detail === "string" && parsed.raw_detail)
+      return parsed.raw_detail;
     return text;
   } catch {
     return text;
@@ -437,14 +442,10 @@ export async function uploadUnstructuredFile(
   file: File,
   blockId: string,
   signal?: AbortSignal,
-  existingFileIds?: string[],
 ): Promise<UnstructuredFileUploadResponse> {
   const formData = new FormData();
   formData.append("file", file);
   formData.append("block_id", blockId);
-  if (existingFileIds?.length) {
-    formData.append("existing_file_ids", existingFileIds.join(","));
-  }
 
   const res = await authFetch(
     `${DATA_DESIGNER_API_BASE}/seed/upload-unstructured-file`,
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx b/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
index 54eae08f7c..878f9eba7c 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
@@ -44,6 +44,10 @@ import {
 } from "react";
 import { cn } from "@/lib/utils";
 import { UnstructuredDropZone, type FileEntry } from "./unstructured-drop-zone";
+import {
+  LOCAL_SEED_UPLOAD_MAX_BYTES,
+  LOCAL_SEED_UPLOAD_MAX_LABEL,
+} from "./upload-limits";
 import {
   getGithubEnvTokenStatus,
   inspectSeedDataset,
@@ -73,7 +77,6 @@ const SELECTION_OPTIONS: Array<{ value: SeedSelectionType; label: string }> = [
 ];
 
 const LOCAL_ACCEPT = ".csv,.json,.jsonl";
-const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const DEFAULT_CHUNK_SIZE = 1200;
 const DEFAULT_CHUNK_OVERLAP = 200;
 const MAX_CHUNK_SIZE = 20000;
@@ -740,8 +743,10 @@ export function SeedDialog({
           if (!localFile) {
             throw new Error("Select a local CSV/JSON/JSONL file first.");
           }
-          if (localFile.size > MAX_UPLOAD_BYTES) {
-            throw new Error("File too large (max 50MB).");
+          if (localFile.size > LOCAL_SEED_UPLOAD_MAX_BYTES) {
+            throw new Error(
+              `File too large (max ${LOCAL_SEED_UPLOAD_MAX_LABEL}).`,
+            );
           }
           const payload = await fileToBase64Payload(localFile);
           const response = await inspectSeedUpload({
@@ -980,7 +985,7 @@ export function SeedDialog({
                 </Button>
               </div>
               <p className="text-xs text-muted-foreground">
-                Max 50MB per file.
+                Max {LOCAL_SEED_UPLOAD_MAX_LABEL} per file.
               </p>
               {(localFile?.name || config.local_file_name?.trim()) && (
                 <p className="text-xs text-muted-foreground">
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/seed/unstructured-drop-zone.tsx b/studio/frontend/src/features/recipe-studio/dialogs/seed/unstructured-drop-zone.tsx
index 6de7cafba3..c052edebc5 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/seed/unstructured-drop-zone.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/seed/unstructured-drop-zone.tsx
@@ -1,11 +1,21 @@
-import { useCallback, useRef, useState } from "react";
-import { CloudUploadIcon, Cancel01Icon, Loading03Icon, CheckmarkCircle02Icon, Alert02Icon } from "@hugeicons/core-free-icons";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  CloudUploadIcon,
+  Cancel01Icon,
+  Loading03Icon,
+  CheckmarkCircle02Icon,
+  Alert02Icon,
+} from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { uploadUnstructuredFile, removeUnstructuredFile } from "../../api";
+import {
+  UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES,
+  UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL,
+  UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES,
+  UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL,
+} from "./upload-limits";
 
 const ACCEPTED_EXTENSIONS = [".txt", ".pdf", ".docx", ".md"];
-const MAX_FILE_SIZE = 50 * 1024 * 1024;
-const MAX_TOTAL_SIZE = 100 * 1024 * 1024;
 
 type FileEntry = {
   id: string;
@@ -19,7 +29,9 @@ type FileEntry = {
 type UnstructuredDropZoneProps = {
   blockId: string;
   files: FileEntry[];
-  onFilesChange: (files: FileEntry[] | ((prev: FileEntry[]) => FileEntry[])) => void;
+  onFilesChange: (
+    files: FileEntry[] | ((prev: FileEntry[]) => FileEntry[]),
+  ) => void;
   disabled?: boolean;
 };
 
@@ -42,16 +54,19 @@ export function UnstructuredDropZone({
 }: UnstructuredDropZoneProps) {
   const inputRef = useRef<HTMLInputElement>(null);
   const filesRef = useRef(files);
-  filesRef.current = files;
   const [isDragOver, setIsDragOver] = useState(false);
 
+  useEffect(() => {
+    filesRef.current = files;
+  }, [files]);
+
   const totalSize = files.reduce((sum, f) => sum + f.size, 0);
 
   const handleFiles = useCallback(
     async (newFiles: File[]) => {
       const valid = newFiles.filter((f) => {
         if (!isValidExtension(f.name)) return false;
-        if (f.size > MAX_FILE_SIZE) return false;
+        if (f.size > UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES) return false;
         return true;
       });
 
@@ -59,7 +74,8 @@ export function UnstructuredDropZone({
 
       const addedSize = valid.reduce((s, f) => s + f.size, 0);
       const currentTotal = filesRef.current.reduce((sum, f) => sum + f.size, 0);
-      if (currentTotal + addedSize > MAX_TOTAL_SIZE) return;
+      if (currentTotal + addedSize > UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES)
+        return;
 
       const entries: FileEntry[] = valid.map((f) => ({
         id: "",
@@ -78,12 +94,10 @@ export function UnstructuredDropZone({
         let updatedStatus: FileEntry["status"] = "error";
         let updatedError: string | undefined;
         try {
-          const existingIds = filesRef.current.filter((f) => f.id).map((f) => f.id);
           const result = await uploadUnstructuredFile(
             file,
             blockId,
             entry.abortController?.signal,
-            existingIds,
           );
           updatedId = result.file_id;
           updatedStatus = result.status === "ok" ? "ok" : "error";
@@ -98,12 +112,16 @@ export function UnstructuredDropZone({
         onFilesChange((prev) =>
           prev.map((f) =>
             f === entry
-              ? { ...f, id: updatedId, status: updatedStatus, error: updatedError }
+              ? {
+                  ...f,
+                  id: updatedId,
+                  status: updatedStatus,
+                  error: updatedError,
+                }
               : f,
           ),
         );
       }
-
     },
     [blockId, onFilesChange],
   );
@@ -116,7 +134,11 @@ export function UnstructuredDropZone({
       if (entry.status === "uploading" && entry.abortController) {
         entry.abortController.abort();
       }
-      if (entry.id && entry.status === "ok" && !deletedIdsRef.current.has(entry.id)) {
+      if (
+        entry.id &&
+        entry.status === "ok" &&
+        !deletedIdsRef.current.has(entry.id)
+      ) {
         deletedIdsRef.current.add(entry.id);
         void removeUnstructuredFile(blockId, entry.id).catch(() => {});
       }
@@ -174,12 +196,16 @@ export function UnstructuredDropZone({
         onDragLeave={handleDragLeave}
         onClick={handleClick}
       >
-        <HugeiconsIcon icon={CloudUploadIcon} className="text-muted-foreground mb-2 size-8" />
+        <HugeiconsIcon
+          icon={CloudUploadIcon}
+          className="text-muted-foreground mb-2 size-8"
+        />
         <p className="text-muted-foreground text-sm">
           Drop files here or click to browse
         </p>
         <p className="text-muted-foreground/60 mt-1 text-xs">
-          PDF, DOCX, TXT, MD - up to 50MB each, 100MB total
+          PDF, DOCX, TXT, MD - up to {UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL}{" "}
+          each, {UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL} total
         </p>
       </div>
 
@@ -200,13 +226,22 @@ export function UnstructuredDropZone({
               className="flex items-center gap-2 rounded-md border px-3 py-1.5 text-sm"
             >
               {entry.status === "uploading" && (
-                <HugeiconsIcon icon={Loading03Icon} className="text-muted-foreground size-4 animate-spin" />
+                <HugeiconsIcon
+                  icon={Loading03Icon}
+                  className="text-muted-foreground size-4 animate-spin"
+                />
               )}
               {entry.status === "ok" && (
-                <HugeiconsIcon icon={CheckmarkCircle02Icon} className="size-4 text-green-500" />
+                <HugeiconsIcon
+                  icon={CheckmarkCircle02Icon}
+                  className="size-4 text-green-500"
+                />
               )}
               {entry.status === "error" && (
-                <HugeiconsIcon icon={Alert02Icon} className="size-4 text-red-500" />
+                <HugeiconsIcon
+                  icon={Alert02Icon}
+                  className="size-4 text-red-500"
+                />
               )}
               <span className="flex-1 truncate">{entry.name}</span>
               <span className="text-muted-foreground text-xs">
@@ -228,8 +263,14 @@ export function UnstructuredDropZone({
             </div>
           ))}
           <div className="text-muted-foreground flex justify-between px-1 text-xs">
-            <span>{successFiles.length} file{successFiles.length !== 1 ? "s" : ""} uploaded</span>
-            <span>{formatSize(totalSize)} / 100MB</span>
+            <span>
+              {successFiles.length} file{successFiles.length !== 1 ? "s" : ""}{" "}
+              uploaded
+            </span>
+            <span>
+              {formatSize(totalSize)} /{" "}
+              {UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL}
+            </span>
           </div>
         </div>
       )}
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/seed/upload-limits.ts b/studio/frontend/src/features/recipe-studio/dialogs/seed/upload-limits.ts
new file mode 100644
index 0000000000..606179851e
--- /dev/null
+++ b/studio/frontend/src/features/recipe-studio/dialogs/seed/upload-limits.ts
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export const LOCAL_SEED_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
+export const LOCAL_SEED_UPLOAD_MAX_LABEL = "100MB";
+export const UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES = 500 * 1024 * 1024;
+export const UNSTRUCTURED_RECIPE_UPLOAD_MAX_LABEL = "500MB";
+export const UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_BYTES = 1024 * 1024 * 1024;
+export const UNSTRUCTURED_RECIPE_UPLOAD_TOTAL_MAX_LABEL = "1GB";
diff --git a/studio/frontend/src/features/settings/api/upload-limit.ts b/studio/frontend/src/features/settings/api/upload-limit.ts
new file mode 100644
index 0000000000..2ef0458286
--- /dev/null
+++ b/studio/frontend/src/features/settings/api/upload-limit.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+
+export const DEFAULT_UPLOAD_LIMIT_MB = 500;
+export const DEFAULT_UPLOAD_LIMIT_BYTES = DEFAULT_UPLOAD_LIMIT_MB * 1024 * 1024;
+
+const UPLOAD_LIMIT_EVENT = "unsloth-upload-limit-change";
+
+export type UploadLimitSettings = {
+  maxUploadSizeMb: number;
+  maxUploadSizeBytes: number;
+  maxUploadSizeLabel: string;
+  defaultUploadSizeMb: number;
+  minUploadSizeMb: number;
+  maxAllowedUploadSizeMb: number;
+};
+
+type ApiUploadLimitSettings = {
+  // biome-ignore lint/style/useNamingConvention: API schema
+  max_upload_size_mb: number;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  max_upload_size_bytes: number;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  max_upload_size_label: string;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  default_upload_size_mb: number;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  min_upload_size_mb: number;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  max_allowed_upload_size_mb: number;
+};
+
+let cachedUploadLimit: UploadLimitSettings | null = null;
+let inFlightUploadLimit: Promise<UploadLimitSettings> | null = null;
+
+export function getCachedUploadLimitBytes() {
+  return cachedUploadLimit?.maxUploadSizeBytes ?? DEFAULT_UPLOAD_LIMIT_BYTES;
+}
+
+export function getCachedUploadLimitLabel() {
+  return (
+    cachedUploadLimit?.maxUploadSizeLabel ?? `${DEFAULT_UPLOAD_LIMIT_MB}MB`
+  );
+}
+
+export function formatUploadSize(bytes: number) {
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function subscribeUploadLimitSettings(
+  listener: (settings: UploadLimitSettings) => void,
+) {
+  const handleChange = (event: Event) => {
+    listener((event as CustomEvent<UploadLimitSettings>).detail);
+  };
+  window.addEventListener(UPLOAD_LIMIT_EVENT, handleChange);
+  return () => window.removeEventListener(UPLOAD_LIMIT_EVENT, handleChange);
+}
+
+function fromApi(settings: ApiUploadLimitSettings): UploadLimitSettings {
+  return {
+    maxUploadSizeMb: settings.max_upload_size_mb,
+    maxUploadSizeBytes: settings.max_upload_size_bytes,
+    maxUploadSizeLabel: settings.max_upload_size_label,
+    defaultUploadSizeMb: settings.default_upload_size_mb,
+    minUploadSizeMb: settings.min_upload_size_mb,
+    maxAllowedUploadSizeMb: settings.max_allowed_upload_size_mb,
+  };
+}
+
+function cacheUploadLimit(settings: UploadLimitSettings) {
+  cachedUploadLimit = settings;
+  window.dispatchEvent(
+    new CustomEvent(UPLOAD_LIMIT_EVENT, { detail: settings }),
+  );
+  return settings;
+}
+
+async function fetchUploadLimitSettings(): Promise<UploadLimitSettings> {
+  const res = await authFetch("/api/settings/upload-limit");
+  if (!res.ok) {
+    throw new Error(await readFastApiError(res, "Failed to load upload limit"));
+  }
+  return fromApi(await res.json());
+}
+
+export async function loadUploadLimitSettings() {
+  if (cachedUploadLimit) {
+    return cachedUploadLimit;
+  }
+  inFlightUploadLimit ??= fetchUploadLimitSettings()
+    .then(cacheUploadLimit)
+    .finally(() => {
+      inFlightUploadLimit = null;
+    });
+  return inFlightUploadLimit;
+}
+
+export async function updateUploadLimitSettings(
+  maxUploadSizeMb: number,
+): Promise<UploadLimitSettings> {
+  const res = await authFetch("/api/settings/upload-limit", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    // biome-ignore lint/style/useNamingConvention: API schema
+    body: JSON.stringify({ max_upload_size_mb: maxUploadSizeMb }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      await readFastApiError(res, "Failed to update upload limit"),
+    );
+  }
+  return cacheUploadLimit(fromApi(await res.json()));
+}
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index 601854f403..aaaf0a7115 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -15,7 +15,13 @@ import { Switch } from "@/components/ui/switch";
 import { usePlatformStore } from "@/config/env";
 import { resetOnboardingDone } from "@/features/auth";
 import { useChatRuntimeStore } from "@/features/chat";
-import { useSettingsDialogStore } from "@/features/settings";
+import {
+  DEFAULT_UPLOAD_LIMIT_MB,
+  loadUploadLimitSettings,
+  updateUploadLimitSettings,
+  type UploadLimitSettings,
+} from "../api/upload-limit";
+import { useSettingsDialogStore } from "../stores/settings-dialog-store";
 import { LOCALE_STORAGE_KEY, useT } from "@/i18n";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import { useEffect, useRef, useState } from "react";
@@ -107,6 +113,14 @@ export function GeneralTab() {
   const [draftToken, setDraftToken] = useState(hfToken ?? "");
   const [showToken, setShowToken] = useState(false);
   const [confirmOpen, setConfirmOpen] = useState(false);
+  const [uploadLimit, setUploadLimit] = useState<UploadLimitSettings | null>(
+    null,
+  );
+  const [draftUploadLimit, setDraftUploadLimit] = useState(
+    String(DEFAULT_UPLOAD_LIMIT_MB),
+  );
+  const [uploadLimitError, setUploadLimitError] = useState<string | null>(null);
+  const [isSavingUploadLimit, setIsSavingUploadLimit] = useState(false);
 
   const draftRef = useRef(draftToken);
   useEffect(() => {
@@ -132,6 +146,52 @@ export function GeneralTab() {
     if (trimmed !== hfToken) setHfToken(trimmed);
   };
 
+  useEffect(() => {
+    let cancelled = false;
+    void loadUploadLimitSettings()
+      .then((settings) => {
+        if (cancelled) return;
+        setUploadLimit(settings);
+        setDraftUploadLimit(String(settings.maxUploadSizeMb));
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        setUploadLimitError(
+          error instanceof Error ? error.message : "Failed to load upload limit.",
+        );
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const saveUploadLimit = async () => {
+    const parsed = Number(draftUploadLimit);
+    if (!Number.isInteger(parsed)) {
+      setUploadLimitError("Enter a whole number of MB.");
+      return;
+    }
+    const min = uploadLimit?.minUploadSizeMb ?? 1;
+    const max = uploadLimit?.maxAllowedUploadSizeMb ?? 8192;
+    if (parsed < min || parsed > max) {
+      setUploadLimitError(`Enter a value from ${min} to ${max} MB.`);
+      return;
+    }
+    setIsSavingUploadLimit(true);
+    setUploadLimitError(null);
+    try {
+      const settings = await updateUploadLimitSettings(parsed);
+      setUploadLimit(settings);
+      setDraftUploadLimit(String(settings.maxUploadSizeMb));
+    } catch (error) {
+      setUploadLimitError(
+        error instanceof Error ? error.message : "Failed to save upload limit.",
+      );
+    } finally {
+      setIsSavingUploadLimit(false);
+    }
+  };
+
   return (
     <div className="flex flex-col gap-6">
       <header className="flex flex-col gap-1">
@@ -183,6 +243,52 @@ export function GeneralTab() {
         </SettingsRow>
       </SettingsSection>
 
+      <SettingsSection title={t("settings.general.uploads.sectionTitle")}>
+        <SettingsRow
+          label={t("settings.general.uploads.maxUploadSize")}
+          description={t("settings.general.uploads.maxUploadSizeDescription", {
+            defaultSize: String(
+              uploadLimit?.defaultUploadSizeMb ?? DEFAULT_UPLOAD_LIMIT_MB,
+            ),
+          })}
+        >
+          <div className="flex flex-col items-end gap-1">
+            <div className="flex items-center gap-2">
+              <div className="relative w-28">
+                <Input
+                  type="number"
+                  min={uploadLimit?.minUploadSizeMb ?? 1}
+                  max={uploadLimit?.maxAllowedUploadSizeMb ?? 8192}
+                  step={1}
+                  value={draftUploadLimit}
+                  aria-label="Training dataset upload cap in MB"
+                  onChange={(event) => setDraftUploadLimit(event.target.value)}
+                  className="h-8 w-full pr-10"
+                />
+                <span className="pointer-events-none absolute inset-y-0 right-3 flex items-center text-xs font-medium text-muted-foreground">
+                  MB
+                </span>
+              </div>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={isSavingUploadLimit}
+                onClick={() => void saveUploadLimit()}
+              >
+                {isSavingUploadLimit
+                  ? t("common.saving")
+                  : t("common.save")}
+              </Button>
+            </div>
+            {uploadLimitError ? (
+              <span className="max-w-[260px] text-right text-xs text-destructive">
+                {uploadLimitError}
+              </span>
+            ) : null}
+          </div>
+        </SettingsRow>
+      </SettingsSection>
+
       {!chatOnly && (
         <SettingsSection title={t("settings.general.gettingStarted")}>
           <SettingsRow
diff --git a/studio/frontend/src/features/studio/sections/dataset-section.tsx b/studio/frontend/src/features/studio/sections/dataset-section.tsx
index f28977978c..3677b8e1bd 100644
--- a/studio/frontend/src/features/studio/sections/dataset-section.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-section.tsx
@@ -40,12 +40,12 @@ import {
 } from "@/hooks";
 import {
   HfDatasetSubsetSplitSelectors,
+  listLocalDatasets,
   uploadTrainingDataset,
   useDatasetPreviewDialogStore,
   useTrainingConfigStore,
+  type LocalDatasetInfo,
 } from "@/features/training";
-import { listLocalDatasets } from "@/features/training/api/datasets-api";
-import type { LocalDatasetInfo } from "@/features/training/types/datasets";
 import { useNavigate } from "@tanstack/react-router";
 import {
   ArrowDown01Icon,
@@ -68,6 +68,13 @@ import {
   useState,
 } from "react";
 import { toast } from "@/lib/toast";
+import {
+  formatUploadSize,
+  getCachedUploadLimitBytes,
+  getCachedUploadLimitLabel,
+  loadUploadLimitSettings,
+  subscribeUploadLimitSettings,
+} from "@/features/settings/api/upload-limit";
 import { useShallow } from "zustand/react/shallow";
 import { DocumentUploadRedirectDialog } from "./document-upload-redirect-dialog";
 import { translate, useT } from "@/i18n";
@@ -81,18 +88,28 @@ const TRAINING_UPLOAD_EXTENSIONS = [
   ".docx",
   ".txt",
 ] as const;
-const TRAINING_UPLOAD_EXTENSION_SET = new Set<string>(TRAINING_UPLOAD_EXTENSIONS);
+const TRAINING_UPLOAD_EXTENSION_SET = new Set<string>(
+  TRAINING_UPLOAD_EXTENSIONS,
+);
 const TRAINING_UPLOAD_ACCEPT = TRAINING_UPLOAD_EXTENSIONS.join(",");
 const TRAINING_UPLOAD_LABEL = "CSV, JSONL, JSON, Parquet, PDF, DOCX, TXT";
+const TRAINING_DATASET_UPLOAD_LABEL = "CSV, JSONL, JSON, Parquet";
+const DOCUMENT_REDIRECT_LABEL = "PDF/DOCX/TXT open Learning Recipes";
 const DOCUMENT_REDIRECT_EXTENSIONS = new Set([".pdf", ".docx", ".txt"]);
 
-const SEARCH_INPUT_REASONS = new Set(["input-change", "input-paste", "input-clear"]);
+const SEARCH_INPUT_REASONS = new Set([
+  "input-change",
+  "input-paste",
+  "input-clear",
+]);
 const OPEN_LEARNING_RECIPES_ON_ARRIVAL_KEY =
   "data-recipes:open-learning-recipes";
 
 function getFileExtension(fileName: string) {
   const extensionStart = fileName.lastIndexOf(".");
-  return extensionStart >= 0 ? fileName.slice(extensionStart).toLowerCase() : "";
+  return extensionStart >= 0
+    ? fileName.slice(extensionStart).toLowerCase()
+    : "";
 }
 
 function isLikelyLocalDatasetRef(value: string) {
@@ -326,7 +343,11 @@ export function DatasetSection() {
 
   const localResultIds = useMemo(() => {
     const ids = localFilteredDatasets.map((item) => item.id);
-    if (selectedLocalDataset && selectedLocalId && !ids.includes(selectedLocalId)) {
+    if (
+      selectedLocalDataset &&
+      selectedLocalId &&
+      !ids.includes(selectedLocalId)
+    ) {
       ids.push(selectedLocalId);
     }
     return ids;
@@ -353,7 +374,8 @@ export function DatasetSection() {
   ]);
 
   const activeSourceTab = datasetSource === "upload" ? "local" : "huggingface";
-  const comboboxItems = pickerTab === "huggingface" ? hfResultIds : localResultIds;
+  const comboboxItems =
+    pickerTab === "huggingface" ? hfResultIds : localResultIds;
   const comboboxValue =
     pickerTab === "huggingface"
       ? datasetSource === "huggingface"
@@ -367,11 +389,14 @@ export function DatasetSection() {
     !!dataset &&
     !isLikelyLocalDatasetRef(dataset);
 
-  const selectedDatasetName = datasetSource === "upload" ? uploadedFile : dataset;
+  const selectedDatasetName =
+    datasetSource === "upload" ? uploadedFile : dataset;
   const selectedLocalMetadata = selectedLocalDataset?.metadata ?? null;
   const selectedLocalColumns = selectedLocalMetadata?.columns ?? [];
   const selectedLocalRows =
-    selectedLocalDataset?.rows ?? selectedLocalMetadata?.actual_num_records ?? null;
+    selectedLocalDataset?.rows ??
+    selectedLocalMetadata?.actual_num_records ??
+    null;
   const selectedLocalUpdatedAt = selectedLocalDataset?.updated_at ?? null;
 
   const comboboxAnchorRef = useRef<HTMLDivElement>(null);
@@ -384,18 +409,67 @@ export function DatasetSection() {
 
   const [isUploading, setIsUploading] = useState(false);
   const [isDatasetDragOver, setIsDatasetDragOver] = useState(false);
+  const [uploadLimitBytes, setUploadLimitBytes] = useState(
+    getCachedUploadLimitBytes,
+  );
+  const [uploadLimitLabel, setUploadLimitLabel] = useState(
+    getCachedUploadLimitLabel,
+  );
   const [documentRedirectOpen, setDocumentRedirectOpen] = useState(false);
   const [redirectFileName, setRedirectFileName] = useState<string | null>(null);
 
+  useEffect(() => {
+    let cancelled = false;
+    const applyLimit = (settings: {
+      maxUploadSizeBytes: number;
+      maxUploadSizeLabel: string;
+    }) => {
+      setUploadLimitBytes(settings.maxUploadSizeBytes);
+      setUploadLimitLabel(settings.maxUploadSizeLabel);
+    };
+    const unsubscribe = subscribeUploadLimitSettings(applyLimit);
+    void loadUploadLimitSettings().then((settings) => {
+      if (!cancelled) applyLimit(settings);
+    }).catch(() => {});
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, []);
+
   const handleUploadButtonClick = () => {
     fileInputRef.current?.click();
   };
 
+  const getLatestUploadLimit = async () => {
+    try {
+      const settings = await loadUploadLimitSettings();
+      setUploadLimitBytes(settings.maxUploadSizeBytes);
+      setUploadLimitLabel(settings.maxUploadSizeLabel);
+      return settings;
+    } catch {
+      return {
+        maxUploadSizeBytes: uploadLimitBytes,
+        maxUploadSizeLabel: uploadLimitLabel,
+      };
+    }
+  };
+
   const handleFileUpload = async (
     file: File,
     onSuccess: (storedPath: string) => void,
     successMessage: string,
   ) => {
+    const latestLimit = await getLatestUploadLimit();
+    if (file.size > latestLimit.maxUploadSizeBytes) {
+      toast.error("File too large", {
+        description: `${file.name} is ${formatUploadSize(
+          file.size,
+        )}. Training uploads support up to ${latestLimit.maxUploadSizeLabel}.`,
+      });
+      return;
+    }
+
     setIsUploading(true);
     try {
       const uploaded = await uploadTrainingDataset(file);
@@ -430,7 +504,9 @@ export function DatasetSection() {
     await handleFileUpload(file, selectLocalDataset, t("studio.dataset.datasetUploaded"));
   };
 
-  const handleDatasetFileChange = async (event: ChangeEvent<HTMLInputElement>) => {
+  const handleDatasetFileChange = async (
+    event: ChangeEvent<HTMLInputElement>,
+  ) => {
     const file = event.target.files?.[0];
     event.target.value = "";
     if (!file) return;
@@ -560,11 +636,16 @@ export function DatasetSection() {
                 value={comboboxValue}
                 onOpenChange={(open) => {
                   setSearchQuery("");
-                  if (open && (pickerTab === "local" || activeSourceTab === "local")) {
+                  if (
+                    open &&
+                    (pickerTab === "local" || activeSourceTab === "local")
+                  ) {
                     void refreshLocalDatasets();
                   }
                   if (!open) {
-                    setPickerTab(pendingSourceTabRef.current ?? activeSourceTab);
+                    setPickerTab(
+                      pendingSourceTabRef.current ?? activeSourceTab,
+                    );
                     pendingSourceTabRef.current = null;
                   }
                 }}
@@ -586,9 +667,7 @@ export function DatasetSection() {
                   handleInputChange(value, eventDetails)
                 }
                 itemToStringValue={(id) =>
-                  pickerTab === "local"
-                    ? localLabelById.get(id) ?? id
-                    : id
+                  pickerTab === "local" ? (localLabelById.get(id) ?? id) : id
                 }
                 autoHighlight={true}
               >
@@ -635,7 +714,11 @@ export function DatasetSection() {
                           <ComboboxList className="p-1 !max-h-none !overflow-visible">
                             {(id: string) => {
                               return (
-                                <ComboboxItem key={id} value={id} className="gap-2">
+                                <ComboboxItem
+                                  key={id}
+                                  value={id}
+                                  className="gap-2"
+                                >
                                   <Tooltip>
                                     <TooltipTrigger asChild={true}>
                                       <span className="block min-w-0 flex-1 truncate">
@@ -670,7 +753,9 @@ export function DatasetSection() {
                         ) : (
                           <>
                             {localError ? (
-                              <p className="px-2 py-2 text-xs text-destructive">{localError}</p>
+                              <p className="px-2 py-2 text-xs text-destructive">
+                                {localError}
+                              </p>
                             ) : (
                               <ComboboxEmpty className="px-2 py-3">
                                 <div className="flex w-full flex-col items-center gap-2 text-center">
@@ -692,7 +777,11 @@ export function DatasetSection() {
                                 {(id: string) => {
                                   const label = localLabelById.get(id) ?? id;
                                   return (
-                                    <ComboboxItem key={id} value={id} className="gap-2">
+                                    <ComboboxItem
+                                      key={id}
+                                      value={id}
+                                      className="gap-2"
+                                    >
                                       <Tooltip>
                                         <TooltipTrigger asChild={true}>
                                           <span className="block min-w-0 flex-1 truncate">
@@ -814,8 +903,10 @@ export function DatasetSection() {
                   <MetadataRow
                     label={t("studio.dataset.batches")}
                     value={
-                      typeof selectedLocalMetadata?.num_completed_batches === "number" &&
-                      typeof selectedLocalMetadata?.total_num_batches === "number"
+                      typeof selectedLocalMetadata?.num_completed_batches ===
+                        "number" &&
+                      typeof selectedLocalMetadata?.total_num_batches ===
+                        "number"
                         ? `${selectedLocalMetadata.num_completed_batches}/${selectedLocalMetadata.total_num_batches}`
                         : "--"
                     }
@@ -837,7 +928,10 @@ export function DatasetSection() {
               {uploadedEvalFile ? (
                 <div className="flex items-center justify-between gap-2">
                   <div className="flex items-center gap-1.5 overflow-hidden">
-                    <HugeiconsIcon icon={FileAttachmentIcon} className="size-3.5 shrink-0 text-muted-foreground" />
+                    <HugeiconsIcon
+                      icon={FileAttachmentIcon}
+                      className="size-3.5 shrink-0 text-muted-foreground"
+                    />
                     <span className="truncate text-xs">
                       {deriveLocalDatasetName(uploadedEvalFile)}
                     </span>
@@ -863,7 +957,10 @@ export function DatasetSection() {
                     {isUploading ? (
                       <Spinner className="size-3.5" />
                     ) : (
-                      <HugeiconsIcon icon={CloudUploadIcon} className="size-3.5" />
+                      <HugeiconsIcon
+                        icon={CloudUploadIcon}
+                        className="size-3.5"
+                      />
                     )}
                     {isUploading
                       ? t("studio.dataset.uploading")
@@ -962,7 +1059,9 @@ export function DatasetSection() {
                       placeholder="0"
                       value={datasetSliceStart ?? ""}
                       onChange={(e) =>
-                        setDatasetSliceStart(normalizeSliceInput(e.target.value))
+                        setDatasetSliceStart(
+                          normalizeSliceInput(e.target.value),
+                        )
                       }
                     />
                   </div>
@@ -1015,8 +1114,8 @@ export function DatasetSection() {
                 <div className="flex-1 min-w-0">
                   <p className="font-mono text-sm font-medium truncate">
                     {datasetSource === "upload"
-                      ? selectedLocalDataset?.label ??
-                        deriveLocalDatasetName(selectedDatasetName)
+                      ? (selectedLocalDataset?.label ??
+                        deriveLocalDatasetName(selectedDatasetName))
                       : selectedDatasetName}
                   </p>
                   <p className="text-[10px] text-muted-foreground">
@@ -1074,7 +1173,8 @@ export function DatasetSection() {
                     {t("studio.dataset.dropFileOrClick")}
                   </span>
                   <span className="mt-0.5 block truncate text-[10px] text-muted-foreground">
-                    {TRAINING_UPLOAD_LABEL}
+                    {TRAINING_DATASET_UPLOAD_LABEL} · up to{" "}
+                    {uploadLimitLabel}; {DOCUMENT_REDIRECT_LABEL}
                   </span>
                 </span>
               </button>
@@ -1131,7 +1231,7 @@ export function DatasetSection() {
             fileName={redirectFileName}
             onOpenLearningRecipes={handleOpenLearningRecipes}
           />
-      </div>
+        </div>
       </SectionCard>
     </div>
   );
diff --git a/studio/frontend/src/features/training/index.ts b/studio/frontend/src/features/training/index.ts
index 654ddedd03..05f882184f 100644
--- a/studio/frontend/src/features/training/index.ts
+++ b/studio/frontend/src/features/training/index.ts
@@ -16,7 +16,8 @@ export {
 export { useMaxStepsEpochsToggle } from "./hooks/use-max-steps-epochs-toggle";
 export { HfDatasetSubsetSplitSelectors } from "./components/hf-dataset-subset-split-selectors";
 export { useDatasetPreviewDialogStore } from "./stores/dataset-preview-dialog-store";
-export { uploadTrainingDataset } from "./api/datasets-api";
+export { listLocalDatasets, uploadTrainingDataset } from "./api/datasets-api";
+export type { LocalDatasetInfo } from "./types/datasets";
 export { listLocalModels } from "./api/models-api";
 export type { LocalModelInfo } from "./api/models-api";
 export type {
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index bb76f1ebb5..83a04b60c1 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -14,6 +14,7 @@ export const en = {
     new: "New",
     rename: "Rename",
     save: "Save",
+    saving: "Saving...",
     search: "Search",
     shutdown: "Shutdown",
   },
@@ -54,11 +55,11 @@ export const en = {
     dialog: {
       deleteChat: {
         title: "Delete chat",
-        description: "Are you sure you want to delete this chat \"{name}\"?",
+        description: 'Are you sure you want to delete this chat "{name}"?',
       },
       deleteRun: {
         title: "Delete training run",
-        description: "Are you sure you want to delete this run \"{name}\"?",
+        description: 'Are you sure you want to delete this run "{name}"?',
       },
       renameChat: {
         title: "Rename chat",
@@ -111,15 +112,21 @@ export const en = {
       startOnboardingDescription:
         "Open the setup wizard again without changing your account.",
       startOnboardingAction: "Start onboarding",
+      uploads: {
+        sectionTitle: "Uploads",
+        maxUploadSize: "Training dataset upload cap",
+        maxUploadSizeDescription:
+          "Applies to training dataset uploads. Default is {defaultSize} MB.",
+      },
       resetPreferences: {
         sectionTitle: "Danger zone",
         label: "Reset all local preferences",
         description:
-          "Clears local-only preferences. Chats, API access, and DB-backed chat settings are not affected.",
+          "Clears local-only preferences. Chats, API access, and DB-backed settings are not affected.",
         action: "Reset preferences",
         confirmTitle: "Reset all local preferences?",
         confirmDescription:
-          "This clears local-only preferences, then reloads Studio. Chats, API access, and DB-backed chat settings are not affected.",
+          "This clears local-only preferences, then reloads Studio. Chats, API access, and DB-backed settings are not affected.",
         confirmAction: "Reset and reload",
       },
     },
@@ -184,8 +191,7 @@ export const en = {
       clearHistoryDescription: "Delete local chat history from this device.",
       clearAction: "Clear",
       clearAllChats: "Clear all chats",
-      clearAllChatsDescription:
-        "Permanently delete every chat on this device.",
+      clearAllChatsDescription: "Permanently delete every chat on this device.",
       noChatsToClear: "No chats to clear.",
       clearOneChatDescription:
         "Permanently delete the only chat on this device.",
@@ -209,8 +215,7 @@ export const en = {
         "{clearedCount} chats cleared; {remainingCount} chats remain. Please retry.",
       oneChatClearedRemain:
         "1 chat cleared; {remainingCount} chats remain. Please retry.",
-      oneChatClearedRemainOne:
-        "1 chat cleared; 1 chat remains. Please retry.",
+      oneChatClearedRemainOne: "1 chat cleared; 1 chat remains. Please retry.",
       storageClearFailedOne:
         "A storage clear failed; 1 chat may remain. Please retry.",
       storageClearFailed:
@@ -223,7 +228,8 @@ export const en = {
     },
     apiKeys: {
       title: "API",
-      description: "Access Unsloth programmatically via the OpenAI-compatible API.",
+      description:
+        "Access Unsloth programmatically via the OpenAI-compatible API.",
       readDocs: "Read the API docs",
       noAccess: "No API access yet.",
       newBadge: "New",
@@ -261,10 +267,10 @@ export const en = {
       actionsFor: "Actions for {name}",
       copyPrefix: "Copy prefix",
       revokeToken: "Revoke token",
-      revokeTitle: "Revoke access token \"{name}\"?",
+      revokeTitle: 'Revoke access token "{name}"?',
       revokeDescription:
         "Applications using this token will immediately lose access. This cannot be undone.",
-      revokeAction: "Revoke \"{name}\"",
+      revokeAction: 'Revoke "{name}"',
       revoking: "Revoking...",
     },
     about: {
@@ -361,7 +367,8 @@ export const en = {
       fasterTrainingBadge: "2x Faster Training",
       baseModel: "Base model",
       localModel: "Local Model",
-      localModelTooltip: "Path to a locally downloaded model or a custom HF repo.",
+      localModelTooltip:
+        "Path to a locally downloaded model or a custom HF repo.",
       scanningLocalAndCachedModels: "Scanning local and cached models...",
       scanning: "Scanning...",
       scanningLocalModels: "Scanning local models...",
@@ -410,8 +417,7 @@ export const en = {
       noLocalDatasetsYet: "No local datasets yet.",
       noLocalDatasetsMatchSearch: "No local datasets match search.",
       openDataRecipes: "Open Data Recipes",
-      browsingSource:
-        "Browsing {browsing}. Current selection stays {current}.",
+      browsingSource: "Browsing {browsing}. Current selection stays {current}.",
       localDatasets: "Local datasets",
       localDataset: "Local dataset",
       localDatasetRows: " / {count} rows",
@@ -471,7 +477,8 @@ export const en = {
       maxStepsTooltip: "Override total optimizer steps.",
       epochsTooltip: "Number of full passes over the dataset.",
       epochsDescription: "Each epoch is one full pass over your dataset.",
-      maxStepsDescription: "Limits training to a fixed number of optimizer steps.",
+      maxStepsDescription:
+        "Limits training to a fixed number of optimizer steps.",
       contextLength: "Context Length",
       contextLengthTooltip: "Maximum number of tokens per training sample.",
       customContextLength: "Enter a custom value",
@@ -487,11 +494,13 @@ export const en = {
       embeddingLearningRateDescription:
         "Leave blank to use lr/10 (recommended). Typical range is 2x-10x smaller than the main learning rate.",
       rank: "Rank",
-      rankTooltip: "Dimension of the low-rank matrices. Higher = more capacity.",
+      rankTooltip:
+        "Dimension of the low-rank matrices. Higher = more capacity.",
       alpha: "Alpha",
       alphaTooltip: "Scaling factor for LoRA updates. Usually 2x rank.",
       dropout: "Dropout",
-      dropoutTooltip: "Dropout probability for LoRA layers to reduce overfitting.",
+      dropoutTooltip:
+        "Dropout probability for LoRA layers to reduce overfitting.",
       visionLayers: "Vision layers",
       languageLayers: "Language layers",
       attentionModules: "Attention modules",
@@ -529,7 +538,8 @@ export const en = {
       weightDecay: "Weight Decay",
       weightDecayTooltip: "L2 regularization to prevent overfitting.",
       warmupSteps: "Warmup Steps",
-      warmupStepsTooltip: "Gradually increase LR at training start for stability.",
+      warmupStepsTooltip:
+        "Gradually increase LR at training start for stability.",
       scheduleEpochsTooltip:
         "Number of full passes over the dataset. Set 0 to run by max steps.",
       saveSteps: "Save Steps",
@@ -586,7 +596,8 @@ export const en = {
       exportModel: "Export Model",
       milestone: "Milestone",
       halfwayDone: "Halfway done. Training is past 50%.",
-      doneNextStep: "Training done. Next step: compare base vs fine-tuned outputs.",
+      doneNextStep:
+        "Training done. Next step: compare base vs fine-tuned outputs.",
     },
     history: {
       title: "History",
@@ -632,7 +643,8 @@ export const en = {
     },
     charts: {
       settings: "Chart Settings",
-      settingsDescription: "Tune chart presentation while training keeps running.",
+      settingsDescription:
+        "Tune chart presentation while training keeps running.",
       openSettings: "Open chart settings",
       viewWindow: "View window",
       viewWindowDescription: "Show latest steps only or the full history.",
@@ -667,7 +679,8 @@ export const en = {
       waitingForFirstEvaluationStep: "Waiting for first evaluation step...",
       evaluationNotConfigured: "Evaluation not configured",
       evalChartWillAppear: "Chart will appear once eval_steps is reached",
-      setEvalDatasetAndSteps: "Set eval dataset & eval_steps to track eval loss",
+      setEvalDatasetAndSteps:
+        "Set eval dataset & eval_steps to track eval loss",
     },
     progress: {
       title: "Training Progress",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 4074a5760b..f7075eb887 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -17,6 +17,7 @@ export const zhCN = {
     new: "新增",
     rename: "重命名",
     save: "保存",
+    saving: "保存中...",
     search: "搜索",
     shutdown: "关闭服务",
   },
@@ -108,15 +109,21 @@ export const zhCN = {
       startOnboarding: "开始引导",
       startOnboardingDescription: "重新打开设置向导，不会更改你的账号。",
       startOnboardingAction: "开始引导",
+      uploads: {
+        sectionTitle: "上传",
+        maxUploadSize: "训练数据集上传上限",
+        maxUploadSizeDescription:
+          "适用于训练数据集上传。默认值为 {defaultSize} MB。",
+      },
       resetPreferences: {
         sectionTitle: "危险区域",
         label: "重置所有本地偏好设置",
         description:
-          "清除仅保存在本地的偏好设置。聊天、API 访问权限和数据库中的聊天设置不会受到影响。",
+          "清除仅保存在本地的偏好设置。聊天、API 访问权限和数据库中的设置不会受到影响。",
         action: "重置偏好设置",
         confirmTitle: "重置所有本地偏好设置？",
         confirmDescription:
-          "这会清除仅保存在本地的偏好设置，然后重新加载 Studio。聊天、API 访问权限和数据库中的聊天设置不会受到影响。",
+          "这会清除仅保存在本地的偏好设置，然后重新加载 Studio。聊天、API 访问权限和数据库中的设置不会受到影响。",
         confirmAction: "重置并重新加载",
       },
     },
@@ -243,10 +250,10 @@ export const zhCN = {
       actionsFor: "{name} 的操作",
       copyPrefix: "复制前缀",
       revokeToken: "撤销 token",
-      revokeTitle: "撤销访问 token \"{name}\"？",
+      revokeTitle: '撤销访问 token "{name}"？',
       revokeDescription:
         "使用此 token 的应用会立即失去访问权限。此操作无法撤销。",
-      revokeAction: "撤销 \"{name}\"",
+      revokeAction: '撤销 "{name}"',
       revoking: "撤销中...",
     },
     about: {
@@ -407,8 +414,7 @@ export const zhCN = {
         "可选。如果未提供，将从训练数据中切分出一小部分。",
       advanced: "高级",
       targetFormat: "目标格式",
-      targetFormatTooltip:
-        "训练数据的格式。自动检测对大多数数据集都有效。",
+      targetFormatTooltip: "训练数据的格式。自动检测对大多数数据集都有效。",
       auto: "自动",
       rawText: "原始文本",
       trainSplitStart: "训练切分起始",
@@ -505,8 +511,7 @@ export const zhCN = {
       weightDecayTooltip: "L2 正则化，用于防止过拟合。",
       warmupSteps: "预热步数",
       warmupStepsTooltip: "在训练开始时逐步提高学习率，提升稳定性。",
-      scheduleEpochsTooltip:
-        "完整遍历数据集的次数。设为 0 则按最大步数运行。",
+      scheduleEpochsTooltip: "完整遍历数据集的次数。设为 0 则按最大步数运行。",
       saveSteps: "保存步数",
       saveStepsTooltip: "每 N 步保存一次检查点。0 表示禁用。",
       evalSteps: "评估步数",

From 85692f1c1c0c19792b27f9e41d603bff776342ff Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Tue, 2 Jun 2026 13:26:15 -0300
Subject: [PATCH 068/222] Studio: persist Tauri window size and maximized state
 across launches (#5799)

* Studio: persist Tauri window size and maximized state across launches

* Studio: keep window state under the app home dir, not ~/.config

* Undo an unnecessary change

* Address Gemini's feedback

* Revert to tauri-plugin-window-state implementation

* fix(Studio): restore saved window size before default layout

* Fix cross-platform window-state restore

* fix(Studio): avoid clobbering saved window size

---------

Co-authored-by: Wasim Yousef Said <wasimysdev@gmail.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/frontend/package-lock.json          | 10 ++++
 studio/frontend/package.json               |  1 +
 studio/frontend/src/app/provider.tsx       | 62 +++++++++++++++-------
 studio/src-tauri/Cargo.lock                | 16 ++++++
 studio/src-tauri/Cargo.toml                |  1 +
 studio/src-tauri/capabilities/default.json |  3 +-
 studio/src-tauri/src/main.rs               | 16 ++++++
 7 files changed, 88 insertions(+), 21 deletions(-)

diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index 4afee8a916..e66f62d2f2 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -37,6 +37,7 @@
         "@tauri-apps/plugin-opener": "^2.5.3",
         "@tauri-apps/plugin-process": "^2.3.1",
         "@tauri-apps/plugin-updater": "^2.10.1",
+        "@tauri-apps/plugin-window-state": "^2.4.1",
         "@toolwind/corner-shape": "^0.0.8-3",
         "@xyflow/react": "^12.10.0",
         "assistant-stream": "0.3.12",
@@ -6239,6 +6240,15 @@
         "@tauri-apps/api": "^2.10.1"
       }
     },
+    "node_modules/@tauri-apps/plugin-window-state": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/plugin-window-state/-/plugin-window-state-2.4.1.tgz",
+      "integrity": "sha512-OuvdrzyY8Q5Dbzpj+GcrnV1iCeoZbcFdzMjanZMMcAEUNy/6PH5pxZPXpaZLOR7whlzXiuzx0L9EKZbH7zpdRw==",
+      "license": "MIT OR Apache-2.0",
+      "dependencies": {
+        "@tauri-apps/api": "^2.8.0"
+      }
+    },
     "node_modules/@toolwind/corner-shape": {
       "version": "0.0.8-3",
       "resolved": "https://registry.npmjs.org/@toolwind/corner-shape/-/corner-shape-0.0.8-3.tgz",
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 66b821d6c7..40e9458d93 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -46,6 +46,7 @@
     "@tauri-apps/plugin-opener": "^2.5.3",
     "@tauri-apps/plugin-process": "^2.3.1",
     "@tauri-apps/plugin-updater": "^2.10.1",
+    "@tauri-apps/plugin-window-state": "^2.4.1",
     "@toolwind/corner-shape": "^0.0.8-3",
     "@xyflow/react": "^12.10.0",
     "assistant-stream": "0.3.12",
diff --git a/studio/frontend/src/app/provider.tsx b/studio/frontend/src/app/provider.tsx
index 83238dadf0..6f3c7618be 100644
--- a/studio/frontend/src/app/provider.tsx
+++ b/studio/frontend/src/app/provider.tsx
@@ -26,6 +26,9 @@ interface AppProviderProps {
 type TauriWindowMode = "setup" | "app";
 type WindowLayoutGuard = () => boolean;
 
+const MIN_WINDOW_WIDTH = 900;
+const MIN_WINDOW_HEIGHT = 600;
+
 async function showSetupWindow(isCurrent: WindowLayoutGuard): Promise<void> {
   const { getCurrentWindow } = await import("@tauri-apps/api/window");
   if (!isCurrent()) return;
@@ -39,35 +42,54 @@ async function showSetupWindow(isCurrent: WindowLayoutGuard): Promise<void> {
 
 async function applyAppWindowLayout(isCurrent: WindowLayoutGuard): Promise<void> {
   const { getCurrentWindow, currentMonitor, LogicalSize } = await import("@tauri-apps/api/window");
+  const { invoke } = await import("@tauri-apps/api/core");
+  const { restoreStateCurrent, StateFlags } = await import("@tauri-apps/plugin-window-state");
   if (!isCurrent()) return;
 
   const win = getCurrentWindow();
-  const monitor = await currentMonitor();
+  // Decide first-launch vs restore from the on-disk state file BEFORE touching the
+  // window. Probing the window itself after restoreStateCurrent is unreliable:
+  // on GTK, set_size against a hidden window is deferred until show(), so
+  // innerSize() reads a stale value and any baseline fallback would overwrite the
+  // queued restore. On macOS the same probe works, hence the inconsistency
+  // between previous iterations of this code.
+  const hasSavedState = await invoke<boolean>("has_saved_window_state");
   if (!isCurrent()) return;
 
-  let finalW = 900;
-  let finalH = 600;
-
-  if (monitor) {
-    const scale = monitor.scaleFactor;
-    const screenW = monitor.size.width / scale;
-    const screenH = monitor.size.height / scale;
-
-    finalW = Math.max(900, Math.round(screenW * 0.75));
-    const targetH = Math.max(600, Math.round(finalW / 1.618));
-    finalH = Math.min(targetH, Math.round(screenH * 0.85));
-  }
-
-  if (!isCurrent()) return;
-  await win.setSize(new LogicalSize(finalW, finalH));
-  if (!isCurrent()) return;
-  await win.setSizeConstraints({ minWidth: 900, minHeight: 600 });
-  if (!isCurrent()) return;
   await win.setResizable(true);
   if (!isCurrent()) return;
-  await win.center();
+
+  if (hasSavedState) {
+    // Subsequent launch: the plugin handles size, position, and maximized,
+    // with built-in off-screen protection (monitor-intersection check) for
+    // positions saved on a now-disconnected display.
+    await restoreStateCurrent(
+      StateFlags.SIZE | StateFlags.POSITION | StateFlags.MAXIMIZED,
+    );
+  } else {
+    // First launch: fit to the current monitor and center.
+    const monitor = await currentMonitor();
+    if (!isCurrent()) return;
+    let finalW = MIN_WINDOW_WIDTH;
+    let finalH = MIN_WINDOW_HEIGHT;
+    if (monitor) {
+      const scale = monitor.scaleFactor;
+      const screenW = monitor.size.width / scale;
+      const screenH = monitor.size.height / scale;
+      finalW = Math.max(MIN_WINDOW_WIDTH, Math.round(screenW * 0.75));
+      const targetH = Math.max(MIN_WINDOW_HEIGHT, Math.round(finalW / 1.618));
+      finalH = Math.min(targetH, Math.round(screenH * 0.85));
+    }
+    await win.setSize(new LogicalSize(finalW, finalH));
+    if (!isCurrent()) return;
+    await win.center();
+  }
   if (!isCurrent()) return;
   await win.show();
+  if (!isCurrent()) return;
+  // Apply constraints after restore/show. Setting constraints before plugin restore
+  // can emit a Resized event and overwrite the plugin's cached saved size.
+  await win.setSizeConstraints({ minWidth: MIN_WINDOW_WIDTH, minHeight: MIN_WINDOW_HEIGHT });
 }
 
 async function showWindowFallback(): Promise<void> {
diff --git a/studio/src-tauri/Cargo.lock b/studio/src-tauri/Cargo.lock
index df350e4011..b2398b9932 100644
--- a/studio/src-tauri/Cargo.lock
+++ b/studio/src-tauri/Cargo.lock
@@ -4751,6 +4751,21 @@ dependencies = [
  "zip",
 ]
 
+[[package]]
+name = "tauri-plugin-window-state"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73736611e14142408d15353e21e3cca2f12a3cfb523ad0ce85999b6d2ef1a704"
+dependencies = [
+ "bitflags 2.11.0",
+ "log",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "tauri-runtime"
 version = "2.10.1"
@@ -5395,6 +5410,7 @@ dependencies = [
  "tauri-plugin-process",
  "tauri-plugin-single-instance",
  "tauri-plugin-updater",
+ "tauri-plugin-window-state",
  "tokio",
  "windows 0.62.2",
  "windows-sys 0.59.0",
diff --git a/studio/src-tauri/Cargo.toml b/studio/src-tauri/Cargo.toml
index 4002ab420d..2250f2774f 100644
--- a/studio/src-tauri/Cargo.toml
+++ b/studio/src-tauri/Cargo.toml
@@ -29,6 +29,7 @@ tauri-plugin-clipboard-manager = "2"
 tauri-plugin-dialog = "2"
 rand = "0.10.0"
 tauri-plugin-notification = "2.3.3"
+tauri-plugin-window-state = "2"
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
diff --git a/studio/src-tauri/capabilities/default.json b/studio/src-tauri/capabilities/default.json
index 413fa14cc1..232472d6db 100644
--- a/studio/src-tauri/capabilities/default.json
+++ b/studio/src-tauri/capabilities/default.json
@@ -28,6 +28,7 @@
       "allow": [{ "url": "https://*" }, { "url": "http://*" }, { "url": "mailto:*" }]
     },
     "updater:default",
-    "clipboard-manager:allow-write-text"
+    "clipboard-manager:allow-write-text",
+    "window-state:default"
   ]
 }
diff --git a/studio/src-tauri/src/main.rs b/studio/src-tauri/src/main.rs
index d07ff5e9d6..498cd81579 100644
--- a/studio/src-tauri/src/main.rs
+++ b/studio/src-tauri/src/main.rs
@@ -23,6 +23,15 @@ use std::fs;
 use tauri::menu::{MenuBuilder, MenuItemBuilder};
 use tauri::tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent};
 use tauri::{Emitter, Manager};
+use tauri_plugin_window_state::{AppHandleExt, StateFlags};
+
+#[tauri::command]
+fn has_saved_window_state(app: tauri::AppHandle) -> bool {
+    let Ok(dir) = app.path().app_config_dir() else {
+        return false;
+    };
+    dir.join(app.filename()).is_file()
+}
 
 fn setup_logging() {
     let mut loggers: Vec<Box<dyn SharedLogger>> = vec![];
@@ -173,6 +182,12 @@ fn main() {
         .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_updater::Builder::new().build())
         .plugin(tauri_plugin_clipboard_manager::init())
+        .plugin(
+            tauri_plugin_window_state::Builder::new()
+                .with_state_flags(StateFlags::SIZE | StateFlags::POSITION | StateFlags::MAXIMIZED)
+                .skip_initial_state("main")
+                .build(),
+        )
         .manage(diagnostics::new_diagnostics_state())
         .manage(install::new_install_state())
         .manage(native_intents::new_native_intake_state())
@@ -204,6 +219,7 @@ fn main() {
             native_intents::register_artifact_path,
             native_intents::reveal_path_token,
             native_intents::open_path_token,
+            has_saved_window_state,
         ])
         .setup(|app| {
             #[cfg(any(target_os = "windows", target_os = "linux"))]

From 21ddb71bedb62ee3a5f6845c69a2d376eeb6dae9 Mon Sep 17 00:00:00 2001
From: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
Date: Wed, 3 Jun 2026 10:18:57 +0400
Subject: [PATCH 069/222] Guard model-load success path against mid-refresh
 cancellation (#5944)

* Guard model-load success path against mid-refresh cancellation

* Skip refresh state writes when cancelled during model load
---
 .../features/chat/hooks/use-chat-model-runtime.ts   | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 8771bc888a..e6892b34fd 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -255,7 +255,8 @@ export function useChatModelRuntime() {
     [],
   );
 
-  const refresh = useCallback(async () => {
+  const refresh = useCallback(async (options?: { signal?: AbortSignal }) => {
+    const signal = options?.signal;
     setModelsError(null);
     try {
       const [listRes, statusRes, lorasRes] = await Promise.all([
@@ -264,6 +265,11 @@ export function useChatModelRuntime() {
         listLoras(),
       ]);
 
+      // Cancellation can land while the requests above are in flight (e.g. the
+      // user cancels a load during this refresh). Bail before writing any
+      // backend state back into the store -- cancelLoading already cleared it.
+      if (signal?.aborted) return;
+
       setModels(listRes.models.map(toChatModelSummary));
       setLoras(lorasRes.loras.map(toLoraSummary));
 
@@ -405,6 +411,7 @@ export function useChatModelRuntime() {
         });
       }
     } catch (error) {
+      if (signal?.aborted) return;
       const message =
         error instanceof Error ? error.message : "Failed to load models";
       setModelsError(message);
@@ -761,7 +768,7 @@ export function useChatModelRuntime() {
                 store.setParams({ ...store.params, ...p });
               }
             }
-            await refresh();
+            await refresh({ signal: abortCtrl.signal });
           } catch (error) {
             // Skip rollback if user cancelled -- model is already being unloaded.
             if (abortCtrl.signal.aborted) throw error;
@@ -1056,6 +1063,8 @@ export function useChatModelRuntime() {
 
         try {
           await performLoad();
+          // User cancelled mid-refresh; cancelLoading handles teardown.
+          if (abortCtrl.signal.aborted) return;
           if (loadToastDismissedRef.current) {
             toast.success(`${toastDisplayName} loaded`, {
               classNames: MODEL_LOADED_TOAST_CLASSNAMES,

From 1798ebe3f30281978abdc7e409bd91a11a1faa8a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 3 Jun 2026 01:10:55 -0700
Subject: [PATCH 070/222] [pre-commit.ci] pre-commit autoupdate (#5935)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.15.14 → v0.15.15](https://github.com/astral-sh/ruff-pre-commit/compare/v0.15.14...v0.15.15)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1919fac9c5..8cfa7f998b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.14
+    rev: v0.15.15
     hooks:
       - id: ruff
         args:

From f4873182e068fb43b442af21678550a58e3a7a58 Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Wed, 3 Jun 2026 07:03:43 -0500
Subject: [PATCH 071/222] Add None/empty content detection for conversation
 datasets (#4438)

Adds studio/backend/utils/datasets/dataset_none_detect.py, a standalone scanner that reports None/empty content turns in alpaca, chatml, sharegpt, and gptoss datasets without modifying data, plus generator and runner scripts under tests/utils. Depends only on the datasets library and is not wired into the package init, so it stays import-light.
---
 .../utils/datasets/dataset_none_detect.py     | 888 ++++++++++++++++++
 tests/utils/generate_dataset_with_none.py     | 265 ++++++
 tests/utils/run_none_detect_tests.py          | 748 +++++++++++++++
 3 files changed, 1901 insertions(+)
 create mode 100644 studio/backend/utils/datasets/dataset_none_detect.py
 create mode 100644 tests/utils/generate_dataset_with_none.py
 create mode 100644 tests/utils/run_none_detect_tests.py

diff --git a/studio/backend/utils/datasets/dataset_none_detect.py b/studio/backend/utils/datasets/dataset_none_detect.py
new file mode 100644
index 0000000000..1e884271cc
--- /dev/null
+++ b/studio/backend/utils/datasets/dataset_none_detect.py
@@ -0,0 +1,888 @@
+"""
+dataset_none_detect.py
+
+Detect None/empty content turns in conversation datasets.
+Reports findings without modifying data.
+
+Usage:
+    from .dataset_none_detect import scan_dataset, print_report
+    stats = scan_dataset(dataset)               # auto-detect + scan
+    stats = scan_dataset(dataset, fmt="chatml")  # explicit format
+    print_report(stats, stats["format"])
+
+Dependencies: only `datasets` (already in studio/unsloth) + stdlib.
+
+Supported formats (via FORMAT_REGISTRY):
+    alpaca     instruction/output            instruction + output must be set
+    chatml     messages/conversations/texts  role + content per turn
+    sharegpt   conversations                 from/value per turn
+    gptoss     messages (alias: gpt-oss)     role/content; has a developer turn
+
+Any role/content chat template matches the chatml entry, so new templates need
+no change; add a FORMAT_REGISTRY entry only for a genuinely new column/turn shape.
+"""
+
+from datasets import Dataset
+
+# ---------------------------------------------------------------------------
+# Conversation column probing (shared by detection + scanning)
+# ---------------------------------------------------------------------------
+
+# Candidate column names for conversational datasets, checked in priority order.
+CONVERSATION_COLUMNS = ("messages", "conversations", "texts")
+
+# Minimum turn key sets that identify a column as conversational (not e.g. messages=[{"id":1}]).
+_CHAT_KEY_SETS = (frozenset({"role", "content"}), frozenset({"from", "value"}))
+
+
+def _probe_conversation(dataset: Dataset, candidates = None):
+    """
+    Probe a dataset for its conversation column and turn structure.
+
+    candidates - iterable of column names to try, in priority order.
+                 Defaults to CONVERSATION_COLUMNS when None.
+
+    Returns a dict with:
+        column    - name of the conversation column found
+        turn_keys - set of keys present in the first turn dict
+        roles     - set of all role values seen across the first few samples
+
+    Returns None if no conversation column is found.
+    """
+    if candidates is None:
+        candidates = CONVERSATION_COLUMNS
+    columns = set(dataset.column_names)
+    # Remember the first all-corrupt candidate, but keep probing: a later column
+    # may be healthy and should win (e.g. bad messages, good conversations).
+    all_corrupt_fallback = None
+    for col in candidates:
+        if col not in columns:
+            continue
+        # Scan up to 100 rows - row 0 alone may be empty or malformed.
+        first = None
+        for i in range(min(len(dataset), 100)):
+            sample = dataset[i][col]
+            if not isinstance(sample, list) or len(sample) == 0:
+                continue
+            # Skip non-dict leading turns (e.g. [None, {"role": ...}]).
+            first_turn = next((t for t in sample if isinstance(t, dict)), None)
+            if first_turn is not None:
+                first = first_turn
+                break
+        if first is None:
+            # No usable dict turn in 100 rows. Record an all_corrupt fallback,
+            # marking it plausible only if we saw turn-shaped data (a None cell or
+            # a list holding a dict/None turn); scalars and list-of-strings must
+            # not look like chatml. Upgrade a non-plausible fallback when a later
+            # candidate is plausible, so probe order keeps the best match.
+            if all_corrupt_fallback is None or not all_corrupt_fallback.get(
+                "has_plausible_turns"
+            ):
+                has_plausible_turns = False
+                for i in range(min(len(dataset), 100)):
+                    cell = dataset[i][col]
+                    if cell is None:
+                        has_plausible_turns = True
+                        break
+                    # A struct-typed cell (single dict, not a list) is metadata,
+                    # not chat: leave it for "unknown format", matching
+                    # format_detection.py.
+                    if isinstance(cell, list):
+                        # Plausible only if the list holds a dict/None turn; empty
+                        # lists and list-of-strings are not chat data.
+                        if any(t is None or isinstance(t, dict) for t in cell):
+                            has_plausible_turns = True
+                            break
+                all_corrupt_fallback = {
+                    "column": col,
+                    "turn_keys": set(),
+                    "roles": set(),
+                    "all_corrupt": True,
+                    "has_plausible_turns": has_plausible_turns,
+                }
+            continue
+
+        # Use the same 100-row window to gather keys/roles.
+        turn_keys = set()
+        roles = set()
+        for i in range(min(len(dataset), 100)):
+            conv = dataset[i][col]
+            if isinstance(conv, list):
+                for t in conv:
+                    if isinstance(t, dict):
+                        turn_keys.update(t.keys())
+                        r = t.get("role") or t.get("from")
+                        if r:
+                            roles.add(str(r))
+        # Column lacks a full chat key pair. If it still has a conversational key
+        # (role/from/content/value) it is a corrupt-but-real chat column, so save
+        # a plausible fallback for find_none_chatml to flag. Pure metadata (e.g.
+        # [{"id":1}]) is not plausible, so a later real-but-corrupt column (e.g.
+        # conversations=None) can still win.
+        _CONV_KEYS = {"role", "from", "content", "value"}
+        if not any(keys <= turn_keys for keys in _CHAT_KEY_SETS):
+            schema_less_plausible = bool(turn_keys & _CONV_KEYS)
+            if all_corrupt_fallback is None or not all_corrupt_fallback.get(
+                "has_plausible_turns"
+            ):
+                all_corrupt_fallback = {
+                    "column": col,
+                    "turn_keys": turn_keys,
+                    "roles": roles,
+                    "all_corrupt": True,
+                    "has_plausible_turns": schema_less_plausible,
+                }
+            continue
+        return {"column": col, "turn_keys": turn_keys, "roles": roles}
+    # No healthy column found; return the all_corrupt fallback if any.
+    return all_corrupt_fallback
+
+
+# None-detection helpers
+# ---------------------------------------------------------------------------
+
+
+def is_none_or_empty(value) -> bool:
+    """True if value is None, empty string, whitespace-only, or an empty/whitespace-only VLM content block list."""
+    if value is None:
+        return True
+    if isinstance(value, str):
+        # Treat zero-width/BOM chars (U+FEFF/200B/200C/200D/2060) as empty too;
+        # they render invisibly. Two-pass strip (ws, invisibles, ws) catches
+        # mixed cases like "\u200b \u200b".
+        stripped = value.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip()
+        if not stripped:
+            return True
+    if isinstance(value, list):
+        # VLM content blocks, e.g. [{"type":"text",...}, {"type":"image",...}].
+        # Empty list -> empty. A non-text block (image/audio/tool) is real
+        # content; only flag when every text block is blank and no such block
+        # exists (an image-only turn is valid).
+        if len(value) == 0:
+            return True
+        # No dict blocks at all (e.g. [None], ['  ']) -> malformed/empty.
+        dict_blocks = [item for item in value if isinstance(item, dict)]
+        if not dict_blocks:
+            return True
+        non_text_blocks = [item for item in dict_blocks if item.get("type") != "text"]
+        if non_text_blocks:
+            return False
+        text_values = [
+            item.get("text") for item in dict_blocks if item.get("type") == "text"
+        ]
+        if text_values and all(
+            t is None
+            or (
+                isinstance(t, str)
+                and not t.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip()
+            )
+            for t in text_values
+        ):
+            return True
+    return False
+
+
+def _classify_empty(value) -> str:
+    """Return a human-readable label for why this value is considered empty."""
+    if value is None:
+        return "None"
+    if isinstance(value, str):
+        if len(value) == 0:
+            return "empty_string"
+        # Only-whitespace or only-invisible (BOM/zero-width) strings render empty.
+        if not value.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip():
+            return "whitespace_only"
+    if isinstance(value, list):
+        # Mirrors the VLM/OpenAI content-block handling in is_none_or_empty.
+        if len(value) == 0:
+            return "empty_list"
+        return "empty_vlm_content"
+    return "valid"  # should not reach here if is_none_or_empty was True
+
+
+# ---------------------------------------------------------------------------
+# Alpaca detection
+# ---------------------------------------------------------------------------
+
+
+def find_none_alpaca(dataset: Dataset) -> dict:
+    """
+    Scan alpaca dataset for None/empty instruction or output fields.
+    Returns stats dict with a detailed 'findings' list.
+    """
+    stats = {
+        "total_rows": len(dataset),
+        "none_instruction": 0,
+        "none_output": 0,
+        "bad_row_indices": [],
+        "findings": [],  # [{row, field, value_type, raw_value}, ...]
+    }
+
+    for i, row in enumerate(dataset):
+        bad = False
+        for field in ("instruction", "output"):
+            val = row.get(field)
+            if is_none_or_empty(val):
+                stats[f"none_{field}"] = stats.get(f"none_{field}", 0) + 1
+                bad = True
+                stats["findings"].append(
+                    {
+                        "row_index": i,
+                        "field": field,
+                        "value_type": _classify_empty(val),
+                        "raw_value": repr(val),
+                    }
+                )
+        if bad:
+            stats["bad_row_indices"].append(i)
+
+    return stats
+
+
+# ---------------------------------------------------------------------------
+# ChatML / conversational detection
+# ---------------------------------------------------------------------------
+
+
+def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
+    """
+    Scan chatml/sharegpt/gptoss dataset for turns with None/empty content.
+    Auto-detects the conversation column if col=None.
+
+    Returns a stats dict that includes a complete 'findings' list - one entry
+    per bad turn with row_index, turn_index, role, value_type, and raw_value.
+    """
+    if col is None:
+        # Reuse _probe_conversation so the all_corrupt path is handled here too.
+        _cinfo = _probe_conversation(dataset)
+        if _cinfo is not None:
+            col = _cinfo["column"]
+
+    if col is None or col not in dataset.column_names:
+        raise ValueError(
+            f"No conversation column found. "
+            f"Expected one of {CONVERSATION_COLUMNS}, got columns: {dataset.column_names}"
+        )
+
+    stats = {
+        "total_rows": len(dataset),
+        "column": col,
+        "rows_with_none_turns": 0,
+        "total_none_turns": 0,
+        "none_by_role": {},  # role -> count of None turns
+        "none_by_type": {},  # "None" | "empty_string" | "whitespace_only" -> count
+        "rows_all_none": 0,  # rows where every turn is bad
+        "bad_row_indices": [],  # every row index that has at least one bad turn
+        "findings": [],  # detailed per-turn list
+    }
+
+    for i, row in enumerate(dataset):
+        conversation = row[col]
+        if not isinstance(conversation, list):
+            # Non-list conversation: unusable for training, flag as bad.
+            vtype = "None" if conversation is None else "invalid_type"
+            stats["bad_row_indices"].append(i)
+            stats["rows_with_none_turns"] += 1
+            stats["total_none_turns"] += 1
+            stats["rows_all_none"] += 1
+            stats["none_by_role"]["unknown"] = (
+                stats["none_by_role"].get("unknown", 0) + 1
+            )
+            stats["none_by_type"][vtype] = stats["none_by_type"].get(vtype, 0) + 1
+            stats["findings"].append(
+                {
+                    "row_index": i,
+                    "turn_index": 0,
+                    "role": "unknown",
+                    "value_type": vtype,
+                    "raw_value": repr(conversation),
+                }
+            )
+            continue
+
+        if len(conversation) == 0:
+            # Zero-turn conversation: flag so it does not scan as clean.
+            stats["bad_row_indices"].append(i)
+            stats["rows_with_none_turns"] += 1
+            stats["total_none_turns"] += 1
+            stats["rows_all_none"] += 1
+            stats["none_by_role"]["unknown"] = (
+                stats["none_by_role"].get("unknown", 0) + 1
+            )
+            stats["none_by_type"]["empty_conversation"] = (
+                stats["none_by_type"].get("empty_conversation", 0) + 1
+            )
+            stats["findings"].append(
+                {
+                    "row_index": i,
+                    "turn_index": 0,
+                    "role": "unknown",
+                    "value_type": "empty_conversation",
+                    "raw_value": "[]",
+                }
+            )
+            continue
+
+        row_findings = []
+        for turn_idx, turn in enumerate(conversation):
+            # Non-dict turn - record it rather than crash or silently skip.
+            if not isinstance(turn, dict):
+                row_findings.append(
+                    {
+                        "row_index": i,
+                        "turn_index": turn_idx,
+                        "role": "unknown",
+                        "value_type": "None" if turn is None else "invalid_type",
+                        "raw_value": repr(turn),
+                    }
+                )
+                stats["none_by_role"]["unknown"] = (
+                    stats["none_by_role"].get("unknown", 0) + 1
+                )
+                vtype = "None" if turn is None else "invalid_type"
+                stats["none_by_type"][vtype] = stats["none_by_type"].get(vtype, 0) + 1
+                continue
+            # Explicit None check so falsy roles (0, "", False) are kept, not
+            # collapsed to "unknown".
+            r = turn.get("role")
+            if r is None:
+                r = turn.get("from")
+            if r is None:
+                role = "unknown"
+            elif isinstance(r, str):
+                role = r
+            else:
+                role = str(r)
+            # Pick the content key: from+value -> value (ShareGPT, even if role is
+            # also set); role -> content (or value); from only -> value (None when
+            # missing, so it is flagged); neither -> content then value.
+            if "from" in turn and "value" in turn:
+                content = turn.get("value")
+            elif "role" in turn:
+                content = (
+                    turn.get("content") if "content" in turn else turn.get("value")
+                )
+            elif "from" in turn:
+                content = turn.get("value")
+            else:
+                content = (
+                    turn.get("content") if "content" in turn else turn.get("value")
+                )
+            # Assistant tool-call turns carry empty content + tool_calls and are
+            # valid; the exemption is assistant-only.
+            if is_none_or_empty(content) and not (
+                role == "assistant" and turn.get("tool_calls")
+            ):
+                vtype = _classify_empty(content)
+                row_findings.append(
+                    {
+                        "row_index": i,
+                        "turn_index": turn_idx,
+                        "role": role,
+                        "value_type": vtype,
+                        "raw_value": repr(content),
+                    }
+                )
+                stats["none_by_role"][role] = stats["none_by_role"].get(role, 0) + 1
+                stats["none_by_type"][vtype] = stats["none_by_type"].get(vtype, 0) + 1
+
+        if row_findings:
+            stats["rows_with_none_turns"] += 1
+            stats["total_none_turns"] += len(row_findings)
+            stats["bad_row_indices"].append(i)
+            stats["findings"].extend(row_findings)
+
+            if len(row_findings) == len(conversation):
+                stats["rows_all_none"] += 1
+
+    return stats
+
+
+# ---------------------------------------------------------------------------
+# Convenience wrappers per format (all delegate to the same scan logic)
+# ---------------------------------------------------------------------------
+
+
+def find_none_sharegpt(dataset: Dataset, col: str = None) -> dict:
+    """ShareGPT uses 'from'/'value' keys - same scan logic handles both."""
+    if col is None:
+        # ShareGPT lives in 'conversations'; probe only that column so a corrupt
+        # one is still scanned, not replaced by a healthy 'messages' (P1 fix).
+        conv_info = _probe_conversation(dataset, candidates = ("conversations",))
+        if conv_info is None:
+            raise ValueError(
+                f"No valid conversation column found in {dataset.column_names}. "
+                "Expected a 'conversations' column with 'from'/'value' or 'role'/'content' turn keys."
+            )
+        col = conv_info["column"]
+    return find_none_chatml(dataset, col = col)
+
+
+def find_none_gptoss(dataset: Dataset, col: str = None) -> dict:
+    """gptoss: role/content plus optional thinking/tool_calls. Only content checked."""
+    if col is None:
+        # gptoss lives in 'messages': target it whenever present (even if
+        # corrupt), and fall back to 'conversations' only if 'messages' is absent.
+        if "messages" in dataset.column_names:
+            conv_info = _probe_conversation(dataset, candidates = ("messages",))
+        else:
+            conv_info = _probe_conversation(dataset, candidates = ("conversations",))
+        if conv_info is None:
+            raise ValueError(
+                f"No valid conversation column found in {dataset.column_names}. "
+                "Expected a 'messages' or 'conversations' column with 'role'/'content' turn keys."
+            )
+        col = conv_info["column"]
+    return find_none_chatml(dataset, col = col)
+
+
+# ---------------------------------------------------------------------------
+# Format registry - first match wins; detect_format() auto-scales.
+# Each entry: name (label/--format value), match(dataset, conv_info) -> bool,
+# scan (find_none_* function). Put specific formats before generalisations
+# (gptoss before chatml, since gptoss is chatml with a 'developer' role).
+# To add a format: write find_none_<name>() (or reuse find_none_chatml) and
+# append an entry; detect_format(), --format, and scan_dataset() pick it up.
+# ---------------------------------------------------------------------------
+
+FORMAT_REGISTRY = [
+    {
+        "name": "alpaca",
+        # instruction/output present and no usable chat column: either none
+        # exists, or the only one is fully corrupt (e.g. a stray all-None or
+        # metadata `messages` column). A healthy chat column falls through to
+        # the conversational scanners below.
+        "match": lambda ds, conv: (
+            {"instruction", "output"}.issubset(ds.column_names)
+            and (conv is None or conv.get("all_corrupt"))
+        ),
+        "scan": find_none_alpaca,
+    },
+    {
+        "name": "gptoss",
+        "match": lambda ds, conv: (
+            conv is not None
+            and {"role", "content"} <= conv["turn_keys"]
+            and "developer" in conv["roles"]
+        ),
+        "scan": find_none_gptoss,
+    },
+    {
+        "name": "sharegpt",
+        "match": lambda ds, conv: (
+            conv is not None and {"from", "value"} <= conv["turn_keys"]
+        ),
+        "scan": find_none_sharegpt,
+    },
+    {
+        "name": "chatml",
+        "match": lambda ds, conv: (
+            conv is not None
+            and (
+                {"role", "content"} <= conv["turn_keys"]
+                # all_corrupt: column found but every row malformed; require
+                # has_plausible_turns so scalar/string columns are not chatml.
+                or (conv.get("all_corrupt") and conv.get("has_plausible_turns"))
+            )
+        ),
+        "scan": find_none_chatml,
+    },
+]
+
+# Derived list of known format names (used by CLI --format choices).
+FORMAT_NAMES = [entry["name"] for entry in FORMAT_REGISTRY]
+
+# Documented aliases accepted by both the Python API and the CLI.
+FORMAT_ALIASES = {"gpt-oss": "gptoss"}
+
+
+def detect_format(dataset: Dataset) -> str:
+    """
+    Auto-detect dataset format by probing columns and turn structure.
+
+    Returns one of the format names in FORMAT_REGISTRY, or 'unknown'.
+    Walks the registry in order; first match wins.
+    """
+    conv_info = _probe_conversation(dataset)
+    for entry in FORMAT_REGISTRY:
+        if entry["match"](dataset, conv_info):
+            return entry["name"]
+    return "unknown"
+
+
+def get_scanner(fmt: str):
+    """Return the scanner function for a format name, or None if unknown."""
+    for entry in FORMAT_REGISTRY:
+        if entry["name"] == fmt:
+            return entry["scan"]
+    return None
+
+
+def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
+    """
+    One-liner: detect format (if 'auto') and scan for None/empty content.
+
+    Returns the stats dict with an added 'format' key.
+    Raises ValueError if the format is unknown or unsupported.
+    """
+    # Reject a DatasetDict / IterableDatasetDict (load_dataset without split):
+    # its column_names is a split map and would yield a confusing "unknown
+    # format". Check both (IterableDatasetDict is not a DatasetDict subclass);
+    # import locally so this module never hard-requires those symbols.
+    _dict_types = []
+    try:
+        from datasets import DatasetDict as _DatasetDict
+
+        _dict_types.append(_DatasetDict)
+    except ImportError:
+        pass
+    try:
+        from datasets import IterableDatasetDict as _IterableDatasetDict
+
+        _dict_types.append(_IterableDatasetDict)
+    except ImportError:
+        pass
+    if _dict_types and isinstance(dataset, tuple(_dict_types)):
+        raise ValueError(
+            "scan_dataset requires a single Dataset split, not a DatasetDict. "
+            f"Available splits: {list(dataset.keys())}. "
+            "Pass dataset[<split>] or use load_dataset(..., split='train')."
+        )
+    # Streaming IterableDataset has no len()/column_names; give a clear error
+    # instead of a confusing TypeError downstream.
+    try:
+        from datasets import IterableDataset as _IterableDataset
+
+        if isinstance(dataset, _IterableDataset):
+            raise ValueError(
+                "scan_dataset requires a materialized Dataset, not an IterableDataset. "
+                "Load without streaming=True, or materialize a slice first: "
+                "Dataset.from_list(list(dataset.take(N)))."
+            )
+    except ImportError:
+        pass
+    fmt = FORMAT_ALIASES.get(fmt, fmt)
+    was_auto = fmt == "auto"
+    # Zero-row dataset: return a trivially clean stats dict.
+    if was_auto and len(dataset) == 0:
+        return {
+            "format": "unknown",
+            "total_rows": 0,
+            "findings": [],
+            "bad_row_indices": [],
+        }
+    # Always probe so detection and column selection share one scan pass.
+    conv_info = _probe_conversation(dataset)
+    if was_auto:
+        fmt = "unknown"
+        for entry in FORMAT_REGISTRY:
+            if entry["match"](dataset, conv_info):
+                fmt = entry["name"]
+                break
+        # No format matched: return clean stats (format="unknown") rather than
+        # raise, so callers can branch on stats["format"].
+        if fmt == "unknown":
+            return {
+                "format": "unknown",
+                "total_rows": len(dataset),
+                "findings": [],
+                "bad_row_indices": [],
+            }
+    scanner = get_scanner(fmt)
+    if scanner is None:
+        raise ValueError(f"Unknown or unsupported format: '{fmt}'")
+    # Column forwarding: on auto-detect pass the probed column (already the best
+    # choice). On an explicit format let that scanner pick its own column, so
+    # e.g. fmt='sharegpt' always scans 'conversations', not 'messages' (P1 fix);
+    # gptoss has its own messages-first rule. alpaca never takes a column.
+    use_probed_col = conv_info is not None and fmt != "alpaca" and was_auto
+    if use_probed_col:
+        stats = scanner(dataset, col = conv_info["column"])
+    else:
+        stats = scanner(dataset)
+    stats["format"] = fmt
+    return stats
+
+
+# ---------------------------------------------------------------------------
+# Report printing
+# ---------------------------------------------------------------------------
+
+
+def _print_summary_header(stats: dict, fmt: str) -> bool:
+    """Print the top-level stats block (shared by all report modes). Returns True if findings exist."""
+    total = stats["total_rows"]
+    findings = stats.get("findings", [])
+
+    print(f"\n{'=' * 64}")
+    print(f"  None / Empty Detection Report")
+    print(f"{'=' * 64}")
+    print(f"  Format:       {fmt}")
+    print(f"  Total rows:   {total}")
+
+    if not findings:
+        if fmt == "unknown":
+            print(f"  Result:       NOT SCANNED -- format could not be detected")
+        else:
+            print(f"  Result:       CLEAN -- no None or empty values found")
+        print(f"{'=' * 64}")
+        return False
+
+    if fmt == "alpaca":
+        bad_rows = len(stats.get("bad_row_indices", []))
+        print(f"  Rows with Nones: {bad_rows} / {total}")
+        print(f"  None instruction: {stats.get('none_instruction', 0)}")
+        print(f"  None output:      {stats.get('none_output', 0)}")
+    else:
+        col = stats.get("column", "?")
+        print(f"  Column:       {col}")
+        print(f"  Rows with bad turns: {stats['rows_with_none_turns']} / {total}")
+        print(f"  Total bad turns:     {len(findings)}")
+        print(f"  By type:      {stats.get('none_by_type', {})}")
+        print(f"  By role:      {stats.get('none_by_role', {})}")
+        rows_all = stats.get("rows_all_none", 0)
+        if rows_all:
+            print(f"  Rows ALL bad: {rows_all} (every turn is None/empty)")
+
+    # Rows with no Nones - compute the count directly instead of allocating a
+    # full set of row indices, which OOMs on large (10M+ row) datasets.
+    bad_indices = set(stats.get("bad_row_indices", []))
+    clean_count = total - len(bad_indices)
+    if 0 < clean_count <= 20:
+        clean_indices = [i for i in range(total) if i not in bad_indices]
+        print(f"  Rows with no Nones: {clean_count} / {total}  {clean_indices}")
+    else:
+        print(f"  Rows with no Nones: {clean_count} / {total}")
+
+    print(f"{'=' * 64}")
+    return True
+
+
+def print_report(stats: dict, fmt: str, summary_only: bool = False):
+    """Print a human-readable summary, optionally with full findings list."""
+    has_findings = _print_summary_header(stats, fmt)
+    if not has_findings or summary_only:
+        return
+
+    findings = stats.get("findings", [])
+    print(f"\n  {'-' * 60}")
+    print(f"  Findings ({len(findings)} total):")
+    print(f"  {'-' * 60}")
+
+    for f in findings:
+        if fmt == "alpaca":
+            print(
+                f"  row {f['row_index']:>5d}  "
+                f"field={f['field']:<12s}  "
+                f"type={f['value_type']:<16s}  "
+                f"raw={f['raw_value']}"
+            )
+        else:
+            print(
+                f"  row {f['row_index']:>5d}  "
+                f"turn {f['turn_index']}  "
+                f"role={str(f['role']):<12s}  "
+                f"type={f['value_type']:<16s}  "
+                f"raw={f['raw_value']}"
+            )
+
+    print(f"{'=' * 64}")
+
+
+def show_row(dataset: Dataset, row_indices: list[int], fmt: str, col: str = None):
+    """Print the full contents of specific rows for inspection.
+
+    Used by test_codex_fixes.py to verify row rendering behaviour.
+    Not part of the production API.
+    """
+    if col is None:
+        for candidate in ("messages", "conversations", "texts"):
+            if candidate in dataset.column_names:
+                col = candidate
+                break
+
+    for ri in row_indices:
+        if ri < 0 or ri >= len(dataset):
+            print(f"\n  [ERROR] Row {ri} out of range (0-{len(dataset)-1})")
+            continue
+
+        row = dataset[ri]
+        print(f"\n{'=' * 64}")
+        print(f"  Row {ri}")
+        print(f"{'=' * 64}")
+
+        # Print non-conversation columns. For alpaca, skip the fields the
+        # alpaca block below prints with status markers (avoid double render).
+        _ALPACA_FIELDS = {"instruction", "input", "output"}
+        for key in dataset.column_names:
+            if key == col:
+                continue
+            if fmt == "alpaca" and key in _ALPACA_FIELDS:
+                continue
+            val = row[key]
+            if isinstance(val, str) and len(val) > 120:
+                val = val[:120] + "..."
+            print(f"  {key}: {val}")
+
+        if fmt == "alpaca":
+            for field in ("instruction", "input", "output"):
+                val = row.get(field)
+                status = "  [NONE]" if is_none_or_empty(val) else ""
+                if val and len(str(val)) > 200:
+                    val = str(val)[:200] + "..."
+                print(f"  {field}: {val}{status}")
+        elif col:
+            conversation = row[col]
+            if isinstance(conversation, list):
+
+                def _is_bad_turn(t):
+                    if not isinstance(t, dict):
+                        return True
+                    # Mirror scanner logic: from+value wins, then role, then from alone.
+                    if "from" in t and "value" in t:
+                        c = t.get("value")
+                    elif "role" in t:
+                        c = t.get("content") if "content" in t else t.get("value")
+                    elif "from" in t:
+                        c = t.get("value")
+                    else:
+                        c = t.get("content") if "content" in t else t.get("value")
+                    # Mirror scanner logic: tool_calls exemption is assistant-only;
+                    # other roles with empty content + tool_calls are still bad.
+                    r = t.get("role") if t.get("role") is not None else t.get("from")
+                    if is_none_or_empty(c) and not (
+                        str(r) == "assistant" and t.get("tool_calls")
+                    ):
+                        return True
+                    return False
+
+                none_count = sum(1 for t in conversation if _is_bad_turn(t))
+                print(f"  {col}: {len(conversation)} turns ({none_count} None)")
+                print(f"  {'-' * 60}")
+                for i, turn in enumerate(conversation):
+                    # Non-dict turn - can't extract role or content normally.
+                    if not isinstance(turn, dict):
+                        label = "None" if turn is None else "invalid_type"
+                        print(f"  [{i:>3d}] {'unknown':<12s} [{label}]  << NONE")
+                        continue
+                    r = turn.get("role")
+                    if r is None:
+                        r = turn.get("from")
+                    role = "?" if r is None else str(r)
+                    # Mirror scanner logic: from+value wins, then role, then from alone.
+                    if "from" in turn and "value" in turn:
+                        content = turn.get("value")
+                    elif "role" in turn:
+                        content = (
+                            turn.get("content")
+                            if "content" in turn
+                            else turn.get("value")
+                        )
+                    elif "from" in turn:
+                        content = turn.get("value")
+                    else:
+                        content = (
+                            turn.get("content")
+                            if "content" in turn
+                            else turn.get("value")
+                        )
+                    if is_none_or_empty(content) and not (
+                        role == "assistant" and turn.get("tool_calls")
+                    ):
+                        status = "  << NONE"
+                    else:
+                        status = ""
+                    if content is None:
+                        preview = "None"
+                    else:
+                        preview_str = str(content)  # cast: content may not be a string
+                        if len(preview_str) > 150:
+                            preview = preview_str[:150].replace("\n", "\\n") + "..."
+                        else:
+                            preview = preview_str.replace("\n", "\\n")
+                    print(f"  [{i:>3d}] {role:<12s} {preview}{status}")
+
+        print(f"{'=' * 64}")
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    import argparse
+    import os
+    import sys
+
+    parser = argparse.ArgumentParser(
+        prog = "dataset_none_detect",
+        description = "Scan a HuggingFace dataset for None/empty content turns.",
+        formatter_class = argparse.RawDescriptionHelpFormatter,
+        epilog = """
+examples:
+  python dataset_none_detect.py org/my-dataset
+  python dataset_none_detect.py org/my-dataset --split train
+  python dataset_none_detect.py org/my-dataset --format sharegpt
+  python dataset_none_detect.py org/my-dataset --summary-only
+  python dataset_none_detect.py org/my-dataset --token hf_...
+        """,
+    )
+    parser.add_argument(
+        "dataset", help = "HuggingFace dataset repo id (e.g. org/my-dataset)"
+    )
+    parser.add_argument(
+        "--split", default = "train", help = "Dataset split to load (default: train)"
+    )
+    parser.add_argument(
+        "--format",
+        default = "auto",
+        choices = ["auto"] + FORMAT_NAMES + list(FORMAT_ALIASES),
+        help = "Force a specific format instead of auto-detecting (default: auto). "
+        "Documented aliases (e.g. 'gpt-oss' for 'gptoss') are also accepted.",
+    )
+    parser.add_argument(
+        "--summary-only",
+        action = "store_true",
+        help = "Print summary header only - skip the per-turn findings list",
+    )
+    parser.add_argument(
+        "--token",
+        default = os.environ.get("HF_TOKEN"),
+        help = (
+            "HuggingFace API token for private datasets (default: $HF_TOKEN). "
+            "Prefer setting $HF_TOKEN; passing --token on the command line "
+            "exposes it in process listings."
+        ),
+    )
+    args = parser.parse_args()
+
+    try:
+        from datasets import load_dataset
+    except ImportError:
+        print(
+            "Error: 'datasets' package not found. Install with: pip install datasets",
+            file = sys.stderr,
+        )
+        sys.exit(1)
+
+    print(f"Loading {args.dataset!r} (split={args.split!r})...")
+    try:
+        ds = load_dataset(args.dataset, split = args.split, token = args.token)
+    except Exception as exc:
+        # Some `datasets` / `requests` versions include the Authorization
+        # header in exception messages. Redact the token before printing.
+        msg = str(exc)
+        if args.token:
+            msg = msg.replace(args.token, "hf_***REDACTED***")
+        print(f"Error loading dataset: {msg}", file = sys.stderr)
+        sys.exit(1)
+
+    print(f"Loaded {len(ds)} rows, columns: {ds.column_names}")
+
+    try:
+        stats = scan_dataset(ds, fmt = args.format)
+    except ValueError as exc:
+        print(f"Error: {exc}", file = sys.stderr)
+        sys.exit(1)
+
+    print_report(stats, stats["format"], summary_only = args.summary_only)
diff --git a/tests/utils/generate_dataset_with_none.py b/tests/utils/generate_dataset_with_none.py
new file mode 100644
index 0000000000..71d228963a
--- /dev/null
+++ b/tests/utils/generate_dataset_with_none.py
@@ -0,0 +1,265 @@
+"""
+generate_dataset_with_none.py
+
+Generates a small synthetic dataset that intentionally contains None/empty
+turns so dataset_none_detect.py can be verified end-to-end.
+
+Produces three formats:
+  - chatml  (messages column, role/content turns)
+  - sharegpt (conversations column, from/value turns)
+  - alpaca  (instruction/output columns)
+
+Each format gets ~20 rows; roughly half have at least one bad turn.
+
+No heavy dependencies -- just `datasets`.
+"""
+
+from datasets import Dataset
+
+# ---------------------------------------------------------------------------
+# ChatML (messages, role/content)
+# ---------------------------------------------------------------------------
+
+# NOTE: pyarrow requires uniform types in a column, so rows with messages=None
+# or messages="not a list" (P1 cases) live in a SEPARATE dataset (see
+# make_chatml_p1_dataset below) so pyarrow can infer the column type correctly.
+
+_CHATML_ROWS = [
+    # clean rows
+    {
+        "messages": [
+            {"role": "user", "content": "What is 2+2?"},
+            {"role": "assistant", "content": "4"},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Name a colour."},
+            {"role": "assistant", "content": "Blue."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "Hi"},
+            {"role": "assistant", "content": "Hello!"},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Tell me a joke."},
+            {"role": "assistant", "content": "Why did the chicken cross the road?"},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Capital of France?"},
+            {"role": "assistant", "content": "Paris."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Count to 3."},
+            {"role": "assistant", "content": "1, 2, 3."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "What is Python?"},
+            {"role": "assistant", "content": "A programming language."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Translate 'hello' to Spanish."},
+            {"role": "assistant", "content": "Hola."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "What is gravity?"},
+            {"role": "assistant", "content": "A fundamental force."},
+        ]
+    },
+    {
+        "messages": [
+            {"role": "user", "content": "Who wrote Hamlet?"},
+            {"role": "assistant", "content": "Shakespeare."},
+        ]
+    },
+    # bad rows — None/empty turn content (all messages values are lists so pyarrow is happy)
+    {
+        "messages": [
+            {"role": "user", "content": None},
+            {"role": "assistant", "content": "Sure!"},
+        ]
+    },  # None content
+    {
+        "messages": [
+            {"role": "user", "content": ""},
+            {"role": "assistant", "content": "OK."},
+        ]
+    },  # empty string
+    {
+        "messages": [
+            {"role": "user", "content": "   "},
+            {"role": "assistant", "content": "Got it."},
+        ]
+    },  # whitespace only
+    {
+        "messages": [
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": None},
+        ]
+    },  # None assistant
+    {
+        "messages": [
+            {"role": "user", "content": None},
+            {"role": "assistant", "content": None},
+        ]
+    },  # both None
+    {
+        "messages": [
+            {"role": "user", "content": ""},
+            {"role": "assistant", "content": ""},
+        ]
+    },  # both empty
+    {
+        "messages": [
+            {"role": "user", "content": "Anything?"},
+            {"role": "assistant", "content": "  \t  "},
+        ]
+    },  # tab whitespace
+    {
+        "messages": [None, {"role": "assistant", "content": "Reply"}]
+    },  # None turn element
+]
+
+# P1 test rows: messages is None or non-list.
+# Stored as a plain list of dicts rather than an HF Dataset because pyarrow
+# cannot mix list and non-list values in the same column.  The test runner
+# uses a lightweight mock to exercise find_none_chatml directly.
+_CHATML_P1_ROWS = [
+    {"messages": None},  # whole column None
+    {"messages": "not a list"},  # wrong type
+]
+
+
+def make_chatml_p1_rows() -> list:
+    """Return the raw P1 rows (not an HF Dataset) for direct mock testing."""
+    return list(_CHATML_P1_ROWS)
+
+
+# ---------------------------------------------------------------------------
+# ShareGPT (conversations, from/value)
+# ---------------------------------------------------------------------------
+
+_SHAREGPT_ROWS = [
+    # clean
+    {
+        "conversations": [
+            {"from": "human", "value": "Hello"},
+            {"from": "gpt", "value": "Hi there!"},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": "What time is it?"},
+            {"from": "gpt", "value": "I don't know."},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": "Good morning"},
+            {"from": "gpt", "value": "Good morning!"},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": "Tell me about AI."},
+            {"from": "gpt", "value": "AI stands for Artificial Intelligence."},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": "Bye"},
+            {"from": "gpt", "value": "Goodbye!"},
+        ]
+    },
+    # bad
+    {
+        "conversations": [
+            {"from": "human", "value": None},
+            {"from": "gpt", "value": "Sure!"},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": ""},
+            {"from": "gpt", "value": "OK."},
+        ]
+    },
+    {
+        "conversations": [
+            {"from": "human", "value": "Hello"},
+            {"from": "gpt", "value": None},
+        ]
+    },
+    {"conversations": None},  # P1: whole column is None
+    {"conversations": [None, {"from": "gpt", "value": "Hi"}]},
+]
+
+# ---------------------------------------------------------------------------
+# Alpaca (instruction / output columns)
+# ---------------------------------------------------------------------------
+
+_ALPACA_ROWS = [
+    # clean
+    {
+        "instruction": "Summarise this text.",
+        "input": "The sky is blue.",
+        "output": "The sky is blue.",
+    },
+    {"instruction": "Translate to French.", "input": "Hello", "output": "Bonjour"},
+    {"instruction": "What is 10*10?", "input": "", "output": "100"},
+    {
+        "instruction": "Name the planets.",
+        "input": "",
+        "output": "Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune",
+    },
+    {
+        "instruction": "Write a haiku.",
+        "input": "",
+        "output": "Old pond — / frog jumps in / water's sound",
+    },
+    # bad
+    {"instruction": None, "input": "", "output": "Some output"},
+    {"instruction": "", "input": "", "output": "Some output"},
+    {"instruction": "Valid instruction", "input": "", "output": None},
+    {"instruction": None, "input": "", "output": None},
+    {"instruction": "  ", "input": "", "output": ""},
+]
+
+
+def make_chatml_dataset() -> Dataset:
+    return Dataset.from_list(_CHATML_ROWS)
+
+
+def make_sharegpt_dataset() -> Dataset:
+    return Dataset.from_list(_SHAREGPT_ROWS)
+
+
+def make_alpaca_dataset() -> Dataset:
+    return Dataset.from_list(_ALPACA_ROWS)
+
+
+if __name__ == "__main__":
+    print("Synthetic dataset sizes:")
+    print(
+        f"  chatml:   {len(_CHATML_ROWS)} rows (+ {len(_CHATML_P1_ROWS)} P1 mock rows)"
+    )
+    print(f"  sharegpt: {len(_SHAREGPT_ROWS)} rows")
+    print(f"  alpaca:   {len(_ALPACA_ROWS)} rows")
+    print(
+        "\nImport make_chatml_dataset, make_sharegpt_dataset, make_alpaca_dataset, make_chatml_p1_rows."
+    )
diff --git a/tests/utils/run_none_detect_tests.py b/tests/utils/run_none_detect_tests.py
new file mode 100644
index 0000000000..8fc31faf04
--- /dev/null
+++ b/tests/utils/run_none_detect_tests.py
@@ -0,0 +1,748 @@
+"""
+run_none_detect_tests.py
+
+Runs dataset_none_detect.py against:
+  1. Synthetic datasets (chatml, sharegpt, alpaca) with deliberately injected Nones
+  2. peteromallet/dataclaw-peteromallet (HuggingFace)
+  3. peteromallet/my-personal-codex-data (HuggingFace)
+
+Writes a detailed log to tests/logs/none_detect_results.log
+
+Usage (from repo root, with venv active):
+    python tests/utils/run_none_detect_tests.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from datetime import datetime
+from io import StringIO
+from pathlib import Path
+
+# Allow running from repo root without install.
+# Insert the datasets directory directly so dataset_none_detect is imported
+# as a top-level module, bypassing utils/datasets/__init__.py which pulls in
+# torch, fastapi, and other heavy studio deps not needed for this utility.
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(REPO_ROOT / "studio" / "backend" / "utils" / "datasets"))
+
+from dataset_none_detect import (
+    find_none_chatml,
+    print_report,
+    scan_dataset,
+)
+
+LOG_DIR = REPO_ROOT / "tests" / "logs"
+LOG_DIR.mkdir(parents = True, exist_ok = True)
+LOG_PATH = LOG_DIR / "none_detect_results.log"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class Tee:
+    """Write to both stdout and a file simultaneously."""
+
+    def __init__(self, file):
+        self.file = file
+        self.stdout = sys.stdout
+
+    def write(self, data):
+        self.stdout.write(data)
+        self.file.write(data)
+
+    def flush(self):
+        self.stdout.flush()
+        self.file.flush()
+
+
+def section(title: str):
+    line = "=" * 70
+    print(f"\n{line}")
+    print(f"  {title}")
+    print(f"{line}")
+
+
+def run_scan(dataset, label: str, fmt: str = "auto") -> dict | None:
+    print(f"\n--- Scanning: {label} (fmt={fmt}) ---")
+    try:
+        stats = scan_dataset(dataset, fmt = fmt)
+        print_report(stats, stats["format"])
+        return stats
+    except Exception as exc:
+        print(f"  [ERROR] {exc}")
+        traceback.print_exc()
+        return None
+
+
+def assert_bad_rows(stats: dict, expected_min: int, label: str):
+    bad = len(stats.get("bad_row_indices", []))
+    status = "PASS" if bad >= expected_min else "FAIL"
+    print(f"  [{status}] {label}: found {bad} bad rows (expected >= {expected_min})")
+    return status == "PASS"
+
+
+def assert_exact_recall(stats: dict, expected_bad: set, label: str):
+    """Every injected bad row index must appear in bad_row_indices — no misses."""
+    actual_bad = set(stats.get("bad_row_indices", []))
+    missed = expected_bad - actual_bad
+    all_caught = len(missed) == 0
+    status = "PASS" if all_caught else "FAIL"
+    caught_count = len(expected_bad) - len(missed)
+    print(
+        f"  [{status}] {label}: exact recall — "
+        f"{caught_count}/{len(expected_bad)} injected bad rows caught",
+        end = "",
+    )
+    if missed:
+        print(f"  (missed rows: {sorted(missed)})")
+    else:
+        print()
+    return all_caught
+
+
+# ---------------------------------------------------------------------------
+# 1. Synthetic datasets
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Minimal mock so find_none_chatml can be called with hand-crafted rows that
+# pyarrow can't represent (e.g. messages=None, messages="not a list").
+# ---------------------------------------------------------------------------
+
+
+class _MockDataset:
+    """Behaves like an HF Dataset for iteration, len(), and index access."""
+
+    def __init__(self, rows: list, columns: list):
+        self.column_names = columns
+        self._rows = rows
+
+    def __len__(self):
+        return len(self._rows)
+
+    def __iter__(self):
+        return iter(self._rows)
+
+    def __getitem__(self, idx):
+        """Support dataset[i] (int) and dataset[i][col] patterns used by _probe_conversation."""
+        return self._rows[idx]
+
+
+def test_p1_fix():
+    """Verify that find_none_chatml records rows where messages is None or non-list."""
+    section("P1 Fix Verification — non-list conversation column values")
+
+    sys.path.insert(0, str(REPO_ROOT / "tests" / "utils"))
+    from generate_dataset_with_none import make_chatml_p1_rows
+
+    p1_rows = make_chatml_p1_rows()
+    mock_ds = _MockDataset(p1_rows, ["messages"])
+
+    print(f"  Rows under test: {p1_rows}")
+    stats = find_none_chatml(mock_ds, col = "messages")
+    print_report(stats, "chatml")
+
+    expected_bad = set(range(len(p1_rows)))
+    actual_bad = set(stats.get("bad_row_indices", []))
+    all_caught = expected_bad.issubset(actual_bad)
+    print(
+        f"  [{'PASS' if all_caught else 'FAIL'}] P1 fix: all {len(expected_bad)} non-list rows caught"
+    )
+
+    for row in stats.get("findings", []):
+        vtype = row.get("value_type", "?")
+        raw = row.get("raw_value", "?")
+        print(f"    row {row['row_index']}: value_type={vtype!r}  raw={raw}")
+
+    return stats
+
+
+def test_probe_p1_fix():
+    """Verify that scan_dataset(fmt='auto') on a fully-corrupt messages column
+    routes through _probe_conversation's all_corrupt=True path and returns
+    findings rather than raising ValueError."""
+    section("P1 Fix Verification — probe skip on all-corrupt column (auto-detect path)")
+
+    # All 5 rows have messages=None — no dict turn will ever be found in the probe.
+    all_corrupt_rows = [{"messages": None}] * 5
+    mock_ds = _MockDataset(all_corrupt_rows, ["messages"])
+
+    print(f"  Rows under test: {len(all_corrupt_rows)} rows all with messages=None")
+    try:
+        stats = scan_dataset(mock_ds, fmt = "auto")
+        print_report(stats, stats.get("format", "?"))
+        bad = len(stats.get("bad_row_indices", []))
+        status = "PASS" if bad == len(all_corrupt_rows) else "FAIL"
+        print(
+            f"  [{status}] Probe P1 fix: {bad}/{len(all_corrupt_rows)} all-corrupt rows caught via auto-detect"
+        )
+        return stats
+    except ValueError as exc:
+        print(
+            f"  [FAIL] scan_dataset raised ValueError (probe P1 bug NOT fixed): {exc}"
+        )
+        return None
+
+
+def test_probe_string_corrupt():
+    """Verify that a plain-string 'messages' column is NOT classified as chatml.
+    The all_corrupt+has_list_or_none guard (P2 fix) must prevent plain-string
+    columns from triggering the chatml path — scan_dataset should raise
+    ValueError('unknown format') rather than misclassifying as chatml."""
+    section("P2 Fix Verification — plain-string messages not classified as chatml")
+
+    string_rows = [{"messages": "this is a string, not a list"}] * 5
+    mock_ds = _MockDataset(string_rows, ["messages"])
+
+    print(f"  Rows under test: {len(string_rows)} rows all with messages='string'")
+    try:
+        stats = scan_dataset(mock_ds, fmt = "auto")
+        fmt = stats.get("format", "?")
+        # Plain strings must NOT be classified as chatml.
+        not_chatml = fmt != "chatml"
+        status = "PASS" if not_chatml else "FAIL"
+        print(
+            f"  [{status}] String-corrupt probe: detected fmt={fmt!r} "
+            f"(expected: anything except 'chatml')"
+        )
+        return stats
+    except ValueError as exc:
+        # ValueError (unknown format) is the CORRECT outcome — plain strings
+        # are not a conversation column and should not match any format.
+        print(
+            f"  [PASS] String-corrupt probe: scan_dataset raised ValueError (not chatml, as expected): {exc}"
+        )
+        return None
+
+
+def test_explicit_fmt_corrupt():
+    """Verify that scan_dataset(fmt='chatml') on an all-corrupt column returns
+    findings instead of raising ValueError (explicit format + all_corrupt path)."""
+    section("P1 Fix Verification — explicit fmt='chatml' on all-corrupt column")
+
+    all_corrupt_rows = [{"messages": None}] * 4 + [{"messages": "not a list"}] * 3
+    mock_ds = _MockDataset(all_corrupt_rows, ["messages"])
+
+    print(f"  Rows under test: {len(all_corrupt_rows)} rows (4×None, 3×string)")
+    try:
+        stats = scan_dataset(mock_ds, fmt = "chatml")
+        print_report(stats, stats.get("format", "?"))
+        bad = len(stats.get("bad_row_indices", []))
+        status = "PASS" if bad == len(all_corrupt_rows) else "FAIL"
+        print(
+            f"  [{status}] Explicit-fmt P1 fix: {bad}/{len(all_corrupt_rows)} rows caught with fmt='chatml'"
+        )
+        return stats
+    except ValueError as exc:
+        print(
+            f"  [FAIL] scan_dataset raised ValueError (explicit-fmt P1 NOT fixed): {exc}"
+        )
+        return None
+
+
+def test_p2_probe_skips_corrupt_prefers_valid():
+    """P2 fix: probe must continue past a corrupt 'messages' column and find
+    a valid 'conversations' column rather than returning all_corrupt immediately."""
+    section(
+        "P2 Fix Verification — probe continues past corrupt first column to valid second"
+    )
+
+    # messages column is all-None; conversations is a valid ShareGPT column.
+    rows = [
+        {
+            "messages": None,
+            "conversations": [
+                {"from": "human", "value": "Hello"},
+                {"from": "gpt", "value": "Hi!"},
+            ],
+        }
+    ] * 5 + [
+        {
+            "messages": None,
+            "conversations": [
+                {"from": "human", "value": ""},
+                {"from": "gpt", "value": "OK"},
+            ],
+        }
+    ] * 2
+    mock_ds = _MockDataset(rows, ["messages", "conversations"])
+
+    print(
+        f"  Rows: {len(rows)} — messages=None, conversations=valid ShareGPT (2 bad value='')"
+    )
+    try:
+        stats = scan_dataset(mock_ds, fmt = "auto")
+        fmt = stats.get("format", "?")
+        col = stats.get("column", "?")
+        bad = len(stats.get("bad_row_indices", []))
+        # Should have detected 'conversations' (sharegpt), not 'messages'.
+        correct_col = col == "conversations"
+        correct_fmt = fmt == "sharegpt"
+        correct_bad = bad == 2
+        status = "PASS" if (correct_col and correct_fmt and correct_bad) else "FAIL"
+        print(
+            f"  [{status}] Probe P2 fix: fmt={fmt!r} col={col!r} bad_rows={bad} "
+            f"(expected fmt='sharegpt' col='conversations' bad=2)"
+        )
+        print_report(stats, fmt)
+        return stats
+    except ValueError as exc:
+        print(f"  [FAIL] scan_dataset raised ValueError: {exc}")
+        return None
+
+
+def test_p2_explicit_fmt_col_priority():
+    """P2 fix: explicit fmt='sharegpt' must let find_none_sharegpt choose its own
+    column (conversations) rather than being forced onto the probe's column (messages)."""
+    section(
+        "P2 Fix Verification — explicit fmt='sharegpt' respects per-scanner column priority"
+    )
+
+    # messages has valid role/content turns (chatml-ish); conversations has bad sharegpt turns.
+    rows = [
+        {
+            "messages": [
+                {"role": "user", "content": "Hi"},
+                {"role": "assistant", "content": "Hello"},
+            ],
+            "conversations": [
+                {"from": "human", "value": None},
+                {"from": "gpt", "value": "OK"},
+            ],
+        }
+    ] * 5
+    mock_ds = _MockDataset(rows, ["messages", "conversations"])
+
+    print(
+        f"  Rows: {len(rows)} — messages=clean chatml, conversations=bad sharegpt (value=None)"
+    )
+    stats = scan_dataset(mock_ds, fmt = "sharegpt")
+    col = stats.get("column", "?")
+    bad = len(stats.get("bad_row_indices", []))
+    # fmt='sharegpt' should scan 'conversations', find 5 bad rows.
+    correct_col = col == "conversations"
+    correct_bad = bad == 5
+    status = "PASS" if (correct_col and correct_bad) else "FAIL"
+    print(
+        f"  [{status}] Explicit-fmt P2 fix: col={col!r} bad_rows={bad} "
+        f"(expected col='conversations' bad=5)"
+    )
+    print_report(stats, "sharegpt")
+    return stats
+
+
+def test_p2_gptoss_col_priority():
+    """P2 fix: fmt='gptoss' must scan 'messages' only, not fall through to
+    a clean 'conversations' column when messages is corrupt."""
+    section("P2 Fix Verification — fmt='gptoss' scans messages only, not conversations")
+
+    # messages is all-None (corrupt); conversations is clean sharegpt.
+    rows = [
+        {
+            "messages": None,
+            "conversations": [
+                {"from": "human", "value": "Hello"},
+                {"from": "gpt", "value": "Hi!"},
+            ],
+        }
+    ] * 5
+    mock_ds = _MockDataset(rows, ["messages", "conversations"])
+
+    print(
+        f"  Rows: {len(rows)} — messages=None (corrupt), conversations=clean sharegpt"
+    )
+    try:
+        stats = scan_dataset(mock_ds, fmt = "gptoss")
+        col = stats.get("column", "?")
+        bad = len(stats.get("bad_row_indices", []))
+        correct_col = col == "messages"
+        correct_bad = bad == 5
+        status = "PASS" if (correct_col and correct_bad) else "FAIL"
+        print(
+            f"  [{status}] gptoss P2 fix: col={col!r} bad_rows={bad} "
+            f"(expected col='messages' bad=5)"
+        )
+        print_report(stats, "gptoss")
+        return stats
+    except ValueError as exc:
+        print(f"  [FAIL] scan_dataset raised ValueError: {exc}")
+        return None
+
+
+def test_new_p1_explicit_sharegpt_both_all_corrupt():
+    """NEW P1 (commit eb7fea3b7e): when fmt='sharegpt' and both 'messages' and
+    'conversations' are all-corrupt in the first 100 rows, scan_dataset must scan
+    'conversations' (the sharegpt column), NOT 'messages' (the generic probe's
+    first candidate)."""
+    section(
+        "NEW P1 — explicit fmt='sharegpt' scans 'conversations' even when both columns all-corrupt"
+    )
+
+    # Both columns are all-corrupt: every row has None.
+    rows = [{"messages": None, "conversations": None}] * 5
+    mock_ds = _MockDataset(rows, ["messages", "conversations"])
+
+    print(f"  Rows: {len(rows)} — messages=None, conversations=None (both all-corrupt)")
+    try:
+        stats = scan_dataset(mock_ds, fmt = "sharegpt")
+        col = stats.get("column", "?")
+        bad = len(stats.get("bad_row_indices", []))
+        # MUST scan 'conversations', not 'messages'.
+        correct_col = col == "conversations"
+        correct_bad = bad == 5
+        status = "PASS" if (correct_col and correct_bad) else "FAIL"
+        print(
+            f"  [{status}] New-P1 explicit sharegpt: col={col!r} bad_rows={bad} "
+            f"(expected col='conversations' bad=5)"
+        )
+        print_report(stats, "sharegpt")
+        return stats
+    except ValueError as exc:
+        print(f"  [FAIL] scan_dataset raised ValueError: {exc}")
+        return None
+
+
+def test_new_p2_plain_string_messages_not_chatml():
+    """NEW P2 (commit eb7fea3b7e): a dataset where 'messages' contains plain
+    strings (not lists) must NOT be auto-classified as chatml.  The all_corrupt
+    path in FORMAT_REGISTRY chatml match previously triggered here too."""
+    section("NEW P2 — plain-string 'messages' column must NOT be classified as chatml")
+
+    # messages is a plain text column, not a conversation column at all.
+    rows = [{"messages": "hello world"}] * 5
+    mock_ds = _MockDataset(rows, ["messages"])
+
+    print(
+        f"  Rows: {len(rows)} — messages='hello world' (plain strings, not conversation)"
+    )
+    try:
+        stats = scan_dataset(mock_ds, fmt = "auto")
+        fmt = stats.get("format", "?")
+        # Classifying as chatml is wrong; 'unknown' or another non-chatml result expected.
+        not_chatml = fmt != "chatml"
+        status = "PASS" if not_chatml else "FAIL"
+        print(
+            f"  [{status}] New-P2 plain-string messages: detected fmt={fmt!r} "
+            f"(expected: anything except 'chatml')"
+        )
+        return stats
+    except ValueError as exc:
+        # ValueError is also acceptable — the column isn't a valid conversation format.
+        print(
+            f"  [PASS] New-P2 plain-string messages: scan_dataset raised ValueError (not chatml): {exc}"
+        )
+        return {
+            "format": "unknown",
+            "total_rows": 5,
+            "bad_row_indices": [],
+            "findings": [],
+        }
+
+
+def test_synthetic():
+    section("1. Synthetic Datasets (generated in-memory)")
+
+    sys.path.insert(0, str(REPO_ROOT / "tests" / "utils"))
+    from generate_dataset_with_none import (
+        make_alpaca_dataset,
+        make_chatml_dataset,
+        make_sharegpt_dataset,
+    )
+
+    results = {}
+
+    # ChatML — 10 clean rows (0-9), 8 bad rows (10-17)
+    ds_chatml = make_chatml_dataset()
+    stats = run_scan(ds_chatml, "Synthetic ChatML (messages/role/content)")
+    assert_bad_rows(stats, 8, "ChatML bad rows")
+    assert_exact_recall(stats, set(range(10, 18)), "ChatML exact recall")
+    results["chatml"] = stats
+
+    # ShareGPT — 5 clean rows (0-4), 5 bad rows (5-9)
+    ds_sgpt = make_sharegpt_dataset()
+    stats = run_scan(ds_sgpt, "Synthetic ShareGPT (conversations/from/value)")
+    assert_bad_rows(stats, 3, "ShareGPT bad rows")
+    assert_exact_recall(stats, set(range(5, 10)), "ShareGPT exact recall")
+    results["sharegpt"] = stats
+
+    # Alpaca — 5 clean rows (0-4), 5 bad rows (5-9)
+    ds_alpaca = make_alpaca_dataset()
+    stats = run_scan(ds_alpaca, "Synthetic Alpaca (instruction/output)")
+    assert_bad_rows(stats, 4, "Alpaca bad rows")
+    assert_exact_recall(stats, set(range(5, 10)), "Alpaca exact recall")
+    results["alpaca"] = stats
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# 2. HuggingFace: peteromallet/dataclaw-peteromallet
+# ---------------------------------------------------------------------------
+
+
+def _brute_force_bad_rows(ds, fmt: str) -> set:
+    """Pure-Python ground-truth scanner — zero shared code with dataset_none_detect.
+
+    Iterates every row and flags it bad if any field/turn contains None, empty,
+    or whitespace-only content.  Returns the set of bad row indices.
+
+    Intentionally re-implements the same logic from scratch so that agreement
+    between this and scan_dataset() constitutes independent proof of correctness.
+    """
+
+    def _blank(val) -> bool:
+        if val is None:
+            return True
+        if isinstance(val, str) and val.strip() == "":
+            return True
+        return False
+
+    bad: set = set()
+    for i, row in enumerate(ds):
+        if fmt in ("chatml", "gptoss"):
+            msgs = row.get("messages")
+            if msgs is None or not isinstance(msgs, list):
+                bad.add(i)
+                continue
+            for turn in msgs:
+                if turn is None or (
+                    isinstance(turn, dict) and _blank(turn.get("content"))
+                ):
+                    bad.add(i)
+                    break
+        elif fmt == "sharegpt":
+            convs = row.get("conversations")
+            if convs is None or not isinstance(convs, list):
+                bad.add(i)
+                continue
+            for turn in convs:
+                if turn is None or (
+                    isinstance(turn, dict) and _blank(turn.get("value"))
+                ):
+                    bad.add(i)
+                    break
+        elif fmt == "alpaca":
+            if _blank(row.get("instruction")) or _blank(row.get("output")):
+                bad.add(i)
+    return bad
+
+
+def _assert_hf_no_misses(ds, stats: dict, label: str) -> bool:
+    """Independent ground-truth check: verify scan_dataset() found every bad row
+    that brute-force row-by-row iteration also finds.
+
+    brute_force_bad ⊆ module_bad  →  no misses (the key assertion)
+    module_bad ⊆ brute_force_bad  →  no false positives (informational)
+    """
+    fmt = stats.get("format", "unknown")
+    module_bad = set(stats.get("bad_row_indices", []))
+
+    print(f"  Running brute-force independent scan (fmt={fmt!r}, {len(ds)} rows)...")
+    brute_bad = _brute_force_bad_rows(ds, fmt)
+
+    missed = brute_bad - module_bad  # rows brute-force found but module missed
+    extra = module_bad - brute_bad  # rows module flagged that brute-force didn't
+
+    no_misses = len(missed) == 0
+    snippet = ""
+    if missed:
+        sample = sorted(missed)[:10]
+        snippet = f"  (first missed rows: {sample}{'...' if len(missed) > 10 else ''})"
+    status = "PASS" if no_misses else "FAIL"
+    print(
+        f"  [{status}] {label} no-miss check — "
+        f"brute-force: {len(brute_bad)} bad rows  |  "
+        f"module: {len(module_bad)} bad rows  |  "
+        f"missed: {len(missed)}{snippet}"
+    )
+    if extra:
+        # Module may legitimately flag more rows than brute-force (e.g. extra
+        # structural checks) — informational only, not a failure.
+        print(
+            f"  [INFO] {label} — module flagged {len(extra)} rows not in brute-force "
+            f"(may reflect additional structural checks, not false positives)"
+        )
+    return no_misses
+
+
+def test_dataclaw():
+    section("2. HuggingFace — peteromallet/dataclaw-peteromallet")
+    try:
+        from datasets import load_dataset
+
+        print("  Loading dataset (streaming first 500 rows for speed)...")
+        ds = load_dataset(
+            "peteromallet/dataclaw-peteromallet",
+            split = "train",
+            streaming = False,
+        )
+        print(f"  Loaded {len(ds)} rows, columns: {ds.column_names}")
+        stats = run_scan(ds, "dataclaw-peteromallet")
+        if stats:
+            _assert_hf_no_misses(ds, stats, "dataclaw-peteromallet")
+        return stats
+    except Exception as exc:
+        print(f"  [ERROR] Could not load dataclaw dataset: {exc}")
+        traceback.print_exc()
+        return None
+
+
+# ---------------------------------------------------------------------------
+# 3. HuggingFace: peteromallet/my-personal-codex-data
+# ---------------------------------------------------------------------------
+
+
+def test_codex_data():
+    section("3. HuggingFace — peteromallet/my-personal-codex-data")
+    try:
+        # load_dataset fails on this repo because ujson chokes on the large
+        # JSONL batch.  Download the raw file and parse it ourselves instead.
+        from huggingface_hub import hf_hub_download
+        from datasets import Dataset
+
+        print("  Downloading conversations.jsonl via huggingface_hub...")
+        path = hf_hub_download(
+            "peteromallet/my-personal-codex-data",
+            "conversations.jsonl",
+            repo_type = "dataset",
+        )
+        rows = []
+        with open(path, encoding = "utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    rows.append(json.loads(line))
+        ds = Dataset.from_list(rows)
+        print(f"  Loaded {len(ds)} rows, columns: {ds.column_names}")
+        stats = run_scan(ds, "my-personal-codex-data")
+        if stats:
+            _assert_hf_no_misses(ds, stats, "my-personal-codex-data")
+        return stats
+    except Exception as exc:
+        print(f"  [ERROR] Could not load codex dataset: {exc}")
+        traceback.print_exc()
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main():
+    started = datetime.now().isoformat()
+
+    with open(LOG_PATH, "w", encoding = "utf-8") as log_file:
+        sys.stdout = Tee(log_file)
+
+        print(f"dataset_none_detect.py — Test Run")
+        print(f"Started: {started}")
+        print(f"Python:  {sys.version}")
+        print(f"Log:     {LOG_PATH}")
+
+        all_results = {}
+
+        all_results["p1_fix"] = test_p1_fix()
+        all_results["probe_p1_fix"] = test_probe_p1_fix()
+        all_results["probe_string_corrupt"] = test_probe_string_corrupt()
+        all_results["explicit_fmt_corrupt"] = test_explicit_fmt_corrupt()
+        all_results["p2_probe_valid_fallback"] = (
+            test_p2_probe_skips_corrupt_prefers_valid()
+        )
+        all_results["p2_explicit_col_priority"] = test_p2_explicit_fmt_col_priority()
+        all_results["p2_gptoss_col_priority"] = test_p2_gptoss_col_priority()
+        all_results["new_p1_sharegpt_all_corrupt"] = (
+            test_new_p1_explicit_sharegpt_both_all_corrupt()
+        )
+        all_results["new_p2_plain_string_not_chatml"] = (
+            test_new_p2_plain_string_messages_not_chatml()
+        )
+        all_results["synthetic"] = test_synthetic()
+        all_results["dataclaw"] = test_dataclaw()
+        all_results["codex_data"] = test_codex_data()
+
+        # ---------------------------------------------------------------------------
+        # Summary table
+        # ---------------------------------------------------------------------------
+        section("SUMMARY")
+        rows = [
+            ("Dataset", "Format", "Total rows", "Bad rows", "Bad turns"),
+        ]
+
+        def _row(label, stats):
+            if stats is None:
+                return (label, "ERROR", "-", "-", "-")
+            fmt = stats.get("format", "?")
+            total = stats.get("total_rows", "?")
+            bad = len(stats.get("bad_row_indices", []))
+            turns = stats.get("total_none_turns") or len(stats.get("findings", []))
+            return (label, fmt, str(total), str(bad), str(turns))
+
+        for key, label in [
+            ("chatml", "Synthetic chatml"),
+            ("sharegpt", "Synthetic sharegpt"),
+            ("alpaca", "Synthetic alpaca"),
+        ]:
+            s = all_results.get("synthetic") or {}
+            rows.append(_row(label, s.get(key) if isinstance(s, dict) else None))
+
+        rows.append(_row("dataclaw-peteromallet", all_results.get("dataclaw")))
+        rows.append(_row("my-personal-codex-data", all_results.get("codex_data")))
+
+        col_widths = [max(len(r[i]) for r in rows) for i in range(5)]
+        fmt_str = "  " + "  ".join(f"{{:<{w}}}" for w in col_widths)
+        header = rows[0]
+        print(fmt_str.format(*header))
+        print("  " + "-" * (sum(col_widths) + 10))
+        for row in rows[1:]:
+            print(fmt_str.format(*row))
+
+        # Write machine-readable JSON summary alongside the log
+        json_path = LOG_DIR / "none_detect_results.json"
+        summary = {}
+        for key, val in all_results.items():
+            if val is None:
+                summary[key] = None
+            elif isinstance(val, dict):
+                # Flatten synthetic sub-keys
+                if key == "synthetic":
+                    for subkey, subval in val.items():
+                        summary[f"synthetic_{subkey}"] = (
+                            {
+                                "format": subval.get("format"),
+                                "total_rows": subval.get("total_rows"),
+                                "bad_row_count": len(subval.get("bad_row_indices", [])),
+                                "bad_turn_count": subval.get(
+                                    "total_none_turns", len(subval.get("findings", []))
+                                ),
+                            }
+                            if subval
+                            else None
+                        )
+                else:
+                    summary[key] = {
+                        "format": val.get("format"),
+                        "total_rows": val.get("total_rows"),
+                        "bad_row_count": len(val.get("bad_row_indices", [])),
+                        "bad_turn_count": val.get(
+                            "total_none_turns", len(val.get("findings", []))
+                        ),
+                    }
+
+        json_path.write_text(json.dumps(summary, indent = 2), encoding = "utf-8")
+
+        finished = datetime.now().isoformat()
+        print(f"\nFinished: {finished}")
+        print(f"Log:      {LOG_PATH}")
+        print(f"JSON:     {json_path}")
+
+        sys.stdout = sys.stdout.stdout  # restore
+
+
+if __name__ == "__main__":
+    main()

From e61167b29068ee6c496a2f254d931f370391e011 Mon Sep 17 00:00:00 2001
From: Ashwin Upadhyay <ashwinupadhyay09@gmail.com>
Date: Wed, 3 Jun 2026 17:34:00 +0530
Subject: [PATCH 072/222] Hide non-matching threads in chat search (#5651)

Fixes #5572. Replaces cmdk's default fuzzy filter with a strict substring-token filter so threads that do not match the query are hidden and the empty state shows. Each item uses its unique thread id as the cmdk value, with the searchable title and preview supplied via keywords.
---
 .../chat/components/chat-search-dialog.tsx    | 20 +++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index 85480359b4..676dcc23d5 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -16,6 +16,21 @@ import { useEffect } from "react";
 import { useChatSearchIndex } from "../hooks/use-chat-search-index";
 import { useChatSearchStore } from "../stores/chat-search-store";
 
+// cmdk's default fuzzy scorer keeps non-matching rows visible (issue #5572), so
+// require every whitespace token to be a substring of the item's keywords.
+// `value` is the unique thread id (cmdk selection); title/preview come via keywords.
+export function chatSearchFilter(
+  _value: string,
+  search: string,
+  keywords?: string[],
+): number {
+  const query = search.trim().toLowerCase();
+  if (query === "") return 1;
+  const haystack = (keywords ?? []).join(" ").toLowerCase();
+  const tokens = query.split(/\s+/);
+  return tokens.every((token) => haystack.includes(token)) ? 1 : 0;
+}
+
 function formatRelative(createdAt: number): string {
   const diff = Date.now() - createdAt;
   const day = 86_400_000;
@@ -52,7 +67,7 @@ export function ChatSearchDialog() {
       className="corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px] border-0 ring-0 shadow-[0_10px_34px_rgba(0,0,0,0.12)] dark:border dark:border-border dark:ring-0 dark:shadow-none"
       overlayClassName="bg-transparent"
     >
-      <Command className="rounded-4xl p-0">
+      <Command className="rounded-4xl p-0" filter={chatSearchFilter}>
         <div className="flex items-center gap-3 border-b border-border/40 px-4 py-3">
           <HugeiconsIcon
             icon={SearchIcon}
@@ -84,7 +99,8 @@ export function ChatSearchDialog() {
             {items.map((item) => (
               <CommandPrimitive.Item
                 key={item.id}
-                value={`${item.title} ${item.preview}`}
+                value={item.id}
+                keywords={[item.title, item.preview]}
                 onSelect={() => {
                   navigate({
                     to: "/chat",

From 4f501e53e9447d2bfbeef1710a14706fb96b7316 Mon Sep 17 00:00:00 2001
From: danielhanchen <23090290+danielhanchen@users.noreply.github.com>
Date: Wed, 3 Jun 2026 10:36:50 +0000
Subject: [PATCH 073/222] Update vulnerable dependencies to patched versions

Clears the safe set of Dependabot advisories.

Frontend (overrides, all transitive; npm audit now 0):
  mermaid 11.14.0->11.15.0, hono 4.12.17->4.12.18, qs 6.15.1->6.15.2,
  ip-address 10.1.0->10.1.1 (also clears express-rate-limit), and
  brace-expansion 5.0.5->5.0.6 (scoped, the 1.1.14 line is untouched).

Desktop: tauri 2.10.3->2.11.1, pulling the runtime crates it requires
(tao, wry, tauri-runtime, tauri-build, tray-icon).

Backend (test-only): pytest <9.0 -> >=9.0.3,<10, and the pinned
pytest-rerunfailures==15.1 -> >=16.2,<17 (16.2 is the first release with
pytest 9 support). Verified pytest 9.0.3 + rerunfailures 16.3 +
pytest-json-report + pytest-xdist run reruns, fixtures, json reports and
xdist together.

Left out intentionally: transformers (stays 4.x for unsloth compat; patch
is 5.0.0rc3), sqlfluff (major 3->4), glib/rand (stack-coupled transitive).
---
 studio/backend/requirements/extras.txt |   4 +-
 studio/frontend/package-lock.json      | 182 ++++------------------
 studio/frontend/package.json           |   7 +-
 studio/src-tauri/Cargo.lock            | 202 ++++++++++++++++++-------
 4 files changed, 185 insertions(+), 210 deletions(-)

diff --git a/studio/backend/requirements/extras.txt b/studio/backend/requirements/extras.txt
index daa8982ea5..40737b0876 100644
--- a/studio/backend/requirements/extras.txt
+++ b/studio/backend/requirements/extras.txt
@@ -11,9 +11,9 @@ hydra-core
 hypothesis
 kgb
 parameterized
-pytest<9.0
+pytest>=9.0.3,<10
 pytest-json-report
-pytest-rerunfailures==15.1
+pytest-rerunfailures>=16.2,<17
 pytest-xdist
 # Also needed by sentence_transformers (installed with --no-deps in extras-no-deps.txt)
 scikit-learn==1.7.1
diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index e66f62d2f2..f36f2d8e79 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -856,41 +856,10 @@
       "integrity": "sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==",
       "license": "MIT"
     },
-    "node_modules/@chevrotain/cst-dts-gen": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
-      "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/gast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
-      "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/regexp-to-ast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
-      "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==",
-      "license": "Apache-2.0"
-    },
     "node_modules/@chevrotain/types": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
-      "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==",
-      "license": "Apache-2.0"
-    },
-    "node_modules/@chevrotain/utils": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
-      "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==",
+      "version": "11.1.2",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
+      "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
       "license": "Apache-2.0"
     },
     "node_modules/@dagrejs/dagre": {
@@ -1598,12 +1567,12 @@
       }
     },
     "node_modules/@mermaid-js/parser": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
-      "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.1.tgz",
+      "integrity": "sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==",
       "license": "MIT",
       "dependencies": {
-        "langium": "^4.0.0"
+        "@chevrotain/types": "~11.1.1"
       }
     },
     "node_modules/@modelcontextprotocol/sdk": {
@@ -6294,9 +6263,9 @@
       }
     },
     "node_modules/@ts-morph/common/node_modules/brace-expansion": {
-      "version": "5.0.5",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
-      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
+      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
@@ -6942,9 +6911,9 @@
       }
     },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": {
-      "version": "5.0.5",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
-      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
+      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -7637,34 +7606,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/chevrotain": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
-      "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@chevrotain/cst-dts-gen": "12.0.0",
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/regexp-to-ast": "12.0.0",
-        "@chevrotain/types": "12.0.0",
-        "@chevrotain/utils": "12.0.0"
-      },
-      "engines": {
-        "node": ">=22.0.0"
-      }
-    },
-    "node_modules/chevrotain-allstar": {
-      "version": "0.4.3",
-      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.3.tgz",
-      "integrity": "sha512-2X4mkroolSMKqW+H22pyPMUVDqYZzPhephTmg/NODKb1IGYPHfxfhcW0EjS7wcPJNbze2i4vBWT7zT5FKF2lrQ==",
-      "license": "MIT",
-      "dependencies": {
-        "lodash-es": "^4.18.1"
-      },
-      "peerDependencies": {
-        "chevrotain": "^12.0.0"
-      }
-    },
     "node_modules/class-variance-authority": {
       "version": "0.7.1",
       "resolved": "https://registry.npmjs.org/class-variance-authority/-/class-variance-authority-0.7.1.tgz",
@@ -10044,9 +9985,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.17",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.17.tgz",
-      "integrity": "sha512-FbJJNb/XgX7YW0hX/V8w5oYLztKEsRLykCMZWt1WdLtsfjzMvmoqWBA4H4t5norinq8/rh20oiZYr+WSl4UzAQ==",
+      "version": "4.12.18",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.18.tgz",
+      "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -10199,9 +10140,9 @@
       }
     },
     "node_modules/ip-address": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
-      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "version": "10.1.1",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.1.tgz",
+      "integrity": "sha512-1FMu8/N15Ck1BL551Jf42NYIoin2unWjLQ2Fze/DXryJRl5twqtwNHlO39qERGbIOcKYWHdgRryhOC+NG4eaLw==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -10627,24 +10568,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/langium": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.3.tgz",
-      "integrity": "sha512-sOPIi4hISFnY7twwV97ca1TsxpBtXq0URu/LL1AvxwccPG/RIBBlKS7a/f/EL6w8lTNaS0EFs/F+IdSOaqYpng==",
-      "license": "MIT",
-      "dependencies": {
-        "@chevrotain/regexp-to-ast": "~12.0.0",
-        "chevrotain": "~12.0.0",
-        "chevrotain-allstar": "~0.4.3",
-        "vscode-languageserver": "~9.0.1",
-        "vscode-languageserver-textdocument": "~1.0.11",
-        "vscode-uri": "~3.1.0"
-      },
-      "engines": {
-        "node": ">=20.10.0",
-        "npm": ">=10.2.3"
-      }
-    },
     "node_modules/layout-base": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz",
@@ -11448,14 +11371,14 @@
       }
     },
     "node_modules/mermaid": {
-      "version": "11.14.0",
-      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
-      "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
+      "version": "11.15.0",
+      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.15.0.tgz",
+      "integrity": "sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==",
       "license": "MIT",
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.1",
         "@iconify/utils": "^3.0.2",
-        "@mermaid-js/parser": "^1.1.0",
+        "@mermaid-js/parser": "^1.1.1",
         "@types/d3": "^7.4.3",
         "@upsetjs/venn.js": "^2.0.0",
         "cytoscape": "^3.33.1",
@@ -11466,14 +11389,14 @@
         "dagre-d3-es": "7.0.14",
         "dayjs": "^1.11.19",
         "dompurify": "^3.3.1",
+        "es-toolkit": "^1.45.1",
         "katex": "^0.16.25",
         "khroma": "^2.1.0",
-        "lodash-es": "^4.17.23",
         "marked": "^16.3.0",
         "roughjs": "^4.6.6",
         "stylis": "^4.3.6",
         "ts-dedent": "^2.2.0",
-        "uuid": "^11.1.0"
+        "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
       }
     },
     "node_modules/micromark": {
@@ -12942,9 +12865,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.15.1",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
-      "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==",
+      "version": "6.15.2",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
+      "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"
@@ -15302,55 +15225,6 @@
         "node": "^10 || ^12 || >=14"
       }
     },
-    "node_modules/vscode-jsonrpc": {
-      "version": "8.2.0",
-      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
-      "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
-    "node_modules/vscode-languageserver": {
-      "version": "9.0.1",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
-      "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
-      "license": "MIT",
-      "dependencies": {
-        "vscode-languageserver-protocol": "3.17.5"
-      },
-      "bin": {
-        "installServerIntoExtension": "bin/installServerIntoExtension"
-      }
-    },
-    "node_modules/vscode-languageserver-protocol": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
-      "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
-      "license": "MIT",
-      "dependencies": {
-        "vscode-jsonrpc": "8.2.0",
-        "vscode-languageserver-types": "3.17.5"
-      }
-    },
-    "node_modules/vscode-languageserver-textdocument": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
-      "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
-      "license": "MIT"
-    },
-    "node_modules/vscode-languageserver-types": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
-      "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
-      "license": "MIT"
-    },
-    "node_modules/vscode-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
-      "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
-      "license": "MIT"
-    },
     "node_modules/web-namespaces": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 40e9458d93..5ba0db143f 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -82,7 +82,12 @@
   "overrides": {
     "@tanstack/react-router": "1.169.2",
     "@tanstack/router-core": "1.169.2",
-    "@tanstack/history": "1.161.6"
+    "@tanstack/history": "1.161.6",
+    "mermaid": "11.15.0",
+    "hono": "4.12.18",
+    "qs": "6.15.2",
+    "ip-address": "10.1.1",
+    "brace-expansion@5.0.5": "5.0.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
diff --git a/studio/src-tauri/Cargo.lock b/studio/src-tauri/Cargo.lock
index b2398b9932..c964946d0e 100644
--- a/studio/src-tauri/Cargo.lock
+++ b/studio/src-tauri/Cargo.lock
@@ -703,14 +703,20 @@ dependencies = [
 
 [[package]]
 name = "ctor"
-version = "0.2.9"
+version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32a2785755761f3ddc1492979ce1e48d2c00d09311c39e4466429188f3dd6501"
+checksum = "352d39c2f7bef1d6ad73db6f5160efcaed66d94ef8c6c573a8410c00bf909a98"
 dependencies = [
- "quote",
- "syn 2.0.117",
+ "ctor-proc-macro",
+ "dtor",
 ]
 
+[[package]]
+name = "ctor-proc-macro"
+version = "0.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52560adf09603e58c9a7ee1fe1dcb95a16927b17c127f0ac02d6e768a0e25bc1"
+
 [[package]]
 name = "darling"
 version = "0.23.0"
@@ -745,6 +751,17 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "dbus"
+version = "0.9.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b942602992bb7acfd1f51c49811c58a610ef9181b6e66f3e519d79b540a3bf73"
+dependencies = [
+ "libc",
+ "libdbus-sys",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -923,6 +940,21 @@ dependencies = [
  "dtoa",
 ]
 
+[[package]]
+name = "dtor"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1057d6c64987086ff8ed0fd3fbf377a6b7d205cc7715868cd401705f715cbe4"
+dependencies = [
+ "dtor-proc-macro",
+]
+
+[[package]]
+name = "dtor-proc-macro"
+version = "0.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f678cf4a922c215c63e0de95eb1ff08a958a81d47e485cf9da1e27bf6305cfa5"
+
 [[package]]
 name = "dunce"
 version = "1.0.5"
@@ -2246,6 +2278,15 @@ version = "0.2.183"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
 
+[[package]]
+name = "libdbus-sys"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "328c4789d42200f1eeec05bd86c9c13c7f091d2ba9a6ea35acdf51f31bc0f043"
+dependencies = [
+ "pkg-config",
+]
+
 [[package]]
 name = "libloading"
 version = "0.7.4"
@@ -2415,9 +2456,9 @@ dependencies = [
 
 [[package]]
 name = "muda"
-version = "0.17.1"
+version = "0.19.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "01c1738382f66ed56b3b9c8119e794a2e23148ac8ea214eda86622d4cb9d415a"
+checksum = "47a2e3dff89cd322c66647942668faee0a2b1f88ea6cbb4d374b4a8d7e92528c"
 dependencies = [
  "crossbeam-channel",
  "dpi",
@@ -2428,10 +2469,10 @@ dependencies = [
  "objc2-core-foundation",
  "objc2-foundation",
  "once_cell",
- "png 0.17.16",
+ "png 0.18.1",
  "serde",
  "thiserror 2.0.18",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2466,12 +2507,6 @@ dependencies = [
  "thiserror 1.0.69",
 ]
 
-[[package]]
-name = "ndk-context"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27b02d87554356db9e9a873add8782d4ea6e3e58ea071a9adb9a2e8ddb884a8b"
-
 [[package]]
 name = "ndk-sys"
 version = "0.6.0+11769913"
@@ -2598,6 +2633,27 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "objc2-cloud-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-data"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-core-foundation"
 version = "0.3.2"
@@ -2622,6 +2678,38 @@ dependencies = [
  "objc2-io-surface",
 ]
 
+[[package]]
+name = "objc2-core-image"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5d563b38d2b97209f8e861173de434bd0214cf020e3423a52624cd1d989f006"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-location"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca347214e24bc973fc025fd0d36ebb179ff30536ed1f80252706db19ee452009"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-text"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+]
+
 [[package]]
 name = "objc2-encode"
 version = "4.1.0"
@@ -2692,8 +2780,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d87d638e33c06f577498cbcc50491496a3ed4246998a7fbba7ccb98b1e7eab22"
 dependencies = [
  "bitflags 2.11.0",
+ "block2",
  "objc2",
+ "objc2-cloud-kit",
+ "objc2-core-data",
  "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-image",
+ "objc2-core-location",
+ "objc2-core-text",
+ "objc2-foundation",
+ "objc2-quartz-core",
+ "objc2-user-notifications",
+]
+
+[[package]]
+name = "objc2-user-notifications"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9df9128cbbfef73cda168416ccf7f837b62737d748333bfe9ab71c245d76613e"
+dependencies = [
+ "objc2",
  "objc2-foundation",
 ]
 
@@ -2915,7 +3022,6 @@ version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
 dependencies = [
- "phf_macros 0.11.3",
  "phf_shared 0.11.3",
 ]
 
@@ -3014,19 +3120,6 @@ dependencies = [
  "syn 1.0.109",
 ]
 
-[[package]]
-name = "phf_macros"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
-dependencies = [
- "phf_generator 0.11.3",
- "phf_shared 0.11.3",
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
 [[package]]
 name = "phf_macros"
 version = "0.13.1"
@@ -4400,15 +4493,16 @@ dependencies = [
 
 [[package]]
 name = "tao"
-version = "0.34.8"
+version = "0.35.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9103edf55f2da3c82aea4c7fab7c4241032bfeea0e71fa557d98e00e7ce7cc20"
+checksum = "d1c93047acf68669466a34690ac58cca7010bd1b201e1ec86f1fd0a75d3dd4a9"
 dependencies = [
  "bitflags 2.11.0",
  "block2",
  "core-foundation 0.10.1",
  "core-graphics",
  "crossbeam-channel",
+ "dbus",
  "dispatch2",
  "dlopen2",
  "dpi",
@@ -4419,13 +4513,14 @@ dependencies = [
  "libc",
  "log",
  "ndk",
- "ndk-context",
  "ndk-sys",
  "objc2",
  "objc2-app-kit",
  "objc2-foundation",
+ "objc2-ui-kit",
  "once_cell",
  "parking_lot",
+ "percent-encoding",
  "raw-window-handle",
  "tao-macros",
  "unicode-segmentation",
@@ -4466,9 +4561,9 @@ checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
 
 [[package]]
 name = "tauri"
-version = "2.10.3"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da77cc00fb9028caf5b5d4650f75e31f1ef3693459dfca7f7e506d1ecef0ba2d"
+checksum = "b93bd86d231f0a8138f11a02a584769fe4b703dc36ae133d783228dbc4801405"
 dependencies = [
  "anyhow",
  "bytes",
@@ -4517,9 +4612,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-build"
-version = "2.5.6"
+version = "2.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4bbc990d1dbf57a8e1c7fa2327f2a614d8b757805603c1b9ba5c81bade09fd4d"
+checksum = "4aa1f9055fc23919a54e4e125052bed16ed04aef0487086e758fe01a67b451c7"
 dependencies = [
  "anyhow",
  "cargo_toml",
@@ -4533,15 +4628,14 @@ dependencies = [
  "serde_json",
  "tauri-utils",
  "tauri-winres",
- "toml 0.9.12+spec-1.1.0",
  "walkdir",
 ]
 
 [[package]]
 name = "tauri-codegen"
-version = "2.5.5"
+version = "2.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4a24476afd977c5d5d169f72425868613d82747916dd29e0a357c84c4bd6d29"
+checksum = "e4a0319528a025a38c4078e7dae2c446f4e63620ddb0659a643ede1cb38f90e9"
 dependencies = [
  "base64 0.22.1",
  "brotli",
@@ -4566,9 +4660,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-macros"
-version = "2.5.5"
+version = "2.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d39b349a98dadaffebb73f0a40dcd1f23c999211e5a2e744403db384d0c33de7"
+checksum = "ae6cb4e3896c21d2f6da5b31251d2faea0153bba56ed0e970f918115dbee4924"
 dependencies = [
  "heck 0.5.0",
  "proc-macro2",
@@ -4768,9 +4862,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-runtime"
-version = "2.10.1"
+version = "2.11.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2826d79a3297ed08cd6ea7f412644ef58e32969504bc4fbd8d7dbeabc4445ea2"
+checksum = "48222d7116c8807eaa6fe2f372e023fae125084e61e6eca6d70b7961cdf129ef"
 dependencies = [
  "cookie",
  "dpi",
@@ -4793,9 +4887,9 @@ dependencies = [
 
 [[package]]
 name = "tauri-runtime-wry"
-version = "2.10.1"
+version = "2.11.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e11ea2e6f801d275fdd890d6c9603736012742a1c33b96d0db788c9cdebf7f9e"
+checksum = "b83849ee63ecb27a8e8d0fe51915ca215076914aca43f96db1179f0f415f6cd9"
 dependencies = [
  "gtk",
  "http",
@@ -4819,14 +4913,15 @@ dependencies = [
 
 [[package]]
 name = "tauri-utils"
-version = "2.8.3"
+version = "2.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "219a1f983a2af3653f75b5747f76733b0da7ff03069c7a41901a5eb3ace4557d"
+checksum = "092379df9a707631978e6c56b1bc2401d387f01e2d4a3c123360d167bbb9aa95"
 dependencies = [
  "anyhow",
  "brotli",
  "cargo_metadata",
  "ctor",
+ "dom_query",
  "dunce",
  "glob",
  "html5ever 0.29.1",
@@ -4836,7 +4931,8 @@ dependencies = [
  "kuchikiki",
  "log",
  "memchr",
- "phf 0.11.3",
+ "phf 0.13.1",
+ "plist",
  "proc-macro2",
  "quote",
  "regex",
@@ -5262,9 +5358,9 @@ dependencies = [
 
 [[package]]
 name = "tray-icon"
-version = "0.21.3"
+version = "0.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a5e85aa143ceb072062fc4d6356c1b520a51d636e7bc8e77ec94be3608e5e80c"
+checksum = "15edbb0d80583e85ee8df283410038e17314df5cba30da2087a54a85216c0773"
 dependencies = [
  "crossbeam-channel",
  "dirs",
@@ -5276,10 +5372,10 @@ dependencies = [
  "objc2-core-graphics",
  "objc2-foundation",
  "once_cell",
- "png 0.17.16",
+ "png 0.18.1",
  "serde",
  "thiserror 2.0.18",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6526,9 +6622,9 @@ checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
 
 [[package]]
 name = "wry"
-version = "0.54.4"
+version = "0.55.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e5a8135d8676225e5744de000d4dff5a082501bf7db6a1c1495034f8c314edbc"
+checksum = "186f9871daa55fd9c016578b810d149de58367113db7fb72b462d2323ce19514"
 dependencies = [
  "base64 0.22.1",
  "block2",

From f47aacdaeaaeb211bce077c656e6ff4a2c435608 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 05:30:38 -0700
Subject: [PATCH 074/222] Show working reset-password command on Windows login
 error (#5971)

The Studio login error rewrote the backend's PATH-based command into a relative Windows path (.\unsloth_studio\Scripts\unsloth.exe ...) that only resolves from inside the Studio home dir and fails with CommandNotFoundException elsewhere. Removes the Windows-only rewrite and the now-unused usePlatformStore import so the backend's unsloth studio reset-password command is shown as-is on all platforms.
---
 studio/backend/routes/auth.py                 | 36 +++++++++++++++++--
 .../features/auth/components/auth-form.tsx    | 15 ++++----
 2 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index bb4ce87cd7..ef01bcc9a9 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -9,6 +9,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 
 import ipaddress
 import os
+import shlex
+import sys
 import threading
 import time
 from collections import deque
@@ -38,6 +40,36 @@ from auth.authentication import (
 router = APIRouter()
 
 
+def _reset_password_command() -> str:
+    """Shell command shown in the 'incorrect password' hint.
+
+    Prefer the ABSOLUTE path to this install's ``unsloth`` launcher (a sibling
+    of the running interpreter) so the hint works even when the launcher's
+    directory is not on PATH -- e.g. a terminal opened before install, a stale
+    Windows PATH, or ``~/.local/bin`` not on PATH (the default on macOS) -- and
+    regardless of the current working directory.
+
+    On POSIX the path is shell-quoted so spaces are handled. On Windows we only
+    use the bare absolute path when it has no spaces, because a quoted path needs
+    different syntax in cmd (``"..."``) vs PowerShell (``& "..."``); when it has
+    a space we fall back to the PATH-based form to stay unambiguous across
+    shells. If the launcher can't be located we fall back to the PATH form too.
+    """
+    try:
+        bin_dir = os.path.dirname(os.path.abspath(sys.executable))
+        if os.name == "nt":
+            exe = os.path.join(bin_dir, "unsloth.exe")
+            if os.path.isfile(exe) and " " not in exe:
+                return f"{exe} studio reset-password"
+        else:
+            exe = os.path.join(bin_dir, "unsloth")
+            if os.path.isfile(exe):
+                return f"{shlex.quote(exe)} studio reset-password"
+    except Exception:
+        pass
+    return "unsloth studio reset-password"
+
+
 # Per-(ip, username) bucket + per-IP aggregate. Account bucket stops one user's
 # typos from blocking others; the aggregate stops username-rotation spray.
 # Single-process only -- multi-worker deployments need a shared store.
@@ -228,7 +260,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
         _record_login_failure(unknown_key)
         raise HTTPException(
             status_code = status.HTTP_401_UNAUTHORIZED,
-            detail = "Incorrect password. Run 'unsloth studio reset-password' in your terminal to reset it.",
+            detail = f"Incorrect password. Run '{_reset_password_command()}' in your terminal to reset it.",
         )
 
     salt, pwd_hash, _jwt_secret, must_change_password = record
@@ -236,7 +268,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
         _record_login_failure(key)
         raise HTTPException(
             status_code = status.HTTP_401_UNAUTHORIZED,
-            detail = "Incorrect password. Run 'unsloth studio reset-password' in your terminal to reset it.",
+            detail = f"Incorrect password. Run '{_reset_password_command()}' in your terminal to reset it.",
         )
 
     _clear_login_bucket(key)
diff --git a/studio/frontend/src/features/auth/components/auth-form.tsx b/studio/frontend/src/features/auth/components/auth-form.tsx
index d753e1aab5..c1606c7020 100644
--- a/studio/frontend/src/features/auth/components/auth-form.tsx
+++ b/studio/frontend/src/features/auth/components/auth-form.tsx
@@ -10,7 +10,6 @@ import { Eye, EyeOff } from "lucide-react";
 import { useEffect, useState } from "react";
 import type { ReactElement } from "react";
 import type { SyntheticEvent } from "react";
-import { usePlatformStore } from "@/config/env";
 import { refreshSession } from "../api";
 
 // Bootstrap credentials injected into index.html by the backend
@@ -294,13 +293,13 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
       storeAuthTokens(token.access_token, token.refresh_token);
       navigate({ to: getPostAuthRoute() });
     } catch (err: unknown) {
-      let msg = err instanceof Error ? err.message : "Auth failed.";
-      if (msg.includes("unsloth studio reset-password") && usePlatformStore.getState().deviceType === "windows") {
-        msg = msg.replace(
-          "unsloth studio reset-password",
-          ".\\unsloth_studio\\Scripts\\unsloth.exe studio reset-password",
-        );
-      }
+      // The backend already returns the correct, PATH-based command
+      // ("unsloth studio reset-password"), which the installer puts on PATH on
+      // every platform. Do NOT rewrite it to a relative Windows path like
+      // ".\unsloth_studio\Scripts\unsloth.exe ..." -- that only resolves when the
+      // terminal happens to be inside the Studio home dir, so it fails with
+      // CommandNotFoundException everywhere else. Show the backend message as-is.
+      const msg = err instanceof Error ? err.message : "Auth failed.";
       setError(msg);
     } finally {
       setLoading(false);

From 92e7563fa28b7bcd8a1e8301a83cc47800830f87 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 05:39:38 -0700
Subject: [PATCH 075/222] Document install env vars in README advanced launch
 options (#5972)

Add copyable per-platform examples for UNSLOTH_NO_TORCH, UNSLOTH_PYTHON and
UNSLOTH_STUDIO_HOME (curl | sh after the pipe; $env: before irm | iex), and
move the UNSLOTH_CPU_THREADS note to the end of the section.
---
 README.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 562c35ff1a..b6a4b836a4 100644
--- a/README.md
+++ b/README.md
@@ -220,7 +220,33 @@ unsloth studio -p 8888
 ```
 
 #### Advanced launch options
-Cap Studio's native CPU thread pools on high-core hosts: `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`. Explicit `OMP_NUM_THREADS` / `MKL_NUM_THREADS` / `OPENBLAS_NUM_THREADS` / `NUMEXPR_NUM_THREADS` still take precedence.
+Installer options can be passed as environment variables. On macOS, Linux and WSL place the variable after the pipe so the shell passes it to `sh`; on Windows set it with `$env:` before piping to `iex`.
+
+Skip PyTorch (GGUF-only mode):
+```bash
+curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh
+```
+```powershell
+$env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex
+```
+
+Pin the Python version:
+```bash
+curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh
+```
+```powershell
+$env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex
+```
+
+Install to a custom location with `UNSLOTH_STUDIO_HOME`:
+```bash
+curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh
+```
+```powershell
+$env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex
+```
+
+Cap Studio's native CPU thread pools on high-core hosts: `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`.
 
 #### Uninstall
 The recommended way to fully remove Unsloth Studio is the matching uninstall script for your OS. It stops any running servers, removes the install dir, the launcher data dir, the desktop shortcut, and any platform-specific entries (macOS `.app` bundle + Launch Services on Mac; Start Menu, `HKCU\Software\Unsloth` registry key and user `PATH` entries on Windows):

From c6e86d5e77c79e7210c16acf28bf626c4f119b20 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 05:39:42 -0700
Subject: [PATCH 076/222] Update Install Scripts (#5968)

* Update Install Scripts

Add SPDX AGPL-3.0 headers to the installer scripts and let the piped web
installs take their common options from the environment.

- install.sh / install.ps1: read UNSLOTH_NO_TORCH (and UNSLOTH_PYTHON for
  install.sh) so a piped install needs no positional flags. Flags and the
  pipe forms still work; an explicit flag wins.
- Fix the UNSLOTH_STUDIO_HOME example so the variable sits after the pipe
  and reaches sh instead of curl.
- Add SPDX headers to install.sh, install.ps1, the uninstall scripts, and
  the MLX install scripts.
- Drop the internal test package names from the studio install comments.

* Mirror UNSLOTH_PYTHON env var to install.ps1

install.ps1 now reads UNSLOTH_PYTHON to pin the Python version, matching
install.sh, and lists all three env vars (UNSLOTH_NO_TORCH, UNSLOTH_PYTHON,
UNSLOTH_STUDIO_HOME) in the header examples. The requested version is
preferred during detection and used as the winget install target; behavior
is unchanged when the variable is unset.
---
 install.ps1                    | 35 +++++++++++++++++++++++-----------
 install.sh                     | 33 ++++++++++++++++++++------------
 scripts/install_gemma4_mlx.sh  |  2 ++
 scripts/install_qwen3_6_mlx.sh |  2 ++
 scripts/uninstall.ps1          |  3 +++
 scripts/uninstall.sh           |  3 +++
 studio/install_python_stack.py |  4 ++--
 studio/setup.ps1               |  2 +-
 8 files changed, 58 insertions(+), 26 deletions(-)

diff --git a/install.ps1 b/install.ps1
index 47c72bcdc1..eb18e0d426 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1,14 +1,20 @@
 # Unsloth Studio Installer for Windows PowerShell
-# Usage:  irm https://raw.githubusercontent.com/unslothai/unsloth/main/install.ps1 | iex
-# Local:  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass; .\install.ps1 --local
-# NoTorch: .\install.ps1 --no-torch  (skip PyTorch, GGUF-only mode)
-# Test:   .\install.ps1 --package roland-sloth
 #
-# Env vars (priority: UNSLOTH_STUDIO_HOME > STUDIO_HOME > USERPROFILE-redirect > default):
-#   UNSLOTH_STUDIO_HOME / STUDIO_HOME = path -> install under that path
-#   (DataDir nests inside; user PATH not modified persistently).
-# Default ($USERPROFILE\.unsloth\studio) is preserved when no env var is set.
-
+# Usage:  irm https://unsloth.ai/install.ps1 | iex
+#         Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass; .\install.ps1 --local
+#
+# irm | iex cannot forward arguments, so web installs take options as env vars set
+# before the pipe (flags still work via .\install.ps1):
+#   $env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex       # skip PyTorch (GGUF-only)
+#   $env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex    # pin Python version
+#   $env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex
+#   .\install.ps1 --no-torch                                                # equivalent flag
+# Or pass flags to a scriptblock: & ([scriptblock]::Create((irm https://unsloth.ai/install.ps1))) --no-torch
+#
+# Install dir priority: UNSLOTH_STUDIO_HOME > STUDIO_HOME (alias) > $USERPROFILE\.unsloth\studio
+#
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 function Install-UnslothStudio {
     $ErrorActionPreference = "Stop"
     $script:UnslothVerbose = ($env:UNSLOTH_VERBOSE -eq "1")
@@ -112,6 +118,10 @@ function Install-UnslothStudio {
             }
         }
     }
+
+    # Env-var equivalent for web installs; an explicit flag still wins.
+    if ($env:UNSLOTH_NO_TORCH -in @('1', 'true', 'yes', 'on')) { $SkipTorch = $true }
+
     # Propagate to child processes so they also respect verbose mode.
     # Process-scoped -- does not persist.
     if ($script:UnslothVerbose) {
@@ -132,7 +142,8 @@ function Install-UnslothStudio {
         return (Exit-InstallFailure "--package name contains invalid characters")
     }
 
-    $PythonVersion = "3.13"
+    # UNSLOTH_PYTHON pins the version (mirrors install.sh --python); default 3.13.
+    $PythonVersion = if ($env:UNSLOTH_PYTHON) { $env:UNSLOTH_PYTHON } else { "3.13" }
 
     # Resolve install destinations. Priority: UNSLOTH_STUDIO_HOME, then
     # STUDIO_HOME alias, then USERPROFILE-redirect, then default.
@@ -935,7 +946,9 @@ shell.Run cmd, 0, False
         # py.exe resolves to the standard CPython install, not conda.
         $pyLauncher = Get-Command py -CommandType Application -ErrorAction SilentlyContinue
         if ($pyLauncher -and $pyLauncher.Source -notmatch $script:CondaSkipPattern) {
-            foreach ($minor in @("3.13", "3.12", "3.11")) {
+            # Prefer the requested $PythonVersion, then newest-first fallback.
+            $minors = @($PythonVersion) + (@("3.13", "3.12", "3.11") | Where-Object { $_ -ne $PythonVersion })
+            foreach ($minor in $minors) {
                 try {
                     $out = & $pyLauncher.Source "-$minor" --version 2>&1 | Out-String
                     if ($out -match "Python (3\.1[1-3])\.\d+") {
diff --git a/install.sh b/install.sh
index 15755c589f..1d4d9067c1 100755
--- a/install.sh
+++ b/install.sh
@@ -1,17 +1,22 @@
 #!/bin/sh
-# Unsloth Studio Installer
-# Usage (curl):  curl -fsSL https://unsloth.ai/install.sh | sh
-# Usage (wget):  wget -qO- https://unsloth.ai/install.sh | sh
-# Usage (local): ./install.sh --local   (install from local repo instead of PyPI)
-# Usage (no-torch): ./install.sh --no-torch  (skip PyTorch, GGUF-only mode)
-# Usage (test):  ./install.sh --package roland-sloth  (install a different package name)
-# Usage (py):    ./install.sh --python 3.12  (override auto-detected Python version)
 #
-# Env vars (priority: UNSLOTH_STUDIO_HOME > STUDIO_HOME > HOME-redirect > default):
-#   UNSLOTH_STUDIO_HOME=/abs/path  -> install under that path
-#   STUDIO_HOME=/abs/path          -> alias, same effect (UNSLOTH_STUDIO_HOME wins)
-#   (DATA_DIR + unsloth CLI shim nest inside; no shell rc-file append.)
-# Default ($HOME/.unsloth/studio) is preserved when no env var is set.
+# Unsloth Studio Installer
+#
+# Usage:  curl -fsSL https://unsloth.ai/install.sh | sh
+#         wget  -qO- https://unsloth.ai/install.sh | sh
+#         ./install.sh --local   (install from a cloned repo instead of PyPI)
+#
+# Piped installs take options as env vars after the pipe (a bare `| sh --no-torch`
+# makes sh reject --no-torch as its own option). Flags still work via ./install.sh:
+#   curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh    # skip PyTorch (GGUF-only)
+#   curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh   # pin Python version
+#   curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh
+# Equivalent flags: ./install.sh --no-torch --python 3.12  (or pipe them: sh -s -- --no-torch)
+#
+# Install dir priority: UNSLOTH_STUDIO_HOME > STUDIO_HOME (alias) > $HOME/.unsloth/studio
+#
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 set -e
 
 # ── Output style (aligned with studio/setup.sh) ──
@@ -70,6 +75,10 @@ for arg in "$@"; do
     esac
 done
 
+# Env-var equivalents for piped installs; an explicit flag still wins.
+case "${UNSLOTH_NO_TORCH:-}" in 1|true|TRUE|yes|YES|on|ON) _NO_TORCH_FLAG=true ;; esac
+[ -z "$_USER_PYTHON" ] && [ -n "${UNSLOTH_PYTHON:-}" ] && _USER_PYTHON="$UNSLOTH_PYTHON"
+
 if [ "$_VERBOSE" = true ]; then
     export UNSLOTH_VERBOSE=1
 fi
diff --git a/scripts/install_gemma4_mlx.sh b/scripts/install_gemma4_mlx.sh
index e1f43b827c..e1ac4628fa 100755
--- a/scripts/install_gemma4_mlx.sh
+++ b/scripts/install_gemma4_mlx.sh
@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 set -euo pipefail
 
 # ============================================================
diff --git a/scripts/install_qwen3_6_mlx.sh b/scripts/install_qwen3_6_mlx.sh
index 38fe1bea05..ef0a3ee9e3 100644
--- a/scripts/install_qwen3_6_mlx.sh
+++ b/scripts/install_qwen3_6_mlx.sh
@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 set -euo pipefail
 
 # ============================================================
diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1
index 6174e7e494..25dd4af01b 100644
--- a/scripts/uninstall.ps1
+++ b/scripts/uninstall.ps1
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+#
 # Unsloth Studio uninstaller for Windows PowerShell.
 # Stops running servers and removes install dir, launcher data, CLI shim,
 # desktop and Start Menu shortcuts, the user PATH entry, and the PathBackup
diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh
index 94ca04b204..bb830151ae 100755
--- a/scripts/uninstall.sh
+++ b/scripts/uninstall.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env sh
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+#
 # Unsloth Studio uninstaller (macOS / Linux / WSL).
 # Stops running servers and removes install dir, launcher data,
 # CLI shim, desktop shortcut, .app bundle, and Launch Services entry.
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 5e785c934d..da202f7ce6 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -1406,7 +1406,7 @@ def install_python_stack() -> int:
     # When called from "unsloth studio update", it is NOT set so base packages
     # (unsloth + unsloth-zoo) are always reinstalled to pick up new versions.
     skip_base = os.environ.get("SKIP_STUDIO_BASE", "0") == "1"
-    # When --package is used, install a different package name (e.g. roland-sloth for testing)
+    # When --package is used, install a different package name (for testing)
     package_name = os.environ.get("STUDIO_PACKAGE_NAME", "unsloth")
     # When --local is used, overlay a local repo checkout after updating deps
     local_repo = os.environ.get("STUDIO_LOCAL_REPO", "")
@@ -1565,7 +1565,7 @@ def install_python_stack() -> int:
             constrain = False,
         )
     elif package_name != "unsloth":
-        # Custom package name (e.g. roland-sloth for testing) — install directly
+        # Custom package name (for testing), install directly
         _progress("base packages")
         pip_install(
             f"Installing {package_name}",
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 28ad512690..4d47010136 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -2016,7 +2016,7 @@ if ($env:SKIP_STUDIO_BASE -ne "1" -and $env:STUDIO_LOCAL_INSTALL -ne "1") {
 #     # the fresh .venv. Install it so run_install() can find its modules
 #     # and bundled requirements files.
 #     Write-Host "   Installing package into venv..." -ForegroundColor Cyan
-#     pip install unsloth-roland-test 2>&1 | Out-Null
+#     pip install unsloth 2>&1 | Out-Null
 # }
 
 if (-not $SkipPythonDeps) {

From 5777ccd03e5875234c7eb57f12dfeabeec5d1569 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 06:05:53 -0700
Subject: [PATCH 077/222] Logging cleanup (#5973)

* Logging cleanup

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/models/_utils.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index abb6969a7e..138a7b3cc0 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -782,6 +782,22 @@ transformers_trainer_logger.addFilter(HideLoggingMessage("No label_names"))
 transformers_trainer_logger.addFilter(HideLoggingMessage("The tokenizer has new"))
 del transformers_trainer_logger
 
+# Strip the "[transformers] " prefix transformers>=5 adds; keep the messages.
+try:
+    try:
+        import transformers.utils.logging as _tf_log
+
+        _tf_log._configure_library_root_logger()
+    except Exception:
+        pass
+    _tf_root = logging.getLogger("transformers")
+    _tf_fmt = logging.Formatter("%(message)s")
+    for _h in list(_tf_root.handlers):
+        _h.setFormatter(_tf_fmt)
+    del _tf_root, _tf_fmt
+except Exception:
+    pass
+
 # Using the default loss: `ForCausalLMLoss`.
 try:
     from transformers.modeling_utils import logger as transformers_modeling_utils_logger

From 37fd76a02fb72e7f7a236fc059b391c7e60a5712 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 3 Jun 2026 06:07:30 -0700
Subject: [PATCH 078/222] studio: redesign chat composer (#5891)

* studio: redesign chat composer

Reworks the new-chat composer and the compare composer into a single
rounded pill surface with a softer, lighter look.

- New welcome screen with a time-of-day sloth mascot and a lighter
  heading.
- One rounded composer surface with a soft drop shadow. The input grows
  inline as you type and collapses back to a single row when cleared.
- Tools and attachments live in a single plus menu; the thinking control
  is a compact pill with a reasoning-effort submenu.
- Inlined glyphs for the thinking, send, and dictate controls, kept in
  sync across the main and compare composers.
- Toast notifications match the composer surface: no border line, the
  same drop shadow, and the same dark surface color, with a ring-less
  close button.
- Dark mode: the side-menu shadow blends into the background, hovered
  menu rows read clearly, and their roundness matches light mode.
- Composer styles use dedicated unsloth- prefixed classes so compare
  mode keeps its own stacked layout.

* studio: sync compare-composer reasoning state and harden compare id

- Compare composer: keep "Preserve thinking" consistent with reasoning,
  matching the main composer. Enabling it now turns reasoning on, and
  disabling reasoning (the None option or the Thinking toggle) turns it
  off, so the invalid "preserve on while thinking off" state can't occur.
- Guard crypto.randomUUID in the Compare action. It is undefined in
  non-secure contexts (HTTP over a LAN IP) and would throw; fall back to
  a timestamped random id, matching createNavigationNonce.

* studio: reflect pre-selected Search/Code tools when no model is loaded

The Search and Code pills only lit up when the tool was usable right now
(a model loaded and capable), so a tool turned on from the + menu showed
as off in the pill while the menu showed it on. toolsEnabled is persisted
and takes effect once a capable model loads, so the pill should reflect it.
The pills now disable only when a loaded model lacks the capability, and
otherwise reflect the selected state. Applied to the main and compare
composers.

* Studio: link MCP Servers heading to its PR and fix composer pill cursors

Make the "MCP Servers" heading in the chat Configuration sheet link to the
MCP PR, keeping the chevron as the toggle. The label and chevron are rendered
as siblings so we don't nest an <a> inside a <button>.

Also add cursor-pointer to the composer pills and the thinking pill so hovering
a clickable pill shows the hand cursor instead of the default arrow.

* Studio: refine chat composer and add compare-mode parity

- Composer expands to two rows only once the input wraps to a second line,
  not on the first keystroke. Re-measure the autosize textarea on the width
  swap so expanding no longer leaves a stray blank row.
- Light-mode composer shadow now matches Gemini's soft elevation.
- Plus menu: replace Canvas with a More submenu (Canvas, Compare chat, RAG)
  and add Code above MCP. Active Web search/Code items use medium weight.
- Compare mode: the plus side menu, Search/Code toggles, and a Compare exit
  pill now match single chat, with the thinking control on the right.
- Projects menu entries link to their tracking PR (#5725).
- Add cursor-pointer to the composer plus button.

* studio: refine composer controls and chat search shadow

- Active tool pills show an x on hover to signal click-to-disable
- Plus button rotates into an x when the tools menu opens
- Composer surface uses a 32px radius and a taller single-line height
- Even, ChatGPT-style spacing between the plus and tool pills in both the single and compare composers
- Send and mic circles resized and spaced, with the arrow centered in the circle
- Chat search box gets a borderless, soft Gemini-style shadow

* studio: size the pill hover x to match the icon it replaces

Cross-engine checks (Chromium, Firefox, WebKit) flagged the active-pill
hover x as a fixed 14px, so it popped smaller than the 19px Code icon.
Fill the glyph slot instead so the x tracks whatever icon it covers.

* studio: do not persist Kimi search/thinking mutual-exclusion in single composer

The single-chat composer flipped the other control off when toggling
search or thinking on Kimi, but without { persist: false }, so it
overwrote the user's saved preference. Match shared-composer and keep
the side effect session-only.

* studio: pointer cursor on model selector trigger and menu items

Add scoped marker classes so the model picker trigger and every
clickable element in its menu (tabs, model rows, delete, eject) show a
pointer cursor; disabled items stay not-allowed.

* studio: pass baseUrl when resolving reasoning caps in single composer

The docked composer omitted baseUrl, so a custom Gemini OpenAI-compat
gateway still advertised the native thinking ladder the backend cannot
honor. Pass selectedExternalProvider.baseUrl like the compare composer
so the resolver hides it.

* studio: grey side-menu hover, green pill hover, thinking hover x

- Plus side-menu items hover grey in light mode, not the green accent
- Thinking pill hovers green like the Search and Code pills
- The plain Thinking toggle shows an x on hover when active, matching
  Search and Code; the effort dropdown trigger keeps its bulb

* studio: make the pill hover x a uniform size

The x filled the icon slot, so the wider Code chevron gave a bigger x
than Search and Compare. Pin it to a fixed 15px, centered, so every
pill's x matches.

* studio: broaden chat attachments, fix active hover color, gemini shadow

- Accept svg, source code and many text/config files as drag-and-drop
  or picked attachments, matched by extension since their MIME is
  unreliable; html keeps its own adapter
- Active (green) side-menu items keep their text and icon color on
  hover instead of switching to the accent color
- Composer surface uses Gemini's soft centered shadow 0 0 20px rgba(0,0,0,0.04)

* studio: keep the thinking pill full height when icon-only

The inactive thinking pill has no label, so its flex row collapsed to
the icon height and the hover box looked short. Reserve one text line
(min-height: 1lh + padding) so it matches the Search and Code pills.

* studio: refine composer menu, drop overlay and greetings

- Open the MCP servers dialog directly from the composer plus menu
- Redesign the drag-and-drop affordance Gemini style, drop the badge and border, make the whole chat page a drop target
- Swap in Hugeicons for the RAG, attachment chip and new project icons
- Add time-based randomized welcome greetings, each matched to a fitting sloth

* studio: rename artifacts toggle to Canvas and make it opt-in

- Label the toggle Canvas everywhere, matching the plus menu
- Stop greying out the Canvas menu item; it toggles like the other items
- Only show the Canvas pill in the composer row once it is turned on, since it is less central than Search and Code

* studio: wire Canvas and MCP composer toggles, even out the pill row

- Open the MCP servers dialog from the menu, or toggle MCP on/off once a server is enabled
- Force MCP off when no server is enabled, so the toggle stays honest
- Show Canvas and MCP as opt-in pills that appear in the order they were toggled on
- Expand the composer and light up the pill when Canvas or MCP is on, like Search and Code
- Keep Compare directly after Code in the compare composer
- Use the same Code icon on both composers and give every pill an even icon slot

* studio: tidy composer toggle row and fix MCP enable/disable lifecycle

- Enable MCP automatically after a server is configured via the toggle flow
- Force MCP off everywhere once the last enabled server is removed
- Collapse the pill labels to icons only when more than 4 pills show, keeping Compare labelled
- Order Compare first in compare mode, before Search and Code
- Use the same Code icon and an even 19px icon slot across both composers
- Match the compare composer surface padding and send button inset to normal chat

* studio: revert compare composer padding change that cramped the input

Matching the surface padding to normal chat clipped the textarea text and
left a white strip on top. Restore the compare composer's own padding, which
gives proper top spacing. The send button inset fix stays.

* studio: center welcome greeting and soften composer scrollbar

Center the sloth and title together over the composer instead of
shifting the row left, which left the greeting sitting off to the side.

Keep the composer textarea scroll thumb faint by default and only darken
it when the thumb is hovered or dragged, so a tall draft no longer shows
a heavy dark rail.

* studio: match composer plus-menu tool gating to the pills

The new plus-menu tool entries did not carry the gating the visible pills
already enforce, so the menu and pills could disagree about a loaded
model's capabilities.

- Web search and Code menu items now disable when a loaded model lacks
  the capability, while still allowing preselection with no model loaded.
- Enabling Web search from the menu on a Kimi model now flips thinking
  off as a session-only change, since Kimi forbids search and thinking
  together. This matches the Search pill.
- Added an Images menu item, shown only for image-generation models and
  disabled until a model loads, so a short prompt has an entry point.

Applied to both the single-chat and compare composers.

* studio: round the active-pill hover x and even out pill padding

The hover x sat bare and the trailing label was tighter to the pill edge
than the leading icon, so the pill looked lopsided.

- Give the hover x a soft circular background that fills the icon slot,
  matching the ChatGPT-style toggle and the icon it replaces.
- Add a little more trailing padding so the label and the leading icon
  have even breathing room, and keep icon-only compact pills symmetric.

* studio: nudge the thinking bulb icon up by 0.5px

Bump the thinking lightbulb from 15px to 15.5px in the single-chat and
compare composers so it sits a touch larger next to the other controls.

* studio: drop the hover x circle on icon-only pills

When pills collapse to icon-only, the circle around the hover x is too
cramped in the small chip, so show a bare x there and keep the circle
only on the full-width labelled pills.

* studio: space the compare send button like normal chat

In compare mode the Thinking control sat right against the send button.
Match the normal composer's control spacing (gap-1.5 plus a send margin)
so Thinking has the same breathing room before send. The send button
keeps its 14px inset, so its position is unchanged.

* studio: make collapsed pill hover a circle, not a wide pill

Icon-only pills were wider than tall, so their rounded-full hover
highlight read as a fat rounded rectangle. Make the compact button a
square and center the glyph so the hover (and the x it reveals) sits in
a clean circle.

* studio: fix compare pane drops and audio picker lifetime

- Skip the page-level drop handler when the composer is hidden, so files
  dropped on a compare pane are not swallowed by a hidden composer; the
  shared compare composer keeps handling drops through its own dropzone.
- Build the audio file input on document.body instead of inside the plus
  menu, so the menu closing on select no longer unmounts the input before
  the OS picker returns and drops the file.

* studio/chat: stop projects list from white-screening on older backends

The projects list API returned data.projects directly, so a backend that
omits the field handed back undefined. useChatProjects cached that value,
then the next mount read undefined.length and crashed the whole chat page.

Default the projects and threads list APIs to an empty array and keep the
hook null-safe so a bad response can never poison the cache.

* studio/chat: align MCP dropdown with the + menu and add a chevron

Reuse the + menu surface (unsloth-plus-menu) for the MCP dropdown: rounded
corners, narrower width, neutral grey hover, and enabled rows shown as green
text with a right-aligned check instead of the emerald underlay. Add a
chevron to the MCP pill so it reads as openable, matching the Thinking pill.

* studio/chat: make MCP an opt-in pill and fix its dropdown placement

- MCP is back in the + menu as a toggle. The pill now only shows in the
  composer when MCP is on, matching Canvas, instead of always sitting there.
- The dropdown follows the composer side like the + menu (opens down in the
  welcome composer, up when docked) rather than always opening upward.
- Drop the dropdown caret when pills collapse so the icon is not squished.
- Stop force-syncing mcpEnabledForChat to the server count; the + menu owns it.

* studio/chat: MCP expands the composer, drop sidebar Compare, tidy scrollbars

- Toggling MCP now expands the composer and shows the tool pills, the same as
  Canvas, instead of leaving the row collapsed.
- Remove the Compare item from the sidebar now that it lives in the + menu, and
  point the compare tour step at the side-by-side view instead of the old button.
- Both sidebars only show their scrollbar on hover, and run settings reserves
  the scrollbar gutter so the close button no longer shifts when it appears.

* studio/chat: tighten toggle gap, fix run-settings close button, collapsed Train

- Reduce the composer toggle gap by 2px (gap-1 to gap-0.5) in both composers.
- Move the run settings header out of the scroll area so the close button keeps
  its position whether or not the scrollbar shows, and sits flush with the
  topbar open button again instead of shifting left.
- Surface Train as an icon in the collapsed sidebar (it already has a labelled
  section when expanded).

* studio/chat: tighten Thinking pill X padding, create projects inline

- The Thinking pill used px-2.5, so the hover X sat further in than the left
  pills. Match their pl-2 so the X lines up.
- The + menu New project now opens a create dialog and jumps straight to the
  new project, instead of routing to the projects list. Shared by both
  composers via a small NewProjectDialog.

* studio/chat: soften account menu, hover scrollbars, show collapsed chevrons

- Account menu drops its border ring for the composer's soft shadow and opens
  centered over its trigger.
- Settings and search reuse the hover-only scrollbar via a shared
  hover-scrollbar class, matching the sidebars.
- Train and Recents keep their chevron visible while collapsed so it is clear
  they can be expanded.

* studio/chat: roomier, more rounded account menu

Widen the account menu, add more left and right padding on the rows, bump the
row height and text a touch, and round the corners more, closer to the GPT
account menu.

* studio/chat: trim account menu width and nudge it up 2px

Pull the account menu in slightly on the left and right (narrower box, a touch
less row padding) and lift it 2px higher above the trigger.

* studio/settings: drop outline ring, circular close hover, pointer cursors

- Remove the settings dialog outline ring, keeping just the soft shadow.
- The close button hover is now a circle instead of a rounded rectangle.
- Every clickable control in the settings dialog uses a pointer cursor.

* studio/chat: bump MCP pill icon to 14.5px

Nudge the MCP icon up 0.5px so it sits even with the other pill glyphs.

* studio/chat: bump MCP pill icon to 15px

Nudge the MCP icon up another 0.5px.

* studio/settings: add a Settings title above the tabs

Put a Settings heading at the top of the sidebar so the tabs sit below it,
matching the Claude settings layout. Hidden on mobile where the nav is a row.

* studio/settings: rounder tab hover, bigger title, less-round search dialog

* studio/sidebar: round nav row hover boxes 2px more (10px to 12px)

* studio: drop settings dark shadow + divider, add tab left padding, tune hover roundness

* studio/model-selector: roomier padding, borderless box, rounder hover rows; settings divider light-only

* studio/search: match chat box shadow (soft light, none dark)

* studio/sidebar: borderless chat context menus, rename submenu to Projects with folder-export icon

* studio/model-selector: match light corner radius in dark, drop dark shadow, more visible dark hover

* studio/sidebar: chat context menu matches + side menu styling; relabel submenu Move to project

* studio: borderless message export menu (no dark shadow), match dark corner radius to light on export menu and settings

* studio/sidebar: open chat options menu GPT-style (down-right) and widen so Move to project fits one line

* studio/chat: message export menu uses the chatbox shadow in light mode

* studio/sidebar: narrow chat options menu slightly (w-60 to w-56)

* studio: unify all download icons to Hugeicons download-01; round profile button hover 1px more

* studio/run-settings: bump header to 16px

* studio/sidebar: trim chat options menu width slightly (w-56 to 216px)

* studio/sidebar: trim chat options menu width to w-52

* studio/profile: camera-01 Hugeicons glyph and chatbox shadow on avatar button

* studio: match dark-mode corner radius to light globally (single --radius token)

* studio/recipes: borderless New Recipe menu with chatbox shadow in light, none in dark

* studio: borderless dropdowns globally, chatbox shadow in light, none in dark

* studio: extend borderless + chatbox/none shadow to select, combobox and popover overlays

* studio/mcp: nudge MCP dropdown radius to 20px so its wider box reads as round as the + menu

* studio: restore dark dropdown shadow to avoid same-color merge; greet name ~1/3 of lines; bigger sloth + more gap

* studio/train: active tab is a borderless pill (no underline), roomier padding, more tab gap and bottom spacing

* studio/chat: nudge welcome up ~5px (still vh-based) and trim sloth image to 44px

* studio/train: active tab pill is white with chatbox shadow in light, taller padding

* studio/chat: welcome offset to calc(30vh - 10px)

* studio/chat: welcome offset to 28vh (drop the -10px)

* studio/chat: tighten sloth-to-text gap by 1px (16px to 15px)

* studio/train: revert light active pill to grey fill, drop white bg + shadow

* studio: app-wide hand cursor on every clickable control (disabled excluded)

* studio/chat: welcome offset to 26vh

* studio/chat: welcome offset to 28vh

* studio/chat: harden project and thread list guards against non-array payloads

* studio/sidebar: give the profile row more height and breathing room

* studio/sidebar: trim the profile row top and bottom padding slightly

* studio/sidebar: reduce Train and Recents section label size slightly

* studio/sidebar: trim the profile row top and bottom padding a touch more

* studio/sidebar: enlarge the profile hover area top and bottom

* studio/sidebar: increase profile hover roundness by 1px

* studio/sidebar: trim the profile row top and bottom padding slightly

* studio/sidebar: trim the profile row top and bottom padding slightly

* studio/chat: cache composer line metrics so wrap detection runs once, not per keystroke

* studio/chat: restore the prior view when exiting compare opened from the + menu

* studio/tests: drive Compare from the composer + menu after it moved out of the sidebar

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* studio/tests: open Compare from the composer + menu in the extra UI suite too

* studio: fix chat dictation microphone access

* studio: snappier plus-to-x spin and steady composer expand gap

Speed up the composer plus icon morph from 480ms to 300ms.

Add row-gap on the expanded composer line so the space between the text
and the controls row stays the same whether the box expanded from
wrapped text or from a toggle being on. The gap sits on the line, not the
input, so the placeholder max-height clamp never crops it.

* studio: only show composer tool pills once a model is loaded

Persisted Search/Code/Canvas/MCP toggles were surfacing the composer pill row on a fresh page load before any model was selected, so an empty composer looked different from the clean just-ejected state. Gate the composerExpanded tool checks on modelLoaded so a model-less composer stays collapsed, while saved preferences still apply the moment a model loads.

* studio: hide RAG composer menu item temporarily

Hide the placeholder RAG entry from the composer plus menu in both single chat and compare until the feature is ready, and drop the now-unused DatabaseIcon import.

* studio: let composer tools pre-select before a model loads

Selecting Web search, Code, Canvas or MCP from the + menu with no model
loaded did nothing visible: the toggle turned on but the composer never
expanded, so the pill stayed hidden. Drop the model-loaded gate from the
expand check so an active tool always surfaces its pill.

Align MCP with the Search/Code pattern too: grey it out only when a loaded
model lacks tool support, so MCP stays toggleable and the pill stays
clickable before a model is loaded instead of looking disabled.

---------

Co-authored-by: Unsloth <michaelhan@Michaels-MacBook-Pro.local>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: wasimysaid <wasimysdev@gmail.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: Daniel Han <23090290+danielhanchen@users.noreply.github.com>
---
 studio/backend/main.py                        |    2 +-
 studio/backend/tests/test_middleware.py       |    5 +-
 .../frontend/src/components/app-sidebar.tsx   |   72 +-
 .../components/assistant-ui/attachment.tsx    |   10 +-
 .../components/assistant-ui/audio-player.tsx  |    6 +-
 .../src/components/assistant-ui/image.tsx     |    5 +-
 .../components/assistant-ui/markdown-text.tsx |    5 +-
 .../assistant-ui/model-selector.tsx           |    4 +-
 .../assistant-ui/model-selector/pickers.tsx   |   12 +-
 .../src/components/assistant-ui/thread.tsx    | 1171 +++++++++++++----
 .../assistant-ui/tool-ui-image-generation.tsx |    6 +-
 .../frontend/src/components/ui/combobox.tsx   |   48 +-
 .../src/components/ui/dropdown-menu.tsx       |   10 +-
 studio/frontend/src/components/ui/popover.tsx |    8 +-
 studio/frontend/src/components/ui/select.tsx  |    2 +-
 studio/frontend/src/components/ui/sonner.tsx  |    3 +-
 studio/frontend/src/components/ui/tabs.tsx    |   14 +-
 .../studio-web-speech-dictation-adapter.ts    |  230 ++++
 .../src/features/chat/api/chat-api.ts         |    8 +-
 .../chat/artifacts/artifact-surface.tsx       |    5 +-
 .../frontend/src/features/chat/chat-page.tsx  |   51 +-
 .../src/features/chat/chat-settings-sheet.tsx |   18 +-
 .../chat/components/chat-search-dialog.tsx    |    4 +-
 .../chat/components/new-project-dialog.tsx    |   97 ++
 .../features/chat/hooks/use-chat-projects.ts  |   12 +-
 .../chat/hooks/use-pill-activation-order.ts   |   30 +
 .../src/features/chat/mcp-composer-button.tsx |  107 +-
 .../src/features/chat/runtime-provider.tsx    |   22 +-
 .../src/features/chat/shared-composer.tsx     |  996 ++++++++------
 .../frontend/src/features/chat/tour/steps.tsx |   45 +-
 .../profile-personalization-panel.tsx         |    7 +-
 .../src/features/settings/settings-dialog.tsx |   19 +-
 .../src/features/settings/tabs/chat-tab.tsx   |    4 +-
 .../src/features/studio/studio-page.tsx       |    2 +-
 studio/frontend/src/index.css                 |  533 +++++++-
 studio/frontend/src/speech-recognition.d.ts   |    9 +-
 tests/studio/playwright_chat_ui.py            |   20 +-
 tests/studio/playwright_extra_ui.py           |   22 +-
 38 files changed, 2645 insertions(+), 979 deletions(-)
 create mode 100644 studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
 create mode 100644 studio/frontend/src/features/chat/components/new-project-dialog.tsx
 create mode 100644 studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts

diff --git a/studio/backend/main.py b/studio/backend/main.py
index d5016980ba..10fbbfddf0 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -515,7 +515,7 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         response.headers.setdefault("Referrer-Policy", "no-referrer")
         response.headers.setdefault(
             "Permissions-Policy",
-            "camera=(), microphone=(), geolocation=()",
+            "camera=(), microphone=(self), geolocation=()",
         )
         response.headers["server"] = "unsloth-studio"
         return response
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 85b82f1011..5e5b5a3c3b 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -260,7 +260,10 @@ class TestSecurityHeadersMiddleware:
         assert r.headers["x-frame-options"] == "DENY"
         assert r.headers["x-content-type-options"] == "nosniff"
         assert r.headers["referrer-policy"] == "no-referrer"
-        assert "camera=()" in r.headers["permissions-policy"]
+        permissions_policy = r.headers["permissions-policy"]
+        assert "camera=()" in permissions_policy
+        assert "microphone=(self)" in permissions_policy
+        assert "geolocation=()" in permissions_policy
         assert r.headers["server"] == "unsloth-studio"
 
     def test_internal_nonce_header_is_spliced_into_csp_and_stripped(self, main_module):
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 16292bd6e4..941c2e8a74 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -46,12 +46,12 @@ import { useAnimatedThemeToggle } from "@/components/ui/animated-theme-toggler";
 import { cn } from "@/lib/utils";
 import {
   ChefHatIcon,
-  ColumnInsertIcon,
   CursorInfo02Icon,
   Delete02Icon,
   DownloadSquare01Icon,
   Edit03Icon,
   FolderAddIcon,
+  FolderExportIcon,
   Folder01Icon,
   Globe02Icon,
   HelpCircleIcon,
@@ -192,6 +192,7 @@ function NavItem({
   onClick,
   children,
   dataTour,
+  className,
 }: {
   icon: typeof ZapIcon;
   label: string;
@@ -200,9 +201,10 @@ function NavItem({
   onClick: () => void;
   children?: ReactNode;
   dataTour?: string;
+  className?: string;
 }) {
   return (
-    <SidebarMenuItem>
+    <SidebarMenuItem className={className}>
       <div className="relative">
         <SidebarMenuButton
           tooltip={label}
@@ -210,7 +212,7 @@ function NavItem({
           onClick={onClick}
           isActive={active}
           data-tour={dataTour}
-          className="sidebar-nav-btn h-[33px] rounded-[10px] gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-[10px] group-data-[collapsible=icon]:mx-auto"
+          className="sidebar-nav-btn h-[33px] rounded-[11px] gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-[10px] group-data-[collapsible=icon]:mx-auto"
         >
           <HugeiconsIcon icon={icon} strokeWidth={1.75} className="size-icon! shrink-0 group-hover/menu-button:animate-icon-pop" />
           <span className="text-[14.5px] leading-[19px] tracking-nav">{label}</span>
@@ -550,7 +552,7 @@ export function AppSidebar() {
         ? "sidebar-row-action group-hover/project-chat-item:opacity-100 group-hover/project-chat-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
         : "sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto";
     const buttonClass = cn(
-      "sidebar-nav-btn h-[33px] cursor-pointer rounded-[10px] pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
+      "sidebar-nav-btn h-[33px] cursor-pointer rounded-[11px] pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
       variant === "project" ? "pl-[37px]" : "pl-2.5",
       variant === "project"
         ? "group-hover/project-chat-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/project-chat-item:pr-8"
@@ -599,9 +601,9 @@ export function AppSidebar() {
           </DropdownMenuTrigger>
           <DropdownMenuContent
             side="bottom"
-            align="end"
-            sideOffset={4}
-            className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
+            align="start"
+            sideOffset={6}
+            className="unsloth-plus-menu menu-flat-destructive w-52"
           >
             <DropdownMenuItem onSelect={() => openRenameChat(item)}>
               <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
@@ -609,13 +611,13 @@ export function AppSidebar() {
             </DropdownMenuItem>
             <DropdownMenuSub>
               <DropdownMenuSubTrigger>
-                <HugeiconsIcon icon={Folder01Icon} strokeWidth={1.75} className="size-icon" />
+                <HugeiconsIcon icon={FolderExportIcon} strokeWidth={1.75} className="size-icon" />
                 <span>Move to project</span>
               </DropdownMenuSubTrigger>
               <DropdownMenuSubContent
                 sideOffset={8}
                 alignOffset={-4}
-                className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-56 py-2 font-heading rounded-[14px] border-0"
+                className="unsloth-plus-menu w-52"
               >
                 <DropdownMenuItem
                   onSelect={() => {
@@ -754,25 +756,6 @@ export function AppSidebar() {
               disabled={chatDisabled}
               onClick={() => openNewChat(null)}
             />
-            <NavItem
-              icon={ColumnInsertIcon}
-              label={t("shell.navigation.compare")}
-              active={
-                !!search.compare &&
-                !chatItems.some((i) => i.id === search.compare)
-              }
-              disabled={chatDisabled}
-              dataTour="chat-compare"
-              onClick={() => {
-                if (chatDisabled) return;
-                setActiveThreadId(null);
-                navigate({
-                  to: "/chat",
-                  search: { compare: createNavigationNonce() },
-                });
-                closeMobileIfOpen();
-              }}
-            />
             <NavItem
               icon={Search01Icon}
               label={t("shell.navigation.search")}
@@ -813,6 +796,22 @@ export function AppSidebar() {
                   closeMobileIfOpen();
                 }}
               />
+              {/* Train has its own labelled section when expanded; surface it as
+                  a plain icon here only while the sidebar is collapsed. */}
+              <NavItem
+                icon={TestTubeOutlineIcon}
+                label={t("shell.navigation.train")}
+                active={
+                  pathname === "/studio" || pathname.startsWith("/studio/")
+                }
+                disabled={chatOnly}
+                onClick={() => {
+                  if (chatOnly) return;
+                  navigate({ to: "/studio" });
+                  closeMobileIfOpen();
+                }}
+                className="hidden group-data-[collapsible=icon]:block"
+              />
             </SidebarMenu>
           </SidebarGroupContent>
         </SidebarGroup>
@@ -822,7 +821,7 @@ export function AppSidebar() {
             <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
               <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
                 {t("shell.navigation.train")}
-                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
             <CollapsibleContent>
@@ -871,7 +870,7 @@ export function AppSidebar() {
               <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
                 <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
                   {t("shell.navigation.recents")}
-                  <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+                  <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
                 </CollapsibleTrigger>
               </SidebarGroupLabel>
               <CollapsibleContent>
@@ -893,7 +892,7 @@ export function AppSidebar() {
             <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
               <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
                 {t("shell.navigation.recents")}
-                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg]" />
+                <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
               </CollapsibleTrigger>
             </SidebarGroupLabel>
             <CollapsibleContent>
@@ -917,7 +916,7 @@ export function AppSidebar() {
                       >
                         <SidebarMenuButton
                           isActive={isActiveRun}
-                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-[10px] pl-2.5 pr-7 text-[14.5px] tracking-nav font-medium"
+                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-[11px] pl-2.5 pr-7 text-[14.5px] tracking-nav font-medium"
                           onClick={() => {
                             setSelectedHistoryRunId(run.id);
                             closeMobileIfOpen();
@@ -1007,14 +1006,14 @@ export function AppSidebar() {
                 <SidebarMenuButton
                   size="lg"
                   aria-label={t("shell.accountMenu", { name: displayTitle })}
-                  className="sidebar-nav-btn !h-[40px] gap-[8px] px-2 py-[5px] rounded-[10px]"
+                  className="sidebar-nav-btn !h-[44px] gap-[9px] px-2 py-[3px] rounded-[14px]"
                 >
                   <div className="shrink-0">
                     <UserAvatar
                       name={displayTitle}
                       imageUrl={avatarDataUrl}
                       size="sm"
-                      className="!size-[30px]"
+                      className="!size-[32px]"
                     />
                   </div>
                   <div className="flex flex-col gap-0.5 leading-tight group-data-[collapsible=icon]:hidden">
@@ -1026,8 +1025,9 @@ export function AppSidebar() {
               </DropdownMenuTrigger>
               <DropdownMenuContent
                 side="top"
-                align="start"
-                className="app-user-menu menu-soft-surface-up ring-0 w-[15rem] py-2.5 font-heading rounded-[14px] border-0"
+                align="center"
+                sideOffset={6}
+                className="app-user-menu menu-soft-surface-up ring-0 w-[16rem] px-1.5 py-2.5 font-heading rounded-[20px] border-0"
               >
                 <DropdownMenuGroup>
                   <DropdownMenuItem
diff --git a/studio/frontend/src/components/assistant-ui/attachment.tsx b/studio/frontend/src/components/assistant-ui/attachment.tsx
index d814490c1d..a96dd7a4e1 100644
--- a/studio/frontend/src/components/assistant-ui/attachment.tsx
+++ b/studio/frontend/src/components/assistant-ui/attachment.tsx
@@ -24,7 +24,9 @@ import {
   useAui,
   useAuiState,
 } from "@assistant-ui/react";
-import { FileText, PlusIcon, XIcon } from "lucide-react";
+import { File02Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { PlusIcon, XIcon } from "lucide-react";
 import {
   type FC,
   type PropsWithChildren,
@@ -134,7 +136,11 @@ const AttachmentThumb: FC = () => {
 
   return (
     <div className="flex h-full w-full items-center justify-center">
-      <FileText className="size-6 text-muted-foreground" />
+      <HugeiconsIcon
+        icon={File02Icon}
+        strokeWidth={2}
+        className="size-6 text-muted-foreground"
+      />
     </div>
   );
 };
diff --git a/studio/frontend/src/components/assistant-ui/audio-player.tsx b/studio/frontend/src/components/assistant-ui/audio-player.tsx
index 6b99de8374..8836eddff5 100644
--- a/studio/frontend/src/components/assistant-ui/audio-player.tsx
+++ b/studio/frontend/src/components/assistant-ui/audio-player.tsx
@@ -4,7 +4,9 @@
 "use client";
 
 import { Button } from "@/components/ui/button";
-import { DownloadIcon, PauseIcon, PlayIcon } from "lucide-react";
+import { PauseIcon, PlayIcon } from "lucide-react";
+import { Download01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import { type FC, useRef, useState } from "react";
 
 interface AudioPlayerProps {
@@ -110,7 +112,7 @@ export const AudioPlayer: FC<AudioPlayerProps> = ({ src }) => {
         onClick={handleDownload}
         title="Download audio"
       >
-        <DownloadIcon className="size-3.5" />
+        <HugeiconsIcon icon={Download01Icon} className="size-3.5" />
       </Button>
     </div>
   );
diff --git a/studio/frontend/src/components/assistant-ui/image.tsx b/studio/frontend/src/components/assistant-ui/image.tsx
index a2e3f30dc1..3cd7ecaaf5 100644
--- a/studio/frontend/src/components/assistant-ui/image.tsx
+++ b/studio/frontend/src/components/assistant-ui/image.tsx
@@ -15,13 +15,14 @@ import type {
 import { type VariantProps, cva } from "class-variance-authority";
 import {
   CopyIcon,
-  DownloadIcon,
   ImageIcon,
   ImageOffIcon,
   Loader2Icon,
   RefreshCwIcon,
   ShieldAlertIcon,
 } from "lucide-react";
+import { Download01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import {
   type ComponentProps,
   type PropsWithChildren,
@@ -427,7 +428,7 @@ function ImageActions({ part, onRegenerate, className }: ImageActionsProps) {
         aria-label="Download image"
         className="inline-flex size-7 items-center justify-center rounded hover:bg-muted"
       >
-        <DownloadIcon className="size-4" />
+        <HugeiconsIcon icon={Download01Icon} className="size-4" />
       </button>
       <button
         type="button"
diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index 8cb33d0ed2..107672d938 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -8,11 +8,10 @@ import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { preprocessLaTeX } from "@/lib/latex";
 import { openLink } from "@/lib/open-link";
 import { INTERNAL, useAuiState, useMessagePartText } from "@assistant-ui/react";
-import { Copy01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
+import { Copy01Icon, Download01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { createMathPlugin } from "@streamdown/math";
 import { mermaid } from "@streamdown/mermaid";
-import { DownloadIcon } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Block, type BlockProps, Streamdown } from "streamdown";
 import { createCodePlugin } from "./code-plugin";
@@ -279,7 +278,7 @@ function CodeBlockActions({
             downloadTextFile(getCodeFilename(language), source);
           }}
         >
-          <DownloadIcon className="size-icon" />
+          <HugeiconsIcon icon={Download01Icon} className="size-icon" />
         </button>
       </div>
     </div>
diff --git a/studio/frontend/src/components/assistant-ui/model-selector.tsx b/studio/frontend/src/components/assistant-ui/model-selector.tsx
index 0fcbefdabd..f8a3ce4e20 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector.tsx
@@ -146,7 +146,7 @@ function ModelSelectorTrigger({
         type="button"
         data-tour={dataTour}
         className={cn(
-          "flex min-w-0 items-center gap-2 transition-colors",
+          "unsloth-model-selector-trigger flex min-w-0 items-center gap-2 transition-colors",
           variant === "outline" &&
           "rounded-[10px] border border-border/60 hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
           variant === "ghost" && "rounded-[10px] hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
@@ -246,7 +246,7 @@ function ModelSelectorContent({
       align="start"
       data-tour={dataTour}
       className={cn(
-        "menu-soft-surface ring-0 w-[min(440px,calc(100vw-1rem))] max-w-[calc(100vw-1rem)] min-w-0 gap-0 p-2",
+        "unsloth-model-selector-menu menu-soft-surface ring-0 w-[min(440px,calc(100vw-1rem))] max-w-[calc(100vw-1rem)] min-w-0 gap-0 p-3",
         className,
       )}
     >
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
index ea40c260c5..2d715bf8de 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
@@ -38,11 +38,11 @@ import {
 import { cn, formatCompact } from "@/lib/utils";
 import type { VramFitStatus } from "@/lib/vram";
 import { checkVramFit, estimateLoadingVram } from "@/lib/vram";
-import { Add01Icon, Cancel01Icon, Folder02Icon, Search01Icon } from "@hugeicons/core-free-icons";
+import { Add01Icon, Cancel01Icon, Download01Icon, Folder02Icon, Search01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { FolderBrowser } from "./folder-browser";
 import { ModelDeleteAction } from "./model-delete-action";
-import { ChevronDownIcon, ChevronRightIcon, DownloadIcon, StarIcon } from "lucide-react";
+import { ChevronDownIcon, ChevronRightIcon, StarIcon } from "lucide-react";
 import {
   type ReactNode,
   useCallback,
@@ -145,8 +145,8 @@ function ModelRow({
       type="button"
       onClick={onClick}
       className={cn(
-        "flex w-full items-center gap-2 rounded-[6px] px-2.5 py-1.5 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#2e3035]",
-        selected && "bg-[#ececec] dark:bg-[#2e3035]",
+        "flex w-full items-center gap-2 rounded-[8px] px-2.5 py-1.5 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
+        selected && "bg-[#ececec] dark:bg-[#3a3d44]",
       )}
     >
       <span
@@ -385,7 +385,7 @@ function GgufVariantExpander({
                 handleVariantClick(v.quant, v.downloaded, v.size_bytes)
               }
               className={cn(
-                "flex min-w-0 flex-1 items-center justify-between gap-2 rounded-[6px] px-2.5 py-1 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#2e3035]",
+                "flex min-w-0 flex-1 items-center justify-between gap-2 rounded-[8px] px-2.5 py-1 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
               )}
             >
               <span className="min-w-0 flex-1 truncate font-mono text-xs">
@@ -925,7 +925,7 @@ export function HubModelPicker({
               (!chatOnly && cachedModels.length > 0)) ? (
             <>
               <ListLabel
-                icon={<DownloadIcon className="size-3" />}
+                icon={<HugeiconsIcon icon={Download01Icon} className="size-3" />}
                 collapsed={downloadedCollapsed}
                 onToggle={() => setDownloadedCollapsed((v) => !v)}
               >Downloaded</ListLabel>
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index b323996072..83057074ba 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -2,11 +2,9 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import {
-  ComposerAddAttachment,
   ComposerAttachments,
   UserMessageAttachments,
 } from "@/components/assistant-ui/attachment";
-import { CodeToggleIcon } from "@/components/assistant-ui/code-toggle-icon";
 import {
   GeneratedImageOverlayProvider,
   useGeneratedImageOverlay,
@@ -40,15 +38,23 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { sentAudioNames } from "@/features/chat/api/chat-adapter";
+import { useChatProjects } from "@/features/chat/hooks/use-chat-projects";
+import { NewProjectDialog } from "@/features/chat/components/new-project-dialog";
 import { parseExternalModelId } from "@/features/chat/external-providers";
 import { McpComposerButton } from "@/features/chat/mcp-composer-button";
 import { getExternalReasoningCapabilities } from "@/features/chat/provider-capabilities";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
 import { useExternalProvidersStore } from "@/features/chat/stores/external-providers-store";
 import { deleteThreadMessage } from "@/features/chat/utils/delete-thread-message";
+import { useUserProfileStore } from "@/features/profile/stores/user-profile-store";
 import { applyQwenThinkingParams } from "@/features/chat/utils/qwen-params";
 import { isTauri } from "@/lib/api-base";
 import { AUDIO_ACCEPT, MAX_AUDIO_SIZE, fileToBase64 } from "@/lib/audio-utils";
@@ -69,44 +75,58 @@ import {
   useAuiState,
 } from "@assistant-ui/react";
 import { flushResourcesSync } from "@assistant-ui/tap";
+import {
+  AttachmentIcon,
+  CodeIcon,
+  Copy01Icon,
+  Delete02Icon,
+  Download01Icon,
+  Edit03Icon,
+  Folder01Icon,
+  FolderAddIcon,
+  Image03Icon,
+  McpServerIcon,
+  PencilRulerIcon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useNavigate } from "@tanstack/react-router";
 import {
   ArrowDownIcon,
   ArrowUpIcon,
+  CheckIcon,
   ChevronLeftIcon,
   ChevronRightIcon,
-  DownloadIcon,
-  FileTextIcon,
+  Columns2Icon,
   GlobeIcon,
   HeadphonesIcon,
-  LightbulbIcon,
-  LightbulbOffIcon,
-  MicIcon,
   MoreHorizontalIcon,
+  PlusIcon,
   RefreshCwIcon,
   SquareIcon,
   TerminalIcon,
   XIcon,
 } from "lucide-react";
-import {
-  Copy01Icon,
-  Delete02Icon,
-  Edit03Icon,
-  Image03Icon,
-  Tick02Icon,
-} from "@hugeicons/core-free-icons";
-import { HugeiconsIcon } from "@hugeicons/react";
 import {
   type ChangeEvent,
   type ComponentProps,
   type CompositionEvent,
   type FC,
   type KeyboardEvent,
+  type DragEvent as ReactDragEvent,
+  type ReactNode,
+  createContext,
   useCallback,
+  useContext,
   useEffect,
   useRef,
   useState,
 } from "react";
 
+// True while a file is dragged anywhere over the chat page (not just the
+// composer), so the composer can show its "Drop files here" affordance.
+const PageDragContext = createContext(false);
+
 export const Thread: FC<{
   hideComposer?: boolean;
   hideWelcome?: boolean;
@@ -125,8 +145,55 @@ export const Thread: FC<{
   const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const threadId = targetThreadId ?? activeThreadId ?? null;
 
+  // Page-wide drag-and-drop: dropping a file anywhere on the chat page (not
+  // just on the composer) attaches it and shows the composer drop affordance.
+  // The composer's own dropzone still handles drops on the box itself; its
+  // handler calls preventDefault, so the page handler skips them (no double-add).
+  const aui = useAui();
+  const [pageDragging, setPageDragging] = useState(false);
+  const dragDepth = useRef(0);
+  const hasFiles = (e: ReactDragEvent) =>
+    Array.from(e.dataTransfer?.types ?? []).includes("Files");
+  const onDragEnter = (e: ReactDragEvent) => {
+    if (isTauri || !hasFiles(e)) return;
+    dragDepth.current += 1;
+    setPageDragging(true);
+  };
+  const onDragOver = (e: ReactDragEvent) => {
+    if (isTauri || !hasFiles(e)) return;
+    e.preventDefault();
+  };
+  const onDragLeave = (e: ReactDragEvent) => {
+    if (isTauri || !hasFiles(e)) return;
+    dragDepth.current = Math.max(0, dragDepth.current - 1);
+    if (dragDepth.current === 0) setPageDragging(false);
+  };
+  const onDrop = (e: ReactDragEvent) => {
+    if (isTauri) return;
+    dragDepth.current = 0;
+    setPageDragging(false);
+    // Compare panes hide this composer and use the shared composer's own
+    // dropzone, so don't capture drops into a hidden composer here.
+    if (hideComposer) return;
+    // Drops on the composer box are handled by its own dropzone, which calls
+    // preventDefault; skip those here so the file isn't added twice.
+    if (e.defaultPrevented) return;
+    const files = Array.from(e.dataTransfer.files);
+    if (files.length === 0) return;
+    e.preventDefault();
+    for (const file of files) {
+      aui
+        .composer()
+        .addAttachment(file)
+        .catch(() => {
+          // Adapter shows its own toast (e.g. "Load a model before adding images").
+        });
+    }
+  };
+
   return (
     <GeneratedImageOverlayProvider key={threadId ?? "default"} threadId={threadId}>
+      <PageDragContext.Provider value={pageDragging}>
       <ThreadPrimitive.Root
         className="aui-root aui-thread-root @container relative flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden"
         style={{
@@ -134,6 +201,10 @@ export const Thread: FC<{
           ["--thread-content-max-width" as string]:
             "calc(var(--thread-max-width) - 1.5rem)",
         }}
+        onDragEnter={onDragEnter}
+        onDragOver={onDragOver}
+        onDragLeave={onDragLeave}
+        onDrop={onDrop}
       >
         <IntentAwareScrollProvider value={autoScrollContext}>
           <ThreadPrimitive.Viewport
@@ -199,6 +270,7 @@ export const Thread: FC<{
           )}
         </IntentAwareScrollProvider>
       </ThreadPrimitive.Root>
+      </PageDragContext.Provider>
     </GeneratedImageOverlayProvider>
   );
 };
@@ -250,7 +322,7 @@ const GeneratedImageViewportOverlay: FC<{ hideComposer?: boolean }> = ({
                 }
                 aria-label="Download generated image"
               >
-                <DownloadIcon className="size-3.5" />
+                <HugeiconsIcon icon={Download01Icon} className="size-3.5" />
               </Button>
               <Button
                 type="button"
@@ -314,7 +386,11 @@ const ThreadComposerDock: FC<{
       />
       <div className="relative px-5 pb-2">
         <div className="pointer-events-auto mx-auto w-full max-w-(--thread-max-width)">
-          <ComposerAnimated disabled={disabled} threadId={threadId} />
+          <ComposerAnimated
+            disabled={disabled}
+            threadId={threadId}
+            menuSide="top"
+          />
         </div>
         <p className="composer-footer-note">
           LLMs can make mistakes. Double-check responses.
@@ -348,38 +424,81 @@ const ThreadScrollToBottom: FC = () => {
   );
 };
 
+const pickRandom = <T,>(arr: T[]): T =>
+  arr[Math.floor(Math.random() * arr.length)];
+
+// Each greeting carries the sloth picture that best fits it, so a given line
+// always shows the same mascot. Greeting varies by local time; name-bearing
+// lines drop the name when none is set.
+type Welcome = { text: string; sloth: string };
+const DEFAULT_WELCOME: Welcome = {
+  text: "What’s on your mind today?",
+  sloth: "sloth magnify final.png",
+};
+
+function buildWelcome(hour: number, name: string): Welcome {
+  const g = (text: string, sloth: string): Welcome => ({ text, sloth });
+  // Use the name on roughly a third of the lines per time of day: only the
+  // direct salutations where it reads most naturally. Everything else stays
+  // name-free so the greeting doesn't feel repetitive.
+  const base: Welcome[] = [
+    g(name ? `Good to see you, ${name}.` : "Good to see you.", "large sloth wave.png"),
+    g("Ready when you are.", "large sloth thumbs.png"),
+    DEFAULT_WELCOME,
+    g("How can I help?", "sloth sir large.png"),
+  ];
+  if (hour >= 4 && hour < 9) {
+    const morning = g(name ? `Good morning, ${name}` : "Good morning", "large sloth drink.png");
+    return pickRandom([...base, morning]);
+  }
+  if (hour >= 17 && hour < 23) {
+    const evening: Welcome[] = [
+      g(name ? `Good evening, ${name}` : "Good evening", "sloth shy large.png"),
+      g("What’s on for tonight?", "large sloth glasses.png"),
+    ];
+    // Lean toward an evening line, but a base greeting can still appear.
+    return pickRandom(Math.random() < 0.75 ? evening : base);
+  }
+  if (hour >= 23 || hour < 4) {
+    return pickRandom([
+      g("Night owl mode?", "large sloth glasses.png"),
+      g("Late night ideas?", "large sloth yay.png"),
+      g("Up late with an idea?", "large sloth heart.png"),
+      g(name ? `The night shift begins, ${name}` : "The night shift begins", "large sloth drink.png"),
+    ]);
+  }
+  return pickRandom(base);
+}
+
 const ThreadWelcome: FC<{
   hideComposer?: boolean;
   threadId?: string | null;
 }> = ({ hideComposer, threadId }) => {
-  const [currentEmoji, setCurrentEmoji] = useState("large sloth drink.png");
+  const displayName = useUserProfileStore((s) => s.displayName);
+  const [welcome, setWelcome] = useState<Welcome>(DEFAULT_WELCOME);
 
   useEffect(() => {
-    const hour = new Date().getHours();
-    if (hour >= 6 && hour < 12) setCurrentEmoji("large sloth drink.png");
-    else if (hour >= 12 && hour < 17)
-      setCurrentEmoji("sloth magnify final.png");
-    else if (hour >= 17 && hour < 21) setCurrentEmoji("sloth shy large.png");
-    else setCurrentEmoji("unsloth-gem.png");
-  }, []);
+    // First name only, for a natural greeting; blank falls back to no name.
+    const name = displayName.trim().split(/\s+/)[0] ?? "";
+    setWelcome(buildWelcome(new Date().getHours(), name));
+  }, [displayName]);
 
-  const currentEmojiSrc =
-    currentEmoji === "unsloth-gem.png"
-      ? `/${currentEmoji}`
-      : `/Sloth emojis/${currentEmoji}`;
+  const currentEmojiSrc = `/Sloth emojis/${welcome.sloth}`;
 
   return (
     <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col">
-      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-center pb-[48px]">
-        <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-6 px-4">
-          <div className="flex flex-col items-center gap-2 text-center">
-            <img src={currentEmojiSrc} alt="Sloth mascot" className="size-20" />
-            <h1 className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in font-heading font-semibold text-2xl tracking-[0em] duration-200">
-              Chat with your model
+      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[28vh]">
+        <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-9 px-4">
+          {/* Center the whole greeting (sloth + title) over the composer. */}
+          <div className="flex flex-row items-center justify-center gap-[15px]">
+            <img
+              src={currentEmojiSrc}
+              alt="Sloth mascot"
+              className="size-[44px] -translate-y-[2px]"
+            />
+            <h1 className="aui-thread-welcome-message-inner unsloth-welcome-title fade-in slide-in-from-bottom-1 animate-in text-3xl tracking-[-0.02em] duration-200">
+              {welcome.text}
             </h1>
-            <p className="aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 -mt-1 animate-in font-heading font-normal text-muted-foreground text-sm delay-75 duration-200">
-              Run GGUFs, safetensors, vision and audio models
-            </p>
           </div>
           {!hideComposer && <ComposerAnimated threadId={threadId} />}
         </div>
@@ -403,15 +522,12 @@ const ComposerAnimated: FC<{
   disabled?: boolean;
   placeholder?: string;
   threadId?: string | null;
-}> = ({ disabled, placeholder, threadId }) => {
+  menuSide?: "top" | "bottom";
+}> = ({ disabled, threadId, menuSide }) => {
   return (
-    <div className="relative mx-auto min-w-0 w-full max-w-(--thread-max-width)">
+    <div className="relative mx-auto min-w-0 w-full max-w-[46rem]">
       <div className="relative z-10 w-full">
-        <Composer
-          disabled={disabled}
-          placeholder={placeholder}
-          threadId={threadId}
-        />
+        <Composer disabled={disabled} threadId={threadId} menuSide={menuSide} />
       </div>
     </div>
   );
@@ -445,12 +561,30 @@ const Composer: FC<{
   disabled?: boolean;
   placeholder?: string;
   threadId?: string | null;
-}> = ({ disabled, placeholder = "Send a message...", threadId }) => {
+  menuSide?: "top" | "bottom";
+}> = ({ disabled, threadId, menuSide }) => {
   const aui = useAui();
+  const pageDragging = useContext(PageDragContext);
   const { overlay, closeOverlay } = useGeneratedImageOverlay();
   const setImageToolsEnabled = useChatRuntimeStore(
     (s) => s.setImageToolsEnabled,
   );
+  const toolsEnabled = useChatRuntimeStore((s) => s.toolsEnabled);
+  const codeToolsEnabled = useChatRuntimeStore((s) => s.codeToolsEnabled);
+  const imageToolsEnabled = useChatRuntimeStore((s) => s.imageToolsEnabled);
+  const supportsBuiltinImageGeneration = useChatRuntimeStore(
+    (s) => s.supportsBuiltinImageGeneration,
+  );
+  const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
+  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  // With more than 4 pills showing, collapse them to icons only to cut clutter.
+  // Search and Code always show; Images, Canvas and MCP are conditional.
+  const pillsCompact =
+    2 +
+      (supportsBuiltinImageGeneration ? 1 : 0) +
+      (artifactsEnabled ? 1 : 0) +
+      (mcpEnabledForChat ? 1 : 0) >
+    4;
   const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const setPendingImageEditReference = useChatRuntimeStore(
     (s) => s.setPendingImageEditReference,
@@ -458,6 +592,37 @@ const Composer: FC<{
   const { inputProps, isComposing, isComposingRef } =
     useImeComposerInputHandlers();
   const composerText = useAuiState(({ composer }) => composer.text);
+  // Expand only once the input wraps to a second line, not on first keystroke.
+  // Latch until cleared so it can't flip-flop at the wrap boundary.
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  // Cache line metrics so getComputedStyle runs once, not on every keystroke.
+  const lineMetricsRef = useRef<{ lineHeight: number; padding: number } | null>(
+    null,
+  );
+  const [isMultiline, setIsMultiline] = useState(false);
+  useEffect(() => {
+    if (composerText.length === 0) {
+      setIsMultiline(false);
+      lineMetricsRef.current = null;
+      return;
+    }
+    // Latched on: stays until the text clears, so skip re-measuring.
+    if (isMultiline) return;
+    const el = inputRef.current;
+    if (!el) {
+      return;
+    }
+    if (!lineMetricsRef.current) {
+      const cs = getComputedStyle(el);
+      const lineHeight = Number.parseFloat(cs.lineHeight) || 24;
+      const padTop = Number.parseFloat(cs.paddingTop) || 0;
+      const padBottom = Number.parseFloat(cs.paddingBottom) || 0;
+      lineMetricsRef.current = { lineHeight, padding: padTop + padBottom };
+    }
+    const { lineHeight, padding } = lineMetricsRef.current;
+    const contentHeight = el.scrollHeight - padding;
+    if (contentHeight > lineHeight * 1.5) setIsMultiline(true);
+  }, [composerText, isMultiline]);
   const hasAttachments = useAuiState(
     ({ composer }) => composer.attachments.length > 0,
   );
@@ -472,6 +637,58 @@ const Composer: FC<{
   const referenceThreadId = threadId ?? activeThreadId ?? null;
   const hasSendableContent =
     composerText.trim().length > 0 || hasAttachments || hasPendingAudio;
+  // Two-row layout shows once the input wraps or a tool is on. Tools pre-select
+  // before a model loads, so an active toggle expands the composer either way.
+  const composerExpanded =
+    isMultiline ||
+    hasAttachments ||
+    hasPendingAudio ||
+    toolsEnabled ||
+    codeToolsEnabled ||
+    imageToolsEnabled ||
+    artifactsEnabled ||
+    mcpEnabledForChat;
+  // react-textarea-autosize re-measures only on value change or window resize,
+  // not on the width swap from expanding, so it keeps the taller height and
+  // leaves a stray blank row. Nudge a resize whenever the input width changes.
+  useEffect(() => {
+    const el = inputRef.current;
+    if (!el || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    let lastWidth = -1;
+    const pending: Array<ReturnType<typeof setTimeout>> = [];
+    const observer = new ResizeObserver((entries) => {
+      const width = Math.round(entries[0]?.contentRect.width ?? 0);
+      // Width changes only; reacting to autosize's height change would loop.
+      if (width === lastWidth) {
+        return;
+      }
+      lastWidth = width;
+      // Re-measure after layout settles. An immediate dispatch races autosize's
+      // own measurement (stale pre-expand width); 0ms + 64ms wins it, no flash.
+      while (pending.length) {
+        clearTimeout(pending.pop());
+      }
+      for (const delay of [0, 64]) {
+        pending.push(
+          setTimeout(() => {
+            window.dispatchEvent(new Event("resize"));
+          }, delay),
+        );
+      }
+    });
+    observer.observe(el);
+    return () => {
+      while (pending.length) {
+        clearTimeout(pending.pop());
+      }
+      observer.disconnect();
+    };
+  }, []);
+  // Docked composer opens upward; the centered welcome composer opens downward
+  // by default and only flips up via collision detection when it would not fit.
+  const effectiveMenuSide = menuSide ?? "bottom";
   const shouldBlockSend = useCallback(
     () =>
       !hasSendableContent || isComposingRef.current || hasPendingAttachments,
@@ -545,28 +762,54 @@ const Composer: FC<{
       <ComposerAttachments />
       <PendingAudioChip />
       <ToolStatusDisplay />
-      <ComposerPrimitive.Input
-        placeholder={overlay ? "Type your edits for your image" : placeholder}
-        className="aui-composer-input composer-input"
-        minRows={1}
-        maxRows={12}
-        autoFocus={!disabled}
-        disabled={disabled}
-        aria-label={overlay ? "Image edit instructions" : "Message input"}
-        // dir="auto": browser picks LTR/RTL from the first strong char;
-        // no effect on Latin / CJK / Devanagari.
-        dir="auto"
-        {...inputProps}
-      />
-      <ComposerAction
-        disabled={
-          disabled ||
-          !hasSendableContent ||
-          isComposing ||
-          hasPendingAttachments
-        }
-        shouldBlockSend={shouldBlockSend}
-      />
+      <div
+        className="unsloth-composer-line"
+        data-expanded={composerExpanded ? "true" : "false"}
+      >
+        <div
+          className="unsloth-composer-left"
+          data-pill-compact={pillsCompact ? "true" : undefined}
+        >
+          <ComposerToolsMenu side={effectiveMenuSide} />
+          {composerExpanded ? (
+            <>
+              <WebSearchToggle />
+              <CodeToolsToggle />
+              <ImagesToggle />
+              {artifactsEnabled ? <ArtifactsToggle /> : null}
+              {mcpEnabledForChat ? (
+                <McpComposerButton side={effectiveMenuSide} />
+              ) : null}
+            </>
+          ) : null}
+        </div>
+        <ComposerPrimitive.Input
+          placeholder={
+            overlay ? "Type your edits for your image" : "Ask anything"
+          }
+          ref={inputRef}
+          className="aui-composer-input unsloth-composer-input"
+          minRows={1}
+          maxRows={12}
+          autoFocus={!disabled}
+          disabled={disabled}
+          aria-label={overlay ? "Image edit instructions" : "Message input"}
+          // dir="auto": browser picks LTR/RTL from the first strong char;
+          // no effect on Latin / CJK / Devanagari.
+          dir="auto"
+          {...inputProps}
+        />
+        <ComposerRightControls
+          disabled={
+            disabled ||
+            !hasSendableContent ||
+            isComposing ||
+            hasPendingAttachments
+          }
+          shouldBlockSend={shouldBlockSend}
+          menuSide={effectiveMenuSide}
+        />
+      </div>
     </>
   );
 
@@ -579,12 +822,30 @@ const Composer: FC<{
       {isTauri ? (
         // Phase 1 native model drops own Tauri local-path drops. Restore browser
         // attachment drops in Tauri when Phase 1d adds attachment-token bridging.
-        <div className="aui-composer-attachment-dropzone chat-composer-surface">
+        <div className="aui-composer-attachment-dropzone unsloth-composer-surface">
           {composerContent}
         </div>
       ) : (
-        <ComposerPrimitive.AttachmentDropzone className="aui-composer-attachment-dropzone chat-composer-surface data-[dragging=true]:border-ring data-[dragging=true]:bg-accent/50">
+        <ComposerPrimitive.AttachmentDropzone className="group/dropzone aui-composer-attachment-dropzone unsloth-composer-surface relative">
           {composerContent}
+          {/* Gemini-style drop affordance: shown only while a file is dragged
+              over the composer. Absolutely positioned + pointer-events-none so
+              the dashed outline adds no layout shift and the drop still lands. */}
+          <div
+            className={cn(
+              "aui-composer-drop-overlay pointer-events-none absolute inset-0 z-20 flex flex-col items-center justify-center gap-1 overflow-hidden rounded-[32px] bg-background/90 opacity-0 backdrop-blur-sm transition-opacity duration-150 group-data-[dragging=true]/dropzone:opacity-100 dark:bg-card/90",
+              pageDragging && "opacity-100",
+            )}
+          >
+            <HugeiconsIcon
+              icon={AttachmentIcon}
+              strokeWidth={2}
+              className="size-6 text-primary"
+            />
+            <span className="text-sm font-medium text-primary">
+              Drop files here
+            </span>
+          </div>
         </ComposerPrimitive.AttachmentDropzone>
       )}
     </ComposerPrimitive.Root>
@@ -715,8 +976,8 @@ function useImeComposerInputHandlers() {
   };
 }
 
-const ComposerAudioUpload: FC = () => {
-  const audioInputRef = useRef<HTMLInputElement>(null);
+// Audio upload row, only for audio-input models.
+const ComposerAudioMenuItem: FC = () => {
   const setPendingAudio = useChatRuntimeStore((s) => s.setPendingAudio);
   const activeModel = useChatRuntimeStore((s) => {
     const checkpoint = s.params.checkpoint;
@@ -738,41 +999,91 @@ const ComposerAudioUpload: FC = () => {
     [setPendingAudio],
   );
 
+  // Build the input on document.body, not in the menu: selecting the item
+  // closes the dropdown, which would unmount a menu-rendered input before the
+  // OS picker returns and drop the file.
+  const pickAudio = useCallback(() => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = AUDIO_ACCEPT;
+    input.hidden = true;
+    document.body.appendChild(input);
+    input.onchange = () => {
+      const file = input.files?.[0];
+      if (file) handleAudioFile(file);
+      document.body.removeChild(input);
+    };
+    input.oncancel = () => {
+      if (!input.files || input.files.length === 0) {
+        document.body.removeChild(input);
+      }
+    };
+    input.click();
+  }, [handleAudioFile]);
+
   if (!activeModel?.hasAudioInput) {
     return null;
   }
 
   return (
-    <>
-      <input
-        ref={audioInputRef}
-        type="file"
-        accept={AUDIO_ACCEPT}
-        className="hidden"
-        onChange={(e) => {
-          const file = e.target.files?.[0];
-          if (file) {
-            handleAudioFile(file);
-          }
-          e.target.value = "";
-        }}
-      />
-      <TooltipIconButton
-        tooltip="Upload audio"
-        side="bottom"
-        variant="ghost"
-        size="icon"
-        className="size-8.5 rounded-full p-1 text-muted-foreground hover:bg-muted-foreground/15"
-        onClick={() => audioInputRef.current?.click()}
-        aria-label="Upload audio"
-      >
-        <HeadphonesIcon className="size-4.5 stroke-[1.5px]" />
-      </TooltipIconButton>
-    </>
+    <DropdownMenuItem onSelect={() => pickAudio()}>
+      <HeadphonesIcon />
+      Upload audio
+    </DropdownMenuItem>
   );
 };
 
-const ReasoningToggle: FC = () => {
+// Phosphor microphone. Inlined to avoid a new icon dependency.
+const MicIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 256 256"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M128,176a48.05,48.05,0,0,0,48-48V64a48,48,0,0,0-96,0v64A48.05,48.05,0,0,0,128,176ZM96,64a32,32,0,0,1,64,0v64a32,32,0,0,1-64,0Zm40,143.6V232a8,8,0,0,1-16,0V207.6A80.11,80.11,0,0,1,48,128a8,8,0,0,1,16,0,64,64,0,0,0,128,0,8,8,0,0,1,16,0A80.11,80.11,0,0,1,136,207.6Z" />
+  </svg>
+);
+
+// HugeIcons arrow-down-01 (stroke-standard): straight-line chevron.
+const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={1.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M5.99977 9.00005L11.9998 15L17.9998 9" />
+  </svg>
+);
+
+// svgrepo.com lightbulb (filled, with base).
+const BulbIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="-10.24 -10.24 1044.48 1044.48"
+    fill="currentColor"
+    stroke="currentColor"
+    strokeWidth={16.384}
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M511.984 0c-198.032 0-353.12 161.104-353.12 359.136 0 149.2 73.28 220.256 131.185 272.128 37.28 33.424 62.368 53.552 62.368 78.352v54.255c0 1.392.193 2.752.368 4.128h-.72v92.624c.016 97.712 63.2 163.376 161.072 163.376 94.464 0 158.944-65.664 158.944-163.376V768h-.928c.176-1.376.416-2.736.416-4.128v-54.255c0-37.76 28.032-60.592 70.528-97.696 57.504-50.208 123.023-112.688 123.023-252.784C865.136 161.104 710.016 0 511.983 0zm-1.215 960c-59.904 0-94.689-37.152-94.689-99.376l-.463-42.672C438.64 825.824 470 832 512 832c41.424 0 72.848-6.624 96.08-14.768v43.392c0 63.152-35.247 99.376-97.312 99.376zm189.248-396.288c-43.472 37.968-92.433 77.216-92.433 145.904v40.432c-15.183 8.48-43.183 18.56-96.127 18.56-55.569 0-81.92-9.856-95.024-17.473V709.6c0-54.608-42.688-89.297-83.68-126.017-54.32-48.672-109.873-103.84-109.873-224.464-.015-162.72 126.385-295.12 289.104-295.12 162.752 0 289.152 132.4 289.152 295.137 0 111.024-48.463 158.576-101.12 204.576z" />
+  </svg>
+);
+
+// Same bulb in every state; greyed by the pill's muted color when off.
+const ThinkIcon: FC = () => <BulbIcon className="size-[15.5px]" />;
+
+const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
+  side = "bottom",
+}) => {
   const modelLoaded = useChatRuntimeStore(
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
@@ -806,6 +1117,11 @@ const ReasoningToggle: FC = () => {
   const isKimiExternal = selectedExternalProvider?.providerType === "kimi";
   const toolsEnabled = useChatRuntimeStore((s) => s.toolsEnabled);
   const setToolsEnabled = useChatRuntimeStore((s) => s.setToolsEnabled);
+  const supportsPreserveThinking = useChatRuntimeStore(
+    (s) => s.supportsPreserveThinking,
+  );
+  const preserveThinking = useChatRuntimeStore((s) => s.preserveThinking);
+  const setPreserveThinking = useChatRuntimeStore((s) => s.setPreserveThinking);
   const effectiveExternalModelId =
     selectedExternalProvider?.providerType === "openrouter" &&
     externalSelection?.modelId === "openrouter/free" &&
@@ -820,6 +1136,7 @@ const ReasoningToggle: FC = () => {
           {
             isReasoningProvider:
               selectedExternalProvider?.isReasoningModel === true,
+            // Lets the resolver detect custom Gemini OAI-compat gateways.
             baseUrl: selectedExternalProvider?.baseUrl ?? null,
           },
         )
@@ -855,71 +1172,143 @@ const ReasoningToggle: FC = () => {
   };
   const effortLabel = formatEffortLabel(reasoningEffort);
 
-  if (effectiveReasoningStyle === "reasoning_effort") {
+  // Only rendered for models that can reason.
+  if (!effectiveSupportsReasoning) {
+    return null;
+  }
+
+  const isEffort = effectiveReasoningStyle === "reasoning_effort";
+  // Dropdown when there are effort levels or preserve-thinking; else a toggle.
+  const useDropdown = isEffort || supportsPreserveThinking;
+  const activeLook = isEffort
+    ? reasoningLockedOn || (effectiveReasoningVisualEnabled && !disabled)
+    : reasoningLockedOn || (effectiveReasoningEnabled && !disabled);
+
+  if (useDropdown) {
     return (
       <DropdownMenu>
         <DropdownMenuTrigger asChild={true}>
           <button
             type="button"
             disabled={disabled}
-            className={cn(
-              "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-              disabled
-                ? "cursor-not-allowed opacity-40"
-                : effectiveReasoningVisualEnabled
-                  ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                  : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-            )}
+            className="unsloth-thinking-pill"
+            data-active={activeLook ? "true" : "false"}
             aria-label={thinkEffortAriaLabel({
               modelLoaded,
               reasoningDisabled: disabled,
               reasoningEffort,
             })}
           >
-            {effectiveReasoningVisualEnabled ? (
-              <LightbulbIcon className="size-3.5" />
-            ) : (
-              <LightbulbOffIcon className="size-3.5" />
-            )}
-            <span>
-              Think: {effectiveReasoningVisualEnabled ? effortLabel : "None"}
-            </span>
+            <ThinkIcon />
+            {activeLook ? (
+              <span>{isEffort ? `Thinking · ${effortLabel}` : "Thinking"}</span>
+            ) : null}
+            <ArrowDownStandardIcon className="size-[15px]" />
           </button>
         </DropdownMenuTrigger>
-        <DropdownMenuContent align="end">
-          {effectiveSupportsReasoningOff && (
-            <DropdownMenuItem
-              onSelect={() => {
-                setReasoningEnabled(false);
-                applyQwenThinkingParams(false);
-              }}
-            >
-              None
-              {!effectiveReasoningVisualEnabled ? " \u2713" : ""}
-            </DropdownMenuItem>
-          )}
-          {effectiveReasoningEffortLevels
-            .filter((level) => level !== "none")
-            .map((level) => (
+        <DropdownMenuContent
+          side={side}
+          align="end"
+          avoidCollisions={true}
+          className="unsloth-plus-menu unsloth-thinking-menu min-w-0 w-[160px]"
+        >
+          {isEffort ? (
+            <>
+              {effectiveSupportsReasoningOff && (
+                <DropdownMenuItem
+                  onSelect={() => {
+                    setReasoningEnabled(false);
+                    applyQwenThinkingParams(false);
+                    // Preserve thinking needs thinking on, so turn it off too.
+                    setPreserveThinking(false);
+                  }}
+                >
+                  <CheckIcon
+                    className={cn(
+                      "unsloth-tick size-4",
+                      effectiveReasoningVisualEnabled && "opacity-0",
+                    )}
+                  />
+                  None
+                </DropdownMenuItem>
+              )}
+              {effectiveReasoningEffortLevels
+                .filter((level) => level !== "none")
+                .map((level) => (
+                  <DropdownMenuItem
+                    key={level}
+                    onSelect={() => {
+                      setReasoningEffort(level);
+                      setReasoningEnabled(true);
+                      applyQwenThinkingParams(true);
+                      // Kimi's $web_search builtin forbids thinking, so
+                      // enabling thinking flips the Search pill off.
+                      if (isKimiExternal && toolsEnabled) {
+                        setToolsEnabled(false, { persist: false });
+                      }
+                    }}
+                  >
+                    <CheckIcon
+                      className={cn(
+                        "unsloth-tick size-4",
+                        !(
+                          effectiveReasoningVisualEnabled &&
+                          reasoningEffort === level
+                        ) && "opacity-0",
+                      )}
+                    />
+                    {formatEffortLabel(level)}
+                  </DropdownMenuItem>
+                ))}
+            </>
+          ) : (
+            effectiveSupportsReasoningOff &&
+            !reasoningLockedOn && (
               <DropdownMenuItem
-                key={level}
                 onSelect={() => {
-                  setReasoningEffort(level);
-                  setReasoningEnabled(true);
-                  applyQwenThinkingParams(true);
-                  // Kimi's $web_search builtin forbids thinking, so
-                  // enabling thinking flips the Search pill off.
-                  if (isKimiExternal && toolsEnabled) {
-                    setToolsEnabled(false);
+                  const next = !reasoningEnabled;
+                  setReasoningEnabled(next);
+                  applyQwenThinkingParams(next);
+                  // Preserve thinking cannot run without thinking.
+                  if (!next) setPreserveThinking(false);
+                  if (isKimiExternal && next && toolsEnabled) {
+                    setToolsEnabled(false, { persist: false });
                   }
                 }}
               >
-                {formatEffortLabel(level)}
-                {effectiveReasoningVisualEnabled && reasoningEffort === level
-                  ? " \u2713"
-                  : ""}
+                <CheckIcon
+                  className={cn(
+                    "unsloth-tick size-4",
+                    !effectiveReasoningEnabled && "opacity-0",
+                  )}
+                />
+                Thinking
               </DropdownMenuItem>
-            ))}
+            )
+          )}
+          {supportsPreserveThinking && (
+            <DropdownMenuItem
+              disabled={disabled}
+              onSelect={(e) => {
+                e.preventDefault();
+                const next = !preserveThinking;
+                setPreserveThinking(next);
+                // Preserve thinking requires thinking on.
+                if (next) {
+                  setReasoningEnabled(true);
+                  applyQwenThinkingParams(true);
+                }
+              }}
+            >
+              <CheckIcon
+                className={cn(
+                  "unsloth-tick size-4",
+                  !preserveThinking && "opacity-0",
+                )}
+              />
+              Preserve thinking
+            </DropdownMenuItem>
+          )}
         </DropdownMenuContent>
       </DropdownMenu>
     );
@@ -940,18 +1329,13 @@ const ReasoningToggle: FC = () => {
         const next = !reasoningEnabled;
         setReasoningEnabled(next);
         applyQwenThinkingParams(next);
-        // Mutual exclusion with the Search pill on Kimi — see the
-        // dropdown branch above and shared-composer for the same rule.
+        // Mutually exclusive with Search on Kimi (see dropdown branch).
         if (isKimiExternal && next && toolsEnabled) {
-          setToolsEnabled(false);
+          setToolsEnabled(false, { persist: false });
         }
       }}
-      className="composer-pill-btn"
-      data-active={
-        reasoningLockedOn || (effectiveReasoningEnabled && !disabled)
-          ? "true"
-          : "false"
-      }
+      className="unsloth-thinking-pill"
+      data-active={activeLook ? "true" : "false"}
       aria-label={thinkToggleAriaLabel({
         reasoningLockedOn,
         modelLoaded,
@@ -959,53 +1343,21 @@ const ReasoningToggle: FC = () => {
         effectiveReasoningEnabled,
       })}
     >
-      {reasoningLockedOn || (effectiveReasoningEnabled && !disabled) ? (
-        <LightbulbIcon className="size-3.5" />
-      ) : (
-        <LightbulbOffIcon className="size-3.5" />
-      )}
-      <span>Think</span>
+      <PillGlyph>
+        <ThinkIcon />
+      </PillGlyph>
+      {activeLook ? <span>Thinking</span> : null}
     </button>
   );
 };
 
-const PreserveThinkingToggle: FC = () => {
-  const modelLoaded = useChatRuntimeStore(
-    (s) => !!s.params.checkpoint && !s.modelLoading,
-  );
-  const supportsPreserveThinking = useChatRuntimeStore(
-    (s) => s.supportsPreserveThinking,
-  );
-  const preserveThinking = useChatRuntimeStore((s) => s.preserveThinking);
-  const setPreserveThinking = useChatRuntimeStore((s) => s.setPreserveThinking);
-  if (!supportsPreserveThinking) return null;
-  const disabled = !modelLoaded;
-  return (
-    <button
-      type="button"
-      disabled={disabled}
-      onClick={() => setPreserveThinking(!preserveThinking)}
-      className={cn(
-        "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-        disabled
-          ? "cursor-not-allowed opacity-40"
-          : preserveThinking
-            ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-            : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-      )}
-      aria-label={
-        preserveThinking ? "Disable preserve think" : "Enable preserve think"
-      }
-    >
-      {preserveThinking && !disabled ? (
-        <LightbulbIcon className="size-3.5" />
-      ) : (
-        <LightbulbOffIcon className="size-3.5" />
-      )}
-      <span>Preserve Think</span>
-    </button>
-  );
-};
+// Tool icon plus an X overlay the CSS reveals on hover when the pill is active.
+const PillGlyph: FC<{ children: ReactNode }> = ({ children }) => (
+  <span className="composer-pill-glyph">
+    {children}
+    <XIcon className="composer-pill-x" />
+  </span>
+);
 
 const WebSearchToggle: FC = () => {
   const modelLoaded = useChatRuntimeStore(
@@ -1034,7 +1386,9 @@ const WebSearchToggle: FC = () => {
       ? externalProviders.find((p) => p.id === externalSelection.providerId)
       : undefined;
   const isKimiExternal = selectedExternalProvider?.providerType === "kimi";
-  const disabled = !modelLoaded || !(supportsTools || supportsBuiltinWebSearch);
+  // Disable only when a loaded model lacks the capability; with no model the
+  // tool can still be pre-selected and reflected, matching the + menu.
+  const disabled = modelLoaded && !(supportsTools || supportsBuiltinWebSearch);
 
   return (
     <button
@@ -1048,7 +1402,7 @@ const WebSearchToggle: FC = () => {
         // the two pills mutually exclusive so the visible state always
         // matches what the backend ends up sending.
         if (isKimiExternal) {
-          setReasoningEnabled(!next);
+          setReasoningEnabled(!next, { persist: false });
           applyQwenThinkingParams(!next);
         }
       }}
@@ -1056,7 +1410,9 @@ const WebSearchToggle: FC = () => {
       data-active={toolsEnabled && !disabled ? "true" : "false"}
       aria-label={toolsEnabled ? "Disable web search" : "Enable web search"}
     >
-      <GlobeIcon className="size-3.5" />
+      <PillGlyph>
+        <GlobeIcon className="size-[15px]" />
+      </PillGlyph>
       <span>Search</span>
     </button>
   );
@@ -1077,8 +1433,9 @@ const CodeToolsToggle: FC = () => {
   );
   const codeToolsEnabled = useChatRuntimeStore((s) => s.codeToolsEnabled);
   const setCodeToolsEnabled = useChatRuntimeStore((s) => s.setCodeToolsEnabled);
-  const disabled =
-    !modelLoaded || !(supportsTools || supportsBuiltinCodeExecution);
+  // Disable only when a loaded model lacks the capability; with no model the
+  // tool can still be pre-selected and reflected, matching the + menu.
+  const disabled = modelLoaded && !(supportsTools || supportsBuiltinCodeExecution);
 
   return (
     <button
@@ -1091,7 +1448,13 @@ const CodeToolsToggle: FC = () => {
         codeToolsEnabled ? "Disable code execution" : "Enable code execution"
       }
     >
-      <CodeToggleIcon className="size-3.5" />
+      <PillGlyph>
+        <HugeiconsIcon
+          icon={CodeIcon}
+          className="size-[18.5px]"
+          strokeWidth={2}
+        />
+      </PillGlyph>
       <span>Code</span>
     </button>
   );
@@ -1129,31 +1492,36 @@ const ImagesToggle: FC = () => {
           : "Enable image generation"
       }
     >
-      <HugeiconsIcon icon={Image03Icon} className="size-3.5" strokeWidth={2} />
+      <PillGlyph>
+        <HugeiconsIcon icon={Image03Icon} className="size-3.5" strokeWidth={2} />
+      </PillGlyph>
       <span>Images</span>
     </button>
   );
 };
 
 const ArtifactsToggle: FC = () => {
-  const modelLoaded = useChatRuntimeStore(
-    (s) => !!s.params.checkpoint && !s.modelLoading,
-  );
   const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
   const setArtifactsEnabled = useChatRuntimeStore((s) => s.setArtifactsEnabled);
-  const disabled = !modelLoaded;
+  // Canvas is opt-in; the pill only shows once it is toggled on from the menu.
+  if (!artifactsEnabled) return null;
 
   return (
     <button
       type="button"
-      disabled={disabled}
-      onClick={() => setArtifactsEnabled(!artifactsEnabled)}
+      onClick={() => setArtifactsEnabled(false)}
       className="composer-pill-btn"
-      data-active={artifactsEnabled && !disabled ? "true" : "false"}
-      aria-label={artifactsEnabled ? "Disable artifacts" : "Enable artifacts"}
+      data-active="true"
+      aria-label="Disable canvas"
     >
-      <FileTextIcon className="size-3.5" />
-      <span>Artifacts</span>
+      <PillGlyph>
+        <HugeiconsIcon
+          icon={PencilRulerIcon}
+          className="size-[15.5px]"
+          strokeWidth={2}
+        />
+      </PillGlyph>
+      <span>Canvas</span>
     </button>
   );
 };
@@ -1215,84 +1583,309 @@ const ToolStatusDisplay: FC = () => {
     </div>
   );
 };
+// Plus menu: attachment and workflow actions. Opens downward in the centered
+// welcome composer; the docked composer passes side="top" to open upward.
+const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
+  side = "bottom",
+}) => {
+  const navigate = useNavigate();
+  const toolsEnabled = useChatRuntimeStore((s) => s.toolsEnabled);
+  const setToolsEnabled = useChatRuntimeStore((s) => s.setToolsEnabled);
+  const codeToolsEnabled = useChatRuntimeStore((s) => s.codeToolsEnabled);
+  const setCodeToolsEnabled = useChatRuntimeStore((s) => s.setCodeToolsEnabled);
+  const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
+  const setArtifactsEnabled = useChatRuntimeStore((s) => s.setArtifactsEnabled);
+  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  const setMcpEnabledForChat = useChatRuntimeStore(
+    (s) => s.setMcpEnabledForChat,
+  );
+  // Capability gating, mirroring the visible pills so menu and pills agree on
+  // what a loaded model supports (a tool the backend drops must not look on).
+  const modelLoaded = useChatRuntimeStore(
+    (s) => !!s.params.checkpoint && !s.modelLoading,
+  );
+  const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
+  const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
+  const supportsBuiltinWebSearch = useChatRuntimeStore(
+    (s) => s.supportsBuiltinWebSearch,
+  );
+  const supportsBuiltinCodeExecution = useChatRuntimeStore(
+    (s) => s.supportsBuiltinCodeExecution,
+  );
+  const supportsBuiltinImageGeneration = useChatRuntimeStore(
+    (s) => s.supportsBuiltinImageGeneration,
+  );
+  const imageToolsEnabled = useChatRuntimeStore((s) => s.imageToolsEnabled);
+  const setImageToolsEnabled = useChatRuntimeStore(
+    (s) => s.setImageToolsEnabled,
+  );
+  const setReasoningEnabled = useChatRuntimeStore((s) => s.setReasoningEnabled);
+  const connectionsEnabled = useExternalProvidersStore(
+    (s) => s.connectionsEnabled,
+  );
+  const externalProvidersAll = useExternalProvidersStore((s) => s.providers);
+  const externalProviders = connectionsEnabled ? externalProvidersAll : [];
+  const externalSelection = parseExternalModelId(checkpoint);
+  const selectedExternalProvider =
+    externalSelection != null
+      ? externalProviders.find((p) => p.id === externalSelection.providerId)
+      : undefined;
+  const isKimiExternal = selectedExternalProvider?.providerType === "kimi";
+  // Disable only when a loaded model lacks the capability; with no model the
+  // tool can still be pre-selected, matching the pill logic above.
+  const searchDisabled =
+    modelLoaded && !(supportsTools || supportsBuiltinWebSearch);
+  const codeDisabled =
+    modelLoaded && !(supportsTools || supportsBuiltinCodeExecution);
+  const imageDisabled = !modelLoaded;
+  // Like Search/Code: disabled only when a loaded model lacks tool support.
+  const mcpDisabled = modelLoaded && !supportsTools;
+  // Three most recently updated projects for the quick-access submenu.
+  const { projects } = useChatProjects();
+  const recentProjects = [...projects]
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, 3);
+  const openProject = (projectId: string) => {
+    useChatRuntimeStore.getState().setActiveProjectId(projectId);
+    navigate({ to: "/chat", search: { project: projectId } });
+  };
 
-const ComposerAction: FC<{
+  const startCompare = useCallback(() => {
+    const store = useChatRuntimeStore.getState();
+    store.setActiveThreadId(null);
+    store.setContextUsage(null);
+    // crypto.randomUUID is undefined in non-secure contexts (HTTP over a LAN IP).
+    const compareId =
+      typeof globalThis.crypto?.randomUUID === "function"
+        ? globalThis.crypto.randomUUID()
+        : `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    navigate({ to: "/chat", search: { compare: compareId } });
+  }, [navigate]);
+
+  const [newProjectOpen, setNewProjectOpen] = useState(false);
+
+  return (
+    <>
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild={true}>
+        <button
+          type="button"
+          aria-label="Tools and attachments"
+          className="unsloth-composer-plus"
+        >
+          <PlusIcon className="size-[22px] stroke-[1.75px]" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        side={side}
+        align="start"
+        sideOffset={2}
+        avoidCollisions={true}
+        className="unsloth-plus-menu w-[212px]"
+        // Don't refocus the + on close; the restored focus showed a stray
+        // focus-visible ring.
+        onCloseAutoFocus={(event) => event.preventDefault()}
+      >
+        <ComposerPrimitive.AddAttachment asChild={true}>
+          <DropdownMenuItem>
+            <HugeiconsIcon icon={AttachmentIcon} strokeWidth={2} />
+            Add photos &amp; files
+          </DropdownMenuItem>
+        </ComposerPrimitive.AddAttachment>
+        <ComposerAudioMenuItem />
+        <DropdownMenuItem
+          disabled={searchDisabled}
+          className={
+            toolsEnabled && !searchDisabled
+              ? "text-primary font-medium"
+              : undefined
+          }
+          onSelect={() => {
+            const next = !toolsEnabled;
+            setToolsEnabled(next);
+            // Mirror the Search pill: Kimi forbids search + thinking together.
+            if (isKimiExternal) {
+              setReasoningEnabled(!next, { persist: false });
+              applyQwenThinkingParams(!next);
+            }
+          }}
+        >
+          <GlobeIcon />
+          Web search
+          {toolsEnabled && !searchDisabled ? (
+            <CheckIcon className="ml-auto" />
+          ) : null}
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          disabled={codeDisabled}
+          className={
+            codeToolsEnabled && !codeDisabled
+              ? "text-primary font-medium"
+              : undefined
+          }
+          onSelect={() => setCodeToolsEnabled(!codeToolsEnabled)}
+        >
+          <HugeiconsIcon
+            icon={CodeIcon}
+            strokeWidth={2}
+            className="size-[1.175rem]!"
+          />
+          Code
+          {codeToolsEnabled && !codeDisabled ? (
+            <CheckIcon className="ml-auto" />
+          ) : null}
+        </DropdownMenuItem>
+        {supportsBuiltinImageGeneration && (
+          <DropdownMenuItem
+            disabled={imageDisabled}
+            className={
+              imageToolsEnabled && !imageDisabled
+                ? "text-primary font-medium"
+                : undefined
+            }
+            onSelect={() => setImageToolsEnabled(!imageToolsEnabled)}
+          >
+            <HugeiconsIcon icon={Image03Icon} strokeWidth={2} />
+            Images
+            {imageToolsEnabled && !imageDisabled ? (
+              <CheckIcon className="ml-auto" />
+            ) : null}
+          </DropdownMenuItem>
+        )}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem
+          className={artifactsEnabled ? "text-primary font-medium" : undefined}
+          onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+        >
+          <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
+          Canvas
+          {artifactsEnabled ? <CheckIcon className="ml-auto" /> : null}
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          disabled={mcpDisabled}
+          className={
+            mcpEnabledForChat && !mcpDisabled
+              ? "text-primary font-medium"
+              : undefined
+          }
+          onSelect={() => setMcpEnabledForChat(!mcpEnabledForChat)}
+        >
+          <HugeiconsIcon icon={McpServerIcon} strokeWidth={2} />
+          MCP
+          {mcpEnabledForChat && !mcpDisabled ? (
+            <CheckIcon className="ml-auto" />
+          ) : null}
+        </DropdownMenuItem>
+        {/* RAG hidden temporarily */}
+        <DropdownMenuItem onSelect={() => startCompare()}>
+          <Columns2Icon />
+          Compare chat
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>
+            <HugeiconsIcon icon={Folder01Icon} strokeWidth={2} />
+            Projects
+          </DropdownMenuSubTrigger>
+          <DropdownMenuSubContent className="unsloth-plus-menu w-[200px]">
+            <DropdownMenuItem onSelect={() => setNewProjectOpen(true)}>
+              <HugeiconsIcon icon={FolderAddIcon} strokeWidth={2} />
+              New project
+            </DropdownMenuItem>
+            <DropdownMenuLabel>Recents</DropdownMenuLabel>
+            {recentProjects.length > 0 ? (
+              recentProjects.map((project) => (
+                <DropdownMenuItem
+                  key={project.id}
+                  onSelect={() => openProject(project.id)}
+                >
+                  <HugeiconsIcon icon={Folder01Icon} strokeWidth={2} />
+                  <span className="truncate">{project.name}</span>
+                </DropdownMenuItem>
+              ))
+            ) : (
+              <DropdownMenuItem disabled={true}>
+                No recent projects
+              </DropdownMenuItem>
+            )}
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+      </DropdownMenuContent>
+    </DropdownMenu>
+      <NewProjectDialog
+        open={newProjectOpen}
+        onOpenChange={setNewProjectOpen}
+      />
+    </>
+  );
+};
+
+const ComposerRightControls: FC<{
   disabled?: boolean;
   shouldBlockSend?: () => boolean;
-}> = ({ disabled, shouldBlockSend }) => {
+  menuSide?: "top" | "bottom";
+}> = ({ disabled, shouldBlockSend, menuSide }) => {
   return (
-    <div className="aui-composer-action-wrapper composer-action-wrapper">
-      <div className="flex items-center gap-0.5">
-        <ComposerAddAttachment />
-        <ComposerAudioUpload />
-        <ReasoningToggle />
-        <PreserveThinkingToggle />
-        <WebSearchToggle />
-        <CodeToolsToggle />
-        <ImagesToggle />
-        <ArtifactsToggle />
-        <McpComposerButton />
-      </div>
-      <div className="flex items-center gap-1">
-        <ComposerPrimitive.If dictation={false}>
-          <ComposerPrimitive.Dictate asChild={true}>
-            <TooltipIconButton
-              tooltip="Dictate"
-              aria-label="Dictate"
-              variant="ghost"
-              className="size-8 rounded-full text-muted-foreground"
-            >
-              <MicIcon className="size-4" />
-            </TooltipIconButton>
-          </ComposerPrimitive.Dictate>
-        </ComposerPrimitive.If>
-        <ComposerPrimitive.If dictation={true}>
-          <ComposerPrimitive.StopDictation asChild={true}>
-            <TooltipIconButton
-              tooltip="Stop dictation"
-              aria-label="Stop dictation"
-              variant="ghost"
-              className="size-8 rounded-full text-destructive"
-            >
-              <SquareIcon className="size-3 animate-pulse fill-current" />
-            </TooltipIconButton>
-          </ComposerPrimitive.StopDictation>
-        </ComposerPrimitive.If>
-        <AuiIf condition={({ thread }) => !thread.isRunning}>
-          <ComposerPrimitive.Send asChild={true}>
-            <TooltipIconButton
-              tooltip="Send message"
-              side="bottom"
-              type="submit"
-              variant="default"
-              size="icon"
-              disabled={disabled}
-              onClick={(event) => {
-                if (shouldBlockSend?.()) {
-                  event.preventDefault();
-                }
-              }}
-              className="aui-composer-send size-8 rounded-full"
-              aria-label="Send message"
-            >
-              <ArrowUpIcon className="aui-composer-send-icon size-4" />
-            </TooltipIconButton>
-          </ComposerPrimitive.Send>
-        </AuiIf>
-        <AuiIf condition={({ thread }) => thread.isRunning}>
-          <ComposerPrimitive.Cancel asChild={true}>
-            <Button
-              type="button"
-              variant="default"
-              size="icon"
-              className="aui-composer-cancel size-8 rounded-full"
-              aria-label="Stop generating"
-            >
-              <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
-            </Button>
-          </ComposerPrimitive.Cancel>
-        </AuiIf>
-      </div>
+    <div className="aui-composer-action-wrapper flex shrink-0 items-center gap-1.5">
+      <ReasoningToggle side={menuSide} />
+      <ComposerPrimitive.If dictation={false}>
+        <ComposerPrimitive.Dictate asChild={true}>
+          <TooltipIconButton
+            tooltip="Dictate"
+            aria-label="Dictate"
+            variant="ghost"
+            className="size-8 rounded-full text-foreground"
+          >
+            <MicIcon className="size-5" />
+          </TooltipIconButton>
+        </ComposerPrimitive.Dictate>
+      </ComposerPrimitive.If>
+      <ComposerPrimitive.If dictation={true}>
+        <ComposerPrimitive.StopDictation asChild={true}>
+          <TooltipIconButton
+            tooltip="Stop dictation"
+            aria-label="Stop dictation"
+            variant="ghost"
+            className="size-8 rounded-full text-destructive"
+          >
+            <SquareIcon className="size-3 animate-pulse fill-current" />
+          </TooltipIconButton>
+        </ComposerPrimitive.StopDictation>
+      </ComposerPrimitive.If>
+      <AuiIf condition={({ thread }) => !thread.isRunning}>
+        <ComposerPrimitive.Send asChild={true}>
+          <TooltipIconButton
+            tooltip="Send message"
+            side="bottom"
+            type="submit"
+            variant="default"
+            size="icon"
+            disabled={disabled}
+            onClick={(event) => {
+              if (shouldBlockSend?.()) {
+                event.preventDefault();
+              }
+            }}
+            className="aui-composer-send ml-1.5 size-8 rounded-full"
+            aria-label="Send message"
+          >
+            <ArrowUpIcon className="aui-composer-send-icon size-[21px] stroke-2" />
+          </TooltipIconButton>
+        </ComposerPrimitive.Send>
+      </AuiIf>
+      <AuiIf condition={({ thread }) => thread.isRunning}>
+        <ComposerPrimitive.Cancel asChild={true}>
+          <Button
+            type="button"
+            variant="default"
+            size="icon"
+            className="aui-composer-cancel ml-1.5 size-8 rounded-full"
+            aria-label="Stop generating"
+          >
+            <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
+          </Button>
+        </ComposerPrimitive.Cancel>
+      </AuiIf>
     </div>
   );
 };
@@ -1474,11 +2067,11 @@ const AssistantActionBar: FC = () => {
           side="bottom"
           align="start"
           onCloseAutoFocus={(e) => e.preventDefault()}
-          className="aui-action-bar-more-content z-50 min-w-32 overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md"
+          className="aui-action-bar-more-content z-50 min-w-32 overflow-hidden rounded-md [--radius:1.1rem] bg-popover p-1 text-popover-foreground shadow-[0_2px_8px_-2px_rgba(27,27,31,0.16)] dark:shadow-none"
         >
           <ActionBarPrimitive.ExportMarkdown asChild={true}>
             <ActionBarMorePrimitive.Item className="aui-action-bar-more-item flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground">
-              <DownloadIcon strokeWidth={1.75} className="size-icon" />
+              <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon" />
               Export as Markdown
             </ActionBarMorePrimitive.Item>
           </ActionBarPrimitive.ExportMarkdown>
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
index a9919708d0..c0ced3b844 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
@@ -6,7 +6,9 @@
 import { Button } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-import { DownloadIcon, ImageIcon, PencilIcon } from "lucide-react";
+import { ImageIcon, PencilIcon } from "lucide-react";
+import { Download01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import type { CSSProperties, MouseEvent } from "react";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { useGeneratedImageOverlay } from "./generated-image-overlay-context";
@@ -374,7 +376,7 @@ const ImageGenerationToolUIImpl: ToolCallMessagePartComponent = ({
                   onClick={handleDownload}
                   aria-label="Download generated image"
                 >
-                  <DownloadIcon className="size-4" />
+                  <HugeiconsIcon icon={Download01Icon} className="size-4" />
                 </Button>
               </div>
             </div>
diff --git a/studio/frontend/src/components/ui/combobox.tsx b/studio/frontend/src/components/ui/combobox.tsx
index 4fe310b788..53d77415e5 100644
--- a/studio/frontend/src/components/ui/combobox.tsx
+++ b/studio/frontend/src/components/ui/combobox.tsx
@@ -1,6 +1,6 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
 "use client";
 
 /* eslint-disable react-refresh/only-export-components */
@@ -143,10 +143,10 @@ function ComboboxInput({
   );
 }
 
-function ComboboxContent({
-  className,
-  side = "bottom",
-  sideOffset = 6,
+function ComboboxContent({
+  className,
+  side = "bottom",
+  sideOffset = 6,
   align = "start",
   alignOffset = 0,
   anchor,
@@ -162,23 +162,23 @@ function ComboboxContent({
   const dialogContainer = useDialogPortalContainer();
   return (
     <ComboboxPrimitive.Portal container={container ?? dialogContainer ?? undefined}>
-      <ComboboxPrimitive.Positioner
-        side={side}
-        sideOffset={sideOffset}
-        align={align}
-        alignOffset={alignOffset}
-        anchor={anchor}
-        className="isolate z-[120] pointer-events-auto"
-      >
-        <ComboboxPrimitive.Popup
-          data-slot="combobox-content"
-          data-chips={!!anchor}
-          className={cn(
-            "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 shadow-border ring-1 ring-border *:data-[slot=input-group]:bg-input/30 max-h-72 min-w-36 overflow-hidden rounded-xl corner-squircle duration-100 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-9 *:data-[slot=input-group]:border-none *:data-[slot=input-group]:shadow-none group/combobox-content relative pointer-events-auto max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) data-[chips=true]:min-w-(--anchor-width)",
-            className,
-          )}
-          {...props}
-        />
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="isolate z-[120] pointer-events-auto"
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          data-chips={!!anchor}
+          className={cn(
+            "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 *:data-[slot=input-group]:bg-input/30 max-h-72 min-w-36 overflow-hidden rounded-xl corner-squircle duration-100 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-9 *:data-[slot=input-group]:border-none *:data-[slot=input-group]:shadow-none group/combobox-content relative pointer-events-auto max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) data-[chips=true]:min-w-(--anchor-width)",
+            className,
+          )}
+          {...props}
+        />
       </ComboboxPrimitive.Positioner>
     </ComboboxPrimitive.Portal>
   );
diff --git a/studio/frontend/src/components/ui/dropdown-menu.tsx b/studio/frontend/src/components/ui/dropdown-menu.tsx
index 9102e5c945..0f67194ee3 100644
--- a/studio/frontend/src/components/ui/dropdown-menu.tsx
+++ b/studio/frontend/src/components/ui/dropdown-menu.tsx
@@ -1,6 +1,6 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
 import type * as React from "react";
 
@@ -46,7 +46,7 @@ function DropdownMenuContent({
         sideOffset={sideOffset}
         align={align}
         className={cn(
-          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 shadow-border ring-1 ring-border bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
+          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
           className,
         )}
         {...props}
@@ -244,7 +244,7 @@ function DropdownMenuSubContent({
     <DropdownMenuPrimitive.SubContent
       data-slot="dropdown-menu-sub-content"
       className={cn(
-        "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 shadow-border ring-1 ring-border bg-popover text-popover-foreground min-w-36 rounded-lg p-1 duration-100 z-50 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden",
+        "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-36 rounded-lg p-1 duration-100 z-50 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden",
         className,
       )}
       {...props}
diff --git a/studio/frontend/src/components/ui/popover.tsx b/studio/frontend/src/components/ui/popover.tsx
index e2031a0b10..a3fdac2100 100644
--- a/studio/frontend/src/components/ui/popover.tsx
+++ b/studio/frontend/src/components/ui/popover.tsx
@@ -1,6 +1,6 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
 "use client";
 
 import { Popover as PopoverPrimitive } from "radix-ui";
@@ -33,7 +33,7 @@ function PopoverContent({
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 shadow-border ring-1 ring-border flex flex-col gap-4 rounded-lg p-4 text-sm duration-100 z-50 w-72 origin-(--radix-popover-content-transform-origin) outline-hidden",
+          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 flex flex-col gap-4 rounded-lg p-4 text-sm duration-100 z-50 w-72 origin-(--radix-popover-content-transform-origin) outline-hidden",
           className,
         )}
         {...props}
diff --git a/studio/frontend/src/components/ui/select.tsx b/studio/frontend/src/components/ui/select.tsx
index 4044c164e5..03c584fdd1 100644
--- a/studio/frontend/src/components/ui/select.tsx
+++ b/studio/frontend/src/components/ui/select.tsx
@@ -125,7 +125,7 @@ function SelectContent({
         data-slot="select-content"
         data-align-trigger={position === "item-aligned"}
         className={cn(
-          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 shadow-border ring-1 ring-border min-w-36 rounded-xl p-1 corner-squircle duration-100 relative z-50 max-h-(--radix-select-content-available-height) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto ",
+          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 min-w-36 rounded-xl p-1 corner-squircle duration-100 relative z-50 max-h-(--radix-select-content-available-height) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto ",
           position === "popper" &&
             "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
           className,
diff --git a/studio/frontend/src/components/ui/sonner.tsx b/studio/frontend/src/components/ui/sonner.tsx
index bf6d4970b0..6380a7bfc8 100644
--- a/studio/frontend/src/components/ui/sonner.tsx
+++ b/studio/frontend/src/components/ui/sonner.tsx
@@ -63,7 +63,8 @@ const Toaster = ({ ...props }: ToasterProps) => {
         {
           "--normal-bg": "var(--popover)",
           "--normal-text": "var(--popover-foreground)",
-          "--normal-border": "var(--border)",
+          // No border line; elevation comes from the composer's drop shadow.
+          "--normal-border": "transparent",
           "--border-radius": "var(--radius)",
           // Pin the close button inside the toast's top-right corner.
           // Sonner defaults to the left/outside edge, so keep the horizontal
diff --git a/studio/frontend/src/components/ui/tabs.tsx b/studio/frontend/src/components/ui/tabs.tsx
index 07167ddf36..1fa8274573 100644
--- a/studio/frontend/src/components/ui/tabs.tsx
+++ b/studio/frontend/src/components/ui/tabs.tsx
@@ -1,6 +1,6 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
 "use client";
 
 /* eslint-disable react-refresh/only-export-components */
@@ -54,7 +54,7 @@ export const tabsListVariants = cva(
     variants: {
       variant: {
         default: "bg-muted",
-        line: "gap-1 bg-transparent",
+        line: "gap-2 bg-transparent group-data-horizontal/tabs:h-auto",
       },
     },
     defaultVariants: {
@@ -95,8 +95,10 @@ export function TabsTrigger({
       className={cn(
         "gap-1.5 rounded-xl corner-squircle border border-transparent px-2 py-1 text-sm font-medium group-data-vertical/tabs:px-2.5 group-data-vertical/tabs:py-1.5 [&_svg:not([class*='size-'])]:size-4 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring text-foreground/60 hover:text-foreground dark:text-muted-foreground dark:hover:text-foreground relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center whitespace-nowrap transition-colors group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
+        // Line variant is a roomier pill (no underline); padding overrides px-2 py-1.
+        "group-data-[variant=line]/tabs-list:px-3.5 group-data-[variant=line]/tabs-list:py-2.5",
         "data-active:text-foreground dark:data-active:text-foreground",
-        "after:bg-foreground after:absolute after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
+        "after:bg-foreground after:absolute after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5",
         className,
       )}
       {...props}
@@ -104,7 +106,7 @@ export function TabsTrigger({
       {isActive && (
         <motion.span
           layoutId={`tab-bg-${ctx.id}`}
-          className="absolute inset-0 rounded-xl bg-background dark:bg-input/30 dark:border dark:border-input"
+          className="absolute inset-0 rounded-xl bg-background dark:bg-input/30 dark:border dark:border-input group-data-[variant=line]/tabs-list:bg-[#ececec] dark:group-data-[variant=line]/tabs-list:bg-[#2d2f33] dark:group-data-[variant=line]/tabs-list:border-0"
           transition={{
             type: "spring",
             stiffness: 500,
diff --git a/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts b/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
new file mode 100644
index 0000000000..a679e8ed83
--- /dev/null
+++ b/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { DictationAdapter } from "@assistant-ui/react";
+import { toast } from "sonner";
+
+const getSpeechRecognitionAPI = (): SpeechRecognitionConstructor | undefined => {
+  if (typeof window === "undefined") return undefined;
+  return window.SpeechRecognition ?? window.webkitSpeechRecognition;
+};
+
+const stopStream = (stream: MediaStream | null) => {
+  stream?.getTracks().forEach((track) => track.stop());
+};
+
+const describeMediaError = (error: unknown): string => {
+  if (!(error instanceof DOMException)) {
+    return "Dictation could not access the microphone.";
+  }
+  if (error.name === "NotAllowedError") {
+    return "Microphone access is blocked. Allow microphone access for this Studio page, then try again.";
+  }
+  if (error.name === "NotFoundError") {
+    return "No microphone was found for dictation.";
+  }
+  if (error.name === "NotReadableError") {
+    return "The microphone is already in use or unavailable.";
+  }
+  return error.message || "Dictation could not access the microphone.";
+};
+
+const describeSpeechError = (error: string, message?: string): string => {
+  if (error === "not-allowed") {
+    return "Speech recognition was blocked by the browser. Check microphone permissions for this Studio page.";
+  }
+  if (error === "service-not-allowed") {
+    return "Speech recognition is blocked by the browser speech service.";
+  }
+  if (error === "network") {
+    return "Speech recognition could not reach the browser speech service.";
+  }
+  if (error === "language-not-supported") {
+    return "Speech recognition does not support the current language.";
+  }
+  return message || `Speech recognition failed: ${error}`;
+};
+
+export class StudioWebSpeechDictationAdapter implements DictationAdapter {
+  private readonly language: string;
+  private readonly continuous: boolean;
+  private readonly interimResults: boolean;
+
+  constructor(
+    options: {
+      language?: string;
+      continuous?: boolean;
+      interimResults?: boolean;
+    } = {},
+  ) {
+    this.language = options.language ?? navigator.language ?? "en-US";
+    this.continuous = options.continuous ?? true;
+    this.interimResults = options.interimResults ?? true;
+  }
+
+  static isSupported(): boolean {
+    return (
+      typeof window !== "undefined" &&
+      window.isSecureContext &&
+      getSpeechRecognitionAPI() !== undefined &&
+      navigator.mediaDevices?.getUserMedia !== undefined
+    );
+  }
+
+  listen(): DictationAdapter.Session {
+    const SpeechRecognitionAPI = getSpeechRecognitionAPI();
+    if (!SpeechRecognitionAPI || !navigator.mediaDevices?.getUserMedia) {
+      throw new Error("Speech recognition is not supported in this browser.");
+    }
+
+    const recognition = new SpeechRecognitionAPI();
+    recognition.lang = this.language;
+    recognition.continuous = this.continuous;
+    recognition.interimResults = this.interimResults;
+
+    const speechStartCallbacks = new Set<() => void>();
+    const speechEndCallbacks = new Set<(result: DictationAdapter.Result) => void>();
+    const speechCallbacks = new Set<(result: DictationAdapter.Result) => void>();
+
+    let stream: MediaStream | null = null;
+    let finalTranscript = "";
+    let ended = false;
+    let started = false;
+    let resolveEnded: (() => void) | null = null;
+    const endedPromise = new Promise<void>((resolve) => {
+      resolveEnded = resolve;
+    });
+
+    const session: DictationAdapter.Session = {
+      status: { type: "starting" },
+
+      stop: async () => {
+        if (!ended && started) {
+          recognition.stop();
+        } else if (!ended) {
+          finish("stopped");
+        }
+        await endedPromise;
+      },
+
+      cancel: () => {
+        if (!ended && started) {
+          recognition.abort();
+        } else if (!ended) {
+          finish("cancelled");
+        }
+      },
+
+      onSpeechStart: (callback) => {
+        speechStartCallbacks.add(callback);
+        return () => {
+          speechStartCallbacks.delete(callback);
+        };
+      },
+
+      onSpeechEnd: (callback) => {
+        speechEndCallbacks.add(callback);
+        return () => {
+          speechEndCallbacks.delete(callback);
+        };
+      },
+
+      onSpeech: (callback) => {
+        speechCallbacks.add(callback);
+        return () => {
+          speechCallbacks.delete(callback);
+        };
+      },
+    };
+
+    const finish = (reason: "stopped" | "cancelled" | "error") => {
+      if (ended) return;
+      ended = true;
+      session.status = { type: "ended", reason };
+      stopStream(stream);
+      stream = null;
+      if (finalTranscript) {
+        for (const callback of speechEndCallbacks) {
+          callback({ transcript: finalTranscript });
+        }
+        finalTranscript = "";
+      }
+      resolveEnded?.();
+    };
+
+    recognition.addEventListener("start", () => {
+      session.status = { type: "running" };
+    });
+
+    recognition.addEventListener("speechstart", () => {
+      for (const callback of speechStartCallbacks) callback();
+    });
+
+    recognition.addEventListener("result", (event) => {
+      const speechEvent = event as SpeechRecognitionEvent;
+      for (let i = speechEvent.resultIndex; i < speechEvent.results.length; i++) {
+        const result = speechEvent.results[i];
+        if (!result) continue;
+        const transcript = result[0]?.transcript ?? "";
+        if (result.isFinal) {
+          finalTranscript += transcript;
+          for (const callback of speechCallbacks) {
+            callback({ transcript, isFinal: true });
+          }
+        } else {
+          for (const callback of speechCallbacks) {
+            callback({ transcript, isFinal: false });
+          }
+        }
+      }
+    });
+
+    recognition.addEventListener("end", () => {
+      finish("stopped");
+    });
+
+    recognition.addEventListener("error", (event) => {
+      const errorEvent = event as SpeechRecognitionErrorEvent;
+      if (errorEvent.error === "aborted") {
+        finish("cancelled");
+        return;
+      }
+      const description = describeSpeechError(errorEvent.error, errorEvent.message);
+      console.error("Dictation error:", errorEvent.error, errorEvent.message);
+      toast.error(description);
+      finish("error");
+    });
+
+    void (async () => {
+      try {
+        stream = await navigator.mediaDevices.getUserMedia({
+          audio: { echoCancellation: true, noiseSuppression: true },
+        });
+        if (ended) {
+          stopStream(stream);
+          stream = null;
+          return;
+        }
+        const audioTrack = stream.getAudioTracks()[0];
+        if (!audioTrack || audioTrack.readyState !== "live") {
+          throw new DOMException("No live microphone track is available.", "NotFoundError");
+        }
+        try {
+          recognition.start(audioTrack);
+        } catch (error) {
+          // Older engines expose only start(); retry without the experimental track overload.
+          console.debug("Dictation start(audioTrack) failed; retrying start().", error);
+          recognition.start();
+        }
+        started = true;
+      } catch (error) {
+        const description = describeMediaError(error);
+        console.error("Dictation microphone error:", error);
+        toast.error(description);
+        finish("error");
+      }
+    })();
+
+    return session;
+  }
+}
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 85b3be7dea..7a71850d66 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -306,7 +306,9 @@ export async function listChatThreads(
   const qs = params.toString();
   const response = await authFetch(`/api/chat/threads${qs ? `?${qs}` : ""}`);
   const data = await parseJsonOrThrow<{ threads: ThreadRecord[] }>(response);
-  return data.threads;
+  // Always hand back an array: an older or misbehaving backend may omit the
+  // field or send a non-array, which would crash list consumers.
+  return Array.isArray(data.threads) ? data.threads : [];
 }
 
 export async function getChatThread(
@@ -370,7 +372,9 @@ export async function listChatProjects(
   const qs = params.toString();
   const response = await authFetch(`/api/chat/projects${qs ? `?${qs}` : ""}`);
   const data = await parseJsonOrThrow<{ projects: ProjectRecord[] }>(response);
-  return data.projects;
+  // Always hand back an array: an older or misbehaving backend may omit the
+  // field or send a non-array, which would crash list consumers.
+  return Array.isArray(data.projects) ? data.projects : [];
 }
 
 export async function getChatProject(
diff --git a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
index 8de3f7861d..b4ddf38aaa 100644
--- a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
+++ b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
@@ -15,11 +15,12 @@ import { cn } from "@/lib/utils";
 import {
   CheckIcon,
   CopyIcon,
-  DownloadIcon,
   EyeIcon,
   Maximize2Icon,
   XIcon,
 } from "lucide-react";
+import { Download01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import {
   type KeyboardEvent,
   useEffect,
@@ -266,7 +267,7 @@ export function ArtifactSurface({
             onClick={() => downloadTextFile(filename, artifact.code)}
             aria-label="Download artifact HTML"
           >
-            <DownloadIcon className="size-4" />
+            <HugeiconsIcon icon={Download01Icon} className="size-4" />
           </Button>
           <Button
             type="button"
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index d793b7697b..834d0baf34 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -388,6 +388,7 @@ const CompareContent = memo(function CompareContent({
   onFoldersChange,
   onModelsChange,
   deleteDisabled,
+  onExitCompare,
 }: {
   pairId: string;
   projectId?: string | null;
@@ -397,11 +398,16 @@ const CompareContent = memo(function CompareContent({
   onFoldersChange?: () => void;
   onModelsChange?: (deletedModel?: DeletedModelRef) => void;
   deleteDisabled?: boolean;
+  onExitCompare?: () => void;
 }): ReactElement {
   const isLoraCompare = useIsLoraCompare();
 
   return isLoraCompare ? (
-    <LoraCompareContent pairId={pairId} projectId={projectId} />
+    <LoraCompareContent
+      pairId={pairId}
+      onExitCompare={onExitCompare}
+      projectId={projectId}
+    />
   ) : (
     <GeneralCompareContent
       pairId={pairId}
@@ -412,6 +418,7 @@ const CompareContent = memo(function CompareContent({
       onFoldersChange={onFoldersChange}
       onModelsChange={onModelsChange}
       deleteDisabled={deleteDisabled}
+      onExitCompare={onExitCompare}
     />
   );
 });
@@ -512,8 +519,13 @@ function CompareShell({
 /** Fast path: same model, adapter on/off, simultaneous generation. */
 const LoraCompareContent = memo(function LoraCompareContent({
   pairId,
+  onExitCompare,
   projectId,
-}: { pairId: string; projectId?: string | null }): ReactElement {
+}: {
+  pairId: string;
+  onExitCompare?: () => void;
+  projectId?: string | null;
+}): ReactElement {
   const handlesRef = useRef<Record<string, CompareHandle>>({});
   const [baseThreadId, setBaseThreadId] = useState<string>();
   const [loraThreadId, setLoraThreadId] = useState<string>();
@@ -539,7 +551,12 @@ const LoraCompareContent = memo(function LoraCompareContent({
   return (
     <CompareShell
       handlesRef={handlesRef}
-      composer={<SharedComposer handlesRef={handlesRef} />}
+      composer={
+        <SharedComposer
+          handlesRef={handlesRef}
+          onExitCompare={onExitCompare}
+        />
+      }
     >
       <>
         <ComparePane
@@ -639,6 +656,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   onFoldersChange,
   onModelsChange,
   deleteDisabled,
+  onExitCompare,
 }: {
   pairId: string;
   projectId?: string | null;
@@ -648,6 +666,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   onFoldersChange?: () => void;
   onModelsChange?: (deletedModel?: DeletedModelRef) => void;
   deleteDisabled?: boolean;
+  onExitCompare?: () => void;
 }): ReactElement {
   const handlesRef = useRef<Record<string, CompareHandle>>({});
   const [model1ThreadId, setModel1ThreadId] = useState<string>();
@@ -712,6 +731,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
           handlesRef={handlesRef}
           model1={model1}
           model2={model2}
+          onExitCompare={onExitCompare}
         />
       }
     >
@@ -1067,6 +1087,15 @@ export function ChatPage(): ReactElement {
   const [modelSelectorOpen, setModelSelectorOpen] = useState(false);
   const [modelSelectorLocked, setModelSelectorLocked] = useState(false);
   const viewBeforeCompareRef = useRef<ChatSearch | null>(null);
+  // Tracks the latest non-compare view so exiting compare can restore it even
+  // when compare was opened from a path that does not set viewBeforeCompareRef
+  // (e.g. the composer + menu).
+  const lastNonCompareViewRef = useRef<ChatSearch | null>(null);
+  useEffect(() => {
+    if (!search.compare) {
+      lastNonCompareViewRef.current = { ...search };
+    }
+  }, [search]);
   const inferenceParams = useChatRuntimeStore((state) => state.params);
   const setInferenceParams = useChatRuntimeStore((state) => state.setParams);
   const activeGgufVariant = useChatRuntimeStore(
@@ -1768,8 +1797,7 @@ export function ChatPage(): ReactElement {
     () => setSettingsOpen(false),
     [setSettingsOpen],
   );
-  const { setPinned, isMobile } = useSidebar();
-  const openSidebar = useCallback(() => setPinned(true), [setPinned]);
+  const { isMobile } = useSidebar();
 
   const enterCompare = useCallback(() => {
     viewBeforeCompareRef.current = { ...search };
@@ -1785,8 +1813,14 @@ export function ChatPage(): ReactElement {
   }, [currentProjectId, navigate, search]);
 
   const exitCompare = useCallback(() => {
-    const saved = viewBeforeCompareRef.current;
-    if (!saved) return;
+    // Prefer the explicit save; fall back to the last non-compare view so the
+    // composer + menu path also returns to where the user started.
+    const saved = viewBeforeCompareRef.current ?? lastNonCompareViewRef.current;
+    // No saved view (compare opened by direct URL); fall back to a fresh chat.
+    if (!saved) {
+      navigate({ to: "/chat" });
+      return;
+    }
     viewBeforeCompareRef.current = null;
     navigate({ to: "/chat", search: saved });
     // Restore usage from the last assistant message, but only if it
@@ -2038,7 +2072,6 @@ export function ChatPage(): ReactElement {
         closeModelSelector,
         openSettings,
         closeSettings,
-        openSidebar,
         enterCompare,
         exitCompare,
       }),
@@ -2050,7 +2083,6 @@ export function ChatPage(): ReactElement {
       exitCompare,
       openModelSelector,
       openSettings,
-      openSidebar,
     ],
   );
 
@@ -2256,6 +2288,7 @@ export function ChatPage(): ReactElement {
             onFoldersChange={refreshLocalModels}
             onModelsChange={refreshModelLists}
             deleteDisabled={modelOperationInProgress}
+            onExitCompare={exitCompare}
           />
         )}
 
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 90c2185db3..bddcb02c69 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -723,18 +723,17 @@ export function ChatSettingsPanel({
 
   const settingsContent = (
     <>
-      <div
-        ref={settingsScrollRef}
-        className="relative h-full overflow-y-auto"
-      >
-      <div className="sticky top-0 z-10 flex h-[48px] items-start gap-2 bg-panel-surface pl-[18px] pr-[16px] pt-[11px]">
+      <div className="flex h-full min-h-0 flex-col">
+      {/* Header sits outside the scroll area so the scrollbar never shifts the
+          close button. */}
+      <div className="flex h-[48px] shrink-0 items-start gap-2 bg-panel-surface pl-[18px] pr-[16px] pt-[11px]">
         {isMobile ? (
-          <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
+          <span className="flex h-[34px] flex-1 items-center text-[16px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
             Run settings
           </span>
         ) : (
           <>
-            <span className="flex h-[34px] flex-1 items-center text-[15px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
+            <span className="flex h-[34px] flex-1 items-center text-[16px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
               Run settings
             </span>
             <Tooltip>
@@ -764,6 +763,10 @@ export function ChatSettingsPanel({
         )}
       </div>
 
+      <div
+        ref={settingsScrollRef}
+        className="run-settings-scroll relative min-h-0 flex-1 overflow-y-auto"
+      >
       <div className="px-[18px] pt-3">
         {hasModelContent && (
         <CollapsibleSection label="Model" defaultOpen={true} first>
@@ -1373,6 +1376,7 @@ export function ChatSettingsPanel({
         ) : null}
       </div>
       </div>
+      </div>
       <Dialog
         open={systemPromptEditorOpen}
         onOpenChange={(nextOpen) => {
diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index 676dcc23d5..3d867b07f7 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -64,7 +64,7 @@ export function ChatSearchDialog() {
     <CommandDialog
       open={isOpen}
       onOpenChange={setOpen}
-      className="corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px] border-0 ring-0 shadow-[0_10px_34px_rgba(0,0,0,0.12)] dark:border dark:border-border dark:ring-0 dark:shadow-none"
+      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px]"
       overlayClassName="bg-transparent"
     >
       <Command className="rounded-4xl p-0" filter={chatSearchFilter}>
@@ -87,7 +87,7 @@ export function ChatSearchDialog() {
             <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="size-4" />
           </button>
         </div>
-        <CommandList className="cmd-native-scrollbar max-h-[420px] p-1">
+        <CommandList className="cmd-native-scrollbar hover-scrollbar max-h-[420px] p-1">
           <CommandEmpty className="py-6 text-center text-xs text-muted-foreground">
             {loading
               ? "Loading…"
diff --git a/studio/frontend/src/features/chat/components/new-project-dialog.tsx b/studio/frontend/src/features/chat/components/new-project-dialog.tsx
new file mode 100644
index 0000000000..38b0983e10
--- /dev/null
+++ b/studio/frontend/src/features/chat/components/new-project-dialog.tsx
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useNavigate } from "@tanstack/react-router";
+import { useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { toast } from "@/lib/toast";
+
+import { createChatProject } from "../hooks/use-chat-projects";
+import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+
+// Create-project dialog usable from the composer + menu. Creating opens the new
+// project straight away rather than dropping the user on the projects list.
+export function NewProjectDialog({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const navigate = useNavigate();
+  const [name, setName] = useState("");
+
+  async function commitCreate() {
+    const trimmed = name.trim();
+    if (!trimmed) return;
+    try {
+      const project = await createChatProject(trimmed);
+      onOpenChange(false);
+      setName("");
+      const runtime = useChatRuntimeStore.getState();
+      runtime.setActiveThreadId(null);
+      runtime.setActiveProjectId(project.id);
+      navigate({ to: "/chat", search: { project: project.id } });
+    } catch (err) {
+      toast.error("Failed to create project", {
+        description: err instanceof Error ? err.message : undefined,
+      });
+    }
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) setName("");
+        onOpenChange(next);
+      }}
+    >
+      <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>New project</DialogTitle>
+        </DialogHeader>
+        <Input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") {
+              e.preventDefault();
+              void commitCreate();
+            }
+          }}
+          autoFocus={true}
+          maxLength={120}
+          placeholder="Project name"
+          aria-label="Project name"
+          className="focus-visible:border-input focus-visible:ring-0"
+        />
+        <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+          <Button
+            type="button"
+            variant="ghost"
+            onClick={() => onOpenChange(false)}
+          >
+            Cancel
+          </Button>
+          <Button
+            type="button"
+            onClick={() => void commitCreate()}
+            disabled={!name.trim()}
+          >
+            Create
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-projects.ts b/studio/frontend/src/features/chat/hooks/use-chat-projects.ts
index fe0dfa9e65..3f0d46982d 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-projects.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-projects.ts
@@ -21,9 +21,11 @@ export function useChatProjects(): {
   isLoading: boolean;
   hasLoaded: boolean;
 } {
-  const [projects, setProjects] = useState<ProjectRecord[]>(cachedProjects);
-  const [isLoading, setIsLoading] = useState(cachedProjects.length === 0);
-  const [hasLoaded, setHasLoaded] = useState(cachedProjects.length > 0);
+  // Stay null-safe even if the cache was poisoned by a bad response.
+  const cached = Array.isArray(cachedProjects) ? cachedProjects : [];
+  const [projects, setProjects] = useState<ProjectRecord[]>(cached);
+  const [isLoading, setIsLoading] = useState(cached.length === 0);
+  const [hasLoaded, setHasLoaded] = useState(cached.length > 0);
 
   useEffect(() => {
     let cancelled = false;
@@ -32,8 +34,8 @@ export function useChatProjects(): {
       if (!cancelled) setIsLoading(true);
       try {
         const next = await listStoredChatProjects({ includeArchived: false });
-        cachedProjects = next;
-        if (!cancelled) setProjects(next);
+        cachedProjects = Array.isArray(next) ? next : [];
+        if (!cancelled) setProjects(cachedProjects);
       } catch (error) {
         if (isExpectedBackgroundChatStorageError(error)) {
           return;
diff --git a/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts b/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts
new file mode 100644
index 0000000000..e159101a7f
--- /dev/null
+++ b/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useEffect, useState } from "react";
+
+// Tracks which of the given keys are active and the order in which each became
+// active, so opt-in composer pills (Canvas, MCP) render in the order they were
+// toggled on rather than a fixed order.
+export function usePillActivationOrder(states: Record<string, boolean>): string[] {
+  const [order, setOrder] = useState<string[]>(() =>
+    Object.keys(states).filter((key) => states[key]),
+  );
+  // Re-run only when the active/inactive set changes, not on every render.
+  const signature = Object.keys(states)
+    .map((key) => `${key}:${states[key] ? 1 : 0}`)
+    .join(",");
+  useEffect(() => {
+    setOrder((prev) => {
+      const next = prev.filter((key) => states[key]);
+      for (const key of Object.keys(states)) {
+        if (states[key] && !next.includes(key)) next.push(key);
+      }
+      const unchanged =
+        next.length === prev.length && next.every((key, i) => key === prev[i]);
+      return unchanged ? prev : next;
+    });
+    // states is read fresh inside; signature captures its boolean values.
+  }, [signature]);
+  return order;
+}
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index b98be8bf69..92d2c319a6 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -1,13 +1,10 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import {
-  Cancel01Icon,
-  McpServerIcon,
-  Tick02Icon,
-} from "@hugeicons/core-free-icons";
+import { McpServerIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { useCallback, useEffect, useState } from "react";
+import { CheckIcon } from "lucide-react";
+import { type FC, useCallback, useEffect, useState } from "react";
 import { toast } from "sonner";
 
 import {
@@ -23,7 +20,6 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
-import { cn } from "@/lib/utils";
 
 import {
   type McpServerConfig,
@@ -34,6 +30,23 @@ import {
 import { ChatMcpServersDialog } from "./chat-mcp-servers-dialog";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
 
+// Matches the Thinking pill chevron so the affordance reads the same.
+const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={1.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M5.99977 9.00005L11.9998 15L17.9998 9" />
+  </svg>
+);
+
 type McpPreset = {
   id: string;
   displayName: string; // stored row name
@@ -76,7 +89,11 @@ function normalizeMcpUrl(url: string): string {
 // Static, so it is not rebuilt on every render.
 const PRESET_URLS = new Set(MCP_PRESETS.map((p) => normalizeMcpUrl(p.url)));
 
-export function McpComposerButton() {
+export function McpComposerButton({
+  side = "bottom",
+}: {
+  side?: "top" | "bottom";
+} = {}) {
   const modelLoaded = useChatRuntimeStore(
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
@@ -93,32 +110,20 @@ export function McpComposerButton() {
   const [pendingUrl, setPendingUrl] = useState<string | null>(null);
   const [hintKey, setHintKey] = useState<string | null>(null);
 
-  // mcp_enabled only applies on the local tool-capable send path; grey out otherwise.
-  const usable = modelLoaded && supportsTools;
-
-  // Keep the per-chat flag in step with whether any server is enabled. Reads the
-  // store directly so the callback stays stable (no refetch loop on mount).
-  const reconcileFlag = useCallback(
-    (rows: McpServerConfig[]) => {
-      const anyEnabled = rows.some((s) => s.is_enabled);
-      const current = useChatRuntimeStore.getState().mcpEnabledForChat;
-      if (anyEnabled && !current) setMcpEnabledForChat(true);
-      else if (!anyEnabled && current) setMcpEnabledForChat(false);
-    },
-    [setMcpEnabledForChat],
-  );
+  // Grey out only when a loaded model lacks tool support; with no model yet MCP
+  // can still be pre-selected, matching the other composer tools.
+  const usable = !modelLoaded || supportsTools;
 
   const refresh = useCallback(async () => {
     try {
       const rows = await listMcpServers();
       setServers(rows);
-      reconcileFlag(rows);
     } catch {
       // Keep prior state if the list call fails.
     }
-  }, [reconcileFlag]);
+  }, []);
 
-  // Initial load reconciles the pill with already-enabled servers (also on open).
+  // Load the server list on mount and whenever the menu opens.
   useEffect(() => {
     void refresh();
   }, [refresh]);
@@ -206,27 +211,12 @@ export function McpComposerButton() {
           ? () => setHintKey((k) => (k === opts.key ? null : k))
           : undefined
       }
-      className={cn(
-        "group/mcp relative flex items-center justify-between gap-2",
-        opts.enabled &&
-          "bg-emerald-500/10 data-[highlighted]:bg-emerald-500/20",
-      )}
+      className={
+        opts.enabled ? "relative text-primary font-medium" : "relative"
+      }
     >
       <span className="truncate">{opts.label}</span>
-      {opts.enabled ? (
-        <span className="flex size-4 shrink-0 items-center justify-center text-emerald-600 dark:text-emerald-400">
-          <HugeiconsIcon
-            icon={Tick02Icon}
-            className="size-4 group-data-[highlighted]/mcp:hidden"
-            strokeWidth={2}
-          />
-          <HugeiconsIcon
-            icon={Cancel01Icon}
-            className="hidden size-4 text-foreground group-data-[highlighted]/mcp:block"
-            strokeWidth={2}
-          />
-        </span>
-      ) : null}
+      {opts.enabled ? <CheckIcon className="ml-auto" /> : null}
       {opts.hint ? (
         <Tooltip open={hintKey === opts.key}>
           <TooltipTrigger asChild={true}>
@@ -260,28 +250,21 @@ export function McpComposerButton() {
             >
               <HugeiconsIcon
                 icon={McpServerIcon}
-                className="size-3.5"
+                className="size-[15px]"
                 strokeWidth={2}
               />
               <span>MCP</span>
+              <ArrowDownStandardIcon className="composer-pill-caret size-[15px]" />
             </button>
           </DropdownMenuTrigger>
-          <DropdownMenuContent align="start" className="w-64">
-            <div className="flex items-center justify-between pr-1">
-              <DropdownMenuLabel>MCP Servers</DropdownMenuLabel>
-              <button
-                type="button"
-                aria-label="Close"
-                onClick={() => setMenuOpen(false)}
-                className="rounded-md p-1 text-muted-foreground hover:bg-accent hover:text-foreground"
-              >
-                <HugeiconsIcon
-                  icon={Cancel01Icon}
-                  className="size-3.5"
-                  strokeWidth={2}
-                />
-              </button>
-            </div>
+          <DropdownMenuContent
+            side={side}
+            align="start"
+            sideOffset={2}
+            avoidCollisions={true}
+            className="unsloth-plus-menu mcp-menu w-[232px]"
+          >
+            <DropdownMenuLabel>MCP Servers</DropdownMenuLabel>
             {MCP_PRESETS.map((preset) => {
               const norm = normalizeMcpUrl(preset.url);
               return renderRow({
@@ -330,7 +313,7 @@ export function McpComposerButton() {
             >
               <HugeiconsIcon
                 icon={McpServerIcon}
-                className="size-3.5"
+                className="size-[15px]"
                 strokeWidth={2}
               />
               <span>MCP</span>
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 32b591d880..979d28a952 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -14,7 +14,6 @@ import {
   type PendingAttachment,
   type ThreadHistoryAdapter,
   type ThreadMessage,
-  WebSpeechDictationAdapter,
   type unstable_RemoteThreadListAdapter,
   useAui,
   useAuiEvent,
@@ -34,6 +33,7 @@ import {
 } from "react";
 import { extractText, getDocumentProxy } from "unpdf";
 import { toast } from "sonner";
+import { StudioWebSpeechDictationAdapter } from "./adapters/studio-web-speech-dictation-adapter";
 import { createOpenAIStreamAdapter } from "./api/chat-adapter";
 import {
   loadConnectionsEnabled,
@@ -190,7 +190,21 @@ class PDFAttachmentAdapter implements AttachmentAdapter {
 }
 
 class TextAttachmentAdapter implements AttachmentAdapter {
-  accept = "text/plain,text/markdown,text/csv,text/xml,text/json,text/css";
+  // MIME is unreliable for source files, so also match by extension
+  // (assistant-ui's fileMatchesAccept supports ".ext" entries). Covers
+  // svg, code, config and other plain-text formats; html keeps its own
+  // adapter below.
+  accept = [
+    "text/plain,text/markdown,text/csv,text/xml,text/json,text/css",
+    "application/json,application/xml,image/svg+xml",
+    ".txt,.text,.log,.md,.markdown,.mdx,.rst,.csv,.tsv",
+    ".json,.jsonl,.ndjson,.xml,.yaml,.yml,.toml,.ini,.cfg,.conf,.env,.properties",
+    ".css,.scss,.sass,.less,.svg",
+    ".js,.jsx,.mjs,.cjs,.ts,.tsx,.py,.pyi,.ipynb,.rb,.php,.go,.rs,.java,.kt,.kts,.scala,.swift",
+    ".c,.h,.cc,.cpp,.hpp,.cxx,.cs,.m,.mm",
+    ".sh,.bash,.zsh,.fish,.ps1,.bat,.lua,.pl,.pm,.r,.jl,.dart,.vue,.svelte,.astro",
+    ".sql,.graphql,.gql,.proto,.tf,.tfvars,.gradle,.dockerfile,.makefile,.cmake,.diff,.patch",
+  ].join(",");
 
   async add({ file }: { file: File }): Promise<PendingAttachment> {
     return {
@@ -962,8 +976,8 @@ function useStudioRuntimeAdapters(
 
   const dictation = useMemo(
     () =>
-      WebSpeechDictationAdapter.isSupported()
-        ? new WebSpeechDictationAdapter()
+      StudioWebSpeechDictationAdapter.isSupported()
+        ? new StudioWebSpeechDictationAdapter()
         : undefined,
     [],
   );
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 0165a3930e..1717152ba0 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -2,7 +2,6 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
-import { CodeToggleIcon } from "@/components/assistant-ui/code-toggle-icon";
 import {
   thinkEffortAriaLabel,
   thinkToggleAriaLabel,
@@ -13,6 +12,11 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { applyQwenThinkingParams } from "@/features/chat/utils/qwen-params";
@@ -23,27 +27,36 @@ import { getImageInputUnavailableReason } from "./utils/image-input-support";
 import { useAui } from "@assistant-ui/react";
 import {
   ArrowUpIcon,
-  DownloadIcon,
-  FileTextIcon,
+  CheckIcon,
+  Columns2Icon,
   GlobeIcon,
   HeadphonesIcon,
-  LightbulbIcon,
-  LightbulbOffIcon,
-  MicIcon,
   PlusIcon,
   SquareIcon,
   XIcon,
 } from "lucide-react";
-import { Image03Icon } from "@hugeicons/core-free-icons";
+import {
+  AttachmentIcon,
+  CodeIcon,
+  Download01Icon,
+  Folder01Icon,
+  FolderAddIcon,
+  Image03Icon,
+  McpServerIcon,
+  PencilRulerIcon,
+} from "@hugeicons/core-free-icons";
+import { useNavigate } from "@tanstack/react-router";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { toast } from "@/lib/toast";
+import { McpComposerButton } from "./mcp-composer-button";
+import { NewProjectDialog } from "./components/new-project-dialog";
+import { useChatProjects } from "./hooks/use-chat-projects";
 import { loadModel, validateModel } from "./api/chat-api";
 import {
   parseExternalModelId,
   providerTypeSupportsVision,
 } from "./external-providers";
 import { useExternalProvidersStore } from "./stores/external-providers-store";
-import { McpComposerButton } from "./mcp-composer-button";
 import {
   type ReasoningEffort,
   useChatRuntimeStore,
@@ -52,11 +65,11 @@ import {
   getExternalReasoningCapabilities,
   providerSupportsBuiltinCodeExecution,
   providerSupportsBuiltinImageGeneration,
-  providerSupportsBuiltinWebSearch,
   providerSupportsBuiltinWebFetch,
 } from "./provider-capabilities";
 import {
   type CompositionEvent,
+  type FC,
   type KeyboardEvent,
   type MutableRefObject,
   type ReactElement,
@@ -77,9 +90,9 @@ export type CompareMessagePart =
 export interface CompareHandle {
   append: (content: CompareMessagePart[]) => void;
   /** Append a user message without triggering generation. */
-  appendMessage: (content: CompareMessagePart[]) => Promise<string | null>;
+  appendMessage: (content: CompareMessagePart[]) => void;
   /** Trigger generation on the current thread (after appendMessage). */
-  startRun: (parentId?: string | null) => void;
+  startRun: () => void;
   cancel: () => void;
   isRunning: () => boolean;
   /** Returns a promise that resolves when the current or next run finishes. */
@@ -88,7 +101,49 @@ export interface CompareHandle {
 
 const IMAGE_ACCEPT = "image/jpeg,image/png,image/webp,image/gif";
 const MAX_IMAGE_SIZE = 20 * 1024 * 1024;
-const COMPARE_APPEND_MESSAGE_TIMEOUT_MS = 10_000;
+
+// Inlined to avoid a new icon dependency. Kept in sync with the main composer.
+const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={1.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M5.99977 9.00005L11.9998 15L17.9998 9" />
+  </svg>
+);
+
+const MicIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 256 256"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M128,176a48.05,48.05,0,0,0,48-48V64a48,48,0,0,0-96,0v64A48.05,48.05,0,0,0,128,176ZM96,64a32,32,0,0,1,64,0v64a32,32,0,0,1-64,0Zm40,143.6V232a8,8,0,0,1-16,0V207.6A80.11,80.11,0,0,1,48,128a8,8,0,0,1,16,0,64,64,0,0,0,128,0,8,8,0,0,1,16,0A80.11,80.11,0,0,1,136,207.6Z" />
+  </svg>
+);
+
+const BulbIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="-10.24 -10.24 1044.48 1044.48"
+    fill="currentColor"
+    stroke="currentColor"
+    strokeWidth={16.384}
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M511.984 0c-198.032 0-353.12 161.104-353.12 359.136 0 149.2 73.28 220.256 131.185 272.128 37.28 33.424 62.368 53.552 62.368 78.352v54.255c0 1.392.193 2.752.368 4.128h-.72v92.624c.016 97.712 63.2 163.376 161.072 163.376 94.464 0 158.944-65.664 158.944-163.376V768h-.928c.176-1.376.416-2.736.416-4.128v-54.255c0-37.76 28.032-60.592 70.528-97.696 57.504-50.208 123.023-112.688 123.023-252.784C865.136 161.104 710.016 0 511.983 0zm-1.215 960c-59.904 0-94.689-37.152-94.689-99.376l-.463-42.672C438.64 825.824 470 832 512 832c41.424 0 72.848-6.624 96.08-14.768v43.392c0 63.152-35.247 99.376-97.312 99.376zm189.248-396.288c-43.472 37.968-92.433 77.216-92.433 145.904v40.432c-15.183 8.48-43.183 18.56-96.127 18.56-55.569 0-81.92-9.856-95.024-17.473V709.6c0-54.608-42.688-89.297-83.68-126.017-54.32-48.672-109.873-103.84-109.873-224.464-.015-162.72 126.385-295.12 289.104-295.12 162.752 0 289.152 132.4 289.152 295.137 0 111.024-48.463 158.576-101.12 204.576z" />
+  </svg>
+);
 
 function isNativeComposing(event: Event) {
   return "isComposing" in event && (event as InputEvent).isComposing === true;
@@ -232,7 +287,6 @@ export function RegisterCompareHandle({
 }): ReactElement | null {
   const handlesRef = useContext(CompareHandlesContext);
   const aui = useAui();
-  const pendingAppendWaitersRef = useRef<Set<() => void>>(new Set());
 
   useEffect(() => {
     if (!handlesRef) {
@@ -245,76 +299,19 @@ export function RegisterCompareHandle({
         aui
           .thread()
           .append({ role: "user", content, createdAt: new Date() } as never),
-      appendMessage: (content) => {
-        const thread = aui.thread();
-        const beforeIds = new Set(
-          thread.getState().messages.map((message) => message.id),
-        );
-        thread.append({
-          role: "user",
-          content,
-          createdAt: new Date(),
-          startRun: false,
-        } as never);
-
-        const findAppendedUserMessageId = () => {
-          const messages = thread.getState().messages;
-          for (let index = messages.length - 1; index >= 0; index -= 1) {
-            const message = messages[index];
-            if (beforeIds.has(message.id) || message.role !== "user") {
-              continue;
-            }
-            return message.id;
-          }
-          return null;
-        };
-
-        const appendedId = findAppendedUserMessageId();
-        if (appendedId) {
-          return Promise.resolve(appendedId);
-        }
-
-        return new Promise<string | null>((resolve) => {
-          const startedAt = Date.now();
-          let settled = false;
-          let timer: number | null = null;
-          let cancel: (() => void) | null = null;
-          const cleanup = () => {
-            if (timer !== null) {
-              window.clearTimeout(timer);
-              timer = null;
-            }
-            if (cancel) {
-              pendingAppendWaitersRef.current.delete(cancel);
-            }
-          };
-          const finish = (messageId: string | null) => {
-            if (settled) return;
-            settled = true;
-            cleanup();
-            resolve(messageId);
-          };
-          cancel = () => finish(null);
-          const poll = () => {
-            timer = null;
-            const messageId = findAppendedUserMessageId();
-            if (
-              messageId ||
-              Date.now() - startedAt >= COMPARE_APPEND_MESSAGE_TIMEOUT_MS
-            ) {
-              finish(messageId);
-              return;
-            }
-            timer = window.setTimeout(poll, 16);
-          };
-          pendingAppendWaitersRef.current.add(cancel);
-          timer = window.setTimeout(poll, 0);
-        });
-      },
-      startRun: (parentId) => {
+      appendMessage: (content) =>
+        aui
+          .thread()
+          .append({
+            role: "user",
+            content,
+            createdAt: new Date(),
+            startRun: false,
+          } as never),
+      startRun: () => {
         const msgs = aui.thread().getState().messages;
-        const fallbackId = msgs.length > 0 ? msgs[msgs.length - 1].id : null;
-        aui.thread().startRun({ parentId: parentId ?? fallbackId });
+        const lastId = msgs.length > 0 ? msgs[msgs.length - 1].id : null;
+        aui.thread().startRun({ parentId: lastId });
       },
       cancel: () => aui.thread().cancelRun(),
       isRunning: () => aui.thread().getState().isRunning,
@@ -332,10 +329,6 @@ export function RegisterCompareHandle({
         }),
     };
     return () => {
-      for (const cancel of pendingAppendWaitersRef.current) {
-        cancel();
-      }
-      pendingAppendWaitersRef.current.clear();
       delete currentHandles[name];
     };
   }, [handlesRef, name, aui]);
@@ -381,15 +374,37 @@ type CompareModelSelection = {
   ggufVariant?: string;
 };
 
+// Tool icon plus an X overlay the CSS reveals on hover when the pill is active.
+function PillGlyph({ children }: { children: ReactNode }) {
+  return (
+    <span className="composer-pill-glyph">
+      {children}
+      <XIcon className="composer-pill-x" />
+    </span>
+  );
+}
+
 export function SharedComposer({
   handlesRef,
   model1,
   model2,
+  onExitCompare,
 }: {
   handlesRef: CompareHandles;
   model1?: CompareModelSelection;
   model2?: CompareModelSelection;
+  onExitCompare?: () => void;
 }): ReactElement {
+  const navigate = useNavigate();
+  // Exit compare. Uses the parent's restore handler, or a fresh chat when
+  // compare was opened by direct URL.
+  const handleExitCompare = useCallback(() => {
+    if (onExitCompare) {
+      onExitCompare();
+      return;
+    }
+    navigate({ to: "/chat" });
+  }, [navigate, onExitCompare]);
   const [text, setText] = useState("");
   const [running, setRunning] = useState(false);
   const [comparing, setComparing] = useState(false);
@@ -400,6 +415,7 @@ export function SharedComposer({
   } | null>(null);
   const [dragging, setDragging] = useState(false);
   const [isComposing, setIsComposing] = useState(false);
+  const [newProjectOpen, setNewProjectOpen] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const composingRef = useRef(false);
   const stuckImeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -452,6 +468,19 @@ export function SharedComposer({
   );
   const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
   const setArtifactsEnabled = useChatRuntimeStore((s) => s.setArtifactsEnabled);
+  const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  const setMcpEnabledForChat = useChatRuntimeStore(
+    (s) => s.setMcpEnabledForChat,
+  );
+  // Three most recently updated projects for the quick-access submenu.
+  const { projects } = useChatProjects();
+  const recentProjects = [...projects]
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, 3);
+  const openProject = (projectId: string) => {
+    useChatRuntimeStore.getState().setActiveProjectId(projectId);
+    navigate({ to: "/chat", search: { project: projectId } });
+  };
   const webFetchToolsEnabled = useChatRuntimeStore(
     (s) => s.webFetchToolsEnabled,
   );
@@ -530,6 +559,10 @@ export function SharedComposer({
   const reasoningDisabled = !modelLoaded || !effectiveSupportsReasoning;
   const showReasoningControl =
     effectiveSupportsReasoning || effectiveReasoningAlwaysOn;
+  const isEffort = effectiveReasoningStyle === "reasoning_effort";
+  const thinkingActiveLook = isEffort
+    ? reasoningLockedOn || (effectiveReasoningVisualEnabled && !reasoningDisabled)
+    : reasoningLockedOn || (effectiveReasoningEnabled && !reasoningDisabled);
   // Two-pill gating: Search pill lights up when the runtime has either
   // a local tool runtime (supportsTools, gives us our Code/python + local
   // web_search) OR a server-side web_search the provider runs for us
@@ -569,24 +602,34 @@ export function SharedComposer({
   // and gate strictly on the provider builtin support.
   const isGeminiImageTier =
     isExternalGemini && supportsBuiltinImageGeneration;
+  // Disable only when a loaded model lacks the capability; with no model the
+  // tool can still be pre-selected and reflected, matching the + menu.
   const searchDisabled =
-    !modelLoaded ||
+    modelLoaded &&
     (isGeminiImageTier
       ? !supportsBuiltinWebSearch
       : !(supportsTools || supportsBuiltinWebSearch));
   const codeDisabled =
-    !modelLoaded ||
-    (isGeminiImageTier
-      ? true
-      : !(supportsTools || supportsBuiltinCodeExecution)) ||
+    (modelLoaded &&
+      (isGeminiImageTier
+        ? true
+        : !(supportsTools || supportsBuiltinCodeExecution))) ||
     imageModeDisablesCode;
   // Images pill is only ever lit on OpenAI cloud's Responses-API models
   // and Gemini Nano Banana family. No local tool runtime fallback.
   const showImagePill = supportsBuiltinImageGeneration;
-  const artifactDisabled = !modelLoaded;
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
   const showWebFetchPill = supportsBuiltinWebFetch;
+  // With more than 4 pills showing, collapse them to icons only to cut clutter.
+  // Compare, Search and Code always show; the rest are conditional.
+  const pillsCompact =
+    3 +
+      (showImagePill ? 1 : 0) +
+      (showWebFetchPill ? 1 : 0) +
+      (artifactsEnabled ? 1 : 0) +
+      (mcpEnabledForChat ? 1 : 0) >
+    4;
   // Backwards-compatible alias for any other call site that may still
   // reference `toolsDisabled` (rare; both pills used it before).
   const toolsDisabled = codeDisabled;
@@ -770,8 +813,6 @@ export function SharedComposer({
         : null;
 
       function modelDisplayName(id: string): string {
-        const external = parseExternalModelId(id);
-        if (external) return external.modelId;
         const parts = id.split("/");
         return parts[parts.length - 1] || id;
       }
@@ -780,76 +821,6 @@ export function SharedComposer({
       async function ensureModelLoaded(
         sel: CompareModelSelection,
       ): Promise<string> {
-        const external = parseExternalModelId(sel.id);
-        if (external) {
-          const externalStore = useExternalProvidersStore.getState();
-          if (!externalStore.connectionsEnabled) {
-            throw new Error(
-              "Connections are disabled. Turn on Enable connections in Settings -> Connections to use hosted models.",
-            );
-          }
-          const provider = externalStore.providers.find(
-            (p) => p.id === external.providerId,
-          );
-          if (!provider) {
-            throw new Error(
-              "Connection not found. Open Settings -> Connections and add it again.",
-            );
-          }
-
-          const reasoningCaps = getExternalReasoningCapabilities(
-            provider.providerType,
-            external.modelId,
-            {
-              isReasoningProvider: provider.isReasoningModel === true,
-              baseUrl: provider.baseUrl ?? null,
-            },
-          );
-          const supportsBuiltinWebSearch = providerSupportsBuiltinWebSearch(
-            provider.providerType,
-            external.modelId,
-            provider.baseUrl,
-          );
-          const supportsBuiltinCodeExecution =
-            providerSupportsBuiltinCodeExecution(
-              provider.providerType,
-              external.modelId,
-              provider.baseUrl,
-            );
-          const supportsBuiltinImageGeneration =
-            providerSupportsBuiltinImageGeneration(
-              provider.providerType,
-              external.modelId,
-              provider.baseUrl,
-            );
-          const supportsBuiltinWebFetch = providerSupportsBuiltinWebFetch(
-            provider.providerType,
-          );
-          const currentStore = useChatRuntimeStore.getState();
-          currentStore.setCheckpoint(sel.id, null);
-          useChatRuntimeStore.setState({
-            activeGgufVariant: null,
-            ggufContextLength: null,
-            ggufMaxContextLength: null,
-            ggufNativeContextLength: null,
-            activeNativePathToken: null,
-            supportsReasoning: reasoningCaps.supportsReasoning,
-            reasoningAlwaysOn: reasoningCaps.reasoningAlwaysOn,
-            reasoningStyle: reasoningCaps.reasoningStyle,
-            supportsReasoningOff: reasoningCaps.supportsReasoningOff,
-            reasoningEffortLevels: reasoningCaps.reasoningEffortLevels,
-            supportsPreserveThinking: false,
-            supportsTools: false,
-            supportsBuiltinWebSearch,
-            supportsBuiltinCodeExecution,
-            supportsBuiltinImageGeneration,
-            supportsBuiltinWebFetch,
-            loadedIsMultimodal:
-              providerTypeSupportsVision(provider.providerType) === true,
-          });
-          return "external";
-        }
-
         const currentStore = useChatRuntimeStore.getState();
         const isAlreadyActive =
           currentStore.params.checkpoint === sel.id &&
@@ -932,19 +903,9 @@ export function SharedComposer({
       const handle1 = handlesRef.current["model1"];
       const handle2 = handlesRef.current["model2"];
 
-      // Show user messages immediately on both sides and keep the ids
-      // so delayed model loads can start the run from the intended turn.
-      const [parentId1, parentId2] = await Promise.all([
-        handle1 ? handle1.appendMessage(content) : Promise.resolve(null),
-        handle2 ? handle2.appendMessage(content) : Promise.resolve(null),
-      ]);
-      if ((handle1 && !parentId1) || (handle2 && !parentId2)) {
-        toast.error("Compare failed", {
-          description:
-            "The prompt could not be added to both compare panes. Try sending it again.",
-        });
-        return;
-      }
+      // Show user messages immediately on both sides
+      if (handle1) handle1.appendMessage(content);
+      if (handle2) handle2.appendMessage(content);
 
       const name1 = model1?.id ? modelDisplayName(model1.id) : "";
       const name2 = model2?.id ? modelDisplayName(model2.id) : "";
@@ -966,7 +927,7 @@ export function SharedComposer({
             duration: Infinity,
           });
           const done = handle1.waitForRunEnd();
-          handle1.startRun(parentId1);
+          handle1.startRun();
           await done;
         }
 
@@ -989,7 +950,7 @@ export function SharedComposer({
             duration: Infinity,
           });
           const done = handle2.waitForRunEnd();
-          handle2.startRun(parentId2);
+          handle2.startRun();
           await done;
         }
 
@@ -1050,7 +1011,7 @@ export function SharedComposer({
 
   return (
     <div
-      className={`chat-composer-surface ${dragging ? "border-ring bg-accent/50" : ""}`}
+      className="chat-composer-surface"
       onDragOver={(e) => {
         if (isTauri) return;
         e.preventDefault();
@@ -1066,6 +1027,17 @@ export function SharedComposer({
         addFiles(e.dataTransfer.files);
       }}
     >
+      {/* Gemini-style drop affordance, mirrored from the single composer. */}
+      <div
+        className={`pointer-events-none absolute inset-0 z-20 flex flex-col items-center justify-center gap-1 overflow-hidden rounded-[32px] bg-background/90 backdrop-blur-sm transition-opacity duration-150 dark:bg-card/90 ${dragging ? "opacity-100" : "opacity-0"}`}
+      >
+        <HugeiconsIcon
+          icon={AttachmentIcon}
+          strokeWidth={2}
+          className="size-6 text-primary"
+        />
+        <span className="text-sm font-medium text-primary">Drop files here</span>
+      </div>
       {(pendingImages.length > 0 || pendingAudio) && (
         <div className="mb-2 flex w-full flex-row flex-wrap items-center gap-2 px-1.5 pt-0.5 pb-1">
           {pendingImages.map(({ id, file }) => (
@@ -1126,7 +1098,10 @@ export function SharedComposer({
         dir="auto"
       />
       <div className="composer-action-wrapper">
-        <div className="flex items-center gap-0.5">
+        <div
+          className="flex items-center gap-0.5"
+          data-pill-compact={pillsCompact ? "true" : undefined}
+        >
           <input
             ref={fileInputRef}
             type="file"
@@ -1138,131 +1113,440 @@ export function SharedComposer({
               e.target.value = "";
             }}
           />
-          <TooltipIconButton
-            tooltip="Add Attachment"
-            side="bottom"
-            variant="ghost"
-            size="icon"
-            className="size-8.5 rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:hover:bg-muted-foreground/30"
-            onClick={() => {
-              // The picker accepts both image and audio. Don't gate the
-              // button on image-availability — addFiles still filters
-              // image files per-file when the loaded model can't take
-              // them, while audio attach always works.
-              fileInputRef.current?.click();
+          <input
+            ref={audioInputRef}
+            type="file"
+            accept={AUDIO_ACCEPT}
+            className="hidden"
+            onChange={(e) => {
+              addFiles(e.target.files);
+              e.target.value = "";
             }}
-            aria-label="Add Attachment"
-          >
-            <PlusIcon className="size-5 stroke-[1.5px]" />
-          </TooltipIconButton>
-          {activeModel?.hasAudioInput && (
-            <>
-              <input
-                ref={audioInputRef}
-                type="file"
-                accept={AUDIO_ACCEPT}
-                className="hidden"
-                onChange={(e) => {
-                  addFiles(e.target.files);
-                  e.target.value = "";
-                }}
-              />
-              <TooltipIconButton
-                tooltip="Upload audio"
-                side="bottom"
-                variant="ghost"
-                size="icon"
-                className="size-8.5 rounded-full p-1 text-muted-foreground hover:bg-muted-foreground/15"
-                onClick={() => audioInputRef.current?.click()}
-                aria-label="Upload audio"
+          />
+          <NewProjectDialog
+            open={newProjectOpen}
+            onOpenChange={setNewProjectOpen}
+          />
+          {/* Same + side menu as the single-chat composer (ComposerToolsMenu),
+              wired to the compare composer's own file/audio inputs and tools. */}
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild={true}>
+              <button
+                type="button"
+                aria-label="Tools and attachments"
+                className="unsloth-composer-plus"
               >
-                <HeadphonesIcon className="size-4.5 stroke-[1.5px]" />
-              </TooltipIconButton>
-            </>
+                <PlusIcon className="size-[22px] stroke-[1.75px]" />
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent
+              side="top"
+              align="start"
+              sideOffset={2}
+              avoidCollisions={true}
+              className="unsloth-plus-menu w-[212px]"
+              onCloseAutoFocus={(event) => event.preventDefault()}
+            >
+              <DropdownMenuItem onSelect={() => fileInputRef.current?.click()}>
+                <HugeiconsIcon icon={AttachmentIcon} strokeWidth={2} />
+                Add photos &amp; files
+              </DropdownMenuItem>
+              {activeModel?.hasAudioInput && (
+                <DropdownMenuItem
+                  onSelect={() => audioInputRef.current?.click()}
+                >
+                  <HeadphonesIcon />
+                  Upload audio
+                </DropdownMenuItem>
+              )}
+              <DropdownMenuItem
+                disabled={searchDisabled}
+                className={
+                  toolsEnabled && !searchDisabled
+                    ? "text-primary font-medium"
+                    : undefined
+                }
+                onSelect={() => {
+                  const next = !toolsEnabled;
+                  setToolsEnabled(next);
+                  // Mirror the Search pill: Kimi forbids search + thinking together.
+                  if (isKimiExternal) {
+                    setReasoningEnabled(!next, { persist: false });
+                    applyQwenThinkingParams(!next);
+                  }
+                }}
+              >
+                <GlobeIcon />
+                Web search
+                {toolsEnabled && !searchDisabled ? (
+                  <CheckIcon className="ml-auto" />
+                ) : null}
+              </DropdownMenuItem>
+              <DropdownMenuItem
+                disabled={codeDisabled}
+                className={
+                  codeToolsEnabled && !codeDisabled
+                    ? "text-primary font-medium"
+                    : undefined
+                }
+                onSelect={() => setCodeToolsEnabled(!codeToolsEnabled)}
+              >
+                <HugeiconsIcon
+                  icon={CodeIcon}
+                  strokeWidth={2}
+                  className="size-[1.175rem]!"
+                />
+                Code
+                {codeToolsEnabled && !codeDisabled ? (
+                  <CheckIcon className="ml-auto" />
+                ) : null}
+              </DropdownMenuItem>
+              {showImagePill && (
+                <DropdownMenuItem
+                  disabled={imageDisabled}
+                  className={
+                    imageToolsEnabled && !imageDisabled
+                      ? "text-primary font-medium"
+                      : undefined
+                  }
+                  onSelect={() => setImageToolsEnabled(!imageToolsEnabled)}
+                >
+                  <HugeiconsIcon icon={Image03Icon} strokeWidth={2} />
+                  Images
+                  {imageToolsEnabled && !imageDisabled ? (
+                    <CheckIcon className="ml-auto" />
+                  ) : null}
+                </DropdownMenuItem>
+              )}
+              <DropdownMenuSeparator />
+              <DropdownMenuItem
+                className={
+                  artifactsEnabled ? "text-primary font-medium" : undefined
+                }
+                onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+              >
+                <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
+                Canvas
+                {artifactsEnabled ? <CheckIcon className="ml-auto" /> : null}
+              </DropdownMenuItem>
+              <DropdownMenuItem
+                disabled={!supportsTools}
+                className={
+                  mcpEnabledForChat ? "text-primary font-medium" : undefined
+                }
+                onSelect={() => setMcpEnabledForChat(!mcpEnabledForChat)}
+              >
+                <HugeiconsIcon icon={McpServerIcon} strokeWidth={2} />
+                MCP
+                {mcpEnabledForChat ? <CheckIcon className="ml-auto" /> : null}
+              </DropdownMenuItem>
+              {/* RAG hidden temporarily */}
+              {/* Always active: this menu only renders in compare mode.
+                  Ticked like Web search/Code; click toggles it off. */}
+              <DropdownMenuItem
+                className="text-primary font-medium"
+                onSelect={handleExitCompare}
+              >
+                <Columns2Icon />
+                Compare chat
+                <CheckIcon className="ml-auto" />
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger>
+                  <HugeiconsIcon icon={Folder01Icon} strokeWidth={2} />
+                  Projects
+                </DropdownMenuSubTrigger>
+                <DropdownMenuSubContent className="unsloth-plus-menu w-[200px]">
+                  <DropdownMenuItem onSelect={() => setNewProjectOpen(true)}>
+                    <HugeiconsIcon icon={FolderAddIcon} strokeWidth={2} />
+                    New project
+                  </DropdownMenuItem>
+                  <DropdownMenuLabel>Recents</DropdownMenuLabel>
+                  {recentProjects.length > 0 ? (
+                    recentProjects.map((project) => (
+                      <DropdownMenuItem
+                        key={project.id}
+                        onSelect={() => openProject(project.id)}
+                      >
+                        <HugeiconsIcon icon={Folder01Icon} strokeWidth={2} />
+                        <span className="truncate">{project.name}</span>
+                      </DropdownMenuItem>
+                    ))
+                  ) : (
+                    <DropdownMenuItem disabled={true}>
+                      No recent projects
+                    </DropdownMenuItem>
+                  )}
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+            </DropdownMenuContent>
+          </DropdownMenu>
+          {/* Active in compare mode; sits first. Click to exit back to single chat. */}
+          <button
+            type="button"
+            onClick={handleExitCompare}
+            className="composer-pill-btn"
+            data-active="true"
+            data-keep-label="true"
+            aria-label="Exit compare chat"
+          >
+            <PillGlyph>
+              <Columns2Icon className="size-[14px]" />
+            </PillGlyph>
+            <span>Compare</span>
+          </button>
+          <button
+            type="button"
+            disabled={searchDisabled}
+            onClick={() => {
+              const next = !toolsEnabled;
+              setToolsEnabled(next);
+              // Kimi's $web_search builtin requires thinking=disabled
+              // (https://platform.kimi.ai/docs/guide/use-web-search). Toggle
+              // the Think pill off when Search is on, mirroring the backend.
+              if (isKimiExternal) {
+                setReasoningEnabled(!next, { persist: false });
+                applyQwenThinkingParams(!next);
+              }
+            }}
+            className="composer-pill-btn"
+            data-active={toolsEnabled && !searchDisabled ? "true" : "false"}
+            aria-label={
+              toolsEnabled ? "Disable web search" : "Enable web search"
+            }
+          >
+            <PillGlyph>
+              <GlobeIcon className="size-[15px]" />
+            </PillGlyph>
+            <span>Search</span>
+          </button>
+          <button
+            type="button"
+            disabled={codeDisabled}
+            onClick={() => setCodeToolsEnabled(!codeToolsEnabled)}
+            className="composer-pill-btn"
+            data-active={codeToolsEnabled && !codeDisabled ? "true" : "false"}
+            aria-label={
+              codeToolsEnabled
+                ? "Disable code execution"
+                : "Enable code execution"
+            }
+          >
+            <PillGlyph>
+              <HugeiconsIcon
+                icon={CodeIcon}
+                className="size-[18.5px]"
+                strokeWidth={2}
+              />
+            </PillGlyph>
+            <span>Code</span>
+          </button>
+          {showImagePill && (
+            <button
+              type="button"
+              disabled={imageDisabled}
+              onClick={() => setImageToolsEnabled(!imageToolsEnabled)}
+              className="composer-pill-btn"
+              data-active={
+                imageToolsEnabled && !imageDisabled ? "true" : "false"
+              }
+              aria-label={
+                imageToolsEnabled
+                  ? "Disable image generation"
+                  : "Enable image generation"
+              }
+            >
+              <PillGlyph>
+                <HugeiconsIcon
+                  icon={Image03Icon}
+                  className="size-3.5"
+                  strokeWidth={2}
+                />
+              </PillGlyph>
+              <span>Images</span>
+            </button>
           )}
+          {showWebFetchPill && (
+            <button
+              type="button"
+              disabled={webFetchDisabled}
+              onClick={() => setWebFetchToolsEnabled(!webFetchToolsEnabled)}
+              className="composer-pill-btn"
+              data-active={
+                webFetchToolsEnabled && !webFetchDisabled ? "true" : "false"
+              }
+              aria-label={
+                webFetchToolsEnabled ? "Disable URL fetch" : "Enable URL fetch"
+              }
+            >
+              <PillGlyph>
+                <HugeiconsIcon icon={Download01Icon} className="size-3.5" />
+              </PillGlyph>
+              <span>Fetch</span>
+            </button>
+          )}
+          {artifactsEnabled ? (
+            <button
+              type="button"
+              onClick={() => setArtifactsEnabled(false)}
+              className="composer-pill-btn"
+              data-active="true"
+              aria-label="Disable canvas"
+            >
+              <PillGlyph>
+                <HugeiconsIcon
+                  icon={PencilRulerIcon}
+                  className="size-[15.5px]"
+                  strokeWidth={2}
+                />
+              </PillGlyph>
+              <span>Canvas</span>
+            </button>
+          ) : null}
+          {mcpEnabledForChat ? <McpComposerButton side="top" /> : null}
+        </div>
+        {/* mr-0.5 matches the send button inset from the edge in normal chat;
+            gap-1.5 matches its control spacing. */}
+        <div className="ml-auto mr-0.5 flex items-center gap-1.5">
           {showReasoningControl ? (
-            effectiveReasoningStyle === "reasoning_effort" ? (
+            isEffort || supportsPreserveThinking ? (
               <DropdownMenu>
                 <DropdownMenuTrigger asChild={true}>
                   <button
                     type="button"
                     disabled={reasoningDisabled}
-                    className={cn(
-                      "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-                      reasoningDisabled
-                        ? "cursor-not-allowed opacity-40"
-                        : effectiveReasoningVisualEnabled
-                          ? "text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                          : "hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-                    )}
+                    className="unsloth-thinking-pill"
+                    data-active={thinkingActiveLook ? "true" : "false"}
                     aria-label={thinkEffortAriaLabel({
                       modelLoaded,
                       reasoningDisabled,
                       reasoningEffort,
                     })}
                   >
-                    {effectiveReasoningVisualEnabled ? (
-                      <LightbulbIcon className="size-3.5" />
-                    ) : (
-                      <LightbulbOffIcon className="size-3.5" />
-                    )}
-                    <span>
-                      Think:{" "}
-                      {effectiveReasoningVisualEnabled
-                        ? formatReasoningEffortLabel(
-                            reasoningEffort,
-                            externalSelection?.modelId,
-                          )
-                        : formatReasoningDisabledLabel(
+                    <BulbIcon className="size-[15.5px]" />
+                    {thinkingActiveLook ? (
+                      <span>
+                        {isEffort
+                          ? `Thinking · ${formatReasoningEffortLabel(
+                              reasoningEffort,
+                              externalSelection?.modelId,
+                            )}`
+                          : "Thinking"}
+                      </span>
+                    ) : null}
+                    <ArrowDownStandardIcon className="size-[15px]" />
+                  </button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent
+                  side="top"
+                  align="end"
+                  className="unsloth-plus-menu min-w-44"
+                >
+                  {isEffort ? (
+                    <>
+                      {effectiveSupportsReasoningOff && (
+                        <DropdownMenuItem
+                          onSelect={() => {
+                            setReasoningEnabled(false);
+                            applyQwenThinkingParams(false);
+                            // Preserve thinking needs thinking on, so turn it off too.
+                            setPreserveThinking(false);
+                          }}
+                        >
+                          <CheckIcon
+                            className={cn(
+                              "unsloth-tick size-4",
+                              effectiveReasoningVisualEnabled && "opacity-0",
+                            )}
+                          />
+                          {formatReasoningDisabledLabel(
                             effectiveSupportsReasoningOff,
                             isExternalOpenAIReasoning,
                             checkpoint,
                           )}
-                    </span>
-                  </button>
-                </DropdownMenuTrigger>
-                <DropdownMenuContent align="end">
-                  {effectiveSupportsReasoningOff && (
-                    <DropdownMenuItem
-                      onSelect={() => {
-                        setReasoningEnabled(false);
-                        applyQwenThinkingParams(false);
-                      }}
-                    >
-                      {formatReasoningDisabledLabel(
-                        effectiveSupportsReasoningOff,
-                        isExternalOpenAIReasoning,
-                        checkpoint,
+                        </DropdownMenuItem>
                       )}
-                      {!effectiveReasoningVisualEnabled ? " \u2713" : ""}
-                    </DropdownMenuItem>
-                  )}
-                  {effectiveReasoningEffortLevels
-                    .filter((level) => level !== "none")
-                    .map((level) => (
+                      {effectiveReasoningEffortLevels
+                        .filter((level) => level !== "none")
+                        .map((level) => (
+                          <DropdownMenuItem
+                            key={level}
+                            onSelect={() => {
+                              setReasoningEffort(level);
+                              setReasoningEnabled(true);
+                              applyQwenThinkingParams(true);
+                              // Mutual exclusion: turning thinking on for a
+                              // Kimi model forces the web_search builtin off.
+                              if (isKimiExternal && toolsEnabled) {
+                                setToolsEnabled(false, { persist: false });
+                              }
+                            }}
+                          >
+                            <CheckIcon
+                              className={cn(
+                                "unsloth-tick size-4",
+                                !(
+                                  effectiveReasoningVisualEnabled &&
+                                  reasoningEffort === level
+                                ) && "opacity-0",
+                              )}
+                            />
+                            {formatReasoningEffortLabel(
+                              level,
+                              externalSelection?.modelId,
+                            )}
+                          </DropdownMenuItem>
+                        ))}
+                    </>
+                  ) : (
+                    effectiveSupportsReasoningOff &&
+                    !reasoningLockedOn && (
                       <DropdownMenuItem
-                        key={level}
                         onSelect={() => {
-                          setReasoningEffort(level);
-                          setReasoningEnabled(true);
-                          applyQwenThinkingParams(true);
-                          // Mutual exclusion: turning thinking on for a
-                          // Kimi model forces the web_search builtin off.
-                          if (isKimiExternal && toolsEnabled) {
+                          const next = !reasoningEnabled;
+                          setReasoningEnabled(next);
+                          applyQwenThinkingParams(next);
+                          // Preserve thinking cannot run without thinking.
+                          if (!next) setPreserveThinking(false);
+                          if (isKimiExternal && next && toolsEnabled) {
                             setToolsEnabled(false, { persist: false });
                           }
                         }}
                       >
-                        {formatReasoningEffortLabel(
-                          level,
-                          externalSelection?.modelId,
-                        )}
-                        {effectiveReasoningVisualEnabled &&
-                        reasoningEffort === level
-                          ? " \u2713"
-                          : ""}
+                        <CheckIcon
+                          className={cn(
+                            "unsloth-tick size-4",
+                            !effectiveReasoningEnabled && "opacity-0",
+                          )}
+                        />
+                        Thinking
                       </DropdownMenuItem>
-                    ))}
+                    )
+                  )}
+                  {supportsPreserveThinking && (
+                    <DropdownMenuItem
+                      disabled={!modelLoaded}
+                      onSelect={(e) => {
+                        e.preventDefault();
+                        const next = !preserveThinking;
+                        setPreserveThinking(next);
+                        // Preserve thinking requires thinking on.
+                        if (next) {
+                          setReasoningEnabled(true);
+                          applyQwenThinkingParams(true);
+                        }
+                      }}
+                    >
+                      <CheckIcon
+                        className={cn(
+                          "unsloth-tick size-4",
+                          !preserveThinking && "opacity-0",
+                        )}
+                      />
+                      Preserve thinking
+                    </DropdownMenuItem>
+                  )}
                 </DropdownMenuContent>
               </DropdownMenu>
             ) : (
@@ -1287,16 +1571,8 @@ export function SharedComposer({
                     setToolsEnabled(false, { persist: false });
                   }
                 }}
-                className={cn(
-                  "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-                  reasoningLockedOn
-                    ? "cursor-not-allowed text-primary"
-                    : reasoningDisabled
-                      ? "cursor-not-allowed opacity-40"
-                      : effectiveReasoningEnabled
-                        ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                        : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-                )}
+                className="unsloth-thinking-pill"
+                data-active={thinkingActiveLook ? "true" : "false"}
                 aria-label={thinkToggleAriaLabel({
                   reasoningLockedOn,
                   modelLoaded,
@@ -1304,141 +1580,13 @@ export function SharedComposer({
                   effectiveReasoningEnabled,
                 })}
               >
-                {reasoningLockedOn ||
-                (effectiveReasoningEnabled && !reasoningDisabled) ? (
-                  <LightbulbIcon className="size-3.5" />
-                ) : (
-                  <LightbulbOffIcon className="size-3.5" />
-                )}
-                <span>Think</span>
+                <PillGlyph>
+                  <BulbIcon className="size-[15.5px]" />
+                </PillGlyph>
+                {thinkingActiveLook ? <span>Thinking</span> : null}
               </button>
             )
           ) : null}
-          {supportsPreserveThinking && (
-            <button
-              type="button"
-              disabled={!modelLoaded}
-              onClick={() => setPreserveThinking(!preserveThinking)}
-              className={cn(
-                "flex items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors",
-                !modelLoaded
-                  ? "cursor-not-allowed opacity-40"
-                  : preserveThinking
-                    ? "cursor-pointer text-primary hover:bg-primary/10 dark:hover:bg-white/[0.08]"
-                    : "cursor-pointer hover:bg-primary/10 dark:hover:bg-white/[0.08]",
-              )}
-              aria-label={
-                preserveThinking
-                  ? "Disable preserve think"
-                  : "Enable preserve think"
-              }
-            >
-              {preserveThinking && modelLoaded ? (
-                <LightbulbIcon className="size-3.5" />
-              ) : (
-                <LightbulbOffIcon className="size-3.5" />
-              )}
-              <span>Preserve Think</span>
-            </button>
-          )}
-          <button
-            type="button"
-            disabled={searchDisabled}
-            onClick={() => {
-              const next = !toolsEnabled;
-              setToolsEnabled(next);
-              // Kimi's $web_search builtin requires thinking=disabled
-              // (https://platform.kimi.ai/docs/guide/use-web-search).
-              // Toggle the Think pill off when Search comes on, and
-              // back on when Search goes off — mutual exclusion that
-              // mirrors what the backend enforces.
-              if (isKimiExternal) {
-                setReasoningEnabled(!next, { persist: false });
-                applyQwenThinkingParams(!next);
-              }
-            }}
-            className="composer-pill-btn"
-            data-active={toolsEnabled && !searchDisabled ? "true" : "false"}
-            aria-label={
-              toolsEnabled ? "Disable web search" : "Enable web search"
-            }
-          >
-            <GlobeIcon className="size-3.5" />
-            <span>Search</span>
-          </button>
-          <button
-            type="button"
-            disabled={codeDisabled}
-            onClick={() => setCodeToolsEnabled(!codeToolsEnabled)}
-            className="composer-pill-btn"
-            data-active={codeToolsEnabled && !codeDisabled ? "true" : "false"}
-            aria-label={
-              codeToolsEnabled
-                ? "Disable code execution"
-                : "Enable code execution"
-            }
-          >
-            <CodeToggleIcon className="size-3.5" />
-            <span>Code</span>
-          </button>
-          {showImagePill && (
-            <button
-              type="button"
-              disabled={imageDisabled}
-              onClick={() => setImageToolsEnabled(!imageToolsEnabled)}
-              className="composer-pill-btn"
-              data-active={
-                imageToolsEnabled && !imageDisabled ? "true" : "false"
-              }
-              aria-label={
-                imageToolsEnabled
-                  ? "Disable image generation"
-                  : "Enable image generation"
-              }
-            >
-              <HugeiconsIcon
-                icon={Image03Icon}
-                className="size-3.5"
-                strokeWidth={2}
-              />
-              <span>Images</span>
-            </button>
-          )}
-          <button
-            type="button"
-            disabled={artifactDisabled}
-            onClick={() => setArtifactsEnabled(!artifactsEnabled)}
-            className="composer-pill-btn"
-            data-active={
-              artifactsEnabled && !artifactDisabled ? "true" : "false"
-            }
-            aria-label={
-              artifactsEnabled ? "Disable artifacts" : "Enable artifacts"
-            }
-          >
-            <FileTextIcon className="size-3.5" />
-            <span>Artifacts</span>
-          </button>
-          <McpComposerButton />
-          {showWebFetchPill && (
-            <button
-              type="button"
-              disabled={webFetchDisabled}
-              onClick={() => setWebFetchToolsEnabled(!webFetchToolsEnabled)}
-              className="composer-pill-btn"
-              data-active={
-                webFetchToolsEnabled && !webFetchDisabled ? "true" : "false"
-              }
-              aria-label={
-                webFetchToolsEnabled ? "Disable URL fetch" : "Enable URL fetch"
-              }
-            >
-              <DownloadIcon className="size-3.5" />
-              <span>Fetch</span>
-            </button>
-          )}
-        </div>
-        <div className="flex items-center gap-1">
           {dictationSupported && (
             <>
               {!isDictating ? (
@@ -1473,7 +1621,7 @@ export function SharedComposer({
               type="button"
               variant="default"
               size="icon"
-              className="size-8 rounded-full"
+              className="ml-1.5 size-8 rounded-full"
               onClick={stop}
             >
               <SquareIcon className="size-3 fill-current" />
@@ -1484,12 +1632,12 @@ export function SharedComposer({
               side="bottom"
               variant="default"
               size="icon"
-              className="size-8 rounded-full"
+              className="ml-1.5 size-8 rounded-full"
               onClick={send}
               disabled={!canSend}
               aria-label="Send message"
             >
-              <ArrowUpIcon className="size-4" />
+              <ArrowUpIcon className="size-[22px] stroke-2" />
             </TooltipIconButton>
           )}
         </div>
diff --git a/studio/frontend/src/features/chat/tour/steps.tsx b/studio/frontend/src/features/chat/tour/steps.tsx
index e222fdc8a0..e4f37685cc 100644
--- a/studio/frontend/src/features/chat/tour/steps.tsx
+++ b/studio/frontend/src/features/chat/tour/steps.tsx
@@ -9,7 +9,6 @@ export function buildChatTourSteps({
   closeModelSelector,
   openSettings,
   closeSettings,
-  openSidebar,
   enterCompare,
   exitCompare,
 }: {
@@ -18,7 +17,6 @@ export function buildChatTourSteps({
   closeModelSelector: () => void;
   openSettings: () => void;
   closeSettings: () => void;
-  openSidebar: () => void;
   enterCompare: () => void;
   exitCompare: () => void;
 }): TourStep[] {
@@ -64,33 +62,22 @@ export function buildChatTourSteps({
   ];
 
   if (canCompare) {
-    steps.push(
-      {
-        id: "compare-btn",
-        target: "chat-compare",
-        title: "Compare mode",
-        body: (
-          <>
-            Compare any two models side-by-side.
-            Pick a different model for each side and see how they respond to the same prompt.
-          </>
-        ),
-        onEnter: openSidebar,
-      },
-      {
-        id: "compare-view",
-        target: "chat-compare-view",
-        title: "Side-by-side threads",
-        body: (
-          <>
-            Same prompt, 2 threads. If LoRA is worse than base, it’s usually
-            data formatting, too many epochs, or a bad checkpoint choice.
-          </>
-        ),
-        onEnter: enterCompare,
-        onExit: exitCompare,
-      },
-    );
+    // Compare now lives in the + menu, so there is no sidebar button to anchor
+    // to; the view step enters compare on its own and explains it.
+    steps.push({
+      id: "compare-view",
+      target: "chat-compare-view",
+      title: "Side-by-side threads",
+      body: (
+        <>
+          Compare any two models side-by-side, available from the + menu. Same
+          prompt, 2 threads. If LoRA is worse than base, it’s usually data
+          formatting, too many epochs, or a bad checkpoint choice.
+        </>
+      ),
+      onEnter: enterCompare,
+      onExit: exitCompare,
+    });
   }
 
   return steps;
diff --git a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
index ed590f226e..3b9b60e5dd 100644
--- a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
+++ b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
@@ -7,7 +7,8 @@ import { Label } from "@/components/ui/label";
 import { getAuthToken } from "@/features/auth";
 import { useT } from "@/i18n";
 import { toastError, toastSuccess } from "@/shared/toast";
-import { Camera } from "lucide-react";
+import { Camera01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import { useMemo, useRef, useState } from "react";
 import { decodeJwtSubject } from "../utils/jwt-subject";
 import { resizeImageFileToDataUrl } from "../utils/resize-image-file";
@@ -117,10 +118,10 @@ export function ProfilePersonalizationPanel() {
         <button
           type="button"
           onClick={() => fileInputRef.current?.click()}
-          className="absolute right-0 bottom-0 -translate-x-[15.625%] -translate-y-[15.625%] flex size-8 items-center justify-center rounded-full border border-border bg-background text-foreground shadow-sm transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+          className="absolute right-0 bottom-0 -translate-x-[15.625%] -translate-y-[15.625%] flex size-8 items-center justify-center rounded-full border border-border bg-background text-foreground shadow-[0_2px_8px_-2px_rgba(27,27,31,0.16)] transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
           aria-label={t("settings.profile.changePicture")}
         >
-          <Camera className="size-3.5" strokeWidth={2} />
+          <HugeiconsIcon icon={Camera01Icon} className="size-3.5" strokeWidth={2} />
         </button>
       </div>
 
diff --git a/studio/frontend/src/features/settings/settings-dialog.tsx b/studio/frontend/src/features/settings/settings-dialog.tsx
index b6f2463b68..a1048b202e 100644
--- a/studio/frontend/src/features/settings/settings-dialog.tsx
+++ b/studio/frontend/src/features/settings/settings-dialog.tsx
@@ -128,8 +128,10 @@ export function SettingsDialog() {
           // Cap at 820px but shrink to the viewport so we don't clip
           // on iPad-portrait widths (640-820px) where the fixed
           // `w-[820px]` overflows by 26px on each side.
-          "!max-w-[min(820px,calc(100vw-2rem))] h-[560px] w-[min(820px,calc(100vw-2rem))] p-0 overflow-hidden",
-          "shadow-border rounded-xl border-border",
+          "settings-surface !max-w-[min(820px,calc(100vw-2rem))] h-[560px] w-[min(820px,calc(100vw-2rem))] p-0 overflow-hidden",
+          // Soft shadow only, no outline ring. Pin --radius to the light value
+          // so the corner rounding is the same in dark mode.
+          "shadow-border rounded-xl ring-0 [--radius:1.1rem]",
           "max-sm:h-dvh max-sm:w-dvw max-sm:!max-w-none max-sm:rounded-none",
         )}
       >
@@ -138,7 +140,10 @@ export function SettingsDialog() {
           {t("settings.dialog.description")}
         </DialogDescription>
         <div className="flex h-full min-h-0 max-sm:flex-col">
-          <aside className="font-heading flex w-[216px] shrink-0 flex-col border-r border-border bg-muted/20 p-2 max-sm:w-full max-sm:border-r-0 max-sm:border-b">
+          <aside className="font-heading flex w-[216px] shrink-0 flex-col border-r border-border bg-muted/20 p-2 dark:border-r-0 max-sm:w-full max-sm:border-r-0 max-sm:border-b max-sm:border-border">
+            <h2 className="pl-3 pr-2.5 pt-3.5 pb-3.5 text-[19px] font-semibold text-foreground max-sm:hidden">
+              {t("settings.dialog.title")}
+            </h2>
             <nav className="flex flex-col gap-0.5 max-sm:flex-row max-sm:overflow-x-auto">
               {TABS.map((tab) => {
                 const active = activeTab === tab.id;
@@ -151,7 +156,7 @@ export function SettingsDialog() {
                     type="button"
                     onClick={() => setActiveTab(tab.id)}
                     className={cn(
-                      "relative flex h-[32px] items-center gap-2.5 rounded-[8px] px-2.5 text-[14.5px] leading-[19px] tracking-nav font-medium transition-colors",
+                      "relative flex h-[32px] items-center gap-2.5 rounded-[11px] pl-3 pr-2.5 text-[14.5px] leading-[19px] tracking-nav font-medium transition-colors",
                       "max-sm:shrink-0",
                       "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                       active
@@ -162,7 +167,7 @@ export function SettingsDialog() {
                     {active && (
                       <motion.span
                         layoutId="settings-active-pill"
-                        className="absolute inset-0 rounded-[8px] bg-[#ececec] dark:bg-[#2d2f33]"
+                        className="absolute inset-0 rounded-[11px] bg-[#ececec] dark:bg-[#2d2f33]"
                         transition={
                           reduced
                             ? { duration: 0 }
@@ -198,12 +203,12 @@ export function SettingsDialog() {
             <button
               type="button"
               onClick={closeDialog}
-              className="absolute top-3 right-3 z-10 flex size-7 items-center justify-center rounded-[8px] text-[#383835] dark:text-[#c7c7c4] transition-colors hover:bg-[#ececec] dark:hover:bg-[#2d2f33] hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              className="absolute top-3 right-3 z-10 flex size-7 items-center justify-center rounded-full text-[#383835] dark:text-[#c7c7c4] transition-colors hover:bg-[#ececec] dark:hover:bg-[#2d2f33] hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               aria-label={t("settings.dialog.closeAriaLabel")}
             >
               <HugeiconsIcon icon={Cancel01Icon} className="size-4" />
             </button>
-            <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto p-6 [scrollbar-gutter:stable]">
+            <div className="hover-scrollbar flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto p-6 [scrollbar-gutter:stable]">
               {renderTab(activeTab)}
             </div>
           </main>
diff --git a/studio/frontend/src/features/settings/tabs/chat-tab.tsx b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
index 4e528eabb1..e37d56e2f7 100644
--- a/studio/frontend/src/features/settings/tabs/chat-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
@@ -19,7 +19,7 @@ import {
   useChatRuntimeStore,
 } from "@/features/chat";
 import { useT } from "@/i18n";
-import { Delete02Icon, Download02Icon } from "@hugeicons/core-free-icons";
+import { Delete02Icon, Download01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useState } from "react";
 import { SettingsRow } from "../components/settings-row";
@@ -165,7 +165,7 @@ export function ChatTab() {
             onClick={handleExport}
             disabled={exporting || count === 0}
           >
-            <HugeiconsIcon icon={Download02Icon} className="size-3.5 mr-1.5" />
+            <HugeiconsIcon icon={Download01Icon} className="size-3.5 mr-1.5" />
             {exporting
               ? t("settings.chat.exportingAction")
               : t("settings.chat.exportAction")}
diff --git a/studio/frontend/src/features/studio/studio-page.tsx b/studio/frontend/src/features/studio/studio-page.tsx
index 53191fa305..d5368fba58 100644
--- a/studio/frontend/src/features/studio/studio-page.tsx
+++ b/studio/frontend/src/features/studio/studio-page.tsx
@@ -177,7 +177,7 @@ export function StudioPage(): ReactElement {
           </div>
         ) : (
           <Tabs value={activeTab} onValueChange={handleTabChange}>
-            <div className="flex items-center gap-3">
+            <div className="flex items-center gap-3 pb-3">
               {selectedHistoryRunId && activeTab === "history" && (
                 <Button
                   variant="ghost"
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 12d63aac88..70dee1dcd7 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -258,7 +258,8 @@
 	--sidebar-border: #2d2d2f;
 	--sidebar-ring: #17b88b;
 	--destructive-foreground: oklch(1 0 0);
-	--radius: 0.625rem;
+	/* Match light's radius so every rounded-* element is the same in both themes. */
+	--radius: 1.1rem;
 	--font-sans: "Inter Variable", ui-sans-serif, sans-serif, system-ui;
 	--font-serif: Source Serif 4, serif;
 	--font-mono: JetBrains Mono, monospace;
@@ -584,7 +585,7 @@
 	}
 
 	.sidebar-sticky-label {
-		@apply rounded-none bg-sidebar pt-0 pb-[8px] pl-[18px] pr-4 text-[14.5px]! leading-[17px] font-medium normal-case focus-visible:ring-0! focus-visible:outline-none transition-shadow duration-150;
+		@apply rounded-none bg-sidebar pt-0 pb-[8px] pl-[18px] pr-4 text-[14px]! leading-[17px] font-medium normal-case focus-visible:ring-0! focus-visible:outline-none transition-shadow duration-150;
 		/* Muted section-header gray, matching Gemini's "Notebooks"/"Recents".
 		   Lightened from #5f6368 so the label reads as a header, clearly
 		   lighter than the near-black nav items. */
@@ -764,13 +765,13 @@
 
 	.app-user-menu [data-slot="dropdown-menu-item"],
 	.app-user-menu [data-slot="dropdown-menu-sub-trigger"] {
-		height: 32px;
-		padding: 0 0.625rem !important;
-		gap: 8.5px !important;
-		border-radius: 10px;
+		height: 36px;
+		padding: 0 0.75rem !important;
+		gap: 9.5px !important;
+		border-radius: 12px;
 		font-weight: 500;
-		font-size: 14.5px;
-		line-height: 19px;
+		font-size: 15px;
+		line-height: 20px;
 		letter-spacing: 0;
 		color: var(--nav-fg);
 	}
@@ -835,6 +836,59 @@
 		--tw-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
 	}
 
+	/* Settings dialog: no shadow in dark mode. */
+	.dark .settings-surface.shadow-border {
+		box-shadow: none;
+	}
+
+	/* App-wide: every clickable control shows the hand cursor. Disabled ones
+	   (native :disabled, aria-disabled, Radix data-disabled) keep the default. */
+	button:not(:disabled):not([aria-disabled="true"]),
+	summary,
+	label[for],
+	select:not(:disabled),
+	a[href],
+	:is(
+		[role="button"],
+		[role="tab"],
+		[role="switch"],
+		[role="radio"],
+		[role="checkbox"],
+		[role="menuitem"],
+		[role="menuitemcheckbox"],
+		[role="menuitemradio"],
+		[role="option"],
+		[role="combobox"],
+		[role="link"]
+	):not([aria-disabled="true"]):not([data-disabled]):not(:disabled) {
+		cursor: pointer;
+	}
+
+	/* Model selector: pointer cursor on every clickable element. */
+	.unsloth-model-selector-trigger,
+	.unsloth-model-selector-menu button {
+		cursor: pointer;
+	}
+
+	.unsloth-model-selector-trigger:disabled,
+	.unsloth-model-selector-menu button:disabled {
+		cursor: not-allowed;
+	}
+
+	/* Chat search box: borderless, soft Gemini-style elevation. */
+	.chat-search-surface {
+		border: none;
+		/* Pin to the dark --radius so the corners are the same (less round) in
+		   both themes; rounded-4xl here and on the inner Command follow this. */
+		--radius: 0.625rem;
+		/* Match the chat box: soft elevation in light, none in dark. */
+		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
+	}
+
+	.dark .chat-search-surface {
+		box-shadow: none;
+	}
+
 	.menu-soft-surface,
 	.menu-soft-surface-up {
 		--menu-soft-edge: rgba(0, 0, 0, 0.14);
@@ -858,31 +912,125 @@
 		--menu-soft-shadow: rgba(0, 0, 0, 0.28);
 	}
 
+	/* Model selector: drop the inset edge ring, keep the soft drop shadow.
+	   Pin --radius to the light value so the corners match in both themes. */
+	.unsloth-model-selector-menu.menu-soft-surface {
+		--radius: 1.1rem;
+		box-shadow: 0 var(--menu-soft-offset-y) var(--menu-soft-blur)
+			var(--menu-soft-spread) var(--menu-soft-shadow);
+	}
+
+	.dark .unsloth-model-selector-menu.menu-soft-surface {
+		box-shadow: none;
+	}
+
+	/* Every dropdown/menu/select/popover: borderless, chatbox shadow in light,
+	   none in dark. !important so it also overrides the bespoke menu shadows. */
+	[data-slot="dropdown-menu-content"],
+	[data-slot="dropdown-menu-sub-content"],
+	[data-slot="select-content"],
+	[data-slot="combobox-content"],
+	[data-slot="popover-content"] {
+		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16) !important;
+	}
+	/* Dark: keep the chat-box dropdown shadow so menus don't merge into a
+	   same-color surface (e.g. a menu overlapping the composer). */
+	.dark [data-slot="dropdown-menu-content"],
+	.dark [data-slot="dropdown-menu-sub-content"],
+	.dark [data-slot="select-content"],
+	.dark [data-slot="combobox-content"],
+	.dark [data-slot="popover-content"] {
+		box-shadow: 0 4px 14px var(--background) !important;
+	}
+
+	/* Context menus (chat, run, project): drop the inset edge ring, keep the soft shadow. */
+	.app-user-menu.menu-soft-surface {
+		box-shadow: 0 var(--menu-soft-offset-y) var(--menu-soft-blur)
+			var(--menu-soft-spread) var(--menu-soft-shadow);
+	}
+
+	/* Account menu: drop the inset edge ring and use the composer's soft shadow. */
+	.app-user-menu.menu-soft-surface-up {
+		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+	}
+	.dark .app-user-menu.menu-soft-surface-up {
+		box-shadow: 0 8px 28px -6px rgba(0, 0, 0, 0.28);
+	}
+
 	.chat-composer-surface {
-		@apply relative flex w-full flex-col rounded-[24px] bg-background dark:bg-card px-1 pt-2 outline-none transition-shadow;
+		@apply relative flex w-full flex-col rounded-[32px] bg-background dark:bg-card px-1 pt-2 outline-none transition-shadow;
 		font-family: var(--font-sans);
-		border: 1px solid oklch(0.93 0 0 / 1);
 		background-clip: padding-box;
-		box-shadow:
-			0 1px 2px oklch(0 0 0 / 0.04),
-			0 6px 14px oklch(0 0 0 / 0.05),
-			0 18px 40px oklch(0 0 0 / 0.05);
+		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
 	}
 
 	.dark .chat-composer-surface {
-		border-color: #34363a;
-		box-shadow: 0 -6px 36px -14px rgba(0, 0, 0, 0.15);
+		background-color: #2a2a2c;
+		box-shadow: none;
 	}
 
 	.composer-pill-btn {
-		@apply flex cursor-pointer items-center gap-1.5 rounded-full px-1.5 py-1.5 text-[13px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
+		@apply flex cursor-pointer items-center gap-1.5 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
 	}
+
+	/* Icon-only (compact) pills drop their label, so make the button a square
+	   and center the glyph; the rounded-full hover highlight then reads as a
+	   circle around the icon rather than a wide rounded rectangle. */
+	[data-pill-compact="true"] .composer-pill-btn:not([data-keep-label]) {
+		@apply size-8 justify-center px-0;
+	}
+
 	.composer-pill-btn[data-active="true"] {
 		color: var(--primary);
 	}
 
+	/* With more than 4 tools on, drop pill labels to icons only to cut clutter.
+	   Compare keeps its label via data-keep-label. */
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label])
+		> span:not(.composer-pill-glyph) {
+		display: none;
+	}
+
+	/* Drop the MCP dropdown caret when collapsed so the icon is not squished. */
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label])
+		.composer-pill-caret {
+		display: none;
+	}
+
+	/* Fixed-width icon slot so every pill's icon occupies the same space and
+	   the labels line up on an even rhythm, regardless of icon size. */
+	.composer-pill-glyph {
+		@apply relative inline-flex w-[19px] shrink-0 items-center justify-center transition-opacity;
+	}
+
+	/* On hover the icon swaps for an X inside a soft circle (ChatGPT-style),
+	   filling the icon slot so every pill's X is identical and centered. */
+	.composer-pill-x {
+		@apply pointer-events-none absolute inset-0 m-auto size-[19px] rounded-full bg-primary/15 p-[3px] opacity-0 transition-opacity dark:bg-white/[0.14];
+	}
+
+	/* Icon-only (compact) pills are too small for the circle, so show a bare x. */
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label])
+		.composer-pill-x {
+		@apply size-[15px] bg-transparent p-0 dark:bg-transparent;
+	}
+
+	/* Hovering an active pill swaps the icon for an X (click to turn off). */
+	.composer-pill-btn[data-active="true"]:hover .composer-pill-glyph > :not(.composer-pill-x),
+	.unsloth-thinking-pill[data-active="true"]:hover .composer-pill-glyph > :not(.composer-pill-x) {
+		@apply opacity-0;
+	}
+
+	.composer-pill-btn[data-active="true"]:hover .composer-pill-x,
+	.unsloth-thinking-pill[data-active="true"]:hover .composer-pill-x {
+		@apply opacity-100;
+	}
+
 	.composer-input {
-		@apply mt-2 mb-1 mx-3 min-h-12 w-[calc(100%-1.5rem)] resize-none overflow-y-auto bg-transparent pl-5 pr-4 pt-2 pb-3 text-sm font-[450] outline-none placeholder:text-muted-foreground focus-visible:ring-0;
+		@apply mt-2 mb-1 mx-3 min-h-12 w-[calc(100%-1.5rem)] resize-none overflow-y-auto bg-transparent pl-2 pr-4 pt-2 pb-3 text-sm font-[450] outline-none placeholder:text-muted-foreground focus-visible:ring-0;
 	}
 
 	.composer-action-wrapper {
@@ -894,6 +1042,254 @@
 		font-family: var(--font-sans);
 	}
 
+	/* Pill composer; own classes so compare-mode keeps its stacked layout. */
+	.unsloth-composer-surface {
+		@apply relative flex w-full flex-col rounded-[32px] bg-background dark:bg-card px-3 py-3 outline-none transition-shadow;
+		font-family: var(--font-sans);
+		background-clip: padding-box;
+		/* Gemini search pill: soft, centered shadow, no downward offset. */
+		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+	}
+
+	.unsloth-composer-surface:focus-within {
+		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+	}
+
+	.dark .unsloth-composer-surface {
+		background-color: #2a2a2c;
+		box-shadow: none;
+	}
+
+	/* Keep the expand/collapse width swap instant. A transition on width (e.g.
+	   the reduced-motion blanket rule) makes getComputedStyle().width lag a
+	   frame, so autosize measures the stale width and leaves a stray blank row. */
+	.unsloth-composer-line,
+	.unsloth-composer-line .unsloth-composer-input,
+	.unsloth-composer-left {
+		transition-property: none !important;
+	}
+
+	/* Composer row: one centered line when empty; two rows (input over controls)
+	   when filled, so the textarea never remounts. */
+	.unsloth-composer-line {
+		@apply flex w-full flex-wrap items-center gap-0.5 px-1;
+	}
+
+	.unsloth-composer-left {
+		@apply flex shrink-0 items-center gap-0.5;
+		order: 1;
+		/* Pull the plus button closer to the composer edge. */
+		margin-left: -0.25rem;
+	}
+
+	.unsloth-composer-line .unsloth-composer-input {
+		order: 2;
+	}
+
+	.unsloth-composer-line .aui-composer-action-wrapper {
+		order: 3;
+		margin-left: auto;
+		/* Inset the send circle from the edge, Gemini-style. */
+		margin-right: -0.125rem;
+	}
+
+	.unsloth-composer-line[data-expanded="true"] .unsloth-composer-input {
+		order: 1;
+		flex-basis: 100%;
+		width: 100%;
+		/* Sits close to the left edge, near the plus. */
+		padding-left: 0.375rem;
+		padding-top: 0.5rem;
+		padding-bottom: 0.5rem;
+	}
+
+	/* Two-row gap between text and controls. On the line, not the input, so
+	   the placeholder max-height clamp never crops it like padding would. */
+	.unsloth-composer-line[data-expanded="true"] {
+		row-gap: 0.75rem;
+	}
+
+	.unsloth-composer-line[data-expanded="true"] .unsloth-composer-left {
+		order: 2;
+	}
+
+	/* Empty (placeholder shown): clamp back to one row. max-height beats the
+	   autosize textarea's inline !important height, so a cleared message leaves
+	   no stale tall box or stray scrollbar. */
+	.unsloth-composer-input:placeholder-shown {
+		max-height: 40px !important;
+		overflow-y: hidden !important;
+	}
+
+	.unsloth-composer-input {
+		@apply min-h-[40px] min-w-0 flex-1 resize-none overflow-y-auto bg-transparent pl-0.5 pr-2 py-2 text-[15px] font-[450] leading-6 outline-none placeholder:text-muted-foreground focus-visible:ring-0;
+	}
+
+	.unsloth-composer-plus {
+		@apply flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full text-foreground transition-colors hover:bg-muted-foreground/15 disabled:cursor-not-allowed disabled:opacity-40;
+	}
+
+	.unsloth-composer-plus[data-state="open"] {
+		@apply bg-muted-foreground/15;
+		/* Radix's modal menu sets body pointer-events:none; re-enable on the open
+		   trigger so the cursor and click-to-close work. */
+		pointer-events: auto;
+		cursor: pointer;
+	}
+
+	/* Open menu rotates the plus 45deg into an x. Ease-in-out for a smooth
+	   spin; keep it at 45deg so it never passes back through a "+". */
+	.unsloth-composer-plus svg {
+		transition: transform 300ms cubic-bezier(0.65, 0, 0.35, 1);
+		will-change: transform;
+	}
+
+	.unsloth-composer-plus[data-state="open"] svg {
+		transform: rotate(45deg);
+	}
+
+	/* Keyboard focus shows a subtle brand ring, not the browser's blue outline;
+	   mouse clicks (no :focus-visible) stay ring-free. */
+	.composer-pill-btn:focus-visible,
+	.unsloth-thinking-pill:focus-visible,
+	.unsloth-composer-plus:focus-visible {
+		outline: none;
+		box-shadow: 0 0 0 2px color-mix(in oklab, var(--ring) 45%, transparent);
+	}
+
+	/* Set Hellix explicitly; .aui-thread-root resets --font-heading to sans. */
+	.unsloth-welcome-title {
+		font-family: "Hellix", "Space Grotesk Variable", var(--font-sans);
+		font-weight: 500;
+	}
+
+	/* Right-side Thinking pill (toggle or dropdown). pl-2 matches the left
+	   pills so the hover X is not pushed in too far. */
+	.unsloth-thinking-pill {
+		@apply inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
+		/* Reserve a text line so the icon-only (inactive) pill matches the
+		   text pills' height instead of collapsing to the icon. */
+		min-height: calc(1lh + 0.75rem);
+	}
+
+	.unsloth-thinking-pill[data-active="true"] {
+		color: var(--primary);
+	}
+
+	.unsloth-thinking-pill[data-state="open"] {
+		@apply bg-muted-foreground/10;
+		/* See .unsloth-composer-plus: re-enable pointer-events on the open trigger. */
+		pointer-events: auto;
+		cursor: pointer;
+	}
+
+	/* Smaller tick for selected Thinking options. */
+	.unsloth-tick {
+		width: 0.8rem !important;
+		height: 0.8rem !important;
+	}
+
+	/* Soft elevation; [data-slot] outranks the component ring-1, dropping the border. */
+	.unsloth-plus-menu[data-slot] {
+		/* Pin radius so dark matches light (rounded-lg resolves smaller in dark). */
+		border-radius: 18px;
+		padding-top: 0.5rem;
+		padding-bottom: 0.5rem;
+		box-shadow:
+			0 1px 2px oklch(0 0 0 / 0.04),
+			0 6px 18px oklch(0 0 0 / 0.08);
+	}
+
+	/* MCP menu is wider (232px), so nudge the radius up so it reads as round as
+	   the narrower + menu (18 * 232/212 ~= 20px). */
+	.unsloth-plus-menu.mcp-menu[data-slot] {
+		border-radius: 20px;
+	}
+
+	.dark .unsloth-plus-menu[data-slot] {
+		background-color: #2a2a2c;
+		/* Shadow tinted to the page bg so it blends, not a dark halo. */
+		box-shadow: 0 4px 14px var(--background);
+	}
+
+	/* Compact items; also applied to portaled sub-content. */
+	.unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		) {
+		@apply gap-3 pl-4 pr-3 py-2 text-[14px];
+		cursor: pointer;
+		/* Pin hover-box radius so dark matches light (same as the container). */
+		border-radius: 1.1rem;
+	}
+
+	.unsloth-plus-menu [data-slot="dropdown-menu-label"] {
+		@apply pl-4 pr-3 py-1.5 text-[12px];
+	}
+
+	/* Active (green) items keep their primary text and icon color on hover. */
+	.unsloth-plus-menu [data-slot="dropdown-menu-item"].text-primary:is(:hover, :focus, :focus-visible, [data-highlighted]),
+	.unsloth-plus-menu [data-slot="dropdown-menu-item"].text-primary:is(:hover, :focus, :focus-visible, [data-highlighted]) svg {
+		color: var(--primary) !important;
+	}
+
+	/* Light hover: neutral grey, not the green accent. */
+	.unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		):is(:hover, :focus, :focus-visible, [data-highlighted], [data-state="open"]) {
+		background-color: rgba(0, 0, 0, 0.06) !important;
+	}
+
+	/* Dark hover: the accent nearly matches the surface, so use a clear overlay. */
+	.dark .unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		):is(:hover, :focus, :focus-visible, [data-highlighted], [data-state="open"]) {
+		background-color: rgba(255, 255, 255, 0.08) !important;
+	}
+
+	/* Hover tints only the background; the item and every descendant (text, icons,
+	   labels) keep their resting color, overriding Radix's focus:**:text-accent-
+	   foreground. The active green rule above still wins via higher specificity. */
+	.unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		):is(:hover, :focus, :focus-visible, [data-highlighted], [data-state="open"]),
+	.unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		):is(:hover, :focus, :focus-visible, [data-highlighted], [data-state="open"]) * {
+		color: inherit !important;
+	}
+
+	.unsloth-plus-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		)
+		svg {
+		width: 1.05rem;
+		height: 1.05rem;
+	}
+
+	/* Destructive items keep red text and a red-tinted hover, not the grey one. */
+	.unsloth-plus-menu [data-slot="dropdown-menu-item"][data-variant="destructive"],
+	.unsloth-plus-menu [data-slot="dropdown-menu-item"][data-variant="destructive"] * {
+		color: var(--destructive) !important;
+	}
+	.unsloth-plus-menu [data-slot="dropdown-menu-item"][data-variant="destructive"]:is(:hover, :focus, :focus-visible, [data-highlighted]) {
+		background-color: color-mix(in oklab, var(--destructive) 10%, transparent) !important;
+	}
+
+	/* Thinking menu: tighter gap; nowrap keeps "Preserve thinking" on one line
+	   so the menu sizes to its content. */
+	.unsloth-thinking-menu :is(
+			[data-slot="dropdown-menu-item"],
+			[data-slot="dropdown-menu-sub-trigger"]
+		) {
+		@apply gap-1.5 pl-2.5 pr-2.5;
+		white-space: nowrap;
+	}
 	.artifact-panel-shell {
 		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
 	}
@@ -1223,7 +1619,8 @@
 	}
 }
 
-/* Lighter shadow + tighter vertical padding than Sonner's defaults; !important because Sonner injects its base rules at runtime. */
+/* No border line; same drop shadow as the composer (.unsloth-composer-surface).
+   !important because Sonner injects its base rules at runtime. */
 [data-sonner-toast][data-styled='true'] {
 	padding: 12px 18px !important;
 	box-shadow: 0 2px 6px rgba(0, 0, 0, 0.08) !important;
@@ -1263,7 +1660,8 @@
 
 /* Boost shadow on dark surfaces; mirrors .shadow-border / .menu-soft-surface pattern. */
 .dark [data-sonner-toast][data-styled='true'] {
-	box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3) !important;
+	background-color: #2a2a2c !important;
+	box-shadow: none !important;
 }
 
 /* Selectable toast text; non-selectable toast buttons. */
@@ -1349,6 +1747,86 @@
 	background: oklch(0.67 0 0 / 0.5);
 }
 
+/* Composer textarea: keep the scroll thumb faint until the user hovers or
+   drags the thumb itself, so a tall draft never shows a heavy dark rail. */
+.composer-input,
+.unsloth-composer-input {
+	scrollbar-color: oklch(0.5 0 0 / 0.16) transparent;
+}
+
+.composer-input::-webkit-scrollbar-thumb,
+.unsloth-composer-input::-webkit-scrollbar-thumb {
+	background: oklch(0.5 0 0 / 0.16);
+}
+
+.composer-input::-webkit-scrollbar-thumb:hover,
+.unsloth-composer-input::-webkit-scrollbar-thumb:hover,
+.composer-input::-webkit-scrollbar-thumb:active,
+.unsloth-composer-input::-webkit-scrollbar-thumb:active {
+	background: oklch(0.5 0 0 / 0.45);
+}
+
+.dark .composer-input,
+.dark .unsloth-composer-input {
+	scrollbar-color: oklch(0.72 0 0 / 0.18) transparent;
+}
+
+.dark .composer-input::-webkit-scrollbar-thumb,
+.dark .unsloth-composer-input::-webkit-scrollbar-thumb {
+	background: oklch(0.72 0 0 / 0.18);
+}
+
+.dark .composer-input::-webkit-scrollbar-thumb:hover,
+.dark .unsloth-composer-input::-webkit-scrollbar-thumb:hover,
+.dark .composer-input::-webkit-scrollbar-thumb:active,
+.dark .unsloth-composer-input::-webkit-scrollbar-thumb:active {
+	background: oklch(0.72 0 0 / 0.5);
+}
+
+/* Sidebars, settings and search: hide the scroll thumb at rest and reveal it
+   only while the area is hovered, so the rail never sits visible over content. */
+.sidebar-scroll-fade,
+.run-settings-scroll,
+.hover-scrollbar {
+	scrollbar-color: transparent transparent;
+}
+
+.sidebar-scroll-fade::-webkit-scrollbar-thumb,
+.run-settings-scroll::-webkit-scrollbar-thumb,
+.hover-scrollbar::-webkit-scrollbar-thumb {
+	background: transparent;
+}
+
+.sidebar-scroll-fade:hover,
+.run-settings-scroll:hover,
+.hover-scrollbar:hover {
+	scrollbar-color: oklch(0.5 0 0 / 0.4) transparent;
+}
+
+.sidebar-scroll-fade:hover::-webkit-scrollbar-thumb,
+.run-settings-scroll:hover::-webkit-scrollbar-thumb,
+.hover-scrollbar:hover::-webkit-scrollbar-thumb {
+	background: oklch(0.5 0 0 / 0.4);
+}
+
+.dark .sidebar-scroll-fade:hover,
+.dark .run-settings-scroll:hover,
+.dark .hover-scrollbar:hover {
+	scrollbar-color: oklch(0.72 0 0 / 0.4) transparent;
+}
+
+.dark .sidebar-scroll-fade:hover::-webkit-scrollbar-thumb,
+.dark .run-settings-scroll:hover::-webkit-scrollbar-thumb,
+.dark .hover-scrollbar:hover::-webkit-scrollbar-thumb {
+	background: oklch(0.72 0 0 / 0.4);
+}
+
+/* Run settings: always reserve the scrollbar gutter so the header close
+   button keeps its position whether or not the scrollbar is showing. */
+.run-settings-scroll {
+	scrollbar-gutter: stable;
+}
+
 /* Chat viewport: solid track matching sidebar so the scrollbar reads as a
    full-height rail flush to the right edge, without a separate decorative strip. */
 .aui-thread-viewport {
@@ -1429,7 +1907,12 @@
 	transform: none !important;
 	background: var(--popover) !important;
 	color: var(--popover-foreground) !important;
-	border-color: var(--border) !important;
+	border-color: transparent !important;
+}
+
+/* Keep the (borderless) close button blended with the dark toast surface. */
+.dark [data-sonner-toast][data-styled="true"] [data-close-button] {
+	background: #2a2a2c !important;
 }
 
 [data-sonner-toast][data-styled="true"] [data-close-button] svg {
@@ -1438,7 +1921,7 @@
 [data-sonner-toast][data-styled="true"]:hover [data-close-button]:hover {
 	background: var(--muted) !important;
 	color: var(--popover-foreground) !important;
-	border-color: var(--border) !important;
+	border-color: transparent !important;
 }
 
 .generated-image-loading-card {
@@ -1522,4 +2005,10 @@
 		animation-duration: 1850ms !important;
 		animation-iteration-count: infinite !important;
 	}
+
+	/* Keep the plus/x morph animating under reduced motion (small rotation,
+	   like the spinners above). */
+	.unsloth-composer-plus svg {
+		transition-duration: 300ms !important;
+	}
 }
diff --git a/studio/frontend/src/speech-recognition.d.ts b/studio/frontend/src/speech-recognition.d.ts
index 181a77fea1..dc7234ce91 100644
--- a/studio/frontend/src/speech-recognition.d.ts
+++ b/studio/frontend/src/speech-recognition.d.ts
@@ -28,6 +28,11 @@ interface SpeechRecognitionEvent extends Event {
   readonly results: SpeechRecognitionResultList;
 }
 
+interface SpeechRecognitionErrorEvent extends Event {
+  readonly error: string;
+  readonly message: string;
+}
+
 interface SpeechRecognition extends EventTarget {
   continuous: boolean;
   interimResults: boolean;
@@ -35,7 +40,7 @@ interface SpeechRecognition extends EventTarget {
   onresult: ((event: SpeechRecognitionEvent) => void) | null;
   onerror: ((event: Event) => void) | null;
   onend: (() => void) | null;
-  start(): void;
+  start(audioTrack?: MediaStreamTrack): void;
   stop(): void;
   abort(): void;
 }
@@ -49,4 +54,4 @@ interface Window {
   webkitSpeechRecognition?: SpeechRecognitionConstructor;
 }
 
-declare var SpeechRecognition: SpeechRecognitionConstructor | undefined;
+declare const SpeechRecognition: SpeechRecognitionConstructor | undefined;
diff --git a/tests/studio/playwright_chat_ui.py b/tests/studio/playwright_chat_ui.py
index 845451919c..b1279e64b9 100644
--- a/tests/studio/playwright_chat_ui.py
+++ b/tests/studio/playwright_chat_ui.py
@@ -1115,7 +1115,25 @@ with sync_playwright() as p:
     step("sidebar nav: New Chat -> Compare -> Search -> Recipes")
     click_nav("New Chat", r"/chat")
     shoot("11-new-chat")
-    click_nav("Compare", r"/chat\?")  # /chat?compare=...
+    # Compare moved into the composer + menu (Tools and attachments).
+    plus_btn = page.get_by_role(
+        "button", name = re.compile(r"Tools and attachments", re.I)
+    ).first
+    if plus_btn.count() > 0:
+        plus_btn.click(force = True)
+        page.wait_for_timeout(400)
+        compare_item = page.get_by_role(
+            "menuitem", name = re.compile(r"Compare chat", re.I)
+        ).first
+        if compare_item.count() > 0:
+            compare_item.click(force = True)
+            page.wait_for_timeout(800)
+            if not re.search(r"/chat\?", page.url):
+                soft_fail(f"'Compare chat' didn't open compare; current: {page.url}")
+        else:
+            soft_fail("composer + menu: 'Compare chat' item not found")
+    else:
+        soft_fail("composer + menu: plus button not found")
     shoot("12-compare")
     # Search opens a dialog (not a route change).
     search_btn = page.get_by_role("button", name = re.compile(r"^search$", re.I)).first
diff --git a/tests/studio/playwright_extra_ui.py b/tests/studio/playwright_extra_ui.py
index 1f507c9f33..0ac9f67a7e 100644
--- a/tests/studio/playwright_extra_ui.py
+++ b/tests/studio/playwright_extra_ui.py
@@ -327,17 +327,23 @@ with sync_playwright() as p:
     # 1. Compare tab.
     # ─────────────────────────────────────────────────────
     step("Compare tab: send to two panes")
-    # The Compare nav lives in the sidebar; click it.
-    compare_nav = page.locator('[data-tour="chat-compare"]').first
-    if compare_nav.count() == 0:
-        compare_nav = page.get_by_role(
-            "button",
-            name = re.compile(r"^\s*Compare\s*$", re.I),
+    # Compare moved into the composer + menu (Tools and attachments).
+    compare_opened = False
+    plus_btn = page.get_by_role(
+        "button", name = re.compile(r"Tools and attachments", re.I)
+    ).first
+    if plus_btn.count() > 0:
+        plus_btn.click(force = True)
+        page.wait_for_timeout(400)
+        compare_item = page.get_by_role(
+            "menuitem", name = re.compile(r"Compare chat", re.I)
         ).first
-    if compare_nav.count() == 0:
+        if compare_item.count() > 0:
+            compare_item.click(force = True)
+            compare_opened = True
+    if not compare_opened:
         soft_fail("Compare nav not found")
     else:
-        compare_nav.click()
         page.wait_for_timeout(1500)
         shoot("02-compare-opened")
         # Compare view's container.

From aa0db1ff5b21e618d74c7a337aaa03a25e6f9098 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 06:10:23 -0700
Subject: [PATCH 079/222] fix(studio): don't double-quote the reset-password
 hint for spaced paths (#5975)

Addresses review feedback on #5971. _reset_password_command() already
shell-quotes the launcher path on POSIX (shlex.quote), so wrapping the result in
another pair of single quotes in the error string produced a mangled hint for
installs / home dirs containing spaces, e.g.

  Run ''/tmp/Unsloth Studio/.../unsloth' studio reset-password' in your terminal

which a shell mis-parses. Drop the outer quotes and put the command at the end of
the message so it is unambiguous and copy-pasteable in every case:

  Incorrect password. To reset it, run this in your terminal: <cmd>

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 studio/backend/routes/auth.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index ef01bcc9a9..23112ca2f8 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -260,7 +260,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
         _record_login_failure(unknown_key)
         raise HTTPException(
             status_code = status.HTTP_401_UNAUTHORIZED,
-            detail = f"Incorrect password. Run '{_reset_password_command()}' in your terminal to reset it.",
+            detail = f"Incorrect password. To reset it, run this in your terminal: {_reset_password_command()}",
         )
 
     salt, pwd_hash, _jwt_secret, must_change_password = record
@@ -268,7 +268,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
         _record_login_failure(key)
         raise HTTPException(
             status_code = status.HTTP_401_UNAUTHORIZED,
-            detail = f"Incorrect password. Run '{_reset_password_command()}' in your terminal to reset it.",
+            detail = f"Incorrect password. To reset it, run this in your terminal: {_reset_password_command()}",
         )
 
     _clear_login_bucket(key)

From 3f68dd5f0e9ecc54e75673cbce281d3ef356f35a Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Wed, 3 Jun 2026 18:44:54 +0530
Subject: [PATCH 080/222] Patch sibling config module so GRPOConfig resolves to
 the patched class (#5946)

Fixes #3931. After patching a TRL trainer, also patch the sibling config module (e.g. trl.trainer.grpo_config.GRPOConfig) to the Unsloth-patched config, so importing the config from its own module returns the patched class carrying unsloth_grpo_mini_batch. Defensive (try/except + hasattr) so it safely no-ops when no sibling config module exists.
---
 .../test_patch_trl_rl_trainers_defensive.py      | 16 ++++++++++++++++
 unsloth/models/rl.py                             | 12 ++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/tests/python/test_patch_trl_rl_trainers_defensive.py b/tests/python/test_patch_trl_rl_trainers_defensive.py
index 7c76ac2792..55a3425c44 100644
--- a/tests/python/test_patch_trl_rl_trainers_defensive.py
+++ b/tests/python/test_patch_trl_rl_trainers_defensive.py
@@ -67,3 +67,19 @@ def test_wrapper_swallows_impl_exception(monkeypatch):
 
     monkeypatch.setattr(_rl, "_patch_trl_rl_trainers_impl", _boom)
     assert _rl._patch_trl_rl_trainers("sft_trainer") is None
+
+
+def test_grpo_config_sibling_module_import_is_patched(tmp_path):
+    import unsloth  # noqa: F401
+    from trl import GRPOConfig as top_config
+    from trl.trainer import GRPOConfig as trainer_config
+    from trl.trainer.grpo_config import GRPOConfig as config_module_config
+    from trl.trainer.grpo_trainer import GRPOConfig as trainer_module_config
+
+    assert top_config is trainer_config
+    assert top_config is trainer_module_config
+    assert top_config is config_module_config
+
+    args = config_module_config(output_dir = str(tmp_path))
+    assert hasattr(args, "unsloth_grpo_mini_batch")
+    assert args.unsloth_grpo_mini_batch is None
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index 359716fda4..afa2753994 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -19,6 +19,7 @@ __all__ = [
 
 import torch
 from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union
+import importlib
 import inspect
 import os
 import re
@@ -1845,6 +1846,17 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         locals(),
         globals(),
     )
+    try:
+        config_module_name = trainer_file.replace("_trainer", "_config")
+        config_module = importlib.import_module(f"trl.trainer.{config_module_name}")
+        if hasattr(config_module, RLConfig_name):
+            setattr(
+                config_module,
+                RLConfig_name,
+                getattr(created_module, f"Unsloth{RLConfig_name}"),
+            )
+    except Exception:
+        pass
 
     if trainer_file == "grpo_trainer":
         try:

From 9a6f404837754805834955940e35a04ee99b27a3 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 06:15:06 -0700
Subject: [PATCH 081/222] Fix UnicodeEncodeError when printing emoji on legacy
 Windows consoles (#5948)

On Windows only, at unsloth import, reconfigure stdout/stderr to UTF-8 when they are not already, so emoji and box-drawing glyphs do not crash legacy code-page consoles (e.g. cp1252) at SFTTrainer init. No-op on Linux/macOS and when output is already UTF-8 (PYTHONUTF8, modern terminals), and fully guarded so it can never raise.
---
 unsloth/__init__.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 75fb169e83..fb11f1f649 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -16,6 +16,27 @@ import os, importlib.util, platform
 
 os.environ["UNSLOTH_IS_PRESENT"] = "1"
 
+# ── Windows console UTF-8 safety ─────────────────────────────────────────────
+# Legacy Windows consoles use a non-UTF-8 code page (e.g. cp1252) that cannot
+# encode the emoji / box-drawing glyphs Unsloth prints, so a bare
+# print("\U0001f9a5 ...") raises UnicodeEncodeError and aborts (observed at
+# SFTTrainer init, unsloth/trainer.py). Reconfigure stdout/stderr to UTF-8 ONLY
+# on Windows and ONLY when they are not already UTF-8 -- this is a no-op when
+# PYTHONUTF8 / PYTHONIOENCODING is set (Unsloth Studio worker, modern terminals)
+# and is never touched on Linux/macOS, so it cannot change their behaviour.
+# errors="replace" guarantees we can never crash on an unencodable glyph.
+if platform.system() == "Windows":
+    import sys as _sys
+
+    for _name in ("stdout", "stderr"):
+        _s = getattr(_sys, _name, None)
+        try:
+            _enc = (getattr(_s, "encoding", None) or "").lower()
+            if _s is not None and hasattr(_s, "reconfigure") and "utf" not in _enc:
+                _s.reconfigure(encoding = "utf-8", errors = "replace")
+        except Exception:
+            pass
+
 
 def _is_mlx_available():
     # Transitional import barrier: while the paired unsloth-zoo MLX runtime

From 08d02610d95b216d57c43402391fe425a01044e0 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 06:35:55 -0700
Subject: [PATCH 082/222] Versioning

---
 pyproject.toml           | 6 +++---
 unsloth/models/_utils.py | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index acc65f12cf..24fd66dbbb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,7 +69,7 @@ triton = [
 ]
 
 huggingfacenotorch = [
-    "unsloth_zoo>=2026.5.5",
+    "unsloth_zoo>=2026.6.1",
     "wheel>=0.42.0",
     "packaging",
     "numpy",
@@ -90,7 +90,7 @@ huggingfacenotorch = [
 ]
 huggingface = [
     "unsloth[huggingfacenotorch]",
-    "unsloth_zoo>=2026.5.5",
+    "unsloth_zoo>=2026.6.1",
     "torchvision",
     "unsloth[triton]",
 ]
@@ -580,7 +580,7 @@ colab-ampere-torch220 = [
     "flash-attn>=2.6.3 ; ('linux' in sys_platform)",
 ]
 colab-new = [
-    "unsloth_zoo>=2026.5.5",
+    "unsloth_zoo>=2026.6.1",
     "packaging",
     "tyro",
     "transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 138a7b3cc0..7af89bcecd 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2026.5.10"
+__version__ = "2026.6.1"
 
 __all__ = [
     "SUPPORTS_BFLOAT16",

From c7d2ed1920e4c6d68632976abc779e710122d04b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 07:29:18 -0700
Subject: [PATCH 083/222] Fix macOS Apple Silicon installs resolving torch
 against x86_64 (#5976)

* Fix macOS Apple Silicon installs that resolve torch against x86_64

On Apple Silicon, `uv venv --python 3.13` can reuse a cached x86_64
(Rosetta) CPython, often because uv itself is an x86_64 build. The
resulting venv reports macosx_*_x86_64 to the wheel resolver, but PyTorch
has shipped no macOS x86_64 wheels since 2.2.2, so the torch install fails
with "no wheels with a matching platform tag (macosx_..._x86_64)".

Two changes, both scoped to macOS arm64 and additive (no other install
path is affected):

- Create the venv with an arch-explicit `cpython-X.Y-macos-aarch64-none`
  request on Apple Silicon (no --python override), so uv cannot fall back
  to a cached x86_64 interpreter.
- Harden the existing x86_64 venv guard: when the venv python cannot be
  executed (x86_64 binary on a Mac without Rosetta), the platform.machine()
  probe returns empty and the recreate was silently skipped. Fall back to
  reading the binary's Mach-O arch via lipo/file so migrated or
  pre-existing x86_64 venvs are still recreated as arm64.

* Harden arm64 static-arch fallback: file -L and set -e safety

Address review feedback on the lipo/file fallback:
- uv symlinks the venv's bin/python to the base interpreter; plain `file`
  reports the symlink ("symbolic link to ...") and the arch substring never
  matches. Use `file -L` to dereference (lipo already follows the link).
- Append `|| true` so the command substitution cannot abort the installer
  under set -e on a Mac that has neither lipo nor file.

---------

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 install.sh | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/install.sh b/install.sh
index 1d4d9067c1..d35d370313 100755
--- a/install.sh
+++ b/install.sh
@@ -1529,7 +1529,17 @@ fi
 if [ ! -x "$VENV_DIR/bin/python" ]; then
     step "venv" "creating Python ${PYTHON_VERSION} virtual environment"
     substep "$VENV_DIR"
-    run_install_cmd "create venv" uv venv "$VENV_DIR" --python "$PYTHON_VERSION"
+    if [ "$OS" = "macos" ] && [ "$_ARCH" = "arm64" ] && [ -z "$_USER_PYTHON" ]; then
+        # Apple Silicon: request an arch-explicit arm64 CPython so uv cannot
+        # reuse a cached x86_64 (Rosetta) build. torch ships no macOS x86_64
+        # wheels since 2.2.2, so an x86_64 venv makes the torch install
+        # unresolvable. The arm64 guard below is kept as a backstop for
+        # migrated / pre-existing venvs.
+        run_install_cmd "create venv" uv venv "$VENV_DIR" \
+            --python "cpython-${PYTHON_VERSION}-macos-aarch64-none"
+    else
+        run_install_cmd "create venv" uv venv "$VENV_DIR" --python "$PYTHON_VERSION"
+    fi
 fi
 
 # Mark the freshly-created venv as Studio-owned so a partial install can be
@@ -1561,6 +1571,21 @@ if [ -z "$_USER_PYTHON" ] && [ "$OS" = "macos" ] && [ "$_ARCH" = "arm64" ]; then
     _info=$(_inspect_venv)
     _VENV_ARCH=${_info%% *}
     _PY_VER=${_info##* }
+    # If the interpreter could not be executed (an x86_64 venv python on a Mac
+    # without Rosetta installed), the probe above yields an empty arch. Fall
+    # back to reading the binary's Mach-O arch statically so the x86_64
+    # recreate below still triggers instead of letting uv fail later.
+    if [ -z "$_VENV_ARCH" ] && [ -x "$VENV_DIR/bin/python" ]; then
+        # uv symlinks bin/python to the base interpreter, so dereference with
+        # file -L (lipo already follows the link). Trailing || true keeps the
+        # installer alive under set -e when neither tool is present.
+        _archs=$(lipo -archs "$VENV_DIR/bin/python" 2>/dev/null \
+            || file -L "$VENV_DIR/bin/python" 2>/dev/null || true)
+        case "$_archs" in
+            *arm64*)  _VENV_ARCH=arm64 ;;
+            *x86_64*) _VENV_ARCH=x86_64 ;;
+        esac
+    fi
 
     if [ "$_VENV_ARCH" = "x86_64" ]; then
         echo "  WARNING: venv was created with an x86_64 (Rosetta) Python on Apple Silicon."

From b0572bd233efc120d50a940f13af89eb879d0dd0 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 3 Jun 2026 10:22:24 -0700
Subject: [PATCH 084/222] Bump install.sh / install.ps1 pin to
 unsloth>=2026.6.1 (#5977)

---
 install.ps1 | 10 +++++-----
 install.sh  | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/install.ps1 b/install.ps1
index eb18e0d426..e57b3f670e 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1579,7 +1579,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Resolve pydantic WITH deps so pip pins pydantic-core
                 # to the matching version (no-torch-runtime.txt below
@@ -1593,7 +1593,7 @@ shell.Run cmd, 0, False
                 }
             }
         } else {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
         }
         if ($baseInstallExit -ne 0) {
             Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
@@ -1640,7 +1640,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.5.10" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Same pydantic-with-deps trick as the migrated branch.
                 $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython pydantic }
@@ -1652,7 +1652,7 @@ shell.Run cmd, 0, False
                 }
             }
         } elseif ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.5.10" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.6.1" unsloth-zoo }
         } else {
             $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth -- "$PackageName" }
         }
@@ -1680,7 +1680,7 @@ shell.Run cmd, 0, False
         Write-TauriLog "STEP" "Installing unsloth"
         substep "installing unsloth (this may take a few minutes)..."
         if ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.5.10" --torch-backend=auto }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.6.1" --torch-backend=auto }
             if ($baseInstallExit -ne 0) {
                 Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
                 return (Exit-InstallFailure "Failed to install unsloth (exit code $baseInstallExit)" $baseInstallExit)
diff --git a/install.sh b/install.sh
index d35d370313..d7de8a946d 100755
--- a/install.sh
+++ b/install.sh
@@ -2117,7 +2117,7 @@ if [ "$_MIGRATED" = true ]; then
         # to prevent transitive torch resolution.
         run_install_cmd "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.10" unsloth-zoo
+            "unsloth>=2026.6.1" unsloth-zoo
         # Resolve pydantic WITH deps so pip pins pydantic-core to the
         # matching version (no-torch-runtime.txt below is --no-deps).
         # All transitive deps are torch-free.
@@ -2130,7 +2130,7 @@ if [ "$_MIGRATED" = true ]; then
     else
         run_install_cmd "install unsloth (migrated)" uv pip install --python "$_VENV_PY" \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.5.10" unsloth-zoo
+            "unsloth>=2026.6.1" unsloth-zoo
     fi
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         substep "overlaying local repo (editable)..."
@@ -2334,7 +2334,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
         run_install_cmd "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --upgrade-package unsloth --upgrade-package unsloth-zoo \
-            "unsloth>=2026.5.10" unsloth-zoo
+            "unsloth>=2026.6.1" unsloth-zoo
         # Same pydantic-with-deps trick as the migrated branch.
         run_install_cmd "install pydantic (with deps for compatible core)" \
             uv pip install --python "$_VENV_PY" pydantic
@@ -2352,7 +2352,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         fi
     elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         run_install_cmd "install unsloth (local)" uv pip install --python "$_VENV_PY" \
-            --upgrade-package unsloth "unsloth>=2026.5.10" unsloth-zoo
+            --upgrade-package unsloth "unsloth>=2026.6.1" unsloth-zoo
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."
@@ -2384,7 +2384,7 @@ else
     tauri_log "STEP" "Installing Unsloth"
     substep "installing unsloth (this may take a few minutes)..."
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
-        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.5.10" --torch-backend=auto
+        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.6.1" --torch-backend=auto
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."

From 157cecb25c3c7277a6da33c81a409373adb2b4b1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 00:07:58 -0700
Subject: [PATCH 085/222] Port KTO logps truncation guard to TRL 1.x
 _compute_logps refactor (#5996)

* Port KTO logps truncation guard to TRL 1.x _compute_logps refactor

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .../test_trl_grpo_pinned_symbols.py           | 20 ++++---
 unsloth/models/rl_replacements.py             | 57 +++++++++++++++++++
 2 files changed, 69 insertions(+), 8 deletions(-)

diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index 4c7dcc4234..8f1435ba5f 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -551,12 +551,12 @@ def test_trl_grpo_source_inference_mode_unwrap(tag: str):
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
 def test_trl_kto_get_batch_logps_signature(tag: str):
-    """TRL 0.27+ moved KTOTrainer to trl.experimental.kto and the
-    canonical kto_trainer.py shrank to a thin re-export wrapper. The
-    real `get_batch_logps` lives at trl/experimental/kto/kto_trainer.py.
-    Unsloth's MRO walk in models/rl.py:592-708 already follows
-    trl.experimental.* parents, so either path is fine — we just
-    require the symbol to exist SOMEWHERE."""
+    """KTO log-prob computation must stay patchable. Through TRL 1.x the
+    target was KTOTrainer.get_batch_logps; TRL 1.x dropped it and moved the
+    math into _compute_logps / compute_ref_log_probs calling
+    selective_log_softmax. unsloth/models/rl_replacements.py patches BOTH
+    shapes (kto_trainer_get_batch_logps + kto_trainer_align_completion_logps),
+    so we require EITHER form to exist wherever KTOTrainer lives."""
     candidates = [
         "trl/trainer/kto_trainer.py",
         "trl/experimental/kto/kto_trainer.py",
@@ -566,11 +566,15 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         src = fetch_text("huggingface/trl", tag, path)
         if src is None:
             continue
+        # Legacy: explicit get_batch_logps method.
         if has_def(src, "get_batch_logps", "func"):
             return
+        # TRL 1.x: refactored into _compute_logps + selective_log_softmax.
+        if has_def(src, "_compute_logps", "func") and "selective_log_softmax" in src:
+            return
     pytest.fail(
-        f"{tag}: KTOTrainer.get_batch_logps not found in any of {candidates}; "
-        f"unsloth/models/rl_replacements.py:1675 rewrite silently skipped"
+        f"{tag}: KTO log-prob computation not found in any of {candidates}; "
+        f"unsloth/models/rl_replacements.py KTO rewrite silently skipped"
     )
 
 
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 31d54675c9..c1d92a31c4 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -1962,6 +1962,63 @@ def kto_trainer_get_batch_logps(function_name, function):
 RL_FUNCTIONS["kto_trainer"].append(kto_trainer_get_batch_logps)
 
 
+# TRL 1.x dropped KTOTrainer.get_batch_logps and moved the log-prob math into
+# _compute_logps / compute_ref_log_probs / _compute_kl_logps, which call
+# selective_log_softmax on completion-only tokens. Same truncation hazard as
+# above, so clamp logits/ids/mask to the shorter seq length (no-op when equal).
+_KTO_COMPLETION_RE = re.compile(
+    r"(?P<ws>[ \t]*)shift_logits = completion_logits\[:, :-1, :\]\.contiguous\(\)\n"
+    r"(?P=ws)per_token_logps = selective_log_softmax\(\s*shift_logits,\s*"
+    r"(?P<var>\w+)\[\"completion_input_ids\"\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
+    r"(?P=ws)per_token_logps\[(?P=var)\[\"completion_mask\"\]\[:, 1:\] == 0\] = 0\.0"
+)
+_KTO_KL_RE = re.compile(
+    r"(?P<ws>[ \t]*)shift_KL_logits = KL_logits\[:, :-1, :\]\.contiguous\(\)\n"
+    r"(?P=ws)KL_per_token_logps = selective_log_softmax\(\s*shift_KL_logits,\s*"
+    r"(?P<var>\w+)\[\"KL_completion_input_ids\"\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
+    r"(?P=ws)KL_per_token_logps\[(?P=var)\[\"KL_completion_mask\"\]\[:, 1:\] == 0\] = 0\.0"
+)
+
+
+def _kto_completion_repl(m):
+    ws, var = m.group("ws"), m.group("var")
+    return (
+        f"{ws}shift_logits = completion_logits[:, :-1, :].contiguous()\n"
+        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
+        f'{ws}_uns_ids = {var}["completion_input_ids"][:, 1:].contiguous()\n'
+        f"{ws}_uns_n = min(shift_logits.shape[1], _uns_ids.shape[1])\n"
+        f"{ws}per_token_logps = selective_log_softmax(shift_logits[:, :_uns_n], _uns_ids[:, :_uns_n])\n"
+        f'{ws}per_token_logps[{var}["completion_mask"][:, 1:][:, :_uns_n] == 0] = 0.0'
+    )
+
+
+def _kto_kl_repl(m):
+    ws, var = m.group("ws"), m.group("var")
+    return (
+        f"{ws}shift_KL_logits = KL_logits[:, :-1, :].contiguous()\n"
+        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
+        f'{ws}_uns_kl_ids = {var}["KL_completion_input_ids"][:, 1:].contiguous()\n'
+        f"{ws}_uns_kl_n = min(shift_KL_logits.shape[1], _uns_kl_ids.shape[1])\n"
+        f"{ws}KL_per_token_logps = selective_log_softmax(shift_KL_logits[:, :_uns_kl_n], _uns_kl_ids[:, :_uns_kl_n])\n"
+        f'{ws}KL_per_token_logps[{var}["KL_completion_mask"][:, 1:][:, :_uns_kl_n] == 0] = 0.0'
+    )
+
+
+def kto_trainer_align_completion_logps(function_name, function):
+    if function_name not in (
+        "_compute_logps",
+        "compute_ref_log_probs",
+        "_compute_kl_logps",
+    ):
+        return function
+    function = _KTO_COMPLETION_RE.sub(_kto_completion_repl, function)
+    function = _KTO_KL_RE.sub(_kto_kl_repl, function)
+    return function
+
+
+RL_FUNCTIONS["kto_trainer"].append(kto_trainer_align_completion_logps)
+
+
 # https://github.com/huggingface/trl/blob/main/trl/trainer/grpo_trainer.py#L356
 # TRL warns if batch size is not a multiple of num_generations -> fix this.
 def grpo_trainer_fix_batch_size(RLTrainer_source, RLConfig_source):

From 4eac5272476372b37febdbfc541076ab4355f72f Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 00:08:19 -0700
Subject: [PATCH 086/222] CI: mark deepseek_ocr2 as known-broken compile
 timeout (#5995)

---
 .github/workflows/consolidated-tests-ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index f8eccc7d18..94ec26ef31 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -990,6 +990,7 @@ jobs:
               # First seen on transformers >=5,<6; each represents a slow
               # or recursive source-rewriter path the zoo can address.
               "beit":            "TimeoutError: compile exceeds per-model budget",
+              "deepseek_ocr2":   "TimeoutError: compile exceeds per-model budget",
               "sam":             "TimeoutError: compile exceeds per-model budget",
               "sam_hq":          "TimeoutError: compile exceeds per-model budget",
           }

From b1ee492982791e02a55979866d1e3b2e90c8af9a Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 07:17:55 +0000
Subject: [PATCH 087/222] Revert "CI: mark deepseek_ocr2 as known-broken
 compile timeout (#5995)"

This reverts commit 4eac5272476372b37febdbfc541076ab4355f72f.
---
 .github/workflows/consolidated-tests-ci.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index 94ec26ef31..f8eccc7d18 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -990,7 +990,6 @@ jobs:
               # First seen on transformers >=5,<6; each represents a slow
               # or recursive source-rewriter path the zoo can address.
               "beit":            "TimeoutError: compile exceeds per-model budget",
-              "deepseek_ocr2":   "TimeoutError: compile exceeds per-model budget",
               "sam":             "TimeoutError: compile exceeds per-model budget",
               "sam_hq":          "TimeoutError: compile exceeds per-model budget",
           }

From 636455a7d6dad04a941ca58a93e2f27e01abc11b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 07:17:55 +0000
Subject: [PATCH 088/222] Revert "Port KTO logps truncation guard to TRL 1.x
 _compute_logps refactor (#5996)"

This reverts commit 157cecb25c3c7277a6da33c81a409373adb2b4b1.
---
 .../test_trl_grpo_pinned_symbols.py           | 20 +++----
 unsloth/models/rl_replacements.py             | 57 -------------------
 2 files changed, 8 insertions(+), 69 deletions(-)

diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index 8f1435ba5f..4c7dcc4234 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -551,12 +551,12 @@ def test_trl_grpo_source_inference_mode_unwrap(tag: str):
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
 def test_trl_kto_get_batch_logps_signature(tag: str):
-    """KTO log-prob computation must stay patchable. Through TRL 1.x the
-    target was KTOTrainer.get_batch_logps; TRL 1.x dropped it and moved the
-    math into _compute_logps / compute_ref_log_probs calling
-    selective_log_softmax. unsloth/models/rl_replacements.py patches BOTH
-    shapes (kto_trainer_get_batch_logps + kto_trainer_align_completion_logps),
-    so we require EITHER form to exist wherever KTOTrainer lives."""
+    """TRL 0.27+ moved KTOTrainer to trl.experimental.kto and the
+    canonical kto_trainer.py shrank to a thin re-export wrapper. The
+    real `get_batch_logps` lives at trl/experimental/kto/kto_trainer.py.
+    Unsloth's MRO walk in models/rl.py:592-708 already follows
+    trl.experimental.* parents, so either path is fine — we just
+    require the symbol to exist SOMEWHERE."""
     candidates = [
         "trl/trainer/kto_trainer.py",
         "trl/experimental/kto/kto_trainer.py",
@@ -566,15 +566,11 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         src = fetch_text("huggingface/trl", tag, path)
         if src is None:
             continue
-        # Legacy: explicit get_batch_logps method.
         if has_def(src, "get_batch_logps", "func"):
             return
-        # TRL 1.x: refactored into _compute_logps + selective_log_softmax.
-        if has_def(src, "_compute_logps", "func") and "selective_log_softmax" in src:
-            return
     pytest.fail(
-        f"{tag}: KTO log-prob computation not found in any of {candidates}; "
-        f"unsloth/models/rl_replacements.py KTO rewrite silently skipped"
+        f"{tag}: KTOTrainer.get_batch_logps not found in any of {candidates}; "
+        f"unsloth/models/rl_replacements.py:1675 rewrite silently skipped"
     )
 
 
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index c1d92a31c4..31d54675c9 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -1962,63 +1962,6 @@ def kto_trainer_get_batch_logps(function_name, function):
 RL_FUNCTIONS["kto_trainer"].append(kto_trainer_get_batch_logps)
 
 
-# TRL 1.x dropped KTOTrainer.get_batch_logps and moved the log-prob math into
-# _compute_logps / compute_ref_log_probs / _compute_kl_logps, which call
-# selective_log_softmax on completion-only tokens. Same truncation hazard as
-# above, so clamp logits/ids/mask to the shorter seq length (no-op when equal).
-_KTO_COMPLETION_RE = re.compile(
-    r"(?P<ws>[ \t]*)shift_logits = completion_logits\[:, :-1, :\]\.contiguous\(\)\n"
-    r"(?P=ws)per_token_logps = selective_log_softmax\(\s*shift_logits,\s*"
-    r"(?P<var>\w+)\[\"completion_input_ids\"\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
-    r"(?P=ws)per_token_logps\[(?P=var)\[\"completion_mask\"\]\[:, 1:\] == 0\] = 0\.0"
-)
-_KTO_KL_RE = re.compile(
-    r"(?P<ws>[ \t]*)shift_KL_logits = KL_logits\[:, :-1, :\]\.contiguous\(\)\n"
-    r"(?P=ws)KL_per_token_logps = selective_log_softmax\(\s*shift_KL_logits,\s*"
-    r"(?P<var>\w+)\[\"KL_completion_input_ids\"\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
-    r"(?P=ws)KL_per_token_logps\[(?P=var)\[\"KL_completion_mask\"\]\[:, 1:\] == 0\] = 0\.0"
-)
-
-
-def _kto_completion_repl(m):
-    ws, var = m.group("ws"), m.group("var")
-    return (
-        f"{ws}shift_logits = completion_logits[:, :-1, :].contiguous()\n"
-        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
-        f'{ws}_uns_ids = {var}["completion_input_ids"][:, 1:].contiguous()\n'
-        f"{ws}_uns_n = min(shift_logits.shape[1], _uns_ids.shape[1])\n"
-        f"{ws}per_token_logps = selective_log_softmax(shift_logits[:, :_uns_n], _uns_ids[:, :_uns_n])\n"
-        f'{ws}per_token_logps[{var}["completion_mask"][:, 1:][:, :_uns_n] == 0] = 0.0'
-    )
-
-
-def _kto_kl_repl(m):
-    ws, var = m.group("ws"), m.group("var")
-    return (
-        f"{ws}shift_KL_logits = KL_logits[:, :-1, :].contiguous()\n"
-        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
-        f'{ws}_uns_kl_ids = {var}["KL_completion_input_ids"][:, 1:].contiguous()\n'
-        f"{ws}_uns_kl_n = min(shift_KL_logits.shape[1], _uns_kl_ids.shape[1])\n"
-        f"{ws}KL_per_token_logps = selective_log_softmax(shift_KL_logits[:, :_uns_kl_n], _uns_kl_ids[:, :_uns_kl_n])\n"
-        f'{ws}KL_per_token_logps[{var}["KL_completion_mask"][:, 1:][:, :_uns_kl_n] == 0] = 0.0'
-    )
-
-
-def kto_trainer_align_completion_logps(function_name, function):
-    if function_name not in (
-        "_compute_logps",
-        "compute_ref_log_probs",
-        "_compute_kl_logps",
-    ):
-        return function
-    function = _KTO_COMPLETION_RE.sub(_kto_completion_repl, function)
-    function = _KTO_KL_RE.sub(_kto_kl_repl, function)
-    return function
-
-
-RL_FUNCTIONS["kto_trainer"].append(kto_trainer_align_completion_logps)
-
-
 # https://github.com/huggingface/trl/blob/main/trl/trainer/grpo_trainer.py#L356
 # TRL warns if batch size is not a multiple of num_generations -> fix this.
 def grpo_trainer_fix_batch_size(RLTrainer_source, RLConfig_source):

From 63dc27f76e00128807b400f91bbe96e37427e64f Mon Sep 17 00:00:00 2001
From: Long Yixing <longyixing331@gmail.com>
Date: Thu, 4 Jun 2026 15:38:45 +0800
Subject: [PATCH 089/222] fix(studio): disable mlx gc for none (#5991)

---
 studio/backend/core/training/worker.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index a825321597..e4ef95a375 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1362,7 +1362,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
     gc_setting = config.get("gradient_checkpointing", "mlx")
     if isinstance(gc_setting, str):
         use_grad_checkpoint = (
-            gc_setting if gc_setting.lower() not in ("false", "") else False
+            gc_setting if gc_setting.lower() not in ("false", "none", "") else False
         )
     else:
         use_grad_checkpoint = gc_setting

From 0425a3c0a1d69e0a99b1436249d012e9703198fd Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 00:39:29 -0700
Subject: [PATCH 090/222] Normalize shell scripts to LF in .gitattributes
 (#5997)

Shell scripts are stored as LF in git, but without an eol rule a Windows
clone with core.autocrlf=true checks them out as CRLF. The trailing \r then
breaks them when run in WSL/Linux -- e.g. `set -e` becomes `set -e\r` and
dash/sh aborts with "set: Illegal option -". This bites developers who clone
on Windows and run the repo's *.sh directly in WSL, increasingly common with
the AMD Strix Halo ROCm-on-WSL support.

Add `*.sh text eol=lf` so every shell script always checks out with LF
regardless of the contributor's platform or core.autocrlf setting. All
tracked *.sh use Unix shebangs; none need CRLF. PowerShell/batch scripts are
left untouched -- they tolerate LF and are unaffected by this bug.

Verified with `git ls-files --eol`: every *.sh now resolves to
i/lf w/lf attr/text eol=lf.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitattributes | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.gitattributes b/.gitattributes
index 264fdfd02f..75fba5d6ab 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,7 @@
 # Normalize Python files to LF line endings
 *.py text eol=lf
+
+# Always check out shell scripts with LF endings. Without this rule a Windows
+# clone (core.autocrlf=true) rewrites them to CRLF, and the trailing \r breaks
+# them when run in WSL/Linux (e.g. `set -e` -> "set: Illegal option -").
+*.sh text eol=lf

From 4c06c1dcc771f3d4f2aecc8d3ab77f2e01aa9107 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 4 Jun 2026 00:56:53 -0700
Subject: [PATCH 091/222] Studio: enable audio input for Gemma 4 GGUFs; default
 chat model to Qwen3.5-4B-MTP (#6000)

* Studio: enable audio input for Gemma 4 GGUF models

Audio file upload was disabled for Gemma 4 vision+audio GGUFs (e.g.
gemma-4-12b-it-GGUF) even though their mmproj carries an audio encoder
(clip.has_audio_encoder, gemma4ua). Two causes:

- Audio-input detection only matched Gemma 3n's <audio_soft_token>;
  Gemma 4 uses <|audio|>, so audio_vlm was never detected.
- The GGUF load/status responses hardcoded has_audio_input=False, so the
  flag was dropped even when audio_vlm was detected (affected Gemma 3n
  GGUFs too).

Changes:
- Recognize <|audio|> alongside <audio_soft_token> in the llama-server
  token probe and the tokenizer-config pattern.
- Read clip.has_audio_encoder from the mmproj as an independent,
  model-agnostic signal (read_mmproj_audio_capability).
- Emit the computed has_audio_input on the GGUF load/status responses.
- Tests for the new pattern and the mmproj reader.

* Studio: default chat model and dataset helper to Qwen3.5-4B-MTP

Switch the auto-loaded chat default and the dataset-analysis helper GGUF
from gemma-4-E2B-it to unsloth/Qwen3.5-4B-MTP-GGUF (UD-Q4_K_XL).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    | 37 ++++++++-
 studio/backend/routes/inference.py            |  6 +-
 .../tests/test_audio_token_detection.py       | 46 +++++++++++
 studio/backend/tests/test_gguf_metadata.py    | 67 +++++++++++++++-
 studio/backend/utils/datasets/llm_assist.py   |  2 +-
 studio/backend/utils/models/gguf_metadata.py  | 78 +++++++++++++++++++
 studio/backend/utils/models/model_config.py   |  3 +-
 .../src/features/chat/api/chat-adapter.ts     | 16 ++--
 8 files changed, 240 insertions(+), 15 deletions(-)
 create mode 100644 studio/backend/tests/test_audio_token_detection.py

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 7bcf02dc35..0f23549138 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -697,6 +697,9 @@ class LlamaCppBackend:
         self._is_audio: bool = False
         self._audio_type: Optional[str] = None
         self._audio_probed: bool = False
+        # Audio INPUT capability (distinct from _is_audio, which is TTS output).
+        self._has_audio_input: bool = False
+        self._mmproj_has_audio: bool = False  # clip.has_audio_encoder, set at load
         # Monotonic timestamp set in _kill_process; read by load_model
         # to decide whether to wait for the VRAM reclaim to finish.
         self._last_kill_monotonic: float = 0.0
@@ -2782,6 +2785,12 @@ class LlamaCppBackend:
                             if not self._healthy:
                                 return False
                             self._audio_type = detected
+                    # Re-derive after a retried probe (_mmproj_has_audio persists).
+                    from utils.models.model_config import is_audio_input_type
+
+                    self._has_audio_input = bool(
+                        is_audio_input_type(self._audio_type)
+                    ) or bool(self._mmproj_has_audio)
                 if not self._healthy:
                     return False
                 return True
@@ -3095,6 +3104,21 @@ class LlamaCppBackend:
                         "image input will be disabled for this session"
                     )
 
+                # Audio input straight from the mmproj (clip.has_audio_encoder),
+                # independent of token names.
+                self._mmproj_has_audio = False
+                if launch_mmproj_path:
+                    try:
+                        from utils.models.gguf_metadata import (
+                            read_mmproj_audio_capability,
+                        )
+
+                        self._mmproj_has_audio = bool(
+                            read_mmproj_audio_capability(launch_mmproj_path)
+                        )
+                    except Exception as e:
+                        logger.debug(f"mmproj audio-capability read failed: {e}")
+
                 cmd = [
                     binary,
                     "-m",
@@ -3527,6 +3551,7 @@ class LlamaCppBackend:
             self._is_audio = False
             self._audio_type = None
             self._audio_probed = False
+            self._has_audio_input = False
             try:
                 detected = self._detect_audio_type_strict()
                 self._audio_probed = True
@@ -3558,6 +3583,13 @@ class LlamaCppBackend:
                         return False
                     self._audio_type = detected
 
+            # Audio input = token probe (audio_vlm/whisper) OR mmproj audio encoder.
+            from utils.models.model_config import is_audio_input_type
+
+            self._has_audio_input = bool(is_audio_input_type(self._audio_type)) or bool(
+                self._mmproj_has_audio
+            )
+
             if not self._healthy:
                 return False
             return True
@@ -3901,6 +3933,8 @@ class LlamaCppBackend:
             self._is_audio = False
             self._audio_type = None
             self._audio_probed = False
+            self._has_audio_input = False
+            self._mmproj_has_audio = False
             self._port = None
             self._healthy = False
             self._context_length = None
@@ -5591,7 +5625,8 @@ class LlamaCppBackend:
                 return "csm"
             if len(_tok("<|startoftranscript|>")) == 1:
                 return "whisper"
-            if len(_tok("<audio_soft_token>")) == 1:
+            # Gemma 3n: <audio_soft_token>; Gemma 4: <|audio|> (not csm's <|AUDIO|>).
+            if len(_tok("<audio_soft_token>")) == 1 or len(_tok("<|audio|>")) == 1:
                 return "audio_vlm"
             if (
                 len(_tok("<|bicodec_semantic_0|>")) == 1
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 2964a0801f..15d73405cb 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -794,7 +794,7 @@ async def load_model(
                     is_gguf = True,
                     is_audio = _gguf_is_audio,
                     audio_type = _gguf_audio,
-                    has_audio_input = False,
+                    has_audio_input = getattr(llama_backend, "_has_audio_input", False),
                     inference = inference_config,
                     requires_trust_remote_code = bool(
                         inference_config.get("trust_remote_code", False)
@@ -1044,7 +1044,7 @@ async def load_model(
                 is_gguf = True,
                 is_audio = _gguf_is_audio,
                 audio_type = _gguf_audio,
-                has_audio_input = False,
+                has_audio_input = llama_backend._has_audio_input,
                 inference = inference_config,
                 requires_trust_remote_code = bool(
                     inference_config.get("trust_remote_code", False)
@@ -1531,7 +1531,7 @@ async def get_status(
                 gguf_variant = llama_backend.hf_variant,
                 is_audio = getattr(llama_backend, "_is_audio", False),
                 audio_type = _audio_type,
-                has_audio_input = False,
+                has_audio_input = getattr(llama_backend, "_has_audio_input", False),
                 loading = [],
                 loaded = [_display_model_id] if _display_model_id else [],
                 inference = _inference_cfg,
diff --git a/studio/backend/tests/test_audio_token_detection.py b/studio/backend/tests/test_audio_token_detection.py
new file mode 100644
index 0000000000..a3ea7c89a7
--- /dev/null
+++ b/studio/backend/tests/test_audio_token_detection.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for tokenizer-based audio_type detection patterns, covering both
+Gemma 3n (<audio_soft_token>) and Gemma 4 (<|audio|>) audio-input tokens."""
+
+from __future__ import annotations
+
+from utils.models.model_config import _AUDIO_TOKEN_PATTERNS, is_audio_input_type
+
+
+def _classify(tokens: list[str]) -> str | None:
+    """Mirror _detect_audio_from_tokenizer._check_token_patterns: first match
+    in dict order wins."""
+    for audio_type, check in _AUDIO_TOKEN_PATTERNS.items():
+        if check(tokens):
+            return audio_type
+    return None
+
+
+def test_gemma3n_audio_soft_token_is_audio_vlm():
+    assert (
+        _classify(["<bos>", "<audio_soft_token>", "<image_soft_token>"]) == "audio_vlm"
+    )
+
+
+def test_gemma4_pipe_audio_token_is_audio_vlm():
+    # Gemma 4 uses <|audio|> (and <|image|>) instead of *_soft_token.
+    assert _classify(["<bos>", "<|image|>", "<|audio|>"]) == "audio_vlm"
+
+
+def test_csm_uppercase_audio_not_classified_as_audio_vlm():
+    # csm uses uppercase <|AUDIO|> + <|audio_eos|>; must stay csm, not audio_vlm.
+    tokens = ["<|AUDIO|>", "<|audio_eos|>"]
+    assert _classify(tokens) == "csm"
+
+
+def test_audio_vlm_and_whisper_accept_audio_input():
+    assert is_audio_input_type("audio_vlm") is True
+    assert is_audio_input_type("whisper") is True
+    assert is_audio_input_type("snac") is False
+    assert is_audio_input_type(None) is False
+
+
+def test_non_audio_tokens_classify_none():
+    assert _classify(["<bos>", "<eos>", "<pad>"]) is None
diff --git a/studio/backend/tests/test_gguf_metadata.py b/studio/backend/tests/test_gguf_metadata.py
index cf1a17347f..e5040e306c 100644
--- a/studio/backend/tests/test_gguf_metadata.py
+++ b/studio/backend/tests/test_gguf_metadata.py
@@ -14,6 +14,7 @@ from utils.models.gguf_metadata import (
     is_mmproj_by_metadata,
     pairing_score,
     read_gguf_general_metadata,
+    read_mmproj_audio_capability,
 )
 
 
@@ -21,6 +22,7 @@ _GGUF_MAGIC = 0x46554747
 _VTYPE_STRING = 8
 _VTYPE_UINT32 = 4
 _VTYPE_ARRAY = 9
+_VTYPE_BOOL = 7
 
 
 def _enc_string(s: str) -> bytes:
@@ -38,6 +40,14 @@ def _enc_kv_uint32(key: str, value: int) -> bytes:
     )
 
 
+def _enc_kv_bool(key: str, value: bool) -> bytes:
+    return (
+        _enc_string(key)
+        + struct.pack("<I", _VTYPE_BOOL)
+        + struct.pack("<B", 1 if value else 0)
+    )
+
+
 def _enc_kv_string_array(key: str, values: Iterable[str]) -> bytes:
     vals = list(values)
     out = _enc_string(key) + struct.pack("<I", _VTYPE_ARRAY)
@@ -53,11 +63,18 @@ def _write_synthetic_gguf(
     *,
     extra_uint32: Mapping[str, int] | None = None,
     extra_string_arrays: Mapping[str, Iterable[str]] | None = None,
+    extra_bools: Mapping[str, bool] | None = None,
 ) -> Path:
     """Minimal GGUF: header + KV body, no tensors."""
     extra_uint32 = extra_uint32 or {}
     extra_string_arrays = extra_string_arrays or {}
-    kv_count = len(general_strings) + len(extra_uint32) + len(extra_string_arrays)
+    extra_bools = extra_bools or {}
+    kv_count = (
+        len(general_strings)
+        + len(extra_uint32)
+        + len(extra_string_arrays)
+        + len(extra_bools)
+    )
     body = b""
     for k, v in general_strings.items():
         body += _enc_kv_string(k, v)
@@ -65,6 +82,8 @@ def _write_synthetic_gguf(
         body += _enc_kv_uint32(k, v)
     for k, v in extra_string_arrays.items():
         body += _enc_kv_string_array(k, v)
+    for k, v in extra_bools.items():
+        body += _enc_kv_bool(k, v)
     header = struct.pack(
         "<IIQQ",
         _GGUF_MAGIC,
@@ -214,3 +233,49 @@ def test_pairing_score_no_overlap_returns_zero():
     assert pairing_score({"general.basename": "Foo"}, {}) == 0
     assert pairing_score({}, {"general.basename": "Foo"}) == 0
     assert pairing_score(None, {"general.basename": "Foo"}) == 0
+
+
+# --- read_mmproj_audio_capability --------------------------------------
+
+
+def test_mmproj_audio_capability_true(tmp_path: Path):
+    """clip.has_audio_encoder=True (e.g. Gemma 4's gemma4ua projector)."""
+    p = _write_synthetic_gguf(
+        tmp_path / "mmproj.gguf",
+        {"general.type": "mmproj"},
+        extra_bools = {
+            "clip.has_vision_encoder": True,
+            "clip.has_audio_encoder": True,
+        },
+    )
+    assert read_mmproj_audio_capability(str(p)) is True
+
+
+def test_mmproj_audio_capability_false(tmp_path: Path):
+    """Vision-only projector: key present but false."""
+    p = _write_synthetic_gguf(
+        tmp_path / "mmproj.gguf",
+        {"general.type": "mmproj"},
+        extra_bools = {
+            "clip.has_vision_encoder": True,
+            "clip.has_audio_encoder": False,
+        },
+    )
+    assert read_mmproj_audio_capability(str(p)) is False
+
+
+def test_mmproj_audio_capability_absent_returns_none(tmp_path: Path):
+    """Key absent (older/vision-only mmproj): None, not False."""
+    p = _write_synthetic_gguf(
+        tmp_path / "mmproj.gguf",
+        {"general.type": "mmproj"},
+        extra_bools = {"clip.has_vision_encoder": True},
+    )
+    assert read_mmproj_audio_capability(str(p)) is None
+
+
+def test_mmproj_audio_capability_missing_or_non_gguf(tmp_path: Path):
+    assert read_mmproj_audio_capability(str(tmp_path / "nope.gguf")) is None
+    junk = tmp_path / "garbage.gguf"
+    junk.write_bytes(b"not a gguf header at all")
+    assert read_mmproj_audio_capability(str(junk)) is None
diff --git a/studio/backend/utils/datasets/llm_assist.py b/studio/backend/utils/datasets/llm_assist.py
index 4c66d2ebf6..758717f76b 100644
--- a/studio/backend/utils/datasets/llm_assist.py
+++ b/studio/backend/utils/datasets/llm_assist.py
@@ -26,7 +26,7 @@ from loggers import get_logger
 
 logger = get_logger(__name__)
 
-DEFAULT_HELPER_MODEL_REPO = "unsloth/gemma-4-E2B-it-GGUF"
+DEFAULT_HELPER_MODEL_REPO = "unsloth/Qwen3.5-4B-MTP-GGUF"
 DEFAULT_HELPER_MODEL_VARIANT = "UD-Q4_K_XL"
 
 README_MAX_CHARS = 1500
diff --git a/studio/backend/utils/models/gguf_metadata.py b/studio/backend/utils/models/gguf_metadata.py
index 5629bac58b..dc9c21226e 100644
--- a/studio/backend/utils/models/gguf_metadata.py
+++ b/studio/backend/utils/models/gguf_metadata.py
@@ -47,6 +47,10 @@ _METADATA_CACHE: Dict[_CacheKey, Optional[Dict[str, str]]] = {}
 _CACHE_LOCK = threading.Lock()
 _CACHE_MAX_ENTRIES = 4096
 
+# Separate cache for single bool capability keys (e.g. clip.has_audio_encoder),
+# keyed by (file cache key, wanted key). None = key absent / file unreadable.
+_BOOL_CACHE: Dict[Tuple[_CacheKey, str], Optional[bool]] = {}
+
 
 def _cache_key(path: str) -> Optional[_CacheKey]:
     try:
@@ -193,6 +197,80 @@ def _skip_gguf_value(f, vtype: int) -> bool:
     return True
 
 
+def _parse_gguf_bool(path: str, wanted_key: str) -> Optional[bool]:
+    """Bool value of ``wanted_key`` (GGUF vtype 7), or ``None`` if absent /
+    unreadable. Mirrors ``_parse_gguf_header`` for a single bool key."""
+    try:
+        with open(path, "rb") as f:
+            head = f.read(24)
+            if len(head) < 24:
+                return None
+            magic, _version, _tcount, kv_count = struct.unpack("<IIQQ", head)
+            if magic != _GGUF_MAGIC:
+                return None
+
+            for _ in range(kv_count):
+                try:
+                    klen_bytes = f.read(8)
+                    if len(klen_bytes) < 8:
+                        break
+                    klen = struct.unpack("<Q", klen_bytes)[0]
+                    if klen > 1 << 20:  # 1 MB sanity bound
+                        break
+                    kbytes = f.read(klen)
+                    if len(kbytes) < klen:
+                        break
+                    key = kbytes.decode("utf-8", "replace")
+                    vt_bytes = f.read(4)
+                    if len(vt_bytes) < 4:
+                        break
+                    vtype = struct.unpack("<I", vt_bytes)[0]
+
+                    if key == wanted_key and vtype == 7:  # BOOL (1 byte)
+                        bbyte = f.read(1)
+                        if len(bbyte) < 1:
+                            break
+                        return bbyte[0] != 0
+                    if not _skip_gguf_value(f, vtype):
+                        break
+                except (struct.error, UnicodeDecodeError):
+                    break
+    except OSError as e:
+        logger.debug(f"_parse_gguf_bool: cannot open {path}: {e}")
+        return None
+    except Exception as e:
+        logger.debug(f"_parse_gguf_bool: parse failure on {path}: {e}")
+        return None
+    return None
+
+
+def _read_gguf_bool(path: str, wanted_key: str) -> Optional[bool]:
+    """Cached single-bool-key read, keyed by (path, mtime, size, wanted_key)."""
+    fkey = _cache_key(path)
+    if fkey is None:
+        return None
+    ckey = (fkey, wanted_key)
+    with _CACHE_LOCK:
+        if ckey in _BOOL_CACHE:
+            return _BOOL_CACHE[ckey]
+    result = _parse_gguf_bool(path, wanted_key)
+    with _CACHE_LOCK:
+        while len(_BOOL_CACHE) >= _CACHE_MAX_ENTRIES:
+            try:
+                _BOOL_CACHE.pop(next(iter(_BOOL_CACHE)))
+            except StopIteration:
+                break
+        _BOOL_CACHE[ckey] = result
+    return result
+
+
+def read_mmproj_audio_capability(path: str) -> Optional[bool]:
+    """``clip.has_audio_encoder`` from an mmproj GGUF (e.g. Gemma 4's gemma4ua):
+    ``True``/``False`` if present, ``None`` if absent / unreadable. Flags
+    audio-input models independently of tokenizer token names."""
+    return _read_gguf_bool(path, "clip.has_audio_encoder")
+
+
 def is_mmproj_by_metadata(meta: Optional[Dict[str, str]]) -> Optional[bool]:
     """True/False from ``general.type``; None means fall back to filename."""
     if not meta:
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index dc34444ccb..b488a19953 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -814,7 +814,8 @@ _audio_detection_cache: Dict[str, Optional[str]] = {}
 _AUDIO_TOKEN_PATTERNS = {
     "csm": lambda tokens: "<|AUDIO|>" in tokens and "<|audio_eos|>" in tokens,
     "whisper": lambda tokens: "<|startoftranscript|>" in tokens,
-    "audio_vlm": lambda tokens: "<audio_soft_token>" in tokens,
+    # Gemma 3n: <audio_soft_token>; Gemma 4: <|audio|> (not csm's <|AUDIO|>).
+    "audio_vlm": lambda tokens: "<audio_soft_token>" in tokens or "<|audio|>" in tokens,
     "bicodec": lambda tokens: any(t.startswith("<|bicodec_") for t in tokens),
     "dac": lambda tokens: (
         "<|audio_start|>" in tokens
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 1fcbe7ff70..9a7f95df87 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -1149,13 +1149,13 @@ async function autoLoadSmallestModel(): Promise<{
     toast("Downloading a small model…", {
       id: toastId,
       description:
-        "No downloaded models found. Fetching Gemma-4-E2B-it (UD-Q4_K_XL).",
+        "No downloaded models found. Fetching Qwen3.5-4B-MTP (UD-Q4_K_XL).",
       duration: 30000,
     });
     try {
       if (
         !(await canAutoLoad({
-          model_path: "unsloth/gemma-4-E2B-it-GGUF",
+          model_path: "unsloth/Qwen3.5-4B-MTP-GGUF",
           max_seq_length: 0,
           is_lora: false,
           gguf_variant: "UD-Q4_K_XL",
@@ -1166,7 +1166,7 @@ async function autoLoadSmallestModel(): Promise<{
       }
       loadAttempts += 1;
       const loadResp = await loadModel({
-        model_path: "unsloth/gemma-4-E2B-it-GGUF",
+        model_path: "unsloth/Qwen3.5-4B-MTP-GGUF",
         hf_token: hfToken,
         max_seq_length: 0,
         load_in_4bit: true,
@@ -1176,7 +1176,7 @@ async function autoLoadSmallestModel(): Promise<{
       });
       useChatRuntimeStore
         .getState()
-        .setCheckpoint("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL");
+        .setCheckpoint("unsloth/Qwen3.5-4B-MTP-GGUF", "UD-Q4_K_XL");
       const store = useChatRuntimeStore.getState();
       store.setModelRequiresTrustRemoteCode(
         loadResp.requires_trust_remote_code ?? false,
@@ -1186,13 +1186,13 @@ async function autoLoadSmallestModel(): Promise<{
         maxTokens: loadResp.context_length ?? 131072,
       });
       const defaultModel: ChatModelSummary = {
-        id: "unsloth/gemma-4-E2B-it-GGUF",
-        name: loadResp.display_name ?? "gemma-4-E2B-it-GGUF",
+        id: "unsloth/Qwen3.5-4B-MTP-GGUF",
+        name: loadResp.display_name ?? "Qwen3.5-4B-MTP-GGUF",
         isVision: loadResp.is_vision ?? false,
         isLora: false,
         isGguf: true,
       };
-      if (!store.models.some((m) => m.id === "unsloth/gemma-4-E2B-it-GGUF")) {
+      if (!store.models.some((m) => m.id === "unsloth/Qwen3.5-4B-MTP-GGUF")) {
         store.setModels([...store.models, defaultModel]);
       }
       useChatRuntimeStore.setState({
@@ -1212,7 +1212,7 @@ async function autoLoadSmallestModel(): Promise<{
         chatTemplateOverride: null,
         loadedIsMultimodal: isMultimodalResponse(loadResp),
       });
-      toast.success("Loaded Gemma-4-E2B-it (UD-Q4_K_XL)", { id: toastId });
+      toast.success("Loaded Qwen3.5-4B-MTP (UD-Q4_K_XL)", { id: toastId });
       return { loaded: true, blockedByTrustRemoteCode: false };
     } catch {
       toast.dismiss(toastId);

From 2b51bec946d56962cadf6e6ef6bb129f30ce48d9 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Fri, 5 Jun 2026 01:54:30 -0700
Subject: [PATCH 092/222] Fix chat text cutoff at composer dock and speed up
 plus icon spin (#5989)

The composer dock backdrop was a solid block with a hard top edge, so
chat text scrolling underneath got visibly clipped. Replace it with a
gradient that fades the top 28px to transparent.

Also shorten the plus to x rotation in the composer from 300ms to 250ms,
including the reduced motion override.
---
 studio/frontend/src/components/assistant-ui/thread.tsx | 3 ++-
 studio/frontend/src/index.css                          | 4 ++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 83057074ba..a55c89f634 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -380,9 +380,10 @@ const ThreadComposerDock: FC<{
         overlay ? "z-40" : "z-20",
       )}
     >
+      {/* Fade the top edge so scrolling text is not cut off by a hard line. */}
       <div
         aria-hidden={true}
-        className="absolute inset-x-0 bottom-0 top-[10px] bg-background"
+        className="absolute inset-x-0 bottom-0 top-[10px] bg-gradient-to-t from-background from-[calc(100%_-_28px)] to-transparent"
       />
       <div className="relative px-5 pb-2">
         <div className="pointer-events-auto mx-auto w-full max-w-(--thread-max-width)">
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 70dee1dcd7..b6c5ac04e7 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -1140,7 +1140,7 @@
 	/* Open menu rotates the plus 45deg into an x. Ease-in-out for a smooth
 	   spin; keep it at 45deg so it never passes back through a "+". */
 	.unsloth-composer-plus svg {
-		transition: transform 300ms cubic-bezier(0.65, 0, 0.35, 1);
+		transition: transform 250ms cubic-bezier(0.65, 0, 0.35, 1);
 		will-change: transform;
 	}
 
@@ -2009,6 +2009,6 @@
 	/* Keep the plus/x morph animating under reduced motion (small rotation,
 	   like the spinners above). */
 	.unsloth-composer-plus svg {
-		transition-duration: 300ms !important;
+		transition-duration: 250ms !important;
 	}
 }

From 9f1d029c18d94ba253f6efca5a52a28f806028f3 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Fri, 5 Jun 2026 01:55:03 -0700
Subject: [PATCH 093/222] Studio: refine tool call and reasoning trigger UI
 (#5873)

* Studio: refine tool call and reasoning trigger UI

Tool call triggers:
- Chevron fades in on hover or keyboard focus and sits next to the
  label instead of being pinned to the right edge, matching the other
  collapsible triggers.
- Labels wrap instead of truncating so long tool names and search
  queries stay fully readable.
- Smaller chevron for a lighter look.

Reasoning trigger:
- Smaller chevron to match.
- Thinking box drops its bottom padding and raises the streaming max
  height so more of the thinking text is visible.

* Studio: pointer cursors and sidebar 3-dots polish

Collapsible triggers:
- Pointer cursor on the reasoning, tool call, and tool group triggers
  so they read as clickable.

Chat sidebar:
- Swap the chat row 3-dots menu to the vertical more-vertical icon.
- Pointer cursor on the chat row and its menu button.
- Chat row right padding opens up on hover (pr-4 at rest, pr-8 on
  hover) so the title keeps a comfortable gap and clears the menu.

* studio: refine tool-call spinner, chevron, and reasoning spacing

- Use the lucide arc spinner for running tool calls and the app-wide
  Spinner, so loading states match the rest of the UI.
- Collapse long tool-call labels to a single line with an ellipsis,
  reveal the full label when the row is expanded, and fix the clipped
  descenders.
- Keep the collapse chevron next to the label and add top spacing above
  the reasoning trigger.
- Remove the redundant nested spinner in the web search running state.

* Studio: drop tool call group background fill

The ghost tool call group used a translucent bg-muted/10 fill that read
as a faint lighter box around every group in dark mode. Remove the fill
and rounding so the group sits flush on the chat background.

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../src/components/assistant-ui/reasoning.tsx | 10 +++----
 .../assistant-ui/tool-call-spinner.tsx        | 21 +++++++++++++++
 .../components/assistant-ui/tool-fallback.tsx | 26 ++++++++++++-------
 .../components/assistant-ui/tool-group.tsx    | 16 +++++-------
 .../assistant-ui/tool-ui-code-execution.tsx   |  4 +--
 .../assistant-ui/tool-ui-python.tsx           |  5 ++--
 .../assistant-ui/tool-ui-terminal.tsx         |  5 ++--
 .../assistant-ui/tool-ui-web-search.tsx       |  5 ++--
 studio/frontend/src/components/ui/spinner.tsx | 20 ++++++++------
 studio/frontend/src/index.css                 | 18 +++++++++++++
 10 files changed, 89 insertions(+), 41 deletions(-)
 create mode 100644 studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx

diff --git a/studio/frontend/src/components/assistant-ui/reasoning.tsx b/studio/frontend/src/components/assistant-ui/reasoning.tsx
index 285b87d138..633c3bc3e9 100644
--- a/studio/frontend/src/components/assistant-ui/reasoning.tsx
+++ b/studio/frontend/src/components/assistant-ui/reasoning.tsx
@@ -33,7 +33,7 @@ import {
 const ANIMATION_DURATION = 200;
 const AUTO_SCROLL_THRESHOLD_PX = 24;
 
-export const reasoningVariants = cva("aui-reasoning-root mb-4 w-full", {
+export const reasoningVariants = cva("aui-reasoning-root mt-3 mb-4 w-full", {
   variants: {
     variant: {
       outline: "rounded-lg border px-3 py-2",
@@ -121,7 +121,7 @@ function ReasoningTrigger({
     <CollapsibleTrigger
       data-slot="reasoning-trigger"
       className={cn(
-        "aui-reasoning-trigger group/trigger flex min-w-0 flex-1 items-center gap-2 py-1 text-muted-foreground text-sm transition-colors hover:text-foreground",
+        "aui-reasoning-trigger group/trigger flex min-w-0 flex-1 cursor-pointer items-center gap-2 py-1 text-muted-foreground text-sm transition-colors hover:text-foreground",
         className,
       )}
       {...props}
@@ -140,7 +140,7 @@ function ReasoningTrigger({
       <ChevronDownIcon
         data-slot="reasoning-trigger-chevron"
         className={cn(
-          "aui-reasoning-trigger-chevron mt-0.5 size-4 shrink-0",
+          "aui-reasoning-trigger-chevron mt-0.5 size-3.5 shrink-0",
           "transition-transform duration-(--animation-duration) ease-out",
           "group-data-[state=closed]/trigger:-rotate-90",
           "group-data-[state=open]/trigger:rotate-0",
@@ -241,8 +241,8 @@ function ReasoningText({
       ref={scrollRef}
       data-slot="reasoning-text"
       className={cn(
-        "aui-reasoning-text relative z-0 overflow-y-auto pt-2 pb-2 pl-0 leading-relaxed",
-        streaming ? "max-h-32" : "max-h-64",
+        "aui-reasoning-text relative z-0 overflow-y-auto pt-2 pb-0 pl-0 leading-relaxed",
+        streaming ? "max-h-64" : "",
         "transform-gpu transition-[transform,opacity]",
         "group-data-[state=open]/collapsible-content:animate-in",
         "group-data-[state=closed]/collapsible-content:animate-out",
diff --git a/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx b/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx
new file mode 100644
index 0000000000..bc91408789
--- /dev/null
+++ b/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { Loader2Icon } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Spinner shown while a tool call is running: a clean circular arc with a
+ * rounded cap (lucide Loader2 / LoaderCircle), animated. Inherits the current
+ * text color so it matches the surrounding font.
+ */
+export function ToolCallSpinner({ className }: { className?: string }) {
+  return (
+    <Loader2Icon
+      aria-label="Loading"
+      className={cn("size-4 shrink-0 animate-spin", className)}
+    />
+  );
+}
diff --git a/studio/frontend/src/components/assistant-ui/tool-fallback.tsx b/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
index 2ea87d63f3..eeb4c2059f 100644
--- a/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-fallback.tsx
@@ -8,6 +8,7 @@ import {
   CollapsibleContent,
   CollapsibleTrigger,
 } from "@/components/ui/collapsible";
+import { ToolCallSpinner } from "@/components/assistant-ui/tool-call-spinner";
 import { useCollapseScrollLock } from "@/hooks/use-collapse-scroll-lock";
 import { cn } from "@/lib/utils";
 import {
@@ -135,16 +136,13 @@ function ToolFallbackTrigger({
     <CollapsibleTrigger
       data-slot="tool-fallback-trigger"
       className={cn(
-        "aui-tool-fallback-trigger group/trigger flex w-full items-center gap-2 py-1.5 text-sm transition-colors",
+        "aui-tool-fallback-trigger group/trigger flex w-full cursor-pointer items-center gap-2 py-1.5 text-sm transition-colors",
         className,
       )}
       {...props}
     >
       {isRunning ? (
-        <StatusIcon
-          data-slot="tool-fallback-trigger-icon"
-          className="aui-tool-fallback-trigger-icon size-4 shrink-0 animate-spin"
-        />
+        <ToolCallSpinner className="aui-tool-fallback-trigger-icon" />
       ) : ToolIcon ? (
         <ToolIcon
           data-slot="tool-fallback-trigger-icon"
@@ -165,11 +163,16 @@ function ToolFallbackTrigger({
       <span
         data-slot="tool-fallback-trigger-label"
         className={cn(
-          "aui-tool-fallback-trigger-label-wrapper relative min-w-0 grow text-left leading-none text-muted-foreground",
+          "aui-tool-fallback-trigger-label-wrapper relative min-w-0 text-left leading-none text-muted-foreground",
           isCancelled && "text-muted-foreground line-through",
         )}
       >
-        <span className="block truncate">
+        <span
+          className={cn(
+            "block truncate leading-normal",
+            "group-data-[state=open]/trigger:overflow-visible group-data-[state=open]/trigger:whitespace-normal group-data-[state=open]/trigger:break-words",
+          )}
+        >
           {label}:{" "}
           <span className="font-medium text-foreground/85">{displayName}</span>
         </span>
@@ -177,7 +180,10 @@ function ToolFallbackTrigger({
           <span
             aria-hidden={true}
             data-slot="tool-fallback-trigger-shimmer"
-            className="aui-tool-fallback-trigger-shimmer shimmer pointer-events-none absolute inset-0 block truncate motion-reduce:animate-none"
+            className={cn(
+              "aui-tool-fallback-trigger-shimmer shimmer pointer-events-none absolute inset-0 block truncate leading-normal motion-reduce:animate-none",
+              "group-data-[state=open]/trigger:overflow-visible group-data-[state=open]/trigger:whitespace-normal group-data-[state=open]/trigger:break-words",
+            )}
           >
             {label}:{" "}
             <span className="font-medium text-foreground/85">{displayName}</span>
@@ -187,8 +193,8 @@ function ToolFallbackTrigger({
       <ChevronDownIcon
         data-slot="tool-fallback-trigger-chevron"
         className={cn(
-          "aui-tool-fallback-trigger-chevron size-4 shrink-0",
-          "transition-transform duration-(--animation-duration) ease-out",
+          "aui-tool-fallback-trigger-chevron mr-1 size-3.5 shrink-0 self-center",
+          "transition-[transform,opacity] duration-(--animation-duration) ease-out",
           "group-data-[state=closed]/trigger:-rotate-90",
           "group-data-[state=open]/trigger:rotate-0",
         )}
diff --git a/studio/frontend/src/components/assistant-ui/tool-group.tsx b/studio/frontend/src/components/assistant-ui/tool-group.tsx
index 47d2b6cd0e..d30c0a8ee1 100644
--- a/studio/frontend/src/components/assistant-ui/tool-group.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-group.tsx
@@ -9,7 +9,7 @@ import {
   type PropsWithChildren,
 } from "react";
 import { useAuiState } from "@assistant-ui/react";
-import { ChevronDownIcon, LoaderIcon } from "lucide-react";
+import { ChevronDownIcon } from "lucide-react";
 import { Wrench01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { cva, type VariantProps } from "class-variance-authority";
@@ -20,6 +20,7 @@ import {
 } from "@/components/ui/collapsible";
 import { useCollapseScrollLock } from "@/hooks/use-collapse-scroll-lock";
 import { cn } from "@/lib/utils";
+import { ToolCallSpinner } from "@/components/assistant-ui/tool-call-spinner";
 
 const ANIMATION_DURATION = 200;
 
@@ -27,7 +28,7 @@ const toolGroupVariants = cva("aui-tool-group-root group/tool-group w-full", {
   variants: {
     variant: {
       outline: "corner-squircle rounded-lg border py-3",
-      ghost: "rounded-lg bg-muted/10 py-2",
+      ghost: "py-2",
       muted:
         "corner-squircle rounded-lg border border-muted-foreground/30 bg-muted/30 py-3",
     },
@@ -113,7 +114,7 @@ function ToolGroupTrigger({
     <CollapsibleTrigger
       data-slot="tool-group-trigger"
       className={cn(
-        "aui-tool-group-trigger group/trigger flex w-full items-center gap-2 text-sm transition-colors",
+        "aui-tool-group-trigger group/trigger flex w-full cursor-pointer items-center gap-2 text-sm transition-colors",
         "group-data-[variant=outline]/tool-group-root:px-4",
         "group-data-[variant=muted]/tool-group-root:px-4",
         "group-data-[variant=ghost]/tool-group-root:px-0",
@@ -122,10 +123,7 @@ function ToolGroupTrigger({
       {...props}
     >
       {active ? (
-        <LoaderIcon
-          data-slot="tool-group-trigger-loader"
-          className="aui-tool-group-trigger-loader size-4 shrink-0 animate-spin"
-        />
+        <ToolCallSpinner className="aui-tool-group-trigger-loader" />
       ) : (
         <HugeiconsIcon
           icon={Wrench01Icon}
@@ -137,7 +135,7 @@ function ToolGroupTrigger({
       <span
         data-slot="tool-group-trigger-label"
         className={cn(
-          "aui-tool-group-trigger-label-wrapper relative inline-block grow text-left font-medium leading-none",
+          "aui-tool-group-trigger-label-wrapper relative inline-block text-left font-medium leading-none",
         )}
       >
         <span>{label}</span>
@@ -154,7 +152,7 @@ function ToolGroupTrigger({
       <ChevronDownIcon
         data-slot="tool-group-trigger-chevron"
         className={cn(
-          "aui-tool-group-trigger-chevron size-4 shrink-0",
+          "aui-tool-group-trigger-chevron size-3.5 shrink-0",
           "transition-transform duration-(--animation-duration) ease-out",
           "group-data-[state=closed]/trigger:-rotate-90",
           "group-data-[state=open]/trigger:rotate-0",
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
index b884c4d2d8..2573509c34 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
@@ -12,9 +12,9 @@ import {
   CheckIcon,
   CopyIcon,
   FileTextIcon,
-  LoaderIcon,
   TerminalIcon,
 } from "lucide-react";
+import { ToolCallSpinner } from "@/components/assistant-ui/tool-call-spinner";
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   ToolFallbackContent,
@@ -185,7 +185,7 @@ const CodeExecutionToolUIImpl: ToolCallMessagePartComponent = ({
       <ToolFallbackContent>
         {isRunning ? (
           <div className="flex items-center gap-2 text-sm text-muted-foreground">
-            <LoaderIcon className="size-3.5 animate-spin" />
+            <ToolCallSpinner className="size-3.5" />
             <span>{runningLabel}</span>
           </div>
         ) : resultText ? (
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
index ce15d3e440..642340bb5f 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
@@ -7,7 +7,8 @@ import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { getAuthToken } from "@/features/auth/session";
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { code as codePlugin } from "@streamdown/code";
-import { CheckIcon, CodeIcon, CopyIcon, LoaderIcon } from "lucide-react";
+import { CheckIcon, CodeIcon, CopyIcon } from "lucide-react";
+import { ToolCallSpinner } from "@/components/assistant-ui/tool-call-spinner";
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Streamdown } from "streamdown";
 import {
@@ -148,7 +149,7 @@ const PythonToolUIImpl: ToolCallMessagePartComponent = ({
           {/* Output */}
           {isRunning ? (
             <div className="mt-2 flex items-center gap-2 text-sm text-muted-foreground">
-              <LoaderIcon className="size-3.5 animate-spin" />
+              <ToolCallSpinner className="size-3.5" />
               <span>Running&hellip;</span>
             </div>
           ) : output ? (
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-terminal.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-terminal.tsx
index 1b1357ab3c..40cb28d4e4 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-terminal.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-terminal.tsx
@@ -5,7 +5,8 @@
 
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-import { CheckIcon, CopyIcon, LoaderIcon, TerminalIcon } from "lucide-react";
+import { CheckIcon, CopyIcon, TerminalIcon } from "lucide-react";
+import { ToolCallSpinner } from "@/components/assistant-ui/tool-call-spinner";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import {
   ToolFallbackContent,
@@ -86,7 +87,7 @@ const TerminalToolUIImpl: ToolCallMessagePartComponent = ({
         <div className="border-l-2 border-muted-foreground/20 pl-2">
           {isRunning ? (
             <div className="flex items-center gap-2 text-sm text-muted-foreground">
-              <LoaderIcon className="size-3.5 animate-spin" />
+              <ToolCallSpinner className="size-3.5" />
               <span>Running&hellip;</span>
             </div>
           ) : output ? (
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
index b9bda2e832..ef8cb4a89b 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
@@ -4,7 +4,7 @@
 "use client";
 
 import { type ToolCallMessagePartComponent, useAuiState } from "@assistant-ui/react";
-import { GlobeIcon, LoaderIcon } from "lucide-react";
+import { GlobeIcon } from "lucide-react";
 import { memo, useEffect, useState } from "react";
 import { Source, SourceIcon, SourceTitle } from "./sources";
 import {
@@ -116,8 +116,7 @@ const WebSearchToolUIImpl: ToolCallMessagePartComponent = ({
       />
       <ToolFallbackContent>
         {isRunning ? (
-          <div className="flex items-center gap-2 text-sm text-muted-foreground">
-            <LoaderIcon className="size-3.5 animate-spin" />
+          <div className="flex items-center text-sm text-muted-foreground">
             <span>
               {isUrlFetch
                 ? <>Reading {displayDomain || "page"}&hellip;</>
diff --git a/studio/frontend/src/components/ui/spinner.tsx b/studio/frontend/src/components/ui/spinner.tsx
index 86eca0c4e6..283b4e21de 100644
--- a/studio/frontend/src/components/ui/spinner.tsx
+++ b/studio/frontend/src/components/ui/spinner.tsx
@@ -1,19 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import { cn } from "@/lib/utils"
+"use client";
 
+import { Loader2Icon } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+/**
+ * App-wide spinner: a clean circular arc with a rounded cap (lucide
+ * Loader2 / LoaderCircle), animated, inheriting the current text color.
+ */
 function Spinner({ className }: { className?: string }) {
   return (
-    <span
+    <Loader2Icon
       role="status"
       aria-label="Loading"
-      className={cn(
-        "inline-block size-4 shrink-0 animate-spin rounded-full border-2 border-current border-t-transparent",
-        className,
-      )}
+      className={cn("size-4 shrink-0 animate-spin", className)}
     />
-  )
+  );
 }
 
-export { Spinner }
+export { Spinner };
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index b6c5ac04e7..68993d4a65 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -2012,3 +2012,21 @@
 		transition-duration: 250ms !important;
 	}
 }
+
+/*
+ * Tool-call chevron visibility:
+ *  - A solo tool call (not wrapped in a multi-tool group) always shows its
+ *    collapsible chevron.
+ *  - When the tool call is part of a multi-tool group (.aui-tool-group-root),
+ *    the chevron stays hidden and only reveals on hover / keyboard focus.
+ */
+.aui-tool-fallback-trigger-chevron {
+  opacity: 1;
+}
+.aui-tool-group-root .aui-tool-fallback-trigger-chevron {
+  opacity: 0;
+}
+.aui-tool-group-root .aui-tool-fallback-trigger:hover .aui-tool-fallback-trigger-chevron,
+.aui-tool-group-root .aui-tool-fallback-trigger:focus-visible .aui-tool-fallback-trigger-chevron {
+  opacity: 1;
+}

From 5cdbfef3902a56a05a0518902215ec9b1728a861 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Fri, 5 Jun 2026 02:40:56 -0700
Subject: [PATCH 094/222] fix: warn when localhost resolves to ::1 but Studio
 is bound only to 127.0.0.1 (#5994)

* fix: warn when localhost resolves to ::1 but Studio is bound only to 127.0.0.1

* studio: fix localhost/::1 warning suppression and cover _run wiring

Addresses the Codex review on #5994 plus review-team findings:

- Remove the `_local_port_open("::1", port)` early-return. Studio binds
  127.0.0.1 only, so a successful connect to ::1:<port> means a *different*
  process is there -- exactly when http://localhost opens the wrong service
  and the user most needs the warning. Dropping the probe also removes the
  ~0.25s startup latency and the probe/warn race.
- Extract the banner/warning block from `_run` into `_emit_startup_output`
  so the wiring is unit-testable, and make the mismatch vs wildcard paths
  an explicit if/elif (they are mutually exclusive by construction).
- Hoist the `_working_local_url` confirmation out of the try block and
  reorder `_stdout_color_ok` before its only caller.
- Tests: add `_emit_startup_output` integration coverage (banner
  include_stop_hint, warning emission, single stop hint), a regression test
  that ::1 being occupied does NOT suppress the warning, dual-stack and
  non-positive-port cases; drop the unreachable `None` getaddrinfo arm.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Etherll <mrmrmidessam@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/run.py                        | 104 ++++++++-
 tests/studio/install/test_selection_logic.py | 228 +++++++++++++++++++
 2 files changed, 320 insertions(+), 12 deletions(-)

diff --git a/studio/backend/run.py b/studio/backend/run.py
index f401bc2ec1..7e84c41075 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -157,6 +157,56 @@ def _working_local_url(port: int) -> "str | None":
     return None
 
 
+def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
+    """Return the IPv4 loopback URL when localhost will not reach 127.0.0.1.
+
+    Local Studio intentionally binds to 127.0.0.1. On hosts where localhost
+    resolves to IPv6 only (::1), a browser pointed at http://localhost:<port>
+    fails -- or worse, reaches a different process listening on ::1 -- even
+    though http://127.0.0.1:<port> works. Return the IPv4 URL so the caller can
+    tell the user which address to open.
+    """
+    import socket
+
+    if bind_host != "127.0.0.1" or not port or port <= 0:
+        return None
+
+    ipv4_url = f"http://127.0.0.1:{port}"
+
+    # Only warn once Studio is confirmed answering on the IPv4 loopback.
+    if _working_local_url(port) != ipv4_url:
+        return None
+
+    try:
+        addr_info = socket.getaddrinfo(
+            "localhost", port, socket.AF_UNSPEC, socket.SOCK_STREAM
+        )
+    except Exception:
+        return None
+
+    if not addr_info:
+        return None
+
+    has_ipv4_loopback = False
+    has_ipv6_loopback = False
+    for family, _, _, _, sockaddr in addr_info:
+        if family == socket.AF_INET and sockaddr and sockaddr[0] == "127.0.0.1":
+            has_ipv4_loopback = True
+        elif family == socket.AF_INET6 and sockaddr:
+            host = sockaddr[0].split("%", 1)[0]
+            if host == "::1":
+                has_ipv6_loopback = True
+
+    # A successful connection to ::1 is NOT evidence that Studio is reachable
+    # there: Studio binds 127.0.0.1 only, so anything answering on ::1 is a
+    # different process -- which is exactly when the user must be steered to
+    # 127.0.0.1. Dual-stack localhost is fine (browsers fall back to 127.0.0.1
+    # when ::1 refuses), so only the IPv6-only case strands the user.
+    if has_ipv6_loopback and not has_ipv4_loopback:
+        return ipv4_url
+    return None
+
+
 def _stdout_color_ok() -> bool:
     """Whether to emit ANSI color codes on stdout. Mirrors startup_banner."""
     if os.environ.get("NO_COLOR", "").strip():
@@ -169,6 +219,20 @@ def _stdout_color_ok() -> bool:
         return False
 
 
+def _print_localhost_ipv6_mismatch_warning(local_url: str, port: int) -> None:
+    """Warn that localhost points at ::1 while Studio is bound to 127.0.0.1."""
+    use_color = _stdout_color_ok()
+    warn_c = "\033[38;5;215;1m" if use_color else ""
+    reset = "\033[0m" if use_color else ""
+
+    print(
+        f"{warn_c}  Warning: localhost resolves to IPv6 (::1), but Unsloth "
+        f"Studio is listening on 127.0.0.1 only. Open {local_url} instead of "
+        f"http://localhost:{port}.{reset}",
+        flush = True,
+    )
+
+
 def _verify_global_reachability(display_host: str, port: int) -> None:
     """Probe check-host.net to confirm display_host:port is reachable from the
     public internet. Synchronous so the caller can render output between the
@@ -334,6 +398,33 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
         pass
 
 
+def _emit_startup_output(host: str, port: int, display_host: str) -> None:
+    """Print the access banner plus any post-startup warnings.
+
+    Extracted from ``_run`` so the banner/warning wiring is unit-testable. The
+    ``localhost``-to-::1 mismatch warning and the wildcard reachability check
+    are mutually exclusive (the mismatch helper returns None for any non
+    127.0.0.1 bind, and wildcard binds are never 127.0.0.1), so the trailing
+    stop hint is emitted exactly once.
+    """
+    wildcard_bind = host in ("0.0.0.0", "::")
+    localhost_mismatch_url = _localhost_ipv6_mismatch_url(host, port)
+    # For wildcard binds, run the reachability check between the URL section
+    # and the stop hint so the stop hint stays last on screen.
+    print_studio_access_banner(
+        port = port,
+        bind_host = host,
+        display_host = display_host,
+        include_stop_hint = not wildcard_bind and not localhost_mismatch_url,
+    )
+    if localhost_mismatch_url:
+        _print_localhost_ipv6_mismatch_warning(localhost_mismatch_url, port)
+        print_studio_stop_hint()
+    elif wildcard_bind:
+        _verify_global_reachability(display_host, port)
+        print_studio_stop_hint()
+
+
 def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
     """Return (pid, process_name) of the process listening on *port*, or None.
 
@@ -823,18 +914,7 @@ def run_server(
         print(f"TAURI_PORT={port}", flush = True)
 
     if not silent:
-        wildcard_bind = host in ("0.0.0.0", "::")
-        # For wildcard binds, run the reachability check between the URL
-        # section and the stop hint so the stop hint stays last on screen.
-        print_studio_access_banner(
-            port = port,
-            bind_host = host,
-            display_host = display_host,
-            include_stop_hint = not wildcard_bind,
-        )
-        if wildcard_bind:
-            _verify_global_reachability(display_host, port)
-            print_studio_stop_hint()
+        _emit_startup_output(host, port, display_host)
 
     return app
 
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 2a94039018..f1c3130a77 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -11,7 +11,9 @@ No GPU, no network, no torch required -- all I/O is monkeypatched.
 """
 
 import importlib.util
+import socket
 import sys
+import types
 from pathlib import Path
 
 import pytest
@@ -19,6 +21,7 @@ import pytest
 
 PACKAGE_ROOT = Path(__file__).resolve().parents[3]
 MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+RUN_MODULE_PATH = PACKAGE_ROOT / "studio" / "backend" / "run.py"
 SPEC = importlib.util.spec_from_file_location(
     "studio_install_llama_prebuilt", MODULE_PATH
 )
@@ -91,6 +94,39 @@ resolve_simple_install_release_plans = (
 )
 
 
+def load_studio_run_module(monkeypatch):
+    logger = types.SimpleNamespace(
+        debug = lambda *a, **k: None,
+        info = lambda *a, **k: None,
+        warning = lambda *a, **k: None,
+    )
+    loggers = types.ModuleType("loggers")
+    loggers.get_logger = lambda name: logger
+    monkeypatch.setitem(sys.modules, "loggers", loggers)
+
+    startup_banner = types.ModuleType("startup_banner")
+    startup_banner.print_studio_access_banner = lambda **k: None
+    startup_banner.print_studio_stop_hint = lambda: None
+    monkeypatch.setitem(sys.modules, "startup_banner", startup_banner)
+
+    paths = types.ModuleType("utils.paths")
+    paths.__path__ = []
+    storage_roots = types.ModuleType("utils.paths.storage_roots")
+    storage_roots.studio_root = lambda: PACKAGE_ROOT / ".studio-test-root"
+    paths.storage_roots = storage_roots
+    monkeypatch.setitem(sys.modules, "utils.paths", paths)
+    monkeypatch.setitem(sys.modules, "utils.paths.storage_roots", storage_roots)
+    monkeypatch.syspath_prepend(str(RUN_MODULE_PATH.parent))
+
+    spec = importlib.util.spec_from_file_location(
+        "studio_backend_run_warning_test", RUN_MODULE_PATH
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
 # ---------------------------------------------------------------------------
 # Helper factories
 # ---------------------------------------------------------------------------
@@ -255,6 +291,198 @@ def mock_windows_runtime(monkeypatch, lines):
     )
 
 
+# ===========================================================================
+# Studio run.py localhost warning
+# ===========================================================================
+
+
+class TestStudioLocalhostIpv6Warning:
+    def _prepare_loopback(self, run_module, monkeypatch):
+        # Studio is confirmed answering on the IPv4 loopback.
+        monkeypatch.setattr(
+            run_module,
+            "_working_local_url",
+            lambda port: f"http://127.0.0.1:{port}",
+        )
+
+    def _set_getaddrinfo(self, monkeypatch, entries):
+        monkeypatch.setattr(socket, "getaddrinfo", lambda *a, **k: entries)
+
+    @staticmethod
+    def _ipv4(port = 8888):
+        return (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", port))
+
+    @staticmethod
+    def _ipv6(port = 8888):
+        return (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("::1", port, 0, 0))
+
+    # -- _localhost_ipv6_mismatch_url ------------------------------------
+
+    def test_ipv4_localhost_does_not_warn(self, monkeypatch):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [self._ipv4()])
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) is None
+
+    def test_dual_stack_localhost_does_not_warn(self, monkeypatch):
+        # localhost -> both ::1 and 127.0.0.1: browsers fall back to IPv4 when
+        # ::1 refuses, so the URL is reachable and no warning is needed.
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [self._ipv6(), self._ipv4()])
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) is None
+
+    def test_ipv6_only_localhost_returns_ipv4_url(self, monkeypatch, capsys):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [self._ipv6()])
+        monkeypatch.setattr(run_module, "_stdout_color_ok", lambda: False)
+
+        local_url = run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888)
+        assert local_url == "http://127.0.0.1:8888"
+
+        run_module._print_localhost_ipv6_mismatch_warning(local_url, 8888)
+        captured = capsys.readouterr()
+        assert "localhost resolves to IPv6 (::1)" in captured.out
+        assert "http://127.0.0.1:8888" in captured.out
+        assert "http://localhost:8888" in captured.out
+
+    def test_ipv6_listener_does_not_suppress_warning(self, monkeypatch):
+        # Regression for the Codex review: a process answering on ::1 is NOT
+        # Studio (Studio binds 127.0.0.1 only), so the warning must still fire
+        # -- that is exactly when http://localhost would open the wrong service.
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [self._ipv6()])
+        # Even with something listening on ::1, the result is unchanged.
+        monkeypatch.setattr(
+            run_module,
+            "_local_port_open",
+            lambda host, port, timeout = 1.0: True,
+        )
+
+        assert (
+            run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888)
+            == "http://127.0.0.1:8888"
+        )
+
+    @pytest.mark.parametrize("host", ["0.0.0.0", "::"])
+    def test_network_bind_suppresses_warning(self, monkeypatch, host):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [self._ipv6()])
+
+        assert run_module._localhost_ipv6_mismatch_url(host, 8888) is None
+
+    @pytest.mark.parametrize("port", [0, -1])
+    def test_non_positive_port_returns_none(self, monkeypatch, port):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", port) is None
+
+    def test_ipv4_not_answering_suppresses_warning(self, monkeypatch):
+        # Studio not confirmed on 127.0.0.1 -> do not warn.
+        run_module = load_studio_run_module(monkeypatch)
+        monkeypatch.setattr(run_module, "_working_local_url", lambda port: None)
+        self._set_getaddrinfo(monkeypatch, [self._ipv6()])
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) is None
+
+    def test_empty_resolver_result_suppresses_warning(self, monkeypatch):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+        self._set_getaddrinfo(monkeypatch, [])
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) is None
+
+    def test_resolver_error_suppresses_warning(self, monkeypatch):
+        run_module = load_studio_run_module(monkeypatch)
+        self._prepare_loopback(run_module, monkeypatch)
+
+        def _raise(*_a, **_k):
+            raise socket.gaierror("resolver unavailable")
+
+        monkeypatch.setattr(socket, "getaddrinfo", _raise)
+
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) is None
+
+    # -- _emit_startup_output (banner / warning wiring) ------------------
+
+    def _wire_recorders(self, run_module, monkeypatch):
+        calls = {"banner": [], "warning": [], "stop_hint": 0, "reachability": []}
+        monkeypatch.setattr(
+            run_module,
+            "print_studio_access_banner",
+            lambda **kwargs: calls["banner"].append(kwargs),
+        )
+        monkeypatch.setattr(
+            run_module,
+            "_print_localhost_ipv6_mismatch_warning",
+            lambda local_url, port: calls["warning"].append((local_url, port)),
+        )
+        monkeypatch.setattr(
+            run_module,
+            "print_studio_stop_hint",
+            lambda: calls.__setitem__("stop_hint", calls["stop_hint"] + 1),
+        )
+        monkeypatch.setattr(
+            run_module,
+            "_verify_global_reachability",
+            lambda display_host, port: calls["reachability"].append(
+                (display_host, port)
+            ),
+        )
+        return calls
+
+    def test_emit_startup_output_wires_mismatch_warning(self, monkeypatch):
+        run_module = load_studio_run_module(monkeypatch)
+        calls = self._wire_recorders(run_module, monkeypatch)
+        monkeypatch.setattr(
+            run_module,
+            "_localhost_ipv6_mismatch_url",
+            lambda host, port: "http://127.0.0.1:8888",
+        )
+
+        run_module._emit_startup_output("127.0.0.1", 8888, "127.0.0.1")
+
+        assert calls["banner"][0]["include_stop_hint"] is False
+        assert calls["warning"] == [("http://127.0.0.1:8888", 8888)]
+        assert calls["stop_hint"] == 1
+        assert calls["reachability"] == []
+
+    def test_emit_startup_output_plain_localhost(self, monkeypatch):
+        run_module = load_studio_run_module(monkeypatch)
+        calls = self._wire_recorders(run_module, monkeypatch)
+        monkeypatch.setattr(
+            run_module, "_localhost_ipv6_mismatch_url", lambda host, port: None
+        )
+
+        run_module._emit_startup_output("127.0.0.1", 8888, "127.0.0.1")
+
+        assert calls["banner"][0]["include_stop_hint"] is True
+        assert calls["warning"] == []
+        assert calls["stop_hint"] == 0
+        assert calls["reachability"] == []
+
+    @pytest.mark.parametrize("host", ["0.0.0.0", "::"])
+    def test_emit_startup_output_wildcard_runs_reachability(self, monkeypatch, host):
+        run_module = load_studio_run_module(monkeypatch)
+        calls = self._wire_recorders(run_module, monkeypatch)
+        monkeypatch.setattr(
+            run_module, "_localhost_ipv6_mismatch_url", lambda h, port: None
+        )
+
+        run_module._emit_startup_output(host, 8888, "203.0.113.5")
+
+        assert calls["banner"][0]["include_stop_hint"] is False
+        assert calls["warning"] == []
+        assert calls["reachability"] == [("203.0.113.5", 8888)]
+        assert calls["stop_hint"] == 1
+
+
 # ===========================================================================
 # A. normalize_compute_cap
 # ===========================================================================

From f22e92c8e40ed745bc805edfda20cf7a950eacd1 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Fri, 5 Jun 2026 02:46:34 -0700
Subject: [PATCH 095/222] fix: persist Studio thread synchronously on first
 runStart so mid-stream refresh keeps the prompt (#5814)

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../src/features/chat/api/chat-adapter.ts     | 46 +++++++++++++++--
 .../src/features/chat/runtime-provider.tsx    | 49 ++++++++++++++++---
 2 files changed, 83 insertions(+), 12 deletions(-)

diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 9a7f95df87..44b8507906 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -134,6 +134,47 @@ function isServerSideBuiltinToolPart(
   return hasNativePart;
 }
 
+const FIRST_THREAD_SAVE_TIMEOUT_MS = 250;
+
+type ThreadAutosaveHandle = {
+  registerFirstSave(threadId: string, promise: Promise<void>): Promise<void>;
+  awaitFirstSave(threadId: string | undefined): Promise<void>;
+};
+
+const pendingFirstThreadSaves = new Map<string, Promise<void>>();
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const ThreadAutosaveHandle: ThreadAutosaveHandle = {
+  registerFirstSave(threadId, promise) {
+    const trackedPromise = promise.catch(() => {});
+    const cleanupPromise = trackedPromise.finally(() => {
+      if (pendingFirstThreadSaves.get(threadId) === cleanupPromise) {
+        pendingFirstThreadSaves.delete(threadId);
+      }
+    });
+    pendingFirstThreadSaves.set(threadId, cleanupPromise);
+    return cleanupPromise;
+  },
+
+  async awaitFirstSave(threadId) {
+    if (!threadId) {
+      return;
+    }
+    const pending = pendingFirstThreadSaves.get(threadId);
+    if (!pending) {
+      return;
+    }
+    await Promise.race([pending, wait(FIRST_THREAD_SAVE_TIMEOUT_MS)]);
+  },
+};
+
+export function useThreadAutosaveHandle(): ThreadAutosaveHandle {
+  return ThreadAutosaveHandle;
+}
+
 /**
  * Match error messages that indicate the request filled or would fill
  * the KV cache, so the UI can show a dedicated toast pointing at the
@@ -169,10 +210,6 @@ export function isContextLimitError(message: string): boolean {
   );
 }
 
-function wait(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 async function updateStoredChatThreadEventually(
   threadId: string,
   patch: Parameters<typeof updateStoredChatThread>[1],
@@ -2179,6 +2216,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               throw error;
             }
             clearSelectedImageEditReference();
+            await ThreadAutosaveHandle.awaitFirstSave(resolvedThreadId);
             const stream = streamChatCompletions(requestPayload, abortSignal);
 
             for await (const chunk of stream) {
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 979d28a952..5e5780ec2a 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -34,7 +34,10 @@ import {
 import { extractText, getDocumentProxy } from "unpdf";
 import { toast } from "sonner";
 import { StudioWebSpeechDictationAdapter } from "./adapters/studio-web-speech-dictation-adapter";
-import { createOpenAIStreamAdapter } from "./api/chat-adapter";
+import {
+  ThreadAutosaveHandle,
+  createOpenAIStreamAdapter,
+} from "./api/chat-adapter";
 import {
   loadConnectionsEnabled,
   loadExternalProviders,
@@ -1132,6 +1135,13 @@ function ThreadBackendAutosave({
 }): ReactElement | null {
   const aui = useAui();
   const saveChainRef = useRef(Promise.resolve());
+  const pendingFirstSavesRef = useRef(new Map<string, Promise<void>>());
+
+  const reportAutosaveError = useCallback((error: unknown): void => {
+    if (!isExpectedBackgroundChatStorageError(error)) {
+      console.error("Failed to autosave chat thread", error);
+    }
+  }, []);
 
   const saveThread = useCallback(
     async (threadId: string): Promise<void> => {
@@ -1173,14 +1183,30 @@ function ThreadBackendAutosave({
     (threadId: string): void => {
       saveChainRef.current = saveChainRef.current
         .catch(() => {})
-        .then(() => saveThread(threadId))
-        .catch((error) => {
-          if (!isExpectedBackgroundChatStorageError(error)) {
-            console.error("Failed to autosave chat thread", error);
-          }
-        });
+        .then(async () => {
+          await pendingFirstSavesRef.current.get(threadId);
+          await saveThread(threadId);
+        })
+        .catch(reportAutosaveError);
     },
-    [saveThread],
+    [reportAutosaveError, saveThread],
+  );
+
+  const saveFirstThreadSnapshot = useCallback(
+    (threadId: string): void => {
+      if (pendingFirstSavesRef.current.has(threadId)) {
+        return;
+      }
+
+      const promise = saveThread(threadId)
+        .catch(reportAutosaveError)
+        .finally(() => {
+          pendingFirstSavesRef.current.delete(threadId);
+        });
+      pendingFirstSavesRef.current.set(threadId, promise);
+      ThreadAutosaveHandle.registerFirstSave(threadId, promise);
+    },
+    [reportAutosaveError, saveThread],
   );
 
   useAuiEvent("thread.runEnd", ({ threadId }) => {
@@ -1188,6 +1214,13 @@ function ThreadBackendAutosave({
   });
 
   useAuiEvent("thread.runStart", ({ threadId }) => {
+    const runtime = aui.threads().__internal_getAssistantRuntime?.();
+    const { remoteId } =
+      runtime?.threads.getItemById(threadId).getState() ?? {};
+    if (!remoteId) {
+      saveFirstThreadSnapshot(threadId);
+      return;
+    }
     queueSave(threadId);
   });
 

From 9806e36aa4980ead7289d809df80616eabfddb4e Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Fri, 5 Jun 2026 11:46:04 +0100
Subject: [PATCH 096/222] Studio: enable GGUF tools with vision inputs (#6009)

* fix: enable GGUF tools with vision inputs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: GGUF vision tool routing

* Dedupe system messages on GGUF vision tool path for PR #6009

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/backend/routes/inference.py            |  30 ++--
 .../tests/test_openai_tool_passthrough.py     | 138 +++++++++++++++++-
 2 files changed, 156 insertions(+), 12 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 15d73405cb..1d505e31f6 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -2780,7 +2780,7 @@ async def openai_chat_completions(
                 detail = "Audio input is not supported for GGUF chat models yet.",
             )
 
-        gguf_messages, has_gguf_image = _openai_messages_for_gguf_chat(
+        gguf_messages, _ = _openai_messages_for_gguf_chat(
             payload,
             llama_backend.is_vision,
         )
@@ -2804,11 +2804,7 @@ async def openai_chat_completions(
         _cli_policy = _get_tool_policy_g()
         _tools_on = _effective_enable_tools(payload)
         _mcp_allowed = bool(payload.mcp_enabled) and _cli_policy is not False
-        use_tools = (
-            (_tools_on or _mcp_allowed)
-            and llama_backend.supports_tools
-            and not has_gguf_image
-        )
+        use_tools = (_tools_on or _mcp_allowed) and llama_backend.supports_tools
 
         if use_tools:
             from core.inference.tools import ALL_TOOLS, get_enabled_mcp_tools
@@ -2897,11 +2893,9 @@ async def openai_chat_completions(
                     system_prompt = system_prompt.rstrip() + "\n\n" + _nudge
                 else:
                     system_prompt = _nudge
-                # Rebuild gguf_messages with updated system prompt
-                gguf_messages = []
-                if system_prompt:
-                    gguf_messages.append({"role": "system", "content": system_prompt})
-                gguf_messages.extend(chat_messages)
+                gguf_messages = _set_or_prepend_system_message(
+                    gguf_messages, system_prompt
+                )
 
             # ── Strip stale tool-call XML from conversation history ─
             for _msg in gguf_messages:
@@ -4860,6 +4854,20 @@ def _normalize_anthropic_openai_images(
     return has_image
 
 
+def _set_or_prepend_system_message(
+    messages: Optional[list[dict]], system_prompt: str
+) -> list[dict]:
+    """Return messages with a single leading system prompt, preserving multimodal parts."""
+    safe_messages = messages or []
+    if not system_prompt:
+        return safe_messages
+
+    # Drop existing system turns so the backend never sees duplicate or
+    # conflicting system instructions, then prepend the resolved prompt.
+    others = [dict(msg) for msg in safe_messages if msg.get("role") != "system"]
+    return [{"role": "system", "content": system_prompt}, *others]
+
+
 @router.post("/messages")
 async def anthropic_messages(
     payload: AnthropicMessagesRequest,
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 84f3e41998..05efee1595 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -20,6 +20,8 @@ No running server or GPU required.
 
 import os
 import sys
+import asyncio
+from types import SimpleNamespace
 
 _backend = os.path.join(os.path.dirname(__file__), "..")
 sys.path.insert(0, _backend)
@@ -36,7 +38,13 @@ from models.inference import (
 from core.inference.anthropic_compat import (
     anthropic_tool_choice_to_openai,
 )
-from routes.inference import _build_passthrough_payload, _friendly_error
+from routes.inference import (
+    _build_passthrough_payload,
+    _friendly_error,
+    _set_or_prepend_system_message,
+    openai_chat_completions,
+)
+from state.tool_policy import reset_tool_policy
 
 
 # =====================================================================
@@ -725,3 +733,131 @@ class TestGgufVisionMessages:
         with pytest.raises(HTTPException) as exc_info:
             _openai_messages_for_gguf_chat(req, is_vision = False)
         assert "does not support vision" in str(exc_info.value)
+
+    def test_tool_nudge_system_update_preserves_image_parts(self):
+        messages = [
+            {"role": "system", "content": "Base instructions."},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "describe this"},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:image/png;base64,{self._PNG_B64}",
+                        },
+                    },
+                ],
+            },
+        ]
+
+        updated = _set_or_prepend_system_message(
+            messages, "Base instructions.\n\nUse tools when appropriate."
+        )
+
+        assert updated[0] == {
+            "role": "system",
+            "content": "Base instructions.\n\nUse tools when appropriate.",
+        }
+        assert updated[1]["content"][1]["type"] == "image_url"
+        assert messages[1]["content"][1]["type"] == "image_url"
+
+    def test_tool_nudge_system_update_handles_none_messages(self):
+        assert _set_or_prepend_system_message(None, "") == []
+        assert _set_or_prepend_system_message(None, "Use tools.") == [
+            {"role": "system", "content": "Use tools."}
+        ]
+
+    def test_tool_nudge_system_update_dedupes_non_leading_system(self):
+        messages = [
+            {"role": "user", "content": "earlier"},
+            {"role": "system", "content": "Mid instructions."},
+            {"role": "user", "content": "now"},
+        ]
+
+        updated = _set_or_prepend_system_message(
+            messages, "Mid instructions.\n\nUse tools."
+        )
+
+        assert [m["role"] for m in updated] == ["system", "user", "user"]
+        assert updated[0]["content"] == "Mid instructions.\n\nUse tools."
+
+
+class TestGgufVisionToolRouting:
+    class _Request:
+        async def is_disconnected(self):
+            return False
+
+    @staticmethod
+    def _drive(coro):
+        return asyncio.run(coro)
+
+    @staticmethod
+    def _consume_response(response):
+        async def _consume():
+            chunks = []
+            async for chunk in response.body_iterator:
+                chunks.append(chunk)
+            return chunks
+
+        return TestGgufVisionToolRouting._drive(_consume())
+
+    def test_image_request_with_enabled_tools_enters_gguf_tool_loop(self, monkeypatch):
+        import routes.inference as inf_mod
+
+        reset_tool_policy()
+        captured = {}
+
+        def _plain(**kwargs):
+            raise AssertionError("plain GGUF path should not be used")
+
+        def _tools(**kwargs):
+            captured["kwargs"] = kwargs
+            yield {"type": "content", "text": "done"}
+
+        backend = SimpleNamespace(
+            is_loaded = True,
+            is_vision = True,
+            supports_tools = True,
+            model_identifier = "gemma-4-12b-it-GGUF",
+            generate_chat_completion = _plain,
+            generate_chat_completion_with_tools = _tools,
+        )
+        monkeypatch.setattr(inf_mod, "get_llama_cpp_backend", lambda: backend)
+
+        payload = ChatCompletionRequest(
+            model = "default",
+            enable_tools = True,
+            enabled_tools = ["web_search"],
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "What is in this image?"},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": (
+                                    "data:image/png;base64,"
+                                    f"{TestGgufVisionMessages._PNG_B64}"
+                                ),
+                            },
+                        },
+                    ],
+                },
+            ],
+        )
+
+        response = self._drive(
+            openai_chat_completions(
+                payload, request = self._Request(), current_subject = "test"
+            )
+        )
+        self._consume_response(response)
+
+        assert "kwargs" in captured
+        assert captured["kwargs"]["tools"]
+        tool_messages = captured["kwargs"]["messages"]
+        assert tool_messages[0]["role"] == "system"
+        assert tool_messages[1]["role"] == "user"
+        assert tool_messages[1]["content"][1]["type"] == "image_url"

From fe604fde20beaf0f9ef1dc7c7ea969d2dc729020 Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Fri, 5 Jun 2026 13:02:54 +0100
Subject: [PATCH 097/222] Studio: accept system-role messages in Claude Code
 requests (#6006)

Normalize misplaced system-role messages in /v1/messages by hoisting their content into the top-level Anthropic system field, fixing the 422 that newer Claude Code clients trigger. Null and non-text system content is ignored rather than stringified.

Fixes #6001
---
 studio/backend/models/inference.py            | 74 +++++++++++++++++++
 .../backend/tests/test_anthropic_messages.py  | 59 +++++++++++++++
 2 files changed, 133 insertions(+)

diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 9c3572bd3a..5a846e536e 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -1431,6 +1431,47 @@ AnthropicContentBlock = Union[
 ]
 
 
+def _anthropic_content_to_system_text(content: Any) -> str:
+    """Convert misplaced system message content into Anthropic system text."""
+    if content is None:  # null content must not become the literal "None"
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                text = block.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+                    continue
+            if block is not None:
+                parts.append(str(block))
+        return "\n\n".join(part for part in parts if part)
+    return str(content)
+
+
+def _merge_anthropic_system(system: Any, additions: list[str]) -> Any:
+    if not additions:
+        return system
+
+    addition_blocks = [
+        {"type": "text", "text": text} for text in additions if text.strip()
+    ]
+    if not addition_blocks:
+        return system
+
+    if system is None:
+        return (
+            addition_blocks[0]["text"] if len(addition_blocks) == 1 else addition_blocks
+        )
+    if isinstance(system, str):
+        return "\n\n".join([system, *[block["text"] for block in addition_blocks]])
+    if isinstance(system, list):
+        return [*system, *addition_blocks]
+    return system
+
+
 class AnthropicMessage(BaseModel):
     role: Literal["user", "assistant"]
     content: Union[str, list[AnthropicContentBlock]]
@@ -1474,6 +1515,39 @@ class AnthropicMessagesRequest(BaseModel):
     cancel_id: Optional[str] = None
     model_config = {"extra": "allow"}
 
+    @model_validator(mode = "before")
+    @classmethod
+    def normalize_system_messages(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        messages = data.get("messages")
+        if not isinstance(messages, list):
+            return data
+
+        normalized_messages: list[Any] = []
+        system_additions: list[str] = []
+        changed = False
+
+        for message in messages:
+            if isinstance(message, dict) and message.get("role") == "system":
+                system_additions.append(
+                    _anthropic_content_to_system_text(message.get("content", ""))
+                )
+                changed = True
+                continue
+            normalized_messages.append(message)
+
+        if not changed:
+            return data
+
+        normalized = dict(data)
+        normalized["messages"] = normalized_messages
+        normalized["system"] = _merge_anthropic_system(
+            normalized.get("system"), system_additions
+        )
+        return normalized
+
 
 # ── Response models ────────────────────────────────────────────
 
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index 634d02ad6c..dfabf27b68 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -78,6 +78,51 @@ class TestAnthropicModels:
         )
         assert req.system == "You are helpful."
 
+    def test_system_role_message_normalized_to_system_field(self):
+        req = AnthropicMessagesRequest(
+            max_tokens = 50,
+            messages = [
+                {"role": "system", "content": "You are helpful."},
+                {"role": "user", "content": "Hi"},
+            ],
+        )
+        assert req.system == "You are helpful."
+        assert len(req.messages) == 1
+        assert req.messages[0].role == "user"
+
+    def test_system_role_message_merges_with_existing_system_field(self):
+        req = AnthropicMessagesRequest(
+            max_tokens = 50,
+            system = "Base instructions.",
+            messages = [
+                {"role": "user", "content": "Hi"},
+                {"role": "system", "content": "Additional instructions."},
+                {"role": "assistant", "content": "Hello."},
+            ],
+        )
+        assert req.system == "Base instructions.\n\nAdditional instructions."
+        assert [msg.role for msg in req.messages] == ["user", "assistant"]
+
+    def test_system_role_message_with_null_content_ignored(self):
+        req = AnthropicMessagesRequest(
+            max_tokens = 50,
+            system = "Base.",
+            messages = [
+                {"role": "system", "content": None},
+                {
+                    "role": "system",
+                    "content": [
+                        None,
+                        {"type": "text", "text": "Use short answers."},
+                    ],
+                },
+                {"role": "user", "content": "Hi"},
+            ],
+        )
+        assert req.system == "Base.\n\nUse short answers."
+        assert "None" not in str(req.system)
+        assert [msg.role for msg in req.messages] == ["user"]
+
     def test_tools_field_parses(self):
         req = AnthropicMessagesRequest(
             max_tokens = 100,
@@ -158,6 +203,20 @@ class TestAnthropicMessagesToOpenAI:
         assert result[0] == {"role": "system", "content": "Be brief."}
         assert result[1] == {"role": "user", "content": "Hello"}
 
+    def test_top_level_system_request_translates_unchanged(self):
+        req = AnthropicMessagesRequest(
+            messages = [{"role": "user", "content": "Hello"}],
+            system = "Be brief.",
+        )
+        result = anthropic_messages_to_openai(
+            [m.model_dump() for m in req.messages],
+            req.system,
+        )
+        assert result == [
+            {"role": "system", "content": "Be brief."},
+            {"role": "user", "content": "Hello"},
+        ]
+
     def test_system_as_block_list(self):
         system = [
             {"type": "text", "text": "Be brief."},

From fe379212232b9649cdf96cafa226e6fa54626851 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Fri, 5 Jun 2026 07:15:45 -0700
Subject: [PATCH 098/222] Studio: fix load_freeze audio-type tests for #6000's
 Gemma 4 `<|audio|>` probe (#6018)

* Studio: fix load_freeze audio-type tests for #6000 Gemma 4 <|audio|> probe

#6000 extended LlamaCppBackend._detect_audio_type_strict audio_vlm arm to
also probe Gemma 4 `<|audio|>` (alongside Gemma 3n `<audio_soft_token>`),
but did not update the load_freeze simulation suite (last touched by #5922).
Its "no-match" and "bicodec" fixtures only defeat `<audio_soft_token>`; the
unmapped `<|audio|>` probe falls through to FakeLlamaServer 1-token default,
so detect_audio_type now returns audio_vlm where these tests expect
None / bicodec:

  - test_functional_equivalence_no_match
  - test_functional_equivalence_bicodec_match
  - test_response_shape_matches_pre_fix_for_no_match

main push-CI does not run "Repo tests (CPU)" (pull_request-only), so this
surfaces in every open PR merge-ref (e.g. #5940, which is unrelated to audio).

Fix: map `<|audio|>` to a 2-token response in the three fixtures that intend
a non-audio_vlm result (restoring their original semantics), and add a
positive test_functional_equivalence_audio_vlm_match locking in #6000 new
`<|audio|>` detection.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .../load_freeze/test_load_orchestrator.py     | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/tests/studio/load_freeze/test_load_orchestrator.py b/tests/studio/load_freeze/test_load_orchestrator.py
index 8d32932d13..91b70f0b03 100644
--- a/tests/studio/load_freeze/test_load_orchestrator.py
+++ b/tests/studio/load_freeze/test_load_orchestrator.py
@@ -3,7 +3,7 @@
 Covers:
   1.  Behavioural canary (the bug class)             — 2 tests
   2.  Behavioural fix-validation                     — 1 test
-  3.  Functional equivalence (sync == to_thread)     — 5 tests, one per codec branch
+  3.  Functional equivalence (sync == to_thread)     — 6 tests, one per codec branch
   4.  Failure modes (HTTP 500, malformed JSON,
       connection reset, unreachable, not-loaded)     — 5 tests
   5.  Stress (50 concurrent probes / 100 healths)    — 2 tests
@@ -254,6 +254,7 @@ def shim_no_match():
             "<|audio_eos|>": [0, 1],
             "<|startoftranscript|>": [0, 1],
             "<audio_soft_token>": [0, 1],
+            "<|audio|>": [0, 1],
             "<|bicodec_semantic_0|>": [0, 1],
             "<|bicodec_global_0|>": [0, 1],
             "<|c1_0|>": [0, 1],
@@ -314,6 +315,28 @@ def test_functional_equivalence_whisper_match():
     assert sync_result == threaded
 
 
+def test_functional_equivalence_audio_vlm_match():
+    # audio_vlm: snac/csm/whisper fail first, then the Gemma 4 <|audio|>
+    # probe tokenises to a single token. #6000 added this arm alongside
+    # Gemma 3n's <audio_soft_token>; keep <audio_soft_token> at 2 tokens so
+    # it is specifically the new <|audio|> arm that triggers the match.
+    with FakeLlamaServer(
+        detok_map = {128258: "non-snac", 128259: "non-snac"},
+        tok_response_map = {
+            "<|AUDIO|>": [0, 1],  # csm fails (>1 token)
+            "<|audio_eos|>": [0, 1],
+            "<|startoftranscript|>": [0, 1],  # whisper fails
+            "<audio_soft_token>": [0, 1],  # Gemma 3n arm fails ...
+            "<|audio|>": [0],  # ... Gemma 4 arm matches (#6000)
+        },
+    ) as srv:
+        backend = _make_backend(srv.port)
+        sync_result = backend.detect_audio_type()
+        threaded = asyncio.run(asyncio.to_thread(backend.detect_audio_type))
+    assert sync_result == "audio_vlm"
+    assert sync_result == threaded
+
+
 def test_functional_equivalence_bicodec_match():
     # bicodec: snac/csm/whisper/audio_vlm all fail first, then both
     # bicodec_semantic_0 and bicodec_global_0 are single tokens.
@@ -324,6 +347,7 @@ def test_functional_equivalence_bicodec_match():
             "<|audio_eos|>": [0, 1],
             "<|startoftranscript|>": [0, 1],
             "<audio_soft_token>": [0, 1],
+            "<|audio|>": [0, 1],
             "<|bicodec_semantic_0|>": [0],
             "<|bicodec_global_0|>": [0],
         },
@@ -644,6 +668,7 @@ def test_response_shape_matches_pre_fix_for_no_match():
             "<|audio_eos|>": [0, 1],
             "<|startoftranscript|>": [0, 1],
             "<audio_soft_token>": [0, 1],
+            "<|audio|>": [0, 1],
             "<|bicodec_semantic_0|>": [0, 1],
             "<|bicodec_global_0|>": [0, 1],
             "<|c1_0|>": [0, 1],

From 783c9d1e8379664cb8ed67e05f14a5f62f1dbe8e Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Fri, 5 Jun 2026 15:16:50 +0100
Subject: [PATCH 099/222] Studio: fix chat preset persistence with fast mode
 (#5870)

* fix: persist chat presets with fast mode

* Add schema drift guard test for chat inference settings (#5862)

Asserts ChatInferenceSettings declares every InferenceParams field the
frontend persists (all but checkpoint). With extra="forbid", a field
present in the UI but missing here 400s PUT /api/chat/settings, which is
exactly how fastMode regressed. Catches the next occurrence at CI time.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/routes/chat_history.py         |  1 +
 .../backend/tests/test_chat_history_routes.py | 66 +++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 8e24096233..75b5be2e49 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -143,6 +143,7 @@ class ChatInferenceSettings(BaseModel):
     maxTokens: Optional[float] = None
     systemPrompt: Optional[str] = None
     trustRemoteCode: Optional[bool] = None
+    fastMode: Optional[bool] = None
 
 
 class ChatPreset(BaseModel):
diff --git a/studio/backend/tests/test_chat_history_routes.py b/studio/backend/tests/test_chat_history_routes.py
index 9337544638..62bcd05205 100644
--- a/studio/backend/tests/test_chat_history_routes.py
+++ b/studio/backend/tests/test_chat_history_routes.py
@@ -3,6 +3,7 @@
 
 import asyncio
 import os
+import re
 import sys
 
 import pytest
@@ -56,6 +57,71 @@ def test_replace_thread_messages_rejects_body_thread_mismatch(monkeypatch):
     assert called is False
 
 
+# ---------------------------------------------------------------------------
+# /api/chat/settings
+# ---------------------------------------------------------------------------
+
+
+def test_chat_settings_payload_accepts_fast_mode_presets():
+    payload = chat_history.ChatSettingsPayload.model_validate(
+        {
+            "inferenceParams": {"fastMode": False},
+            "customPresets": [
+                {
+                    "name": "Fast Opus",
+                    "params": {
+                        "temperature": 0.6,
+                        "topP": 0.95,
+                        "topK": 20,
+                        "minP": 0.01,
+                        "repetitionPenalty": 1.0,
+                        "presencePenalty": 0.0,
+                        "maxTokens": 8192,
+                        "systemPrompt": "",
+                        "trustRemoteCode": False,
+                        "fastMode": True,
+                    },
+                },
+            ],
+        }
+    )
+
+    dumped = payload.model_dump(exclude_unset = True)
+    assert dumped["inferenceParams"]["fastMode"] is False
+    assert dumped["customPresets"][0]["params"]["fastMode"] is True
+
+
+def test_chat_inference_settings_covers_frontend_persisted_fields():
+    # Drift guard: every InferenceParams field the UI persists (all but
+    # checkpoint) must exist on ChatInferenceSettings, else extra="forbid"
+    # 400s PUT /api/chat/settings on the next added field (issue #5862).
+    runtime_ts = os.path.join(
+        _backend,
+        "..",
+        "frontend",
+        "src",
+        "features",
+        "chat",
+        "types",
+        "runtime.ts",
+    )
+    if not os.path.exists(runtime_ts):
+        pytest.skip("frontend runtime.ts not present")
+
+    with open(runtime_ts, encoding = "utf-8") as fh:
+        block = re.search(
+            r"interface InferenceParams \{(.*?)\n\}", fh.read(), re.DOTALL
+        )
+    assert block, "InferenceParams interface not found in runtime.ts"
+    persisted = set(re.findall(r"^\s*(\w+)\??:", block.group(1), re.M)) - {"checkpoint"}
+
+    backend = set(chat_history.ChatInferenceSettings.model_fields)
+    assert persisted == backend, (
+        f"schema drift: frontend-only {persisted - backend}, "
+        f"backend-only {backend - persisted}"
+    )
+
+
 # ---------------------------------------------------------------------------
 # /api/chat/import-ledger
 # ---------------------------------------------------------------------------

From 0003f889e6b8dd0a8da21cb382f175dab17985ac Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Fri, 5 Jun 2026 07:52:26 -0700
Subject: [PATCH 100/222] Studio: stop ROCm worker test leaking a fake utils
 into sys.modules (#6027)

test_direct_wheel_url_returns_none_without_cuda_major set sys.modules
"utils"/"utils.hardware" (and structlog/loggers) to MagicMocks without
cleanup. Once run.py started importing utils.cpu_threads (#5760), the
leaked non-package utils made later tests in the same job fail with
'No module named utils.cpu_threads; utils is not a package', e.g. all of
test_selection_logic.py's TestStudioLocalhostIpv6Warning. Use
monkeypatch.setitem so the stubs are undone after the test.
---
 tests/studio/install/test_rocm_support.py | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 1d6e4f4c51..1c1a4df377 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -1123,7 +1123,7 @@ class TestWorkerRocmMambaSsm:
         source = _WHEEL_UTILS_PATH.read_text(encoding = "utf-8")
         assert "getattr(torch.version, 'hip', None)" in source
 
-    def test_direct_wheel_url_returns_none_without_cuda_major(self):
+    def test_direct_wheel_url_returns_none_without_cuda_major(self, monkeypatch):
         """_direct_wheel_url should return None when cuda_major is empty (ROCm)."""
         # Load module for function access
         _worker_spec = importlib.util.spec_from_file_location(
@@ -1132,12 +1132,15 @@ class TestWorkerRocmMambaSsm:
         assert _worker_spec is not None and _worker_spec.loader is not None
         worker_mod = importlib.util.module_from_spec(_worker_spec)
 
-        # Mock all the imports worker.py needs
-        sys.modules["structlog"] = MagicMock()
-        sys.modules["loggers"] = MagicMock()
-        sys.modules["loggers"].get_logger = MagicMock(return_value = MagicMock())
-        sys.modules["utils"] = MagicMock()
-        sys.modules["utils.hardware"] = MagicMock()
+        # Stub worker.py's imports via monkeypatch so the fakes (notably a
+        # non-package "utils") are undone and don't break later tests that
+        # import the real utils.* package.
+        loggers_mock = MagicMock()
+        loggers_mock.get_logger = MagicMock(return_value = MagicMock())
+        monkeypatch.setitem(sys.modules, "structlog", MagicMock())
+        monkeypatch.setitem(sys.modules, "loggers", loggers_mock)
+        monkeypatch.setitem(sys.modules, "utils", MagicMock())
+        monkeypatch.setitem(sys.modules, "utils.hardware", MagicMock())
 
         try:
             _worker_spec.loader.exec_module(worker_mod)

From 686a30f95e4432522609dcdcb1bec71aea38e471 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sat, 6 Jun 2026 21:19:21 -0700
Subject: [PATCH 101/222] Studio: stop ROCm amd-smi tests leaking a fake
 loggers into sys.modules (#6055)

Follow-up to #6027. The four TestAmdGpuMonitoring tests also set
sys.modules["loggers"] = MagicMock() without cleanup, leaking a mock
loggers module into later tests. Switch them to monkeypatch.setitem so
the stub is undone at teardown, matching the worker test fix in #6027.
---
 tests/studio/install/test_rocm_support.py | 26 +++++++++++++----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 1c1a4df377..4aa7fb3a34 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -1206,15 +1206,16 @@ class TestAmdGpuMonitoring:
         assert "def get_primary_gpu_utilization" in source
         assert "def get_visible_gpu_utilization" in source
 
-    def test_amd_smi_json_parsing(self):
+    def test_amd_smi_json_parsing(self, monkeypatch):
         """Verify _extract_gpu_metrics parses amd-smi JSON correctly."""
         amd_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "amd.py"
         _amd_spec = importlib.util.spec_from_file_location("test_amd", amd_path)
         assert _amd_spec is not None and _amd_spec.loader is not None
         amd_mod = importlib.util.module_from_spec(_amd_spec)
 
-        sys.modules["loggers"] = MagicMock()
-        sys.modules["loggers"].get_logger = MagicMock(return_value = MagicMock())
+        loggers_mock = MagicMock()
+        loggers_mock.get_logger = MagicMock(return_value = MagicMock())
+        monkeypatch.setitem(sys.modules, "loggers", loggers_mock)
 
         try:
             _amd_spec.loader.exec_module(amd_mod)
@@ -1251,8 +1252,9 @@ class TestAmdGpuMonitoring:
         assert _amd_spec is not None and _amd_spec.loader is not None
         amd_mod = importlib.util.module_from_spec(_amd_spec)
 
-        sys.modules["loggers"] = MagicMock()
-        sys.modules["loggers"].get_logger = MagicMock(return_value = MagicMock())
+        loggers_mock = MagicMock()
+        loggers_mock.get_logger = MagicMock(return_value = MagicMock())
+        monkeypatch.setitem(sys.modules, "loggers", loggers_mock)
 
         try:
             _amd_spec.loader.exec_module(amd_mod)
@@ -1290,15 +1292,16 @@ class TestAmdGpuMonitoring:
         assert result["gpu_utilization_pct"] == 50.0
         assert result["temperature_c"] == 65.0
 
-    def test_amd_smi_not_found_returns_unavailable(self):
+    def test_amd_smi_not_found_returns_unavailable(self, monkeypatch):
         """get_primary_gpu_utilization returns available=False when amd-smi is missing."""
         amd_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "amd.py"
         _amd_spec = importlib.util.spec_from_file_location("test_amd3", amd_path)
         assert _amd_spec is not None and _amd_spec.loader is not None
         amd_mod = importlib.util.module_from_spec(_amd_spec)
 
-        sys.modules["loggers"] = MagicMock()
-        sys.modules["loggers"].get_logger = MagicMock(return_value = MagicMock())
+        loggers_mock = MagicMock()
+        loggers_mock.get_logger = MagicMock(return_value = MagicMock())
+        monkeypatch.setitem(sys.modules, "loggers", loggers_mock)
 
         try:
             _amd_spec.loader.exec_module(amd_mod)
@@ -1309,15 +1312,16 @@ class TestAmdGpuMonitoring:
             result = amd_mod.get_primary_gpu_utilization()
         assert result["available"] is False
 
-    def test_amd_timeout_returns_unavailable(self):
+    def test_amd_timeout_returns_unavailable(self, monkeypatch):
         """get_primary_gpu_utilization handles timeout gracefully."""
         amd_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "amd.py"
         _amd_spec = importlib.util.spec_from_file_location("test_amd4", amd_path)
         assert _amd_spec is not None and _amd_spec.loader is not None
         amd_mod = importlib.util.module_from_spec(_amd_spec)
 
-        sys.modules["loggers"] = MagicMock()
-        sys.modules["loggers"].get_logger = MagicMock(return_value = MagicMock())
+        loggers_mock = MagicMock()
+        loggers_mock.get_logger = MagicMock(return_value = MagicMock())
+        monkeypatch.setitem(sys.modules, "loggers", loggers_mock)
 
         try:
             _amd_spec.loader.exec_module(amd_mod)

From 1b588cd141daf20af272afeed0e014b808bbc071 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 7 Jun 2026 01:57:52 -0700
Subject: [PATCH 102/222] Studio: emit usage and timings for MLX generation
 speed stats (#6068)

* Studio: emit usage and timings for MLX generation speed stats

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: make MLX generation stats request scoped

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .../backend/core/inference/mlx_inference.py   | 85 ++++++++++++++++---
 studio/backend/core/inference/orchestrator.py | 19 +++++
 studio/backend/core/inference/worker.py       |  2 +
 studio/backend/routes/inference.py            | 51 ++++++++++-
 4 files changed, 142 insertions(+), 15 deletions(-)

diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index 716e4c27a2..b9adba13e6 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -12,6 +12,35 @@ from loggers import get_logger
 logger = get_logger(__name__)
 
 
+def _build_generation_stats(prompt_n, prompt_tps, gen_n, gen_tps):
+    """Map mlx_lm / mlx_vlm stream stats onto the usage/timings shape
+    llama-server emits so the chat speed popover renders the same."""
+    prompt_n = int(prompt_n or 0)
+    gen_n = int(gen_n or 0)
+    prompt_tps = float(prompt_tps or 0.0)
+    gen_tps = float(gen_tps or 0.0)
+    prompt_ms = (prompt_n / prompt_tps * 1000.0) if prompt_tps > 0 else 0.0
+    predicted_ms = (gen_n / gen_tps * 1000.0) if gen_tps > 0 else 0.0
+    return {
+        "usage": {
+            "prompt_tokens": prompt_n,
+            "completion_tokens": gen_n,
+            "total_tokens": prompt_n + gen_n,
+        },
+        "timings": {
+            "prompt_n": prompt_n,
+            "prompt_ms": prompt_ms,
+            "prompt_per_token_ms": (prompt_ms / prompt_n) if prompt_n > 0 else 0.0,
+            "prompt_per_second": prompt_tps,
+            "predicted_n": gen_n,
+            "predicted_ms": predicted_ms,
+            "predicted_per_token_ms": (predicted_ms / gen_n) if gen_n > 0 else 0.0,
+            "predicted_per_second": gen_tps,
+            "cache_n": 0,
+        },
+    }
+
+
 class MLXInferenceBackend:
     def __init__(self):
         self.models = {}
@@ -20,6 +49,8 @@ class MLXInferenceBackend:
         self.loaded_local_models = []
         self.device = "mlx"
         self._generation_lock = threading.Lock()
+        # usage/timings of the latest generation; shipped on gen_done.
+        self.last_generation_stats = None
 
         # MLX state
         self._model = None
@@ -258,6 +289,9 @@ class MLXInferenceBackend:
         if self._model is None:
             raise RuntimeError("No model loaded")
 
+        # Reset so a failed run cannot surface stale stats.
+        self.last_generation_stats = None
+
         # Build messages with system prompt
         full_messages = []
         if system_prompt:
@@ -380,6 +414,7 @@ class MLXInferenceBackend:
             type(self._tokenizer).__name__,
         )
         with self._generation_lock:
+            final_response = None
             try:
                 gen_kwargs = dict(
                     prompt = prompt,
@@ -393,6 +428,7 @@ class MLXInferenceBackend:
                     self._tokenizer,
                     **gen_kwargs,
                 ):
+                    final_response = response
                     token_ids.append(response.token)
                     # Decode full sequence with skip_special_tokens — same as GPU
                     cumulative = self._tokenizer.decode(
@@ -408,6 +444,15 @@ class MLXInferenceBackend:
 
                 logger.error("stream_generate failed:\n%s", traceback.format_exc())
                 raise
+            finally:
+                # Latch final cumulative stats for the usage/timings chunk.
+                if final_response is not None:
+                    self.last_generation_stats = _build_generation_stats(
+                        getattr(final_response, "prompt_tokens", 0),
+                        getattr(final_response, "prompt_tps", 0.0),
+                        getattr(final_response, "generation_tokens", 0),
+                        getattr(final_response, "generation_tps", 0.0),
+                    )
 
     def _generate_vlm(
         self,
@@ -483,20 +528,32 @@ class MLXInferenceBackend:
             vlm_kwargs["repetition_penalty"] = float(repetition_penalty)
 
         with self._generation_lock:
-            for response in vlm_stream(
-                self._model,
-                self._processor,
-                prompt,
-                images,
-                **vlm_kwargs,
-            ):
-                token_text = (
-                    response.text if hasattr(response, "text") else str(response)
-                )
-                cumulative += token_text
-                yield cumulative
-                if cancel_event and cancel_event.is_set():
-                    break
+            final_response = None
+            try:
+                for response in vlm_stream(
+                    self._model,
+                    self._processor,
+                    prompt,
+                    images,
+                    **vlm_kwargs,
+                ):
+                    final_response = response
+                    token_text = (
+                        response.text if hasattr(response, "text") else str(response)
+                    )
+                    cumulative += token_text
+                    yield cumulative
+                    if cancel_event and cancel_event.is_set():
+                        break
+            finally:
+                # mlx_vlm exposes the same stats fields as mlx_lm.
+                if final_response is not None:
+                    self.last_generation_stats = _build_generation_stats(
+                        getattr(final_response, "prompt_tokens", 0),
+                        getattr(final_response, "prompt_tps", 0.0),
+                        getattr(final_response, "generation_tokens", 0),
+                        getattr(final_response, "generation_tps", 0.0),
+                    )
 
     def generate_with_adapter_control(
         self, use_adapter = None, cancel_event = None, **gen_kwargs
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 7e7d7026f6..6321ca892d 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -453,6 +453,7 @@ class InferenceOrchestrator:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
+        stats_holder: Optional[dict] = None,
     ) -> Generator[str, None, None]:
         """Dispatched generation — sends command without holding _gen_lock.
 
@@ -544,6 +545,8 @@ class InferenceOrchestrator:
                     yield resp.get("text", "")
 
                 elif rtype == "gen_done":
+                    if stats_holder is not None:
+                        stats_holder["stats"] = resp.get("stats")
                     return
 
                 elif rtype == "gen_error":
@@ -793,6 +796,7 @@ class InferenceOrchestrator:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
+        stats_holder: Optional[dict] = None,
     ) -> Generator[str, None, None]:
         """Generate response, streaming tokens from subprocess.
 
@@ -800,6 +804,10 @@ class InferenceOrchestrator:
         ``preserve_thinking`` kwargs are forwarded into the worker so
         ``tokenizer.apply_chat_template`` can render tool schemas and
         reasoning controls when the template understands them.
+
+        ``stats_holder``: caller-owned dict; on gen_done its "stats" key
+        receives the worker's usage/timings. Request-scoped by design so
+        concurrent streams cannot read each other's stats.
         """
         yield from self._generate_inner(
             messages = messages,
@@ -817,6 +825,7 @@ class InferenceOrchestrator:
             enable_thinking = enable_thinking,
             reasoning_effort = reasoning_effort,
             preserve_thinking = preserve_thinking,
+            stats_holder = stats_holder,
         )
 
     def generate_chat_completion_with_tools(
@@ -839,6 +848,7 @@ class InferenceOrchestrator:
         tool_call_timeout: int = 300,
         session_id: Optional[str] = None,
         use_adapter: Optional[Union[bool, str]] = None,
+        stats_holder: Optional[dict] = None,
         **_unused,
     ):
         """Run the safetensors agentic tool loop in this (parent)
@@ -872,6 +882,8 @@ class InferenceOrchestrator:
                 enable_thinking = enable_thinking,
                 reasoning_effort = reasoning_effort,
                 preserve_thinking = preserve_thinking,
+                # last turn wins, same as the GGUF tool loop's metadata
+                stats_holder = stats_holder,
             )
             if use_adapter is not None:
                 yield from self.generate_with_adapter_control(
@@ -901,6 +913,7 @@ class InferenceOrchestrator:
         self,
         use_adapter: Optional[Union[bool, str]] = None,
         cancel_event = None,
+        stats_holder: Optional[dict] = None,
         **gen_kwargs,
     ) -> Generator[str, None, None]:
         """Generate with adapter control, streaming tokens from subprocess.
@@ -912,6 +925,7 @@ class InferenceOrchestrator:
         yield from self._generate_dispatched(
             use_adapter = use_adapter,
             cancel_event = cancel_event,
+            stats_holder = stats_holder,
             **gen_kwargs,
         )
 
@@ -932,6 +946,7 @@ class InferenceOrchestrator:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
+        stats_holder: Optional[dict] = None,
     ) -> Generator[str, None, None]:
         """Inner generation logic — sends command to subprocess, yields tokens.
 
@@ -972,6 +987,7 @@ class InferenceOrchestrator:
                 enable_thinking = enable_thinking,
                 reasoning_effort = reasoning_effort,
                 preserve_thinking = preserve_thinking,
+                stats_holder = stats_holder,
             )
 
     def _generate_locked(
@@ -991,6 +1007,7 @@ class InferenceOrchestrator:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
+        stats_holder: Optional[dict] = None,
     ) -> Generator[str, None, None]:
         """Actual generation logic — must be called under _gen_lock."""
         request_id = str(uuid.uuid4())
@@ -1069,6 +1086,8 @@ class InferenceOrchestrator:
                 yield resp.get("text", "")
 
             elif rtype == "gen_done":
+                if stats_holder is not None:
+                    stats_holder["stats"] = resp.get("stats")
                 return
 
             elif rtype == "gen_error":
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 20a7d2d16c..d01cce4fc1 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -481,6 +481,8 @@ def _handle_generate(
             {
                 "type": "gen_done",
                 "request_id": request_id,
+                # usage/timings from the MLX backend (None elsewhere).
+                "stats": getattr(backend, "last_generation_stats", None),
                 "ts": time.time(),
             },
         )
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 1d505e31f6..d3a279319a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3426,6 +3426,9 @@ async def openai_chat_completions(
             else:
                 _sf_chat_messages.append(_msg)
 
+        # Request-scoped usage/timings receptacle (filled at gen_done).
+        _sf_stats_holder: dict = {}
+
         def sf_generate_with_tools():
             return backend.generate_chat_completion_with_tools(
                 messages = _sf_chat_messages,
@@ -3450,6 +3453,7 @@ async def openai_chat_completions(
                 else 300,
                 session_id = payload.session_id,
                 use_adapter = payload.use_adapter,
+                stats_holder = _sf_stats_holder,
             )
 
         _sf_tool_sentinel = object()
@@ -3537,6 +3541,25 @@ async def openai_chat_completions(
                     ],
                 )
                 yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
+                # Usage chunk from the last turn, same shape as the
+                # GGUF tool loop's metadata. Request-scoped holder, so
+                # concurrent streams cannot read each other's stats.
+                _stats = _sf_stats_holder.get("stats")
+                if _stats:
+                    _stream_usage = _stats.get("usage") or {}
+                    usage_chunk = ChatCompletionChunk(
+                        id = completion_id,
+                        created = created,
+                        model = model_name,
+                        choices = [],
+                        usage = CompletionUsage(
+                            prompt_tokens = _stream_usage.get("prompt_tokens", 0),
+                            completion_tokens = _stream_usage.get("completion_tokens", 0),
+                            total_tokens = _stream_usage.get("total_tokens", 0),
+                        ),
+                        timings = _stats.get("timings"),
+                    )
+                    yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
                 yield "data: [DONE]\n\n"
 
             except asyncio.CancelledError:
@@ -3627,19 +3650,25 @@ async def openai_chat_completions(
     if payload.preserve_thinking is not None:
         gen_kwargs["preserve_thinking"] = payload.preserve_thinking
 
+    # Request-scoped usage/timings receptacle (filled at gen_done).
+    stats_holder: dict = {}
+
     if payload.use_adapter is not None:
 
         def generate():
             return backend.generate_with_adapter_control(
                 use_adapter = payload.use_adapter,
                 cancel_event = cancel_event,
+                stats_holder = stats_holder,
                 **gen_kwargs,
             )
     else:
 
         def generate():
             return backend.generate_chat_response(
-                cancel_event = cancel_event, **gen_kwargs
+                cancel_event = cancel_event,
+                stats_holder = stats_holder,
+                **gen_kwargs,
             )
 
     # ── Streaming response ────────────────────────────────────────
@@ -3716,6 +3745,26 @@ async def openai_chat_completions(
                     ],
                 )
                 yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
+                # Usage chunk (choices=[], usage set), same shape as the
+                # GGUF path so the speed popover works for MLX too.
+                # Request-scoped holder, so concurrent streams cannot
+                # read each other's stats.
+                _stats = stats_holder.get("stats")
+                if _stats:
+                    _stream_usage = _stats.get("usage") or {}
+                    usage_chunk = ChatCompletionChunk(
+                        id = completion_id,
+                        created = created,
+                        model = model_name,
+                        choices = [],
+                        usage = CompletionUsage(
+                            prompt_tokens = _stream_usage.get("prompt_tokens", 0),
+                            completion_tokens = _stream_usage.get("completion_tokens", 0),
+                            total_tokens = _stream_usage.get("total_tokens", 0),
+                        ),
+                        timings = _stats.get("timings"),
+                    )
+                    yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
                 yield "data: [DONE]\n\n"
 
             except asyncio.CancelledError:

From 1e811acd622de45bfad5c42dfac34dcb6e82a165 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 7 Jun 2026 01:57:55 -0700
Subject: [PATCH 103/222] Studio: tag MLX loaded models as MLX instead of Base
 in chat (#6067)

* Studio: tag MLX loaded models as MLX instead of Base in chat

* Studio: tag MLX named hub defaults via name heuristic
---
 studio/backend/core/inference/orchestrator.py   |  1 +
 studio/backend/core/inference/worker.py         |  2 ++
 studio/backend/models/models.py                 |  3 +++
 studio/backend/routes/models.py                 | 17 ++++++++++++++++-
 .../chat/hooks/use-chat-model-runtime.ts        | 13 ++++++++++++-
 studio/frontend/src/features/chat/types/api.ts  |  1 +
 .../frontend/src/features/chat/types/runtime.ts |  1 +
 7 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 6321ca892d..9810f2b9da 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -705,6 +705,7 @@ class InferenceOrchestrator:
                     self.models[self.active_model_name] = {
                         "is_vision": model_info.get("is_vision", False),
                         "is_lora": model_info.get("is_lora", False),
+                        "is_mlx": model_info.get("is_mlx", False),
                         "display_name": model_info.get("display_name", model_name),
                         "is_audio": model_info.get("is_audio", False),
                         "audio_type": model_info.get("audio_type"),
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index d01cce4fc1..31fd55a156 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -342,6 +342,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 "is_vision": mc.is_vision,
                 "is_lora": mc.is_lora,
                 "is_gguf": False,
+                # MLX backend sets device="mlx"; lets the UI tag MLX models.
+                "is_mlx": getattr(backend, "device", None) == "mlx",
                 "is_audio": getattr(mc, "is_audio", False),
                 "audio_type": getattr(mc, "audio_type", None),
                 "has_audio_input": getattr(mc, "has_audio_input", False),
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index 46ca4e3784..a53569aaa1 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -76,6 +76,9 @@ class ModelDetails(BaseModel):
     is_gguf: bool = Field(
         False, description = "Whether model is a GGUF model (llama.cpp format)"
     )
+    is_mlx: bool = Field(
+        False, description = "Whether model is served via the MLX backend (Apple Silicon)"
+    )
     is_audio: bool = Field(False, description = "Whether model is a TTS audio model")
     audio_type: Optional[str] = Field(
         None, description = "Audio codec type: snac, csm, bicodec, dac"
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 9ea113e488..2b729eea9c 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -1446,6 +1446,15 @@ async def browse_folders(
     )
 
 
+def _looks_like_mlx_repo(model_id: str) -> bool:
+    """Name heuristic for unloaded models, mirrors the -GGUF suffix check.
+    Tokenized so MLX only matches as a whole name segment."""
+    if model_id.lower().startswith("mlx-community/"):
+        return True
+    tail = model_id.split("/")[-1]
+    return "MLX" in _re.split(r"[-_.]", tail.upper())
+
+
 @router.get("/list")
 async def list_models(
     current_subject: str = Depends(get_current_subject),
@@ -1471,6 +1480,7 @@ async def list_models(
                 name = model_name.split("/")[-1] if "/" in model_name else model_name,
                 is_vision = _is_vision,
                 is_lora = model_data.get("is_lora", False),
+                is_mlx = model_data.get("is_mlx", False),
                 is_audio = model_data.get("is_audio", False),
                 audio_type = _audio_type,
                 has_audio_input = model_data.get("has_audio_input", False),
@@ -1498,13 +1508,18 @@ async def list_models(
         all_models = []
         seen_ids = set()
 
+        # Prefer loaded entries for duplicate ids so runtime flags
+        # (is_mlx, is_vision, is_audio, ...) are not lost.
+        loaded_by_id = {model_info.id: model_info for model_info in loaded_models}
+
         # Add default models
         for model_id in default_models:
             if model_id not in seen_ids:
-                model_info = ModelDetails(
+                model_info = loaded_by_id.get(model_id) or ModelDetails(
                     id = model_id,
                     name = model_id.split("/")[-1] if "/" in model_id else model_id,
                     is_gguf = model_id.upper().endswith("-GGUF"),
+                    is_mlx = _looks_like_mlx_repo(model_id),
                 )
                 all_models.append(model_info)
                 seen_ids.add(model_id)
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index e6892b34fd..d1dab924cb 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -94,16 +94,25 @@ function describeModel(model: {
   is_lora?: boolean;
   is_vision?: boolean;
   is_gguf?: boolean;
+  is_mlx?: boolean;
   is_audio?: boolean;
   has_audio_input?: boolean;
 }): string | undefined {
   const tags: string[] = [];
   if (model.is_gguf) tags.push("GGUF");
+  if (model.is_mlx) tags.push("MLX");
   if (model.is_lora) tags.push("LoRA");
   if (model.is_vision) tags.push("Vision");
   if (model.is_audio) tags.push("Audio");
   if (model.has_audio_input) tags.push("Audio Input");
-  if (!model.is_lora && !model.is_vision && !model.is_gguf && !model.is_audio && !model.has_audio_input)
+  if (
+    !model.is_lora &&
+    !model.is_vision &&
+    !model.is_gguf &&
+    !model.is_mlx &&
+    !model.is_audio &&
+    !model.has_audio_input
+  )
     tags.push("Base");
   return tags.join(" · ");
 }
@@ -114,6 +123,7 @@ function toChatModelSummary(model: {
   is_lora?: boolean;
   is_vision?: boolean;
   is_gguf?: boolean;
+  is_mlx?: boolean;
   is_audio?: boolean;
   audio_type?: string | null;
   has_audio_input?: boolean;
@@ -125,6 +135,7 @@ function toChatModelSummary(model: {
     isLora: Boolean(model.is_lora),
     isVision: Boolean(model.is_vision),
     isGguf: Boolean(model.is_gguf),
+    isMlx: Boolean(model.is_mlx),
     isAudio: Boolean(model.is_audio),
     audioType: model.audio_type ?? null,
     hasAudioInput: Boolean(model.has_audio_input),
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index d313b43438..92ea1500bd 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -7,6 +7,7 @@ export interface BackendModelDetails {
   is_vision?: boolean;
   is_lora?: boolean;
   is_gguf?: boolean;
+  is_mlx?: boolean;
   is_audio?: boolean;
   audio_type?: string | null;
   has_audio_input?: boolean;
diff --git a/studio/frontend/src/features/chat/types/runtime.ts b/studio/frontend/src/features/chat/types/runtime.ts
index 4c44ee1e9c..24286c94fb 100644
--- a/studio/frontend/src/features/chat/types/runtime.ts
+++ b/studio/frontend/src/features/chat/types/runtime.ts
@@ -44,6 +44,7 @@ export interface ChatModelSummary {
   isVision: boolean;
   isLora: boolean;
   isGguf?: boolean;
+  isMlx?: boolean;
   isAudio?: boolean;
   audioType?: string | null;
   hasAudioInput?: boolean;

From da1c5b4b94a5628dce40ce773ba881f1ef08a4dc Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 7 Jun 2026 01:57:58 -0700
Subject: [PATCH 104/222] Studio: remove red border on chat error messages
 (#6063)

Co-authored-by: shimmyshimmer <shimmyshimmer@users.noreply.github.com>
---
 studio/frontend/src/components/assistant-ui/thread.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index a55c89f634..27404c83eb 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -1894,7 +1894,7 @@ const ComposerRightControls: FC<{
 const MessageError: FC = () => {
   return (
     <MessagePrimitive.Error>
-      <ErrorPrimitive.Root className="aui-message-error-root mt-2 rounded-md border border-destructive bg-destructive/10 p-3 text-destructive text-sm dark:bg-destructive/5 dark:text-red-200">
+      <ErrorPrimitive.Root className="aui-message-error-root mt-2 rounded-md bg-destructive/10 p-3 text-destructive text-sm dark:bg-destructive/5 dark:text-red-200">
         <ErrorPrimitive.Message className="aui-message-error-message line-clamp-2" />
       </ErrorPrimitive.Root>
     </MessagePrimitive.Error>

From cf97faed9ff73af5e46c18a21efdad24ded876dc Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Sun, 7 Jun 2026 01:58:01 -0700
Subject: [PATCH 105/222] Studio: keep chat in place when composer attachments
 resize it (#6070)

* Studio: keep chat in place when composer attachments resize it

Attaching or removing a file in the chat composer could yank the whole
conversation to the bottom, and the grown composer covered the end of
the chat with no way to scroll it back into view.

Root cause: the Viewport composes refs with an identity that changes on
re-render, so React re-runs our scroll ref on unrelated renders and the
autoscroll hook treated every rebind as a fresh mount, pinning to the
bottom. On top of that the viewport reserved a fixed 160px under the
last message regardless of composer size.

- Treat same-element ref rebinds as no-ops in the autoscroll hook; only
  a genuinely new viewport element pins and resets detach state
- Size the bottom spacer from the measured composer height plus a 24px
  gap so the chat can always be scrolled above the composer
- On composer growth, detach from the bottom instead of auto-scrolling;
  the user scrolls down to reveal the covered lines
- On composer shrink, defer the spacer shrink until it cannot clamp
  scrollTop, then release it invisibly on scroll or on bottom-pinning
  moments (run start, thread switch, thread load)

* Studio: release deferred composer spacer when a run owns the bottom

Sending with attachments cleared the chips after thread.runStart had
already fired, so the spacer shrink was deferred while the user sat
pinned at the bottom, leaving a permanent extra gap above the composer.
Apply shrinks immediately while a run is active or within 1s of run
start; the run-start pin owns the bottom then, so the clamp is the
intended glide. Caught by a cross-engine Playwright pass (Chromium,
Firefox, WebKit) over the pre and post builds.

* Studio: track the viewport element in state so listeners survive remounts

The deferred-shrink scroll listener was attached once against a ref, but
the keyed overlay provider remounts the viewport subtree on thread
switches, leaving the listener bound to the unmounted element. Removing
an attachment near the bottom in the new thread then left the oversized
spacer stuck until a run started. Track the viewport element in state so
the listener and the clamp math follow the new element.

Reproduced and verified with a thread-switch scenario on Chromium,
Firefox and WebKit; full matrix re-run green.

* Studio: release deferred composer spacer shrink when at the bottom (#6070)

---------

Co-authored-by: shimmyshimmer <michael@unsloth.ai>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../src/components/assistant-ui/thread.tsx    | 226 +++++++++++++++++-
 .../use-intent-aware-autoscroll.tsx           |  71 ++++--
 2 files changed, 270 insertions(+), 27 deletions(-)

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 27404c83eb..6b94bfff6c 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -119,6 +119,7 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useRef,
   useState,
 } from "react";
@@ -127,6 +128,18 @@ import {
 // composer), so the composer can show its "Drop files here" affordance.
 const PageDragContext = createContext(false);
 
+// Gap (px) between the last message and the floating composer. The bottom
+// spacer tracks composer height plus this gap so the chat can always be
+// scrolled fully above the composer.
+const COMPOSER_SCROLL_GAP_PX = 24;
+// The scroll-to-bottom footer sits 10px below the spacer top.
+const FOOTER_GAP_BELOW_SPACER_PX = 10;
+// Composer shrinks this soon after a run start (send clears the chips)
+// apply immediately: the run-start pin owns the bottom, so the clamp is
+// the intended glide. Covers instant responses where isRunning is
+// already false by the time the dock resize is observed.
+const RUN_SHRINK_WINDOW_MS = 1000;
+
 export const Thread: FC<{
   hideComposer?: boolean;
   hideWelcome?: boolean;
@@ -144,12 +157,156 @@ export const Thread: FC<{
   );
   const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const threadId = targetThreadId ?? activeThreadId ?? null;
+  const aui = useAui();
+
+  // Measured height of the floating composer dock (null until measured).
+  // Drives the bottom spacer and the scroll-to-bottom footer offset.
+  const [composerHeight, setComposerHeight] = useState<number | null>(null);
+  const footerBottomPx =
+    composerHeight == null
+      ? null
+      : composerHeight + COMPOSER_SCROLL_GAP_PX - FOOTER_GAP_BELOW_SPACER_PX;
+
+  // The viewport element is owned by the autoscroll hook; mirror it
+  // locally for the spacer clamp math below. State, not a ref: the keyed
+  // provider below remounts the viewport on thread switches, and the
+  // scroll listener effect must re-attach to the new element.
+  const [viewportEl, setViewportEl] = useState<HTMLElement | null>(null);
+  const composedViewportRef = useCallback(
+    (node: HTMLElement | null) => {
+      setViewportEl(node);
+      viewportRef(node);
+    },
+    [viewportRef],
+  );
+
+  // Bottom spacer sizing. Invariant: the chat never moves on its own when
+  // the composer resizes.
+  // - Grow (attachment added, multiline input): grow the spacer at once.
+  //   Growth below the scroll position is invisible and only adds room.
+  // - Shrink (attachment removed): shrinking scrollHeight near the bottom
+  //   would clamp scrollTop and yank the chat down. Defer the shrink until
+  //   it is invisible (user scrolled up) or a bottom-pinning moment.
+  // Applied imperatively so a remounted spacer can be sized from refs even
+  // when composerHeight did not change (e.g. thread switch).
+  const spacerElRef = useRef<HTMLDivElement | null>(null);
+  const desiredSpacerPxRef = useRef<number | null>(null);
+  const appliedSpacerPxRef = useRef<number | null>(null);
+
+  const applySpacerPx = useCallback((px: number) => {
+    appliedSpacerPxRef.current = px;
+    const node = spacerElRef.current;
+    if (node) {
+      node.style.height = `${px}px`;
+    }
+  }, []);
+
+  // Release any deferred shrink; used at moments that pin to the bottom
+  // anyway, where the clamp is the intended motion.
+  const releaseSpacerExcess = useCallback(() => {
+    const desired = desiredSpacerPxRef.current;
+    const applied = appliedSpacerPxRef.current;
+    if (desired != null && applied != null && applied > desired) {
+      applySpacerPx(desired);
+    }
+  }, [applySpacerPx]);
+
+  const spacerRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      spacerElRef.current = node;
+      // Fresh mounts (thread switch, first message) start at the desired
+      // size; deferral state from a previous mount is moot.
+      const desired = desiredSpacerPxRef.current;
+      if (node && desired != null) {
+        applySpacerPx(desired);
+      }
+    },
+    [applySpacerPx],
+  );
+
+  const prevComposerHeightRef = useRef<number | null>(null);
+  // Set on thread.runStart; see RUN_SHRINK_WINDOW_MS.
+  const runStartAtRef = useRef(0);
+  useLayoutEffect(() => {
+    const prev = prevComposerHeightRef.current;
+    prevComposerHeightRef.current = composerHeight;
+    if (composerHeight == null || hideComposer) {
+      desiredSpacerPxRef.current = null;
+      appliedSpacerPxRef.current = null;
+      spacerElRef.current?.style.removeProperty("height");
+      return;
+    }
+    const desired = composerHeight + COMPOSER_SCROLL_GAP_PX;
+    desiredSpacerPxRef.current = desired;
+    const applied = appliedSpacerPxRef.current;
+    if (applied == null || desired >= applied) {
+      applySpacerPx(desired);
+    } else {
+      const distance = viewportEl
+        ? viewportEl.scrollHeight - viewportEl.scrollTop - viewportEl.clientHeight
+        : Number.POSITIVE_INFINITY;
+      const runOwnsBottom =
+        aui.thread().getState().isRunning ||
+        performance.now() - runStartAtRef.current < RUN_SHRINK_WINDOW_MS;
+      // At the bottom the shrink only drops blank spacer, so apply it now
+      // instead of stranding dead space until the next pin.
+      if (
+        runOwnsBottom ||
+        distance >= applied - desired ||
+        autoScrollContext.getIsAtBottom()
+      ) {
+        applySpacerPx(desired);
+      }
+      // else: deferred; released on scroll or a bottom-pinning event.
+    }
+    if (prev != null && composerHeight > prev) {
+      // The chat is now above the new bottom. Detach as if the user had
+      // scrolled up so no later signal re-pins and shoves the chat up.
+      // Scrolling back down re-attaches; explicit pins still work.
+      // Mid-run growth comes from tool-status rows, not the user, and
+      // detaching then would break streaming autoscroll, so skip it.
+      if (!aui.thread().getState().isRunning) {
+        autoScrollContext.detachFromBottom();
+      }
+    }
+  }, [composerHeight, hideComposer, autoScrollContext, aui, applySpacerPx, viewportEl]);
+
+  // Drop deferred spacer excess as soon as the user has scrolled far
+  // enough above the bottom that the shrink cannot clamp scrollTop.
+  // Keyed on viewportEl so the listener follows viewport remounts.
+  useEffect(() => {
+    const el = viewportEl;
+    if (!el) {
+      return;
+    }
+    const onScroll = () => {
+      const desired = desiredSpacerPxRef.current;
+      const applied = appliedSpacerPxRef.current;
+      if (desired == null || applied == null || applied <= desired) {
+        return;
+      }
+      const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
+      if (distance >= applied - desired) {
+        applySpacerPx(desired);
+      }
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [viewportEl, applySpacerPx]);
+
+  // These pin to the bottom, so releasing the excess here is invisible.
+  // runStart also opens the shrink window for the send-clears-chips case.
+  useAuiEvent("thread.runStart", () => {
+    runStartAtRef.current = performance.now();
+    releaseSpacerExcess();
+  });
+  useAuiEvent("thread.initialize", releaseSpacerExcess);
+  useAuiEvent("threadListItem.switchedTo", releaseSpacerExcess);
 
   // Page-wide drag-and-drop: dropping a file anywhere on the chat page (not
   // just on the composer) attaches it and shows the composer drop affordance.
   // The composer's own dropzone still handles drops on the box itself; its
   // handler calls preventDefault, so the page handler skips them (no double-add).
-  const aui = useAui();
   const [pageDragging, setPageDragging] = useState(false);
   const dragDepth = useRef(0);
   const hasFiles = (e: ReactDragEvent) =>
@@ -208,7 +365,7 @@ export const Thread: FC<{
       >
         <IntentAwareScrollProvider value={autoScrollContext}>
           <ThreadPrimitive.Viewport
-            ref={viewportRef}
+            ref={composedViewportRef}
             autoScroll={false}
             scrollToBottomOnRunStart={false}
             scrollToBottomOnInitialize={false}
@@ -240,7 +397,15 @@ export const Thread: FC<{
             sticky footer and feel cramped. */}
             <AuiIf condition={({ thread }) => hideWelcome || !thread.isEmpty}>
               <div
-                className={cn("shrink-0", hideComposer ? "h-16" : "h-40")}
+                ref={spacerRef}
+                className={cn(
+                  "shrink-0",
+                  hideComposer
+                    ? "h-16"
+                    : composerHeight == null
+                      ? "h-40"
+                      : undefined,
+                )}
                 aria-hidden={true}
               />
             </AuiIf>
@@ -250,21 +415,34 @@ export const Thread: FC<{
                 className={cn(
                   "aui-thread-viewport-footer pointer-events-none sticky z-20 flex w-full justify-center bg-transparent",
                   // 150px (was 140px) to add a small gap above the composer
-                  hideComposer ? "bottom-3" : "bottom-[150px]",
+                  hideComposer
+                    ? "bottom-3"
+                    : footerBottomPx == null
+                      ? "bottom-[150px]"
+                      : undefined,
                 )}
+                style={
+                  !hideComposer && footerBottomPx != null
+                    ? { bottom: footerBottomPx }
+                    : undefined
+                }
               >
                 <ThreadScrollToBottom />
               </ThreadPrimitive.ViewportFooter>
             </AuiIf>
           </ThreadPrimitive.Viewport>
 
-          <GeneratedImageViewportOverlay hideComposer={hideComposer} />
+          <GeneratedImageViewportOverlay
+            hideComposer={hideComposer}
+            bottomOffsetPx={footerBottomPx}
+          />
 
           {!hideComposer && (
             <AuiIf condition={({ thread }) => hideWelcome || !thread.isEmpty}>
               <ThreadComposerDock
                 disabled={isComposerAttachPending}
                 threadId={threadId}
+                onHeightChange={setComposerHeight}
               />
             </AuiIf>
           )}
@@ -275,9 +453,10 @@ export const Thread: FC<{
   );
 };
 
-const GeneratedImageViewportOverlay: FC<{ hideComposer?: boolean }> = ({
-  hideComposer,
-}) => {
+const GeneratedImageViewportOverlay: FC<{
+  hideComposer?: boolean;
+  bottomOffsetPx?: number | null;
+}> = ({ hideComposer, bottomOffsetPx }) => {
   const { overlay, closeOverlay } = useGeneratedImageOverlay();
 
   useEffect(() => {
@@ -302,8 +481,17 @@ const GeneratedImageViewportOverlay: FC<{ hideComposer?: boolean }> = ({
       <section
         className={cn(
           "pointer-events-none absolute inset-x-5 top-[48px] flex flex-col items-center",
-          hideComposer ? "bottom-4" : "bottom-[150px]",
+          hideComposer
+            ? "bottom-4"
+            : bottomOffsetPx == null
+              ? "bottom-[150px]"
+              : undefined,
         )}
+        style={
+          !hideComposer && bottomOffsetPx != null
+            ? { bottom: bottomOffsetPx }
+            : undefined
+        }
         aria-label="Generated image preview"
       >
         <div className="pointer-events-auto relative flex min-h-0 w-full max-w-[1100px] flex-1 flex-col items-center justify-center gap-3 rounded-3xl bg-muted/10 p-3 ring-1 ring-border/20">
@@ -370,11 +558,29 @@ const GeneratedImageViewportOverlay: FC<{ hideComposer?: boolean }> = ({
 const ThreadComposerDock: FC<{
   disabled?: boolean;
   threadId?: string | null;
-}> = ({ disabled, threadId }) => {
+  onHeightChange?: (height: number | null) => void;
+}> = ({ disabled, threadId, onHeightChange }) => {
   const { overlay } = useGeneratedImageOverlay();
 
+  // Report the dock's rendered height so the viewport can reserve matching
+  // scroll space when attachments or multiline input grow the composer.
+  const dockRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    const el = dockRef.current;
+    if (!el || !onHeightChange) return;
+    const measure = () => onHeightChange(el.offsetHeight);
+    measure();
+    const resizeObserver = new ResizeObserver(measure);
+    resizeObserver.observe(el);
+    return () => {
+      resizeObserver.disconnect();
+      onHeightChange(null);
+    };
+  }, [onHeightChange]);
+
   return (
     <div
+      ref={dockRef}
       className={cn(
         "aui-thread-composer-dock pointer-events-none absolute bottom-0 left-0 right-0 md:right-[10px]",
         overlay ? "z-40" : "z-20",
diff --git a/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx b/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
index d5927f77c1..e4c17a5021 100644
--- a/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
+++ b/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
@@ -77,6 +77,14 @@ type AutoScrollContextValue = {
   scrollToBottom: ScrollToBottom;
   getIsAtBottom: () => boolean;
   subscribe: (listener: () => void) => () => void;
+  /**
+   * Mark the user as detached from the bottom, as if they had scrolled
+   * up. Called when the composer grows and the bottom spacer grows with
+   * it: the chat is then above the new bottom, and observer-driven pins
+   * must not shove it up. Scrolling back to the bottom re-attaches;
+   * explicit pins (run start, scroll-to-bottom button) still work.
+   */
+  detachFromBottom: () => void;
 };
 
 const noopContext: AutoScrollContextValue = {
@@ -87,6 +95,9 @@ const noopContext: AutoScrollContextValue = {
   subscribe: () => () => {
     /* no-op */
   },
+  detachFromBottom: () => {
+    /* no viewport mounted */
+  },
 };
 
 const AutoScrollContext = createContext<AutoScrollContextValue>(noopContext);
@@ -129,6 +140,9 @@ export function useIntentAwareAutoScroll(): {
   const scrollImplRef = useRef<ScrollToBottom>(() => {
     /* no viewport mounted */
   });
+  const detachImplRef = useRef<() => void>(() => {
+    /* no viewport mounted */
+  });
 
   const getIsAtBottom = useCallback(() => isAtBottomRef.current, []);
 
@@ -153,8 +167,12 @@ export function useIntentAwareAutoScroll(): {
     scrollImplRef.current(behavior);
   }, []);
 
+  const detachFromBottom = useCallback(() => {
+    detachImplRef.current();
+  }, []);
+
   const attach = useCallback(
-    (el: HTMLElement) => {
+    (el: HTMLElement, isRebind: boolean) => {
       let rafId: number | null = null;
       let lastScrollTop = el.scrollTop;
       let lastClientWidth = el.clientWidth;
@@ -286,6 +304,13 @@ export function useIntentAwareAutoScroll(): {
         requestTick();
       };
 
+      // Programmatic detach (see detachFromBottom). Same effect as the
+      // user scrolling up; the tick refresh updates isAtBottom.
+      detachImplRef.current = () => {
+        detach();
+        requestTick();
+      };
+
       const onWheel = (e: WheelEvent) => {
         if (
           e.deltaY < 0 &&
@@ -476,21 +501,24 @@ export function useIntentAwareAutoScroll(): {
       const mutationObserver = new MutationObserver(onLayoutChange);
       const onViewportResize = onLayoutChange;
 
-      // Fresh attach always starts pinned. `userDetachedRef` survives
-      // ref rebinds (it's hook-scoped), so if the viewport element is
-      // ever unmounted and remounted without an AUI lifecycle event
-      // (e.g. a parent layout refactor that remounts the viewport),
-      // a prior detach would silently disable auto-follow for the
-      // rest of the session.
-      userDetachedRef.current = false;
+      // Fresh attach (a new viewport element) always starts pinned.
+      // Rebinds to the SAME element must not pin or reset detach state:
+      // the Viewport composes refs with an identity that changes on
+      // re-render, so React re-runs the ref (null, then same element)
+      // on unrelated renders such as composer resizes. Pinning here
+      // would yank the chat to the bottom on every such render. The
+      // observers below are re-installed either way.
+      if (!isRebind) {
+        userDetachedRef.current = false;
 
-      // Pin to bottom when the ref first attaches. Covers the case
-      // where `thread.initialize` fires before the ref is bound.
-      extendFollow();
-      if (el.scrollHeight > el.clientHeight) {
-        el.scrollTo({ top: el.scrollHeight, behavior: "instant" });
+        // Pin to bottom when the ref first attaches. Covers the case
+        // where `thread.initialize` fires before the ref is bound.
+        extendFollow();
+        if (el.scrollHeight > el.clientHeight) {
+          el.scrollTo({ top: el.scrollHeight, behavior: "instant" });
+        }
+        setIsAtBottom(true);
       }
-      setIsAtBottom(true);
       requestTick();
 
       // Observe the border box, not the content box. The stabilizer
@@ -544,6 +572,9 @@ export function useIntentAwareAutoScroll(): {
         scrollImplRef.current = () => {
           /* no viewport mounted */
         };
+        detachImplRef.current = () => {
+          /* no viewport mounted */
+        };
       };
     },
     [setIsAtBottom],
@@ -562,6 +593,7 @@ export function useIntentAwareAutoScroll(): {
   useAuiEvent("thread.initialize", () => pinToBottom("instant"));
   useAuiEvent("threadListItem.switchedTo", () => pinToBottom("instant"));
 
+  const lastElRef = useRef<HTMLElement | null>(null);
   const ref = useCallback<RefCallback<HTMLElement>>(
     (el) => {
       if (cleanupRef.current) {
@@ -569,15 +601,20 @@ export function useIntentAwareAutoScroll(): {
         cleanupRef.current = null;
       }
       if (el) {
-        cleanupRef.current = attach(el);
+        // Same-element rebind vs a genuinely new element, see attach().
+        const isRebind = lastElRef.current === el;
+        lastElRef.current = el;
+        cleanupRef.current = attach(el, isRebind);
       }
+      // On null, keep lastElRef so a rebind to the same element is
+      // recognized; a real remount binds a different element anyway.
     },
     [attach],
   );
 
   const context = useMemo<AutoScrollContextValue>(
-    () => ({ scrollToBottom, getIsAtBottom, subscribe }),
-    [scrollToBottom, getIsAtBottom, subscribe],
+    () => ({ scrollToBottom, getIsAtBottom, subscribe, detachFromBottom }),
+    [scrollToBottom, getIsAtBottom, subscribe, detachFromBottom],
   );
 
   return { ref, context };

From b2b4e4c37655fa9a3ce19555c9868a1b7240b4dd Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Sun, 7 Jun 2026 21:43:09 -0700
Subject: [PATCH 106/222] CI: allowlist deepseek_ocr2 in the compiler
 full-model-sweep (#6085)

transformers-latest ships a new deepseek_ocr2 model whose source-rewriter
compile exceeds the 60s per-model budget on the CI runner, same as the
existing beit/sam/sam_hq entries. Add it to KNOWN_BROKEN_COMPILE Category F
so HF=latest Core stops failing on a new upstream model. The slow compile
path itself remains a follow-up for unsloth_zoo.
---
 .github/workflows/consolidated-tests-ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index f8eccc7d18..bf7e62e295 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -992,6 +992,7 @@ jobs:
               "beit":            "TimeoutError: compile exceeds per-model budget",
               "sam":             "TimeoutError: compile exceeds per-model budget",
               "sam_hq":          "TimeoutError: compile exceeds per-model budget",
+              "deepseek_ocr2":   "TimeoutError: compile exceeds per-model budget",
           }
 
 

From e20a6c30206e213f5e18111460a20281ce89c33b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 03:40:47 -0700
Subject: [PATCH 107/222] Restore KTO logps truncation guard for TRL (re-apply
 dropped #5996) (#6086)

* Restore KTO logps truncation guard for TRL (re-apply dropped #5996)

#5996 ported the KTO truncation guard to TRL's _compute_logps refactor but was
dropped from main in the 2026-06-05 history rewrite. Re-apply the
unsloth/models/rl_replacements.py guard (kto_trainer_get_batch_logps +
kto_trainer_align_completion_logps); its regexes still match TRL main's current
compute_ref_log_probs / _compute_kl_logps shape
(per_token_logps = selective_log_softmax(shift_logits, ...)), so the guard
remains effective.

Also extend the version_compat detection to recognize that current shape: TRL
refactored KTO again (no get_batch_logps / _compute_logps), so the test was
failing on TRL main even though the rewrite still applies.

* KTO patcher: match single or double quotes in dict-key regexes

Per review: _KTO_COMPLETION_RE / _KTO_KL_RE hardcoded double quotes for the
TRL dict keys, so a formatter or TRL version using single quotes would make the
patch silently skip. Accept both quote styles. Verified the regexes still match
TRL main's current experimental/kto source.
---
 .../test_trl_grpo_pinned_symbols.py           | 25 +++++---
 unsloth/models/rl_replacements.py             | 57 +++++++++++++++++++
 2 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index 4c7dcc4234..815cb5f784 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -551,12 +551,12 @@ def test_trl_grpo_source_inference_mode_unwrap(tag: str):
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
 def test_trl_kto_get_batch_logps_signature(tag: str):
-    """TRL 0.27+ moved KTOTrainer to trl.experimental.kto and the
-    canonical kto_trainer.py shrank to a thin re-export wrapper. The
-    real `get_batch_logps` lives at trl/experimental/kto/kto_trainer.py.
-    Unsloth's MRO walk in models/rl.py:592-708 already follows
-    trl.experimental.* parents, so either path is fine — we just
-    require the symbol to exist SOMEWHERE."""
+    """KTO log-prob computation must stay patchable. Through TRL 1.x the
+    target was KTOTrainer.get_batch_logps; TRL 1.x dropped it and moved the
+    math into _compute_logps / compute_ref_log_probs calling
+    selective_log_softmax. unsloth/models/rl_replacements.py patches BOTH
+    shapes (kto_trainer_get_batch_logps + kto_trainer_align_completion_logps),
+    so we require EITHER form to exist wherever KTOTrainer lives."""
     candidates = [
         "trl/trainer/kto_trainer.py",
         "trl/experimental/kto/kto_trainer.py",
@@ -566,11 +566,20 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         src = fetch_text("huggingface/trl", tag, path)
         if src is None:
             continue
+        # Legacy: explicit get_batch_logps method.
         if has_def(src, "get_batch_logps", "func"):
             return
+        # TRL 1.x: refactored into _compute_logps + selective_log_softmax.
+        if has_def(src, "_compute_logps", "func") and "selective_log_softmax" in src:
+            return
+        # TRL 1.x (current): compute_ref_log_probs / _compute_kl_logps build
+        # per_token_logps via selective_log_softmax(shift_logits, ...); this is
+        # the exact shape kto_trainer_align_completion_logps patches.
+        if "per_token_logps = selective_log_softmax(shift_logits" in src:
+            return
     pytest.fail(
-        f"{tag}: KTOTrainer.get_batch_logps not found in any of {candidates}; "
-        f"unsloth/models/rl_replacements.py:1675 rewrite silently skipped"
+        f"{tag}: KTO log-prob computation not found in any of {candidates}; "
+        f"unsloth/models/rl_replacements.py KTO rewrite silently skipped"
     )
 
 
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 31d54675c9..7bceebb252 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -1962,6 +1962,63 @@ def kto_trainer_get_batch_logps(function_name, function):
 RL_FUNCTIONS["kto_trainer"].append(kto_trainer_get_batch_logps)
 
 
+# TRL 1.x dropped KTOTrainer.get_batch_logps and moved the log-prob math into
+# _compute_logps / compute_ref_log_probs / _compute_kl_logps, which call
+# selective_log_softmax on completion-only tokens. Same truncation hazard as
+# above, so clamp logits/ids/mask to the shorter seq length (no-op when equal).
+_KTO_COMPLETION_RE = re.compile(
+    r"(?P<ws>[ \t]*)shift_logits = completion_logits\[:, :-1, :\]\.contiguous\(\)\n"
+    r"(?P=ws)per_token_logps = selective_log_softmax\(\s*shift_logits,\s*"
+    r"(?P<var>\w+)\[[\"']completion_input_ids[\"']\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
+    r"(?P=ws)per_token_logps\[(?P=var)\[[\"']completion_mask[\"']\]\[:, 1:\] == 0\] = 0\.0"
+)
+_KTO_KL_RE = re.compile(
+    r"(?P<ws>[ \t]*)shift_KL_logits = KL_logits\[:, :-1, :\]\.contiguous\(\)\n"
+    r"(?P=ws)KL_per_token_logps = selective_log_softmax\(\s*shift_KL_logits,\s*"
+    r"(?P<var>\w+)\[[\"']KL_completion_input_ids[\"']\]\[:, 1:\]\.contiguous\(\)\s*\)\n"
+    r"(?P=ws)KL_per_token_logps\[(?P=var)\[[\"']KL_completion_mask[\"']\]\[:, 1:\] == 0\] = 0\.0"
+)
+
+
+def _kto_completion_repl(m):
+    ws, var = m.group("ws"), m.group("var")
+    return (
+        f"{ws}shift_logits = completion_logits[:, :-1, :].contiguous()\n"
+        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
+        f'{ws}_uns_ids = {var}["completion_input_ids"][:, 1:].contiguous()\n'
+        f"{ws}_uns_n = min(shift_logits.shape[1], _uns_ids.shape[1])\n"
+        f"{ws}per_token_logps = selective_log_softmax(shift_logits[:, :_uns_n], _uns_ids[:, :_uns_n])\n"
+        f'{ws}per_token_logps[{var}["completion_mask"][:, 1:][:, :_uns_n] == 0] = 0.0'
+    )
+
+
+def _kto_kl_repl(m):
+    ws, var = m.group("ws"), m.group("var")
+    return (
+        f"{ws}shift_KL_logits = KL_logits[:, :-1, :].contiguous()\n"
+        f"{ws}# Unsloth: clamp logits/ids/mask to shorter seq len (model may truncate input_ids)\n"
+        f'{ws}_uns_kl_ids = {var}["KL_completion_input_ids"][:, 1:].contiguous()\n'
+        f"{ws}_uns_kl_n = min(shift_KL_logits.shape[1], _uns_kl_ids.shape[1])\n"
+        f"{ws}KL_per_token_logps = selective_log_softmax(shift_KL_logits[:, :_uns_kl_n], _uns_kl_ids[:, :_uns_kl_n])\n"
+        f'{ws}KL_per_token_logps[{var}["KL_completion_mask"][:, 1:][:, :_uns_kl_n] == 0] = 0.0'
+    )
+
+
+def kto_trainer_align_completion_logps(function_name, function):
+    if function_name not in (
+        "_compute_logps",
+        "compute_ref_log_probs",
+        "_compute_kl_logps",
+    ):
+        return function
+    function = _KTO_COMPLETION_RE.sub(_kto_completion_repl, function)
+    function = _KTO_KL_RE.sub(_kto_kl_repl, function)
+    return function
+
+
+RL_FUNCTIONS["kto_trainer"].append(kto_trainer_align_completion_logps)
+
+
 # https://github.com/huggingface/trl/blob/main/trl/trainer/grpo_trainer.py#L356
 # TRL warns if batch size is not a multiple of num_generations -> fix this.
 def grpo_trainer_fix_batch_size(RLTrainer_source, RLConfig_source):

From 8ccdf596aa8e69f9f949c07098cbced0c37ae111 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 03:40:59 -0700
Subject: [PATCH 108/222] Studio: stop leaking internal exceptions to API
 clients; harden sandbox path (#6072)

* Studio: stop leaking internal exceptions to API clients; harden sandbox path

Security hardening for the FastAPI backend.

Error exposure (CodeQL py/stack-trace-exposure): many route handlers returned
raw caught-exception text to clients via HTTPException detail / response bodies,
which can leak internal filesystem paths and stack detail. Add shared helpers in
utils/utils.py (safe_error_detail, log_and_http_error) that log the full
exception server-side and return a generic message, and sweep the route layer
(inference, models, export, training, datasets, chat_history, providers,
mcp_servers, settings, data_recipe/{jobs,seed,validate,mcp}) to use them.
Intentionally user-facing validation messages, the existing _friendly_error SSE
paths, and upstream-service body passthrough (llama-server / OpenAI) are kept;
absolute server paths echoed in models.py browse/read errors are redacted.

Path injection (CodeQL py/path-injection): serve_sandbox_file already does
basename + realpath containment; add a strict filename allowlist
(^[A-Za-z0-9._-]{1,255}$) before the path is built as defense-in-depth and to
give the analyzer a clear sanitizer.

No behavior change beyond error-message text; status codes preserved.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address review: keep curated error messages, fix remaining load leak

- inference.py /load non-native path: redact str(e) instead of leaking it
  (matched the native branch which already redacted).
- llama_extra_args validation: return the curated, path-redacted message
  instead of the generic fallback so users see the offending flag.
- sandbox file serving: allowlist now forbids only separators/control chars
  via fullmatch, so generated images like 'loss curve.png' render again
  while traversal is still blocked by basename + extension + realpath.
- Add safe_curated_detail() for domain/validation exceptions whose message
  is intentionally user-facing; apply it to data_recipe job/validate,
  chat conflict, provider test, and MCP probe paths (these were collapsing
  to 'An internal error occurred', and 'connection' even mis-mapped to an
  upstream-service message). Generic Exception paths keep safe_error_detail.
- log_and_http_error: tolerate stdlib loggers (no structlog kwargs).
- delete_openai_container: log transport errors with exc_info like list/create.
- Drop helper/HTTPException imports this change left unused.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* log_and_http_error: log original error traceback on stdlib-logger fallback

* Tidy error-helper and sandbox comments for PR #6072

* Trim redundant comments in studio error-hardening routes for PR #6072

* Re-trigger CI now that unsloth-zoo #727 is merged (Core pulls zoo main)

* Address PR #6072 review feedback

- inference.py: keep the actionable NativePathLeaseError detail (path-redacted)
  instead of collapsing it to the generic message, matching the other curated
  validation paths in this file.
- utils.py: log via a single formatted log.error(exc_info=error) call that works
  for structlog and stdlib loggers; drop the now-unneeded try/except helper.
- models.py: use Path.name instead of os.path.basename(str(current)).

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/routes/chat_history.py         |  28 ++++-
 studio/backend/routes/data_recipe/jobs.py     |  51 ++++++--
 studio/backend/routes/data_recipe/mcp.py      |  17 ++-
 studio/backend/routes/data_recipe/seed.py     |  50 ++++++--
 studio/backend/routes/data_recipe/validate.py |  25 +++-
 studio/backend/routes/datasets.py             |   6 +-
 studio/backend/routes/export.py               |  18 +--
 studio/backend/routes/inference.py            |  83 +++++++++----
 studio/backend/routes/mcp_servers.py          |  25 +++-
 studio/backend/routes/models.py               | 113 ++++++++++++------
 studio/backend/routes/providers.py            |  20 +++-
 studio/backend/routes/settings.py             |  14 ++-
 studio/backend/routes/training.py             |  57 ++++++---
 studio/backend/utils/utils.py                 |  61 ++++++++++
 14 files changed, 436 insertions(+), 132 deletions(-)

diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 75b5be2e49..4da3c7d621 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -11,6 +11,8 @@ from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
 from auth.authentication import get_current_subject
+from loggers import get_logger
+from utils.utils import safe_curated_detail, log_and_http_error
 from storage.studio_db import (
     ChatMessageConflictError,
     CorruptSettingsError,
@@ -40,6 +42,8 @@ from storage.studio_db import (
 
 router = APIRouter()
 
+logger = get_logger(__name__)
+
 
 class ChatThread(BaseModel):
     id: str
@@ -406,7 +410,13 @@ async def save_thread_message(
     try:
         return ChatMessage(**upsert_chat_message(payload.model_dump()))
     except ChatMessageConflictError as exc:
-        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            409,
+            safe_curated_detail(exc),
+            event = "chat_history.save_message_conflict",
+            log = logger,
+        ) from exc
 
 
 @router.put("/threads/{thread_id}/messages", response_model = ChatMessageListResponse)
@@ -442,7 +452,13 @@ async def replace_thread_messages(
             ]
         )
     except ChatMessageConflictError as exc:
-        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            409,
+            safe_curated_detail(exc),
+            event = "chat_history.replace_messages_conflict",
+            log = logger,
+        ) from exc
 
 
 @router.get("/count", response_model = ChatCountResponse)
@@ -497,7 +513,13 @@ async def put_settings(
             settings = upsert_chat_settings_merge(parsed.model_dump(exclude_unset = True))
         )
     except CorruptSettingsError as exc:
-        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            409,
+            safe_curated_detail(exc),
+            event = "chat_history.put_settings_conflict",
+            log = logger,
+        ) from exc
 
 
 @router.get("/export", response_model = ChatExportResponse)
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index 107a1657f3..238ff08006 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -19,13 +19,16 @@ from core.data_recipe.huggingface import (
     publish_recipe_dataset,
 )
 from core.data_recipe.jobs import get_job_manager
+from loggers import get_logger
 from models.data_recipe import (
     JobCreateResponse,
     PublishDatasetRequest,
     PublishDatasetResponse,
     RecipePayload,
 )
+from utils.utils import safe_error_detail, safe_curated_detail, log_and_http_error
 
+logger = get_logger(__name__)
 router = APIRouter()
 
 
@@ -439,14 +442,24 @@ def create_job(payload: RecipePayload, request: Request):
 
             RunConfig.model_validate(run_config_raw)
         except (ImportError, ValidationError, TypeError, ValueError) as exc:
-            raise HTTPException(
-                status_code = 400, detail = f"invalid run_config: {exc}"
+            raise log_and_http_error(
+                exc,
+                400,
+                "invalid run_config",
+                event = "data_recipe.jobs.run_config_invalid",
+                log = logger,
             ) from exc
 
     try:
         internal_api_key_id = _inject_local_providers(recipe, request)
     except ValueError as exc:
-        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            400,
+            safe_curated_detail(exc),
+            event = "data_recipe.jobs.inject_local_providers_failed",
+            log = logger,
+        ) from exc
 
     # Single try block covers get_job_manager() AND mgr.start() so a workflow
     # key minted above never outlives the request even when an unexpected
@@ -463,11 +476,23 @@ def create_job(payload: RecipePayload, request: Request):
     except RuntimeError as exc:
         if internal_api_key_id is not None:
             _revoke_internal_api_key_safe(internal_api_key_id)
-        raise HTTPException(status_code = 409, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            409,
+            safe_curated_detail(exc),
+            event = "data_recipe.jobs.start_conflict",
+            log = logger,
+        ) from exc
     except ValueError as exc:
         if internal_api_key_id is not None:
             _revoke_internal_api_key_safe(internal_api_key_id)
-        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            400,
+            safe_curated_detail(exc),
+            event = "data_recipe.jobs.start_failed",
+            log = logger,
+        ) from exc
     except Exception:
         if internal_api_key_id is not None:
             _revoke_internal_api_key_safe(internal_api_key_id)
@@ -593,9 +618,21 @@ def publish_job_dataset(job_id: str, payload: PublishDatasetRequest):
             private = payload.private,
         )
     except RecipeDatasetPublishError as exc:
-        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            400,
+            safe_curated_detail(exc),
+            event = "data_recipe.jobs.publish_failed",
+            log = logger,
+        ) from exc
     except Exception as exc:
-        raise HTTPException(status_code = 500, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            500,
+            safe_error_detail(exc),
+            event = "data_recipe.jobs.publish_error",
+            log = logger,
+        ) from exc
 
     return {
         "success": True,
diff --git a/studio/backend/routes/data_recipe/mcp.py b/studio/backend/routes/data_recipe/mcp.py
index 7184934ce9..2c79d323f3 100644
--- a/studio/backend/routes/data_recipe/mcp.py
+++ b/studio/backend/routes/data_recipe/mcp.py
@@ -10,12 +10,15 @@ from collections import defaultdict
 from fastapi import APIRouter
 
 from core.data_recipe.service import build_mcp_providers
+from loggers import get_logger
 from models.data_recipe import (
     McpToolsListRequest,
     McpToolsListResponse,
     McpToolsProviderResult,
 )
+from utils.utils import safe_error_detail
 
+logger = get_logger(__name__)
 router = APIRouter()
 
 
@@ -24,11 +27,16 @@ def list_mcp_tools(payload: McpToolsListRequest) -> McpToolsListResponse:
     try:
         from data_designer.engine.mcp import io as mcp_io
     except ImportError as exc:
+        logger.error(
+            "data_recipe.mcp.dependencies_unavailable",
+            error = str(exc),
+            exc_info = True,
+        )
         return McpToolsListResponse(
             providers = [
                 McpToolsProviderResult(
                     name = "",
-                    error = f"MCP dependencies unavailable: {exc}",
+                    error = "MCP dependencies unavailable.",
                 )
             ]
         )
@@ -73,10 +81,15 @@ def list_mcp_tools(payload: McpToolsListRequest) -> McpToolsListResponse:
                 )
             )
         except Exception as exc:
+            logger.error(
+                "data_recipe.mcp.list_tools_failed",
+                error = str(exc),
+                exc_info = True,
+            )
             providers.append(
                 McpToolsProviderResult(
                     name = provider.name or provider_name,
-                    error = str(exc).strip() or "Failed to load tools.",
+                    error = safe_error_detail(exc, fallback = "Failed to load tools."),
                 )
             )
 
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index a18f8f3e32..51ea37452e 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -30,7 +30,9 @@ except ImportError:
     normalize_unstructured_text = None
     resolve_chunking = None
 from core.data_recipe.jsonable import to_preview_jsonable
+from loggers import get_logger
 from utils.paths import ensure_dir, seed_uploads_root, unstructured_uploads_root
+from utils.utils import log_and_http_error
 from utils.upload_limits import (
     LOCAL_SEED_UPLOAD_MAX_BYTES,
     LOCAL_SEED_UPLOAD_MAX_LABEL,
@@ -47,6 +49,7 @@ from models.data_recipe import (
     UnstructuredFileUploadResponse,
 )
 
+logger = get_logger(__name__)
 router = APIRouter()
 
 DATA_EXTS = (".parquet", ".jsonl", ".json", ".csv")
@@ -201,8 +204,12 @@ def _read_preview_rows_from_local_file(
     try:
         import pandas as pd
     except ImportError as exc:
-        raise HTTPException(
-            status_code = 500, detail = f"seed inspect dependencies unavailable: {exc}"
+        raise log_and_http_error(
+            exc,
+            500,
+            "seed inspect dependencies unavailable",
+            event = "data_recipe.seed.dependencies_unavailable",
+            log = logger,
         ) from exc
 
     ext = path.suffix.lower()
@@ -231,8 +238,12 @@ def _read_preview_rows_from_local_file(
     except HTTPException:
         raise
     except (ValueError, OSError) as exc:
-        raise HTTPException(
-            status_code = 422, detail = f"seed inspect failed: {exc}"
+        raise log_and_http_error(
+            exc,
+            422,
+            "seed inspect failed",
+            event = "data_recipe.seed.local_preview_failed",
+            log = logger,
         ) from exc
 
     rows = df.to_dict(orient = "records")
@@ -260,8 +271,12 @@ def _read_preview_rows_from_unstructured_file(
             chunk_overlap = overlap,
         )
     except (FileNotFoundError, RuntimeError, ValueError, OSError) as exc:
-        raise HTTPException(
-            status_code = 422, detail = f"seed inspect failed: {exc}"
+        raise log_and_http_error(
+            exc,
+            422,
+            "seed inspect failed",
+            event = "data_recipe.seed.unstructured_preview_failed",
+            log = logger,
         ) from exc
     return _serialize_preview_rows(rows)
 
@@ -312,8 +327,12 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
     try:
         from datasets import load_dataset
     except ImportError as exc:
-        raise HTTPException(
-            status_code = 500, detail = f"seed inspect dependencies unavailable: {exc}"
+        raise log_and_http_error(
+            exc,
+            500,
+            "seed inspect dependencies unavailable",
+            event = "data_recipe.seed.dependencies_unavailable",
+            log = logger,
         ) from exc
 
     split = _normalize_optional_text(payload.split) or DEFAULT_SPLIT
@@ -356,8 +375,12 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
                 preview_size = preview_size,
             )
         except (ValueError, OSError, RuntimeError) as exc:
-            raise HTTPException(
-                status_code = 422, detail = f"seed inspect failed: {exc}"
+            raise log_and_http_error(
+                exc,
+                422,
+                "seed inspect failed",
+                event = "data_recipe.seed.hf_preview_failed",
+                log = logger,
             ) from exc
 
     if not preview_rows:
@@ -480,12 +503,17 @@ async def upload_unstructured_file(
     except Exception as e:
         raw_path.unlink(missing_ok = True)
         extracted_path.unlink(missing_ok = True)
+        logger.error(
+            "data_recipe.seed.text_extraction_failed",
+            error = str(e),
+            exc_info = True,
+        )
         return UnstructuredFileUploadResponse(
             file_id = file_id,
             filename = original_filename,
             size_bytes = size_bytes,
             status = "error",
-            error = f"Text extraction failed: {type(e).__name__}: {e}",
+            error = "Text extraction failed.",
         )
 
     try:
diff --git a/studio/backend/routes/data_recipe/validate.py b/studio/backend/routes/data_recipe/validate.py
index e794d68e54..f6fd9e6046 100644
--- a/studio/backend/routes/data_recipe/validate.py
+++ b/studio/backend/routes/data_recipe/validate.py
@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter
 
 from core.data_recipe.service import (
     build_config_builder,
@@ -16,6 +16,7 @@ from core.data_recipe.service import (
 )
 from loggers import get_logger
 from models.data_recipe import RecipePayload, ValidateError, ValidateResponse
+from utils.utils import safe_error_detail, safe_curated_detail, log_and_http_error
 
 logger = get_logger(__name__)
 router = APIRouter()
@@ -170,7 +171,12 @@ def validate(payload: RecipePayload) -> ValidateResponse:
                 missing_module = exc.name,
             )
         except Exception as exc:
-            detail = str(exc).strip() or "Validation failed."
+            logger.error(
+                "data_recipe.validate.github_config_failed",
+                error = str(exc),
+                exc_info = True,
+            )
+            detail = safe_error_detail(exc, fallback = "Validation failed.")
             return ValidateResponse(
                 valid = False,
                 errors = [ValidateError(message = detail)],
@@ -181,9 +187,20 @@ def validate(payload: RecipePayload) -> ValidateResponse:
     try:
         validate_recipe(recipe)
     except RuntimeError as exc:
-        raise HTTPException(status_code = 503, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            503,
+            safe_error_detail(exc),
+            event = "data_recipe.validate.service_unavailable",
+            log = logger,
+        ) from exc
     except Exception as exc:
-        detail = str(exc).strip() or "Validation failed."
+        logger.error(
+            "data_recipe.validate.recipe_failed",
+            error = str(exc),
+            exc_info = True,
+        )
+        detail = safe_curated_detail(exc, fallback = "Validation failed.")
         parsed_errors = _collect_validation_errors(recipe)
         return ValidateResponse(
             valid = False,
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index c34d6d8732..1ea696705c 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -647,9 +647,7 @@ def check_format(
         raise
     except Exception as e:
         logger.error(f"Error checking dataset format: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to check dataset format: {str(e)}"
-        )
+        raise HTTPException(status_code = 500, detail = "Failed to check dataset format")
 
 
 @router.post("/ai-assist-mapping", response_model = AiAssistMappingResponse)
@@ -705,4 +703,4 @@ def ai_assist_mapping(
 
     except Exception as e:
         logger.error(f"AI assist mapping failed: {e}", exc_info = True)
-        raise HTTPException(status_code = 500, detail = f"AI assist failed: {str(e)}")
+        raise HTTPException(status_code = 500, detail = "AI assist failed")
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index 7dbc52dbed..2bfca30cee 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -26,6 +26,8 @@ if str(backend_path) not in sys.path:
 # Auth
 from auth.authentication import get_current_subject
 
+from utils.utils import safe_error_detail
+
 # Import backend functions
 try:
     from core.export import get_export_backend
@@ -125,7 +127,7 @@ async def load_checkpoint(
         logger.error(f"Error loading checkpoint: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to load checkpoint: {str(e)}",
+            detail = "Failed to load checkpoint",
         )
 
 
@@ -158,7 +160,7 @@ async def cleanup_export_memory(
         logger.error(f"Error during export memory cleanup: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to cleanup export memory: {str(e)}",
+            detail = "Failed to cleanup export memory",
         )
 
 
@@ -180,7 +182,7 @@ async def get_export_status(
         logger.error(f"Error getting export status: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to get export status: {str(e)}",
+            detail = "Failed to get export status",
         )
 
 
@@ -235,7 +237,7 @@ async def export_merged_model(
         logger.error(f"Error exporting merged model: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to export merged model: {str(e)}",
+            detail = "Failed to export merged model",
         )
 
 
@@ -275,7 +277,7 @@ async def export_base_model(
         logger.error(f"Error exporting base model: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to export base model: {str(e)}",
+            detail = "Failed to export base model",
         )
 
 
@@ -314,7 +316,7 @@ async def export_gguf(
         logger.error(f"Error exporting GGUF model: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to export GGUF model: {str(e)}",
+            detail = "Failed to export GGUF model",
         )
 
 
@@ -353,7 +355,7 @@ async def export_lora_adapter(
         logger.error(f"Error exporting LoRA adapter: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to export LoRA adapter: {str(e)}",
+            detail = "Failed to export LoRA adapter",
         )
 
 
@@ -492,7 +494,7 @@ async def stream_export_logs(
             logger.error("Export log stream failed: %s", exc, exc_info = True)
             try:
                 yield _format_sse(
-                    json.dumps({"error": str(exc)}),
+                    json.dumps({"error": safe_error_detail(exc)}),
                     event = "error",
                 )
             except Exception:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index d3a279319a..5d22b3ff90 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -227,6 +227,7 @@ from core.inference.key_exchange import decrypt_api_key
 from core.inference.providers import get_provider_info, get_base_url
 from core.inference.external_provider import ExternalProviderClient
 from storage import providers_db
+from utils.utils import safe_error_detail, log_and_http_error
 
 import io
 import wave
@@ -697,7 +698,13 @@ def _resolve_model_identifier_for_request(
             allowed_suffixes = (".gguf",),
         )
     except NativePathLeaseError as exc:
-        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+        # Curated, client-correctable lease error (expired / wrong type / re-select);
+        # keep the actionable message, just redact paths.
+        logger.warning("inference.native_path_lease_failed: %s", exc)
+        raise HTTPException(
+            status_code = 400,
+            detail = redact_native_paths(str(exc)),
+        ) from exc
     display_label = (
         grant.display_label or Path(request.model_path).name or "Native model"
     )
@@ -735,7 +742,12 @@ async def load_model(
         try:
             extra_llama_args = validate_extra_args(request.llama_extra_args)
         except ValueError as exc:
-            raise HTTPException(status_code = 400, detail = str(exc))
+            # Keep the curated validation message (names the flag); just strip paths.
+            logger.warning("inference.validate_extra_args_failed: %s", exc)
+            raise HTTPException(
+                status_code = 400,
+                detail = redact_native_paths(str(exc)),
+            )
         # Re-narrow []-from-None back to None so the inheritance path
         # below can tell "caller omitted" from "caller explicit []".
         extra_llama_args: Optional[list[str]] = (
@@ -1221,7 +1233,8 @@ async def load_model(
             )
             raise HTTPException(status_code = 400, detail = redacted_msg)
         logger.warning("Rejected inference GPU selection: %s", e)
-        raise HTTPException(status_code = 400, detail = str(e))
+        # User-facing validation (e.g. "Invalid gpu_ids [99]"): redact paths, keep detail.
+        raise HTTPException(status_code = 400, detail = redact_native_paths(str(e)))
     except Exception as e:
         # Surface a friendlier message for models that Unsloth cannot load
         not_supported_hints = [
@@ -1245,7 +1258,7 @@ async def load_model(
                 detail = f"Failed to load native model {model_log_label}: {msg}",
             )
         logger.error(f"Error loading model: {e}", exc_info = True)
-        msg = str(e)
+        msg = redact_native_paths(str(e))
         if any(h.lower() in msg.lower() for h in not_supported_hints):
             msg = f"This model is not supported yet. Try a different model. (Original error: {msg})"
         raise HTTPException(status_code = 500, detail = f"Failed to load model: {msg}")
@@ -1324,7 +1337,7 @@ async def validate_model(
         )
         raise HTTPException(
             status_code = 400,
-            detail = f"Invalid model: {str(e)}",
+            detail = "Invalid model",
         )
 
 
@@ -1359,7 +1372,7 @@ async def unload_model(
 
     except Exception as e:
         logger.error(f"Error unloading model: {e}", exc_info = True)
-        raise HTTPException(status_code = 500, detail = f"Failed to unload model: {str(e)}")
+        raise HTTPException(status_code = 500, detail = "Failed to unload model")
 
 
 @studio_router.post("/cancel")
@@ -1444,8 +1457,12 @@ async def generate_stream(
         except HTTPException:
             raise
         except Exception as e:
-            raise HTTPException(
-                status_code = 400, detail = f"Failed to decode image: {str(e)}"
+            raise log_and_http_error(
+                e,
+                400,
+                "Failed to decode image",
+                event = "inference.decode_image_failed",
+                log = logger,
             )
 
     async def stream():
@@ -1614,7 +1631,7 @@ async def get_status(
 
     except Exception as e:
         logger.error(f"Error getting status: {e}", exc_info = True)
-        raise HTTPException(status_code = 500, detail = f"Failed to get status: {str(e)}")
+        raise HTTPException(status_code = 500, detail = "Failed to get status")
 
 
 @router.get("/load-progress", response_model = LoadProgressResponse)
@@ -1715,7 +1732,7 @@ async def generate_audio(
         )
     except Exception as e:
         logger.error(f"Audio generation error: {e}", exc_info = True)
-        raise HTTPException(status_code = 500, detail = str(e))
+        raise HTTPException(status_code = 500, detail = safe_error_detail(e))
 
     audio_b64 = base64.b64encode(wav_bytes).decode("ascii")
     return JSONResponse(
@@ -2402,9 +2419,12 @@ async def list_openai_containers(
                 detail = f"OpenAI rejected /containers list: {detail}",
             )
         except httpx.HTTPError as exc:
-            raise HTTPException(
-                status_code = 502,
-                detail = f"Failed to reach OpenAI: {exc}",
+            raise log_and_http_error(
+                exc,
+                502,
+                "Could not reach OpenAI.",
+                event = "openai_container_list.transport_error",
+                log = logger,
             )
         # OpenAI keeps expired containers in /v1/containers indefinitely
         # with status="expired" — they're effectively dead but still
@@ -2443,9 +2463,12 @@ async def create_openai_container(
                 detail = f"OpenAI rejected /containers create: {detail}",
             )
         except httpx.HTTPError as exc:
-            raise HTTPException(
-                status_code = 502,
-                detail = f"Failed to reach OpenAI: {exc}",
+            raise log_and_http_error(
+                exc,
+                502,
+                "Could not reach OpenAI.",
+                event = "openai_container_create.transport_error",
+                log = logger,
             )
         if not isinstance(raw, dict):
             raise HTTPException(
@@ -2490,14 +2513,12 @@ async def delete_openai_container(
                 detail = f"OpenAI rejected /containers delete: {detail}",
             )
         except httpx.HTTPError as exc:
-            logger.warning(
-                "openai_container_delete.transport_error container_id=%s error=%s",
-                body.container_id,
+            raise log_and_http_error(
                 exc,
-            )
-            raise HTTPException(
-                status_code = 502,
-                detail = f"Failed to reach OpenAI: {exc}",
+                502,
+                "Could not reach OpenAI.",
+                event = "openai_container_delete.transport_error",
+                log = logger,
             )
     finally:
         await client.close()
@@ -3262,7 +3283,7 @@ async def openai_chat_completions(
 
             except Exception as e:
                 logger.error(f"Error during GGUF completion: {e}", exc_info = True)
-                raise HTTPException(status_code = 500, detail = str(e))
+                raise HTTPException(status_code = 500, detail = safe_error_detail(e))
 
     # ── Standard Unsloth path ─────────────────────────────────
 
@@ -3290,7 +3311,13 @@ async def openai_chat_completions(
         except HTTPException:
             raise
         except Exception as e:
-            raise HTTPException(status_code = 400, detail = f"Failed to decode image: {e}")
+            raise log_and_http_error(
+                e,
+                400,
+                "Failed to decode image",
+                event = "inference.decode_image_failed",
+                log = logger,
+            )
 
     # Classify capability flags from the loaded template.
     _sf_model_info = backend.models.get(backend.active_model_name, {})
@@ -3817,7 +3844,7 @@ async def openai_chat_completions(
         except Exception as e:
             backend.reset_generation_state()
             logger.error(f"Error during OpenAI completion: {e}", exc_info = True)
-            raise HTTPException(status_code = 500, detail = str(e))
+            raise HTTPException(status_code = 500, detail = safe_error_detail(e))
 
 
 # =====================================================================
@@ -3869,6 +3896,10 @@ async def serve_sandbox_file(
     safe_filename = os.path.basename(filename)
     if not safe_filename or safe_filename in (".", ".."):
         raise HTTPException(status_code = 404, detail = "Not found")
+    # Defense-in-depth allowlist (clears CodeQL py/path-injection), still allowing
+    # names like "loss curve.png"; basename + extension + realpath below are the guards.
+    if not _re.fullmatch(r"[^/\\\x00-\x1f]{1,255}", safe_filename):
+        raise HTTPException(status_code = 404, detail = "Not found")
 
     # ── Extension allowlist ─────────────────────────────────────
     ext = os.path.splitext(safe_filename)[1].lower()
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 200c0ed452..87cdcf9402 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -26,6 +26,7 @@ from models.mcp_servers import (
     McpServerUpdate,
 )
 from storage import mcp_servers_db
+from utils.utils import safe_curated_detail, log_and_http_error
 
 logger = structlog.get_logger(__name__)
 
@@ -51,7 +52,13 @@ def _validate_url(url: str) -> str:
         try:
             parts = parse_stdio_command(trimmed)
         except ValueError as exc:
-            raise HTTPException(status_code = 400, detail = f"Invalid command: {exc}")
+            raise log_and_http_error(
+                exc,
+                400,
+                "Invalid command. Check quoting and try again.",
+                event = "mcp_servers.invalid_command",
+                log = logger,
+            )
         if not parts or not parts[0].strip():
             raise HTTPException(status_code = 400, detail = "command must not be empty")
         if "://" in parts[0]:
@@ -241,8 +248,13 @@ async def refresh_mcp_server_tools(
             use_oauth = use_oauth,
         )
     except Exception as exc:  # noqa: BLE001 — surface transport+timeout errors to UI
-        logger.warning("MCP refresh failed", server_id = server_id, error = str(exc))
-        return McpServerProbeResult(ok = False, error = str(exc))
+        logger.error(
+            "mcp_servers.refresh_failed",
+            server_id = server_id,
+            error = str(exc),
+            exc_info = True,
+        )
+        return McpServerProbeResult(ok = False, error = safe_curated_detail(exc))
 
     return McpServerProbeResult(ok = True, tool_count = len(tools))
 
@@ -265,6 +277,11 @@ async def test_mcp_server(
             use_oauth = payload.use_oauth,
         )
     except Exception as exc:  # noqa: BLE001
-        return McpServerProbeResult(ok = False, error = str(exc))
+        logger.error(
+            "mcp_servers.test_failed",
+            error = str(exc),
+            exc_info = True,
+        )
+        return McpServerProbeResult(ok = False, error = safe_curated_detail(exc))
 
     return McpServerProbeResult(ok = True, tool_count = len(tools))
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 2b729eea9c..0e1e491998 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -16,6 +16,7 @@ from fastapi import APIRouter, Body, Depends, HTTPException, Query
 from typing import List, Optional
 import structlog
 from loggers import get_logger
+from utils.utils import log_and_http_error
 
 import re as _re
 
@@ -825,10 +826,12 @@ async def list_local_models(
             models = models,
         )
     except Exception as e:
-        logger.error(f"Error listing local models: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500,
-            detail = f"Failed to list local models: {str(e)}",
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to list local models",
+            event = "models.list_local_models_failed",
+            log = logger,
         )
 
 
@@ -854,7 +857,10 @@ async def add_scan_folder_endpoint(
         folder = add_scan_folder(body.path)
     except ValueError as e:
         logger.warning("Scan folder rejected: %s (path=%s)", e, body.path)
-        raise HTTPException(status_code = 400, detail = str(e))
+        # Curated, path-free validation message (e.g. "Path does not exist"):
+        # forward the text, not the raw exception.
+        rejection_message = str(e)
+        raise HTTPException(status_code = 400, detail = rejection_message)
     logger.info("Scan folder added: %s", folder.get("path"))
     return folder
 
@@ -1182,12 +1188,15 @@ def _match_browse_child(current: Path, name: str) -> Optional[Path]:
     except PermissionError:
         raise HTTPException(
             status_code = 403,
-            detail = f"Permission denied reading {current}",
+            detail = f"Permission denied reading {current.name}",
         ) from None
     except OSError as exc:
+        logger.warning(
+            "browse-folders: could not read %s: %s", current, exc, exc_info = True
+        )
         raise HTTPException(
             status_code = 500,
-            detail = f"Could not read {current}: {exc}",
+            detail = f"Could not read {os.path.basename(str(current))}",
         ) from exc
     return None
 
@@ -1219,14 +1228,21 @@ def _resolve_browse_target(path: Optional[str], allowed_roots: list[Path]) -> Pa
             if child is None:
                 raise HTTPException(
                     status_code = 404,
-                    detail = f"Path does not exist: {requested_path}",
+                    detail = f"Path does not exist: {os.path.basename(requested_path)}",
                 )
             try:
                 resolved_child = child.resolve()
             except OSError as exc:
+                logger.warning(
+                    "browse-folders: invalid path component %r under %s: %s",
+                    part,
+                    current,
+                    exc,
+                    exc_info = True,
+                )
                 raise HTTPException(
                     status_code = 400,
-                    detail = f"Invalid path: {exc}",
+                    detail = "Invalid path",
                 ) from exc
             if not _is_path_inside_allowlist(resolved_child, resolved_roots):
                 raise HTTPException(
@@ -1242,7 +1258,7 @@ def _resolve_browse_target(path: Optional[str], allowed_roots: list[Path]) -> Pa
         if not current.is_dir():
             raise HTTPException(
                 status_code = 400,
-                detail = f"Not a directory: {current}",
+                detail = f"Not a directory: {os.path.basename(str(current))}",
             )
         return current
 
@@ -1325,12 +1341,15 @@ async def browse_folders(
     except PermissionError:
         raise HTTPException(
             status_code = 403,
-            detail = f"Permission denied reading {target}",
+            detail = f"Permission denied reading {os.path.basename(str(target))}",
         )
     except OSError as exc:
+        logger.warning(
+            "browse-folders: could not read %s: %s", target, exc, exc_info = True
+        )
         raise HTTPException(
             status_code = 500,
-            detail = f"Could not read {target}: {exc}",
+            detail = f"Could not read {os.path.basename(str(target))}",
         )
 
     try:
@@ -1533,8 +1552,13 @@ async def list_models(
         return ModelListResponse(models = all_models, default_models = default_models)
 
     except Exception as e:
-        logger.error(f"Error listing models: {e}", exc_info = True)
-        raise HTTPException(status_code = 500, detail = f"Failed to list models: {str(e)}")
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to list models",
+            event = "models.list_models_failed",
+            log = logger,
+        )
 
 
 def _get_max_position_embeddings(config) -> Optional[int]:
@@ -1653,9 +1677,12 @@ async def get_model_config(
         )
 
     except Exception as e:
-        logger.error(f"Error getting model config: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to get model config: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to get model config",
+            event = "models.get_model_config_failed",
+            log = logger,
         )
 
 
@@ -1710,9 +1737,12 @@ async def scan_loras(
         return LoRAScanResponse(loras = lora_list, outputs_dir = resolved_outputs_dir)
 
     except Exception as e:
-        logger.error(f"Error scanning LoRAs: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to scan LoRA adapters: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to scan LoRA adapters",
+            event = "models.scan_loras_failed",
+            log = logger,
         )
 
 
@@ -2044,7 +2074,7 @@ async def delete_finetuned_model(
         )
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to delete fine-tuned model: {str(e)}",
+            detail = "Failed to delete fine-tuned model",
         )
 
 
@@ -2075,9 +2105,12 @@ async def get_lora_base_model(
     except HTTPException:
         raise
     except Exception as e:
-        logger.error(f"Error getting LoRA base model: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to get base model: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to get base model",
+            event = "models.get_lora_base_model_failed",
+            log = logger,
         )
 
 
@@ -2102,9 +2135,12 @@ async def check_vision_model(
         )
 
     except Exception as e:
-        logger.error(f"Error checking vision model: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to check vision model: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to check vision model",
+            event = "models.check_vision_model_failed",
+            log = logger,
         )
 
 
@@ -2132,9 +2168,12 @@ async def check_embedding_model(
         )
 
     except Exception as e:
-        logger.error(f"Error checking embedding model: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to check embedding model: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to check embedding model",
+            event = "models.check_embedding_model_failed",
+            log = logger,
         )
 
 
@@ -2247,7 +2286,7 @@ async def get_gguf_variants(
         logger.error(f"Error listing GGUF variants for '{repo_id}': {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to list GGUF variants: {str(e)}",
+            detail = "Failed to list GGUF variants",
         )
 
 
@@ -2722,7 +2761,7 @@ async def delete_cached_model(
         logger.error(f"Error deleting cached model {repo_id}: {e}", exc_info = True)
         raise HTTPException(
             status_code = 500,
-            detail = f"Failed to delete cached model: {str(e)}",
+            detail = "Failed to delete cached model",
         )
 
 
@@ -2763,8 +2802,10 @@ async def list_checkpoints(
             models = models,
         )
     except Exception as e:
-        logger.error(f"Error listing checkpoints: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500,
-            detail = f"Failed to list checkpoints: {str(e)}",
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to list checkpoints",
+            event = "models.list_checkpoints_failed",
+            log = logger,
         )
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index 5d4bd46e62..4eaa007750 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -40,6 +40,7 @@ from models.providers import (
     ProviderUpdate,
 )
 from storage import providers_db
+from utils.utils import safe_curated_detail, log_and_http_error
 
 logger = structlog.get_logger(__name__)
 
@@ -254,10 +255,15 @@ async def test_provider(
             models_count = len(models),
         )
     except Exception as exc:
-        logger.warning("Provider test failed for %s: %s", payload.provider_type, exc)
+        logger.error(
+            "providers.test_failed",
+            provider_type = payload.provider_type,
+            error = str(exc),
+            exc_info = True,
+        )
         return ProviderTestResult(
             success = False,
-            message = f"Connection failed: {exc}",
+            message = f"Connection failed: {safe_curated_detail(exc)}",
             models_count = None,
         )
     finally:
@@ -375,10 +381,12 @@ async def list_provider_models(
             for m in models
         ]
     except Exception as exc:
-        logger.error("Failed to list models from %s: %s", payload.provider_type, exc)
-        raise HTTPException(
-            status_code = 502,
-            detail = f"Failed to list models from {payload.provider_type}: {exc}",
+        raise log_and_http_error(
+            exc,
+            502,
+            f"Failed to list models from {payload.provider_type}.",
+            event = "providers.list_models_failed",
+            log = logger,
         )
     finally:
         await client.close()
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 275fbb678b..b6fbeeee7a 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -1,10 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 from pydantic import BaseModel, Field
 
 from auth.authentication import get_current_subject
+from loggers import get_logger
+from utils.utils import safe_error_detail, log_and_http_error
 from utils.upload_limits import (
     MAX_UPLOAD_LIMIT_MB,
     MIN_UPLOAD_LIMIT_MB,
@@ -17,6 +19,8 @@ from utils.upload_limits import (
 
 router = APIRouter()
 
+logger = get_logger(__name__)
+
 
 class UploadLimitPayload(BaseModel):
     max_upload_size_mb: int = Field(..., ge = MIN_UPLOAD_LIMIT_MB, le = MAX_UPLOAD_LIMIT_MB)
@@ -55,5 +59,11 @@ def update_upload_limit(
     try:
         limit_mb = set_upload_limit_mb(payload.max_upload_size_mb)
     except ValueError as exc:
-        raise HTTPException(status_code = 400, detail = str(exc)) from exc
+        raise log_and_http_error(
+            exc,
+            400,
+            safe_error_detail(exc, fallback = "Invalid upload limit."),
+            event = "settings.update_upload_limit_failed",
+            log = logger,
+        ) from exc
     return _upload_limit_response(limit_mb)
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 41a9e15562..5b4267b2ef 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -51,6 +51,8 @@ except ImportError:
 # Auth
 from auth.authentication import get_current_subject
 
+from utils.utils import log_and_http_error
+
 from models import (
     TrainingStartRequest,
     TrainingJobResponse,
@@ -171,7 +173,9 @@ async def start_training(
                     request.resume_from_checkpoint
                 )
             except ValueError as e:
-                raise HTTPException(status_code = 400, detail = str(e))
+                # Deliberate user-facing validation message.
+                validation_message = str(e)
+                raise HTTPException(status_code = 400, detail = validation_message)
 
             resume_run = get_resumable_run_by_output_dir(resume_output_dir)
             if not resume_run or not can_resume_run(resume_run):
@@ -319,12 +323,16 @@ async def start_training(
 
     except ValueError as e:
         logger.warning("Rejected training GPU selection: %s", e)
-        raise HTTPException(status_code = 400, detail = str(e))
+        # Deliberate user-facing GPU-selection validation message.
+        validation_message = str(e)
+        raise HTTPException(status_code = 400, detail = validation_message)
     except Exception as e:
-        logger.error(f"Error starting training: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500,
-            detail = f"Failed to start training: {str(e)}",
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to start training",
+            event = "training.start_failed",
+            log = logger,
         )
 
 
@@ -358,9 +366,12 @@ async def stop_training(
         )
 
     except Exception as e:
-        logger.error(f"Error stopping training: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to stop training: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to stop training",
+            event = "training.stop_failed",
+            log = logger,
         )
 
 
@@ -412,10 +423,12 @@ async def reset_training(
     except HTTPException:
         raise
     except Exception as e:
-        logger.error(f"Error resetting training: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500,
-            detail = f"Failed to reset training: {str(e)}",
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to reset training",
+            event = "training.reset_failed",
+            log = logger,
         )
 
 
@@ -505,9 +518,12 @@ async def get_training_status(
         )
 
     except Exception as e:
-        logger.error(f"Error getting training status: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to get training status: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to get training status",
+            event = "training.status_failed",
+            log = logger,
         )
 
 
@@ -545,9 +561,12 @@ async def get_training_metrics(
         )
 
     except Exception as e:
-        logger.error(f"Error getting training metrics: {e}", exc_info = True)
-        raise HTTPException(
-            status_code = 500, detail = f"Failed to get training metrics: {str(e)}"
+        raise log_and_http_error(
+            e,
+            500,
+            "Failed to get training metrics",
+            event = "training.metrics_failed",
+            log = logger,
         )
 
 
diff --git a/studio/backend/utils/utils.py b/studio/backend/utils/utils.py
index 4e61a5b969..e95ef08a7d 100644
--- a/studio/backend/utils/utils.py
+++ b/studio/backend/utils/utils.py
@@ -17,6 +17,67 @@ import tempfile
 logger = get_logger(__name__)
 
 
+# ── Client-safe error helpers ───────────────────────────────────
+# Never return raw exception text to clients (it can leak paths/internals);
+# log the full exception server-side and return a generic message.
+
+
+def safe_error_detail(
+    error: Exception, fallback: str = "An internal error occurred"
+) -> str:
+    """Map a caught exception to a generic, client-safe message.
+
+    Never includes raw ``str(error)`` (which can leak internal paths or stack
+    detail); known transient conditions get a friendlier hint. Always log the
+    real exception server-side (e.g. via ``log_and_http_error``) for diagnosis.
+    """
+    text = str(error).lower()
+    if (
+        isinstance(error, (ConnectionError, TimeoutError))
+        or "connection" in text
+        or "timed out" in text
+        or "timeout" in text
+    ):
+        return "Could not reach an upstream service. Please try again."
+    if "out of memory" in text or "cuda error" in text:
+        return "Ran out of memory. Try a smaller model or shorter input."
+    return fallback
+
+
+def safe_curated_detail(
+    error: Exception, fallback: str = "An internal error occurred"
+) -> str:
+    """Client-safe text for curated domain/validation exceptions meant for the user.
+
+    Keeps the message (paths stripped) instead of a generic fallback; use for known
+    exception types, keep ``safe_error_detail`` for generic ``Exception``.
+    """
+    from utils.native_path_leases import redact_native_paths
+
+    msg = redact_native_paths(str(error)).strip()
+    return msg or fallback
+
+
+def log_and_http_error(
+    error: Exception,
+    status_code: int,
+    public_message: str,
+    *,
+    event: str = "request_failed",
+    log = None,
+):
+    """Log ``error`` in full server-side and return an ``HTTPException`` whose
+    ``detail`` is only ``public_message`` -- never the raw exception text.
+
+    Usage:  raise log_and_http_error(e, 500, "Failed to start training")
+    """
+    from fastapi import HTTPException
+
+    # Works for both structlog and stdlib loggers; exc_info=error logs its traceback.
+    (log or logger).error(f"{event}: {error}", exc_info = error)
+    return HTTPException(status_code = status_code, detail = public_message)
+
+
 @contextmanager
 def without_hf_auth():
     """

From 3ce187da021b17ef8ca001f1abf20817f28f23e0 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 04:24:13 -0700
Subject: [PATCH 109/222] Formatting: ruff line-length 100, kwarg-spacing
 passes, drop blank after short local imports (#6079)

Raise ruff line-length to 100 and extend the local pre-commit format pipeline (def-signature magic-comma normalization, short multi-line assert collapse, kwarg '=' spacing, blank-line-after-short-import removal, adjacent string-literal / f-string+plain merge, redundant-pass pruning). Every transform re-checks the file AST and is dropped if it would differ; the whole-repo reformat is verified AST-identical per file and idempotent.
---
 .pre-commit-config.yaml                       |   3 +
 pyproject.toml                                |   1 +
 scripts/check_frontend_dep_removal.py         |  64 +-
 scripts/check_new_install_scripts.py          |  11 +-
 scripts/enforce_kwargs_spacing.py             | 499 +++++++++++-
 scripts/lint_workflow_triggers.py             |   8 +-
 scripts/lockfile_supply_chain_audit.py        |   9 +-
 scripts/notebook_to_python.py                 |  20 +-
 scripts/notebook_validator.py                 |  61 +-
 scripts/run_ruff_format.py                    |  16 +-
 scripts/scan_npm_packages.py                  |  49 +-
 scripts/scan_packages.py                      |  64 +-
 scripts/stamp_studio_release.py               |  10 +-
 scripts/verify_comment_only_diff.py           |   9 +-
 scripts/verify_import_hoist.py                |  76 +-
 studio/backend/auth/authentication.py         |  12 +-
 studio/backend/auth/storage.py                |  16 +-
 studio/backend/colab.py                       |  25 +-
 studio/backend/core/__init__.py               |   1 -
 studio/backend/core/_torchao_stub.py          |  14 +-
 .../backend/core/data_recipe/huggingface.py   |   4 +-
 .../backend/core/data_recipe/jobs/manager.py  |  47 +-
 studio/backend/core/data_recipe/jobs/parse.py |  38 +-
 .../backend/core/data_recipe/jobs/worker.py   |  23 +-
 studio/backend/core/data_recipe/jsonable.py   |   2 -
 .../data_recipe/local_callable_validators.py  |  50 +-
 studio/backend/core/data_recipe/service.py    |  39 +-
 studio/backend/core/export/export.py          |  53 +-
 studio/backend/core/export/orchestrator.py    |  23 +-
 studio/backend/core/export/worker.py          |  20 +-
 .../core/inference/anthropic_compat.py        |   7 +-
 studio/backend/core/inference/audio_codecs.py |  33 +-
 .../core/inference/chat_template_helpers.py   |   4 +-
 .../core/inference/external_provider.py       | 722 +++++-------------
 studio/backend/core/inference/inference.py    | 218 ++----
 studio/backend/core/inference/llama_cpp.py    | 492 +++---------
 .../core/inference/llama_server_args.py       |  32 +-
 studio/backend/core/inference/mcp_client.py   |  17 +-
 .../backend/core/inference/mlx_inference.py   |  19 +-
 studio/backend/core/inference/orchestrator.py |  60 +-
 studio/backend/core/inference/pricing.py      |  21 +-
 studio/backend/core/inference/providers.py    |   3 +-
 .../core/inference/safetensors_agentic.py     |  23 +-
 .../core/inference/tool_call_parser.py        |  10 +-
 studio/backend/core/inference/tools.py        | 144 +---
 studio/backend/core/inference/worker.py       |  54 +-
 studio/backend/core/tool_healing.py           |  10 +-
 studio/backend/core/training/trainer.py       | 530 +++++--------
 studio/backend/core/training/training.py      |  82 +-
 studio/backend/core/training/worker.py        | 210 ++---
 studio/backend/main.py                        |  69 +-
 studio/backend/models/auth.py                 |  12 +-
 studio/backend/models/data_recipe.py          |   4 +-
 studio/backend/models/inference.py            | 128 +---
 studio/backend/models/models.py               |  52 +-
 studio/backend/models/providers.py            |  16 +-
 studio/backend/models/responses.py            |  12 +-
 studio/backend/models/training.py             |  95 +--
 .../data_designer_github_repo_seed/scraper.py |  36 +-
 .../scraper_impl/gh_client.py                 |  35 +-
 .../scraper_impl/scraper.py                   |  87 +--
 .../scraper_impl/state_store.py               |   6 +-
 .../chunking.py                               |  47 +-
 studio/backend/routes/auth.py                 |  28 +-
 studio/backend/routes/chat_history.py         |  52 +-
 studio/backend/routes/data_recipe/jobs.py     |  37 +-
 studio/backend/routes/data_recipe/mcp.py      |   4 +-
 studio/backend/routes/data_recipe/seed.py     |  51 +-
 studio/backend/routes/data_recipe/validate.py |  19 +-
 studio/backend/routes/datasets.py             |  47 +-
 studio/backend/routes/export.py               |  36 +-
 studio/backend/routes/inference.py            | 379 +++------
 studio/backend/routes/mcp_servers.py          |  37 +-
 studio/backend/routes/models.py               | 141 +---
 studio/backend/routes/providers.py            |  41 +-
 studio/backend/routes/settings.py             |   7 +-
 studio/backend/routes/training.py             | 152 +---
 studio/backend/routes/training_history.py     |  19 +-
 studio/backend/run.py                         |  48 +-
 studio/backend/state/tool_policy.py           |   4 +-
 studio/backend/storage/mcp_servers_db.py      |   8 +-
 studio/backend/storage/providers_db.py        |  11 +-
 studio/backend/storage/studio_db.py           |  72 +-
 .../tests/test_amd_apu_unified_memory.py      |   7 +-
 .../tests/test_anthropic_citations_edge.py    |   8 +-
 .../tests/test_anthropic_code_execution.py    |  18 +-
 .../tests/test_anthropic_compaction.py        |  45 +-
 .../test_anthropic_fast_mode_and_refusal.py   |   6 +-
 .../tests/test_anthropic_fast_mode_edge.py    |  19 +-
 .../backend/tests/test_anthropic_messages.py  |  61 +-
 .../tests/test_anthropic_tool_versions.py     |   5 +-
 .../backend/tests/test_anthropic_web_fetch.py |  19 +-
 .../tests/test_audio_token_detection.py       |   4 +-
 .../backend/tests/test_cached_gguf_routes.py  |  31 +-
 .../backend/tests/test_chat_history_routes.py |   8 +-
 .../tests/test_chat_history_storage.py        |  40 +-
 .../test_cleanup_cancelled_checkpoints.py     |   1 -
 studio/backend/tests/test_cpu_threads.py      |   4 +-
 .../tests/test_dataset_upload_limits.py       |   8 +-
 studio/backend/tests/test_desktop_auth.py     |  44 +-
 .../backend/tests/test_detect_mmproj_file.py  |   9 +-
 .../backend/tests/test_export_log_cursor.py   |   7 +-
 .../test_external_provider_usage_chunk.py     |  14 +-
 .../backend/tests/test_frontend_resolution.py |   8 +-
 studio/backend/tests/test_gemini_provider.py  | 349 +++------
 .../tests/test_gguf_completion_usage.py       |   8 +-
 studio/backend/tests/test_gguf_metadata.py    |  20 +-
 studio/backend/tests/test_gpu_selection.py    |  83 +-
 .../tests/test_gpu_selection_sandbox.py       |  22 +-
 studio/backend/tests/test_host_defaults.py    |  13 +-
 .../tests/test_index_bootstrap_origin.py      |  24 +-
 .../test_index_bootstrap_origin_extra.py      |  15 +-
 .../tests/test_inference_model_validation.py  |   5 +-
 .../backend/tests/test_kv_cache_estimation.py | 121 +--
 .../test_lemonade_llamacpp_rocm_bins_mock.py  |  24 +-
 .../tests/test_llama_cpp_context_fit.py       |  10 +-
 .../backend/tests/test_llama_cpp_freshness.py |  44 +-
 .../tests/test_llama_cpp_load_progress.py     |   4 -
 .../test_llama_cpp_load_progress_live.py      |   6 +-
 .../test_llama_cpp_max_context_threshold.py   |   7 +-
 .../tests/test_llama_cpp_mtp_detection.py     |  41 +-
 ..._llama_cpp_start_failure_classification.py |   7 +-
 .../test_llama_cpp_wait_for_vram_settle.py    |   8 +-
 .../test_llama_cpp_windows_nvidia_path.py     |   8 +-
 .../backend/tests/test_llama_server_args.py   |  29 +-
 studio/backend/tests/test_login_rate_limit.py |  36 +-
 studio/backend/tests/test_mcp_servers.py      |  39 +-
 .../tests/test_mcp_stdio_improvements.py      |  26 +-
 studio/backend/tests/test_mcp_stdio_pr5863.py |  37 +-
 studio/backend/tests/test_middleware.py       |  13 +-
 .../tests/test_mlx_inference_backend.py       |  11 +-
 .../tests/test_mlx_training_worker_config.py  |   8 +-
 ...models_get_model_config_case_resolution.py |   4 +-
 .../backend/tests/test_multimodal_document.py |  19 +-
 .../tests/test_native_context_length.py       |  16 +-
 .../tests/test_offline_gguf_cache_fallback.py |  79 +-
 .../tests/test_offline_inference_parent.py    |  21 +-
 .../test_openai_citation_markers_edge.py      |   4 +-
 .../tests/test_openai_code_execution.py       |  15 +-
 .../tests/test_openai_container_crud.py       |   9 +-
 .../test_openai_responses_translation.py      |  11 +-
 .../tests/test_openai_tool_passthrough.py     |  68 +-
 studio/backend/tests/test_pricing.py          |  22 +-
 studio/backend/tests/test_pricing_edge.py     |  14 +-
 studio/backend/tests/test_providers_api.py    |  52 +-
 studio/backend/tests/test_responses_api.py    |   5 +-
 .../tests/test_responses_tool_passthrough.py  |  16 +-
 studio/backend/tests/test_rocm_oom_guard.py   |   4 +-
 .../test_safetensors_capability_advertise.py  |   6 +-
 .../tests/test_safetensors_tool_loop.py       | 155 ++--
 studio/backend/tests/test_sandbox_tools.py    |  12 +-
 studio/backend/tests/test_studio_api.py       |  51 +-
 studio/backend/tests/test_tool_xml_strip.py   |   4 +-
 .../backend/tests/test_trained_model_scan.py  |  20 +-
 .../tests/test_training_raw_support.py        |   5 +-
 .../tests/test_training_worker_flash_attn.py  | 239 ++----
 .../tests/test_transformers_version.py        |   4 +-
 studio/backend/tests/test_utils.py            |  15 +-
 studio/backend/tests/test_vision_cache.py     |   4 +-
 studio/backend/tests/test_vram_estimation.py  |  87 +--
 .../tests/test_windows_gpu_detection_mock.py  |  44 +-
 studio/backend/utils/cache_cleanup.py         |   3 +-
 .../backend/utils/datasets/data_collators.py  |  16 +-
 .../utils/datasets/dataset_none_detect.py     |  83 +-
 .../backend/utils/datasets/dataset_utils.py   |  68 +-
 .../utils/datasets/format_conversion.py       |  71 +-
 .../utils/datasets/format_detection.py        |  43 +-
 studio/backend/utils/datasets/llm_assist.py   |  50 +-
 studio/backend/utils/datasets/raw_text.py     |   8 +-
 .../backend/utils/datasets/vlm_processing.py  |   5 +-
 studio/backend/utils/downsample.py            |   4 +-
 studio/backend/utils/hardware/amd.py          |  30 +-
 studio/backend/utils/hardware/hardware.py     | 114 +--
 studio/backend/utils/hardware/nvidia.py       |  32 +-
 .../backend/utils/hardware/vram_estimation.py | 151 +---
 .../utils/inference/inference_config.py       |   5 +-
 studio/backend/utils/llama_cpp_freshness.py   |   5 +-
 studio/backend/utils/models/checkpoints.py    |   8 +-
 studio/backend/utils/models/gguf_metadata.py  |   3 +-
 studio/backend/utils/models/model_config.py   | 119 +--
 studio/backend/utils/native_path_leases.py    |  38 +-
 studio/backend/utils/paths/path_utils.py      |   1 -
 studio/backend/utils/paths/storage_roots.py   |  15 +-
 studio/backend/utils/studio_version.py        |   4 +-
 studio/backend/utils/transformers_version.py  |  27 +-
 studio/backend/utils/update_status.py         |  25 +-
 studio/backend/utils/upload_limits.py         |   1 -
 studio/backend/utils/utils.py                 |   8 +-
 studio/backend/utils/wheel_utils.py           |   4 +-
 studio/install_llama_prebuilt.py              | 633 ++++-----------
 studio/install_python_stack.py                |  61 +-
 tests/_zoo_aggressive_cuda_spoof.py           |   6 +-
 tests/conftest.py                             |   2 -
 tests/python/conftest.py                      |   8 +-
 tests/python/test_cross_platform_parity.py    |  10 +-
 .../test_dpo_vision_processor_passthrough.py  |  13 +-
 tests/python/test_e2e_no_torch_sandbox.py     |  61 +-
 ...sentence_transformer_redirect_lifecycle.py |  18 +-
 .../test_flash_attn_install_python_stack.py   | 108 ++-
 tests/python/test_gpu_init_ldconfig_guard.py  |   4 +-
 tests/python/test_no_torch_filtering.py       |  85 +--
 .../test_orpo_processor_text_tokenizer.py     |  13 +-
 tests/python/test_studio_import_no_torch.py   |  35 +-
 .../test_tokenizers_and_torch_constraint.py   |  40 +-
 .../test_unsloth_run_tool_policy_resolver.py  |   8 +-
 tests/qlora/test_hf_qlora_train_and_merge.py  |   4 +-
 .../saving/gpt-oss-merge/test_merged_model.py |   8 +-
 tests/saving/gpt-oss-merge/train_and_merge.py |  12 +-
 .../test_merge_4bit_validation.py             |   8 +-
 .../test_merge_model_perplexity_llama-3.2.py  |  26 +-
 .../test_merge_model_perplexity_mistral.py    |  28 +-
 .../test_merge_model_perplexity_phi_4.py      |  26 +-
 ...st_merged_model_perplexity_llama-3.1-8b.py |  26 +-
 .../test_merged_model_perplexity_qwen_2.5.py  |  18 +-
 .../test_push_to_hub_merged.py                |   8 +-
 ...t_push_to_hub_merged_sharded_index_file.py |   8 +-
 .../test_save_merged_grpo_model.py            |  41 +-
 .../test_fix_sentencepiece_gguf_robustness.py |   9 +-
 .../test_preserve_tokenizer_eos_token.py      |   7 +-
 tests/saving/test_save_shell_injection.py     |   9 +-
 tests/saving/test_unsloth_save.py             |  64 +-
 .../saving/text_to_speech_models/test_csm.py  |   4 +-
 .../saving/text_to_speech_models/test_lasa.py |   4 +-
 .../text_to_speech_models/test_orpheus.py     |   8 +-
 .../text_to_speech_models/test_whisper.py     |   8 +-
 .../test_index_file_sharded_model.py          |   4 +-
 .../vision_models/test_push_to_hub_merged.py  |   4 +-
 ..._merge_qwen2.5vl32B_model_ocr_benchmark.py |   4 +-
 ...t_save_merge_vision_model_ocr_benchmark.py |   4 +-
 .../test_lockfile_supply_chain_audit.py       |   5 +-
 tests/security/test_new_install_scripts.py    |  20 +-
 tests/security/test_scan_npm_packages.py      |  10 +-
 tests/security/test_scan_packages.py          |   7 +-
 tests/studio/_playwright_robust.py            |   8 +-
 .../install/smoke_test_llama_prebuilt.py      |  12 +-
 .../smoke_test_parallel_studio_home.py        |  41 +-
 .../test_install_llama_prebuilt_logic.py      | 178 ++---
 .../install/test_llama_pr_force_and_source.py |  40 +-
 .../install/test_macos_version_compat.py      |  28 +-
 tests/studio/install/test_pr4562_bugfixes.py  | 114 +--
 tests/studio/install/test_rocm_support.py     | 164 +---
 tests/studio/install/test_selection_logic.py  | 257 ++-----
 tests/studio/load_freeze/llama_server_shim.py |  14 +-
 .../load_freeze/test_load_orchestrator.py     |  28 +-
 tests/studio/playwright_chat_ime_i18n.py      |  18 +-
 tests/studio/playwright_chat_ui.py            |  70 +-
 tests/studio/playwright_extra_ui.py           |  36 +-
 tests/studio/run_real_mlx_smoke.py            |  36 +-
 tests/studio/studio_api_smoke.py              |   4 +-
 tests/studio/test_auth_form_input_count.py    |   5 +-
 tests/studio/test_cancel_atomicity.py         |  16 +-
 tests/studio/test_cancel_id_wiring.py         |  19 +-
 .../test_chat_preset_builtin_invariants.py    |   7 +-
 tests/studio/test_cli_repo_variant.py         |   8 +-
 tests/studio/test_cli_run_alias.py            |   8 +-
 tests/studio/test_cli_studio_defaults.py      |   8 +-
 .../test_composer_rtl_bidi_attribute.py       |  27 +-
 .../test_export_output_path_contract.py       |   8 +-
 tests/studio/test_frontend_dep_removal.py     |  63 +-
 tests/studio/test_hardware_dispatch_matrix.py |  29 +-
 tests/studio/test_is_mlx_dispatch_gate.py     |  10 +-
 .../test_stream_cancel_registration_timing.py |  22 +-
 .../test_studio_gguf_export_script_pin.py     |  28 +-
 .../test_studio_text_descender_clipping.py    |  20 +-
 tests/test_callback_signature_drift.py        |   6 +-
 tests/test_enforce_kwargs_spacing.py          | 428 +++++++++++
 tests/test_finetune_last_n_layers.py          |   2 -
 tests/test_gemma4_chat_template.py            |   4 +-
 tests/test_get_model_name.py                  |   8 +-
 tests/test_import_fixes_drift.py              |  23 +-
 tests/test_loader_glob_skip.py                |  16 +-
 tests/test_model_registry.py                  |   7 +-
 tests/test_multi_image_grpo_chunking.py       |  16 +-
 tests/test_peft_weight_converter_compat.py    |  26 +-
 tests/test_raw_text.py                        |  39 +-
 tests/test_resolve_model_class.py             |   7 +-
 tests/test_studio_install_workspace_guard.py  |  80 +-
 tests/test_studio_root_resilience.py          |  20 +-
 tests/test_tool_mask_zoo_compat.py            |  19 +-
 tests/utils/aime_eval.py                      |  36 +-
 tests/utils/cleanup_utils.py                  |  14 +-
 tests/utils/data_utils.py                     |  20 +-
 tests/utils/generate_dataset_with_none.py     |   8 +-
 tests/utils/hf_utils.py                       |  30 +-
 tests/utils/ocr_eval.py                       |  45 +-
 tests/utils/os_utils.py                       |  18 +-
 tests/utils/perplexity_eval.py                |  12 +-
 tests/utils/run_none_detect_tests.py          |  54 +-
 tests/utils/test_attention_masks.py           |  41 +-
 tests/utils/test_packing.py                   |  45 +-
 tests/utils/test_q_galore.py                  |  24 +-
 tests/utils/test_qat.py                       |   5 +-
 tests/utils/test_trunc_normal_patch.py        |   4 +-
 tests/version_compat/_fetch.py                |   6 +-
 .../test_bitsandbytes_pinned_symbols.py       |  45 +-
 .../test_peft_pinned_symbols.py               |  16 +-
 ...st_sentence_transformers_pinned_symbols.py |  16 +-
 .../test_transformers_pinned_symbols.py       |  32 +-
 .../test_trl_grpo_pinned_symbols.py           |  20 +-
 ..._unsloth_zoo_save_merged_pinned_symbols.py |  12 +-
 .../test_extended_module_imports.py           |  18 +-
 tests/vllm_compat/test_vllm_pinned_symbols.py |  33 +-
 unsloth-cli.py                                |  22 +-
 unsloth/__init__.py                           |   6 +-
 unsloth/_gpu_init.py                          |   8 +-
 unsloth/dataprep/raw_text.py                  |  94 ++-
 unsloth/dataprep/synthetic.py                 |  17 +-
 unsloth/device_type.py                        |  14 +-
 unsloth/import_fixes.py                       | 170 ++---
 unsloth/kernels/__init__.py                   |   4 +-
 unsloth/kernels/cross_entropy_loss.py         |  15 +-
 unsloth/kernels/fast_lora.py                  |  31 +-
 unsloth/kernels/flex_attention.py             |   9 +-
 unsloth/kernels/fp8.py                        |  77 +-
 unsloth/kernels/geglu.py                      |  48 +-
 unsloth/kernels/layernorm.py                  |  12 +-
 unsloth/kernels/moe/autotune_cache.py         |  16 +-
 .../moe/benchmark/benchmark_fused_moe.py      |  42 +-
 unsloth/kernels/moe/benchmark/utils.py        |  31 +-
 unsloth/kernels/moe/grouped_gemm/interface.py |  85 +--
 .../moe/grouped_gemm/kernels/autotuning.py    |  14 +-
 .../moe/grouped_gemm/kernels/backward.py      |  32 +-
 .../moe/grouped_gemm/kernels/forward.py       |  21 +-
 .../moe/grouped_gemm/kernels/tuning.py        |  18 +-
 .../reference/layers/llama4_moe.py            |  46 +-
 .../reference/layers/qwen3_moe.py             |  33 +-
 .../moe/grouped_gemm/reference/moe_block.py   |  15 +-
 .../moe/grouped_gemm/reference/moe_ops.py     |  23 +-
 unsloth/kernels/moe/tests/common.py           |  78 +-
 unsloth/kernels/moe/tests/moe_utils.py        |  92 +--
 .../kernels/moe/tests/test_grouped_gemm.py    | 117 +--
 unsloth/kernels/moe/tests/test_llama4_moe.py  |  47 +-
 unsloth/kernels/moe/tests/test_qwen3_moe.py   |  55 +-
 unsloth/kernels/rms_layernorm.py              |  25 +-
 unsloth/kernels/rope_embedding.py             |  44 +-
 unsloth/kernels/swiglu.py                     |  26 +-
 unsloth/kernels/utils.py                      |  94 ++-
 unsloth/models/_utils.py                      | 326 +++-----
 unsloth/models/cohere.py                      |  74 +-
 unsloth/models/falcon_h1.py                   |  77 +-
 unsloth/models/gemma.py                       |  73 +-
 unsloth/models/gemma2.py                      |  76 +-
 unsloth/models/glm4_moe.py                    |  30 +-
 unsloth/models/granite.py                     |  83 +-
 unsloth/models/llama.py                       | 407 ++++------
 unsloth/models/loader.py                      | 100 +--
 unsloth/models/loader_utils.py                |  33 +-
 unsloth/models/mistral.py                     |  50 +-
 unsloth/models/qwen2.py                       |   8 +-
 unsloth/models/qwen3.py                       |  48 +-
 unsloth/models/qwen3_moe.py                   |  35 +-
 unsloth/models/rl.py                          | 180 ++---
 unsloth/models/rl_replacements.py             | 259 +++----
 unsloth/models/sentence_transformer.py        | 272 ++-----
 unsloth/models/vision.py                      | 130 +---
 unsloth/optimizers/q_galore_adamw.py          |  16 +-
 unsloth/optimizers/q_galore_projector.py      |  17 +-
 unsloth/registry/__init__.py                  |  20 +-
 unsloth/registry/_deepseek.py                 |  28 +-
 unsloth/registry/_gemma.py                    |   4 +-
 unsloth/registry/_llama.py                    |  16 +-
 unsloth/registry/_mistral.py                  |  16 +-
 unsloth/registry/_phi.py                      |   4 +-
 unsloth/registry/_qwen.py                     |  16 +-
 unsloth/registry/registry.py                  |  24 +-
 unsloth/save.py                               | 285 ++-----
 unsloth/tokenizer_utils.py                    | 129 +---
 unsloth/trainer.py                            |  55 +-
 unsloth/utils/attention_dispatch.py           |  55 +-
 unsloth/utils/packing.py                      |  40 +-
 unsloth_cli/commands/export.py                |   4 +-
 unsloth_cli/commands/studio.py                |  76 +-
 unsloth_cli/commands/train.py                 |  12 +-
 unsloth_cli/config.py                         |   5 +-
 unsloth_cli/options.py                        |   4 +-
 .../tests/test_studio_run_parallel_flag.py    |  40 +-
 .../test_studio_run_short_alias_clashes.py    |  46 +-
 377 files changed, 5945 insertions(+), 11859 deletions(-)
 create mode 100644 tests/test_enforce_kwargs_spacing.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 8cfa7f998b..e018803a5f 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -14,5 +14,8 @@ repos:
         entry: scripts/run_ruff_format.py
         language: python
         types: [python]
+        # Mirror ruff's [tool.ruff] extend-exclude so this hook does not
+        # half-process files ruff itself skips (which produced churn).
+        exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$'
         additional_dependencies:
           - ruff==0.6.9
diff --git a/pyproject.toml b/pyproject.toml
index 24fd66dbbb..713146ff32 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1308,6 +1308,7 @@ repository = "https://github.com/unslothai/unsloth"
 
 [tool.ruff]
 target-version = "py311"
+line-length = 100
 force-exclude = true
 extend-exclude = [
     "*chat_templates.py",
diff --git a/scripts/check_frontend_dep_removal.py b/scripts/check_frontend_dep_removal.py
index 260ad5215a..3ec4e9037f 100644
--- a/scripts/check_frontend_dep_removal.py
+++ b/scripts/check_frontend_dep_removal.py
@@ -52,9 +52,7 @@ EXPECTED_NOISE_FILES = {
 }
 
 # Only quoted-string occurrences in these file types can be module specifiers.
-JS_LIKE_EXT = re.compile(
-    r"\.(ts|tsx|js|jsx|mjs|cjs|html|htm|css|scss|sass|json|jsonc)$"
-)
+JS_LIKE_EXT = re.compile(r"\.(ts|tsx|js|jsx|mjs|cjs|html|htm|css|scss|sass|json|jsonc)$")
 # Files where JS-syntactic import patterns (static/dynamic/require/re-export)
 # could be a real module reference. Markdown gets a separate gate (.mdx is
 # real ESM; .md code fences are not).
@@ -273,9 +271,7 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     if is_script and re.search(rf"\bimport\(\s*['\"]{esc}{sub}['\"]\s*\)", content):
         return "dynamic_import"
     # require / require.resolve
-    if is_script and re.search(
-        rf"\brequire(?:\.resolve)?\(\s*['\"]{esc}{sub}['\"]\s*\)", content
-    ):
+    if is_script and re.search(rf"\brequire(?:\.resolve)?\(\s*['\"]{esc}{sub}['\"]\s*\)", content):
         return "require"
     # Re-exports: `export * from "pkg"`, `export { x } from "pkg"`,
     # `export type { Foo } from "pkg"`. Multi-line supported.
@@ -289,16 +285,12 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     # segment bounded by a quote / `#` / `?` or a subpath `/`, so
     # `/node_modules/foo-extra/...` is NOT treated as usage of `foo`.
     html_pkg = rf"{esc}(?:/[^'\"#?]*)?(?=['\"#?])"
-    if is_html and re.search(
-        rf"<script[^>]*src\s*=\s*['\"][^'\"]*/{html_pkg}", content
-    ):
+    if is_html and re.search(rf"<script[^>]*src\s*=\s*['\"][^'\"]*/{html_pkg}", content):
         return "html_script"
     if is_html and re.search(rf"<link[^>]*href\s*=\s*['\"][^'\"]*/{html_pkg}", content):
         return "html_link"
     # TypeScript triple-slash
-    if is_ts and re.search(
-        rf"///\s*<reference\s+types\s*=\s*['\"]{esc}{sub}['\"]", content
-    ):
+    if is_ts and re.search(rf"///\s*<reference\s+types\s*=\s*['\"]{esc}{sub}['\"]", content):
         return "tsc_triple_slash"
     # new URL("pkg/...", import.meta.url)
     if is_script and re.search(rf"\bnew\s+URL\(\s*['\"]{esc}{sub}['\"]", content):
@@ -544,19 +536,13 @@ def _next_real_bin(words: list[str], idx: int) -> str | None:
         if first in {"npx", "pnpx", "bunx"} and idx + 1 < len(words):
             idx += 1
             continue
-        if (
-            first in {"pnpm", "yarn"}
-            and idx + 2 < len(words)
-            and words[idx + 1] in {"exec", "dlx"}
-        ):
+        if first in {"pnpm", "yarn"} and idx + 2 < len(words) and words[idx + 1] in {"exec", "dlx"}:
             idx += 2
             continue
 
         # 3. Wrapper bin (cross-env, dotenv, etc.). Skip the wrapper's
         # own flags and any subsequent env-prefix tokens, then re-loop.
-        bin_token = first.removeprefix("./node_modules/.bin/").removeprefix(
-            "node_modules/.bin/"
-        )
+        bin_token = first.removeprefix("./node_modules/.bin/").removeprefix("node_modules/.bin/")
         if bin_token in _SCRIPT_WRAPPERS and bin_token not in seen_wrappers:
             seen_wrappers.add(bin_token)
             idx += 1
@@ -585,9 +571,7 @@ def _next_real_bin(words: list[str], idx: int) -> str | None:
     return None
 
 
-def scripts_bin_refs(
-    head_pkg: dict, bin_to_pkg: dict[str, str]
-) -> dict[str, list[str]]:
+def scripts_bin_refs(head_pkg: dict, bin_to_pkg: dict[str, str]) -> dict[str, list[str]]:
     """Return `{package_name: ['scripts.X: cmd', ...]}` listing every
     package referenced via its bin name in package.json scripts.
 
@@ -652,11 +636,7 @@ def tsconfig_compiler_types_refs() -> set[str]:
             if not isinstance(t, str):
                 continue
             # `vite/client` resolves to `vite` package.
-            pkg = (
-                t.split("/", 1)[0]
-                if not t.startswith("@")
-                else "/".join(t.split("/", 2)[:2])
-            )
+            pkg = t.split("/", 1)[0] if not t.startswith("@") else "/".join(t.split("/", 2)[:2])
             out.add(pkg)
     return out
 
@@ -820,9 +800,7 @@ _file_lines_cache: dict[str, list[str]] = {}
 def _read_file(path: str) -> list[str]:
     if path not in _file_lines_cache:
         try:
-            _file_lines_cache[path] = (
-                Path(path).read_text(errors = "replace").splitlines()
-            )
+            _file_lines_cache[path] = Path(path).read_text(errors = "replace").splitlines()
         except (OSError, UnicodeDecodeError):
             _file_lines_cache[path] = []
     return _file_lines_cache[path]
@@ -952,18 +930,14 @@ def find_types_runtime_usage(pkg: str, tsc_types: set[str]) -> list[Hit]:
 
 
 def main() -> int:
-    p = argparse.ArgumentParser(
-        description = __doc__, formatter_class = argparse.RawTextHelpFormatter
-    )
+    p = argparse.ArgumentParser(description = __doc__, formatter_class = argparse.RawTextHelpFormatter)
     p.add_argument(
         "--base",
         default = "origin/main",
         help = "git ref to diff against (default: origin/main). "
         "Examples: HEAD~1, main, a-tag, a-sha.",
     )
-    p.add_argument(
-        "--base-pkg", help = "optional override: read base package.json from this path"
-    )
+    p.add_argument("--base-pkg", help = "optional override: read base package.json from this path")
     p.add_argument(
         "--base-lock",
         help = "optional override: read base package-lock.json from this path. "
@@ -1057,9 +1031,7 @@ def main() -> int:
                 print(f"  - {w}")
             print()
         if missing_imports:
-            print(
-                f"Imports without a matching package.json dep ({len(missing_imports)}):"
-            )
+            print(f"Imports without a matching package.json dep ({len(missing_imports)}):")
             for file, ln, spec in missing_imports[:20]:
                 print(f"  - {file}:{ln}  imports '{spec}'")
             print()
@@ -1097,9 +1069,7 @@ def main() -> int:
             return 1
         return 0
 
-    print(
-        f"Checking {len(removed)} removed package(s) from studio/frontend/package.json"
-    )
+    print(f"Checking {len(removed)} removed package(s) from studio/frontend/package.json")
     print(f"Base: {args.base}    Head: working tree")
     print()
 
@@ -1127,9 +1097,7 @@ def main() -> int:
         top = f"node_modules/{name}"
         top_path = top if top in reachable_paths else None
         nested = sorted(
-            p
-            for p in reachable_paths
-            if p != top and p.endswith(f"/node_modules/{name}")
+            p for p in reachable_paths if p != top and p.endswith(f"/node_modules/{name}")
         )
         return top_path, nested
 
@@ -1177,9 +1145,7 @@ def main() -> int:
     _print_hygiene()
 
     if failures:
-        print(
-            f"FAIL: {len(failures)} removed package(s) still referenced and not resolvable"
-        )
+        print(f"FAIL: {len(failures)} removed package(s) still referenced and not resolvable")
         for name, _ in failures:
             print(f"  - {name}")
         return 1
diff --git a/scripts/check_new_install_scripts.py b/scripts/check_new_install_scripts.py
index af3c84f96d..2beaada0bf 100644
--- a/scripts/check_new_install_scripts.py
+++ b/scripts/check_new_install_scripts.py
@@ -53,9 +53,7 @@ HIGH = "HIGH"
 class Finding:
     __slots__ = ("severity", "name", "version", "kind", "detail")
 
-    def __init__(
-        self, severity: str, name: str, version: str, kind: str, detail: str
-    ) -> None:
+    def __init__(self, severity: str, name: str, version: str, kind: str, detail: str) -> None:
         self.severity = severity
         self.name = name
         self.version = version
@@ -206,9 +204,7 @@ def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
             continue  # pre-existing install-script dep; not in scope
         name = head[key]
         # key is "name@version"; rsplit("@", 1) handles scoped names.
-        version = (
-            key[len(name) + 1 :] if key.startswith(name + "@") else "<unversioned>"
-        )
+        version = key[len(name) + 1 :] if key.startswith(name + "@") else "<unversioned>"
         scripts = _fetch_registry_scripts(name, version)
         if scripts:
             detail = "; ".join(f"{h}={cmd!r}" for h, cmd in scripts.items())
@@ -238,8 +234,7 @@ def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         description = (
-            "Diff two package-lock.json files and refuse any newly-"
-            "added install-script dep."
+            "Diff two package-lock.json files and refuse any newly-added install-script dep."
         ),
     )
     parser.add_argument(
diff --git a/scripts/enforce_kwargs_spacing.py b/scripts/enforce_kwargs_spacing.py
index 6b36231610..fdef950d7f 100755
--- a/scripts/enforce_kwargs_spacing.py
+++ b/scripts/enforce_kwargs_spacing.py
@@ -1,5 +1,10 @@
 #!/usr/bin/env python3
-"""Ensure keyword arguments use spaces around '=', prune redundant pass statements."""
+"""Ensure keyword arguments use spaces around '=', prune redundant pass statements,
+drop the blank line after a short indented import block, merge adjacent same-line
+string literals, normalize def-signature magic commas (pre-ruff) so a def with
+>= 3 params and a default goes one-per-line while everything else stays
+collapsible, and collapse a short multi-line assert onto one line (pre-ruff) by
+stripping the magic trailing comma that holds it open."""
 
 from __future__ import annotations
 
@@ -123,9 +128,7 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
     lines = text.splitlines(keepends=True)
     changed = False
 
-    for node in sorted(
-        redundant, key=lambda item: (item.lineno, item.col_offset), reverse=True
-    ):
+    for node in sorted(redundant, key=lambda item: (item.lineno, item.col_offset), reverse=True):
         start = node.lineno - 1
         end = (node.end_lineno or node.lineno) - 1
         if start >= len(lines):
@@ -160,7 +163,470 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
     return "".join(result_lines), changed
 
 
-def process_file(path: Path) -> bool:
+def remove_blank_after_short_import(text: str) -> tuple[str, bool]:
+    """Drop blank line(s) after an import block in a *small* nested suite.
+
+    Inside an indented suite of <= 3 statements (function/try/if/with/etc., never
+    module level), when a run of consecutive ``import`` / ``from ... import``
+    statements is directly followed -- across one or more blank lines and nothing
+    else -- by another statement in the same suite, remove those blank lines so
+    the import sits next to the code that uses it. A comment in the gap blocks the
+    rule. Removing blank lines never changes the AST, so this is always
+    semantics-preserving.
+    """
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return text, False
+
+    lines = text.splitlines(keepends=True)
+    import_types = (ast.Import, ast.ImportFrom)
+    drop: set[int] = set()  # 1-based physical line numbers to delete
+
+    def suites_of(node: ast.AST) -> list[list[ast.stmt]]:
+        if isinstance(node, ast.Module):
+            return []  # module-level import spacing is left alone
+        out: list[list[ast.stmt]] = []
+        for attr in ("body", "orelse", "finalbody"):
+            val = getattr(node, attr, None)
+            if isinstance(val, list) and val and all(isinstance(s, ast.stmt) for s in val):
+                out.append(val)
+        return out
+
+    for node in ast.walk(tree):
+        for suite in suites_of(node):
+            if len(suite) > 3:  # only small blocks
+                continue
+            i = 0
+            while i < len(suite):
+                if not isinstance(suite[i], import_types):
+                    i += 1
+                    continue
+                j = i
+                while j + 1 < len(suite) and isinstance(suite[j + 1], import_types):
+                    j += 1
+                if j + 1 < len(suite):  # an import block followed by another statement
+                    last_imp, nxt = suite[j], suite[j + 1]
+                    gap = range((last_imp.end_lineno or last_imp.lineno) + 1, nxt.lineno)
+                    nums = [n for n in gap if 1 <= n <= len(lines)]
+                    if nums and all(lines[n - 1].strip() == "" for n in nums):
+                        drop.update(nums)
+                i = j + 1
+
+    if not drop:
+        return text, False
+    kept = [ln for idx, ln in enumerate(lines, start=1) if idx not in drop]
+    return "".join(kept), True
+
+
+_STRING_TRIVIA = (tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT, tokenize.INDENT, tokenize.DEDENT)
+
+
+_DEF_MIN_PARAMS_FOR_MULTILINE = 3  # signatures with < this many params stay one line
+
+
+def _def_specs_by_line(tree: ast.AST) -> dict[int, tuple[int, bool]]:
+    """Map the line of each def keyword to (param count, has-any-default).
+
+    One def per line, so the line is a stable key. ``*`` / ``/`` markers are not
+    parameters and are not counted. A default exists if any positional default
+    is present or any keyword-only default is not ``None`` (a ``None`` entry in
+    ``kw_defaults`` means a required keyword-only arg).
+    """
+    out: dict[int, tuple[int, bool]] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            a = node.args
+            count = (
+                len(a.posonlyargs)
+                + len(a.args)
+                + len(a.kwonlyargs)
+                + (1 if a.vararg else 0)
+                + (1 if a.kwarg else 0)
+            )
+            has_default = bool(a.defaults) or any(d is not None for d in a.kw_defaults)
+            out[node.lineno] = (count, has_default)
+    return out
+
+
+def normalize_def_trailing_comma(text: str) -> tuple[str, bool]:
+    """Force a def / async-def signature one-per-line iff it has >= 3 parameters
+    AND at least one default value; otherwise keep it collapsible.
+
+    Rationale: signatures with defaults read better one parameter per line, but
+    only once they are non-trivial (< 3 params always stay on one line). A
+    signature with >= 3 params and a default gets a magic trailing comma added
+    (ruff then wraps it one-per-line regardless of length); every other
+    signature has its trailing comma stripped so ruff collapses it onto one line
+    when it fits (and wraps a genuinely long one by length alone).
+
+    Function-definition parameter lists only, never call sites or collection
+    literals. Parameter counts and defaults come from the AST. Run BEFORE ruff
+    format. Adding or removing a def trailing comma never changes the AST, which
+    is re-checked before returning.
+    """
+    try:
+        tree = ast.parse(text)
+        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return text, False
+
+    specs = _def_specs_by_line(tree)
+    n = len(toks)
+    edits: list[tuple[int, int, str]] = []  # (row, col, "del" | "ins")
+    i = 0
+    while i < n:
+        t = toks[i]
+        if t.type == tokenize.NAME and t.string == "def" and t.start[0] in specs:
+            cnt, has_default = specs[t.start[0]]
+            force_multiline = cnt >= _DEF_MIN_PARAMS_FOR_MULTILINE and has_default
+            j = i + 1
+            while j < n and not (toks[j].type == tokenize.OP and toks[j].string == "("):
+                if toks[j].type == tokenize.NEWLINE:
+                    break
+                j += 1
+            if j < n and toks[j].type == tokenize.OP and toks[j].string == "(":
+                depth = 0
+                k = j
+                while k < n:
+                    tk = toks[k]
+                    if tk.type == tokenize.OP and tk.string == "(":
+                        depth += 1
+                    elif tk.type == tokenize.OP and tk.string == ")":
+                        depth -= 1
+                        if depth == 0:
+                            m = k - 1
+                            while m > j and toks[m].type in _STRING_TRIVIA:
+                                m -= 1
+                            last = toks[m]
+                            has_comma = last.type == tokenize.OP and last.string == ","
+                            empty = m == j  # nothing between ( and )
+                            if force_multiline and not has_comma and not empty:
+                                edits.append((last.end[0], last.end[1], "ins"))
+                            elif not force_multiline and has_comma:
+                                edits.append((last.start[0], last.start[1], "del"))
+                            break
+                    k += 1
+                i = k + 1
+                continue
+        i += 1
+
+    if not edits:
+        return text, False
+
+    lines = text.splitlines(keepends=True)
+    for row, col, kind in sorted(edits, reverse=True):
+        ln = lines[row - 1]
+        if kind == "del":
+            if col < len(ln) and ln[col] == ",":
+                lines[row - 1] = ln[:col] + ln[col + 1 :]
+        else:  # ins
+            lines[row - 1] = ln[:col] + "," + ln[col:]
+    out = "".join(lines)
+    try:
+        if ast.dump(ast.parse(out)) != ast.dump(ast.parse(text)):
+            return text, False
+    except SyntaxError:
+        return text, False
+    return out, True
+
+
+def _split_string_token(s: str) -> tuple[str, str, str] | None:
+    """Split a string literal's source into (prefix, quote, body).
+
+    ``prefix`` is the letters before the opening quote (``r``/``f``/``b``/``u``
+    in any case/order), ``quote`` is the opening delimiter (``'``, ``"``,
+    ``'''`` or ``\"\"\"``) and ``body`` is everything between the delimiters.
+    Returns ``None`` if ``s`` is not a recognizable string literal.
+    """
+    i = 0
+    while i < len(s) and s[i] not in ("'", '"'):
+        i += 1
+    if i >= len(s):
+        return None
+    prefix, rest = s[:i], s[i:]
+    for q in ('"""', "'''", '"', "'"):
+        if rest.startswith(q) and rest.endswith(q) and len(rest) >= 2 * len(q):
+            return prefix, q, rest[len(q) : len(rest) - len(q)]
+    return None
+
+
+# A "piece" is one string literal in source: a plain STRING token, or a whole
+# f-string spanning FSTRING_START..FSTRING_END. (kind, (row, col0), (row, col1), raw)
+def _string_pieces(
+    toks: list[tokenize.TokenInfo], lines: list[str]
+) -> list[tuple[str, tuple[int, int], tuple[int, int], str | None]]:
+    pieces: list[tuple[str, tuple[int, int], tuple[int, int], str | None]] = []
+    n = len(toks)
+
+    def raw_of(start: tuple[int, int], end: tuple[int, int]) -> str | None:
+        if start[0] != end[0]:  # only single-physical-line pieces are mergeable
+            return None
+        return lines[start[0] - 1][start[1] : end[1]]
+
+    i = 0
+    while i < n:
+        t = toks[i]
+        if t.type == tokenize.STRING:
+            pieces.append(("str", t.start, t.end, raw_of(t.start, t.end)))
+            i += 1
+        elif t.type == tokenize.FSTRING_START:
+            depth = 0
+            j = i
+            while j < n:  # walk to the matching FSTRING_END (f-strings can nest)
+                if toks[j].type == tokenize.FSTRING_START:
+                    depth += 1
+                elif toks[j].type == tokenize.FSTRING_END:
+                    depth -= 1
+                    if depth == 0:
+                        break
+                j += 1
+            end = toks[j].end
+            pieces.append(("f", t.start, end, raw_of(t.start, end)))
+            i = j + 1
+        else:
+            pieces.append(("other", t.start, t.end, None))
+            i += 1
+    return pieces
+
+
+def _merge_string_run(pieces: list[tuple[str, str]]) -> str | None:
+    """Merge a run of adjacent string pieces into one literal's source text.
+
+    ``pieces`` is a list of ``(kind, raw_source)`` where kind is ``"str"`` or
+    ``"f"``. Rules: bytes are left side-by-side (return ``None``); a run with no
+    f-string merges plain/raw/unicode pieces sharing one prefix+quote by simple
+    body concatenation; a run mixing an f-string with at least one plain string
+    (and no bytes, no raw) folds into a single f-string -- f pieces keep their
+    bodies verbatim and plain pieces have their braces escaped (``{`` -> ``{{``).
+    Runs of only f-strings are left side-by-side. The caller re-checks the file
+    AST and drops the change if it differs, so any subtle case (e.g. ``\\N{...}``)
+    that this would mis-handle is caught and skipped.
+    """
+    parsed = []
+    for kind, raw in pieces:
+        pqb = _split_string_token(raw)
+        if pqb is None:
+            return None
+        prefix, quote, body = pqb
+        if "b" in prefix.lower():
+            return None  # bytes: leave side-by-side
+        parsed.append((kind, prefix, quote, body))
+    if len({p[2] for p in parsed}) != 1:
+        return None  # mixed quote style: not a safe textual merge
+    quote = parsed[0][2]
+    if not any(p[0] == "f" for p in parsed):
+        # No f-string: merge plain/raw/unicode sharing one prefix by concatenation.
+        if len({p[1].lower() for p in parsed}) != 1:
+            return None
+        return f"{parsed[0][1]}{quote}{''.join(p[3] for p in parsed)}{quote}"
+    # f-string fold only when a plain string is glued onto an f-string; a run of
+    # only f-strings is left side-by-side (folding long ones would force ruff to
+    # re-wrap the surrounding statement).
+    if all(p[0] == "f" for p in parsed):
+        return None
+    # raw mixed with f is too subtle (backslash + brace escaping) -> skip.
+    if any("r" in p[1].lower() for p in parsed):
+        return None
+    body = "".join(
+        b if kind == "f" else b.replace("{", "{{").replace("}", "}}")
+        for kind, _pfx, _q, b in parsed
+    )
+    return f"f{quote}{body}{quote}"
+
+
+_LINE_LENGTH = 100  # ruff line-length; an f-fold must not push a statement past it
+
+
+def _enclosing_stmt(tree: ast.AST, row: int) -> ast.stmt | None:
+    """The innermost statement whose physical-line span contains ``row``."""
+    best: tuple[ast.stmt, int] | None = None
+    for node in ast.walk(tree):
+        if isinstance(node, ast.stmt):
+            lo = node.lineno
+            hi = node.end_lineno or lo
+            if lo <= row <= hi and (best is None or hi - lo < best[1]):
+                best = (node, hi - lo)
+    return best[0] if best else None
+
+
+def _fold_collapses(
+    tree: ast.AST, lines: list[str], row: int, c0: int, c1: int, merged: str
+) -> bool:
+    """Whether an f-string fold at ``row[c0:c1]`` -> ``merged`` is safe to apply.
+
+    Only ``assert`` statements wrap awkwardly when a message is folded: ruff
+    parenthesizes the *condition* once ``assert cond, msg`` no longer fits on one
+    line. For every other construct (call argument, ``raise``, assignment, ...) a
+    folded long message wraps acceptably, so the fold is always allowed. For an
+    ``assert`` the fold is allowed only when the statement is already one physical
+    line, or its estimated one-line length after folding fits the line length;
+    otherwise the message is left side-by-side.
+    """
+    stmt = _enclosing_stmt(tree, row)
+    if not isinstance(stmt, ast.Assert):
+        return True
+    lo, hi = stmt.lineno, stmt.end_lineno or stmt.lineno
+    if lo == hi:
+        return True
+    seg = []
+    for k in range(lo, hi + 1):
+        ln = lines[k - 1].rstrip("\n")
+        if k == row:
+            ln = ln[:c0] + merged + ln[c1:]
+        seg.append(ln)
+    indent = len(seg[0]) - len(seg[0].lstrip())
+    # Conservative over-estimate: join continuation lines with a single space
+    # (ruff joins bracketed wraps with none), so borderline cases skip the fold.
+    joined = " ".join(s.strip() for s in seg)
+    return indent + len(joined) <= _LINE_LENGTH
+
+
+def merge_adjacent_string_literals(text: str) -> tuple[str, bool]:
+    """Merge a run of adjacent string literals on ONE physical line into a single
+    literal (the ``"a" "b"`` form ruff emits when it collapses an implicit
+    concatenation). Plain/raw/unicode runs merge by concatenation; a run mixing
+    an f-string with a plain string folds into one f-string (plain parts' braces
+    escaped) -- but only when the statement still fits on one line, so a long
+    message is left side-by-side rather than forcing the statement to re-wrap.
+    Runs of only f-strings, and bytes, are left side-by-side. The whole file's AST
+    is re-checked and the change is dropped if it would differ, so the transform
+    can never change meaning.
+    """
+    try:
+        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
+        tree = ast.parse(text)
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return text, False
+
+    lines = text.splitlines(keepends=True)
+    pieces = _string_pieces(toks, lines)
+
+    # Group consecutive mergeable pieces (str/f, single line, same physical line).
+    runs: list[list[tuple[str, tuple[int, int], tuple[int, int], str]]] = []
+    cur: list[tuple[str, tuple[int, int], tuple[int, int], str]] = []
+    for kind, start, end, raw in pieces:
+        if kind in ("str", "f") and raw is not None:
+            if cur and cur[-1][2][0] != start[0]:
+                if len(cur) >= 2:
+                    runs.append(cur)
+                cur = []
+            cur.append((kind, start, end, raw))
+        else:
+            if len(cur) >= 2:
+                runs.append(cur)
+            cur = []
+    if len(cur) >= 2:
+        runs.append(cur)
+    if not runs:
+        return text, False
+
+    edits = []
+    for run in runs:
+        merged = _merge_string_run([(kind, raw) for kind, _s, _e, raw in run])
+        if merged is None:
+            continue
+        row, c0, c1 = run[0][1][0], run[0][1][1], run[-1][2][1]
+        # An f-string fold must not push its statement onto extra lines; a plain
+        # concatenation always collapses cleanly so it skips this check.
+        if any(kind == "f" for kind, _s, _e, _r in run) and not _fold_collapses(
+            tree, lines, row, c0, c1, merged
+        ):
+            continue
+        edits.append((row, c0, c1, merged))
+    if not edits:
+        return text, False
+
+    for row, c0, c1, repl in sorted(edits, key=lambda e: (e[0], e[1]), reverse=True):
+        ln = lines[row - 1]
+        lines[row - 1] = ln[:c0] + repl + ln[c1:]
+    out = "".join(lines)
+    try:
+        if ast.dump(ast.parse(text)) != ast.dump(ast.parse(out)):
+            return text, False
+    except SyntaxError:
+        return text, False
+    return out, True
+
+
+def collapse_short_asserts(text: str) -> tuple[str, bool]:
+    """Collapse a multi-line ``assert`` onto one line when it would fit.
+
+    An ``assert`` is often kept multi-line only by a magic trailing comma inside
+    a collection / call / tuple-message (``assert x == {\"a\": 1,}`` written
+    across lines). When the whole statement's estimated one-line length fits the
+    line length, strip those trailing commas (the comma before a ``)`` / ``]`` /
+    ``}``) so ruff joins it back onto one line on the following format pass.
+
+    Run BEFORE ruff format. Skips any assert that contains a comment (a comment
+    forces ruff to keep it multi-line, which would oscillate). Stripping a
+    trailing comma is non-semantic except for a one-element tuple ``(x,)``; the
+    file AST is re-checked and any assert whose strip would change it is left
+    alone.
+    """
+    try:
+        tree = ast.parse(text)
+        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return text, False
+
+    lines = text.splitlines(keepends=True)
+    multiline = [
+        (n.lineno, n.end_lineno)
+        for n in ast.walk(tree)
+        if isinstance(n, ast.Assert) and (n.end_lineno or n.lineno) > n.lineno
+    ]
+    if not multiline:
+        return text, False
+
+    comment_rows = {t.start[0] for t in toks if t.type == tokenize.COMMENT}
+
+    targets = []  # (lo, hi) spans whose one-line form fits and have no comment
+    for lo, hi in multiline:
+        if any(lo <= r <= hi for r in comment_rows):
+            continue  # a comment would keep ruff multi-line -> never collapses
+        seg = [lines[k].rstrip("\n") for k in range(lo - 1, hi)]
+        indent = len(seg[0]) - len(seg[0].lstrip())
+        # Over-estimate (join with a space; keep the comma) so a "fits" verdict
+        # is always at least as long as ruff's real one-line output -> no fight.
+        if indent + len(" ".join(s.strip() for s in seg)) <= _LINE_LENGTH:
+            targets.append((lo, hi))
+    if not targets:
+        return text, False
+
+    # Trailing commas (a ',' whose next significant token is a closer), grouped
+    # by the target assert they belong to.
+    sig = [t for t in toks if t.type not in _STRING_TRIVIA]
+    by_target: dict[tuple[int, int], list[tuple[int, int]]] = defaultdict(list)
+    for i, t in enumerate(sig):
+        if t.type == tokenize.OP and t.string == ",":
+            nxt = sig[i + 1] if i + 1 < len(sig) else None
+            if nxt and nxt.type == tokenize.OP and nxt.string in (")", "]", "}"):
+                for lo, hi in targets:
+                    if lo <= t.start[0] <= hi:
+                        by_target[(lo, hi)].append(t.start)
+                        break
+    if not by_target:
+        return text, False
+
+    base_dump = ast.dump(tree)
+    working = lines[:]
+    changed = False
+    for positions in by_target.values():  # apply per assert; skip any that break AST
+        trial = working[:]
+        for row, col in sorted(positions, reverse=True):
+            ln = trial[row - 1]
+            if col < len(ln) and ln[col] == ",":
+                trial[row - 1] = ln[:col] + ln[col + 1 :]
+        try:
+            if ast.dump(ast.parse("".join(trial))) == base_dump:
+                working, changed = trial, True
+        except SyntaxError:
+            pass
+    return ("".join(working), True) if changed else (text, False)
+
+
+def process_file(path: Path, pre: bool = False) -> bool:
     try:
         with tokenize.open(path) as handle:
             original = handle.read()
@@ -169,9 +635,23 @@ def process_file(path: Path) -> bool:
         print(f"Failed to read {path}: {exc}", file=sys.stderr)
         return False
 
+    if pre:
+        # Pre-ruff: normalize def-signature magic commas (>=3 params + a default
+        # add so ruff forces one-per-line; everything else strips so ruff
+        # collapses), and strip the magic trailing comma from a short multi-line
+        # assert so ruff joins it onto one line. Everything else runs post-ruff.
+        updated, normalized = normalize_def_trailing_comma(original)
+        updated, collapsed = collapse_short_asserts(updated)
+        if normalized or collapsed:
+            _atomic_write_text(path, updated, encoding)
+            return True
+        return False
+
     updated, changed = enforce_spacing(original)
+    updated, blanked = remove_blank_after_short_import(updated)
+    updated, merged = merge_adjacent_string_literals(updated)
     updated, removed = remove_redundant_passes(updated)
-    if changed or removed:
+    if changed or blanked or merged or removed:
         _atomic_write_text(path, updated, encoding)
         return True
     return False
@@ -180,6 +660,11 @@ def process_file(path: Path) -> bool:
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("files", nargs="+", help="Python files to fix")
+    parser.add_argument(
+        "--pre",
+        action="store_true",
+        help="pre-ruff pass: normalize def-signature commas + collapse short multi-line asserts",
+    )
     args = parser.parse_args(argv)
 
     touched: list[Path] = []
@@ -192,7 +677,7 @@ def main(argv: list[str]) -> int:
             continue
         if not path.exists() or path.is_dir():
             continue
-        if process_file(path):
+        if process_file(path, pre=args.pre):
             touched.append(path)
 
     if touched:
diff --git a/scripts/lint_workflow_triggers.py b/scripts/lint_workflow_triggers.py
index d8e7356fd1..34868b7d68 100644
--- a/scripts/lint_workflow_triggers.py
+++ b/scripts/lint_workflow_triggers.py
@@ -47,9 +47,7 @@ from pathlib import Path
 try:
     import yaml
 except ImportError:
-    print(
-        "ERROR: PyYAML is required. Install with 'pip install pyyaml'", file = sys.stderr
-    )
+    print("ERROR: PyYAML is required. Install with 'pip install pyyaml'", file = sys.stderr)
     sys.exit(2)
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
@@ -153,9 +151,7 @@ def main() -> int:
                 )
 
     if findings:
-        print(
-            "Workflow trigger lint failed with the following issues:", file = sys.stderr
-        )
+        print("Workflow trigger lint failed with the following issues:", file = sys.stderr)
         for f in findings:
             print(f"  - {f}", file = sys.stderr)
         return 1
diff --git a/scripts/lockfile_supply_chain_audit.py b/scripts/lockfile_supply_chain_audit.py
index ffeea51c23..5b503dcffe 100644
--- a/scripts/lockfile_supply_chain_audit.py
+++ b/scripts/lockfile_supply_chain_audit.py
@@ -541,9 +541,7 @@ def audit_npm_lockfile(path: Path) -> list[Finding]:
                     path = str(path),
                     package = key,
                     kind = "blocked-known-malicious",
-                    detail = (
-                        f"{pkg_name}@{version} is on the " "BLOCKED_NPM_VERSIONS list"
-                    ),
+                    detail = (f"{pkg_name}@{version} is on the BLOCKED_NPM_VERSIONS list"),
                 )
             )
 
@@ -765,10 +763,7 @@ def main(argv: list[str] | None = None) -> int:
         "--cargo-lockfile",
         action = "append",
         default = None,
-        help = (
-            "Path to a Cargo.lock (repeatable). "
-            "Default: studio/src-tauri/Cargo.lock."
-        ),
+        help = ("Path to a Cargo.lock (repeatable). Default: studio/src-tauri/Cargo.lock."),
     )
     parser.add_argument(
         "--strict",
diff --git a/scripts/notebook_to_python.py b/scripts/notebook_to_python.py
index 4e3046103e..cc9dc0acda 100644
--- a/scripts/notebook_to_python.py
+++ b/scripts/notebook_to_python.py
@@ -186,9 +186,7 @@ def convert_cell_to_python(source: str, *, allow_shell: bool = True) -> str:
                 cmd_lines.append(lines[i].strip())
             full_cmd = "\n".join(cmd_lines)
 
-            result.extend(
-                _emit_shell_command(indent, full_cmd, allow_shell = allow_shell)
-            )
+            result.extend(_emit_shell_command(indent, full_cmd, allow_shell = allow_shell))
 
         # %cd path -> os.chdir(path)
         elif stripped.startswith("%cd "):
@@ -313,9 +311,7 @@ def convert_notebook_to_script(
     # Generate output filename
     output_filename = filename.replace(".ipynb", ".py")
     # Clean up filename
-    output_filename = (
-        output_filename.replace("(", "").replace(")", "").replace("-", "_")
-    )
+    output_filename = output_filename.replace("(", "").replace(")", "").replace("-", "_")
 
     # Add output directory if specified
     if output_dir:
@@ -337,9 +333,7 @@ def convert_notebook_to_script(
 def main():
     import argparse
 
-    class Formatter(
-        argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter
-    ):
+    class Formatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter):
         pass
 
     parser = argparse.ArgumentParser(
@@ -353,12 +347,8 @@ Examples:
   python notebook_to_python.py https://github.com/unslothai/notebooks/blob/main/nb/Oute_TTS_(1B).ipynb
 """,
     )
-    parser.add_argument(
-        "notebooks", nargs = "+", help = "Notebook files or URLs to convert."
-    )
-    parser.add_argument(
-        "-o", "--output", dest = "output_dir", default = ".", help = "Output directory."
-    )
+    parser.add_argument("notebooks", nargs = "+", help = "Notebook files or URLs to convert.")
+    parser.add_argument("-o", "--output", dest = "output_dir", default = ".", help = "Output directory.")
     # Default True for backwards compatibility: existing Colab notebooks
     # routinely use pipes / redirection / interpolation in `!cmd` lines
     # and the converted script needs to keep working. Operators who
diff --git a/scripts/notebook_validator.py b/scripts/notebook_validator.py
index 55a9203e0b..74bfaa8d41 100644
--- a/scripts/notebook_validator.py
+++ b/scripts/notebook_validator.py
@@ -92,9 +92,7 @@ COLAB_ORACLE_FILES: dict[str, str] = {
     "apt-list-gpu.txt": "colab_apt_list.gpu.txt",
     "os-info-gpu.txt": "colab_os_info.gpu.txt",
 }
-COLAB_ORACLE_BASE_URL = (
-    "https://raw.githubusercontent.com/googlecolab/backend-info/main/"
-)
+COLAB_ORACLE_BASE_URL = "https://raw.githubusercontent.com/googlecolab/backend-info/main/"
 
 # ----- Compat tables. PRs add rows as new releases land. ----- #
 
@@ -195,9 +193,7 @@ def install_cells(nb: dict[str, Any]) -> list[tuple[int, str]]:
         if first and first[0].strip().startswith("%%capture"):
             out.append((i, src))
             continue
-        if re.search(
-            r"^[ \t]*!\s*(uv\s+)?pip\s+(install|uninstall)\b", src, re.MULTILINE
-        ):
+        if re.search(r"^[ \t]*!\s*(uv\s+)?pip\s+(install|uninstall)\b", src, re.MULTILINE):
             out.append((i, src))
     return out
 
@@ -331,9 +327,7 @@ def parse_pip_line(line: str, line_no: int = 0) -> PipInvocation | None:
         if t in ("install", "uninstall"):
             continue
         packages.append(t)
-    return PipInvocation(
-        tool = tool, flags = flags, packages = packages, raw = line, line_no = line_no
-    )
+    return PipInvocation(tool = tool, flags = flags, packages = packages, raw = line, line_no = line_no)
 
 
 def _glue_line_continuations(text: str) -> list[tuple[int, str]]:
@@ -418,9 +412,7 @@ def pypi_metadata(name: str, version: str) -> dict[str, Any] | None:
     return data
 
 
-def transitive_constraint(
-    name: str, version: str, target: str
-) -> tuple[str | None, list[str]]:
+def transitive_constraint(name: str, version: str, target: str) -> tuple[str | None, list[str]]:
     """Return (raw_specifier_string_or_None, list_of_(op,version) tuples)
     for the constraint that `name==version` places on `target`.
     """
@@ -501,10 +493,7 @@ def resolved_set(install_cell: str, colab: dict[str, str]) -> dict[str, str]:
                     out[sp.name] = ver
                     pinned.add(sp.name)
                 elif op == "<=" and sp.name not in pinned:
-                    if (
-                        sp.name not in upper_bounds
-                        or cmp_versions(ver, upper_bounds[sp.name]) < 0
-                    ):
+                    if sp.name not in upper_bounds or cmp_versions(ver, upper_bounds[sp.name]) < 0:
                         upper_bounds[sp.name] = ver
     # Apply upper bounds where Colab's preinstall violates them.
     for name, ub in upper_bounds.items():
@@ -519,9 +508,7 @@ def resolved_set(install_cell: str, colab: dict[str, str]) -> dict[str, str]:
 # ----- Rules ----- #
 
 
-def rule_inst_001_git_plus(
-    install_cell: str, file: str, cell_idx: int
-) -> list[Finding]:
+def rule_inst_001_git_plus(install_cell: str, file: str, cell_idx: int) -> list[Finding]:
     findings: list[Finding] = []
     for inv in iter_pip_invocations(install_cell):
         if any("git+" in p for p in inv.packages) or "git+" in inv.raw:
@@ -714,9 +701,7 @@ def rule_inst_005_transformers_tokenizers(
 _RE_DOUBLE_BANG = re.compile(r"^[ \t]*!{2,}\s*pip\b", re.MULTILINE)
 
 
-def rule_inst_006_double_bang(
-    install_cell: str, file: str, cell_idx: int
-) -> list[Finding]:
+def rule_inst_006_double_bang(install_cell: str, file: str, cell_idx: int) -> list[Finding]:
     findings: list[Finding] = []
     for m in _RE_DOUBLE_BANG.finditer(install_cell):
         line_no = install_cell.count("\n", 0, m.start()) + 1
@@ -813,9 +798,7 @@ POLICY_CLAUSES_DEFAULT = [
 ]
 
 
-def extract_policy_clauses(
-    update_script: pathlib.Path,
-) -> list[tuple[str, re.Pattern[str], Any]]:
+def extract_policy_clauses(update_script: pathlib.Path) -> list[tuple[str, re.Pattern[str], Any]]:
     """Best-effort: scan update_all_notebooks.py for canonical phrases used by
     multiple templates. Falls back to POLICY_CLAUSES_DEFAULT.
 
@@ -879,11 +862,7 @@ def cmd_drift(args: argparse.Namespace) -> int:
         print(f"FAIL: {update_script} not found", file = sys.stderr)
         return 2
     # Stash any pre-existing dirty state, run the updater, diff, restore.
-    head = (
-        subprocess.check_output(["git", "rev-parse", "HEAD"], cwd = nbdir)
-        .decode()
-        .strip()
-    )
+    head = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd = nbdir).decode().strip()
     subprocess.run(
         ["git", "-C", str(nbdir), "stash", "--include-untracked"],
         check = False,
@@ -990,9 +969,7 @@ def cmd_convert(args: argparse.Namespace) -> int:
                         hint = proc.stderr[-200:].strip(),
                     )
                 )
-    print(
-        f"converted {len(notebooks) - len(failed)}/{len(notebooks)} notebooks to {out}"
-    )
+    print(f"converted {len(notebooks) - len(failed)}/{len(notebooks)} notebooks to {out}")
     _emit(failed)
     return 0 if not failed else 1
 
@@ -1002,11 +979,7 @@ def cmd_convert(args: argparse.Namespace) -> int:
 
 def cmd_lint(args: argparse.Namespace) -> int:
     nbdir = pathlib.Path(args.notebooks_dir).resolve()
-    colab_path = (
-        pathlib.Path(args.colab_pin).resolve()
-        if args.colab_pin
-        else COLAB_FALLBACK_FILE
-    )
+    colab_path = pathlib.Path(args.colab_pin).resolve() if args.colab_pin else COLAB_FALLBACK_FILE
     colab = parse_pip_freeze(colab_path)
     if not colab:
         print(
@@ -1049,13 +1022,9 @@ def cmd_lint(args: argparse.Namespace) -> int:
             first_cell = cells[0][0] if cells else None
             findings += rule_inst_003_peft_torchao(merged, oracle, rel, first_cell)
             findings += rule_inst_004_torchcodec_torch(merged, oracle, rel, first_cell)
-            findings += rule_inst_005_transformers_tokenizers(
-                merged, oracle, rel, first_cell
-            )
+            findings += rule_inst_005_transformers_tokenizers(merged, oracle, rel, first_cell)
             if not args.no_pypi:
-                findings += rule_inst_002_no_deps_transitive(
-                    merged, oracle, rel, first_cell
-                )
+                findings += rule_inst_002_no_deps_transitive(merged, oracle, rel, first_cell)
         findings += scan_user_cells(nb, rel)
     _emit(findings)
     return 0 if not any(f.severity == "error" for f in findings) else 1
@@ -1232,9 +1201,7 @@ def cmd_colab_diff(args: argparse.Namespace) -> int:
             print(f"::warning::colab-diff: could not fetch {url}: {e}")
             continue
         if not snap_path.exists():
-            print(
-                f"::warning::colab-diff: no committed snapshot at {snap_path}; skipping"
-            )
+            print(f"::warning::colab-diff: no committed snapshot at {snap_path}; skipping")
             continue
         snapshot_text = snap_path.read_text(encoding = "utf-8", errors = "replace")
         parser = _COLAB_ORACLE_PARSERS[upstream_name]
diff --git a/scripts/run_ruff_format.py b/scripts/run_ruff_format.py
index 5ec16cd9f5..2f0a6c6bba 100755
--- a/scripts/run_ruff_format.py
+++ b/scripts/run_ruff_format.py
@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
-"""Run `ruff format` followed by kwarg spacing enforcement."""
+"""Run a pre-pass (normalize def-signature magic commas + collapse short
+multi-line asserts), then `ruff format`, then the kwarg-spacing / import /
+string-merge post-pass."""
 
 from __future__ import annotations
 
@@ -15,12 +17,22 @@ def main(argv: list[str]) -> int:
     if not files:
         return 0
 
+    spacing_script = HERE / "enforce_kwargs_spacing.py"
+
+    # Pre-ruff: normalize def-signature trailing commas (>=3 params with a
+    # default -> one-per-line; everything else collapsible) and strip the magic
+    # comma from a short multi-line assert, so ruff wraps signatures accordingly
+    # and joins the assert back onto one line.
+    pre_cmd = [sys.executable, str(spacing_script), "--pre", *files]
+    pre_proc = subprocess.run(pre_cmd)
+    if pre_proc.returncode != 0:
+        return pre_proc.returncode
+
     ruff_cmd = [sys.executable, "-m", "ruff", "format", *files]
     ruff_proc = subprocess.run(ruff_cmd)
     if ruff_proc.returncode != 0:
         return ruff_proc.returncode
 
-    spacing_script = HERE / "enforce_kwargs_spacing.py"
     spacing_cmd = [sys.executable, str(spacing_script), *files]
     spacing_proc = subprocess.run(spacing_cmd)
     return spacing_proc.returncode
diff --git a/scripts/scan_npm_packages.py b/scripts/scan_npm_packages.py
index 07eccdd716..14a3cd6560 100644
--- a/scripts/scan_npm_packages.py
+++ b/scripts/scan_npm_packages.py
@@ -823,8 +823,7 @@ def download_tarball(
                     written += len(chunk)
                     if written > max_bytes:
                         return dest, (
-                            f"download exceeded cap {max_bytes} bytes "
-                            f"after {written} bytes"
+                            f"download exceeded cap {max_bytes} bytes " f"after {written} bytes"
                         )
                     h.update(chunk)
                     out.write(chunk)
@@ -926,11 +925,7 @@ def safe_extract(
                 # get the generous binary cap. We bound BOTH cases.
                 header = src.read(16)
                 is_binary = _looks_binary(name, header)
-                file_cap = (
-                    HARD_MAX_BINARY_FILE_BYTES
-                    if is_binary
-                    else HARD_MAX_TEXT_FILE_BYTES
-                )
+                file_cap = HARD_MAX_BINARY_FILE_BYTES if is_binary else HARD_MAX_TEXT_FILE_BYTES
                 if declared > file_cap:
                     return (
                         f"member {name!r} declared size {declared} > "
@@ -963,7 +958,11 @@ def safe_extract(
 # ─────────────────────────────────────────────────────────────────────
 
 
-def _evidence(text: str, pat: re.Pattern, max_chars: int = 200) -> str:
+def _evidence(
+    text: str,
+    pat: re.Pattern,
+    max_chars: int = 200,
+) -> str:
     m = pat.search(text)
     if not m:
         return ""
@@ -978,11 +977,7 @@ def _evidence(text: str, pat: re.Pattern, max_chars: int = 200) -> str:
 LIFECYCLE_HOOKS = ("preinstall", "install", "postinstall", "prepare")
 
 
-def scan_package_json(
-    pkg: PackageEntry,
-    rel: str,
-    text: str,
-) -> list[Finding]:
+def scan_package_json(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
     findings: list[Finding] = []
     try:
         meta = json.loads(text)
@@ -1056,9 +1051,7 @@ def scan_package_json(
     if isinstance(opt, dict):
         for k, v in opt.items():
             if isinstance(v, str) and (
-                v.startswith("github:")
-                or v.startswith("git+")
-                or v.startswith("git://")
+                v.startswith("github:") or v.startswith("git+") or v.startswith("git://")
             ):
                 findings.append(
                     Finding(
@@ -1117,11 +1110,7 @@ def _host_in_outbound_context(text: str, host: str) -> bool:
     return False
 
 
-def scan_text_blob(
-    pkg: PackageEntry,
-    rel: str,
-    text: str,
-) -> list[Finding]:
+def scan_text_blob(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
     findings: list[Finding] = []
 
     # IOC substrings (literal, case-sensitive).
@@ -1190,10 +1179,7 @@ def scan_text_blob(
                 filename = rel,
                 pattern = "js-fetch-eval",
                 evidence = _evidence(text, _JS_FETCH_EVAL),
-                detail = (
-                    "Function/eval against base64-decoded payload "
-                    "(obfuscated dropper shape)"
-                ),
+                detail = ("Function/eval against base64-decoded payload (obfuscated dropper shape)"),
             )
         )
     if _JS_ENV_TOKEN.search(text):
@@ -1247,10 +1233,7 @@ _TEXT_SUFFIXES = (
 )
 
 
-def scan_extracted_tree(
-    pkg: PackageEntry,
-    root: Path,
-) -> list[Finding]:
+def scan_extracted_tree(pkg: PackageEntry, root: Path) -> list[Finding]:
     findings: list[Finding] = []
     for path in sorted(root.rglob("*")):
         if not path.is_file():
@@ -1304,10 +1287,7 @@ def scan_extracted_tree(
 # ─────────────────────────────────────────────────────────────────────
 
 
-def scan_one(
-    pkg: PackageEntry,
-    workspace: Path,
-) -> tuple[list[Finding], str | None]:
+def scan_one(pkg: PackageEntry, workspace: Path) -> tuple[list[Finding], str | None]:
     """Download + extract + scan a single package. Cleans up its dir.
 
     Returns (findings, error). `error` is non-None only on hard
@@ -1444,8 +1424,7 @@ def main(argv: list[str] | None = None) -> int:
     if hard_errors or blocking:
         if blocking:
             print(
-                f"\n[scan-npm] FAIL: {len(blocking)} finding(s) "
-                f"at or above {threshold}",
+                f"\n[scan-npm] FAIL: {len(blocking)} finding(s) " f"at or above {threshold}",
                 file = sys.stderr,
             )
         return 1
diff --git a/scripts/scan_packages.py b/scripts/scan_packages.py
index 6779b634f7..d753a17e49 100644
--- a/scripts/scan_packages.py
+++ b/scripts/scan_packages.py
@@ -86,8 +86,7 @@ RE_SUBPROCESS = re.compile(
 
 # Encoding / obfuscation
 RE_BASE64 = re.compile(
-    r"\bbase64\s*\.\s*(b64decode|decodebytes|b32decode|b16decode)\b"
-    r"|\bcodecs\s*\.\s*decode\b",
+    r"\bbase64\s*\.\s*(b64decode|decodebytes|b32decode|b16decode)\b|\bcodecs\s*\.\s*decode\b",
 )
 
 # exec / eval
@@ -299,9 +298,7 @@ RE_CRYPTO_THEFT = re.compile(
 RE_PTH_IMPORT = re.compile(r"^\s*import\s+", re.MULTILINE)
 
 # openssl CLI invocations via subprocess (encrypted exfiltration)
-RE_OPENSSL_CLI = re.compile(
-    r"\bopenssl\s+(enc|rand|rsautl|pkeyutl|genrsa|dgst|s_client)\b"
-)
+RE_OPENSSL_CLI = re.compile(r"\bopenssl\s+(enc|rand|rsautl|pkeyutl|genrsa|dgst|s_client)\b")
 
 # Write to /tmp then execute (staged dropper)
 RE_TEMP_EXEC = re.compile(
@@ -962,7 +959,11 @@ def check_py_file(content: str, filename: str, package: str) -> list[Finding]:
     return findings
 
 
-def _extract_evidence(content: str, pattern: re.Pattern, max_matches: int = 3) -> str:
+def _extract_evidence(
+    content: str,
+    pattern: re.Pattern,
+    max_matches: int = 3,
+) -> str:
     """Pull matching lines as evidence snippets."""
     lines = content.splitlines()
     matches = []
@@ -1266,15 +1267,13 @@ def iter_archive_files(archive_path: str):
                 # have historically dereferenced them on extract.
                 if member.issym() or member.islnk():
                     print(
-                        f"  [WARN] {path.name}: refused link member "
-                        f"{member.name!r}",
+                        f"  [WARN] {path.name}: refused link member " f"{member.name!r}",
                         file = sys.stderr,
                     )
                     continue
                 if member.isdev() or member.isfifo():
                     print(
-                        f"  [WARN] {path.name}: refused special member "
-                        f"{member.name!r}",
+                        f"  [WARN] {path.name}: refused special member " f"{member.name!r}",
                         file = sys.stderr,
                     )
                     continue
@@ -1379,9 +1378,7 @@ def scan_archive(archive_path: str, package: str) -> list[Finding]:
 _RE_PYPI_SPEC_VERSION = re.compile(r"==\s*([A-Za-z0-9_.\-+!]+)")
 
 
-def _check_blocked_pypi_versions(
-    specs: list[str],
-) -> tuple[list[str], list[Finding]]:
+def _check_blocked_pypi_versions(specs: list[str]) -> tuple[list[str], list[Finding]]:
     """Filter ``specs`` against ``BLOCKED_PYPI_VERSIONS``.
 
     Returns ``(safe_specs, findings)``. Each blocked spec emits a CRITICAL
@@ -1502,9 +1499,7 @@ def download_packages(
                 env = env,
             )
             if proc.returncode != 0:
-                msg = (
-                    f"pip download (with deps) failed: " f"{proc.stderr.strip()[:500]}"
-                )
+                msg = f"pip download (with deps) failed: " f"{proc.stderr.strip()[:500]}"
                 print(f"  [ERROR] {msg}", file = sys.stderr)
                 download_errors.append(msg)
         except subprocess.TimeoutExpired:
@@ -1547,10 +1542,7 @@ def download_packages(
                     env = env,
                 )
                 if proc.returncode != 0:
-                    msg = (
-                        f"pip download failed for {spec}: "
-                        f"{proc.stderr.strip()[:500]}"
-                    )
+                    msg = f"pip download failed for {spec}: " f"{proc.stderr.strip()[:500]}"
                     print(f"  [ERROR] {msg}", file = sys.stderr)
                     download_errors.append(msg)
                     continue
@@ -1579,9 +1571,7 @@ def _extract_pkg_name(spec: str) -> str:
     """Extract the package name from a pip spec string."""
     m = _RE_NAME.match(spec)
     return (
-        m.group(1)
-        if m
-        else spec.split("==")[0].split(">=")[0].split("<=")[0].split("[")[0].strip()
+        m.group(1) if m else spec.split("==")[0].split(">=")[0].split("<=")[0].split("[")[0].strip()
     )
 
 
@@ -1917,11 +1907,7 @@ def update_req_file(filepath: str, updates: dict[int, str]) -> None:
         raise
 
 
-def _run_fix(
-    critical_pkgs: set[str],
-    entries: list[dict],
-    max_search: int,
-) -> None:
+def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> None:
     """Run the --fix flow: find safe versions, update requirements files."""
     # Map package names to their entries for source tracking
     pkg_entries: dict[str, list[dict]] = {}
@@ -1941,9 +1927,7 @@ def _run_fix(
             if git_entries:
                 for e in git_entries:
                     src = e["source_file"] or "CLI"
-                    print(
-                        f"  [SKIP] {pkg_name} is a git URL dep in {src}, cannot auto-update"
-                    )
+                    print(f"  [SKIP] {pkg_name} is a git URL dep in {src}, cannot auto-update")
                     changes_summary.append(f"  SKIP  {pkg_name} (git URL)")
                 continue
 
@@ -1967,9 +1951,7 @@ def _run_fix(
                 shutil.rmtree(dl_dir, ignore_errors = True)
 
             if not current_ver:
-                print(
-                    f"  [WARN] Cannot determine current version of {pkg_name}, skipping fix"
-                )
+                print(f"  [WARN] Cannot determine current version of {pkg_name}, skipping fix")
                 changes_summary.append(f"  SKIP  {pkg_name} (version unknown)")
                 continue
 
@@ -1986,9 +1968,7 @@ def _run_fix(
                 continue
 
             print(f"  [OK]   {pkg_name}: {current_ver} -> {safe_ver}")
-            changes_summary.append(
-                f"  FIX   {pkg_name}=={current_ver} -> {pkg_name}=={safe_ver}"
-            )
+            changes_summary.append(f"  FIX   {pkg_name}=={current_ver} -> {pkg_name}=={safe_ver}")
 
             # Update all occurrences in requirements files
             file_updates: dict[str, dict[int, str]] = {}
@@ -2038,9 +2018,7 @@ def _find_requirements_files(root: str) -> list[str]:
         dirnames[:] = [
             d
             for d in dirnames
-            if not d.startswith(".")
-            and d not in skip_dirs
-            and not d.endswith(".egg-info")
+            if not d.startswith(".") and d not in skip_dirs and not d.endswith(".egg-info")
         ]
         dirname = os.path.basename(dirpath)
         for fname in sorted(filenames):
@@ -2115,9 +2093,7 @@ def main() -> int:
                 print(f"    {f}")
             req_files.extend(found)
         else:
-            print(
-                f"  [WARN] No requirements files found in {scan_dir}/", file = sys.stderr
-            )
+            print(f"  [WARN] No requirements files found in {scan_dir}/", file = sys.stderr)
 
     # Build unified entry list: list of dicts with source tracking
     entries: list[dict] = []
@@ -2211,7 +2187,7 @@ def main() -> int:
         for err in download_errors:
             print(f"  [ERROR] {err}", file = sys.stderr)
         print(
-            "  Refusing to report 'all clean' on a partial scan; " "exiting 2.",
+            "  Refusing to report 'all clean' on a partial scan; exiting 2.",
             file = sys.stderr,
         )
         return 2
diff --git a/scripts/stamp_studio_release.py b/scripts/stamp_studio_release.py
index ac538e9937..a3c8712a6e 100644
--- a/scripts/stamp_studio_release.py
+++ b/scripts/stamp_studio_release.py
@@ -17,7 +17,11 @@ import zipfile
 from pathlib import Path
 
 
-def _atomic_write_text(path: Path, data: str, encoding: str = "utf-8") -> None:
+def _atomic_write_text(
+    path: Path,
+    data: str,
+    encoding: str = "utf-8",
+) -> None:
     """Atomic version of ``Path.write_text``.
 
     A crash or signal mid-write leaves the prior file intact; the
@@ -41,9 +45,7 @@ def _atomic_write_text(path: Path, data: str, encoding: str = "utf-8") -> None:
 
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
-BUILD_INFO_PATH = (
-    REPO_ROOT / "studio" / "backend" / "utils" / "_studio_release_build.py"
-)
+BUILD_INFO_PATH = REPO_ROOT / "studio" / "backend" / "utils" / "_studio_release_build.py"
 BUILD_INFO_SUFFIX = "studio/backend/utils/_studio_release_build.py"
 VERSION_RE = re.compile(r"^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.][0-9A-Za-z.-]*)?$")
 GIT_DESCRIBE_SUFFIX_RE = re.compile(r"-\d+-g[0-9A-Fa-f]+(?:-dirty)?$")
diff --git a/scripts/verify_comment_only_diff.py b/scripts/verify_comment_only_diff.py
index 90eafb7f8f..b661f76859 100644
--- a/scripts/verify_comment_only_diff.py
+++ b/scripts/verify_comment_only_diff.py
@@ -128,12 +128,15 @@ def _normalize_yaml_run_strings(obj: Any) -> Any:
     return obj
 
 
-def _walk_yaml_diff(b: Any, a: Any, prefix: str = "") -> None:
+def _walk_yaml_diff(
+    b: Any,
+    a: Any,
+    prefix: str = "",
+) -> None:
     """Print a path-keyed summary of the first structural / scalar diff."""
     if type(b) is not type(a):
         print(
-            f"     type-diff at {prefix or '/'}: "
-            f"{type(b).__name__} -> {type(a).__name__}",
+            f"     type-diff at {prefix or '/'}: " f"{type(b).__name__} -> {type(a).__name__}",
         )
         return
     if isinstance(b, dict):
diff --git a/scripts/verify_import_hoist.py b/scripts/verify_import_hoist.py
index 606488cc7f..6f5b452f3c 100644
--- a/scripts/verify_import_hoist.py
+++ b/scripts/verify_import_hoist.py
@@ -123,9 +123,7 @@ class _Builder(ast.NodeVisitor):
     def __init__(self):
         self.module = Scope("module", "<module>", None)
         self.uses: list[tuple[Scope, str, int]] = []  # (scope, name, lineno) hard loads
-        self.soft_uses: list[
-            tuple[Scope, str, int]
-        ] = []  # annotations: count as "used"
+        self.soft_uses: list[tuple[Scope, str, int]] = []  # annotations: count as "used"
         #                                                     but never as "unresolved"
         #                                                     (forward refs / string annos)
 
@@ -166,9 +164,7 @@ class _Builder(ast.NodeVisitor):
 
     def _visit_stmt(self, node: ast.AST, scope: Scope) -> None:
         if isinstance(node, (ast.Import, ast.ImportFrom)):
-            star = isinstance(node, ast.ImportFrom) and any(
-                a.name == "*" for a in node.names
-            )
+            star = isinstance(node, ast.ImportFrom) and any(a.name == "*" for a in node.names)
             if star:
                 scope.star_import = True
             for alias in node.names:
@@ -356,9 +352,7 @@ class _Builder(ast.NodeVisitor):
             self._bind_args(node.args, child)
             self._visit_expr(node.body, child)
             return
-        if isinstance(
-            node, (ast.ListComp, ast.SetComp, ast.GeneratorExp, ast.DictComp)
-        ):
+        if isinstance(node, (ast.ListComp, ast.SetComp, ast.GeneratorExp, ast.DictComp)):
             child = Scope("comp", f"{scope.qualname}.<comp>", scope)
             for i, gen in enumerate(node.generators):
                 # first iterable is evaluated in the enclosing scope
@@ -447,9 +441,7 @@ def _legb_chain(scope: Scope) -> list[Scope]:
     chain = [scope]
     p = scope.parent
     while p is not None:
-        if (
-            p.kind != "class" or p.parent is None
-        ):  # module-level class never happens; keep module
+        if p.kind != "class" or p.parent is None:  # module-level class never happens; keep module
             if p.kind != "class":
                 chain.append(p)
         p = p.parent
@@ -624,9 +616,7 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
     for scope, names in b["ambiguous"].items():
         new = names - a["ambiguous"].get(scope, set())
         for n in sorted(new):
-            findings.append(
-                ("WARN", f"{path}: AMBIGUOUS-BIND '{n}' import+non-import in {scope}")
-            )
+            findings.append(("WARN", f"{path}: AMBIGUOUS-BIND '{n}' import+non-import in {scope}"))
 
     # 6. TARGET-MISSING (informational): a scope stopped resolving to an import
     #    target. Real bugs are already covered above; remaining cases are code
@@ -639,9 +629,7 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
                 if t in added_module_targets
                 else "  [target not re-added here -> likely relocated/deleted]"
             )
-            findings.append(
-                ("INFO", f"{path}: TARGET-MISSING {t} in scope {scope}{relocated}")
-            )
+            findings.append(("INFO", f"{path}: TARGET-MISSING {t} in scope {scope}{relocated}"))
     return findings
 
 
@@ -650,45 +638,38 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
 _SELF_TESTS = {
     "dangling_alias": (
         # before: inline aliased import, used as _b
-        "import os\n"
-        "def f():\n"
-        "    import glob as _b\n"
-        "    return _b.glob('*')\n",
+        "import os\ndef f():\n    import glob as _b\n    return _b.glob('*')\n",
         # after: hoisted to canonical, but reference NOT normalized -> _b dangles
-        "import os\n" "import glob\n" "def f():\n" "    return _b.glob('*')\n",
+        "import os\nimport glob\ndef f():\n    return _b.glob('*')\n",
         "BLOCKER",
     ),
     "rename_clash": (
         # before: _b is a deliberate alias; `b` already means something else
-        "import re as _b\n" "b = 123\n" "def f():\n" "    return _b.compile('x'), b\n",
+        "import re as _b\nb = 123\ndef f():\n    return _b.compile('x'), b\n",
         # after: someone normalized _b -> b ; now f().b is the int, re is lost
-        "import re\n" "b = 123\n" "def f():\n" "    return b.compile('x'), b\n",
+        "import re\nb = 123\ndef f():\n    return b.compile('x'), b\n",
         "BLOCKER",  # TARGET-MISSING from:.. or import:re in f
     ),
     "clean_rename": (
-        "def f():\n" "    import glob as _g\n" "    return _g.glob('*')\n",
-        "import glob\n" "def f():\n" "    return glob.glob('*')\n",
+        "def f():\n    import glob as _g\n    return _g.glob('*')\n",
+        "import glob\ndef f():\n    return glob.glob('*')\n",
         None,  # expect NO blocker
     ),
     "clean_dedup_redundant": (
-        "import sys\n" "def f():\n" "    import sys\n" "    return sys.argv\n",
-        "import sys\n" "def f():\n" "    return sys.argv\n",
+        "import sys\ndef f():\n    import sys\n    return sys.argv\n",
+        "import sys\ndef f():\n    return sys.argv\n",
         None,
     ),
     "from_import_dangling": (
         # from-import alias left un-normalized
-        "def f():\n"
-        "    from importlib.metadata import version as _v\n"
-        "    return _v('x')\n",
-        "from importlib.metadata import version\n" "def f():\n" "    return _v('x')\n",
+        "def f():\n    from importlib.metadata import version as _v\n    return _v('x')\n",
+        "from importlib.metadata import version\ndef f():\n    return _v('x')\n",
         "BLOCKER",
     ),
     "local_var_clash": (
         # _b renamed to b, but b is a LOCAL variable in f -> import silently unused
-        "def f(b):\n" "    import re as _b\n" "    return _b.compile(b)\n",
-        "import re\n"
-        "def f(b):\n"
-        "    return b.compile(b)\n",  # 'b' is the param, not the module
+        "def f(b):\n    import re as _b\n    return _b.compile(b)\n",
+        "import re\ndef f(b):\n    return b.compile(b)\n",  # 'b' is the param, not the module
         "BLOCKER",
     ),
     "substring_safe": (
@@ -705,11 +686,8 @@ _SELF_TESTS = {
     ),
     "attr_access_not_a_use": (
         # x._b is attribute access, not a use of name _b; removing import _b is fine
-        "import os\n"
-        "def f(x):\n"
-        "    import sys as _b\n"
-        "    return x._b + _b.argv[0]\n",
-        "import os\n" "import sys\n" "def f(x):\n" "    return x._b + sys.argv[0]\n",
+        "import os\ndef f(x):\n    import sys as _b\n    return x._b + _b.argv[0]\n",
+        "import os\nimport sys\ndef f(x):\n    return x._b + sys.argv[0]\n",
         None,
     ),
 }
@@ -797,9 +775,7 @@ def audit_files(paths: list[str]) -> int:
     ok = n_err == 0 and n_fp == 0
     print(
         "\nAUDIT:",
-        "ROBUST (no crashes, no false positives vs pyflakes)"
-        if ok
-        else "NEEDS WORK (see above)",
+        "ROBUST (no crashes, no false positives vs pyflakes)" if ok else "NEEDS WORK (see above)",
     )
     return 0 if ok else 1
 
@@ -835,18 +811,12 @@ def main() -> int:
         blockers = [f for f in findings if f[0] == "BLOCKER"]
         warns = [f for f in findings if f[0] == "WARN"]
         infos = [f for f in findings if f[0] == "INFO"]
-        status = (
-            "CLEAN"
-            if not blockers and not warns
-            else ("BLOCKERS" if blockers else "WARNINGS")
-        )
+        status = "CLEAN" if not blockers and not warns else ("BLOCKERS" if blockers else "WARNINGS")
         print(f"\n=== {path}: {status} ===")
         for sev, m in blockers + warns + infos:
             print(f"  [{sev}] {m}")
         any_blocker = any_blocker or bool(blockers)
-    print(
-        "\nOVERALL:", "FAIL (blockers found)" if any_blocker else "PASS (no blockers)"
-    )
+    print("\nOVERALL:", "FAIL (blockers found)" if any_blocker else "PASS (no blockers)")
     return 1 if any_blocker else 0
 
 
diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index 6ddcbc8e0b..bb5b873e65 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -108,9 +108,7 @@ def create_refresh_token(subject: str, *, desktop: bool = False) -> str:
     return token
 
 
-def refresh_access_token(
-    refresh_token: str,
-) -> Tuple[Optional[str], Optional[str], bool]:
+def refresh_access_token(refresh_token: str) -> Tuple[Optional[str], Optional[str], bool]:
     """
     Validate a refresh token and issue a new access token.
 
@@ -137,9 +135,7 @@ def reload_secret() -> None:
     load_jwt_secret()
 
 
-async def get_current_subject(
-    credentials: HTTPAuthorizationCredentials = Depends(security),
-) -> str:
+async def get_current_subject(credentials: HTTPAuthorizationCredentials = Depends(security)) -> str:
     """Validate JWT and require the password-change flow to be completed."""
     return await _get_current_subject(
         credentials,
@@ -158,9 +154,7 @@ async def get_current_subject_allow_password_change(
 
 
 async def _get_current_subject(
-    credentials: HTTPAuthorizationCredentials,
-    *,
-    allow_password_change: bool,
+    credentials: HTTPAuthorizationCredentials, *, allow_password_change: bool
 ) -> str:
     """
     FastAPI dependency to validate the JWT and return the subject.
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index 3233aa05ef..0e34a0cf28 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -151,13 +151,9 @@ def get_connection() -> sqlite3.Connection:
         );
         """
     )
-    api_key_columns = {
-        row["name"] for row in conn.execute("PRAGMA table_info(api_keys)")
-    }
+    api_key_columns = {row["name"] for row in conn.execute("PRAGMA table_info(api_keys)")}
     if "is_internal" not in api_key_columns:
-        conn.execute(
-            "ALTER TABLE api_keys ADD COLUMN is_internal INTEGER NOT NULL DEFAULT 0"
-        )
+        conn.execute("ALTER TABLE api_keys ADD COLUMN is_internal INTEGER NOT NULL DEFAULT 0")
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS app_secrets (
@@ -171,13 +167,9 @@ def get_connection() -> sqlite3.Connection:
         conn.execute(
             "ALTER TABLE auth_user ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0"
         )
-    refresh_columns = {
-        row["name"] for row in conn.execute("PRAGMA table_info(refresh_tokens)")
-    }
+    refresh_columns = {row["name"] for row in conn.execute("PRAGMA table_info(refresh_tokens)")}
     if "is_desktop" not in refresh_columns:
-        conn.execute(
-            "ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0"
-        )
+        conn.execute("ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0")
     conn.commit()
     return conn
 
diff --git a/studio/backend/colab.py b/studio/backend/colab.py
index 1bca16359b..c3a1e03fbe 100644
--- a/studio/backend/colab.py
+++ b/studio/backend/colab.py
@@ -44,12 +44,7 @@ def get_colab_url(port: int = 8888) -> str:
         try:
             url = eval_js(f"google.colab.kernel.proxyPort({port})", timeout_sec = 10)
             # A valid Colab proxy URL starts with https:// and embeds the port.
-            if (
-                url
-                and isinstance(url, str)
-                and url.startswith("https://")
-                and str(port) in url
-            ):
+            if url and isinstance(url, str) and url.startswith("https://") and str(port) in url:
                 return url.rstrip("/")
         except Exception as e:
             logger.info(f"Note: Could not get Colab URL (attempt {attempt + 1}/3: {e})")
@@ -118,11 +113,8 @@ def show_link(port: int = 8888, *, _url: "str | None" = None):
 def _is_studio_healthy(port: int, timeout: float = 2.0) -> bool:
     """Return True if a Studio backend is already answering health checks on *port*."""
     import urllib.request
-
     try:
-        with urllib.request.urlopen(
-            f"http://localhost:{port}/api/health", timeout = timeout
-        ):
+        with urllib.request.urlopen(f"http://localhost:{port}/api/health", timeout = timeout):
             return True
     except Exception:
         return False
@@ -178,7 +170,6 @@ def _show_and_embed(port: int):
         # Fallback: Colab's built-in helper (less control, but always works)
         try:
             from google.colab import output as colab_output
-
             colab_output.serve_kernel_port_as_iframe(port, height = 900, width = "100%")
         except ImportError:
             pass
@@ -200,9 +191,7 @@ def start(port: int = 8888):
     # Re-launching would either collide on the port or silently shift to a new
     # port and confuse the user.  Just re-show the link and iframe instead.
     if _is_studio_healthy(port):
-        logger.info(
-            f"   Studio is already running on port {port} — reusing existing server."
-        )
+        logger.info(f"   Studio is already running on port {port} — reusing existing server.")
         _show_and_embed(port)
         try:
             for _ in range(10000):
@@ -225,9 +214,7 @@ def start(port: int = 8888):
 
     logger.info("   Starting server...")
     try:
-        app = run_server(
-            host = "0.0.0.0", port = port, frontend_path = frontend_path, silent = True
-        )
+        app = run_server(host = "0.0.0.0", port = port, frontend_path = frontend_path, silent = True)
     except SystemExit as exc:
         logger.error(f"❌ Unsloth Studio failed to start: {exc}")
         return
@@ -250,9 +237,7 @@ def start(port: int = 8888):
     server_ready = False
     for _ in range(40):
         try:
-            with urllib.request.urlopen(
-                f"http://localhost:{actual_port}/api/health", timeout = 1
-            ):
+            with urllib.request.urlopen(f"http://localhost:{actual_port}/api/health", timeout = 1):
                 server_ready = True
                 break
         except Exception:
diff --git a/studio/backend/core/__init__.py b/studio/backend/core/__init__.py
index d39815c437..2ba9d5c65c 100644
--- a/studio/backend/core/__init__.py
+++ b/studio/backend/core/__init__.py
@@ -140,7 +140,6 @@ def __getattr__(name):
     # Datasets
     if name == "format_and_template_dataset":
         from utils.datasets import format_and_template_dataset
-
         globals()["format_and_template_dataset"] = format_and_template_dataset
         return format_and_template_dataset
 
diff --git a/studio/backend/core/_torchao_stub.py b/studio/backend/core/_torchao_stub.py
index 5650a60ee2..217c25fda3 100644
--- a/studio/backend/core/_torchao_stub.py
+++ b/studio/backend/core/_torchao_stub.py
@@ -64,7 +64,11 @@ def _make_mod_stub(mod_name):
     m._unsloth_stub = _STUB_SENTINEL
     m.__spec__ = importlib.machinery.ModuleSpec(mod_name, loader = None, is_package = True)
 
-    def _ga(attr, _m = m, _n = mod_name):
+    def _ga(
+        attr,
+        _m = m,
+        _n = mod_name,
+    ):
         if attr.startswith("__"):
             raise AttributeError(attr)
         # Return a stub CLASS (not a module) so that isinstance(x, attr)
@@ -89,7 +93,12 @@ class _StubSubpackageLoader(importlib.abc.Loader):
 
 
 class _StubSubpackageFinder(importlib.abc.MetaPathFinder):
-    def find_spec(self, fullname, path, target = None):
+    def find_spec(
+        self,
+        fullname,
+        path,
+        target = None,
+    ):
         if "." not in fullname:
             return None
         parent = sys.modules.get(fullname.rsplit(".", 1)[0])
@@ -118,7 +127,6 @@ def install_torchao_windows_rocm_stub() -> None:
     if sys.platform == "win32":
         try:
             import torch as _torch_probe
-
             _is_win32_rocm = bool(
                 getattr(getattr(_torch_probe, "version", None), "hip", None)
                 or "rocm" in getattr(_torch_probe, "__version__", "").lower()
diff --git a/studio/backend/core/data_recipe/huggingface.py b/studio/backend/core/data_recipe/huggingface.py
index 16f6b15af5..d5a6db6baf 100644
--- a/studio/backend/core/data_recipe/huggingface.py
+++ b/studio/backend/core/data_recipe/huggingface.py
@@ -36,9 +36,7 @@ def _resolve_recipe_artifact_path(artifact_path: str) -> Path:
     if not resolved.exists():
         raise RecipeDatasetPublishError("Execution artifacts are no longer available.")
     if not resolved.is_dir():
-        raise RecipeDatasetPublishError(
-            "Execution artifact path is not a dataset folder."
-        )
+        raise RecipeDatasetPublishError("Execution artifact path is not a dataset folder.")
 
     return resolved
 
diff --git a/studio/backend/core/data_recipe/jobs/manager.py b/studio/backend/core/data_recipe/jobs/manager.py
index cdc28d9560..75dc1efb9c 100644
--- a/studio/backend/core/data_recipe/jobs/manager.py
+++ b/studio/backend/core/data_recipe/jobs/manager.py
@@ -108,9 +108,7 @@ class Subscription:
             event_id = self._next_id
         body = json.dumps(event, separators = (",", ":"), ensure_ascii = False)
         event_type = event.get("type") or "message"
-        return (
-            f"id: {event_id}\n" f"event: {event_type}\n" f"data: {body}\n\n"
-        ).encode("utf-8")
+        return (f"id: {event_id}\n" f"event: {event_type}\n" f"data: {body}\n\n").encode("utf-8")
 
 
 class JobManager:
@@ -158,9 +156,7 @@ class JobManager:
             job_id = uuid.uuid4().hex
             self._job = Job(job_id = job_id, status = "pending", started_at = time.time())
             self._job.progress_columns_total = llm_column_count
-            self._job.source_progress_estimated_total = _github_source_estimated_total(
-                recipe
-            )
+            self._job.source_progress_estimated_total = _github_source_estimated_total(recipe)
             self._job.internal_api_key_id = internal_api_key_id
             self._events.clear()
             self._seq = 0
@@ -187,9 +183,7 @@ class JobManager:
             self._pump_thread = threading.Thread(target = self._pump_loop, daemon = True)
             self._pump_thread.start()
 
-            self._emit(
-                {"type": EVENT_JOB_ENQUEUED, "ts": time.time(), "job_id": job_id}
-            )
+            self._emit({"type": EVENT_JOB_ENQUEUED, "ts": time.time(), "job_id": job_id})
             return job_id
 
     def cancel(self, job_id: str) -> bool:
@@ -200,9 +194,7 @@ class JobManager:
             if self._proc is None or not self._proc.is_alive():
                 return True
             self._job.status = "cancelling"
-            self._emit(
-                {"type": EVENT_JOB_CANCELLING, "ts": time.time(), "job_id": job_id}
-            )
+            self._emit({"type": EVENT_JOB_CANCELLING, "ts": time.time(), "job_id": job_id})
             try:
                 self._proc.terminate()
             except (AttributeError, OSError):
@@ -319,19 +311,12 @@ class JobManager:
             if not parquet_dir.exists():
                 return {"error": f"dataset path missing: {parquet_dir}"}
 
-            return self._load_dataset_page(
-                parquet_dir = parquet_dir, limit = limit, offset = offset
-            )
+            return self._load_dataset_page(parquet_dir = parquet_dir, limit = limit, offset = offset)
         except Exception as exc:
             return {"error": f"dataset load failed: {exc}"}
 
     @staticmethod
-    def _load_dataset_page(
-        *,
-        parquet_dir: Path,
-        limit: int,
-        offset: int,
-    ) -> dict[str, Any]:
+    def _load_dataset_page(*, parquet_dir: Path, limit: int, offset: int) -> dict[str, Any]:
         dataset_page = JobManager._load_dataset_page_with_duckdb(
             parquet_dir = parquet_dir,
             limit = limit,
@@ -347,10 +332,7 @@ class JobManager:
 
     @staticmethod
     def _load_dataset_page_with_duckdb(
-        *,
-        parquet_dir: Path,
-        limit: int,
-        offset: int,
+        *, parquet_dir: Path, limit: int, offset: int
     ) -> dict[str, Any] | None:
         parquet_glob = str((parquet_dir / "*.parquet").resolve())
         try:
@@ -389,10 +371,7 @@ class JobManager:
 
     @staticmethod
     def _load_dataset_page_with_data_designer(
-        *,
-        parquet_dir: Path,
-        limit: int,
-        offset: int,
+        *, parquet_dir: Path, limit: int, offset: int
     ) -> dict[str, Any]:
         from data_designer.config.utils.io_helpers import read_parquet_dataset
 
@@ -402,7 +381,10 @@ class JobManager:
         return {"dataset": to_preview_jsonable(rows), "total": total}
 
     def subscribe(
-        self, job_id: str, *, after_seq: int | None = None
+        self,
+        job_id: str,
+        *,
+        after_seq: int | None = None,
     ) -> Subscription | None:
         """SSE subscribe: get replay buffer + live events stream."""
         with self._lock:
@@ -497,9 +479,7 @@ class JobManager:
                         self._job.error = self._job.error or "process exited"
                     self._job.finished_at = time.time()
                     event_type = (
-                        EVENT_JOB_CANCELLED
-                        if self._job.status == "cancelled"
-                        else EVENT_JOB_ERROR
+                        EVENT_JOB_CANCELLED if self._job.status == "cancelled" else EVENT_JOB_ERROR
                     )
                     self._emit(
                         {
@@ -566,7 +546,6 @@ class JobManager:
             return
         try:
             from auth import storage  # deferred: avoids circular import
-
             storage.revoke_internal_api_key(int(key_id))
         except Exception:
             pass
diff --git a/studio/backend/core/data_recipe/jobs/parse.py b/studio/backend/core/data_recipe/jobs/parse.py
index cea6d8ea64..8ca3702edd 100644
--- a/studio/backend/core/data_recipe/jobs/parse.py
+++ b/studio/backend/core/data_recipe/jobs/parse.py
@@ -119,8 +119,7 @@ def parse_log_message(msg: str) -> ParsedUpdate | None:
                 page_items = page_items,
                 rate_remaining = int(m.group("remaining")),
                 message = (
-                    f"Scraping GitHub source: {repo} "
-                    f"{resource} page {page} (+{page_items})"
+                    f"Scraping GitHub source: {repo} " f"{resource} page {page} (+{page_items})"
                 ),
             ),
         )
@@ -134,10 +133,7 @@ def parse_log_message(msg: str) -> ParsedUpdate | None:
                 source = "github",
                 status = "rate_limited",
                 retry_after_sec = seconds,
-                message = (
-                    "Waiting for GitHub rate limit. "
-                    "Studio will resume automatically."
-                ),
+                message = ("Waiting for GitHub rate limit. Studio will resume automatically."),
             ),
         )
 
@@ -151,8 +147,7 @@ def parse_log_message(msg: str) -> ParsedUpdate | None:
                 status = "rate_limited",
                 retry_after_sec = seconds,
                 message = (
-                    "Waiting for GitHub secondary rate limit. "
-                    "Studio will resume automatically."
+                    "Waiting for GitHub secondary rate limit. Studio will resume automatically."
                 ),
             ),
         )
@@ -166,10 +161,7 @@ def parse_log_message(msg: str) -> ParsedUpdate | None:
                 source = "github",
                 status = "rate_limited",
                 retry_after_sec = seconds,
-                message = (
-                    "Waiting for GitHub rate limit. "
-                    "Studio will resume automatically."
-                ),
+                message = ("Waiting for GitHub rate limit. Studio will resume automatically."),
             ),
         )
 
@@ -387,15 +379,13 @@ def _apply_source_progress(job: Job, progress: SourceProgress) -> None:
         count_key = f"{progress.repo}:{progress.resource}"
         if page_key not in job._source_seen_pages:
             job._source_seen_pages.add(page_key)
-            job._source_counts[count_key] = int(
-                job._source_counts.get(count_key, 0)
-            ) + int(page_items or 0)
+            job._source_counts[count_key] = int(job._source_counts.get(count_key, 0)) + int(
+                page_items or 0
+            )
 
     fetched_items = sum(job._source_counts.values())
     if fetched_items <= 0:
-        fetched_items = progress.fetched_items or (
-            previous.fetched_items if previous else None
-        )
+        fetched_items = progress.fetched_items or (previous.fetched_items if previous else None)
 
     estimated_total = (
         progress.estimated_total
@@ -415,14 +405,10 @@ def _apply_source_progress(job: Job, progress: SourceProgress) -> None:
         repo = progress.repo or (previous.repo if previous else None),
         resource = progress.resource or (previous.resource if previous else None),
         page = (
-            progress.page
-            if progress.page is not None
-            else (previous.page if previous else None)
+            progress.page if progress.page is not None else (previous.page if previous else None)
         ),
         page_items = (
-            page_items
-            if page_items is not None
-            else (previous.page_items if previous else None)
+            page_items if page_items is not None else (previous.page_items if previous else None)
         ),
         fetched_items = fetched_items,
         estimated_total = estimated_total,
@@ -453,9 +439,7 @@ def _compute_overall_progress(job: Job, column_progress: Progress) -> Progress:
     if len(job._column_done) == 0:
         done = current_done
     else:
-        sum_done = sum(
-            max(0, min(value, total_rows)) for value in job._column_done.values()
-        )
+        sum_done = sum(max(0, min(value, total_rows)) for value in job._column_done.values())
         done = int(sum_done / total_columns)
 
     prev_done = int(job.progress.done or 0)
diff --git a/studio/backend/core/data_recipe/jobs/worker.py b/studio/backend/core/data_recipe/jobs/worker.py
index 8c5c7fe657..f59538769e 100644
--- a/studio/backend/core/data_recipe/jobs/worker.py
+++ b/studio/backend/core/data_recipe/jobs/worker.py
@@ -60,9 +60,7 @@ def _slugify_run_name(value: str) -> str:
     return slug[:80].strip("-")
 
 
-def _build_dataset_name(
-    *, run_name: str | None, job_id: str, artifact_root: Path
-) -> str:
+def _build_dataset_name(*, run_name: str | None, job_id: str, artifact_root: Path) -> str:
     fallback = f"recipe_{job_id}"
     slug = _slugify_run_name(run_name or "")
     base_name = f"recipe_{slug}" if slug else fallback
@@ -74,21 +72,14 @@ def _build_dataset_name(
     return candidate
 
 
-def run_job_process(
-    *,
-    event_queue,
-    recipe: dict[str, Any],
-    run: dict[str, Any],
-) -> None:
+def run_job_process(*, event_queue, recipe: dict[str, Any], run: dict[str, Any]) -> None:
     """
     Subprocess entrypoint.
     Sends events to `event_queue`.
     """
     import os
 
-    os.environ["PYTHONWARNINGS"] = (
-        "ignore"  # Suppress warnings at C-level before imports
-    )
+    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
 
     import warnings
     from loggers.config import LogConfig
@@ -172,14 +163,10 @@ def run_job_process(
                 }
             )
         else:
-            results = designer.create(
-                builder, num_records = rows, dataset_name = dataset_name
-            )
+            results = designer.create(builder, num_records = rows, dataset_name = dataset_name)
             analysis = to_jsonable(results.load_analysis().model_dump(mode = "json"))
             if merge_batches:
-                _merge_batches_to_single_parquet(
-                    results.artifact_storage.base_dataset_path
-                )
+                _merge_batches_to_single_parquet(results.artifact_storage.base_dataset_path)
             artifact_path = str(results.artifact_storage.base_dataset_path)
             event_queue.put(
                 {
diff --git a/studio/backend/core/data_recipe/jsonable.py b/studio/backend/core/data_recipe/jsonable.py
index 8bec60cf82..5a4fcd35c3 100644
--- a/studio/backend/core/data_recipe/jsonable.py
+++ b/studio/backend/core/data_recipe/jsonable.py
@@ -23,7 +23,6 @@ def _pil_to_preview_payload(image: Any) -> dict[str, Any]:
 
 def _open_pil_image_from_bytes(raw_bytes: bytes):
     from PIL import Image  # type: ignore
-
     with Image.open(io.BytesIO(raw_bytes)) as image:
         return image.copy()
 
@@ -52,7 +51,6 @@ def _to_pil_from_hf_image_dict(value: Any) -> Any | None:
     if isinstance(path_value, str) and path_value.strip():
         try:
             from PIL import Image  # type: ignore
-
             with Image.open(Path(path_value)) as image:
                 return image.copy()
         except (OSError, ValueError, TypeError):
diff --git a/studio/backend/core/data_recipe/local_callable_validators.py b/studio/backend/core/data_recipe/local_callable_validators.py
index 44459e88c5..a40261fa92 100644
--- a/studio/backend/core/data_recipe/local_callable_validators.py
+++ b/studio/backend/core/data_recipe/local_callable_validators.py
@@ -81,9 +81,7 @@ def split_oxc_local_callable_validators(
 
 
 def register_oxc_local_callable_validators(
-    *,
-    builder,
-    specs: list[OxcLocalCallableValidatorSpec],
+    *, builder, specs: list[OxcLocalCallableValidatorSpec]
 ) -> None:
     if not specs:
         return
@@ -114,10 +112,7 @@ def register_oxc_local_callable_validators(
         )
 
 
-def _parse_oxc_spec(
-    *,
-    column: dict[str, Any],
-) -> OxcLocalCallableValidatorSpec | None:
+def _parse_oxc_spec(*, column: dict[str, Any]) -> OxcLocalCallableValidatorSpec | None:
     if str(column.get("column_type") or "").strip() != "validation":
         return None
     if str(column.get("validator_type") or "").strip() != "local_callable":
@@ -138,11 +133,7 @@ def _parse_oxc_spec(
 
     target_columns_raw = column.get("target_columns")
     target_columns = (
-        [
-            value.strip()
-            for value in target_columns_raw
-            if isinstance(value, str) and value.strip()
-        ]
+        [value.strip() for value in target_columns_raw if isinstance(value, str) and value.strip()]
         if isinstance(target_columns_raw, list)
         else []
     )
@@ -182,9 +173,7 @@ def _parse_oxc_validation_marker(fn_name: str) -> tuple[str, str, str]:
         return "javascript", "syntax", "auto"
     code_lang = parts[0] if parts[0] in _OXC_LANG_TO_NODE_LANG else "javascript"
     mode = parts[1] if parts[1] in _OXC_VALIDATION_MODES else "syntax"
-    code_shape = (
-        parts[2] if len(parts) >= 3 and parts[2] in _OXC_CODE_SHAPES else "auto"
-    )
+    code_shape = parts[2] if len(parts) >= 3 and parts[2] in _OXC_CODE_SHAPES else "auto"
     return code_lang, mode, code_shape
 
 
@@ -205,10 +194,7 @@ def _build_oxc_validation_function(lang: str, validation_mode: str, code_shape:
         code_values = (
             ["" for _ in range(row_count)]
             if not code_column
-            else [
-                "" if value is None else str(value)
-                for value in df[code_column].tolist()
-            ]
+            else ["" if value is None else str(value) for value in df[code_column].tolist()]
         )
 
         results = _run_oxc_batch(
@@ -224,16 +210,14 @@ def _build_oxc_validation_function(lang: str, validation_mode: str, code_shape:
             )
         return pd.DataFrame(results)
 
-    _validator.__name__ = f"{OXC_VALIDATION_FN_MARKER}_{node_lang}_{mode.replace('+', '_')}_{normalized_code_shape}"
+    _validator.__name__ = (
+        f"{OXC_VALIDATION_FN_MARKER}_{node_lang}_{mode.replace('+', '_')}_{normalized_code_shape}"
+    )
     return _validator
 
 
 def _run_oxc_batch(
-    *,
-    node_lang: str,
-    validation_mode: str,
-    code_shape: str,
-    code_values: list[str],
+    *, node_lang: str, validation_mode: str, code_shape: str, code_values: list[str]
 ) -> list[dict[str, Any]]:
     if not _OXC_RUNNER_PATH.exists():
         return _fallback_results(
@@ -308,21 +292,13 @@ def _run_oxc_batch(
         warning_count_raw = item.get("warning_count")
         out.append(
             {
-                "is_valid": bool(is_valid_raw)
-                if isinstance(is_valid_raw, bool)
-                else False,
-                "error_count": int(error_count_raw)
-                if isinstance(error_count_raw, int)
-                else 0,
+                "is_valid": bool(is_valid_raw) if isinstance(is_valid_raw, bool) else False,
+                "error_count": int(error_count_raw) if isinstance(error_count_raw, int) else 0,
                 "error_message": str(message_raw or ""),
-                "severity": str(severity_raw)
-                if isinstance(severity_raw, str)
-                else None,
+                "severity": str(severity_raw) if isinstance(severity_raw, str) else None,
                 "code": str(code_raw) if isinstance(code_raw, str) else None,
                 "labels": labels_raw if isinstance(labels_raw, list) else [],
-                "codeframe": str(codeframe_raw)
-                if isinstance(codeframe_raw, str)
-                else None,
+                "codeframe": str(codeframe_raw) if isinstance(codeframe_raw, str) else None,
                 "warning_count": int(warning_count_raw)
                 if isinstance(warning_count_raw, int)
                 else 0,
diff --git a/studio/backend/core/data_recipe/service.py b/studio/backend/core/data_recipe/service.py
index 85b567885f..cb5901f04e 100644
--- a/studio/backend/core/data_recipe/service.py
+++ b/studio/backend/core/data_recipe/service.py
@@ -22,9 +22,7 @@ def _encode_bytes_to_base64(value: bytes | bytearray) -> str:
     return base64.b64encode(bytes(value)).decode("utf-8")
 
 
-def _load_image_file_to_base64(
-    path_value: str, *, base_path: str | None = None
-) -> str | None:
+def _load_image_file_to_base64(path_value: str, *, base_path: str | None = None) -> str | None:
     try:
         path = Path(path_value)
         candidates: list[Path] = []
@@ -119,9 +117,7 @@ def _apply_data_designer_image_context_patch() -> None:
 
     original_auto_resolve = ImageContext._auto_resolve_context_value
 
-    def _patched_auto_resolve(
-        self: Any, context_value: Any, base_path: str | None
-    ) -> Any:
+    def _patched_auto_resolve(self: Any, context_value: Any, base_path: str | None) -> Any:
         normalized = _normalize_image_context_value(context_value, base_path = base_path)
         return original_auto_resolve(self, normalized, base_path)
 
@@ -163,17 +159,12 @@ def _recipe_has_llm_columns(recipe: dict[str, Any]) -> bool:
     return False
 
 
-def _validate_recipe_runtime_support(
-    recipe: dict[str, Any],
-    model_providers: list[Any],
-) -> None:
+def _validate_recipe_runtime_support(recipe: dict[str, Any], model_providers: list[Any]) -> None:
     if _recipe_has_llm_columns(recipe) and not model_providers:
         raise ValueError("Add a Provider connection block before running this recipe.")
 
 
-def build_mcp_providers(
-    recipe: dict[str, Any],
-) -> list:
+def build_mcp_providers(recipe: dict[str, Any]) -> list:
     from data_designer.config.mcp import LocalStdioMCPProvider, MCPProvider  # pyright: ignore[reportMissingImports]
 
     # Same gate as the chat MCP path: stdio providers spawn a local subprocess,
@@ -259,9 +250,7 @@ def build_config_builder(recipe: dict[str, Any]):
         if key not in {"model_providers", "mcp_providers"}
     }
     recipe_core = _strip_frontend_model_config_metadata(recipe_core)
-    recipe_core, oxc_local_callable_specs = split_oxc_local_callable_validators(
-        recipe_core
-    )
+    recipe_core, oxc_local_callable_specs = split_oxc_local_callable_validators(recipe_core)
     builder = DataDesignerConfigBuilder.from_config({"data_designer": recipe_core})
     register_oxc_local_callable_validators(
         builder = builder,
@@ -285,11 +274,7 @@ def build_config_builder(recipe: dict[str, Any]):
     return builder
 
 
-def create_data_designer(
-    recipe: dict[str, Any],
-    *,
-    artifact_path: str | None = None,
-):
+def create_data_designer(recipe: dict[str, Any], *, artifact_path: str | None = None):
     _apply_data_designer_image_context_patch()
     from data_designer.interface.data_designer import DataDesigner  # pyright: ignore[reportMissingImports]
 
@@ -302,7 +287,6 @@ def create_data_designer(
     # so sampler/expression-only recipes can run without a real provider.
     if not model_providers:
         from data_designer.config.models import ModelProvider  # pyright: ignore[reportMissingImports]
-
         model_providers = [
             ModelProvider(
                 name = "_unused",
@@ -326,8 +310,7 @@ def validate_recipe(recipe: dict[str, Any]) -> None:
 
 
 def preview_recipe(
-    recipe: dict[str, Any],
-    num_records: int,
+    recipe: dict[str, Any], num_records: int
 ) -> tuple[list[dict[str, Any]], dict[str, Any] | None, dict[str, Any] | None]:
     builder = build_config_builder(recipe)
     designer = create_data_designer(recipe)
@@ -339,14 +322,10 @@ def preview_recipe(
         dataset = [to_jsonable(row) for row in raw_rows]
 
     artifacts = (
-        None
-        if results.processor_artifacts is None
-        else to_jsonable(results.processor_artifacts)
+        None if results.processor_artifacts is None else to_jsonable(results.processor_artifacts)
     )
     analysis = (
-        None
-        if results.analysis is None
-        else to_jsonable(results.analysis.model_dump(mode = "json"))
+        None if results.analysis is None else to_jsonable(results.analysis.model_dump(mode = "json"))
     )
 
     return dataset, artifacts, analysis
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 7cabd382eb..e74dc13e8a 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -58,16 +58,11 @@ def _apply_wsl_sudo_patch():
         import unsloth_zoo.llama_cpp as llama_cpp_module
 
         def _wsl_do_we_need_sudo(system_type = "debian"):
-            logger.info(
-                "WSL detected — skipping sudo check "
-                "(build deps pre-installed by setup.sh)"
-            )
+            logger.info("WSL detected — skipping sudo check (build deps pre-installed by setup.sh)")
             return False
 
         llama_cpp_module.do_we_need_sudo = _wsl_do_we_need_sudo
-        logger.info(
-            "Applied WSL sudo patch to " "unsloth_zoo.llama_cpp.do_we_need_sudo"
-        )
+        logger.info("Applied WSL sudo patch to unsloth_zoo.llama_cpp.do_we_need_sudo")
     except Exception as e:
         logger.warning(f"Could not apply WSL sudo patch: {e}")
 
@@ -146,7 +141,6 @@ class ExportBackend:
             List of tuples: [(model_name, [(display_name, checkpoint_path), ...]), ...]
         """
         from utils.models.checkpoints import scan_checkpoints
-
         return scan_checkpoints(outputs_dir = outputs_dir)
 
     def load_checkpoint(
@@ -224,7 +218,6 @@ class ExportBackend:
 
             elif self._audio_type == "bicodec":
                 from unsloth import FastModel
-
                 logger.info("Loading as BiCodec (Spark-TTS) audio model...")
                 model, tokenizer = FastModel.from_pretrained(
                     model_name = checkpoint_path,
@@ -236,7 +229,6 @@ class ExportBackend:
 
             elif self._audio_type == "dac":
                 from unsloth import FastModel
-
                 logger.info("Loading as DAC (OuteTTS) audio model...")
                 model, tokenizer = FastModel.from_pretrained(
                     model_name = checkpoint_path,
@@ -348,9 +340,7 @@ class ExportBackend:
         output_path: Optional[str] = None
         try:
             if _IS_MLX:
-                mlx_save_method = (
-                    "merged_4bit" if format_type == "4-bit (FP4)" else "merged_16bit"
-                )
+                mlx_save_method = "merged_4bit" if format_type == "4-bit (FP4)" else "merged_16bit"
             else:
                 if format_type == "4-bit (FP4)":
                     save_method = "merged_4bit_forced"
@@ -415,9 +405,7 @@ class ExportBackend:
                                 private = private,
                             )
                 else:
-                    hub_save_method = (
-                        save_method if save_method is not None else "merged_16bit"
-                    )
+                    hub_save_method = save_method if save_method is not None else "merged_16bit"
                     self.current_model.push_to_hub_merged(
                         repo_id,
                         self.current_tokenizer,
@@ -523,9 +511,7 @@ class ExportBackend:
                 else:
                     # Get base model name from request or model config
                     base_model = (
-                        base_model_id
-                        or self.current_model.config._name_or_path
-                        or "unknown"
+                        base_model_id or self.current_model.config._name_or_path or "unknown"
                     )
 
                     # Create repo
@@ -547,9 +533,7 @@ class ExportBackend:
                         extra = "unsloth",
                     )
                     card = ModelCard(content)
-                    card.push_to_hub(
-                        repo_id, token = hf_token, commit_message = "Unsloth Model Card"
-                    )
+                    card.push_to_hub(repo_id, token = hf_token, commit_message = "Unsloth Model Card")
 
                     # Upload model files
                     if save_directory:
@@ -614,10 +598,7 @@ class ExportBackend:
                     LLAMA_CPP_DEFAULT_DIR,
                     _resolve_local_convert_script,  # noqa: F401
                 )
-
-                os.environ.setdefault(
-                    "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR
-                )
+                os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
             except ImportError:
                 if not _LLAMA_CPP_SCRIPTS_WARNING_EMITTED:
                     logger.warning(
@@ -663,15 +644,11 @@ class ExportBackend:
                 # Relocate GGUF artifacts into the export directory.
                 # convert_to_gguf writes .gguf files to cwd (repo root)
                 # because --outfile is a relative path like "model.Q4_K_M.gguf".
-                new_ggufs = (
-                    set(glob.glob(os.path.join(cwd, "*.gguf"))) - pre_existing_ggufs
-                )
+                new_ggufs = set(glob.glob(os.path.join(cwd, "*.gguf"))) - pre_existing_ggufs
                 for src in sorted(new_ggufs):
                     dest = os.path.join(abs_save_dir, os.path.basename(src))
                     shutil.move(src, dest)
-                    logger.info(
-                        f"Relocated GGUF: {os.path.basename(src)} → {abs_save_dir}/"
-                    )
+                    logger.info(f"Relocated GGUF: {os.path.basename(src)} → {abs_save_dir}/")
 
                 # Flatten any .gguf files from subdirectories into abs_save_dir.
                 # save_pretrained_gguf may create subdirs (e.g. model_gguf/)
@@ -701,9 +678,7 @@ class ExportBackend:
                         # Also relocate Ollama Modelfile if present
                         modelfile = gguf_dir / "Modelfile"
                         if modelfile.is_file():
-                            shutil.move(
-                                str(modelfile), os.path.join(abs_save_dir, "Modelfile")
-                            )
+                            shutil.move(str(modelfile), os.path.join(abs_save_dir, "Modelfile"))
                             logger.info(f"Relocated Modelfile → {abs_save_dir}/")
                         shutil.rmtree(str(gguf_dir), ignore_errors = True)
                         logger.info(f"Cleaned up intermediate GGUF dir: {gguf_dir}")
@@ -814,12 +789,8 @@ class ExportBackend:
                             repo_type = "model",
                         )
                 else:
-                    self.current_model.push_to_hub(
-                        repo_id, token = hf_token, private = private
-                    )
-                    self.current_tokenizer.push_to_hub(
-                        repo_id, token = hf_token, private = private
-                    )
+                    self.current_model.push_to_hub(repo_id, token = hf_token, private = private)
+                    self.current_tokenizer.push_to_hub(repo_id, token = hf_token, private = private)
                 logger.info(f"Adapter pushed successfully to {repo_id}")
 
             return True, "LoRA adapter exported successfully", output_path
diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.py
index 82de925592..90a946163e 100644
--- a/studio/backend/core/export/orchestrator.py
+++ b/studio/backend/core/export/orchestrator.py
@@ -261,7 +261,11 @@ class ExportOrchestrator:
         except (EOFError, OSError, ValueError):
             return None
 
-    def _wait_response(self, expected_type: str, timeout: float = 3600.0) -> dict:
+    def _wait_response(
+        self,
+        expected_type: str,
+        timeout: float = 3600.0,
+    ) -> dict:
         """Block until a response of the expected type arrives.
 
         Export operations can take a very long time — GGUF conversion for
@@ -318,9 +322,7 @@ class ExportOrchestrator:
                 expected_type,
             )
 
-        raise RuntimeError(
-            f"Timeout waiting for '{expected_type}' response after {timeout}s"
-        )
+        raise RuntimeError(f"Timeout waiting for '{expected_type}' response after {timeout}s")
 
     def _drain_queue(self) -> list:
         """Drain all pending responses."""
@@ -371,9 +373,7 @@ class ExportOrchestrator:
                 elif self._proc is not None:
                     self._shutdown_subprocess(timeout = 2)
 
-                logger.info(
-                    "Spawning fresh export subprocess for '%s'", checkpoint_path
-                )
+                logger.info("Spawning fresh export subprocess for '%s'", checkpoint_path)
                 self._spawn_subprocess(sub_config)
 
                 try:
@@ -485,9 +485,7 @@ class ExportOrchestrator:
             },
         )
 
-    def _run_export(
-        self, export_type: str, params: dict
-    ) -> Tuple[bool, str, Optional[str]]:
+    def _run_export(self, export_type: str, params: dict) -> Tuple[bool, str, Optional[str]]:
         """Send an export command to the subprocess and wait for result.
 
         Returns ``(success, message, output_path)``. ``output_path`` is the
@@ -554,12 +552,9 @@ class ExportOrchestrator:
             finally:
                 self._export_active = False
 
-    def scan_checkpoints(
-        self, outputs_dir: str = str(outputs_root())
-    ) -> List[Tuple[str, list]]:
+    def scan_checkpoints(self, outputs_dir: str = str(outputs_root())) -> List[Tuple[str, list]]:
         """Scan for checkpoints — no ML imports needed, runs locally."""
         from utils.models.checkpoints import scan_checkpoints
-
         return scan_checkpoints(outputs_dir = outputs_dir)
 
 
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index defcff924b..405956ec9d 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -362,12 +362,7 @@ def _handle_cleanup(backend, resp_queue: Any) -> None:
         )
 
 
-def run_export_process(
-    *,
-    cmd_queue: Any,
-    resp_queue: Any,
-    config: dict,
-) -> None:
+def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None:
     """Subprocess entrypoint. Persistent — runs command loop until shutdown.
 
     Args:
@@ -383,9 +378,7 @@ def run_export_process(
     _setup_log_capture(resp_queue)
 
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
-    os.environ["PYTHONWARNINGS"] = (
-        "ignore"  # Suppress warnings at C-level before imports
-    )
+    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
     # Force unbuffered output from any child Python process (e.g. the
     # GGUF converter) so their prints surface in the log stream as they
     # happen rather than at the end.
@@ -430,7 +423,6 @@ def run_export_process(
     if sys.platform == "win32":
         try:
             import triton  # noqa: F401
-
             logger.info("Triton available — torch.compile enabled")
         except ImportError:
             os.environ["TORCHDYNAMO_DISABLE"] = "1"
@@ -467,9 +459,7 @@ def run_export_process(
 
         import transformers
 
-        logger.info(
-            "Export subprocess loaded transformers %s", transformers.__version__
-        )
+        logger.info("Export subprocess loaded transformers %s", transformers.__version__)
 
     except Exception as exc:
         _send_response(
@@ -570,9 +560,7 @@ def run_export_process(
                 )
 
         except Exception as exc:
-            logger.error(
-                "Error handling command '%s': %s", cmd_type, exc, exc_info = True
-            )
+            logger.error("Error handling command '%s': %s", cmd_type, exc, exc_info = True)
             _send_response(
                 resp_queue,
                 {
diff --git a/studio/backend/core/inference/anthropic_compat.py b/studio/backend/core/inference/anthropic_compat.py
index cdb0fdebff..61dea5c010 100644
--- a/studio/backend/core/inference/anthropic_compat.py
+++ b/studio/backend/core/inference/anthropic_compat.py
@@ -42,8 +42,7 @@ def _anthropic_image_block_to_openai_part(block: dict) -> Optional[dict]:
 
 
 def anthropic_messages_to_openai(
-    messages: list[dict],
-    system: Optional[Union[str, list]] = None,
+    messages: list[dict], system: Optional[Union[str, list]] = None
 ) -> list[dict]:
     """Convert Anthropic messages + system to OpenAI-format message dicts.
 
@@ -125,9 +124,7 @@ def anthropic_messages_to_openai(
                     tc = b.get("content", "")
                     if isinstance(tc, list):
                         tc = " ".join(
-                            p["text"]
-                            for p in tc
-                            if isinstance(p, dict) and p.get("type") == "text"
+                            p["text"] for p in tc if isinstance(p, dict) and p.get("type") == "text"
                         )
                     tool_results.append(
                         {
diff --git a/studio/backend/core/inference/audio_codecs.py b/studio/backend/core/inference/audio_codecs.py
index df3bf27c16..e6b7f9c613 100644
--- a/studio/backend/core/inference/audio_codecs.py
+++ b/studio/backend/core/inference/audio_codecs.py
@@ -77,12 +77,14 @@ class AudioCodecManager:
             return
         from snac import SNAC
 
-        self._snac_model = (
-            SNAC.from_pretrained("hubertsiuzdak/snac_24khz").to(device).eval()
-        )
+        self._snac_model = SNAC.from_pretrained("hubertsiuzdak/snac_24khz").to(device).eval()
         logger.info("Loaded SNAC codec (24kHz)")
 
-    def _load_bicodec(self, device: str, model_repo_path: Optional[str] = None) -> None:
+    def _load_bicodec(
+        self,
+        device: str,
+        model_repo_path: Optional[str] = None,
+    ) -> None:
         if self._bicodec_tokenizer is not None:
             return
         import os
@@ -90,9 +92,7 @@ class AudioCodecManager:
 
         # Clone SparkAudio/Spark-TTS GitHub repo for the sparktts Python package
         # (same approach as training — the HF model repos don't contain the package)
-        spark_code_dir = os.path.join(
-            os.path.dirname(model_repo_path or "."), "Spark-TTS"
-        )
+        spark_code_dir = os.path.join(os.path.dirname(model_repo_path or "."), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
             logger.info(f"Cloning SparkAudio/Spark-TTS to {spark_code_dir}...")
@@ -177,9 +177,7 @@ class AudioCodecManager:
 
     # ── Decoders ─────────────────────────────────────────────────
 
-    def decode_snac(
-        self, generated_ids: torch.Tensor, device: str
-    ) -> Tuple[bytes, int]:
+    def decode_snac(self, generated_ids: torch.Tensor, device: str) -> Tuple[bytes, int]:
         """
         Decode SNAC tokens (Orpheus) into WAV bytes.
 
@@ -195,9 +193,7 @@ class AudioCodecManager:
             cropped = generated_ids[:, token_indices[1][-1] + 1 :]
         else:
             # Gracefully fall back to using entire output if marker not found
-            logger.warning(
-                "No START_OF_SPEECH token (128257) found — using full generated output"
-            )
+            logger.warning("No START_OF_SPEECH token (128257) found — using full generated output")
             cropped = generated_ids
         row = cropped[0]
 
@@ -223,8 +219,7 @@ class AudioCodecManager:
             layer_3.append(codes[7 * i + 6] - 24576)
 
         snac_codes = [
-            torch.tensor(layer).unsqueeze(0).to(device)
-            for layer in [layer_1, layer_2, layer_3]
+            torch.tensor(layer).unsqueeze(0).to(device) for layer in [layer_1, layer_2, layer_3]
         ]
 
         with torch.no_grad():
@@ -254,16 +249,12 @@ class AudioCodecManager:
             f"BiCodec decode: {len(global_matches)} global tokens, {len(semantic_matches)} semantic tokens"
         )
         if len(global_matches) < 10:
-            logger.info(
-                f"BiCodec generated text (first 500 chars): {generated_text[:500]}"
-            )
+            logger.info(f"BiCodec generated text (first 500 chars): {generated_text[:500]}")
 
         if not semantic_matches:
             raise ValueError("No bicodec_semantic tokens found in generated output")
 
-        semantic_ids = (
-            torch.tensor([int(t) for t in semantic_matches]).long().unsqueeze(0)
-        )
+        semantic_ids = torch.tensor([int(t) for t in semantic_matches]).long().unsqueeze(0)
 
         # Speaker encoder expects exactly 32 global tokens (token_num=32 in BiCodec config).
         # Pad with zeros or truncate to 32.
diff --git a/studio/backend/core/inference/chat_template_helpers.py b/studio/backend/core/inference/chat_template_helpers.py
index 833a714ee4..c70e9b3c53 100644
--- a/studio/backend/core/inference/chat_template_helpers.py
+++ b/studio/backend/core/inference/chat_template_helpers.py
@@ -55,6 +55,4 @@ def apply_chat_template_for_generation(
             break
     if last_exc is not None:
         raise last_exc
-    raise RuntimeError(
-        "apply_chat_template_for_generation: no attempt produced a result"
-    )
+    raise RuntimeError("apply_chat_template_for_generation: no attempt produced a result")
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index 8a1edd608b..3142434d09 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -65,9 +65,7 @@ def _is_openai_family_cloud(base_url: Optional[str]) -> bool:
     return host == "api.openai.com" or host.endswith(".openai.azure.com")
 
 
-_ANTHROPIC_4_7_SAMPLING_REMOVED = re.compile(
-    r"^claude-(?:opus|sonnet|haiku)-4-7(?:[-.]|$)"
-)
+_ANTHROPIC_4_7_SAMPLING_REMOVED = re.compile(r"^claude-(?:opus|sonnet|haiku)-4-7(?:[-.]|$)")
 _OPENAI_REASONING_SUMMARY_UNSUPPORTED = re.compile(r"^o3(?:[-.]|$)")
 _OPENAI_REASONING_STATUSES = {"in_progress", "completed", "incomplete"}
 
@@ -77,9 +75,7 @@ def _openai_image_replay_requires_reasoning(model: str) -> bool:
     return normalized.startswith("gpt-5") or normalized.startswith("o")
 
 
-def _sanitize_openai_reasoning_replay_item(
-    item: Any,
-) -> Optional[dict[str, Any]]:
+def _sanitize_openai_reasoning_replay_item(item: Any) -> Optional[dict[str, Any]]:
     """Return a Responses input-safe reasoning item, if ``item`` is one.
 
     OpenAI's image-generation docs allow follow-up edits by sending the
@@ -128,9 +124,7 @@ _OPENAI_CITATION_MARKER = re.compile(
 )
 
 
-def _build_citation_lookup(
-    url_citations: list[dict[str, Any]],
-) -> dict[str, tuple[int, str]]:
+def _build_citation_lookup(url_citations: list[dict[str, Any]]) -> dict[str, tuple[int, str]]:
     """Map every known ``source_id`` alias to ``(citation_index, url)``.
 
     Accepts singular ``source_id`` and plural ``source_ids``. First-seen
@@ -153,10 +147,7 @@ def _build_citation_lookup(
     return by_source
 
 
-def _replace_openai_citation_markers(
-    text: str,
-    url_citations: list[dict[str, Any]],
-) -> str:
+def _replace_openai_citation_markers(text: str, url_citations: list[dict[str, Any]]) -> str:
     """Rewrite `\\ue200cite\\ue202SOURCE_ID[\\ue202LOCATOR]\\ue201` markers into
     `[[N]](URL)` per resolvable id. Multi-source markers expand to one link
     per id; unresolved tokens drop silently. Idempotent on text without
@@ -185,8 +176,7 @@ def _replace_openai_citation_markers(
 
 
 def _rewrite_citation_markers_partial(
-    text: str,
-    url_citations: list[dict[str, Any]],
+    text: str, url_citations: list[dict[str, Any]]
 ) -> tuple[str, bool]:
     """Like ``_replace_openai_citation_markers`` but also reports whether
     any marker referenced a source_id not yet in ``url_citations``.
@@ -366,9 +356,7 @@ def _anthropic_supports_compaction(model: str) -> bool:
 def _anthropic_supports_fast_mode(model: str) -> bool:
     # Require a family boundary ("" or "-") after the prefix so IDs like
     # "claude-opus-4-70" / "claude-opus-4-7b" do not match.
-    return any(
-        model == p or model.startswith(f"{p}-") for p in _ANTHROPIC_FAST_MODE_PREFIXES
-    )
+    return any(model == p or model.startswith(f"{p}-") for p in _ANTHROPIC_FAST_MODE_PREFIXES)
 
 
 # Cap on ``cited_text`` forwarded in document_citations tool_events;
@@ -632,9 +620,7 @@ def _safe_fetch_image_for_gemini_sync(
             if rp_info is None:
                 return None
             _rp, current_host, current_port = rp_info
-            ok2, reason2, pinned_ip = _validate_and_resolve_host(
-                current_host, current_port
-            )
+            ok2, reason2, pinned_ip = _validate_and_resolve_host(current_host, current_port)
             if not ok2:
                 logger.warning(
                     "Gemini image fetch: refusing redirect host=%s reason=%s",
@@ -654,13 +640,9 @@ def _safe_fetch_image_for_gemini_sync(
         with resp:
             status = getattr(resp, "status", None) or resp.getcode()
             if status != 200:
-                logger.info(
-                    "Gemini image fetch: status=%s host=%s", status, current_host
-                )
+                logger.info("Gemini image fetch: status=%s host=%s", status, current_host)
                 return None
-            _hdr_mime = (
-                (resp.headers.get("content-type") or "").split(";")[0].strip().lower()
-            )
+            _hdr_mime = (resp.headers.get("content-type") or "").split(";")[0].strip().lower()
             # Declared non-image MIME is a refusal; missing MIME falls back to caller's.
             if _hdr_mime and not _hdr_mime.startswith("image/"):
                 logger.info(
@@ -670,9 +652,7 @@ def _safe_fetch_image_for_gemini_sync(
                 )
                 return None
             _final_mime_pre = _hdr_mime if _hdr_mime else fallback_mime
-            if not isinstance(_final_mime_pre, str) or not _final_mime_pre.startswith(
-                "image/"
-            ):
+            if not isinstance(_final_mime_pre, str) or not _final_mime_pre.startswith("image/"):
                 logger.info(
                     "Gemini image fetch: missing content-type and no image fallback host=%s",
                     current_host,
@@ -715,10 +695,7 @@ async def _safe_fetch_image_for_gemini(
     rejected up front.
     """
     import asyncio
-
-    return await asyncio.to_thread(
-        _safe_fetch_image_for_gemini_sync, url, fallback_mime, max_bytes
-    )
+    return await asyncio.to_thread(_safe_fetch_image_for_gemini_sync, url, fallback_mime, max_bytes)
 
 
 # Synthetic-tool names stamped onto outbound _toolEvent.arguments so the
@@ -753,9 +730,7 @@ def _stamp_server_tool_marker(payload: dict[str, Any]) -> None:
 
 
 def _build_kimi_tool_end(
-    synthetic_chunk_fn: Any,
-    tool_call_id: str,
-    citations: list[dict[str, str]],
+    synthetic_chunk_fn: Any, tool_call_id: str, citations: list[dict[str, str]]
 ) -> str:
     """Format Kimi web_search citations into the tool_end payload.
 
@@ -798,10 +773,10 @@ class ExternalProviderClient:
         if self.provider_type == "gemini":
             _parsed_base = urlparse(self.base_url)
             if (
-                (_parsed_base.hostname or "").lower()
-                == "generativelanguage.googleapis.com"
-                and _parsed_base.path.rstrip("/") == "/v1beta/openai"
-            ):
+                _parsed_base.hostname or ""
+            ).lower() == "generativelanguage.googleapis.com" and _parsed_base.path.rstrip(
+                "/"
+            ) == "/v1beta/openai":
                 self.base_url = self.base_url[: -len("/openai")]
         self.api_key = api_key
         self._timeout = httpx.Timeout(timeout, connect = 10.0)
@@ -1018,9 +993,7 @@ class ExternalProviderClient:
             else:
                 body["thinking"] = {"type": "disabled"}
         elif self.provider_type == "mistral":
-            _apply_mistral_reasoning_controls(
-                body, model, enable_thinking, reasoning_effort
-            )
+            _apply_mistral_reasoning_controls(body, model, enable_thinking, reasoning_effort)
         elif self.provider_type == "vllm" and enable_thinking is not None:
             # vLLM gates thinking via chat_template_kwargs.enable_thinking.
             tpl_kw = body.get("chat_template_kwargs")
@@ -1061,9 +1034,7 @@ class ExternalProviderClient:
                 and "web_search" in enabled_tools
             ):
                 plugins = list(body.get("plugins") or [])
-                if not any(
-                    isinstance(p, dict) and p.get("id") == "web" for p in plugins
-                ):
+                if not any(isinstance(p, dict) and p.get("id") == "web" for p in plugins):
                     plugins.append({"id": "web"})
                 body["plugins"] = plugins
                 logger.info(
@@ -1110,9 +1081,7 @@ class ExternalProviderClient:
                         response.status_code,
                         error_text[:500],
                     )
-                    yield _error_sse_line(
-                        response.status_code, error_text, self.provider_type
-                    )
+                    yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
                 # Manual __anext__ (not `async for`) so we can close
@@ -1193,11 +1162,7 @@ class ExternalProviderClient:
                         {
                             "type": "tool_end",
                             "tool_call_id": web_search_tool_id,
-                            "result": (
-                                "\n---\n".join(blocks)
-                                if blocks
-                                else "(search complete)"
-                            ),
+                            "result": ("\n---\n".join(blocks) if blocks else "(search complete)"),
                         }
                     )
 
@@ -1245,18 +1210,14 @@ class ExternalProviderClient:
                                     # in particular returns 200 then surfaces the
                                     # actual failure as an SSE error event.
                                     if "error" in parsed:
-                                        event_counts["error"] = (
-                                            event_counts.get("error", 0) + 1
-                                        )
+                                        event_counts["error"] = event_counts.get("error", 0) + 1
                                         logger.warning(
                                             "%s SSE error event: %s",
                                             self.provider_type,
                                             parsed.get("error"),
                                         )
                                     else:
-                                        event_counts["delta"] = (
-                                            event_counts.get("delta", 0) + 1
-                                        )
+                                        event_counts["delta"] = event_counts.get("delta", 0) + 1
                                     # OpenRouter (and most OAI-compat providers)
                                     # report the underlying model that handled
                                     # the request in every chunk's `model` field.
@@ -1284,20 +1245,13 @@ class ExternalProviderClient:
                                                 ):
                                                     if not isinstance(envelope, dict):
                                                         continue
-                                                    for ann in (
-                                                        envelope.get("annotations")
-                                                        or []
-                                                    ):
+                                                    for ann in envelope.get("annotations") or []:
                                                         _record_or_url_citation(ann)
                         yield line
                     # Stream ended without [DONE] (some upstreams just close
                     # the connection). Emit tool_end so the card doesn't
                     # stay in "running" forever.
-                    if (
-                        web_search_active
-                        and web_search_tool_started
-                        and not web_search_tool_ended
-                    ):
+                    if web_search_active and web_search_tool_started and not web_search_tool_ended:
                         yield _build_web_search_tool_end()
                         web_search_tool_ended = True
                 except GeneratorExit:
@@ -1341,10 +1295,7 @@ class ExternalProviderClient:
             )
 
     async def _stream_kimi_web_search(
-        self,
-        messages: list[dict[str, Any]],
-        model: str,
-        max_tokens: Optional[int],
+        self, messages: list[dict[str, Any]], model: str, max_tokens: Optional[int]
     ) -> AsyncGenerator[str, None]:
         """
         Kimi $web_search round-trip.
@@ -1377,9 +1328,7 @@ class ExternalProviderClient:
             # $web_search forbids thinking; sending the toggle silently
             # would have the server reject the request with 400.
             "thinking": {"type": "disabled"},
-            "tools": [
-                {"type": "builtin_function", "function": {"name": "$web_search"}}
-            ],
+            "tools": [{"type": "builtin_function", "function": {"name": "$web_search"}}],
         }
         if max_tokens is not None:
             body["max_tokens"] = max_tokens
@@ -1429,9 +1378,7 @@ class ExternalProviderClient:
                         response.status_code,
                         error_text[:500],
                     )
-                    yield _error_sse_line(
-                        response.status_code, error_text, self.provider_type
-                    )
+                    yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
                 lines_gen = response.aiter_lines().__aiter__()
@@ -1496,14 +1443,11 @@ class ExternalProviderClient:
         # of every other provider when web_search is on but the model
         # didn't actually need it.
         search_calls = [
-            tc
-            for tc in tool_calls_acc.values()
-            if tc["function"]["name"] == "$web_search"
+            tc for tc in tool_calls_acc.values() if tc["function"]["name"] == "$web_search"
         ]
         if not search_calls:
             logger.info(
-                "Kimi $web_search: model did not invoke search; "
-                "falling back to plain stream"
+                "Kimi $web_search: model did not invoke search; falling back to plain stream"
             )
             fallback_body = dict(body)
             fallback_body.pop("tools", None)
@@ -1523,9 +1467,7 @@ class ExternalProviderClient:
                             response.status_code,
                             error_text[:500],
                         )
-                        yield _error_sse_line(
-                            response.status_code, error_text, self.provider_type
-                        )
+                        yield _error_sse_line(response.status_code, error_text, self.provider_type)
                         return
                     # Manual __anext__ loop instead of `async for` — see the
                     # comment in stream_chat_completion for the Python 3.13 +
@@ -1641,9 +1583,7 @@ class ExternalProviderClient:
                         response.status_code,
                         error_text[:500],
                     )
-                    yield _error_sse_line(
-                        response.status_code, error_text, self.provider_type
-                    )
+                    yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
                 lines_gen = response.aiter_lines().__aiter__()
@@ -1686,9 +1626,7 @@ class ExternalProviderClient:
                                         ):
                                             if not isinstance(envelope, dict):
                                                 continue
-                                            for ann in (
-                                                envelope.get("annotations") or []
-                                            ):
+                                            for ann in envelope.get("annotations") or []:
                                                 if isinstance(ann, dict):
                                                     annotation_shapes.add(
                                                         str(ann.get("type") or "?")
@@ -1758,9 +1696,7 @@ class ExternalProviderClient:
                 system = (
                     content
                     if isinstance(content, str)
-                    else "\n".join(
-                        p["text"] for p in content if p.get("type") == "text"
-                    )
+                    else "\n".join(p["text"] for p in content if p.get("type") == "text")
                 )
                 continue
 
@@ -1823,18 +1759,13 @@ class ExternalProviderClient:
                         #   https://platform.claude.com/docs/en/build-with-claude/compaction
                         summary = part.get("content") or ""
                         if isinstance(summary, str) and summary:
-                            anthropic_parts.append(
-                                {"type": "compaction", "content": summary}
-                            )
+                            anthropic_parts.append({"type": "compaction", "content": summary})
                     elif part.get("type") == "image_url":
                         url = part.get("image_url", {}).get("url", "")
                         if url.startswith("data:"):
                             # data:image/png;base64,<DATA> -> split header and data
                             header, _, b64data = url.partition(",")
-                            media_type = (
-                                header.split(";")[0].replace("data:", "")
-                                or "image/jpeg"
-                            )
+                            media_type = header.split(";")[0].replace("data:", "") or "image/jpeg"
                             anthropic_parts.append(
                                 {
                                     "type": "image",
@@ -1918,9 +1849,7 @@ class ExternalProviderClient:
                 # Messages API does not accept OpenAI's top-level
                 # `tool_calls` field; the call lives inside a content
                 # block with `{type:"tool_use", id, name, input}`.
-                if msg.get("role") == "assistant" and isinstance(
-                    msg.get("tool_calls"), list
-                ):
+                if msg.get("role") == "assistant" and isinstance(msg.get("tool_calls"), list):
                     for _tc in msg["tool_calls"]:
                         if not isinstance(_tc, dict):
                             continue
@@ -1929,9 +1858,7 @@ class ExternalProviderClient:
                             continue
                         _raw = _fn.get("arguments") or "{}"
                         try:
-                            _input = (
-                                _json.loads(_raw) if isinstance(_raw, str) else _raw
-                            )
+                            _input = _json.loads(_raw) if isinstance(_raw, str) else _raw
                         except Exception:
                             _input = {"_raw": _raw}
                         if not isinstance(_input, dict):
@@ -1999,9 +1926,7 @@ class ExternalProviderClient:
                             continue
                         _raw = _fn.get("arguments") or "{}"
                         try:
-                            _input = (
-                                _json.loads(_raw) if isinstance(_raw, str) else _raw
-                            )
+                            _input = _json.loads(_raw) if isinstance(_raw, str) else _raw
                         except Exception:
                             _input = {"_raw": _raw}
                         if not isinstance(_input, dict):
@@ -2097,18 +2022,14 @@ class ExternalProviderClient:
                 last_msg["content"] = head
         thinking_spec = _anthropic_thinking_spec(model)
         allowed_efforts = (
-            thinking_spec.efforts
-            if thinking_spec
-            else ("none", "low", "medium", "high")
+            thinking_spec.efforts if thinking_spec else ("none", "low", "medium", "high")
         )
         effort = reasoning_effort if reasoning_effort in allowed_efforts else None
         # Claude 4.6 Opus/Sonnet accept top-tier adaptive effort as "max" only;
         # "xhigh" is rejected (supported on Claude 4.7). Map our shared "xhigh"
         # semantic to "max" for 4.6 outbound requests while still accepting
         # both in ``allowed_efforts`` for persisted / cross-provider UI state.
-        if effort == "xhigh" and model.startswith(
-            ("claude-opus-4-6", "claude-sonnet-4-6")
-        ):
+        if effort == "xhigh" and model.startswith(("claude-opus-4-6", "claude-sonnet-4-6")):
             effort = "max"
         if effort is None:
             if enable_thinking is False:
@@ -2170,17 +2091,12 @@ class ExternalProviderClient:
             and bool(tool_choice["function"].get("name"))
         )
         _anthropic_hosted_builtins_allowed = (
-            not _anthropic_tool_choice_disabled
-            and not _anthropic_tool_choice_forced_function
+            not _anthropic_tool_choice_disabled and not _anthropic_tool_choice_forced_function
         )
 
         # Anthropic web_search (date-pinned per model family).
         # https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
-        if (
-            _anthropic_hosted_builtins_allowed
-            and enabled_tools
-            and "web_search" in enabled_tools
-        ):
+        if _anthropic_hosted_builtins_allowed and enabled_tools and "web_search" in enabled_tools:
             anthropic_tools = list(body.get("tools") or [])
             anthropic_tools.append(
                 {
@@ -2194,9 +2110,7 @@ class ExternalProviderClient:
         # Anthropic web_fetch: only URLs already in conversation. Date-pinned.
         # https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
         web_fetch_enabled = bool(
-            _anthropic_hosted_builtins_allowed
-            and enabled_tools
-            and "web_fetch" in enabled_tools
+            _anthropic_hosted_builtins_allowed and enabled_tools and "web_fetch" in enabled_tools
         )
         if web_fetch_enabled:
             anthropic_tools = list(body.get("tools") or [])
@@ -2302,9 +2216,7 @@ class ExternalProviderClient:
         # Merge new beta flags onto whatever the registry contributed.
         existing_beta = request_headers.get("anthropic-beta", "").strip()
         beta_parts = (
-            [p.strip() for p in existing_beta.split(",") if p.strip()]
-            if existing_beta
-            else []
+            [p.strip() for p in existing_beta.split(",") if p.strip()] if existing_beta else []
         )
         if code_execution_enabled and _ANTHROPIC_CODE_EXECUTION_BETA not in beta_parts:
             beta_parts.append(_ANTHROPIC_CODE_EXECUTION_BETA)
@@ -2337,10 +2249,7 @@ class ExternalProviderClient:
                     # expired / missing, emit container_invalidated so
                     # the chat adapter clears the stored id and the
                     # next turn falls back to auto-create.
-                    if (
-                        anthropic_code_exec_container_id
-                        and 400 <= response.status_code < 500
-                    ):
+                    if anthropic_code_exec_container_id and 400 <= response.status_code < 500:
                         lowered = error_text.lower()
                         if "container" in lowered and (
                             "expired" in lowered
@@ -2353,9 +2262,7 @@ class ExternalProviderClient:
                                 f"data: "
                                 f"{_json.dumps({'id': completion_id, 'object': 'chat.completion.chunk', 'choices': [{'index': 0, 'delta': {}, 'finish_reason': None}], '_toolEvent': {'type': 'container_invalidated'}})}"
                             )
-                    yield _error_sse_line(
-                        response.status_code, error_text, self.provider_type
-                    )
+                    yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
                 # NOTE: same manual __anext__ loop as stream_chat_completion — see comment there.
@@ -2457,9 +2364,7 @@ class ExternalProviderClient:
                     }
                     return f"data: {_json.dumps(chunk)}"
 
-                def _format_web_search_results(
-                    results: list[Any],
-                ) -> str:
+                def _format_web_search_results(results: list[Any]) -> str:
                     blocks: list[str] = []
                     for r in results:
                         if not isinstance(r, dict):
@@ -2506,11 +2411,7 @@ class ExternalProviderClient:
                             # Inline a short text preview so the source
                             # pill carries usable context; skip for PDFs
                             # since the body is base64-encoded.
-                            if (
-                                media_type.startswith("text/")
-                                and isinstance(data, str)
-                                and data
-                            ):
+                            if media_type.startswith("text/") and isinstance(data, str) and data:
                                 snippet = data[:240].strip()
                     # Frontend parseSourcesFromResult only emits a source
                     # pill when both `Title:` and `URL:` are present, so
@@ -2527,9 +2428,7 @@ class ExternalProviderClient:
                         parts.append(f"Snippet: {snippet}")
                     return "\n".join(parts) if parts else "(fetch complete)"
 
-                def _format_code_execution_result(
-                    inner: dict[str, Any],
-                ) -> str:
+                def _format_code_execution_result(inner: dict[str, Any]) -> str:
                     """Render an Anthropic code-execution result block as
                     the preformatted text payload the frontend's
                     CodeExecutionToolUI displays inside a <pre>. Handles
@@ -2560,9 +2459,7 @@ class ExternalProviderClient:
                         if "lines" in inner and isinstance(inner.get("lines"), list):
                             return "\n".join(str(line) for line in inner["lines"])
                         if "is_file_update" in inner:
-                            return (
-                                "Updated" if inner.get("is_file_update") else "Created"
-                            )
+                            return "Updated" if inner.get("is_file_update") else "Created"
                         content_field = inner.get("content")
                         if isinstance(content_field, str):
                             return content_field
@@ -2611,10 +2508,7 @@ class ExternalProviderClient:
                             content_block = event.get("content_block") or {}
                             block_type = content_block.get("type")
                             block_name = content_block.get("name")
-                            if (
-                                block_type == "server_tool_use"
-                                and block_name == "web_search"
-                            ):
+                            if block_type == "server_tool_use" and block_name == "web_search":
                                 tool_use_id = content_block.get("id", "") or (
                                     f"ws_{len(web_search_calls)}"
                                 )
@@ -2635,14 +2529,9 @@ class ExternalProviderClient:
                                 content = content_block.get("content") or []
                                 current_result_block = {
                                     "tool_use_id": tool_use_id,
-                                    "results": list(content)
-                                    if isinstance(content, list)
-                                    else [],
+                                    "results": list(content) if isinstance(content, list) else [],
                                 }
-                            elif (
-                                block_type == "server_tool_use"
-                                and block_name == "web_fetch"
-                            ):
+                            elif block_type == "server_tool_use" and block_name == "web_fetch":
                                 tool_use_id = content_block.get("id", "") or (
                                     f"wf_{len(web_fetch_calls)}"
                                 )
@@ -2669,9 +2558,7 @@ class ExternalProviderClient:
                                     f"ce_{len(code_execution_calls)}"
                                 )
                                 kind = (
-                                    "bash"
-                                    if block_name == "bash_code_execution"
-                                    else "text_editor"
+                                    "bash" if block_name == "bash_code_execution" else "text_editor"
                                 )
                                 current_code_exec_use = {
                                     "id": tool_use_id,
@@ -2751,9 +2638,7 @@ class ExternalProviderClient:
                                 if isinstance(cit, dict):
                                     key = _anthropic_citation_key(cit)
                                     idx_for_marker: Optional[int] = None
-                                    for idx, existing in enumerate(
-                                        document_citations, start = 1
-                                    ):
+                                    for idx, existing in enumerate(document_citations, start = 1):
                                         if existing.get("_key") == key:
                                             idx_for_marker = idx
                                             break
@@ -2807,9 +2692,7 @@ class ExternalProviderClient:
                                         "type": "tool_start",
                                         "tool_name": "web_search",
                                         "tool_call_id": tool_use_id,
-                                        "arguments": (
-                                            {"query": query} if query else {}
-                                        ),
+                                        "arguments": ({"query": query} if query else {}),
                                     }
                                 )
                                 current_server_tool_use = None
@@ -2851,9 +2734,7 @@ class ExternalProviderClient:
                                 kind = current_code_exec_use["kind"]
                                 emit_args = {"kind": kind, **parsed_args}
                                 if tool_use_id in code_execution_calls:
-                                    code_execution_calls[tool_use_id]["arguments"] = (
-                                        emit_args
-                                    )
+                                    code_execution_calls[tool_use_id]["arguments"] = emit_args
                                 yield _emit_tool_event(
                                     {
                                         "type": "tool_start",
@@ -2892,17 +2773,13 @@ class ExternalProviderClient:
                                     file_blocks = inner.get("content")
                                     if isinstance(file_blocks, list):
                                         for entry in file_blocks:
-                                            if isinstance(entry, dict) and entry.get(
-                                                "file_id"
-                                            ):
+                                            if isinstance(entry, dict) and entry.get("file_id"):
                                                 code_execution_generated_files += 1
                                 result_text = _format_code_execution_result(
                                     inner if isinstance(inner, dict) else {}
                                 )
                                 if tool_use_id in code_execution_calls:
-                                    code_execution_calls[tool_use_id]["result"] = (
-                                        result_text
-                                    )
+                                    code_execution_calls[tool_use_id]["result"] = result_text
                                 yield _emit_tool_event(
                                     {
                                         "type": "tool_end",
@@ -2989,10 +2866,7 @@ class ExternalProviderClient:
                                     c_in = 0
                                     c_out = 0
                                     for it in iterations:
-                                        if (
-                                            isinstance(it, dict)
-                                            and it.get("type") == "compaction"
-                                        ):
+                                        if isinstance(it, dict) and it.get("type") == "compaction":
                                             c_in += int(it.get("input_tokens") or 0)
                                             c_out += int(it.get("output_tokens") or 0)
                                     if c_in or c_out:
@@ -3008,18 +2882,14 @@ class ExternalProviderClient:
                             # the same id to the thread record every turn.
                             delta_obj = event.get("delta") or {}
                             container_obj = delta_obj.get("container")
-                            if (
-                                isinstance(container_obj, dict)
-                                and latched_container_id is None
-                            ):
+                            if isinstance(container_obj, dict) and latched_container_id is None:
                                 probe = container_obj.get("id")
                                 if isinstance(probe, str) and probe:
                                     latched_container_id = probe
                             if (
                                 latched_container_id
                                 and not container_id_emitted
-                                and latched_container_id
-                                != anthropic_code_exec_container_id
+                                and latched_container_id != anthropic_code_exec_container_id
                             ):
                                 yield _emit_tool_event(
                                     {
@@ -3059,9 +2929,7 @@ class ExternalProviderClient:
                                         "or remove the previous turn and try "
                                         "again._"
                                     )
-                                    yield _emit_tool_event(
-                                        {"type": "anthropic_refusal"}
-                                    )
+                                    yield _emit_tool_event({"type": "anthropic_refusal"})
                                 if mapped is not None:
                                     chunk = {
                                         "id": completion_id,
@@ -3089,13 +2957,8 @@ class ExternalProviderClient:
                                 for c in document_citations:
                                     entry = {k: v for k, v in c.items() if k != "_key"}
                                     cited = entry.get("cited_text")
-                                    if (
-                                        isinstance(cited, str)
-                                        and len(cited) > _CITED_TEXT_MAX_LEN
-                                    ):
-                                        entry["cited_text"] = (
-                                            cited[:_CITED_TEXT_MAX_LEN] + "…"
-                                        )
+                                    if isinstance(cited, str) and len(cited) > _CITED_TEXT_MAX_LEN:
+                                        entry["cited_text"] = cited[:_CITED_TEXT_MAX_LEN] + "…"
                                     clean_cits.append(entry)
                                 yield _emit_tool_event(
                                     {
@@ -3114,9 +2977,7 @@ class ExternalProviderClient:
                             if usage_line:
                                 yield usage_line
                             yield "data: [DONE]"
-                            await (
-                                response.aclose()
-                            )  # set PoolByteStream._closed=True FIRST
+                            await response.aclose()  # set PoolByteStream._closed=True FIRST
                             break
                 except GeneratorExit:
                     await response.aclose()  # set PoolByteStream._closed=True FIRST
@@ -3126,18 +2987,12 @@ class ExternalProviderClient:
                     # Surface per-event-type counts + web_search summary so
                     # reports of "no reasoning panel content" / "Search
                     # didn't do anything" can be triaged at a glance.
-                    web_search_requested = bool(
-                        enabled_tools and "web_search" in enabled_tools
-                    )
+                    web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                     web_search_invocations = len(web_search_calls)
                     total_results = sum(
                         len(sc.get("results") or []) for sc in web_search_calls.values()
                     )
-                    queries = [
-                        sc["query"]
-                        for sc in web_search_calls.values()
-                        if sc.get("query")
-                    ]
+                    queries = [sc["query"] for sc in web_search_calls.values() if sc.get("query")]
                     # cache_read_input_tokens > 0 on turn N proves the
                     # cache_control marker on the system block is doing
                     # its job — turn 1 will show cache_creation > 0
@@ -3146,15 +3001,11 @@ class ExternalProviderClient:
                     # discount.
                     code_execution_invocations = len(code_execution_calls)
                     code_execution_results = sum(
-                        1
-                        for c in code_execution_calls.values()
-                        if c.get("result") is not None
+                        1 for c in code_execution_calls.values() if c.get("result") is not None
                     )
                     web_fetch_requested = web_fetch_enabled
                     web_fetch_invocations = len(web_fetch_calls)
-                    web_fetch_urls = [
-                        wf["url"] for wf in web_fetch_calls.values() if wf.get("url")
-                    ]
+                    web_fetch_urls = [wf["url"] for wf in web_fetch_calls.values() if wf.get("url")]
                     logger.info(
                         "Anthropic stream complete (model=%s, "
                         "web_search_requested=%s, web_search_invocations=%s, "
@@ -3347,10 +3198,7 @@ class ExternalProviderClient:
                         if url.startswith("data:"):
                             header, _, b64data = url.partition(",")
                             media_type = (
-                                header.split(";")[0]
-                                .replace("data:", "")
-                                .strip()
-                                .lower()
+                                header.split(";")[0].replace("data:", "").strip().lower()
                                 or "image/jpeg"
                             )
                             # Symmetry with the fetched remote image
@@ -3368,10 +3216,7 @@ class ExternalProviderClient:
                                 # data: URLs share the same caps as fetched
                                 # URLs so inline payloads don't bypass them.
                                 _data_approx_bytes = (len(b64data) * 3) // 4
-                                if (
-                                    _remote_image_count
-                                    >= _GEMINI_REMOTE_IMAGE_MAX_COUNT
-                                ):
+                                if _remote_image_count >= _GEMINI_REMOTE_IMAGE_MAX_COUNT:
                                     logger.info(
                                         "Gemini inlineData: per-request count cap %d reached, dropping image",
                                         _GEMINI_REMOTE_IMAGE_MAX_COUNT,
@@ -3425,8 +3270,7 @@ class ExternalProviderClient:
                             _guessed, _ = mimetypes.guess_type(_img_path)
                             _media_type = (
                                 _guessed
-                                if isinstance(_guessed, str)
-                                and _guessed.startswith("image/")
+                                if isinstance(_guessed, str) and _guessed.startswith("image/")
                                 else "image/jpeg"
                             )
                             if _is_youtube:
@@ -3459,8 +3303,7 @@ class ExternalProviderClient:
                                 # byte budget is spent; pass the remainder
                                 # so over-budget URLs reject on Content-Length.
                                 _remaining_bytes = (
-                                    _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES
-                                    - _remote_image_total_bytes
+                                    _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES - _remote_image_total_bytes
                                 )
                                 if _remaining_bytes <= 0:
                                     logger.info(
@@ -3506,9 +3349,7 @@ class ExternalProviderClient:
                 if isinstance(_msg_extra, dict):
                     _msg_g = _msg_extra.get("google") or {}
                     if isinstance(_msg_g, dict):
-                        _msg_sig = _msg_g.get("thought_signature") or _msg_g.get(
-                            "thoughtSignature"
-                        )
+                        _msg_sig = _msg_g.get("thought_signature") or _msg_g.get("thoughtSignature")
                         if isinstance(_msg_sig, str) and _msg_sig:
                             for _idx in range(len(parts) - 1, -1, -1):
                                 if "text" in parts[_idx]:
@@ -3579,9 +3420,7 @@ class ExternalProviderClient:
                         and isinstance(args, dict)
                         and (
                             args.get("_server_tool") is True
-                            or isinstance(
-                                (args.get("google") or {}).get("native_part"), dict
-                            )
+                            or isinstance((args.get("google") or {}).get("native_part"), dict)
                         )
                     )
                     if _is_synthetic_server_builtin and not (
@@ -3624,9 +3463,9 @@ class ExternalProviderClient:
                         # thoughtSignature only when one subpart exists;
                         # for code+result, prefer executableCode and drop
                         # the signature elsewhere.
-                        _legacy_sig = _native_part.get(
-                            "thoughtSignature"
-                        ) or _native_part.get("thought_signature")
+                        _legacy_sig = _native_part.get("thoughtSignature") or _native_part.get(
+                            "thought_signature"
+                        )
                         _legacy_subparts = [
                             _k
                             for _k in (
@@ -3769,9 +3608,7 @@ class ExternalProviderClient:
 
         body: dict[str, Any] = {"contents": contents}
         if system_text_parts:
-            body["systemInstruction"] = {
-                "parts": [{"text": "\n\n".join(system_text_parts)}]
-            }
+            body["systemInstruction"] = {"parts": [{"text": "\n\n".join(system_text_parts)}]}
 
         # Generation config -- temperature / topP / topK / maxOutputTokens
         # map straight across. The frontend capability matrix restricts
@@ -3815,9 +3652,7 @@ class ExternalProviderClient:
             and isinstance(tool_choice.get("function"), dict)
             and bool(tool_choice["function"].get("name"))
         )
-        _hosted_builtins_allowed = (
-            not _tool_choice_disabled and not _tool_choice_forced_function
-        )
+        _hosted_builtins_allowed = not _tool_choice_disabled and not _tool_choice_forced_function
         # Image-tier model IDs reject text-only tools (code_execution,
         # user functions) and thinkingConfig regardless of whether the
         # Images pill is on -- those are model-level constraints
@@ -3828,9 +3663,7 @@ class ExternalProviderClient:
         # forwards `tools: [{codeExecution: {}}]` plus
         # `thinkingConfig` to an image model and 400s.
         image_tool_requested = bool(
-            _hosted_builtins_allowed
-            and enabled_tools
-            and "image_generation" in enabled_tools
+            _hosted_builtins_allowed and enabled_tools and "image_generation" in enabled_tools
         )
         # Strict tool / thinking strip uses the model-id check.
         is_image_model_strict = is_image_picker_model
@@ -3862,13 +3695,10 @@ class ExternalProviderClient:
             "gemini-pro-latest",
         )
         _PRO_THINKING_PREFIXES = ("gemini-2.5-pro",)
-        is_gemini3_thinking = any(
-            model_lc.startswith(p) for p in _GEMINI3_THINKING_PREFIXES
-        )
+        is_gemini3_thinking = any(model_lc.startswith(p) for p in _GEMINI3_THINKING_PREFIXES)
         is_gemini3_pro = any(model_lc.startswith(p) for p in _GEMINI3_PRO_PREFIXES)
         _is_pro_thinking_only = any(
-            model_lc == p or model_lc.startswith(p + "-")
-            for p in _PRO_THINKING_PREFIXES
+            model_lc == p or model_lc.startswith(p + "-") for p in _PRO_THINKING_PREFIXES
         )
         effort_lc = (reasoning_effort or "").strip().lower()
         if not is_image_model_strict and is_gemini3_thinking:
@@ -3945,8 +3775,7 @@ class ExternalProviderClient:
             )
 
         google_search_allowed = (
-            not is_image_model_strict
-            or _gemini_image_model_allows_google_search(model_lc)
+            not is_image_model_strict or _gemini_image_model_allows_google_search(model_lc)
         )
         code_execution_allowed = not is_image_model_strict
         text_tools_allowed = not is_image_model_strict
@@ -4001,9 +3830,7 @@ class ExternalProviderClient:
             }
         )
 
-        def _resolve_local_schema_ref(
-            root: Optional[dict[str, Any]], ref: str
-        ) -> Optional[Any]:
+        def _resolve_local_schema_ref(root: Optional[dict[str, Any]], ref: str) -> Optional[Any]:
             # Walk a `#/foo/bar` JSON pointer against the schema root.
             # Returns None if the pointer doesn't resolve to a dict, so
             # the caller can fall back to the unresolved node.
@@ -4058,9 +3885,7 @@ class ExternalProviderClient:
                             **_target,
                             **{k: v for k, v in node.items() if k != "$ref"},
                         }
-                        return _sanitize_gemini_schema(
-                            _merged, root, _seen_refs | {_ref}
-                        )
+                        return _sanitize_gemini_schema(_merged, root, _seen_refs | {_ref})
                 cleaned: dict[str, Any] = {}
                 _nullable_from_union = False
                 _flattened_type: Optional[str] = None
@@ -4076,9 +3901,7 @@ class ExternalProviderClient:
                         # Preserve multi-type unions as anyOf; flattening
                         # to the first non-null type silently drops the
                         # other branches and changes the tool contract.
-                        _union_any_of = [
-                            {"type": _t} for _t in _non_null if isinstance(_t, str)
-                        ]
+                        _union_any_of = [{"type": _t} for _t in _non_null if isinstance(_t, str)]
                 for _k, _v in node.items():
                     if _k == "type" and isinstance(_v, list):
                         # Handled below via _flattened_type.
@@ -4108,15 +3931,10 @@ class ExternalProviderClient:
                         _non_null_entries = [
                             _entry
                             for _entry in _v
-                            if not (
-                                isinstance(_entry, dict)
-                                and _entry.get("type") == "null"
-                            )
+                            if not (isinstance(_entry, dict) and _entry.get("type") == "null")
                         ]
                         if len(_non_null_entries) == 1 and _saw_null:
-                            _inner = _sanitize_gemini_schema(
-                                _non_null_entries[0], root, _seen_refs
-                            )
+                            _inner = _sanitize_gemini_schema(_non_null_entries[0], root, _seen_refs)
                             if isinstance(_inner, dict):
                                 for _ik, _iv in _inner.items():
                                     cleaned.setdefault(_ik, _iv)
@@ -4135,8 +3953,7 @@ class ExternalProviderClient:
                         cleaned[_k] = _v
                 if _union_any_of is not None and "anyOf" not in cleaned:
                     cleaned["anyOf"] = [
-                        _sanitize_gemini_schema(_s, root, _seen_refs)
-                        for _s in _union_any_of
+                        _sanitize_gemini_schema(_s, root, _seen_refs) for _s in _union_any_of
                     ]
                 elif _flattened_type is not None:
                     cleaned["type"] = _flattened_type
@@ -4178,9 +3995,7 @@ class ExternalProviderClient:
                     _mode = "NONE"
                 elif _tc_lc in ("required", "any"):
                     _mode = "ANY"
-            elif (
-                isinstance(tool_choice, dict) and tool_choice.get("type") == "function"
-            ):
+            elif isinstance(tool_choice, dict) and tool_choice.get("type") == "function":
                 _fn_pick = tool_choice.get("function") or {}
                 _name = _fn_pick.get("name") if isinstance(_fn_pick, dict) else None
                 if isinstance(_name, str) and _name:
@@ -4208,8 +4023,7 @@ class ExternalProviderClient:
         completion_id = f"chatcmpl-gemini-{model.replace('/', '-')}"
 
         logger.info(
-            "Proxying Gemini streamGenerateContent to %s (model=%s, "
-            "tools=%s, image=%s)",
+            "Proxying Gemini streamGenerateContent to %s (model=%s, tools=%s, image=%s)",
             url,
             model,
             [list(t.keys())[0] for t in tools_array] if tools_array else [],
@@ -4232,9 +4046,7 @@ class ExternalProviderClient:
             }
             return f"data: {_json.dumps(chunk)}"
 
-        def _text_chunk(
-            text: str, extra_content: Optional[dict[str, Any]] = None
-        ) -> str:
+        def _text_chunk(text: str, extra_content: Optional[dict[str, Any]] = None) -> str:
             delta: dict[str, Any] = {"content": text}
             if extra_content:
                 delta["extra_content"] = extra_content
@@ -4321,9 +4133,7 @@ class ExternalProviderClient:
                         response.status_code,
                         error_text[:500],
                     )
-                    yield _error_sse_line(
-                        response.status_code, error_text, self.provider_type
-                    )
+                    yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
                 if web_search_active:
@@ -4379,9 +4189,7 @@ class ExternalProviderClient:
                         # response. Surface as a content_filter error
                         # event so the UI can render the block reason.
                         prompt_feedback = event.get("promptFeedback")
-                        if isinstance(prompt_feedback, dict) and prompt_feedback.get(
-                            "blockReason"
-                        ):
+                        if isinstance(prompt_feedback, dict) and prompt_feedback.get("blockReason"):
                             block_reason = str(prompt_feedback.get("blockReason"))
                             # Close out the synthetic web_search start so
                             # the UI does not show a spinner stuck on
@@ -4432,9 +4240,7 @@ class ExternalProviderClient:
                                         u = web.get("uri") or ""
                                         if not u or not isinstance(u, str):
                                             continue
-                                        if any(
-                                            c["url"] == u for c in web_search_citations
-                                        ):
+                                        if any(c["url"] == u for c in web_search_citations):
                                             continue
                                         web_search_citations.append(
                                             {
@@ -4446,9 +4252,7 @@ class ExternalProviderClient:
 
                             content_obj = cand.get("content") or {}
                             parts = (
-                                content_obj.get("parts")
-                                if isinstance(content_obj, dict)
-                                else None
+                                content_obj.get("parts") if isinstance(content_obj, dict) else None
                             )
                             if isinstance(parts, list):
                                 for part in parts:
@@ -4487,10 +4291,7 @@ class ExternalProviderClient:
                                     if isinstance(fc, dict):
                                         fc_name = fc.get("name") or ""
                                         fc_args = fc.get("args") or {}
-                                        fc_id = (
-                                            fc.get("id")
-                                            or f"call_{fc_name}_{time.time_ns()}"
-                                        )
+                                        fc_id = fc.get("id") or f"call_{fc_name}_{time.time_ns()}"
                                         if fc_id in emitted_function_call_ids:
                                             continue
                                         emitted_function_call_ids.add(fc_id)
@@ -4521,9 +4322,9 @@ class ExternalProviderClient:
                                         # so the frontend can persist it
                                         # and our outbound translator
                                         # (below) can replay it.
-                                        thought_sig = part.get(
-                                            "thoughtSignature"
-                                        ) or part.get("thought_signature")
+                                        thought_sig = part.get("thoughtSignature") or part.get(
+                                            "thought_signature"
+                                        )
                                         if isinstance(thought_sig, str) and thought_sig:
                                             tool_call_delta["extra_content"] = {
                                                 "google": {
@@ -4537,9 +4338,7 @@ class ExternalProviderClient:
                                             "choices": [
                                                 {
                                                     "index": 0,
-                                                    "delta": {
-                                                        "tool_calls": [tool_call_delta]
-                                                    },
+                                                    "delta": {"tool_calls": [tool_call_delta]},
                                                     "finish_reason": None,
                                                 }
                                             ],
@@ -4596,9 +4395,7 @@ class ExternalProviderClient:
                                                         "kind": "code_execution",
                                                         "language": (
                                                             (
-                                                                exec_code.get(
-                                                                    "language"
-                                                                )
+                                                                exec_code.get("language")
                                                                 or "PYTHON"
                                                             ).lower()
                                                         ),
@@ -4619,9 +4416,7 @@ class ExternalProviderClient:
                                         # non-OK outcomes as stderr so the
                                         # UI surfaces the error.
                                         if outcome and outcome != "OUTCOME_OK":
-                                            result_text = (
-                                                f"[{outcome}]\n{output}".rstrip()
-                                            )
+                                            result_text = f"[{outcome}]\n{output}".rstrip()
                                         else:
                                             result_text = output
                                         # Pair tool_end with the most recent
@@ -4687,8 +4482,7 @@ class ExternalProviderClient:
                                                 not is_image_model
                                                 and last_code_exec_tool_id is not None
                                                 and bool(enabled_tools)
-                                                and "code_execution"
-                                                in (enabled_tools or [])
+                                                and "code_execution" in (enabled_tools or [])
                                             )
                                             if attached_to_code_exec:
                                                 updated_result = (
@@ -4712,28 +4506,22 @@ class ExternalProviderClient:
                                                     isinstance(_plot_thought_sig, str)
                                                     and _plot_thought_sig
                                                 ):
-                                                    _plot_part_entry[
-                                                        "thoughtSignature"
-                                                    ] = _plot_thought_sig
+                                                    _plot_part_entry["thoughtSignature"] = (
+                                                        _plot_thought_sig
+                                                    )
                                                 yield _emit_tool_event(
                                                     {
                                                         "type": "tool_end",
-                                                        "tool_call_id": (
-                                                            last_code_exec_tool_id
-                                                        ),
+                                                        "tool_call_id": (last_code_exec_tool_id),
                                                         "result": updated_result,
                                                         "google": {
                                                             "native_part": {
-                                                                "parts": [
-                                                                    _plot_part_entry
-                                                                ],
+                                                                "parts": [_plot_part_entry],
                                                             },
                                                         },
                                                     }
                                                 )
-                                                last_code_exec_result_text = (
-                                                    updated_result
-                                                )
+                                                last_code_exec_result_text = updated_result
                                             else:
                                                 img_id = f"img_{time.time_ns()}"
                                                 yield _emit_tool_event(
@@ -4773,9 +4561,9 @@ class ExternalProviderClient:
                                                     isinstance(_img_thought_sig, str)
                                                     and _img_thought_sig
                                                 ):
-                                                    _img_part_entry[
-                                                        "thoughtSignature"
-                                                    ] = _img_thought_sig
+                                                    _img_part_entry["thoughtSignature"] = (
+                                                        _img_thought_sig
+                                                    )
                                                 _img_native: dict[str, Any] = {
                                                     "parts": [_img_part_entry],
                                                 }
@@ -4802,11 +4590,7 @@ class ExternalProviderClient:
                     # chunk -> [DONE]. Matches the Anthropic / OpenAI
                     # helpers' contract so the frontend handler does
                     # not need provider-specific ordering knowledge.
-                    if (
-                        web_search_active
-                        and web_search_tool_started
-                        and not web_search_tool_ended
-                    ):
+                    if web_search_active and web_search_tool_started and not web_search_tool_ended:
                         blocks: list[str] = []
                         for cit in web_search_citations:
                             line_out = f"Title: {cit['title']}\nURL: {cit['url']}"
@@ -4818,9 +4602,7 @@ class ExternalProviderClient:
                                 "type": "tool_end",
                                 "tool_call_id": web_search_tool_id,
                                 "result": (
-                                    "\n---\n".join(blocks)
-                                    if blocks
-                                    else "(search complete)"
+                                    "\n---\n".join(blocks) if blocks else "(search complete)"
                                 ),
                             }
                         )
@@ -4857,25 +4639,19 @@ class ExternalProviderClient:
                         # Gemini bills tool-call prompt slices separately
                         # via `toolUsePromptTokenCount`. Fold into input
                         # so total_tokens does not undercount tool turns.
-                        tool_use_prompt_tokens = (
-                            last_usage.get("toolUsePromptTokenCount") or 0
-                        )
+                        tool_use_prompt_tokens = last_usage.get("toolUsePromptTokenCount") or 0
                         translated_usage = {
                             "input_tokens": prompt_tokens + tool_use_prompt_tokens,
                             "output_tokens": candidate_tokens + thought_tokens,
                             "input_tokens_details": {
-                                "cached_tokens": (
-                                    last_usage.get("cachedContentTokenCount") or 0
-                                ),
+                                "cached_tokens": (last_usage.get("cachedContentTokenCount") or 0),
                                 "tool_use_prompt_tokens": tool_use_prompt_tokens,
                             },
                             "output_tokens_details": {
                                 "reasoning_tokens": thought_tokens,
                             },
                         }
-                        usage_line = _build_usage_chunk(
-                            completion_id, "openai", translated_usage
-                        )
+                        usage_line = _build_usage_chunk(completion_id, "openai", translated_usage)
                         if usage_line:
                             yield usage_line
 
@@ -5064,13 +4840,9 @@ class ExternalProviderClient:
                         elif _pt == "image_url":
                             _u = _part.get("image_url", {}).get("url", "")
                             if _u:
-                                _asst_parts.append(
-                                    {"type": "input_image", "image_url": _u}
-                                )
+                                _asst_parts.append({"type": "input_image", "image_url": _u})
                     if _asst_parts:
-                        input_items.append(
-                            {"role": "assistant", "content": _asst_parts}
-                        )
+                        input_items.append({"role": "assistant", "content": _asst_parts})
 
                 for _tc in _tool_calls:
                     if not isinstance(_tc, dict):
@@ -5096,9 +4868,7 @@ class ExternalProviderClient:
                                 _is_server_builtin = True
                             else:
                                 _g = _args_obj.get("google")
-                                if isinstance(_g, dict) and isinstance(
-                                    _g.get("native_part"), dict
-                                ):
+                                if isinstance(_g, dict) and isinstance(_g.get("native_part"), dict):
                                     _is_server_builtin = True
                     _call_id_out = _tc.get("id") or f"call_{time.time_ns()}"
                     if _is_server_builtin:
@@ -5134,9 +4904,7 @@ class ExternalProviderClient:
                         if url:
                             # Responses takes image_url as a flat string (both
                             # https:// URLs and data: URLs are accepted).
-                            translated_parts.append(
-                                {"type": "input_image", "image_url": url}
-                            )
+                            translated_parts.append({"type": "input_image", "image_url": url})
                     elif (
                         part_type == "reasoning"
                         and role == "assistant"
@@ -5314,11 +5082,7 @@ class ExternalProviderClient:
 
         # Server-side context compaction (OpenAI cloud only).
         # https://developers.openai.com/api/docs/guides/compaction
-        if (
-            is_openai_cloud
-            and compaction_threshold is not None
-            and compaction_threshold > 0
-        ):
+        if is_openai_cloud and compaction_threshold is not None and compaction_threshold > 0:
             body["context_management"] = [
                 {
                     "type": "compaction",
@@ -5394,13 +5158,10 @@ class ExternalProviderClient:
             and bool(tool_choice["function"].get("name"))
         )
         _responses_hosted_builtins_allowed = (
-            not _responses_tool_choice_none
-            and not _responses_tool_choice_forced_function
+            not _responses_tool_choice_none and not _responses_tool_choice_forced_function
         )
 
-        if (
-            enabled_tools or responses_user_function_tools
-        ) and not _responses_tool_choice_none:
+        if (enabled_tools or responses_user_function_tools) and not _responses_tool_choice_none:
             tools_array: list[dict[str, Any]] = list(responses_user_function_tools)
             if (
                 _responses_hosted_builtins_allowed
@@ -5440,12 +5201,8 @@ class ExternalProviderClient:
             first attempt.
             """
             attempt_body = dict(body)
-            if (
-                enabled_tools or responses_user_function_tools
-            ) and not _responses_tool_choice_none:
-                tools_array_attempt: list[dict[str, Any]] = list(
-                    responses_user_function_tools
-                )
+            if (enabled_tools or responses_user_function_tools) and not _responses_tool_choice_none:
+                tools_array_attempt: list[dict[str, Any]] = list(responses_user_function_tools)
                 if (
                     _responses_hosted_builtins_allowed
                     and enabled_tools
@@ -5460,13 +5217,8 @@ class ExternalProviderClient:
                         }
                     else:
                         env_attempt = {"type": "container_auto"}
-                    tools_array_attempt.append(
-                        {"type": "shell", "environment": env_attempt}
-                    )
-                if (
-                    _responses_hosted_builtins_allowed
-                    and image_generation_enabled_openai
-                ):
+                    tools_array_attempt.append({"type": "shell", "environment": env_attempt})
+                if _responses_hosted_builtins_allowed and image_generation_enabled_openai:
                     tools_array_attempt.append(_openai_image_generation_tool())
                 if tools_array_attempt:
                     attempt_body["tools"] = tools_array_attempt
@@ -5524,9 +5276,7 @@ class ExternalProviderClient:
                             retried = True
                             attempt_container_id = None
                             continue
-                        yield _error_sse_line(
-                            response.status_code, error_text, self.provider_type
-                        )
+                        yield _error_sse_line(response.status_code, error_text, self.provider_type)
                         return
 
                     # NOTE: same manual __anext__ loop as stream_chat_completion —
@@ -5622,9 +5372,7 @@ class ExternalProviderClient:
                             # Unterminated: drop the whole tail, otherwise the
                             # residual ``cite<sid>`` would leak as plain text.
                             return ""
-                        rendered = _replace_openai_citation_markers(
-                            tail, all_url_citations
-                        )
+                        rendered = _replace_openai_citation_markers(tail, all_url_citations)
                         # Scrub residual private-use bytes (e.g. a partial opener).
                         for ch in ("", "", ""):
                             rendered = rendered.replace(ch, "")
@@ -5682,11 +5430,7 @@ class ExternalProviderClient:
                                     chunk_parts.append("(timeout)")
                             if chunk_parts:
                                 parts.append("\n".join(chunk_parts))
-                        return (
-                            "\n--- next command ---\n".join(parts)
-                            if parts
-                            else "(no output)"
-                        )
+                        return "\n--- next command ---\n".join(parts) if parts else "(no output)"
 
                     def _record_url_citation(payload: dict[str, Any]) -> None:
                         """Append a url_citation onto the shared all_url_citations
@@ -5755,17 +5499,11 @@ class ExternalProviderClient:
                                 return existing
                         summary_text = ""
                         part = payload.get("part")
-                        if (
-                            isinstance(part, dict)
-                            and part.get("type") == "summary_text"
-                        ):
+                        if isinstance(part, dict) and part.get("type") == "summary_text":
                             text = part.get("text")
                             if isinstance(text, str):
                                 summary_text = text
-                        elif (
-                            payload.get("type")
-                            == "response.reasoning_summary_text.done"
-                        ):
+                        elif payload.get("type") == "response.reasoning_summary_text.done":
                             text = payload.get("text")
                             if isinstance(text, str):
                                 summary_text = text
@@ -5777,22 +5515,16 @@ class ExternalProviderClient:
                                     "type": "summary_text",
                                     "text": summary_text,
                                 }
-                                if (
-                                    isinstance(summary_index, int)
-                                    and summary_index >= 0
-                                ):
+                                if isinstance(summary_index, int) and summary_index >= 0:
                                     while len(summary) <= summary_index:
-                                        summary.append(
-                                            {"type": "summary_text", "text": ""}
-                                        )
+                                        summary.append({"type": "summary_text", "text": ""})
                                     summary[summary_index] = summary_part
                                 else:
                                     summary.append(summary_part)
                         return existing
 
                     def _image_generation_arguments(
-                        prompt: str,
-                        raw_item_id: Any,
+                        prompt: str, raw_item_id: Any
                     ) -> dict[str, Any]:
                         arguments: dict[str, Any] = {"kind": "image", "prompt": prompt}
                         if isinstance(raw_item_id, str) and raw_item_id:
@@ -5800,9 +5532,7 @@ class ExternalProviderClient:
                         if current_openai_response_id:
                             arguments["openai_response_id"] = current_openai_response_id
                         if last_openai_reasoning_replay_item:
-                            arguments["openai_reasoning_item"] = (
-                                last_openai_reasoning_replay_item
-                            )
+                            arguments["openai_reasoning_item"] = last_openai_reasoning_replay_item
                         return arguments
 
                     def _extract_reasoning_text(payload: Any) -> str:
@@ -5861,9 +5591,7 @@ class ExternalProviderClient:
                                 # Flush any held-over partial marker; strip
                                 # private-use bytes so garbled glyphs don't leak.
                                 if pending_marker_tail:
-                                    flushed = _flush_pending_marker_tail(
-                                        pending_marker_tail
-                                    )
+                                    flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
                                     if flushed:
                                         if reasoning_open:
@@ -5906,8 +5634,8 @@ class ExternalProviderClient:
                                     # Prepend any held-over tail so a marker
                                     # straddling two SSE events resolves cleanly.
                                     combined = pending_marker_tail + delta_text
-                                    head, pending_marker_tail = (
-                                        _split_pending_citation_tail(combined)
+                                    head, pending_marker_tail = _split_pending_citation_tail(
+                                        combined
                                     )
                                     if head:
                                         if reasoning_open:
@@ -5928,9 +5656,7 @@ class ExternalProviderClient:
                                             )
                                         )
                                         if has_unresolved or pending_citation_segments:
-                                            pending_citation_segments.append(
-                                                head_rewritten
-                                            )
+                                            pending_citation_segments.append(head_rewritten)
                                         elif head_rewritten:
                                             yield _chunk_with_text(head_rewritten)
 
@@ -5949,24 +5675,14 @@ class ExternalProviderClient:
 
                             elif event_type == "response.output_item.added":
                                 item = event.get("item", {})
-                                if (
-                                    isinstance(item, dict)
-                                    and item.get("type") == "web_search_call"
-                                ):
-                                    item_id = item.get("id", "") or (
-                                        f"ws_{len(web_search_calls)}"
-                                    )
+                                if isinstance(item, dict) and item.get("type") == "web_search_call":
+                                    item_id = item.get("id", "") or (f"ws_{len(web_search_calls)}")
                                     web_search_calls.setdefault(item_id, {"query": ""})
                                 # Register shell_call eagerly so out-of-order
                                 # output links back. Probe env.container_id
                                 # to emit container_ready before response.completed.
-                                if (
-                                    isinstance(item, dict)
-                                    and item.get("type") == "shell_call"
-                                ):
-                                    item_id = item.get("id", "") or (
-                                        f"sc_{len(shell_calls)}"
-                                    )
+                                if isinstance(item, dict) and item.get("type") == "shell_call":
+                                    item_id = item.get("id", "") or (f"sc_{len(shell_calls)}")
                                     shell_calls.setdefault(
                                         item_id,
                                         {"commands": [], "output": None},
@@ -6008,9 +5724,7 @@ class ExternalProviderClient:
                                     last_openai_reasoning_replay_item = (
                                         _record_openai_reasoning_replay_item(item)
                                     )
-                                    summary_text = _extract_reasoning_text(
-                                        item.get("summary")
-                                    )
+                                    summary_text = _extract_reasoning_text(item.get("summary"))
                                     if summary_text and not reasoning_emitted:
                                         if not reasoning_open:
                                             summary_text = f"<think>{summary_text}"
@@ -6027,14 +5741,10 @@ class ExternalProviderClient:
                                     # response.completed with the citation list
                                     # (so the source-pill extraction at message
                                     # tail surfaces them once).
-                                    item_id = item.get("id", "") or (
-                                        f"ws_{len(web_search_calls)}"
-                                    )
+                                    item_id = item.get("id", "") or (f"ws_{len(web_search_calls)}")
                                     action = item.get("action")
                                     query = (
-                                        action.get("query", "")
-                                        if isinstance(action, dict)
-                                        else ""
+                                        action.get("query", "") if isinstance(action, dict) else ""
                                     )
                                     web_search_calls[item_id] = {"query": query}
                                     yield _emit_tool_event(
@@ -6042,16 +5752,12 @@ class ExternalProviderClient:
                                             "type": "tool_start",
                                             "tool_name": "web_search",
                                             "tool_call_id": item_id,
-                                            "arguments": (
-                                                {"query": query} if query else {}
-                                            ),
+                                            "arguments": ({"query": query} if query else {}),
                                         }
                                     )
                                     # Per-card text; last call gets overwritten
                                     # with citations at response.completed.
-                                    per_call_result = (
-                                        f"Searching: {query}" if query else ""
-                                    )
+                                    per_call_result = f"Searching: {query}" if query else ""
                                     yield _emit_tool_event(
                                         {
                                             "type": "tool_end",
@@ -6068,14 +5774,10 @@ class ExternalProviderClient:
                                     # `command`. Multiple commands in one
                                     # shell_call get joined with newlines so
                                     # they still render as one card.
-                                    item_id = item.get("id", "") or (
-                                        f"sc_{len(shell_calls)}"
-                                    )
+                                    item_id = item.get("id", "") or (f"sc_{len(shell_calls)}")
                                     action = item.get("action") or {}
                                     commands = (
-                                        action.get("commands")
-                                        if isinstance(action, dict)
-                                        else None
+                                        action.get("commands") if isinstance(action, dict) else None
                                     ) or []
                                     joined_command = (
                                         "\n".join(str(c) for c in commands)
@@ -6091,9 +5793,7 @@ class ExternalProviderClient:
                                         },
                                     )
                                     shell_calls[item_id]["commands"] = (
-                                        list(commands)
-                                        if isinstance(commands, list)
-                                        else []
+                                        list(commands) if isinstance(commands, list) else []
                                     )
                                     yield _emit_tool_event(
                                         {
@@ -6109,19 +5809,14 @@ class ExternalProviderClient:
                                     # Fallback: output may be bundled on the
                                     # shell_call done event itself.
                                     embedded_output = item.get("output")
-                                    if (
-                                        isinstance(embedded_output, list)
-                                        and embedded_output
-                                    ):
+                                    if isinstance(embedded_output, list) and embedded_output:
                                         shell_calls[item_id]["output"] = embedded_output
                                         shell_calls[item_id]["tool_end_emitted"] = True
                                         yield _emit_tool_event(
                                             {
                                                 "type": "tool_end",
                                                 "tool_call_id": item_id,
-                                                "result": _format_shell_output(
-                                                    embedded_output
-                                                ),
+                                                "result": _format_shell_output(embedded_output),
                                             }
                                         )
                                 elif item.get("type") == "shell_call_output":
@@ -6130,15 +5825,11 @@ class ExternalProviderClient:
                                     # tool_call_id on tool_start. Match on
                                     # call_id when present so the matching
                                     # card transitions to complete.
-                                    call_id = (
-                                        item.get("call_id") or item.get("id") or ""
-                                    )
+                                    call_id = item.get("call_id") or item.get("id") or ""
                                     output = item.get("output") or []
                                     # Skip if bundled-output path already
                                     # finalised this card.
-                                    if shell_calls.get(call_id, {}).get(
-                                        "tool_end_emitted"
-                                    ):
+                                    if shell_calls.get(call_id, {}).get("tool_end_emitted"):
                                         continue
                                     if call_id in shell_calls:
                                         shell_calls[call_id]["output"] = output
@@ -6158,9 +5849,7 @@ class ExternalProviderClient:
                                     raw_item_id = item.get("id")
                                     item_id = raw_item_id or f"img_{time.time_ns()}"
                                     prompt_in = (
-                                        item.get("revised_prompt")
-                                        or item.get("prompt")
-                                        or ""
+                                        item.get("revised_prompt") or item.get("prompt") or ""
                                     )
                                     done_arguments = _image_generation_arguments(
                                         prompt_in,
@@ -6175,9 +5864,7 @@ class ExternalProviderClient:
                                                 "arguments": done_arguments,
                                             }
                                         )
-                                    b64 = (
-                                        item.get("result") or item.get("b64_json") or ""
-                                    )
+                                    b64 = item.get("result") or item.get("b64_json") or ""
                                     output_format = item.get("output_format") or "png"
                                     yield _emit_tool_event(
                                         {
@@ -6227,9 +5914,7 @@ class ExternalProviderClient:
                                                                     "type": "function",
                                                                     "function": {
                                                                         "name": fn_name,
-                                                                        "arguments": (
-                                                                            fn_args
-                                                                        ),
+                                                                        "arguments": (fn_args),
                                                                     },
                                                                 }
                                                             ],
@@ -6242,17 +5927,10 @@ class ExternalProviderClient:
                                     )
                                     saw_function_call = True
 
-                            elif (
-                                isinstance(event_type, str)
-                                and "reasoning" in event_type
-                            ):
-                                recorded_reasoning = (
-                                    _record_openai_reasoning_replay_item(event)
-                                )
+                            elif isinstance(event_type, str) and "reasoning" in event_type:
+                                recorded_reasoning = _record_openai_reasoning_replay_item(event)
                                 if recorded_reasoning:
-                                    last_openai_reasoning_replay_item = (
-                                        recorded_reasoning
-                                    )
+                                    last_openai_reasoning_replay_item = recorded_reasoning
                                 reasoning_delta = _extract_reasoning_text(event)
                                 if reasoning_delta:
                                     if not reasoning_open:
@@ -6262,9 +5940,7 @@ class ExternalProviderClient:
                                     reasoning_emitted = True
 
                             elif event_type == "response.completed":
-                                completed_usage = (event.get("response") or {}).get(
-                                    "usage"
-                                )
+                                completed_usage = (event.get("response") or {}).get("usage")
                                 if isinstance(completed_usage, dict):
                                     last_usage = completed_usage
                                 # Flush any unterminated citation tail
@@ -6276,9 +5952,7 @@ class ExternalProviderClient:
                                 # private-use bytes so no garbled
                                 # glyph reaches the user.
                                 if pending_marker_tail:
-                                    flushed = _flush_pending_marker_tail(
-                                        pending_marker_tail
-                                    )
+                                    flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
                                     if flushed:
                                         if reasoning_open:
@@ -6321,8 +5995,7 @@ class ExternalProviderClient:
                                 if (
                                     latched_container_id
                                     and not container_id_emitted
-                                    and latched_container_id
-                                    != openai_code_exec_container_id
+                                    and latched_container_id != openai_code_exec_container_id
                                 ):
                                     yield _emit_tool_event(
                                         {
@@ -6339,9 +6012,7 @@ class ExternalProviderClient:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks: list[str] = []
                                     for cit in all_url_citations:
-                                        line = (
-                                            f"Title: {cit['title']}\nURL: {cit['url']}"
-                                        )
+                                        line = f"Title: {cit['title']}\nURL: {cit['url']}"
                                         if cit.get("snippet"):
                                             line += f"\nSnippet: {cit['snippet']}"
                                         blocks.append(line)
@@ -6375,9 +6046,7 @@ class ExternalProviderClient:
                                             "index": 0,
                                             "delta": {},
                                             "finish_reason": (
-                                                "tool_calls"
-                                                if saw_function_call
-                                                else "stop"
+                                                "tool_calls" if saw_function_call else "stop"
                                             ),
                                         }
                                     ],
@@ -6395,18 +6064,14 @@ class ExternalProviderClient:
                                     yield usage_line
 
                             elif event_type == "response.incomplete":
-                                incomplete_usage = (event.get("response") or {}).get(
-                                    "usage"
-                                )
+                                incomplete_usage = (event.get("response") or {}).get("usage")
                                 if isinstance(incomplete_usage, dict):
                                     last_usage = incomplete_usage
                                 # Same flush as response.completed --
                                 # truncated streams can leave a half-
                                 # marker in the buffer.
                                 if pending_marker_tail:
-                                    flushed = _flush_pending_marker_tail(
-                                        pending_marker_tail
-                                    )
+                                    flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
                                     if flushed:
                                         if reasoning_open:
@@ -6436,9 +6101,7 @@ class ExternalProviderClient:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks = []
                                     for cit in all_url_citations:
-                                        line = (
-                                            f"Title: {cit['title']}\nURL: {cit['url']}"
-                                        )
+                                        line = f"Title: {cit['title']}\nURL: {cit['url']}"
                                         if cit.get("snippet"):
                                             line += f"\nSnippet: {cit['snippet']}"
                                         blocks.append(line)
@@ -6492,9 +6155,7 @@ class ExternalProviderClient:
                             elif event_type in ("response.failed", "error"):
                                 # Surface the failure to the client; let the
                                 # outer route emit [DONE] as part of its cleanup.
-                                error_payload = event.get("response", {}).get(
-                                    "error", {}
-                                ) or {
+                                error_payload = event.get("response", {}).get("error", {}) or {
                                     "message": event.get("message", "Unknown error"),
                                     "code": event.get("code"),
                                 }
@@ -6513,15 +6174,11 @@ class ExternalProviderClient:
                         # support reports of "I clicked Search and got nothing"
                         # can be triaged at a glance: was the tool requested,
                         # did OpenAI invoke it, and how many sources came back?
-                        web_search_requested = bool(
-                            enabled_tools and "web_search" in enabled_tools
-                        )
+                        web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                         web_search_invocations = len(web_search_calls)
                         total_citations = len(all_url_citations)
                         queries = [
-                            sc["query"]
-                            for sc in web_search_calls.values()
-                            if sc.get("query")
+                            sc["query"] for sc in web_search_calls.values() if sc.get("query")
                         ]
                         # cached_input_tokens > 0 on turn N proves
                         # prompt_cache_retention="24h" is letting the previous
@@ -6538,9 +6195,7 @@ class ExternalProviderClient:
                         code_execution_requested = code_execution_enabled_openai
                         code_execution_invocations = len(shell_calls)
                         code_execution_results = sum(
-                            1
-                            for sc in shell_calls.values()
-                            if sc.get("output") is not None
+                            1 for sc in shell_calls.values() if sc.get("output") is not None
                         )
                         logger.info(
                             "OpenAI Responses stream complete (model=%s, "
@@ -6698,9 +6353,7 @@ class ExternalProviderClient:
             if (
                 isinstance(methods, list)
                 and methods
-                and not any(
-                    m in methods for m in ("generateContent", "streamGenerateContent")
-                )
+                and not any(m in methods for m in ("generateContent", "streamGenerateContent"))
             ):
                 continue
             base_id = entry.get("baseModelId")
@@ -6808,19 +6461,11 @@ class ExternalProviderClient:
         logger.info(
             "openai_container_list.response count=%s items=%s",
             len(result),
-            [
-                {"id": c.get("id"), "status": c.get("status")}
-                for c in result
-                if isinstance(c, dict)
-            ],
+            [{"id": c.get("id"), "status": c.get("status")} for c in result if isinstance(c, dict)],
         )
         return result
 
-    async def create_openai_container(
-        self,
-        name: str,
-        ttl_minutes: int,
-    ) -> dict[str, Any]:
+    async def create_openai_container(self, name: str, ttl_minutes: int) -> dict[str, Any]:
         """
         POST /v1/containers with ``expires_after.anchor="last_active_at"``.
         ``ttl_minutes`` is the idle timeout — every API call that
@@ -6894,7 +6539,6 @@ class ExternalProviderClient:
 
 def _provider_display_name(provider_type: str) -> str:
     from core.inference.providers import get_provider_info
-
     info = get_provider_info(provider_type) or {}
     return str(info.get("display_name") or provider_type)
 
@@ -6942,9 +6586,7 @@ def _error_sse_line(status_code: int, message: str, provider_type: str) -> str:
 
 
 def _build_usage_chunk(
-    completion_id: str,
-    provider: Literal["anthropic", "openai"],
-    last_usage: Optional[dict],
+    completion_id: str, provider: Literal["anthropic", "openai"], last_usage: Optional[dict]
 ) -> Optional[str]:
     """Build an OpenAI ``include_usage``-style SSE chunk that carries the
     upstream prompt-cache accounting back to the client.
diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index e1620f5ca3..33647a6cd1 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -68,7 +68,13 @@ class HarmonyTextStreamer:
         _re.DOTALL,
     )
 
-    def __init__(self, tokenizer, *, skip_prompt: bool = True, timeout: float = 0.2):
+    def __init__(
+        self,
+        tokenizer,
+        *,
+        skip_prompt: bool = True,
+        timeout: float = 0.2,
+    ):
         import queue
 
         self.tokenizer = tokenizer
@@ -142,7 +148,6 @@ class HarmonyTextStreamer:
 
     def __next__(self):
         from queue import Empty
-
         while True:
             try:
                 val = self._queue.get(timeout = self.timeout)
@@ -293,9 +298,7 @@ class InferenceBackend:
             if config.is_audio:
                 audio_type = config.audio_type
                 adapter_info = " (LoRA adapter)" if config.is_lora else ""
-                logger.info(
-                    f"Loading audio ({audio_type}) model{adapter_info}: {model_name}"
-                )
+                logger.info(f"Loading audio ({audio_type}) model{adapter_info}: {model_name}")
                 log_gpu_memory(f"Before loading {model_name}")
 
                 if audio_type == "csm":
@@ -330,9 +333,7 @@ class InferenceBackend:
                             from huggingface_hub import snapshot_download
 
                             local_dir = base_path.split("/")[-1]
-                            repo_path = snapshot_download(
-                                base_path, local_dir = local_dir
-                            )
+                            repo_path = snapshot_download(base_path, local_dir = local_dir)
                             abs_repo_path = os.path.abspath(repo_path)
 
                         logger.info(
@@ -443,9 +444,7 @@ class InferenceBackend:
                     )
 
                 # Reject CPU/disk offload for audio models too
-                raise_if_offloaded(
-                    self.models[model_name]["model"], device_map, "Inference"
-                )
+                raise_if_offloaded(self.models[model_name]["model"], device_map, "Inference")
 
                 self.active_model_name = model_name
                 self.loading_models.discard(model_name)
@@ -454,9 +453,7 @@ class InferenceBackend:
                 return True
 
             model_type = "vision" if config.is_vision else "text"
-            adapter_info = (
-                " (LoRA adapter)" if self.models[model_name]["is_lora"] else ""
-            )
+            adapter_info = " (LoRA adapter)" if self.models[model_name]["is_lora"] else ""
             logger.info(f"Loading {model_type} model{adapter_info}: {model_name}")
             log_gpu_memory(f"Before loading {model_name}")
 
@@ -482,14 +479,11 @@ class InferenceBackend:
                 from transformers import ProcessorMixin
 
                 if not (
-                    isinstance(processor, ProcessorMixin)
-                    or hasattr(processor, "image_processor")
+                    isinstance(processor, ProcessorMixin) or hasattr(processor, "image_processor")
                 ):
                     # For LoRA adapters, use the base model. For local merged exports,
                     # read export_metadata.json to find the original base model.
-                    processor_source = (
-                        config.base_model if config.is_lora else config.identifier
-                    )
+                    processor_source = config.base_model if config.is_lora else config.identifier
                     if not config.is_lora and config.is_local:
                         _meta_path = Path(config.path) / "export_metadata.json"
                         try:
@@ -510,9 +504,7 @@ class InferenceBackend:
                         token = hf_token if hf_token and hf_token.strip() else None,
                         trust_remote_code = trust_remote_code,
                     )
-                    logger.info(
-                        f"Loaded {type(processor).__name__} from {processor_source}"
-                    )
+                    logger.info(f"Loaded {type(processor).__name__} from {processor_source}")
 
                 self.models[model_name]["model"] = model
                 self.models[model_name]["tokenizer"] = processor
@@ -536,9 +528,7 @@ class InferenceBackend:
                 self.models[model_name]["model"] = model
                 self.models[model_name]["tokenizer"] = tokenizer
 
-            raise_if_offloaded(
-                self.models[model_name]["model"], device_map, "Inference"
-            )
+            raise_if_offloaded(self.models[model_name]["model"], device_map, "Inference")
 
             # Load chat template info
             self._load_chat_template_info(model_name)
@@ -588,11 +578,7 @@ class InferenceBackend:
                 import sys as _sys
                 from utils.cache_cleanup import clear_unsloth_compiled_cache
 
-                _preserve = (
-                    ["Unsloth*Trainer.py"]
-                    if _sys.platform in ("win32", "darwin")
-                    else None
-                )
+                _preserve = ["Unsloth*Trainer.py"] if _sys.platform in ("win32", "darwin") else None
                 clear_unsloth_compiled_cache(preserve_patterns = _preserve)
 
                 logger.info(f"Model '{model_name}' successfully unloaded.")
@@ -665,13 +651,9 @@ class InferenceBackend:
             base_model_name = lora_config.base_model
 
             # 1. Load the base model if it's not already in memory
-            if base_model_name not in self.models or not self.models[
-                base_model_name
-            ].get("model"):
+            if base_model_name not in self.models or not self.models[base_model_name].get("model"):
                 logger.info(f"Base model '{base_model_name}' not loaded, loading now.")
-                base_config = ModelConfig.from_ui_selection(
-                    base_model_name, None, is_lora = False
-                )
+                base_config = ModelConfig.from_ui_selection(base_model_name, None, is_lora = False)
                 if not self.load_model(
                     base_config,
                     max_seq_length,
@@ -707,9 +689,7 @@ class InferenceBackend:
             logger.error(traceback.format_exc())
             return False, None, None
 
-    def load_adapter(
-        self, base_model_name: str, adapter_path: str, adapter_name: str
-    ) -> bool:
+    def load_adapter(self, base_model_name: str, adapter_path: str, adapter_name: str) -> bool:
         """
         Loads an adapter onto the model ONLY if it's not already attached.
         """
@@ -790,16 +770,12 @@ class InferenceBackend:
                 )
                 model.base_model.disable_adapter_layers()
             else:
-                logger.info(
-                    f"Compare mode: model '{base}' is not a PeftModel, already base"
-                )
+                logger.info(f"Compare mode: model '{base}' is not a PeftModel, already base")
 
         elif use_adapter is True:
             # Re-enable LoRA layers → adapter output
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
-                logger.info(
-                    f"Compare mode: enabling adapters on '{base}' for LoRA generation"
-                )
+                logger.info(f"Compare mode: enabling adapters on '{base}' for LoRA generation")
                 model.base_model.enable_adapter_layers()
             else:
                 logger.warning("use_adapter=true but model is not a PeftModel")
@@ -807,15 +783,11 @@ class InferenceBackend:
         elif isinstance(use_adapter, str):
             # Enable adapters and set the specific one active
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
-                logger.info(
-                    f"Compare mode: enabling adapter '{use_adapter}' on '{base}'"
-                )
+                logger.info(f"Compare mode: enabling adapter '{use_adapter}' on '{base}'")
                 model.base_model.enable_adapter_layers()
                 self.set_active_adapter(base, use_adapter)
             else:
-                logger.warning(
-                    f"use_adapter='{use_adapter}' but model is not a PeftModel"
-                )
+                logger.warning(f"use_adapter='{use_adapter}' but model is not a PeftModel")
 
     def generate_with_adapter_control(
         self,
@@ -996,8 +968,7 @@ class InferenceBackend:
 
             processor = model_info.get("processor")
             has_image_processing = processor is not None and (
-                isinstance(processor, ProcessorMixin)
-                or hasattr(processor, "image_processor")
+                isinstance(processor, ProcessorMixin) or hasattr(processor, "image_processor")
             )
             if has_image_processing:
                 yield from self._generate_vision_response(
@@ -1029,7 +1000,6 @@ class InferenceBackend:
                 MODEL_TO_TEMPLATE_MAPPER,
                 get_tokenizer_chat_template,
             )
-
             model_name_lower = self.active_model_name.lower()
 
             # Check if model has a registered template
@@ -1053,9 +1023,7 @@ class InferenceBackend:
 
         # Step 2: Format with tokenizer.apply_chat_template()
         if system_prompt:
-            template_messages = [
-                {"role": "system", "content": system_prompt}
-            ] + messages
+            template_messages = [{"role": "system", "content": system_prompt}] + messages
         else:
             template_messages = messages
         try:
@@ -1119,7 +1087,6 @@ class InferenceBackend:
         user_message = ""
         if messages and messages[-1]["role"] == "user":
             import re
-
             user_message = messages[-1]["content"]
             user_message = re.sub(r"<img[^>]*>", "", user_message).strip()
 
@@ -1171,9 +1138,7 @@ class InferenceBackend:
         else:
             # Text-only for vision model
             formatted_prompt = self.format_chat_prompt(messages, system_prompt)
-            inputs = raw_tokenizer(formatted_prompt, return_tensors = "pt").to(
-                model.device
-            )
+            inputs = raw_tokenizer(formatted_prompt, return_tensors = "pt").to(model.device)
 
         # Stream with TextIteratorStreamer + background thread
         try:
@@ -1385,7 +1350,9 @@ class InferenceBackend:
             yield f"Error: {str(e)}"
 
     def generate_whisper_response(
-        self, audio_array, cancel_event = None
+        self,
+        audio_array,
+        cancel_event = None,
     ) -> Generator[str, None, None]:
         """Whisper ASR — takes audio numpy array, yields transcribed text.
 
@@ -1411,7 +1378,6 @@ class InferenceBackend:
     def _is_gpt_oss_model(self, model_name: str = None) -> bool:
         """Check if the given (or active) model uses the gpt-oss harmony protocol."""
         from utils.datasets import is_gpt_oss_model_name
-
         return is_gpt_oss_model_name(model_name or self.active_model_name or "")
 
     def generate_stream(
@@ -1459,9 +1425,7 @@ class InferenceBackend:
                         timeout = 0.2,
                     )
                 except Exception as e:
-                    logger.warning(
-                        f"HarmonyTextStreamer init failed, falling back: {e}"
-                    )
+                    logger.warning(f"HarmonyTextStreamer init failed, falling back: {e}")
                     streamer = TextIteratorStreamer(
                         tokenizer,
                         skip_prompt = True,
@@ -1496,7 +1460,6 @@ class InferenceBackend:
                     StoppingCriteria,
                     StoppingCriteriaList,
                 )
-
                 class _CancelCriteria(StoppingCriteria):
                     def __init__(self, ev):
                         self.ev = ev
@@ -1559,9 +1522,7 @@ class InferenceBackend:
                     cancel_event.set()
                 thread.join(timeout = 10)
                 if thread.is_alive():
-                    logger.warning(
-                        "Generation thread did not exit after cancel/join timeout"
-                    )
+                    logger.warning("Generation thread did not exit after cancel/join timeout")
 
             if err.get("msg"):
                 yield f"Error: {err['msg']}"
@@ -1638,21 +1599,12 @@ class InferenceBackend:
                 raise RuntimeError(f"Unknown audio_type: {audio_type}")
 
     def _generate_snac(
-        self,
-        model,
-        tokenizer,
-        text,
-        temperature,
-        top_p,
-        max_new_tokens,
-        repetition_penalty,
+        self, model, tokenizer, text, temperature, top_p, max_new_tokens, repetition_penalty
     ):
         """Generate audio using SNAC codec (Orpheus)."""
         device = model.device
         start_token = torch.tensor([[128259]], device = device)  # START_OF_HUMAN
-        end_tokens = torch.tensor(
-            [[128009, 128260]], device = device
-        )  # EOT, END_OF_HUMAN
+        end_tokens = torch.tensor([[128009, 128260]], device = device)  # EOT, END_OF_HUMAN
         text_ids = tokenizer(text, return_tensors = "pt").input_ids.to(device)
         input_ids = torch.cat([start_token, text_ids, end_tokens], dim = 1)
         attention_mask = torch.ones_like(input_ids)
@@ -1676,20 +1628,12 @@ class InferenceBackend:
         inputs = processor(
             f"[{speaker_id}]{text}", add_special_tokens = True, return_tensors = "pt"
         ).to(model.device)
-        audio_values = model.generate(
-            **inputs, max_new_tokens = max_new_tokens, output_audio = True
-        )
+        audio_values = model.generate(**inputs, max_new_tokens = max_new_tokens, output_audio = True)
         return self._audio_codec_manager.decode_csm(audio_values)
 
-    def _generate_bicodec(
-        self, model, tokenizer, text, temperature, top_k, max_new_tokens
-    ):
+    def _generate_bicodec(self, model, tokenizer, text, temperature, top_k, max_new_tokens):
         """Generate audio using BiCodec (Spark-TTS)."""
-        prompt = (
-            "<|task_tts|><|start_content|>"
-            + text
-            + "<|end_content|><|start_global_token|>"
-        )
+        prompt = "<|task_tts|><|start_content|>" + text + "<|end_content|><|start_global_token|>"
         inputs = tokenizer([prompt], return_tensors = "pt").to(model.device)
         generated = model.generate(
             **inputs,
@@ -1761,9 +1705,7 @@ class InferenceBackend:
             def __init__(self, penalty: float):
                 self.penalty_last_n = 64
                 if not isinstance(penalty, float) or penalty <= 0:
-                    raise ValueError(
-                        f"`penalty` has to be a positive float, but is {penalty}"
-                    )
+                    raise ValueError(f"`penalty` has to be a positive float, but is {penalty}")
                 self.penalty = penalty
 
             @torch.no_grad()
@@ -1788,12 +1730,8 @@ class InferenceBackend:
                         )
                 return scores
 
-        generation_utils.RepetitionPenaltyLogitsProcessor = (
-            RepetitionPenaltyLogitsProcessorPatch
-        )
-        logger.info(
-            "Patched RepetitionPenaltyLogitsProcessor with 64-token window for OuteTTS"
-        )
+        generation_utils.RepetitionPenaltyLogitsProcessor = RepetitionPenaltyLogitsProcessorPatch
+        logger.info("Patched RepetitionPenaltyLogitsProcessor with 64-token window for OuteTTS")
 
     def _apply_chat_template_for_generation(
         self,
@@ -1813,7 +1751,6 @@ class InferenceBackend:
         from core.inference.chat_template_helpers import (
             apply_chat_template_for_generation,
         )
-
         return apply_chat_template_for_generation(
             tokenizer,
             messages,
@@ -1823,7 +1760,11 @@ class InferenceBackend:
             preserve_thinking = preserve_thinking,
         )
 
-    def format_chat_prompt(self, messages: list, system_prompt: str = None) -> str:
+    def format_chat_prompt(
+        self,
+        messages: list,
+        system_prompt: str = None,
+    ) -> str:
         if not self.active_model_name or self.active_model_name not in self.models:
             logger.error("No active model available")
             return ""
@@ -1832,9 +1773,7 @@ class InferenceBackend:
             logger.error("Tokenizer not loaded for active model")
             return ""
 
-        chat_template_info = self.models[self.active_model_name].get(
-            "chat_template_info", {}
-        )
+        chat_template_info = self.models[self.active_model_name].get("chat_template_info", {})
         tokenizer = self.models[self.active_model_name]["tokenizer"]
         tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
 
@@ -1851,14 +1790,11 @@ class InferenceBackend:
 
             if role in ["system", "user", "assistant"] and content.strip():
                 if role == last_role:
-                    logger.debug(
-                        f"Skipping consecutive {role} message to maintain alternation"
-                    )
+                    logger.debug(f"Skipping consecutive {role} message to maintain alternation")
                     continue
 
                 if role == "user":
                     import re
-
                     clean_content = re.sub(r"<[^>]+>", "", content).strip()
                     if clean_content:
                         chat_messages.append({"role": role, "content": clean_content})
@@ -1870,9 +1806,7 @@ class InferenceBackend:
                     continue
 
         if chat_messages and chat_messages[-1]["role"] == "assistant":
-            logger.debug(
-                "Removing final assistant message to ensure proper alternation"
-            )
+            logger.debug("Removing final assistant message to ensure proper alternation")
             chat_messages.pop()
 
         logger.info(f"Sending {len(chat_messages)} messages to tokenizer:")
@@ -1887,10 +1821,7 @@ class InferenceBackend:
             return formatted_prompt
         except Exception as e:
             error_msg = str(e).lower()
-            if (
-                "chat_template is not set" in error_msg
-                or "no template argument" in error_msg
-            ):
+            if "chat_template is not set" in error_msg or "no template argument" in error_msg:
                 logger.info(
                     f"Base model detected - no built-in chat template available, using fallback formatting"
                 )
@@ -1901,9 +1832,7 @@ class InferenceBackend:
             )
 
         if chat_template_info.get("has_template", False):
-            logger.info(
-                "Falling back to manual template formatting based on detected patterns"
-            )
+            logger.info("Falling back to manual template formatting based on detected patterns")
             template_type = chat_template_info.get("format_type", "generic")
             manual_prompt = self._format_chat_manual(
                 chat_messages,
@@ -1916,9 +1845,7 @@ class InferenceBackend:
             logger.info("Using generic chat formatting for base model")
             return self._format_generic_template(chat_messages, {})
 
-    def _format_chat_manual(
-        self, messages: list, template_type: str, special_tokens: dict
-    ) -> str:
+    def _format_chat_manual(self, messages: list, template_type: str, special_tokens: dict) -> str:
         """
         Manual chat formatting fallback for when tokenizer template fails
 
@@ -1949,9 +1876,7 @@ class InferenceBackend:
         for msg in messages:
             role = msg["role"]
             content = msg["content"]
-            formatted += (
-                f"<|start_header_id|>{role}<|end_header_id|>\n\n{content}<|eot_id|>"
-            )
+            formatted += f"<|start_header_id|>{role}<|end_header_id|>\n\n{content}<|eot_id|>"
 
         formatted += "<|start_header_id|>assistant<|end_header_id|>\n\n"
         return formatted
@@ -1980,10 +1905,7 @@ class InferenceBackend:
 
                 formatted += f"[INST] {user_content} [/INST]"
 
-                if (
-                    i + 1 < len(conversation)
-                    and conversation[i + 1]["role"] == "assistant"
-                ):
+                if i + 1 < len(conversation) and conversation[i + 1]["role"] == "assistant":
                     formatted += f" {conversation[i + 1]['content']}</s>"
                     i += 2
                 else:
@@ -2088,7 +2010,11 @@ class InferenceBackend:
         except Exception as e:
             logger.warning(f"Could not fully reset generation state: {e}")
 
-    def resize_image(self, img, max_size: int = 800):
+    def resize_image(
+        self,
+        img,
+        max_size: int = 800,
+    ):
         """Resize image while maintaining aspect ratio if either dimension exceeds max_size"""
         if img is None:
             return None
@@ -2107,7 +2033,6 @@ class InferenceBackend:
             # Strip harmony protocol tokens and other gpt-oss added tokens
             # (e.g. <|return|>) that may leak past the streamer.
             import re
-
             text = re.sub(r"<\|[a-z_]+\|>", "", text)
             return text.strip()
 
@@ -2119,9 +2044,7 @@ class InferenceBackend:
         return text.strip()
 
     def _load_chat_template_info(self, model_name: str):
-        if model_name not in self.models or not self.models[model_name].get(
-            "tokenizer"
-        ):
+        if model_name not in self.models or not self.models[model_name].get("tokenizer"):
             return
 
         tokenizer = self.models[model_name]["tokenizer"]
@@ -2139,9 +2062,7 @@ class InferenceBackend:
             # Try exact match first
             model_name_lower = model_name.lower()
             if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
-                chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[
-                    model_name_lower
-                ]
+                chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[model_name_lower]
                 logger.info(
                     f"Detected template '{chat_template_info['template_name']}' for {model_name} from mapper"
                 )
@@ -2149,17 +2070,13 @@ class InferenceBackend:
                 # Try partial match (for variants like model_name-bnb-4bit)
                 for key in MODEL_TO_TEMPLATE_MAPPER:
                     if key in model_name_lower or model_name_lower in key:
-                        chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[
-                            key
-                        ]
+                        chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[key]
                         logger.info(
                             f"Detected template '{chat_template_info['template_name']}' for {model_name} (partial match)"
                         )
                         break
         except Exception as e:
-            logger.warning(
-                f"Could not detect template from mapper for {model_name}: {e}"
-            )
+            logger.warning(f"Could not detect template from mapper for {model_name}: {e}")
 
         try:
             if hasattr(tokenizer, "chat_template") and tokenizer.chat_template:
@@ -2168,10 +2085,7 @@ class InferenceBackend:
 
                 template_str = tokenizer.chat_template.lower()
 
-                if (
-                    "start_header_id" in template_str
-                    and "end_header_id" in template_str
-                ):
+                if "start_header_id" in template_str and "end_header_id" in template_str:
                     chat_template_info["format_type"] = "llama3"
                 elif "[inst]" in template_str and "[/inst]" in template_str:
                     chat_template_info["format_type"] = "mistral"
@@ -2198,9 +2112,7 @@ class InferenceBackend:
                 chat_template_info["special_tokens"] = special_tokens
 
             else:
-                logger.info(
-                    f"No chat template found for {model_name}, will use generic formatting"
-                )
+                logger.info(f"No chat template found for {model_name}, will use generic formatting")
 
         except Exception as e:
             logger.error(f"Error loading chat template info for {model_name}: {e}")
@@ -2212,9 +2124,7 @@ class InferenceBackend:
                 f"Chat template loaded for {model_name}: {chat_template_info['format_type']} format"
             )
         else:
-            logger.info(
-                f"No built-in chat template for {model_name}, will use generic formatting"
-            )
+            logger.info(f"No built-in chat template for {model_name}, will use generic formatting")
 
     def get_current_model(self) -> Optional[str]:
         """Get currently active model name"""
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 0f23549138..72dcc11beb 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -220,7 +220,6 @@ def _period_from_layer_types(layer_types: list) -> Optional[int]:
 def _fetch_swa_entry_from_hf(repo_id: str) -> Optional[object]:
     try:
         from huggingface_hub import hf_hub_download
-
         cfg_path = hf_hub_download(repo_id, "config.json", repo_type = "model")
         with open(cfg_path) as f:
             cfg = json.load(f)
@@ -233,9 +232,7 @@ def _fetch_swa_entry_from_hf(repo_id: str) -> Optional[object]:
         return period
     lt = src.get("layer_types")
     if isinstance(lt, list) and lt:
-        return _period_from_layer_types(lt) or [
-            "full" not in str(t).lower() for t in lt
-        ]
+        return _period_from_layer_types(lt) or ["full" not in str(t).lower() for t in lt]
     return None
 
 
@@ -255,15 +252,11 @@ def _swa_entry_from_config_obj(cfg) -> Optional[object]:
         return period
     lt = getattr(src, "layer_types", None)
     if isinstance(lt, list) and lt:
-        return _period_from_layer_types(lt) or [
-            "full" not in str(t).lower() for t in lt
-        ]
+        return _period_from_layer_types(lt) or ["full" not in str(t).lower() for t in lt]
     return None
 
 
-_SWA_PATTERN_SOURCE_RE = re.compile(
-    r"sliding_window_pattern\s*(?::\s*[\w\[\], ]*)?\s*=\s*(\d+)"
-)
+_SWA_PATTERN_SOURCE_RE = re.compile(r"sliding_window_pattern\s*(?::\s*[\w\[\], ]*)?\s*=\s*(\d+)")
 
 
 def _resolve_swa_entry_from_transformers(arch: str) -> Optional[object]:
@@ -383,7 +376,6 @@ def _hf_repo_from_url(url: Optional[str]) -> Optional[str]:
 # at module level.  See PR description for the full explanation.
 def _extract_model_size_b(model_id: str):
     from utils.models import extract_model_size_b
-
     return extract_model_size_b(model_id)
 
 
@@ -465,10 +457,7 @@ def detect_reasoning_flags(
     return flags
 
 
-def _is_mtp_model_name(
-    model_identifier: Optional[str],
-    gguf_path: Optional[str] = None,
-) -> bool:
+def _is_mtp_model_name(model_identifier: Optional[str], gguf_path: Optional[str] = None) -> bool:
     """Name-based MTP detector. Fallback for the metadata signal."""
     for cand in (model_identifier, Path(gguf_path).name if gguf_path else None):
         if cand and "-mtp" in cand.lower():
@@ -1047,9 +1036,7 @@ class LlamaCppBackend:
         if build_path.is_file():
             return str(build_path)
         if sys.platform == "win32":
-            win_path = (
-                project_root / "llama.cpp" / "build" / "bin" / "Release" / binary_name
-            )
+            win_path = project_root / "llama.cpp" / "build" / "bin" / "Release" / binary_name
             if win_path.is_file():
                 return str(win_path)
 
@@ -1071,9 +1058,7 @@ class LlamaCppBackend:
     _capability_cache: dict[tuple[str, int], dict[str, object]] = {}
 
     @classmethod
-    def probe_server_capabilities(
-        cls, binary: Optional[str] = None
-    ) -> dict[str, object]:
+    def probe_server_capabilities(cls, binary: Optional[str] = None) -> dict[str, object]:
         """Parse `llama-server --help` for feature flags. Returns
         {found, mtp_token, supports_mtp, ngram_mod_flavor,
         supports_ngram_mod, spec_draft_n_max_flag}.
@@ -1142,9 +1127,7 @@ class LlamaCppBackend:
                     # first token that isn't itself a flag, so flag
                     # references inside descriptions are ignored.
                     for tok in re.split(r"[,\s]+", stripped):
-                        if tok.startswith("--") and re.match(
-                            r"--[A-Za-z][A-Za-z0-9_-]*$", tok
-                        ):
+                        if tok.startswith("--") and re.match(r"--[A-Za-z][A-Za-z0-9_-]*$", tok):
                             current_flags.append(tok)
                         elif tok.startswith("-") and len(tok) > 1:
                             # short alias like -fa; keep scanning aliases.
@@ -1228,11 +1211,7 @@ class LlamaCppBackend:
         if m:
             prefix, _, num_total = m.group(1), m.group(2), m.group(3)
             sibling_pat = re.compile(
-                r"^"
-                + re.escape(prefix)
-                + r"-\d{5}-of-"
-                + re.escape(num_total)
-                + r"\.gguf$"
+                r"^" + re.escape(prefix) + r"-\d{5}-of-" + re.escape(num_total) + r"\.gguf$"
             )
             for sibling in main.parent.iterdir():
                 if sibling != main and sibling_pat.match(sibling.name):
@@ -1255,10 +1234,7 @@ class LlamaCppBackend:
                 return False
             for _i in range(torch.cuda.device_count()):
                 try:
-                    _arch = (
-                        getattr(torch.cuda.get_device_properties(_i), "gcnArchName", "")
-                        or ""
-                    )
+                    _arch = getattr(torch.cuda.get_device_properties(_i), "gcnArchName", "") or ""
                 except Exception:
                     continue
                 if _arch.split(":")[0].strip().lower() in {"gfx1150", "gfx1151"}:
@@ -1308,9 +1284,7 @@ class LlamaCppBackend:
                         # an empty token. An explicitly empty mask (CVD="")
                         # yields an empty `allowed` set so all GPUs are
                         # filtered out, matching the codebase convention.
-                        allowed = set(
-                            int(x.strip()) for x in cvd.split(",") if x.strip()
-                        )
+                        allowed = set(int(x.strip()) for x in cvd.split(",") if x.strip())
                     except ValueError:
                         pass
                 gpus: list[tuple[int, int]] = []
@@ -1527,9 +1501,7 @@ class LlamaCppBackend:
         return out
 
     @staticmethod
-    def _build_windows_path_dirs(
-        binary_dir: str, prefix: str, cuda_path: str
-    ) -> list[str]:
+    def _build_windows_path_dirs(binary_dir: str, prefix: str, cuda_path: str) -> list[str]:
         """Ordered PATH entries the win32 branch of start_llama_server
         prepends so llama-server.exe resolves cudart / cublas DLLs:
         binary_dir, pip nvidia wheels, CUDA_PATH/bin, CUDA_PATH/bin/x64.
@@ -1548,8 +1520,7 @@ class LlamaCppBackend:
 
     @staticmethod
     def _select_gpus(
-        model_size_bytes: int,
-        gpus: list[tuple[int, int]],
+        model_size_bytes: int, gpus: list[tuple[int, int]]
     ) -> tuple[Optional[list[int]], bool]:
         """Pick GPU(s) for a model based on estimated VRAM and free memory.
 
@@ -1612,9 +1583,7 @@ class LlamaCppBackend:
         )
 
     def _kv_heads_for_layer(self, layer_idx: int, fallback: int) -> int:
-        if self._n_kv_heads_by_layer is not None and layer_idx < len(
-            self._n_kv_heads_by_layer
-        ):
+        if self._n_kv_heads_by_layer is not None and layer_idx < len(self._n_kv_heads_by_layer):
             return self._n_kv_heads_by_layer[layer_idx]
         return fallback
 
@@ -1699,10 +1668,7 @@ class LlamaCppBackend:
 
         # Path 2: Hybrid Mamba/Attention (Qwen3.5-27B, Qwen3.5-35B-A3B)
         # Only 1 in N layers is attention; the rest are Mamba (no KV cache).
-        if (
-            self._ssm_inner_size is not None
-            and self._full_attention_interval is not None
-        ):
+        if self._ssm_inner_size is not None and self._full_attention_interval is not None:
             fai = self._full_attention_interval
             n_attn = -(-n_layers // fai) if fai > 0 else n_layers  # ceiling division
             if key_len is not None and val_len is not None:
@@ -1736,9 +1702,7 @@ class LlamaCppBackend:
             # cells = per_slot_ctx and the slots*per-slot product collapses
             # back to the constant ``n_ctx`` total.  Otherwise SWA caches
             # 2*sliding_window per slot, clamped at the per-slot ctx.
-            swa_cells_per_slot = (
-                per_slot_ctx if swa_full else min(n_ctx, 2 * swa, per_slot_ctx)
-            )
+            swa_cells_per_slot = per_slot_ctx if swa_full else min(n_ctx, 2 * swa, per_slot_ctx)
             key_len_swa = self._kv_key_length_swa or key_len
             val_len_swa = self._kv_value_length_swa or val_len
             if self._sliding_window_pattern is not None:
@@ -1755,10 +1719,7 @@ class LlamaCppBackend:
                     )
                     if is_swa:
                         swa_bytes_per_slot += (
-                            swa_cells_per_slot
-                            * layer_n_kv
-                            * (key_len_swa + val_len_swa)
-                            * bpe
+                            swa_cells_per_slot * layer_n_kv * (key_len_swa + val_len_swa) * bpe
                         )
                         if ctx_checkpoints > 0 and not swa_full:
                             checkpoint_extra_per_slot += (
@@ -1770,10 +1731,7 @@ class LlamaCppBackend:
                             )
                     else:
                         global_bytes += n_ctx * layer_n_kv * (key_len + val_len) * bpe
-                return int(
-                    global_bytes
-                    + slots * (swa_bytes_per_slot + checkpoint_extra_per_slot)
-                )
+                return int(global_bytes + slots * (swa_bytes_per_slot + checkpoint_extra_per_slot))
             n_global = max(1, n_layers_kv // 4)
             n_swa = n_layers_kv - n_global
             kv_per_token = n_kv * (key_len + val_len) * bpe
@@ -1785,9 +1743,7 @@ class LlamaCppBackend:
                 if ctx_checkpoints > 0 and not swa_full
                 else 0.0
             )
-            return int(
-                global_bytes + slots * (swa_bytes_per_slot + checkpoint_extra_per_slot)
-            )
+            return int(global_bytes + slots * (swa_bytes_per_slot + checkpoint_extra_per_slot))
 
         # Path 4: Standard GQA with explicit key/value dimensions
         if key_len is not None and val_len is not None:
@@ -1910,9 +1866,7 @@ class LlamaCppBackend:
             from huggingface_hub import get_paths_info, list_repo_files
 
             files = list_repo_files(hf_repo, token = hf_token)
-            gguf_files = [
-                f for f in files if f.endswith(".gguf") and "mmproj" not in f.lower()
-            ]
+            gguf_files = [f for f in files if f.endswith(".gguf") and "mmproj" not in f.lower()]
             if not gguf_files:
                 return None
 
@@ -2128,10 +2082,7 @@ class LlamaCppBackend:
                             if vtype == 8:  # STRING
                                 slen = struct.unpack("<Q", f.read(8))[0]
                                 val_s = f.read(slen).decode("utf-8")
-                                if (
-                                    key.startswith("general.")
-                                    and key != "general.architecture"
-                                ):
+                                if key.startswith("general.") and key != "general.architecture":
                                     general[key] = val_s
                                 if key == "general.architecture":
                                     arch = val_s
@@ -2178,13 +2129,8 @@ class LlamaCppBackend:
                                     self._n_kv_heads_by_layer = [int(x) for x in val_a]
                                     if self._n_kv_heads is None and val_a:
                                         self._n_kv_heads = max(int(x) for x in val_a)
-                                elif (
-                                    attr == "sliding_window_pattern"
-                                    and val_a is not None
-                                ):
-                                    self._sliding_window_pattern = [
-                                        bool(x) for x in val_a
-                                    ]
+                                elif attr == "sliding_window_pattern" and val_a is not None:
+                                    self._sliding_window_pattern = [bool(x) for x in val_a]
                                     sliding_window_pattern_period = None
                             else:
                                 self._gguf_skip_value(f, vtype)
@@ -2203,17 +2149,12 @@ class LlamaCppBackend:
                 and self._n_layers
             ):
                 self._sliding_window_pattern = [
-                    (i + 1) % sliding_window_pattern_period != 0
-                    for i in range(self._n_layers)
+                    (i + 1) % sliding_window_pattern_period != 0 for i in range(self._n_layers)
                 ]
 
             # Otherwise hand off to the resolver (cache / bootstrap /
             # transformers / HF). See `_resolve_swa_pattern`.
-            if (
-                self._sliding_window_pattern is None
-                and self._sliding_window
-                and self._n_layers
-            ):
+            if self._sliding_window_pattern is None and self._sliding_window and self._n_layers:
                 hf_repo_candidates = (
                     general.get("general.source.huggingface.repository"),
                     _hf_repo_from_url(general.get("general.source.url")),
@@ -2229,8 +2170,7 @@ class LlamaCppBackend:
                     (
                         f"{general['general.organization']}/"
                         f"{general['general.basename']}".replace(" ", "-")
-                        if general.get("general.organization")
-                        and general.get("general.basename")
+                        if general.get("general.organization") and general.get("general.basename")
                         else None
                     ),
                 )
@@ -2243,9 +2183,7 @@ class LlamaCppBackend:
             if self._context_length:
                 logger.info(f"GGUF metadata: context_length={self._context_length}")
             if self._chat_template:
-                logger.info(
-                    f"GGUF metadata: chat_template={len(self._chat_template)} chars"
-                )
+                logger.info(f"GGUF metadata: chat_template={len(self._chat_template)} chars")
                 # Detect thinking/reasoning support from chat template
                 flags = detect_reasoning_flags(
                     self._chat_template,
@@ -2296,9 +2234,7 @@ class LlamaCppBackend:
                     r"(?<![a-zA-Z0-9])" + re.escape(variant_lower) + r"(?![a-zA-Z0-9])"
                 )
                 gguf_files = sorted(
-                    f
-                    for f in files
-                    if f.endswith(".gguf") and boundary.search(f.lower())
+                    f for f in files if f.endswith(".gguf") and boundary.search(f.lower())
                 )
                 if gguf_files:
                     gguf_filename = gguf_files[0]
@@ -2307,15 +2243,9 @@ class LlamaCppBackend:
                         prefix = m.group(1)
                         total = m.group(3)
                         sibling_pat = re.compile(
-                            r"^"
-                            + re.escape(prefix)
-                            + r"-\d{5}-of-"
-                            + re.escape(total)
-                            + r"\.gguf$"
+                            r"^" + re.escape(prefix) + r"-\d{5}-of-" + re.escape(total) + r"\.gguf$"
                         )
-                        gguf_extra_shards = [
-                            f for f in gguf_files[1:] if sibling_pat.match(f)
-                        ]
+                        gguf_extra_shards = [f for f in gguf_files[1:] if sibling_pat.match(f)]
             except Exception as e:
                 logger.warning(f"Could not list repo files: {e}")
 
@@ -2327,11 +2257,8 @@ class LlamaCppBackend:
             if not gguf_filename:
                 try:
                     from utils.models.model_config import _iter_hf_cache_snapshots
-
                     boundary = re.compile(
-                        r"(?<![a-zA-Z0-9])"
-                        + re.escape(hf_variant.lower())
-                        + r"(?![a-zA-Z0-9])"
+                        r"(?<![a-zA-Z0-9])" + re.escape(hf_variant.lower()) + r"(?![a-zA-Z0-9])"
                     )
                     for snap in _iter_hf_cache_snapshots(hf_repo):
                         matches = sorted(
@@ -2355,9 +2282,7 @@ class LlamaCppBackend:
                                 + r"\.gguf$"
                             )
                             gguf_extra_shards = [
-                                f
-                                for f in matches[1:]
-                                if sibling_pat.match(Path(f).name)
+                                f for f in matches[1:] if sibling_pat.match(Path(f).name)
                             ]
                         logger.info(
                             "Resolved variant %s -> %s from local HF cache",
@@ -2525,7 +2450,6 @@ class LlamaCppBackend:
         target: Optional[str] = None
         try:
             from huggingface_hub import list_repo_files
-
             target = _pick_mmproj(list_repo_files(hf_repo, token = hf_token))
         except Exception as e:
             logger.debug(f"Could not list repo files for mmproj: {e}")
@@ -2535,11 +2459,8 @@ class LlamaCppBackend:
         if target is None:
             try:
                 from utils.models.model_config import _iter_hf_cache_snapshots
-
                 for snap in _iter_hf_cache_snapshots(hf_repo):
-                    rel_files = [
-                        p.relative_to(snap).as_posix() for p in snap.rglob("*.gguf")
-                    ]
+                    rel_files = [p.relative_to(snap).as_posix() for p in snap.rglob("*.gguf")]
                     target = _pick_mmproj(rel_files)
                     if target is not None:
                         logger.info("Resolved mmproj %s from local HF cache", target)
@@ -2565,10 +2486,7 @@ class LlamaCppBackend:
             return None
 
     def _resolve_launch_mmproj_path(
-        self,
-        *,
-        model_path: str,
-        mmproj_path: Optional[str],
+        self, *, model_path: str, mmproj_path: Optional[str]
     ) -> Optional[str]:
         """Return mmproj_path iff it exists on disk AND matches the model family.
 
@@ -2622,9 +2540,7 @@ class LlamaCppBackend:
 
     @staticmethod
     def _classify_llama_start_failure(
-        output: str,
-        gguf_path: Optional[str],
-        model_identifier: Optional[str],
+        output: str, gguf_path: Optional[str], model_identifier: Optional[str]
     ) -> str:
         """Explain *why* llama-server failed to start, from its output.
 
@@ -2788,9 +2704,9 @@ class LlamaCppBackend:
                     # Re-derive after a retried probe (_mmproj_has_audio persists).
                     from utils.models.model_config import is_audio_input_type
 
-                    self._has_audio_input = bool(
-                        is_audio_input_type(self._audio_type)
-                    ) or bool(self._mmproj_has_audio)
+                    self._has_audio_input = bool(is_audio_input_type(self._audio_type)) or bool(
+                        self._mmproj_has_audio
+                    )
                 if not self._healthy:
                     return False
                 return True
@@ -2867,18 +2783,10 @@ class LlamaCppBackend:
                 cache_override = parse_cache_override(extra_args)
                 cache_type_kv = resolve_cache_type_kv(extra_args, cache_type_kv)
                 if ctx_override is not None and ctx_override > 0:
-                    logger.info(
-                        f"User --ctx-size {ctx_override} honored; "
-                        "skipping auto-reduce"
-                    )
+                    logger.info(f"User --ctx-size {ctx_override} honored; skipping auto-reduce")
                 if cache_override is not None:
-                    logger.info(
-                        f"User --cache-type-k/-v {cache_override} "
-                        "honored for KV estimate"
-                    )
-                effective_ctx = (
-                    requested_ctx if requested_ctx > 0 else (self._context_length or 0)
-                )
+                    logger.info(f"User --cache-type-k/-v {cache_override} honored for KV estimate")
+                effective_ctx = requested_ctx if requested_ctx > 0 else (self._context_length or 0)
                 max_available_ctx = self._context_length or effective_ctx
                 gpus: list[tuple[int, int]] = []
                 try:
@@ -2910,9 +2818,7 @@ class LlamaCppBackend:
                     _mtp_canonical = _canonicalize_spec_mode(speculative_type)
                     _mtp_effective = _mtp_canonical or "auto"
                     _mtp_size_for_fit = _extract_model_size_b(model_identifier)
-                    _mtp_sub_3b_for_fit = (
-                        _mtp_size_for_fit is not None and _mtp_size_for_fit < 3.0
-                    )
+                    _mtp_sub_3b_for_fit = _mtp_size_for_fit is not None and _mtp_size_for_fit < 3.0
                     _mtp_will_engage = bool(
                         not _extra_args_set_spec_type(extra_args)
                         and (
@@ -2950,9 +2856,7 @@ class LlamaCppBackend:
                         # bounds), independent of the currently requested context.
                         native_ctx_for_cap = self._context_length or effective_ctx
                         if native_ctx_for_cap > 0:
-                            ranked_for_cap = sorted(
-                                gpus, key = lambda g: g[1], reverse = True
-                            )
+                            ranked_for_cap = sorted(gpus, key = lambda g: g[1], reverse = True)
                             best_cap = 0
                             for n_gpus in range(1, len(ranked_for_cap) + 1):
                                 subset = ranked_for_cap[:n_gpus]
@@ -2990,15 +2894,10 @@ class LlamaCppBackend:
                             # -ngl (CPU layer offload). The UI is expected to
                             # have surfaced the "might be slower" warning before
                             # the user submitted a ctx above the fit ceiling.
-                            requested_total = (
-                                model_size
-                                + self._estimate_kv_cache_bytes(
-                                    effective_ctx, cache_type_kv, n_parallel = n_parallel
-                                )
-                            )
-                            gpu_indices, use_fit = self._select_gpus(
-                                requested_total, gpus
+                            requested_total = model_size + self._estimate_kv_cache_bytes(
+                                effective_ctx, cache_type_kv, n_parallel = n_parallel
                             )
+                            gpu_indices, use_fit = self._select_gpus(requested_total, gpus)
                             # No silent shrink: effective_ctx stays == requested_ctx.
                         else:
                             # Auto context: prefer fewer GPUs, cap context
@@ -3043,9 +2942,7 @@ class LlamaCppBackend:
                                         )
                                         total_mib = (model_size + kv) / (1024 * 1024)
                                         if total_mib <= pool_mib * pin_fraction:
-                                            gpu_indices = sorted(
-                                                idx for idx, _ in subset
-                                            )
+                                            gpu_indices = sorted(idx for idx, _ in subset)
                                             use_fit = False
                                             break
 
@@ -3062,9 +2959,7 @@ class LlamaCppBackend:
                             # Weights don't fit on any subset. Default the UI to
                             # 4096 so the slider doesn't land on an unusable native
                             # context. --fit on will flex -ngl at runtime.
-                            effective_ctx = (
-                                min(4096, effective_ctx) if effective_ctx > 0 else 4096
-                            )
+                            effective_ctx = min(4096, effective_ctx) if effective_ctx > 0 else 4096
 
                     if effective_ctx < original_ctx:
                         kv_est = self._estimate_kv_cache_bytes(
@@ -3112,7 +3007,6 @@ class LlamaCppBackend:
                         from utils.models.gguf_metadata import (
                             read_mmproj_audio_capability,
                         )
-
                         self._mmproj_has_audio = bool(
                             read_mmproj_audio_capability(launch_mmproj_path)
                         )
@@ -3144,9 +3038,7 @@ class LlamaCppBackend:
                 # -1 = llama.cpp auto-detect (physical cores). Pass explicitly so we
                 # do not inherit llama-server's internal default, which has historically
                 # varied (hardware concurrency incl. hyperthreads on some builds).
-                cmd.extend(
-                    ["--threads", str(n_threads if n_threads is not None else -1)]
-                )
+                cmd.extend(["--threads", str(n_threads if n_threads is not None else -1)])
 
                 # Always enable Jinja chat template rendering for proper template support
                 cmd.extend(["--jinja"])
@@ -3224,9 +3116,7 @@ class LlamaCppBackend:
                     self._supports_reasoning = flags["supports_reasoning"]
                     self._reasoning_style = flags["reasoning_style"]
                     self._reasoning_always_on = flags["reasoning_always_on"]
-                    self._supports_preserve_thinking = flags[
-                        "supports_preserve_thinking"
-                    ]
+                    self._supports_preserve_thinking = flags["supports_preserve_thinking"]
                     self._supports_tools = flags["supports_tools"]
 
                     self._chat_template_file = tempfile.NamedTemporaryFile(
@@ -3238,9 +3128,7 @@ class LlamaCppBackend:
                     self._chat_template_file.write(chat_template_override)
                     self._chat_template_file.close()
                     cmd.extend(["--chat-template-file", self._chat_template_file.name])
-                    logger.info(
-                        f"Using custom chat template file: {self._chat_template_file.name}"
-                    )
+                    logger.info(f"Using custom chat template file: {self._chat_template_file.name}")
 
                 # For reasoning models, set default thinking mode.
                 # Qwen3.5/3.6 models below 9B (0.8B, 2B, 4B) disable thinking by default.
@@ -3274,9 +3162,7 @@ class LlamaCppBackend:
                 if _os.getenv("UNSLOTH_DIRECT_STREAM", "0") == "1":
                     self._api_key = _secrets.token_urlsafe(32)
                     cmd.extend(["--api-key", self._api_key])
-                    logger.info(
-                        "llama-server started with --api-key for direct streaming"
-                    )
+                    logger.info("llama-server started with --api-key for direct streaming")
                 else:
                     self._api_key = None
 
@@ -3287,9 +3173,7 @@ class LlamaCppBackend:
                 # the managed-flag denylist via validate_extra_args().
                 if extra_args:
                     cmd.extend(str(a) for a in extra_args)
-                    logger.info(
-                        f"Appending user extra args to llama-server: {list(extra_args)}"
-                    )
+                    logger.info(f"Appending user extra args to llama-server: {list(extra_args)}")
 
                 _log_cmd = list(cmd)
                 if "--api-key" in _log_cmd:
@@ -3309,9 +3193,7 @@ class LlamaCppBackend:
                 # shared system RAM. setdefault so a user value wins.
                 if self._amd_apu_wants_unified_memory():
                     env.setdefault("GGML_CUDA_ENABLE_UNIFIED_MEMORY", "1")
-                    logger.info(
-                        "AMD unified-memory APU: set GGML_CUDA_ENABLE_UNIFIED_MEMORY=1"
-                    )
+                    logger.info("AMD unified-memory APU: set GGML_CUDA_ENABLE_UNIFIED_MEMORY=1")
 
                 if sys.platform == "win32":
                     # See _build_windows_path_dirs for ordering. #5106.
@@ -3331,13 +3213,9 @@ class LlamaCppBackend:
                     # not exist, causing a silent crash on the first GEMM.
                     # ROCBLAS_TENSILE_LIBPATH overrides that search to point at
                     # the ROCm installation where the kernel files actually are.
-                    _hip_path = os.environ.get(
-                        "HIP_PATH", os.environ.get("ROCM_PATH", "")
-                    )
+                    _hip_path = os.environ.get("HIP_PATH", os.environ.get("ROCM_PATH", ""))
                     if _hip_path:
-                        _rocblas_lib = os.path.join(
-                            _hip_path, "bin", "rocblas", "library"
-                        )
+                        _rocblas_lib = os.path.join(_hip_path, "bin", "rocblas", "library")
                         if os.path.isdir(_rocblas_lib):
                             env.setdefault("ROCBLAS_TENSILE_LIBPATH", _rocblas_lib)
                 else:
@@ -3402,9 +3280,7 @@ class LlamaCppBackend:
                             lib_dirs.append(cuda_lib)
                     existing_ld = env.get("LD_LIBRARY_PATH", "")
                     new_ld = ":".join(lib_dirs)
-                    env["LD_LIBRARY_PATH"] = (
-                        f"{new_ld}:{existing_ld}" if existing_ld else new_ld
-                    )
+                    env["LD_LIBRARY_PATH"] = f"{new_ld}:{existing_ld}" if existing_ld else new_ld
 
                 # Pin to selected GPU(s). On ROCm, llama-server (and any torch
                 # in the subprocess) honors HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES;
@@ -3415,14 +3291,11 @@ class LlamaCppBackend:
                     env["CUDA_VISIBLE_DEVICES"] = pinned
                     try:
                         import torch as _torch
-
                         if getattr(_torch.version, "hip", None) is not None:
                             env["HIP_VISIBLE_DEVICES"] = pinned
                             env["ROCR_VISIBLE_DEVICES"] = pinned
                     except Exception as e:
-                        logger.debug(
-                            "Failed to set ROCm visibility env vars for child: %s", e
-                        )
+                        logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 
                 # Defensive kill: if a concurrent load slipped past Phase 1
                 # (because its `self._process` was None at the time) and
@@ -3483,7 +3356,6 @@ class LlamaCppBackend:
                 elif gguf_path:
                     try:
                         from utils.models.model_config import _extract_quant_label
-
                         self._hf_variant = _extract_quant_label(gguf_path)
                     except Exception:
                         self._hf_variant = None
@@ -3499,9 +3371,7 @@ class LlamaCppBackend:
                     effective_ctx if effective_ctx > 0 else self._context_length
                 )
                 self._max_context_length = (
-                    max_available_ctx
-                    if max_available_ctx > 0
-                    else self._effective_context_length
+                    max_available_ctx if max_available_ctx > 0 else self._effective_context_length
                 )
 
                 # Wait for llama-server to become healthy
@@ -3543,8 +3413,7 @@ class LlamaCppBackend:
                     )
 
                 logger.info(
-                    f"llama-server ready on port {self._port} "
-                    f"for model '{model_identifier}'"
+                    f"llama-server ready on port {self._port} " f"for model '{model_identifier}'"
                 )
 
             # Probe outside _lock (interruptible by /unload); init inside.
@@ -3893,9 +3762,7 @@ class LlamaCppBackend:
         return True
 
     def _classify_gpu_offload(
-        self,
-        expected_gpu: bool,
-        detected_gpus: list[tuple[int, int]],
+        self, expected_gpu: bool, detected_gpus: list[tuple[int, int]]
     ) -> Optional[bool]:
         """True if a GPU model buffer was allocated, False if only CPU
         buffers landed despite GPU intent, None when there's no signal
@@ -3974,7 +3841,6 @@ class LlamaCppBackend:
             if hasattr(self, "_chat_template_file") and self._chat_template_file:
                 try:
                     import os
-
                     os.unlink(self._chat_template_file.name)
                 except Exception:
                     pass
@@ -4105,7 +3971,6 @@ class LlamaCppBackend:
             # Linux when psutil is not installed.
             try:
                 import psutil
-
                 has_psutil = True
             except ImportError:
                 has_psutil = False
@@ -4137,8 +4002,7 @@ class LlamaCppBackend:
 
                         proc.kill()
                         logger.info(
-                            f"Killed orphaned llama-server process "
-                            f"(pid={proc.info['pid']})"
+                            f"Killed orphaned llama-server process " f"(pid={proc.info['pid']})"
                         )
                     except (
                         psutil.NoSuchProcess,
@@ -4203,7 +4067,11 @@ class LlamaCppBackend:
         """atexit handler to ensure llama-server is terminated."""
         self._kill_process()
 
-    def _wait_for_health(self, timeout: float = 120.0, interval: float = 0.5) -> bool:
+    def _wait_for_health(
+        self,
+        timeout: float = 120.0,
+        interval: float = 0.5,
+    ) -> bool:
         """
         Poll llama-server's /health endpoint until it responds 200.
 
@@ -4256,10 +4124,7 @@ class LlamaCppBackend:
         return _shared_parse_tool_calls_from_text(content)
 
     @staticmethod
-    def _build_openai_messages(
-        messages: list[dict],
-        image_b64: Optional[str] = None,
-    ) -> list[dict]:
+    def _build_openai_messages(messages: list[dict], image_b64: Optional[str] = None) -> list[dict]:
         """
         Build OpenAI-format messages, optionally injecting an image_url
         content part into the last user message for vision models.
@@ -4294,8 +4159,7 @@ class LlamaCppBackend:
 
     @staticmethod
     def _iter_text_cancellable(
-        response: "httpx.Response",
-        cancel_event: Optional[threading.Event] = None,
+        response: "httpx.Response", cancel_event: Optional[threading.Event] = None
     ) -> Generator[str, None, None]:
         """Iterate over an httpx streaming response with cancel support.
 
@@ -4368,18 +4232,14 @@ class LlamaCppBackend:
                                 r.close()
                                 return
                             except Exception as e:
-                                logger.debug(
-                                    f"Error closing response in cancel watcher: {e}"
-                                )
+                                logger.debug(f"Error closing response in cancel watcher: {e}")
                         # Response not created yet -- wait briefly and retry
                         _cancel_closed.wait(timeout = 0.1)
                     return
 
         watcher = None
         if cancel_event is not None:
-            watcher = threading.Thread(
-                target = _cancel_watcher, daemon = True, name = "prefill-cancel"
-            )
+            watcher = threading.Thread(target = _cancel_watcher, daemon = True, name = "prefill-cancel")
             watcher.start()
 
         try:
@@ -4484,9 +4344,7 @@ class LlamaCppBackend:
             # can finish.  Cancel during streaming is handled by the
             # watcher thread (closes the response on cancel_event).
             stream_timeout = httpx.Timeout(connect = 10, read = 0.5, write = 10, pool = 10)
-            _auth_headers = (
-                {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
-            )
+            _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
             with httpx.Client(
                 timeout = stream_timeout, limits = httpx.Limits(max_keepalive_connections = 0)
             ) as client:
@@ -4506,9 +4364,7 @@ class LlamaCppBackend:
                     buffer = ""
                     has_content_tokens = False
                     reasoning_text = ""
-                    for raw_chunk in self._iter_text_cancellable(
-                        response, cancel_event
-                    ):
+                    for raw_chunk in self._iter_text_cancellable(response, cancel_event):
                         buffer += raw_chunk
                         while "\n" in buffer:
                             line, buffer = buffer.split("\n", 1)
@@ -4568,9 +4424,7 @@ class LlamaCppBackend:
                                         cumulative += token
                                         yield cumulative
                             except json.JSONDecodeError:
-                                logger.debug(
-                                    f"Skipping malformed SSE line: {line[:100]}"
-                                )
+                                logger.debug(f"Skipping malformed SSE line: {line[:100]}")
                         if _stream_done:
                             break  # exit outer for
                     if _metadata_usage or _metadata_timings:
@@ -4640,9 +4494,7 @@ class LlamaCppBackend:
         # XML prefixes that signal a tool call in content.
         # Empty when auto_heal is disabled so the buffer never
         # speculatively holds content for XML detection.
-        _TOOL_XML_SIGNALS = (
-            ("<tool_call>", "<function=") if auto_heal_tool_calls else ()
-        )
+        _TOOL_XML_SIGNALS = ("<tool_call>", "<function=") if auto_heal_tool_calls else ()
         _MAX_BUFFER_CHARS = 32
 
         # ── Duplicate tool-call detection ────────────────────────
@@ -4700,9 +4552,7 @@ class LlamaCppBackend:
 
             try:
                 _auth_headers = (
-                    {"Authorization": f"Bearer {self._api_key}"}
-                    if self._api_key
-                    else None
+                    {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
                 )
 
                 # ── Speculative buffer state machine ──────────────────
@@ -4748,8 +4598,7 @@ class LlamaCppBackend:
                         if response.status_code != 200:
                             error_body = response.read().decode()
                             raise RuntimeError(
-                                f"llama-server returned {response.status_code}: "
-                                f"{error_body}"
+                                f"llama-server returned {response.status_code}: " f"{error_body}"
                             )
 
                         raw_buf = ""
@@ -4829,23 +4678,20 @@ class LlamaCppBackend:
                                                 tool_calls_acc[idx]["id"] = tc_d["id"]
                                             func = tc_d.get("function", {})
                                             if func.get("name"):
-                                                tool_calls_acc[idx]["function"][
+                                                tool_calls_acc[idx]["function"]["name"] += func[
                                                     "name"
-                                                ] += func["name"]
+                                                ]
                                             if func.get("arguments"):
-                                                tool_calls_acc[idx]["function"][
-                                                    "arguments"
-                                                ] += func["arguments"]
-                                            current_name = tool_calls_acc[idx][
-                                                "function"
-                                            ].get("name", "")
-                                            fallback_id = f"call_{idx}"
-                                            current_id = tool_calls_acc[idx].get(
-                                                "id", fallback_id
+                                                tool_calls_acc[idx]["function"]["arguments"] += (
+                                                    func["arguments"]
+                                                )
+                                            current_name = tool_calls_acc[idx]["function"].get(
+                                                "name", ""
                                             )
+                                            fallback_id = f"call_{idx}"
+                                            current_id = tool_calls_acc[idx].get("id", fallback_id)
                                             already_started = (
-                                                current_id
-                                                in provisional_render_html_tool_call_ids
+                                                current_id in provisional_render_html_tool_call_ids
                                             )
                                             has_real_id = current_id != fallback_id
                                             if (
@@ -4928,9 +4774,7 @@ class LlamaCppBackend:
                                             if is_match:
                                                 detect_state = _S_DRAINING
                                             elif (
-                                                is_prefix
-                                                and len(stripped_buf)
-                                                < _MAX_BUFFER_CHARS
+                                                is_prefix and len(stripped_buf) < _MAX_BUFFER_CHARS
                                             ):
                                                 pass  # keep buffering
                                             else:
@@ -4940,9 +4784,7 @@ class LlamaCppBackend:
                                                 # during BUFFERING phase
                                                 if reasoning_accum:
                                                     cumulative_display += "<think>"
-                                                    cumulative_display += (
-                                                        reasoning_accum
-                                                    )
+                                                    cumulative_display += reasoning_accum
                                                     cumulative_display += "</think>"
                                                 cumulative_display += content_buffer
                                                 cleaned = _strip_tool_markup(
@@ -4956,9 +4798,7 @@ class LlamaCppBackend:
                                                     }
 
                                 except json.JSONDecodeError:
-                                    logger.debug(
-                                        f"Skipping malformed SSE line: {line[:100]}"
-                                    )
+                                    logger.debug(f"Skipping malformed SSE line: {line[:100]}")
                             if _stream_done:
                                 break  # exit outer for
 
@@ -5007,9 +4847,7 @@ class LlamaCppBackend:
                     # post-tool synthesis streams correctly even if
                     # content was already emitted before the tool XML.
                     _safety_tc = None
-                    if auto_heal_tool_calls and any(
-                        s in content_accum for s in _TOOL_XML_SIGNALS
-                    ):
+                    if auto_heal_tool_calls and any(s in content_accum for s in _TOOL_XML_SIGNALS):
                         _safety_tc = self._parse_tool_calls_from_text(
                             content_accum,
                         )
@@ -5047,15 +4885,10 @@ class LlamaCppBackend:
                             available_tool_names = [
                                 tool.get("function", {}).get("name")
                                 for tool in tools
-                                if isinstance(tool, dict)
-                                and isinstance(tool.get("function"), dict)
+                                if isinstance(tool, dict) and isinstance(tool.get("function"), dict)
                             ]
-                            available_tool_names = [
-                                name for name in available_tool_names if name
-                            ]
-                            tool_hint = (
-                                " or ".join(available_tool_names) or "an available tool"
-                            )
+                            available_tool_names = [name for name in available_tool_names if name]
+                            tool_hint = " or ".join(available_tool_names) or "an available tool"
                             conversation.append(
                                 {
                                     "role": "user",
@@ -5067,13 +4900,8 @@ class LlamaCppBackend:
                                 }
                             )
                             # Accumulate tokens and timing from this iteration
-                            _fu_r = (
-                                _backfill_usage_from_timings(_iter_usage, _iter_timings)
-                                or {}
-                            )
-                            _accumulated_completion_tokens += _fu_r.get(
-                                "completion_tokens", 0
-                            )
+                            _fu_r = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
+                            _accumulated_completion_tokens += _fu_r.get("completion_tokens", 0)
                             _it_r = _iter_timings or {}
                             _accumulated_predicted_ms += _it_r.get("predicted_ms", 0)
                             _accumulated_predicted_n += _it_r.get("predicted_n", 0)
@@ -5082,27 +4910,17 @@ class LlamaCppBackend:
 
                         # Content was already streamed.  Yield metadata.
                         yield {"type": "status", "text": ""}
-                        _fu = (
-                            _backfill_usage_from_timings(_iter_usage, _iter_timings)
-                            or {}
-                        )
+                        _fu = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
                         _fc = _fu.get("completion_tokens", 0)
                         _fp = _fu.get("prompt_tokens", 0)
                         _tc = _fc + _accumulated_completion_tokens
-                        if (
-                            _iter_usage
-                            or _iter_timings
-                            or _accumulated_completion_tokens
-                        ):
+                        if _iter_usage or _iter_timings or _accumulated_completion_tokens:
                             _mt = dict(_iter_timings) if _iter_timings else {}
                             if _accumulated_predicted_ms or _accumulated_predicted_n:
                                 _mt["predicted_ms"] = (
-                                    _mt.get("predicted_ms", 0)
-                                    + _accumulated_predicted_ms
-                                )
-                                _tn = (
-                                    _mt.get("predicted_n", 0) + _accumulated_predicted_n
+                                    _mt.get("predicted_ms", 0) + _accumulated_predicted_ms
                                 )
+                                _tn = _mt.get("predicted_n", 0) + _accumulated_predicted_n
                                 _mt["predicted_n"] = _tn
                                 _tms = _mt["predicted_ms"]
                                 if _tms > 0:
@@ -5138,12 +4956,7 @@ class LlamaCppBackend:
                         tool_calls = [
                             tool_calls_acc[i]
                             for i in sorted(tool_calls_acc)
-                            if (
-                                tool_calls_acc[i]
-                                .get("function", {})
-                                .get("name", "")
-                                .strip()
-                            )
+                            if (tool_calls_acc[i].get("function", {}).get("name", "").strip())
                         ] or None
                     if (
                         not tool_calls
@@ -5170,32 +4983,20 @@ class LlamaCppBackend:
                         yield {"type": "status", "text": ""}
                         if content_accum:
                             # Strip leaked tool-call XML before yielding
-                            content_accum = _strip_tool_markup(
-                                content_accum, final = True
-                            )
+                            content_accum = _strip_tool_markup(content_accum, final = True)
                         if content_accum:
                             yield {"type": "content", "text": content_accum}
-                        _fu = (
-                            _backfill_usage_from_timings(_iter_usage, _iter_timings)
-                            or {}
-                        )
+                        _fu = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
                         _fc = _fu.get("completion_tokens", 0)
                         _fp = _fu.get("prompt_tokens", 0)
                         _tc = _fc + _accumulated_completion_tokens
-                        if (
-                            _iter_usage
-                            or _iter_timings
-                            or _accumulated_completion_tokens
-                        ):
+                        if _iter_usage or _iter_timings or _accumulated_completion_tokens:
                             _mt = dict(_iter_timings) if _iter_timings else {}
                             if _accumulated_predicted_ms or _accumulated_predicted_n:
                                 _mt["predicted_ms"] = (
-                                    _mt.get("predicted_ms", 0)
-                                    + _accumulated_predicted_ms
-                                )
-                                _tn = (
-                                    _mt.get("predicted_n", 0) + _accumulated_predicted_n
+                                    _mt.get("predicted_ms", 0) + _accumulated_predicted_ms
                                 )
+                                _tn = _mt.get("predicted_n", 0) + _accumulated_predicted_n
                                 _mt["predicted_n"] = _tn
                                 _tms = _mt["predicted_ms"]
                                 if _tms > 0:
@@ -5259,26 +5060,18 @@ class LlamaCppBackend:
                         else:
                             status_text = f"Searching: {arguments.get('query', '')}"
                     elif tool_name == "python":
-                        preview = (
-                            (arguments.get("code") or "").strip().split("\n")[0][:60]
-                        )
+                        preview = (arguments.get("code") or "").strip().split("\n")[0][:60]
                         status_text = (
-                            f"Running Python: {preview}"
-                            if preview
-                            else "Running Python..."
+                            f"Running Python: {preview}" if preview else "Running Python..."
                         )
                     elif tool_name == "terminal":
                         cmd_preview = (arguments.get("command") or "")[:60]
                         status_text = (
-                            f"Running: {cmd_preview}"
-                            if cmd_preview
-                            else "Running command..."
+                            f"Running: {cmd_preview}" if cmd_preview else "Running command..."
                         )
                     else:
                         status_text = f"Calling: {tool_name}"
-                    _repeat_render_html = (
-                        tool_name == "render_html" and _render_html_succeeded
-                    )
+                    _repeat_render_html = tool_name == "render_html" and _render_html_succeeded
                     if not _repeat_render_html:
                         yield {"type": "status", "text": status_text}
 
@@ -5450,9 +5243,7 @@ class LlamaCppBackend:
 
         try:
             stream_timeout = httpx.Timeout(connect = 10, read = 0.5, write = 10, pool = 10)
-            _auth_headers = (
-                {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
-            )
+            _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
             with httpx.Client(
                 timeout = stream_timeout, limits = httpx.Limits(max_keepalive_connections = 0)
             ) as client:
@@ -5470,9 +5261,7 @@ class LlamaCppBackend:
                         )
 
                     buffer = ""
-                    for raw_chunk in self._iter_text_cancellable(
-                        response, cancel_event
-                    ):
+                    for raw_chunk in self._iter_text_cancellable(response, cancel_event):
                         buffer += raw_chunk
                         while "\n" in buffer:
                             line, buffer = buffer.split("\n", 1)
@@ -5486,9 +5275,7 @@ class LlamaCppBackend:
                                         cumulative += "</think>"
                                         yield {
                                             "type": "content",
-                                            "text": _strip_tool_markup(
-                                                cumulative, final = True
-                                            ),
+                                            "text": _strip_tool_markup(cumulative, final = True),
                                         }
                                     else:
                                         cumulative = reasoning_text
@@ -5533,35 +5320,27 @@ class LlamaCppBackend:
                                             _last_emitted = cleaned
                                             yield {"type": "content", "text": cleaned}
                             except json.JSONDecodeError:
-                                logger.debug(
-                                    f"Skipping malformed SSE line: {line[:100]}"
-                                )
+                                logger.debug(f"Skipping malformed SSE line: {line[:100]}")
                         if _stream_done:
                             break  # exit outer for
                     _final_usage = _metadata_usage or {}
                     _final_completion = _final_usage.get("completion_tokens", 0)
                     _final_prompt = _final_usage.get("prompt_tokens", 0)
-                    _total_completion = (
-                        _final_completion + _accumulated_completion_tokens
-                    )
+                    _total_completion = _final_completion + _accumulated_completion_tokens
                     if _metadata_usage or _metadata_timings:
-                        _merged_timings = (
-                            dict(_metadata_timings) if _metadata_timings else {}
-                        )
+                        _merged_timings = dict(_metadata_timings) if _metadata_timings else {}
                         if _accumulated_predicted_ms or _accumulated_predicted_n:
                             _merged_timings["predicted_ms"] = (
-                                _merged_timings.get("predicted_ms", 0)
-                                + _accumulated_predicted_ms
+                                _merged_timings.get("predicted_ms", 0) + _accumulated_predicted_ms
                             )
                             _total_predicted_n = (
-                                _merged_timings.get("predicted_n", 0)
-                                + _accumulated_predicted_n
+                                _merged_timings.get("predicted_n", 0) + _accumulated_predicted_n
                             )
                             _merged_timings["predicted_n"] = _total_predicted_n
                             _total_predicted_ms = _merged_timings["predicted_ms"]
                             if _total_predicted_ms > 0:
-                                _merged_timings["predicted_per_second"] = (
-                                    _total_predicted_n / (_total_predicted_ms / 1000.0)
+                                _merged_timings["predicted_per_second"] = _total_predicted_n / (
+                                    _total_predicted_ms / 1000.0
                                 )
                         yield {
                             "type": "metadata",
@@ -5594,9 +5373,7 @@ class LlamaCppBackend:
         """Codec name on match, None on definitive non-audio, raises on transport/JSON errors."""
         if not self.is_loaded:
             return None
-        _auth_headers = (
-            {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
-        )
+        _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
         with httpx.Client(timeout = 10, headers = _auth_headers) as client:
 
             def _detok(tid: int) -> str:
@@ -5617,9 +5394,7 @@ class LlamaCppBackend:
                 return r.json().get("tokens", [])
 
             # Check codec-specific tokens (not generic ones that may exist in non-audio models)
-            if "<custom_token_" in _detok(128258) and "<custom_token_" in _detok(
-                128259
-            ):
+            if "<custom_token_" in _detok(128258) and "<custom_token_" in _detok(128259):
                 return "snac"
             if len(_tok("<|AUDIO|>")) == 1 and len(_tok("<|audio_eos|>")) == 1:
                 return "csm"
@@ -5628,10 +5403,7 @@ class LlamaCppBackend:
             # Gemma 3n: <audio_soft_token>; Gemma 4: <|audio|> (not csm's <|AUDIO|>).
             if len(_tok("<audio_soft_token>")) == 1 or len(_tok("<|audio|>")) == 1:
                 return "audio_vlm"
-            if (
-                len(_tok("<|bicodec_semantic_0|>")) == 1
-                and len(_tok("<|bicodec_global_0|>")) == 1
-            ):
+            if len(_tok("<|bicodec_semantic_0|>")) == 1 and len(_tok("<|bicodec_global_0|>")) == 1:
                 return "bicodec"
             if len(_tok("<|c1_0|>")) == 1 and len(_tok("<|c2_0|>")) == 1:
                 return "dac"
@@ -5675,14 +5447,10 @@ class LlamaCppBackend:
             from huggingface_hub import snapshot_download
             import os
 
-            repo_path = snapshot_download(
-                "unsloth/Spark-TTS-0.5B", local_dir = "Spark-TTS-0.5B"
-            )
+            repo_path = snapshot_download("unsloth/Spark-TTS-0.5B", local_dir = "Spark-TTS-0.5B")
             model_repo_path = os.path.abspath(repo_path)
 
-        LlamaCppBackend._codec_mgr.load_codec(
-            audio_type, device, model_repo_path = model_repo_path
-        )
+        LlamaCppBackend._codec_mgr.load_codec(audio_type, device, model_repo_path = model_repo_path)
         logger.info(f"Loaded audio codec for GGUF TTS: {audio_type}")
 
     def generate_audio_response(
@@ -5720,17 +5488,11 @@ class LlamaCppBackend:
         if need_ids:
             payload["n_probs"] = 1
 
-        _auth_headers = (
-            {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
-        )
-        with httpx.Client(
-            timeout = httpx.Timeout(300, connect = 10), headers = _auth_headers
-        ) as client:
+        _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
+        with httpx.Client(timeout = httpx.Timeout(300, connect = 10), headers = _auth_headers) as client:
             resp = client.post(f"{self.base_url}/completion", json = payload)
             if resp.status_code != 200:
-                raise RuntimeError(
-                    f"llama-server returned {resp.status_code}: {resp.text}"
-                )
+                raise RuntimeError(f"llama-server returned {resp.status_code}: {resp.text}")
 
         data = resp.json()
         token_ids = (
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index b299e1ee9e..66cd138d99 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -126,9 +126,7 @@ def is_managed_flag(flag: str) -> bool:
 # stripped from inherited extras so they can't last-wins-override an
 # Apply that re-sets the same field.
 _CONTEXT_FLAGS: frozenset[str] = frozenset({"-c", "--ctx-size"})
-_CACHE_FLAGS: frozenset[str] = frozenset(
-    {"-ctk", "--cache-type-k", "-ctv", "--cache-type-v"}
-)
+_CACHE_FLAGS: frozenset[str] = frozenset({"-ctk", "--cache-type-k", "-ctv", "--cache-type-v"})
 _SPEC_FLAGS: frozenset[str] = frozenset(
     {
         "--spec-default",
@@ -157,15 +155,11 @@ _TEMPLATE_FLAGS: frozenset[str] = frozenset(
     }
 )
 
-_SHADOWING_FLAGS: frozenset[str] = (
-    _CONTEXT_FLAGS | _CACHE_FLAGS | _SPEC_FLAGS | _TEMPLATE_FLAGS
-)
+_SHADOWING_FLAGS: frozenset[str] = _CONTEXT_FLAGS | _CACHE_FLAGS | _SPEC_FLAGS | _TEMPLATE_FLAGS
 
 # Shadowing flags that take no value -- strip the flag only, never the
 # following token.
-_BOOLEAN_SHADOWING_FLAGS: frozenset[str] = frozenset(
-    {"--spec-default", "--jinja", "--no-jinja"}
-)
+_BOOLEAN_SHADOWING_FLAGS: frozenset[str] = frozenset({"--spec-default", "--jinja", "--no-jinja"})
 
 
 def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
@@ -192,31 +186,22 @@ def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
             i += 1
         else:
             if i + 1 >= n or _flag_name(tokens[i + 1]) is not None:
-                raise ValueError(
-                    f"llama-server flag '{flag}' requires an integer value"
-                )
+                raise ValueError(f"llama-server flag '{flag}' requires an integer value")
             raw_value = tokens[i + 1]
             i += 2
 
         try:
             value = int(str(raw_value).strip())
         except ValueError as exc:
-            raise ValueError(
-                f"llama-server flag '{flag}' requires an integer value"
-            ) from exc
+            raise ValueError(f"llama-server flag '{flag}' requires an integer value") from exc
         if value < 0:
-            raise ValueError(
-                f"llama-server flag '{flag}' requires a non-negative integer value"
-            )
+            raise ValueError(f"llama-server flag '{flag}' requires a non-negative integer value")
         override = value
 
     return override
 
 
-def resolve_requested_ctx(
-    args: Optional[Iterable[str]],
-    fallback_n_ctx: int,
-) -> int:
+def resolve_requested_ctx(args: Optional[Iterable[str]], fallback_n_ctx: int) -> int:
     """Return the context size load_model should treat as requested.
 
     Single source of truth for the two-line ``ctx_override = parse_ctx_override(...);
@@ -267,8 +252,7 @@ def parse_cache_override(args: Optional[Iterable[str]]) -> Optional[str]:
 
 
 def resolve_cache_type_kv(
-    args: Optional[Iterable[str]],
-    fallback_cache_type_kv: Optional[str],
+    args: Optional[Iterable[str]], fallback_cache_type_kv: Optional[str]
 ) -> Optional[str]:
     """Return the cache type load_model should treat as requested.
 
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index 2ed1a630dc..ad5f67f325 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -34,10 +34,7 @@ def parse_stdio_command(address: str) -> list[str]:
         # posix=False keeps backslash paths intact but also keeps the surrounding
         # quotes on a token. Strip a matched pair so the argv reaches the
         # subprocess clean ('"C:\\Program Files\\node"' -> C:\\Program Files\\node).
-        parts = [
-            p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p
-            for p in parts
-        ]
+        parts = [p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p for p in parts]
     return parts
 
 
@@ -104,7 +101,6 @@ async def clear_oauth_tokens_async(url: str) -> None:
     failing must not make the delete / update route 500."""
     try:
         from fastmcp.client.auth import OAuth
-
         auth = OAuth(mcp_url = url, token_storage = _oauth_store())
         await auth.token_storage_adapter.clear()
     except Exception as exc:  # noqa: BLE001
@@ -112,7 +108,11 @@ async def clear_oauth_tokens_async(url: str) -> None:
         logger.warning("Failed to clear OAuth tokens for %s: %s", url, exc)
 
 
-def _client(url: str, headers: Optional[dict], use_oauth: bool = False):
+def _client(
+    url: str,
+    headers: Optional[dict],
+    use_oauth: bool = False,
+):
     from fastmcp import Client
 
     if is_stdio(url):
@@ -142,13 +142,10 @@ def _client(url: str, headers: Optional[dict], use_oauth: bool = False):
     auth = None
     if use_oauth:
         from fastmcp.client.auth import OAuth
-
         auth = OAuth(mcp_url = url, token_storage = _oauth_store())
 
     transport_cls = (
-        SSETransport
-        if infer_transport_type_from_url(url) == "sse"
-        else StreamableHttpTransport
+        SSETransport if infer_transport_type_from_url(url) == "sse" else StreamableHttpTransport
     )
     return Client(transport_cls(url = url, headers = headers or None, auth = auth))
 
diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index b9adba13e6..5913c29282 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -133,7 +133,6 @@ class MLXInferenceBackend:
 
         if hf_token:
             import os
-
             os.environ["HF_TOKEN"] = hf_token
         self._configure_memory_limits()
 
@@ -311,9 +310,7 @@ class MLXInferenceBackend:
                     elif isinstance(content, list):
                         # Prepend image if not already there
                         has_image = any(
-                            p.get("type") == "image"
-                            for p in content
-                            if isinstance(p, dict)
+                            p.get("type") == "image" for p in content if isinstance(p, dict)
                         )
                         if not has_image:
                             content.insert(0, {"type": "image"})
@@ -383,9 +380,7 @@ class MLXInferenceBackend:
             preserve_thinking = preserve_thinking,
         )
         if prompt is None:
-            raise RuntimeError(
-                "apply_chat_template returned None — tokenizer may be incompatible"
-            )
+            raise RuntimeError("apply_chat_template returned None — tokenizer may be incompatible")
 
         sampler = make_sampler(
             temp = temperature,
@@ -441,7 +436,6 @@ class MLXInferenceBackend:
                         break
             except Exception as e:
                 import traceback
-
                 logger.error("stream_generate failed:\n%s", traceback.format_exc())
                 raise
             finally:
@@ -538,9 +532,7 @@ class MLXInferenceBackend:
                     **vlm_kwargs,
                 ):
                     final_response = response
-                    token_text = (
-                        response.text if hasattr(response, "text") else str(response)
-                    )
+                    token_text = response.text if hasattr(response, "text") else str(response)
                     cumulative += token_text
                     yield cumulative
                     if cancel_event and cancel_event.is_set():
@@ -556,7 +548,10 @@ class MLXInferenceBackend:
                     )
 
     def generate_with_adapter_control(
-        self, use_adapter = None, cancel_event = None, **gen_kwargs
+        self,
+        use_adapter = None,
+        cancel_event = None,
+        **gen_kwargs,
     ) -> Generator[str, None, None]:
         # MLX LoRA adapter toggling not yet supported — generate normally
         yield from self.generate_chat_response(cancel_event = cancel_event, **gen_kwargs)
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 9810f2b9da..1c132c3f52 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -63,9 +63,7 @@ class InferenceOrchestrator:
         self._resp_queue: Any = None
         self._cancel_event: Any = None  # mp.Event — set to cancel generation instantly
         self._lock = threading.Lock()
-        self._gen_lock = (
-            threading.Lock()
-        )  # Serializes generation — one request at a time
+        self._gen_lock = threading.Lock()  # Serializes generation — one request at a time
 
         # Dispatcher state — for compare mode (adapter-controlled requests).
         # Instead of serializing via _gen_lock, adapter-controlled requests
@@ -95,9 +93,7 @@ class InferenceOrchestrator:
         logger.info("InferenceOrchestrator initialized (subprocess mode)")
 
         # Kick off background fetch of top models from HF
-        threading.Thread(
-            target = self._fetch_top_models, daemon = True, name = "top-models"
-        ).start()
+        threading.Thread(target = self._fetch_top_models, daemon = True, name = "top-models").start()
 
     # ------------------------------------------------------------------
     # Default models (top GGUFs fetched dynamically from HF)
@@ -125,7 +121,6 @@ class InferenceOrchestrator:
         """Fetch top GGUF and non-GGUF repos from unsloth by downloads."""
         try:
             import httpx
-
             resp = httpx.get(
                 "https://huggingface.co/api/models",
                 params = {
@@ -140,14 +135,12 @@ class InferenceOrchestrator:
                 models = resp.json()
                 # Top 40 GGUFs - frontend pages through them on-demand via
                 # infinite scroll, so we send a deep pool.
-                gguf_ids = [
-                    m["id"] for m in models if m.get("id", "").upper().endswith("-GGUF")
-                ][:40]
+                gguf_ids = [m["id"] for m in models if m.get("id", "").upper().endswith("-GGUF")][
+                    :40
+                ]
                 # Top 40 non-GGUF hub models
                 hub_ids = [
-                    m["id"]
-                    for m in models
-                    if not m.get("id", "").upper().endswith("-GGUF")
+                    m["id"] for m in models if not m.get("id", "").upper().endswith("-GGUF")
                 ][:40]
                 if gguf_ids:
                     self._top_gguf_cache = gguf_ids
@@ -277,7 +270,11 @@ class InferenceOrchestrator:
         except (EOFError, OSError, ValueError):
             return None
 
-    def _wait_response(self, expected_type: str, timeout: float = 300.0) -> dict:
+    def _wait_response(
+        self,
+        expected_type: str,
+        timeout: float = 300.0,
+    ) -> dict:
         """Block until a response of the expected type arrives.
 
         Also handles 'status' and 'error' events during the wait.
@@ -329,8 +326,7 @@ class InferenceOrchestrator:
             )
 
         raise RuntimeError(
-            f"Timeout waiting for '{expected_type}' response "
-            f"(no activity for {timeout}s)"
+            f"Timeout waiting for '{expected_type}' response " f"(no activity for {timeout}s)"
         )
 
     def _drain_queue(self) -> list:
@@ -556,7 +552,11 @@ class InferenceOrchestrator:
             with self._mailbox_lock:
                 self._mailboxes.pop(request_id, None)
 
-    def _drain_mailbox(self, mailbox: queue.Queue, timeout: float = 5.0) -> None:
+    def _drain_mailbox(
+        self,
+        mailbox: queue.Queue,
+        timeout: float = 5.0,
+    ) -> None:
         """Drain a mailbox until gen_done/gen_error, discarding tokens."""
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
@@ -683,8 +683,7 @@ class InferenceOrchestrator:
                     # First stall and Xet was enabled -> retry with Xet disabled
                     if attempt == 0 and not disable_xet:
                         logger.warning(
-                            "Download stalled for '%s' -- retrying with "
-                            "HF_HUB_DISABLE_XET=1",
+                            "Download stalled for '%s' -- retrying with HF_HUB_DISABLE_XET=1",
                             model_name,
                         )
                         self._shutdown_subprocess(timeout = 5)
@@ -715,13 +714,9 @@ class InferenceOrchestrator:
                     # capabilities without re-entering the subprocess.
                     _tpl_info = model_info.get("chat_template_info")
                     if isinstance(_tpl_info, dict):
-                        self.models[self.active_model_name]["chat_template_info"] = (
-                            _tpl_info
-                        )
+                        self.models[self.active_model_name]["chat_template_info"] = _tpl_info
                     self.loading_models.discard(model_name)
-                    logger.info(
-                        "Model '%s' loaded successfully in subprocess", model_name
-                    )
+                    logger.info("Model '%s' loaded successfully in subprocess", model_name)
                     return True
                 else:
                     error = resp.get("error", "Failed to load model")
@@ -1157,9 +1152,7 @@ class InferenceOrchestrator:
 
             if resp is None:
                 if not self._ensure_subprocess_alive():
-                    raise RuntimeError(
-                        "Inference subprocess crashed during audio generation"
-                    )
+                    raise RuntimeError("Inference subprocess crashed during audio generation")
                 continue
 
             rtype = resp.get("type", "")
@@ -1251,9 +1244,7 @@ class InferenceOrchestrator:
 
             # Convert numpy array to list for mp.Queue serialization
             audio_data = (
-                audio_array.tolist()
-                if hasattr(audio_array, "tolist")
-                else list(audio_array)
+                audio_array.tolist() if hasattr(audio_array, "tolist") else list(audio_array)
             )
 
             cmd = {
@@ -1314,7 +1305,11 @@ class InferenceOrchestrator:
     # Local helpers (no subprocess needed)
     # ------------------------------------------------------------------
 
-    def resize_image(self, img, max_size: int = 800):
+    def resize_image(
+        self,
+        img,
+        max_size: int = 800,
+    ):
         """Resize image while maintaining aspect ratio.
         No ML imports needed — runs locally in parent process.
         """
@@ -1357,7 +1352,6 @@ class InferenceOrchestrator:
         """Parent-side gpt-oss detection so the safetensors route can run
         the same guard without an IPC round-trip to the subprocess."""
         from utils.datasets import is_gpt_oss_model_name
-
         return is_gpt_oss_model_name(model_name or self.active_model_name or "")
 
 
diff --git a/studio/backend/core/inference/pricing.py b/studio/backend/core/inference/pricing.py
index 84eec17e84..a604749c9c 100644
--- a/studio/backend/core/inference/pricing.py
+++ b/studio/backend/core/inference/pricing.py
@@ -106,11 +106,7 @@ def _lookup(provider: str, model: str) -> Optional[dict[str, float]]:
     return None
 
 
-def calculate_cost(
-    provider: str,
-    model: str,
-    usage: dict[str, Any],
-) -> dict[str, float]:
+def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str, float]:
     """Return a per-turn USD cost breakdown with per-bucket + total
     fields so the frontend can render either a single number or a
     tooltip without re-doing the math. When the model isn't in the
@@ -141,8 +137,7 @@ def calculate_cost(
     # Clamp tokens >=0 so corrupted payloads can't produce a negative bill.
     cache_creation = max(0, int(usage.get("cache_creation_input_tokens") or 0))
     cache_read_native_present = (
-        "cache_read_input_tokens" in usage
-        and usage.get("cache_read_input_tokens") is not None
+        "cache_read_input_tokens" in usage and usage.get("cache_read_input_tokens") is not None
     )
     cache_read = max(0, int(usage.get("cache_read_input_tokens") or 0))
     # Fallback to mirrored prompt_tokens_details only when the native
@@ -226,14 +221,10 @@ def calculate_cost(
         if cc_5m + cc_1h == 0 and cache_creation > 0:
             # No breakdown -- assume default 5m pool.
             cc_5m = cache_creation
-        out["cache_write_usd"] = (
-            cc_5m / 1_000_000.0
-        ) * base * ANTHROPIC_CACHE_5M_WRITE_MULT + (
+        out["cache_write_usd"] = (cc_5m / 1_000_000.0) * base * ANTHROPIC_CACHE_5M_WRITE_MULT + (
             cc_1h / 1_000_000.0
         ) * base * ANTHROPIC_CACHE_1H_WRITE_MULT
-        out["cache_read_usd"] = (
-            (cache_read / 1_000_000.0) * base * ANTHROPIC_CACHE_READ_MULT
-        )
+        out["cache_read_usd"] = (cache_read / 1_000_000.0) * base * ANTHROPIC_CACHE_READ_MULT
         # Server-tool surcharges.
         srv = usage.get("server_tool_use") or {}
         if isinstance(srv, dict):
@@ -250,9 +241,7 @@ def calculate_cost(
         if cache_read > 0:
             non_cached_input = max(0, input_tokens - cache_read)
             out["input_usd"] = (non_cached_input / 1_000_000.0) * base
-            out["cache_read_usd"] = (
-                (cache_read / 1_000_000.0) * base * OPENAI_CACHE_READ_MULT
-            )
+            out["cache_read_usd"] = (cache_read / 1_000_000.0) * base * OPENAI_CACHE_READ_MULT
         # OpenAI server-tool surcharges arrive under `openai_tool_use`
         # (normalised by the SSE finaliser from output array items).
         srv = usage.get("openai_tool_use") or {}
diff --git a/studio/backend/core/inference/providers.py b/studio/backend/core/inference/providers.py
index 785f1dec3b..19b776a6d9 100644
--- a/studio/backend/core/inference/providers.py
+++ b/studio/backend/core/inference/providers.py
@@ -258,8 +258,7 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         # sources. The HF /v1/models response is otherwise hundreds of
         # ids long (community fine-tunes, mirrors, fp8 variants, etc.).
         "model_id_allowlist": re.compile(
-            r"^(openai|deepseek-ai|google|meta-llama|Qwen|moonshotai|"
-            r"mistralai|zai-org)/"
+            r"^(openai|deepseek-ai|google|meta-llama|Qwen|moonshotai|mistralai|zai-org)/"
         ),
         # Cap the post-filter list. /v1/models has no server-side limit
         # or popularity sort, so this is just "first N matches" — pair it
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index 94e9e303ab..e4eb0cd100 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -86,9 +86,7 @@ def _detect_render_html_tool_start(content: str) -> bool:
     if not function_match and tool_call_index < 0:
         return False
 
-    if function_match and (
-        tool_call_index < 0 or function_match.start() < tool_call_index
-    ):
+    if function_match and (tool_call_index < 0 or function_match.start() < tool_call_index):
         return function_match.group(1) == "render_html"
 
     if tool_call_index >= 0:
@@ -98,7 +96,12 @@ def _detect_render_html_tool_start(content: str) -> bool:
     return False
 
 
-def _coerce_arguments(raw_args, *, heal: bool, tool_name: str = "") -> dict:
+def _coerce_arguments(
+    raw_args,
+    *,
+    heal: bool,
+    tool_name: str = "",
+) -> dict:
     """Normalise tool ``arguments`` to a dict.
 
     Some templates emit a JSON string, others a bare query string. With
@@ -403,15 +406,11 @@ def run_safetensors_tool_loop(
                     "final answer."
                 )
             else:
-                already_ran_ok = any(
-                    k == tc_key and not err for k, err in tool_call_history
-                )
+                already_ran_ok = any(k == tc_key and not err for k, err in tool_call_history)
                 if already_ran_ok:
                     result = DUPLICATE_CALL_NUDGE
                 else:
-                    eff_timeout = (
-                        None if tool_call_timeout >= 9999 else tool_call_timeout
-                    )
+                    eff_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
                     try:
                         result = execute_tool(
                             tool_name,
@@ -432,9 +431,7 @@ def run_safetensors_tool_loop(
                     "result": result,
                 }
 
-            is_error = isinstance(result, str) and result.lstrip().startswith(
-                TOOL_ERROR_PREFIXES
-            )
+            is_error = isinstance(result, str) and result.lstrip().startswith(TOOL_ERROR_PREFIXES)
             if tool_name == "render_html" and not is_error:
                 render_html_succeeded = True
             tool_call_history.append((tc_key, is_error))
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index dacbc19ac0..23b7d4c97a 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -160,9 +160,7 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                     },
                 }
                 if isinstance(tc["function"]["arguments"], dict):
-                    tc["function"]["arguments"] = json.dumps(
-                        tc["function"]["arguments"]
-                    )
+                    tc["function"]["arguments"] = json.dumps(tc["function"]["arguments"])
                 tool_calls.append(tc)
             except (json.JSONDecodeError, ValueError):
                 pass
@@ -179,11 +177,7 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
         for idx, fm in enumerate(func_starts):
             func_name = fm.group(1)
             body_start = fm.end()
-            next_func = (
-                func_starts[idx + 1].start()
-                if idx + 1 < len(func_starts)
-                else len(content)
-            )
+            next_func = func_starts[idx + 1].start() if idx + 1 < len(func_starts) else len(content)
             end_tag = _TC_END_TAG_RE.search(content[body_start:])
             if end_tag:
                 body_end = body_start + end_tag.start()
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 0f5dbfa237..9be2276d3d 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -121,9 +121,7 @@ _BLOCKED_COMMANDS = (
 )
 
 
-_SHELL_SEPARATORS = frozenset(
-    {";", "&&", "||", "|", "&", "\n", "(", ")", "`", "{", "}"}
-)
+_SHELL_SEPARATORS = frozenset({";", "&&", "||", "|", "&", "\n", "(", ")", "`", "{", "}"})
 # Bash keywords that introduce a new command position (then $cmd, do $cmd, etc.).
 _SHELL_KEYWORDS_AS_SEP = frozenset({"then", "do", "else", "elif"})
 # Wrappers whose next non-flag argument is itself the command Bash will exec.
@@ -256,9 +254,7 @@ def _find_blocked_commands(command: str) -> set[str]:
         tok_lower = token.lower()
         # Match -c exactly, or combined flags ending in c (e.g. -lc, -xc)
         is_unix_c = tok_lower == "-c" or (
-            tok_lower.startswith("-")
-            and tok_lower.endswith("c")
-            and not tok_lower.startswith("--")
+            tok_lower.startswith("-") and tok_lower.endswith("c") and not tok_lower.startswith("--")
         )
         is_win_c = tok_lower == "/c"
         if not (is_unix_c or is_win_c) or i < 1 or i + 1 >= len(tokens):
@@ -370,18 +366,11 @@ def _sandbox_preexec():
         except (ValueError, OSError, AttributeError):
             pass
         try:
-            _resource.setrlimit(
-                _resource.RLIMIT_FSIZE, (100 * 1024 * 1024, 100 * 1024 * 1024)
-            )
+            _resource.setrlimit(_resource.RLIMIT_FSIZE, (100 * 1024 * 1024, 100 * 1024 * 1024))
         except (ValueError, OSError):
             pass
         try:
-            as_bytes = (
-                int(os.environ.get("UNSLOTH_STUDIO_SANDBOX_AS_GB", "8"))
-                * 1024
-                * 1024
-                * 1024
-            )
+            as_bytes = int(os.environ.get("UNSLOTH_STUDIO_SANDBOX_AS_GB", "8")) * 1024 * 1024 * 1024
             _resource.setrlimit(_resource.RLIMIT_AS, (as_bytes, as_bytes))
         except (ValueError, OSError, AttributeError):
             pass
@@ -398,9 +387,7 @@ def _sandbox_preexec():
             # value (would otherwise leave NOFILE at the parent's default).
             nofile = int(os.environ.get("UNSLOTH_STUDIO_SANDBOX_NOFILE", "16384"))
             _soft_cur, hard_cur = _resource.getrlimit(_resource.RLIMIT_NOFILE)
-            target = (
-                nofile if hard_cur == _resource.RLIM_INFINITY else min(nofile, hard_cur)
-            )
+            target = nofile if hard_cur == _resource.RLIM_INFINITY else min(nofile, hard_cur)
             _resource.setrlimit(_resource.RLIMIT_NOFILE, (target, target))
         except (ValueError, OSError, AttributeError):
             pass
@@ -432,12 +419,9 @@ def _get_project_workdir(session_id: str) -> str | None:
         return None
     try:
         from storage.studio_db import ensure_chat_project_workspace
-
         project = ensure_chat_project_workspace(project_id)
     except Exception:
-        logger.warning(
-            "Failed to resolve project sandbox for %s", session_id, exc_info = True
-        )
+        logger.warning("Failed to resolve project sandbox for %s", session_id, exc_info = True)
         return None
     if not project:
         return None
@@ -468,9 +452,7 @@ def _get_workdir(session_id: str | None = None) -> str:
             workdir = project_workdir
         elif session_id and _SESSION_ID_RE.match(session_id):
             workdir = os.path.join(sandbox_root, session_id)
-            if not os.path.realpath(workdir).startswith(
-                os.path.realpath(sandbox_root) + os.sep
-            ):
+            if not os.path.realpath(workdir).startswith(os.path.realpath(sandbox_root) + os.sep):
                 workdir = os.path.join(sandbox_root, "_invalid")
         elif session_id:
             workdir = os.path.join(sandbox_root, "_invalid")
@@ -618,9 +600,7 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
         # Same MCP server returning duplicate tool names would also 400
         # OpenAI ("tools[N].function.name duplicates ..."). Drop dupes.
         if name in seen_names:
-            logger.warning(
-                "Skipping duplicate MCP tool '%s' on '%s'.", raw_name, display
-            )
+            logger.warning("Skipping duplicate MCP tool '%s' on '%s'.", raw_name, display)
             continue
         seen_names.add(name)
         specs.append(
@@ -629,8 +609,7 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
                 "function": {
                     "name": name,
                     "description": f"[{display}] {tool.get('description') or ''}".strip(),
-                    "parameters": tool.get("inputSchema")
-                    or {"type": "object", "properties": {}},
+                    "parameters": tool.get("inputSchema") or {"type": "object", "properties": {}},
                 },
             }
         )
@@ -708,9 +687,7 @@ def execute_tool(
     unset (default) uses ``_EXEC_TIMEOUT`` (300 s).
     ``session_id``: optional thread/session ID for per-conversation sandbox isolation.
     """
-    logger.info(
-        f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}"
-    )
+    logger.info(f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}")
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
     if name == "render_html":
         return _render_html_result(arguments)
@@ -742,13 +719,9 @@ def execute_tool(
             timeout = effective_timeout,
         )
     if name == "python":
-        return _python_exec(
-            arguments.get("code", ""), cancel_event, effective_timeout, session_id
-        )
+        return _python_exec(arguments.get("code", ""), cancel_event, effective_timeout, session_id)
     if name == "terminal":
-        return _bash_exec(
-            arguments.get("command", ""), cancel_event, effective_timeout, session_id
-        )
+        return _bash_exec(arguments.get("command", ""), cancel_event, effective_timeout, session_id)
     return f"Unknown tool: {name}"
 
 
@@ -867,7 +840,9 @@ def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str
 
 
 def _fetch_page_text(
-    url: str, max_chars: int = _MAX_PAGE_CHARS, timeout: int = 30
+    url: str,
+    max_chars: int = _MAX_PAGE_CHARS,
+    timeout: int = 30,
 ) -> str:
     """Fetch a URL and return plain text content (HTML tags stripped).
 
@@ -921,9 +896,7 @@ def _fetch_page_text(
                 resp = opener.open(req, timeout = timeout)
             except _HTTPError as e:
                 if e.code not in (301, 302, 303, 307, 308):
-                    return (
-                        f"Failed to fetch URL: HTTP {e.code} {getattr(e, 'reason', '')}"
-                    )
+                    return f"Failed to fetch URL: HTTP {e.code} {getattr(e, 'reason', '')}"
                 location = e.headers.get("Location")
                 if not location:
                     return "Failed to fetch URL: redirect missing Location header."
@@ -1188,9 +1161,7 @@ def _check_signal_escape_patterns(code: str):
             if func_name:
                 if func_name in ("signal.signal", "signal"):
                     if len(node.args) >= 1:
-                        if _ast_name_matches(
-                            node.args[0], ("SIGALRM", "signal.SIGALRM")
-                        ):
+                        if _ast_name_matches(node.args[0], ("SIGALRM", "signal.SIGALRM")):
                             signal_tampering.append(
                                 {
                                     "type": "signal_handler_override",
@@ -1200,9 +1171,7 @@ def _check_signal_escape_patterns(code: str):
                             )
                 elif func_name in ("signal.setitimer", "setitimer"):
                     if len(node.args) >= 1:
-                        if _ast_name_matches(
-                            node.args[0], ("ITIMER_REAL", "signal.ITIMER_REAL")
-                        ):
+                        if _ast_name_matches(node.args[0], ("ITIMER_REAL", "signal.ITIMER_REAL")):
                             signal_tampering.append(
                                 {
                                     "type": "timer_manipulation",
@@ -1255,9 +1224,7 @@ def _check_signal_escape_patterns(code: str):
                     else:
                         has_opaque_kwargs = True
 
-                cmd_kw_values = [
-                    v for k, v in expanded_kwargs.items() if k in _CMD_KWARGS
-                ]
+                cmd_kw_values = [v for k, v in expanded_kwargs.items() if k in _CMD_KWARGS]
                 all_call_args = list(node.args) + cmd_kw_values
                 blocked_in_args = _check_args_for_blocked(all_call_args)
 
@@ -1267,9 +1234,7 @@ def _check_signal_escape_patterns(code: str):
                         {
                             "type": "shell_escape_dynamic",
                             "line": node.lineno,
-                            "description": (
-                                f"{shell_func}() called with dynamic **kwargs"
-                            ),
+                            "description": (f"{shell_func}() called with dynamic **kwargs"),
                         }
                     )
                 elif blocked_in_args:
@@ -1301,8 +1266,7 @@ def _check_signal_escape_patterns(code: str):
                     )
                     shell_node = expanded_kwargs.get("shell")
                     shell_safe = shell_node is None or (
-                        isinstance(shell_node, ast.Constant)
-                        and shell_node.value is False
+                        isinstance(shell_node, ast.Constant) and shell_node.value is False
                     )
                     # Dynamic shell-exec args (chr/format/concat bypasses).
                     if (
@@ -1315,15 +1279,10 @@ def _check_signal_escape_patterns(code: str):
                             if _extract_string_from_node(n) is not None:
                                 return True
                             if isinstance(n, (ast.List, ast.Tuple)):
-                                return all(
-                                    _extract_string_from_node(e) is not None
-                                    for e in n.elts
-                                )
+                                return all(_extract_string_from_node(e) is not None for e in n.elts)
                             return False
 
-                        has_non_literal = any(
-                            not _is_safe_literal(a) for a in all_call_args
-                        )
+                        has_non_literal = any(not _is_safe_literal(a) for a in all_call_args)
                         if has_non_literal:
                             shell_escapes.append(
                                 {
@@ -1582,9 +1541,7 @@ def _check_signal_escape_patterns(code: str):
         "/etc/sudoers",
         "/etc/ssh/",
     )
-    _SENSITIVE_FILE_RE = re.compile(
-        r"^/proc/(?:self|\d+)/(?:environ|cmdline|task/\d+/environ)$"
-    )
+    _SENSITIVE_FILE_RE = re.compile(r"^/proc/(?:self|\d+)/(?:environ|cmdline|task/\d+/environ)$")
 
     def _normalize_host(host: str) -> str:
         if not host:
@@ -1627,15 +1584,9 @@ def _check_signal_escape_patterns(code: str):
                 return True
             if kw.arg == "data":
                 v = kw.value
-                if (
-                    isinstance(v, ast.Call)
-                    and isinstance(v.func, ast.Name)
-                    and v.func.id == "open"
-                ):
+                if isinstance(v, ast.Call) and isinstance(v.func, ast.Name) and v.func.id == "open":
                     return True
-                if isinstance(v, ast.Constant) and isinstance(
-                    v.value, (bytes, bytearray)
-                ):
+                if isinstance(v, ast.Constant) and isinstance(v.value, (bytes, bytearray)):
                     return True
         return False
 
@@ -1777,9 +1728,7 @@ def _check_signal_escape_patterns(code: str):
         """Whether the path argument resolves to a sandbox-local literal."""
         if node is None:
             return False
-        if isinstance(node, ast.Constant) and isinstance(
-            node.value, (bytes, bytearray)
-        ):
+        if isinstance(node, ast.Constant) and isinstance(node.value, (bytes, bytearray)):
             return True  # inline bytes, no file access
         if isinstance(node, ast.Constant) and isinstance(node.value, str):
             return _is_safe_relative_path(node.value)
@@ -1865,11 +1814,7 @@ def _check_signal_escape_patterns(code: str):
                     )
 
             # Direct sock.connect((host, port)) bypasses the FQ-prefix branch below.
-            if (
-                isinstance(node.func, ast.Attribute)
-                and node.func.attr == "connect"
-                and node.args
-            ):
+            if isinstance(node.func, ast.Attribute) and node.func.attr == "connect" and node.args:
                 a0 = node.args[0]
                 host_lit = None
                 if isinstance(a0, ast.Tuple) and a0.elts:
@@ -1906,9 +1851,7 @@ def _check_signal_escape_patterns(code: str):
                         {
                             "type": "upload_blocked",
                             "line": getattr(node, "lineno", -1),
-                            "description": (
-                                "Blocked: file upload disallowed in sandbox"
-                            ),
+                            "description": ("Blocked: file upload disallowed in sandbox"),
                         }
                     )
 
@@ -2010,28 +1953,18 @@ def _check_code_safety(code: str) -> str | None:
         if info.get("error"):
             return None
 
-        reasons = [
-            item.get("description", "") for item in info.get("signal_tampering", [])
-        ]
-        shell_reasons = [
-            item.get("description", "") for item in info.get("shell_escapes", [])
-        ]
+        reasons = [item.get("description", "") for item in info.get("signal_tampering", [])]
+        shell_reasons = [item.get("description", "") for item in info.get("shell_escapes", [])]
         exception_reasons = [
             item.get("description", "") for item in info.get("exception_catching", [])
         ]
-        network_reasons = [
-            item.get("description", "") for item in info.get("network_calls", [])
-        ]
+        network_reasons = [item.get("description", "") for item in info.get("network_calls", [])]
         file_reasons = [
             item.get("description", "") for item in info.get("sensitive_file_reads", [])
         ]
         all_reasons = [
             r
-            for r in reasons
-            + shell_reasons
-            + exception_reasons
-            + network_reasons
-            + file_reasons
+            for r in reasons + shell_reasons + exception_reasons + network_reasons + file_reasons
             if r
         ]
         if all_reasons:
@@ -2063,7 +1996,11 @@ def _kill_process_tree(proc) -> None:
         pass
 
 
-def _cancel_watcher(proc, cancel_event, poll_interval = 0.2):
+def _cancel_watcher(
+    proc,
+    cancel_event,
+    poll_interval = 0.2,
+):
     """Daemon thread that kills a process when cancel_event is set."""
     while proc.poll() is None:
         if cancel_event is not None and cancel_event.is_set():
@@ -2107,9 +2044,7 @@ def _python_exec(
                     except OSError:
                         pass
     try:
-        fd, tmp_path = tempfile.mkstemp(
-            suffix = ".py", prefix = "studio_exec_", dir = workdir
-        )
+        fd, tmp_path = tempfile.mkstemp(suffix = ".py", prefix = "studio_exec_", dir = workdir)
         with os.fdopen(fd, "w") as f:
             f.write(code)
 
@@ -2170,7 +2105,6 @@ def _python_exec(
                     new_images.append(_name)
             if new_images:
                 import json as _json
-
                 result += f"\n__IMAGES__:{_json.dumps(sorted(new_images))}"
 
         return result
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 31fd55a156..525aa53a70 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -93,9 +93,7 @@ def _build_model_config(config: dict):
     return mc
 
 
-def _get_hf_download_state(
-    model_names: list[str] | None = None,
-) -> tuple[int, bool] | None:
+def _get_hf_download_state(model_names: list[str] | None = None) -> tuple[int, bool] | None:
     """Return (total_bytes, has_incomplete) for the HF Hub cache, or None on error.
 
     When *model_names* is provided, only those models' ``blobs/``
@@ -124,7 +122,6 @@ def _get_hf_download_state(
 
         if model_names:
             from utils.paths import resolve_cached_repo_id_case
-
             for name in model_names:
                 if not name:
                     continue
@@ -265,14 +262,10 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                         adapter_cfg = json.load(f)
                     training_method = adapter_cfg.get("unsloth_training_method")
                     if training_method == "lora" and load_in_4bit:
-                        logger.info(
-                            "adapter_config.json says lora — setting load_in_4bit=False"
-                        )
+                        logger.info("adapter_config.json says lora — setting load_in_4bit=False")
                         load_in_4bit = False
                     elif training_method == "qlora" and not load_in_4bit:
-                        logger.info(
-                            "adapter_config.json says qlora — setting load_in_4bit=True"
-                        )
+                        logger.info("adapter_config.json says qlora — setting load_in_4bit=True")
                         load_in_4bit = True
                     elif not training_method:
                         if (
@@ -401,12 +394,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
         )
 
 
-def _handle_generate(
-    backend,
-    cmd: dict,
-    resp_queue: Any,
-    cancel_event,
-) -> None:
+def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
     """Handle a generate command: stream tokens back via resp_queue.
 
     cancel_event is an mp.Event shared with the parent process.
@@ -504,11 +492,7 @@ def _handle_generate(
         )
 
 
-def _handle_generate_audio(
-    backend,
-    cmd: dict,
-    resp_queue: Any,
-) -> None:
+def _handle_generate_audio(backend, cmd: dict, resp_queue: Any) -> None:
     """Handle TTS audio generation — returns WAV bytes + sample_rate."""
     request_id = cmd.get("request_id", "")
     try:
@@ -551,12 +535,7 @@ def _handle_generate_audio(
         )
 
 
-def _handle_generate_audio_input(
-    backend,
-    cmd: dict,
-    resp_queue: Any,
-    cancel_event,
-) -> None:
+def _handle_generate_audio_input(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
     """Handle audio input generation (ASR/Whisper) — streams text tokens back."""
     request_id = cmd.get("request_id", "")
 
@@ -591,9 +570,7 @@ def _handle_generate_audio_input(
 
         for text_chunk in generator:
             if cancel_event.is_set():
-                logger.info(
-                    "Audio input generation cancelled for request %s", request_id
-                )
+                logger.info("Audio input generation cancelled for request %s", request_id)
                 break
 
             _send_response(
@@ -660,13 +637,7 @@ def _handle_unload(backend, cmd: dict, resp_queue: Any) -> None:
         )
 
 
-def run_inference_process(
-    *,
-    cmd_queue: Any,
-    resp_queue: Any,
-    cancel_event,
-    config: dict,
-) -> None:
+def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, config: dict) -> None:
     """Subprocess entrypoint. Persistent — runs command loop until shutdown.
 
     Args:
@@ -676,9 +647,7 @@ def run_inference_process(
         config: Initial configuration dict with model info.
     """
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
-    os.environ["PYTHONWARNINGS"] = (
-        "ignore"  # Suppress warnings at C-level before imports
-    )
+    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
 
     if config.get("disable_xet"):
         os.environ["HF_HUB_DISABLE_XET"] = "1"
@@ -810,7 +779,6 @@ def run_inference_process(
     if sys.platform == "win32":
         try:
             import triton  # noqa: F401
-
             logger.info("Triton available — torch.compile enabled")
         except ImportError:
             os.environ["TORCHDYNAMO_DISABLE"] = "1"
@@ -986,9 +954,7 @@ def run_inference_process(
                 )
 
         except Exception as exc:
-            logger.error(
-                "Error handling command '%s': %s", cmd_type, exc, exc_info = True
-            )
+            logger.error("Error handling command '%s': %s", cmd_type, exc, exc_info = True)
             _send_response(
                 resp_queue,
                 {
diff --git a/studio/backend/core/tool_healing.py b/studio/backend/core/tool_healing.py
index e8bd7d9ea4..77619bcdb3 100644
--- a/studio/backend/core/tool_healing.py
+++ b/studio/backend/core/tool_healing.py
@@ -87,9 +87,7 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                     },
                 }
                 if isinstance(tc["function"]["arguments"], dict):
-                    tc["function"]["arguments"] = json.dumps(
-                        tc["function"]["arguments"]
-                    )
+                    tc["function"]["arguments"] = json.dumps(tc["function"]["arguments"])
                 tool_calls.append(tc)
             except (json.JSONDecodeError, ValueError):
                 pass
@@ -108,11 +106,7 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
             func_name = fm.group(1)
             body_start = fm.end()
             # Hard boundaries: next <function= tag or </tool_call>
-            next_func = (
-                func_starts[idx + 1].start()
-                if idx + 1 < len(func_starts)
-                else len(content)
-            )
+            next_func = func_starts[idx + 1].start() if idx + 1 < len(func_starts) else len(content)
             end_tag = _TC_END_TAG_RE.search(content[body_start:])
             if end_tag:
                 body_end = body_start + end_tag.start()
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 0365b3ffd8..781c18ff15 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -22,9 +22,7 @@ os.environ["TOKENIZERS_PARALLELISM"] = "false"
 # (not just Pool workers) can find compiled modules.
 # NOTE: Do NOT import unsloth_zoo.compiler here -- it triggers heavy torch/triton imports.
 if sys.platform in ("win32", "darwin"):
-    _compile_cache = os.environ.get(
-        "UNSLOTH_COMPILE_LOCATION", "unsloth_compiled_cache"
-    )
+    _compile_cache = os.environ.get("UNSLOTH_COMPILE_LOCATION", "unsloth_compiled_cache")
     if not os.path.isabs(_compile_cache):
         _compile_cache = os.path.abspath(_compile_cache)
         os.environ["UNSLOTH_COMPILE_LOCATION"] = _compile_cache
@@ -136,16 +134,10 @@ class UnslothTrainer:
         self.is_cpt = False  # Set to True for Continued Pretraining
         self.is_vlm = False
         self.is_audio = False
-        self.is_audio_vlm = (
-            False  # Multimodal model (e.g. Gemma 3N) trained on audio data
-        )
+        self.is_audio_vlm = False  # Multimodal model (e.g. Gemma 3N) trained on audio data
         self._audio_type = None  # 'csm', 'whisper', 'snac', 'bicodec', 'dac'
-        self._cuda_audio_used = (
-            False  # Set once after audio CUDA preprocessing; never cleared
-        )
-        self._spark_tts_repo_dir = (
-            None  # Path to downloaded Spark-TTS repo (for BiCodecTokenizer)
-        )
+        self._cuda_audio_used = False  # Set once after audio CUDA preprocessing; never cleared
+        self._spark_tts_repo_dir = None  # Path to downloaded Spark-TTS repo (for BiCodecTokenizer)
         self.model_name = None
 
         # Training metrics tracking
@@ -205,11 +197,7 @@ class UnslothTrainer:
             self._cuda_audio_used = False
 
         # --- Detect VLM ---
-        vision = (
-            is_vision_model(model_name, hf_token = hf_token)
-            if not self.is_audio
-            else False
-        )
+        vision = is_vision_model(model_name, hf_token = hf_token) if not self.is_audio else False
         self.is_vlm = not self.is_audio_vlm and vision and is_dataset_image
 
         logger.info(
@@ -225,7 +213,6 @@ class UnslothTrainer:
         # All others work with AutoTokenizer (CSM loads its own processor inline).
         if self._audio_type == "whisper":
             from transformers import AutoProcessor
-
             self.tokenizer = AutoProcessor.from_pretrained(
                 model_name,
                 trust_remote_code = trust_remote_code,
@@ -233,7 +220,6 @@ class UnslothTrainer:
             )
         else:
             from transformers import AutoTokenizer
-
             self.tokenizer = AutoTokenizer.from_pretrained(
                 model_name,
                 trust_remote_code = trust_remote_code,
@@ -267,7 +253,14 @@ class UnslothTrainer:
         trainer_ref = self
 
         class _ProgressCallback(TrainerCallback):
-            def on_log(self, args, state, control, logs = None, **kwargs):
+            def on_log(
+                self,
+                args,
+                state,
+                control,
+                logs = None,
+                **kwargs,
+            ):
                 if not logs:
                     return
                 loss_value = logs.get("loss", logs.get("train_loss", None))
@@ -284,9 +277,7 @@ class UnslothTrainer:
                     if total_steps > 0:
                         steps_remaining = total_steps - current_step
                         if steps_remaining > 0:
-                            eta_seconds = (
-                                elapsed_seconds / current_step
-                            ) * steps_remaining
+                            eta_seconds = (elapsed_seconds / current_step) * steps_remaining
 
                 num_tokens = getattr(state, "num_input_tokens_seen", None)
 
@@ -314,9 +305,7 @@ class UnslothTrainer:
 
         return _ProgressCallback()
 
-    def _calculate_total_steps(
-        self, num_samples, batch_size, grad_accum, num_epochs, max_steps
-    ):
+    def _calculate_total_steps(self, num_samples, batch_size, grad_accum, num_epochs, max_steps):
         """Calculate total training steps from dataset size and training params."""
         if max_steps and max_steps > 0:
             return max_steps
@@ -326,16 +315,20 @@ class UnslothTrainer:
         )
         return steps_per_epoch * num_epochs
 
-    def _build_audio_training_args(self, training_args, output_dir, *, extra_args = None):
+    def _build_audio_training_args(
+        self,
+        training_args,
+        output_dir,
+        *,
+        extra_args = None,
+    ):
         """Build training args dict for audio branches.
 
         Constructs the common config (batch size, lr, warmup, fp16/bf16, etc.)
         and applies per-branch overrides via extra_args.
         """
         batch_size = training_args.get("batch_size", 2)
-        gradient_accumulation_steps = training_args.get(
-            "gradient_accumulation_steps", 4
-        )
+        gradient_accumulation_steps = training_args.get("gradient_accumulation_steps", 4)
         warmup_steps_val = training_args.get("warmup_steps", 5)
         max_steps_val = training_args.get("max_steps", 0)
         learning_rate = training_args.get("learning_rate", 2e-4)
@@ -383,7 +376,11 @@ class UnslothTrainer:
 
         return config
 
-    def _finalize_training(self, output_dir, label = ""):
+    def _finalize_training(
+        self,
+        output_dir,
+        label = "",
+    ):
         """Save model after training and update progress. Used by all training branches."""
         if self.should_stop and self.save_on_stop:
             self.trainer._save_checkpoint(self.trainer.model, trial = None)
@@ -399,9 +396,7 @@ class UnslothTrainer:
         elif self.should_stop:
             msg = f"{label} training cancelled" if label else "Training cancelled"
             logger.info(f"\n{msg}.\n")
-            self._update_progress(
-                is_training = False, status_message = "Training cancelled."
-            )
+            self._update_progress(is_training = False, status_message = "Training cancelled.")
         else:
             self.trainer.save_model()
             self.tokenizer.save_pretrained(output_dir)
@@ -429,9 +424,7 @@ class UnslothTrainer:
         ]
         # Spark-TTS path is relative to the downloaded repo
         if self._spark_tts_repo_dir:
-            spark_code_dir = os.path.join(
-                os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS"
-            )
+            spark_code_dir = os.path.join(os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS")
             audio_paths.append(spark_code_dir)
 
         removed_paths = []
@@ -452,7 +445,11 @@ class UnslothTrainer:
                 f"{len(removed_modules)} modules\n"
             )
 
-    def _resolve_audio_columns(self, dataset, custom_format_mapping: dict = None):
+    def _resolve_audio_columns(
+        self,
+        dataset,
+        custom_format_mapping: dict = None,
+    ):
         """Resolve audio, text, and speaker columns from user mapping or hardcoded fallback.
 
         Returns:
@@ -482,11 +479,7 @@ class UnslothTrainer:
         # Hardcoded fallback (existing behavior)
         audio_col = next((c for c in cols if c.lower() in ("audio", "speech")), None)
         text_col = next(
-            (
-                c
-                for c in cols
-                if c.lower() in ("text", "sentence", "transcript", "transcription")
-            ),
+            (c for c in cols if c.lower() in ("text", "sentence", "transcript", "transcription")),
             None,
         )
 
@@ -516,9 +509,7 @@ class UnslothTrainer:
     ) -> bool:
         """Load model for training (supports both text and vision models)"""
         self.load_in_4bit = load_in_4bit  # Store for training_meta.json
-        self.trust_remote_code = (
-            trust_remote_code  # For AutoProcessor etc. used during training
-        )
+        self.trust_remote_code = trust_remote_code  # For AutoProcessor etc. used during training
         try:
             if self.model is not None:
                 del self.model
@@ -554,18 +545,14 @@ class UnslothTrainer:
             # Remove stale compiled cache so the new model gets a fresh one
             from utils.cache_cleanup import clear_unsloth_compiled_cache
 
-            _preserve = (
-                ["Unsloth*Trainer.py"] if sys.platform in ("win32", "darwin") else None
-            )
+            _preserve = ["Unsloth*Trainer.py"] if sys.platform in ("win32", "darwin") else None
             clear_unsloth_compiled_cache(preserve_patterns = _preserve)
             # Detect audio model type dynamically (config.json + tokenizer)
             self._audio_type = detect_audio_type(model_name, hf_token)
             # audio_vlm is detected as an audio_type now, handle it separately
             if self._audio_type == "audio_vlm":
                 self.is_audio = False
-                self.is_audio_vlm = (
-                    is_dataset_audio  # Only use audio VLM path if dataset has audio
-                )
+                self.is_audio_vlm = is_dataset_audio  # Only use audio VLM path if dataset has audio
                 self._audio_type = None
             else:
                 self.is_audio = self._audio_type is not None
@@ -575,11 +562,7 @@ class UnslothTrainer:
                 self._cuda_audio_used = False
 
             # VLM: vision model with image dataset (mutually exclusive with audio paths)
-            vision = (
-                is_vision_model(model_name, hf_token = hf_token)
-                if not self.is_audio
-                else False
-            )
+            vision = is_vision_model(model_name, hf_token = hf_token) if not self.is_audio else False
             self.is_vlm = not self.is_audio_vlm and vision and is_dataset_image
             self.model_name = model_name
             self.max_seq_length = max_seq_length
@@ -587,9 +570,7 @@ class UnslothTrainer:
             logger.info(
                 f"Audio type: {self._audio_type}, is_audio: {self.is_audio}, is_audio_vlm: {self.is_audio_vlm}"
             )
-            logger.info(
-                f"Dataset has images: {is_dataset_image}, audio: {is_dataset_audio}"
-            )
+            logger.info(f"Dataset has images: {is_dataset_image}, audio: {is_dataset_audio}")
             logger.info(f"Using VLM path: {self.is_vlm}")
 
             # Reset training state for new run
@@ -603,12 +584,8 @@ class UnslothTrainer:
             )
 
             # Update UI immediately with loading message
-            model_display = (
-                model_name.split("/")[-1] if "/" in model_name else model_name
-            )
-            model_type_label = (
-                "audio" if self.is_audio else ("vision" if self.is_vlm else "text")
-            )
+            model_display = model_name.split("/")[-1] if "/" in model_name else model_name
+            model_type_label = "audio" if self.is_audio else ("vision" if self.is_vlm else "text")
             self._update_progress(
                 status_message = f"Loading {model_type_label} model... {model_display}"
             )
@@ -625,7 +602,6 @@ class UnslothTrainer:
             if "/" in model_name and not _env_offline():
                 try:
                     from huggingface_hub import model_info as hf_model_info
-
                     info = hf_model_info(model_name, token = hf_token or None)
                     # model_info succeeds even for gated repos (metadata is public),
                     # but info.gated tells us if files require acceptance/token.
@@ -644,7 +620,6 @@ class UnslothTrainer:
                         GatedRepoError,
                         RepositoryNotFoundError,
                     )
-
                     if isinstance(gate_err, (GatedRepoError, RepositoryNotFoundError)):
                         friendly = (
                             f"Access denied for '{model_name}'. This model is gated or private. "
@@ -669,12 +644,9 @@ class UnslothTrainer:
             # Derive ROCm inline (not hardware.IS_ROCM) because that flag is unset
             # until detect_hardware() runs, which isn't guaranteed in this subprocess.
             _is_rocm = (
-                bool(getattr(torch.version, "hip", None))
-                or "rocm" in torch.__version__.lower()
-            )
-            _auto_dtype = (
-                torch.float16 if (_is_rocm and not is_bfloat16_supported()) else None
+                bool(getattr(torch.version, "hip", None)) or "rocm" in torch.__version__.lower()
             )
+            _auto_dtype = torch.float16 if (_is_rocm and not is_bfloat16_supported()) else None
 
             # Branch based on model type
             if self._audio_type == "csm":
@@ -731,9 +703,7 @@ class UnslothTrainer:
                     token = hf_token,
                     trust_remote_code = trust_remote_code,
                 )
-                logger.info(
-                    f"Loaded {self._audio_type} audio model (FastLanguageModel)"
-                )
+                logger.info(f"Loaded {self._audio_type} audio model (FastLanguageModel)")
 
             elif self._audio_type == "bicodec":
                 # Spark-TTS: download full repo (contains sparktts package + BiCodec weights),
@@ -756,9 +726,7 @@ class UnslothTrainer:
                     llm_path = f"{local_dir}/LLM"
 
                 repo_path = snapshot_download(hf_repo, local_dir = local_dir)
-                self._spark_tts_repo_dir = os.path.abspath(
-                    repo_path
-                )  # Absolute path for sys.path
+                self._spark_tts_repo_dir = os.path.abspath(repo_path)  # Absolute path for sys.path
                 llm_path = os.path.join(self._spark_tts_repo_dir, "LLM")
 
                 self.model, self.tokenizer = FastModel.from_pretrained(
@@ -776,7 +744,6 @@ class UnslothTrainer:
             elif self._audio_type == "dac":
                 # OuteTTS: uses FastModel (not FastLanguageModel) with load_in_4bit=False
                 from unsloth import FastModel
-
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name,
                     max_seq_length = max_seq_length,
@@ -792,7 +759,6 @@ class UnslothTrainer:
                 # Audio VLM: multimodal model trained on audio (e.g. Gemma 3N)
                 # Uses FastModel (general loader) — returns (model, processor)
                 from unsloth import FastModel
-
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name = model_name,
                     max_seq_length = max_seq_length,
@@ -823,21 +789,15 @@ class UnslothTrainer:
                 from transformers import ProcessorMixin
 
                 tok = self.tokenizer
-                has_image_proc = isinstance(tok, ProcessorMixin) or hasattr(
-                    tok, "image_processor"
-                )
-                logger.info(
-                    f"\n[VLM Diagnostic] FastVisionModel returned: {type(tok).__name__}"
-                )
+                has_image_proc = isinstance(tok, ProcessorMixin) or hasattr(tok, "image_processor")
+                logger.info(f"\n[VLM Diagnostic] FastVisionModel returned: {type(tok).__name__}")
                 logger.info(
                     f"[VLM Diagnostic] Is ProcessorMixin: {isinstance(tok, ProcessorMixin)}"
                 )
                 logger.info(
                     f"[VLM Diagnostic] Has image_processor: {hasattr(tok, 'image_processor')}"
                 )
-                logger.info(
-                    f"[VLM Diagnostic] Usable as vision processor: {has_image_proc}\n"
-                )
+                logger.info(f"[VLM Diagnostic] Usable as vision processor: {has_image_proc}\n")
             else:
                 # Load text model - returns (model, tokenizer)
                 self.model, self.tokenizer = FastLanguageModel.from_pretrained(
@@ -960,9 +920,7 @@ class UnslothTrainer:
 
             # Full finetuning mode - skip PEFT entirely
             if not use_lora:
-                self._update_progress(
-                    status_message = "Full finetuning mode - no LoRA adapters"
-                )
+                self._update_progress(status_message = "Full finetuning mode - no LoRA adapters")
                 logger.info("Full finetuning mode - training all parameters\n")
                 return True
 
@@ -990,10 +948,7 @@ class UnslothTrainer:
             # Must be one of: True, False, or "unsloth"
             if isinstance(use_gradient_checkpointing, str):
                 use_gradient_checkpointing = use_gradient_checkpointing.strip().lower()
-                if (
-                    use_gradient_checkpointing == ""
-                    or use_gradient_checkpointing == "unsloth"
-                ):
+                if use_gradient_checkpointing == "" or use_gradient_checkpointing == "unsloth":
                     use_gradient_checkpointing = "unsloth"
                 elif use_gradient_checkpointing in ("true", "1", "yes"):
                     use_gradient_checkpointing = True
@@ -1021,14 +976,14 @@ class UnslothTrainer:
 
             # Check if model has the expected attributes
             if not hasattr(self.model, "config"):
-                error_msg = "Model does not have config attribute - model may not be loaded correctly"
+                error_msg = (
+                    "Model does not have config attribute - model may not be loaded correctly"
+                )
                 logger.error(error_msg)
                 self._update_progress(error = error_msg)
                 return False
 
-            logger.info(
-                f"Configuring LoRA adapters (r={lora_r}, alpha={lora_alpha})...\n"
-            )
+            logger.info(f"Configuring LoRA adapters (r={lora_r}, alpha={lora_alpha})...\n")
             logger.info(
                 f"Gradient checkpointing: {use_gradient_checkpointing} (type: {type(use_gradient_checkpointing).__name__})\n"
             )
@@ -1043,12 +998,8 @@ class UnslothTrainer:
                 logger.info(f"  - Target modules: {target_modules}")
                 if self.is_audio_vlm:
                     logger.info(f"  - Finetune vision layers: {finetune_vision_layers}")
-                    logger.info(
-                        f"  - Finetune language layers: {finetune_language_layers}"
-                    )
-                    logger.info(
-                        f"  - Finetune attention modules: {finetune_attention_modules}"
-                    )
+                    logger.info(f"  - Finetune language layers: {finetune_language_layers}")
+                    logger.info(f"  - Finetune attention modules: {finetune_attention_modules}")
                     logger.info(f"  - Finetune MLP modules: {finetune_mlp_modules}")
                 logger.info()
 
@@ -1061,9 +1012,7 @@ class UnslothTrainer:
                     use_gradient_checkpointing = use_gradient_checkpointing,
                     random_state = 3407,
                     use_rslora = use_rslora,
-                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1}
-                    if use_loftq
-                    else None,
+                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1} if use_loftq else None,
                 )
                 # Audio VLM models support VLM-style layer selection
                 if self.is_audio_vlm:
@@ -1093,9 +1042,7 @@ class UnslothTrainer:
                     use_gradient_checkpointing = use_gradient_checkpointing,
                     random_state = 3407,
                     use_rslora = use_rslora,
-                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1}
-                    if use_loftq
-                    else None,
+                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1} if use_loftq else None,
                     task_type = None,
                 )
 
@@ -1114,9 +1061,7 @@ class UnslothTrainer:
                     use_gradient_checkpointing = use_gradient_checkpointing,
                     random_state = 3407,
                     use_rslora = use_rslora,
-                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1}
-                    if use_loftq
-                    else None,
+                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1} if use_loftq else None,
                 )
 
             elif self.is_vlm:
@@ -1124,9 +1069,7 @@ class UnslothTrainer:
                 logger.info(f"Vision model LoRA configuration:")
                 logger.info(f"  - Finetune vision layers: {finetune_vision_layers}")
                 logger.info(f"  - Finetune language layers: {finetune_language_layers}")
-                logger.info(
-                    f"  - Finetune attention modules: {finetune_attention_modules}"
-                )
+                logger.info(f"  - Finetune attention modules: {finetune_attention_modules}")
                 logger.info(f"  - Finetune MLP modules: {finetune_mlp_modules}\n")
 
                 self.model = FastVisionModel.get_peft_model(
@@ -1143,9 +1086,7 @@ class UnslothTrainer:
                     use_gradient_checkpointing = use_gradient_checkpointing,
                     random_state = 3407,
                     use_rslora = use_rslora,
-                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1}
-                    if use_loftq
-                    else None,
+                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1} if use_loftq else None,
                     modules_to_save = modules_to_save,
                 )
             else:
@@ -1165,9 +1106,7 @@ class UnslothTrainer:
                     use_gradient_checkpointing = use_gradient_checkpointing,
                     random_state = 3407,
                     use_rslora = use_rslora,
-                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1}
-                    if use_loftq
-                    else None,
+                    loftq_config = {"loftq_bits": 4, "loftq_iter": 1} if use_loftq else None,
                     modules_to_save = modules_to_save,
                 )
 
@@ -1185,9 +1124,7 @@ class UnslothTrainer:
             import sys
 
             error_details = (
-                f"{type(e).__name__}: {str(e)}"
-                if str(e)
-                else f"{type(e).__name__} (no message)"
+                f"{type(e).__name__}: {str(e)}" if str(e) else f"{type(e).__name__} (no message)"
             )
             full_traceback = traceback.format_exc()
             logger.error(f"Error preparing model: {error_details}")
@@ -1256,9 +1193,7 @@ class UnslothTrainer:
             kwargs.pop("task_ids", None)
 
             # Only keep recognized TransformersKwargs
-            clean_kwargs = {
-                k: v for k, v in kwargs.items() if k in _TRANSFORMERS_KWARGS
-            }
+            clean_kwargs = {k: v for k, v in kwargs.items() if k in _TRANSFORMERS_KWARGS}
 
             if input_ids is not None and input_ids.ndim == 2:
                 merged = self._merge_input_ids_with_input_values(
@@ -1283,9 +1218,7 @@ class UnslothTrainer:
 
             backbone_hidden_states = backbone_outputs[0]
             slice_indices = (
-                slice(-logits_to_keep, None)
-                if isinstance(logits_to_keep, int)
-                else logits_to_keep
+                slice(-logits_to_keep, None) if isinstance(logits_to_keep, int) else logits_to_keep
             )
             backbone_logits = self.lm_head(backbone_hidden_states[:, slice_indices, :])
 
@@ -1303,9 +1236,7 @@ class UnslothTrainer:
                 )
 
                 train_mask = ~(labels[:, :, 1:] == -100).all(dim = -1)
-                depth_decoder_input_ids = labels[train_mask][
-                    ..., : self.config.num_codebooks - 1
-                ]
+                depth_decoder_input_ids = labels[train_mask][..., : self.config.num_codebooks - 1]
                 depth_decoder_input_ids = nn.functional.pad(
                     depth_decoder_input_ids, (1, 0), value = 0
                 )
@@ -1320,9 +1251,9 @@ class UnslothTrainer:
                 dd_kwargs = clean_kwargs.copy()
                 # Scale num_items_in_batch for depth decoder (31 codebooks)
                 if "num_items_in_batch" in dd_kwargs:
-                    dd_kwargs["num_items_in_batch"] = dd_kwargs[
-                        "num_items_in_batch"
-                    ] * (self.config.num_codebooks - 1)
+                    dd_kwargs["num_items_in_batch"] = dd_kwargs["num_items_in_batch"] * (
+                        self.config.num_codebooks - 1
+                    )
 
                 depth_decoder_outputs = self.depth_decoder(
                     input_ids = depth_decoder_input_ids,
@@ -1359,14 +1290,10 @@ class UnslothTrainer:
                     depth_decoder_outputs.logits if depth_decoder_outputs else None
                 ),
                 depth_decoder_past_key_values = (
-                    depth_decoder_outputs.past_key_values
-                    if depth_decoder_outputs
-                    else None
+                    depth_decoder_outputs.past_key_values if depth_decoder_outputs else None
                 ),
                 depth_decoder_hidden_states = (
-                    depth_decoder_outputs.hidden_states
-                    if depth_decoder_outputs
-                    else None
+                    depth_decoder_outputs.hidden_states if depth_decoder_outputs else None
                 ),
                 depth_decoder_attentions = (
                     depth_decoder_outputs.attentions if depth_decoder_outputs else None
@@ -1380,7 +1307,11 @@ class UnslothTrainer:
         CsmForConditionalGeneration.forward = _fixed_csm_forward
         logger.info("Applied CSM forward fix (class + instance level)\n")
 
-    def _preprocess_csm_dataset(self, dataset, custom_format_mapping = None):
+    def _preprocess_csm_dataset(
+        self,
+        dataset,
+        custom_format_mapping = None,
+    ):
         """Preprocess dataset for CSM TTS training (exact notebook copy)."""
         from transformers import AutoProcessor
         from datasets import Audio
@@ -1403,17 +1334,11 @@ class UnslothTrainer:
         speaker_key = resolved["speaker_col"]
 
         if audio_col is None:
-            raise ValueError(
-                f"No audio column found in dataset. Columns: {dataset.column_names}"
-            )
+            raise ValueError(f"No audio column found in dataset. Columns: {dataset.column_names}")
         if text_col is None:
-            raise ValueError(
-                f"No text column found in dataset. Columns: {dataset.column_names}"
-            )
+            raise ValueError(f"No text column found in dataset. Columns: {dataset.column_names}")
         if speaker_key is None:
-            logger.info(
-                "No speaker found, adding default 'source' of 0 for all examples\n"
-            )
+            logger.info("No speaker found, adding default 'source' of 0 for all examples\n")
             dataset = dataset.add_column("source", ["0"] * len(dataset))
             speaker_key = "source"
 
@@ -1493,18 +1418,19 @@ class UnslothTrainer:
                 )
 
         if not processed_examples:
-            raise ValueError(
-                f"No valid examples after CSM preprocessing (skipped {skipped})"
-            )
+            raise ValueError(f"No valid examples after CSM preprocessing (skipped {skipped})")
 
         result_dataset = Dataset.from_list(processed_examples)
         logger.info(
-            f"CSM preprocessing complete: {len(result_dataset)} examples "
-            f"({skipped} skipped)\n"
+            f"CSM preprocessing complete: {len(result_dataset)} examples " f"({skipped} skipped)\n"
         )
         return result_dataset
 
-    def _format_audio_vlm_dataset(self, dataset, custom_format_mapping = None):
+    def _format_audio_vlm_dataset(
+        self,
+        dataset,
+        custom_format_mapping = None,
+    ):
         """Format dataset as audio chat messages for multimodal models (e.g. Gemma 3N).
 
         Expects columns: audio (Audio), text (str).
@@ -1563,7 +1489,11 @@ class UnslothTrainer:
         logger.info(f"Audio VLM dataset formatted: {len(dataset)} examples\n")
         return dataset
 
-    def _preprocess_snac_dataset(self, dataset, custom_format_mapping = None):
+    def _preprocess_snac_dataset(
+        self,
+        dataset,
+        custom_format_mapping = None,
+    ):
         """Preprocess dataset for Orpheus TTS training with SNAC codec.
 
         Mirrors Orpheus_(3B)-TTS.ipynb: encode audio with SNAC (24kHz, 3 hierarchical
@@ -1654,9 +1584,7 @@ class UnslothTrainer:
 
                 # --- Encode audio with SNAC (notebook lines 122-142) ---
                 waveform = (
-                    torch.from_numpy(audio_data["array"])
-                    .unsqueeze(0)
-                    .to(dtype = torch.float32)
+                    torch.from_numpy(audio_data["array"]).unsqueeze(0).to(dtype = torch.float32)
                 )
                 if resample_transform is not None:
                     waveform = resample_transform(waveform)
@@ -1670,21 +1598,11 @@ class UnslothTrainer:
                 for i in range(codes[0].shape[1]):
                     all_codes.append(codes[0][0][i].item() + AUDIO_OFFSET)
                     all_codes.append(codes[1][0][2 * i].item() + AUDIO_OFFSET + 4096)
-                    all_codes.append(
-                        codes[2][0][4 * i].item() + AUDIO_OFFSET + (2 * 4096)
-                    )
-                    all_codes.append(
-                        codes[2][0][(4 * i) + 1].item() + AUDIO_OFFSET + (3 * 4096)
-                    )
-                    all_codes.append(
-                        codes[1][0][(2 * i) + 1].item() + AUDIO_OFFSET + (4 * 4096)
-                    )
-                    all_codes.append(
-                        codes[2][0][(4 * i) + 2].item() + AUDIO_OFFSET + (5 * 4096)
-                    )
-                    all_codes.append(
-                        codes[2][0][(4 * i) + 3].item() + AUDIO_OFFSET + (6 * 4096)
-                    )
+                    all_codes.append(codes[2][0][4 * i].item() + AUDIO_OFFSET + (2 * 4096))
+                    all_codes.append(codes[2][0][(4 * i) + 1].item() + AUDIO_OFFSET + (3 * 4096))
+                    all_codes.append(codes[1][0][(2 * i) + 1].item() + AUDIO_OFFSET + (4 * 4096))
+                    all_codes.append(codes[2][0][(4 * i) + 2].item() + AUDIO_OFFSET + (5 * 4096))
+                    all_codes.append(codes[2][0][(4 * i) + 3].item() + AUDIO_OFFSET + (6 * 4096))
 
                 if len(all_codes) == 0:
                     skipped += 1
@@ -1740,9 +1658,7 @@ class UnslothTrainer:
 
             # Progress update every 100 examples
             if (idx + 1) % 100 == 0:
-                self._update_progress(
-                    status_message = f"Encoding audio... {idx + 1}/{len(dataset)}"
-                )
+                self._update_progress(status_message = f"Encoding audio... {idx + 1}/{len(dataset)}")
 
         # Free SNAC model from GPU
         logger.info("Freeing SNAC codec model from GPU...\n")
@@ -1754,18 +1670,19 @@ class UnslothTrainer:
         self._cuda_audio_used = True
 
         if not processed_examples:
-            raise ValueError(
-                f"No valid examples after SNAC preprocessing (skipped {skipped})"
-            )
+            raise ValueError(f"No valid examples after SNAC preprocessing (skipped {skipped})")
 
         result_dataset = Dataset.from_list(processed_examples)
         logger.info(
-            f"SNAC preprocessing complete: {len(result_dataset)} examples "
-            f"({skipped} skipped)\n"
+            f"SNAC preprocessing complete: {len(result_dataset)} examples " f"({skipped} skipped)\n"
         )
         return result_dataset
 
-    def _preprocess_bicodec_dataset(self, dataset, custom_format_mapping = None):
+    def _preprocess_bicodec_dataset(
+        self,
+        dataset,
+        custom_format_mapping = None,
+    ):
         """Preprocess dataset for Spark-TTS training with BiCodec tokenizer.
 
         Mirrors Spark_TTS_(0_5B).ipynb: encode audio with BiCodec (semantic + global tokens),
@@ -1779,9 +1696,7 @@ class UnslothTrainer:
 
         # The sparktts Python package lives in the SparkAudio/Spark-TTS GitHub repo,
         # NOT in the unsloth/Spark-TTS-0.5B HF model repo. Clone it if needed.
-        spark_code_dir = os.path.join(
-            os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS"
-        )
+        spark_code_dir = os.path.join(os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
             self._update_progress(status_message = "Cloning Spark-TTS code repo...")
@@ -1848,9 +1763,7 @@ class UnslothTrainer:
                 return_tensors = "pt",
                 padding = True,
             )
-            input_values = processed.input_values.to(
-                audio_tokenizer.feature_extractor.device
-            )
+            input_values = processed.input_values.to(audio_tokenizer.feature_extractor.device)
             model_output = audio_tokenizer.feature_extractor(input_values)
 
             if model_output.hidden_states is None:
@@ -1899,12 +1812,8 @@ class UnslothTrainer:
                 ref_wav_np = audio_tokenizer.get_ref_clip(audio_array)
 
                 # Prepare tensors
-                audio_tensor = (
-                    torch.from_numpy(audio_array).unsqueeze(0).float().to(device)
-                )
-                ref_wav_tensor = (
-                    torch.from_numpy(ref_wav_np).unsqueeze(0).float().to(device)
-                )
+                audio_tensor = torch.from_numpy(audio_array).unsqueeze(0).float().to(device)
+                ref_wav_tensor = torch.from_numpy(ref_wav_np).unsqueeze(0).float().to(device)
 
                 # Extract wav2vec2 features
                 feat = extract_wav2vec2_features(audio_tensor)
@@ -1916,15 +1825,10 @@ class UnslothTrainer:
                 }
 
                 # BiCodec tokenize
-                semantic_token_ids, global_token_ids = audio_tokenizer.model.tokenize(
-                    batch
-                )
+                semantic_token_ids, global_token_ids = audio_tokenizer.model.tokenize(batch)
 
                 global_tokens = "".join(
-                    [
-                        f"<|bicodec_global_{i}|>"
-                        for i in global_token_ids.squeeze().cpu().numpy()
-                    ]
+                    [f"<|bicodec_global_{i}|>" for i in global_token_ids.squeeze().cpu().numpy()]
                 )
                 semantic_tokens = "".join(
                     [
@@ -1980,9 +1884,7 @@ class UnslothTrainer:
         self._cuda_audio_used = True
 
         if not processed_examples:
-            raise ValueError(
-                f"No valid examples after BiCodec preprocessing (skipped {skipped})"
-            )
+            raise ValueError(f"No valid examples after BiCodec preprocessing (skipped {skipped})")
 
         result_dataset = Dataset.from_list(processed_examples)
         logger.info(
@@ -1995,7 +1897,11 @@ class UnslothTrainer:
         logger.info(f"Sample text length: {len(sample)} chars\n")
         return result_dataset
 
-    def _preprocess_dac_dataset(self, dataset, custom_format_mapping = None):
+    def _preprocess_dac_dataset(
+        self,
+        dataset,
+        custom_format_mapping = None,
+    ):
         """Preprocess dataset for OuteTTS training with DAC codec.
 
         Mirrors Oute_TTS_(1B).ipynb DataCreationV3: uses Whisper for word timings,
@@ -2065,9 +1971,7 @@ class UnslothTrainer:
         logger.info("Cast audio column to 24kHz\n")
 
         # Load Whisper for word timings
-        self._update_progress(
-            status_message = "Loading Whisper model for word timings..."
-        )
+        self._update_progress(status_message = "Loading Whisper model for word timings...")
         logger.info("Loading Whisper model for word timings...\n")
         import whisper
 
@@ -2086,9 +1990,7 @@ class UnslothTrainer:
         prompt_processor = PromptProcessor(model_tokenizer_path)
 
         self._update_progress(status_message = "Preprocessing audio with OuteTTS...")
-        logger.info(
-            f"DAC preprocessing: audio_col='{audio_col}', text_col='{text_col}'\n"
-        )
+        logger.info(f"DAC preprocessing: audio_col='{audio_col}', text_col='{text_col}'\n")
 
         processed_examples = []
         skipped = 0
@@ -2128,9 +2030,7 @@ class UnslothTrainer:
                     tmp.flush()
                     tmp_path = tmp.name
                 try:
-                    whisper_result = whisper_model.transcribe(
-                        tmp_path, word_timestamps = True
-                    )
+                    whisper_result = whisper_model.transcribe(tmp_path, word_timestamps = True)
                 finally:
                     Path(tmp_path).unlink(missing_ok = True)
 
@@ -2191,21 +2091,21 @@ class UnslothTrainer:
         self._cuda_audio_used = True
 
         if not processed_examples:
-            raise ValueError(
-                f"No valid examples after DAC preprocessing (skipped {skipped})"
-            )
+            raise ValueError(f"No valid examples after DAC preprocessing (skipped {skipped})")
 
         result_dataset = HFDataset.from_list(processed_examples)
         logger.info(
-            f"DAC preprocessing complete: {len(result_dataset)} examples "
-            f"({skipped} skipped)\n"
+            f"DAC preprocessing complete: {len(result_dataset)} examples " f"({skipped} skipped)\n"
         )
         sample = result_dataset[0]["text"]
         logger.info(f"Sample text (first 200 chars): {sample[:200]}...\n")
         return result_dataset
 
     def _preprocess_whisper_dataset(
-        self, dataset, eval_split = None, custom_format_mapping = None
+        self,
+        dataset,
+        eval_split = None,
+        custom_format_mapping = None,
     ):
         """Preprocess dataset for Whisper speech-to-text training.
 
@@ -2226,9 +2126,7 @@ class UnslothTrainer:
             )
 
         # Cast audio to 16kHz (Whisper's expected sample rate)
-        dataset = dataset.cast_column(
-            audio_col, Audio(sampling_rate = WHISPER_SAMPLE_RATE)
-        )
+        dataset = dataset.cast_column(audio_col, Audio(sampling_rate = WHISPER_SAMPLE_RATE))
 
         # Train/eval split (notebook does dataset.train_test_split)
         eval_dataset_raw = None
@@ -2255,11 +2153,7 @@ class UnslothTrainer:
                 try:
                     audio_data = example.get(audio_col)
                     text = example.get(text_col)
-                    if (
-                        audio_data is None
-                        or audio_data.get("array") is None
-                        or not text
-                    ):
+                    if audio_data is None or audio_data.get("array") is None or not text:
                         skipped += 1
                         continue
 
@@ -2277,9 +2171,7 @@ class UnslothTrainer:
                         }
                     )
                 except Exception as e:
-                    logger.warning(
-                        f"Error processing Whisper {split_name} example {idx}: {e}"
-                    )
+                    logger.warning(f"Error processing Whisper {split_name} example {idx}: {e}")
                     skipped += 1
                     continue
 
@@ -2294,9 +2186,7 @@ class UnslothTrainer:
             return processed
 
         train_data = process_split(dataset, "train")
-        eval_data = (
-            process_split(eval_dataset_raw, "eval") if eval_dataset_raw else None
-        )
+        eval_data = process_split(eval_dataset_raw, "eval") if eval_dataset_raw else None
 
         if not train_data:
             raise ValueError("No valid examples after Whisper preprocessing")
@@ -2331,9 +2221,7 @@ class UnslothTrainer:
                 if candidates:
                     all_files.extend(str(c) for c in candidates)
                     continue
-                raise ValueError(
-                    f"No supported data files in directory: {file_path_obj}"
-                )
+                raise ValueError(f"No supported data files in directory: {file_path_obj}")
             else:
                 all_files.append(str(file_path_obj))
         return all_files
@@ -2378,9 +2266,7 @@ class UnslothTrainer:
         try:
             dataset = None
             eval_dataset = None
-            has_separate_eval_source = (
-                False  # True if eval comes from a separate HF split
-            )
+            has_separate_eval_source = False  # True if eval comes from a separate HF split
             eval_enabled = eval_steps is not None and eval_steps > 0
             raw_text_mode = is_cpt or format_type == "raw"
 
@@ -2524,9 +2410,7 @@ class UnslothTrainer:
                         if eval_dataset is not None:
                             has_separate_eval_source = True
                 else:
-                    logger.info(
-                        "Eval disabled (eval_steps <= 0), skipping eval split detection\n"
-                    )
+                    logger.info("Eval disabled (eval_steps <= 0), skipping eval split detection\n")
 
             if dataset is None:
                 raise ValueError("No dataset provided")
@@ -2535,11 +2419,7 @@ class UnslothTrainer:
             if dataset_slice_start is not None or dataset_slice_end is not None:
                 total_rows = len(dataset)
                 start = dataset_slice_start if dataset_slice_start is not None else 0
-                end = (
-                    dataset_slice_end
-                    if dataset_slice_end is not None
-                    else total_rows - 1
-                )
+                end = dataset_slice_end if dataset_slice_end is not None else total_rows - 1
                 # Clamp to valid range
                 start = max(0, min(start, total_rows - 1))
                 end = max(start, min(end, total_rows - 1))
@@ -2570,15 +2450,11 @@ class UnslothTrainer:
                 return (train_data, eval_data)
 
             elif self._audio_type == "snac":
-                processed = self._preprocess_snac_dataset(
-                    dataset, custom_format_mapping
-                )
+                processed = self._preprocess_snac_dataset(dataset, custom_format_mapping)
                 return (processed, None)
 
             elif self._audio_type == "bicodec":
-                processed = self._preprocess_bicodec_dataset(
-                    dataset, custom_format_mapping
-                )
+                processed = self._preprocess_bicodec_dataset(dataset, custom_format_mapping)
                 return ({"dataset": processed, "final_format": "audio_bicodec"}, None)
 
             elif self._audio_type == "dac":
@@ -2628,9 +2504,7 @@ class UnslothTrainer:
                 return (dataset_info, eval_dataset)
 
             elif self.is_audio_vlm:
-                formatted = self._format_audio_vlm_dataset(
-                    dataset, custom_format_mapping
-                )
+                formatted = self._format_audio_vlm_dataset(dataset, custom_format_mapping)
                 return (formatted, None)
 
             # ========== FORMAT FIRST ==========
@@ -2666,9 +2540,7 @@ class UnslothTrainer:
             self._update_progress(
                 status_message = f"Dataset ready ({final_n:,} samples, {detected} format)"
             )
-            logger.info(
-                f"Dataset formatted successfully ({final_n} samples, {detected})\n"
-            )
+            logger.info(f"Dataset formatted successfully ({final_n} samples, {detected})\n")
 
             # ========== THEN SPLIT ==========
             if has_separate_eval_source and eval_dataset is not None:
@@ -2863,15 +2735,12 @@ class UnslothTrainer:
             # compiled modules such as UnslothSFTTrainer.
             if sys.platform in ("win32", "darwin"):
                 from utils.cache_cleanup import register_compiled_cache_on_path
-
                 register_compiled_cache_on_path()
 
             # Store training parameters for metrics calculation
             self.batch_size = training_args.get("batch_size", 2)
             self.max_seq_length = training_args.get("max_seq_length", 2048)
-            self.gradient_accumulation_steps = training_args.get(
-                "gradient_accumulation_steps", 4
-            )
+            self.gradient_accumulation_steps = training_args.get("gradient_accumulation_steps", 4)
 
             # Set training start time
             self.training_start_time = time.time()
@@ -2879,15 +2748,10 @@ class UnslothTrainer:
             self._update_progress(is_training = True, error = None)
 
             # Setup logging
-            if training_args.get("enable_wandb", False) and training_args.get(
-                "wandb_token"
-            ):
+            if training_args.get("enable_wandb", False) and training_args.get("wandb_token"):
                 os.environ["WANDB_API_KEY"] = training_args["wandb_token"]
                 import wandb
-
-                wandb.init(
-                    project = training_args.get("wandb_project", "unsloth-training")
-                )
+                wandb.init(project = training_args.get("wandb_project", "unsloth-training"))
 
             # Create output directory
             output_dir = str(resolve_output_dir(training_args.get("output_dir")))
@@ -2923,9 +2787,7 @@ class UnslothTrainer:
                     training_args.get("num_epochs", 3),
                     training_args.get("max_steps", 0),
                 )
-                self._update_progress(
-                    total_steps = total, status_message = "Starting CSM training..."
-                )
+                self._update_progress(total_steps = total, status_message = "Starting CSM training...")
                 logger.info(f"CSM training config: {config}\n")
                 self.trainer.train(
                     resume_from_checkpoint = training_args.get("resume_from_checkpoint")
@@ -2964,9 +2826,7 @@ class UnslothTrainer:
                     training_args.get("num_epochs", 3),
                     training_args.get("max_steps", 0),
                 )
-                self._update_progress(
-                    total_steps = total, status_message = "Starting SNAC training..."
-                )
+                self._update_progress(total_steps = total, status_message = "Starting SNAC training...")
                 logger.info(f"SNAC training config: {config}\n")
                 self.trainer.train(
                     resume_from_checkpoint = training_args.get("resume_from_checkpoint")
@@ -2992,9 +2852,7 @@ class UnslothTrainer:
                 trainer_kwargs = {
                     "model": self.model,
                     "train_dataset": dataset,
-                    "data_collator": DataCollatorSpeechSeq2SeqWithPadding(
-                        processor = self.tokenizer
-                    ),
+                    "data_collator": DataCollatorSpeechSeq2SeqWithPadding(processor = self.tokenizer),
                     "processing_class": self.tokenizer.feature_extractor,
                     "args": Seq2SeqTrainingArguments(**config),
                 }
@@ -3034,16 +2892,12 @@ class UnslothTrainer:
             # ========== DATA COLLATOR SELECTION ==========
             # Detect special model types
             model_name_lower = self.model_name.lower()
-            is_deepseek_ocr = (
-                "deepseek" in model_name_lower and "ocr" in model_name_lower
-            )
+            is_deepseek_ocr = "deepseek" in model_name_lower and "ocr" in model_name_lower
 
             logger.info("Configuring data collator...\n")
 
             dataset_final_format = (
-                str(dataset.get("final_format", "")).lower()
-                if isinstance(dataset, dict)
-                else ""
+                str(dataset.get("final_format", "")).lower() if isinstance(dataset, dict) else ""
             )
             raw_text_mode = dataset_final_format == "raw_text"
 
@@ -3082,9 +2936,7 @@ class UnslothTrainer:
                         image_size = 640,
                         base_size = 1024,
                         crop_mode = True,
-                        train_on_responses_only = training_args.get(
-                            "train_on_completions", False
-                        ),
+                        train_on_responses_only = training_args.get("train_on_completions", False),
                     )
                     logger.info("DeepSeek OCR data collator configured successfully\n")
 
@@ -3114,9 +2966,7 @@ class UnslothTrainer:
                         texts.append(text)
                         audios.append(example[audio_col_name]["array"])
 
-                    batch = processor(
-                        text = texts, audio = audios, return_tensors = "pt", padding = True
-                    )
+                    batch = processor(text = texts, audio = audios, return_tensors = "pt", padding = True)
 
                     # Labels = input_ids with special tokens masked
                     labels = batch["input_ids"].clone()
@@ -3144,13 +2994,9 @@ class UnslothTrainer:
                 FastVisionModel.for_training(self.model)
                 vision_image_size = training_args.get("vision_image_size")
                 if vision_image_size is None:
-                    data_collator = UnslothVisionDataCollator(
-                        self.model, self.tokenizer
-                    )
+                    data_collator = UnslothVisionDataCollator(self.model, self.tokenizer)
                 else:
-                    logger.info(
-                        f"Vision image resize: {vision_image_size} (max dimension)\n"
-                    )
+                    logger.info(f"Vision image resize: {vision_image_size} (max dimension)\n")
                     data_collator = UnslothVisionDataCollator(
                         self.model,
                         self.tokenizer,
@@ -3171,12 +3017,8 @@ class UnslothTrainer:
 
             config_args = {
                 "per_device_train_batch_size": training_args.get("batch_size", 2),
-                "gradient_accumulation_steps": training_args.get(
-                    "gradient_accumulation_steps", 4
-                ),
-                "num_train_epochs": training_args.get(
-                    "num_epochs", 3
-                ),  # Default to epochs
+                "gradient_accumulation_steps": training_args.get("gradient_accumulation_steps", 4),
+                "num_train_epochs": training_args.get("num_epochs", 3),  # Default to epochs
                 "learning_rate": lr_value,
                 "fp16": not is_bfloat16_supported(),
                 "bf16": is_bfloat16_supported(),
@@ -3206,7 +3048,6 @@ class UnslothTrainer:
             # sys.path (.venv_t5) in spawned workers.
             if sys.platform in ("win32", "darwin"):
                 import transformers as _tf
-
                 if _tf.__version__.startswith("5."):
                     config_args["dataloader_num_workers"] = 0
 
@@ -3271,9 +3112,7 @@ class UnslothTrainer:
                 logger.info(f"Configuring {label} model training parameters\n")
                 # Use provided values or defaults for vision models
                 optim_value = training_args.get("optim", "adamw_torch_fused")
-                lr_scheduler_type_value = training_args.get(
-                    "lr_scheduler_type", "cosine"
-                )
+                lr_scheduler_type_value = training_args.get("lr_scheduler_type", "cosine")
                 config_args.update(
                     {
                         "optim": optim_value,
@@ -3328,9 +3167,7 @@ class UnslothTrainer:
                 # Audio VLM (e.g. Gemma 3N + audio): raw Dataset from _format_audio_vlm_dataset
                 # Notebook uses processing_class=processor.tokenizer (text tokenizer only)
                 # Raw-text runs are routed to the text path below.
-                train_dataset = (
-                    dataset if isinstance(dataset, Dataset) else dataset["dataset"]
-                )
+                train_dataset = dataset if isinstance(dataset, Dataset) else dataset["dataset"]
                 processing_class = (
                     self.tokenizer.tokenizer
                     if hasattr(self.tokenizer, "tokenizer")
@@ -3349,9 +3186,7 @@ class UnslothTrainer:
             elif self.is_vlm and not raw_text_mode:
                 # Image VLM: dataset is dict wrapper from format_and_template_dataset
                 # Raw-text runs are routed to the text path below.
-                train_dataset = (
-                    dataset["dataset"] if isinstance(dataset, dict) else dataset
-                )
+                train_dataset = dataset["dataset"] if isinstance(dataset, dict) else dataset
                 trainer_kwargs = {
                     "model": self.model,
                     "train_dataset": train_dataset,
@@ -3440,9 +3275,7 @@ class UnslothTrainer:
             )
 
             if is_cpt:
-                logger.info(
-                    "CPT mode: skipping train_on_responses_only — training on all tokens\n"
-                )
+                logger.info("CPT mode: skipping train_on_responses_only — training on all tokens\n")
             elif raw_text_mode:
                 logger.info(
                     "Raw-text mode: skipping train_on_responses_only — training on all tokens\n"
@@ -3467,16 +3300,12 @@ class UnslothTrainer:
                         logger.info(f"Detected template: {template_name}\n")
 
                         if template_name in TEMPLATE_TO_RESPONSES_MAPPER:
-                            instruction_part = TEMPLATE_TO_RESPONSES_MAPPER[
-                                template_name
-                            ]["instruction"]
-                            response_part = TEMPLATE_TO_RESPONSES_MAPPER[template_name][
-                                "response"
+                            instruction_part = TEMPLATE_TO_RESPONSES_MAPPER[template_name][
+                                "instruction"
                             ]
+                            response_part = TEMPLATE_TO_RESPONSES_MAPPER[template_name]["response"]
 
-                            logger.info(
-                                f"Instruction marker: {instruction_part[:50]}...\n"
-                            )
+                            logger.info(f"Instruction marker: {instruction_part[:50]}...\n")
                             logger.info(f"Response marker: {response_part[:50]}...\n")
                         else:
                             logger.info(
@@ -3484,9 +3313,7 @@ class UnslothTrainer:
                             )
                             train_on_responses_enabled = False
                     else:
-                        logger.info(
-                            f"No template mapping found for model: {self.model_name}\n"
-                        )
+                        logger.info(f"No template mapping found for model: {self.model_name}\n")
                         train_on_responses_enabled = False
 
                 except Exception as e:
@@ -3522,11 +3349,7 @@ class UnslothTrainer:
                     filtered_len = len(self.trainer.train_dataset)
                     original_len = len(dataset["dataset"])
                     dropped = original_len - filtered_len
-                    drop_pct = (
-                        round(100 * dropped / original_len, 1)
-                        if original_len > 0
-                        else 0
-                    )
+                    drop_pct = round(100 * dropped / original_len, 1) if original_len > 0 else 0
 
                     if filtered_len == 0 or drop_pct > 30:
                         max_seq = training_args.get("max_seq_length", 2048)
@@ -3584,9 +3407,7 @@ class UnslothTrainer:
             # ========== PROGRESS TRACKING ==========
             self.trainer.add_callback(self._create_progress_callback())
 
-            num_samples = len(
-                dataset["dataset"] if isinstance(dataset, dict) else dataset
-            )
+            num_samples = len(dataset["dataset"] if isinstance(dataset, dict) else dataset)
             batch_size = training_args.get("batch_size", 2)
             total_steps = self._calculate_total_steps(
                 num_samples,
@@ -3600,9 +3421,7 @@ class UnslothTrainer:
             # ========== START TRAINING ==========
             self._update_progress(status_message = "Starting training...")
             logger.info("Starting training...\n")
-            self.trainer.train(
-                resume_from_checkpoint = training_args.get("resume_from_checkpoint")
-            )
+            self.trainer.train(resume_from_checkpoint = training_args.get("resume_from_checkpoint"))
 
             # ========== SAVE MODEL ==========
             self._finalize_training(output_dir)
@@ -3641,9 +3460,7 @@ class UnslothTrainer:
                 method = "lora"
 
             config["unsloth_training_method"] = method
-            logger.info(
-                f"Patching adapter_config.json with unsloth_training_method='{method}'"
-            )
+            logger.info(f"Patching adapter_config.json with unsloth_training_method='{method}'")
 
             with open(config_path, "w") as f:
                 json.dump(config, f, indent = 2)
@@ -3657,9 +3474,7 @@ class UnslothTrainer:
         self.should_stop = True
         self.save_on_stop = save
         stop_msg = (
-            "Stopping training and saving checkpoint..."
-            if save
-            else "Cancelling training..."
+            "Stopping training and saving checkpoint..." if save else "Cancelling training..."
         )
         self._update_progress(status_message = stop_msg)
 
@@ -3700,16 +3515,13 @@ def _ensure_deepseek_ocr_installed():
     try:
         # Try importing to see if already available
         from deepseek_ocr.modeling_deepseekocr import format_messages
-
         logger.info("DeepSeek OCR module already available")
         return True
     except ImportError:
         pass
 
     try:
-        logger.info(
-            "DeepSeek OCR module not found. Auto-installing from HuggingFace..."
-        )
+        logger.info("DeepSeek OCR module not found. Auto-installing from HuggingFace...")
         logger.info("\n Downloading DeepSeek OCR module from HuggingFace...\n")
 
         from huggingface_hub import snapshot_download
@@ -3723,9 +3535,7 @@ def _ensure_deepseek_ocr_installed():
         # Download to project root as 'deepseek_ocr' folder
         local_dir = os.path.join(parent_dir, "deepseek_ocr")
 
-        snapshot_download(
-            "unsloth/DeepSeek-OCR", local_dir = local_dir, local_dir_use_symlinks = False
-        )
+        snapshot_download("unsloth/DeepSeek-OCR", local_dir = local_dir, local_dir_use_symlinks = False)
 
         # Add to sys.path if not already there
         if parent_dir not in sys.path:
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index 0af3349c6f..d27109aedb 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -180,9 +180,7 @@ class TrainingBackend:
         if self._pump_thread is not None and self._pump_thread.is_alive():
             self._pump_thread.join(timeout = 5.0)
             if self._pump_thread.is_alive():
-                logger.warning(
-                    "Previous pump thread did not exit within 5s — refusing to start"
-                )
+                logger.warning("Previous pump thread did not exit within 5s — refusing to start")
                 return False
         self._pump_thread = None
 
@@ -234,9 +232,7 @@ class TrainingBackend:
             "train_on_completions": kwargs.get("train_on_completions", False),
             "finetune_vision_layers": kwargs.get("finetune_vision_layers", True),
             "finetune_language_layers": kwargs.get("finetune_language_layers", True),
-            "finetune_attention_modules": kwargs.get(
-                "finetune_attention_modules", True
-            ),
+            "finetune_attention_modules": kwargs.get("finetune_attention_modules", True),
             "finetune_mlp_modules": kwargs.get("finetune_mlp_modules", True),
             "enable_wandb": kwargs.get("enable_wandb", False),
             "wandb_token": kwargs.get("wandb_token"),
@@ -321,9 +317,7 @@ class TrainingBackend:
         self._run_finalized = False
         self._db_run_created = False
         self._db_total_steps_set = False
-        self._db_config = {
-            k: v for k, v in config.items() if k not in {"hf_token", "wandb_token"}
-        }
+        self._db_config = {k: v for k, v in config.items() if k not in {"hf_token", "wandb_token"}}
         self._db_started_at = datetime.now(timezone.utc).isoformat()
 
         # Assign subprocess handles after state reset
@@ -353,9 +347,7 @@ class TrainingBackend:
                     pass
             # Update progress immediately for responsive UI
             self._progress.status_message = (
-                "Stopping training and saving checkpoint..."
-                if save
-                else "Cancelling training..."
+                "Stopping training and saving checkpoint..." if save else "Cancelling training..."
             )
         return True
 
@@ -363,9 +355,7 @@ class TrainingBackend:
         """Force-kill the training subprocess so state can be reset immediately."""
         with self._lock:
             if self._proc is not None and self._proc.is_alive():
-                logger.info(
-                    "Force-terminating training subprocess (pid=%s)", self._proc.pid
-                )
+                logger.info("Force-terminating training subprocess (pid=%s)", self._proc.pid)
                 self._proc.terminate()
             proc = self._proc
             cancelled = self._cancel_requested
@@ -525,8 +515,7 @@ class TrainingBackend:
                     else:
                         self._progress.is_training = False
                         self._progress.error = (
-                            self._progress.error
-                            or "Training process exited unexpectedly"
+                            self._progress.error or "Training process exited unexpectedly"
                         )
 
             self._ensure_db_run_created()
@@ -566,9 +555,7 @@ class TrainingBackend:
                 try:
                     _safe_lr = float(_raw_lr) if _raw_lr is not None else None
                 except (TypeError, ValueError):
-                    logger.debug(
-                        "Could not convert learning_rate to float: %s", _raw_lr
-                    )
+                    logger.debug("Could not convert learning_rate to float: %s", _raw_lr)
                     _safe_lr = None
                 if _safe_lr is not None and not math.isfinite(_safe_lr):
                     _safe_lr = None
@@ -576,9 +563,7 @@ class TrainingBackend:
                     self._progress.loss = _safe_loss
                 if _safe_lr is not None:
                     self._progress.learning_rate = _safe_lr
-                self._progress.total_steps = event.get(
-                    "total_steps", self._progress.total_steps
-                )
+                self._progress.total_steps = event.get("total_steps", self._progress.total_steps)
                 self._progress.elapsed_seconds = event.get("elapsed_seconds")
                 self._progress.eta_seconds = event.get("eta_seconds")
                 self._progress.grad_norm = event.get("grad_norm")
@@ -622,9 +607,7 @@ class TrainingBackend:
                     try:
                         eval_loss = float(eval_loss)
                     except (TypeError, ValueError):
-                        logger.debug(
-                            "Could not convert eval_loss to float: %s", eval_loss
-                        )
+                        logger.debug("Could not convert eval_loss to float: %s", eval_loss)
                         eval_loss = None
                     if step > 0 and eval_loss is not None and math.isfinite(eval_loss):
                         self.eval_loss_history.append(eval_loss)
@@ -654,12 +637,9 @@ class TrainingBackend:
                         "job_id": self.current_job_id,
                         "model_name": self._db_config["model_name"],
                         "dataset_name": self._db_config.get("hf_dataset")
-                        or next(
-                            iter(self._db_config.get("local_datasets") or []), "unknown"
-                        ),
+                        or next(iter(self._db_config.get("local_datasets") or []), "unknown"),
                         "config_json": _json.dumps(self._db_config),
-                        "started_at": self._db_started_at
-                        or datetime.now(timezone.utc).isoformat(),
+                        "started_at": self._db_started_at or datetime.now(timezone.utc).isoformat(),
                         "total_steps": event.get("total_steps"),
                     }
                 elif (
@@ -737,10 +717,7 @@ class TrainingBackend:
         elif db_action == "update_total_steps":
             try:
                 from storage.studio_db import update_run_total_steps
-
-                update_run_total_steps(
-                    db_action_kwargs["job_id"], db_action_kwargs["total_steps"]
-                )
+                update_run_total_steps(db_action_kwargs["job_id"], db_action_kwargs["total_steps"])
                 self._db_total_steps_set = True
             except Exception:
                 logger.warning("Failed to update total_steps in DB", exc_info = True)
@@ -764,15 +741,12 @@ class TrainingBackend:
                 model_name = self._db_config["model_name"],
                 dataset_name = dataset_name,
                 config_json = _json.dumps(self._db_config),
-                started_at = self._db_started_at
-                or datetime.now(timezone.utc).isoformat(),
+                started_at = self._db_started_at or datetime.now(timezone.utc).isoformat(),
                 total_steps = self._progress.total_steps or None,
             )
             self._db_run_created = True
         except Exception:
-            logger.warning(
-                "Failed to create DB run record for early failure", exc_info = True
-            )
+            logger.warning("Failed to create DB run record for early failure", exc_info = True)
 
     def _finalize_run_in_db(
         self,
@@ -795,10 +769,7 @@ class TrainingBackend:
                 ended_at = datetime.now(timezone.utc).isoformat(),
                 final_step = self._progress.step,
                 final_loss = self._progress.loss
-                if (
-                    self._progress.loss is not None
-                    and math.isfinite(self._progress.loss)
-                )
+                if (self._progress.loss is not None and math.isfinite(self._progress.loss))
                 else None,
                 duration_seconds = self._progress.elapsed_seconds,
                 loss_sparkline = _json.dumps(sparkline),
@@ -807,17 +778,11 @@ class TrainingBackend:
             )
             self._run_finalized = True
         except Exception:
-            logger.warning(
-                "Failed to finalize run in DB (status=%s)", status, exc_info = True
-            )
+            logger.warning("Failed to finalize run in DB (status=%s)", status, exc_info = True)
 
     def _flush_metrics_to_db(self) -> None:
         """Flush buffered metrics to the database and update live progress."""
-        if (
-            not self._metric_buffer
-            or not self.current_job_id
-            or not self._db_run_created
-        ):
+        if not self._metric_buffer or not self.current_job_id or not self._db_run_created:
             return
         # Cap buffer to prevent unbounded memory growth
         if len(self._metric_buffer) > 500:
@@ -837,10 +802,7 @@ class TrainingBackend:
                 id = self.current_job_id,
                 step = self._progress.step,
                 loss = self._progress.loss
-                if (
-                    self._progress.loss is not None
-                    and math.isfinite(self._progress.loss)
-                )
+                if (self._progress.loss is not None and math.isfinite(self._progress.loss))
                 else None,
                 duration_seconds = self._progress.elapsed_seconds,
             )
@@ -873,7 +835,9 @@ class TrainingBackend:
     # ------------------------------------------------------------------
 
     def _create_loss_plot(
-        self, progress: TrainingProgress, theme: str = "light"
+        self,
+        progress: TrainingProgress,
+        theme: str = "light",
     ) -> plt.Figure:
         """Create training loss plot with theme-aware styling."""
         plt.close("all")
@@ -956,9 +920,7 @@ class TrainingBackend:
             else:
                 title = "Training Loss"
 
-            ax.set_title(
-                title, fontsize = 11, fontweight = "bold", pad = 10, color = style["text"]
-            )
+            ax.set_title(title, fontsize = 11, fontweight = "bold", pad = 10, color = style["text"])
             ax.grid(True, alpha = 0.4, linestyle = "--", color = style["grid_color"])
             ax.tick_params(colors = style["text"], which = "both")
             ax.spines["top"].set_visible(False)
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index e4ef95a375..d5d8186815 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -40,9 +40,7 @@ from utils.wheel_utils import (
 )
 
 
-def _output_dir_from_resume_checkpoint(
-    resume_from_checkpoint: str | None,
-) -> str | None:
+def _output_dir_from_resume_checkpoint(resume_from_checkpoint: str | None) -> str | None:
     if not resume_from_checkpoint:
         return None
     path = Path(resume_from_checkpoint)
@@ -107,9 +105,7 @@ if sys.platform == "win32":
 
         try:
             if os.path.isdir(_default_root):
-                for _ver in sorted(
-                    os.listdir(_default_root), key = _ver_key, reverse = True
-                ):
+                for _ver in sorted(os.listdir(_default_root), key = _ver_key, reverse = True):
                     _bin = os.path.join(_default_root, _ver, "bin")
                     if os.path.isdir(_bin):
                         _candidates.append(_bin)
@@ -259,9 +255,7 @@ def _install_package_wheel_first(
                 "(this may take several minutes)..."
             )
         else:
-            pypi_status_message = (
-                f"Installing {display_name} from PyPI for faster training..."
-            )
+            pypi_status_message = f"Installing {display_name} from PyPI for faster training..."
 
     _send_status(event_queue, pypi_status_message)
 
@@ -353,8 +347,7 @@ def _install_package_wheel_first(
         )
         _send_status(
             event_queue,
-            f"{display_name} installation timed out after "
-            f"{_run_kwargs.get('timeout')}s",
+            f"{display_name} installation timed out after " f"{_run_kwargs.get('timeout')}s",
         )
         return False
 
@@ -435,7 +428,6 @@ def _flash_linear_attention_importable() -> bool:
     try:
         import fla.modules  # noqa: F401
         import fla.ops.gated_delta_rule  # noqa: F401
-
         return True
     except Exception as exc:
         logger.warning(
@@ -473,9 +465,7 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
     if os.getenv(_FLA_SKIP_ENV) == "1":
         return False
     if sys.platform == "win32":
-        logger.info(
-            "Skipping flash-linear-attention install: no prebuilt wheel for Windows"
-        )
+        logger.info("Skipping flash-linear-attention install: no prebuilt wheel for Windows")
         return False
     if sys.version_info < _FLA_MIN_PYTHON:
         logger.info(
@@ -550,9 +540,7 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
         )
     except _sp.TimeoutExpired:
         logger.warning("flash-linear-attention install timed out; continuing")
-        _send_status(
-            event_queue, "flash-linear-attention install timed out; continuing"
-        )
+        _send_status(event_queue, "flash-linear-attention install timed out; continuing")
         return False
 
     if result.returncode != 0:
@@ -635,7 +623,6 @@ def _discover_fla_model_types() -> frozenset[str]:
     found: set[str] = set()
     try:
         import transformers
-
         models_root = Path(transformers.__file__).parent / "models"
         for modeling in models_root.glob("*/modeling_*.py"):
             try:
@@ -665,7 +652,6 @@ def _installed_tvm_ffi_version() -> str | None:
     """Installed apache-tvm-ffi version, or None if missing/unimportable."""
     try:
         from importlib.metadata import version as _pkg_version
-
         return _pkg_version("apache-tvm-ffi")
     except Exception:
         return None
@@ -676,7 +662,6 @@ def _tilelang_importable() -> bool:
     try:
         import tilelang  # noqa: F401
         import tvm_ffi  # noqa: F401
-
         return True
     except Exception as exc:
         logger.warning(
@@ -694,7 +679,6 @@ def _torch_has_hip() -> bool:
     """
     try:
         import torch as _torch
-
         return bool(
             getattr(_torch.version, "hip", None)
             or "rocm" in getattr(_torch, "__version__", "").lower()
@@ -734,10 +718,7 @@ def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
     # Arch attrs absent — fall back to device-name matching.
     dev_lower = (getattr(props, "name", "") or "").lower()
     is_unified = (
-        "890m" in dev_lower
-        or "880m" in dev_lower
-        or "8060s" in dev_lower
-        or "8050s" in dev_lower
+        "890m" in dev_lower or "880m" in dev_lower or "8060s" in dev_lower or "8050s" in dev_lower
     )
     return gcn_arch, is_unified
 
@@ -780,9 +761,7 @@ def _run_pip(cmd: list[str], event_queue: Any, label: str) -> bool:
         _send_status(event_queue, f"{label} install timed out; continuing")
         return False
     if result.returncode != 0:
-        logger.warning(
-            "%s install failed (continuing without it):\n%s", label, result.stdout
-        )
+        logger.warning("%s install failed (continuing without it):\n%s", label, result.stdout)
         _send_status(event_queue, f"{label} install failed; continuing")
         return False
     return True
@@ -807,7 +786,6 @@ def _ensure_tilelang_backend_unconditional(event_queue: Any) -> bool:
         return False
     if not _tilelang_platform_supported():
         import platform as _platform
-
         logger.info(
             "Skipping tilelang install: no prebuilt wheel for %s/%s",
             sys.platform,
@@ -883,9 +861,7 @@ def _ensure_tilelang_backend(event_queue: Any, model_name: str) -> None:
 # UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 falls back to the legacy substring path.
 
 
-def _rebind_in_already_imported_modules(
-    *, attr_name: str, old_obj: Any, new_obj: Any
-) -> int:
+def _rebind_in_already_imported_modules(*, attr_name: str, old_obj: Any, new_obj: Any) -> int:
     """Rebind `attr_name -> new_obj` in every module that already imported `old_obj`.
 
     `from X import Y` creates a local binding that reassigning X.Y won't reach.
@@ -958,9 +934,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
                 try:
                     ok = bool(install_fn(event_queue))
                 except Exception as exc:
-                    logger.warning(
-                        "%s install raised: %s; falling back to torch", gate_name, exc
-                    )
+                    logger.warning("%s install raised: %s; falling back to torch", gate_name, exc)
                     ok = False
                 logger.info("%s hook done; available=%s", gate_name, ok)
             # post_available_fn handles "gate already True but ancillary kernel broken" (e.g. tilelang
@@ -969,9 +943,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
                 try:
                     post_available_fn(event_queue)
                 except Exception as exc:
-                    logger.warning(
-                        "%s post-available step raised: %s; continuing", gate_name, exc
-                    )
+                    logger.warning("%s post-available step raised: %s; continuing", gate_name, exc)
             state["installed"] = True
             return ok
 
@@ -982,9 +954,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
     def _fla_install(eq: Any) -> bool:
         # FLA alone ~2.35x; +tilelang adds ~26%. tilelang is GDN-only (Qwen3.5 family).
         if not _ensure_flash_linear_attention_unconditional(eq):
-            logger.info(
-                "FLA install did not produce an importable runtime; skipping TileLang"
-            )
+            logger.info("FLA install did not produce an importable runtime; skipping TileLang")
             return False
         if _model_wants_tilelang(model_name):
             _ensure_tilelang_backend_unconditional(eq)
@@ -999,10 +969,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
         # FLA already imports; repair tilelang if missing or on the broken tvm-ffi list.
         if not _model_wants_tilelang(model_name):
             return
-        if (
-            _installed_tvm_ffi_version() not in _TVM_FFI_BROKEN_VERSIONS
-            and _tilelang_importable()
-        ):
+        if _installed_tvm_ffi_version() not in _TVM_FFI_BROKEN_VERSIONS and _tilelang_importable():
             return
         _ensure_tilelang_backend_unconditional(eq)
 
@@ -1018,9 +985,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
             pypi_version = _CAUSAL_CONV1D_PACKAGE_VERSION,
             filename_prefix = "causal_conv1d",
             release_tag = _CAUSAL_CONV1D_RELEASE_TAG,
-            release_base_url = (
-                "https://github.com/Dao-AILab/causal-conv1d/releases/download"
-            ),
+            release_base_url = ("https://github.com/Dao-AILab/causal-conv1d/releases/download"),
         )
         return bool(ok)
 
@@ -1040,9 +1005,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
         rebound = _rebind_in_already_imported_modules(
             attr_name = gate_name, old_obj = original, new_obj = wrapped
         )
-        logger.info(
-            "Installed fast-path hook on %s (rebound %d modules)", gate_name, rebound
-        )
+        logger.info("Installed fast-path hook on %s (rebound %d modules)", gate_name, rebound)
 
 
 def _should_try_runtime_flash_attn_install(max_seq_length: int) -> bool:
@@ -1190,8 +1153,7 @@ def _normalize_mlx_studio_optimizer(value):
     except KeyError:
         supported = ", ".join(sorted(_MLX_STUDIO_OPTIM_MAP))
         raise ValueError(
-            f"Unsupported optimizer for MLX training: {value!r}. "
-            f"Supported values: {supported}."
+            f"Unsupported optimizer for MLX training: {value!r}. " f"Supported values: {supported}."
         )
 
 
@@ -1213,9 +1175,7 @@ def _resolve_mlx_local_dataset_files(file_paths: list) -> list[str]:
     all_files: list[str] = []
     for dataset_file in file_paths or []:
         file_path = (
-            dataset_file
-            if os.path.isabs(dataset_file)
-            else str(resolve_dataset_path(dataset_file))
+            dataset_file if os.path.isabs(dataset_file) else str(resolve_dataset_path(dataset_file))
         )
         file_path_obj = Path(file_path)
 
@@ -1313,9 +1273,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
         raise NotImplementedError(message)
 
     optim_name = _normalize_mlx_studio_optimizer(config.get("optim", "adamw_8bit"))
-    lr_scheduler_type = _normalize_mlx_studio_scheduler(
-        config.get("lr_scheduler_type", "linear")
-    )
+    lr_scheduler_type = _normalize_mlx_studio_scheduler(config.get("lr_scheduler_type", "linear"))
 
     # ── 1. Load model ──
     # Force text-only if the dataset is not an image dataset, even if the model
@@ -1344,8 +1302,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
         _send(
             "status",
             status_message = (
-                "MLX vision image resize ignored for DeepSeek OCR "
-                "(uses fixed Gundam preset)."
+                "MLX vision image resize ignored for DeepSeek OCR (uses fixed Gundam preset)."
             ),
         )
         vision_image_size = None
@@ -1391,15 +1348,9 @@ def _run_mlx_training(event_queue, stop_queue, config):
         finetune_language = config.get("finetune_language_layers", True)
         finetune_attention = config.get("finetune_attention_modules", True)
         finetune_mlp = config.get("finetune_mlp_modules", True)
-        finetune_vision = (
-            config.get("finetune_vision_layers", False) if is_vlm else False
-        )
+        finetune_vision = config.get("finetune_vision_layers", False) if is_vlm else False
 
-        if (
-            (finetune_attention or finetune_mlp)
-            and not finetune_language
-            and not finetune_vision
-        ):
+        if (finetune_attention or finetune_mlp) and not finetune_language and not finetune_vision:
             finetune_language = True
 
         peft_kwargs["finetune_language_layers"] = finetune_language
@@ -1432,9 +1383,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
 
         if len(file_paths) == 1:
             p = Path(file_paths[0])
-            if p.is_dir() and (
-                (p / "dataset_info.json").exists() or (p / "state.json").exists()
-            ):
+            if p.is_dir() and ((p / "dataset_info.json").exists() or (p / "state.json").exists()):
                 return load_from_disk(str(p))
         all_files = _resolve_mlx_local_dataset_files(file_paths)
         if not all_files:
@@ -1474,7 +1423,6 @@ def _run_mlx_training(event_queue, stop_queue, config):
     format_type = config.get("format_type", "")
     try:
         from utils.datasets import format_and_template_dataset
-
         def _fmt_progress(status_message = "", **_kw):
             _send("status", status_message = status_message)
 
@@ -1495,9 +1443,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
                 )
             else:
                 errors = vlm_info.get("errors", [])
-                raise ValueError(
-                    f"VLM dataset format conversion failed: {'; '.join(errors)}"
-                )
+                raise ValueError(f"VLM dataset format conversion failed: {'; '.join(errors)}")
             if eval_dataset is not None:
                 ev_info = format_and_template_dataset(
                     eval_dataset,
@@ -1629,11 +1575,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
             )
 
             template_name = MODEL_TO_TEMPLATE_MAPPER.get(model_name.lower())
-            markers = (
-                TEMPLATE_TO_RESPONSES_MAPPER.get(template_name)
-                if template_name
-                else None
-            )
+            markers = TEMPLATE_TO_RESPONSES_MAPPER.get(template_name) if template_name else None
             if markers:
                 trainer = train_on_responses_only(
                     trainer,
@@ -1725,11 +1667,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
                         "train/tokens_per_sec": tok_s,
                         "train/peak_gb": peak_gb,
                         "train/num_tokens": num_tokens,
-                        **(
-                            {"train/grad_norm": grad_norm}
-                            if grad_norm is not None
-                            else {}
-                        ),
+                        **({"train/grad_norm": grad_norm} if grad_norm is not None else {}),
                     },
                     step = step,
                 )
@@ -1752,9 +1690,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
         _send("progress", step = step, eval_loss = eval_loss)
         if wandb_run is not None:
             try:
-                wandb_run.log(
-                    {"eval/loss": eval_loss, "eval/perplexity": perplexity}, step = step
-                )
+                wandb_run.log({"eval/loss": eval_loss, "eval/perplexity": perplexity}, step = step)
             except Exception:
                 pass
         if tb_writer is not None:
@@ -1813,12 +1749,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
             pass
 
 
-def run_training_process(
-    *,
-    event_queue: Any,
-    stop_queue: Any,
-    config: dict,
-) -> None:
+def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) -> None:
     """Subprocess entrypoint. Fresh Python — no stale module state.
 
     Args:
@@ -1827,9 +1758,7 @@ def run_training_process(
         config: Training configuration dict with all parameters.
     """
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
-    os.environ["PYTHONWARNINGS"] = (
-        "ignore"  # Suppress warnings at C-level before imports
-    )
+    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
 
     # Offline auto-detect: skip ~25s of HF retries per call when DNS is
     # dead. Scoped to this subprocess (orchestrator spawns a fresh one).
@@ -2002,7 +1931,6 @@ def run_training_process(
     # do NOT override on macOS. Windows has no fork at all.
     if sys.platform == "linux":
         import multiprocessing as _mp
-
         try:
             _mp.set_start_method("fork", force = True)
         except RuntimeError:
@@ -2012,7 +1940,6 @@ def run_training_process(
     if sys.platform == "win32":
         try:
             import triton  # noqa: F401
-
             logger.info("Triton available — torch.compile enabled")
         except ImportError:
             os.environ["TORCHDYNAMO_DISABLE"] = "1"
@@ -2044,7 +1971,6 @@ def run_training_process(
 
     try:
         import torch.distributed as _td
-
         for _name, _stub in _td_stubs.items():
             if not hasattr(_td, _name):
                 setattr(_td, _name, _stub)
@@ -2055,7 +1981,6 @@ def run_training_process(
         sys.modules["torch.distributed"] = _td_mock
         try:
             import torch as _torch
-
             _torch.distributed = _td_mock
         except Exception:
             pass
@@ -2163,9 +2088,7 @@ def run_training_process(
             # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back
             # to that string when version.hip is missing.
             def _hip_ver_at_least(major: int, minor: int) -> bool:
-                _hip_str = getattr(
-                    getattr(_torch_for_rocm, "version", None), "hip", None
-                )
+                _hip_str = getattr(getattr(_torch_for_rocm, "version", None), "hip", None)
                 if not _hip_str:
                     # Try the standard "+rocmX.Y.Z" embedded version first
                     # (e.g. "2.11.0+rocm7.13.0").
@@ -2227,7 +2150,11 @@ def run_training_process(
                     _gm_lib = _torch_for_rocm.library.Library("aten", "IMPL")
 
                     def _grouped_mm_safe_impl(
-                        self, mat2, offs = None, bias = None, out_dtype = None
+                        self,
+                        mat2,
+                        offs = None,
+                        bias = None,
+                        out_dtype = None,
                     ):
                         """Python mm/bmm fallback for _grouped_mm on gfx1200 (null HIP kernel, ROCm ≤ 7.12)."""
                         _t = _torch_for_rocm
@@ -2266,9 +2193,7 @@ def run_training_process(
                             if prev < self.shape[0]:
                                 a_tail = self[prev:].contiguous()
                                 b_tail = (
-                                    mat2[-1].contiguous()
-                                    if mat2.dim() == 3
-                                    else mat2.contiguous()
+                                    mat2[-1].contiguous() if mat2.dim() == 3 else mat2.contiguous()
                                 )
                                 pieces.append(_t.mm(a_tail, b_tail))
                             result = (
@@ -2329,7 +2254,6 @@ def run_training_process(
     if _hw.IS_ROCM:
         try:
             import torch as _torch_mem
-
             if _torch_mem.cuda.is_available():
                 # Classify unified vs discrete via _rocm_classify_unified_memory.
                 # See that function's docstring for classification priority.
@@ -2539,15 +2463,12 @@ def run_training_process(
 
         if dataset is None or trainer.should_stop:
             if trainer.should_stop:
-                event_queue.put(
-                    {"type": "complete", "output_dir": None, "ts": time.time()}
-                )
+                event_queue.put({"type": "complete", "output_dir": None, "ts": time.time()})
             else:
                 event_queue.put(
                     {
                         "type": "error",
-                        "error": trainer.training_progress.error
-                        or "Failed to load dataset",
+                        "error": trainer.training_progress.error or "Failed to load dataset",
                         "stack": "",
                         "ts": time.time(),
                     }
@@ -2561,7 +2482,6 @@ def run_training_process(
 
         def _monitor_tqdm():
             from tqdm.auto import tqdm as _tqdm_cls
-
             while not _tqdm_stop.is_set():
                 for bar in list(getattr(_tqdm_cls, "_instances", set())):
                     try:
@@ -2569,9 +2489,7 @@ def run_training_process(
                         desc = getattr(bar, "desc", "") or ""
                         if total > 0 and n > 0 and desc:
                             pct = min(int(n * 100 / total), 100)
-                            _send_status(
-                                event_queue, f"{desc.strip()} {pct}% ({n:,}/{total:,})"
-                            )
+                            _send_status(event_queue, f"{desc.strip()} {pct}% ({n:,}/{total:,})")
                     except (AttributeError, ReferenceError):
                         pass
                 _tqdm_stop.wait(3)
@@ -2599,9 +2517,7 @@ def run_training_process(
         )
         if not success or trainer.should_stop:
             if trainer.should_stop:
-                event_queue.put(
-                    {"type": "complete", "output_dir": None, "ts": time.time()}
-                )
+                event_queue.put({"type": "complete", "output_dir": None, "ts": time.time()})
             else:
                 error_msg = trainer.training_progress.error or "Failed to load model"
                 event_queue.put(
@@ -2642,9 +2558,7 @@ def run_training_process(
                 lora_r = config.get("lora_r", 128),
                 lora_alpha = config.get("lora_alpha", 32),
                 lora_dropout = config.get("lora_dropout", 0.0),
-                use_gradient_checkpointing = config.get(
-                    "gradient_checkpointing", "unsloth"
-                ),
+                use_gradient_checkpointing = config.get("gradient_checkpointing", "unsloth"),
                 use_rslora = config.get("use_rslora", False),
                 use_loftq = config.get("use_loftq", False),
             )
@@ -2654,17 +2568,13 @@ def run_training_process(
                 use_lora = True,
                 finetune_vision_layers = config.get("finetune_vision_layers", True),
                 finetune_language_layers = config.get("finetune_language_layers", True),
-                finetune_attention_modules = config.get(
-                    "finetune_attention_modules", True
-                ),
+                finetune_attention_modules = config.get("finetune_attention_modules", True),
                 finetune_mlp_modules = config.get("finetune_mlp_modules", True),
                 target_modules = config.get("target_modules"),
                 lora_r = config.get("lora_r", 16),
                 lora_alpha = config.get("lora_alpha", 16),
                 lora_dropout = config.get("lora_dropout", 0.0),
-                use_gradient_checkpointing = config.get(
-                    "gradient_checkpointing", "unsloth"
-                ),
+                use_gradient_checkpointing = config.get("gradient_checkpointing", "unsloth"),
                 use_rslora = config.get("use_rslora", False),
                 use_loftq = config.get("use_loftq", False),
             )
@@ -2674,15 +2584,12 @@ def run_training_process(
 
         if not success or trainer.should_stop:
             if trainer.should_stop:
-                event_queue.put(
-                    {"type": "complete", "output_dir": None, "ts": time.time()}
-                )
+                event_queue.put({"type": "complete", "output_dir": None, "ts": time.time()})
             else:
                 event_queue.put(
                     {
                         "type": "error",
-                        "error": trainer.training_progress.error
-                        or "Failed to prepare model",
+                        "error": trainer.training_progress.error or "Failed to prepare model",
                         "stack": "",
                         "ts": time.time(),
                     }
@@ -2738,9 +2645,7 @@ def run_training_process(
             ensure_dir(Path(tensorboard_dir))
 
         # Start training (directly — no inner thread, we ARE the subprocess)
-        dataset_display = (
-            config.get("hf_dataset", "") or config.get("uploaded_file", "") or ""
-        )
+        dataset_display = config.get("hf_dataset", "") or config.get("uploaded_file", "") or ""
         _send_status(
             event_queue,
             f'Training "{model_name}"'
@@ -2764,9 +2669,7 @@ def run_training_process(
             weight_decay = config.get("weight_decay", 0.001),
             random_seed = config.get("random_seed", 3407),
             packing = config.get("packing", False),
-            train_on_completions = False
-            if is_cpt
-            else config.get("train_on_completions", False),
+            train_on_completions = False if is_cpt else config.get("train_on_completions", False),
             enable_wandb = config.get("enable_wandb", False),
             wandb_project = config.get("wandb_project", "unsloth-training"),
             wandb_token = config.get("wandb_token"),
@@ -3039,9 +2942,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
                     if candidates:
                         all_files.extend(str(c) for c in candidates)
                         continue
-                    raise ValueError(
-                        f"No supported data files in directory: {file_path_obj}"
-                    )
+                    raise ValueError(f"No supported data files in directory: {file_path_obj}")
                 else:
                     all_files.append(file_path)
 
@@ -3054,9 +2955,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
                 elif first_ext == ".parquet":
                     loader = "parquet"
                 else:
-                    raise ValueError(
-                        f"Unsupported local dataset format: {all_files[0]}"
-                    )
+                    raise ValueError(f"Unsupported local dataset format: {all_files[0]}")
                 dataset = load_dataset(loader, data_files = all_files, split = "train")
         else:
             event_queue.put(
@@ -3116,9 +3015,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
         resume_from_checkpoint
     )
     if not output_dir:
-        output_dir = str(
-            resolve_output_dir(f"{model_name.replace('/', '_')}_{int(time.time())}")
-        )
+        output_dir = str(resolve_output_dir(f"{model_name.replace('/', '_')}_{int(time.time())}"))
     output_dir = str(resolve_output_dir(output_dir))
 
     num_epochs = config.get("num_epochs", 2)
@@ -3179,7 +3076,14 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
     class _EmbeddingProgressCallback(TrainerCallback):
         """Sends training progress events to the parent process via event_queue."""
 
-        def on_log(self, args, state, control, logs = None, **kwargs):
+        def on_log(
+            self,
+            args,
+            state,
+            control,
+            logs = None,
+            **kwargs,
+        ):
             if not logs:
                 return
             loss_value = logs.get("loss", logs.get("train_loss", None))
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 10fbbfddf0..8e3a118e27 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -45,9 +45,7 @@ if sys.platform == "win32":
 
         try:
             if os.path.isdir(_default_root):
-                for _ver in sorted(
-                    os.listdir(_default_root), key = _ver_key, reverse = True
-                ):
+                for _ver in sorted(os.listdir(_default_root), key = _ver_key, reverse = True):
                     _bin = os.path.join(_default_root, _ver, "bin")
                     if os.path.isdir(_bin):
                         candidates.append(_bin)
@@ -83,7 +81,6 @@ if sys.platform == "win32":
         _found_rocm_bnb = False
         try:
             import importlib.util as _ilu
-
             _bnb_spec = _ilu.find_spec("bitsandbytes")
             # submodule_search_locations (not spec.origin) handles editable installs.
             if _bnb_spec and _bnb_spec.submodule_search_locations:
@@ -91,9 +88,7 @@ if sys.platform == "win32":
 
                 _all_vers_main: list[str] = []
                 for _pkg_dir in _bnb_spec.submodule_search_locations:
-                    for _dll in _glob.glob(
-                        os.path.join(_pkg_dir, "libbitsandbytes_rocm*.dll")
-                    ):
+                    for _dll in _glob.glob(os.path.join(_pkg_dir, "libbitsandbytes_rocm*.dll")):
                         _found_rocm_bnb = True
                         _km = _re_bnb.search(
                             r"libbitsandbytes_rocm(\d+)\.dll", os.path.basename(_dll)
@@ -129,9 +124,7 @@ try:
     configure_cpu_threads()
 except ValueError as exc:
     _raw = os.environ.get("UNSLOTH_CPU_THREADS")
-    raise SystemExit(
-        f"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}"
-    ) from None
+    raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}") from None
 
 # Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
 # any library imports that trigger attrs -> rich -> structlog -> platform crash.
@@ -183,9 +176,7 @@ def _read_studio_install_id() -> str:
     information for callers reaching /api/health (relevant when Studio
     is run with -H 0.0.0.0)."""
     try:
-        token = (
-            (_STUDIO_ROOT_RESOLVED / "share" / "studio_install_id").read_text().strip()
-        )
+        token = (_STUDIO_ROOT_RESOLVED / "share" / "studio_install_id").read_text().strip()
     except (OSError, ValueError):
         return ""
     return token if _STUDIO_INSTALL_ID_RE.fullmatch(token) else ""
@@ -269,9 +260,7 @@ def get_unsloth_version() -> str:
     except PackageNotFoundError:
         pass
 
-    version_file = (
-        _Path(__file__).resolve().parents[2] / "unsloth" / "models" / "_utils.py"
-    )
+    version_file = _Path(__file__).resolve().parents[2] / "unsloth" / "models" / "_utils.py"
     try:
         for line in version_file.read_text(encoding = "utf-8").splitlines():
             if line.startswith("__version__ = "):
@@ -355,10 +344,7 @@ async def lifespan(app: FastAPI):
             print(f"WARNING: {_msg}", flush = True)
     except Exception as _probe_exc:
         import structlog as _structlog
-
-        _structlog.get_logger(__name__).debug(
-            "llama.cpp startup probes failed: %s", _probe_exc
-        )
+        _structlog.get_logger(__name__).debug("llama.cpp startup probes failed: %s", _probe_exc)
 
     from storage.studio_db import cleanup_orphaned_runs
 
@@ -366,10 +352,7 @@ async def lifespan(app: FastAPI):
         cleanup_orphaned_runs()
     except Exception as exc:
         import structlog
-
-        structlog.get_logger(__name__).warning(
-            "cleanup_orphaned_runs failed at startup: %s", exc
-        )
+        structlog.get_logger(__name__).warning("cleanup_orphaned_runs failed at startup: %s", exc)
 
     # Pre-cache the helper GGUF model for LLM-assisted dataset detection.
     # Runs in a background thread so it doesn't block server startup.
@@ -378,7 +361,6 @@ async def lifespan(app: FastAPI):
     def _precache():
         try:
             from utils.datasets.llm_assist import precache_helper_gguf
-
             precache_helper_gguf()
         except Exception:
             pass  # non-critical
@@ -477,9 +459,7 @@ def _build_csp(script_nonce: "str | None" = None) -> str:
             "https://*.googleusercontent.com wss://*.googleusercontent.com"
         )
     else:
-        connect_src = (
-            "'self' https://huggingface.co https://datasets-server.huggingface.co"
-        )
+        connect_src = "'self' https://huggingface.co https://datasets-server.huggingface.co"
 
     return (
         "default-src 'self'; "
@@ -581,11 +561,7 @@ async def _send_411(send) -> None:
 
 async def _send_413(send, total_bytes: int, max_bytes: int) -> None:
     payload = _json_for_413.dumps(
-        {
-            "detail": (
-                f"Request body too large ({total_bytes:,} bytes; max {max_bytes:,})."
-            )
-        },
+        {"detail": (f"Request body too large ({total_bytes:,} bytes; max {max_bytes:,}).")},
     ).encode("utf-8")
     await send(
         {
@@ -768,9 +744,7 @@ app.include_router(mcp_servers_router, prefix = "/api/mcp/servers", tags = ["mcp
 app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"])
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
 app.include_router(export_router, prefix = "/api/export", tags = ["export"])
-app.include_router(
-    training_history_router, prefix = "/api/train", tags = ["training-history"]
-)
+app.include_router(training_history_router, prefix = "/api/train", tags = ["training-history"])
 
 
 # ============ Health and System Endpoints ============
@@ -808,9 +782,7 @@ async def health_check(request: Request):
         from auth.authentication import get_current_subject as _gcs
         from fastapi.security import HTTPAuthorizationCredentials
 
-        creds = HTTPAuthorizationCredentials(
-            scheme = "Bearer", credentials = auth.split(" ", 1)[1]
-        )
+        creds = HTTPAuthorizationCredentials(scheme = "Bearer", credentials = auth.split(" ", 1)[1])
         # Must await: a bare coroutine is truthy and would skip the auth check.
         subject = await _gcs(creds)
     except HTTPException:
@@ -843,10 +815,7 @@ def studio_update_status(_current_subject: str = Depends(get_current_subject)):
 
 
 @app.post("/api/shutdown")
-async def shutdown_server(
-    request: Request,
-    current_subject: str = Depends(get_current_subject),
-):
+async def shutdown_server(request: Request, current_subject: str = Depends(get_current_subject)):
     """Gracefully shut down the Unsloth Studio server.
 
     Called by the frontend quit dialog so users can stop the server from the UI
@@ -863,7 +832,6 @@ async def shutdown_server(
             # Fallback when not launched via run_server() (e.g. direct uvicorn)
             import signal
             import os
-
             os.kill(os.getpid(), signal.SIGTERM)
 
     request.app.state._shutdown_task = asyncio.create_task(_delayed_shutdown())
@@ -871,9 +839,7 @@ async def shutdown_server(
 
 
 @app.get("/api/system")
-async def get_system_info(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_system_info(current_subject: str = Depends(get_current_subject)):
     """Get system information.
 
     Gated behind auth: the response includes platform, Python version,
@@ -914,23 +880,18 @@ async def get_system_info(
 
 
 @app.get("/api/system/gpu-visibility")
-async def get_gpu_visibility(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_gpu_visibility(current_subject: str = Depends(get_current_subject)):
     return get_backend_visible_gpu_info()
 
 
 @app.get("/api/system/hardware")
-async def get_hardware_info(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_hardware_info(current_subject: str = Depends(get_current_subject)):
     """Return GPU name, total VRAM, and key ML package versions.
 
     Gated behind auth alongside /api/system -- same fingerprinting
     concern. /api/system/gpu-visibility is also auth-gated already.
     """
     from utils.hardware import get_gpu_summary, get_package_versions
-
     return {
         "gpu": get_gpu_summary(),
         "versions": get_package_versions(),
diff --git a/studio/backend/models/auth.py b/studio/backend/models/auth.py
index b7870379f7..9550e354a8 100644
--- a/studio/backend/models/auth.py
+++ b/studio/backend/models/auth.py
@@ -26,17 +26,13 @@ class DesktopLoginRequest(BaseModel):
 class RefreshTokenRequest(BaseModel):
     """Refresh token payload to obtain new access + refresh tokens."""
 
-    refresh_token: str = Field(
-        ..., description = "Refresh token from a previous login or refresh"
-    )
+    refresh_token: str = Field(..., description = "Refresh token from a previous login or refresh")
 
 
 class AuthStatusResponse(BaseModel):
     """Indicate whether the seeded admin auth flow is ready."""
 
-    initialized: bool = Field(
-        ..., description = "True if the auth database contains a login user"
-    )
+    initialized: bool = Field(..., description = "True if the auth database contains a login user")
     default_username: str = Field(
         "unsloth",
         description = "Default admin username for first-boot UI prefill.",
@@ -77,9 +73,7 @@ class ApiKeyResponse(BaseModel):
 
     id: int
     name: str
-    key_prefix: str = Field(
-        ..., description = "First 8 characters after sk-unsloth- for display"
-    )
+    key_prefix: str = Field(..., description = "First 8 characters after sk-unsloth- for display")
     created_at: str
     last_used_at: Optional[str] = None
     expires_at: Optional[str] = None
diff --git a/studio/backend/models/data_recipe.py b/studio/backend/models/data_recipe.py
index b382ddb3d0..f3faddf843 100644
--- a/studio/backend/models/data_recipe.py
+++ b/studio/backend/models/data_recipe.py
@@ -103,9 +103,7 @@ class SeedInspectUploadRequest(BaseModel):
             if not self.block_id:
                 raise ValueError("block_id is required when using file_ids")
             if self.file_names is None or len(self.file_ids) != len(self.file_names):
-                raise ValueError(
-                    "file_names must be provided and same length as file_ids"
-                )
+                raise ValueError("file_names must be provided and same length as file_ids")
         if has_legacy:
             if not self.filename:
                 raise ValueError("filename is required when using content_base64")
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 5a846e536e..d2fa45dd92 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -28,9 +28,7 @@ class LoadRequest(BaseModel):
     native_path_lease: Optional[str] = Field(
         None, description = "Frontend-visible signed native path grant"
     )
-    hf_token: Optional[str] = Field(
-        None, description = "HuggingFace token for gated models"
-    )
+    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated models")
     max_seq_length: int = Field(
         0,
         ge = 0,
@@ -53,9 +51,7 @@ class LoadRequest(BaseModel):
 
     @field_validator("chat_template_override")
     @classmethod
-    def normalize_blank_chat_template_override(
-        cls, value: Optional[str]
-    ) -> Optional[str]:
+    def normalize_blank_chat_template_override(cls, value: Optional[str]) -> Optional[str]:
         if value is not None and value.strip() == "":
             return None
         return value
@@ -123,9 +119,7 @@ class ValidateModelRequest(BaseModel):
     native_path_lease: Optional[str] = Field(
         None, description = "Frontend-visible signed native path grant"
     )
-    hf_token: Optional[str] = Field(
-        None, description = "HuggingFace token for gated models"
-    )
+    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated models")
     gguf_variant: Optional[str] = Field(
         None, description = "GGUF quantization variant (e.g. 'Q4_K_M')"
     )
@@ -142,9 +136,7 @@ class ValidateModelResponse(BaseModel):
     valid: bool = Field(..., description = "Whether the model identifier looks valid")
     message: str = Field(..., description = "Human-readable validation message")
     identifier: Optional[str] = Field(None, description = "Resolved model identifier")
-    display_name: Optional[str] = Field(
-        None, description = "Display name derived from identifier"
-    )
+    display_name: Optional[str] = Field(None, description = "Display name derived from identifier")
     is_gguf: bool = Field(False, description = "Whether this is a GGUF model (llama.cpp)")
     is_lora: bool = Field(False, description = "Whether this is a LoRA adapter")
     is_vision: bool = Field(False, description = "Whether this is a vision-capable model")
@@ -162,16 +154,10 @@ class GenerateRequest(BaseModel):
     temperature: float = Field(0.6, ge = 0.0, le = 2.0, description = "Sampling temperature")
     top_p: float = Field(0.95, ge = 0.0, le = 1.0, description = "Top-p sampling")
     top_k: int = Field(20, ge = -1, le = 100, description = "Top-k sampling")
-    max_new_tokens: int = Field(
-        2048, ge = 1, le = 4096, description = "Maximum tokens to generate"
-    )
-    repetition_penalty: float = Field(
-        1.0, ge = 1.0, le = 2.0, description = "Repetition penalty"
-    )
+    max_new_tokens: int = Field(2048, ge = 1, le = 4096, description = "Maximum tokens to generate")
+    repetition_penalty: float = Field(1.0, ge = 1.0, le = 2.0, description = "Repetition penalty")
     presence_penalty: float = Field(0.0, ge = 0.0, le = 2.0, description = "Presence penalty")
-    image_base64: Optional[str] = Field(
-        None, description = "Base64 encoded image for vision models"
-    )
+    image_base64: Optional[str] = Field(None, description = "Base64 encoded image for vision models")
 
 
 class LoadResponse(BaseModel):
@@ -182,16 +168,10 @@ class LoadResponse(BaseModel):
     display_name: str = Field(..., description = "Display name of the model")
     is_vision: bool = Field(False, description = "Whether model is a vision model")
     is_lora: bool = Field(False, description = "Whether model is a LoRA adapter")
-    is_gguf: bool = Field(
-        False, description = "Whether model is a GGUF model (llama.cpp)"
-    )
+    is_gguf: bool = Field(False, description = "Whether model is a GGUF model (llama.cpp)")
     is_audio: bool = Field(False, description = "Whether model is a TTS audio model")
-    audio_type: Optional[str] = Field(
-        None, description = "Audio codec type: snac, csm, bicodec, dac"
-    )
-    has_audio_input: bool = Field(
-        False, description = "Whether model accepts audio input (ASR)"
-    )
+    audio_type: Optional[str] = Field(None, description = "Audio codec type: snac, csm, bicodec, dac")
+    has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")
     inference: dict = Field(
         ..., description = "Inference parameters (temperature, top_p, top_k, min_p)"
     )
@@ -282,17 +262,14 @@ class LoadProgressResponse(BaseModel):
     bytes_loaded: int = Field(
         0,
         description = (
-            "Bytes of the model already resident in the llama-server "
-            "process (VmRSS on Linux)."
+            "Bytes of the model already resident in the llama-server process (VmRSS on Linux)."
         ),
     )
     bytes_total: int = Field(
         0,
         description = "Total bytes across all GGUF shards for the active model.",
     )
-    fraction: float = Field(
-        0.0, description = "bytes_loaded / bytes_total, clamped to 0..1."
-    )
+    fraction: float = Field(0.0, description = "bytes_loaded / bytes_total, clamped to 0..1.")
 
 
 class InferenceStatusResponse(BaseModel):
@@ -305,30 +282,14 @@ class InferenceStatusResponse(BaseModel):
         None,
         description = "Loadable identifier for the active model.",
     )
-    is_vision: bool = Field(
-        False, description = "Whether the active model is a vision model"
-    )
-    is_gguf: bool = Field(
-        False, description = "Whether the active model is a GGUF model (llama.cpp)"
-    )
-    gguf_variant: Optional[str] = Field(
-        None, description = "GGUF quantization variant (e.g. Q4_K_M)"
-    )
-    is_audio: bool = Field(
-        False, description = "Whether the active model is a TTS audio model"
-    )
-    audio_type: Optional[str] = Field(
-        None, description = "Audio codec type: snac, csm, bicodec, dac"
-    )
-    has_audio_input: bool = Field(
-        False, description = "Whether model accepts audio input (ASR)"
-    )
-    loading: List[str] = Field(
-        default_factory = list, description = "Models currently being loaded"
-    )
-    loaded: List[str] = Field(
-        default_factory = list, description = "Models currently loaded"
-    )
+    is_vision: bool = Field(False, description = "Whether the active model is a vision model")
+    is_gguf: bool = Field(False, description = "Whether the active model is a GGUF model (llama.cpp)")
+    gguf_variant: Optional[str] = Field(None, description = "GGUF quantization variant (e.g. Q4_K_M)")
+    is_audio: bool = Field(False, description = "Whether the active model is a TTS audio model")
+    audio_type: Optional[str] = Field(None, description = "Audio codec type: snac, csm, bicodec, dac")
+    has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")
+    loading: List[str] = Field(default_factory = list, description = "Models currently being loaded")
+    loaded: List[str] = Field(default_factory = list, description = "Models currently loaded")
     inference: Optional[Dict[str, Any]] = Field(
         None, description = "Recommended inference parameters for the active model"
     )
@@ -353,9 +314,7 @@ class InferenceStatusResponse(BaseModel):
     supports_tools: bool = Field(
         False, description = "Whether the active model supports tool calling"
     )
-    context_length: Optional[int] = Field(
-        None, description = "Context length of the active model"
-    )
+    context_length: Optional[int] = Field(None, description = "Context length of the active model")
     max_context_length: Optional[int] = Field(
         None,
         description = "Maximum context length currently available for the active model",
@@ -563,9 +522,7 @@ class ChatMessage(BaseModel):
     ``ChatCompletionRequest`` layer by walking back to the preceding assistant.
     """
 
-    role: Literal["system", "user", "assistant", "tool"] = Field(
-        ..., description = "Message role"
-    )
+    role: Literal["system", "user", "assistant", "tool"] = Field(..., description = "Message role")
     content: Optional[Union[str, list[ContentPart]]] = Field(
         None, description = "Message content (string or multimodal parts)"
     )
@@ -666,9 +623,7 @@ class ChatCompletionRequest(BaseModel):
 
     # ── Unsloth extensions (ignored by standard OpenAI clients) ──
     top_k: int = Field(20, ge = -1, le = 100, description = "[x-unsloth] Top-k sampling")
-    min_p: float = Field(
-        0.01, ge = 0.0, le = 1.0, description = "[x-unsloth] Min-p sampling threshold"
-    )
+    min_p: float = Field(0.01, ge = 0.0, le = 1.0, description = "[x-unsloth] Min-p sampling threshold")
     repetition_penalty: float = Field(
         1.0, ge = 1.0, le = 2.0, description = "[x-unsloth] Repetition penalty"
     )
@@ -925,9 +880,7 @@ class ChatCompletionRequest(BaseModel):
                     if not tc_id:
                         continue
                     function = tc.get("function")
-                    function_name = (
-                        function.get("name") if isinstance(function, dict) else None
-                    )
+                    function_name = function.get("name") if isinstance(function, dict) else None
                     if msg.name and function_name == msg.name:
                         name_match = (tc_id, asst_idx, tc_idx)
                         break
@@ -940,7 +893,6 @@ class ChatCompletionRequest(BaseModel):
                     break
             if picked is None:
                 import secrets as _secrets
-
                 picked = f"call_{_secrets.token_hex(8)}"
             msg.tool_call_id = picked
         return self
@@ -1160,17 +1112,13 @@ class ResponsesFunctionCallInputItem(BaseModel):
     """
 
     type: Literal["function_call"]
-    id: Optional[str] = Field(
-        None, description = "Item id assigned by the server (e.g. fc_...)"
-    )
+    id: Optional[str] = Field(None, description = "Item id assigned by the server (e.g. fc_...)")
     call_id: str = Field(
         ...,
         description = "Correlation id matching a function_call_output on the next turn.",
     )
     name: str
-    arguments: str = Field(
-        ..., description = "JSON string of the arguments the model produced."
-    )
+    arguments: str = Field(..., description = "JSON string of the arguments the model produced.")
     status: Optional[Literal["in_progress", "completed", "incomplete"]] = None
 
 
@@ -1266,9 +1214,7 @@ class ResponsesRequest(BaseModel):
         default = [],
         description = "Input text or list of messages / function_call / function_call_output items",
     )
-    instructions: Optional[str] = Field(
-        None, description = "System / developer instructions"
-    )
+    instructions: Optional[str] = Field(None, description = "System / developer instructions")
     temperature: Optional[float] = Field(None, ge = 0.0, le = 2.0)
     top_p: Optional[float] = Field(None, ge = 0.0, le = 1.0)
     max_output_tokens: Optional[int] = Field(None, ge = 1)
@@ -1344,9 +1290,7 @@ class ResponsesOutputFunctionCall(BaseModel):
     id: str = Field(default_factory = lambda: f"fc_{uuid.uuid4().hex[:12]}")
     call_id: str
     name: str
-    arguments: str = Field(
-        ..., description = "JSON string of the arguments the model produced."
-    )
+    arguments: str = Field(..., description = "JSON string of the arguments the model produced.")
     status: Literal["completed", "in_progress", "incomplete"] = "completed"
 
 
@@ -1455,16 +1399,12 @@ def _merge_anthropic_system(system: Any, additions: list[str]) -> Any:
     if not additions:
         return system
 
-    addition_blocks = [
-        {"type": "text", "text": text} for text in additions if text.strip()
-    ]
+    addition_blocks = [{"type": "text", "text": text} for text in additions if text.strip()]
     if not addition_blocks:
         return system
 
     if system is None:
-        return (
-            addition_blocks[0]["text"] if len(addition_blocks) == 1 else addition_blocks
-        )
+        return addition_blocks[0]["text"] if len(addition_blocks) == 1 else addition_blocks
     if isinstance(system, str):
         return "\n\n".join([system, *[block["text"] for block in addition_blocks]])
     if isinstance(system, list):
@@ -1543,9 +1483,7 @@ class AnthropicMessagesRequest(BaseModel):
 
         normalized = dict(data)
         normalized["messages"] = normalized_messages
-        normalized["system"] = _merge_anthropic_system(
-            normalized.get("system"), system_additions
-        )
+        normalized["system"] = _merge_anthropic_system(normalized.get("system"), system_additions)
         return normalized
 
 
@@ -1569,9 +1507,7 @@ class AnthropicResponseToolUseBlock(BaseModel):
     input: dict
 
 
-AnthropicResponseBlock = Union[
-    AnthropicResponseTextBlock, AnthropicResponseToolUseBlock
-]
+AnthropicResponseBlock = Union[AnthropicResponseTextBlock, AnthropicResponseToolUseBlock]
 
 
 class AnthropicMessagesResponse(BaseModel):
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index a53569aaa1..3dd8e779f7 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -14,9 +14,7 @@ ModelType = Literal["text", "vision", "audio", "embeddings"]
 class CheckpointInfo(BaseModel):
     """Information about a discovered checkpoint directory."""
 
-    display_name: str = Field(
-        ..., description = "User-friendly checkpoint name (folder name)"
-    )
+    display_name: str = Field(..., description = "User-friendly checkpoint name (folder name)")
     path: str = Field(..., description = "Full path to the checkpoint directory")
     loss: Optional[float] = Field(None, description = "Training loss at this checkpoint")
 
@@ -65,33 +63,23 @@ class ModelDetails(BaseModel):
         None, description = "Model identifier (alias for id, for backward compatibility)"
     )
     name: Optional[str] = Field(None, description = "Display name for the model")
-    config: Optional[Dict[str, Any]] = Field(
-        None, description = "Model configuration dictionary"
-    )
+    config: Optional[Dict[str, Any]] = Field(None, description = "Model configuration dictionary")
     is_vision: bool = Field(False, description = "Whether model is a vision model")
     is_embedding: bool = Field(
         False, description = "Whether model is an embedding/sentence-transformer model"
     )
     is_lora: bool = Field(False, description = "Whether model is a LoRA adapter")
-    is_gguf: bool = Field(
-        False, description = "Whether model is a GGUF model (llama.cpp format)"
-    )
+    is_gguf: bool = Field(False, description = "Whether model is a GGUF model (llama.cpp format)")
     is_mlx: bool = Field(
         False, description = "Whether model is served via the MLX backend (Apple Silicon)"
     )
     is_audio: bool = Field(False, description = "Whether model is a TTS audio model")
-    audio_type: Optional[str] = Field(
-        None, description = "Audio codec type: snac, csm, bicodec, dac"
-    )
-    has_audio_input: bool = Field(
-        False, description = "Whether model accepts audio input (ASR)"
-    )
+    audio_type: Optional[str] = Field(None, description = "Audio codec type: snac, csm, bicodec, dac")
+    has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")
     model_type: Optional[ModelType] = Field(
         None, description = "Collapsed model modality: text, vision, audio, or embeddings"
     )
-    base_model: Optional[str] = Field(
-        None, description = "Base model if this is a LoRA adapter"
-    )
+    base_model: Optional[str] = Field(None, description = "Base model if this is a LoRA adapter")
     max_position_embeddings: Optional[int] = Field(
         None, description = "Maximum context length supported by the model"
     )
@@ -104,9 +92,7 @@ class LoRAInfo(BaseModel):
     """LoRA adapter or exported model information"""
 
     display_name: str = Field(..., description = "Display name for the LoRA")
-    adapter_path: str = Field(
-        ..., description = "Path to the LoRA adapter or exported model"
-    )
+    adapter_path: str = Field(..., description = "Path to the LoRA adapter or exported model")
     base_model: Optional[str] = Field(None, description = "Base model identifier")
     source: Optional[str] = Field(None, description = "'training' or 'exported'")
     export_type: Optional[str] = Field(
@@ -117,29 +103,21 @@ class LoRAInfo(BaseModel):
 class LoRAScanResponse(BaseModel):
     """Response schema for scanning trained LoRA adapters"""
 
-    loras: List[LoRAInfo] = Field(
-        default_factory = list, description = "List of found LoRA adapters"
-    )
+    loras: List[LoRAInfo] = Field(default_factory = list, description = "List of found LoRA adapters")
     outputs_dir: str = Field(..., description = "Directory that was scanned")
 
 
 class ModelListResponse(BaseModel):
     """Response schema for listing models"""
 
-    models: List[ModelDetails] = Field(
-        default_factory = list, description = "List of models"
-    )
-    default_models: List[str] = Field(
-        default_factory = list, description = "List of default model IDs"
-    )
+    models: List[ModelDetails] = Field(default_factory = list, description = "List of models")
+    default_models: List[str] = Field(default_factory = list, description = "List of default model IDs")
 
 
 class GgufVariantDetail(BaseModel):
     """A single GGUF quantization variant in a HuggingFace repo."""
 
-    filename: str = Field(
-        ..., description = "GGUF filename (e.g., 'gemma-3-4b-it-Q4_K_M.gguf')"
-    )
+    filename: str = Field(..., description = "GGUF filename (e.g., 'gemma-3-4b-it-Q4_K_M.gguf')")
     quant: str = Field(..., description = "Quantization label (e.g., 'Q4_K_M')")
     size_bytes: int = Field(0, description = "File size in bytes")
     downloaded: bool = Field(
@@ -185,9 +163,7 @@ class LocalModelInfo(BaseModel):
 class LocalModelListResponse(BaseModel):
     """Response schema for listing local/cached models."""
 
-    models_dir: str = Field(
-        ..., description = "Directory scanned for custom local models"
-    )
+    models_dir: str = Field(..., description = "Directory scanned for custom local models")
     hf_cache_dir: Optional[str] = Field(
         None,
         description = "HF cache root that was scanned",
@@ -205,9 +181,7 @@ class LocalModelListResponse(BaseModel):
 class AddScanFolderRequest(BaseModel):
     """Request body for adding a custom scan folder."""
 
-    path: str = Field(
-        ..., description = "Absolute or relative directory path to scan for models"
-    )
+    path: str = Field(..., description = "Absolute or relative directory path to scan for models")
 
 
 class ScanFolderInfo(BaseModel):
diff --git a/studio/backend/models/providers.py b/studio/backend/models/providers.py
index 53ce981392..e9d2d859f5 100644
--- a/studio/backend/models/providers.py
+++ b/studio/backend/models/providers.py
@@ -16,9 +16,7 @@ from pydantic import BaseModel, Field
 class ProviderRegistryEntry(BaseModel):
     """A supported provider type with its default configuration."""
 
-    provider_type: str = Field(
-        ..., description = "Provider identifier (e.g. 'openai', 'mistral')"
-    )
+    provider_type: str = Field(..., description = "Provider identifier (e.g. 'openai', 'mistral')")
     display_name: str = Field(..., description = "Human-readable provider name")
     base_url: str = Field(..., description = "Default API base URL")
     default_models: list[str] = Field(
@@ -46,9 +44,7 @@ class ProviderCreate(BaseModel):
     """Request to create a saved provider configuration."""
 
     provider_type: str = Field(..., description = "Provider type from the registry")
-    display_name: str = Field(
-        ..., description = "User-chosen label (e.g. 'My OpenAI Key')"
-    )
+    display_name: str = Field(..., description = "User-chosen label (e.g. 'My OpenAI Key')")
     base_url: Optional[str] = Field(
         None,
         description = "Custom base URL (overrides registry default). Omit to use the default.",
@@ -60,9 +56,7 @@ class ProviderUpdate(BaseModel):
 
     display_name: Optional[str] = Field(None, description = "New display name")
     base_url: Optional[str] = Field(None, description = "New base URL")
-    is_enabled: Optional[bool] = Field(
-        None, description = "Enable or disable this provider"
-    )
+    is_enabled: Optional[bool] = Field(None, description = "Enable or disable this provider")
 
 
 class ProviderResponse(BaseModel):
@@ -85,9 +79,7 @@ class ProviderModelInfo(BaseModel):
 
     id: str = Field(..., description = "Model ID as expected by the provider API")
     display_name: str = Field("", description = "Human-readable model name")
-    context_length: Optional[int] = Field(
-        None, description = "Maximum context length in tokens"
-    )
+    context_length: Optional[int] = Field(None, description = "Maximum context length in tokens")
     owned_by: Optional[str] = Field(None, description = "Model owner/organization")
 
 
diff --git a/studio/backend/models/responses.py b/studio/backend/models/responses.py
index 3081f67422..f6357bf999 100644
--- a/studio/backend/models/responses.py
+++ b/studio/backend/models/responses.py
@@ -23,16 +23,10 @@ class TrainingStopResponse(BaseModel):
 class TrainingMetricsResponse(BaseModel):
     """Response for training metrics history"""
 
-    loss_history: List[float] = Field(
-        default_factory = list, description = "Loss values per step"
-    )
-    lr_history: List[float] = Field(
-        default_factory = list, description = "Learning rate per step"
-    )
+    loss_history: List[float] = Field(default_factory = list, description = "Loss values per step")
+    lr_history: List[float] = Field(default_factory = list, description = "Learning rate per step")
     step_history: List[int] = Field(default_factory = list, description = "Step numbers")
-    grad_norm_history: List[float] = Field(
-        default_factory = list, description = "Gradient norm values"
-    )
+    grad_norm_history: List[float] = Field(default_factory = list, description = "Gradient norm values")
     grad_norm_step_history: List[int] = Field(
         default_factory = list, description = "Step numbers for gradient norm values"
     )
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index c6be1eff4e..cef0b8f36f 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -41,9 +41,7 @@ def _parse_lr(v: Any) -> float:
     except (TypeError, ValueError):
         raise ValueError(f"learning_rate must be parseable as float (got {v!r})")
     if not (lr > 0.0):
-        raise ValueError(
-            f"learning_rate must be > 0 (got {lr!r}); " "typical range is 1e-6 .. 1e-3"
-        )
+        raise ValueError(f"learning_rate must be > 0 (got {lr!r}); typical range is 1e-6 .. 1e-3")
     if lr >= _MAX_LR_VALUE:
         raise ValueError(
             f"learning_rate must be < 1.0 (got {lr!r}); "
@@ -59,11 +57,9 @@ class TrainingStartRequest(BaseModel):
     model_name: str = Field(
         ..., description = "Model identifier (e.g., 'unsloth/llama-3-8b-bnb-4bit')"
     )
-    training_type: Literal["LoRA/QLoRA", "Full Finetuning", "Continued Pretraining"] = (
-        Field(
-            ...,
-            description = "Training type: 'LoRA/QLoRA', 'Full Finetuning', or 'Continued Pretraining'",
-        )
+    training_type: Literal["LoRA/QLoRA", "Full Finetuning", "Continued Pretraining"] = Field(
+        ...,
+        description = "Training type: 'LoRA/QLoRA', 'Full Finetuning', or 'Continued Pretraining'",
     )
     hf_token: Optional[str] = Field(None, description = "HuggingFace token")
     load_in_4bit: bool = Field(True, description = "Load model in 4-bit quantization")
@@ -78,9 +74,7 @@ class TrainingStartRequest(BaseModel):
     )
 
     # Dataset parameters
-    hf_dataset: Optional[str] = Field(
-        None, description = "HuggingFace dataset identifier"
-    )
+    hf_dataset: Optional[str] = Field(None, description = "HuggingFace dataset identifier")
     local_datasets: List[str] = Field(
         default_factory = list, description = "List of local dataset paths"
     )
@@ -90,12 +84,8 @@ class TrainingStartRequest(BaseModel):
     format_type: str = Field(..., description = "Dataset format type")
     subset: Optional[str] = None
     train_split: Optional[str] = Field("train", description = "Training split name")
-    eval_split: Optional[str] = Field(
-        None, description = "Eval split name. None = auto-detect"
-    )
-    eval_steps: float = Field(
-        0.00, description = "Fraction of total steps between evals (0-1)"
-    )
+    eval_split: Optional[str] = Field(None, description = "Eval split name. None = auto-detect")
+    eval_steps: float = Field(0.00, description = "Fraction of total steps between evals (0-1)")
     dataset_slice_start: Optional[int] = Field(
         None, description = "Inclusive start row index for dataset slicing"
     )
@@ -124,9 +114,7 @@ class TrainingStartRequest(BaseModel):
         if v is None:
             raise ValueError("batch_size is required")
         if v < 1 or v > _MAX_BATCH_SIZE:
-            raise ValueError(
-                f"batch_size must be in [1, {_MAX_BATCH_SIZE}] (got {v!r})"
-            )
+            raise ValueError(f"batch_size must be in [1, {_MAX_BATCH_SIZE}] (got {v!r})")
         return v
 
     @field_validator("gradient_accumulation_steps")
@@ -136,8 +124,7 @@ class TrainingStartRequest(BaseModel):
             return 1
         if v < 1 or v > _MAX_GRAD_ACCUM:
             raise ValueError(
-                f"gradient_accumulation_steps must be in [1, {_MAX_GRAD_ACCUM}] "
-                f"(got {v!r})"
+                f"gradient_accumulation_steps must be in [1, {_MAX_GRAD_ACCUM}] " f"(got {v!r})"
             )
         return v
 
@@ -159,18 +146,14 @@ class TrainingStartRequest(BaseModel):
         if v is None:
             return v
         if not isinstance(v, int) or v < 0 or v > _MAX_STEPS:
-            raise ValueError(
-                f"max_steps must be a non-negative int <= {_MAX_STEPS} (got {v!r})"
-            )
+            raise ValueError(f"max_steps must be a non-negative int <= {_MAX_STEPS} (got {v!r})")
         return v
 
     @field_validator("max_seq_length")
     @classmethod
     def _check_max_seq_length(cls, v: int) -> int:
         if v is None or v < 1 or v > _MAX_SEQ_LENGTH:
-            raise ValueError(
-                f"max_seq_length must be in [1, {_MAX_SEQ_LENGTH}] (got {v!r})"
-            )
+            raise ValueError(f"max_seq_length must be in [1, {_MAX_SEQ_LENGTH}] (got {v!r})")
         return v
 
     @field_validator("vision_image_size", mode = "before")
@@ -191,7 +174,6 @@ class TrainingStartRequest(BaseModel):
             # numpy ints / Integral subclasses, without a hard numpy import.
             try:
                 import numbers
-
                 if isinstance(v, numbers.Integral):
                     coerced = int(v)
                 elif isinstance(v, numbers.Real) and float(v).is_integer():
@@ -214,8 +196,7 @@ class TrainingStartRequest(BaseModel):
             return v
         if not isinstance(v, int) or v < 0 or v > _MAX_STEPS:
             raise ValueError(
-                f"warmup_steps must be a non-negative int <= {_MAX_STEPS} "
-                f"(got {v!r})"
+                f"warmup_steps must be a non-negative int <= {_MAX_STEPS} " f"(got {v!r})"
             )
         return v
 
@@ -251,9 +232,7 @@ class TrainingStartRequest(BaseModel):
         except (TypeError, ValueError):
             raise ValueError(f"weight_decay must be a number (got {v!r})")
         if wd < 0 or wd > 10.0:
-            raise ValueError(
-                f"weight_decay must be in [0, 10] (got {wd!r}); typical 0..0.1"
-            )
+            raise ValueError(f"weight_decay must be in [0, 10] (got {wd!r}); typical 0..0.1")
         return wd
 
     @field_validator("lora_r")
@@ -271,9 +250,7 @@ class TrainingStartRequest(BaseModel):
         if v is None:
             return 16
         if v < 1 or v > _MAX_LORA_ALPHA:
-            raise ValueError(
-                f"lora_alpha must be in [1, {_MAX_LORA_ALPHA}] (got {v!r})"
-            )
+            raise ValueError(f"lora_alpha must be in [1, {_MAX_LORA_ALPHA}] (got {v!r})")
         return v
 
     @field_validator("lora_dropout")
@@ -302,9 +279,7 @@ class TrainingStartRequest(BaseModel):
     num_epochs: int = Field(1, description = "Number of training epochs")
     learning_rate: str = Field("2e-4", description = "Learning rate")
     batch_size: int = Field(1, description = "Batch size")
-    gradient_accumulation_steps: int = Field(
-        1, description = "Gradient accumulation steps"
-    )
+    gradient_accumulation_steps: int = Field(1, description = "Gradient accumulation steps")
     warmup_steps: Optional[int] = Field(None, description = "Warmup steps")
     warmup_ratio: Optional[float] = Field(None, description = "Warmup ratio")
     max_steps: Optional[int] = Field(None, description = "Maximum training steps")
@@ -332,31 +307,19 @@ class TrainingStartRequest(BaseModel):
     lora_r: int = Field(16, description = "LoRA rank")
     lora_alpha: int = Field(16, description = "LoRA alpha")
     lora_dropout: float = Field(0.0, description = "LoRA dropout")
-    target_modules: List[str] = Field(
-        default_factory = list, description = "Target modules for LoRA"
-    )
-    gradient_checkpointing: str = Field(
-        "", description = "Gradient checkpointing setting"
-    )
+    target_modules: List[str] = Field(default_factory = list, description = "Target modules for LoRA")
+    gradient_checkpointing: str = Field("", description = "Gradient checkpointing setting")
     use_rslora: bool = Field(False, description = "Use RSLoRA")
     use_loftq: bool = Field(False, description = "Use LoftQ")
     train_on_completions: bool = Field(False, description = "Train on completions only")
 
     # Vision-specific LoRA parameters
     finetune_vision_layers: bool = Field(False, description = "Finetune vision layers")
-    finetune_language_layers: bool = Field(
-        False, description = "Finetune language layers"
-    )
-    finetune_attention_modules: bool = Field(
-        False, description = "Finetune attention modules"
-    )
+    finetune_language_layers: bool = Field(False, description = "Finetune language layers")
+    finetune_attention_modules: bool = Field(False, description = "Finetune attention modules")
     finetune_mlp_modules: bool = Field(False, description = "Finetune MLP modules")
-    is_dataset_image: bool = Field(
-        False, description = "Whether the dataset contains image data"
-    )
-    is_dataset_audio: bool = Field(
-        False, description = "Whether the dataset contains audio data"
-    )
+    is_dataset_image: bool = Field(False, description = "Whether the dataset contains image data")
+    is_dataset_audio: bool = Field(False, description = "Whether the dataset contains audio data")
     is_embedding: bool = Field(
         False, description = "Whether model is an embedding/sentence-transformer model"
     )
@@ -382,9 +345,7 @@ class TrainingStartRequest(BaseModel):
         # num_epochs and max_steps each accept 0 as a "use the other one"
         # sentinel. If both resolve to 0 there's nothing to train against.
         if (self.max_steps is None or self.max_steps == 0) and self.num_epochs == 0:
-            raise ValueError(
-                "Either num_epochs or max_steps must be > 0; both cannot be 0."
-            )
+            raise ValueError("Either num_epochs or max_steps must be > 0; both cannot be 0.")
         return self
 
 
@@ -411,9 +372,7 @@ class TrainingStatus(BaseModel):
         "error",
         "stopped",
     ] = Field(..., description = "Current phase of training pipeline")
-    is_training_running: bool = Field(
-        ..., description = "True if training loop is actively running"
-    )
+    is_training_running: bool = Field(..., description = "True if training loop is actively running")
     eval_enabled: bool = Field(
         False,
         description = "True if evaluation dataset is configured for this training run",
@@ -438,9 +397,7 @@ class TrainingProgress(BaseModel):
     total_steps: int = Field(..., description = "Total training steps")
     loss: Optional[float] = Field(None, description = "Current loss value")
     learning_rate: Optional[float] = Field(None, description = "Current learning rate")
-    progress_percent: float = Field(
-        ..., description = "Progress percentage (0.0 to 100.0)"
-    )
+    progress_percent: float = Field(..., description = "Progress percentage (0.0 to 100.0)")
     epoch: Optional[float] = Field(None, description = "Current epoch")
     elapsed_seconds: Optional[float] = Field(
         None, description = "Time elapsed since training started"
@@ -449,9 +406,7 @@ class TrainingProgress(BaseModel):
     grad_norm: Optional[float] = Field(
         None, description = "L2 norm of gradients, computed before gradient clipping"
     )
-    num_tokens: Optional[int] = Field(
-        None, description = "Total number of tokens processed so far"
-    )
+    num_tokens: Optional[int] = Field(None, description = "Total number of tokens processed so far")
     eval_loss: Optional[float] = Field(
         None, description = "Eval loss from the most recent evaluation step"
     )
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
index 6acb985b5b..d468db70d2 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
@@ -91,18 +91,13 @@ def _read_jsonl(path: Path, max_rows: int | None = None):
 
 
 def _flatten_issue_row(r: dict, repo: str, include_comments: bool, max_c: int) -> dict:
-    labels = [
-        l.get("name")
-        for l in (r.get("labels", {}) or {}).get("nodes", [])
-        if l.get("name")
-    ]
+    labels = [l.get("name") for l in (r.get("labels", {}) or {}).get("nodes", []) if l.get("name")]
     comments_nodes = (r.get("comments") or {}).get("nodes") or []
     comments_text = ""
     if include_comments and comments_nodes:
         kept = comments_nodes[:max_c]
         comments_text = "\n\n".join(
-            f"[{(c.get('author') or {}).get('login', '?')}]: {c.get('body') or ''}"
-            for c in kept
+            f"[{(c.get('author') or {}).get('login', '?')}]: {c.get('body') or ''}" for c in kept
         )
     return {
         "item_type": "issue",
@@ -121,18 +116,13 @@ def _flatten_issue_row(r: dict, repo: str, include_comments: bool, max_c: int) -
 
 
 def _flatten_pr_row(r: dict, repo: str, include_comments: bool, max_c: int) -> dict:
-    labels = [
-        l.get("name")
-        for l in (r.get("labels", {}) or {}).get("nodes", [])
-        if l.get("name")
-    ]
+    labels = [l.get("name") for l in (r.get("labels", {}) or {}).get("nodes", []) if l.get("name")]
     comments_nodes = (r.get("comments") or {}).get("nodes") or []
     comments_text = ""
     if include_comments and comments_nodes:
         kept = comments_nodes[:max_c]
         comments_text = "\n\n".join(
-            f"[{(c.get('author') or {}).get('login', '?')}]: {c.get('body') or ''}"
-            for c in kept
+            f"[{(c.get('author') or {}).get('login', '?')}]: {c.get('body') or ''}" for c in kept
         )
     return {
         "item_type": "pull",
@@ -205,14 +195,8 @@ def scrape(cfg: ScrapeConfig, base_dir: Path):
                 scraper.scrape_prs()
             if "commits" in cfg.item_types:
                 default_ref = repo_meta.get("defaultBranchRef") or {}
-                default_branch = (
-                    default_ref.get("name") if isinstance(default_ref, dict) else None
-                )
-                branch = (
-                    f"refs/heads/{default_branch}"
-                    if default_branch
-                    else "refs/heads/main"
-                )
+                default_branch = default_ref.get("name") if isinstance(default_ref, dict) else None
+                branch = f"refs/heads/{default_branch}" if default_branch else "refs/heads/main"
                 scraper.scrape_commits(branch = branch)
         finally:
             scraper.close()
@@ -222,16 +206,12 @@ def scrape(cfg: ScrapeConfig, base_dir: Path):
         if "issues" in cfg.item_types:
             for row in _read_jsonl(repo_dir / "issues.jsonl", read_cap):
                 all_rows.append(
-                    _flatten_issue_row(
-                        row, repo, cfg.include_comments, cfg.max_comments_per_item
-                    )
+                    _flatten_issue_row(row, repo, cfg.include_comments, cfg.max_comments_per_item)
                 )
         if "pulls" in cfg.item_types:
             for row in _read_jsonl(repo_dir / "pull_requests.jsonl", read_cap):
                 all_rows.append(
-                    _flatten_pr_row(
-                        row, repo, cfg.include_comments, cfg.max_comments_per_item
-                    )
+                    _flatten_pr_row(row, repo, cfg.include_comments, cfg.max_comments_per_item)
                 )
         if "commits" in cfg.item_types:
             for row in _read_jsonl(repo_dir / "commits.jsonl", read_cap):
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
index 696d0ccb98..eda242a6ea 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
@@ -60,9 +60,7 @@ class GitHubClient:
         token_source: str | None = None,
     ):
         if token:
-            self._token_source = (
-                token_source or "explicit token argument (recipe-level field)"
-            )
+            self._token_source = token_source or "explicit token argument (recipe-level field)"
         elif os.environ.get("GH_TOKEN"):
             self._token_source = "GH_TOKEN environment variable"
             token = os.environ["GH_TOKEN"]
@@ -72,9 +70,7 @@ class GitHubClient:
         else:
             raise RuntimeError("GH_TOKEN or GITHUB_TOKEN not set in environment")
         self.session = requests.Session()
-        self.session.headers.update(
-            {**BASE_HEADERS, "Authorization": f"Bearer {token}"}
-        )
+        self.session.headers.update({**BASE_HEADERS, "Authorization": f"Bearer {token}"})
         self.min_remaining_graphql = min_remaining_graphql
         self.min_remaining_rest = min_remaining_rest
         self.graphql_remaining: Optional[int] = None
@@ -85,7 +81,11 @@ class GitHubClient:
         self.calls_rest = 0
         self.retry_count = 0
 
-    def _sleep_until(self, reset_ts: int, buffer_s: int = 10) -> None:
+    def _sleep_until(
+        self,
+        reset_ts: int,
+        buffer_s: int = 10,
+    ) -> None:
         now = int(time.time())
         wait = max(0, reset_ts - now) + buffer_s
         log.warning("Rate limit hit. Sleeping %ds until reset.", wait)
@@ -209,9 +209,7 @@ class GitHubClient:
                     # Retry on RATE_LIMITED
                     for e in errs:
                         if e.get("type") == "RATE_LIMITED":
-                            self._sleep_until(
-                                (self.graphql_reset or int(time.time()) + 60)
-                            )
+                            self._sleep_until((self.graphql_reset or int(time.time()) + 60))
                             break
                     else:
                         # No rate-limit error, log and return partial
@@ -243,9 +241,7 @@ class GitHubClient:
         last_err = None
         for attempt in range(max_retries):
             try:
-                r = self.session.request(
-                    method, url, params = params, json = json_body, timeout = 120
-                )
+                r = self.session.request(method, url, params = params, json = json_body, timeout = 120)
                 self.calls_rest += 1
                 rem = r.headers.get("X-RateLimit-Remaining")
                 rst = r.headers.get("X-RateLimit-Reset")
@@ -269,9 +265,7 @@ class GitHubClient:
                 if r.status_code in (403, 429):
                     retry_after = _retry_after_seconds(r.headers.get("Retry-After"))
                     if retry_after is not None:
-                        log.warning(
-                            "Secondary rate limit on REST. Sleep %ds.", retry_after
-                        )
+                        log.warning("Secondary rate limit on REST. Sleep %ds.", retry_after)
                         time.sleep(retry_after + 2)
                         continue
                     # Check if primary rate
@@ -290,7 +284,10 @@ class GitHubClient:
         raise RuntimeError(f"REST failed after {max_retries} retries: {last_err}")
 
     def rest_paginate(
-        self, path: str, params: Optional[Dict[str, Any]] = None, per_page: int = 100
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        per_page: int = 100,
     ) -> Iterator[dict]:
         params = dict(params or {})
         params.setdefault("per_page", per_page)
@@ -298,9 +295,7 @@ class GitHubClient:
         while True:
             r = self.rest("GET", url, params = params if url == path else None)
             if r.status_code != 200:
-                log.error(
-                    "REST paginate got %s at %s: %s", r.status_code, url, r.text[:200]
-                )
+                log.error("REST paginate got %s at %s: %s", r.status_code, url, r.text[:200])
                 return
             items = r.json()
             if isinstance(items, dict):
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
index 127129e18b..826ffc1256 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
@@ -86,11 +86,7 @@ class RepoScraper:
         return counter >= lim
 
     def _log_rate(self, where: str, data: Dict[str, Any]) -> None:
-        rl = (
-            data.get("data", {}).get("rateLimit")
-            if isinstance(data.get("data"), dict)
-            else None
-        )
+        rl = data.get("data", {}).get("rateLimit") if isinstance(data.get("data"), dict) else None
         if rl:
             log.debug(
                 "[%s] rate cost=%s remaining=%s resetAt=%s",
@@ -102,9 +98,7 @@ class RepoScraper:
 
     # ----- repo meta -----
     def scrape_repo_meta(self) -> Dict[str, Any]:
-        data = self.client.graphql(
-            Q.REPO_META_QUERY, {"owner": self.owner, "name": self.name}
-        )
+        data = self.client.graphql(Q.REPO_META_QUERY, {"owner": self.owner, "name": self.name})
         self._log_rate("repo_meta", data)
         repo = data.get("data", {}).get("repository") or {}
         repo["_fetchedAt"] = ts()
@@ -150,11 +144,7 @@ class RepoScraper:
                         self._paginate_issue_comments(
                             it["number"], it["comments"]["pageInfo"]["endCursor"]
                         )
-                    if (
-                        it.get("timelineItems", {})
-                        .get("pageInfo", {})
-                        .get("hasNextPage")
-                    ):
+                    if it.get("timelineItems", {}).get("pageInfo", {}).get("hasNextPage"):
                         self._paginate_issue_timeline(
                             it["number"],
                             it["timelineItems"]["pageInfo"]["endCursor"],
@@ -261,30 +251,16 @@ class RepoScraper:
                 num = pr["number"]
                 if not self.light:
                     if pr.get("comments", {}).get("pageInfo", {}).get("hasNextPage"):
-                        self._paginate_pr_comments(
-                            num, pr["comments"]["pageInfo"]["endCursor"]
-                        )
-                    if (
-                        pr.get("timelineItems", {})
-                        .get("pageInfo", {})
-                        .get("hasNextPage")
-                    ):
+                        self._paginate_pr_comments(num, pr["comments"]["pageInfo"]["endCursor"])
+                    if pr.get("timelineItems", {}).get("pageInfo", {}).get("hasNextPage"):
                         self._paginate_pr_timeline(
                             num, pr["timelineItems"]["pageInfo"]["endCursor"]
                         )
                     if pr.get("commits", {}).get("pageInfo", {}).get("hasNextPage"):
-                        self._paginate_pr_commits(
-                            num, pr["commits"]["pageInfo"]["endCursor"]
-                        )
+                        self._paginate_pr_commits(num, pr["commits"]["pageInfo"]["endCursor"])
                     if pr.get("files", {}).get("pageInfo", {}).get("hasNextPage"):
-                        self._paginate_pr_files(
-                            num, pr["files"]["pageInfo"]["endCursor"]
-                        )
-                    if (
-                        pr.get("reviewThreads", {})
-                        .get("pageInfo", {})
-                        .get("hasNextPage")
-                    ):
+                        self._paginate_pr_files(num, pr["files"]["pageInfo"]["endCursor"])
+                    if pr.get("reviewThreads", {}).get("pageInfo", {}).get("hasNextPage"):
                         self._paginate_pr_review_threads(
                             num, pr["reviewThreads"]["pageInfo"]["endCursor"]
                         )
@@ -342,9 +318,7 @@ class RepoScraper:
                 "after": cur,
             }
             data = self.client.graphql(Q.PR_TIMELINE_QUERY, vars_)
-            item = ((data.get("data") or {}).get("repository") or {}).get(
-                "pullRequest"
-            ) or {}
+            item = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
             tl = item.get("timelineItems") or {}
             for ev in tl.get("nodes") or []:
                 ev["_owner"] = self.owner
@@ -367,9 +341,7 @@ class RepoScraper:
                 "after": cur,
             }
             data = self.client.graphql(Q.PR_COMMITS_QUERY, vars_)
-            item = ((data.get("data") or {}).get("repository") or {}).get(
-                "pullRequest"
-            ) or {}
+            item = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
             cc = item.get("commits") or {}
             for c in cc.get("nodes") or []:
                 c["_owner"] = self.owner
@@ -392,9 +364,7 @@ class RepoScraper:
                 "after": cur,
             }
             data = self.client.graphql(Q.PR_FILES_QUERY, vars_)
-            item = ((data.get("data") or {}).get("repository") or {}).get(
-                "pullRequest"
-            ) or {}
+            item = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
             ff = item.get("files") or {}
             for f in ff.get("nodes") or []:
                 f["_owner"] = self.owner
@@ -419,9 +389,7 @@ class RepoScraper:
                 "after": cur,
             }
             data = self.client.graphql(Q.PR_REVIEW_THREADS_QUERY, vars_)
-            item = ((data.get("data") or {}).get("repository") or {}).get(
-                "pullRequest"
-            ) or {}
+            item = ((data.get("data") or {}).get("repository") or {}).get("pullRequest") or {}
             rt = item.get("reviewThreads") or {}
             for th in rt.get("nodes") or []:
                 th["_owner"] = self.owner
@@ -461,9 +429,7 @@ class RepoScraper:
                 d["_fetchedAt"] = ts()
                 num = d["number"]
                 if d.get("comments", {}).get("pageInfo", {}).get("hasNextPage"):
-                    self._paginate_discussion_comments(
-                        num, d["comments"]["pageInfo"]["endCursor"]
-                    )
+                    self._paginate_discussion_comments(num, d["comments"]["pageInfo"]["endCursor"])
                 # paginate replies per comment if needed
                 for c in d.get("comments", {}).get("nodes", []) or []:
                     if c.get("replies", {}).get("pageInfo", {}).get("hasNextPage"):
@@ -501,9 +467,7 @@ class RepoScraper:
                 "after": cur,
             }
             data = self.client.graphql(Q.DISCUSSION_COMMENTS_QUERY, vars_)
-            disc = ((data.get("data") or {}).get("repository") or {}).get(
-                "discussion"
-            ) or {}
+            disc = ((data.get("data") or {}).get("repository") or {}).get("discussion") or {}
             cc = disc.get("comments") or {}
             for c in cc.get("nodes") or []:
                 c["_owner"] = self.owner
@@ -513,9 +477,7 @@ class RepoScraper:
             info = cc.get("pageInfo") or {}
             cur = info.get("endCursor") if info.get("hasNextPage") else None
 
-    def _paginate_discussion_replies(
-        self, comment_id: str, after: str, disc_number: int
-    ) -> None:
+    def _paginate_discussion_replies(self, comment_id: str, after: str, disc_number: int) -> None:
         cur = after
         while cur:
             vars_ = {
@@ -650,12 +612,8 @@ def setup_logging(log_file: Path) -> None:
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument(
-        "--base-dir", default = "/mnt/disks/unslothai/ubuntu/workspace_34/github_scraper"
-    )
-    ap.add_argument(
-        "--repos", nargs = "+", default = ["unslothai/unsloth", "unslothai/unsloth-zoo"]
-    )
+    ap.add_argument("--base-dir", default = "/mnt/disks/unslothai/ubuntu/workspace_34/github_scraper")
+    ap.add_argument("--repos", nargs = "+", default = ["unslothai/unsloth", "unslothai/unsloth-zoo"])
     ap.add_argument("--trial", action = "store_true", help = "Small trial run")
     ap.add_argument(
         "--only",
@@ -688,7 +646,6 @@ def main():
     uploader = None
     if args.hf_upload_interval > 0:
         from hf_uploader import HFUploader
-
         uploader = HFUploader(data_dir, interval_s = args.hf_upload_interval)
         uploader.start()
 
@@ -729,15 +686,9 @@ def main():
                 if not only or "commits" in only:
                     default_ref = repo_meta.get("defaultBranchRef") or {}
                     default_branch = (
-                        default_ref.get("name")
-                        if isinstance(default_ref, dict)
-                        else None
-                    )
-                    branch = (
-                        f"refs/heads/{default_branch}"
-                        if default_branch
-                        else "refs/heads/main"
+                        default_ref.get("name") if isinstance(default_ref, dict) else None
                     )
+                    branch = f"refs/heads/{default_branch}" if default_branch else "refs/heads/main"
                     scraper.scrape_commits(branch = branch)
             finally:
                 scraper.close()
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
index efa663db2f..de9ccca82b 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
@@ -25,7 +25,11 @@ class StateStore:
             except Exception:
                 self._data = {}
 
-    def get(self, key: str, default: Any = None) -> Any:
+    def get(
+        self,
+        key: str,
+        default: Any = None,
+    ) -> Any:
         with self._lock:
             return self._data.get(key, default)
 
diff --git a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
index f6fdf74612..4da46634e5 100644
--- a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
+++ b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
@@ -19,10 +19,7 @@ _MIN_BREAK_RATIO = 0.6
 _CACHE_DIR = unstructured_seed_cache_root()
 
 
-def resolve_chunking(
-    chunk_size: Any,
-    chunk_overlap: Any,
-) -> tuple[int, int]:
+def resolve_chunking(chunk_size: Any, chunk_overlap: Any) -> tuple[int, int]:
     size = _to_int(chunk_size, DEFAULT_CHUNK_SIZE)
     size = max(1, min(size, MAX_CHUNK_SIZE))
     overlap = _to_int(chunk_overlap, DEFAULT_CHUNK_OVERLAP)
@@ -31,11 +28,7 @@ def resolve_chunking(
 
 
 def build_unstructured_preview_rows(
-    *,
-    source_path: Path,
-    preview_size: int,
-    chunk_size: Any,
-    chunk_overlap: Any,
+    *, source_path: Path, preview_size: int, chunk_size: Any, chunk_overlap: Any
 ) -> list[dict[str, str]]:
     parquet_path, rows = materialize_unstructured_seed_dataset(
         source_path = source_path,
@@ -49,9 +42,7 @@ def build_unstructured_preview_rows(
     try:
         import pandas as pd
     except ImportError as exc:  # pragma: no cover
-        raise RuntimeError(
-            f"pandas is required for unstructured seed processing: {exc}"
-        ) from exc
+        raise RuntimeError(f"pandas is required for unstructured seed processing: {exc}") from exc
 
     dataframe = pd.read_parquet(parquet_path).head(count)
     return [
@@ -78,10 +69,7 @@ def build_multi_file_preview_rows(
     return _round_robin_preview(rows, preview_size)
 
 
-def _round_robin_preview(
-    rows: list[dict[str, str]],
-    preview_size: int,
-) -> list[dict[str, str]]:
+def _round_robin_preview(rows: list[dict[str, str]], preview_size: int) -> list[dict[str, str]]:
     """Pick preview rows round-robin across source files so every file is represented."""
     if not rows or preview_size <= 0:
         return []
@@ -115,10 +103,7 @@ def _round_robin_preview(
 
 
 def materialize_unstructured_seed_dataset(
-    *,
-    source_path: Path,
-    chunk_size: Any,
-    chunk_overlap: Any,
+    *, source_path: Path, chunk_size: Any, chunk_overlap: Any
 ) -> tuple[Path, list[dict[str, str]]]:
     resolved = source_path.expanduser().resolve()
     if not resolved.is_file():
@@ -148,9 +133,7 @@ def materialize_unstructured_seed_dataset(
     try:
         import pandas as pd
     except ImportError as exc:  # pragma: no cover
-        raise RuntimeError(
-            f"pandas is required for unstructured seed processing: {exc}"
-        ) from exc
+        raise RuntimeError(f"pandas is required for unstructured seed processing: {exc}") from exc
 
     tmp_path = _CACHE_DIR / f"{key}.tmp.parquet"
     pd.DataFrame(rows).to_parquet(tmp_path, index = False)
@@ -209,12 +192,7 @@ def normalize_unstructured_text(text: str) -> str:
     return re.sub(r"\n{3,}", "\n\n", normalized).strip()
 
 
-def split_text_into_chunks(
-    *,
-    text: str,
-    chunk_size: int,
-    chunk_overlap: int,
-) -> list[str]:
+def split_text_into_chunks(*, text: str, chunk_size: int, chunk_overlap: int) -> list[str]:
     if not text:
         return []
     if chunk_size <= 0:
@@ -268,12 +246,7 @@ def _to_int(value: Any, fallback: int) -> int:
     return parsed
 
 
-def _compute_cache_key(
-    *,
-    source_path: Path,
-    chunk_size: int,
-    chunk_overlap: int,
-) -> str:
+def _compute_cache_key(*, source_path: Path, chunk_size: int, chunk_overlap: int) -> str:
     stat = source_path.stat()
     payload = "|".join(
         [
@@ -288,9 +261,7 @@ def _compute_cache_key(
 
 
 def _compute_multi_file_cache_key(
-    file_entries: list[tuple[Path, str]],
-    chunk_size: int,
-    chunk_overlap: int,
+    file_entries: list[tuple[Path, str]], chunk_size: int, chunk_overlap: int
 ) -> str:
     parts: list[str] = []
     for path, name in sorted(file_entries, key = lambda e: e[1]):
diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index 23112ca2f8..7c60545595 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -227,9 +227,7 @@ async def auth_status() -> AuthStatusResponse:
     return AuthStatusResponse(
         initialized = storage.is_initialized(),
         default_username = storage.DEFAULT_ADMIN_USERNAME,
-        requires_password_change = storage.requires_password_change(
-            storage.DEFAULT_ADMIN_USERNAME
-        )
+        requires_password_change = storage.requires_password_change(storage.DEFAULT_ADMIN_USERNAME)
         if storage.is_initialized()
         else True,
     )
@@ -246,10 +244,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
             status_code = status.HTTP_429_TOO_MANY_REQUESTS,
             # IP is intentionally not interpolated into the body; behind a
             # proxy or NAT it is either misleading or an info leak.
-            detail = (
-                f"Too many failed login attempts. "
-                f"Try again in {blocked_for} seconds."
-            ),
+            detail = (f"Too many failed login attempts. " f"Try again in {blocked_for} seconds."),
             headers = {"Retry-After": str(blocked_for)},
         )
 
@@ -285,8 +280,7 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
 
 @router.post("/logout", status_code = status.HTTP_204_NO_CONTENT)
 async def logout(
-    request: Request,
-    current_subject: str = Depends(get_current_subject_allow_password_change),
+    request: Request, current_subject: str = Depends(get_current_subject_allow_password_change)
 ) -> Response:
     """Revoke refresh tokens for the subject; the access token is stateless and expires on its own."""
     try:
@@ -335,9 +329,7 @@ async def refresh(payload: RefreshTokenRequest) -> Token:
         access_token = new_access_token,
         refresh_token = new_refresh_token,
         token_type = "bearer",
-        must_change_password = False
-        if is_desktop
-        else storage.requires_password_change(username),
+        must_change_password = False if is_desktop else storage.requires_password_change(username),
     )
 
 
@@ -402,8 +394,7 @@ def _row_to_api_key_response(row: dict) -> ApiKeyResponse:
 
 @router.post("/api-keys", response_model = CreateApiKeyResponse)
 async def create_api_key(
-    payload: CreateApiKeyRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: CreateApiKeyRequest, current_subject: str = Depends(get_current_subject)
 ) -> CreateApiKeyResponse:
     """Create a new API key. The raw key is returned once and cannot be retrieved later."""
     expires_at = None
@@ -424,9 +415,7 @@ async def create_api_key(
 
 
 @router.get("/api-keys", response_model = ApiKeyListResponse)
-async def list_api_keys(
-    current_subject: str = Depends(get_current_subject),
-) -> ApiKeyListResponse:
+async def list_api_keys(current_subject: str = Depends(get_current_subject)) -> ApiKeyListResponse:
     """List all API keys for the authenticated user (raw keys are never exposed)."""
     rows = storage.list_api_keys(current_subject)
     return ApiKeyListResponse(
@@ -435,10 +424,7 @@ async def list_api_keys(
 
 
 @router.delete("/api-keys/{key_id}")
-async def revoke_api_key(
-    key_id: int,
-    current_subject: str = Depends(get_current_subject),
-) -> dict:
+async def revoke_api_key(key_id: int, current_subject: str = Depends(get_current_subject)) -> dict:
     """Revoke (soft-delete) an API key."""
     if not storage.revoke_api_key(current_subject, key_id):
         raise HTTPException(
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 4da3c7d621..68d2c67ec8 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -163,9 +163,7 @@ class ChatSettingsPayload(BaseModel):
     inferenceParams: Optional[ChatInferenceSettings] = None
     customPresets: Optional[list[ChatPreset]] = None
     activePreset: Optional[str] = None
-    activePresetSource: Optional[Literal["builtin-default", "custom", "modified"]] = (
-        None
-    )
+    activePresetSource: Optional[Literal["builtin-default", "custom", "modified"]] = None
     autoTitle: Optional[bool] = None
     reasoningEffort: Optional[
         Literal["none", "minimal", "low", "medium", "high", "max", "xhigh"]
@@ -228,10 +226,7 @@ async def list_threads(
 
 
 @router.post("/threads", response_model = ChatThread)
-async def save_thread(
-    payload: ChatThread,
-    current_subject: str = Depends(get_current_subject),
-):
+async def save_thread(payload: ChatThread, current_subject: str = Depends(get_current_subject)):
     if payload.projectId and get_chat_project(payload.projectId) is None:
         raise HTTPException(
             status_code = 404,
@@ -241,10 +236,7 @@ async def save_thread(
 
 
 @router.get("/threads/{thread_id}", response_model = ChatThread)
-async def get_thread(
-    thread_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_thread(thread_id: str, current_subject: str = Depends(get_current_subject)):
     thread = get_chat_thread(thread_id)
     if thread is None:
         raise HTTPException(status_code = 404, detail = f"Thread {thread_id} not found")
@@ -277,8 +269,7 @@ async def patch_thread(
 
 @router.delete("/threads")
 async def delete_threads(
-    payload: ChatDeleteRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: ChatDeleteRequest, current_subject: str = Depends(get_current_subject)
 ):
     delete_chat_threads(payload.ids)
     return {"status": "deleted"}
@@ -286,8 +277,7 @@ async def delete_threads(
 
 @router.get("/projects", response_model = ChatProjectListResponse)
 async def list_projects(
-    include_archived: bool = Query(False),
-    current_subject: str = Depends(get_current_subject),
+    include_archived: bool = Query(False), current_subject: str = Depends(get_current_subject)
 ):
     return ChatProjectListResponse(
         projects = [
@@ -298,18 +288,12 @@ async def list_projects(
 
 
 @router.post("/projects", response_model = ChatProject)
-async def save_project(
-    payload: ChatProject,
-    current_subject: str = Depends(get_current_subject),
-):
+async def save_project(payload: ChatProject, current_subject: str = Depends(get_current_subject)):
     return ChatProject(**upsert_chat_project(payload.model_dump()))
 
 
 @router.get("/projects/{project_id}", response_model = ChatProject)
-async def get_project(
-    project_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_project(project_id: str, current_subject: str = Depends(get_current_subject)):
     project = ensure_chat_project_workspace(project_id)
     if project is None:
         raise HTTPException(
@@ -356,10 +340,7 @@ async def delete_project(
 
 
 @router.get("/threads/{thread_id}/messages", response_model = ChatMessageListResponse)
-async def get_thread_messages(
-    thread_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_thread_messages(thread_id: str, current_subject: str = Depends(get_current_subject)):
     if get_chat_thread(thread_id) is None:
         raise HTTPException(status_code = 404, detail = f"Thread {thread_id} not found")
     return ChatMessageListResponse(
@@ -369,8 +350,7 @@ async def get_thread_messages(
 
 @router.post("/messages:batch", response_model = ChatMessagesBatchResponse)
 async def batch_thread_messages(
-    payload: ChatMessagesBatchRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: ChatMessagesBatchRequest, current_subject: str = Depends(get_current_subject)
 ):
     """One round-trip per sidebar/search rebuild instead of N. Unknown thread
     ids are returned as empty lists so callers don't need a pre-flight."""
@@ -425,14 +405,10 @@ async def replace_thread_messages(
     payload: ChatMessageSyncRequest,
     current_subject: str = Depends(get_current_subject),
 ):
-    mismatched_ids = [
-        message.id for message in payload.messages if message.threadId != thread_id
-    ]
+    mismatched_ids = [message.id for message in payload.messages if message.threadId != thread_id]
     if mismatched_ids:
         preview = ", ".join(mismatched_ids[:5])
-        suffix = (
-            "" if len(mismatched_ids) <= 5 else f" (+{len(mismatched_ids) - 5} more)"
-        )
+        suffix = "" if len(mismatched_ids) <= 5 else f" (+{len(mismatched_ids) - 5} more)"
         raise HTTPException(
             status_code = 400,
             detail = f"Message threadId mismatch: {preview}{suffix}",
@@ -478,8 +454,7 @@ async def get_import_ledger(current_subject: str = Depends(get_current_subject))
 
 @router.post("/import-ledger", response_model = ChatImportLedgerRecordResponse)
 async def record_import_ledger(
-    payload: ChatImportLedgerRecordRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: ChatImportLedgerRecordRequest, current_subject: str = Depends(get_current_subject)
 ):
     """Mark each legacy thread id as imported. Idempotent."""
     accepted, inserted = upsert_chat_legacy_imports(payload.threadIds)
@@ -499,8 +474,7 @@ async def get_settings(current_subject: str = Depends(get_current_subject)):
 
 @router.put("/settings", response_model = ChatSettingsResponse)
 async def put_settings(
-    payload: dict[str, Any],
-    current_subject: str = Depends(get_current_subject),
+    payload: dict[str, Any], current_subject: str = Depends(get_current_subject)
 ):
     try:
         parsed = ChatSettingsPayload.model_validate(payload)
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index 238ff08006..a2d41f87b0 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -159,9 +159,7 @@ def _ensure_selected_local_model_loaded(
 ) -> None:
     model_loaded, active_model, active_variant = _loaded_local_model_identity()
     if not model_loaded:
-        raise ValueError(
-            "No model loaded in Chat. Load a model first, then run the recipe."
-        )
+        raise ValueError("No model loaded in Chat. Load a model first, then run the recipe.")
 
     selection = _single_used_local_model_selection(recipe, local_provider_names)
     if selection is None:
@@ -171,9 +169,7 @@ def _ensure_selected_local_model_loaded(
     variant_matches = not gguf_variant or active_variant == gguf_variant
     if active_model.lower() != target.lower() or not variant_matches:
         selected = f"{target} ({gguf_variant})" if gguf_variant else target
-        active = (
-            f"{active_model} ({active_variant})" if active_variant else active_model
-        )
+        active = f"{active_model} ({active_variant})" if active_variant else active_model
         raise ValueError(
             "Selected local model is not loaded. "
             f"Selected {selected}; active {active or 'none'}. "
@@ -207,9 +203,7 @@ def _inject_local_structured_response_format(
     for mc in model_configs:
         if not isinstance(mc, dict):
             continue
-        if mc.get("provider") in local_provider_names and isinstance(
-            mc.get("alias"), str
-        ):
+        if mc.get("provider") in local_provider_names and isinstance(mc.get("alias"), str):
             alias_to_local_mc[mc["alias"]] = mc
 
     if not alias_to_local_mc:
@@ -307,18 +301,12 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
     # from an LLM column through a model_config. Orphan model_config nodes
     # that reference a local provider but that no LLM column uses should
     # not block runs; the recipe would never call /v1 for them.
-    local_names = {
-        providers[i].get("name") for i in local_indices if providers[i].get("name")
-    }
+    local_names = {providers[i].get("name") for i in local_indices if providers[i].get("name")}
     used_aliases = _used_llm_model_aliases(recipe)
     referenced_providers = {
         mc.get("provider")
         for mc in recipe.get("model_configs", [])
-        if (
-            isinstance(mc, dict)
-            and mc.get("provider")
-            and mc.get("alias") in used_aliases
-        )
+        if (isinstance(mc, dict) and mc.get("provider") and mc.get("alias") in used_aliases)
     }
 
     token = ""
@@ -409,9 +397,7 @@ def _normalize_run_name(value: Any) -> str | None:
     if value is None:
         return None
     if not isinstance(value, str):
-        raise HTTPException(
-            status_code = 400, detail = "invalid run_name: must be a string"
-        )
+        raise HTTPException(status_code = 400, detail = "invalid run_name: must be a string")
     trimmed = value.strip()
     if not trimmed:
         return None
@@ -439,7 +425,6 @@ def create_job(payload: RecipePayload, request: Request):
     if run_config_raw is not None:
         try:
             from data_designer.config.run_config import RunConfig
-
             RunConfig.model_validate(run_config_raw)
         except (ImportError, ValidationError, TypeError, ValueError) as exc:
             raise log_and_http_error(
@@ -506,7 +491,6 @@ def _revoke_internal_api_key_safe(key_id: int) -> None:
     that revocation failures never mask the caller's own error path."""
     try:
         from auth import storage  # deferred: avoids circular import
-
         storage.revoke_internal_api_key(key_id)
     except Exception:
         pass
@@ -578,9 +562,7 @@ def publish_job_dataset(job_id: str, payload: PublishDatasetRequest):
     description = payload.description.strip()
     hf_token = payload.hf_token.strip() if isinstance(payload.hf_token, str) else None
     artifact_path = (
-        payload.artifact_path.strip()
-        if isinstance(payload.artifact_path, str)
-        else None
+        payload.artifact_path.strip() if isinstance(payload.artifact_path, str) else None
     )
 
     if not repo_id:
@@ -591,10 +573,7 @@ def publish_job_dataset(job_id: str, payload: PublishDatasetRequest):
     mgr = get_job_manager()
     status = mgr.get_status(job_id)
     if status is not None:
-        if (
-            status.get("status") != "completed"
-            or status.get("execution_type") != "full"
-        ):
+        if status.get("status") != "completed" or status.get("execution_type") != "full":
             raise HTTPException(
                 status_code = 409,
                 detail = "Only completed full runs can be published.",
diff --git a/studio/backend/routes/data_recipe/mcp.py b/studio/backend/routes/data_recipe/mcp.py
index 2c79d323f3..78a39877cc 100644
--- a/studio/backend/routes/data_recipe/mcp.py
+++ b/studio/backend/routes/data_recipe/mcp.py
@@ -69,9 +69,7 @@ def list_mcp_tools(payload: McpToolsListRequest) -> McpToolsListResponse:
         provider = built[0]
         try:
             tools = mcp_io.list_tools(provider, timeout_sec = payload.timeout_sec)
-            tool_names = sorted(
-                {tool.name for tool in tools if getattr(tool, "name", "")}
-            )
+            tool_names = sorted({tool.name for tool in tools if getattr(tool, "name", "")})
             for tool_name in tool_names:
                 tool_to_providers[tool_name].append(provider.name)
             providers.append(
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index 51ea37452e..6368585932 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -63,9 +63,7 @@ _SAFE_ID_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
 
 def _validate_safe_id(value: str, label: str) -> str:
     if not value or not _SAFE_ID_RE.match(value):
-        raise HTTPException(
-            400, f"Invalid {label}: must be alphanumeric/dash/underscore only"
-        )
+        raise HTTPException(400, f"Invalid {label}: must be alphanumeric/dash/underscore only")
     return value
 
 
@@ -75,8 +73,7 @@ def _serialize_preview_value(value: Any) -> Any:
 
 def _serialize_preview_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return [
-        {str(key): _serialize_preview_value(value) for key, value in row.items()}
-        for row in rows
+        {str(key): _serialize_preview_value(value) for key, value in row.items()} for row in rows
     ]
 
 
@@ -124,7 +121,9 @@ def _select_best_file(data_files: list[str], split: str = DEFAULT_SPLIT) -> str
 
 
 def _resolve_seed_hf_path(
-    dataset_name: str, data_files: list[str], split: str = DEFAULT_SPLIT
+    dataset_name: str,
+    data_files: list[str],
+    split: str = DEFAULT_SPLIT,
 ) -> str | None:
     selected = _select_best_file(data_files, split)
     if not selected:
@@ -164,10 +163,7 @@ def _build_stream_load_kwargs(
 
 
 def _load_preview_rows(
-    *,
-    load_dataset_fn,
-    load_kwargs: dict[str, Any],
-    preview_size: int,
+    *, load_dataset_fn, load_kwargs: dict[str, Any], preview_size: int
 ) -> list[dict[str, Any]]:
     streamed_ds = load_dataset_fn(**load_kwargs)
     return [row for row in islice(streamed_ds, preview_size)]
@@ -198,9 +194,7 @@ def _decode_base64_payload(content_base64: str) -> bytes:
         raise HTTPException(status_code = 400, detail = "invalid base64 payload") from exc
 
 
-def _read_preview_rows_from_local_file(
-    path: Path, preview_size: int
-) -> list[dict[str, Any]]:
+def _read_preview_rows_from_local_file(path: Path, preview_size: int) -> list[dict[str, Any]]:
     try:
         import pandas as pd
     except ImportError as exc:
@@ -251,11 +245,7 @@ def _read_preview_rows_from_local_file(
 
 
 def _read_preview_rows_from_unstructured_file(
-    *,
-    path: Path,
-    preview_size: int,
-    chunk_size: int | None,
-    chunk_overlap: int | None,
+    *, path: Path, preview_size: int, chunk_size: int | None, chunk_overlap: int | None
 ) -> list[dict[str, Any]]:
     if resolve_chunking is None or build_unstructured_preview_rows is None:
         raise HTTPException(
@@ -302,9 +292,7 @@ def _read_preview_rows_from_multi_files(
     for fid, fname in zip(file_ids, file_names):
         extracted = block_dir / f"{fid}.extracted.txt"
         if not extracted.exists():
-            raise HTTPException(
-                404, f"Extracted text not found for file: {fname} (id: {fid})"
-            )
+            raise HTTPException(404, f"Extracted text not found for file: {fname} (id: {fid})")
         file_entries.append((extracted, fname))
 
     return build_multi_file_preview_rows(
@@ -384,9 +372,7 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
             ) from exc
 
     if not preview_rows:
-        raise HTTPException(
-            status_code = 422, detail = "dataset appears empty or unreadable"
-        )
+        raise HTTPException(status_code = 422, detail = "dataset appears empty or unreadable")
     preview_rows = _serialize_preview_rows(preview_rows)
     columns = _extract_columns(preview_rows)
 
@@ -395,9 +381,7 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
     else:
         resolved_path = _resolve_seed_hf_path(dataset_name, data_files, split)
         if not resolved_path:
-            raise HTTPException(
-                status_code = 422, detail = "unable to resolve seed dataset path"
-            )
+            raise HTTPException(status_code = 422, detail = "unable to resolve seed dataset path")
 
     return SeedInspectResponse(
         dataset_name = dataset_name,
@@ -415,13 +399,11 @@ def _extract_text_from_file(file_path: Path, ext: str) -> str:
         raw = file_path.read_text(encoding = "utf-8", errors = "ignore")
     elif ext == ".pdf":
         import pymupdf4llm
-
         raw = pymupdf4llm.to_markdown(
             str(file_path), write_images = False, show_progress = False, use_ocr = False
         )
     elif ext == ".docx":
         import mammoth
-
         with open(str(file_path), "rb") as f:
             result = mammoth.convert_to_markdown(f)
             raw = result.value
@@ -449,8 +431,7 @@ def _get_block_total_size(block_dir: Path) -> int:
 
 @router.post("/seed/upload-unstructured-file")
 async def upload_unstructured_file(
-    file: UploadFile = FastAPIFile(...),
-    block_id: str = Form(...),
+    file: UploadFile = FastAPIFile(...), block_id: str = Form(...)
 ) -> UnstructuredFileUploadResponse:
     _validate_safe_id(block_id, "block_id")
 
@@ -519,9 +500,7 @@ async def upload_unstructured_file(
     try:
         meta_path = block_dir / f"{file_id}.meta.json"
         meta_path.write_text(
-            json.dumps(
-                {"original_filename": original_filename, "size_bytes": size_bytes}
-            ),
+            json.dumps({"original_filename": original_filename, "size_bytes": size_bytes}),
             encoding = "utf-8",
         )
     except OSError:
@@ -647,9 +626,7 @@ def inspect_seed_upload(payload: SeedInspectUploadRequest) -> SeedInspectRespons
             int(payload.preview_size),
         )
     if not preview_rows:
-        raise HTTPException(
-            status_code = 422, detail = "dataset appears empty or unreadable"
-        )
+        raise HTTPException(status_code = 422, detail = "dataset appears empty or unreadable")
     columns = _extract_columns(preview_rows)
 
     return SeedInspectResponse(
diff --git a/studio/backend/routes/data_recipe/validate.py b/studio/backend/routes/data_recipe/validate.py
index f6fd9e6046..e26093d6bf 100644
--- a/studio/backend/routes/data_recipe/validate.py
+++ b/studio/backend/routes/data_recipe/validate.py
@@ -21,7 +21,9 @@ from utils.utils import safe_error_detail, safe_curated_detail, log_and_http_err
 logger = get_logger(__name__)
 router = APIRouter()
 
-_GITHUB_VALIDATE_NOTE = "Recipe shape is valid. GitHub access and rate limits are checked when the run starts."
+_GITHUB_VALIDATE_NOTE = (
+    "Recipe shape is valid. GitHub access and rate limits are checked when the run starts."
+)
 _GITHUB_ITEM_TYPES = {"issues", "pulls", "commits"}
 
 
@@ -44,23 +46,17 @@ def _validate_github_seed_static(source: dict[str, Any]) -> list[ValidateError]:
     else:
         for repo in repos:
             if not isinstance(repo, str) or not repo.strip() or "/" not in repo:
-                errors.append(
-                    ValidateError(message = "GitHub repos must be owner/name strings.")
-                )
+                errors.append(ValidateError(message = "GitHub repos must be owner/name strings."))
                 break
 
     item_types = source.get("item_types")
     if not isinstance(item_types, list) or not item_types:
-        errors.append(
-            ValidateError(message = "GitHub seed requires at least one item type.")
-        )
+        errors.append(ValidateError(message = "GitHub seed requires at least one item type."))
     else:
         invalid_items = [item for item in item_types if item not in _GITHUB_ITEM_TYPES]
         if invalid_items:
             errors.append(
-                ValidateError(
-                    message = "GitHub item types must be issues, pulls, or commits."
-                )
+                ValidateError(message = "GitHub item types must be issues, pulls, or commits.")
             )
 
     try:
@@ -166,8 +162,7 @@ def validate(payload: RecipePayload) -> ValidateResponse:
             if not (exc.name or "").startswith("data_designer"):
                 raise
             logger.debug(
-                "data_designer not installed; deferring full config "
-                "validation to run start",
+                "data_designer not installed; deferring full config validation to run start",
                 missing_module = exc.name,
             )
         except Exception as exc:
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 1ea696705c..711e9723d5 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -99,7 +99,6 @@ def _serialize_preview_value(value):
 
     try:
         from PIL.Image import Image as PILImage
-
         if isinstance(value, PILImage):
             buffer = io.BytesIO()
             value.convert("RGB").save(buffer, format = "JPEG", quality = 85)
@@ -261,9 +260,7 @@ def _build_local_dataset_items() -> list[LocalDatasetItem]:
     return items
 
 
-def _load_local_preview_slice(
-    *, dataset_path: Path, train_split: str, preview_size: int
-):
+def _load_local_preview_slice(*, dataset_path: Path, train_split: str, preview_size: int):
     from datasets import load_dataset
 
     if dataset_path.is_dir():
@@ -298,9 +295,7 @@ def _load_local_preview_slice(
     elif dataset_path.suffix == ".csv":
         dataset = load_dataset("csv", data_files = str(dataset_path), split = train_split)
     elif dataset_path.suffix == ".parquet":
-        dataset = load_dataset(
-            "parquet", data_files = str(dataset_path), split = train_split
-        )
+        dataset = load_dataset("parquet", data_files = str(dataset_path), split = train_split)
     else:
         raise HTTPException(
             status_code = 400, detail = f"Unsupported file format: {dataset_path.suffix}"
@@ -320,8 +315,7 @@ def _sanitize_filename(filename: str) -> str:
 
 @router.post("/upload", response_model = UploadDatasetResponse)
 async def upload_dataset(
-    file: UploadFile,
-    current_subject: str = Depends(get_current_subject),
+    file: UploadFile, current_subject: str = Depends(get_current_subject)
 ) -> UploadDatasetResponse:
     filename = _sanitize_filename(file.filename or "dataset_upload")
     ext = Path(filename).suffix.lower()
@@ -378,9 +372,7 @@ def list_local_datasets(
 
 @router.get("/download-progress")
 async def get_dataset_download_progress(
-    repo_id: str = Query(
-        ..., description = "HuggingFace dataset repo ID, e.g. 'unsloth/LaTeX_OCR'"
-    ),
+    repo_id: str = Query(..., description = "HuggingFace dataset repo ID, e.g. 'unsloth/LaTeX_OCR'"),
     current_subject: str = Depends(get_current_subject),
 ):
     """Return download progress for a HuggingFace dataset repo.
@@ -460,10 +452,7 @@ async def get_dataset_download_progress(
 
 
 @router.post("/check-format", response_model = CheckFormatResponse)
-def check_format(
-    request: CheckFormatRequest,
-    current_subject: str = Depends(get_current_subject),
-):
+def check_format(request: CheckFormatRequest, current_subject: str = Depends(get_current_subject)):
     """
     Check if a dataset requires manual column mapping.
 
@@ -511,25 +500,19 @@ def check_format(
                     repo_type = "dataset",
                     token = request.hf_token or None,
                 )
-                data_files = [
-                    f for f in repo_files if any(f.endswith(ext) for ext in DATA_EXTS)
-                ]
+                data_files = [f for f in repo_files if any(f.endswith(ext) for ext in DATA_EXTS)]
 
                 # Prefer tabular formats over archives (e.g. images.zip → ImageFolder
                 # with synthetic image/label columns that don't match the real schema).
                 tabular_files = [
-                    f
-                    for f in data_files
-                    if any(f.endswith(ext) for ext in _TABULAR_EXTS)
+                    f for f in data_files if any(f.endswith(ext) for ext in _TABULAR_EXTS)
                 ]
                 candidates = tabular_files or data_files
 
                 # When a subset is specified, narrow to files whose name matches
                 # (e.g. subset="testmini" → prefer "testmini.parquet").
                 if request.subset and candidates:
-                    subset_matches = [
-                        f for f in candidates if request.subset in Path(f).stem
-                    ]
+                    subset_matches = [f for f in candidates if request.subset in Path(f).stem]
                     if subset_matches:
                         candidates = subset_matches
 
@@ -601,9 +584,7 @@ def check_format(
                     processed = format_result["dataset"]
                     preview_samples = _serialize_preview_rows(processed)
                 except Exception as e:
-                    logger.warning(
-                        f"Processed preview generation failed (non-fatal): {e}"
-                    )
+                    logger.warning(f"Processed preview generation failed (non-fatal): {e}")
                     preview_samples = _serialize_preview_rows(preview_slice)
         else:
             preview_samples = _serialize_preview_rows(preview_slice)
@@ -614,9 +595,7 @@ def check_format(
         if image_col and image_col in (result.get("columns") or []):
             try:
                 sample_val = preview_slice[0][image_col]
-                if isinstance(sample_val, str) and sample_val.startswith(
-                    ("http://", "https://")
-                ):
+                if isinstance(sample_val, str) and sample_val.startswith(("http://", "https://")):
                     url_warning = (
                         "This dataset contains image URLs instead of embedded images. "
                         "Images will be downloaded during training, which may be slow for large datasets."
@@ -652,8 +631,7 @@ def check_format(
 
 @router.post("/ai-assist-mapping", response_model = AiAssistMappingResponse)
 def ai_assist_mapping(
-    request: AiAssistMappingRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: AiAssistMappingRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Run LLM-assisted dataset conversion advisor (user-triggered).
@@ -670,8 +648,7 @@ def ai_assist_mapping(
 
         # Truncate sample values for the LLM prompt
         truncated = [
-            {col: str(s.get(col, ""))[:200] for col in request.columns}
-            for s in request.samples[:5]
+            {col: str(s.get(col, ""))[:200] for col in request.columns} for s in request.samples[:5]
         ]
 
         result = llm_conversion_advisor(
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index 2bfca30cee..302d534874 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -54,8 +54,7 @@ logger = get_logger(__name__)
 
 @router.post("/load-checkpoint", response_model = ExportOperationResponse)
 async def load_checkpoint(
-    request: LoadCheckpointRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: LoadCheckpointRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Load a checkpoint into the export backend.
@@ -70,7 +69,6 @@ async def load_checkpoint(
         # before loading the export checkpoint (they'd compete for VRAM).
         try:
             from core.inference import get_inference_backend
-
             inf = get_inference_backend()
             if inf.active_model_name:
                 logger.info(
@@ -85,7 +83,6 @@ async def load_checkpoint(
 
         try:
             from core.training import get_training_backend
-
             trn = get_training_backend()
             if trn.is_training_active():
                 logger.info("Stopping active training to free GPU memory for export")
@@ -96,12 +93,9 @@ async def load_checkpoint(
                     if not trn.is_training_active():
                         break
                     import time
-
                     time.sleep(0.5)
                 else:
-                    logger.warning(
-                        "Training subprocess did not exit within 30s, proceeding anyway"
-                    )
+                    logger.warning("Training subprocess did not exit within 30s, proceeding anyway")
         except Exception as e:
             logger.warning("Could not stop training: %s", e)
 
@@ -132,9 +126,7 @@ async def load_checkpoint(
 
 
 @router.post("/cleanup", response_model = ExportOperationResponse)
-async def cleanup_export_memory(
-    current_subject: str = Depends(get_current_subject),
-):
+async def cleanup_export_memory(current_subject: str = Depends(get_current_subject)):
     """
     Cleanup export-related models from memory (GPU/CPU).
 
@@ -165,9 +157,7 @@ async def cleanup_export_memory(
 
 
 @router.get("/status", response_model = ExportStatusResponse)
-async def get_export_status(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_export_status(current_subject: str = Depends(get_current_subject)):
     """
     Get current export backend status (loaded checkpoint, model type, PEFT flag).
     """
@@ -203,8 +193,7 @@ def _export_details(output_path: Optional[str]) -> Optional[Dict[str, Any]]:
 
 @router.post("/export/merged", response_model = ExportOperationResponse)
 async def export_merged_model(
-    request: ExportMergedModelRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: ExportMergedModelRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Export a merged PEFT model (e.g., 16-bit or 4-bit) and optionally push to Hub.
@@ -243,8 +232,7 @@ async def export_merged_model(
 
 @router.post("/export/base", response_model = ExportOperationResponse)
 async def export_base_model(
-    request: ExportBaseModelRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: ExportBaseModelRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Export a non-PEFT base model and optionally push to Hub.
@@ -283,8 +271,7 @@ async def export_base_model(
 
 @router.post("/export/gguf", response_model = ExportOperationResponse)
 async def export_gguf(
-    request: ExportGGUFRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: ExportGGUFRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Export the current model to GGUF format and optionally push to Hub.
@@ -322,8 +309,7 @@ async def export_gguf(
 
 @router.post("/export/lora", response_model = ExportOperationResponse)
 async def export_lora_adapter(
-    request: ExportLoRAAdapterRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: ExportLoRAAdapterRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Export only the LoRA adapter (if the loaded model is PEFT).
@@ -377,7 +363,11 @@ async def export_lora_adapter(
 # directive, and `Last-Event-ID` is honored on reconnect.
 
 
-def _format_sse(data: str, event: str, event_id: Optional[int] = None) -> str:
+def _format_sse(
+    data: str,
+    event: str,
+    event_id: Optional[int] = None,
+) -> str:
     """Format a single SSE message with id/event/data fields."""
     lines = []
     if event_id is not None:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 5d22b3ff90..70a9aa27d0 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -92,7 +92,9 @@ def _friendly_error(exc: Exception) -> str:
     # subprocess is unreachable", which for Studio always means the
     # llama-server subprocess crashed or is still coming up.
     if isinstance(exc, httpx.RequestError):
-        return "Lost connection to the model server. It may have crashed -- try reloading the model."
+        return (
+            "Lost connection to the model server. It may have crashed -- try reloading the model."
+        )
     msg = str(exc)
     m = _re.search(
         r"request \((\d+) tokens?\) exceeds the available context size \((\d+) tokens?\)",
@@ -105,7 +107,9 @@ def _friendly_error(exc: Exception) -> str:
             f"or shorten the conversation."
         )
     if "Lost connection to llama-server" in msg:
-        return "Lost connection to the model server. It may have crashed -- try reloading the model."
+        return (
+            "Lost connection to the model server. It may have crashed -- try reloading the model."
+        )
     return "An internal error occurred"
 
 
@@ -353,9 +357,7 @@ async def artifact_preview_frame(
         await get_current_subject(creds)
 
     csp = (
-        _ARTIFACT_PREVIEW_FRAME_NETWORK_CSP
-        if allow_network
-        else _ARTIFACT_PREVIEW_FRAME_STRICT_CSP
+        _ARTIFACT_PREVIEW_FRAME_NETWORK_CSP if allow_network else _ARTIFACT_PREVIEW_FRAME_STRICT_CSP
     )
     return Response(
         content = _ARTIFACT_PREVIEW_FRAME_HTML,
@@ -446,9 +448,7 @@ _PENDING_CANCEL_TTL_S = 30.0
 
 
 def _prune_pending(now: float) -> None:
-    for k in [
-        k for k, ts in _PENDING_CANCELS.items() if now - ts > _PENDING_CANCEL_TTL_S
-    ]:
+    for k in [k for k, ts in _PENDING_CANCELS.items() if now - ts > _PENDING_CANCEL_TTL_S]:
         _PENDING_CANCELS.pop(k, None)
 
 
@@ -590,9 +590,7 @@ _TOOL_XML_RE = _re.compile(
 logger = get_logger(__name__)
 
 
-def _validate_native_mmproj_companion(
-    mmproj_path: str | None, gguf_path: str | None
-) -> None:
+def _validate_native_mmproj_companion(mmproj_path: str | None, gguf_path: str | None) -> None:
     if not mmproj_path or not gguf_path:
         return
     import stat as _stat_module
@@ -606,9 +604,7 @@ def _validate_native_mmproj_companion(
             status_code = 400,
             detail = "Native vision companion is no longer accessible.",
         ) from exc
-    if _stat_module.S_ISLNK(mm_lstat.st_mode) or not _stat_module.S_ISREG(
-        mm_lstat.st_mode
-    ):
+    if _stat_module.S_ISLNK(mm_lstat.st_mode) or not _stat_module.S_ISREG(mm_lstat.st_mode):
         raise HTTPException(
             status_code = 400,
             detail = "Native vision companion must be a regular file.",
@@ -636,9 +632,7 @@ def _normalise_settings_str(value: Optional[str]) -> Optional[str]:
     return value
 
 
-def _request_matches_loaded_settings(
-    request: LoadRequest, llama_backend: LlamaCppBackend
-) -> bool:
+def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaCppBackend) -> bool:
     """True iff every runtime setting on the request matches the loaded
     server. Caller has already checked model+variant+is_loaded. See #5401."""
     # Compare requested n_ctx (not effective) so VRAM-cap doesn't mask
@@ -664,9 +658,7 @@ def _request_matches_loaded_settings(
     if backend_mode in ("mtp", "mtp+ngram") and request.spec_draft_n_max is not None:
         if int(request.spec_draft_n_max) != (llama_backend.spec_draft_n_max or 0):
             return False
-    if (request.chat_template_override or None) != (
-        llama_backend.chat_template_override or None
-    ):
+    if (request.chat_template_override or None) != (llama_backend.chat_template_override or None):
         return False
     # llama_extra_args=None means "inherit"; only an explicit list that
     # differs forces a reload. On the inherit path, refuse to match if
@@ -683,9 +675,7 @@ def _request_matches_loaded_settings(
 
 
 def _resolve_model_identifier_for_request(
-    request: LoadRequest | ValidateModelRequest,
-    *,
-    operation: str,
+    request: LoadRequest | ValidateModelRequest, *, operation: str
 ) -> tuple[str, str, bool]:
     if not request.native_path_lease:
         return request.model_path, request.model_path, False
@@ -705,9 +695,7 @@ def _resolve_model_identifier_for_request(
             status_code = 400,
             detail = redact_native_paths(str(exc)),
         ) from exc
-    display_label = (
-        grant.display_label or Path(request.model_path).name or "Native model"
-    )
+    display_label = grant.display_label or Path(request.model_path).name or "Native model"
     return str(grant.canonical_path), display_label, True
 
 
@@ -788,9 +776,7 @@ async def load_model(
                 inference_config = load_inference_config(llama_backend.model_identifier)
 
                 _gguf_audio = (
-                    llama_backend._audio_type
-                    if hasattr(llama_backend, "_audio_type")
-                    else None
+                    llama_backend._audio_type if hasattr(llama_backend, "_audio_type") else None
                 )
                 _gguf_is_audio = getattr(llama_backend, "_is_audio", False)
                 return LoadResponse(
@@ -828,9 +814,7 @@ async def load_model(
                 backend.active_model_name
                 and backend.active_model_name.lower() == model_identifier.lower()
             ):
-                logger.info(
-                    f"Model already loaded (Unsloth): {model_log_label}, skipping reload"
-                )
+                logger.info(f"Model already loaded (Unsloth): {model_log_label}, skipping reload")
                 inference_config = load_inference_config(backend.active_model_name)
                 _model_info = backend.models.get(backend.active_model_name, {})
                 _chat_template = None
@@ -847,9 +831,7 @@ async def load_model(
                 _sf_reasoning_style = _sf_flags["reasoning_style"]
                 return LoadResponse(
                     status = "already_loaded",
-                    model = model_log_label
-                    if native_grant_backed
-                    else backend.active_model_name,
+                    model = model_log_label if native_grant_backed else backend.active_model_name,
                     display_name = model_log_label
                     if native_grant_backed
                     else backend.active_model_name,
@@ -932,8 +914,7 @@ async def load_model(
                 )
                 if not same_source:
                     logger.info(
-                        "Not inheriting llama_extra_args: stored args came "
-                        "from %s, loading %s",
+                        "Not inheriting llama_extra_args: stored args came from %s, loading %s",
                         source,
                         (model_identifier, resolved_variant),
                     )
@@ -951,8 +932,7 @@ async def load_model(
                         strip_context = "max_seq_length" in fields_set,
                         strip_cache = "cache_type_kv" in fields_set,
                         strip_spec = (
-                            "speculative_type" in fields_set
-                            or "spec_draft_n_max" in fields_set
+                            "speculative_type" in fields_set or "spec_draft_n_max" in fields_set
                         ),
                         strip_template = "chat_template_override" in fields_set,
                     )
@@ -1001,9 +981,7 @@ async def load_model(
             else:
                 # Local mode: llama-server loads via -m <path>
                 if native_grant_backed and config.gguf_mmproj_file:
-                    _validate_native_mmproj_companion(
-                        config.gguf_mmproj_file, config.gguf_file
-                    )
+                    _validate_native_mmproj_companion(config.gguf_mmproj_file, config.gguf_file)
                 success = await asyncio.to_thread(
                     llama_backend.load_model,
                     gguf_path = config.gguf_file,
@@ -1036,9 +1014,7 @@ async def load_model(
             # Audio detection moved into load_model under _serial_load_lock (#5642).
             _gguf_audio = llama_backend._audio_type
             _gguf_is_audio = llama_backend._is_audio
-            llama_backend._native_display_label = (
-                model_log_label if native_grant_backed else None
-            )
+            llama_backend._native_display_label = model_log_label if native_grant_backed else None
             llama_backend._native_grant_backed = bool(native_grant_backed)
             if _gguf_is_audio:
                 logger.info(f"GGUF model detected as audio: audio_type={_gguf_audio}")
@@ -1048,9 +1024,7 @@ async def load_model(
             return LoadResponse(
                 status = "loaded",
                 model = model_log_label if native_grant_backed else config.identifier,
-                display_name = model_log_label
-                if native_grant_backed
-                else config.display_name,
+                display_name = model_log_label if native_grant_backed else config.display_name,
                 is_vision = llama_backend.is_vision,
                 is_lora = False,
                 is_gguf = True,
@@ -1058,9 +1032,7 @@ async def load_model(
                 audio_type = _gguf_audio,
                 has_audio_input = llama_backend._has_audio_input,
                 inference = inference_config,
-                requires_trust_remote_code = bool(
-                    inference_config.get("trust_remote_code", False)
-                ),
+                requires_trust_remote_code = bool(inference_config.get("trust_remote_code", False)),
                 context_length = llama_backend.context_length,
                 max_context_length = llama_backend.max_context_length,
                 native_context_length = llama_backend.native_context_length,
@@ -1087,12 +1059,9 @@ async def load_model(
         # Shut down any export subprocess to free VRAM
         try:
             from core.export import get_export_backend
-
             exp_backend = get_export_backend()
             if exp_backend.current_checkpoint:
-                logger.info(
-                    "Shutting down export subprocess to free GPU memory for inference"
-                )
+                logger.info("Shutting down export subprocess to free GPU memory for inference")
                 exp_backend._shutdown_subprocess()
                 exp_backend.current_checkpoint = None
                 exp_backend.is_vision = False
@@ -1162,9 +1131,7 @@ async def load_model(
             # Check if YAML says this model needs trust_remote_code
             if not request.trust_remote_code:
                 model_defaults = load_model_defaults(config.identifier)
-                yaml_trust = model_defaults.get("inference", {}).get(
-                    "trust_remote_code", False
-                )
+                yaml_trust = model_defaults.get("inference", {}).get("trust_remote_code", False)
                 if yaml_trust:
                     raise HTTPException(
                         status_code = 400,
@@ -1200,9 +1167,7 @@ async def load_model(
         return LoadResponse(
             status = "loaded",
             model = model_log_label if native_grant_backed else config.identifier,
-            display_name = model_log_label
-            if native_grant_backed
-            else config.display_name,
+            display_name = model_log_label if native_grant_backed else config.display_name,
             is_vision = config.is_vision,
             is_lora = config.is_lora,
             is_gguf = False,
@@ -1210,9 +1175,7 @@ async def load_model(
             audio_type = config.audio_type,
             has_audio_input = config.has_audio_input,
             inference = inference_config,
-            requires_trust_remote_code = bool(
-                inference_config.get("trust_remote_code", False)
-            ),
+            requires_trust_remote_code = bool(inference_config.get("trust_remote_code", False)),
             supports_reasoning = _sf_flags["supports_reasoning"],
             reasoning_style = _sf_flags["reasoning_style"],
             reasoning_always_on = _sf_flags["reasoning_always_on"],
@@ -1266,8 +1229,7 @@ async def load_model(
 
 @router.post("/validate", response_model = ValidateModelResponse)
 async def validate_model(
-    request: ValidateModelRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: ValidateModelRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Lightweight validation endpoint for model identifiers.
@@ -1342,10 +1304,7 @@ async def validate_model(
 
 
 @router.post("/unload", response_model = UnloadResponse)
-async def unload_model(
-    request: UnloadRequest,
-    current_subject: str = Depends(get_current_subject),
-):
+async def unload_model(request: UnloadRequest, current_subject: str = Depends(get_current_subject)):
     """
     Unload a model from memory.
     Routes to the correct backend (llama-server for GGUF, Unsloth otherwise).
@@ -1355,9 +1314,7 @@ async def unload_model(
         llama_backend = get_llama_cpp_backend()
         if llama_backend.is_active and (
             llama_backend.model_identifier == request.model_path
-            or is_registered_native_path_label(
-                llama_backend.model_identifier, request.model_path
-            )
+            or is_registered_native_path_label(llama_backend.model_identifier, request.model_path)
             or not llama_backend.is_loaded
         ):
             llama_backend.unload_model()
@@ -1376,10 +1333,7 @@ async def unload_model(
 
 
 @studio_router.post("/cancel")
-async def cancel_inference(
-    request: Request,
-    current_subject: str = Depends(get_current_subject),
-):
+async def cancel_inference(request: Request, current_subject: str = Depends(get_current_subject)):
     """Cancel in-flight inference requests.
 
     Body (JSON, at least one key required):
@@ -1419,8 +1373,7 @@ async def cancel_inference(
 
 @router.post("/generate/stream")
 async def generate_stream(
-    request: GenerateRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: GenerateRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Generate a chat response with Server-Sent Events (SSE) streaming.
@@ -1496,9 +1449,7 @@ async def generate_stream(
 
 
 @router.get("/status", response_model = InferenceStatusResponse)
-async def get_status(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_status(current_subject: str = Depends(get_current_subject)):
     """
     Get current inference backend status.
     Reports whichever backend (Unsloth or llama-server) is currently active.
@@ -1516,7 +1467,6 @@ async def get_status(
             _supports_mtp = True  # fail open
         try:
             from utils.llama_cpp_freshness import check_prebuilt_freshness
-
             _freshness = check_prebuilt_freshness(_bin)
         except Exception:
             _freshness = {}
@@ -1590,17 +1540,13 @@ async def get_status(
             has_audio_input = model_info.get("has_audio_input", False)
         chat_template_info = model_info.get("chat_template_info", {})
         chat_template = (
-            chat_template_info.get("template")
-            if isinstance(chat_template_info, dict)
-            else None
+            chat_template_info.get("template") if isinstance(chat_template_info, dict) else None
         )
 
         # Non-GGUF: classify from the loaded template.
         _sf_flags = _detect_safetensors_features(backend, chat_template)
         inference_config = (
-            load_inference_config(backend.active_model_name)
-            if backend.active_model_name
-            else None
+            load_inference_config(backend.active_model_name) if backend.active_model_name else None
         )
 
         return InferenceStatusResponse(
@@ -1635,9 +1581,7 @@ async def get_status(
 
 
 @router.get("/load-progress", response_model = LoadProgressResponse)
-async def get_load_progress(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_load_progress(current_subject: str = Depends(get_current_subject)):
     """
     Return the active GGUF load's mmap/upload progress.
 
@@ -1684,9 +1628,7 @@ async def generate_audio(
     _, chat_messages, _ = _extract_content_parts(payload.messages)
     if not chat_messages:
         raise HTTPException(status_code = 400, detail = "No messages provided.")
-    last_user_msg = next(
-        (m for m in reversed(chat_messages) if m["role"] == "user"), None
-    )
+    last_user_msg = next((m for m in reversed(chat_messages) if m["role"] == "user"), None)
     if not last_user_msg:
         raise HTTPException(status_code = 400, detail = "No user message found.")
     text = last_user_msg["content"]
@@ -1711,9 +1653,7 @@ async def generate_audio(
             raise HTTPException(status_code = 400, detail = "No model loaded.")
         model_info = backend.models.get(backend.active_model_name, {})
         if not model_info.get("is_audio"):
-            raise HTTPException(
-                status_code = 400, detail = "Active model is not an audio model."
-            )
+            raise HTTPException(status_code = 400, detail = "Active model is not an audio model.")
         model_name = backend.active_model_name
         gen = lambda: backend.generate_audio_response(
             text = text,
@@ -1727,9 +1667,7 @@ async def generate_audio(
         )
 
     try:
-        wav_bytes, sample_rate = await asyncio.get_event_loop().run_in_executor(
-            None, gen
-        )
+        wav_bytes, sample_rate = await asyncio.get_event_loop().run_in_executor(None, gen)
     except Exception as e:
         logger.error(f"Audio generation error: {e}", exc_info = True)
         raise HTTPException(status_code = 500, detail = safe_error_detail(e))
@@ -1795,9 +1733,7 @@ def _decode_audio_base64(b64: str) -> np.ndarray:
     return waveform.squeeze(0).numpy()
 
 
-def _extract_content_parts(
-    messages: list,
-) -> tuple[str, list[dict], "Optional[str]"]:
+def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[str]"]:
     """
     Parse OpenAI-format messages into components the inference backend expects.
 
@@ -1820,9 +1756,7 @@ def _extract_content_parts(
                 system_prompt = msg.content
             elif isinstance(msg.content, list):
                 # Unlikely but handle: join text parts
-                system_prompt = "\n".join(
-                    p.text for p in msg.content if p.type == "text"
-                )
+                system_prompt = "\n".join(p.text for p in msg.content if p.type == "text")
             continue
 
         # ── User / assistant messages ─────────────────────────
@@ -1841,9 +1775,7 @@ def _extract_content_parts(
                         # data:image/png;base64,<DATA> → extract <DATA>
                         first_image_b64 = url.split(",", 1)[1] if "," in url else None
                     else:
-                        logger.warning(
-                            f"Remote image URLs not yet supported: {url[:80]}..."
-                        )
+                        logger.warning(f"Remote image URLs not yet supported: {url[:80]}...")
             combined_text = "\n".join(text_parts) if text_parts else ""
             chat_messages.append({"role": msg.role, "content": combined_text})
 
@@ -1906,7 +1838,6 @@ def _build_external_messages(
     if provider_type == "gemini" and base_url:
         try:
             from urllib.parse import urlparse as _urlparse
-
             _host = (_urlparse(base_url).hostname or "").lower()
             _native_gemini = _host == "generativelanguage.googleapis.com"
         except Exception:
@@ -2015,11 +1946,7 @@ def _build_external_messages(
             # tool_calls (some providers reject empty assistant turns).
             # Preserve assistant turns whose only payload is tool_calls
             # so multi-turn function-call loops round-trip.
-            if (
-                msg.role == "assistant"
-                and not msg.content.strip()
-                and not msg.tool_calls
-            ):
+            if msg.role == "assistant" and not msg.content.strip() and not msg.tool_calls:
                 continue
             out: dict[str, Any] = {"role": msg.role, "content": msg.content}
             if msg.role == "assistant" and msg.tool_calls:
@@ -2073,9 +2000,7 @@ def _build_external_messages(
                                 "image_url": {"url": part.image_url.url},
                             }
                         )
-                    elif (
-                        part.type == "reasoning" and openai and msg.role == "assistant"
-                    ):
+                    elif part.type == "reasoning" and openai and msg.role == "assistant":
                         reasoning: dict[str, Any] = {
                             "type": "reasoning",
                             "id": part.id,
@@ -2085,9 +2010,7 @@ def _build_external_messages(
                             reasoning["status"] = part.status
                         parts.append(reasoning)
                     elif (
-                        part.type == "image_generation_call"
-                        and openai
-                        and msg.role == "assistant"
+                        part.type == "image_generation_call" and openai and msg.role == "assistant"
                     ):
                         # ExternalProviderClient maps this onto a top-level
                         # Responses input item after the current user prompt,
@@ -2158,11 +2081,7 @@ def _build_external_messages(
                         if p.status:
                             reasoning["status"] = p.status
                         preserved.append(reasoning)
-                    elif (
-                        p.type == "image_generation_call"
-                        and openai
-                        and msg.role == "assistant"
-                    ):
+                    elif p.type == "image_generation_call" and openai and msg.role == "assistant":
                         image_ref = {"type": "image_generation_call", "id": p.id}
                         if getattr(p, "response_id", None):
                             image_ref["response_id"] = p.response_id
@@ -2187,9 +2106,7 @@ def _build_external_messages(
                         _entry_content = entry.get("content")
                         _has_text = (
                             isinstance(_entry_content, str) and _entry_content.strip()
-                        ) or (
-                            isinstance(_entry_content, list) and len(_entry_content) > 0
-                        )
+                        ) or (isinstance(_entry_content, list) and len(_entry_content) > 0)
                         if not _has_text:
                             continue
                 if msg.role == "tool":
@@ -2204,8 +2121,7 @@ def _build_external_messages(
 
 
 async def _proxy_to_external_provider(
-    payload: ChatCompletionRequest,
-    request: Request,
+    payload: ChatCompletionRequest, request: Request
 ) -> StreamingResponse:
     """
     Proxy a chat completion request to an external LLM provider.
@@ -2343,9 +2259,7 @@ async def _proxy_to_external_provider(
 # ── OpenAI shell-tool container management ───────────────────────
 
 
-def _resolve_openai_cloud_client(
-    body: OpenAIContainerRequest,
-) -> ExternalProviderClient:
+def _resolve_openai_cloud_client(body: OpenAIContainerRequest) -> ExternalProviderClient:
     """
     Decrypt the API key + validate the base URL points at OpenAI cloud,
     then build an ExternalProviderClient for the three container CRUD
@@ -2388,9 +2302,7 @@ def _summarize_container(raw: dict) -> OpenAIContainerSummary:
     return OpenAIContainerSummary(
         id = str(raw.get("id") or ""),
         name = raw.get("name"),
-        created_at = raw.get("created_at")
-        if isinstance(raw.get("created_at"), int)
-        else None,
+        created_at = raw.get("created_at") if isinstance(raw.get("created_at"), int) else None,
         last_active_at = raw.get("last_active_at")
         if isinstance(raw.get("last_active_at"), int)
         else None,
@@ -2404,8 +2316,7 @@ def _summarize_container(raw: dict) -> OpenAIContainerSummary:
     response_model = ListOpenAIContainersResponse,
 )
 async def list_openai_containers(
-    body: OpenAIContainerRequest,
-    current_subject: str = Depends(get_current_subject),
+    body: OpenAIContainerRequest, current_subject: str = Depends(get_current_subject)
 ) -> ListOpenAIContainersResponse:
     """List the user's OpenAI shell-tool containers."""
     client = _resolve_openai_cloud_client(body)
@@ -2445,8 +2356,7 @@ async def list_openai_containers(
     response_model = OpenAIContainerSummary,
 )
 async def create_openai_container(
-    body: CreateOpenAIContainerBody,
-    current_subject: str = Depends(get_current_subject),
+    body: CreateOpenAIContainerBody, current_subject: str = Depends(get_current_subject)
 ) -> OpenAIContainerSummary:
     """Create a named container with the user-chosen idle TTL."""
     client = _resolve_openai_cloud_client(body)
@@ -2482,8 +2392,7 @@ async def create_openai_container(
 
 @router.post("/external/openai/containers/delete", status_code = 204)
 async def delete_openai_container(
-    body: DeleteOpenAIContainerBody,
-    current_subject: str = Depends(get_current_subject),
+    body: DeleteOpenAIContainerBody, current_subject: str = Depends(get_current_subject)
 ) -> None:
     """Delete a named container by id."""
     logger.info(
@@ -2671,9 +2580,7 @@ async def openai_chat_completions(
                             id = completion_id,
                             created = created,
                             model = model_name,
-                            choices = [
-                                ChunkChoice(delta = ChoiceDelta(), finish_reason = "stop")
-                            ],
+                            choices = [ChunkChoice(delta = ChoiceDelta(), finish_reason = "stop")],
                         )
                         yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
                         yield "data: [DONE]\n\n"
@@ -2681,9 +2588,7 @@ async def openai_chat_completions(
                         cancel_event.set()
                         raise
                     except Exception as e:
-                        logger.error(
-                            f"Error during audio input streaming: {e}", exc_info = True
-                        )
+                        logger.error(f"Error during audio input streaming: {e}", exc_info = True)
                         yield f"data: {json.dumps({'error': {'message': _friendly_error(e), 'type': 'server_error'}})}\n\n"
                     finally:
                         _tracker.__exit__(None, None, None)
@@ -2783,9 +2688,7 @@ async def openai_chat_completions(
         )
 
     # ── Parse messages (handles multimodal content parts) ─────
-    system_prompt, chat_messages, extracted_image_b64 = _extract_content_parts(
-        payload.messages
-    )
+    system_prompt, chat_messages, extracted_image_b64 = _extract_content_parts(payload.messages)
 
     if not chat_messages:
         raise HTTPException(
@@ -2835,9 +2738,7 @@ async def openai_chat_completions(
                 tools_to_use = []
             elif payload.enabled_tools is not None:
                 tools_to_use = [
-                    t
-                    for t in ALL_TOOLS
-                    if t["function"]["name"] in payload.enabled_tools
+                    t for t in ALL_TOOLS if t["function"]["name"] in payload.enabled_tools
                 ]
             else:
                 tools_to_use = ALL_TOOLS
@@ -2901,8 +2802,7 @@ async def openai_chat_completions(
                 _nudge = (
                     _date_line + " "
                     "You have access to tools. When appropriate, prefer using "
-                    "tools rather than answering from memory. "
-                    + " ".join(_tool_tip_parts)
+                    "tools rather than answering from memory. " + " ".join(_tool_tip_parts)
                 )
             else:
                 _nudge = ""
@@ -2914,15 +2814,11 @@ async def openai_chat_completions(
                     system_prompt = system_prompt.rstrip() + "\n\n" + _nudge
                 else:
                     system_prompt = _nudge
-                gguf_messages = _set_or_prepend_system_message(
-                    gguf_messages, system_prompt
-                )
+                gguf_messages = _set_or_prepend_system_message(gguf_messages, system_prompt)
 
             # ── Strip stale tool-call XML from conversation history ─
             for _msg in gguf_messages:
-                if _msg.get("role") == "assistant" and isinstance(
-                    _msg.get("content"), str
-                ):
+                if _msg.get("role") == "assistant" and isinstance(_msg.get("content"), str):
                     _msg["content"] = _TOOL_XML_RE.sub("", _msg["content"]).strip()
 
             def gguf_generate_with_tools():
@@ -3058,9 +2954,7 @@ async def openai_chat_completions(
                     if _stream_usage or _stream_timings:
                         usage_obj = CompletionUsage(
                             prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
-                            completion_tokens = (_stream_usage or {}).get(
-                                "completion_tokens", 0
-                            ),
+                            completion_tokens = (_stream_usage or {}).get("completion_tokens", 0),
                             total_tokens = (_stream_usage or {}).get("total_tokens", 0),
                         )
                         usage_chunk = ChatCompletionChunk(
@@ -3167,11 +3061,7 @@ async def openai_chat_completions(
                             else:
                                 logger.warning(
                                     "gguf_stream_chunks: unexpected dict event: %s",
-                                    {
-                                        k: v
-                                        for k, v in cumulative.items()
-                                        if k != "timings"
-                                    },
+                                    {k: v for k, v in cumulative.items() if k != "timings"},
                                 )
                             continue
                         new_text = cumulative[len(prev_text) :]
@@ -3208,9 +3098,7 @@ async def openai_chat_completions(
                     if _stream_usage or _stream_timings:
                         usage_obj = CompletionUsage(
                             prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
-                            completion_tokens = (_stream_usage or {}).get(
-                                "completion_tokens", 0
-                            ),
+                            completion_tokens = (_stream_usage or {}).get("completion_tokens", 0),
                             total_tokens = (_stream_usage or {}).get("total_tokens", 0),
                         )
                         usage_chunk = ChatCompletionChunk(
@@ -3270,12 +3158,8 @@ async def openai_chat_completions(
                         )
                     ],
                     usage = CompletionUsage(
-                        prompt_tokens = (completion_usage or {}).get("prompt_tokens")
-                        or 0,
-                        completion_tokens = (completion_usage or {}).get(
-                            "completion_tokens"
-                        )
-                        or 0,
+                        prompt_tokens = (completion_usage or {}).get("prompt_tokens") or 0,
+                        completion_tokens = (completion_usage or {}).get("completion_tokens") or 0,
                         total_tokens = (completion_usage or {}).get("total_tokens") or 0,
                     ),
                 )
@@ -3335,16 +3219,12 @@ async def openai_chat_completions(
     # XML -- gpt-oss tools still work via the GGUF path).
     _sf_is_gptoss = False
     try:
-        _sf_is_gptoss = bool(
-            hasattr(backend, "_is_gpt_oss_model") and backend._is_gpt_oss_model()
-        )
+        _sf_is_gptoss = bool(hasattr(backend, "_is_gpt_oss_model") and backend._is_gpt_oss_model())
     except Exception:
         _sf_is_gptoss = False
 
     _sf_tool_budget = (
-        payload.max_tool_calls_per_message
-        if payload.max_tool_calls_per_message is not None
-        else 25
+        payload.max_tool_calls_per_message if payload.max_tool_calls_per_message is not None else 25
     )
 
     # Match the GGUF path: mcp_enabled also opens the tool loop on its own
@@ -3426,8 +3306,7 @@ async def openai_chat_completions(
             _sf_nudge = (
                 _sf_date_line + " "
                 "You have access to tools. When appropriate, prefer using "
-                "tools rather than answering from memory. "
-                + " ".join(_sf_tool_tip_parts)
+                "tools rather than answering from memory. " + " ".join(_sf_tool_tip_parts)
             )
         else:
             _sf_nudge = ""
@@ -3940,9 +3819,7 @@ async def serve_sandbox_file(
 
 
 @router.get("/models")
-async def openai_list_models(
-    current_subject: str = Depends(get_current_subject),
-):
+async def openai_list_models(current_subject: str = Depends(get_current_subject)):
     """
     OpenAI-compatible model listing endpoint.
 
@@ -3982,10 +3859,7 @@ async def openai_list_models(
 
 
 @router.post("/completions")
-async def openai_completions(
-    request: Request,
-    current_subject: str = Depends(get_current_subject),
-):
+async def openai_completions(request: Request, current_subject: str = Depends(get_current_subject)):
     """
     OpenAI-compatible text completions endpoint (non-chat).
 
@@ -4059,10 +3933,7 @@ async def openai_completions(
 
 
 @router.post("/embeddings")
-async def openai_embeddings(
-    request: Request,
-    current_subject: str = Depends(get_current_subject),
-):
+async def openai_embeddings(request: Request, current_subject: str = Depends(get_current_subject)):
     """
     OpenAI-compatible embeddings endpoint.
 
@@ -4095,9 +3966,7 @@ async def openai_embeddings(
 # =====================================================================
 
 
-def _translate_responses_tools_to_chat(
-    tools: Optional[list[dict]],
-) -> Optional[list[dict]]:
+def _translate_responses_tools_to_chat(tools: Optional[list[dict]]) -> Optional[list[dict]]:
     """Translate Responses-shape function tools to the Chat Completions nested shape.
 
     Responses uses a flat shape per tool entry::
@@ -4371,9 +4240,7 @@ def _chat_tool_calls_to_responses_output(tool_calls: list[dict]) -> list[dict]:
 
 
 async def _responses_non_streaming(
-    payload: ResponsesRequest,
-    messages: list[ChatMessage],
-    request: Request,
+    payload: ResponsesRequest, messages: list[ChatMessage], request: Request
 ) -> JSONResponse:
     """Handle a non-streaming Responses API call."""
     chat_req = _build_chat_request(payload, messages, stream = False)
@@ -4439,9 +4306,7 @@ async def _responses_non_streaming(
 
 
 async def _responses_stream(
-    payload: ResponsesRequest,
-    messages: list[ChatMessage],
-    request: Request,
+    payload: ResponsesRequest, messages: list[ChatMessage], request: Request
 ):
     """Handle a streaming Responses API call, emitting named SSE events.
 
@@ -4491,8 +4356,7 @@ async def _responses_stream(
 
     # Direct pass-through bypasses the openai_chat_completions image gate.
     if not llama_backend.is_vision and any(
-        isinstance(m.content, list)
-        and any(isinstance(p, ImageContentPart) for p in m.content)
+        isinstance(m.content, list) and any(isinstance(p, ImageContentPart) for p in m.content)
         for m in messages
     ):
         raise HTTPException(
@@ -4500,9 +4364,7 @@ async def _responses_stream(
             detail = "Image provided but current GGUF model does not support vision.",
         )
 
-    body = _build_openai_passthrough_body(
-        chat_req, backend_ctx = llama_backend.context_length
-    )
+    body = _build_openai_passthrough_body(chat_req, backend_ctx = llama_backend.context_length)
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
 
     async def event_generator():
@@ -4861,9 +4723,7 @@ def _anthropic_requested_studio_tools(tools: Optional[list]) -> set[str]:
 
 
 def _select_anthropic_server_tools(
-    all_tools: list[dict],
-    requested_studio_tools: set[str],
-    enabled_tools: Optional[list[str]],
+    all_tools: list[dict], requested_studio_tools: set[str], enabled_tools: Optional[list[str]]
 ) -> list[dict]:
     """Select Studio tools requested through Anthropic tools and extensions."""
     if not requested_studio_tools and enabled_tools is None:
@@ -4876,9 +4736,7 @@ def _select_anthropic_server_tools(
     return [tool for tool in all_tools if tool["function"]["name"] in selected_names]
 
 
-def _normalize_anthropic_openai_images(
-    openai_messages: list[dict], is_vision: bool
-) -> bool:
+def _normalize_anthropic_openai_images(openai_messages: list[dict], is_vision: bool) -> bool:
     """Enforce the vision guard on translated Anthropic messages and
     normalize any ``image_url`` parts with base64 data URLs to PNG.
 
@@ -4991,9 +4849,7 @@ async def anthropic_messages(
 
     # Enforce vision guard + re-encode embedded images to PNG so the
     # Anthropic endpoint matches the behavior of /v1/chat/completions.
-    _has_image = _normalize_anthropic_openai_images(
-        openai_messages, llama_backend.is_vision
-    )
+    _has_image = _normalize_anthropic_openai_images(openai_messages, llama_backend.is_vision)
 
     temperature = payload.temperature if payload.temperature is not None else 0.6
     top_p = payload.top_p if payload.top_p is not None else 0.95
@@ -5002,9 +4858,7 @@ async def anthropic_messages(
     repetition_penalty = (
         payload.repetition_penalty if payload.repetition_penalty is not None else 1.0
     )
-    presence_penalty = (
-        payload.presence_penalty if payload.presence_penalty is not None else 0.0
-    )
+    presence_penalty = payload.presence_penalty if payload.presence_penalty is not None else 0.0
     stop = payload.stop_sequences or None
 
     # Translate Anthropic tool_choice to OpenAI format for forwarding to
@@ -5083,9 +4937,7 @@ async def anthropic_messages(
         and not _has_image
     )
     client_tools = (
-        not server_tools
-        and len(openai_client_tools) > 0
-        and llama_backend.supports_tools
+        not server_tools and len(openai_client_tools) > 0 and llama_backend.supports_tools
     )
 
     # ── Client-side pass-through path ─────────────────────────
@@ -5265,13 +5117,7 @@ async def anthropic_messages(
     )
 
 
-async def _anthropic_tool_stream(
-    request,
-    cancel_event,
-    run_gen,
-    message_id,
-    model_name,
-):
+async def _anthropic_tool_stream(request, cancel_event, run_gen, message_id, model_name):
     """Streaming response for the tool-calling path."""
     _sentinel = object()
 
@@ -5312,13 +5158,7 @@ async def _anthropic_tool_stream(
     )
 
 
-async def _anthropic_plain_stream(
-    request,
-    cancel_event,
-    run_gen,
-    message_id,
-    model_name,
-):
+async def _anthropic_plain_stream(request, cancel_event, run_gen, message_id, model_name):
     """Streaming response for the no-tool path."""
     _sentinel = object()
 
@@ -5388,18 +5228,14 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
             new = clean[len(prev_text) :]
             prev_text = clean
             if new:
-                if content_blocks and isinstance(
-                    content_blocks[-1], AnthropicResponseTextBlock
-                ):
+                if content_blocks and isinstance(content_blocks[-1], AnthropicResponseTextBlock):
                     content_blocks[-1].text += new
                 else:
                     content_blocks.append(AnthropicResponseTextBlock(text = new))
         elif etype == "tool_start":
             tool_call_id = event["tool_call_id"]
             arguments = event.get("arguments", {})
-            existing_tool_block = (
-                tool_blocks_by_id.get(tool_call_id) if tool_call_id else None
-            )
+            existing_tool_block = tool_blocks_by_id.get(tool_call_id) if tool_call_id else None
             if existing_tool_block is not None:
                 if arguments or not existing_tool_block.input:
                     existing_tool_block.input = arguments
@@ -5500,9 +5336,7 @@ def _build_passthrough_payload(
     if stream:
         body["stream_options"] = {"include_usage": True}
     body["max_tokens"] = (
-        max_tokens
-        if max_tokens is not None
-        else (backend_ctx or _DEFAULT_MAX_TOKENS_FLOOR)
+        max_tokens if max_tokens is not None else (backend_ctx or _DEFAULT_MAX_TOKENS_FLOOR)
     )
     body["t_max_predict_ms"] = _DEFAULT_T_MAX_PREDICT_MS
     if stop:
@@ -5619,9 +5453,7 @@ async def _anthropic_passthrough_stream(
             # blocks during llama-server prefill, so the in-loop cancel
             # check is unreachable until the first SSE chunk arrives.
             # The watcher closes `resp` on cancel, raising in aiter_lines.
-            cancel_watcher = asyncio.create_task(
-                _await_cancel_then_close(cancel_event, resp)
-            )
+            cancel_watcher = asyncio.create_task(_await_cancel_then_close(cancel_event, resp))
             lines_iter = resp.aiter_lines()
             async for raw_line in lines_iter:
                 if cancel_event.is_set():
@@ -5855,9 +5687,7 @@ def _strip_provider_synthetic_tool_history(messages: list[dict]) -> list[dict]:
                     if args_obj.get("_server_tool") is True:
                         is_synthetic = True
                     google = args_obj.get("google")
-                    if isinstance(google, dict) and isinstance(
-                        google.get("native_part"), dict
-                    ):
+                    if isinstance(google, dict) and isinstance(google.get("native_part"), dict):
                         is_synthetic = True
                 if is_synthetic:
                     tc_id = tc.get("id")
@@ -5912,9 +5742,7 @@ def _openai_messages_for_passthrough(payload) -> list[dict]:
     transparently.
     """
     messages = _strip_provider_synthetic_tool_history(
-        _drop_empty_assistant_sentinels(
-            [m.model_dump(exclude_none = True) for m in payload.messages]
-        )
+        _drop_empty_assistant_sentinels([m.model_dump(exclude_none = True) for m in payload.messages])
     )
 
     if not payload.image_base64:
@@ -5964,9 +5792,7 @@ def _openai_messages_for_gguf_chat(payload, is_vision: bool) -> tuple[list[dict]
     image attached to its original turn.
     """
     messages = _strip_provider_synthetic_tool_history(
-        _drop_empty_assistant_sentinels(
-            [m.model_dump(exclude_none = True) for m in payload.messages]
-        )
+        _drop_empty_assistant_sentinels([m.model_dump(exclude_none = True) for m in payload.messages])
     )
     has_message_image = any(
         isinstance(msg.get("content"), list)
@@ -6048,12 +5874,7 @@ def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
 
 
 async def _openai_passthrough_stream(
-    request,
-    cancel_event,
-    llama_backend,
-    payload,
-    model_name,
-    completion_id,
+    request, cancel_event, llama_backend, payload, model_name, completion_id
 ):
     """Streaming client-side pass-through for /v1/chat/completions.
 
@@ -6064,9 +5885,7 @@ async def _openai_passthrough_stream(
     observes a standard OpenAI response.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
-    body = _build_openai_passthrough_body(
-        payload, backend_ctx = llama_backend.context_length
-    )
+    body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
 
     _cancel_keys = (payload.cancel_id, payload.session_id, completion_id)
     _tracker = _TrackedCancel(cancel_event, *_cancel_keys)
@@ -6139,9 +5958,7 @@ async def _openai_passthrough_stream(
             # tiny watcher that closes `resp` as soon as cancel fires,
             # unblocking the iterator with a RemoteProtocolError caught
             # in the except clause below.
-            cancel_watcher = asyncio.create_task(
-                _await_cancel_then_close(cancel_event, resp)
-            )
+            cancel_watcher = asyncio.create_task(_await_cancel_then_close(cancel_event, resp))
             try:
                 lines_iter = resp.aiter_lines()
                 async for raw_line in lines_iter:
@@ -6209,11 +6026,7 @@ async def _openai_passthrough_stream(
         raise
 
 
-async def _openai_passthrough_non_streaming(
-    llama_backend,
-    payload,
-    model_name,
-):
+async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
     """Non-streaming client-side pass-through for /v1/chat/completions.
 
     Returns llama-server's JSON response verbatim (via JSONResponse) so the
@@ -6222,9 +6035,7 @@ async def _openai_passthrough_non_streaming(
     token counts.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
-    body = _build_openai_passthrough_body(
-        payload, backend_ctx = llama_backend.context_length
-    )
+    body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
 
     try:
         async with httpx.AsyncClient() as client:
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 87cdcf9402..bf8550f583 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -112,16 +112,13 @@ def _row_to_response(row: dict) -> McpServerResponse:
 
 
 @router.get("/", response_model = list[McpServerResponse])
-async def list_mcp_servers(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_mcp_servers(current_subject: str = Depends(get_current_subject)):
     return [_row_to_response(row) for row in mcp_servers_db.list_servers()]
 
 
 @router.post("/", response_model = McpServerResponse, status_code = 201)
 async def create_mcp_server(
-    payload: McpServerCreate,
-    current_subject: str = Depends(get_current_subject),
+    payload: McpServerCreate, current_subject: str = Depends(get_current_subject)
 ):
     display_name = (payload.display_name or "").strip()
     if not display_name:
@@ -151,9 +148,7 @@ def _changes_from_payload(payload: McpServerUpdate) -> dict:
     if "display_name" in sent:
         name = (payload.display_name or "").strip()
         if not name:
-            raise HTTPException(
-                status_code = 400, detail = "display_name must not be empty"
-            )
+            raise HTTPException(status_code = 400, detail = "display_name must not be empty")
         changes["display_name"] = name
     if "url" in sent:
         changes["url"] = _validate_url(payload.url or "")
@@ -162,15 +157,11 @@ def _changes_from_payload(payload: McpServerUpdate) -> dict:
         changes["headers_json"] = json.dumps(headers) if headers else None
     if "is_enabled" in sent:
         if payload.is_enabled is None:
-            raise HTTPException(
-                status_code = 400, detail = "is_enabled must be true or false"
-            )
+            raise HTTPException(status_code = 400, detail = "is_enabled must be true or false")
         changes["is_enabled"] = payload.is_enabled
     if "use_oauth" in sent:
         if payload.use_oauth is None:
-            raise HTTPException(
-                status_code = 400, detail = "use_oauth must be true or false"
-            )
+            raise HTTPException(status_code = 400, detail = "use_oauth must be true or false")
         changes["use_oauth"] = payload.use_oauth
     # stdio is OAuth-less: drop a stale OAuth flag when switching to a command.
     if "url" in changes and is_stdio(changes["url"]):
@@ -203,8 +194,7 @@ async def update_mcp_server(
     # disabled; fastmcp keys tokens by URL and would otherwise let a
     # re-pointed server silently inherit the old account's credentials.
     if bool(old.get("use_oauth")) and (
-        ("url" in changes and changes["url"] != old["url"])
-        or changes.get("use_oauth") is False
+        ("url" in changes and changes["url"] != old["url"]) or changes.get("use_oauth") is False
     ):
         await clear_oauth_tokens_async(old["url"])
     mcp_servers_db.update_server(server_id, changes)
@@ -212,10 +202,7 @@ async def update_mcp_server(
 
 
 @router.delete("/{server_id}", status_code = 204)
-async def delete_mcp_server(
-    server_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def delete_mcp_server(server_id: str, current_subject: str = Depends(get_current_subject)):
     old = mcp_servers_db.get_server(server_id)
     if not old:
         raise HTTPException(status_code = 404, detail = "MCP server not found")
@@ -226,8 +213,7 @@ async def delete_mcp_server(
 
 @router.post("/{server_id}/refresh", response_model = McpServerProbeResult)
 async def refresh_mcp_server_tools(
-    server_id: str,
-    current_subject: str = Depends(get_current_subject),
+    server_id: str, current_subject: str = Depends(get_current_subject)
 ):
     server = mcp_servers_db.get_server(server_id)
     if not server:
@@ -235,9 +221,7 @@ async def refresh_mcp_server_tools(
     # Refresh uses the stored address, so re-check the stdio gate here too: a
     # stdio row from a desktop DB must not spawn on a hosted/network host.
     if is_stdio(server["url"]) and not stdio_mcp_enabled():
-        raise HTTPException(
-            status_code = 400, detail = "stdio MCP servers are disabled on this host"
-        )
+        raise HTTPException(status_code = 400, detail = "stdio MCP servers are disabled on this host")
 
     use_oauth = bool(server.get("use_oauth"))
     try:
@@ -261,8 +245,7 @@ async def refresh_mcp_server_tools(
 
 @router.post("/test", response_model = McpServerProbeResult)
 async def test_mcp_server(
-    payload: McpServerTestRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: McpServerTestRequest, current_subject: str = Depends(get_current_subject)
 ):
     # URL/header validation must surface as 400 like create/update so the
     # frontend's create-form pre-flight gets the same error semantics as
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 0e1e491998..3871f579af 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -141,7 +141,9 @@ logger = get_logger(__name__)
 
 
 def derive_model_type(
-    is_vision: bool, audio_type: Optional[str], is_embedding: bool = False
+    is_vision: bool,
+    audio_type: Optional[str],
+    is_embedding: bool = False,
 ) -> ModelType:
     """Collapse individual capability flags into a single model modality string."""
     if is_embedding:
@@ -157,7 +159,6 @@ def _resolve_hf_cache_dir() -> Path:
     """Resolve local HF cache root used by hub downloads."""
     try:
         from huggingface_hub.constants import HF_HUB_CACHE
-
         return Path(HF_HUB_CACHE)
     except Exception:
         return Path.home() / ".cache" / "huggingface" / "hub"
@@ -194,9 +195,7 @@ def _is_model_directory(d: Path) -> bool:
         return False
 
     try:
-        has_config = (d / "config.json").exists() or (
-            d / "adapter_config.json"
-        ).exists()
+        has_config = (d / "config.json").exists() or (d / "adapter_config.json").exists()
         if not has_config:
             return False
         return any(_is_weight_file(f) for f in d.iterdir() if f.is_file())
@@ -204,11 +203,7 @@ def _is_model_directory(d: Path) -> bool:
         return False
 
 
-def _scan_models_dir(
-    models_dir: Path,
-    *,
-    limit: int | None = None,
-) -> List[LocalModelInfo]:
+def _scan_models_dir(models_dir: Path, *, limit: int | None = None) -> List[LocalModelInfo]:
     if not models_dir.exists() or not models_dir.is_dir():
         return []
 
@@ -449,8 +444,7 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
         return primary
     except OSError as e:
         logger.debug(
-            "Ollama dir %s not writable for .studio_links (%s); "
-            "falling back to Studio cache",
+            "Ollama dir %s not writable for .studio_links (%s); falling back to Studio cache",
             ollama_dir,
             e,
         )
@@ -475,9 +469,7 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
         return None
 
 
-def _scan_ollama_dir(
-    ollama_dir: Path, limit: Optional[int] = None
-) -> List[LocalModelInfo]:
+def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[LocalModelInfo]:
     """Scan an Ollama models directory for downloaded models.
 
     Ollama stores models in a content-addressable layout::
@@ -571,9 +563,7 @@ def _scan_ollama_dir(
                 if tmp_path.is_symlink() or tmp_path.exists():
                     tmp_path.unlink()
             except OSError as cleanup_err:
-                logger.debug(
-                    "Could not clean up tmp path %s: %s", tmp_path, cleanup_err
-                )
+                logger.debug("Could not clean up tmp path %s: %s", tmp_path, cleanup_err)
             return None
 
     try:
@@ -590,11 +580,7 @@ def _scan_ollama_dir(
             repo_parts = list(parts[1:-1])
             tag = parts[-1]
 
-            if (
-                host == "registry.ollama.ai"
-                and repo_parts
-                and repo_parts[0] == "library"
-            ):
+            if host == "registry.ollama.ai" and repo_parts and repo_parts[0] == "library":
                 repo_name = "/".join(repo_parts[1:])
             elif host == "registry.ollama.ai":
                 repo_name = "/".join(repo_parts)
@@ -651,9 +637,7 @@ def _scan_ollama_dir(
                     candidate = blobs_dir / digest.replace(":", "-")
                     if candidate.is_file():
                         link_name = f"{safe_name}-{tag}{quant}.gguf"
-                        gguf_link_path = _make_link(
-                            model_link_dir, link_name, candidate
-                        )
+                        gguf_link_path = _make_link(model_link_dir, link_name, candidate)
 
                 elif media == "application/vnd.ollama.image.projector":
                     candidate = blobs_dir / digest.replace(":", "-")
@@ -726,7 +710,6 @@ async def list_local_models(
         allowed_roots.append(hf_default)
     try:
         from utils.paths import studio_root, outputs_root
-
         allowed_roots.extend([studio_root(), outputs_root()])
     except Exception:
         pass
@@ -785,10 +768,7 @@ async def list_local_models(
                         + _scan_hf_cache(folder_path)
                         + _scan_lmstudio_dir(folder_path)
                     )
-                    if not any(
-                        p in (".studio_links", "ollama_links")
-                        for p in Path(m.path).parts
-                    )
+                    if not any(p in (".studio_links", "ollama_links") for p in Path(m.path).parts)
                 ]
                 custom_models = _generic
                 if len(custom_models) < _MAX_MODELS_PER_FOLDER:
@@ -799,9 +779,7 @@ async def list_local_models(
             except OSError as e:
                 logger.warning("Skipping unreadable scan folder %s: %s", folder_path, e)
                 continue
-            local_models += [
-                m.model_copy(update = {"source": "custom"}) for m in custom_models
-            ]
+            local_models += [m.model_copy(update = {"source": "custom"}) for m in custom_models]
 
         # Deduplicate models, but always keep custom folder entries so they
         # appear in the "Custom Folders" UI section even when the same model
@@ -836,19 +814,15 @@ async def list_local_models(
 
 
 @router.get("/scan-folders")
-async def get_scan_folders(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_scan_folders(current_subject: str = Depends(get_current_subject)):
     """List all registered custom model scan folders."""
     from storage.studio_db import list_scan_folders
-
     return {"folders": list_scan_folders()}
 
 
 @router.post("/scan-folders", response_model = ScanFolderInfo, status_code = 201)
 async def add_scan_folder_endpoint(
-    body: AddScanFolderRequest,
-    current_subject: str = Depends(get_current_subject),
+    body: AddScanFolderRequest, current_subject: str = Depends(get_current_subject)
 ):
     """Register a new directory to scan for local models."""
     from storage.studio_db import add_scan_folder
@@ -867,8 +841,7 @@ async def add_scan_folder_endpoint(
 
 @router.delete("/scan-folders/{folder_id}")
 async def remove_scan_folder_endpoint(
-    folder_id: int,
-    current_subject: str = Depends(get_current_subject),
+    folder_id: int, current_subject: str = Depends(get_current_subject)
 ):
     """Remove a registered custom scan folder."""
     from storage.studio_db import remove_scan_folder
@@ -879,9 +852,7 @@ async def remove_scan_folder_endpoint(
 
 
 @router.get("/recommended-folders")
-async def get_recommended_folders(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_recommended_folders(current_subject: str = Depends(get_current_subject)):
     """Return well-known model directories that exist on this machine.
 
     Lightweight alternative to ``browse-folders`` for showing quick-pick
@@ -1191,9 +1162,7 @@ def _match_browse_child(current: Path, name: str) -> Optional[Path]:
             detail = f"Permission denied reading {current.name}",
         ) from None
     except OSError as exc:
-        logger.warning(
-            "browse-folders: could not read %s: %s", current, exc, exc_info = True
-        )
+        logger.warning("browse-folders: could not read %s: %s", current, exc, exc_info = True)
         raise HTTPException(
             status_code = 500,
             detail = f"Could not read {os.path.basename(str(current))}",
@@ -1344,9 +1313,7 @@ async def browse_folders(
             detail = f"Permission denied reading {os.path.basename(str(target))}",
         )
     except OSError as exc:
-        logger.warning(
-            "browse-folders: could not read %s: %s", target, exc, exc_info = True
-        )
+        logger.warning("browse-folders: could not read %s: %s", target, exc, exc_info = True)
         raise HTTPException(
             status_code = 500,
             detail = f"Could not read {os.path.basename(str(target))}",
@@ -1404,9 +1371,7 @@ async def browse_folders(
     # would 403 on click. Users can still hop to other allowed roots
     # via the suggestion chips below.
     parent: Optional[str]
-    if target.parent == target or not _is_path_inside_allowlist(
-        target.parent, allowed_roots
-    ):
+    if target.parent == target or not _is_path_inside_allowlist(target.parent, allowed_roots):
         parent = None
     else:
         parent = str(target.parent)
@@ -1475,9 +1440,7 @@ def _looks_like_mlx_repo(model_id: str) -> bool:
 
 
 @router.get("/list")
-async def list_models(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_models(current_subject: str = Depends(get_current_subject)):
     """
     List available models (default models and loaded models).
 
@@ -1565,16 +1528,12 @@ def _get_max_position_embeddings(config) -> Optional[int]:
     """Extract max_position_embeddings from a model config, checking text_config fallback."""
     if hasattr(config, "max_position_embeddings"):
         return config.max_position_embeddings
-    if hasattr(config, "text_config") and hasattr(
-        config.text_config, "max_position_embeddings"
-    ):
+    if hasattr(config, "text_config") and hasattr(config.text_config, "max_position_embeddings"):
         return config.text_config.max_position_embeddings
     return None
 
 
-def _get_model_size_bytes(
-    model_name: str, hf_token: Optional[str] = None
-) -> Optional[int]:
+def _get_model_size_bytes(model_name: str, hf_token: Optional[str] = None) -> Optional[int]:
     """Get total size of model weight files from HF Hub."""
     try:
         from huggingface_hub import HfApi
@@ -1587,9 +1546,7 @@ def _get_model_size_bytes(
         weight_exts = (".safetensors", ".bin", ".pt", ".pth", ".gguf")
         total = 0
         for sibling in info.siblings:
-            if sibling.rfilename and any(
-                sibling.rfilename.endswith(ext) for ext in weight_exts
-            ):
+            if sibling.rfilename and any(sibling.rfilename.endswith(ext) for ext in weight_exts):
                 if sibling.size is not None:
                     total += sibling.size
 
@@ -1777,15 +1734,10 @@ def _loaded_model_matches_deleted_path(active_model: str, deleted_path: Path) ->
         )
         active_lower = active_model.lower()
         target_lower = str(deleted_path).lower()
-        return active_lower == target_lower or active_lower.startswith(
-            f"{target_lower}{os.sep}"
-        )
+        return active_lower == target_lower or active_lower.startswith(f"{target_lower}{os.sep}")
 
 
-def _loading_model_matches_deleted_path(
-    loading_model: object,
-    deleted_path: Path,
-) -> bool:
+def _loading_model_matches_deleted_path(loading_model: object, deleted_path: Path) -> bool:
     if not loading_model:
         return False
     return _loaded_model_matches_deleted_path(str(loading_model), deleted_path)
@@ -1918,7 +1870,6 @@ async def delete_finetuned_model(
     if source == "training":
         try:
             from core.training import get_training_backend
-
             training_backend = get_training_backend()
             if training_backend.is_training_active():
                 raise HTTPException(
@@ -2005,9 +1956,7 @@ async def delete_finetuned_model(
     except HTTPException:
         raise
     except Exception as e:
-        logger.warning(
-            "Could not check inference backend loaded model before delete: %s", e
-        )
+        logger.warning("Could not check inference backend loaded model before delete: %s", e)
         raise HTTPException(
             status_code = 503,
             detail = "Could not verify model load status before deleting",
@@ -2079,10 +2028,7 @@ async def delete_finetuned_model(
 
 
 @router.get("/loras/{lora_path:path}/base-model", response_model = LoRABaseModelResponse)
-async def get_lora_base_model(
-    lora_path: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_lora_base_model(lora_path: str, current_subject: str = Depends(get_current_subject)):
     """
     Get the base model for a LoRA adapter.
 
@@ -2115,10 +2061,7 @@ async def get_lora_base_model(
 
 
 @router.get("/check-vision/{model_name:path}", response_model = VisionCheckResponse)
-async def check_vision_model(
-    model_name: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def check_vision_model(model_name: str, current_subject: str = Depends(get_current_subject)):
     """
     Check if a model is a vision model.
 
@@ -2159,9 +2102,7 @@ async def check_embedding_model(
         logger.info(f"Checking if embedding model: {model_name}")
         is_embedding = is_embedding_model(model_name, hf_token = hf_token)
 
-        logger.info(
-            f"Embedding check result for {model_name}: is_embedding={is_embedding}"
-        )
+        logger.info(f"Embedding check result for {model_name}: is_embedding={is_embedding}")
         return EmbeddingCheckResponse(
             model_name = model_name,
             is_embedding = is_embedding,
@@ -2182,9 +2123,7 @@ async def get_gguf_variants(
     repo_id: str = Query(
         ..., description = "HuggingFace repo ID (e.g. 'unsloth/gemma-3-4b-it-GGUF')"
     ),
-    hf_token: Optional[str] = Query(
-        None, description = "HuggingFace token for private repos"
-    ),
+    hf_token: Optional[str] = Query(None, description = "HuggingFace token for private repos"),
     current_subject: str = Depends(get_current_subject),
 ):
     """
@@ -2333,11 +2272,7 @@ async def get_gguf_download_progress(
                 break
 
         total_progress_bytes = downloaded_bytes + in_progress_bytes
-        progress = (
-            min(total_progress_bytes / expected_bytes, 0.99)
-            if expected_bytes > 0
-            else 0
-        )
+        progress = min(total_progress_bytes / expected_bytes, 0.99) if expected_bytes > 0 else 0
         # Only report 1.0 when all bytes are in completed files (not in-progress)
         if expected_bytes > 0 and downloaded_bytes >= expected_bytes:
             progress = 1.0
@@ -2480,7 +2415,6 @@ def _all_hf_cache_scans():
     try:
         # Resolve the active cache dir so we can dedup
         from huggingface_hub.constants import HF_HUB_CACHE
-
         seen.add(str(Path(HF_HUB_CACHE).resolve()))
     except Exception:
         pass
@@ -2553,9 +2487,7 @@ def _repo_has_gguf_files(repo_info) -> bool:
 
 
 @router.get("/cached-gguf")
-async def list_cached_gguf(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_cached_gguf(current_subject: str = Depends(get_current_subject)):
     """List GGUF repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
     try:
         cache_scans = _all_hf_cache_scans()
@@ -2590,9 +2522,7 @@ async def list_cached_gguf(
 
 
 @router.get("/cached-models")
-async def list_cached_models(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_cached_models(current_subject: str = Depends(get_current_subject)):
     """List non-GGUF model repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
     _WEIGHT_EXTENSIONS = (".safetensors", ".bin")
 
@@ -2609,9 +2539,7 @@ async def list_cached_models(
                     if _repo_has_gguf_files(repo_info):
                         continue
                     total_size = sum(
-                        (f.size_on_disk or 0)
-                        for rev in repo_info.revisions
-                        for f in rev.files
+                        (f.size_on_disk or 0) for rev in repo_info.revisions for f in rev.files
                     )
                     if total_size == 0:
                         continue
@@ -2658,7 +2586,6 @@ async def delete_cached_model(
     # Check if model is currently loaded
     try:
         from routes.inference import get_llama_cpp_backend
-
         llama_backend = get_llama_cpp_backend()
         if llama_backend.is_loaded and llama_backend.model_identifier:
             loaded_id = llama_backend.model_identifier.lower()
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index 4eaa007750..5dd7038330 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -51,9 +51,7 @@ router = APIRouter()
 
 
 @router.get("/public-key")
-async def get_public_key(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_public_key(current_subject: str = Depends(get_current_subject)):
     """Return the RSA public key PEM for client-side API key encryption.
 
     The ``fingerprint`` field is a short SHA256 of the PEM and is meant
@@ -72,9 +70,7 @@ async def get_public_key(
 
 
 @router.get("/registry", response_model = list[ProviderRegistryEntry])
-async def list_registry(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_registry(current_subject: str = Depends(get_current_subject)):
     """List all supported provider types with their default configurations."""
     return list_available_providers()
 
@@ -83,9 +79,7 @@ async def list_registry(
 
 
 @router.get("/pricing")
-async def get_pricing_snapshot(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_pricing_snapshot(current_subject: str = Depends(get_current_subject)):
     """Static per-MTok pricing table the frontend uses to convert
     upstream usage chunks into a per-turn USD cost. See
     ``core/inference/pricing.py`` for sourcing notes; values reflect
@@ -97,9 +91,7 @@ async def get_pricing_snapshot(
 
 
 @router.get("/", response_model = list[ProviderResponse])
-async def list_provider_configs(
-    current_subject: str = Depends(get_current_subject),
-):
+async def list_provider_configs(current_subject: str = Depends(get_current_subject)):
     """List all saved provider configurations."""
     rows = providers_db.list_providers()
     return [
@@ -118,8 +110,7 @@ async def list_provider_configs(
 
 @router.post("/", response_model = ProviderResponse, status_code = 201)
 async def create_provider_config(
-    payload: ProviderCreate,
-    current_subject: str = Depends(get_current_subject),
+    payload: ProviderCreate, current_subject: str = Depends(get_current_subject)
 ):
     """Create a new saved provider configuration (no API key stored)."""
     info = get_provider_info(payload.provider_type)
@@ -186,8 +177,7 @@ async def update_provider_config(
 
 @router.delete("/{provider_id}", status_code = 204)
 async def delete_provider_config(
-    provider_id: str,
-    current_subject: str = Depends(get_current_subject),
+    provider_id: str, current_subject: str = Depends(get_current_subject)
 ):
     """Delete a saved provider configuration."""
     deleted = providers_db.delete_provider(provider_id)
@@ -200,8 +190,7 @@ async def delete_provider_config(
 
 @router.post("/test", response_model = ProviderTestResult)
 async def test_provider(
-    payload: ProviderTestRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: ProviderTestRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Test connectivity to an external provider.
@@ -221,9 +210,7 @@ async def test_provider(
         try:
             api_key = decrypt_api_key(payload.encrypted_api_key)
         except Exception as exc:
-            logger.warning(
-                "Failed to decrypt API key (%s): %s", type(exc).__name__, exc
-            )
+            logger.warning("Failed to decrypt API key (%s): %s", type(exc).__name__, exc)
             raise HTTPException(
                 status_code = 400,
                 detail = "Failed to decrypt API key. The public key may have changed — try refreshing the page.",
@@ -275,8 +262,7 @@ async def test_provider(
 
 @router.post("/models", response_model = list[ProviderModelInfo])
 async def list_provider_models(
-    payload: ProviderModelsRequest,
-    current_subject: str = Depends(get_current_subject),
+    payload: ProviderModelsRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     List models available from an external provider.
@@ -295,9 +281,7 @@ async def list_provider_models(
         try:
             api_key = decrypt_api_key(payload.encrypted_api_key)
         except Exception as exc:
-            logger.warning(
-                "Failed to decrypt API key (%s): %s", type(exc).__name__, exc
-            )
+            logger.warning("Failed to decrypt API key (%s): %s", type(exc).__name__, exc)
             raise HTTPException(
                 status_code = 400,
                 detail = "Failed to decrypt API key. The public key may have changed — try refreshing the page.",
@@ -338,7 +322,6 @@ async def list_provider_models(
         if payload.provider_type == "gemini":
             try:
                 from urllib.parse import urlparse as _urlparse
-
                 _host = (_urlparse(base_url).hostname or "").lower()
             except Exception:
                 _host = ""
@@ -349,9 +332,7 @@ async def list_provider_models(
             if allow_prefixes is not None:
                 prefix_tuple = tuple(str(p) for p in allow_prefixes if str(p))
                 if prefix_tuple:
-                    models = [
-                        m for m in models if m.get("id", "").startswith(prefix_tuple)
-                    ]
+                    models = [m for m in models if m.get("id", "").startswith(prefix_tuple)]
             allowlist = info.get("model_id_allowlist")
             if allowlist is not None:
                 models = [m for m in models if allowlist.match(m.get("id", ""))]
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index b6fbeeee7a..94ea4c7b6c 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -45,16 +45,13 @@ def _upload_limit_response(limit_mb: int) -> UploadLimitResponse:
 
 
 @router.get("/upload-limit", response_model = UploadLimitResponse)
-def get_upload_limit(
-    current_subject: str = Depends(get_current_subject),
-) -> UploadLimitResponse:
+def get_upload_limit(current_subject: str = Depends(get_current_subject)) -> UploadLimitResponse:
     return _upload_limit_response(get_upload_limit_mb())
 
 
 @router.put("/upload-limit", response_model = UploadLimitResponse)
 def update_upload_limit(
-    payload: UploadLimitPayload,
-    current_subject: str = Depends(get_current_subject),
+    payload: UploadLimitPayload, current_subject: str = Depends(get_current_subject)
 ) -> UploadLimitResponse:
     try:
         limit_mb = set_upload_limit_mb(payload.max_upload_size_mb)
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 5b4267b2ef..d62e0209b0 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -71,9 +71,7 @@ router = APIRouter()
 logger = get_logger(__name__)
 
 
-def _validate_local_dataset_paths(
-    paths: list[str], label: str = "Local dataset"
-) -> list[str]:
+def _validate_local_dataset_paths(paths: list[str], label: str = "Local dataset") -> list[str]:
     """Resolve and validate a list of local dataset paths. Returns validated absolute paths."""
     validated = []
     missing = []
@@ -95,9 +93,7 @@ def _validate_local_dataset_paths(
 
 
 @router.get("/hardware")
-async def get_hardware_utilization(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_hardware_utilization(current_subject: str = Depends(get_current_subject)):
     """
     Get a live snapshot of GPU hardware utilization.
 
@@ -105,23 +101,18 @@ async def get_hardware_utilization(
     Returns live GPU memory usage information for the active backend.
     """
     from utils.hardware import get_gpu_utilization
-
     return get_gpu_utilization()
 
 
 @router.get("/hardware/visible")
-async def get_visible_hardware_utilization(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_visible_hardware_utilization(current_subject: str = Depends(get_current_subject)):
     from utils.hardware import get_visible_gpu_utilization
-
     return get_visible_gpu_utilization()
 
 
 @router.post("/start")
 async def start_training(
-    request: TrainingStartRequest,
-    current_subject: str = Depends(get_current_subject),
+    request: TrainingStartRequest, current_subject: str = Depends(get_current_subject)
 ):
     """
     Start a training job.
@@ -153,9 +144,7 @@ async def start_training(
 
         # Generate job ID — passed into start_training() which sets it on the
         # backend only after confirming the old pump thread is dead.
-        job_id = (
-            f"job_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{_uuid.uuid4().hex[:8]}"
-        )
+        job_id = f"job_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{_uuid.uuid4().hex[:8]}"
 
         # Validate dataset paths if provided
         if request.local_datasets:
@@ -169,9 +158,7 @@ async def start_training(
         resume_output_dir: Optional[str] = None
         if request.resume_from_checkpoint:
             try:
-                resume_output_dir = normalize_resume_output_dir(
-                    request.resume_from_checkpoint
-                )
+                resume_output_dir = normalize_resume_output_dir(request.resume_from_checkpoint)
             except ValueError as e:
                 # Deliberate user-facing validation message.
                 validation_message = str(e)
@@ -229,9 +216,7 @@ async def start_training(
             "lora_r": request.lora_r,
             "lora_alpha": request.lora_alpha,
             "lora_dropout": request.lora_dropout,
-            "target_modules": request.target_modules
-            if request.target_modules
-            else None,
+            "target_modules": request.target_modules if request.target_modules else None,
             "gradient_checkpointing": request.gradient_checkpointing.strip()
             if request.gradient_checkpointing and request.gradient_checkpointing.strip()
             else "unsloth",
@@ -261,20 +246,15 @@ async def start_training(
         # net, consult the YAML directly so models that need it always get it.
         if not training_kwargs["trust_remote_code"]:
             model_defaults = load_model_defaults(request.model_name)
-            yaml_trust = model_defaults.get("training", {}).get(
-                "trust_remote_code", False
-            )
+            yaml_trust = model_defaults.get("training", {}).get("trust_remote_code", False)
             if yaml_trust:
-                logger.info(
-                    f"YAML config sets trust_remote_code=True for {request.model_name}"
-                )
+                logger.info(f"YAML config sets trust_remote_code=True for {request.model_name}")
                 training_kwargs["trust_remote_code"] = True
 
         # Free GPU memory: shut down any running inference/export subprocesses
         # before training starts (they'd compete for VRAM otherwise)
         try:
             from core.inference import get_inference_backend
-
             inf_backend = get_inference_backend()
             if inf_backend.active_model_name:
                 logger.info(
@@ -289,12 +269,9 @@ async def start_training(
 
         try:
             from core.export import get_export_backend
-
             exp_backend = get_export_backend()
             if exp_backend.current_checkpoint:
-                logger.info(
-                    "Shutting down export subprocess to free GPU memory for training"
-                )
+                logger.info("Shutting down export subprocess to free GPU memory for training")
                 exp_backend._shutdown_subprocess()
                 exp_backend.current_checkpoint = None
                 exp_backend.is_vision = False
@@ -376,9 +353,7 @@ async def stop_training(
 
 
 @router.post("/reset")
-async def reset_training(
-    current_subject: str = Depends(get_current_subject),
-):
+async def reset_training(current_subject: str = Depends(get_current_subject)):
     """
     Reset training state so the user can return to configuration.
     """
@@ -389,14 +364,10 @@ async def reset_training(
         if is_active:
             if backend._cancel_requested:
                 # Cancel (save=False) was requested — force-terminate so we can reset immediately
-                logger.info(
-                    "Force-terminating subprocess for immediate reset (cancel path)"
-                )
+                logger.info("Force-terminating subprocess for immediate reset (cancel path)")
                 backend.force_terminate()
             else:
-                logger.warning(
-                    "Rejected reset while training active: is_active=%s", is_active
-                )
+                logger.warning("Rejected reset while training active: is_active=%s", is_active)
                 raise HTTPException(
                     status_code = 409,
                     detail = "Training is still running. Stop training and wait for it to finish before resetting.",
@@ -433,9 +404,7 @@ async def reset_training(
 
 
 @router.get("/status")
-async def get_training_status(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_training_status(current_subject: str = Depends(get_current_subject)):
     """
     Get the current training status.
     """
@@ -467,9 +436,7 @@ async def get_training_status(
             msg_lower = status_message.lower()
             if "loading" in msg_lower or "importing" in msg_lower:
                 phase = "loading_model"
-            elif any(
-                k in msg_lower for k in ["preparing", "initializing", "configuring"]
-            ):
+            elif any(k in msg_lower for k in ["preparing", "initializing", "configuring"]):
                 phase = "configuring"
             else:
                 phase = "training"
@@ -528,9 +495,7 @@ async def get_training_status(
 
 
 @router.get("/metrics", response_model = TrainingMetricsResponse)
-async def get_training_metrics(
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_training_metrics(current_subject: str = Depends(get_current_subject)):
     """
     Get training metrics (loss, learning rate, steps).
     """
@@ -572,8 +537,7 @@ async def get_training_metrics(
 
 @router.get("/progress")
 async def stream_training_progress(
-    request: Request,
-    current_subject: str = Depends(get_current_subject),
+    request: Request, current_subject: str = Depends(get_current_subject)
 ):
     """
     Stream training progress updates using Server-Sent Events (SSE).
@@ -614,14 +578,10 @@ async def stream_training_progress(
             if step < 0 or total == 0:
                 progress_percent = 0.0
             else:
-                progress_percent = (
-                    float(step) / float(total) * 100.0 if total > 0 else 0.0
-                )
+                progress_percent = float(step) / float(total) * 100.0 if total > 0 else 0.0
 
             # Get actual values from progress object if available
-            elapsed_seconds = (
-                getattr(progress, "elapsed_seconds", None) if progress else None
-            )
+            elapsed_seconds = getattr(progress, "elapsed_seconds", None) if progress else None
             eta_seconds = getattr(progress, "eta_seconds", None) if progress else None
             grad_norm = grad_norm_override
             if grad_norm is None and progress:
@@ -677,25 +637,15 @@ async def stream_training_progress(
             }
             for i, step_val in enumerate(backend.step_history):
                 if step_val > resume_from_step:
-                    loss_val = (
-                        backend.loss_history[i]
-                        if i < len(backend.loss_history)
-                        else None
-                    )
-                    lr_val = (
-                        backend.lr_history[i] if i < len(backend.lr_history) else None
-                    )
+                    loss_val = backend.loss_history[i] if i < len(backend.loss_history) else None
+                    lr_val = backend.lr_history[i] if i < len(backend.lr_history) else None
                     tp_replay = getattr(
                         getattr(backend, "trainer", None), "training_progress", None
                     )
                     total_replay = (
-                        getattr(tp_replay, "total_steps", step_val)
-                        if tp_replay
-                        else step_val
-                    )
-                    epoch_replay = (
-                        getattr(tp_replay, "epoch", None) if tp_replay else None
+                        getattr(tp_replay, "total_steps", step_val) if tp_replay else step_val
                     )
+                    epoch_replay = getattr(tp_replay, "epoch", None) if tp_replay else None
                     payload = build_progress(
                         step_val,
                         loss_val,
@@ -705,9 +655,7 @@ async def stream_training_progress(
                         progress = tp_replay,
                         grad_norm_override = grad_norm_by_step.get(step_val),
                     )
-                    yield format_sse(
-                        payload.model_dump_json(), event = "progress", event_id = step_val
-                    )
+                    yield format_sse(payload.model_dump_json(), event = "progress", event_id = step_val)
                     replayed += 1
             if replayed:
                 logger.info(f"SSE reconnect: replayed {replayed} missed steps")
@@ -727,21 +675,15 @@ async def stream_training_progress(
                 epoch = initial_epoch,
                 progress = tp,
             )
-            yield format_sse(
-                initial_progress.model_dump_json(), event = "progress", event_id = 0
-            )
+            yield format_sse(initial_progress.model_dump_json(), event = "progress", event_id = 0)
 
             # If not active, send final state and exit
             if not is_active:
                 if backend.step_history:
                     final_step = backend.step_history[-1]
-                    final_loss = (
-                        backend.loss_history[-1] if backend.loss_history else None
-                    )
+                    final_loss = backend.loss_history[-1] if backend.loss_history else None
                     final_lr = backend.lr_history[-1] if backend.lr_history else None
-                    final_total_steps = (
-                        getattr(tp, "total_steps", final_step) if tp else final_step
-                    )
+                    final_total_steps = getattr(tp, "total_steps", final_step) if tp else final_step
                     final_epoch = getattr(tp, "epoch", None) if tp else None
                     payload = build_progress(
                         final_step,
@@ -756,9 +698,7 @@ async def stream_training_progress(
                     )
                 else:
                     yield format_sse(
-                        build_progress(
-                            -1, None, None, 0, progress = tp
-                        ).model_dump_json(),
+                        build_progress(-1, None, None, 0, progress = tp).model_dump_json(),
                         event = "complete",
                         event_id = 0,
                     )
@@ -767,29 +707,19 @@ async def stream_training_progress(
         # ── Live polling loop ────────────────────────────────────
         last_step = resume_from_step if resume_from_step is not None else -1
         no_update_count = 0
-        max_no_updates = (
-            1800  # Timeout after 30 minutes (large models need time for compilation)
-        )
+        max_no_updates = 1800  # Timeout after 30 minutes (large models need time for compilation)
 
         while backend.is_training_active():
             try:
                 if backend.step_history:
                     current_step = backend.step_history[-1]
-                    current_loss = (
-                        backend.loss_history[-1] if backend.loss_history else None
-                    )
+                    current_loss = backend.loss_history[-1] if backend.loss_history else None
                     current_lr = backend.lr_history[-1] if backend.lr_history else None
-                    tp_inner = getattr(
-                        getattr(backend, "trainer", None), "training_progress", None
-                    )
+                    tp_inner = getattr(getattr(backend, "trainer", None), "training_progress", None)
                     current_total_steps = (
-                        getattr(tp_inner, "total_steps", current_step)
-                        if tp_inner
-                        else current_step
-                    )
-                    current_epoch = (
-                        getattr(tp_inner, "epoch", None) if tp_inner else None
+                        getattr(tp_inner, "total_steps", current_step) if tp_inner else current_step
                     )
+                    current_epoch = getattr(tp_inner, "epoch", None) if tp_inner else None
 
                     # Only send if step changed
                     if current_step != last_step:
@@ -836,9 +766,7 @@ async def stream_training_progress(
                             "training_progress",
                             None,
                         )
-                        prep_total = (
-                            getattr(tp_prep, "total_steps", 0) if tp_prep else 0
-                        )
+                        prep_total = getattr(tp_prep, "total_steps", 0) if tp_prep else 0
                         preparing_payload = build_progress(
                             0,
                             None,
@@ -858,9 +786,7 @@ async def stream_training_progress(
                     tp_timeout = getattr(
                         getattr(backend, "trainer", None), "training_progress", None
                     )
-                    timeout_payload = build_progress(
-                        last_step, None, None, 0, progress = tp_timeout
-                    )
+                    timeout_payload = build_progress(last_step, None, None, 0, progress = tp_timeout)
                     yield format_sse(
                         timeout_payload.model_dump_json(),
                         event = "error",
@@ -872,9 +798,7 @@ async def stream_training_progress(
 
             except Exception as e:
                 logger.error(f"Error in progress stream: {e}", exc_info = True)
-                tp_error = getattr(
-                    getattr(backend, "trainer", None), "training_progress", None
-                )
+                tp_error = getattr(getattr(backend, "trainer", None), "training_progress", None)
                 error_payload = build_progress(0, None, None, 0, progress = tp_error)
                 yield format_sse(
                     error_payload.model_dump_json(),
@@ -888,9 +812,7 @@ async def stream_training_progress(
         final_loss = backend.loss_history[-1] if backend.loss_history else None
         final_lr = backend.lr_history[-1] if backend.lr_history else None
         final_tp = getattr(getattr(backend, "trainer", None), "training_progress", None)
-        final_total_steps = (
-            getattr(final_tp, "total_steps", final_step) if final_tp else final_step
-        )
+        final_total_steps = getattr(final_tp, "total_steps", final_step) if final_tp else final_step
         final_epoch = getattr(final_tp, "epoch", None) if final_tp else None
         final_payload = build_progress(
             final_step,
diff --git a/studio/backend/routes/training_history.py b/studio/backend/routes/training_history.py
index 771d9f1e35..1560c72767 100644
--- a/studio/backend/routes/training_history.py
+++ b/studio/backend/routes/training_history.py
@@ -42,19 +42,13 @@ async def list_training_runs(
     """List training runs, newest first."""
     result = list_runs(limit = limit, offset = offset)
     return TrainingRunListResponse(
-        runs = [
-            TrainingRunSummary(**{**r, "can_resume": can_resume_run(r)})
-            for r in result["runs"]
-        ],
+        runs = [TrainingRunSummary(**{**r, "can_resume": can_resume_run(r)}) for r in result["runs"]],
         total = result["total"],
     )
 
 
 @router.get("/runs/{run_id}", response_model = TrainingRunDetailResponse)
-async def get_training_run_detail(
-    run_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def get_training_run_detail(run_id: str, current_subject: str = Depends(get_current_subject)):
     """Get a single training run with full config and metrics."""
     run = get_run(run_id)
     if run is None:
@@ -109,18 +103,13 @@ async def update_training_run(
 
 
 @router.delete("/runs/{run_id}", response_model = TrainingRunDeleteResponse)
-async def delete_training_run(
-    run_id: str,
-    current_subject: str = Depends(get_current_subject),
-):
+async def delete_training_run(run_id: str, current_subject: str = Depends(get_current_subject)):
     """Delete a training run and its metrics (CASCADE)."""
     run = get_run(run_id)
     if run is None:
         raise HTTPException(status_code = 404, detail = f"Run {run_id} not found")
     if run["status"] == "running":
-        raise HTTPException(
-            status_code = 409, detail = "Cannot delete a running training run"
-        )
+        raise HTTPException(status_code = 409, detail = "Cannot delete a running training run")
     logger.info("Deleting training run %s", run_id)
     delete_run(run_id)
     return TrainingRunDeleteResponse(
diff --git a/studio/backend/run.py b/studio/backend/run.py
index 7e84c41075..5cfc1822f7 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -25,9 +25,7 @@ try:
     configure_cpu_threads()
 except ValueError as exc:
     configured = os.environ.get("UNSLOTH_CPU_THREADS")
-    raise SystemExit(
-        f"Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {exc}"
-    ) from None
+    raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {exc}") from None
 
 # Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
 # any library imports that trigger attrs -> rich -> structlog -> platform crash.
@@ -93,9 +91,7 @@ def _install_uvicorn_startup_log_rewrite(bind_host: str, display_host: str) -> N
     import re
 
     rewrite_host = (
-        bind_host in ("0.0.0.0", "::")
-        and bool(display_host)
-        and display_host != bind_host
+        bind_host in ("0.0.0.0", "::") and bool(display_host) and display_host != bind_host
     )
     new_suffix = "(To stop: press Ctrl+C -- on macOS, Control+C not Command+C)"
     old_suffix_re = re.compile(r"\(Press CTRL\+C to quit\)")
@@ -136,10 +132,13 @@ def _install_uvicorn_startup_log_rewrite(bind_host: str, display_host: str) -> N
         logging.getLogger(name).addFilter(f)
 
 
-def _local_port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+def _local_port_open(
+    host: str,
+    port: int,
+    timeout: float = 1.0,
+) -> bool:
     """Return True iff a TCP connection to (host, port) succeeds within timeout."""
     import socket
-
     try:
         with socket.create_connection((host, port), timeout = timeout):
             return True
@@ -178,9 +177,7 @@ def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
         return None
 
     try:
-        addr_info = socket.getaddrinfo(
-            "localhost", port, socket.AF_UNSPEC, socket.SOCK_STREAM
-        )
+        addr_info = socket.getaddrinfo("localhost", port, socket.AF_UNSPEC, socket.SOCK_STREAM)
     except Exception:
         return None
 
@@ -369,8 +366,7 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
                 flush = True,
             )
             print(
-                f"{dim}        ssh -L {port}:localhost:{port} "
-                f"<user>@{display_host}{reset}",
+                f"{dim}        ssh -L {port}:localhost:{port} " f"<user>@{display_host}{reset}",
                 flush = True,
             )
             print(
@@ -499,15 +495,17 @@ def _is_port_free(host: str, port: int) -> bool:
     return True
 
 
-def _find_free_port(host: str, start: int, max_attempts: int = 20) -> int:
+def _find_free_port(
+    host: str,
+    start: int,
+    max_attempts: int = 20,
+) -> int:
     """Find a free port starting from `start`, trying up to max_attempts ports."""
     for offset in range(max_attempts):
         candidate = start + offset
         if _is_port_free(host, candidate):
             return candidate
-    raise RuntimeError(
-        f"Could not find a free port in range {start}-{start + max_attempts - 1}"
-    )
+    raise RuntimeError(f"Could not find a free port in range {start}-{start + max_attempts - 1}")
 
 
 from utils.paths.storage_roots import studio_root as _studio_root
@@ -570,7 +568,6 @@ def _graceful_shutdown(server = None):
     # 2. Clean up inference subprocess (if instantiated)
     try:
         from core.inference.orchestrator import _inference_backend
-
         if _inference_backend is not None:
             _inference_backend._shutdown_subprocess(timeout = 5.0)
     except Exception as e:
@@ -579,7 +576,6 @@ def _graceful_shutdown(server = None):
     # 3. Clean up export subprocess (if instantiated)
     try:
         from core.export.orchestrator import _export_backend
-
         if _export_backend is not None:
             _export_backend._shutdown_subprocess(timeout = 5.0)
     except Exception as e:
@@ -588,7 +584,6 @@ def _graceful_shutdown(server = None):
     # 4. Clean up training subprocess (if active)
     try:
         from core.training.training import _training_backend
-
         if _training_backend is not None:
             _training_backend.force_terminate()
     except Exception as e:
@@ -597,7 +592,6 @@ def _graceful_shutdown(server = None):
     # 5. Kill llama-server subprocess (if loaded)
     try:
         from routes.inference import _llama_cpp_backend
-
         if _llama_cpp_backend is not None:
             _llama_cpp_backend._kill_process()
     except Exception as e:
@@ -651,9 +645,7 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
                 # Tolerate single- or multi-line dict literals; [^}]* still
                 # rejects nested dicts, which the setuptools template never
                 # emits for editable installs.
-                m = re.search(
-                    r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S
-                )
+                m = re.search(r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S)
                 if not m:
                     continue
                 try:
@@ -760,9 +752,7 @@ def run_server(
             print("=" * 50)
             if blocker:
                 pid, name = blocker
-                print(
-                    f"Port {original_port} is already in use by " f"{name} (PID {pid})."
-                )
+                print(f"Port {original_port} is already in use by " f"{name} (PID {pid}).")
             else:
                 print(f"Port {original_port} is already in use.")
             print(f"Unsloth Studio will use port {port} instead.")
@@ -991,9 +981,7 @@ if __name__ == "__main__":
         sys.stderr.write("=" * 60 + "\n")
         traceback.print_exc(file = sys.stderr)
         sys.stderr.write("\n")
-        sys.stderr.write(
-            "If a package is missing, try re-running: unsloth studio setup\n"
-        )
+        sys.stderr.write("If a package is missing, try re-running: unsloth studio setup\n")
         sys.stderr.flush()
         sys.exit(1)
 
diff --git a/studio/backend/state/tool_policy.py b/studio/backend/state/tool_policy.py
index 9343a39806..9b0fc7d6cb 100644
--- a/studio/backend/state/tool_policy.py
+++ b/studio/backend/state/tool_policy.py
@@ -21,9 +21,7 @@ def get_tool_policy() -> Optional[bool]:
 
 def set_tool_policy(value: Optional[bool]) -> None:
     if value is not None and not isinstance(value, bool):
-        raise TypeError(
-            f"tool_policy must be Optional[bool], got {type(value).__name__}"
-        )
+        raise TypeError(f"tool_policy must be Optional[bool], got {type(value).__name__}")
     global _tool_policy
     _tool_policy = value
 
diff --git a/studio/backend/storage/mcp_servers_db.py b/studio/backend/storage/mcp_servers_db.py
index da2fa15423..9dd90a58bb 100644
--- a/studio/backend/storage/mcp_servers_db.py
+++ b/studio/backend/storage/mcp_servers_db.py
@@ -29,13 +29,9 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         """
     )
     # use_oauth was added after the first release; backfill for pre-existing DBs.
-    cols = {
-        r["name"] for r in conn.execute("PRAGMA table_info(mcp_servers)").fetchall()
-    }
+    cols = {r["name"] for r in conn.execute("PRAGMA table_info(mcp_servers)").fetchall()}
     if "use_oauth" not in cols:
-        conn.execute(
-            "ALTER TABLE mcp_servers ADD COLUMN use_oauth INTEGER NOT NULL DEFAULT 0"
-        )
+        conn.execute("ALTER TABLE mcp_servers ADD COLUMN use_oauth INTEGER NOT NULL DEFAULT 0")
 
 
 def get_connection() -> sqlite3.Connection:
diff --git a/studio/backend/storage/providers_db.py b/studio/backend/storage/providers_db.py
index ca47fcbd80..3c6056fb8d 100644
--- a/studio/backend/storage/providers_db.py
+++ b/studio/backend/storage/providers_db.py
@@ -62,12 +62,7 @@ def get_connection() -> sqlite3.Connection:
     return conn
 
 
-def create_provider(
-    id: str,
-    provider_type: str,
-    display_name: str,
-    base_url: str,
-) -> None:
+def create_provider(id: str, provider_type: str, display_name: str, base_url: str) -> None:
     """Insert a new provider configuration."""
     now = datetime.now(timezone.utc).isoformat()
     conn = get_connection()
@@ -145,9 +140,7 @@ def list_providers() -> list[dict]:
     """List all provider configurations, ordered by creation time."""
     conn = get_connection()
     try:
-        rows = conn.execute(
-            "SELECT * FROM llm_providers ORDER BY created_at"
-        ).fetchall()
+        rows = conn.execute("SELECT * FROM llm_providers ORDER BY created_at").fetchall()
         return [dict(row) for row in rows]
     finally:
         conn.close()
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index 0175e54b35..5f0d6449d5 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -89,9 +89,7 @@ def _delete_project_workspace(project: dict) -> None:
     try:
         root_resolved = root.resolve(strict = False)
     except (OSError, RuntimeError, ValueError):
-        logger.warning(
-            "Skipping project workspace delete for invalid path %r", root_path
-        )
+        logger.warning("Skipping project workspace delete for invalid path %r", root_path)
         return
 
     project_id = str(project["id"])
@@ -155,9 +153,7 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    existing_cols = {
-        row[1] for row in conn.execute("PRAGMA table_info(training_runs)").fetchall()
-    }
+    existing_cols = {row[1] for row in conn.execute("PRAGMA table_info(training_runs)").fetchall()}
     if "display_name" not in existing_cols:
         conn.execute("ALTER TABLE training_runs ADD COLUMN display_name TEXT")
     conn.execute(
@@ -177,9 +173,7 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    conn.execute(
-        "CREATE INDEX IF NOT EXISTS idx_metrics_run_id ON training_metrics(run_id)"
-    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_metrics_run_id ON training_metrics(run_id)")
     # Use COLLATE NOCASE on Windows so C:\Models and c:\models dedup via the
     # UNIQUE constraint.  On Linux/macOS (case-sensitive FS) keep the default
     # BINARY collation so /Models and /models remain distinct.
@@ -237,13 +231,9 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
     if "project_id" not in chat_thread_cols:
         conn.execute("ALTER TABLE chat_threads ADD COLUMN project_id TEXT")
     if "openai_code_exec_container_id" not in chat_thread_cols:
-        conn.execute(
-            "ALTER TABLE chat_threads ADD COLUMN openai_code_exec_container_id TEXT"
-        )
+        conn.execute("ALTER TABLE chat_threads ADD COLUMN openai_code_exec_container_id TEXT")
     if "anthropic_code_exec_container_id" not in chat_thread_cols:
-        conn.execute(
-            "ALTER TABLE chat_threads ADD COLUMN anthropic_code_exec_container_id TEXT"
-        )
+        conn.execute("ALTER TABLE chat_threads ADD COLUMN anthropic_code_exec_container_id TEXT")
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS chat_messages (
@@ -261,9 +251,7 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_chat_threads_model_type_created_at ON chat_threads(model_type, created_at)"
     )
-    conn.execute(
-        "CREATE INDEX IF NOT EXISTS idx_chat_threads_pair_id ON chat_threads(pair_id)"
-    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_chat_threads_pair_id ON chat_threads(pair_id)")
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_chat_threads_project_id ON chat_threads(project_id)"
     )
@@ -513,9 +501,7 @@ def list_runs(limit: int = 50, offset: int = 0) -> dict:
                 try:
                     run["loss_sparkline"] = json.loads(sparkline)
                 except (json.JSONDecodeError, TypeError):
-                    logger.debug(
-                        "Failed to parse loss_sparkline for run %s", run.get("id")
-                    )
+                    logger.debug("Failed to parse loss_sparkline for run %s", run.get("id"))
                     run["loss_sparkline"] = None
             runs.append(run)
         return {"runs": runs, "total": total}
@@ -591,9 +577,7 @@ def get_resumable_run_by_output_dir(output_dir: str) -> Optional[dict]:
             try:
                 run["loss_sparkline"] = json.loads(sparkline)
             except (json.JSONDecodeError, TypeError):
-                logger.debug(
-                    "Failed to parse loss_sparkline for output_dir %s", output_dir
-                )
+                logger.debug("Failed to parse loss_sparkline for output_dir %s", output_dir)
                 run["loss_sparkline"] = None
         return run
     finally:
@@ -1130,9 +1114,7 @@ def _parse_chat_setting_json(key: str, value_json: str) -> tuple[bool, Any]:
         return False, None
 
 
-def _load_chat_settings_for_merge(
-    conn: sqlite3.Connection,
-) -> tuple[dict[str, Any], set[str]]:
+def _load_chat_settings_for_merge(conn: sqlite3.Connection) -> tuple[dict[str, Any], set[str]]:
     rows = conn.execute("SELECT key, value_json FROM chat_settings").fetchall()
     current: dict[str, Any] = {}
     corrupt: set[str] = set()
@@ -1159,9 +1141,7 @@ def _load_chat_settings_for_merge(
 
 
 def _raise_if_chat_message_thread_conflicts(
-    conn: sqlite3.Connection,
-    thread_id: str,
-    message_ids: list[str],
+    conn: sqlite3.Connection, thread_id: str, message_ids: list[str]
 ) -> None:
     unique_ids = list(dict.fromkeys(message_ids))
     if not unique_ids:
@@ -1270,12 +1250,8 @@ def sync_chat_messages(
                     m.get("parentId"),
                     m["role"],
                     json.dumps(m.get("content", [])),
-                    json.dumps(m.get("attachments"))
-                    if m.get("attachments") is not None
-                    else None,
-                    json.dumps(m.get("metadata"))
-                    if m.get("metadata") is not None
-                    else None,
+                    json.dumps(m.get("attachments")) if m.get("attachments") is not None else None,
+                    json.dumps(m.get("metadata")) if m.get("metadata") is not None else None,
                     int(m["createdAt"]),
                 )
                 for m in messages
@@ -1355,9 +1331,7 @@ def list_chat_messages_for_threads(thread_ids: list[str]) -> list[dict]:
 def get_app_setting(key: str, fallback = None):
     conn = get_connection()
     try:
-        row = conn.execute(
-            "SELECT value_json FROM app_settings WHERE key = ?", (key,)
-        ).fetchone()
+        row = conn.execute("SELECT value_json FROM app_settings WHERE key = ?", (key,)).fetchone()
         if row is None:
             return fallback
         return _json_loads(row["value_json"], fallback)
@@ -1382,9 +1356,7 @@ def upsert_app_settings(settings: dict[str, Any]) -> dict[str, Any]:
             [(key, json.dumps(value), now) for key, value in settings.items()],
         )
         conn.commit()
-        rows = conn.execute(
-            "SELECT key, value_json FROM app_settings ORDER BY key"
-        ).fetchall()
+        rows = conn.execute("SELECT key, value_json FROM app_settings ORDER BY key").fetchall()
         return {row["key"]: _json_loads(row["value_json"], None) for row in rows}
     finally:
         conn.close()
@@ -1393,9 +1365,7 @@ def upsert_app_settings(settings: dict[str, Any]) -> dict[str, Any]:
 def list_chat_settings() -> dict[str, Any]:
     conn = get_connection()
     try:
-        rows = conn.execute(
-            "SELECT key, value_json FROM chat_settings ORDER BY key"
-        ).fetchall()
+        rows = conn.execute("SELECT key, value_json FROM chat_settings ORDER BY key").fetchall()
         settings: dict[str, Any] = {}
         for row in rows:
             settings[row["key"]] = _json_loads(row["value_json"], None)
@@ -1426,9 +1396,7 @@ def upsert_chat_settings(settings: dict[str, Any]) -> dict[str, Any]:
         conn.close()
 
 
-def _deep_merge_settings(
-    current: dict[str, Any], updates: dict[str, Any]
-) -> dict[str, Any]:
+def _deep_merge_settings(current: dict[str, Any], updates: dict[str, Any]) -> dict[str, Any]:
     merged = dict(current)
     for key, value in updates.items():
         current_value = merged.get(key)
@@ -1449,9 +1417,7 @@ def upsert_chat_settings_merge(updates: dict[str, Any]) -> dict[str, Any]:
         conn.execute("BEGIN IMMEDIATE")
         current, corrupt = _load_chat_settings_for_merge(conn)
         unsafe_partial_keys = [
-            key
-            for key, value in updates.items()
-            if key in corrupt and isinstance(value, dict)
+            key for key, value in updates.items() if key in corrupt and isinstance(value, dict)
         ]
         if unsafe_partial_keys:
             conn.commit()
@@ -1496,9 +1462,7 @@ def list_chat_legacy_imports() -> list[str]:
     """
     conn = get_connection()
     try:
-        rows = conn.execute(
-            "SELECT legacy_thread_id FROM chat_legacy_imports"
-        ).fetchall()
+        rows = conn.execute("SELECT legacy_thread_id FROM chat_legacy_imports").fetchall()
         return [row[0] for row in rows]
     finally:
         conn.close()
diff --git a/studio/backend/tests/test_amd_apu_unified_memory.py b/studio/backend/tests/test_amd_apu_unified_memory.py
index e0b819d54b..104182a232 100644
--- a/studio/backend/tests/test_amd_apu_unified_memory.py
+++ b/studio/backend/tests/test_amd_apu_unified_memory.py
@@ -14,7 +14,12 @@ import pytest
 from core.inference.llama_cpp import LlamaCppBackend
 
 
-def _fake_torch(hip, archs, *, cuda_ok = True):
+def _fake_torch(
+    hip,
+    archs,
+    *,
+    cuda_ok = True,
+):
     t = types.ModuleType("torch")
     t.version = types.SimpleNamespace(hip = hip)
     t.cuda = types.SimpleNamespace(
diff --git a/studio/backend/tests/test_anthropic_citations_edge.py b/studio/backend/tests/test_anthropic_citations_edge.py
index be1b5f7922..6b10600847 100644
--- a/studio/backend/tests/test_anthropic_citations_edge.py
+++ b/studio/backend/tests/test_anthropic_citations_edge.py
@@ -80,8 +80,7 @@ def _capture(
         client = _make_client()
         try:
             async for line in client.stream_chat_completion(
-                messages = messages
-                or [{"role": "user", "content": "what color is grass?"}],
+                messages = messages or [{"role": "user", "content": "what color is grass?"}],
                 model = "claude-opus-4-7",
                 max_tokens = 64,
             ):
@@ -159,10 +158,7 @@ def _citation_payload(body: str) -> dict:
         except json.JSONDecodeError:
             continue
         tool_event = payload.get("_toolEvent") if isinstance(payload, dict) else None
-        if (
-            isinstance(tool_event, dict)
-            and tool_event.get("type") == "document_citations"
-        ):
+        if isinstance(tool_event, dict) and tool_event.get("type") == "document_citations":
             return tool_event
     raise AssertionError("document_citations event not parsed out of SSE body")
 
diff --git a/studio/backend/tests/test_anthropic_code_execution.py b/studio/backend/tests/test_anthropic_code_execution.py
index 5c88437d17..dd2f2eef6c 100644
--- a/studio/backend/tests/test_anthropic_code_execution.py
+++ b/studio/backend/tests/test_anthropic_code_execution.py
@@ -118,10 +118,7 @@ def test_code_execution_tool_appended_to_request_body(monkeypatch):
     tools = body.get("tools") or []
     # Opus 4.7 gets the newer date-pinned variant (`_20260120`) that
     # supports REPL state persistence + programmatic tool calling.
-    assert {
-        "type": "code_execution_20260120",
-        "name": "code_execution",
-    } in tools
+    assert {"type": "code_execution_20260120", "name": "code_execution"} in tools
     # No web_search entry when only code_execution is enabled.
     assert all("web_search" not in (t.get("type") or "") for t in tools)
     # Beta header still carries the documented flag; both `_20250825`
@@ -201,9 +198,7 @@ def test_no_code_execution_tool_when_pill_off(monkeypatch):
     assert all("code_execution" not in (t.get("type") or "") for t in tools)
     # Beta header must NOT mention code-execution when the tool isn't on
     # -- that flag is opt-in only.
-    assert "code-execution-2025-08-25" not in captured["headers"].get(
-        "anthropic-beta", ""
-    )
+    assert "code-execution-2025-08-25" not in captured["headers"].get("anthropic-beta", "")
 
 
 def test_bash_code_execution_emits_tool_start_and_end(monkeypatch):
@@ -277,11 +272,7 @@ def test_bash_code_execution_emits_tool_start_and_end(monkeypatch):
     assert start["tool_call_id"] == "srvtoolu_1"
     # `_server_tool: True` marks this as a provider-side synthetic
     # tool card for the frontend's history serializer.
-    assert start["arguments"] == {
-        "kind": "bash",
-        "command": "ls -la",
-        "_server_tool": True,
-    }
+    assert start["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
 
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_1"
@@ -308,8 +299,7 @@ def test_text_editor_create_emits_kind_and_status(monkeypatch):
             "delta": {
                 "type": "input_json_delta",
                 "partial_json": (
-                    '{"command": "create", "path": "new_file.txt", '
-                    '"file_text": "hi"}'
+                    '{"command": "create", "path": "new_file.txt", "file_text": "hi"}'
                 ),
             },
         },
diff --git a/studio/backend/tests/test_anthropic_compaction.py b/studio/backend/tests/test_anthropic_compaction.py
index 92b9280146..6da752eac4 100644
--- a/studio/backend/tests/test_anthropic_compaction.py
+++ b/studio/backend/tests/test_anthropic_compaction.py
@@ -40,7 +40,12 @@ def _make_client() -> ExternalProviderClient:
     )
 
 
-def _capture(monkeypatch, model: str, threshold, tools = None) -> dict:
+def _capture(
+    monkeypatch,
+    model: str,
+    threshold,
+    tools = None,
+) -> dict:
     captured: dict = {}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -120,13 +125,9 @@ def test_supported_model_attaches_compaction_block_and_beta(monkeypatch):
 def test_threshold_clamped_to_50k_minimum(monkeypatch):
     # Below-min values get clamped UP so we don't 400 upstream.
     captured = _capture(monkeypatch, "claude-opus-4-7", 60_000)
-    assert (
-        captured["body"]["context_management"]["edits"][0]["trigger"]["value"] == 60_000
-    )
+    assert captured["body"]["context_management"]["edits"][0]["trigger"]["value"] == 60_000
     captured = _capture(monkeypatch, "claude-opus-4-7", 1)
-    assert (
-        captured["body"]["context_management"]["edits"][0]["trigger"]["value"] == 50_000
-    )
+    assert captured["body"]["context_management"]["edits"][0]["trigger"]["value"] == 50_000
 
 
 # ── beta header merge with code execution ────────────────────────────
@@ -151,10 +152,7 @@ def test_unsupported_model_silently_drops_compaction(monkeypatch):
     captured = _capture(monkeypatch, "claude-haiku-4-5-20251001", 150_000)
     assert "context_management" not in captured["body"]
     # The beta header must not carry compact-2026-01-12 either.
-    assert "compact-2026-01-12" not in captured["headers"].get(
-        "anthropic-beta",
-        "",
-    )
+    assert "compact-2026-01-12" not in captured["headers"].get("anthropic-beta", "")
 
 
 # ── omitted threshold leaves body untouched ─────────────────────────
@@ -163,10 +161,7 @@ def test_unsupported_model_silently_drops_compaction(monkeypatch):
 def test_omitted_threshold_no_body_field(monkeypatch):
     captured = _capture(monkeypatch, "claude-opus-4-7", None)
     assert "context_management" not in captured["body"]
-    assert "compact-2026-01-12" not in captured["headers"].get(
-        "anthropic-beta",
-        "",
-    )
+    assert "compact-2026-01-12" not in captured["headers"].get("anthropic-beta", "")
 
 
 # ── ChatCompletionRequest schema accepts sub-50k threshold ──────────
@@ -212,9 +207,7 @@ def test_chat_completion_request_accepts_sub_50k_compaction_threshold():
 # ── usage.iterations[] surfaces compaction tokens ──────────────────
 
 
-def test_message_delta_iterations_array_aggregates_compaction_tokens(
-    monkeypatch, capsys
-):
+def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch, capsys):
     # When Anthropic compacts mid-stream, the SSE message_delta usage
     # payload carries `iterations: [{type:"compaction", ...}, ...]`.
     # The top-level input_tokens / output_tokens only account for the
@@ -552,9 +545,7 @@ def test_build_external_messages_passes_compaction_for_anthropic_only():
             }
         )
     ]
-    out = _build_external_messages(
-        msgs, supports_vision = True, provider_type = "anthropic"
-    )
+    out = _build_external_messages(msgs, supports_vision = True, provider_type = "anthropic")
     assert len(out) == 1
     parts = out[0]["content"]
     assert parts[0] == {"type": "compaction", "content": "prior summary"}
@@ -582,9 +573,7 @@ def test_build_external_messages_strips_compaction_for_non_anthropic_providers()
         )
     ]
     for provider in ("openai", "deepseek", "mistral", "gemini", "kimi", "openrouter"):
-        out = _build_external_messages(
-            msgs, supports_vision = True, provider_type = provider
-        )
+        out = _build_external_messages(msgs, supports_vision = True, provider_type = provider)
         assert len(out) == 1, (provider, out)
         parts = out[0]["content"]
         types = [p.get("type") for p in parts if isinstance(p, dict)]
@@ -635,14 +624,10 @@ def test_build_external_messages_non_vision_anthropic_keeps_compaction():
             }
         )
     ]
-    out = _build_external_messages(
-        msgs, supports_vision = False, provider_type = "anthropic"
-    )
+    out = _build_external_messages(msgs, supports_vision = False, provider_type = "anthropic")
     parts = out[0]["content"]
     assert {"type": "compaction", "content": "prior summary"} in parts
     # Non-anthropic + non-vision -> compaction stripped, text collapsed
     # back to a string.
-    out2 = _build_external_messages(
-        msgs, supports_vision = False, provider_type = "deepseek"
-    )
+    out2 = _build_external_messages(msgs, supports_vision = False, provider_type = "deepseek")
     assert out2[0]["content"] == "answer", out2
diff --git a/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py b/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
index e7e5ec64d4..94a1ca4e2c 100644
--- a/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
+++ b/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
@@ -58,7 +58,11 @@ def _refusal_sse() -> bytes:
     )
 
 
-def _capture(monkeypatch, sse: bytes = b"", **kwargs) -> tuple[dict, list[str]]:
+def _capture(
+    monkeypatch,
+    sse: bytes = b"",
+    **kwargs,
+) -> tuple[dict, list[str]]:
     """Install a MockTransport, drive one streamed call, return body+lines."""
     captured: dict = {}
 
diff --git a/studio/backend/tests/test_anthropic_fast_mode_edge.py b/studio/backend/tests/test_anthropic_fast_mode_edge.py
index 0052cb94ad..116f58f7f2 100644
--- a/studio/backend/tests/test_anthropic_fast_mode_edge.py
+++ b/studio/backend/tests/test_anthropic_fast_mode_edge.py
@@ -60,7 +60,11 @@ def _refusal_sse(model: str = "claude-opus-4-7") -> bytes:
     )
 
 
-def _capture(monkeypatch, sse: bytes = b"", **kwargs) -> tuple[dict, list[str]]:
+def _capture(
+    monkeypatch,
+    sse: bytes = b"",
+    **kwargs,
+) -> tuple[dict, list[str]]:
     """Install a MockTransport, drive one streamed call, return body+lines."""
     captured: dict = {}
 
@@ -266,9 +270,7 @@ def test_refusal_notice_appears_before_content_filter_chunk(monkeypatch):
     """The notice content delta must precede the finish_reason chunk."""
     _, lines = _capture(monkeypatch, sse = _refusal_sse(), model = "claude-opus-4-7")
     notice_idx = next(i for i, l in enumerate(lines) if "stopped by Anthropic" in l)
-    filter_idx = next(
-        i for i, l in enumerate(lines) if '"finish_reason": "content_filter"' in l
-    )
+    filter_idx = next(i for i, l in enumerate(lines) if '"finish_reason": "content_filter"' in l)
     assert notice_idx < filter_idx, (notice_idx, filter_idx, lines)
 
 
@@ -350,7 +352,6 @@ def test_fast_mode_prefix_tuple_matches_capability_doc(monkeypatch):
     """Tuple must exactly match the two families in the upstream docs:
     https://platform.claude.com/docs/en/build-with-claude/fast-mode."""
     from core.inference.external_provider import _ANTHROPIC_FAST_MODE_PREFIXES
-
     assert set(_ANTHROPIC_FAST_MODE_PREFIXES) == {
         "claude-opus-4-7",
         "claude-opus-4-6",
@@ -421,9 +422,7 @@ def test_usage_speed_propagates_to_final_usage_chunk_fast(monkeypatch):
 def test_usage_speed_propagates_to_final_usage_chunk_standard(monkeypatch):
     _, lines = _capture(monkeypatch, sse = _fast_speed_sse(speed = "standard"))
     parsed = [
-        json.loads(l[len("data: ") :])
-        for l in lines
-        if l.startswith("data: ") and '"usage"' in l
+        json.loads(l[len("data: ") :]) for l in lines if l.startswith("data: ") and '"usage"' in l
     ]
     speeds = [p["usage"].get("speed") for p in parsed if "usage" in p]
     assert "standard" in speeds, parsed
@@ -433,9 +432,7 @@ def test_usage_speed_absent_when_anthropic_does_not_report(monkeypatch):
     """Studio must not invent ``usage.speed`` when upstream omits it."""
     _, lines = _capture(monkeypatch)
     parsed = [
-        json.loads(l[len("data: ") :])
-        for l in lines
-        if l.startswith("data: ") and '"usage"' in l
+        json.loads(l[len("data: ") :]) for l in lines if l.startswith("data: ") and '"usage"' in l
     ]
     for p in parsed:
         usage = p.get("usage") or {}
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index dfabf27b68..ee19a96bca 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -372,10 +372,7 @@ class TestAnthropicMessagesToOpenAI:
         ]
         result = anthropic_messages_to_openai(msgs)
         parts = result[0]["content"]
-        assert parts[1] == {
-            "type": "image_url",
-            "image_url": {"url": "https://x/y.png"},
-        }
+        assert parts[1] == {"type": "image_url", "image_url": {"url": "https://x/y.png"}}
 
     def test_image_only_user_message_emits_no_text_part(self):
         msgs = [
@@ -440,12 +437,7 @@ class TestAnthropicMessagesToOpenAI:
         ]
         result = anthropic_messages_to_openai(msgs)
         parts = result[0]["content"]
-        assert [p["type"] for p in parts] == [
-            "text",
-            "image_url",
-            "text",
-            "image_url",
-        ]
+        assert [p["type"] for p in parts] == ["text", "image_url", "text", "image_url"]
         assert parts[0]["text"] == "before"
         assert parts[2]["text"] == "after"
         assert parts[1]["image_url"]["url"] == "data:image/png;base64,AA"
@@ -523,15 +515,10 @@ class TestAnthropicToolsToOpenAI:
             enabled_tools = ["python"],
         )
 
-        assert [tool["function"]["name"] for tool in result] == [
-            "web_search",
-            "python",
-        ]
+        assert [tool["function"]["name"] for tool in result] == ["web_search", "python"]
 
     def test_pydantic_model_input(self):
-        tool = AnthropicTool(
-            name = "test", description = "desc", input_schema = {"type": "object"}
-        )
+        tool = AnthropicTool(name = "test", description = "desc", input_schema = {"type": "object"})
         result = anthropic_tools_to_openai([tool])
         assert result[0]["function"]["name"] == "test"
 
@@ -631,12 +618,8 @@ class TestAnthropicStreamEmitter:
             }
         )
 
-        first_payloads = [
-            json.loads(event.split("data: ")[1]) for event in first_events
-        ]
-        second_payloads = [
-            json.loads(event.split("data: ")[1]) for event in second_events
-        ]
+        first_payloads = [json.loads(event.split("data: ")[1]) for event in first_events]
+        second_payloads = [json.loads(event.split("data: ")[1]) for event in second_events]
 
         tool_starts = [
             payload
@@ -652,9 +635,7 @@ class TestAnthropicStreamEmitter:
                 "index": tool_starts[0]["index"],
                 "delta": {
                     "type": "input_json_delta",
-                    "partial_json": json.dumps(
-                        {"code": "<!doctype html><html></html>"}
-                    ),
+                    "partial_json": json.dumps({"code": "<!doctype html><html></html>"}),
                 },
             }
         ]
@@ -811,9 +792,7 @@ class TestAnthropicToolNonStreaming:
 
         response = asyncio.run(_anthropic_tool_non_streaming(_run_gen, "msg_1", "m"))
         body = json.loads(response.body)
-        tool_blocks = [
-            block for block in body["content"] if block["type"] == "tool_use"
-        ]
+        tool_blocks = [block for block in body["content"] if block["type"] == "tool_use"]
 
         assert tool_blocks == [
             {
@@ -919,26 +898,14 @@ class TestAnthropicPassthroughEmitter:
         events1 = e.feed_chunk(
             {
                 "choices": [
-                    {
-                        "delta": {
-                            "tool_calls": [
-                                {"index": 0, "function": {"arguments": '{"cmd'}}
-                            ]
-                        }
-                    }
+                    {"delta": {"tool_calls": [{"index": 0, "function": {"arguments": '{"cmd'}}]}}
                 ]
             }
         )
         events2 = e.feed_chunk(
             {
                 "choices": [
-                    {
-                        "delta": {
-                            "tool_calls": [
-                                {"index": 0, "function": {"arguments": '": "ls"}'}}
-                            ]
-                        }
-                    }
+                    {"delta": {"tool_calls": [{"index": 0, "function": {"arguments": '": "ls"}'}}]}}
                 ]
             }
         )
@@ -1331,9 +1298,7 @@ class TestAnthropicMessagesToolRouting:
         assert exc.value.status_code == 400
         assert "Mixing Anthropic server tools" in exc.value.detail
 
-    def test_mixed_rejected_when_client_tool_name_collides_with_server_alias(
-        self, monkeypatch
-    ):
+    def test_mixed_rejected_when_client_tool_name_collides_with_server_alias(self, monkeypatch):
         # Regression: a client tool sharing a name with a mapped server
         # tool (e.g. user defines their own "web_search") must still
         # trigger the mixed-mode 400 — the post-name filter would
@@ -1392,9 +1357,7 @@ class TestAnthropicMessagesToolRouting:
         assert exc.value.status_code == 400
         assert "name" in exc.value.detail
 
-    def test_alias_named_client_tool_without_schema_rejected_with_400(
-        self, monkeypatch
-    ):
+    def test_alias_named_client_tool_without_schema_rejected_with_400(self, monkeypatch):
         # Regression: a typo'd client tool whose name happens to collide
         # with a Studio alias (e.g. user meant a custom "python" tool but
         # forgot input_schema) must surface a 400, not silently switch
diff --git a/studio/backend/tests/test_anthropic_tool_versions.py b/studio/backend/tests/test_anthropic_tool_versions.py
index 608977ab07..8f5d3f7f46 100644
--- a/studio/backend/tests/test_anthropic_tool_versions.py
+++ b/studio/backend/tests/test_anthropic_tool_versions.py
@@ -168,10 +168,7 @@ def test_outbound_body_uses_new_versions_on_opus_4_7(monkeypatch):
     # Beta header for code execution stays on the existing flag for
     # both _20250825 and _20260120; the API uses one header to gate
     # the feature, not the date.
-    assert "code-execution-2025-08-25" in captured["headers"].get(
-        "anthropic-beta",
-        "",
-    )
+    assert "code-execution-2025-08-25" in captured["headers"].get("anthropic-beta", "")
 
 
 def test_outbound_body_falls_back_on_haiku_4_5(monkeypatch):
diff --git a/studio/backend/tests/test_anthropic_web_fetch.py b/studio/backend/tests/test_anthropic_web_fetch.py
index 88a922e7eb..7d754872cd 100644
--- a/studio/backend/tests/test_anthropic_web_fetch.py
+++ b/studio/backend/tests/test_anthropic_web_fetch.py
@@ -104,11 +104,7 @@ def test_web_fetch_tool_appended_to_request_body(monkeypatch):
     body = captured["body"]
     tools = body.get("tools") or []
     # claude-opus-4-7 routes web_fetch to _20260209 (dynamic filtering).
-    assert {
-        "type": "web_fetch_20260209",
-        "name": "web_fetch",
-        "max_uses": 5,
-    } in tools
+    assert {"type": "web_fetch_20260209", "name": "web_fetch", "max_uses": 5} in tools
     # web_fetch is GA; no beta header is required.
     assert "web-fetch" not in captured["headers"].get("anthropic-beta", "")
 
@@ -183,9 +179,7 @@ def test_no_web_fetch_tool_when_pill_off(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    assert all(
-        t.get("type") not in ("web_fetch_20250910", "web_fetch_20260209") for t in tools
-    )
+    assert all(t.get("type") not in ("web_fetch_20250910", "web_fetch_20260209") for t in tools)
 
 
 # ── SSE translation ─────────────────────────────────────────────────
@@ -253,9 +247,7 @@ def test_web_fetch_success_emits_tool_start_and_end(monkeypatch):
         client = _make_client()
         return await _collect(
             client._stream_anthropic(
-                messages = [
-                    {"role": "user", "content": "Fetch https://example.com/article"}
-                ],
+                messages = [{"role": "user", "content": "Fetch https://example.com/article"}],
                 model = "claude-opus-4-7",
                 temperature = 0.7,
                 top_p = 0.95,
@@ -273,10 +265,7 @@ def test_web_fetch_success_emits_tool_start_and_end(monkeypatch):
     assert start["tool_call_id"] == "srvtoolu_wf1"
     # `_server_tool: True` marks this as a provider-side synthetic
     # tool card for the frontend's history serializer.
-    assert start["arguments"] == {
-        "url": "https://example.com/article",
-        "_server_tool": True,
-    }
+    assert start["arguments"] == {"url": "https://example.com/article", "_server_tool": True}
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_wf1"
     # The source pill uses Title / URL / snippet as parseSourcesFromResult expects.
diff --git a/studio/backend/tests/test_audio_token_detection.py b/studio/backend/tests/test_audio_token_detection.py
index a3ea7c89a7..bf1217b231 100644
--- a/studio/backend/tests/test_audio_token_detection.py
+++ b/studio/backend/tests/test_audio_token_detection.py
@@ -19,9 +19,7 @@ def _classify(tokens: list[str]) -> str | None:
 
 
 def test_gemma3n_audio_soft_token_is_audio_vlm():
-    assert (
-        _classify(["<bos>", "<audio_soft_token>", "<image_soft_token>"]) == "audio_vlm"
-    )
+    assert _classify(["<bos>", "<audio_soft_token>", "<image_soft_token>"]) == "audio_vlm"
 
 
 def test_gemma4_pipe_audio_token_is_audio_vlm():
diff --git a/studio/backend/tests/test_cached_gguf_routes.py b/studio/backend/tests/test_cached_gguf_routes.py
index 05aae8fb75..980de216db 100644
--- a/studio/backend/tests/test_cached_gguf_routes.py
+++ b/studio/backend/tests/test_cached_gguf_routes.py
@@ -66,9 +66,7 @@ def test_iter_gguf_paths_matches_extension_case_insensitively(tmp_path):
     assert result == ["Q4_K_M.gguf", "Q8_0.GGUF"]
 
 
-def test_list_cached_gguf_includes_non_suffix_repo_when_cache_contains_gguf(
-    monkeypatch, tmp_path
-):
+def test_list_cached_gguf_includes_non_suffix_repo_when_cache_contains_gguf(monkeypatch, tmp_path):
     repo = _repo(
         "HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive",
         [_file("Q4_K_M.gguf", 5_000), _file("README.md", 10)],
@@ -130,9 +128,7 @@ def test_list_cached_gguf_skips_repos_without_positive_gguf_size(monkeypatch, tm
     assert result["cached"] == []
 
 
-def test_list_cached_gguf_keeps_largest_duplicate_repo_across_scans(
-    monkeypatch, tmp_path
-):
+def test_list_cached_gguf_keeps_largest_duplicate_repo_across_scans(monkeypatch, tmp_path):
     smaller = _repo(
         "Org/Dupe",
         [_file("Q4_K_M.gguf", 2_000)],
@@ -193,9 +189,7 @@ def test_list_cached_gguf_dedupes_shared_blobs_across_revisions(monkeypatch, tmp
     ]
 
 
-def test_list_cached_models_skips_non_suffix_repo_when_gguf_files_exist(
-    monkeypatch, tmp_path
-):
+def test_list_cached_models_skips_non_suffix_repo_when_gguf_files_exist(monkeypatch, tmp_path):
     mixed = _repo(
         "Org/MixedRepo",
         [
@@ -216,9 +210,7 @@ def test_list_cached_models_skips_non_suffix_repo_when_gguf_files_exist(
     assert result["cached"] == []
 
 
-def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(
-    monkeypatch, tmp_path
-):
+def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(monkeypatch, tmp_path):
     """Mirror of the _skips_ test: the mixed repo should still surface in
     cached-gguf so the picker can show it as a GGUF download."""
     mixed = _repo(
@@ -274,9 +266,7 @@ def test_list_cached_gguf_handles_none_size_on_disk(monkeypatch, tmp_path):
     ]
 
 
-def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(
-    monkeypatch, tmp_path
-):
+def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(monkeypatch, tmp_path):
     """One repo raising during classification must not poison the response
     for every other repo in the scan."""
 
@@ -357,17 +347,10 @@ def test_list_cached_models_includes_repo_with_only_mmproj_gguf(monkeypatch, tmp
 
     result = asyncio.run(models_route.list_cached_models(current_subject = "test-user"))
 
-    assert result["cached"] == [
-        {
-            "repo_id": "Org/MmprojAux",
-            "size_bytes": 15_000,
-        }
-    ]
+    assert result["cached"] == [{"repo_id": "Org/MmprojAux", "size_bytes": 15_000}]
 
 
-def test_list_cached_gguf_includes_vision_repo_with_main_gguf_and_mmproj(
-    monkeypatch, tmp_path
-):
+def test_list_cached_gguf_includes_vision_repo_with_main_gguf_and_mmproj(monkeypatch, tmp_path):
     """A vision-capable GGUF repo (main weight + mmproj adapter) is still
     a GGUF repo. The reported size is the main weight size; mmproj is
     excluded from the GGUF-size accounting because it is filtered out at
diff --git a/studio/backend/tests/test_chat_history_routes.py b/studio/backend/tests/test_chat_history_routes.py
index 62bcd05205..e3aeb4eb22 100644
--- a/studio/backend/tests/test_chat_history_routes.py
+++ b/studio/backend/tests/test_chat_history_routes.py
@@ -109,16 +109,13 @@ def test_chat_inference_settings_covers_frontend_persisted_fields():
         pytest.skip("frontend runtime.ts not present")
 
     with open(runtime_ts, encoding = "utf-8") as fh:
-        block = re.search(
-            r"interface InferenceParams \{(.*?)\n\}", fh.read(), re.DOTALL
-        )
+        block = re.search(r"interface InferenceParams \{(.*?)\n\}", fh.read(), re.DOTALL)
     assert block, "InferenceParams interface not found in runtime.ts"
     persisted = set(re.findall(r"^\s*(\w+)\??:", block.group(1), re.M)) - {"checkpoint"}
 
     backend = set(chat_history.ChatInferenceSettings.model_fields)
     assert persisted == backend, (
-        f"schema drift: frontend-only {persisted - backend}, "
-        f"backend-only {backend - persisted}"
+        f"schema drift: frontend-only {persisted - backend}, " f"backend-only {backend - persisted}"
     )
 
 
@@ -168,7 +165,6 @@ def test_record_import_ledger_returns_accepted_and_inserted(monkeypatch):
 
 def test_record_import_ledger_rejects_oversize_payload():
     from pydantic import ValidationError
-
     with pytest.raises(ValidationError):
         chat_history.ChatImportLedgerRecordRequest(
             threadIds = [f"id-{i}" for i in range(10_001)],
diff --git a/studio/backend/tests/test_chat_history_storage.py b/studio/backend/tests/test_chat_history_storage.py
index e88cac3276..b79f8f8119 100644
--- a/studio/backend/tests/test_chat_history_storage.py
+++ b/studio/backend/tests/test_chat_history_storage.py
@@ -13,7 +13,11 @@ import pytest
 from storage import studio_db
 
 
-def _reset_studio_db(tmp_path, monkeypatch, projects_home = None):
+def _reset_studio_db(
+    tmp_path,
+    monkeypatch,
+    projects_home = None,
+):
     monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
     monkeypatch.setenv(
         "UNSLOTH_STUDIO_PROJECTS_HOME",
@@ -105,10 +109,7 @@ def test_sync_chat_messages_upserts_without_pruning(tmp_path, monkeypatch):
     assert by_id["msg-2"]["content"] == [{"type": "text", "text": "updated text"}]
 
 
-def test_chat_projects_delete_cascades_threads_and_messages(
-    tmp_path,
-    monkeypatch,
-):
+def test_chat_projects_delete_cascades_threads_and_messages(tmp_path, monkeypatch):
     _reset_studio_db(tmp_path, monkeypatch)
     project = studio_db.upsert_chat_project(_project())
     assert project["rootPath"].startswith(str(tmp_path / "Projects"))
@@ -231,23 +232,16 @@ def test_settings_merge_atomic_under_concurrency(tmp_path, monkeypatch):
 
 def test_settings_merge_preserves_nested_keys(tmp_path, monkeypatch):
     _reset_studio_db(tmp_path, monkeypatch)
-    studio_db.upsert_chat_settings_merge(
-        {"inferenceParams": {"temperature": 0.5, "topP": 0.8}}
-    )
+    studio_db.upsert_chat_settings_merge({"inferenceParams": {"temperature": 0.5, "topP": 0.8}})
     studio_db.upsert_chat_settings_merge({"inferenceParams": {"temperature": 0.9}})
 
     params = studio_db.list_chat_settings()["inferenceParams"]
     assert params == {"temperature": 0.9, "topP": 0.8}
 
 
-def test_settings_merge_quarantines_corrupt_json_and_rejects_partial_patch(
-    tmp_path,
-    monkeypatch,
-):
+def test_settings_merge_quarantines_corrupt_json_and_rejects_partial_patch(tmp_path, monkeypatch):
     _reset_studio_db(tmp_path, monkeypatch)
-    studio_db.upsert_chat_settings_merge(
-        {"inferenceParams": {"temperature": 0.5, "topP": 0.8}}
-    )
+    studio_db.upsert_chat_settings_merge({"inferenceParams": {"temperature": 0.5, "topP": 0.8}})
     conn = studio_db.get_connection()
     try:
         conn.execute(
@@ -295,9 +289,7 @@ def test_settings_merge_replaces_corrupt_scalar_after_quarantine(tmp_path, monke
     assert settings["autoTitle"] is True
     conn = studio_db.get_connection()
     try:
-        quarantined = conn.execute(
-            "SELECT key, reason FROM chat_settings_quarantine"
-        ).fetchall()
+        quarantined = conn.execute("SELECT key, reason FROM chat_settings_quarantine").fetchall()
     finally:
         conn.close()
     assert [(row["key"], row["reason"]) for row in quarantined] == [
@@ -353,11 +345,7 @@ def test_legacy_imports_records_and_lists(tmp_path, monkeypatch):
     )
     assert accepted == 3
     assert inserted == 3
-    assert set(studio_db.list_chat_legacy_imports()) == {
-        "legacy-a",
-        "legacy-b",
-        "legacy-c",
-    }
+    assert set(studio_db.list_chat_legacy_imports()) == {"legacy-a", "legacy-b", "legacy-c"}
 
 
 def test_legacy_imports_is_idempotent(tmp_path, monkeypatch):
@@ -371,11 +359,7 @@ def test_legacy_imports_is_idempotent(tmp_path, monkeypatch):
     assert (accepted1, inserted1) == (2, 2)
     # legacy-b is already in the ledger, only legacy-c is genuinely new.
     assert (accepted2, inserted2) == (2, 1)
-    assert set(studio_db.list_chat_legacy_imports()) == {
-        "legacy-a",
-        "legacy-b",
-        "legacy-c",
-    }
+    assert set(studio_db.list_chat_legacy_imports()) == {"legacy-a", "legacy-b", "legacy-c"}
 
 
 def test_legacy_imports_dedups_input(tmp_path, monkeypatch):
diff --git a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
index 0d09f027cf..3bb60336eb 100644
--- a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
+++ b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
@@ -130,7 +130,6 @@ def test_symlinked_output_dir_skipped(outputs_setup):
 
 def test_missing_output_dir_is_noop(outputs_setup):
     from core.training.training import _cleanup_cancelled_checkpoints
-
     _cleanup_cancelled_checkpoints(outputs_setup / "does-not-exist")
     # Should not raise; nothing to assert beyond non-failure.
 
diff --git a/studio/backend/tests/test_cpu_threads.py b/studio/backend/tests/test_cpu_threads.py
index 1224941622..b51d2bfb7d 100644
--- a/studio/backend/tests/test_cpu_threads.py
+++ b/studio/backend/tests/test_cpu_threads.py
@@ -63,9 +63,7 @@ def test_cpu_thread_cap_is_opt_in(raw):
 
 
 # Anything that is not a positive integer raises a clear ValueError.
-@pytest.mark.parametrize(
-    "raw", ["zero", "0", "-3", "1.5", "abc", "8a", "0x4", "1e3", "4 0"]
-)
+@pytest.mark.parametrize("raw", ["zero", "0", "-3", "1.5", "abc", "8a", "0x4", "1e3", "4 0"])
 def test_cpu_thread_cap_requires_positive_integer(raw):
     with pytest.raises(ValueError, match = "must be a positive integer"):
         configure_cpu_threads({"UNSLOTH_CPU_THREADS": raw})
diff --git a/studio/backend/tests/test_dataset_upload_limits.py b/studio/backend/tests/test_dataset_upload_limits.py
index 0991059318..dc6030edbf 100644
--- a/studio/backend/tests/test_dataset_upload_limits.py
+++ b/studio/backend/tests/test_dataset_upload_limits.py
@@ -40,9 +40,7 @@ def isolate_upload_dir(tmp_path, monkeypatch):
 def test_dataset_upload_under_configured_cap_succeeds(isolate_upload_dir):
     upload = FakeUploadFile("sample.csv", [b"a,b\n1,2\n"])
     response = asyncio.run(
-        datasets_route.upload_dataset(
-            cast(UploadFile, upload), current_subject = "test-user"
-        )
+        datasets_route.upload_dataset(cast(UploadFile, upload), current_subject = "test-user")
     )
     stored = Path(response.stored_path)
     assert response.filename == "sample.csv"
@@ -58,9 +56,7 @@ def test_dataset_upload_over_configured_cap_removes_partial_file(isolate_upload_
     )
     with pytest.raises(HTTPException) as exc:
         asyncio.run(
-            datasets_route.upload_dataset(
-                cast(UploadFile, upload), current_subject = "test-user"
-            )
+            datasets_route.upload_dataset(cast(UploadFile, upload), current_subject = "test-user")
         )
     assert exc.value.status_code == 413
     assert "Maximum is 1MB" in exc.value.detail
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index 3d01342a5c..219d64145f 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -51,12 +51,8 @@ def auth_client():
 
 
 def data_recipe_jobs_module():
-    route_path = (
-        Path(__file__).resolve().parents[1] / "routes" / "data_recipe" / "jobs.py"
-    )
-    spec = importlib.util.spec_from_file_location(
-        "_desktop_data_recipe_jobs", route_path
-    )
+    route_path = Path(__file__).resolve().parents[1] / "routes" / "data_recipe" / "jobs.py"
+    spec = importlib.util.spec_from_file_location("_desktop_data_recipe_jobs", route_path)
     jobs_route = importlib.util.module_from_spec(spec)
     assert spec.loader is not None
     spec.loader.exec_module(jobs_route)
@@ -265,9 +261,7 @@ def test_consume_refresh_token_concurrent_only_one_succeeds(tmp_path, monkeypatc
         results = list(pool.map(attempt, range(workers)))
 
     successes = [r for r in results if r is not None]
-    assert (
-        len(successes) == 1
-    ), f"expected exactly one consumer to win, got {len(successes)}"
+    assert len(successes) == 1, f"expected exactly one consumer to win, got {len(successes)}"
     assert successes[0] == (storage.DEFAULT_ADMIN_USERNAME, False)
 
 
@@ -285,9 +279,7 @@ def test_desktop_session_uses_real_admin_identity_for_api_keys():
     seed_user(must_change_password = True)
     raw = storage.create_desktop_secret()
     client = auth_client()
-    token = client.post("/api/auth/desktop-login", json = {"secret": raw}).json()[
-        "access_token"
-    ]
+    token = client.post("/api/auth/desktop-login", json = {"secret": raw}).json()["access_token"]
 
     response = client.post(
         "/api/auth/api-keys",
@@ -322,9 +314,7 @@ def test_local_recipe_token_authenticates_as_admin_for_desktop_user(loaded_local
         scheme = "Bearer",
         credentials = local_token,
     )
-    assert (
-        asyncio.run(get_current_subject(credentials)) == storage.DEFAULT_ADMIN_USERNAME
-    )
+    assert asyncio.run(get_current_subject(credentials)) == storage.DEFAULT_ADMIN_USERNAME
 
 
 def test_local_recipe_token_authenticates_as_admin_for_web_user(loaded_local_model):
@@ -345,9 +335,7 @@ def test_local_recipe_token_authenticates_as_admin_for_web_user(loaded_local_mod
         scheme = "Bearer",
         credentials = local_token,
     )
-    assert (
-        asyncio.run(get_current_subject(credentials)) == storage.DEFAULT_ADMIN_USERNAME
-    )
+    assert asyncio.run(get_current_subject(credentials)) == storage.DEFAULT_ADMIN_USERNAME
 
 
 def test_desktop_login_rejects_invalid_secret():
@@ -480,8 +468,7 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
 
 
 def test_provision_desktop_auth_writes_secret_and_creates_db_without_backend_deps(
-    tmp_path,
-    monkeypatch,
+    tmp_path, monkeypatch
 ):
     auth_dir = tmp_path / "auth"
     auth_dir.mkdir()
@@ -536,12 +523,9 @@ if result.exit_code != 0:
             """
         ).fetchone()
         app_secrets = {
-            row["key"]: row["value"]
-            for row in conn.execute("SELECT key, value FROM app_secrets")
-        }
-        refresh_columns = {
-            row["name"] for row in conn.execute("PRAGMA table_info(refresh_tokens)")
+            row["key"]: row["value"] for row in conn.execute("SELECT key, value FROM app_secrets")
         }
+        refresh_columns = {row["name"] for row in conn.execute("PRAGMA table_info(refresh_tokens)")}
     finally:
         conn.close()
 
@@ -633,9 +617,7 @@ def test_update_password_clears_desktop_secret():
     raw = storage.create_desktop_secret()
     assert storage.validate_desktop_secret(raw) == storage.DEFAULT_ADMIN_USERNAME
 
-    changed = storage.update_password(
-        storage.DEFAULT_ADMIN_USERNAME, "new-admin-password"
-    )
+    changed = storage.update_password(storage.DEFAULT_ADMIN_USERNAME, "new-admin-password")
     assert changed is True
     assert storage.validate_desktop_secret(raw) is None
 
@@ -651,11 +633,7 @@ def test_update_password_on_unknown_user_leaves_desktop_secret_intact():
 
 def test_desktop_auth_provision_has_bounded_timeout():
     rs_path = (
-        Path(__file__).resolve().parents[3]
-        / "studio"
-        / "src-tauri"
-        / "src"
-        / "desktop_auth.rs"
+        Path(__file__).resolve().parents[3] / "studio" / "src-tauri" / "src" / "desktop_auth.rs"
     )
     src = rs_path.read_text()
     start = src.index("async fn provision_desktop_auth(")
diff --git a/studio/backend/tests/test_detect_mmproj_file.py b/studio/backend/tests/test_detect_mmproj_file.py
index cdb73448be..9487db1e5b 100644
--- a/studio/backend/tests/test_detect_mmproj_file.py
+++ b/studio/backend/tests/test_detect_mmproj_file.py
@@ -132,10 +132,7 @@ def test_family_token_mistral_does_not_match_ministral():
     assert _detect_family_token("Ministral-3-8B-Instruct-2512-BF16.gguf") == "ministral"
     assert _detect_family_token("Mistral-7B-Instruct-v0.3.gguf") == "mistral"
     assert _detect_family_token("Magistral-Small-2506-BF16.gguf") == "magistral"
-    assert (
-        _detect_family_token("Devstral-Small-2-24B-Instruct-2512-BF16.gguf")
-        == "devstral"
-    )
+    assert _detect_family_token("Devstral-Small-2-24B-Instruct-2512-BF16.gguf") == "devstral"
 
 
 def test_family_token_picks_leftmost_when_multiple_present():
@@ -160,9 +157,7 @@ def test_family_token_new_families_recognised():
 
 def test_blocks_cross_family_for_new_token_pair(tmp_path: Path):
     """Nemotron weight + lone Gemma projector returns None."""
-    model = _touch(
-        tmp_path / "NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-MXFP4_MOE.gguf"
-    )
+    model = _touch(tmp_path / "NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-MXFP4_MOE.gguf")
     _touch(tmp_path / "gemma-4-26B-A4B-it.mmproj-q8_0.gguf")
     assert detect_mmproj_file(str(model)) is None
 
diff --git a/studio/backend/tests/test_export_log_cursor.py b/studio/backend/tests/test_export_log_cursor.py
index 734ca522c9..253922ce74 100644
--- a/studio/backend/tests/test_export_log_cursor.py
+++ b/studio/backend/tests/test_export_log_cursor.py
@@ -66,11 +66,14 @@ sys.modules.setdefault("utils.paths", _utils_paths_stub)
 def orchestrator():
     """Fresh ExportOrchestrator with only the log-buffer state exercised."""
     from core.export.orchestrator import ExportOrchestrator
-
     return ExportOrchestrator()
 
 
-def _append(orch, line: str, stream: str = "stdout") -> None:
+def _append(
+    orch,
+    line: str,
+    stream: str = "stdout",
+) -> None:
     """Shortcut for simulating a worker log message."""
     orch._append_log({"type": "log", "stream": stream, "line": line, "ts": 0.0})
 
diff --git a/studio/backend/tests/test_external_provider_usage_chunk.py b/studio/backend/tests/test_external_provider_usage_chunk.py
index 82c641d049..afeb26e9e9 100644
--- a/studio/backend/tests/test_external_provider_usage_chunk.py
+++ b/studio/backend/tests/test_external_provider_usage_chunk.py
@@ -191,11 +191,7 @@ def _usage_chunks(lines: list[str]) -> list[dict]:
             parsed = json.loads(payload)
         except json.JSONDecodeError:
             continue
-        if (
-            isinstance(parsed, dict)
-            and "usage" in parsed
-            and parsed.get("choices") == []
-        ):
+        if isinstance(parsed, dict) and "usage" in parsed and parsed.get("choices") == []:
             out.append(parsed["usage"])
     return out
 
@@ -256,13 +252,9 @@ def test_anthropic_stream_emits_usage_chunk_before_done(monkeypatch):
 
     # Usage chunk must come before [DONE].
     data_lines = [ln for ln in lines if ln.startswith("data:")]
-    done_idx = next(
-        i for i, ln in enumerate(data_lines) if ln.strip().endswith("[DONE]")
-    )
+    done_idx = next(i for i, ln in enumerate(data_lines) if ln.strip().endswith("[DONE]"))
     usage_idx = next(
-        i
-        for i, ln in enumerate(data_lines)
-        if '"usage":' in ln and '"choices": []' in ln
+        i for i, ln in enumerate(data_lines) if '"usage":' in ln and '"choices": []' in ln
     )
     assert usage_idx < done_idx
 
diff --git a/studio/backend/tests/test_frontend_resolution.py b/studio/backend/tests/test_frontend_resolution.py
index 2b49763386..3cdc755f7f 100644
--- a/studio/backend/tests/test_frontend_resolution.py
+++ b/studio/backend/tests/test_frontend_resolution.py
@@ -130,13 +130,7 @@ def test_resolver_falls_back_to_windows_layout_site_packages(tmp_path, monkeypat
     alongside the POSIX `lib/python*/site-packages` path."""
     studio_home = tmp_path / "studio_home"
     sp_dist = (
-        studio_home
-        / "unsloth_studio"
-        / "Lib"
-        / "site-packages"
-        / "studio"
-        / "frontend"
-        / "dist"
+        studio_home / "unsloth_studio" / "Lib" / "site-packages" / "studio" / "frontend" / "dist"
     )
     sp_dist.mkdir(parents = True)
     (sp_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
diff --git a/studio/backend/tests/test_gemini_provider.py b/studio/backend/tests/test_gemini_provider.py
index 4dc97302e2..01ef2e16fd 100644
--- a/studio/backend/tests/test_gemini_provider.py
+++ b/studio/backend/tests/test_gemini_provider.py
@@ -545,9 +545,7 @@ def test_finish_reason_swaps_to_tool_calls_when_function_call_emitted(monkeypatc
                 {
                     "content": {
                         "role": "model",
-                        "parts": [
-                            {"functionCall": {"name": "lookup", "args": {"k": "v"}}}
-                        ],
+                        "parts": [{"functionCall": {"name": "lookup", "args": {"k": "v"}}}],
                     },
                     "finishReason": "STOP",
                 }
@@ -631,9 +629,7 @@ def test_thought_signature_emitted_in_tool_call_delta(monkeypatch):
     deltas = [
         tc
         for c in chunks
-        for tc in (c.get("choices", [{}])[0].get("delta", {}) or {}).get(
-            "tool_calls", []
-        )
+        for tc in (c.get("choices", [{}])[0].get("delta", {}) or {}).get("tool_calls", [])
     ]
     assert deltas, chunks
     sig = deltas[0].get("extra_content", {}).get("google", {}).get("thought_signature")
@@ -687,10 +683,7 @@ def test_image_generation_tool_on_image_model_drops_text_tools(monkeypatch):
         ],
     )
     assert "tools" not in captured["body"], captured["body"]
-    assert captured["body"]["generationConfig"].get("responseModalities") == [
-        "TEXT",
-        "IMAGE",
-    ]
+    assert captured["body"]["generationConfig"].get("responseModalities") == ["TEXT", "IMAGE"]
 
 
 def test_prompt_feedback_block_reason_surfaces_as_error(monkeypatch):
@@ -704,9 +697,7 @@ def test_prompt_feedback_block_reason_surfaces_as_error(monkeypatch):
     chunks = _parse_chunks(_collect(monkeypatch, sse))
     error_chunks = [c for c in chunks if "error" in c]
     assert error_chunks, chunks
-    assert "SAFETY" in (
-        error_chunks[0].get("error", {}).get("message") or ""
-    ), error_chunks
+    assert "SAFETY" in (error_chunks[0].get("error", {}).get("message") or ""), error_chunks
 
 
 def test_usage_chunk_includes_thoughts_tokens(monkeypatch):
@@ -794,10 +785,7 @@ def test_image_model_sets_response_modalities(monkeypatch):
         model = "gemini-2.5-flash-image",
         enabled_tools = ["image_generation"],
     )
-    assert captured["body"]["generationConfig"]["responseModalities"] == [
-        "TEXT",
-        "IMAGE",
-    ]
+    assert captured["body"]["generationConfig"]["responseModalities"] == ["TEXT", "IMAGE"]
 
 
 def test_image_generation_tool_sets_response_modalities_on_image_model(monkeypatch):
@@ -810,10 +798,7 @@ def test_image_generation_tool_sets_response_modalities_on_image_model(monkeypat
         model = "gemini-2.5-flash-image",
         enabled_tools = ["image_generation"],
     )
-    assert captured["body"]["generationConfig"]["responseModalities"] == [
-        "TEXT",
-        "IMAGE",
-    ]
+    assert captured["body"]["generationConfig"]["responseModalities"] == ["TEXT", "IMAGE"]
 
 
 def test_image_response_emits_image_b64_tool_event(monkeypatch):
@@ -1001,9 +986,7 @@ def test_parallel_function_calls_get_distinct_tool_call_indices(monkeypatch):
         )
     ]
     assert len(tool_call_chunks) == 2, tool_call_chunks
-    indices = [
-        c["choices"][0]["delta"]["tool_calls"][0]["index"] for c in tool_call_chunks
-    ]
+    indices = [c["choices"][0]["delta"]["tool_calls"][0]["index"] for c in tool_call_chunks]
     assert indices == [0, 1], indices
 
 
@@ -1050,10 +1033,7 @@ def test_function_call_ids_forwarded_into_gemini_function_call_part(monkeypatch)
     call_ids = [p["functionCall"]["id"] for p in assistant_parts if "functionCall" in p]
     assert call_ids == ["call_alpha", "call_beta"], assistant_parts
     response_ids = [
-        p["functionResponse"]["id"]
-        for c in contents
-        for p in c["parts"]
-        if "functionResponse" in p
+        p["functionResponse"]["id"] for c in contents for p in c["parts"] if "functionResponse" in p
     ]
     assert response_ids == ["call_alpha", "call_beta"], contents
 
@@ -1131,9 +1111,7 @@ def test_code_execution_parts_translate_to_code_execution_tool_events(monkeypatc
         if e.get("type") == "tool_start" and e.get("tool_name") == "code_execution"
     ]
     code_ends = [
-        e
-        for e in tool_events
-        if e.get("type") == "tool_end" and "4" in str(e.get("result", ""))
+        e for e in tool_events if e.get("type") == "tool_end" and "4" in str(e.get("result", ""))
     ]
     assert len(code_starts) == 1, tool_events
     assert code_starts[0]["arguments"]["code"] == "print(2+2)"
@@ -1277,10 +1255,7 @@ def test_vision_data_url_translates_to_inline_data(monkeypatch):
     parts = captured["body"]["contents"][0]["parts"]
     inline_parts = [p for p in parts if "inlineData" in p]
     assert len(inline_parts) == 1, parts
-    assert inline_parts[0]["inlineData"] == {
-        "mimeType": "image/jpeg",
-        "data": fake,
-    }
+    assert inline_parts[0]["inlineData"] == {"mimeType": "image/jpeg", "data": fake}
 
 
 # ── finish reason mapping ────────────────────────────────────────────
@@ -1412,14 +1387,8 @@ def test_custom_gemini_proxy_uses_openai_dispatch():
         )
         assert client._is_openai_compatible() is True, base
         headers = client._auth_headers()
-        assert "x-goog-api-key" not in {k.lower() for k in headers}, (
-            base,
-            headers,
-        )
-        assert headers["Authorization"] == "Bearer AIza-test-key", (
-            base,
-            headers,
-        )
+        assert "x-goog-api-key" not in {k.lower() for k in headers}, (base, headers)
+        assert headers["Authorization"] == "Bearer AIza-test-key", (base, headers)
 
 
 def test_google_hosted_gemini_still_uses_native_dispatch():
@@ -1493,9 +1462,7 @@ def test_text_model_image_generation_tool_silently_dropped(monkeypatch):
     assert "responseModalities" not in gc, gc
 
 
-def test_empty_text_part_with_thought_signature_emits_extra_content(
-    monkeypatch,
-):
+def test_empty_text_part_with_thought_signature_emits_extra_content(monkeypatch):
     """Gemini 3 can ship a content-free fragment whose only payload is
     `thoughtSignature`. The translator must still surface that signature
     on a delta.extra_content envelope so the next turn can replay it."""
@@ -1584,7 +1551,11 @@ def test_remote_image_url_downloads_and_inlines_as_base64(monkeypatch):
     inline them as base64 inlineData."""
     image_bytes = b"FAKEPNGBYTES"
 
-    async def fake_fetch(url, fallback_mime, max_bytes = None):
+    async def fake_fetch(
+        url,
+        fallback_mime,
+        max_bytes = None,
+    ):
         assert url == "https://cdn.example.com/diagram.png"
         return ("image/png", base64.b64encode(image_bytes).decode("ascii"))
 
@@ -1620,7 +1591,11 @@ def test_remote_image_url_dropped_when_fetch_returns_none(monkeypatch):
     image part is silently dropped instead of forwarding raw bytes
     or a fileData fallback."""
 
-    async def fake_fetch_reject(url, fallback_mime, max_bytes = None):
+    async def fake_fetch_reject(
+        url,
+        fallback_mime,
+        max_bytes = None,
+    ):
         return None
 
     monkeypatch.setattr(ep_mod, "_safe_fetch_image_for_gemini", fake_fetch_reject)
@@ -1677,9 +1652,7 @@ def test_safe_fetch_image_rejects_resolved_private_host(monkeypatch):
 
     monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
     res = asyncio.new_event_loop().run_until_complete(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://internal.example/x.png", "image/png"
-        )
+        ep_mod._safe_fetch_image_for_gemini("https://internal.example/x.png", "image/png")
     )
     assert res is None
 
@@ -1753,9 +1726,7 @@ def test_youtube_and_files_api_uris_stay_as_file_data(monkeypatch):
     parts = captured["body"]["contents"][-1]["parts"]
     file_uris = [p["fileData"]["fileUri"] for p in parts if "fileData" in p]
     assert "https://www.youtube.com/watch?v=abc123" in file_uris, parts
-    assert (
-        "https://generativelanguage.googleapis.com/v1beta/files/abc" in file_uris
-    ), parts
+    assert "https://generativelanguage.googleapis.com/v1beta/files/abc" in file_uris, parts
 
 
 def test_tool_use_prompt_tokens_added_to_input_tokens(monkeypatch):
@@ -1947,9 +1918,7 @@ def test_inline_image_tool_end_carries_thought_signature(monkeypatch):
     )
     chunks = _parse_chunks(lines)
     tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
-    image_ends = [
-        e for e in tool_events if e.get("type") == "tool_end" and e.get("image_b64")
-    ]
+    image_ends = [e for e in tool_events if e.get("type") == "tool_end" and e.get("image_b64")]
     assert image_ends, tool_events
     assert image_ends[0]["google"]["thought_signature"] == "SIG-IMG"
     # Multi-turn image edit must replay the original inlineData part with
@@ -2016,9 +1985,7 @@ def test_code_execution_plot_attaches_inline_image_native_part(monkeypatch):
     chunks = _parse_chunks(lines)
     tool_events = [c["_toolEvent"] for c in chunks if "_toolEvent" in c]
     code_ends = [
-        e
-        for e in tool_events
-        if e.get("type") == "tool_end" and e.get("tool_call_id") == "code_a"
+        e for e in tool_events if e.get("type") == "tool_end" and e.get("tool_call_id") == "code_a"
     ]
     # Two tool_end events on the same id: one for codeExecutionResult,
     # one merging in the inlineData plot. The plot one must carry the
@@ -2065,9 +2032,7 @@ def test_text_chunk_carries_thought_signature(monkeypatch):
     lines = _collect(monkeypatch, sse)
     chunks = _parse_chunks(lines)
     text_chunks = [
-        c
-        for c in chunks
-        if c.get("choices") and c["choices"][0]["delta"].get("content") == "hello"
+        c for c in chunks if c.get("choices") and c["choices"][0]["delta"].get("content") == "hello"
     ]
     assert text_chunks, chunks
     extra = text_chunks[0]["choices"][0]["delta"].get("extra_content")
@@ -2246,8 +2211,7 @@ def test_code_execution_tool_call_replays_native_executable_code(monkeypatch):
     assert "executableCode" in native_keys, parts
     assert "codeExecutionResult" in native_keys, parts
     assert not any(
-        "functionCall" in p
-        and (p["functionCall"] or {}).get("name") == "code_execution"
+        "functionCall" in p and (p["functionCall"] or {}).get("name") == "code_execution"
         for p in parts
     ), parts
     exec_part = next(p for p in parts if "executableCode" in p)
@@ -2303,8 +2267,7 @@ def test_image_generation_tool_call_replays_native_inline_data(monkeypatch):
     assert inline_parts[0]["inlineData"]["data"] == pixel
     assert inline_parts[0].get("thoughtSignature") == "SIG-IMG", inline_parts
     assert not any(
-        "functionCall" in p
-        and (p["functionCall"] or {}).get("name") == "image_generation"
+        "functionCall" in p and (p["functionCall"] or {}).get("name") == "image_generation"
         for p in parts
     ), parts
 
@@ -2371,11 +2334,7 @@ def test_function_declarations_strip_openai_only_schema_keys(monkeypatch):
     )
     tools_arr = captured["body"].get("tools") or []
     decls = next(
-        (
-            t.get("functionDeclarations")
-            for t in tools_arr
-            if "functionDeclarations" in t
-        ),
+        (t.get("functionDeclarations") for t in tools_arr if "functionDeclarations" in t),
         None,
     )
     assert decls is not None, captured["body"]
@@ -2428,11 +2387,7 @@ def test_function_declarations_inline_local_refs_into_gemini_schema(monkeypatch)
     )
     tools_arr = captured["body"].get("tools") or []
     decls = next(
-        (
-            t.get("functionDeclarations")
-            for t in tools_arr
-            if "functionDeclarations" in t
-        ),
+        (t.get("functionDeclarations") for t in tools_arr if "functionDeclarations" in t),
         None,
     )
     assert decls is not None, captured["body"]
@@ -2484,11 +2439,7 @@ def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch)
     )
     tools_arr = captured["body"].get("tools") or []
     decls = next(
-        (
-            t.get("functionDeclarations")
-            for t in tools_arr
-            if "functionDeclarations" in t
-        ),
+        (t.get("functionDeclarations") for t in tools_arr if "functionDeclarations" in t),
         None,
     )
     assert decls is not None
@@ -2503,10 +2454,7 @@ def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch)
     extras = params["properties"]["extras"]
     assert extras.get("type") == "array"
     assert extras.get("items", {}).get("type") == "object"
-    assert (
-        extras.get("items", {}).get("properties", {}).get("zip", {}).get("type")
-        == "string"
-    )
+    assert extras.get("items", {}).get("properties", {}).get("zip", {}).get("type") == "string"
 
 
 def test_function_declarations_self_referential_schema_terminates(monkeypatch):
@@ -2544,11 +2492,7 @@ def test_function_declarations_self_referential_schema_terminates(monkeypatch):
     )
     tools_arr = captured["body"].get("tools") or []
     decls = next(
-        (
-            t.get("functionDeclarations")
-            for t in tools_arr
-            if "functionDeclarations" in t
-        ),
+        (t.get("functionDeclarations") for t in tools_arr if "functionDeclarations" in t),
         None,
     )
     assert decls is not None
@@ -2557,9 +2501,7 @@ def test_function_declarations_self_referential_schema_terminates(monkeypatch):
     assert root.get("properties", {}).get("value", {}).get("type") == "string"
 
 
-def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(
-    monkeypatch,
-):
+def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(monkeypatch):
     """Round 26: when the assistant-side synthetic web_search/web_fetch
     tool_call is dropped from native Gemini history, the matching
     role="tool" follow-up must also be dropped. Otherwise the outbound
@@ -2613,9 +2555,7 @@ def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(
                 assert fr.get("name") != "web_search", contents
 
 
-def test_gemini_native_skips_orphan_function_response_for_native_part_replay(
-    monkeypatch,
-):
+def test_gemini_native_skips_orphan_function_response_for_native_part_replay(monkeypatch):
     """Round 26: code_execution / image_generation tool_calls are
     replayed as Gemini-native executableCode / codeExecutionResult /
     inlineData parts. The matching role="tool" follow-up must NOT then
@@ -2824,9 +2764,7 @@ def test_chat_message_extra_content_round_trips_through_validation():
         }
     )
     assistant_msg = req.messages[1]
-    assert assistant_msg.extra_content == {
-        "google": {"thought_signature": "SIG-TEXT"},
-    }
+    assert assistant_msg.extra_content == {"google": {"thought_signature": "SIG-TEXT"}}
     built = _build_external_messages(
         req.messages,
         supports_vision = True,
@@ -2834,9 +2772,7 @@ def test_chat_message_extra_content_round_trips_through_validation():
         base_url = "https://generativelanguage.googleapis.com/v1beta",
     )
     assistant_out = built[1]
-    assert assistant_out["extra_content"] == {
-        "google": {"thought_signature": "SIG-TEXT"},
-    }
+    assert assistant_out["extra_content"] == {"google": {"thought_signature": "SIG-TEXT"}}
     # Non-Gemini providers must NOT receive extra_content; Google's
     # thought_signature field is unknown to OpenAI / Mistral / etc.
     built_openai = _build_external_messages(
@@ -2904,10 +2840,7 @@ def test_parallel_tool_results_group_into_one_user_block(monkeypatch):
         c
         for c in contents
         if c.get("role") == "user"
-        and all(
-            isinstance(p, dict) and "functionResponse" in p
-            for p in (c.get("parts") or [])
-        )
+        and all(isinstance(p, dict) and "functionResponse" in p for p in (c.get("parts") or []))
     ]
     assert len(tool_result_users) == 1, contents
     fr_parts = tool_result_users[0]["parts"]
@@ -2967,9 +2900,7 @@ def test_image_picker_model_with_search_off_pill_strips_text_tools(monkeypatch):
     )
     body = captured["body"]
     assert "tools" not in body, body.get("tools")
-    assert "thinkingConfig" not in body.get("generationConfig", {}), body[
-        "generationConfig"
-    ]
+    assert "thinkingConfig" not in body.get("generationConfig", {}), body["generationConfig"]
 
 
 def test_image_models_drop_function_declarations(monkeypatch):
@@ -2987,10 +2918,7 @@ def test_image_models_drop_function_declarations(monkeypatch):
         ],
     )
     assert captured["body"].get("tools") is None
-    assert captured["body"]["generationConfig"]["responseModalities"] == [
-        "TEXT",
-        "IMAGE",
-    ]
+    assert captured["body"]["generationConfig"]["responseModalities"] == ["TEXT", "IMAGE"]
 
 
 def test_safe_fetch_image_rejects_malformed_bracketed_url():
@@ -3001,9 +2929,7 @@ def test_safe_fetch_image_rejects_malformed_bracketed_url():
     assert res is None
 
 
-def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(
-    monkeypatch,
-):
+def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(monkeypatch):
     """Round 17: the fetch helper must pin the validated IP into the
     outgoing request URL (with a Host header carrying the original
     hostname). A second hostname-style getaddrinfo after the validate
@@ -3046,7 +2972,11 @@ def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(
             return b"PNG"
 
     class _StubOpener:
-        def open(self, req, timeout = None):
+        def open(
+            self,
+            req,
+            timeout = None,
+        ):
             captured["requests"].append(
                 {
                     "url": req.full_url,
@@ -3055,22 +2985,14 @@ def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(
             )
             return _StubResp()
 
-    monkeypatch.setattr(
-        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
-    )
+    monkeypatch.setattr("urllib.request.build_opener", lambda *_args, **_kw: _StubOpener())
 
-    res = _drive(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://cdn.example.com/x.png", "image/png"
-        )
-    )
+    res = _drive(ep_mod._safe_fetch_image_for_gemini("https://cdn.example.com/x.png", "image/png"))
     assert res is not None
     assert res[0] == "image/png"
     # The outgoing URL must use the pinned IP literal, not the hostname.
     assert any("8.8.8.8" in r["url"] for r in captured["requests"]), captured
-    assert all(
-        "cdn.example.com" not in r["url"] for r in captured["requests"]
-    ), captured
+    assert all("cdn.example.com" not in r["url"] for r in captured["requests"]), captured
     # Host header still carries the original hostname for vhost/SNI.
     assert captured["requests"][0]["host_header"] == "cdn.example.com"
 
@@ -3109,7 +3031,11 @@ def test_safe_fetch_image_redirect_to_private_host_rejected(monkeypatch):
     monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
 
     class _StubOpener:
-        def open(self, req, timeout = None):
+        def open(
+            self,
+            req,
+            timeout = None,
+        ):
             # Simulate a 302 to a private host.
             raise urllib.error.HTTPError(
                 req.full_url,
@@ -3119,15 +3045,9 @@ def test_safe_fetch_image_redirect_to_private_host_rejected(monkeypatch):
                 None,
             )
 
-    monkeypatch.setattr(
-        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
-    )
+    monkeypatch.setattr("urllib.request.build_opener", lambda *_args, **_kw: _StubOpener())
 
-    res = _drive(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://cdn.example.com/x.png", "image/png"
-        )
-    )
+    res = _drive(ep_mod._safe_fetch_image_for_gemini("https://cdn.example.com/x.png", "image/png"))
     assert res is None
 
 
@@ -3140,7 +3060,11 @@ def test_files_api_substring_url_not_misclassified_as_filedata(monkeypatch):
     captured_outbound: dict = {}
     fetch_calls: list[str] = []
 
-    async def fake_fetch(url, fallback_mime, max_bytes = None):
+    async def fake_fetch(
+        url,
+        fallback_mime,
+        max_bytes = None,
+    ):
         fetch_calls.append(url)
         return "image/png", base64.b64encode(b"DATA").decode("ascii")
 
@@ -3273,9 +3197,7 @@ def test_legacy_gemini3_pro_medium_coerced_to_high(monkeypatch):
         model = "gemini-3-pro-preview",
         reasoning_effort = "medium",
     )
-    assert captured["body"]["generationConfig"]["thinkingConfig"] == {
-        "thinkingLevel": "high",
-    }
+    assert captured["body"]["generationConfig"]["thinkingConfig"] == {"thinkingLevel": "high"}
 
 
 def test_gemini_3_1_pro_medium_passes_through(monkeypatch):
@@ -3286,9 +3208,7 @@ def test_gemini_3_1_pro_medium_passes_through(monkeypatch):
         model = "gemini-3.1-pro-preview",
         reasoning_effort = "medium",
     )
-    assert captured["body"]["generationConfig"]["thinkingConfig"] == {
-        "thinkingLevel": "medium",
-    }
+    assert captured["body"]["generationConfig"]["thinkingConfig"] == {"thinkingLevel": "medium"}
 
 
 def test_tool_calls_extra_content_stripped_for_non_native_gemini():
@@ -3385,9 +3305,7 @@ def test_user_function_named_with_server_tool_arg_not_dropped(monkeypatch):
                             "type": "function",
                             "function": {
                                 "name": "user_function",
-                                "arguments": json.dumps(
-                                    {"_server_tool": True, "q": "x"}
-                                ),
+                                "arguments": json.dumps({"_server_tool": True, "q": "x"}),
                             },
                         }
                     ],
@@ -3453,9 +3371,7 @@ def test_builtin_named_with_server_tool_marker_dropped(monkeypatch):
                             "type": "function",
                             "function": {
                                 "name": "web_search",
-                                "arguments": json.dumps(
-                                    {"_server_tool": True, "query": "x"}
-                                ),
+                                "arguments": json.dumps({"_server_tool": True, "query": "x"}),
                             },
                         }
                     ],
@@ -3507,9 +3423,7 @@ def test_gemini_tool_choice_none_disables_function_declarations(monkeypatch):
     assert captured["body"].get("tools") is None, captured["body"]
 
 
-def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(
-    monkeypatch,
-):
+def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(monkeypatch):
     """Round 18: multi-branch unions with null (e.g.
     `Union[str, int, None]`) must keep the slim anyOf without the null
     branch and add `nullable: true`; Gemini rejects
@@ -3546,9 +3460,7 @@ def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(
     assert either.get("nullable") is True
     inner = either.get("anyOf")
     assert isinstance(inner, list) and len(inner) == 2, either
-    assert all(
-        not (isinstance(b, dict) and b.get("type") == "null") for b in inner
-    ), inner
+    assert all(not (isinstance(b, dict) and b.get("type") == "null") for b in inner), inner
 
 
 def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
@@ -3576,7 +3488,11 @@ def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
     monkeypatch.setattr(socket, "getaddrinfo", fake_getaddrinfo)
 
     class _StubOpener:
-        def open(self, req, timeout = None):
+        def open(
+            self,
+            req,
+            timeout = None,
+        ):
             raise urllib.error.HTTPError(
                 req.full_url,
                 302,
@@ -3585,26 +3501,16 @@ def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
                 None,
             )
 
-    monkeypatch.setattr(
-        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
-    )
+    monkeypatch.setattr("urllib.request.build_opener", lambda *_args, **_kw: _StubOpener())
 
-    res = _drive(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://cdn.example.com/x.png", "image/png"
-        )
-    )
+    res = _drive(ep_mod._safe_fetch_image_for_gemini("https://cdn.example.com/x.png", "image/png"))
     assert res is None
 
 
 def test_safe_fetch_image_malformed_port_no_crash():
     """Round 18: a URL with a non-numeric port (`https://h:bad/x.png`)
     must not raise; urlparse's port property lazily ValueErrors."""
-    res = _drive(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://example.com:bad/x.png", "image/png"
-        )
-    )
+    res = _drive(ep_mod._safe_fetch_image_for_gemini("https://example.com:bad/x.png", "image/png"))
     assert res is None
 
 
@@ -3646,17 +3552,17 @@ def test_safe_fetch_image_missing_content_type_uses_fallback(monkeypatch):
             return b"PNG"
 
     class _StubOpener:
-        def open(self, req, timeout = None):
+        def open(
+            self,
+            req,
+            timeout = None,
+        ):
             return _StubResp()
 
-    monkeypatch.setattr(
-        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
-    )
+    monkeypatch.setattr("urllib.request.build_opener", lambda *_args, **_kw: _StubOpener())
 
     res = _drive(
-        ep_mod._safe_fetch_image_for_gemini(
-            "https://cdn.example.com/cat.png", "image/png"
-        )
+        ep_mod._safe_fetch_image_for_gemini("https://cdn.example.com/cat.png", "image/png")
     )
     assert res is not None
     assert res[0] == "image/png"
@@ -3737,9 +3643,7 @@ def test_anthropic_translates_openai_tool_calls_into_tool_use_blocks(monkeypatch
     tool_results: list[dict] = []
     for m in msgs:
         if m.get("role") == "user" and isinstance(m.get("content"), list):
-            tool_results.extend(
-                b for b in m["content"] if b.get("type") == "tool_result"
-            )
+            tool_results.extend(b for b in m["content"] if b.get("type") == "tool_result")
     assert any(
         tr.get("tool_use_id") == "call_a" and tr.get("content") == "result_text"
         for tr in tool_results
@@ -4118,7 +4022,11 @@ def test_remote_image_fetch_attempt_cap_includes_failures(monkeypatch):
     failing/slow URLs runs 100 fetches each up to the 15s timeout."""
     fetch_calls: list[str] = []
 
-    async def fake_fetch(url, fallback_mime, max_bytes = None):
+    async def fake_fetch(
+        url,
+        fallback_mime,
+        max_bytes = None,
+    ):
         fetch_calls.append(url)
         return None
 
@@ -4218,9 +4126,7 @@ def test_orphan_function_call_output_dropped_when_call_skipped(monkeypatch):
                             "type": "function",
                             "function": {
                                 "name": "web_search",
-                                "arguments": json.dumps(
-                                    {"_server_tool": True, "query": "x"}
-                                ),
+                                "arguments": json.dumps({"_server_tool": True, "query": "x"}),
                             },
                         }
                     ],
@@ -4281,9 +4187,7 @@ def test_schema_multitype_union_with_null_preserves_anyof(monkeypatch):
     assert either.get("nullable") is True
     inner = either.get("anyOf")
     assert isinstance(inner, list) and len(inner) == 2, either
-    types = sorted(
-        b.get("type") for b in inner if isinstance(b, dict) and b.get("type")
-    )
+    types = sorted(b.get("type") for b in inner if isinstance(b, dict) and b.get("type"))
     assert types == ["integer", "string"], inner
 
 
@@ -4293,7 +4197,11 @@ def test_invalid_gemini_model_rejected_before_image_fetch(monkeypatch):
     runs."""
     fetch_calls: list[str] = []
 
-    async def fake_fetch(url, fallback_mime, max_bytes = None):
+    async def fake_fetch(
+        url,
+        fallback_mime,
+        max_bytes = None,
+    ):
         fetch_calls.append(url)
         return None
 
@@ -4429,9 +4337,7 @@ def test_role_tool_dropped_when_matching_synthetic_call_filtered():
     assert roles == ["user"], result
 
 
-def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(
-    monkeypatch,
-):
+def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(monkeypatch):
     """Round 20: OpenRouter dispatcher must not emit synthetic
     web_search tool_start / tool_end events when tool_choice="none";
     otherwise the chat UI shows a search card for a search that
@@ -4487,14 +4393,10 @@ def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(
 
     _drive(run())
     # No synthetic web_search tool_start / tool_end emitted.
-    assert all(
-        e.get("tool_name") != "web_search" for e in captured_events
-    ), captured_events
+    assert all(e.get("tool_name") != "web_search" for e in captured_events), captured_events
 
 
-def test_anthropic_role_tool_list_content_translates_to_tool_result(
-    monkeypatch,
-):
+def test_anthropic_role_tool_list_content_translates_to_tool_result(monkeypatch):
     """Round 20: an OpenAI-shape role=tool message with list content
     (`content=[{"type":"text","text":"result"}]`) must be translated
     into Anthropic's native tool_result block, not forwarded as an
@@ -4558,9 +4460,7 @@ def test_anthropic_role_tool_list_content_translates_to_tool_result(
     tool_results: list[dict] = []
     for m in msgs:
         if m.get("role") == "user" and isinstance(m.get("content"), list):
-            tool_results.extend(
-                b for b in m["content"] if b.get("type") == "tool_result"
-            )
+            tool_results.extend(b for b in m["content"] if b.get("type") == "tool_result")
     assert any(
         tr.get("tool_use_id") == "call_a" and tr.get("content") == "result_text"
         for tr in tool_results
@@ -4618,9 +4518,7 @@ def test_youtube_filedata_uses_video_mime(monkeypatch):
     assert yt["fileData"]["mimeType"].startswith("video/"), yt
 
 
-def test_openai_responses_assistant_text_serialized_before_function_call(
-    monkeypatch,
-):
+def test_openai_responses_assistant_text_serialized_before_function_call(monkeypatch):
     """Round 20: in OpenAI Responses history, the assistant's
     visible text for a turn that ALSO emitted a function_call must
     serialize BEFORE the function_call item, matching the prior
@@ -4689,13 +4587,7 @@ def test_openai_responses_assistant_text_serialized_before_function_call(
     #   function_call (get_weather)
     #   function_call_output (sunny)
     #   user ("thanks")
-    assert types == [
-        "user",
-        "assistant",
-        "function_call",
-        "function_call_output",
-        "user",
-    ], items
+    assert types == ["user", "assistant", "function_call", "function_call_output", "user"], items
 
 
 def test_gemini_tool_choice_none_disables_image_generation(monkeypatch):
@@ -4765,9 +4657,7 @@ def test_gemini_forced_function_tool_choice_drops_image_generation(monkeypatch):
     assert body["generationConfig"].get("responseModalities") == ["TEXT"], body
 
 
-def test_gemini_code_execution_native_part_list_replays_per_part_signatures(
-    monkeypatch,
-):
+def test_gemini_code_execution_native_part_list_replays_per_part_signatures(monkeypatch):
     """Round 21: merged code-execution history must replay per-part
     `thoughtSignature`s, not fan one top-level signature across every
     native subpart. Gemini 3 strict validators reject a signature
@@ -4832,9 +4722,7 @@ def test_gemini_code_execution_native_part_list_replays_per_part_signatures(
     assert "thoughtSignature" not in result_parts[0], result_parts[0]
 
 
-def test_gemini_code_execution_legacy_merged_signature_only_on_executable(
-    monkeypatch,
-):
+def test_gemini_code_execution_legacy_merged_signature_only_on_executable(monkeypatch):
     """Round 21: backward compatibility for pre-round-21 persisted
     history that stored merged `native_part` as a single object plus a
     top-level `thoughtSignature`. The replay branch must attach that
@@ -4978,12 +4866,14 @@ def test_safe_fetch_image_threads_per_request_byte_budget(monkeypatch):
             return b"\x00" * (5 * 1024 * 1024)
 
     class _StubOpener:
-        def open(self, req, timeout = None):
+        def open(
+            self,
+            req,
+            timeout = None,
+        ):
             return _StubResp()
 
-    monkeypatch.setattr(
-        "urllib.request.build_opener", lambda *_args, **_kw: _StubOpener()
-    )
+    monkeypatch.setattr("urllib.request.build_opener", lambda *_args, **_kw: _StubOpener())
 
     res = _drive(
         ep_mod._safe_fetch_image_for_gemini(
@@ -5006,9 +4896,7 @@ def test_openai_chat_delta_type_includes_tool_calls_and_extra_content():
     import os
 
     here = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-    types_path = os.path.join(
-        here, "frontend", "src", "features", "chat", "types", "api.ts"
-    )
+    types_path = os.path.join(here, "frontend", "src", "features", "chat", "types", "api.ts")
     with open(types_path, "r", encoding = "utf-8") as f:
         src = f.read()
     assert "tool_calls?: OpenAIToolCallPart[]" in src, src[:200]
@@ -5215,9 +5103,7 @@ def test_openai_responses_forced_function_tool_choice_drops_hosted_tools(monkeyp
     assert not (hosted_seen & hosted_types), body
     # The user function declaration must still be present so the pin
     # has something to target.
-    user_function_seen = any(
-        isinstance(t, dict) and t.get("type") == "function" for t in tools
-    )
+    user_function_seen = any(isinstance(t, dict) and t.get("type") == "function" for t in tools)
     assert user_function_seen, body
     # And the forced-function tool_choice must be forwarded in Responses
     # shape: `{type:"function", name:"..."}`.
@@ -5442,9 +5328,7 @@ def test_strip_provider_synthetic_tool_history_drops_empty_assistant():
     assert roles == ["user", "user"], out
 
 
-def test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice(
-    monkeypatch,
-):
+def test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice(monkeypatch):
     """Round 22 sibling of the round-20 `tool_choice='none'` test: when
     the caller forces a specific function via `tool_choice={"type":
     "function", ...}` AND passes `enabled_tools=["web_search"]`, the
@@ -5456,10 +5340,7 @@ def test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice
     def handler(request: httpx.Request) -> httpx.Response:
         return httpx.Response(
             200,
-            content = (
-                b'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n'
-                b"data: [DONE]\n\n"
-            ),
+            content = (b'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n' b"data: [DONE]\n\n"),
             headers = {"content-type": "text/event-stream"},
         )
 
diff --git a/studio/backend/tests/test_gguf_completion_usage.py b/studio/backend/tests/test_gguf_completion_usage.py
index b8cfaee7c7..9f9de80a84 100644
--- a/studio/backend/tests/test_gguf_completion_usage.py
+++ b/studio/backend/tests/test_gguf_completion_usage.py
@@ -30,12 +30,8 @@ class _GgufBackend:
 
 
 def _request_completion(monkeypatch, usage):
-    monkeypatch.setattr(
-        inference_route, "get_llama_cpp_backend", lambda: _GgufBackend(usage)
-    )
-    monkeypatch.setattr(
-        inference_route, "_effective_enable_tools", lambda payload: False
-    )
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: _GgufBackend(usage))
+    monkeypatch.setattr(inference_route, "_effective_enable_tools", lambda payload: False)
 
     app = FastAPI()
     app.include_router(inference_route.router)
diff --git a/studio/backend/tests/test_gguf_metadata.py b/studio/backend/tests/test_gguf_metadata.py
index e5040e306c..08f22edb18 100644
--- a/studio/backend/tests/test_gguf_metadata.py
+++ b/studio/backend/tests/test_gguf_metadata.py
@@ -35,17 +35,11 @@ def _enc_kv_string(key: str, value: str) -> bytes:
 
 
 def _enc_kv_uint32(key: str, value: int) -> bytes:
-    return (
-        _enc_string(key) + struct.pack("<I", _VTYPE_UINT32) + struct.pack("<I", value)
-    )
+    return _enc_string(key) + struct.pack("<I", _VTYPE_UINT32) + struct.pack("<I", value)
 
 
 def _enc_kv_bool(key: str, value: bool) -> bytes:
-    return (
-        _enc_string(key)
-        + struct.pack("<I", _VTYPE_BOOL)
-        + struct.pack("<B", 1 if value else 0)
-    )
+    return _enc_string(key) + struct.pack("<I", _VTYPE_BOOL) + struct.pack("<B", 1 if value else 0)
 
 
 def _enc_kv_string_array(key: str, values: Iterable[str]) -> bytes:
@@ -70,10 +64,7 @@ def _write_synthetic_gguf(
     extra_string_arrays = extra_string_arrays or {}
     extra_bools = extra_bools or {}
     kv_count = (
-        len(general_strings)
-        + len(extra_uint32)
-        + len(extra_string_arrays)
-        + len(extra_bools)
+        len(general_strings) + len(extra_uint32) + len(extra_string_arrays) + len(extra_bools)
     )
     body = b""
     for k, v in general_strings.items():
@@ -126,10 +117,7 @@ def test_extracts_general_string_fields(tmp_path: Path):
     assert meta is not None
     assert meta["general.architecture"] == "qwen2vl"
     assert meta["general.basename"] == "Qwen3.5"
-    assert (
-        meta["general.base_model.0.repo_url"]
-        == "https://huggingface.co/Qwen/Qwen3.5-9B"
-    )
+    assert meta["general.base_model.0.repo_url"] == "https://huggingface.co/Qwen/Qwen3.5-9B"
 
 
 def test_skips_unrelated_fields_without_breaking(tmp_path: Path):
diff --git a/studio/backend/tests/test_gpu_selection.py b/studio/backend/tests/test_gpu_selection.py
index a1fe5653ef..90020efe43 100644
--- a/studio/backend/tests/test_gpu_selection.py
+++ b/studio/backend/tests/test_gpu_selection.py
@@ -64,9 +64,7 @@ class TestResolveRequestedGpuIds(_GpuCacheResetMixin, unittest.TestCase):
 
     def test_parent_visibility_uses_empty_numeric_ids_for_uuid_masks(self):
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
         ):
             self.assertEqual(get_parent_visible_gpu_ids(), [])
@@ -96,9 +94,7 @@ class TestResolveRequestedGpuIds(_GpuCacheResetMixin, unittest.TestCase):
 
     def test_explicit_ids_are_rejected_for_uuid_parent_visibility(self):
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
         ):
             with self.assertRaisesRegex(
@@ -204,13 +200,9 @@ class TestVisibleGpuUtilization(_GpuCacheResetMixin, unittest.TestCase):
             },
         ]
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch("utils.hardware.hardware.get_device", return_value = DeviceType.CUDA),
-            patch(
-                "utils.hardware.hardware._torch_get_physical_gpu_count", return_value = 2
-            ),
+            patch("utils.hardware.hardware._torch_get_physical_gpu_count", return_value = 2),
             patch(
                 "utils.hardware.hardware._torch_get_per_device_info",
                 return_value = fake_torch_devices,
@@ -254,9 +246,7 @@ class TestGpuAutoSelection(_GpuCacheResetMixin, unittest.TestCase):
 
     def test_get_device_map_uses_all_inherited_visible_gpus_for_uuid_masks(self):
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch("utils.hardware.hardware.get_device", return_value = DeviceType.CUDA),
         ):
             self.assertEqual(get_device_map(None), "balanced")
@@ -376,9 +366,7 @@ class TestGpuAutoSelection(_GpuCacheResetMixin, unittest.TestCase):
                 return_value = 1234,
             ),
         ):
-            model_size_bytes, source = _hw_module.estimate_fp16_model_size_bytes(
-                "unsloth/test"
-            )
+            model_size_bytes, source = _hw_module.estimate_fp16_model_size_bytes("unsloth/test")
 
         self.assertEqual(model_size_bytes, 1234)
         self.assertEqual(source, "vllm_utils")
@@ -475,9 +463,7 @@ class TestGpuAutoSelection(_GpuCacheResetMixin, unittest.TestCase):
 
     def test_prepare_gpu_selection_preserves_uuid_parent_visibility_in_auto_mode(self):
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch(
                 "utils.hardware.hardware.estimate_required_model_memory_gb",
                 return_value = (
@@ -524,9 +510,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
             patch(
                 "core.training.training._CTX.Process", return_value = DummyProcess()
             ) as mock_process,
-            patch(
-                "core.training.training.threading.Thread", return_value = DummyThread()
-            ),
+            patch("core.training.training.threading.Thread", return_value = DummyThread()),
         ):
             backend.start_training(
                 job_id = "test-job-1",
@@ -567,9 +551,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
             patch(
                 "core.training.training._CTX.Process", return_value = DummyProcess()
             ) as mock_process,
-            patch(
-                "core.training.training.threading.Thread", return_value = DummyThread()
-            ),
+            patch("core.training.training.threading.Thread", return_value = DummyThread()),
         ):
             backend.start_training(
                 job_id = "test-job-2",
@@ -599,9 +581,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
         dummy_queue = object()
 
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-aaa,GPU-bbb"}, clear = True),
             patch(
                 "core.training.training._CTX.Queue",
                 side_effect = [dummy_queue, dummy_queue],
@@ -609,9 +589,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
             patch(
                 "core.training.training._CTX.Process", return_value = DummyProcess()
             ) as mock_process,
-            patch(
-                "core.training.training.threading.Thread", return_value = DummyThread()
-            ),
+            patch("core.training.training.threading.Thread", return_value = DummyThread()),
             patch(
                 "utils.hardware.hardware.estimate_required_model_memory_gb",
                 return_value = (
@@ -629,9 +607,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
 
         config = mock_process.call_args.kwargs["kwargs"]["config"]
         self.assertIsNone(config["resolved_gpu_ids"])
-        self.assertEqual(
-            config["gpu_selection"]["selection_mode"], "inherit_parent_visible"
-        )
+        self.assertEqual(config["gpu_selection"]["selection_mode"], "inherit_parent_visible")
 
     def test_inference_orchestrator_resolves_explicit_gpu_ids_before_spawn(self):
         class DummyThread:
@@ -643,7 +619,6 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
 
         with patch("core.inference.orchestrator.threading.Thread", DummyThread):
             from core.inference.orchestrator import InferenceOrchestrator
-
             orchestrator = InferenceOrchestrator()
 
         config = SimpleNamespace(identifier = "unsloth/test", gguf_variant = None)
@@ -660,9 +635,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
                 "_wait_response",
                 return_value = {"success": True, "model_info": {}},
             ),
-            patch(
-                "utils.transformers_version.needs_transformers_5", return_value = False
-            ),
+            patch("utils.transformers_version.needs_transformers_5", return_value = False),
         ):
             self.assertTrue(orchestrator.load_model(config = config, gpu_ids = [1]))
 
@@ -681,7 +654,6 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
 
         with patch("core.inference.orchestrator.threading.Thread", DummyThread):
             from core.inference.orchestrator import InferenceOrchestrator
-
             orchestrator = InferenceOrchestrator()
 
         config = SimpleNamespace(identifier = "unsloth/test", gguf_variant = None)
@@ -698,9 +670,7 @@ class TestPreSpawnGpuResolution(_GpuCacheResetMixin, unittest.TestCase):
                 "_wait_response",
                 return_value = {"success": True, "model_info": {}},
             ),
-            patch(
-                "utils.transformers_version.needs_transformers_5", return_value = False
-            ),
+            patch("utils.transformers_version.needs_transformers_5", return_value = False),
         ):
             self.assertTrue(orchestrator.load_model(config = config, gpu_ids = None))
 
@@ -782,9 +752,7 @@ class TestRouteErrors(unittest.TestCase):
                 raise ValueError("Invalid gpu_ids [99]")
 
         with (
-            patch.object(
-                training_route, "get_training_backend", return_value = DummyBackend()
-            ),
+            patch.object(training_route, "get_training_backend", return_value = DummyBackend()),
             patch(
                 "core.inference.get_inference_backend",
                 return_value = SimpleNamespace(active_model_name = None),
@@ -795,9 +763,7 @@ class TestRouteErrors(unittest.TestCase):
             ),
         ):
             with self.assertRaises(HTTPException) as exc_info:
-                asyncio.run(
-                    training_route.start_training(request, current_subject = "test-user")
-                )
+                asyncio.run(training_route.start_training(request, current_subject = "test-user"))
 
         self.assertEqual(exc_info.exception.status_code, 400)
         self.assertIn("gpu_ids [99]", exc_info.exception.detail)
@@ -826,9 +792,7 @@ class TestRouteErrors(unittest.TestCase):
                 )
 
         with (
-            patch.object(
-                training_route, "get_training_backend", return_value = DummyBackend()
-            ),
+            patch.object(training_route, "get_training_backend", return_value = DummyBackend()),
             patch(
                 "core.inference.get_inference_backend",
                 return_value = SimpleNamespace(active_model_name = None),
@@ -839,9 +803,7 @@ class TestRouteErrors(unittest.TestCase):
             ),
         ):
             with self.assertRaises(HTTPException) as exc_info:
-                asyncio.run(
-                    training_route.start_training(request, current_subject = "test-user")
-                )
+                asyncio.run(training_route.start_training(request, current_subject = "test-user"))
 
         self.assertEqual(exc_info.exception.status_code, 400)
         self.assertIn("UUID/MIG", exc_info.exception.detail)
@@ -976,22 +938,17 @@ class TestRouteErrors(unittest.TestCase):
 class TestRaiseIfOffloaded(unittest.TestCase):
     def test_no_offload_is_noop(self):
         from utils.hardware import raise_if_offloaded
-
         model = SimpleNamespace(hf_device_map = {"model.embed_tokens": 0, "lm_head": 1})
         raise_if_offloaded(model, "balanced", "Test")
 
     def test_cpu_offload_raises(self):
         from utils.hardware import raise_if_offloaded
-
-        model = SimpleNamespace(
-            hf_device_map = {"model.layers.0": 0, "model.layers.1": "cpu"}
-        )
+        model = SimpleNamespace(hf_device_map = {"model.layers.0": 0, "model.layers.1": "cpu"})
         with self.assertRaisesRegex(ValueError, "offloaded"):
             raise_if_offloaded(model, "balanced", "Test")
 
     def test_no_device_map_attr_is_noop(self):
         from utils.hardware import raise_if_offloaded
-
         raise_if_offloaded(SimpleNamespace(), "sequential", "Test")
 
 
@@ -1314,7 +1271,6 @@ class TestEstimateFp16ModelSizeBytesPrefersLocalWeights(unittest.TestCase):
         config = object(),
     ):
         from utils.hardware import hardware as hardware_module
-
         with (
             patch.object(
                 hardware_module,
@@ -1395,7 +1351,6 @@ class TestEstimateFp16ModelSizeBytesPrefersLocalWeights(unittest.TestCase):
 
     def test_remote_safetensors_path_unaffected_by_local_weights(self):
         from utils.hardware import hardware as hardware_module
-
         with (
             patch.object(
                 hardware_module,
diff --git a/studio/backend/tests/test_gpu_selection_sandbox.py b/studio/backend/tests/test_gpu_selection_sandbox.py
index 830a98a2fb..073f8d9437 100644
--- a/studio/backend/tests/test_gpu_selection_sandbox.py
+++ b/studio/backend/tests/test_gpu_selection_sandbox.py
@@ -35,7 +35,6 @@ def _make_fake_config(
 ):
     """Create a fake HF config-like object for estimation tests."""
     from types import SimpleNamespace
-
     return SimpleNamespace(
         vocab_size = vocab_size,
         hidden_size = hidden_size,
@@ -122,7 +121,6 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
     def test_inference_fp16_uses_1_3x(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
-
         with patch(
             "utils.hardware.hardware.estimate_fp16_model_size_bytes",
             return_value = (10 * (1024**3), "config"),  # 10GB model
@@ -138,7 +136,6 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
     def test_inference_4bit_uses_reduced_estimate(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
-
         with patch(
             "utils.hardware.hardware.estimate_fp16_model_size_bytes",
             return_value = (30 * (1024**3), "config"),  # 30GB fp16 model
@@ -154,7 +151,6 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
     def test_4bit_training_reduces_base(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
-
         with patch(
             "utils.hardware.hardware.estimate_fp16_model_size_bytes",
             return_value = (30 * (1024**3), "config"),  # 30GB fp16 model
@@ -170,7 +166,6 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
     def test_full_finetune_uses_3_5x(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
-
         with patch(
             "utils.hardware.hardware.estimate_fp16_model_size_bytes",
             return_value = (10 * (1024**3), "config"),  # 10GB model
@@ -185,7 +180,6 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
     def test_returns_none_when_unavailable(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
-
         with patch(
             "utils.hardware.hardware.estimate_fp16_model_size_bytes",
             return_value = (None, "unavailable"),
@@ -214,7 +208,6 @@ class TestAutoSelectGpuIds(unittest.TestCase):
     def test_single_gpu_sufficient(self):
         from utils.hardware.hardware import auto_select_gpu_ids
         import utils.hardware.hardware as hw
-
         with (
             patch.object(hw, "get_device", return_value = hw.DeviceType.CUDA),
             patch.object(
@@ -261,7 +254,6 @@ class TestAutoSelectGpuIds(unittest.TestCase):
     def test_two_gpus_needed(self):
         from utils.hardware.hardware import auto_select_gpu_ids
         import utils.hardware.hardware as hw
-
         with (
             patch.object(hw, "get_device", return_value = hw.DeviceType.CUDA),
             patch.object(
@@ -305,7 +297,6 @@ class TestAutoSelectGpuIds(unittest.TestCase):
     def test_non_cuda_returns_none(self):
         from utils.hardware.hardware import auto_select_gpu_ids
         import utils.hardware.hardware as hw
-
         with patch.object(hw, "get_device", return_value = hw.DeviceType.CPU):
             selected, meta = auto_select_gpu_ids("test/model")
             self.assertIsNone(selected)
@@ -318,7 +309,6 @@ class TestGetDeviceMap(unittest.TestCase):
     def test_single_gpu_returns_sequential(self):
         from utils.hardware.hardware import get_device_map
         import utils.hardware.hardware as hw
-
         with (
             patch.object(hw, "get_device", return_value = hw.DeviceType.CUDA),
             patch.object(
@@ -338,7 +328,6 @@ class TestGetDeviceMap(unittest.TestCase):
     def test_multi_gpu_returns_balanced(self):
         from utils.hardware.hardware import get_device_map
         import utils.hardware.hardware as hw
-
         with patch.object(hw, "get_device", return_value = hw.DeviceType.CUDA):
             dm = get_device_map(gpu_ids = [0, 1])
             self.assertEqual(dm, "balanced")
@@ -346,7 +335,6 @@ class TestGetDeviceMap(unittest.TestCase):
     def test_cpu_returns_sequential(self):
         from utils.hardware.hardware import get_device_map
         import utils.hardware.hardware as hw
-
         with patch.object(hw, "get_device", return_value = hw.DeviceType.CPU):
             dm = get_device_map(gpu_ids = None)
             self.assertEqual(dm, "sequential")
@@ -357,7 +345,6 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
     def test_none_returns_parent_visible(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
-
         with (
             patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "2,3"}, clear = False),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
@@ -367,7 +354,6 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
     def test_empty_list_returns_parent_visible(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
-
         with (
             patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "2,3"}, clear = False),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
@@ -377,7 +363,6 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
     def test_duplicates_rejected(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
-
         with (
             patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "0,1,2"}, clear = False),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
@@ -387,7 +372,6 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
     def test_out_of_range_rejected(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
-
         with (
             patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "0,1"}, clear = False),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 4),
@@ -397,11 +381,8 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
     def test_uuid_env_var_rejects_explicit_ids(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
-
         with (
-            patch.dict(
-                os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-abc,GPU-def"}, clear = False
-            ),
+            patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": "GPU-abc,GPU-def"}, clear = False),
             patch("utils.hardware.hardware.get_physical_gpu_count", return_value = 8),
         ):
             with self.assertRaises(ValueError):
@@ -413,7 +394,6 @@ class TestApplyGpuIds(unittest.TestCase):
 
     def test_apply_list(self):
         from utils.hardware.hardware import apply_gpu_ids
-
         with patch.dict(os.environ, {}, clear = False):
             apply_gpu_ids([3, 5])
             self.assertEqual(os.environ.get("CUDA_VISIBLE_DEVICES"), "3,5")
diff --git a/studio/backend/tests/test_host_defaults.py b/studio/backend/tests/test_host_defaults.py
index 8b81474e92..02bb54df56 100644
--- a/studio/backend/tests/test_host_defaults.py
+++ b/studio/backend/tests/test_host_defaults.py
@@ -20,10 +20,7 @@ def _parse_function_param_defaults(source: str, func_name: str) -> dict:
     """
     tree = ast.parse(source)
     for node in ast.walk(tree):
-        if (
-            isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
-            and node.name == func_name
-        ):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == func_name:
             result = {}
             all_args = node.args.args
             defaults = node.args.defaults
@@ -71,9 +68,7 @@ def test_run_server_default_host_is_loopback():
     """
     source = _RUN_PY.read_text()
     defaults = _parse_function_param_defaults(source, "run_server")
-    assert (
-        "host" in defaults
-    ), "run_server() must have a 'host' parameter with a default"
+    assert "host" in defaults, "run_server() must have a 'host' parameter with a default"
     host_default = defaults["host"]
     assert host_default == "127.0.0.1", (
         f"run_server() host default must be '127.0.0.1' (loopback) "
@@ -90,9 +85,7 @@ def test_argparse_default_host_is_loopback():
     """
     source = _RUN_PY.read_text()
     host_default = _parse_argparse_add_argument_default(source, "--host")
-    assert (
-        host_default is not None
-    ), "Could not find add_argument('--host', ...) in run.py"
+    assert host_default is not None, "Could not find add_argument('--host', ...) in run.py"
     assert (
         host_default == "127.0.0.1"
     ), f"run.py argparse --host default must be '127.0.0.1', got '{host_default}'"
diff --git a/studio/backend/tests/test_index_bootstrap_origin.py b/studio/backend/tests/test_index_bootstrap_origin.py
index 89f7613ee4..b36e3fcedd 100644
--- a/studio/backend/tests/test_index_bootstrap_origin.py
+++ b/studio/backend/tests/test_index_bootstrap_origin.py
@@ -13,7 +13,11 @@ from unittest.mock import MagicMock
 import pytest
 
 
-def _build_request(host: str, origin: str | None, scheme: str = "http") -> MagicMock:
+def _build_request(
+    host: str,
+    origin: str | None,
+    scheme: str = "http",
+) -> MagicMock:
     request = MagicMock()
     request.url.scheme = scheme
     request.url.netloc = host
@@ -23,21 +27,18 @@ def _build_request(host: str, origin: str | None, scheme: str = "http") -> Magic
 
 def test_is_same_origin_request_missing_origin_is_same_origin(monkeypatch):
     from main import _is_same_origin_request
-
     req = _build_request("127.0.0.1:8888", origin = None)
     assert _is_same_origin_request(req) is True
 
 
 def test_is_same_origin_request_matching_origin_is_same_origin():
     from main import _is_same_origin_request
-
     req = _build_request("127.0.0.1:8888", origin = "http://127.0.0.1:8888")
     assert _is_same_origin_request(req) is True
 
 
 def test_is_same_origin_request_evil_origin_is_cross_origin():
     from main import _is_same_origin_request
-
     req = _build_request("127.0.0.1:8888", origin = "https://evil.example")
     assert _is_same_origin_request(req) is False
 
@@ -45,7 +46,6 @@ def test_is_same_origin_request_evil_origin_is_cross_origin():
 def test_is_same_origin_request_scheme_mismatch_is_cross_origin():
     # https origin against an http listener is not same-origin.
     from main import _is_same_origin_request
-
     req = _build_request("127.0.0.1:8888", origin = "https://127.0.0.1:8888")
     assert _is_same_origin_request(req) is False
 
@@ -53,7 +53,6 @@ def test_is_same_origin_request_scheme_mismatch_is_cross_origin():
 def test_is_same_origin_request_port_mismatch_is_cross_origin():
     # Same host different port is not same-origin per the web platform.
     from main import _is_same_origin_request
-
     req = _build_request("127.0.0.1:8888", origin = "http://127.0.0.1:5173")
     assert _is_same_origin_request(req) is False
 
@@ -67,15 +66,12 @@ def test_is_same_origin_request_https_default_port_stripped_on_origin():
     """
     from main import _is_same_origin_request
 
-    req = _build_request(
-        "example.com:443", origin = "https://example.com", scheme = "https"
-    )
+    req = _build_request("example.com:443", origin = "https://example.com", scheme = "https")
     assert _is_same_origin_request(req) is True
 
 
 def test_is_same_origin_request_http_default_port_stripped_on_origin():
     from main import _is_same_origin_request
-
     req = _build_request("example.com:80", origin = "http://example.com")
     assert _is_same_origin_request(req) is True
 
@@ -84,9 +80,7 @@ def test_is_same_origin_request_default_port_present_on_origin():
     """Mirror case: Origin carries the default port, netloc doesn't. Same-origin."""
     from main import _is_same_origin_request
 
-    req = _build_request(
-        "example.com", origin = "https://example.com:443", scheme = "https"
-    )
+    req = _build_request("example.com", origin = "https://example.com:443", scheme = "https")
     assert _is_same_origin_request(req) is True
 
 
@@ -138,7 +132,5 @@ def test_is_same_origin_request_explicit_non_default_port_still_mismatch():
     """Canonicalisation does NOT collapse non-default ports to default."""
     from main import _is_same_origin_request
 
-    req = _build_request(
-        "example.com", origin = "https://example.com:9999", scheme = "https"
-    )
+    req = _build_request("example.com", origin = "https://example.com:9999", scheme = "https")
     assert _is_same_origin_request(req) is False
diff --git a/studio/backend/tests/test_index_bootstrap_origin_extra.py b/studio/backend/tests/test_index_bootstrap_origin_extra.py
index aea6b36a96..71fdbad930 100644
--- a/studio/backend/tests/test_index_bootstrap_origin_extra.py
+++ b/studio/backend/tests/test_index_bootstrap_origin_extra.py
@@ -10,7 +10,11 @@ the ``localhost`` vs ``127.0.0.1`` distinct-origin rule.
 from unittest.mock import MagicMock
 
 
-def _build_request(host: str, origin, scheme: str = "http") -> MagicMock:
+def _build_request(
+    host: str,
+    origin,
+    scheme: str = "http",
+) -> MagicMock:
     request = MagicMock()
     request.url.scheme = scheme
     request.url.netloc = host
@@ -34,7 +38,6 @@ def test_is_same_origin_request_ipv6_loopback_same_origin():
 
 def test_is_same_origin_request_ipv6_full_address_same_origin():
     from main import _is_same_origin_request
-
     req = _build_request(
         "[2001:db8::1]:8443",
         origin = "https://[2001:db8::1]:8443",
@@ -65,21 +68,18 @@ def test_is_same_origin_request_ipv6_case_insensitive():
 
 def test_is_same_origin_request_ipv6_different_host_cross_origin():
     from main import _is_same_origin_request
-
     req = _build_request("[::1]:8902", origin = "http://[2001:db8::1]:8902")
     assert _is_same_origin_request(req) is False
 
 
 def test_is_same_origin_request_ipv6_port_mismatch_cross_origin():
     from main import _is_same_origin_request
-
     req = _build_request("[::1]:8902", origin = "http://[::1]:9999")
     assert _is_same_origin_request(req) is False
 
 
 def test_is_same_origin_request_ipv6_userinfo_stripped():
     from main import _is_same_origin_request
-
     req = _build_request("user:pass@[::1]:8902", origin = "http://[::1]:8902")
     assert _is_same_origin_request(req) is True
 
@@ -93,9 +93,7 @@ def test_is_same_origin_request_data_url_origin_is_cross_origin():
     """
     from main import _is_same_origin_request
 
-    req = _build_request(
-        "127.0.0.1:8902", origin = "data:text/html,<script>alert(1)</script>"
-    )
+    req = _build_request("127.0.0.1:8902", origin = "data:text/html,<script>alert(1)</script>")
     assert _is_same_origin_request(req) is False
 
 
@@ -150,7 +148,6 @@ def test_is_same_origin_request_localhost_vs_127_is_cross_origin():
 
 def test_is_same_origin_request_127_vs_localhost_is_cross_origin():
     from main import _is_same_origin_request
-
     req = _build_request("localhost:8902", origin = "http://127.0.0.1:8902")
     assert _is_same_origin_request(req) is False
 
diff --git a/studio/backend/tests/test_inference_model_validation.py b/studio/backend/tests/test_inference_model_validation.py
index ebd9c6c722..faf5a67873 100644
--- a/studio/backend/tests/test_inference_model_validation.py
+++ b/studio/backend/tests/test_inference_model_validation.py
@@ -202,10 +202,7 @@ def test_walkback_skips_explicitly_consumed_tool_call_id():
             {"role": "tool", "content": "second result"},
         ]
     )
-    assert [m.tool_call_id for m in req.messages if m.role == "tool"] == [
-        "call_a",
-        "call_b",
-    ]
+    assert [m.tool_call_id for m in req.messages if m.role == "tool"] == ["call_a", "call_b"]
 
 
 def test_walkback_handles_malformed_function_string():
diff --git a/studio/backend/tests/test_kv_cache_estimation.py b/studio/backend/tests/test_kv_cache_estimation.py
index d52a58a25c..001b5f1bee 100644
--- a/studio/backend/tests/test_kv_cache_estimation.py
+++ b/studio/backend/tests/test_kv_cache_estimation.py
@@ -128,7 +128,9 @@ def _make_gguf_bytes(arch: str, kv_pairs: dict) -> bytes:
 
 
 def _backend_from_gguf(
-    arch: str, fields: dict, general: dict | None = None
+    arch: str,
+    fields: dict,
+    general: dict | None = None,
 ) -> LlamaCppBackend:
     """Create a LlamaCppBackend with parsed GGUF metadata from given fields.
 
@@ -346,8 +348,7 @@ class TestArchSwaPatternDefaults:
         assert kv_default > 0
         assert kv_legacy > 0
         assert kv_default < kv_legacy, (
-            f"arch fallback should under-shoot legacy estimate: "
-            f"{kv_default} >= {kv_legacy}"
+            f"arch fallback should under-shoot legacy estimate: " f"{kv_default} >= {kv_legacy}"
         )
 
     def test_scalar_sliding_window_pattern_expanded(self):
@@ -430,25 +431,12 @@ class TestDynamicSwaResolver:
         from core.inference.llama_cpp import _period_from_layer_types
 
         # gemma3 (1 global per 6), gpt-oss (alternating), gemma3n (1 per 5).
-        assert (
-            _period_from_layer_types(
-                (["sliding_attention"] * 5 + ["full_attention"]) * 4
-            )
-            == 6
-        )
-        assert (
-            _period_from_layer_types(["sliding_attention", "full_attention"] * 12) == 2
-        )
-        assert (
-            _period_from_layer_types(
-                (["sliding_attention"] * 4 + ["full_attention"]) * 7
-            )
-            == 5
-        )
+        assert _period_from_layer_types((["sliding_attention"] * 5 + ["full_attention"]) * 4) == 6
+        assert _period_from_layer_types(["sliding_attention", "full_attention"] * 12) == 2
+        assert _period_from_layer_types((["sliding_attention"] * 4 + ["full_attention"]) * 7) == 5
 
     def test_period_from_layer_types_returns_none_for_aperiodic(self):
         from core.inference.llama_cpp import _period_from_layer_types
-
         lt = [
             "sliding_attention",
             "full_attention",
@@ -469,9 +457,7 @@ class TestDynamicSwaResolver:
             == "google/gemma-3-1b-it"
         )
         assert (
-            _hf_repo_from_url(
-                "https://huggingface.co/google/gemma-3-1b-it/blob/main/config.json"
-            )
+            _hf_repo_from_url("https://huggingface.co/google/gemma-3-1b-it/blob/main/config.json")
             == "google/gemma-3-1b-it"
         )
         for bad in [
@@ -524,9 +510,7 @@ class TestDynamicSwaResolver:
         b = _backend_from_gguf(
             "newmodel",
             _SWA_FIELDS,
-            general = {
-                "general.source.huggingface.repository": "vendor/newmodel-1b-instruct"
-            },
+            general = {"general.source.huggingface.repository": "vendor/newmodel-1b-instruct"},
         )
         assert b._sliding_window_pattern == [(i + 1) % 4 != 0 for i in range(12)]
         assert calls == ["vendor/newmodel-1b-instruct"]
@@ -573,9 +557,7 @@ class TestDynamicSwaResolver:
 
         monkeypatch.setattr(lc, "_fetch_swa_entry_from_hf", lambda repo_id: None)
         # Force the failure into the Tier 3 path; bypass Tier 2.5.
-        monkeypatch.setattr(
-            lc, "_resolve_swa_entry_from_transformers", lambda arch: None
-        )
+        monkeypatch.setattr(lc, "_resolve_swa_entry_from_transformers", lambda arch: None)
         b = _backend_from_gguf(
             "newmodel",
             _SWA_FIELDS,
@@ -621,18 +603,14 @@ class TestTransformersIntrospection:
 
         class _FakeLazyMapping(dict):
             def __getitem__(self, k):
-                return (
-                    _FakeBrokenConfig if k == "brokenarch" else super().__getitem__(k)
-                )
+                return _FakeBrokenConfig if k == "brokenarch" else super().__getitem__(k)
 
         import sys, types as _types
 
         fake_auto = _types.ModuleType("transformers.models.auto.configuration_auto")
         fake_auto.CONFIG_MAPPING_NAMES = {"brokenarch": "FakeBroken"}
         fake_auto.CONFIG_MAPPING = _FakeLazyMapping({"brokenarch": "FakeBroken"})
-        monkeypatch.setitem(
-            sys.modules, "transformers.models.auto.configuration_auto", fake_auto
-        )
+        monkeypatch.setitem(sys.modules, "transformers.models.auto.configuration_auto", fake_auto)
         assert lc._resolve_swa_entry_from_transformers("brokenarch") == 7
 
     def test_returns_none_when_transformers_unavailable(self, monkeypatch):
@@ -658,12 +636,9 @@ class TestTransformersIntrospection:
 
     def test_returns_none_for_arch_unknown_to_transformers(self):
         from core.inference.llama_cpp import _resolve_swa_entry_from_transformers
-
         assert _resolve_swa_entry_from_transformers("totally-fake-arch-xyz") is None
 
-    def test_full_resolver_uses_transformers_before_hf_fetch(
-        self, monkeypatch, tmp_path
-    ):
+    def test_full_resolver_uses_transformers_before_hf_fetch(self, monkeypatch, tmp_path):
         # With bootstrap empty, Tier 2.5 must answer before Tier 3 fires.
         self._isolate_cache(monkeypatch, tmp_path)
         from core.inference import llama_cpp as lc
@@ -1328,8 +1303,7 @@ class TestServerFlags:
             "_kv_key_length": 256,
             "_kv_value_length": 256,
             "_sliding_window": 512,
-            "_sliding_window_pattern": [True, True, True, True, True, False] * 4
-            + [True, True],
+            "_sliding_window_pattern": [True, True, True, True, True, False] * 4 + [True, True],
         }
         defaults.update(overrides)
         b = LlamaCppBackend()
@@ -1385,9 +1359,7 @@ class TestServerFlags:
     def test_swa_full_suppresses_checkpoint_term(self):
         b = self._swa_backend()
         with_cp = b._estimate_kv_cache_bytes(8192, "f16", ctx_checkpoints = 8)
-        with_cp_full = b._estimate_kv_cache_bytes(
-            8192, "f16", ctx_checkpoints = 8, swa_full = True
-        )
+        with_cp_full = b._estimate_kv_cache_bytes(8192, "f16", ctx_checkpoints = 8, swa_full = True)
         no_cp_full = b._estimate_kv_cache_bytes(8192, "f16", swa_full = True)
         # Checkpoints only matter when SWA layers don't already keep n_ctx.
         assert with_cp_full == no_cp_full
@@ -1405,9 +1377,7 @@ class TestServerFlags:
         for slots in (1, 2, 4, 8):
             for unified in (True, False):
                 assert (
-                    b._estimate_kv_cache_bytes(
-                        4096, "f16", n_parallel = slots, kv_unified = unified
-                    )
+                    b._estimate_kv_cache_bytes(4096, "f16", n_parallel = slots, kv_unified = unified)
                     == baseline
                 )
 
@@ -1416,9 +1386,7 @@ class TestServerFlags:
         baseline = b._estimate_kv_cache_bytes(4096, "f16")
         for unified in (True, False):
             assert (
-                b._estimate_kv_cache_bytes(
-                    4096, "f16", n_parallel = 0, kv_unified = unified
-                )
+                b._estimate_kv_cache_bytes(4096, "f16", n_parallel = 0, kv_unified = unified)
                 == baseline
             )
 
@@ -1432,9 +1400,7 @@ class TestServerFlags:
         per_token_swa = 4 * (256 + 256) * 2  # k_swa/val_swa fall back
         per_slot_swa_cells = min(ctx, 2 * swa)  # not clamped at parallel=1
         global_bytes = sum(
-            ctx * per_token_global
-            for f in b._sliding_window_pattern[: b._n_layers]
-            if not f
+            ctx * per_token_global for f in b._sliding_window_pattern[: b._n_layers] if not f
         )
         swa_bytes_per_slot = sum(
             per_slot_swa_cells * per_token_swa
@@ -1445,16 +1411,12 @@ class TestServerFlags:
         assert global_bytes + swa_bytes_per_slot == baseline
         # Only SWA portion scales by parallel
         for slots in (1, 2, 3, 4):
-            scaled = b._estimate_kv_cache_bytes(
-                ctx, "f16", n_parallel = slots, kv_unified = False
-            )
+            scaled = b._estimate_kv_cache_bytes(ctx, "f16", n_parallel = slots, kv_unified = False)
             # SWA cells get clamped to per_slot_ctx when ctx/slots < 2*swa
             per_slot_ctx = max(1, ctx // slots)
             cells = min(ctx, 2 * swa, per_slot_ctx)
             swa_bps = sum(
-                cells * per_token_swa
-                for f in b._sliding_window_pattern[: b._n_layers]
-                if f
+                cells * per_token_swa for f in b._sliding_window_pattern[: b._n_layers] if f
             )
             assert scaled == global_bytes + slots * swa_bps
 
@@ -1469,9 +1431,7 @@ class TestServerFlags:
         for slots in (1, 2, 4, 8):
             for unified in (True, False):
                 assert (
-                    b._estimate_kv_cache_bytes(
-                        8192, "f16", n_parallel = slots, kv_unified = unified
-                    )
+                    b._estimate_kv_cache_bytes(8192, "f16", n_parallel = slots, kv_unified = unified)
                     == baseline
                 )
 
@@ -1493,9 +1453,7 @@ class TestServerFlags:
         baseline = b._estimate_kv_cache_bytes(ctx, "f16")
         flagged = b._estimate_kv_cache_bytes(ctx, "f16", ctx_checkpoints = 4)
         # 22 SWA layers * 4 checkpoints * 512 cells * 4 heads * (256+256) * 2 bytes
-        n_swa_layers = sum(
-            1 for f in [True, True, True, True, True, False] * 4 + [True, True] if f
-        )
+        n_swa_layers = sum(1 for f in [True, True, True, True, True, False] * 4 + [True, True] if f)
         per_layer = 4 * 512 * 4 * (256 + 256) * 2
         assert flagged == baseline + n_swa_layers * per_layer
 
@@ -1529,9 +1487,7 @@ class TestServerFlags:
         flagged = b._estimate_kv_cache_bytes(
             ctx, "f16", ctx_checkpoints = 4, n_parallel = slots, kv_unified = False
         )
-        assert flagged == global_bytes + slots * (
-            swa_bytes_per_slot + cp_extra_per_slot
-        )
+        assert flagged == global_bytes + slots * (swa_bytes_per_slot + cp_extra_per_slot)
 
     # ── --kv-offload (kv_on_gpu) ───────────────────────────────────
 
@@ -1655,9 +1611,7 @@ class TestParallelSWAScaling:
             "_kv_value_length": 256,
             "_sliding_window": 512,
             # 15 SWA + 3 global, mirrors gemma-3-270m
-            "_sliding_window_pattern": [
-                t == "swa" for t in (["swa"] * 5 + ["global"]) * 3
-            ],
+            "_sliding_window_pattern": [t == "swa" for t in (["swa"] * 5 + ["global"]) * 3],
         }
         defaults.update(overrides)
         b = LlamaCppBackend()
@@ -1673,9 +1627,7 @@ class TestParallelSWAScaling:
         for slots in (1, 2, 4, 8):
             for unified in (True, False):
                 assert (
-                    b._estimate_kv_cache_bytes(
-                        8192, "f16", n_parallel = slots, kv_unified = unified
-                    )
+                    b._estimate_kv_cache_bytes(8192, "f16", n_parallel = slots, kv_unified = unified)
                     == baseline
                 )
 
@@ -1729,9 +1681,7 @@ class TestParallelSWAScaling:
             cells = min(ctx, 2 * swa, per_slot_ctx)
             swa_bps = n_swa * cells * per_token
             for unified in (True, False):
-                got = b._estimate_kv_cache_bytes(
-                    ctx, "f16", n_parallel = slots, kv_unified = unified
-                )
+                got = b._estimate_kv_cache_bytes(ctx, "f16", n_parallel = slots, kv_unified = unified)
                 assert got == global_bytes + slots * swa_bps
 
     def test_swa_fallback_scales_only_swa_portion(self):
@@ -1776,8 +1726,7 @@ class TestParallelSWAScaling:
         baseline = b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True)
         for slots in (1, 2, 4, 8):
             assert (
-                b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True, n_parallel = slots)
-                == baseline
+                b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True, n_parallel = slots) == baseline
             )
 
     # ── kv_unified: no-op for memory math ──────────────────────────
@@ -1791,12 +1740,8 @@ class TestParallelSWAScaling:
         ]
         for label, b in backends:
             for slots in (1, 2, 4, 8):
-                u = b._estimate_kv_cache_bytes(
-                    8192, "f16", n_parallel = slots, kv_unified = True
-                )
-                nu = b._estimate_kv_cache_bytes(
-                    8192, "f16", n_parallel = slots, kv_unified = False
-                )
+                u = b._estimate_kv_cache_bytes(8192, "f16", n_parallel = slots, kv_unified = True)
+                nu = b._estimate_kv_cache_bytes(8192, "f16", n_parallel = slots, kv_unified = False)
                 assert u == nu, f"{label} parallel={slots} unified-mismatch"
 
     # ── Empirical Gemma-3 270m formula ─────────────────────────────
@@ -1937,9 +1882,7 @@ class TestSharedKVLayers:
         assert full_in_unshared == 4
         kv_per = 4 * (256 + 256) * 2
         swa_cells = min(ctx, 2 * 1024)
-        expected = (
-            full_in_unshared * ctx * kv_per + sliding_in_unshared * swa_cells * kv_per
-        )
+        expected = full_in_unshared * ctx * kv_per + sliding_in_unshared * swa_cells * kv_per
         assert b._estimate_kv_cache_bytes(ctx, "f16") == expected
 
     def test_shared_layers_reduces_estimate(self):
@@ -1995,9 +1938,7 @@ class TestSharedKVLayers:
         per_slot_ctx = max(1, ctx // slots)
         swa_cells = min(ctx, 2 * swa, per_slot_ctx)
         swa_bytes_per_slot = sliding_in_unshared * swa_cells * per_token
-        flagged = b._estimate_kv_cache_bytes(
-            ctx, "f16", n_parallel = slots, kv_unified = False
-        )
+        flagged = b._estimate_kv_cache_bytes(ctx, "f16", n_parallel = slots, kv_unified = False)
         assert flagged == global_bytes + slots * swa_bytes_per_slot
 
     def test_composes_with_ctx_checkpoints(self):
diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
index 5d2d672890..f887f7747c 100644
--- a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -134,12 +134,8 @@ def test_unknown_gpu_not_in_families():
 def test_asset_resolves_for_known_gpu(gfx, os_prefix, windows):
     host = _make_rocm_host(gfx, windows = windows)
     with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
-        result = resolve_lemonade_rocm_choice(
-            host, os_prefix, "default", llama_tag = "latest"
-        )
-    assert (
-        result is not None
-    ), f"Installer will NOT fetch lemonade binary for {gfx} ({os_prefix})"
+        result = resolve_lemonade_rocm_choice(host, os_prefix, "default", llama_tag = "latest")
+    assert result is not None, f"Installer will NOT fetch lemonade binary for {gfx} ({os_prefix})"
     assert _lookup_family(gfx) in result.name
     assert result.url.startswith("https://github.com/lemonade-sdk/llamacpp-rocm")
 
@@ -213,9 +209,7 @@ def test_simple_policy_plans_lemonade_for_windows_hip_host():
         "assets": [],
     }
     with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
-        plan = direct_upstream_release_plan(
-            release, host, "ggml-org/llama.cpp", "latest"
-        )
+        plan = direct_upstream_release_plan(release, host, "ggml-org/llama.cpp", "latest")
     assert plan is not None, "Windows ROCm host should plan a lemonade HIP attempt"
     kinds = [a.install_kind for a in plan.attempts]
     assert (
@@ -245,9 +239,7 @@ def test_simple_policy_windows_hip_falls_back_to_upstream_when_lemonade_unavaila
     plan = direct_upstream_release_plan(release, host, "ggml-org/llama.cpp", "latest")
     assert plan is not None
     kinds = [a.install_kind for a in plan.attempts]
-    assert (
-        "windows-hip" in kinds
-    ), f"upstream HIP asset not included as fallback; got {kinds}"
+    assert "windows-hip" in kinds, f"upstream HIP asset not included as fallback; got {kinds}"
     hip_attempt = next(a for a in plan.attempts if a.install_kind == "windows-hip")
     assert hip_attempt.source_label == "upstream"
 
@@ -294,9 +286,7 @@ def test_lemonade_resolver_rejects_non_github_url(monkeypatch):
     }
     host = _make_rocm_host("gfx1151")
     with patch.object(_mod, "fetch_json", return_value = bad_release):
-        res = resolve_lemonade_rocm_choice(
-            host, "ubuntu", "linux-rocm", llama_tag = "latest"
-        )
+        res = resolve_lemonade_rocm_choice(host, "ubuntu", "linux-rocm", llama_tag = "latest")
     assert res is None
 
 
@@ -349,9 +339,7 @@ def test_lemonade_resolver_rejects_empty_browser_download_url():
     }
     host = _make_rocm_host("gfx1151")
     with patch.object(_mod, "fetch_json", return_value = release):
-        res = resolve_lemonade_rocm_choice(
-            host, "ubuntu", "linux-rocm", llama_tag = "latest"
-        )
+        res = resolve_lemonade_rocm_choice(host, "ubuntu", "linux-rocm", llama_tag = "latest")
     assert res is None
 
 
diff --git a/studio/backend/tests/test_llama_cpp_context_fit.py b/studio/backend/tests/test_llama_cpp_context_fit.py
index 6fe5372147..ee8d54443a 100644
--- a/studio/backend/tests/test_llama_cpp_context_fit.py
+++ b/studio/backend/tests/test_llama_cpp_context_fit.py
@@ -143,7 +143,11 @@ def _drive(
     model_size = int(model_gib * GIB)
     cache_type_kv = None
 
-    def fake_estimate(n_ctx_, _type = None, **_kwargs):
+    def fake_estimate(
+        n_ctx_,
+        _type = None,
+        **_kwargs,
+    ):
         return 0 if n_ctx_ <= 0 else n_ctx_ * kv_per_token_bytes
 
     inst._estimate_kv_cache_bytes = fake_estimate
@@ -233,9 +237,7 @@ def _drive(
     elif gpus:
         gpu_indices, use_fit = inst._select_gpus(model_size, gpus)
         if use_fit and not explicit_ctx:
-            effective_ctx = (
-                min(FALLBACK_CTX, effective_ctx) if effective_ctx > 0 else FALLBACK_CTX
-            )
+            effective_ctx = min(FALLBACK_CTX, effective_ctx) if effective_ctx > 0 else FALLBACK_CTX
 
     return {
         "c_arg": effective_ctx if effective_ctx > 0 else 0,
diff --git a/studio/backend/tests/test_llama_cpp_freshness.py b/studio/backend/tests/test_llama_cpp_freshness.py
index b32aeefcdb..c7dd111ee3 100644
--- a/studio/backend/tests/test_llama_cpp_freshness.py
+++ b/studio/backend/tests/test_llama_cpp_freshness.py
@@ -172,9 +172,7 @@ def test_latest_published_release_returns_none_on_network_failure(monkeypatch):
     assert fr.latest_published_release("unslothai/llama.cpp") is None
 
 
-def test_latest_published_release_keeps_old_cache_on_transient_failure(
-    monkeypatch, tmp_path
-):
+def test_latest_published_release_keeps_old_cache_on_transient_failure(monkeypatch, tmp_path):
     # Disk entry older than TTL + network fail -> return cached value.
     cache_dir = tmp_path / ".freshness"
     cache_dir.mkdir()
@@ -188,9 +186,7 @@ def test_latest_published_release_keeps_old_cache_on_transient_failure(
 # check_prebuilt_freshness end-to-end.
 
 
-def test_check_prebuilt_freshness_reports_stale_when_old_and_behind(
-    monkeypatch, tmp_path
-):
+def test_check_prebuilt_freshness_reports_stale_when_old_and_behind(monkeypatch, tmp_path):
     install_dir = tmp_path / "llama.cpp"
     _write_marker(
         install_dir,
@@ -200,9 +196,7 @@ def test_check_prebuilt_freshness_reports_stale_when_old_and_behind(
         .replace("+00:00", "Z"),
     )
     bin_path = _fake_binary(install_dir, layout = "root")
-    monkeypatch.setattr(
-        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300"
-    )
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300")
     info = fr.check_prebuilt_freshness(str(bin_path))
     assert info["has_marker"] is True
     assert info["stale"] is True
@@ -222,9 +216,7 @@ def test_check_prebuilt_freshness_not_stale_when_tag_matches(monkeypatch, tmp_pa
         .replace("+00:00", "Z"),
     )
     bin_path = _fake_binary(install_dir, layout = "root")
-    monkeypatch.setattr(
-        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300"
-    )
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300")
     info = fr.check_prebuilt_freshness(str(bin_path))
     assert info["stale"] is False
     assert info["installed_tag"] == "b9300"
@@ -242,9 +234,7 @@ def test_check_prebuilt_freshness_not_stale_within_threshold(monkeypatch, tmp_pa
         .replace("+00:00", "Z"),
     )
     bin_path = _fake_binary(install_dir, layout = "root")
-    monkeypatch.setattr(
-        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300"
-    )
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300")
     info = fr.check_prebuilt_freshness(str(bin_path))
     assert info["stale"] is False
     assert info["age_days"] == 1
@@ -257,9 +247,7 @@ def test_check_prebuilt_freshness_fails_open_without_marker(tmp_path):
     assert info["stale"] is False
 
 
-def test_check_prebuilt_freshness_fails_open_when_github_unreachable(
-    monkeypatch, tmp_path
-):
+def test_check_prebuilt_freshness_fails_open_when_github_unreachable(monkeypatch, tmp_path):
     install_dir = tmp_path / "llama.cpp"
     _write_marker(
         install_dir,
@@ -276,15 +264,11 @@ def test_check_prebuilt_freshness_fails_open_when_github_unreachable(
     assert info["latest_tag"] is None
 
 
-def test_check_prebuilt_freshness_handles_unparseable_install_timestamp(
-    monkeypatch, tmp_path
-):
+def test_check_prebuilt_freshness_handles_unparseable_install_timestamp(monkeypatch, tmp_path):
     install_dir = tmp_path / "llama.cpp"
     _write_marker(install_dir, tag = "b9190", installed_at_utc = "not-a-date")
     bin_path = _fake_binary(install_dir, layout = "root")
-    monkeypatch.setattr(
-        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300"
-    )
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300")
     info = fr.check_prebuilt_freshness(str(bin_path))
     assert info["stale"] is False
     assert info["age_days"] is None
@@ -300,9 +284,7 @@ def test_check_prebuilt_freshness_respects_custom_threshold(monkeypatch, tmp_pat
         .replace("+00:00", "Z"),
     )
     bin_path = _fake_binary(install_dir, layout = "root")
-    monkeypatch.setattr(
-        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300"
-    )
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9300")
     info = fr.check_prebuilt_freshness(str(bin_path), threshold_days = 1)
     assert info["stale"] is True
 
@@ -311,9 +293,7 @@ def test_check_prebuilt_freshness_respects_custom_threshold(monkeypatch, tmp_pat
 
 
 def test_format_stale_warning_contains_actionable_command():
-    msg = fr.format_stale_warning(
-        {"installed_tag": "b9190", "latest_tag": "b9300", "age_days": 5}
-    )
+    msg = fr.format_stale_warning({"installed_tag": "b9190", "latest_tag": "b9300", "age_days": 5})
     assert "b9190" in msg
     assert "b9300" in msg
     assert "5 days" in msg
@@ -321,8 +301,6 @@ def test_format_stale_warning_contains_actionable_command():
 
 
 def test_format_stale_warning_singular_day():
-    msg = fr.format_stale_warning(
-        {"installed_tag": "b9190", "latest_tag": "b9300", "age_days": 1}
-    )
+    msg = fr.format_stale_warning({"installed_tag": "b9190", "latest_tag": "b9300", "age_days": 1})
     assert "1 day" in msg
     assert "1 days" not in msg
diff --git a/studio/backend/tests/test_llama_cpp_load_progress.py b/studio/backend/tests/test_llama_cpp_load_progress.py
index f46751b798..f95d8bf1a4 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress.py
@@ -150,7 +150,6 @@ class TestLoadProgressSingleShard:
         def fake_open(path, *args, **kwargs):
             if str(path).startswith("/proc/"):
                 import io
-
                 return io.StringIO(f"Name:\ttest\nVmRSS:\t{10 * 1024 ** 2}\tkB\n")
             return open(path, *args, **kwargs)  # fall through
 
@@ -175,7 +174,6 @@ class TestLoadProgressSingleShard:
         def fake_open(path, *args, **kwargs):
             if str(path).startswith("/proc/"):
                 import io
-
                 return io.StringIO(f"VmRSS:\t{8 * 1024 ** 2}\tkB\n")
             return open(path, *args, **kwargs)
 
@@ -210,7 +208,6 @@ class TestLoadProgressMultiShard:
         def fake_open(path, *args, **kwargs):
             if str(path).startswith("/proc/"):
                 import io
-
                 return io.StringIO("VmRSS:\t0\tkB\n")
             return open(path, *args, **kwargs)
 
@@ -233,7 +230,6 @@ class TestLoadProgressDegradation:
         def fake_open(path, *args, **kwargs):
             if str(path).startswith("/proc/"):
                 import io
-
                 return io.StringIO("VmRSS:\t1024\tkB\n")
             return open(path, *args, **kwargs)
 
diff --git a/studio/backend/tests/test_llama_cpp_load_progress_live.py b/studio/backend/tests/test_llama_cpp_load_progress_live.py
index beed8713c1..44a8f00834 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress_live.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress_live.py
@@ -75,7 +75,11 @@ pytestmark = pytest.mark.skipif(
 )
 
 
-def _make_backend(pid: int, gguf_path: str, healthy: bool = False):
+def _make_backend(
+    pid: int,
+    gguf_path: str,
+    healthy: bool = False,
+):
     inst = LlamaCppBackend.__new__(LlamaCppBackend)
     inst._process = type("P", (), {"pid": pid})()
     inst._gguf_path = gguf_path
diff --git a/studio/backend/tests/test_llama_cpp_max_context_threshold.py b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
index 22e4cda7d1..aa0198892f 100644
--- a/studio/backend/tests/test_llama_cpp_max_context_threshold.py
+++ b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
@@ -109,7 +109,12 @@ def _make_backend(native_ctx = 131072):
     return inst
 
 
-def _compute_max_available_ctx(native_ctx, model_gib, gpus, kv_per_token_bytes = 325_000):
+def _compute_max_available_ctx(
+    native_ctx,
+    model_gib,
+    gpus,
+    kv_per_token_bytes = 325_000,
+):
     """Run the ceiling-probe block from load_model and return the final
     ``max_available_ctx`` value the backend would assign to
     ``_max_context_length``.
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index 4a8276adc0..9e7944913a 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -77,9 +77,7 @@ def _enc_kv_string(key: str, value: str) -> bytes:
 
 
 def _enc_kv_uint32(key: str, value: int) -> bytes:
-    return (
-        _enc_string(key) + struct.pack("<I", _VTYPE_UINT32) + struct.pack("<I", value)
-    )
+    return _enc_string(key) + struct.pack("<I", _VTYPE_UINT32) + struct.pack("<I", value)
 
 
 def _write_minimal_gguf(
@@ -497,7 +495,7 @@ def test_unload_resets_nextn_predict_layers():
 
 def _make_fake_llama_server(path: Path, help_text: str) -> Path:
     """Bash stub that prints `help_text` on --help."""
-    path.write_text("#!/usr/bin/env bash\n" f"cat <<'EOF'\n{help_text}\nEOF\n")
+    path.write_text(f"#!/usr/bin/env bash\ncat <<'EOF'\n{help_text}\nEOF\n")
     path.chmod(0o755)
     return path
 
@@ -532,8 +530,7 @@ def test_probe_server_capabilities_detects_renamed_mtp(tmp_path):
     # Renamed upstream: draft-mtp -> mtp.
     fake = _make_fake_llama_server(
         tmp_path / "llama-server",
-        "--spec-type [none|mtp|ngram-cache|ngram-simple|ngram-map-k|"
-        "ngram-map-k4v|ngram-mod]",
+        "--spec-type [none|mtp|ngram-cache|ngram-simple|ngram-map-k|ngram-map-k4v|ngram-mod]",
     )
     _clear_caps_cache()
     caps = LlamaCppBackend.probe_server_capabilities(str(fake))
@@ -655,14 +652,7 @@ def test_build_ngram_mod_flags_new():
 
 def test_build_ngram_mod_flags_legacy():
     flags = _build_ngram_mod_flags({"ngram_mod_flavor": "legacy"})
-    assert flags == [
-        "--spec-ngram-size-n",
-        "24",
-        "--draft-min",
-        "48",
-        "--draft-max",
-        "64",
-    ]
+    assert flags == ["--spec-ngram-size-n", "24", "--draft-min", "48", "--draft-max", "64"]
 
 
 def test_build_ngram_mod_flags_empty_when_unsupported():
@@ -672,9 +662,7 @@ def test_build_ngram_mod_flags_empty_when_unsupported():
 
 
 def test_build_ngram_mod_flags_respects_custom_values():
-    flags = _build_ngram_mod_flags(
-        {"ngram_mod_flavor": "new"}, n_match = 16, n_min = 24, n_max = 32
-    )
+    flags = _build_ngram_mod_flags({"ngram_mod_flavor": "new"}, n_match = 16, n_min = 24, n_max = 32)
     assert flags == [
         "--spec-ngram-mod-n-match",
         "16",
@@ -826,9 +814,7 @@ def _patch_probe(monkeypatch, ngram_supported):
     )
 
 
-def test_already_in_target_state_sub_3b_falls_back_to_ngram_mod_when_supported(
-    monkeypatch,
-):
+def test_already_in_target_state_sub_3b_falls_back_to_ngram_mod_when_supported(monkeypatch):
     # 0.8B MTP request -- load_model would have promoted to ngram-mod
     # (no MTP head); reload check must match a ngram-mod backend.
     _patch_probe(monkeypatch, ngram_supported = True)
@@ -1011,7 +997,12 @@ def test_canonicalize_spec_mode(value, expected):
 # ── _build_speculative_flags resolver matrix ──────────────────────
 
 
-def _resolver_backend(monkeypatch, *, ngram_supported = True, mtp_token = "draft-mtp"):
+def _resolver_backend(
+    monkeypatch,
+    *,
+    ngram_supported = True,
+    mtp_token = "draft-mtp",
+):
     """Backend with a deterministic probe so the resolver is hermetic."""
     fake = {
         "found": True,
@@ -1093,13 +1084,7 @@ _SUB_3B_MTP_MODEL = "unsloth/Qwen3.5-0.8B-MTP-GGUF"
     ],
 )
 def test_build_speculative_flags_matrix(
-    monkeypatch,
-    requested,
-    gpus,
-    model,
-    expect_spec_type,
-    expect_n_max,
-    expect_ngram_knobs,
+    monkeypatch, requested, gpus, model, expect_spec_type, expect_n_max, expect_ngram_knobs
 ):
     backend = _resolver_backend(monkeypatch)
     flags = backend._build_speculative_flags(
diff --git a/studio/backend/tests/test_llama_cpp_start_failure_classification.py b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
index e647ff2c7d..202fd36c86 100644
--- a/studio/backend/tests/test_llama_cpp_start_failure_classification.py
+++ b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
@@ -30,9 +30,7 @@ sys.modules.setdefault("loggers", _loggers_stub)
 # Give the structlog stub a real get_logger: a bare ModuleType poisons
 # sys.modules for later tests that call structlog.get_logger at import time.
 _structlog_stub = _types.ModuleType("structlog")
-_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger(
-    "structlog"
-)
+_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("structlog")
 sys.modules.setdefault("structlog", _structlog_stub)
 if not hasattr(sys.modules["structlog"], "get_logger"):
     sys.modules["structlog"].get_logger = _structlog_stub.get_logger
@@ -109,8 +107,7 @@ class TestUnsupportedNonDiffusionArchitecture:
 
 class TestOllamaAndFallback:
     _OLLAMA_GGUF = (
-        f"/home/u/.ollama{__import__('os').sep}ollama_links"
-        f"{__import__('os').sep}m.gguf"
+        f"/home/u/.ollama{__import__('os').sep}ollama_links" f"{__import__('os').sep}m.gguf"
     )
 
     def test_ollama_compat_message_still_works(self):
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
index 00295d6283..125b13782a 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
@@ -131,9 +131,7 @@ def test_stale_kill_skips_wait():
         LlamaCppBackend._wait_for_vram_settle(
             **_kw(since_kill = long_ago, max_wait = 2.0, interval = 0.25)
         )
-    assert (
-        state["calls"] == 0
-    ), "kill older than _VRAM_SETTLE_WINDOW_S must skip the wait"
+    assert state["calls"] == 0, "kill older than _VRAM_SETTLE_WINDOW_S must skip the wait"
 
 
 def test_empty_first_sample_returns_immediately():
@@ -221,9 +219,7 @@ def test_max_wait_respected_when_probe_is_slow():
         elapsed = time.monotonic() - start
     # First probe (0.30 s) + at most one short clipped sleep + bail.
     # Hard cap well below the old behaviour of 0.30 + 0.25 + 0.30 = 0.85.
-    assert (
-        elapsed < 0.85
-    ), f"helper exceeded the deadline due to slow probes: {elapsed:.3f}s"
+    assert elapsed < 0.85, f"helper exceeded the deadline due to slow probes: {elapsed:.3f}s"
 
 
 def test_gpu_index_set_change_returns():
diff --git a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
index 7d4719c0e7..a5c9d2255f 100644
--- a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
+++ b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
@@ -185,9 +185,7 @@ class TestWindowsPipNvidiaDllDirs:
         # If sys.prefix points to a path that doesn't exist (unusual,
         # but possible during test setup), the resolver must just
         # return [] rather than raising.
-        result = LlamaCppBackend._windows_pip_nvidia_dll_dirs(
-            "/this/path/does/not/exist/anywhere"
-        )
+        result = LlamaCppBackend._windows_pip_nvidia_dll_dirs("/this/path/does/not/exist/anywhere")
         assert result == []
 
     def test_picks_up_cu13_bin_x86_64_layout(self, tmp_path):
@@ -196,9 +194,7 @@ class TestWindowsPipNvidiaDllDirs:
         # ``nvidia/cu13/bin/x86_64/`` instead of ``nvidia/<pkg>/bin/``.
         # Without this, users on the new CUDA 13 wheel generation hit
         # the original #5106 failure mode.
-        dll_dir = (
-            tmp_path / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
-        )
+        dll_dir = tmp_path / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
         dll_dir.mkdir(parents = True)
         for name in ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll"):
             (dll_dir / name).write_bytes(b"")
diff --git a/studio/backend/tests/test_llama_server_args.py b/studio/backend/tests/test_llama_server_args.py
index 2f7431497d..2c7362a9ff 100644
--- a/studio/backend/tests/test_llama_server_args.py
+++ b/studio/backend/tests/test_llama_server_args.py
@@ -20,12 +20,7 @@ import pytest
 # full backend chain (fastapi / structlog / loggers / utils.hardware)
 # via core/inference/__init__.py. The validator is intentionally
 # dependency-free and unit-tests should reflect that.
-_LSA_PATH = (
-    Path(__file__).resolve().parent.parent
-    / "core"
-    / "inference"
-    / "llama_server_args.py"
-)
+_LSA_PATH = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_server_args.py"
 _spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
 _lsa = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(_lsa)
@@ -359,14 +354,7 @@ def test_strip_shadowing_flags_keeps_cache_when_cache_disabled():
         ["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"],
         strip_cache = False,
     )
-    assert out == [
-        "--cache-type-k",
-        "q8_0",
-        "--cache-type-v",
-        "q8_0",
-        "--top-k",
-        "20",
-    ]
+    assert out == ["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"]
 
 
 def test_strip_shadowing_flags_keeps_spec_when_spec_disabled():
@@ -374,14 +362,7 @@ def test_strip_shadowing_flags_keeps_spec_when_spec_disabled():
         ["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"],
         strip_spec = False,
     )
-    assert out == [
-        "--spec-type",
-        "ngram-mod",
-        "--draft-min",
-        "48",
-        "--top-k",
-        "20",
-    ]
+    assert out == ["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"]
 
 
 def test_strip_shadowing_flags_drops_mtp_flags_when_requested():
@@ -505,9 +486,7 @@ def test_strip_shadowing_flags_jinja_boolean_preserves_positional():
 
 
 def test_strip_shadowing_flags_no_jinja_boolean_preserves_positional():
-    out = strip_shadowing_flags(
-        ["--no-jinja", "trailing-positional"], strip_template = True
-    )
+    out = strip_shadowing_flags(["--no-jinja", "trailing-positional"], strip_template = True)
     assert out == ["trailing-positional"]
 
 
diff --git a/studio/backend/tests/test_login_rate_limit.py b/studio/backend/tests/test_login_rate_limit.py
index c8498d4857..1b084cf436 100644
--- a/studio/backend/tests/test_login_rate_limit.py
+++ b/studio/backend/tests/test_login_rate_limit.py
@@ -45,9 +45,12 @@ def env_trust_proxy(monkeypatch):
 
 
 class _FakeRequest:
-    def __init__(self, client_host = "127.0.0.1", headers = None):
+    def __init__(
+        self,
+        client_host = "127.0.0.1",
+        headers = None,
+    ):
         from starlette.datastructures import Headers
-
         self.client = type("Client", (), {"host": client_host})()
         self.headers = Headers(headers or {})
 
@@ -58,12 +61,10 @@ class _FakeRequest:
 class TestClientIp:
     def test_uses_request_client_host_by_default(self, env_no_proxy):
         from routes.auth import _client_ip
-
         assert _client_ip(_FakeRequest("203.0.113.5")) == "203.0.113.5"
 
     def test_ignores_xff_when_trust_off(self, env_no_proxy):
         from routes.auth import _client_ip
-
         req = _FakeRequest(
             "127.0.0.1",
             {"x-forwarded-for": "198.51.100.7, 10.0.0.1"},
@@ -74,7 +75,6 @@ class TestClientIp:
 
     def test_honours_first_xff_when_trust_on(self, env_trust_proxy):
         from routes.auth import _client_ip
-
         req = _FakeRequest(
             "127.0.0.1",
             {"x-forwarded-for": "198.51.100.7, 10.0.0.1"},
@@ -83,12 +83,10 @@ class TestClientIp:
 
     def test_falls_back_to_client_host_when_xff_missing(self, env_trust_proxy):
         from routes.auth import _client_ip
-
         assert _client_ip(_FakeRequest("203.0.113.9")) == "203.0.113.9"
 
     def test_honours_forwarded_header_when_trust_on(self, env_trust_proxy):
         from routes.auth import _client_ip
-
         req = _FakeRequest(
             "127.0.0.1",
             {"forwarded": 'for="198.51.100.42";proto=https'},
@@ -104,34 +102,22 @@ class TestClientIp:
 
     def test_xff_strips_ipv4_port(self, env_trust_proxy):
         from routes.auth import _client_ip
-
-        req = _FakeRequest(
-            "127.0.0.1", {"x-forwarded-for": "198.51.100.7:50001, 10.0.0.1"}
-        )
+        req = _FakeRequest("127.0.0.1", {"x-forwarded-for": "198.51.100.7:50001, 10.0.0.1"})
         assert _client_ip(req) == "198.51.100.7"
 
     def test_xff_strips_bracketed_ipv6_port(self, env_trust_proxy):
         from routes.auth import _client_ip
-
-        req = _FakeRequest(
-            "127.0.0.1", {"x-forwarded-for": "[2001:db8::1]:50001, 10.0.0.1"}
-        )
+        req = _FakeRequest("127.0.0.1", {"x-forwarded-for": "[2001:db8::1]:50001, 10.0.0.1"})
         assert _client_ip(req) == "2001:db8::1"
 
     def test_forwarded_strips_ipv4_port(self, env_trust_proxy):
         from routes.auth import _client_ip
-
-        req = _FakeRequest(
-            "127.0.0.1", {"forwarded": 'for="198.51.100.7:50001";proto=https'}
-        )
+        req = _FakeRequest("127.0.0.1", {"forwarded": 'for="198.51.100.7:50001";proto=https'})
         assert _client_ip(req) == "198.51.100.7"
 
     def test_forwarded_strips_bracketed_ipv6_port(self, env_trust_proxy):
         from routes.auth import _client_ip
-
-        req = _FakeRequest(
-            "127.0.0.1", {"forwarded": 'for="[2001:db8::1]:50001";proto=https'}
-        )
+        req = _FakeRequest("127.0.0.1", {"forwarded": 'for="[2001:db8::1]:50001";proto=https'})
         assert _client_ip(req) == "2001:db8::1"
 
     def test_forwarded_isolates_first_element(self, env_trust_proxy):
@@ -247,9 +233,7 @@ class TestLogin429Body:
         import secrets as _secrets
 
         monkeypatch.setattr(storage, "DB_PATH", tmp_path / "auth.db")
-        monkeypatch.setattr(
-            storage, "_BOOTSTRAP_PW_PATH", tmp_path / ".bootstrap_password"
-        )
+        monkeypatch.setattr(storage, "_BOOTSTRAP_PW_PATH", tmp_path / ".bootstrap_password")
         monkeypatch.setattr(storage, "_bootstrap_password", None)
         storage.create_initial_user(
             username = storage.DEFAULT_ADMIN_USERNAME,
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index 10a6eb012b..0d263d7630 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -45,9 +45,7 @@ def test_list_servers_ordered_by_created_at(tmp_path, monkeypatch):
 def test_update_server_coerces_bools(tmp_path, monkeypatch):
     _reset_db(tmp_path, monkeypatch)
     mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a/m")
-    assert mcp_servers_db.update_server(
-        "srv1", {"is_enabled": False, "use_oauth": True}
-    )
+    assert mcp_servers_db.update_server("srv1", {"is_enabled": False, "use_oauth": True})
     row = mcp_servers_db.get_server("srv1")
     assert row["is_enabled"] == 0
     assert row["use_oauth"] == 1
@@ -81,7 +79,6 @@ def test_validate_url_accepts_http_and_https():
 @pytest.mark.parametrize("bad", ["", "   ", "ftp://x", "http://", "noscheme.com"])
 def test_validate_url_rejects_bad(bad):
     from routes.mcp_servers import _validate_url
-
     with pytest.raises(HTTPException) as exc:
         _validate_url(bad)
     assert exc.value.status_code == 400
@@ -90,9 +87,7 @@ def test_validate_url_rejects_bad(bad):
 def test_normalize_headers():
     from routes.mcp_servers import _normalize_headers
 
-    assert _normalize_headers({"  Auth  ": "Bearer x", "": "ignored"}) == {
-        "Auth": "Bearer x"
-    }
+    assert _normalize_headers({"  Auth  ": "Bearer x", "": "ignored"}) == {"Auth": "Bearer x"}
     assert _normalize_headers({"X": 42}) == {"X": "42"}
     assert _normalize_headers({}) is None
     assert _normalize_headers(None) is None
@@ -104,15 +99,12 @@ def test_changes_from_payload_tristate_headers():
     from models.mcp_servers import McpServerUpdate
 
     # omitted → key absent
-    assert "headers_json" not in _changes_from_payload(
-        McpServerUpdate(display_name = "x")
-    )
+    assert "headers_json" not in _changes_from_payload(McpServerUpdate(display_name = "x"))
     # null → stored as None (clear all headers)
     assert _changes_from_payload(McpServerUpdate(headers = None))["headers_json"] is None
     # dict → serialised JSON
     assert (
-        _changes_from_payload(McpServerUpdate(headers = {"a": "1"}))["headers_json"]
-        == '{"a": "1"}'
+        _changes_from_payload(McpServerUpdate(headers = {"a": "1"}))["headers_json"] == '{"a": "1"}'
     )
 
 
@@ -135,7 +127,6 @@ def test_mcp_specs_skip_oversized_names():
 
 def test_execute_tool_malformed_mcp_name():
     from core.inference.tools import execute_tool
-
     out = execute_tool("mcp__no_double_underscore", {})
     assert out.startswith("Error: malformed MCP tool name")
 
@@ -143,11 +134,7 @@ def test_execute_tool_malformed_mcp_name():
 def test_execute_tool_unknown_server(tmp_path, monkeypatch):
     _reset_db(tmp_path, monkeypatch)
     from core.inference.tools import execute_tool
-
-    assert (
-        execute_tool("mcp__missing__do_thing", {})
-        == "Error: MCP server 'missing' not found"
-    )
+    assert execute_tool("mcp__missing__do_thing", {}) == "Error: MCP server 'missing' not found"
 
 
 def test_execute_tool_disabled_server(tmp_path, monkeypatch):
@@ -160,10 +147,7 @@ def test_execute_tool_disabled_server(tmp_path, monkeypatch):
     )
     from core.inference.tools import execute_tool
 
-    assert (
-        execute_tool("mcp__srv1__do_thing", {})
-        == "Error: MCP server 'srv1' is disabled"
-    )
+    assert execute_tool("mcp__srv1__do_thing", {}) == "Error: MCP server 'srv1' is disabled"
 
 
 def test_mcp_specs_skip_invalid_openai_function_names():
@@ -219,7 +203,6 @@ def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
 
         async def call_tool(self, name, args):
             import asyncio as _asyncio
-
             await _asyncio.sleep(30)  # never finishes within the test
 
     monkeypatch.setattr(mcp_client, "_client", lambda *a, **kw: _StubClient())
@@ -439,8 +422,7 @@ def test_tool_healing_strip_handles_hyphenated_function_names():
     from core.tool_healing import strip_tool_call_markup
 
     out = strip_tool_call_markup(
-        "before <function=mcp__srv__list-issues>"
-        "<parameter=q>x</parameter></function> after"
+        "before <function=mcp__srv__list-issues><parameter=q>x</parameter></function> after"
     )
     assert out == "before  after"
 
@@ -558,9 +540,7 @@ def test_tool_xml_parser_handles_hyphenated_function_names():
     from core.inference.tool_call_parser import parse_tool_calls_from_text
 
     calls = parse_tool_calls_from_text(
-        "<function=mcp__srv__list-issues>"
-        "<parameter=repo>octocat/hello</parameter>"
-        "</function>"
+        "<function=mcp__srv__list-issues><parameter=repo>octocat/hello</parameter></function>"
     )
     assert len(calls) == 1
     assert calls[0]["function"]["name"] == "mcp__srv__list-issues"
@@ -584,8 +564,7 @@ def test_tool_xml_strip_handles_hyphenated_function_names():
     rx = ns["_TOOL_XML_RE"]
     stripped = rx.sub(
         "",
-        "before <function=mcp__srv__list-issues>"
-        "<parameter=q>x</parameter></function> after",
+        "before <function=mcp__srv__list-issues><parameter=q>x</parameter></function> after",
     )
     assert stripped == "before  after"
 
diff --git a/studio/backend/tests/test_mcp_stdio_improvements.py b/studio/backend/tests/test_mcp_stdio_improvements.py
index e980e6a057..515e39d5b6 100644
--- a/studio/backend/tests/test_mcp_stdio_improvements.py
+++ b/studio/backend/tests/test_mcp_stdio_improvements.py
@@ -62,9 +62,7 @@ def test_create_forces_oauth_off_for_stdio(tmp_path, monkeypatch):
     _enable(monkeypatch)
     resp = asyncio.run(
         routes_mcp.create_mcp_server(
-            McpServerCreate(
-                display_name = "FS", url = "npx -y server /tmp", use_oauth = True
-            ),
+            McpServerCreate(display_name = "FS", url = "npx -y server /tmp", use_oauth = True),
             current_subject = "u",
         )
     )
@@ -94,12 +92,8 @@ def test_update_url_to_stdio_clears_oauth(tmp_path, monkeypatch):
     _reset_db(tmp_path, monkeypatch)
     _enable(monkeypatch)
     monkeypatch.setattr(mcp_client, "_oauth_token_store", None)
-    monkeypatch.setattr(
-        routes_mcp, "clear_oauth_tokens_async", lambda *a, **k: asyncio.sleep(0)
-    )
-    mcp_servers_db.create_server(
-        id = "s1", display_name = "A", url = "https://a/mcp", use_oauth = True
-    )
+    monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", lambda *a, **k: asyncio.sleep(0))
+    mcp_servers_db.create_server(id = "s1", display_name = "A", url = "https://a/mcp", use_oauth = True)
     resp = asyncio.run(
         routes_mcp.update_mcp_server(
             "s1", McpServerUpdate(url = "npx -y server /tmp"), current_subject = "u"
@@ -148,9 +142,7 @@ def test_switch_keeps_explicitly_supplied_headers(tmp_path, monkeypatch):
     resp = asyncio.run(
         routes_mcp.update_mcp_server(
             "s1",
-            McpServerUpdate(
-                url = "https://remote/mcp", headers = {"Authorization": "Bearer new"}
-            ),
+            McpServerUpdate(url = "https://remote/mcp", headers = {"Authorization": "Bearer new"}),
             current_subject = "u",
         )
     )
@@ -171,9 +163,7 @@ def test_same_transport_edit_keeps_headers(tmp_path, monkeypatch):
     )
     # editing only the display name (still stdio) must not wipe env vars
     resp = asyncio.run(
-        routes_mcp.update_mcp_server(
-            "s1", McpServerUpdate(display_name = "B"), current_subject = "u"
-        )
+        routes_mcp.update_mcp_server("s1", McpServerUpdate(display_name = "B"), current_subject = "u")
     )
     assert resp.headers == {"API_KEY": "secret"}
 
@@ -183,7 +173,6 @@ def test_same_transport_edit_keeps_headers(tmp_path, monkeypatch):
 
 def test_validate_url_rejects_url_scheme_command_when_enabled(monkeypatch):
     from routes.mcp_servers import _validate_url
-
     _enable(monkeypatch)
     for bad in ["ftp://host/x", "file:///etc/passwd", "ws://h/y"]:
         with pytest.raises(HTTPException) as exc:
@@ -193,12 +182,9 @@ def test_validate_url_rejects_url_scheme_command_when_enabled(monkeypatch):
 
 def test_validate_url_allows_url_in_argument(monkeypatch):
     from routes.mcp_servers import _validate_url
-
     _enable(monkeypatch)
     # :// inside an ARGUMENT (not the first token) is still a valid command
-    assert _validate_url("npx server --url https://x/mcp") == (
-        "npx server --url https://x/mcp"
-    )
+    assert _validate_url("npx server --url https://x/mcp") == ("npx server --url https://x/mcp")
 
 
 # ── P6: Data Recipe stdio path obeys the same host gate ─────────────
diff --git a/studio/backend/tests/test_mcp_stdio_pr5863.py b/studio/backend/tests/test_mcp_stdio_pr5863.py
index f49edcdaae..277306836b 100644
--- a/studio/backend/tests/test_mcp_stdio_pr5863.py
+++ b/studio/backend/tests/test_mcp_stdio_pr5863.py
@@ -83,9 +83,7 @@ def transport(monkeypatch):
     monkeypatch.setattr(
         mcp_client,
         "_client",
-        lambda url, headers, use_oauth = False: _RecordingClient(
-            url, headers, use_oauth, recorder
-        ),
+        lambda url, headers, use_oauth = False: _RecordingClient(url, headers, use_oauth, recorder),
     )
     return recorder
 
@@ -130,9 +128,12 @@ def test_parse_basic_argv():
 
 def test_parse_keeps_url_argument_as_one_command():
     # gemini "high": a :// inside an ARGUMENT must not break the command.
-    assert mcp_client.parse_stdio_command(
-        "npx server --endpoint https://example.com/mcp"
-    ) == ["npx", "server", "--endpoint", "https://example.com/mcp"]
+    assert mcp_client.parse_stdio_command("npx server --endpoint https://example.com/mcp") == [
+        "npx",
+        "server",
+        "--endpoint",
+        "https://example.com/mcp",
+    ]
 
 
 def test_parse_quoted_arg():
@@ -158,9 +159,7 @@ def test_parse_windows_strips_wrapping_quotes(monkeypatch):
     # gemini "medium": posix=False keeps backslash paths but also the wrapping
     # quotes; the PR strips a matched pair so argv[0] reaches the OS clean.
     monkeypatch.setattr(sys, "platform", "win32")
-    parts = mcp_client.parse_stdio_command(
-        r'"C:\Program Files\node\node.exe" server.js'
-    )
+    parts = mcp_client.parse_stdio_command(r'"C:\Program Files\node\node.exe" server.js')
     assert parts[0] == r"C:\Program Files\node\node.exe"
     assert parts[1] == "server.js"
 
@@ -242,14 +241,10 @@ def test_validate_url_gate_on_accepts_stdio(monkeypatch):
     # http still works when stdio is on
     assert _validate_url("https://x/mcp") == "https://x/mcp"
     # url-bearing argument accepted as a command
-    assert _validate_url("npx server --url https://x/mcp") == (
-        "npx server --url https://x/mcp"
-    )
+    assert _validate_url("npx server --url https://x/mcp") == ("npx server --url https://x/mcp")
     # A lone token is ambiguous; keep the prior behaviour and accept it as a
     # command rather than guessing it's a URL (no regression for single binaries).
-    assert (
-        _validate_url("/usr/local/bin/my-mcp-server") == "/usr/local/bin/my-mcp-server"
-    )
+    assert _validate_url("/usr/local/bin/my-mcp-server") == "/usr/local/bin/my-mcp-server"
     assert _validate_url("mcp-server-sqlite") == "mcp-server-sqlite"
     # empty / unparseable still rejected
     for bad in ["   ", '"unclosed']:
@@ -336,9 +331,7 @@ def test_refresh_route_gate(tmp_path, monkeypatch, transport):
     assert transport == []
 
     _enable(monkeypatch)
-    res = asyncio.run(
-        routes_mcp.refresh_mcp_server_tools("stdio1", current_subject = "u")
-    )
+    res = asyncio.run(routes_mcp.refresh_mcp_server_tools("stdio1", current_subject = "u"))
     assert res.ok and res.tool_count == 2
     assert len(transport) == 1
 
@@ -349,9 +342,7 @@ def test_discovery_gate(tmp_path, monkeypatch, transport):
     from core.inference.tools import get_enabled_mcp_tools
 
     _reset_db(tmp_path, monkeypatch)
-    mcp_servers_db.create_server(
-        id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True
-    )
+    mcp_servers_db.create_server(id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True)
 
     _disable(monkeypatch)
     assert asyncio.run(get_enabled_mcp_tools()) == []
@@ -367,9 +358,7 @@ def test_execute_gate(tmp_path, monkeypatch, transport):
     from core.inference.tools import execute_tool
 
     _reset_db(tmp_path, monkeypatch)
-    mcp_servers_db.create_server(
-        id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True
-    )
+    mcp_servers_db.create_server(id = "stdio1", display_name = "FS", url = "npx server", is_enabled = True)
 
     _disable(monkeypatch)
     out = execute_tool("mcp__stdio1__list_directory", {"path": "/tmp"})
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 5e5b5a3c3b..2d6efa9f8b 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -24,7 +24,6 @@ if str(_BACKEND_ROOT) not in sys.path:
 @pytest.fixture(scope = "module")
 def main_module():
     import main as _main  # noqa: F401
-
     return _main
 
 
@@ -168,9 +167,7 @@ class TestMaxBodyMiddleware:
         assert r.status_code == 200
         assert r.json()["total"] == 512
 
-    def test_upload_passthrough_rejects_declared_body_over_dedicated_cap(
-        self, main_module
-    ):
+    def test_upload_passthrough_rejects_declared_body_over_dedicated_cap(self, main_module):
         app = _make_protected_app(
             128,
             main_module,
@@ -274,9 +271,7 @@ class TestSecurityHeadersMiddleware:
         csp = r.headers["content-security-policy"]
         assert f"'nonce-{nonce}'" in csp
         # Internal handoff header must not leak to clients.
-        assert main_module._CSP_SCRIPT_NONCE_HEADER not in {
-            k.lower() for k in r.headers.keys()
-        }
+        assert main_module._CSP_SCRIPT_NONCE_HEADER not in {k.lower() for k in r.headers.keys()}
 
     def test_build_csp_helper_shape(self, main_module):
         plain = main_module._build_csp()
@@ -290,9 +285,7 @@ class TestSecurityHeadersMiddleware:
         # this allowlist entry citation favicons fall back to gray initials.
         csp = main_module._build_csp()
         img_directive = next(
-            chunk.strip()
-            for chunk in csp.split(";")
-            if chunk.strip().startswith("img-src ")
+            chunk.strip() for chunk in csp.split(";") if chunk.strip().startswith("img-src ")
         )
         # Tokenise and compare with `==` so CodeQL's URL-substring rule does
         # not read directive-string `in` membership as URL sanitisation.
diff --git a/studio/backend/tests/test_mlx_inference_backend.py b/studio/backend/tests/test_mlx_inference_backend.py
index 16cca7dd40..49afab048d 100644
--- a/studio/backend/tests/test_mlx_inference_backend.py
+++ b/studio/backend/tests/test_mlx_inference_backend.py
@@ -103,8 +103,7 @@ def test_mlx_inference_text_load_forwards_studio_settings(monkeypatch):
 
 
 def test_mlx_inference_vlm_lora_uses_unsloth_loader_without_native_adapter_rewrite(
-    monkeypatch,
-    tmp_path,
+    monkeypatch, tmp_path
 ):
     _install_fake_mlx(monkeypatch)
     calls = []
@@ -199,7 +198,7 @@ def test_mlx_generate_text_forwards_kwargs_into_template_helper(monkeypatch):
         return "<rendered prompt>"
 
     monkeypatch.setattr(
-        "core.inference.chat_template_helpers." "apply_chat_template_for_generation",
+        "core.inference.chat_template_helpers.apply_chat_template_for_generation",
         _fake_apply,
         raising = True,
     )
@@ -228,7 +227,11 @@ def test_mlx_generate_text_forwards_kwargs_into_template_helper(monkeypatch):
     class _Tok:
         chat_template = "x"
 
-        def decode(self, ids, skip_special_tokens = False):
+        def decode(
+            self,
+            ids,
+            skip_special_tokens = False,
+        ):
             return "hi"
 
     backend = MLXInferenceBackend()
diff --git a/studio/backend/tests/test_mlx_training_worker_config.py b/studio/backend/tests/test_mlx_training_worker_config.py
index c36363b1ae..811971ec36 100644
--- a/studio/backend/tests/test_mlx_training_worker_config.py
+++ b/studio/backend/tests/test_mlx_training_worker_config.py
@@ -45,12 +45,8 @@ def _load_worker_module():
             setattr(wheel_utils, name, lambda *_args, **_kwargs: None)
         sys.modules["utils.wheel_utils"] = wheel_utils
 
-        worker_path = (
-            Path(__file__).resolve().parents[1] / "core" / "training" / "worker.py"
-        )
-        spec = importlib.util.spec_from_file_location(
-            "mlx_training_worker_under_test", worker_path
-        )
+        worker_path = Path(__file__).resolve().parents[1] / "core" / "training" / "worker.py"
+        spec = importlib.util.spec_from_file_location("mlx_training_worker_under_test", worker_path)
         module = importlib.util.module_from_spec(spec)
         assert spec.loader is not None
         spec.loader.exec_module(module)
diff --git a/studio/backend/tests/test_models_get_model_config_case_resolution.py b/studio/backend/tests/test_models_get_model_config_case_resolution.py
index 3481e29948..417ec74d17 100644
--- a/studio/backend/tests/test_models_get_model_config_case_resolution.py
+++ b/studio/backend/tests/test_models_get_model_config_case_resolution.py
@@ -50,9 +50,7 @@ def test_get_model_config_resolves_cached_case_before_model_checks(monkeypatch):
         return _DummyModelConfig()
 
     monkeypatch.setattr(models_route, "is_local_path", lambda _: False)
-    monkeypatch.setattr(
-        models_route, "resolve_cached_repo_id_case", lambda _: "Org/Model"
-    )
+    monkeypatch.setattr(models_route, "resolve_cached_repo_id_case", lambda _: "Org/Model")
     monkeypatch.setattr(models_route, "load_model_defaults", _record_load)
     monkeypatch.setattr(models_route, "is_vision_model", _record_vision)
     monkeypatch.setattr(models_route, "is_embedding_model", _record_embedding)
diff --git a/studio/backend/tests/test_multimodal_document.py b/studio/backend/tests/test_multimodal_document.py
index 4d7528d238..b2986f2c3a 100644
--- a/studio/backend/tests/test_multimodal_document.py
+++ b/studio/backend/tests/test_multimodal_document.py
@@ -317,11 +317,7 @@ def test_openai_base64_pdf_becomes_input_file(monkeypatch):
     user_msg = captured["body"]["input"][0]
     parts = user_msg["content"]
     fileblk = next(p for p in parts if p.get("type") == "input_file")
-    assert fileblk == {
-        "type": "input_file",
-        "file_data": _PDF_DATA_URI,
-        "filename": "paper.pdf",
-    }
+    assert fileblk == {"type": "input_file", "file_data": _PDF_DATA_URI, "filename": "paper.pdf"}
 
 
 def test_openai_url_pdf_becomes_input_file(monkeypatch):
@@ -344,10 +340,7 @@ def test_openai_url_pdf_becomes_input_file(monkeypatch):
     )
     parts = captured["body"]["input"][0]["content"]
     fileblk = next(p for p in parts if p.get("type") == "input_file")
-    assert fileblk == {
-        "type": "input_file",
-        "file_url": "https://example.com/doc.pdf",
-    }
+    assert fileblk == {"type": "input_file", "file_url": "https://example.com/doc.pdf"}
 
 
 def test_openai_empty_data_uri_falls_back_to_file_url(monkeypatch):
@@ -512,9 +505,7 @@ def test_build_external_messages_passes_input_document_for_anthropic_and_openai(
         )
     ]
     for provider in ("anthropic", "openai"):
-        out = _build_external_messages(
-            msgs, supports_vision = True, provider_type = provider
-        )
+        out = _build_external_messages(msgs, supports_vision = True, provider_type = provider)
         assert len(out) == 1, (provider, out)
         parts = out[0]["content"]
         assert parts[0] == {"type": "text", "text": "summarise"}, provider
@@ -550,9 +541,7 @@ def test_build_external_messages_strips_input_document_for_unmapped_providers():
         )
     ]
     for provider in ("gemini", "mistral", "kimi", "openrouter", "deepseek", "qwen"):
-        out = _build_external_messages(
-            msgs, supports_vision = True, provider_type = provider
-        )
+        out = _build_external_messages(msgs, supports_vision = True, provider_type = provider)
         assert len(out) == 1, (provider, out)
         parts = out[0]["content"]
         types = [p.get("type") for p in parts if isinstance(p, dict)]
diff --git a/studio/backend/tests/test_native_context_length.py b/studio/backend/tests/test_native_context_length.py
index 60622c776d..01c05d3ec6 100644
--- a/studio/backend/tests/test_native_context_length.py
+++ b/studio/backend/tests/test_native_context_length.py
@@ -332,9 +332,7 @@ class TestPydanticModels:
     def test_status_response_chat_template_roundtrip(self):
         """chat_template serializes and validates as part of status."""
         resp = InferenceStatusResponse(chat_template = "{{ messages }}")
-        roundtripped = InferenceStatusResponse.model_validate_json(
-            resp.model_dump_json()
-        )
+        roundtripped = InferenceStatusResponse.model_validate_json(resp.model_dump_json())
         assert roundtripped.chat_template == "{{ messages }}"
 
     def test_roundtrip_preserves_value(self):
@@ -390,9 +388,7 @@ class TestRouteCompleteness:
     def test_gguf_load_responses_have_field(self):
         """Every GGUF LoadResponse (is_gguf = True) includes native_context_length."""
         blocks = self._find_construction_blocks("LoadResponse")
-        gguf_blocks = [
-            b for b in blocks if "is_gguf = True" in b or "is_gguf=True" in b
-        ]
+        gguf_blocks = [b for b in blocks if "is_gguf = True" in b or "is_gguf=True" in b]
         assert (
             len(gguf_blocks) >= 2
         ), f"Expected at least 2 GGUF LoadResponse blocks, found {len(gguf_blocks)}"
@@ -404,9 +400,7 @@ class TestRouteCompleteness:
     def test_non_gguf_load_responses_omit_field(self):
         """Non-GGUF LoadResponse blocks do not set native_context_length (defaults to None)."""
         blocks = self._find_construction_blocks("LoadResponse")
-        non_gguf = [
-            b for b in blocks if "is_gguf = True" not in b and "is_gguf=True" not in b
-        ]
+        non_gguf = [b for b in blocks if "is_gguf = True" not in b and "is_gguf=True" not in b]
         # Non-GGUF paths should not reference native_context_length
         # (Pydantic defaults it to None, so not setting it is correct)
         for block in non_gguf:
@@ -422,7 +416,9 @@ class TestRouteCompleteness:
             if "llama_backend" in block and "native_context_length" in block:
                 found = True
                 break
-        assert found, "No InferenceStatusResponse block with llama_backend has native_context_length"
+        assert (
+            found
+        ), "No InferenceStatusResponse block with llama_backend has native_context_length"
 
 
 # =====================================================================
diff --git a/studio/backend/tests/test_offline_gguf_cache_fallback.py b/studio/backend/tests/test_offline_gguf_cache_fallback.py
index d3b2f553a2..df7652a590 100644
--- a/studio/backend/tests/test_offline_gguf_cache_fallback.py
+++ b/studio/backend/tests/test_offline_gguf_cache_fallback.py
@@ -149,8 +149,7 @@ def _siblings(items: dict[str, int]):
     """Mock ``hf_model_info(...).siblings`` payload."""
     return _types.SimpleNamespace(
         siblings = [
-            _types.SimpleNamespace(rfilename = name, size = size)
-            for name, size in items.items()
+            _types.SimpleNamespace(rfilename = name, size = size) for name, size in items.items()
         ],
     )
 
@@ -174,12 +173,8 @@ class TestIterHfCacheSnapshots:
         assert list(_iter_hf_cache_snapshots("unsloth/bare")) == []
 
     def test_yields_newest_first(self, hf_cache):
-        old = _build_cache(
-            hf_cache, "unsloth/multi", {"x.gguf": 1}, snapshot_sha = "a" * 40
-        )
-        new = _build_cache(
-            hf_cache, "unsloth/multi", {"y.gguf": 1}, snapshot_sha = "b" * 40
-        )
+        old = _build_cache(hf_cache, "unsloth/multi", {"x.gguf": 1}, snapshot_sha = "a" * 40)
+        new = _build_cache(hf_cache, "unsloth/multi", {"y.gguf": 1}, snapshot_sha = "b" * 40)
         os.utime(old, (1000, 1000))
         os.utime(new, (2000, 2000))
         out = list(_iter_hf_cache_snapshots("unsloth/multi"))
@@ -218,9 +213,7 @@ class TestListGgufVariantsFromCache:
 
 
 class TestListGgufVariantsOffline:
-    def test_offline_env_short_circuits_api(
-        self, hf_cache, clean_offline_env, monkeypatch
-    ):
+    def test_offline_env_short_circuits_api(self, hf_cache, clean_offline_env, monkeypatch):
         _build_cache(hf_cache, "unsloth/a", {"a-UD-Q4_K_XL.gguf": 1})
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
 
@@ -232,11 +225,7 @@ class TestListGgufVariantsOffline:
         assert len(variants) == 1
         assert variants[0].quant == "UD-Q4_K_XL"
 
-    def test_api_exception_falls_back_to_cache(
-        self,
-        hf_cache,
-        clean_offline_env,
-    ):
+    def test_api_exception_falls_back_to_cache(self, hf_cache, clean_offline_env):
         _build_cache(hf_cache, "unsloth/a", {"a-Q4_K_M.gguf": 1})
 
         def boom(*a, **k):
@@ -302,12 +291,7 @@ class TestDetectGgufFromCache:
 
 
 class TestDetectGgufModelRemoteOffline:
-    def test_offline_env_short_circuits_retries(
-        self,
-        hf_cache,
-        clean_offline_env,
-        monkeypatch,
-    ):
+    def test_offline_env_short_circuits_retries(self, hf_cache, clean_offline_env, monkeypatch):
         _build_cache(hf_cache, "unsloth/a", {"a-Q4_K_M.gguf": 1})
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
 
@@ -331,11 +315,7 @@ class TestDetectGgufModelRemoteOffline:
             out = detect_gguf_model_remote("unsloth/a")
         assert out == "a-Q4_K_M.gguf"
 
-    def test_repository_not_found_does_not_consult_cache(
-        self,
-        hf_cache,
-        clean_offline_env,
-    ):
+    def test_repository_not_found_does_not_consult_cache(self, hf_cache, clean_offline_env):
         # Cache has a file but the API explicitly says repo is gone.
         _build_cache(hf_cache, "unsloth/a", {"a-Q4_K_M.gguf": 1})
 
@@ -430,12 +410,7 @@ class TestHfOfflineIfDnsDead:
             assert did_set is False
             assert "HF_HUB_OFFLINE" not in os.environ
 
-    def test_user_set_hf_hub_offline_is_preserved(
-        self,
-        dns,
-        clean_offline_env,
-        monkeypatch,
-    ):
+    def test_user_set_hf_hub_offline_is_preserved(self, dns, clean_offline_env, monkeypatch):
         # User explicitly set offline before launching Studio.
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
         dns.fail()
@@ -445,12 +420,7 @@ class TestHfOfflineIfDnsDead:
         # Helper must not pop a variable it did not set.
         assert os.environ.get("HF_HUB_OFFLINE") == "1"
 
-    def test_user_set_transformers_offline_is_preserved(
-        self,
-        dns,
-        clean_offline_env,
-        monkeypatch,
-    ):
+    def test_user_set_transformers_offline_is_preserved(self, dns, clean_offline_env, monkeypatch):
         monkeypatch.setenv("TRANSFORMERS_OFFLINE", "1")
         dns.fail()
         with _hf_offline_if_dns_dead():
@@ -461,11 +431,7 @@ class TestHfOfflineIfDnsDead:
         # TRANSFORMERS_OFFLINE pre-existed -> preserved.
         assert os.environ.get("TRANSFORMERS_OFFLINE") == "1"
 
-    def test_exception_inside_block_still_restores_env(
-        self,
-        dns,
-        clean_offline_env,
-    ):
+    def test_exception_inside_block_still_restores_env(self, dns, clean_offline_env):
         dns.fail()
         with pytest.raises(RuntimeError, match = "boom"):
             with _hf_offline_if_dns_dead():
@@ -503,10 +469,7 @@ class TestDownloadMmprojOfflineCacheFallback:
     offline vision GGUF load path returns ``None`` even when the mmproj
     is present in cache."""
 
-    def test_cache_lookup_returns_cached_mmproj_when_list_repo_files_fails(
-        self,
-        hf_cache,
-    ):
+    def test_cache_lookup_returns_cached_mmproj_when_list_repo_files_fails(self, hf_cache):
         _build_cache(
             hf_cache,
             "unsloth/vision-GGUF",
@@ -520,7 +483,12 @@ class TestDownloadMmprojOfflineCacheFallback:
         def boom_list(*a, **k):
             raise OSError("offline")
 
-        def fake_download(*, repo_id, filename, token = None):
+        def fake_download(
+            *,
+            repo_id,
+            filename,
+            token = None,
+        ):
             # Echo back so the test can verify the cache-resolved filename
             return f"/fake/cache/{repo_id}/{filename}"
 
@@ -551,7 +519,12 @@ class TestDownloadMmprojOfflineCacheFallback:
 
         captured = {}
 
-        def fake_download(*, repo_id, filename, token = None):
+        def fake_download(
+            *,
+            repo_id,
+            filename,
+            token = None,
+        ):
             captured["filename"] = filename
             return f"/fake/{filename}"
 
@@ -655,9 +628,7 @@ class TestListGgufVariantsPermanentErrors:
                 list_gguf_variants("u/gated-gguf")
         assert type(exc_info.value).__name__ == "GatedRepoError"
 
-    def test_transient_error_still_falls_back_to_cache(
-        self, hf_cache, clean_offline_env
-    ):
+    def test_transient_error_still_falls_back_to_cache(self, hf_cache, clean_offline_env):
         from utils.models.model_config import list_gguf_variants
 
         _build_cache(hf_cache, "u/transient-gguf", {"foo-Q4_K_M.gguf": 1})
@@ -676,7 +647,6 @@ class TestDetectGgufFromCacheExcludesMmproj:
 
     def test_mmproj_only_returns_none(self, hf_cache):
         from utils.models.model_config import _detect_gguf_from_hf_cache
-
         _build_cache(
             hf_cache,
             "u/vision-only-mmproj",
@@ -739,7 +709,6 @@ class TestProbeDnsDeadNoGlobalTimeoutMutation:
         # Simulate a wedged resolver: thread blocks forever.
         def wedged(host):
             import threading
-
             threading.Event().wait()
 
         monkeypatch.setattr(_socket, "gethostbyname", wedged)
diff --git a/studio/backend/tests/test_offline_inference_parent.py b/studio/backend/tests/test_offline_inference_parent.py
index 088be4fcd5..fbb0aa8999 100644
--- a/studio/backend/tests/test_offline_inference_parent.py
+++ b/studio/backend/tests/test_offline_inference_parent.py
@@ -103,10 +103,7 @@ class TestEnvOffline:
 
 class TestTransformersVersionOfflineShortCircuits:
     def test_tokenizer_config_skips_urllib_when_offline(
-        self,
-        monkeypatch,
-        clean_offline_env,
-        tmp_path,
+        self, monkeypatch, clean_offline_env, tmp_path
     ):
         # No local config + offline env -> must NOT call urlopen.
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
@@ -118,12 +115,7 @@ class TestTransformersVersionOfflineShortCircuits:
         with patch("urllib.request.urlopen", boom):
             assert _check_tokenizer_config_needs_v5(unique) is False
 
-    def test_config_550_skips_urllib_when_offline(
-        self,
-        monkeypatch,
-        clean_offline_env,
-        tmp_path,
-    ):
+    def test_config_550_skips_urllib_when_offline(self, monkeypatch, clean_offline_env, tmp_path):
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
         unique = f"unsloth/never-cached-{tmp_path.name}-cfg"
 
@@ -139,9 +131,7 @@ class TestLoraDetectOffline:
     OfflineModeIsEnabled; cached adapter_config.json wins."""
 
     def test_hf_model_info_short_circuits_with_OfflineModeIsEnabled(
-        self,
-        monkeypatch,
-        clean_offline_env,
+        self, monkeypatch, clean_offline_env
     ):
         from unittest.mock import MagicMock
 
@@ -171,10 +161,7 @@ class TestLoraDetectOffline:
         )
 
     def test_cached_lora_detected_when_api_unreachable(
-        self,
-        monkeypatch,
-        clean_offline_env,
-        tmp_path,
+        self, monkeypatch, clean_offline_env, tmp_path
     ):
         """A cached adapter_config.json must still mark the repo as a
         LoRA when the HF API is unreachable."""
diff --git a/studio/backend/tests/test_openai_citation_markers_edge.py b/studio/backend/tests/test_openai_citation_markers_edge.py
index ffe8c6b6eb..e8d0be6246 100644
--- a/studio/backend/tests/test_openai_citation_markers_edge.py
+++ b/studio/backend/tests/test_openai_citation_markers_edge.py
@@ -320,9 +320,7 @@ def test_split_helper_buffers_only_after_last_open_byte():
     assert head == f"pre {complete} mid "
     assert tail == partial
     # And the head, once rewritten, drops every private-use byte.
-    rewritten = _replace_openai_citation_markers(
-        head, [{"source_id": "done", "url": "https://d"}]
-    )
+    rewritten = _replace_openai_citation_markers(head, [{"source_id": "done", "url": "https://d"}])
     assert rewritten == "pre [[1]](https://d) mid "
 
 
diff --git a/studio/backend/tests/test_openai_code_execution.py b/studio/backend/tests/test_openai_code_execution.py
index 0b1a65c69e..d4f814856b 100644
--- a/studio/backend/tests/test_openai_code_execution.py
+++ b/studio/backend/tests/test_openai_code_execution.py
@@ -117,10 +117,7 @@ def test_shell_tool_added_on_cloud_with_container_auto(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    assert {
-        "type": "shell",
-        "environment": {"type": "container_auto"},
-    } in tools
+    assert {"type": "shell", "environment": {"type": "container_auto"}} in tools
 
 
 def test_shell_tool_uses_container_reference_when_id_supplied(monkeypatch):
@@ -273,11 +270,7 @@ def test_shell_call_emits_tool_start_and_end(monkeypatch):
     # backend stamps onto every provider-side tool_start so the
     # frontend serializer can distinguish hosted tools from
     # user-declared functions on history replay.
-    assert starts[0]["arguments"] == {
-        "kind": "bash",
-        "command": "ls -la",
-        "_server_tool": True,
-    }
+    assert starts[0]["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
     assert ends[0]["tool_call_id"] == "scall_1"
     assert "total 24" in ends[0]["result"]
 
@@ -539,7 +532,5 @@ def test_expired_container_retries_only_once(monkeypatch):
     # infinite loop.
     assert call_count["n"] == 2
     # The second failure surfaces normally as an error SSE line.
-    error_lines = [
-        line for line in lines if '"error"' in line and "_toolEvent" not in line
-    ]
+    error_lines = [line for line in lines if '"error"' in line and "_toolEvent" not in line]
     assert len(error_lines) >= 1
diff --git a/studio/backend/tests/test_openai_container_crud.py b/studio/backend/tests/test_openai_container_crud.py
index 161a6fab83..48acf97e1f 100644
--- a/studio/backend/tests/test_openai_container_crud.py
+++ b/studio/backend/tests/test_openai_container_crud.py
@@ -80,17 +80,12 @@ def test_create_sends_openai_beta_header(monkeypatch):
         return httpx.Response(200, json = {"id": "cntr_new", "name": "analysis"})
 
     _mock_http_client(monkeypatch, handler)
-    result = _drive(
-        _make_client().create_openai_container(name = "analysis", ttl_minutes = 30)
-    )
+    result = _drive(_make_client().create_openai_container(name = "analysis", ttl_minutes = 30))
 
     assert result == {"id": "cntr_new", "name": "analysis"}
     assert seen["headers"].get("openai-beta") == "containers=v1"
     assert seen["body"]["name"] == "analysis"
-    assert seen["body"]["expires_after"] == {
-        "anchor": "last_active_at",
-        "minutes": 30,
-    }
+    assert seen["body"]["expires_after"] == {"anchor": "last_active_at", "minutes": 30}
 
 
 def test_delete_sends_openai_beta_header_and_accepts_confirmation(monkeypatch):
diff --git a/studio/backend/tests/test_openai_responses_translation.py b/studio/backend/tests/test_openai_responses_translation.py
index f177ed5ef3..95e9b2d63c 100644
--- a/studio/backend/tests/test_openai_responses_translation.py
+++ b/studio/backend/tests/test_openai_responses_translation.py
@@ -154,10 +154,7 @@ def test_responses_translates_image_parts(monkeypatch):
 
     parts = captured["body"]["input"][0]["content"]
     assert parts[0] == {"type": "input_text", "text": "What is this?"}
-    assert parts[1] == {
-        "type": "input_image",
-        "image_url": "data:image/png;base64,AAA",
-    }
+    assert parts[1] == {"type": "input_image", "image_url": "data:image/png;base64,AAA"}
     # No max_output_tokens key when caller passes max_tokens=None.
     assert "max_output_tokens" not in captured["body"]
 
@@ -497,8 +494,7 @@ def test_responses_response_incomplete_maps_to_length_finish_reason(monkeypatch)
     finish_reasons = [
         json.loads(line[len("data:") :].strip())["choices"][0]["finish_reason"]
         for line in lines
-        if line.startswith("data:")
-        and line[len("data:") :].strip() not in ("", "[DONE]")
+        if line.startswith("data:") and line[len("data:") :].strip() not in ("", "[DONE]")
     ]
     assert "length" in finish_reasons
 
@@ -730,8 +726,7 @@ def test_responses_reasoning_summary_wrapped_in_think_tags(monkeypatch):
     data_lines = [
         line[len("data:") :].strip()
         for line in lines
-        if line.startswith("data:")
-        and line[len("data:") :].strip() not in ("", "[DONE]")
+        if line.startswith("data:") and line[len("data:") :].strip() not in ("", "[DONE]")
     ]
     payloads = [json.loads(raw) for raw in data_lines]
     combined = "".join(
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 05efee1595..7d488ae4c9 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -271,10 +271,7 @@ class TestChatCompletionRequestToolFields:
         assert self._make(stop = "\nUser:").stop == "\nUser:"
 
     def test_stop_list(self):
-        assert self._make(stop = ["\nUser:", "\nAssistant:"]).stop == [
-            "\nUser:",
-            "\nAssistant:",
-        ]
+        assert self._make(stop = ["\nUser:", "\nAssistant:"]).stop == ["\nUser:", "\nAssistant:"]
 
     def test_tools_default_none(self):
         req = self._make()
@@ -316,9 +313,7 @@ class TestChatCompletionRequestToolFields:
         req = self._make()
         assert req.stream is False
 
-    def test_post_without_stream_field_decodes_to_stream_false_over_http(
-        self, monkeypatch
-    ):
+    def test_post_without_stream_field_decodes_to_stream_false_over_http(self, monkeypatch):
         # Wire-level guard for the same default: a POST body that omits
         # `stream` entirely (the exact shape naive curl / .NET clients
         # send) must deserialise into stream=False *and* the response
@@ -419,13 +414,8 @@ class TestAnthropicToolChoiceToOpenAI:
         assert anthropic_tool_choice_to_openai({"type": "none"}) == "none"
 
     def test_tool_named(self):
-        result = anthropic_tool_choice_to_openai(
-            {"type": "tool", "name": "get_weather"}
-        )
-        assert result == {
-            "type": "function",
-            "function": {"name": "get_weather"},
-        }
+        result = anthropic_tool_choice_to_openai({"type": "tool", "name": "get_weather"})
+        assert result == {"type": "function", "function": {"name": "get_weather"}}
 
     def test_tool_missing_name_returns_none(self):
         assert anthropic_tool_choice_to_openai({"type": "tool"}) is None
@@ -528,15 +518,11 @@ class TestFriendlyErrorHttpx:
         # Non-httpx exceptions still fall through to the existing substring
         # heuristics — a context-size message must still produce the
         # "Message too long" path.
-        ctx_msg = (
-            "request (4096 tokens) exceeds the available context size (2048 tokens)"
-        )
+        ctx_msg = "request (4096 tokens) exceeds the available context size (2048 tokens)"
         assert "Message too long" in _friendly_error(ValueError(ctx_msg))
 
     def test_generic_exception_returns_generic_message(self):
-        assert (
-            _friendly_error(RuntimeError("unrelated")) == "An internal error occurred"
-        )
+        assert _friendly_error(RuntimeError("unrelated")) == "An internal error occurred"
 
 
 from routes.inference import (  # noqa: E402
@@ -554,10 +540,7 @@ class TestDropEmptyAssistantSentinels:
             {"role": "user", "content": "again"},
         ]
         out = _drop_empty_assistant_sentinels(msgs)
-        assert out == [
-            {"role": "user", "content": "hi"},
-            {"role": "user", "content": "again"},
-        ]
+        assert out == [{"role": "user", "content": "hi"}, {"role": "user", "content": "again"}]
 
     def test_drops_assistant_with_no_content_key(self):
         # exclude_none=True strips the content key entirely; filter must catch this.
@@ -567,10 +550,7 @@ class TestDropEmptyAssistantSentinels:
             {"role": "user", "content": "ok"},
         ]
         out = _drop_empty_assistant_sentinels(msgs)
-        assert out == [
-            {"role": "user", "content": "hi"},
-            {"role": "user", "content": "ok"},
-        ]
+        assert out == [{"role": "user", "content": "hi"}, {"role": "user", "content": "ok"}]
 
     def test_preserves_assistant_with_text(self):
         msgs = [
@@ -670,16 +650,10 @@ class TestGgufVisionMessages:
         messages, has_image = _openai_messages_for_gguf_chat(req, is_vision = True)
 
         assert has_image is True
-        assert messages[0]["content"][0] == {
-            "type": "text",
-            "text": "describe image one",
-        }
+        assert messages[0]["content"][0] == {"type": "text", "text": "describe image one"}
         assert messages[0]["content"][1]["type"] == "image_url"
         assert len(messages[0]["content"]) == 2
-        assert messages[2]["content"][0] == {
-            "type": "text",
-            "text": "describe image two",
-        }
+        assert messages[2]["content"][0] == {"type": "text", "text": "describe image two"}
         assert messages[2]["content"][1]["type"] == "image_url"
         assert len(messages[2]["content"]) == 2
         assert isinstance(messages[1]["content"], str)
@@ -702,14 +676,9 @@ class TestGgufVisionMessages:
         messages, has_image = _openai_messages_for_gguf_chat(req, is_vision = True)
 
         assert has_image is True
-        assert messages[0]["content"][0] == {
-            "type": "text",
-            "text": "describe this image",
-        }
+        assert messages[0]["content"][0] == {"type": "text", "text": "describe this image"}
         assert messages[0]["content"][1]["type"] == "image_url"
-        assert messages[0]["content"][1]["image_url"]["url"].startswith(
-            "data:image/png;base64,"
-        )
+        assert messages[0]["content"][1]["image_url"]["url"].startswith("data:image/png;base64,")
 
     def test_rejects_image_parts_for_text_only_gguf(self):
         req = ChatCompletionRequest(
@@ -775,9 +744,7 @@ class TestGgufVisionMessages:
             {"role": "user", "content": "now"},
         ]
 
-        updated = _set_or_prepend_system_message(
-            messages, "Mid instructions.\n\nUse tools."
-        )
+        updated = _set_or_prepend_system_message(messages, "Mid instructions.\n\nUse tools.")
 
         assert [m["role"] for m in updated] == ["system", "user", "user"]
         assert updated[0]["content"] == "Mid instructions.\n\nUse tools."
@@ -837,10 +804,7 @@ class TestGgufVisionToolRouting:
                         {
                             "type": "image_url",
                             "image_url": {
-                                "url": (
-                                    "data:image/png;base64,"
-                                    f"{TestGgufVisionMessages._PNG_B64}"
-                                ),
+                                "url": (f"data:image/png;base64,{TestGgufVisionMessages._PNG_B64}"),
                             },
                         },
                     ],
@@ -849,9 +813,7 @@ class TestGgufVisionToolRouting:
         )
 
         response = self._drive(
-            openai_chat_completions(
-                payload, request = self._Request(), current_subject = "test"
-            )
+            openai_chat_completions(payload, request = self._Request(), current_subject = "test")
         )
         self._consume_response(response)
 
diff --git a/studio/backend/tests/test_pricing.py b/studio/backend/tests/test_pricing.py
index 313c15a441..d669747b1a 100644
--- a/studio/backend/tests/test_pricing.py
+++ b/studio/backend/tests/test_pricing.py
@@ -21,7 +21,11 @@ from core.inference.pricing import (
 )
 
 
-def _isclose(a, b, tol = 1e-6):
+def _isclose(
+    a,
+    b,
+    tol = 1e-6,
+):
     return math.isclose(a, b, rel_tol = tol, abs_tol = tol)
 
 
@@ -241,9 +245,7 @@ def test_openai_cache_read_subtracted_from_input_at_discount():
     )
     # 20k charged at full price, 80k charged at 0.1x
     assert _isclose(out["input_usd"], 20_000 / 1_000_000.0 * base)
-    assert _isclose(
-        out["cache_read_usd"], 80_000 / 1_000_000.0 * base * OPENAI_CACHE_READ_MULT
-    )
+    assert _isclose(out["cache_read_usd"], 80_000 / 1_000_000.0 * base * OPENAI_CACHE_READ_MULT)
 
 
 def test_openai_billable_input_tokens_does_not_double_count_cache_read():
@@ -390,9 +392,7 @@ def test_openai_web_search_charged_per_thousand():
             "openai_tool_use": {"web_search_requests": 250},
         },
     )
-    assert _isclose(
-        out["server_tools_usd"], 250 / 1_000.0 * OPENAI_WEB_SEARCH_USD_PER_1K
-    )
+    assert _isclose(out["server_tools_usd"], 250 / 1_000.0 * OPENAI_WEB_SEARCH_USD_PER_1K)
     assert _isclose(out["total_usd"], 250 / 1_000.0 * OPENAI_WEB_SEARCH_USD_PER_1K)
 
 
@@ -426,8 +426,7 @@ def test_openai_tool_surcharges_added_to_total():
     expected_input = 100_000 / 1_000_000.0 * 5.0
     expected_output = 5_000 / 1_000_000.0 * 30.0
     expected_tools = (
-        3 / 1_000.0 * OPENAI_WEB_SEARCH_USD_PER_1K
-        + 0.25 * OPENAI_CONTAINER_USD_PER_HOUR
+        3 / 1_000.0 * OPENAI_WEB_SEARCH_USD_PER_1K + 0.25 * OPENAI_CONTAINER_USD_PER_HOUR
     )
     assert _isclose(
         out["total_usd"],
@@ -600,10 +599,7 @@ def test_openai_chat_style_envelope_reads_cache_from_prompt_tokens_details():
     )
     # Both envelopes must price identically.
     assert _isclose(chat_style["input_usd"], raw["input_usd"]), (chat_style, raw)
-    assert _isclose(chat_style["cache_read_usd"], raw["cache_read_usd"]), (
-        chat_style,
-        raw,
-    )
+    assert _isclose(chat_style["cache_read_usd"], raw["cache_read_usd"]), (chat_style, raw)
     # 80k at 0.1x base, 20k at full.
     assert _isclose(
         chat_style["cache_read_usd"],
diff --git a/studio/backend/tests/test_pricing_edge.py b/studio/backend/tests/test_pricing_edge.py
index ca4be258e0..5818b42e8a 100644
--- a/studio/backend/tests/test_pricing_edge.py
+++ b/studio/backend/tests/test_pricing_edge.py
@@ -18,7 +18,11 @@ from core.inference.pricing import (
 )
 
 
-def _isclose(a, b, tol = 1e-6):
+def _isclose(
+    a,
+    b,
+    tol = 1e-6,
+):
     return math.isclose(a, b, rel_tol = tol, abs_tol = tol)
 
 
@@ -188,9 +192,7 @@ def test_anthropic_chat_cache_read_exceeds_prompt_no_negative_billable():
     assert out["billable_input_tokens"] == 500  # 0 uncached + 500 cache_read
     # cache_read still priced at the discount rate.
     base = ANTHROPIC_PRICING["claude-opus-4-7"]["input_per_mtok"]
-    assert _isclose(
-        out["cache_read_usd"], 500 / 1_000_000.0 * base * ANTHROPIC_CACHE_READ_MULT
-    )
+    assert _isclose(out["cache_read_usd"], 500 / 1_000_000.0 * base * ANTHROPIC_CACHE_READ_MULT)
 
 
 def test_openai_raw_cached_tokens_exceeds_input_clamp_non_cached():
@@ -207,9 +209,7 @@ def test_openai_raw_cached_tokens_exceeds_input_clamp_non_cached():
     )
     assert out["input_usd"] == 0.0
     # Cache read still priced (the 0.1x bucket).
-    assert _isclose(
-        out["cache_read_usd"], 500 / 1_000_000.0 * base * OPENAI_CACHE_READ_MULT
-    )
+    assert _isclose(out["cache_read_usd"], 500 / 1_000_000.0 * base * OPENAI_CACHE_READ_MULT)
 
 
 # ── long-context tier crosses on billable, including cache_creation ──
diff --git a/studio/backend/tests/test_providers_api.py b/studio/backend/tests/test_providers_api.py
index 0e668944f4..88df886b6c 100644
--- a/studio/backend/tests/test_providers_api.py
+++ b/studio/backend/tests/test_providers_api.py
@@ -225,9 +225,7 @@ class TestAuth:
             json = {"username": USERNAME, "password": PASSWORD},
             timeout = 10,
         )
-        assert (
-            resp.status_code == 200
-        ), f"Login failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 200, f"Login failed ({resp.status_code}): {resp.text}"
         body = resp.json()
         assert body.get("access_token"), "access_token is missing or empty"
         assert body.get("token_type") == "bearer"
@@ -237,9 +235,7 @@ class TestAuth:
 
 
 class TestPublicKey:
-    def test_public_key_is_valid_pem(
-        self, auth_headers: dict[str, str], public_key_pem: str
-    ):
+    def test_public_key_is_valid_pem(self, auth_headers: dict[str, str], public_key_pem: str):
         """GET /api/providers/public-key returns an importable RSA PEM key."""
         pem_bytes = public_key_pem.encode("utf-8")
         key = serialization.load_pem_public_key(pem_bytes)
@@ -261,9 +257,7 @@ class TestRegistry:
         )
         assert resp.status_code == 200, f"Registry failed: {resp.text}"
         providers = resp.json()
-        assert (
-            len(providers) == 9
-        ), f"Expected 9 providers, got {len(providers)}: {providers}"
+        assert len(providers) == 9, f"Expected 9 providers, got {len(providers)}: {providers}"
         print(f"\n  {'Provider':<12} {'Base URL'}")
         print(f"  {'-'*12} {'-'*45}")
         for p in providers:
@@ -283,9 +277,7 @@ class TestRegistry:
 
     def test_registry_entries_have_required_fields(self, auth_headers: dict[str, str]):
         """Each registry entry has provider_type, display_name, base_url, default_models."""
-        resp = requests.get(
-            _url("/api/providers/registry"), headers = auth_headers, timeout = 10
-        )
+        resp = requests.get(_url("/api/providers/registry"), headers = auth_headers, timeout = 10)
         assert resp.status_code == 200
         for entry in resp.json():
             for field in (
@@ -320,9 +312,7 @@ class TestProviderCRUD:
             json = {"provider_type": "openai", "display_name": "Test OpenAI (pytest)"},
             timeout = 10,
         )
-        assert (
-            resp.status_code == 201
-        ), f"Create failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 201, f"Create failed ({resp.status_code}): {resp.text}"
         body = resp.json()
         assert body.get("id"), "No id in response"
         assert body["provider_type"] == "openai"
@@ -333,9 +323,7 @@ class TestProviderCRUD:
 
     def test_list_includes_created(self, auth_headers: dict[str, str]):
         """GET /api/providers/ includes the newly created config."""
-        assert (
-            TestProviderCRUD._created_id
-        ), "No created_id (run test_create_provider first)"
+        assert TestProviderCRUD._created_id, "No created_id (run test_create_provider first)"
         resp = requests.get(_url("/api/providers/"), headers = auth_headers, timeout = 10)
         assert resp.status_code == 200
         ids = [p["id"] for p in resp.json()]
@@ -354,9 +342,7 @@ class TestProviderCRUD:
             json = {"display_name": new_name},
             timeout = 10,
         )
-        assert (
-            resp.status_code == 200
-        ), f"Update failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 200, f"Update failed ({resp.status_code}): {resp.text}"
         assert resp.json()["display_name"] == new_name
         print(f"\n  updated display_name to '{new_name}'")
 
@@ -368,14 +354,10 @@ class TestProviderCRUD:
             headers = auth_headers,
             timeout = 10,
         )
-        assert (
-            resp.status_code == 204
-        ), f"Delete failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 204, f"Delete failed ({resp.status_code}): {resp.text}"
 
         # Confirm gone from list
-        list_resp = requests.get(
-            _url("/api/providers/"), headers = auth_headers, timeout = 10
-        )
+        list_resp = requests.get(_url("/api/providers/"), headers = auth_headers, timeout = 10)
         ids = [p["id"] for p in list_resp.json()]
         assert TestProviderCRUD._created_id not in ids, "Deleted provider still in list"
         print(f"\n  deleted id={TestProviderCRUD._created_id} confirmed gone")
@@ -423,9 +405,7 @@ class TestProviderInference:
             json = {"provider_type": provider_type, "encrypted_api_key": encrypted},
             timeout = 30,
         )
-        assert (
-            resp.status_code == 200
-        ), f"Request failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 200, f"Request failed ({resp.status_code}): {resp.text}"
         body = resp.json()
         assert (
             body["success"] is True
@@ -449,9 +429,7 @@ class TestProviderInference:
             json = {"provider_type": provider_type, "encrypted_api_key": encrypted},
             timeout = 30,
         )
-        assert (
-            resp.status_code == 200
-        ), f"Request failed ({resp.status_code}): {resp.text}"
+        assert resp.status_code == 200, f"Request failed ({resp.status_code}): {resp.text}"
         models = resp.json()
         assert isinstance(models, list), f"Expected list, got {type(models)}"
         assert len(models) > 0, f"No models returned for {provider_type}"
@@ -498,9 +476,7 @@ class TestProviderInference:
 # ── TestVisionInference ─────────────────────────────────────────────
 
 # Sloth photo — used to test vision routing across providers
-_VISION_IMAGE_URL = (
-    "https://www.travelexcellence.com/images/where-to-see-sloths-in-costa-rica.jpg"
-)
+_VISION_IMAGE_URL = "https://www.travelexcellence.com/images/where-to-see-sloths-in-costa-rica.jpg"
 
 _VISION_PARAMS = [
     pytest.param(
@@ -602,8 +578,6 @@ class TestLocalInferenceUnaffected:
             f"This likely means the provider fields broke the base request schema."
         )
         status_label = (
-            "local model responded"
-            if resp.status_code == 200
-            else "no model loaded (expected)"
+            "local model responded" if resp.status_code == 200 else "no model loaded (expected)"
         )
         print(f"\n  status={resp.status_code} ({status_label}) — local path unaffected")
diff --git a/studio/backend/tests/test_responses_api.py b/studio/backend/tests/test_responses_api.py
index 5b55f87259..c0ec876ad0 100644
--- a/studio/backend/tests/test_responses_api.py
+++ b/studio/backend/tests/test_responses_api.py
@@ -173,9 +173,7 @@ class TestResponsesResponse:
         resp = ResponsesResponse(
             model = "test-model",
             output = [
-                ResponsesOutputMessage(
-                    content = [ResponsesOutputTextContent(text = "Hello!")]
-                ),
+                ResponsesOutputMessage(content = [ResponsesOutputTextContent(text = "Hello!")]),
             ],
             usage = ResponsesUsage(input_tokens = 10, output_tokens = 5, total_tokens = 15),
         )
@@ -324,5 +322,4 @@ class TestNormaliseResponsesInput:
 
 if __name__ == "__main__":
     import pytest
-
     pytest.main([__file__, "-v"])
diff --git a/studio/backend/tests/test_responses_tool_passthrough.py b/studio/backend/tests/test_responses_tool_passthrough.py
index 2f1161c329..146d6017d0 100644
--- a/studio/backend/tests/test_responses_tool_passthrough.py
+++ b/studio/backend/tests/test_responses_tool_passthrough.py
@@ -160,9 +160,7 @@ class TestResponsesMultiTurnInput:
 
     def test_function_call_output_missing_call_id_rejected(self):
         with pytest.raises(ValidationError):
-            ResponsesFunctionCallOutputInputItem(
-                type = "function_call_output", output = "x"
-            )
+            ResponsesFunctionCallOutputInputItem(type = "function_call_output", output = "x")
 
     def test_function_call_output_accepts_content_array(self):
         item = ResponsesFunctionCallOutputInputItem(
@@ -222,9 +220,7 @@ class TestToolsTranslation:
         assert _translate_responses_tools_to_chat([]) is None
 
     def test_only_builtin_tools_returns_none(self):
-        assert (
-            _translate_responses_tools_to_chat([{"type": "web_search_preview"}]) is None
-        )
+        assert _translate_responses_tools_to_chat([{"type": "web_search_preview"}]) is None
 
     def test_description_optional(self):
         out = _translate_responses_tools_to_chat(
@@ -256,9 +252,7 @@ class TestToolChoiceTranslation:
         """If a client happens to send the Chat Completions nested shape,
         we don't double-wrap it."""
         already_nested = {"type": "function", "function": {"name": "get_weather"}}
-        assert (
-            _translate_responses_tool_choice_to_chat(already_nested) == already_nested
-        )
+        assert _translate_responses_tool_choice_to_chat(already_nested) == already_nested
 
     def test_unknown_shape_passes_through(self):
         obj = {"type": "allowed_tools", "tools": [{"type": "function", "name": "x"}]}
@@ -625,9 +619,7 @@ class TestCodexStyleRequestShapes:
             input = [
                 {
                     "role": "assistant",
-                    "content": [
-                        {"type": "output_text", "text": "ok", "annotations": []}
-                    ],
+                    "content": [{"type": "output_text", "text": "ok", "annotations": []}],
                 },
                 {"role": "user", "content": "next"},
             ],
diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.py
index 2ce9b55789..d27ee83f1d 100644
--- a/studio/backend/tests/test_rocm_oom_guard.py
+++ b/studio/backend/tests/test_rocm_oom_guard.py
@@ -135,9 +135,7 @@ class TestDeviceNameFallback:
         props = _props(name = device_name)
         gcn, is_unified = _rocm_classify_unified_memory(props)
         assert gcn == "", f"expected empty gcn_arch, got {gcn!r}"
-        assert (
-            is_unified is True
-        ), f"device {device_name!r} should be classified as unified-memory"
+        assert is_unified is True, f"device {device_name!r} should be classified as unified-memory"
 
     # --- discrete devices that must NOT be mis-classified ---
 
diff --git a/studio/backend/tests/test_safetensors_capability_advertise.py b/studio/backend/tests/test_safetensors_capability_advertise.py
index c3ee5b9ff1..5e3d2cc9d1 100644
--- a/studio/backend/tests/test_safetensors_capability_advertise.py
+++ b/studio/backend/tests/test_safetensors_capability_advertise.py
@@ -369,11 +369,7 @@ def test_worker_load_reply_payload_includes_chat_template_info():
         "is_gguf": False,
     }
     _bm = getattr(backend, "models", {}) or {}
-    _entry = (
-        _bm.get(mc.identifier)
-        or _bm.get(getattr(backend, "active_model_name", None))
-        or {}
-    )
+    _entry = _bm.get(mc.identifier) or _bm.get(getattr(backend, "active_model_name", None)) or {}
     _tpl_info = _entry.get("chat_template_info")
     if isinstance(_tpl_info, dict):
         model_info["chat_template_info"] = {
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index 50f6011959..ff5653c742 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -53,9 +53,7 @@ from utils.datasets import is_gpt_oss_model_name
 
 class TestParser:
     def test_json_tool_call(self):
-        text = (
-            '<tool_call>{"name":"web_search","arguments":{"query":"hello"}}</tool_call>'
-        )
+        text = '<tool_call>{"name":"web_search","arguments":{"query":"hello"}}</tool_call>'
         result = parse_tool_calls_from_text(text)
         assert len(result) == 1
         tc = result[0]
@@ -214,7 +212,12 @@ def _collect_events(generator, max_events = 200):
     return events
 
 
-def _make_loop(*, turns, exec_results = None, **kwargs):
+def _make_loop(
+    *,
+    turns,
+    exec_results = None,
+    **kwargs,
+):
     """Build a configured loop with a multi-turn fake generator.
 
     ``turns`` is a list of chunk-lists; iteration N yields chunks from
@@ -342,9 +345,7 @@ class TestLoopBasic:
         assert exec_fn.calls[0][0] == "render_html"
         assert "<!doctype html>" in exec_fn.calls[0][1]["code"]
 
-    def test_python_tool_containing_render_html_signal_does_not_emit_provisional_start(
-        self,
-    ):
+    def test_python_tool_containing_render_html_signal_does_not_emit_provisional_start(self):
         loop, exec_fn = _make_loop(
             turns = [
                 [
@@ -361,9 +362,7 @@ class TestLoopBasic:
 
         assert len(tool_starts) == 1
         assert tool_starts[0]["tool_name"] == "python"
-        assert exec_fn.calls == [
-            ("python", {"code": "print('<function=render_html>')"})
-        ]
+        assert exec_fn.calls == [("python", {"code": "print('<function=render_html>')"})]
 
     def test_render_html_success_blocks_second_artifact_call(self):
         exec_fn = FakeExecuteTool(["Rendered HTML artifact."])
@@ -398,10 +397,7 @@ class TestLoopBasic:
         tool_starts = [e for e in events if e["type"] == "tool_start"]
 
         assert exec_fn.calls == [("render_html", {"code": "<html>one</html>"})]
-        assert [e["arguments"] for e in tool_starts] == [
-            {},
-            {"code": "<html>one</html>"},
-        ]
+        assert [e["arguments"] for e in tool_starts] == [{}, {"code": "<html>one</html>"}]
 
     def test_truncated_unclosed_tool_call(self):
         loop, exec_fn = _make_loop(
@@ -425,9 +421,7 @@ class TestLoopBasic:
                 # ``arguments`` is a string that is not itself valid
                 # JSON for ``_coerce_arguments`` to parse, so the
                 # heal path runs.
-                [
-                    '<tool_call>{"name":"web_search","arguments":"hello world"}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":"hello world"}</tool_call>'],
                 ["ok"],
             ],
             exec_results = ["..."],
@@ -444,12 +438,8 @@ class TestLoopBehaviour:
         # called only once.
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["final"],
             ],
             exec_results = ["search-result-1"],
@@ -467,9 +457,7 @@ class TestLoopBehaviour:
         # tool_end event still carries the raw result for the UI.
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"python","arguments":{"code":"plot()"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"python","arguments":{"code":"plot()"}}</tool_call>'],
                 ["see chart"],
             ],
             exec_results = ["chart\n__IMAGES__:/tmp/chart.png"],
@@ -507,9 +495,7 @@ class TestLoopBehaviour:
         tool_msgs = [m for m in captured[1] if m.get("role") == "tool"]
         assert tool_msgs, "no tool message reached the model"
         for tm in tool_msgs:
-            assert (
-                "__IMAGES__" not in tm["content"]
-            ), f"sentinel leaked to model: {tm['content']!r}"
+            assert "__IMAGES__" not in tm["content"], f"sentinel leaked to model: {tm['content']!r}"
 
     def test_image_sentinel_stripped_with_multiple_markers(self):
         # Consecutive sentinels: cut at the first, nothing leaks.
@@ -539,19 +525,13 @@ class TestLoopBehaviour:
         tool_msgs = [m for m in captured[1] if m.get("role") == "tool"]
         assert tool_msgs
         for tm in tool_msgs:
-            assert (
-                "__IMAGES__" not in tm["content"]
-            ), f"second sentinel leaked: {tm['content']!r}"
-            assert (
-                tm["content"] == "panel"
-            ), f"expected payload-only 'panel', got {tm['content']!r}"
+            assert "__IMAGES__" not in tm["content"], f"second sentinel leaked: {tm['content']!r}"
+            assert tm["content"] == "panel", f"expected payload-only 'panel', got {tm['content']!r}"
 
     def test_tool_execution_error_is_emitted_but_loop_continues(self):
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["sorry, that failed"],
             ],
             exec_results = ["Error: network unreachable"],
@@ -566,9 +546,7 @@ class TestLoopBehaviour:
     def test_exception_in_executor_does_not_raise(self):
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["recovered"],
             ],
             exec_results = [RuntimeError("boom")],
@@ -588,8 +566,7 @@ class TestLoopControl:
         events = list(
             run_safetensors_tool_loop(
                 single_turn = _const_stream(
-                    '<tool_call>{"name":"web_search",'
-                    '"arguments":{"query":"x"}}</tool_call>'
+                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
                 ),
                 messages = [{"role": "user", "content": "hi"}],
                 tools = [],
@@ -606,9 +583,7 @@ class TestLoopControl:
         loop, exec_fn = _make_loop(
             turns = [
                 # : tool call (executes once)
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"a"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"a"}}</tool_call>'],
                 # : model gives a final answer when nudged.
                 ["here is the final answer"],
             ],
@@ -625,24 +600,19 @@ class TestStatusFormatting:
     def test_status_for_known_tools(self):
         # Use the private helper directly to verify status formatting.
         assert (
-            safetensors_agentic._status_for_tool("web_search", {"query": "abc"})
-            == "Searching: abc"
+            safetensors_agentic._status_for_tool("web_search", {"query": "abc"}) == "Searching: abc"
         )
         assert (
-            safetensors_agentic._status_for_tool(
-                "web_search", {"url": "https://www.example.com/x"}
-            )
+            safetensors_agentic._status_for_tool("web_search", {"url": "https://www.example.com/x"})
             == "Reading: example.com"
         )
-        assert safetensors_agentic._status_for_tool(
-            "python", {"code": "x = 1"}
-        ).startswith("Running Python:")
-        assert safetensors_agentic._status_for_tool(
-            "terminal", {"command": "ls"}
-        ).startswith("Running:")
-        assert safetensors_agentic._status_for_tool("unknown_tool", {}).startswith(
-            "Calling:"
+        assert safetensors_agentic._status_for_tool("python", {"code": "x = 1"}).startswith(
+            "Running Python:"
         )
+        assert safetensors_agentic._status_for_tool("terminal", {"command": "ls"}).startswith(
+            "Running:"
+        )
+        assert safetensors_agentic._status_for_tool("unknown_tool", {}).startswith("Calling:")
 
 
 class TestProseMentioningToolCall:
@@ -655,9 +625,7 @@ class TestProseMentioningToolCall:
             turns = [
                 # : a real tool call so the loop moves to
                 # .
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 # : prose that mentions the literal text.
                 ["the docs say <tool_call> means an LLM tool call wrapper"],
             ],
@@ -677,9 +645,7 @@ class TestProseMentioningToolCall:
         # result, so we should see exactly one call.
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["the docs mention <tool_call> wrappers"],
             ],
             exec_results = ["Page text: <tool_call> appears here in the docs"],
@@ -695,7 +661,6 @@ class TestChatTemplateHelper:
         from core.inference.chat_template_helpers import (
             apply_chat_template_for_generation,
         )
-
         self.apply = apply_chat_template_for_generation
 
     class _Tok:
@@ -705,7 +670,12 @@ class TestChatTemplateHelper:
             self.last_kwargs = None
 
         def apply_chat_template(
-            self, messages, *, tokenize = False, add_generation_prompt = True, **kw
+            self,
+            messages,
+            *,
+            tokenize = False,
+            add_generation_prompt = True,
+            **kw,
         ):
             self.call_count += 1
             unknown = set(kw) - self.accepted
@@ -758,9 +728,7 @@ class TestGuardrails:
         exec_fn = FakeExecuteTool([])
         loop = run_safetensors_tool_loop(
             single_turn = _fake_stream(
-                [
-                    '<tool_call>{"name":"terminal","arguments":{"command":"echo bypass"}}</tool_call>'
-                ]
+                ['<tool_call>{"name":"terminal","arguments":{"command":"echo bypass"}}</tool_call>']
             ),
             messages = [{"role": "user", "content": "hi"}],
             tools = [{"type": "function", "function": {"name": "web_search"}}],
@@ -776,9 +744,7 @@ class TestGuardrails:
         exec_fn = FakeExecuteTool(["OK"])
         loop = run_safetensors_tool_loop(
             single_turn = _fake_stream(
-                [
-                    '<tool_call>{"name":"python","arguments":{"code":"print(1)"}}</tool_call>'
-                ]
+                ['<tool_call>{"name":"python","arguments":{"code":"print(1)"}}</tool_call>']
             ),
             messages = [{"role": "user", "content": "hi"}],
             tools = [],
@@ -790,11 +756,7 @@ class TestGuardrails:
 
     def test_max_iterations_zero_executes_no_tools(self):
         loop, exec_fn = _make_loop(
-            turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ]
-            ],
+            turns = [['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>']],
             exec_results = ["OK"],
             max_tool_iterations = 0,
         )
@@ -825,9 +787,7 @@ class TestGuardrails:
     def test_auto_heal_disabled_still_parses_valid_tool_call(self):
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["done"],
             ],
             exec_results = ["OK"],
@@ -840,47 +800,30 @@ class TestGuardrails:
     def test_non_consecutive_duplicate_is_short_circuited(self):
         loop, exec_fn = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'
-                ],
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"B"}}</tool_call>'
-                ],
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"B"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'],
                 ["final"],
             ],
             exec_results = ["res-A", "res-B"],
             max_tool_iterations = 4,
         )
         events = _collect_events(loop)
-        assert exec_fn.calls == [
-            ("web_search", {"query": "A"}),
-            ("web_search", {"query": "B"}),
-        ]
+        assert exec_fn.calls == [("web_search", {"query": "A"}), ("web_search", {"query": "B"})]
         tool_ends = [e for e in events if e["type"] == "tool_end"]
         assert "already made this exact call" in tool_ends[-1]["result"]
 
     def test_coerce_string_args_python_uses_code_key(self):
-        assert _coerce_arguments("print(1)", heal = True, tool_name = "python") == {
-            "code": "print(1)"
-        }
+        assert _coerce_arguments("print(1)", heal = True, tool_name = "python") == {"code": "print(1)"}
 
     def test_coerce_string_args_terminal_uses_command_key(self):
-        assert _coerce_arguments("ls -la", heal = True, tool_name = "terminal") == {
-            "command": "ls -la"
-        }
+        assert _coerce_arguments("ls -la", heal = True, tool_name = "terminal") == {"command": "ls -la"}
 
     def test_tool_call_ids_unique_across_loop_iterations(self):
         loop, _exec = _make_loop(
             turns = [
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'
-                ],
-                [
-                    '<tool_call>{"name":"web_search","arguments":{"query":"B"}}</tool_call>'
-                ],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"B"}}</tool_call>'],
                 ["done"],
             ],
             exec_results = ["A", "B"],
diff --git a/studio/backend/tests/test_sandbox_tools.py b/studio/backend/tests/test_sandbox_tools.py
index cd8957c3dd..92fee2e8e5 100644
--- a/studio/backend/tests/test_sandbox_tools.py
+++ b/studio/backend/tests/test_sandbox_tools.py
@@ -88,9 +88,7 @@ class TestTrustedHostAllowlist:
         _ok(f"import requests; requests.get({url!r})")
 
     def test_wikipedia_subdomain_passes(self):
-        _ok(
-            'import urllib.request; urllib.request.urlopen("https://m.en.wikipedia.org/wiki/Foo")'
-        )
+        _ok('import urllib.request; urllib.request.urlopen("https://m.en.wikipedia.org/wiki/Foo")')
 
     def test_hf_co_short_form_passes(self):
         _ok('import requests; requests.get("https://hf.co/unsloth/Qwen3.5-4B-GGUF")')
@@ -221,10 +219,7 @@ class TestUploadDenylist:
         )
 
     def test_plain_post_json_not_blocked(self):
-        _ok(
-            "import requests\n"
-            'requests.post("https://api.weather.gov/lookup", json={"k": "v"})'
-        )
+        _ok("import requests\n" 'requests.post("https://api.weather.gov/lookup", json={"k": "v"})')
 
 
 class TestSandboxEnvIsolation:
@@ -361,7 +356,6 @@ class TestBashBlocklistPosition:
     @staticmethod
     def _find():
         from core.inference.tools import _find_blocked_commands
-
         return _find_blocked_commands
 
     # ---- argument-position: must NOT be blocked ----
@@ -526,7 +520,7 @@ class TestHfUploadImportGate:
 
     def test_bare_name_upload_file_without_hf_import_allowed(self):
         # No HF import -- local helper named upload_file should pass.
-        _ok("def upload_file(*a, **k):\n    pass\n" "upload_file('x', 'y', 'z')")
+        _ok("def upload_file(*a, **k):\n    pass\nupload_file('x', 'y', 'z')")
 
 
 class TestHfUploadSandboxLocalPaths:
diff --git a/studio/backend/tests/test_studio_api.py b/studio/backend/tests/test_studio_api.py
index 521c99e126..70a103a2f8 100644
--- a/studio/backend/tests/test_studio_api.py
+++ b/studio/backend/tests/test_studio_api.py
@@ -72,11 +72,7 @@ DEFAULT_VARIANT = "UD-Q4_K_XL"
 PORT = 18222  # high port unlikely to collide
 HOST = "127.0.0.1"
 STARTUP_TIMEOUT = 120  # seconds to wait for banner
-LOG_FILE = (
-    Path(__file__).resolve().parent.parent.parent.parent
-    / "temp"
-    / "test_studio_api.log"
-)
+LOG_FILE = Path(__file__).resolve().parent.parent.parent.parent / "temp" / "test_studio_api.log"
 
 
 # ── Helpers ──────────────────────────────────────────────────────────
@@ -219,9 +215,7 @@ def test_openai_sdk(base_url: str, api_key: str):
     client = OpenAI(base_url = f"{base_url}/v1", api_key = api_key)
     response = client.chat.completions.create(
         model = "current",
-        messages = [
-            {"role": "user", "content": "What is 2+2? Answer with just the number."}
-        ],
+        messages = [{"role": "user", "content": "What is 2+2? Answer with just the number."}],
         stream = True,
     )
     content_parts = []
@@ -390,9 +384,7 @@ def test_openai_tools_nonstream(base_url: str, api_key: str):
     assert "city" in parsed, f"Tool call missing required 'city' arg: {parsed}"
     # Usage must be non-zero (was 0 before the fix)
     usage = data.get("usage") or {}
-    assert (
-        usage.get("prompt_tokens", 0) > 0
-    ), f"Expected non-zero prompt_tokens; got {usage}"
+    assert usage.get("prompt_tokens", 0) > 0, f"Expected non-zero prompt_tokens; got {usage}"
     assert data.get("id"), "Missing response id"
     print(
         f"  PASS  openai tools non-stream: "
@@ -417,8 +409,7 @@ def test_openai_tools_stream(base_url: str, api_key: str):
     assert status == 200, f"Expected 200, got {status}"
     assert len(chunks) > 0, "No SSE chunks received"
     assert _final_finish_reason(chunks) == "tool_calls", (
-        f"Expected final finish_reason='tool_calls', got "
-        f"{_final_finish_reason(chunks)!r}"
+        f"Expected final finish_reason='tool_calls', got " f"{_final_finish_reason(chunks)!r}"
     )
     assembled = _collect_streamed_tool_calls(chunks)
     assert len(assembled) >= 1, "No tool_calls reassembled from stream"
@@ -501,8 +492,7 @@ def test_openai_sdk_tool_calling(base_url: str, api_key: str):
         stream = False,
     )
     assert resp.choices[0].finish_reason == "tool_calls", (
-        f"Expected finish_reason='tool_calls', got "
-        f"{resp.choices[0].finish_reason!r}"
+        f"Expected finish_reason='tool_calls', got " f"{resp.choices[0].finish_reason!r}"
     )
     tool_calls = resp.choices[0].message.tool_calls
     assert tool_calls and len(tool_calls) >= 1, "No tool_calls from SDK"
@@ -510,9 +500,7 @@ def test_openai_sdk_tool_calling(base_url: str, api_key: str):
     assert tc.function.name == "get_weather"
     parsed = json.loads(tc.function.arguments)
     assert "city" in parsed
-    print(
-        f"  PASS  openai SDK tool calling: " f"tool={tc.function.name}, args={parsed}"
-    )
+    print(f"  PASS  openai SDK tool calling: " f"tool={tc.function.name}, args={parsed}")
 
 
 def test_invalid_key_rejected(base_url: str):
@@ -655,9 +643,7 @@ def test_anthropic_sdk(base_url: str, api_key: str):
     message = client.messages.create(
         model = "default",
         max_tokens = 100,
-        messages = [
-            {"role": "user", "content": "What is 2+2? Answer with just the number."}
-        ],
+        messages = [{"role": "user", "content": "What is 2+2? Answer with just the number."}],
     )
     assert message.role == "assistant"
     assert len(message.content) > 0, "Empty content"
@@ -708,9 +694,7 @@ def test_anthropic_with_tools(base_url: str, api_key: str):
     assert "message_stop" in event_types, "Missing message_stop"
 
     full = _collect_anthropic_text(events)
-    print(
-        f"  PASS  anthropic with tools: {len(events)} events, {len(full)} chars content"
-    )
+    print(f"  PASS  anthropic with tools: {len(events)} events, {len(full)} chars content")
 
 
 def test_anthropic_tool_choice_any(base_url: str, api_key: str):
@@ -770,8 +754,7 @@ def test_anthropic_tool_choice_any(base_url: str, api_key: str):
     tool_use_starts = [
         e
         for e in events
-        if e[0] == "content_block_start"
-        and e[1].get("content_block", {}).get("type") == "tool_use"
+        if e[0] == "content_block_start" and e[1].get("content_block", {}).get("type") == "tool_use"
     ]
     assert len(tool_use_starts) >= 1, "No tool_use content block emitted"
     print(
@@ -821,9 +804,7 @@ def _start_server(model: str, variant: str | None) -> tuple[subprocess.Popen, st
         if proc.poll() is not None:
             log_fh.flush()
             log_text = LOG_FILE.read_text()
-            raise RuntimeError(
-                f"Server exited early (code {proc.returncode}):\n{log_text[-2000:]}"
-            )
+            raise RuntimeError(f"Server exited early (code {proc.returncode}):\n{log_text[-2000:]}")
         log_text = LOG_FILE.read_text()
         m = re.search(r"API Key:\s+(sk-unsloth-[a-f0-9]+)", log_text)
         if m:
@@ -833,9 +814,7 @@ def _start_server(model: str, variant: str | None) -> tuple[subprocess.Popen, st
     if not api_key:
         log_text = LOG_FILE.read_text()
         _kill_server(proc)
-        raise RuntimeError(
-            f"Timed out waiting for API key in server output:\n{log_text[-2000:]}"
-        )
+        raise RuntimeError(f"Timed out waiting for API key in server output:\n{log_text[-2000:]}")
 
     # Wait a moment for the model to be fully loaded
     time.sleep(2)
@@ -862,9 +841,7 @@ def _kill_server(proc: subprocess.Popen):
 
 
 def main():
-    parser = argparse.ArgumentParser(
-        description = "End-to-end tests for unsloth studio run"
-    )
+    parser = argparse.ArgumentParser(description = "End-to-end tests for unsloth studio run")
     parser.add_argument(
         "--model",
         default = DEFAULT_MODEL,
@@ -898,9 +875,7 @@ def main():
     run_test(test_help_output)
 
     # ── 2-16. Start server and run API tests ─────────────────────────
-    print(
-        f"\nStarting server: {args.model} (variant={args.gguf_variant}) on port {PORT}..."
-    )
+    print(f"\nStarting server: {args.model} (variant={args.gguf_variant}) on port {PORT}...")
     proc = None
     try:
         proc, api_key = _start_server(args.model, args.gguf_variant)
diff --git a/studio/backend/tests/test_tool_xml_strip.py b/studio/backend/tests/test_tool_xml_strip.py
index 8b90a46d5a..857302d543 100644
--- a/studio/backend/tests/test_tool_xml_strip.py
+++ b/studio/backend/tests/test_tool_xml_strip.py
@@ -77,9 +77,7 @@ def test_strips_orphan_tool_call_no_close():
 
 
 def test_strips_orphan_function_no_close():
-    text = (
-        "I'll call python:\n<function=python>\n<parameter=code>\nprint(1)\n</parameter>"
-    )
+    text = "I'll call python:\n<function=python>\n<parameter=code>\nprint(1)\n</parameter>"
     cleaned = _TOOL_XML_RE.sub("", text)
     assert "<function=" not in cleaned
     assert "I'll call python:" in cleaned
diff --git a/studio/backend/tests/test_trained_model_scan.py b/studio/backend/tests/test_trained_model_scan.py
index 8ba97af701..1958c8d570 100644
--- a/studio/backend/tests/test_trained_model_scan.py
+++ b/studio/backend/tests/test_trained_model_scan.py
@@ -28,9 +28,7 @@ from utils.models.model_config import (
 )
 
 
-def test_scan_trained_models_includes_lora_and_full_finetune_outputs(
-    tmp_path: Path, monkeypatch
-):
+def test_scan_trained_models_includes_lora_and_full_finetune_outputs(tmp_path: Path, monkeypatch):
     # resolve_output_dir refuses absolutes outside outputs_root; point it at tmp_path.
     from utils.models import model_config as _mc
     from utils.paths import storage_roots as _sr
@@ -53,17 +51,14 @@ def test_scan_trained_models_includes_lora_and_full_finetune_outputs(
     (full_dir / "model.safetensors").write_bytes(b"")
 
     found = {
-        name: (path, model_type)
-        for name, path, model_type in scan_trained_models(str(tmp_path))
+        name: (path, model_type) for name, path, model_type in scan_trained_models(str(tmp_path))
     }
 
     assert found[lora_dir.name] == (str(lora_dir), "lora")
     assert found[full_dir.name] == (str(full_dir), "merged")
 
 
-def test_get_base_model_from_checkpoint_falls_back_to_full_finetune_config(
-    tmp_path: Path,
-):
+def test_get_base_model_from_checkpoint_falls_back_to_full_finetune_config(tmp_path: Path):
     (tmp_path / "config.json").write_text(
         json.dumps({"_name_or_path": "HuggingFaceTB/SmolLM-135M"})
     )
@@ -85,14 +80,9 @@ def test_get_base_model_from_lora_rejects_full_finetune_dirs(tmp_path: Path):
 @patch("utils.models.model_config.detect_audio_type", return_value = None)
 @patch("utils.models.model_config.is_vision_model", return_value = False)
 def test_model_config_full_finetune_local_path_is_not_lora(
-    _mock_vision,
-    _mock_audio_type,
-    _mock_audio_input,
-    tmp_path: Path,
+    _mock_vision, _mock_audio_type, _mock_audio_input, tmp_path: Path
 ):
-    (tmp_path / "config.json").write_text(
-        json.dumps({"_name_or_path": "unsloth/Qwen3-4B"})
-    )
+    (tmp_path / "config.json").write_text(json.dumps({"_name_or_path": "unsloth/Qwen3-4B"}))
     (tmp_path / "model.safetensors").write_bytes(b"")
 
     config = ModelConfig.from_identifier(str(tmp_path))
diff --git a/studio/backend/tests/test_training_raw_support.py b/studio/backend/tests/test_training_raw_support.py
index 384247a191..2b1299de5c 100644
--- a/studio/backend/tests/test_training_raw_support.py
+++ b/studio/backend/tests/test_training_raw_support.py
@@ -214,10 +214,7 @@ class TestTrainingRawSupport(unittest.TestCase):
         self.assertEqual(result.dataset[0]["text"], "hello<eos>")
         self.assertEqual(result.dataset[1]["text"], "world<eos>")
         self.assertTrue(
-            any(
-                "null or non-string 'text' values" in notice.message
-                for notice in result.notices
-            )
+            any("null or non-string 'text' values" in notice.message for notice in result.notices)
         )
 
 
diff --git a/studio/backend/tests/test_training_worker_flash_attn.py b/studio/backend/tests/test_training_worker_flash_attn.py
index 94279c28b4..edc47c705e 100644
--- a/studio/backend/tests/test_training_worker_flash_attn.py
+++ b/studio/backend/tests/test_training_worker_flash_attn.py
@@ -15,7 +15,13 @@ from core.training import worker
 def _missing_flash_attn_import():
     real_import = builtins.__import__
 
-    def fake_import(name, globals = None, locals = None, fromlist = (), level = 0):
+    def fake_import(
+        name,
+        globals = None,
+        locals = None,
+        fromlist = (),
+        level = 0,
+    ):
         if name == "flash_attn":
             raise ImportError
         return real_import(name, globals, locals, fromlist, level)
@@ -26,7 +32,13 @@ def _missing_flash_attn_import():
 def _missing_module_import(missing: str):
     real_import = builtins.__import__
 
-    def fake_import(name, globals = None, locals = None, fromlist = (), level = 0):
+    def fake_import(
+        name,
+        globals = None,
+        locals = None,
+        fromlist = (),
+        level = 0,
+    ):
         if name == missing:
             raise ImportError
         return real_import(name, globals, locals, fromlist, level)
@@ -37,9 +49,7 @@ def _missing_module_import(missing: str):
 def test_should_try_runtime_flash_attn_install_threshold_and_skip(monkeypatch):
     monkeypatch.delenv(worker._FLASH_ATTN_SKIP_ENV, raising = False)
     assert worker._should_try_runtime_flash_attn_install(32767) is False
-    assert worker._should_try_runtime_flash_attn_install(
-        32768
-    ) is sys.platform.startswith("linux")
+    assert worker._should_try_runtime_flash_attn_install(32768) is sys.platform.startswith("linux")
 
     monkeypatch.setenv(worker._FLASH_ATTN_SKIP_ENV, "1")
     assert worker._should_try_runtime_flash_attn_install(32768) is False
@@ -105,7 +115,12 @@ def test_runtime_flash_attn_falls_back_to_pypi(monkeypatch):
     )
     monkeypatch.setattr(worker, "install_wheel", mock.Mock())
 
-    def fake_run(cmd, stdout = None, stderr = None, text = None):
+    def fake_run(
+        cmd,
+        stdout = None,
+        stderr = None,
+        text = None,
+    ):
         calls.append(list(cmd))
         return subprocess.CompletedProcess(cmd, 0, "")
 
@@ -131,9 +146,7 @@ def test_runtime_flash_attn_skips_on_blackwell(monkeypatch):
     install_mock = mock.Mock()
 
     monkeypatch.delenv(worker._FLASH_ATTN_SKIP_ENV, raising = False)
-    monkeypatch.setattr(
-        worker, "_should_try_runtime_flash_attn_install", lambda max_seq: True
-    )
+    monkeypatch.setattr(worker, "_should_try_runtime_flash_attn_install", lambda max_seq: True)
     monkeypatch.setattr(worker, "has_blackwell_gpu", lambda: True)
     monkeypatch.setattr(worker, "_install_package_wheel_first", install_mock)
     monkeypatch.setattr(
@@ -504,14 +517,10 @@ def test_tilelang_backend_reinstalls_when_tvm_ffi_is_broken(monkeypatch):
 
     # Repair: --force-reinstall --no-deps, apache-tvm-ffi ONLY (no tilelang).
     assert "--force-reinstall" in repair_args
-    assert (
-        "--no-deps" in repair_args
-    ), "Repair MUST use --no-deps to avoid replacing torch / CUDA"
+    assert "--no-deps" in repair_args, "Repair MUST use --no-deps to avoid replacing torch / CUDA"
     assert "--only-binary=:all:" in repair_args
     assert f"apache-tvm-ffi=={worker._APACHE_TVM_FFI_PACKAGE_VERSION}" in repair_args
-    assert all(
-        "tilelang" not in a for a in repair_args
-    ), "Repair MUST only touch apache-tvm-ffi"
+    assert all("tilelang" not in a for a in repair_args), "Repair MUST only touch apache-tvm-ffi"
 
     # Install: regular dep-resolving install, NO --force-reinstall.
     assert "--force-reinstall" not in install_args
@@ -689,16 +698,12 @@ def test_hook_installs_when_gate_returns_false(monkeypatch):
 
     conv_install = mock.Mock(side_effect = _conv_install_side_effect)
 
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
     monkeypatch.setattr(worker, "_install_package_wheel_first", conv_install)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -722,9 +727,7 @@ def test_hook_skips_install_when_gate_already_true(monkeypatch):
     fla_install = mock.Mock()
     tile_install = mock.Mock()
     conv_install = mock.Mock()
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
     monkeypatch.setattr(worker, "_install_package_wheel_first", conv_install)
     # Tilelang healthy so the post_available path is a no-op (otherwise
@@ -734,9 +737,7 @@ def test_hook_skips_install_when_gate_already_true(monkeypatch):
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.9")
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -764,16 +765,12 @@ def test_hook_idempotent_on_repeat_call(monkeypatch):
         return True
 
     conv_install = mock.Mock(side_effect = _conv_install_side_effect)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
     monkeypatch.setattr(worker, "_install_package_wheel_first", conv_install)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -794,18 +791,12 @@ def test_hook_handles_install_failure_gracefully(monkeypatch):
     def raising_install(eq):
         raise RuntimeError("pip failed to fetch wheel")
 
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", raising_install
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: None
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", raising_install)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: None)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: None)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -819,14 +810,10 @@ def test_hook_can_be_disabled_via_env(monkeypatch):
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
 
     fla_install = mock.Mock()
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setenv(worker._FAST_PATH_HOOKS_SKIP_ENV, "1")
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -841,18 +828,12 @@ def test_hook_clears_lru_cache_before_first_check(monkeypatch):
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
 
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", lambda eq: None
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: None
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", lambda eq: None)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: None)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: None)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
     from transformers.utils import import_utils as _iu
 
     _iu.is_flash_linear_attention_available()
@@ -880,18 +861,12 @@ def test_hook_rewrites_previously_imported_module_bindings(monkeypatch):
         fla_gate.next_return = True
         return True
 
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fake_install
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: True
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fake_install)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: True)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: True)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     # The fake module's local binding has been rewritten to the wrapper.
     assert fake_mod.is_flash_linear_attention_available is not fla_gate
@@ -915,30 +890,20 @@ def test_hook_skips_when_import_utils_unavailable(monkeypatch):
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
     # Should not raise.
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
 
 def test_substring_fallback_unchanged_when_hook_skipped(monkeypatch):
     """Hook disabled -> legacy gate falls back to auto-discovered model types."""
     install_mock = mock.Mock()
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", install_mock
-    )
-    monkeypatch.setattr(
-        worker, "_discover_fla_model_types", lambda: frozenset({"qwen3_5"})
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", install_mock)
+    monkeypatch.setattr(worker, "_discover_fla_model_types", lambda: frozenset({"qwen3_5"}))
     monkeypatch.setenv(worker._FAST_PATH_HOOKS_SKIP_ENV, "1")
 
-    worker._ensure_flash_linear_attention(
-        event_queue = [], model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._ensure_flash_linear_attention(event_queue = [], model_name = "unsloth/Qwen3.5-2B")
     assert install_mock.call_count == 1
 
-    worker._ensure_flash_linear_attention(
-        event_queue = [], model_name = "meta-llama/Llama-3.1-8B"
-    )
+    worker._ensure_flash_linear_attention(event_queue = [], model_name = "meta-llama/Llama-3.1-8B")
     assert install_mock.call_count == 1
 
 
@@ -968,13 +933,9 @@ def test_hook_does_not_install_tilelang_for_model_outside_allowlist(monkeypatch)
 
     fla_install = mock.Mock(side_effect = _fla_install)
     tile_install = mock.Mock(return_value = True)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
-    monkeypatch.setattr(
-        worker, "_install_package_wheel_first", mock.Mock(return_value = True)
-    )
+    monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
     # Hermetize the auto-discovered set so the test stays valid as new
     # transformers releases add FLA-using model_types (eg olmo_hybrid in
@@ -1009,18 +970,12 @@ def test_hook_does_install_tilelang_for_qwen35(monkeypatch):
 
     fla_install = mock.Mock(side_effect = _fla_install)
     tile_install = mock.Mock(return_value = True)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
-    monkeypatch.setattr(
-        worker, "_install_package_wheel_first", mock.Mock(return_value = True)
-    )
+    monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -1079,20 +1034,14 @@ def test_hook_trusts_installer_bool_not_metadata(monkeypatch):
         return False  # but deep import is broken
 
     fake_fla_install = mock.Mock(side_effect = _bad_install)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fake_fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fake_fla_install)
     monkeypatch.setattr(
         worker, "_ensure_tilelang_backend_unconditional", mock.Mock(return_value = True)
     )
-    monkeypatch.setattr(
-        worker, "_install_package_wheel_first", mock.Mock(return_value = True)
-    )
+    monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -1145,14 +1094,10 @@ def test_hook_skips_tilelang_when_fla_install_is_skipped(monkeypatch):
     monkeypatch.setenv(worker._FLA_SKIP_ENV, "1")
     tile_install = mock.Mock(return_value = True)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
-    monkeypatch.setattr(
-        worker, "_install_package_wheel_first", mock.Mock(return_value = True)
-    )
+    monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -1172,21 +1117,15 @@ def test_hook_runs_tilelang_repair_when_fla_already_true(monkeypatch):
 
     fla_install = mock.Mock(return_value = True)
     tile_install = mock.Mock(return_value = True)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", fla_install
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
-    monkeypatch.setattr(
-        worker, "_install_package_wheel_first", mock.Mock(return_value = True)
-    )
+    monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
     # tilelang missing AND tvm-ffi is on broken list — both trigger repair.
     monkeypatch.setattr(worker, "_tilelang_importable", lambda: False)
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.11")
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     from transformers.utils import import_utils as _iu
 
@@ -1290,17 +1229,11 @@ def test_install_fast_path_hooks_sets_fla_tilelang_zero_on_hip(monkeypatch):
     monkeypatch.delenv("FLA_TILELANG", raising = False)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker, "_torch_has_hip", lambda: True)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: True
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: True)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: True)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     assert _os.environ.get("FLA_TILELANG") == "0"
 
@@ -1314,17 +1247,11 @@ def test_install_fast_path_hooks_respects_user_fla_tilelang_override(monkeypatch
     monkeypatch.setenv("FLA_TILELANG", "1")
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker, "_torch_has_hip", lambda: True)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: True
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: True)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: True)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     assert _os.environ["FLA_TILELANG"] == "1"
 
@@ -1336,17 +1263,11 @@ def test_install_fast_path_hooks_does_not_set_fla_tilelang_on_cuda(monkeypatch):
     monkeypatch.delenv("FLA_TILELANG", raising = False)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker, "_torch_has_hip", lambda: False)
-    monkeypatch.setattr(
-        worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True
-    )
-    monkeypatch.setattr(
-        worker, "_ensure_tilelang_backend_unconditional", lambda eq: True
-    )
+    monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", lambda eq: True)
+    monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", lambda eq: True)
     monkeypatch.setattr(worker, "_install_package_wheel_first", lambda **kw: True)
 
-    worker._install_fast_path_hooks(
-        event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B"
-    )
+    worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
     assert _os.environ.get("FLA_TILELANG") is None
 
@@ -1356,9 +1277,7 @@ def test_install_fast_path_hooks_does_not_set_fla_tilelang_on_cuda(monkeypatch):
 # ───────────────────────────────────────────────────────────────────
 
 
-def _make_fake_transformers_tree(
-    tmp_path, fla_types: list[str], non_fla_types: list[str]
-):
+def _make_fake_transformers_tree(tmp_path, fla_types: list[str], non_fla_types: list[str]):
     """Lay out a tmp dir as `transformers/models/{type}/modeling_{type}.py`."""
     pkg = tmp_path / "transformers"
     models = pkg / "models"
@@ -1401,9 +1320,7 @@ def test_discover_fla_model_types_returns_only_fla_users(tmp_path, monkeypatch):
 
 
 def test_discover_fla_model_types_caches_across_calls(tmp_path, monkeypatch):
-    pkg = _make_fake_transformers_tree(
-        tmp_path, fla_types = ["qwen3_5"], non_fla_types = []
-    )
+    pkg = _make_fake_transformers_tree(tmp_path, fla_types = ["qwen3_5"], non_fla_types = [])
     fake = mock.MagicMock(__file__ = str(pkg / "__init__.py"))
     monkeypatch.setitem(sys.modules, "transformers", fake)
     _reset_fla_cache(monkeypatch)
@@ -1432,7 +1349,13 @@ def test_discover_fla_model_types_handles_missing_transformers(monkeypatch):
 
     real_import = builtins.__import__
 
-    def fake_import(name, globals = None, locals = None, fromlist = (), level = 0):
+    def fake_import(
+        name,
+        globals = None,
+        locals = None,
+        fromlist = (),
+        level = 0,
+    ):
         if name == "transformers":
             raise ImportError("transformers not installed")
         return real_import(name, globals, locals, fromlist, level)
@@ -1443,9 +1366,7 @@ def test_discover_fla_model_types_handles_missing_transformers(monkeypatch):
 
 
 def test_discover_fla_model_types_handles_unreadable_file(tmp_path, monkeypatch):
-    pkg = _make_fake_transformers_tree(
-        tmp_path, fla_types = ["qwen3_5"], non_fla_types = []
-    )
+    pkg = _make_fake_transformers_tree(tmp_path, fla_types = ["qwen3_5"], non_fla_types = [])
     fake = mock.MagicMock(__file__ = str(pkg / "__init__.py"))
     monkeypatch.setitem(sys.modules, "transformers", fake)
     _reset_fla_cache(monkeypatch)
@@ -1491,9 +1412,7 @@ def test_model_wants_tilelang_empty_when_transformers_has_no_fla(monkeypatch):
 
 
 def test_model_wants_tilelang_normalizes_separators(monkeypatch):
-    monkeypatch.setattr(
-        worker, "_discover_fla_model_types", lambda: frozenset({"qwen3_next"})
-    )
+    monkeypatch.setattr(worker, "_discover_fla_model_types", lambda: frozenset({"qwen3_next"}))
     for variant in (
         "qwen3-next",
         "Qwen3.Next",
diff --git a/studio/backend/tests/test_transformers_version.py b/studio/backend/tests/test_transformers_version.py
index c031c2fea3..ff5e1f1381 100644
--- a/studio/backend/tests/test_transformers_version.py
+++ b/studio/backend/tests/test_transformers_version.py
@@ -295,9 +295,7 @@ class TestGetTransformersTier:
             "utils.transformers_version._check_config_needs_550",
             return_value = False,
         ):
-            assert (
-                get_transformers_tier("mistralai/Ministral-3-8B-Instruct-2512") == "530"
-            )
+            assert get_transformers_tier("mistralai/Ministral-3-8B-Instruct-2512") == "530"
 
     def test_llama_returns_default(self):
         with (
diff --git a/studio/backend/tests/test_utils.py b/studio/backend/tests/test_utils.py
index 64c9907119..bdb1cd2ce8 100644
--- a/studio/backend/tests/test_utils.py
+++ b/studio/backend/tests/test_utils.py
@@ -25,14 +25,12 @@ import pytest
 # --- Conditional framework imports ---
 try:
     import torch
-
     HAS_TORCH = True
 except ImportError:
     HAS_TORCH = False
 
 try:
     import mlx.core as mx
-
     HAS_MLX = True
 except ImportError:
     HAS_MLX = False
@@ -196,15 +194,12 @@ class TestGetGpuMemoryInfo:
         # can render the correct label. On CUDA / XPU / MLX / CPU hosts
         # it is equivalent to `get_device().value`.
         from utils.hardware.hardware import _backend_label
-
         result = get_gpu_memory_info()
         assert result["backend"] == _backend_label(get_device())
 
     # --- When a GPU IS available ---
 
-    @pytest.mark.skipif(
-        _actual_device() == "cpu", reason = "No GPU available on this machine"
-    )
+    @pytest.mark.skipif(_actual_device() == "cpu", reason = "No GPU available on this machine")
     def test_gpu_available_fields(self):
         result = get_gpu_memory_info()
         assert result["available"] is True
@@ -302,9 +297,7 @@ class TestLogGpuMemory:
             "free_gb": 14.0,
         }
 
-        with patch(
-            "utils.hardware.hardware.get_gpu_memory_info", return_value = fake_info
-        ):
+        with patch("utils.hardware.hardware.get_gpu_memory_info", return_value = fake_info):
             log_gpu_memory("unit-test")
 
         captured = capfd.readouterr()
@@ -315,9 +308,7 @@ class TestLogGpuMemory:
     def test_logs_cpu_fallback_when_no_gpu(self, capfd):
         fake_info = {"available": False, "backend": "cpu"}
 
-        with patch(
-            "utils.hardware.hardware.get_gpu_memory_info", return_value = fake_info
-        ):
+        with patch("utils.hardware.hardware.get_gpu_memory_info", return_value = fake_info):
             log_gpu_memory("cpu-test")
 
         captured = capfd.readouterr()
diff --git a/studio/backend/tests/test_vision_cache.py b/studio/backend/tests/test_vision_cache.py
index 9e7bbdd1fb..2af64dac91 100644
--- a/studio/backend/tests/test_vision_cache.py
+++ b/studio/backend/tests/test_vision_cache.py
@@ -209,9 +209,7 @@ class TestVisionCacheDirectPath:
 
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
     @patch("utils.models.model_config.load_model_config")
-    def test_vision_config_attr_detected_and_cached(
-        self, mock_load_config, mock_needs_t5
-    ):
+    def test_vision_config_attr_detected_and_cached(self, mock_load_config, mock_needs_t5):
         """Models with vision_config (LLaVA, Qwen2-VL, etc.) should be cached as True."""
         cfg = MagicMock(spec = [])  # strict: only explicitly set attrs exist
         cfg.model_type = "qwen2_vl"
diff --git a/studio/backend/tests/test_vram_estimation.py b/studio/backend/tests/test_vram_estimation.py
index e54ae6dcf8..65964908d7 100644
--- a/studio/backend/tests/test_vram_estimation.py
+++ b/studio/backend/tests/test_vram_estimation.py
@@ -316,12 +316,8 @@ class TestLoraParams(unittest.TestCase):
         self.assertLess(qv_only, all_mods)
 
     def test_moe_mlp_modules_scale_with_experts(self):
-        dense_lora = compute_lora_params(
-            LLAMA_8B, 16, ["gate_proj", "up_proj", "down_proj"]
-        )
-        moe_lora = compute_lora_params(
-            MOE_CONFIG, 16, ["gate_proj", "up_proj", "down_proj"]
-        )
+        dense_lora = compute_lora_params(LLAMA_8B, 16, ["gate_proj", "up_proj", "down_proj"])
+        moe_lora = compute_lora_params(MOE_CONFIG, 16, ["gate_proj", "up_proj", "down_proj"])
         ratio = moe_lora / dense_lora
         self.assertAlmostEqual(ratio, 8.0, delta = 0.5)
 
@@ -338,12 +334,8 @@ class TestLoraParams(unittest.TestCase):
         self.assertGreater(moe_lora, dense_lora * 20)
 
     def test_attention_modules_same_for_moe(self):
-        dense_attn = compute_lora_params(
-            LLAMA_8B, 16, ["q_proj", "k_proj", "v_proj", "o_proj"]
-        )
-        moe_attn = compute_lora_params(
-            MOE_CONFIG, 16, ["q_proj", "k_proj", "v_proj", "o_proj"]
-        )
+        dense_attn = compute_lora_params(LLAMA_8B, 16, ["q_proj", "k_proj", "v_proj", "o_proj"])
+        moe_attn = compute_lora_params(MOE_CONFIG, 16, ["q_proj", "k_proj", "v_proj", "o_proj"])
         self.assertEqual(dense_attn, moe_attn)
 
     def test_all_linear_uses_default_text_modules(self):
@@ -466,9 +458,7 @@ class TestActivationBytes(unittest.TestCase):
 
     def test_non_flash_attention_uses_quadratic_path(self):
         seq_len = 4096
-        expected_quadratic = (
-            1 * STRUCTURED_MIXED.num_attention_heads * seq_len * seq_len * 2 * 12.0
-        )
+        expected_quadratic = 1 * STRUCTURED_MIXED.num_attention_heads * seq_len * seq_len * 2 * 12.0
         for attention_implementation in ("eager", "unknown_impl", None):
             with self.subTest(attention_implementation = attention_implementation):
                 non_flash = compute_activation_bytes(
@@ -483,9 +473,7 @@ class TestActivationBytes(unittest.TestCase):
 
     def test_non_flash_attention_without_gc_scales_quadratic_path_by_layers(self):
         seq_len = 4096
-        one_layer = (
-            1 * STRUCTURED_MIXED.num_attention_heads * seq_len * seq_len * 2 * 12.0
-        )
+        one_layer = 1 * STRUCTURED_MIXED.num_attention_heads * seq_len * seq_len * 2 * 12.0
         non_flash = compute_activation_bytes(
             STRUCTURED_MIXED,
             1,
@@ -717,9 +705,7 @@ class TestEstimateTrainingVram(unittest.TestCase):
         )
         v8 = estimate_training_vram(LLAMA_8B, opt8)
         v32 = estimate_training_vram(LLAMA_8B, opt32)
-        self.assertAlmostEqual(
-            v32.optimizer_states / v8.optimizer_states, 1.5, delta = 0.1
-        )
+        self.assertAlmostEqual(v32.optimizer_states / v8.optimizer_states, 1.5, delta = 0.1)
 
     def test_min_gpu_vram_treats_activations_as_per_gpu_fixed(self):
         config = TrainingVramConfig(training_method = "qlora", load_in_4bit = True)
@@ -769,9 +755,7 @@ class TestEstimateTrainingVram(unittest.TestCase):
             optimizer = "adamw_8bit",
             load_in_4bit = False,
         )
-        expected_floor = int(
-            compute_model_weights_bytes(LLAMA_8B, "full", False) * 0.15
-        )
+        expected_floor = int(compute_model_weights_bytes(LLAMA_8B, "full", False) * 0.15)
         with patch(
             "utils.hardware.vram_estimation.compute_gradient_bytes",
             return_value = 1,
@@ -1059,7 +1043,6 @@ class TestDenseLayerIndices(unittest.TestCase):
 class TestKvSharedLayer(unittest.TestCase):
     def test_fully_shared_kv_returns_false_matching_upstream(self):
         from utils.hardware.vram_estimation import _is_kv_shared_layer
-
         arch = ModelArchConfig(
             hidden_size = 512,
             num_hidden_layers = 4,
@@ -1293,9 +1276,7 @@ class TestSharedExperts(unittest.TestCase):
         delta_per_layer = 4096 * 1407 * 3 * 2
         expected_delta = delta_per_layer * 32 * 2
         actual_delta = w_yes - w_no
-        self.assertAlmostEqual(
-            actual_delta, expected_delta, delta = expected_delta * 0.01
-        )
+        self.assertAlmostEqual(actual_delta, expected_delta, delta = expected_delta * 0.01)
 
     def test_deepseek_v3_params_in_range(self):
         total = compute_total_params(DEEPSEEK_V3)
@@ -1411,9 +1392,7 @@ class TestDenseMoEMix(unittest.TestCase):
             moe_intermediate_size = 1024,
             num_dense_layers = 5,
         )
-        lora_all = compute_lora_params(
-            all_moe, 16, ["gate_proj", "up_proj", "down_proj"]
-        )
+        lora_all = compute_lora_params(all_moe, 16, ["gate_proj", "up_proj", "down_proj"])
         lora_mix = compute_lora_params(mixed, 16, ["gate_proj", "up_proj", "down_proj"])
         self.assertNotEqual(lora_all, lora_mix)
 
@@ -1497,9 +1476,7 @@ class TestPerLayerInputSkipAlias(unittest.TestCase):
         delta = _compute_skipped_quantizable_elements(arch)
         self.assertEqual(
             delta,
-            arch.hidden_size
-            * arch.num_hidden_layers
-            * arch.hidden_size_per_layer_input,
+            arch.hidden_size * arch.num_hidden_layers * arch.hidden_size_per_layer_input,
         )
 
     def test_layer_aggregate_skip_includes_per_layer_input_modules(self):
@@ -1578,9 +1555,7 @@ class TestSharedExpertVariants(unittest.TestCase):
     def test_shared_expert_size_separate_from_routed_changes_weight_count(self):
         from utils.hardware.vram_estimation import _compute_moe_mlp_elements
 
-        arch_separate = extract_arch_config(
-            self._hf(shared_expert_intermediate_size = 64)
-        )
+        arch_separate = extract_arch_config(self._hf(shared_expert_intermediate_size = 64))
         arch_implicit = extract_arch_config(self._hf(n_shared_experts = 1))
         # Different shared sizes (64 vs default moe_intermediate_size=128) must
         # produce different MoE element counts.
@@ -1624,9 +1599,7 @@ class TestSharedExpertActivation(unittest.TestCase):
             moe_intermediate_size = 64,
             **fields,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_shared_expert_increases_activation_bytes(self):
         with_shared = self._make(shared_expert_intermediate_size = 64)
@@ -1678,9 +1651,7 @@ class TestPerLayerInputActivation(unittest.TestCase):
             tie_word_embeddings = False,
             **fields,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_ple_increases_activation_bytes(self):
         with_ple = self._make(
@@ -1744,9 +1715,7 @@ class TestKvSharedActivation(unittest.TestCase):
             num_kv_shared_layers = kv_shared,
             layer_types = ["full_attention"] * 4,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_kv_shared_layers_keep_activation_bytes(self):
         shared = self._make(kv_shared = 2)
@@ -1792,10 +1761,7 @@ class TestSparseMoeSkipAliases(unittest.TestCase):
 
     def test_gemma4_layers_experts_alias_pulls_routed(self):
         from utils.hardware.vram_estimation import _compute_skipped_quantizable_elements
-
-        arch = extract_arch_config(
-            self._hf(["model.layers.0.experts"], enable_moe_block = True)
-        )
+        arch = extract_arch_config(self._hf(["model.layers.0.experts"], enable_moe_block = True))
         self.assertGreater(_compute_skipped_quantizable_elements(arch), 0)
 
     def test_qwen_shared_expert_skip_pulls_only_shared(self):
@@ -1823,7 +1789,6 @@ class TestSparseMoeSkipAliases(unittest.TestCase):
 
     def test_exaone_shared_experts_plural_alias(self):
         from utils.hardware.vram_estimation import _compute_skipped_quantizable_elements
-
         arch = extract_arch_config(
             self._hf(
                 ["model.layers.0.mlp.shared_experts"],
@@ -1847,9 +1812,7 @@ class TestAllLinearMoELoraExclusion(unittest.TestCase):
             moe_intermediate_size = 64,
             **fields,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_all_linear_drops_routed_moe_expert_lora(self):
         arch = self._arch()
@@ -1867,9 +1830,7 @@ class TestAllLinearMoELoraExclusion(unittest.TestCase):
     def test_all_linear_includes_attention_lora(self):
         arch = self._arch()
         all_linear = compute_lora_params(arch, 8, "all-linear")
-        attn_only = compute_lora_params(
-            arch, 8, ["q_proj", "k_proj", "v_proj", "o_proj"]
-        )
+        attn_only = compute_lora_params(arch, 8, ["q_proj", "k_proj", "v_proj", "o_proj"])
         # all-linear still attaches to attention nn.Linear modules.
         self.assertGreaterEqual(all_linear, attn_only)
 
@@ -1887,9 +1848,7 @@ class TestExplicitPerLayerInputLora(unittest.TestCase):
             hidden_size_per_layer_input = 32,
             vocab_size_per_layer_input = 128,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_explicit_per_layer_input_gate_returns_nonzero(self):
         arch = self._arch()
@@ -1928,9 +1887,7 @@ class TestTopKExpertActivation(unittest.TestCase):
             moe_intermediate_size = 64,
             **fields,
         )
-        return extract_arch_config(
-            SimpleNamespace(text_config = text_config, quantization_config = {})
-        )
+        return extract_arch_config(SimpleNamespace(text_config = text_config, quantization_config = {}))
 
     def test_num_experts_per_tok_extracted(self):
         arch = self._make(num_experts_per_tok = 4)
@@ -2180,13 +2137,11 @@ class TestLlama4ArchExtraction(unittest.TestCase):
 
     def test_llama4_moe_layers_dispatch_uses_explicit_indices(self):
         from utils.hardware.vram_estimation import _compute_dense_layer_indices
-
         cfg = SimpleNamespace(num_hidden_layers = 4, moe_layers = [1, 3])
         self.assertEqual(_compute_dense_layer_indices(cfg, 4), (0, 2))
 
     def test_llama4_moe_layers_takes_priority_over_first_k_dense_replace(self):
         from utils.hardware.vram_estimation import _compute_dense_layer_indices
-
         cfg = SimpleNamespace(
             num_hidden_layers = 6,
             moe_layers = [2, 4],
@@ -2288,7 +2243,6 @@ class TestDbrxFfnConfigExtraction(unittest.TestCase):
 class TestErniePhaseModuloDispatch(unittest.TestCase):
     def test_phase_modulo_with_interval_two_matches_decoder(self):
         from utils.hardware.vram_estimation import _compute_dense_layer_indices
-
         cfg = SimpleNamespace(
             num_hidden_layers = 10,
             moe_layer_start_index = 2,
@@ -2300,7 +2254,6 @@ class TestErniePhaseModuloDispatch(unittest.TestCase):
 
     def test_phase_modulo_with_interval_three(self):
         from utils.hardware.vram_estimation import _compute_dense_layer_indices
-
         cfg = SimpleNamespace(
             num_hidden_layers = 9,
             moe_layer_start_index = 0,
diff --git a/studio/backend/tests/test_windows_gpu_detection_mock.py b/studio/backend/tests/test_windows_gpu_detection_mock.py
index 023630fb9a..bc887f8cc5 100644
--- a/studio/backend/tests/test_windows_gpu_detection_mock.py
+++ b/studio/backend/tests/test_windows_gpu_detection_mock.py
@@ -169,14 +169,14 @@ def _populate_studio_install(install_dir: Path, runtime: str = "13.1") -> None:
 
 
 def _build_path_dirs_like_start_llama_server(
-    binary_dir: Path, prefix: Path, cuda_path: str = ""
+    binary_dir: Path,
+    prefix: Path,
+    cuda_path: str = "",
 ) -> list[str]:
     """Path-friendly wrapper around LlamaCppBackend._build_windows_path_dirs.
     Asserting against the staticmethod (not a hand-copy) is the point:
     if the win32 PATH order drops _windows_pip_nvidia_dll_dirs, tests fail."""
-    return LlamaCppBackend._build_windows_path_dirs(
-        str(binary_dir), str(prefix), cuda_path
-    )
+    return LlamaCppBackend._build_windows_path_dirs(str(binary_dir), str(prefix), cuda_path)
 
 
 def _mock_nvidia_smi_run(fake_output: str, returncode: int = 0) -> "mock._patch":
@@ -210,9 +210,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         fake_csv = "0, 22805\n"
         with _mock_nvidia_smi_run(fake_csv):
             gpus = LlamaCppBackend._get_gpu_free_memory()
-        assert gpus == [
-            (0, 22805)
-        ], f"GPU probe failed to parse mocked nvidia-smi output: {gpus}"
+        assert gpus == [(0, 22805)], f"GPU probe failed to parse mocked nvidia-smi output: {gpus}"
 
     def test_nvidia_smi_probe_respects_cuda_visible_devices(self, monkeypatch):
         """CUDA_VISIBLE_DEVICES=1 -> only GPU 1 visible."""
@@ -247,9 +245,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
             site / "nvidia" / "cu13" / "bin" / "x86_64",
             site / "torch" / "lib",
         ):
-            assert (
-                str(expected) in out
-            ), f"resolver missed {expected.relative_to(prefix)}: {out}"
+            assert str(expected) in out, f"resolver missed {expected.relative_to(prefix)}: {out}"
 
     def test_path_assembly_makes_cudart_reachable_without_toolkit(self, tmp_path):
         """The #5106 scenario: GPU detected, pip nvidia wheels present,
@@ -260,9 +256,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         _populate_studio_venv(prefix)
         _populate_studio_install(install, runtime = "13.1")
         binary_dir = install / "build" / "bin" / "Release"
-        path_dirs = _build_path_dirs_like_start_llama_server(
-            binary_dir, prefix, cuda_path = ""
-        )
+        path_dirs = _build_path_dirs_like_start_llama_server(binary_dir, prefix, cuda_path = "")
         # binary_dir first -- Windows DLL search step 1.
         assert path_dirs[0] == str(
             binary_dir
@@ -278,9 +272,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         )
         # Defence in depth: both fix paths contribute cudart.
         sources = {Path(e).relative_to(tmp_path).parts[0] for e, _ in cudart_locations}
-        assert (
-            "studio_install" in sources
-        ), f"#5322's cudart drop not reachable: {cudart_locations}"
+        assert "studio_install" in sources, f"#5322's cudart drop not reachable: {cudart_locations}"
         assert (
             "studio_venv" in sources
         ), f"#5324's pip nvidia dir not contributing cudart: {cudart_locations}"
@@ -297,8 +289,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         for required in REAL_UPSTREAM_CUDART_BUNDLE["13.1"]:
             reachable = any((Path(d) / required).exists() for d in path_dirs)
             assert reachable, (
-                f"{required} unreachable from PATH; #5106 not fixed.\n"
-                f"PATH entries: {path_dirs}"
+                f"{required} unreachable from PATH; #5106 not fixed.\n" f"PATH entries: {path_dirs}"
             )
 
     def test_no_pip_nvidia_wheels_still_works_via_install_dir(self, tmp_path):
@@ -310,9 +301,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         _populate_studio_install(install, runtime = "13.1")
         binary_dir = install / "build" / "bin" / "Release"
         path_dirs = _build_path_dirs_like_start_llama_server(binary_dir, prefix)
-        assert path_dirs == [
-            str(binary_dir)
-        ], f"bare venv produced unexpected PATH: {path_dirs}"
+        assert path_dirs == [str(binary_dir)], f"bare venv produced unexpected PATH: {path_dirs}"
         for required in REAL_UPSTREAM_CUDART_BUNDLE["13.1"]:
             assert (
                 binary_dir / required
@@ -336,8 +325,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
             (rel / fn).write_bytes(b"PE-stub")
         path_dirs = _build_path_dirs_like_start_llama_server(rel, prefix)
         cudart_reachable = any(
-            (Path(d) / "cudart64_12.dll").exists()
-            or (Path(d) / "cudart64_13.dll").exists()
+            (Path(d) / "cudart64_12.dll").exists() or (Path(d) / "cudart64_13.dll").exists()
             for d in path_dirs
         )
         assert cudart_reachable, (
@@ -345,8 +333,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
             f"on cudart-less install. PATH entries: {path_dirs}"
         )
         cublas_reachable = any(
-            (Path(d) / "cublas64_12.dll").exists()
-            or (Path(d) / "cublas64_13.dll").exists()
+            (Path(d) / "cublas64_12.dll").exists() or (Path(d) / "cublas64_13.dll").exists()
             for d in path_dirs
         )
         assert cublas_reachable, "cublas unreachable on cudart-less install"
@@ -365,8 +352,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         # Pre-PR PATH: binary_dir only. No pip nvidia dirs, no toolkit.
         pre_pr_path_dirs = [str(rel)]
         cudart_reachable_pre = any(
-            (Path(d) / "cudart64_12.dll").exists()
-            or (Path(d) / "cudart64_13.dll").exists()
+            (Path(d) / "cudart64_12.dll").exists() or (Path(d) / "cudart64_13.dll").exists()
             for d in pre_pr_path_dirs
         )
         assert not cudart_reachable_pre, (
@@ -387,7 +373,5 @@ class TestWindowsSysPlatformMocked:
         out = LlamaCppBackend._windows_pip_nvidia_dll_dirs(str(prefix))
         assert out, f"resolver returned empty under sys.platform=win32: {out}"
         # cu13 arch dir must be in the output.
-        cu13_arch = (
-            prefix / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
-        )
+        cu13_arch = prefix / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
         assert str(cu13_arch) in out
diff --git a/studio/backend/utils/cache_cleanup.py b/studio/backend/utils/cache_cleanup.py
index 4c8e6239a0..9d01b40add 100644
--- a/studio/backend/utils/cache_cleanup.py
+++ b/studio/backend/utils/cache_cleanup.py
@@ -75,8 +75,7 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
 
         if preserve_patterns:
             logger.info(
-                f"Cleaning unsloth compiled cache (preserving {preserve_patterns}): "
-                f"{cache_dir}"
+                f"Cleaning unsloth compiled cache (preserving {preserve_patterns}): " f"{cache_dir}"
             )
 
             for item in cache_dir.iterdir():
diff --git a/studio/backend/utils/datasets/data_collators.py b/studio/backend/utils/datasets/data_collators.py
index 687da74c21..2955ec9023 100644
--- a/studio/backend/utils/datasets/data_collators.py
+++ b/studio/backend/utils/datasets/data_collators.py
@@ -28,19 +28,13 @@ class DataCollatorSpeechSeq2SeqWithPadding:
     processor: Any
 
     def __call__(self, features: List[dict]) -> dict:
-        input_features = [
-            {"input_features": feature["input_features"]} for feature in features
-        ]
-        batch = self.processor.feature_extractor.pad(
-            input_features, return_tensors = "pt"
-        )
+        input_features = [{"input_features": feature["input_features"]} for feature in features]
+        batch = self.processor.feature_extractor.pad(input_features, return_tensors = "pt")
 
         label_features = [{"input_ids": feature["labels"]} for feature in features]
         labels_batch = self.processor.tokenizer.pad(label_features, return_tensors = "pt")
 
-        labels = labels_batch["input_ids"].masked_fill(
-            labels_batch.attention_mask.ne(1), -100
-        )
+        labels = labels_batch["input_ids"].masked_fill(labels_batch.attention_mask.ne(1), -100)
 
         if (labels[:, 0] == self.processor.tokenizer.bos_token_id).all().cpu().item():
             labels = labels[:, 1:]
@@ -169,9 +163,7 @@ class VLMDataCollator:
 
         # Apply chat template
         texts = [
-            self.processor.apply_chat_template(
-                msgs, tokenize = False, add_generation_prompt = False
-            )
+            self.processor.apply_chat_template(msgs, tokenize = False, add_generation_prompt = False)
             for msgs in all_messages
         ]
 
diff --git a/studio/backend/utils/datasets/dataset_none_detect.py b/studio/backend/utils/datasets/dataset_none_detect.py
index 1e884271cc..e48e153fb8 100644
--- a/studio/backend/utils/datasets/dataset_none_detect.py
+++ b/studio/backend/utils/datasets/dataset_none_detect.py
@@ -75,9 +75,7 @@ def _probe_conversation(dataset: Dataset, candidates = None):
             # a list holding a dict/None turn); scalars and list-of-strings must
             # not look like chatml. Upgrade a non-plausible fallback when a later
             # candidate is plausible, so probe order keeps the best match.
-            if all_corrupt_fallback is None or not all_corrupt_fallback.get(
-                "has_plausible_turns"
-            ):
+            if all_corrupt_fallback is None or not all_corrupt_fallback.get("has_plausible_turns"):
                 has_plausible_turns = False
                 for i in range(min(len(dataset), 100)):
                     cell = dataset[i][col]
@@ -122,9 +120,7 @@ def _probe_conversation(dataset: Dataset, candidates = None):
         _CONV_KEYS = {"role", "from", "content", "value"}
         if not any(keys <= turn_keys for keys in _CHAT_KEY_SETS):
             schema_less_plausible = bool(turn_keys & _CONV_KEYS)
-            if all_corrupt_fallback is None or not all_corrupt_fallback.get(
-                "has_plausible_turns"
-            ):
+            if all_corrupt_fallback is None or not all_corrupt_fallback.get("has_plausible_turns"):
                 all_corrupt_fallback = {
                     "column": col,
                     "turn_keys": turn_keys,
@@ -167,14 +163,11 @@ def is_none_or_empty(value) -> bool:
         non_text_blocks = [item for item in dict_blocks if item.get("type") != "text"]
         if non_text_blocks:
             return False
-        text_values = [
-            item.get("text") for item in dict_blocks if item.get("type") == "text"
-        ]
+        text_values = [item.get("text") for item in dict_blocks if item.get("type") == "text"]
         if text_values and all(
             t is None
             or (
-                isinstance(t, str)
-                and not t.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip()
+                isinstance(t, str) and not t.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip()
             )
             for t in text_values
         ):
@@ -285,9 +278,7 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
             stats["rows_with_none_turns"] += 1
             stats["total_none_turns"] += 1
             stats["rows_all_none"] += 1
-            stats["none_by_role"]["unknown"] = (
-                stats["none_by_role"].get("unknown", 0) + 1
-            )
+            stats["none_by_role"]["unknown"] = stats["none_by_role"].get("unknown", 0) + 1
             stats["none_by_type"][vtype] = stats["none_by_type"].get(vtype, 0) + 1
             stats["findings"].append(
                 {
@@ -306,9 +297,7 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
             stats["rows_with_none_turns"] += 1
             stats["total_none_turns"] += 1
             stats["rows_all_none"] += 1
-            stats["none_by_role"]["unknown"] = (
-                stats["none_by_role"].get("unknown", 0) + 1
-            )
+            stats["none_by_role"]["unknown"] = stats["none_by_role"].get("unknown", 0) + 1
             stats["none_by_type"]["empty_conversation"] = (
                 stats["none_by_type"].get("empty_conversation", 0) + 1
             )
@@ -336,9 +325,7 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
                         "raw_value": repr(turn),
                     }
                 )
-                stats["none_by_role"]["unknown"] = (
-                    stats["none_by_role"].get("unknown", 0) + 1
-                )
+                stats["none_by_role"]["unknown"] = stats["none_by_role"].get("unknown", 0) + 1
                 vtype = "None" if turn is None else "invalid_type"
                 stats["none_by_type"][vtype] = stats["none_by_type"].get(vtype, 0) + 1
                 continue
@@ -359,20 +346,14 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
             if "from" in turn and "value" in turn:
                 content = turn.get("value")
             elif "role" in turn:
-                content = (
-                    turn.get("content") if "content" in turn else turn.get("value")
-                )
+                content = turn.get("content") if "content" in turn else turn.get("value")
             elif "from" in turn:
                 content = turn.get("value")
             else:
-                content = (
-                    turn.get("content") if "content" in turn else turn.get("value")
-                )
+                content = turn.get("content") if "content" in turn else turn.get("value")
             # Assistant tool-call turns carry empty content + tool_calls and are
             # valid; the exemption is assistant-only.
-            if is_none_or_empty(content) and not (
-                role == "assistant" and turn.get("tool_calls")
-            ):
+            if is_none_or_empty(content) and not (role == "assistant" and turn.get("tool_calls")):
                 vtype = _classify_empty(content)
                 row_findings.append(
                     {
@@ -469,9 +450,7 @@ FORMAT_REGISTRY = [
     },
     {
         "name": "sharegpt",
-        "match": lambda ds, conv: (
-            conv is not None and {"from", "value"} <= conv["turn_keys"]
-        ),
+        "match": lambda ds, conv: (conv is not None and {"from", "value"} <= conv["turn_keys"]),
         "scan": find_none_sharegpt,
     },
     {
@@ -532,13 +511,11 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
     _dict_types = []
     try:
         from datasets import DatasetDict as _DatasetDict
-
         _dict_types.append(_DatasetDict)
     except ImportError:
         pass
     try:
         from datasets import IterableDatasetDict as _IterableDatasetDict
-
         _dict_types.append(_IterableDatasetDict)
     except ImportError:
         pass
@@ -552,7 +529,6 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
     # instead of a confusing TypeError downstream.
     try:
         from datasets import IterableDataset as _IterableDataset
-
         if isinstance(dataset, _IterableDataset):
             raise ValueError(
                 "scan_dataset requires a materialized Dataset, not an IterableDataset. "
@@ -658,7 +634,11 @@ def _print_summary_header(stats: dict, fmt: str) -> bool:
     return True
 
 
-def print_report(stats: dict, fmt: str, summary_only: bool = False):
+def print_report(
+    stats: dict,
+    fmt: str,
+    summary_only: bool = False,
+):
     """Print a human-readable summary, optionally with full findings list."""
     has_findings = _print_summary_header(stats, fmt)
     if not has_findings or summary_only:
@@ -689,7 +669,12 @@ def print_report(stats: dict, fmt: str, summary_only: bool = False):
     print(f"{'=' * 64}")
 
 
-def show_row(dataset: Dataset, row_indices: list[int], fmt: str, col: str = None):
+def show_row(
+    dataset: Dataset,
+    row_indices: list[int],
+    fmt: str,
+    col: str = None,
+):
     """Print the full contents of specific rows for inspection.
 
     Used by test_codex_fixes.py to verify row rendering behaviour.
@@ -750,9 +735,7 @@ def show_row(dataset: Dataset, row_indices: list[int], fmt: str, col: str = None
                     # Mirror scanner logic: tool_calls exemption is assistant-only;
                     # other roles with empty content + tool_calls are still bad.
                     r = t.get("role") if t.get("role") is not None else t.get("from")
-                    if is_none_or_empty(c) and not (
-                        str(r) == "assistant" and t.get("tool_calls")
-                    ):
+                    if is_none_or_empty(c) and not (str(r) == "assistant" and t.get("tool_calls")):
                         return True
                     return False
 
@@ -773,19 +756,11 @@ def show_row(dataset: Dataset, row_indices: list[int], fmt: str, col: str = None
                     if "from" in turn and "value" in turn:
                         content = turn.get("value")
                     elif "role" in turn:
-                        content = (
-                            turn.get("content")
-                            if "content" in turn
-                            else turn.get("value")
-                        )
+                        content = turn.get("content") if "content" in turn else turn.get("value")
                     elif "from" in turn:
                         content = turn.get("value")
                     else:
-                        content = (
-                            turn.get("content")
-                            if "content" in turn
-                            else turn.get("value")
-                        )
+                        content = turn.get("content") if "content" in turn else turn.get("value")
                     if is_none_or_empty(content) and not (
                         role == "assistant" and turn.get("tool_calls")
                     ):
@@ -827,12 +802,8 @@ examples:
   python dataset_none_detect.py org/my-dataset --token hf_...
         """,
     )
-    parser.add_argument(
-        "dataset", help = "HuggingFace dataset repo id (e.g. org/my-dataset)"
-    )
-    parser.add_argument(
-        "--split", default = "train", help = "Dataset split to load (default: train)"
-    )
+    parser.add_argument("dataset", help = "HuggingFace dataset repo id (e.g. org/my-dataset)")
+    parser.add_argument("--split", default = "train", help = "Dataset split to load (default: train)")
     parser.add_argument(
         "--format",
         default = "auto",
diff --git a/studio/backend/utils/datasets/dataset_utils.py b/studio/backend/utils/datasets/dataset_utils.py
index 26378d64ee..792e0ea9bc 100644
--- a/studio/backend/utils/datasets/dataset_utils.py
+++ b/studio/backend/utils/datasets/dataset_utils.py
@@ -202,7 +202,11 @@ _CHATML_ROLE_ORDER = ("system", "user", "assistant")
 _CHATML_TO_ALPACA = {"user": "instruction", "system": "input", "assistant": "output"}
 
 
-def _apply_user_mapping(dataset, mapping: dict, batch_size: int = 1000):
+def _apply_user_mapping(
+    dataset,
+    mapping: dict,
+    batch_size: int = 1000,
+):
     """
     Apply user-provided column mapping to convert dataset to conversations format.
 
@@ -279,7 +283,10 @@ def _extract_column_value(val, col: str, label_mapping: dict) -> str:
 
 
 def _apply_template_mapping(
-    dataset, column_roles: dict, meta: dict, batch_size: int = 1000
+    dataset,
+    column_roles: dict,
+    meta: dict,
+    batch_size: int = 1000,
 ):
     """
     Apply advisor-driven mapping for non-conversational datasets.
@@ -324,9 +331,7 @@ def _apply_template_mapping(
             user_parts = []
             for col in role_groups["user"]:
                 if col in examples:
-                    user_parts.append(
-                        _extract_column_value(examples[col][i], col, label_mapping)
-                    )
+                    user_parts.append(_extract_column_value(examples[col][i], col, label_mapping))
             if user_parts:
                 convo.append({"role": "user", "content": "\n".join(user_parts)})
 
@@ -334,9 +339,7 @@ def _apply_template_mapping(
             asst_parts = []
             for col in role_groups["assistant"]:
                 if col in examples:
-                    asst_parts.append(
-                        _extract_column_value(examples[col][i], col, label_mapping)
-                    )
+                    asst_parts.append(_extract_column_value(examples[col][i], col, label_mapping))
             if asst_parts:
                 convo.append({"role": "assistant", "content": "\n".join(asst_parts)})
 
@@ -351,7 +354,11 @@ def _apply_template_mapping(
     )
 
 
-def _apply_user_mapping_alpaca(dataset, mapping: dict, batch_size: int = 1000):
+def _apply_user_mapping_alpaca(
+    dataset,
+    mapping: dict,
+    batch_size: int = 1000,
+):
     """
     Apply user-provided column mapping to convert dataset to Alpaca format.
 
@@ -382,11 +389,7 @@ def _apply_user_mapping_alpaca(dataset, mapping: dict, batch_size: int = 1000):
                 ("output", outputs),
             ):
                 col = col_for[field]
-                val = (
-                    str(examples[col][i])
-                    if col and col in examples and examples[col][i]
-                    else ""
-                )
+                val = str(examples[col][i]) if col and col in examples and examples[col][i] else ""
                 dest.append(val)
         return {"instruction": instructions, "input": inputs, "output": outputs}
 
@@ -464,9 +467,7 @@ def format_dataset(
             else:
                 # auto / chatml / sharegpt / conversational — all produce chatml conversations
                 # (sharegpt is always standardized to role/content internally)
-                mapped_dataset = _apply_user_mapping(
-                    dataset, custom_format_mapping, batch_size
-                )
+                mapped_dataset = _apply_user_mapping(dataset, custom_format_mapping, batch_size)
                 final_format = "chatml_conversations"
                 chat_column = "conversations"
 
@@ -578,9 +579,7 @@ def format_dataset(
 
         # Unknown - try standardization, if fails pass as is
         else:
-            warnings.append(
-                f"Unknown format detected. Keys found: {detected['sample_keys']}"
-            )
+            warnings.append(f"Unknown format detected. Keys found: {detected['sample_keys']}")
 
             # NEW: Try heuristic detection
             if auto_detect_custom:
@@ -606,9 +605,7 @@ def format_dataset(
                                     if role == target_role and col_name in examples:
                                         content = examples[col_name][i]
                                         if content and str(content).strip():
-                                            convo.append(
-                                                {"role": role, "content": str(content)}
-                                            )
+                                            convo.append({"role": role, "content": str(content)})
                             conversations.append(convo)
 
                         return {"conversations": conversations, **preserved_columns}
@@ -656,9 +653,7 @@ def format_dataset(
                         "warnings": warnings,
                     }
                 except Exception as e:
-                    warnings.append(
-                        f"Could not standardize: {e}. Passing dataset as-is."
-                    )
+                    warnings.append(f"Could not standardize: {e}. Passing dataset as-is.")
 
             # Return as-is with warnings
             return {
@@ -928,9 +923,7 @@ def format_and_template_dataset(
                         f"text='{user_vlm_text_column}') failed: {e} — "
                         f"falling back to auto-detection"
                     )
-                    logger.info(
-                        f"⚠️ User VLM mapping failed, falling back to auto-detection..."
-                    )
+                    logger.info(f"⚠️ User VLM mapping failed, falling back to auto-detection...")
                     custom_format_mapping = None  # clear so auto-detection runs below
             else:
                 errors.append(
@@ -984,9 +977,7 @@ def format_and_template_dataset(
                     dataset_name = dataset_name,
                     progress_callback = progress_callback,
                 )
-                warnings.append(
-                    "Converted from ShareGPT+image format to standard VLM format"
-                )
+                warnings.append("Converted from ShareGPT+image format to standard VLM format")
             except Exception as e:
                 errors.append(f"Failed to convert ShareGPT+image format: {e}")
                 import traceback
@@ -1020,7 +1011,6 @@ def format_and_template_dataset(
                 friendly = None
                 try:
                     from .llm_assist import llm_generate_dataset_warning
-
                     friendly = llm_generate_dataset_warning(
                         issues,
                         dataset_name = dataset_name,
@@ -1055,13 +1045,9 @@ def format_and_template_dataset(
                 )
 
                 if vlm_instruction:
-                    warnings.append(
-                        f"Using user-provided instruction: '{vlm_instruction}'"
-                    )
+                    warnings.append(f"Using user-provided instruction: '{vlm_instruction}'")
                 else:
-                    warnings.append(
-                        "Auto-generated instruction based on dataset analysis"
-                    )
+                    warnings.append("Auto-generated instruction based on dataset analysis")
 
             except Exception as e:
                 errors.append(f"Failed to convert to VLM format: {e}")
@@ -1166,9 +1152,7 @@ def format_and_template_dataset(
         summary = get_dataset_info_summary(dataset_info)
 
         # Combine results
-        all_warnings = dataset_info.get("warnings", []) + template_result.get(
-            "warnings", []
-        )
+        all_warnings = dataset_info.get("warnings", []) + template_result.get("warnings", [])
         all_errors = template_result.get("errors", [])
 
         # If format_dataset returned "unknown" but apply_chat_template rescued
diff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.py
index 289b30e55e..5433d3115c 100644
--- a/studio/backend/utils/datasets/format_conversion.py
+++ b/studio/backend/utils/datasets/format_conversion.py
@@ -140,7 +140,11 @@ def standardize_chat_format(
     return dataset.map(_standardize_dataset, **dataset_map_kwargs)
 
 
-def convert_chatml_to_alpaca(dataset, batch_size = 1000, num_proc = None):
+def convert_chatml_to_alpaca(
+    dataset,
+    batch_size = 1000,
+    num_proc = None,
+):
     """
     Converts ChatML format (messages OR conversations) to Alpaca format.
     Handles both standardized and ShareGPT formats.
@@ -151,7 +155,6 @@ def convert_chatml_to_alpaca(dataset, batch_size = 1000, num_proc = None):
     """
     try:
         from torch.utils.data import IterableDataset
-
         _is_torch_iterable = isinstance(dataset, IterableDataset)
     except ImportError:
         _is_torch_iterable = False
@@ -159,15 +162,11 @@ def convert_chatml_to_alpaca(dataset, batch_size = 1000, num_proc = None):
     def _convert(examples):
         # Auto-detect which column name is used
         chatml_data = (
-            examples.get("messages")
-            or examples.get("conversations")
-            or examples.get("texts")
+            examples.get("messages") or examples.get("conversations") or examples.get("texts")
         )
 
         if chatml_data is None:
-            raise ValueError(
-                "No 'messages' or 'conversations' or 'texts' column found."
-            )
+            raise ValueError("No 'messages' or 'conversations' or 'texts' column found.")
 
         instructions = []
         outputs = []
@@ -215,7 +214,11 @@ def convert_chatml_to_alpaca(dataset, batch_size = 1000, num_proc = None):
     return dataset.map(_convert, **dataset_map_kwargs)
 
 
-def convert_alpaca_to_chatml(dataset, batch_size = 1000, num_proc = None):
+def convert_alpaca_to_chatml(
+    dataset,
+    batch_size = 1000,
+    num_proc = None,
+):
     """
     Converts Alpaca format to ChatML format.
 
@@ -223,7 +226,6 @@ def convert_alpaca_to_chatml(dataset, batch_size = 1000, num_proc = None):
     """
     try:
         from torch.utils.data import IterableDataset
-
         _is_torch_iterable = isinstance(dataset, IterableDataset)
     except ImportError:
         _is_torch_iterable = False
@@ -328,16 +330,12 @@ def convert_to_vlm_format(
         instruction_column = instruction_info.get("instruction_column")
         uses_dynamic = instruction_info["uses_dynamic_instruction"]
 
-        logger.info(
-            f"📝 Auto-detected instruction type: {instruction_info['instruction_type']}"
-        )
+        logger.info(f"📝 Auto-detected instruction type: {instruction_info['instruction_type']}")
         logger.info(f"📝 Confidence: {instruction_info['confidence']:.2f}")
         if not uses_dynamic:
             logger.info(f"📝 Using instruction: '{instruction}'")
         else:
-            logger.info(
-                f"📝 Using dynamic instructions from column: '{instruction_column}'"
-            )
+            logger.info(f"📝 Using dynamic instructions from column: '{instruction_column}'")
     else:
         instruction_column = None
         uses_dynamic = False
@@ -351,13 +349,11 @@ def convert_to_vlm_format(
             if image_data.startswith(("http://", "https://")):
                 import fsspec
                 from io import BytesIO
-
                 with fsspec.open(image_data, "rb", expand = True) as f:
                     image_data = Image.open(BytesIO(f.read())).convert("RGB")
             elif _image_lookup is not None and image_data in _image_lookup:
                 # Bare filename → resolve via HF repo lookup
                 from huggingface_hub import hf_hub_download
-
                 local_path = hf_hub_download(
                     dataset_name,
                     _image_lookup[image_data],
@@ -371,7 +367,6 @@ def convert_to_vlm_format(
         text_data = sample[text_column]
         if isinstance(text_data, list) and len(text_data) > 0:
             import random
-
             text_data = random.choice(text_data)
 
         # Get instruction (static or dynamic)
@@ -397,9 +392,7 @@ def convert_to_vlm_format(
 
     total = len(dataset)
     first_image = next(iter(dataset))[image_column]
-    has_urls = isinstance(first_image, str) and first_image.startswith(
-        ("http://", "https://")
-    )
+    has_urls = isinstance(first_image, str) and first_image.startswith(("http://", "https://"))
 
     # ── Bare-filename detection: images stored as filenames (e.g. "img_001.png")
     #    that don't exist locally.  Build a basename→repo_path lookup so we can
@@ -449,9 +442,7 @@ def convert_to_vlm_format(
 
         num_workers = safe_thread_num_proc()
         _notify(f"Probing {PROBE_SIZE} image URLs with {num_workers} workers...")
-        logger.info(
-            f"🔍 Probing {PROBE_SIZE}/{total} image URLs with {num_workers} workers..."
-        )
+        logger.info(f"🔍 Probing {PROBE_SIZE}/{total} image URLs with {num_workers} workers...")
 
         probe_samples = [dataset[i] for i in range(PROBE_SIZE)]
         probe_ok = 0
@@ -459,9 +450,7 @@ def convert_to_vlm_format(
         probe_start = time.time()
 
         with ThreadPoolExecutor(max_workers = num_workers) as executor:
-            futures = {
-                executor.submit(_convert_single_sample, s): s for s in probe_samples
-            }
+            futures = {executor.submit(_convert_single_sample, s): s for s in probe_samples}
             for future in as_completed(futures):
                 try:
                     future.result()
@@ -483,7 +472,6 @@ def convert_to_vlm_format(
             friendly = None
             try:
                 from .llm_assist import llm_generate_dataset_warning
-
                 friendly = llm_generate_dataset_warning(
                     issues,
                     dataset_name = dataset_name,
@@ -554,9 +542,7 @@ def convert_to_vlm_format(
                     except Exception as e:
                         failed_count += 1
                         if failed_count == 1:
-                            logger.info(
-                                f"First VLM conversion failure: {type(e).__name__}: {e}"
-                            )
+                            logger.info(f"First VLM conversion failure: {type(e).__name__}: {e}")
 
             converted_list.extend(r for r in batch_results if r is not None)
 
@@ -581,9 +567,7 @@ def convert_to_vlm_format(
                 failed_count += 1
                 if failed_count == 1:
                     # Log the first failure to aid debugging
-                    logger.info(
-                        f"First VLM conversion failure: {type(e).__name__}: {e}"
-                    )
+                    logger.info(f"First VLM conversion failure: {type(e).__name__}: {e}")
             pbar.set_postfix(ok = len(converted_list), failed = failed_count, refresh = False)
         pbar.close()
 
@@ -601,7 +585,6 @@ def convert_to_vlm_format(
             friendly = None
             try:
                 from .llm_assist import llm_generate_dataset_warning
-
                 friendly = llm_generate_dataset_warning(
                     issues,
                     dataset_name = dataset_name,
@@ -627,7 +610,6 @@ def convert_to_vlm_format(
         friendly = None
         try:
             from .llm_assist import llm_generate_dataset_warning
-
             friendly = llm_generate_dataset_warning(
                 issues,
                 dataset_name = dataset_name,
@@ -739,12 +721,10 @@ def convert_sharegpt_with_images_to_vlm_format(
             if image_data.startswith(("http://", "https://")):
                 import fsspec
                 from io import BytesIO
-
                 with fsspec.open(image_data, "rb", expand = True) as f:
                     return Image.open(BytesIO(f.read())).convert("RGB")
             elif _image_lookup is not None and image_data in _image_lookup:
                 from huggingface_hub import hf_hub_download
-
                 local_path = hf_hub_download(
                     dataset_name,
                     _image_lookup[image_data],
@@ -753,12 +733,9 @@ def convert_sharegpt_with_images_to_vlm_format(
                 return Image.open(local_path).convert("RGB")
             else:
                 return Image.open(image_data).convert("RGB")
-        if isinstance(image_data, dict) and (
-            "bytes" in image_data or "path" in image_data
-        ):
+        if isinstance(image_data, dict) and ("bytes" in image_data or "path" in image_data):
             if image_data.get("bytes"):
                 from io import BytesIO
-
                 return Image.open(BytesIO(image_data["bytes"])).convert("RGB")
             if image_data.get("path"):
                 return Image.open(image_data["path"]).convert("RGB")
@@ -812,9 +789,7 @@ def convert_sharegpt_with_images_to_vlm_format(
     pbar.close()
 
     if failed_count > 0:
-        logger.info(
-            f"⚠️ Skipped {failed_count}/{total} ({failed_count*100//total}%) samples"
-        )
+        logger.info(f"⚠️ Skipped {failed_count}/{total} ({failed_count*100//total}%) samples")
 
     if len(converted_list) == 0:
         raise ValueError(
@@ -840,9 +815,7 @@ def convert_llava_to_vlm_format(dataset):
     """
     from PIL import Image
 
-    logger.info(
-        f"🔄 Converting {len(dataset)} samples from Llava format to standard VLM format..."
-    )
+    logger.info(f"🔄 Converting {len(dataset)} samples from Llava format to standard VLM format...")
 
     def _convert_single_sample(sample):
         """Convert a single llava sample to standard VLM format."""
diff --git a/studio/backend/utils/datasets/format_detection.py b/studio/backend/utils/datasets/format_detection.py
index 7b70ff3a76..829838064a 100644
--- a/studio/backend/utils/datasets/format_detection.py
+++ b/studio/backend/utils/datasets/format_detection.py
@@ -13,10 +13,7 @@ import re
 
 def _keyword_in_column(keyword: str, col_name: str) -> bool:
     """Word-boundary keyword match to avoid false positives like 'pic' in 'topic'."""
-    return (
-        re.search(r"\b" + re.escape(keyword) + r"\b", col_name, re.IGNORECASE)
-        is not None
-    )
+    return re.search(r"\b" + re.escape(keyword) + r"\b", col_name, re.IGNORECASE) is not None
 
 
 def detect_dataset_format(dataset):
@@ -220,10 +217,7 @@ def detect_custom_format_heuristic(dataset):
             return True
 
         for pattern in metadata_prefix_patterns:
-            if (
-                col_lower.startswith(pattern.split("_")[0] + "_")
-                and col_lower != pattern
-            ):
+            if col_lower.startswith(pattern.split("_")[0] + "_") and col_lower != pattern:
                 if "_" in col_lower:
                     prefix = col_lower.split("_")[0]
                     if prefix in ["generation", "pass", "inference"]:
@@ -267,9 +261,7 @@ def detect_custom_format_heuristic(dataset):
         if role_type == "user":
             col_lower = col_name.lower()
             # If column is ONLY "task" (or task_xxx), give it lower priority for user role
-            if "task" in col_lower and not any(
-                kw in col_lower for kw in user_words_high_priority
-            ):
+            if "task" in col_lower and not any(kw in col_lower for kw in user_words_high_priority):
                 score -= 15  # Significant penalty so other user columns win
 
         priority_bonus = get_priority_score(col_name)
@@ -301,17 +293,13 @@ def detect_custom_format_heuristic(dataset):
     content_columns = [col for col in all_columns if not is_metadata(col)]
 
     # Count candidates first
-    assistant_potential = [
-        col for col in content_columns if has_keyword(col, assistant_words)
-    ]
+    assistant_potential = [col for col in content_columns if has_keyword(col, assistant_words)]
     user_potential = [col for col in content_columns if has_keyword(col, user_words)]
 
     # STEP 1: Find best ASSISTANT column
     assistant_candidates = []
     for col in assistant_potential:
-        score = score_column(
-            col, assistant_words, "assistant", len(assistant_potential)
-        )
+        score = score_column(col, assistant_words, "assistant", len(assistant_potential))
         if score > 0:
             assistant_candidates.append((col, score))
 
@@ -518,7 +506,6 @@ def _is_image_value(value) -> bool:
     # PIL Image instance
     try:
         from PIL.Image import Image as PILImage
-
         if isinstance(value, PILImage):
             return True
     except ImportError:
@@ -647,9 +634,7 @@ def detect_vlm_dataset_structure(dataset):
                     if isinstance(content[0], dict) and "type" in content[0]:
                         # Check for llava format
                         has_index = any(
-                            "index" in item
-                            for item in content
-                            if isinstance(item, dict)
+                            "index" in item for item in content if isinstance(item, dict)
                         )
                         has_images_column = "images" in column_names
 
@@ -664,9 +649,7 @@ def detect_vlm_dataset_structure(dataset):
 
                         # Standard VLM format
                         has_image = any(
-                            "image" in item
-                            for item in content
-                            if isinstance(item, dict)
+                            "image" in item for item in content if isinstance(item, dict)
                         )
                         if has_image:
                             return {
@@ -777,9 +760,7 @@ def detect_vlm_dataset_structure(dataset):
             return True
 
         # Check prefixes
-        if any(
-            col_lower.startswith(prefix) for prefix in metadata_patterns["prefixes"]
-        ):
+        if any(col_lower.startswith(prefix) for prefix in metadata_patterns["prefixes"]):
             return True
 
         return False
@@ -791,9 +772,7 @@ def detect_vlm_dataset_structure(dataset):
             return 100
 
         # Dict with image data (bytes/path from HF Image feature)
-        if isinstance(sample_value, dict) and (
-            "bytes" in sample_value or "path" in sample_value
-        ):
+        if isinstance(sample_value, dict) and ("bytes" in sample_value or "path" in sample_value):
             return 75
 
         if isinstance(sample_value, str):
@@ -818,9 +797,7 @@ def detect_vlm_dataset_structure(dataset):
 
         # Local file — check it exists
         if not sample_value.startswith(("http://", "https://")):
-            return os.path.exists(
-                sample_value
-            )  # bare filenames return False here, that's OK
+            return os.path.exists(sample_value)  # bare filenames return False here, that's OK
 
         # URL — quick HEAD request with short timeout
         try:
diff --git a/studio/backend/utils/datasets/llm_assist.py b/studio/backend/utils/datasets/llm_assist.py
index 758717f76b..10004ce3db 100644
--- a/studio/backend/utils/datasets/llm_assist.py
+++ b/studio/backend/utils/datasets/llm_assist.py
@@ -68,9 +68,7 @@ def precache_helper_gguf():
         return
 
     repo = os.environ.get("UNSLOTH_HELPER_MODEL_REPO", DEFAULT_HELPER_MODEL_REPO)
-    variant = os.environ.get(
-        "UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT
-    )
+    variant = os.environ.get("UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT)
 
     try:
         from huggingface_hub import HfApi, hf_hub_download
@@ -86,9 +84,7 @@ def precache_helper_gguf():
 
         # Find all GGUF files matching the variant (may be split into shards)
         variant_lower = variant.lower().replace("-", "_")
-        matching = sorted(
-            f for f in gguf_files if variant_lower in f.lower().replace("-", "_")
-        )
+        matching = sorted(f for f in gguf_files if variant_lower in f.lower().replace("-", "_"))
 
         if matching:
             logger.info(
@@ -119,9 +115,7 @@ def _run_with_helper(prompt: str, max_tokens: int = 256) -> Optional[str]:
         return None
 
     repo = os.environ.get("UNSLOTH_HELPER_MODEL_REPO", DEFAULT_HELPER_MODEL_REPO)
-    variant = os.environ.get(
-        "UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT
-    )
+    variant = os.environ.get("UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT)
 
     backend = None
     try:
@@ -143,9 +137,7 @@ def _run_with_helper(prompt: str, max_tokens: int = 256) -> Optional[str]:
             return None
 
         messages = [{"role": "user", "content": prompt}]
-        logger.info(
-            "Helper model request: enable_thinking=False (per-request override)"
-        )
+        logger.info("Helper model request: enable_thinking=False (per-request override)")
         cumulative = ""
         for chunk in backend.generate_chat_completion(
             messages = messages,
@@ -240,10 +232,7 @@ def llm_generate_vlm_instruction(
     }
 
 
-def llm_classify_columns(
-    column_names: list[str],
-    samples: list[dict],
-) -> Optional[dict[str, str]]:
+def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Optional[dict[str, str]]:
     """
     Ask a helper LLM to classify dataset columns into roles.
 
@@ -294,7 +283,6 @@ def llm_classify_columns(
     except json.JSONDecodeError:
         # Try to find JSON object in the response
         import re
-
         match = re.search(r"\{[^}]+\}", text)
         if match:
             try:
@@ -313,11 +301,7 @@ def llm_classify_columns(
     valid_roles = {"user", "assistant", "system", "metadata"}
     cleaned = {}
     for col, role in mapping.items():
-        if (
-            col in column_names
-            and isinstance(role, str)
-            and role.lower() in valid_roles
-        ):
+        if col in column_names and isinstance(role, str) and role.lower() in valid_roles:
             cleaned[col] = role.lower()
 
     if not cleaned:
@@ -420,7 +404,11 @@ def _parse_json_response(text: str) -> Optional[dict]:
     return None
 
 
-def _generate_with_backend(backend, messages: list[dict], max_tokens: int = 512) -> str:
+def _generate_with_backend(
+    backend,
+    messages: list[dict],
+    max_tokens: int = 512,
+) -> str:
     """Run one chat completion on an already-loaded backend. Returns raw text."""
     logger.info("Advisor request: enable_thinking=False (per-request override)")
     cumulative = ""
@@ -480,9 +468,7 @@ def fetch_hf_dataset_card(
                 if val is not None:
                     metadata[key] = val
 
-        logger.info(
-            f"Fetched dataset card: {len(readme)} chars, {len(metadata)} metadata fields"
-        )
+        logger.info(f"Fetched dataset card: {len(readme)} chars, {len(metadata)} metadata fields")
         return readme, metadata
 
     except Exception as e:
@@ -509,9 +495,7 @@ def _run_multi_pass_advisor(
         return None
 
     repo = os.environ.get("UNSLOTH_HELPER_MODEL_REPO", DEFAULT_HELPER_MODEL_REPO)
-    variant = os.environ.get(
-        "UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT
-    )
+    variant = os.environ.get("UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT)
 
     backend = None
     try:
@@ -541,9 +525,7 @@ def _run_multi_pass_advisor(
             samples_text += f"Row {i}:\n" + "\n".join(parts) + "\n"
 
         metadata_str = (
-            json.dumps(dataset_metadata, indent = 2, default = str)[:500]
-            if dataset_metadata
-            else "N/A"
+            json.dumps(dataset_metadata, indent = 2, default = str)[:500] if dataset_metadata else "N/A"
         )
         card_excerpt = (dataset_card or "")[:1200] or "N/A"
 
@@ -745,9 +727,7 @@ def _run_multi_pass_advisor(
         # Validate: must have at least one user AND one assistant
         roles_present = set(column_roles.values())
         if "user" not in roles_present or "assistant" not in roles_present:
-            logger.warning(
-                f"Pass 2 sanity fail: missing user or assistant role: {column_roles}"
-            )
+            logger.warning(f"Pass 2 sanity fail: missing user or assistant role: {column_roles}")
             return None  # triggers fallback to simple classification
 
         # ── Pass 3: System prompt (non-conversational datasets only) ──
diff --git a/studio/backend/utils/datasets/raw_text.py b/studio/backend/utils/datasets/raw_text.py
index 353145fd5a..86b1963fc1 100644
--- a/studio/backend/utils/datasets/raw_text.py
+++ b/studio/backend/utils/datasets/raw_text.py
@@ -40,10 +40,7 @@ def _split_scope(split_name: str | None) -> str:
 
 
 def _drop_invalid_text_rows(
-    dataset: Dataset,
-    *,
-    mode_title: str,
-    split_scope: str,
+    dataset: Dataset, *, mode_title: str, split_scope: str
 ) -> tuple[Dataset, list[RawTextNotice]]:
     filtered_dataset = dataset.filter(lambda ex: isinstance(ex["text"], str))
     dropped_rows = len(dataset) - len(filtered_dataset)
@@ -105,8 +102,7 @@ def prepare_raw_text_dataset(
         notices.append(
             RawTextNotice(
                 message = (
-                    f"{mode_title}: renaming column '{renamed_col}' -> 'text' "
-                    f"for {split_scope}"
+                    f"{mode_title}: renaming column '{renamed_col}' -> 'text' " f"for {split_scope}"
                 ),
                 level = "info",
             )
diff --git a/studio/backend/utils/datasets/vlm_processing.py b/studio/backend/utils/datasets/vlm_processing.py
index 7b63152ede..a0f1fd9f99 100644
--- a/studio/backend/utils/datasets/vlm_processing.py
+++ b/studio/backend/utils/datasets/vlm_processing.py
@@ -66,9 +66,7 @@ def generate_smart_vlm_instruction(
         # OCR / Transcription
         "ocr": {
             "keywords": ["ocr", "transcribe", "transcript"],
-            "content_hints": [
-                r"[A-Za-z\u0600-\u06FF]{10,}"
-            ],  # Long text passages (Latin/Arabic)
+            "content_hints": [r"[A-Za-z\u0600-\u06FF]{10,}"],  # Long text passages (Latin/Arabic)
             "instruction": "Transcribe all the text shown in this image.",
             "confidence": 0.9,
         },
@@ -220,7 +218,6 @@ def generate_smart_vlm_instruction(
             }
     except Exception as e:
         import logging
-
         logging.getLogger(__name__).debug(f"LLM-assisted instruction skipped: {e}")
 
     # ===== LEVEL 5: Generic Fallback =====
diff --git a/studio/backend/utils/downsample.py b/studio/backend/utils/downsample.py
index bccf6a23b7..2d340ca248 100644
--- a/studio/backend/utils/downsample.py
+++ b/studio/backend/utils/downsample.py
@@ -12,7 +12,5 @@ def downsample(values: list[float], target_count: int) -> list[float]:
         return []
     if target_count == 1:
         return [values[-1]]
-    indices = [
-        round(i * (len(values) - 1) / (target_count - 1)) for i in range(target_count)
-    ]
+    indices = [round(i * (len(values) - 1) / (target_count - 1)) for i in range(target_count)]
     return [values[i] for i in indices]
diff --git a/studio/backend/utils/hardware/amd.py b/studio/backend/utils/hardware/amd.py
index 48d5890399..04b9494a29 100644
--- a/studio/backend/utils/hardware/amd.py
+++ b/studio/backend/utils/hardware/amd.py
@@ -160,9 +160,7 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
     # amd-smi metric output structure varies by version; try common paths
     usage = gpu_data.get("usage", gpu_data.get("gpu_activity", {}))
     if isinstance(usage, dict):
-        gpu_util = _parse_numeric(
-            usage.get("gfx_activity", usage.get("gpu_use_percent"))
-        )
+        gpu_util = _parse_numeric(usage.get("gfx_activity", usage.get("gpu_use_percent")))
     else:
         gpu_util = _parse_numeric(usage)
 
@@ -188,9 +186,7 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
                 power_data.get("average_socket_power", power_data.get("socket_power")),
             )
         )
-        power_limit = _parse_numeric(
-            power_data.get("power_cap", power_data.get("max_power_limit"))
-        )
+        power_limit = _parse_numeric(power_data.get("power_cap", power_data.get("max_power_limit")))
     else:
         power_draw = None
         power_limit = None
@@ -205,14 +201,10 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
     )
     if isinstance(vram_data, dict):
         vram_used_mb = _parse_memory_mb(
-            vram_data.get(
-                "used_vram", vram_data.get("vram_used", vram_data.get("used"))
-            )
+            vram_data.get("used_vram", vram_data.get("vram_used", vram_data.get("used")))
         )
         vram_total_mb = _parse_memory_mb(
-            vram_data.get(
-                "total_vram", vram_data.get("vram_total", vram_data.get("total"))
-            )
+            vram_data.get("total_vram", vram_data.get("vram_total", vram_data.get("total")))
         )
     else:
         vram_used_mb = None
@@ -220,9 +212,7 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
 
     # Build the standardized dict (same shape as nvidia._build_gpu_metrics)
     vram_used_gb = round(vram_used_mb / 1024, 2) if vram_used_mb is not None else None
-    vram_total_gb = (
-        round(vram_total_mb / 1024, 2) if vram_total_mb is not None else None
-    )
+    vram_total_gb = round(vram_total_mb / 1024, 2) if vram_total_mb is not None else None
     vram_util = (
         round((vram_used_mb / vram_total_mb) * 100, 1)
         if vram_used_mb is not None and vram_total_mb is not None and vram_total_mb > 0
@@ -340,8 +330,7 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 
 
 def get_visible_gpu_utilization(
-    parent_visible_ids: Optional[list[int]],
-    parent_cuda_visible_devices: Optional[str] = None,
+    parent_visible_ids: Optional[list[int]], parent_cuda_visible_devices: Optional[str] = None
 ) -> dict[str, Any]:
     """Return utilization metrics for visible AMD GPUs."""
     if parent_visible_ids is None:
@@ -391,14 +380,11 @@ def get_visible_gpu_utilization(
         # "unit": "none"}``, so route raw_id through ``_parse_numeric``
         # which already handles bare ints, floats, strings, and that
         # dict shape uniformly.
-        raw_id = gpu_data.get(
-            "gpu", gpu_data.get("gpu_id", gpu_data.get("id", fallback_idx))
-        )
+        raw_id = gpu_data.get("gpu", gpu_data.get("gpu_id", gpu_data.get("id", fallback_idx)))
         parsed_id = _parse_numeric(raw_id)
         if parsed_id is None:
             logger.warning(
-                "amd-smi GPU id %r could not be parsed; falling back to "
-                "enumeration index %d",
+                "amd-smi GPU id %r could not be parsed; falling back to enumeration index %d",
                 raw_id,
                 fallback_idx,
             )
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index 180fde8f13..3f2823302a 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -51,9 +51,7 @@ class DeviceType(str, Enum):
 
 DEVICE: Optional[DeviceType] = None
 CHAT_ONLY: bool = True  # No CUDA GPU -> GGUF chat only (Mac, CPU-only, etc.)
-IS_ROCM: bool = (
-    False  # True when running on AMD ROCm (HIP) -- routes GPU monitoring to amd.py
-)
+IS_ROCM: bool = False  # True when running on AMD ROCm (HIP) -- routes GPU monitoring to amd.py
 
 
 def _backend_label(device: DeviceType) -> str:
@@ -85,7 +83,6 @@ def _has_torch() -> bool:
     """Check if PyTorch is importable."""
     try:
         import torch
-
         return True
     except ImportError:
         return False
@@ -95,7 +92,6 @@ def _has_mlx() -> bool:
     """Check if MLX is importable."""
     try:
         import mlx.core
-
         return True
     except ImportError:
         return False
@@ -120,7 +116,6 @@ def detect_hardware() -> DeviceType:
     # --- CUDA / ROCm: try PyTorch ---
     if _has_torch():
         import torch
-
         if torch.cuda.is_available():
             DEVICE = DeviceType.CUDA
             CHAT_ONLY = False
@@ -142,7 +137,6 @@ def detect_hardware() -> DeviceType:
     # --- XPU: Intel GPU ---
     if _has_torch():
         import torch
-
         if hasattr(torch, "xpu") and torch.xpu.is_available():
             DEVICE = DeviceType.XPU
             CHAT_ONLY = False
@@ -198,7 +192,6 @@ def clear_gpu_cache():
         torch.cuda.ipc_collect()
     elif device == DeviceType.XPU:
         import torch
-
         torch.xpu.synchronize()
         torch.xpu.empty_cache()
     elif device == DeviceType.MLX:
@@ -379,7 +372,6 @@ def get_package_versions() -> Dict[str, Optional[str]]:
     # GPU runtime version bundled with torch
     try:
         import torch
-
         versions["cuda"] = getattr(torch.version, "cuda", None)
         versions["rocm"] = getattr(torch.version, "hip", None)
     except Exception:
@@ -646,9 +638,7 @@ def get_gpu_utilization() -> Dict[str, Any]:
             result["backend"] = _backend_label(device)
             if IS_ROCM:
                 # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
-                _reconcile_primary_rocm_unified_memory(
-                    result, _get_parent_visible_gpu_spec()
-                )
+                _reconcile_primary_rocm_unified_memory(result, _get_parent_visible_gpu_spec())
             return result
         # SMI tool unavailable or returned no usable data. On Windows, query
         # the Performance Counter API (same source as Task Manager) for
@@ -709,9 +699,7 @@ def get_gpu_utilization() -> Dict[str, Any]:
                 "temperature_c": None,
                 "vram_used_gb": _used,
                 "vram_total_gb": _total,
-                "vram_utilization_pct": round((_used / _total) * 100, 1)
-                if _total > 0
-                else None,
+                "vram_utilization_pct": round((_used / _total) * 100, 1) if _total > 0 else None,
                 "power_draw_w": None,
                 "power_limit_w": None,
                 "power_utilization_pct": None,
@@ -722,7 +710,6 @@ def get_gpu_utilization() -> Dict[str, Any]:
     if device == DeviceType.MLX:
         try:
             import psutil
-
             agx = _read_apple_gpu_stats()
             total_bytes = psutil.virtual_memory().total
         except Exception as e:
@@ -795,9 +782,7 @@ def _apply_unified_memory_correction(
         device_metrics["vram_total_gb"] = torch_total_gb
         device_metrics["vram_used_gb"] = torch_used_gb
         device_metrics["vram_utilization_pct"] = (
-            round((torch_used_gb / torch_total_gb) * 100, 1)
-            if torch_total_gb > 0
-            else None
+            round((torch_used_gb / torch_total_gb) * 100, 1) if torch_total_gb > 0 else None
         )
         logger.debug(
             "ROCm unified memory: replaced amd-smi VRAM (%.2f GB) with "
@@ -808,9 +793,7 @@ def _apply_unified_memory_correction(
         )
 
 
-def _reconcile_rocm_unified_memory(
-    utilization: Dict[str, Any], device_indices: list[int]
-) -> None:
+def _reconcile_rocm_unified_memory(utilization: Dict[str, Any], device_indices: list[int]) -> None:
     """Fix amd-smi VRAM for ROCm unified-memory GPUs (e.g. Strix Halo).
 
     amd-smi reports only the dedicated slice (~512 MB); torch sees the full
@@ -969,9 +952,7 @@ def _get_parent_visible_gpu_spec() -> Dict[str, Any]:
     # stale HIP_VISIBLE_DEVICES on an NVIDIA host can't override CUDA_VISIBLE_DEVICES.
     _is_rocm_spec = IS_ROCM or (
         "CUDA_VISIBLE_DEVICES" not in os.environ
-        and (
-            "HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ
-        )
+        and ("HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ)
     )
     if _is_rocm_spec:
         hip_vis = os.environ.get("HIP_VISIBLE_DEVICES")
@@ -1064,9 +1045,7 @@ def resolve_requested_gpu_ids(gpu_ids: Optional[list[int]]) -> list[int]:
         max_parent_id = max(parent_visible_ids)
         if physical_gpu_count > max_parent_id:
             # Count is plausibly physical (not just visible), so enforce it
-            out_of_range = [
-                gpu_id for gpu_id in requested_ids if gpu_id >= physical_gpu_count
-            ]
+            out_of_range = [gpu_id for gpu_id in requested_ids if gpu_id >= physical_gpu_count]
             if out_of_range:
                 raise ValueError(
                     f"Invalid gpu_ids {requested_ids}: IDs must be physical GPU IDs "
@@ -1074,9 +1053,7 @@ def resolve_requested_gpu_ids(gpu_ids: Optional[list[int]]) -> list[int]:
                     f"Rejected IDs: {out_of_range}. Parent-visible GPUs: {parent_visible_ids}"
                 )
 
-    disallowed_ids = [
-        gpu_id for gpu_id in requested_ids if gpu_id not in parent_visible_ids
-    ]
+    disallowed_ids = [gpu_id for gpu_id in requested_ids if gpu_id not in parent_visible_ids]
     if disallowed_ids:
         raise ValueError(
             f"Invalid gpu_ids {requested_ids}: requested GPUs {disallowed_ids} are "
@@ -1097,9 +1074,7 @@ def _resolve_model_identifier_for_gpu_estimate(
             return config.base_model
         return config.identifier if config else model_name
     except Exception as e:
-        logger.debug(
-            "Could not resolve base model for GPU estimate '%s': %s", model_name, e
-        )
+        logger.debug("Could not resolve base model for GPU estimate '%s': %s", model_name, e)
         return model_name
 
 
@@ -1136,7 +1111,6 @@ def _get_hf_safetensors_total_params(
 def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = None):
     try:
         from transformers import AutoConfig
-
         trust_remote_code = model_name.lower().startswith("unsloth/")
         return AutoConfig.from_pretrained(
             model_name,
@@ -1188,7 +1162,6 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
 
     try:
         import torch.distributed as _td
-
         for _attr, _stub in (
             ("is_initialized", lambda: False),
             ("is_available", lambda: False),
@@ -1251,17 +1224,15 @@ def _estimate_fp16_model_size_bytes_from_vllm_utils(config) -> Optional[int]:
                 synthetic_total_bytes,
                 synthetic_total_bytes,
             )
-            _, _, _, memory_left_for_kv_cache_gb = (
-                _vllm_utils.approximate_vllm_memory_usage(
-                    config,
-                    load_in_4bit = False,
-                    load_in_8bit = False,
-                    max_seq_length = 1,
-                    gpu_memory_utilization = 1.0,
-                    enable_lora = False,
-                    account_for_gradients = False,
-                    cuda_graph_overhead = False,
-                )
+            _, _, _, memory_left_for_kv_cache_gb = _vllm_utils.approximate_vllm_memory_usage(
+                config,
+                load_in_4bit = False,
+                load_in_8bit = False,
+                max_seq_length = 1,
+                gpu_memory_utilization = 1.0,
+                enable_lora = False,
+                account_for_gradients = False,
+                cuda_graph_overhead = False,
             )
         finally:
             _vllm_utils.get_mem_info = original_get_mem_info
@@ -1283,15 +1254,11 @@ def _estimate_fp16_model_size_bytes_from_vllm_utils(config) -> Optional[int]:
 def estimate_fp16_model_size_bytes(
     model_name: str, hf_token: Optional[str] = None
 ) -> tuple[Optional[int], str]:
-    estimate_model = _resolve_model_identifier_for_gpu_estimate(
-        model_name, hf_token = hf_token
-    )
+    estimate_model = _resolve_model_identifier_for_gpu_estimate(model_name, hf_token = hf_token)
 
     total_params = None
     if "/" in estimate_model and not Path(estimate_model).exists():
-        total_params = _get_hf_safetensors_total_params(
-            estimate_model, hf_token = hf_token
-        )
+        total_params = _get_hf_safetensors_total_params(estimate_model, hf_token = hf_token)
     if total_params:
         return int(total_params * 2), "safetensors"
 
@@ -1346,9 +1313,7 @@ def estimate_required_model_memory_gb(
         DEFAULT_TARGET_MODULES,
     )
 
-    model_size_bytes, source = estimate_fp16_model_size_bytes(
-        model_name, hf_token = hf_token
-    )
+    model_size_bytes, source = estimate_fp16_model_size_bytes(model_name, hf_token = hf_token)
     metadata: Dict[str, Any] = {
         "mode": "inference" if training_type is None else "training",
         "model_size_source": source,
@@ -1371,9 +1336,7 @@ def estimate_required_model_memory_gb(
         return required_gb, metadata
 
     training_method = (
-        "full"
-        if training_type == "Full Finetuning"
-        else ("qlora" if load_in_4bit else "lora")
+        "full" if training_type == "Full Finetuning" else ("qlora" if load_in_4bit else "lora")
     )
     vram_config = TrainingVramConfig(
         training_method = training_method,
@@ -1386,14 +1349,12 @@ def estimate_required_model_memory_gb(
         load_in_4bit = load_in_4bit,
     )
 
-    estimate_model = _resolve_model_identifier_for_gpu_estimate(
-        model_name, hf_token = hf_token
-    )
+    estimate_model = _resolve_model_identifier_for_gpu_estimate(model_name, hf_token = hf_token)
     config = _load_config_for_gpu_estimate(estimate_model, hf_token = hf_token)
     if config is not None:
         try:
-            vram_config.attention_implementation = (
-                _determine_attention_impl_for_gpu_estimate(config)
+            vram_config.attention_implementation = _determine_attention_impl_for_gpu_estimate(
+                config
             )
         except Exception as e:
             # Log at debug: on Windows ROCm the torch.distributed stub does
@@ -1587,9 +1548,7 @@ def auto_select_gpu_ids(
             return selected, metadata
 
     # Use only GPUs with verified VRAM data (from gpu_candidates, not raw devices)
-    fallback_all = (
-        [c["index"] for c in gpu_candidates] if gpu_candidates else parent_ids
-    )
+    fallback_all = [c["index"] for c in gpu_candidates] if gpu_candidates else parent_ids
     metadata["selection_mode"] = "fallback_all"
     if ranked:
         fallback_usable = ranked[0]["free_gb"] + sum(
@@ -1853,7 +1812,6 @@ def get_visible_gpu_count() -> int:
     # No visibility env var set -- try torch, fall back to physical count
     try:
         import torch
-
         if get_device() == DeviceType.XPU and hasattr(torch, "xpu"):
             _visible_gpu_count = torch.xpu.device_count()
         else:
@@ -1902,7 +1860,6 @@ def apply_gpu_ids(gpu_ids) -> None:
         # Broad except: a probe failure must never crash a training worker.
         try:
             import torch as _torch
-
             _is_rocm = (
                 getattr(_torch.version, "hip", None) is not None
                 or "rocm" in getattr(_torch, "__version__", "").lower()
@@ -1923,9 +1880,7 @@ def apply_gpu_ids(gpu_ids) -> None:
         logger.info("Applied gpu_ids: CUDA_VISIBLE_DEVICES='%s'", value)
 
 
-def get_device_map(
-    gpu_ids: Optional[list[int]] = None,
-) -> str:
+def get_device_map(gpu_ids: Optional[list[int]] = None) -> str:
     """Return the Hugging Face ``device_map`` string for model loading.
 
     Returns ``"balanced"`` (shard evenly across GPUs) when:
@@ -1949,10 +1904,7 @@ def get_device_map(
             # UUID/MIG masks cannot be split into numeric IDs, so if multiple
             # GPUs are visible we assume multi-GPU sharding is intended.
             parent_visible_spec = _get_parent_visible_gpu_spec()
-            if (
-                parent_visible_spec["numeric_ids"] is None
-                and get_visible_gpu_count() > 1
-            ):
+            if parent_visible_spec["numeric_ids"] is None and get_visible_gpu_count() > 1:
                 multi_gpu = True
 
         if multi_gpu:
@@ -1972,14 +1924,16 @@ def get_offloaded_device_map_entries(model) -> dict[str, str]:
     }
 
 
-def raise_if_offloaded(model, device_map: str, context: str = "Loading") -> None:
+def raise_if_offloaded(
+    model,
+    device_map: str,
+    context: str = "Loading",
+) -> None:
     """Raise ``ValueError`` if *model* has modules offloaded to CPU or disk."""
     offloaded = get_offloaded_device_map_entries(model)
     if not offloaded:
         return
-    example = ", ".join(
-        f"{name}={placement}" for name, placement in list(offloaded.items())[:5]
-    )
+    example = ", ".join(f"{name}={placement}" for name, placement in list(offloaded.items())[:5])
     raise ValueError(
         f"{context} does not support models loaded with CPU or disk offload. "
         f"device_map='{device_map}' produced offloaded modules: {example}"
diff --git a/studio/backend/utils/hardware/nvidia.py b/studio/backend/utils/hardware/nvidia.py
index 099c5fa3a5..6cead61f08 100644
--- a/studio/backend/utils/hardware/nvidia.py
+++ b/studio/backend/utils/hardware/nvidia.py
@@ -25,20 +25,12 @@ def _parse_smi_value(raw: str):
 
 
 def _build_gpu_metrics(
-    vram_used_mb,
-    vram_total_mb,
-    power_draw,
-    power_limit,
-    **extra,
+    vram_used_mb, vram_total_mb, power_draw, power_limit, **extra
 ) -> dict[str, Any]:
     return {
         **extra,
-        "vram_used_gb": round(vram_used_mb / 1024, 2)
-        if vram_used_mb is not None
-        else None,
-        "vram_total_gb": round(vram_total_mb / 1024, 2)
-        if vram_total_mb is not None
-        else None,
+        "vram_used_gb": round(vram_used_mb / 1024, 2) if vram_used_mb is not None else None,
+        "vram_total_gb": round(vram_total_mb / 1024, 2) if vram_total_mb is not None else None,
         "vram_utilization_pct": round((vram_used_mb / vram_total_mb) * 100, 1)
         if vram_used_mb is not None and vram_total_mb and vram_total_mb > 0
         else None,
@@ -50,9 +42,7 @@ def _build_gpu_metrics(
     }
 
 
-def _visible_ordinal_map(
-    parent_visible_ids: Optional[list[int]],
-) -> Optional[dict[int, int]]:
+def _visible_ordinal_map(parent_visible_ids: Optional[list[int]]) -> Optional[dict[int, int]]:
     if parent_visible_ids is None:
         return None
     return {gpu_id: ordinal for ordinal, gpu_id in enumerate(parent_visible_ids)}
@@ -118,8 +108,7 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 
 
 def get_visible_gpu_utilization(
-    parent_visible_ids: Optional[list[int]],
-    parent_cuda_visible_devices: Optional[str] = None,
+    parent_visible_ids: Optional[list[int]], parent_cuda_visible_devices: Optional[str] = None
 ) -> dict[str, Any]:
     # When parent_visible_ids is None (UUID/MIG mask), we cannot safely
     # map nvidia-smi rows to the process's visible devices. Return empty
@@ -188,9 +177,7 @@ def get_visible_gpu_utilization(
                 index = idx,
                 index_kind = "physical",
                 visible_ordinal = (
-                    visible_ordinals[idx]
-                    if visible_ordinals is not None
-                    else len(devices)
+                    visible_ordinals[idx] if visible_ordinals is not None else len(devices)
                 ),
                 gpu_utilization_pct = _parse_smi_value(parts[1]),
                 temperature_c = _parse_smi_value(parts[2]),
@@ -207,8 +194,7 @@ def get_visible_gpu_utilization(
 
 
 def get_backend_visible_gpu_info(
-    parent_visible_ids: Optional[list[int]],
-    backend_cuda_visible_devices: Optional[str],
+    parent_visible_ids: Optional[list[int]], backend_cuda_visible_devices: Optional[str]
 ) -> dict[str, Any]:
     # When parent_visible_ids is None (UUID/MIG mask), we cannot safely
     # map nvidia-smi rows to the process's visible devices.
@@ -274,9 +260,7 @@ def get_backend_visible_gpu_info(
                 "index": idx,
                 "index_kind": "physical",
                 "visible_ordinal": (
-                    visible_ordinals[idx]
-                    if visible_ordinals is not None
-                    else len(devices)
+                    visible_ordinals[idx] if visible_ordinals is not None else len(devices)
                 ),
                 "name": name,
                 "memory_total_gb": round(mem_total_mb / 1024, 2),
diff --git a/studio/backend/utils/hardware/vram_estimation.py b/studio/backend/utils/hardware/vram_estimation.py
index ba1b1dfe61..ddc39733e3 100644
--- a/studio/backend/utils/hardware/vram_estimation.py
+++ b/studio/backend/utils/hardware/vram_estimation.py
@@ -16,9 +16,7 @@ from dataclasses import dataclass, field
 from typing import Dict, Optional
 
 QUANT_4BIT_FACTOR = 16 / 5
-DOUBLE_QUANT_4BIT_FACTOR = (
-    3.6  # bnb_4bit_use_double_quant; see VRAM_ESTIMATION.md section 1
-)
+DOUBLE_QUANT_4BIT_FACTOR = 3.6  # bnb_4bit_use_double_quant; see VRAM_ESTIMATION.md section 1
 CUDA_OVERHEAD_BYTES = int(1.4 * 1024**3)  # calibrated on RTX 5070 Ti
 NON_FLASH_ATTENTION_FACTOR = (
     12.0  # eager attention score+workspace overhead; see VRAM_ESTIMATION.md section 5
@@ -148,12 +146,7 @@ class VramBreakdown:
         Weights/LoRA/optimizer/gradients shard across GPUs.
         Activations do NOT shard (the GPU running a layer holds them).
         """
-        shardable = (
-            self.model_weights
-            + self.lora_adapters
-            + self.optimizer_states
-            + self.gradients
-        )
+        shardable = self.model_weights + self.lora_adapters + self.optimizer_states + self.gradients
         per_gpu_fixed = self.activations + self.cuda_overhead
         return shardable // max(n_gpus, 1) + per_gpu_fixed
 
@@ -194,9 +187,7 @@ def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
     layer_types = getattr(text_config, "mlp_layer_types", None)
     if layer_types:
         return tuple(
-            i
-            for i, t in enumerate(layer_types[:total_layers])
-            if str(t).lower() == "dense"
+            i for i, t in enumerate(layer_types[:total_layers]) if str(t).lower() == "dense"
         )
 
     # why: Llama4TextConfig.__init__ auto-populates self.moe_layers from
@@ -234,9 +225,7 @@ def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
     if sparse_step is not None and sparse_step > 0:
         mlp_only_set = {int(i) for i in mlp_only}
         return tuple(
-            i
-            for i in range(total_layers)
-            if i in mlp_only_set or (i + 1) % sparse_step != 0
+            i for i in range(total_layers) if i in mlp_only_set or (i + 1) % sparse_step != 0
         )
     return ()
 
@@ -264,8 +253,7 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
         intermediate_size = hidden_size * 4
 
     if not all(
-        v is not None
-        for v in (hidden_size, num_layers, num_heads, intermediate_size, vocab_size)
+        v is not None for v in (hidden_size, num_layers, num_heads, intermediate_size, vocab_size)
     ):
         return None
     if num_heads <= 0:
@@ -330,9 +318,7 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
     # per MoE layer (modeling_llama4.py).
     intermediate_size_mlp_raw = _first_scalar(_moe_attr("intermediate_size_mlp"))
     dense_intermediate_size = (
-        int(intermediate_size_mlp_raw)
-        if intermediate_size_mlp_raw is not None
-        else None
+        int(intermediate_size_mlp_raw) if intermediate_size_mlp_raw is not None else None
     )
     if (
         intermediate_size_mlp_raw is not None
@@ -391,9 +377,7 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
             None,
         )
         or 0,
-        quantization_skip_modules = list(
-            quantization_config.get("llm_int8_skip_modules", []) or []
-        ),
+        quantization_skip_modules = list(quantization_config.get("llm_int8_skip_modules", []) or []),
         quant_4bit_factor = quant_4bit_factor,
         moe_has_dense_mlp = bool(getattr(text_config, "enable_moe_block", False)),
         dense_layer_indices = dense_layer_indices,
@@ -475,11 +459,7 @@ def _per_layer_input_norm_elements(arch: ModelArchConfig) -> int:
     return hd * n_layers + pli
 
 
-def _per_layer_input_lora_params(
-    arch: ModelArchConfig,
-    r: int,
-    target_modules,
-) -> int:
+def _per_layer_input_lora_params(arch: ModelArchConfig, r: int, target_modules) -> int:
     # why: Unsloth's get_peft_regex (unsloth_zoo/peft_utils.py) requires module
     # names to contain a component tag (mlp/attn/...); PLE module names lack
     # any tag, so all-linear training does NOT attach LoRA to them. Only count
@@ -487,11 +467,7 @@ def _per_layer_input_lora_params(
     pli = arch.hidden_size_per_layer_input
     if pli <= 0:
         return 0
-    targets = (
-        {target_modules}
-        if isinstance(target_modules, str)
-        else set(target_modules or [])
-    )
+    targets = {target_modules} if isinstance(target_modules, str) else set(target_modules or [])
     n_layers = arch.num_hidden_layers
     hd = arch.hidden_size
     total = 0
@@ -508,11 +484,7 @@ def _layer_attention_dims(arch: ModelArchConfig, layer_idx: int) -> tuple:
     layer_types = _layer_types(arch)
     layer_type = layer_types[layer_idx]
     is_sliding = layer_type == "sliding_attention"
-    head_dim = (
-        arch.global_head_dim
-        if not is_sliding and arch.global_head_dim
-        else _head_dim(arch)
-    )
+    head_dim = arch.global_head_dim if not is_sliding and arch.global_head_dim else _head_dim(arch)
     use_alt_attention = arch.attention_k_eq_v and not is_sliding
     num_kv_heads = (
         arch.num_global_key_value_heads
@@ -532,10 +504,7 @@ def _layer_mlp_size(arch: ModelArchConfig, layer_idx: int) -> int:
     return _dense_mlp_size(arch)
 
 
-def _text_linear_dims(
-    arch: ModelArchConfig,
-    layer_idx: int,
-) -> Dict[str, tuple[int, int]]:
+def _text_linear_dims(arch: ModelArchConfig, layer_idx: int) -> Dict[str, tuple[int, int]]:
     hd = arch.hidden_size
     if _uses_structured_layer_shapes(arch):
         q_size, kv_size, has_k, has_v = _layer_attention_dims(arch, layer_idx)
@@ -589,11 +558,7 @@ def _module_path_matches(skip_module: str, alias: str) -> bool:
     return ".".join(prefix_parts) in _SKIP_MODULE_TEXT_PREFIXES
 
 
-def _add_module_aliases(
-    aliases: Dict[str, str],
-    canonical: str,
-    suffix: str,
-) -> None:
+def _add_module_aliases(aliases: Dict[str, str], canonical: str, suffix: str) -> None:
     for prefix in (
         "",
         "model",
@@ -607,9 +572,7 @@ def _add_module_aliases(
         aliases[alias] = canonical
 
 
-def _build_text_module_elements(
-    arch: ModelArchConfig,
-) -> tuple[Dict[str, int], Dict[str, str]]:
+def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int], Dict[str, str]]:
     elements: Dict[str, int] = {}
     aliases: Dict[str, str] = {}
 
@@ -620,12 +583,8 @@ def _build_text_module_elements(
     for layer_idx in range(arch.num_hidden_layers):
         layer_modules: Dict[str, int] = {}
         dims = _text_linear_dims(arch, layer_idx)
-        attn_dims = {
-            name: dim for name, dim in dims.items() if name in ATTENTION_TARGET_MODULES
-        }
-        mlp_dims = {
-            name: dim for name, dim in dims.items() if name in MLP_TARGET_MODULES
-        }
+        attn_dims = {name: dim for name, dim in dims.items() if name in ATTENTION_TARGET_MODULES}
+        mlp_dims = {name: dim for name, dim in dims.items() if name in MLP_TARGET_MODULES}
 
         if is_mla:
             # why: _text_linear_dims uses (hd, hd) for q/o; MLA actually splits
@@ -677,10 +636,7 @@ def _build_text_module_elements(
                     )
         else:
             layer_modules.update(
-                {
-                    f"mlp.{name}": in_dim * out_dim
-                    for name, (in_dim, out_dim) in mlp_dims.items()
-                }
+                {f"mlp.{name}": in_dim * out_dim for name, (in_dim, out_dim) in mlp_dims.items()}
             )
 
         if pli > 0:
@@ -704,10 +660,7 @@ def _build_text_module_elements(
             for name, value in layer_modules.items()
             if (
                 name == "mlp"
-                or (
-                    name.startswith("mlp.")
-                    and not (is_sibling_experts and name == "mlp.experts")
-                )
+                or (name.startswith("mlp.") and not (is_sibling_experts and name == "mlp.experts"))
             )
         )
         experts_total = layer_modules.get("mlp.experts", 0) if is_sibling_experts else 0
@@ -764,10 +717,7 @@ def _compute_skipped_quantizable_elements(arch: ModelArchConfig) -> int:
     pruned = {
         canonical
         for canonical in matched
-        if not any(
-            canonical != parent and canonical.startswith(f"{parent}.")
-            for parent in matched
-        )
+        if not any(canonical != parent and canonical.startswith(f"{parent}.") for parent in matched)
     }
     return sum(module_elements[canonical] for canonical in pruned)
 
@@ -900,9 +850,7 @@ def _compute_layer_elements(arch: ModelArchConfig):
         mlp_total = _compute_dense_mlp_elements(arch) * n_layers
 
     layernorms = 2 * hd
-    per_layer_embed = (
-        arch.vocab_size_per_layer_input * arch.hidden_size_per_layer_input * n_layers
-    )
+    per_layer_embed = arch.vocab_size_per_layer_input * arch.hidden_size_per_layer_input * n_layers
     ple_text_linear = _per_layer_input_quantizable(arch)
     ple_norms = _per_layer_input_norm_elements(arch)
     embed_tokens = arch.vocab_size * hd + per_layer_embed + ple_norms
@@ -911,9 +859,7 @@ def _compute_layer_elements(arch: ModelArchConfig):
 
 
 def compute_model_weights_bytes(
-    arch: ModelArchConfig,
-    training_method: str,
-    load_in_4bit: bool,
+    arch: ModelArchConfig, training_method: str, load_in_4bit: bool
 ) -> int:
     total_quantizable, layernorms, embed_tokens, lm_head = _compute_layer_elements(arch)
     n_layers = arch.num_hidden_layers
@@ -926,9 +872,7 @@ def compute_model_weights_bytes(
         )
         quantized = total_quantizable - skipped_quantizable
         return int(
-            quantized * 2 / arch.quant_4bit_factor
-            + skipped_quantizable * 2
-            + non_quantizable * 2
+            quantized * 2 / arch.quant_4bit_factor + skipped_quantizable * 2 + non_quantizable * 2
         )
 
     return int((total_quantizable + non_quantizable) * 2)
@@ -940,11 +884,7 @@ def compute_total_params(arch: ModelArchConfig) -> int:
     return total_quantizable + layernorms * n_layers + embed_tokens + lm_head
 
 
-def _lora_attn_elements(
-    arch: ModelArchConfig,
-    r: int,
-    target_modules: list,
-) -> int:
+def _lora_attn_elements(arch: ModelArchConfig, r: int, target_modules: list) -> int:
     hd = arch.hidden_size
     if arch.q_lora_rank is not None:
         # MLA: q_proj->q_b, k_proj->kv_a, v_proj->kv_b, o_proj->o
@@ -974,11 +914,7 @@ def _lora_attn_elements(
 
 
 def _lora_mlp_elements(
-    hd: int,
-    mlp_size: int,
-    r: int,
-    target_modules: list,
-    expert_mult: int,
+    hd: int, mlp_size: int, r: int, target_modules: list, expert_mult: int
 ) -> int:
     module_ab = {
         "gate_proj": (hd * r, r * mlp_size),
@@ -992,11 +928,7 @@ def _lora_mlp_elements(
     return total
 
 
-def compute_lora_params(
-    arch: ModelArchConfig,
-    lora_rank: int,
-    target_modules: list,
-) -> int:
+def compute_lora_params(arch: ModelArchConfig, lora_rank: int, target_modules: list) -> int:
     all_linear = _targets_all_linear(target_modules)
     selected_modules = list(DEFAULT_TARGET_MODULES) if all_linear else target_modules
     hd = arch.hidden_size
@@ -1062,11 +994,7 @@ def compute_lora_params(
                 mlp_total = moe_mlp * n_moe + dense_only
         else:
             mlp_total = structured_dense_mlp
-        return (
-            attn_total
-            + mlp_total
-            + _per_layer_input_lora_params(arch, r, target_modules)
-        )
+        return attn_total + mlp_total + _per_layer_input_lora_params(arch, r, target_modules)
     elif n_experts > 1:
         attn_total = _lora_attn_elements(arch, r, selected_modules) * n_layers
         n_dense = arch.num_dense_layers
@@ -1118,9 +1046,7 @@ def compute_lora_params(
             * n_layers
         )
 
-    return (
-        attn_total + mlp_total + _per_layer_input_lora_params(arch, r, target_modules)
-    )
+    return attn_total + mlp_total + _per_layer_input_lora_params(arch, r, target_modules)
 
 
 def compute_lora_adapter_bytes(lora_params: int) -> int:
@@ -1144,10 +1070,7 @@ def _is_linear_attention(attention_implementation: Optional[str]) -> bool:
 
 
 def _compute_non_flash_attention_bytes(
-    arch: ModelArchConfig,
-    batch_size: int,
-    seq_len: int,
-    effective_layers: float,
+    arch: ModelArchConfig, batch_size: int, seq_len: int, effective_layers: float
 ) -> int:
     score_elements = batch_size * arch.num_attention_heads * seq_len * seq_len
     return int(score_elements * 2 * NON_FLASH_ATTENTION_FACTOR * effective_layers)
@@ -1190,10 +1113,7 @@ def _layer_qkv_mlp_sizes(arch: ModelArchConfig, layer_idx: int) -> tuple:
 
 
 def _per_layer_activation_bytes(
-    arch: ModelArchConfig,
-    layer_idx: int,
-    batch_size: int,
-    seq_len: int,
+    arch: ModelArchConfig, layer_idx: int, batch_size: int, seq_len: int
 ) -> int:
     qkv_size, mlp_size = _layer_qkv_mlp_sizes(arch, layer_idx)
     activation_qkv = seq_len * batch_size * qkv_size
@@ -1204,9 +1124,7 @@ def _per_layer_activation_bytes(
     # is set; see gemma4/modular_gemma4.py:1141-1145.
     pli = arch.hidden_size_per_layer_input
     activation_ple = seq_len * batch_size * (arch.hidden_size + pli) if pli > 0 else 0
-    return int(
-        (activation_qkv + residual_memory + activation_mlp + activation_ple) * 2 * 1.25
-    )
+    return int((activation_qkv + residual_memory + activation_mlp + activation_ple) * 2 * 1.25)
 
 
 def compute_activation_bytes(
@@ -1227,14 +1145,12 @@ def compute_activation_bytes(
     if gc_multiplier is None:
         effective_layers = n_layers
         linear_bytes = sum(
-            _per_layer_activation_bytes(arch, i, batch_size, seq_len)
-            for i in range(n_layers)
+            _per_layer_activation_bytes(arch, i, batch_size, seq_len) for i in range(n_layers)
         )
     else:
         effective_layers = gc_multiplier
         max_layer_bytes = max(
-            _per_layer_activation_bytes(arch, i, batch_size, seq_len)
-            for i in range(n_layers)
+            _per_layer_activation_bytes(arch, i, batch_size, seq_len) for i in range(n_layers)
         )
         linear_bytes = int(max_layer_bytes * effective_layers)
 
@@ -1257,10 +1173,7 @@ def compute_activation_bytes(
     )
 
 
-def estimate_training_vram(
-    arch: ModelArchConfig,
-    config: TrainingVramConfig,
-) -> VramBreakdown:
+def estimate_training_vram(arch: ModelArchConfig, config: TrainingVramConfig) -> VramBreakdown:
     method = config.training_method.lower()
     is_lora = method in ("qlora", "lora")
     load_in_4bit = config.load_in_4bit or method == "qlora"
diff --git a/studio/backend/utils/inference/inference_config.py b/studio/backend/utils/inference/inference_config.py
index 9efc281b0b..e07bc62cfd 100644
--- a/studio/backend/utils/inference/inference_config.py
+++ b/studio/backend/utils/inference/inference_config.py
@@ -34,10 +34,7 @@ def _load_family_defaults():
         return
 
     json_path = (
-        Path(__file__).parent.parent.parent
-        / "assets"
-        / "configs"
-        / "inference_defaults.json"
+        Path(__file__).parent.parent.parent / "assets" / "configs" / "inference_defaults.json"
     )
     try:
         with open(json_path, "r", encoding = "utf-8") as f:
diff --git a/studio/backend/utils/llama_cpp_freshness.py b/studio/backend/utils/llama_cpp_freshness.py
index 2c781f4a7b..f0e642a38e 100644
--- a/studio/backend/utils/llama_cpp_freshness.py
+++ b/studio/backend/utils/llama_cpp_freshness.py
@@ -38,7 +38,6 @@ def _cache_dir() -> Path:
     """Lazy import so tests can stub storage_roots."""
     try:
         from utils.paths.storage_roots import cache_root
-
         return cache_root() / "llama_cpp_freshness"
     except Exception:
         return Path.home() / ".unsloth" / "studio" / "cache" / "llama_cpp_freshness"
@@ -136,9 +135,7 @@ def _fetch_latest_release_tag(repo: str, timeout: float = 5.0) -> Optional[str]:
     return tag if isinstance(tag, str) and tag else None
 
 
-def latest_published_release(
-    repo: str, *, force_refresh: bool = False
-) -> Optional[str]:
+def latest_published_release(repo: str, *, force_refresh: bool = False) -> Optional[str]:
     """Latest release tag for `repo`. Memo + disk-cached (24h TTL).
     None when offline and never previously cached."""
     if not repo:
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index b6b2e11c2e..99770ce7a6 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -99,9 +99,7 @@ def scan_checkpoints(
                     name_part = parts[0]
                     idx = name_part.find("_")
                     if idx > 0:
-                        metadata["base_model"] = (
-                            name_part[:idx] + "/" + name_part[idx + 1 :]
-                        )
+                        metadata["base_model"] = name_part[:idx] + "/" + name_part[idx + 1 :]
                     else:
                         metadata["base_model"] = name_part
 
@@ -131,9 +129,7 @@ def scan_checkpoints(
                 )
 
             models.append((item.name, checkpoints, metadata))
-            logger.debug(
-                f"Found model: {item.name} with {len(checkpoints)} checkpoint(s)"
-            )
+            logger.debug(f"Found model: {item.name} with {len(checkpoints)} checkpoint(s)")
 
         # Sort by modification time (newest first)
         models.sort(key = lambda x: Path(x[1][0][1]).stat().st_mtime, reverse = True)
diff --git a/studio/backend/utils/models/gguf_metadata.py b/studio/backend/utils/models/gguf_metadata.py
index dc9c21226e..32618773b7 100644
--- a/studio/backend/utils/models/gguf_metadata.py
+++ b/studio/backend/utils/models/gguf_metadata.py
@@ -282,8 +282,7 @@ def is_mmproj_by_metadata(meta: Optional[Dict[str, str]]) -> Optional[bool]:
 
 
 def pairing_score(
-    weight_meta: Optional[Dict[str, str]],
-    mmproj_meta: Optional[Dict[str, str]],
+    weight_meta: Optional[Dict[str, str]], mmproj_meta: Optional[Dict[str, str]]
 ) -> int:
     """Pairing confidence: 100 = base_model URL match, 80 = basename + org,
     60 = basename, -1 = definitive mismatch, 0 = decide from filename."""
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index b488a19953..92960485a4 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -57,13 +57,9 @@ def _env_offline() -> bool:
 # ── Model size extraction ────────────────────────────────────
 import re as _re
 
-_MODEL_SIZE_RE = _re.compile(
-    r"(?:^|[-_/])(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE
-)
+_MODEL_SIZE_RE = _re.compile(r"(?:^|[-_/])(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
 # MoE active-parameter pattern: matches "A3B", "A3.5B", etc.
-_ACTIVE_SIZE_RE = _re.compile(
-    r"(?:^|[-_/])a(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE
-)
+_ACTIVE_SIZE_RE = _re.compile(r"(?:^|[-_/])a(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
 
 
 def extract_model_size_b(model_id: str) -> float | None:
@@ -571,9 +567,7 @@ except Exception as exc:
 """
 
 
-def _is_vision_model_subprocess(
-    model_name: str, hf_token: Optional[str] = None
-) -> Optional[bool]:
+def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
     """Run is_vision_model check in a subprocess with transformers 5.x.
 
     Same pattern as training/inference workers: spawn a clean subprocess
@@ -715,9 +709,7 @@ def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
     return False
 
 
-def _is_vision_model_uncached(
-    model_name: str, hf_token: Optional[str] = None
-) -> Optional[bool]:
+def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
     """Uncached vision model detection -- called by is_vision_model().
 
     Returns True/False for definitive results, or None when detection failed
@@ -775,9 +767,7 @@ def _is_vision_model_uncached(
         # Check 5: Known VLM model_type values that may not match above checks
         if hasattr(config, "model_type"):
             if config.model_type in _VLM_MODEL_TYPES:
-                logger.info(
-                    f"Model {model_name} detected as VLM: model_type={config.model_type}"
-                )
+                logger.info(f"Model {model_name} detected as VLM: model_type={config.model_type}")
                 return True
 
         return False
@@ -823,9 +813,7 @@ _AUDIO_TOKEN_PATTERNS = {
         and "<|text_start|>" in tokens
         and "<|text_end|>" in tokens
     ),
-    "snac": lambda tokens: (
-        sum(1 for t in tokens if t.startswith("<custom_token_")) > 10000
-    ),
+    "snac": lambda tokens: (sum(1 for t in tokens if t.startswith("<custom_token_")) > 10000),
 }
 
 
@@ -849,9 +837,7 @@ def detect_audio_type(model_name: str, hf_token: Optional[str] = None) -> Option
     return result
 
 
-def _detect_audio_from_tokenizer(
-    model_name: str, hf_token: Optional[str] = None
-) -> Optional[str]:
+def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None) -> Optional[str]:
     """Detect audio type from tokenizer special tokens (for LLM-based audio models).
 
     First checks local HF cache, then fetches tokenizer_config.json from HuggingFace.
@@ -913,9 +899,7 @@ def _detect_audio_from_tokenizer(
 
         return None
     except Exception as e:
-        logger.debug(
-            f"Could not detect audio type from tokenizer for {model_name}: {e}"
-        )
+        logger.debug(f"Could not detect audio type from tokenizer for {model_name}: {e}")
         return None
 
 
@@ -1346,9 +1330,7 @@ def _iter_hf_cache_snapshots(repo_id: str):
     yield from snap_dirs
 
 
-def _list_gguf_variants_from_hf_cache(
-    repo_id: str,
-) -> Optional[tuple[list[GgufVariantInfo], bool]]:
+def _list_gguf_variants_from_hf_cache(repo_id: str) -> Optional[tuple[list[GgufVariantInfo], bool]]:
     """Variants from the local HF cache snapshot, or None if not cached."""
     for snap in _iter_hf_cache_snapshots(repo_id):
         variants, has_vision = list_local_gguf_variants(str(snap))
@@ -1358,8 +1340,7 @@ def _list_gguf_variants_from_hf_cache(
 
 
 def list_gguf_variants(
-    repo_id: str,
-    hf_token: Optional[str] = None,
+    repo_id: str, hf_token: Optional[str] = None
 ) -> tuple[list[GgufVariantInfo], bool]:
     """
     List all GGUF quantization variants in a HuggingFace repo.
@@ -1462,9 +1443,7 @@ def _resolve_gguf_dir(p: Path) -> Optional[Path]:
     return None
 
 
-def list_local_gguf_variants(
-    directory: str,
-) -> tuple[list[GgufVariantInfo], bool]:
+def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], bool]:
     """List GGUF quantization variants in a local directory.
 
     Mirrors :func:`list_gguf_variants` but reads from the filesystem
@@ -1533,8 +1512,7 @@ def _find_local_gguf_by_variant(directory: str, variant: str) -> Optional[str]:
     matches = sorted(
         f
         for f in _iter_gguf_files(p, recursive = True)
-        if not _is_mmproj(f.name)
-        and _extract_quant_label(f.relative_to(p).as_posix()) == variant
+        if not _is_mmproj(f.name) and _extract_quant_label(f.relative_to(p).as_posix()) == variant
     )
     if matches:
         return str(matches[0].resolve())
@@ -1558,10 +1536,7 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
     return None
 
 
-def detect_gguf_model_remote(
-    repo_id: str,
-    hf_token: Optional[str] = None,
-) -> Optional[str]:
+def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Optional[str]:
     """
     Check if a HuggingFace repo contains GGUF files.
 
@@ -1617,9 +1592,7 @@ def detect_gguf_model_remote(
         )
         return cached
 
-    logger.warning(
-        f"Could not check GGUF files for '{repo_id}' after 3 attempts: {last_err}"
-    )
+    logger.warning(f"Could not check GGUF files for '{repo_id}' after 3 attempts: {last_err}")
     return None
 
 
@@ -1752,9 +1725,7 @@ def _looks_like_lora_adapter(model_dir: Path) -> bool:
     )
 
 
-def scan_trained_models(
-    outputs_dir: str = str(outputs_root()),
-) -> List[Tuple[str, str, str]]:
+def scan_trained_models(outputs_dir: str = str(outputs_root())) -> List[Tuple[str, str, str]]:
     """
     Scan outputs folder for trained Studio models.
 
@@ -1823,9 +1794,7 @@ def scan_exported_models(
 
             # Check for flat GGUF export (e.g. exports/gemma-3-4b-it-finetune-gguf/)
             # Filter out mmproj (vision projection) files — they aren't loadable as main models
-            gguf_files = [
-                f for f in _iter_gguf_files(run_dir) if not _is_mmproj(f.name)
-            ]
+            gguf_files = [f for f in _iter_gguf_files(run_dir) if not _is_mmproj(f.name)]
             if gguf_files:
                 base_model = None
                 export_meta = run_dir / "export_metadata.json"
@@ -1900,9 +1869,7 @@ def scan_exported_models(
                 # Fallback: read base model from the original training run's
                 # adapter_config.json in ./outputs/{run_name}/
                 if not base_model:
-                    outputs_adapter_cfg = (
-                        resolve_output_dir(run_dir.name) / "adapter_config.json"
-                    )
+                    outputs_adapter_cfg = resolve_output_dir(run_dir.name) / "adapter_config.json"
                     try:
                         if outputs_adapter_cfg.exists():
                             cfg = json.loads(outputs_adapter_cfg.read_text())
@@ -1935,9 +1902,7 @@ def get_base_model_from_checkpoint(checkpoint_path: str) -> Optional[str]:
                 config = json.load(f)
                 base_model = config.get("base_model_name_or_path")
                 if base_model:
-                    logger.info(
-                        "Detected base model from adapter_config.json: %s", base_model
-                    )
+                    logger.info("Detected base model from adapter_config.json: %s", base_model)
                     return base_model
 
         config_path = checkpoint_path_obj / "config.json"
@@ -2010,9 +1975,7 @@ def get_base_model_from_lora(lora_path: str) -> Optional[str]:
                 config = json.load(f)
                 base_model = config.get("base_model_name_or_path")
                 if base_model:
-                    logger.info(
-                        f"Detected base model from adapter_config.json: {base_model}"
-                    )
+                    logger.info(f"Detected base model from adapter_config.json: {base_model}")
                     return base_model
 
         # Fallback: try training_args.bin (requires torch)
@@ -2084,9 +2047,7 @@ def load_model_defaults(model_name: str) -> Dict[str, Any]:
                 if config_path.is_file():
                     with open(config_path, "r", encoding = "utf-8") as f:
                         config = yaml.safe_load(f) or {}
-                        logger.info(
-                            f"Loaded model defaults from {config_path} (via mapping)"
-                        )
+                        logger.info(f"Loaded model defaults from {config_path} (via mapping)")
                         return config
 
         # If model_name is a local path (e.g. /home/.../Spark-TTS-0.5B/LLM from
@@ -2156,14 +2117,10 @@ class ModelConfig:
     is_lora: bool  # Is this a lora adapter?
     is_gguf: bool = False  # Is this a GGUF model?
     is_audio: bool = False  # Is this a TTS audio model?
-    audio_type: Optional[str] = (
-        None  # Audio codec type: 'snac', 'csm', 'bicodec', 'dac'
-    )
+    audio_type: Optional[str] = None  # Audio codec type: 'snac', 'csm', 'bicodec', 'dac'
     has_audio_input: bool = False  # Accepts audio input (ASR/speech understanding)
     gguf_file: Optional[str] = None  # Full path to the .gguf file (local mode)
-    gguf_mmproj_file: Optional[str] = (
-        None  # Full path to the mmproj .gguf file (vision projection)
-    )
+    gguf_mmproj_file: Optional[str] = None  # Full path to the mmproj .gguf file (vision projection)
     gguf_hf_repo: Optional[str] = (
         None  # HF repo ID for -hf mode (e.g. "unsloth/gemma-3-4b-it-GGUF")
     )
@@ -2172,7 +2129,9 @@ class ModelConfig:
 
     @classmethod
     def from_lora_path(
-        cls, lora_path: str, hf_token: Optional[str] = None
+        cls,
+        lora_path: str,
+        hf_token: Optional[str] = None,
     ) -> Optional["ModelConfig"]:
         """
         Create ModelConfig from a local LoRA adapter path.
@@ -2321,9 +2280,7 @@ class ModelConfig:
                     gguf_is_vision = True
                     logger.info(f"Detected mmproj for vision: {mmproj_file}")
                 elif base_is_vision:
-                    logger.warning(
-                        f"Base model is vision but no mmproj file found in {gguf_dir}"
-                    )
+                    logger.warning(f"Base model is vision but no mmproj file found in {gguf_dir}")
 
                 return cls(
                     identifier = identifier,
@@ -2385,15 +2342,11 @@ class ModelConfig:
         # Auto-detect LoRA for local paths (check adapter_config.json on disk)
         if not is_lora and is_local:
             detected_base = (
-                get_base_model_from_lora(path)
-                if _looks_like_lora_adapter(Path(path))
-                else None
+                get_base_model_from_lora(path) if _looks_like_lora_adapter(Path(path)) else None
             )
             if detected_base:
                 is_lora = True
-                logger.info(
-                    f"Auto-detected local LoRA adapter at '{path}' (base: {detected_base})"
-                )
+                logger.info(f"Auto-detected local LoRA adapter at '{path}' (base: {detected_base})")
 
         # Auto-detect LoRA for remote HF models. When offline, huggingface_hub
         # raises OfflineModeIsEnabled in ~0ms; we fall through to the cache.
@@ -2407,18 +2360,14 @@ class ModelConfig:
                     is_lora = True
                     logger.info(f"Auto-detected remote LoRA adapter: '{identifier}'")
             except Exception as e:
-                logger.debug(
-                    f"Could not check remote LoRA status for '{identifier}': {e}"
-                )
+                logger.debug(f"Could not check remote LoRA status for '{identifier}': {e}")
 
             # API may have failed; adapter_config.json may still be cached.
             if not is_lora:
                 for snap in _iter_hf_cache_snapshots(identifier):
                     if (snap / "adapter_config.json").is_file():
                         is_lora = True
-                        logger.info(
-                            f"Auto-detected cached LoRA adapter: '{identifier}'"
-                        )
+                        logger.info(f"Auto-detected cached LoRA adapter: '{identifier}'")
                         break
 
         # Handle LoRA adapters
@@ -2432,9 +2381,7 @@ class ModelConfig:
                 try:
                     from huggingface_hub import hf_hub_download
 
-                    config_path = hf_hub_download(
-                        identifier, "adapter_config.json", token = hf_token
-                    )
+                    config_path = hf_hub_download(identifier, "adapter_config.json", token = hf_token)
                     with open(config_path, "r") as f:
                         adapter_config = json.load(f)
                     base_model = adapter_config.get("base_model_name_or_path")
@@ -2498,9 +2445,7 @@ class ModelConfig:
 
         #  Use the correct 'local_models' parameter to resolve display names
         if " (Active)" in selected or " (Ready)" in selected:
-            clean_display_name = selected.replace(" (Active)", "").replace(
-                " (Ready)", ""
-            )
+            clean_display_name = selected.replace(" (Active)", "").replace(" (Ready)", "")
             if local_models:
                 for local_display, local_path in local_models:
                     if local_display == clean_display_name:
diff --git a/studio/backend/utils/native_path_leases.py b/studio/backend/utils/native_path_leases.py
index a69dfab532..7d8514abc8 100644
--- a/studio/backend/utils/native_path_leases.py
+++ b/studio/backend/utils/native_path_leases.py
@@ -68,9 +68,7 @@ def native_path_leases_supported() -> bool:
     return True
 
 
-def child_env_without_native_path_secret(
-    env: Mapping[str, str] | None = None,
-) -> dict[str, str]:
+def child_env_without_native_path_secret(env: Mapping[str, str] | None = None) -> dict[str, str]:
     """Return a child-process env with the native path lease secret removed."""
 
     if env is None:
@@ -82,11 +80,7 @@ def child_env_without_native_path_secret(
     return cleaned
 
 
-def run_without_native_path_secret(
-    target: Callable[..., Any],
-    *args: Any,
-    **kwargs: Any,
-) -> Any:
+def run_without_native_path_secret(target: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
     """Run a multiprocessing child target without the native path lease secret."""
 
     global _CACHED_LEASE_SECRET, _SCRUB_SAVED_SECRET
@@ -153,9 +147,7 @@ def verify_native_path_lease(
         raise NativePathLeaseError("Native path is no longer accessible.") from exc
     _reject_network_or_device_path(resolved)
     if not _same_native_path(resolved, path):
-        raise NativePathLeaseError(
-            "Native path grant no longer resolves to the selected path."
-        )
+        raise NativePathLeaseError("Native path grant no longer resolves to the selected path.")
 
     grant = NativePathGrant(
         operation = str(payload["operation"]),
@@ -219,9 +211,7 @@ def _decode_secret() -> bytes:
             if encoded is None and _SCRUB_SAVED_SECRET is not None:
                 encoded = _SCRUB_SAVED_SECRET
         if not encoded:
-            raise NativePathLeaseError(
-                "Native path grants require the managed desktop backend."
-            )
+            raise NativePathLeaseError("Native path grants require the managed desktop backend.")
         try:
             secret = _b64decode(encoded)
         except Exception as exc:
@@ -272,9 +262,7 @@ def _validate_payload(
     )
     missing = [key for key in required if key not in payload]
     if missing:
-        raise NativePathLeaseError(
-            "Native path grant payload is missing required fields."
-        )
+        raise NativePathLeaseError("Native path grant payload is missing required fields.")
     if _required_int(payload, "version") != 1:
         raise NativePathLeaseError("Native path grant version is unsupported.")
     if payload["operation"] != operation:
@@ -353,19 +341,13 @@ def _reject_network_or_device_path(path: Path) -> None:
             rest = normalized[4:]
             is_local_drive = len(rest) >= 3 and rest[0].isalpha() and rest[1:3] == ":\\"
             if not is_local_drive:
-                raise NativePathLeaseError(
-                    "Network paths are not supported for native grants."
-                )
+                raise NativePathLeaseError("Network paths are not supported for native grants.")
         elif normalized.startswith("\\\\"):
-            raise NativePathLeaseError(
-                "Network paths are not supported for native grants."
-            )
+            raise NativePathLeaseError("Network paths are not supported for native grants.")
     if os.name != "nt":
         for root in ("/dev", "/proc", "/sys"):
             if path.is_relative_to(root):
-                raise NativePathLeaseError(
-                    "Device and virtual filesystem paths are not supported."
-                )
+                raise NativePathLeaseError("Device and virtual filesystem paths are not supported.")
     if "\x00" in text:
         raise NativePathLeaseError("Native path contains invalid characters.")
 
@@ -397,9 +379,7 @@ def _optional_int(value: Any) -> int | None:
 def _required_int(payload: dict[str, Any], key: str) -> int:
     raw = payload.get(key)
     if raw is None:
-        raise NativePathLeaseError(
-            "Native path grant payload is missing required fields."
-        )
+        raise NativePathLeaseError("Native path grant payload is missing required fields.")
     try:
         return int(raw)
     except (TypeError, ValueError) as exc:
diff --git a/studio/backend/utils/paths/path_utils.py b/studio/backend/utils/paths/path_utils.py
index 9ef9a2dd92..22c6c46ee1 100644
--- a/studio/backend/utils/paths/path_utils.py
+++ b/studio/backend/utils/paths/path_utils.py
@@ -134,7 +134,6 @@ def _hf_hub_cache_dir() -> Path:
     """Return HF cache root honoring HF_HUB_CACHE when available."""
     try:
         from huggingface_hub.constants import HF_HUB_CACHE
-
         return Path(HF_HUB_CACHE)
     except Exception as exc:
         logger.debug(
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index 6319452ed2..b254c20f97 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -263,9 +263,7 @@ def _setup_cache_env() -> None:
     Works on Linux, macOS, and Windows.
     """
     root = cache_root()
-    xdg_cache = Path(
-        os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")
-    ).expanduser()
+    xdg_cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")).expanduser()
     hf_default = xdg_cache / "huggingface"
     defaults: dict[str, str] = {
         "HF_HOME": str(hf_default),
@@ -298,9 +296,7 @@ def ensure_studio_directories() -> None:
     _setup_cache_env()
 
 
-def _clean_relative_path(
-    path_value: str, *, strip_prefixes: tuple[str, ...] = ()
-) -> Path:
+def _clean_relative_path(path_value: str, *, strip_prefixes: tuple[str, ...] = ()) -> Path:
     path = Path(path_value).expanduser()
     parts = [part for part in path.parts if part not in ("", ".")]
     while parts and parts[0] in strip_prefixes:
@@ -319,8 +315,7 @@ def _assert_contained(resolved: Path, root: Path) -> None:
         resolved_real.relative_to(root_real)
     except ValueError as exc:
         raise ValueError(
-            f"path escapes root: {resolved!s} -> {resolved_real!s} "
-            f"is not under {root_real!s}"
+            f"path escapes root: {resolved!s} -> {resolved_real!s} " f"is not under {root_real!s}"
         ) from exc
 
 
@@ -394,9 +389,7 @@ def resolve_dataset_path(path_value: str) -> Path:
                 return path
             except ValueError:
                 continue
-        raise ValueError(
-            f"dataset path must be relative or under a dataset root: {raw!r}"
-        )
+        raise ValueError(f"dataset path must be relative or under a dataset root: {raw!r}")
 
     parts = [part for part in Path(path_value).parts if part not in ("", ".")]
     if parts[:2] == ["assets", "datasets"]:
diff --git a/studio/backend/utils/studio_version.py b/studio/backend/utils/studio_version.py
index 70059f8a3c..e59439a2cc 100644
--- a/studio/backend/utils/studio_version.py
+++ b/studio/backend/utils/studio_version.py
@@ -39,9 +39,7 @@ def _path_is_in_site_packages(path: Path) -> bool:
 
 
 def _is_source_checkout(repo_root: Path) -> bool:
-    return (repo_root / ".git").exists() and not _path_is_in_site_packages(
-        Path(__file__).resolve()
-    )
+    return (repo_root / ".git").exists() and not _path_is_in_site_packages(Path(__file__).resolve())
 
 
 def _exact_git_studio_tag(repo_root: Path) -> str | None:
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index c23857e0a4..16f964d628 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -201,7 +201,6 @@ def _resolve_base_model(model_name: str) -> str:
     if local_path.is_dir():
         try:
             from utils.models import get_base_model_from_lora
-
             base = get_base_model_from_lora(model_name)
             if base:
                 logger.info(
@@ -275,9 +274,7 @@ def _check_tokenizer_config_needs_v5(model_name: str) -> bool:
         _tokenizer_class_cache[model_name] = result
         return result
     except Exception as exc:
-        logger.debug(
-            "Could not fetch tokenizer_config.json for '%s': %s", model_name, exc
-        )
+        logger.debug("Could not fetch tokenizer_config.json for '%s': %s", model_name, exc)
         _tokenizer_class_cache[model_name] = False
         return False
 
@@ -467,8 +464,7 @@ def _venv_dir_is_valid(venv_dir: str, packages: tuple[str, ...]) -> bool:
         pkg_name_norm = pkg_name.replace("-", "_")
         # Check directory exists
         if not any(
-            (Path(venv_dir) / d).is_dir()
-            for d in (pkg_name_norm, pkg_name_norm.replace("_", "-"))
+            (Path(venv_dir) / d).is_dir() for d in (pkg_name_norm, pkg_name_norm.replace("_", "-"))
         ):
             return False
         # For unpinned packages, existence is enough
@@ -563,9 +559,7 @@ def _ensure_venv_dir(venv_dir: str, packages: tuple[str, ...], label: str) -> bo
     if _venv_dir_is_valid(venv_dir, packages):
         return True
 
-    logger.warning(
-        "%s not found or incomplete at %s -- installing at runtime", label, venv_dir
-    )
+    logger.warning("%s not found or incomplete at %s -- installing at runtime", label, venv_dir)
     shutil.rmtree(venv_dir, ignore_errors = True)
     os.makedirs(venv_dir, exist_ok = True)
     for pkg in packages:
@@ -577,16 +571,12 @@ def _ensure_venv_dir(venv_dir: str, packages: tuple[str, ...], label: str) -> bo
 
 def _ensure_venv_t5_530_exists() -> bool:
     """Ensure .venv_t5_530/ exists with transformers 5.3.0."""
-    return _ensure_venv_dir(
-        _VENV_T5_530_DIR, _VENV_T5_530_PACKAGES, "transformers 5.3.0"
-    )
+    return _ensure_venv_dir(_VENV_T5_530_DIR, _VENV_T5_530_PACKAGES, "transformers 5.3.0")
 
 
 def _ensure_venv_t5_550_exists() -> bool:
     """Ensure .venv_t5_550/ exists with transformers 5.5.0."""
-    return _ensure_venv_dir(
-        _VENV_T5_550_DIR, _VENV_T5_550_PACKAGES, "transformers 5.5.0"
-    )
+    return _ensure_venv_dir(_VENV_T5_550_DIR, _VENV_T5_550_PACKAGES, "transformers 5.5.0")
 
 
 def _ensure_venv_t5_exists() -> bool:
@@ -693,15 +683,12 @@ def ensure_transformers_version(model_name: str) -> None:
         _deactivate_5x()
         if not ensure_fn():
             raise RuntimeError(
-                f"Cannot activate transformers {target_version}: "
-                f"venv missing at {venv_dir}"
+                f"Cannot activate transformers {target_version}: " f"venv missing at {venv_dir}"
             )
         logger.info("Activating transformers %s…", target_version)
         _activate_venv(venv_dir, f"transformers {target_version}")
     else:
-        logger.info(
-            "Reverting to default transformers %s…", TRANSFORMERS_DEFAULT_VERSION
-        )
+        logger.info("Reverting to default transformers %s…", TRANSFORMERS_DEFAULT_VERSION)
         _deactivate_5x()
 
     final = _get_in_memory_version()
diff --git a/studio/backend/utils/update_status.py b/studio/backend/utils/update_status.py
index 9142203a69..9b71ff31a0 100644
--- a/studio/backend/utils/update_status.py
+++ b/studio/backend/utils/update_status.py
@@ -73,11 +73,7 @@ def detect_install_source() -> str:
     try:
         dist = distribution(PACKAGE_NAME)
     except PackageNotFoundError:
-        return (
-            "local_repo"
-            if _path_has_git_parent(_repo_root_from_this_file())
-            else "unknown"
-        )
+        return "local_repo" if _path_has_git_parent(_repo_root_from_this_file()) else "unknown"
 
     try:
         direct_url = dist.read_text("direct_url.json")
@@ -146,9 +142,7 @@ def get_studio_update_status(current_version: str) -> dict[str, Any]:
             current_version = current_version,
             latest_version = None,
             install_source = install_source,
-            reason = "invalid_current_version"
-            if current_version != "dev"
-            else "dev_build",
+            reason = "invalid_current_version" if current_version != "dev" else "dev_build",
         )
     latest_result = get_latest_pypi_version()
     if latest_result.latest_version is None:
@@ -216,9 +210,7 @@ def get_latest_pypi_version() -> LatestVersionResult:
             error = "Could not check PyPI update metadata.",
         )
 
-    ttl = (
-        PYPI_SUCCESS_TTL_SECONDS if result.latest_version else PYPI_FAILURE_TTL_SECONDS
-    )
+    ttl = PYPI_SUCCESS_TTL_SECONDS if result.latest_version else PYPI_FAILURE_TTL_SECONDS
     with _cache_condition:
         _latest_version_cache = _LatestVersionCacheEntry(
             result = result,
@@ -262,9 +254,7 @@ def _fetch_latest_pypi_version() -> LatestVersionResult:
             error = "Could not reach PyPI for update metadata.",
         )
 
-    latest = (
-        payload.get("info", {}).get("version") if isinstance(payload, dict) else None
-    )
+    latest = payload.get("info", {}).get("version") if isinstance(payload, dict) else None
     if not isinstance(latest, str) or not latest.strip():
         return LatestVersionResult(
             latest_version = None,
@@ -366,9 +356,4 @@ def _parse_current_version(current_version: str) -> Version | None:
 
 
 def _utc_now_iso() -> str:
-    return (
-        datetime.now(timezone.utc)
-        .replace(microsecond = 0)
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
+    return datetime.now(timezone.utc).replace(microsecond = 0).isoformat().replace("+00:00", "Z")
diff --git a/studio/backend/utils/upload_limits.py b/studio/backend/utils/upload_limits.py
index b8a6a2474b..c21ea69af7 100644
--- a/studio/backend/utils/upload_limits.py
+++ b/studio/backend/utils/upload_limits.py
@@ -52,7 +52,6 @@ def validate_upload_limit_mb(value: Any) -> int:
 def get_upload_limit_mb() -> int:
     try:
         from storage.studio_db import get_app_setting
-
         stored = get_app_setting(UPLOAD_LIMIT_SETTING_KEY, None)
     except Exception:
         stored = None
diff --git a/studio/backend/utils/utils.py b/studio/backend/utils/utils.py
index e95ef08a7d..7a7774be40 100644
--- a/studio/backend/utils/utils.py
+++ b/studio/backend/utils/utils.py
@@ -22,9 +22,7 @@ logger = get_logger(__name__)
 # log the full exception server-side and return a generic message.
 
 
-def safe_error_detail(
-    error: Exception, fallback: str = "An internal error occurred"
-) -> str:
+def safe_error_detail(error: Exception, fallback: str = "An internal error occurred") -> str:
     """Map a caught exception to a generic, client-safe message.
 
     Never includes raw ``str(error)`` (which can leak internal paths or stack
@@ -44,9 +42,7 @@ def safe_error_detail(
     return fallback
 
 
-def safe_curated_detail(
-    error: Exception, fallback: str = "An internal error occurred"
-) -> str:
+def safe_curated_detail(error: Exception, fallback: str = "An internal error occurred") -> str:
     """Client-safe text for curated domain/validation exceptions meant for the user.
 
     Keeps the message (paths stripped) instead of a generic fallback; use for known
diff --git a/studio/backend/utils/wheel_utils.py b/studio/backend/utils/wheel_utils.py
index e0ce02261b..cca30bfd44 100644
--- a/studio/backend/utils/wheel_utils.py
+++ b/studio/backend/utils/wheel_utils.py
@@ -19,9 +19,7 @@ from utils.subprocess_compat import windows_hidden_subprocess_kwargs
 
 _logger = logging.getLogger(__name__)
 
-FLASH_ATTN_RELEASE_BASE_URL = (
-    "https://github.com/Dao-AILab/flash-attention/releases/download"
-)
+FLASH_ATTN_RELEASE_BASE_URL = "https://github.com/Dao-AILab/flash-attention/releases/download"
 
 
 @functools.lru_cache(maxsize = 1)
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 62b7b2b290..09953843f0 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -70,7 +70,12 @@ def windows_hidden_subprocess_kwargs() -> dict[str, object]:
     return kwargs
 
 
-def env_int(name: str, default: int, *, minimum: int | None = None) -> int:
+def env_int(
+    name: str,
+    default: int,
+    *,
+    minimum: int | None = None,
+) -> int:
     raw = os.environ.get(name)
     if raw is None:
         value = default
@@ -104,9 +109,7 @@ UPSTREAM_REPO = "ggml-org/llama.cpp"
 UPSTREAM_RELEASES_API = f"https://api.github.com/repos/{UPSTREAM_REPO}/releases/latest"
 
 LEMONADE_ROCM_REPO = "lemonade-sdk/llamacpp-rocm"
-LEMONADE_ROCM_RELEASES_API = (
-    f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}/releases/latest"
-)
+LEMONADE_ROCM_RELEASES_API = f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}/releases/latest"
 
 
 def _lemonade_release_api_for(llama_tag: str) -> str:
@@ -135,9 +138,7 @@ def _lemonade_release_api_for(llama_tag: str) -> str:
     )
 
 
-TEST_MODEL_URL = (
-    "https://huggingface.co/ggml-org/models/resolve/main/tinyllamas/stories260K.gguf"
-)
+TEST_MODEL_URL = "https://huggingface.co/ggml-org/models/resolve/main/tinyllamas/stories260K.gguf"
 TEST_MODEL_SHA256 = "270cba1bd5109f42d03350f60406024560464db173c0e387d91f0426d3bd256d"
 VALIDATION_MODEL_CACHE_DIRNAME = ".cache"
 VALIDATION_MODEL_CACHE_FILENAME = "stories260K.gguf"
@@ -256,12 +257,8 @@ _BLACKWELL_MIN_SM = 120
 # windows-cuda build at or above this already covers Blackwell and makes the
 # older pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
 _BLACKWELL_MIN_TOOLKIT = (12, 8)
-_PINNED_BLACKWELL_LLAMA_SHA256 = (
-    "31ddb8b42d7ab4a47cab8c48c397519f580ca502df7e73f3ab396eacc16c8e8d"
-)
-_PINNED_BLACKWELL_CUDART_SHA256 = (
-    "f96935e7e385e3b2d0189239077c10fe8fd7e95690fea4afec455b1b6c7e3f18"
-)
+_PINNED_BLACKWELL_LLAMA_SHA256 = "31ddb8b42d7ab4a47cab8c48c397519f580ca502df7e73f3ab396eacc16c8e8d"
+_PINNED_BLACKWELL_CUDART_SHA256 = "f96935e7e385e3b2d0189239077c10fe8fd7e95690fea4afec455b1b6c7e3f18"
 
 
 def _cuda_runtime_lines_for_major(major: int) -> list[str]:
@@ -279,9 +276,7 @@ def _resolve_linux_bundle_profile(bundle_profile: str) -> "dict[str, Any] | None
     known = DIRECT_LINUX_BUNDLE_PROFILES.get(bundle_profile)
     if known is not None:
         return known
-    m = re.fullmatch(
-        r"cuda(?P<major>\d+)-(?P<klass>older|newer|portable)", bundle_profile
-    )
+    m = re.fullmatch(r"cuda(?P<major>\d+)-(?P<klass>older|newer|portable)", bundle_profile)
     if not m:
         return None
     base_key = max(
@@ -788,9 +783,9 @@ def refs_match(candidate_ref: str | None, requested_ref: str | None) -> bool:
     candidate_commit = normalize_source_commit(candidate_ref)
     requested_commit = normalize_source_commit(requested_ref)
     if candidate_commit and requested_commit:
-        return candidate_commit.startswith(
-            requested_commit
-        ) or requested_commit.startswith(candidate_commit)
+        return candidate_commit.startswith(requested_commit) or requested_commit.startswith(
+            candidate_commit
+        )
     return False
 
 
@@ -820,9 +815,7 @@ def windows_cuda_upstream_asset_names(llama_tag: str, runtime: str) -> list[str]
 
 
 def windows_cuda_asset_aliases(
-    asset_name: str,
-    *,
-    compatibility_tag: str | None = None,
+    asset_name: str, *, compatibility_tag: str | None = None
 ) -> list[str]:
     aliases: list[str] = []
     legacy_match = re.fullmatch(
@@ -886,11 +879,7 @@ class DownloadProgress:
         self.last_emit = 0.0
         term_ok = os.environ.get("TERM", "").lower() != "dumb"
         self.stream = (
-            sys.stderr
-            if sys.stderr.isatty()
-            else sys.stdout
-            if sys.stdout.isatty()
-            else sys.stderr
+            sys.stderr if sys.stderr.isatty() else sys.stdout if sys.stdout.isatty() else sys.stderr
         )
         self.is_tty = term_ok and self.stream.isatty()
         self.completed = False
@@ -898,7 +887,12 @@ class DownloadProgress:
         self.last_milestone_bytes = 0
         self.has_rendered_tty_progress = False
 
-    def _render(self, downloaded_bytes: int, *, final: bool = False) -> str:
+    def _render(
+        self,
+        downloaded_bytes: int,
+        *,
+        final: bool = False,
+    ) -> str:
         elapsed = max(time.monotonic() - self.start_time, 1e-6)
         speed = downloaded_bytes / elapsed
         speed_text = f"{format_byte_count(speed)}/s"
@@ -918,10 +912,7 @@ class DownloadProgress:
         if self.is_tty:
             elapsed = now - self.start_time
             if not self.has_rendered_tty_progress:
-                if (
-                    self.total_bytes is not None
-                    and downloaded_bytes >= self.total_bytes
-                ):
+                if self.total_bytes is not None and downloaded_bytes >= self.total_bytes:
                     return
                 if elapsed < TTY_PROGRESS_START_DELAY_SECONDS:
                     return
@@ -943,10 +934,7 @@ class DownloadProgress:
         if self.total_bytes is not None:
             percent = int((downloaded_bytes * 100) / max(self.total_bytes, 1))
             milestone_percent = min((percent // 25) * 25, 100)
-            if (
-                milestone_percent > self.last_milestone_percent
-                and milestone_percent < 100
-            ):
+            if milestone_percent > self.last_milestone_percent and milestone_percent < 100:
                 self.last_milestone_percent = milestone_percent
                 should_emit = True
         else:
@@ -999,11 +987,7 @@ def download_bytes(
                 content_length = response.headers.get("Content-Length")
                 if content_length and content_length.isdigit():
                     total_bytes = int(content_length)
-                progress = (
-                    DownloadProgress(progress_label, total_bytes)
-                    if progress_label
-                    else None
-                )
+                progress = DownloadProgress(progress_label, total_bytes) if progress_label else None
                 data = bytearray()
                 while True:
                     chunk = response.read(1024 * 1024)
@@ -1033,17 +1017,13 @@ def fetch_json(url: str) -> Any:
             data = download_bytes(
                 url,
                 timeout = 30,
-                headers = github_api_headers(url)
-                if is_github_api_url(url)
-                else auth_headers(url),
+                headers = github_api_headers(url) if is_github_api_url(url) else auth_headers(url),
             )
         except urllib.error.HTTPError as exc:
             if exc.code == 403 and is_github_api_url(url):
                 hint = ""
                 if not (os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")):
-                    hint = (
-                        "; set GH_TOKEN or GITHUB_TOKEN to avoid GitHub API rate limits"
-                    )
+                    hint = "; set GH_TOKEN or GITHUB_TOKEN to avoid GitHub API rate limits"
                 raise RuntimeError(f"GitHub API returned 403 for {url}{hint}") from exc
             raise
         if not data:
@@ -1052,9 +1032,7 @@ def fetch_json(url: str) -> Any:
             try:
                 payload = json.loads(data.decode("utf-8"))
             except (UnicodeDecodeError, json.JSONDecodeError) as exc:
-                last_decode_exc = RuntimeError(
-                    f"downloaded invalid JSON from {url}: {exc}"
-                )
+                last_decode_exc = RuntimeError(f"downloaded invalid JSON from {url}: {exc}")
             else:
                 if not isinstance(payload, dict) and not isinstance(payload, list):
                     raise RuntimeError(
@@ -1088,9 +1066,7 @@ def download_file(url: str, destination: Path) -> None:
                     content_length = response.headers.get("Content-Length")
                     if content_length and content_length.isdigit():
                         total_bytes = int(content_length)
-                    progress = DownloadProgress(
-                        f"Downloading {destination.name}", total_bytes
-                    )
+                    progress = DownloadProgress(f"Downloading {destination.name}", total_bytes)
                     downloaded_bytes = 0
                     while True:
                         chunk = response.read(1024 * 1024)
@@ -1115,27 +1091,19 @@ def download_file(url: str, destination: Path) -> None:
                     pass
             if attempt >= HTTP_FETCH_ATTEMPTS or not is_retryable_url_error(exc):
                 raise
-            log(
-                f"download failed ({attempt}/{HTTP_FETCH_ATTEMPTS}) for {url}: {exc}; retrying"
-            )
+            log(f"download failed ({attempt}/{HTTP_FETCH_ATTEMPTS}) for {url}: {exc}; retrying")
             sleep_backoff(attempt, exc = exc)
     assert last_exc is not None
     raise last_exc
 
 
 def download_file_verified(
-    url: str,
-    destination: Path,
-    *,
-    expected_sha256: str | None,
-    label: str,
+    url: str, destination: Path, *, expected_sha256: str | None, label: str
 ) -> None:
     normalized_expected = normalize_sha256_digest(expected_sha256)
     if not normalized_expected:
         download_file(url, destination)
-        log(
-            f"downloaded {label} without a published sha256; relying on install validation"
-        )
+        log(f"downloaded {label} without a published sha256; relying on install validation")
         return
 
     for attempt in range(1, 3):
@@ -1219,9 +1187,7 @@ def latest_upstream_release_tag() -> str:
     payload = fetch_json(UPSTREAM_RELEASES_API)
     tag = payload.get("tag_name")
     if not isinstance(tag, str) or not tag:
-        raise RuntimeError(
-            f"latest release tag was missing from {UPSTREAM_RELEASES_API}"
-        )
+        raise RuntimeError(f"latest release tag was missing from {UPSTREAM_RELEASES_API}")
     return tag
 
 
@@ -1256,19 +1222,13 @@ def iter_release_payloads_by_time(
         yield github_release(repo, published_release_tag)
         return
 
-    if (
-        requested_tag
-        and requested_tag != "latest"
-        and is_release_tag_like(requested_tag)
-    ):
+    if requested_tag and requested_tag != "latest" and is_release_tag_like(requested_tag):
         try:
             yield github_release(repo, requested_tag)
             return
         except urllib.error.HTTPError as exc:
             if exc.code == 404:
-                log(
-                    f"release tag {requested_tag} not found in {repo}; scanning recent releases"
-                )
+                log(f"release tag {requested_tag} not found in {repo}; scanning recent releases")
             else:
                 raise
         except Exception:
@@ -1276,21 +1236,15 @@ def iter_release_payloads_by_time(
 
     releases = [
         release
-        for release in github_releases(
-            repo, max_pages = DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES
-        )
-        if isinstance(release, dict)
-        and not release.get("draft")
-        and not release.get("prerelease")
+        for release in github_releases(repo, max_pages = DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES)
+        if isinstance(release, dict) and not release.get("draft") and not release.get("prerelease")
     ]
     releases.sort(key = release_time_sort_key, reverse = True)
     for release in releases:
         yield release
 
 
-def direct_release_matches_request(
-    *, release_tag: str, llama_tag: str, requested_tag: str
-) -> bool:
+def direct_release_matches_request(*, release_tag: str, llama_tag: str, requested_tag: str) -> bool:
     if requested_tag == "latest":
         return True
     for candidate in (release_tag, llama_tag):
@@ -1392,10 +1346,7 @@ def parse_direct_linux_release_bundle(
 
 
 def direct_linux_release_plan(
-    release: dict[str, Any],
-    host: HostInfo,
-    repo: str,
-    requested_tag: str,
+    release: dict[str, Any], host: HostInfo, repo: str, requested_tag: str
 ) -> InstallReleasePlan | None:
     bundle = parse_direct_linux_release_bundle(repo, release)
     if bundle is None:
@@ -1477,10 +1428,7 @@ def direct_linux_release_plan(
 
 
 def direct_upstream_release_plan(
-    release: dict[str, Any],
-    host: HostInfo,
-    repo: str,
-    requested_tag: str,
+    release: dict[str, Any], host: HostInfo, repo: str, requested_tag: str
 ) -> InstallReleasePlan | None:
     release_tag = release.get("tag_name")
     if not isinstance(release_tag, str) or not release_tag:
@@ -1674,9 +1622,7 @@ def resolve_simple_install_release_plans(
             f"{repo} ships only linux-x64 prebuilts; "
             f"{host.machine or 'non-x64'} Linux falls back to source build"
         )
-    allow_older_release_fallback = (
-        requested_tag == "latest" and not published_release_tag
-    )
+    allow_older_release_fallback = requested_tag == "latest" and not published_release_tag
     # macOS: pin the last upstream build that loads on a pre-26 host instead of
     # fetching the latest (macOS 26 only) build and walking back release by
     # release. No-op on macOS 26+, unknown version, non-macOS, and the fork.
@@ -1690,17 +1636,13 @@ def resolve_simple_install_release_plans(
     last_error: PrebuiltFallback | None = None
 
     try:
-        releases = iter_release_payloads_by_time(
-            repo, published_release_tag, requested_tag
-        )
+        releases = iter_release_payloads_by_time(repo, published_release_tag, requested_tag)
         for release in releases:
             try:
                 if host.is_linux and repo == "unslothai/llama.cpp":
                     plan = direct_linux_release_plan(release, host, repo, requested_tag)
                 else:
-                    plan = direct_upstream_release_plan(
-                        release, host, repo, requested_tag
-                    )
+                    plan = direct_upstream_release_plan(release, host, repo, requested_tag)
                 if plan is None:
                     continue
             except PrebuiltFallback as exc:
@@ -1720,17 +1662,13 @@ def resolve_simple_install_release_plans(
     except PrebuiltFallback:
         raise
     except Exception as exc:
-        raise PrebuiltFallback(
-            f"failed to inspect published releases in {repo}: {exc}"
-        ) from exc
+        raise PrebuiltFallback(f"failed to inspect published releases in {repo}: {exc}") from exc
 
     if plans:
         return requested_tag, plans
     if last_error is not None:
         raise last_error
-    raise PrebuiltFallback(
-        f"no installable published llama.cpp releases were found in {repo}"
-    )
+    raise PrebuiltFallback(f"no installable published llama.cpp releases were found in {repo}")
 
 
 def normalized_requested_llama_tag(requested_tag: str | None) -> str:
@@ -1782,9 +1720,7 @@ def parse_cuda_visible_devices(value: str | None) -> list[str] | None:
     return [token.strip() for token in raw.split(",") if token.strip()]
 
 
-def supports_explicit_visible_device_matching(
-    visible_devices: list[str] | None,
-) -> bool:
+def supports_explicit_visible_device_matching(visible_devices: list[str] | None) -> bool:
     if not visible_devices:
         return False
     for token in visible_devices:
@@ -1796,8 +1732,7 @@ def supports_explicit_visible_device_matching(
 
 
 def select_visible_gpu_rows(
-    gpu_rows: Iterable[tuple[str, str, str]],
-    visible_devices: list[str] | None,
+    gpu_rows: Iterable[tuple[str, str, str]], visible_devices: list[str] | None
 ) -> list[tuple[str, str, str]]:
     rows = list(gpu_rows)
     if visible_devices is None:
@@ -1835,9 +1770,7 @@ def dir_provides_exact_library(directory: str | Path, library: str) -> bool:
     return candidate.exists() and (candidate.is_file() or candidate.is_symlink())
 
 
-def linux_runtime_dirs_for_required_libraries(
-    required_libraries: Iterable[str],
-) -> list[str]:
+def linux_runtime_dirs_for_required_libraries(required_libraries: Iterable[str]) -> list[str]:
     required = [library for library in required_libraries if library]
     candidates: list[str | Path] = []
 
@@ -1853,9 +1786,7 @@ def linux_runtime_dirs_for_required_libraries(
         value = os.environ.get(name)
         if value:
             cuda_roots.append(Path(value))
-    cuda_roots.extend(
-        Path(path) for path in glob_paths("/usr/local/cuda", "/usr/local/cuda-*")
-    )
+    cuda_roots.extend(Path(path) for path in glob_paths("/usr/local/cuda", "/usr/local/cuda-*"))
 
     for root in cuda_roots:
         candidates.extend(
@@ -1880,8 +1811,7 @@ def linux_runtime_dirs_for_required_libraries(
         )
     )
     candidates.extend(
-        Path(path)
-        for path in glob_paths("/usr/local/lib/ollama/cuda_v*", "/usr/lib/wsl/lib")
+        Path(path) for path in glob_paths("/usr/local/lib/ollama/cuda_v*", "/usr/lib/wsl/lib")
     )
     candidates.extend(Path(path) for path in python_runtime_dirs())
     candidates.extend(Path(path) for path in ldconfig_runtime_dirs(required))
@@ -1893,9 +1823,7 @@ def linux_runtime_dirs_for_required_libraries(
     matched: list[tuple[int, str]] = []
     for directory in resolved:
         base = Path(directory)
-        provided = sum(
-            1 for library in required if dir_provides_exact_library(directory, library)
-        )
+        provided = sum(1 for library in required if dir_provides_exact_library(directory, library))
         if provided:
             matched.append((provided, directory))
 
@@ -1916,9 +1844,7 @@ def detected_linux_runtime_lines() -> tuple[list[str], dict[str, list[str]]]:
         matching_dirs: list[str] = []
         for library in required:
             matched_dirs = [
-                directory
-                for directory in dirs
-                if any(Path(directory).glob(f"{library}*"))
+                directory for directory in dirs if any(Path(directory).glob(f"{library}*"))
             ]
             if not matched_dirs:
                 library_matches = {}
@@ -1955,17 +1881,13 @@ def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
     if not isinstance(asset_name, str) or not asset_name:
         raise ValueError("artifact.asset_name was missing or not a string")
     if not isinstance(install_kind, str) or not install_kind:
-        raise ValueError(
-            f"artifact {asset_name} install_kind was missing or not a string"
-        )
+        raise ValueError(f"artifact {asset_name} install_kind was missing or not a string")
 
     supported_sms_raw = raw.get("supported_sms", [])
     if not isinstance(supported_sms_raw, (list, tuple)):
         raise ValueError(f"artifact {asset_name} supported_sms must be a list or tuple")
     if any(not isinstance(value, (int, str)) for value in supported_sms_raw):
-        raise ValueError(
-            f"artifact {asset_name} supported_sms entries must be ints or strings"
-        )
+        raise ValueError(f"artifact {asset_name} supported_sms entries must be ints or strings")
     supported_sms = normalize_compute_caps(supported_sms_raw)
 
     min_sm_raw = raw.get("min_sm")
@@ -1974,9 +1896,7 @@ def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
         min_sm = int(min_sm_raw) if min_sm_raw is not None else None
         max_sm = int(max_sm_raw) if max_sm_raw is not None else None
     except (TypeError, ValueError) as exc:
-        raise ValueError(
-            f"artifact {asset_name} min_sm/max_sm were not integers"
-        ) from exc
+        raise ValueError(f"artifact {asset_name} min_sm/max_sm were not integers") from exc
     runtime_line = raw.get("runtime_line")
     coverage_class = raw.get("coverage_class")
     bundle_profile = raw.get("bundle_profile")
@@ -1994,9 +1914,7 @@ def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
     return PublishedLlamaArtifact(
         asset_name = asset_name,
         install_kind = install_kind,
-        runtime_line = runtime_line
-        if isinstance(runtime_line, str) and runtime_line
-        else None,
+        runtime_line = runtime_line if isinstance(runtime_line, str) and runtime_line else None,
         coverage_class = coverage_class
         if isinstance(coverage_class, str) and coverage_class
         else None,
@@ -2071,9 +1989,7 @@ def parse_published_release_bundle(
         try:
             artifact = parse_published_artifact(raw_artifact)
         except ValueError as exc:
-            log(
-                f"published artifact ignored for {repo}@{release_tag} artifact[{index}]: {exc}"
-            )
+            log(f"published artifact ignored for {repo}@{release_tag} artifact[{index}]: {exc}")
             continue
         if artifact is not None:
             artifacts.append(artifact)
@@ -2092,9 +2008,7 @@ def parse_published_release_bundle(
         release_tag = release_tag,
         upstream_tag = upstream_tag,
         manifest_sha256 = manifest_sha256,
-        source_repo = source_repo
-        if isinstance(source_repo, str) and source_repo
-        else None,
+        source_repo = source_repo if isinstance(source_repo, str) and source_repo else None,
         source_repo_url = source_repo_url
         if isinstance(source_repo_url, str) and source_repo_url
         else None,
@@ -2117,9 +2031,7 @@ def parse_published_release_bundle(
 
 
 def parse_approved_release_checksums(
-    repo: str,
-    release_tag: str,
-    payload: Any,
+    repo: str, release_tag: str, payload: Any
 ) -> ApprovedReleaseChecksums:
     if not isinstance(payload, dict):
         raise RuntimeError(
@@ -2157,18 +2069,12 @@ def parse_approved_release_checksums(
     artifacts: dict[str, ApprovedArtifactHash] = {}
     for asset_name, raw_entry in artifacts_payload.items():
         if not isinstance(asset_name, str) or not asset_name:
-            raise RuntimeError(
-                "published checksum asset used a non-string artifact key"
-            )
+            raise RuntimeError("published checksum asset used a non-string artifact key")
         if not isinstance(raw_entry, dict):
-            raise RuntimeError(
-                f"published checksum entry for {asset_name} was not an object"
-            )
+            raise RuntimeError(f"published checksum entry for {asset_name} was not an object")
         digest = normalize_sha256_digest(raw_entry.get("sha256"))
         if not digest:
-            raise RuntimeError(
-                f"published checksum entry for {asset_name} omitted a valid sha256"
-            )
+            raise RuntimeError(f"published checksum entry for {asset_name} omitted a valid sha256")
         repo_value = raw_entry.get("repo")
         kind_value = raw_entry.get("kind")
         artifacts[asset_name] = ApprovedArtifactHash(
@@ -2189,9 +2095,7 @@ def parse_approved_release_checksums(
         repo = repo,
         release_tag = release_tag,
         upstream_tag = upstream_tag,
-        source_repo = source_repo
-        if isinstance(source_repo, str) and source_repo
-        else None,
+        source_repo = source_repo if isinstance(source_repo, str) and source_repo else None,
         source_repo_url = source_repo_url
         if isinstance(source_repo_url, str) and source_repo_url
         else None,
@@ -2210,9 +2114,7 @@ def parse_approved_release_checksums(
     )
 
 
-def load_approved_release_checksums(
-    repo: str, release_tag: str
-) -> ApprovedReleaseChecksums:
+def load_approved_release_checksums(repo: str, release_tag: str) -> ApprovedReleaseChecksums:
     try:
         release = github_release(repo, release_tag)
     except Exception as exc:
@@ -2246,9 +2148,7 @@ def iter_published_release_bundles(
         else github_releases(repo, max_pages = DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES)
     )
     for release in releases:
-        if not published_release_tag and (
-            release.get("draft") or release.get("prerelease")
-        ):
+        if not published_release_tag and (release.get("draft") or release.get("prerelease")):
             continue
         try:
             bundle = parse_published_release_bundle(repo, release)
@@ -2301,13 +2201,9 @@ def linux_cuda_choice_from_release(
             )
         )
     published_artifacts = [
-        artifact
-        for artifact in release.artifacts
-        if artifact.install_kind == "linux-cuda"
+        artifact for artifact in release.artifacts if artifact.install_kind == "linux-cuda"
     ]
-    published_asset_names = sorted(
-        artifact.asset_name for artifact in published_artifacts
-    )
+    published_asset_names = sorted(artifact.asset_name for artifact in published_artifacts)
     selection_log.append(
         "linux_cuda_selection: published_assets="
         + (",".join(published_asset_names) if published_asset_names else "none")
@@ -2343,9 +2239,7 @@ def linux_cuda_choice_from_release(
     attempts: list[AssetChoice] = []
     seen_attempts: set[str] = set()
 
-    def add_attempt(
-        artifact: PublishedLlamaArtifact, asset_url: str, reason: str
-    ) -> None:
+    def add_attempt(artifact: PublishedLlamaArtifact, asset_url: str, reason: str) -> None:
         asset_name = artifact.asset_name
         if asset_name in seen_attempts:
             return
@@ -2382,9 +2276,7 @@ def linux_cuda_choice_from_release(
             asset_name = artifact.asset_name
             asset_url = release.assets.get(asset_name)
             if not asset_url:
-                selection_log.append(
-                    f"linux_cuda_selection: reject {asset_name} missing asset"
-                )
+                selection_log.append(f"linux_cuda_selection: reject {asset_name} missing asset")
                 continue
             if not host_sms and artifact.coverage_class != "portable":
                 selection_log.append(
@@ -2412,9 +2304,7 @@ def linux_cuda_choice_from_release(
             supported_sms = {str(value) for value in artifact.supported_sms}
             missing_sms = [sm for sm in host_sms if sm not in supported_sms]
             out_of_range_sms = [
-                sm
-                for sm in host_sms
-                if not (artifact.min_sm <= int(sm) <= artifact.max_sm)
+                sm for sm in host_sms if not (artifact.min_sm <= int(sm) <= artifact.max_sm)
             ]
             reasons: list[str] = []
             if missing_sms:
@@ -2458,8 +2348,7 @@ def linux_cuda_choice_from_release(
         return None
 
     selection_log.append(
-        "linux_cuda_selection: attempt_order="
-        + ",".join(choice.name for choice in attempts)
+        "linux_cuda_selection: attempt_order=" + ",".join(choice.name for choice in attempts)
     )
     for attempt in attempts:
         attempt.selection_log = list(selection_log) + [
@@ -2477,9 +2366,7 @@ def latest_published_linux_cuda_tag(host: HostInfo, published_repo: str) -> str
 
 
 def iter_upstream_releases() -> Iterable[dict[str, Any]]:
-    for release in github_releases(
-        UPSTREAM_REPO, max_pages = DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES
-    ):
+    for release in github_releases(UPSTREAM_REPO, max_pages = DEFAULT_GITHUB_RELEASE_SCAN_MAX_PAGES):
         if release.get("draft") or release.get("prerelease"):
             continue
         yield release
@@ -2514,9 +2401,7 @@ def validated_checksums_for_bundle(
     return checksums
 
 
-def published_release_matches_request(
-    bundle: PublishedReleaseBundle, requested_ref: str
-) -> bool:
+def published_release_matches_request(bundle: PublishedReleaseBundle, requested_ref: str) -> bool:
     if requested_ref == "latest":
         return True
     for candidate in (
@@ -2571,9 +2456,7 @@ def resolve_published_release(
             raise PrebuiltFallback(
                 f"no usable published llama.cpp releases were available in {repo}"
             )
-        raise PrebuiltFallback(
-            f"no published llama.cpp releases were available in {repo}"
-        )
+        raise PrebuiltFallback(f"no published llama.cpp releases were available in {repo}")
 
     raise PrebuiltFallback(
         f"no published prebuilt release in {repo} matched upstream tag {normalized_requested}"
@@ -2632,9 +2515,7 @@ def iter_resolved_published_releases(
         return
 
     if normalized_requested == "latest":
-        raise PrebuiltFallback(
-            f"no published llama.cpp releases were available in {repo}"
-        )
+        raise PrebuiltFallback(f"no published llama.cpp releases were available in {repo}")
 
     raise PrebuiltFallback(
         f"no published prebuilt release in {repo} matched upstream tag {normalized_requested}"
@@ -2692,33 +2573,23 @@ def resolve_requested_install_tag(
     ).bundle.upstream_tag
 
 
-def exact_source_archive_hash(
-    checksums: ApprovedReleaseChecksums,
-) -> ApprovedArtifactHash | None:
+def exact_source_archive_hash(checksums: ApprovedReleaseChecksums) -> ApprovedArtifactHash | None:
     if not checksums.source_commit:
         return None
-    return checksums.artifacts.get(
-        exact_source_archive_logical_name(checksums.source_commit)
-    )
+    return checksums.artifacts.get(exact_source_archive_logical_name(checksums.source_commit))
 
 
 def source_clone_url_from_checksums(checksums: ApprovedReleaseChecksums) -> str | None:
     return source_repo_clone_url(checksums.source_repo, checksums.source_repo_url)
 
 
-def source_build_plan_for_release(
-    release: ResolvedPublishedRelease,
-) -> SourceBuildPlan:
+def source_build_plan_for_release(release: ResolvedPublishedRelease) -> SourceBuildPlan:
     checksums = release.checksums
     exact_source = exact_source_archive_hash(checksums)
     source_repo = checksums.source_repo or release.bundle.source_repo
     source_repo_url = checksums.source_repo_url or release.bundle.source_repo_url
-    requested_source_ref = (
-        checksums.requested_source_ref or release.bundle.requested_source_ref
-    )
-    resolved_source_ref = (
-        checksums.resolved_source_ref or release.bundle.resolved_source_ref
-    )
+    requested_source_ref = checksums.requested_source_ref or release.bundle.requested_source_ref
+    resolved_source_ref = checksums.resolved_source_ref or release.bundle.resolved_source_ref
     source_commit = checksums.source_commit or release.bundle.source_commit
     source_ref_kind = checksums.source_ref_kind or release.bundle.source_ref_kind
     source_url = source_repo_clone_url(source_repo, source_repo_url)
@@ -2734,14 +2605,8 @@ def source_build_plan_for_release(
             resolved_source_ref = resolved_source_ref,
             source_commit = source_commit,
         )
-    source_ref = checkout_friendly_ref(
-        source_ref_kind, resolved_source_ref or requested_source_ref
-    )
-    if (
-        source_url
-        and source_ref
-        and source_ref_kind in {"tag", "branch", "pull", "commit"}
-    ):
+    source_ref = checkout_friendly_ref(source_ref_kind, resolved_source_ref or requested_source_ref)
+    if source_url and source_ref and source_ref_kind in {"tag", "branch", "pull", "commit"}:
         return SourceBuildPlan(
             source_url = source_url,
             source_ref = source_ref,
@@ -2925,9 +2790,7 @@ def detect_host() -> HostInfo:
         # ROCm host as NVIDIA and short-circuit the ROCm path.
         try:
             listing = run_capture([nvidia_smi, "-L"], timeout = 20)
-            gpu_lines = [
-                line for line in listing.stdout.splitlines() if line.startswith("GPU ")
-            ]
+            gpu_lines = [line for line in listing.stdout.splitlines() if line.startswith("GPU ")]
             if gpu_lines:
                 has_physical_nvidia = True
                 has_usable_nvidia = visible_device_tokens != []
@@ -3225,9 +3088,7 @@ def detect_torch_cuda_runtime_preference(host: HostInfo) -> CudaRuntimePreferenc
     try:
         cuda_available = bool(torch.cuda.is_available())
     except Exception as exc:
-        selection_log.append(
-            f"torch_cuda_preference: torch.cuda.is_available() failed: {exc}"
-        )
+        selection_log.append(f"torch_cuda_preference: torch.cuda.is_available() failed: {exc}")
         return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)
 
     if not cuda_available:
@@ -3315,14 +3176,10 @@ def windows_cuda_attempts(
             f"{preferred_runtime_line} unavailable_or_incompatible"
         )
     else:
-        selection_log.append(
-            "windows_cuda_selection: no Torch runtime preference available"
-        )
+        selection_log.append("windows_cuda_selection: no Torch runtime preference available")
 
     runtime_order.extend(
-        runtime_line
-        for runtime_line in normal_runtime_lines
-        if runtime_line not in runtime_order
+        runtime_line for runtime_line in normal_runtime_lines if runtime_line not in runtime_order
     )
     # Keep every driver-compatible line reachable as a fallback, so a line gated
     # out by the driver version still drops to an older major (cuda13 -> cuda12).
@@ -3346,9 +3203,7 @@ def windows_cuda_attempts(
         # Track whatever minor llama.cpp actually ships for this major
         # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release has no
         # matching asset instead of guessing a now-missing name.
-        runtime = _published_windows_cuda_runtime(
-            upstream_assets, major, host.driver_cuda_version
-        )
+        runtime = _published_windows_cuda_runtime(upstream_assets, major, host.driver_cuda_version)
         if runtime is None:
             selection_log.append(
                 f"windows_cuda_selection: no driver-supported asset for {runtime_line}"
@@ -3414,9 +3269,7 @@ def _windows_cuda_attempt_covers_blackwell(attempt: AssetChoice) -> bool:
     if attempt.install_kind != "windows-cuda":
         return False
     m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
-    return (
-        m is not None and (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
-    )
+    return m is not None and (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
 
 
 def _pinned_windows_cuda_fallback(
@@ -3441,10 +3294,7 @@ def _pinned_windows_cuda_fallback(
     caps = normalize_compute_caps(host.compute_caps)
     if not caps or int(caps[-1]) < _BLACKWELL_MIN_SM:
         return None
-    if any(
-        _windows_cuda_attempt_covers_blackwell(attempt)
-        for attempt in existing_cuda_attempts
-    ):
+    if any(_windows_cuda_attempt_covers_blackwell(attempt) for attempt in existing_cuda_attempts):
         return None
     tag = _PINNED_BLACKWELL_FALLBACK_TAG
     runtime = _PINNED_BLACKWELL_FALLBACK_RUNTIME
@@ -3499,9 +3349,7 @@ def _augment_checksums_with_pin(
 
 
 def _with_pinned_windows_cuda_fallback(
-    host: HostInfo,
-    attempts: list[AssetChoice],
-    checksums: ApprovedReleaseChecksums,
+    host: HostInfo, attempts: list[AssetChoice], checksums: ApprovedReleaseChecksums
 ) -> tuple[list[AssetChoice], ApprovedReleaseChecksums]:
     """Insert the Blackwell pin ahead of the Windows CUDA attempts and keep it
     through apply_approved_hashes, or return the inputs unchanged when dormant.
@@ -3544,9 +3392,7 @@ def published_windows_cuda_attempts(
         selection_log,
     )
     published_artifacts = [
-        artifact
-        for artifact in release.artifacts
-        if artifact.install_kind == "windows-cuda"
+        artifact for artifact in release.artifacts if artifact.install_kind == "windows-cuda"
     ]
     artifacts_by_runtime: dict[str, list[PublishedLlamaArtifact]] = {}
     for artifact in published_artifacts:
@@ -3642,15 +3488,10 @@ def resolve_linux_cuda_choice(
 
 
 def published_asset_choice_for_kind(
-    release: PublishedReleaseBundle,
-    install_kind: str,
+    release: PublishedReleaseBundle, install_kind: str
 ) -> AssetChoice | None:
     candidates = sorted(
-        (
-            artifact
-            for artifact in release.artifacts
-            if artifact.install_kind == install_kind
-        ),
+        (artifact for artifact in release.artifacts if artifact.install_kind == install_kind),
         key = lambda artifact: (artifact.rank, artifact.asset_name),
     )
     for artifact in candidates:
@@ -3666,9 +3507,7 @@ def published_asset_choice_for_kind(
             install_kind = install_kind,
             runtime_line = artifact.runtime_line,
             selection_log = list(release.selection_log)
-            + [
-                f"published_selection: selected {artifact.asset_name} install_kind={install_kind}"
-            ],
+            + [f"published_selection: selected {artifact.asset_name} install_kind={install_kind}"],
         )
     return None
 
@@ -3725,11 +3564,7 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
             if result.returncode == 0:
                 raw = (result.stdout or "").strip().split("\n")[0]
                 parts = raw.split(".")
-                if (
-                    len(parts) >= 2
-                    and parts[0].isdigit()
-                    and parts[1].split("-")[0].isdigit()
-                ):
+                if len(parts) >= 2 and parts[0].isdigit() and parts[1].split("-")[0].isdigit():
                     return int(parts[0]), int(parts[1].split("-")[0])
         except Exception:
             pass
@@ -3888,9 +3723,7 @@ def resolve_lemonade_rocm_choice(
         return None
     release_tag = release.get("tag_name") if isinstance(release, dict) else None
     if not isinstance(release_tag, str) or not release_tag:
-        log(
-            f"Unexpected {LEMONADE_ROCM_REPO} release payload; skipping lemonade prebuilt"
-        )
+        log(f"Unexpected {LEMONADE_ROCM_REPO} release payload; skipping lemonade prebuilt")
         return None
     assets = release_asset_map(release)
     asset_name = f"llama-{release_tag}-{os_prefix}-rocm-{gfx_family}-x64.zip"
@@ -3986,9 +3819,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
             _compatible: list[tuple[tuple[int, ...], str]] = rocm_candidates
             if _host_rocm_version is not None:
                 _compatible = [
-                    item
-                    for item in rocm_candidates
-                    if item[0][:2] <= _host_rocm_version
+                    item for item in rocm_candidates if item[0][:2] <= _host_rocm_version
                 ]
             if rocm_candidates and not _compatible:
                 # Fall back to the newest candidate so a source build is
@@ -4052,9 +3883,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
 
             hip_name = f"llama-{llama_tag}-bin-win-hip-radeon-x64.zip"
             if hip_name in upstream_assets:
-                log(
-                    f"AMD ROCm detected on Windows -- trying upstream HIP prebuilt {hip_name}"
-                )
+                log(f"AMD ROCm detected on Windows -- trying upstream HIP prebuilt {hip_name}")
                 return AssetChoice(
                     repo = UPSTREAM_REPO,
                     tag = llama_tag,
@@ -4063,9 +3892,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                     source_label = "upstream",
                     install_kind = "windows-hip",
                 )
-            log(
-                "AMD ROCm detected on Windows but no HIP prebuilt found -- falling back to CPU"
-            )
+            log("AMD ROCm detected on Windows but no HIP prebuilt found -- falling back to CPU")
 
         upstream_name = f"llama-{llama_tag}-bin-win-cpu-x64.zip"
         if upstream_name not in upstream_assets:
@@ -4105,9 +3932,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
             install_kind = "macos-x64",
         )
 
-    raise PrebuiltFallback(
-        f"no prebuilt policy exists for {host.system} {host.machine}"
-    )
+    raise PrebuiltFallback(f"no prebuilt policy exists for {host.system} {host.machine}")
 
 
 def resolve_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice:
@@ -4185,18 +4010,14 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
         normalized = member_name.replace("\\", "/")
         member_path = Path(normalized)
         if member_path.is_absolute():
-            raise PrebuiltFallback(
-                f"archive member used an absolute path: {member_name}"
-            )
+            raise PrebuiltFallback(f"archive member used an absolute path: {member_name}")
 
         target = (base / member_path).resolve()
         base_resolved = base.resolve()
         try:
             target.relative_to(base_resolved)
         except ValueError as exc:
-            raise PrebuiltFallback(
-                f"archive member escaped destination: {member_name}"
-            ) from exc
+            raise PrebuiltFallback(f"archive member escaped destination: {member_name}") from exc
         return target
 
     def _try_repair_missing_slash(
@@ -4242,11 +4063,7 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
         return candidates[0][len(prefix) :]
 
     def safe_link_target(
-        base: Path,
-        member_name: str,
-        link_name: str,
-        target: Path,
-        archive_names: set[str],
+        base: Path, member_name: str, link_name: str, target: Path, archive_names: set[str]
     ) -> tuple[str, Path]:
         normalized = link_name.replace("\\", "/")
         repaired = _try_repair_missing_slash(member_name, normalized, archive_names)
@@ -4306,9 +4123,7 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
                 target.parent.mkdir(parents = True, exist_ok = True)
                 extracted = archive.extractfile(member)
                 if extracted is None:
-                    raise PrebuiltFallback(
-                        f"tar archive entry could not be read: {member.name}"
-                    )
+                    raise PrebuiltFallback(f"tar archive entry could not be read: {member.name}")
                 with extracted, target.open("wb") as dst:
                     shutil.copyfileobj(extracted, dst)
 
@@ -4342,9 +4157,7 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
                 details = ", ".join(
                     f"{member.name} -> {member.linkname}" for member, _ in next_round
                 )
-                raise PrebuiltFallback(
-                    f"tar archive contained unresolved link entries: {details}"
-                )
+                raise PrebuiltFallback(f"tar archive contained unresolved link entries: {details}")
             unresolved = next_round
 
     destination.mkdir(parents = True, exist_ok = True)
@@ -4358,7 +4171,11 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
 
 
 def copy_globs(
-    source_dir: Path, destination: Path, patterns: list[str], *, required: bool = True
+    source_dir: Path,
+    destination: Path,
+    patterns: list[str],
+    *,
+    required: bool = True,
 ) -> None:
     destination.mkdir(parents = True, exist_ok = True)
     matched_sources: dict[str, Path] = {}
@@ -4457,9 +4274,7 @@ def hydrate_source_tree(
         for index, source_url in enumerate(source_urls):
             try:
                 if index > 0:
-                    log(
-                        f"retrying source tree download from fallback URL: {source_url}"
-                    )
+                    log(f"retrying source tree download from fallback URL: {source_url}")
                 download_file_verified(
                     source_url,
                     archive_path,
@@ -4484,14 +4299,11 @@ def hydrate_source_tree(
             source_root / "gguf-py",
         ]
         missing = [
-            str(path.relative_to(source_root))
-            for path in required_paths
-            if not path.exists()
+            str(path.relative_to(source_root)) for path in required_paths if not path.exists()
         ]
         if missing:
             raise PrebuiltFallback(
-                "upstream source archive was missing required repo files: "
-                + ", ".join(missing)
+                "upstream source archive was missing required repo files: " + ", ".join(missing)
             )
         copy_directory_contents(source_root, install_dir)
     except PrebuiltFallback:
@@ -4518,9 +4330,7 @@ def discover_installed_executable(install_dir: Path, executable_name: str) -> Pa
     direct = install_dir / executable_name
     if direct.exists() and direct.is_file():
         return direct
-    candidate = next(
-        (path for path in install_dir.rglob(executable_name) if path.is_file()), None
-    )
+    candidate = next((path for path in install_dir.rglob(executable_name) if path.is_file()), None)
     if candidate is None:
         raise PrebuiltFallback(f"{executable_name} was not installed")
     return candidate
@@ -4550,9 +4360,7 @@ def create_exec_entrypoint(entrypoint: Path, target: Path) -> None:
         write_exec_wrapper(entrypoint, target)
 
 
-def overlay_directory_for_choice(
-    install_dir: Path, choice: AssetChoice, host: HostInfo
-) -> Path:
+def overlay_directory_for_choice(install_dir: Path, choice: AssetChoice, host: HostInfo) -> Path:
     if host.is_windows or choice.install_kind.startswith("windows"):
         path = install_dir / "build" / "bin" / "Release"
     else:
@@ -4590,9 +4398,7 @@ def runtime_patterns_for_choice(choice: AssetChoice) -> list[str]:
         "windows-arm64",
     }:
         return ["llama-server.exe", "llama-quantize.exe", "*.dll"]
-    raise PrebuiltFallback(
-        f"unsupported install kind for runtime overlay: {choice.install_kind}"
-    )
+    raise PrebuiltFallback(f"unsupported install kind for runtime overlay: {choice.install_kind}")
 
 
 def runtime_subdirs_for_choice(choice: AssetChoice) -> list[str]:
@@ -4801,9 +4607,7 @@ def confirm_install_tree(install_dir: Path, host: HostInfo) -> None:
     expected.append(install_dir / "UNSLOTH_PREBUILT_INFO.json")
     missing = [str(path) for path in expected if not path.exists()]
     if missing:
-        raise RuntimeError(
-            "activated install was missing expected files: " + ", ".join(missing)
-        )
+        raise RuntimeError("activated install was missing expected files: " + ", ".join(missing))
 
 
 def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo) -> None:
@@ -4926,15 +4730,11 @@ def install_from_archives(
                 expected_sha256 = choice.runtime_sha256,
                 label = f"prebuilt runtime archive {choice.runtime_name}",
             )
-            runtime_extract_dir = Path(
-                tempfile.mkdtemp(prefix = "extract-runtime-", dir = work_dir)
-            )
+            runtime_extract_dir = Path(tempfile.mkdtemp(prefix = "extract-runtime-", dir = work_dir))
             extract_archive(runtime_archive, runtime_extract_dir)
         source_dir = extract_dir
         overlay_dir = overlay_directory_for_choice(install_dir, choice, host)
-        copy_globs(
-            source_dir, overlay_dir, runtime_patterns_for_choice(choice), required = True
-        )
+        copy_globs(source_dir, overlay_dir, runtime_patterns_for_choice(choice), required = True)
         for _subdir in runtime_subdirs_for_choice(choice):
             _src_subdir = source_dir / _subdir
             if _src_subdir.is_dir():
@@ -4979,9 +4779,7 @@ def install_from_archives(
     source_server = build_bin / "llama-server"
     source_quantize = build_bin / "llama-quantize"
     if not source_server.exists() or not source_quantize.exists():
-        raise PrebuiltFallback(
-            "unix executables were not installed correctly into build/bin"
-        )
+        raise PrebuiltFallback("unix executables were not installed correctly into build/bin")
     os.chmod(source_server, 0o755)
     os.chmod(source_quantize, 0o755)
 
@@ -5007,13 +4805,9 @@ def ensure_repo_shape(install_dir: Path) -> None:
         install_dir / "convert_hf_to_gguf.py",
         install_dir / "gguf-py",
     ]
-    missing = [
-        str(path.relative_to(install_dir)) for path in required if not path.exists()
-    ]
+    missing = [str(path.relative_to(install_dir)) for path in required if not path.exists()]
     if missing:
-        raise PrebuiltFallback(
-            "hydrated llama.cpp source tree was missing: " + ", ".join(missing)
-        )
+        raise PrebuiltFallback("hydrated llama.cpp source tree was missing: " + ", ".join(missing))
 
 
 def validation_model_cache_path(install_dir: Path) -> Path:
@@ -5028,8 +4822,7 @@ def validated_validation_model_bytes(data: bytes) -> bytes:
     digest = hashlib.sha256(data).hexdigest()
     if digest != TEST_MODEL_SHA256:
         raise RuntimeError(
-            "validation model checksum mismatch: "
-            f"expected={TEST_MODEL_SHA256} actual={digest}"
+            f"validation model checksum mismatch: expected={TEST_MODEL_SHA256} actual={digest}"
         )
     return data
 
@@ -5042,9 +4835,7 @@ def download_validation_model(path: Path, cache_path: Path | None = None) -> Non
                 data = validated_validation_model_bytes(cache_path.read_bytes())
                 log(f"using cached tiny GGUF validation model from {cache_path}")
             except Exception as exc:
-                log(
-                    f"cached tiny GGUF validation model was invalid; refreshing cache ({exc})"
-                )
+                log(f"cached tiny GGUF validation model was invalid; refreshing cache ({exc})")
                 data = None
         if data is None:
             log("downloading tiny GGUF validation model")
@@ -5133,9 +4924,7 @@ def dedupe_existing_dirs(paths: Iterable[str | Path]) -> list[str]:
     return unique
 
 
-def linux_missing_libraries(
-    binary_path: Path, *, env: dict[str, str] | None = None
-) -> list[str]:
+def linux_missing_libraries(binary_path: Path, *, env: dict[str, str] | None = None) -> list[str]:
     try:
         result = run_capture(["ldd", str(binary_path)], timeout = 20, env = env)
     except Exception:
@@ -5292,9 +5081,7 @@ def _macho_slice_minos(data: bytes, offset: int) -> tuple[int, int] | None:
     return None
 
 
-def macho_minimum_macos(
-    path: Path, host: HostInfo | None = None
-) -> tuple[int, int] | None:
+def macho_minimum_macos(path: Path, host: HostInfo | None = None) -> tuple[int, int] | None:
     """Minimum macOS (major, minor) a Mach-O binary or dylib requires.
 
     Pure-Python so it works on consumer Macs without the Xcode command line
@@ -5333,9 +5120,7 @@ def macho_minimum_macos(
             return None
         if host is not None:
             want = (
-                _CPU_TYPE_ARM64
-                if host.is_arm64
-                else (_CPU_TYPE_X86_64 if host.is_x86_64 else None)
+                _CPU_TYPE_ARM64 if host.is_arm64 else (_CPU_TYPE_X86_64 if host.is_x86_64 else None)
             )
             for cputype, minos in slices:
                 if cputype == want:
@@ -5355,9 +5140,7 @@ def looks_like_macos_incompatibility(text: str) -> bool:
 
 
 def macos_binary_minos_issues(
-    binaries: Iterable[Path],
-    install_dir: Path,
-    host: HostInfo,
+    binaries: Iterable[Path], install_dir: Path, host: HostInfo
 ) -> list[str]:
     """Issue strings for every installed Mach-O whose minimum macOS exceeds the
     host. Scans the given executables plus every bundled .dylib next to them --
@@ -5387,9 +5170,7 @@ def macos_binary_minos_issues(
 
 
 def preflight_macos_installed_binaries(
-    binaries: Iterable[Path],
-    install_dir: Path,
-    host: HostInfo,
+    binaries: Iterable[Path], install_dir: Path, host: HostInfo
 ) -> None:
     """Reject a macos prebuilt whose minimum-OS is newer than the host. The
     upstream selector pins a loadable release up front, so here this is the
@@ -5400,15 +5181,12 @@ def preflight_macos_installed_binaries(
     issues = macos_binary_minos_issues(binaries, install_dir, host)
     if issues:
         raise PrebuiltFallback(
-            "macos prebuilt requires a newer macOS than this host:\n"
-            + "\n".join(issues)
+            "macos prebuilt requires a newer macOS than this host:\n" + "\n".join(issues)
         )
 
 
 def preflight_linux_installed_binaries(
-    binaries: Iterable[Path],
-    install_dir: Path,
-    host: HostInfo,
+    binaries: Iterable[Path], install_dir: Path, host: HostInfo
 ) -> None:
     if not host.is_linux:
         return
@@ -5419,18 +5197,14 @@ def preflight_linux_installed_binaries(
         missing = linux_missing_libraries(binary_path, env = env)
         if not missing:
             continue
-        runtime_dirs = [
-            part for part in env.get("LD_LIBRARY_PATH", "").split(os.pathsep) if part
-        ]
+        runtime_dirs = [part for part in env.get("LD_LIBRARY_PATH", "").split(os.pathsep) if part]
         issues.append(
             f"{binary_path.name}: missing={','.join(missing)} "
             f"ld_library_path={','.join(runtime_dirs) if runtime_dirs else 'none'}"
         )
 
     if issues:
-        raise PrebuiltFallback(
-            "linux extracted binary preflight failed:\n" + "\n".join(issues)
-        )
+        raise PrebuiltFallback("linux extracted binary preflight failed:\n" + "\n".join(issues))
 
 
 def glob_paths(*patterns: str) -> list[str]:
@@ -5474,12 +5248,9 @@ def windows_runtime_dirs() -> list[str]:
 
 
 def windows_runtime_dirs_for_patterns(
-    required_patterns: Iterable[str],
-    candidate_dirs: Iterable[str] | None = None,
+    required_patterns: Iterable[str], candidate_dirs: Iterable[str] | None = None
 ) -> list[str]:
-    directories = (
-        list(candidate_dirs) if candidate_dirs is not None else windows_runtime_dirs()
-    )
+    directories = list(candidate_dirs) if candidate_dirs is not None else windows_runtime_dirs()
     matching_dirs: list[str] = []
     for pattern in required_patterns:
         matched_dirs = [
@@ -5523,20 +5294,12 @@ def binary_env(
             str(install_dir),
             *linux_runtime_dirs(binary_path),
         ]
-        existing = [
-            part for part in env.get("LD_LIBRARY_PATH", "").split(os.pathsep) if part
-        ]
-        env["LD_LIBRARY_PATH"] = os.pathsep.join(
-            dedupe_existing_dirs([*ld_dirs, *existing])
-        )
+        existing = [part for part in env.get("LD_LIBRARY_PATH", "").split(os.pathsep) if part]
+        env["LD_LIBRARY_PATH"] = os.pathsep.join(dedupe_existing_dirs([*ld_dirs, *existing]))
     elif host.is_macos:
         dyld_dirs = [str(binary_path.parent), str(install_dir)]
-        existing = [
-            part for part in env.get("DYLD_LIBRARY_PATH", "").split(os.pathsep) if part
-        ]
-        env["DYLD_LIBRARY_PATH"] = os.pathsep.join(
-            dedupe_existing_dirs([*dyld_dirs, *existing])
-        )
+        existing = [part for part in env.get("DYLD_LIBRARY_PATH", "").split(os.pathsep) if part]
+        env["DYLD_LIBRARY_PATH"] = os.pathsep.join(dedupe_existing_dirs([*dyld_dirs, *existing]))
     return env
 
 
@@ -5558,11 +5321,7 @@ def validate_quantize(
         env = binary_env(quantize_path, install_dir, host, runtime_line = runtime_line),
         **windows_hidden_subprocess_kwargs(),
     )
-    if (
-        result.returncode != 0
-        or not quantized_path.exists()
-        or quantized_path.stat().st_size == 0
-    ):
+    if result.returncode != 0 or not quantized_path.exists() or quantized_path.stat().st_size == 0:
         combined = result.stdout + ("\n" + result.stderr if result.stderr else "")
         # Backstop for prebuilts the static minos scan could not read: a dyld
         # "built for macOS N" / missing Metal symbol failure means this binary
@@ -5572,9 +5331,7 @@ def validate_quantize(
             if looks_like_macos_incompatibility(combined)
             else ""
         )
-        raise PrebuiltFallback(
-            prefix + "llama-quantize validation failed:\n" + combined
-        )
+        raise PrebuiltFallback(prefix + "llama-quantize validation failed:\n" + combined)
 
 
 def validate_server(
@@ -5630,9 +5387,7 @@ def validate_server(
             # is exercised against the actual hardware rather than the
             # CPU fallback. NVIDIA and macOS-arm64 are already covered.
             _enable_gpu_layers = (
-                host.has_usable_nvidia
-                or host.has_rocm
-                or (host.is_macos and host.is_arm64)
+                host.has_usable_nvidia or host.has_rocm or (host.is_macos and host.is_arm64)
             )
         if _enable_gpu_layers:
             command.extend(["--n-gpu-layers", "1"])
@@ -5648,9 +5403,7 @@ def validate_server(
                     stdout = log_handle,
                     stderr = subprocess.STDOUT,
                     text = True,
-                    env = binary_env(
-                        server_path, install_dir, host, runtime_line = runtime_line
-                    ),
+                    env = binary_env(server_path, install_dir, host, runtime_line = runtime_line),
                     **windows_hidden_subprocess_kwargs(),
                 )
                 deadline = time.time() + 60
@@ -5665,9 +5418,7 @@ def validate_server(
                         exited_quickly = (
                             time.time() - startup_started
                         ) <= SERVER_BIND_RETRY_WINDOW_SECONDS
-                        failure = PrebuiltFallback(
-                            "llama-server exited during startup:\n" + output
-                        )
+                        failure = PrebuiltFallback("llama-server exited during startup:\n" + output)
                         if (
                             port_attempt < SERVER_PORT_BIND_ATTEMPTS
                             and is_retryable_server_bind_error(
@@ -5684,9 +5435,7 @@ def validate_server(
                             break
                         raise failure
 
-                    payload = json.dumps({"prompt": "a", "n_predict": 1}).encode(
-                        "utf-8"
-                    )
+                    payload = json.dumps({"prompt": "a", "n_predict": 1}).encode("utf-8")
                     request = urllib.request.Request(
                         f"http://127.0.0.1:{port}/completion",
                         data = payload,
@@ -5698,9 +5447,7 @@ def validate_server(
                             response_body = response.read().decode("utf-8", "replace")
                             if status_code == 200:
                                 return
-                            last_error = RuntimeError(
-                                f"unexpected HTTP status {status_code}"
-                            )
+                            last_error = RuntimeError(f"unexpected HTTP status {status_code}")
                     except urllib.error.HTTPError as exc:
                         response_body = exc.read().decode("utf-8", "replace")
                         last_error = exc
@@ -5734,9 +5481,7 @@ def validate_server(
     raise PrebuiltFallback("llama-server validation failed unexpectedly")
 
 
-def collect_system_report(
-    host: HostInfo, choice: AssetChoice | None, install_dir: Path
-) -> str:
+def collect_system_report(host: HostInfo, choice: AssetChoice | None, install_dir: Path) -> str:
     lines = [
         f"platform={host.system} machine={host.machine}",
         f"driver_cuda_version={host.driver_cuda_version}",
@@ -5750,8 +5495,7 @@ def collect_system_report(
     if host.is_linux and host.has_physical_nvidia:
         runtime_lines, runtime_dirs = detected_linux_runtime_lines()
         lines.append(
-            "linux_runtime_lines="
-            + (",".join(runtime_lines) if runtime_lines else "none")
+            "linux_runtime_lines=" + (",".join(runtime_lines) if runtime_lines else "none")
         )
         for runtime_line in ("cuda13", "cuda12"):
             lines.append(
@@ -5780,10 +5524,7 @@ def collect_system_report(
             server_env = binary_env(server_binary, install_dir, host)
             lines.append(
                 "linux_missing_libs="
-                + (
-                    ",".join(linux_missing_libraries(server_binary, env = server_env))
-                    or "none"
-                )
+                + (",".join(linux_missing_libraries(server_binary, env = server_env)) or "none")
             )
             lines.append(
                 "linux_runtime_dirs="
@@ -5791,9 +5532,7 @@ def collect_system_report(
                     ",".join(
                         [
                             part
-                            for part in server_env.get("LD_LIBRARY_PATH", "").split(
-                                os.pathsep
-                            )
+                            for part in server_env.get("LD_LIBRARY_PATH", "").split(os.pathsep)
                             if part
                         ]
                     )
@@ -5801,21 +5540,16 @@ def collect_system_report(
                 )
             )
             try:
-                ldd = run_capture(
-                    ["ldd", str(server_binary)], timeout = 20, env = server_env
-                )
+                ldd = run_capture(["ldd", str(server_binary)], timeout = 20, env = server_env)
                 lines.append("ldd llama-server:")
                 lines.append((ldd.stdout + ldd.stderr).strip())
             except Exception as exc:
                 lines.append(f"ldd error: {exc}")
     elif host.is_windows:
-        lines.append(
-            "windows_runtime_dirs=" + (",".join(windows_runtime_dirs()) or "none")
-        )
+        lines.append("windows_runtime_dirs=" + (",".join(windows_runtime_dirs()) or "none"))
         runtime_lines, runtime_dirs = detected_windows_runtime_lines()
         lines.append(
-            "windows_runtime_lines="
-            + (",".join(runtime_lines) if runtime_lines else "none")
+            "windows_runtime_lines=" + (",".join(runtime_lines) if runtime_lines else "none")
         )
         for runtime_line in ("cuda13", "cuda12"):
             lines.append(
@@ -5840,8 +5574,7 @@ def collect_system_report(
 
 
 def apply_approved_hashes(
-    attempts: Iterable[AssetChoice],
-    checksums: ApprovedReleaseChecksums,
+    attempts: Iterable[AssetChoice], checksums: ApprovedReleaseChecksums
 ) -> list[AssetChoice]:
     def approved_hash_for_attempt(attempt: AssetChoice) -> ApprovedArtifactHash | None:
         candidate_names = [attempt.name]
@@ -5949,8 +5682,7 @@ def preferred_source_archive(
 
 
 def selected_source_archive_metadata(
-    checksums: ApprovedReleaseChecksums,
-    llama_tag: str,
+    checksums: ApprovedReleaseChecksums, llama_tag: str
 ) -> tuple[str, str | None]:
     _source_repo, _source_ref, source_archive, _exact_source = preferred_source_archive(
         checksums, llama_tag
@@ -5961,10 +5693,7 @@ def selected_source_archive_metadata(
 
 
 def resolve_install_attempts(
-    llama_tag: str,
-    host: HostInfo,
-    published_repo: str,
-    published_release_tag: str,
+    llama_tag: str, host: HostInfo, published_repo: str, published_release_tag: str
 ) -> tuple[str, str, list[AssetChoice], ApprovedReleaseChecksums]:
     requested_tag, plans = resolve_install_release_plans(
         llama_tag,
@@ -5987,17 +5716,11 @@ def resolve_install_release_plans(
     max_release_fallbacks: int = DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS,
 ) -> tuple[str, list[InstallReleasePlan]]:
     requested_tag = normalized_requested_llama_tag(llama_tag)
-    allow_older_release_fallback = (
-        requested_tag == "latest" and not published_release_tag
-    )
+    allow_older_release_fallback = requested_tag == "latest" and not published_release_tag
     release_limit = max(1, max_release_fallbacks)
     # macOS may need to walk past a run of too-new prebuilts. Only when the host
     # version is known; otherwise keep the default (cannot tell up front).
-    if (
-        host.is_macos
-        and allow_older_release_fallback
-        and host.macos_version is not None
-    ):
+    if host.is_macos and allow_older_release_fallback and host.macos_version is not None:
         release_limit = max(release_limit, DEFAULT_MAX_MACOS_RELEASE_FALLBACKS)
     plans: list[InstallReleasePlan] = []
     last_error: PrebuiltFallback | None = None
@@ -6013,9 +5736,7 @@ def resolve_install_release_plans(
         try:
             if host.is_linux and host.is_x86_64 and host.has_usable_nvidia:
                 linux_cuda_selection = resolve_linux_cuda_choice(host, bundle)
-                attempts = apply_approved_hashes(
-                    linux_cuda_selection.attempts, checksums
-                )
+                attempts = apply_approved_hashes(linux_cuda_selection.attempts, checksums)
                 if not attempts:
                     raise PrebuiltFallback("no compatible Linux CUDA asset was found")
                 log_lines(linux_cuda_selection.selection_log)
@@ -6117,9 +5838,7 @@ def write_prebuilt_metadata(
         "prebuilt_fallback_used": prebuilt_fallback_used,
         "installed_at_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
     }
-    (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(
-        json.dumps(metadata, indent = 2) + "\n"
-    )
+    (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(json.dumps(metadata, indent = 2) + "\n")
 
 
 def expected_install_fingerprint(
@@ -6236,9 +5955,7 @@ def install_runtime_dir(install_dir: Path, host: HostInfo) -> Path:
     return install_dir / "build" / "bin"
 
 
-def runtime_payload_is_healthy(
-    install_dir: Path, host: HostInfo, choice: AssetChoice
-) -> bool:
+def runtime_payload_is_healthy(install_dir: Path, host: HostInfo, choice: AssetChoice) -> bool:
     runtime_dir = install_runtime_dir(install_dir, host)
     if not runtime_dir.exists():
         return False
@@ -6326,9 +6043,7 @@ def existing_install_matches_choice(
 
 
 def existing_install_matches_plan(
-    install_dir: Path,
-    host: HostInfo,
-    plan: InstallReleasePlan,
+    install_dir: Path, host: HostInfo, plan: InstallReleasePlan
 ) -> bool:
     if not plan.attempts:
         return False
@@ -6360,9 +6075,7 @@ def validate_prebuilt_choice(
         approved_checksums, llama_tag
     )
     if exact_source:
-        log(
-            f"hydrating exact llama.cpp source for {source_repo}@{source_ref} into {install_dir}"
-        )
+        log(f"hydrating exact llama.cpp source for {source_repo}@{source_ref} into {install_dir}")
     else:
         log(f"hydrating upstream llama.cpp source for {llama_tag} into {install_dir}")
     hydrate_source_tree(
@@ -6379,9 +6092,7 @@ def validate_prebuilt_choice(
         exact_source = exact_source,
     )
     log(f"overlaying prebuilt bundle {choice.name} into {install_dir}")
-    server_path, quantize_path = install_from_archives(
-        choice, host, install_dir, work_dir
-    )
+    server_path, quantize_path = install_from_archives(choice, host, install_dir, work_dir)
     preflight_linux_installed_binaries((server_path, quantize_path), install_dir, host)
     preflight_macos_installed_binaries((server_path, quantize_path), install_dir, host)
     ensure_repo_shape(install_dir)
@@ -6539,9 +6250,7 @@ def install_prebuilt(
                     published_repo,
                     published_release_tag,
                 )
-            if release_plans and existing_install_matches_plan(
-                install_dir, host, release_plans[0]
-            ):
+            if release_plans and existing_install_matches_plan(install_dir, host, release_plans[0]):
                 current = release_plans[0]
                 log(
                     "existing llama.cpp install already matches selected release "
@@ -6551,9 +6260,7 @@ def install_prebuilt(
             with tempfile.TemporaryDirectory(prefix = "unsloth-llama-prebuilt-") as tmp:
                 work_dir = Path(tmp)
                 probe_path = work_dir / "stories260K.gguf"
-                download_validation_model(
-                    probe_path, validation_model_cache_path(install_dir)
-                )
+                download_validation_model(probe_path, validation_model_cache_path(install_dir))
                 release_count = len(release_plans)
                 for release_index, plan in enumerate(release_plans):
                     choice = plan.attempts[0]
@@ -6759,9 +6466,7 @@ def main() -> int:
         )
         emit_resolver_output(
             {
-                "requested_tag": normalized_requested_llama_tag(
-                    args.resolve_install_tag
-                ),
+                "requested_tag": normalized_requested_llama_tag(args.resolve_install_tag),
                 "llama_tag": resolved,
             },
             output_format = args.output_format,
@@ -6776,9 +6481,7 @@ def main() -> int:
         )
         emit_resolver_output(
             {
-                "requested_tag": normalized_requested_llama_tag(
-                    args.resolve_source_build
-                ),
+                "requested_tag": normalized_requested_llama_tag(args.resolve_source_build),
                 "source_url": plan.source_url,
                 "source_ref_kind": plan.source_ref_kind,
                 "source_ref": plan.source_ref,
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index da202f7ce6..5ff8e8572b 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -176,7 +176,6 @@ def _detect_rocm_version() -> tuple[int, int] | None:
             )
             if result.returncode == 0:
                 import re
-
                 m = re.search(r"ROCm version:\s*(\d+)\.(\d+)", result.stdout)
                 if m:
                     return int(m.group(1)), int(m.group(2))
@@ -196,11 +195,7 @@ def _detect_rocm_version() -> tuple[int, int] | None:
             if result.returncode == 0:
                 raw = result.stdout.decode().strip().split("\n")[0]
                 parts = raw.split(".")
-                if (
-                    len(parts) >= 2
-                    and parts[0].isdigit()
-                    and parts[1].split("-")[0].isdigit()
-                ):
+                if len(parts) >= 2 and parts[0].isdigit() and parts[1].split("-")[0].isdigit():
                     return int(parts[0]), int(parts[1].split("-")[0])
         except Exception:
             pass
@@ -309,8 +304,7 @@ def _detect_windows_gfx_arch() -> str | None:
                 # findall picks every gcnArchName line so multi-GPU hosts
                 # are enumerable and HIP_VISIBLE_DEVICES selects correctly.
                 _tokens = [
-                    t.strip().lower()
-                    for t in re.findall(r"(?im)^\s*gcnArchName\s*:\s*(\S+)", text)
+                    t.strip().lower() for t in re.findall(r"(?im)^\s*gcnArchName\s*:\s*(\S+)", text)
                 ]
                 _pick = _dedup_pick(_tokens)
                 if _pick:
@@ -612,9 +606,7 @@ def _ensure_rocm_torch() -> None:
         if not _torch_already_rocm:
             index_url = _windows_rocm_index_url(gfx_arch)
             if index_url is None:
-                print(
-                    f"   No AMD Windows torch index for GPU arch {gfx_arch} -- skipping"
-                )
+                print(f"   No AMD Windows torch index for GPU arch {gfx_arch} -- skipping")
                 return
             print(f"   {gfx_arch} (Windows) -- installing torch from {index_url}")
             pip_install(
@@ -688,9 +680,7 @@ def _ensure_rocm_torch() -> None:
     except (OSError, subprocess.TimeoutExpired):
         probe = None
     has_hip_torch = (
-        probe is not None
-        and probe.returncode == 0
-        and probe.stdout.decode().strip() != ""
+        probe is not None and probe.returncode == 0 and probe.stdout.decode().strip() != ""
     )
 
     rocm_torch_ready = has_hip_torch
@@ -714,14 +704,11 @@ def _ensure_rocm_torch() -> None:
             # specific index into gfx_codes, use that gfx; else default to the
             # first listed GPU. Skip the override unless the resolved GPU is
             # Strix.
-            _runtime_gfx = (
-                gfx_codes[_pick_visible_index(len(gfx_codes))] if gfx_codes else None
-            )
+            _runtime_gfx = gfx_codes[_pick_visible_index(len(gfx_codes))] if gfx_codes else None
             if _runtime_gfx in _strix_gfx:
                 _selected_gfx = _runtime_gfx
                 _amd_mirror = (
-                    os.environ.get("UNSLOTH_AMD_ROCM_MIRROR")
-                    or "https://repo.amd.com/rocm/whl"
+                    os.environ.get("UNSLOTH_AMD_ROCM_MIRROR") or "https://repo.amd.com/rocm/whl"
                 ).rstrip("/")
                 _strix_override_url = f"{_amd_mirror}/{_selected_gfx}/"
                 _strix_override_pkgs = (
@@ -782,10 +769,7 @@ def _ensure_rocm_torch() -> None:
             None,
         )
         if tag is None:
-            print(
-                f"   No PyTorch wheel for ROCm {ver[0]}.{ver[1]} -- "
-                f"skipping torch reinstall"
-            )
+            print(f"   No PyTorch wheel for ROCm {ver[0]}.{ver[1]} -- " f"skipping torch reinstall")
         else:
             index_url = f"{_PYTORCH_WHL_BASE}/{tag}"
             print(f"   ROCm {ver[0]}.{ver[1]} -- installing torch from {index_url}")
@@ -922,9 +906,7 @@ CONSTRAINTS = SINGLE_ENV / "constraints.txt"
 LOCAL_DD_UNSTRUCTURED_PLUGIN = (
     SCRIPT_DIR / "backend" / "plugins" / "data-designer-unstructured-seed"
 )
-LOCAL_DD_GITHUB_PLUGIN = (
-    SCRIPT_DIR / "backend" / "plugins" / "data-designer-github-repo-seed"
-)
+LOCAL_DD_GITHUB_PLUGIN = SCRIPT_DIR / "backend" / "plugins" / "data-designer-github-repo-seed"
 
 # Apple Silicon: override mlx-vlm/mlx-lm's transformers pin (see overrides file).
 _MLX_OVERRIDES = SINGLE_ENV / "overrides-darwin-arm64.txt"
@@ -1026,7 +1008,11 @@ def _title(msg: str) -> str:
 _RULE = "\u2500" * 52
 
 
-def _step(label: str, value: str, color_fn = None) -> None:
+def _step(
+    label: str,
+    value: str,
+    color_fn = None,
+) -> None:
     """Print a single step line in the column format."""
     if color_fn is None:
         color_fn = _green
@@ -1046,16 +1032,17 @@ def _progress(label: str) -> None:
     pad = " " * (_COL - len(_LABEL))
     end = "\n" if _STEP >= _TOTAL else ""
     try:
-        sys.stdout.write(
-            f"\r  {_dim(_LABEL)}{pad}[{bar}] {_STEP:2}/{_TOTAL}  {label:<20}{end}"
-        )
+        sys.stdout.write(f"\r  {_dim(_LABEL)}{pad}[{bar}] {_STEP:2}/{_TOTAL}  {label:<20}{end}")
         sys.stdout.flush()
     except OSError:
         pass
 
 
 def run(
-    label: str, cmd: list[str], *, quiet: bool = True
+    label: str,
+    cmd: list[str],
+    *,
+    quiet: bool = True,
 ) -> subprocess.CompletedProcess[bytes]:
     """Run a command; on failure print output and exit."""
     if VERBOSE:
@@ -1107,9 +1094,7 @@ def _build_flash_attn_wheel_url(env: dict[str, str]) -> str | None:
     return flash_attn_wheel_url(env)
 
 
-def _print_optional_install_failure(
-    label: str, result: subprocess.CompletedProcess[str]
-) -> None:
+def _print_optional_install_failure(label: str, result: subprocess.CompletedProcess[str]) -> None:
     _step("warning", f"{label} failed (exit code {result.returncode})", _cyan)
     if result.stdout:
         print(result.stdout.strip())
@@ -1204,9 +1189,7 @@ def _filter_requirements(req: Path, skip: set[str]) -> Path:
     """Return a temp copy of a requirements file with certain packages removed."""
     lines = req.read_text(encoding = "utf-8").splitlines(keepends = True)
     filtered = [
-        line
-        for line in lines
-        if not any(line.strip().lower().startswith(pkg) for pkg in skip)
+        line for line in lines if not any(line.strip().lower().startswith(pkg) for pkg in skip)
     ]
     tmp = tempfile.NamedTemporaryFile(
         mode = "w",
@@ -1416,9 +1399,7 @@ def install_python_stack() -> int:
     if not IS_MACOS and not NO_TORCH:
         base_total += 1  # ROCm torch check (line 1526) -- all non-macOS platforms
         if not IS_WINDOWS:
-            base_total += (
-                2  # flash-attn (line 1620) + ROCm torch final (line 1705) -- Linux only
-            )
+            base_total += 2  # flash-attn (line 1620) + ROCm torch final (line 1705) -- Linux only
     _TOTAL = (base_total - 1) if skip_base else base_total
 
     # 1. Try to use uv for faster installs (must happen before pip upgrade
diff --git a/tests/_zoo_aggressive_cuda_spoof.py b/tests/_zoo_aggressive_cuda_spoof.py
index eaafe445fb..9111aa9519 100644
--- a/tests/_zoo_aggressive_cuda_spoof.py
+++ b/tests/_zoo_aggressive_cuda_spoof.py
@@ -159,7 +159,11 @@ def apply() -> None:
         if _orig is None:
             continue
 
-        def _wrap(*args: Any, _orig = _orig, **kwargs: Any):
+        def _wrap(
+            *args: Any,
+            _orig = _orig,
+            **kwargs: Any,
+        ):
             kwargs.pop("pin_memory", None)
             return _orig(*args, **kwargs)
 
diff --git a/tests/conftest.py b/tests/conftest.py
index 2d7038d5d4..ad58cb9706 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -105,13 +105,11 @@ def _patch_torch_cuda_for_import() -> None:
     CPU like normal."""
     try:
         import torch.cuda.memory as _cuda_memory  # type: ignore
-
         _cuda_memory.mem_get_info = lambda *a, **k: (0, 80 * 1024**3)
     except Exception:
         pass
     try:
         import torch
-
         torch.cuda.get_device_capability = lambda *a, **k: (8, 0)
         torch.cuda.is_bf16_supported = lambda *a, **k: True
     except Exception:
diff --git a/tests/python/conftest.py b/tests/python/conftest.py
index 9129e384e5..f7b125edf6 100644
--- a/tests/python/conftest.py
+++ b/tests/python/conftest.py
@@ -2,9 +2,5 @@
 
 
 def pytest_configure(config):
-    config.addinivalue_line(
-        "markers", "server: heavyweight tests requiring studio venv"
-    )
-    config.addinivalue_line(
-        "markers", "e2e: end-to-end tests requiring network and venv creation"
-    )
+    config.addinivalue_line("markers", "server: heavyweight tests requiring studio venv")
+    config.addinivalue_line("markers", "e2e: end-to-end tests requiring network and venv creation")
diff --git a/tests/python/test_cross_platform_parity.py b/tests/python/test_cross_platform_parity.py
index 7b9868c1f2..6c504579ce 100644
--- a/tests/python/test_cross_platform_parity.py
+++ b/tests/python/test_cross_platform_parity.py
@@ -28,17 +28,11 @@ class TestNoTorchBackendAutoInInstallSh:
         for i, line in enumerate(lines):
             if fallback_start is None and "GPU detection failed" in line:
                 fallback_start = i
-            elif (
-                fallback_start is not None
-                and fallback_end is None
-                and line.strip() == "fi"
-            ):
+            elif fallback_start is not None and fallback_end is None and line.strip() == "fi":
                 fallback_end = i
                 break
         fallback_range = (
-            range(fallback_start or 0, (fallback_end or 0) + 1)
-            if fallback_start
-            else range(0)
+            range(fallback_start or 0, (fallback_end or 0) + 1) if fallback_start else range(0)
         )
 
         matches = [
diff --git a/tests/python/test_dpo_vision_processor_passthrough.py b/tests/python/test_dpo_vision_processor_passthrough.py
index a4f2e2e12a..a320cab935 100644
--- a/tests/python/test_dpo_vision_processor_passthrough.py
+++ b/tests/python/test_dpo_vision_processor_passthrough.py
@@ -33,7 +33,11 @@ class _Tok:
     eos_token_id = 99
     bos_token_id = None
 
-    def __call__(self, t, add_special_tokens = False):
+    def __call__(
+        self,
+        t,
+        add_special_tokens = False,
+    ):
         return {"input_ids": [10]}
 
 
@@ -46,7 +50,12 @@ class _Capture:
         self.last_text = None
         self.last_images = "__sentinel__"
 
-    def __call__(self, images = None, text = None, add_special_tokens = False):
+    def __call__(
+        self,
+        images = None,
+        text = None,
+        add_special_tokens = False,
+    ):
         self.last_text = text
         self.last_images = images
         out = {"input_ids": [[1, 2]]}
diff --git a/tests/python/test_e2e_no_torch_sandbox.py b/tests/python/test_e2e_no_torch_sandbox.py
index f36f69201d..382d0afe4e 100644
--- a/tests/python/test_e2e_no_torch_sandbox.py
+++ b/tests/python/test_e2e_no_torch_sandbox.py
@@ -247,12 +247,8 @@ class TestBeforeAfterImportChain:
             exec(source)
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode != 0
-        ), "BEFORE chat_templates.py should crash without torch"
-        assert (
-            b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
-        )
+        assert result.returncode != 0, "BEFORE chat_templates.py should crash without torch"
+        assert b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
 
     def test_before_data_collators_crashes(self, no_torch_venv, sandbox_dir):
         """BEFORE: data_collators.py with top-level 'import torch' crashes."""
@@ -270,12 +266,8 @@ class TestBeforeAfterImportChain:
             exec(open({str(before_file)!r}).read())
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode != 0
-        ), "BEFORE data_collators.py should crash without torch"
-        assert (
-            b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
-        )
+        assert result.returncode != 0, "BEFORE data_collators.py should crash without torch"
+        assert b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
 
     def test_before_full_import_chain_crashes(self, no_torch_venv, sandbox_dir):
         """BEFORE: full utils/datasets/ package with top-level torch imports crashes."""
@@ -320,12 +312,8 @@ class TestBeforeAfterImportChain:
             from utils.datasets import detect_dataset_format
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode != 0
-        ), "BEFORE full import chain should crash without torch"
-        assert (
-            b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
-        )
+        assert result.returncode != 0, "BEFORE full import chain should crash without torch"
+        assert b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
 
     # -- AFTER: succeeds --
 
@@ -539,9 +527,7 @@ class TestEdgeCasesBrokenTorch:
             print("OK: data_collators works despite broken torch on sys.path")
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode == 0
-        ), f"Should work with broken torch:\n{result.stderr.decode()}"
+        assert result.returncode == 0, f"Should work with broken torch:\n{result.stderr.decode()}"
         assert b"OK:" in result.stdout
 
     def test_torch_import_error_hardware_fallback(self, no_torch_venv, sandbox_dir):
@@ -604,14 +590,10 @@ class TestEdgeCasesBrokenTorch:
             print("OK: detect_hardware returned CPU with fake torch (no CUDA)")
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode == 0
-        ), f"Should fall back to CPU:\n{result.stderr.decode()}"
+        assert result.returncode == 0, f"Should fall back to CPU:\n{result.stderr.decode()}"
         assert b"OK:" in result.stdout
 
-    def test_lazy_torch_fails_at_call_time_not_import_time(
-        self, no_torch_venv, sandbox_dir
-    ):
+    def test_lazy_torch_fails_at_call_time_not_import_time(self, no_torch_venv, sandbox_dir):
         """apply_chat_template_to_dataset is importable without torch.
 
         Calling the alpaca branch triggers the lazy 'from torch.utils.data' inside
@@ -657,9 +639,7 @@ class TestEdgeCasesBrokenTorch:
                 print("OK: call succeeded (unexpected but not a crash)")
         """)
         result = _run_in_sandbox(no_torch_venv, code)
-        assert (
-            result.returncode == 0
-        ), f"Should not crash at import time:\n{result.stderr.decode()}"
+        assert result.returncode == 0, f"Should not crash at import time:\n{result.stderr.decode()}"
         assert b"OK: import succeeded" in result.stdout
 
 
@@ -1011,9 +991,7 @@ class TestInstallPythonStackFiltering:
         source = Path(ips.__file__).read_text(encoding = "utf-8")
 
         # NO_TORCH guard before overrides
-        assert (
-            "if NO_TORCH:" in source
-        ), "NO_TORCH guard not found in install_python_stack.py"
+        assert "if NO_TORCH:" in source, "NO_TORCH guard not found in install_python_stack.py"
 
         # macOS guard for triton
         assert (
@@ -1037,7 +1015,6 @@ def _studio_venv_python() -> Path | None:
 def _server_port() -> int:
     """Find an available port for the test server."""
     import socket
-
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
         s.bind(("", 0))
         return s.getsockname()[1]
@@ -1117,9 +1094,7 @@ class TestLiveServerStartup:
         for _ in range(30):
             time.sleep(1)
             try:
-                resp = urllib.request.urlopen(
-                    f"http://127.0.0.1:{port}/api/health", timeout = 2
-                )
+                resp = urllib.request.urlopen(f"http://127.0.0.1:{port}/api/health", timeout = 2)
                 if resp.status == 200:
                     ready = True
                     break
@@ -1143,12 +1118,8 @@ class TestLiveServerStartup:
                     capture_output = True,
                     timeout = 300,
                 )
-            server_output = stdout.decode(errors = "replace") + stderr.decode(
-                errors = "replace"
-            )
-            pytest.skip(
-                f"Server failed to start within 30 seconds. Output:\n{server_output}"
-            )
+            server_output = stdout.decode(errors = "replace") + stderr.decode(errors = "replace")
+            pytest.skip(f"Server failed to start within 30 seconds. Output:\n{server_output}")
 
         yield proc, port
 
@@ -1192,9 +1163,7 @@ class TestLiveServerStartup:
         import urllib.request
 
         _, port = server_process
-        resp = urllib.request.urlopen(
-            f"http://127.0.0.1:{port}/openapi.json", timeout = 5
-        )
+        resp = urllib.request.urlopen(f"http://127.0.0.1:{port}/openapi.json", timeout = 5)
         spec = json.loads(resp.read())
         assert (
             len(spec.get("paths", {})) >= 20
diff --git a/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py b/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
index 31d86b09a4..3f5f235aae 100644
--- a/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
+++ b/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
@@ -62,7 +62,6 @@ class _RecordingTransformerOk:
 
     def __init__(self, model_name, **kwargs):
         from transformers import AutoModel, AutoProcessor, AutoTokenizer
-
         type(self).last_calls = {
             "model": AutoModel.from_pretrained(model_name),
             "processor": AutoProcessor.from_pretrained(model_name),
@@ -73,7 +72,6 @@ class _RecordingTransformerOk:
 class _RaisingTransformer:
     def __init__(self, *a, **kw):
         from transformers import AutoModel
-
         AutoModel.from_pretrained(a[0] if a else kw.get("model_name_or_path"))
         raise RuntimeError("simulated init failure")
 
@@ -129,18 +127,10 @@ def _build_driver(transformer_class):
             return model if is_requested_model_name(a, kw) else original_model(*a, **kw)
 
         def return_existing_tokenizer(*a, **kw):
-            return (
-                tokenizer
-                if is_requested_model_name(a, kw)
-                else original_tokenizer(*a, **kw)
-            )
+            return tokenizer if is_requested_model_name(a, kw) else original_tokenizer(*a, **kw)
 
         def return_existing_processor(*a, **kw):
-            return (
-                tokenizer
-                if is_requested_model_name(a, kw)
-                else original_processor(*a, **kw)
-            )
+            return tokenizer if is_requested_model_name(a, kw) else original_processor(*a, **kw)
 
         try:
             AutoModel.from_pretrained = return_existing_model
@@ -190,7 +180,6 @@ def test_redirect_passes_through_for_other_model_names():
 
         def __init__(self, model_name, **kw):
             from transformers import AutoModel
-
             type(self).captured = AutoModel.from_pretrained("some-other/aux-model")
 
     driver, *_ = _build_driver(_OtherNameTransformer)
@@ -210,7 +199,6 @@ def test_is_requested_model_name_handles_pathlib_path(tmp_path):
 
         def __init__(self, model_name, **kw):
             from transformers import AutoModel
-
             type(self).last_calls = AutoModel.from_pretrained(pathlib.Path(model_name))
 
     driver, *_ = _build_driver(_PathTransformer)
@@ -228,7 +216,6 @@ def test_is_requested_model_name_trailing_slash_local_path(tmp_path):
 
         def __init__(self, model_name, **kw):
             from transformers import AutoModel
-
             type(self).last_calls = AutoModel.from_pretrained(str(target) + "/")
 
     driver, *_ = _build_driver(_SlashTransformer)
@@ -243,7 +230,6 @@ def test_is_requested_model_name_returns_false_when_no_identifier():
     class _NoNameTransformer:
         def __init__(self, model_name, **kw):
             from transformers import AutoModel
-
             captured["args"] = AutoModel.from_pretrained(some_other_kwarg = "x")
 
     driver, *_ = _build_driver(_NoNameTransformer)
diff --git a/tests/python/test_flash_attn_install_python_stack.py b/tests/python/test_flash_attn_install_python_stack.py
index 49f4350a7b..26ff03505a 100644
--- a/tests/python/test_flash_attn_install_python_stack.py
+++ b/tests/python/test_flash_attn_install_python_stack.py
@@ -33,64 +33,42 @@ class TestHasBlackwellGpu:
 
     def test_returns_true_for_sm_100(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
-            mock.patch.object(
-                wheel_utils.subprocess, "run", return_value = _smi_result("10.0\n")
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
+            mock.patch.object(wheel_utils.subprocess, "run", return_value = _smi_result("10.0\n")),
         ):
             assert wheel_utils.has_blackwell_gpu() is True
 
     def test_returns_true_for_sm_120(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
-            mock.patch.object(
-                wheel_utils.subprocess, "run", return_value = _smi_result("12.0\n")
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
+            mock.patch.object(wheel_utils.subprocess, "run", return_value = _smi_result("12.0\n")),
         ):
             assert wheel_utils.has_blackwell_gpu() is True
 
     def test_returns_true_for_sm_121(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
-            mock.patch.object(
-                wheel_utils.subprocess, "run", return_value = _smi_result("12.1\n")
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
+            mock.patch.object(wheel_utils.subprocess, "run", return_value = _smi_result("12.1\n")),
         ):
             assert wheel_utils.has_blackwell_gpu() is True
 
     def test_returns_false_for_sm_90(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
-            mock.patch.object(
-                wheel_utils.subprocess, "run", return_value = _smi_result("9.0\n")
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
+            mock.patch.object(wheel_utils.subprocess, "run", return_value = _smi_result("9.0\n")),
         ):
             assert wheel_utils.has_blackwell_gpu() is False
 
     def test_returns_false_for_sm_89(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
-            mock.patch.object(
-                wheel_utils.subprocess, "run", return_value = _smi_result("8.9\n")
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
+            mock.patch.object(wheel_utils.subprocess, "run", return_value = _smi_result("8.9\n")),
         ):
             assert wheel_utils.has_blackwell_gpu() is False
 
     def test_mixed_gpus_with_one_blackwell_returns_true(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
             mock.patch.object(
                 wheel_utils.subprocess,
                 "run",
@@ -101,9 +79,7 @@ class TestHasBlackwellGpu:
 
     def test_returns_false_when_nvidia_smi_fails(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
             mock.patch.object(
                 wheel_utils.subprocess,
                 "run",
@@ -114,9 +90,7 @@ class TestHasBlackwellGpu:
 
     def test_returns_false_on_subprocess_timeout(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
             mock.patch.object(
                 wheel_utils.subprocess,
                 "run",
@@ -127,9 +101,7 @@ class TestHasBlackwellGpu:
 
     def test_returns_false_on_malformed_output(self):
         with (
-            mock.patch.object(
-                wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"
-            ),
+            mock.patch.object(wheel_utils.shutil, "which", return_value = "/usr/bin/nvidia-smi"),
             mock.patch.object(
                 wheel_utils.subprocess,
                 "run",
@@ -161,10 +133,7 @@ class TestFlashAttnWheelSelection:
         )
         assert url is not None
         assert "v2.8.1" in url
-        assert (
-            "flash_attn-2.8.1+cu12torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl"
-            in url
-        )
+        assert "flash_attn-2.8.1+cu12torch2.10cxx11abiTRUE-cp313-cp313-linux_x86_64.whl" in url
 
     def test_missing_cuda_major_disables_wheel_lookup(self):
         assert (
@@ -262,7 +231,11 @@ class TestEnsureFlashAttn:
         step_messages: list[tuple[str, str]] = []
         printed_failures: list[str] = []
 
-        def fake_step(label: str, value: str, color_fn = None):
+        def fake_step(
+            label: str,
+            value: str,
+            color_fn = None,
+        ):
             step_messages.append((label, value))
 
         with (
@@ -313,7 +286,11 @@ class TestEnsureFlashAttn:
     def test_wheel_missing_skips_install_at_setup_time(self):
         step_messages: list[tuple[str, str]] = []
 
-        def fake_step(label: str, value: str, color_fn = None):
+        def fake_step(
+            label: str,
+            value: str,
+            color_fn = None,
+        ):
             step_messages.append((label, value))
 
         with (
@@ -339,10 +316,7 @@ class TestEnsureFlashAttn:
             ips._ensure_flash_attn()
 
         mock_install_wheel.assert_not_called()
-        assert (
-            "warning",
-            "No published flash-attn prebuilt wheel found",
-        ) in step_messages
+        assert ("warning", "No published flash-attn prebuilt wheel found") in step_messages
 
     def test_skip_env_disables_setup_install(self):
         with (
@@ -362,7 +336,11 @@ class TestEnsureFlashAttn:
     def test_blackwell_gpu_skips_install_with_warning(self):
         step_messages: list[tuple[str, str]] = []
 
-        def fake_step(label: str, value: str, color_fn = None):
+        def fake_step(
+            label: str,
+            value: str,
+            color_fn = None,
+        ):
             step_messages.append((label, value))
 
         with (
@@ -379,14 +357,16 @@ class TestEnsureFlashAttn:
 
         mock_probe.assert_not_called()
         mock_install_wheel.assert_not_called()
-        assert any(
-            label == "warning" and "Blackwell" in msg for label, msg in step_messages
-        )
+        assert any(label == "warning" and "Blackwell" in msg for label, msg in step_messages)
 
     def test_blackwell_gpu_on_windows_emits_blackwell_warning(self):
         step_messages: list[tuple[str, str]] = []
 
-        def fake_step(label: str, value: str, color_fn = None):
+        def fake_step(
+            label: str,
+            value: str,
+            color_fn = None,
+        ):
             step_messages.append((label, value))
 
         with (
@@ -403,14 +383,16 @@ class TestEnsureFlashAttn:
 
         mock_probe.assert_not_called()
         mock_install_wheel.assert_not_called()
-        assert any(
-            label == "warning" and "Blackwell" in msg for label, msg in step_messages
-        )
+        assert any(label == "warning" and "Blackwell" in msg for label, msg in step_messages)
 
     def test_non_blackwell_windows_does_not_emit_blackwell_warning(self):
         step_messages: list[tuple[str, str]] = []
 
-        def fake_step(label: str, value: str, color_fn = None):
+        def fake_step(
+            label: str,
+            value: str,
+            color_fn = None,
+        ):
             step_messages.append((label, value))
 
         with (
@@ -453,9 +435,7 @@ class TestInstallPythonStackFlashAttnIntegration:
             mock.patch("subprocess.run", side_effect = fake_run),
             mock.patch.object(ips, "_has_usable_nvidia_gpu", return_value = False),
             mock.patch.object(ips, "_has_rocm_gpu", return_value = False),
-            mock.patch.object(
-                ips, "LOCAL_DD_UNSTRUCTURED_PLUGIN", Path("/fake/plugin")
-            ),
+            mock.patch.object(ips, "LOCAL_DD_UNSTRUCTURED_PLUGIN", Path("/fake/plugin")),
             mock.patch("pathlib.Path.is_dir", return_value = True),
             mock.patch("pathlib.Path.is_file", return_value = True),
             mock.patch.dict(os.environ, {"SKIP_STUDIO_BASE": "1"}, clear = False),
diff --git a/tests/python/test_gpu_init_ldconfig_guard.py b/tests/python/test_gpu_init_ldconfig_guard.py
index 081a6132b4..248bb84faa 100644
--- a/tests/python/test_gpu_init_ldconfig_guard.py
+++ b/tests/python/test_gpu_init_ldconfig_guard.py
@@ -19,9 +19,7 @@ def _find_geteuid_guard(tree: ast.AST):
 def test_gpu_init_has_geteuid_guard():
     tree = ast.parse(GPU_INIT.read_text())
     guard = _find_geteuid_guard(tree)
-    assert (
-        guard is not None
-    ), "_gpu_init.py must guard ldconfig recovery on os.geteuid()"
+    assert guard is not None, "_gpu_init.py must guard ldconfig recovery on os.geteuid()"
 
 
 def test_ldconfig_calls_only_inside_geteuid_guard():
diff --git a/tests/python/test_no_torch_filtering.py b/tests/python/test_no_torch_filtering.py
index 29cadf87ae..f7a90fc6a8 100644
--- a/tests/python/test_no_torch_filtering.py
+++ b/tests/python/test_no_torch_filtering.py
@@ -156,9 +156,7 @@ class TestFilterRequirements:
         )
         # First filter Windows packages, then NO_TORCH packages
         intermediate = ips._filter_requirements(req, ips.WINDOWS_SKIP_PACKAGES)
-        result = ips._filter_requirements(
-            Path(intermediate), ips.NO_TORCH_SKIP_PACKAGES
-        )
+        result = ips._filter_requirements(Path(intermediate), ips.NO_TORCH_SKIP_PACKAGES)
         lines = Path(result).read_text(encoding = "utf-8").splitlines()
         non_blank = [l.strip() for l in lines if l.strip()]
         assert non_blank == [
@@ -177,9 +175,7 @@ class TestFilterRequirements:
         result = ips._filter_requirements(req, ips.NO_TORCH_SKIP_PACKAGES)
         lines = Path(result).read_text(encoding = "utf-8").splitlines()
         non_blank = [l.strip() for l in lines if l.strip()]
-        assert non_blank == [
-            "numpy"
-        ], f"VCS URL line should be filtered, got: {non_blank}"
+        assert non_blank == ["numpy"], f"VCS URL line should be filtered, got: {non_blank}"
 
     def test_env_marker_line_filtered(self, tmp_path):
         """Package lines with env markers are still filtered by prefix."""
@@ -193,9 +189,7 @@ class TestFilterRequirements:
         result = ips._filter_requirements(req, ips.NO_TORCH_SKIP_PACKAGES)
         lines = Path(result).read_text(encoding = "utf-8").splitlines()
         non_blank = [l.strip() for l in lines if l.strip()]
-        assert non_blank == [
-            "numpy"
-        ], f"Env marker line should be filtered, got: {non_blank}"
+        assert non_blank == ["numpy"], f"Env marker line should be filtered, got: {non_blank}"
 
     def test_git_plus_url_not_over_matched(self, tmp_path):
         """A git+ URL whose path contains a skip package name but does NOT start with it."""
@@ -247,9 +241,7 @@ class TestRealRequirementsFiltering:
         expected = [
             l
             for l in original
-            if not any(
-                l.strip().lower().startswith(p) for p in ips.NO_TORCH_SKIP_PACKAGES
-            )
+            if not any(l.strip().lower().startswith(p) for p in ips.NO_TORCH_SKIP_PACKAGES)
         ]
         assert filtered == expected, (
             f"Filtered extras.txt should match expected.\n"
@@ -259,9 +251,7 @@ class TestRealRequirementsFiltering:
 
     def test_extras_no_deps_txt_torchcodec_and_dlpack_removed(self):
         """extras-no-deps.txt: torchcodec and torch-c-dlpack-ext must be removed."""
-        result = ips._filter_requirements(
-            EXTRAS_NO_DEPS_TXT, ips.NO_TORCH_SKIP_PACKAGES
-        )
+        result = ips._filter_requirements(EXTRAS_NO_DEPS_TXT, ips.NO_TORCH_SKIP_PACKAGES)
         filtered = self._non_blank_non_comment(Path(result))
         original = self._non_blank_non_comment(EXTRAS_NO_DEPS_TXT)
 
@@ -273,9 +263,7 @@ class TestRealRequirementsFiltering:
         expected = [
             l
             for l in original
-            if not any(
-                l.strip().lower().startswith(p) for p in ips.NO_TORCH_SKIP_PACKAGES
-            )
+            if not any(l.strip().lower().startswith(p) for p in ips.NO_TORCH_SKIP_PACKAGES)
         ]
         assert filtered == expected
 
@@ -291,9 +279,7 @@ class TestRealRequirementsFiltering:
 
     def test_extras_no_deps_txt_trl_preserved(self):
         """trl should survive NO_TORCH filtering in extras-no-deps.txt."""
-        result = ips._filter_requirements(
-            EXTRAS_NO_DEPS_TXT, ips.NO_TORCH_SKIP_PACKAGES
-        )
+        result = ips._filter_requirements(EXTRAS_NO_DEPS_TXT, ips.NO_TORCH_SKIP_PACKAGES)
         filtered_text = Path(result).read_text(encoding = "utf-8").lower()
         assert "trl" in filtered_text, "trl should survive NO_TORCH filtering"
 
@@ -370,7 +356,6 @@ class TestIsMacosConstant:
 
     def test_is_macos_matches_platform(self):
         import sys
-
         expected = sys.platform == "darwin"
         assert ips.IS_MACOS is expected
 
@@ -405,9 +390,7 @@ class TestInstallPythonStackSubprocessMock:
         captured_cmds: list[list[str]] = []
 
         def mock_run(cmd, **kw):
-            captured_cmds.append(
-                list(cmd) if isinstance(cmd, (list, tuple)) else [str(cmd)]
-            )
+            captured_cmds.append(list(cmd) if isinstance(cmd, (list, tuple)) else [str(cmd)])
             return subprocess.CompletedProcess(cmd, 0, b"", b"")
 
         env = {"SKIP_STUDIO_BASE": "1"} if skip_base else {}
@@ -424,9 +407,7 @@ class TestInstallPythonStackSubprocessMock:
             mock.patch.object(ips, "_has_rocm_gpu", return_value = False),
             mock.patch("subprocess.run", side_effect = mock_run),
             mock.patch.object(ips, "_bootstrap_uv", return_value = True),
-            mock.patch.object(
-                ips, "LOCAL_DD_UNSTRUCTURED_PLUGIN", Path("/fake/plugin")
-            ),
+            mock.patch.object(ips, "LOCAL_DD_UNSTRUCTURED_PLUGIN", Path("/fake/plugin")),
             mock.patch("pathlib.Path.is_dir", return_value = True),
             mock.patch("pathlib.Path.is_file", return_value = True),
         ):
@@ -469,9 +450,7 @@ class TestInstallPythonStackSubprocessMock:
         has_extras_nd = self._cmds_contain_file(cmds, "extras-no-deps.txt") or any(
             "-r" in cmd and "tmp" in cmd.lower() for cmd in cmds
         )
-        assert (
-            has_extras_nd
-        ), "extras-no-deps.txt (or its filtered temp) should be called"
+        assert has_extras_nd, "extras-no-deps.txt (or its filtered temp) should be called"
 
     # -- IS_WINDOWS=True + NO_TORCH=True (stacked) --
 
@@ -570,17 +549,13 @@ class TestOverridesSkip:
     def test_no_torch_guard_exists_in_source(self):
         """The install_python_stack source must contain a NO_TORCH guard around overrides."""
         source = Path(ips.__file__).read_text(encoding = "utf-8")
-        assert (
-            "if NO_TORCH:" in source
-        ), "NO_TORCH guard not found in install_python_stack.py"
+        assert "if NO_TORCH:" in source, "NO_TORCH guard not found in install_python_stack.py"
 
     def test_overrides_skipped_when_no_torch(self):
         """With NO_TORCH=True on the module, pip_install should NOT be called for overrides."""
         source = Path(ips.__file__).read_text(encoding = "utf-8")
         overrides_match = re.search(r"if NO_TORCH:.*?overrides", source, re.DOTALL)
-        assert (
-            overrides_match is not None
-        ), "Expected NO_TORCH conditional before overrides install"
+        assert overrides_match is not None, "Expected NO_TORCH conditional before overrides install"
 
 
 # ── install.sh --no-torch flag tests ──────────────────────────────────
@@ -599,33 +574,21 @@ class TestInstallShNoTorchFlag:
 
     def test_no_torch_flag_in_case_statement(self):
         """--no-torch must appear in the flag parser case statement."""
-        assert (
-            "--no-torch)" in self.source
-        ), "--no-torch not found in install.sh flag parser"
+        assert "--no-torch)" in self.source, "--no-torch not found in install.sh flag parser"
 
     def test_no_torch_flag_variable_initialized(self):
         """_NO_TORCH_FLAG must be initialized to false."""
-        assert (
-            "_NO_TORCH_FLAG=false" in self.source
-        ), "_NO_TORCH_FLAG=false not found in install.sh"
+        assert "_NO_TORCH_FLAG=false" in self.source, "_NO_TORCH_FLAG=false not found in install.sh"
 
     def test_skip_torch_variable_exists(self):
         """SKIP_TORCH variable must be defined."""
-        assert (
-            "SKIP_TORCH=false" in self.source
-        ), "SKIP_TORCH=false not found in install.sh"
-        assert (
-            "SKIP_TORCH=true" in self.source
-        ), "SKIP_TORCH=true not found in install.sh"
+        assert "SKIP_TORCH=false" in self.source, "SKIP_TORCH=false not found in install.sh"
+        assert "SKIP_TORCH=true" in self.source, "SKIP_TORCH=true not found in install.sh"
 
     def test_skip_torch_driven_by_flag_and_mac_intel(self):
         """SKIP_TORCH must check both _NO_TORCH_FLAG and MAC_INTEL."""
-        assert (
-            "_NO_TORCH_FLAG" in self.source
-        ), "_NO_TORCH_FLAG not referenced in SKIP_TORCH logic"
-        assert (
-            "MAC_INTEL" in self.source
-        ), "MAC_INTEL not referenced in SKIP_TORCH logic"
+        assert "_NO_TORCH_FLAG" in self.source, "_NO_TORCH_FLAG not referenced in SKIP_TORCH logic"
+        assert "MAC_INTEL" in self.source, "MAC_INTEL not referenced in SKIP_TORCH logic"
 
     def test_unsloth_no_torch_uses_skip_torch(self):
         """UNSLOTH_NO_TORCH must reference $SKIP_TORCH, not $MAC_INTEL."""
@@ -633,18 +596,12 @@ class TestInstallShNoTorchFlag:
 
         matches = re.findall(r'UNSLOTH_NO_TORCH="\$(\w+)"', self.source)
         for var in matches:
-            assert (
-                var == "SKIP_TORCH"
-            ), f"UNSLOTH_NO_TORCH references ${var} instead of $SKIP_TORCH"
+            assert var == "SKIP_TORCH", f"UNSLOTH_NO_TORCH references ${var} instead of $SKIP_TORCH"
 
     def test_cpu_hint_message_exists(self):
         """CPU hint message must exist in install.sh."""
-        assert (
-            "No GPU detected" in self.source
-        ), "CPU hint message not found in install.sh"
-        assert (
-            "--no-torch" in self.source
-        ), "--no-torch suggestion not found in CPU hint"
+        assert "No GPU detected" in self.source, "CPU hint message not found in install.sh"
+        assert "--no-torch" in self.source, "--no-torch suggestion not found in CPU hint"
 
     def test_no_torch_flag_parsing_subprocess(self):
         """--no-torch flag sets _NO_TORCH_FLAG=true (subprocess test)."""
diff --git a/tests/python/test_orpo_processor_text_tokenizer.py b/tests/python/test_orpo_processor_text_tokenizer.py
index 44c4e26a86..9ae205c6b9 100644
--- a/tests/python/test_orpo_processor_text_tokenizer.py
+++ b/tests/python/test_orpo_processor_text_tokenizer.py
@@ -34,7 +34,12 @@ class _Tokenizer:
     def __init__(self):
         self.calls = []
 
-    def __call__(self, text, add_special_tokens = False, **kwargs):
+    def __call__(
+        self,
+        text,
+        add_special_tokens = False,
+        **kwargs,
+    ):
         self.calls.append((text, add_special_tokens, kwargs))
         ids = [ord(c) % 31 + 3 for c in text]
         return {"input_ids": ids, "attention_mask": [1] * len(ids)}
@@ -60,7 +65,11 @@ class _Trainer:
         self.padding_value = 0
 
 
-def _exec_rewritten(function_name, source, extra_ns = None):
+def _exec_rewritten(
+    function_name,
+    source,
+    extra_ns = None,
+):
     rewriter = _load_orpo_rewriter()
     rewritten = rewriter(function_name, source)
     ns = {} if extra_ns is None else dict(extra_ns)
diff --git a/tests/python/test_studio_import_no_torch.py b/tests/python/test_studio_import_no_torch.py
index 5592a282ff..c8b67023f5 100644
--- a/tests/python/test_studio_import_no_torch.py
+++ b/tests/python/test_studio_import_no_torch.py
@@ -23,15 +23,9 @@ from pathlib import Path
 import pytest
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-DATA_COLLATORS = (
-    REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "data_collators.py"
-)
-CHAT_TEMPLATES = (
-    REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "chat_templates.py"
-)
-FORMAT_CONVERSION = (
-    REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "format_conversion.py"
-)
+DATA_COLLATORS = REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "data_collators.py"
+CHAT_TEMPLATES = REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "chat_templates.py"
+FORMAT_CONVERSION = REPO_ROOT / "studio" / "backend" / "utils" / "datasets" / "format_conversion.py"
 
 
 def _has_uv() -> bool:
@@ -72,9 +66,7 @@ def no_torch_venv(request, tmp_path_factory):
         [str(venv_python), "-c", "import torch"],
         capture_output = True,
     )
-    assert (
-        check.returncode != 0
-    ), f"torch should NOT be importable in fresh {py_version} venv"
+    assert check.returncode != 0, f"torch should NOT be importable in fresh {py_version} venv"
 
     return str(venv_python)
 
@@ -223,9 +215,7 @@ class TestDataCollatorsNoTorchVenv:
             capture_output = True,
             timeout = 30,
         )
-        assert (
-            result.returncode == 0
-        ), f"DeepSeekOCRDataCollator failed:\n{result.stderr.decode()}"
+        assert result.returncode == 0, f"DeepSeekOCRDataCollator failed:\n{result.stderr.decode()}"
         assert b"OK: DeepSeekOCRDataCollator instantiated" in result.stdout
 
     def test_dataclass_vlm_collator_instantiable(self, no_torch_venv):
@@ -246,9 +236,7 @@ class TestDataCollatorsNoTorchVenv:
             capture_output = True,
             timeout = 30,
         )
-        assert (
-            result.returncode == 0
-        ), f"VLMDataCollator failed:\n{result.stderr.decode()}"
+        assert result.returncode == 0, f"VLMDataCollator failed:\n{result.stderr.decode()}"
         assert b"OK: VLMDataCollator instantiated" in result.stdout
 
 
@@ -529,12 +517,9 @@ class TestNegativeControls:
                 capture_output = True,
                 timeout = 30,
             )
+            assert result.returncode != 0, "Expected failure when 'import torch' is prepended"
             assert (
-                result.returncode != 0
-            ), "Expected failure when 'import torch' is prepended"
-            assert (
-                b"ModuleNotFoundError" in result.stderr
-                or b"ImportError" in result.stderr
+                b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
             ), f"Expected ImportError, got:\n{result.stderr.decode()}"
         finally:
             os.unlink(temp_file)
@@ -577,6 +562,4 @@ class TestNegativeControls:
             timeout = 30,
         )
         assert result.returncode != 0, "import torch should fail in no-torch venv"
-        assert (
-            b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
-        )
+        assert b"ModuleNotFoundError" in result.stderr or b"ImportError" in result.stderr
diff --git a/tests/python/test_tokenizers_and_torch_constraint.py b/tests/python/test_tokenizers_and_torch_constraint.py
index 4be53d2d03..17f2d17f94 100644
--- a/tests/python/test_tokenizers_and_torch_constraint.py
+++ b/tests/python/test_tokenizers_and_torch_constraint.py
@@ -18,9 +18,7 @@ _TESTS_DIR = pathlib.Path(__file__).resolve().parent.parent  # tests/
 _REPO_ROOT = _TESTS_DIR.parent  # unsloth/
 _INSTALL_SH = _REPO_ROOT / "install.sh"
 _INSTALL_PS1 = _REPO_ROOT / "install.ps1"
-_NO_TORCH_RT = (
-    _REPO_ROOT / "studio" / "backend" / "requirements" / "no-torch-runtime.txt"
-)
+_NO_TORCH_RT = _REPO_ROOT / "studio" / "backend" / "requirements" / "no-torch-runtime.txt"
 
 
 def _read(path: pathlib.Path) -> str:
@@ -45,30 +43,23 @@ class TestStructuralTokenizers:
     def test_tokenizers_present(self):
         """tokenizers must be a standalone package line."""
         pkgs = _lines(_NO_TORCH_RT)
-        bare_names = [
-            p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs
-        ]
+        bare_names = [p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs]
         assert "tokenizers" in bare_names
 
     def test_tokenizers_before_transformers(self):
         """tokenizers should appear before transformers (install order intent)."""
         pkgs = _lines(_NO_TORCH_RT)
-        bare_names = [
-            p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs
-        ]
+        bare_names = [p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs]
         idx_tok = bare_names.index("tokenizers")
         idx_tf = bare_names.index("transformers")
         assert idx_tok < idx_tf, (
-            f"tokenizers at index {idx_tok} should appear before "
-            f"transformers at index {idx_tf}"
+            f"tokenizers at index {idx_tok} should appear before " f"transformers at index {idx_tf}"
         )
 
     def test_torch_not_in_no_torch_file(self):
         """torch itself must NOT be listed in the no-torch requirements."""
         pkgs = _lines(_NO_TORCH_RT)
-        bare_names = [
-            p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs
-        ]
+        bare_names = [p.split(">")[0].split("<")[0].split("!")[0].split("=")[0] for p in pkgs]
         assert "torch" not in bare_names
 
 
@@ -409,9 +400,7 @@ class TestE2ETokenizersFix:
         r = self._pip_install(venv, "--no-deps", "-r", str(_NO_TORCH_RT))
         assert r.returncode == 0, f"Install failed: {r.stderr}"
 
-        result = self._run_python(
-            venv, "from transformers import AutoConfig; print('OK')"
-        )
+        result = self._run_python(venv, "from transformers import AutoConfig; print('OK')")
         assert (
             result.returncode == 0
         ), f"AutoConfig import failed:\nstdout: {result.stdout}\nstderr: {result.stderr}"
@@ -441,22 +430,15 @@ class TestE2ETokenizersFix:
         req_no_tokenizers = tmp_path / "no-tokenizers.txt"
         req_no_tokenizers.write_text(
             "\n".join(
-                line
-                for line in _read(_NO_TORCH_RT).splitlines()
-                if line.strip() != "tokenizers"
+                line for line in _read(_NO_TORCH_RT).splitlines() if line.strip() != "tokenizers"
             ),
             encoding = "utf-8",
         )
         r = self._pip_install(venv, "--no-deps", "-r", str(req_no_tokenizers))
         assert r.returncode == 0, f"Install failed: {r.stderr}"
         result = self._run_python(venv, "from transformers import AutoConfig")
-        assert (
-            result.returncode != 0
-        ), "AutoConfig should fail without tokenizers installed"
-        assert (
-            "tokenizers" in result.stderr.lower()
-            or "ModuleNotFoundError" in result.stderr
-        )
+        assert result.returncode != 0, "AutoConfig should fail without tokenizers installed"
+        assert "tokenizers" in result.stderr.lower() or "ModuleNotFoundError" in result.stderr
 
 
 # ======================================================================
@@ -535,9 +517,7 @@ class TestE2EFullNoTorchSandbox:
         venv = self._create_venv(tmp_path, "full-no-torch")
         r = self._pip_install(venv, "--no-deps", "-r", str(_NO_TORCH_RT))
         assert r.returncode == 0, f"Install failed: {r.stderr}"
-        result = self._run_python(
-            venv, "from transformers import AutoConfig; print('OK')"
-        )
+        result = self._run_python(venv, "from transformers import AutoConfig; print('OK')")
         assert (
             result.returncode == 0
         ), f"AutoConfig failed:\nstdout: {result.stdout}\nstderr: {result.stderr}"
diff --git a/tests/python/test_unsloth_run_tool_policy_resolver.py b/tests/python/test_unsloth_run_tool_policy_resolver.py
index 6aff02494b..6e3e3a722d 100644
--- a/tests/python/test_unsloth_run_tool_policy_resolver.py
+++ b/tests/python/test_unsloth_run_tool_policy_resolver.py
@@ -141,15 +141,11 @@ class TestZeroHost:
 
 
 class TestIsExternalHost:
-    @pytest.mark.parametrize(
-        "host", ["127.0.0.1", "localhost", "::1", "LOCALHOST", "Localhost"]
-    )
+    @pytest.mark.parametrize("host", ["127.0.0.1", "localhost", "::1", "LOCALHOST", "Localhost"])
     def test_loopback_aliases_are_local(self, host):
         assert is_external_host(host) is False
 
-    @pytest.mark.parametrize(
-        "host", ["0.0.0.0", "::", "192.168.1.5", "10.0.0.1", "example.com"]
-    )
+    @pytest.mark.parametrize("host", ["0.0.0.0", "::", "192.168.1.5", "10.0.0.1", "example.com"])
     def test_non_loopback_is_external(self, host):
         assert is_external_host(host) is True
 
diff --git a/tests/qlora/test_hf_qlora_train_and_merge.py b/tests/qlora/test_hf_qlora_train_and_merge.py
index ae975b0266..0892627c46 100644
--- a/tests/qlora/test_hf_qlora_train_and_merge.py
+++ b/tests/qlora/test_hf_qlora_train_and_merge.py
@@ -91,9 +91,7 @@ if __name__ == "__main__":
         print(training_args)
         print(peft_config)
 
-    trainer = setup_trainer(
-        model, tokenizer, dataset, training_args, peft_config = peft_config
-    )
+    trainer = setup_trainer(model, tokenizer, dataset, training_args, peft_config = peft_config)
 
     with header_footer_context("Model"):
         print(type(model.model))
diff --git a/tests/saving/gpt-oss-merge/test_merged_model.py b/tests/saving/gpt-oss-merge/test_merged_model.py
index 48f0ed2d3d..497c74debf 100644
--- a/tests/saving/gpt-oss-merge/test_merged_model.py
+++ b/tests/saving/gpt-oss-merge/test_merged_model.py
@@ -42,9 +42,7 @@ inputs = merged_tokenizer.apply_chat_template(
     reasoning_effort = "low",  # **NEW!** Set reasoning effort to low, medium or high
 ).to(merged_model.device)
 
-_ = merged_model.generate(
-    **inputs, max_new_tokens = 512, streamer = TextStreamer(merged_tokenizer)
-)
+_ = merged_model.generate(**inputs, max_new_tokens = 512, streamer = TextStreamer(merged_tokenizer))
 print("\n✅ Inference complete.")
 
 # --- Final Cleanup ---
@@ -54,7 +52,5 @@ torch.cuda.empty_cache()
 gc.collect()
 
 safe_remove_directory("./gpt-oss-finetuned-merged")
-safe_remove_directory(
-    "./unsloth_compiled_cache"
-)  # Clean up cache created by this process
+safe_remove_directory("./unsloth_compiled_cache")  # Clean up cache created by this process
 print("✅ Final cleanup complete. Exiting inference script.")
diff --git a/tests/saving/gpt-oss-merge/train_and_merge.py b/tests/saving/gpt-oss-merge/train_and_merge.py
index 308d19bfb4..8c76ff9662 100644
--- a/tests/saving/gpt-oss-merge/train_and_merge.py
+++ b/tests/saving/gpt-oss-merge/train_and_merge.py
@@ -28,9 +28,7 @@ tokenizer = None
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
@@ -84,9 +82,7 @@ print("Fine-tuning complete.")
 
 # --- Merge and Save ---
 print("\n💾 Merging and saving the 16-bit model to './gpt-oss-finetuned-merged'...")
-model.save_pretrained_merged(
-    save_directory = "./gpt-oss-finetuned-merged", tokenizer = tokenizer
-)
+model.save_pretrained_merged(save_directory = "./gpt-oss-finetuned-merged", tokenizer = tokenizer)
 print("✅ Model merged and saved.")
 
 # --- Cleanup ---
@@ -96,7 +92,5 @@ torch.cuda.empty_cache()
 gc.collect()
 
 safe_remove_directory("./outputs")
-safe_remove_directory(
-    "./unsloth_compiled_cache"
-)  # Clean up the cache created by this process
+safe_remove_directory("./unsloth_compiled_cache")  # Clean up the cache created by this process
 print("✅ Cleanup complete. Exiting training script.")
diff --git a/tests/saving/language_models/test_merge_4bit_validation.py b/tests/saving/language_models/test_merge_4bit_validation.py
index 343e737710..c889001706 100644
--- a/tests/saving/language_models/test_merge_4bit_validation.py
+++ b/tests/saving/language_models/test_merge_4bit_validation.py
@@ -16,9 +16,7 @@ from tests.utils.cleanup_utils import safe_remove_directory
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
@@ -51,9 +49,7 @@ tokenizer = get_chat_template(
 )
 
 # Load small dataset for quick training
-dataset_train = load_dataset(
-    "allenai/openassistant-guanaco-reformatted", split = "train[:100]"
-)
+dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train[:100]")
 dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
 
 print("✅ Base model loaded successfully!")
diff --git a/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py b/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
index dd0e8c25c6..3f2b811b07 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
@@ -35,15 +35,17 @@ from tests.utils.perplexity_eval import (
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
 
 
-def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit = False):
+def load_and_compute_8bit_ppl(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     """Load model and compute perplexity in subprocess"""
     from unsloth import FastLanguageModel
     from unsloth.chat_templates import get_chat_template
@@ -63,17 +65,13 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
     )
 
     # Load dataset fresh in subprocess
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
-            merged_tokenizer.apply_chat_template(
-                convo, tokenize = False, add_generation_prompt = False
-            )
+            merged_tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
             for convo in convos
         ]
         return {"text": texts}
@@ -130,12 +128,8 @@ if __name__ == "__main__":
 
     from unsloth.chat_templates import standardize_sharegpt
 
-    dataset_train = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "train"
-    )
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train")
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
diff --git a/tests/saving/language_models/test_merge_model_perplexity_mistral.py b/tests/saving/language_models/test_merge_model_perplexity_mistral.py
index 14e657c68a..d17a20d755 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_mistral.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_mistral.py
@@ -30,7 +30,11 @@ from tests.utils.perplexity_eval import (
 )
 
 
-def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit = False):
+def load_and_compute_8bit_ppl(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     """Load model and compute perplexity in subprocess"""
     from unsloth import FastLanguageModel
     from tests.utils.perplexity_eval import ppl_model
@@ -49,9 +53,7 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
     # )
 
     # Load dataset fresh in subprocess
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.
 
@@ -90,10 +92,7 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
             outputs.append(assistant_message)
 
             # Create formatted text
-            text = (
-                alpaca_prompt.format(instruction, user_message, assistant_message)
-                + EOS_TOKEN
-            )
+            text = alpaca_prompt.format(instruction, user_message, assistant_message) + EOS_TOKEN
             texts.append(text)
 
         return {
@@ -186,10 +185,7 @@ if __name__ == "__main__":
             outputs.append(assistant_message)
 
             # Create formatted text
-            text = (
-                alpaca_prompt.format(instruction, user_message, assistant_message)
-                + EOS_TOKEN
-            )
+            text = alpaca_prompt.format(instruction, user_message, assistant_message) + EOS_TOKEN
             texts.append(text)
 
         return {
@@ -199,12 +195,8 @@ if __name__ == "__main__":
             "text": texts,
         }
 
-    dataset_train = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "train"
-    )
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train")
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
diff --git a/tests/saving/language_models/test_merge_model_perplexity_phi_4.py b/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
index bebea8168e..6dbdf36032 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
@@ -35,9 +35,7 @@ from tests.utils.perplexity_eval import (
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {
@@ -45,7 +43,11 @@ def formatting_prompts_func(examples):
     }
 
 
-def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit = False):
+def load_and_compute_8bit_ppl(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     """Load model and compute perplexity in subprocess"""
     from unsloth import FastLanguageModel
     from unsloth.chat_templates import get_chat_template
@@ -65,17 +67,13 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
     )
 
     # Load dataset fresh in subprocess
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
-            merged_tokenizer.apply_chat_template(
-                convo, tokenize = False, add_generation_prompt = False
-            )
+            merged_tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
             for convo in convos
         ]
         return {"text": texts}
@@ -130,12 +128,8 @@ if __name__ == "__main__":
         chat_template = "phi-4",
     )
 
-    dataset_train = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "train"
-    )
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train")
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
diff --git a/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py b/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
index c6da9e2ca6..a0624f0c2c 100644
--- a/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
+++ b/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
@@ -34,15 +34,17 @@ from tests.utils.perplexity_eval import (
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
 
 
-def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit = False):
+def load_and_compute_8bit_ppl(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     """Load model and compute perplexity in subprocess"""
     from unsloth import FastLanguageModel
     from unsloth.chat_templates import get_chat_template
@@ -62,17 +64,13 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
     )
 
     # Load dataset fresh in subprocess
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
-            merged_tokenizer.apply_chat_template(
-                convo, tokenize = False, add_generation_prompt = False
-            )
+            merged_tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
             for convo in convos
         ]
         return {"text": texts}
@@ -129,12 +127,8 @@ if __name__ == "__main__":
 
     from unsloth.chat_templates import standardize_sharegpt
 
-    dataset_train = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "train"
-    )
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train")
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
diff --git a/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py b/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
index d63bb9fe09..0b377eca81 100644
--- a/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
+++ b/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
@@ -78,7 +78,11 @@ def formatting_prompts_func(examples):
     }
 
 
-def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit = False):
+def load_and_compute_8bit_ppl(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     """Load model and compute perplexity in subprocess"""
     from unsloth import FastLanguageModel
     from tests.utils.perplexity_eval import ppl_model
@@ -97,9 +101,7 @@ def load_and_compute_8bit_ppl(result_queue, load_in_4bit = False, load_in_8bit =
     # )
 
     # Load dataset fresh in subprocess
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.
 
@@ -191,12 +193,8 @@ if __name__ == "__main__":
         attn_implementation = attn_implementation,
     )
 
-    dataset_train = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "train"
-    )
-    dataset_ppl = load_dataset(
-        "allenai/openassistant-guanaco-reformatted", split = "eval"
-    )
+    dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train")
+    dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
diff --git a/tests/saving/language_models/test_push_to_hub_merged.py b/tests/saving/language_models/test_push_to_hub_merged.py
index 58d589305a..aa79394556 100644
--- a/tests/saving/language_models/test_push_to_hub_merged.py
+++ b/tests/saving/language_models/test_push_to_hub_merged.py
@@ -36,9 +36,7 @@ from tests.utils.perplexity_eval import (
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
@@ -176,9 +174,7 @@ try:
     print("=== TESTING MODEL DOWNLOAD ===".center(80))
     print("=" * 80 + "\n")
     # Force download even if cached
-    model, tokenizer = FastLanguageModel.from_pretrained(
-        f"{hf_username}/merged_llama_text_model"
-    )
+    model, tokenizer = FastLanguageModel.from_pretrained(f"{hf_username}/merged_llama_text_model")
     success["download"] = True
     print("✅ Model downloaded successfully!")
 except Exception as e:
diff --git a/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py b/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
index 038565d170..38b82c5469 100644
--- a/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
+++ b/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
@@ -36,9 +36,7 @@ from tests.utils.perplexity_eval import (
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
-        tokenizer.apply_chat_template(
-            convo, tokenize = False, add_generation_prompt = False
-        )
+        tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
         for convo in convos
     ]
     return {"text": texts}
@@ -195,9 +193,7 @@ try:
     print("=== TESTING MODEL DOWNLOAD ===".center(80))
     print("=" * 80 + "\n")
     # Force download even if cached
-    model, tokenizer = FastLanguageModel.from_pretrained(
-        f"{hf_username}/merged_llama_text_model"
-    )
+    model, tokenizer = FastLanguageModel.from_pretrained(f"{hf_username}/merged_llama_text_model")
     success["download"] = True
     print("✅ Model downloaded successfully!")
 except Exception as e:
diff --git a/tests/saving/language_models/test_save_merged_grpo_model.py b/tests/saving/language_models/test_save_merged_grpo_model.py
index 67b649305a..b5d8025fcb 100644
--- a/tests/saving/language_models/test_save_merged_grpo_model.py
+++ b/tests/saving/language_models/test_save_merged_grpo_model.py
@@ -24,7 +24,11 @@ max_seq_length = 2048  # Can increase for longer reasoning traces
 lora_rank = 64  # Larger rank = smarter, but slower
 
 
-def evaluate_merged_model(result_queue, load_in_4bit = False, load_in_8bit = False):
+def evaluate_merged_model(
+    result_queue,
+    load_in_4bit = False,
+    load_in_8bit = False,
+):
     from unsloth import FastLanguageModel
     from tests.utils.aime_eval import evaluate_model_aime
 
@@ -176,12 +180,14 @@ def training_run(result_queue):
         avg_length = sum(lengths) / len(lengths)
         min_length = min(lengths)
 
-        print(
-            f"Prompt lengths - Min: {min_length}, Max: {max_length}, Avg: {avg_length:.1f}"
-        )
+        print(f"Prompt lengths - Min: {min_length}, Max: {max_length}, Avg: {avg_length:.1f}")
         return max_length, avg_length
 
-    def extract_unsloth_answer(text, start_tag = "<SOLUTION>", end_tag = "</SOLUTION>"):
+    def extract_unsloth_answer(
+        text,
+        start_tag = "<SOLUTION>",
+        end_tag = "</SOLUTION>",
+    ):
         """Extract answer from Unsloth SOLUTION tags"""
         pattern = re.escape(start_tag) + r"(.*?)" + re.escape(end_tag)
         matches = re.findall(pattern, text, re.DOTALL)
@@ -265,9 +271,7 @@ def training_run(result_queue):
             ground_truth_num = float(norm_ground_truth)
 
             if ground_truth_num != 0:
-                relative_error = abs(extracted_num - ground_truth_num) / abs(
-                    ground_truth_num
-                )
+                relative_error = abs(extracted_num - ground_truth_num) / abs(ground_truth_num)
 
                 if relative_error < 0.01:
                     return True, True, 0.9
@@ -302,10 +306,7 @@ def training_run(result_queue):
         )
 
         responses = [completion[0]["content"] for completion in completions]
-        rewards = [
-            3.0 if re.match(pattern, response, re.DOTALL) else 0.0
-            for response in responses
-        ]
+        rewards = [3.0 if re.match(pattern, response, re.DOTALL) else 0.0 for response in responses]
         return rewards
 
     def match_format_approximately(completions, **kwargs):
@@ -405,9 +406,7 @@ def training_run(result_queue):
                 format_improvement = (
                     result["correct_format_pct"] - base_result["correct_format_pct"]
                 )
-                exact_improvement = (
-                    result["exact_match_pct"] - base_result["exact_match_pct"]
-                )
+                exact_improvement = result["exact_match_pct"] - base_result["exact_match_pct"]
                 plausible_improvement = (
                     result["plausible_match_pct"] - base_result["plausible_match_pct"]
                 )
@@ -440,9 +439,7 @@ def training_run(result_queue):
         if torch.cuda.is_available():
             allocated = torch.cuda.memory_allocated() / 1024**3
             reserved = torch.cuda.memory_reserved() / 1024**3
-            print(
-                f"GPU memory - Allocated: {allocated:.2f} GB, Reserved: {reserved:.2f} GB"
-            )
+            print(f"GPU memory - Allocated: {allocated:.2f} GB, Reserved: {reserved:.2f} GB")
 
     """#### Data Loading and Preparation"""
 
@@ -486,9 +483,7 @@ def training_run(result_queue):
     def formatting_prompts_func(examples):
         convos = examples["prompt"]
         texts = [
-            tokenizer.apply_chat_template(
-                convo, tokenize = False, add_generation_prompt = False
-            )
+            tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False)
             for convo in convos
         ]
         return {
@@ -715,9 +710,7 @@ def training_run(result_queue):
 
     # Save as merged model
     try:
-        model.save_pretrained_merged(
-            "final_merged_model", tokenizer, save_method = "merged_16bit"
-        )
+        model.save_pretrained_merged("final_merged_model", tokenizer, save_method = "merged_16bit")
         print("✅ Merged model saved to: final_merged_model/")
     except Exception as e:
         print(f"⚠️ Could not save merged model: {e}")
diff --git a/tests/saving/test_fix_sentencepiece_gguf_robustness.py b/tests/saving/test_fix_sentencepiece_gguf_robustness.py
index 49bd70fa2f..9c61ca4067 100644
--- a/tests/saving/test_fix_sentencepiece_gguf_robustness.py
+++ b/tests/saving/test_fix_sentencepiece_gguf_robustness.py
@@ -44,9 +44,7 @@ def test_user_defined_special_piece_is_not_retyped(tmp_path):
     ]
     (tmp_path / "tokenizer.model").write_bytes(_build(pieces))
     (tmp_path / "tokenizer.json").write_text(
-        json.dumps(
-            {"added_tokens": [{"id": 2, "content": "<ud_special>", "special": True}]}
-        )
+        json.dumps({"added_tokens": [{"id": 2, "content": "<ud_special>", "special": True}]})
     )
     fix_sentencepiece_gguf(str(tmp_path))
     got = dict(_read(str(tmp_path / "tokenizer.model")))
@@ -87,10 +85,7 @@ def test_save_py_except_clause_is_broad_exception():
     with open(_SAVE_PY) as f:
         tree = ast.parse(f.read())
     for node in ast.walk(tree):
-        if (
-            isinstance(node, ast.FunctionDef)
-            and node.name == "unsloth_save_pretrained_gguf"
-        ):
+        if isinstance(node, ast.FunctionDef) and node.name == "unsloth_save_pretrained_gguf":
             for subnode in ast.walk(node):
                 if isinstance(subnode, ast.Try):
                     body_src = "\n".join(ast.unparse(s) for s in subnode.body)
diff --git a/tests/saving/test_preserve_tokenizer_eos_token.py b/tests/saving/test_preserve_tokenizer_eos_token.py
index 6e2f8c7f9d..2ea40ab778 100644
--- a/tests/saving/test_preserve_tokenizer_eos_token.py
+++ b/tests/saving/test_preserve_tokenizer_eos_token.py
@@ -16,8 +16,7 @@ def _load_preserve_helper():
     helper = next(
         node
         for node in tree.body
-        if isinstance(node, ast.FunctionDef)
-        and node.name == "_preserve_tokenizer_eos_token"
+        if isinstance(node, ast.FunctionDef) and node.name == "_preserve_tokenizer_eos_token"
     )
     module = ast.Module(body = [helper], type_ignores = [])
     ast.fix_missing_locations(module)
@@ -46,9 +45,7 @@ def test_preserve_tokenizer_eos_token_supports_processor_tokenizer(tmp_path):
     preserve = _load_preserve_helper()
     tokenizer_config = tmp_path / "tokenizer_config.json"
     tokenizer_config.write_text(json.dumps({"eos_token": "<eos>"}), encoding = "utf-8")
-    processor = types.SimpleNamespace(
-        tokenizer = types.SimpleNamespace(eos_token = "<turn|>")
-    )
+    processor = types.SimpleNamespace(tokenizer = types.SimpleNamespace(eos_token = "<turn|>"))
 
     preserve(processor, tmp_path)
 
diff --git a/tests/saving/test_save_shell_injection.py b/tests/saving/test_save_shell_injection.py
index c6c2c8fe15..b02748c250 100644
--- a/tests/saving/test_save_shell_injection.py
+++ b/tests/saving/test_save_shell_injection.py
@@ -19,10 +19,7 @@ def _assert_safe_ggml_calls(calls: list[ast.Call]) -> None:
     popen_calls = []
     for call in calls:
         if isinstance(call.func, ast.Attribute) and call.func.attr == "Popen":
-            if (
-                isinstance(call.func.value, ast.Name)
-                and call.func.value.id == "subprocess"
-            ):
+            if isinstance(call.func.value, ast.Name) and call.func.value.id == "subprocess":
                 popen_calls.append(call)
 
     assert popen_calls, "Expected at least one subprocess.Popen call"
@@ -54,9 +51,7 @@ def _assert_safe_ggml_calls(calls: list[ast.Call]) -> None:
 
         assert call.args, "subprocess.Popen must receive argv as a positional argument"
         argv = call.args[0]
-        assert isinstance(
-            argv, ast.List
-        ), "subprocess.Popen must be called with an argv list"
+        assert isinstance(argv, ast.List), "subprocess.Popen must be called with an argv list"
         assert len(argv.elts) == 5, "GGML conversion argv should have five elements"
 
         second_arg = argv.elts[1]
diff --git a/tests/saving/test_unsloth_save.py b/tests/saving/test_unsloth_save.py
index 35fdad6ba0..c7dd712734 100644
--- a/tests/saving/test_unsloth_save.py
+++ b/tests/saving/test_unsloth_save.py
@@ -132,20 +132,14 @@ def test_save_merged_16bit(model, tokenizer, temp_save_dir: str):
         model.config._name_or_path.replace("/", "_"),
     )
 
-    model.save_pretrained_merged(
-        save_path, tokenizer = tokenizer, save_method = "merged_16bit"
-    )
+    model.save_pretrained_merged(save_path, tokenizer = tokenizer, save_method = "merged_16bit")
 
     # Check model files
     assert os.path.isdir(save_path), f"Directory {save_path} does not exist."
-    assert os.path.isfile(
-        os.path.join(save_path, "config.json")
-    ), "config.json not found."
+    assert os.path.isfile(os.path.join(save_path, "config.json")), "config.json not found."
 
     weight_files = [
-        f
-        for f in os.listdir(save_path)
-        if f.endswith(".bin") or f.endswith(".safetensors")
+        f for f in os.listdir(save_path) if f.endswith(".bin") or f.endswith(".safetensors")
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
@@ -160,9 +154,7 @@ def test_save_merged_16bit(model, tokenizer, temp_save_dir: str):
     with open(config_path, "r") as f:
         config = json.load(f)
 
-    assert (
-        "quantization_config" not in config
-    ), "Quantization config not found in the model config."
+    assert "quantization_config" not in config, "Quantization config not found in the model config."
 
     # Store the size of the model files
     total_size = sum(os.path.getsize(os.path.join(save_path, f)) for f in weight_files)
@@ -185,20 +177,14 @@ def test_save_merged_4bit(model, tokenizer, temp_save_dir: str):
         model.config._name_or_path.replace("/", "_"),
     )
 
-    model.save_pretrained_merged(
-        save_path, tokenizer = tokenizer, save_method = "merged_4bit_forced"
-    )
+    model.save_pretrained_merged(save_path, tokenizer = tokenizer, save_method = "merged_4bit_forced")
 
     # Check model files
     assert os.path.isdir(save_path), f"Directory {save_path} does not exist."
-    assert os.path.isfile(
-        os.path.join(save_path, "config.json")
-    ), "config.json not found."
+    assert os.path.isfile(os.path.join(save_path, "config.json")), "config.json not found."
 
     weight_files = [
-        f
-        for f in os.listdir(save_path)
-        if f.endswith(".bin") or f.endswith(".safetensors")
+        f for f in os.listdir(save_path) if f.endswith(".bin") or f.endswith(".safetensors")
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
@@ -223,9 +209,7 @@ def test_save_merged_4bit(model, tokenizer, temp_save_dir: str):
     with open(config_path, "r") as f:
         config = json.load(f)
 
-    assert (
-        "quantization_config" in config
-    ), "Quantization config not found in the model config."
+    assert "quantization_config" in config, "Quantization config not found in the model config."
 
     # Test loading the model from the saved path
     loaded_model, loaded_tokenizer = FastModel.from_pretrained(
@@ -257,29 +241,19 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
     )
 
     weight_files_16bit = [
-        f
-        for f in os.listdir(save_path)
-        if f.endswith(".bin") or f.endswith(".safetensors")
+        f for f in os.listdir(save_path) if f.endswith(".bin") or f.endswith(".safetensors")
     ]
-    total_16bit_size = sum(
-        os.path.getsize(os.path.join(save_path, f)) for f in weight_files_16bit
-    )
+    total_16bit_size = sum(os.path.getsize(os.path.join(save_path, f)) for f in weight_files_16bit)
     save_file_sizes["merged_16bit"][model.config._name_or_path] = total_16bit_size
 
     torchao_save_path = save_path + "-torchao"
 
     # Check model files
-    assert os.path.isdir(
-        torchao_save_path
-    ), f"Directory {torchao_save_path} does not exist."
-    assert os.path.isfile(
-        os.path.join(torchao_save_path, "config.json")
-    ), "config.json not found."
+    assert os.path.isdir(torchao_save_path), f"Directory {torchao_save_path} does not exist."
+    assert os.path.isfile(os.path.join(torchao_save_path, "config.json")), "config.json not found."
 
     weight_files = [
-        f
-        for f in os.listdir(torchao_save_path)
-        if f.endswith(".bin") or f.endswith(".safetensors")
+        f for f in os.listdir(torchao_save_path) if f.endswith(".bin") or f.endswith(".safetensors")
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
@@ -290,9 +264,7 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
         ), f"{file} not found in the save directory."
 
     # Store the size of the model files
-    total_size = sum(
-        os.path.getsize(os.path.join(torchao_save_path, f)) for f in weight_files
-    )
+    total_size = sum(os.path.getsize(os.path.join(torchao_save_path, f)) for f in weight_files)
     save_file_sizes["torchao"][model.config._name_or_path] = total_size
 
     assert (
@@ -304,9 +276,7 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
     with open(config_path, "r") as f:
         config = json.load(f)
 
-    assert (
-        "quantization_config" in config
-    ), "Quantization config not found in the model config."
+    assert "quantization_config" in config, "Quantization config not found in the model config."
 
     # Test loading the model from the saved path
     # can't set `load_in_4bit` to True because the model is torchao quantized
@@ -332,9 +302,7 @@ def test_save_and_inference_torchao(fp16_model_tokenizer, temp_save_dir: str):
 
     print(f"Testing TorchAO save and inference for: {model_name}")
 
-    save_path = os.path.join(
-        temp_save_dir, "torchao_models", model_name.replace("/", "_")
-    )
+    save_path = os.path.join(temp_save_dir, "torchao_models", model_name.replace("/", "_"))
 
     from torchao.quantization import Int8DynamicActivationInt8WeightConfig
 
diff --git a/tests/saving/text_to_speech_models/test_csm.py b/tests/saving/text_to_speech_models/test_csm.py
index c1a892a8d3..dd2287d1d6 100644
--- a/tests/saving/text_to_speech_models/test_csm.py
+++ b/tests/saving/text_to_speech_models/test_csm.py
@@ -134,9 +134,7 @@ import torch
 
 output_audio_path = "csm_audio.wav"
 try:
-    text = (
-        "We just finished fine tuning a text to speech model... and it's pretty good!"
-    )
+    text = "We just finished fine tuning a text to speech model... and it's pretty good!"
     speaker_id = 0
     inputs = processor(f"[{speaker_id}]{text}", add_special_tokens = True).to("cuda")
     audio_values = model.generate(
diff --git a/tests/saving/text_to_speech_models/test_lasa.py b/tests/saving/text_to_speech_models/test_lasa.py
index 804ff512f9..c0c4f80e0e 100644
--- a/tests/saving/text_to_speech_models/test_lasa.py
+++ b/tests/saving/text_to_speech_models/test_lasa.py
@@ -167,9 +167,7 @@ def extract_speech_ids(speech_tokens_str):
 # TTS start!
 with torch.inference_mode():
     with torch.amp.autocast("cuda", dtype = model.dtype):
-        formatted_text = (
-            f"<|TEXT_UNDERSTANDING_START|>{input_text}<|TEXT_UNDERSTANDING_END|>"
-        )
+        formatted_text = f"<|TEXT_UNDERSTANDING_START|>{input_text}<|TEXT_UNDERSTANDING_END|>"
 
         # Tokenize the text
         chat = [
diff --git a/tests/saving/text_to_speech_models/test_orpheus.py b/tests/saving/text_to_speech_models/test_orpheus.py
index bd8bf14979..2915749d99 100644
--- a/tests/saving/text_to_speech_models/test_orpheus.py
+++ b/tests/saving/text_to_speech_models/test_orpheus.py
@@ -152,9 +152,7 @@ for prompt in prompts_:
     all_input_ids.append(input_ids)
 
 start_token = torch.tensor([[128259]], dtype = torch.int64)  # Start of human
-end_tokens = torch.tensor(
-    [[128009, 128260]], dtype = torch.int64
-)  # End of text, End of human
+end_tokens = torch.tensor([[128009, 128260]], dtype = torch.int64)  # End of text, End of human
 
 all_modified_input_ids = []
 for input_ids in all_input_ids:
@@ -165,9 +163,7 @@ for input_ids in all_input_ids:
 
 all_padded_tensors = []
 all_attention_masks = []
-max_length = max(
-    [modified_input_ids.shape[1] for modified_input_ids in all_modified_input_ids]
-)
+max_length = max([modified_input_ids.shape[1] for modified_input_ids in all_modified_input_ids])
 for modified_input_ids in all_modified_input_ids:
     padding = max_length - modified_input_ids.shape[1]
     padded_tensor = torch.cat(
diff --git a/tests/saving/text_to_speech_models/test_whisper.py b/tests/saving/text_to_speech_models/test_whisper.py
index 55f6d98ca0..d0eeb49d17 100644
--- a/tests/saving/text_to_speech_models/test_whisper.py
+++ b/tests/saving/text_to_speech_models/test_whisper.py
@@ -181,13 +181,9 @@ expected_phrases = [
 ]
 
 transcribed_lower = transcribed_text["text"].lower()
-all_phrases_found = all(
-    phrase.lower() in transcribed_lower for phrase in expected_phrases
-)
+all_phrases_found = all(phrase.lower() in transcribed_lower for phrase in expected_phrases)
 
-assert (
-    all_phrases_found
-), f"Expected phrases not found in transcription: {transcribed_text['text']}"
+assert all_phrases_found, f"Expected phrases not found in transcription: {transcribed_text['text']}"
 print("✅ Transcription contains all expected phrases!")
 
 
diff --git a/tests/saving/vision_models/test_index_file_sharded_model.py b/tests/saving/vision_models/test_index_file_sharded_model.py
index 8d107463e0..79a25ec666 100644
--- a/tests/saving/vision_models/test_index_file_sharded_model.py
+++ b/tests/saving/vision_models/test_index_file_sharded_model.py
@@ -138,9 +138,7 @@ try:
             per_device_train_batch_size = 2,
             gradient_accumulation_steps = 4,
             gradient_checkpointing = True,
-            gradient_checkpointing_kwargs = {
-                "use_reentrant": False
-            },  # use reentrant checkpointing
+            gradient_checkpointing_kwargs = {"use_reentrant": False},  # use reentrant checkpointing
             max_grad_norm = 0.3,  # max gradient norm based on QLoRA paper
             warmup_ratio = 0.03,
             # num_train_epochs = 2, # Set this instead of max_steps for full training runs
diff --git a/tests/saving/vision_models/test_push_to_hub_merged.py b/tests/saving/vision_models/test_push_to_hub_merged.py
index fb2af4b4fe..86c7b56cf2 100644
--- a/tests/saving/vision_models/test_push_to_hub_merged.py
+++ b/tests/saving/vision_models/test_push_to_hub_merged.py
@@ -139,9 +139,7 @@ try:
             per_device_train_batch_size = 2,
             gradient_accumulation_steps = 4,
             gradient_checkpointing = True,
-            gradient_checkpointing_kwargs = {
-                "use_reentrant": False
-            },  # use reentrant checkpointing
+            gradient_checkpointing_kwargs = {"use_reentrant": False},  # use reentrant checkpointing
             max_grad_norm = 0.3,  # max gradient norm based on QLoRA paper
             warmup_ratio = 0.03,
             # num_train_epochs = 2, # Set this instead of max_steps for full training runs
diff --git a/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py b/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
index 2b24bc4a32..391d7bacca 100644
--- a/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
+++ b/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
@@ -134,9 +134,7 @@ trainer = SFTTrainer(
         per_device_train_batch_size = 2,
         gradient_accumulation_steps = 4,
         gradient_checkpointing = True,
-        gradient_checkpointing_kwargs = {
-            "use_reentrant": False
-        },  # use reentrant checkpointing
+        gradient_checkpointing_kwargs = {"use_reentrant": False},  # use reentrant checkpointing
         max_grad_norm = 0.3,  # max gradient norm based on QLoRA paper
         warmup_ratio = 0.03,
         # num_train_epochs = 2, # Set this instead of max_steps for full training runs
diff --git a/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py b/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
index 16914707c2..b4812cdfa8 100644
--- a/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
+++ b/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
@@ -134,9 +134,7 @@ trainer = SFTTrainer(
         per_device_train_batch_size = 2,
         gradient_accumulation_steps = 4,
         gradient_checkpointing = True,
-        gradient_checkpointing_kwargs = {
-            "use_reentrant": False
-        },  # use reentrant checkpointing
+        gradient_checkpointing_kwargs = {"use_reentrant": False},  # use reentrant checkpointing
         max_grad_norm = 0.3,  # max gradient norm based on QLoRA paper
         warmup_ratio = 0.03,
         # num_train_epochs = 2, # Set this instead of max_steps for full training runs
diff --git a/tests/security/test_lockfile_supply_chain_audit.py b/tests/security/test_lockfile_supply_chain_audit.py
index 483bb9e763..cec07aea28 100644
--- a/tests/security/test_lockfile_supply_chain_audit.py
+++ b/tests/security/test_lockfile_supply_chain_audit.py
@@ -143,7 +143,6 @@ def test_lockfile_auditor_blocked_versions_match_scanner():
     comment until the next PR factors them into a shared module).
     """
     from scripts import scan_npm_packages as snp
-
     assert (
         lsa.BLOCKED_NPM_VERSIONS == snp.BLOCKED_NPM_VERSIONS
     ), "auditor and scanner BLOCKED_NPM_VERSIONS tables drifted"
@@ -275,9 +274,7 @@ def test_advisory_finding_emitted_as_single_line_annotation(tmp_path):
         npm_lockfiles = [FIXTURES / "clean_lockfile.json"],
         cargo_lockfiles = [lockfile],
     )
-    warning_lines = [
-        line for line in proc.stderr.splitlines() if line.startswith("::warning::")
-    ]
+    warning_lines = [line for line in proc.stderr.splitlines() if line.startswith("::warning::")]
     assert warning_lines, (
         "expected at least one ::warning:: annotation; " f"stderr was:\n{proc.stderr}"
     )
diff --git a/tests/security/test_new_install_scripts.py b/tests/security/test_new_install_scripts.py
index 32340d2536..9a73f4b0d9 100644
--- a/tests/security/test_new_install_scripts.py
+++ b/tests/security/test_new_install_scripts.py
@@ -18,7 +18,12 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 SCRIPT = REPO_ROOT / "scripts" / "check_new_install_scripts.py"
 
 
-def _run(base: Path, head: Path, *, timeout: int = 30) -> subprocess.CompletedProcess:
+def _run(
+    base: Path,
+    head: Path,
+    *,
+    timeout: int = 30,
+) -> subprocess.CompletedProcess:
     return subprocess.run(
         [
             sys.executable,
@@ -103,9 +108,7 @@ def test_new_dep_with_postinstall_exits_1(tmp_path: Path):
     head_pkgs = dict(base_pkgs)
     head_pkgs["node_modules/evil-postinstall"] = {
         "version": "1.0.0",
-        "resolved": (
-            "https://registry.npmjs.org/evil-postinstall/-/evil-postinstall-1.0.0.tgz"
-        ),
+        "resolved": ("https://registry.npmjs.org/evil-postinstall/-/evil-postinstall-1.0.0.tgz"),
         "integrity": "sha512-fake",
         "hasInstallScript": True,
     }
@@ -166,8 +169,7 @@ def test_v2_v3_lockfile_format_support(tmp_path: Path):
         "node_modules/v2-postinstall-dep": {
             "version": "2.0.0",
             "resolved": (
-                "https://registry.npmjs.org/v2-postinstall-dep/-/"
-                "v2-postinstall-dep-2.0.0.tgz"
+                "https://registry.npmjs.org/v2-postinstall-dep/-/v2-postinstall-dep-2.0.0.tgz"
             ),
             "integrity": "sha512-fake",
             "hasInstallScript": True,
@@ -177,8 +179,7 @@ def test_v2_v3_lockfile_format_support(tmp_path: Path):
         "v2-postinstall-dep": {
             "version": "2.0.0",
             "resolved": (
-                "https://registry.npmjs.org/v2-postinstall-dep/-/"
-                "v2-postinstall-dep-2.0.0.tgz"
+                "https://registry.npmjs.org/v2-postinstall-dep/-/v2-postinstall-dep-2.0.0.tgz"
             ),
             "integrity": "sha512-fake",
         },
@@ -187,8 +188,7 @@ def test_v2_v3_lockfile_format_support(tmp_path: Path):
     head = _write(tmp_path / "head.json", _v2_lockfile(head_pkgs, head_deps))
     result = _run(base, head)
     assert result.returncode == 1, (
-        f"expected exit 1 for v2 lockfile, got {result.returncode}; "
-        f"stderr:\n{result.stderr}"
+        f"expected exit 1 for v2 lockfile, got {result.returncode}; " f"stderr:\n{result.stderr}"
     )
     assert "v2-postinstall-dep" in result.stderr
 
diff --git a/tests/security/test_scan_npm_packages.py b/tests/security/test_scan_npm_packages.py
index c632c618b0..fb575b730d 100644
--- a/tests/security/test_scan_npm_packages.py
+++ b/tests/security/test_scan_npm_packages.py
@@ -106,16 +106,10 @@ def test_blocked_npm_versions_complete():
     table = snp.BLOCKED_NPM_VERSIONS
     tanstack_keys = [k for k in table if k.startswith("@tanstack/")]
     assert len(tanstack_keys) == 42, (
-        f"expected 42 @tanstack/* entries, got {len(tanstack_keys)}: "
-        f"{sorted(tanstack_keys)}"
+        f"expected 42 @tanstack/* entries, got {len(tanstack_keys)}: " f"{sorted(tanstack_keys)}"
     )
     assert "@opensearch-project/opensearch" in table
-    assert table["@opensearch-project/opensearch"] == {
-        "3.5.3",
-        "3.6.2",
-        "3.7.0",
-        "3.8.0",
-    }
+    assert table["@opensearch-project/opensearch"] == {"3.5.3", "3.6.2", "3.7.0", "3.8.0"}
     squawk = [k for k in table if k.startswith("@squawk/")]
     assert len(squawk) >= 22, (
         f"expected at least 22 @squawk/* entries (full safedep.io enumeration), "
diff --git a/tests/security/test_scan_packages.py b/tests/security/test_scan_packages.py
index 6ef10f12eb..b35d89ce48 100644
--- a/tests/security/test_scan_packages.py
+++ b/tests/security/test_scan_packages.py
@@ -118,9 +118,7 @@ def test_clean_wheel_no_findings():
         str(FIXTURES / "clean_wheel.whl"),
         "clean_fixture",
     )
-    assert (
-        findings == []
-    ), f"unexpected findings on clean wheel: {[str(f) for f in findings]}"
+    assert findings == [], f"unexpected findings on clean wheel: {[str(f) for f in findings]}"
 
 
 # ---------------------------------------------------------------------------
@@ -245,8 +243,7 @@ def test_archive_corruption_produces_critical_finding(tmp_path):
     assert findings, "scan_archive returned 0 findings on corrupt wheel"
     corrupted = [f for f in findings if f.check == "archive_corrupted"]
     assert corrupted, (
-        "no archive_corrupted finding; got "
-        f"{[(f.severity, f.check) for f in findings]}"
+        "no archive_corrupted finding; got " f"{[(f.severity, f.check) for f in findings]}"
     )
     assert all(f.severity == sp.CRITICAL for f in corrupted)
 
diff --git a/tests/studio/_playwright_robust.py b/tests/studio/_playwright_robust.py
index b190b2b3e1..831153bf96 100644
--- a/tests/studio/_playwright_robust.py
+++ b/tests/studio/_playwright_robust.py
@@ -182,9 +182,7 @@ def wait_for_health(
         # but accept any 200 -- different Studio builds report differently.
         if status == 200:
             if info is not None:
-                info(
-                    f"health pre-flight OK: status=200, body keys={list((body or {}).keys())}"
-                )
+                info(f"health pre-flight OK: status=200, body keys={list((body or {}).keys())}")
             return True
         time.sleep(0.5)
     if info is not None:
@@ -230,9 +228,7 @@ def recover_or_replace_page(
             info(f"recovery: page.is_closed() check failed: {exc!r}")
     if goto_url is not None:
         try:
-            page.goto(
-                goto_url, wait_until = "domcontentloaded", timeout = default_timeout_ms
-            )
+            page.goto(goto_url, wait_until = "domcontentloaded", timeout = default_timeout_ms)
             if settle_networkidle:
                 try:
                     page.wait_for_load_state("networkidle", timeout = 30_000)
diff --git a/tests/studio/install/smoke_test_llama_prebuilt.py b/tests/studio/install/smoke_test_llama_prebuilt.py
index d87537dc94..f7fd58aaa4 100644
--- a/tests/studio/install/smoke_test_llama_prebuilt.py
+++ b/tests/studio/install/smoke_test_llama_prebuilt.py
@@ -15,9 +15,7 @@ INSTALLER_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
 
 
 def load_installer_module():
-    spec = importlib.util.spec_from_file_location(
-        "studio_install_llama_prebuilt", INSTALLER_PATH
-    )
+    spec = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", INSTALLER_PATH)
     if spec is None or spec.loader is None:
         raise RuntimeError(f"unable to load installer module from {INSTALLER_PATH}")
     module = importlib.util.module_from_spec(spec)
@@ -112,17 +110,13 @@ def main() -> int:
             published_release_tag = args.published_release_tag,
         )
         print(f"[smoke] PASS install_dir={install_dir}")
-        print(
-            "[smoke] note=This was a real prebuilt install into an isolated temp directory."
-        )
+        print("[smoke] note=This was a real prebuilt install into an isolated temp directory.")
         return installer.EXIT_SUCCESS
     except SystemExit as exc:
         code = int(exc.code) if isinstance(exc.code, int) else installer.EXIT_ERROR
         if code == installer.EXIT_FALLBACK:
             print(f"[smoke] FALLBACK install_dir={install_dir}")
-            print(
-                "[smoke] note=Prebuilt path failed and would fall back to source build in setup."
-            )
+            print("[smoke] note=Prebuilt path failed and would fall back to source build in setup.")
             print(installer.collect_system_report(host, choice, install_dir))
         else:
             print(f"[smoke] ERROR exit_code={code} install_dir={install_dir}")
diff --git a/tests/studio/install/smoke_test_parallel_studio_home.py b/tests/studio/install/smoke_test_parallel_studio_home.py
index 133591fb33..c4fc250655 100644
--- a/tests/studio/install/smoke_test_parallel_studio_home.py
+++ b/tests/studio/install/smoke_test_parallel_studio_home.py
@@ -86,12 +86,7 @@ def _free_port() -> int:
 
 
 def _run_one_install(
-    label: str,
-    repo: Path,
-    studio_home: Path,
-    fake_home: Path,
-    uv_cache: Path,
-    log_path: Path,
+    label: str, repo: Path, studio_home: Path, fake_home: Path, uv_cache: Path, log_path: Path
 ) -> tuple[str, int]:
     studio_home.mkdir(parents = True, exist_ok = True)
     fake_home.mkdir(parents = True, exist_ok = True)
@@ -159,12 +154,14 @@ def _wait_for_health(port: int, timeout: float) -> dict:
         except (urllib.error.URLError, ConnectionError, OSError) as e:
             last_err = e
         time.sleep(HEALTH_POLL_INTERVAL_S)
-    raise TestFailure(
-        f"port {port}: /api/health never returned 200 (last_err={last_err})"
-    )
+    raise TestFailure(f"port {port}: /api/health never returned 200 (last_err={last_err})")
 
 
-def _http_status(port: int, path: str, timeout: float = 5.0) -> int:
+def _http_status(
+    port: int,
+    path: str,
+    timeout: float = 5.0,
+) -> int:
     url = f"http://127.0.0.1:{port}{path}"
     try:
         with urllib.request.urlopen(url, timeout = timeout) as r:
@@ -211,9 +208,7 @@ def _check_install_layout(label: str, studio_home: Path) -> dict:
         raise TestFailure(f"[{label}] launch-studio.sh kept @@DATA_DIR@@ placeholder")
     expected_data_dir_line = f"DATA_DIR='{studio_home}/share'"
     if expected_data_dir_line not in launcher:
-        raise TestFailure(
-            f"[{label}] launch-studio.sh missing {expected_data_dir_line!r}"
-        )
+        raise TestFailure(f"[{label}] launch-studio.sh missing {expected_data_dir_line!r}")
 
     return {"label": label, "studio_home": str(studio_home), "install_id": install_id}
 
@@ -230,9 +225,7 @@ def _check_fake_home_clean(fake_home: Path) -> None:
     ]
     leaked = [str(p) for p in forbidden if (fake_home / p).exists()]
     if leaked:
-        raise TestFailure(
-            f"redirected HOME picked up persistent install pollution: {leaked}"
-        )
+        raise TestFailure(f"redirected HOME picked up persistent install pollution: {leaked}")
 
 
 def _backend_pid_python(pid: int) -> Path | None:
@@ -256,9 +249,7 @@ def run(n_installs: int, keep: bool) -> int:
 
     repo = PACKAGE_ROOT
     if not (repo / "install.sh").is_file():
-        raise TestFailure(
-            f"install.sh not found at {repo}; " "run from a clone of unslothai/unsloth"
-        )
+        raise TestFailure(f"install.sh not found at {repo}; run from a clone of unslothai/unsloth")
 
     test_root = Path(tempfile.mkdtemp(prefix = "unsloth_studio_clash_"))
     _log(f"test root: {test_root}")
@@ -346,8 +337,7 @@ def run(n_installs: int, keep: bool) -> int:
                 raise TestFailure(f"[{label}] chat_only is not true under --no-torch")
             if health["studio_root_id"] in seen_root_ids:
                 raise TestFailure(
-                    f"[{label}] studio_root_id collision at runtime: "
-                    f"{health['studio_root_id']}"
+                    f"[{label}] studio_root_id collision at runtime: " f"{health['studio_root_id']}"
                 )
             seen_root_ids.add(health["studio_root_id"])
 
@@ -358,9 +348,7 @@ def run(n_installs: int, keep: bool) -> int:
 
             exe = _backend_pid_python(proc.pid)
             if exe is not None:
-                expected_python = (
-                    studio_home / "unsloth_studio" / "bin" / "python"
-                ).resolve()
+                expected_python = (studio_home / "unsloth_studio" / "bin" / "python").resolve()
                 if exe != expected_python:
                     raise TestFailure(
                         f"[{label}] PID {proc.pid} exe={exe}, expected {expected_python}"
@@ -370,10 +358,7 @@ def run(n_installs: int, keep: bool) -> int:
         if len(versions) != 1:
             raise TestFailure(f"version mismatch across installs: {versions}")
 
-        _log(
-            f"PASS: all install + runtime invariants hold "
-            f"(version={next(iter(versions))})"
-        )
+        _log(f"PASS: all install + runtime invariants hold " f"(version={next(iter(versions))})")
         return 0
 
     except TestFailure as e:
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 4a427d6f54..de3808469c 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -12,9 +12,7 @@ import pytest
 
 PACKAGE_ROOT = Path(__file__).resolve().parents[3]
 MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
-SPEC = importlib.util.spec_from_file_location(
-    "studio_install_llama_prebuilt", MODULE_PATH
-)
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
 assert SPEC is not None and SPEC.loader is not None
 INSTALL_LLAMA_PREBUILT = importlib.util.module_from_spec(SPEC)
 sys.modules[SPEC.name] = INSTALL_LLAMA_PREBUILT
@@ -274,12 +272,8 @@ def test_validate_prebuilt_choice_creates_repo_shaped_linux_install(
         "preflight_linux_installed_binaries",
         lambda *args, **kwargs: None,
     )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT, "validate_quantize", lambda *args, **kwargs: None
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT, "validate_server", lambda *args, **kwargs: None
-    )
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "validate_quantize", lambda *args, **kwargs: None)
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "validate_server", lambda *args, **kwargs: None)
 
     host = HostInfo(
         system = "Linux",
@@ -381,9 +375,7 @@ def test_simple_linux_direct_release_uses_published_source_checksums_for_branch(
             INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
                 source_commit
             ): ApprovedArtifactHash(
-                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
-                    source_commit
-                ),
+                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(source_commit),
                 sha256 = "b" * 64,
                 repo = "ggml-org/llama.cpp",
                 kind = "exact-source",
@@ -429,9 +421,7 @@ def test_simple_linux_direct_release_uses_published_source_checksums_for_branch(
     assert plan.approved_checksums.source_commit == source_commit
     assert plan.attempts[0].expected_sha256 == "a" * 64
     source_repo, source_ref, _source_archive, exact_source = (
-        INSTALL_LLAMA_PREBUILT.preferred_source_archive(
-            plan.approved_checksums, plan.llama_tag
-        )
+        INSTALL_LLAMA_PREBUILT.preferred_source_archive(plan.approved_checksums, plan.llama_tag)
     )
     assert source_repo == "ggml-org/llama.cpp"
     assert source_ref == source_commit
@@ -468,9 +458,7 @@ def test_simple_linux_direct_release_honors_torch_cudart_preference(
             ["cuda13", "cuda12"],
             {
                 "cuda13": ["/usr/local/lib/python3.13/site-packages/nvidia/cu13/lib"],
-                "cuda12": [
-                    "/venv/lib/python3.13/site-packages/nvidia/cuda_runtime/lib"
-                ],
+                "cuda12": ["/venv/lib/python3.13/site-packages/nvidia/cuda_runtime/lib"],
             },
         ),
     )
@@ -517,24 +505,20 @@ def test_simple_linux_direct_release_honors_torch_cudart_preference(
     [
         # Missing source_commit.
         (
-            lambda c: setattr(c, "source_commit", None)
-            or setattr(c, "source_commit_short", None),
+            lambda c: setattr(c, "source_commit", None) or setattr(c, "source_commit_short", None),
             "exact source provenance",
         ),
         # source_commit present, but no exact-source archive hash.
         (
             lambda c: c.artifacts.pop(
-                INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
-                    c.source_commit
-                ),
+                INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(c.source_commit),
                 None,
             ),
             "exact source provenance",
         ),
         # source_commit + exact-source archive present, but no source_repo.
         (
-            lambda c: setattr(c, "source_repo", None)
-            or setattr(c, "source_repo_url", None),
+            lambda c: setattr(c, "source_repo", None) or setattr(c, "source_repo_url", None),
             "exact source provenance",
         ),
     ],
@@ -545,9 +529,7 @@ def test_simple_linux_direct_release_honors_torch_cudart_preference(
     ],
 )
 def test_simple_linux_direct_release_rejects_branch_without_exact_source_metadata(
-    monkeypatch: pytest.MonkeyPatch,
-    mutate,
-    expected_match,
+    monkeypatch: pytest.MonkeyPatch, mutate, expected_match
 ):
     source_commit = "25b1bc9c2f9aa0a390b968ee1ffd9ff01340a3fe"
     release = {
@@ -583,9 +565,7 @@ def test_simple_linux_direct_release_rejects_branch_without_exact_source_metadat
             INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
                 source_commit
             ): ApprovedArtifactHash(
-                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
-                    source_commit
-                ),
+                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(source_commit),
                 sha256 = "b" * 64,
                 repo = "ggml-org/llama.cpp",
                 kind = "exact-source",
@@ -646,9 +626,7 @@ def test_simple_linux_direct_release_keeps_legacy_b_tag_path_without_checksums(
     }
 
     def unexpected_checksum_load(repo: str, release_tag: str):
-        raise AssertionError(
-            "legacy b-tag direct releases should not require checksum metadata"
-        )
+        raise AssertionError("legacy b-tag direct releases should not require checksum metadata")
 
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
@@ -741,12 +719,8 @@ def test_validate_prebuilt_choice_creates_repo_shaped_windows_install(
         "preflight_linux_installed_binaries",
         lambda *args, **kwargs: None,
     )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT, "validate_quantize", lambda *args, **kwargs: None
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT, "validate_server", lambda *args, **kwargs: None
-    )
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "validate_quantize", lambda *args, **kwargs: None)
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "validate_server", lambda *args, **kwargs: None)
 
     host = HostInfo(
         system = "Windows",
@@ -809,9 +783,7 @@ def test_validate_prebuilt_choice_creates_repo_shaped_windows_install(
 
 
 def test_activate_install_tree_restores_existing_install_after_activation_failure(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ):
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
@@ -839,9 +811,7 @@ def test_activate_install_tree_restores_existing_install_after_activation_failur
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
         "confirm_install_tree",
-        lambda *_args, **_kwargs: (_ for _ in ()).throw(
-            RuntimeError("activation confirm failed")
-        ),
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(RuntimeError("activation confirm failed")),
     )
 
     with pytest.raises(
@@ -862,9 +832,7 @@ def test_activate_install_tree_restores_existing_install_after_activation_failur
 
 
 def test_activate_install_tree_cleans_all_paths_when_rollback_restore_fails(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ):
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
@@ -892,9 +860,7 @@ def test_activate_install_tree_cleans_all_paths_when_rollback_restore_fails(
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
         "confirm_install_tree",
-        lambda *_args, **_kwargs: (_ for _ in ()).throw(
-            RuntimeError("activation confirm failed")
-        ),
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(RuntimeError("activation confirm failed")),
     )
 
     original_replace = INSTALL_LLAMA_PREBUILT.os.replace
@@ -921,10 +887,7 @@ def test_activate_install_tree_cleans_all_paths_when_rollback_restore_fails(
     captured = capsys.readouterr()
     output = captured.out + captured.err
     assert "rollback after failed activation also failed: restore failed" in output
-    assert (
-        "cleaning staging, install, and rollback paths before source build fallback"
-        in output
-    )
+    assert "cleaning staging, install, and rollback paths before source build fallback" in output
     assert "removing failed install path" in output
     assert "removing rollback path" in output
 
@@ -1108,9 +1071,7 @@ def write_linux_install_shape(install_dir: Path) -> None:
     (runtime_dir / "libggml-base.so.0").write_bytes(b"DLL")
     (runtime_dir / "libggml-cpu-x64.so.0").write_bytes(b"DLL")
     (runtime_dir / "libmtmd.so.0").write_bytes(b"DLL")
-    (install_dir / "convert_hf_to_gguf.py").write_text(
-        "#!/usr/bin/env python3\n", encoding = "utf-8"
-    )
+    (install_dir / "convert_hf_to_gguf.py").write_text("#!/usr/bin/env python3\n", encoding = "utf-8")
     (install_dir / "gguf-py" / "gguf").mkdir(parents = True, exist_ok = True)
 
 
@@ -1134,9 +1095,7 @@ def write_windows_install_shape(
         (runtime_dir / "cudart64_12.dll").write_bytes(b"DLL")
         (runtime_dir / "cublas64_12.dll").write_bytes(b"DLL")
         (runtime_dir / "cublasLt64_12.dll").write_bytes(b"DLL")
-    (install_dir / "convert_hf_to_gguf.py").write_text(
-        "#!/usr/bin/env python3\n", encoding = "utf-8"
-    )
+    (install_dir / "convert_hf_to_gguf.py").write_text("#!/usr/bin/env python3\n", encoding = "utf-8")
     (install_dir / "gguf-py" / "gguf").mkdir(parents = True, exist_ok = True)
 
 
@@ -1159,9 +1118,7 @@ def write_macos_install_shape(
         (runtime_dir / "libggml.0.dylib").write_bytes(b"DLL")
     if include_libmtmd:
         (runtime_dir / "libmtmd.0.dylib").write_bytes(b"DLL")
-    (install_dir / "convert_hf_to_gguf.py").write_text(
-        "#!/usr/bin/env python3\n", encoding = "utf-8"
-    )
+    (install_dir / "convert_hf_to_gguf.py").write_text("#!/usr/bin/env python3\n", encoding = "utf-8")
     (install_dir / "gguf-py" / "gguf").mkdir(parents = True, exist_ok = True)
 
 
@@ -1240,8 +1197,7 @@ def test_existing_install_matches_plan_false_without_fingerprint(tmp_path: Path)
     install_dir.mkdir()
     write_linux_install_shape(install_dir)
     (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(
-        json.dumps({"tag": "b9001", "asset": "llama-b9001-bin-ubuntu-x64.tar.gz"})
-        + "\n",
+        json.dumps({"tag": "b9001", "asset": "llama-b9001-bin-ubuntu-x64.tar.gz"}) + "\n",
         encoding = "utf-8",
     )
 
@@ -1304,9 +1260,7 @@ def test_existing_install_matches_plan_false_with_malformed_metadata(tmp_path: P
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
     write_linux_install_shape(install_dir)
-    (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(
-        "{not-json\n", encoding = "utf-8"
-    )
+    (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text("{not-json\n", encoding = "utf-8")
 
     host = HostInfo(
         system = "Linux",
@@ -1437,9 +1391,7 @@ def test_existing_install_matches_plan_windows_cpu_requires_llama_dll(tmp_path:
 def test_existing_install_matches_plan_windows_cuda_requires_cuda_dll(tmp_path: Path):
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
-    write_windows_install_shape(
-        install_dir, include_llama_dll = True, include_cuda_dll = True
-    )
+    write_windows_install_shape(install_dir, include_llama_dll = True, include_cuda_dll = True)
 
     host = HostInfo(
         system = "Windows",
@@ -1508,9 +1460,7 @@ def test_existing_install_matches_plan_windows_cuda_requires_cuda_dll(tmp_path:
     assert existing_install_matches_plan(install_dir, host, plan) is False
 
 
-def test_existing_install_matches_plan_windows_cuda_paired_requires_cudart(
-    tmp_path: Path,
-):
+def test_existing_install_matches_plan_windows_cuda_paired_requires_cudart(tmp_path: Path):
     """When the choice ships a paired cudart bundle (#5106), the install
     is considered stale unless cudart64_*.dll and cublas64_*.dll are
     actually on disk. Otherwise existing broken installs would keep
@@ -1626,9 +1576,7 @@ def test_existing_install_matches_plan_windows_cuda_paired_requires_cudart(
     assert existing_install_matches_plan(install_dir, host, plan) is False
 
 
-def test_existing_install_matches_plan_windows_cuda_unpaired_skips_cudart_check(
-    tmp_path: Path,
-):
+def test_existing_install_matches_plan_windows_cuda_unpaired_skips_cudart_check(tmp_path: Path):
     """If the choice has no paired runtime archive (manifest dropped it,
     or upstream did not ship cudart), legacy installs without cudart on
     disk must still pass the health check -- otherwise the installer
@@ -1708,9 +1656,7 @@ def test_existing_install_matches_plan_windows_cuda_unpaired_skips_cudart_check(
     assert existing_install_matches_plan(install_dir, host, plan) is True
 
 
-def test_existing_install_fingerprint_changes_when_cudart_pair_added(
-    tmp_path: Path,
-):
+def test_existing_install_fingerprint_changes_when_cudart_pair_added(tmp_path: Path):
     """Existing pre-#5322 Windows CUDA installs (no paired cudart) must
     be treated as stale once the choice gains a runtime archive,
     otherwise the fingerprint match would keep skipping the reinstall
@@ -1985,9 +1931,7 @@ def test_install_prebuilt_skips_download_when_existing_install_matches(
         INSTALL_LLAMA_PREBUILT,
         "download_validation_model",
         lambda *args, **kwargs: (_ for _ in ()).throw(
-            AssertionError(
-                "matching install should skip before validation model download"
-            )
+            AssertionError("matching install should skip before validation model download")
         ),
     )
 
@@ -2503,9 +2447,7 @@ def test_install_prebuilt_same_tag_upstream_failure_uses_older_unsloth_release_p
         (staging_dir / "marker.txt").write_text("ready\n")
         return attempts[0], staging_dir, initial_fallback_used
 
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT, "validate_prebuilt_attempts", fake_validate
-    )
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "validate_prebuilt_attempts", fake_validate)
 
     activated = {}
     monkeypatch.setattr(
@@ -2523,10 +2465,7 @@ def test_install_prebuilt_same_tag_upstream_failure_uses_older_unsloth_release_p
 
     install_prebuilt(install_dir, "latest", "unslothai/llama.cpp", "")
 
-    assert attempted == [
-        ("b9002", "release-2", "upstream"),
-        ("b9001", "release-1", "upstream"),
-    ]
+    assert attempted == [("b9002", "release-2", "upstream"), ("b9001", "release-1", "upstream")]
     assert activated["install_dir"] == install_dir
 
 
@@ -2535,7 +2474,11 @@ def io_bytes(data: bytes):
 
 
 def add_bytes_to_tar(
-    archive: tarfile.TarFile, name: str, data: bytes, *, mode: int = 0o644
+    archive: tarfile.TarFile,
+    name: str,
+    data: bytes,
+    *,
+    mode: int = 0o644,
 ) -> None:
     info = tarfile.TarInfo(name)
     info.size = len(data)
@@ -2550,9 +2493,7 @@ def add_symlink_to_tar(archive: tarfile.TarFile, name: str, target: str) -> None
     archive.addfile(info)
 
 
-def test_existing_install_matches_choice_fails_when_install_tree_incomplete(
-    tmp_path: Path,
-):
+def test_existing_install_matches_choice_fails_when_install_tree_incomplete(tmp_path: Path):
     """confirm_install_tree guard rejects installs missing critical files."""
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
@@ -2641,9 +2582,7 @@ def test_existing_install_matches_choice_fails_when_install_tree_incomplete(
     )
 
 
-def test_existing_install_matches_choice_fails_when_install_tree_incomplete_macos(
-    tmp_path: Path,
-):
+def test_existing_install_matches_choice_fails_when_install_tree_incomplete_macos(tmp_path: Path):
     """confirm_install_tree guard rejects macOS arm64 installs missing critical files."""
     install_dir = tmp_path / "llama.cpp"
     install_dir.mkdir()
@@ -2780,9 +2719,7 @@ def test_paired_runtime_dll_patterns_excludes_executables() -> None:
         assert paired_runtime_dll_patterns(non_windows) == []
 
 
-def test_runtime_overlay_cannot_overwrite_main_archive_payload(
-    tmp_path: Path,
-) -> None:
+def test_runtime_overlay_cannot_overwrite_main_archive_payload(tmp_path: Path) -> None:
     """End-to-end: a malformed runtime archive containing
     ``llama-server.exe`` alongside the real cudart DLLs must NOT
     replace the main archive's ``llama-server.exe``.
@@ -2846,15 +2783,20 @@ def test_runtime_overlay_cannot_overwrite_main_archive_payload(
 
     orig_download = INSTALL_LLAMA_PREBUILT.download_file_verified
 
-    def fake_download(url, target_path, *, expected_sha256 = None, label = None, **kw):
+    def fake_download(
+        url,
+        target_path,
+        *,
+        expected_sha256 = None,
+        label = None,
+        **kw,
+    ):
         src = main_zip if "cudart" not in url else runtime_zip
         _shutil.copy2(src, target_path)
         if expected_sha256:
             actual = hashlib.sha256(Path(target_path).read_bytes()).hexdigest()
             if actual != expected_sha256:
-                raise INSTALL_LLAMA_PREBUILT.PrebuiltFallback(
-                    f"sha256 mismatch on {label}"
-                )
+                raise INSTALL_LLAMA_PREBUILT.PrebuiltFallback(f"sha256 mismatch on {label}")
 
     INSTALL_LLAMA_PREBUILT.download_file_verified = fake_download
     try:
@@ -2866,16 +2808,13 @@ def test_runtime_overlay_cannot_overwrite_main_archive_payload(
     server = release_dir / "llama-server.exe"
     assert server.exists()
     assert server.read_bytes() == b"MAIN-SERVER", (
-        "runtime archive overwrote main llama-server.exe; "
-        f"got {server.read_bytes()!r}"
+        "runtime archive overwrote main llama-server.exe; " f"got {server.read_bytes()!r}"
     )
     for name in ("cudart64_12.dll", "cublas64_12.dll", "cublasLt64_12.dll"):
         assert (release_dir / name).exists(), f"missing {name}"
 
 
-def test_linux_runtime_overlay_copies_llama_tool_impl_libraries(
-    tmp_path: Path,
-) -> None:
+def test_linux_runtime_overlay_copies_llama_tool_impl_libraries(tmp_path: Path) -> None:
     install_from_archives = INSTALL_LLAMA_PREBUILT.install_from_archives
 
     work = tmp_path / "work"
@@ -2939,14 +2878,19 @@ def test_linux_runtime_overlay_copies_llama_tool_impl_libraries(
 
     orig_download = INSTALL_LLAMA_PREBUILT.download_file_verified
 
-    def fake_download(url, target_path, *, expected_sha256 = None, label = None, **kw):
+    def fake_download(
+        url,
+        target_path,
+        *,
+        expected_sha256 = None,
+        label = None,
+        **kw,
+    ):
         _shutil.copy2(bundle, target_path)
         if expected_sha256:
             actual = hashlib.sha256(Path(target_path).read_bytes()).hexdigest()
             if actual != expected_sha256:
-                raise INSTALL_LLAMA_PREBUILT.PrebuiltFallback(
-                    f"sha256 mismatch on {label}"
-                )
+                raise INSTALL_LLAMA_PREBUILT.PrebuiltFallback(f"sha256 mismatch on {label}")
 
     INSTALL_LLAMA_PREBUILT.download_file_verified = fake_download
     try:
@@ -2964,9 +2908,7 @@ def test_linux_runtime_overlay_copies_llama_tool_impl_libraries(
     assert not (runtime_dir / "llama-cli").exists()
 
 
-def test_python_runtime_dirs_covers_cu13_and_library_bin(
-    monkeypatch, tmp_path: Path
-) -> None:
+def test_python_runtime_dirs_covers_cu13_and_library_bin(monkeypatch, tmp_path: Path) -> None:
     """Installer-side runtime DLL discovery must scan the same path
     set as the backend ``_windows_pip_nvidia_dll_dirs``: legacy
     ``nvidia/<pkg>/bin``, current ``nvidia/<pkg>/bin/x86_64``
diff --git a/tests/studio/install/test_llama_pr_force_and_source.py b/tests/studio/install/test_llama_pr_force_and_source.py
index 2d7c038861..17c58cba51 100644
--- a/tests/studio/install/test_llama_pr_force_and_source.py
+++ b/tests/studio/install/test_llama_pr_force_and_source.py
@@ -35,7 +35,10 @@ requires_pwsh = pytest.mark.skipif(not PWSH_AVAILABLE, reason = "pwsh not availa
 # Helpers
 # ---------------------------------------------------------------------------
 def run_bash(
-    script: str, *, timeout: int = 60, env: dict | None = None
+    script: str,
+    *,
+    timeout: int = 60,
+    env: dict | None = None,
 ) -> subprocess.CompletedProcess:
     """Run a bash script fragment and return the CompletedProcess.
     60s default tolerates slow shell startup on heavily-loaded CI
@@ -53,7 +56,10 @@ def run_bash(
 
 
 def run_pwsh(
-    script: str, *, timeout: int = 60, env: dict | None = None
+    script: str,
+    *,
+    timeout: int = 60,
+    env: dict | None = None,
 ) -> subprocess.CompletedProcess:
     """Run a PowerShell script fragment and return the CompletedProcess.
     60s default tolerates slow pwsh startup on heavily-loaded CI
@@ -383,10 +389,7 @@ class TestSourcePatternsSh:
         assert '_DEFAULT_LLAMA_PR_FORCE=""' in self.content
 
     def test_has_default_source(self):
-        assert (
-            '_DEFAULT_LLAMA_SOURCE="https://github.com/ggml-org/llama.cpp"'
-            in self.content
-        )
+        assert '_DEFAULT_LLAMA_SOURCE="https://github.com/ggml-org/llama.cpp"' in self.content
 
     def test_has_pr_force_env_read(self):
         assert "UNSLOTH_LLAMA_PR_FORCE" in self.content
@@ -416,8 +419,7 @@ class TestSourcePatternsSh:
     def test_clone_urls_parameterized_pr_path(self):
         """PR clone path uses ${_LLAMA_SOURCE}.git, not hardcoded URL."""
         pr_clone_idx = self.content.index(
-            'if [ -n "$_LLAMA_PR" ]; then\n'
-            '            run_quiet_no_exit "clone llama.cpp"'
+            'if [ -n "$_LLAMA_PR" ]; then\n            run_quiet_no_exit "clone llama.cpp"'
         )
         else_idx = self.content.index("else\n", pr_clone_idx)
         pr_block = self.content[pr_clone_idx:else_idx]
@@ -437,9 +439,7 @@ class TestSourcePatternsSh:
         lines = self.content.splitlines()
         for i, line in enumerate(lines, 1):
             if "git clone" in line and "ggml-org/llama.cpp.git" in line:
-                pytest.fail(
-                    f"Line {i} has hardcoded ggml-org clone URL: {line.strip()}"
-                )
+                pytest.fail(f"Line {i} has hardcoded ggml-org clone URL: {line.strip()}")
 
 
 # =========================================================================
@@ -456,10 +456,7 @@ class TestSourcePatternsPs1:
         assert '$DefaultLlamaPrForce = ""' in self.content
 
     def test_has_default_source(self):
-        assert (
-            '$DefaultLlamaSource = "https://github.com/ggml-org/llama.cpp"'
-            in self.content
-        )
+        assert '$DefaultLlamaSource = "https://github.com/ggml-org/llama.cpp"' in self.content
 
     def test_has_pr_force_env_read(self):
         assert "$env:UNSLOTH_LLAMA_PR_FORCE" in self.content
@@ -469,10 +466,7 @@ class TestSourcePatternsPs1:
         assert "$LlamaSource = $DefaultLlamaSource" in self.content
 
     def test_release_repo_override_removed(self):
-        assert (
-            "$HelperReleaseRepo = if ($env:UNSLOTH_LLAMA_RELEASE_REPO)"
-            not in self.content
-        )
+        assert "$HelperReleaseRepo = if ($env:UNSLOTH_LLAMA_RELEASE_REPO)" not in self.content
         assert '$HelperReleaseRepo = "ggml-org/llama.cpp"' in self.content
 
     def test_force_compile_skips_prebuilt_resolution_early(self):
@@ -491,9 +485,7 @@ class TestSourcePatternsPs1:
 
     def test_clone_urls_parameterized_pr_path(self):
         """PR clone path uses $LlamaSource.git, not hardcoded URL."""
-        pr_idx = self.content.index(
-            "if ($LlamaPr) {\n", self.content.index("Cloning llama.cpp")
-        )
+        pr_idx = self.content.index("if ($LlamaPr) {\n", self.content.index("Cloning llama.cpp"))
         else_idx = self.content.index("} else {", pr_idx)
         pr_block = self.content[pr_idx:else_idx]
         assert '"$LlamaSource.git"' in pr_block
@@ -511,9 +503,7 @@ class TestSourcePatternsPs1:
         lines = self.content.splitlines()
         for i, line in enumerate(lines, 1):
             if "git clone" in line and "ggml-org/llama.cpp.git" in line:
-                pytest.fail(
-                    f"Line {i} has hardcoded ggml-org clone URL: {line.strip()}"
-                )
+                pytest.fail(f"Line {i} has hardcoded ggml-org clone URL: {line.strip()}")
 
 
 # =========================================================================
diff --git a/tests/studio/install/test_macos_version_compat.py b/tests/studio/install/test_macos_version_compat.py
index 1b87e5af65..7f93b295eb 100644
--- a/tests/studio/install/test_macos_version_compat.py
+++ b/tests/studio/install/test_macos_version_compat.py
@@ -20,9 +20,7 @@ import pytest
 
 PACKAGE_ROOT = Path(__file__).resolve().parents[3]
 MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
-SPEC = importlib.util.spec_from_file_location(
-    "studio_install_llama_prebuilt_macos", MODULE_PATH
-)
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt_macos", MODULE_PATH)
 assert SPEC is not None and SPEC.loader is not None
 ILP = importlib.util.module_from_spec(SPEC)
 sys.modules[SPEC.name] = ILP
@@ -54,7 +52,12 @@ def make_macos_host(macos_version, *, arm64 = True):
     )
 
 
-def thin_macho(minos = (14, 0), *, cputype = _CPU_TYPE_ARM64, build_version = True):
+def thin_macho(
+    minos = (14, 0),
+    *,
+    cputype = _CPU_TYPE_ARM64,
+    build_version = True,
+):
     """Synthesize a minimal little-endian 64-bit Mach-O carrying a macOS
     minimum-version load command."""
     encoded = (minos[0] << 16) | (minos[1] << 8)
@@ -139,10 +142,7 @@ class TestMachoMinimumMacos:
             )
         )
         assert ILP.macho_minimum_macos(path, make_macos_host((14, 0))) == (14, 0)
-        assert ILP.macho_minimum_macos(path, make_macos_host((26, 0), arm64 = False)) == (
-            26,
-            0,
-        )
+        assert ILP.macho_minimum_macos(path, make_macos_host((26, 0), arm64 = False)) == (26, 0)
 
     def test_non_macho_returns_none(self, tmp_path):
         path = tmp_path / "script.sh"
@@ -185,23 +185,17 @@ class TestPreflightMacosInstalledBinaries:
     def test_rejects_too_new_dylib(self, tmp_path):
         install_dir, binaries = self._install_dir(tmp_path, (26, 0))
         with pytest.raises(PrebuiltFallback, match = "newer macOS"):
-            ILP.preflight_macos_installed_binaries(
-                binaries, install_dir, make_macos_host((14, 0))
-            )
+            ILP.preflight_macos_installed_binaries(binaries, install_dir, make_macos_host((14, 0)))
 
     def test_accepts_compatible_prebuilt(self, tmp_path):
         install_dir, binaries = self._install_dir(tmp_path, (14, 0))
         # Must not raise on a macOS 15 host.
-        ILP.preflight_macos_installed_binaries(
-            binaries, install_dir, make_macos_host((15, 5))
-        )
+        ILP.preflight_macos_installed_binaries(binaries, install_dir, make_macos_host((15, 5)))
 
     def test_skips_when_host_version_unknown(self, tmp_path):
         install_dir, binaries = self._install_dir(tmp_path, (26, 0))
         # Unknown host version -> defer to runtime validation, do not raise.
-        ILP.preflight_macos_installed_binaries(
-            binaries, install_dir, make_macos_host(None)
-        )
+        ILP.preflight_macos_installed_binaries(binaries, install_dir, make_macos_host(None))
 
     def test_noop_on_non_macos_host(self, tmp_path):
         install_dir, binaries = self._install_dir(tmp_path, (26, 0))
diff --git a/tests/studio/install/test_pr4562_bugfixes.py b/tests/studio/install/test_pr4562_bugfixes.py
index 34b144a905..5b1c4a44e5 100644
--- a/tests/studio/install/test_pr4562_bugfixes.py
+++ b/tests/studio/install/test_pr4562_bugfixes.py
@@ -29,9 +29,7 @@ import pytest
 # ---------------------------------------------------------------------------
 PACKAGE_ROOT = Path(__file__).resolve().parents[3]
 MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
-SPEC = importlib.util.spec_from_file_location(
-    "studio_install_llama_prebuilt", MODULE_PATH
-)
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
 assert SPEC is not None and SPEC.loader is not None
 MOD = importlib.util.module_from_spec(SPEC)
 sys.modules[SPEC.name] = MOD
@@ -74,7 +72,12 @@ def make_host(*, system: str) -> HostInfo:
 BASH = "/bin/bash"
 
 
-def run_bash(script: str, *, timeout: int = 10, env: dict | None = None) -> str:
+def run_bash(
+    script: str,
+    *,
+    timeout: int = 10,
+    env: dict | None = None,
+) -> str:
     """Run a bash script fragment and return its stdout."""
     run_env = os.environ.copy()
     if env:
@@ -113,9 +116,7 @@ class TestBinaryEnvCrossPlatform:
         env = binary_env(binary_path, install_dir, host)
         ld_dirs = env["LD_LIBRARY_PATH"].split(os.pathsep)
         assert str(bin_dir) in ld_dirs, f"build/bin not in LD_LIBRARY_PATH: {ld_dirs}"
-        assert (
-            str(install_dir) in ld_dirs
-        ), f"install_dir not in LD_LIBRARY_PATH: {ld_dirs}"
+        assert str(install_dir) in ld_dirs, f"install_dir not in LD_LIBRARY_PATH: {ld_dirs}"
 
     def test_linux_binary_parent_comes_before_install_dir(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -134,9 +135,7 @@ class TestBinaryEnvCrossPlatform:
         ld_dirs = env["LD_LIBRARY_PATH"].split(os.pathsep)
         bin_idx = ld_dirs.index(str(bin_dir))
         install_idx = ld_dirs.index(str(install_dir))
-        assert (
-            bin_idx < install_idx
-        ), "binary_path.parent should come before install_dir"
+        assert bin_idx < install_idx, "binary_path.parent should come before install_dir"
 
     def test_linux_deduplicates_when_binary_parent_equals_install_dir(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -195,17 +194,13 @@ class TestBinaryEnvCrossPlatform:
         binary_path.write_bytes(b"MZ")
 
         host = make_host(system = "Windows")
-        monkeypatch.setattr(
-            MOD, "windows_runtime_dirs_for_runtime_line", lambda _rt: []
-        )
+        monkeypatch.setattr(MOD, "windows_runtime_dirs_for_runtime_line", lambda _rt: [])
 
         env = binary_env(binary_path, install_dir, host)
         path_dirs = env["PATH"].split(os.pathsep)
         assert str(bin_dir) in path_dirs, f"build/bin/Release not in PATH: {path_dirs}"
 
-    def test_macos_sets_dyld_library_path(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ):
+    def test_macos_sets_dyld_library_path(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
         install_dir = tmp_path / "llama.cpp"
         install_dir.mkdir(parents = True)
         bin_dir = install_dir / "build" / "bin"
@@ -218,12 +213,8 @@ class TestBinaryEnvCrossPlatform:
 
         env = binary_env(binary_path, install_dir, host)
         dyld_parts = [p for p in env["DYLD_LIBRARY_PATH"].split(os.pathsep) if p]
-        assert (
-            str(bin_dir) in dyld_parts
-        ), f"build/bin not in DYLD_LIBRARY_PATH: {dyld_parts}"
-        assert (
-            str(install_dir) in dyld_parts
-        ), f"install_dir not in DYLD_LIBRARY_PATH: {dyld_parts}"
+        assert str(bin_dir) in dyld_parts, f"build/bin not in DYLD_LIBRARY_PATH: {dyld_parts}"
+        assert str(install_dir) in dyld_parts, f"install_dir not in DYLD_LIBRARY_PATH: {dyld_parts}"
         # binary_path.parent (build/bin) should come before install_dir
         assert dyld_parts.index(str(bin_dir)) < dyld_parts.index(str(install_dir))
 
@@ -303,7 +294,11 @@ class TestResolveRequestedLlamaTag:
     ):
         captured = {}
 
-        def fake_resolve(requested_tag, published_repo, published_release_tag = ""):
+        def fake_resolve(
+            requested_tag,
+            published_repo,
+            published_release_tag = "",
+        ):
             captured["requested_tag"] = requested_tag
             captured["published_repo"] = published_repo
             captured["published_release_tag"] = published_release_tag
@@ -350,9 +345,7 @@ class TestResolveRequestedLlamaTag:
 
 
 class TestFetchJsonRetries:
-    def test_fetch_json_retries_invalid_github_api_json(
-        self, monkeypatch: pytest.MonkeyPatch
-    ):
+    def test_fetch_json_retries_invalid_github_api_json(self, monkeypatch: pytest.MonkeyPatch):
         calls = {"count": 0}
 
         def fake_download_bytes(url, **kwargs):
@@ -593,11 +586,7 @@ class TestLatestTagResolution:
     """)
 
     def _run_resolve(
-        self,
-        tmp_path: Path,
-        requested_tag: str,
-        resolved_tag: str,
-        resolve_status: int,
+        self, tmp_path: Path, requested_tag: str, resolved_tag: str, resolve_status: int
     ) -> str:
         script = self.RESOLVE_TEMPLATE.format(
             requested_tag = requested_tag,
@@ -691,10 +680,7 @@ class TestSourceCodePatterns:
         content = SETUP_SH.read_text()
         assert "--resolve-source-build" not in content
         assert "--resolve-install-tag" not in content
-        assert (
-            '--resolve-llama-tag latest --published-repo "ggml-org/llama.cpp"'
-            in content
-        )
+        assert '--resolve-llama-tag latest --published-repo "ggml-org/llama.cpp"' in content
         assert "--output-format json" in content
         assert "_RESOLVED_SOURCE_URL" in content
         assert "_RESOLVED_SOURCE_REF_KIND" in content
@@ -758,9 +744,7 @@ class TestSourceCodePatterns:
         # Delivered via NVCC_PREPEND_FLAGS (covers the configure-time compiler
         # probe too), not embedded in the word-split CMAKE_ARGS string.
         assert "export NVCC_PREPEND_FLAGS=" in content
-        cmake_args_lines = [
-            line for line in content.splitlines() if "CMAKE_ARGS=" in line
-        ]
+        cmake_args_lines = [line for line in content.splitlines() if "CMAKE_ARGS=" in line]
         assert all(
             "-allow-unsupported-compiler" not in line for line in cmake_args_lines
         ), "flag must stay out of CMAKE_ARGS (bash word-splitting safety)"
@@ -776,9 +760,7 @@ class TestSourceCodePatterns:
         # Delivered via the process environment, not the $CmakeArgs array, so it
         # reaches both the configure-time compiler probe and `cmake --build`.
         assert "$env:NVCC_PREPEND_FLAGS" in content
-        cmake_args_lines = [
-            line for line in content.splitlines() if "$CmakeArgs +=" in line
-        ]
+        cmake_args_lines = [line for line in content.splitlines() if "$CmakeArgs +=" in line]
         assert all(
             "-allow-unsupported-compiler" not in line for line in cmake_args_lines
         ), "flag must not be pushed into the $CmakeArgs array"
@@ -794,15 +776,10 @@ class TestSourceCodePatterns:
 
     def test_macos_arm64_cpu_fallback_args_exclude_rpath(self):
         """CPU fallback args must NOT contain Metal-only RPATH flags at runtime."""
-        script = (
-            '_IS_MACOS_ARM64=true\nNVCC_PATH=""\nGPU_BACKEND=""\n'
-            + _GPU_BACKEND_FRAGMENT
-        )
+        script = '_IS_MACOS_ARM64=true\nNVCC_PATH=""\nGPU_BACKEND=""\n' + _GPU_BACKEND_FRAGMENT
         output = run_bash(script)
         fallback_line = next(
-            line
-            for line in output.splitlines()
-            if line.startswith("CPU_FALLBACK_CMAKE_ARGS=")
+            line for line in output.splitlines() if line.startswith("CPU_FALLBACK_CMAKE_ARGS=")
         )
         assert "-DGGML_METAL=OFF" in fallback_line
         assert (
@@ -823,8 +800,7 @@ class TestSourceCodePatterns:
         assert (
             "x86_64"
             not in content[
-                content.find("-DGGML_METAL=ON") - 200 : content.find("-DGGML_METAL=ON")
-                + 200
+                content.find("-DGGML_METAL=ON") - 200 : content.find("-DGGML_METAL=ON") + 200
             ]
         )
 
@@ -854,9 +830,7 @@ class TestSourceCodePatterns:
                 # Allow git pull in other contexts
                 context = "\n".join(lines[max(0, i - 5) : i + 5])
                 if "LlamaCppDir" in context:
-                    pytest.fail(
-                        f"Found 'git pull' in llama.cpp build section at line {i+1}"
-                    )
+                    pytest.fail(f"Found 'git pull' in llama.cpp build section at line {i+1}")
 
     def test_setup_ps1_prebuilt_install_uses_simple_policy_only(self):
         """PS1 prebuilt path should use the simplified helper install entrypoint."""
@@ -883,8 +857,7 @@ class TestSourceCodePatterns:
         assert "--resolve-source-build" not in content
         assert "--resolve-install-tag" not in content
         assert (
-            '"--resolve-llama-tag", "latest", "--published-repo", "ggml-org/llama.cpp"'
-            in content
+            '"--resolve-llama-tag", "latest", "--published-repo", "ggml-org/llama.cpp"' in content
         )
         assert '--output-format", "json"' in content
         assert "$ResolvedSourceUrl" in content
@@ -898,10 +871,7 @@ class TestSourceCodePatterns:
         block = content[max(0, install_idx - 800) : install_idx + 800]
         assert "$PSNativeCommandUseErrorActionPreference = $false" in block
         assert "$restoreNativeErrorPreference = $true" in block
-        assert (
-            "$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreference"
-            in block
-        )
+        assert "$PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreference" in block
 
     def test_setup_ps1_helper_disables_error_action_abort(self):
         """Helper resolution should suppress terminating NativeCommandError on PS 5.1."""
@@ -922,9 +892,7 @@ class TestSourceCodePatterns:
         """The unconstrained nvcc fallback should not sort toolkit dirs lexicographically."""
         content = SETUP_PS1.read_text()
         assert "Sort-Object Name | Select-Object -Last 1" not in content
-        assert (
-            "Sort-Object { [version]($_.Name -replace '^v','') } -Descending" in content
-        )
+        assert "Sort-Object { [version]($_.Name -replace '^v','') } -Descending" in content
 
     def test_binary_env_linux_has_binary_parent(self):
         """The Linux branch of binary_env should include binary_path.parent."""
@@ -985,10 +953,7 @@ class TestMacOSMetalBuildLogic:
 
     def test_macos_arm64_cmake_args_contain_metal_flags(self):
         """macOS arm64 should enable Metal, not CUDA."""
-        script = (
-            '_IS_MACOS_ARM64=true\nNVCC_PATH=""\nGPU_BACKEND=""\n'
-            + _GPU_BACKEND_FRAGMENT
-        )
+        script = '_IS_MACOS_ARM64=true\nNVCC_PATH=""\nGPU_BACKEND=""\n' + _GPU_BACKEND_FRAGMENT
         output = run_bash(script)
         assert "-DGGML_METAL=ON" in output
         assert "-DGGML_CUDA=ON" not in output
@@ -996,10 +961,7 @@ class TestMacOSMetalBuildLogic:
 
     def test_intel_macos_no_metal_flags(self):
         """Intel macOS (not arm64) should not get Metal flags."""
-        script = (
-            '_IS_MACOS_ARM64=false\nNVCC_PATH=""\nGPU_BACKEND=""\n'
-            + _GPU_BACKEND_FRAGMENT
-        )
+        script = '_IS_MACOS_ARM64=false\nNVCC_PATH=""\nGPU_BACKEND=""\n' + _GPU_BACKEND_FRAGMENT
         output = run_bash(script)
         assert "-DGGML_METAL=ON" not in output
         assert "BUILD_DESC=building (CPU)" in output
@@ -1085,18 +1047,14 @@ class TestMacOSMetalBuildLogic:
         # Verify cmake args: first call has Metal ON, second has Metal OFF
         calls = calls_file.read_text().splitlines()
         assert len(calls) >= 2, f"Expected >= 2 cmake calls, got {len(calls)}"
-        assert (
-            "-DGGML_METAL=ON" in calls[0]
-        ), f"First cmake call should have Metal ON: {calls[0]}"
+        assert "-DGGML_METAL=ON" in calls[0], f"First cmake call should have Metal ON: {calls[0]}"
         assert (
             "-DGGML_METAL=OFF" in calls[1]
         ), f"Second cmake call should have Metal OFF: {calls[1]}"
         assert (
             "-DGGML_METAL=ON" not in calls[1]
         ), f"Second cmake call should NOT have Metal ON: {calls[1]}"
-        assert (
-            "@loader_path" not in calls[1]
-        ), f"CPU fallback should not have RPATH: {calls[1]}"
+        assert "@loader_path" not in calls[1], f"CPU fallback should not have RPATH: {calls[1]}"
         assert (
             "-DCMAKE_BUILD_WITH_INSTALL_RPATH=ON" not in calls[1]
         ), f"CPU fallback should not have RPATH build flag: {calls[1]}"
@@ -1204,9 +1162,7 @@ class TestMacOSMetalBuildLogic:
         # Third call: re-configure with Metal OFF and no RPATH flags
         assert "-DGGML_METAL=OFF" in calls[2]
         assert "-DGGML_METAL=ON" not in calls[2]
-        assert (
-            "@loader_path" not in calls[2]
-        ), f"CPU fallback should not have RPATH: {calls[2]}"
+        assert "@loader_path" not in calls[2], f"CPU fallback should not have RPATH: {calls[2]}"
         assert (
             "-DCMAKE_BUILD_WITH_INSTALL_RPATH=ON" not in calls[2]
         ), f"CPU fallback should not have RPATH build flag: {calls[2]}"
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 4aa7fb3a34..bcfc42c69f 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -40,9 +40,7 @@ _normalize_forwarded_gfx = prebuilt_mod._normalize_forwarded_gfx
 
 # install_python_stack.py
 _STACK_PATH = PACKAGE_ROOT / "studio" / "install_python_stack.py"
-_STACK_SPEC = importlib.util.spec_from_file_location(
-    "studio_install_python_stack", _STACK_PATH
-)
+_STACK_SPEC = importlib.util.spec_from_file_location("studio_install_python_stack", _STACK_PATH)
 assert _STACK_SPEC is not None and _STACK_SPEC.loader is not None
 stack_mod = importlib.util.module_from_spec(_STACK_SPEC)
 sys.modules[_STACK_SPEC.name] = stack_mod
@@ -304,9 +302,7 @@ class TestResolveUpstreamAssetChoice:
     def test_rocm_linux_no_prebuilt_falls_back(self, mock_assets):
         """AMD ROCm host should fall back to source build when no ROCm prebuilt exists."""
         # Remove the ROCm asset from available assets
-        assets_without_rocm = {
-            k: v for k, v in UPSTREAM_ASSETS.items() if "rocm" not in k
-        }
+        assets_without_rocm = {k: v for k, v in UPSTREAM_ASSETS.items() if "rocm" not in k}
         mock_assets.return_value = assets_without_rocm
         host = rocm_host()
         with pytest.raises(PrebuiltFallback, match = "ROCm detected"):
@@ -573,9 +569,7 @@ class TestEnsureRocmTorch:
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
     @patch.object(stack_mod, "_detect_rocm_version", return_value = (7, 1))
-    def test_torch_already_has_cuda_skips(
-        self, mock_ver, mock_gpu, mock_nvidia, mock_pip
-    ):
+    def test_torch_already_has_cuda_skips(self, mock_ver, mock_gpu, mock_nvidia, mock_pip):
         """If torch already has CUDA, should skip ROCm reinstall."""
         mock_probe = MagicMock()
         mock_probe.returncode = 0
@@ -589,9 +583,7 @@ class TestEnsureRocmTorch:
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
     @patch.object(stack_mod, "_detect_rocm_version", return_value = (7, 1))
-    def test_torch_already_has_hip_skips(
-        self, mock_ver, mock_gpu, mock_nvidia, mock_pip
-    ):
+    def test_torch_already_has_hip_skips(self, mock_ver, mock_gpu, mock_nvidia, mock_pip):
         """If torch already has HIP, should skip ROCm reinstall."""
         mock_probe = MagicMock()
         mock_probe.returncode = 0
@@ -629,9 +621,7 @@ class TestEnsureRocmTorch:
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
     @patch.object(stack_mod, "_detect_rocm_version", return_value = (6, 3))
-    def test_rocm_63_selects_correct_tag(
-        self, mock_ver, mock_gpu, mock_nvidia, mock_pip
-    ):
+    def test_rocm_63_selects_correct_tag(self, mock_ver, mock_gpu, mock_nvidia, mock_pip):
         """ROCm 6.3 should select rocm6.3 tag."""
         mock_probe = MagicMock()
         mock_probe.returncode = 0
@@ -698,9 +688,7 @@ class TestEnsureRocmTorch:
     ):
         """Probe subprocess timeout should not crash; should proceed to reinstall."""
         with patch("os.path.isdir", return_value = True):
-            with patch(
-                "subprocess.run", side_effect = subprocess.TimeoutExpired("python", 30)
-            ):
+            with patch("subprocess.run", side_effect = subprocess.TimeoutExpired("python", 30)):
                 _ensure_rocm_torch()
         # If probe times out, the function should treat torch as unusable and reinstall
         # both torch (via pip_install) and bitsandbytes (via pip_install_try).
@@ -788,25 +776,19 @@ class TestHardwareRocmFlag:
 
     def test_hardware_py_has_is_rocm(self):
         """hardware.py should define IS_ROCM."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         assert "IS_ROCM: bool" in source and "False" in source
 
     def test_hardware_py_sets_is_rocm_on_hip(self):
         """detect_hardware() should set IS_ROCM when torch.version.hip is set."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         assert 'torch.version, "hip"' in source or "torch.version.hip" in source
 
     def test_hardware_py_still_returns_cuda_for_rocm(self):
         """DeviceType should remain CUDA even on ROCm -- no DeviceType.ROCM."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         # Ensure ROCM is NOT a DeviceType member
         enum_section = source.split("class DeviceType")[1].split("\n\n")[0]
@@ -814,17 +796,13 @@ class TestHardwareRocmFlag:
 
     def test_hardware_py_has_rocm_in_package_versions(self):
         """get_package_versions() should include 'rocm' key."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         assert '"rocm"' in source
 
     def test_hardware_py_device_type_cuda_references_intact(self):
         """All existing DeviceType.CUDA references should still be present."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         # Key functions that must still reference DeviceType.CUDA
         assert "DeviceType.CUDA" in source
@@ -832,26 +810,20 @@ class TestHardwareRocmFlag:
 
     def test_is_rocm_exported_from_init(self):
         """IS_ROCM should be exported from hardware __init__.py."""
-        init_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
-        )
+        init_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
         source = init_path.read_text(encoding = "utf-8")
         assert "IS_ROCM" in source
 
     def test_is_rocm_in_all_list(self):
         """IS_ROCM should be in __all__ list in __init__.py."""
-        init_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
-        )
+        init_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "__init__.py"
         source = init_path.read_text(encoding = "utf-8")
         # Extract __all__ section
         assert '"IS_ROCM"' in source
 
     def test_get_package_versions_returns_rocm_key(self):
         """get_package_versions() source should return both 'cuda' and 'rocm' keys."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         # Find the get_package_versions function body
         func_start = source.find("def get_package_versions")
@@ -866,22 +838,16 @@ class TestHardwareRocmFlag:
         Windows ROCm where torch.distributed ships without that helper, causing
         a warning: 'module torch.distributed has no attribute is_torchelastic_launched'.
         """
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         assert "is_torchelastic_launched" in source
 
     def test_distributed_stubs_cover_core_helpers(self):
         """_determine_attention_impl_for_gpu_estimate must stub the four core distributed helpers."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         for attr in ("is_initialized", "is_available", "get_rank", "get_world_size"):
-            assert (
-                attr in source
-            ), f"distributed stub for '{attr}' missing from hardware.py"
+            assert attr in source, f"distributed stub for '{attr}' missing from hardware.py"
 
 
 # =============================================================================
@@ -947,12 +913,8 @@ class TestInstallShStructure:
         nvidia_call = body.find("_has_usable_nvidia_gpu")
         no_nvidia_branch = body.find('if [ -z "$_smi" ]')
         rocm_call = body.find("_has_amd_rocm_gpu")
-        assert (
-            nvidia_call >= 0
-        ), "get_torch_index_url should call _has_usable_nvidia_gpu"
-        assert (
-            no_nvidia_branch >= 0
-        ), "get_torch_index_url should gate ROCm on no-nvidia-smi"
+        assert nvidia_call >= 0, "get_torch_index_url should call _has_usable_nvidia_gpu"
+        assert no_nvidia_branch >= 0, "get_torch_index_url should gate ROCm on no-nvidia-smi"
         assert (
             rocm_call > no_nvidia_branch
         ), "ROCm detection should sit inside the 'no nvidia-smi' branch"
@@ -1013,9 +975,7 @@ class TestInstallShStructure:
                 continue
             # Remove POSIX character classes [[:foo:]] before checking for [[ ]]
             cleaned = re.sub(r"\[\[:[a-z]+:\]\]", "", line)
-            assert (
-                "[[" not in cleaned
-            ), f"get_torch_index_url line {i} uses non-POSIX [["
+            assert "[[" not in cleaned, f"get_torch_index_url line {i} uses non-POSIX [["
 
     def test_no_arithmetic_expansion_in_rocm_block(self):
         """ROCm detection block should not use (( )) (bash-only)."""
@@ -1063,8 +1023,7 @@ class TestLiveRegression:
             [
                 "bash",
                 "-c",
-                "nvidia-smi -L 2>/dev/null | "
-                "awk '/^GPU[[:space:]]+[0-9]+:/{f=1} END{exit !f}'",
+                "nvidia-smi -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{f=1} END{exit !f}'",
             ],
             capture_output = True,
         )
@@ -1098,9 +1057,7 @@ class TestLiveRegression:
 
 # Load worker.py module
 _WORKER_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "training" / "worker.py"
-_EXPORT_WORKER_PATH = (
-    PACKAGE_ROOT / "studio" / "backend" / "core" / "export" / "worker.py"
-)
+_EXPORT_WORKER_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "export" / "worker.py"
 # The torchao Windows-ROCm stub was de-duplicated out of the export/training
 # workers into a shared module; both workers now call into it.
 _TORCHAO_STUB_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "_torchao_stub.py"
@@ -1126,9 +1083,7 @@ class TestWorkerRocmMambaSsm:
     def test_direct_wheel_url_returns_none_without_cuda_major(self, monkeypatch):
         """_direct_wheel_url should return None when cuda_major is empty (ROCm)."""
         # Load module for function access
-        _worker_spec = importlib.util.spec_from_file_location(
-            "test_worker", _WORKER_PATH
-        )
+        _worker_spec = importlib.util.spec_from_file_location("test_worker", _WORKER_PATH)
         assert _worker_spec is not None and _worker_spec.loader is not None
         worker_mod = importlib.util.module_from_spec(_worker_spec)
 
@@ -1347,9 +1302,7 @@ class TestHardwareAmdBranching:
 
     def test_hardware_imports_amd_module(self):
         """hardware.py should import from amd module when IS_ROCM."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         assert "from . import amd" in source
 
@@ -1357,17 +1310,13 @@ class TestHardwareAmdBranching:
         """get_gpu_utilization should dispatch to amd.py via _smi_query
         when IS_ROCM, and the dispatcher itself must check IS_ROCM and
         import the amd backend."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_gpu_utilization")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert '_smi_query("get_primary_gpu_utilization"' in func_body
         smi = source[
-            source.find("def _smi_query") : source.find(
-                "\ndef ", source.find("def _smi_query") + 1
-            )
+            source.find("def _smi_query") : source.find("\ndef ", source.find("def _smi_query") + 1)
         ]
         assert "IS_ROCM" in smi
         assert "from . import amd" in smi
@@ -1375,9 +1324,7 @@ class TestHardwareAmdBranching:
     def test_hardware_branches_on_is_rocm_for_visible(self):
         """get_visible_gpu_utilization should dispatch to amd.py via
         _smi_query when IS_ROCM."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_visible_gpu_utilization")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
@@ -1387,18 +1334,14 @@ class TestHardwareAmdBranching:
 
         assert _re.search(r'_smi_query\(\s*"get_visible_gpu_utilization"', func_body)
         smi = source[
-            source.find("def _smi_query") : source.find(
-                "\ndef ", source.find("def _smi_query") + 1
-            )
+            source.find("def _smi_query") : source.find("\ndef ", source.find("def _smi_query") + 1)
         ]
         assert "IS_ROCM" in smi
         assert "from . import amd" in smi
 
     def test_hardware_branches_on_is_rocm_for_physical_count(self):
         """get_physical_gpu_count should try amd.py when IS_ROCM."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def get_physical_gpu_count")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
@@ -1417,9 +1360,7 @@ class TestApplyGpuIdsRocmFallback:
 
     def test_apply_gpu_ids_falls_back_to_torch_version_hip(self):
         """apply_gpu_ids should probe torch.version.hip when IS_ROCM is False and no ROCm env vars are set."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def apply_gpu_ids")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
@@ -1427,9 +1368,7 @@ class TestApplyGpuIdsRocmFallback:
 
     def test_apply_gpu_ids_sets_hip_and_rocr_visible_devices(self):
         """apply_gpu_ids should set both HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES on ROCm."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def apply_gpu_ids")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
@@ -1438,9 +1377,7 @@ class TestApplyGpuIdsRocmFallback:
 
     def test_apply_gpu_ids_rocm_fallback_is_guarded_by_try_except(self):
         """torch import in apply_gpu_ids must be wrapped in try/except so a missing torch never crashes."""
-        hw_path = (
-            PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-        )
+        hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def apply_gpu_ids")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
@@ -1591,9 +1528,7 @@ class TestWindowsRocmIndexUrl:
         assert "repo.amd.com" in url
 
     def test_mirror_env_var_overrides_base(self, monkeypatch):
-        monkeypatch.setenv(
-            "UNSLOTH_ROCM_WINDOWS_MIRROR", "https://my-mirror.example.com/rocm/whl"
-        )
+        monkeypatch.setenv("UNSLOTH_ROCM_WINDOWS_MIRROR", "https://my-mirror.example.com/rocm/whl")
         # Reload module-level constant by calling helper directly
         url = stack_mod._windows_rocm_index_url("gfx1200")
         # The env var is read at module load time for _ROCM_WINDOWS_INDEX_BASE,
@@ -1722,9 +1657,7 @@ class TestInstallBnbWindowsRocm:
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
-                with patch.object(
-                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "72"
-                ):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "72"):
                     stack_mod._install_bnb_windows_rocm()
             assert os.environ.get("BNB_ROCM_VERSION") == "72"
 
@@ -1733,9 +1666,7 @@ class TestInstallBnbWindowsRocm:
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
-                with patch.object(
-                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "713"
-                ):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "713"):
                     stack_mod._install_bnb_windows_rocm()
             assert os.environ.get("BNB_ROCM_VERSION") == "713"
 
@@ -1744,9 +1675,7 @@ class TestInstallBnbWindowsRocm:
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
-                with patch.object(
-                    stack_mod, "_detect_bnb_rocm_dll_ver", return_value = None
-                ):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = None):
                     stack_mod._install_bnb_windows_rocm()
             assert os.environ.get("BNB_ROCM_VERSION") == "72"
 
@@ -1764,7 +1693,6 @@ class TestDetectBnbRocmDllVer:
     def test_returns_none_when_bnb_not_installed(self):
         """Returns None if bitsandbytes is not importable."""
         import importlib.util
-
         with patch.object(importlib.util, "find_spec", return_value = None):
             assert stack_mod._detect_bnb_rocm_dll_ver() is None
 
@@ -1973,9 +1901,7 @@ class TestWorkerWindowsRocmPatches:
         # entry-point function (not the trainer helper which has its own "# ── 2.").
         idx_sec2 = source.find("# ── 2. Now import ML libraries")
         assert idx_bnb != -1, "BNB_ROCM_VERSION not found in worker.py"
-        assert (
-            idx_sec2 != -1
-        ), "'# ── 2. Now import ML libraries' marker not found in worker.py"
+        assert idx_sec2 != -1, "'# ── 2. Now import ML libraries' marker not found in worker.py"
         assert idx_bnb < idx_sec2, (
             "BNB_ROCM_VERSION must be set before section 2 ML imports "
             f"(found at {idx_bnb}, section 2 at {idx_sec2})"
@@ -2269,16 +2195,12 @@ class TestHipSdkEnvPathResolution:
         """setup.ps1 must tell the user how to add the HIP bin dir to PATH."""
         source = _SETUP_PS1_PATH.read_text(encoding = "utf-8")
         # Should mention adding to PATH or SetEnvironmentVariable
-        assert "PATH" in source and (
-            "SetEnvironmentVariable" in source or "Add" in source
-        )
+        assert "PATH" in source and ("SetEnvironmentVariable" in source or "Add" in source)
 
     def test_install_provides_path_fix_hint(self):
         """install.ps1 must tell the user how to add the HIP bin dir to PATH."""
         source = _INSTALL_PS1_PATH.read_text(encoding = "utf-8")
-        assert "PATH" in source and (
-            "SetEnvironmentVariable" in source or "Add" in source
-        )
+        assert "PATH" in source and ("SetEnvironmentVariable" in source or "Add" in source)
 
 
 # =============================================================================
@@ -2448,9 +2370,7 @@ class TestSetupShGccInstallDir:
 # =============================================================================
 
 _MAIN_PY_PATH = PACKAGE_ROOT / "studio" / "backend" / "main.py"
-_HARDWARE_PY_PATH = (
-    PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
-)
+_HARDWARE_PY_PATH = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
 
 
 class TestServerStartupRocmFixes:
@@ -2664,9 +2584,7 @@ class TestApplyHostOverrides:
         assert out.rocm_gfx_target is None
 
     def test_malformed_forwarded_gfx_falls_back_to_has_rocm(self):
-        out = _apply_host_overrides(
-            cpu_host(), override_has_rocm = True, override_rocm_gfx = "junk"
-        )
+        out = _apply_host_overrides(cpu_host(), override_has_rocm = True, override_rocm_gfx = "junk")
         assert out.has_rocm is True
         assert out.rocm_gfx_target is None
 
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index f1c3130a77..1ada35888c 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -22,9 +22,7 @@ import pytest
 PACKAGE_ROOT = Path(__file__).resolve().parents[3]
 MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
 RUN_MODULE_PATH = PACKAGE_ROOT / "studio" / "backend" / "run.py"
-SPEC = importlib.util.spec_from_file_location(
-    "studio_install_llama_prebuilt", MODULE_PATH
-)
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
 assert SPEC is not None and SPEC.loader is not None
 INSTALL_LLAMA_PREBUILT = importlib.util.module_from_spec(SPEC)
 sys.modules[SPEC.name] = INSTALL_LLAMA_PREBUILT
@@ -49,15 +47,11 @@ supports_explicit_visible_device_matching = (
 select_visible_gpu_rows = INSTALL_LLAMA_PREBUILT.select_visible_gpu_rows
 compatible_linux_runtime_lines = INSTALL_LLAMA_PREBUILT.compatible_linux_runtime_lines
 pick_windows_cuda_runtime = INSTALL_LLAMA_PREBUILT.pick_windows_cuda_runtime
-compatible_windows_runtime_lines = (
-    INSTALL_LLAMA_PREBUILT.compatible_windows_runtime_lines
-)
+compatible_windows_runtime_lines = INSTALL_LLAMA_PREBUILT.compatible_windows_runtime_lines
 runtime_line_from_cuda_version = INSTALL_LLAMA_PREBUILT.runtime_line_from_cuda_version
 apply_approved_hashes = INSTALL_LLAMA_PREBUILT.apply_approved_hashes
 linux_cuda_choice_from_release = INSTALL_LLAMA_PREBUILT.linux_cuda_choice_from_release
-parse_direct_linux_release_bundle = (
-    INSTALL_LLAMA_PREBUILT.parse_direct_linux_release_bundle
-)
+parse_direct_linux_release_bundle = INSTALL_LLAMA_PREBUILT.parse_direct_linux_release_bundle
 windows_cuda_attempts = INSTALL_LLAMA_PREBUILT.windows_cuda_attempts
 resolve_upstream_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_upstream_asset_choice
 resolve_requested_install_tag = INSTALL_LLAMA_PREBUILT.resolve_requested_install_tag
@@ -66,19 +60,11 @@ resolve_install_release_plans = INSTALL_LLAMA_PREBUILT.resolve_install_release_p
 resolve_published_release = INSTALL_LLAMA_PREBUILT.resolve_published_release
 resolve_source_build_plan = INSTALL_LLAMA_PREBUILT.resolve_source_build_plan
 validated_checksums_for_bundle = INSTALL_LLAMA_PREBUILT.validated_checksums_for_bundle
-parse_approved_release_checksums = (
-    INSTALL_LLAMA_PREBUILT.parse_approved_release_checksums
-)
-published_release_matches_request = (
-    INSTALL_LLAMA_PREBUILT.published_release_matches_request
-)
-exact_source_archive_logical_name = (
-    INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name
-)
+parse_approved_release_checksums = INSTALL_LLAMA_PREBUILT.parse_approved_release_checksums
+published_release_matches_request = INSTALL_LLAMA_PREBUILT.published_release_matches_request
+exact_source_archive_logical_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name
 source_archive_logical_name = INSTALL_LLAMA_PREBUILT.source_archive_logical_name
-windows_cuda_upstream_asset_names = (
-    INSTALL_LLAMA_PREBUILT.windows_cuda_upstream_asset_names
-)
+windows_cuda_upstream_asset_names = INSTALL_LLAMA_PREBUILT.windows_cuda_upstream_asset_names
 env_int = INSTALL_LLAMA_PREBUILT.env_int
 direct_upstream_release_plan = INSTALL_LLAMA_PREBUILT.direct_upstream_release_plan
 _pinned_windows_cuda_fallback = INSTALL_LLAMA_PREBUILT._pinned_windows_cuda_fallback
@@ -89,9 +75,7 @@ _windows_cuda_attempt_covers_blackwell = (
 )
 resolve_release_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_release_asset_choice
 pinned_macos_release_tag = INSTALL_LLAMA_PREBUILT.pinned_macos_release_tag
-resolve_simple_install_release_plans = (
-    INSTALL_LLAMA_PREBUILT.resolve_simple_install_release_plans
-)
+resolve_simple_install_release_plans = INSTALL_LLAMA_PREBUILT.resolve_simple_install_release_plans
 
 
 def load_studio_run_module(monkeypatch):
@@ -244,9 +228,7 @@ def make_checksums_with_source(
             kind = "upstream-source",
         ),
     }
-    normalized_source_commit = (
-        source_commit.lower() if isinstance(source_commit, str) else None
-    )
+    normalized_source_commit = source_commit.lower() if isinstance(source_commit, str) else None
     if normalized_source_commit:
         artifacts[exact_source_archive_logical_name(normalized_source_commit)] = (
             ApprovedArtifactHash(
@@ -266,9 +248,7 @@ def make_checksums_with_source(
         requested_source_ref = requested_source_ref,
         resolved_source_ref = resolved_source_ref,
         source_commit = normalized_source_commit,
-        source_commit_short = normalized_source_commit[:7]
-        if normalized_source_commit
-        else None,
+        source_commit_short = normalized_source_commit[:7] if normalized_source_commit else None,
         artifacts = artifacts,
     )
 
@@ -363,10 +343,7 @@ class TestStudioLocalhostIpv6Warning:
             lambda host, port, timeout = 1.0: True,
         )
 
-        assert (
-            run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888)
-            == "http://127.0.0.1:8888"
-        )
+        assert run_module._localhost_ipv6_mismatch_url("127.0.0.1", 8888) == "http://127.0.0.1:8888"
 
     @pytest.mark.parametrize("host", ["0.0.0.0", "::"])
     def test_network_bind_suppresses_warning(self, monkeypatch, host):
@@ -431,9 +408,7 @@ class TestStudioLocalhostIpv6Warning:
         monkeypatch.setattr(
             run_module,
             "_verify_global_reachability",
-            lambda display_host, port: calls["reachability"].append(
-                (display_host, port)
-            ),
+            lambda display_host, port: calls["reachability"].append((display_host, port)),
         )
         return calls
 
@@ -456,9 +431,7 @@ class TestStudioLocalhostIpv6Warning:
     def test_emit_startup_output_plain_localhost(self, monkeypatch):
         run_module = load_studio_run_module(monkeypatch)
         calls = self._wire_recorders(run_module, monkeypatch)
-        monkeypatch.setattr(
-            run_module, "_localhost_ipv6_mismatch_url", lambda host, port: None
-        )
+        monkeypatch.setattr(run_module, "_localhost_ipv6_mismatch_url", lambda host, port: None)
 
         run_module._emit_startup_output("127.0.0.1", 8888, "127.0.0.1")
 
@@ -471,9 +444,7 @@ class TestStudioLocalhostIpv6Warning:
     def test_emit_startup_output_wildcard_runs_reachability(self, monkeypatch, host):
         run_module = load_studio_run_module(monkeypatch)
         calls = self._wire_recorders(run_module, monkeypatch)
-        monkeypatch.setattr(
-            run_module, "_localhost_ipv6_mismatch_url", lambda h, port: None
-        )
+        monkeypatch.setattr(run_module, "_localhost_ipv6_mismatch_url", lambda h, port: None)
 
         run_module._emit_startup_output(host, 8888, "203.0.113.5")
 
@@ -651,9 +622,7 @@ class TestParseDirectLinuxReleaseBundle:
         names = [f"app-bTEST-linux-x64-{t}.tar.gz" for t in targets]
         return {
             "tag_name": "bTEST",
-            "assets": [
-                {"name": n, "browser_download_url": "https://x/" + n} for n in names
-            ],
+            "assets": [{"name": n, "browser_download_url": "https://x/" + n} for n in names],
         }
 
     def _cuda_artifact(self, bundle):
@@ -885,9 +854,7 @@ class TestPublishedReleaseResolution:
         def fake_load(repo, release_tag):
             if release_tag == "v2.0":
                 raise PrebuiltFallback("checksum asset missing")
-            return make_checksums_with_source(
-                [], release_tag = "v1.0", upstream_tag = "b8999"
-            )
+            return make_checksums_with_source([], release_tag = "v1.0", upstream_tag = "b8999")
 
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
@@ -917,9 +884,7 @@ class TestPublishedReleaseResolution:
             ),
         )
 
-        assert (
-            resolve_requested_install_tag("b8508", "", "unslothai/llama.cpp") == "b8508"
-        )
+        assert resolve_requested_install_tag("b8508", "", "unslothai/llama.cpp") == "b8508"
 
     def test_concrete_tag_without_matching_release_raises(self, monkeypatch):
         release = make_release([], release_tag = "release-b9000", upstream_tag = "b9000")
@@ -933,9 +898,7 @@ class TestPublishedReleaseResolution:
             resolve_requested_install_tag("b8508", "", "unslothai/llama.cpp")
 
     def test_pinned_release_must_match_requested_upstream_tag(self, monkeypatch):
-        bundle = make_release(
-            [], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000"
-        )
+        bundle = make_release([], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000")
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
             "pinned_published_release_bundle",
@@ -1110,15 +1073,13 @@ class TestSourceBuildPlanResolution:
         assert plan.source_ref == "main"
         assert plan.compatibility_upstream_tag == "b9000"
 
-    def test_direct_main_request_without_published_release_uses_branch_kind(
-        self, monkeypatch
-    ):
+    def test_direct_main_request_without_published_release_uses_branch_kind(self, monkeypatch):
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
             "resolve_published_release",
-            lambda requested_tag, published_repo, published_release_tag = "": (
-                _ for _ in ()
-            ).throw(PrebuiltFallback("missing")),
+            lambda requested_tag, published_repo, published_release_tag = "": (_ for _ in ()).throw(
+                PrebuiltFallback("missing")
+            ),
         )
 
         plan = resolve_source_build_plan("main", "unslothai/llama.cpp")
@@ -1193,9 +1154,7 @@ class TestValidatedChecksumsForBundle:
     def test_rejects_manifest_checksum_mismatch(self, monkeypatch):
         bundle = make_release([], release_tag = "r1", upstream_tag = "b8508")
         bundle.manifest_sha256 = "a" * 64
-        checksums = make_checksums_with_source(
-            [], release_tag = "r1", upstream_tag = "b8508"
-        )
+        checksums = make_checksums_with_source([], release_tag = "r1", upstream_tag = "b8508")
         checksums.artifacts[bundle.manifest_asset_name] = ApprovedArtifactHash(
             asset_name = bundle.manifest_asset_name,
             sha256 = "b" * 64,
@@ -1249,9 +1208,7 @@ class TestLinuxCudaChoiceFromRelease:
         art12 = make_artifact("bundle-cuda12.tar.gz", runtime_line = "cuda12")
         art13 = make_artifact("bundle-cuda13.tar.gz", runtime_line = "cuda13")
         release = make_release([art12, art13])
-        result = linux_cuda_choice_from_release(
-            host, release, preferred_runtime_line = "cuda12"
-        )
+        result = linux_cuda_choice_from_release(host, release, preferred_runtime_line = "cuda12")
         assert result is not None
         assert result.primary.runtime_line == "cuda12"
 
@@ -1260,9 +1217,7 @@ class TestLinuxCudaChoiceFromRelease:
         host = make_host(driver_cuda_version = (12, 8))
         art = make_artifact("bundle-cuda12.tar.gz", runtime_line = "cuda12")
         release = make_release([art])
-        result = linux_cuda_choice_from_release(
-            host, release, preferred_runtime_line = "cuda13"
-        )
+        result = linux_cuda_choice_from_release(host, release, preferred_runtime_line = "cuda13")
         assert result is not None
         assert result.primary.runtime_line == "cuda12"
         log_entries = result.selection_log
@@ -1273,9 +1228,7 @@ class TestLinuxCudaChoiceFromRelease:
     def test_exact_sm_match(self, monkeypatch):
         mock_linux_runtime(monkeypatch, ["cuda12"])
         host = make_host(compute_caps = ["86"])
-        art = make_artifact(
-            "bundle.tar.gz", supported_sms = ["75", "86", "89"], min_sm = 75, max_sm = 89
-        )
+        art = make_artifact("bundle.tar.gz", supported_sms = ["75", "86", "89"], min_sm = 75, max_sm = 89)
         release = make_release([art])
         result = linux_cuda_choice_from_release(host, release)
         assert result is not None
@@ -1284,9 +1237,7 @@ class TestLinuxCudaChoiceFromRelease:
     def test_sm_not_in_supported_sms(self, monkeypatch):
         mock_linux_runtime(monkeypatch, ["cuda12"])
         host = make_host(compute_caps = ["86"])
-        art = make_artifact(
-            "bundle.tar.gz", supported_sms = ["75", "80", "89"], min_sm = 75, max_sm = 89
-        )
+        art = make_artifact("bundle.tar.gz", supported_sms = ["75", "80", "89"], min_sm = 75, max_sm = 89)
         release = make_release([art])
         result = linux_cuda_choice_from_release(host, release)
         assert result is None
@@ -1294,9 +1245,7 @@ class TestLinuxCudaChoiceFromRelease:
     def test_sm_outside_min_range(self, monkeypatch):
         mock_linux_runtime(monkeypatch, ["cuda12"])
         host = make_host(compute_caps = ["50"])
-        art = make_artifact(
-            "bundle.tar.gz", supported_sms = ["50", "75", "86"], min_sm = 75, max_sm = 90
-        )
+        art = make_artifact("bundle.tar.gz", supported_sms = ["50", "75", "86"], min_sm = 75, max_sm = 90)
         release = make_release([art])
         result = linux_cuda_choice_from_release(host, release)
         assert result is None
@@ -1365,9 +1314,7 @@ class TestLinuxCudaChoiceFromRelease:
     def test_multi_gpu_not_all_covered(self, monkeypatch):
         mock_linux_runtime(monkeypatch, ["cuda12"])
         host = make_host(compute_caps = ["50", "89"])
-        art = make_artifact(
-            "bundle.tar.gz", supported_sms = ["75", "89"], min_sm = 75, max_sm = 89
-        )
+        art = make_artifact("bundle.tar.gz", supported_sms = ["75", "89"], min_sm = 75, max_sm = 89)
         release = make_release([art])
         result = linux_cuda_choice_from_release(host, release)
         assert result is None
@@ -1559,9 +1506,7 @@ class TestBlackwellUltraSm103Coverage:
 
 
 class TestResolveInstallAttempts:
-    def test_windows_cuda_prefers_published_asset_from_selected_release(
-        self, monkeypatch
-    ):
+    def test_windows_cuda_prefers_published_asset_from_selected_release(self, monkeypatch):
         host = make_host(system = "Windows", machine = "AMD64")
         host.driver_cuda_version = (12, 4)
         mock_windows_runtime(monkeypatch, ["cuda12"])
@@ -1605,9 +1550,7 @@ class TestResolveInstallAttempts:
             INSTALL_LLAMA_PREBUILT,
             "github_release_assets",
             lambda repo, tag: (_ for _ in ()).throw(
-                AssertionError(
-                    "published Windows CUDA choice should not query upstream"
-                )
+                AssertionError("published Windows CUDA choice should not query upstream")
             ),
         )
 
@@ -1629,9 +1572,7 @@ class TestResolveInstallAttempts:
         host = make_host(system = "Windows", machine = "AMD64")
         host.driver_cuda_version = (12, 4)
         mock_windows_runtime(monkeypatch, ["cuda12"])
-        release = make_release(
-            [], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000"
-        )
+        release = make_release([], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000")
         checksums = make_checksums_with_source(
             ["llama-b9000-bin-win-cuda-12.4-x64.zip"],
             release_tag = release.release_tag,
@@ -1692,9 +1633,7 @@ class TestResolveInstallAttempts:
             has_physical_nvidia = False,
             nvidia_smi = None,
         )
-        release = make_release(
-            [], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000"
-        )
+        release = make_release([], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000")
         checksums = make_checksums_with_source(
             ["llama-b9000-bin-ubuntu-x64.tar.gz"],
             release_tag = release.release_tag,
@@ -1735,9 +1674,7 @@ class TestResolveInstallAttempts:
 
     def test_linux_cuda_does_not_fall_back_to_upstream_cpu(self, monkeypatch):
         host = make_host(system = "Linux", machine = "x86_64", compute_caps = ["86"])
-        release = make_release(
-            [], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000"
-        )
+        release = make_release([], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000")
         checksums = make_checksums_with_source(
             [],
             release_tag = release.release_tag,
@@ -1758,9 +1695,7 @@ class TestResolveInstallAttempts:
         )
         mock_linux_runtime(monkeypatch, ["cuda12"])
 
-        with pytest.raises(
-            PrebuiltFallback, match = "no compatible published Linux CUDA bundle"
-        ):
+        with pytest.raises(PrebuiltFallback, match = "no compatible published Linux CUDA bundle"):
             resolve_install_attempts("latest", host, "unslothai/llama.cpp", "")
 
     def test_windows_cpu_prefers_published_asset(self, monkeypatch):
@@ -1956,9 +1891,7 @@ class TestResolveInstallAttempts:
 
 
 class TestResolveInstallReleasePlans:
-    def test_latest_collects_multiple_older_release_plans_up_to_limit(
-        self, monkeypatch
-    ):
+    def test_latest_collects_multiple_older_release_plans_up_to_limit(self, monkeypatch):
         host = make_host(
             has_usable_nvidia = False,
             has_physical_nvidia = False,
@@ -1994,9 +1927,7 @@ class TestResolveInstallReleasePlans:
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
             "iter_resolved_published_releases",
-            lambda requested_tag, published_repo, published_release_tag = "": iter(
-                releases
-            ),
+            lambda requested_tag, published_repo, published_release_tag = "": iter(releases),
         )
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
@@ -2018,9 +1949,7 @@ class TestResolveInstallReleasePlans:
         assert [plan.release_tag for plan in plans] == ["r3", "r2"]
         assert [plan.llama_tag for plan in plans] == ["b9003", "b9002"]
 
-    def test_latest_skips_non_installable_release_and_keeps_searching(
-        self, monkeypatch
-    ):
+    def test_latest_skips_non_installable_release_and_keeps_searching(self, monkeypatch):
         host = make_host(
             has_usable_nvidia = False,
             has_physical_nvidia = False,
@@ -2048,9 +1977,7 @@ class TestResolveInstallReleasePlans:
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
             "iter_resolved_published_releases",
-            lambda requested_tag, published_repo, published_release_tag = "": iter(
-                releases
-            ),
+            lambda requested_tag, published_repo, published_release_tag = "": iter(releases),
         )
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
@@ -2078,13 +2005,9 @@ class TestResolveInstallReleasePlans:
 
     def test_malformed_release_fallback_env_uses_default(self, monkeypatch):
         monkeypatch.setenv("UNSLOTH_LLAMA_MAX_PREBUILT_RELEASE_FALLBACKS", "not-an-int")
-        assert (
-            env_int("UNSLOTH_LLAMA_MAX_PREBUILT_RELEASE_FALLBACKS", 3, minimum = 1) == 3
-        )
+        assert env_int("UNSLOTH_LLAMA_MAX_PREBUILT_RELEASE_FALLBACKS", 3, minimum = 1) == 3
 
-    def test_import_with_malformed_release_fallback_env_does_not_crash(
-        self, monkeypatch
-    ):
+    def test_import_with_malformed_release_fallback_env_does_not_crash(self, monkeypatch):
         monkeypatch.setenv("UNSLOTH_LLAMA_MAX_PREBUILT_RELEASE_FALLBACKS", "bad-value")
         spec = importlib.util.spec_from_file_location(
             "studio_install_llama_prebuilt_env_reload",
@@ -2108,7 +2031,11 @@ class TestResolveInstallReleasePlans:
 class TestWindowsCudaAttempts:
     TAG = "b8508"
 
-    def _upstream(self, *runtime_versions, current_names: bool = False):
+    def _upstream(
+        self,
+        *runtime_versions,
+        current_names: bool = False,
+    ):
         assets = {}
         for rv in runtime_versions:
             if current_names:
@@ -2350,23 +2277,14 @@ class TestPinnedBlackwellCudaFallback:
         assert pin.runtime_sha256 and len(pin.runtime_sha256) == 64
 
     def test_pin_offered_for_driver_13_2(self):
-        assert (
-            _pinned_windows_cuda_fallback(self._win_host((13, 2), ["120"]), [])
-            is not None
-        )
+        assert _pinned_windows_cuda_fallback(self._win_host((13, 2), ["120"]), []) is not None
 
     def test_pin_offered_for_sm121_variant(self):
         # sm_121 is Blackwell-family and also needs toolkit >= 12.8.
-        assert (
-            _pinned_windows_cuda_fallback(self._win_host((13, 1), ["121"]), [])
-            is not None
-        )
+        assert _pinned_windows_cuda_fallback(self._win_host((13, 1), ["121"]), []) is not None
 
     def test_pin_uses_max_of_multi_gpu_caps(self):
-        assert (
-            _pinned_windows_cuda_fallback(self._win_host((13, 1), ["86", "120"]), [])
-            is not None
-        )
+        assert _pinned_windows_cuda_fallback(self._win_host((13, 1), ["86", "120"]), []) is not None
 
     @pytest.mark.parametrize("sm", ["89", "90", "100"])
     def test_pin_not_offered_to_non_blackwell(self, sm):
@@ -2377,16 +2295,11 @@ class TestPinnedBlackwellCudaFallback:
         # b9360 is native sm_120a SASS (no JIT) and ships a cuda-13.1 cudart,
         # both of which run on a 13.0 r580+ driver via CUDA minor-version
         # compatibility. 13.0 is the mainstream Blackwell branch, so it must fire.
-        assert (
-            _pinned_windows_cuda_fallback(self._win_host((13, 0), ["120"]), [])
-            is not None
-        )
+        assert _pinned_windows_cuda_fallback(self._win_host((13, 0), ["120"]), []) is not None
 
     def test_pin_not_offered_below_floor(self):
         # 12.x predates Blackwell entirely; the pin stays dormant below 13.0.
-        assert (
-            _pinned_windows_cuda_fallback(self._win_host((12, 9), ["120"]), []) is None
-        )
+        assert _pinned_windows_cuda_fallback(self._win_host((12, 9), ["120"]), []) is None
 
     def test_pin_not_offered_without_driver(self):
         assert _pinned_windows_cuda_fallback(self._win_host(None, ["120"]), []) is None
@@ -2460,10 +2373,7 @@ class TestPinnedBlackwellCudaFallback:
         ],
     )
     def test_attempt_covers_blackwell(self, minor, covers):
-        assert (
-            _windows_cuda_attempt_covers_blackwell(self._win_cuda_attempt(minor))
-            is covers
-        )
+        assert _windows_cuda_attempt_covers_blackwell(self._win_cuda_attempt(minor)) is covers
 
     def test_attempt_covers_blackwell_ignores_non_cuda_kind(self):
         cpu = AssetChoice(
@@ -2500,8 +2410,7 @@ class TestDirectUpstreamBlackwellPin:
         return {
             "tag_name": self.TAG,
             "assets": [
-                {"name": n, "browser_download_url": f"https://example.com/{n}"}
-                for n in names
+                {"name": n, "browser_download_url": f"https://example.com/{n}"} for n in names
             ],
         }
 
@@ -2521,15 +2430,9 @@ class TestDirectUpstreamBlackwellPin:
             driver_cuda_version = (13, 1),
             compute_caps = ["120"],
         )
-        plan = direct_upstream_release_plan(
-            self._release(), host, UPSTREAM_REPO, "latest"
-        )
+        plan = direct_upstream_release_plan(self._release(), host, UPSTREAM_REPO, "latest")
         order = [(a.tag, a.runtime_line or a.install_kind) for a in plan.attempts]
-        assert order == [
-            ("b9360", "cuda13"),
-            (self.TAG, "cuda12"),
-            (self.TAG, "windows-cpu"),
-        ]
+        assert order == [("b9360", "cuda13"), (self.TAG, "cuda12"), (self.TAG, "windows-cpu")]
         assert plan.attempts[0].name == "llama-b9360-bin-win-cuda-13.1-x64.zip"
         # Direct/upstream path stays unverified-by-manifest (no approved hashes).
         assert plan.approved_checksums.artifacts == {}
@@ -2543,9 +2446,7 @@ class TestDirectUpstreamBlackwellPin:
             driver_cuda_version = (13, 3),
             compute_caps = ["120"],
         )
-        plan = direct_upstream_release_plan(
-            self._release(), host, UPSTREAM_REPO, "latest"
-        )
+        plan = direct_upstream_release_plan(self._release(), host, UPSTREAM_REPO, "latest")
         assert "b9360" not in [a.tag for a in plan.attempts]
         assert plan.attempts[0].tag == self.TAG
         assert plan.attempts[0].runtime_line == "cuda13"
@@ -2581,9 +2482,7 @@ class TestPublishedWindowsCudaAttemptsDynamicMajor:
         # the old hardcoded cuda12/cuda13 seed would never order it (the cuda14
         # line would be skipped for want of a 14.x asset in the seed).
         mock_windows_runtime(monkeypatch, ["cuda14", "cuda13", "cuda12"])
-        release = self._release(
-            [("14.0", "cuda14"), ("13.3", "cuda13"), ("12.4", "cuda12")]
-        )
+        release = self._release([("14.0", "cuda14"), ("13.3", "cuda13"), ("12.4", "cuda12")])
         host = make_host(
             system = "Windows",
             machine = "AMD64",
@@ -2809,18 +2708,14 @@ class TestResolveUpstreamAssetChoice:
     def test_linux_x86_64_cpu(self, monkeypatch):
         name = f"llama-{self.TAG}-bin-ubuntu-x64.tar.gz"
         self._mock_github_assets(monkeypatch, {name: f"https://x/{name}"})
-        host = make_host(
-            has_usable_nvidia = False, nvidia_smi = None, has_physical_nvidia = False
-        )
+        host = make_host(has_usable_nvidia = False, nvidia_smi = None, has_physical_nvidia = False)
         result = resolve_upstream_asset_choice(host, self.TAG)
         assert result.install_kind == "linux-cpu"
         assert result.name == name
 
     def test_linux_cpu_missing(self, monkeypatch):
         self._mock_github_assets(monkeypatch, {})
-        host = make_host(
-            has_usable_nvidia = False, nvidia_smi = None, has_physical_nvidia = False
-        )
+        host = make_host(has_usable_nvidia = False, nvidia_smi = None, has_physical_nvidia = False)
         with pytest.raises(PrebuiltFallback, match = "Linux CPU"):
             resolve_upstream_asset_choice(host, self.TAG)
 
@@ -2907,9 +2802,7 @@ class TestResolveUpstreamAssetChoice:
             has_physical_nvidia = False,
             has_usable_nvidia = False,
         )
-        with pytest.raises(
-            PrebuiltFallback, match = "no prebuilt policy exists for Linux aarch64"
-        ):
+        with pytest.raises(PrebuiltFallback, match = "no prebuilt policy exists for Linux aarch64"):
             resolve_upstream_asset_choice(host, self.TAG)
 
     def test_windows_usable_nvidia_delegates(self, monkeypatch):
@@ -3022,7 +2915,11 @@ class TestResolveSimpleMacosPin:
                 ],
             }
 
-        def fake_iter(repo, published_release_tag = "", requested_tag = ""):
+        def fake_iter(
+            repo,
+            published_release_tag = "",
+            requested_tag = "",
+        ):
             calls.append((repo, published_release_tag, requested_tag))
             # Emulate the real iterator: a specific tag yields only that release.
             if requested_tag and requested_tag != "latest":
@@ -3031,9 +2928,7 @@ class TestResolveSimpleMacosPin:
             for tag in self.TAGS:
                 yield _release(tag)
 
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", fake_iter
-        )
+        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", fake_iter)
         return calls
 
     def test_pre26_host_pins_b9415_without_walkback(self, monkeypatch):
@@ -3081,14 +2976,10 @@ class TestLinuxArm64ForkFallsBackToSource:
         def _boom(*_a, **_k):
             raise AssertionError("iterator must not run for arm64 fork hosts")
 
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", _boom
-        )
+        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", _boom)
         host = make_host(system = "Linux", machine = "aarch64")
         with pytest.raises(PrebuiltFallback, match = "linux-x64 prebuilts"):
-            resolve_simple_install_release_plans(
-                "latest", host, "unslothai/llama.cpp", ""
-            )
+            resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
 
     def test_x86_64_fork_is_not_blocked_by_the_arch_guard(self, monkeypatch):
         # x64 host must pass the guard and reach the iterator (here empty, so it
@@ -3100,9 +2991,7 @@ class TestLinuxArm64ForkFallsBackToSource:
         )
         host = make_host(system = "Linux", machine = "x86_64")
         with pytest.raises(PrebuiltFallback) as exc:
-            resolve_simple_install_release_plans(
-                "latest", host, "unslothai/llama.cpp", ""
-            )
+            resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
         assert "linux-x64 prebuilts" not in str(exc.value)
 
     def test_arm64_cpu_on_ggml_org_is_not_blocked(self, monkeypatch):
@@ -3123,9 +3012,7 @@ class TestLinuxArm64ForkFallsBackToSource:
             has_usable_nvidia = False,
         )
         with pytest.raises(PrebuiltFallback) as exc:
-            resolve_simple_install_release_plans(
-                "latest", host, "ggml-org/llama.cpp", ""
-            )
+            resolve_simple_install_release_plans("latest", host, "ggml-org/llama.cpp", "")
         assert "linux-x64 prebuilts" not in str(exc.value)
 
 
@@ -3212,9 +3099,7 @@ class TestCpuFallback:
             has_physical_nvidia = False,
             has_usable_nvidia = False,
         )
-        plan = direct_upstream_release_plan(
-            release, cpu_host, "ggml-org/llama.cpp", "latest"
-        )
+        plan = direct_upstream_release_plan(release, cpu_host, "ggml-org/llama.cpp", "latest")
         assert plan.attempts[0].install_kind == "linux-arm64"
         assert plan.attempts[0].name == f"llama-{tag}-bin-ubuntu-arm64.tar.gz"
 
diff --git a/tests/studio/load_freeze/llama_server_shim.py b/tests/studio/load_freeze/llama_server_shim.py
index 1166c7521d..bb9e119820 100644
--- a/tests/studio/load_freeze/llama_server_shim.py
+++ b/tests/studio/load_freeze/llama_server_shim.py
@@ -41,7 +41,11 @@ class _Handler(BaseHTTPRequestHandler):
         self.wfile.write(payload)
 
     def _send_raw(
-        self, status: int, body: bytes, *, content_type: str = "application/json"
+        self,
+        status: int,
+        body: bytes,
+        *,
+        content_type: str = "application/json",
     ) -> None:
         self.send_response(status)
         self.send_header("Content-Type", content_type)
@@ -119,9 +123,7 @@ class _Handler(BaseHTTPRequestHandler):
                 self._send_raw(srv.config.detok_status, srv.config.detok_body)
                 return
             tids = body.get("tokens") or []
-            content = "".join(
-                srv.config.detok_map.get(int(t), f"<tok_{t}>") for t in tids
-            )
+            content = "".join(srv.config.detok_map.get(int(t), f"<tok_{t}>") for t in tids)
             self._send_json(srv.config.detok_status, {"content": content})
             return
         if path == "/completion":
@@ -224,9 +226,7 @@ class FakeLlamaServer:
     def start(self) -> "FakeLlamaServer":
         # port=0 lets ThreadingHTTPServer pick a free port atomically
         # (avoids find-port-then-bind race); read back via server_address[1].
-        self._server = FakeLlamaServer._Server(
-            (self.host, self._requested_port), _Handler
-        )
+        self._server = FakeLlamaServer._Server((self.host, self._requested_port), _Handler)
         self._server.config = self.config
         bound_port = self._server.server_address[1]
         self._thread = threading.Thread(
diff --git a/tests/studio/load_freeze/test_load_orchestrator.py b/tests/studio/load_freeze/test_load_orchestrator.py
index 91b70f0b03..b76c4c361b 100644
--- a/tests/studio/load_freeze/test_load_orchestrator.py
+++ b/tests/studio/load_freeze/test_load_orchestrator.py
@@ -103,14 +103,18 @@ def _free_port() -> int:
 
 
 class _UvicornServerThread:
-    def __init__(self, app, *, host: str = "127.0.0.1", port: int) -> None:
+    def __init__(
+        self,
+        app,
+        *,
+        host: str = "127.0.0.1",
+        port: int,
+    ) -> None:
         import uvicorn
 
         self.host = host
         self.port = port
-        cfg = uvicorn.Config(
-            app, host = host, port = port, log_level = "warning", access_log = False
-        )
+        cfg = uvicorn.Config(app, host = host, port = port, log_level = "warning", access_log = False)
         self._server = uvicorn.Server(cfg)
         self._server.install_signal_handlers = lambda: None  # type: ignore[assignment]
         self._thread: threading.Thread | None = None
@@ -169,7 +173,12 @@ def _build_app(backend, *, wrap_in_thread: bool):
     return app
 
 
-def _drive_concurrent_probe_and_health(base_url, *, n_health = 12, gap = 0.05):
+def _drive_concurrent_probe_and_health(
+    base_url,
+    *,
+    n_health = 12,
+    gap = 0.05,
+):
     elapsed = -1.0
     latencies: list[float] = []
 
@@ -211,9 +220,7 @@ def test_buggy_route_blocks_event_loop():
         app = _build_app(backend, wrap_in_thread = False)
         port = _free_port()
         with _UvicornServerThread(app, port = port) as uv:
-            max_lat, probe_t, _ = _drive_concurrent_probe_and_health(
-                f"http://127.0.0.1:{uv.port}"
-            )
+            max_lat, probe_t, _ = _drive_concurrent_probe_and_health(f"http://127.0.0.1:{uv.port}")
     assert probe_t >= 0.5
     assert max_lat >= 0.4, f"expected >=0.4s stall, got {max_lat:.3f}s"
 
@@ -442,9 +449,7 @@ def test_50_concurrent_probes_complete_without_deadlock():
             with ThreadPoolExecutor(max_workers = 50) as pool:
                 futs = [
                     pool.submit(
-                        lambda: httpx.get(
-                            f"http://127.0.0.1:{uv.port}/probe", timeout = 30.0
-                        )
+                        lambda: httpx.get(f"http://127.0.0.1:{uv.port}/probe", timeout = 30.0)
                     )
                     for _ in range(50)
                 ]
@@ -660,7 +665,6 @@ def test_response_shape_matches_pre_fix_for_no_match():
     bodies for the no-match scenario (the dominant code path in
     practice for non-audio models)."""
     import json as _json
-
     with FakeLlamaServer(
         detok_map = {128258: "abc", 128259: "def"},
         tok_response_map = {
diff --git a/tests/studio/playwright_chat_ime_i18n.py b/tests/studio/playwright_chat_ime_i18n.py
index efcd048b44..828187d462 100644
--- a/tests/studio/playwright_chat_ime_i18n.py
+++ b/tests/studio/playwright_chat_ime_i18n.py
@@ -246,8 +246,7 @@ with sync_playwright() as p:
     dir_attr = composer.evaluate("(el) => el.getAttribute('dir')")
     if dir_attr != "auto":
         soft_fail(
-            f'composer is missing dir="auto" (got {dir_attr!r}); RTL '
-            "languages will render LTR."
+            f'composer is missing dir="auto" (got {dir_attr!r}); RTL ' "languages will render LTR."
         )
     else:
         info('composer dir="auto" present')
@@ -258,9 +257,7 @@ with sync_playwright() as p:
     _thread_src = (
         _repo_root / "studio/frontend/src/components/assistant-ui/thread.tsx"
     ).read_text()
-    _shared_src = (
-        _repo_root / "studio/frontend/src/features/chat/shared-composer.tsx"
-    ).read_text()
+    _shared_src = (_repo_root / "studio/frontend/src/features/chat/shared-composer.tsx").read_text()
     _edit_idx = _thread_src.find("aui-edit-composer-input")
     if _edit_idx == -1 or 'dir="auto"' not in _thread_src[_edit_idx : _edit_idx + 600]:
         soft_fail('edit composer source is missing dir="auto"')
@@ -269,8 +266,7 @@ with sync_playwright() as p:
     _compare_idx = _shared_src.find("Send to both models")
     if (
         _compare_idx == -1
-        or 'dir="auto"'
-        not in _shared_src[max(_compare_idx - 400, 0) : _compare_idx + 400]
+        or 'dir="auto"' not in _shared_src[max(_compare_idx - 400, 0) : _compare_idx + 400]
     ):
         soft_fail('compare composer source is missing dir="auto"')
     else:
@@ -484,9 +480,7 @@ with sync_playwright() as p:
     #     handleSubmit / blockSend guards keep refusing. The Send button stays
     #     visually enabled (watchdog has already cleared the React state); the
     #     refusal happens at form.requestSubmit() time, not at the button.
-    step(
-        "BUG REPRO: keydown re-pin after watchdog cleared composing (issue #5546 follow-up)"
-    )
+    step("BUG REPRO: keydown re-pin after watchdog cleared composing (issue #5546 follow-up)")
     clear()
     composer.click()
     composer.evaluate(
@@ -533,9 +527,7 @@ with sync_playwright() as p:
             "Form submitted after an IME keydown -- preedit text leaked "
             "through the watchdog gap (#5546 follow-up regression)."
         )
-    info(
-        f"Form submit refused after IME keydown; textarea retained {submit_probe.get('after')!r}"
-    )
+    info(f"Form submit refused after IME keydown; textarea retained {submit_probe.get('after')!r}")
     shoot("06c-keydown-repin")
     info("keydown re-pin gate PASS")
     clear()
diff --git a/tests/studio/playwright_chat_ui.py b/tests/studio/playwright_chat_ui.py
index b1279e64b9..dc62194be8 100644
--- a/tests/studio/playwright_chat_ui.py
+++ b/tests/studio/playwright_chat_ui.py
@@ -141,10 +141,7 @@ def expected_default_model():
     for node in tree.body:
         if not isinstance(node, ast.Assign):
             continue
-        if not any(
-            isinstance(t, ast.Name) and t.id == "DEFAULT_MODELS_GGUF"
-            for t in node.targets
-        ):
+        if not any(isinstance(t, ast.Name) and t.id == "DEFAULT_MODELS_GGUF" for t in node.targets):
             continue
         try:
             models = ast.literal_eval(node.value)
@@ -321,9 +318,7 @@ with sync_playwright() as p:
     form_err: Exception | None = None
     for _form_attempt in range(3):
         try:
-            page.goto(
-                f"{BASE}/change-password", wait_until = "domcontentloaded", timeout = 60_000
-            )
+            page.goto(f"{BASE}/change-password", wait_until = "domcontentloaded", timeout = 60_000)
             try:
                 page.wait_for_load_state("networkidle", timeout = 30_000)
             except Exception:
@@ -382,9 +377,7 @@ with sync_playwright() as p:
                     flush = True,
                 )
             if page_errors:
-                print(
-                    f"[ui]   first pageerror:    {page_errors[0][:200]!r}", flush = True
-                )
+                print(f"[ui]   first pageerror:    {page_errors[0][:200]!r}", flush = True)
             try:
                 shoot(f"01-change-password-attempt-{_form_attempt + 1}-fail")
             except Exception:
@@ -458,9 +451,7 @@ with sync_playwright() as p:
                     flush = True,
                 )
             if page_errors:
-                print(
-                    f"[ui]   first pageerror:    {page_errors[0][:200]!r}", flush = True
-                )
+                print(f"[ui]   first pageerror:    {page_errors[0][:200]!r}", flush = True)
             try:
                 shoot(f"03-composer-wait-attempt-{_attempt + 1}-fail")
             except Exception:
@@ -557,9 +548,7 @@ with sync_playwright() as p:
     try:
         sel_text = (selector_btn.text_content(timeout = 2_000) or "").strip()
     except Exception as _sel_err:
-        info(
-            f"WARN: model-selector probe skipped: {type(_sel_err).__name__}: {_sel_err}"
-        )
+        info(f"WARN: model-selector probe skipped: {type(_sel_err).__name__}: {_sel_err}")
     if sel_text:
         info(f"model selector button text: {sel_text!r}")
         shoot("03b-default-model-button")
@@ -595,10 +584,7 @@ with sync_playwright() as p:
     if load_resp.get("error"):
         fail(f"/api/inference/load wedged: {load_resp['error']!r}")
     if load_resp["status"] != 200:
-        fail(
-            f"/api/inference/load returned {load_resp['status']}: "
-            f"{load_resp.get('body')!r}"
-        )
+        fail(f"/api/inference/load returned {load_resp['status']}: " f"{load_resp.get('body')!r}")
     info(f"loaded model: {(load_resp['body'] or {}).get('display_name')}")
 
     # Studio caches the per-context model state in zustand; reload
@@ -845,8 +831,7 @@ with sync_playwright() as p:
         # Look for either "Disable X" or "Enable X" -- whichever
         # is currently rendered.
         toggle = page.locator(
-            f'button[aria-label="Disable {feature}"], '
-            f'button[aria-label="Enable {feature}"]'
+            f'button[aria-label="Disable {feature}"], ' f'button[aria-label="Enable {feature}"]'
         ).first
         if toggle.count() == 0:
             info(f"toggle '{feature}' not present on this layout")
@@ -862,8 +847,7 @@ with sync_playwright() as p:
         page.wait_for_timeout(200)
         after = (
             page.locator(
-                f'button[aria-label="Disable {feature}"], '
-                f'button[aria-label="Enable {feature}"]'
+                f'button[aria-label="Disable {feature}"], ' f'button[aria-label="Enable {feature}"]'
             ).first.get_attribute("aria-label")
             or ""
         )
@@ -874,8 +858,7 @@ with sync_playwright() as p:
         # Flip back so test state is unchanged.
         try:
             page.locator(
-                f'button[aria-label="Disable {feature}"], '
-                f'button[aria-label="Enable {feature}"]'
+                f'button[aria-label="Disable {feature}"], ' f'button[aria-label="Enable {feature}"]'
             ).first.click()
         except Exception:
             pass
@@ -968,8 +951,7 @@ with sync_playwright() as p:
                 except Exception as exc:
                     if attempt == 1:
                         soft_fail(
-                            f"theme cycle {cycle + 1}: account-menu click failed "
-                            f"({exc!r})"
+                            f"theme cycle {cycle + 1}: account-menu click failed " f"({exc!r})"
                         )
                     continue
                 try:
@@ -1020,8 +1002,7 @@ with sync_playwright() as p:
             if click_err is not None:
                 page.keyboard.press("Escape")
                 soft_fail(
-                    f"theme cycle {cycle + 1}: theme menuitem click failed "
-                    f"({click_err!r})"
+                    f"theme cycle {cycle + 1}: theme menuitem click failed " f"({click_err!r})"
                 )
                 break
             # Settle. The ".dark" class on <html> is the ground
@@ -1078,9 +1059,7 @@ with sync_playwright() as p:
         # progressively more permissive locators so the test stays
         # green on both platforms.
         candidates = [
-            page.get_by_role(
-                "button", name = re.compile(rf"^\s*{label}\s*$", re.I)
-            ).first,
+            page.get_by_role("button", name = re.compile(rf"^\s*{label}\s*$", re.I)).first,
             page.locator(f'button:has-text("{label}")').first,
             page.locator(f'a:has-text("{label}")').first,
             page.locator(f'[data-sidebar="menu-button"]:has-text("{label}")').first,
@@ -1116,15 +1095,11 @@ with sync_playwright() as p:
     click_nav("New Chat", r"/chat")
     shoot("11-new-chat")
     # Compare moved into the composer + menu (Tools and attachments).
-    plus_btn = page.get_by_role(
-        "button", name = re.compile(r"Tools and attachments", re.I)
-    ).first
+    plus_btn = page.get_by_role("button", name = re.compile(r"Tools and attachments", re.I)).first
     if plus_btn.count() > 0:
         plus_btn.click(force = True)
         page.wait_for_timeout(400)
-        compare_item = page.get_by_role(
-            "menuitem", name = re.compile(r"Compare chat", re.I)
-        ).first
+        compare_item = page.get_by_role("menuitem", name = re.compile(r"Compare chat", re.I)).first
         if compare_item.count() > 0:
             compare_item.click(force = True)
             page.wait_for_timeout(800)
@@ -1159,9 +1134,7 @@ with sync_playwright() as p:
         step("Developer (API) tab via account menu")
         acct.click()
         page.wait_for_timeout(400)
-        dev = page.get_by_role(
-            "menuitem", name = re.compile(r"developer|api", re.I)
-        ).first
+        dev = page.get_by_role("menuitem", name = re.compile(r"developer|api", re.I)).first
         if dev.count() > 0:
             dev.click()
             page.wait_for_timeout(800)
@@ -1178,9 +1151,7 @@ with sync_playwright() as p:
                 re.compile(r"api keys|developer", re.I),
             ).first
             if keys_section.count() > 0:
-                info(
-                    f"OK API tab text: {(keys_section.text_content() or '').strip()[:80]!r}"
-                )
+                info(f"OK API tab text: {(keys_section.text_content() or '').strip()[:80]!r}")
             # Close dialog with Escape.
             page.keyboard.press("Escape")
             page.wait_for_timeout(300)
@@ -1198,9 +1169,7 @@ with sync_playwright() as p:
     page.wait_for_timeout(1500)
     # Recipe cards are rendered as <a> or button elements; count
     # all clickable headings under main + screenshot.
-    headings = page.locator(
-        "main h2, main h3, [data-recipe], a[href*='/data-recipes/']"
-    )
+    headings = page.locator("main h2, main h3, [data-recipe], a[href*='/data-recipes/']")
     n_cards = headings.count()
     info(f"Recipes route headings/cards: {n_cards}")
     shoot("15b-recipes-cards")
@@ -1289,10 +1258,7 @@ with sync_playwright() as p:
             info(f"recent-thread click {i} failed: {_click_err!s}")
             continue
     if not clicked_recent:
-        soft_fail(
-            f"no Recents entry was clickable within 30s deadline "
-            f"(n_threads={n_threads})"
-        )
+        soft_fail(f"no Recents entry was clickable within 30s deadline " f"(n_threads={n_threads})")
     # Back to chat.
     page.goto(f"{BASE}/chat")
     composer = page.locator('textarea[aria-label="Message input"]')
diff --git a/tests/studio/playwright_extra_ui.py b/tests/studio/playwright_extra_ui.py
index 0ac9f67a7e..20c7bda87c 100644
--- a/tests/studio/playwright_extra_ui.py
+++ b/tests/studio/playwright_extra_ui.py
@@ -170,9 +170,7 @@ with sync_playwright() as p:
     form_err: Exception | None = None
     for _form_attempt in range(3):
         try:
-            page.goto(
-                f"{BASE}/change-password", wait_until = "domcontentloaded", timeout = 60_000
-            )
+            page.goto(f"{BASE}/change-password", wait_until = "domcontentloaded", timeout = 60_000)
             try:
                 page.wait_for_load_state("networkidle", timeout = 30_000)
             except Exception:
@@ -329,15 +327,11 @@ with sync_playwright() as p:
     step("Compare tab: send to two panes")
     # Compare moved into the composer + menu (Tools and attachments).
     compare_opened = False
-    plus_btn = page.get_by_role(
-        "button", name = re.compile(r"Tools and attachments", re.I)
-    ).first
+    plus_btn = page.get_by_role("button", name = re.compile(r"Tools and attachments", re.I)).first
     if plus_btn.count() > 0:
         plus_btn.click(force = True)
         page.wait_for_timeout(400)
-        compare_item = page.get_by_role(
-            "menuitem", name = re.compile(r"Compare chat", re.I)
-        ).first
+        compare_item = page.get_by_role("menuitem", name = re.compile(r"Compare chat", re.I)).first
         if compare_item.count() > 0:
             compare_item.click(force = True)
             compare_opened = True
@@ -416,9 +410,7 @@ with sync_playwright() as p:
                         arg = ok_count_before + 4,
                         timeout = 60_000,
                     )
-                    info(
-                        "OK Compare: 4 total new assistant bubbles after second prompt"
-                    )
+                    info("OK Compare: 4 total new assistant bubbles after second prompt")
                 except Exception as exc:
                     runtime_warn(
                         f"Compare: 4 bubbles didn't appear (panes likely "
@@ -439,9 +431,7 @@ with sync_playwright() as p:
     page.wait_for_timeout(1500)
     shoot("05-recipes-list")
     # Template cards render as <button> elements.
-    templates = page.locator("main button").filter(
-        has_not_text = re.compile(r"^(\+|Create)")
-    )
+    templates = page.locator("main button").filter(has_not_text = re.compile(r"^(\+|Create)"))
     n_templates = templates.count()
     info(f"recipe templates visible: {n_templates}")
     if n_templates == 0:
@@ -475,9 +465,7 @@ with sync_playwright() as p:
     shoot("07-export")
     if chat_only:
         if "/export" in page.url:
-            soft_fail(
-                f"chat-only mode should redirect /export -> /chat; url={page.url}"
-            )
+            soft_fail(f"chat-only mode should redirect /export -> /chat; url={page.url}")
         else:
             info(f"OK chat-only redirected /export -> {page.url}")
     else:
@@ -527,16 +515,12 @@ with sync_playwright() as p:
     shoot("08-studio")
     if chat_only:
         if "/studio" in page.url:
-            soft_fail(
-                f"chat-only mode should redirect /studio -> /chat; url={page.url}"
-            )
+            soft_fail(f"chat-only mode should redirect /studio -> /chat; url={page.url}")
         else:
             info(f"OK chat-only redirected /studio -> {page.url}")
     else:
         for tab_name in ("Configure", "Current run", "History"):
-            tab = page.get_by_role(
-                "tab", name = re.compile(rf"^\s*{tab_name}\s*$", re.I)
-            ).first
+            tab = page.get_by_role("tab", name = re.compile(rf"^\s*{tab_name}\s*$", re.I)).first
             if tab.count() == 0:
                 soft_fail(f"tab '{tab_name}' not found in /studio")
             else:
@@ -598,9 +582,7 @@ with sync_playwright() as p:
                     info(f"OK Settings tab '{tab_name}' body length={body_text}")
                     seen_tabs.append(tab_name)
                 else:
-                    soft_fail(
-                        f"Settings tab '{tab_name}' body suspiciously short: {body_text}"
-                    )
+                    soft_fail(f"Settings tab '{tab_name}' body suspiciously short: {body_text}")
             except Exception as exc:
                 soft_fail(f"Settings tab '{tab_name}' click failed: {exc!r}")
         shoot("10-settings-tabs-visited")
diff --git a/tests/studio/run_real_mlx_smoke.py b/tests/studio/run_real_mlx_smoke.py
index dc3001fd99..3b494a4272 100644
--- a/tests/studio/run_real_mlx_smoke.py
+++ b/tests/studio/run_real_mlx_smoke.py
@@ -103,9 +103,7 @@ def _peak_gpu_gb() -> float:
     # top-level mx.get_peak_memory; fall back to the old API for
     # compatibility with older MLX versions still present in the
     # environment.
-    getter = getattr(mx, "get_peak_memory", None) or getattr(
-        mx.metal, "get_peak_memory", None
-    )
+    getter = getattr(mx, "get_peak_memory", None) or getattr(mx.metal, "get_peak_memory", None)
     if getter is None:
         return 0.0
     try:
@@ -186,9 +184,7 @@ def _compute_loss_and_grad_norm(model, tokenizer, text: str) -> tuple[float, flo
     return float(loss_val.item()), float(mx.sqrt(norm_sq).item())
 
 
-def _teacher_forced_completion_loss(
-    model, tokenizer, prompt: str, completion: str
-) -> float:
+def _teacher_forced_completion_loss(model, tokenizer, prompt: str, completion: str) -> float:
     """Mean next-token CE loss on `completion` tokens given `prompt` (teacher
     forced -- no decoding, no sampling, no greedy argmax).
 
@@ -229,9 +225,7 @@ def _teacher_forced_completion_loss(
     start = len(prompt_ids) - 1
     completion_logits = logits[:, start:, :]
     completion_targets = targets[:, start:]
-    loss = nn.losses.cross_entropy(
-        completion_logits, completion_targets, reduction = "mean"
-    )
+    loss = nn.losses.cross_entropy(completion_logits, completion_targets, reduction = "mean")
     return float(loss.item())
 
 
@@ -364,7 +358,15 @@ def cmd_train(args) -> int:
         )
 
         def _on_step(
-            step, total, loss, lr, tok_s, peak_gb, elapsed, num_tokens, grad_norm = None
+            step,
+            total,
+            loss,
+            lr,
+            tok_s,
+            peak_gb,
+            elapsed,
+            num_tokens,
+            grad_norm = None,
         ):
             losses_per_step.append(round(float(loss), 4))
             grad_text = f"  grad={grad_norm:.4f}" if grad_norm is not None else ""
@@ -602,9 +604,7 @@ def cmd_reload(args) -> int:
             in_mem_loss = None
     metrics["in_memory_generation_ref"] = in_mem_out
     metrics["in_memory_post_train_loss"] = in_mem_loss
-    metrics["reload_completion_matches_in_memory"] = (
-        in_mem_out is not None and out == in_mem_out
-    )
+    metrics["reload_completion_matches_in_memory"] = in_mem_out is not None and out == in_mem_out
     if isinstance(in_mem_loss, (int, float)) and math.isfinite(in_mem_loss):
         reload_loss, _ = _compute_loss_and_grad_norm(m, t, TRAIN_TEXT)
         metrics["reload_post_train_loss"] = round(reload_loss, 4)
@@ -619,8 +619,7 @@ def cmd_reload(args) -> int:
         # workdir layouts): keep a non-empty-completion gate.
         body = out.replace(PROMPT, "", 1).strip()
         assert len(body) >= 4, (
-            f"reload {args.format!r} produced no usable output for "
-            f"{PROMPT!r}: {out!r}"
+            f"reload {args.format!r} produced no usable output for " f"{PROMPT!r}: {out!r}"
         )
 
     metrics["final_peak_gpu_gb"] = round(_peak_gpu_gb(), 3)
@@ -671,9 +670,7 @@ def _reload_gguf(save_dir: Path, metrics: dict) -> int:
 
     print(f"  [reload:gguf] stdout (head):\n{proc.stdout[:800]}", flush = True)
     if proc.returncode != 0:
-        raise SystemExit(
-            f"llama-cli exit {proc.returncode}; stderr head: {proc.stderr[:400]}"
-        )
+        raise SystemExit(f"llama-cli exit {proc.returncode}; stderr head: {proc.stderr[:400]}")
     # llama.cpp uses different tokenisation + sampling internals than
     # mlx_lm, so the GGUF reload completion does not have to match the
     # in-memory completion exactly. Require non-empty, non-prompt-only
@@ -683,8 +680,7 @@ def _reload_gguf(save_dir: Path, metrics: dict) -> int:
     body = (proc.stdout or "").replace(PROMPT, "", 1).strip()
     metrics["gguf_has_expected"] = EXPECT_IN_OUTPUT in (proc.stdout or "")
     assert len(body) >= 4, (
-        f"GGUF reload produced no usable output for {PROMPT!r}: "
-        f"{proc.stdout[:400]!r}"
+        f"GGUF reload produced no usable output for {PROMPT!r}: " f"{proc.stdout[:400]!r}"
     )
 
     metrics["final_peak_rss_gb"] = round(_peak_rss_gb(), 3)
diff --git a/tests/studio/studio_api_smoke.py b/tests/studio/studio_api_smoke.py
index d6718defcc..0390b39c03 100644
--- a/tests/studio/studio_api_smoke.py
+++ b/tests/studio/studio_api_smoke.py
@@ -192,9 +192,7 @@ try:
         acao = r.headers.get("Access-Control-Allow-Origin", "")
         acac = r.headers.get("Access-Control-Allow-Credentials", "")
         if acao == "*" and acac.lower() == "true":
-            fail(
-                f"CORS: wildcard origin + credentials=true (acao={acao!r}, acac={acac!r})"
-            )
+            fail(f"CORS: wildcard origin + credentials=true (acao={acao!r}, acac={acac!r})")
         else:
             ok(f"CORS preflight acao={acao!r} acac={acac!r}")
 except Exception as exc:
diff --git a/tests/studio/test_auth_form_input_count.py b/tests/studio/test_auth_form_input_count.py
index 559fb7e524..b80f59d960 100644
--- a/tests/studio/test_auth_form_input_count.py
+++ b/tests/studio/test_auth_form_input_count.py
@@ -63,10 +63,7 @@ def test_hasbootstrappassword_constant_is_derived_from_bootstrap_window_value():
     a prop) would silently drift from the backend's bootstrap-injection
     contract in studio/backend/main.py::_inject_bootstrap."""
     src = AUTH_FORM.read_text()
-    assert (
-        "const hasBootstrapPassword = Boolean(window.__UNSLOTH_BOOTSTRAP__?.password);"
-        in src
-    ), (
+    assert "const hasBootstrapPassword = Boolean(window.__UNSLOTH_BOOTSTRAP__?.password);" in src, (
         "hasBootstrapPassword constant missing or its derivation drifted; "
         "this is the gate that hides the Current password input on first boot"
     )
diff --git a/tests/studio/test_cancel_atomicity.py b/tests/studio/test_cancel_atomicity.py
index a8d4839454..ea4169f6ff 100644
--- a/tests/studio/test_cancel_atomicity.py
+++ b/tests/studio/test_cancel_atomicity.py
@@ -16,23 +16,14 @@ import threading
 from pathlib import Path
 
 
-SOURCE_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "studio"
-    / "backend"
-    / "routes"
-    / "inference.py"
-)
+SOURCE_PATH = Path(__file__).resolve().parents[2] / "studio" / "backend" / "routes" / "inference.py"
 _SRC = SOURCE_PATH.read_text()
 _TREE = ast.parse(_SRC)
 
 
 def _find_function(name: str) -> ast.FunctionDef | ast.AsyncFunctionDef:
     for node in ast.walk(_TREE):
-        if (
-            isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
-            and node.name == name
-        ):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == name:
             return node
     raise AssertionError(f"function {name!r} not found")
 
@@ -187,8 +178,7 @@ def test_parallel_cancel_vs_register_never_drops():
         tracker.__exit__(None, None, None)
 
     assert dropped == 0, (
-        f"TOCTOU regression: {dropped}/{trials} parallel trials silently "
-        f"dropped the cancel"
+        f"TOCTOU regression: {dropped}/{trials} parallel trials silently " f"dropped the cancel"
     )
 
 
diff --git a/tests/studio/test_cancel_id_wiring.py b/tests/studio/test_cancel_id_wiring.py
index 5fd76ded9b..b6f75c0be9 100644
--- a/tests/studio/test_cancel_id_wiring.py
+++ b/tests/studio/test_cancel_id_wiring.py
@@ -25,12 +25,8 @@ from pathlib import Path
 WORKSPACE = Path(__file__).resolve().parents[2]
 MODELS_SRC = (WORKSPACE / "studio/backend/models/inference.py").read_text()
 ROUTES_SRC = (WORKSPACE / "studio/backend/routes/inference.py").read_text()
-ADAPTER_SRC = (
-    WORKSPACE / "studio/frontend/src/features/chat/api/chat-adapter.ts"
-).read_text()
-API_TYPES_SRC = (
-    WORKSPACE / "studio/frontend/src/features/chat/types/api.ts"
-).read_text()
+ADAPTER_SRC = (WORKSPACE / "studio/frontend/src/features/chat/api/chat-adapter.ts").read_text()
+API_TYPES_SRC = (WORKSPACE / "studio/frontend/src/features/chat/types/api.ts").read_text()
 
 
 def _find_class(tree: ast.AST, name: str) -> ast.ClassDef | None:
@@ -49,10 +45,9 @@ def test_chat_completion_request_has_cancel_id_field():
         for n in cls.body
         if isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name)
     }
-    assert "cancel_id" in fields, (
-        "ChatCompletionRequest must expose a cancel_id field for per-run "
-        "cancellation routing"
-    )
+    assert (
+        "cancel_id" in fields
+    ), "ChatCompletionRequest must expose a cancel_id field for per-run cancellation routing"
 
 
 def test_cancel_route_matches_cancel_id_exclusively_when_present():
@@ -117,9 +112,7 @@ def test_chat_adapter_generates_cancel_id_per_run():
     )
     assert m, "chat-adapter.ts must declare a per-run `cancelId` constant"
     rhs = m.group(1)
-    assert (
-        "randomUUID" in rhs
-    ), "cancelId should prefer crypto.randomUUID() for uniqueness"
+    assert "randomUUID" in rhs, "cancelId should prefer crypto.randomUUID() for uniqueness"
 
 
 def test_chat_adapter_sends_cancel_id_in_completion_payload():
diff --git a/tests/studio/test_chat_preset_builtin_invariants.py b/tests/studio/test_chat_preset_builtin_invariants.py
index 16434ff7e8..3ca09dadda 100644
--- a/tests/studio/test_chat_preset_builtin_invariants.py
+++ b/tests/studio/test_chat_preset_builtin_invariants.py
@@ -17,9 +17,7 @@ def _source_path(relative_path: str) -> Path:
     return WORKDIR / "unsloth_repo" / relative_path
 
 
-PRESET_POLICY = _source_path(
-    "studio/frontend/src/features/chat/presets/preset-policy.ts"
-)
+PRESET_POLICY = _source_path("studio/frontend/src/features/chat/presets/preset-policy.ts")
 RUNTIME_TYPES = _source_path("studio/frontend/src/features/chat/types/runtime.ts")
 TEMP = WORKDIR / "temp" / "chat_preset_builtin_invariants"
 
@@ -42,8 +40,7 @@ def _require_node():
 def _ensure_harness():
     TEMP.mkdir(parents = True, exist_ok = True)
     (TEMP / "register.mjs").write_text(
-        "import { register } from 'node:module';\n"
-        "register('./loader.mjs', import.meta.url);\n"
+        "import { register } from 'node:module';\nregister('./loader.mjs', import.meta.url);\n"
     )
     (TEMP / "loader.mjs").write_text(
         "export function resolve(specifier, context, next) {\n"
diff --git a/tests/studio/test_cli_repo_variant.py b/tests/studio/test_cli_repo_variant.py
index 1aa21cfd7d..21f935965f 100644
--- a/tests/studio/test_cli_repo_variant.py
+++ b/tests/studio/test_cli_repo_variant.py
@@ -42,12 +42,8 @@ def _load_split_repo_variant():
         typer_stub.echo = lambda *args, **kwargs: None
         sys.modules["typer"] = typer_stub
 
-    studio_py = (
-        Path(__file__).resolve().parents[2] / "unsloth_cli" / "commands" / "studio.py"
-    )
-    spec = importlib.util.spec_from_file_location(
-        "_studio_for_repo_variant_test", studio_py
-    )
+    studio_py = Path(__file__).resolve().parents[2] / "unsloth_cli" / "commands" / "studio.py"
+    spec = importlib.util.spec_from_file_location("_studio_for_repo_variant_test", studio_py)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
     return module._split_repo_variant
diff --git a/tests/studio/test_cli_run_alias.py b/tests/studio/test_cli_run_alias.py
index aed6361ee2..c69cad9bb8 100644
--- a/tests/studio/test_cli_run_alias.py
+++ b/tests/studio/test_cli_run_alias.py
@@ -38,9 +38,7 @@ def test_top_level_run_alias_registered():
         # Decorator-call form has a string literal "run" as the first
         # positional or as keyword ``name="run"``.
         first_pos = call.args[0] if call.args else None
-        keyword_name = next(
-            (kw.value for kw in call.keywords if kw.arg == "name"), None
-        )
+        keyword_name = next((kw.value for kw in call.keywords if kw.arg == "name"), None)
         is_run = (isinstance(first_pos, ast.Constant) and first_pos.value == "run") or (
             isinstance(keyword_name, ast.Constant) and keyword_name.value == "run"
         )
@@ -66,4 +64,6 @@ def test_studio_run_imported_for_alias():
             if alias.name == "run":
                 has_import = True
                 break
-    assert has_import, "Expected `from unsloth_cli.commands.studio import run` in unsloth_cli/__init__.py"
+    assert (
+        has_import
+    ), "Expected `from unsloth_cli.commands.studio import run` in unsloth_cli/__init__.py"
diff --git a/tests/studio/test_cli_studio_defaults.py b/tests/studio/test_cli_studio_defaults.py
index 4d6f28f075..a83a62f586 100644
--- a/tests/studio/test_cli_studio_defaults.py
+++ b/tests/studio/test_cli_studio_defaults.py
@@ -7,9 +7,7 @@ full unsloth_cli dependencies (typer/pydantic) at test-collection time.
 import ast
 from pathlib import Path
 
-_STUDIO_CMD_PY = (
-    Path(__file__).resolve().parents[2] / "unsloth_cli" / "commands" / "studio.py"
-)
+_STUDIO_CMD_PY = Path(__file__).resolve().parents[2] / "unsloth_cli" / "commands" / "studio.py"
 
 
 def _find_typer_option_default(source: str, func_name: str, long_option: str):
@@ -78,9 +76,7 @@ def test_studio_run_host_is_loopback():
     """`unsloth studio run` --host typer Option default must be 127.0.0.1."""
     source = _STUDIO_CMD_PY.read_text()
     host_default = _find_typer_option_default(source, "run", "--host")
-    assert (
-        host_default is not None
-    ), "Could not find --host typer.Option default in run()"
+    assert host_default is not None, "Could not find --host typer.Option default in run()"
     assert host_default == "127.0.0.1", (
         f"`unsloth studio run` --host default must be '127.0.0.1' (loopback) "
         f"but got '{host_default}'."
diff --git a/tests/studio/test_composer_rtl_bidi_attribute.py b/tests/studio/test_composer_rtl_bidi_attribute.py
index 1e2f0d0cf4..e4273c8731 100644
--- a/tests/studio/test_composer_rtl_bidi_attribute.py
+++ b/tests/studio/test_composer_rtl_bidi_attribute.py
@@ -19,7 +19,11 @@ WORKFLOW_YML = REPO / ".github/workflows/studio-ui-smoke.yml"
 IME_PY = REPO / "tests/studio/playwright_chat_ime_i18n.py"
 
 
-def _block_around(src: str, anchor: str, radius: int = 600) -> str:
+def _block_around(
+    src: str,
+    anchor: str,
+    radius: int = 600,
+) -> str:
     idx = src.find(anchor)
     assert idx != -1, f"anchor {anchor!r} not found"
     return src[max(idx - radius, 0) : idx + radius]
@@ -83,9 +87,9 @@ def test_main_composer_has_stuck_compositionend_watchdog():
     composing flag once events go silent; without it Send stays disabled
     forever and CJK input is effectively dropped."""
     src = THREAD_TSX.read_text()
-    assert "IME_STUCK_TIMEOUT_MS" in src, (
-        "main composer is missing the stuck-compositionend watchdog " "(issue #5546)"
-    )
+    assert (
+        "IME_STUCK_TIMEOUT_MS" in src
+    ), "main composer is missing the stuck-compositionend watchdog (issue #5546)"
     assert "onCompositionUpdate" in src, (
         "main composer is missing onCompositionUpdate wiring; the "
         "watchdog only resets while the IME is actively emitting events"
@@ -94,12 +98,10 @@ def test_main_composer_has_stuck_compositionend_watchdog():
 
 def test_compare_composer_has_stuck_compositionend_watchdog():
     src = SHARED_TSX.read_text()
-    assert "IME_STUCK_TIMEOUT_MS" in src, (
-        "compare composer is missing the stuck-compositionend watchdog " "(issue #5546)"
-    )
     assert (
-        "onCompositionUpdate" in src
-    ), "compare composer is missing onCompositionUpdate wiring"
+        "IME_STUCK_TIMEOUT_MS" in src
+    ), "compare composer is missing the stuck-compositionend watchdog (issue #5546)"
+    assert "onCompositionUpdate" in src, "compare composer is missing onCompositionUpdate wiring"
 
 
 def test_main_composer_keydown_repins_composing_during_ime():
@@ -125,7 +127,12 @@ def test_compare_composer_keydown_repins_composing_during_ime():
     )
 
 
-def _extract_block(src: str, anchor: str, opener: str = "(", closer: str = ")") -> str:
+def _extract_block(
+    src: str,
+    anchor: str,
+    opener: str = "(",
+    closer: str = ")",
+) -> str:
     """Return the source between the first balanced opener/closer that
     starts at or after `anchor`. Used to scope assertions to a specific
     handler so a re-arm call in some other function does not satisfy
diff --git a/tests/studio/test_export_output_path_contract.py b/tests/studio/test_export_output_path_contract.py
index e99fc42091..8b2f829146 100644
--- a/tests/studio/test_export_output_path_contract.py
+++ b/tests/studio/test_export_output_path_contract.py
@@ -68,9 +68,7 @@ def test_local_save_assigns_output_path():
                     if isinstance(tgt, ast.Name) and tgt.id == "output_path":
                         assigns.append(node)
         non_none = [
-            a
-            for a in assigns
-            if not (isinstance(a.value, ast.Constant) and a.value.value is None)
+            a for a in assigns if not (isinstance(a.value, ast.Constant) and a.value.value is None)
         ]
         assert non_none, f"{fn_name} never assigns a non-None output_path"
 
@@ -86,9 +84,7 @@ def test_gpu_save_method_bound_for_hub_only():
                 if isinstance(stmt, ast.If):
                     test = stmt.test
                     if isinstance(test, ast.Name) and test.id == "_IS_MLX":
-                        for sub in ast.walk(
-                            ast.Module(body = stmt.orelse, type_ignores = [])
-                        ):
+                        for sub in ast.walk(ast.Module(body = stmt.orelse, type_ignores = [])):
                             if isinstance(sub, ast.Assign) and any(
                                 isinstance(t, ast.Name) and t.id == "save_method"
                                 for t in sub.targets
diff --git a/tests/studio/test_frontend_dep_removal.py b/tests/studio/test_frontend_dep_removal.py
index a8e4cda8b7..138ffb4ba0 100644
--- a/tests/studio/test_frontend_dep_removal.py
+++ b/tests/studio/test_frontend_dep_removal.py
@@ -90,8 +90,7 @@ CASES: list[Case] = [
     ),
     Case(
         "C8",
-        "multi-remove with mixed safety: next-themes + "
-        "@huggingface/hub + dexie all unsafe",
+        "multi-remove with mixed safety: next-themes + @huggingface/hub + dexie all unsafe",
         ["next-themes", "@huggingface/hub", "dexie"],
         "FAIL",
         ["next-themes", "@huggingface/hub", "dexie"],
@@ -119,8 +118,7 @@ CASES: list[Case] = [
     ),
     Case(
         "C12",
-        "moving @hugeicons/react from deps to devDeps is NOT a "
-        "removal (still declared)",
+        "moving @hugeicons/react from deps to devDeps is NOT a removal (still declared)",
         [],
         "PASS",
         [],
@@ -136,7 +134,7 @@ CASES: list[Case] = [
     ),
     Case(
         "C14",
-        "removing dexie breaks src imports (no other declared " "dep needs it)",
+        "removing dexie breaks src imports (no other declared dep needs it)",
         ["dexie"],
         "FAIL",
         ["dexie"],
@@ -151,14 +149,14 @@ CASES: list[Case] = [
     ),
     Case(
         "C16",
-        "removing canvas-confetti (imported in confetti.tsx); " "no transitive parent",
+        "removing canvas-confetti (imported in confetti.tsx); no transitive parent",
         ["canvas-confetti"],
         "FAIL",
         ["canvas-confetti"],
     ),
     Case(
         "C17",
-        "removing recharts (imported in chart.tsx); no transitive " "parent",
+        "removing recharts (imported in chart.tsx); no transitive parent",
         ["recharts"],
         "FAIL",
         ["recharts"],
@@ -173,36 +171,35 @@ CASES: list[Case] = [
     ),
     Case(
         "C19",
-        "removing node-forge (imported in providers-api.ts); " "no transitive parent",
+        "removing node-forge (imported in providers-api.ts); no transitive parent",
         ["node-forge"],
         "FAIL",
         ["node-forge"],
     ),
     Case(
         "C20",
-        "removing @tauri-apps/api is safe: all 5 @tauri-apps "
-        "plugins declare it as a direct dep",
+        "removing @tauri-apps/api is safe: all 5 @tauri-apps plugins declare it as a direct dep",
         ["@tauri-apps/api"],
         "PASS",
         [],
     ),
     Case(
         "C21",
-        "removing mammoth (imported in runtime-provider.tsx); " "no transitive parent",
+        "removing mammoth (imported in runtime-provider.tsx); no transitive parent",
         ["mammoth"],
         "FAIL",
         ["mammoth"],
     ),
     Case(
         "C22",
-        "removing unpdf (imported in runtime-provider.tsx); " "no transitive parent",
+        "removing unpdf (imported in runtime-provider.tsx); no transitive parent",
         ["unpdf"],
         "FAIL",
         ["unpdf"],
     ),
     Case(
         "C23",
-        "removing remark-gfm is safe: streamdown declares it " "as a direct dep",
+        "removing remark-gfm is safe: streamdown declares it as a direct dep",
         ["remark-gfm"],
         "PASS",
         [],
@@ -310,9 +307,7 @@ def run_case(case: Case, head_pkg: dict) -> tuple[bool, str]:
         if in_summary and line.strip().startswith("- "):
             failure_pkgs.append(line.strip()[2:])
 
-    ok = actual_status == case.expected_status and set(failure_pkgs) == set(
-        case.expected_failures
-    )
+    ok = actual_status == case.expected_status and set(failure_pkgs) == set(case.expected_failures)
     return ok, (
         f"expected: status={case.expected_status} fails={sorted(case.expected_failures)}\n"
         f"actual:   status={actual_status} fails={sorted(failure_pkgs)}\n"
@@ -532,8 +527,7 @@ CLASSIFY_CASES: list[ClassifyCase] = [
     ),
     ClassifyCase(
         "U23",
-        "package name in Python file (ignored, "
-        "Python can never import npm packages)",
+        "package name in Python file (ignored, Python can never import npm packages)",
         "playwright",
         "tests/x.py",
         'label: str = "playwright"',
@@ -854,7 +848,7 @@ ADV_CASES: list[AdvCase] = [
     ),
     AdvCase(
         "A10",
-        "package referenced only in a Python file should " "NOT trigger a JS FAIL",
+        "package referenced only in a Python file should NOT trigger a JS FAIL",
         "adv10.py",
         'label = "__adv_only_pkg_j__"\n',
         "__adv_only_pkg_j__",
@@ -863,8 +857,7 @@ ADV_CASES: list[AdvCase] = [
     ),
     AdvCase(
         "A11",
-        "package mentioned in a markdown doc file is "
-        "ignored by JS-like-only string_literal",
+        "package mentioned in a markdown doc file is ignored by JS-like-only string_literal",
         "adv11.md",
         "See [docs](https://example.com/__adv_only_pkg_k__).\n",
         "__adv_only_pkg_k__",
@@ -1117,9 +1110,7 @@ def run_pkg_field_cases() -> int:
         finally:
             os.unlink(base_path)
             os.unlink(head_path)
-        actual_status = {0: "PASS", 1: "FAIL"}.get(
-            proc.returncode, f"RC{proc.returncode}"
-        )
+        actual_status = {0: "PASS", 1: "FAIL"}.get(proc.returncode, f"RC{proc.returncode}")
         fails: list[str] = []
         in_summary = False
         for line in proc.stdout.splitlines():
@@ -1130,15 +1121,11 @@ def run_pkg_field_cases() -> int:
                 fails.append(line.strip()[2:])
         # The expected_failures includes the tolerated-FP case (P15); we
         # accept BOTH expected_status and expected_failures matches.
-        ok = actual_status == pc.expected_status and set(fails) == set(
-            pc.expected_failures
-        )
+        ok = actual_status == pc.expected_status and set(fails) == set(pc.expected_failures)
         mark = "PASS" if ok else "FAIL"
         print(f"  [{mark}] {pc.id}: {pc.desc}")
         if not ok:
-            print(
-                f"      expected: status={pc.expected_status} fails={pc.expected_failures}"
-            )
+            print(f"      expected: status={pc.expected_status} fails={pc.expected_failures}")
             print(f"      actual:   status={actual_status} fails={fails}")
             for ln in proc.stdout.splitlines()[:25]:
                 print(f"      {ln}")
@@ -1184,9 +1171,7 @@ def run_adversarial_cases() -> int:
                 )
             finally:
                 os.unlink(base_path)
-            actual_status = {0: "PASS", 1: "FAIL"}.get(
-                proc.returncode, f"RC{proc.returncode}"
-            )
+            actual_status = {0: "PASS", 1: "FAIL"}.get(proc.returncode, f"RC{proc.returncode}")
             fails = []
             in_summary = False
             for line in proc.stdout.splitlines():
@@ -1195,15 +1180,11 @@ def run_adversarial_cases() -> int:
                     continue
                 if in_summary and line.strip().startswith("- "):
                     fails.append(line.strip()[2:])
-            ok = actual_status == ac.expected_status and set(fails) == set(
-                ac.expected_failures
-            )
+            ok = actual_status == ac.expected_status and set(fails) == set(ac.expected_failures)
             mark = "PASS" if ok else "FAIL"
             print(f"  [{mark}] {ac.id}: {ac.desc}")
             if not ok:
-                print(
-                    f"      expected: status={ac.expected_status} fails={ac.expected_failures}"
-                )
+                print(f"      expected: status={ac.expected_status} fails={ac.expected_failures}")
                 print(f"      actual:   status={actual_status} fails={fails}")
                 for ln in proc.stdout.splitlines()[:20]:
                     print(f"      {ln}")
@@ -1385,9 +1366,7 @@ def run_enum_cases() -> int:
         if not ok:
             print(f"      expected unused superset: {sorted(ec.expected_unused)}")
             print(f"      expected used NOT in unused: {sorted(ec.expected_used)}")
-            print(
-                f"      expected orphans superset: {sorted(ec.expected_orphan_types)}"
-            )
+            print(f"      expected orphans superset: {sorted(ec.expected_orphan_types)}")
             print(f"      actual unused: {sorted(unused)}")
             print(f"      actual orphans: {sorted(orphans)}")
             for ln in proc.stdout.splitlines()[:30]:
diff --git a/tests/studio/test_hardware_dispatch_matrix.py b/tests/studio/test_hardware_dispatch_matrix.py
index 8b71409155..8864075dd7 100644
--- a/tests/studio/test_hardware_dispatch_matrix.py
+++ b/tests/studio/test_hardware_dispatch_matrix.py
@@ -60,17 +60,13 @@ class HardwareProfile:
     system: str  # platform.system() value
     machine: str  # platform.machine() value
     cuda_available: bool  # torch.cuda.is_available() value
-    hip_version: Optional[
-        str
-    ]  # torch.version.hip; None for NVIDIA, "6.1" etc. for ROCm
+    hip_version: Optional[str]  # torch.version.hip; None for NVIDIA, "6.1" etc. for ROCm
     xpu_available: bool  # torch.xpu.is_available() value
     has_mlx: bool  # whether to inject a fake mlx into sys.modules
     mps_available: bool  # torch.backends.mps.is_available() value
 
     expect_is_mlx: bool  # unsloth._IS_MLX
-    expect_device_type: (
-        str  # Studio DeviceType (uppercased name: "CUDA"/"XPU"/"MLX"/"CPU")
-    )
+    expect_device_type: str  # Studio DeviceType (uppercased name: "CUDA"/"XPU"/"MLX"/"CPU")
     expect_is_rocm: bool  # Studio IS_ROCM
     expect_apple_silicon: bool  # Studio is_apple_silicon()
     extra_notes: str = ""
@@ -231,9 +227,7 @@ def spoof_hardware(monkeypatch):
         # Real torch.xpu.get_device_name requires the XPU-compiled torch build,
         # so always stub it under the spoof to keep tests hardware-agnostic.
         if hasattr(torch, "xpu"):
-            monkeypatch.setattr(
-                torch.xpu, "is_available", lambda: profile.xpu_available
-            )
+            monkeypatch.setattr(torch.xpu, "is_available", lambda: profile.xpu_available)
             monkeypatch.setattr(
                 torch.xpu,
                 "get_device_name",
@@ -249,9 +243,7 @@ def spoof_hardware(monkeypatch):
 
         # torch.backends.mps.is_available
         if hasattr(torch.backends, "mps"):
-            monkeypatch.setattr(
-                torch.backends.mps, "is_available", lambda: profile.mps_available
-            )
+            monkeypatch.setattr(torch.backends.mps, "is_available", lambda: profile.mps_available)
 
         # mlx + mlx.core in sys.modules
         if profile.has_mlx:
@@ -283,11 +275,15 @@ def spoof_hardware(monkeypatch):
             # it via a meta_path finder that raises ImportError for any
             # `mlx` / `mlx.*` import while this profile is active.
             class _BlockMLXFinder:
-                def find_spec(self_inner, name, path = None, target = None):
+                def find_spec(
+                    self_inner,
+                    name,
+                    path = None,
+                    target = None,
+                ):
                     if name == "mlx" or name.startswith("mlx."):
                         raise ImportError(
-                            f"mlx import blocked by spoof_hardware "
-                            f"(profile={profile.name})"
+                            f"mlx import blocked by spoof_hardware " f"(profile={profile.name})"
                         )
                     return None
 
@@ -356,8 +352,7 @@ def test_studio_detect_hardware_matches_profile(profile, spoof_hardware):
         f"got {detected!r}. {profile.extra_notes}"
     )
     assert hw.IS_ROCM is profile.expect_is_rocm, (
-        f"profile {profile.name}: expected IS_ROCM={profile.expect_is_rocm}, "
-        f"got {hw.IS_ROCM}"
+        f"profile {profile.name}: expected IS_ROCM={profile.expect_is_rocm}, " f"got {hw.IS_ROCM}"
     )
 
 
diff --git a/tests/studio/test_is_mlx_dispatch_gate.py b/tests/studio/test_is_mlx_dispatch_gate.py
index 043f2796aa..4e379aa976 100644
--- a/tests/studio/test_is_mlx_dispatch_gate.py
+++ b/tests/studio/test_is_mlx_dispatch_gate.py
@@ -67,9 +67,7 @@ def test_is_mlx_gate_uses_three_required_predicates():
     assert target is not None, "_IS_MLX assignment not found in unsloth/__init__.py"
     assert isinstance(target, ast.Call), "_IS_MLX must call the shared MLX helper"
     expr_src = ast.unparse(target)
-    assert (
-        expr_src == "_is_mlx_available()"
-    ), "_IS_MLX must delegate to the shared MLX runtime gate"
+    assert expr_src == "_is_mlx_available()", "_IS_MLX must delegate to the shared MLX runtime gate"
 
     helper = None
     for node in ast.walk(tree):
@@ -166,7 +164,6 @@ def test_is_mlx_gate_false_on_non_apple_silicon():
     if platform.system() == "Darwin" and platform.machine() == "arm64":
         # On a Mac CI runner this assertion would not apply; skip there.
         import pytest
-
         pytest.skip("Test host is Apple Silicon; CUDA-side canary doesn't apply.")
 
     import os
@@ -227,11 +224,8 @@ def test_detect_hardware_picks_cuda_on_real_host():
 
     if not torch.cuda.is_available():
         import pytest
-
         pytest.skip("No CUDA available on this host; canary not applicable.")
 
     hw = _import_studio_hardware()
     detected = hw.detect_hardware()
-    assert (
-        detected == hw.DeviceType.CUDA
-    ), f"CUDA host must dispatch to CUDA, got {detected!r}"
+    assert detected == hw.DeviceType.CUDA, f"CUDA host must dispatch to CUDA, got {detected!r}"
diff --git a/tests/studio/test_stream_cancel_registration_timing.py b/tests/studio/test_stream_cancel_registration_timing.py
index 40ec3d6e1f..6906e9b7d2 100644
--- a/tests/studio/test_stream_cancel_registration_timing.py
+++ b/tests/studio/test_stream_cancel_registration_timing.py
@@ -49,13 +49,7 @@ import time
 from pathlib import Path
 
 
-SOURCE_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "studio"
-    / "backend"
-    / "routes"
-    / "inference.py"
-)
+SOURCE_PATH = Path(__file__).resolve().parents[2] / "studio" / "backend" / "routes" / "inference.py"
 SRC = SOURCE_PATH.read_text()
 _TREE = ast.parse(SRC)
 
@@ -355,13 +349,7 @@ def test_normal_path_streams_all_tokens():
     # when cancel_event is unset.
     ev = threading.Event()
     chunks = asyncio.run(_consume(_post_fix_gguf_loop(ev)))
-    assert chunks == [
-        "first_chunk",
-        "cumulative-1",
-        "cumulative-2",
-        "final_chunk",
-        "[DONE]",
-    ]
+    assert chunks == ["first_chunk", "cumulative-1", "cumulative-2", "final_chunk", "[DONE]"]
 
 
 def test_cancel_during_streaming_stops_iteration_promptly():
@@ -674,8 +662,7 @@ def test_unsloth_stream_loop_emits_zero_tokens_on_preset_cancel():
         f"(pending-replay path); got {seen}"
     )
     assert next_calls[0] == 0, (
-        f"loop must not call next() at all on pre-set cancel; got "
-        f"{next_calls[0]} calls"
+        f"loop must not call next() at all on pre-set cancel; got " f"{next_calls[0]} calls"
     )
     assert reset_calls[0] == 1, (
         f"backend.reset_generation_state() must still fire exactly once "
@@ -713,6 +700,5 @@ def test_audio_stream_emits_zero_chunks_on_preset_cancel():
     seen = asyncio.run(_loop())
     assert seen == [], f"audio loop must emit zero chunks on pre-set cancel; got {seen}"
     assert next_calls[0] == 0, (
-        f"audio loop must not call next() on pre-set cancel; got "
-        f"{next_calls[0]} calls"
+        f"audio loop must not call next() on pre-set cancel; got " f"{next_calls[0]} calls"
     )
diff --git a/tests/studio/test_studio_gguf_export_script_pin.py b/tests/studio/test_studio_gguf_export_script_pin.py
index 12aaaafff4..b97ecd4367 100644
--- a/tests/studio/test_studio_gguf_export_script_pin.py
+++ b/tests/studio/test_studio_gguf_export_script_pin.py
@@ -23,12 +23,7 @@ from pathlib import Path
 
 
 SOURCE_PATH = (
-    Path(__file__).resolve().parents[2]
-    / "studio"
-    / "backend"
-    / "core"
-    / "export"
-    / "export.py"
+    Path(__file__).resolve().parents[2] / "studio" / "backend" / "core" / "export" / "export.py"
 )
 SRC = SOURCE_PATH.read_text()
 TREE = ast.parse(SRC)
@@ -50,10 +45,7 @@ def _find_pin_try(tree: ast.AST):
             if (
                 isinstance(stmt, ast.ImportFrom)
                 and stmt.module == "unsloth_zoo.llama_cpp"
-                and any(
-                    alias.name == "_resolve_local_convert_script"
-                    for alias in stmt.names
-                )
+                and any(alias.name == "_resolve_local_convert_script" for alias in stmt.names)
             ):
                 return node
     return None
@@ -107,9 +99,7 @@ def test_warning_handler_gated_on_module_flag():
     try_node = _find_pin_try(TREE)
     assert try_node is not None
     handlers = [
-        h
-        for h in try_node.handlers
-        if isinstance(h.type, ast.Name) and h.type.id == "ImportError"
+        h for h in try_node.handlers if isinstance(h.type, ast.Name) and h.type.id == "ImportError"
     ]
     assert handlers
     handler = handlers[0]
@@ -117,10 +107,7 @@ def test_warning_handler_gated_on_module_flag():
     flag_writes = []
     warning_calls = []
     for node in ast.walk(ast.Module(body = handler.body, type_ignores = [])):
-        if (
-            isinstance(node, ast.Name)
-            and node.id == "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED"
-        ):
+        if isinstance(node, ast.Name) and node.id == "_LLAMA_CPP_SCRIPTS_WARNING_EMITTED":
             if isinstance(node.ctx, ast.Load):
                 flag_reads.append(node)
             elif isinstance(node.ctx, ast.Store):
@@ -141,7 +128,6 @@ def test_warning_handler_gated_on_module_flag():
 
 def test_default_dir_is_string_for_setdefault_compat():
     from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR
-
     assert isinstance(LLAMA_CPP_DEFAULT_DIR, str)
 
 
@@ -175,10 +161,7 @@ def _simulate_pin_block(emit_records, set_value):
                 LLAMA_CPP_DEFAULT_DIR,
                 _resolve_local_convert_script,  # noqa: F401
             )
-
-            os.environ.setdefault(
-                "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR
-            )
+            os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
         except ImportError:
             if not state["emitted"]:
                 emit_records.append("warned")
@@ -220,7 +203,6 @@ def test_no_warning_when_both_symbols_present(monkeypatch):
             LLAMA_CPP_DEFAULT_DIR,
             _resolve_local_convert_script,  # noqa: F401
         )
-
         os.environ.setdefault("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", LLAMA_CPP_DEFAULT_DIR)
     except ImportError:
         if not state["emitted"]:
diff --git a/tests/studio/test_studio_text_descender_clipping.py b/tests/studio/test_studio_text_descender_clipping.py
index dd0df320bc..0b805cbd6f 100644
--- a/tests/studio/test_studio_text_descender_clipping.py
+++ b/tests/studio/test_studio_text_descender_clipping.py
@@ -12,13 +12,7 @@ from pathlib import Path
 
 WORKDIR = Path(__file__).resolve().parents[2]
 MODEL_SELECTOR = (
-    WORKDIR
-    / "studio"
-    / "frontend"
-    / "src"
-    / "components"
-    / "assistant-ui"
-    / "model-selector.tsx"
+    WORKDIR / "studio" / "frontend" / "src" / "components" / "assistant-ui" / "model-selector.tsx"
 )
 APP_SIDEBAR = WORKDIR / "studio" / "frontend" / "src" / "components" / "app-sidebar.tsx"
 
@@ -37,9 +31,7 @@ def test_model_selector_trigger_label_uses_leading_tight():
     assert matches, "could not find ModelSelectorTrigger model-name span"
     for cls in matches:
         assert "leading-tight" in cls, f"expected leading-tight, got: {cls}"
-        assert (
-            "leading-none" not in cls
-        ), f"leading-none must not coexist with truncate here: {cls}"
+        assert "leading-none" not in cls, f"leading-none must not coexist with truncate here: {cls}"
 
 
 def test_sidebar_account_block_uses_leading_tight():
@@ -50,13 +42,9 @@ def test_sidebar_account_block_uses_leading_tight():
     matches = pattern.findall(src)
     assert matches, "could not find sidebar account-block parent div"
     leading_classes = [m for m in matches if m.startswith("leading-")]
-    assert (
-        leading_classes
-    ), f"no leading-* class on sidebar account-block parent: {matches}"
+    assert leading_classes, f"no leading-* class on sidebar account-block parent: {matches}"
     for cls in leading_classes:
-        assert (
-            cls == "leading-tight"
-        ), f"sidebar account-block must use leading-tight, got: {cls}"
+        assert cls == "leading-tight", f"sidebar account-block must use leading-tight, got: {cls}"
 
 
 def test_no_truncate_plus_leading_none_in_changed_files():
diff --git a/tests/test_callback_signature_drift.py b/tests/test_callback_signature_drift.py
index 82226c30e6..4a29f4f7c7 100644
--- a/tests/test_callback_signature_drift.py
+++ b/tests/test_callback_signature_drift.py
@@ -77,7 +77,6 @@ def _safe_parse(path: pathlib.Path):
         return _PARSE_CACHE[key]
     try:
         import warnings as _w
-
         with _w.catch_warnings():
             # Suppress SyntaxWarning emitted while parsing third-party files
             # that contain invalid escape sequences in regex / docstrings.
@@ -180,9 +179,7 @@ def _func_arity(node: ast.AST) -> tuple[int, bool] | None:
     return arity, accepts_var
 
 
-def discover_producers(
-    roots: list[pathlib.Path],
-) -> dict[str, list[tuple[pathlib.Path, int]]]:
+def discover_producers(roots: list[pathlib.Path]) -> dict[str, list[tuple[pathlib.Path, int]]]:
     """Walk every .py under each root and return {cb_list_attr: [(file, arity), ...]}."""
     producers: dict[str, list[tuple[pathlib.Path, int]]] = {}
     for root in roots:
@@ -307,7 +304,6 @@ def test_no_callback_signature_drift():
     producers = discover_producers(roots)
     if not producers:
         import pytest
-
         pytest.skip(
             "no callback producer pattern (self._*_callbacks + cb(...)) found in "
             "unsloth or unsloth_zoo. Set UNSLOTH_ZOO_SRC=<path-to-unsloth-zoo-git-checkout> "
diff --git a/tests/test_enforce_kwargs_spacing.py b/tests/test_enforce_kwargs_spacing.py
new file mode 100644
index 0000000000..5e135c982c
--- /dev/null
+++ b/tests/test_enforce_kwargs_spacing.py
@@ -0,0 +1,428 @@
+"""Tests for scripts/enforce_kwargs_spacing.py.
+
+Focus on remove_blank_after_short_import (the blank-line-after-short-import-block
+rule): it must fire on small nested import blocks, leave everything else alone,
+never change the AST, and be idempotent. A couple of enforce_spacing checks pin
+the existing kwarg-spacing behavior.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS = str(Path(__file__).resolve().parent.parent / "scripts")
+if _SCRIPTS not in sys.path:
+    sys.path.insert(0, _SCRIPTS)
+
+from enforce_kwargs_spacing import (  # noqa: E402
+    collapse_short_asserts,
+    enforce_spacing,
+    merge_adjacent_string_literals,
+    normalize_def_trailing_comma,
+    remove_blank_after_short_import,
+)
+
+
+# (name, source) pairs where the blank after the import block MUST be removed.
+_MUST_CHANGE = {
+    "try_except_import": (
+        "def f():\n"
+        "    try:\n"
+        "        import torch\n"
+        "\n"
+        "        return torch.inference_mode\n"
+        "    except Exception:\n"
+        "        from contextlib import nullcontext\n"
+        "\n"
+        "        return nullcontext\n"
+    ),
+    "if_from_import": (
+        "def g():\n"
+        "    if cond:\n"
+        "        from . import locators\n"
+        "\n"
+        "        regions = locators.regions()\n"
+    ),
+    "multiple_consecutive_imports": ("def f():\n    import a\n    import b\n\n    return a, b\n"),
+    "type_checking_block": (
+        "def f():\n"
+        "    if TYPE_CHECKING:\n"
+        "        import x\n"
+        "\n"
+        "        y = x\n"
+        "        return y\n"
+    ),
+    "with_block": ("def f():\n    with ctx():\n        import a\n\n        return a.run()\n"),
+}
+
+# Sources that MUST be left byte-for-byte unchanged.
+_MUST_NOT_CHANGE = {
+    "module_level": 'import os\n\nVALUE = os.environ.get("V")\n',
+    "large_suite": (
+        "def f():\n"
+        "    import a\n"
+        "\n"
+        "    x = a.load()\n"
+        "    y = transform(x)\n"
+        "    return y\n"
+    ),
+    "comment_between": ("def f():\n    import a\n\n    # keep separated\n    return a.value\n"),
+    "import_is_last_stmt": "def f():\n    if cond:\n        import a\n\n",
+    "no_blank_already": "def f():\n    import a\n    return a\n",
+}
+
+
+@pytest.mark.parametrize("name", sorted(_MUST_CHANGE))
+def test_blank_removed_for_small_import_block(name):
+    src = _MUST_CHANGE[name]
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is True
+    assert out != src
+    # The import line and the following statement are now adjacent (no blank between).
+    assert "\n\n" not in out or out.count("\n\n") < src.count("\n\n")
+    # Semantics preserved and idempotent.
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    out2, changed2 = remove_blank_after_short_import(out)
+    assert out2 == out and changed2 is False
+
+
+@pytest.mark.parametrize("name", sorted(_MUST_NOT_CHANGE))
+def test_blank_preserved_when_not_applicable(name):
+    src = _MUST_NOT_CHANGE[name]
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is False
+    assert out == src
+
+
+def test_exact_output_try_block():
+    src = (
+        "def f():\n"
+        "    try:\n"
+        "        import torch\n"
+        "\n"
+        "        return torch.inference_mode\n"
+        "    except Exception:\n"
+        "        from contextlib import nullcontext\n"
+        "\n"
+        "        return nullcontext\n"
+    )
+    expected = (
+        "def f():\n"
+        "    try:\n"
+        "        import torch\n"
+        "        return torch.inference_mode\n"
+        "    except Exception:\n"
+        "        from contextlib import nullcontext\n"
+        "        return nullcontext\n"
+    )
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is True
+    assert out == expected
+
+
+def test_exact_output_multiple_consecutive_imports():
+    # Pins that only the blank after the LAST import in a run is dropped and
+    # both imports are kept (the loose \n\n heuristic above does not pin this).
+    src = "def f():\n    import a\n    import b\n\n    return a, b\n"
+    expected = "def f():\n    import a\n    import b\n    return a, b\n"
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is True
+    assert out == expected
+
+
+def test_multiple_blank_lines_in_gap_all_removed():
+    src = "def f():\n    import a\n\n\n    return a\n"
+    expected = "def f():\n    import a\n    return a\n"
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is True
+    assert out == expected
+    out2, changed2 = remove_blank_after_short_import(out)
+    assert out2 == out and changed2 is False
+
+
+def test_multiline_import_internal_blank_preserved():
+    # A blank line INSIDE a parenthesized import is part of the import span, not
+    # the gap, so it must survive; only the trailing blank before code is dropped.
+    src = (
+        "def g():\n"
+        "    from mod import (\n"
+        "        a,\n"
+        "\n"
+        "        b,\n"
+        "    )\n"
+        "\n"
+        "    return a, b\n"
+    )
+    expected = (
+        "def g():\n"
+        "    from mod import (\n"
+        "        a,\n"
+        "\n"
+        "        b,\n"
+        "    )\n"
+        "    return a, b\n"
+    )
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is True
+    assert out == expected
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    out2, changed2 = remove_blank_after_short_import(out)
+    assert out2 == out and changed2 is False
+
+
+def test_syntax_error_is_left_alone():
+    src = "def f(:\n    import a\n\n    return a\n"
+    out, changed = remove_blank_after_short_import(src)
+    assert changed is False
+    assert out == src
+
+
+def test_enforce_spacing_pads_kwargs():
+    src = "f(a=1, b = 2)\n"
+    out, changed = enforce_spacing(src)
+    assert changed is True
+    assert "a = 1" in out and "b = 2" in out
+
+
+def test_enforce_spacing_noop_when_already_spaced():
+    src = "f(a = 1, b = 2)\n"
+    out, changed = enforce_spacing(src)
+    assert changed is False
+    assert out == src
+
+
+# ── Rule D: def one-per-line iff >= 3 params AND a default ──────────────────
+# add comma -> force one-per-line; strip comma -> stay collapsible.
+
+# Comma must be ADDED: >= 3 params, has a default, no trailing comma yet.
+_DEF_ADD = {
+    "three_with_default": "def f(a, b, c=1):\n    return a\n",
+    "four_with_default": "def f(a, b, c, d=1):\n    return a\n",
+    "kwonly_default": "def f(a, b, *, c=1):\n    return a\n",  # 3 real params, kw default
+    "continuation_default": "def f(\n    a, b, c=1\n):\n    return a\n",
+    "starred_with_default": "def f(a, b, *args, c=1):\n    return a\n",  # 4 params
+}
+
+# Comma must be STRIPPED: NOT (>=3 params and default), but a trailing comma exists.
+_DEF_STRIP = {
+    "three_no_default_multiline": "def f(\n    a,\n    b,\n    c,\n):\n    return a\n",
+    "four_no_default_multiline": "def f(\n    a,\n    b,\n    c,\n    d,\n):\n    return a\n",
+    "two_with_default": "def f(\n    a,\n    b=1,\n):\n    return a\n",  # < 3 params -> one line
+    "single_arg": "def f(\n    a,\n):\n    return a\n",
+}
+
+# Left byte-for-byte unchanged.
+_DEF_NOCHANGE = {
+    "three_no_default_oneline": "def f(a, b, c):\n    return a\n",
+    "two_with_default_oneline": "def f(a, b=1):\n    return a\n",  # < 3 -> one line, no comma
+    "noparams": "def f():\n    return 1\n",
+    "call_site": "x = foo(\n    a,\n    b,\n    c,\n    d,\n)\n",
+    "nested_default_call": "def f(a=g(1, 2,)):\n    return a\n",  # 1 param, no def comma
+    "three_default_already_comma": "def f(\n    a,\n    b,\n    c=1,\n):\n    return a\n",
+}
+
+
+@pytest.mark.parametrize("name", sorted(_DEF_ADD))
+def test_def_comma_added(name):
+    src = _DEF_ADD[name]
+    out, changed = normalize_def_trailing_comma(src)
+    assert changed is True
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    assert out.count(",") == src.count(",") + 1
+    out2, changed2 = normalize_def_trailing_comma(out)
+    assert out2 == out and changed2 is False
+
+
+@pytest.mark.parametrize("name", sorted(_DEF_STRIP))
+def test_def_comma_stripped(name):
+    src = _DEF_STRIP[name]
+    out, changed = normalize_def_trailing_comma(src)
+    assert changed is True
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    assert out.count(",") == src.count(",") - 1
+    out2, changed2 = normalize_def_trailing_comma(out)
+    assert out2 == out and changed2 is False
+
+
+@pytest.mark.parametrize("name", sorted(_DEF_NOCHANGE))
+def test_def_comma_unchanged(name):
+    src = _DEF_NOCHANGE[name]
+    out, changed = normalize_def_trailing_comma(src)
+    assert changed is False
+    assert out == src
+
+
+def test_def_comma_exact_output_strip_and_add():
+    # >= 3 params + default -> add comma (force one-per-line)
+    assert normalize_def_trailing_comma("def f(a, b, c=1):\n    return a\n")[0] == (
+        "def f(a, b, c=1,):\n    return a\n"
+    )
+    # 3 params, no default -> strip comma (collapsible)
+    assert (
+        normalize_def_trailing_comma("def f(\n    a,\n    b,\n    c,\n):\n    return a\n")[0]
+        == "def f(\n    a,\n    b,\n    c\n):\n    return a\n"
+    )
+
+
+# ── Rule C: merge adjacent same-line string literals ───────────────────────
+
+
+@pytest.mark.parametrize(
+    "src,expected",
+    [
+        ('x = "ab" "cd"\n', 'x = "abcd"\n'),
+        ('d = "newly-" "added dep."\n', 'd = "newly-added dep."\n'),
+        ('m = ("a. " "b.")\n', 'm = ("a. b.")\n'),
+        ('x = r"a\\n" r"b"\n', 'x = r"a\\nb"\n'),
+        ('x = "a\\"q" "b"\n', 'x = "a\\"qb"\n'),
+        # f + plain folds into one f-string (plain braces escaped).
+        ('x = f"a" "b"\n', 'x = f"ab"\n'),
+        (
+            'd = (f"{pkg}@{ver} is on the " "BLOCKED list")\n',
+            'd = (f"{pkg}@{ver} is on the BLOCKED list")\n',
+        ),
+        ('x = f"a{z}" "{lit}"\n', 'x = f"a{z}{{lit}}"\n'),
+        ('m = "plain " f"then {y}"\n', 'm = f"plain then {y}"\n'),  # plain + f
+    ],
+)
+def test_merge_adjacent_strings(src, expected):
+    out, changed = merge_adjacent_string_literals(src)
+    assert changed is True
+    assert out == expected
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    out2, changed2 = merge_adjacent_string_literals(out)
+    assert out2 == out and changed2 is False
+
+
+@pytest.mark.parametrize(
+    "src",
+    [
+        'x = "ab"\n',  # single literal
+        "x = \"ab\" 'cd'\n",  # mixed quote style
+        'x = b"a" b"b"\n',  # bytes: left side-by-side by request
+        'x = rb"a" rb"b"\n',  # raw-bytes: also left alone
+        'm = f"a {x} " f"after {y}"\n',  # pure f + f: left side-by-side
+        'x = rf"a{z}" "b"\n',  # raw f-string: brace/backslash too subtle -> skip
+        'x = f"a{z}" "\\N{BULLET}"\n',  # named escape: AST guard rejects the fold
+        'x = (\n    "a"\n    "b"\n)\n',  # different lines, not merged
+    ],
+)
+def test_merge_adjacent_strings_skips(src):
+    out, changed = merge_adjacent_string_literals(src)
+    assert changed is False
+    assert out == src
+
+
+def test_fstring_fold_skipped_when_statement_would_not_collapse():
+    # A long f + plain assert message: folding it cannot fit the statement on one
+    # line, so ruff would re-wrap the assert condition. Leave it side-by-side.
+    src = (
+        "def f():\n"
+        "    assert some_condition_holds_here, (\n"
+        '        f"a fairly detailed message about {value} explaining " "why this failed badly"\n'
+        "    )\n"
+    )
+    out, changed = merge_adjacent_string_literals(src)
+    assert changed is False
+    assert out == src
+
+
+def test_fstring_fold_applied_when_statement_collapses():
+    # A multi-line f + plain that DOES fit on one line after folding is folded
+    # (ruff then collapses the call to a single line on the next pass).
+    src = "def f():\n    raise ValueError(\n" '        f"bad {x}: " "try again"\n' "    )\n"
+    out, changed = merge_adjacent_string_literals(src)
+    assert changed is True
+    assert 'f"bad {x}: try again"' in out
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+
+
+def test_fstring_fold_applied_inside_large_multiline_call():
+    # The fit guard only restricts asserts; an f + plain argument on its own line
+    # inside a big multi-line call (the lockfile case) folds even though the whole
+    # call cannot fit on one line.
+    src = (
+        "findings.append(\n"
+        "    Finding(\n"
+        "        path=str(path),\n"
+        "        package=key,\n"
+        '        detail=(f"{name}@{ver} is on the " "BLOCKED list"),\n'
+        "    )\n"
+        ")\n"
+    )
+    out, changed = merge_adjacent_string_literals(src)
+    assert changed is True
+    assert 'detail=(f"{name}@{ver} is on the BLOCKED list")' in out
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+
+
+# ── collapse_short_asserts: strip the magic comma holding a short assert open ──
+# The pass strips the trailing comma so ruff joins the assert onto one line on the
+# next format pass; it never changes the AST.
+
+
+@pytest.mark.parametrize(
+    "name,src",
+    [
+        (
+            "dict_eq",
+            'def t():\n    assert got == {\n        "a": 1,\n        "b": 2,\n    }\n',
+        ),
+        (
+            "list_eq",
+            'def t():\n    assert xs == [\n        "a",\n        "b",\n        "c",\n    ]\n',
+        ),
+        (
+            "membership",
+            'def t():\n    assert {\n        "type": "x",\n        "name": "y",\n    } in tools\n',
+        ),
+        (
+            "tuple_message",
+            "def t():\n    assert cond, (\n        base,\n        headers,\n    )\n",
+        ),
+        (
+            "call_args",
+            "def t():\n    assert eq(\n        a,\n        b,\n    )\n",
+        ),
+    ],
+)
+def test_collapse_short_assert_strips_trailing_comma(name, src):
+    out, changed = collapse_short_asserts(src)
+    assert changed is True
+    # The magic trailing comma is gone (so ruff will join it on the next pass).
+    assert out.count(",") == src.count(",") - 1
+    # Semantics preserved and idempotent at the strip level.
+    assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
+    out2, changed2 = collapse_short_asserts(out)
+    assert out2 == out and changed2 is False
+
+
+@pytest.mark.parametrize(
+    "name,src",
+    [
+        # one-element tuple message: stripping (only,) -> (only) changes meaning.
+        ("one_tuple_message", "def t():\n    assert cond, (\n        only,\n    )\n"),
+        # a comment inside keeps ruff multi-line, so collapsing would oscillate.
+        (
+            "comment_inside",
+            'def t():\n    assert x == {\n        "a": 1,  # keep\n        "b": 2,\n    }\n',
+        ),
+        # genuinely long: would not fit on one line, leave expanded.
+        (
+            "too_long",
+            "def t():\n    assert some_really_long_left_operand_name_here == {\n"
+            '        "alpha": 11111111,\n        "beta": 22222222,\n'
+            '        "gamma": 33333333,\n        "delta": 44444444,\n    }\n',
+        ),
+        # already one line: nothing to do.
+        ("one_line", 'def t():\n    assert got == {"a": 1, "b": 2}\n'),
+    ],
+)
+def test_collapse_short_assert_left_alone(name, src):
+    out, changed = collapse_short_asserts(src)
+    assert changed is False
+    assert out == src
diff --git a/tests/test_finetune_last_n_layers.py b/tests/test_finetune_last_n_layers.py
index fa0e2af5bc..e2dafb7638 100644
--- a/tests/test_finetune_last_n_layers.py
+++ b/tests/test_finetune_last_n_layers.py
@@ -47,7 +47,6 @@ def test_get_total_transformer_layers_reads_text_config():
 
 def test_get_total_transformer_layers_handles_alternative_attr_names():
     from unsloth.models.vision import _get_total_transformer_layers
-
     for attr in ("n_layer", "n_layers", "num_layers"):
         cfg = type("Cfg", (), {attr: 12})()
         model = type("M", (), {"config": cfg})()
@@ -68,7 +67,6 @@ def test_get_total_transformer_layers_returns_none_when_unknown():
 
 def test_get_total_transformer_layers_returns_none_for_missing_config():
     from unsloth.models.vision import _get_total_transformer_layers
-
     class FakeModel:
         pass
 
diff --git a/tests/test_gemma4_chat_template.py b/tests/test_gemma4_chat_template.py
index 6211b4d433..5c362576c6 100644
--- a/tests/test_gemma4_chat_template.py
+++ b/tests/test_gemma4_chat_template.py
@@ -23,9 +23,7 @@ def _extract_template(name):
 
 def _env():
     env = Environment(undefined = StrictUndefined, trim_blocks = False, lstrip_blocks = False)
-    env.globals["raise_exception"] = lambda msg: (_ for _ in ()).throw(
-        TemplateError(msg)
-    )
+    env.globals["raise_exception"] = lambda msg: (_ for _ in ()).throw(TemplateError(msg))
     return env
 
 
diff --git a/tests/test_get_model_name.py b/tests/test_get_model_name.py
index 15dd44f0ec..993931c0ef 100644
--- a/tests/test_get_model_name.py
+++ b/tests/test_get_model_name.py
@@ -137,9 +137,7 @@ class TestGetModelName(unittest.TestCase):
             else:
                 model_name, load_in_4bit, expected, should_change = case
                 with self.subTest(model_name = model_name, load_in_4bit = load_in_4bit):
-                    self._assert_mapping(
-                        model_name, load_in_4bit, expected, should_change
-                    )
+                    self._assert_mapping(model_name, load_in_4bit, expected, should_change)
 
     def test_static_mapper_contract(self):
         contracts = [
@@ -158,9 +156,7 @@ class TestGetModelName(unittest.TestCase):
         for src, expected in contracts:
             with self.subTest(src = src):
                 self.assertEqual(FLOAT_TO_INT_MAPPER[src], expected)
-        self.assertEqual(
-            MAP_TO_UNSLOTH_16bit["qwen/qwen3-8b-fp8"], "unsloth/Qwen3-8B-FP8"
-        )
+        self.assertEqual(MAP_TO_UNSLOTH_16bit["qwen/qwen3-8b-fp8"], "unsloth/Qwen3-8B-FP8")
 
 
 if __name__ == "__main__":
diff --git a/tests/test_import_fixes_drift.py b/tests/test_import_fixes_drift.py
index 099b65d09a..bf033d0235 100644
--- a/tests/test_import_fixes_drift.py
+++ b/tests/test_import_fixes_drift.py
@@ -110,9 +110,7 @@ def test_trl_is_x_available_returns_bool_not_tuple():
     accessor_names = [
         n
         for n in dir(tiu)
-        if n.startswith("is_")
-        and n.endswith("_available")
-        and callable(getattr(tiu, n, None))
+        if n.startswith("is_") and n.endswith("_available") and callable(getattr(tiu, n, None))
     ]
     assert accessor_names, "trl.import_utils has no is_*_available accessors"
 
@@ -158,9 +156,7 @@ def test_trl_cached_available_flags_are_not_tuples():
     tuple_flags = {
         name: value
         for name, value in vars(tiu).items()
-        if name.startswith("_")
-        and name.endswith("_available")
-        and isinstance(value, tuple)
+        if name.startswith("_") and name.endswith("_available") and isinstance(value, tuple)
     }
     if tuple_flags:
         pytest.fail(
@@ -290,10 +286,9 @@ def test_peft_transformers_weight_conversion_importable_and_signature():
             "patch_peft_weight_converter_compatibility will silently no-op."
         )
 
-    assert hasattr(twc, "build_peft_weight_mapping"), (
-        "build_peft_weight_mapping vanished from "
-        "peft.utils.transformers_weight_conversion."
-    )
+    assert hasattr(
+        twc, "build_peft_weight_mapping"
+    ), "build_peft_weight_mapping vanished from peft.utils.transformers_weight_conversion."
     sig = inspect.signature(twc.build_peft_weight_mapping)
     expected_params = {"weight_conversions", "adapter_name"}
     actual_params = set(sig.parameters)
@@ -390,9 +385,7 @@ def test_installed_torch_torchvision_pair_is_compatible():
         )
 
     pre_tags = (".dev", "a0", "b0", "rc", "alpha", "beta", "nightly")
-    is_prerelease = any(t in torch_raw for t in pre_tags) or any(
-        t in tv_raw for t in pre_tags
-    )
+    is_prerelease = any(t in torch_raw for t in pre_tags) or any(t in tv_raw for t in pre_tags)
     is_custom = _is_custom_torch_build(torch_raw) or _is_custom_torch_build(tv_raw)
     if is_prerelease or is_custom:
         pytest.skip(
@@ -593,9 +586,7 @@ def test_patch_loss_functions_does_not_touch_other_loss_types():
     cel = pytest.importorskip("unsloth.kernels.cross_entropy_loss")
 
     non_causal_keys = {
-        k
-        for k, v in lu.LOSS_MAPPING.items()
-        if getattr(v, "__name__", "") != "ForCausalLMLoss"
+        k for k, v in lu.LOSS_MAPPING.items() if getattr(v, "__name__", "") != "ForCausalLMLoss"
     }
 
     saved = dict(lu.LOSS_MAPPING)
diff --git a/tests/test_loader_glob_skip.py b/tests/test_loader_glob_skip.py
index d461e23cf8..f26f71271c 100644
--- a/tests/test_loader_glob_skip.py
+++ b/tests/test_loader_glob_skip.py
@@ -15,7 +15,12 @@ class TestGlobSkippedWhenNotBothConfigs(unittest.TestCase):
     """Verify HfFileSystem.glob is not called when is_model or is_peft is False."""
 
     def _run_both_exist_block(
-        self, is_model, is_peft, supports_llama32, model_name, is_local_dir = False
+        self,
+        is_model,
+        is_peft,
+        supports_llama32,
+        model_name,
+        is_local_dir = False,
     ):
         """Simulate the both_exist detection block from loader.py.
 
@@ -40,10 +45,7 @@ class TestGlobSkippedWhenNotBothConfigs(unittest.TestCase):
             else:
                 files = glob_mock(f"{model_name}/*.json")
                 files = list(os.path.split(x)[-1] for x in files)
-                if (
-                    sum(x == "adapter_config.json" or x == "config.json" for x in files)
-                    >= 2
-                ):
+                if sum(x == "adapter_config.json" or x == "config.json" for x in files) >= 2:
                     both_exist = True
 
         return both_exist, glob_mock.called
@@ -87,9 +89,7 @@ class TestGlobSkippedWhenNotBothConfigs(unittest.TestCase):
             supports_llama32 = False,
             model_name = "org/some-model",
         )
-        self.assertFalse(
-            glob_called, "glob should not be called when SUPPORTS_LLAMA32=False"
-        )
+        self.assertFalse(glob_called, "glob should not be called when SUPPORTS_LLAMA32=False")
         # both_exist is set by the old-style check: (is_model and is_peft) and not SUPPORTS_LLAMA32
         self.assertTrue(both_exist)
 
diff --git a/tests/test_model_registry.py b/tests/test_model_registry.py
index fb9a734c6f..3d34e783ba 100644
--- a/tests/test_model_registry.py
+++ b/tests/test_model_registry.py
@@ -58,8 +58,7 @@ def _test_model_uploaded(model_ids: list[str]):
 
 
 TestParams = [
-    ModelTestParam(name, models)
-    for name, models in zip(MODEL_NAMES, MODEL_REGISTRATION_METHODS)
+    ModelTestParam(name, models) for name, models in zip(MODEL_NAMES, MODEL_REGISTRATION_METHODS)
 ]
 
 
@@ -71,9 +70,7 @@ def test_model_registration(model_test_param: ModelTestParam):
     registration_method()
     registered_models = MODEL_REGISTRY.keys()
     missing_models = _test_model_uploaded(registered_models)
-    assert (
-        not missing_models
-    ), f"{model_test_param.name} missing following models: {missing_models}"
+    assert not missing_models, f"{model_test_param.name} missing following models: {missing_models}"
 
 
 def test_all_model_registration():
diff --git a/tests/test_multi_image_grpo_chunking.py b/tests/test_multi_image_grpo_chunking.py
index 0bd876b664..07ad95d5d7 100644
--- a/tests/test_multi_image_grpo_chunking.py
+++ b/tests/test_multi_image_grpo_chunking.py
@@ -25,9 +25,7 @@ def test_cum_rows_materialized_on_cpu():
     assert idx != -1, "cum_rows assignment must exist"
     window = src[idx : idx + 400]
     assert "rows_per_sample.cumsum(0)" in window
-    assert (
-        ").cpu()" in window
-    ), "cum_rows must be moved to CPU once via .cpu() after construction"
+    assert ").cpu()" in window, "cum_rows must be moved to CPU once via .cpu() after construction"
 
 
 def test_cum_imgs_slice_indices_use_item():
@@ -165,9 +163,7 @@ def test_guard_prefers_inspect_signature_over_getsource():
     src_call = body.find("inspect.getsource(grpo_accumulated_loss)")
     assert sig_call != -1
     assert src_call != -1
-    assert (
-        sig_call < src_call
-    ), "signature.parameters must run before the getsource fallback"
+    assert sig_call < src_call, "signature.parameters must run before the getsource fallback"
 
 
 def test_guard_only_raises_when_both_checks_fail():
@@ -178,16 +174,12 @@ def test_guard_only_raises_when_both_checks_fail():
         r"if not _supports_num_images:\s*\n\s*raise RuntimeError",
         re.DOTALL,
     )
-    assert pattern.search(
-        src
-    ), "guard flow must be: signature check, source fallback, then raise"
+    assert pattern.search(src), "guard flow must be: signature check, source fallback, then raise"
 
 
 def test_guard_introspection_failure_does_not_silent_no_op():
     src = _read_source()
-    assert (
-        "(TypeError, OSError)" in src
-    ), "guard must catch inspect.getsource failures explicitly"
+    assert "(TypeError, OSError)" in src, "guard must catch inspect.getsource failures explicitly"
     assert re.search(
         r"_zoo_src\s*=\s*['\"]{2}", src
     ), "introspection failure path must default _zoo_src to empty string"
diff --git a/tests/test_peft_weight_converter_compat.py b/tests/test_peft_weight_converter_compat.py
index 62f17f0f45..91704cbc41 100644
--- a/tests/test_peft_weight_converter_compat.py
+++ b/tests/test_peft_weight_converter_compat.py
@@ -13,9 +13,7 @@ IMPORT_FIXES = REPO_ROOT / "unsloth" / "import_fixes.py"
 
 
 def _load_patch_function():
-    spec = importlib.util.spec_from_file_location(
-        "_unsloth_import_fixes_under_test", IMPORT_FIXES
-    )
+    spec = importlib.util.spec_from_file_location("_unsloth_import_fixes_under_test", IMPORT_FIXES)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
     return module.patch_peft_weight_converter_compatibility
@@ -87,7 +85,11 @@ def _make_modern_converter():
     return _ModernConverter(["src.*"], ["tgt.*"], [])
 
 
-def _build_that_calls_init(weight_conversions, adapter_name, peft_config = None):
+def _build_that_calls_init(
+    weight_conversions,
+    adapter_name,
+    peft_config = None,
+):
     out = []
     for c in weight_conversions or []:
         out.append(
@@ -149,7 +151,11 @@ def test_class_init_restored_after_call():
 
 
 def test_class_init_restored_after_original_build_raises():
-    def _raise(weight_conversions, adapter_name, peft_config = None):
+    def _raise(
+        weight_conversions,
+        adapter_name,
+        peft_config = None,
+    ):
         raise RuntimeError("simulated PEFT failure")
 
     twc = _install_fake_peft({"build_peft_weight_mapping": _raise})
@@ -211,7 +217,11 @@ def test_idempotent_install_does_not_double_wrap():
 def test_concurrent_legacy_calls_no_typeerror():
     import time
 
-    def _slow_build(weight_conversions, adapter_name, peft_config = None):
+    def _slow_build(
+        weight_conversions,
+        adapter_name,
+        peft_config = None,
+    ):
         time.sleep(0.05)
         return _build_that_calls_init(weight_conversions, adapter_name, peft_config)
 
@@ -226,9 +236,7 @@ def test_concurrent_legacy_calls_no_typeerror():
     def _worker():
         start.wait(timeout = 10)
         try:
-            out = twc.build_peft_weight_mapping(
-                [_make_legacy_converter()], "default", None
-            )
+            out = twc.build_peft_weight_mapping([_make_legacy_converter()], "default", None)
             results.append(out)
         except Exception as e:
             errors.append(e)
diff --git a/tests/test_raw_text.py b/tests/test_raw_text.py
index 056ea8660f..dda8de9a5e 100644
--- a/tests/test_raw_text.py
+++ b/tests/test_raw_text.py
@@ -45,9 +45,7 @@ sys.modules["datasets"] = datasets_mock
 
 # Import the raw_text module directly to avoid unsloth/__init__.py dependencies
 current_dir = os.path.dirname(__file__)
-raw_text_path = os.path.join(
-    os.path.dirname(current_dir), "unsloth", "dataprep", "raw_text.py"
-)
+raw_text_path = os.path.join(os.path.dirname(current_dir), "unsloth", "dataprep", "raw_text.py")
 
 spec = importlib.util.spec_from_file_location("raw_text", raw_text_path)
 raw_text_module = importlib.util.module_from_spec(spec)
@@ -66,7 +64,12 @@ def test_raw_text_loader():
             self.eos_token = "</s>"
             self.eos_token_id = 2  # Mock EOS token ID
 
-        def __call__(self, text, return_tensors = None, add_special_tokens = False):
+        def __call__(
+            self,
+            text,
+            return_tensors = None,
+            add_special_tokens = False,
+        ):
             words = text.split()
             token_ids = list(range(len(words)))
 
@@ -88,7 +91,11 @@ def test_raw_text_loader():
                 return {"input_ids": [MockTensor(token_ids)]}
             return {"input_ids": token_ids}
 
-        def decode(self, token_ids, skip_special_tokens = False):
+        def decode(
+            self,
+            token_ids,
+            skip_special_tokens = False,
+        ):
             return " ".join([f"word_{i}" for i in token_ids])
 
     # Create test file
@@ -120,20 +127,14 @@ def test_raw_text_loader():
         # Verify tokenized data structure
         first_sample = tokenized_dataset[0]
         assert isinstance(first_sample["input_ids"], list), "input_ids should be a list"
-        assert isinstance(
-            first_sample["attention_mask"], list
-        ), "attention_mask should be a list"
+        assert isinstance(first_sample["attention_mask"], list), "attention_mask should be a list"
         assert len(first_sample["input_ids"]) == len(
             first_sample["attention_mask"]
         ), "input_ids and attention_mask should have same length"
 
         # Verify labels field exists (for causal LM training)
-        assert (
-            "labels" in tokenized_dataset.column_names
-        ), "Dataset should have 'labels' column"
-        assert (
-            first_sample["labels"] == first_sample["input_ids"]
-        ), "labels should match input_ids"
+        assert "labels" in tokenized_dataset.column_names, "Dataset should have 'labels' column"
+        assert first_sample["labels"] == first_sample["input_ids"], "labels should match input_ids"
 
         # Test constructor validation
         try:
@@ -172,16 +173,14 @@ def test_raw_text_loader():
         ]
         for raw, expected in unicode_whitespace_cases:
             assert preprocessor.clean_text(raw) == expected, (
-                f"Should normalize Unicode/control whitespace to a single space "
-                f"for {raw!r}"
+                f"Should normalize Unicode/control whitespace to a single space " f"for {raw!r}"
             )
 
         # Mixed paragraph + Unicode whitespace realistic input
         mixed = preprocessor.clean_text("Section\u00a01\r\n\r\nBody\ftext\u202fhere")
-        assert mixed == "Section 1\n\nBody text here", (
-            "Should preserve paragraph breaks and normalize Unicode "
-            "whitespace simultaneously"
-        )
+        assert (
+            mixed == "Section 1\n\nBody text here"
+        ), "Should preserve paragraph breaks and normalize Unicode whitespace simultaneously"
 
         # Tabs should collapse to a single space
         assert preprocessor.clean_text("a\tb") == "a b"
diff --git a/tests/test_resolve_model_class.py b/tests/test_resolve_model_class.py
index 5ec2a21a07..c2957e64df 100644
--- a/tests/test_resolve_model_class.py
+++ b/tests/test_resolve_model_class.py
@@ -7,7 +7,12 @@ class _AutoModelLike:
 
 
 class _FakeLazyMapping:
-    def __init__(self, entries, extra_content = None, broken_keys = ()):
+    def __init__(
+        self,
+        entries,
+        extra_content = None,
+        broken_keys = (),
+    ):
         self._entries = dict(entries)
         self._config_mapping = {k: f"Cfg_{k}" for k in self._entries}
         self._model_mapping = {k: f"Mdl_{k}" for k in self._entries}
diff --git a/tests/test_studio_install_workspace_guard.py b/tests/test_studio_install_workspace_guard.py
index b68f882126..a0093adb12 100644
--- a/tests/test_studio_install_workspace_guard.py
+++ b/tests/test_studio_install_workspace_guard.py
@@ -45,7 +45,9 @@ def _extract_install_sh_guard_block() -> str:
 
 
 def _build_install_guard_script(
-    studio_home: Path, redirect: str, block: str | None = None
+    studio_home: Path,
+    redirect: str,
+    block: str | None = None,
 ) -> str:
     """Build a self-contained bash script that exercises the extracted
     guard block. Includes stubs for substep / _start_studio_venv_replacement
@@ -135,12 +137,8 @@ def test_install_ps1_has_matching_env_mode_guard():
     assert (
         "$StudioRedirectMode -eq 'env'" in block
     ), "install.ps1 must gate Remove-Item $VenvDir on env-mode"
-    assert (
-        "share\\studio.conf" in block
-    ), "install.ps1 guard must check share\\studio.conf sentinel"
-    assert (
-        "bin\\unsloth.exe" in block
-    ), "install.ps1 guard must check bin\\unsloth.exe sentinel"
+    assert "share\\studio.conf" in block, "install.ps1 guard must check share\\studio.conf sentinel"
+    assert "bin\\unsloth.exe" in block, "install.ps1 guard must check bin\\unsloth.exe sentinel"
     assert "Refusing to delete non-Studio venv" in block
 
 
@@ -243,9 +241,7 @@ def test_setup_ps1_stale_venv_has_env_mode_guard():
     # The guard must fire BEFORE the destructive call.
     guard_idx = block.index("$StudioHomeIsCustom")
     rm_idx = block.index("Remove-Item -LiteralPath $VenvDir")
-    assert (
-        guard_idx < rm_idx
-    ), "custom-root guard must precede Remove-Item -LiteralPath $VenvDir"
+    assert guard_idx < rm_idx, "custom-root guard must precede Remove-Item -LiteralPath $VenvDir"
 
 
 def test_setup_sh_prebuilt_llama_cpp_has_ownership_guard():
@@ -262,9 +258,7 @@ def test_setup_sh_prebuilt_llama_cpp_has_ownership_guard():
     guard_idx = block.index('_assert_studio_owned_or_absent "$LLAMA_CPP_DIR"')
     # Anchor on the actual command-array entry, not the why-comment mention.
     helper_idx = block.index('python "$SCRIPT_DIR/install_llama_prebuilt.py"')
-    assert (
-        guard_idx < helper_idx
-    ), "ownership guard must precede the install_llama_prebuilt.py call"
+    assert guard_idx < helper_idx, "ownership guard must precede the install_llama_prebuilt.py call"
 
 
 def test_setup_ps1_prebuilt_llama_cpp_has_ownership_guard():
@@ -274,8 +268,7 @@ def test_setup_ps1_prebuilt_llama_cpp_has_ownership_guard():
     idx = src.index("installing prebuilt llama.cpp bundle (preferred path)")
     block = src[idx : idx + 2000]
     assert (
-        'Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install"'
-        in block
+        'Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install"' in block
     ), "setup.ps1 must guard the prebuilt llama.cpp path with Assert-StudioOwnedOrAbsent"
     guard_idx = block.index("Assert-StudioOwnedOrAbsent -Path $LlamaCppDir")
     # Anchor on the actual command-array entry, not the why-comment mention.
@@ -293,8 +286,7 @@ def test_env_mode_passes_when_venv_marker_present(tmp_path):
     studio_home = tmp_path / "ws"
     res = _run_install_guard(studio_home, redirect = "env", create_venv_marker = True)
     assert res.returncode == 0, (
-        f"in-VENV marker must allow cleanup; "
-        f"stdout={res.stdout!r} stderr={res.stderr!r}"
+        f"in-VENV marker must allow cleanup; " f"stdout={res.stdout!r} stderr={res.stderr!r}"
     )
     assert "RESULT=ok" in res.stdout
     assert not (studio_home / "unsloth_studio").exists()
@@ -450,9 +442,7 @@ def test_setup_ps1_inplace_git_sync_asserts_studio_owned_before_mutation():
     ), "in-place git-sync must Assert-StudioOwnedOrAbsent before mutating $LlamaCppDir"
     guard_idx = inplace_block.index("Assert-StudioOwnedOrAbsent -Path $LlamaCppDir")
     git_idx = inplace_block.index("git -C $LlamaCppDir remote set-url")
-    assert (
-        guard_idx < git_idx
-    ), "Assert-StudioOwnedOrAbsent must precede the first git mutation"
+    assert guard_idx < git_idx, "Assert-StudioOwnedOrAbsent must precede the first git mutation"
 
 
 def _extract_check_health_function() -> str:
@@ -549,9 +539,7 @@ def test_check_health_handles_arbitrary_id_token():
         expected_id,
         f'{{"status":"healthy","service":"Unsloth UI Backend","studio_root_id":"{expected_id}"}}',
     )
-    assert (
-        rc == 0
-    ), "arbitrary 64-hex install id must round-trip cleanly (no JSON escape issue)"
+    assert rc == 0, "arbitrary 64-hex install id must round-trip cleanly (no JSON escape issue)"
 
 
 def test_install_ps1_test_studio_health_verifies_studio_root_id():
@@ -561,9 +549,7 @@ def test_install_ps1_test_studio_health_verifies_studio_root_id():
     fn_start = src.index("function Test-StudioHealth")
     fn_end = src.index("\n}\n", fn_start) + 2
     fn = src[fn_start:fn_end]
-    assert (
-        "studio_root_id" in fn
-    ), "Test-StudioHealth must inspect the studio_root_id field"
+    assert "studio_root_id" in fn, "Test-StudioHealth must inspect the studio_root_id field"
     assert (
         "$_ExpectedStudioRootId" in fn
     ), "Test-StudioHealth must compare against the install-time baked $_ExpectedStudioRootId"
@@ -576,9 +562,7 @@ def test_install_ps1_bakes_studio_root_id_into_launcher():
     verify the backend belongs to THIS install. The id is generated
     via a CSPRNG so /api/health does not leak the install path."""
     src = INSTALL_PS1.read_text()
-    assert (
-        "$_studioRootId" in src
-    ), "install.ps1 must compute $_studioRootId for the launcher"
+    assert "$_studioRootId" in src, "install.ps1 must compute $_studioRootId for the launcher"
     assert (
         '"share"' in src and "studio_install_id" in src
     ), "install.ps1 must persist the id at $StudioHome\\share\\studio_install_id"
@@ -603,15 +587,11 @@ def test_health_endpoint_exposes_studio_root_id_not_raw_path():
     if next_app_idx == -1:
         next_app_idx = len(src)
     health_block = src[health_idx:next_app_idx]
-    assert (
-        '"studio_root_id"' in health_block
-    ), "/api/health must expose studio_root_id (hex digest)"
+    assert '"studio_root_id"' in health_block, "/api/health must expose studio_root_id (hex digest)"
     assert (
         '"studio_root":' not in health_block
     ), "/api/health must NOT expose the raw studio_root path (information disclosure)"
-    assert (
-        "_studio_root_id()" in health_block
-    ), "/api/health must call the _studio_root_id helper"
+    assert "_studio_root_id()" in health_block, "/api/health must call the _studio_root_id helper"
 
 
 def test_install_sh_bakes_studio_root_id_into_launcher():
@@ -685,9 +665,7 @@ def test_install_sh_shim_uses_atomic_replace():
     ), "the explicit rm + ln pair must be replaced by atomic ln -sfn"
 
 
-def test_install_sh_create_shortcuts_seeds_id_from_csprng_with_python_fallback(
-    tmp_path,
-):
+def test_install_sh_create_shortcuts_seeds_id_from_csprng_with_python_fallback(tmp_path):
     """_create_shortcuts must seed new ids from /dev/urandom first (no
     interpreter spawn cost on the install hot path) and fall back to
     `python3 -c 'secrets.token_hex(32)'` only when urandom is unreadable.
@@ -732,12 +710,8 @@ def test_install_sh_create_shortcuts_seeds_id_from_csprng_with_python_fallback(
     )
     res = subprocess.run(["bash", "-c", gen_script], text = True, capture_output = True)
     assert res.returncode == 0, res.stderr
-    out = dict(
-        line.split("=", 1) for line in res.stdout.strip().splitlines() if "=" in line
-    )
-    assert (
-        out.get("LEN") == "64"
-    ), f"id must be 64 hex chars, got LEN={out.get('LEN')!r}"
+    out = dict(line.split("=", 1) for line in res.stdout.strip().splitlines() if "=" in line)
+    assert out.get("LEN") == "64", f"id must be 64 hex chars, got LEN={out.get('LEN')!r}"
     assert all(
         c in "0123456789abcdef" for c in out.get("ID", "")
     ), f"id must be lowercase hex, got {out.get('ID')!r}"
@@ -751,8 +725,7 @@ def test_install_sh_create_shortcuts_fails_fast_when_no_entropy():
     fn_start = src.index('_css_data_dir="$DATA_DIR"')
     block = src[fn_start : fn_start + 3000]
     assert (
-        "[WARN] Cannot create launcher: no entropy source for studio_install_id"
-        in block
+        "[WARN] Cannot create launcher: no entropy source for studio_install_id" in block
     ), "install.sh must warn when neither urandom nor python3 is available"
     assert (
         "[WARN] Cannot create launcher: failed to read" in block
@@ -770,9 +743,7 @@ def test_install_sh_bakes_installed_is_env_mode_flag_in_launcher():
     assert (
         "_INSTALLED_IS_ENV_MODE='@@INSTALLED_IS_ENV_MODE@@'" in src
     ), "launcher heredoc must declare _INSTALLED_IS_ENV_MODE='@@INSTALLED_IS_ENV_MODE@@'"
-    assert (
-        "_css_is_env_mode=false" in src
-    ), "install.sh must default _css_is_env_mode to false"
+    assert "_css_is_env_mode=false" in src, "install.sh must default _css_is_env_mode to false"
     assert (
         '[ "$_STUDIO_HOME_REDIRECT" = "env" ] && _css_is_env_mode=true' in src
     ), "install.sh must set _css_is_env_mode=true only when _STUDIO_HOME_REDIRECT=env"
@@ -798,8 +769,7 @@ def test_install_sh_launcher_gates_port_file_on_baked_flag_not_runtime_env():
     port_block = heredoc[port_block_start:port_block_end]
     assert 'PORT_FILE="$DATA_DIR/studio.port"' in port_block
     assert (
-        'if [ -n "${UNSLOTH_STUDIO_HOME:-}" ]; then\n    if command -v cksum'
-        not in heredoc
+        'if [ -n "${UNSLOTH_STUDIO_HOME:-}" ]; then\n    if command -v cksum' not in heredoc
     ), "launcher must NOT gate PORT_FILE on runtime UNSLOTH_STUDIO_HOME"
 
     def _run_launcher_gate(installed_flag: str, runtime_env: dict) -> str:
@@ -853,9 +823,7 @@ def test_main_py_studio_root_id_caches_at_module_load():
     ), "_studio_root_id() must NOT do filesystem or hash work on every call"
 
 
-def test_main_py_read_studio_install_id_validates_hex_and_handles_missing(
-    tmp_path, monkeypatch
-):
+def test_main_py_read_studio_install_id_validates_hex_and_handles_missing(tmp_path, monkeypatch):
     """_read_studio_install_id reads $STUDIO_HOME/share/studio_install_id and
     returns "" when the file is absent, empty, contains non-hex content, or
     is the wrong length. "" triggers the launcher's "no baked id, accept any
@@ -887,9 +855,7 @@ def test_main_py_read_studio_install_id_validates_hex_and_handles_missing(
     id_file.write_text("")
     assert _read(root) == ""
     # Non-hex content -> empty
-    id_file.write_text(
-        "not-a-hex-id-just-text-padded-to-64-chars-zzzzzzzzzzzzzzzzzzzzzz"
-    )
+    id_file.write_text("not-a-hex-id-just-text-padded-to-64-chars-zzzzzzzzzzzzzzzzzzzzzz")
     assert _read(root) == ""
     # Uppercase hex -> empty (must be lowercase)
     id_file.write_text("F" * 64)
diff --git a/tests/test_studio_root_resilience.py b/tests/test_studio_root_resilience.py
index 1ce0430dc4..9037d6965c 100644
--- a/tests/test_studio_root_resilience.py
+++ b/tests/test_studio_root_resilience.py
@@ -22,9 +22,7 @@ import pytest
 
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
-STORAGE_ROOTS = (
-    REPO_ROOT / "studio" / "backend" / "utils" / "paths" / "storage_roots.py"
-)
+STORAGE_ROOTS = REPO_ROOT / "studio" / "backend" / "utils" / "paths" / "storage_roots.py"
 LLAMA_CPP = REPO_ROOT / "studio" / "backend" / "core" / "inference" / "llama_cpp.py"
 
 
@@ -128,18 +126,14 @@ def test_search_roots_keeps_custom_when_resolve_fails(tmp_path):
     home.mkdir()
     custom = tmp_path / "custom_studio"
     custom.mkdir()
-    roots = _exec_search_roots_block(
-        home = home, studio_root_value = custom, resolve_raises = True
-    )
+    roots = _exec_search_roots_block(home = home, studio_root_value = custom, resolve_raises = True)
     # On resolve() failure, the inner except falls back to direct equality;
     # custom != legacy_studio so the custom root must remain in search_roots.
-    assert (
-        custom / "llama.cpp" in roots
-    ), f"custom root dropped on resolve() failure: {roots}"
+    assert custom / "llama.cpp" in roots, f"custom root dropped on resolve() failure: {roots}"
     # custom-mode discovery excludes the legacy tree to match _kill_orphaned_servers.
     assert (
-        (home / ".unsloth" / "llama.cpp") not in roots
-    ), f"legacy llama path must not appear in custom-mode search_roots: {roots}"
+        home / ".unsloth" / "llama.cpp"
+    ) not in roots, f"legacy llama path must not appear in custom-mode search_roots: {roots}"
 
 
 def test_search_roots_default_mode_uses_legacy_only(tmp_path):
@@ -147,8 +141,6 @@ def test_search_roots_default_mode_uses_legacy_only(tmp_path):
     home.mkdir()
     legacy = home / ".unsloth" / "studio"
     legacy.mkdir(parents = True)
-    roots = _exec_search_roots_block(
-        home = home, studio_root_value = legacy, resolve_raises = False
-    )
+    roots = _exec_search_roots_block(home = home, studio_root_value = legacy, resolve_raises = False)
     # Default mode: only legacy_llama.
     assert roots == [home / ".unsloth" / "llama.cpp"]
diff --git a/tests/test_tool_mask_zoo_compat.py b/tests/test_tool_mask_zoo_compat.py
index b6b68a7561..6212b6f807 100644
--- a/tests/test_tool_mask_zoo_compat.py
+++ b/tests/test_tool_mask_zoo_compat.py
@@ -11,9 +11,7 @@ import torch
 
 REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
 RL_SOURCE_PATH = os.path.join(REPO_ROOT, "unsloth", "models", "rl.py")
-RL_REPLACEMENTS_SOURCE_PATH = os.path.join(
-    REPO_ROOT, "unsloth", "models", "rl_replacements.py"
-)
+RL_REPLACEMENTS_SOURCE_PATH = os.path.join(REPO_ROOT, "unsloth", "models", "rl_replacements.py")
 
 
 def _read(path: str) -> str:
@@ -27,10 +25,7 @@ def _load_local_align_completion_tool_mask():
     for node in tree.body:
         if isinstance(node, ast.If):
             for item in node.body:
-                if (
-                    isinstance(item, ast.FunctionDef)
-                    and item.name == "align_completion_tool_mask"
-                ):
+                if isinstance(item, ast.FunctionDef) and item.name == "align_completion_tool_mask":
                     function_src = ast.get_source_segment(src, item)
                     break
             else:
@@ -41,7 +36,11 @@ def _load_local_align_completion_tool_mask():
 
     calls = []
 
-    def align_logprobs_with_mask(logprob_tensor, completion_mask, pad_value = None):
+    def align_logprobs_with_mask(
+        logprob_tensor,
+        completion_mask,
+        pad_value = None,
+    ):
         calls.append((logprob_tensor, completion_mask, pad_value))
         return torch.tensor(
             [[1, 0, 1], [0, 1, 1]],
@@ -90,9 +89,7 @@ def test_grpo_accumulated_loss_omits_none_tool_mask_for_old_zoo():
     accelerated_loss_start = src.find('if hasattr(self.args, "loss_type"):')
     assert accelerated_loss_start != -1
     accelerated_loss_body = src[
-        accelerated_loss_start : src.find(
-            'if "train" in self._metrics:', accelerated_loss_start
-        )
+        accelerated_loss_start : src.find('if "train" in self._metrics:', accelerated_loss_start)
     ]
     assert "tool_mask = tool_mask" not in accelerated_loss_body
 
diff --git a/tests/utils/aime_eval.py b/tests/utils/aime_eval.py
index 131da3e50b..8fd0207180 100644
--- a/tests/utils/aime_eval.py
+++ b/tests/utils/aime_eval.py
@@ -102,9 +102,7 @@ def load_aime_dataset(data_dir: str = "./data/aime") -> List[Dict[str, Any]]:
                     # Format as expected by our evaluation
                     formatted_example = {
                         "global_id": data.get("global_id", line_num),
-                        "original_id": data.get(
-                            "original_id", data.get("id", line_num)
-                        ),
+                        "original_id": data.get("original_id", data.get("id", line_num)),
                         "source_dataset": data.get("source_dataset", "unknown"),
                         "problem": data["problem"],
                         "answer": str(data["answer"]),  # Ensure answer is string
@@ -271,9 +269,7 @@ def evaluate_model_aime(
         print(f"\n🚀 Evaluating {len(eval_dataset)} problems...")
 
         # Main evaluation loop
-        with tqdm(
-            total = len(eval_dataset), desc = "Processing AIME problems", unit = "problem"
-        ) as pbar:
+        with tqdm(total = len(eval_dataset), desc = "Processing AIME problems", unit = "problem") as pbar:
             for task_id, item in enumerate(eval_dataset):
                 try:
                     # Prepare prompt
@@ -293,9 +289,7 @@ def evaluate_model_aime(
 
                     # Process all generated responses
                     responses = [output.text for output in outputs]
-                    extracted_answers = [
-                        extract_aime_answer(response) for response in responses
-                    ]
+                    extracted_answers = [extract_aime_answer(response) for response in responses]
 
                     # Calculate total output tokens
                     total_output_tokens = sum(
@@ -305,9 +299,7 @@ def evaluate_model_aime(
 
                     # Check if any answer is correct
                     ground_truth = item["answer"]
-                    correct_responses = [
-                        ans == ground_truth for ans in extracted_answers
-                    ]
+                    correct_responses = [ans == ground_truth for ans in extracted_answers]
                     is_correct = any(correct_responses)
 
                     if is_correct:
@@ -401,12 +393,8 @@ def evaluate_model_aime(
         "max_tokens": max_tokens,
         "top_p": top_p,
         "seed": seed,
-        "avg_input_tokens": sum(input_tokens) / len(input_tokens)
-        if input_tokens
-        else 0,
-        "avg_output_tokens": sum(output_tokens) / len(output_tokens)
-        if output_tokens
-        else 0,
+        "avg_input_tokens": sum(input_tokens) / len(input_tokens) if input_tokens else 0,
+        "avg_output_tokens": sum(output_tokens) / len(output_tokens) if output_tokens else 0,
         "max_input_tokens": max(input_tokens) if input_tokens else 0,
         "max_output_tokens": max(output_tokens) if output_tokens else 0,
     }
@@ -423,17 +411,13 @@ def evaluate_model_aime(
 
     print(f"\n🎯 Overall Performance:")
     print(f"   Total problems:       {total_problems:>6}")
-    print(
-        f"   Correct answers:      {correct_answers:>6}/{total_problems} ({accuracy:>5.1f}%)"
-    )
+    print(f"   Correct answers:      {correct_answers:>6}/{total_problems} ({accuracy:>5.1f}%)")
     print(f"   Pass@{n_sampling}:              {pass_at_k:>10.1f}%")
 
     print(f"\n📈 Performance by Dataset:")
     for source, stats in source_stats.items():
         source_acc = source_accuracies[source]
-        print(
-            f"   {source:>12}: {stats['correct']:>3}/{stats['total']:>3} ({source_acc:>5.1f}%)"
-        )
+        print(f"   {source:>12}: {stats['correct']:>3}/{stats['total']:>3} ({source_acc:>5.1f}%)")
 
     print(f"\n🔧 Configuration:")
     print(f"   Temperature:          {temperature}")
@@ -477,9 +461,7 @@ def compare_aime_results(all_results):
     print(f"{'='*80}")
 
     # Main comparison table
-    print(
-        f"{'Model':<15} {'Accuracy %':<12} {'Pass@K %':<10} {'Correct':<8} {'Total':<8}"
-    )
+    print(f"{'Model':<15} {'Accuracy %':<12} {'Pass@K %':<10} {'Correct':<8} {'Total':<8}")
     print("-" * 80)
 
     for result in all_results:
diff --git a/tests/utils/cleanup_utils.py b/tests/utils/cleanup_utils.py
index af38528196..dbe5dbd556 100644
--- a/tests/utils/cleanup_utils.py
+++ b/tests/utils/cleanup_utils.py
@@ -7,7 +7,11 @@ import sys
 import warnings
 
 
-def clear_memory(variables_to_clear = None, verbose = False, clear_all_caches = True):
+def clear_memory(
+    variables_to_clear = None,
+    verbose = False,
+    clear_all_caches = True,
+):
     """
     Comprehensive memory clearing for persistent memory leaks.
 
@@ -75,9 +79,7 @@ def clear_memory(variables_to_clear = None, verbose = False, clear_all_caches =
             torch.cuda.reset_accumulated_memory_stats()
 
             # Clear JIT cache
-            if hasattr(torch.jit, "_state") and hasattr(
-                torch.jit._state, "_clear_class_state"
-            ):
+            if hasattr(torch.jit, "_state") and hasattr(torch.jit._state, "_clear_class_state"):
                 torch.jit._state._clear_class_state()
 
             # Force another CUDA cache clear
@@ -89,9 +91,7 @@ def clear_memory(variables_to_clear = None, verbose = False, clear_all_caches =
         if verbose:
             mem_after = torch.cuda.memory_allocated() / 1024**3
             mem_reserved = torch.cuda.memory_reserved() / 1024**3
-            print(
-                f"GPU memory - Before: {mem_before:.2f} GB, After: {mem_after:.2f} GB"
-            )
+            print(f"GPU memory - Before: {mem_before:.2f} GB, After: {mem_after:.2f} GB")
             print(f"GPU reserved memory: {mem_reserved:.2f} GB")
             if mem_before > 0:
                 print(f"Memory freed: {mem_before - mem_after:.2f} GB")
diff --git a/tests/utils/data_utils.py b/tests/utils/data_utils.py
index 9551688437..48d732b5f8 100644
--- a/tests/utils/data_utils.py
+++ b/tests/utils/data_utils.py
@@ -28,7 +28,11 @@ def create_instruction_dataset(messages: list[dict] = DEFAULT_MESSAGES):
     return dataset
 
 
-def create_dataset(tokenizer, num_examples: int = None, messages: list[dict] = None):
+def create_dataset(
+    tokenizer,
+    num_examples: int = None,
+    messages: list[dict] = None,
+):
     dataset = create_instruction_dataset(messages)
 
     def _apply_chat_template(example):
@@ -119,9 +123,7 @@ def format_summary(stats: dict, precision: int = 6) -> str:
             # Format each element in tuples or lists (e.g., the shape)
             formatted_value = ", ".join(str(v) for v in value)
             formatted_value = (
-                f"({formatted_value})"
-                if isinstance(value, tuple)
-                else f"[{formatted_value}]"
+                f"({formatted_value})" if isinstance(value, tuple) else f"[{formatted_value}]"
             )
         else:
             formatted_value = str(value)
@@ -132,9 +134,7 @@ def format_summary(stats: dict, precision: int = 6) -> str:
 def get_peft_weights(model):
     # ruff: noqa
     is_lora_weight = lambda name: any(s in name for s in ["lora_A", "lora_B"])
-    return {
-        name: param for name, param in model.named_parameters() if is_lora_weight(name)
-    }
+    return {name: param for name, param in model.named_parameters() if is_lora_weight(name)}
 
 
 def describe_peft_weights(model):
@@ -142,7 +142,11 @@ def describe_peft_weights(model):
         yield name, describe_param(param, as_str = True)
 
 
-def check_responses(responses: list[str], answer: str, prompt: str = None) -> bool:
+def check_responses(
+    responses: list[str],
+    answer: str,
+    prompt: str = None,
+) -> bool:
     for i, response in enumerate(responses, start = 1):
         if answer in response:
             print(f"\u2713 response {i} contains answer")
diff --git a/tests/utils/generate_dataset_with_none.py b/tests/utils/generate_dataset_with_none.py
index 71d228963a..decda5d5a6 100644
--- a/tests/utils/generate_dataset_with_none.py
+++ b/tests/utils/generate_dataset_with_none.py
@@ -130,9 +130,7 @@ _CHATML_ROWS = [
             {"role": "assistant", "content": "  \t  "},
         ]
     },  # tab whitespace
-    {
-        "messages": [None, {"role": "assistant", "content": "Reply"}]
-    },  # None turn element
+    {"messages": [None, {"role": "assistant", "content": "Reply"}]},  # None turn element
 ]
 
 # P1 test rows: messages is None or non-list.
@@ -255,9 +253,7 @@ def make_alpaca_dataset() -> Dataset:
 
 if __name__ == "__main__":
     print("Synthetic dataset sizes:")
-    print(
-        f"  chatml:   {len(_CHATML_ROWS)} rows (+ {len(_CHATML_P1_ROWS)} P1 mock rows)"
-    )
+    print(f"  chatml:   {len(_CHATML_ROWS)} rows (+ {len(_CHATML_P1_ROWS)} P1 mock rows)")
     print(f"  sharegpt: {len(_SHAREGPT_ROWS)} rows")
     print(f"  alpaca:   {len(_ALPACA_ROWS)} rows")
     print(
diff --git a/tests/utils/hf_utils.py b/tests/utils/hf_utils.py
index 8ad6d5ad08..22d984f87a 100644
--- a/tests/utils/hf_utils.py
+++ b/tests/utils/hf_utils.py
@@ -37,32 +37,19 @@ from trl import SFTTrainer
 
 class PeftWeightCallback(TrainerCallback):
     def on_log(
-        self,
-        args: TrainingArguments,
-        state: TrainerState,
-        control: TrainerControl,
-        logs,
-        **kwargs,
+        self, args: TrainingArguments, state: TrainerState, control: TrainerControl, logs, **kwargs
     ):
         print(f"DEBUG::CALLBACK::on_log::{state.log_history}")
 
     def on_train_begin(
-        self,
-        args: TrainingArguments,
-        state: TrainerState,
-        control: TrainerControl,
-        **kwargs,
+        self, args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs
     ):
         model = kwargs.get("model")
         assert model is not None
         print(f"DEBUG::CALLBACK::on_train_begin::{kwargs.keys()}")
 
     def on_step_end(
-        self,
-        args: TrainingArguments,
-        state: TrainerState,
-        control: TrainerControl,
-        **kwargs,
+        self, args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs
     ):
         print(f"DEBUG::CALLBACK::on_step_end::{state.global_step}")
 
@@ -82,8 +69,7 @@ def generate_responses(
     inputs = [tokenizer(prompt, return_tensors = "pt") for _ in range(num_generations)]
     keys = inputs[0].keys()
     batched_inputs = {
-        key: torch.cat([input[key] for input in inputs], dim = 0).to(model.device)
-        for key in keys
+        key: torch.cat([input[key] for input in inputs], dim = 0).to(model.device) for key in keys
     }
 
     if dtype is not None:
@@ -160,9 +146,7 @@ def setup_model(
     model = prepare_model_for_kbit_training(model) if quantize else model
 
     if peft_config is not None:
-        model = get_peft_model(
-            model, peft_config, autocast_adapter_dtype = autocast_adapter
-        )
+        model = get_peft_model(model, peft_config, autocast_adapter_dtype = autocast_adapter)
 
     return model
 
@@ -246,9 +230,7 @@ def fix_llama3_tokenizer(tokenizer, padding_side = "right"):
 
 
 def replace_module(
-    module: torch.nn.Module,
-    target_module_type: torch.nn.Module,
-    conversion_func: Callable,
+    module: torch.nn.Module, target_module_type: torch.nn.Module, conversion_func: Callable
 ):
     for child_name, child_module in module.named_children():
         if isinstance(child_module, target_module_type):
diff --git a/tests/utils/ocr_eval.py b/tests/utils/ocr_eval.py
index 3c5cd74a22..05c56982f8 100644
--- a/tests/utils/ocr_eval.py
+++ b/tests/utils/ocr_eval.py
@@ -55,8 +55,8 @@ class OCRModelEvaluator:
                 messages = sample["messages"]
 
                 # Get ground truth, image, and question
-                ground_truth, image, question, input_messages = (
-                    self._extract_sample_components(messages, i, verbose)
+                ground_truth, image, question, input_messages = self._extract_sample_components(
+                    messages, i, verbose
                 )
 
                 if ground_truth is None or image is None or question is None:
@@ -108,9 +108,7 @@ class OCRModelEvaluator:
         """Extract ground truth, image, question, and input messages from sample."""
 
         # Extract system message (if present)
-        system_message = next(
-            (msg for msg in messages if msg["role"] == "system"), None
-        )
+        system_message = next((msg for msg in messages if msg["role"] == "system"), None)
 
         # Extract user message with the image and question
         user_message = next((msg for msg in messages if msg["role"] == "user"), None)
@@ -120,14 +118,10 @@ class OCRModelEvaluator:
             return None, None, None, []
 
         # Extract assistant message with ground truth
-        assistant_message = next(
-            (msg for msg in messages if msg["role"] == "assistant"), None
-        )
+        assistant_message = next((msg for msg in messages if msg["role"] == "assistant"), None)
         if not assistant_message:
             if verbose:
-                print(
-                    f"Skipping sample {sample_idx}: No assistant message (ground truth) found"
-                )
+                print(f"Skipping sample {sample_idx}: No assistant message (ground truth) found")
             return None, None, None, []
 
         # Extract ground truth text
@@ -139,9 +133,7 @@ class OCRModelEvaluator:
 
         if not ground_truth:
             if verbose:
-                print(
-                    f"Skipping sample {sample_idx}: No text found in assistant message"
-                )
+                print(f"Skipping sample {sample_idx}: No text found in assistant message")
             return None, None, None, []
 
         # Extract image and question from user message
@@ -161,9 +153,7 @@ class OCRModelEvaluator:
 
         if not question:
             if verbose:
-                print(
-                    f"Skipping sample {sample_idx}: No question found in user message"
-                )
+                print(f"Skipping sample {sample_idx}: No question found in user message")
             return None, None, None, []
 
         # Construct messages for the model input (excluding assistant message)
@@ -215,8 +205,7 @@ class OCRModelEvaluator:
 
         # Extract only the generated part (not the input)
         generated_ids_trimmed = [
-            out_ids[len(in_ids) :]
-            for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+            out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
         ]
 
         # Decode the generated text
@@ -283,7 +272,9 @@ class OCRModelEvaluator:
         self.model_comparison_results[model_name] = {"wer": wer, "cer": cer}
 
     def print_model_comparison(
-        self, save_csv: bool = True, save_plot: bool = True
+        self,
+        save_csv: bool = True,
+        save_plot: bool = True,
     ) -> Optional[pd.DataFrame]:
         """Print a comparison of all models evaluated so far."""
         if not self.model_comparison_results:
@@ -296,12 +287,8 @@ class OCRModelEvaluator:
         comparison_df = pd.DataFrame(
             {
                 "Model": list(self.model_comparison_results.keys()),
-                "WER": [
-                    results["wer"] for results in self.model_comparison_results.values()
-                ],
-                "CER": [
-                    results["cer"] for results in self.model_comparison_results.values()
-                ],
+                "WER": [results["wer"] for results in self.model_comparison_results.values()],
+                "CER": [results["cer"] for results in self.model_comparison_results.values()],
             }
         )
 
@@ -360,7 +347,11 @@ class OCRModelEvaluator:
 
 
 def evaluate_ocr_model(
-    model, processor, dataset, output_dir = "ocr_evaluation_results", **kwargs
+    model,
+    processor,
+    dataset,
+    output_dir = "ocr_evaluation_results",
+    **kwargs,
 ):
     """
     Convenience function that maintains backward compatibility with the original function.
diff --git a/tests/utils/os_utils.py b/tests/utils/os_utils.py
index 448f13b8a0..7bf0821200 100644
--- a/tests/utils/os_utils.py
+++ b/tests/utils/os_utils.py
@@ -34,22 +34,16 @@ def check_package_installed(package_name, package_manager = None):
     try:
         if package_manager == "apt":
             # Check with dpkg
-            result = subprocess.run(
-                ["dpkg", "-l", package_name], capture_output = True, text = True
-            )
+            result = subprocess.run(["dpkg", "-l", package_name], capture_output = True, text = True)
             return result.returncode == 0
 
         elif package_manager in ["yum", "dnf"]:
             # Check with rpm
-            result = subprocess.run(
-                ["rpm", "-q", package_name], capture_output = True, text = True
-            )
+            result = subprocess.run(["rpm", "-q", package_name], capture_output = True, text = True)
             return result.returncode == 0
 
         elif package_manager == "pacman":
-            result = subprocess.run(
-                ["pacman", "-Q", package_name], capture_output = True, text = True
-            )
+            result = subprocess.run(["pacman", "-Q", package_name], capture_output = True, text = True)
             return result.returncode == 0
 
         elif package_manager == "zypper":
@@ -109,7 +103,11 @@ def require_package(package_name, executable_name = None):
 # require_package("ffmpeg", "ffmpeg")
 
 
-def require_python_package(package_name, import_name = None, pip_name = None):
+def require_python_package(
+    package_name,
+    import_name = None,
+    pip_name = None,
+):
     """Require a Python package to be installed, exit if not found"""
     if import_name is None:
         import_name = package_name
diff --git a/tests/utils/perplexity_eval.py b/tests/utils/perplexity_eval.py
index cf625fc74e..bebc5ed99c 100644
--- a/tests/utils/perplexity_eval.py
+++ b/tests/utils/perplexity_eval.py
@@ -22,14 +22,10 @@ def ppl_model(model, tokenizer, dataset):
             target_ids = input_ids.clone()
             target_ids[:, :-trg_len] = -100
             # Create attention mask based on pad token id
-            pad_token_id = (
-                tokenizer.pad_token_id if tokenizer.pad_token_id is not None else 0
-            )
+            pad_token_id = tokenizer.pad_token_id if tokenizer.pad_token_id is not None else 0
             attention_mask = (input_ids != pad_token_id).long()
             with torch.no_grad():
-                outputs = model(
-                    input_ids, labels = target_ids, attention_mask = attention_mask
-                )
+                outputs = model(input_ids, labels = target_ids, attention_mask = attention_mask)
                 neg_log_likelihood = outputs.loss
             nlls.append(neg_log_likelihood)
             prev_end_loc = end_loc
@@ -68,9 +64,7 @@ def print_model_comparison():
             # "Perplexity": [results["ppl"] for results in model_comparison_results.values()],
             "Perplexity": [
                 # Convert tensors to CPU and then to float if needed
-                results["ppl"].cpu().item()
-                if torch.is_tensor(results["ppl"])
-                else results["ppl"]
+                results["ppl"].cpu().item() if torch.is_tensor(results["ppl"]) else results["ppl"]
                 for results in model_comparison_results.values()
             ],
         }
diff --git a/tests/utils/run_none_detect_tests.py b/tests/utils/run_none_detect_tests.py
index 8fc31faf04..979d3865c9 100644
--- a/tests/utils/run_none_detect_tests.py
+++ b/tests/utils/run_none_detect_tests.py
@@ -66,7 +66,11 @@ def section(title: str):
     print(f"{line}")
 
 
-def run_scan(dataset, label: str, fmt: str = "auto") -> dict | None:
+def run_scan(
+    dataset,
+    label: str,
+    fmt: str = "auto",
+) -> dict | None:
     print(f"\n--- Scanning: {label} (fmt={fmt}) ---")
     try:
         stats = scan_dataset(dataset, fmt = fmt)
@@ -183,9 +187,7 @@ def test_probe_p1_fix():
         )
         return stats
     except ValueError as exc:
-        print(
-            f"  [FAIL] scan_dataset raised ValueError (probe P1 bug NOT fixed): {exc}"
-        )
+        print(f"  [FAIL] scan_dataset raised ValueError (probe P1 bug NOT fixed): {exc}")
         return None
 
 
@@ -239,18 +241,14 @@ def test_explicit_fmt_corrupt():
         )
         return stats
     except ValueError as exc:
-        print(
-            f"  [FAIL] scan_dataset raised ValueError (explicit-fmt P1 NOT fixed): {exc}"
-        )
+        print(f"  [FAIL] scan_dataset raised ValueError (explicit-fmt P1 NOT fixed): {exc}")
         return None
 
 
 def test_p2_probe_skips_corrupt_prefers_valid():
     """P2 fix: probe must continue past a corrupt 'messages' column and find
     a valid 'conversations' column rather than returning all_corrupt immediately."""
-    section(
-        "P2 Fix Verification — probe continues past corrupt first column to valid second"
-    )
+    section("P2 Fix Verification — probe continues past corrupt first column to valid second")
 
     # messages column is all-None; conversations is a valid ShareGPT column.
     rows = [
@@ -272,9 +270,7 @@ def test_p2_probe_skips_corrupt_prefers_valid():
     ] * 2
     mock_ds = _MockDataset(rows, ["messages", "conversations"])
 
-    print(
-        f"  Rows: {len(rows)} — messages=None, conversations=valid ShareGPT (2 bad value='')"
-    )
+    print(f"  Rows: {len(rows)} — messages=None, conversations=valid ShareGPT (2 bad value='')")
     try:
         stats = scan_dataset(mock_ds, fmt = "auto")
         fmt = stats.get("format", "?")
@@ -299,9 +295,7 @@ def test_p2_probe_skips_corrupt_prefers_valid():
 def test_p2_explicit_fmt_col_priority():
     """P2 fix: explicit fmt='sharegpt' must let find_none_sharegpt choose its own
     column (conversations) rather than being forced onto the probe's column (messages)."""
-    section(
-        "P2 Fix Verification — explicit fmt='sharegpt' respects per-scanner column priority"
-    )
+    section("P2 Fix Verification — explicit fmt='sharegpt' respects per-scanner column priority")
 
     # messages has valid role/content turns (chatml-ish); conversations has bad sharegpt turns.
     rows = [
@@ -318,9 +312,7 @@ def test_p2_explicit_fmt_col_priority():
     ] * 5
     mock_ds = _MockDataset(rows, ["messages", "conversations"])
 
-    print(
-        f"  Rows: {len(rows)} — messages=clean chatml, conversations=bad sharegpt (value=None)"
-    )
+    print(f"  Rows: {len(rows)} — messages=clean chatml, conversations=bad sharegpt (value=None)")
     stats = scan_dataset(mock_ds, fmt = "sharegpt")
     col = stats.get("column", "?")
     bad = len(stats.get("bad_row_indices", []))
@@ -353,9 +345,7 @@ def test_p2_gptoss_col_priority():
     ] * 5
     mock_ds = _MockDataset(rows, ["messages", "conversations"])
 
-    print(
-        f"  Rows: {len(rows)} — messages=None (corrupt), conversations=clean sharegpt"
-    )
+    print(f"  Rows: {len(rows)} — messages=None (corrupt), conversations=clean sharegpt")
     try:
         stats = scan_dataset(mock_ds, fmt = "gptoss")
         col = stats.get("column", "?")
@@ -417,9 +407,7 @@ def test_new_p2_plain_string_messages_not_chatml():
     rows = [{"messages": "hello world"}] * 5
     mock_ds = _MockDataset(rows, ["messages"])
 
-    print(
-        f"  Rows: {len(rows)} — messages='hello world' (plain strings, not conversation)"
-    )
+    print(f"  Rows: {len(rows)} — messages='hello world' (plain strings, not conversation)")
     try:
         stats = scan_dataset(mock_ds, fmt = "auto")
         fmt = stats.get("format", "?")
@@ -510,9 +498,7 @@ def _brute_force_bad_rows(ds, fmt: str) -> set:
                 bad.add(i)
                 continue
             for turn in msgs:
-                if turn is None or (
-                    isinstance(turn, dict) and _blank(turn.get("content"))
-                ):
+                if turn is None or (isinstance(turn, dict) and _blank(turn.get("content"))):
                     bad.add(i)
                     break
         elif fmt == "sharegpt":
@@ -521,9 +507,7 @@ def _brute_force_bad_rows(ds, fmt: str) -> set:
                 bad.add(i)
                 continue
             for turn in convs:
-                if turn is None or (
-                    isinstance(turn, dict) and _blank(turn.get("value"))
-                ):
+                if turn is None or (isinstance(turn, dict) and _blank(turn.get("value"))):
                     bad.add(i)
                     break
         elif fmt == "alpaca":
@@ -651,9 +635,7 @@ def main():
         all_results["probe_p1_fix"] = test_probe_p1_fix()
         all_results["probe_string_corrupt"] = test_probe_string_corrupt()
         all_results["explicit_fmt_corrupt"] = test_explicit_fmt_corrupt()
-        all_results["p2_probe_valid_fallback"] = (
-            test_p2_probe_skips_corrupt_prefers_valid()
-        )
+        all_results["p2_probe_valid_fallback"] = test_p2_probe_skips_corrupt_prefers_valid()
         all_results["p2_explicit_col_priority"] = test_p2_explicit_fmt_col_priority()
         all_results["p2_gptoss_col_priority"] = test_p2_gptoss_col_priority()
         all_results["new_p1_sharegpt_all_corrupt"] = (
@@ -729,9 +711,7 @@ def main():
                         "format": val.get("format"),
                         "total_rows": val.get("total_rows"),
                         "bad_row_count": len(val.get("bad_row_indices", [])),
-                        "bad_turn_count": val.get(
-                            "total_none_turns", len(val.get("findings", []))
-                        ),
+                        "bad_turn_count": val.get("total_none_turns", len(val.get("findings", []))),
                     }
 
         json_path.write_text(json.dumps(summary, indent = 2), encoding = "utf-8")
diff --git a/tests/utils/test_attention_masks.py b/tests/utils/test_attention_masks.py
index dbd5419617..627da0552f 100644
--- a/tests/utils/test_attention_masks.py
+++ b/tests/utils/test_attention_masks.py
@@ -57,7 +57,11 @@ def test_sdpa_packed_attention_mask_sliding_window():
 
 def test_xformers_block_mask_sliding_window(monkeypatch):
     class _FakeMask:
-        def __init__(self, lengths, window = None):
+        def __init__(
+            self,
+            lengths,
+            window = None,
+        ):
             self.lengths = lengths
             self.window = window
 
@@ -87,7 +91,13 @@ def test_run_attention_sdpa_passes_sliding_window(monkeypatch):
     original_builder = attention_dispatch.build_sdpa_packed_attention_mask
     captured = {}
 
-    def _capture_builder(seq_info_arg, *, dtype, device, sliding_window = None):
+    def _capture_builder(
+        seq_info_arg,
+        *,
+        dtype,
+        device,
+        sliding_window = None,
+    ):
         captured["window"] = sliding_window
         return original_builder(
             seq_info_arg,
@@ -154,24 +164,29 @@ def test_run_attention_xformers_passes_sliding_window(monkeypatch):
 
     captured = {}
 
-    def _fake_builder(seq_info_arg, *, sliding_window = None, base_mask = None):
+    def _fake_builder(
+        seq_info_arg,
+        *,
+        sliding_window = None,
+        base_mask = None,
+    ):
         captured["window"] = sliding_window
         captured["base"] = base_mask
         return _FakeBias()
 
-    def _fake_attention(Q, K, V, attn_bias = None, **_):
+    def _fake_attention(
+        Q,
+        K,
+        V,
+        attn_bias = None,
+        **_,
+    ):
         captured["bias"] = attn_bias
         return torch.zeros_like(Q)
 
-    monkeypatch.setattr(
-        attention_dispatch, "build_xformers_block_causal_mask", _fake_builder
-    )
-    monkeypatch.setattr(
-        attention_dispatch, "xformers_attention", _fake_attention, raising = False
-    )
-    monkeypatch.setattr(
-        attention_dispatch, "XFORMERS_BLOCK_DIAG_CLS", _FakeBias, raising = False
-    )
+    monkeypatch.setattr(attention_dispatch, "build_xformers_block_causal_mask", _fake_builder)
+    monkeypatch.setattr(attention_dispatch, "xformers_attention", _fake_attention, raising = False)
+    monkeypatch.setattr(attention_dispatch, "XFORMERS_BLOCK_DIAG_CLS", _FakeBias, raising = False)
 
     config = attention_dispatch.AttentionConfig(
         backend = attention_dispatch.XFORMERS,
diff --git a/tests/utils/test_packing.py b/tests/utils/test_packing.py
index 098f6a3667..590419ad52 100644
--- a/tests/utils/test_packing.py
+++ b/tests/utils/test_packing.py
@@ -190,9 +190,7 @@ class _DummyTrainer:
         ]
         for extra in optional_flags:
             try:
-                self.data_collator = DataCollatorForLanguageModeling(
-                    **collator_args, **extra
-                )
+                self.data_collator = DataCollatorForLanguageModeling(**collator_args, **extra)
                 break
             except TypeError:
                 continue
@@ -247,10 +245,7 @@ def test_enable_sample_packing():
 
     # packed lengths are aggregated into a single tensor
     assert "packed_seq_lengths" in batch
-    assert torch.equal(
-        batch["packed_seq_lengths"],
-        torch.tensor([2, 1, 3], dtype = torch.int32),
-    )
+    assert torch.equal(batch["packed_seq_lengths"], torch.tensor([2, 1, 3], dtype = torch.int32))
 
     assert batch["input_ids"].shape == (1, 6)
     expected_positions = torch.tensor([0, 1, 0, 0, 1, 2], dtype = torch.long)
@@ -279,10 +274,7 @@ def test_enable_sample_packing_trl_collator(tmp_path):
     batch = trainer.data_collator.torch_call(examples)
 
     assert batch["input_ids"].shape == (1, 6)
-    assert torch.equal(
-        batch["packed_seq_lengths"],
-        torch.tensor([2, 1, 3], dtype = torch.int32),
-    )
+    assert torch.equal(batch["packed_seq_lengths"], torch.tensor([2, 1, 3], dtype = torch.int32))
 
     expected_positions = torch.tensor([0, 1, 0, 0, 1, 2], dtype = torch.long)
     assert torch.equal(batch["position_ids"].view(-1)[:6], expected_positions)
@@ -312,10 +304,7 @@ def test_enable_padding_free_metadata():
         {"input_ids": [3, 4]},
     ]
     batch = collator.torch_call(examples)
-    assert torch.equal(
-        batch["packed_seq_lengths"],
-        torch.tensor([3, 2], dtype = torch.int32),
-    )
+    assert torch.equal(batch["packed_seq_lengths"], torch.tensor([3, 2], dtype = torch.int32))
     assert trainer.args.remove_unused_columns is False
 
 
@@ -334,10 +323,7 @@ def test_packing_sdpa(tmp_path):
     assert "position_ids" in batch
     flat_positions = batch["position_ids"].reshape(-1)[:packed_tokens]
     expected_positions = torch.cat(
-        [
-            torch.arange(length, dtype = torch.long)
-            for length in batch["packed_seq_lengths"].tolist()
-        ]
+        [torch.arange(length, dtype = torch.long) for length in batch["packed_seq_lengths"].tolist()]
     )
     assert torch.equal(flat_positions.cpu(), expected_positions)
     inputs = _trim_batch_to_total_tokens(batch, packed_tokens)
@@ -352,7 +338,13 @@ def test_packing_sdpa(tmp_path):
     mask_calls = []
     captured_loss_labels = {}
 
-    def _capture_mask(seq_info, dtype, device, *, sliding_window = None):
+    def _capture_mask(
+        seq_info,
+        dtype,
+        device,
+        *,
+        sliding_window = None,
+    ):
         mask_calls.append(tuple(seq_info[0].tolist()))
         return original_mask(
             seq_info,
@@ -366,12 +358,8 @@ def test_packing_sdpa(tmp_path):
         return torch.zeros((), device = logits.device, dtype = logits.dtype)
 
     with ExitStack() as stack:
-        stack.enter_context(
-            patch.object(attention_dispatch_utils, "HAS_FLASH_ATTENTION", False)
-        )
-        stack.enter_context(
-            patch.object(attention_dispatch_utils, "HAS_XFORMERS", False)
-        )
+        stack.enter_context(patch.object(attention_dispatch_utils, "HAS_FLASH_ATTENTION", False))
+        stack.enter_context(patch.object(attention_dispatch_utils, "HAS_XFORMERS", False))
         stack.enter_context(
             patch.object(
                 attention_dispatch_utils,
@@ -394,10 +382,7 @@ def test_packing_sdpa(tmp_path):
     assert "labels" in captured_loss_labels
     flat_loss_labels = captured_loss_labels["labels"].reshape(-1)
     boundaries = (
-        torch.cumsum(
-            batch["packed_seq_lengths"].to(device = "cpu", dtype = torch.long), dim = 0
-        )
-        - 1
+        torch.cumsum(batch["packed_seq_lengths"].to(device = "cpu", dtype = torch.long), dim = 0) - 1
     )
     for idx in boundaries.tolist():
         assert flat_loss_labels[idx].item() == -100
diff --git a/tests/utils/test_q_galore.py b/tests/utils/test_q_galore.py
index 6dea5014a0..3a2925fca1 100644
--- a/tests/utils/test_q_galore.py
+++ b/tests/utils/test_q_galore.py
@@ -201,9 +201,7 @@ class TestQuantizationUtils:
             errors.append((w - w_hat).mean().item())
 
         mean_error = sum(errors) / len(errors)
-        assert (
-            abs(mean_error) < 0.01
-        ), f"Mean error {mean_error} suggests biased rounding"
+        assert abs(mean_error) < 0.01, f"Mean error {mean_error} suggests biased rounding"
 
 
 # ======================================================================
@@ -235,9 +233,7 @@ class TestParamGroupHelper:
         # q_proj and k_proj should be in galore group (2 params)
         assert len(galore_group["params"]) == 2
         # embed and norm should be in non-galore group
-        assert (
-            len(non_galore_group["params"]) == 3
-        )  # embed weight + norm weight + norm bias
+        assert len(non_galore_group["params"]) == 3  # embed weight + norm weight + norm bias
 
     def test_custom_target_modules(self):
         """Custom target_modules narrows GaLore scope."""
@@ -294,9 +290,7 @@ class TestParamGroupHelper:
         )
 
         galore_groups = [g for g in groups if "rank" in g]
-        assert (
-            len(galore_groups) == 0
-        ), "Expected no GaLore groups when target_modules=[]"
+        assert len(galore_groups) == 0, "Expected no GaLore groups when target_modules=[]"
 
 
 # ======================================================================
@@ -340,9 +334,7 @@ class TestQGaLoreIntegration:
             optimizer.step()
 
         # Loss should decrease
-        assert (
-            losses[-1] < losses[0]
-        ), f"Loss did not decrease: {losses[0]:.4f} → {losses[-1]:.4f}"
+        assert losses[-1] < losses[0], f"Loss did not decrease: {losses[0]:.4f} → {losses[-1]:.4f}"
 
     def test_full_projector_roundtrip_quality(self):
         """project → project_back captures the dominant gradient directions."""
@@ -359,9 +351,7 @@ class TestQGaLoreIntegration:
         # For a rank-4 gradient with rank-4 projection, reconstruction
         # should be very close to original
         relative_error = (grad - reconstructed).norm() / grad.norm()
-        assert (
-            relative_error < 0.05
-        ), f"Reconstruction error too high: {relative_error:.4f}"
+        assert relative_error < 0.05, f"Reconstruction error too high: {relative_error:.4f}"
 
     def test_weight_quant_activates_on_first_step(self):
         """_has_weight_quant returns True even when _q_scales is None (first step)."""
@@ -479,9 +469,7 @@ class TestQGaLoreIntegration:
 
         # Replicate the re-quantize logic at the end of optimizer step
         float_data = p.data.clone()
-        q, scales, zeros, shape = _quantize(
-            float_data, q_group_size = group["weight_group_size"]
-        )
+        q, scales, zeros, shape = _quantize(float_data, q_group_size = group["weight_group_size"])
 
         # The key assertion: p.data stays float, _q_data holds uint8
         p._q_data = q.to(p.data.device)
diff --git a/tests/utils/test_qat.py b/tests/utils/test_qat.py
index 08b8cd3930..5c87db4e3d 100644
--- a/tests/utils/test_qat.py
+++ b/tests/utils/test_qat.py
@@ -103,10 +103,7 @@ def _test_linear_is_fake_quantized(linear: torch.nn.Linear, qat_scheme: str):
 
 
 def _test_fake_quantizers_are_called(
-    model: torch.nn.Module,
-    example_inputs: Dict,
-    full_finetuning: bool,
-    qat_scheme: str,
+    model: torch.nn.Module, example_inputs: Dict, full_finetuning: bool, qat_scheme: str
 ):
     """
     Verify that the fake quantizers are actually called when the model is called.
diff --git a/tests/utils/test_trunc_normal_patch.py b/tests/utils/test_trunc_normal_patch.py
index b84a0772d8..0ccd455674 100644
--- a/tests/utils/test_trunc_normal_patch.py
+++ b/tests/utils/test_trunc_normal_patch.py
@@ -29,9 +29,7 @@ _MISSING = object()
 def _load_import_fixes_module():
     repo_root = Path(__file__).resolve().parents[2]
     import_fixes_path = repo_root / "unsloth" / "import_fixes.py"
-    spec = importlib.util.spec_from_file_location(
-        "unsloth_import_fixes_local", import_fixes_path
-    )
+    spec = importlib.util.spec_from_file_location("unsloth_import_fixes_local", import_fixes_path)
     assert spec is not None and spec.loader is not None
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
diff --git a/tests/version_compat/_fetch.py b/tests/version_compat/_fetch.py
index ba65019c70..be96823016 100644
--- a/tests/version_compat/_fetch.py
+++ b/tests/version_compat/_fetch.py
@@ -43,7 +43,11 @@ def fetch_text(repo: str, ref: str, path: str) -> str | None:
         pytest.skip(f"GitHub fetch failed ({e}) for {url}")
 
 
-def has_def(src: str, name: str, kind: str = "any") -> bool:
+def has_def(
+    src: str,
+    name: str,
+    kind: str = "any",
+) -> bool:
     """Heuristic AST-equivalent grep for `class Name`, `def name`,
     or `Name = ...` — at any indent level. We avoid a full ast.parse
     so a single non-importable line (e.g. `# type: ignore` after an
diff --git a/tests/version_compat/test_bitsandbytes_pinned_symbols.py b/tests/version_compat/test_bitsandbytes_pinned_symbols.py
index 8c6277f829..ec6e5fdaa1 100644
--- a/tests/version_compat/test_bitsandbytes_pinned_symbols.py
+++ b/tests/version_compat/test_bitsandbytes_pinned_symbols.py
@@ -50,15 +50,12 @@ def test_bnb_functional_4bit(tag: str):
         "bitsandbytes/functional/__init__.py",
     ]
     hit = first_match("bitsandbytes-foundation/bitsandbytes", tag, candidates)
-    assert (
-        hit is not None
-    ), f"{tag}: bitsandbytes/functional[.py|/__init__.py] both missing"
+    assert hit is not None, f"{tag}: bitsandbytes/functional[.py|/__init__.py] both missing"
     _, src = hit
     needed = ("dequantize_4bit", "quantize_4bit")
     missing = [n for n in needed if not has_def(src, n, "func") and n not in src]
     assert not missing, (
-        f"{tag}: bnb.functional missing {missing}; "
-        f"unsloth-zoo dequant kernels rely on these"
+        f"{tag}: bnb.functional missing {missing}; " f"unsloth-zoo dequant kernels rely on these"
     )
 
 
@@ -106,9 +103,7 @@ def test_bnb_nn_linear4bit_classes(tag: str):
 
 @pytest.mark.parametrize("tag", BNB_TAGS)
 def test_bnb_matmul_4bit_top_level(tag: str):
-    src = fetch_text(
-        "bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/__init__.py"
-    )
+    src = fetch_text("bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/__init__.py")
     if src is None:
         pytest.skip(f"{tag}: bitsandbytes/__init__.py missing")
     assert "matmul_4bit" in src, (
@@ -181,12 +176,9 @@ def test_bnb_quantstate_from_dict(tag: str):
     if hit is None:
         pytest.skip(f"{tag}: functional missing")
     _, src = hit
-    assert has_def(
-        src, "QuantState", "class"
-    ), f"{tag}: bnb.functional.QuantState missing"
+    assert has_def(src, "QuantState", "class"), f"{tag}: bnb.functional.QuantState missing"
     assert "from_dict" in src, (
-        f"{tag}: QuantState.from_dict missing; "
-        f"unsloth-zoo monkey-patch silently no-ops"
+        f"{tag}: QuantState.from_dict missing; " f"unsloth-zoo monkey-patch silently no-ops"
     )
 
 
@@ -194,9 +186,7 @@ def test_bnb_quantstate_from_dict(tag: str):
 def test_bnb_nn_modules_fix_4bit_weight_optional(tag: str):
     """fix_4bit_weight_quant_state_from_module added in newer bnb;
     unsloth uses getattr() with a fallback so older versions are OK."""
-    src = fetch_text(
-        "bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/nn/modules.py"
-    )
+    src = fetch_text("bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/nn/modules.py")
     if src is None:
         pytest.skip(f"{tag}: bitsandbytes/nn/modules.py missing")
     if "fix_4bit_weight_quant_state_from_module" not in src:
@@ -215,8 +205,7 @@ def test_bnb_nn_linear8bitlt(tag: str):
         if src and (has_def(src, "Linear8bitLt", "class") or "Linear8bitLt" in src):
             return
     pytest.fail(
-        f"{tag}: bnb.nn.Linear8bitLt missing in {candidates}; "
-        f"legacy load_in_8bit path breaks"
+        f"{tag}: bnb.nn.Linear8bitLt missing in {candidates}; " f"legacy load_in_8bit path breaks"
     )
 
 
@@ -238,24 +227,18 @@ def test_bnb_optim_optimizer2state(tag: str):
 @pytest.mark.parametrize("tag", BNB_TAGS)
 def test_bnb_utils_pack_unpack(tag: str):
     """4bit state-dict save/load uses these two helpers."""
-    src = fetch_text(
-        "bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/utils.py"
-    )
+    src = fetch_text("bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/utils.py")
     if src is None:
         pytest.skip(f"{tag}: bitsandbytes/utils.py missing")
     for name in ("pack_dict_to_tensor", "unpack_tensor_to_dict"):
-        assert (
-            has_def(src, name, "func") or name in src
-        ), f"{tag}: bnb.utils.{name} missing"
+        assert has_def(src, name, "func") or name in src, f"{tag}: bnb.utils.{name} missing"
 
 
 @pytest.mark.parametrize("tag", BNB_TAGS)
 def test_bnb_cextension_rocm_warp_size_optional(tag: str):
     """ROCM_WARP_SIZE_64 added with AMD ROCm support; pre-ROCm bnb
     builds don't have it. unsloth probes via try/except — informational."""
-    src = fetch_text(
-        "bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/cextension.py"
-    )
+    src = fetch_text("bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/cextension.py")
     if src is None:
         pytest.skip(f"{tag}: cextension.py missing")
     if "ROCM_WARP_SIZE_64" not in src:
@@ -282,15 +265,11 @@ def test_bnb_version_parseable(tag: str):
     """Multiple unsloth code paths read Version(bnb.__version__) for
     feature gating (floors 0.43.3, 0.46.0, 0.48.2.dev0, 0.49.0,
     0.49.2). At least one export mechanism must work."""
-    src = fetch_text(
-        "bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/__init__.py"
-    )
+    src = fetch_text("bitsandbytes-foundation/bitsandbytes", tag, "bitsandbytes/__init__.py")
     if src is None:
         pytest.skip(f"{tag}: bitsandbytes/__init__.py missing")
     has_literal = bool(re.search(r'^__version__\s*=\s*["\']', src, re.MULTILINE))
-    has_subimport = bool(
-        re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE)
-    )
+    has_subimport = bool(re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE))
     has_metadata = bool(
         re.search(
             r"^from\s+importlib\.metadata\s+import\s+(?:[\w,\s]+,\s*)?version",
diff --git a/tests/version_compat/test_peft_pinned_symbols.py b/tests/version_compat/test_peft_pinned_symbols.py
index a1d36c2f15..10fc690d80 100644
--- a/tests/version_compat/test_peft_pinned_symbols.py
+++ b/tests/version_compat/test_peft_pinned_symbols.py
@@ -285,8 +285,7 @@ def test_peft_transformers_weight_conversion_module(tag: str):
         pytest.skip(f"{tag}: transformers_weight_conversion not present (legacy peft)")
     _, src = hit
     assert (
-        has_def(src, "build_peft_weight_mapping", "func")
-        or "build_peft_weight_mapping" in src
+        has_def(src, "build_peft_weight_mapping", "func") or "build_peft_weight_mapping" in src
     ), (
         f"{tag}: build_peft_weight_mapping missing in transformers_weight_conversion; "
         f"unsloth/import_fixes.py:1375-1456 wrap breaks (unsloth#5167)"
@@ -306,14 +305,9 @@ def test_peft_integrations_dequantize_module_weight(tag: str):
         "src/peft/utils/integrations/__init__.py",
     ]
     hit = first_match("huggingface/peft", tag, candidates)
-    assert (
-        hit is not None
-    ), f"{tag}: src/peft/utils/integrations[.py|/__init__.py] both missing"
+    assert hit is not None, f"{tag}: src/peft/utils/integrations[.py|/__init__.py] both missing"
     _, src = hit
-    assert (
-        has_def(src, "dequantize_module_weight", "func")
-        or "dequantize_module_weight" in src
-    ), (
+    assert has_def(src, "dequantize_module_weight", "func") or "dequantize_module_weight" in src, (
         f"{tag}: peft.utils.integrations.dequantize_module_weight missing; "
         f"unsloth-zoo vllm_utils.py:2701, unsloth/_utils.py:1550, "
         f"saving_utils.py:270 ImportError"
@@ -400,9 +394,7 @@ def test_peft_version_parseable(tag: str):
     assert src is not None
     # Same gates as the TRL test: literal / submodule / metadata / VERSION file.
     has_literal = bool(re.search(r'^__version__\s*=\s*["\']', src, re.MULTILINE))
-    has_subimport = bool(
-        re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE)
-    )
+    has_subimport = bool(re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE))
     has_metadata = bool(
         re.search(
             r"^from\s+importlib\.metadata\s+import\s+(?:[\w,\s]+,\s*)?version",
diff --git a/tests/version_compat/test_sentence_transformers_pinned_symbols.py b/tests/version_compat/test_sentence_transformers_pinned_symbols.py
index 2a8c33827c..c0cb1a6d96 100644
--- a/tests/version_compat/test_sentence_transformers_pinned_symbols.py
+++ b/tests/version_compat/test_sentence_transformers_pinned_symbols.py
@@ -50,9 +50,7 @@ ST_TAGS = [
 
 @pytest.mark.parametrize("tag", ST_TAGS)
 def test_st_top_level_exports(tag: str):
-    src = fetch_text(
-        "UKPLab/sentence-transformers", tag, "sentence_transformers/__init__.py"
-    )
+    src = fetch_text("UKPLab/sentence-transformers", tag, "sentence_transformers/__init__.py")
     assert src is not None, f"{tag}: sentence_transformers/__init__.py missing"
     needed = ("SentenceTransformer", "SentenceTransformerTrainer")
     missing = [n for n in needed if n not in src]
@@ -126,15 +124,11 @@ def test_st_models_re_exports(tag: str):
             if src and has_def(src, cls, "class"):
                 break
         else:
-            pytest.fail(
-                f"{tag}: ST 5.4+ layout: class {cls} not found in any of {paths}"
-            )
+            pytest.fail(f"{tag}: ST 5.4+ layout: class {cls} not found in any of {paths}")
 
     # The backward-compat shim must be wired up so user code doing
     # `from sentence_transformers.models import Pooling` keeps working.
-    top = fetch_text(
-        "UKPLab/sentence-transformers", tag, "sentence_transformers/__init__.py"
-    )
+    top = fetch_text("UKPLab/sentence-transformers", tag, "sentence_transformers/__init__.py")
     assert top is not None, f"{tag}: sentence_transformers/__init__.py missing"
     has_shim = bool(
         re.search(r"setup_deprecated_module_imports\s*\(", top)
@@ -192,9 +186,7 @@ def test_st_util_helpers(tag: str):
         "sentence_transformers/util/__init__.py",
     ]
     hit = first_match("UKPLab/sentence-transformers", tag, candidates)
-    assert (
-        hit is not None
-    ), f"{tag}: sentence_transformers/util[.py|/__init__.py] both missing"
+    assert hit is not None, f"{tag}: sentence_transformers/util[.py|/__init__.py] both missing"
     _path, src = hit
     for fn in ("import_from_string", "load_dir_path"):
         defined_here = has_def(src, fn, "func")
diff --git a/tests/version_compat/test_transformers_pinned_symbols.py b/tests/version_compat/test_transformers_pinned_symbols.py
index 2e347dcf69..cebef77c7f 100644
--- a/tests/version_compat/test_transformers_pinned_symbols.py
+++ b/tests/version_compat/test_transformers_pinned_symbols.py
@@ -68,9 +68,7 @@ def test_trainer_class_importable_path(tag: str):
     or src/transformers/trainer/__init__.py."""
     candidates = ["src/transformers/trainer.py", "src/transformers/trainer/__init__.py"]
     hit = first_match("huggingface/transformers", tag, candidates)
-    assert (
-        hit is not None
-    ), f"{tag}: src/transformers/trainer[.py|/__init__.py] both missing"
+    assert hit is not None, f"{tag}: src/transformers/trainer[.py|/__init__.py] both missing"
     _, src = hit
     assert has_def(src, "Trainer", "class"), f"{tag}: class Trainer missing"
 
@@ -165,9 +163,7 @@ def test_modeling_utils_exposes_checkpoint(tag: str):
     """unsloth-zoo#549: transformers 5.2+ uses `transformers.modeling_utils.checkpoint`
     (alias for torch.utils.checkpoint.checkpoint). Patch must replace
     the transformers reference, not just torch's."""
-    src = fetch_text(
-        "huggingface/transformers", tag, "src/transformers/modeling_utils.py"
-    )
+    src = fetch_text("huggingface/transformers", tag, "src/transformers/modeling_utils.py")
     if src is None:
         pytest.skip(f"{tag}: modeling_utils.py missing")
     # Either a direct import or local rebinding.
@@ -190,9 +186,7 @@ def test_modeling_utils_exposes_checkpoint(tag: str):
 def test_pushtohubmixin_create_repo_status(tag: str):
     """unsloth-zoo#393: transformers 5.x removed PushToHubMixin._create_repo.
     On 4.x present, on 5.x absent. Snapshot which side."""
-    src = fetch_text(
-        "huggingface/transformers", tag, "src/transformers/modeling_utils.py"
-    )
+    src = fetch_text("huggingface/transformers", tag, "src/transformers/modeling_utils.py")
     if src is None:
         pytest.skip(f"{tag}: modeling_utils.py missing")
     # Just record the presence; either is OK as long as we know.
@@ -274,9 +268,7 @@ def test_fp8linear_init_param_names(tag: str):
 def test_processing_utils_unpack_importable(tag: str):
     """unsloth-zoo#583/584: `from transformers.processing_utils import Unpack`
     must keep working."""
-    src = fetch_text(
-        "huggingface/transformers", tag, "src/transformers/processing_utils.py"
-    )
+    src = fetch_text("huggingface/transformers", tag, "src/transformers/processing_utils.py")
     if src is None:
         pytest.skip(f"{tag}: processing_utils.py missing")
     has_unpack = bool(re.search(r"^Unpack\b\s*=", src, re.MULTILINE) or "Unpack" in src)
@@ -300,9 +292,7 @@ def test_gemma3_attention_forward_present(tag: str):
     )
     if src is None:
         pytest.skip(f"{tag}: modeling_gemma3.py missing")
-    assert has_def(
-        src, "Gemma3Attention", "class"
-    ), f"{tag}: class Gemma3Attention missing"
+    assert has_def(src, "Gemma3Attention", "class"), f"{tag}: class Gemma3Attention missing"
 
 
 @pytest.mark.parametrize("tag", TRANSFORMERS_TAGS)
@@ -410,9 +400,7 @@ def test_modeling_attn_mask_utils_symbols(tag: str):
     )
     if src is None:
         pytest.skip(f"{tag}: modeling_attn_mask_utils.py missing")
-    assert has_def(
-        src, "AttentionMaskConverter", "class"
-    ), f"{tag}: AttentionMaskConverter missing"
+    assert has_def(src, "AttentionMaskConverter", "class"), f"{tag}: AttentionMaskConverter missing"
     # _prepare_4d_attention_mask_for_sdpa is a function we hard-import.
     assert (
         has_def(src, "_prepare_4d_attention_mask_for_sdpa", "func")
@@ -427,16 +415,12 @@ def test_cache_utils_classes(tag: str):
         pytest.skip(f"{tag}: cache_utils.py missing")
     needed = ("Cache", "DynamicCache")
     for cls in needed:
-        assert has_def(
-            src, cls, "class"
-        ), f"{tag}: transformers.cache_utils.{cls} missing"
+        assert has_def(src, cls, "class"), f"{tag}: transformers.cache_utils.{cls} missing"
 
 
 @pytest.mark.parametrize("tag", TRANSFORMERS_TAGS)
 def test_training_args_parallel_mode_importable(tag: str):
-    src = fetch_text(
-        "huggingface/transformers", tag, "src/transformers/training_args.py"
-    )
+    src = fetch_text("huggingface/transformers", tag, "src/transformers/training_args.py")
     if src is None:
         pytest.skip(f"{tag}: training_args.py missing")
     assert "ParallelMode" in src, (
diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index 815cb5f784..3f6c40f90d 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -288,9 +288,7 @@ def test_trl_version_parseable(tag: str):
     #   4. `__version__ = f.read().strip()` (TRL 0.22.x reads from a
     #      sibling VERSION file)
     has_literal = bool(re.search(r'^__version__\s*=\s*["\']', src, re.MULTILINE))
-    has_subimport = bool(
-        re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE)
-    )
+    has_subimport = bool(re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE))
     has_metadata = bool(
         re.search(
             r"^from\s+importlib\.metadata\s+import\s+(?:[\w,\s]+,\s*)?version",
@@ -346,9 +344,7 @@ def test_trl_sft_trainer_module_internals(tag: str):
         f"{tag}: trl/trainer/sft_trainer.py missing; "
         f"unsloth/tokenizer_utils.py:1538 wildcard import fails"
     )
-    assert has_def(
-        src, "SFTTrainer", "class"
-    ), f"{tag}: class SFTTrainer missing in sft_trainer.py"
+    assert has_def(src, "SFTTrainer", "class"), f"{tag}: class SFTTrainer missing in sft_trainer.py"
     # neftune_post_forward_hook: optional (TRL removed it in some
     # versions); soft-imported in tokenizer_utils.py:1542. Don't fail.
     if "neftune_post_forward_hook" not in src:
@@ -368,9 +364,7 @@ def test_trl_dpo_trainer_module_exists(tag: str):
         f"{tag}: trl/trainer/dpo_trainer.py missing; "
         f"unsloth-zoo/temporary_patches/misc.py:1376 import fails"
     )
-    assert has_def(
-        src, "DPOTrainer", "class"
-    ), f"{tag}: class DPOTrainer missing in dpo_trainer.py"
+    assert has_def(src, "DPOTrainer", "class"), f"{tag}: class DPOTrainer missing in dpo_trainer.py"
 
 
 # -------------------------------------------------------------------------
@@ -392,8 +386,7 @@ def test_trl_constant_length_dataset_optional(tag: str):
     _, src = hit
     if "ConstantLengthDataset" not in src:
         pytest.skip(
-            f"{tag}: ConstantLengthDataset removed; unsloth-zoo soft "
-            f"import handles this"
+            f"{tag}: ConstantLengthDataset removed; unsloth-zoo soft " f"import handles this"
         )
 
 
@@ -414,7 +407,6 @@ def test_trl_models_utils_disable_gradient_checkpointing(tag: str):
         # Strip leading 'v' and parse.
         try:
             from packaging.version import Version
-
             require = Version(tag.lstrip("v")) >= Version("1.0.0")
         except Exception:
             require = False
@@ -625,9 +617,7 @@ def test_trl_dpo_trainer_methods(tag: str):
     src = fetch_text("huggingface/trl", tag, "trl/trainer/dpo_trainer.py")
     assert src is not None
     # The DPO class itself must always exist.
-    assert has_def(
-        src, "DPOTrainer", "class"
-    ), f"{tag}: class DPOTrainer missing in dpo_trainer.py"
+    assert has_def(src, "DPOTrainer", "class"), f"{tag}: class DPOTrainer missing in dpo_trainer.py"
     # Informational only -- pass either way:
     for method in (
         "concatenated_inputs",
diff --git a/tests/version_compat/test_unsloth_zoo_save_merged_pinned_symbols.py b/tests/version_compat/test_unsloth_zoo_save_merged_pinned_symbols.py
index 19faa51119..53f48382ca 100644
--- a/tests/version_compat/test_unsloth_zoo_save_merged_pinned_symbols.py
+++ b/tests/version_compat/test_unsloth_zoo_save_merged_pinned_symbols.py
@@ -68,12 +68,8 @@ def test_zoo_saving_utils_has_moe_merge_state():
 def test_zoo_saving_utils_has_layout_detector():
     src = _fetch_saving_utils()
     _skip_until_pr_647_lands(src)
-    assert (
-        "_detect_moe_lora_layout" in src
-    ), "_detect_moe_lora_layout removed (issue #5410)."
-    assert (
-        '"swapped"' in src and '"standard"' in src
-    ), "one of the layout labels removed."
+    assert "_detect_moe_lora_layout" in src, "_detect_moe_lora_layout removed (issue #5410)."
+    assert '"swapped"' in src and '"standard"' in src, "one of the layout labels removed."
 
 
 def test_zoo_saving_utils_has_num_experts_resolver():
@@ -123,6 +119,4 @@ def test_unsloth_save_pretrained_merged_entry_point_exists():
         pytest.skip(f"{save_py} not present")
     text = save_py.read_text(encoding = "utf-8", errors = "replace")
     assert "save_pretrained_merged" in text, "entry point removed from unsloth/save.py."
-    assert (
-        "merge_and_overwrite_lora" in text
-    ), "no dispatch into unsloth_zoo merge; #647 bypassed."
+    assert "merge_and_overwrite_lora" in text, "no dispatch into unsloth_zoo merge; #647 bypassed."
diff --git a/tests/vllm_compat/test_extended_module_imports.py b/tests/vllm_compat/test_extended_module_imports.py
index a52dc0c657..cbf6a7e301 100644
--- a/tests/vllm_compat/test_extended_module_imports.py
+++ b/tests/vllm_compat/test_extended_module_imports.py
@@ -52,9 +52,7 @@ def _stub_module(name: str, attrs: dict | None = None) -> None:
         return
     m = types.ModuleType(name)
     # Minimal viable spec so importlib treats the stub as a real module.
-    m.__spec__ = importlib.machinery.ModuleSpec(
-        name = name, loader = None, origin = "<test stub>"
-    )
+    m.__spec__ = importlib.machinery.ModuleSpec(name = name, loader = None, origin = "<test stub>")
     for k, v in (attrs or {}).items():
         setattr(m, k, v)
     sys.modules[name] = m
@@ -142,8 +140,7 @@ def test_unsloth_zoo_module_imports_under_spoof(modname: str):
         importlib.import_module(modname)
     except Exception as e:
         pytest.fail(
-            f"{modname} failed to import under CUDA spoof: "
-            f"{type(e).__name__}: {str(e)[:300]}"
+            f"{modname} failed to import under CUDA spoof: " f"{type(e).__name__}: {str(e)[:300]}"
         )
 
 
@@ -209,8 +206,7 @@ def test_unsloth_core_module_imports_under_spoof(modname: str):
         pytest.skip(f"{modname} env issue: {e!s}")
     except Exception as e:
         pytest.fail(
-            f"{modname} failed to import under CUDA spoof: "
-            f"{type(e).__name__}: {str(e)[:300]}"
+            f"{modname} failed to import under CUDA spoof: " f"{type(e).__name__}: {str(e)[:300]}"
         )
 
 
@@ -269,9 +265,7 @@ def test_unsloth_rl_replacements_dispatch_populated():
     funcs = getattr(rl, "RL_FUNCTIONS", None)
     if funcs is None:
         pytest.skip("RL_FUNCTIONS attribute not present (architecture changed; check)")
-    assert isinstance(
-        funcs, dict
-    ), f"RL_FUNCTIONS expected dict, got {type(funcs).__name__}"
+    assert isinstance(funcs, dict), f"RL_FUNCTIONS expected dict, got {type(funcs).__name__}"
     # The trainer types unsloth-zoo dispatches against MUST be keys.
     for key in ("grpo_trainer", "sft_trainer", "dpo_trainer"):
         assert key in funcs, (
@@ -313,9 +307,7 @@ def test_fast_model_from_pretrained_kwargs_under_spoof():
     sys.modules.pop("unsloth", None)
     import unsloth
 
-    cls = getattr(unsloth, "FastLanguageModel", None) or getattr(
-        unsloth, "FastModel", None
-    )
+    cls = getattr(unsloth, "FastLanguageModel", None) or getattr(unsloth, "FastModel", None)
     if cls is None:
         pytest.skip("FastLanguageModel/FastModel not exported")
     fn = getattr(cls, "from_pretrained", None)
diff --git a/tests/vllm_compat/test_vllm_pinned_symbols.py b/tests/vllm_compat/test_vllm_pinned_symbols.py
index dd6a9d0a9b..41b9790680 100644
--- a/tests/vllm_compat/test_vllm_pinned_symbols.py
+++ b/tests/vllm_compat/test_vllm_pinned_symbols.py
@@ -96,13 +96,15 @@ def _fetch_text(repo: str, ref: str, path: str) -> str | None:
         pytest.skip(f"GitHub fetch failed ({e}) for {url}")
 
 
-def _has_def(src: str, name: str, kind: str = "any") -> bool:
+def _has_def(
+    src: str,
+    name: str,
+    kind: str = "any",
+) -> bool:
     """Heuristic AST-equivalent grep for `class Name`, `def name`,
     or `Name = ...` at module scope. We avoid a full ast.parse so a
     single non-importable line (e.g. type: ignore) doesn't false-fail."""
-    if kind in ("any", "class") and re.search(
-        rf"^class\s+{re.escape(name)}\b", src, re.MULTILINE
-    ):
+    if kind in ("any", "class") and re.search(rf"^class\s+{re.escape(name)}\b", src, re.MULTILINE):
         return True
     if kind in ("any", "func") and re.search(
         rf"^(?:async\s+)?def\s+{re.escape(name)}\b", src, re.MULTILINE
@@ -183,11 +185,7 @@ def test_vllm_lora_models_either_path(tag: str):
     # Old path: a single vllm/lora/models.py (or vllm/lora/models/__init__.py).
     old_candidates = ["vllm/lora/models.py", "vllm/lora/models/__init__.py"]
     old_src = next(
-        (
-            s
-            for s in (_fetch_text("vllm-project/vllm", tag, p) for p in old_candidates)
-            if s
-        ),
+        (s for s in (_fetch_text("vllm-project/vllm", tag, p) for p in old_candidates) if s),
         None,
     )
     if old_src is not None:
@@ -229,9 +227,7 @@ def test_vllm_worker_lora_manager_class(tag: str):
     src = _fetch_text("vllm-project/vllm", tag, "vllm/lora/worker_manager.py")
     if src is None:
         # Some vLLM versions split this; check fallback locations.
-        alt = _fetch_text(
-            "vllm-project/vllm", tag, "vllm/v1/worker/lora_model_runner_mixin.py"
-        )
+        alt = _fetch_text("vllm-project/vllm", tag, "vllm/v1/worker/lora_model_runner_mixin.py")
         if alt and ("WorkerLoRAManager" in alt or "LoRAModelRunnerMixin" in alt):
             return
         pytest.fail(
@@ -257,9 +253,7 @@ def test_lora_request_no_removed_kwargs(tag: str):
     assert src is not None
     has_dir = bool(re.search(r"\blora_dir\b", src))
     has_path = bool(re.search(r"\blora_path\b", src))
-    assert (
-        has_dir or has_path
-    ), f"{tag}: vllm.lora.request has neither lora_dir nor lora_path"
+    assert has_dir or has_path, f"{tag}: vllm.lora.request has neither lora_dir nor lora_path"
 
 
 # -------------------------------------------------------------------------
@@ -277,7 +271,6 @@ def _vllm_zoo_local_path() -> str | None:
     importable. None otherwise."""
     try:
         import importlib.util
-
         spec = importlib.util.find_spec("unsloth_zoo.vllm_utils")
         if spec and spec.origin:
             return spec.origin
@@ -294,12 +287,8 @@ def test_unsloth_zoo_standby_guards_present():
     if path is None:
         pytest.skip("unsloth_zoo not installed on runner")
     src = open(path, encoding = "utf-8").read()
-    has_10x_guard = re.search(r"0\.10\.0", src) and re.search(
-        r"standby", src, re.IGNORECASE
-    )
-    has_14x_guard = re.search(r"0\.14\.0", src) and re.search(
-        r"standby", src, re.IGNORECASE
-    )
+    has_10x_guard = re.search(r"0\.10\.0", src) and re.search(r"standby", src, re.IGNORECASE)
+    has_14x_guard = re.search(r"0\.14\.0", src) and re.search(r"standby", src, re.IGNORECASE)
     assert has_10x_guard or has_14x_guard, (
         "unsloth_zoo.vllm_utils dropped the UNSLOTH_VLLM_STANDBY "
         "version-gate against vLLM 0.10.x / 0.14.x; that re-introduces the "
diff --git a/unsloth-cli.py b/unsloth-cli.py
index 612da11eb2..4ebc36164f 100644
--- a/unsloth-cli.py
+++ b/unsloth-cli.py
@@ -102,7 +102,6 @@ def run(args):
 
     def load_dataset_smart(args):
         from transformers.utils import strtobool
-
         if args.raw_text_file:
             # Use raw text loader
             loader = RawTextDataLoader(tokenizer, args.chunk_size, args.stride)
@@ -113,12 +112,9 @@ def run(args):
             dataset = loader.load_from_file(args.dataset)
         else:
             # Check for modelscope usage
-            use_modelscope = strtobool(
-                os.environ.get("UNSLOTH_USE_MODELSCOPE", "False")
-            )
+            use_modelscope = strtobool(os.environ.get("UNSLOTH_USE_MODELSCOPE", "False"))
             if use_modelscope:
                 from modelscope import MsDataset
-
                 dataset = MsDataset.load(args.dataset, split = "train")
             else:
                 # Existing HuggingFace dataset logic
@@ -171,9 +167,7 @@ def run(args):
         if args.save_gguf:
             if isinstance(args.quantization, list):
                 for quantization_method in args.quantization:
-                    print(
-                        f"Saving model with quantization method: {quantization_method}"
-                    )
+                    print(f"Saving model with quantization method: {quantization_method}")
                     model.save_pretrained_gguf(
                         args.save_path,
                         tokenizer,
@@ -207,9 +201,7 @@ def run(args):
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
-        description = "🦥 Fine-tune your llm faster using unsloth!"
-    )
+    parser = argparse.ArgumentParser(description = "🦥 Fine-tune your llm faster using unsloth!")
 
     model_group = parser.add_argument_group("🤖 Model Options")
     model_group.add_argument(
@@ -459,15 +451,11 @@ if __name__ == "__main__":
         help = "Token for pushing the model to Hugging Face hub",
     )
 
-    parser.add_argument(
-        "--raw_text_file", type = str, help = "Path to raw text file for training"
-    )
+    parser.add_argument("--raw_text_file", type = str, help = "Path to raw text file for training")
     parser.add_argument(
         "--chunk_size", type = int, default = 2048, help = "Size of text chunks for training"
     )
-    parser.add_argument(
-        "--stride", type = int, default = 512, help = "Overlap between chunks"
-    )
+    parser.add_argument("--stride", type = int, default = 512, help = "Overlap between chunks")
 
     args = parser.parse_args()
     run(args)
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index fb11f1f649..b723611c5a 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -27,7 +27,6 @@ os.environ["UNSLOTH_IS_PRESENT"] = "1"
 # errors="replace" guarantees we can never crash on an unencodable glyph.
 if platform.system() == "Windows":
     import sys as _sys
-
     for _name in ("stdout", "stderr"):
         _s = getattr(_sys, _name, None)
         try:
@@ -89,9 +88,7 @@ if _IS_MLX:
     from pathlib import Path as _Path
 
     _raw_text_path = _Path(__file__).resolve().parent / "dataprep" / "raw_text.py"
-    _raw_text_spec = importlib.util.spec_from_file_location(
-        "unsloth._mlx_raw_text", _raw_text_path
-    )
+    _raw_text_spec = importlib.util.spec_from_file_location("unsloth._mlx_raw_text", _raw_text_path)
     if _raw_text_spec is None or _raw_text_spec.loader is None:
         raise ImportError("Unsloth: could not load MLX raw_text dataprep helpers.")
     _raw_text = importlib.util.module_from_spec(_raw_text_spec)
@@ -145,7 +142,6 @@ if _IS_MLX:
     def is_bfloat16_supported():
         try:
             import mlx.core as mx
-
             name = mx.device_info().get("device_name", "") or ""
             return not name.startswith(("Apple M1", "Apple M2"))
         except Exception:
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 2309ab3366..3a84b8b012 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -268,9 +268,7 @@ if DEVICE_TYPE == "cuda":
             elif os.path.exists("/usr/local"):
                 # Sometimes bitsandbytes cannot be linked properly in Runpod for example
                 possible_cudas = (
-                    subprocess.check_output(["ls", "-al", "/usr/local"])
-                    .decode("utf-8")
-                    .split("\n")
+                    subprocess.check_output(["ls", "-al", "/usr/local"]).decode("utf-8").split("\n")
                 )
                 find_cuda = re.compile(r"[\s](cuda\-[\d\.]{2,})$")
                 possible_cudas = [find_cuda.search(x) for x in possible_cudas]
@@ -301,9 +299,7 @@ if DEVICE_TYPE == "cuda":
                         pass
                 else:
                     from triton.common.build import libcuda_dirs
-                cdequantize_blockwise_fp32 = (
-                    bnb.functional.lib.cdequantize_blockwise_fp32
-                )
+                cdequantize_blockwise_fp32 = bnb.functional.lib.cdequantize_blockwise_fp32
                 libcuda_dirs()
             except:
                 warnings.warn(
diff --git a/unsloth/dataprep/raw_text.py b/unsloth/dataprep/raw_text.py
index 1e2221dc08..3abb6df6cd 100644
--- a/unsloth/dataprep/raw_text.py
+++ b/unsloth/dataprep/raw_text.py
@@ -35,13 +35,17 @@ SUPPORTED_FORMATS = {
 
 
 class RawTextDataLoader:
-    def __init__(self, tokenizer, chunk_size = 2048, stride = 512, return_tokenized = True):
+    def __init__(
+        self,
+        tokenizer,
+        chunk_size = 2048,
+        stride = 512,
+        return_tokenized = True,
+    ):
         if chunk_size <= 0:
             raise ValueError(f"chunk_size must be positive, got {chunk_size}")
         if stride >= chunk_size:
-            raise ValueError(
-                f"stride ({stride}) must be smaller than chunk_size ({chunk_size})"
-            )
+            raise ValueError(f"stride ({stride}) must be smaller than chunk_size ({chunk_size})")
         self.tokenizer = tokenizer
         self.chunk_size = chunk_size
         self.stride = stride
@@ -52,7 +56,11 @@ class RawTextDataLoader:
         extension = Path(file_path).suffix.lower()
         return SUPPORTED_FORMATS.get(extension, "plain_text")
 
-    def load_from_file(self, file_path, return_tokenized = None):
+    def load_from_file(
+        self,
+        file_path,
+        return_tokenized = None,
+    ):
         """Load raw text and convert to dataset"""
         if return_tokenized is None:
             return_tokenized = self.return_tokenized
@@ -60,12 +68,14 @@ class RawTextDataLoader:
         text_content = self._read_file_by_format(file_path, file_format)
         if not text_content or not text_content.strip():
             raise ValueError(f"File '{file_path}' is empty or contains only whitespace")
-        chunks = self.smart_chunk_text(
-            text_content, self.chunk_size, self.stride, return_tokenized
-        )
+        chunks = self.smart_chunk_text(text_content, self.chunk_size, self.stride, return_tokenized)
         return self.create_causal_dataset(chunks)
 
-    def load_from_files(self, file_paths, return_tokenized = None):
+    def load_from_files(
+        self,
+        file_paths,
+        return_tokenized = None,
+    ):
         """Load multiple text files"""
         if return_tokenized is None:
             return_tokenized = self.return_tokenized
@@ -79,13 +89,15 @@ class RawTextDataLoader:
             all_chunks.extend(chunks)
         return self.create_causal_dataset(all_chunks)
 
-    def chunk_text(self, text, return_tokenized = None):
+    def chunk_text(
+        self,
+        text,
+        return_tokenized = None,
+    ):
         """Split text into overlapping chunks"""
         if return_tokenized is None:
             return_tokenized = self.return_tokenized
-        return self.smart_chunk_text(
-            text, self.chunk_size, self.stride, return_tokenized
-        )
+        return self.smart_chunk_text(text, self.chunk_size, self.stride, return_tokenized)
 
     def create_causal_dataset(self, chunks):
         """Create dataset for causal language modeling"""
@@ -107,7 +119,13 @@ class RawTextDataLoader:
             # If chunks are text strings (backward compatibility)
             return Dataset.from_dict({"text": chunks})
 
-    def smart_chunk_text(self, text, chunk_size, stride, return_tokenized = True):
+    def smart_chunk_text(
+        self,
+        text,
+        chunk_size,
+        stride,
+        return_tokenized = True,
+    ):
         """
         Intelligent chunking that:
         1. Respects sentence/paragraph boundaries
@@ -134,9 +152,7 @@ class RawTextDataLoader:
                 # Add EOS token to the tokens if available
                 eos_token_id = getattr(self.tokenizer, "eos_token_id", None)
                 if eos_token_id is not None:
-                    tokens = (
-                        tokens.tolist() if hasattr(tokens, "tolist") else list(tokens)
-                    )
+                    tokens = tokens.tolist() if hasattr(tokens, "tolist") else list(tokens)
                     tokens.append(eos_token_id)
 
                 # Create attention mask
@@ -159,9 +175,7 @@ class RawTextDataLoader:
             if return_tokenized:
                 # Convert to list if it's a tensor
                 chunk_tokens_list = (
-                    chunk_tokens.tolist()
-                    if hasattr(chunk_tokens, "tolist")
-                    else list(chunk_tokens)
+                    chunk_tokens.tolist() if hasattr(chunk_tokens, "tolist") else list(chunk_tokens)
                 )
 
                 # Add EOS token if it's the last chunk or chunk is complete
@@ -173,20 +187,14 @@ class RawTextDataLoader:
                 # Create attention mask (all tokens are attended to)
                 attention_mask = [1] * len(chunk_tokens_list)
 
-                chunks.append(
-                    {"input_ids": chunk_tokens_list, "attention_mask": attention_mask}
-                )
+                chunks.append({"input_ids": chunk_tokens_list, "attention_mask": attention_mask})
             else:
                 # Decode back to text (backward compatibility)
-                chunk_text = self.tokenizer.decode(
-                    chunk_tokens, skip_special_tokens = True
-                )
+                chunk_text = self.tokenizer.decode(chunk_tokens, skip_special_tokens = True)
 
                 # Add EOS token if it's the last chunk or chunk is complete
                 if end_idx == len(tokens) or len(chunk_tokens) == chunk_size:
-                    eos_token = (
-                        self.tokenizer.eos_token if self.tokenizer.eos_token else ""
-                    )
+                    eos_token = self.tokenizer.eos_token if self.tokenizer.eos_token else ""
                     chunk_text += eos_token
 
                 chunks.append(chunk_text)
@@ -262,18 +270,10 @@ class TextPreprocessor:
 
     def add_structure_tokens(self, text):
         """Add special tokens for structure (chapters, sections)"""
-        text = re.sub(
-            r"^# (.+)$", r"<|chapter|>\1<|/chapter|>", text, flags = re.MULTILINE
-        )
-        text = re.sub(
-            r"^## (.+)$", r"<|section|>\1<|/section|>", text, flags = re.MULTILINE
-        )
-        text = re.sub(
-            r"^### (.+)$", r"<|subsection|>\1<|/subsection|>", text, flags = re.MULTILINE
-        )
-        text = re.sub(
-            r"```(\w*)\n(.*?)\n```", r"<|code|\1|>\2<|/code|>", text, flags = re.DOTALL
-        )
+        text = re.sub(r"^# (.+)$", r"<|chapter|>\1<|/chapter|>", text, flags = re.MULTILINE)
+        text = re.sub(r"^## (.+)$", r"<|section|>\1<|/section|>", text, flags = re.MULTILINE)
+        text = re.sub(r"^### (.+)$", r"<|subsection|>\1<|/subsection|>", text, flags = re.MULTILINE)
+        text = re.sub(r"```(\w*)\n(.*?)\n```", r"<|code|\1|>\2<|/code|>", text, flags = re.DOTALL)
         return text
 
     def validate_dataset(self, dataset):
@@ -326,23 +326,17 @@ class TextPreprocessor:
         # Calculate average length
         if text_lengths:
             stats["avg_length"] = sum(text_lengths) / len(text_lengths)
-            stats["min_length"] = (
-                stats["min_length"] if stats["min_length"] != float("inf") else 0
-            )
+            stats["min_length"] = stats["min_length"] if stats["min_length"] != float("inf") else 0
 
         # Generate warnings
         if stats["empty_samples"] > 0:
             stats["warnings"].append(f"Found {stats['empty_samples']} empty samples")
 
         if stats["repeated_content"] > 0:
-            stats["warnings"].append(
-                f"Found {stats['repeated_content']} repeated samples"
-            )
+            stats["warnings"].append(f"Found {stats['repeated_content']} repeated samples")
 
         if stats["encoding_issues"] > 0:
-            stats["warnings"].append(
-                f"Found {stats['encoding_issues']} encoding issues"
-            )
+            stats["warnings"].append(f"Found {stats['encoding_issues']} encoding issues")
 
         if stats["min_length"] < 10:
             stats["warnings"].append("Some samples are very short (< 10 characters)")
diff --git a/unsloth/dataprep/synthetic.py b/unsloth/dataprep/synthetic.py
index 1be83c3bb9..9d9143254b 100644
--- a/unsloth/dataprep/synthetic.py
+++ b/unsloth/dataprep/synthetic.py
@@ -46,7 +46,6 @@ def _load_vllm_utils():
         patch_vllm,
         delete_vllm,
     )
-
     return load_vllm, patch_vllm, delete_vllm
 
 
@@ -355,9 +354,7 @@ class SyntheticDataKit:
             vllm_process.wait(timeout = 10)
             print("Server terminated gracefully.")
         except subprocess.TimeoutExpired:
-            print(
-                "Server did not terminate gracefully after 10 seconds. Forcing kill..."
-            )
+            print("Server did not terminate gracefully after 10 seconds. Forcing kill...")
             vllm_process.kill()
             vllm_process.wait()
             print("Server killed forcefully.")
@@ -394,9 +391,7 @@ class SyntheticDataKit:
         assert os.path.exists(filename)
         assert hasattr(self, "tokenizer")
         if not hasattr(self, "max_seq_length"):
-            raise RuntimeError(
-                "Please use SynthetidDataKit.from_pretrained(...) first!"
-            )
+            raise RuntimeError("Please use SynthetidDataKit.from_pretrained(...) first!")
         if not hasattr(self, "overlap") or not hasattr(self, "max_generation_tokens"):
             raise RuntimeError("Please use prepare_qa_generation first!")
 
@@ -413,9 +408,7 @@ class SyntheticDataKit:
         # Get left and right boundaries
         length = len(input_ids)
         n_chunks = int(np.ceil(length / (max_tokens - self.overlap)))
-        boundaries = np.ceil(np.linspace(0, length - self.overlap, n_chunks)).astype(
-            int
-        )
+        boundaries = np.ceil(np.linspace(0, length - self.overlap, n_chunks)).astype(int)
         boundaries = np.stack((boundaries[:-1], (boundaries + self.overlap)[1:])).T
         boundaries = np.minimum(boundaries, length).tolist()
 
@@ -461,9 +454,7 @@ class SyntheticDataKit:
             .replace("{model_name}", str(self.model_name))
             .replace("{temperature}", str(temperature))
             .replace("{top_p}", str(top_p))
-            .replace(
-                "{chunk_size}", str(self.max_seq_length - max_generation_tokens * 2 - 2)
-            )
+            .replace("{chunk_size}", str(self.max_seq_length - max_generation_tokens * 2 - 2))
             .replace("{overlap}", str(overlap))
             .replace("{max_tokens}", str(max_generation_tokens))
             .replace("{default_num_pairs}", str(default_num_pairs))
diff --git a/unsloth/device_type.py b/unsloth/device_type.py
index f7a330594b..170d5541f4 100644
--- a/unsloth/device_type.py
+++ b/unsloth/device_type.py
@@ -70,9 +70,7 @@ def get_device_type():
     # Check torch.accelerator
     if hasattr(torch, "accelerator"):
         if not torch.accelerator.is_available():
-            raise NotImplementedError(
-                "Unsloth cannot find any torch accelerator? You need a GPU."
-            )
+            raise NotImplementedError("Unsloth cannot find any torch accelerator? You need a GPU.")
         accelerator = str(torch.accelerator.current_accelerator())
         if accelerator in ("cuda", "xpu", "hip"):
             raise RuntimeError(
@@ -80,9 +78,7 @@ def get_device_type():
                 f"But `torch.accelerator.current_accelerator()` works with it being = `{accelerator}`\n"
                 f"Please reinstall torch - it's most likely broken :("
             )
-    raise NotImplementedError(
-        "Unsloth currently only works on NVIDIA, AMD and Intel GPUs."
-    )
+    raise NotImplementedError("Unsloth currently only works on NVIDIA, AMD and Intel GPUs.")
 
 
 DEVICE_TYPE: str = get_device_type()
@@ -141,7 +137,6 @@ if DEVICE_TYPE == "hip":
             try:
                 # Pre-quantized bitsandbytes models use blocksize 64, so we need to check the GPU
                 from bitsandbytes.cextension import ROCM_WARP_SIZE_64
-
                 ALLOW_PREQUANTIZED_MODELS = not ROCM_WARP_SIZE_64
             except Exception as e:
                 print(
@@ -153,8 +148,5 @@ if DEVICE_TYPE == "hip":
                 ALLOW_BITSANDBYTES = False
         elif ALLOW_BITSANDBYTES:
             from bitsandbytes.nn.modules import Params4bit
-
-            if "blocksize = 64 if not HIP_ENVIRONMENT else 128" in inspect.getsource(
-                Params4bit
-            ):
+            if "blocksize = 64 if not HIP_ENVIRONMENT else 128" in inspect.getsource(Params4bit):
                 ALLOW_PREQUANTIZED_MODELS = False
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 182355640a..45b127a067 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -35,14 +35,10 @@ UNSLOTH_ENABLE_LOGGING = os.environ.get("UNSLOTH_ENABLE_LOGGING", "0") in (
 )
 logger = logging.getLogger(__name__)
 if UNSLOTH_ENABLE_LOGGING:
-    logging.basicConfig(
-        level = logging.INFO, format = "[%(name)s|%(levelname)s]%(message)s"
-    )
+    logging.basicConfig(level = logging.INFO, format = "[%(name)s|%(levelname)s]%(message)s")
     logger.setLevel(logging.INFO)
 else:
-    logging.basicConfig(
-        level = logging.WARNING, format = "[%(name)s|%(levelname)s]%(message)s"
-    )
+    logging.basicConfig(level = logging.WARNING, format = "[%(name)s|%(levelname)s]%(message)s")
     logger.setLevel(logging.WARNING)
 
 _AMDGPU_IDS_MISSING_TEXT = "amdgpu.ids: No such file or directory"
@@ -60,7 +56,6 @@ def Version(version):
         return TrueVersion(new_version)
     except:
         from inspect import getframeinfo, stack
-
         caller = getframeinfo(stack()[1][0])
         raise RuntimeError(
             f"Unsloth: Could not get version for `{version}`\n"
@@ -130,7 +125,6 @@ def suppress_cuda_printf():
     finally:
         try:
             import torch
-
             if torch.cuda.is_available():
                 torch.cuda.synchronize()
         except Exception:
@@ -164,15 +158,11 @@ if not UNSLOTH_ENABLE_LOGGING:
     # Also filter torchao print to stderr about cpp extensions
     sys.stderr.add_filter("Skipping import of cpp extensions")
     # SyntaxWarning: invalid escape sequence '\.'
-    warnings.filterwarnings(
-        "ignore", message = "invalid escape sequence", category = SyntaxWarning
-    )
+    warnings.filterwarnings("ignore", message = "invalid escape sequence", category = SyntaxWarning)
     # PYTORCH_CUDA_ALLOC_CONF is deprecated warning from torch
     warnings.filterwarnings("ignore", message = "PYTORCH_CUDA_ALLOC_CONF is deprecated")
     # TF32 precision deprecation warning from torch
-    warnings.filterwarnings(
-        "ignore", message = "Please use the new API settings to control TF32"
-    )
+    warnings.filterwarnings("ignore", message = "Please use the new API settings to control TF32")
     # Deprecation warnings from torchao
     warnings.filterwarnings("ignore", message = "`int4_weight_only` is deprecated")
     warnings.filterwarnings("ignore", message = "`int8_weight_only` is deprecated")
@@ -211,12 +201,8 @@ if not UNSLOTH_ENABLE_LOGGING:
     )
 
     # Resource warnings from internal socket/file operations
-    warnings.filterwarnings(
-        "ignore", message = r"unclosed.*socket", category = ResourceWarning
-    )
-    warnings.filterwarnings(
-        "ignore", message = r"unclosed file.*dev/null", category = ResourceWarning
-    )
+    warnings.filterwarnings("ignore", message = r"unclosed.*socket", category = ResourceWarning)
+    warnings.filterwarnings("ignore", message = r"unclosed file.*dev/null", category = ResourceWarning)
 
     # torch 2.9+ pin_memory/is_pinned device arg deprecation
     warnings.filterwarnings(
@@ -282,18 +268,14 @@ def fix_message_factory_issue():
             google.protobuf.message_factory.MessageFactory = MessageFactory
         elif (
             hasattr(google.protobuf.message_factory, "MessageFactory")
-            and not hasattr(
-                google.protobuf.message_factory.MessageFactory, "GetPrototype"
-            )
+            and not hasattr(google.protobuf.message_factory.MessageFactory, "GetPrototype")
             and not hasattr(google.protobuf.message_factory, "GetMessageClass")
         ):
             google.protobuf.message_factory.MessageFactory = MessageFactory
             logger.info("Unsloth: Patching protobuf.MessageFactory as it doesn't exist")
         elif (
             hasattr(google.protobuf.message_factory, "MessageFactory")
-            and not hasattr(
-                google.protobuf.message_factory.MessageFactory, "GetPrototype"
-            )
+            and not hasattr(google.protobuf.message_factory.MessageFactory, "GetPrototype")
             and hasattr(google.protobuf.message_factory, "GetMessageClass")
         ):
             GetMessageClass = google.protobuf.message_factory.GetMessageClass
@@ -334,9 +316,7 @@ def fix_xformers_performance_issue():
                         f.seek(0)
                         f.write(text)
                         f.truncate()
-                        logger.info(
-                            "Unsloth: Patching Xformers to fix some performance issues."
-                        )
+                        logger.info("Unsloth: Patching Xformers to fix some performance issues.")
         except Exception as e:
             logger.info(f"Unsloth: Failed patching Xformers with error = {str(e)}")
 
@@ -359,7 +339,6 @@ def patch_vllm_for_notebooks():
     if ipython is None:
         try:
             import builtins
-
             _get_ipython = getattr(builtins, "get_ipython", None)
             if callable(_get_ipython):
                 ipython = _get_ipython()
@@ -371,9 +350,7 @@ def patch_vllm_for_notebooks():
 
     try:
         shell = ipython.__class__.__name__
-        is_notebook = shell == "ZMQInteractiveShell" or "google.colab" in str(
-            type(ipython)
-        )
+        is_notebook = shell == "ZMQInteractiveShell" or "google.colab" in str(type(ipython))
     except Exception:
         return
 
@@ -446,10 +423,7 @@ def fix_vllm_aimv2_issue():
 def fix_vllm_guided_decoding_params():
     def _maybe_raise_vllm_transformers_mismatch(error):
         error_text = str(error)
-        if (
-            "ALLOWED_LAYER_TYPES" in error_text
-            or "transformers.configuration_utils" in error_text
-        ):
+        if "ALLOWED_LAYER_TYPES" in error_text or "transformers.configuration_utils" in error_text:
             try:
                 vllm_version = importlib_version("vllm")
             except Exception:
@@ -485,9 +459,7 @@ def fix_vllm_guided_decoding_params():
             vllm.sampling_params, "StructuredOutputsParams"
         ):
             raise
-        vllm.sampling_params.GuidedDecodingParams = (
-            vllm.sampling_params.StructuredOutputsParams
-        )
+        vllm.sampling_params.GuidedDecodingParams = vllm.sampling_params.StructuredOutputsParams
 
 
 def fix_trl_vllm_ascend():
@@ -520,7 +492,6 @@ def ignore_logger_messages():
     # Ignore Environment variable `HF_TOKEN` is set
     try:
         from huggingface_hub._login import logger as huggingface_hub_logger
-
         huggingface_hub_logger.addFilter(HideLoggingMessage("`HF_TOKEN`"))
         del huggingface_hub_logger
     except:
@@ -555,7 +526,6 @@ def patch_ipykernel_hf_xet():
             "https://github.com/huggingface/xet-core/issues/526"
         )
         from huggingface_hub.utils import disable_progress_bars
-
         disable_progress_bars()
 
 
@@ -577,9 +547,7 @@ def patch_datasets():
         return
 
     datasets_version = Version(importlib_version("datasets"))
-    if (datasets_version <= Version("4.5.0")) and (
-        datasets_version >= Version("4.4.0")
-    ):
+    if (datasets_version <= Version("4.5.0")) and (datasets_version >= Version("4.4.0")):
         raise NotImplementedError(
             f"#### Unsloth: Using `datasets = {str(datasets_version)}` will cause recursion errors.\n"
             "Please downgrade datasets to `datasets==4.3.0"
@@ -635,8 +603,7 @@ def patch_enable_input_require_grads():
 
         for module in self.modules():
             if not (
-                isinstance(module, PreTrainedModel)
-                and hasattr(module, "get_input_embeddings")
+                isinstance(module, PreTrainedModel) and hasattr(module, "get_input_embeddings")
             ):
                 continue
 
@@ -655,9 +622,7 @@ def patch_enable_input_require_grads():
                 continue
 
             seen_modules.add(embedding_id)
-            hooks.append(
-                input_embeddings.register_forward_hook(make_inputs_require_grads)
-            )
+            hooks.append(input_embeddings.register_forward_hook(make_inputs_require_grads))
 
         self._require_grads_hooks = hooks
         if hooks:
@@ -665,9 +630,7 @@ def patch_enable_input_require_grads():
 
     PreTrainedModel.enable_input_require_grads = _patched_enable_input_require_grads
 
-    logger.info(
-        "Unsloth: Patched enable_input_require_grads for vision model compatibility"
-    )
+    logger.info("Unsloth: Patched enable_input_require_grads for vision model compatibility")
 
 
 def _is_custom_torch_build(raw_version_str):
@@ -832,9 +795,7 @@ def fix_openenv_no_vllm():
                 f.seek(0)
                 f.write(text)
                 f.truncate()
-                logger.info(
-                    "Unsloth: Patching TRL OpenEnv to fix SamplingParams not defined"
-                )
+                logger.info("Unsloth: Patching TRL OpenEnv to fix SamplingParams not defined")
     except Exception as e:
         logger.info(f"Unsloth: Failed patching TRL OpenEnv with error = {str(e)}")
 
@@ -913,11 +874,8 @@ def fix_diffusers_warnings():
 def fix_huggingface_hub():
     # huggingface_hub.is_offline_mode got removed, so add it back
     import huggingface_hub
-
     if not hasattr(huggingface_hub, "is_offline_mode"):
-        huggingface_hub.is_offline_mode = (
-            lambda: huggingface_hub.constants.HF_HUB_OFFLINE
-        )
+        huggingface_hub.is_offline_mode = lambda: huggingface_hub.constants.HF_HUB_OFFLINE
 
 
 def fix_triton_compiled_kernel_missing_attrs():
@@ -999,9 +957,7 @@ def patch_trunc_normal_precision_issue():
         if generator is None:
             return original_trunc_normal(target, mean = mean, std = std, a = a, b = b)
         try:
-            return original_trunc_normal(
-                target, mean = mean, std = std, a = a, b = b, generator = generator
-            )
+            return original_trunc_normal(target, mean = mean, std = std, a = a, b = b, generator = generator)
         except TypeError as exc:
             # Older torch versions may not accept a generator keyword argument.
             msg = str(exc).lower()
@@ -1178,9 +1134,7 @@ def fix_vllm_pdl_blackwell():
             )
             return
     except Exception as e:
-        logger.debug(
-            f"Unsloth: vLLM version check failed ({e}), applying PDL workaround."
-        )
+        logger.debug(f"Unsloth: vLLM version check failed ({e}), applying PDL workaround.")
 
     # Apply the PDL fix
     os.environ["TRITON_DISABLE_PDL"] = "1"
@@ -1265,11 +1219,8 @@ def patch_openspiel_env_async():
 
         try:
             import nest_asyncio
-
             nest_asyncio.apply()
-            logger.info(
-                "Unsloth: Applied nest_asyncio for OpenEnv EnvClient async compatibility"
-            )
+            logger.info("Unsloth: Applied nest_asyncio for OpenEnv EnvClient async compatibility")
         except ImportError:
             logger.info(
                 "Unsloth: nest_asyncio not installed, OpenEnv async methods may need manual wrapping"
@@ -1282,7 +1233,6 @@ def patch_torchcodec_audio_decoder():
     """Call unsloth_zoo's AudioDecoder patch."""
     try:
         from unsloth_zoo.dataset_utils import patch_torchcodec_audio_decoder as _patch
-
         _patch()
     except (ImportError, AttributeError, RuntimeError):
         pass
@@ -1298,7 +1248,6 @@ def disable_torchcodec_if_broken():
     """
     try:
         import importlib.util
-
         if importlib.util.find_spec("torchcodec") is None:
             return  # absent or already disabled
 
@@ -1327,7 +1276,6 @@ def disable_torchcodec_if_broken():
         # datasets >= 4.0: own flag gating audio/video/features/formatters.
         try:
             import datasets.config as datasets_config
-
             if hasattr(datasets_config, "TORCHCODEC_AVAILABLE"):
                 datasets_config.TORCHCODEC_AVAILABLE = False
         except ImportError:
@@ -1377,7 +1325,6 @@ def disable_broken_wandb():
         # Patch transformers' is_wandb_available (used by most trl trainers)
         try:
             import transformers.integrations.integration_utils as tf_integration
-
             tf_integration.is_wandb_available = _wandb_false
         except (ImportError, AttributeError):
             pass
@@ -1387,13 +1334,11 @@ def disable_broken_wandb():
         # accelerate.utils, not accelerate.utils.imports.
         try:
             import accelerate.utils.imports as acc_imports
-
             acc_imports.is_wandb_available = _wandb_false
         except (ImportError, AttributeError):
             pass
         try:
             import accelerate.utils as acc_utils
-
             acc_utils.is_wandb_available = _wandb_false
         except (ImportError, AttributeError):
             pass
@@ -1500,7 +1445,12 @@ def _install_transformers_core_model_loading_stub():
             raise NotImplementedError
 
     class Concatenate(ConversionOps):
-        def __init__(self, dim = 0, *args, **kwargs):
+        def __init__(
+            self,
+            dim = 0,
+            *args,
+            **kwargs,
+        ):
             self.dim = dim
 
     class MergeModulelist(ConversionOps):
@@ -1508,7 +1458,13 @@ def _install_transformers_core_model_loading_stub():
             pass
 
     class Transpose(ConversionOps):
-        def __init__(self, dim0 = 0, dim1 = 1, *args, **kwargs):
+        def __init__(
+            self,
+            dim0 = 0,
+            dim1 = 1,
+            *args,
+            **kwargs,
+        ):
             self.dim0 = dim0
             self.dim1 = dim1
 
@@ -1660,9 +1616,7 @@ def patch_peft_weight_converter_compatibility():
 
             original_init = conversion_cls.__init__
             params = inspect.signature(original_init).parameters
-            supports_kwargs = any(
-                p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values()
-            )
+            supports_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
             supports_distributed = "distributed_operation" in params
             supports_quantization = "quantization_operation" in params
             if supports_kwargs or (supports_distributed and supports_quantization):
@@ -1678,13 +1632,9 @@ def patch_peft_weight_converter_compatibility():
             ):
                 unsupported = {}
                 if not __supports_distributed and "distributed_operation" in kwargs:
-                    unsupported["distributed_operation"] = kwargs.pop(
-                        "distributed_operation"
-                    )
+                    unsupported["distributed_operation"] = kwargs.pop("distributed_operation")
                 if not __supports_quantization and "quantization_operation" in kwargs:
-                    unsupported["quantization_operation"] = kwargs.pop(
-                        "quantization_operation"
-                    )
+                    unsupported["quantization_operation"] = kwargs.pop("quantization_operation")
                 result = __original_init(self, *args, **kwargs)
                 for name, value in unsupported.items():
                     if hasattr(self, name):
@@ -1756,9 +1706,7 @@ def _is_rocm_torch_build() -> bool:
     try:
         torch_version_raw = str(importlib_version("torch")).lower()
         if "rocm" in torch_version_raw:
-            _log_rocm_detection(
-                "Unsloth: ROCm detection matched torch version tag (+rocm)."
-            )
+            _log_rocm_detection("Unsloth: ROCm detection matched torch version tag (+rocm).")
             return True
     except Exception:
         pass
@@ -1767,18 +1715,14 @@ def _is_rocm_torch_build() -> bool:
     for key in _ROCM_ENV_HINT_KEYS:
         value = os.environ.get(key, "")
         if isinstance(value, str) and value.strip():
-            _log_rocm_detection(
-                f"Unsloth: ROCm detection matched environment key `{key}`."
-            )
+            _log_rocm_detection(f"Unsloth: ROCm detection matched environment key `{key}`.")
             return True
 
     # Filesystem / driver hints for ROCm stacks.
     for path in _ROCM_PATH_HINTS:
         try:
             if path.exists():
-                _log_rocm_detection(
-                    f"Unsloth: ROCm detection matched filesystem hint `{path}`."
-                )
+                _log_rocm_detection(f"Unsloth: ROCm detection matched filesystem hint `{path}`.")
                 return True
         except Exception:
             continue
@@ -1843,9 +1787,7 @@ def configure_amdgpu_asic_id_table_path():
             if candidate.is_file():
                 os.environ[_AMDGPU_ASIC_ID_TABLE_PATH_ENV] = str(candidate)
                 if UNSLOTH_ENABLE_LOGGING:
-                    logger.info(
-                        f"Unsloth: Set {_AMDGPU_ASIC_ID_TABLE_PATH_ENV}={candidate}"
-                    )
+                    logger.info(f"Unsloth: Set {_AMDGPU_ASIC_ID_TABLE_PATH_ENV}={candidate}")
                 return str(candidate)
         except Exception:
             continue
@@ -1886,9 +1828,7 @@ def _is_broken_causal_conv1d_error(error) -> bool:
             or ("causal_conv1d" in message and "undefined symbol" in message)
         ):
             return True
-        current = getattr(current, "__cause__", None) or getattr(
-            current, "__context__", None
-        )
+        current = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
     return False
 
 
@@ -1913,9 +1853,7 @@ def _is_broken_vllm_error(error) -> bool:
             "libcudart" in message or "libcublas" in message or "libnvrtc" in message
         ) and "cannot open shared object file" in message:
             return True
-        current = getattr(current, "__cause__", None) or getattr(
-            current, "__context__", None
-        )
+        current = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
     return False
 
 
@@ -1934,9 +1872,7 @@ def _get_vllm_cuda_mismatch_message(error):
         if match:
             wanted_cuda = match.group(1)
             break
-        current = getattr(current, "__cause__", None) or getattr(
-            current, "__context__", None
-        )
+        current = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
     if wanted_cuda is None:
         return None
 
@@ -1945,7 +1881,6 @@ def _get_vllm_cuda_mismatch_message(error):
     system_cuda_tag = None  # For wheel URL, e.g. "130"
     try:
         import torch
-
         cuda_version = torch.version.cuda  # e.g. "13.0" or "12.8"
         if cuda_version:
             system_cuda_display = cuda_version
@@ -1964,7 +1899,6 @@ def _get_vllm_cuda_mismatch_message(error):
     cpu_arch = "x86_64"
     try:
         import platform
-
         cpu_arch = platform.machine()
     except Exception:
         pass
@@ -1998,7 +1932,12 @@ class _CausalConv1dImportBlockerFinder(importlib.abc.MetaPathFinder):
     def __init__(self):
         setattr(self, _CAUSAL_CONV1D_BLOCKER_SENTINEL, True)
 
-    def find_spec(self, fullname, path = None, target = None):
+    def find_spec(
+        self,
+        fullname,
+        path = None,
+        target = None,
+    ):
         if not CAUSAL_CONV1D_BROKEN or not _is_causal_conv1d_name(fullname):
             return None
         return importlib.machinery.ModuleSpec(
@@ -2027,7 +1966,12 @@ class _VllmImportBlockerFinder(importlib.abc.MetaPathFinder):
     def __init__(self):
         setattr(self, _VLLM_BLOCKER_SENTINEL, True)
 
-    def find_spec(self, fullname, path = None, target = None):
+    def find_spec(
+        self,
+        fullname,
+        path = None,
+        target = None,
+    ):
         if not VLLM_BROKEN or not _is_vllm_name(fullname):
             return None
         return importlib.machinery.ModuleSpec(
@@ -2116,7 +2060,6 @@ def disable_broken_vllm(error = None):
 
         try:
             import vllm  # noqa: F401
-
             return False
         except Exception as import_error:
             failure = import_error
@@ -2178,7 +2121,6 @@ def disable_broken_causal_conv1d():
 
     try:
         import causal_conv1d  # noqa: F401
-
         return
     except Exception as error:
         if not _is_broken_causal_conv1d_error(error):
diff --git a/unsloth/kernels/__init__.py b/unsloth/kernels/__init__.py
index 15913413d9..d46e0f4d59 100644
--- a/unsloth/kernels/__init__.py
+++ b/unsloth/kernels/__init__.py
@@ -65,9 +65,7 @@ import os
 
 if "UNSLOTH_ZOO_IS_PRESENT" not in os.environ:
     try:
-        print(
-            "🦥 Unsloth: Will patch your computer to enable 2x faster free finetuning."
-        )
+        print("🦥 Unsloth: Will patch your computer to enable 2x faster free finetuning.")
     except:
         print("Unsloth: Will patch your computer to enable 2x faster free finetuning.")
 del os
diff --git a/unsloth/kernels/cross_entropy_loss.py b/unsloth/kernels/cross_entropy_loss.py
index 4a8f83ad04..a170ed3dcf 100644
--- a/unsloth/kernels/cross_entropy_loss.py
+++ b/unsloth/kernels/cross_entropy_loss.py
@@ -75,9 +75,7 @@ def _cross_entropy_forward(
     mask = col_offsets < VOCAB_SIZE
 
     label_idx = tl.load(labels_ptr).to(tl.int32)
-    logits = tl.load(logits_ptr + col_offsets, mask = mask, other = -float("inf")).to(
-        tl.float32
-    )
+    logits = tl.load(logits_ptr + col_offsets, mask = mask, other = -float("inf")).to(tl.float32)
 
     # Go logit scaling for Cohere: t * x
     if DO_LOGIT_SCALING:
@@ -162,9 +160,7 @@ def _chunked_cross_entropy_forward(
     mask = col_offsets < VOCAB_SIZE
 
     label_idx = tl.load(labels_ptr).to(tl.int32)
-    logits = tl.load(logits_ptr + col_offsets, mask = mask, other = -float("inf")).to(
-        tl.float32
-    )
+    logits = tl.load(logits_ptr + col_offsets, mask = mask, other = -float("inf")).to(tl.float32)
 
     # Go logit scaling for Cohere: t * x
     if DO_LOGIT_SCALING:
@@ -295,7 +291,11 @@ MAX_FUSED_SIZE = 65536  # 2**16
 class Fast_CrossEntropyLoss(torch.autograd.Function):
     @staticmethod
     def forward(
-        ctx, logits, labels, logit_softcapping: float = 0, logit_scaling: float = 0
+        ctx,
+        logits,
+        labels,
+        logit_softcapping: float = 0,
+        logit_scaling: float = 0,
     ):
         n_rows: int
         vocab_size: int
@@ -468,7 +468,6 @@ def patch_loss_functions(torch_compile = True):
     # the floor pin moves past unslothai/unsloth-zoo#656.
     try:
         import transformers.loss.loss_utils as _lu
-
         _unsloth_loss = _lu.LOSS_MAPPING.get("ForCausalLM")
         if _unsloth_loss is not None:
             for _key, _fn in list(_lu.LOSS_MAPPING.items()):
diff --git a/unsloth/kernels/fast_lora.py b/unsloth/kernels/fast_lora.py
index f1c0e298d9..a49a9e04e8 100644
--- a/unsloth/kernels/fast_lora.py
+++ b/unsloth/kernels/fast_lora.py
@@ -232,7 +232,11 @@ class LoRA_MLP(torch.autograd.Function):
 from .swiglu import swiglu_fg_kernel, swiglu_DWf_DW_dfg_kernel
 
 
-def apply_lora_mlp_swiglu(self, X, inplace = True):
+def apply_lora_mlp_swiglu(
+    self,
+    X,
+    inplace = True,
+):
     X = _maybe_fake_quantize_activations(X, self.gate_proj)
     gateW, gateW_quant, gateA, gateB, gateS = get_lora_parameters(self.gate_proj)
     upW, upW_quant, upA, upB, upS = get_lora_parameters(self.up_proj)
@@ -264,7 +268,11 @@ def apply_lora_mlp_swiglu(self, X, inplace = True):
 from .geglu import geglu_exact_forward_kernel, geglu_exact_backward_kernel
 
 
-def apply_lora_mlp_geglu_exact(self, X, inplace = True):
+def apply_lora_mlp_geglu_exact(
+    self,
+    X,
+    inplace = True,
+):
     X = _maybe_fake_quantize_activations(X, self.gate_proj)
     gateW, gateW_quant, gateA, gateB, gateS = get_lora_parameters(self.gate_proj)
     upW, upW_quant, upA, upB, upS = get_lora_parameters(self.up_proj)
@@ -532,7 +540,11 @@ class LoRA_QKV(torch.autograd.Function):
         )
 
 
-def apply_lora_qkv(self, X, inplace = True):
+def apply_lora_qkv(
+    self,
+    X,
+    inplace = True,
+):
     X = _maybe_fake_quantize_activations(X, self.q_proj)
     QW, QW_quant, QA, QB, QS = get_lora_parameters(self.q_proj)
     KW, KW_quant, KA, KB, KS = get_lora_parameters(self.k_proj)
@@ -650,9 +662,7 @@ IDENTITY_DROPOUT = torch.nn.Identity
 
 @torch._disable_dynamo
 def fast_lora_forward(self, x: torch.Tensor, *args, **kwargs) -> torch.Tensor:
-    raise NotImplementedError(
-        "Unsloth: Currently not supported yet - reshaping done incorrectly"
-    )
+    raise NotImplementedError("Unsloth: Currently not supported yet - reshaping done incorrectly")
     self._check_forward_args(x, *args, **kwargs)
     adapter_names = kwargs.pop("adapter_names", None)
 
@@ -661,9 +671,7 @@ def fast_lora_forward(self, x: torch.Tensor, *args, **kwargs) -> torch.Tensor:
             self.unmerge()
         result = self.base_layer(x, *args, **kwargs)
     elif adapter_names is not None:
-        result = self._mixed_batch_forward(
-            x, *args, adapter_names = adapter_names, **kwargs
-        )
+        result = self._mixed_batch_forward(x, *args, adapter_names = adapter_names, **kwargs)
     elif self.merged:
         result = self.base_layer(x, *args, **kwargs)
     else:
@@ -674,10 +682,7 @@ def fast_lora_forward(self, x: torch.Tensor, *args, **kwargs) -> torch.Tensor:
                 return self.base_layer(x, *args, **kwargs)
 
             dropout = self.lora_dropout[active_adapter]
-            if (
-                isinstance(dropout, IDENTITY_DROPOUT)
-                and not self.use_dora[active_adapter]
-            ):
+            if isinstance(dropout, IDENTITY_DROPOUT) and not self.use_dora[active_adapter]:
                 lora_A = self.lora_A[active_adapter].weight
                 lora_B = self.lora_B[active_adapter].weight
                 scaling = self.scaling[active_adapter]
diff --git a/unsloth/kernels/flex_attention.py b/unsloth/kernels/flex_attention.py
index b94ff56dec..0e386ac4aa 100644
--- a/unsloth/kernels/flex_attention.py
+++ b/unsloth/kernels/flex_attention.py
@@ -31,10 +31,7 @@ try:
         flex_attention as _flex_attention,
         create_block_mask as _create_block_mask,
     )
-
-    _flex_attention = torch.compile(
-        _flex_attention, dynamic = True, options = torch_compile_options
-    )
+    _flex_attention = torch.compile(_flex_attention, dynamic = True, options = torch_compile_options)
     HAS_FLEX_ATTENTION = False
 except:
     HAS_FLEX_ATTENTION = False
@@ -116,9 +113,7 @@ else:
         causal_mask = create_block_mask(causal_masker, max_seq_length)
         return causal_mask
 
-    def create_flex_attention_sliding_window_mask(
-        max_seq_length = 8192, sliding_window = 4096
-    ):
+    def create_flex_attention_sliding_window_mask(max_seq_length = 8192, sliding_window = 4096):
         sliding_masker = sliding_window_masker(sliding_window)
         causal_mask = create_block_mask(sliding_masker, max_seq_length)
         return causal_mask
diff --git a/unsloth/kernels/fp8.py b/unsloth/kernels/fp8.py
index f704d4e3c4..81dfe9880d 100644
--- a/unsloth/kernels/fp8.py
+++ b/unsloth/kernels/fp8.py
@@ -77,7 +77,10 @@ def weight_dequant_kernel(x_ptr, s_ptr, y_ptr, M, N, BLOCK_SIZE: tl.constexpr):
 
 
 def weight_dequant_block(
-    x: torch.Tensor, s: torch.Tensor, block_size: int = 128, dtype = torch.bfloat16
+    x: torch.Tensor,
+    s: torch.Tensor,
+    block_size: int = 128,
+    dtype = torch.bfloat16,
 ) -> torch.Tensor:
     if not x.is_contiguous():
         x = x.contiguous()
@@ -94,7 +97,11 @@ def weight_dequant_block(
     return y
 
 
-def weight_dequant(x: torch.Tensor, s: torch.Tensor, dtype = torch.bfloat16):
+def weight_dequant(
+    x: torch.Tensor,
+    s: torch.Tensor,
+    dtype = torch.bfloat16,
+):
     # Per-tensor scale: single value for entire weight matrix
     if s.numel() == 1:
         return x.to(dtype) * s.view(1, 1).to(dtype)
@@ -131,9 +138,7 @@ def act_quant_kernel(x_ptr, y_ptr, s_ptr, BLOCK_SIZE: tl.constexpr):
     tl.store(s_ptr + pid, s)
 
 
-def act_quant(
-    x: torch.Tensor, block_size: int = 128
-) -> tuple[torch.Tensor, torch.Tensor]:
+def act_quant(x: torch.Tensor, block_size: int = 128) -> tuple[torch.Tensor, torch.Tensor]:
     if not x.is_contiguous():
         x = x.contiguous()
     assert x.shape[-1] % block_size == 0
@@ -266,9 +271,7 @@ def w8a8_block_fp8_matmul_triton(
     BLOCK_SIZE_K, BLOCK_SIZE_N = block_k, block_n
 
     def grid(META):
-        return (
-            triton.cdiv(M, META["BLOCK_SIZE_M"]) * triton.cdiv(N, META["BLOCK_SIZE_N"]),
-        )
+        return (triton.cdiv(M, META["BLOCK_SIZE_M"]) * triton.cdiv(N, META["BLOCK_SIZE_N"]),)
 
     _w8a8_block_fp8_matmul[grid](
         A,
@@ -321,9 +324,7 @@ def torchao_block_matmul(
 # So our preference order is fbgemm (>=1.4.0) > torchao > triton. All of these have similar outputs/losses. Never use fbgemm (<=1.3.0) for block quantized FP8 matmul.
 # This torchao FP8 matmul seems to be ~3x faster than the w8a8_block_fp8_matmul_triton. Though torchao is 15-30% slower than fbgemm implementation (on H100 GPUs).
 fp8_block_matmul = (
-    torchao_block_matmul
-    if torchao_blockwise_gemm is not None
-    else w8a8_block_fp8_matmul_triton
+    torchao_block_matmul if torchao_blockwise_gemm is not None else w8a8_block_fp8_matmul_triton
 )
 
 
@@ -350,10 +351,7 @@ class FP8BlockQuantLinear(torch.autograd.Function):
             )
             assert block_size is not None, "block_size is not set"
             if triton.cdiv(m, block_size[0]) != p or triton.cdiv(n, block_size[1]) != q:
-                if (
-                    triton.cdiv(m, block_size[0]) == q
-                    and triton.cdiv(n, block_size[1]) == p
-                ):
+                if triton.cdiv(m, block_size[0]) == q and triton.cdiv(n, block_size[1]) == p:
                     weight_scale = weight_scale.T
                     original_weight_scale = weight_scale  # Update for transposed case
                 else:
@@ -393,7 +391,13 @@ def fp8_torch_block_quant_forward(X, weight, weight_scale):
 
 class FbgemmFp8Linear_matmul(torch.autograd.Function):
     @staticmethod
-    def forward(ctx, x, weight, weight_scale, bias = None):
+    def forward(
+        ctx,
+        x,
+        weight,
+        weight_scale,
+        bias = None,
+    ):
         if weight.shape[0] == weight_scale.shape[0] and (
             weight.shape[0] % 8 == 0 and weight.shape[1] % 8 == 0
         ):
@@ -430,8 +434,7 @@ class FbgemmFp8Linear_matmul(torch.autograd.Function):
             output = output.reshape(output_shape)
             del x_quantized, x_scale
         elif (
-            weight.shape[0] != weight_scale.shape[0]
-            and weight.shape[1] == weight_scale.shape[0]
+            weight.shape[0] != weight_scale.shape[0] and weight.shape[1] == weight_scale.shape[0]
         ) or (weight.shape[0] % 8 != 0 or weight.shape[1] % 8 != 0):
             # Either the weight/scale is transposed or its shape is not divisible by 8. Both cases, dequantizing is the preferred way.
             # The transpose case is generally noticed in backward pass when we do dY@W instead of @W.T as we do for forward.
@@ -459,13 +462,24 @@ class FbgemmFp8Linear_matmul(torch.autograd.Function):
 
 
 @torch_compile
-def fbgemm_fp8_linear(X, weight, weight_scale, bias = None):
+def fbgemm_fp8_linear(
+    X,
+    weight,
+    weight_scale,
+    bias = None,
+):
     return FbgemmFp8Linear_matmul.apply(X, weight, weight_scale, bias)
 
 
 class FP8_fbgemm_block_linear(torch.autograd.Function):
     @staticmethod
-    def forward(ctx, X, weight, weight_scale, bias = None):
+    def forward(
+        ctx,
+        X,
+        weight,
+        weight_scale,
+        bias = None,
+    ):
         orig_shape = X.shape
         X = X.view(-1, X.shape[-1])
 
@@ -516,7 +530,12 @@ class FP8_fbgemm_block_linear(torch.autograd.Function):
 
 
 @torch_compile
-def fp8_fbgemm_block_linear(X, weight, weight_scale, bias = None):
+def fp8_fbgemm_block_linear(
+    X,
+    weight,
+    weight_scale,
+    bias = None,
+):
     return FP8_fbgemm_block_linear.apply(X, weight, weight_scale, bias)
 
 
@@ -555,9 +574,7 @@ def test_has_fbgemm():
         is_cutlass_cuda_error = any(err in error_str for err in cutlass_cuda_errors)
 
         if is_cutlass_cuda_error:
-            print(
-                "Unsloth: FBGEMM on the current GPU cannot load - will switch to Triton kernels"
-            )
+            print("Unsloth: FBGEMM on the current GPU cannot load - will switch to Triton kernels")
         else:
             print(
                 f"Unsloth: FBGEMM on the current GPU cannot load with error = {e} - will switch to Triton kernels"
@@ -584,7 +601,6 @@ try:
         # FBGEMM's CUTLASS blockwise kernel (hardcoded SM90) fires thousands of
         # "Arch conditional MMA" lines to stdout fd 1 before aborting.
         from unsloth.import_fixes import suppress_cuda_printf
-
         with suppress_cuda_printf():
             _has_fbgemm = test_has_fbgemm()
         if _has_fbgemm:
@@ -598,12 +614,15 @@ except:
 
 
 @torch_compile
-def fp8_linear(X, weight, weight_scale, bias = None):
+def fp8_linear(
+    X,
+    weight,
+    weight_scale,
+    bias = None,
+):
     # Per-tensor quantization: single scalar scale for entire weight
     # Block quantized FP8: 2D scale tensor with multiple columns
-    if weight_scale.numel() == 1 or (
-        weight_scale.ndim == 2 and weight_scale.shape[1] > 1
-    ):
+    if weight_scale.numel() == 1 or (weight_scale.ndim == 2 and weight_scale.shape[1] > 1):
         out = fp8_block_quant_linear(X, weight, weight_scale)
     # Row/channel quantized FP8: 2D scale with shape (n, 1)
     else:
diff --git a/unsloth/kernels/geglu.py b/unsloth/kernels/geglu.py
index 50b4e521d3..3a628f105c 100644
--- a/unsloth/kernels/geglu.py
+++ b/unsloth/kernels/geglu.py
@@ -30,18 +30,11 @@ INT32_SAFETY_BUFFER = NUM_INT32_ELEMENTS - BLOCK_SIZE * SAFE_INT32_BUFFER_MULTIP
 
 @triton.jit
 def _exact_forward_kernel(
-    e,
-    g,
-    h,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
+    e, g, h, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr
 ):
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
@@ -80,12 +73,7 @@ def geglu_exact_forward_kernel(gate, up):
 
 @triton.jit
 def _exact_backward_kernel(
-    DW,
-    e,
-    g,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
+    DW, e, g, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr
 ):
     """
     f = 1/2 * e * (1 + erf(1/sqrt(2) * e))
@@ -99,9 +87,7 @@ def _exact_backward_kernel(
     """
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
@@ -155,18 +141,11 @@ def geglu_exact_backward_kernel(DW, e, g):
 
 @triton.jit
 def _approx_forward_kernel(
-    e,
-    g,
-    h,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
+    e, g, h, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr
 ):
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
@@ -180,9 +159,7 @@ def _approx_forward_kernel(
     e_row = tl.load(e + offsets, mask = mask, other = 0).to(tl.float32)
     g_row = tl.load(g + offsets, mask = mask, other = 0)  # .to(tl.float32)
 
-    f_row = (
-        0.5 * e_row * (triton_tanh(s * e_row * (1.0 + 0.044715 * e_row * e_row)) + 1.0)
-    )
+    f_row = 0.5 * e_row * (triton_tanh(s * e_row * (1.0 + 0.044715 * e_row * e_row)) + 1.0)
     f_row = f_row.to(g_row.dtype)  # Exact copy from HF
     h_row = f_row * g_row
 
@@ -210,12 +187,7 @@ def geglu_approx_forward_kernel(gate, up):
 
 @triton.jit
 def _approx_backward_kernel(
-    DW,
-    e,
-    g,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
+    DW, e, g, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr
 ):
     """
     f = 1/2 * e * (1 + tanh( sqrt(2/pi) * x * (1 + 0.044715 * x^2 ) ))
@@ -233,9 +205,7 @@ def _approx_backward_kernel(
     """
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
diff --git a/unsloth/kernels/layernorm.py b/unsloth/kernels/layernorm.py
index 9e64c3d341..4da6c8bf9a 100644
--- a/unsloth/kernels/layernorm.py
+++ b/unsloth/kernels/layernorm.py
@@ -99,11 +99,7 @@ def layernorm_backward(
     mean = tl.load(mu).to(tl.float32)
     normed = (X_row - mean) * inv_var
     dY_W = dY_row * W_row
-    dX_row = (
-        dY_W
-        - tl.sum(dY_W, axis = 0) / n_cols
-        - normed * tl.sum(dY_W * normed, axis = 0) / n_cols
-    )
+    dX_row = dY_W - tl.sum(dY_W, axis = 0) / n_cols - normed * tl.sum(dY_W * normed, axis = 0) / n_cols
     dX_row = dX_row * inv_var
     tl.store(dY + col_offsets, dX_row, mask = mask)
 
@@ -173,11 +169,7 @@ def fast_layernorm(layernorm, X):
     assert layernorm.elementwise_affine is True
     W = layernorm.weight
     bias = layernorm.bias
-    eps = (
-        layernorm.variance_epsilon
-        if hasattr(layernorm, "variance_epsilon")
-        else layernorm.eps
-    )
+    eps = layernorm.variance_epsilon if hasattr(layernorm, "variance_epsilon") else layernorm.eps
     out = Fast_Layernorm.apply(X, W, bias, eps)
     return out
 
diff --git a/unsloth/kernels/moe/autotune_cache.py b/unsloth/kernels/moe/autotune_cache.py
index eac6b02b08..5756a9c416 100644
--- a/unsloth/kernels/moe/autotune_cache.py
+++ b/unsloth/kernels/moe/autotune_cache.py
@@ -105,9 +105,7 @@ def save_cached_config(
     cache_data = {
         "timestamp": time.time(),
         "device_capability": torch.cuda.get_device_capability(),
-        "config_fwd": config_fwd.__dict__
-        if hasattr(config_fwd, "__dict__")
-        else str(config_fwd),
+        "config_fwd": config_fwd.__dict__ if hasattr(config_fwd, "__dict__") else str(config_fwd),
         "config_bwd_dx": config_bwd_dx.__dict__
         if hasattr(config_bwd_dx, "__dict__")
         else str(config_bwd_dx),
@@ -230,9 +228,7 @@ def get_or_autotune_moe_kernels(
 
     except Exception as e:
         logger.error(f"MoE kernel auto-tuning failed: {e}")
-        if "AttributeError" in str(e) and "_experimental_make_tensor_descriptor" in str(
-            e
-        ):
+        if "AttributeError" in str(e) and "_experimental_make_tensor_descriptor" in str(e):
             logger.warning(
                 "Unsloth: Your Triton version might be incompatible with TMA features. Falling back to default configs."
             )
@@ -270,9 +266,7 @@ def _run_moe_autotuning(
     )
 
     # Create dummy routing data
-    m_sizes = torch.randint(
-        1, total_tokens // num_experts + 1, (num_experts,), device = device
-    )
+    m_sizes = torch.randint(1, total_tokens // num_experts + 1, (num_experts,), device = device)
     m_sizes = m_sizes * (total_tokens // m_sizes.sum().item())
     # Adjust to ensure exact total
     diff = total_tokens - m_sizes.sum().item()
@@ -328,9 +322,7 @@ def _run_moe_autotuning(
 
     # Autotune backward dX kernel
     logger.info("Autotuning backward dX kernel...")
-    dummy_grad = torch.randn(
-        total_tokens, 2 * intermediate_dim, device = device, dtype = dtype
-    )
+    dummy_grad = torch.randn(total_tokens, 2 * intermediate_dim, device = device, dtype = dtype)
     _ = grouped_gemm_dX(
         dY = dummy_grad,
         W = gate_up_weights,
diff --git a/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py b/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
index 074cc5a566..a5ea4a4e71 100644
--- a/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
+++ b/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
@@ -55,9 +55,7 @@ def run_benchmark_forward(
     device = "cuda"
     hidden_size = config.hidden_size
 
-    X = torch.randn(
-        bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True
-    )
+    X = torch.randn(bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True)
 
     # Forward
     bench_forward_ref = lambda: ref_model(X)  # noqa: E731
@@ -97,9 +95,7 @@ def run_benchmark_backward(
     device = "cuda"
     hidden_size = config.hidden_size
 
-    X = torch.randn(
-        bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True
-    )
+    X = torch.randn(bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True)
     X_test = X.detach().clone().requires_grad_(True)
 
     output, _ = ref_model(X)
@@ -107,9 +103,9 @@ def run_benchmark_backward(
     # Prevent autotuning forward pass
     from grouped_gemm.kernels.forward import _autotuned_grouped_gemm_forward_kernel
 
-    _autotuned_grouped_gemm_forward_kernel.configs = (
-        _autotuned_grouped_gemm_forward_kernel.configs[:20]
-    )
+    _autotuned_grouped_gemm_forward_kernel.configs = _autotuned_grouped_gemm_forward_kernel.configs[
+        :20
+    ]
     test_output, _ = tt_model(X_test)
 
     # Bench
@@ -117,9 +113,7 @@ def run_benchmark_backward(
     bench_backward_ref = lambda: output.backward(grad_output, retain_graph = True)  # noqa: E731
     bench_backward_fused = lambda: test_output.backward(grad_output, retain_graph = True)  # noqa: E731
 
-    ref_backward_time = do_bench(
-        bench_backward_ref, grad_to_none = [X, *ref_model.parameters()]
-    )
+    ref_backward_time = do_bench(bench_backward_ref, grad_to_none = [X, *ref_model.parameters()])
     fused_backward_time = do_bench(
         bench_backward_fused, grad_to_none = [X_test, *tt_model.parameters()]
     )
@@ -235,16 +229,10 @@ def run_benchmark(
     if autotune:
         if mode == "backward":
             autotuner_dW, autotuner_dX = autotuner
-            postprocess_autotune_results(
-                autotuner_dW, "dW", ref_time, fused_time, results_dir
-            )
-            postprocess_autotune_results(
-                autotuner_dX, "dX", ref_time, fused_time, results_dir
-            )
+            postprocess_autotune_results(autotuner_dW, "dW", ref_time, fused_time, results_dir)
+            postprocess_autotune_results(autotuner_dX, "dX", ref_time, fused_time, results_dir)
         else:
-            postprocess_autotune_results(
-                autotuner, mode, ref_time, fused_time, results_dir
-            )
+            postprocess_autotune_results(autotuner, mode, ref_time, fused_time, results_dir)
 
     return ref_time, fused_time
 
@@ -254,9 +242,7 @@ if __name__ == "__main__":
     parser.add_argument("--results_dir", type = str, default = "benchmark_results")
     parser.add_argument("--model", type = str, choices = ["llama4", "qwen3"], required = True)
     parser.add_argument("--seqlen", type = int, default = 1024)
-    parser.add_argument(
-        "--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16"
-    )
+    parser.add_argument("--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16")
     parser.add_argument("--permute_x", action = "store_true")
     parser.add_argument("--permute_y", action = "store_true")
     parser.add_argument("--autotune", action = "store_true")
@@ -391,9 +377,5 @@ if __name__ == "__main__":
                     kernel_config = kernel_config,
                 )
             )
-        df = post_process_results(
-            results, args.mode, args.seqlen, args.dtype, args.autotune
-        )
-        save_results(
-            df, args.results_dir, args.mode, args.seqlen, args.dtype, args.autotune
-        )
+        df = post_process_results(results, args.mode, args.seqlen, args.dtype, args.autotune)
+        save_results(df, args.results_dir, args.mode, args.seqlen, args.dtype, args.autotune)
diff --git a/unsloth/kernels/moe/benchmark/utils.py b/unsloth/kernels/moe/benchmark/utils.py
index 56396687e4..7f119a7e6f 100644
--- a/unsloth/kernels/moe/benchmark/utils.py
+++ b/unsloth/kernels/moe/benchmark/utils.py
@@ -38,11 +38,7 @@ def create_merged_results(
 
 
 def post_process_results(
-    results: list[KernelResult],
-    mode: str,
-    seqlen: int,
-    dtype: torch.dtype,
-    autotune: bool,
+    results: list[KernelResult], mode: str, seqlen: int, dtype: torch.dtype, autotune: bool
 ):
     df = KernelResult.to_dataframe(results, sort_by = "speedup")
     df = create_merged_results(df, mode, seqlen, dtype, autotune)
@@ -50,12 +46,7 @@ def post_process_results(
 
 
 def save_results(
-    df: pd.DataFrame,
-    results_dir: str,
-    mode: str,
-    seqlen: int,
-    dtype: torch.dtype,
-    autotune: bool,
+    df: pd.DataFrame, results_dir: str, mode: str, seqlen: int, dtype: torch.dtype, autotune: bool
 ):
     dt = datetime.datetime.now().strftime("%Y%m%d_%H%M")
     save_dir = f"{results_dir}/{mode}"
@@ -71,9 +62,7 @@ def create_kernel_configs(args: argparse.Namespace, permute_x: bool, permute_y:
     block_n_range = power_of_two_range(args.BLOCK_SIZE_N[0], args.BLOCK_SIZE_N[1])
     block_k_range = power_of_two_range(args.BLOCK_SIZE_K[0], args.BLOCK_SIZE_K[1])
     num_warps_range = multiples_of_range(args.num_warps[0], args.num_warps[1], step = 2)
-    num_stages_range = multiples_of_range(
-        args.num_stages[0], args.num_stages[1], step = 1
-    )
+    num_stages_range = multiples_of_range(args.num_stages[0], args.num_stages[1], step = 1)
 
     mode = args.mode
     kernel_configs = []
@@ -161,7 +150,11 @@ def power_of_two_range(start, end):
     return [2**i for i in range(int(start), int(end) + 1)]
 
 
-def multiples_of_range(start, end, step = 1):
+def multiples_of_range(
+    start,
+    end,
+    step = 1,
+):
     return list(range(start, end + step, step))
 
 
@@ -177,9 +170,7 @@ def save_autotune_results(autotune_cache, mode, ref_time, fused_time, results_di
         os.makedirs(save_dir)
 
     for key, config in autotune_cache.items():
-        key = [
-            str(k) if not "torch" in str(k) else str(k.split("torch.")[-1]) for k in key
-        ]
+        key = [str(k) if not "torch" in str(k) else str(k.split("torch.")[-1]) for k in key]
         filename = "_".join(key)
         save_path = f"{save_dir}/{filename}.json"
         print(f"Saving autotune results to {save_path}")
@@ -195,22 +186,18 @@ def save_autotune_results(autotune_cache, mode, ref_time, fused_time, results_di
 def get_autotuner(mode):
     if mode == "forward":
         from grouped_gemm.kernels.forward import _autotuned_grouped_gemm_forward_kernel
-
         return _autotuned_grouped_gemm_forward_kernel
     elif mode == "dW":
         from grouped_gemm.kernels.backward import _autotuned_grouped_gemm_dW_kernel
-
         return _autotuned_grouped_gemm_dW_kernel
     elif mode == "dX":
         from grouped_gemm.kernels.backward import _autotuned_grouped_gemm_dX_kernel
-
         return _autotuned_grouped_gemm_dX_kernel
     elif mode == "backward":
         from grouped_gemm.kernels.backward import (
             _autotuned_grouped_gemm_dW_kernel,
             _autotuned_grouped_gemm_dX_kernel,
         )
-
         return _autotuned_grouped_gemm_dW_kernel, _autotuned_grouped_gemm_dX_kernel
     else:
         raise ValueError(f"Invalid mode: {mode}")
diff --git a/unsloth/kernels/moe/grouped_gemm/interface.py b/unsloth/kernels/moe/grouped_gemm/interface.py
index 5588458973..86b1558ff9 100644
--- a/unsloth/kernels/moe/grouped_gemm/interface.py
+++ b/unsloth/kernels/moe/grouped_gemm/interface.py
@@ -27,9 +27,7 @@ from .kernels.tuning import (
 
 logger = logging.getLogger(__name__)
 # Set formatter to include timestamp, pathname and lineno
-formatter = logging.Formatter(
-    "%(asctime)s::%(levelname)s,%(pathname)s:%(lineno)d:: %(message)s"
-)
+formatter = logging.Formatter("%(asctime)s::%(levelname)s,%(pathname)s:%(lineno)d:: %(message)s")
 
 # Add console handler
 ch = logging.StreamHandler()
@@ -98,13 +96,8 @@ def get_per_device_per_stream_alloc_fn(device):
 
         def alloc_fn(size: int, alignment: int, stream):
             assert alignment == 128
-            if (
-                stream not in _per_stream_tensors
-                or _per_stream_tensors[stream].numel() < size
-            ):
-                _per_stream_tensors[stream] = torch.empty(
-                    size, device = device, dtype = torch.int8
-                )
+            if stream not in _per_stream_tensors or _per_stream_tensors[stream].numel() < size:
+                _per_stream_tensors[stream] = torch.empty(size, device = device, dtype = torch.int8)
                 _per_stream_tensors[stream].__hibernate__ = {"type": "ignore"}
             return _per_stream_tensors[stream]
 
@@ -119,9 +112,7 @@ def log_kernel_info(
     nregs = compiled_kernel.n_regs
     nspills = compiled_kernel.n_spills
     metadata = compiled_kernel.metadata
-    logger.debug(
-        f"{kernel_name}: n_regs={nregs} n_spills={nspills} metadata={metadata}"
-    )
+    logger.debug(f"{kernel_name}: n_regs={nregs} n_spills={nspills} metadata={metadata}")
     if best_config is not None:
         logger.debug(f"{kernel_name} autotuned best_config: {best_config}")
 
@@ -248,9 +239,7 @@ def grouped_gemm_forward(
     if fuse_mul_post:
         global _FUSED_MUL_WARN
         if not _FUSED_MUL_WARN:
-            warnings.warn(
-                "fused_mul should only be used for inference, not for training"
-            )
+            warnings.warn("fused_mul should only be used for inference, not for training")
             _FUSED_MUL_WARN = True
         assert permute_y, "FUSE_MUL requires PERMUTE_Y"
         assert topk_weights is not None
@@ -259,9 +248,7 @@ def grouped_gemm_forward(
         assert topk_weights.is_contiguous()
         topk_weights = topk_weights.view(-1)
         if debug:
-            print(
-                f"DEBUG::GROUPED_GEMM {topk_weights.tolist()} {gather_indices.tolist()}"
-            )
+            print(f"DEBUG::GROUPED_GEMM {topk_weights.tolist()} {gather_indices.tolist()}")
 
     y = torch.empty((total_tokens, N), device = X.device, dtype = X.dtype)
     # if total_tokens == 0 or N == 0:
@@ -281,9 +268,7 @@ def grouped_gemm_forward(
         print(
             f"DEBUG::GROUPED_GEMM {num_tokens = } {topk = } {num_experts = } {N = } {K = } {BLOCK_SIZE_M = } {BLOCK_SIZE_N = } {BLOCK_SIZE_K = } {permute_x = }"
         )
-        print(
-            f"DEBUG::GROUPED_GEMM {m_sizes.tolist()} {(gather_indices // topk).tolist()}"
-        )
+        print(f"DEBUG::GROUPED_GEMM {m_sizes.tolist()} {(gather_indices // topk).tolist()}")
 
     kernel_args = {
         # Inputs
@@ -323,11 +308,7 @@ def grouped_gemm_forward(
             }
         )
 
-    kernel = (
-        _autotuned_grouped_gemm_forward_kernel
-        if autotune
-        else _grouped_gemm_forward_kernel
-    )
+    kernel = _autotuned_grouped_gemm_forward_kernel if autotune else _grouped_gemm_forward_kernel
 
     is_fake = _is_tracing(X, W)
     if not is_fake:
@@ -383,12 +364,8 @@ def grouped_gemm_dX(
     use_tma_load_w: use TMA for loading weights.  If TMA supported, this should always be enabled as it is faster than global memory load.
     use_tma_store: use TMA for storing dX.  Incompatible with permute_x.  TODO: add TMA gather / scatter support for Blackwell+ which will enable permute_x and use_tma_store.
     """
-    assert (
-        not fuse_mul_pre
-    ), "fuse_mul_pre should only be used for inference, not for training"
-    assert (
-        not fuse_mul_post
-    ), "fuse_mul_post should only be used for inference, not for training"
+    assert not fuse_mul_pre, "fuse_mul_pre should only be used for inference, not for training"
+    assert not fuse_mul_post, "fuse_mul_post should only be used for inference, not for training"
     assert dY.is_contiguous()
     assert W.is_contiguous()
     assert m_sizes.is_contiguous()
@@ -433,24 +410,18 @@ def grouped_gemm_dX(
     # N = N_total // num_experts
     assert N_grad == N, f"Grad_output N ({N_grad}) must match weight N ({N})"
 
-    assert (
-        M_total % topk == 0
-    ), f"M_total ({M_total}) must be divisible by topk ({topk})"
+    assert M_total % topk == 0, f"M_total ({M_total}) must be divisible by topk ({topk})"
     num_tokens = M_total // topk
 
     total_tokens = gather_indices.shape[0]
-    assert (
-        total_tokens == M_total
-    ), f"Total tokens ({total_tokens}) must match M_total ({M_total})"
+    assert total_tokens == M_total, f"Total tokens ({total_tokens}) must match M_total ({M_total})"
 
     # Note that the output shape is [NUM_TOKENS * TOPK, K] even when `permute_x` is True since we need to accumulate gradients across all experts chosen by the token.
     # This will be done in a post-processing step reduction step.
     output_shape = (total_tokens, K)
     dX = torch.zeros(output_shape, device = dY.device, dtype = dY.dtype)
 
-    NUM_SMS = torch.cuda.get_device_properties(
-        "cuda"
-    ).multi_processor_count  # if not debug else 1
+    NUM_SMS = torch.cuda.get_device_properties("cuda").multi_processor_count  # if not debug else 1
 
     def grid(META):
         return (NUM_SMS,)
@@ -555,11 +526,7 @@ def grouped_gemm_dW(
     """
     assert not fuse_mul_pre, "fuse_mul_pre not supported"
     assert not fuse_mul_post, "fuse_mul_post not supported"
-    NUM_SMS = (
-        torch.cuda.get_device_properties("cuda").multi_processor_count
-        if not debug
-        else 1
-    )
+    NUM_SMS = torch.cuda.get_device_properties("cuda").multi_processor_count if not debug else 1
     X = X.view(-1, X.shape[-1]).contiguous()
     dY = dY.contiguous()
     m_sizes = m_sizes.contiguous()
@@ -632,9 +599,7 @@ def grouped_gemm_dW(
                 token_idx = expert_token_idx[t_start : t_start + BLOCK_SIZE_M]
                 if permute_x:
                     token_idx = token_idx // topk
-                print(
-                    f"DEBUG::GROUPED_GEMM_DW_TMA Token expert {i} indices: {token_idx.tolist()}"
-                )
+                print(f"DEBUG::GROUPED_GEMM_DW_TMA Token expert {i} indices: {token_idx.tolist()}")
                 t_start += BLOCK_SIZE_M
 
             m_start += m_sizes[i]
@@ -774,9 +739,7 @@ class GroupedGemm(torch.autograd.Function):
                     kernel_config_bwd_dW is not None
                 ), "kernel_config_bwd_dW must be provided if autotune is False"
 
-        assert (
-            not fuse_mul_post
-        ), "fused_mul should only be used for inference, not for training"
+        assert not fuse_mul_post, "fused_mul should only be used for inference, not for training"
 
         if not dX_only:
             bwd_dW_config = {}
@@ -872,15 +835,9 @@ def check_valid_config_fwd(
     is_second_gemm = not is_first_gemm
 
     assert not (permute_x and permute_y), "Cannot permute both X and Y"
-    assert not (
-        is_second_gemm and permute_x
-    ), "Cannot permute X for the second grouped GEMM"
-    assert not (
-        is_first_gemm and permute_y
-    ), "Cannot permute Y for the first grouped GEMM"
-    assert not (
-        fuse_mul_post and is_first_gemm
-    ), "Cannot fuse mul for the first grouped GEMM"
+    assert not (is_second_gemm and permute_x), "Cannot permute X for the second grouped GEMM"
+    assert not (is_first_gemm and permute_y), "Cannot permute Y for the first grouped GEMM"
+    assert not (fuse_mul_post and is_first_gemm), "Cannot fuse mul for the first grouped GEMM"
     assert not (
         use_tma_load_x and permute_x
     ), "Cannot use TMA load and permute X unless on sm100+ (Blackwell+)"
@@ -1014,9 +971,7 @@ def grouped_gemm(
         ), "gather_indices is required when either permute_x or permute_y is True"
 
     if fuse_mul_post:
-        assert (
-            topk_weights is not None
-        ), "topk_weights is required when fuse_mul_post is True"
+        assert topk_weights is not None, "topk_weights is required when fuse_mul_post is True"
 
     X = X.view(-1, X.shape[-1])
     m_sizes = m_sizes.view(-1)
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py b/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
index d25913975e..7c1b25e234 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
@@ -307,16 +307,11 @@ def get_dW_kernel_configs(
 
 
 def estimate_smem_reqs(
-    num_stages: int,
-    BLOCK_SIZE_M: int,
-    BLOCK_SIZE_N: int,
-    BLOCK_SIZE_K: int,
-    dtype: torch.dtype,
+    num_stages: int, BLOCK_SIZE_M: int, BLOCK_SIZE_N: int, BLOCK_SIZE_K: int, dtype: torch.dtype
 ):
     num_bytes = dtype.itemsize
     return (
-        num_stages * BLOCK_SIZE_K * (BLOCK_SIZE_M + BLOCK_SIZE_N)
-        + BLOCK_SIZE_M * BLOCK_SIZE_N
+        num_stages * BLOCK_SIZE_K * (BLOCK_SIZE_M + BLOCK_SIZE_N) + BLOCK_SIZE_M * BLOCK_SIZE_N
     ) * num_bytes
 
 
@@ -329,9 +324,7 @@ def exceeds_smem_capacity(
     smem_size: int,
     slack: float = 50000,
 ):
-    smem_reqs = estimate_smem_reqs(
-        num_stages, BLOCK_SIZE_M, BLOCK_SIZE_N, BLOCK_SIZE_K, dtype
-    )
+    smem_reqs = estimate_smem_reqs(num_stages, BLOCK_SIZE_M, BLOCK_SIZE_N, BLOCK_SIZE_K, dtype)
     return smem_reqs > smem_size + slack
 
 
@@ -369,7 +362,6 @@ def common_prune_criteria(config: triton.Config, kwargs: dict, dtype):
 
 def maybe_disable_tma(config: triton.Config):
     from ..interface import supports_tma
-
     tma_keys = [k for k in config.kwargs.keys() if k.startswith("USE_TMA_")]
     if not supports_tma():
         logger.info("Disabling TMA")
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/backward.py b/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
index 5e07056b52..8c3c8fd13e 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
@@ -120,9 +120,7 @@ def _grouped_gemm_dX_kernel(
 
             if USE_TMA_STORE:
                 # Need to define descript within loop to predicate store along M
-                tl.static_assert(
-                    K % BLOCK_SIZE_K == 0, "K must be divisible by BLOCK_SIZE_K"
-                )
+                tl.static_assert(K % BLOCK_SIZE_K == 0, "K must be divisible by BLOCK_SIZE_K")
                 dX_desc = tl.make_tensor_descriptor(
                     dX_ptr,
                     shape = [m_end, K],
@@ -133,9 +131,7 @@ def _grouped_gemm_dX_kernel(
             # Lower bound and upper bound are defined relative to the total tiles processed so far
             # This ensures that we are only processing tiles for the current expert group AND
             # we never exceed the total number of tiles for all expert groups
-            while tidx >= processed_tiles and tidx < (
-                processed_tiles + num_tiles_per_expert
-            ):
+            while tidx >= processed_tiles and tidx < (processed_tiles + num_tiles_per_expert):
                 group_index = tidx - processed_tiles
 
                 # Output tile for this thread block for this expert group
@@ -177,9 +173,7 @@ def _grouped_gemm_dX_kernel(
                         load_a_idx = (
                             expert_token_offsets * N
                         )  # Permute on load from token -> expert order
-                        store_idx = (
-                            indices_to_gather[:, None] * K
-                        )  # Store in contiguous order
+                        store_idx = indices_to_gather[:, None] * K  # Store in contiguous order
                 else:
                     # # Position in full matrix - needed for TMA
                     # m_offset = (M_start + (tile_m_idx * BLOCK_SIZE_M)).to(tl.int32)
@@ -218,16 +212,12 @@ def _grouped_gemm_dX_kernel(
                     if not USE_TMA_LOAD_dY:
                         dY = tl.load(dY_ptrs, mask = row_mask)
                     else:
-                        dY = dY_desc.load(
-                            [m_start + tile_m_idx * BLOCK_SIZE_M, n_offset]
-                        )
+                        dY = dY_desc.load([m_start + tile_m_idx * BLOCK_SIZE_M, n_offset])
 
                     if not USE_TMA_LOAD_W:
                         w = tl.load(w_ptrs)  # , mask=col_mask)
                     else:
-                        w = w_desc.load(
-                            [expert_idx, n_offset, tile_k_idx * BLOCK_SIZE_K]
-                        )
+                        w = w_desc.load([expert_idx, n_offset, tile_k_idx * BLOCK_SIZE_K])
                         w = tl.reshape(w, (BLOCK_SIZE_N, BLOCK_SIZE_K))
                     # TODO: check if predication along K is needed since we checked that K is divisible by BLOCK_SIZE_K in the forward kernel
 
@@ -358,9 +348,7 @@ def _grouped_gemm_dW_kernel(
             block_shape = [1, BLOCK_SIZE_N, BLOCK_SIZE_K],
         )
 
-    for tile_idx in range(
-        tidx, output_tiles_per_expert, NUM_SMS
-    ):  # , flatten=FLATTEN):
+    for tile_idx in range(tidx, output_tiles_per_expert, NUM_SMS):  # , flatten=FLATTEN):
         # Output tile index
         tile_n_idx = tile_idx % num_n_tiles
         tile_k_idx = tile_idx // num_n_tiles
@@ -460,9 +448,7 @@ def _grouped_gemm_dW_kernel(
                             x = x_desc.load([m_global_offset, k_offset])
                         else:
                             x = tl.load(
-                                x_ptr
-                                + x_row_load_idx
-                                + (k_offset + block_range_k)[None, :],
+                                x_ptr + x_row_load_idx + (k_offset + block_range_k)[None, :],
                                 mask = mk_mask,
                             )
 
@@ -470,9 +456,7 @@ def _grouped_gemm_dW_kernel(
                             dY = dY_desc.load([m_global_offset, n_offset])
                         else:
                             dY = tl.load(
-                                dY_ptr
-                                + dY_row_load_idx
-                                + (n_offset + block_range_n)[None, :],
+                                dY_ptr + dY_row_load_idx + (n_offset + block_range_n)[None, :],
                                 mask = mn_mask,
                             )
 
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/forward.py b/unsloth/kernels/moe/grouped_gemm/kernels/forward.py
index a42ec5ffe9..e95179dd9f 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/forward.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/forward.py
@@ -108,10 +108,7 @@ def _grouped_gemm_forward_kernel(
                 )
 
             # Process tiles for this expert
-            while (
-                tidx >= processed_tiles
-                and tidx < processed_tiles + num_tiles_per_expert
-            ):
+            while tidx >= processed_tiles and tidx < processed_tiles + num_tiles_per_expert:
                 tile_idx = tidx - processed_tiles
 
                 # Check if L2 cache re-use for this order is optimal
@@ -146,9 +143,7 @@ def _grouped_gemm_forward_kernel(
                     load_idx = (
                         (expert_token_offsets // TOPK) * K
                     )  # Permute on load from token -> expert order, divide by TOPK to index from original number of tokens
-                    store_idx = (
-                        indices_to_gather[:, None] * N
-                    )  # Store in contiguous order
+                    store_idx = indices_to_gather[:, None] * N  # Store in contiguous order
                 else:
                     off_am = tile_m_idx * BLOCK_SIZE_M
                     if not PERMUTE_Y:
@@ -200,17 +195,13 @@ def _grouped_gemm_forward_kernel(
 
                     if FUSE_MUL_PRE:
                         # Check for correct broadcasting
-                        topk_weights = tl.load(
-                            topk_weights_ptr + topk_load_idx, mask = row_mask
-                        )
+                        topk_weights = tl.load(topk_weights_ptr + topk_load_idx, mask = row_mask)
                         x *= topk_weights.to(x.dtype)
 
                     if not USE_TMA_LOAD_W:
                         w = tl.load(w_ptrs, mask = offs_bn[:, None] < N)
                     else:
-                        w = w_desc.load(
-                            [expert_idx, tile_n_idx * BLOCK_SIZE_N, k_offset]
-                        )
+                        w = w_desc.load([expert_idx, tile_n_idx * BLOCK_SIZE_N, k_offset])
                         w = tl.reshape(w, (BLOCK_SIZE_N, BLOCK_SIZE_K))
 
                     x = x.to(w.dtype)
@@ -228,9 +219,7 @@ def _grouped_gemm_forward_kernel(
                 # Fusing before accumulator dtype conversion results in numerical diffs
                 if FUSE_MUL_POST:
                     # Check for correct broadcasting
-                    topk_weights = tl.load(
-                        topk_weights_ptr + topk_load_idx, mask = row_mask
-                    )
+                    topk_weights = tl.load(topk_weights_ptr + topk_load_idx, mask = row_mask)
                     y *= topk_weights.to(output_dtype)
 
                 offs_bn = tile_n_idx * BLOCK_SIZE_N + tl.arange(0, BLOCK_SIZE_N)
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py b/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
index 00d4824703..c1962c1116 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
@@ -63,7 +63,11 @@ class KernelConfig:
     fuse_mul_post: bool = False
     use_tma_store: bool = False
 
-    def to_string(self, include_tuning_params: bool = False, include_tma: bool = False):
+    def to_string(
+        self,
+        include_tuning_params: bool = False,
+        include_tma: bool = False,
+    ):
         s = []
         if self.permute_x:
             s.append("permute_x")
@@ -116,7 +120,9 @@ class KernelResult:
 
     @staticmethod
     def to_dataframe(
-        results: list["KernelResult"], sort_by: str = "speedup", ascending: bool = False
+        results: list["KernelResult"],
+        sort_by: str = "speedup",
+        ascending: bool = False,
     ):
         df = pd.DataFrame([result.to_dict() for result in results])
         df = df.sort_values(by = sort_by, ascending = ascending)
@@ -202,12 +208,8 @@ def get_kernel_configs(
         )
 
     kernel_configs_fwd = prune_kernel_configs_fwd(kernel_configs_fwd)
-    kernel_configs_backward_dW = prune_kernel_configs_backward_dW(
-        kernel_configs_backward_dW
-    )
-    kernel_configs_backward_dX = prune_kernel_configs_backward_dX(
-        kernel_configs_backward_dX
-    )
+    kernel_configs_backward_dW = prune_kernel_configs_backward_dW(kernel_configs_backward_dW)
+    kernel_configs_backward_dX = prune_kernel_configs_backward_dX(kernel_configs_backward_dX)
     return kernel_configs_fwd, kernel_configs_backward_dW, kernel_configs_backward_dX
 
 
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py b/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
index 6bb0bfb0c3..863765b0b8 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
@@ -75,9 +75,7 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
             self.experts.gate_up_proj.as_strided_(permuted_shape, permuted_stride)
 
         if verbose:
-            print(
-                f"{self.experts.gate_up_proj.shape}:{self.experts.gate_up_proj.stride()}"
-            )
+            print(f"{self.experts.gate_up_proj.shape}:{self.experts.gate_up_proj.stride()}")
 
         assert self.experts.down_proj.shape == torch.Size(
             [E, N, K]
@@ -110,9 +108,7 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
             if any(n in name for n in self.EXPERT_WEIGHT_NAMES):
                 param_to_copy = param_to_copy.permute(0, 2, 1)
 
-            assert (
-                param.shape == param_to_copy.shape
-            ), f"{param.shape} != {param_to_copy.shape}"
+            assert param.shape == param_to_copy.shape, f"{param.shape} != {param_to_copy.shape}"
             param.copy_(param_to_copy)
 
         return self
@@ -135,9 +131,7 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
         # router_logits: (batch * sequence_length, n_experts)
         hidden_states = hidden_states.view(-1, self.hidden_dim)
         router_logits = self.router(hidden_states)
-        routing_weights, selected_experts = torch.topk(
-            router_logits, self.top_k, dim = -1
-        )
+        routing_weights, selected_experts = torch.topk(router_logits, self.top_k, dim = -1)
 
         routing_weights = F.sigmoid(routing_weights.float()).to(hidden_states.dtype)
 
@@ -164,9 +158,7 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
             # Marker for all prior ops on default stream
             self.default_event.record()
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
         assert routing_weights.shape == (
             num_tokens,
             self.top_k,
@@ -190,8 +182,7 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
             shared_expert_out = self.shared_expert(hidden_states)
 
         hidden_states = (
-            hidden_states.view(num_tokens, self.top_k, hidden_dim)
-            * routing_weights[..., None]
+            hidden_states.view(num_tokens, self.top_k, hidden_dim) * routing_weights[..., None]
         )
 
         if self.top_k > 1:
@@ -200,14 +191,12 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
 
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. Permute tokens from token order to expert order
-        hidden_states = permute(
-            hidden_states_after_weight_merge, gather_indices, self.top_k
-        )
+        hidden_states = permute(hidden_states_after_weight_merge, gather_indices, self.top_k)
         assert hidden_states.shape == (total_tokens, hidden_dim)
 
         # Start expert computation
@@ -295,9 +284,7 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
             if any(n in name for n in self.EXPERT_WEIGHT_NAMES):
                 param_to_copy = param_to_copy.permute(0, 2, 1)
 
-            assert (
-                param.shape == param_to_copy.shape
-            ), f"{param.shape} != {param_to_copy.shape}"
+            assert param.shape == param_to_copy.shape, f"{param.shape} != {param_to_copy.shape}"
             param.copy_(param_to_copy)
 
         return self
@@ -320,9 +307,7 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
         # router_logits: (batch * sequence_length, n_experts)
         hidden_states = hidden_states.view(-1, self.hidden_dim)
         router_logits = self.router(hidden_states)
-        routing_weights, selected_experts = torch.topk(
-            router_logits, self.top_k, dim = -1
-        )
+        routing_weights, selected_experts = torch.topk(router_logits, self.top_k, dim = -1)
 
         routing_weights = F.sigmoid(routing_weights.float()).to(hidden_states.dtype)
 
@@ -349,9 +334,7 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
             # Marker for all prior ops on default stream
             self.default_event.record()
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
         assert routing_weights.shape == (
             num_tokens,
             self.top_k,
@@ -375,8 +358,7 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
             shared_expert_out = self.shared_expert(hidden_states)
 
         hidden_states = (
-            hidden_states.view(num_tokens, self.top_k, hidden_dim)
-            * routing_weights[..., None]
+            hidden_states.view(num_tokens, self.top_k, hidden_dim) * routing_weights[..., None]
         )
 
         if self.top_k > 1:
@@ -385,8 +367,8 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
 
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. Permute tokens from token order to expert order
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py b/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
index 31c635ba37..bd51cac377 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
@@ -49,11 +49,7 @@ class GroupedGEMMResult:
 
 class Qwen3MoeGroupedGEMMBlock(torch.nn.Module):
     def __init__(
-        self,
-        config,
-        gate: torch.Tensor,
-        gate_up_proj: torch.Tensor,
-        down_proj: torch.Tensor,
+        self, config, gate: torch.Tensor, gate_up_proj: torch.Tensor, down_proj: torch.Tensor
     ):
         super().__init__()
         self.num_experts = config.num_experts
@@ -133,9 +129,7 @@ class Qwen3MoeGroupedGEMMBlock(torch.nn.Module):
         router_logits = torch.nn.functional.linear(hidden_states, self.gate)
 
         routing_weights = F.softmax(router_logits, dim = 1, dtype = torch.float)
-        routing_weights, selected_experts = torch.topk(
-            routing_weights, self.top_k, dim = -1
-        )
+        routing_weights, selected_experts = torch.topk(routing_weights, self.top_k, dim = -1)
         if self.norm_topk_prob:  # only diff with mixtral sparse moe block!
             routing_weights /= routing_weights.sum(dim = -1, keepdim = True)
         # we cast back to the input dtype
@@ -161,14 +155,12 @@ class Qwen3MoeGroupedGEMMBlock(torch.nn.Module):
 
         hidden_states = hidden_states.view(-1, hidden_dim)
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
 
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. Permute tokens from token order to expert order
@@ -259,9 +251,7 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         dX_only: bool = False,
     ):
         config: Qwen3MoeConfig = moe_block.experts[0].config
-        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(
-            moe_block
-        )
+        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(moe_block)
         return cls(
             config,
             gate,
@@ -284,14 +274,12 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
 
         hidden_states = hidden_states.view(-1, hidden_dim)
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
         # Pre-processing
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. permute_x -> permutation will be fused in prologue of first grouped gemm
@@ -339,8 +327,7 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
 
         # 2. Merge topk weights
         hidden_states = (
-            hidden_states.view(num_tokens, self.top_k, hidden_dim)
-            * routing_weights[..., None]
+            hidden_states.view(num_tokens, self.top_k, hidden_dim) * routing_weights[..., None]
         )
         hidden_states = hidden_states.sum(dim = 1)
 
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/moe_block.py b/unsloth/kernels/moe/grouped_gemm/reference/moe_block.py
index 2a015252c6..2412425c1a 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/moe_block.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/moe_block.py
@@ -72,9 +72,7 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         dX_only: bool = False,
     ):
         config: Qwen3MoeConfig = moe_block.experts[0].config
-        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(
-            moe_block
-        )
+        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(moe_block)
         return cls(
             config,
             gate,
@@ -97,14 +95,12 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
 
         hidden_states = hidden_states.view(-1, hidden_dim)
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
         # Pre-processing
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. permute_x -> permutation will be fused in prologue of first grouped gemm
@@ -152,8 +148,7 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
 
         # 2. Merge topk weights
         hidden_states = (
-            hidden_states.view(num_tokens, self.top_k, hidden_dim)
-            * routing_weights[..., None]
+            hidden_states.view(num_tokens, self.top_k, hidden_dim) * routing_weights[..., None]
         )
         hidden_states = hidden_states.sum(dim = 1)
 
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/moe_ops.py b/unsloth/kernels/moe/grouped_gemm/reference/moe_ops.py
index 46d9c3c514..41866de347 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/moe_ops.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/moe_ops.py
@@ -52,13 +52,9 @@ def calculate_topk(
 
     def _activation(gating_output: torch.Tensor):
         if use_sigmoid:
-            scores = torch.sigmoid(gating_output.to(torch.float32)).to(
-                gating_output.dtype
-            )
+            scores = torch.sigmoid(gating_output.to(torch.float32)).to(gating_output.dtype)
         else:
-            scores = F.softmax(gating_output.to(torch.float32), dim = 1).to(
-                gating_output.dtype
-            )
+            scores = F.softmax(gating_output.to(torch.float32), dim = 1).to(gating_output.dtype)
 
         return scores
 
@@ -73,16 +69,16 @@ def calculate_topk(
         topk_weights = _activation(topk_weights)
 
     if renormalize:
-        topk_weights /= torch.sum(topk_weights, dim = -1, keepdim = True).to(
-            gating_output.dtype
-        )
+        topk_weights /= torch.sum(topk_weights, dim = -1, keepdim = True).to(gating_output.dtype)
 
     return topk_weights, topk_ids
 
 
 @torch.no_grad()
 def get_routing_indices(
-    selected_experts, num_experts, return_scatter_indices: bool = False
+    selected_experts,
+    num_experts,
+    return_scatter_indices: bool = False,
 ):
     """
     Returns:
@@ -107,7 +103,12 @@ def get_routing_indices(
         return token_counts_by_expert, gather_indices
 
 
-def torch_grouped_gemm(X, W, m_sizes, transpose = True):
+def torch_grouped_gemm(
+    X,
+    W,
+    m_sizes,
+    transpose = True,
+):
     """
     X: [M, K] if forward, else [M, N]
     W: [E, N, K]
diff --git a/unsloth/kernels/moe/tests/common.py b/unsloth/kernels/moe/tests/common.py
index bfe6f2094b..9d19fd4a18 100644
--- a/unsloth/kernels/moe/tests/common.py
+++ b/unsloth/kernels/moe/tests/common.py
@@ -29,27 +29,19 @@ def delimiter_context():
     print_delimiter()
 
 
-def make_inputs(M, N, K, E, topk, dtype, requires_grad = False):
-    X1 = (
-        torch.randn((M, K), device = "cuda", dtype = dtype, requires_grad = requires_grad)
-        / 10
-    )
-    X2 = (
-        torch.randn(
-            (M * topk, N), device = "cuda", dtype = dtype, requires_grad = requires_grad
-        )
-        / 10
-    )
-    W1 = (
-        torch.randn(
-            (E, 2 * N, K), device = "cuda", dtype = dtype, requires_grad = requires_grad
-        )
-        / 10
-    )
-    W2 = (
-        torch.randn((E, K, N), device = "cuda", dtype = dtype, requires_grad = requires_grad)
-        / 10
-    )
+def make_inputs(
+    M,
+    N,
+    K,
+    E,
+    topk,
+    dtype,
+    requires_grad = False,
+):
+    X1 = torch.randn((M, K), device = "cuda", dtype = dtype, requires_grad = requires_grad) / 10
+    X2 = torch.randn((M * topk, N), device = "cuda", dtype = dtype, requires_grad = requires_grad) / 10
+    W1 = torch.randn((E, 2 * N, K), device = "cuda", dtype = dtype, requires_grad = requires_grad) / 10
+    W2 = torch.randn((E, K, N), device = "cuda", dtype = dtype, requires_grad = requires_grad) / 10
     score = torch.randn((M, E), device = "cuda", dtype = dtype, requires_grad = requires_grad)
     if requires_grad:
         X1.retain_grad()
@@ -105,7 +97,14 @@ def assert_equal(ref, tri):
         assert ref == tri, f"ref not equal to tri {ref} != {tri}"
 
 
-def assert_close(ref, tri, maxtol = None, rmstol = None, description = "--", verbose = True):
+def assert_close(
+    ref,
+    tri,
+    maxtol = None,
+    rmstol = None,
+    description = "--",
+    verbose = True,
+):
     if tri.dtype.itemsize == 1:
         ref_as_type = ref.to(tri.dtype)
         if ref.dtype == tri.dtype:
@@ -124,16 +123,12 @@ def assert_close(ref, tri, maxtol = None, rmstol = None, description = "--", ver
     # cast to float32:
     ref = ref.to(torch.float32).detach()
     tri = tri.to(torch.float32).detach()
-    assert (
-        ref.shape == tri.shape
-    ), f"Tensors must have same size {ref.shape = } {tri.shape = }"
+    assert ref.shape == tri.shape, f"Tensors must have same size {ref.shape = } {tri.shape = }"
 
     # deal with infinite elements:
     inf_mask_ref = torch.isinf(ref)
     inf_mask_tri = torch.isinf(tri)
-    assert torch.equal(
-        inf_mask_ref, inf_mask_tri
-    ), "Tensor must have same infinite elements"
+    assert torch.equal(inf_mask_ref, inf_mask_tri), "Tensor must have same infinite elements"
     refn = torch.where(inf_mask_ref, 0, ref)
     trin = torch.where(inf_mask_tri, 0, tri)
 
@@ -150,14 +145,8 @@ def assert_close(ref, tri, maxtol = None, rmstol = None, description = "--", ver
     rms_err = torch.sqrt(torch.square(rel_err).mean()).item()
 
     if verbose:
-        print(
-            "%s maximum relative error = %s (threshold = %s)"
-            % (description, max_err, maxtol)
-        )
-        print(
-            "%s RMS relative error = %s (threshold = %s)"
-            % (description, rms_err, rmstol)
-        )
+        print("%s maximum relative error = %s (threshold = %s)" % (description, max_err, maxtol))
+        print("%s RMS relative error = %s (threshold = %s)" % (description, rms_err, rmstol))
 
     if max_err > maxtol:
         bad_idxs = torch.nonzero(rel_err > maxtol)
@@ -296,9 +285,7 @@ SMALL_MODEL_CONFIGS = [
         use_sigmoid = False,
         renormalize = False,
     )
-    for topk, num_experts, model_size in itertools.product(
-        TOPK, NUM_EXPERTS, TEST_MODEL_SIZES
-    )
+    for topk, num_experts, model_size in itertools.product(TOPK, NUM_EXPERTS, TEST_MODEL_SIZES)
 ]
 LLAMA_MODEL_CONFIG = ModelConfig(
     topk = 1,
@@ -321,16 +308,9 @@ SEQLENS = [128, 1024]
 DTYPE = [torch.bfloat16]
 
 DATA_CONFIGS = [
-    DataConfig(seq_len = seq_len, dtype = dtype)
-    for seq_len, dtype in itertools.product(SEQLENS, DTYPE)
+    DataConfig(seq_len = seq_len, dtype = dtype) for seq_len, dtype in itertools.product(SEQLENS, DTYPE)
 ]
-KERNEL_CONFIGS_FWD, KERNEL_CONFIGS_BWD_dX, KERNEL_CONFIGS_BWD_dW = (
-    get_kernel_test_configs()
-)
+KERNEL_CONFIGS_FWD, KERNEL_CONFIGS_BWD_dX, KERNEL_CONFIGS_BWD_dW = get_kernel_test_configs()
 
 if __name__ == "__main__":
-    print(
-        KERNEL_CONFIGS_BWD_dX[0].to_string(
-            include_tuning_params = False, include_tma = False
-        )
-    )
+    print(KERNEL_CONFIGS_BWD_dX[0].to_string(include_tuning_params = False, include_tma = False))
diff --git a/unsloth/kernels/moe/tests/moe_utils.py b/unsloth/kernels/moe/tests/moe_utils.py
index 26ac9fdb5e..71f5873510 100644
--- a/unsloth/kernels/moe/tests/moe_utils.py
+++ b/unsloth/kernels/moe/tests/moe_utils.py
@@ -23,24 +23,16 @@ from grouped_gemm.reference.layers.qwen3_moe import (
 from grouped_gemm.reference.moe_ops import permute, unpermute
 
 
-def rebind_experts_to_shared_buffer(
-    moe_block: Qwen3MoeSparseMoeBlock, config: Qwen3MoeConfig
-):
+def rebind_experts_to_shared_buffer(moe_block: Qwen3MoeSparseMoeBlock, config: Qwen3MoeConfig):
     num_experts = config.num_experts
     hidden_size = config.hidden_size
     interm_size = config.moe_intermediate_size
     device = moe_block.experts[0].down_proj.weight.device
     dtype = moe_block.experts[0].down_proj.weight.dtype
 
-    buffer_up = torch.empty(
-        num_experts, interm_size, hidden_size, device = device, dtype = dtype
-    )
-    buffer_gate = torch.empty(
-        num_experts, interm_size, hidden_size, device = device, dtype = dtype
-    )
-    buffer_down = torch.empty(
-        num_experts, hidden_size, interm_size, device = device, dtype = dtype
-    )
+    buffer_up = torch.empty(num_experts, interm_size, hidden_size, device = device, dtype = dtype)
+    buffer_gate = torch.empty(num_experts, interm_size, hidden_size, device = device, dtype = dtype)
+    buffer_down = torch.empty(num_experts, hidden_size, interm_size, device = device, dtype = dtype)
 
     # Step 2: Copy existing expert weights into buffers
     for i, expert in enumerate(moe_block.experts):
@@ -59,24 +51,18 @@ def rebind_experts_to_shared_buffer(
 
 def get_expert_metadata(model_id: str):
     api = HfApi()
-    metadata: _safetensors.SafetensorsRepoMetadata = api.get_safetensors_metadata(
-        model_id
-    )
+    metadata: _safetensors.SafetensorsRepoMetadata = api.get_safetensors_metadata(model_id)
     return metadata.files_metadata
 
 
 def clone_experts(
-    moe_block: Qwen3MoeSparseMoeBlock, config: Qwen3MoeConfig, copy: bool = True
+    moe_block: Qwen3MoeSparseMoeBlock,
+    config: Qwen3MoeConfig,
+    copy: bool = True,
 ):
-    down_projs = torch.empty(
-        config.num_experts, config.hidden_size, config.moe_intermediate_size
-    )
-    up_projs = torch.empty(
-        config.num_experts, config.moe_intermediate_size, config.hidden_size
-    )
-    gate_projs = torch.empty(
-        config.num_experts, config.moe_intermediate_size, config.hidden_size
-    )
+    down_projs = torch.empty(config.num_experts, config.hidden_size, config.moe_intermediate_size)
+    up_projs = torch.empty(config.num_experts, config.moe_intermediate_size, config.hidden_size)
+    gate_projs = torch.empty(config.num_experts, config.moe_intermediate_size, config.hidden_size)
     for expert_idx, expert in enumerate(moe_block.experts):
         down_projs[expert_idx].copy_(expert.down_proj.weight.data)
         up_projs[expert_idx].copy_(expert.up_proj.weight.data)
@@ -132,12 +118,8 @@ def check_gate_up_proj_grad(
         assert ref_up_proj_grad is not None
 
         # Extract gradients
-        test_gate_proj_grad = grouped_gemm_block.gate_up_proj.grad[
-            i, :moe_intermediate_size
-        ]
-        test_up_proj_grad = grouped_gemm_block.gate_up_proj.grad[
-            i, moe_intermediate_size:
-        ]
+        test_gate_proj_grad = grouped_gemm_block.gate_up_proj.grad[i, :moe_intermediate_size]
+        test_up_proj_grad = grouped_gemm_block.gate_up_proj.grad[i, moe_intermediate_size:]
         assert test_gate_proj_grad is not None
         assert test_up_proj_grad is not None
 
@@ -151,14 +133,10 @@ def check_gate_up_proj_grad(
 
         # Check gradients
         diff = (ref_gate_proj_grad - test_gate_proj_grad).abs().max()
-        if not torch.allclose(
-            ref_gate_proj_grad, test_gate_proj_grad, atol = atol, rtol = rtol
-        ):
+        if not torch.allclose(ref_gate_proj_grad, test_gate_proj_grad, atol = atol, rtol = rtol):
             print(f"expert {i} gate_proj_grad_diff: {diff.detach().cpu().item():.6f}")
         diff = (ref_up_proj_grad - test_up_proj_grad).abs().max()
-        if not torch.allclose(
-            ref_up_proj_grad, test_up_proj_grad, atol = atol, rtol = rtol
-        ):
+        if not torch.allclose(ref_up_proj_grad, test_up_proj_grad, atol = atol, rtol = rtol):
             print(f"expert {i} up_proj_grad_diff: {diff.detach().cpu().item():.6f}")
 
 
@@ -246,9 +224,7 @@ def check_grads(
     rtol: float,
     verbose: bool = False,
 ):
-    check_tensor_allclose(
-        ref_result.X_grad, test_result.X_grad, atol, rtol, "X.grad", verbose
-    )
+    check_tensor_allclose(ref_result.X_grad, test_result.X_grad, atol, rtol, "X.grad", verbose)
     check_tensor_allclose(
         ref_result.gate_grad, test_result.gate_grad, atol, rtol, "gate.grad", verbose
     )
@@ -309,7 +285,11 @@ def check_grouped_gemm_results(
         ), f"{field.name} diff: {diff.detach().cpu().item():.6f}"
 
 
-def run_forward(model: nn.Module, X: torch.Tensor, is_grouped_gemm: bool = False):
+def run_forward(
+    model: nn.Module,
+    X: torch.Tensor,
+    is_grouped_gemm: bool = False,
+):
     X = X.detach().clone().requires_grad_(True)
     output, router_logits = model(X)
     if is_grouped_gemm:
@@ -333,15 +313,9 @@ def run_backward(
         assert param.grad is not None, f"{name} grad is None"
     if isinstance(model, Qwen3MoeSparseMoeBlock):
         gate_grad = model.gate.weight.grad
-        gate_proj_grad = torch.stack(
-            [expert.gate_proj.weight.grad for expert in model.experts]
-        )
-        up_proj_grad = torch.stack(
-            [expert.up_proj.weight.grad for expert in model.experts]
-        )
-        down_proj_grad = torch.stack(
-            [expert.down_proj.weight.grad for expert in model.experts]
-        )
+        gate_proj_grad = torch.stack([expert.gate_proj.weight.grad for expert in model.experts])
+        up_proj_grad = torch.stack([expert.up_proj.weight.grad for expert in model.experts])
+        down_proj_grad = torch.stack([expert.down_proj.weight.grad for expert in model.experts])
     elif isinstance(model, Qwen3MoeGroupedGEMMBlock):
         gate_grad = model.gate.grad
         gate_proj_grad, up_proj_grad = model.gate_up_proj.grad.chunk(2, dim = 1)
@@ -406,9 +380,7 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         kernel_config_bwd_dX: KernelConfigBackward_dX = None,
     ):
         config: Qwen3MoeConfig = moe_block.experts[0].config
-        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(
-            moe_block
-        )
+        gate, gate_up_proj, down_proj = Qwen3MoeGroupedGEMMBlock.extract_hf_weights(moe_block)
         return cls(
             config,
             gate,
@@ -422,21 +394,23 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
             kernel_config_bwd_dX = kernel_config_bwd_dX,
         )
 
-    def forward(self, hidden_states: torch.Tensor, debug: bool = False) -> torch.Tensor:
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        debug: bool = False,
+    ) -> torch.Tensor:
         batch_size, sequence_length, hidden_dim = hidden_states.shape
         num_tokens = batch_size * sequence_length
         total_tokens = num_tokens * self.top_k
 
         hidden_states = hidden_states.view(-1, hidden_dim)
 
-        router_logits, routing_weights, selected_experts = self.run_router(
-            hidden_states
-        )
+        router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
         # Pre-processing
         # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
         # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
-        token_counts_by_expert, gather_indices = (
-            self.get_token_counts_and_gather_indices(selected_experts)
+        token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
+            selected_experts
         )
 
         # 2. permute_x -> permutation will be fused in prologue of first grouped gemm
diff --git a/unsloth/kernels/moe/tests/test_grouped_gemm.py b/unsloth/kernels/moe/tests/test_grouped_gemm.py
index bd98b6a276..35de6fca51 100644
--- a/unsloth/kernels/moe/tests/test_grouped_gemm.py
+++ b/unsloth/kernels/moe/tests/test_grouped_gemm.py
@@ -50,7 +50,12 @@ SEED = 0
 # permute_y => permute the output of the grouped GEMM, only done for the second grouped GEMM
 # fuse_mul_post => fuse the multiplication of topk weights in the epilogue of the second grouped GEMM; only used for inference, not currently tested
 def check_valid_config(
-    permute_x, permute_y, use_W1, fuse_mul_post = False, is_backward = False, verbose = False
+    permute_x,
+    permute_y,
+    use_W1,
+    fuse_mul_post = False,
+    is_backward = False,
+    verbose = False,
 ):
     use_W2 = not use_W1
 
@@ -121,9 +126,7 @@ def _test_grouped_gemm_forward(
     allow_tma_store: bool = False,
     use_autograd: bool = False,
 ):
-    if not check_valid_config(
-        permute_x, permute_y, use_W1 = use_W1, fuse_mul_post = fuse_mul_post
-    ):
+    if not check_valid_config(permute_x, permute_y, use_W1 = use_W1, fuse_mul_post = fuse_mul_post):
         pytest.skip(
             f"Skipping test due to invalid config: {permute_x = } {permute_y = } {use_W1 = } {fuse_mul_post = }"
         )
@@ -193,7 +196,6 @@ def _test_grouped_gemm_forward(
     # No need to run all configs for tests, otherwise takes too long
     if autotune:
         from grouped_gemm.kernels.forward import _autotuned_grouped_gemm_forward_kernel
-
         if num_autotune_configs is not None:
             _autotuned_grouped_gemm_forward_kernel.configs = (
                 _autotuned_grouped_gemm_forward_kernel.configs[:num_autotune_configs]
@@ -202,7 +204,6 @@ def _test_grouped_gemm_forward(
     # Use autograd.Function interface
     if use_autograd:
         from grouped_gemm.interface import grouped_gemm
-
         kernel_config_fwd = KernelConfigForward(
             BLOCK_SIZE_M = BLOCK_SIZE_M,
             BLOCK_SIZE_N = BLOCK_SIZE_N,
@@ -330,15 +331,9 @@ def test_grouped_gemm_forward_manual_autograd(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [10], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [10], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
@@ -368,15 +363,9 @@ def test_grouped_gemm_forward_autotune(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [10], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [10], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
@@ -469,11 +458,7 @@ def _test_grouped_gemm_backward_dX(
     if use_tma_store and not allow_tma_store:
         pytest.skip("TMA store needs to be debugged due to non-deterministic behavior")
 
-    if (
-        autotune
-        and model_config.intermediate_size <= 128
-        and model_config.hidden_size <= 128
-    ):
+    if autotune and model_config.intermediate_size <= 128 and model_config.hidden_size <= 128:
         pytest.skip("Skipping autotuning for small model configs")
 
     # Prevent OOM for large intermediate sizes
@@ -558,11 +543,10 @@ def _test_grouped_gemm_backward_dX(
     if autotune:
         # No need to run all configs for autotuning
         from grouped_gemm.kernels.backward import _autotuned_grouped_gemm_dX_kernel
-
         if num_autotune_configs is not None:
-            _autotuned_grouped_gemm_dX_kernel.configs = (
-                _autotuned_grouped_gemm_dX_kernel.configs[:num_autotune_configs]
-            )
+            _autotuned_grouped_gemm_dX_kernel.configs = _autotuned_grouped_gemm_dX_kernel.configs[
+                :num_autotune_configs
+            ]
 
     if use_autograd:
         from grouped_gemm.interface import grouped_gemm
@@ -594,9 +578,7 @@ def _test_grouped_gemm_backward_dX(
                     _autotuned_grouped_gemm_dX_kernel.configs[:num_autotune_configs]
                 )
                 _autotuned_grouped_gemm_forward_kernel.configs = (
-                    _autotuned_grouped_gemm_forward_kernel.configs[
-                        :num_autotune_configs
-                    ]
+                    _autotuned_grouped_gemm_forward_kernel.configs[:num_autotune_configs]
                 )
 
             kernel_config_fwd = None
@@ -761,15 +743,9 @@ def test_grouped_gemm_backward_dX_manual_autograd(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
@@ -800,15 +776,9 @@ def test_grouped_gemm_backward_dX_autotune(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
@@ -957,11 +927,10 @@ def _test_grouped_gemm_backward_dW(
 
     if autotune:
         from grouped_gemm.kernels.backward import _autotuned_grouped_gemm_dW_kernel
-
         if num_autotune_configs is not None:
-            _autotuned_grouped_gemm_dW_kernel.configs = (
-                _autotuned_grouped_gemm_dW_kernel.configs[:num_autotune_configs]
-            )
+            _autotuned_grouped_gemm_dW_kernel.configs = _autotuned_grouped_gemm_dW_kernel.configs[
+                :num_autotune_configs
+            ]
 
     if use_autograd:
         from grouped_gemm.interface import grouped_gemm
@@ -996,9 +965,7 @@ def _test_grouped_gemm_backward_dW(
 
             if num_autotune_configs is not None:
                 _autotuned_grouped_gemm_forward_kernel.configs = (
-                    _autotuned_grouped_gemm_forward_kernel.configs[
-                        :num_autotune_configs
-                    ]
+                    _autotuned_grouped_gemm_forward_kernel.configs[:num_autotune_configs]
                 )
                 _autotuned_grouped_gemm_dW_kernel.configs = (
                     _autotuned_grouped_gemm_dW_kernel.configs[:num_autotune_configs]
@@ -1067,9 +1034,7 @@ def _test_grouped_gemm_backward_dW(
                 print(f"Expert {i} diff: {expert_diff:.6f}")
 
             diff = (W.grad - dW_test).abs().max().item()
-            assert (
-                False
-            ), f"Grouped gemm manual backward_dW outputs mismatch: {diff:.6f}"
+            assert False, f"Grouped gemm manual backward_dW outputs mismatch: {diff:.6f}"
     else:
         diff = (W.grad - dW_test).abs().max().item()
         assert torch.allclose(
@@ -1137,15 +1102,9 @@ def test_grouped_gemm_backward_dW_manual_autograd(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
@@ -1175,15 +1134,9 @@ def test_grouped_gemm_backward_dW_autotune(
     )
 
 
-@pytest.mark.parametrize(
-    "num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True, False], ids = lambda x: "permute_x" if x else ""
-)
-@pytest.mark.parametrize(
-    "permute_y", [True, False], ids = lambda x: "permute_y" if x else ""
-)
+@pytest.mark.parametrize("num_autotune_configs", [20], ids = lambda x: f"num_autotune_configs={x}")
+@pytest.mark.parametrize("permute_x", [True, False], ids = lambda x: "permute_x" if x else "")
+@pytest.mark.parametrize("permute_y", [True, False], ids = lambda x: "permute_y" if x else "")
 @pytest.mark.parametrize(
     "model_config",
     [LLAMA_MODEL_CONFIG, QWEN_MODEL_CONFIG],
diff --git a/unsloth/kernels/moe/tests/test_llama4_moe.py b/unsloth/kernels/moe/tests/test_llama4_moe.py
index 13ad552bf4..ccc04b692a 100644
--- a/unsloth/kernels/moe/tests/test_llama4_moe.py
+++ b/unsloth/kernels/moe/tests/test_llama4_moe.py
@@ -37,7 +37,12 @@ NUM_AUTOTUNE_CONFIGS = 50
 
 
 @contextmanager
-def annotated_context(prelude, epilogue = "Passed!", char = "-", num_chars = 80):
+def annotated_context(
+    prelude,
+    epilogue = "Passed!",
+    char = "-",
+    num_chars = 80,
+):
     print(char * num_chars)
     print(prelude)
     yield
@@ -66,12 +71,12 @@ def prep_triton_kernel_traits(autotune):
         _autotuned_grouped_gemm_forward_kernel.configs = (
             _autotuned_grouped_gemm_forward_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
         )
-        _autotuned_grouped_gemm_dW_kernel.configs = (
-            _autotuned_grouped_gemm_dW_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
-        )
-        _autotuned_grouped_gemm_dX_kernel.configs = (
-            _autotuned_grouped_gemm_dX_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
-        )
+        _autotuned_grouped_gemm_dW_kernel.configs = _autotuned_grouped_gemm_dW_kernel.configs[
+            :NUM_AUTOTUNE_CONFIGS
+        ]
+        _autotuned_grouped_gemm_dX_kernel.configs = _autotuned_grouped_gemm_dX_kernel.configs[
+            :NUM_AUTOTUNE_CONFIGS
+        ]
 
         kernel_config_fwd = None
         kernel_config_bwd_dW = None
@@ -147,9 +152,7 @@ def model_config():
 @pytest.mark.parametrize(
     "permute_x", [False], ids = lambda x: "permute_x" if x else "no_permute_x"
 )  # Llama4 does not support permute_x
-@pytest.mark.parametrize(
-    "autotune", [True], ids = lambda x: "autotune" if x else "manual"
-)
+@pytest.mark.parametrize("autotune", [True], ids = lambda x: "autotune" if x else "manual")
 @pytest.mark.parametrize("seqlen", SEQ_LENS, ids = lambda x: f"seqlen={x}")
 @pytest.mark.parametrize("dtype", DTYPES, ids = str)
 def test_llama4_ref(
@@ -171,12 +174,8 @@ def test_llama4_ref(
     device = "cuda"
     hidden_dim = model_config.hidden_size
     atol, rtol = TOLERANCES[dtype]
-    check_diff = partial(
-        _check_diff, atol = atol, rtol = rtol, precision = precision, verbose = verbose
-    )
-    check_grads = partial(
-        _check_grads, atol = atol, rtol = rtol, precision = precision, verbose = verbose
-    )
+    check_diff = partial(_check_diff, atol = atol, rtol = rtol, precision = precision, verbose = verbose)
+    check_grads = partial(_check_grads, atol = atol, rtol = rtol, precision = precision, verbose = verbose)
 
     # Reference op -- HF
     llama4_ref = Llama4TextMoe(model_config).to(dtype = dtype, device = device)
@@ -188,9 +187,7 @@ def test_llama4_ref(
     llama4_gg_ref.copy_weights(llama4_ref)
     llama4_gg_ref.check_weights(llama4_ref)
 
-    x_ref = torch.randn(
-        bs, seqlen, hidden_dim, dtype = dtype, device = device, requires_grad = True
-    )
+    x_ref = torch.randn(bs, seqlen, hidden_dim, dtype = dtype, device = device, requires_grad = True)
     x_torch_gg = x_ref.detach().clone().requires_grad_()
     x_triton = x_ref.detach().clone().requires_grad_()
 
@@ -199,12 +196,10 @@ def test_llama4_ref(
     assert y_ref.shape == y_torch_gg.shape, f"{y_ref.shape} != {y_torch_gg.shape}"
     with annotated_context("Testing torch grouped gemm Llama4TextMoe"):
         check_diff(y_ref, y_torch_gg, msg = "y_torch_gg")
-        check_diff(
-            sparse_to_dense(routing_ref), routing_torch_gg, msg = "routing_torch_gg"
-        )
+        check_diff(sparse_to_dense(routing_ref), routing_torch_gg, msg = "routing_torch_gg")
 
-    kernel_config_fwd, kernel_config_bwd_dW, kernel_config_bwd_dX = (
-        prep_triton_kernel_traits(autotune)
+    kernel_config_fwd, kernel_config_bwd_dW, kernel_config_bwd_dX = prep_triton_kernel_traits(
+        autotune
     )
 
     llama4_triton = Llama4TritonTextMoe(
@@ -239,9 +234,7 @@ def test_llama4_ref(
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
     parser.add_argument("--seqlen", type = int, default = 1024)
-    parser.add_argument(
-        "--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16"
-    )
+    parser.add_argument("--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16")
     args = parser.parse_args()
     args.dtype = getattr(torch, args.dtype)
     args_dict = vars(args)
diff --git a/unsloth/kernels/moe/tests/test_qwen3_moe.py b/unsloth/kernels/moe/tests/test_qwen3_moe.py
index 42a8356c09..c601ebcfc7 100644
--- a/unsloth/kernels/moe/tests/test_qwen3_moe.py
+++ b/unsloth/kernels/moe/tests/test_qwen3_moe.py
@@ -79,7 +79,12 @@ def config(model_id: str):
 
 
 @contextmanager
-def annotated_context(prelude, epilogue = "Passed!", char = "-", num_chars = 80):
+def annotated_context(
+    prelude,
+    epilogue = "Passed!",
+    char = "-",
+    num_chars = 80,
+):
     print(char * num_chars)
     print(prelude)
     yield
@@ -95,15 +100,9 @@ DTYPES = [torch.bfloat16]
 NUM_AUTOTUNE_CONFIGS = 50
 
 
-@pytest.mark.parametrize(
-    "permute_y", [True], ids = lambda x: "permute_y" if x else "no_permute_y"
-)
-@pytest.mark.parametrize(
-    "permute_x", [True], ids = lambda x: "permute_x" if x else "no_permute_x"
-)
-@pytest.mark.parametrize(
-    "autotune", [True], ids = lambda x: "autotune" if x else "manual"
-)
+@pytest.mark.parametrize("permute_y", [True], ids = lambda x: "permute_y" if x else "no_permute_y")
+@pytest.mark.parametrize("permute_x", [True], ids = lambda x: "permute_x" if x else "no_permute_x")
+@pytest.mark.parametrize("autotune", [True], ids = lambda x: "autotune" if x else "manual")
 @pytest.mark.parametrize("seqlen", SEQ_LENS, ids = lambda x: f"seqlen={x}")
 @pytest.mark.parametrize("dtype", DTYPES, ids = str)
 def test_qwen3_moe(
@@ -143,12 +142,12 @@ def test_qwen3_moe(
         _autotuned_grouped_gemm_forward_kernel.configs = (
             _autotuned_grouped_gemm_forward_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
         )
-        _autotuned_grouped_gemm_dW_kernel.configs = (
-            _autotuned_grouped_gemm_dW_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
-        )
-        _autotuned_grouped_gemm_dX_kernel.configs = (
-            _autotuned_grouped_gemm_dX_kernel.configs[:NUM_AUTOTUNE_CONFIGS]
-        )
+        _autotuned_grouped_gemm_dW_kernel.configs = _autotuned_grouped_gemm_dW_kernel.configs[
+            :NUM_AUTOTUNE_CONFIGS
+        ]
+        _autotuned_grouped_gemm_dX_kernel.configs = _autotuned_grouped_gemm_dX_kernel.configs[
+            :NUM_AUTOTUNE_CONFIGS
+        ]
 
         kernel_config_fwd = None
         kernel_config_bwd_dW = None
@@ -166,9 +165,7 @@ def test_qwen3_moe(
     ).to(device, dtype)
     fused_gemm_block.check_weights(moe_block)
 
-    X = torch.randn(
-        bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True
-    )
+    X = torch.randn(bs, seqlen, hidden_size, dtype = dtype, device = device, requires_grad = True)
 
     # Forward
     ref_result = run_forward(moe_block, X, is_grouped_gemm = False)
@@ -183,9 +180,7 @@ def test_qwen3_moe(
     ):
         # Sanity checks
 
-        with annotated_context(
-            "Checking HF vs torch grouped gemm MoE forward outputs..."
-        ):
+        with annotated_context("Checking HF vs torch grouped gemm MoE forward outputs..."):
             check_fwd(ref_result, grouped_result, atol, rtol, verbose = False)
 
         with annotated_context(
@@ -201,9 +196,7 @@ def test_qwen3_moe(
                 verbose = False,
             )
         # Actual test
-        with annotated_context(
-            "Checking HF vs fused grouped gemm MoE forward outputs..."
-        ):
+        with annotated_context("Checking HF vs fused grouped gemm MoE forward outputs..."):
             check_fwd(ref_result, fused_result, atol, rtol, verbose = True)
 
     # Backward
@@ -229,9 +222,7 @@ def test_qwen3_moe(
     ):
         # Sanity checks
         with annotated_context("Checking HF vs torch grouped gemm MoE grads..."):
-            check_grads(
-                ref_backward_result, grouped_backward_result, atol, rtol, verbose = False
-            )
+            check_grads(ref_backward_result, grouped_backward_result, atol, rtol, verbose = False)
         with annotated_context(
             "Checking torch grouped gemm MoE vs fused grouped gemm MoE grads..."
         ):
@@ -245,17 +236,13 @@ def test_qwen3_moe(
 
         # Actual test
         with annotated_context("Checking HF vs fused grouped gemm MoE grads..."):
-            check_grads(
-                ref_backward_result, fused_backward_result, atol, rtol, verbose = True
-            )
+            check_grads(ref_backward_result, fused_backward_result, atol, rtol, verbose = True)
 
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
     parser.add_argument("--seqlen", type = int, default = 1024)
-    parser.add_argument(
-        "--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16"
-    )
+    parser.add_argument("--dtype", type = str, choices = ["bfloat16", "float16"], default = "bfloat16")
     parser.add_argument("--permute_x", action = "store_true")
     parser.add_argument("--permute_y", action = "store_true")
     parser.add_argument("--autotune", action = "store_true")
diff --git a/unsloth/kernels/rms_layernorm.py b/unsloth/kernels/rms_layernorm.py
index 74c16c1e63..bc81c5533a 100644
--- a/unsloth/kernels/rms_layernorm.py
+++ b/unsloth/kernels/rms_layernorm.py
@@ -161,7 +161,13 @@ def _gemma_rms_layernorm_forward(
 
 class Fast_RMS_Layernorm(torch.autograd.Function):
     @staticmethod
-    def forward(ctx, X: torch.Tensor, W: torch.Tensor, eps: float, gemma: bool = False):
+    def forward(
+        ctx,
+        X: torch.Tensor,
+        W: torch.Tensor,
+        eps: float,
+        gemma: bool = False,
+    ):
         shape = X.shape
         dim: int = shape[-1]
         X = X.reshape(-1, dim)
@@ -236,12 +242,14 @@ class Fast_RMS_Layernorm(torch.autograd.Function):
 
 # [TODO] Unsure why RMS Layernorm is not torch.compiling properly
 @torch.compiler.disable
-def fast_rms_layernorm(layernorm, X: torch.Tensor, gemma: bool = False):
+def fast_rms_layernorm(
+    layernorm,
+    X: torch.Tensor,
+    gemma: bool = False,
+):
     W: torch.Tensor = layernorm.weight
     eps: float = (
-        layernorm.variance_epsilon
-        if hasattr(layernorm, "variance_epsilon")
-        else layernorm.eps
+        layernorm.variance_epsilon if hasattr(layernorm, "variance_epsilon") else layernorm.eps
     )
     out = Fast_RMS_Layernorm.apply(X, W, eps, gemma)
     return out
@@ -257,7 +265,6 @@ class Unsloth_LlamaRMSNorm(LlamaRMSNorm):
 
 try:
     from transformers.models.mllama.modeling_mllama import MllamaTextRMSNorm
-
     class Unsloth_MllamaTextRMSNorm(MllamaTextRMSNorm):
         def forward(self, X):
             return fast_rms_layernorm(self, X, gemma = False)
@@ -273,10 +280,7 @@ def patch_rms_layernorm():
     transformers.models.llama.modeling_llama.LlamaRMSNorm = Unsloth_LlamaRMSNorm
     try:
         import transformers.models.mllama.modeling_mllama
-
-        transformers.models.mllama.modeling_mllama.MllamaTextRMSNorm = (
-            Unsloth_MllamaTextRMSNorm
-        )
+        transformers.models.mllama.modeling_mllama.MllamaTextRMSNorm = Unsloth_MllamaTextRMSNorm
     except:
         pass
     return
@@ -288,7 +292,6 @@ def unpatch_rms_layernorm():
     transformers.models.llama.modeling_llama.LlamaRMSNorm = LlamaRMSNorm
     try:
         import transformers.models.mllama.modeling_mllama
-
         transformers.models.mllama.modeling_mllama.MllamaTextRMSNorm = MllamaTextRMSNorm
     except:
         pass
diff --git a/unsloth/kernels/rope_embedding.py b/unsloth/kernels/rope_embedding.py
index fcc9cb923b..7acab02e8e 100644
--- a/unsloth/kernels/rope_embedding.py
+++ b/unsloth/kernels/rope_embedding.py
@@ -73,12 +73,7 @@ def _rope_embedding_QK(
     batch_id = row_position // seqlen
     seq_index = row_position - batch_id * seqlen
 
-    q_ptr = (
-        Q
-        + batch_id * Q_batch_stride
-        + head_position * Q_head_stride
-        + seq_index * Q_seq_stride
-    )
+    q_ptr = Q + batch_id * Q_batch_stride + head_position * Q_head_stride + seq_index * Q_seq_stride
     q0 = tl.load(q_ptr + col_offsets, mask = mask, other = 0)
     q1 = tl.load(q_ptr + half_head_dim + col_offsets, mask = mask, other = 0)
     tl.store(q_ptr + col_offsets, q0 * cos1 - q1 * sin1, mask = mask)
@@ -86,10 +81,7 @@ def _rope_embedding_QK(
 
     if head_position < n_heads_K:
         k_ptr = (
-            K
-            + batch_id * K_batch_stride
-            + head_position * K_head_stride
-            + seq_index * K_seq_stride
+            K + batch_id * K_batch_stride + head_position * K_head_stride + seq_index * K_seq_stride
         )
         k0 = tl.load(k_ptr + col_offsets, mask = mask, other = 0)
         k1 = tl.load(k_ptr + half_head_dim + col_offsets, mask = mask, other = 0)
@@ -135,18 +127,12 @@ def _rope_embedding(
     mask = col_offsets < half_head_dim
 
     sin1 = tl.load(
-        sin
-        + (row_position % seqlen) * sin_row_stride
-        + half_head_dim * 0
-        + col_offsets,
+        sin + (row_position % seqlen) * sin_row_stride + half_head_dim * 0 + col_offsets,
         mask = mask,
         other = 0,
     )
     cos1 = tl.load(
-        cos
-        + (row_position % seqlen) * cos_row_stride
-        + half_head_dim * 0
-        + col_offsets,
+        cos + (row_position % seqlen) * cos_row_stride + half_head_dim * 0 + col_offsets,
         mask = mask,
         other = 0,
     )
@@ -162,9 +148,7 @@ def _rope_embedding(
     # 10% Faster kernel from [HuyNguyen-hust](https://github.com/unslothai/unsloth/pull/238)
     for k in range(head_start, head_end):
         offs_q1 = row_position * Q_row_stride + k * head_dim + col_offsets
-        offs_q2 = (
-            row_position * Q_row_stride + k * head_dim + col_offsets + half_head_dim
-        )
+        offs_q2 = row_position * Q_row_stride + k * head_dim + col_offsets + half_head_dim
 
         # For Gemma - sometimes RoPE must be done in float32 and not bfloat16
         Q1 = tl.load(Q + offs_q1, mask = mask, other = 0).to(sin1.dtype)
@@ -287,16 +271,10 @@ def fast_rope_embedding(
     rope_embedding_indices = None,
 ):
     if rope_embedding_indices is not None:
-        Q_out, K_out = Fast_RoPE_Embedding_QK.apply(
-            Q, K, cos, sin, rope_embedding_indices
-        )
+        Q_out, K_out = Fast_RoPE_Embedding_QK.apply(Q, K, cos, sin, rope_embedding_indices)
     else:
-        Q_out = Fast_RoPE_Embedding.apply(
-            Q.transpose(1, 2).contiguous(), cos, sin
-        ).transpose(1, 2)
-        K_out = Fast_RoPE_Embedding.apply(
-            K.transpose(1, 2).contiguous(), cos, sin
-        ).transpose(1, 2)
+        Q_out = Fast_RoPE_Embedding.apply(Q.transpose(1, 2).contiguous(), cos, sin).transpose(1, 2)
+        K_out = Fast_RoPE_Embedding.apply(K.transpose(1, 2).contiguous(), cos, sin).transpose(1, 2)
     if DEVICE_COUNT > 1:
         torch_device_stream(Q.device).synchronize()
     return Q_out, K_out
@@ -377,11 +355,7 @@ class Fast_RoPE_Embedding_QK(torch.autograd.Function):
     def backward(ctx, dQ, dK):
         batch, _, _, head_dim = dQ.shape
 
-        rope_ptr = (
-            ctx.rope_indices
-            if ctx.has_indices
-            else ctx.cos.new_empty(1, dtype = torch.int32)
-        )
+        rope_ptr = ctx.rope_indices if ctx.has_indices else ctx.cos.new_empty(1, dtype = torch.int32)
 
         # Inplace rotary embedding is generally fine
         dQ_out = dQ.clone() if not dQ.is_contiguous() else dQ
diff --git a/unsloth/kernels/swiglu.py b/unsloth/kernels/swiglu.py
index b3ae9d40e6..6d74a868fe 100644
--- a/unsloth/kernels/swiglu.py
+++ b/unsloth/kernels/swiglu.py
@@ -25,19 +25,10 @@ INT32_SAFETY_BUFFER = NUM_INT32_ELEMENTS - BLOCK_SIZE * SAFE_INT32_BUFFER_MULTIP
 
 
 @triton.jit
-def _fg_kernel(
-    e,
-    g,
-    h,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
-):
+def _fg_kernel(e, g, h, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr):
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
@@ -74,14 +65,7 @@ def swiglu_fg_kernel(e, g):
 
 
 @triton.jit
-def _DWf_DW_dfg_kernel(
-    DW,
-    e,
-    g,
-    n_elements,
-    BLOCK_SIZE: tl.constexpr,
-    LONG_INDEXING: tl.constexpr,
-):
+def _DWf_DW_dfg_kernel(DW, e, g, n_elements, BLOCK_SIZE: tl.constexpr, LONG_INDEXING: tl.constexpr):
     """
     e = e.float()
     se = 1.0 / (1.0 + torch.exp(-e))
@@ -93,9 +77,7 @@ def _DWf_DW_dfg_kernel(
     """
     block_idx = tl.program_id(0)
     if LONG_INDEXING:
-        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(
-            tl.int64
-        )
+        offsets = block_idx.to(tl.int64) * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE).to(tl.int64)
         n_elements = tl.cast(n_elements, tl.int64)
     else:
         offsets = block_idx * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
diff --git a/unsloth/kernels/utils.py b/unsloth/kernels/utils.py
index f77baea281..0db97aabcb 100644
--- a/unsloth/kernels/utils.py
+++ b/unsloth/kernels/utils.py
@@ -39,9 +39,7 @@ torch_Tensor = torch.Tensor
 from unsloth_zoo.utils import Version
 
 if DEVICE_TYPE == "xpu" and Version(torch.__version__) < Version("2.6.0"):
-    raise RuntimeError(
-        "Intel xpu currently supports unsloth with torch.version >= 2.6.0"
-    )
+    raise RuntimeError("Intel xpu currently supports unsloth with torch.version >= 2.6.0")
 
 if Version(torch.__version__) < Version("2.4.0"):
     torch_amp_custom_fwd = torch.cuda.amp.custom_fwd
@@ -64,7 +62,6 @@ if Version(triton.__version__) >= Version("3.0.0"):
         triton_tanh = tl.extra.intel.libdevice.tanh
     else:
         from triton.language.extra import libdevice
-
         triton_tanh = libdevice.tanh
     triton_cast = tl.cast
 else:
@@ -152,7 +149,6 @@ if DEVICE_COUNT > 1:
         torch_gpu_device = torch.xpu.device
 else:
     from contextlib import nullcontext
-
     def torch_gpu_device(device):
         return nullcontext()
 
@@ -273,7 +269,6 @@ if importlib.util.find_spec("torchao") is not None:
         from torchao.quantization import Float8Tensor
     except:
         import torchao
-
         if Version(torchao.__version__) >= Version("0.15.0"):
             print(
                 f"Unsloth: `from torchao.quantization import Float8Tensor` failed on version={torchao.__version__}"
@@ -386,9 +381,7 @@ def get_lora_parameters_bias(proj):
     )
 
 
-def _maybe_fake_quantize_activations(
-    X: torch.Tensor, proj: torch.nn.Module
-) -> torch.Tensor:
+def _maybe_fake_quantize_activations(X: torch.Tensor, proj: torch.nn.Module) -> torch.Tensor:
     """
     If QAT is enabled, fake quantize the input activations.
     Otherwise, just return the input activations as is.
@@ -405,7 +398,12 @@ def _maybe_fake_quantize_activations(
 if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
 
     @torch.inference_mode
-    def fast_dequantize(W, quant_state = None, out = None, use_global_buffer = False):
+    def fast_dequantize(
+        W,
+        quant_state = None,
+        out = None,
+        use_global_buffer = False,
+    ):
         # TODO: After adding XPU BNB support, check this function
         if isinstance(W, Float8Tensor):
             return W.dequantize()
@@ -464,9 +462,7 @@ if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
             out_absmax = ABSMAX_BUFFER[:n_elements_absmax]
         else:
             if out is None:
-                out = torch_empty(
-                    shape, dtype = dtype, device = device, requires_grad = False
-                )
+                out = torch_empty(shape, dtype = dtype, device = device, requires_grad = False)
             else:
                 assert out.shape == shape
                 assert out.dtype == dtype
@@ -514,7 +510,12 @@ if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
 elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
 
     @torch.inference_mode
-    def fast_dequantize(W, quant_state = None, out = None, use_global_buffer = False):
+    def fast_dequantize(
+        W,
+        quant_state = None,
+        out = None,
+        use_global_buffer = False,
+    ):
         if isinstance(W, Float8Tensor):
             return W.dequantize()
         if quant_state is None:
@@ -574,9 +575,7 @@ elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
             out_absmax = ABSMAX_BUFFER[:n_elements_absmax]
         else:
             if out is None:
-                out = torch_empty(
-                    shape, dtype = dtype, device = device, requires_grad = False
-                )
+                out = torch_empty(shape, dtype = dtype, device = device, requires_grad = False)
             else:
                 assert out.shape == shape
                 assert out.dtype == dtype
@@ -626,7 +625,12 @@ elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
 else:
 
     @torch.inference_mode
-    def fast_dequantize(W, quant_state = None, out = None, use_global_buffer = False):
+    def fast_dequantize(
+        W,
+        quant_state = None,
+        out = None,
+        use_global_buffer = False,
+    ):
         if isinstance(W, Float8Tensor):
             return W.dequantize()
         if quant_state is None:
@@ -701,7 +705,12 @@ else:
 # INTEL GPU Specific Logic
 if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
 
-    def fast_gemv(X, W, quant_state, out = None):
+    def fast_gemv(
+        X,
+        W,
+        quant_state,
+        out = None,
+    ):
         if quant_state is None:
             return torch_matmul(X, W, out = out)
         # For fast X @ W where seq_len == 1
@@ -722,9 +731,7 @@ if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
             code2 = state2.code
             blocksize2 = state2.blocksize
         else:
-            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = (
-                quant_state
-            )
+            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = quant_state
             offset, state2 = compressed_stats
             absmax2, code2, blocksize2, _, _, _, _ = state2
         global XPU_STREAMS
@@ -807,7 +814,12 @@ if DEVICE_TYPE == "xpu" and HAS_XPU_STREAM:
 
 elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
 
-    def fast_gemv(X, W, quant_state, out = None):
+    def fast_gemv(
+        X,
+        W,
+        quant_state,
+        out = None,
+    ):
         if quant_state is None:
             return torch_matmul(X, W, out = out)
         # For fast X @ W where seq_len == 1
@@ -828,9 +840,7 @@ elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
             code2 = state2.code
             blocksize2 = state2.blocksize
         else:
-            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = (
-                quant_state
-            )
+            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = quant_state
             offset, state2 = compressed_stats
             absmax2, code2, blocksize2, _, _, _, _ = state2
         pass
@@ -912,7 +922,12 @@ elif DEVICE_TYPE in ("cuda", "hip") and HAS_CUDA_STREAM:
     pass
 else:
 
-    def fast_gemv(X, W, quant_state, out = None):
+    def fast_gemv(
+        X,
+        W,
+        quant_state,
+        out = None,
+    ):
         if quant_state is None:
             return torch_matmul(X, W, out = out)
         # For fast X @ W where seq_len == 1
@@ -933,9 +948,7 @@ else:
             code2 = state2.code
             blocksize2 = state2.blocksize
         else:
-            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = (
-                quant_state
-            )
+            absmax, shape, dtype, blocksize, compressed_stats, quant_type, stats = quant_state
             offset, state2 = compressed_stats
             absmax2, code2, blocksize2, _, _, _, _ = state2
         pass
@@ -1009,7 +1022,12 @@ else:
     pass
 
 
-def fast_linear_forward(proj, X, temp_lora = None, out = None):
+def fast_linear_forward(
+    proj,
+    X,
+    temp_lora = None,
+    out = None,
+):
     W, W_quant, lora_A, lora_B, lora_S, bias = get_lora_parameters_bias(proj)
     bsz, q_len, in_dim = X.shape
     if q_len != 1:
@@ -1040,9 +1058,7 @@ def fast_linear_forward(proj, X, temp_lora = None, out = None):
             out.addmv_(lora_B._fast_lora, temp_lora, alpha = lora_S)
         else:
             out = out.view(bsz, out_dim)
-            temp_lora = torch_mm(
-                X.view(bsz, in_dim), lora_A._fast_lora.t(), out = temp_lora
-            )
+            temp_lora = torch_mm(X.view(bsz, in_dim), lora_A._fast_lora.t(), out = temp_lora)
             out.addmm_(temp_lora, lora_B._fast_lora.t(), alpha = lora_S)
         out = out.view(bsz, 1, out_dim)
 
@@ -1052,7 +1068,15 @@ def fast_linear_forward(proj, X, temp_lora = None, out = None):
     return out
 
 
-def matmul_lora(X, W, W_quant, A, B, s, out = None):
+def matmul_lora(
+    X,
+    W,
+    W_quant,
+    A,
+    B,
+    s,
+    out = None,
+):
     dtype = X.dtype
 
     if X.dim() == 3:
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 7af89bcecd..10f3ce0b1d 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -192,9 +192,7 @@ from unsloth_zoo.temporary_patches import (
 )
 
 
-def apply_unsloth_gradient_checkpointing(
-    use_gradient_checkpointing, max_seq_length, dtype
-):
+def apply_unsloth_gradient_checkpointing(use_gradient_checkpointing, max_seq_length, dtype):
     """
     Apply gradient checkpointing with smart heuristics.
 
@@ -258,8 +256,7 @@ def _is_flash_excluded(model_type):
 
 def _config_prefers_flex_attention(config):
     return any(
-        _config_get(attention_config, "model_type", "").lower()
-        in _FLEX_PREFERRED_MODELS
+        _config_get(attention_config, "model_type", "").lower() in _FLEX_PREFERRED_MODELS
         for attention_config in _iter_attention_configs(config)
     )
 
@@ -281,7 +278,6 @@ def _supports_flex_attention(model_class, config, model_type):
             return False
     try:
         from transformers.utils.import_utils import is_torch_flex_attn_available
-
         return is_torch_flex_attn_available()
     except Exception:
         return False
@@ -295,7 +291,11 @@ def _config_items(config):
     return ()
 
 
-def _config_get(config, field_name, default = None):
+def _config_get(
+    config,
+    field_name,
+    default = None,
+):
     if isinstance(config, dict):
         return config.get(field_name, default)
     return getattr(config, field_name, default)
@@ -309,9 +309,7 @@ def _config_set(config, field_name, value):
 
 
 def _iter_attention_configs(config, seen = None):
-    if config is None or (
-        not isinstance(config, dict) and not hasattr(config, "__dict__")
-    ):
+    if config is None or (not isinstance(config, dict) and not hasattr(config, "__dict__")):
         return
     if seen is None:
         seen = set()
@@ -354,11 +352,7 @@ def _collect_attention_head_dims(config):
             continue
         for num_heads_name in num_heads_names:
             num_heads = _config_get(config, num_heads_name, None)
-            if (
-                isinstance(num_heads, int)
-                and num_heads > 0
-                and (hidden_size % num_heads) == 0
-            ):
+            if isinstance(num_heads, int) and num_heads > 0 and (hidden_size % num_heads) == 0:
                 head_dims.append(hidden_size // num_heads)
 
     return head_dims
@@ -409,9 +403,7 @@ def _disable_flash_attention_if_needed(
 
     requested_attn_implementation = attn_implementation
     if requested_attn_implementation is None:
-        requested_attn_implementation = _config_get(
-            config, "_attn_implementation", None
-        )
+        requested_attn_implementation = _config_get(config, "_attn_implementation", None)
     if requested_attn_implementation is None:
         requested_attn_implementation = _config_get(config, "attn_implementation", None)
 
@@ -424,10 +416,7 @@ def _disable_flash_attention_if_needed(
         fallback_attn_implementation = "flex_attention"
     else:
         fallback_attn_implementation = "eager"
-    if (
-        _is_flash_attention_requested(requested_attn_implementation)
-        or would_use_flash_attention
-    ):
+    if _is_flash_attention_requested(requested_attn_implementation) or would_use_flash_attention:
         logged_attn_implementation = (
             requested_attn_implementation
             if _is_flash_attention_requested(requested_attn_implementation)
@@ -467,20 +456,14 @@ def resolve_model_class(auto_model, config):
         result = None
         for key in list(getattr(mapping, "_model_mapping", {})):
             try:
-                config_class = mapping._load_attr_from_module(
-                    key, mapping._config_mapping[key]
-                )
+                config_class = mapping._load_attr_from_module(key, mapping._config_mapping[key])
                 if isinstance(config, config_class):
-                    result = mapping._load_attr_from_module(
-                        key, mapping._model_mapping[key]
-                    )
+                    result = mapping._load_attr_from_module(key, mapping._model_mapping[key])
                     break
             except Exception:
                 continue
         if result is None:
-            for extra_cls, extra_model in getattr(
-                mapping, "_extra_content", {}
-            ).items():
+            for extra_cls, extra_model in getattr(mapping, "_extra_content", {}).items():
                 try:
                     if isinstance(config, extra_cls):
                         result = extra_model
@@ -501,9 +484,7 @@ def resolve_attention_implementation(
     model_type_name = _config_get(config, "model_type", "")
     model_type = model_type_name.lower()
     if supports_sdpa is None:
-        supports_sdpa = model_class is not None and getattr(
-            model_class, "_supports_sdpa", False
-        )
+        supports_sdpa = model_class is not None and getattr(model_class, "_supports_sdpa", False)
     if _is_sdpa_excluded(model_type):
         supports_sdpa = False
     supports_flash_attention = (
@@ -529,20 +510,14 @@ def resolve_attention_implementation(
             # over flash. Caller can still override by passing
             # requested_attn_implementation="sdpa" (handled below).
             attn_impl = _set_attn_impl(config, "flex_attention")
-        elif (
-            not flash_attention_disabled
-            and HAS_FLASH_ATTENTION
-            and supports_flash_attention
-        ):
+        elif not flash_attention_disabled and HAS_FLASH_ATTENTION and supports_flash_attention:
             attn_impl = _set_attn_impl(config, "flash_attention_2")
         elif flash_attention_disabled:
             attn_impl = _disable_flash_attention_if_needed(
                 config,
                 supports_sdpa = supports_sdpa,
                 supports_flex_attention = supports_flex_attention,
-                would_use_flash_attention = (
-                    HAS_FLASH_ATTENTION and supports_flash_attention
-                ),
+                would_use_flash_attention = (HAS_FLASH_ATTENTION and supports_flash_attention),
                 disable_reason = disable_reason,
             )
         elif supports_sdpa:
@@ -585,9 +560,7 @@ def resolve_encoder_attention_implementation(
     disable_sdpa_model_names = (),
 ):
     model_class = resolve_model_class(auto_model, config)
-    supports_sdpa = model_class is not None and getattr(
-        model_class, "_supports_sdpa", False
-    )
+    supports_sdpa = model_class is not None and getattr(model_class, "_supports_sdpa", False)
     if any(name in model_type.lower() for name in disable_sdpa_model_names):
         return "eager"
     if supports_sdpa:
@@ -597,7 +570,6 @@ def resolve_encoder_attention_implementation(
 
 def _run_temporary_patches(phase):
     import inspect
-
     for temporary_patch in TEMPORARY_PATCHES:
         try:
             sig = inspect.signature(temporary_patch)
@@ -616,18 +588,14 @@ _run_temporary_patches("init")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "torch")
 warnings.filterwarnings(action = "ignore", category = FutureWarning, module = "torch")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "huggingface_hub")
-warnings.filterwarnings(
-    action = "ignore", category = FutureWarning, module = "huggingface_hub"
-)
+warnings.filterwarnings(action = "ignore", category = FutureWarning, module = "huggingface_hub")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "trl")
 warnings.filterwarnings(action = "ignore", category = FutureWarning, module = "trl")
 warnings.filterwarnings(action = "ignore", category = FutureWarning, module = "xformers")
 warnings.filterwarnings(action = "ignore", category = RuntimeWarning, module = "subprocess")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "transformers")
 warnings.filterwarnings(action = "ignore", category = FutureWarning, module = "accelerate")
-warnings.filterwarnings(
-    action = "ignore", category = RuntimeWarning, module = "multiprocessing"
-)
+warnings.filterwarnings(action = "ignore", category = RuntimeWarning, module = "multiprocessing")
 warnings.filterwarnings(action = "ignore", category = RuntimeWarning, module = "multiprocess")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "triton")
 warnings.filterwarnings(action = "ignore", category = UserWarning, module = "bitsandbytes")
@@ -661,7 +629,12 @@ class ReplaceWarningMessage:
     _installed = False
 
     @classmethod
-    def add_rule(cls, match_text, replacement, category = None):
+    def add_rule(
+        cls,
+        match_text,
+        replacement,
+        category = None,
+    ):
         cls._rules.append((match_text, replacement, category))
         if not cls._installed:
             cls._install()
@@ -672,13 +645,16 @@ class ReplaceWarningMessage:
         cls._installed = True
 
         def _patched_showwarning(
-            message, category, filename, lineno, file = None, line = None
+            message,
+            category,
+            filename,
+            lineno,
+            file = None,
+            line = None,
         ):
             msg_str = str(message)
             for match_text, replacement, match_category in cls._rules:
-                if match_text in msg_str and (
-                    match_category is None or category is match_category
-                ):
+                if match_text in msg_str and (match_category is None or category is match_category):
                     print(replacement)
                     return
             cls._original_showwarning(message, category, filename, lineno, file, line)
@@ -690,14 +666,12 @@ class ReplaceWarningMessage:
 if not UNSLOTH_ENABLE_LOGGING:
     try:
         from vllm.worker.worker import logger as vllm_worker_logger
-
         vllm_worker_logger.addFilter(HideLoggingMessage("Sleep mode freed"))
         del vllm_worker_logger
     except:
         pass
     try:
         from vllm.v1.worker.gpu_worker import logger as vllm_gpu_worker_logger
-
         vllm_gpu_worker_logger.addFilter(HideLoggingMessage("Sleep mode freed"))
         del vllm_gpu_worker_logger
     except:
@@ -716,9 +690,7 @@ if not UNSLOTH_ENABLE_LOGGING:
 
         vllm_v1_executor_logger.addFilter(HideLoggingMessage("to fall asleep"))
         vllm_v1_executor_logger.addFilter(HideLoggingMessage("to wake up"))
-        vllm_v1_executor_logger.addFilter(
-            HideLoggingMessage("Executor is not sleeping")
-        )
+        vllm_v1_executor_logger.addFilter(HideLoggingMessage("Executor is not sleeping"))
         del vllm_v1_executor_logger
     except:
         pass
@@ -726,25 +698,20 @@ if not UNSLOTH_ENABLE_LOGGING:
         from vllm.core.block.prefix_caching_block import (
             logger as vllm_prefix_caching_logger,
         )
-
         vllm_prefix_caching_logger.addFilter(HideLoggingMessage("reset prefix cache"))
         del vllm_prefix_caching_logger
     except:
         pass
     try:
         from vllm.v1.core.block_pool import logger as vllm_block_pool_logger
-
         vllm_block_pool_logger.addFilter(HideLoggingMessage("reset prefix cache"))
         del vllm_block_pool_logger
     except:
         pass
     try:
         from vllm.lora.models import logger as vllm_lora_model_logger
-
         vllm_lora_model_logger.addFilter(
-            HideLoggingMessage(
-                "Regarding multimodal models, vLLM currently only supports adding"
-            )
+            HideLoggingMessage("Regarding multimodal models, vLLM currently only supports adding")
         )
         del vllm_lora_model_logger
     except:
@@ -753,10 +720,7 @@ if not UNSLOTH_ENABLE_LOGGING:
         from vllm.attention.utils.fa_utils import (
             logger as vllm_attention_utils_fa_utils_logger,
         )
-
-        vllm_attention_utils_fa_utils_logger.addFilter(
-            HideLoggingMessage("Cannot use FA version")
-        )
+        vllm_attention_utils_fa_utils_logger.addFilter(HideLoggingMessage("Cannot use FA version"))
         del vllm_attention_utils_fa_utils_logger
     except:
         pass
@@ -768,9 +732,7 @@ transformers_training_args_logger.addFilter(HideLoggingMessage("The speedups"))
 # torch.distributed process group is initialized, but parallel_mode != ParallelMode.DISTRIBUTED.
 transformers_training_args_logger.addFilter(HideLoggingMessage("torch.distributed"))
 # average_tokens_across_devices is set to True but it is invalid when world size is1
-transformers_training_args_logger.addFilter(
-    HideLoggingMessage("average_tokens_across_devices")
-)
+transformers_training_args_logger.addFilter(HideLoggingMessage("average_tokens_across_devices"))
 del transformers_training_args_logger
 
 # No label_names provided for model class
@@ -786,7 +748,6 @@ del transformers_trainer_logger
 try:
     try:
         import transformers.utils.logging as _tf_log
-
         _tf_log._configure_library_root_logger()
     except Exception:
         pass
@@ -801,7 +762,6 @@ except Exception:
 # Using the default loss: `ForCausalLMLoss`.
 try:
     from transformers.modeling_utils import logger as transformers_modeling_utils_logger
-
     transformers_modeling_utils_logger.addFilter(HideLoggingMessage("ForCausalLMLoss"))
     del transformers_modeling_utils_logger
 except:
@@ -810,10 +770,7 @@ except:
 # The model weights are not tied. Please use the `tie_weights` method before using the `infer_auto_device` function.
 try:
     from accelerate.utils.modeling import logger as accelerate_utils_modeling_logger
-
-    accelerate_utils_modeling_logger.addFilter(
-        HideLoggingMessage("The model weights are not tied")
-    )
+    accelerate_utils_modeling_logger.addFilter(HideLoggingMessage("The model weights are not tied"))
     del accelerate_utils_modeling_logger
 except:
     pass
@@ -838,7 +795,6 @@ try:
     from transformers.generation.configuration_utils import (
         logger as configuration_logger,
     )
-
     configuration_logger.addFilter(HideLoggingMessage("following generation flags"))
     del configuration_logger
 except:
@@ -847,7 +803,6 @@ except:
 # Gemma3 It is strongly recommended to train Gemma3 models with the `eager`
 try:
     from transformers.models.gemma3.modeling_gemma3 import logger as gemma3_logger
-
     gemma3_logger.addFilter(HideLoggingMessage("strongly recommended"))
     del gemma3_logger
 except:
@@ -856,7 +811,6 @@ except:
 # Gemma4 It is strongly recommended to train Gemma4 models with the `eager`
 try:
     from transformers.models.gemma4.modeling_gemma4 import logger as gemma4_logger
-
     gemma4_logger.addFilter(HideLoggingMessage("strongly recommended"))
     del gemma4_logger
 except:
@@ -865,7 +819,6 @@ except:
 # Xet Storage is enabled for this repo, but the 'hf_xet' package is not installed.
 try:
     from huggingface_hub.file_download import logger as hub_logger
-
     hub_logger.addFilter(HideLoggingMessage("hf_xet"))
     del hub_logger
 except:
@@ -874,7 +827,6 @@ except:
 # MXFP4 quantization requires triton >= 3.4.0
 try:
     from transformers.quantizers.quantizer_mxfp4 import logger as mxfp4_logger
-
     mxfp4_logger.addFilter(HideLoggingMessage("requires triton"))
     del mxfp4_logger
 except:
@@ -906,7 +858,6 @@ except:
 # Using a slow image processor as `use_fast`
 try:
     from transformers.processing_utils import logger as processing_utils_logger
-
     processing_utils_logger.addFilter(HideLoggingMessage("`use_fast`"))
     del processing_utils_logger
 except:
@@ -917,7 +868,6 @@ try:
     from transformers.models.auto.image_processing_auto import (
         logger as processing_utils_logger,
     )
-
     processing_utils_logger.addFilter(HideLoggingMessage("`use_fast`"))
     del processing_utils_logger
 except:
@@ -926,7 +876,6 @@ except:
 # `use_cache=True` is incompatible with gradient checkpointing
 try:
     from transformers.trainer import logger as trainer_logger
-
     trainer_logger.addFilter(HideLoggingMessage("`use_cache=True`"))
     del trainer_logger
 except:
@@ -935,7 +884,6 @@ except:
 # `use_cache=True` is incompatible with gradient checkpointing
 try:
     from transformers.utils.generic import logger as trainer_logger
-
     trainer_logger.addFilter(HideLoggingMessage("`use_cache=True`"))
     del trainer_logger
 except:
@@ -944,7 +892,6 @@ except:
 # We detected that you are using `from_pretrained` with a meta device context manager or `torch.set_default_device('meta')
 try:
     from transformers.modeling_utils import logger as modeling_utils_logger
-
     modeling_utils_logger.addFilter(HideLoggingMessage("anti-pattern"))
     del modeling_utils_logger
 except:
@@ -988,7 +935,6 @@ class RaiseUninitialized:
 
 try:
     from transformers.trainer import logger as transformers_trainer_logger
-
     transformers_trainer_logger.addFilter(
         HideLoggingMessage("The model is already on multiple devices.")
     )
@@ -998,10 +944,7 @@ except:
 # Hide HF Hub unauthenticated request warnings
 try:
     from huggingface_hub.utils._http import logger as hf_http_logger
-
-    hf_http_logger.addFilter(
-        HideLoggingMessage("You are sending unauthenticated requests")
-    )
+    hf_http_logger.addFilter(HideLoggingMessage("You are sending unauthenticated requests"))
     del hf_http_logger
 except:
     pass
@@ -1046,9 +989,7 @@ def get_model_param_count(model, trainable_only = False):
         def numel(p):
             return p.numel()
 
-    s = sum(
-        numel(p) for p in model.parameters() if not trainable_only or p.requires_grad
-    )
+    s = sum(numel(p) for p in model.parameters() if not trainable_only or p.requires_grad)
     if (
         (not trainable_only)
         and hasattr(model, "config")
@@ -1080,9 +1021,7 @@ def patch_mistral_nemo_config(config):
             "        head_dim (`int`, *optional*, defaults to `hidden_size // num_attention_heads`):\n"
             "            The attention head dimension."
         )
-        config = config.replace(
-            "If it is not specified, will default to `8`.", add_head_dim
-        )
+        config = config.replace("If it is not specified, will default to `8`.", add_head_dim)
 
         add_head_dim = "num_key_value_heads=8,\n        head_dim=None,"
         config = config.replace("num_key_value_heads=8,", add_head_dim)
@@ -1258,9 +1197,7 @@ if DEVICE_TYPE == "cuda":
                 # Also check for softcapping
                 from flash_attn import __version__ as flash_attn_version
 
-                HAS_FLASH_ATTENTION_SOFTCAPPING = Version(
-                    flash_attn_version
-                ) >= Version("2.6.3")
+                HAS_FLASH_ATTENTION_SOFTCAPPING = Version(flash_attn_version) >= Version("2.6.3")
                 if not HAS_FLASH_ATTENTION_SOFTCAPPING:
                     print(
                         "Unsloth: If you want to finetune Gemma 2, upgrade flash-attn to version 2.6.3 or higher!\n"
@@ -1282,9 +1219,7 @@ if DEVICE_TYPE == "cuda":
                 )
                 import transformers.utils
 
-                transformers.utils.is_flash_attn_2_available = (
-                    lambda *args, **kwargs: False
-                )
+                transformers.utils.is_flash_attn_2_available = lambda *args, **kwargs: False
 
                 HAS_FLASH_ATTENTION = False
         else:
@@ -1307,9 +1242,7 @@ elif DEVICE_TYPE == "hip":
             # Also check for softcapping
             from flash_attn import __version__ as flash_attn_version
 
-            HAS_FLASH_ATTENTION_SOFTCAPPING = Version(flash_attn_version) >= Version(
-                "2.6.3"
-            )
+            HAS_FLASH_ATTENTION_SOFTCAPPING = Version(flash_attn_version) >= Version("2.6.3")
             if not HAS_FLASH_ATTENTION_SOFTCAPPING:
                 print(
                     "Unsloth: If you want to finetune Gemma 2, upgrade flash-attn to version 2.6.3 or higher!\n"
@@ -1383,23 +1316,21 @@ try:
             'Please downgrade xformers via `pip install --force-reinstall "xformers<=0.0.27"'
         )
 
-    if Version(torch_version) < Version("2.2.0") and Version(
-        xformers_version
-    ) >= Version("0.0.24"):
+    if Version(torch_version) < Version("2.2.0") and Version(xformers_version) >= Version("0.0.24"):
         raise ImportError(
             f"Unsloth: You have torch = {torch_version} but xformers = {xformers_version}.\n"
             f"Please install xformers < 0.0.24 for torch = {torch_version}."
         )
-    elif Version(torch_version) < Version("2.3.0") and Version(
-        xformers_version
-    ) >= Version("0.0.26"):
+    elif Version(torch_version) < Version("2.3.0") and Version(xformers_version) >= Version(
+        "0.0.26"
+    ):
         raise ImportError(
             f"Unsloth: You have torch = {torch_version} but xformers = {xformers_version}.\n"
             f"Please install xformers < 0.0.26 for torch = {torch_version}."
         )
-    elif Version(torch_version) < Version("2.4.0") and Version(
-        xformers_version
-    ) > Version("0.0.27"):
+    elif Version(torch_version) < Version("2.4.0") and Version(xformers_version) > Version(
+        "0.0.27"
+    ):
         raise ImportError(
             f"Unsloth: You have torch = {torch_version} but xformers = {xformers_version}.\n"
             f"Please install xformers <= 0.0.27 for torch = {torch_version}."
@@ -1426,9 +1357,7 @@ except ModuleNotFoundError:
     xformers_version = None
 except Exception as e:
     if UNSLOTH_ENABLE_LOGGING:
-        print(
-            "========\nSwitching to PyTorch attention since your Xformers is broken.\n========\n"
-        )
+        print("========\nSwitching to PyTorch attention since your Xformers is broken.\n========\n")
         print(str(e))
     xformers = None
     xformers_attention = None
@@ -1478,26 +1407,16 @@ if False:  # Version(trl_version) >= Version("0.9.0"):
 import transformers.generation.configuration_utils
 
 if hasattr(transformers.generation.configuration_utils, "ALL_CACHE_IMPLEMENTATIONS"):
-    if (
-        type(transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS)
-        is list
-    ):
-        if (
-            "dynamic"
-            not in transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS
-        ):
-            transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS.append(
-                "dynamic"
-            )
+    if type(transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS) is list:
+        if "dynamic" not in transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS:
+            transformers.generation.configuration_utils.ALL_CACHE_IMPLEMENTATIONS.append("dynamic")
 # =============================================
 
 # =============================================
 # Torch compile settings
 UNSLOTH_COMPILE_DEBUG = os.environ.get("UNSLOTH_COMPILE_DEBUG", "0") == "1"
 UNSLOTH_COMPILE_MAXIMUM = os.environ.get("UNSLOTH_COMPILE_MAXIMUM", "0") == "1"
-UNSLOTH_COMPILE_IGNORE_ERRORS = (
-    os.environ.get("UNSLOTH_COMPILE_IGNORE_ERRORS", "1") == "1"
-)
+UNSLOTH_COMPILE_IGNORE_ERRORS = os.environ.get("UNSLOTH_COMPILE_IGNORE_ERRORS", "1") == "1"
 # Just remove max_autotune_gemm warning
 from torch._inductor.runtime.hints import DeviceProperties
 
@@ -1505,14 +1424,10 @@ from torch._inductor.runtime.hints import DeviceProperties
 @functools.lru_cache(None)
 def is_big_gpu(index) -> bool:
     if DEVICE_TYPE == "xpu":
-        prop = DeviceProperties.create(
-            torch.device("xpu", index) if type(index) is int else index
-        )
+        prop = DeviceProperties.create(torch.device("xpu", index) if type(index) is int else index)
         min_sms = 16
     else:
-        prop = DeviceProperties.create(
-            torch.device("cuda", index) if type(index) is int else index
-        )
+        prop = DeviceProperties.create(torch.device("cuda", index) if type(index) is int else index)
         min_sms = 80
 
     avail_sms = prop.multi_processor_count
@@ -1618,7 +1533,6 @@ from peft.utils.integrations import dequantize_module_weight
 
 if Version(peft_version) < Version("0.12.0"):
     from peft.tuners.lora.layer import LoraLayer
-
     try:
         source = inspect.getsource(LoraLayer.update_layer)
         text = "if weight is not None:\n"
@@ -1661,7 +1575,11 @@ import socket
 
 
 @functools.lru_cache(1)
-def has_internet(host = "8.8.8.8", port = 53, timeout = 3):
+def has_internet(
+    host = "8.8.8.8",
+    port = 53,
+    timeout = 3,
+):
     if os.environ.get("TRANSFORMERS_OFFLINE", "0") == "1":
         return False
 
@@ -1699,7 +1617,6 @@ def _get_statistics(statistics = None, force_download = True):
         # Prefer filesystem markers (harder to misidentify) before env-key matching
         try:
             from pathlib import Path
-
             if Path("/kaggle/working").exists():
                 statistics = "kaggle"
             elif Path("/content").exists() and Path("/opt/colab").exists():
@@ -1869,9 +1786,7 @@ BitsAndBytesConfig__init__ = re.sub(
 )
 BitsAndBytesConfig__init__ = BitsAndBytesConfig__init__.split("\n")
 length_spaces = len(re.match(r"[\s]{1,}", BitsAndBytesConfig__init__[0]).group(0))
-BitsAndBytesConfig__init__ = "\n".join(
-    x[length_spaces:] for x in BitsAndBytesConfig__init__
-)
+BitsAndBytesConfig__init__ = "\n".join(x[length_spaces:] for x in BitsAndBytesConfig__init__)
 BitsAndBytesConfig__init__ = BitsAndBytesConfig__init__.replace(
     "__init__",
     "_BitsAndBytesConfig__init__",
@@ -1887,9 +1802,7 @@ if DEVICE_COUNT == 1 and int(os.environ.get("WORLD_SIZE", "1")) <= 1:
     import accelerate.state
 
     accelerate.state.PartialState._prepare_backend = _prepare_backend
-    accelerate.accelerator.Accelerator.distributed_type = (
-        lambda *args, **kwargs: DistributedType.NO
-    )
+    accelerate.accelerator.Accelerator.distributed_type = lambda *args, **kwargs: DistributedType.NO
 
 
 # to move multiple tensors to the same device
@@ -1924,9 +1837,7 @@ def move_to_device(target_device, *tensors):
 
 import transformers.utils.quantization_config
 
-transformers.utils.quantization_config.BitsAndBytesConfig.__init__ = (
-    _BitsAndBytesConfig__init__
-)
+transformers.utils.quantization_config.BitsAndBytesConfig.__init__ = _BitsAndBytesConfig__init__
 # =============================================
 
 # Offloading to disk for modules (lm_head, embed_tokens)
@@ -1934,7 +1845,10 @@ import pickle
 
 
 def offload_to_disk(
-    W, model, name, temporary_location: str = "_unsloth_temporary_saved_buffers"
+    W,
+    model,
+    name,
+    temporary_location: str = "_unsloth_temporary_saved_buffers",
 ):
     file_location = os.path.join(temporary_location, model.config._name_or_path)
     if not os.path.exists(file_location):
@@ -1949,16 +1863,12 @@ def offload_to_disk(
         pickle_protocol = pickle.HIGHEST_PROTOCOL,
     )
     # We must use weights_only = False due to pickling
-    offloaded_W = torch.load(
-        filename, map_location = "cpu", mmap = True, weights_only = False
-    )
+    offloaded_W = torch.load(filename, map_location = "cpu", mmap = True, weights_only = False)
     offloaded_W._offloaded_file_location = filename
     return offloaded_W
 
 
-def offload_input_embeddings(
-    model, temporary_location: str = "_unsloth_temporary_saved_buffers"
-):
+def offload_input_embeddings(model, temporary_location: str = "_unsloth_temporary_saved_buffers"):
     offloaded_W = offload_to_disk(
         model.get_input_embeddings(), model, "input_embeddings", temporary_location
     )
@@ -1968,9 +1878,7 @@ def offload_input_embeddings(
     return
 
 
-def offload_output_embeddings(
-    model, temporary_location: str = "_unsloth_temporary_saved_buffers"
-):
+def offload_output_embeddings(model, temporary_location: str = "_unsloth_temporary_saved_buffers"):
     offloaded_W = offload_to_disk(
         model.get_output_embeddings(), model, "output_embeddings", temporary_location
     )
@@ -1981,9 +1889,7 @@ def offload_output_embeddings(
     new_output_embeddings.in_features = offloaded_W.shape[1]
     new_output_embeddings.out_features = offloaded_W.shape[0]
 
-    new_output_embeddings._offloaded_file_location = (
-        offloaded_W._offloaded_file_location
-    )
+    new_output_embeddings._offloaded_file_location = offloaded_W._offloaded_file_location
     model.set_output_embeddings(new_output_embeddings)
     return
 
@@ -2185,7 +2091,6 @@ def create_boolean_mask(n = 4096, sliding_window = 2048):
 
 def test_mask_creation():
     from transformers.modeling_attn_mask_utils import AttentionMaskConverter
-
     for n in range(2, 23):
         for s in range(1, 23):
             correct_mask = (
@@ -2295,9 +2200,7 @@ def patch_gradient_accumulation_fix(Trainer):
             .strip()
             .endswith("return batch_samples, num_items_in_batch")
         ):
-            raise NotImplementedError(
-                "Unsloth: Please make a Github issue immediately!!"
-            )
+            raise NotImplementedError("Unsloth: Please make a Github issue immediately!!")
         else:
             if Trainer.get_batch_samples.__name__ != "_unsloth_get_batch_samples":
                 Trainer.get_batch_samples = _unsloth_get_batch_samples
@@ -2347,8 +2250,7 @@ def patch_gradient_accumulation_fix(Trainer):
     # Also fix up loss scaling ie negate loss *= self.args.gradient_accumulation_steps
     if not (
         Trainer.training_step.__name__ == "_unsloth_training_step"
-        or "num_items_in_batch"
-        not in inspect.signature(Trainer.training_step).parameters
+        or "num_items_in_batch" not in inspect.signature(Trainer.training_step).parameters
     ):
         function = inspect.getsource(Trainer.training_step)
         where = function.find("def")
@@ -2364,9 +2266,7 @@ def patch_gradient_accumulation_fix(Trainer):
             if item in function:
                 good_items.append(item)
         exec(
-            "from transformers.trainer import ("
-            + ", ".join(x for x in good_items)
-            + ")",
+            "from transformers.trainer import (" + ", ".join(x for x in good_items) + ")",
             globals(),
         )
 
@@ -2376,9 +2276,7 @@ def patch_gradient_accumulation_fix(Trainer):
             "loss *= self.args.gradient_accumulation_steps",
             "if num_items_in_batch is not None: loss *= self.args.gradient_accumulation_steps",
         )
-        function = function.replace(
-            "def training_step", "def _unsloth_training_step", 1
-        )
+        function = function.replace("def training_step", "def _unsloth_training_step", 1)
 
         # Fix 4.47.0 issue where num_items_in_batch was removed
         # See https://github.com/huggingface/transformers/pull/35121
@@ -2558,7 +2456,6 @@ def patch_tokenizer(model, tokenizer):
 def patch_fast_lora():
     import peft.tuners.lora.bnb
     from ..kernels.fast_lora import fast_lora_forward
-
     peft.tuners.lora.bnb.Linear4bit.forward = fast_lora_forward
 
 
@@ -2695,9 +2592,7 @@ EMPTY_LOGITS = EmptyLogits()
 functions = dir(torch.Tensor)
 for j, function in enumerate(functions):
     if function.startswith("__") and function.endswith("__"):
-        exec(
-            f"def raise_{j}(*args, **kwargs): print('{function}')", globals(), locals()
-        )
+        exec(f"def raise_{j}(*args, **kwargs): print('{function}')", globals(), locals())
         try:
             exec(f"EMPTY_LOGITS.{function} = raise_{j}", globals(), locals())
         except:
@@ -2738,7 +2633,6 @@ def validate_loftq_config(loftq_config, lora_dropout, bias, init_lora_weights, m
     if init_lora_weights == "loftq":
         if not SUPPORTS_LOFTQ:
             import peft
-
             raise RuntimeError(
                 f"Unsloth: Your PEFT version of {peft.__version__} does not support LoftQ init.\n"
                 "Please install PEFT 0.7.2 or higher.\n"
@@ -2747,7 +2641,6 @@ def validate_loftq_config(loftq_config, lora_dropout, bias, init_lora_weights, m
 
         if loftq_config == {}:
             from peft import LoftQConfig
-
             logger.warning_once(
                 "Unsloth: init_lora_weights = `loftq` is set, but `loftq_config` is None.\n"
                 "We shall use `loftq_config = LoftQConfig(loftq_bits = 4, loftq_iter = 1)`."
@@ -2766,9 +2659,7 @@ def validate_loftq_config(loftq_config, lora_dropout, bias, init_lora_weights, m
 def fast_inference_setup(model_name, model_config):
     fast_inference = True
     if not is_vLLM_available():
-        logger.warning_once(
-            "Unsloth: vLLM is not installed! Will use Unsloth inference!"
-        )
+        logger.warning_once("Unsloth: vLLM is not installed! Will use Unsloth inference!")
         fast_inference = False
     from unsloth_zoo.vllm_utils import (
         patch_vllm,
@@ -2809,7 +2700,6 @@ def error_out_no_vllm(*args, **kwargs):
 
 try:
     from torchao.core.config import AOBaseConfig
-
     try:
         from torchao.quantization import Int4WeightOnlyConfig
     except:
@@ -2831,8 +2721,7 @@ class TorchAOConfig:
         default_factory = lambda: [
             (
                 Int4WeightOnlyConfig(group_size = 128),
-                lambda m, _: isinstance(m, torch.nn.Linear)
-                and getattr(m, "in_features", 0) >= 128,
+                lambda m, _: isinstance(m, torch.nn.Linear) and getattr(m, "in_features", 0) >= 128,
             ),
         ]
     )
@@ -2876,14 +2765,11 @@ def _untie_input_output_embeddings(model: torch.nn.Module) -> None:
     model.tie_weights = _no_tie.__get__(model, model.__class__)
 
     # 5) Verify no shared storage
-    assert (
-        out_proj.weight.data_ptr() != in_emb.weight.data_ptr()
-    ), "Embeddings still tied!"
+    assert out_proj.weight.data_ptr() != in_emb.weight.data_ptr(), "Embeddings still tied!"
 
 
 def _filter_fn_to_fqns(
-    model: torch.nn.Module,
-    filter_fn: Callable[[torch.nn.Module, str], bool],
+    model: torch.nn.Module, filter_fn: Callable[[torch.nn.Module, str], bool]
 ) -> Iterator[str]:
     """
     Given a model and a filter function (m, fqn) -> bool,
@@ -2970,10 +2856,7 @@ def _prepare_model_for_qat(
                 raise ImportError(TORCHAO_MSG)
             group_size = 128
             base_config = Float8DynamicActivationInt4WeightConfig()
-            filter_fn = (
-                lambda m, _: isinstance(m, torch.nn.Linear)
-                and m.in_features >= group_size
-            )
+            filter_fn = lambda m, _: isinstance(m, torch.nn.Linear) and m.in_features >= group_size
             torchao_config = TorchAOConfig(
                 qat_scheme = qat_scheme,
                 base_config_and_filter_fns = [(base_config, filter_fn)],
@@ -2985,9 +2868,7 @@ def _prepare_model_for_qat(
                 )
             except ImportError:
                 raise ImportError(TORCHAO_MSG)
-            base_config = Float8DynamicActivationFloat8WeightConfig(
-                granularity = PerRow()
-            )
+            base_config = Float8DynamicActivationFloat8WeightConfig(granularity = PerRow())
             torchao_config = TorchAOConfig(
                 qat_scheme = qat_scheme, base_config_and_filter_fns = [(base_config, None)]
             )
@@ -3003,9 +2884,7 @@ def _prepare_model_for_qat(
                 qat_scheme = qat_scheme,
                 base_config_and_filter_fns = [
                     (
-                        IntxWeightOnlyConfig(
-                            weight_dtype = torch.int8, granularity = PerAxis(0)
-                        ),
+                        IntxWeightOnlyConfig(weight_dtype = torch.int8, granularity = PerAxis(0)),
                         lambda m, fqn: isinstance(m, torch.nn.Embedding),
                     ),
                     (
@@ -3024,10 +2903,7 @@ def _prepare_model_for_qat(
                 raise ImportError(TORCHAO_MSG)
             group_size = 128
             base_config = Int4WeightOnlyConfig(group_size = group_size)
-            filter_fn = (
-                lambda m, _: isinstance(m, torch.nn.Linear)
-                and m.in_features >= group_size
-            )
+            filter_fn = lambda m, _: isinstance(m, torch.nn.Linear) and m.in_features >= group_size
             torchao_config = TorchAOConfig(
                 qat_scheme = qat_scheme,
                 base_config_and_filter_fns = [(base_config, filter_fn)],
@@ -3127,7 +3003,6 @@ def patch_hf_quantizer():
         from transformers.quantizers.quantizer_finegrained_fp8 import (
             FineGrainedFP8HfQuantizer,
         )
-
         FineGrainedFP8HfQuantizer.is_trainable = property(make_trainable)
         FineGrainedFP8HfQuantizer.is_qat_trainable = property(make_trainable)
     except Exception as e:
@@ -3135,7 +3010,6 @@ def patch_hf_quantizer():
 
     try:
         from transformers.quantizers.quantizer_fbgemm_fp8 import FbgemmFp8HfQuantizer
-
         FbgemmFp8HfQuantizer.is_trainable = property(make_trainable)
         FbgemmFp8HfQuantizer.is_qat_trainable = property(make_trainable)
     except Exception as e:
@@ -3143,7 +3017,6 @@ def patch_hf_quantizer():
 
     try:
         from transformers.quantizers.quantizer_torchao import TorchAoHfQuantizer
-
         TorchAoHfQuantizer.is_trainable = property(make_trainable)
         TorchAoHfQuantizer.is_qat_trainable = property(make_trainable)
     except Exception as e:
@@ -3198,7 +3071,6 @@ def hf_login(token: Optional[str] = None) -> Optional[str]:
     if token is None:
         try:
             from huggingface_hub import get_token
-
             token = get_token()
             if token is None:
                 return None
@@ -3206,7 +3078,6 @@ def hf_login(token: Optional[str] = None) -> Optional[str]:
             return None
     try:
         from huggingface_hub import login
-
         login(token = token)
         return token
     except Exception as e:
@@ -3332,9 +3203,7 @@ def get_moe_target_parameters(model, target_modules = None) -> Optional[List[str
     elif isinstance(target_modules, str):
         target_set = {target_modules}
         # Heuristic for regex matching MLPs
-        if "proj" in target_modules and (
-            "mlp" in target_modules or "ffn" in target_modules
-        ):
+        if "proj" in target_modules and ("mlp" in target_modules or "ffn" in target_modules):
             target_set.update({"gate_proj", "up_proj", "down_proj", "gate_up_proj"})
     else:
         target_set = set(target_modules) if target_modules else set()
@@ -3352,11 +3221,7 @@ def get_moe_target_parameters(model, target_modules = None) -> Optional[List[str
 
     # gate_up_proj combines both gate_proj and up_proj in MoE
     # Also match "gate_up_proj" directly since users may specify the fused name
-    if (
-        "gate_proj" in target_set
-        or "up_proj" in target_set
-        or "gate_up_proj" in target_set
-    ):
+    if "gate_proj" in target_set or "up_proj" in target_set or "gate_up_proj" in target_set:
         moe_params.append(gate_up_name)
 
     if "down_proj" in target_set:
@@ -3456,9 +3321,7 @@ if (
             aliases.add(full_name.replace("language_model.model.", "language_model."))
         if full_name.startswith("model.language_model.model."):
             aliases.add(
-                full_name[len("model.") :].replace(
-                    "language_model.model.", "language_model."
-                )
+                full_name[len("model.") :].replace("language_model.model.", "language_model.")
             )
         return aliases
 
@@ -3487,16 +3350,11 @@ if (
             for candidate in _get_full_name_aliases(full_name)
         )
 
-    patched_should_convert_module._original_should_convert_module = (
-        _original_should_convert_module
-    )
+    patched_should_convert_module._original_should_convert_module = _original_should_convert_module
     _quantizers_utils.should_convert_module = patched_should_convert_module
 
     try:
         import transformers.integrations.bitsandbytes
-
-        transformers.integrations.bitsandbytes.should_convert_module = (
-            patched_should_convert_module
-        )
+        transformers.integrations.bitsandbytes.should_convert_module = patched_should_convert_module
     except Exception:
         pass
diff --git a/unsloth/models/cohere.py b/unsloth/models/cohere.py
index 294e8d0c7e..0b7f3ab973 100644
--- a/unsloth/models/cohere.py
+++ b/unsloth/models/cohere.py
@@ -59,7 +59,11 @@ except:
     CohereFlashAttention2 = CohereAttention
 
 
-def fast_layernorm_inference(self, X, out_weight = None):
+def fast_layernorm_inference(
+    self,
+    X,
+    out_weight = None,
+):
     XX = X.to(torch.float32, copy = True)
     XX -= X.mean(-1, keepdim = True)
     variance = XX.square().mean(-1, keepdim = True)
@@ -124,9 +128,7 @@ def CohereAttention_fast_forward(
     else:
         cos, sin = self.rotary_emb.get_cached(kv_seq_len, Q.device.index)
 
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     # Useful for LongRoPE
     Q, K = fast_rope_embedding(Q, K, cos, sin, rope_position_ids)
 
@@ -184,9 +186,7 @@ def CohereDecoderLayer_fast_forward(
     *args,
     **kwargs,
 ):
-    if use_cache and hasattr(
-        self, "_flag_for_generation"
-    ):  # past_key_value is not None:
+    if use_cache and hasattr(self, "_flag_for_generation"):  # past_key_value is not None:
         out_weight = torch.empty(
             self.input_layernorm.weight.shape,
             dtype = torch.float32,
@@ -195,9 +195,7 @@ def CohereDecoderLayer_fast_forward(
 
         # Self Attention
         residual = hidden_states
-        hidden_states = fast_layernorm_inference(
-            self.input_layernorm, hidden_states, out_weight
-        )
+        hidden_states = fast_layernorm_inference(self.input_layernorm, hidden_states, out_weight)
         hidden_states_attention, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -340,9 +338,7 @@ def CohereAttention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -402,30 +398,22 @@ def CohereAttention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Knn.shape
     if n_groups != 1:
-        Knn = Knn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vnn = Vnn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Knn = Knn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vnn = Vnn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Knn = Knn.reshape(bsz, n_heads, cached_len, head_dim)
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
     # Attention
     if bsz == 1:
-        Qn *= self.scalar  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
+        Qn *= (
+            self.scalar
+        )  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
         # It seems like doing (Q * scalar) @ K is better than (Q @ K) * scalar to stop overflows
-        A = torch_matmul(
-            Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len]
-        )
-        A[:] = torch_nn_functional_softmax(
-            A, dim = -1, dtype = torch.float32
-        )  # .to(A.dtype)
+        A = torch_matmul(Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len])
+        A[:] = torch_nn_functional_softmax(A, dim = -1, dtype = torch.float32)  # .to(A.dtype)
         A = torch_matmul(A, Vnn, out = Qn)
     else:
-        A = scaled_dot_product_attention(
-            Qn, Knn, Vnn, attn_mask = attention_mask, is_causal = False
-        )
+        A = scaled_dot_product_attention(Qn, Knn, Vnn, attn_mask = attention_mask, is_causal = False)
     A = A.transpose(1, 2)
     A = A.reshape(bsz, 1, attention_size)
     A = fast_linear_forward(self.o_proj, A, out = self.temp_O)
@@ -471,22 +459,18 @@ def CohereModel_fast_forward_inference(
     next_decoder_cache = []
     for idx, decoder_layer in enumerate(self.model.layers):
         device_index = getattr(decoder_layer, "_per_layer_device_index", 0)
-        hidden_states, position_ids = move_to_device(
-            device_index, hidden_states, position_ids
-        )
+        hidden_states, position_ids = move_to_device(device_index, hidden_states, position_ids)
         residual = hidden_states
         hidden_states = fast_layernorm_inference(
             decoder_layer.input_layernorm, hidden_states, out_weights[device_index]
         )
-        hidden_states_attention, present_key_value = (
-            CohereAttention_fast_forward_inference(
-                decoder_layer.self_attn,
-                hidden_states = hidden_states,
-                past_key_value = past_key_values[idx],
-                position_ids = position_ids,
-                attention_mask = attention_mask,
-                do_prefill = not hasattr(decoder_layer.self_attn, "paged_attention"),
-            )
+        hidden_states_attention, present_key_value = CohereAttention_fast_forward_inference(
+            decoder_layer.self_attn,
+            hidden_states = hidden_states,
+            past_key_value = past_key_values[idx],
+            position_ids = position_ids,
+            attention_mask = attention_mask,
+            do_prefill = not hasattr(decoder_layer.self_attn, "paged_attention"),
         )
 
         hidden_states_mlp = fast_swiglu_inference(decoder_layer.mlp, hidden_states)
@@ -524,15 +508,11 @@ class FastCohereModel(FastLlamaModel):
         CohereFlashAttention2.forward = CohereAttention_fast_forward
         CohereDecoderLayer.forward = CohereDecoderLayer_fast_forward
         CohereModel.forward = LlamaModel_fast_forward
-        CohereForCausalLM.forward = CausalLM_fast_forward(
-            CohereModel_fast_forward_inference
-        )
+        CohereForCausalLM.forward = CausalLM_fast_forward(CohereModel_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(CohereForCausalLM)
 
         import transformers.models.cohere.modeling_cohere
 
-        transformers.models.cohere.modeling_cohere.CohereRotaryEmbedding = (
-            LlamaRotaryEmbedding
-        )
+        transformers.models.cohere.modeling_cohere.CohereRotaryEmbedding = LlamaRotaryEmbedding
         return
diff --git a/unsloth/models/falcon_h1.py b/unsloth/models/falcon_h1.py
index 659d27de54..3b03333241 100644
--- a/unsloth/models/falcon_h1.py
+++ b/unsloth/models/falcon_h1.py
@@ -41,11 +41,8 @@ try:
     )
 except:
     from transformers import __version__ as transformers_version
-
     transformers_version = Version(transformers_version)
-    if not transformers_version >= Version(
-        "4.53.0"
-    ):  # TODO: Update when transformers is updated
+    if not transformers_version >= Version("4.53.0"):  # TODO: Update when transformers is updated
         raise ImportError(
             f"Unsloth: Your transformers version of {transformers_version} does not support FalconH1.\n"
             f"The minimum required version is 4.53.0.\n"
@@ -129,9 +126,7 @@ def FalconH1Attention_fast_forward(
         rotary_emb.extend_rope_embedding(V, seq_len = kv_seq_len)
         cos, sin = rotary_emb.get_cached(kv_seq_len, Q.device.index)
 
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     # Useful for LongRoPE
     Q, K = fast_rope_embedding(Q, K, cos, sin, rope_position_ids)
 
@@ -149,9 +144,7 @@ def FalconH1Attention_fast_forward(
         and window == (-1, -1)
     )
 
-    backend = (
-        SDPA if attention_mask is not None else select_attention_backend(use_varlen)
-    )
+    backend = SDPA if attention_mask is not None else select_attention_backend(use_varlen)
     attention_config = AttentionConfig(
         backend = backend,
         n_kv_heads = n_kv_heads,
@@ -256,12 +249,8 @@ def FalconH1Attention_fast_forward_inference(
         self.paged_attention_V = self.paged_attention[:, 1]
         self.paged_attention_K[:seq_len] = K1.permute(2, 0, 1, 3)
         self.paged_attention_V[:seq_len] = V1.permute(2, 0, 1, 3)
-        self.temp_QA = torch.empty(
-            (2, bsz, 1, attention_size), dtype = dtype, device = device
-        )
-        self.temp_KV = torch.empty(
-            (2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device
-        )
+        self.temp_QA = torch.empty((2, bsz, 1, attention_size), dtype = dtype, device = device)
+        self.temp_KV = torch.empty((2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device)
         self.RH_Q = torch.empty((bsz, n_heads, 1, head_dim), dtype = dtype, device = device)
 
         # Mistral Nemo 12b has weird dimensions
@@ -287,9 +276,7 @@ def FalconH1Attention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -358,25 +345,19 @@ def FalconH1Attention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Knn.shape
     if bsz == 1 or not SDPA_HAS_GQA and n_groups != 1:
-        Knn = Knn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vnn = Vnn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Knn = Knn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vnn = Vnn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Knn = Knn.reshape(bsz, n_heads, cached_len, head_dim)
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
     # Attention
     if bsz == 1:
-        Qn *= self.scalar  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
+        Qn *= (
+            self.scalar
+        )  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
         # It seems like doing (Q * scalar) @ K is better than (Q @ K) * scalar to stop overflows
-        A = torch_matmul(
-            Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len]
-        )
-        A[:] = torch_nn_functional_softmax(
-            A, dim = -1, dtype = torch.float32
-        )  # .to(A.dtype)
+        A = torch_matmul(Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len])
+        A[:] = torch_nn_functional_softmax(A, dim = -1, dtype = torch.float32)  # .to(A.dtype)
         A = torch_matmul(A, Vnn, out = Qn)
     else:
         if SDPA_HAS_GQA:
@@ -425,9 +406,7 @@ def FalconH1DecoderLayer_fast_forward(
     """
     if use_cache and hasattr(self, "_flag_for_generation"):
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.input_layernorm, hidden_states)
         attention_hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -456,9 +435,7 @@ def FalconH1DecoderLayer_fast_forward(
 
         # Fully Connected
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.pre_ff_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.pre_ff_layernorm, hidden_states)
         hidden_states = fast_swiglu_inference(self.feed_forward, hidden_states)
         hidden_states += residual
     else:
@@ -537,9 +514,7 @@ def _FalconH1_fast_forward_inference(
         residual = torch.empty(
             (bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
         )
-        _XX = torch.empty(
-            (2, bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
-        )
+        _XX = torch.empty((2, bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0")
         XX, XX2 = _XX[0], _XX[1]
         variance = torch.empty(
             (bsz, q_len, 1), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
@@ -571,19 +546,15 @@ def _FalconH1_fast_forward_inference(
                 XX2 = XX2,
                 variance = variance,
             )
-            attention_hidden_states, present_key_value = (
-                attention_fast_forward_inference(
-                    decoder_layer.self_attn,
-                    hidden_states = X * decoder_layer.attention_in_multiplier,
-                    past_key_value = past_key_values[idx],
-                    position_ids = position_ids,
-                    attention_mask = attention_mask,
-                    do_prefill = not hasattr(decoder_layer.self_attn, "paged_attention"),
-                )
-            )
-            attention_hidden_states = (
-                attention_hidden_states * decoder_layer.attn_out_multiplier
+            attention_hidden_states, present_key_value = attention_fast_forward_inference(
+                decoder_layer.self_attn,
+                hidden_states = X * decoder_layer.attention_in_multiplier,
+                past_key_value = past_key_values[idx],
+                position_ids = position_ids,
+                attention_mask = attention_mask,
+                do_prefill = not hasattr(decoder_layer.self_attn, "paged_attention"),
             )
+            attention_hidden_states = attention_hidden_states * decoder_layer.attn_out_multiplier
             mamba_hidden_states = decoder_layer.mamba(
                 hidden_states = X,
                 cache_params = present_key_value,
diff --git a/unsloth/models/gemma.py b/unsloth/models/gemma.py
index cf543ae094..34655c5735 100644
--- a/unsloth/models/gemma.py
+++ b/unsloth/models/gemma.py
@@ -93,9 +93,7 @@ def GemmaDecoderLayer_fast_forward(
     *args,
     **kwargs,
 ):
-    if use_cache and hasattr(
-        self, "_flag_for_generation"
-    ):  # past_key_value is not None:
+    if use_cache and hasattr(self, "_flag_for_generation"):  # past_key_value is not None:
         out_weight = torch.empty(
             self.input_layernorm.weight.shape,
             dtype = torch.float32,
@@ -129,9 +127,7 @@ def GemmaDecoderLayer_fast_forward(
         hidden_states += residual
     else:
         residual = hidden_states
-        hidden_states = fast_rms_layernorm(
-            self.input_layernorm, hidden_states, gemma = True
-        )
+        hidden_states = fast_rms_layernorm(self.input_layernorm, hidden_states, gemma = True)
         hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -147,9 +143,7 @@ def GemmaDecoderLayer_fast_forward(
 
         # Fully Connected
         residual = hidden_states
-        hidden_states = fast_rms_layernorm(
-            self.post_attention_layernorm, hidden_states, gemma = True
-        )
+        hidden_states = fast_rms_layernorm(self.post_attention_layernorm, hidden_states, gemma = True)
         hidden_states = self.mlp(hidden_states)
         hidden_states = residual + hidden_states
 
@@ -187,9 +181,7 @@ def GemmaModel_fast_forward_inference(
     hidden_states = hidden_states.to(_get_dtype(dtype_from_config(self.config)))
     # 3072**0.5 = 55.5000 in bfloat16, whilst 55.4256 in float32
     # 2048**0.5 = 45.2500 in bfloat16, whilst 45.2548 in float32
-    hidden_states *= torch.tensor(
-        math_sqrt(self.config.hidden_size), dtype = hidden_states.dtype
-    )
+    hidden_states *= torch.tensor(math_sqrt(self.config.hidden_size), dtype = hidden_states.dtype)
 
     bsz, q_len, hd = hidden_states.shape
     seq_len = past_key_values[0][0].shape[-2]
@@ -211,9 +203,7 @@ def GemmaModel_fast_forward_inference(
     next_decoder_cache = []
     for idx, decoder_layer in enumerate(self.model.layers):
         device_index = getattr(decoder_layer, "_per_layer_device_index", 0)
-        hidden_states, position_ids = move_to_device(
-            device_index, hidden_states, position_ids
-        )
+        hidden_states, position_ids = move_to_device(device_index, hidden_states, position_ids)
 
         residual = hidden_states
         hidden_states = fast_rms_layernorm_inference_gemma(
@@ -268,20 +258,14 @@ class GemmaFixedRotaryEmbedding(torch.nn.Module):
     ):
         super().__init__()
         # In transformers 5.0+, RotaryEmbedding(config) passes config as first positional arg (dim)
-        if (
-            config is None
-            and dim is not None
-            and hasattr(dim, "max_position_embeddings")
-        ):
+        if config is None and dim is not None and hasattr(dim, "max_position_embeddings"):
             config = dim
             dim = None
         if config is not None:
             # [TODO] Hack to pass in config - need to remove later
             base = _get_rope_theta(config, default = base)
             partial_rotary_factor = (
-                config.partial_rotary_factor
-                if hasattr(config, "partial_rotary_factor")
-                else 1.0
+                config.partial_rotary_factor if hasattr(config, "partial_rotary_factor") else 1.0
             )
             dim = getattr(config, "head_dim", None)
             if dim is None:
@@ -322,9 +306,7 @@ class GemmaFixedRotaryEmbedding(torch.nn.Module):
             torch.arange(self.dim // 2, dtype = torch.int64, device = "cpu").float()
         )
         timescale = self.base**freq_exponents
-        positions = torch.arange(
-            self.current_rope_size, device = "cpu", dtype = torch.int64
-        ).float()
+        positions = torch.arange(self.current_rope_size, device = "cpu", dtype = torch.int64).float()
         radians_new = positions[..., None] / timescale[None, None, :]
         radians_new = radians_new.squeeze(0)
 
@@ -336,7 +318,12 @@ class GemmaFixedRotaryEmbedding(torch.nn.Module):
         self.multi_gpu_sin_cached[device.index] = sin
         return cos, sin
 
-    def forward(self, x, position_ids = None, seq_len = None):
+    def forward(
+        self,
+        x,
+        position_ids = None,
+        seq_len = None,
+    ):
         # x: [bs, num_attention_heads, seq_len, head_size]
         if seq_len is not None and seq_len > self.current_rope_size:
             self._set_cos_sin_cache(seq_len = seq_len, device = x.device, dtype = x.dtype)
@@ -348,12 +335,14 @@ class GemmaFixedRotaryEmbedding(torch.nn.Module):
             self.multi_gpu_sin_cached[device_index][:seq_len],
         )
 
-    def get_cached(self, seq_len = None, device_index = None):
+    def get_cached(
+        self,
+        seq_len = None,
+        device_index = None,
+    ):
         if device_index is None:
             device_index = torch.cuda.current_device()
-        return self.multi_gpu_cos_cached[device_index], self.multi_gpu_sin_cached[
-            device_index
-        ]
+        return self.multi_gpu_cos_cached[device_index], self.multi_gpu_sin_cached[device_index]
 
     def extend_rope_embedding(self, x, seq_len):
         if seq_len <= self.current_rope_size:
@@ -400,9 +389,7 @@ class GemmaFixedLinearScalingRotaryEmbedding(GemmaFixedRotaryEmbedding):
             torch.arange(self.dim // 2, dtype = torch.int64, device = "cpu").float()
         )
         timescale = self.base**freq_exponents
-        positions = torch.arange(
-            self.current_rope_size, device = "cpu", dtype = torch.int64
-        ).float()
+        positions = torch.arange(self.current_rope_size, device = "cpu", dtype = torch.int64).float()
         positions = positions / self.scaling_factor
         radians_new = positions[..., None] / timescale[None, None, :]
         radians_new = radians_new.squeeze(0)
@@ -433,9 +420,7 @@ class FastGemmaModel(FastLlamaModel):
         GemmaFlashAttention2.forward = LlamaAttention_fast_forward
         GemmaDecoderLayer.forward = GemmaDecoderLayer_fast_forward
         GemmaModel.forward = LlamaModel_fast_forward
-        GemmaForCausalLM.forward = CausalLM_fast_forward(
-            GemmaModel_fast_forward_inference
-        )
+        GemmaForCausalLM.forward = CausalLM_fast_forward(GemmaModel_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(GemmaForCausalLM)
 
@@ -446,13 +431,15 @@ class FastGemmaModel(FastLlamaModel):
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.gemma.modeling_gemma
 
-        transformers.models.gemma.modeling_gemma.GemmaRotaryEmbedding = (
-            GemmaFixedRotaryEmbedding
-        )
+        transformers.models.gemma.modeling_gemma.GemmaRotaryEmbedding = GemmaFixedRotaryEmbedding
         return
 
     @staticmethod
-    def post_patch(model, tokenizer, correct_dtype = None):
+    def post_patch(
+        model,
+        tokenizer,
+        correct_dtype = None,
+    ):
         # Gemma does not downcast RoPE
         model, tokenizer = patch_model_and_tokenizer(
             model, tokenizer, downcast_rope = False, correct_dtype = correct_dtype
@@ -480,9 +467,7 @@ class FastGemmaModel(FastLlamaModel):
                 # Leave + 1 to Triton kernel itself
                 # module.weight += 1.0 # return output * (1 + self.weight)
                 if not hasattr(module, "variance_epsilon"):
-                    module.variance_epsilon = (
-                        module.eps
-                    )  # Gemma doesn't use variance_epsilon
+                    module.variance_epsilon = module.eps  # Gemma doesn't use variance_epsilon
 
         # Clear deleted GPU items
         import gc
diff --git a/unsloth/models/gemma2.py b/unsloth/models/gemma2.py
index 720c9a7414..c3398d6554 100644
--- a/unsloth/models/gemma2.py
+++ b/unsloth/models/gemma2.py
@@ -114,9 +114,7 @@ def Gemma2Attention_fast_forward(
     cos = self.rotary_emb.multi_gpu_cos_cached[device_index]
     sin = self.rotary_emb.multi_gpu_sin_cached[device_index]
 
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     if rope_position_ids is not None:
         # Useful for LongRoPE
         cos_var, sin_var = self.rotary_emb.get_cached(kv_seq_len, device_index)
@@ -143,19 +141,11 @@ def Gemma2Attention_fast_forward(
         window = (-1, -1)
         sliding_window = getattr(self.config, "sliding_window", None)
         if has_sliding_window:
-            sliding_window = (
-                sliding_window if sliding_window is not None else kv_seq_len
-            )
-            window = (
-                (-1, -1)
-                if kv_seq_len <= sliding_window
-                else (sliding_window, sliding_window)
-            )
+            sliding_window = sliding_window if sliding_window is not None else kv_seq_len
+            window = (-1, -1) if kv_seq_len <= sliding_window else (sliding_window, sliding_window)
 
         if not hasattr(self, "_flash_attention_softmax_scale"):
-            self._flash_attention_softmax_scale = 1.0 / (
-                self.config.query_pre_attn_scalar**0.5
-            )
+            self._flash_attention_softmax_scale = 1.0 / (self.config.query_pre_attn_scalar**0.5)
 
         use_varlen = seq_info is not None and past_key_value is None
 
@@ -218,9 +208,7 @@ def Gemma2DecoderLayer_fast_forward(
     *args,
     **kwargs,
 ):
-    if use_cache and hasattr(
-        self, "_flag_for_generation"
-    ):  # past_key_value is not None:
+    if use_cache and hasattr(self, "_flag_for_generation"):  # past_key_value is not None:
         out_weight = torch.empty(
             self.input_layernorm.weight.shape,
             dtype = torch.float32,
@@ -261,9 +249,7 @@ def Gemma2DecoderLayer_fast_forward(
         hidden_states += residual
     else:
         residual = hidden_states
-        hidden_states = fast_rms_layernorm(
-            self.input_layernorm, hidden_states, gemma = True
-        )
+        hidden_states = fast_rms_layernorm(self.input_layernorm, hidden_states, gemma = True)
         hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -275,9 +261,7 @@ def Gemma2DecoderLayer_fast_forward(
             padding_mask = padding_mask,
             **kwargs,
         )
-        hidden_states = fast_rms_layernorm(
-            self.post_attention_layernorm, hidden_states, gemma = True
-        )
+        hidden_states = fast_rms_layernorm(self.post_attention_layernorm, hidden_states, gemma = True)
         hidden_states = residual + hidden_states
 
         # Fully Connected
@@ -346,12 +330,8 @@ def Gemma2Attention_fast_forward_inference(
         self.paged_attention_V = self.paged_attention[:, 1]
         self.paged_attention_K[:seq_len] = K1.permute(2, 0, 1, 3)
         self.paged_attention_V[:seq_len] = V1.permute(2, 0, 1, 3)
-        self.temp_QA = torch.empty(
-            (2, bsz, 1, attention_size), dtype = dtype, device = device
-        )
-        self.temp_KV = torch.empty(
-            (2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device
-        )
+        self.temp_QA = torch.empty((2, bsz, 1, attention_size), dtype = dtype, device = device)
+        self.temp_KV = torch.empty((2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device)
         self.RH_Q = torch.empty((bsz, n_heads, 1, head_dim), dtype = dtype, device = device)
         # Only for Gemma2
         self.temp_O = torch.empty((bsz, 1, hidden_size), dtype = dtype, device = device)
@@ -380,9 +360,7 @@ def Gemma2Attention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -437,12 +415,8 @@ def Gemma2Attention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Knn.shape
     if n_groups != 1:
-        Knn = Knn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vnn = Vnn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Knn = Knn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vnn = Vnn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Knn = Knn.reshape(bsz, n_heads, cached_len, head_dim)
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
@@ -500,9 +474,7 @@ def Gemma2Model_fast_forward_inference(
     hidden_states = hidden_states.to(_get_dtype(dtype_from_config(self.config)))
     # 3072**0.5 = 55.5000 in bfloat16, whilst 55.4256 in float32
     # 2048**0.5 = 45.2500 in bfloat16, whilst 45.2548 in float32
-    hidden_states *= torch.tensor(
-        math_sqrt(self.config.hidden_size), dtype = hidden_states.dtype
-    )
+    hidden_states *= torch.tensor(math_sqrt(self.config.hidden_size), dtype = hidden_states.dtype)
 
     bsz, q_len, hd = hidden_states.shape
     seq_len = past_key_values[0][0].shape[-2]
@@ -532,9 +504,7 @@ def Gemma2Model_fast_forward_inference(
         # For pipeline parallelism, we need to move all tensors to the same device
         # note that this movement is once per GPU in PP
         device_index = getattr(decoder_layer, "_per_layer_device_index", 0)
-        hidden_states, position_ids = move_to_device(
-            device_index, hidden_states, position_ids
-        )
+        hidden_states, position_ids = move_to_device(device_index, hidden_states, position_ids)
 
         use_sliding_window = idx % 2 == 0
 
@@ -602,9 +572,7 @@ class FastGemma2Model(FastLlamaModel):
         Gemma2FlashAttention2.forward = Gemma2Attention_fast_forward
         Gemma2DecoderLayer.forward = Gemma2DecoderLayer_fast_forward
         Gemma2Model.forward = LlamaModel_fast_forward
-        Gemma2ForCausalLM.forward = CausalLM_fast_forward(
-            Gemma2Model_fast_forward_inference
-        )
+        Gemma2ForCausalLM.forward = CausalLM_fast_forward(Gemma2Model_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(Gemma2ForCausalLM)
 
@@ -615,13 +583,15 @@ class FastGemma2Model(FastLlamaModel):
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.gemma2.modeling_gemma2
 
-        transformers.models.gemma2.modeling_gemma2.Gemma2RotaryEmbedding = (
-            GemmaFixedRotaryEmbedding
-        )
+        transformers.models.gemma2.modeling_gemma2.Gemma2RotaryEmbedding = GemmaFixedRotaryEmbedding
         return
 
     @staticmethod
-    def post_patch(model, tokenizer, correct_dtype = None):
+    def post_patch(
+        model,
+        tokenizer,
+        correct_dtype = None,
+    ):
         # Gemma does not downcast RoPE
         model, tokenizer = patch_model_and_tokenizer(
             model, tokenizer, downcast_rope = False, correct_dtype = correct_dtype
@@ -649,9 +619,7 @@ class FastGemma2Model(FastLlamaModel):
                 # Leave + 1 to Triton kernel itself
                 # module.weight += 1.0 # return output * (1 + self.weight)
                 if not hasattr(module, "variance_epsilon"):
-                    module.variance_epsilon = (
-                        module.eps
-                    )  # Gemma doesn't use variance_epsilon
+                    module.variance_epsilon = module.eps  # Gemma doesn't use variance_epsilon
 
         # Clear deleted GPU items
         import gc
diff --git a/unsloth/models/glm4_moe.py b/unsloth/models/glm4_moe.py
index 5d04b2f1d0..e5fd88acbc 100644
--- a/unsloth/models/glm4_moe.py
+++ b/unsloth/models/glm4_moe.py
@@ -70,10 +70,7 @@ try:
     HAS_GROUPED_GEMM = True
 except ImportError as e:
     import warnings
-
-    warnings.warn(
-        f"Grouped GEMM not available: {e}. MoE will use fallback implementation."
-    )
+    warnings.warn(f"Grouped GEMM not available: {e}. MoE will use fallback implementation.")
 
 
 # Import transformers GLM4 MoE Lite classes
@@ -89,7 +86,6 @@ try:
         Glm4MoeLiteForCausalLM,
         Glm4MoeLiteRMSNorm,
     )
-
     HAS_GLM4_MOE = True
 except ImportError:
     HAS_GLM4_MOE = False
@@ -194,8 +190,7 @@ def Glm4MoeLiteMoE_fast_forward(self, hidden_states):
 
         # Merge topk weights: [num_tokens, top_k, hidden_dim] -> [num_tokens, hidden_dim]
         hidden_states = (
-            expert_output.view(num_tokens, self.top_k, hidden_dim)
-            * topk_weights.unsqueeze(-1)
+            expert_output.view(num_tokens, self.top_k, hidden_dim) * topk_weights.unsqueeze(-1)
         ).sum(dim = 1)
     else:
         # Fallback to naive implementation
@@ -208,10 +203,7 @@ def Glm4MoeLiteMoE_fast_forward(self, hidden_states):
 
 
 def Glm4MoeLiteNaiveMoe_fast_forward(
-    self,
-    hidden_states: torch.Tensor,
-    top_k_index: torch.Tensor,
-    top_k_weights: torch.Tensor,
+    self, hidden_states: torch.Tensor, top_k_index: torch.Tensor, top_k_weights: torch.Tensor
 ) -> torch.Tensor:
     """
     Optimized expert forward using grouped GEMM.
@@ -233,9 +225,7 @@ def Glm4MoeLiteNaiveMoe_fast_forward(
         # Fallback to original naive implementation
         final_hidden_states = torch.zeros_like(hidden_states)
         with torch.no_grad():
-            expert_mask = torch.nn.functional.one_hot(
-                top_k_index, num_classes = self.num_experts
-            )
+            expert_mask = torch.nn.functional.one_hot(top_k_index, num_classes = self.num_experts)
             expert_mask = expert_mask.permute(2, 1, 0)
             expert_hit = torch.greater(expert_mask.sum(dim = (-1, -2)), 0).nonzero()
 
@@ -263,9 +253,7 @@ def Glm4MoeLiteNaiveMoe_fast_forward(
 
     # Get routing indices for grouped GEMM
     with torch.no_grad():
-        token_counts_by_expert, gather_indices = get_routing_indices(
-            top_k_index, self.num_experts
-        )
+        token_counts_by_expert, gather_indices = get_routing_indices(top_k_index, self.num_experts)
 
     # Cast hidden_states to match expert weights dtype
     # Under autocast, hidden_states may be fp32 while weights are bf16
@@ -329,9 +317,7 @@ def Glm4MoeLiteDecoderLayer_fast_forward(
     if is_inference:
         # Self-attention with fast inference path
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.input_layernorm, hidden_states)
         hidden_states, _ = self.self_attn(
             hidden_states = hidden_states,
             attention_mask = attention_mask,
@@ -346,9 +332,7 @@ def Glm4MoeLiteDecoderLayer_fast_forward(
 
         # MLP/MoE
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.post_attention_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.post_attention_layernorm, hidden_states)
         hidden_states = self.mlp(hidden_states)
         hidden_states = residual + hidden_states
     else:
diff --git a/unsloth/models/granite.py b/unsloth/models/granite.py
index fea3dc1b36..084dc7722f 100644
--- a/unsloth/models/granite.py
+++ b/unsloth/models/granite.py
@@ -110,9 +110,7 @@ def GraniteAttention_fast_forward(
 
     assert position_embeddings is not None
     cos, sin = position_embeddings
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     if rope_position_ids is not None:
         # Useful for LongRoPE
         Q, K = fast_rope_embedding(Q, K, cos, sin, rope_position_ids)
@@ -125,13 +123,9 @@ def GraniteAttention_fast_forward(
     past_key_value = (K, V) if use_cache else None
 
     # Attention module
-    use_varlen = (
-        attention_mask is None and seq_info is not None and past_key_value is None
-    )
+    use_varlen = attention_mask is None and seq_info is not None and past_key_value is None
 
-    backend = (
-        SDPA if attention_mask is not None else select_attention_backend(use_varlen)
-    )
+    backend = SDPA if attention_mask is not None else select_attention_backend(use_varlen)
 
     window = (kv_seq_len, kv_seq_len)
     softmax_scale = getattr(self, "scaling", None)
@@ -205,13 +199,9 @@ def GraniteDecoderLayer_fast_forward(
         else self.config.residual_multiplier
     )
 
-    if use_cache and hasattr(
-        self, "_flag_for_generation"
-    ):  # past_key_value is not None:
+    if use_cache and hasattr(self, "_flag_for_generation"):  # past_key_value is not None:
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.input_layernorm, hidden_states)
         hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -229,9 +219,7 @@ def GraniteDecoderLayer_fast_forward(
 
         # Fully Connected
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.post_attention_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.post_attention_layernorm, hidden_states)
         hidden_states = fast_swiglu_inference(self.mlp, hidden_states)
         hidden_states = torch.add(residual, hidden_states, alpha = residual_multiplier)
     else:
@@ -316,12 +304,8 @@ def GraniteAttention_fast_forward_inference(
         self.paged_attention_V = self.paged_attention[:, 1]
         self.paged_attention_K[:seq_len] = K1.permute(2, 0, 1, 3)
         self.paged_attention_V[:seq_len] = V1.permute(2, 0, 1, 3)
-        self.temp_QA = torch.empty(
-            (2, bsz, 1, attention_size), dtype = dtype, device = device
-        )
-        self.temp_KV = torch.empty(
-            (2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device
-        )
+        self.temp_QA = torch.empty((2, bsz, 1, attention_size), dtype = dtype, device = device)
+        self.temp_KV = torch.empty((2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device)
         self.RH_Q = torch.empty((bsz, n_heads, 1, head_dim), dtype = dtype, device = device)
         self.temp_O = torch.empty((bsz, 1, hidden_size), dtype = dtype, device = device)
         self.attention = torch.empty(
@@ -341,9 +325,7 @@ def GraniteAttention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -388,21 +370,15 @@ def GraniteAttention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Kn.shape
     if bsz == 1 or ((not SDPA_HAS_GQA) and n_groups != 1):
-        Kn = Kn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vn = Vn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Kn = Kn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vn = Vn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Kn = Kn.reshape(bsz, n_heads, cached_len, head_dim)
         Vn = Vn.reshape(bsz, n_heads, cached_len, head_dim)
 
     # Attention
     if bsz == 1:
         Qn *= self.scaling
-        A = torch_matmul(
-            Qn, Kn.transpose(2, 3), out = self.attention[:, :, :, :cached_len]
-        )
+        A = torch_matmul(Qn, Kn.transpose(2, 3), out = self.attention[:, :, :, :cached_len])
         A[:] = torch_nn_functional_softmax(A, dim = -1, dtype = torch.float32)
         A = torch_matmul(A, Vn, out = Qn)
     else:
@@ -476,14 +452,10 @@ def GraniteModel_fast_forward_inference(
     next_decoder_cache = []
     for idx, decoder_layer in enumerate(self.model.layers):
         device_index = getattr(decoder_layer, "_per_layer_device_index", 0)
-        hidden_states, position_ids = move_to_device(
-            device_index, hidden_states, position_ids
-        )
+        hidden_states, position_ids = move_to_device(device_index, hidden_states, position_ids)
 
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            decoder_layer.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(decoder_layer.input_layernorm, hidden_states)
         hidden_states, present_key_value = GraniteAttention_fast_forward_inference(
             decoder_layer.self_attn,
             hidden_states = hidden_states,
@@ -550,23 +522,23 @@ class FastGraniteModel(FastLlamaModel):
         GraniteFlashAttention2.forward = GraniteAttention_fast_forward
         GraniteDecoderLayer.forward = GraniteDecoderLayer_fast_forward
         GraniteModel.forward = LlamaModel_fast_forward
-        GraniteForCausalLM.forward = CausalLM_fast_forward(
-            GraniteModel_fast_forward_inference
-        )
+        GraniteForCausalLM.forward = CausalLM_fast_forward(GraniteModel_fast_forward_inference)
         GraniteForCausalLM.__init__ = patched_init(GraniteForCausalLM.__init__)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(GraniteForCausalLM)
 
         import transformers.models.granite.modeling_granite
 
-        transformers.models.granite.modeling_granite.GraniteRotaryEmbedding = (
-            GraniteRotaryEmbedding
-        )
+        transformers.models.granite.modeling_granite.GraniteRotaryEmbedding = GraniteRotaryEmbedding
 
         return
 
     @staticmethod
-    def post_patch(model, tokenizer, correct_dtype = None):
+    def post_patch(
+        model,
+        tokenizer,
+        correct_dtype = None,
+    ):
         # Torch.compile fails on embedding matrix??
         # Workaround randomnly fixes it for torch versions < 2.2
         model.model.embed_tokens = torch.nn.Embedding.from_pretrained(
@@ -583,10 +555,7 @@ class FastGraniteModel(FastLlamaModel):
         model.lm_head = lm_head
 
         # Granite has tied weights! This means lm_head == embed_tokens
-        if (
-            model.model.embed_tokens.weight.data_ptr()
-            != model.lm_head.weight.data_ptr()
-        ):
+        if model.model.embed_tokens.weight.data_ptr() != model.lm_head.weight.data_ptr():
             lm_head = torch.nn.Linear(1, 1, bias = None)
             del lm_head.weight
             lm_head.weight = model.model.embed_tokens.weight
@@ -605,17 +574,13 @@ class FastGraniteModel(FastLlamaModel):
 
                 if type(quant_state) is list:
                     # BnB seems to have float16 as default!
-                    module.weight.quant_state[2] = (
-                        correct_dtype  # Cast to correct dtype
-                    )
+                    module.weight.quant_state[2] = correct_dtype  # Cast to correct dtype
                 else:
                     # https://github.com/TimDettmers/bitsandbytes/pull/763/files
                     quant_state.dtype = correct_dtype
             # Downcast RoPE embedding to correct data type
             if name.endswith("rotary_emb") or hasattr(module, "cos_cached"):
-                if hasattr(module, "cos_cached") and (
-                    module.cos_cached.dtype != correct_dtype
-                ):
+                if hasattr(module, "cos_cached") and (module.cos_cached.dtype != correct_dtype):
                     module.cos_cached = module.cos_cached.to(correct_dtype)
                     module.sin_cached = module.sin_cached.to(correct_dtype)
 
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 7af2a7d136..945d827573 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -119,9 +119,7 @@ except:
 from triton import __version__ as triton_version
 
 HAS_XFORMERS = xformers is not None
-BlockDiagonalCausalMask = (
-    xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else None
-)
+BlockDiagonalCausalMask = xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else None
 
 if DEVICE_TYPE == "xpu":
     clean_gpu_cache = torch.xpu.empty_cache
@@ -195,9 +193,7 @@ def _offload_frozen_module_for_training(
         # Tesla T4 must use float32 and not float16
         new_dtype = torch.float32
 
-    module.modules_to_save.default.to(
-        device = device_type, dtype = new_dtype, non_blocking = True
-    )
+    module.modules_to_save.default.to(device = device_type, dtype = new_dtype, non_blocking = True)
     module.modules_to_save.default.requires_grad_(True)
 
     # [TODO] Move old module to CPU - should be disk!
@@ -238,10 +234,7 @@ def _fast_prepare_inputs_for_generation(
             kwargs["past_key_values"] = None
             use_inputs_embeds = inputs_embeds is not None
         # New since 4.56
-        elif (
-            hasattr(past_key_values, "get_seq_length")
-            and past_key_values.get_seq_length() == 0
-        ):
+        elif hasattr(past_key_values, "get_seq_length") and past_key_values.get_seq_length() == 0:
             past_key_values = None
             kwargs["past_key_values"] = None
             use_inputs_embeds = inputs_embeds is not None
@@ -282,10 +275,7 @@ def _fast_prepare_inputs_for_generation(
                     dtype = torch.long,
                 )
             else:
-                if (
-                    hasattr(cache_position, "device")
-                    and cache_position.device != device
-                ):
+                if hasattr(cache_position, "device") and cache_position.device != device:
                     kwargs["cache_position"] = cache_position.to(device)
 
             # Get to the base model
@@ -293,9 +283,7 @@ def _fast_prepare_inputs_for_generation(
             if hasattr(base_model, "base_model_prefix"):
                 base_model = getattr(base_model, base_model.base_model_prefix)
 
-            if hasattr(
-                base_model, "_prepare_4d_causal_attention_mask_with_cache_position"
-            ):
+            if hasattr(base_model, "_prepare_4d_causal_attention_mask_with_cache_position"):
                 if not hasattr(base_model, "_unsloth_mask_needs_device"):
 
                     def _check_needs_device(fn) -> bool:
@@ -312,10 +300,7 @@ def _fast_prepare_inputs_for_generation(
 
                 if max_cache_len is not None:
                     target_length = max_cache_len
-                elif (
-                    original_attention_mask is not None
-                    and original_attention_mask.dim() == 2
-                ):
+                elif original_attention_mask is not None and original_attention_mask.dim() == 2:
                     target_length = original_attention_mask.shape[-1]
                 else:
                     target_length = past_len + seq_length
@@ -332,11 +317,9 @@ def _fast_prepare_inputs_for_generation(
                 if base_model._unsloth_mask_needs_device:
                     mask_kwargs["device"] = device
 
-                attention_mask = (
-                    base_model._prepare_4d_causal_attention_mask_with_cache_position(
-                        attention_mask,
-                        **mask_kwargs,
-                    )
+                attention_mask = base_model._prepare_4d_causal_attention_mask_with_cache_position(
+                    attention_mask,
+                    **mask_kwargs,
                 )
             else:
                 if transformers_version <= Version("4.52.4"):
@@ -446,12 +429,8 @@ def LlamaAttention_fast_forward_inference(
         self.paged_attention_V = self.paged_attention[:, 1]
         self.paged_attention_K[:seq_len] = K1.permute(2, 0, 1, 3)
         self.paged_attention_V[:seq_len] = V1.permute(2, 0, 1, 3)
-        self.temp_QA = torch.empty(
-            (2, bsz, 1, attention_size), dtype = dtype, device = device
-        )
-        self.temp_KV = torch.empty(
-            (2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device
-        )
+        self.temp_QA = torch.empty((2, bsz, 1, attention_size), dtype = dtype, device = device)
+        self.temp_KV = torch.empty((2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device)
         self.RH_Q = torch.empty((bsz, n_heads, 1, head_dim), dtype = dtype, device = device)
 
         # Mistral Nemo 12b has weird dimensions
@@ -477,9 +456,7 @@ def LlamaAttention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -551,12 +528,8 @@ def LlamaAttention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Knn.shape
     if bsz == 1 or ((not SDPA_HAS_GQA) and n_groups != 1):
-        Knn = Knn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vnn = Vnn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Knn = Knn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vnn = Vnn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Knn = Knn.reshape(bsz, n_heads, cached_len, head_dim)
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
@@ -569,14 +542,12 @@ def LlamaAttention_fast_forward_inference(
         is_causal = False
     # Attention
     if bsz == 1:
-        Qn *= self.scalar  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
+        Qn *= (
+            self.scalar
+        )  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
         # It seems like doing (Q * scalar) @ K is better than (Q @ K) * scalar to stop overflows
-        A = torch_matmul(
-            Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len]
-        )
-        A[:] = torch_nn_functional_softmax(
-            A, dim = -1, dtype = torch.float32
-        )  # .to(A.dtype)
+        A = torch_matmul(Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len])
+        A[:] = torch_nn_functional_softmax(A, dim = -1, dtype = torch.float32)  # .to(A.dtype)
         A = torch_matmul(A, Vnn, out = Qn)
     # --- attention_mask fixup for SDPA if user passes 2D padding mask
     else:
@@ -614,7 +585,12 @@ torch_nn_functional_silu = torch.nn.functional.silu
 
 
 def fast_swiglu_inference(
-    self, X, temp_gate = None, temp_up = None, gate_multiplier = None, down_multiplier = None
+    self,
+    X,
+    temp_gate = None,
+    temp_up = None,
+    gate_multiplier = None,
+    down_multiplier = None,
 ):
     # gate = self.gate_proj(X)
     # up   = self.up_proj(X)
@@ -645,7 +621,13 @@ torch_square = torch.square
 torch_mean = torch.mean
 
 
-def fast_rms_layernorm_inference(self, X, XX = None, XX2 = None, variance = None):
+def fast_rms_layernorm_inference(
+    self,
+    X,
+    XX = None,
+    XX2 = None,
+    variance = None,
+):
     old_dtype = X.dtype
     if XX is None:
         XX = X.to(torch.float32)
@@ -665,7 +647,11 @@ def fast_rms_layernorm_inference(self, X, XX = None, XX2 = None, variance = None
     return X
 
 
-def fast_rms_layernorm_inference_gemma(self, X, out_weight = None):
+def fast_rms_layernorm_inference_gemma(
+    self,
+    X,
+    out_weight = None,
+):
     XX = X.to(torch.float32)
     variance = XX.square().mean(-1, keepdim = True)
     variance += self.variance_epsilon
@@ -765,9 +751,7 @@ def LlamaAttention_fast_forward(
 
     # Attention module
     use_varlen = seq_info is not None and past_key_value is None
-    backend = (
-        SDPA if attention_mask is not None else select_attention_backend(use_varlen)
-    )
+    backend = SDPA if attention_mask is not None else select_attention_backend(use_varlen)
 
     # should dropout be hardcoded to 0.0?
     config = AttentionConfig(
@@ -826,9 +810,7 @@ def LlamaDecoderLayer_fast_forward(
     """
     if use_cache and hasattr(self, "_flag_for_generation"):
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.input_layernorm, hidden_states)
         hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -845,9 +827,7 @@ def LlamaDecoderLayer_fast_forward(
 
         # Fully Connected
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.post_attention_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.post_attention_layernorm, hidden_states)
         hidden_states = fast_swiglu_inference(self.mlp, hidden_states)
         hidden_states += residual
     else:
@@ -909,9 +889,7 @@ def LlamaModel_fast_forward(
     **kwargs,
 ) -> Union[Tuple, BaseModelOutputWithPast]:
     output_attentions = (
-        output_attentions
-        if output_attentions is not None
-        else self.config.output_attentions
+        output_attentions if output_attentions is not None else self.config.output_attentions
     )
     assert output_attentions is False
     output_hidden_states = (
@@ -921,9 +899,7 @@ def LlamaModel_fast_forward(
     )
     use_cache = use_cache if use_cache is not None else self.config.use_cache
 
-    return_dict = (
-        return_dict if return_dict is not None else self.config.use_return_dict
-    )
+    return_dict = return_dict if return_dict is not None else self.config.use_return_dict
 
     # retrieve input_ids and inputs_embeds
     if input_ids is not None and inputs_embeds is not None:
@@ -956,10 +932,7 @@ def LlamaModel_fast_forward(
             input_ids = input_ids[:, : self.max_seq_length]
         elif inputs_embeds is not None:
             inputs_embeds = inputs_embeds[:, : self.max_seq_length, :]
-        if (
-            attention_mask is not None
-            and attention_mask.shape[-1] > self.max_seq_length
-        ):
+        if attention_mask is not None and attention_mask.shape[-1] > self.max_seq_length:
             attention_mask = attention_mask[:, : self.max_seq_length]
 
     past_key_values_length = 0
@@ -1006,9 +979,7 @@ def LlamaModel_fast_forward(
         # inputs_embeds *= math_sqrt(self.config.hidden_size)
         # Ie 3072**0.5 = 55.5000 in bfloat16, whilst 55.4256 in float32
         # &  2048**0.5 = 45.2500 in bfloat16, whilst 45.2548 in float32
-        normalizer = torch.tensor(
-            math_sqrt(self.config.hidden_size), dtype = inputs_embeds.dtype
-        )
+        normalizer = torch.tensor(math_sqrt(self.config.hidden_size), dtype = inputs_embeds.dtype)
 
         if train_embed_tokens:
             # Careful we must not do an inplace op!
@@ -1179,10 +1150,7 @@ def LlamaModel_fast_forward(
 
     if (
         IS_ATTENTION_REFACTOR
-        and (
-            hasattr(self, "rotary_emb")
-            or not hasattr(self.layers[0].self_attn, "rotary_emb")
-        )
+        and (hasattr(self, "rotary_emb") or not hasattr(self.layers[0].self_attn, "rotary_emb"))
     ) or IS_GRANITE:
         # Transformers main has made it mandatory to pass position_embeddings
         # https://github.com/huggingface/transformers/pull/34858
@@ -1190,9 +1158,7 @@ def LlamaModel_fast_forward(
         # unsloth's check for granite too has "version >= 4.45.0 (rightly so)".
         # so let granite always use the attention refactor implementation.
 
-        self.rotary_emb.extend_rope_embedding(
-            hidden_states, self.config.max_position_embeddings
-        )
+        self.rotary_emb.extend_rope_embedding(hidden_states, self.config.max_position_embeddings)
         position_embeddings = self.rotary_emb.get_cached(
             self.config.max_position_embeddings, hidden_states.device.index
         )
@@ -1214,9 +1180,7 @@ def LlamaModel_fast_forward(
                 mask = self.GA_mask if use_static_mask else dynamic_GA_mask
             kwargs["use_sliding_window"] = use_sliding_window
 
-        if gradient_checkpointing and not isinstance(
-            decoder_layer, GradientCheckpointingLayer
-        ):
+        if gradient_checkpointing and not isinstance(decoder_layer, GradientCheckpointingLayer):
 
             def create_custom_forward(module):
                 def custom_forward(*inputs):
@@ -1265,21 +1229,15 @@ def LlamaModel_fast_forward(
     # Final layernorm
     if use_cache:
         if IS_FALCON_H1:
-            hidden_states = fast_rms_layernorm_inference(
-                self.final_layernorm, hidden_states
-            )
+            hidden_states = fast_rms_layernorm_inference(self.final_layernorm, hidden_states)
         else:
             hidden_states = (
-                fast_rms_layernorm_inference_gemma
-                if IS_GEMMA
-                else fast_rms_layernorm_inference
+                fast_rms_layernorm_inference_gemma if IS_GEMMA else fast_rms_layernorm_inference
             )(self.norm, hidden_states)
     elif IS_COHERE:
         hidden_states = self.norm(hidden_states)
     elif IS_FALCON_H1:
-        hidden_states = fast_rms_layernorm(
-            self.final_layernorm, hidden_states, gemma = IS_GEMMA
-        )
+        hidden_states = fast_rms_layernorm(self.final_layernorm, hidden_states, gemma = IS_GEMMA)
     else:
         hidden_states = fast_rms_layernorm(self.norm, hidden_states, gemma = IS_GEMMA)
 
@@ -1329,9 +1287,7 @@ def _LlamaModel_fast_forward_inference(
         residual = torch.empty(
             (bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
         )
-        _XX = torch.empty(
-            (2, bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
-        )
+        _XX = torch.empty((2, bsz, q_len, hd), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0")
         XX, XX2 = _XX[0], _XX[1]
         variance = torch.empty(
             (bsz, q_len, 1), dtype = torch.float32, device = f"{DEVICE_TYPE_TORCH}:0"
@@ -1367,9 +1323,7 @@ def _LlamaModel_fast_forward_inference(
 
         for idx, decoder_layer in enumerate(self.model.layers):
             device_index = getattr(decoder_layer, "_per_layer_device_index", 0)
-            X, residual, position_ids = move_to_device(
-                device_index, X, residual, position_ids
-            )
+            X, residual, position_ids = move_to_device(device_index, X, residual, position_ids)
             residual.copy_(X)  # residual = X
             X = fast_rms_layernorm_inference(
                 decoder_layer.input_layernorm,
@@ -1457,9 +1411,7 @@ def CausalLM_fast_forward(fast_forward_inference):
                 **kwargs,
             )
         else:
-            causal_mask = (
-                xformers.attn_bias.LowerTriangularMask() if HAS_XFORMERS else None
-            )
+            causal_mask = xformers.attn_bias.LowerTriangularMask() if HAS_XFORMERS else None
 
             output_attentions = (
                 output_attentions
@@ -1471,9 +1423,7 @@ def CausalLM_fast_forward(fast_forward_inference):
                 if output_hidden_states is not None
                 else self.config.output_hidden_states
             )
-            return_dict = (
-                return_dict if return_dict is not None else self.config.use_return_dict
-            )
+            return_dict = return_dict if return_dict is not None else self.config.use_return_dict
             # decoder outputs consists of (dec_features, layer_state, dec_hidden, dec_attn)
             self.model._has_no_labels = labels is None
             outputs = self.model(
@@ -1499,9 +1449,7 @@ def CausalLM_fast_forward(fast_forward_inference):
         logit_scaling = getattr(self.config, "logit_scale", 0)
         dtype = lm_head.dtype
         # Skip int max() if either is a tensor (HF selective-decode form).
-        if isinstance(num_logits_to_keep, torch.Tensor) or isinstance(
-            logits_to_keep, torch.Tensor
-        ):
+        if isinstance(num_logits_to_keep, torch.Tensor) or isinstance(logits_to_keep, torch.Tensor):
             num_logits_to_keep = 0
         else:
             num_logits_to_keep = max(num_logits_to_keep, logits_to_keep)
@@ -1725,9 +1673,7 @@ class LlamaRotaryEmbedding(torch.nn.Module):
             # [TODO] Hack to pass in config - need to remove later
             base = _get_rope_theta(config, default = base)
             partial_rotary_factor = (
-                config.partial_rotary_factor
-                if hasattr(config, "partial_rotary_factor")
-                else 1.0
+                config.partial_rotary_factor if hasattr(config, "partial_rotary_factor") else 1.0
             )
             dim = getattr(config, "head_dim", None)
             if dim is None:
@@ -1746,10 +1692,7 @@ class LlamaRotaryEmbedding(torch.nn.Module):
         # Normal Llama-3 RoPE
         inv_freq = 1.0 / (
             self.base
-            ** (
-                torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float()
-                / self.dim
-            )
+            ** (torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float() / self.dim)
         )
         inv_freq = self._apply_inv_freq_scaling(inv_freq)
         self.register_buffer("inv_freq", inv_freq, persistent = False)
@@ -1796,7 +1739,12 @@ class LlamaRotaryEmbedding(torch.nn.Module):
         self.multi_gpu_sin_cached[device.index] = sin
         return cos, sin
 
-    def forward(self, x, position_ids = None, seq_len = None):
+    def forward(
+        self,
+        x,
+        position_ids = None,
+        seq_len = None,
+    ):
         # x: [bs, num_attention_heads, seq_len, head_size]
         if seq_len is not None and seq_len > self.current_rope_size:
             self._set_cos_sin_cache(seq_len = seq_len, device = x.device, dtype = x.dtype)
@@ -1807,12 +1755,14 @@ class LlamaRotaryEmbedding(torch.nn.Module):
             self.multi_gpu_sin_cached[device_index][:seq_len],
         )
 
-    def get_cached(self, seq_len = None, device_index = None):
+    def get_cached(
+        self,
+        seq_len = None,
+        device_index = None,
+    ):
         if device_index is None:
             device_index = get_current_device()
-        return self.multi_gpu_cos_cached[device_index], self.multi_gpu_sin_cached[
-            device_index
-        ]
+        return self.multi_gpu_cos_cached[device_index], self.multi_gpu_sin_cached[device_index]
 
     def extend_rope_embedding(self, x, seq_len):
         if seq_len <= self.current_rope_size:
@@ -1921,9 +1871,7 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
             # [TODO] Hack to pass in config - need to remove later
             base = _get_rope_theta(config, default = base)
             partial_rotary_factor = (
-                config.partial_rotary_factor
-                if hasattr(config, "partial_rotary_factor")
-                else 1.0
+                config.partial_rotary_factor if hasattr(config, "partial_rotary_factor") else 1.0
             )
             dim = int((config.hidden_size // config.num_attention_heads))
             device = DEVICE_TYPE_TORCH
@@ -1934,9 +1882,7 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
         self.original_max_position_embeddings = original_max_position_embeddings
         self.base = base
         # Dynamic RoPE we first set it to a max of 4 * 8192 tokens then we iteratively grow this
-        self.current_rope_size = min(
-            original_max_position_embeddings, self.max_position_embeddings
-        )
+        self.current_rope_size = min(original_max_position_embeddings, self.max_position_embeddings)
         self.multi_gpu_short_cos_cached = [None] * DEVICE_COUNT
         self.multi_gpu_short_sin_cached = [None] * DEVICE_COUNT
         self.multi_gpu_long_cos_cached = [None] * DEVICE_COUNT
@@ -1945,8 +1891,7 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
         # Long RoPE similar to RoPE except short sequences have 1 cos / sin
         # and long sequences have another cos / sin
         inv_freq_shape = (
-            torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float()
-            / self.dim
+            torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float() / self.dim
         )
         short_factor = torch.tensor(short_factor, device = "cpu", dtype = torch.float32)
         long_factor = torch.tensor(long_factor, device = "cpu", dtype = torch.float32)
@@ -2024,7 +1969,12 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
         self.multi_gpu_long_sin_cached[device.index] = sin_cached
         return cos_cached, sin_cached
 
-    def forward(self, x, position_ids = None, seq_len = None):
+    def forward(
+        self,
+        x,
+        position_ids = None,
+        seq_len = None,
+    ):
         # x: [bs, num_attention_heads, seq_len, head_size]
         if seq_len is not None and seq_len > self.current_rope_size:
             self._set_cos_sin_cache(seq_len = seq_len, device = x.device, dtype = x.dtype)
@@ -2042,16 +1992,20 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
                 self.multi_gpu_long_sin_cached[device_index][:seq_len],
             )
 
-    def get_cached(self, seq_len = None, device_index = None):
+    def get_cached(
+        self,
+        seq_len = None,
+        device_index = None,
+    ):
         if device_index is None:
             device_index = get_current_device()
         if seq_len is not None and seq_len < self.original_max_position_embeddings:
-            return self.multi_gpu_short_cos_cached[
+            return self.multi_gpu_short_cos_cached[device_index], self.multi_gpu_short_sin_cached[
                 device_index
-            ], self.multi_gpu_short_sin_cached[device_index]
-        return self.multi_gpu_long_cos_cached[
+            ]
+        return self.multi_gpu_long_cos_cached[device_index], self.multi_gpu_long_sin_cached[
             device_index
-        ], self.multi_gpu_long_sin_cached[device_index]
+        ]
 
     def extend_rope_embedding(self, x, seq_len):
         if seq_len <= self.current_rope_size:
@@ -2064,24 +2018,14 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
             )
 
 
-def unsloth_fast_generate(
-    self,
-    *args,
-    **kwargs,
-):
+def unsloth_fast_generate(self, *args, **kwargs):
     # If the model starts out in training mode, restore training mode after generation
     restore_training_mode = self.training
     # why: snapshot the actual GC mode value (e.g. "unsloth") before for_inference
     # clears it, so the post-generate restore preserves the caller's configured GC
     # mode rather than collapsing it to a plain bool.
     use_gradient_checkpointing = next(
-        (
-            v
-            for v in (
-                getattr(m, "gradient_checkpointing", False) for m in self.modules()
-            )
-            if v
-        ),
+        (v for v in (getattr(m, "gradient_checkpointing", False) for m in self.modules()) if v),
         False,
     )
 
@@ -2105,15 +2049,10 @@ def unsloth_fast_generate(
     dtype = _get_dtype(dtype_from_config(self.config))
 
     if hasattr(self, "config") and hasattr(self.config, "max_position_embeddings"):
-        if (
-            "input_ids" in kwargs
-            and kwargs["input_ids"] is not None
-            and "max_new_tokens" in kwargs
-        ):
+        if "input_ids" in kwargs and kwargs["input_ids"] is not None and "max_new_tokens" in kwargs:
             _ids = kwargs["input_ids"]
             if hasattr(_ids, "shape") and (
-                _ids.shape[-1] + kwargs["max_new_tokens"]
-                > self.config.max_position_embeddings
+                _ids.shape[-1] + kwargs["max_new_tokens"] > self.config.max_position_embeddings
             ):
                 raise ValueError(
                     f"Unsloth: input length {_ids.shape[-1]} + max_new_tokens {kwargs['max_new_tokens']} exceeds the maximum sequence length of {self.config.max_position_embeddings}!\n"
@@ -2201,9 +2140,7 @@ class FastLlamaModel:
         LlamaFlashAttention2.forward = LlamaAttention_fast_forward
         LlamaDecoderLayer.forward = LlamaDecoderLayer_fast_forward
         LlamaModel.forward = LlamaModel_fast_forward
-        LlamaForCausalLM.forward = CausalLM_fast_forward(
-            LlamaModel_fast_forward_inference
-        )
+        LlamaForCausalLM.forward = CausalLM_fast_forward(LlamaModel_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(LlamaForCausalLM)
 
@@ -2214,9 +2151,7 @@ class FastLlamaModel:
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.llama.modeling_llama
 
-        transformers.models.llama.modeling_llama.LlamaRotaryEmbedding = (
-            LlamaRotaryEmbedding
-        )
+        transformers.models.llama.modeling_llama.LlamaRotaryEmbedding = LlamaRotaryEmbedding
         transformers.models.llama.modeling_llama.LlamaLinearScalingRotaryEmbedding = (
             LlamaLinearScalingRotaryEmbedding
         )
@@ -2271,10 +2206,7 @@ class FastLlamaModel:
                     fast_inference = False
             elif DEVICE_TYPE == "hip":
                 fast_inference = True
-            if (
-                unsloth_vllm_standby
-                and os.environ.get("UNSLOTH_VLLM_STANDBY", "0") == "0"
-            ):
+            if unsloth_vllm_standby and os.environ.get("UNSLOTH_VLLM_STANDBY", "0") == "0":
                 raise RuntimeError(
                     "Unsloth: `unsloth_vllm_standby` is True, but  environment variable `UNSLOTH_VLLM_STANDBY` is not set to 1!"
                 )
@@ -2290,7 +2222,9 @@ class FastLlamaModel:
                 gpu_stats.name + ". " if gpu_stats.name != "" else "NVIDIA GPU Device. "
             )
             gpu_version = torch.version.cuda
-            gpu_stats_snippet = f"CUDA: {gpu_stats.major}.{gpu_stats.minor}. CUDA Toolkit: {gpu_version}."
+            gpu_stats_snippet = (
+                f"CUDA: {gpu_stats.major}.{gpu_stats.minor}. CUDA Toolkit: {gpu_version}."
+            )
             try:
                 vllm_version = f" vLLM: {importlib_version('vllm')}."
             except:
@@ -2306,9 +2240,7 @@ class FastLlamaModel:
                 vllm_version = ""
         elif DEVICE_TYPE == "xpu":
             gpu_stats = torch.xpu.get_device_properties(0)
-            gpu_stats_name = (
-                gpu_stats.name + ". " if gpu_stats.name != "" else "Intel XPU Device. "
-            )
+            gpu_stats_name = gpu_stats.name + ". " if gpu_stats.name != "" else "Intel XPU Device. "
             gpu_version = torch.version.xpu
             gpu_stats_snippet = f"Intel Toolkit: {gpu_version}."
             try:
@@ -2353,17 +2285,13 @@ class FastLlamaModel:
         if dtype is None:
             dtype = torch.float16 if not SUPPORTS_BFLOAT16 else torch.bfloat16
         elif dtype == torch.bfloat16 and not SUPPORTS_BFLOAT16:
-            logger.warning_once(
-                "Device does not support bfloat16. Will change to float16."
-            )
+            logger.warning_once("Device does not support bfloat16. Will change to float16.")
             dtype = torch.float16
         # elif dtype == torch.float16 and SUPPORTS_BFLOAT16:
         #     logger.warning_once("Device supports bfloat16 but you selected float16. Will change to bfloat16.")
         #     dtype = torch.bfloat16
 
-        assert (
-            dtype == torch.float16 or dtype == torch.bfloat16 or dtype == torch.float32
-        )
+        assert dtype == torch.float16 or dtype == torch.bfloat16 or dtype == torch.float32
 
         # RoPE Scaling
         model_config = AutoConfig.from_pretrained(
@@ -2380,9 +2308,7 @@ class FastLlamaModel:
         model_function = MODEL_FOR_CAUSAL_LM_MAPPING[model_config.__class__]
         IS_FALCON_H1 = model_config.model_type.startswith("falcon_h1")
 
-        preferred_attn_impl = resolve_attention_implementation(
-            model_function, model_config
-        )
+        preferred_attn_impl = resolve_attention_implementation(model_function, model_config)
 
         has_rope_scaling = False
         try:
@@ -2454,9 +2380,7 @@ class FastLlamaModel:
                             _ckpt_skip.append(_m)
                     _ckpt_qcfg["llm_int8_skip_modules"] = _ckpt_skip
                 else:
-                    _ckpt_skip = list(
-                        getattr(_ckpt_qcfg, "llm_int8_skip_modules", None) or []
-                    )
+                    _ckpt_skip = list(getattr(_ckpt_qcfg, "llm_int8_skip_modules", None) or [])
                     for _m in llm_int8_skip_modules:
                         if _m not in _ckpt_skip:
                             _ckpt_skip.append(_m)
@@ -2590,15 +2514,11 @@ class FastLlamaModel:
                 config = model_config,
                 load_in_fp8 = load_in_fp8,
             )
-            model = convert_vllm_to_huggingface(
-                quant_state_dict, model_config, dtype, bnb_config
-            )
+            model = convert_vllm_to_huggingface(quant_state_dict, model_config, dtype, bnb_config)
             model.vllm_engine = llm
             llm.shared_weights = True
             model.fast_generate = model.vllm_engine.generate
-            model.fast_generate_batches = functools.partial(
-                generate_batches, model.vllm_engine
-            )
+            model.fast_generate_batches = functools.partial(generate_batches, model.vllm_engine)
         raise_handler.remove()
         # Return old flag
         os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = old_hf_transfer
@@ -2615,9 +2535,7 @@ class FastLlamaModel:
         )
 
         model, tokenizer = patch_tokenizer(model, tokenizer)
-        model, tokenizer = model_patcher.post_patch(
-            model, tokenizer, correct_dtype = dtype
-        )
+        model, tokenizer = model_patcher.post_patch(model, tokenizer, correct_dtype = dtype)
 
         # Patch up QKV / O and MLP
         for idx, layer in enumerate(model.model.layers):
@@ -2644,15 +2562,13 @@ class FastLlamaModel:
             if item in inner_training_loop:
                 good_items.append(item)
         exec(
-            "from transformers.trainer import ("
-            + ", ".join(x for x in good_items)
-            + ")",
+            "from transformers.trainer import (" + ", ".join(x for x in good_items) + ")",
             globals(),
         )
 
-        start = re.search(
-            r"logger\.info\([\"\'].+?Running training", inner_training_loop
-        ).span(0)[0]
+        start = re.search(r"logger\.info\([\"\'].+?Running training", inner_training_loop).span(0)[
+            0
+        ]
         end = inner_training_loop.find("\n\n", start)
         original_debug = inner_training_loop[start:end]
         spaces = re.search(r"\n([\s\t]{1,})", original_debug).group(0)[1:]
@@ -2676,9 +2592,7 @@ class FastLlamaModel:
                 torch.cuda.empty_cache()"""
 
         debug_info = debug_info.split("\n")
-        debug_info = "\n".join(
-            [debug_info[0]] + [spaces + x[8:] for x in debug_info[1:]]
-        )
+        debug_info = "\n".join([debug_info[0]] + [spaces + x[8:] for x in debug_info[1:]])
         inner_training_loop = inner_training_loop.replace(original_debug, debug_info)
 
         debug_info = """n_total_devices = total_train_batch_size // \\
@@ -2687,9 +2601,7 @@ class FastLlamaModel:
             logger.warning_once('Unsloth is running with multi GPUs - the effective batch size is multiplied by ' + str(n_total_devices))
         debug_info ="""
         debug_info = debug_info.split("\n")
-        debug_info = "\n".join(
-            [debug_info[0]] + [spaces + x[8:] for x in debug_info[1:]]
-        )
+        debug_info = "\n".join([debug_info[0]] + [spaces + x[8:] for x in debug_info[1:]])
         inner_training_loop = inner_training_loop.replace("debug_info =", debug_info, 1)
 
         front_spaces = re.match(r"[\t\s]{1,}", inner_training_loop).group(0)
@@ -2794,17 +2706,11 @@ class FastLlamaModel:
         # This is higher than the (negative) logits for real tokens in models
         # like Gemma, causing the decoder to emit <pad> and produce gibberish.
         # Skip entirely if eos_token == pad_token to avoid zeroing EOS embedding.
-        eos_token_id = (
-            getattr(tokenizer, "eos_token_id", None) if tokenizer is not None else None
-        )
-        pad_token_id = (
-            getattr(tokenizer, "pad_token_id", None) if tokenizer is not None else None
-        )
+        eos_token_id = getattr(tokenizer, "eos_token_id", None) if tokenizer is not None else None
+        pad_token_id = getattr(tokenizer, "pad_token_id", None) if tokenizer is not None else None
         if tokenizer is not None and eos_token_id != pad_token_id:
             lm_head = getattr(model, "lm_head", None)
-            lm_head_weight = (
-                getattr(lm_head, "weight", None) if lm_head is not None else None
-            )
+            lm_head_weight = getattr(lm_head, "weight", None) if lm_head is not None else None
             with torch.no_grad():
                 for name, module in model.named_modules():
                     if type(module) is torch.nn.Embedding:
@@ -2816,15 +2722,18 @@ class FastLlamaModel:
                                 # Skip if tied to lm_head
                                 if (
                                     lm_head_weight is not None
-                                    and module.weight.data_ptr()
-                                    == lm_head_weight.data_ptr()
+                                    and module.weight.data_ptr() == lm_head_weight.data_ptr()
                                 ):
                                     continue
                                 module.weight[module.padding_idx] = 0
         return model, tokenizer
 
     @staticmethod
-    def post_patch(model, tokenizer, correct_dtype = None):
+    def post_patch(
+        model,
+        tokenizer,
+        correct_dtype = None,
+    ):
         model, tokenizer = patch_model_and_tokenizer(
             model, tokenizer, downcast_rope = True, correct_dtype = correct_dtype
         )
@@ -2895,9 +2804,7 @@ class FastLlamaModel:
                 **kwargs,
             )
         if os.environ.get("UNSLOTH_ENABLE_FULL_FINETUNING", "0") == "1":
-            print(
-                "Unsloth: Full finetuning is enabled, so .get_peft_model has no effect"
-            )
+            print("Unsloth: Full finetuning is enabled, so .get_peft_model has no effect")
             return model
         transformers_set_seed(random_state)
 
@@ -2949,30 +2856,21 @@ class FastLlamaModel:
 
             # Now check!
             new_target_modules = set(new_target_modules)
-            check_all = check_all and (
-                len(set(old_target_modules) ^ new_target_modules) == 0
-            )
+            check_all = check_all and (len(set(old_target_modules) ^ new_target_modules) == 0)
 
             check_all = check_all and (
                 (loftq_config == {} or loftq_config is None)
-                and (
-                    peft_config["loftq_config"] == {}
-                    or peft_config["loftq_config"] is None
-                )
+                and (peft_config["loftq_config"] == {} or peft_config["loftq_config"] is None)
             )
 
             if check_all:
                 # Simply pass through!
-                logger.warning(
-                    "Unsloth: Already have LoRA adapters! We shall skip this step."
-                )
+                logger.warning("Unsloth: Already have LoRA adapters! We shall skip this step.")
 
                 # Offload!
                 # [TODO] First offload lm_head and embed_tokens to CPU (should be disk!!)
                 if "embed_tokens" in new_target_modules:
-                    print(
-                        "Unsloth: Training embed_tokens in mixed precision to save VRAM"
-                    )
+                    print("Unsloth: Training embed_tokens in mixed precision to save VRAM")
 
                     _offload_frozen_module_for_training(
                         model.get_input_embeddings(), DEVICE_TYPE_TORCH
@@ -3023,7 +2921,6 @@ class FastLlamaModel:
         if init_lora_weights == "loftq":
             if not SUPPORTS_LOFTQ:
                 import peft
-
                 raise RuntimeError(
                     f"Unsloth: Your PEFT version of {peft.__version__} does not support LoftQ init.\n"
                     "Please install PEFT 0.7.2 or higher.\n"
@@ -3032,7 +2929,6 @@ class FastLlamaModel:
 
             if loftq_config == {}:
                 from peft import LoftQConfig
-
                 logger.warning_once(
                     "Unsloth: init_lora_weights = `loftq` is set, but `loftq_config` is None.\n"
                     "We shall use `loftq_config = LoftQConfig(loftq_bits = 4, loftq_iter = 1)`."
@@ -3050,7 +2946,6 @@ class FastLlamaModel:
             if not SUPPORTS_RSLORA:
                 # We manually check for PEFT
                 import peft
-
                 raise RuntimeError(
                     f"Unsloth: Your PEFT version of {peft.__version__} does not support `use_rslora`.\n"
                     "Please install PEFT 0.7.2 or higher.\n"
@@ -3105,9 +3000,7 @@ class FastLlamaModel:
         if hasattr(model, "_need_to_train_embeddings"):
             # Check if embed_tokens/lm_head are already being trained
             # (either as LoRA targets in final_modules or via modules_to_save)
-            _embed_already_trained = (
-                train_embed_tokens or "embed_tokens" in final_modules
-            )
+            _embed_already_trained = train_embed_tokens or "embed_tokens" in final_modules
             _lm_head_already_trained = train_lm_head or "lm_head" in final_modules
             if not _lm_head_already_trained or not _embed_already_trained:
                 print(
@@ -3181,7 +3074,6 @@ class FastLlamaModel:
 
         if finetune_last_n_layers is not None and layers_to_transform is None:
             from .vision import _get_total_transformer_layers
-
             _total_layers = _get_total_transformer_layers(model)
             if _total_layers is not None and _total_layers > 0:
                 _n = max(1, min(int(finetune_last_n_layers), _total_layers))
@@ -3278,9 +3170,9 @@ class FastLlamaModel:
                     if hasattr(input_embeddings, "modules_to_save") and hasattr(
                         output_embeddings, "modules_to_save"
                     ):
-                        if hasattr(
-                            input_embeddings.modules_to_save, "default"
-                        ) and hasattr(output_embeddings.modules_to_save, "default"):
+                        if hasattr(input_embeddings.modules_to_save, "default") and hasattr(
+                            output_embeddings.modules_to_save, "default"
+                        ):
                             _retie_parameter(
                                 output_embeddings.modules_to_save.default,
                                 input_embeddings.modules_to_save.default,
@@ -3346,10 +3238,7 @@ class FastLlamaModel:
         return model
 
     @staticmethod
-    def patch_peft_model(
-        model,
-        use_gradient_checkpointing = "unsloth",
-    ):
+    def patch_peft_model(model, use_gradient_checkpointing = "unsloth"):
         if os.environ.get("UNSLOTH_USE_NEW_MODEL", "0") == "1":
             return FastBaseModel.patch_peft_model(
                 model = model,
@@ -3358,9 +3247,7 @@ class FastLlamaModel:
         if not isinstance(model, PeftModelForCausalLM) and not isinstance(
             model, PeftModelForSequenceClassification
         ):
-            raise TypeError(
-                "Unsloth: Your model needs to call `.get_peft_model` first!"
-            )
+            raise TypeError("Unsloth: Your model needs to call `.get_peft_model` first!")
 
         # Get activation function
         model_type = model.config.model_type
@@ -3410,18 +3297,13 @@ class FastLlamaModel:
         from transformers.trainer import Trainer
 
         if Trainer._inner_training_loop.__name__ != "_fast_inner_training_loop":
-            raise RuntimeError(
-                "Unsloth: Unsuccessfully patched Trainer! Please file a bug report!"
-            )
+            raise RuntimeError("Unsloth: Unsuccessfully patched Trainer! Please file a bug report!")
 
         # Fix loftq issues
         # loftq_config must not = None, but rather {}
         all_configs = model.peft_config
         for key, current_config in all_configs.items():
-            if (
-                hasattr(current_config, "loftq_config")
-                and current_config.loftq_config is None
-            ):
+            if hasattr(current_config, "loftq_config") and current_config.loftq_config is None:
                 new_args = current_config.__dict__
                 new_args["loftq_config"] = {}
                 current_config = current_config.__class__(**new_args)
@@ -3433,9 +3315,7 @@ class FastLlamaModel:
         n_o = 0
 
         active_adapter = (
-            model.active_adapters[0]
-            if hasattr(model, "active_adapters")
-            else model.active_adapter
+            model.active_adapters[0] if hasattr(model, "active_adapters") else model.active_adapter
         )
 
         # Get dropout and bias
@@ -3468,18 +3348,9 @@ class FastLlamaModel:
                         and (getattr(gate_proj, "base_layer", gate_proj).bias is None)
                         and (getattr(up_proj, "base_layer", up_proj).bias is None)
                         and (getattr(down_proj, "base_layer", down_proj).bias is None)
-                        and (
-                            len(getattr(gate_proj, "lora_magnitude_vector", []) or [])
-                            == 0
-                        )
-                        and (
-                            len(getattr(up_proj, "lora_magnitude_vector", []) or [])
-                            == 0
-                        )
-                        and (
-                            len(getattr(down_proj, "lora_magnitude_vector", []) or [])
-                            == 0
-                        )
+                        and (len(getattr(gate_proj, "lora_magnitude_vector", []) or []) == 0)
+                        and (len(getattr(up_proj, "lora_magnitude_vector", []) or []) == 0)
+                        and (len(getattr(down_proj, "lora_magnitude_vector", []) or []) == 0)
                     ):
                         # https://stackoverflow.com/questions/50599045/python-replacing-a-function-within-a-class-of-a-module
                         if hasattr(mlp_module, "_unsloth_forward"):
@@ -3488,9 +3359,7 @@ class FastLlamaModel:
                                 _apply_lora_mlp, mlp_module
                             )
                         else:
-                            mlp_module.forward = types.MethodType(
-                                _apply_lora_mlp, mlp_module
-                            )
+                            mlp_module.forward = types.MethodType(_apply_lora_mlp, mlp_module)
                         n_mlp += 1
                     else:
                         logger.warning_once(
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 0808138ac9..34514e7013 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -178,9 +178,7 @@ def _fix_rope_inv_freq(model):
             inv_freq = 1.0 / (
                 module.base
                 ** (
-                    torch.arange(
-                        0, module.dim, 2, dtype = torch.int64, device = "cpu"
-                    ).float()
+                    torch.arange(0, module.dim, 2, dtype = torch.int64, device = "cpu").float()
                     / module.dim
                 )
             )
@@ -208,9 +206,7 @@ def _fix_rope_inv_freq(model):
                 long_factor = rope_scaling.get("long_factor", None)
                 if short_factor is not None and long_factor is not None:
                     inv_freq_shape = (
-                        torch.arange(
-                            0, module.dim, 2, dtype = torch.int64, device = "cpu"
-                        ).float()
+                        torch.arange(0, module.dim, 2, dtype = torch.int64, device = "cpu").float()
                         / module.dim
                     )
                     sf = torch.tensor(short_factor, device = "cpu", dtype = torch.float32)
@@ -294,14 +290,10 @@ class FastLanguageModel(FastLlamaModel):
             bnb_compute_dtype = None
             if isinstance(quantization_config, dict):
                 if quantization_config.get("load_in_4bit", False):
-                    bnb_compute_dtype = quantization_config.get(
-                        "bnb_4bit_compute_dtype", None
-                    )
+                    bnb_compute_dtype = quantization_config.get("bnb_4bit_compute_dtype", None)
             else:
                 if getattr(quantization_config, "load_in_4bit", False):
-                    bnb_compute_dtype = getattr(
-                        quantization_config, "bnb_4bit_compute_dtype", None
-                    )
+                    bnb_compute_dtype = getattr(quantization_config, "bnb_4bit_compute_dtype", None)
             if isinstance(bnb_compute_dtype, str):
                 bnb_compute_dtype = getattr(torch, bnb_compute_dtype, None)
             if isinstance(bnb_compute_dtype, torch.dtype):
@@ -440,7 +432,6 @@ class FastLanguageModel(FastLlamaModel):
 
         if USE_MODELSCOPE and not os.path.exists(model_name):
             from modelscope import snapshot_download
-
             model_name = snapshot_download(model_name)
 
         # First check if it's a normal model via AutoConfig
@@ -599,9 +590,7 @@ class FastLanguageModel(FastLlamaModel):
             if getattr(model_config, "rope_scaling", None) is not None:
                 scaling_type1 = model_config.rope_scaling.get("type", None)
                 scaling_type2 = model_config.rope_scaling.get("rope_type", None)
-                scaling_type = (
-                    scaling_type1 if scaling_type1 is not None else scaling_type2
-                )
+                scaling_type = scaling_type1 if scaling_type1 is not None else scaling_type2
 
             if scaling_type == "llama3" and not SUPPORTS_LLAMA31:
                 raise ImportError(
@@ -658,9 +647,7 @@ class FastLanguageModel(FastLlamaModel):
                     f'Try `pip install --upgrade "transformers>=4.50.3"`\n'
                     f"to obtain the latest transformers build, then restart this session."
                 )
-            dispatch_model = (
-                FastQwen3Model if model_type == "qwen3" else FastQwen3MoeModel
-            )
+            dispatch_model = FastQwen3Model if model_type == "qwen3" else FastQwen3MoeModel
         # elif model_type == "falcon_h1":
         #     dispatch_model = FastFalconH1Model
         #     if not SUPPORTS_FALCON_H1:
@@ -797,9 +784,7 @@ class FastLanguageModel(FastLlamaModel):
                 model.config.update({"quantization_config": quantization_config})
             else:
                 if hasattr(quantization_config, "to_dict"):
-                    model.config.update(
-                        {"quantization_config": quantization_config.to_dict()}
-                    )
+                    model.config.update({"quantization_config": quantization_config.to_dict()})
                 elif isinstance(quantization_config, dict):
                     model.config.update({"quantization_config": quantization_config})
 
@@ -843,7 +828,6 @@ from transformers import (
 
 try:
     from transformers import AutoModelForImageTextToText
-
     AutoModelForVision2Seq = AutoModelForImageTextToText
 except:
     from transformers import AutoModelForVision2Seq
@@ -922,14 +906,10 @@ class FastModel(FastBaseModel):
             bnb_compute_dtype = None
             if isinstance(quantization_config, dict):
                 if quantization_config.get("load_in_4bit", False):
-                    bnb_compute_dtype = quantization_config.get(
-                        "bnb_4bit_compute_dtype", None
-                    )
+                    bnb_compute_dtype = quantization_config.get("bnb_4bit_compute_dtype", None)
             else:
                 if getattr(quantization_config, "load_in_4bit", False):
-                    bnb_compute_dtype = getattr(
-                        quantization_config, "bnb_4bit_compute_dtype", None
-                    )
+                    bnb_compute_dtype = getattr(quantization_config, "bnb_4bit_compute_dtype", None)
             if isinstance(bnb_compute_dtype, str):
                 bnb_compute_dtype = getattr(torch, bnb_compute_dtype, None)
             if isinstance(bnb_compute_dtype, torch.dtype):
@@ -938,9 +918,7 @@ class FastModel(FastBaseModel):
         if dtype is None:
             dtype = torch.float16 if not SUPPORTS_BFLOAT16 else torch.bfloat16
         elif dtype == torch.bfloat16 and not SUPPORTS_BFLOAT16:
-            logger.warning_once(
-                "Device does not support bfloat16. Will change to float16."
-            )
+            logger.warning_once("Device does not support bfloat16. Will change to float16.")
             dtype = torch.float16
         assert dtype in (torch.float16, torch.bfloat16, torch.float32)
         assert load_in_fp8 in (True, False, "block")
@@ -958,10 +936,7 @@ class FastModel(FastBaseModel):
             load_in_16bit = False
 
         if (
-            int(load_in_4bit)
-            + int(load_in_8bit)
-            + int(load_in_16bit)
-            + int(load_in_fp8 != False)
+            int(load_in_4bit) + int(load_in_8bit) + int(load_in_16bit) + int(load_in_fp8 != False)
             >= 2
         ):
             raise RuntimeError(
@@ -1055,7 +1030,6 @@ class FastModel(FastBaseModel):
         # Check modelscope
         if USE_MODELSCOPE and not os.path.exists(model_name):
             from modelscope import snapshot_download
-
             model_name = snapshot_download(model_name)
 
         # First check if it's a normal model via AutoConfig
@@ -1159,23 +1133,19 @@ class FastModel(FastBaseModel):
 
         # Check versions
         LATEST = "\nPlease use transformers via `pip install --no-deps git+https://github.com/huggingface/transformers.git`"
-        NIGHTLY = '\nPlease use nightly transformers via pip install --upgrade "transformers>=4.49.0"`'
+        NIGHTLY = (
+            '\nPlease use nightly transformers via pip install --upgrade "transformers>=4.49.0"`'
+        )
         # Pixtral
         if "pixtral" in model_types_all and transformers_version < Version("4.49.0"):
-            raise RuntimeError(
-                "Unsloth: Pixtral only works on transformers >= 4.49.0." + LATEST
-            )
+            raise RuntimeError("Unsloth: Pixtral only works on transformers >= 4.49.0." + LATEST)
         # Qwen 2.5
         elif "qwen2_5" in model_types_all and transformers_version < Version("4.49.0"):
-            raise RuntimeError(
-                "Unsloth: Qwen 2.5 only works on transformers >= 4.49.0." + LATEST
-            )
+            raise RuntimeError("Unsloth: Qwen 2.5 only works on transformers >= 4.49.0." + LATEST)
         # Gemma 4 must be before Gemma 3N and Gemma 3
         elif "gemma4" in model_types_all:
             if not SUPPORTS_GEMMA4:
-                raise RuntimeError(
-                    "Unsloth: Gemma 4 requires transformers >= 5.5.0" + LATEST
-                )
+                raise RuntimeError("Unsloth: Gemma 4 requires transformers >= 5.5.0" + LATEST)
             os.environ["UNSLOTH_DISABLE_STATIC_GENERATION"] = "1"
             os.environ["UNSLOTH_HIGH_PRECISION_LAYERNORM"] = "1"
         # Gemma 3N must be before Gemma 3
@@ -1213,12 +1183,9 @@ class FastModel(FastBaseModel):
             if is_rdna():
                 os.environ["UNSLOTH_COMPILE_DISABLE"] = "partial"
         # Cohere
-        elif "cohere2" in model_types_all and transformers_version < Version(
-            "4.50.0.dev0"
-        ):
+        elif "cohere2" in model_types_all and transformers_version < Version("4.50.0.dev0"):
             raise RuntimeError(
-                "Unsloth: Cohere's Command model only works on transformers >= 4.50.0."
-                + NIGHTLY
+                "Unsloth: Cohere's Command model only works on transformers >= 4.50.0." + NIGHTLY
             )
         # Sesame
         elif "csm" in model_types_all:
@@ -1235,19 +1202,11 @@ class FastModel(FastBaseModel):
             os.environ["UNSLOTH_HIGH_PRECISION_LAYERNORM"] = "1"
             os.environ["UNSLOTH_DISABLE_STATIC_GENERATION"] = "1"
         # OLMo 2
-        elif "olmo2" in model_types_all and transformers_version < Version(
-            "4.50.0.dev0"
-        ):
-            raise RuntimeError(
-                "Unsloth: OLMo-2 only works on transformers >= 4.50.0." + NIGHTLY
-            )
+        elif "olmo2" in model_types_all and transformers_version < Version("4.50.0.dev0"):
+            raise RuntimeError("Unsloth: OLMo-2 only works on transformers >= 4.50.0." + NIGHTLY)
         # OLMo 3
-        elif "olmo3" in model_types_all and transformers_version < Version(
-            "4.57.0.dev0"
-        ):
-            raise RuntimeError(
-                "Unsloth: OLMo-3 only works on transformers >= 4.57.0." + LATEST
-            )
+        elif "olmo3" in model_types_all and transformers_version < Version("4.57.0.dev0"):
+            raise RuntimeError("Unsloth: OLMo-3 only works on transformers >= 4.57.0." + LATEST)
         elif "falcon_h1" in model_types_all:
             # Falcon must use float32 Triton ie TRITON_F32_DEFAULT = 'ieee'
             # since Mamba kernels error out on using lower precision
@@ -1392,8 +1351,7 @@ class FastModel(FastBaseModel):
         for disable_name in FORCE_FLOAT32:
             # add comma to model_types_all matching in case of exact match for end
             if (
-                disable_name.lower()
-                == model_type_arch.lower().replace("-", "").replace("_", "")
+                disable_name.lower() == model_type_arch.lower().replace("-", "").replace("_", "")
                 or disable_name.lower() in model_types_all
             ) and ((dtype == torch.float16) or not SUPPORTS_BFLOAT16):
                 os.environ["UNSLOTH_FORCE_FLOAT32"] = "1"
@@ -1463,7 +1421,6 @@ class FastModel(FastBaseModel):
         if auto_model is None:
             if _num_labels is not None:
                 from transformers import AutoModelForSequenceClassification
-
                 auto_model = AutoModelForSequenceClassification
             elif is_vlm:
                 # Check if the model's auto_map supports the VLM auto class.
@@ -1471,10 +1428,7 @@ class FastModel(FastBaseModel):
                 # in their auto_map, not AutoModelForImageTextToText/AutoModelForVision2Seq.
                 _auto_map = getattr(model_config, "auto_map", {}) or {}
                 _vlm_class_name = AutoModelForVision2Seq.__name__
-                if (
-                    "AutoModelForCausalLM" in _auto_map
-                    and _vlm_class_name not in _auto_map
-                ):
+                if "AutoModelForCausalLM" in _auto_map and _vlm_class_name not in _auto_map:
                     auto_model = AutoModelForCausalLM
                 else:
                     auto_model = AutoModelForVision2Seq
@@ -1558,9 +1512,7 @@ class FastModel(FastBaseModel):
                 model.config.update({"quantization_config": quantization_config})
             else:
                 if hasattr(quantization_config, "to_dict"):
-                    model.config.update(
-                        {"quantization_config": quantization_config.to_dict()}
-                    )
+                    model.config.update({"quantization_config": quantization_config.to_dict()})
                 elif isinstance(quantization_config, dict):
                     model.config.update({"quantization_config": quantization_config})
 
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index c0c6455a2e..ea18dc125a 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -51,7 +51,6 @@ BAD_MAPPINGS = {
 def _get_torchao_fp8_config(fp8_mode):
     # Import lazily so an optional, broken vLLM install does not break plain `import unsloth`.
     from unsloth_zoo.vllm_utils import _get_torchao_fp8_config as _impl
-
     return _impl(fp8_mode)
 
 
@@ -133,7 +132,6 @@ def __get_model_name(
         # fall through to offline quantization via _offline_quantize_to_fp8.
         if importlib.util.find_spec("vllm") is not None:
             import vllm
-
             if Version(vllm.__version__) >= Version("0.12.0"):
                 return model_name
         return None
@@ -181,7 +179,9 @@ def _get_new_mapper():
     try:
         import requests
 
-        new_mapper = "https://raw.githubusercontent.com/unslothai/unsloth/main/unsloth/models/mapper.py"
+        new_mapper = (
+            "https://raw.githubusercontent.com/unslothai/unsloth/main/unsloth/models/mapper.py"
+        )
         with requests.get(new_mapper, timeout = 3) as new_mapper:
             new_mapper = new_mapper.text
         new_mapper = new_mapper[new_mapper.find("__INT_TO_FLOAT_MAPPER") :]
@@ -202,12 +202,7 @@ def _get_new_mapper():
 
 
 def _resolve_with_mappers(
-    model_name,
-    load_in_4bit,
-    load_in_fp8,
-    int_to_float,
-    float_to_int,
-    map_to_unsloth_16bit,
+    model_name, load_in_4bit, load_in_fp8, int_to_float, float_to_int, map_to_unsloth_16bit
 ):
     return __get_model_name(
         model_name = model_name,
@@ -246,11 +241,7 @@ def get_model_name(
     ):
         new_model_name = BAD_MAPPINGS[new_model_name.lower()]
 
-    if (
-        new_model_name is None
-        and model_name.count("/") == 1
-        and model_name[0].isalnum()
-    ):
+    if new_model_name is None and model_name.count("/") == 1 and model_name[0].isalnum():
         # Try checking if a new Unsloth version allows it!
         NEW_INT_TO_FLOAT_MAPPER, NEW_FLOAT_TO_INT_MAPPER, NEW_MAP_TO_UNSLOTH_16bit = (
             _get_new_mapper()
@@ -292,9 +283,7 @@ def _offline_quantize_to_fp8(model_name: str, fp8_mode: str) -> str:
     temp_dir = tempfile.gettempdir()
     new_model_name = model_name.split("/")[-1] + "-fp8-" + fp8_mode
     new_model_name = os.path.join(temp_dir, new_model_name)
-    print(
-        f"Unsloth: Quantizing '{model_name}' to fp8, using model_name='{new_model_name}' instead"
-    )
+    print(f"Unsloth: Quantizing '{model_name}' to fp8, using model_name='{new_model_name}' instead")
 
     if not os.path.isdir(new_model_name):
         from transformers import (
@@ -373,13 +362,9 @@ def _get_fp8_mode_and_check_settings(
 
     # Check user settings
     if fp8_mode not in ["row", "block"]:
-        raise ValueError(
-            f"Unsloth: `load_in_fp8` can only be 'row' or 'block', got '{fp8_mode}'"
-        )
+        raise ValueError(f"Unsloth: `load_in_fp8` can only be 'row' or 'block', got '{fp8_mode}'")
     if full_finetuning:
-        raise ValueError(
-            "Unsloth: `load_in_fp8` is not compatible with full finetuning"
-        )
+        raise ValueError("Unsloth: `load_in_fp8` is not compatible with full finetuning")
     if load_in_4bit or load_in_8bit or load_in_16bit:
         raise ValueError(
             "Unsloth: `load_in_fp8` is not compatible with `load_in_4bit`, `load_in_8bit` or `load_in_16bit`",
@@ -423,12 +408,10 @@ def _get_fp8_mode_and_check_settings(
         and importlib.util.find_spec("fbgemm_gpu.experimental") is not None
     ):
         import fbgemm_gpu.experimental.gen_ai
-
         if Version(fbgemm_gpu.__version__) < Version("1.4.1"):
             # Old FBGEMM version - disable and use Triton kernels instead
             os.environ["UNSLOTH_HAS_FBGEMM"] = "0"
             from unsloth_zoo.log import logger
-
             logger.info(
                 f"Unsloth: fbgemm_gpu_genai=={fbgemm_gpu.__version__} is old for FP8 loading. "
                 f"Using Triton kernels instead."
diff --git a/unsloth/models/mistral.py b/unsloth/models/mistral.py
index 191852b49e..cd6dd2ed1a 100644
--- a/unsloth/models/mistral.py
+++ b/unsloth/models/mistral.py
@@ -97,9 +97,7 @@ def MistralAttention_fast_forward(
     self.rotary_emb.extend_rope_embedding(V, seq_len = kv_seq_len)
     cos, sin = self.rotary_emb.get_cached(kv_seq_len, Q.device.index)
 
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     # Useful for LongRoPE
     Q, K = fast_rope_embedding(Q, K, cos, sin, rope_position_ids)
 
@@ -113,12 +111,8 @@ def MistralAttention_fast_forward(
     sw = kv_seq_len if (sw_cfg is None or sw_cfg == "null") else sw_cfg
     window_size = (-1, -1) if (kv_seq_len <= sw) else (sw, sw)
 
-    use_varlen = (
-        seq_info is not None and past_key_value is None and window_size == (-1, -1)
-    )
-    backend = (
-        SDPA if attention_mask is not None else select_attention_backend(use_varlen)
-    )
+    use_varlen = seq_info is not None and past_key_value is None and window_size == (-1, -1)
+    backend = SDPA if attention_mask is not None else select_attention_backend(use_varlen)
     attention_config = AttentionConfig(
         backend = backend,
         n_kv_heads = n_kv_heads,
@@ -173,11 +167,7 @@ def MistralForCausalLM_fast_forward(
 
         if HAS_XFORMERS:
             # Always create causal mask for xformers
-            if (
-                sliding_window is None
-                or sliding_window == "null"
-                or sliding_window <= 0
-            ):
+            if sliding_window is None or sliding_window == "null" or sliding_window <= 0:
                 causal_mask = xformers.attn_bias.LowerTriangularMask()
             elif q_len <= sliding_window:
                 causal_mask = xformers.attn_bias.LowerTriangularMask()
@@ -225,9 +215,7 @@ def MistralForCausalLM_fast_forward(
 
             # Combine with existing attention_mask if present
             if attention_mask is None:
-                attention_mask = causal_mask_values[None, None, :, :].expand(
-                    bsz, 1, q_len, q_len
-                )
+                attention_mask = causal_mask_values[None, None, :, :].expand(bsz, 1, q_len, q_len)
             else:
                 if attention_mask.dim() == 2:
                     # Convert 0/1 padding mask to additive format: 1->0 (keep), 0->-inf (mask)
@@ -238,27 +226,19 @@ def MistralForCausalLM_fast_forward(
                     )
                     attention_mask = causal_mask_values[None, None, :, :] + padding_mask
                 else:
-                    attention_mask = (
-                        attention_mask + causal_mask_values[None, None, :, :]
-                    )
+                    attention_mask = attention_mask + causal_mask_values[None, None, :, :]
 
-            attention_mask = attention_mask.to(
-                dtype = _get_dtype(dtype_from_config(self.config))
-            )
+            attention_mask = attention_mask.to(dtype = _get_dtype(dtype_from_config(self.config)))
 
     output_attentions = (
-        output_attentions
-        if output_attentions is not None
-        else self.config.output_attentions
+        output_attentions if output_attentions is not None else self.config.output_attentions
     )
     output_hidden_states = (
         output_hidden_states
         if output_hidden_states is not None
         else self.config.output_hidden_states
     )
-    return_dict = (
-        return_dict if return_dict is not None else self.config.use_return_dict
-    )
+    return_dict = return_dict if return_dict is not None else self.config.use_return_dict
 
     # decoder outputs consists of (dec_features, layer_state, dec_hidden, dec_attn)
     self.model._has_no_labels = labels is None
@@ -300,9 +280,7 @@ def MistralForCausalLM_fast_forward(
     # Merge legacy / new spellings before branching so the decode-time
     # last-token slice fires on the normal path too. Skip int max() if
     # either is a tensor (HF selective-decode form).
-    if isinstance(num_logits_to_keep, torch.Tensor) or isinstance(
-        logits_to_keep, torch.Tensor
-    ):
+    if isinstance(num_logits_to_keep, torch.Tensor) or isinstance(logits_to_keep, torch.Tensor):
         num_logits_to_keep = 0
     else:
         num_logits_to_keep = max(num_logits_to_keep, logits_to_keep)
@@ -323,9 +301,7 @@ def MistralForCausalLM_fast_forward(
         logits = torch.mv(lm_head, hidden_states.ravel().to(lm_head.dtype))
         logits = logits.unsqueeze(0).unsqueeze(0)
     elif num_logits_to_keep != 0:
-        logits = self.lm_head(
-            hidden_states[:, -num_logits_to_keep:, :].to(lm_head.dtype)
-        )
+        logits = self.lm_head(hidden_states[:, -num_logits_to_keep:, :].to(lm_head.dtype))
     else:
         RETURN_LOGITS = os.environ.get("UNSLOTH_RETURN_LOGITS", "0") == "1"
         # < 1024 Normal Unsloth uses less VRAM!
@@ -460,9 +436,7 @@ class FastMistralModel(FastLlamaModel):
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.mistral.modeling_mistral
 
-        transformers.models.mistral.modeling_mistral.MistralRotaryEmbedding = (
-            LlamaRotaryEmbedding
-        )
+        transformers.models.mistral.modeling_mistral.MistralRotaryEmbedding = LlamaRotaryEmbedding
         return
 
     @staticmethod
diff --git a/unsloth/models/qwen2.py b/unsloth/models/qwen2.py
index 3f819d6dc1..f33c3a2b23 100644
--- a/unsloth/models/qwen2.py
+++ b/unsloth/models/qwen2.py
@@ -52,9 +52,7 @@ class FastQwen2Model(FastLlamaModel):
         Qwen2FlashAttention2.forward = LlamaAttention_fast_forward
         Qwen2DecoderLayer.forward = LlamaDecoderLayer_fast_forward
         Qwen2Model.forward = LlamaModel_fast_forward
-        Qwen2ForCausalLM.forward = CausalLM_fast_forward(
-            LlamaModel_fast_forward_inference
-        )
+        Qwen2ForCausalLM.forward = CausalLM_fast_forward(LlamaModel_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(Qwen2ForCausalLM)
 
@@ -65,9 +63,7 @@ class FastQwen2Model(FastLlamaModel):
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.qwen2.modeling_qwen2
 
-        transformers.models.qwen2.modeling_qwen2.Qwen2RotaryEmbedding = (
-            LlamaRotaryEmbedding
-        )
+        transformers.models.qwen2.modeling_qwen2.Qwen2RotaryEmbedding = LlamaRotaryEmbedding
         return
 
     @staticmethod
diff --git a/unsloth/models/qwen3.py b/unsloth/models/qwen3.py
index 3129483be8..c515347b5b 100644
--- a/unsloth/models/qwen3.py
+++ b/unsloth/models/qwen3.py
@@ -39,9 +39,7 @@ try:
     )
 except:
     transformers_version = Version(transformers_version)
-    if not transformers_version >= Version(
-        "4.50.3"
-    ):  # TODO: Update when transformers is updated
+    if not transformers_version >= Version("4.50.3"):  # TODO: Update when transformers is updated
         raise ImportError(
             f"Unsloth: Your transformers version of {transformers_version} does not support Qwen3 and Qwen3Moe.\n"
             f"The minimum required version is 4.50.3.\n"
@@ -127,9 +125,7 @@ def Qwen3Attention_fast_forward(
         rotary_emb.extend_rope_embedding(V, seq_len = kv_seq_len)
         cos, sin = rotary_emb.get_cached(kv_seq_len, Q.device.index)
 
-    rope_position_ids = (
-        position_ids if position_ids is not None else kwargs.get("position_ids")
-    )
+    rope_position_ids = position_ids if position_ids is not None else kwargs.get("position_ids")
     # Useful for LongRoPE
     Q, K = fast_rope_embedding(Q, K, cos, sin, rope_position_ids)
 
@@ -140,9 +136,7 @@ def Qwen3Attention_fast_forward(
 
     # Attention module
     use_varlen = seq_info is not None and past_key_value is None
-    backend = (
-        SDPA if attention_mask is not None else select_attention_backend(use_varlen)
-    )
+    backend = SDPA if attention_mask is not None else select_attention_backend(use_varlen)
     attention_config = AttentionConfig(
         backend = backend,
         n_kv_heads = n_kv_heads,
@@ -243,12 +237,8 @@ def Qwen3Attention_fast_forward_inference(
         self.paged_attention_V = self.paged_attention[:, 1]
         self.paged_attention_K[:seq_len] = K1.permute(2, 0, 1, 3)
         self.paged_attention_V[:seq_len] = V1.permute(2, 0, 1, 3)
-        self.temp_QA = torch.empty(
-            (2, bsz, 1, attention_size), dtype = dtype, device = device
-        )
-        self.temp_KV = torch.empty(
-            (2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device
-        )
+        self.temp_QA = torch.empty((2, bsz, 1, attention_size), dtype = dtype, device = device)
+        self.temp_KV = torch.empty((2, bsz, 1, n_kv_heads * head_dim), dtype = dtype, device = device)
         self.RH_Q = torch.empty((bsz, n_heads, 1, head_dim), dtype = dtype, device = device)
 
         # Mistral Nemo 12b has weird dimensions
@@ -274,9 +264,7 @@ def Qwen3Attention_fast_forward_inference(
         )
         self.paged_attention_K = self.paged_attention[:, 0]
         self.paged_attention_V = self.paged_attention[:, 1]
-        self.attention.resize_(
-            (bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT)
-        )
+        self.attention.resize_((bsz, n_heads, 1, self.attention.shape[-1] + KV_CACHE_INCREMENT))
 
     Qn = fast_linear_forward(self.q_proj, Xn, out = self.temp_QA[0])
     Kn = fast_linear_forward(self.k_proj, Xn, out = self.temp_KV[0])
@@ -372,25 +360,19 @@ def Qwen3Attention_fast_forward_inference(
     # Grouped query attention
     _, _, cached_len, _ = Knn.shape
     if bsz == 1 or ((not use_sdpa_gqa) and n_groups != 1):
-        Knn = Knn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
-        Vnn = Vnn[:, :, None, :, :].expand(
-            bsz, n_kv_heads, n_groups, cached_len, head_dim
-        )
+        Knn = Knn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
+        Vnn = Vnn[:, :, None, :, :].expand(bsz, n_kv_heads, n_groups, cached_len, head_dim)
         Knn = Knn.reshape(bsz, n_heads, cached_len, head_dim)
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
     # Attention
     if bsz == 1:
-        Qn *= self.scalar  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
+        Qn *= (
+            self.scalar
+        )  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
         # It seems like doing (Q * scalar) @ K is better than (Q @ K) * scalar to stop overflows
-        A = torch_matmul(
-            Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len]
-        )
-        A[:] = torch_nn_functional_softmax(
-            A, dim = -1, dtype = torch.float32
-        )  # .to(A.dtype)
+        A = torch_matmul(Qn, Knn.transpose(2, 3), out = self.attention[:, :, :, :cached_len])
+        A[:] = torch_nn_functional_softmax(A, dim = -1, dtype = torch.float32)  # .to(A.dtype)
         A = torch_matmul(A, Vnn, out = Qn)
     else:
         if use_sdpa_gqa:
@@ -442,9 +424,7 @@ class FastQwen3Model(FastLlamaModel):
         # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
         import transformers.models.qwen3.modeling_qwen3
 
-        transformers.models.qwen3.modeling_qwen3.Qwen3RotaryEmbedding = (
-            LlamaRotaryEmbedding
-        )
+        transformers.models.qwen3.modeling_qwen3.Qwen3RotaryEmbedding = LlamaRotaryEmbedding
         return
 
     @staticmethod
diff --git a/unsloth/models/qwen3_moe.py b/unsloth/models/qwen3_moe.py
index e1f8c71b6b..8e692e46ea 100644
--- a/unsloth/models/qwen3_moe.py
+++ b/unsloth/models/qwen3_moe.py
@@ -49,7 +49,12 @@ from unsloth_zoo.utils import Version, _get_dtype
 torch_nn_functional_softmax = torch.nn.functional.softmax
 
 
-def Qwen3MoeSparseMoeBlock_fast_forward(self, X, temp_gate = None, temp_up = None):
+def Qwen3MoeSparseMoeBlock_fast_forward(
+    self,
+    X,
+    temp_gate = None,
+    temp_up = None,
+):
     # adapted from https://github.com/huggingface/transformers/pull/36878/files#diff-0855b77fc27ad9449158a1c74953f909b011c00de7125f7c8e68d0ff209c092aR356-R370
 
     bsz, seq_len, hd = X.shape
@@ -59,9 +64,7 @@ def Qwen3MoeSparseMoeBlock_fast_forward(self, X, temp_gate = None, temp_up = Non
         self.gate_proj, X, out = temp_gate
     )  # pretty much the only change from transformers implementation.
 
-    routing_weights = torch_nn_functional_softmax(
-        router_logits, dim = -1, dtype = torch.float32
-    )
+    routing_weights = torch_nn_functional_softmax(router_logits, dim = -1, dtype = torch.float32)
     routing_weights, selected_experts = torch.topk(routing_weights, self.top_k, dim = -1)
     routing_weights /= routing_weights.sum(dim = -1, keepdim = True)
     # we cast back to the input dtype
@@ -111,13 +114,9 @@ def Qwen3MoeDecoderLayer_fast_forward(
 ):
     residual = hidden_states
 
-    if use_cache and hasattr(
-        self, "_flag_for_generation"
-    ):  # past_key_value is not None:
+    if use_cache and hasattr(self, "_flag_for_generation"):  # past_key_value is not None:
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.input_layernorm, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.input_layernorm, hidden_states)
         hidden_states, self_attn_weights, present_key_value = self.self_attn(
             hidden_states = hidden_states,
             causal_mask = causal_mask,
@@ -134,12 +133,8 @@ def Qwen3MoeDecoderLayer_fast_forward(
 
         # MoE Router MLP
         residual = hidden_states
-        hidden_states = fast_rms_layernorm_inference(
-            self.post_attention_layernorm, hidden_states
-        )
-        hidden_states, router_logits = Qwen3MoeSparseMoeBlock_fast_forward(
-            self.mlp, hidden_states
-        )
+        hidden_states = fast_rms_layernorm_inference(self.post_attention_layernorm, hidden_states)
+        hidden_states, router_logits = Qwen3MoeSparseMoeBlock_fast_forward(self.mlp, hidden_states)
         hidden_states += residual
     else:
         residual = hidden_states
@@ -189,14 +184,10 @@ class FastQwen3MoeModel(FastQwen3Model):
         # Qwen3SdpaAttention   .forward = Qwen3Attention_fast_forward
         # Qwen3FlashAttention2 .forward = Qwen3Attention_fast_forward
         Qwen3MoeSparseMoeBlock.forward = Qwen3MoeSparseMoeBlock_fast_forward
-        Qwen3MoeMLP.forward = (
-            fast_swiglu_inference  # This is analogous to Dense models' MLP
-        )
+        Qwen3MoeMLP.forward = fast_swiglu_inference  # This is analogous to Dense models' MLP
         Qwen3MoeDecoderLayer.forward = Qwen3MoeDecoderLayer_fast_forward
         Qwen3MoeModel.forward = LlamaModel_fast_forward
-        Qwen3MoeForCausalLM.forward = CausalLM_fast_forward(
-            LlamaModel_fast_forward_inference
-        )
+        Qwen3MoeForCausalLM.forward = CausalLM_fast_forward(LlamaModel_fast_forward_inference)
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(Qwen3MoeForCausalLM)
 
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index afa2753994..a9d2a90b8a 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -50,7 +50,6 @@ torch_compile_options = {
 # vLLM compatibility shim (TRL expects GuidedDecodingParams even if vLLM doesn't provide it)
 try:
     import vllm.sampling_params as _unsloth_vllm_sp
-
     if not hasattr(_unsloth_vllm_sp, "GuidedDecodingParams"):
 
         class GuidedDecodingParams:
@@ -82,7 +81,6 @@ except Exception:
 # Get transformers version for feature detection
 try:
     from transformers import __version__ as _transformers_version_raw
-
     transformers_version = Version(_transformers_version_raw)
 except Exception:
     transformers_version = Version("0.0.0")
@@ -160,7 +158,9 @@ def PatchRL(FastLanguageModel):
 
             @_cm
             def unwrap_model_for_generation(
-                model, accelerator, gather_deepspeed3_params = True
+                model,
+                accelerator,
+                gather_deepspeed3_params = True,
             ):
                 unwrapped_model = accelerator.unwrap_model(model)
                 is_gc = getattr(unwrapped_model, "is_gradient_checkpointing", False)
@@ -175,7 +175,6 @@ def PatchRL(FastLanguageModel):
                         yield accelerator.unwrap_model(model)
                     else:
                         import deepspeed
-
                         with deepspeed.zero.GatheredParameters(model.parameters()):
                             yield accelerator.unwrap_model(model)
                 else:
@@ -194,9 +193,7 @@ def PatchRL(FastLanguageModel):
         use_gradient_checkpointing = next(
             (
                 v
-                for v in (
-                    getattr(m, "gradient_checkpointing", False) for m in model.modules()
-                )
+                for v in (getattr(m, "gradient_checkpointing", False) for m in model.modules())
                 if v
             ),
             False,
@@ -231,13 +228,7 @@ def PatchRL(FastLanguageModel):
     from transformers.trainer_pt_utils import nested_detach
 
     @torch.no_grad()
-    def unsloth_prediction_step(
-        self,
-        model,
-        inputs,
-        prediction_loss_only,
-        ignore_keys,
-    ):
+    def unsloth_prediction_step(self, model, inputs, prediction_loss_only, ignore_keys):
         """
         Perform an evaluation step on `model` using `inputs`.
         Subclass and override to inject custom behavior.
@@ -268,16 +259,12 @@ def PatchRL(FastLanguageModel):
         return_loss = inputs.get("return_loss", None)
         if return_loss is None:
             return_loss = self.can_return_loss
-        loss_without_labels = (
-            True if len(self.label_names) == 0 and return_loss else False
-        )
+        loss_without_labels = True if len(self.label_names) == 0 and return_loss else False
 
         inputs = self._prepare_inputs(inputs)
         if ignore_keys is None:
             if hasattr(self.model, "config"):
-                ignore_keys = getattr(
-                    self.model.config, "keys_to_ignore_at_inference", []
-                )
+                ignore_keys = getattr(self.model.config, "keys_to_ignore_at_inference", [])
             else:
                 ignore_keys = []
 
@@ -308,9 +295,7 @@ def PatchRL(FastLanguageModel):
                 loss = loss.mean().detach()
 
                 if isinstance(outputs, dict):
-                    logits = tuple(
-                        v for k, v in outputs.items() if k not in ignore_keys + ["loss"]
-                    )
+                    logits = tuple(v for k, v in outputs.items() if k not in ignore_keys + ["loss"])
                 else:
                     logits = outputs[1:]
             else:
@@ -324,9 +309,7 @@ def PatchRL(FastLanguageModel):
                     ).to(model.device)
                     outputs = model(**tokenized_output)
                 if isinstance(outputs, dict):
-                    logits = tuple(
-                        v for k, v in outputs.items() if k not in ignore_keys
-                    )
+                    logits = tuple(v for k, v in outputs.items() if k not in ignore_keys)
                 else:
                     logits = outputs
                 # TODO: this needs to be fixed and made cleaner later.
@@ -370,8 +353,7 @@ align_completion_tool_mask = RL_REPLACEMENTS.get("align_completion_tool_mask")
 if align_completion_tool_mask is None:
 
     def align_completion_tool_mask(
-        tool_mask: torch.Tensor,
-        completion_mask: torch.Tensor,
+        tool_mask: torch.Tensor, completion_mask: torch.Tensor
     ) -> torch.Tensor:
         if tool_mask is None:
             return completion_mask
@@ -574,9 +556,7 @@ def _wrap_grpo_generate_and_score(trainer_cls):
     trainer_cls._generate_and_score_completions = wrapped
 
 
-_UNSLOTH_RETURN_HIDDEN_STATES_SUPPORT_MARKER = (
-    "__UNSLOTH_SUPPORTS_RETURN_HIDDEN_STATES__"
-)
+_UNSLOTH_RETURN_HIDDEN_STATES_SUPPORT_MARKER = "__UNSLOTH_SUPPORTS_RETURN_HIDDEN_STATES__"
 _UNSLOTH_GRPO_HIDDEN_STATES_WRAPPED_ATTR = "_unsloth_grpo_hidden_states_forward_wrapped"
 _UNSLOTH_GRPO_HIDDEN_STATES_WARNING_ATTR = "_unsloth_grpo_hidden_states_warning_issued"
 
@@ -603,9 +583,7 @@ def _model_supports_unsloth_return_hidden_states(model):
             continue
         if getattr(candidate, _UNSLOTH_RETURN_HIDDEN_STATES_SUPPORT_MARKER, False):
             return True
-        if getattr(
-            type(candidate), _UNSLOTH_RETURN_HIDDEN_STATES_SUPPORT_MARKER, False
-        ):
+        if getattr(type(candidate), _UNSLOTH_RETURN_HIDDEN_STATES_SUPPORT_MARKER, False):
             return True
     return False
 
@@ -682,9 +660,7 @@ def _replace_outputs_logits(outputs, hidden_states):
         return outputs
     if isinstance(outputs, tuple) and len(outputs) != 0:
         return (hidden_states,) + tuple(outputs[1:])
-    raise TypeError(
-        f"Unsupported output type for GRPO hidden-state fallback: {type(outputs)}"
-    )
+    raise TypeError(f"Unsupported output type for GRPO hidden-state fallback: {type(outputs)}")
 
 
 def _install_grpo_hidden_states_forward_wrapper(model):
@@ -706,20 +682,14 @@ def _install_grpo_hidden_states_forward_wrapper(model):
         if os.environ.get("UNSLOTH_RETURN_HIDDEN_STATES", "0") != "1":
             return original_forward(*args, **kwargs)
 
-        forward_kwargs = _drop_forward_kwargs_consumed_positionally(
-            forward_signature, args, kwargs
-        )
-        num_logits_to_keep = _get_num_logits_to_keep(
-            forward_signature, args, forward_kwargs
-        )
+        forward_kwargs = _drop_forward_kwargs_consumed_positionally(forward_signature, args, kwargs)
+        num_logits_to_keep = _get_num_logits_to_keep(forward_signature, args, forward_kwargs)
         forward_kwargs["output_hidden_states"] = True
         forward_kwargs["return_dict"] = True
         try:
             outputs = original_forward(*args, **forward_kwargs)
         except TypeError as error:
-            if "output_hidden_states" not in str(error) and "return_dict" not in str(
-                error
-            ):
+            if "output_hidden_states" not in str(error) and "return_dict" not in str(error):
                 raise
             _warn_grpo_hidden_states_fallback_once(
                 target_model,
@@ -769,8 +739,7 @@ def _patch_trl_rl_trainers(trainer_file = "grpo_trainer"):
         return _patch_trl_rl_trainers_impl(trainer_file)
     except Exception as e:
         logger.info(
-            f"Unsloth: Could not patch trl.trainer.{trainer_file}: "
-            f"{type(e).__name__}: {e}"
+            f"Unsloth: Could not patch trl.trainer.{trainer_file}: " f"{type(e).__name__}: {e}"
         )
         return
 
@@ -832,10 +801,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
                 if _parent is object:
                     continue
                 _parent_mod = inspect.getmodule(_parent)
-                if (
-                    _parent_mod is None
-                    or _parent_mod.__name__ == f"trl.trainer.{trainer_file}"
-                ):
+                if _parent_mod is None or _parent_mod.__name__ == f"trl.trainer.{trainer_file}":
                     continue
                 config = [
                     x
@@ -882,10 +848,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
                     if _parent is object:
                         continue
                     _parent_mod = inspect.getmodule(_parent)
-                    if (
-                        _parent_mod is None
-                        or _parent_mod.__name__ == f"trl.trainer.{trainer_file}"
-                    ):
+                    if _parent_mod is None or _parent_mod.__name__ == f"trl.trainer.{trainer_file}":
                         continue
                     if hasattr(_parent_mod, RLConfig_name):
                         RLConfig = getattr(_parent_mod, RLConfig_name)
@@ -914,13 +877,8 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     try:
         _trainer_src = inspect.getsource(RLTrainer)
         _trainer_module = inspect.getmodule(RLTrainer)
-        _trainer_module_src = (
-            inspect.getsource(_trainer_module) if _trainer_module else ""
-        )
-        if (
-            "trl.experimental" in _trainer_src
-            or "trl.experimental" in _trainer_module_src
-        ):
+        _trainer_module_src = inspect.getsource(_trainer_module) if _trainer_module else ""
+        if "trl.experimental" in _trainer_src or "trl.experimental" in _trainer_module_src:
             for _parent in RLTrainer.__mro__[1:]:
                 if _parent is object:
                     continue
@@ -939,10 +897,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         _config_src = inspect.getsource(RLConfig)
         _config_module = inspect.getmodule(RLConfig)
         _config_module_src = inspect.getsource(_config_module) if _config_module else ""
-        if (
-            "trl.experimental" in _config_src
-            or "trl.experimental" in _config_module_src
-        ):
+        if "trl.experimental" in _config_src or "trl.experimental" in _config_module_src:
             for _parent in RLConfig.__mro__[1:]:
                 if _parent is object:
                     continue
@@ -1293,9 +1248,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     if trainer_file in RL_METRICS_CHANGES:
         process_extra_args = RL_METRICS_CHANGES[trainer_file]
         for process_extra_arg in process_extra_args:
-            other_metrics_processor += process_extra_arg(
-                old_RLTrainer_source, old_RLConfig_source
-            )
+            other_metrics_processor += process_extra_arg(old_RLTrainer_source, old_RLConfig_source)
 
     # Add statistics as well!
     extra_args += (
@@ -1587,12 +1540,8 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     # Selective log softmax and other functions
     selective_log_softmax_code = inspect.getsource(selective_log_softmax)
     grpo_selective_log_softmax_code = inspect.getsource(grpo_selective_log_softmax)
-    calculate_pad_tokens_in_prompt_code = inspect.getsource(
-        calculate_pad_tokens_in_prompt
-    )
-    create_completion_attention_mask_code = inspect.getsource(
-        create_completion_attention_mask
-    )
+    calculate_pad_tokens_in_prompt_code = inspect.getsource(calculate_pad_tokens_in_prompt)
+    create_completion_attention_mask_code = inspect.getsource(create_completion_attention_mask)
     left_pack_padding_code = inspect.getsource(left_pack_padding)
     align_logprobs_with_mask_code = inspect.getsource(align_logprobs_with_mask)
     align_completion_tool_mask_code = inspect.getsource(align_completion_tool_mask)
@@ -1663,9 +1612,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
 
         pattern = r"torch_compile_options\s*=\s*\{[^}]*\}"
 
-        RLTrainer_source = re.sub(
-            pattern, new_options, RLTrainer_source, flags = re.DOTALL
-        )
+        RLTrainer_source = re.sub(pattern, new_options, RLTrainer_source, flags = re.DOTALL)
 
         if trl_version >= Version("0.27.0"):
             peft_pattern = (
@@ -1674,7 +1621,9 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
                 r"param\.data = param\.data\.to\(torch\.bfloat16\)"
             )
 
-            replacement_comment = "\n        # PEFT initialization logic removed via script for trl >= 0.27.0\n"
+            replacement_comment = (
+                "\n        # PEFT initialization logic removed via script for trl >= 0.27.0\n"
+            )
 
             RLTrainer_source = re.sub(
                 peft_pattern, replacement_comment, RLTrainer_source, flags = re.DOTALL
@@ -1707,8 +1656,12 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     )
 
     if RLTrainer_name == "SFTTrainer":
-        original_text = 'self._signature_columns = ["input_ids", "attention_mask", "completion_mask"]'
-        new_text = 'self._signature_columns = ["input_ids", "attention_mask", "completion_mask","labels"]'
+        original_text = (
+            'self._signature_columns = ["input_ids", "attention_mask", "completion_mask"]'
+        )
+        new_text = (
+            'self._signature_columns = ["input_ids", "attention_mask", "completion_mask","labels"]'
+        )
         RLTrainer_source = RLTrainer_source.replace(original_text, new_text)
 
         # Do NOT override _is_vlm -- let TRL detect VLM models naturally.
@@ -1734,9 +1687,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
             "        if self._is_vision_dataset and not self._is_vlm:"
         )
         if _vlm_check_original in RLTrainer_source:
-            RLTrainer_source = RLTrainer_source.replace(
-                _vlm_check_original, _vlm_check_patched
-            )
+            RLTrainer_source = RLTrainer_source.replace(_vlm_check_original, _vlm_check_patched)
 
         # Fix TRL 0.22.x: VLM models with text-only datasets.
         # TRL 0.22.x checks _is_vlm (model type) not _is_vision_dataset (dataset
@@ -1745,9 +1696,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         # overlap with tokenized text columns. Fix: merge both column sets into the
         # VLM branch. Extra columns not in the dataset are harmlessly ignored by
         # _remove_unused_columns (it only raises when zero columns match).
-        _sig_vlm_old = (
-            'self._signature_columns = ["messages", "prompt", "completion", "images"]'
-        )
+        _sig_vlm_old = 'self._signature_columns = ["messages", "prompt", "completion", "images"]'
         _sig_vlm_new = (
             'self._signature_columns = ["messages", "prompt", "completion", "images",'
             ' "input_ids", "labels", "attention_mask", "seq_lengths", "completion_mask", "assistant_masks"]'
@@ -1757,10 +1706,10 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         # Inject model reference before _prepare_dataset for dynamic
         # token_type_ids detection in sft_prepare_dataset
         _prep_pattern = r"([ \t]*)train_dataset = self\._prepare_dataset\("
-        _prep_replacement = r"\1self._unsloth_model_ref = model\n\1train_dataset = self._prepare_dataset("
-        RLTrainer_source = re.sub(
-            _prep_pattern, _prep_replacement, RLTrainer_source, count = 1
+        _prep_replacement = (
+            r"\1self._unsloth_model_ref = model\n\1train_dataset = self._prepare_dataset("
         )
+        RLTrainer_source = re.sub(_prep_pattern, _prep_replacement, RLTrainer_source, count = 1)
 
     # Silence TRL's noisy batch_size=1 + padding-free warning (handles both
     # the original "anihilate" typo and the corrected "annihilate" spelling)
@@ -1769,9 +1718,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         if _idx == -1:
             continue
         # Walk backwards to find "if args.per_device_train_batch_size"
-        _block_start = RLTrainer_source.rfind(
-            "if args.per_device_train_batch_size == 1", 0, _idx
-        )
+        _block_start = RLTrainer_source.rfind("if args.per_device_train_batch_size == 1", 0, _idx)
         if _block_start == -1:
             continue
         # Walk backwards to the newline before the if
@@ -1783,9 +1730,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         _block_end = RLTrainer_source.find("\n", _close)
         if _block_end == -1:
             continue
-        RLTrainer_source = (
-            RLTrainer_source[:_line_start] + RLTrainer_source[_block_end:]
-        )
+        RLTrainer_source = RLTrainer_source[:_line_start] + RLTrainer_source[_block_end:]
         break
 
     # Remove multiple doc strings
@@ -1798,9 +1743,7 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
     # Create new function
     _resolved_module = _trainer_resolved_module or _config_resolved_module
     _model_location = (
-        _resolved_module.__name__
-        if _resolved_module is not None
-        else f"trl.trainer.{trainer_file}"
+        _resolved_module.__name__ if _resolved_module is not None else f"trl.trainer.{trainer_file}"
     )
     created_module = create_new_function(
         f"Unsloth{RLTrainer_name}",
@@ -1860,17 +1803,13 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
 
     if trainer_file == "grpo_trainer":
         try:
-            _wrap_grpo_generate_and_score(
-                getattr(created_module, f"Unsloth{RLTrainer_name}")
-            )
+            _wrap_grpo_generate_and_score(getattr(created_module, f"Unsloth{RLTrainer_name}"))
         except Exception as e:
             logger.info(
                 f"Unsloth: Could not wrap _generate_and_score_completions for {RLTrainer_name}: {e}"
             )
         try:
-            _wrap_grpo_hidden_states_fallback(
-                getattr(created_module, f"Unsloth{RLTrainer_name}")
-            )
+            _wrap_grpo_hidden_states_fallback(getattr(created_module, f"Unsloth{RLTrainer_name}"))
         except Exception as e:
             logger.info(
                 f"Unsloth: Could not wrap GRPO hidden-state fallback for {RLTrainer_name}: {e}"
@@ -1903,9 +1842,7 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
         "if False:",
     )
     # New TRL 0.20.0
-    init = init.replace(
-        "model = self._prepare_peft_model(model, peft_config, args)\n", "pass\n"
-    )
+    init = init.replace("model = self._prepare_peft_model(model, peft_config, args)\n", "pass\n")
     # TRL 0.22.0+ uses prepare_peft_model as a standalone function
     init = init.replace("model = prepare_peft_model(model, peft_config, args)", "pass")
 
@@ -2000,7 +1937,7 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
 
         # Get SamplingParams
         sampling_params = re.findall(
-            r"\n[\s]{4,}(self\.[^\s]{1,}[\s]{0,}\=[\s]{0,}" r"SamplingParams\(.+?\))",
+            r"\n[\s]{4,}(self\.[^\s]{1,}[\s]{0,}\=[\s]{0,}SamplingParams\(.+?\))",
             new_vllm_part,
             flags = re.MULTILINE | re.DOTALL,
         )
@@ -2028,9 +1965,7 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
             if len(splitted_sampling_params) >= 2:
                 last_line = splitted_sampling_params[-1]
                 last_prev_line = splitted_sampling_params[-2]
-                last_prev_indentation = len(last_prev_line) - len(
-                    last_prev_line.lstrip()
-                )
+                last_prev_indentation = len(last_prev_line) - len(last_prev_line.lstrip())
                 last_indentation = len(last_line) - len(last_line.lstrip())
 
                 # Add extra arguments to SamplingParams
@@ -2049,16 +1984,13 @@ def patch_functions(RLTrainer, trainer_file, RLTrainer_name, all_imports, import
                 sampling_params = re.sub(r"[\,][\s]{0,}\,", ",", sampling_params)
 
                 new_vllm_part = (
-                    f"\n{' ' * 8}if {args}.use_vllm:\n{sampling_params}"
-                    f"\n{' ' * 8}else:\n"
+                    f"\n{' ' * 8}if {args}.use_vllm:\n{sampling_params}" f"\n{' ' * 8}else:\n"
                 )
 
         if trl_version >= Version("0.18.0"):
             # Guard LLM init - use existing vLLM engine when sharing weights,
             # otherwise keep the original LLM() creation for sync/reload path
-            vllm_llm_init_pattern = (
-                r"(?P<indent>[ \t]*)self\.llm\s*=\s*LLM\(.*?\)*\)\s*?\n(?!,)"
-            )
+            vllm_llm_init_pattern = r"(?P<indent>[ \t]*)self\.llm\s*=\s*LLM\(.*?\)*\)\s*?\n(?!,)"
 
             def guard_llm_init(match):
                 indent = match.group("indent")
@@ -2216,9 +2148,7 @@ def patch_trl_rl_trainers():
 
     all_trainers = dir(trl.trainer)
     all_trainers = [
-        x
-        for x in all_trainers
-        if x.islower() and x.endswith("_trainer") and x != "base_trainer"
+        x for x in all_trainers if x.islower() and x.endswith("_trainer") and x != "base_trainer"
     ]
     for trainer in all_trainers:
         try:
@@ -2318,9 +2248,7 @@ def patch_trl_vllm_generation():
     # We need to min_p patch it to not instantiate another vLLM instance if we already have one with fast_inference
     # Find the instance of self.llm = LLM(..) (multiline) and wrap it around an if clause
     for function in RL_ADDITIONAL_FUNCTIONS["vllm_generation"]:
-        logger.info(
-            f"Unsloth: Patching trl VLLMGeneration with function: {function.__name__}"
-        )
+        logger.info(f"Unsloth: Patching trl VLLMGeneration with function: {function.__name__}")
         function()
     return
 
@@ -2330,9 +2258,7 @@ def patch_trl_vllm_generation():
     # We need to min_p patch it to not instantiate another vLLM instance if we already have one with fast_inference
     # Find the instance of self.llm = LLM(..) (multiline) and wrap it around an if clause
     for function in RL_ADDITIONAL_FUNCTIONS["vllm_generation"]:
-        logger.info(
-            f"Unsloth: Patching trl VLLMGeneration with function: {function.__name__}"
-        )
+        logger.info(f"Unsloth: Patching trl VLLMGeneration with function: {function.__name__}")
         function()
     return
 
diff --git a/unsloth/models/rl_replacements.py b/unsloth/models/rl_replacements.py
index 7bceebb252..ab18a5ec93 100644
--- a/unsloth/models/rl_replacements.py
+++ b/unsloth/models/rl_replacements.py
@@ -62,9 +62,7 @@ def _unsloth_clear_stateful_mrope(model):
 
     cleared = False
     for module in modules():
-        if hasattr(module, "compute_3d_position_ids") and hasattr(
-            module, "rope_deltas"
-        ):
+        if hasattr(module, "compute_3d_position_ids") and hasattr(module, "rope_deltas"):
             module.rope_deltas = None
             cleared = True
     return cleared
@@ -185,12 +183,8 @@ def dpo_trainer_vision_process_row(
     )
 
     prompt_input_ids = processed_features["input_ids"][0]
-    chosen_input_ids = tokenizer(features["chosen"], add_special_tokens = False)[
-        "input_ids"
-    ]
-    rejected_input_ids = tokenizer(features["rejected"], add_special_tokens = False)[
-        "input_ids"
-    ]
+    chosen_input_ids = tokenizer(features["chosen"], add_special_tokens = False)["input_ids"]
+    rejected_input_ids = tokenizer(features["rejected"], add_special_tokens = False)["input_ids"]
 
     if add_special_tokens:
         if tokenizer.bos_token_id is not None:
@@ -245,7 +239,7 @@ def dpo_trainer_vision_signature_columns(function_name, function):
 
     _extra_columns = "".join(f'                "{_k}",\n' for _k in _DPO_VISION_KEYS)
     new_function = function.replace(
-        '                "image_sizes",\n' '                "token_type_ids",\n',
+        '                "image_sizes",\n                "token_type_ids",\n',
         f'                "image_sizes",\n'
         f"{_extra_columns}"
         f'                "token_type_ids",\n',
@@ -253,7 +247,7 @@ def dpo_trainer_vision_signature_columns(function_name, function):
     if new_function != function:
         return new_function
     return function.replace(
-        '                "image_sizes",\n' '                "ref_chosen_logps",\n',
+        '                "image_sizes",\n                "ref_chosen_logps",\n',
         f'                "image_sizes",\n'
         f"{_extra_columns}"
         f'                "ref_chosen_logps",\n',
@@ -413,10 +407,7 @@ RL_EXTRA_ARGS["dpo_trainer"].append(dpo_trainer_data_collator_vision_keys)
 
 # Fix tokenizer double BOS
 def sft_trainer_prepare_dataset(function_name, function):
-    if (
-        function_name != "_prepare_non_packed_dataloader"
-        and function_name != "_prepare_dataset"
-    ):
+    if function_name != "_prepare_non_packed_dataloader" and function_name != "_prepare_dataset":
         return function
 
     fast_sft_prepare_dataset = RL_REPLACEMENTS.get("sft_prepare_dataset", None)
@@ -433,9 +424,7 @@ def sft_trainer_prepare_dataset(function_name, function):
             function = inspect.getsource(fast_sft_prepare_dataset)
             function = function.split("\n")
             function = "\n".join(" " * 4 + x for x in function)
-            function = function.replace(
-                "def sft_prepare_dataset", "def _prepare_dataset"
-            )
+            function = function.replace("def sft_prepare_dataset", "def _prepare_dataset")
             return function
 
     check_text = (
@@ -482,9 +471,7 @@ def sft_trainer_prepare_dataset(function_name, function):
         function = function.replace(replacer, replacer + check_text)
 
     # Return tokenizer's original state
-    return_state = (
-        "if tokenizer_call is not None: tokenizer.__call__ = tokenizer_call\n"
-    )
+    return_state = "if tokenizer_call is not None: tokenizer.__call__ = tokenizer_call\n"
     function = re.sub(
         r"\n([ ]{4,})(return .*?[\s]{0,})$",
         rf"\1{return_state}\1\2",
@@ -503,7 +490,11 @@ def sft_trainer_compute_loss(function_name, function):
         return function
 
     def compute_loss(
-        self, model, inputs, return_outputs = False, num_items_in_batch = None
+        self,
+        model,
+        inputs,
+        return_outputs = False,
+        num_items_in_batch = None,
     ):
         outputs = super().compute_loss(
             model,
@@ -558,12 +549,8 @@ def orpo_trainer_text_tokenizer(function_name, function):
             return function
         function = new_function
     function = function.replace("self.processing_class(", "tokenizer(")
-    function = function.replace(
-        "self.processing_class.bos_token_id", "tokenizer.bos_token_id"
-    )
-    function = function.replace(
-        "self.processing_class.eos_token_id", "tokenizer.eos_token_id"
-    )
+    function = function.replace("self.processing_class.bos_token_id", "tokenizer.bos_token_id")
+    function = function.replace("self.processing_class.eos_token_id", "tokenizer.eos_token_id")
     return function
 
 
@@ -696,9 +683,7 @@ def grpo_trainer__generate_single_turn(function_name, function):
     ]:
         function = re.sub(pattern, "", function)
 
-    string_to_find = (
-        "            generate_inputs = super()._prepare_inputs(generate_inputs)"
-    )
+    string_to_find = "            generate_inputs = super()._prepare_inputs(generate_inputs)"
     replacement_string = (
         string_to_find
         + """
@@ -799,8 +784,7 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
 
     # Always between max_prompt_length and use_vllm
     found = re.findall(
-        r"\n(([ ]{8,})if self\.max_prompt_length is not None:.*?"
-        r"\2if self\.use_vllm:)",
+        r"\n(([ ]{8,})if self\.max_prompt_length is not None:.*?\2if self\.use_vllm:)",
         function,
         flags = re.DOTALL | re.MULTILINE,
     )
@@ -841,9 +825,7 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
     # We must adjust the vLLM sampling_logprob tensor in Unsloth to account for this.
     string_to_find = "if self.use_vllm and self.vllm_importance_sampling_correction:"
 
-    replacement_string = (
-        "if False and self.use_vllm and self.vllm_importance_sampling_correction:"
-    )
+    replacement_string = "if False and self.use_vllm and self.vllm_importance_sampling_correction:"
 
     function = function.replace(string_to_find, replacement_string)
 
@@ -965,11 +947,11 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
             if _mm_token_type_ids is not None:
                 forward_kwargs["mm_token_type_ids"] = _mm_token_type_ids
 """
-    _tool_image_marker = "        # For VLM tool images: build token type IDs from the full prompt_completion_ids."
+    _tool_image_marker = (
+        "        # For VLM tool images: build token type IDs from the full prompt_completion_ids."
+    )
     if _tool_image_marker in function:
-        function = function.replace(
-            _tool_image_marker, _mm_alignment + "\n" + _tool_image_marker
-        )
+        function = function.replace(_tool_image_marker, _mm_alignment + "\n" + _tool_image_marker)
     else:
         _tt_search = (
             'if "token_type_ids" in forward_kwargs:\n'
@@ -978,9 +960,7 @@ def grpo_trainer__generate_and_score_completions(function_name, function):
             "                [token_type_ids, token_type_ids.new_zeros(completion_ids.shape)], dim=1\n"
             "            )"
         )
-        function = function.replace(
-            _tt_search, _tt_search + "\n" + _mm_alignment.rstrip()
-        )
+        function = function.replace(_tt_search, _tt_search + "\n" + _mm_alignment.rstrip())
 
     _save_search = (
         'if "token_type_ids" in forward_kwargs:\n'
@@ -1042,9 +1022,7 @@ def grpo_trainer_fix_maybe_apply_chat_template(function_name, function):
     replacement = textwrap.indent(replacement, spaces * " ")
     replacement = f"\n{replacement}\n"
     what = 'prompts_text = [maybe_apply_chat_template(example, self.processing_class)["prompt"] for example in inputs]'
-    function = function.replace(
-        what, replacement.replace("__INPUTS__REPLACEMENT__", "inputs")
-    )
+    function = function.replace(what, replacement.replace("__INPUTS__REPLACEMENT__", "inputs"))
 
     """prompts_text = [
         maybe_apply_chat_template({"prompt": prompt}, self.processing_class)["prompt"] for prompt in prompts
@@ -1086,7 +1064,12 @@ def grpo_trainer__get_per_token_logps(function_name, function):
         return function
 
     def _get_per_token_logps(
-        self, model, input_ids, attention_mask, logits_to_keep, compute_efficient = False
+        self,
+        model,
+        input_ids,
+        attention_mask,
+        logits_to_keep,
+        compute_efficient = False,
     ):
         if True:  # os.environ.get('UNSLOTH_USE_NEW_MODEL', '0') == '0':
             return None  # Unsloth efficient GRPO
@@ -1183,15 +1166,11 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                     self.processing_class, input_ids, mm_token_type_ids
                 )
 
-            unwrapped_model = self.accelerator.unwrap_model(
-                model, keep_fp32_wrapper = False
-            )
+            unwrapped_model = self.accelerator.unwrap_model(model, keep_fp32_wrapper = False)
 
             lm_head = self.model.get_output_embeddings().weight
 
-            dtype_bytes = (
-                16 if self._autocast_dtype in [torch.float16, torch.bfloat16] else 32
-            )
+            dtype_bytes = 16 if self._autocast_dtype in [torch.float16, torch.bfloat16] else 32
             total_rows = input_ids.shape[0]
             seq_len = input_ids.shape[1]
             hidden_dim = lm_head.shape[1]
@@ -1221,9 +1200,7 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                     input_ids, logits_to_keep, self.processing_class.pad_token_id
                 )
                 max_left_pad = torch.max(left_pad_tokens_per_prompt).item()
-                input_ids = left_pack_padding(
-                    input_ids, self.processing_class.pad_token_id
-                )
+                input_ids = left_pack_padding(input_ids, self.processing_class.pad_token_id)
                 attention_mask = input_ids != self.processing_class.pad_token_id
                 attention_mask = attention_mask.to(attention_mask.dtype)
             else:
@@ -1240,11 +1217,7 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
             batch_size = math.ceil(total_samples / B)
             if isinstance(num_images, torch.Tensor):
                 num_images = num_images.detach().cpu().reshape(-1).tolist()
-            if (
-                image_grid_thw is not None
-                and pixel_values is not None
-                and num_images is not None
-            ):
+            if image_grid_thw is not None and pixel_values is not None and num_images is not None:
                 rows_per_image = image_grid_thw.prod(dim = -1)
                 rows_per_sample = torch.split(rows_per_image, num_images)
                 rows_per_sample = torch.stack([s.sum() for s in rows_per_sample])
@@ -1290,12 +1263,8 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
 
                 input_ids_chunks.append(input_ids[start:end])
                 attention_mask_chunks.append(attention_mask[start:end])
-                token_type_ids_chunks.append(
-                    slice_sample_axis(token_type_ids, start, end)
-                )
-                mm_token_type_ids_chunks.append(
-                    slice_sample_axis(mm_token_type_ids, start, end)
-                )
+                token_type_ids_chunks.append(slice_sample_axis(token_type_ids, start, end))
+                mm_token_type_ids_chunks.append(slice_sample_axis(mm_token_type_ids, start, end))
 
                 if image_grid_thw is not None and pixel_values is not None:
                     if num_images is None:
@@ -1313,9 +1282,7 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                         grid_slice = image_grid_thw[img_start:img_end]
                     image_grid_thw_chunks.append(grid_slice)
 
-                    pixel_values_chunks.append(
-                        pixel_values[start_pixel_idx:end_pixel_idx]
-                    )
+                    pixel_values_chunks.append(pixel_values[start_pixel_idx:end_pixel_idx])
 
                     if image_sizes is None:
                         image_sizes_chunks.append(None)
@@ -1326,9 +1293,7 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                     ):
                         image_sizes_chunks.append(image_sizes[img_start:img_end])
                     else:
-                        image_sizes_chunks.append(
-                            slice_sample_axis(image_sizes, start, end)
-                        )
+                        image_sizes_chunks.append(slice_sample_axis(image_sizes, start, end))
 
                     if pixel_attention_mask is None:
                         pixel_attention_mask_chunks.append(None)
@@ -1337,9 +1302,7 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                         and img_start is not None
                         and pixel_attention_mask.shape[0] == image_grid_thw.shape[0]
                     ):
-                        pixel_attention_mask_chunks.append(
-                            pixel_attention_mask[img_start:img_end]
-                        )
+                        pixel_attention_mask_chunks.append(pixel_attention_mask[img_start:img_end])
                     elif (
                         pixel_attention_mask.shape[0] == pixel_values.shape[0]
                         and pixel_attention_mask.shape[0] != input_ids.shape[0]
@@ -1348,17 +1311,13 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                             pixel_attention_mask[start_pixel_idx:end_pixel_idx]
                         )
                     else:
-                        pixel_attention_mask_chunks.append(
-                            pixel_attention_mask[start:end]
-                        )
+                        pixel_attention_mask_chunks.append(pixel_attention_mask[start:end])
 
                 else:
                     pixel_values_chunks.append(None)
                     image_grid_thw_chunks.append(None)
                     pixel_attention_mask_chunks.append(None)
-                    image_sizes_chunks.append(
-                        slice_sample_axis(image_sizes, start, end)
-                    )
+                    image_sizes_chunks.append(slice_sample_axis(image_sizes, start, end))
 
             temperature = self.temperature
             logit_softcapping = _unsloth_get_final_logit_softcapping(model.config)
@@ -1396,12 +1355,8 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                     if token_type_ids_chunk is not None:
                         _extra_vision_kwargs["token_type_ids"] = token_type_ids_chunk
                     if mm_token_type_ids_chunk is not None:
-                        _extra_vision_kwargs["mm_token_type_ids"] = (
-                            mm_token_type_ids_chunk
-                        )
-                    with torch.amp.autocast(
-                        device_type = "cuda", dtype = self._autocast_dtype
-                    ):
+                        _extra_vision_kwargs["mm_token_type_ids"] = mm_token_type_ids_chunk
+                    with torch.amp.autocast(device_type = "cuda", dtype = self._autocast_dtype):
                         if pixel_values is None:
                             logits_chunk = unwrapped_model(
                                 input_ids = input_ids_chunk,
@@ -1420,17 +1375,15 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                                 :, -(logits_to_keep + max_left_pad + 1) :, :
                             ]
                             logits_chunk = logits_chunk[:, :-1, :]
-                            logprobs_chunk = (
-                                chunked_hidden_states_selective_log_softmax(
-                                    logits_chunk,
-                                    lm_head,
-                                    completion_input_ids_chunk,
-                                    chunks = input_ids_chunk.shape[0] * multiplier,
-                                    logit_scale_multiply = logit_scale_multiply,
-                                    logit_scale_divide = logit_scale_divide,
-                                    logit_softcapping = logit_softcapping,
-                                    temperature = temperature,
-                                )
+                            logprobs_chunk = chunked_hidden_states_selective_log_softmax(
+                                logits_chunk,
+                                lm_head,
+                                completion_input_ids_chunk,
+                                chunks = input_ids_chunk.shape[0] * multiplier,
+                                logit_scale_multiply = logit_scale_multiply,
+                                logit_scale_divide = logit_scale_divide,
+                                logit_softcapping = logit_softcapping,
+                                temperature = temperature,
                             )
                         else:
                             # Essentially, for VLMs we do not go via the optimized path in models/,
@@ -1447,22 +1400,18 @@ def grpo_trainer__get_per_token_logps_and_entropies(function_name, function):
                             ).logits
 
                             logits_chunk = logits_chunk[:, :-1, :]
-                            completion_input_ids_chunk = input_ids_chunk[
-                                :, -logits_to_keep:
-                            ]
+                            completion_input_ids_chunk = input_ids_chunk[:, -logits_to_keep:]
                             # Guard: check if model returned hidden states or logits
                             if logits_chunk.shape[-1] == lm_head.shape[1]:
-                                logprobs_chunk = (
-                                    chunked_hidden_states_selective_log_softmax(
-                                        logits_chunk,
-                                        lm_head,
-                                        completion_input_ids_chunk,
-                                        chunks = input_ids_chunk.shape[0] * multiplier,
-                                        logit_scale_multiply = logit_scale_multiply,
-                                        logit_scale_divide = logit_scale_divide,
-                                        logit_softcapping = logit_softcapping,
-                                        temperature = temperature,
-                                    )
+                                logprobs_chunk = chunked_hidden_states_selective_log_softmax(
+                                    logits_chunk,
+                                    lm_head,
+                                    completion_input_ids_chunk,
+                                    chunks = input_ids_chunk.shape[0] * multiplier,
+                                    logit_scale_multiply = logit_scale_multiply,
+                                    logit_scale_divide = logit_scale_divide,
+                                    logit_softcapping = logit_softcapping,
+                                    temperature = temperature,
                                 )
                             else:
                                 # Model returned logits directly - scaling/softcapping already applied by model forward
@@ -1533,9 +1482,7 @@ grpo_compute_loss_slow = RL_REPLACEMENTS["grpo_compute_loss_slow"]
 UnslothEfficientGRPO = RL_REPLACEMENTS["UnslothEfficientGRPO"]
 grpo_accumulated_loss = RL_REPLACEMENTS["grpo_accumulated_loss"]
 grpo_update_SamplingParams = RL_REPLACEMENTS["grpo_update_SamplingParams"]
-RL_PRE_ITEMS["grpo_trainer"].append(
-    inspect.getsource(_unsloth_get_final_logit_softcapping)
-)
+RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_get_final_logit_softcapping))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_get_mm_token_id))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_fix_mm_token_type_ids))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_unsloth_clear_stateful_mrope))
@@ -1544,9 +1491,7 @@ RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(UnslothEfficientGRPO))
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(grpo_accumulated_loss))
 RL_PRE_ITEMS["grpo_trainer"].append(grpo_compute_loss_slow)
 RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(grpo_update_SamplingParams))
-RL_PRE_ITEMS["grpo_trainer"].append(
-    inspect.getsource(_get_inference_mode_context_manager)
-)
+RL_PRE_ITEMS["grpo_trainer"].append(inspect.getsource(_get_inference_mode_context_manager))
 
 
 # Edit _get_per_token_logps to handle mixed precision
@@ -1555,7 +1500,11 @@ def grpo_trainer_compute_loss(function_name, function):
         return function
 
     def compute_loss(
-        self, model, inputs, return_outputs = False, num_items_in_batch = None
+        self,
+        model,
+        inputs,
+        return_outputs = False,
+        num_items_in_batch = None,
     ):
         if return_outputs:
             raise ValueError("The GRPOTrainer does not support returning outputs")
@@ -1797,30 +1746,28 @@ def grpo_trainer_compute_loss(function_name, function):
                 )
             else:
                 # to ensure backwards compatibility with trl 0.15.2 and maybe even 0.17
-                loss, completion_length, mean_kl, coef_1, completion_mask = (
-                    grpo_accumulated_loss(
-                        trainer = self,
-                        input_ids = _input_ids,
-                        pixel_values = pixel_values,
-                        image_grid_thw = image_grid_thw,
-                        pixel_attention_mask = pixel_attention_mask,
-                        image_sizes = image_sizes,
-                        num_images = num_images,
-                        logits_to_keep = logits_to_keep,
-                        completion_mask = completion_mask,
-                        advantages = advantages,
-                        old_logps = old_logps,
-                        ref_logps = ref_logps,
-                        n_chunks = self.args.unsloth_num_chunks,
-                        temperature = self.args.temperature,
-                        logit_softcapping = logit_softcapping,
-                        logit_scale_multiply = logit_scale_multiply,
-                        logit_scale_divide = logit_scale_divide,
-                        attention_mask = attention_mask,
-                        token_type_ids = token_type_ids,
-                        mm_token_type_ids = mm_token_type_ids,
-                        **_grpo_accumulated_loss_kwargs,
-                    )
+                loss, completion_length, mean_kl, coef_1, completion_mask = grpo_accumulated_loss(
+                    trainer = self,
+                    input_ids = _input_ids,
+                    pixel_values = pixel_values,
+                    image_grid_thw = image_grid_thw,
+                    pixel_attention_mask = pixel_attention_mask,
+                    image_sizes = image_sizes,
+                    num_images = num_images,
+                    logits_to_keep = logits_to_keep,
+                    completion_mask = completion_mask,
+                    advantages = advantages,
+                    old_logps = old_logps,
+                    ref_logps = ref_logps,
+                    n_chunks = self.args.unsloth_num_chunks,
+                    temperature = self.args.temperature,
+                    logit_softcapping = logit_softcapping,
+                    logit_scale_multiply = logit_scale_multiply,
+                    logit_scale_divide = logit_scale_divide,
+                    attention_mask = attention_mask,
+                    token_type_ids = token_type_ids,
+                    mm_token_type_ids = mm_token_type_ids,
+                    **_grpo_accumulated_loss_kwargs,
                 )
         if "train" in self._metrics:
             mode = "eval" if self.control.should_evaluate else "train"
@@ -1905,19 +1852,11 @@ def grpo_trainer_compute_loss(function_name, function):
             clip_ratio = masked_batch_mean(is_region_clipped.float())
 
             gathered_low_clip = self.accelerator.gather(low_clip)
-            self._metrics[mode]["clip_ratio/low_mean"].append(
-                gathered_low_clip.nanmean().item()
-            )
-            self._metrics[mode]["clip_ratio/low_min"].append(
-                nanmin(gathered_low_clip).item()
-            )
+            self._metrics[mode]["clip_ratio/low_mean"].append(gathered_low_clip.nanmean().item())
+            self._metrics[mode]["clip_ratio/low_min"].append(nanmin(gathered_low_clip).item())
             gathered_high_clip = self.accelerator.gather(high_clip)
-            self._metrics[mode]["clip_ratio/high_mean"].append(
-                gathered_high_clip.nanmean().item()
-            )
-            self._metrics[mode]["clip_ratio/high_max"].append(
-                nanmax(gathered_high_clip).item()
-            )
+            self._metrics[mode]["clip_ratio/high_mean"].append(gathered_high_clip.nanmean().item())
+            self._metrics[mode]["clip_ratio/high_max"].append(nanmax(gathered_high_clip).item())
             gathered_clip_ratio = self.accelerator.gather(clip_ratio)
             self._metrics[mode]["clip_ratio/region_mean"].append(
                 gathered_clip_ratio.nanmean().item()
@@ -2198,9 +2137,7 @@ def vllm_generation_init_patch():
         try:
             src = inspect.getsource(method)
         except Exception as e:
-            logger.info(
-                f"Unsloth: Could not get source of VLLMGeneration.{method_name}: {e}"
-            )
+            logger.info(f"Unsloth: Could not get source of VLLMGeneration.{method_name}: {e}")
             return False
 
         src = textwrap.dedent(src)
@@ -2292,9 +2229,7 @@ def vllm_generation_init_patch():
                 f'{indent}    self.llm.collective_rpc("reload_weights")'
             )
 
-        patched_src, num_replacements = pattern.subn(
-            replace_reload_weights, src, count = 1
-        )
+        patched_src, num_replacements = pattern.subn(replace_reload_weights, src, count = 1)
         if num_replacements == 0:
             raise RuntimeError(
                 "Unsloth: Warning - regex did not match, VLLMGeneration.generate patch may have failed"
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index aafc416221..a42340f282 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -234,10 +234,7 @@ def _save_pretrained_gguf(
 
             # Check if file is inside transformer_dir (subpath)
             try:
-                is_subpath = (
-                    os.path.commonpath([abs_gguf_file, transformer_dir])
-                    == transformer_dir
-                )
+                is_subpath = os.path.commonpath([abs_gguf_file, transformer_dir]) == transformer_dir
             except ValueError:
                 # Can happen on Windows with different drives, or mix of absolute/relative (handled by abspath above)
                 is_subpath = False
@@ -280,9 +277,7 @@ def _save_pretrained_gguf(
 
         print(f"Unsloth: Uploading to {repo_id}...")
         try:
-            api.create_repo(
-                repo_id = repo_id, exist_ok = True, private = kwargs.get("private", False)
-            )
+            api.create_repo(repo_id = repo_id, exist_ok = True, private = kwargs.get("private", False))
             api.upload_folder(
                 folder_path = save_directory,
                 repo_id = repo_id,
@@ -520,9 +515,7 @@ This sentence-transformers model was finetuned and converted to GGUF format usin
     except:
         pass
 
-    print(
-        f"Unsloth: Successfully uploaded GGUF to https://huggingface.co/{full_repo_id}"
-    )
+    print(f"Unsloth: Successfully uploaded GGUF to https://huggingface.co/{full_repo_id}")
     return full_repo_id
 
 
@@ -560,9 +553,7 @@ class FastSentenceTransformer(FastModel):
                 getattr(self, "_unsloth_base_config", None), output_path
             )
 
-        transformer_module.save = types.MethodType(
-            _save_with_base_config, transformer_module
-        )
+        transformer_module.save = types.MethodType(_save_with_base_config, transformer_module)
         transformer_module._unsloth_save_config_patched = True
         return transformer_module
 
@@ -577,9 +568,7 @@ class FastSentenceTransformer(FastModel):
             ):
                 modules_json_path = os.path.join(model_name, "modules.json")
             else:
-                modules_json_path = hf_hub_download(
-                    model_name, "modules.json", token = token
-                )
+                modules_json_path = hf_hub_download(model_name, "modules.json", token = token)
 
             with open(modules_json_path, "r", encoding = "utf-8") as f:
                 modules_config = json.load(f)
@@ -642,15 +631,17 @@ class FastSentenceTransformer(FastModel):
         modeling_mpnet.MPNetModel.supports_gradient_checkpointing = True
 
         # add _set_gradient_checkpointing method
-        def _set_gradient_checkpointing(self, module = None, value = True):
+        def _set_gradient_checkpointing(
+            self,
+            module = None,
+            value = True,
+        ):
             if module is None:
                 module = self.encoder
             if isinstance(module, modeling_mpnet.MPNetEncoder):
                 module.gradient_checkpointing = value
 
-        modeling_mpnet.MPNetModel._set_gradient_checkpointing = (
-            _set_gradient_checkpointing
-        )
+        modeling_mpnet.MPNetModel._set_gradient_checkpointing = _set_gradient_checkpointing
 
         # patch MPNetEncoder.forward to support checkpointing
         # based on:
@@ -712,9 +703,7 @@ class FastSentenceTransformer(FastModel):
 
             if not return_dict:
                 return tuple(
-                    v
-                    for v in [hidden_states, all_hidden_states, all_attentions]
-                    if v is not None
+                    v for v in [hidden_states, all_hidden_states, all_attentions] if v is not None
                 )
             return BaseModelOutput(
                 last_hidden_state = hidden_states,
@@ -737,15 +726,17 @@ class FastSentenceTransformer(FastModel):
         modeling_mpnet.MPNetModel.supports_gradient_checkpointing = True
 
         # add _set_gradient_checkpointing method
-        def _set_gradient_checkpointing(self, module = None, value = True):
+        def _set_gradient_checkpointing(
+            self,
+            module = None,
+            value = True,
+        ):
             if module is None:
                 module = self.encoder
             if isinstance(module, modeling_mpnet.MPNetEncoder):
                 module.gradient_checkpointing = value
 
-        modeling_mpnet.MPNetModel._set_gradient_checkpointing = (
-            _set_gradient_checkpointing
-        )
+        modeling_mpnet.MPNetModel._set_gradient_checkpointing = _set_gradient_checkpointing
 
         # patch MPNetEncoder.forward to support checkpointing
         # based on:
@@ -804,9 +795,7 @@ class FastSentenceTransformer(FastModel):
 
             if not return_dict:
                 return tuple(
-                    v
-                    for v in [hidden_states, all_hidden_states, all_attentions]
-                    if v is not None
+                    v for v in [hidden_states, all_hidden_states, all_attentions] if v is not None
                 )
             return BaseModelOutput(
                 last_hidden_state = hidden_states,
@@ -847,9 +836,7 @@ class FastSentenceTransformer(FastModel):
                 if output_hidden_states is not None
                 else self.config.output_hidden_states
             )
-            return_dict = (
-                return_dict if return_dict is not None else self.config.use_return_dict
-            )
+            return_dict = return_dict if return_dict is not None else self.config.use_return_dict
 
             if input_ids is not None and inputs_embeds is not None:
                 raise ValueError(
@@ -861,9 +848,7 @@ class FastSentenceTransformer(FastModel):
             elif inputs_embeds is not None:
                 input_shape = inputs_embeds.size()[:-1]
             else:
-                raise ValueError(
-                    "You have to specify either input_ids or inputs_embeds"
-                )
+                raise ValueError("You have to specify either input_ids or inputs_embeds")
 
             device = input_ids.device if input_ids is not None else inputs_embeds.device
 
@@ -871,21 +856,15 @@ class FastSentenceTransformer(FastModel):
             # Prepare head mask if needed
             head_mask = self.get_head_mask(head_mask, self.config.num_hidden_layers)
 
-            embeddings = self.embeddings(
-                input_ids, inputs_embeds
-            )  # (bs, seq_length, dim)
+            embeddings = self.embeddings(input_ids, inputs_embeds)  # (bs, seq_length, dim)
 
             if self.config._attn_implementation == "flash_attention_2":
                 attention_mask = (
-                    attention_mask
-                    if (attention_mask is not None and 0 in attention_mask)
-                    else None
+                    attention_mask if (attention_mask is not None and 0 in attention_mask) else None
                 )
             else:
                 if attention_mask is None:
-                    attention_mask = torch.ones(
-                        input_shape, device = device
-                    )  # (bs, seq_length)
+                    attention_mask = torch.ones(input_shape, device = device)  # (bs, seq_length)
 
                 if (
                     self.config._attn_implementation == "sdpa"
@@ -946,9 +925,7 @@ class FastSentenceTransformer(FastModel):
             **kwargs,
         ):
             if (input_ids is None) ^ (inputs_embeds is not None):
-                raise ValueError(
-                    "You must specify exactly one of input_ids or inputs_embeds"
-                )
+                raise ValueError("You must specify exactly one of input_ids or inputs_embeds")
 
             embeddings = self.embeddings(input_ids, inputs_embeds, position_ids)
 
@@ -968,7 +945,11 @@ class FastSentenceTransformer(FastModel):
         modeling_distilbert.DistilBertModel.forward = forward
 
     @staticmethod
-    def _add_unsloth_tags(repo_id, token, tags = None):
+    def _add_unsloth_tags(
+        repo_id,
+        token,
+        tags = None,
+    ):
         """
         Add Unsloth and sentence-transformers tags to the Hugging Face Hub repository.
         """
@@ -1006,9 +987,7 @@ class FastSentenceTransformer(FastModel):
             # if tags exist but not right at start, use regex to append
             pattern = r"(^tags:\s*\n)"
             if re.search(pattern, content, re.MULTILINE):
-                content = re.sub(
-                    pattern, r"\1- unsloth\n", content, count = 1, flags = re.MULTILINE
-                )
+                content = re.sub(pattern, r"\1- unsloth\n", content, count = 1, flags = re.MULTILINE)
 
         # add branding badge and text
         branding = (
@@ -1044,13 +1023,7 @@ class FastSentenceTransformer(FastModel):
             return None
 
     @staticmethod
-    def _create_transformer_module(
-        model_name,
-        model,
-        tokenizer,
-        max_seq_length,
-        trust_remote_code,
-    ):
+    def _create_transformer_module(model_name, model, tokenizer, max_seq_length, trust_remote_code):
         """Helper to create and configure a Transformer module."""
         from sentence_transformers.models import Transformer
 
@@ -1122,9 +1095,7 @@ class FastSentenceTransformer(FastModel):
                 AutoProcessor.from_pretrained = return_existing_processor
                 AutoTokenizer.from_pretrained = return_existing_tokenizer
 
-                transformer_init_params = inspect.signature(
-                    Transformer.__init__
-                ).parameters
+                transformer_init_params = inspect.signature(Transformer.__init__).parameters
                 trust_remote_code_kwargs = {"trust_remote_code": trust_remote_code}
                 do_lower_case = getattr(tokenizer, "do_lower_case", False)
                 transformer_kwargs = {"max_seq_length": max_seq_length}
@@ -1132,20 +1103,14 @@ class FastSentenceTransformer(FastModel):
                     transformer_kwargs["do_lower_case"] = do_lower_case
                 if "model_kwargs" in transformer_init_params:
                     transformer_kwargs["model_kwargs"] = trust_remote_code_kwargs.copy()
-                    transformer_kwargs["config_kwargs"] = (
-                        trust_remote_code_kwargs.copy()
-                    )
+                    transformer_kwargs["config_kwargs"] = trust_remote_code_kwargs.copy()
                 else:
                     transformer_kwargs["model_args"] = trust_remote_code_kwargs.copy()
                     transformer_kwargs["config_args"] = trust_remote_code_kwargs.copy()
                 if "processor_kwargs" in transformer_init_params:
-                    transformer_kwargs["processor_kwargs"] = (
-                        trust_remote_code_kwargs.copy()
-                    )
+                    transformer_kwargs["processor_kwargs"] = trust_remote_code_kwargs.copy()
                 elif "tokenizer_args" in transformer_init_params:
-                    transformer_kwargs["tokenizer_args"] = (
-                        trust_remote_code_kwargs.copy()
-                    )
+                    transformer_kwargs["tokenizer_args"] = trust_remote_code_kwargs.copy()
 
                 # Initialize Transformer
                 transformer_module = Transformer(model_name, **transformer_kwargs)
@@ -1158,16 +1123,12 @@ class FastSentenceTransformer(FastModel):
         # On sentence-transformers >=5.4 `tokenizer` is a read-only property backed
         # by `self.processor` (already wired via the redirect above). On older
         # versions it's a regular attribute and the explicit assignment is required.
-        if not isinstance(
-            getattr(type(transformer_module), "tokenizer", None), property
-        ):
+        if not isinstance(getattr(type(transformer_module), "tokenizer", None), property):
             transformer_module.tokenizer = tokenizer
         transformer_module.do_lower_case = getattr(tokenizer, "do_lower_case", False)
 
         # sentence-transformers only passes along known keys to model.forward
-        preinit_model_forward_params = getattr(
-            transformer_module, "model_forward_params", set()
-        )
+        preinit_model_forward_params = getattr(transformer_module, "model_forward_params", set())
         model_forward_params = list(inspect.signature(model.forward).parameters)
         transformer_module.model_forward_params = set(model_forward_params) | {
             "input_ids",
@@ -1180,9 +1141,7 @@ class FastSentenceTransformer(FastModel):
 
         # determine max_seq_length if not provided
         if max_seq_length is None:
-            if hasattr(model, "config") and hasattr(
-                model.config, "max_position_embeddings"
-            ):
+            if hasattr(model, "config") and hasattr(model.config, "max_position_embeddings"):
                 max_seq_length = model.config.max_position_embeddings
             elif hasattr(tokenizer, "model_max_length"):
                 max_seq_length = tokenizer.model_max_length
@@ -1256,19 +1215,15 @@ class FastSentenceTransformer(FastModel):
 
             for module_config in modules_config:
                 class_ref = module_config["type"]
-                name = module_config.get(
-                    "name", str(module_config.get("idx", len(modules)))
-                )
+                name = module_config.get("name", str(module_config.get("idx", len(modules))))
 
                 if FastSentenceTransformer._is_transformer_module_ref(class_ref):
-                    transformer_module = (
-                        FastSentenceTransformer._create_transformer_module(
-                            model_name,
-                            model,
-                            tokenizer,
-                            max_seq_length,
-                            trust_remote_code,
-                        )
+                    transformer_module = FastSentenceTransformer._create_transformer_module(
+                        model_name,
+                        model,
+                        tokenizer,
+                        max_seq_length,
+                        trust_remote_code,
                     )
                     modules[name] = transformer_module
                 else:
@@ -1278,13 +1233,9 @@ class FastSentenceTransformer(FastModel):
                         load_path = os.path.join(model_name, module_path)
                     else:
                         try:
-                            load_path = load_dir_path(
-                                model_name, module_path, token = token
-                            )
+                            load_path = load_dir_path(model_name, module_path, token = token)
                         except Exception as e:
-                            print(
-                                f"Unsloth Warning: Could not download module {module_path}: {e}"
-                            )
+                            print(f"Unsloth Warning: Could not download module {module_path}: {e}")
                             continue
 
                     module_class = import_from_string(class_ref)
@@ -1292,9 +1243,7 @@ class FastSentenceTransformer(FastModel):
                         module = module_class.load(load_path)
                         modules[name] = module
                     except Exception as e:
-                        print(
-                            f"Unsloth Warning: Failed to load module {name} ({class_ref}): {e}"
-                        )
+                        print(f"Unsloth Warning: Failed to load module {name} ({class_ref}): {e}")
 
             return modules, False
 
@@ -1313,9 +1262,7 @@ class FastSentenceTransformer(FastModel):
         if pooling_mode == "mean":
             pooling_mode = FastSentenceTransformer._read_pooling_mode(model_name, token)
 
-        modules["1"] = Pooling(
-            word_embedding_dimension = hidden_size, pooling_mode = pooling_mode
-        )
+        modules["1"] = Pooling(word_embedding_dimension = hidden_size, pooling_mode = pooling_mode)
         modules["2"] = Normalize()
 
         return modules, True
@@ -1402,11 +1349,7 @@ class FastSentenceTransformer(FastModel):
         # This uses only pre-run information (batch size, grad accum, seq length).
         generic_scale = 1.0
         fast_scale = 1.0
-        if (
-            batch_size is not None
-            or grad_accum is not None
-            or max_seq_length is not None
-        ):
+        if batch_size is not None or grad_accum is not None or max_seq_length is not None:
             try:
                 bs = int(batch_size) if batch_size is not None else 2
                 ga = int(grad_accum) if grad_accum is not None else 4
@@ -1588,9 +1531,7 @@ class FastSentenceTransformer(FastModel):
         # NOTE: The old Unsloth path is BROKEN for encoder models with torch 2.9+ due to
         # conflicting @torch.compile and @torch.compiler.disable decorators.
         # Set UNSLOTH_COMPILE_DISABLE=1 to disable torch.compile and use the old path.
-        is_encoder_model = (
-            model_type.lower() in FastSentenceTransformer.ENCODER_MODEL_TYPES
-        )
+        is_encoder_model = model_type.lower() in FastSentenceTransformer.ENCODER_MODEL_TYPES
         use_fast_encoder = os.environ.get("UNSLOTH_COMPILE_DISABLE", "0") != "1"
         if use_fast_encoder and is_encoder_model:
             # torch.compile mode: "default" is safest for PEFT/LoRA training
@@ -1604,9 +1545,7 @@ class FastSentenceTransformer(FastModel):
                 else:
                     dtype = torch.float32
             elif dtype == torch.bfloat16 and not SUPPORTS_BFLOAT16:
-                print(
-                    "Unsloth: Device does not support bfloat16. Using float16 instead."
-                )
+                print("Unsloth: Device does not support bfloat16. Using float16 instead.")
                 dtype = torch.float16
 
             # Determine device
@@ -1657,9 +1596,7 @@ class FastSentenceTransformer(FastModel):
             # Handle gradient checkpointing - warn user it conflicts with torch.compile
             _use_gc = use_gradient_checkpointing
             if _use_gc and _use_gc != False:
-                print(
-                    "Unsloth Warning: Gradient checkpointing is incompatible with torch.compile."
-                )
+                print("Unsloth Warning: Gradient checkpointing is incompatible with torch.compile.")
                 print("Disabling torch.compile to enable gradient checkpointing.")
                 compile_mode = None  # Disable compilation
 
@@ -1708,17 +1645,11 @@ class FastSentenceTransformer(FastModel):
                     tokenizer.save_pretrained(save_directory)
                 FastSentenceTransformer._add_unsloth_branding(save_directory)
 
-            st_model.save_pretrained_merged = types.MethodType(
-                _save_pretrained_merged, st_model
-            )
+            st_model.save_pretrained_merged = types.MethodType(_save_pretrained_merged, st_model)
 
-            st_model.save_pretrained_torchao = types.MethodType(
-                _save_pretrained_torchao, st_model
-            )
+            st_model.save_pretrained_torchao = types.MethodType(_save_pretrained_torchao, st_model)
 
-            st_model.save_pretrained_gguf = types.MethodType(
-                _save_pretrained_gguf, st_model
-            )
+            st_model.save_pretrained_gguf = types.MethodType(_save_pretrained_gguf, st_model)
 
             st_model.push_to_hub_gguf = types.MethodType(_push_to_hub_gguf, st_model)
 
@@ -1742,23 +1673,17 @@ class FastSentenceTransformer(FastModel):
                     api.upload_folder(
                         folder_path = temp_dir,
                         repo_id = repo_id,
-                        commit_message = push_kwargs.get(
-                            "commit_message", "Upload model"
-                        ),
+                        commit_message = push_kwargs.get("commit_message", "Upload model"),
                     )
                 print(f"Unsloth: Pushed to https://huggingface.co/{repo_id}")
 
-            st_model.push_to_hub_merged = types.MethodType(
-                _push_to_hub_merged, st_model
-            )
+            st_model.push_to_hub_merged = types.MethodType(_push_to_hub_merged, st_model)
 
             return st_model
 
         # Warn if using 4-bit with encoder (slow due to dequantization overhead)
         if is_encoder_model and load_in_4bit:
-            print(
-                "Unsloth Warning: 4-bit quantization adds ~2.3x overhead for encoder models."
-            )
+            print("Unsloth Warning: 4-bit quantization adds ~2.3x overhead for encoder models.")
             print("Consider using load_in_16bit=True for better performance.")
 
         # check if the model supports add_pooling_layer
@@ -1796,9 +1721,7 @@ class FastSentenceTransformer(FastModel):
         # check if modules.json exists - if not, force 16-bit training
         # why? because i have to implement saving myself for these models, and i don't feel like adding dequantization
         # to the save_pretrained_merged for a model that really should be trained in 16-bit anyway
-        has_modules_json = (
-            FastSentenceTransformer._module_path(model_name, token) is not None
-        )
+        has_modules_json = FastSentenceTransformer._module_path(model_name, token) is not None
 
         if not has_modules_json and load_in_4bit:
             print(
@@ -1865,9 +1788,7 @@ class FastSentenceTransformer(FastModel):
             # check which adapter files exist before save_pretrained
             adapter_files = ["adapter_model.safetensors", "adapter_config.json"]
             existing_before = {
-                f
-                for f in adapter_files
-                if os.path.exists(os.path.join(save_directory, f))
+                f for f in adapter_files if os.path.exists(os.path.join(save_directory, f))
             }
 
             # sentence-transformers config and modules only get saved if we call save_pretrained
@@ -1884,9 +1805,7 @@ class FastSentenceTransformer(FastModel):
             tokenizer = kwargs.pop("tokenizer", self.tokenizer)
             if self.no_modules:
                 # fallback for non-sentence-transformers models
-                print(
-                    "Unsloth: No modules detected. Using standard merge_and_unload for saving..."
-                )
+                print("Unsloth: No modules detected. Using standard merge_and_unload for saving...")
                 safe_kwargs = kwargs.copy()
                 # filter out Unsloth-specific args that are not in huggingface's save_pretrained
                 unsloth_args = [
@@ -1912,17 +1831,11 @@ class FastSentenceTransformer(FastModel):
             except Exception as e:
                 print(f"Unsloth Warning: Failed to add branding to README: {e}")
 
-        st_model.save_pretrained_merged = types.MethodType(
-            _save_pretrained_merged, st_model
-        )
+        st_model.save_pretrained_merged = types.MethodType(_save_pretrained_merged, st_model)
 
-        st_model.save_pretrained_torchao = types.MethodType(
-            _save_pretrained_torchao, st_model
-        )
+        st_model.save_pretrained_torchao = types.MethodType(_save_pretrained_torchao, st_model)
 
-        st_model.save_pretrained_gguf = types.MethodType(
-            _save_pretrained_gguf, st_model
-        )
+        st_model.save_pretrained_gguf = types.MethodType(_save_pretrained_gguf, st_model)
 
         st_model.push_to_hub_gguf = types.MethodType(_push_to_hub_gguf, st_model)
 
@@ -1958,9 +1871,7 @@ class FastSentenceTransformer(FastModel):
                     repo_id = repo_id,
                     commit_message = commit_message,
                 )
-            print(
-                f"Unsloth: Successfully pushed merged model to https://huggingface.co/{repo_id}"
-            )
+            print(f"Unsloth: Successfully pushed merged model to https://huggingface.co/{repo_id}")
 
         st_model.push_to_hub_merged = types.MethodType(_push_to_hub_merged, st_model)
         return st_model
@@ -2008,8 +1919,7 @@ class FastSentenceTransformer(FastModel):
                 # Check if model is quantized (4-bit/8-bit)
                 is_quantized = (
                     getattr(inner_model, "is_quantized", False)
-                    or getattr(inner_model.config, "quantization_config", None)
-                    is not None
+                    or getattr(inner_model.config, "quantization_config", None) is not None
                 )
 
                 # Track if gradient checkpointing was actually enabled
@@ -2032,11 +1942,8 @@ class FastSentenceTransformer(FastModel):
                 # Prepare for k-bit training if quantized
                 if is_quantized:
                     from ._utils import prepare_model_for_kbit_training
-
                     _gc_for_kbit = (
-                        use_gradient_checkpointing
-                        if use_gradient_checkpointing
-                        else False
+                        use_gradient_checkpointing if use_gradient_checkpointing else False
                     )
                     try:
                         inner_model = prepare_model_for_kbit_training(
@@ -2091,7 +1998,6 @@ class FastSentenceTransformer(FastModel):
                 qat_scheme = kwargs.get("qat_scheme", None)
                 if qat_scheme is not None:
                     from ._utils import _prepare_model_for_qat
-
                     peft_model = _prepare_model_for_qat(peft_model, qat_scheme)
 
                 # Determine compile mode (only if not using gradient checkpointing)
@@ -2106,9 +2012,7 @@ class FastSentenceTransformer(FastModel):
                 # Re-assign the peft model back to the transformer module.
                 # On sentence-transformers >=5.4 `auto_model` is a read-only property
                 # backed by `self.model`, so write to the backing attribute there.
-                if isinstance(
-                    getattr(type(transformer_module), "auto_model", None), property
-                ):
+                if isinstance(getattr(type(transformer_module), "auto_model", None), property):
                     transformer_module.model = peft_model
                 else:
                     transformer_module.auto_model = peft_model
@@ -2120,8 +2024,8 @@ class FastSentenceTransformer(FastModel):
                 # torch.compile is deferred until training starts so we can check max_steps
                 if compile_mode is not None:
                     model._compile_mode = compile_mode
-                    model._compile_threshold = (
-                        FastSentenceTransformer._estimate_compile_threshold(model)
+                    model._compile_threshold = FastSentenceTransformer._estimate_compile_threshold(
+                        model
                     )
                     # Flag to indicate compile has not been applied yet
                     model._compile_pending = True
@@ -2131,9 +2035,7 @@ class FastSentenceTransformer(FastModel):
                 else:
                     model._compile_mode = None
                     model._compile_pending = False
-                    print(
-                        "Unsloth: torch.compile disabled (gradient checkpointing enabled)"
-                    )
+                    print("Unsloth: torch.compile disabled (gradient checkpointing enabled)")
 
                 return model
 
@@ -2163,9 +2065,7 @@ class FastSentenceTransformer(FastModel):
             # re-assign the peft model back to the transformer module.
             # On sentence-transformers >=5.4 `auto_model` is a read-only property
             # backed by `self.model`, so write to the backing attribute there.
-            if isinstance(
-                getattr(type(transformer_module), "auto_model", None), property
-            ):
+            if isinstance(getattr(type(transformer_module), "auto_model", None), property):
                 transformer_module.model = peft_model
             else:
                 transformer_module.auto_model = peft_model
@@ -2240,9 +2140,7 @@ def _patch_sentence_transformer_trainer():
             if max_seq_length is None:
                 tokenizer = getattr(model, "tokenizer", None)
                 max_seq_length = (
-                    getattr(tokenizer, "model_max_length", None)
-                    if tokenizer is not None
-                    else None
+                    getattr(tokenizer, "model_max_length", None) if tokenizer is not None else None
                 )
 
             threshold = FastSentenceTransformer._estimate_compile_threshold(
@@ -2254,9 +2152,7 @@ def _patch_sentence_transformer_trainer():
             model._compile_threshold = threshold
 
             if max_steps > 0 and max_steps >= threshold:
-                print(
-                    f"Unsloth: Auto-compiling model ({max_steps} steps >= {threshold} threshold)"
-                )
+                print(f"Unsloth: Auto-compiling model ({max_steps} steps >= {threshold} threshold)")
                 FastSentenceTransformer._apply_torch_compile(model, mode = compile_mode)
                 model._compile_pending = False
             elif max_steps > 0:
@@ -2291,9 +2187,7 @@ def _patch_st_trainer_load_from_checkpoint():
         from sentence_transformers import SentenceTransformerTrainer
     except ImportError:
         return
-    if getattr(
-        SentenceTransformerTrainer, "_unsloth_load_from_checkpoint_patched", False
-    ):
+    if getattr(SentenceTransformerTrainer, "_unsloth_load_from_checkpoint_patched", False):
         return
     if not hasattr(SentenceTransformerTrainer, "_load_from_checkpoint"):
         return
@@ -2333,9 +2227,7 @@ def _patch_st_trainer_load_from_checkpoint():
             adapter_name = inner.active_adapters()
         if isinstance(adapter_name, (list, tuple, set)):
             if len(adapter_name) != 1:
-                raise RuntimeError(
-                    "Unsloth: Cannot resume multiple active PEFT adapters."
-                )
+                raise RuntimeError("Unsloth: Cannot resume multiple active PEFT adapters.")
             adapter_name = next(iter(adapter_name))
         adapter_name = adapter_name or "default"
         if adapter_name not in getattr(inner, "peft_config", {}):
@@ -2379,17 +2271,13 @@ def _patch_st_trainer_load_from_checkpoint():
             if saved_type and not saved_type.endswith(f".{module_cls.__name__}"):
                 raise RuntimeError(f"Unsloth: Checkpoint module {idx} type mismatch.")
             module_path = entry.get("path")
-            module_dir = os.path.abspath(
-                os.path.join(root, os.fspath(module_path or ""))
-            )
+            module_dir = os.path.abspath(os.path.join(root, os.fspath(module_path or "")))
             try:
                 inside_root = os.path.commonpath([root, module_dir]) == root
             except ValueError:
                 inside_root = False
             if not module_path or not inside_root or not os.path.isdir(module_dir):
-                raise RuntimeError(
-                    f"Unsloth: Bad checkpoint module path for index {idx}."
-                )
+                raise RuntimeError(f"Unsloth: Bad checkpoint module path for index {idx}.")
             if not hasattr(module_cls, "load"):
                 raise RuntimeError(f"Unsloth: Module {idx} cannot be reloaded.")
             fresh = module_cls.load(module_dir)
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 6c4842596f..b308a6f1da 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -22,7 +22,6 @@ from transformers import (
 
 try:
     from transformers import AutoModelForImageTextToText
-
     AutoModelForVision2Seq = AutoModelForImageTextToText
 except:
     from transformers import AutoModelForVision2Seq
@@ -120,9 +119,7 @@ def _infer_device_map_from_loaded_model(model):
             for pname, param in module.named_parameters(remove_duplicate = False):
                 if "." not in pname:
                     full = f"{prefix}.{pname}" if prefix else pname
-                    if not any(
-                        full == k or full.startswith(k + ".") for k in device_map
-                    ):
+                    if not any(full == k or full.startswith(k + ".") for k in device_map):
                         device_map[full] = param.device
 
     _assign(model, "")
@@ -195,9 +192,7 @@ def _attach_bnb_multidevice_hooks(
         try:
             # CUDA -> int index, non-CUDA -> type string ("cpu", "meta").
             device_map_int = {
-                k: (v.index if v.type == "cuda" else v.type)
-                if isinstance(v, torch.device)
-                else v
+                k: (v.index if v.type == "cuda" else v.type) if isinstance(v, torch.device) else v
                 for k, v in inferred_map.items()
             }
 
@@ -257,7 +252,6 @@ from transformers import GenerationConfig, CompileConfig, AutoConfig
 
 try:
     from transformers import PreTrainedConfig
-
     PretrainedConfig = PreTrainedConfig
 except:
     from transformers import PretrainedConfig
@@ -277,11 +271,7 @@ except:
     torch_compiler_set_stance = None
 
 
-def unsloth_base_fast_generate(
-    self,
-    *args,
-    **kwargs,
-):
+def unsloth_base_fast_generate(self, *args, **kwargs):
     if len(args) != 0:
         input_ids = args[0]
     elif "input_ids" in kwargs:
@@ -305,9 +295,7 @@ def unsloth_base_fast_generate(
     FastBaseModel.for_inference(self)
     dtype = _get_dtype(dtype_from_config(self.config))
     # Handle full float32 cases as config.dtype == torch.float32!
-    do_bfloat16_mixed_precision = (
-        os.environ.get("UNSLOTH_BFLOAT16_MIXED_PRECISION", "0") == "1"
-    )
+    do_bfloat16_mixed_precision = os.environ.get("UNSLOTH_BFLOAT16_MIXED_PRECISION", "0") == "1"
     if do_bfloat16_mixed_precision:
         dtype = torch.bfloat16
 
@@ -388,9 +376,7 @@ def unsloth_base_fast_generate(
     # Fix generation_config
     # Use hybrid if sliding window seen, otherwise try static
     cache_implementation = getattr(self.config, "cache_implementation", None)
-    if getattr(
-        self, "_supports_static_cache", getattr(self, "_can_compile_fullgraph", True)
-    ):
+    if getattr(self, "_supports_static_cache", getattr(self, "_can_compile_fullgraph", True)):
         if os.environ.get("UNSLOTH_DISABLE_STATIC_GENERATION", "0") == "0":
             cache_implementation = "static"
         elif Version(transformers_version) < Version("4.56.0.dev0"):
@@ -401,9 +387,7 @@ def unsloth_base_fast_generate(
     else:
         cache_implementation = None
     if cache_implementation is not None:
-        swa = getattr(
-            getattr(self.config, "text_config", self.config), "sliding_window", None
-        )
+        swa = getattr(getattr(self.config, "text_config", self.config), "sliding_window", None)
         if (swa == 0 or type(swa) is not int) and (
             getattr(self, "_can_compile_fullgraph", True) is True
         ):
@@ -462,9 +446,7 @@ def unsloth_base_fast_generate(
     return output
 
 
-def _construct_vlm_processor_fallback(
-    tokenizer_name, model_type, token, trust_remote_code
-):
+def _construct_vlm_processor_fallback(tokenizer_name, model_type, token, trust_remote_code):
     """Construct a VLM processor manually when AutoProcessor.from_pretrained fails.
 
     Some VLMs (e.g., LFM2.5-VL) have tokenizer_class entries that AutoTokenizer
@@ -493,9 +475,7 @@ def _construct_vlm_processor_fallback(
         try:
             from huggingface_hub import hf_hub_download
 
-            config_path = hf_hub_download(
-                tokenizer_name, "tokenizer_config.json", token = token
-            )
+            config_path = hf_hub_download(tokenizer_name, "tokenizer_config.json", token = token)
             with open(config_path, "r", encoding = "utf-8") as f:
                 tok_config = json.load(f)
             # Set model-specific special tokens and their IDs
@@ -532,7 +512,6 @@ def _construct_vlm_processor_fallback(
 
         if proc_class_name is not None:
             import transformers
-
             proc_class = getattr(transformers, proc_class_name, None)
             if proc_class is not None:
                 processor = proc_class(image_processor = image_processor, tokenizer = tok)
@@ -663,7 +642,9 @@ class FastBaseModel:
                 gpu_stats.name + ". " if gpu_stats.name != "" else "NVIDIA GPU Device. "
             )
             gpu_version = torch.version.cuda
-            gpu_stats_snippet = f"CUDA: {gpu_stats.major}.{gpu_stats.minor}. CUDA Toolkit: {gpu_version}."
+            gpu_stats_snippet = (
+                f"CUDA: {gpu_stats.major}.{gpu_stats.minor}. CUDA Toolkit: {gpu_version}."
+            )
             try:
                 vllm_version = f" vLLM: {importlib_version('vllm')}."
             except:
@@ -679,9 +660,7 @@ class FastBaseModel:
                 vllm_version = ""
         elif DEVICE_TYPE == "xpu":
             gpu_stats = torch.xpu.get_device_properties(0)
-            gpu_stats_name = (
-                gpu_stats.name + ". " if gpu_stats.name != "" else "Intel XPU Device. "
-            )
+            gpu_stats_name = gpu_stats.name + ". " if gpu_stats.name != "" else "Intel XPU Device. "
             gpu_version = torch.version.xpu
             gpu_stats_snippet = f"Intel Toolkit: {gpu_version}."
             # [TODO] After adding vLLM support for XPU, change this
@@ -728,9 +707,7 @@ class FastBaseModel:
             if dtype == torch.float16:
                 dtype = torch.bfloat16
         elif dtype == torch.bfloat16 and not SUPPORTS_BFLOAT16:
-            logger.warning_once(
-                "Device does not support bfloat16. Will change to float16."
-            )
+            logger.warning_once("Device does not support bfloat16. Will change to float16.")
             dtype = torch.float16
         assert dtype in (torch.float16, torch.bfloat16, torch.float32)
 
@@ -755,11 +732,8 @@ class FastBaseModel:
             # Allow custom dtypes on all runs
             allow_all_runs = checker == "all"
             # Allow only on float16 datatypes
-            allow_float16_runs = (
-                checker == "float16" or checker == "torch.float16"
-            ) and (
-                dtype == torch.float16
-                or os.environ.get("UNSLOTH_FORCE_FLOAT32", "0") == "1"
+            allow_float16_runs = (checker == "float16" or checker == "torch.float16") and (
+                dtype == torch.float16 or os.environ.get("UNSLOTH_FORCE_FLOAT32", "0") == "1"
             )
             if allow_all_runs or allow_float16_runs:
                 if eval(_dtype) is not None:
@@ -831,9 +805,7 @@ class FastBaseModel:
         elif load_in_16bit:
             bnb_config = None
         elif not load_in_4bit and not load_in_8bit and not full_finetuning:
-            print(
-                "Unsloth: QLoRA and full finetuning all not selected. Switching to 16bit LoRA."
-            )
+            print("Unsloth: QLoRA and full finetuning all not selected. Switching to 16bit LoRA.")
 
         if full_finetuning:
             os.environ["UNSLOTH_ENABLE_FULL_FINETUNING"] = "1"
@@ -864,10 +836,7 @@ class FastBaseModel:
         # Cannot be None, since HF now checks for the config
         if load_in_4bit or load_in_8bit:
             # Ignore load_in_4bit / load_in_8bit for MXFP4 - best to get config file
-            if (
-                "gpt-oss-20b" in model_name.lower()
-                or "gpt-oss-120b" in model_name.lower()
-            ):
+            if "gpt-oss-20b" in model_name.lower() or "gpt-oss-120b" in model_name.lower():
                 pass
             else:
                 if user_quantization_config is None:
@@ -904,10 +873,7 @@ class FastBaseModel:
                     pass
                 else:
                     # We cannot dequantize since gpt-oss-20b MXFP4 will now be gpt-oss-20b-BF16
-                    if (
-                        load_in_16bit
-                        and "dequantize" in inspect.signature(quantizer).parameters
-                    ):
+                    if load_in_16bit and "dequantize" in inspect.signature(quantizer).parameters:
                         quantizer_kwargs["dequantize"] = True
                     try:
                         # Sometimes this fails so we wrap it in a try except
@@ -976,9 +942,7 @@ class FastBaseModel:
                 model.fast_generate = make_fast_generate_wrapper(model.generate)
                 model.fast_generate_batches = error_out_no_vllm
             if offload_embedding:
-                if bool(
-                    os.environ.get("WSL_DISTRO_NAME") or os.environ.get("WSL_INTEROP")
-                ):
+                if bool(os.environ.get("WSL_DISTRO_NAME") or os.environ.get("WSL_INTEROP")):
                     # WSL doesn't work with offloaded embeddings
                     pass
                 elif os.name == "nt":
@@ -1026,9 +990,7 @@ class FastBaseModel:
             model_config.model_name = model_name
 
             if fast_inference:
-                fast_inference, model_name = fast_inference_setup(
-                    model_name, model_config
-                )
+                fast_inference, model_name = fast_inference_setup(model_name, model_config)
 
             fp8_mode = None
             if load_in_fp8 != False:
@@ -1081,9 +1043,7 @@ class FastBaseModel:
             model.vllm_engine = llm
             llm.shared_weights = True
             model.fast_generate = model.vllm_engine.generate
-            model.fast_generate_batches = functools.partial(
-                generate_batches, model.vllm_engine
-            )
+            model.fast_generate_batches = functools.partial(generate_batches, model.vllm_engine)
 
         raise_handler.remove()
 
@@ -1118,7 +1078,6 @@ class FastBaseModel:
         # Fix _Unsloth_Patched_ prefix in local config files from old saves (issue #4085)
         if os.path.isdir(tokenizer_name):
             import json as _json
-
             for _cfg_name in (
                 "processor_config.json",
                 "preprocessor_config.json",
@@ -1129,9 +1088,7 @@ class FastBaseModel:
                     try:
                         with open(_cfg_path, "r", encoding = "utf-8") as _f:
                             _cfg = _json.load(_f)
-                        if _cfg.get("processor_class", "").startswith(
-                            "_Unsloth_Patched_"
-                        ):
+                        if _cfg.get("processor_class", "").startswith("_Unsloth_Patched_"):
                             _cfg["processor_class"] = _cfg["processor_class"][
                                 len("_Unsloth_Patched_") :
                             ]
@@ -1175,9 +1132,7 @@ class FastBaseModel:
         # instead of returning a full VLM processor (issue #4085),
         # try constructing the processor manually from separate components.
         _processor_is_degraded = (
-            is_vlm
-            and tokenizer is not None
-            and not hasattr(tokenizer, "image_processor")
+            is_vlm and tokenizer is not None and not hasattr(tokenizer, "image_processor")
         )
         if (tokenizer is None or _processor_is_degraded) and is_vlm:
             _fallback = _construct_vlm_processor_fallback(
@@ -1190,7 +1145,6 @@ class FastBaseModel:
                 tokenizer = _fallback
             if tokenizer is None:
                 import sys
-
                 print(
                     f"Unsloth: Warning - VLM processor fallback returned None for model_type={model_type_arch}",
                     file = sys.stderr,
@@ -1261,7 +1215,6 @@ class FastBaseModel:
             # Last resort: try loading tokenizer via AutoTokenizer, then PreTrainedTokenizerFast
             try:
                 from transformers import AutoTokenizer as _AutoTokenizer
-
                 tokenizer = _AutoTokenizer.from_pretrained(
                     tokenizer_name,
                     padding_side = "left",
@@ -1271,7 +1224,6 @@ class FastBaseModel:
             except Exception:
                 try:
                     from transformers import PreTrainedTokenizerFast
-
                     tokenizer = PreTrainedTokenizerFast.from_pretrained(
                         tokenizer_name,
                         padding_side = "left",
@@ -1367,9 +1319,7 @@ class FastBaseModel:
         **kwargs,
     ):
         if os.environ.get("UNSLOTH_ENABLE_FULL_FINETUNING", "0") == "1":
-            print(
-                "Unsloth: Full finetuning is enabled, so .get_peft_model has no effect"
-            )
+            print("Unsloth: Full finetuning is enabled, so .get_peft_model has no effect")
             return model
         transformers_set_seed(random_state)
 
@@ -1379,9 +1329,7 @@ class FastBaseModel:
             raise TypeError(f"Unsloth: Rank of {str(r)} must be larger than 0.")
 
         if isinstance(model, PeftModelForCausalLM):
-            raise RuntimeError(
-                "Unsloth: You already added LoRA adapters to your model!"
-            )
+            raise RuntimeError("Unsloth: You already added LoRA adapters to your model!")
 
         if target_modules == "all-linear":
             finetune_vision_layers = True
@@ -1397,20 +1345,13 @@ class FastBaseModel:
                 finetune_mlp_modules = finetune_mlp_modules,
             )
         else:
-            assert type(target_modules) in (
-                list,
-                tuple,
-                str,
-            )
+            assert type(target_modules) in (list, tuple, str)
 
         if hasattr(model, "vllm_engine"):
             if (
                 hasattr(model.vllm_engine, "llm_engine")
                 and hasattr(model.vllm_engine.llm_engine, "vllm_config")
-                and getattr(
-                    model.vllm_engine.llm_engine.vllm_config, "lora_config", None
-                )
-                is None
+                and getattr(model.vllm_engine.llm_engine.vllm_config, "lora_config", None) is None
             ):
                 # If vLLM is being used but lora is not enabled, throw an error
                 # Ref https://github.com/vllm-project/vllm/blob/51ba839555a5d122eadd91e9c16463ac288f5fa1/vllm/v1/engine/processor.py#L148-L151
@@ -1575,10 +1516,7 @@ class FastBaseModel:
             pass
         else:
             float32_mixed_precision = True
-            if (
-                _get_dtype(dtype_from_config(model.config)) == torch.bfloat16
-                and full_finetuning
-            ):
+            if _get_dtype(dtype_from_config(model.config)) == torch.bfloat16 and full_finetuning:
                 # Use bfloat16 precision for full finetuning
                 float32_mixed_precision = False
 
@@ -1674,13 +1612,8 @@ class FastBaseModel:
         # Only do this if tokenizer is defined since eos_token == pad_token sometimes!
         pad_token_id = getattr(tokenizer, "pad_token_id", None)
         lm_head = getattr(model, "lm_head", None)
-        lm_head_weight = (
-            getattr(lm_head, "weight", None) if lm_head is not None else None
-        )
-        if (
-            tokenizer is not None
-            and getattr(tokenizer, "eos_token_id", None) != pad_token_id
-        ):
+        lm_head_weight = getattr(lm_head, "weight", None) if lm_head is not None else None
+        if tokenizer is not None and getattr(tokenizer, "eos_token_id", None) != pad_token_id:
             with torch.no_grad():
                 for name, module in model.named_modules():
                     if type(module) is torch.nn.Embedding:
@@ -1695,8 +1628,7 @@ class FastBaseModel:
                                 # Skip if tied to lm_head
                                 if (
                                     lm_head_weight is not None
-                                    and module.weight.data_ptr()
-                                    == lm_head_weight.data_ptr()
+                                    and module.weight.data_ptr() == lm_head_weight.data_ptr()
                                 ):
                                     continue
                                 module.weight[module.padding_idx] = 0
diff --git a/unsloth/optimizers/q_galore_adamw.py b/unsloth/optimizers/q_galore_adamw.py
index 6cd0a4a846..1f4219d69a 100644
--- a/unsloth/optimizers/q_galore_adamw.py
+++ b/unsloth/optimizers/q_galore_adamw.py
@@ -31,7 +31,6 @@ __all__ = ["QGaLoreAdamW8bit", "install_weight_quant_hooks"]
 try:
     import bitsandbytes.functional as bnb_F
     from bitsandbytes.optim.optimizer import Optimizer2State
-
     _HAS_BNB = True
 except ImportError:
     _HAS_BNB = False
@@ -42,8 +41,7 @@ except ImportError:
 def _require_bnb():
     if not _HAS_BNB:
         raise ImportError(
-            "Unsloth: Q-GaLore requires bitsandbytes. "
-            "Install it with: pip install bitsandbytes"
+            "Unsloth: Q-GaLore requires bitsandbytes. Install it with: pip install bitsandbytes"
         )
 
 
@@ -178,9 +176,7 @@ class QGaLoreAdamW8bit(Optimizer2State):
                     # Save current weight; replace p.data with zeros so
                     # the 8-bit update writes the pure weight delta.
                     p._saved_data = p.data.clone()
-                    p.data = torch.zeros_like(
-                        grad, dtype = p.data.dtype, device = p.data.device
-                    )
+                    p.data = torch.zeros_like(grad, dtype = p.data.dtype, device = p.data.device)
                     p.grad = grad
 
                 # --- 8-bit Adam update ---
@@ -295,9 +291,7 @@ def install_weight_quant_hooks(model: torch.nn.Module) -> list:
     """
     handles = []
     for module in model.modules():
-        has_quant_param = any(
-            hasattr(p, "_q_scales") for p in module.parameters(recurse = False)
-        )
+        has_quant_param = any(hasattr(p, "_q_scales") for p in module.parameters(recurse = False))
         if has_quant_param:
             h = module.register_forward_pre_hook(_weight_quant_pre_hook)
             handles.append(h)
@@ -366,9 +360,7 @@ def make_q_galore_param_groups(
     Returns:
         List of two param group dicts: ``[galore_group, non_galore_group]``.
     """
-    targets = (
-        set(target_modules) if target_modules is not None else _DEFAULT_GALORE_TARGETS
-    )
+    targets = set(target_modules) if target_modules is not None else _DEFAULT_GALORE_TARGETS
 
     galore_params = []
     non_galore_params = []
diff --git a/unsloth/optimizers/q_galore_projector.py b/unsloth/optimizers/q_galore_projector.py
index cabd228b92..809e15512c 100644
--- a/unsloth/optimizers/q_galore_projector.py
+++ b/unsloth/optimizers/q_galore_projector.py
@@ -191,11 +191,7 @@ class GaLoreProjector:
     # ------------------------------------------------------------------
 
     @staticmethod
-    def _compute_orthogonal(
-        weights: torch.Tensor,
-        rank: int,
-        side: str,
-    ) -> torch.Tensor:
+    def _compute_orthogonal(weights: torch.Tensor, rank: int, side: str) -> torch.Tensor:
         """Compute the top-``rank`` orthogonal matrix via truncated SVD.
 
         Args:
@@ -233,11 +229,7 @@ class GaLoreProjector:
     # Adaptive scheduling
     # ------------------------------------------------------------------
 
-    def _update_adaptive_schedule(
-        self,
-        float_ortho: torch.Tensor,
-        side: str,
-    ) -> None:
+    def _update_adaptive_schedule(self, float_ortho: torch.Tensor, side: str) -> None:
         """Track subspace stability and increase ``update_proj_gap`` if stable."""
         self.svd_count += 1
 
@@ -329,10 +321,7 @@ def _quantize(
 
 @torch.no_grad()
 def _dequantize(
-    w: torch.Tensor,
-    scales: torch.Tensor,
-    zeros: torch.Tensor,
-    original_shape: tuple,
+    w: torch.Tensor, scales: torch.Tensor, zeros: torch.Tensor, original_shape: tuple
 ) -> torch.Tensor:
     """Dequantize from uint8 back to float."""
     # Infer group size: scales has shape (n_groups, 1), so n_groups = scales.shape[0]
diff --git a/unsloth/registry/__init__.py b/unsloth/registry/__init__.py
index 52e6f52431..dede85329f 100644
--- a/unsloth/registry/__init__.py
+++ b/unsloth/registry/__init__.py
@@ -45,23 +45,15 @@ def search_models(
 
     model_infos = MODEL_REGISTRY.values()
     if org:
-        model_infos = [
-            model_info for model_info in model_infos if model_info.org == org
-        ]
+        model_infos = [model_info for model_info in model_infos if model_info.org == org]
     if base_name:
         model_infos = [
-            model_info
-            for model_info in model_infos
-            if model_info.base_name == base_name
+            model_info for model_info in model_infos if model_info.base_name == base_name
         ]
     if version:
-        model_infos = [
-            model_info for model_info in model_infos if model_info.version == version
-        ]
+        model_infos = [model_info for model_info in model_infos if model_info.version == version]
     if size:
-        model_infos = [
-            model_info for model_info in model_infos if model_info.size == size
-        ]
+        model_infos = [model_info for model_info in model_infos if model_info.size == size]
     if quant_types:
         model_infos = [
             model_info
@@ -70,9 +62,7 @@ def search_models(
         ]
     if search_pattern:
         model_infos = [
-            model_info
-            for model_info in model_infos
-            if search_pattern in model_info.model_path
+            model_info for model_info in model_infos if search_pattern in model_info.model_path
         ]
 
     return model_infos
diff --git a/unsloth/registry/_deepseek.py b/unsloth/registry/_deepseek.py
index 4bbc852cd7..e29190f0f2 100644
--- a/unsloth/registry/_deepseek.py
+++ b/unsloth/registry/_deepseek.py
@@ -12,9 +12,7 @@ class DeepseekV3ModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-V{version}"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 class DeepseekR1ModelInfo(ModelInfo):
@@ -23,9 +21,7 @@ class DeepseekR1ModelInfo(ModelInfo):
         key = f"{base_name}-{version}" if version else base_name
         if size:
             key = f"{key}-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 # Deepseek V3 Model Meta
@@ -138,9 +134,7 @@ def register_deepseek_r1_distill_llama_models(include_original_model: bool = Fal
     global _IS_DEEPSEEK_R1_DISTILL_LLAMA_REGISTERED
     if _IS_DEEPSEEK_R1_DISTILL_LLAMA_REGISTERED:
         return
-    _register_models(
-        DeepseekR1DistillLlamaMeta, include_original_model = include_original_model
-    )
+    _register_models(DeepseekR1DistillLlamaMeta, include_original_model = include_original_model)
     _IS_DEEPSEEK_R1_DISTILL_LLAMA_REGISTERED = True
 
 
@@ -148,9 +142,7 @@ def register_deepseek_r1_distill_qwen_models(include_original_model: bool = Fals
     global _IS_DEEPSEEK_R1_DISTILL_QWEN_REGISTERED
     if _IS_DEEPSEEK_R1_DISTILL_QWEN_REGISTERED:
         return
-    _register_models(
-        DeepseekR1DistillQwenMeta, include_original_model = include_original_model
-    )
+    _register_models(DeepseekR1DistillQwenMeta, include_original_model = include_original_model)
     _IS_DEEPSEEK_R1_DISTILL_QWEN_REGISTERED = True
 
 
@@ -159,21 +151,15 @@ def register_deepseek_models(include_original_model: bool = False):
     register_deepseek_v3_0324_models(include_original_model = include_original_model)
     register_deepseek_r1_models(include_original_model = include_original_model)
     register_deepseek_r1_zero_models(include_original_model = include_original_model)
-    register_deepseek_r1_distill_llama_models(
-        include_original_model = include_original_model
-    )
-    register_deepseek_r1_distill_qwen_models(
-        include_original_model = include_original_model
-    )
+    register_deepseek_r1_distill_llama_models(include_original_model = include_original_model)
+    register_deepseek_r1_distill_qwen_models(include_original_model = include_original_model)
 
 
 def _list_deepseek_r1_distill_models():
     from unsloth.utils.hf_hub import ModelInfo as HfModelInfo
     from unsloth.utils.hf_hub import list_models
 
-    models: list[HfModelInfo] = list_models(
-        author = "unsloth", search = "Distill", limit = 1000
-    )
+    models: list[HfModelInfo] = list_models(author = "unsloth", search = "Distill", limit = 1000)
     distill_models = []
     for model in models:
         model_id = model.id
diff --git a/unsloth/registry/_gemma.py b/unsloth/registry/_gemma.py
index c338128bc6..8b43dc3566 100644
--- a/unsloth/registry/_gemma.py
+++ b/unsloth/registry/_gemma.py
@@ -8,9 +8,7 @@ class GemmaModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{version}-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 # Gemma3 Base Model Meta
diff --git a/unsloth/registry/_llama.py b/unsloth/registry/_llama.py
index f5f82372bf..9a699a1939 100644
--- a/unsloth/registry/_llama.py
+++ b/unsloth/registry/_llama.py
@@ -9,18 +9,14 @@ class LlamaModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{version}-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 class LlamaVisionModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{version}-{size}B-Vision"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 # Llama 3.1
@@ -88,9 +84,7 @@ def register_llama_3_2_models(include_original_model: bool = False):
     if _IS_LLAMA_3_2_REGISTERED:
         return
     _register_models(LlamaMeta_3_2_Base, include_original_model = include_original_model)
-    _register_models(
-        LlamaMeta_3_2_Instruct, include_original_model = include_original_model
-    )
+    _register_models(LlamaMeta_3_2_Instruct, include_original_model = include_original_model)
     _IS_LLAMA_3_2_REGISTERED = True
 
 
@@ -98,9 +92,7 @@ def register_llama_3_2_vision_models(include_original_model: bool = False):
     global _IS_LLAMA_3_2_VISION_REGISTERED
     if _IS_LLAMA_3_2_VISION_REGISTERED:
         return
-    _register_models(
-        LlamaMeta_3_2_Vision, include_original_model = include_original_model
-    )
+    _register_models(LlamaMeta_3_2_Vision, include_original_model = include_original_model)
     _IS_LLAMA_3_2_VISION_REGISTERED = True
 
 
diff --git a/unsloth/registry/_mistral.py b/unsloth/registry/_mistral.py
index 173d6cfdef..eec098d2a4 100644
--- a/unsloth/registry/_mistral.py
+++ b/unsloth/registry/_mistral.py
@@ -53,18 +53,10 @@ def register_mistral_small_models(include_original_model: bool = False):
     global _IS_MISTRAL_SMALL_REGISTERED
     if _IS_MISTRAL_SMALL_REGISTERED:
         return
-    _register_models(
-        MistralSmall_2503_Base_Meta, include_original_model = include_original_model
-    )
-    _register_models(
-        MistralSmall_2503_Instruct_Meta, include_original_model = include_original_model
-    )
-    _register_models(
-        MistralSmall_2501_Base_Meta, include_original_model = include_original_model
-    )
-    _register_models(
-        MistralSmall_2501_Instruct_Meta, include_original_model = include_original_model
-    )
+    _register_models(MistralSmall_2503_Base_Meta, include_original_model = include_original_model)
+    _register_models(MistralSmall_2503_Instruct_Meta, include_original_model = include_original_model)
+    _register_models(MistralSmall_2501_Base_Meta, include_original_model = include_original_model)
+    _register_models(MistralSmall_2501_Instruct_Meta, include_original_model = include_original_model)
 
     _IS_MISTRAL_SMALL_REGISTERED = True
 
diff --git a/unsloth/registry/_phi.py b/unsloth/registry/_phi.py
index a6f773c48e..17d8f40a90 100644
--- a/unsloth/registry/_phi.py
+++ b/unsloth/registry/_phi.py
@@ -8,9 +8,7 @@ class PhiModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{version}"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 # Phi Model Meta
diff --git a/unsloth/registry/_qwen.py b/unsloth/registry/_qwen.py
index f852cb8762..bc84f90159 100644
--- a/unsloth/registry/_qwen.py
+++ b/unsloth/registry/_qwen.py
@@ -9,36 +9,28 @@ class QwenModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}{version}-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 class QwenVLModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}{version}-VL-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 class QwenQwQModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{size}B"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 class QwenQVQPreviewModelInfo(ModelInfo):
     @classmethod
     def construct_model_name(cls, base_name, version, size, quant_type, instruct_tag):
         key = f"{base_name}-{size}B-Preview"
-        return super().construct_model_name(
-            base_name, version, size, quant_type, instruct_tag, key
-        )
+        return super().construct_model_name(base_name, version, size, quant_type, instruct_tag, key)
 
 
 # Qwen2.5 Model Meta
diff --git a/unsloth/registry/registry.py b/unsloth/registry/registry.py
index 945301420a..009223088c 100644
--- a/unsloth/registry/registry.py
+++ b/unsloth/registry/registry.py
@@ -33,7 +33,9 @@ class ModelInfo:
     base_name: str
     version: str
     size: int
-    name: str = None  # full model name, constructed from base_name, version, and size unless provided
+    name: str = (
+        None  # full model name, constructed from base_name, version, and size unless provided
+    )
     is_multimodal: bool = False
     instruct_tag: str = None
     quant_type: QuantType = None
@@ -62,16 +64,20 @@ class ModelInfo:
 
     @classmethod
     def construct_model_name(
-        cls, base_name, version, size, quant_type, instruct_tag, key = ""
+        cls,
+        base_name,
+        version,
+        size,
+        quant_type,
+        instruct_tag,
+        key = "",
     ):
         key = cls.append_instruct_tag(key, instruct_tag)
         key = cls.append_quant_type(key, quant_type)
         return key
 
     @property
-    def model_path(
-        self,
-    ) -> str:
+    def model_path(self) -> str:
         return f"{self.org}/{self.name}"
 
 
@@ -83,9 +89,7 @@ class ModelMeta:
     model_info_cls: type[ModelInfo]
     model_sizes: list[str] = field(default_factory = list)
     instruct_tags: list[str] = field(default_factory = list)
-    quant_types: list[QuantType] | dict[str, list[QuantType]] = field(
-        default_factory = list
-    )
+    quant_types: list[QuantType] | dict[str, list[QuantType]] = field(default_factory = list)
     is_multimodal: bool = False
 
 
@@ -113,9 +117,7 @@ def register_model(
     key = f"{org}/{name}"
 
     if key in MODEL_REGISTRY:
-        raise ValueError(
-            f"Model {key} already registered, current keys: {MODEL_REGISTRY.keys()}"
-        )
+        raise ValueError(f"Model {key} already registered, current keys: {MODEL_REGISTRY.keys()}")
 
     MODEL_REGISTRY[key] = model_info_cls(
         org = org,
diff --git a/unsloth/save.py b/unsloth/save.py
index 3628c468e3..d6f69e6a6c 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -30,7 +30,6 @@ try:
     from unsloth_zoo.llama_cpp import LLAMA_CPP_DEFAULT_DIR, IS_WINDOWS
 except ImportError:
     import sys
-
     IS_WINDOWS = sys.platform == "win32"
     LLAMA_CPP_DEFAULT_DIR = "llama.cpp"
 from bitsandbytes.nn import Linear4bit as Bnb_Linear4bit
@@ -218,28 +217,20 @@ def _quantize_q2_k_l(
             error_details += f"\nSubprocess stdout:\n{e.stdout}"
         if hasattr(e, "stderr") and e.stderr:
             error_details += f"\nSubprocess stderr:\n{e.stderr}"
-        raise RuntimeError(
-            f"Failed to quantize {input_gguf} to q2_k_l: {e}{error_details}"
-        )
+        raise RuntimeError(f"Failed to quantize {input_gguf} to q2_k_l: {e}{error_details}")
 
     output_path = Path(output_gguf)
     if not output_path.exists():
-        raise RuntimeError(
-            f"Quantization failed - output file {output_gguf} not created"
-        )
+        raise RuntimeError(f"Quantization failed - output file {output_gguf} not created")
 
     if print_output:
         file_size_bytes = output_path.stat().st_size
         file_size_gb = file_size_bytes / (1024**3)
-        print(
-            f"Unsloth: Successfully quantized to {output_gguf} (size: {file_size_gb:.2f}GB)"
-        )
+        print(f"Unsloth: Successfully quantized to {output_gguf} (size: {file_size_gb:.2f}GB)")
     return str(output_gguf)
 
 
-def check_if_sentencepiece_model(
-    model, temporary_location = "_unsloth_sentencepiece_temp"
-):
+def check_if_sentencepiece_model(model, temporary_location = "_unsloth_sentencepiece_temp"):
     if not hasattr(model, "_saved_temp_tokenizer"):
         return False
 
@@ -298,9 +289,7 @@ def _preserve_sentencepiece_tokenizer_assets(
     tokenizer_config_path = os.path.join(save_directory, "tokenizer_config.json")
     if os.path.isfile(tokenizer_config_path):
         desired_added_tokens_decoder = {}
-        for token_id, added_token in getattr(
-            tokenizer, "added_tokens_decoder", {}
-        ).items():
+        for token_id, added_token in getattr(tokenizer, "added_tokens_decoder", {}).items():
             desired_added_tokens_decoder[str(token_id)] = {
                 "content": getattr(added_token, "content", str(added_token)),
                 "single_word": getattr(added_token, "single_word", False),
@@ -312,10 +301,7 @@ def _preserve_sentencepiece_tokenizer_assets(
         if desired_added_tokens_decoder:
             with open(tokenizer_config_path, "r", encoding = "utf-8") as file:
                 tokenizer_config = json.load(file)
-            if (
-                tokenizer_config.get("added_tokens_decoder")
-                != desired_added_tokens_decoder
-            ):
+            if tokenizer_config.get("added_tokens_decoder") != desired_added_tokens_decoder:
                 tokenizer_config["added_tokens_decoder"] = desired_added_tokens_decoder
                 with open(tokenizer_config_path, "w", encoding = "utf-8") as file:
                     json.dump(tokenizer_config, file, indent = 2, ensure_ascii = False)
@@ -339,7 +325,6 @@ def _preserve_sentencepiece_tokenizer_assets(
                     downloaded_path = local_path
             else:
                 from huggingface_hub import hf_hub_download
-
                 try:
                     downloaded_path = hf_hub_download(
                         repo_id = source,
@@ -352,14 +337,12 @@ def _preserve_sentencepiece_tokenizer_assets(
     if not os.path.isfile(tokenizer_model) and downloaded_path is not None:
         shutil.copy2(downloaded_path, tokenizer_model)
         logger.warning_once(
-            f"Unsloth: Preserved sentencepiece asset `tokenizer.model` in "
-            f"{save_directory}."
+            f"Unsloth: Preserved sentencepiece asset `tokenizer.model` in " f"{save_directory}."
         )
 
 
 def _free_cached_model(model):
     from huggingface_hub import scan_cache_dir
-
     cached_repos = list(scan_cache_dir().repos)
 
     # Go through every cached repo, and delete the one that matches the model we want to save.
@@ -385,9 +368,7 @@ def _merge_lora(layer, name):
         # Is LoRA so we need to merge!
         W, quant_state, A, B, s, bias = get_lora_parameters_bias(layer)
         if quant_state is not None:
-            dtype = (
-                quant_state.dtype if type(quant_state) is not list else quant_state[2]
-            )
+            dtype = quant_state.dtype if type(quant_state) is not list else quant_state[2]
             W = fast_dequantize(W, quant_state)
         else:
             dtype = W.dtype
@@ -402,9 +383,7 @@ def _merge_lora(layer, name):
             # if not torch.isfinite(W).all():
             maximum_element = torch.max(W.min().abs(), W.max())
             if not torch.isfinite(maximum_element).item():
-                raise ValueError(
-                    f"Unsloth: Merge failed.\n{name} has some elements = infinity."
-                )
+                raise ValueError(f"Unsloth: Merge failed.\n{name} has some elements = infinity.")
         W = W.t().to(dtype)
     else:
         W = layer.weight
@@ -424,7 +403,11 @@ def fast_save_pickle(shard, name):
     return
 
 
-def _preserve_tokenizer_eos_token(tokenizer, save_directory, filename_prefix = None):
+def _preserve_tokenizer_eos_token(
+    tokenizer,
+    save_directory,
+    filename_prefix = None,
+):
     """Restore tokenizer_config.json eos_token from the tokenizer passed to save.
 
     Some merge paths may re-save or mutate tokenizer metadata after the tokenizer
@@ -442,9 +425,7 @@ def _preserve_tokenizer_eos_token(tokenizer, save_directory, filename_prefix = N
     if tokenizer is None or save_directory is None:
         return
 
-    source_tokenizer = (
-        tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
-    )
+    source_tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
     eos_token = getattr(source_tokenizer, "eos_token", None)
     if eos_token is None and source_tokenizer is not tokenizer:
         eos_token = getattr(tokenizer, "eos_token", None)
@@ -453,9 +434,7 @@ def _preserve_tokenizer_eos_token(tokenizer, save_directory, filename_prefix = N
     eos_token = str(eos_token)
 
     tokenizer_config_name = (
-        f"{filename_prefix}-tokenizer_config.json"
-        if filename_prefix
-        else "tokenizer_config.json"
+        f"{filename_prefix}-tokenizer_config.json" if filename_prefix else "tokenizer_config.json"
     )
     tokenizer_config = os.path.join(str(save_directory), tokenizer_config_name)
     if not os.path.isfile(tokenizer_config):
@@ -547,13 +526,11 @@ def unsloth_save_model(
     # First check for a token!
     if push_to_hub:
         from huggingface_hub import whoami
-
         try:
             username = whoami(token = token)["name"]
         except:
             raise RuntimeError(
-                "Unsloth: Please supply a token!\n"
-                "Go to https://huggingface.co/settings/tokens"
+                "Unsloth: Please supply a token!\nGo to https://huggingface.co/settings/tokens"
             )
 
     assert maximum_memory_usage > 0 and maximum_memory_usage <= 0.95
@@ -564,11 +541,7 @@ def unsloth_save_model(
         gc.collect()
 
     save_method = save_method.lower().replace(" ", "_")
-    if (
-        save_method != "lora"
-        and save_method != "merged_16bit"
-        and save_method != "merged_4bit"
-    ):
+    if save_method != "lora" and save_method != "merged_16bit" and save_method != "merged_4bit":
         raise RuntimeError(
             "Unsloth: You must select one of 3 options when saving models:\n"
             '"lora"         ==> This is the fastest and easiet. Just saves LoRA modules.\n'
@@ -636,9 +609,7 @@ def unsloth_save_model(
         )
         if tokenizer is not None:
             # Set padding side to left for inference
-            _tokenizer = (
-                tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
-            )
+            _tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
             old_padding_side = _tokenizer.padding_side
             _tokenizer.padding_side = "left"
 
@@ -660,9 +631,7 @@ def unsloth_save_model(
             _tokenizer.padding_side = old_padding_side
 
         if hasattr(model, "config"):
-            print(
-                f"Saved {save_method} model to https://huggingface.co/" + save_directory
-            )
+            print(f"Saved {save_method} model to https://huggingface.co/" + save_directory)
         return save_directory, None
 
     # Tokenizer has different saving arguments
@@ -738,9 +707,7 @@ def unsloth_save_model(
             print("Unsloth: Saving tokenizer...", end = "")
 
             # Set padding side to left for inference
-            _tokenizer = (
-                tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
-            )
+            _tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
             old_padding_side = _tokenizer.padding_side
             _tokenizer.padding_side = "left"
 
@@ -764,10 +731,7 @@ def unsloth_save_model(
         model.save_pretrained(**save_pretrained_settings)
 
         if push_to_hub and hasattr(model, "config"):
-            print(
-                "Saved to https://huggingface.co/"
-                + save_pretrained_settings["save_directory"]
-            )
+            print("Saved to https://huggingface.co/" + save_pretrained_settings["save_directory"])
 
         print(" Done.")
         return save_directory, None
@@ -803,12 +767,8 @@ def unsloth_save_model(
     max_ram = psutil.virtual_memory().available
     sharded_ram_usage = 5 * 1024 * 1024 * 1024
     if type(max_shard_size) is str:
-        gb_found = re.match(
-            r"([0-9]{1,})[\s]{0,}GB", max_shard_size, flags = re.IGNORECASE
-        )
-        mb_found = re.match(
-            r"([0-9]{1,})[\s]{0,}MB", max_shard_size, flags = re.IGNORECASE
-        )
+        gb_found = re.match(r"([0-9]{1,})[\s]{0,}GB", max_shard_size, flags = re.IGNORECASE)
+        mb_found = re.match(r"([0-9]{1,})[\s]{0,}MB", max_shard_size, flags = re.IGNORECASE)
         if gb_found:
             sharded_ram_usage = int(gb_found.group(1)) * 1024 * 1024 * 1024
         elif mb_found:
@@ -881,13 +841,11 @@ def unsloth_save_model(
             torch_dtype = torch.bfloat16
 
     # Check modules to save float32 dtype
-    state_dict["model.embed_tokens.weight"] = (
-        internal_model.model.embed_tokens.weight.data.to(torch_dtype)
+    state_dict["model.embed_tokens.weight"] = internal_model.model.embed_tokens.weight.data.to(
+        torch_dtype
     )
 
-    max_vram = int(
-        torch.cuda.get_device_properties(0).total_memory * maximum_memory_usage
-    )
+    max_vram = int(torch.cuda.get_device_properties(0).total_memory * maximum_memory_usage)
 
     print("Unsloth: Saving model... This might take 5 minutes ...")
 
@@ -929,9 +887,7 @@ def unsloth_save_model(
         for item in LLAMA_LAYERNORMS:
             try:
                 # Skip for Gemma 2
-                state_dict[f"model.layers.{j}.{item}.weight"] = eval(
-                    f"layer.{item}.weight.data"
-                )
+                state_dict[f"model.layers.{j}.{item}.weight"] = eval(f"layer.{item}.weight.data")
             except:
                 continue
 
@@ -943,9 +899,7 @@ def unsloth_save_model(
         internal_model.model.embed_tokens.weight.data_ptr()
         != internal_model.lm_head.weight.data_ptr()
     ):
-        state_dict["lm_head.weight"] = internal_model.lm_head.weight.data.to(
-            torch_dtype
-        )
+        state_dict["lm_head.weight"] = internal_model.lm_head.weight.data.to(torch_dtype)
 
     # All tensors MUST be type torch.Tensor and not torch.nn.parameter.Parameter
     for key, value in state_dict.items():
@@ -1004,13 +958,10 @@ def unsloth_save_model(
     save_directory = save_pretrained_settings["save_directory"]
 
     if save_pretrained_settings["push_to_hub"]:
-        new_save_directory, new_username = _determine_username(
-            save_directory, username, token
-        )
+        new_save_directory, new_username = _determine_username(save_directory, username, token)
 
         if token is not None:
             from huggingface_hub import whoami
-
             actual_username = whoami(token = token)["name"]
         else:
             actual_username = username
@@ -1027,9 +978,7 @@ def unsloth_save_model(
         print("Unsloth: Saving tokenizer...", end = "")
 
         # Set padding side to left for inference
-        _tokenizer = (
-            tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
-        )
+        _tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
         old_padding_side = _tokenizer.padding_side
         _tokenizer.padding_side = "left"
 
@@ -1371,9 +1320,7 @@ def save_to_gguf(
     elif isinstance(quantization_method, tuple):
         quantization_method = list(quantization_method)
     else:
-        raise TypeError(
-            "Unsloth: quantization_method can only be a string or a list of strings"
-        )
+        raise TypeError("Unsloth: quantization_method can only be a string or a list of strings")
 
     # Check if bfloat16 is supported
     if model_dtype == "bf16" and not torch.cuda.is_bf16_supported():
@@ -1490,9 +1437,7 @@ def save_to_gguf(
         )
 
         # Step 3: Initial GGUF conversion
-        print(
-            f"Unsloth: [1] Converting model into {first_conversion_dtype} GGUF format."
-        )
+        print(f"Unsloth: [1] Converting model into {first_conversion_dtype} GGUF format.")
         print(f"This might take 3 minutes...")
 
         initial_files, is_vlm_update = convert_to_gguf(
@@ -1599,7 +1544,9 @@ def save_to_gguf(
                                 f"cmake --build build --config Release"
                             )
                         else:
-                            build_instructions = f'cd "{LLAMA_CPP_DEFAULT_DIR}" && make clean && make all -j'
+                            build_instructions = (
+                                f'cd "{LLAMA_CPP_DEFAULT_DIR}" && make clean && make all -j'
+                            )
 
                         raise RuntimeError(
                             f"Unsloth: Quantization failed for {output_location}\n"
@@ -1615,9 +1562,7 @@ def save_to_gguf(
         if quants_created:
             # convert_to_gguf may return multiple base shards plus an mmproj entry,
             # so treat every initial file that is not an mmproj as part of the base set.
-            base_files = [
-                f for f in initial_files if "-mmproj" not in os.path.basename(f).lower()
-            ]
+            base_files = [f for f in initial_files if "-mmproj" not in os.path.basename(f).lower()]
             if not want_full_precision:
                 for f in base_files:
                     if f in all_saved_locations:
@@ -1762,16 +1707,13 @@ def _determine_username(save_directory, old_username, token):
     save_directory = save_directory.lstrip("./")
     if "/" not in save_directory:
         from huggingface_hub import whoami
-
         try:
             username = whoami(token = token)["name"]
             if type(old_username) is str and username != old_username:
                 username = old_username
             save_directory = f"{username}/{save_directory}"
         except:
-            raise RuntimeError(
-                f"Unsloth: {save_directory} is not a Huggingface directory."
-            )
+            raise RuntimeError(f"Unsloth: {save_directory} is not a Huggingface directory.")
     else:
         username = save_directory.split("/")[0]
     return save_directory, username
@@ -1818,10 +1760,7 @@ def create_huggingface_repo(
         if datasets:
             try:
                 from huggingface_hub import metadata_update
-
-                metadata_update(
-                    save_directory, {"datasets": datasets}, overwrite = True, token = token
-                )
+                metadata_update(save_directory, {"datasets": datasets}, overwrite = True, token = token)
             except Exception as e:
                 logger.warning_once(
                     f"Unsloth: Could not update datasets metadata for {save_directory}: {e}"
@@ -1874,10 +1813,7 @@ def upload_to_huggingface(
         if datasets:
             try:
                 from huggingface_hub import metadata_update
-
-                metadata_update(
-                    save_directory, {"datasets": datasets}, overwrite = True, token = token
-                )
+                metadata_update(save_directory, {"datasets": datasets}, overwrite = True, token = token)
             except Exception as e:
                 logger.warning_once(
                     f"Unsloth: Could not update datasets metadata for {save_directory}: {e}"
@@ -1985,9 +1921,7 @@ def create_ollama_modelfile(tokenizer, base_model_name, model_location):
             f"Unsloth: No Ollama template mapping found for model '{base_model_name}'. Skipping Ollama Modelfile"
         )
         return None
-    tokenizer._ollama_modelfile = (
-        ollama_modelfile  # This comes from the unpacking above
-    )
+    tokenizer._ollama_modelfile = ollama_modelfile  # This comes from the unpacking above
     modelfile = ollama_modelfile
 
     FILE_LOCATION_REPLACER = "⚫@✅#🦥__FILE_LOCATION__⚡@🦥#⛵"
@@ -2005,9 +1939,9 @@ def create_ollama_modelfile(tokenizer, base_model_name, model_location):
     )
 
     # Revert {__FILE_LOCATION__} back
-    modelfile = modelfile.replace(
-        FILE_LOCATION_REPLACER, "{__FILE_LOCATION__}"
-    ).replace(EOS_TOKEN_REPLACER, "{__EOS_TOKEN__}")
+    modelfile = modelfile.replace(FILE_LOCATION_REPLACER, "{__FILE_LOCATION__}").replace(
+        EOS_TOKEN_REPLACER, "{__EOS_TOKEN__}"
+    )
 
     if "__EOS_TOKEN__" in modelfile:
         modelfile = modelfile.format(
@@ -2103,9 +2037,7 @@ def push_to_ollama_hub(username: str, model_name: str, tag: str):
 
 
 def push_to_ollama(tokenizer, gguf_location, username: str, model_name: str, tag: str):
-    model_file = create_ollama_modelfile(
-        tokenizer = tokenizer, gguf_location = gguf_location
-    )
+    model_file = create_ollama_modelfile(tokenizer = tokenizer, gguf_location = gguf_location)
 
     with open(f"Modelfile_{model_name}", "w", encoding = "utf-8") as f:
         f.write(model_file)
@@ -2210,10 +2142,7 @@ def unsloth_save_pretrained_gguf(
             hasattr(self.config, "architectures")
             and self.config.architectures == "GptOssForCausalLM"
         )
-        or (
-            hasattr(self.config, "model_type")
-            and self.config.model_type in ["gpt-oss", "gpt_oss"]
-        )
+        or (hasattr(self.config, "model_type") and self.config.model_type in ["gpt-oss", "gpt_oss"])
         else False
     )
     # Step 2: Prepare arguments for model saving
@@ -2256,14 +2185,10 @@ def unsloth_save_pretrained_gguf(
         fix_bos_token, old_chat_template = fix_tokenizer_bos_token(tokenizer)
 
     # Step 4: Save/merge model to 16-bit format
-    is_peft_model = isinstance(self, PeftModelForCausalLM) or isinstance(
-        self, PeftModel
-    )
+    is_peft_model = isinstance(self, PeftModelForCausalLM) or isinstance(self, PeftModel)
 
     if is_peft_model:
-        print(
-            f'Unsloth: Merging model weights to {"mxfp4" if is_gpt_oss else "16-bit"} format...'
-        )
+        print(f'Unsloth: Merging model weights to {"mxfp4" if is_gpt_oss else "16-bit"} format...')
         try:
             # Call unsloth_generic_save directly (it's in the same file)
             unsloth_generic_save(**arguments)
@@ -2286,9 +2211,7 @@ def unsloth_save_pretrained_gguf(
                 tokenizer.save_pretrained(save_directory)
         else:
             # Fallback: save the in-memory model to save_directory
-            print(
-                "Unsloth: Model is not a PEFT model. Saving directly without LoRA merge..."
-            )
+            print("Unsloth: Model is not a PEFT model. Saving directly without LoRA merge...")
             os.makedirs(save_directory, exist_ok = True)
             try:
                 self.save_pretrained(save_directory)
@@ -2307,7 +2230,6 @@ def unsloth_save_pretrained_gguf(
     # Step 6: Clean up memory
     for _ in range(3):
         import gc
-
         gc.collect()
         if torch.cuda.is_available():
             torch.cuda.empty_cache()
@@ -2363,12 +2285,9 @@ def unsloth_save_pretrained_gguf(
 
     try:
         from .tokenizer_utils import fix_sentencepiece_gguf
-
         fix_sentencepiece_gguf(save_directory)
     except Exception as e:
-        logger.warning(
-            f"Unsloth: fix_sentencepiece_gguf skipped ({type(e).__name__}): {e}"
-        )
+        logger.warning(f"Unsloth: fix_sentencepiece_gguf skipped ({type(e).__name__}): {e}")
 
     try:
         all_file_locations, want_full_precision, is_vlm_update = save_to_gguf(
@@ -2550,7 +2469,6 @@ def unsloth_push_to_hub_gguf(
     except Exception as e:
         if cleanup_temp:
             import shutil
-
             for d in [save_directory, f"{save_directory}_gguf"]:
                 try:
                     shutil.rmtree(d)
@@ -2588,15 +2506,11 @@ def unsloth_push_to_hub_gguf(
             if cleanup_temp and "unsloth_gguf_" in original_name:
                 # Extract the quantization part (e.g., ".Q8_0.gguf" or ".Q8_0-mmproj.gguf")
                 quant_suffix = (
-                    original_name.split(".", 1)[1]
-                    if "." in original_name
-                    else original_name
+                    original_name.split(".", 1)[1] if "." in original_name else original_name
                 )
                 proper_name = f"{model_name}.{quant_suffix}"
             else:
-                proper_name = original_name.replace(
-                    os.path.basename(save_directory), model_name
-                )
+                proper_name = original_name.replace(os.path.basename(save_directory), model_name)
 
             print(f"Uploading {proper_name}...")
 
@@ -2662,15 +2576,11 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
             original_name = os.path.basename(file)
             if cleanup_temp and "unsloth_gguf_" in original_name:
                 quant_suffix = (
-                    original_name.split(".", 1)[1]
-                    if "." in original_name
-                    else original_name
+                    original_name.split(".", 1)[1] if "." in original_name else original_name
                 )
                 proper_name = f"{model_name}.{quant_suffix}"
             else:
-                proper_name = original_name.replace(
-                    os.path.basename(save_directory), model_name
-                )
+                proper_name = original_name.replace(os.path.basename(save_directory), model_name)
             readme_content += f"- `{proper_name}`\n"
 
         # Special note for VLM with Modelfile
@@ -2681,9 +2591,7 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
             readme_content += "1. Place the `Modelfile` in the same directory as the finetuned bf16 merged model\n"
             readme_content += "3. Run: `ollama create model_name -f ./Modelfile`\n"
             readme_content += "   (Replace `model_name` with your desired name)\n\n"
-            readme_content += (
-                "This will create a unified bf16 model that Ollama can use.\n"
-            )
+            readme_content += "This will create a unified bf16 model that Ollama can use.\n"
         elif modelfile_location:
             readme_content += "\n## Ollama\n"
             readme_content += "An Ollama Modelfile is included for easy deployment.\n"
@@ -2713,9 +2621,7 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
             revision = revision,
         )
 
-        print(
-            f"Unsloth: Successfully uploaded GGUF to https://huggingface.co/{full_repo_id}"
-        )
+        print(f"Unsloth: Successfully uploaded GGUF to https://huggingface.co/{full_repo_id}")
 
         # Add tags
         if tags is None:
@@ -2736,10 +2642,7 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
         if datasets:
             try:
                 from huggingface_hub import metadata_update
-
-                metadata_update(
-                    full_repo_id, {"datasets": datasets}, overwrite = True, token = token
-                )
+                metadata_update(full_repo_id, {"datasets": datasets}, overwrite = True, token = token)
             except Exception as e:
                 logger.warning_once(
                     f"Unsloth: Could not update datasets metadata for {full_repo_id}: {e}"
@@ -2753,7 +2656,6 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
         if cleanup_temp:
             print("Unsloth: Cleaning up temporary files...")
             import shutil
-
             for d in [save_directory, f"{save_directory}_gguf"]:
                 if os.path.exists(d):
                     try:
@@ -2818,9 +2720,7 @@ def unsloth_convert_lora_to_ggml_and_push_to_hub(
     model_type = self.config.model_type
     output_file = os.path.join(lora_directory_push, "ggml-adapter-model.bin")
 
-    print(
-        f"Unsloth: Converting auto-saved LoRA adapters at {lora_directory_push} to GGML format."
-    )
+    print(f"Unsloth: Converting auto-saved LoRA adapters at {lora_directory_push} to GGML format.")
     print(f"The output file will be {output_file}")
 
     try:
@@ -2900,9 +2800,7 @@ def unsloth_convert_lora_to_ggml_and_save_locally(
     model_type = self.config.model_type
     output_file = os.path.join(save_directory, "ggml-adapter-model.bin")
 
-    print(
-        f"Unsloth: Converting auto-saved LoRA adapters at {save_directory} to GGML format."
-    )
+    print(f"Unsloth: Converting auto-saved LoRA adapters at {save_directory} to GGML format.")
     print(f"The output file will be {output_file}")
 
     try:
@@ -3092,9 +2990,7 @@ def unsloth_generic_save(
             variant = variant,
         )
         if "16bit" in save_method:
-            _target_dtype = (
-                torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
-            )
+            _target_dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
             _save_kwargs["state_dict"] = {
                 k: v.to(dtype = _target_dtype) if v.is_floating_point() else v
                 for k, v in model.state_dict().items()
@@ -3114,11 +3010,7 @@ def unsloth_generic_save(
                 **_save_kwargs,
             )
             if tokenizer is not None:
-                _tokenizer = (
-                    tokenizer.tokenizer
-                    if hasattr(tokenizer, "tokenizer")
-                    else tokenizer
-                )
+                _tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
                 old_padding_side = _tokenizer.padding_side
                 _tokenizer.padding_side = "left"
                 tokenizer.push_to_hub(
@@ -3134,11 +3026,7 @@ def unsloth_generic_save(
             print(f"Unsloth: Saving full fine-tuned model to '{save_directory}' ...")
             model.save_pretrained(save_directory, **_save_kwargs)
             if tokenizer is not None:
-                _tokenizer = (
-                    tokenizer.tokenizer
-                    if hasattr(tokenizer, "tokenizer")
-                    else tokenizer
-                )
+                _tokenizer = tokenizer.tokenizer if hasattr(tokenizer, "tokenizer") else tokenizer
                 old_padding_side = _tokenizer.padding_side
                 _tokenizer.padding_side = "left"
                 tokenizer.save_pretrained(save_directory)
@@ -3163,11 +3051,8 @@ def unsloth_generic_save(
     if push_to_hub and datasets:
         try:
             from huggingface_hub import metadata_update
-
             save_dir, _ = _determine_username(save_directory, None, token)
-            metadata_update(
-                save_dir, {"datasets": datasets}, overwrite = True, token = token
-            )
+            metadata_update(save_dir, {"datasets": datasets}, overwrite = True, token = token)
         except Exception as e:
             logger.warning_once(
                 f"Unsloth: Could not update datasets metadata for {save_directory}: {e}"
@@ -3289,9 +3174,7 @@ def _unsloth_save_torchao_with_attached_config(
     safe_serialization = False
 
     if push_to_hub:
-        model.push_to_hub(
-            save_directory, safe_serialization = safe_serialization, token = token
-        )
+        model.push_to_hub(save_directory, safe_serialization = safe_serialization, token = token)
         tokenizer.push_to_hub(save_directory, token = token)
     else:
         model.save_pretrained(save_directory, safe_serialization = safe_serialization)
@@ -3439,9 +3322,7 @@ def unsloth_save_pretrained_torchao(
     if token is None and push_to_hub:
         token = get_token()
 
-    has_qat_config = (
-        hasattr(self, "_torchao_config") and self._torchao_config is not None
-    )
+    has_qat_config = hasattr(self, "_torchao_config") and self._torchao_config is not None
 
     if torchao_config is not None:
         # PTQ path: user provided a config, model must NOT have QAT config unless PEFT
@@ -3478,9 +3359,7 @@ def unsloth_save_pretrained_torchao(
 
 
 def not_implemented_save(*args, **kwargs):
-    raise NotImplementedError(
-        "Unsloth: Sorry GGUF is currently not supported for vision models!"
-    )
+    raise NotImplementedError("Unsloth: Sorry GGUF is currently not supported for vision models!")
 
 
 def patch_saving_functions(model, vision = False):
@@ -3591,9 +3470,7 @@ def patch_saving_functions(model, vision = False):
         and model.save_pretrained.__name__ != "unsloth_tokenizer_save_pretrained"
     ):
         model.original_save_pretrained = model.save_pretrained
-        model.save_pretrained = types.MethodType(
-            unsloth_tokenizer_save_pretrained, model
-        )
+        model.save_pretrained = types.MethodType(unsloth_tokenizer_save_pretrained, model)
     elif getattr(model, "tokenizer", None) is not None:
         patch_saving_functions(model.tokenizer)
 
@@ -3605,9 +3482,7 @@ def patch_saving_functions(model, vision = False):
             and original_model.push_to_hub.__name__ != "unsloth_push_to_hub"
         ):
             original_model.original_push_to_hub = original_model.push_to_hub
-            original_model.push_to_hub = types.MethodType(
-                unsloth_push_to_hub, original_model
-            )
+            original_model.push_to_hub = types.MethodType(unsloth_push_to_hub, original_model)
             if hasattr(original_model, "add_model_tags"):
                 original_model.add_model_tags(
                     [
@@ -3624,19 +3499,13 @@ def patch_saving_functions(model, vision = False):
     if not vision:
         if hasattr(model, "config"):
             # Counteract tokenizers
-            model.push_to_hub_merged = types.MethodType(
-                unsloth_generic_push_to_hub_merged, model
-            )
+            model.push_to_hub_merged = types.MethodType(unsloth_generic_push_to_hub_merged, model)
             model.save_pretrained_merged = types.MethodType(
                 unsloth_generic_save_pretrained_merged, model
             )
             model.push_to_hub_gguf = types.MethodType(unsloth_push_to_hub_gguf, model)
-            model.save_pretrained_gguf = types.MethodType(
-                unsloth_save_pretrained_gguf, model
-            )
-            model.save_pretrained_torchao = types.MethodType(
-                unsloth_save_pretrained_torchao, model
-            )
+            model.save_pretrained_gguf = types.MethodType(unsloth_save_pretrained_gguf, model)
+            model.save_pretrained_torchao = types.MethodType(unsloth_save_pretrained_torchao, model)
             model.push_to_hub_ggml = types.MethodType(
                 unsloth_convert_lora_to_ggml_and_push_to_hub, model
             )
@@ -3645,17 +3514,11 @@ def patch_saving_functions(model, vision = False):
             )
     else:
         # Vision only 1 option
-        model.push_to_hub_merged = types.MethodType(
-            unsloth_generic_push_to_hub_merged, model
-        )
+        model.push_to_hub_merged = types.MethodType(unsloth_generic_push_to_hub_merged, model)
         model.save_pretrained_merged = types.MethodType(
             unsloth_generic_save_pretrained_merged, model
         )
         model.push_to_hub_gguf = types.MethodType(unsloth_push_to_hub_gguf, model)
-        model.save_pretrained_gguf = types.MethodType(
-            unsloth_save_pretrained_gguf, model
-        )
-        model.save_pretrained_torchao = types.MethodType(
-            unsloth_save_pretrained_torchao, model
-        )
+        model.save_pretrained_gguf = types.MethodType(unsloth_save_pretrained_gguf, model)
+        model.save_pretrained_torchao = types.MethodType(unsloth_save_pretrained_torchao, model)
     return model
diff --git a/unsloth/tokenizer_utils.py b/unsloth/tokenizer_utils.py
index 67edc41d52..556b2e53e2 100644
--- a/unsloth/tokenizer_utils.py
+++ b/unsloth/tokenizer_utils.py
@@ -135,10 +135,7 @@ def get_sorted_dict(dictionary):
     return sorted_dictionary
 
 
-def convert_to_fast_tokenizer(
-    slow_tokenizer,
-    temporary_location = "_unsloth_sentencepiece_temp",
-):
+def convert_to_fast_tokenizer(slow_tokenizer, temporary_location = "_unsloth_sentencepiece_temp"):
     is_fast = getattr(slow_tokenizer, "is_fast", False)
     if is_fast:
         return slow_tokenizer
@@ -180,9 +177,7 @@ def convert_to_fast_tokenizer(
     sorted_fast_tokenizer = get_sorted_dict(fast_tokenizer.get_vocab())
 
     check_vocab = sorted_slow_tokenizer == sorted_fast_tokenizer
-    check_special = (
-        slow_tokenizer.all_special_tokens == fast_tokenizer.all_special_tokens
-    )
+    check_special = slow_tokenizer.all_special_tokens == fast_tokenizer.all_special_tokens
 
     # Failure so return slow_tokenizer
     if not check_vocab or not check_special:
@@ -324,9 +319,7 @@ def assert_same_tokenization(slow_tokenizer, fast_tokenizer):
     slow_tokenizer.chat_template = slow_chat_template
     fast_tokenizer.chat_template = fast_chat_template
     """
-    check_chat_template = (
-        check_chat_template1 and check_chat_template2 and check_chat_template3
-    )
+    check_chat_template = check_chat_template1 and check_chat_template2 and check_chat_template3
 
     # Try special tokens
     try:
@@ -335,9 +328,7 @@ def assert_same_tokenization(slow_tokenizer, fast_tokenizer):
             + "A quick brown fox jumps over the lazy dog!!\n\nHi</s>\n\n"
             + "".join(all_special_tokens)
         )
-        check_special_tokens = (
-            slow_tokenizer(string).input_ids == fast_tokenizer(string).input_ids
-        )
+        check_special_tokens = slow_tokenizer(string).input_ids == fast_tokenizer(string).input_ids
 
         return check_chat_template and check_special_tokens
     except:
@@ -360,7 +351,6 @@ def fix_sentencepiece_tokenizer(
     # We need to manually edit the sentencepiece tokenizer!
     try:
         from transformers.convert_slow_tokenizer import import_protobuf
-
         sentencepiece_model_pb2 = import_protobuf()
     except Exception as e:
         try:
@@ -388,9 +378,7 @@ def fix_sentencepiece_tokenizer(
     old_tokenizer.save_pretrained(temporary_location)
 
     tokenizer_file = sentencepiece_model_pb2.ModelProto()
-    tokenizer_file.ParseFromString(
-        open(f"{temporary_location}/tokenizer.model", "rb").read()
-    )
+    tokenizer_file.ParseFromString(open(f"{temporary_location}/tokenizer.model", "rb").read())
 
     # Now save the new tokenizer
     new_tokenizer.save_pretrained(temporary_location)
@@ -446,7 +434,6 @@ def fix_sentencepiece_gguf(saved_location):
 
     try:
         from transformers.convert_slow_tokenizer import import_protobuf
-
         sys.modules.setdefault(
             "transformers.utils.sentencepiece_model_pb2",
             import_protobuf(),
@@ -469,9 +456,7 @@ def fix_sentencepiece_gguf(saved_location):
     tokenizer_file = sentencepiece_model_pb2.ModelProto()
     if not os.path.isfile(f"{saved_location}/tokenizer.model"):
         return
-    tokenizer_file.ParseFromString(
-        open(f"{saved_location}/tokenizer.model", "rb").read()
-    )
+    tokenizer_file.ParseFromString(open(f"{saved_location}/tokenizer.model", "rb").read())
     sentence_piece_size = len(tokenizer_file.pieces)
 
     # Build a set of token IDs that are marked as special in tokenizer.json.
@@ -515,9 +500,7 @@ def fix_sentencepiece_gguf(saved_location):
                 file.write(tokenizer_file.SerializeToString())
         return
 
-    added_tokens_json = dict(
-        sorted(added_tokens_json.items(), key = lambda item: item[1])
-    )
+    added_tokens_json = dict(sorted(added_tokens_json.items(), key = lambda item: item[1]))
     new_size = sentence_piece_size + len(added_tokens_json)
 
     # Confirm added_tokens_json is correct
@@ -629,22 +612,16 @@ def _load_correct_tokenizer(
     elif "phi-4" in tokenizer_name.lower():
         return fast_tokenizer
     elif slow_tokenizer is not None:
-        if hasattr(fast_tokenizer, "add_bos_token") and hasattr(
-            slow_tokenizer, "add_bos_token"
-        ):
+        if hasattr(fast_tokenizer, "add_bos_token") and hasattr(slow_tokenizer, "add_bos_token"):
             fast_tokenizer.add_bos_token = slow_tokenizer.add_bos_token
-        if hasattr(fast_tokenizer, "add_eos_token") and hasattr(
-            slow_tokenizer, "add_eos_token"
-        ):
+        if hasattr(fast_tokenizer, "add_eos_token") and hasattr(slow_tokenizer, "add_eos_token"):
             fast_tokenizer.add_eos_token = slow_tokenizer.add_eos_token
 
         # Confirm if slow and fast are equivalent!
         if assert_same_tokenization(slow_tokenizer, fast_tokenizer):
             return fast_tokenizer
         else:
-            logger.warning(
-                f"Unsloth: Will load {tokenizer_name} as a legacy tokenizer."
-            )
+            logger.warning(f"Unsloth: Will load {tokenizer_name} as a legacy tokenizer.")
             return convert_to_fast_tokenizer(slow_tokenizer)
         pass
     else:
@@ -675,8 +652,7 @@ def load_correct_tokenizer(
 
     # Ignore mistral type models since they don't have an add_generation_prompt
     if any(
-        s in str(getattr(tokenizer, "name_or_path", "")).lower()
-        for s in ["mistral", "qwen3guard"]
+        s in str(getattr(tokenizer, "name_or_path", "")).lower() for s in ["mistral", "qwen3guard"]
     ):
         chat_template = old_chat_template
 
@@ -709,7 +685,11 @@ _RE_ENDIF = re.compile(r"\{%(-?)\s*endif\s*(-?)%\}")
 _RE_JINJA_COMMENT = re.compile(r"\{#.*?#\}", flags = re.DOTALL)
 
 
-def _find_end_position(template, endfor = None, endif = None):
+def _find_end_position(
+    template,
+    endfor = None,
+    endif = None,
+):
     """Rightmost {% endfor %}/{% endif %} (any dash variant), as a dict
     with start/end/text/dash_left/dash_right. Tokens inside Jinja comments
     are ignored. `endfor`/`endif` kwargs kept for back-compat, ignored."""
@@ -743,7 +723,6 @@ def _template_ends_with_toplevel_for(chat_template):
     try:
         import jinja2
         import jinja2.nodes
-
         ast = jinja2.Environment().parse(chat_template)
     except Exception:
         return False
@@ -752,8 +731,7 @@ def _template_ends_with_toplevel_for(chat_template):
         for node in reversed(nodes):
             if isinstance(node, jinja2.nodes.Output):
                 only_ws = all(
-                    isinstance(child, jinja2.nodes.TemplateData)
-                    and child.data.strip() == ""
+                    isinstance(child, jinja2.nodes.TemplateData) and child.data.strip() == ""
                     for child in node.nodes
                 )
                 if only_ws:
@@ -783,10 +761,7 @@ def _if_body_emits_content(if_node):
     for node in if_node.body:
         if isinstance(node, jinja2.nodes.Output):
             return True
-        if any(
-            isinstance(d, jinja2.nodes.Output)
-            for d in node.find_all(jinja2.nodes.Output)
-        ):
+        if any(isinstance(d, jinja2.nodes.Output) for d in node.find_all(jinja2.nodes.Output)):
             return True
     return False
 
@@ -800,7 +775,6 @@ def _has_add_generation_prompt_block(chat_template):
     try:
         import jinja2
         import jinja2.nodes
-
         ast = jinja2.Environment().parse(chat_template)
     except Exception:
         return "if add_generation_prompt" in chat_template and "%}" in chat_template
@@ -859,12 +833,8 @@ def _derive_assistant_prefix_by_render(chat_template, is_sharegpt = False):
         sent_c_msgs = base_msgs + [{"from": "human", "value": _RENDER_DIFF_SENTINEL_C}]
     else:
         base_msgs = [{"role": "user", "content": "Hi"}]
-        sent_a_msgs = base_msgs + [
-            {"role": "assistant", "content": _RENDER_DIFF_SENTINEL_A}
-        ]
-        sent_b_msgs = base_msgs + [
-            {"role": "assistant", "content": _RENDER_DIFF_SENTINEL_B}
-        ]
+        sent_a_msgs = base_msgs + [{"role": "assistant", "content": _RENDER_DIFF_SENTINEL_A}]
+        sent_b_msgs = base_msgs + [{"role": "assistant", "content": _RENDER_DIFF_SENTINEL_B}]
         sent_c_msgs = base_msgs + [{"role": "user", "content": _RENDER_DIFF_SENTINEL_C}]
 
     # Strip trailing whitespace/comments after the last endfor/endif: they
@@ -959,29 +929,23 @@ def _fix_chat_template(chat_template, is_sharegpt = False):
         and after_endfor.count("{{") == 1
         and after_endfor.count("}}") == 1
     ):
-        wrapped = (
-            open_tag("if add_generation_prompt") + after_endfor + open_tag("endif")
-        )
+        wrapped = open_tag("if add_generation_prompt") + after_endfor + open_tag("endif")
         return chat_template[: end["end"]] + wrapped
 
     # Case 2 (GH#4150): template ends at {% endfor %} with only whitespace
     # or comments left. Inject an {% if add_generation_prompt %} block with
     # the assistant prefix derived by render-diff. The top-level-For gate
     # keeps us out of outer-If wrappers (e.g. Qwen3-Guard).
-    if _RE_JINJA_COMMENT.sub(
-        "", after_endfor
-    ).strip() == "" and _template_ends_with_toplevel_for(chat_template):
+    if _RE_JINJA_COMMENT.sub("", after_endfor).strip() == "" and _template_ends_with_toplevel_for(
+        chat_template
+    ):
         # No redundant "agp not in scrubbed" check: the fast path already
         # confirmed no *positive* block, and a mere reference (header
         # guard) should still get repaired.
-        assistant_prefix = _derive_assistant_prefix_by_render(
-            chat_template, is_sharegpt
-        )
+        assistant_prefix = _derive_assistant_prefix_by_render(chat_template, is_sharegpt)
         # Dual-probe: dict/list callers don't know the shape up front.
         if assistant_prefix is None and not is_sharegpt:
-            assistant_prefix = _derive_assistant_prefix_by_render(
-                chat_template, is_sharegpt = True
-            )
+            assistant_prefix = _derive_assistant_prefix_by_render(chat_template, is_sharegpt = True)
         if assistant_prefix is None:
             return chat_template
         # Escape for a double-quoted Jinja string literal.
@@ -992,11 +956,7 @@ def _fix_chat_template(chat_template, is_sharegpt = False):
             .replace("\r", "\\r")
         )
         generation_block = (
-            open_tag("if add_generation_prompt")
-            + '{{ "'
-            + escaped
-            + '" }}'
-            + open_tag("endif")
+            open_tag("if add_generation_prompt") + '{{ "' + escaped + '" }}' + open_tag("endif")
         )
         return chat_template[: end["end"]] + generation_block
 
@@ -1047,9 +1007,7 @@ def _format_chat_template_message(
             "Consider filing a bug report with the model maintainers."
         ).format(name = name_or_path)
     strict_suffix = (
-        ""
-        if strict
-        else (" Set UNSLOTH_STRICT_CHAT_TEMPLATE=1 to raise instead of warn.")
+        "" if strict else (" Set UNSLOTH_STRICT_CHAT_TEMPLATE=1 to raise instead of warn.")
     )
     if repaired:
         return (
@@ -1087,9 +1045,7 @@ def _validate_patched_template(tokenizer, patched_template, is_sharegpt):
     flag by appending (not replacing) content. Returns True if validation
     passes."""
     msgs = (
-        [{"from": "human", "value": "Hi"}]
-        if is_sharegpt
-        else [{"role": "user", "content": "Hi"}]
+        [{"from": "human", "value": "Hi"}] if is_sharegpt else [{"role": "user", "content": "Hi"}]
     )
     original = getattr(tokenizer, "chat_template", None)
     try:
@@ -1246,14 +1202,17 @@ class _VariantTokenizerProxy:
     preserved; falls back to bare Jinja for read-only stubs.
     """
 
-    def __init__(self, base_tokenizer, variant_template, variant_label = ""):
+    def __init__(
+        self,
+        base_tokenizer,
+        variant_template,
+        variant_label = "",
+    ):
         self._base = base_tokenizer
         self._template = variant_template
         base_name = getattr(base_tokenizer, "name_or_path", "unknown")
         self._source_path = base_name
-        self.name_or_path = (
-            f"{base_name} ({variant_label})" if variant_label else base_name
-        )
+        self.name_or_path = f"{base_name} ({variant_label})" if variant_label else base_name
 
     @property
     def chat_template(self):
@@ -1308,9 +1267,7 @@ def fix_chat_template(tokenizer):
             if not isinstance(tmpl, str):
                 fixed[key] = tmpl
                 continue
-            proxy = _VariantTokenizerProxy(
-                tokenizer, tmpl, variant_label = f"variant={key!r}"
-            )
+            proxy = _VariantTokenizerProxy(tokenizer, tmpl, variant_label = f"variant={key!r}")
             fixed[key] = _fix_chat_template_for_tokenizer(proxy, tmpl)
         return fixed
 
@@ -1358,9 +1315,7 @@ def check_tokenizer(
 
     max_embedding_size = model.model.embed_tokens.weight.shape[0]
     added_tokens_fast = tokenizer.added_tokens_decoder
-    added_tokens_fast = {
-        index: str(value) for index, value in added_tokens_fast.items()
-    }
+    added_tokens_fast = {index: str(value) for index, value in added_tokens_fast.items()}
     sorted_keys = sorted(added_tokens_fast)
     added_tokens_fast = {key: added_tokens_fast[key] for key in sorted_keys}
 
@@ -1381,9 +1336,7 @@ def check_tokenizer(
                 )
                 can_be_removed1 = [x for x in bad_tokens if x not in special_tokens]
                 can_be_removed2 = [
-                    x
-                    for x in can_be_removed1
-                    if x in tokenizer._added_tokens_encoder.keys()
+                    x for x in can_be_removed1 if x in tokenizer._added_tokens_encoder.keys()
                 ]
 
                 # Check of extra tokens can in fact we removed!
@@ -1396,9 +1349,7 @@ def check_tokenizer(
                 try_mapper = []
                 if not can_be_removed:
                     names = dir(tokenizer)
-                    names = (
-                        x for x in names if x.endswith("_token") and x.count("_") == 1
-                    )
+                    names = (x for x in names if x.endswith("_token") and x.count("_") == 1)
                     generic_tokens = [(x, getattr(tokenizer, x, None)) for x in names]
 
                     try_removal = []
diff --git a/unsloth/trainer.py b/unsloth/trainer.py
index 01b8822bd5..c5df9516df 100644
--- a/unsloth/trainer.py
+++ b/unsloth/trainer.py
@@ -70,11 +70,7 @@ def _should_pack(config) -> bool:
 
 
 def _should_auto_padding_free(config) -> bool:
-    if (
-        config is None
-        or _AUTO_PADDING_FREE_ENV_DISABLED
-        or getattr(config, "packing", False)
-    ):
+    if config is None or _AUTO_PADDING_FREE_ENV_DISABLED or getattr(config, "packing", False):
         return False
     return getattr(config, "padding_free", None) is None
 
@@ -227,9 +223,7 @@ class UnslothTrainer(SFTTrainer):
             return super().create_optimizer()
 
         if self.optimizer is None:
-            optimizer_cls, optimizer_kwargs = SFTTrainer.get_optimizer_cls_and_kwargs(
-                self.args
-            )
+            optimizer_cls, optimizer_kwargs = SFTTrainer.get_optimizer_cls_and_kwargs(self.args)
             self.optimizer = _create_unsloth_optimizer(
                 self.model,
                 optimizer_cls,
@@ -238,7 +232,11 @@ class UnslothTrainer(SFTTrainer):
             )
         return self.optimizer
 
-    def _create_q_galore_optimizer(self, config: "QGaloreConfig", embedding_lr = None):
+    def _create_q_galore_optimizer(
+        self,
+        config: "QGaloreConfig",
+        embedding_lr = None,
+    ):
         """Build the Q-GaLore optimizer from a QGaloreConfig."""
         from unsloth.optimizers.q_galore_adamw import (
             QGaLoreAdamW8bit,
@@ -351,8 +349,7 @@ def _resolve_trainer_params(trainer_class, init_fn):
     named = {
         k
         for k, v in params.items()
-        if v.kind
-        in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+        if v.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
         and k != "self"
     }
     if named:
@@ -404,9 +401,7 @@ def _backwards_compatible_trainer(trainer_class, config_class):
 
             # Get fields that should be passed to Config init
             config_fields = {
-                field.name: field
-                for field in dataclasses.fields(config_class)
-                if field.init
+                field.name: field for field in dataclasses.fields(config_class) if field.init
             }
 
             # Create config dict with valid fields from training_args
@@ -482,17 +477,13 @@ def _patch_sft_trainer_auto_packing(trl_module):
             if model_config is not None:
                 model_types = get_transformers_model_type(model_config)
                 # Blocklist: models that don't work correctly with padding_free
-                is_unsupported_model = any(
-                    x in PADDING_FREE_BLOCKLIST for x in model_types
-                )
+                is_unsupported_model = any(x in PADDING_FREE_BLOCKLIST for x in model_types)
 
                 # Check if VLM
                 architectures = getattr(model_config, "architectures", None)
                 if architectures is None:
                     architectures = []
-                is_vlm = any(
-                    x.endswith("ForConditionalGeneration") for x in architectures
-                )
+                is_vlm = any(x.endswith("ForConditionalGeneration") for x in architectures)
                 is_vlm = is_vlm or hasattr(model_config, "vision_config")
 
         processing_class = kwargs.get("processing_class") or kwargs.get("tokenizer")
@@ -523,7 +514,7 @@ def _patch_sft_trainer_auto_packing(trl_module):
                 reason = "vision-language model"
             elif is_unsupported_model:
                 reason = f"unsupported model type(s): {', '.join(model_types)}"
-            message = "Unsloth: Sample packing skipped " f"({reason} detected)."
+            message = f"Unsloth: Sample packing skipped ({reason} detected)."
             print(message)
 
         packing_active = False
@@ -541,9 +532,7 @@ def _patch_sft_trainer_auto_packing(trl_module):
             elif _should_auto_padding_free(config_arg):
                 configure_padding_free(config_arg)
                 auto_padding_free_active = True
-                logger.info(
-                    "Unsloth: Padding-free batching auto-enabled for SFTTrainer instance."
-                )
+                logger.info("Unsloth: Padding-free batching auto-enabled for SFTTrainer instance.")
 
         try:
             original_init(self, *args, **kwargs)
@@ -561,24 +550,16 @@ def _patch_sft_trainer_auto_packing(trl_module):
 
         trainer_args = getattr(self, "args", None)
         trainer_packing = bool(trainer_args and getattr(trainer_args, "packing", False))
-        trainer_padding_free = bool(
-            trainer_args and getattr(trainer_args, "padding_free", False)
-        )
+        trainer_padding_free = bool(trainer_args and getattr(trainer_args, "padding_free", False))
 
         if blocked and trainer_args is not None:
             # Mirror the block on the trainer args to avoid re-enabling later
             setattr(trainer_args, "packing", False)
             setattr(trainer_args, "padding_free", False)
 
-        if (
-            not blocked
-            and trainer_packing
-            and (packing_active or _should_pack(trainer_args))
-        ):
+        if not blocked and trainer_packing and (packing_active or _should_pack(trainer_args)):
             enable_sample_packing(self.model, self)
-            print(
-                "🦥 Unsloth: Packing enabled - training is >2x faster and uses less VRAM!"
-            )
+            print("🦥 Unsloth: Packing enabled - training is >2x faster and uses less VRAM!")
         elif not blocked and trainer_padding_free:
             enable_padding_free_metadata(self.model, self)
             message = (
@@ -603,9 +584,7 @@ def _patch_trl_trainer():
     import trl.trainer
 
     trl_classes = dir(trl.trainer)
-    trl_trainers = set(
-        x[: -len("Trainer")] for x in trl_classes if x.endswith("Trainer")
-    )
+    trl_trainers = set(x[: -len("Trainer")] for x in trl_classes if x.endswith("Trainer"))
     trl_configs = set(x[: -len("Config")] for x in trl_classes if x.endswith("Config"))
     trl_classes = list(trl_trainers & trl_configs)
 
diff --git a/unsloth/utils/attention_dispatch.py b/unsloth/utils/attention_dispatch.py
index 51e7c8e7a9..8f10d7570a 100644
--- a/unsloth/utils/attention_dispatch.py
+++ b/unsloth/utils/attention_dispatch.py
@@ -48,9 +48,7 @@ XFORMERS = "xformers"
 SDPA = "sdpa"
 
 
-XFORMERS_BLOCK_DIAG_CLS = (
-    xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else None
-)
+XFORMERS_BLOCK_DIAG_CLS = xformers.attn_bias.BlockDiagonalCausalMask if HAS_XFORMERS else None
 
 
 @dataclass
@@ -104,12 +102,7 @@ def select_attention_backend(use_varlen: bool = False) -> str:
 
 
 def run_attention(
-    *,
-    config: AttentionConfig,
-    context: AttentionContext,
-    Q: Tensor,
-    K: Tensor,
-    V: Tensor,
+    *, config: AttentionConfig, context: AttentionContext, Q: Tensor, K: Tensor, V: Tensor
 ) -> Tensor:
     """
     Run attention using config / context info.
@@ -193,20 +186,14 @@ def run_attention(
         if config.n_groups != 1:
             K_mod = K_t.view(bsz, kv_seq_len, config.n_kv_heads, 1, head_dim)
             V_mod = V_t.view(bsz, kv_seq_len, config.n_kv_heads, 1, head_dim)
-            K_mod = K_mod.expand(
-                bsz, kv_seq_len, config.n_kv_heads, config.n_groups, head_dim
-            )
-            V_mod = V_mod.expand(
-                bsz, kv_seq_len, config.n_kv_heads, config.n_groups, head_dim
-            )
+            K_mod = K_mod.expand(bsz, kv_seq_len, config.n_kv_heads, config.n_groups, head_dim)
+            V_mod = V_mod.expand(bsz, kv_seq_len, config.n_kv_heads, config.n_groups, head_dim)
 
             if requires_grad:
                 K_mod = K_mod.reshape(bsz, kv_seq_len, n_heads, head_dim)
                 V_mod = V_mod.reshape(bsz, kv_seq_len, n_heads, head_dim)
             else:
-                Q_mod = Q_t.view(
-                    bsz, q_len, config.n_kv_heads, config.n_groups, head_dim
-                )
+                Q_mod = Q_t.view(bsz, q_len, config.n_kv_heads, config.n_groups, head_dim)
 
         has_block = XFORMERS_BLOCK_DIAG_CLS is not None and isinstance(
             attn_bias, XFORMERS_BLOCK_DIAG_CLS
@@ -214,9 +201,7 @@ def run_attention(
 
         if config.n_groups != 1 and has_block:
             if not requires_grad:
-                Q_mod = Q_mod.view(
-                    1, bsz * q_len, config.n_kv_heads, config.n_groups, head_dim
-                )
+                Q_mod = Q_mod.view(1, bsz * q_len, config.n_kv_heads, config.n_groups, head_dim)
                 K_mod = K_mod.view(
                     1, bsz * kv_seq_len, config.n_kv_heads, config.n_groups, head_dim
                 )
@@ -267,26 +252,16 @@ def run_attention(
                         # tokenizer attention_mask is typically int 0/1
                         key_keep = local_mask != 0
 
-                    past_len = (
-                        k_len_local - q_len_local
-                    )  # works for prefill (0) and decode
-                    q_pos = torch.arange(
-                        past_len, past_len + q_len_local, device = Q.device
-                    )
+                    past_len = k_len_local - q_len_local  # works for prefill (0) and decode
+                    q_pos = torch.arange(past_len, past_len + q_len_local, device = Q.device)
                     k_pos = torch.arange(k_len_local, device = Q.device)
 
-                    causal_keep = (
-                        k_pos[None, :] <= q_pos[:, None]
-                    )  # True = allowed (SDPA)
+                    causal_keep = k_pos[None, :] <= q_pos[:, None]  # True = allowed (SDPA)
                     if sliding_window is not None:
-                        causal_keep &= k_pos[None, :] >= (
-                            q_pos[:, None] - (sliding_window - 1)
-                        )
+                        causal_keep &= k_pos[None, :] >= (q_pos[:, None] - (sliding_window - 1))
 
                     # (bsz, 1, q_len, k_len) boolean keep mask
-                    local_mask = (
-                        causal_keep[None, None, :, :] & key_keep[:, None, None, :]
-                    )
+                    local_mask = causal_keep[None, None, :, :] & key_keep[:, None, None, :]
 
                 elif local_mask.dim() == 3:
                     # (bsz, q_len, k_len) -> (bsz, 1, q_len, k_len)
@@ -297,15 +272,11 @@ def run_attention(
                         # Use boolean keep masks for better SDPA stability.
                         local_mask = local_mask.eq(0)
                 else:
-                    raise ValueError(
-                        f"Unsupported SDPA attention_mask rank: {local_mask.dim()}"
-                    )
+                    raise ValueError(f"Unsupported SDPA attention_mask rank: {local_mask.dim()}")
 
                 # Avoid NaNs from fully-masked rows (common with left padding).
                 if local_mask.dtype == torch.bool:
-                    no_allowed = ~local_mask.any(
-                        dim = -1, keepdim = True
-                    )  # (bsz,1,q_len,1)
+                    no_allowed = ~local_mask.any(dim = -1, keepdim = True)  # (bsz,1,q_len,1)
                     local_mask = local_mask | no_allowed
 
             is_causal_local = local_mask is None and q_len_local == k_len_local
diff --git a/unsloth/utils/packing.py b/unsloth/utils/packing.py
index bd6631d461..dd0a1bfb62 100644
--- a/unsloth/utils/packing.py
+++ b/unsloth/utils/packing.py
@@ -52,10 +52,7 @@ def _window_cache_key(sliding_window: Optional[int]) -> int:
     return int(sliding_window)
 
 
-def _get_cached_block_mask(
-    lengths: Tuple[int, ...],
-    sliding_window: Optional[int],
-):
+def _get_cached_block_mask(lengths: Tuple[int, ...], sliding_window: Optional[int]):
     if _XFormersBlockMask is None:
         return None
 
@@ -169,9 +166,7 @@ def enable_sample_packing(
                     if isinstance(ids, Iterable):
                         seq_lengths.append(len(ids))
             if seq_lengths:
-                batch["packed_seq_lengths"] = torch.tensor(
-                    seq_lengths, dtype = torch.int32
-                )
+                batch["packed_seq_lengths"] = torch.tensor(seq_lengths, dtype = torch.int32)
                 if "attention_mask" in batch:
                     batch.pop("attention_mask")
         return batch
@@ -224,8 +219,7 @@ def enable_padding_free_metadata(model, trainer):
 
 
 def get_packed_info_from_kwargs(
-    kwargs: dict,
-    device: torch.device,
+    kwargs: dict, device: torch.device
 ) -> Optional[Tuple[torch.Tensor, torch.Tensor, int]]:
     """Return packed sequence metadata expected by the attention kernels."""
 
@@ -261,11 +255,7 @@ def build_xformers_block_causal_mask(
         device = seq_lengths.device
         params = (sliding_window,)
         entry = _XFORMERS_BLOCK_MASK_CACHE.get(device)
-        if (
-            entry is not None
-            and entry["seq_lengths"] is seq_lengths
-            and entry["params"] == params
-        ):
+        if entry is not None and entry["seq_lengths"] is seq_lengths and entry["params"] == params:
             return entry["mask"]
 
         lengths_tensor = seq_lengths.to("cpu", torch.int32)
@@ -303,11 +293,7 @@ def build_sdpa_packed_attention_mask(
 
     params = (dtype, sliding_window)
     entry = _SDPA_MASK_CACHE.get(device)
-    if (
-        entry is not None
-        and entry["seq_lengths"] is seq_lengths
-        and entry["params"] == params
-    ):
+    if entry is not None and entry["seq_lengths"] is seq_lengths and entry["params"] == params:
         return entry["mask"]
 
     total_tokens = int(seq_lengths.sum().item())
@@ -323,15 +309,9 @@ def build_sdpa_packed_attention_mask(
         if length <= 0:
             continue
         block = torch.zeros((length, length), dtype = dtype, device = device)
-        upper = torch.triu(
-            torch.ones((length, length), device = device), diagonal = 1
-        ).bool()
+        upper = torch.triu(torch.ones((length, length), device = device), diagonal = 1).bool()
         block = block.masked_fill(upper, float("-inf"))
-        if (
-            sliding_window is not None
-            and sliding_window > 0
-            and length > sliding_window
-        ):
+        if sliding_window is not None and sliding_window > 0 and length > sliding_window:
             idx = torch.arange(length, device = device)
             dist = idx.unsqueeze(1) - idx.unsqueeze(0)
             window_mask = dist >= sliding_window
@@ -348,11 +328,7 @@ def build_sdpa_packed_attention_mask(
     return result
 
 
-def _normalize_packed_lengths(
-    seq_lengths: Any,
-    *,
-    device: torch.device,
-) -> Optional[torch.Tensor]:
+def _normalize_packed_lengths(seq_lengths: Any, *, device: torch.device) -> Optional[torch.Tensor]:
     if seq_lengths is None:
         return None
     if isinstance(seq_lengths, torch.Tensor):
diff --git a/unsloth_cli/commands/export.py b/unsloth_cli/commands/export.py
index be65f310ce..a72ceb5f27 100644
--- a/unsloth_cli/commands/export.py
+++ b/unsloth_cli/commands/export.py
@@ -56,9 +56,7 @@ def export(
     hf_token: Optional[str] = typer.Option(
         None, "--hf-token", envvar = "HF_TOKEN", help = "HuggingFace token."
     ),
-    private: bool = typer.Option(
-        False, "--private", help = "Make the HuggingFace repo private."
-    ),
+    private: bool = typer.Option(False, "--private", help = "Make the HuggingFace repo private."),
     max_seq_length: int = typer.Option(2048, "--max-seq-length"),
     load_in_4bit: bool = typer.Option(True, "--load-in-4bit/--no-load-in-4bit"),
 ):
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index edb8ea2cf4..b889a1e3bc 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -52,9 +52,7 @@ def _resolve_studio_home() -> tuple[Path, bool]:
         if prefix.name == "unsloth_studio":
             inferred = prefix.parent
             legacy = (Path.home() / ".unsloth" / "studio").resolve()
-            if inferred != legacy and _looks_like_installer_managed_studio_home(
-                inferred
-            ):
+            if inferred != legacy and _looks_like_installer_managed_studio_home(inferred):
                 return inferred, True
     except (OSError, ValueError):
         pass
@@ -234,9 +232,7 @@ def _iter_editable_studio_source_roots(venv_dir: Path):
                 # Tolerate single- or multi-line dict literals; [^}]* still
                 # rejects nested dicts, which the setuptools template never
                 # emits for editable installs.
-                m = re.search(
-                    r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S
-                )
+                m = re.search(r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S)
                 if not m:
                     continue
                 try:
@@ -326,9 +322,7 @@ def _create_api_key_inprocess(name: str) -> str:
 
 def _load_backend_auth_storage():
     run_py = _find_run_py()
-    backend_dir = (
-        run_py.parent if run_py is not None else _PACKAGE_ROOT / "studio" / "backend"
-    )
+    backend_dir = run_py.parent if run_py is not None else _PACKAGE_ROOT / "studio" / "backend"
     if backend_dir.is_dir() and str(backend_dir) not in sys.path:
         sys.path.insert(0, str(backend_dir))
 
@@ -437,13 +431,9 @@ def _connect_auth_db() -> sqlite3.Connection:
         conn.execute(
             "ALTER TABLE auth_user ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0"
         )
-    refresh_columns = {
-        row[1] for row in conn.execute("PRAGMA table_info(refresh_tokens)")
-    }
+    refresh_columns = {row[1] for row in conn.execute("PRAGMA table_info(refresh_tokens)")}
     if "is_desktop" not in refresh_columns:
-        conn.execute(
-            "ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0"
-        )
+        conn.execute("ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0")
     conn.commit()
     return conn
 
@@ -690,7 +680,6 @@ def studio_default(
 
     if not silent:
         from studio.backend.run import _resolve_external_ip
-
         display_host = _resolve_external_ip() if host == "0.0.0.0" else host
         typer.echo(f"Starting Unsloth Studio on http://{display_host}:{port}")
 
@@ -718,7 +707,6 @@ def studio_default(
                 time.sleep(1)
     except KeyboardInterrupt:
         from studio.backend.run import _graceful_shutdown, _server
-
         _graceful_shutdown(_server)
         typer.echo("\nShutting down...")
 
@@ -773,10 +761,7 @@ def _expand_attached_np_short() -> None:
 
 
 def _consume_legacy_short_aliases(
-    args: List[str],
-    aliases: tuple[str, ...],
-    current: Optional[str],
-    canonical: str,
+    args: List[str], aliases: tuple[str, ...], current: Optional[str], canonical: str
 ) -> tuple[Optional[str], List[str]]:
     """Pop exact-match legacy shorts (`-m`/`-hfr`/`-f`) from args;
     leave clusters (`-mg`/`-fa`/...) for the llama-server tail. Inline
@@ -795,9 +780,7 @@ def _consume_legacy_short_aliases(
             i += 1
             continue
         if value is not None:
-            raise typer.BadParameter(
-                f"{name} conflicts with {canonical} already provided"
-            )
+            raise typer.BadParameter(f"{name} conflicts with {canonical} already provided")
         if sep:
             if inline == "":  # `-m=` would become --model '' (Path('')='.').
                 raise typer.BadParameter(f"{name} requires a non-empty value")
@@ -807,9 +790,7 @@ def _consume_legacy_short_aliases(
             nxt = args[i + 1]
             # `--long` is unambiguously a flag; single-dash `-x` may be a path.
             if nxt.startswith("--") and nxt != "--":
-                raise typer.BadParameter(
-                    f"{name} expects a value but got the flag {nxt}"
-                )
+                raise typer.BadParameter(f"{name} expects a value but got the flag {nxt}")
             value = nxt
             i += 2
         else:
@@ -962,9 +943,7 @@ def run(
         # Re-exec via the studio venv's `unsloth` console-script.
         studio_bin = studio_python.parent / "unsloth"
         if not studio_bin.is_file():
-            typer.echo(
-                "Studio venv missing 'unsloth' entry point. Re-run: unsloth studio setup"
-            )
+            typer.echo("Studio venv missing 'unsloth' entry point. Re-run: unsloth studio setup")
             raise typer.Exit(1)
         args = [
             str(studio_bin),
@@ -1177,9 +1156,7 @@ def stop():
     try:
         os.kill(pid, 0)
     except ProcessLookupError:
-        typer.echo(
-            f"Studio server (PID {pid}) is not running. Cleaning up stale PID file."
-        )
+        typer.echo(f"Studio server (PID {pid}) is not running. Cleaning up stale PID file.")
         _PID_FILE.unlink(missing_ok = True)
         raise typer.Exit(0)
     except PermissionError:
@@ -1307,9 +1284,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
     if is_windows:
         ps_argv: list[str] = ["powershell.exe"]
         if _should_hide_windows_subprocesses():
-            ps_argv.extend(
-                ["-NoLogo", "-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden"]
-            )
+            ps_argv.extend(["-NoLogo", "-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden"])
 
         for script in candidates:
             try:
@@ -1331,9 +1306,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
                         **_windows_hidden_subprocess_kwargs(),
                     )
                     if result.returncode != 0:
-                        typer.echo(
-                            f"  refresh-launcher  install.ps1 exited {result.returncode}"
-                        )
+                        typer.echo(f"  refresh-launcher  install.ps1 exited {result.returncode}")
                     return
             except OSError:
                 continue
@@ -1346,9 +1319,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
             with urllib.request.urlopen(request, timeout = 30) as response:
                 installer = response.read().decode("utf-8", errors = "replace")
         except (urllib.error.URLError, TimeoutError, OSError) as exc:
-            typer.echo(
-                f"  refresh-launcher  skipped: could not fetch {installer_url} ({exc})"
-            )
+            typer.echo(f"  refresh-launcher  skipped: could not fetch {installer_url} ({exc})")
             return
 
         # install.ps1 auto-invokes `Install-UnslothStudio @args` at EOF; over
@@ -1389,9 +1360,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
                         f"  refresh-launcher  fetched install.ps1 exited {result.returncode}"
                     )
             except OSError as exc:
-                typer.echo(
-                    f"  refresh-launcher  skipped: powershell exec failed ({exc})"
-                )
+                typer.echo(f"  refresh-launcher  skipped: powershell exec failed ({exc})")
         finally:
             try:
                 os.unlink(ps1_path)
@@ -1408,9 +1377,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
                     check = False,
                 )
                 if result.returncode != 0:
-                    typer.echo(
-                        f"  refresh-launcher  install.sh exited {result.returncode}"
-                    )
+                    typer.echo(f"  refresh-launcher  install.sh exited {result.returncode}")
                 return
         except OSError:
             continue
@@ -1423,9 +1390,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
         with urllib.request.urlopen(request, timeout = 30) as response:
             installer = response.read()
     except (urllib.error.URLError, TimeoutError, OSError) as exc:
-        typer.echo(
-            f"  refresh-launcher  skipped: could not fetch {installer_url} ({exc})"
-        )
+        typer.echo(f"  refresh-launcher  skipped: could not fetch {installer_url} ({exc})")
         return
 
     try:
@@ -1436,9 +1401,7 @@ def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
             check = False,
         )
         if result.returncode != 0:
-            typer.echo(
-                f"  refresh-launcher  fetched install.sh exited {result.returncode}"
-            )
+            typer.echo(f"  refresh-launcher  fetched install.sh exited {result.returncode}")
     except OSError as exc:
         typer.echo(f"  refresh-launcher  skipped: bash exec failed ({exc})")
 
@@ -1458,9 +1421,7 @@ def setup(
 
 @studio_app.command()
 def update(
-    local: bool = typer.Option(
-        False, "--local", help = "Install from local repo instead of PyPI"
-    ),
+    local: bool = typer.Option(False, "--local", help = "Install from local repo instead of PyPI"),
     package: str = typer.Option(
         "unsloth", "--package", help = "Package name to install/update (for testing)"
     ),
@@ -1592,7 +1553,6 @@ def desktop_capabilities(
     }
     try:
         from importlib.metadata import version as package_version
-
         payload["version"] = package_version("unsloth")
     except Exception:
         pass
diff --git a/unsloth_cli/commands/train.py b/unsloth_cli/commands/train.py
index 1157620092..88a9594639 100644
--- a/unsloth_cli/commands/train.py
+++ b/unsloth_cli/commands/train.py
@@ -65,17 +65,13 @@ def train(
         raise typer.Exit(code = 2)
 
     if not cfg.data.dataset and not cfg.data.local_dataset:
-        typer.echo(
-            "Error: provide --dataset or --local-dataset (or via --config)", err = True
-        )
+        typer.echo("Error: provide --dataset or --local-dataset (or via --config)", err = True)
         raise typer.Exit(code = 2)
 
     # Check if the model path is a LoRA adapter (has adapter_config.json)
     model_path = Path(cfg.model) if cfg.model else None
     model_is_lora = (
-        model_path
-        and model_path.is_dir()
-        and (model_path / "adapter_config.json").exists()
+        model_path and model_path.is_dir() and (model_path / "adapter_config.json").exists()
     )
     use_lora = cfg.training.training_type.lower() == "lora"
 
@@ -120,9 +116,7 @@ def train(
 
     training_kwargs = cfg.training_kwargs()
     training_kwargs["wandb_token"] = wandb_token  # CLI/env takes precedence
-    started = trainer.start_training(
-        dataset = ds, eval_dataset = eval_ds, **training_kwargs
-    )
+    started = trainer.start_training(dataset = ds, eval_dataset = eval_ds, **training_kwargs)
 
     if not started:
         typer.echo("Training failed to start", err = True)
diff --git a/unsloth_cli/config.py b/unsloth_cli/config.py
index d5362f5673..3cfa87ec6d 100644
--- a/unsloth_cli/config.py
+++ b/unsloth_cli/config.py
@@ -84,9 +84,7 @@ class Config(BaseModel):
             target_modules = "all-linear" if self.lora.vision_all_linear else None
         else:
             parsed = [
-                m.strip()
-                for m in str(self.lora.target_modules).split(",")
-                if m and m.strip()
+                m.strip() for m in str(self.lora.target_modules).split(",") if m and m.strip()
             ]
             target_modules = parsed or None
 
@@ -143,7 +141,6 @@ def load_config(path: Optional[Path]) -> Config:
         data = yaml.safe_load(text) or {}
     else:
         import json
-
         data = json.loads(text or "{}")
 
     return Config(**data)
diff --git a/unsloth_cli/options.py b/unsloth_cli/options.py
index f1ab586ee5..4a2470ac00 100644
--- a/unsloth_cli/options.py
+++ b/unsloth_cli/options.py
@@ -80,9 +80,7 @@ def add_options_from_config(config_class: type[BaseModel]) -> Callable:
     which will receive a dict of all CLI-provided config values.
     """
     fields = _collect_config_fields(config_class)
-    field_names = {
-        name for name, field_info in fields if not _is_list_type(field_info.annotation)
-    }
+    field_names = {name for name, field_info in fields if not _is_list_type(field_info.annotation)}
 
     def decorator(func: Callable) -> Callable:
         sig = inspect.signature(func)
diff --git a/unsloth_cli/tests/test_studio_run_parallel_flag.py b/unsloth_cli/tests/test_studio_run_parallel_flag.py
index 561600e43b..abc0b3c7c4 100644
--- a/unsloth_cli/tests/test_studio_run_parallel_flag.py
+++ b/unsloth_cli/tests/test_studio_run_parallel_flag.py
@@ -29,7 +29,6 @@ def _load_run_command():
     """Import `studio` without triggering server start; backend imports
     are lazy inside run()."""
     from unsloth_cli.commands import studio as _studio
-
     return _studio
 
 
@@ -60,9 +59,7 @@ def test_parallel_default_is_four():
     sig = inspect.signature(studio_mod.run)
     opt = sig.parameters["parallel"].default
     default = getattr(opt, "default", None)
-    assert (
-        default == 4
-    ), f"default changed to {default}; would silently alter existing deployments"
+    assert default == 4, f"default changed to {default}; would silently alter existing deployments"
 
 
 def test_parallel_range_guards_are_set():
@@ -179,7 +176,12 @@ def _install_reexec_capture(monkeypatch, *, platform):
     return captured
 
 
-def _invoke_run(monkeypatch, args, *, platform = "linux"):
+def _invoke_run(
+    monkeypatch,
+    args,
+    *,
+    platform = "linux",
+):
     import typer as _typer
 
     studio_mod = _load_run_command()
@@ -224,9 +226,7 @@ def test_reexec_forwards_parallel_all_aliases(monkeypatch, flag, value):
 @pytest.mark.parametrize("platform", ["linux", "darwin", "win32"])
 def test_reexec_argv_is_consistent_across_platforms(monkeypatch, platform):
     """Linux/Darwin (execvp) and Windows (Popen) must build the same argv."""
-    result, captured = _invoke_run(
-        monkeypatch, _BASE + ["--parallel", "12"], platform = platform
-    )
+    result, captured = _invoke_run(monkeypatch, _BASE + ["--parallel", "12"], platform = platform)
     assert len(captured) == 1
     expected_kind = "popen" if platform == "win32" else "execvp"
     assert (
@@ -270,9 +270,7 @@ def test_reexec_mixed_parallel_with_passthrough(monkeypatch):
         (None, "--load-in-4bit"),  # default True
     ],
 )
-def test_reexec_forwards_load_in_4bit_in_both_directions(
-    monkeypatch, user_flag, expected_in_child
-):
+def test_reexec_forwards_load_in_4bit_in_both_directions(monkeypatch, user_flag, expected_in_child):
     """Re-exec must emit the chosen polarity (or the typer default),
     so a future default flip on one layer can't silently invert
     behaviour for users who never typed the flag."""
@@ -281,16 +279,10 @@ def test_reexec_forwards_load_in_4bit_in_both_directions(
     assert len(captured) == 1
     argv = captured[0]["argv"]
     other_polarity = (
-        "--no-load-in-4bit"
-        if expected_in_child == "--load-in-4bit"
-        else "--load-in-4bit"
+        "--no-load-in-4bit" if expected_in_child == "--load-in-4bit" else "--load-in-4bit"
     )
-    assert (
-        expected_in_child in argv
-    ), f"expected {expected_in_child} in child argv; got {argv}"
-    assert (
-        other_polarity not in argv
-    ), f"unexpected {other_polarity} in child argv; got {argv}"
+    assert expected_in_child in argv, f"expected {expected_in_child} in child argv; got {argv}"
+    assert other_polarity not in argv, f"unexpected {other_polarity} in child argv; got {argv}"
 
 
 # Runtime check: fake sys.prefix into the studio venv to bypass
@@ -306,7 +298,6 @@ class _RunServerCaptured(SystemExit):
 
 def _types_module(name):
     import types as _types
-
     return _types.ModuleType(name)
 
 
@@ -354,10 +345,9 @@ def test_studio_default_exposes_parallel_option():
     import inspect
 
     sig = inspect.signature(studio_mod.studio_default)
-    assert "parallel" in sig.parameters, (
-        "studio_default missing `parallel`; API-only path can't set "
-        "llama_parallel_slots"
-    )
+    assert (
+        "parallel" in sig.parameters
+    ), "studio_default missing `parallel`; API-only path can't set llama_parallel_slots"
     opt = sig.parameters["parallel"].default
     decls = set(getattr(opt, "param_decls", []) or [])
     assert "--parallel" in decls
diff --git a/unsloth_cli/tests/test_studio_run_short_alias_clashes.py b/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
index 8a3e94db47..2fb94c37c7 100644
--- a/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
+++ b/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
@@ -34,7 +34,6 @@ if str(_REPO_ROOT) not in sys.path:
 
 def _studio_mod():
     from unsloth_cli.commands import studio as _s
-
     return _s
 
 
@@ -87,9 +86,7 @@ def _install_capture(monkeypatch):
     captured = []
     monkeypatch.setattr(sys, "prefix", "/nonexistent/outer/venv")
     fake_bin = Path("/fake/studio/venv/unsloth_studio/bin/unsloth")
-    monkeypatch.setattr(
-        studio_mod, "_studio_venv_python", lambda: fake_bin.parent / "python"
-    )
+    monkeypatch.setattr(studio_mod, "_studio_venv_python", lambda: fake_bin.parent / "python")
     real_is_file = Path.is_file
     monkeypatch.setattr(
         Path,
@@ -147,12 +144,7 @@ _PREVIOUSLY_BROKEN = [
 
 
 @pytest.mark.parametrize("flag,value,llama_long_name", _PREVIOUSLY_BROKEN)
-def test_previously_broken_short_flag_now_passes_through(
-    monkeypatch,
-    flag,
-    value,
-    llama_long_name,
-):
+def test_previously_broken_short_flag_now_passes_through(monkeypatch, flag, value, llama_long_name):
     """Each of these was eaten by typer pre-cleanup; must pass through verbatim now."""
     extras = [flag] if value is None else [flag, value]
     captured = _invoke(monkeypatch, ["--model", "X"] + extras)
@@ -197,11 +189,7 @@ def test_dash_hf_documented_alias_still_works(monkeypatch):
         (["-hfr=unsloth/Qwen3-1.7B-GGUF"], "unsloth/Qwen3-1.7B-GGUF"),
     ],
 )
-def test_legacy_model_aliases_still_promote_to_model(
-    monkeypatch,
-    legacy_args,
-    expected_model,
-):
+def test_legacy_model_aliases_still_promote_to_model(monkeypatch, legacy_args, expected_model):
     """Pre-PR `-m X` / `-hfr X` set --model X; preprocessor preserves that."""
     captured = _invoke(monkeypatch, legacy_args)
     assert len(captured) == 1, f"parent did not re-exec for {legacy_args}"
@@ -227,9 +215,7 @@ def test_legacy_frontend_alias_still_promotes_to_frontend(monkeypatch):
 def test_legacy_model_alias_conflicts_with_long_form(monkeypatch):
     """`--model X` plus `-m Y` is ambiguous; must error pre-re-exec."""
     captured = _invoke(monkeypatch, ["--model", "X", "-m", "Y"])
-    assert (
-        len(captured) == 0
-    ), f"expected error before re-exec, got launch with argv = {captured}"
+    assert len(captured) == 0, f"expected error before re-exec, got launch with argv = {captured}"
 
 
 def test_clustered_tokens_are_not_promoted(monkeypatch):
@@ -262,9 +248,7 @@ def test_legacy_m_with_repo_variant_syntax(monkeypatch):
 def test_missing_model_after_preprocessor_errors(monkeypatch):
     """Neither --model nor a legacy alias → clean exit(2) before re-exec."""
     captured = _invoke(monkeypatch, ["--parallel", "8"])
-    assert (
-        len(captured) == 0
-    ), f"expected exit before re-exec, got launch with argv = {captured}"
+    assert len(captured) == 0, f"expected exit before re-exec, got launch with argv = {captured}"
 
 
 def test_legacy_m_inline_value_form(monkeypatch):
@@ -317,7 +301,6 @@ def test_consume_helper_leaves_clusters_alone():
 def test_consume_helper_value_already_set_raises():
     helper = _studio_mod()._consume_legacy_short_aliases
     import typer as _typer
-
     with pytest.raises(_typer.BadParameter):
         helper(["-m", "Y"], ("-m",), "X", "--model")
 
@@ -325,7 +308,6 @@ def test_consume_helper_value_already_set_raises():
 def test_consume_helper_missing_value_raises():
     helper = _studio_mod()._consume_legacy_short_aliases
     import typer as _typer
-
     with pytest.raises(_typer.BadParameter):
         helper(["-m"], ("-m",), None, "--model")
 
@@ -365,15 +347,7 @@ def test_expand_np_rewrites_attached_form(monkeypatch):
         ["unsloth", "studio", "run", "--model", "X", "-np8"],
     )
     _studio_mod()._expand_attached_np_short()
-    assert sys.argv == [
-        "unsloth",
-        "studio",
-        "run",
-        "--model",
-        "X",
-        "-np",
-        "8",
-    ]
+    assert sys.argv == ["unsloth", "studio", "run", "--model", "X", "-np", "8"]
 
 
 @pytest.mark.parametrize("value", ["1", "8", "64", "999"])
@@ -430,9 +404,7 @@ def test_expand_np_handles_signed_attached_forms(monkeypatch, attached, expected
     "attached,expected_suffix",
     [("-np8x", "8x"), ("-np-1foo", "-1foo"), ("-np9bar", "9bar")],
 )
-def test_expand_np_rewrites_numeric_prefix_even_with_junk(
-    monkeypatch, attached, expected_suffix
-):
+def test_expand_np_rewrites_numeric_prefix_even_with_junk(monkeypatch, attached, expected_suffix):
     """`-np8x` would surface as a baffling --port error; rewriting to
     `-np 8x` makes typer report against `-np` where it was typed."""
     monkeypatch.setattr(sys, "argv", ["unsloth", "run", attached])
@@ -465,9 +437,7 @@ def test_consume_helper_rejects_empty_inline_value():
         "unsloth-cli.py",
     ],
 )
-def test_third_party_importers_do_not_trigger_np_rewrite(
-    monkeypatch, third_party_argv0
-):
+def test_third_party_importers_do_not_trigger_np_rewrite(monkeypatch, third_party_argv0):
     """Only the `unsloth` / `unsloth.exe` console-script may run the
     canonicaliser; third-party scripts must keep their argv intact."""
     import os as _os

From 6f27ecc66e250a56d0538f7f9af4f273136d5777 Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Mon, 8 Jun 2026 20:20:00 +0530
Subject: [PATCH 110/222] Merge moe-lora-target-fix CI fixes

Merged latest main, resolved _utils.py and KTO test conflicts
---
 .github/workflows/consolidated-tests-ci.yml   |  1 +
 .github/workflows/studio-inference-smoke.yml  | 32 ++++++++----
 .../studio-windows-inference-smoke.yml        | 10 ++--
 tests/test_moe_lora_targets.py                | 51 +++++++++++++++++++
 .../test_trl_grpo_pinned_symbols.py           | 12 ++++-
 unsloth/import_fixes.py                       | 43 ++++++++++++++++
 unsloth/models/_utils.py                      | 35 +++++++++----
 7 files changed, 156 insertions(+), 28 deletions(-)
 create mode 100644 tests/test_moe_lora_targets.py

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index bf7e62e295..7e8d52525c 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -990,6 +990,7 @@ jobs:
               # First seen on transformers >=5,<6; each represents a slow
               # or recursive source-rewriter path the zoo can address.
               "beit":            "TimeoutError: compile exceeds per-model budget",
+              "deepseek_ocr2":    "TimeoutError: compile exceeds per-model budget",
               "sam":             "TimeoutError: compile exceeds per-model budget",
               "sam_hq":          "TimeoutError: compile exceeds per-model budget",
               "deepseek_ocr2":   "TimeoutError: compile exceeds per-model budget",
diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.yml
index c1297b84cc..3a4c76a2bb 100644
--- a/.github/workflows/studio-inference-smoke.yml
+++ b/.github/workflows/studio-inference-smoke.yml
@@ -20,7 +20,7 @@
 #        enable_tools / enabled_tools, and enable_thinking on/off.
 #
 #   3. JSON, images
-#        gemma-4-E2B-it UD-IQ3_XXS (~2.4 GiB) + mmproj-F16 (~986 MiB).
+#        Qwen3-VL-2B-Instruct UD-IQ2_XXS (~570 MiB) + mmproj-F16 (~780 MiB).
 #        response_format JSON-schema decoding and OpenAI image_url
 #        (data URI) plus Anthropic source/base64 image inputs.
 #
@@ -791,9 +791,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     env:
-      GGUF_REPO: unsloth/gemma-4-E2B-it-GGUF
-      GGUF_VARIANT: UD-IQ3_XXS
-      GGUF_FILE: gemma-4-E2B-it-UD-IQ3_XXS.gguf
+      GGUF_REPO: unsloth/Qwen3-VL-2B-Instruct-GGUF
+      GGUF_VARIANT: UD-IQ2_XXS
+      GGUF_FILE: Qwen3-VL-2B-Instruct-UD-IQ2_XXS.gguf
       MMPROJ_FILE: mmproj-F16.gguf
       STUDIO_PORT: '18890'
       HF_HOME: ${{ github.workspace }}/hf-cache
@@ -888,13 +888,23 @@ jobs:
             -H 'content-type: application/json' \
             -d "{\"username\":\"unsloth\",\"password\":\"$NEW\"}" | jq -r .access_token)
           echo "API_KEY=$TOKEN" >> "$GITHUB_ENV"
-          # Load the GGUF (mmproj is auto-detected via the HF repo
-          # lookup, the cached file is pulled out of HF_HOME).
-          curl -fs -X POST "http://127.0.0.1:${STUDIO_PORT}/api/inference/load" \
-            -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-            --max-time 900 \
-            -d "{\"model_path\":\"$GGUF_REPO\",\"gguf_variant\":\"$GGUF_VARIANT\",\"is_lora\":false,\"max_seq_length\":2048}" \
-            | jq '{status, display_name, is_vision}'
+          # Retry: llama-server startup can race process teardown after a
+          # failed attempt. Keep curl out of a pipe so HTTP failures are not
+          # masked by jq.
+          LOAD_OK=0
+          for attempt in 1 2 3; do
+            HTTP=$(curl -s -o /tmp/load.json -w '%{http_code}' \
+              -X POST "http://127.0.0.1:${STUDIO_PORT}/api/inference/load" \
+              -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+              --max-time 900 \
+              -d "{\"model_path\":\"$GGUF_REPO\",\"gguf_variant\":\"$GGUF_VARIANT\",\"is_lora\":false,\"max_seq_length\":2048}")
+            if [ "$HTTP" = "200" ]; then LOAD_OK=1; break; fi
+            echo "::warning::/api/inference/load attempt $attempt returned $HTTP; response:"
+            cat /tmp/load.json || true
+            sleep 10
+          done
+          [ "$LOAD_OK" = "1" ] || { echo "::error::/api/inference/load failed 3 attempts"; exit 22; }
+          jq '{status, display_name, is_vision}' /tmp/load.json
 
       - name: JSON schema decoding + image input
         env:
diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index bbe6b9e33a..6148856016 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -13,7 +13,7 @@
 #   2. Tool calling Tests
 #        Qwen3.5-2B UD-Q4_K_XL (~890 MiB).
 #   3. JSON, images
-#        gemma-4-E2B-it UD-Q4_K_XL + mmproj-F16 (~3.4 GiB total).
+#        Qwen3-VL-2B-Instruct UD-IQ2_XXS + mmproj-F16 (~1.4 GiB total).
 #        Within the 14 GB windows-latest SSD budget.
 
 name: Windows Studio GGUF CI
@@ -843,9 +843,9 @@ jobs:
       run:
         shell: bash
     env:
-      GGUF_REPO: unsloth/gemma-4-E2B-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-4-E2B-it-UD-Q4_K_XL.gguf
+      GGUF_REPO: unsloth/Qwen3-VL-2B-Instruct-GGUF
+      GGUF_VARIANT: UD-IQ2_XXS
+      GGUF_FILE: Qwen3-VL-2B-Instruct-UD-IQ2_XXS.gguf
       MMPROJ_FILE: mmproj-F16.gguf
       STUDIO_PORT: '18899'
       HF_HOME: ${{ github.workspace }}/hf-cache
@@ -1123,7 +1123,7 @@ jobs:
           )
           data_uri = f"data:image/png;base64,{PNG_64X64_RED_B64}"
 
-          # On Windows + the gemma-4-E2B mmproj, llama.cpp's vision
+          # On Windows + the Qwen3-VL mmproj, llama.cpp's vision
           # path runs on CPU (no Metal involvement). The wrapper is
           # kept for resilience but the vision path is expected to
           # work on Windows; an exception here is a real regression.
diff --git a/tests/test_moe_lora_targets.py b/tests/test_moe_lora_targets.py
new file mode 100644
index 0000000000..994d39f261
--- /dev/null
+++ b/tests/test_moe_lora_targets.py
@@ -0,0 +1,51 @@
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+
+class _ExpertWeights(torch.nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.gate_up_proj = torch.nn.Parameter(torch.zeros(2, 4, 8))
+        self.down_proj = torch.nn.Parameter(torch.zeros(2, 8, 4))
+
+
+class _Mlp(torch.nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.experts = _ExpertWeights()
+
+
+class _FakeMoeModel(torch.nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.config = SimpleNamespace(num_experts = 2, model_type = "qwen3_moe")
+        self.mlp = _Mlp()
+
+
+@pytest.mark.parametrize(
+    "target_modules",
+    [
+        ".*mlp.*proj",
+        ".*ffn.*proj",
+        r"(?:\bmodel\.layers\.[\d]{1,}\.(?:mlp)\.(?:gate_proj|up_proj|down_proj))",
+    ],
+)
+def test_regex_mlp_targets_discover_moe_parameters(target_modules):
+    from unsloth.models._utils import get_moe_target_parameters
+    assert get_moe_target_parameters(_FakeMoeModel(), target_modules) == [
+        "mlp.experts.gate_up_proj",
+        "mlp.experts.down_proj",
+    ]
+
+
+def test_explicit_dotted_module_target_does_not_discover_moe_parameters():
+    from unsloth.models._utils import get_moe_target_parameters
+    assert (
+        get_moe_target_parameters(
+            _FakeMoeModel(),
+            "model.layers.0.mlp.shared_expert.down_proj",
+        )
+        is None
+    )
diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index 3f6c40f90d..e49f9292e0 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -554,11 +554,12 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         "trl/experimental/kto/kto_trainer.py",
         "trl/experimental/kto/__init__.py",
     ]
+    checked_sources = []
     for path in candidates:
         src = fetch_text("huggingface/trl", tag, path)
         if src is None:
             continue
-        # Legacy: explicit get_batch_logps method.
+        checked_sources.append((path, src))
         if has_def(src, "get_batch_logps", "func"):
             return
         # TRL 1.x: refactored into _compute_logps + selective_log_softmax.
@@ -569,6 +570,15 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         # the exact shape kto_trainer_align_completion_logps patches.
         if "per_token_logps = selective_log_softmax(shift_logits" in src:
             return
+    old_shape_check = (
+        'raise ValueError("Logits (batch and sequence length dim) and labels '
+        'must have the same shape.")'
+    )
+    if checked_sources and not any(old_shape_check in src for _, src in checked_sources):
+        # TRL main inlined KTO log-prob computation and removed the old
+        # helper/shape-check rewrite target. There is no skipped rewrite to
+        # guard until a new concrete KTO shape mismatch target appears.
+        return
     pytest.fail(
         f"{tag}: KTO log-prob computation not found in any of {candidates}; "
         f"unsloth/models/rl_replacements.py KTO rewrite silently skipped"
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 45b127a067..c8be78bc3c 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1597,6 +1597,8 @@ def patch_peft_weight_converter_compatibility():
     except (ImportError, AttributeError):
         return
 
+    _patch_peft_moe_target_conversion(twc)
+
     if getattr(twc, "_unsloth_weight_converter_compat_patch", False):
         return
 
@@ -1666,6 +1668,47 @@ def patch_peft_weight_converter_compatibility():
     twc._unsloth_weight_converter_compat_patch = True
 
 
+def _patch_peft_moe_target_conversion(twc):
+    """Keep PEFT 0.19 MoE conversion from rewriting explicit Unsloth targets."""
+    if getattr(twc, "_unsloth_moe_target_conversion_patch", False):
+        return
+
+    original_convert_moe = getattr(twc, "_convert_peft_config_moe", None)
+    if original_convert_moe is None:
+        return
+
+    @functools.wraps(original_convert_moe)
+    def _convert_peft_config_moe_unsloth(peft_config, model_type: str) -> None:
+        if getattr(peft_config, "target_parameters", None):
+            return
+
+        target_modules = getattr(peft_config, "target_modules", None)
+        if isinstance(target_modules, str):
+            if "." in target_modules:
+                return
+            return original_convert_moe(peft_config, model_type)
+
+        if not target_modules:
+            return original_convert_moe(peft_config, model_type)
+
+        explicit_targets = {
+            target for target in target_modules if isinstance(target, str) and "." in target
+        }
+        if not explicit_targets:
+            return original_convert_moe(peft_config, model_type)
+
+        bare_targets = set(target_modules) - explicit_targets
+        if not bare_targets:
+            return
+
+        peft_config.target_modules = bare_targets
+        original_convert_moe(peft_config, model_type)
+        peft_config.target_modules = set(peft_config.target_modules or ()) | explicit_targets
+
+    twc._convert_peft_config_moe = _convert_peft_config_moe_unsloth
+    twc._unsloth_moe_target_conversion_patch = True
+
+
 CAUSAL_CONV1D_BROKEN = False
 _CAUSAL_CONV1D_PREFIX = "causal_conv1d"
 _CAUSAL_CONV1D_BLOCKER_SENTINEL = "_unsloth_causal_conv1d_blocker"
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 10f3ce0b1d..f8324bf8e0 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -3154,6 +3154,21 @@ def _resolve_moe_parameter_name(model, default_name: str, alternate_name: str) -
     return default_name
 
 
+_MOE_BROAD_MLP_TARGETS = frozenset(("gate_proj", "up_proj", "down_proj", "gate_up_proj"))
+
+
+def _moe_target_set_from_string(target_modules: str) -> set[str]:
+    if target_modules in _MOE_BROAD_MLP_TARGETS:
+        return {target_modules}
+
+    is_regex = re.search(r"[*+?()[\]{}|\\^$]", target_modules) is not None
+    targets_mlp = "mlp" in target_modules or "ffn" in target_modules
+    if is_regex and "proj" in target_modules and targets_mlp:
+        return set(_MOE_BROAD_MLP_TARGETS)
+
+    return set()
+
+
 def get_moe_target_parameters(model, target_modules = None) -> Optional[List[str]]:
     """
     Get the target_parameters for MoE expert layers if applicable.
@@ -3193,20 +3208,18 @@ def get_moe_target_parameters(model, target_modules = None) -> Optional[List[str
     if num_experts is None:
         num_experts = 0
 
-    # Determine which MoE parameters to include based on target_modules
-    moe_params = []
-
-    # Normalize target_modules to a set for efficient lookup
     if target_modules is None:
-        # If no target_modules specified, include all MoE params
-        target_set = {"gate_proj", "up_proj", "down_proj", "gate_up_proj"}
+        return None
     elif isinstance(target_modules, str):
-        target_set = {target_modules}
-        # Heuristic for regex matching MLPs
-        if "proj" in target_modules and ("mlp" in target_modules or "ffn" in target_modules):
-            target_set.update({"gate_proj", "up_proj", "down_proj", "gate_up_proj"})
+        target_set = _moe_target_set_from_string(target_modules)
     else:
-        target_set = set(target_modules) if target_modules else set()
+        target_set = {
+            target
+            for target in target_modules or ()
+            if (isinstance(target, str) and "." not in target and target in _MOE_BROAD_MLP_TARGETS)
+        }
+
+    moe_params = []
 
     gate_up_name = _resolve_moe_parameter_name(
         model,

From ca476c41f86b661f454ac687de56db3401be3f4a Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Mon, 8 Jun 2026 20:20:08 +0530
Subject: [PATCH 111/222] Merge studio_gemma4_vlm CI fixes

Merged latest main, resolved model_config.py conflict, removed redundant VLM checks
---
 studio/backend/tests/test_vision_cache.py   | 202 ++++++++++++++++++++
 studio/backend/utils/models/model_config.py | 144 +++++++++-----
 2 files changed, 296 insertions(+), 50 deletions(-)

diff --git a/studio/backend/tests/test_vision_cache.py b/studio/backend/tests/test_vision_cache.py
index 2af64dac91..78f88fd7ea 100644
--- a/studio/backend/tests/test_vision_cache.py
+++ b/studio/backend/tests/test_vision_cache.py
@@ -117,6 +117,18 @@ class TestVisionCacheSubprocessPath:
         mock_subprocess.assert_called_once()
         assert _vision_detection_cache[("unsloth/Qwen3.5-2B", None)] is True
 
+    @patch("utils.models.model_config._raw_config_has_vision_config", return_value = True)
+    @patch("utils.models.model_config._is_vision_model_subprocess", return_value = None)
+    @patch("utils.transformers_version.needs_transformers_5", return_value = True)
+    def test_subprocess_none_falls_back_to_raw_vision_config(
+        self, mock_needs_t5, mock_subprocess, mock_raw_config
+    ):
+        assert is_vision_model("unsloth/gemma-4-E4B-it") is True
+        assert is_vision_model("unsloth/gemma-4-E4B-it") is True
+
+        mock_subprocess.assert_called_once()
+        mock_raw_config.assert_called_once_with("unsloth/gemma-4-E4B-it", hf_token = None)
+
 
 # ---------------------------------------------------------------------------
 # Exception handling — cache the False fallback
@@ -221,6 +233,42 @@ class TestVisionCacheDirectPath:
         assert is_vision_model("Qwen/Qwen2-VL-7B") is True
         mock_load_config.assert_called_once()
 
+    @patch("utils.transformers_version.needs_transformers_5", return_value = False)
+    @patch("utils.models.model_config.load_model_config")
+    def test_gemma4_model_type_detected_and_cached(self, mock_load_config, mock_needs_t5):
+        cfg = MagicMock(spec = [])
+        cfg.model_type = "gemma4"
+        cfg.architectures = ["Gemma4ForConditionalGeneration"]
+        mock_load_config.return_value = cfg
+
+        assert is_vision_model("google/gemma-4-E4B-it") is True
+        assert is_vision_model("google/gemma-4-E4B-it") is True
+        mock_load_config.assert_called_once()
+
+    @patch("utils.transformers_version.needs_transformers_5", return_value = False)
+    @patch("utils.models.model_config.load_model_config")
+    def test_gemma4_audio_subconfig_not_detected_as_vision(self, mock_load_config, mock_needs_t5):
+        cfg = MagicMock(spec = [])
+        cfg.model_type = "gemma4_audio"
+        cfg.architectures = ["Gemma4AudioModel"]
+        mock_load_config.return_value = cfg
+
+        assert is_vision_model("local/gemma4-audio-encoder") is False
+        assert is_vision_model("local/gemma4-audio-encoder") is False
+        mock_load_config.assert_called_once()
+
+    @patch("utils.transformers_version.needs_transformers_5", return_value = False)
+    @patch("utils.models.model_config.load_model_config")
+    def test_gemma4_text_subconfig_not_detected_as_vision(self, mock_load_config, mock_needs_t5):
+        cfg = MagicMock(spec = [])
+        cfg.model_type = "gemma4_text"
+        cfg.architectures = ["Gemma4ForCausalLM"]
+        mock_load_config.return_value = cfg
+
+        assert is_vision_model("local/gemma-4-text") is False
+        assert is_vision_model("local/gemma-4-text") is False
+        mock_load_config.assert_called_once()
+
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
     @patch("utils.models.model_config.load_model_config")
     def test_audio_model_excluded_and_cached(self, mock_load_config, mock_needs_t5):
@@ -261,3 +309,157 @@ class TestVisionCacheTokenHandling:
         assert is_vision_model("gated/model", hf_token = "token-a") is True
         assert is_vision_model("gated/model", hf_token = "token-a") is True
         mock_uncached.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Direct unit tests for _raw_config_has_vision_config
+# ---------------------------------------------------------------------------
+
+
+import json as _json
+
+from utils.models.model_config import (
+    _AUDIO_ONLY_MODEL_TYPES,
+    _VISION_CHECK_INLINE_HELPERS,
+    _VISION_CHECK_SCRIPT,
+    _is_vlm,
+    _raw_config_has_vision_config,
+)
+
+
+def _write_config(tmp_path, config):
+    (tmp_path / "config.json").write_text(_json.dumps(config))
+    return tmp_path
+
+
+class TestRawConfigVlmDetection:
+    """Direct coverage of _raw_config_has_vision_config across the same
+    indicator set used by _is_vlm. The cache integration tests above mock
+    this function; these exercise its real implementation."""
+
+    def test_truthy_vision_config(self, tmp_path):
+        p = _write_config(tmp_path, {"vision_config": {"hidden_size": 1024}})
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_empty_vision_config_key(self, tmp_path):
+        p = _write_config(tmp_path, {"vision_config": {}})
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_arch_suffix_detection(self, tmp_path):
+        p = _write_config(
+            tmp_path,
+            {
+                "architectures": ["Gemma4ForConditionalGeneration"],
+                "model_type": "gemma4",
+            },
+        )
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_img_processor_key(self, tmp_path):
+        p = _write_config(tmp_path, {"img_processor": {"image_size": 336}})
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_image_token_index_key(self, tmp_path):
+        p = _write_config(tmp_path, {"image_token_index": 32000})
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_known_vlm_model_type(self, tmp_path):
+        p = _write_config(tmp_path, {"model_type": "gemma4"})
+        assert _raw_config_has_vision_config(str(p)) is True
+
+    def test_plain_text_model_returns_false(self, tmp_path):
+        p = _write_config(
+            tmp_path,
+            {"model_type": "llama", "architectures": ["LlamaForCausalLM"]},
+        )
+        assert _raw_config_has_vision_config(str(p)) is False
+
+    def test_missing_config_returns_none(self, tmp_path):
+        assert _raw_config_has_vision_config(str(tmp_path)) is None
+
+
+# ---------------------------------------------------------------------------
+# Self-contained subprocess script (no parent backend imports)
+# ---------------------------------------------------------------------------
+
+
+class TestSubprocessScript:
+    def test_does_not_import_parent_module(self):
+        assert "from utils.models.model_config" not in _VISION_CHECK_SCRIPT
+
+    def test_inline_is_vlm_executes_correctly(self):
+        ns: dict = {}
+        exec(_VISION_CHECK_INLINE_HELPERS, ns)
+        inline_is_vlm = ns["_is_vlm"]
+
+        class _C:
+            def __init__(self, **kw):
+                for k, v in kw.items():
+                    setattr(self, k, v)
+
+        assert (
+            inline_is_vlm(
+                _C(
+                    model_type = "gemma4",
+                    architectures = ["Gemma4ForConditionalGeneration"],
+                )
+            )
+            is True
+        )
+        assert (
+            inline_is_vlm(_C(model_type = "gemma4_text", architectures = ["Gemma4ForCausalLM"]))
+            is False
+        )
+        assert inline_is_vlm(_C(model_type = "llama", architectures = ["LlamaForCausalLM"])) is False
+
+
+# ---------------------------------------------------------------------------
+# Audio-only model exclusion must apply across every detection path
+# ---------------------------------------------------------------------------
+
+
+class TestVlmAudioExclusion:
+    """The {csm, whisper} guard previously lived only in the direct caller
+    branch. These tests assert it now applies inside _is_vlm, the raw
+    fallback, and the inlined subprocess helper too."""
+
+    def test_audio_only_set_canonical(self):
+        assert _AUDIO_ONLY_MODEL_TYPES == {"csm", "whisper"}
+
+    def test_is_vlm_excludes_whisper(self):
+        cfg = MagicMock(spec = [])
+        cfg.model_type = "whisper"
+        cfg.architectures = ["WhisperForConditionalGeneration"]
+        assert _is_vlm(cfg) is False
+
+    def test_raw_fallback_excludes_whisper(self, tmp_path):
+        p = _write_config(
+            tmp_path,
+            {
+                "architectures": ["WhisperForConditionalGeneration"],
+                "model_type": "whisper",
+            },
+        )
+        assert _raw_config_has_vision_config(str(p)) is False
+
+    def test_inline_subprocess_helper_excludes_whisper(self):
+        ns: dict = {}
+        exec(_VISION_CHECK_INLINE_HELPERS, ns)
+        cfg = MagicMock(spec = [])
+        cfg.model_type = "whisper"
+        cfg.architectures = ["WhisperForConditionalGeneration"]
+        assert ns["_is_vlm"](cfg) is False
+
+    @patch("utils.models.model_config._is_vision_model_subprocess", return_value = None)
+    @patch("utils.transformers_version.needs_transformers_5", return_value = True)
+    def test_t5_subprocess_none_falls_back_through_raw_for_whisper(
+        self, mock_needs_t5, mock_subprocess, tmp_path
+    ):
+        _write_config(
+            tmp_path,
+            {
+                "architectures": ["WhisperForConditionalGeneration"],
+                "model_type": "whisper",
+            },
+        )
+        assert is_vision_model(str(tmp_path)) is False
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 92960485a4..2947bab3d3 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -507,8 +507,13 @@ _VLM_MODEL_TYPES = {
     "internvl_chat",
     "cogvlm2",
     "minicpmv",
+    "gemma4",
 }
 
+# Audio-only models that share the ForConditionalGeneration suffix
+# (e.g. CsmForConditionalGeneration, WhisperForConditionalGeneration).
+_AUDIO_ONLY_MODEL_TYPES = {"csm", "whisper"}
+
 # Pre-computed .venv_t5 paths and backend dir for subprocess version switching.
 # Vision check uses 5.5.0 (newest, recognizes all architectures).
 from utils.paths.storage_roots import studio_root as _studio_root  # noqa: E402
@@ -516,9 +521,77 @@ from utils.paths.storage_roots import studio_root as _studio_root  # noqa: E402
 _VENV_T5_DIR = str(_studio_root() / ".venv_t5_550")
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent.parent)
 
+
+def _is_vlm(config) -> bool:
+    architectures = getattr(config, "architectures", None) or []
+    model_type = getattr(config, "model_type", None)
+    if model_type in _AUDIO_ONLY_MODEL_TYPES:
+        return False
+    return (
+        any(x.endswith(_VLM_ARCH_SUFFIXES) for x in architectures)
+        or hasattr(config, "vision_config")
+        or hasattr(config, "img_processor")
+        or hasattr(config, "image_token_index")
+        or model_type in _VLM_MODEL_TYPES
+    )
+
+
+def _raw_config_has_vision_config(
+    model_name: str, hf_token: Optional[str] = None
+) -> Optional[bool]:
+    try:
+        if is_local_path(model_name):
+            config_path = Path(normalize_path(model_name)).expanduser() / "config.json"
+        else:
+            from huggingface_hub import hf_hub_download
+            config_path = Path(
+                hf_hub_download(
+                    repo_id = model_name,
+                    filename = "config.json",
+                    token = hf_token,
+                )
+            )
+        config = json.loads(config_path.read_text())
+        architectures = config.get("architectures") or []
+        model_type = config.get("model_type")
+        if model_type in _AUDIO_ONLY_MODEL_TYPES:
+            return False
+        return (
+            any(isinstance(x, str) and x.endswith(_VLM_ARCH_SUFFIXES) for x in architectures)
+            or "vision_config" in config
+            or "img_processor" in config
+            or "image_token_index" in config
+            or model_type in _VLM_MODEL_TYPES
+        )
+    except Exception as exc:
+        logger.warning("Could not read config.json for '%s': %s", model_name, exc)
+        return None
+
+
+# why: inline _is_vlm and constants are prepended so the subprocess stays
+# self-contained and does not import the parent backend module graph.
+_VISION_CHECK_INLINE_HELPERS = (
+    "_VLM_ARCH_SUFFIXES = " + repr(_VLM_ARCH_SUFFIXES) + "\n"
+    "_VLM_MODEL_TYPES = " + repr(_VLM_MODEL_TYPES) + "\n"
+    "_AUDIO_ONLY_MODEL_TYPES = " + repr(_AUDIO_ONLY_MODEL_TYPES) + "\n"
+    "def _is_vlm(config):\n"
+    "    architectures = getattr(config, 'architectures', None) or []\n"
+    "    model_type = getattr(config, 'model_type', None)\n"
+    "    if model_type in _AUDIO_ONLY_MODEL_TYPES:\n"
+    "        return False\n"
+    "    return (\n"
+    "        any(x.endswith(_VLM_ARCH_SUFFIXES) for x in architectures)\n"
+    "        or hasattr(config, 'vision_config')\n"
+    "        or hasattr(config, 'img_processor')\n"
+    "        or hasattr(config, 'image_token_index')\n"
+    "        or model_type in _VLM_MODEL_TYPES\n"
+    "    )\n"
+)
+
 # Inline script executed in a subprocess with transformers 5.x activated.
 # Receives model_name and token via argv, prints JSON result to stdout.
-_VISION_CHECK_SCRIPT = r"""
+_VISION_CHECK_SCRIPT = (
+    r"""
 import sys, os, json
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
@@ -532,32 +605,20 @@ sys.path.insert(0, venv_t5)
 if backend_dir not in sys.path:
     sys.path.insert(0, backend_dir)
 
+"""
+    + _VISION_CHECK_INLINE_HELPERS
+    + r"""
 try:
     from transformers import AutoConfig
+
     kwargs = {"trust_remote_code": True}
     if token:
         kwargs["token"] = token
     config = AutoConfig.from_pretrained(model_name, **kwargs)
 
-    is_vlm = False
-    if hasattr(config, "architectures"):
-        is_vlm = any(
-            x.endswith(("ForConditionalGeneration", "ForVisionText2Text"))
-            for x in config.architectures
-        )
-    if not is_vlm and hasattr(config, "vision_config"):
-        is_vlm = True
-    if not is_vlm and hasattr(config, "img_processor"):
-        is_vlm = True
-    if not is_vlm and hasattr(config, "image_token_index"):
-        is_vlm = True
-    if not is_vlm and hasattr(config, "model_type"):
-        vlm_types = {"phi3_v","llava","llava_next","llava_onevision",
-                      "internvl_chat","cogvlm2","minicpmv"}
-        if config.model_type in vlm_types:
-            is_vlm = True
+    is_vlm = _is_vlm(config)
 
-    model_type = getattr(config, "model_type", "unknown")
+    model_type = getattr(config, "model_type", None)
     archs = getattr(config, "architectures", [])
     print(json.dumps({"is_vision": is_vlm, "model_type": model_type,
                        "architectures": archs}))
@@ -565,6 +626,7 @@ except Exception as exc:
     print(json.dumps({"error": str(exc)}))
     sys.exit(1)
 """
+)
 
 
 def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
@@ -728,48 +790,30 @@ def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -
             "Model '%s' needs transformers 5.x -- checking vision via subprocess",
             model_name,
         )
-        return _is_vision_model_subprocess(model_name, hf_token = hf_token)
+        result = _is_vision_model_subprocess(model_name, hf_token = hf_token)
+        if result is not None:
+            return result
+        return _raw_config_has_vision_config(model_name, hf_token = hf_token)
 
     try:
         config = load_model_config(model_name, use_auth = True, token = hf_token)
 
         # Exclude audio-only models that share ForConditionalGeneration suffix
         # (e.g. CsmForConditionalGeneration, WhisperForConditionalGeneration)
-        _audio_only_model_types = {"csm", "whisper"}
         model_type = getattr(config, "model_type", None)
-        if model_type in _audio_only_model_types:
+        if model_type in _AUDIO_ONLY_MODEL_TYPES:
             return False
 
-        # Check 1: Architecture class name patterns
-        if hasattr(config, "architectures"):
-            is_vlm = any(x.endswith(_VLM_ARCH_SUFFIXES) for x in config.architectures)
-            if is_vlm:
-                logger.info(
-                    f"Model {model_name} detected as VLM: architecture {config.architectures}"
-                )
-                return True
-
-        # Check 2: Has vision_config (most VLMs: LLaVA, Gemma-3, Qwen2-VL, etc.)
-        if hasattr(config, "vision_config"):
-            logger.info(f"Model {model_name} detected as VLM: has vision_config")
+        if _is_vlm(config):
+            archs = getattr(config, "architectures", None) or []
+            logger.info(
+                "Model %s detected as VLM (model_type=%s, architectures=%s)",
+                model_name,
+                model_type,
+                archs,
+            )
             return True
 
-        # Check 3: Has img_processor (Phi-3.5 Vision uses this instead of vision_config)
-        if hasattr(config, "img_processor"):
-            logger.info(f"Model {model_name} detected as VLM: has img_processor")
-            return True
-
-        # Check 4: Has image_token_index (common in VLMs for image placeholder tokens)
-        if hasattr(config, "image_token_index"):
-            logger.info(f"Model {model_name} detected as VLM: has image_token_index")
-            return True
-
-        # Check 5: Known VLM model_type values that may not match above checks
-        if hasattr(config, "model_type"):
-            if config.model_type in _VLM_MODEL_TYPES:
-                logger.info(f"Model {model_name} detected as VLM: model_type={config.model_type}")
-                return True
-
         return False
 
     except Exception as e:

From b30e2b4b15cb58a9ac09fe466a0be6ab5e162a74 Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Mon, 8 Jun 2026 22:02:05 +0530
Subject: [PATCH 112/222] Merge qwen35_export CI fixes

Merged latest main, resolved save.py/KTO test conflicts, fixed TRL/GRPO KTO drift
---
 ...est_qwen3_5_vlm_full_finetune_key_remap.py | 71 +++++++++++++++++++
 .../test_trl_grpo_pinned_symbols.py           |  1 +
 unsloth/save.py                               | 42 ++++++++++-
 3 files changed, 111 insertions(+), 3 deletions(-)
 create mode 100644 tests/saving/test_qwen3_5_vlm_full_finetune_key_remap.py

diff --git a/tests/saving/test_qwen3_5_vlm_full_finetune_key_remap.py b/tests/saving/test_qwen3_5_vlm_full_finetune_key_remap.py
new file mode 100644
index 0000000000..ba3b6874a4
--- /dev/null
+++ b/tests/saving/test_qwen3_5_vlm_full_finetune_key_remap.py
@@ -0,0 +1,71 @@
+import ast
+import types
+from pathlib import Path
+
+import torch
+
+
+def _load_qwen3_5_vlm_save_helpers():
+    source = Path(__file__).parents[2] / "unsloth" / "save.py"
+    tree = ast.parse(source.read_text(encoding = "utf-8"))
+    helpers = [
+        node
+        for node in tree.body
+        if isinstance(node, ast.FunctionDef)
+        and node.name
+        in {
+            "_is_qwen3_5_vlm",
+            "_qwen3_5_vlm_state_dict_for_save",
+        }
+    ]
+    module = ast.Module(body = helpers, type_ignores = [])
+    ast.fix_missing_locations(module)
+    namespace = {}
+    exec(compile(module, str(source), "exec"), namespace)
+    return namespace
+
+
+def _qwen3_5_vlm_model():
+    return types.SimpleNamespace(
+        config = types.SimpleNamespace(
+            architectures = ["Qwen3_5ForConditionalGeneration"],
+            model_type = "qwen3_5",
+            vision_config = types.SimpleNamespace(),
+        )
+    )
+
+
+def test_qwen3_5_vlm_state_dict_uses_hf_checkpoint_namespace():
+    helpers = _load_qwen3_5_vlm_save_helpers()
+    state_dict = {
+        "language_model.model.embed_tokens.weight": torch.ones(2, 2),
+        "language_model.model.layers.0.input_layernorm.weight": torch.ones(2),
+        "language_model.lm_head.weight": torch.ones(2, 2),
+        "visual.blocks.0.norm1.weight": torch.ones(2),
+        "other.weight": torch.ones(2),
+    }
+
+    remapped = helpers["_qwen3_5_vlm_state_dict_for_save"](state_dict)
+
+    assert "model.language_model.embed_tokens.weight" in remapped
+    assert "model.language_model.layers.0.input_layernorm.weight" in remapped
+    assert "lm_head.weight" in remapped
+    assert "model.visual.blocks.0.norm1.weight" in remapped
+    assert "other.weight" in remapped
+    assert "language_model.model.embed_tokens.weight" not in remapped
+    assert "language_model.lm_head.weight" not in remapped
+    assert "visual.blocks.0.norm1.weight" not in remapped
+
+
+def test_qwen3_5_vlm_detection_requires_vision_config():
+    helpers = _load_qwen3_5_vlm_save_helpers()
+    assert helpers["_is_qwen3_5_vlm"](_qwen3_5_vlm_model())
+
+    model = types.SimpleNamespace(
+        config = types.SimpleNamespace(
+            architectures = ["Qwen3_5ForCausalLM"],
+            model_type = "qwen3_5_text",
+        )
+    )
+
+    assert not helpers["_is_qwen3_5_vlm"](model)
diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index e49f9292e0..ce5e2644fd 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -560,6 +560,7 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
         if src is None:
             continue
         checked_sources.append((path, src))
+        # Legacy: explicit get_batch_logps method.
         if has_def(src, "get_batch_logps", "func"):
             return
         # TRL 1.x: refactored into _compute_logps + selective_log_softmax.
diff --git a/unsloth/save.py b/unsloth/save.py
index d6f69e6a6c..a44f186e40 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -457,6 +457,36 @@ def _preserve_tokenizer_eos_token(
         )
 
 
+def _is_qwen3_5_vlm(model):
+    config = getattr(model, "config", None)
+    if config is None or not hasattr(config, "vision_config"):
+        return False
+    architectures = getattr(config, "architectures", None) or ()
+    return any(
+        architecture
+        in (
+            "Qwen3_5ForConditionalGeneration",
+            "Qwen3_5MoeForConditionalGeneration",
+        )
+        for architecture in architectures
+    ) or getattr(config, "model_type", None) in ("qwen3_5", "qwen3_5_moe")
+
+
+def _qwen3_5_vlm_state_dict_for_save(state_dict):
+    remapped_state_dict = {}
+    for key, value in state_dict.items():
+        if key.startswith("language_model.model."):
+            new_key = "model.language_model." + key[len("language_model.model.") :]
+        elif key.startswith("visual."):
+            new_key = "model.visual." + key[len("visual.") :]
+        elif key.startswith("language_model.lm_head."):
+            new_key = "lm_head." + key[len("language_model.lm_head.") :]
+        else:
+            new_key = key
+        remapped_state_dict[new_key] = value
+    return remapped_state_dict
+
+
 @torch.inference_mode
 def unsloth_save_model(
     model,
@@ -2983,18 +3013,24 @@ def unsloth_generic_save(
         if not is_main_process:
             return
 
-        # Honor merged_16bit by casting to the target dtype if needed
         _save_kwargs = dict(
             safe_serialization = safe_serialization,
             max_shard_size = max_shard_size,
             variant = variant,
         )
+        is_qwen3_5_vlm = _is_qwen3_5_vlm(model)
+        if ("16bit" in save_method or is_qwen3_5_vlm) and state_dict is None:
+            state_dict = model.state_dict()
         if "16bit" in save_method:
             _target_dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
-            _save_kwargs["state_dict"] = {
+            state_dict = {
                 k: v.to(dtype = _target_dtype) if v.is_floating_point() else v
-                for k, v in model.state_dict().items()
+                for k, v in state_dict.items()
             }
+        if is_qwen3_5_vlm:
+            state_dict = _qwen3_5_vlm_state_dict_for_save(state_dict)
+        if state_dict is not None:
+            _save_kwargs["state_dict"] = state_dict
 
         if push_to_hub:
             print(f"Unsloth: Pushing full fine-tuned model to '{save_directory}' ...")

From 6f36e8403a0830b311059006bcce3aad95f77229 Mon Sep 17 00:00:00 2001
From: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
Date: Mon, 8 Jun 2026 23:23:53 +0530
Subject: [PATCH 113/222] Merge nvfp4_load CI fixes

Merged latest main, resolved KTO test conflicts, fixed nvfp4 test to use synthetic configs, fixed TRL/GRPO KTO drift
---
 tests/test_nvfp4_quant_load.py | 143 +++++++++++++++++++++++++++++++++
 unsloth/models/llama.py        |  16 +++-
 unsloth/models/loader_utils.py |  43 +++++++++-
 unsloth/models/vision.py       |   8 ++
 4 files changed, 207 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_nvfp4_quant_load.py

diff --git a/tests/test_nvfp4_quant_load.py b/tests/test_nvfp4_quant_load.py
new file mode 100644
index 0000000000..988fae5c97
--- /dev/null
+++ b/tests/test_nvfp4_quant_load.py
@@ -0,0 +1,143 @@
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Test cases for NVFP4 / compressed-tensors model loading.
+Ensures that models with non-bitsandbytes quantization configs
+don't conflict with Unsloth's default load_in_4bit=True behavior.
+
+Uses synthetic config objects (no network access) so this suite
+runs offline in CI where tests/security/conftest.py blocks socket
+connections.
+"""
+
+from types import SimpleNamespace
+
+# Import unsloth first to set UNSLOTH_IS_PRESENT env var
+import unsloth
+from unsloth_zoo.utils import get_quant_type
+from unsloth.models.loader_utils import check_and_disable_bitsandbytes_loading
+
+
+def _make_config(quantization_config = None, model_type = "llama"):
+    return SimpleNamespace(
+        quantization_config = quantization_config,
+        model_type = model_type,
+    )
+
+
+_NVFP4_QCFG_DICT = {
+    "quant_method": "compressed-tensors",
+    "format": "nvfp4-pack-quantized",
+    "quantization_config": {"num_bits": 4},
+}
+
+_BNB_QCFG_DICT = {
+    "quant_method": "bitsandbytes",
+    "load_in_4bit": True,
+    "bnb_4bit_compute_dtype": "float16",
+    "llm_int8_skip_modules": [],
+}
+
+
+def test_nvfp4_config_has_compressed_tensors():
+    config = _make_config(quantization_config = _NVFP4_QCFG_DICT)
+    qcfg = config.quantization_config
+    assert qcfg is not None
+    assert qcfg.get("quant_method") == "compressed-tensors"
+    assert qcfg.get("format") == "nvfp4-pack-quantized"
+
+
+def test_regular_bnb_config_has_bitsandbytes():
+    config = _make_config(quantization_config = _BNB_QCFG_DICT)
+    qcfg = config.quantization_config
+    assert qcfg is not None
+    assert qcfg.get("quant_method") == "bitsandbytes"
+
+
+def test_nvfp4_disables_load_in_4bit():
+    config = _make_config(quantization_config = _NVFP4_QCFG_DICT)
+    quant_method = get_quant_type(config)
+    assert quant_method == "compressed-tensors"
+
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = False, verbose = False
+    )
+    assert load_in_4bit is False
+    assert load_in_8bit is False
+
+
+def test_bnb_does_not_disable_load_in_4bit():
+    config = _make_config(quantization_config = _BNB_QCFG_DICT)
+    quant_method = get_quant_type(config)
+    assert quant_method == "bitsandbytes"
+
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = False, verbose = False
+    )
+    assert load_in_4bit is True
+    assert load_in_8bit is False
+
+
+def test_no_quantization_config_leaves_settings_unchanged():
+    config = _make_config(quantization_config = None)
+    quant_method = get_quant_type(config)
+    assert quant_method is None
+
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = False, verbose = False
+    )
+    assert load_in_4bit is True
+    assert load_in_8bit is False
+
+
+def test_nvfp4_disables_both_4bit_and_8bit():
+    config = _make_config(quantization_config = _NVFP4_QCFG_DICT)
+
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = True, verbose = False
+    )
+    assert load_in_4bit is False
+    assert load_in_8bit is False
+
+
+def test_verbose_flag_does_not_raise():
+    config = _make_config(quantization_config = _NVFP4_QCFG_DICT)
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = False, verbose = True
+    )
+    assert load_in_4bit is False
+    assert load_in_8bit is False
+
+
+def test_empty_quantization_config_is_not_quantized():
+    config = _make_config(quantization_config = {})
+    assert get_quant_type(config) is None
+
+    load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+        config, load_in_4bit = True, load_in_8bit = False, verbose = False
+    )
+    assert load_in_4bit is True
+
+
+if __name__ == "__main__":
+    test_nvfp4_config_has_compressed_tensors()
+    test_regular_bnb_config_has_bitsandbytes()
+    test_nvfp4_disables_load_in_4bit()
+    test_bnb_does_not_disable_load_in_4bit()
+    test_no_quantization_config_leaves_settings_unchanged()
+    test_nvfp4_disables_both_4bit_and_8bit()
+    test_verbose_flag_does_not_raise()
+    test_empty_quantization_config_is_not_quantized()
+    print("All tests passed!")
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 945d827573..17d485f9f9 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -2352,7 +2352,20 @@ class FastLlamaModel:
             # Add to kwargs
             kwargs["rope_scaling"] = rope_scaling
 
+        from .loader_utils import check_and_disable_bitsandbytes_loading
+        from unsloth_zoo.utils import get_quant_type
+
+        # Extract load_in_8bit from kwargs if provided
+        load_in_8bit = kwargs.get("load_in_8bit", False)
+
+        # Check and disable bitsandbytes loading if model has non-bitsandbytes quantization
+        load_in_4bit, load_in_8bit, _ckpt_quant_method = check_and_disable_bitsandbytes_loading(
+            model_config, load_in_4bit = load_in_4bit, load_in_8bit = load_in_8bit
+        )
+
         bnb_config = None
+        _ckpt_qcfg = getattr(model_config, "quantization_config", None)
+
         if load_in_4bit:
             llm_int8_skip_modules = SKIP_QUANTIZATION_MODULES.copy()
             if IS_FALCON_H1:
@@ -2371,8 +2384,7 @@ class FastLlamaModel:
             # we pass via kwargs. Merge our skip list into that bundled config
             # so task heads like `score` (for *ForSequenceClassification) stay
             # in the compute dtype. See unslothai/unsloth#5027.
-            _ckpt_qcfg = getattr(model_config, "quantization_config", None)
-            if _ckpt_qcfg is not None:
+            if _ckpt_quant_method == "bitsandbytes" and _ckpt_qcfg is not None:
                 if isinstance(_ckpt_qcfg, dict):
                     _ckpt_skip = list(_ckpt_qcfg.get("llm_int8_skip_modules") or [])
                     for _m in llm_int8_skip_modules:
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index ea18dc125a..d304bb454e 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -30,7 +30,7 @@ from .mapper import (
 # https://github.com/huggingface/transformers/pull/26037 allows 4 bit loading!
 from transformers import __version__ as transformers_version
 from unsloth.models._utils import TorchAOConfig
-from unsloth_zoo.utils import Version
+from unsloth_zoo.utils import Version, get_quant_type
 import gc
 
 transformers_version = Version(transformers_version)
@@ -335,6 +335,47 @@ def _tag_model_with_fp8_torchao_config(model: torch.nn.Module, fp8_mode: str):
         pass
 
 
+def check_and_disable_bitsandbytes_loading(
+    model_config,
+    load_in_4bit = True,
+    load_in_8bit = False,
+    verbose = True,
+):
+    """
+    Check if we should disable bitsandbytes loading (load_in_4bit/load_in_8bit)
+    because the model already has a non-bitsandbytes quantization config.
+    If so, disable BOTH 4bit and 8bit loading and print a warning message.
+
+    Args:
+        model_config: The AutoConfig object from the model
+        load_in_4bit: Whether load_in_4bit is currently enabled
+        load_in_8bit: Whether load_in_8bit is currently enabled
+        verbose: Whether to print warning messages
+
+    Returns:
+        tuple: (load_in_4bit, load_in_8bit, quant_method)
+            load_in_4bit/load_in_8bit will be False if they were disabled
+            quant_method is the detected quantization method or None
+    """
+    quant_method = get_quant_type(model_config)
+
+    if quant_method is None or quant_method == "bitsandbytes":
+        return load_in_4bit, load_in_8bit, quant_method
+
+    # Model has a non-bitsandbytes quantization config (e.g., compressed-tensors, gptq, awq)
+    # We should disable BOTH bitsandbytes loading to avoid config conflicts
+    if load_in_4bit or load_in_8bit:
+        if verbose:
+            print(
+                f"Unsloth: Model already quantized with {quant_method}. "
+                f"Disabling `load_in_4bit` and `load_in_8bit` to avoid quantization config conflict."
+            )
+        load_in_4bit = False
+        load_in_8bit = False
+
+    return load_in_4bit, load_in_8bit, quant_method
+
+
 def _get_fp8_mode_and_check_settings(
     load_in_fp8: Union[bool, str],
     fast_inference: bool,
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index b308a6f1da..3e779a46b1 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -770,6 +770,14 @@ class FastBaseModel:
 
         bnb_config = None
         user_quantization_config = kwargs.get("quantization_config", None)
+
+        # Check if model already has a non-bitsandbytes quantization config (e.g. compressed-tensors/NVFP4)
+        from .loader_utils import check_and_disable_bitsandbytes_loading
+
+        load_in_4bit, load_in_8bit, _ = check_and_disable_bitsandbytes_loading(
+            auto_config, load_in_4bit = load_in_4bit, load_in_8bit = load_in_8bit
+        )
+
         if full_finetuning and (load_in_4bit or load_in_8bit):
             print(
                 "Unsloth: You selected full finetuning support, but 4bit / 8bit is enabled - disabling LoRA / QLoRA."

From ebf28e7e07212bd41756e9b3390073021a3ba1a0 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Mon, 8 Jun 2026 15:18:05 -0300
Subject: [PATCH 114/222] Studio: open the MCP dialog to the server list so
 servers can be managed (#6100)

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 .../src/features/chat/chat-mcp-servers-dialog.tsx   | 13 ++++---------
 .../src/features/chat/mcp-composer-button.tsx       |  5 ++---
 2 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index 93c4c8972c..c706d971ac 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -178,8 +178,6 @@ function HeadersEditor({
 export interface ChatMcpServersDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  /** Open straight into the "add server" form instead of the list view. */
-  openToCreate?: boolean;
 }
 
 type View =
@@ -190,7 +188,6 @@ type View =
 export function ChatMcpServersDialog({
   open,
   onOpenChange,
-  openToCreate = false,
 }: ChatMcpServersDialogProps) {
   const [servers, setServers] = useState<McpServerConfig[]>([]);
   const [loading, setLoading] = useState(false);
@@ -217,12 +214,10 @@ export function ChatMcpServersDialog({
   useEffect(() => {
     if (!open) return;
     refresh();
-    // Land on the create form when opened via "Add custom MCP".
-    if (openToCreate) {
-      setView({ kind: "create" });
-      setForm(EMPTY_FORM);
-    }
-  }, [open, openToCreate, refresh]);
+    // Reset to the list on each open, else a stale create/edit view persists.
+    setView({ kind: "list" });
+    setForm(EMPTY_FORM);
+  }, [open, refresh]);
 
   function startCreate() {
     setView({ kind: "create" });
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index 92d2c319a6..1e59960d07 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -57,7 +57,7 @@ type McpPreset = {
 };
 
 // Keyless remote MCP presets (rate-limited free tiers, no API key).
-// Hugging Face runs anonymously; add a token via "Add custom MCP".
+// Hugging Face runs anonymously; add a token via "Manage MCP servers".
 const MCP_PRESETS: readonly McpPreset[] = [
   {
     id: "context7",
@@ -296,7 +296,7 @@ export function McpComposerButton({
                 setDialogOpen(true);
               }}
             >
-              Add custom MCP
+              Manage MCP servers
             </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>
@@ -331,7 +331,6 @@ export function McpComposerButton({
           // Resync after managing servers.
           if (!next) void refresh();
         }}
-        openToCreate={true}
       />
     </>
   );

From 8292e699e4d4c3d8f079b4cdd695fe7c2e282d32 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 23:07:28 -0700
Subject: [PATCH 115/222] Studio: make code comments and docstrings more
 succinct (#6029)

Trim and tighten code comments and docstrings across studio/ Python. Comment-only: every changed file verified code-identical to main via AST/token comparison.
---
 studio/backend/_platform_compat.py            |   26 +-
 studio/backend/auth/__init__.py               |    4 +-
 studio/backend/auth/authentication.py         |   14 +-
 studio/backend/auth/storage.py                |   85 +-
 studio/backend/colab.py                       |   63 +-
 studio/backend/core/__init__.py               |   14 +-
 studio/backend/core/_torchao_stub.py          |   38 +-
 .../backend/core/data_recipe/huggingface.py   |    4 +-
 .../backend/core/data_recipe/jobs/manager.py  |   12 +-
 studio/backend/core/data_recipe/jobs/parse.py |    4 +-
 studio/backend/core/data_recipe/jobs/types.py |    4 +-
 .../backend/core/data_recipe/jobs/worker.py   |    9 +-
 studio/backend/core/data_recipe/service.py    |   13 +-
 studio/backend/core/export/__init__.py        |    4 +-
 studio/backend/core/export/export.py          |   73 +-
 studio/backend/core/export/orchestrator.py    |  138 +-
 studio/backend/core/export/worker.py          |  110 +-
 studio/backend/core/inference/__init__.py     |    8 +-
 studio/backend/core/inference/_html_to_md.py  |   62 +-
 .../core/inference/anthropic_compat.py        |   38 +-
 studio/backend/core/inference/audio_codecs.py |   28 +-
 .../core/inference/chat_template_helpers.py   |    4 +-
 .../core/inference/external_provider.py       | 1935 ++++++++---------
 studio/backend/core/inference/inference.py    |  340 ++-
 studio/backend/core/inference/key_exchange.py |   24 +-
 studio/backend/core/inference/llama_cpp.py    | 1356 ++++++------
 .../core/inference/llama_server_args.py       |   91 +-
 studio/backend/core/inference/mcp_client.py   |   55 +-
 .../backend/core/inference/mlx_inference.py   |   71 +-
 studio/backend/core/inference/orchestrator.py |  189 +-
 studio/backend/core/inference/pricing.py      |   85 +-
 studio/backend/core/inference/providers.py    |  121 +-
 .../core/inference/safetensors_agentic.py     |   73 +-
 .../core/inference/tool_call_parser.py        |   24 +-
 studio/backend/core/inference/tools.py        |  252 +--
 studio/backend/core/inference/worker.py       |  120 +-
 studio/backend/core/tool_healing.py           |   53 +-
 studio/backend/core/training/__init__.py      |    4 +-
 studio/backend/core/training/trainer.py       |  422 ++--
 studio/backend/core/training/training.py      |   64 +-
 studio/backend/core/training/worker.py        |  398 ++--
 studio/backend/loggers/config.py              |   24 +-
 studio/backend/loggers/handlers.py            |   21 +-
 studio/backend/main.py                        |  185 +-
 studio/backend/models/__init__.py             |    4 +-
 studio/backend/models/auth.py                 |    4 +-
 studio/backend/models/data_recipe.py          |    4 +-
 studio/backend/models/datasets.py             |    4 +-
 studio/backend/models/export.py               |    4 +-
 studio/backend/models/inference.py            |  181 +-
 studio/backend/models/models.py               |    6 +-
 studio/backend/models/providers.py            |    4 +-
 studio/backend/models/responses.py            |    6 +-
 studio/backend/models/training.py             |    4 +-
 studio/backend/models/users.py                |    5 +-
 .../__init__.py                               |    2 +-
 .../data_designer_github_repo_seed/impl.py    |   17 +-
 .../data_designer_github_repo_seed/scraper.py |   11 +-
 .../scraper_impl/gh_client.py                 |   22 +-
 .../scraper_impl/queries.py                   |    6 +-
 .../scraper_impl/scraper.py                   |   14 +-
 .../scraper_impl/state_store.py               |    2 +-
 .../chunking.py                               |    6 +-
 .../requirements/single-env/patch_metadata.py |    4 +-
 studio/backend/routes/auth.py                 |   44 +-
 studio/backend/routes/chat_history.py         |   24 +-
 studio/backend/routes/data_recipe/jobs.py     |  164 +-
 studio/backend/routes/data_recipe/seed.py     |    4 +-
 studio/backend/routes/data_recipe/validate.py |   18 +-
 studio/backend/routes/datasets.py             |   78 +-
 studio/backend/routes/export.py               |  106 +-
 studio/backend/routes/inference.py            | 1199 +++++-----
 studio/backend/routes/mcp_servers.py          |   28 +-
 studio/backend/routes/models.py               |  487 ++---
 studio/backend/routes/providers.py            |   59 +-
 studio/backend/routes/training.py             |   74 +-
 studio/backend/run.py                         |  266 ++-
 studio/backend/startup_banner.py              |   10 +-
 studio/backend/storage/mcp_servers_db.py      |    2 +-
 studio/backend/storage/providers_db.py        |    6 +-
 studio/backend/storage/studio_db.py           |   65 +-
 studio/backend/tests/conftest.py              |   42 +-
 .../backend/tests/test_anthropic_cache_ttl.py |   32 +-
 .../backend/tests/test_anthropic_citations.py |    9 +-
 .../tests/test_anthropic_citations_edge.py    |   77 +-
 .../tests/test_anthropic_code_execution.py    |   44 +-
 .../tests/test_anthropic_compaction.py        |   86 +-
 .../test_anthropic_fast_mode_and_refusal.py   |   16 +-
 .../tests/test_anthropic_fast_mode_edge.py    |   17 +-
 .../backend/tests/test_anthropic_messages.py  |   45 +-
 .../test_anthropic_thinking_translation.py    |   45 +-
 .../tests/test_anthropic_tool_versions.py     |   27 +-
 .../backend/tests/test_anthropic_web_fetch.py |   60 +-
 .../tests/test_audio_token_detection.py       |    7 +-
 .../tests/test_browse_folders_route.py        |    3 +-
 .../tests/test_cache_case_resolution.py       |    4 +-
 .../backend/tests/test_cached_gguf_routes.py  |   32 +-
 .../tests/test_chat_history_storage.py        |   10 +-
 .../test_cleanup_cancelled_checkpoints.py     |   10 +-
 studio/backend/tests/test_cpu_threads.py      |    4 +-
 studio/backend/tests/test_desktop_auth.py     |   14 +-
 .../backend/tests/test_detect_mmproj_file.py  |    2 +-
 .../backend/tests/test_export_log_cursor.py   |   78 +-
 .../test_external_provider_usage_chunk.py     |   27 +-
 .../backend/tests/test_frontend_resolution.py |   35 +-
 studio/backend/tests/test_gemini_provider.py  |  841 ++++---
 studio/backend/tests/test_gguf_metadata.py    |    6 +-
 .../tests/test_gguf_reload_inheritance.py     |    9 +-
 studio/backend/tests/test_gguf_routing.py     |   17 +-
 studio/backend/tests/test_gpu_selection.py    |    4 +-
 .../tests/test_gpu_selection_sandbox.py       |   32 +-
 studio/backend/tests/test_host_defaults.py    |   18 +-
 .../tests/test_index_bootstrap_origin.py      |    9 +-
 .../test_index_bootstrap_origin_extra.py      |   34 +-
 .../tests/test_inference_model_validation.py  |    7 +-
 .../backend/tests/test_kv_cache_estimation.py |  194 +-
 .../test_lemonade_llamacpp_rocm_bins_mock.py  |   43 +-
 .../test_llama_cpp_cache_aware_disk_check.py  |   44 +-
 .../tests/test_llama_cpp_context_fit.py       |   73 +-
 .../backend/tests/test_llama_cpp_freshness.py |   16 +-
 .../tests/test_llama_cpp_load_progress.py     |   38 +-
 .../test_llama_cpp_load_progress_live.py      |   44 +-
 .../test_llama_cpp_load_progress_matrix.py    |   77 +-
 .../test_llama_cpp_max_context_threshold.py   |   39 +-
 .../tests/test_llama_cpp_mtp_detection.py     |   63 +-
 .../tests/test_llama_cpp_no_context_shift.py  |   51 +-
 ..._llama_cpp_start_failure_classification.py |   12 +-
 .../tests/test_llama_cpp_wait_for_health.py   |   52 +-
 .../test_llama_cpp_wait_for_vram_settle.py    |   46 +-
 .../test_llama_cpp_windows_nvidia_path.py     |   67 +-
 .../backend/tests/test_llama_server_args.py   |   50 +-
 .../tests/test_log_filter_no_truncation.py    |    6 +-
 studio/backend/tests/test_login_rate_limit.py |   34 +-
 studio/backend/tests/test_mcp_servers.py      |   65 +-
 .../tests/test_mcp_stdio_improvements.py      |   18 +-
 studio/backend/tests/test_mcp_stdio_pr5863.py |   28 +-
 studio/backend/tests/test_middleware.py       |   18 +-
 .../tests/test_mlx_inference_backend.py       |   18 +-
 .../backend/tests/test_multimodal_document.py |   96 +-
 .../tests/test_native_context_length.py       |   30 +-
 .../tests/test_offline_gguf_cache_fallback.py |   78 +-
 .../tests/test_offline_inference_parent.py    |    2 +-
 .../tests/test_openai_citation_markers.py     |   23 +-
 .../test_openai_citation_markers_edge.py      |   57 +-
 .../tests/test_openai_code_execution.py       |   63 +-
 .../backend/tests/test_openai_compaction.py   |   73 +-
 .../tests/test_openai_container_crud.py       |   35 +-
 .../tests/test_openai_image_generation.py     |   27 +-
 .../test_openai_responses_translation.py      |   46 +-
 .../tests/test_openai_tool_passthrough.py     |   67 +-
 .../test_openai_tool_result_fallbacks.py      |   12 +-
 studio/backend/tests/test_pricing.py          |   14 +-
 studio/backend/tests/test_pricing_edge.py     |   46 +-
 studio/backend/tests/test_providers_api.py    |   72 +-
 studio/backend/tests/test_pytorch_mirror.py   |    6 +-
 .../test_recommended_folders_permission.py    |   39 +-
 studio/backend/tests/test_responses_api.py    |   29 +-
 .../tests/test_responses_tool_passthrough.py  |   76 +-
 studio/backend/tests/test_rocm_oom_guard.py   |   20 +-
 .../test_safetensors_capability_advertise.py  |   34 +-
 .../tests/test_safetensors_tool_loop.py       |  100 +-
 studio/backend/tests/test_sandbox_tools.py    |   65 +-
 studio/backend/tests/test_studio_api.py       |   70 +-
 .../tests/test_studio_train_validation.py     |    6 +-
 .../backend/tests/test_tool_policy_gates.py   |    4 +-
 studio/backend/tests/test_tool_xml_strip.py   |   12 +-
 .../tests/test_training_worker_flash_attn.py  |  237 +-
 .../tests/test_transformers_version.py        |   27 +-
 studio/backend/tests/test_utils.py            |   13 +-
 studio/backend/tests/test_vision_cache.py     |   73 +-
 studio/backend/tests/test_vram_estimation.py  |   55 +-
 .../tests/test_windows_gpu_detection_mock.py  |   71 +-
 studio/backend/utils/cache_cleanup.py         |   25 +-
 studio/backend/utils/cpu_threads.py           |    6 +-
 studio/backend/utils/datasets/__init__.py     |    9 +-
 .../backend/utils/datasets/chat_templates.py  |   58 +-
 .../backend/utils/datasets/data_collators.py  |   35 +-
 .../utils/datasets/dataset_none_detect.py     |   90 +-
 .../backend/utils/datasets/dataset_utils.py   |   69 +-
 .../utils/datasets/format_conversion.py       |  116 +-
 .../utils/datasets/format_detection.py        |  161 +-
 studio/backend/utils/datasets/llm_assist.py   |   56 +-
 .../backend/utils/datasets/model_mappings.py  |   10 +-
 .../backend/utils/datasets/vlm_processing.py  |   29 +-
 studio/backend/utils/hardware/__init__.py     |    8 +-
 studio/backend/utils/hardware/amd.py          |  131 +-
 studio/backend/utils/hardware/hardware.py     |  302 ++-
 studio/backend/utils/hardware/nvidia.py       |   12 +-
 .../backend/utils/hardware/vram_estimation.py |  171 +-
 .../utils/inference/inference_config.py       |   50 +-
 studio/backend/utils/llama_cpp_freshness.py   |    2 +-
 studio/backend/utils/models/checkpoints.py    |   18 +-
 studio/backend/utils/models/gguf_metadata.py  |   25 +-
 studio/backend/utils/models/model_config.py   |  376 ++--
 studio/backend/utils/paths/__init__.py        |    8 +-
 studio/backend/utils/paths/path_utils.py      |   27 +-
 studio/backend/utils/paths/storage_roots.py   |   49 +-
 studio/backend/utils/studio_version.py        |    4 +-
 studio/backend/utils/subprocess_compat.py     |    4 +-
 studio/backend/utils/transformers_version.py  |  105 +-
 studio/backend/utils/update_status.py         |   11 +-
 studio/backend/utils/utils.py                 |   15 +-
 studio/backend/utils/wheel_utils.py           |   10 +-
 studio/install_llama_prebuilt.py              |  448 ++--
 studio/install_python_stack.py                |  356 ++-
 205 files changed, 8016 insertions(+), 8863 deletions(-)

diff --git a/studio/backend/_platform_compat.py b/studio/backend/_platform_compat.py
index 490e1820d7..37bf5e3fb5 100644
--- a/studio/backend/_platform_compat.py
+++ b/studio/backend/_platform_compat.py
@@ -4,17 +4,17 @@
 """
 Compatibility shim for Anaconda/conda-forge Python builds.
 
-Anaconda modifies sys.version to include distributor metadata between pipe
-characters, e.g. '3.12.4 | packaged by Anaconda, Inc. | (main, ...) [MSC ...]'.
-Python's platform._sys_version() has a hardcoded regex that cannot parse this,
-raising ValueError. CPython closed this as "not planned" (cpython#102396).
+Anaconda puts distributor metadata between pipes in sys.version, e.g.
+'3.12.4 | packaged by Anaconda, Inc. | (main, ...) [MSC ...]'. The hardcoded
+regex in platform._sys_version() can't parse this and raises ValueError;
+CPython closed it as "not planned" (cpython#102396).
 
-This module seeds platform._sys_version_cache so the stdlib parser never sees
-the problematic string, fixing the import chain:
+We seed platform._sys_version_cache so the stdlib parser never sees the bad
+string, fixing the import chain:
     structlog -> rich.pretty -> attrs._compat -> platform.python_implementation()
 
-Import this module before any library imports that may trigger the above chain.
-Safe to import multiple times (no-op if cache is already seeded or no pipes).
+Import before any library that may trigger that chain. Idempotent (no-op if the
+cache is already seeded or there are no pipes).
 """
 
 import platform
@@ -29,12 +29,12 @@ def _seed_sys_version_cache() -> None:
     # Strip paired |...| segments (Anaconda, conda-forge metadata)
     cleaned = re.sub(r"\s*\|[^|]*\|\s*", " ", raw).strip()
 
-    # Format B: "ver (build) | label | (build_dup) \n[compiler]"
-    # After pipe-strip, two consecutive (...) groups remain; drop the second.
+    # Format B: "ver (build) | label | (build_dup) \n[compiler]" leaves two
+    # consecutive (...) groups after pipe-strip; drop the second.
     cleaned = re.sub(r"(\([^)]*\))\s+\([^)]*\)", r"\1", cleaned)
 
     if "|" in cleaned:
-        # Unpaired pipe remaining -- keep version + everything from "(" onward
+        # Unpaired pipe left: keep version + everything from "(" onward
         m = re.match(r"([\w.+]+)\s*", cleaned)
         p = cleaned.find("(")
         if m and p > 0:
@@ -47,9 +47,9 @@ def _seed_sys_version_cache() -> None:
     try:
         result = platform._sys_version(cleaned)
     except ValueError:
-        return  # Cleaning didn't produce a parseable string; don't make things worse
+        return  # Still unparsable; don't make things worse
 
-    # Seed the cache so future calls with the raw string skip parsing entirely
+    # Seed the cache so future calls with the raw string skip parsing
     cache = getattr(platform, "_sys_version_cache", None)
     if isinstance(cache, dict):
         cache[raw] = result
diff --git a/studio/backend/auth/__init__.py b/studio/backend/auth/__init__.py
index b3e1a8a9c0..a63d5303d4 100644
--- a/studio/backend/auth/__init__.py
+++ b/studio/backend/auth/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Authentication module for JWT-based auth with SQLite storage.
-"""
+"""Authentication module for JWT-based auth with SQLite storage."""
 
 from .authentication import (
     create_access_token,
diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index bb5b873e65..6509cb6825 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -58,7 +58,7 @@ def create_access_token(
     """
     Create a signed JWT for the given subject (e.g. username).
 
-    Tokens are valid across restarts because the signing secret is stored in SQLite.
+    Valid across restarts: the signing secret is stored in SQLite.
     """
     to_encode = {"sub": subject}
     if desktop:
@@ -100,7 +100,7 @@ def create_refresh_token(subject: str, *, desktop: bool = False) -> str:
     """
     Create a random refresh token, store its hash in SQLite, and return it.
 
-    Refresh tokens are opaque (not JWTs) and expire after REFRESH_TOKEN_EXPIRE_DAYS.
+    Refresh tokens are opaque (not JWTs); expire after REFRESH_TOKEN_EXPIRE_DAYS.
     """
     token = secrets.token_urlsafe(48)
     expires_at = datetime.now(timezone.utc) + timedelta(days = REFRESH_TOKEN_EXPIRE_DAYS)
@@ -112,8 +112,8 @@ def refresh_access_token(refresh_token: str) -> Tuple[Optional[str], Optional[st
     """
     Validate a refresh token and issue a new access token.
 
-    The refresh token itself is NOT consumed — it stays valid until expiry.
-    Returns a new access_token or None if the refresh token is invalid/expired.
+    The refresh token is NOT consumed; it stays valid until expiry.
+    Returns a new access_token, or None if the refresh token is invalid/expired.
     """
     verified = verify_refresh_token(refresh_token)
     if verified is None:
@@ -128,7 +128,7 @@ def refresh_access_token(refresh_token: str) -> Tuple[Optional[str], Optional[st
 
 def reload_secret() -> None:
     """
-    Keep legacy API compatibility for callers expecting auth storage init.
+    Legacy API compat for callers expecting auth storage init.
 
     Auth now resolves the current signing secret directly from SQLite.
     """
@@ -157,9 +157,9 @@ async def _get_current_subject(
     credentials: HTTPAuthorizationCredentials, *, allow_password_change: bool
 ) -> str:
     """
-    FastAPI dependency to validate the JWT and return the subject.
+    FastAPI dependency: validate the JWT and return the subject.
 
-    Use this as a dependency on routes that should be protected, e.g.:
+    Use as a dependency on protected routes, e.g.:
 
         @router.get("/secure")
         async def secure_endpoint(current_subject: str = Depends(get_current_subject)):
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index 0e34a0cf28..42e2de7450 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-SQLite storage for authentication data (user credentials + JWT secret).
-"""
+"""SQLite storage for auth data (user credentials + JWT secret)."""
 
 import hashlib
 import os
@@ -17,20 +15,19 @@ from utils.paths import auth_db_path, ensure_dir
 DB_PATH = auth_db_path()
 DEFAULT_ADMIN_USERNAME = "unsloth"
 
-# Plaintext bootstrap password file — lives beside auth.db, deleted on
-# first password change so the credential never lingers on disk.
+# Plaintext bootstrap password file beside auth.db, deleted on first password
+# change so the credential never lingers on disk.
 _BOOTSTRAP_PW_PATH = DB_PATH.parent / ".bootstrap_password"
 
-# In-process cache so we don't re-read the file on every HTML serve.
+# In-process cache to avoid re-reading the file on every HTML serve.
 _bootstrap_password: Optional[str] = None
 
 
 def generate_bootstrap_password() -> str:
     """Generate a 4-word diceware passphrase and persist it to disk.
 
-    The passphrase is written to ``_BOOTSTRAP_PW_PATH`` so that it
-    survives server restarts (the DB only stores the *hash*).  On
-    subsequent calls / restarts, the persisted value is returned.
+    Written to ``_BOOTSTRAP_PW_PATH`` so it survives restarts (the DB only
+    stores the *hash*). Later calls / restarts return the persisted value.
     """
     global _bootstrap_password
 
@@ -51,7 +48,7 @@ def generate_bootstrap_password() -> str:
         options = diceware.handle_options(args = ["-n", "4", "-d", "", "-c"])
     )
 
-    # Persist so the *same* passphrase is used if the server restarts
+    # Persist so the *same* passphrase is reused if the server restarts
     # before the user changes the password.
     ensure_dir(_BOOTSTRAP_PW_PATH.parent)
     _BOOTSTRAP_PW_PATH.write_text(_bootstrap_password)
@@ -88,21 +85,19 @@ def clear_bootstrap_password() -> None:
 
 
 def _hash_token(token: str) -> str:
-    """SHA-256 hash helper used for refresh token storage.
+    """SHA-256 hash helper for refresh token storage.
 
-    Plain SHA-256 is intentional here: refresh tokens are high-entropy
-    random strings from ``secrets.token_urlsafe(48)`` (384 bits of
-    entropy), so a slow KDF (Argon2 / bcrypt / PBKDF2) provides zero
-    additional security — no attacker can brute-force 2^384 regardless
-    of hash speed — while adding tens of ms of CPU to every refresh.
-    See the OWASP Password Storage Cheat Sheet on fast-vs-slow hashing
-    of high-entropy inputs.
+    Plain SHA-256 is intentional: refresh tokens are high-entropy random
+    strings from ``secrets.token_urlsafe(48)`` (384 bits), so a slow KDF
+    (Argon2 / bcrypt / PBKDF2) adds zero security (2^384 is unbruteforceable
+    regardless of hash speed) while costing tens of ms per refresh. See the
+    OWASP Password Storage Cheat Sheet on hashing high-entropy inputs.
 
-    API keys use the separate ``_pbkdf2_api_key`` helper below, which
-    runs PBKDF2-HMAC-SHA256 with a persistent server-side salt — not
-    for cryptographic reasons (128-bit random tokens don't need slow
-    hashing), but because CodeQL's ``py/weak-sensitive-data-hashing``
-    query mislabels API keys as passwords and demands a KDF.
+    API keys use the separate ``_pbkdf2_api_key`` helper (PBKDF2-HMAC-SHA256
+    with a persistent server-side salt) — not for crypto reasons (128-bit
+    random tokens don't need slow hashing) but because CodeQL's
+    ``py/weak-sensitive-data-hashing`` query mislabels them as passwords and
+    demands a KDF.
     """
     return hashlib.sha256(token.encode("utf-8")).hexdigest()
 
@@ -176,22 +171,20 @@ def get_connection() -> sqlite3.Connection:
 
 # ── API-key PBKDF2 salt ────────────────────────────────────────────────
 #
-# Module-level cache for the persistent API-key PBKDF2 salt. Populated
-# lazily on first use via ``_get_or_create_api_key_pbkdf2_salt``. Not
-# protected by a lock because (a) the ``INSERT OR IGNORE`` provides
-# atomicity at the SQLite layer and (b) concurrent populations converge
-# on the same value, so the worst case is a harmless duplicate read on
-# startup.
+# Module-level cache for the persistent API-key PBKDF2 salt, populated lazily
+# via ``_get_or_create_api_key_pbkdf2_salt``. No lock needed: (a) ``INSERT OR
+# IGNORE`` is atomic at the SQLite layer and (b) concurrent populations
+# converge on the same value, so the worst case is a harmless duplicate read
+# on startup.
 _api_key_pbkdf2_salt_cache: Optional[bytes] = None
 
 
 def _get_or_create_api_key_pbkdf2_salt() -> bytes:
     """Return the persistent API-key PBKDF2 salt, generating it once if missing.
 
-    Stored as a hex-encoded 32-byte random value in the ``app_secrets``
-    table under key ``"api_key_pbkdf2_salt"``. Regenerated only if the row
-    is missing (i.e. fresh install, or operator manually deleted the row
-    and accepts invalidating existing API keys).
+    Stored as a hex-encoded 32-byte random value in ``app_secrets`` under key
+    ``"api_key_pbkdf2_salt"``. Regenerated only when the row is missing (fresh
+    install, or operator deleted it and accepts invalidating existing keys).
     """
     global _api_key_pbkdf2_salt_cache
     if _api_key_pbkdf2_salt_cache is not None:
@@ -233,22 +226,18 @@ _DESKTOP_SECRET_CREATED_AT_KEY = "desktop_secret_created_at"
 def _pbkdf2_api_key(raw_key: str) -> str:
     """PBKDF2-HMAC-SHA256 an API key with a persistent server-side salt.
 
-    Used for API-key storage ONLY, not refresh tokens. Matches the
-    PBKDF2 algorithm + iteration count used by the password hasher in
-    ``auth/hashing.py`` so the codebase is consistent on which KDF it
-    uses for credential storage.
+    For API-key storage ONLY, not refresh tokens. Matches the PBKDF2 algorithm
+    + iteration count used by the password hasher in ``auth/hashing.py`` so
+    the codebase is consistent on its credential-storage KDF.
 
-    Notes on why a slow KDF here is *only* a CodeQL appeasement and
-    *not* a cryptographic requirement: API keys are cryptographically
-    random 128-bit tokens (via ``secrets.token_hex``), so brute force
-    against 2^128 is infeasible regardless of hash speed. CodeQL's
-    ``py/weak-sensitive-data-hashing`` query mislabels these tokens as
-    "password" sensitive data and then demands a KDF from its
-    allowlist (Argon2 / scrypt / bcrypt / PBKDF2). Per the query's
-    own recommendation page we use PBKDF2. The persistent salt is
-    still loaded from ``app_secrets`` so an attacker dumping the
-    ``api_keys`` table alone cannot derive hashes for candidate
-    tokens without also obtaining the salt row.
+    The slow KDF here is *only* a CodeQL appeasement, not a crypto
+    requirement: API keys are random 128-bit tokens (``secrets.token_hex``),
+    so brute force against 2^128 is infeasible regardless of hash speed.
+    CodeQL's ``py/weak-sensitive-data-hashing`` query mislabels them as
+    "password" data and demands a KDF from its allowlist (Argon2 / scrypt /
+    bcrypt / PBKDF2); we use PBKDF2 per its recommendation page. The salt is
+    still loaded from ``app_secrets`` so dumping the ``api_keys`` table alone
+    can't derive hashes for candidate tokens without the salt row.
     """
     salt = _get_or_create_api_key_pbkdf2_salt()
     dk = hashlib.pbkdf2_hmac(
diff --git a/studio/backend/colab.py b/studio/backend/colab.py
index c3a1e03fbe..1f618a34ab 100644
--- a/studio/backend/colab.py
+++ b/studio/backend/colab.py
@@ -2,15 +2,14 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Colab-specific helpers for running Unsloth Studio.
-Uses Colab's built-in proxy - no external tunneling needed!
+Colab helpers for Unsloth Studio. Uses Colab's built-in proxy.
 """
 
 from pathlib import Path
 import sys
 
-# Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
-# any library imports that trigger attrs -> rich -> structlog -> platform crash.
+# Anaconda/conda-forge Python: seed platform._sys_version_cache before any
+# import that triggers attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
 _backend_dir = str(Path(__file__).parent)
 if _backend_dir not in sys.path:
@@ -25,11 +24,10 @@ logger = get_logger(__name__)
 
 def get_colab_url(port: int = 8888) -> str:
     """
-    Get the actual Colab proxy URL for a port.
+    Get the Colab proxy URL for a port.
 
-    Retries up to 3 times and validates that the result is a real HTTPS Colab
-    URL before returning.  Falls back to http://localhost:{port} only when all
-    attempts fail.
+    Retries up to 3 times, validating the result is a real HTTPS Colab URL.
+    Falls back to http://localhost:{port} only when all attempts fail.
     """
     import time as _time
 
@@ -43,7 +41,7 @@ def get_colab_url(port: int = 8888) -> str:
     for attempt in range(3):
         try:
             url = eval_js(f"google.colab.kernel.proxyPort({port})", timeout_sec = 10)
-            # A valid Colab proxy URL starts with https:// and embeds the port.
+            # Valid Colab proxy URL starts with https:// and embeds the port.
             if url and isinstance(url, str) and url.startswith("https://") and str(port) in url:
                 return url.rstrip("/")
         except Exception as e:
@@ -61,16 +59,16 @@ def get_colab_url(port: int = 8888) -> str:
 def show_link(port: int = 8888, *, _url: "str | None" = None):
     """Display a styled clickable link to the UI.
 
-    *_url* is an optional pre-fetched Colab proxy URL. When omitted,
-    ``get_colab_url(port)`` is called internally. Pass it from
-    ``_show_and_embed`` to avoid a second ``eval_js`` round-trip.
+    *_url* is an optional pre-fetched Colab proxy URL; when omitted,
+    ``get_colab_url(port)`` is called. Pass it from ``_show_and_embed`` to
+    avoid a second ``eval_js`` round-trip.
     """
     from IPython.display import display, HTML
 
     url = _url if _url is not None else get_colab_url(port)
 
-    # Build a truncated display URL. Wrap in try/except so an unexpected URL
-    # shape never prevents the link from rendering.
+    # Truncated display URL. try/except so an unexpected URL shape never
+    # prevents the link from rendering.
     try:
         port_prefix = f"{port}-"
         idx = url.index(port_prefix)
@@ -79,8 +77,7 @@ def show_link(port: int = 8888, *, _url: "str | None" = None):
     except (ValueError, IndexError):
         short_url = url
 
-    # Also emit a plain-text line so the URL is visible even if HTML display
-    # is suppressed or fails.
+    # Plain-text line so the URL is visible even if HTML display fails.
     logger.info(f"🌐 Unsloth Studio URL: {url}")
 
     html = f"""
@@ -123,12 +120,10 @@ def _is_studio_healthy(port: int, timeout: float = 2.0) -> bool:
 def _show_and_embed(port: int):
     """Embed the Studio inline for *port* with a branded header bar.
 
-    Fetches the Colab proxy URL once (registering the port with Colab's
-    reverse-proxy at the same time) then renders a header bar + full-height
-    iframe as a single HTML block.
-
-    Falls back to ``serve_kernel_port_as_iframe`` if ``IPython.display.HTML``
-    is unavailable for any reason.
+    Fetches the Colab proxy URL once (also registering the port with Colab's
+    reverse-proxy) then renders a header bar + full-height iframe as one HTML
+    block. Falls back to ``serve_kernel_port_as_iframe`` if
+    ``IPython.display.HTML`` is unavailable.
     """
     url = get_colab_url(port)
     logger.info(f"🌐 Unsloth Studio URL: {url}")
@@ -138,7 +133,7 @@ def _show_and_embed(port: int):
 
         iframe_id = f"unsloth-studio-{port}"
 
-        # Truncated URL shown in the header — best-effort, falls back to full URL.
+        # Truncated header URL — best-effort, falls back to full URL.
         try:
             port_prefix = f"{port}-"
             idx = url.index(port_prefix)
@@ -188,8 +183,8 @@ def start(port: int = 8888):
     logger.info("🦥 Starting Unsloth Studio...")
 
     # --- Fast path: Studio is already running (cell re-run) ---
-    # Re-launching would either collide on the port or silently shift to a new
-    # port and confuse the user.  Just re-show the link and iframe instead.
+    # Re-launching would collide on the port or silently shift to a new one.
+    # Just re-show the link and iframe instead.
     if _is_studio_healthy(port):
         logger.info(f"   Studio is already running on port {port} — reusing existing server.")
         _show_and_embed(port)
@@ -222,16 +217,16 @@ def start(port: int = 8888):
         logger.error(f"❌ Unsloth Studio failed to start: {exc}")
         return
 
-    # run_server auto-increments the port when the requested one is already in
-    # use (e.g. Jupyter occupying 8888). Read back the actual bound port so the
-    # Colab proxy URL and iframe always point at the right place.
+    # run_server auto-increments the port if the requested one is in use (e.g.
+    # Jupyter on 8888). Read back the bound port so the Colab proxy URL and
+    # iframe point at the right place.
     actual_port: int = getattr(getattr(app, "state", None), "server_port", None) or port
 
     logger.info(f"   Server started on port {actual_port}!")
 
-    # Poll health endpoint to confirm the server is truly reachable before
-    # showing the link and registering the iframe — avoids the race where
-    # ready_event fires but the process hasn't finished binding.
+    # Poll health endpoint to confirm reachability before showing the link and
+    # registering the iframe — avoids the race where ready_event fires but the
+    # process hasn't finished binding.
     import urllib.request
 
     server_ready = False
@@ -252,9 +247,9 @@ def start(port: int = 8888):
 
     _show_and_embed(actual_port)
 
-    # Keep kernel alive so the daemon server thread stays running.
-    # Handle KeyboardInterrupt cleanly so the user gets a readable message
-    # rather than a raw traceback when they interrupt the cell.
+    # Keep kernel alive so the daemon server thread stays running. Handle
+    # KeyboardInterrupt cleanly so interrupting the cell gives a readable
+    # message, not a raw traceback.
     try:
         for _ in range(10000):
             time.sleep(300)
diff --git a/studio/backend/core/__init__.py b/studio/backend/core/__init__.py
index 2ba9d5c65c..5400ef0d35 100644
--- a/studio/backend/core/__init__.py
+++ b/studio/backend/core/__init__.py
@@ -4,18 +4,16 @@
 """
 Unified core module for Unsloth backend
 
-Imports are LAZY (via __getattr__) so that training subprocesses can
-import core.training.worker without pulling in heavy ML dependencies
-like unsloth, transformers, or torch before the version activation
-code has a chance to run.
+Imports are LAZY (via __getattr__) so training subprocesses can import
+core.training.worker without pulling in heavy ML deps (unsloth, transformers,
+torch) before the version-activation code runs.
 """
 
 import sys
 from pathlib import Path
 
-# Ensure the backend directory is on sys.path so that bare "from utils.*"
-# imports used throughout the backend work when core is imported as a package
-# (e.g. from the CLI: "from studio.backend.core import ModelConfig").
+# Put the backend dir on sys.path so bare "from utils.*" imports work when core
+# is imported as a package (e.g. CLI: "from studio.backend.core import ModelConfig").
 _backend_dir = str(Path(__file__).resolve().parent.parent)
 if _backend_dir not in sys.path:
     sys.path.insert(0, _backend_dir)
@@ -69,7 +67,7 @@ def __getattr__(name):
         globals()["TrainingProgress"] = TrainingProgress
         return globals()[name]
 
-    # Config (from utils.models)
+    # Config (utils.models)
     if name in (
         "is_vision_model",
         "ModelConfig",
diff --git a/studio/backend/core/_torchao_stub.py b/studio/backend/core/_torchao_stub.py
index 217c25fda3..4a62004bac 100644
--- a/studio/backend/core/_torchao_stub.py
+++ b/studio/backend/core/_torchao_stub.py
@@ -6,15 +6,14 @@
 torchao (pulled in by transformers.quantizers) imports
 torch.distributed._functional_collectives at module level, which imports
 distributed_c10d.py unconditionally — that file crashes on Windows ROCm because
-torch._C._distributed_c10d (the RCCL backend) is absent.
-torch/distributed/__init__.py itself is guarded by `if is_available()` so
-`import torch.distributed` alone is safe; the crash only comes via torchao's
-import chain.  Stubbing torchao short-circuits it entirely.
+torch._C._distributed_c10d (the RCCL backend) is absent. `import
+torch.distributed` alone is safe (guarded by `if is_available()`); the crash
+only comes via torchao's import chain, so stubbing torchao short-circuits it.
 _StubSubpackageFinder handles any depth of torchao.xxx.yyy imports.
 
-This logic used to be duplicated inline inside run_export_process() and
-run_training_process(); it now lives here so both worker subprocesses call the
-single `install_torchao_windows_rocm_stub()` entrypoint before importing
+Previously duplicated inline in run_export_process() and run_training_process();
+now both worker subprocesses call the single
+`install_torchao_windows_rocm_stub()` entrypoint before importing
 transformers / unsloth_zoo.
 """
 
@@ -28,9 +27,9 @@ import importlib.machinery
 _STUB_SENTINEL = object()
 
 
-# Metaclass for stub types so that isinstance(x, StubClass) returns False
-# instead of raising TypeError ("arg 2 must be a type").
-# peft/tuners/lora/torchao.py does:
+# Metaclass for stub types so isinstance(x, StubClass) returns False instead
+# of raising TypeError ("arg 2 must be a type"). peft/tuners/lora/torchao.py
+# does:
 #   from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
 #   isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))
 # If those names resolve to stub modules rather than types, isinstance() raises.
@@ -71,8 +70,8 @@ def _make_mod_stub(mod_name):
     ):
         if attr.startswith("__"):
             raise AttributeError(attr)
-        # Return a stub CLASS (not a module) so that isinstance(x, attr)
-        # works and returns False instead of raising TypeError.
+        # Return a stub CLASS (not a module) so isinstance(x, attr) returns
+        # False instead of raising TypeError.
         child = _make_stub_type(f"{_n}.{attr}")
         setattr(_m, attr, child)
         return child
@@ -114,14 +113,13 @@ class _StubSubpackageFinder(importlib.abc.MetaPathFinder):
 def install_torchao_windows_rocm_stub() -> None:
     """Pre-stub torchao on Windows ROCm so transformers/peft imports don't crash.
 
-    No-op on every other platform (Windows CUDA included — there torchao is real
-    and shadowing it would break torchao-based quantization paths). Must run
-    before any import of transformers / unsloth_zoo. Safe to call once per worker
-    process.
+    No-op on every other platform (incl. Windows CUDA — there torchao is real
+    and shadowing it would break torchao quantization paths). Must run before
+    any import of transformers / unsloth_zoo. Safe to call once per worker.
     """
     # Gate on the active torch runtime, not env-var presence -- HIP_PATH /
-    # ROCM_PATH stay set after a user installs the HIP SDK and reverts to a
-    # CUDA torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
+    # ROCM_PATH stay set after installing the HIP SDK and reverting to a CUDA
+    # torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
     # but still encode "rocm" in torch.__version__, so accept either.
     _is_win32_rocm = False
     if sys.platform == "win32":
@@ -135,8 +133,8 @@ def install_torchao_windows_rocm_stub() -> None:
         except Exception:
             pass
     if _is_win32_rocm:
-        # Register the finder only on Windows ROCm -- on other platforms there
-        # are no stub modules seeded, so appending is a pure accumulation.
+        # Register the finder only on Windows ROCm -- elsewhere no stub modules
+        # are seeded, so appending would be pure accumulation.
         sys.meta_path.append(_StubSubpackageFinder())
         # Seed torchao top-level + key submodules; the finder handles the rest.
         for _tao_name in (
diff --git a/studio/backend/core/data_recipe/huggingface.py b/studio/backend/core/data_recipe/huggingface.py
index d5a6db6baf..3012fed1ea 100644
--- a/studio/backend/core/data_recipe/huggingface.py
+++ b/studio/backend/core/data_recipe/huggingface.py
@@ -95,8 +95,8 @@ def publish_recipe_dataset(
             tags = None,
         )
         card.text = card.text.replace(_DATA_DESIGNER_FOOTER, _UNSLOTH_STUDIO_FOOTER)
-        # Data Designer currently drops the explicit token when pushing the
-        # dataset card. Push it ourselves so auth stays request-local.
+        # Data Designer drops the explicit token when pushing the dataset
+        # card, so push it ourselves to keep auth request-local.
         card.push_to_hub(repo_id, token = hf_token, repo_type = "dataset")
 
         client._upload_main_dataset_files(
diff --git a/studio/backend/core/data_recipe/jobs/manager.py b/studio/backend/core/data_recipe/jobs/manager.py
index 75dc1efb9c..71c2b7468f 100644
--- a/studio/backend/core/data_recipe/jobs/manager.py
+++ b/studio/backend/core/data_recipe/jobs/manager.py
@@ -134,8 +134,8 @@ class JobManager:
 
         ``internal_api_key_id`` is the row id of a workflow-scoped
         sk-unsloth-* key minted by the route layer for local providers.
-        JobManager revokes it when the job reaches a terminal state so the
-        key's live window is no longer than the run.
+        JobManager revokes it on terminal state so the key's live window is
+        no longer than the run.
         """
         llm_columns = recipe.get("columns") or []
         llm_column_count = 0
@@ -202,7 +202,7 @@ class JobManager:
             return True
 
     def get_status(self, job_id: str) -> dict | None:
-        """UI friendly snapshot that we need. Alternative to sse kinda of and structured"""
+        """UI-friendly structured snapshot; an alternative to SSE."""
         with self._lock:
             if self._job is None or self._job.job_id != job_id:
                 return None
@@ -537,9 +537,9 @@ class JobManager:
     def _retire_workflow_key(self, job: Job) -> None:
         """Revoke the workflow-scoped sk-unsloth-* key, if one was minted.
 
-        Best-effort: revocation failures are swallowed. The key would
-        expire on its own after 24h, so a missed revoke is a latency
-        concern, not a correctness one.
+        Best-effort: revocation failures are swallowed. The key expires on
+        its own after 24h, so a missed revoke is a latency concern, not a
+        correctness one.
         """
         key_id = getattr(job, "internal_api_key_id", None)
         if not key_id:
diff --git a/studio/backend/core/data_recipe/jobs/parse.py b/studio/backend/core/data_recipe/jobs/parse.py
index 8ca3702edd..e37d7064ed 100644
--- a/studio/backend/core/data_recipe/jobs/parse.py
+++ b/studio/backend/core/data_recipe/jobs/parse.py
@@ -46,7 +46,7 @@ class ParsedUpdate:
     source_progress: SourceProgress | None = None
 
 
-# kinda of a bummber but currently only option, Best effort parser from data-designer logs -> structured status for UI.
+# Best-effort parser from data-designer logs -> structured status for UI.
 _RE_SAMPLERS = re.compile(
     r"Preparing samplers to generate (?P<rows>\d+) records across (?P<cols>\d+) columns"
 )
@@ -327,7 +327,7 @@ def apply_update(job: Job, update: ParsedUpdate) -> None:
         _apply_source_progress(job, update.source_progress)
 
     if update.stage in USAGE_RESET_STAGES:
-        # usage summary is a short block so we reset once we move into the next stage.
+        # Usage summary is a short block; reset on entering the next stage.
         job._in_usage_summary = False
 
     if update.usage_section_start is not None:
diff --git a/studio/backend/core/data_recipe/jobs/types.py b/studio/backend/core/data_recipe/jobs/types.py
index 3d3ddb974e..6dd4db5973 100644
--- a/studio/backend/core/data_recipe/jobs/types.py
+++ b/studio/backend/core/data_recipe/jobs/types.py
@@ -91,8 +91,8 @@ class Job:
     source_progress_estimated_total: int | None = None
     completed_columns: list[str] = field(default_factory = list)
     # Id of the internal sk-unsloth-* API key minted for a local-model
-    # workflow. Revoked when the job terminates so the key's live window
-    # matches the run rather than its 24h TTL.
+    # workflow. Revoked when the job ends so the key's window matches the
+    # run rather than its 24h TTL.
     internal_api_key_id: int | None = None
     _current_usage_model: str | None = None
     _in_usage_summary: bool = False
diff --git a/studio/backend/core/data_recipe/jobs/worker.py b/studio/backend/core/data_recipe/jobs/worker.py
index f59538769e..27d08e90fe 100644
--- a/studio/backend/core/data_recipe/jobs/worker.py
+++ b/studio/backend/core/data_recipe/jobs/worker.py
@@ -73,10 +73,7 @@ def _build_dataset_name(*, run_name: str | None, job_id: str, artifact_root: Pat
 
 
 def run_job_process(*, event_queue, recipe: dict[str, Any], run: dict[str, Any]) -> None:
-    """
-    Subprocess entrypoint.
-    Sends events to `event_queue`.
-    """
+    """Subprocess entrypoint. Sends events to `event_queue`."""
     import os
 
     os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
@@ -115,8 +112,8 @@ def run_job_process(*, event_queue, recipe: dict[str, Any], run: dict[str, Any])
         builder = build_config_builder(recipe)
         designer = create_data_designer(recipe, artifact_path = str(_ARTIFACT_ROOT))
 
-        # DataDesigner configures root logging in DataDesigner.__init__.
-        # Attach queue logger directly to `data_designer` so parser events survive root resets.
+        # DataDesigner configures root logging in __init__. Attach the queue
+        # logger to `data_designer` directly so parser events survive root resets.
         handler = _QueueLogHandler(event_queue)
         handler.setLevel(logging.INFO)
         for logger_name in (
diff --git a/studio/backend/core/data_recipe/service.py b/studio/backend/core/data_recipe/service.py
index cb5901f04e..addbe8f848 100644
--- a/studio/backend/core/data_recipe/service.py
+++ b/studio/backend/core/data_recipe/service.py
@@ -167,9 +167,10 @@ def _validate_recipe_runtime_support(recipe: dict[str, Any], model_providers: li
 def build_mcp_providers(recipe: dict[str, Any]) -> list:
     from data_designer.config.mcp import LocalStdioMCPProvider, MCPProvider  # pyright: ignore[reportMissingImports]
 
-    # Same gate as the chat MCP path: stdio providers spawn a local subprocess,
-    # so only build them when this host allows it (desktop / explicit opt-in).
-    # Skip them otherwise so a recipe carried onto a hosted host cannot spawn.
+    # Same gate as the chat MCP path: stdio providers spawn a local
+    # subprocess, so build them only when this host allows it (desktop /
+    # explicit opt-in). Otherwise a recipe carried onto a hosted host
+    # cannot spawn.
     from core.inference.mcp_client import stdio_mcp_enabled
 
     stdio_allowed = stdio_mcp_enabled()
@@ -258,7 +259,7 @@ def build_config_builder(recipe: dict[str, Any]):
     )
 
     # DataDesignerConfigBuilder.from_config currently skips processors.
-    # Re-attach explicitly so drop_columns/schema_transform survive API payload.
+    # Re-attach so drop_columns/schema_transform survive the API payload.
     for processor in recipe_core.get("processors") or []:
         if not isinstance(processor, dict):
             continue
@@ -283,8 +284,8 @@ def create_data_designer(recipe: dict[str, Any], *, artifact_path: str | None =
     _validate_recipe_runtime_support(recipe, model_providers)
 
     # DataDesigner requires at least one model provider in its registry even
-    # when the pipeline contains no LLM columns.  Supply a lightweight stub
-    # so sampler/expression-only recipes can run without a real provider.
+    # when the pipeline has no LLM columns. Supply a lightweight stub so
+    # sampler/expression-only recipes can run without a real provider.
     if not model_providers:
         from data_designer.config.models import ModelProvider  # pyright: ignore[reportMissingImports]
         model_providers = [
diff --git a/studio/backend/core/export/__init__.py b/studio/backend/core/export/__init__.py
index 16fba368ef..db9d1b352c 100644
--- a/studio/backend/core/export/__init__.py
+++ b/studio/backend/core/export/__init__.py
@@ -5,8 +5,8 @@
 Export submodule - Model export operations
 
 The default get_export_backend() returns an ExportOrchestrator that
-delegates to a subprocess. The original ExportBackend runs inside
-the subprocess and can be imported directly from .export when needed.
+delegates to a subprocess. The original ExportBackend runs inside the
+subprocess and can be imported directly from .export when needed.
 """
 
 from .orchestrator import ExportOrchestrator, get_export_backend
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index e74dc13e8a..aaae8002fc 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -2,9 +2,7 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 # backend/export.py
-"""
-Export backend - handles model exporting in various formats
-"""
+"""Export backend - exports models in various formats."""
 
 import glob
 import json
@@ -46,10 +44,10 @@ def _is_wsl():
 def _apply_wsl_sudo_patch():
     """On WSL, monkey-patch do_we_need_sudo() to return False.
 
-    WSL doesn't have passwordless sudo, and do_we_need_sudo() runs
-    `sudo apt-get update` which hangs waiting for a stdin password
-    inside a non-interactive subprocess. setup.sh pre-installs the
-    build dependencies on WSL, so sudo is not needed at runtime.
+    WSL lacks passwordless sudo, and do_we_need_sudo() runs
+    `sudo apt-get update`, which hangs on a stdin password in a
+    non-interactive subprocess. setup.sh pre-installs the build deps on
+    WSL, so sudo isn't needed at runtime.
     """
     if not _is_wsl():
         return
@@ -110,7 +108,7 @@ class ExportBackend:
         try:
             logger.info("Starting memory cleanup...")
 
-            # Unload all models from inference backend
+            # Unload all inference-backend models
             model_names = list(self.inference_backend.models.keys())
             for model_name in model_names:
                 self.inference_backend.unload_model(model_name)
@@ -121,7 +119,7 @@ class ExportBackend:
             self.current_checkpoint = None
             self._audio_type = None
 
-            # Clear GPU memory cache (handles gc + backend-specific cleanup)
+            # Clear GPU cache (handles gc + backend-specific cleanup)
             clear_gpu_cache()
 
             logger.info("Memory cleanup completed successfully")
@@ -137,8 +135,7 @@ class ExportBackend:
         """
         Scan outputs folder for training runs and their checkpoints.
 
-        Returns:
-            List of tuples: [(model_name, [(display_name, checkpoint_path), ...]), ...]
+        Returns: [(model_name, [(display_name, checkpoint_path), ...]), ...]
         """
         from utils.models.checkpoints import scan_checkpoints
         return scan_checkpoints(outputs_dir = outputs_dir)
@@ -159,12 +156,12 @@ class ExportBackend:
         try:
             logger.info(f"Loading checkpoint: {checkpoint_path}")
 
-            # First, cleanup existing models
+            # Cleanup existing models first
             self.cleanup_memory()
 
             checkpoint_path_obj = Path(checkpoint_path)
 
-            # Determine the model identity for type detection
+            # Model identity for type detection
             adapter_config = checkpoint_path_obj / "adapter_config.json"
             base_model = None
             if adapter_config.exists():
@@ -246,7 +243,7 @@ class ExportBackend:
                     load_in_4bit = load_in_4bit,
                     trust_remote_code = trust_remote_code,
                 )
-                tokenizer = processor  # For vision models, processor acts as tokenizer
+                tokenizer = processor  # vision: processor acts as tokenizer
 
             else:
                 logger.info("Loading as text model...")
@@ -258,14 +255,13 @@ class ExportBackend:
                     trust_remote_code = trust_remote_code,
                 )
 
-            # Check if PEFT / LoRA model
+            # Detect PEFT / LoRA model
             if _IS_MLX:
                 # MLX doesn't use PeftModel — detect LoRA via adapter_config.json
                 self.is_peft = adapter_config.exists()
             else:
                 self.is_peft = isinstance(model, (PeftModel, PeftModelForCausalLM))
 
-            # Store loaded model
             self.current_model = model
             self.current_tokenizer = tokenizer
             self.current_checkpoint = checkpoint_path
@@ -459,7 +455,7 @@ class ExportBackend:
 
                 if _IS_MLX:
                     # MLX: save_pretrained_merged handles non-LoRA models too
-                    # (fuse() is a no-op when there are no LoRA layers)
+                    # (fuse() is a no-op without LoRA layers)
                     self.current_model.save_pretrained_merged(
                         save_directory,
                         self.current_tokenizer,
@@ -509,12 +505,11 @@ class ExportBackend:
                                 private = private,
                             )
                 else:
-                    # Get base model name from request or model config
+                    # Base model name from request or model config
                     base_model = (
                         base_model_id or self.current_model.config._name_or_path or "unknown"
                     )
 
-                    # Create repo
                     hf_api = HfApi(token = hf_token)
                     repo_id = PushToHubMixin._create_repo(
                         PushToHubMixin,
@@ -524,7 +519,7 @@ class ExportBackend:
                     )
                     username = repo_id.split("/")[0]
 
-                    # Create and push model card
+                    # Build and push model card
                     content = MODEL_CARD.format(
                         username = username,
                         base_model = base_model,
@@ -535,7 +530,7 @@ class ExportBackend:
                     card = ModelCard(content)
                     card.push_to_hub(repo_id, token = hf_token, commit_message = "Unsloth Model Card")
 
-                    # Upload model files
+                    # Upload files
                     if save_directory:
                         hf_api.upload_folder(
                             folder_path = save_directory,
@@ -585,7 +580,7 @@ class ExportBackend:
 
         output_path: Optional[str] = None
         try:
-            # Convert quantization method to lowercase for unsloth
+            # unsloth expects lowercase quant method
             quant_method = quantization_method.lower()
 
             # Pin convert_hf_to_gguf.py to the same llama.cpp ref as the
@@ -613,27 +608,26 @@ class ExportBackend:
             # Save locally if requested
             if save_directory:
                 save_directory = str(resolve_export_dir(save_directory))
-                # Resolve to absolute path so unsloth's relative-path internals
+                # Use absolute path so unsloth's relative-path internals
                 # (check_llama_cpp, use_local_gguf, _download_convert_hf_to_gguf)
-                # all resolve against the repo root cwd, NOT the export directory.
+                # resolve against the repo root cwd, NOT the export directory.
                 abs_save_dir = os.path.abspath(save_directory)
                 logger.info(f"Saving GGUF model locally to: {abs_save_dir}")
 
-                # Create the directory if it doesn't exist
                 ensure_dir(Path(abs_save_dir))
 
                 # On WSL, patch out sudo check before llama.cpp build
                 _apply_wsl_sudo_patch()
 
-                # Snapshot existing .gguf files in cwd before conversion.
-                # unsloth's convert_to_gguf writes output files relative to
-                # cwd (repo root), so we diff afterwards and relocate them.
+                # Snapshot existing .gguf files in cwd before conversion;
+                # unsloth's convert_to_gguf writes output relative to cwd
+                # (repo root), so we diff afterwards and relocate.
                 cwd = os.getcwd()
                 pre_existing_ggufs = set(glob.glob(os.path.join(cwd, "*.gguf")))
 
-                # Pass absolute path — no os.chdir needed.
-                # unsloth saves intermediate HF model files into model_save_path.
-                # unsloth-zoo's check_llama_cpp() uses ~/.unsloth/llama.cpp by default.
+                # Absolute path — no os.chdir needed. unsloth saves intermediate
+                # HF model files into model_save_path; unsloth-zoo's
+                # check_llama_cpp() uses ~/.unsloth/llama.cpp by default.
                 model_save_path = os.path.join(abs_save_dir, "model")
                 self.current_model.save_pretrained_gguf(
                     model_save_path,
@@ -642,17 +636,17 @@ class ExportBackend:
                 )
 
                 # Relocate GGUF artifacts into the export directory.
-                # convert_to_gguf writes .gguf files to cwd (repo root)
-                # because --outfile is a relative path like "model.Q4_K_M.gguf".
+                # convert_to_gguf writes .gguf to cwd (repo root) because
+                # --outfile is a relative path like "model.Q4_K_M.gguf".
                 new_ggufs = set(glob.glob(os.path.join(cwd, "*.gguf"))) - pre_existing_ggufs
                 for src in sorted(new_ggufs):
                     dest = os.path.join(abs_save_dir, os.path.basename(src))
                     shutil.move(src, dest)
                     logger.info(f"Relocated GGUF: {os.path.basename(src)} → {abs_save_dir}/")
 
-                # Flatten any .gguf files from subdirectories into abs_save_dir.
+                # Flatten any .gguf from subdirs into abs_save_dir.
                 # save_pretrained_gguf may create subdirs (e.g. model_gguf/)
-                # with a name different from model_save_path.
+                # named differently from model_save_path.
                 for sub in list(Path(abs_save_dir).iterdir()):
                     if not sub.is_dir():
                         continue
@@ -660,13 +654,13 @@ class ExportBackend:
                         dest = os.path.join(abs_save_dir, src.name)
                         shutil.move(str(src), dest)
                         logger.info(f"Relocated GGUF: {src.name} → {abs_save_dir}/")
-                    # Clean up the subdirectory (intermediate HF files, etc.)
+                    # Clean up the subdir (intermediate HF files, etc.)
                     shutil.rmtree(str(sub), ignore_errors = True)
                     logger.info(f"Cleaned up subdirectory: {sub.name}")
 
                 # For non-PEFT models, save_pretrained_gguf redirects to the
-                # checkpoint path, leaving a *_gguf directory in outputs/.
-                # Relocate any GGUFs from there and clean it up.
+                # checkpoint path, leaving a *_gguf dir in outputs/. Relocate
+                # any GGUFs from there and clean it up.
                 if self.current_checkpoint:
                     ckpt = Path(self.current_checkpoint)
                     gguf_dir = ckpt.parent / f"{ckpt.name}_gguf"
@@ -686,8 +680,7 @@ class ExportBackend:
                 # Write export metadata so the Chat page can identify the base model
                 self._write_export_metadata(abs_save_dir)
 
-                # Log final file locations (after relocation) so it's clear
-                # where the GGUF files actually ended up.
+                # Log final file locations (post-relocation).
                 final_ggufs = sorted(glob.glob(os.path.join(abs_save_dir, "*.gguf")))
                 logger.info(
                     "GGUF export complete. Final files in %s:\n  %s",
diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.py
index 90a946163e..49c1af8822 100644
--- a/studio/backend/core/export/orchestrator.py
+++ b/studio/backend/core/export/orchestrator.py
@@ -1,15 +1,13 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Export orchestrator — subprocess-based.
+"""Export orchestrator — subprocess-based.
 
-Provides the same API as ExportBackend, but delegates all ML work
-to a persistent subprocess. The subprocess is spawned on first checkpoint
-load and stays alive for subsequent export operations.
+Same API as ExportBackend, but delegates all ML work to a persistent
+subprocess spawned on first checkpoint load and reused for later exports.
 
-When switching between checkpoints that need different transformers versions,
-the old subprocess is killed and a new one is spawned with the correct version.
+When switching between checkpoints needing different transformers
+versions, the old subprocess is killed and a new one spawned.
 
 Pattern follows core/inference/orchestrator.py.
 """
@@ -30,9 +28,9 @@ logger = get_logger(__name__)
 
 _CTX = mp.get_context("spawn")
 
-# Maximum number of captured log lines kept in memory per export
-# orchestrator. Acts as scrollback for the live export log panel in the
-# UI. 4000 lines is ~1 MB worst-case at 256 chars/line.
+# Max captured log lines kept in memory per export orchestrator;
+# scrollback for the live export log panel. 4000 lines is ~1 MB
+# worst-case at 256 chars/line.
 _LOG_BUFFER_MAXLEN = 4000
 
 
@@ -41,46 +39,44 @@ class ExportOrchestrator:
     Export backend orchestrator — subprocess-based.
 
     Exposes the same API surface as ExportBackend so routes/export.py
-    needs minimal changes. Internally, all heavy ML operations happen in
-    a persistent subprocess.
+    needs minimal changes. All heavy ML work happens in a persistent
+    subprocess.
     """
 
     def __init__(self):
-        # Subprocess state
+        # Subprocess state.
         self._proc: Optional[mp.Process] = None
         self._cmd_queue: Any = None
         self._resp_queue: Any = None
-        # Serializes export operations (load_checkpoint, export_*,
-        # cleanup) so concurrent HTTP requests can never interleave
-        # commands on the subprocess queue. Previously unused.
+        # Serializes export ops (load_checkpoint, export_*, cleanup) so
+        # concurrent HTTP requests can't interleave commands on the
+        # subprocess queue.
         self._lock = threading.Lock()
 
-        # Local state mirrors (updated from subprocess responses)
+        # Local state mirrors (updated from subprocess responses).
         self.current_checkpoint: Optional[str] = None
         self.is_vision: bool = False
         self.is_peft: bool = False
 
         # ── Live log capture ─────────────────────────────────────
-        # Thread-safe ring buffer of log lines forwarded from the
-        # worker subprocess. Powers the GET /api/export/logs/stream
-        # SSE endpoint that the export dialog consumes.
+        # Thread-safe ring buffer of log lines from the worker
+        # subprocess. Powers the GET /api/export/logs/stream SSE
+        # endpoint the export dialog consumes.
         self._log_buffer: Deque[Dict[str, Any]] = deque(maxlen = _LOG_BUFFER_MAXLEN)
         self._log_lock = threading.Lock()
-        # Monotonically increasing sequence number. Never reset across
-        # operations, so SSE clients can use it as a stable cursor even
-        # if clear_logs() is called mid-session.
+        # Monotonic sequence number. Never reset across operations, so
+        # SSE clients can use it as a stable cursor even if clear_logs()
+        # runs mid-session.
         self._log_seq: int = 0
-        # Snapshot of _log_seq captured at the start of the current run
-        # (updated by clear_logs()). The SSE endpoint defaults its
-        # cursor to this value so a client that connects AFTER the
-        # worker has already emitted its first lines still sees the
-        # full run. Every line appended during the current run has seq
-        # strictly greater than _run_start_seq, and every line from
-        # prior runs has seq less than or equal to it.
+        # Snapshot of _log_seq at the start of the current run (set by
+        # clear_logs()). The SSE endpoint defaults its cursor here so a
+        # client connecting AFTER the worker's first lines still sees the
+        # full run. Lines in the current run have seq > _run_start_seq;
+        # prior-run lines have seq <= it.
         self._run_start_seq: int = 0
-        # True while an export operation (load/export/cleanup) is
-        # running. The SSE endpoint ends the stream 1 second after
-        # this flips back to False to drain any trailing log lines.
+        # True while an export op (load/export/cleanup) is running. The
+        # SSE endpoint ends the stream 1s after this flips False to drain
+        # trailing log lines.
         self._export_active: bool = False
 
         atexit.register(self._cleanup)
@@ -91,12 +87,11 @@ class ExportOrchestrator:
     # ------------------------------------------------------------------
 
     def _append_log(self, entry: Dict[str, Any]) -> None:
-        """Append a log line from the worker subprocess to the buffer.
+        """Append a worker-subprocess log line to the buffer.
 
         Entries look like {"type": "log", "stream": "stdout"|"stderr",
-        "line": "...", "ts": ...}. Each is stamped with a monotonic
-        seq number before it lands in the buffer so SSE clients can
-        cursor through new lines.
+        "line": "...", "ts": ...}. Each gets a monotonic seq number so
+        SSE clients can cursor through new lines.
         """
         line = entry.get("line")
         if not line:
@@ -113,17 +108,16 @@ class ExportOrchestrator:
             )
 
     def clear_logs(self) -> None:
-        """Drop any buffered log lines from a previous operation.
+        """Drop buffered log lines from a previous operation.
 
         Called at the start of each export op so the UI shows only the
-        output of the current run. The seq counter is NOT reset, so an
-        SSE client that captured the cursor before clear_logs() will
-        still see new lines (with strictly greater seq numbers).
+        current run. The seq counter is NOT reset, so an SSE client that
+        captured the cursor before clear_logs() still sees new lines
+        (with strictly greater seq).
 
-        Also snapshots the current seq into ``_run_start_seq`` so the
-        SSE endpoint can anchor its default cursor at the start of
-        this run. Anything appended after this call has seq strictly
-        greater than the snapshot and is reachable via
+        Also snapshots the current seq into ``_run_start_seq`` so the SSE
+        endpoint can anchor its default cursor at this run's start.
+        Anything appended after has seq > the snapshot, reachable via
         ``get_logs_since(get_run_start_seq())``.
         """
         with self._log_lock:
@@ -144,11 +138,11 @@ class ExportOrchestrator:
             return self._log_seq
 
     def get_run_start_seq(self) -> int:
-        """Return the seq value captured at the start of the current run.
+        """Return the seq captured at the start of the current run.
 
         The SSE endpoint uses this as the default cursor so a client
-        that connects AFTER the worker has already started emitting
-        output still sees every line from the current run.
+        connecting AFTER the worker started emitting still sees every
+        line from the current run.
         """
         with self._log_lock:
             return self._run_start_seq
@@ -193,22 +187,22 @@ class ExportOrchestrator:
             self._proc = None
             return
 
-        # 1. Drain stale responses
+        # 1. Drain stale responses.
         self._drain_queue()
 
-        # 2. Send shutdown command
+        # 2. Send shutdown command.
         try:
             self._cmd_queue.put({"type": "shutdown"})
         except (OSError, ValueError):
             pass
 
-        # 3. Wait for graceful shutdown
+        # 3. Wait for graceful shutdown.
         try:
             self._proc.join(timeout = timeout)
         except Exception:
             pass
 
-        # 4. Force kill if still alive
+        # 4. Force kill if still alive.
         if self._proc is not None and self._proc.is_alive():
             logger.warning("Export subprocess did not exit gracefully, terminating")
             try:
@@ -268,9 +262,8 @@ class ExportOrchestrator:
     ) -> dict:
         """Block until a response of the expected type arrives.
 
-        Export operations can take a very long time — GGUF conversion for
-        large models (30B+) easily takes 20-30 minutes. Default timeout
-        is 1 hour.
+        Export ops can take a long time — GGUF conversion for large
+        models (30B+) easily takes 20-30 minutes. Default timeout 1 hour.
         """
         deadline = time.monotonic() + timeout
 
@@ -279,7 +272,7 @@ class ExportOrchestrator:
             resp = self._read_resp(timeout = min(remaining, 2.0))
 
             if resp is None:
-                # Check subprocess health
+                # Check subprocess health.
                 if not self._ensure_subprocess_alive():
                     raise RuntimeError("Export subprocess crashed during wait")
                 continue
@@ -294,17 +287,16 @@ class ExportOrchestrator:
                 raise RuntimeError(f"Subprocess error: {error_msg}")
 
             if rtype == "log":
-                # Forwarded stdout/stderr line from the worker process.
+                # Forwarded stdout/stderr line from the worker.
                 self._append_log(resp)
                 continue
 
             if rtype == "status":
                 message = resp.get("message", "")
                 logger.info("Export subprocess status: %s", message)
-                # Surface status messages in the live log panel too so
-                # users see high level progress (e.g. "Importing
-                # Unsloth...", "Loading checkpoint: ...") alongside
-                # subprocess output.
+                # Surface status in the live log panel too so users see
+                # high-level progress (e.g. "Importing Unsloth...",
+                # "Loading checkpoint: ...") alongside subprocess output.
                 if message:
                     self._append_log(
                         {
@@ -315,7 +307,7 @@ class ExportOrchestrator:
                     )
                 continue
 
-            # Other response types during wait — skip
+            # Other response types during wait — skip.
             logger.debug(
                 "Skipping response type '%s' while waiting for '%s'",
                 rtype,
@@ -362,12 +354,11 @@ class ExportOrchestrator:
         }
 
         with self._lock:
-            # Start a fresh log buffer for this operation so the UI
-            # sees only the current run's output.
+            # Fresh log buffer so the UI sees only this run's output.
             self.clear_logs()
             self._export_active = True
             try:
-                # Always kill existing subprocess and spawn fresh.
+                # Always kill any existing subprocess and spawn fresh.
                 if self._ensure_subprocess_alive():
                     self._shutdown_subprocess()
                 elif self._proc is not None:
@@ -488,12 +479,11 @@ class ExportOrchestrator:
     def _run_export(self, export_type: str, params: dict) -> Tuple[bool, str, Optional[str]]:
         """Send an export command to the subprocess and wait for result.
 
-        Returns ``(success, message, output_path)``. ``output_path`` is the
-        resolved on-disk directory the worker actually wrote to (None when
-        the export only pushed to Hub or failed before any file was
-        written). Surfaced via the export route's ``details.output_path``
-        so the dialog's success screen can show the user where the model
-        landed.
+        Returns ``(success, message, output_path)``. ``output_path`` is
+        the resolved on-disk dir the worker wrote to (None when the
+        export only pushed to Hub or failed before writing). Surfaced via
+        the export route's ``details.output_path`` so the dialog's success
+        screen shows where the model landed.
         """
         with self._lock:
             if not self._ensure_subprocess_alive():
@@ -527,7 +517,7 @@ class ExportOrchestrator:
         """Cleanup export-related models from memory."""
         with self._lock:
             if not self._ensure_subprocess_alive():
-                # No subprocess — just clear local state
+                # No subprocess — clear local state.
                 self.current_checkpoint = None
                 self.is_vision = False
                 self.is_peft = False
@@ -542,7 +532,7 @@ class ExportOrchestrator:
                 except RuntimeError:
                     success = False
 
-                # Shut down subprocess after cleanup — no model loaded
+                # Shut down subprocess after cleanup — no model loaded.
                 self._shutdown_subprocess()
 
                 self.current_checkpoint = None
@@ -553,7 +543,7 @@ class ExportOrchestrator:
                 self._export_active = False
 
     def scan_checkpoints(self, outputs_dir: str = str(outputs_root())) -> List[Tuple[str, list]]:
-        """Scan for checkpoints — no ML imports needed, runs locally."""
+        """Scan for checkpoints — runs locally, no ML imports."""
         from utils.models.checkpoints import scan_checkpoints
         return scan_checkpoints(outputs_dir = outputs_dir)
 
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index 405956ec9d..a517d6d7b1 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -4,9 +4,9 @@
 """
 Export subprocess entry point.
 
-Each export session runs in a persistent subprocess (mp.get_context("spawn")).
-This gives us a clean Python interpreter with no stale module state —
-solving the transformers version-switching problem completely.
+Each export session runs in a persistent subprocess (mp.get_context("spawn")),
+giving a clean interpreter with no stale module state — solving the
+transformers version-switching problem completely.
 
 The subprocess stays alive while a model is loaded, accepting commands
 (load, export_merged, export_base, export_gguf, export_lora, cleanup,
@@ -31,41 +31,39 @@ from typing import Any
 logger = get_logger(__name__)
 
 
-# Gate that controls whether captured stdout/stderr lines are forwarded
-# to the parent's resp_queue (and from there to the export-dialog SSE
-# stream). Closed by default so the noisy bootstrap phase -- transformers
-# venv activation, Unsloth/torch imports, base-model resolution, "Top
-# GGUF/hub models" lists, vision detection, weight loading bars -- is
-# suppressed in the UI. _handle_export() opens the gate at the start of
-# the actual export work and leaves it open; the orchestrator always
-# spawns a fresh subprocess for the next checkpoint load (see
-# orchestrator._spawn_subprocess) which resets this state.
+# Gate controlling whether captured stdout/stderr lines are forwarded to
+# the parent's resp_queue (and on to the export-dialog SSE stream). Closed
+# by default so the noisy bootstrap phase -- transformers venv activation,
+# Unsloth/torch imports, base-model resolution, "Top GGUF/hub models" lists,
+# vision detection, weight loading bars -- is suppressed in the UI.
+# _handle_export() opens the gate when actual export work starts and leaves
+# it open; the orchestrator spawns a fresh subprocess for the next checkpoint
+# load (see orchestrator._spawn_subprocess), resetting this state.
 #
 # Lines dropped while the gate is closed are still echoed to the saved
-# original stdout/stderr fds so the server console / log file keeps the
-# full output for debugging.
+# original stdout/stderr fds so the server console / log file keeps the full
+# output for debugging.
 _log_forward_gate = threading.Event()
 
 
 def _setup_log_capture(resp_queue: Any) -> None:
     """Redirect fds 1 and 2 through pipes so every line printed by this
-    worker process and any child process it spawns is forwarded to the
-    parent process via resp_queue as {"type": "log", ...} messages.
+    worker and any child it spawns is forwarded to the parent via resp_queue
+    as {"type": "log", ...} messages.
 
-    Must be called BEFORE LogConfig.setup_logging and BEFORE any ML
-    imports, otherwise library handlers may capture the original stderr
-    reference and bypass the pipe.
+    Must run BEFORE LogConfig.setup_logging and any ML imports, else library
+    handlers may capture the original stderr reference and bypass the pipe.
 
-    Lines are also echoed back to the original stdout/stderr so the
-    server console keeps receiving the full subprocess output, even
-    while ``_log_forward_gate`` is closed.
+    Lines are also echoed back to the original stdout/stderr so the server
+    console keeps the full subprocess output, even while
+    ``_log_forward_gate`` is closed.
     """
 
     try:
         saved_out_fd = os.dup(1)
         saved_err_fd = os.dup(2)
     except OSError:
-        # dup failed (exotic platforms) - give up quietly, export still
+        # dup failed (exotic platforms) - give up quietly; export still
         # works, just no live log streaming.
         return
 
@@ -88,13 +86,13 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 pass
         return
 
-    # Close the write ends we just dup2'd (fds 1 and 2 are the real
-    # write ends now).
+    # Close the write ends we just dup2'd (fds 1 and 2 are now the real
+    # write ends).
     os.close(w_out)
     os.close(w_err)
 
-    # Replace Python's sys.stdout/sys.stderr with line-buffered writers
-    # bound to the (now-redirected) fds 1 and 2.
+    # Replace sys.stdout/sys.stderr with line-buffered writers bound to the
+    # (now-redirected) fds 1 and 2.
     try:
         sys.stdout = os.fdopen(1, "w", buffering = 1, encoding = "utf-8", errors = "replace")
         sys.stderr = os.fdopen(2, "w", buffering = 1, encoding = "utf-8", errors = "replace")
@@ -112,8 +110,8 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 continue
             if not chunk:
                 break
-            # Echo to the original fd so the server console still sees
-            # the full output.
+            # Echo to the original fd so the server console keeps the
+            # full output.
             try:
                 os.write(echo_fd, chunk)
             except OSError:
@@ -133,9 +131,9 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 if not line:
                     continue
                 if not _log_forward_gate.is_set():
-                    # Gate closed (bootstrap phase) -- already echoed to
-                    # the saved console fd above; drop the line so the
-                    # export dialog doesn't see import / vendoring noise.
+                    # Gate closed (bootstrap) -- already echoed to the saved
+                    # console fd above; drop the line so the export dialog
+                    # doesn't see import / vendoring noise.
                     continue
                 try:
                     resp_queue.put_nowait(
@@ -147,8 +145,8 @@ def _setup_log_capture(resp_queue: Any) -> None:
                         }
                     )
                 except Exception:
-                    # Queue put failed (full, closed, etc.) - drop the
-                    # line rather than crash the reader thread.
+                    # Queue put failed (full, closed, etc.) - drop the line
+                    # rather than crash the reader thread.
                     pass
         if buf and _log_forward_gate.is_set():
             try:
@@ -181,7 +179,7 @@ def _setup_log_capture(resp_queue: Any) -> None:
 
 def _activate_transformers_version(model_name: str) -> None:
     """Activate the correct transformers version BEFORE any ML imports."""
-    # Ensure backend is on path for utils imports
+    # Ensure backend is on sys.path for utils imports
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -267,11 +265,11 @@ def _handle_export(backend, cmd: dict, resp_queue: Any) -> None:
     export_type = cmd["export_type"]  # "merged", "base", "gguf", "lora"
     response_type = f"export_{export_type}_done"
 
-    # Open the log forwarding gate so the user sees the actual export
-    # progress (Unsloth merge bars, file copies, GGUF conversion, etc.)
-    # in the live log panel. The gate stays open for the rest of this
-    # subprocess's life; the orchestrator spawns a fresh subprocess for
-    # the next checkpoint load, which resets the gate to closed.
+    # Open the log forwarding gate so the user sees actual export progress
+    # (Unsloth merge bars, file copies, GGUF conversion, etc.) in the live
+    # log panel. The gate stays open for the rest of this subprocess's life;
+    # the orchestrator spawns a fresh subprocess for the next checkpoint
+    # load, which resets the gate to closed.
     _log_forward_gate.set()
 
     output_path: Any = None
@@ -372,23 +370,23 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
     """
     import queue as _queue
 
-    # Install fd-level stdout/stderr capture FIRST so every subsequent
-    # print and every child process inherits the redirected fds. This
-    # is what powers the live export log stream in the UI.
+    # Install fd-level stdout/stderr capture FIRST so every subsequent print
+    # and every child process inherits the redirected fds. This powers the
+    # live export log stream in the UI.
     _setup_log_capture(resp_queue)
 
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
     os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
-    # Force unbuffered output from any child Python process (e.g. the
-    # GGUF converter) so their prints surface in the log stream as they
-    # happen rather than at the end.
+    # Force unbuffered output from child Python processes (e.g. the GGUF
+    # converter) so their prints surface in the log stream as they happen,
+    # not at the end.
     os.environ["PYTHONUNBUFFERED"] = "1"
     # tqdm defaults to a 10-second mininterval when stdout is not a tty
-    # (which it isn't here -- we redirected fd 1/2 to a pipe). That makes
-    # multi-step progress bars look frozen in the export log panel. Force
-    # frequent flushes so the user sees movement during merge / GGUF
-    # conversion. Has no effect on single-step bars (e.g. "Copying 1
-    # files") which only emit start/end events regardless.
+    # (it isn't -- we redirected fd 1/2 to a pipe), making multi-step
+    # progress bars look frozen in the export log panel. Force frequent
+    # flushes so the user sees movement during merge / GGUF conversion. No
+    # effect on single-step bars (e.g. "Copying 1 files") which only emit
+    # start/end events anyway.
     os.environ.setdefault("TQDM_MININTERVAL", "0.5")
 
     import warnings
@@ -419,7 +417,7 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
         )
         return
 
-    # ── 1b. On Windows, check Triton availability (must be before import torch) ──
+    # ── 1b. Check Triton on Windows (must precede import torch) ──
     if sys.platform == "win32":
         try:
             import triton  # noqa: F401
@@ -433,9 +431,9 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
 
     # ── 1c. Stub torchao on Windows ROCm ──
     # Shared with the training worker; see core/_torchao_stub.py for the full
-    # rationale (torchao -> torch.distributed._functional_collectives crashes on
-    # Windows ROCm because the RCCL backend is absent). No-op off Windows ROCm.
-    # Must run before any import of transformers / unsloth_zoo.
+    # rationale (torchao -> torch.distributed._functional_collectives crashes
+    # on Windows ROCm: RCCL backend absent). No-op off Windows ROCm. Must run
+    # before importing transformers / unsloth_zoo.
     from core._torchao_stub import install_torchao_windows_rocm_stub
 
     install_torchao_windows_rocm_stub()
@@ -511,7 +509,7 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
 
         try:
             if cmd_type == "load":
-                # Load a new checkpoint (reusing this subprocess)
+                # Load a new checkpoint, reusing this subprocess
                 backend.cleanup_memory()
                 _handle_load(backend, cmd, resp_queue)
 
diff --git a/studio/backend/core/inference/__init__.py b/studio/backend/core/inference/__init__.py
index 35318f6357..2faf70bb79 100644
--- a/studio/backend/core/inference/__init__.py
+++ b/studio/backend/core/inference/__init__.py
@@ -2,17 +2,17 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Inference submodule - Inference backend for model loading and generation
+Inference submodule - backend for model loading and generation.
 
 The default get_inference_backend() returns an InferenceOrchestrator that
-delegates to a subprocess. The original InferenceBackend runs inside
-the subprocess and can be imported directly from .inference when needed.
+delegates to a subprocess. The original InferenceBackend runs inside the
+subprocess and can be imported directly from .inference when needed.
 """
 
 from .orchestrator import InferenceOrchestrator, get_inference_backend
 from .llama_cpp import LlamaCppBackend
 
-# Expose InferenceOrchestrator as InferenceBackend for backward compat
+# Expose InferenceOrchestrator as InferenceBackend for backward compat.
 InferenceBackend = InferenceOrchestrator
 
 __all__ = [
diff --git a/studio/backend/core/inference/_html_to_md.py b/studio/backend/core/inference/_html_to_md.py
index f999120ffb..b6262d9974 100644
--- a/studio/backend/core/inference/_html_to_md.py
+++ b/studio/backend/core/inference/_html_to_md.py
@@ -5,7 +5,7 @@
 Minimal HTML-to-Markdown converter using only the standard library.
 
 Replaces the external ``html2text`` (GPL-3.0) dependency with a ~250-line
-``html.parser.HTMLParser`` subclass.  Covers headings, links, bold/italic,
+``html.parser.HTMLParser`` subclass. Covers headings, links, bold/italic,
 lists, tables, blockquotes, code blocks, and entity decoding.
 """
 
@@ -81,9 +81,9 @@ class _MarkdownRenderer(HTMLParser):
         self._pre_parts: list[str] = []
         self._in_inline_code: bool = False
 
-        # Blockquote state -- stack of output buffers so nested
-        # blockquotes each collect their own content and get prefixed
-        # with the correct number of ">" markers on close.
+        # Blockquote state -- stack of output buffers so nested blockquotes
+        # each collect their own content and get prefixed with the correct
+        # number of ">" markers on close.
         self._bq_stack: list[list[str]] = []
 
     # ------------------------------------------------------------------
@@ -102,7 +102,7 @@ class _MarkdownRenderer(HTMLParser):
     # ------------------------------------------------------------------
     def _prefix_blockquote(self, content: str) -> str:
         """Prefix every line of *content* with ``> ``."""
-        # Strip trailing whitespace first, then collapse blank lines
+        # Strip trailing whitespace, then collapse blank lines.
         content = re.sub(r"[ \t]+$", "", content, flags = re.MULTILINE)
         content = re.sub(r"\n{3,}", "\n\n", content).strip()
         if not content:
@@ -117,8 +117,8 @@ class _MarkdownRenderer(HTMLParser):
         return "\n".join(prefixed)
 
     # ------------------------------------------------------------------
-    # Table helpers -- flush open cells and rows so that HTML with
-    # omitted optional end tags (</td>, </tr>) does not lose data.
+    # Table helpers -- flush open cells/rows so HTML with omitted optional
+    # end tags (</td>, </tr>) does not lose data.
     # ------------------------------------------------------------------
     def _finish_cell(self) -> None:
         if not self._in_cell:
@@ -143,8 +143,8 @@ class _MarkdownRenderer(HTMLParser):
         self._row_has_th = False
 
     # ------------------------------------------------------------------
-    # Link text helper -- normalize whitespace so block-level content
-    # inside an <a> does not produce multiline Markdown link labels.
+    # Link text helper -- normalize whitespace so block-level content inside
+    # an <a> does not produce multiline Markdown link labels.
     # ------------------------------------------------------------------
     def _finish_link(self) -> None:
         text = re.sub(r"\s+", " ", "".join(self._link_text_parts)).strip()
@@ -234,13 +234,13 @@ class _MarkdownRenderer(HTMLParser):
             self._emit("\n\n")
 
         elif tag == "tr":
-            # Flush any open cell/row from a previous row that may
-            # have omitted its optional </td> or </tr> end tags.
+            # Flush any open cell/row from a previous row that omitted its
+            # optional </td> or </tr> end tags.
             self._finish_cell()
             self._finish_row()
 
         elif tag in ("th", "td"):
-            # Flush any open cell (handles omitted </td>/<th>)
+            # Flush any open cell (handles omitted </td>/<th>).
             self._finish_cell()
             self._cell_parts = []
             self._in_cell = True
@@ -248,8 +248,8 @@ class _MarkdownRenderer(HTMLParser):
                 self._row_has_th = True
 
         elif tag == "img":
-            # Skip images -- keeps fetched page text focused on readable
-            # content and avoids data-URI amplification.
+            # Skip images -- keeps page text focused on readable content and
+            # avoids data-URI amplification.
             return
 
     def handle_endtag(self, tag: str) -> None:
@@ -310,7 +310,7 @@ class _MarkdownRenderer(HTMLParser):
             self._finish_row()
 
         elif tag == "table":
-            # Flush any remaining row (handles omitted </tr>)
+            # Flush any remaining row (handles omitted </tr>).
             self._finish_cell()
             self._finish_row()
             self._in_table = False
@@ -325,15 +325,15 @@ class _MarkdownRenderer(HTMLParser):
         if self._in_pre:
             self._pre_parts.append(data)
             return
-        # Preserve literal whitespace inside inline <code> spans
+        # Preserve literal whitespace inside inline <code> spans.
         if self._in_inline_code:
             self._emit(data)
             return
-        # Collapse all whitespace (including newlines) per HTML rules
+        # Collapse all whitespace (including newlines) per HTML rules.
         text = re.sub(r"\s+", " ", data)
-        # Suppress whitespace-only text nodes between table structural
-        # elements (indentation from source HTML) to prevent leading
-        # spaces from breaking Markdown table row alignment.
+        # Suppress whitespace-only text nodes between table structural elements
+        # (source indentation) so leading spaces don't break Markdown table
+        # row alignment.
         if self._in_table and not self._in_cell and not text.strip():
             return
         self._emit(text)
@@ -354,9 +354,9 @@ class _MarkdownRenderer(HTMLParser):
     def flush_pending(self) -> None:
         """Flush any open side-buffers into ``_out``.
 
-        Called after ``close()`` to recover content from truncated HTML
-        where closing tags were never seen (common when ``_fetch_page_text``
-        caps the download by byte count).
+        Called after ``close()`` to recover content from truncated HTML where
+        closing tags were never seen (common when ``_fetch_page_text`` caps the
+        download by byte count).
         """
         # Flush innermost buffers first so their content propagates outward.
 
@@ -376,7 +376,7 @@ class _MarkdownRenderer(HTMLParser):
             block = "```\n" + raw + "\n```"
             self._emit("\n\n" + block + "\n\n")
 
-        # Flatten any open blockquote buffers (innermost first)
+        # Flatten any open blockquote buffers (innermost first).
         while self._bq_stack:
             content = "".join(self._bq_stack.pop())
             prefixed = self._prefix_blockquote(content)
@@ -394,8 +394,8 @@ class _MarkdownRenderer(HTMLParser):
 def _cleanup(text: str) -> str:
     """Normalize whitespace and blank lines in the final output.
 
-    Preserves content inside fenced code blocks verbatim so that
-    intentional blank lines in ``<pre>`` content are not collapsed.
+    Preserves content inside fenced code blocks verbatim so intentional blank
+    lines in ``<pre>`` content are not collapsed.
     """
     lines = text.split("\n")
     out: list[str] = []
@@ -411,7 +411,7 @@ def _cleanup(text: str) -> str:
             continue
 
         if in_fence:
-            # Preserve code block content exactly as-is
+            # Preserve code block content exactly as-is.
             out.append(line)
             continue
 
@@ -433,11 +433,11 @@ def _cleanup(text: str) -> str:
 def html_to_markdown(source_html: str) -> str:
     """Convert an HTML string to Markdown.
 
-    Handles headings, links, bold/italic, lists (ordered and unordered),
-    tables, blockquotes, code blocks, and HTML entities.  ``<script>``,
-    ``<style>``, and ``<head>`` sections are stripped entirely.
+    Handles headings, links, bold/italic, ordered/unordered lists, tables,
+    blockquotes, code blocks, and HTML entities. ``<script>``, ``<style>``,
+    and ``<head>`` sections are stripped entirely.
     """
-    # Normalize line endings before parsing
+    # Normalize line endings before parsing.
     source_html = source_html.replace("\r\n", "\n").replace("\r", "\n")
     renderer = _MarkdownRenderer()
     renderer.feed(source_html)
diff --git a/studio/backend/core/inference/anthropic_compat.py b/studio/backend/core/inference/anthropic_compat.py
index 61dea5c010..ce5f5c220f 100644
--- a/studio/backend/core/inference/anthropic_compat.py
+++ b/studio/backend/core/inference/anthropic_compat.py
@@ -4,7 +4,7 @@
 """
 Anthropic Messages API ↔ OpenAI format translation utilities.
 
-Pure functions and a stateful stream emitter — no FastAPI, no I/O.
+Pure functions plus stateful stream emitters; no FastAPI, no I/O.
 """
 
 from __future__ import annotations
@@ -46,9 +46,9 @@ def anthropic_messages_to_openai(
 ) -> list[dict]:
     """Convert Anthropic messages + system to OpenAI-format message dicts.
 
-    User messages that carry ``image`` blocks are emitted as OpenAI
-    multimodal content arrays (``[{type: "text", ...}, {type: "image_url", ...}]``)
-    so they flow through llama-server's native vision pathway.
+    User messages with ``image`` blocks are emitted as OpenAI multimodal
+    content arrays (``[{type: "text", ...}, {type: "image_url", ...}]``) so
+    they flow through llama-server's native vision pathway.
     """
     result: list[dict] = []
 
@@ -104,9 +104,9 @@ def anthropic_messages_to_openai(
             continue
 
         if role == "user":
-            # Build an ordered part list so text/image interleaving is
-            # preserved (e.g. [text, image, text, image]). tool_result
-            # blocks become their own OpenAI "tool" role messages.
+            # Ordered part list to preserve text/image interleaving (e.g.
+            # [text, image, text, image]). tool_result blocks become their
+            # own OpenAI "tool" role messages.
             user_parts: list[dict] = []
             has_image = False
             tool_results: list[dict] = []
@@ -137,8 +137,8 @@ def anthropic_messages_to_openai(
             if has_image:
                 result.append({"role": "user", "content": user_parts})
             else:
-                # No images — collapse text parts to a plain string so
-                # existing text-only callers keep their simple shape.
+                # No images: collapse text parts to a plain string so
+                # text-only callers keep their simple shape.
                 text = "\n".join(p["text"] for p in user_parts)
                 if text:
                     result.append({"role": "user", "content": text})
@@ -181,8 +181,8 @@ def anthropic_tool_choice_to_openai(tc: Any) -> Any:
     - ``{"type": "tool", "name": "get_weather"}``
           → ``{"type": "function", "function": {"name": "get_weather"}}``
 
-    Returns ``None`` for ``None`` or any unrecognized shape (caller may
-    then fall back to its own default, typically ``"auto"``).
+    Returns ``None`` for ``None`` or any unrecognized shape (caller falls
+    back to its own default, typically ``"auto"``).
     """
     if tc is None:
         return None
@@ -209,8 +209,8 @@ def build_anthropic_sse_event(event_type: str, data: dict) -> str:
 
 
 class AnthropicStreamEmitter:
-    """Converts generator events from generate_chat_completion_with_tools()
-    into Anthropic Messages SSE strings."""
+    """Converts generate_chat_completion_with_tools() events into Anthropic
+    Messages SSE strings."""
 
     def __init__(self) -> None:
         self.block_index: int = 0
@@ -320,8 +320,8 @@ class AnthropicStreamEmitter:
         # Close current text block if open.
         if self._text_block_open:
             events.append(self._close_block())
-        # Defensive: if a replacement/different tool_start arrives while a
-        # tool_use block is open, close the stale block before starting another.
+        # Defensive: if a different tool_start arrives while a tool_use
+        # block is open, close the stale block before starting another.
         elif self._open_tool_call_id is not None:
             events.append(self._close_block())
             self._open_tool_call_id = None
@@ -421,10 +421,10 @@ class AnthropicStreamEmitter:
 class AnthropicPassthroughEmitter:
     """Converts llama-server's OpenAI-format streaming chunks into Anthropic SSE.
 
-    Used for the client-side tool-use pass-through path: the client (e.g. Claude
-    Code) sends its own tool definitions in the ``tools`` field and expects to
-    execute them itself. We forward them to llama-server and translate the
-    streaming response back to Anthropic format without executing anything.
+    Used for the client-side tool-use pass-through path: the client (e.g.
+    Claude Code) sends its own tool definitions in ``tools`` and executes
+    them itself. We forward them to llama-server and translate the streaming
+    response back to Anthropic format without executing anything.
     """
 
     def __init__(self) -> None:
diff --git a/studio/backend/core/inference/audio_codecs.py b/studio/backend/core/inference/audio_codecs.py
index e6b7f9c613..c6d87d44f0 100644
--- a/studio/backend/core/inference/audio_codecs.py
+++ b/studio/backend/core/inference/audio_codecs.py
@@ -90,8 +90,8 @@ class AudioCodecManager:
         import os
         import sys
 
-        # Clone SparkAudio/Spark-TTS GitHub repo for the sparktts Python package
-        # (same approach as training — the HF model repos don't contain the package)
+        # Clone SparkAudio/Spark-TTS for the sparktts package (same as
+        # training; the HF model repos don't contain it)
         spark_code_dir = os.path.join(os.path.dirname(model_repo_path or "."), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
@@ -115,7 +115,7 @@ class AudioCodecManager:
 
         from sparktts.models.audio_tokenizer import BiCodecTokenizer
 
-        # BiCodecTokenizer needs the MODEL repo path (contains BiCodec/ weights)
+        # BiCodecTokenizer needs the MODEL repo path (has BiCodec/ weights)
         tokenizer_path = model_repo_path or spark_code_dir
         self._bicodec_repo_path = tokenizer_path
         self._bicodec_tokenizer = BiCodecTokenizer(tokenizer_path, device)
@@ -127,9 +127,9 @@ class AudioCodecManager:
         import os
         import sys
 
-        # Clone OuteTTS repo (same pattern as Spark-TTS / BiCodec)
-        # The pip package has problematic dependencies; the notebook clones and
-        # removes gguf_model.py, interface.py, __init__.py before importing.
+        # Clone OuteTTS (same pattern as Spark-TTS / BiCodec). The pip
+        # package has problematic deps; the notebook clones and removes
+        # gguf_model.py, interface.py, __init__.py before importing.
         base_dir = os.path.dirname(os.path.abspath(__file__))
         outetts_code_dir = os.path.join(base_dir, "OuteTTS")
         outetts_pkg = os.path.join(outetts_code_dir, "outetts")
@@ -148,8 +148,8 @@ class AudioCodecManager:
                 env = child_env_without_native_path_secret(),
                 **_windows_hidden_subprocess_kwargs(),
             )
-            # Remove files that pull in heavy / incompatible dependencies
-            # (matches notebook: gguf_model.py is under models/, others under outetts/)
+            # Remove files pulling in heavy / incompatible deps (matches
+            # notebook: gguf_model.py under models/, others under outetts/)
             remove_paths = [
                 os.path.join(outetts_pkg, "models", "gguf_model.py"),
                 os.path.join(outetts_pkg, "interface.py"),
@@ -181,9 +181,9 @@ class AudioCodecManager:
         """
         Decode SNAC tokens (Orpheus) into WAV bytes.
 
-        generated_ids: full model output including prompt tokens.
-        Looks for START_OF_SPEECH (128257) marker, extracts codes after it,
-        strips EOS (128258), redistributes 7-per-frame codes into 3 SNAC layers.
+        generated_ids: full model output including prompt tokens. Finds the
+        START_OF_SPEECH (128257) marker, extracts codes after it, strips EOS
+        (128258), redistributes 7-per-frame codes into 3 SNAC layers.
 
         Returns (wav_bytes, 24000).
         """
@@ -192,7 +192,7 @@ class AudioCodecManager:
         if len(token_indices[1]) > 0:
             cropped = generated_ids[:, token_indices[1][-1] + 1 :]
         else:
-            # Gracefully fall back to using entire output if marker not found
+            # Fall back to the entire output if the marker is missing
             logger.warning("No START_OF_SPEECH token (128257) found — using full generated output")
             cropped = generated_ids
         row = cropped[0]
@@ -256,8 +256,8 @@ class AudioCodecManager:
 
         semantic_ids = torch.tensor([int(t) for t in semantic_matches]).long().unsqueeze(0)
 
-        # Speaker encoder expects exactly 32 global tokens (token_num=32 in BiCodec config).
-        # Pad with zeros or truncate to 32.
+        # Speaker encoder expects exactly 32 global tokens (token_num=32 in
+        # BiCodec config). Pad with zeros or truncate to 32.
         GLOBAL_TOKEN_NUM = 32
         if global_matches:
             raw = [int(t) for t in global_matches]
diff --git a/studio/backend/core/inference/chat_template_helpers.py b/studio/backend/core/inference/chat_template_helpers.py
index c70e9b3c53..b85e9c348a 100644
--- a/studio/backend/core/inference/chat_template_helpers.py
+++ b/studio/backend/core/inference/chat_template_helpers.py
@@ -2,8 +2,8 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Dependency-light wrapper around tokenizer.apply_chat_template with a
-kwarg fallback for templates that reject reasoning/tools args.
+Dependency-light wrapper around tokenizer.apply_chat_template with a kwarg
+fallback for templates that reject reasoning/tools args.
 """
 
 from typing import Optional
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index 3142434d09..3132ad6f86 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -2,10 +2,10 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Async HTTP client for proxying chat completions to external LLM providers.
+Async HTTP client proxying chat completions to external LLM providers.
 
-Most registry providers expose OpenAI-compatible /v1/chat/completions endpoints;
-Anthropic uses native Messages API with translation in this client.
+Most providers use OpenAI-compatible /v1/chat/completions; Anthropic uses
+the native Messages API, translated in this client.
 """
 
 import base64
@@ -19,40 +19,36 @@ from urllib.parse import urlparse
 import httpx
 import structlog
 
-# Use structlog so INFO-level diagnostics actually surface in the
-# studio backend's JSON log stream. The stdlib root logger defaults to
-# WARNING and is not configured with handlers, so plain
-# `logging.getLogger(__name__).info(...)` was being silently dropped —
-# only WARNING/ERROR made it through (because they bypassed the root
-# level threshold via uvicorn's stderr capture). All existing call
-# sites use printf-style positional args, which structlog accepts.
+# Use structlog so INFO diagnostics surface in the backend's JSON log
+# stream. The stdlib root logger defaults to WARNING with no handlers, so
+# `logging.getLogger(__name__).info(...)` was silently dropped (only
+# WARNING/ERROR reached uvicorn's stderr capture). Existing call sites use
+# printf-style positional args, which structlog accepts.
 logger = structlog.get_logger(__name__)
 
 
 # Claude 4.7 (Opus/Sonnet/Haiku) removed temperature, top_p, and top_k —
-# the API returns 400 "<param> is deprecated for this model" if any of
-# them is set to a non-default value. The "Sampling parameters removed"
-# section of the 4.7 release notes is the authoritative reference:
+# the API returns 400 "<param> is deprecated for this model" if any is set
+# to a non-default value. Authoritative ref ("Sampling parameters removed"):
 #   https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7
-# 3.x and 4.5/4.6 still accept all three; match the 4-7 line strictly so
-# the knobs keep working on earlier families. The trailing -4-7[-.]/EOL
-# anchor keeps future versions (e.g. claude-opus-5) unaffected.
+# 3.x and 4.5/4.6 still accept all three; match the 4-7 line strictly so the
+# knobs keep working on earlier families. The -4-7[-.]/EOL anchor keeps
+# future versions (e.g. claude-opus-5) unaffected.
 def _is_openai_family_cloud(base_url: Optional[str]) -> bool:
     """True iff ``base_url`` points at OpenAI cloud or Azure OpenAI Foundry.
 
-    Anchored to the URL host so an attacker can't bypass the gate with a
-    path or subdomain like ``https://evil.com/api.openai.com/v1`` or
+    Anchored to the URL host so the gate can't be bypassed with a path or
+    subdomain like ``https://evil.com/api.openai.com/v1`` or
     ``https://api.openai.com.attacker.com/v1`` (CodeQL py/incomplete-url-
-    substring-sanitization). Used to scope cloud-only Responses-API
-    extensions (prompt_cache_retention, context_management compaction,
-    container shell tool) that 400 on non-cloud OpenAI-compatible
-    servers (ollama / llama.cpp / vLLM).
+    substring-sanitization). Scopes cloud-only Responses-API extensions
+    (prompt_cache_retention, context_management compaction, container shell
+    tool) that 400 on non-cloud OpenAI-compatible servers (ollama /
+    llama.cpp / vLLM).
 
-    Azure Foundry resources are scoped to
-    ``<resource-name>.openai.azure.com``; match any subdomain via an
-    `endswith` on the lowercased hostname, with the leading dot so
-    `openai.azure.com` itself doesn't slip through (there is no
-    apex-hosted Azure Foundry endpoint).
+    Azure Foundry resources live at ``<resource-name>.openai.azure.com``;
+    match any subdomain via `endswith` on the lowercased host, with the
+    leading dot so `openai.azure.com` itself doesn't slip through (no
+    apex-hosted Azure Foundry endpoint exists).
     """
     if not base_url:
         return False
@@ -78,10 +74,10 @@ def _openai_image_replay_requires_reasoning(model: str) -> bool:
 def _sanitize_openai_reasoning_replay_item(item: Any) -> Optional[dict[str, Any]]:
     """Return a Responses input-safe reasoning item, if ``item`` is one.
 
-    OpenAI's image-generation docs allow follow-up edits by sending the
-    previous ``image_generation_call`` id. Reasoning models can additionally
-    require the paired ``reasoning`` output item in manually managed context,
-    so keep the public replay fields only and drop everything else.
+    OpenAI image-generation docs allow follow-up edits via the previous
+    ``image_generation_call`` id. Reasoning models can also require the
+    paired ``reasoning`` output item in manually managed context, so keep
+    only the public replay fields and drop everything else.
     """
     if not isinstance(item, dict) or item.get("type") != "reasoning":
         return None
@@ -113,9 +109,9 @@ def _sanitize_openai_reasoning_replay_item(item: Any) -> Optional[dict[str, Any]
 # OpenAI Responses inline citation markers: `citeSOURCE_ID[id2...][LOCATOR]`
 # using private-use codepoints (see
 # https://developers.openai.com/api/docs/guides/citation-formatting).
-# Group 1 holds the delim-separated tokens; each resolvable token expands
-# to `[[N]](URL)`, unresolved tokens (locators, unknown ids) drop silently
-# so no garbled glyph reaches the renderer.
+# Group 1 holds delim-separated tokens; each resolvable token expands to
+# `[[N]](URL)`, unresolved tokens (locators, unknown ids) drop silently so
+# no garbled glyph reaches the renderer.
 _OPENAI_CITE_OPEN = "cite"
 _OPENAI_CITE_STOP = ""
 _OPENAI_CITE_DELIM = ""
@@ -128,7 +124,7 @@ def _build_citation_lookup(url_citations: list[dict[str, Any]]) -> dict[str, tup
     """Map every known ``source_id`` alias to ``(citation_index, url)``.
 
     Accepts singular ``source_id`` and plural ``source_ids``. First-seen
-    wins on alias collision so an earlier citation keeps its number.
+    wins on collision so an earlier citation keeps its number.
     """
     by_source: dict[str, tuple[int, str]] = {}
     for idx, cit in enumerate(url_citations, start = 1):
@@ -150,17 +146,17 @@ def _build_citation_lookup(url_citations: list[dict[str, Any]]) -> dict[str, tup
 def _replace_openai_citation_markers(text: str, url_citations: list[dict[str, Any]]) -> str:
     """Rewrite `\\ue200cite\\ue202SOURCE_ID[\\ue202LOCATOR]\\ue201` markers into
     `[[N]](URL)` per resolvable id. Multi-source markers expand to one link
-    per id; unresolved tokens drop silently. Idempotent on text without
-    private-use codepoints.
+    per id; unresolved tokens drop. Idempotent on text without private-use
+    codepoints.
     """
     if not text or _OPENAI_CITE_STOP not in text:
         return text
     by_source = _build_citation_lookup(url_citations)
 
     def _sub(match: re.Match[str]) -> str:
-        # Try every delim-split token; unresolved tokens drop silently.
-        # Handles multi-source (all resolve) and source+locator (only the
-        # id resolves, locator drops). Empty result strips the marker.
+        # Try every delim-split token; unresolved tokens drop. Handles
+        # multi-source (all resolve) and source+locator (only id resolves,
+        # locator drops). Empty result strips the marker.
         rendered: list[str] = []
         for tok in match.group(1).split(_OPENAI_CITE_DELIM):
             if not tok:
@@ -181,10 +177,10 @@ def _rewrite_citation_markers_partial(
     """Like ``_replace_openai_citation_markers`` but also reports whether
     any marker referenced a source_id not yet in ``url_citations``.
 
-    The ``annotation.added`` event for a url_citation typically arrives
-    AFTER the delta carrying the marker referencing it. Callers buffer the
-    segment until a later event records the annotation; unresolved markers
-    are left verbatim so a follow-up pass still parses cleanly.
+    A url_citation's ``annotation.added`` event typically arrives AFTER the
+    delta carrying the marker that references it. Callers buffer the segment
+    until a later event records the annotation; unresolved markers are left
+    verbatim so a follow-up pass still parses cleanly.
     """
     if not text or _OPENAI_CITE_STOP not in text:
         return text, False
@@ -205,7 +201,7 @@ def _rewrite_citation_markers_partial(
             rendered.append(f"[[{idx}]]({url})")
         # Leave the whole marker verbatim if any token is unresolved so the
         # caller can re-run once the late annotation lands; partial emission
-        # would lose the unresolved ids once the source text is dropped.
+        # would lose unresolved ids once the source text is dropped.
         if any_unresolved:
             has_unresolved = True
             return match.group(0)
@@ -222,14 +218,14 @@ def _split_pending_citation_tail(text: str) -> tuple[str, str]:
     unterminated tail is buffered and prepended onto the next delta so the
     rewriter sees a complete marker. ``pending_tail`` is the longest suffix
     starting with ``\\ue200`` and lacking ``\\ue201``; ``head`` is safe to
-    emit. Empty tail when ``text`` has no open marker or a fully closed one.
+    emit. Empty tail when ``text`` has no open or a fully closed marker.
     """
     if not text:
         return text, ""
     last_open = text.rfind("")
     if last_open == -1:
         return text, ""
-    # Stop byte after the last open byte means the marker closed in this delta.
+    # A stop byte after the last open byte means the marker closed here.
     if _OPENAI_CITE_STOP in text[last_open:]:
         return text, ""
     return text[:last_open], text[last_open:]
@@ -271,11 +267,10 @@ def _anthropic_thinking_spec(model: str) -> Optional[_AnthropicThinkingSpec]:
 # tool-reference docs (https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference)
 # the newer `_20260209` / `_20260120` variants only run on Opus 4.6/4.7
 # and Sonnet 4.6 (web_search / web_fetch) or Opus 4.5+ and Sonnet 4.5+
-# (code_execution). Sending the new versions to an older model returns
-# 400 "tool not supported", and sending the old versions on a new model
-# misses the dynamic-filtering and free-with-search pricing path. Pick
-# the newest combination the model accepts, falling back to the GA
-# (`_20250305` / `_20250910` / `_20250825`) defaults for everything else.
+# (code_execution). New versions on an older model return 400 "tool not
+# supported"; old versions on a new model miss the dynamic-filtering and
+# free-with-search pricing path. Pick the newest combination the model
+# accepts, else the GA (`_20250305` / `_20250910` / `_20250825`) defaults.
 _ANTHROPIC_NEW_WEB_PREFIXES = (
     "claude-opus-4-7",
     "claude-opus-4-6",
@@ -314,18 +309,18 @@ def _anthropic_code_execution_version(model: str) -> str:
     )
 
 
-# Anthropic's beta-header flag for code execution does NOT change with
-# the tool version -- both `_20250825` and `_20260120` are unlocked by
-# the same `code-execution-2025-08-25` header per the upstream docs.
+# Anthropic's beta-header flag for code execution does NOT change with the
+# tool version -- both `_20250825` and `_20260120` are unlocked by the same
+# `code-execution-2025-08-25` header per the upstream docs.
 _ANTHROPIC_CODE_EXECUTION_BETA = "code-execution-2025-08-25"
 
 
 # Anthropic server-side context compaction (beta as of compact-2026-01-12).
-# Per the docs, the compaction tool is currently supported on Opus 4.6,
-# Opus 4.7, Sonnet 4.6 and Mythos Preview. The beta header is the same
-# for every supported model; the dated `compact_20260112` type lives in
-# the body's `context_management.edits` array. Anything sent to a model
-# outside this prefix list is silently ignored so we don't 400 upstream.
+# The compaction tool currently supports Opus 4.6, Opus 4.7, Sonnet 4.6 and
+# Mythos Preview. The beta header is the same for every supported model; the
+# dated `compact_20260112` type lives in the body's
+# `context_management.edits` array. Models outside this prefix list are
+# silently ignored so we don't 400 upstream.
 _ANTHROPIC_COMPACTION_PREFIXES = (
     "claude-opus-4-7",
     "claude-opus-4-6",
@@ -334,8 +329,8 @@ _ANTHROPIC_COMPACTION_PREFIXES = (
 )
 _ANTHROPIC_COMPACTION_BETA = "compact-2026-01-12"
 _ANTHROPIC_COMPACTION_TYPE = "compact_20260112"
-# The docs require the threshold to be at least 50K tokens; lower values
-# would 400. We clamp on the way out so a UI slider can't underflow.
+# The threshold must be >= 50K tokens; lower 400s. Clamp on the way out so
+# a UI slider can't underflow.
 _ANTHROPIC_COMPACTION_MIN = 50_000
 
 
@@ -355,13 +350,12 @@ def _anthropic_supports_compaction(model: str) -> bool:
 
 def _anthropic_supports_fast_mode(model: str) -> bool:
     # Require a family boundary ("" or "-") after the prefix so IDs like
-    # "claude-opus-4-70" / "claude-opus-4-7b" do not match.
+    # "claude-opus-4-70" / "claude-opus-4-7b" don't match.
     return any(model == p or model.startswith(f"{p}-") for p in _ANTHROPIC_FAST_MODE_PREFIXES)
 
 
-# Cap on ``cited_text`` forwarded in document_citations tool_events;
-# keeps SSE bytes bounded on multi-KB cited spans (frontend trims to
-# 240 chars anyway).
+# Cap on ``cited_text`` forwarded in document_citations tool_events; bounds
+# SSE bytes on multi-KB cited spans (frontend trims to 240 chars anyway).
 _CITED_TEXT_MAX_LEN = 512
 
 
@@ -370,12 +364,11 @@ def _anthropic_citation_key(citation: dict[str, Any]) -> tuple:
 
     Anchor fields vary per type (char_location, page_location,
     content_block_location, search_result_location); both start AND
-    exclusive end indices are part of the key so same-start /
-    different-end pairs stay distinct. search_result_location keys on
-    ``search_result_index`` + ``source`` instead of document_index so
-    distinct results with the same source don't collapse. Unknown
-    shapes fall back to a stringified copy (more entries, never
-    collisions). See
+    exclusive end indices are in the key so same-start / different-end pairs
+    stay distinct. search_result_location keys on ``search_result_index`` +
+    ``source`` instead of document_index so distinct results with the same
+    source don't collapse. Unknown shapes fall back to a stringified copy
+    (more entries, never collisions). See
     https://platform.claude.com/docs/en/build-with-claude/citations
     and https://platform.claude.com/docs/en/build-with-claude/search-results.
     """
@@ -462,9 +455,9 @@ def _apply_mistral_reasoning_controls(
     """
     Translate generic reasoning controls into Mistral's model-specific shape.
 
-    Current contract:
+    Contract:
       - magistral-medium-latest: baseline (no extra field) or
-        `prompt_mode="reasoning"` for the explicit reasoning mode.
+        `prompt_mode="reasoning"` for explicit reasoning mode.
       - mistral-small-latest / mistral-vibe-cli-latest:
         `reasoning_effort` in {"none", "high"}.
       - all other tested Mistral models: no reasoning/thinking params.
@@ -475,8 +468,8 @@ def _apply_mistral_reasoning_controls(
     body.pop("reasoning_effort", None)
 
     if spec.style == "prompt_mode":
-        # Magistral baseline is already reasoning-capable. The explicit
-        # prompt_mode path is only used for the "high" UI selection.
+        # Magistral baseline is already reasoning-capable; the explicit
+        # prompt_mode path is only for the "high" UI selection.
         if enable_thinking is True or reasoning_effort == "high":
             body["prompt_mode"] = "reasoning"
         return
@@ -491,8 +484,8 @@ def _apply_mistral_reasoning_controls(
 
 
 # Shared client reused across all requests for HTTP connection pooling.
-# Auth headers and timeouts are passed per-request, so a single client
-# handles every provider without storing credentials.
+# Auth headers and timeouts are per-request, so one client handles every
+# provider without storing credentials.
 _http_client = httpx.AsyncClient()
 
 
@@ -508,15 +501,15 @@ def _safe_fetch_image_for_gemini_sync(
 ) -> Optional[tuple[str, str]]:
     """Synchronous IP-pinned HTTPS image fetch with SSRF guards.
 
-    Uses the same pinned-IP + SNI pattern as `tools._fetch_page_text` so
-    DNS rebinding between validation and the actual connection cannot
-    redirect us to a private/metadata address. Follows up to 4 hops,
-    re-validating each redirect target. Returns (mime, base64) or None.
+    Uses the same pinned-IP + SNI pattern as `tools._fetch_page_text` so DNS
+    rebinding between validation and the connection cannot redirect us to a
+    private/metadata address. Follows up to 4 hops, re-validating each
+    redirect target. Returns (mime, base64) or None.
 
-    `max_bytes` is clamped to the per-image cap and additionally lets
-    the caller pass the remaining per-request budget so an over-budget
-    URL is rejected via Content-Length (or read short-circuit) instead
-    of being fully downloaded then discarded after the fact.
+    `max_bytes` is clamped to the per-image cap and also lets the caller pass
+    the remaining per-request budget, so an over-budget URL is rejected via
+    Content-Length (or read short-circuit) instead of being fully downloaded
+    then discarded.
     """
     import urllib.error
     import urllib.request
@@ -527,7 +520,7 @@ def _safe_fetch_image_for_gemini_sync(
     if _byte_limit <= 0:
         return None
 
-    # Share tools.py's pinned-IP hardening: validate-once-then-pin.
+    # Reuse tools.py's pinned-IP hardening: validate-once-then-pin.
     from .tools import (
         _NoRedirect,
         _SNIHTTPSHandler,
@@ -537,7 +530,7 @@ def _safe_fetch_image_for_gemini_sync(
     def _safe_parse_https(raw_url: str) -> Optional[tuple[Any, str, int]]:
         """Validate https + hostname + port. Returns (parsed, host, port) or
         None. Handles malformed-port and malformed-bracketed-IPv6 URLs that
-        would otherwise raise ValueError mid-build.
+        would else raise ValueError mid-build.
         """
         try:
             parsed_url = urlparse(raw_url)
@@ -576,7 +569,7 @@ def _safe_fetch_image_for_gemini_sync(
         return None
 
     for _hop in range(4):
-        # Pin to validated IP; SNI + cert still use hostname via _SNIHTTPSHandler.
+        # Pin to validated IP; SNI + cert still use the hostname via _SNIHTTPSHandler.
         cp_info = _safe_parse_https(current_url)
         if cp_info is None:
             return None
@@ -643,7 +636,7 @@ def _safe_fetch_image_for_gemini_sync(
                 logger.info("Gemini image fetch: status=%s host=%s", status, current_host)
                 return None
             _hdr_mime = (resp.headers.get("content-type") or "").split(";")[0].strip().lower()
-            # Declared non-image MIME is a refusal; missing MIME falls back to caller's.
+            # Declared non-image MIME is refused; missing MIME uses the caller's.
             if _hdr_mime and not _hdr_mime.startswith("image/"):
                 logger.info(
                     "Gemini image fetch: non-image content-type=%s host=%s",
@@ -689,31 +682,29 @@ async def _safe_fetch_image_for_gemini(
 ) -> Optional[tuple[str, str]]:
     """Async wrapper running the IP-pinned fetch on a worker thread.
 
-    SSRF guards (https only, pinned IP, per-hop redirect re-check, size
-    cap, image/* content-type) live in the sync helper. `max_bytes`
-    carries the remaining per-request budget so over-budget URLs are
-    rejected up front.
+    SSRF guards (https only, pinned IP, per-hop redirect re-check, size cap,
+    image/* content-type) live in the sync helper. `max_bytes` carries the
+    remaining per-request budget so over-budget URLs are rejected up front.
     """
     import asyncio
     return await asyncio.to_thread(_safe_fetch_image_for_gemini_sync, url, fallback_mime, max_bytes)
 
 
 # Synthetic-tool names stamped onto outbound _toolEvent.arguments so the
-# frontend can distinguish provider-side cards from real user-declared
-# tools of the same name. Mirrored on the TS side.
+# frontend can tell provider-side cards from real user-declared tools of the
+# same name. Mirrored on the TS side.
 _SERVER_SIDE_BUILTIN_TOOL_NAMES = frozenset(
     {"web_search", "web_fetch", "code_execution", "image_generation"}
 )
 
 
 def _stamp_server_tool_marker(payload: dict[str, Any]) -> None:
-    """Tag synthetic provider-side tool events so the frontend can
-    distinguish them from real user-declared / local function tools of
-    the same name. The marker rides on `arguments._server_tool` and is
-    only added for known server-side builtin names; user-supplied
-    tool calls echoed back through these helpers (e.g. Kimi
-    `$web_search`) keep their existing shape because we keep this scoped
-    to the canonical builtin names.
+    """Tag synthetic provider-side tool events so the frontend can tell them
+    from real user-declared / local function tools of the same name. The
+    marker rides on `arguments._server_tool` and is only added for known
+    server-side builtin names; user-supplied tool calls echoed back through
+    these helpers (e.g. Kimi `$web_search`) keep their shape because this
+    stays scoped to the canonical builtin names.
     """
     if not isinstance(payload, dict):
         return
@@ -734,11 +725,11 @@ def _build_kimi_tool_end(
 ) -> str:
     """Format Kimi web_search citations into the tool_end payload.
 
-    Same shape parseSourcesFromResult on the frontend expects for the
-    other built-in web_search providers: `Title: ...\\nURL: ...\\n
-    Snippet: ...\\n---\\n...`. If no citations were emitted, fall back
-    to a generic "(search complete)" string so the UI still shows the
-    tool card transitioning to a completed state.
+    Same shape the frontend's parseSourcesFromResult expects for the other
+    built-in web_search providers: `Title: ...\\nURL: ...\\n
+    Snippet: ...\\n---\\n...`. If no citations were emitted, fall back to a
+    generic "(search complete)" string so the UI still transitions the tool
+    card to completed.
     """
     blocks: list[str] = []
     for cit in citations:
@@ -767,9 +758,9 @@ class ExternalProviderClient:
     ):
         self.provider_type = provider_type
         self.base_url = base_url.rstrip("/")
-        # Strip a legacy `/openai` suffix from Google-hosted bases so
-        # configs saved before the native switch still route correctly.
-        # Custom proxy paths ending in `/openai` are left untouched.
+        # Strip a legacy `/openai` suffix from Google-hosted bases so configs
+        # saved before the native switch still route correctly. Custom proxy
+        # paths ending in `/openai` are left untouched.
         if self.provider_type == "gemini":
             _parsed_base = urlparse(self.base_url)
             if (
@@ -780,10 +771,10 @@ class ExternalProviderClient:
                 self.base_url = self.base_url[: -len("/openai")]
         self.api_key = api_key
         self._timeout = httpx.Timeout(timeout, connect = 10.0)
-        # Disable read timeout on SSE streams: reasoning-heavy models
-        # pause tens of seconds between bytes while thinking, and httpx's
-        # read timeout is the per-byte gap, not wall clock. connect/write
-        # bounds still surface real network failures.
+        # Disable read timeout on SSE streams: reasoning-heavy models pause
+        # tens of seconds between bytes while thinking, and httpx's read
+        # timeout is the per-byte gap, not wall clock. connect/write bounds
+        # still surface real network failures.
         self._stream_timeout = httpx.Timeout(timeout, connect = 10.0, read = None)
 
     def _auth_headers(self) -> dict[str, str]:
@@ -795,7 +786,7 @@ class ExternalProviderClient:
         auth_prefix = provider_info.get("auth_prefix", "Bearer ")
 
         # Non-Google Gemini bases (LiteLLM, custom gateways) use OAI-compat
-        # Bearer auth, not Google's x-goog-api-key. Override the registry default.
+        # Bearer auth, not Google's x-goog-api-key. Override the default.
         if self.provider_type == "gemini":
             _host = (urlparse(self.base_url).hostname or "").lower()
             if _host != "generativelanguage.googleapis.com":
@@ -807,17 +798,17 @@ class ExternalProviderClient:
         # httpx rejects an empty `Bearer ` value as "Illegal header value".
         if self.api_key:
             headers[auth_header] = f"{auth_prefix}{self.api_key}"
-        # Merge any provider-specific extra headers (e.g. anthropic-version, OpenRouter attribution)
+        # Merge provider-specific extra headers (anthropic-version, OpenRouter attribution).
         headers.update(provider_info.get("extra_headers", {}))
         return headers
 
     def _is_openai_compatible(self) -> bool:
-        """Return False for providers that need request/response translation (e.g. Anthropic)."""
+        """Return False for providers needing request/response translation (e.g. Anthropic)."""
         from core.inference.providers import get_provider_info
 
         info = get_provider_info(self.provider_type) or {}
-        # Google-hosted Gemini uses the native translator; non-Google
-        # bases stay on OAI-compat so LiteLLM / custom proxies still work.
+        # Google-hosted Gemini uses the native translator; non-Google bases
+        # stay on OAI-compat so LiteLLM / custom proxies still work.
         if self.provider_type == "gemini":
             _host = (urlparse(self.base_url).hostname or "").lower()
             if _host != "generativelanguage.googleapis.com":
@@ -849,19 +840,19 @@ class ExternalProviderClient:
         """
         Yield OpenAI-format SSE lines from the external provider.
 
-        For OpenAI-compatible providers, lines are forwarded verbatim.
-        For Anthropic, the native Messages API SSE is translated to OpenAI format.
+        OpenAI-compatible providers forward lines verbatim. For Anthropic, the
+        native Messages API SSE is translated to OpenAI format.
 
         ``top_k`` and ``presence_penalty`` are forwarded only when the caller
-        supplies a value the provider accepts — the frontend's
-        provider-capability map already filters these per provider, so we
-        treat them as opt-in here.
+        supplies a value the provider accepts; the frontend's
+        provider-capability map already filters these per provider, so they're
+        opt-in here.
 
         ``fast_mode`` only applies to Anthropic Opus 4.6 / 4.7 (silently
         dropped elsewhere); adds the beta header and ``speed: "fast"``.
         """
-        # tool_choice="none" hard-disables hosted/builtin tools across
-        # every provider so enabled_tools cannot accidentally bill or leak.
+        # tool_choice="none" hard-disables hosted/builtin tools across every
+        # provider so enabled_tools can't accidentally bill or leak.
         tool_choice_disabled = (
             isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
         )
@@ -870,7 +861,7 @@ class ExternalProviderClient:
             # Gemini speaks its own native REST shape (contents/parts);
             # `_stream_gemini` translates request/response into the OpenAI
             # Chat Completions chunk format the rest of Studio expects.
-            # API reference: https://ai.google.dev/gemini-api/docs
+            # API ref: https://ai.google.dev/gemini-api/docs
             if self.provider_type == "gemini":
                 async for line in self._stream_gemini(
                     messages,
@@ -909,9 +900,9 @@ class ExternalProviderClient:
                 yield line
             return
 
-        # OpenAI moved their flagship models (gpt-5.x) off /v1/chat/completions
-        # — those endpoints return 404 with "This is not a chat model" for the
-        # new families. Route all OpenAI traffic through /v1/responses instead;
+        # OpenAI moved flagship models (gpt-5.x) off /v1/chat/completions —
+        # those endpoints return 404 "This is not a chat model" for the new
+        # families. Route all OpenAI traffic through /v1/responses instead;
         # we translate the Responses SSE back into Chat Completions chunks so
         # the frontend stays endpoint-agnostic.
         if self.provider_type == "openai":
@@ -933,8 +924,8 @@ class ExternalProviderClient:
                 yield line
             return
 
-        # Kimi $web_search needs a 2-call round-trip + thinking off; route
-        # to a helper. Forced-function tool_choice suppresses it.
+        # Kimi $web_search needs a 2-call round-trip + thinking off; route to
+        # a helper. Forced-function tool_choice suppresses it.
         # https://platform.kimi.ai/docs/guide/use-web-search
         _kimi_tool_choice_forced_function = (
             isinstance(tool_choice, dict)
@@ -966,24 +957,24 @@ class ExternalProviderClient:
             "presence_penalty": presence_penalty,
         }
         if max_tokens is not None:
-            # OpenAI newer models (gpt-4o, gpt-5.x) reject max_tokens
+            # Newer OpenAI models (gpt-4o, gpt-5.x) reject max_tokens
             if self.provider_type == "openai":
                 body["max_completion_tokens"] = max_tokens
             else:
                 body["max_tokens"] = max_tokens
 
-        # Drop fields the registry flags as unusable so reasoning-class
-        # models with fixed defaults (Kimi k2.6 etc) don't 400 on pydantic
-        # default values that the route layer still fills in.
+        # Drop fields the registry flags as unusable so reasoning-class models
+        # with fixed defaults (Kimi k2.6 etc) don't 400 on pydantic defaults
+        # the route layer still fills in.
         from core.inference.providers import get_provider_info
 
         provider_info = get_provider_info(self.provider_type) or {}
         for field in provider_info.get("body_omit", ()):
             body.pop(field, None)
 
-        # Kimi thinking is a top-level body field. kimi-k2-thinking is
-        # always on (ignore the toggle); kimi-k2.6 defaults on, can be
-        # disabled. `keep: all` preserves every chunk for the UI panel.
+        # Kimi thinking is a top-level body field. kimi-k2-thinking is always
+        # on (ignore the toggle); kimi-k2.6 defaults on, can be disabled.
+        # `keep: all` preserves every chunk for the UI panel.
         if self.provider_type == "kimi" and enable_thinking is not None:
             if model == "kimi-k2-thinking":
                 # Always on; ignore client toggle to avoid an API-level reject.
@@ -1018,8 +1009,8 @@ class ExternalProviderClient:
                     body["reasoning"] = {"enabled": False}
 
             # OpenRouter web plugin works on every model id including
-            # meta-routers (unlike the `:online` suffix). Forced-function
-            # tool_choice suppresses it, matching Gemini/Anthropic.
+            # meta-routers (unlike `:online`). Forced-function tool_choice
+            # suppresses it, matching Gemini/Anthropic.
             # https://openrouter.ai/docs/guides/features/plugins/web-search
             _or_tool_choice_forced_function = (
                 isinstance(tool_choice, dict)
@@ -1042,10 +1033,10 @@ class ExternalProviderClient:
                     body.get("model"),
                 )
 
-        # Forward OpenAI-style function tools / tool_choice on every
-        # OAI-compat route (incl. custom Gemini OpenAI proxies like
-        # LiteLLM). Without this, callers that wire user-defined tools
-        # silently lose function-calling on non-native providers.
+        # Forward OpenAI-style function tools / tool_choice on every OAI-compat
+        # route (incl. custom Gemini OpenAI proxies like LiteLLM). Without
+        # this, callers wiring user-defined tools silently lose
+        # function-calling on non-native providers.
         if tools:
             body["tools"] = tools
         if tool_choice is not None:
@@ -1084,18 +1075,17 @@ class ExternalProviderClient:
                     yield _error_sse_line(response.status_code, error_text, self.provider_type)
                     return
 
-                # Manual __anext__ (not `async for`) so we can close
-                # the response BEFORE lines_gen, avoiding the httpcore
-                # 1.0 GeneratorExit -> RuntimeError path on Python 3.13.
+                # Manual __anext__ (not `async for`) so we can close the
+                # response BEFORE lines_gen, avoiding the httpcore 1.0
+                # GeneratorExit -> RuntimeError path on Python 3.13.
                 lines_gen = response.aiter_lines().__aiter__()
-                # Diagnostic counters for the OAI-compat path; surfaces
-                # OpenRouter mid-stream errors that would otherwise be
-                # invisible server-side.
+                # Diagnostic counters for the OAI-compat path; surface
+                # OpenRouter mid-stream errors otherwise invisible server-side.
                 event_counts: dict[str, int] = {}
                 chosen_model: Optional[str] = None
-                # OpenRouter has no web_search_call events — citations
-                # arrive as url_citation annotations. Synthesise a
-                # tool_start/tool_end pair to match the OpenAI/Anthropic UX.
+                # OpenRouter has no web_search_call events — citations arrive
+                # as url_citation annotations. Synthesise a tool_start/tool_end
+                # pair to match the OpenAI/Anthropic UX.
                 web_search_active = (
                     self.provider_type == "openrouter"
                     and not tool_choice_disabled
@@ -1129,10 +1119,9 @@ class ExternalProviderClient:
                         return
                     if payload.get("type") != "url_citation":
                         return
-                    # OpenRouter (and OpenAI Chat Completions web_search)
-                    # nest the citation under url_citation; some variants
-                    # ship the fields flat on the annotation itself. Accept
-                    # both.
+                    # OpenRouter (and OpenAI Chat Completions web_search) nest
+                    # the citation under url_citation; some variants ship the
+                    # fields flat on the annotation itself. Accept both.
                     cit = payload.get("url_citation")
                     if not isinstance(cit, dict):
                         cit = payload
@@ -1191,8 +1180,8 @@ class ExternalProviderClient:
                                 event_counts["done"] = event_counts.get("done", 0) + 1
                                 # Emit synthetic tool_end with collected
                                 # citations BEFORE forwarding [DONE], so the
-                                # tool-card transitions to "complete" in the
-                                # UI before the stream closes.
+                                # tool-card transitions to "complete" before
+                                # the stream closes.
                                 if (
                                     web_search_active
                                     and web_search_tool_started
@@ -1208,7 +1197,7 @@ class ExternalProviderClient:
                                 if isinstance(parsed, dict):
                                     # Mid-stream provider error event. OpenRouter
                                     # in particular returns 200 then surfaces the
-                                    # actual failure as an SSE error event.
+                                    # failure as an SSE error event.
                                     if "error" in parsed:
                                         event_counts["error"] = event_counts.get("error", 0) + 1
                                         logger.warning(
@@ -1219,20 +1208,18 @@ class ExternalProviderClient:
                                     else:
                                         event_counts["delta"] = event_counts.get("delta", 0) + 1
                                     # OpenRouter (and most OAI-compat providers)
-                                    # report the underlying model that handled
-                                    # the request in every chunk's `model` field.
-                                    # Latch the first non-empty value so the
-                                    # router-picked model surfaces in logs and
-                                    # is available to the proxy caller.
+                                    # report the handling model in every chunk's
+                                    # `model` field. Latch the first non-empty
+                                    # value so the router-picked model surfaces
+                                    # in logs and reaches the proxy caller.
                                     if chosen_model is None and isinstance(
                                         parsed.get("model"), str
                                     ):
                                         chosen_model = parsed["model"]
-                                    # When the user has web_search on, scan
-                                    # every chunk's delta and message
-                                    # objects for url_citation annotations.
-                                    # Different OpenRouter upstreams place
-                                    # them in different spots.
+                                    # With web_search on, scan every chunk's
+                                    # delta and message objects for url_citation
+                                    # annotations. Different OpenRouter upstreams
+                                    # place them in different spots.
                                     if web_search_active:
                                         choices = parsed.get("choices") or []
                                         if isinstance(choices, list):
@@ -1249,8 +1236,8 @@ class ExternalProviderClient:
                                                         _record_or_url_citation(ann)
                         yield line
                     # Stream ended without [DONE] (some upstreams just close
-                    # the connection). Emit tool_end so the card doesn't
-                    # stay in "running" forever.
+                    # the connection). Emit tool_end so the card doesn't stay
+                    # in "running" forever.
                     if web_search_active and web_search_tool_started and not web_search_tool_ended:
                         yield _build_web_search_tool_end()
                         web_search_tool_ended = True
@@ -1303,30 +1290,30 @@ class ExternalProviderClient:
         Wire flow (per https://platform.kimi.ai/docs/guide/use-web-search):
           1. POST messages with tools=[{type: "builtin_function",
              function: {name: "$web_search"}}] and thinking=disabled.
-          2. Stream the first response — accumulate function.arguments
-             across tool_call deltas until finish_reason="tool_calls".
-             Do NOT forward those tool_call chunks to the client (they
-             are an internal protocol step, not user-visible output).
-          3. Build a second request: original messages + the assistant
-             message carrying the tool_calls + a role=tool message that
-             echoes the same arguments back verbatim (per Kimi docs,
-             the caller "just needs to submit tool_call.function.arguments
-             to Kimi as they are" — the server actually runs the search).
-          4. Stream the second response — that is the final answer the
-             user sees, with search results already incorporated.
+          2. Stream the first response — accumulate function.arguments across
+             tool_call deltas until finish_reason="tool_calls". Do NOT forward
+             those tool_call chunks to the client (internal protocol step, not
+             user-visible output).
+          3. Build a second request: original messages + the assistant message
+             carrying the tool_calls + a role=tool message echoing the same
+             arguments verbatim (per Kimi docs, the caller "just needs to
+             submit tool_call.function.arguments to Kimi as they are" — the
+             server actually runs the search).
+          4. Stream the second response — the final answer the user sees, with
+             search results already incorporated.
 
         We synthesize tool_start (with the parsed query) when step (2)
-        completes, and tool_end (with any url_citation annotations the
-        second stream emits) before [DONE], so the chat UI shows the
-        same web-search tool card as the other providers.
+        completes, and tool_end (with any url_citation annotations the second
+        stream emits) before [DONE], so the chat UI shows the same web-search
+        tool card as other providers.
         """
         url = f"{self.base_url}/chat/completions"
         body: dict[str, Any] = {
             "model": model,
             "messages": messages,
             "stream": True,
-            # $web_search forbids thinking; sending the toggle silently
-            # would have the server reject the request with 400.
+            # $web_search forbids thinking; sending the toggle would make the
+            # server reject the request with 400.
             "thinking": {"type": "disabled"},
             "tools": [{"type": "builtin_function", "function": {"name": "$web_search"}}],
         }
@@ -1438,10 +1425,9 @@ class ExternalProviderClient:
             )
             return
 
-        # If the model decided not to search, fall back to a plain
-        # streaming call without the builtin tool. That mirrors the UX
-        # of every other provider when web_search is on but the model
-        # didn't actually need it.
+        # If the model decided not to search, fall back to a plain streaming
+        # call without the builtin tool. Mirrors the UX of every other
+        # provider when web_search is on but the model didn't need it.
         search_calls = [
             tc for tc in tool_calls_acc.values() if tc["function"]["name"] == "$web_search"
         ]
@@ -1470,7 +1456,7 @@ class ExternalProviderClient:
                         yield _error_sse_line(response.status_code, error_text, self.provider_type)
                         return
                     # Manual __anext__ loop instead of `async for` — see the
-                    # comment in stream_chat_completion for the Python 3.13 +
+                    # stream_chat_completion comment for the Python 3.13 +
                     # httpcore 1.0.x GeneratorExit interaction this avoids.
                     lines_gen = response.aiter_lines().__aiter__()
                     try:
@@ -1497,20 +1483,19 @@ class ExternalProviderClient:
                 )
             return
 
-        # Synthesize tool_start with the parsed search query so the
-        # chat UI's web-search card shows "Searching for: ...".
+        # Synthesize tool_start with the parsed search query so the chat UI's
+        # web-search card shows "Searching for: ...".
         first_args_raw = search_calls[0]["function"]["arguments"] or "{}"
         try:
             first_args = _json.loads(first_args_raw)
         except Exception:
             first_args = {}
-        # Log the raw arguments so we can confirm the server actually
-        # ran the search. The shape is documented loosely but in practice
-        # the model emits `{"search_result":{"search_id":...},
-        # "usage":{"total_tokens":N}}` — an opaque receipt where N is the
-        # token cost of the injected search context. The query string is
-        # NOT present; Kimi runs the search server-side during the first
-        # call and bakes the results straight into the model's context.
+        # Log the raw arguments to confirm the server ran the search. The shape
+        # is loosely documented but in practice the model emits
+        # `{"search_result":{"search_id":...}, "usage":{"total_tokens":N}}` —
+        # an opaque receipt where N is the token cost of the injected search
+        # context. The query string is NOT present; Kimi runs the search
+        # server-side during the first call and bakes the results into context.
         logger.info(
             "Kimi $web_search: %d tool_call(s), args[0]=%s",
             len(search_calls),
@@ -1531,14 +1516,13 @@ class ExternalProviderClient:
                 "arguments": first_args if isinstance(first_args, dict) else {},
             }
         )
-        # Kimi's search has already executed server-side by the time the
-        # first call returns (the tool_call envelope encodes the search
-        # result reference, not a query for us to dispatch). Emit
-        # tool_end NOW so the UI's web-search card transitions to
-        # "complete" before the second call starts streaming the
-        # answer, instead of after — otherwise the card sits in
-        # "running" all the way through the answer streaming and the
-        # user perceives the model answering before search finishes.
+        # Kimi's search has already run server-side by the time the first call
+        # returns (the tool_call envelope encodes the search result reference,
+        # not a query for us to dispatch). Emit tool_end NOW so the UI's
+        # web-search card transitions to "complete" before the second call
+        # streams the answer — otherwise the card sits in "running" through the
+        # whole answer and the user perceives the model answering before search
+        # finishes.
         yield _build_kimi_tool_end(_synthetic_chunk, tool_call_id, [])
 
         # ---- Second call: echo the tool_calls back and stream answer ----
@@ -1558,14 +1542,14 @@ class ExternalProviderClient:
         ]
         followup_body = dict(body)
         followup_body["messages"] = list(messages) + [assistant_msg] + tool_msgs
-        # Ask the SSE stream to include a final `usage` block so we can
-        # see prompt_tokens (which jumps to thousands when the server
-        # injects search context). Without this, OpenAI-compat streams
-        # omit usage entirely. Kimi follows the same convention.
+        # Ask the SSE stream for a final `usage` block so we see prompt_tokens
+        # (which jumps to thousands when the server injects search context).
+        # Without this, OpenAI-compat streams omit usage entirely; Kimi follows
+        # the same convention.
         followup_body["stream_options"] = {"include_usage": True}
-        # Keep the tool definition on the second call so the model can
-        # decide to search again mid-turn if needed. Kimi's doc shows
-        # the same tools array on every step.
+        # Keep the tool definition on the second call so the model can search
+        # again mid-turn if needed. Kimi's doc shows the same tools array on
+        # every step.
 
         try:
             async with _http_client.stream(
@@ -1587,10 +1571,10 @@ class ExternalProviderClient:
                     return
 
                 lines_gen = response.aiter_lines().__aiter__()
-                # Diagnostics: latch usage.prompt_tokens from the final
-                # chunk. The Kimi docs say search results count toward
-                # prompt_tokens, so a big value here is direct evidence
-                # the server actually injected results into context.
+                # Diagnostics: latch usage.prompt_tokens from the final chunk.
+                # Kimi docs say search results count toward prompt_tokens, so a
+                # big value here is direct evidence the server injected results
+                # into context.
                 last_usage: Optional[dict[str, Any]] = None
                 annotation_shapes: set[str] = set()
                 try:
@@ -1614,9 +1598,9 @@ class ExternalProviderClient:
                                         last_usage = usage
                                     # Scan annotations only for diagnostics —
                                     # Kimi today doesn't emit url_citation, but
-                                    # if a future model version starts to we'll
-                                    # see the type name in the final log line
-                                    # and can wire it into the tool_end payload.
+                                    # if a future version does we'll see the
+                                    # type name in the final log line and can
+                                    # wire it into the tool_end payload.
                                     for choice in parsed.get("choices") or []:
                                         if not isinstance(choice, dict):
                                             continue
@@ -1687,7 +1671,7 @@ class ExternalProviderClient:
         """
         import json as _json
 
-        # Extract system prompt and translate image_url parts to Anthropic format
+        # Extract system prompt; translate image_url parts to Anthropic format
         system: Optional[str] = None
         filtered: list[dict[str, Any]] = []
         for msg in messages:
@@ -1702,10 +1686,10 @@ class ExternalProviderClient:
 
             content = msg.get("content")
             # OpenAI role="tool" with list content -> Anthropic native
-            # tool_result block on a user message. Translating in the
-            # string-content branch only (below) leaves the list-content
-            # form forwarded as an invalid `role:"tool"` message that
-            # Anthropic rejects. Handle both upfront.
+            # tool_result block on a user message. Translating only in the
+            # string-content branch (below) would forward the list-content form
+            # as an invalid `role:"tool"` message Anthropic rejects. Handle both
+            # upfront.
             if msg.get("role") == "tool":
                 _tr_id = msg.get("tool_call_id") or ""
                 if isinstance(content, list):
@@ -1749,12 +1733,11 @@ class ExternalProviderClient:
                     if part.get("type") == "text":
                         anthropic_parts.append({"type": "text", "text": part["text"]})
                     elif part.get("type") == "compaction":
-                        # Round-trip the compaction block. When the
-                        # prior assistant turn ran server-side
-                        # compaction, that block must land back on this
-                        # turn's assistant message so Anthropic skips
-                        # re-compaction from scratch. Forward verbatim
-                        # under the {type:"compaction", content:"..."}
+                        # Round-trip the compaction block. When the prior
+                        # assistant turn ran server-side compaction, that block
+                        # must land back on this turn's assistant message so
+                        # Anthropic skips re-compaction from scratch. Forward
+                        # verbatim under the {type:"compaction", content:"..."}
                         # shape the API expects. See
                         #   https://platform.claude.com/docs/en/build-with-claude/compaction
                         summary = part.get("content") or ""
@@ -1777,7 +1760,7 @@ class ExternalProviderClient:
                                 }
                             )
                         else:
-                            # Remote URL -- Anthropic supports url source type natively.
+                            # Remote URL -- Anthropic supports the url source type natively.
                             # See: https://docs.anthropic.com/en/docs/build-with-claude/vision#url-based-images
                             anthropic_parts.append(
                                 {
@@ -1793,16 +1776,15 @@ class ExternalProviderClient:
                         # for PDFs / docs. The frontend sends either
                         # `{type:"input_document", file_data:"data:application/pdf;base64,..."}`
                         # or `{type:"input_document", file_url:"https://..."}`,
-                        # plus optional `filename` and `media_type`.
-                        # Translate to Anthropic's native `document` block.
+                        # plus optional `filename` and `media_type`. Translate
+                        # to Anthropic's native `document` block.
                         url = part.get("file_url") or ""
                         data_uri = part.get("file_data") or ""
                         title = part.get("filename")
-                        # Treat any "data:" URI with no actual base64
-                        # payload (`data:application/pdf;base64,` or
-                        # whitespace-only) as missing so the file_url
-                        # branch below can take over. Matches the
-                        # OpenAI-side fallback so a malformed inline
+                        # Treat any "data:" URI with no actual base64 payload
+                        # (`data:application/pdf;base64,` or whitespace-only) as
+                        # missing so the file_url branch below can take over.
+                        # Matches the OpenAI-side fallback so a malformed inline
                         # payload + valid remote URL still attaches.
                         data_uri_valid = False
                         b64data = ""
@@ -1844,11 +1826,10 @@ class ExternalProviderClient:
                             if title:
                                 doc_block["title"] = title
                             anthropic_parts.append(doc_block)
-                # Assistant tool_calls -> Anthropic tool_use blocks
-                # appended to the same message. Anthropic native
-                # Messages API does not accept OpenAI's top-level
-                # `tool_calls` field; the call lives inside a content
-                # block with `{type:"tool_use", id, name, input}`.
+                # Assistant tool_calls -> Anthropic tool_use blocks appended to
+                # the same message. The native Messages API doesn't accept
+                # OpenAI's top-level `tool_calls` field; the call lives inside a
+                # content block `{type:"tool_use", id, name, input}`.
                 if msg.get("role") == "assistant" and isinstance(msg.get("tool_calls"), list):
                     for _tc in msg["tool_calls"]:
                         if not isinstance(_tc, dict):
@@ -1871,17 +1852,16 @@ class ExternalProviderClient:
                                 "input": _input,
                             }
                         )
-                # Skip whole-message append when nothing usable survived.
-                # An empty content array (e.g. user dropped only an unparseable
-                # `input_document`) would 400 the Anthropic API with
-                # "messages.N.content: at least one block is required".
+                # Skip whole-message append when nothing usable survived. An
+                # empty content array (e.g. user dropped only an unparseable
+                # `input_document`) would 400 with "messages.N.content: at
+                # least one block is required".
                 if anthropic_parts:
                     filtered.append({"role": msg["role"], "content": anthropic_parts})
             else:
-                # role="tool" follow-up -> Anthropic native tool_result
-                # block on a `user` message. The OpenAI shape
-                # (role=tool, content=string, tool_call_id) is not a
-                # valid Anthropic role.
+                # role="tool" follow-up -> Anthropic native tool_result block
+                # on a `user` message. The OpenAI shape (role=tool,
+                # content=string, tool_call_id) is not a valid Anthropic role.
                 if msg.get("role") == "tool":
                     _tr_id = msg.get("tool_call_id") or ""
                     _tr_content = msg.get("content")
@@ -1904,11 +1884,10 @@ class ExternalProviderClient:
                         }
                     )
                     continue
-                # Assistant turn whose content is a plain string but
-                # also carries OpenAI `tool_calls`: convert into a
-                # content-array message with a text block + tool_use
-                # blocks. Without this, the top-level tool_calls leaks
-                # through unchanged.
+                # Assistant turn whose content is a plain string but also
+                # carries OpenAI `tool_calls`: convert into a content-array
+                # message with a text block + tool_use blocks. Without this,
+                # the top-level tool_calls leaks through unchanged.
                 if (
                     msg.get("role") == "assistant"
                     and isinstance(msg.get("tool_calls"), list)
@@ -1944,12 +1923,12 @@ class ExternalProviderClient:
                     continue
                 filtered.append(msg)
 
-        # Claude 4.7 family removed temperature / top_p / top_k entirely.
-        # The earlier guard only handled top_k; temperature is now also
-        # rejected with 400 "temperature is deprecated for this model".
-        # Latch the match once and reuse it everywhere temperature or
-        # top_k would otherwise be set — including the thinking-mode
-        # override below, which used to force temperature=1.
+        # Claude 4.7 family removed temperature / top_p / top_k entirely. The
+        # earlier guard only handled top_k; temperature is now also rejected
+        # with 400 "temperature is deprecated for this model". Latch the match
+        # once and reuse it everywhere temperature or top_k would be set —
+        # including the thinking-mode override below, which used to force
+        # temperature=1.
         sampling_removed = bool(_ANTHROPIC_4_7_SAMPLING_REMOVED.match(model))
 
         body: dict[str, Any] = {
@@ -1962,15 +1941,14 @@ class ExternalProviderClient:
             body["temperature"] = temperature
         if top_k is not None and top_k > 0 and not sampling_removed:
             body["top_k"] = top_k
-        # Anthropic only caches a prefix when at least one cache_control
-        # marker is attached to it — the frontend defaults
-        # enable_prompt_caching to True for Anthropic, so treat `None` the
-        # same as True here (callers that don't set the flag still get
-        # caching). Pass False explicitly to opt out.
+        # Anthropic only caches a prefix when at least one cache_control marker
+        # is attached. The frontend defaults enable_prompt_caching to True for
+        # Anthropic, so treat `None` as True here (callers that don't set the
+        # flag still get caching). Pass False explicitly to opt out.
         prompt_caching_enabled = enable_prompt_caching is not False
-        # Optional 1h cache TTL is GA as of 2026-05 (no beta header). 1h
-        # writes are 2x vs 5m's 1.25x but reads are 0.1x for both, so 1h
-        # wins after a single extra hit. Unknown TTL strings drop.
+        # Optional 1h cache TTL is GA as of 2026-05 (no beta header). 1h writes
+        # are 2x vs 5m's 1.25x but reads are 0.1x for both, so 1h wins after a
+        # single extra hit. Unknown TTL strings drop.
         cache_marker: dict[str, Any] = {"type": "ephemeral"}
         if prompt_cache_ttl in ("5m", "1h"):
             cache_marker["ttl"] = prompt_cache_ttl
@@ -1989,14 +1967,13 @@ class ExternalProviderClient:
                 body["system"] = system
 
         if prompt_caching_enabled and filtered:
-            # Second breakpoint at the end of the conversation. Anthropic
-            # caches the longest matching prefix up to a cache_control
-            # marker; placing one on the latest message means turn N+1
-            # rehydrates everything up through turn N from cache instead
-            # of recomputing it. This is what makes caching actually work
-            # when the system prompt is empty or shorter than Anthropic's
-            # ~1024-token cache floor — the conversation history carries
-            # the bulk of the input tokens. Anthropic allows up to 4
+            # Second breakpoint at the end of the conversation. Anthropic caches
+            # the longest matching prefix up to a cache_control marker; placing
+            # one on the latest message means turn N+1 rehydrates everything
+            # through turn N from cache instead of recomputing. This makes
+            # caching work when the system prompt is empty or shorter than
+            # Anthropic's ~1024-token cache floor — the conversation history
+            # carries the bulk of input tokens. Anthropic allows up to 4
             # breakpoints per request; we use at most 2 (system + tail).
             last_msg = filtered[-1]
             content = last_msg.get("content")
@@ -2010,9 +1987,9 @@ class ExternalProviderClient:
                 ]
             elif isinstance(content, list) and content:
                 # Don't mutate the caller's list. Rebuild the tail with
-                # cache_control attached to the final block so an
-                # upstream image-bearing turn still cleanly slots into
-                # the cache as part of the conversational prefix.
+                # cache_control on the final block so an upstream image-bearing
+                # turn still cleanly slots into the cache as part of the
+                # conversational prefix.
                 head = list(content[:-1])
                 tail = content[-1]
                 if isinstance(tail, dict):
@@ -2027,8 +2004,8 @@ class ExternalProviderClient:
         effort = reasoning_effort if reasoning_effort in allowed_efforts else None
         # Claude 4.6 Opus/Sonnet accept top-tier adaptive effort as "max" only;
         # "xhigh" is rejected (supported on Claude 4.7). Map our shared "xhigh"
-        # semantic to "max" for 4.6 outbound requests while still accepting
-        # both in ``allowed_efforts`` for persisted / cross-provider UI state.
+        # to "max" for 4.6 outbound requests while still accepting both in
+        # ``allowed_efforts`` for persisted / cross-provider UI state.
         if effort == "xhigh" and model.startswith(("claude-opus-4-6", "claude-sonnet-4-6")):
             effort = "max"
         if effort is None:
@@ -2041,31 +2018,30 @@ class ExternalProviderClient:
         if effort and effort != "none":
             # Anthropic rejects top_k whenever thinking is enabled.
             body.pop("top_k", None)
-            # Earlier families (4.5/4.6) require temperature=1 when
-            # thinking is enabled and forbid top_p in the same request:
+            # Earlier families (4.5/4.6) require temperature=1 when thinking is
+            # enabled and forbid top_p in the same request:
             #   "temperature and top_p cannot both be specified for this
             #    model. Please use only one."
-            # On Claude 4.7, temperature was removed entirely — sending
-            # any value (including 1) returns 400 — so skip the override
-            # there and let the model use its default sampling.
+            # On Claude 4.7, temperature was removed entirely — any value
+            # (including 1) returns 400 — so skip the override there and let
+            # the model use its default sampling.
             if not sampling_removed:
                 body["temperature"] = 1
             body.pop("top_p", None)
             if thinking_spec and thinking_spec.kind == "adaptive":
                 # `display` defaults to "omitted" on Claude Opus 4.7 (per the
-                # adaptive-thinking docs) — without an explicit opt-in the
-                # API emits an empty thinking block plus a signature_delta,
-                # so our SSE handler would surface a stray <think></think>
-                # and the reasoning panel would stay blank. Force
-                # "summarized" so 4.7 streams thinking_delta events like
-                # 4.6 does. On 4.6 / Sonnet 4.6 this is the default, so
-                # setting it explicitly is harmless.
+                # adaptive-thinking docs) — without an explicit opt-in the API
+                # emits an empty thinking block plus a signature_delta, so our
+                # SSE handler would surface a stray <think></think> and the
+                # reasoning panel would stay blank. Force "summarized" so 4.7
+                # streams thinking_delta events like 4.6 does. On 4.6 / Sonnet
+                # 4.6 this is the default, so setting it is harmless.
                 body["thinking"] = {"type": "adaptive", "display": "summarized"}
-                # Per the Messages API reference, the effort knob for
-                # adaptive thinking lives under `output_config.effort` —
-                # NOT as a top-level field. Sending `effort: ...` directly
-                # produces a 400 "effort: Extra inputs are not permitted".
-                # Allowed values: low | medium | high | xhigh | max. See:
+                # Per the Messages API reference, the effort knob for adaptive
+                # thinking lives under `output_config.effort` — NOT as a
+                # top-level field. Sending `effort: ...` directly produces a 400
+                # "effort: Extra inputs are not permitted". Allowed values:
+                # low | medium | high | xhigh | max. See:
                 # https://platform.claude.com/docs/en/api/messages
                 body["output_config"] = {"effort": effort}
             elif thinking_spec and thinking_spec.kind == "manual":
@@ -2079,8 +2055,8 @@ class ExternalProviderClient:
                 if body.get("max_tokens", 0) <= budget_tokens:
                     body["max_tokens"] = budget_tokens + 1024
 
-        # tool_choice="none" or pinned-function suppresses hosted tools
-        # so a stale UI toggle can't fire server-side search/code-exec.
+        # tool_choice="none" or pinned-function suppresses hosted tools so a
+        # stale UI toggle can't fire server-side search/code-exec.
         _anthropic_tool_choice_disabled = (
             isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
         )
@@ -2141,13 +2117,13 @@ class ExternalProviderClient:
                 }
             )
             body["tools"] = anthropic_tools
-            # Reuse the thread's prior container so filesystem state
-            # persists. Stale ids 4xx and clear via container_invalidated.
+            # Reuse the thread's prior container so filesystem state persists.
+            # Stale ids 4xx and clear via container_invalidated.
             if anthropic_code_exec_container_id:
                 body["container"] = anthropic_code_exec_container_id
 
-        # Server-side compaction (beta `compact-2026-01-12`). Clamps
-        # below-min thresholds to 50K so the request doesn't 400.
+        # Server-side compaction (beta `compact-2026-01-12`). Clamps below-min
+        # thresholds to 50K so the request doesn't 400.
         # https://platform.claude.com/docs/en/build-with-claude/compaction
         compaction_active = (
             compaction_threshold is not None
@@ -2171,9 +2147,9 @@ class ExternalProviderClient:
                 ]
             }
 
-        # fast_mode is Opus 4.6/4.7 only; silently drop elsewhere.
-        # Incompatible with the Priority service_tier (frontend gate
-        # prevents both at once; backend lets Anthropic 400 if combined).
+        # fast_mode is Opus 4.6/4.7 only; silently drop elsewhere. Incompatible
+        # with the Priority service_tier (frontend gate prevents both at once;
+        # backend lets Anthropic 400 if combined).
         fast_mode_active = bool(fast_mode) and _anthropic_supports_fast_mode(model)
         if fast_mode_active:
             body["speed"] = "fast"
@@ -2182,7 +2158,7 @@ class ExternalProviderClient:
         completion_id = f"chatcmpl-anthropic-{model.replace('/', '-')}"
 
         # Log outgoing config keys (not messages) to prove which thinking /
-        # effort fields actually reached the wire.
+        # effort fields reached the wire.
         logger.info(
             "Anthropic request shape (model=%s, has_thinking=%s, thinking=%s, "
             "output_config=%s, temperature=%s, has_top_p=%s, has_top_k=%s, "
@@ -2197,9 +2173,9 @@ class ExternalProviderClient:
             body.get("max_tokens"),
         )
 
-        # Anthropic stop_reason -> OpenAI finish_reason. `pause_turn`
-        # maps to None so the UI doesn't treat a paused server-tool turn
-        # as final. `refusal` -> "content_filter" (closest match).
+        # Anthropic stop_reason -> OpenAI finish_reason. `pause_turn` maps to
+        # None so the UI doesn't treat a paused server-tool turn as final.
+        # `refusal` -> "content_filter" (closest match).
         # https://platform.claude.com/docs/en/api/messages#response-stop-reason
         _finish_reason_map: dict[str, Optional[str]] = {
             "end_turn": "stop",
@@ -2243,12 +2219,11 @@ class ExternalProviderClient:
                         response.status_code,
                         error_text[:500],
                     )
-                    # Stale container detection (mirror of the OpenAI
-                    # path). When we sent a `container` field and the
-                    # response is 4xx with any hint that the id is
-                    # expired / missing, emit container_invalidated so
-                    # the chat adapter clears the stored id and the
-                    # next turn falls back to auto-create.
+                    # Stale container detection (mirrors the OpenAI path). When
+                    # we sent a `container` field and the response is 4xx hinting
+                    # the id is expired / missing, emit container_invalidated so
+                    # the chat adapter clears the stored id and the next turn
+                    # falls back to auto-create.
                     if anthropic_code_exec_container_id and 400 <= response.status_code < 500:
                         lowered = error_text.lower()
                         if "container" in lowered and (
@@ -2268,47 +2243,44 @@ class ExternalProviderClient:
                 # NOTE: same manual __anext__ loop as stream_chat_completion — see comment there.
                 lines_gen = response.aiter_lines().__aiter__()
                 thinking_open = False
-                # Diagnostic counters for the next time the user reports
-                # "no thinking content" — distinguishes "Anthropic never sent
-                # thinking_delta" from "frontend didn't render the chunks".
+                # Diagnostic counters for "no thinking content" reports —
+                # distinguish "Anthropic never sent thinking_delta" from
+                # "frontend didn't render the chunks".
                 event_counts: dict[str, int] = {}
-                # web_search state. Query streams via input_json_delta
-                # on a server_tool_use block; results land in a separate
+                # web_search state. Query streams via input_json_delta on a
+                # server_tool_use block; results land in a separate
                 # web_search_tool_result block. Per-call citations.
                 current_server_tool_use: Optional[dict[str, Any]] = None
                 current_result_block: Optional[dict[str, Any]] = None
                 web_search_calls: dict[str, dict[str, Any]] = {}
-                # code_execution state (bash / text_editor sub-tools);
-                # kept parallel to web_search so concurrent pills don't collide.
+                # code_execution state (bash / text_editor sub-tools); kept
+                # parallel to web_search so concurrent pills don't collide.
                 current_code_exec_use: Optional[dict[str, Any]] = None
                 current_code_exec_result: Optional[dict[str, Any]] = None
                 code_execution_calls: dict[str, dict[str, Any]] = {}
-                # web_fetch state. Same server_tool_use → *_tool_result
-                # block shape as web_search but the server_tool_use
-                # carries name="web_fetch" and the result block is
-                # `web_fetch_tool_result` with content.type=
-                # `web_fetch_result` (success) or `web_fetch_tool_error`
-                # (failure). Kept separate from web_search state so a
-                # turn that uses both does not collide.
+                # web_fetch state. Same server_tool_use → *_tool_result block
+                # shape as web_search but server_tool_use carries
+                # name="web_fetch" and the result block is
+                # `web_fetch_tool_result` with content.type=`web_fetch_result`
+                # (success) or `web_fetch_tool_error` (failure). Kept separate
+                # from web_search state so a turn using both doesn't collide.
                 current_web_fetch_use: Optional[dict[str, Any]] = None
                 current_web_fetch_result: Optional[dict[str, Any]] = None
                 web_fetch_calls: dict[str, dict[str, Any]] = {}
                 # Compaction state. Server-side compaction emits a
-                # `{type:"compaction", content:"..."}` content block
-                # whenever it runs. The summary text can land on the
-                # start event AND/OR via text_delta events on the same
-                # block (Anthropic's wire format is permissive here).
-                # Accumulate in `current_compaction["content"]` and emit
-                # on content_block_stop so the chat-adapter can persist
-                # it onto the assistant message for round-tripping on
-                # the next turn.
+                # `{type:"compaction", content:"..."}` content block whenever it
+                # runs. The summary text can land on the start event AND/OR via
+                # text_delta events on the same block (Anthropic's wire format
+                # is permissive). Accumulate in `current_compaction["content"]`
+                # and emit on content_block_stop so the chat-adapter can persist
+                # it onto the assistant message for next-turn round-tripping.
                 current_compaction: Optional[dict[str, Any]] = None
                 compaction_blocks_seen = 0
-                # Document citations from ``citations_delta`` events.
-                # Deduped by type-specific anchor key; inline [N] is
-                # injected after each cited run, and the full list is
-                # forwarded as a synthetic document_citations tool_event
-                # on message_stop for the Sources panel.
+                # Document citations from ``citations_delta`` events. Deduped by
+                # type-specific anchor key; inline [N] is injected after each
+                # cited run, and the full list is forwarded as a synthetic
+                # document_citations tool_event on message_stop for the Sources
+                # panel.
                 document_citations: list[dict[str, Any]] = []
                 # Counts surfaced in the final log line so reports of
                 # "Code execution did nothing" can be triaged at a
@@ -2326,12 +2298,12 @@ class ExternalProviderClient:
                 # from the inbound id — no churn on reuse.
                 latched_container_id: Optional[str] = None
                 container_id_emitted = False
-                # Cache usage tracking. message_start carries the input
-                # accounting (incl. cache_creation_input_tokens and
+                # Cache usage tracking. message_start carries input accounting
+                # (incl. cache_creation_input_tokens and
                 # cache_read_input_tokens); message_delta carries cumulative
-                # output_tokens. Both are surfaced in the "stream complete"
-                # log so prompt caching can be verified per-request without
-                # opening the Anthropic dashboard.
+                # output_tokens. Both surface in the "stream complete" log so
+                # prompt caching can be verified per-request without opening the
+                # Anthropic dashboard.
                 last_usage: dict[str, Any] = {}
 
                 def _content_chunk(text: str) -> str:
@@ -2379,20 +2351,18 @@ class ExternalProviderClient:
                     return "\n---\n".join(blocks)
 
                 def _format_web_fetch_result(inner: dict[str, Any]) -> str:
-                    """Render a `web_fetch_tool_result.content` payload
-                    as the Title / URL / snippet block CodeExecutionToolUI
-                    and parseSourcesFromResult already expect from the
-                    web_search path.
+                    """Render a `web_fetch_tool_result.content` payload as the
+                    Title / URL / snippet block CodeExecutionToolUI and
+                    parseSourcesFromResult expect from the web_search path.
 
                     Success shape (text):
                         {type: web_fetch_result, url, retrieved_at,
                          content: {type: document, source: {type: text,
                                    media_type, data}, title?}}
                     Success shape (pdf): source.type=base64 + media_type=
-                        application/pdf. We do not surface the base64
-                        bytes; the title + url is enough for the source
-                        pill, and the model still sees the document
-                        contents on its side.
+                        application/pdf. We don't surface the base64 bytes; the
+                        title + url is enough for the source pill, and the model
+                        still sees the document contents.
                     Error shape: {type: web_fetch_tool_error, error_code}.
                     """
                     inner_type = inner.get("type") or ""
@@ -2408,15 +2378,15 @@ class ExternalProviderClient:
                         if isinstance(source, dict):
                             media_type = source.get("media_type") or ""
                             data = source.get("data") or ""
-                            # Inline a short text preview so the source
-                            # pill carries usable context; skip for PDFs
-                            # since the body is base64-encoded.
+                            # Inline a short text preview so the source pill
+                            # carries usable context; skip for PDFs (body is
+                            # base64-encoded).
                             if media_type.startswith("text/") and isinstance(data, str) and data:
                                 snippet = data[:240].strip()
-                    # Frontend parseSourcesFromResult only emits a source
-                    # pill when both `Title:` and `URL:` are present, so
-                    # fall back to the URL when Anthropic omits the
-                    # document title (matches the web_search formatter).
+                    # Frontend parseSourcesFromResult only emits a source pill
+                    # when both `Title:` and `URL:` are present, so fall back to
+                    # the URL when Anthropic omits the document title (matches
+                    # the web_search formatter).
                     if not title and url:
                         title = url
                     parts: list[str] = []
@@ -2429,11 +2399,11 @@ class ExternalProviderClient:
                     return "\n".join(parts) if parts else "(fetch complete)"
 
                 def _format_code_execution_result(inner: dict[str, Any]) -> str:
-                    """Render an Anthropic code-execution result block as
-                    the preformatted text payload the frontend's
-                    CodeExecutionToolUI displays inside a <pre>. Handles
-                    bash, text_editor (view/create/str_replace), and the
-                    matching error variants.
+                    """Render an Anthropic code-execution result block as the
+                    preformatted text payload the frontend's
+                    CodeExecutionToolUI displays inside a <pre>. Handles bash,
+                    text_editor (view/create/str_replace), and the matching
+                    error variants.
                     """
                     inner_type = inner.get("type") or ""
                     if inner_type.endswith("_error"):
@@ -2453,9 +2423,9 @@ class ExternalProviderClient:
                     if inner_type == "text_editor_code_execution_result":
                         # view: file content; create: is_file_update flag;
                         # str_replace: diff `lines` list. The matching
-                        # server_tool_use carries the command + path, but
-                        # that's encoded into the tool_start arguments
-                        # already — here we only format the result body.
+                        # server_tool_use carries the command + path, already
+                        # encoded into tool_start arguments — here we only
+                        # format the result body.
                         if "lines" in inner and isinstance(inner.get("lines"), list):
                             return "\n".join(str(line) for line in inner["lines"])
                         if "is_file_update" in inner:
@@ -2494,11 +2464,11 @@ class ExternalProviderClient:
                             key = event_type or "<unknown>"
                         event_counts[key] = event_counts.get(key, 0) + 1
 
-                        # message_start carries the input-side usage block
-                        # including cache_creation_input_tokens and
+                        # message_start carries the input-side usage block incl.
+                        # cache_creation_input_tokens and
                         # cache_read_input_tokens. message_delta updates
-                        # output_tokens (and may overwrite the input fields
-                        # with final values). Merge both into last_usage.
+                        # output_tokens (and may overwrite the input fields with
+                        # final values). Merge both into last_usage.
                         if event_type == "message_start":
                             start_usage = (event.get("message") or {}).get("usage")
                             if isinstance(start_usage, dict):
@@ -2522,10 +2492,10 @@ class ExternalProviderClient:
                                 }
                             elif block_type == "web_search_tool_result":
                                 tool_use_id = content_block.get("tool_use_id", "")
-                                # Anthropic sometimes ships the full results
-                                # list on the start event; sometimes deltas
-                                # follow. Capture whatever is present and
-                                # finalize on content_block_stop.
+                                # Anthropic sometimes ships the full results list
+                                # on the start event; sometimes deltas follow.
+                                # Capture whatever is present and finalize on
+                                # content_block_stop.
                                 content = content_block.get("content") or []
                                 current_result_block = {
                                     "tool_use_id": tool_use_id,
@@ -2574,12 +2544,12 @@ class ExternalProviderClient:
                                 "bash_code_execution_tool_result",
                                 "text_editor_code_execution_tool_result",
                             ):
-                                # Anthropic ships the full result content
-                                # on the start event for code-exec result
-                                # blocks (unlike web_search, which can
-                                # split across deltas). Capture it and
-                                # finalize on content_block_stop so the
-                                # ordering matches the web_search path.
+                                # Anthropic ships the full result content on the
+                                # start event for code-exec result blocks
+                                # (unlike web_search, which can split across
+                                # deltas). Capture it and finalize on
+                                # content_block_stop so ordering matches the
+                                # web_search path.
                                 tool_use_id = content_block.get("tool_use_id", "")
                                 inner = content_block.get("content") or {}
                                 current_code_exec_result = {
@@ -2607,19 +2577,18 @@ class ExternalProviderClient:
                                     yield _content_chunk(thinking_text)
                             elif delta_type == "text_delta":
                                 text = delta.get("text", "")
-                                # text_deltas inside a compaction block
-                                # carry the summary chunks; route them
-                                # into the compaction buffer and DON'T
-                                # yield them to the user-visible stream
-                                # -- the summary is opaque internal
-                                # state, not assistant prose.
+                                # text_deltas inside a compaction block carry
+                                # summary chunks; route them into the compaction
+                                # buffer and DON'T yield them to the
+                                # user-visible stream -- the summary is opaque
+                                # internal state, not assistant prose.
                                 if current_compaction is not None:
                                     if text:
                                         current_compaction["content"] += text
                                 else:
                                     # First text after a thinking block closes the
-                                    # <think> tag we opened above. Anthropic emits
-                                    # a content_block_stop between blocks, but
+                                    # <think> tag opened above. Anthropic emits a
+                                    # content_block_stop between blocks, but
                                     # closing on the text_delta transition is more
                                     # forgiving if events arrive out of order.
                                     if thinking_open:
@@ -2630,9 +2599,8 @@ class ExternalProviderClient:
                                     # web_search citations: web_search_tool_result.
                                     # User-doc citations: citations_delta below.
                             elif delta_type == "citations_delta":
-                                # One citation per event; collapse onto a
-                                # numbered footnote list and inject [N]
-                                # inline. See
+                                # One citation per event; collapse onto a numbered
+                                # footnote list and inject [N] inline. See
                                 # https://platform.claude.com/docs/en/build-with-claude/citations
                                 cit = delta.get("citation")
                                 if isinstance(cit, dict):
@@ -2647,14 +2615,13 @@ class ExternalProviderClient:
                                         idx_for_marker = len(document_citations)
                                     yield _content_chunk(f"[{idx_for_marker}]")
                             elif delta_type == "input_json_delta":
-                                # Streamed partial_json carrying tool inputs
-                                # — the search query for web_search, or the
-                                # command/path/etc. for code execution.
-                                # Route to whichever buffer is open. The two
-                                # state slots are exclusive in practice
-                                # (Anthropic doesn't interleave tool input
-                                # streams), but checking both keeps the
-                                # dispatch robust if that ever changes.
+                                # Streamed partial_json carrying tool inputs —
+                                # the search query for web_search, or
+                                # command/path/etc. for code execution. Route to
+                                # whichever buffer is open. The state slots are
+                                # exclusive in practice (Anthropic doesn't
+                                # interleave tool input streams), but checking
+                                # all keeps the dispatch robust if that changes.
                                 partial = delta.get("partial_json", "")
                                 if current_server_tool_use is not None:
                                     current_server_tool_use["buffer"] += partial
@@ -2662,17 +2629,17 @@ class ExternalProviderClient:
                                     current_code_exec_use["buffer"] += partial
                                 elif current_web_fetch_use is not None:
                                     current_web_fetch_use["buffer"] += partial
-                            # signature_delta and any other delta types are
-                            # intentionally skipped — they carry trust /
-                            # verification metadata, not user-visible content.
+                            # signature_delta and other delta types are skipped
+                            # — they carry trust / verification metadata, not
+                            # user-visible content.
 
                         elif event_type == "content_block_stop":
                             if current_server_tool_use is not None:
                                 # End of the server_tool_use block — parse the
-                                # accumulated input_json into a query and
-                                # emit tool_start. The matching tool_end fires
-                                # later when the web_search_tool_result block
-                                # closes with the actual results.
+                                # accumulated input_json into a query and emit
+                                # tool_start. The matching tool_end fires later
+                                # when the web_search_tool_result block closes
+                                # with the actual results.
                                 buffer = current_server_tool_use["buffer"]
                                 query = ""
                                 if buffer:
@@ -2697,11 +2664,10 @@ class ExternalProviderClient:
                                 )
                                 current_server_tool_use = None
                             elif current_result_block is not None:
-                                # End of a web_search_tool_result — emit
-                                # tool_end carrying the search results as
-                                # Title:/URL: blocks. parseSourcesFromResult
-                                # on the frontend lifts these into source
-                                # pills at message tail.
+                                # End of a web_search_tool_result — emit tool_end
+                                # carrying the search results as Title:/URL:
+                                # blocks. The frontend's parseSourcesFromResult
+                                # lifts these into source pills at message tail.
                                 tool_use_id = current_result_block["tool_use_id"]
                                 results = current_result_block["results"]
                                 if tool_use_id in web_search_calls:
@@ -2716,11 +2682,11 @@ class ExternalProviderClient:
                                 )
                                 current_result_block = None
                             elif current_code_exec_use is not None:
-                                # End of a code-execution server_tool_use —
-                                # parse the buffered input_json into a
-                                # {command, path, ...} dict and emit
-                                # tool_start. The matching tool_end fires
-                                # on the result block's content_block_stop.
+                                # End of a code-execution server_tool_use — parse
+                                # the buffered input_json into a {command, path,
+                                # ...} dict and emit tool_start. The matching
+                                # tool_end fires on the result block's
+                                # content_block_stop.
                                 buffer = current_code_exec_use["buffer"]
                                 parsed_args: dict[str, Any] = {}
                                 if buffer:
@@ -2746,13 +2712,12 @@ class ExternalProviderClient:
                                 current_code_exec_use = None
                             elif current_compaction is not None:
                                 # End of a compaction block. Emit it as a
-                                # synthetic tool_event so the chat-adapter
-                                # can persist the {type:"compaction",
-                                # content:"..."} payload onto the
-                                # assistant message. The next turn's
-                                # request body forwards the content_part
-                                # verbatim and Anthropic recognises it
-                                # as the prior compaction state.
+                                # synthetic tool_event so the chat-adapter can
+                                # persist the {type:"compaction", content:"..."}
+                                # payload onto the assistant message. The next
+                                # turn's request body forwards the content_part
+                                # verbatim and Anthropic recognises it as the
+                                # prior compaction state.
                                 compaction_blocks_seen += 1
                                 yield _emit_tool_event(
                                     {
@@ -2762,13 +2727,13 @@ class ExternalProviderClient:
                                 )
                                 current_compaction = None
                             elif current_code_exec_result is not None:
-                                # End of a code-execution result block —
-                                # format the inner result into the text
-                                # payload CodeExecutionToolUI renders.
+                                # End of a code-execution result block — format
+                                # the inner result into the text payload
+                                # CodeExecutionToolUI renders.
                                 tool_use_id = current_code_exec_result["tool_use_id"]
                                 inner = current_code_exec_result["inner"]
-                                # Track generated-file count for the
-                                # follow-up Files API PR. v1 drops them.
+                                # Track generated-file count for the follow-up
+                                # Files API PR. v1 drops them.
                                 if isinstance(inner, dict):
                                     file_blocks = inner.get("content")
                                     if isinstance(file_blocks, list):
@@ -2789,11 +2754,10 @@ class ExternalProviderClient:
                                 )
                                 current_code_exec_result = None
                             elif current_web_fetch_use is not None:
-                                # End of the web_fetch server_tool_use —
-                                # parse the buffered input_json into the
-                                # URL the model asked Anthropic to fetch
-                                # and emit tool_start. The matching
-                                # tool_end fires on the result block's
+                                # End of the web_fetch server_tool_use — parse the
+                                # buffered input_json into the URL the model asked
+                                # Anthropic to fetch and emit tool_start. The
+                                # matching tool_end fires on the result block's
                                 # content_block_stop just below.
                                 buffer = current_web_fetch_use["buffer"]
                                 url = ""
@@ -2823,15 +2787,14 @@ class ExternalProviderClient:
                                 )
                                 current_web_fetch_use = None
                             elif current_web_fetch_result is not None:
-                                # End of the web_fetch_tool_result —
-                                # format Title / URL / snippet for the
-                                # frontend source pill and emit tool_end.
-                                # `inner` is sanitised to a dict at the
-                                # matching content_block_start, and the
-                                # formatter always returns a non-empty
-                                # string (defaulting to "(fetch complete)"
-                                # when no fields are present), so no
-                                # extra fallback is needed here.
+                                # End of the web_fetch_tool_result — format Title
+                                # / URL / snippet for the frontend source pill
+                                # and emit tool_end. `inner` is sanitised to a
+                                # dict at the matching content_block_start, and
+                                # the formatter always returns a non-empty string
+                                # (defaulting to "(fetch complete)" when no
+                                # fields are present), so no extra fallback is
+                                # needed here.
                                 tool_use_id = current_web_fetch_result["tool_use_id"]
                                 result_text = _format_web_fetch_result(
                                     current_web_fetch_result["inner"]
@@ -2849,8 +2812,8 @@ class ExternalProviderClient:
                             elif thinking_open:
                                 # Close the <think> tag when the thinking block
                                 # ends, in case no text_delta follows (e.g.
-                                # display=omitted on Claude 4.7, or thinking-
-                                # only turns).
+                                # display=omitted on Claude 4.7, or
+                                # thinking-only turns).
                                 yield _content_chunk("</think>")
                                 thinking_open = False
 
@@ -2872,14 +2835,14 @@ class ExternalProviderClient:
                                     if c_in or c_out:
                                         last_usage["compaction_input_tokens"] = c_in
                                         last_usage["compaction_output_tokens"] = c_out
-                            # Anthropic reports the code_execution container
-                            # id on `message_delta.delta.container.{id,
-                            # expires_at}` (NOT on message_start — at start
-                            # the container hasn't been provisioned yet).
-                            # Latch on first sight and emit container_ready
-                            # only when the value differs from the inbound
-                            # id, so steady-state reuse doesn't re-write
-                            # the same id to the thread record every turn.
+                            # Anthropic reports the code_execution container id
+                            # on `message_delta.delta.container.{id,
+                            # expires_at}` (NOT on message_start — at start the
+                            # container isn't provisioned yet). Latch on first
+                            # sight and emit container_ready only when the value
+                            # differs from the inbound id, so steady-state reuse
+                            # doesn't re-write the same id to the thread record
+                            # every turn.
                             delta_obj = event.get("delta") or {}
                             container_obj = delta_obj.get("container")
                             if isinstance(container_obj, dict) and latched_container_id is None:
@@ -2903,16 +2866,15 @@ class ExternalProviderClient:
                                 if thinking_open:
                                     yield _content_chunk("</think>")
                                     thinking_open = False
-                                # `pause_turn` is in-progress, not terminal:
-                                # the SSE stream still ends with [DONE] via
+                                # `pause_turn` is in-progress, not terminal: the
+                                # SSE stream still ends with [DONE] via
                                 # message_stop but we skip emitting a
-                                # finish_reason="stop" chunk that would
-                                # truncate the rendered message in the UI.
+                                # finish_reason="stop" chunk that would truncate
+                                # the rendered message in the UI.
                                 mapped = _finish_reason_map.get(stop_reason, "stop")
-                                # Streaming refusal: emit a visible notice
-                                # plus an out-of-band _toolEvent so the
-                                # frontend can prune the refused turn.
-                                # The mapped finish_reason is
+                                # Streaming refusal: emit a visible notice plus an
+                                # out-of-band _toolEvent so the frontend can prune
+                                # the refused turn. The mapped finish_reason is
                                 # "content_filter" per OpenAI spec.
                                 # https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals
                                 if stop_reason == "refusal":
@@ -2920,9 +2882,9 @@ class ExternalProviderClient:
                                         "Anthropic refusal stop_reason (model=%s)",
                                         model,
                                     )
-                                    # Drop signal rides _toolEvent (not
-                                    # text) so assistant content cannot
-                                    # spoof a context reset.
+                                    # Drop signal rides _toolEvent (not text) so
+                                    # assistant content can't spoof a context
+                                    # reset.
                                     yield _content_chunk(
                                         "\n\n_The response was stopped by "
                                         "Anthropic's safety classifier. Edit "
@@ -2948,10 +2910,10 @@ class ExternalProviderClient:
                             if thinking_open:
                                 yield _content_chunk("</think>")
                                 thinking_open = False
-                            # Forward document_citations so the Sources
-                            # panel can render the inline [N] footnotes.
-                            # ``cited_text`` is truncated server-side to
-                            # keep SSE bytes bounded on long spans.
+                            # Forward document_citations so the Sources panel
+                            # can render the inline [N] footnotes. ``cited_text``
+                            # is truncated server-side to keep SSE bytes bounded
+                            # on long spans.
                             if document_citations:
                                 clean_cits = []
                                 for c in document_citations:
@@ -2966,9 +2928,9 @@ class ExternalProviderClient:
                                         "citations": clean_cits,
                                     }
                                 )
-                            # Final include_usage-style chunk so callers can
-                            # see cache_creation / cache_read without
-                            # scraping the server log.
+                            # Final include_usage-style chunk so callers see
+                            # cache_creation / cache_read without scraping the
+                            # server log.
                             usage_line = _build_usage_chunk(
                                 completion_id,
                                 "anthropic",
@@ -2985,8 +2947,8 @@ class ExternalProviderClient:
                     raise
                 finally:
                     # Surface per-event-type counts + web_search summary so
-                    # reports of "no reasoning panel content" / "Search
-                    # didn't do anything" can be triaged at a glance.
+                    # reports of "no reasoning panel content" / "Search didn't
+                    # do anything" can be triaged at a glance.
                     web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                     web_search_invocations = len(web_search_calls)
                     total_results = sum(
@@ -2994,11 +2956,10 @@ class ExternalProviderClient:
                     )
                     queries = [sc["query"] for sc in web_search_calls.values() if sc.get("query")]
                     # cache_read_input_tokens > 0 on turn N proves the
-                    # cache_control marker on the system block is doing
-                    # its job — turn 1 will show cache_creation > 0
-                    # instead. cache_creation tokens are billed at a
-                    # small premium; cache_read tokens are billed at a
-                    # discount.
+                    # cache_control marker on the system block is working —
+                    # turn 1 shows cache_creation > 0 instead. cache_creation
+                    # tokens are billed at a small premium; cache_read tokens
+                    # at a discount.
                     code_execution_invocations = len(code_execution_calls)
                     code_execution_results = sum(
                         1 for c in code_execution_calls.values() if c.get("result") is not None
@@ -3089,11 +3050,10 @@ class ExternalProviderClient:
     ) -> AsyncGenerator[str, None]:
         """
         Call Google's native Gemini API and translate its streaming
-        ``streamGenerateContent`` response into OpenAI Chat Completions
-        chunk format.
+        ``streamGenerateContent`` response into OpenAI Chat Completions chunks.
 
-        Gemini does NOT speak the OpenAI Chat Completions contract on
-        its primary endpoint. The wire shape is:
+        Gemini does NOT speak the OpenAI Chat Completions contract on its
+        primary endpoint. The wire shape is:
 
           POST /v1beta/models/{model}:streamGenerateContent?alt=sse
           {
@@ -3113,12 +3073,11 @@ class ExternalProviderClient:
            "usageMetadata": {"promptTokenCount": 7, "candidatesTokenCount": 3}}
 
         Image generation uses the same endpoint with model
-        ``gemini-2.5-flash-image`` (also called Nano Banana); the
-        response carries an ``inlineData`` part with the base64 PNG
-        bytes and a ``mimeType``. We surface that through the same
-        ``tool_start`` / ``tool_end`` ``image_b64`` envelope the OpenAI
-        image_generation path uses, so the chat UI renders the image
-        inline with no extra plumbing.
+        ``gemini-2.5-flash-image`` (Nano Banana); the response carries an
+        ``inlineData`` part with base64 PNG bytes and a ``mimeType``. We surface
+        that through the same ``tool_start`` / ``tool_end`` ``image_b64``
+        envelope the OpenAI image_generation path uses, so the chat UI renders
+        the image inline with no extra plumbing.
 
         References:
           - https://ai.google.dev/gemini-api/docs/text-generation
@@ -3129,12 +3088,12 @@ class ExternalProviderClient:
         """
         import json as _json
 
-        # Validate the user-controlled model id BEFORE any message
-        # translation. A model like `../cachedContents/x` is path-
-        # traversal that lands in `/v1beta/cachedContents/...`; rejecting
-        # it here also avoids triggering user-controlled outbound fetches
-        # (remote image_url inlining) on a request we'll error out
-        # anyway. Documented catalog ids match `[A-Za-z0-9._-]+`.
+        # Validate the user-controlled model id BEFORE any message translation.
+        # A model like `../cachedContents/x` is path-traversal landing in
+        # `/v1beta/cachedContents/...`; rejecting it here also avoids triggering
+        # user-controlled outbound fetches (remote image_url inlining) on a
+        # request we'll error out anyway. Documented catalog ids match
+        # `[A-Za-z0-9._-]+`.
         if not re.fullmatch(r"[A-Za-z0-9._-]+", model):
             yield _error_sse_line(
                 400,
@@ -3143,21 +3102,21 @@ class ExternalProviderClient:
             )
             return
 
-        # Translate OpenAI messages -> Gemini contents. system role
-        # promotes to top-level systemInstruction.
+        # Translate OpenAI messages -> Gemini contents. system role promotes to
+        # top-level systemInstruction.
         system_text_parts: list[str] = []
         contents: list[dict[str, Any]] = []
-        # OpenAI may drop `name` from role="tool" follow-ups. Remember
-        # prior function names so functionResponse isn't sent name-less
-        # (Gemini 400s on empty names).
+        # OpenAI may drop `name` from role="tool" follow-ups. Remember prior
+        # function names so functionResponse isn't sent name-less (Gemini 400s
+        # on empty names).
         tool_call_names: dict[str, str] = {}
-        # tool_call_ids whose assistant card was dropped (synthetic
-        # builtin) or already replayed as native parts. Their role="tool"
-        # follow-up must be skipped to avoid orphan/duplicate responses.
+        # tool_call_ids whose assistant card was dropped (synthetic builtin) or
+        # already replayed as native parts. Their role="tool" follow-up must be
+        # skipped to avoid orphan/duplicate responses.
         _gemini_skip_tool_result_ids: set[str] = set()
-        # Per-request image caps. The byte cap counts DECODED bytes; we
-        # set it to ~14 MB because base64 expansion + prompt overhead
-        # must fit Gemini's ~20 MB request limit.
+        # Per-request image caps. The byte cap counts DECODED bytes; set to
+        # ~14 MB because base64 expansion + prompt overhead must fit Gemini's
+        # ~20 MB request limit.
         _GEMINI_REMOTE_IMAGE_MAX_COUNT = 8
         _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES = 14 * 1024 * 1024
         _remote_image_count = 0
@@ -3201,12 +3160,11 @@ class ExternalProviderClient:
                                 header.split(";")[0].replace("data:", "").strip().lower()
                                 or "image/jpeg"
                             )
-                            # Symmetry with the fetched remote image
-                            # path, which already rejects non-image
-                            # Content-Type. A `data:text/html;base64,...`
-                            # URL otherwise lands as Gemini inlineData
-                            # with mimeType="text/html" and 400s the
-                            # whole request.
+                            # Symmetry with the fetched remote image path, which
+                            # already rejects non-image Content-Type. A
+                            # `data:text/html;base64,...` URL otherwise lands as
+                            # Gemini inlineData with mimeType="text/html" and
+                            # 400s the whole request.
                             if not media_type.startswith("image/"):
                                 logger.info(
                                     "Gemini inlineData: refusing non-image data URL media_type=%s",
@@ -3240,11 +3198,11 @@ class ExternalProviderClient:
                                         }
                                     )
                         elif url:
-                            # fileData.fileUri only accepts Files-API URIs
-                            # and YouTube; everything else must be downloaded
-                            # and inlined. Parse fields explicitly so
-                            # attacker URLs like https://evil.com/youtube.com/x
-                            # aren't misclassified as YouTube.
+                            # fileData.fileUri only accepts Files-API URIs and
+                            # YouTube; everything else must be downloaded and
+                            # inlined. Parse fields explicitly so attacker URLs
+                            # like https://evil.com/youtube.com/x aren't
+                            # misclassified as YouTube.
                             try:
                                 _parsed_image_url = urlparse(url)
                             except (ValueError, UnicodeError):
@@ -3299,9 +3257,9 @@ class ExternalProviderClient:
                                     _GEMINI_REMOTE_IMAGE_MAX_COUNT,
                                 )
                             else:
-                                # Refuse pre-fetch when the per-request
-                                # byte budget is spent; pass the remainder
-                                # so over-budget URLs reject on Content-Length.
+                                # Refuse pre-fetch when the per-request byte
+                                # budget is spent; pass the remainder so
+                                # over-budget URLs reject on Content-Length.
                                 _remaining_bytes = (
                                     _GEMINI_REMOTE_IMAGE_MAX_TOTAL_BYTES - _remote_image_total_bytes
                                 )
@@ -3310,8 +3268,8 @@ class ExternalProviderClient:
                                         "Gemini image fetch: per-request byte cap already reached, dropping image",
                                     )
                                 else:
-                                    # Count attempts before awaiting so
-                                    # slow URLs don't each burn the timeout.
+                                    # Count attempts before awaiting so slow URLs
+                                    # don't each burn the timeout.
                                     _remote_image_count += 1
                                     _fetched = await _safe_fetch_image_for_gemini(
                                         url,
@@ -3340,10 +3298,9 @@ class ExternalProviderClient:
                                                 }
                                             )
             # Gemini 3 strict function-calling requires text-part
-            # thoughtSignatures to be replayed on history; the frontend
-            # stows the latest one as
-            # extra_content.google.thought_signature on the assistant
-            # message and we pin it onto the last text part here.
+            # thoughtSignatures to be replayed on history; the frontend stows
+            # the latest one as extra_content.google.thought_signature on the
+            # assistant message and we pin it onto the last text part here.
             if role == "assistant" and parts:
                 _msg_extra = msg.get("extra_content") if isinstance(msg, dict) else None
                 if isinstance(_msg_extra, dict):
@@ -3360,8 +3317,8 @@ class ExternalProviderClient:
                                     break
             # Translate OpenAI tool_calls into Gemini functionCall parts.
             # code_execution / image_generation replay their native parts
-            # (executableCode / codeExecutionResult / inlineData) stowed
-            # on extra_content.google.native_part.
+            # (executableCode / codeExecutionResult / inlineData) stowed on
+            # extra_content.google.native_part.
             tool_calls = msg.get("tool_calls") if isinstance(msg, dict) else None
             if isinstance(tool_calls, list):
                 for tc in tool_calls:
@@ -3385,9 +3342,9 @@ class ExternalProviderClient:
                     if fn_name and isinstance(tc_id, str) and tc_id:
                         tool_call_names[tc_id] = fn_name
 
-                    # Replay native Gemini code_execution / image_generation parts
-                    # from extra_content.google.native_part, with fallback to
-                    # args.google.native_part for OAI-compat round-trips.
+                    # Replay native Gemini code_execution / image_generation
+                    # parts from extra_content.google.native_part, falling back
+                    # to args.google.native_part for OAI-compat round-trips.
                     _extra = tc.get("extra_content")
                     _native_part = None
                     _google_extra: dict[str, Any] = {}
@@ -3405,8 +3362,8 @@ class ExternalProviderClient:
                                 if not _google_extra:
                                     _google_extra = _args_google
 
-                    # Synthetic builtin cards (web_search/web_fetch) must
-                    # not become fake functionCalls; drop them. Native
+                    # Synthetic builtin cards (web_search/web_fetch) must not
+                    # become fake functionCalls; drop them. Native
                     # code_execution / image_generation replay below.
                     _name_lc = fn_name.lower() if isinstance(fn_name, str) else ""
                     _is_synthetic_server_builtin = (
@@ -3427,11 +3384,10 @@ class ExternalProviderClient:
                         _name_lc in ("code_execution", "image_generation")
                         and isinstance(_native_part, dict)
                     ):
-                        # No replayable Gemini native part -- skip
-                        # entirely rather than send a fake functionCall.
-                        # Also remember this tool_call_id so a matching
-                        # role="tool" follow-up does not become an
-                        # orphan functionResponse below.
+                        # No replayable Gemini native part -- skip entirely
+                        # rather than send a fake functionCall. Also remember
+                        # this tool_call_id so a matching role="tool" follow-up
+                        # doesn't become an orphan functionResponse below.
                         if isinstance(tc_id, str) and tc_id:
                             _gemini_skip_tool_result_ids.add(tc_id)
                             tool_call_names.pop(tc_id, None)
@@ -3439,20 +3395,18 @@ class ExternalProviderClient:
                     if fn_name in ("code_execution", "image_generation") and isinstance(
                         _native_part, dict
                     ):
-                        # code_execution/image_generation history is
-                        # replayed as native parts; the matching
-                        # role="tool" must be skipped or Gemini sees a
-                        # functionResponse with no declared function
-                        # name and 400s the turn.
+                        # code_execution/image_generation history is replayed as
+                        # native parts; the matching role="tool" must be skipped
+                        # or Gemini sees a functionResponse with no declared
+                        # function name and 400s the turn.
                         if isinstance(tc_id, str) and tc_id:
                             _gemini_skip_tool_result_ids.add(tc_id)
-                        # New shape: `native_part.parts` is an ordered list
-                        # of full part wrappers, each carrying its own
-                        # `thoughtSignature`. This preserves Gemini 3's
-                        # strict per-part replay requirement when the
-                        # frontend has merged executableCode +
-                        # codeExecutionResult + inlineData into the same
-                        # tool-call card.
+                        # New shape: `native_part.parts` is an ordered list of
+                        # full part wrappers, each carrying its own
+                        # `thoughtSignature`. Preserves Gemini 3's strict
+                        # per-part replay requirement when the frontend merged
+                        # executableCode + codeExecutionResult + inlineData into
+                        # the same tool-call card.
                         _native_parts_list = _native_part.get("parts")
                         if isinstance(_native_parts_list, list):
                             for _entry in _native_parts_list:
@@ -3460,9 +3414,9 @@ class ExternalProviderClient:
                                     parts.append(_entry)
                             continue
                         # Legacy single-object native_part: fan the shared
-                        # thoughtSignature only when one subpart exists;
-                        # for code+result, prefer executableCode and drop
-                        # the signature elsewhere.
+                        # thoughtSignature only when one subpart exists; for
+                        # code+result, prefer executableCode and drop the
+                        # signature elsewhere.
                         _legacy_sig = _native_part.get("thoughtSignature") or _native_part.get(
                             "thought_signature"
                         )
@@ -3493,10 +3447,10 @@ class ExternalProviderClient:
                         continue
 
                     # Forward the OpenAI tool_call id into Gemini's
-                    # functionCall.id so a follow-up turn that issues
-                    # multiple calls to the same function (different
-                    # args, same name) can be disambiguated on the
-                    # response side. Gemini accepts the field per
+                    # functionCall.id so a follow-up turn issuing multiple calls
+                    # to the same function (different args, same name) can be
+                    # disambiguated on the response side. Gemini accepts the
+                    # field per
                     # https://ai.google.dev/gemini-api/docs/function-calling.
                     function_call_part: dict[str, Any] = {
                         "name": fn_name,
@@ -3505,11 +3459,11 @@ class ExternalProviderClient:
                     if isinstance(tc_id, str) and tc_id:
                         function_call_part["id"] = tc_id
                     # Gemini 3 function-calling requires the prior
-                    # thoughtSignature to be echoed back as a sibling
-                    # of the functionCall part. The translator stows
-                    # it on the assistant tool_call via
-                    # `extra_content.google.thought_signature` (see
-                    # the inbound emit below).
+                    # thoughtSignature echoed back as a sibling of the
+                    # functionCall part. The translator stows it on the
+                    # assistant tool_call via
+                    # `extra_content.google.thought_signature` (see the inbound
+                    # emit below).
                     fc_part: dict[str, Any] = {"functionCall": function_call_part}
                     sig = _google_extra.get("thought_signature") or _google_extra.get(
                         "thoughtSignature"
@@ -3518,23 +3472,23 @@ class ExternalProviderClient:
                         fc_part["thoughtSignature"] = sig
                     parts.append(fc_part)
             if role == "tool":
-                # If the matching assistant-side tool_call was either
-                # dropped (synthetic server-tool with no native part)
-                # or already replayed as Gemini-native parts
-                # (code_execution/image_generation native_part), drop
-                # the follow-up too. Emitting it as a functionResponse
-                # would be orphaned or duplicate the native result.
+                # If the matching assistant-side tool_call was dropped
+                # (synthetic server-tool with no native part) or already
+                # replayed as Gemini-native parts
+                # (code_execution/image_generation native_part), drop the
+                # follow-up too. Emitting it as a functionResponse would be
+                # orphaned or duplicate the native result.
                 _tc_id_for_skip = msg.get("tool_call_id")
                 if (
                     isinstance(_tc_id_for_skip, str)
                     and _tc_id_for_skip in _gemini_skip_tool_result_ids
                 ):
                     continue
-                # OpenAI's role="tool" follow-up carries the function
-                # result. Gemini's matching shape is a role="user" turn
-                # with a functionResponse part. When the caller dropped
-                # ``name``, recover it from the matching assistant
-                # tool_call so Gemini doesn't 400 on an empty name.
+                # OpenAI's role="tool" follow-up carries the function result.
+                # Gemini's matching shape is a role="user" turn with a
+                # functionResponse part. When the caller dropped ``name``,
+                # recover it from the matching assistant tool_call so Gemini
+                # doesn't 400 on an empty name.
                 tool_name = msg.get("name") or msg.get("tool_name") or ""
                 if not tool_name:
                     tc_id = msg.get("tool_call_id")
@@ -3546,9 +3500,9 @@ class ExternalProviderClient:
                     # (`[{"type":"text","text":"..."}]`). Forwarding the
                     # content-part objects verbatim into Gemini's
                     # `functionResponse.response.result` yields
-                    # `result:[{"type":"text","text":"..."}]` instead of
-                    # the actual tool output text; flatten text parts so
-                    # the result mirrors the string-content path.
+                    # `result:[{"type":"text","text":"..."}]` instead of the
+                    # actual tool output text; flatten text parts so the result
+                    # mirrors the string-content path.
                     _flat_parts: list[str] = []
                     for _cpart in content:
                         if (
@@ -3577,22 +3531,21 @@ class ExternalProviderClient:
                         else {"result": response_payload}
                     ),
                 }
-                # Mirror tool_call_id onto functionResponse.id so
-                # Gemini can match the result to the originating
-                # functionCall when multiple parallel calls were made.
+                # Mirror tool_call_id onto functionResponse.id so Gemini can
+                # match the result to the originating functionCall when multiple
+                # parallel calls were made.
                 tc_id = msg.get("tool_call_id")
                 if isinstance(tc_id, str) and tc_id:
                     function_response_part["id"] = tc_id
                 parts = [{"functionResponse": function_response_part}]
                 gemini_role = "user"
             if parts:
-                # Gemini expects parallel functionResponses (multiple
-                # OpenAI role="tool" messages in a row) to ride on a
-                # single user content with multiple functionResponse
-                # parts -- the docs show parallel responses grouped
-                # together in the next turn. Merge consecutive
-                # functionResponse-only user blocks so realistic
-                # parallel tool loops round-trip correctly.
+                # Gemini expects parallel functionResponses (multiple OpenAI
+                # role="tool" messages in a row) to ride on a single user
+                # content with multiple functionResponse parts -- the docs show
+                # parallel responses grouped in the next turn. Merge consecutive
+                # functionResponse-only user blocks so realistic parallel tool
+                # loops round-trip correctly.
                 if (
                     role == "tool"
                     and contents
@@ -3610,9 +3563,9 @@ class ExternalProviderClient:
         if system_text_parts:
             body["systemInstruction"] = {"parts": [{"text": "\n\n".join(system_text_parts)}]}
 
-        # Generation config -- temperature / topP / topK / maxOutputTokens
-        # map straight across. The frontend capability matrix restricts
-        # the sliders the UI exposes for Gemini to this set.
+        # Generation config -- temperature / topP / topK / maxOutputTokens map
+        # straight across. The frontend capability matrix restricts the sliders
+        # the UI exposes for Gemini to this set.
         gen_config: dict[str, Any] = {}
         if temperature is not None:
             gen_config["temperature"] = temperature
@@ -3620,29 +3573,29 @@ class ExternalProviderClient:
             gen_config["topP"] = top_p
         if top_k is not None and top_k > 0:
             gen_config["topK"] = top_k
-        # Gemini accepts ``presencePenalty`` on generationConfig with the
-        # same sign convention as the OpenAI knob (positive discourages
-        # repetition). Forward when the caller bothers to set it.
+        # Gemini accepts ``presencePenalty`` on generationConfig with the same
+        # sign convention as the OpenAI knob (positive discourages repetition).
+        # Forward when the caller sets it.
         if presence_penalty:
             gen_config["presencePenalty"] = presence_penalty
         if max_tokens is not None:
             gen_config["maxOutputTokens"] = max_tokens
 
         # Nano Banana image generation. Gemini only accepts
-        # `responseModalities: ["TEXT","IMAGE"]` on the image-capable
-        # model family (id contains `-image` or `nano-banana`). Text-
-        # only models such as `gemini-2.5-flash` 400 on the same body,
-        # so only force image mode when the selected model actually
-        # supports it -- a stale `enabled_tools=["image_generation"]`
-        # on a text model is silently treated as a regular turn.
+        # `responseModalities: ["TEXT","IMAGE"]` on the image-capable model
+        # family (id contains `-image` or `nano-banana`). Text-only models such
+        # as `gemini-2.5-flash` 400 on the same body, so only force image mode
+        # when the selected model supports it -- a stale
+        # `enabled_tools=["image_generation"]` on a text model is silently
+        # treated as a regular turn.
         # https://ai.google.dev/gemini-api/docs/image-generation
         model_lc = model.lower()
         is_image_picker_model = "-image" in model_lc or "nano-banana" in model_lc
-        # tool_choice="none" / forced-function tool_choice must also
-        # suppress the implicit image-generation hosted tool. Otherwise
-        # an explicit OpenAI-style opt-out (or an explicit user-function
-        # pin) still flips `responseModalities=["TEXT","IMAGE"]` on
-        # image-tier models and bills for image output.
+        # tool_choice="none" / forced-function tool_choice must also suppress
+        # the implicit image-generation hosted tool. Otherwise an explicit
+        # OpenAI-style opt-out (or user-function pin) still flips
+        # `responseModalities=["TEXT","IMAGE"]` on image-tier models and bills
+        # for image output.
         _tool_choice_disabled = (
             isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
         )
@@ -3653,15 +3606,14 @@ class ExternalProviderClient:
             and bool(tool_choice["function"].get("name"))
         )
         _hosted_builtins_allowed = not _tool_choice_disabled and not _tool_choice_forced_function
-        # Image-tier model IDs reject text-only tools (code_execution,
-        # user functions) and thinkingConfig regardless of whether the
-        # Images pill is on -- those are model-level constraints
-        # documented by Google. The pill only controls whether we ask
-        # Gemini to actually emit image output via
-        # `responseModalities: ["TEXT","IMAGE"]`. Decoupling the two
-        # avoids the case where Images is off + Code/Search is on
-        # forwards `tools: [{codeExecution: {}}]` plus
-        # `thinkingConfig` to an image model and 400s.
+        # Image-tier model IDs reject text-only tools (code_execution, user
+        # functions) and thinkingConfig regardless of the Images pill -- those
+        # are model-level constraints documented by Google. The pill only
+        # controls whether we ask Gemini to emit image output via
+        # `responseModalities: ["TEXT","IMAGE"]`. Decoupling the two avoids the
+        # case where Images off + Code/Search on forwards
+        # `tools: [{codeExecution: {}}]` plus `thinkingConfig` to an image model
+        # and 400s.
         image_tool_requested = bool(
             _hosted_builtins_allowed and enabled_tools and "image_generation" in enabled_tools
         )
@@ -3672,8 +3624,8 @@ class ExternalProviderClient:
         if is_image_model:
             gen_config["responseModalities"] = ["TEXT", "IMAGE"]
         elif is_image_picker_model:
-            # Force TEXT-only so an image-capable model with Images OFF
-            # doesn't still bill for image output.
+            # Force TEXT-only so an image-capable model with Images OFF doesn't
+            # still bill for image output.
             gen_config["responseModalities"] = ["TEXT"]
 
         # Thinking control. Gemini 3 uses thinkingLevel (str), 2.5 uses
@@ -3731,11 +3683,11 @@ class ExternalProviderClient:
             if level is not None:
                 gen_config["thinkingConfig"] = {"thinkingLevel": level}
         elif not is_image_model_strict:
-            # Gemini 2.5 / older: thinkingBudget int. Effort -> budget
-            # mirrors the OpenAI minimal/low/medium/high ladder so the
-            # existing frontend picker maps cleanly.
-            # NOTE: gemini-2.5-flash-lite rejects positive budgets below
-            # 512 with HTTP 400, so minimal=512 sits at that floor.
+            # Gemini 2.5 / older: thinkingBudget int. Effort -> budget mirrors
+            # the OpenAI minimal/low/medium/high ladder so the frontend picker
+            # maps cleanly.
+            # NOTE: gemini-2.5-flash-lite rejects positive budgets below 512
+            # with HTTP 400, so minimal=512 sits at that floor.
             _EFFORT_TO_BUDGET: dict[str, int] = {
                 "minimal": 512,
                 "low": 2048,
@@ -3746,8 +3698,8 @@ class ExternalProviderClient:
             }
             thinking_budget: Optional[int] = None
             if effort_lc == "none" or enable_thinking is False:
-                # Pro-tier 2.5 rejects budget=0 (400 "only works in
-                # thinking mode"), so coerce to a small positive value.
+                # Pro-tier 2.5 rejects budget=0 (400 "only works in thinking
+                # mode"), so coerce to a small positive value.
                 thinking_budget = 128 if _is_pro_thinking_only else 0
             elif effort_lc in _EFFORT_TO_BUDGET:
                 thinking_budget = _EFFORT_TO_BUDGET[effort_lc]
@@ -3779,8 +3731,8 @@ class ExternalProviderClient:
         )
         code_execution_allowed = not is_image_model_strict
         text_tools_allowed = not is_image_model_strict
-        # tool_choice="none" / forced-function suppresses hosted builtins
-        # too, matching the Anthropic / OpenRouter gates.
+        # tool_choice="none" / forced-function suppresses hosted builtins too,
+        # matching the Anthropic / OpenRouter gates.
         tools_array: list[dict[str, Any]] = []
         if (
             _hosted_builtins_allowed
@@ -3798,12 +3750,11 @@ class ExternalProviderClient:
             tools_array.append({"codeExecution": {}})
         # OpenAI-style function declarations -> Gemini functionDeclarations.
         # https://ai.google.dev/gemini-api/docs/function-calling#step_1
-        # Gemini's Schema accepts only the OpenAPI 3.0 subset documented
-        # at https://ai.google.dev/api/caching#Schema; OpenAI's strict
-        # tool definitions routinely include `additionalProperties`,
-        # `$schema`, `$defs`, `strict`, `examples`, and similar keys
-        # which 400 the request as INVALID_ARGUMENT. Strip them
-        # recursively before forwarding.
+        # Gemini's Schema accepts only the OpenAPI 3.0 subset documented at
+        # https://ai.google.dev/api/caching#Schema; OpenAI's strict tool
+        # definitions routinely include `additionalProperties`, `$schema`,
+        # `$defs`, `strict`, `examples`, and similar keys which 400 the request
+        # as INVALID_ARGUMENT. Strip them recursively before forwarding.
         _GEMINI_ALLOWED_SCHEMA_KEYS = frozenset(
             {
                 "type",
@@ -3831,9 +3782,9 @@ class ExternalProviderClient:
         )
 
         def _resolve_local_schema_ref(root: Optional[dict[str, Any]], ref: str) -> Optional[Any]:
-            # Walk a `#/foo/bar` JSON pointer against the schema root.
-            # Returns None if the pointer doesn't resolve to a dict, so
-            # the caller can fall back to the unresolved node.
+            # Walk a `#/foo/bar` JSON pointer against the schema root. Returns
+            # None if the pointer doesn't resolve to a dict, so the caller can
+            # fall back to the unresolved node.
             if not isinstance(root, dict) or not isinstance(ref, str):
                 return None
             if not ref.startswith("#/"):
@@ -3854,27 +3805,26 @@ class ExternalProviderClient:
             _seen_refs: Optional[frozenset[str]] = None,
         ) -> Any:
             # Recursively filter to Gemini's OpenAPI 3.0 subset. At a
-            # Schema-keyword dict layer we drop keys not in the
-            # allowlist; under `properties` the keys are user-defined
-            # field names and the values are themselves Schemas; under
-            # `items` / `anyOf` the values are also Schemas.
+            # Schema-keyword dict layer we drop keys not in the allowlist; under
+            # `properties` the keys are user-defined field names and the values
+            # are Schemas; under `items` / `anyOf` the values are also Schemas.
             # OpenAI strict tools commonly use JSON Schema's
-            # `"type": ["string", "null"]` form for nullable fields;
-            # Gemini's OpenAPI Schema uses `"type": "string"` plus
-            # `"nullable": true`. Translate that here.
+            # `"type": ["string", "null"]` form for nullable fields; Gemini's
+            # OpenAPI Schema uses `"type": "string"` plus `"nullable": true`.
+            # Translate that here.
             if root is None and isinstance(node, dict):
                 root = node
             if _seen_refs is None:
                 _seen_refs = frozenset()
             if isinstance(node, dict):
-                # Pydantic / OpenAI strict tools commonly hoist nested
-                # object schemas into `$defs` and reference them via
-                # `{"$ref": "#/$defs/Address"}`. Gemini's OpenAPI subset
-                # has no $ref and drops anything not in the allowlist,
-                # so the referenced shape would vanish if we didn't
-                # inline it here. Recurse into the resolved target with
-                # local siblings overriding the reference (normal JSON
-                # Schema composition), guarding against ref cycles.
+                # Pydantic / OpenAI strict tools commonly hoist nested object
+                # schemas into `$defs` and reference them via
+                # `{"$ref": "#/$defs/Address"}`. Gemini's OpenAPI subset has no
+                # $ref and drops anything not in the allowlist, so the
+                # referenced shape would vanish if we didn't inline it here.
+                # Recurse into the resolved target with local siblings
+                # overriding the reference (normal JSON Schema composition),
+                # guarding against ref cycles.
                 _ref = node.get("$ref")
                 if isinstance(_ref, str):
                     if _ref in _seen_refs:
@@ -3898,9 +3848,9 @@ class ExternalProviderClient:
                     if len(_non_null) == 1:
                         _flattened_type = _non_null[0]
                     elif len(_non_null) > 1:
-                        # Preserve multi-type unions as anyOf; flattening
-                        # to the first non-null type silently drops the
-                        # other branches and changes the tool contract.
+                        # Preserve multi-type unions as anyOf; flattening to the
+                        # first non-null type silently drops the other branches
+                        # and changes the tool contract.
                         _union_any_of = [{"type": _t} for _t in _non_null if isinstance(_t, str)]
                 for _k, _v in node.items():
                     if _k == "type" and isinstance(_v, list):
@@ -3917,13 +3867,12 @@ class ExternalProviderClient:
                         cleaned[_k] = _sanitize_gemini_schema(_v, root, _seen_refs)
                     elif _k == "anyOf" and isinstance(_v, list):
                         # Optional[X] / Union[A, B, None]: Pydantic emits
-                        # `anyOf: [..., {"type":"null"}]`. Gemini's
-                        # OpenAPI subset rejects `"type": "null"` inside
-                        # anyOf, so drop the null variant and surface it
-                        # via `nullable: true`. If exactly one non-null
-                        # branch remains, collapse it inline; otherwise
-                        # keep the slim anyOf and mark the field
-                        # nullable.
+                        # `anyOf: [..., {"type":"null"}]`. Gemini's OpenAPI
+                        # subset rejects `"type": "null"` inside anyOf, so drop
+                        # the null variant and surface it via `nullable: true`.
+                        # If exactly one non-null branch remains, collapse it
+                        # inline; otherwise keep the slim anyOf and mark the
+                        # field nullable.
                         _saw_null = any(
                             isinstance(_entry, dict) and _entry.get("type") == "null"
                             for _entry in _v
@@ -3982,8 +3931,8 @@ class ExternalProviderClient:
             tools_array.append({"functionDeclarations": function_declarations})
         if tools_array:
             body["tools"] = tools_array
-        # Tool-choice mapping: OpenAI "auto"/"none"/"required"/{name=...}
-        # -> Gemini toolConfig.functionCallingConfig.mode + allowedFunctionNames.
+        # Tool-choice mapping: OpenAI "auto"/"none"/"required"/{name=...} ->
+        # Gemini toolConfig.functionCallingConfig.mode + allowedFunctionNames.
         if tool_choice is not None and function_declarations and text_tools_allowed:
             _mode: Optional[str] = None
             _allowed: Optional[list[str]] = None
@@ -4007,18 +3956,17 @@ class ExternalProviderClient:
                     _fcc["allowedFunctionNames"] = _allowed
                 body["toolConfig"] = {"functionCallingConfig": _fcc}
 
-        # Prompt caching. The Gemini caching contract is "create a
-        # CachedContent resource, then pass its name on
-        # `cachedContent`". The cache itself is created out of band by
-        # the caller via POST /cachedContents; here we forward an
-        # explicit cache id when the dispatcher hands us one (a string
-        # value on enable_prompt_caching means "use this cache name").
+        # Prompt caching. The Gemini contract is "create a CachedContent
+        # resource, then pass its name on `cachedContent`". The cache is created
+        # out of band by the caller via POST /cachedContents; here we forward an
+        # explicit cache id when the dispatcher hands us one (a string value on
+        # enable_prompt_caching means "use this cache name").
         # https://ai.google.dev/gemini-api/docs/caching
         if isinstance(enable_prompt_caching, str) and enable_prompt_caching:
             body["cachedContent"] = enable_prompt_caching
 
-        # Model id is already validated at the top of _stream_gemini so
-        # we never reach a path-traversed URL segment here.
+        # Model id is already validated at the top of _stream_gemini so we never
+        # reach a path-traversed URL segment here.
         url = f"{self.base_url}/models/{model}:streamGenerateContent?alt=sse"
         completion_id = f"chatcmpl-gemini-{model.replace('/', '-')}"
 
@@ -4064,10 +4012,10 @@ class ExternalProviderClient:
             return f"data: {_json.dumps(chunk)}"
 
         def _gemini_part_extra(part: dict[str, Any]) -> Optional[dict[str, Any]]:
-            """Return ``{"google": {"thought_signature": ...}}`` when the
-            Gemini stream part carries a `thoughtSignature` we need to
-            replay on a follow-up turn (Gemini 3 image editing + tool
-            contexts both require an exact signature echo)."""
+            """Return ``{"google": {"thought_signature": ...}}`` when the Gemini
+            stream part carries a `thoughtSignature` we must replay on a
+            follow-up turn (Gemini 3 image editing + tool contexts both require
+            an exact signature echo)."""
             sig = part.get("thoughtSignature") or part.get("thought_signature")
             if isinstance(sig, str) and sig:
                 return {"google": {"thought_signature": sig}}
@@ -4089,31 +4037,29 @@ class ExternalProviderClient:
 
         last_usage: Optional[dict[str, Any]] = None
         emitted_function_call_ids: set[str] = set()
-        # True once any Gemini functionCall part has been emitted so the
-        # final finish_reason swaps STOP -> tool_calls (matches the
-        # OpenAI Chat Completions contract; an OAI client that sees a
-        # tool_calls delta followed by finish_reason="stop" never
-        # executes the tool).
+        # True once any Gemini functionCall part has been emitted so the final
+        # finish_reason swaps STOP -> tool_calls (matches the OpenAI Chat
+        # Completions contract; an OAI client that sees a tool_calls delta
+        # followed by finish_reason="stop" never executes the tool).
         emitted_any_function_call = False
-        # web_search_active drives the tool_start / tool_end envelope.
-        # Track on whether `googleSearch` was actually forwarded above,
-        # not the raw caller intent -- image-mode requests filter the
-        # tool out, and emitting a phantom "search complete" card on a
-        # turn where Gemini was never told to search confuses the UI.
+        # web_search_active drives the tool_start / tool_end envelope. Keyed on
+        # whether `googleSearch` was actually forwarded above, not raw caller
+        # intent -- image-mode requests filter the tool out, and a phantom
+        # "search complete" card on a turn where Gemini was never told to search
+        # confuses the UI.
         web_search_active = any("googleSearch" in t for t in tools_array)
         web_search_tool_id = "gemini_web_search"
         web_search_tool_started = False
         web_search_tool_ended = False
         web_search_citations: list[dict[str, str]] = []
-        # Tracks the tool_call_id minted on the most recent
-        # executableCode part so the matching codeExecutionResult can
-        # close out the same envelope. None between rounds.
+        # tool_call_id minted on the most recent executableCode part so the
+        # matching codeExecutionResult closes out the same envelope. None
+        # between rounds.
         gemini_code_exec_pending_id: Optional[str] = None
-        # The most recently emitted code_execution id + result text. Kept
-        # *after* the tool_end so a following inline image (matplotlib
-        # plot rendered by codeExecution) can attach to the same card
-        # via a `__IMAGES__:` marker instead of spawning a separate
-        # image_generation event.
+        # The most recently emitted code_execution id + result text. Kept *after*
+        # the tool_end so a following inline image (matplotlib plot from
+        # codeExecution) can attach to the same card via a `__IMAGES__:` marker
+        # instead of spawning a separate image_generation event.
         last_code_exec_tool_id: Optional[str] = None
         last_code_exec_result_text: str = ""
 
@@ -4147,9 +4093,9 @@ class ExternalProviderClient:
                     )
                     web_search_tool_started = True
 
-                # NOTE: same manual __anext__ loop pattern as the other
-                # streaming helpers (see stream_chat_completion for the
-                # Python 3.13 + httpcore 1.0.x GeneratorExit ordering).
+                # NOTE: same manual __anext__ loop as the other streaming
+                # helpers (see stream_chat_completion for the Python 3.13 +
+                # httpcore 1.0.x GeneratorExit ordering).
                 lines_gen = response.aiter_lines().__aiter__()
                 final_finish_reason: Optional[str] = None
                 try:
@@ -4176,24 +4122,24 @@ class ExternalProviderClient:
                         if not isinstance(event, dict):
                             continue
 
-                        # Latch usageMetadata across deltas -- the final
-                        # fragment carries the complete totals.
+                        # Latch usageMetadata across deltas -- the final fragment
+                        # carries the complete totals.
                         usage_meta = event.get("usageMetadata")
                         if isinstance(usage_meta, dict):
                             last_usage = usage_meta
 
-                        # Prompt-level safety block: Gemini ships zero
-                        # candidates plus a `promptFeedback.blockReason`
-                        # (e.g. SAFETY). The downstream OAI client would
-                        # otherwise see an empty successful assistant
-                        # response. Surface as a content_filter error
-                        # event so the UI can render the block reason.
+                        # Prompt-level safety block: Gemini ships zero candidates
+                        # plus a `promptFeedback.blockReason` (e.g. SAFETY). The
+                        # downstream OAI client would otherwise see an empty
+                        # successful assistant response. Surface as a
+                        # content_filter error event so the UI can render the
+                        # block reason.
                         prompt_feedback = event.get("promptFeedback")
                         if isinstance(prompt_feedback, dict) and prompt_feedback.get("blockReason"):
                             block_reason = str(prompt_feedback.get("blockReason"))
-                            # Close out the synthetic web_search start so
-                            # the UI does not show a spinner stuck on
-                            # "searching..." after the error toast lands.
+                            # Close out the synthetic web_search start so the UI
+                            # doesn't show a spinner stuck on "searching..."
+                            # after the error toast lands.
                             if (
                                 web_search_active
                                 and web_search_tool_started
@@ -4224,9 +4170,9 @@ class ExternalProviderClient:
                             if not isinstance(cand, dict):
                                 continue
                             # Citations / grounding metadata.
-                            # `groundingMetadata.groundingChunks[].web`
-                            # carries `uri` + `title`. Collect for the
-                            # tool_end emission at stream close.
+                            # `groundingMetadata.groundingChunks[].web` carries
+                            # `uri` + `title`. Collect for the tool_end emission
+                            # at stream close.
                             gm = cand.get("groundingMetadata")
                             if isinstance(gm, dict) and web_search_active:
                                 chunks_list = gm.get("groundingChunks") or []
@@ -4259,9 +4205,9 @@ class ExternalProviderClient:
                                     if not isinstance(part, dict):
                                         continue
                                     # Text delta. Stow part-level
-                                    # `thoughtSignature` on the delta so
-                                    # Gemini 3 turns that need an exact
-                                    # signature echo round-trip cleanly.
+                                    # `thoughtSignature` on the delta so Gemini 3
+                                    # turns needing an exact signature echo
+                                    # round-trip cleanly.
                                     text = part.get("text")
                                     _part_extra = _gemini_part_extra(part)
                                     if isinstance(text, str) and text:
@@ -4279,8 +4225,8 @@ class ExternalProviderClient:
                                         )
                                     ):
                                         # Empty-content part carrying a
-                                        # thoughtSignature: emit an empty delta
-                                        # so the signature is preserved.
+                                        # thoughtSignature: emit an empty delta to
+                                        # preserve the signature.
                                         yield _text_chunk(
                                             "",
                                             extra_content = _part_extra,
@@ -4297,10 +4243,9 @@ class ExternalProviderClient:
                                         emitted_function_call_ids.add(fc_id)
                                         # Each distinct functionCall in an
                                         # assistant turn needs its own
-                                        # tool_calls[*].index. Consumers
-                                        # that reassemble tool_calls by
-                                        # index collapse all calls onto
-                                        # the same slot when this is
+                                        # tool_calls[*].index. Consumers that
+                                        # reassemble tool_calls by index collapse
+                                        # all calls onto one slot if this is
                                         # hardcoded to 0, breaking
                                         # parallel/multi-tool turns.
                                         tc_index = len(emitted_function_call_ids) - 1
@@ -4314,14 +4259,13 @@ class ExternalProviderClient:
                                             },
                                         }
                                         # Gemini 3 function-calling: the
-                                        # part-level `thoughtSignature`
-                                        # must be echoed back on the
-                                        # next turn or the model rejects
-                                        # the tool-result envelope. Stow
-                                        # it on `extra_content.google`
-                                        # so the frontend can persist it
-                                        # and our outbound translator
-                                        # (below) can replay it.
+                                        # part-level `thoughtSignature` must be
+                                        # echoed on the next turn or the model
+                                        # rejects the tool-result envelope. Stow
+                                        # it on `extra_content.google` so the
+                                        # frontend can persist it and our
+                                        # outbound translator (below) can replay
+                                        # it.
                                         thought_sig = part.get("thoughtSignature") or part.get(
                                             "thought_signature"
                                         )
@@ -4344,13 +4288,12 @@ class ExternalProviderClient:
                                             ],
                                         }
                                         yield f"data: {_json.dumps(tool_chunk)}"
-                                    # executableCode + codeExecutionResult
-                                    # parts surface as the standard
-                                    # code_execution tool_start/tool_end
-                                    # envelope (same shape OpenAI and
-                                    # Anthropic emit) so the chat
-                                    # adapter can render Gemini sandbox
-                                    # output through CodeExecutionToolUI.
+                                    # executableCode + codeExecutionResult parts
+                                    # surface as the standard code_execution
+                                    # tool_start/tool_end envelope (same shape
+                                    # OpenAI and Anthropic emit) so the chat
+                                    # adapter renders Gemini sandbox output
+                                    # through CodeExecutionToolUI.
                                     # https://ai.google.dev/gemini-api/docs/code-execution
                                     exec_code = part.get("executableCode")
                                     if isinstance(exec_code, dict):
@@ -4362,11 +4305,10 @@ class ExternalProviderClient:
                                             )
                                             gemini_code_exec_pending_id = code_tool_id
                                             # Stow the raw Gemini part so
-                                            # follow-up turns can replay
-                                            # the native `executableCode`
-                                            # (Gemini rejects a generic
-                                            # functionCall echo for code
-                                            # execution history).
+                                            # follow-up turns can replay the
+                                            # native `executableCode` (Gemini
+                                            # rejects a generic functionCall echo
+                                            # for code execution history).
                                             _exec_thought_sig = part.get(
                                                 "thoughtSignature"
                                             ) or part.get("thought_signature")
@@ -4410,18 +4352,18 @@ class ExternalProviderClient:
                                     if isinstance(exec_result, dict):
                                         outcome = exec_result.get("outcome") or ""
                                         output = exec_result.get("output") or ""
-                                        # Gemini returns
-                                        # OUTCOME_OK / OUTCOME_FAILED /
-                                        # OUTCOME_DEADLINE_EXCEEDED. Treat
-                                        # non-OK outcomes as stderr so the
-                                        # UI surfaces the error.
+                                        # Gemini returns OUTCOME_OK /
+                                        # OUTCOME_FAILED /
+                                        # OUTCOME_DEADLINE_EXCEEDED. Treat non-OK
+                                        # outcomes as stderr so the UI surfaces
+                                        # the error.
                                         if outcome and outcome != "OUTCOME_OK":
                                             result_text = f"[{outcome}]\n{output}".rstrip()
                                         else:
                                             result_text = output
                                         # Pair tool_end with the most recent
-                                        # executableCode tool_start; fall back
-                                        # to exec_result.id then a fresh id.
+                                        # executableCode tool_start; else
+                                        # exec_result.id, then a fresh id.
                                         pair_id = (
                                             gemini_code_exec_pending_id
                                             or exec_result.get("id")
@@ -4468,10 +4410,10 @@ class ExternalProviderClient:
                                         last_code_exec_tool_id = pair_id
                                         last_code_exec_result_text = result_text
                                         gemini_code_exec_pending_id = None
-                                    # inlineData: either a Nano Banana
-                                    # generation (own card) or a sandbox
-                                    # plot attached to the code_execution
-                                    # card via the __IMAGES__: marker.
+                                    # inlineData: either a Nano Banana generation
+                                    # (own card) or a sandbox plot attached to
+                                    # the code_execution card via the __IMAGES__:
+                                    # marker.
                                     inline = part.get("inlineData")
                                     if isinstance(inline, dict):
                                         b64 = inline.get("data") or ""
@@ -4491,8 +4433,8 @@ class ExternalProviderClient:
                                                     + _json.dumps([image_uri])
                                                 )
                                                 # Stow inlineData so a follow-up
-                                                # turn can replay the plot with
-                                                # its per-part thoughtSignature.
+                                                # turn replays the plot with its
+                                                # per-part thoughtSignature.
                                                 _plot_thought_sig = part.get(
                                                     "thoughtSignature"
                                                 ) or part.get("thought_signature")
@@ -4585,11 +4527,11 @@ class ExternalProviderClient:
                                 if mapped is not None:
                                     final_finish_reason = mapped
 
-                    # End-of-stream emission order: web_search tool_end
-                    # (with citations) -> finish_reason chunk -> usage
-                    # chunk -> [DONE]. Matches the Anthropic / OpenAI
-                    # helpers' contract so the frontend handler does
-                    # not need provider-specific ordering knowledge.
+                    # End-of-stream emission order: web_search tool_end (with
+                    # citations) -> finish_reason chunk -> usage chunk -> [DONE].
+                    # Matches the Anthropic / OpenAI helpers' contract so the
+                    # frontend handler needs no provider-specific ordering
+                    # knowledge.
                     if web_search_active and web_search_tool_started and not web_search_tool_ended:
                         blocks: list[str] = []
                         for cit in web_search_citations:
@@ -4610,9 +4552,8 @@ class ExternalProviderClient:
 
                     if final_finish_reason:
                         # OpenAI clients trigger tool execution when
-                        # finish_reason="tool_calls". Gemini emits
-                        # "STOP" even when the turn was a pure
-                        # functionCall request, so override after the
+                        # finish_reason="tool_calls". Gemini emits "STOP" even
+                        # for a pure functionCall request, so override after the
                         # fact to match the OAI contract.
                         if emitted_any_function_call and final_finish_reason == "stop":
                             final_finish_reason = "tool_calls"
@@ -4630,15 +4571,15 @@ class ExternalProviderClient:
                         yield f"data: {_json.dumps(finish_chunk)}"
 
                     # Map Gemini usageMetadata onto OpenAI include_usage.
-                    # thoughtsTokenCount is billed output too — fold it in
-                    # so cost calculators don't undercount.
+                    # thoughtsTokenCount is billed output too — fold it in so
+                    # cost calculators don't undercount.
                     if isinstance(last_usage, dict):
                         thought_tokens = last_usage.get("thoughtsTokenCount") or 0
                         candidate_tokens = last_usage.get("candidatesTokenCount") or 0
                         prompt_tokens = last_usage.get("promptTokenCount") or 0
-                        # Gemini bills tool-call prompt slices separately
-                        # via `toolUsePromptTokenCount`. Fold into input
-                        # so total_tokens does not undercount tool turns.
+                        # Gemini bills tool-call prompt slices separately via
+                        # `toolUsePromptTokenCount`. Fold into input so
+                        # total_tokens doesn't undercount tool turns.
                         tool_use_prompt_tokens = last_usage.get("toolUsePromptTokenCount") or 0
                         translated_usage = {
                             "input_tokens": prompt_tokens + tool_use_prompt_tokens,
@@ -4657,9 +4598,9 @@ class ExternalProviderClient:
 
                     yield "data: [DONE]"
                 finally:
-                    # Close response first so lines_gen.aclose() becomes
-                    # a no-op (avoids the httpcore 1.0 GeneratorExit
-                    # path and the aclose-never-awaited RuntimeWarning).
+                    # Close response first so lines_gen.aclose() becomes a no-op
+                    # (avoids the httpcore 1.0 GeneratorExit path and the
+                    # aclose-never-awaited RuntimeWarning).
                     await response.aclose()
                     await lines_gen.aclose()
 
@@ -4732,12 +4673,12 @@ class ExternalProviderClient:
         Call OpenAI's /v1/responses endpoint and translate its SSE stream back
         into OpenAI Chat Completions chunk format.
 
-        The Responses API uses a different request shape (``input`` instead of
+        The Responses API uses a different request shape (``input`` not
         ``messages``, ``instructions`` for system prompts, ``max_output_tokens``
         for the budget) and emits event-typed SSE frames (e.g.
         ``response.output_text.delta``) rather than chat-completion chunks.
-        ``presence_penalty`` / ``top_k`` are not part of the Responses contract
-        and are dropped here intentionally.
+        ``presence_penalty`` / ``top_k`` aren't part of the Responses contract
+        and are dropped here.
         """
         import json as _json
 
@@ -4746,15 +4687,14 @@ class ExternalProviderClient:
             enabled_tools and "image_generation" in enabled_tools and is_openai_cloud
         )
 
-        # Split system messages out into a single `instructions` string and
+        # Split system messages into a single `instructions` string and
         # translate user/assistant messages into the Responses input shape.
         instructions_parts: list[str] = []
         input_items: list[dict[str, Any]] = []
-        # When we drop a server-side builtin `function_call` here, the
-        # matching `role="tool"` follow-up must also be dropped --
-        # otherwise the outbound body contains an orphan
-        # `function_call_output` with no matching `function_call`, which
-        # OpenAI Responses can reject or mis-associate.
+        # When we drop a server-side builtin `function_call` here, the matching
+        # `role="tool"` follow-up must also be dropped -- otherwise the outbound
+        # body has an orphan `function_call_output` with no matching
+        # `function_call`, which OpenAI Responses can reject or mis-associate.
         skipped_server_builtin_call_ids: set[str] = set()
         openai_replay_items: list[dict[str, Any]] = []
         previous_response_id: Optional[str] = None
@@ -4772,19 +4712,17 @@ class ExternalProviderClient:
                             instructions_parts.append(part["text"])
                 continue
 
-            # OpenAI Responses uses item-shape history for function
-            # calling: assistant turns that invoked user tools must
-            # serialize each call as a `function_call` input item, and
-            # each role="tool" follow-up as a `function_call_output`
-            # item keyed by the matching `call_id`. Without this the
-            # second turn after a function call sends Chat Completions
-            # shape and Responses 400s the request.
+            # OpenAI Responses uses item-shape history for function calling:
+            # assistant turns that invoked user tools must serialize each call
+            # as a `function_call` input item, and each role="tool" follow-up as
+            # a `function_call_output` item keyed by the matching `call_id`.
+            # Without this the second turn after a function call sends Chat
+            # Completions shape and Responses 400s the request.
             if role == "tool":
                 _call_id = msg.get("tool_call_id") or ""
-                # If the matching assistant `function_call` was a
-                # server-side builtin we already dropped, drop the
-                # follow-up too to avoid emitting an orphan
-                # `function_call_output`.
+                # If the matching assistant `function_call` was a server-side
+                # builtin we already dropped, drop the follow-up too to avoid
+                # an orphan `function_call_output`.
                 if _call_id and _call_id in skipped_server_builtin_call_ids:
                     continue
                 if isinstance(content, list):
@@ -4805,22 +4743,20 @@ class ExternalProviderClient:
                     )
                 continue
 
-            # Assistant turns that returned tool_calls translate each
-            # call as a `function_call` item (carrying name + JSON
-            # arguments + call_id). Skip builtin server-side cards
-            # (canonical builtin name + `args._server_tool` marker)
-            # which never round-trip as user functions. We require both
-            # checks so a user function literally named `_server_tool`
-            # in its argument schema is not dropped.
+            # Assistant turns that returned tool_calls translate each call as a
+            # `function_call` item (name + JSON arguments + call_id). Skip
+            # builtin server-side cards (canonical builtin name +
+            # `args._server_tool` marker) which never round-trip as user
+            # functions. Both checks are required so a user function literally
+            # named `_server_tool` in its argument schema isn't dropped.
             _tool_calls = msg.get("tool_calls") if isinstance(msg, dict) else None
             if role == "assistant" and isinstance(_tool_calls, list):
-                # Preserve the prior `response.output` ordering: the
-                # model's text precedes its function_call items, and
-                # the matching role=tool follow-up arrives AFTER the
-                # call. Without this guard, history replay puts
-                # function_call -> assistant text -> function_call_output,
-                # which can put the tool output after an unrelated
-                # assistant message and confuse multi-turn function
+                # Preserve the prior `response.output` ordering: the model's text
+                # precedes its function_call items, and the matching role=tool
+                # follow-up arrives AFTER the call. Without this guard, history
+                # replay puts function_call -> assistant text ->
+                # function_call_output, which can place tool output after an
+                # unrelated assistant message and confuse multi-turn function
                 # calling.
                 if isinstance(content, str) and content:
                     input_items.append({"role": "assistant", "content": content})
@@ -4882,8 +4818,8 @@ class ExternalProviderClient:
                             "arguments": _args_raw,
                         }
                     )
-                # Assistant text already emitted above (in order) so we
-                # don't fall through to the generic content branches.
+                # Assistant text already emitted above (in order) so we don't
+                # fall through to the generic content branches.
                 continue
 
             if isinstance(content, str):
@@ -4941,18 +4877,17 @@ class ExternalProviderClient:
                         # or `{type:"input_file", file_url:"https://..."}`,
                         # with optional `filename`. See
                         # https://developers.openai.com/api/docs/guides/images-vision
-                        # Map Studio's normalised `input_document` shape
-                        # straight onto Responses' `input_file`.
+                        # Map Studio's normalised `input_document` onto
+                        # Responses' `input_file`.
                         file_url = part.get("file_url")
                         file_data = part.get("file_data")
                         filename = part.get("filename")
                         # Mirror the Anthropic-side guard: any "data:" URI
                         # without an actual base64 payload (`data:application/pdf;base64,`
-                        # or whitespace-only) would otherwise be forwarded
-                        # to OpenAI as `file_data=""`, which 400s the whole
-                        # turn. Treat such payloads as missing AND fall
-                        # back to file_url if one is also present, so a
-                        # recoverable remote URL doesn't get discarded in
+                        # or whitespace-only) would otherwise be forwarded to
+                        # OpenAI as `file_data=""`, which 400s the turn. Treat
+                        # such payloads as missing AND fall back to file_url if
+                        # present, so a recoverable remote URL isn't discarded in
                         # favour of a malformed inline payload.
                         file_data_valid = bool(
                             isinstance(file_data, str)
@@ -4978,9 +4913,9 @@ class ExternalProviderClient:
         if previous_response_id:
             # OpenAI's documented multi-turn image generation path can use
             # `previous_response_id` to carry the prior generated image and
-            # paired reasoning state. Prefer that over manual item replay when
-            # we captured the response id; keep replay below as a fallback for
-            # older stored turns that only have an image_generation_call id.
+            # paired reasoning state. Prefer that over manual item replay when we
+            # captured the response id; replay below is a fallback for older
+            # stored turns that only have an image_generation_call id.
             openai_replay_items = []
         elif (
             _openai_image_replay_requires_reasoning(model)
@@ -5027,11 +4962,11 @@ class ExternalProviderClient:
 
         # NOTE: gpt-5.x / o3 / gpt-4.5 are reasoning-class models. They reject
         # temperature and top_p with `Unsupported parameter` 400s on
-        # /v1/responses (and on /v1/chat/completions for the same families).
-        # The PROVIDER_REGISTRY['openai'] model_id_allowlist already scopes
-        # the picker to those families, so we never need to send sampling
-        # knobs here. ``reasoning.effort`` defaults to "medium" server-side
-        # if omitted — surface it in a future commit if a knob is wanted.
+        # /v1/responses (and /v1/chat/completions for the same families). The
+        # PROVIDER_REGISTRY['openai'] model_id_allowlist already scopes the
+        # picker to those families, so we never send sampling knobs here.
+        # ``reasoning.effort`` defaults to "medium" server-side if omitted —
+        # surface it in a future commit if a knob is wanted.
         del temperature, top_p  # explicit drop — params are accepted for
         # API symmetry with the other stream methods but not forwarded.
 
@@ -5042,12 +4977,12 @@ class ExternalProviderClient:
         }
         if previous_response_id:
             body["previous_response_id"] = previous_response_id
-        # `summary: "auto"` is what makes /v1/responses emit reasoning
-        # summary events — without it OpenAI returns no thinking text on
-        # most reasoning models, the SSE handler has no <think>…</think>
-        # to wrap, and the chat reasoning panel stays blank. Always pair
-        # an explicit effort with summary except for the explicit "off"
-        # case (effort: "none"), where summaries are pointless.
+        # `summary: "auto"` is what makes /v1/responses emit reasoning summary
+        # events — without it OpenAI returns no thinking text on most reasoning
+        # models, the SSE handler has no <think>…</think> to wrap, and the chat
+        # reasoning panel stays blank. Always pair an explicit effort with
+        # summary except for the "off" case (effort: "none"), where summaries
+        # are pointless.
         summary_unsupported = bool(
             _OPENAI_REASONING_SUMMARY_UNSUPPORTED.match(model.strip().lower())
         )
@@ -5073,10 +5008,9 @@ class ExternalProviderClient:
         if max_tokens is not None:
             body["max_output_tokens"] = max_tokens
 
-        # Opt into 24h prompt-cache retention (free, vs the default
-        # ~5-10 min). Gated on the OpenAI cloud host because ollama /
-        # llama.cpp / "custom" presets reach this code path too and
-        # would 400 on the unknown field.
+        # Opt into 24h prompt-cache retention (free, vs the default ~5-10 min).
+        # Gated on the OpenAI cloud host because ollama / llama.cpp / "custom"
+        # presets reach this path too and would 400 on the unknown field.
         if is_openai_cloud and enable_prompt_caching is not False:
             body["prompt_cache_retention"] = "24h"
 
@@ -5108,7 +5042,7 @@ class ExternalProviderClient:
             return tool
 
         # Translate Chat-Completions function tools into the Responses
-        # function-tool shape (flattened name/description/parameters).
+        # function-tool shape (flat name/description/parameters).
         responses_user_function_tools: list[dict[str, Any]] = []
         if tools:
             for _tool in tools:
@@ -5170,9 +5104,9 @@ class ExternalProviderClient:
             ):
                 tools_array.append({"type": "web_search"})
             if _responses_hosted_builtins_allowed and code_execution_enabled_openai:
-                # Reuse the thread's container so filesystem state
-                # persists; auto-create when there isn't one yet. Stale
-                # ids 400 and are cleared via container_invalidated.
+                # Reuse the thread's container so filesystem state persists;
+                # auto-create when there isn't one yet. Stale ids 400 and are
+                # cleared via container_invalidated.
                 shell_env: dict[str, Any]
                 if openai_code_exec_container_id:
                     shell_env = {
@@ -5195,10 +5129,9 @@ class ExternalProviderClient:
         logger.info("Proxying OpenAI Responses API to %s (model=%s)", url, model)
 
         def _build_body(container_id_for_this_attempt: Optional[str]) -> dict[str, Any]:
-            """Snapshot of the request body. Called once for the initial
-            attempt and again with ``None`` for the post-expiry retry.
-            Returns a fresh dict so the retry doesn't share state with the
-            first attempt.
+            """Snapshot of the request body. Called once for the initial attempt
+            and again with ``None`` for the post-expiry retry. Returns a fresh
+            dict so the retry doesn't share state with the first attempt.
             """
             attempt_body = dict(body)
             if (enabled_tools or responses_user_function_tools) and not _responses_tool_choice_none:
@@ -5230,8 +5163,8 @@ class ExternalProviderClient:
 
         def _is_openai_container_expired_error(error_text: str) -> bool:
             """Match the substring patterns OpenAI uses for expired / missing
-            code-exec containers. There's no official error code in the public
-            docs, so we substring-match a small set.
+            code-exec containers. No official error code exists in the public
+            docs, so substring-match a small set.
             """
             lowered = error_text.lower()
             if "container" not in lowered:
@@ -5292,19 +5225,19 @@ class ExternalProviderClient:
                     # Latched from response.completed/incomplete; surfaces
                     # input_tokens_details.cached_tokens to prove cache hits.
                     last_usage: Optional[dict[str, Any]] = None
-                    # web_search state. Citations are emitted on text deltas
-                    # (not per call), so the aggregate list is shared and
-                    # applied to the LAST web_search tool_end (parseSourcesFromResult
+                    # web_search state. Citations are emitted on text deltas (not
+                    # per call), so the aggregate list is shared and applied to
+                    # the LAST web_search tool_end (parseSourcesFromResult
                     # flatmaps every call, one non-empty is enough).
                     web_search_calls: dict[str, dict[str, Any]] = {}
                     all_url_citations: list[dict[str, Any]] = []
-                    # shell_calls (code execution): { call_id -> {commands, output} }.
+                    # shell_calls (code execution): {call_id -> {commands, output}}.
                     # shell_call <-> shell_call_output match by call_id; emit
                     # tool_start/tool_end like the Anthropic UX.
                     shell_calls: dict[str, dict[str, Any]] = {}
                     # Container id latched from response.container_id or
-                    # item.environment.container_id; emit container_ready
-                    # when it differs from the inbound id.
+                    # item.environment.container_id; emit container_ready when it
+                    # differs from the inbound id.
                     latched_container_id: Optional[str] = None
                     container_id_emitted = False
                     current_openai_response_id: Optional[str] = None
@@ -5315,10 +5248,10 @@ class ExternalProviderClient:
                     # prepended onto the next delta. See _split_pending_citation_tail.
                     pending_marker_tail: str = ""
                     # Segments deferred while their markers reference unseen
-                    # source_ids; held in arrival order so output never
-                    # leapfrogs an earlier deferred segment. Flushed on
-                    # annotation events and force-flushed at end-of-stream
-                    # with leftover private-use codepoints stripped.
+                    # source_ids; held in arrival order so output never leapfrogs
+                    # an earlier deferred segment. Flushed on annotation events
+                    # and force-flushed at end-of-stream with leftover
+                    # private-use codepoints stripped.
                     pending_citation_segments: list[str] = []
 
                     def _record_openai_response_id(payload: dict[str, Any]) -> None:
@@ -5336,7 +5269,7 @@ class ExternalProviderClient:
                     def _drain_pending_segments(force: bool) -> str:
                         """Re-attempt resolution on buffered segments in order.
                         Stops at the first still-unresolved segment unless
-                        ``force`` (end-of-stream), where lingering markers are stripped."""
+                        ``force`` (end-of-stream), where lingering markers drop."""
                         out: list[str] = []
                         while pending_citation_segments:
                             seg = pending_citation_segments[0]
@@ -5369,8 +5302,8 @@ class ExternalProviderClient:
                         if not tail:
                             return ""
                         if _OPENAI_CITE_STOP not in tail:
-                            # Unterminated: drop the whole tail, otherwise the
-                            # residual ``cite<sid>`` would leak as plain text.
+                            # Unterminated: drop the whole tail, else the residual
+                            # ``cite<sid>`` would leak as plain text.
                             return ""
                         rendered = _replace_openai_citation_markers(tail, all_url_citations)
                         # Scrub residual private-use bytes (e.g. a partial opener).
@@ -5398,13 +5331,13 @@ class ExternalProviderClient:
                         return f"data: {_json.dumps(chunk)}"
 
                     def _format_shell_output(output: Any) -> str:
-                        """Render an OpenAI `shell_call_output.output` list
-                        as the preformatted text payload the frontend's
-                        CodeExecutionToolUI displays inside a <pre>. Each
-                        entry has stdout/stderr/outcome — concatenate them
-                        with a separator block per entry and append
-                        `return_code` / `(timeout)` annotations only when
-                        they convey information beyond "succeeded".
+                        """Render an OpenAI `shell_call_output.output` list as the
+                        preformatted text payload the frontend's
+                        CodeExecutionToolUI displays inside a <pre>. Each entry
+                        has stdout/stderr/outcome — concatenate them with a
+                        separator block per entry and append `return_code` /
+                        `(timeout)` annotations only when they convey info beyond
+                        "succeeded".
                         """
                         if not isinstance(output, list):
                             return ""
@@ -5434,13 +5367,12 @@ class ExternalProviderClient:
 
                     def _record_url_citation(payload: dict[str, Any]) -> None:
                         """Append a url_citation onto the shared all_url_citations
-                        list. Dedup by URL — the same URL can be cited many
-                        times under different ``source_id`` aliases (one per
-                        span/locator), so collect every alias we see onto
-                        the matching entry's ``source_ids`` list. The
-                        delta-text rewriter resolves any of those aliases
-                        back to this entry's URL. The id may live under
-                        ``source_id``, ``id``, or ``locator`` across the
+                        list. Dedup by URL — the same URL can be cited many times
+                        under different ``source_id`` aliases (one per
+                        span/locator), so collect every alias onto the matching
+                        entry's ``source_ids`` list. The delta-text rewriter
+                        resolves any alias back to this entry's URL. The id may
+                        live under ``source_id``, ``id``, or ``locator`` across
                         Responses API revisions."""
                         if payload.get("type") != "url_citation":
                             return
@@ -5453,9 +5385,9 @@ class ExternalProviderClient:
                             or payload.get("locator")
                             or ""
                         )
-                        # Single pass: either backfill aliases onto an
-                        # existing URL entry (and return) or fall through
-                        # to append a fresh one.
+                        # Single pass: either backfill aliases onto an existing
+                        # URL entry (and return) or fall through to append a
+                        # fresh one.
                         for c in all_url_citations:
                             if c["url"] != url:
                                 continue
@@ -5548,7 +5480,7 @@ class ExternalProviderClient:
                                     out.append(text)
                             return "".join(out)
                         if isinstance(payload, dict):
-                            # OpenAI responses may carry reasoning summaries in
+                            # OpenAI responses carry reasoning summaries in
                             # different envelope fields across event variants.
                             for key in ("text", "delta", "content", "summary"):
                                 if key in payload:
@@ -5599,7 +5531,7 @@ class ExternalProviderClient:
                                             reasoning_open = False
                                         yield _chunk_with_text(flushed)
                                 # Force-drain any segment still awaiting an
-                                # annotation; lingering codepoints are stripped.
+                                # annotation; lingering codepoints drop.
                                 tail_flushed = _drain_pending_segments(
                                     force = True,
                                 )
@@ -5624,9 +5556,9 @@ class ExternalProviderClient:
                             if event_type == "response.output_text.delta":
                                 delta_text = event.get("delta", "")
                                 # Process inline annotations first so source_ids
-                                # referenced by same-delta markers are in the lookup
-                                # before the rewriter runs. Some API versions inline
-                                # url citations on the delta event itself.
+                                # referenced by same-delta markers are in the
+                                # lookup before the rewriter runs. Some API
+                                # versions inline url citations on the delta event.
                                 for ann in event.get("annotations") or []:
                                     if isinstance(ann, dict):
                                         _record_url_citation(ann)
@@ -5641,9 +5573,10 @@ class ExternalProviderClient:
                                         if reasoning_open:
                                             yield _chunk_with_text("</think>")
                                             reasoning_open = False
-                                        # Re-attempt earlier deferred segments first
-                                        # so output stays in order; the needed
-                                        # annotation may have arrived inline above.
+                                        # Re-attempt earlier deferred segments
+                                        # first so output stays in order; the
+                                        # needed annotation may have arrived
+                                        # inline above.
                                         flushed = _drain_pending_segments(
                                             force = False,
                                         )
@@ -5679,8 +5612,8 @@ class ExternalProviderClient:
                                     item_id = item.get("id", "") or (f"ws_{len(web_search_calls)}")
                                     web_search_calls.setdefault(item_id, {"query": ""})
                                 # Register shell_call eagerly so out-of-order
-                                # output links back. Probe env.container_id
-                                # to emit container_ready before response.completed.
+                                # output links back. Probe env.container_id to
+                                # emit container_ready before response.completed.
                                 if isinstance(item, dict) and item.get("type") == "shell_call":
                                     item_id = item.get("id", "") or (f"sc_{len(shell_calls)}")
                                     shell_calls.setdefault(
@@ -5735,12 +5668,12 @@ class ExternalProviderClient:
                                     # done is the canonical place to read the
                                     # query, so emit both tool_start and tool_end
                                     # here. Frontend then renders a card per call
-                                    # with the proper "Searching: <query>" label.
+                                    # with the "Searching: <query>" label.
                                     # Citations are aggregated separately and the
                                     # *last* call's result is overwritten at
                                     # response.completed with the citation list
-                                    # (so the source-pill extraction at message
-                                    # tail surfaces them once).
+                                    # (so source-pill extraction at message tail
+                                    # surfaces them once).
                                     item_id = item.get("id", "") or (f"ws_{len(web_search_calls)}")
                                     action = item.get("action")
                                     query = (
@@ -5767,13 +5700,12 @@ class ExternalProviderClient:
                                     )
                                 elif item.get("type") == "shell_call":
                                     # OpenAI ships the commands array on the
-                                    # action field. Join them onto one
-                                    # command string for the tool card —
-                                    # the renderer is shared with Anthropic
-                                    # bash, which only carries a single
-                                    # `command`. Multiple commands in one
-                                    # shell_call get joined with newlines so
-                                    # they still render as one card.
+                                    # action field. Join them onto one command
+                                    # string for the tool card — the renderer is
+                                    # shared with Anthropic bash, which carries a
+                                    # single `command`. Multiple commands in one
+                                    # shell_call are joined with newlines so they
+                                    # still render as one card.
                                     item_id = item.get("id", "") or (f"sc_{len(shell_calls)}")
                                     action = item.get("action") or {}
                                     commands = (
@@ -5821,10 +5753,9 @@ class ExternalProviderClient:
                                         )
                                 elif item.get("type") == "shell_call_output":
                                     # `call_id` links back to the shell_call's
-                                    # `id`, which is what we used as the
-                                    # tool_call_id on tool_start. Match on
-                                    # call_id when present so the matching
-                                    # card transitions to complete.
+                                    # `id`, used as the tool_call_id on
+                                    # tool_start. Match on call_id when present so
+                                    # the matching card transitions to complete.
                                     call_id = item.get("call_id") or item.get("id") or ""
                                     output = item.get("output") or []
                                     # Skip if bundled-output path already
@@ -5845,7 +5776,7 @@ class ExternalProviderClient:
                                 elif item.get("type") == "image_generation_call":
                                     # Base64 image on `result` (or `b64_json`),
                                     # `revised_prompt` for the rewritten prompt.
-                                    # ns-resolution id so concurrent gens stay unique.
+                                    # ns-resolution id so concurrent gens are unique.
                                     raw_item_id = item.get("id")
                                     item_id = raw_item_id or f"img_{time.time_ns()}"
                                     prompt_in = (
@@ -5943,14 +5874,12 @@ class ExternalProviderClient:
                                 completed_usage = (event.get("response") or {}).get("usage")
                                 if isinstance(completed_usage, dict):
                                     last_usage = completed_usage
-                                # Flush any unterminated citation tail
-                                # held over from the last delta. By
-                                # the time we get here every annotation
-                                # has been recorded so a late-arriving
-                                # source_id may resolve cleanly; if it
-                                # still doesn't, the helper strips the
-                                # private-use bytes so no garbled
-                                # glyph reaches the user.
+                                # Flush any unterminated citation tail held over
+                                # from the last delta. By now every annotation is
+                                # recorded so a late-arriving source_id may
+                                # resolve; if not, the helper strips the
+                                # private-use bytes so no garbled glyph reaches
+                                # the user.
                                 if pending_marker_tail:
                                     flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
@@ -5960,7 +5889,7 @@ class ExternalProviderClient:
                                             reasoning_open = False
                                         yield _chunk_with_text(flushed)
                                 # Force-drain any segment still awaiting an
-                                # annotation; lingering codepoints are stripped.
+                                # annotation; lingering codepoints drop.
                                 tail_flushed = _drain_pending_segments(
                                     force = True,
                                 )
@@ -5974,11 +5903,10 @@ class ExternalProviderClient:
                                     reasoning_open = False
                                 # Probe response.container_id (top-level) and
                                 # response.container.id for the shell-tool
-                                # container id. OpenAI's docs don't pin the
-                                # exact field, so we scan both. Emit
-                                # `container_ready` only when the value
-                                # differs from the inbound one — no churn on
-                                # reuse.
+                                # container id. OpenAI's docs don't pin the exact
+                                # field, so scan both. Emit `container_ready` only
+                                # when the value differs from the inbound one — no
+                                # churn on reuse.
                                 response_obj = event.get("response") or {}
                                 if isinstance(response_obj, dict):
                                     probe_id = response_obj.get("container_id")
@@ -6006,8 +5934,8 @@ class ExternalProviderClient:
                                     container_id_emitted = True
                                 # Overwrite the last web_search call with the
                                 # citation list; the source-pill extractor
-                                # flatMaps across cards. Earlier cards keep
-                                # their per-call "Searching:" text.
+                                # flatMaps across cards. Earlier cards keep their
+                                # per-call "Searching:" text.
                                 if web_search_calls and all_url_citations:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks: list[str] = []
@@ -6067,9 +5995,8 @@ class ExternalProviderClient:
                                 incomplete_usage = (event.get("response") or {}).get("usage")
                                 if isinstance(incomplete_usage, dict):
                                     last_usage = incomplete_usage
-                                # Same flush as response.completed --
-                                # truncated streams can leave a half-
-                                # marker in the buffer.
+                                # Same flush as response.completed -- truncated
+                                # streams can leave a half-marker in the buffer.
                                 if pending_marker_tail:
                                     flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
@@ -6079,7 +6006,7 @@ class ExternalProviderClient:
                                             reasoning_open = False
                                         yield _chunk_with_text(flushed)
                                 # Force-drain any segment still awaiting an
-                                # annotation; lingering codepoints are stripped.
+                                # annotation; lingering codepoints drop.
                                 tail_flushed = _drain_pending_segments(
                                     force = True,
                                 )
@@ -6092,11 +6019,11 @@ class ExternalProviderClient:
                                     yield _chunk_with_text("</think>")
                                     reasoning_open = False
                                 # Same backfill as response.completed — apply
-                                # whatever citations we managed to gather
-                                # before truncation onto the last call. All
-                                # earlier tool cards already have their proper
-                                # query + empty placeholder result from the
-                                # output_item.done emissions above.
+                                # whatever citations we gathered before
+                                # truncation onto the last call. Earlier tool
+                                # cards already have their query + empty
+                                # placeholder result from the output_item.done
+                                # emissions above.
                                 if web_search_calls and all_url_citations:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks = []
@@ -6142,8 +6069,7 @@ class ExternalProviderClient:
                                 yield f"data: {_json.dumps(chunk)}"
                                 # Emit include_usage-style chunk after the
                                 # length-truncated finish_reason too, so
-                                # incomplete responses still report
-                                # cached_tokens.
+                                # incomplete responses still report cached_tokens.
                                 usage_line = _build_usage_chunk(
                                     completion_id,
                                     "openai",
@@ -6153,8 +6079,8 @@ class ExternalProviderClient:
                                     yield usage_line
 
                             elif event_type in ("response.failed", "error"):
-                                # Surface the failure to the client; let the
-                                # outer route emit [DONE] as part of its cleanup.
+                                # Surface the failure to the client; the outer
+                                # route emits [DONE] as part of its cleanup.
                                 error_payload = event.get("response", {}).get("error", {}) or {
                                     "message": event.get("message", "Unknown error"),
                                     "code": event.get("code"),
@@ -6170,10 +6096,10 @@ class ExternalProviderClient:
                         await lines_gen.aclose()
                         raise
                     finally:
-                        # Summarise what the model actually did this turn so
-                        # support reports of "I clicked Search and got nothing"
-                        # can be triaged at a glance: was the tool requested,
-                        # did OpenAI invoke it, and how many sources came back?
+                        # Summarise what the model did this turn so support
+                        # reports of "I clicked Search and got nothing" can be
+                        # triaged at a glance: was the tool requested, did OpenAI
+                        # invoke it, and how many sources came back?
                         web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                         web_search_invocations = len(web_search_calls)
                         total_citations = len(all_url_citations)
@@ -6183,10 +6109,9 @@ class ExternalProviderClient:
                         # cached_input_tokens > 0 on turn N proves
                         # prompt_cache_retention="24h" is letting the previous
                         # turn's prefix hit the cache instead of being
-                        # recomputed. On /v1/responses the field is nested as
+                        # recomputed. On /v1/responses the field is nested at
                         # usage.input_tokens_details.cached_tokens (not
-                        # prompt_tokens_details, which is the /v1/chat/completions
-                        # shape).
+                        # prompt_tokens_details, the /v1/chat/completions shape).
                         cached_input_tokens = None
                         if isinstance(last_usage, dict):
                             details = last_usage.get("input_tokens_details")
@@ -6259,9 +6184,9 @@ class ExternalProviderClient:
     ) -> dict[str, Any]:
         """Non-streaming chat completion. Returns the full response dict.
 
-        Note: only valid for OpenAI-compatible providers. Anthropic requires its
-        own Messages API; use stream_chat_completion (with stream=False) instead
-        if a non-streaming Anthropic path is needed in the future.
+        Only valid for OpenAI-compatible providers. Anthropic requires its own
+        Messages API; use stream_chat_completion (with stream=False) if a
+        non-streaming Anthropic path is needed later.
         """
         body: dict[str, Any] = {
             "model": model,
@@ -6290,8 +6215,8 @@ class ExternalProviderClient:
         """
         Call GET /models on the provider to discover available models.
 
-        Returns a list of model dicts with at least 'id' and optionally
-        'created', 'owned_by', etc.
+        Returns model dicts with at least 'id' and optionally 'created',
+        'owned_by', etc.
 
         All supported providers expose a /models endpoint:
         - OpenAI-compatible: standard {"data": [...]} response
@@ -6316,8 +6241,8 @@ class ExternalProviderClient:
                 models = await self._list_ollama_native_models()
             # Gemini's native /v1beta/models returns
             # {"models": [{"name": "models/gemini-2.5-flash", ...}]}
-            # -- repackage into the OpenAI-compatible shape the rest
-            # of Studio expects so dynamic model discovery works.
+            # -- repackage into the OpenAI-compatible shape the rest of Studio
+            # expects so dynamic model discovery works.
             if not models and self.provider_type == "gemini":
                 models = self._parse_gemini_models(data)
             return models
@@ -6335,10 +6260,9 @@ class ExternalProviderClient:
                        "displayName": "Gemini 2.5 Flash",
                        "supportedGenerationMethods": [...]}]}
 
-        We only keep entries that advertise
-        ``generateContent`` / ``streamGenerateContent`` so the picker
-        does not surface embedding-only models the chat path can't
-        drive.
+        We only keep entries that advertise ``generateContent`` /
+        ``streamGenerateContent`` so the picker doesn't surface embedding-only
+        models the chat path can't drive.
         """
         if not isinstance(payload, dict):
             return []
@@ -6358,8 +6282,8 @@ class ExternalProviderClient:
                 continue
             base_id = entry.get("baseModelId")
             name = entry.get("name") or ""
-            # ``name`` arrives as ``"models/gemini-2.5-flash"``; the
-            # chat path uses the bare id.
+            # ``name`` arrives as ``"models/gemini-2.5-flash"``; the chat path
+            # uses the bare id.
             short_id = (
                 base_id
                 if isinstance(base_id, str) and base_id
@@ -6401,8 +6325,8 @@ class ExternalProviderClient:
         """
         Confirm GET /models returns 200 without buffering the full response body.
 
-        Used for providers with enormous catalogs (e.g. OpenRouter, Hugging Face router)
-        where downloading the full JSON would be prohibitive.
+        Used for providers with enormous catalogs (e.g. OpenRouter, Hugging Face
+        router) where downloading the full JSON would be prohibitive.
         """
         url = f"{self.base_url}/models"
         try:
@@ -6427,11 +6351,11 @@ class ExternalProviderClient:
     def _container_headers(self) -> dict[str, str]:
         """Auth headers plus the OpenAI-Beta opt-in for /v1/containers.
 
-        OpenAI's containers API requires ``OpenAI-Beta: containers=v1``.
-        Without it, DELETE silently no-ops: the API returns 200 with a
-        ``{"deleted": true}`` body but does not actually remove the
-        container (verified 2026-05-15). The header is required for
-        list / create / delete to behave consistently.
+        OpenAI's containers API requires ``OpenAI-Beta: containers=v1``. Without
+        it, DELETE silently no-ops: the API returns 200 with a
+        ``{"deleted": true}`` body but doesn't actually remove the container
+        (verified 2026-05-15). The header is required for list / create / delete
+        to behave consistently.
         """
         headers = self._auth_headers()
         headers["OpenAI-Beta"] = "containers=v1"
@@ -6441,13 +6365,13 @@ class ExternalProviderClient:
         """
         GET /v1/containers on the user's OpenAI account.
 
-        Returns the raw container records (id, name, created_at,
-        last_active_at, expires_after, status). The route layer
-        reshapes these into the UI summary shape.
+        Returns the raw container records (id, name, created_at, last_active_at,
+        expires_after, status). The route layer reshapes these into the UI
+        summary shape.
 
-        Only valid against api.openai.com — non-cloud OpenAI-compat
-        servers don't implement /v1/containers and would 404 here.
-        Caller is responsible for the is_openai_cloud guard.
+        Only valid against api.openai.com — non-cloud OpenAI-compat servers
+        don't implement /v1/containers and would 404 here. Caller is responsible
+        for the is_openai_cloud guard.
         """
         response = await _http_client.get(
             f"{self.base_url}/containers",
@@ -6468,8 +6392,8 @@ class ExternalProviderClient:
     async def create_openai_container(self, name: str, ttl_minutes: int) -> dict[str, Any]:
         """
         POST /v1/containers with ``expires_after.anchor="last_active_at"``.
-        ``ttl_minutes`` is the idle timeout — every API call that
-        touches the container resets the timer.
+        ``ttl_minutes`` is the idle timeout — every API call touching the
+        container resets the timer.
         """
         body = {
             "name": name,
@@ -6491,16 +6415,14 @@ class ExternalProviderClient:
         """DELETE /v1/containers/{id}. 404s are surfaced as HTTPError.
 
         Uses a fresh httpx client (not the shared ``_http_client``) so
-        connection-pool state from earlier chat requests cannot
-        interfere — observed in the wild that DELETEs over the shared
-        pool returned ``deleted: true`` while the container persisted
-        in subsequent /containers list calls, even though the same
-        DELETE issued from a fresh client genuinely removed it.
+        connection-pool state from earlier chat requests can't interfere —
+        observed that DELETEs over the shared pool returned ``deleted: true``
+        while the container persisted in later /containers list calls, even
+        though the same DELETE from a fresh client genuinely removed it.
 
-        Verifies the response body reports ``deleted: true``. OpenAI
-        returns a 2xx ``deleted: true`` body even when the request is
-        silently rejected (e.g. missing OpenAI-Beta header), so a
-        status-only check is not sufficient.
+        Verifies the response body reports ``deleted: true``. OpenAI returns a
+        2xx ``deleted: true`` body even when the request is silently rejected
+        (e.g. missing OpenAI-Beta header), so a status-only check isn't enough.
         """
         url = f"{self.base_url}/containers/{container_id}"
         headers = self._container_headers()
@@ -6588,41 +6510,38 @@ def _error_sse_line(status_code: int, message: str, provider_type: str) -> str:
 def _build_usage_chunk(
     completion_id: str, provider: Literal["anthropic", "openai"], last_usage: Optional[dict]
 ) -> Optional[str]:
-    """Build an OpenAI ``include_usage``-style SSE chunk that carries the
-    upstream prompt-cache accounting back to the client.
+    """Build an OpenAI ``include_usage``-style SSE chunk carrying upstream
+    prompt-cache accounting back to the client.
 
-    Until now Studio captured ``cache_creation_input_tokens`` /
+    Studio captured ``cache_creation_input_tokens`` /
     ``cache_read_input_tokens`` (Anthropic) and
-    ``input_tokens_details.cached_tokens`` (OpenAI Responses) on
-    ``last_usage`` and only wrote them to the structlog stream.
-    Browser / SDK clients had no way to see how many tokens hit the cache
-    -- so the "you saved $X" UX in the chat panel was impossible without
-    scraping the server log.
+    ``input_tokens_details.cached_tokens`` (OpenAI Responses) on ``last_usage``
+    but only wrote them to the structlog stream. Browser / SDK clients couldn't
+    see how many tokens hit the cache, so the "you saved $X" UX was impossible
+    without scraping the server log.
 
-    This helper emits the standard OpenAI chunk shape -- ``choices: []``
-    with a populated ``usage`` block -- so any client that already
-    consumes ``stream_options={"include_usage": true}`` keeps working,
-    and the Anthropic-native counts are surfaced as extra keys on the
-    same ``usage`` dict:
+    This emits the standard OpenAI chunk shape -- ``choices: []`` with a
+    populated ``usage`` block -- so any client consuming
+    ``stream_options={"include_usage": true}`` keeps working, with the
+    Anthropic-native counts surfaced as extra keys on the same ``usage`` dict:
 
         usage.prompt_tokens_details.cached_tokens
             normalised cache-read count, present for both providers.
         usage.cache_creation_input_tokens
             Anthropic-only; tokens billed at the cache-write premium.
         usage.cache_read_input_tokens
-            Anthropic-only; same value as cached_tokens, kept for
-            callers that already key off the native Anthropic name.
+            Anthropic-only; same value as cached_tokens, kept for callers
+            that key off the native Anthropic name.
 
-    Anthropic's ``input_tokens`` excludes the cache buckets -- the
-    real prompt size is ``input_tokens + cache_creation_input_tokens
-    + cache_read_input_tokens``. Emitting ``input_tokens`` alone as
-    ``prompt_tokens`` undercounts cache-heavy turns and breaks
-    downstream context / cost displays, so we add all three input
-    buckets together. OpenAI Responses already folds cached tokens
-    into ``input_tokens`` so no extra arithmetic is needed there.
+    Anthropic's ``input_tokens`` excludes the cache buckets -- real prompt size
+    is ``input_tokens + cache_creation_input_tokens + cache_read_input_tokens``.
+    Emitting ``input_tokens`` alone as ``prompt_tokens`` undercounts cache-heavy
+    turns and breaks downstream context / cost displays, so we sum all three
+    input buckets. OpenAI Responses already folds cached tokens into
+    ``input_tokens`` so no extra arithmetic is needed there.
 
-    Returns ``None`` when there are no usage numbers to report (e.g. an
-    upstream error before ``message_start`` / ``response.completed``).
+    Returns ``None`` when there are no usage numbers to report (e.g. an upstream
+    error before ``message_start`` / ``response.completed``).
     """
     if not isinstance(last_usage, dict):
         return None
@@ -6644,14 +6563,14 @@ def _build_usage_chunk(
             "cache_creation_input_tokens": cache_creation,
             "cache_read_input_tokens": cache_read,
         }
-        # Forward 5m/1h cache-write breakdown so cost calc applies the
-        # 2x 1h premium instead of defaulting to 5m on chat-style.
+        # Forward 5m/1h cache-write breakdown so cost calc applies the 2x 1h
+        # premium instead of defaulting to 5m on chat-style.
         cc_breakdown = last_usage.get("cache_creation")
         if isinstance(cc_breakdown, dict) and cc_breakdown:
             usage_block["cache_creation"] = cc_breakdown
-        # Propagate fast-mode `usage.speed` so the cost ledger can apply
-        # the 6x multiplier without re-derivation (Anthropic falls back
-        # to "standard" when fast-mode is unsupported or rate-limited).
+        # Propagate fast-mode `usage.speed` so the cost ledger applies the 6x
+        # multiplier without re-derivation (Anthropic falls back to "standard"
+        # when fast-mode is unsupported or rate-limited).
         speed = last_usage.get("speed")
         if speed in ("fast", "standard"):
             usage_block["speed"] = speed
@@ -6669,9 +6588,9 @@ def _build_usage_chunk(
             "total_tokens": prompt_tokens + completion_tokens,
             "prompt_tokens_details": {"cached_tokens": cached},
         }
-        # Surface OpenAI Responses / Gemini reasoning-token detail. The
-        # caller pre-populates last_usage["output_tokens_details"] with
-        # at least {"reasoning_tokens": ...}; mirror it into the OAI
+        # Surface OpenAI Responses / Gemini reasoning-token detail. The caller
+        # pre-populates last_usage["output_tokens_details"] with at least
+        # {"reasoning_tokens": ...}; mirror it into the OAI
         # `completion_tokens_details` shape so SDKs can render the
         # hidden-thoughts slice.
         out_details = last_usage.get("output_tokens_details")
diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index 33647a6cd1..0cef6c41ff 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Core inference backend - streamlined
-"""
+"""Core inference backend."""
 
 from unsloth import FastLanguageModel, FastVisionModel
 from unsloth.chat_templates import get_chat_template
@@ -36,29 +34,25 @@ logger = get_logger(__name__)
 
 
 class HarmonyTextStreamer:
-    """Streaming text decoder for gpt-oss harmony channel protocol.
+    """Streaming text decoder for the gpt-oss harmony channel protocol.
 
-    gpt-oss models emit multi-channel output using special tokens like
-    ``<|channel|>analysis<|message|>...`` and ``<|channel|>final<|message|>...``.
-    A plain ``TextIteratorStreamer(skip_special_tokens=True)`` strips the special
-    tokens but leaves the channel names concatenated with content, producing
-    garbled output such as ``analysisWe need to respond...assistantfinalHello!``.
+    gpt-oss emits multi-channel output via special tokens like
+    ``<|channel|>analysis<|message|>...`` / ``<|channel|>final<|message|>...``.
+    A plain ``TextIteratorStreamer(skip_special_tokens=True)`` drops the tokens
+    but leaves channel names glued to content, producing garbled output like
+    ``analysisWe need to respond...assistantfinalHello!``.
 
-    This streamer decodes with ``skip_special_tokens=False`` so the full
-    harmony markup is visible, then uses **stateful incremental** parsing
-    to emit properly-formatted text:
+    This streamer decodes with ``skip_special_tokens=False`` so the harmony
+    markup is visible, then uses stateful incremental parsing:
 
-    - ``<think>`` emitted once when the ``analysis`` channel is first seen
-    - Analysis content streamed incrementally
-    - ``</think>`` emitted once when the ``final`` channel is first seen
-    - Final content streamed incrementally
+    - ``<think>`` once when ``analysis`` channel is first seen
+    - analysis content streamed incrementally
+    - ``</think>`` once when ``final`` channel is first seen
+    - final content streamed incrementally
 
     This avoids the delta-on-transformed bug where wrapping tags shift
-    position as content grows.
-
-    Implements the same ``put`` / ``end`` / iterator interface as
-    ``TextIteratorStreamer`` so ``generate_stream`` can use it as a drop-in
-    replacement.
+    position as content grows. Implements the same ``put`` / ``end`` / iterator
+    interface as ``TextIteratorStreamer`` for drop-in use in ``generate_stream``.
     """
 
     import re as _re
@@ -87,7 +81,7 @@ class HarmonyTextStreamer:
         self._is_first_put: bool = True
         self._stop: bool = False
 
-        # Stateful channel tracking — avoids delta-on-transformed bugs
+        # Stateful channel tracking avoids delta-on-transformed bugs
         self._emitted_think_open: bool = False
         self._emitted_think_close: bool = False
         self._analysis_emitted: int = 0  # chars of analysis content emitted
@@ -102,7 +96,7 @@ class HarmonyTextStreamer:
         import torch
 
         if isinstance(value, torch.Tensor):
-            # value shape: (batch, seq) — take first batch element
+            # shape (batch, seq) — take first batch element
             ids = value[0].tolist() if value.dim() > 1 else value.tolist()
         elif isinstance(value, (list, tuple)):
             ids = list(value)
@@ -110,7 +104,7 @@ class HarmonyTextStreamer:
             ids = [value]
 
         if self._is_first_put and self.skip_prompt:
-            # First call contains the full prompt; remember its length
+            # First call is the full prompt; remember its length
             self._prompt_len = len(ids)
             self._token_ids = list(ids)
             self._is_first_put = False
@@ -125,7 +119,7 @@ class HarmonyTextStreamer:
 
     def end(self):
         """Signal generation is complete."""
-        # Final decode to capture any remaining content
+        # Final decode to capture remaining content
         gen_ids = self._token_ids[self._prompt_len :]
         if gen_ids:
             raw = self.tokenizer.decode(gen_ids, skip_special_tokens = False)
@@ -164,19 +158,19 @@ class HarmonyTextStreamer:
     # ------------------------------------------------------------------
 
     def _process_incremental(self, raw: str) -> None:
-        """Parse harmony channels and emit deltas per-channel.
+        """Parse harmony channels and emit per-channel deltas.
 
-        Instead of transforming the entire raw text and computing a string
-        delta (which breaks when wrapping ``<think>`` tags shift position),
-        this tracks per-channel content lengths and emits:
+        Tracks per-channel content lengths (instead of diffing transformed
+        whole-text, which breaks when wrapping ``<think>`` tags shift position)
+        and emits:
 
         - ``<think>`` once when analysis channel first appears
         - analysis content deltas (computed on channel content directly)
         - ``</think>`` once when final channel first appears
         - final content deltas
         """
-        # If raw contains <|channel|> but no complete channel+message pair yet,
-        # buffer silently — don't emit partial channel names as text.
+        # raw has <|channel|> but no complete channel+message pair yet:
+        # buffer silently, don't emit partial channel names as text.
         has_channel_token = "<|channel|>" in raw
         matches = list(self._HARMONY_RE.finditer(raw))
 
@@ -185,8 +179,7 @@ class HarmonyTextStreamer:
             return
 
         if not has_channel_token and not matches:
-            # No harmony protocol at all — should not happen for gpt-oss
-            # but handle gracefully by not emitting anything
+            # No harmony protocol (shouldn't happen for gpt-oss) — emit nothing
             return
 
         for m in matches:
@@ -228,11 +221,11 @@ class InferenceBackend:
         self.device = get_device().value
         self._audio_codec_manager = AudioCodecManager()
 
-        # Thread safety — _generation_lock serializes model.generate() calls.
-        # Must be a regular Lock (NOT RLock) because in async FastAPI, multiple
-        # requests share the same event-loop thread, so RLock reentrancy lets
-        # concurrent compare-mode requests race on the GPU.  The lock is
-        # acquired by the *background generation thread*, not the event-loop.
+        # _generation_lock serializes model.generate() calls. Must be a plain
+        # Lock (NOT RLock): in async FastAPI requests share one event-loop
+        # thread, so RLock reentrancy would let concurrent compare-mode
+        # requests race on the GPU. Acquired by the *background generation
+        # thread*, not the event-loop.
         import threading
 
         self._generation_lock = threading.Lock()
@@ -242,7 +235,7 @@ class InferenceBackend:
 
     @staticmethod
     def _normalize_top_k(top_k: int) -> int:
-        # API supports -1 as "disable top-k"; transformers expects 0 to disable.
+        # API uses -1 to disable top-k; transformers uses 0.
         return 0 if top_k < 0 else top_k
 
     def load_model(
@@ -255,9 +248,7 @@ class InferenceBackend:
         trust_remote_code: bool = False,
         gpu_ids: Optional[list[int]] = None,
     ) -> bool:
-        """
-        Load any model: base, LoRA adapter, text, or vision.
-        """
+        """Load any model: base, LoRA adapter, text, or vision."""
         # GGUF uses max_seq_length=0 as "model default"; Unsloth crashes on it.
         if max_seq_length <= 0:
             max_seq_length = 2048
@@ -265,13 +256,13 @@ class InferenceBackend:
         try:
             model_name = config.identifier
 
-            # Check if already loaded
+            # Already loaded?
             if model_name in self.models and self.models[model_name].get("model"):
                 logger.info(f"Model {model_name} already loaded")
                 self.active_model_name = model_name
                 return True
 
-            # Check if currently loading
+            # Currently loading?
             if model_name in self.loading_models:
                 logger.info(f"Model {model_name} is already being loaded")
                 return False
@@ -322,9 +313,9 @@ class InferenceBackend:
                     from unsloth import FastModel
 
                     if config.is_lora and config.base_model:
-                        # LoRA adapter: load from local adapter path.
-                        # base_model is e.g. /home/.../Spark-TTS-0.5B/LLM
-                        # The BiCodec weights are in the parent dir (Spark-TTS-0.5B/).
+                        # LoRA adapter from local path. base_model is e.g.
+                        # /home/.../Spark-TTS-0.5B/LLM; BiCodec weights live in
+                        # the parent dir (Spark-TTS-0.5B/).
                         base_path = config.base_model
                         if os.path.isdir(base_path):
                             abs_repo_path = os.path.abspath(os.path.dirname(base_path))
@@ -348,7 +339,7 @@ class InferenceBackend:
                             trust_remote_code = trust_remote_code,
                         )
                     else:
-                        # Base model: download full HF repo, then load from /LLM subfolder
+                        # Base model: download full HF repo, load from /LLM subfolder
                         from huggingface_hub import snapshot_download
 
                         hf_repo = config.path
@@ -406,7 +397,7 @@ class InferenceBackend:
                     FastModel.for_inference(model)
                     model.eval()
 
-                    # Create ASR pipeline (per notebook)
+                    # ASR pipeline (per notebook)
                     from transformers import pipeline as hf_pipeline
 
                     whisper_pipe = hf_pipeline(
@@ -435,8 +426,8 @@ class InferenceBackend:
                     self.models[model_name]["model"] = model
                     self.models[model_name]["tokenizer"] = tokenizer
 
-                # Load the external codec for TTS audio types
-                # (Whisper is ASR, audio_vlm is audio input — neither needs a codec)
+                # Load external codec for TTS audio types
+                # (Whisper is ASR, audio_vlm is audio input — neither needs one)
                 if audio_type not in ("whisper", "audio_vlm"):
                     model_repo_path = self.models[model_name].get("model_repo_path")
                     self._audio_codec_manager.load_codec(
@@ -457,7 +448,7 @@ class InferenceBackend:
             logger.info(f"Loading {model_type} model{adapter_info}: {model_name}")
             log_gpu_memory(f"Before loading {model_name}")
 
-            # Load model - same approach for base models and LoRA adapters
+            # Same load path for base models and LoRA adapters
             if config.is_vision:
                 # Vision model (or vision LoRA adapter)
                 model, processor = FastVisionModel.from_pretrained(
@@ -470,19 +461,19 @@ class InferenceBackend:
                     trust_remote_code = trust_remote_code,
                 )
 
-                # Apply inference optimization
                 FastVisionModel.for_inference(model)
 
-                # FastVisionModel may return a raw tokenizer (e.g. GemmaTokenizerFast)
-                # instead of a proper Processor for some models (e.g. Gemma-3).
-                # In that case, load the real processor from the base model.
+                # FastVisionModel may return a raw tokenizer (e.g.
+                # GemmaTokenizerFast) instead of a proper Processor for some
+                # models (e.g. Gemma-3). If so, load the real processor from
+                # the base model.
                 from transformers import ProcessorMixin
 
                 if not (
                     isinstance(processor, ProcessorMixin) or hasattr(processor, "image_processor")
                 ):
-                    # For LoRA adapters, use the base model. For local merged exports,
-                    # read export_metadata.json to find the original base model.
+                    # LoRA adapters: use the base model. Local merged exports:
+                    # read export_metadata.json for the original base model.
                     processor_source = config.base_model if config.is_lora else config.identifier
                     if not config.is_lora and config.is_local:
                         _meta_path = Path(config.path) / "export_metadata.json"
@@ -522,7 +513,6 @@ class InferenceBackend:
                     trust_remote_code = trust_remote_code,
                 )
 
-                # Apply inference optimization
                 FastLanguageModel.for_inference(model)
 
                 self.models[model_name]["model"] = model
@@ -530,7 +520,6 @@ class InferenceBackend:
 
             raise_if_offloaded(self.models[model_name]["model"], device_map, "Inference")
 
-            # Load chat template info
             self._load_chat_template_info(model_name)
 
             self.active_model_name = model_name
@@ -552,29 +541,25 @@ class InferenceBackend:
             raise Exception(error_msg)
 
     def unload_model(self, model_name: str) -> bool:
-        """
-        Completely removes a model from the registry and clears GPU memory.
-        """
+        """Remove a model from the registry and clear GPU memory."""
         if model_name in self.models:
             try:
-                # If this was an audio model, clean up codecs
+                # Clean up codecs for audio models
                 if self.models[model_name].get("is_audio"):
                     self._audio_codec_manager.unload()
 
                 logger.info(f"Unloading model '{model_name}' from memory.")
-                # Delete the model entry from our registry
                 del self.models[model_name]
 
-                # Clear the active model if it was the one being unloaded
+                # Clear the active model if it was the one unloaded
                 if self.active_model_name == model_name:
                     self.active_model_name = None
 
-                # Clear GPU memory cache
                 clear_gpu_cache()
 
-                # Remove stale compiled cache so the next model gets a fresh one.
-                # On spawn-based platforms, preserve trainer files so that any
-                # concurrent training dataset.map() workers can still import them.
+                # Drop stale compiled cache so the next model gets a fresh one.
+                # On spawn-based platforms, preserve trainer files so concurrent
+                # training dataset.map() workers can still import them.
                 import sys as _sys
                 from utils.cache_cleanup import clear_unsloth_compiled_cache
 
@@ -593,26 +578,23 @@ class InferenceBackend:
             return True
 
     def revert_to_base_model(self, base_model_name: str) -> bool:
-        """
-        Reverts the model to its pristine base state by unloading AND
-        deleting all adapter configurations, as instructed.
-        """
+        """Revert the model to its pristine base state by unloading and
+        deleting all adapter configurations."""
         if base_model_name not in self.models:
             return False
 
         model = self.models[base_model_name].get("model")
 
         try:
-            # Step 1: Unload the adapter weights if model is a PeftModel.
+            # Unload adapter weights if model is a PeftModel.
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
                 logger.info(f"Unloading LoRA adapters from '{base_model_name}'...")
                 unwrapped_base_model = model.unload()
                 self.models[base_model_name]["model"] = unwrapped_base_model
                 model = unwrapped_base_model
 
-            # Step 2: Clear any lingering peft_config from the unwrapped model.
-            # After model.unload(), the base model may still carry a peft_config
-            # attribute. Removing it ensures PeftModel.from_pretrained() gets
+            # Clear any lingering peft_config. model.unload() can leave a
+            # peft_config attribute; removing it gives PeftModel.from_pretrained()
             # a clean base model without "multiple adapters" warnings.
             if hasattr(model, "peft_config"):
                 del model.peft_config
@@ -636,10 +618,8 @@ class InferenceBackend:
         hf_token: Optional[str] = None,
         gpu_ids: Optional[list[int]] = None,
     ) -> Tuple[bool, Optional[str], Optional[str]]:
-        """
-        Final Corrected Version:
-        Ensures the base model and the specified adapter are loaded.
-        This function is idempotent and handles all states correctly.
+        """Ensure the base model and the given adapter are loaded.
+        Idempotent and handles all states correctly.
         """
         try:
             from utils.models import ModelConfig
@@ -650,7 +630,7 @@ class InferenceBackend:
 
             base_model_name = lora_config.base_model
 
-            # 1. Load the base model if it's not already in memory
+            # 1. Load the base model if not already in memory
             if base_model_name not in self.models or not self.models[base_model_name].get("model"):
                 logger.info(f"Base model '{base_model_name}' not loaded, loading now.")
                 base_config = ModelConfig.from_ui_selection(base_model_name, None, is_lora = False)
@@ -666,11 +646,11 @@ class InferenceBackend:
 
             self.active_model_name = base_model_name
 
-            # 2. Determine the required adapter name from the user's selection
+            # 2. Derive adapter name from the user's selection
             adapter_name = lora_path.split("/")[-1].replace(".", "_")
 
-            # 3. Call our robust load_adapter function to ensure this specific adapter is loaded.
-            # It will only load from disk if the model doesn't already have it.
+            # 3. Ensure this adapter is loaded (load_adapter only reads from
+            # disk if the model doesn't already have it).
             adapter_success = self.load_adapter(
                 base_model_name = base_model_name,
                 adapter_path = lora_path,
@@ -679,7 +659,7 @@ class InferenceBackend:
             if not adapter_success:
                 return False, base_model_name, None
 
-            # 4. Return the correct, verified adapter name for the UI logic to use.
+            # 4. Return the verified adapter name for the UI.
             return True, base_model_name, adapter_name
 
         except Exception as e:
@@ -690,12 +670,10 @@ class InferenceBackend:
             return False, None, None
 
     def load_adapter(self, base_model_name: str, adapter_path: str, adapter_name: str) -> bool:
-        """
-        Loads an adapter onto the model ONLY if it's not already attached.
-        """
+        """Load an adapter onto the model only if not already attached."""
         model = self.models[base_model_name].get("model")
 
-        # Check if this adapter name is already part of the model's config. This is the most reliable check.
+        # Most reliable check: adapter name already in the model's config.
         if hasattr(model, "peft_config") and adapter_name in model.peft_config:
             logger.info(
                 f"Adapter '{adapter_name}' is already attached to the model. Skipping load."
@@ -708,7 +686,7 @@ class InferenceBackend:
             )
             model.load_adapter(adapter_path, adapter_name = adapter_name)
 
-            # Update our internal registry ONLY after a successful load.
+            # Update the registry only after a successful load.
             if "loaded_adapters" not in self.models[base_model_name]:
                 self.models[base_model_name]["loaded_adapters"] = {}
             self.models[base_model_name]["loaded_adapters"][adapter_name] = adapter_path
@@ -723,9 +701,8 @@ class InferenceBackend:
             return False
 
     def set_active_adapter(self, base_model_name: str, adapter_name: str) -> bool:
-        """
-        Sets the active adapter for generation. This replaces the flawed 'enable_adapter'.
-        """
+        """Set the active adapter for generation (replaces the flawed
+        'enable_adapter')."""
         model = self.models[base_model_name].get("model")
         try:
             logger.info(f"Setting active adapter to: '{adapter_name}'")
@@ -733,18 +710,17 @@ class InferenceBackend:
             self.models[base_model_name]["active_adapter"] = adapter_name
             return True
         except Exception as e:
-            # This will catch the "adapter not found" error if something goes wrong.
+            # Catches "adapter not found" if something goes wrong.
             logger.error(f"Failed to set active adapter to '{adapter_name}': {e}")
             return False
 
     def _apply_adapter_state(self, use_adapter: Optional[Union[bool, str]]) -> None:
-        """
-        Apply adapter state before generation. Must be called under _generation_lock.
+        """Apply adapter state before generation. Must hold _generation_lock.
 
-        Uses PEFT's disable_adapter_layers() / enable_adapter_layers() which toggle
-        a boolean flag on each LoRA layer. Unsloth's fast_linear_forward checks this
-        flag (proj.disable_adapters) and skips LoRA computation when True.
-        This is non-destructive — no model unloading/reloading needed.
+        Uses PEFT's disable_adapter_layers() / enable_adapter_layers(), which
+        toggle a flag (proj.disable_adapters) on each LoRA layer; Unsloth's
+        fast_linear_forward checks it and skips LoRA when True. Non-destructive,
+        no unload/reload.
 
         Args:
             use_adapter: None = no change, False = disable (base model),
@@ -781,7 +757,7 @@ class InferenceBackend:
                 logger.warning("use_adapter=true but model is not a PeftModel")
 
         elif isinstance(use_adapter, str):
-            # Enable adapters and set the specific one active
+            # Enable adapters and set the named one active
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
                 logger.info(f"Compare mode: enabling adapter '{use_adapter}' on '{base}'")
                 model.base_model.enable_adapter_layers()
@@ -795,13 +771,12 @@ class InferenceBackend:
         cancel_event = None,
         **gen_kwargs,
     ) -> Generator[str, None, None]:
-        """
-        Thread-safe generation with optional adapter toggling.
+        """Thread-safe generation with optional adapter toggling.
 
         The adapter toggle + model.generate() are serialized by _generation_lock
-        inside the background generation thread — NOT in the event-loop thread.
-        This prevents the RLock-reentrant race that occurs when two async SSE
-        handlers share the same event-loop thread.
+        in the background generation thread, NOT the event-loop thread. Prevents
+        the RLock-reentrant race when two async SSE handlers share one
+        event-loop thread.
 
         Args:
             use_adapter: Adapter control (None/False/True/str). See _apply_adapter_state.
@@ -833,9 +808,8 @@ class InferenceBackend:
     ):
         """Run an agentic tool loop on top of ``generate_chat_response``.
 
-        Yields the same event-dict protocol used by the GGUF path so
-        the route layer can stream both backends through one helper.
-        Each event is one of:
+        Yields the same event-dict protocol as the GGUF path so the route
+        layer can stream both backends through one helper. Each event is one of:
 
         * ``{"type": "status", "text": ...}``
         * ``{"type": "content", "text": cumulative_text}``
@@ -896,15 +870,14 @@ class InferenceBackend:
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
     ) -> Generator[str, None, None]:
-        """
-        Generate response for text or vision models.
+        """Generate response for text or vision models.
         The generation lock is acquired by the background generation thread.
 
         ``tools`` / ``enable_thinking`` / ``reasoning_effort`` /
         ``preserve_thinking`` are forwarded into
-        ``tokenizer.apply_chat_template`` so templates that understand
-        these kwargs (Qwen3, Llama 3.1+, gpt-oss harmony, ...) advertise
-        the tool schemas and reasoning controls to the model.
+        ``tokenizer.apply_chat_template`` so templates that understand them
+        (Qwen3, Llama 3.1+, gpt-oss harmony, ...) advertise the tool schemas
+        and reasoning controls to the model.
         """
         yield from self._generate_chat_response_inner(
             messages = messages,
@@ -941,9 +914,8 @@ class InferenceBackend:
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
     ) -> Generator[str, None, None]:
-        """
-        Inner generation logic. Called by both generate_chat_response
-        and generate_with_adapter_control.
+        """Inner generation logic, called by generate_chat_response and
+        generate_with_adapter_control.
 
         _adapter_state is passed to generate_stream/vision so the background
         thread can toggle adapters under the generation lock.
@@ -960,10 +932,10 @@ class InferenceBackend:
         top_k = self._normalize_top_k(top_k)
 
         if is_vision and image:
-            # Vision model generation (only when an image is actually provided)
-            # Check that the stored processor can actually handle images.
-            # FastVisionModel may return a raw tokenizer (e.g. GemmaTokenizerFast)
-            # instead of a proper ProcessorMixin for some models (e.g. Gemma-3).
+            # Vision generation (only with an actual image). Verify the stored
+            # processor can handle images — FastVisionModel may return a raw
+            # tokenizer (e.g. GemmaTokenizerFast) instead of a ProcessorMixin
+            # for some models (e.g. Gemma-3).
             from transformers import ProcessorMixin
 
             processor = model_info.get("processor")
@@ -991,10 +963,10 @@ class InferenceBackend:
                     f"falling back to text-only generation (image will be ignored)."
                 )
 
-        # Text path: Use training pipeline approach
-        # Messages are already in ChatML format from eval.py
+        # Text path: training-pipeline approach. Messages are already in
+        # ChatML format from eval.py.
 
-        # Step 1: Apply get_chat_template if model is in mapper
+        # Step 1: apply get_chat_template if model is in mapper
         try:
             from utils.datasets import (
                 MODEL_TO_TEMPLATE_MAPPER,
@@ -1002,14 +974,13 @@ class InferenceBackend:
             )
             model_name_lower = self.active_model_name.lower()
 
-            # Check if model has a registered template
             if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
                 template_name = MODEL_TO_TEMPLATE_MAPPER[model_name_lower]
                 logger.info(
                     f"Applying chat template '{template_name}' for {self.active_model_name}"
                 )
 
-                # This modifies the tokenizer with the correct template
+                # Sets the correct template on the tokenizer
                 tokenizer = get_chat_template(
                     tokenizer,
                     chat_template = template_name,
@@ -1021,7 +992,7 @@ class InferenceBackend:
         except Exception as e:
             logger.warning(f"Could not apply get_chat_template: {e}")
 
-        # Step 2: Format with tokenizer.apply_chat_template()
+        # Step 2: format with tokenizer.apply_chat_template()
         if system_prompt:
             template_messages = [{"role": "system", "content": system_prompt}] + messages
         else:
@@ -1046,10 +1017,10 @@ class InferenceBackend:
             logger.debug(f"Formatted prompt: {formatted_prompt[:200]}...")
         except Exception as e:
             logger.error(f"Error applying chat template: {e}")
-            # Fallback to manual formatting
+            # Fall back to manual formatting
             formatted_prompt = self.format_chat_prompt(messages, system_prompt)
 
-        # Step 3: Generate
+        # Step 3: generate
         yield from self.generate_stream(
             formatted_prompt,
             temperature,
@@ -1080,7 +1051,7 @@ class InferenceBackend:
         model = model_info["model"]
         processor = model_info["processor"]
         # FastVisionModel may return a raw tokenizer (e.g. GemmaTokenizerFast)
-        # instead of a Processor for some models. Safe unwrap for tokenize-only ops.
+        # for some models. Safe unwrap for tokenize-only ops.
         raw_tokenizer = getattr(processor, "tokenizer", processor)
 
         # Extract user message
@@ -1136,7 +1107,7 @@ class InferenceBackend:
                 return_tensors = "pt",
             ).to(model.device)
         else:
-            # Text-only for vision model
+            # Text-only path for a vision model
             formatted_prompt = self.format_chat_prompt(messages, system_prompt)
             inputs = raw_tokenizer(formatted_prompt, return_tensors = "pt").to(model.device)
 
@@ -1233,7 +1204,7 @@ class InferenceBackend:
         repetition_penalty,
         cancel_event = None,
     ) -> Generator[str, None, None]:
-        """Handle audio input (ASR) generation — accepts audio numpy array, streams text output.
+        """Audio-input (ASR) generation: takes an audio numpy array, streams text.
 
         Uses processor.apply_chat_template with audio embedded in messages (Gemma 3n pattern).
         """
@@ -1245,7 +1216,7 @@ class InferenceBackend:
         processor = model_info.get("processor") or model_info.get("tokenizer")
         raw_tokenizer = getattr(processor, "tokenizer", processor)
 
-        # Extract last user text — default matches notebook prompt
+        # Last user text; default matches the notebook prompt
         user_text = "Please transcribe this audio."
         if messages:
             for msg in reversed(messages):
@@ -1253,11 +1224,11 @@ class InferenceBackend:
                     user_text = msg["content"]
                     break
 
-        # Use ASR-specific system prompt if user hasn't set a custom one
+        # ASR-specific default system prompt if none set
         if not system_prompt:
             system_prompt = "You are an assistant that transcribes speech accurately."
 
-        # Build messages in Gemma 3n format — audio goes INTO apply_chat_template
+        # Gemma 3n format — audio goes INTO apply_chat_template
         audio_messages = [
             {"role": "system", "content": [{"type": "text", "text": system_prompt}]},
             {
@@ -1269,7 +1240,7 @@ class InferenceBackend:
             },
         ]
 
-        # apply_chat_template handles audio embedding + tokenization in one step
+        # apply_chat_template does audio embedding + tokenization in one step
         inputs = processor.apply_chat_template(
             audio_messages,
             add_generation_prompt = True,
@@ -1290,7 +1261,7 @@ class InferenceBackend:
                 timeout = 0.2,
             )
 
-            # Notebook uses do_sample=False for ASR (greedy decoding for accuracy)
+            # Notebook uses do_sample=False (greedy) for ASR accuracy
             generation_kwargs = dict(
                 **inputs,
                 streamer = streamer,
@@ -1354,9 +1325,9 @@ class InferenceBackend:
         audio_array,
         cancel_event = None,
     ) -> Generator[str, None, None]:
-        """Whisper ASR — takes audio numpy array, yields transcribed text.
+        """Whisper ASR: takes an audio numpy array, yields transcribed text.
 
-        Uses the pre-built transformers pipeline (created during model loading).
+        Uses the pre-built transformers pipeline created at model load.
         """
         model_info = self.models[self.active_model_name]
         whisper_pipe = model_info.get("whisper_pipeline")
@@ -1376,7 +1347,7 @@ class InferenceBackend:
             yield f"Error: {str(e)}"
 
     def _is_gpt_oss_model(self, model_name: str = None) -> bool:
-        """Check if the given (or active) model uses the gpt-oss harmony protocol."""
+        """Whether the given (or active) model uses the gpt-oss harmony protocol."""
         from utils.datasets import is_gpt_oss_model_name
         return is_gpt_oss_model_name(model_name or self.active_model_name or "")
 
@@ -1392,10 +1363,10 @@ class InferenceBackend:
         cancel_event = None,
         _adapter_state = None,
     ) -> Generator[str, None, None]:
-        """Generate streaming text response (text models only).
+        """Generate a streaming text response (text models only).
 
         _adapter_state: if not None, the background thread toggles adapters
-        before model.generate(), all under _generation_lock.
+        before model.generate(), under _generation_lock.
         """
         if not self.active_model_name:
             yield "Error: No active model"
@@ -1403,9 +1374,9 @@ class InferenceBackend:
 
         model_info = self.models[self.active_model_name]
         model = model_info["model"]
-        # For VLMs the stored "tokenizer" is actually the processor.
-        # Unwrap to get the real tokenizer so TextIteratorStreamer's
-        # skip_prompt / skip_special_tokens work correctly.
+        # For VLMs the stored "tokenizer" is actually the processor. Unwrap to
+        # the real tokenizer so TextIteratorStreamer's skip_prompt /
+        # skip_special_tokens work correctly.
         tokenizer = model_info["tokenizer"]
         tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
 
@@ -1415,8 +1386,8 @@ class InferenceBackend:
             from transformers import TextIteratorStreamer
             import threading
 
-            # Use HarmonyTextStreamer for gpt-oss models to properly parse
-            # the multi-channel harmony protocol into <think> tags
+            # gpt-oss models: HarmonyTextStreamer parses the multi-channel
+            # harmony protocol into <think> tags
             if self._is_gpt_oss_model():
                 try:
                     streamer = HarmonyTextStreamer(
@@ -1513,11 +1484,10 @@ class InferenceBackend:
                         cleaned = self._clean_generated_text(output)
                         yield cleaned
             finally:
-                # Only set cancel_event when we exited early (user cancel),
-                # NOT on normal completion.  cancel_event is a shared mp.Event
-                # — setting it unconditionally would leave a stale cancel
-                # signal that could interfere with the next serialized
-                # generation request (e.g. in compare mode).
+                # Set cancel_event only on early exit (user cancel), NOT on
+                # normal completion. It's a shared mp.Event; setting it
+                # unconditionally would leave a stale cancel signal that could
+                # disrupt the next serialized request (e.g. compare mode).
                 if cancel_event is not None and not generation_complete:
                     cancel_event.set()
                 thread.join(timeout = 10)
@@ -1544,10 +1514,8 @@ class InferenceBackend:
         repetition_penalty: float = 1.0,
         use_adapter: Optional[Union[bool, str]] = None,
     ) -> Tuple[bytes, int]:
-        """
-        Generate audio from text for TTS models.
-        Returns (wav_bytes, sample_rate).
-        Blocking — generates complete audio before returning.
+        """Generate audio from text for TTS models.
+        Returns (wav_bytes, sample_rate). Blocking — full audio before return.
         """
         if not self.active_model_name:
             raise RuntimeError("No active model")
@@ -1661,8 +1629,8 @@ class InferenceBackend:
         repetition_penalty,
     ):
         """Generate audio using DAC (OuteTTS). Follows Oute_TTS_(1B).ipynb exactly."""
-        # Monkey-patch RepetitionPenaltyLogitsProcessor with a 64-token penalty
-        # window (same as the OuteTTS notebook) to avoid degenerate repetition.
+        # Monkey-patch RepetitionPenaltyLogitsProcessor with a 64-token window
+        # (same as the OuteTTS notebook) to avoid degenerate repetition.
         self._patch_repetition_penalty_processor()
 
         prompt = (
@@ -1689,10 +1657,9 @@ class InferenceBackend:
 
     @classmethod
     def _patch_repetition_penalty_processor(cls):
-        """
-        Monkey-patch transformers' RepetitionPenaltyLogitsProcessor with a
-        64-token sliding window variant (from the OuteTTS notebook).
-        Only applied once per process.
+        """Monkey-patch transformers' RepetitionPenaltyLogitsProcessor with a
+        64-token sliding-window variant (from the OuteTTS notebook).
+        Applied once per process.
         """
         if cls._repetition_penalty_patched:
             return
@@ -1743,10 +1710,10 @@ class InferenceBackend:
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
     ) -> str:
-        """Render the chat prompt, peeling kwargs the template does not
-        understand. Delegates to the dependency-light helper module so
-        the fallback chain can be unit-tested without pulling unsloth /
-        torch into the test sandbox.
+        """Render the chat prompt, peeling kwargs the template doesn't
+        understand. Delegates to the dependency-light helper module so the
+        fallback chain is unit-testable without pulling unsloth / torch into
+        the test sandbox.
         """
         from core.inference.chat_template_helpers import (
             apply_chat_template_for_generation,
@@ -1846,8 +1813,7 @@ class InferenceBackend:
             return self._format_generic_template(chat_messages, {})
 
     def _format_chat_manual(self, messages: list, template_type: str, special_tokens: dict) -> str:
-        """
-        Manual chat formatting fallback for when tokenizer template fails
+        """Manual chat-formatting fallback when the tokenizer template fails.
 
         Args:
             messages: List of message dictionaries
@@ -1960,12 +1926,7 @@ class InferenceBackend:
         return formatted
 
     def check_vision_model_compatibility(self) -> bool:
-        """
-        Check if current model supports vision.
-
-        Returns:
-            bool: True if current model supports vision, False otherwise
-        """
+        """Whether the current model supports vision."""
         current_model = self.get_current_model()
         if current_model and current_model in self.models:
             return self.models[current_model].get("is_vision", False)
@@ -1981,7 +1942,7 @@ class InferenceBackend:
             return
 
         try:
-            # This is a common pattern for Unsloth/Hugging Face models
+            # Common pattern for Unsloth/Hugging Face models
             if hasattr(model, "past_key_values"):
                 model.past_key_values = None
             if hasattr(model, "generation_config"):
@@ -1995,7 +1956,7 @@ class InferenceBackend:
     def reset_generation_state(self):
         """Reset any cached generation state to prevent hanging after errors"""
         try:
-            # Clear cached states for ALL loaded models
+            # Clear cached state for ALL loaded models
             for model_name in self.models.keys():
                 self._reset_model_generation_state(model_name)
 
@@ -2029,9 +1990,9 @@ class InferenceBackend:
     def _clean_generated_text(self, text: str) -> str:
         """Strip leaked special tokens using the tokenizer's own token list."""
         if self._is_gpt_oss_model():
-            # HarmonyTextStreamer produces clean <think>...</think> output.
-            # Strip harmony protocol tokens and other gpt-oss added tokens
-            # (e.g. <|return|>) that may leak past the streamer.
+            # HarmonyTextStreamer emits clean <think>...</think>. Strip any
+            # harmony protocol tokens and other gpt-oss tokens (e.g.
+            # <|return|>) that leak past the streamer.
             import re
             text = re.sub(r"<\|[a-z_]+\|>", "", text)
             return text.strip()
@@ -2059,7 +2020,7 @@ class InferenceBackend:
         try:
             from utils.datasets import MODEL_TO_TEMPLATE_MAPPER
 
-            # Try exact match first
+            # Exact match first
             model_name_lower = model_name.lower()
             if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
                 chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[model_name_lower]
@@ -2067,7 +2028,7 @@ class InferenceBackend:
                     f"Detected template '{chat_template_info['template_name']}' for {model_name} from mapper"
                 )
             else:
-                # Try partial match (for variants like model_name-bnb-4bit)
+                # Partial match (for variants like model_name-bnb-4bit)
                 for key in MODEL_TO_TEMPLATE_MAPPER:
                     if key in model_name_lower or model_name_lower in key:
                         chat_template_info["template_name"] = MODEL_TO_TEMPLATE_MAPPER[key]
@@ -2127,15 +2088,15 @@ class InferenceBackend:
             logger.info(f"No built-in chat template for {model_name}, will use generic formatting")
 
     def get_current_model(self) -> Optional[str]:
-        """Get currently active model name"""
+        """Currently active model name."""
         return self.active_model_name
 
     def is_model_loading(self) -> bool:
-        """Check if any model is currently loading"""
+        """Whether any model is currently loading."""
         return len(self.loading_models) > 0
 
     def get_loading_model(self) -> Optional[str]:
-        """Get name of currently loading model"""
+        """Name of the currently loading model."""
         return next(iter(self.loading_models)) if self.loading_models else None
 
     def load_model_simple(
@@ -2145,9 +2106,8 @@ class InferenceBackend:
         max_seq_length: int = 2048,
         load_in_4bit: bool = True,
     ) -> bool:
-        """
-        Simple model loading wrapper for chat interface.
-        Accepts model path as string and handles ModelConfig creation internally.
+        """Simple model-loading wrapper for the chat interface. Takes a string
+        path and builds the ModelConfig internally.
 
         Args:
             model_path: Model name or path (e.g., "unsloth/llama-3-8b")
@@ -2159,14 +2119,12 @@ class InferenceBackend:
             bool: True if successful, False otherwise
         """
         try:
-            # Create config from string path
             config = ModelConfig.from_ui_selection(
                 model_path,
                 lora_path = None,  # No LoRA for chat
                 is_lora = False,
             )
 
-            # Call existing load_model with config
             return self.load_model(
                 config = config,
                 max_seq_length = max_seq_length,
diff --git a/studio/backend/core/inference/key_exchange.py b/studio/backend/core/inference/key_exchange.py
index f43bb16cf6..ddc726751d 100644
--- a/studio/backend/core/inference/key_exchange.py
+++ b/studio/backend/core/inference/key_exchange.py
@@ -4,13 +4,13 @@
 """
 RSA key pair for encrypting API keys in transit.
 
-The frontend encrypts API keys with the server's public key before
-including them in requests. The backend decrypts with its private key
-before forwarding to external providers.
+The frontend encrypts API keys with the server's public key before sending
+them; the backend decrypts with its private key before forwarding to external
+providers.
 
-The key pair is generated at server startup and lives only in memory —
-it is regenerated on each restart. The frontend fetches the public key
-via GET /api/providers/public-key on load.
+The key pair is generated at server startup, lives only in memory, and is
+regenerated on each restart. The frontend fetches the public key via
+GET /api/providers/public-key on load.
 """
 
 import base64
@@ -36,9 +36,9 @@ def init_key_pair() -> None:
     """Generate an RSA-2048 key pair. Called once at server startup."""
     global _private_key, _public_key_pem, _public_key_fingerprint
     if _private_key is not None:
-        # Re-entry is suspicious — every fresh keypair invalidates all
-        # in-flight ciphertext encrypted against the previous public key.
-        # Log loudly so a regression that calls init twice is visible.
+        # Re-entry is suspicious — a fresh keypair invalidates all in-flight
+        # ciphertext encrypted against the previous public key. Log loudly so a
+        # regression that calls init twice is visible.
         logger.warning(
             "init_key_pair called again — replacing existing RSA keypair "
             "(previous fingerprint=%s). Any frontend that cached the old "
@@ -111,9 +111,9 @@ def decrypt_api_key(encrypted_b64: str) -> str:
             ),
         )
     except Exception as exc:
-        # Surface enough state to distinguish key mismatch (wrong public key
-        # used on encrypt) from a padding/algo mismatch or corrupted bytes.
-        # Expected ciphertext length for RSA-2048 is exactly 256 bytes.
+        # Surface enough state to tell a key mismatch (wrong public key used on
+        # encrypt) from a padding/algo mismatch or corrupted bytes. Expected
+        # RSA-2048 ciphertext length is exactly 256 bytes.
         logger.warning(
             "decrypt_api_key: RSA decrypt failed (ciphertext_len=%d, expected=256, "
             "fingerprint=%s, exc=%s): %s",
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 72dcc11beb..e2b2533d2e 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -4,8 +4,8 @@
 """
 llama-server inference backend for GGUF models.
 
-Manages a llama-server subprocess and proxies chat completions
-through its OpenAI-compatible /v1/chat/completions endpoint.
+Manages a llama-server subprocess and proxies chat completions through
+its OpenAI-compatible /v1/chat/completions endpoint.
 """
 
 import atexit
@@ -60,16 +60,14 @@ logger = get_logger(__name__)
 
 
 # ── Pre-compiled patterns for plan-without-action re-prompt ──
-# Forward-looking intent signals that indicate the model is
-# describing what it *will* do rather than giving a final answer.
+# Forward-looking intent signals: the model is describing what it *will*
+# do rather than giving a final answer.
 _INTENT_SIGNAL = re.compile(
     r"(?i)("
-    # Direct intent: "I'll ...", "I will ...", "Let me ...", "I am going to ..."
-    # Handles both straight and curly apostrophes.
-    # Excludes "I can", "I should", "I want to", "let's" which
-    # appear frequently in direct answers / explanations.
-    # Negative lookahead drops negated forms ("I will not", "I'll never")
-    # so a refusal doesn't trigger a re-prompt.
+    # Direct intent ("I'll ...", "Let me ...", straight + curly apostrophes).
+    # Excludes "I can"/"I should"/"I want to"/"let's" (common in answers).
+    # Negative lookahead drops negated forms ("I will not") so a refusal
+    # doesn't trigger a re-prompt.
     r"\b(i['\u2019](ll|m going to|m gonna)|i am (going to|gonna)|i will|i shall|let me|allow me)\b(?!\s+(?:not|never)\b)"
     r"|"
     # Step/plan framing: "First ...", "Step 1:", "Here's my plan"
@@ -81,18 +79,17 @@ _INTENT_SIGNAL = re.compile(
 )
 _MAX_REPROMPTS = 3
 
-# Without max_tokens, llama-server defaults to n_predict = n_ctx (up to
+# Without max_tokens, llama-server defaults n_predict = n_ctx (up to
 # 262144 for Qwen3.5), producing many-minute zombie decodes when cancel
-# fails. t_max_predict_ms is a wall-clock backstop applied unconditionally,
-# but the llama.cpp README notes it ONLY fires after a newline has been
-# generated -- a model stuck in a long unbroken non-newline sequence is
-# unbounded by it. So we still want a token cap as the front-line limiter.
+# fails. t_max_predict_ms is an unconditional wall-clock backstop, but the
+# llama.cpp README notes it ONLY fires after a newline -- a model stuck in
+# a long non-newline sequence is unbounded by it. So we keep a token cap
+# as the front-line limiter.
 #
-# The cap is the model's effective context length when we know it,
-# falling back to a generous floor when metadata is unavailable. 4096 was
-# too low: Qwen3 / gpt-oss reasoning traces routinely exceed it, and any
-# OpenAI-API caller that omits max_tokens (langchain, llama-index, raw
-# curl) sees responses silently truncated mid-sentence.
+# The cap is the model's effective context length when known, else a
+# generous floor. 4096 was too low: Qwen3 / gpt-oss reasoning traces
+# exceed it, and any OpenAI-API caller omitting max_tokens (langchain,
+# llama-index, raw curl) sees responses truncated mid-sentence.
 _DEFAULT_MAX_TOKENS_FLOOR = 32768
 _DEFAULT_T_MAX_PREDICT_MS = 600_000  # 10 min
 _REPROMPT_MAX_CHARS = 2000
@@ -103,15 +100,14 @@ _SHARD_RE = re.compile(r"^(.*)-\d{5}-of-\d{5}\.gguf$")
 
 
 # ── Sliding-window-pattern resolver ───────────────────────────
-# Resolves the per-layer SWA mask when a GGUF reports a sliding window
-# but no `sliding_window_pattern` field. Tier order in
-# `_resolve_swa_pattern`: GGUF metadata, on-disk cache, bootstrap dict
-# below, transformers introspection, HF Hub config.json, legacy 1/4
-# fallback. Period N means layer i is SWA iff `(i + 1) % N != 0`,
-# matching transformers. Skipped on purpose: phi3 (no key/val length
-# in GGUF, window >= ctx anyway), qwen2 family (converter strips
-# sliding_window when use_sliding_window=False), mistral v0.1/v0.2
-# (all-SWA can't be expressed as a period).
+# Resolves the per-layer SWA mask when a GGUF reports a sliding window but
+# no `sliding_window_pattern` field. Tier order in `_resolve_swa_pattern`:
+# GGUF metadata, on-disk cache, bootstrap dict below, transformers
+# introspection, HF Hub config.json, legacy 1/4 fallback. Period N means
+# layer i is SWA iff `(i + 1) % N != 0`, matching transformers. Skipped on
+# purpose: phi3 (no key/val length in GGUF, window >= ctx anyway), qwen2
+# family (converter strips sliding_window when use_sliding_window=False),
+# mistral v0.1/v0.2 (all-SWA can't be a period).
 _BOOTSTRAP_SWA_DEFAULTS: dict[str, int] = {
     "gemma2": 2,  # Gemma2Config.sliding_window_pattern
     "gemma3": 6,  # Gemma3TextConfig.sliding_window_pattern
@@ -127,8 +123,8 @@ _SWA_CACHE_LOCK = threading.Lock()
 
 
 def _probe_dns_dead(host: str = "huggingface.co", timeout: float = 2.0) -> bool:
-    """Quick DNS check. Runs on a daemon thread so concurrent sockets
-    in the same process are not affected by socket.setdefaulttimeout."""
+    """Quick DNS check on a daemon thread, so concurrent sockets in the
+    same process aren't affected by socket.setdefaulttimeout."""
     result: list[Optional[bool]] = [None]
 
     def _probe() -> None:
@@ -141,16 +137,15 @@ def _probe_dns_dead(host: str = "huggingface.co", timeout: float = 2.0) -> bool:
     t = threading.Thread(target = _probe, daemon = True)
     t.start()
     t.join(timeout)
-    # Thread still running -> resolver wedged -> treat as dead.
+    # Thread still running -> resolver wedged -> dead.
     return True if result[0] is None else result[0]
 
 
 @contextlib.contextmanager
 def _hf_offline_if_dns_dead():
-    """Set HF_HUB_OFFLINE for the body of this block only when DNS to
-    huggingface.co fails. Restores the env on exit so a transient
-    resolver hiccup at the start of one load can't quarantine the whole
-    process. Respects an explicit user setting (no-op if already set)."""
+    """Set HF_HUB_OFFLINE for this block only when DNS to huggingface.co
+    fails. Restores the env on exit so a transient resolver hiccup can't
+    quarantine the whole process. No-op if the user already set it."""
     if "HF_HUB_OFFLINE" in os.environ:
         yield False
         return
@@ -205,8 +200,8 @@ def _save_swa_cache(cache: dict) -> None:
 
 
 def _period_from_layer_types(layer_types: list) -> Optional[int]:
-    """Smallest period N where `(i+1) % N != 0` matches the SWA mask,
-    or None if no fixed period fits."""
+    """Smallest period N where `(i+1) % N != 0` matches the SWA mask, or
+    None if no fixed period fits."""
     if not layer_types:
         return None
     is_swa = ["full" not in str(t).lower() for t in layer_types]
@@ -260,8 +255,8 @@ _SWA_PATTERN_SOURCE_RE = re.compile(r"sliding_window_pattern\s*(?::\s*[\w\[\], ]
 
 
 def _resolve_swa_entry_from_transformers(arch: str) -> Optional[object]:
-    """Default-instantiate the matching Config; on failure, regex-parse
-    its source for `sliding_window_pattern = N`."""
+    """Default-instantiate the matching Config; on failure, regex-parse its
+    source for `sliding_window_pattern = N`."""
     try:
         from transformers.models.auto.configuration_auto import (
             CONFIG_MAPPING,
@@ -348,7 +343,7 @@ def _resolve_swa_pattern(
         _persist(entry)
         return _entry_to_mask(entry)
 
-    # Tier 3: live HF fetch (with persistent caching of the result)
+    # Tier 3: live HF fetch (result persistently cached)
     if allow_network:
         for repo_id in source_repo_candidates:
             if not repo_id:
@@ -362,7 +357,7 @@ def _resolve_swa_pattern(
 
 
 def _hf_repo_from_url(url: Optional[str]) -> Optional[str]:
-    """Strip `https://huggingface.co/owner/name(/...)` to `owner/name`."""
+    """Strip `https://huggingface.co/owner/name(/...)` -> `owner/name`."""
     if not url or "huggingface.co/" not in url:
         return None
     tail = url.split("huggingface.co/", 1)[1].rstrip("/")
@@ -372,8 +367,8 @@ def _hf_repo_from_url(url: Optional[str]) -> Optional[str]:
     return f"{parts[0]}/{parts[1]}"
 
 
-# Model size extraction — lazy import to avoid pulling in transformers
-# at module level.  See PR description for the full explanation.
+# Lazy import to avoid pulling transformers in at module level.
+# See PR description for the full explanation.
 def _extract_model_size_b(model_id: str):
     from utils.models import extract_model_size_b
     return extract_model_size_b(model_id)
@@ -399,13 +394,12 @@ def detect_reasoning_flags(
 ) -> dict:
     """Classify a chat template's reasoning and tool-calling capabilities.
 
-    Returns a dict with the same five keys populated by the GGUF sniffer:
-    ``supports_reasoning``, ``reasoning_style``
-    (``"enable_thinking"`` | ``"reasoning_effort"``),
-    ``reasoning_always_on``, ``supports_preserve_thinking``, and
-    ``supports_tools``. Used by both the llama-server backend at load
-    time and the safetensors/transformers paths in ``routes/inference``
-    so the two agree on what the frontend will see.
+    Returns the same five keys as the GGUF sniffer: ``supports_reasoning``,
+    ``reasoning_style`` (``"enable_thinking"`` | ``"reasoning_effort"``),
+    ``reasoning_always_on``, ``supports_preserve_thinking``,
+    ``supports_tools``. Used by both the llama-server backend at load time
+    and the safetensors/transformers paths in ``routes/inference`` so they
+    agree on what the frontend sees.
     """
     flags = {
         "supports_reasoning": False,
@@ -424,28 +418,28 @@ def detect_reasoning_flags(
         flags["reasoning_style"] = "enable_thinking"
         logger.info(f"{prefix}model supports reasoning (enable_thinking)")
     elif "reasoning_effort" in tpl:
-        # gpt-oss / Harmony templates use reasoning_effort
-        # ("low" | "medium" | "high") instead of a boolean.
+        # gpt-oss / Harmony use reasoning_effort
+        # ("low" | "medium" | "high"), not a boolean.
         flags["supports_reasoning"] = True
         flags["reasoning_style"] = "reasoning_effort"
         logger.info(f"{prefix}model supports reasoning (reasoning_effort)")
     elif "thinking" in tpl:
-        # DeepSeek uses 'thinking' instead of 'enable_thinking'
+        # DeepSeek uses 'thinking', not 'enable_thinking'
         normalized_id = (model_identifier or "").lower()
         if "deepseek" in normalized_id:
             flags["supports_reasoning"] = True
             logger.info(f"{prefix}model supports reasoning (DeepSeek thinking)")
 
     # Hardcoded <think> tags or reasoning_content in the template mean
-    # thinking is always on (no toggle to disable it).
+    # thinking is always on (no toggle).
     if not flags["supports_reasoning"]:
         if ("<think>" in tpl and "</think>" in tpl) or "reasoning_content" in tpl:
             flags["supports_reasoning"] = True
             flags["reasoning_always_on"] = True
             logger.info(f"{prefix}model always reasons (<think> tags in template)")
 
-    # preserve_thinking is an independent kwarg on some Qwen templates
-    # that keeps historical <think> blocks in prior assistant turns.
+    # preserve_thinking: independent kwarg on some Qwen templates that
+    # keeps historical <think> blocks in prior assistant turns.
     if "preserve_thinking" in tpl:
         flags["supports_preserve_thinking"] = True
         logger.info(f"{prefix}model supports preserve_thinking")
@@ -466,9 +460,8 @@ def _is_mtp_model_name(model_identifier: Optional[str], gguf_path: Optional[str]
 
 
 def _extra_args_set_spec_type(extra_args: Optional[Iterable[str]]) -> bool:
-    """User passed --spec-type / --spec-default? llama-server takes a
-    single --spec-type (comma-separated to chain), so suppress
-    auto-emit when this is true."""
+    """User passed --spec-type / --spec-default? llama-server takes one
+    --spec-type (comma-separated to chain), so suppress auto-emit."""
     if not extra_args:
         return False
     for raw in extra_args:
@@ -490,11 +483,11 @@ def _build_ngram_mod_flags(
     """Emit the right ngram-mod knob flags for the running llama-server.
 
     Post-rename builds expose ``--spec-ngram-mod-n-{match,min,max}``;
-    pre-rename builds expose the legacy ``--spec-ngram-size-n`` /
+    pre-rename builds expose legacy ``--spec-ngram-size-n`` /
     ``--draft-min`` / ``--draft-max``. ``caps`` comes from
-    ``probe_server_capabilities``; ``ngram_mod_flavor`` tells us which
-    set is real (vs a removal-stub entry). Returns ``[]`` when neither
-    set is available so the caller can drop ngram-mod entirely.
+    ``probe_server_capabilities``; ``ngram_mod_flavor`` says which set is
+    real (vs a removal-stub). Returns ``[]`` when neither is available so
+    the caller can drop ngram-mod entirely.
     """
     flavor = caps.get("ngram_mod_flavor") if caps else None
     if flavor == "new":
@@ -507,9 +500,8 @@ def _build_ngram_mod_flags(
             str(n_max),
         ]
     if flavor == "legacy":
-        # Legacy llama.cpp before the spec arg rename: same knobs lived
-        # under --spec-ngram-size-n (lookup length) and the generic
-        # --draft-min / --draft-max (ngram size N range).
+        # Pre-rename llama.cpp: same knobs lived under --spec-ngram-size-n
+        # (lookup length) and generic --draft-min / --draft-max (N range).
         return [
             "--spec-ngram-size-n",
             str(n_match),
@@ -522,9 +514,9 @@ def _build_ngram_mod_flags(
 
 
 # Canonical Speculative Decoding modes exposed by the Studio chat UI.
-# The dropdown renders five options (auto, mtp, ngram, mtp+ngram, off);
-# the load API also accepts legacy values that the original Switch and
-# external callers emit (default, draft-mtp, ngram-mod, ngram-simple).
+# Dropdown renders five (auto, mtp, ngram, mtp+ngram, off); the load API
+# also accepts legacy values the original Switch and external callers emit
+# (default, draft-mtp, ngram-mod, ngram-simple).
 _CANONICAL_SPEC_MODES = {"auto", "mtp", "ngram", "mtp+ngram", "off", "ngram-simple"}
 _LEGACY_SPEC_MODE_MAP = {
     "default": "auto",
@@ -536,10 +528,10 @@ _LEGACY_SPEC_MODE_MAP = {
 def _canonicalize_spec_mode(value):
     """Map any accepted ``speculative_type`` input onto a canonical mode.
 
-    Returns one of ``auto``, ``mtp``, ``ngram``, ``mtp+ngram``, ``off``,
+    Returns ``auto``, ``mtp``, ``ngram``, ``mtp+ngram``, ``off``,
     ``ngram-simple``, or ``None`` (callers treat ``None`` as ``auto``).
-    Unknown strings collapse to ``auto`` so a stale UI value or typo
-    falls back to the safe platform-aware path.
+    Unknown strings collapse to ``auto`` so a stale UI value or typo falls
+    back to the safe platform-aware path.
     """
     if value is None:
         return None
@@ -552,7 +544,7 @@ def _canonicalize_spec_mode(value):
         return stripped
     if stripped in _LEGACY_SPEC_MODE_MAP:
         return _LEGACY_SPEC_MODE_MAP[stripped]
-    # llama.cpp comma-chains are emitted by old persisted state e.g.
+    # Old persisted state emits llama.cpp comma-chains e.g.
     # "ngram-mod,draft-mtp"; collapse the most common one explicitly.
     pieces = [p.strip() for p in stripped.split(",") if p.strip()]
     has_mtp = any(p in ("mtp", "draft-mtp") for p in pieces)
@@ -571,12 +563,11 @@ def _backfill_usage_from_timings(usage, timings):
     OpenAI-style usage block is missing or reports zero tokens.
 
     The Studio chat UI computes generation t/s from
-    ``meta.usage.completion_tokens / totalStreamTime``. llama-server
-    always populates ``timings.predicted_n`` (true decoded count) and
-    ``timings.prompt_n``, but the ``usage`` field on the final SSE chunk
-    can be absent or zero on some server builds / streaming
-    configurations, which makes the UI fall back to wall-clock t/s and
-    dilute speculative-decoding speedups.
+    ``meta.usage.completion_tokens / totalStreamTime``. llama-server always
+    populates ``timings.predicted_n`` (true decoded count) and
+    ``timings.prompt_n``, but the final SSE chunk's ``usage`` can be absent
+    or zero on some server builds / streaming configs, making the UI fall
+    back to wall-clock t/s and dilute speculative-decoding speedups.
     """
     if not timings:
         return usage
@@ -602,9 +593,9 @@ class LlamaCppBackend:
     Manages a llama-server subprocess for GGUF model inference.
 
     Lifecycle:
-        1. load_model()  — starts llama-server with the GGUF file
-        2. generate_chat_completion() — proxies to /v1/chat/completions, streams back
-        3. unload_model() — terminates llama-server subprocess
+        1. load_model() — start llama-server with the GGUF file
+        2. generate_chat_completion() — proxy to /v1/chat/completions, stream back
+        3. unload_model() — terminate the subprocess
     """
 
     def __init__(self):
@@ -631,14 +622,13 @@ class LlamaCppBackend:
         self._cache_type_kv: Optional[str] = None
         self._reasoning_default: bool = True
         self._speculative_type: Optional[str] = None
-        # Canonical UI-facing mode the user requested: one of
+        # Canonical UI-facing mode the user requested:
         # ``auto``/``mtp``/``ngram``/``mtp+ngram``/``off``/``ngram-simple``.
-        # Round-tripped through the status API so the dropdown reflects
-        # the picked mode rather than the resolved internal flag set
-        # (auto on a 27B MTP GGUF resolves to draft-mtp but the dropdown
-        # should still read "Auto").
+        # Round-tripped through the status API so the dropdown reflects the
+        # picked mode, not the resolved internal flag set (auto on a 27B MTP
+        # GGUF resolves to draft-mtp but the dropdown still reads "Auto").
         self._requested_spec_mode: Optional[str] = None
-        # User-supplied --spec-draft-n-max override (None = platform default).
+        # User --spec-draft-n-max override (None = platform default).
         self._spec_draft_n_max: Optional[int] = None
         # KV-cache estimation fields (populated by _read_gguf_metadata)
         self._n_layers: Optional[int] = None
@@ -658,17 +648,17 @@ class LlamaCppBackend:
         self._kv_value_length_swa: Optional[int] = None
         self._ssm_inner_size: Optional[int] = None
         self._ssm_state_size: Optional[int] = None
-        # Last N layers reuse KV from earlier layers and don't allocate
-        # their own cache (Gemma 3n / Gemma 4: <arch>.attention.shared_kv_layers).
+        # Last N layers reuse earlier layers' KV and don't allocate their own
+        # cache (Gemma 3n / Gemma 4: <arch>.attention.shared_kv_layers).
         self._shared_kv_layers: Optional[int] = None
         # MTP head count (llama.cpp #22673); >0 enables --spec-type draft-mtp.
         self._nextn_predict_layers: Optional[int] = None
         self._lock = threading.Lock()
-        # Wraps load_model() end-to-end so concurrent loads serialise
-        # and never coexist as two llama-server processes (#5401).
+        # Wraps load_model() end-to-end so concurrent loads serialise and
+        # never coexist as two llama-server processes (#5401).
         self._serial_load_lock = threading.Lock()
-        # Last extra_args / requested n_ctx, preserved across unload so
-        # the chat UI's /unload+/load Apply path can inherit them (#5401).
+        # Last extra_args / requested n_ctx, preserved across unload so the
+        # chat UI's /unload+/load Apply path can inherit them (#5401).
         # ``_extra_args_source`` records the (model_identifier, hf_variant)
         # the stored args came from so the route can refuse cross-model
         # inheritance.
@@ -725,8 +715,9 @@ class LlamaCppBackend:
 
     @property
     def extra_args(self) -> Optional[List[str]]:
-        """Extra llama-server flags from the last load. Copy; None = never
-        set, [] = explicitly cleared. Used by the route for inheritance."""
+        """Extra llama-server flags from the last load (a copy). None =
+        never set, [] = explicitly cleared. Used by the route for
+        inheritance."""
         return list(self._extra_args) if self._extra_args is not None else None
 
     @property
@@ -751,14 +742,12 @@ class LlamaCppBackend:
     def max_context_length(self) -> Optional[int]:
         """Return the largest context that fits on this hardware at load time.
 
-        This is the "safe zone" threshold the UI renders warnings
-        against. For a model whose weights fit on some GPU subset, it
-        is the binary-search cap from ``_fit_context_to_vram`` for that
-        subset. For a model whose weights exceed 90% of every GPU
-        subset, it is the 4096 fallback -- the spec's default when the
-        model will not fit. The UI slider ceiling is
-        ``native_context_length``; dragging above ``max_context_length``
-        triggers the "might be slower" warning.
+        The UI's "safe zone" warning threshold. If the weights fit on some
+        GPU subset, it's the binary-search cap from ``_fit_context_to_vram``
+        for that subset; if they exceed 90% of every subset, it's the 4096
+        fallback (the spec's default when the model won't fit). The UI
+        slider ceiling is ``native_context_length``; dragging above
+        ``max_context_length`` triggers the "might be slower" warning.
         """
         return self._max_context_length or self._context_length
 
@@ -770,17 +759,16 @@ class LlamaCppBackend:
     def load_progress(self) -> Optional[dict]:
         """Return live model-load progress, or None if not loading.
 
-        While llama-server is warming up, its process is typically in
-        kernel state D (disk sleep) mmap'ing the weight shards into
-        page cache before pushing layers to VRAM. During that window
-        ``/api/inference/status`` only reports ``loading``, which gives
-        the UI nothing to display besides a spinner that looks stuck
-        for minutes on large MoE models.
+        While llama-server warms up, its process is typically in kernel
+        state D (disk sleep) mmap'ing weight shards into page cache before
+        pushing layers to VRAM. During that window
+        ``/api/inference/status`` only reports ``loading``, so the UI has
+        nothing but a spinner that looks stuck for minutes on large MoEs.
 
-        This method samples ``/proc/<pid>/status VmRSS`` against the
-        sum of the GGUF shard sizes so the UI can render a real bar
-        and compute rate / ETA. Returns ``None`` when no load is in
-        flight (no process, or process already healthy).
+        Samples ``/proc/<pid>/status VmRSS`` against the sum of GGUF shard
+        sizes so the UI can render a real bar and compute rate / ETA.
+        Returns ``None`` when no load is in flight (no process, or already
+        healthy).
 
         Shape::
 
@@ -791,9 +779,8 @@ class LlamaCppBackend:
                 "fraction": float,     # bytes_loaded / bytes_total, 0..1
             }
 
-        Linux-only in the current implementation. On macOS/Windows the
-        equivalent would be a different API; this returns ``None`` on
-        platforms where ``/proc/<pid>/status`` is unavailable.
+        Linux-only for now; returns ``None`` where ``/proc/<pid>/status``
+        is unavailable (macOS/Windows would need a different API).
         """
         proc = self._process
         if proc is None:
@@ -802,7 +789,7 @@ class LlamaCppBackend:
         if pid is None:
             return None
 
-        # Sum up shard sizes (primary + any extras sitting alongside).
+        # Sum shard sizes (primary + any extras alongside).
         bytes_total = 0
         gguf_path = self._gguf_path
         if gguf_path:
@@ -812,8 +799,8 @@ class LlamaCppBackend:
                     bytes_total += primary.stat().st_size
             except OSError:
                 pass
-            # Extra shards live alongside the primary with the same prefix
-            # before the shard index (e.g. ``-00001-of-00004.gguf``).
+            # Extra shards share the primary's prefix before the shard
+            # index (e.g. ``-00001-of-00004.gguf``).
             try:
                 parent = primary.parent
                 stem = primary.name
@@ -834,7 +821,7 @@ class LlamaCppBackend:
             except OSError:
                 pass
 
-        # Read VmRSS from /proc/<pid>/status. Kilobytes on Linux.
+        # Read VmRSS from /proc/<pid>/status (kilobytes on Linux).
         bytes_loaded = 0
         try:
             with open(f"/proc/{pid}/status", "r", encoding = "utf-8") as f:
@@ -898,13 +885,13 @@ class LlamaCppBackend:
     ) -> Optional[dict]:
         """Build chat_template_kwargs from per-request reasoning fields.
 
-        Produces a merged dict covering the active model's reasoning style
-        (``enable_thinking`` or ``reasoning_effort``) plus the independent
-        ``preserve_thinking`` kwarg when the template supports it.
+        Merges the active model's reasoning style (``enable_thinking`` or
+        ``reasoning_effort``) plus the independent ``preserve_thinking``
+        kwarg when the template supports it.
         """
         kwargs: dict = {}
-        # Always-on reasoning models hardcode <think> tags in their template
-        # and do not consume enable_thinking / reasoning_effort -- skip.
+        # Always-on reasoning models hardcode <think> tags and don't consume
+        # enable_thinking / reasoning_effort -- skip.
         if self._supports_reasoning and not self._reasoning_always_on:
             if self._reasoning_style == "reasoning_effort":
                 if reasoning_effort in ("low", "medium", "high"):
@@ -937,8 +924,8 @@ class LlamaCppBackend:
 
     @property
     def spec_draft_n_max(self) -> Optional[int]:
-        """User --spec-draft-n-max override active on the load, or None
-        when the platform default (6 GPU / 3 CPU) is in effect."""
+        """User --spec-draft-n-max override active on the load, or None when
+        the platform default (6 GPU / 3 CPU) is in effect."""
         return self._spec_draft_n_max
 
     # ── Binary discovery ──────────────────────────────────────────
@@ -961,12 +948,12 @@ class LlamaCppBackend:
         """
         binary_name = "llama-server.exe" if sys.platform == "win32" else "llama-server"
 
-        # 1. Env var — direct path to binary
+        # 1. Env var: direct path to binary
         env_path = os.environ.get("LLAMA_SERVER_PATH")
         if env_path and Path(env_path).is_file():
             return env_path
 
-        # 1b. UNSLOTH_LLAMA_CPP_PATH — custom llama.cpp install directory
+        # 1b. UNSLOTH_LLAMA_CPP_PATH: custom llama.cpp install dir
         custom_llama_cpp = os.environ.get("UNSLOTH_LLAMA_CPP_PATH")
         if custom_llama_cpp:
             custom_dir = Path(custom_llama_cpp)
@@ -974,11 +961,11 @@ class LlamaCppBackend:
             root_bin = custom_dir / binary_name
             if root_bin.is_file():
                 return str(root_bin)
-            # build/bin/ (cmake builds on Linux)
+            # build/bin/ (cmake on Linux)
             cmake_bin = custom_dir / "build" / "bin" / binary_name
             if cmake_bin.is_file():
                 return str(cmake_bin)
-            # build/bin/Release/ (cmake builds on Windows)
+            # build/bin/Release/ (cmake on Windows)
             if sys.platform == "win32":
                 win_bin = custom_dir / "build" / "bin" / "Release" / binary_name
                 if win_bin.is_file():
@@ -999,10 +986,10 @@ class LlamaCppBackend:
             if _is_legacy:
                 search_roots = [legacy_llama]
             else:
-                # why: _kill_orphaned_servers excludes the legacy root in custom
-                # mode; discovery must match so we never spawn a server we then
-                # refuse to clean up. UNSLOTH_LLAMA_CPP_PATH (handled earlier)
-                # is the explicit way to share a build across roots.
+                # _kill_orphaned_servers excludes the legacy root in custom
+                # mode; discovery must match so we never spawn a server we
+                # then refuse to clean up. UNSLOTH_LLAMA_CPP_PATH (handled
+                # earlier) is the explicit way to share a build across roots.
                 search_roots = [_resolved_sr / "llama.cpp"]
         except (ImportError, OSError, ValueError):
             search_roots = [legacy_llama]
@@ -1025,7 +1012,7 @@ class LlamaCppBackend:
                 if home_win.is_file():
                     return str(home_win)
 
-        # 5–6. Legacy: in-tree build (older setup.sh / setup.ps1 versions)
+        # 5-6. Legacy: in-tree build (older setup.sh / setup.ps1)
         project_root = Path(__file__).resolve().parents[4]
         # Root dir (make builds)
         root_path = project_root / "llama.cpp" / binary_name
@@ -1063,17 +1050,17 @@ class LlamaCppBackend:
         {found, mtp_token, supports_mtp, ngram_mod_flavor,
         supports_ngram_mod, spec_draft_n_max_flag}.
 
-        ``ngram_mod_flavor`` is ``"new"`` when the binary exposes the
-        post-rename ``--spec-ngram-mod-n-match / -n-min / -n-max`` as
-        real args, ``"legacy"`` when only the pre-rename
-        ``--spec-ngram-size-n / --draft-min / --draft-max`` are real
-        (the rename ships with stub removal entries for the legacy
-        names; we tell stubs apart by the "argument has been removed"
-        description), or ``None`` if neither set is usable.
+        ``ngram_mod_flavor``: ``"new"`` when the post-rename
+        ``--spec-ngram-mod-n-match / -n-min / -n-max`` are real args;
+        ``"legacy"`` when only the pre-rename
+        ``--spec-ngram-size-n / --draft-min / --draft-max`` are real (the
+        rename ships stub removal entries for legacy names, told apart by
+        the "argument has been removed" description); ``None`` if neither
+        set is usable.
 
-        ``spec_draft_n_max_flag`` is the actual flag name the binary
-        accepts: ``--spec-draft-n-max`` on post-rename builds, or
-        ``--draft-max`` on legacy. ``None`` means n_max cannot be set.
+        ``spec_draft_n_max_flag``: the flag the binary accepts --
+        ``--spec-draft-n-max`` post-rename, ``--draft-max`` on legacy.
+        ``None`` means n_max cannot be set.
         """
         bin_path = binary or cls._find_llama_server_binary()
         if not bin_path or not Path(bin_path).is_file():
@@ -1106,9 +1093,9 @@ class LlamaCppBackend:
                 check = False,
             )
             help_text = (result.stdout or "") + "\n" + (result.stderr or "")
-            # Split into per-flag blocks: each --flag line plus its
-            # indented continuation lines, so the "argument has been
-            # removed" description sits with its flag.
+            # Split into per-flag blocks (each --flag line + its indented
+            # continuation), so the "argument has been removed" description
+            # sits with its flag.
             blocks: dict[str, str] = {}
             current_flags: list[str] = []
             current_desc: list[str] = []
@@ -1124,8 +1111,8 @@ class LlamaCppBackend:
                     current_desc = [stripped]
                     # Extract long-form flag tokens from the DECLARATION
                     # prefix only (comma-separated aliases). Stop at the
-                    # first token that isn't itself a flag, so flag
-                    # references inside descriptions are ignored.
+                    # first non-flag token so flag references inside
+                    # descriptions are ignored.
                     for tok in re.split(r"[,\s]+", stripped):
                         if tok.startswith("--") and re.match(r"--[A-Za-z][A-Za-z0-9_-]*$", tok):
                             current_flags.append(tok)
@@ -1149,7 +1136,7 @@ class LlamaCppBackend:
                     return False
                 return "argument has been removed" not in desc
 
-            # MTP token detection from --spec-type line.
+            # MTP token from the --spec-type line.
             spec_line = ""
             for line in help_text.splitlines():
                 if "--spec-type" in line:
@@ -1161,9 +1148,9 @@ class LlamaCppBackend:
             elif re.search(r"[|,\[]mtp[|,\]]", spec_line):
                 mtp_token = "mtp"
 
-            # ngram-mod flag flavor. Post-rename builds advertise both
-            # the new args (real) and the legacy ones (stubs); pre-rename
-            # builds only have the legacy ones as real.
+            # ngram-mod flag flavor. Post-rename builds advertise both new
+            # args (real) and legacy ones (stubs); pre-rename builds only
+            # have legacy ones as real.
             new_ngram_real = (
                 _is_real("--spec-ngram-mod-n-match")
                 and _is_real("--spec-ngram-mod-n-min")
@@ -1202,11 +1189,11 @@ class LlamaCppBackend:
 
     @staticmethod
     def _get_gguf_size_bytes(model_path: str) -> int:
-        """Get total GGUF size in bytes, including split shards."""
+        """Total GGUF size in bytes, including split shards."""
         main = Path(model_path)
         total = main.stat().st_size
 
-        # Check for split shards (e.g., model-00001-of-00003.gguf)
+        # Check for split shards (e.g. model-00001-of-00003.gguf)
         m = _SHARD_FULL_RE.match(main.name)
         if m:
             prefix, _, num_total = m.group(1), m.group(2), m.group(3)
@@ -1222,9 +1209,10 @@ class LlamaCppBackend:
     @staticmethod
     def _amd_apu_wants_unified_memory() -> bool:
         """True only for AMD unified-memory APUs (gfx1150/gfx1151), where
-        GGML_CUDA_ENABLE_UNIFIED_MEMORY lets llama.cpp use shared system RAM.
-        False for discrete AMD, NVIDIA, CPU and macOS (the env hurts discrete
-        GPUs). ROCm reuses torch.cuda.*; the gcnArchName suffix is stripped."""
+        GGML_CUDA_ENABLE_UNIFIED_MEMORY lets llama.cpp use shared system
+        RAM. False for discrete AMD, NVIDIA, CPU and macOS (the env hurts
+        discrete GPUs). ROCm reuses torch.cuda.*; gcnArchName suffix is
+        stripped."""
         try:
             import torch
 
@@ -1250,15 +1238,14 @@ class LlamaCppBackend:
         Order:
           1. ``nvidia-smi`` (NVIDIA CUDA hosts) -- respects
              ``CUDA_VISIBLE_DEVICES``.
-          2. ``torch.cuda.mem_get_info`` -- universal fallback that
-             works on AMD ROCm too because the HIP runtime
-             reuses the entire ``torch.cuda.*`` namespace. Covers the
-             AMD case for issue #5106 (nvidia-smi-only probe silently
-             returned [] on AMD hosts) and also rescues NVIDIA hosts
-             where ``nvidia-smi`` is missing from PATH.
+          2. ``torch.cuda.mem_get_info`` -- universal fallback that works
+             on AMD ROCm too (HIP runtime reuses the ``torch.cuda.*``
+             namespace). Covers the AMD case for issue #5106 (nvidia-smi
+             probe returned [] on AMD) and NVIDIA hosts missing
+             ``nvidia-smi`` from PATH.
 
-        Returns list of (gpu_index, free_mib) sorted by index. Empty
-        list if no supported GPU is reachable.
+        Returns list of (gpu_index, free_mib) sorted by index; empty if no
+        supported GPU is reachable.
         """
         # ── NVIDIA via nvidia-smi ────────────────────────────────────
         try:
@@ -1280,10 +1267,10 @@ class LlamaCppBackend:
                 if cvd is not None:
                     try:
                         # `if x.strip()` filters trailing-comma masks like
-                        # "0,1," which would otherwise raise ValueError on
-                        # an empty token. An explicitly empty mask (CVD="")
-                        # yields an empty `allowed` set so all GPUs are
-                        # filtered out, matching the codebase convention.
+                        # "0,1," that would raise ValueError on an empty
+                        # token. An empty mask (CVD="") yields an empty
+                        # `allowed` set so all GPUs are filtered out, per
+                        # the codebase convention.
                         allowed = set(int(x.strip()) for x in cvd.split(",") if x.strip())
                     except ValueError:
                         pass
@@ -1296,9 +1283,8 @@ class LlamaCppBackend:
                         if allowed is not None and idx not in allowed:
                             continue
                         gpus.append((idx, free_mib))
-                # Match the docstring's sort-by-id guarantee. nvidia-smi
-                # almost always returns sorted output, but driver order
-                # is not formally guaranteed.
+                # Match the docstring's sort-by-id guarantee; nvidia-smi
+                # output is usually sorted but driver order isn't guaranteed.
                 gpus.sort(key = lambda g: g[0])
                 if gpus:
                     return gpus
@@ -1313,20 +1299,18 @@ class LlamaCppBackend:
                 return []
             if not hasattr(torch.cuda, "mem_get_info"):
                 return []
-            # torch.cuda enumerates GPUs RELATIVE to the visibility mask.
-            # On NVIDIA builds the mask is CUDA_VISIBLE_DEVICES; on AMD
-            # ROCm builds it is HIP_VISIBLE_DEVICES (or ROCR_VISIBLE_DEVICES
-            # if HIP is unset). Downstream we feed these IDs back into the
-            # llama-server subprocess as CVD, so we must translate visible
-            # ordinals back to physical indices first; otherwise launching
-            # with ``CUDA_VISIBLE_DEVICES=2,3`` would get rewritten to
-            # ``CUDA_VISIBLE_DEVICES=0,1`` and target the wrong GPUs.
+            # torch.cuda enumerates GPUs RELATIVE to the visibility mask
+            # (CUDA_VISIBLE_DEVICES on NVIDIA; HIP_VISIBLE_DEVICES, or
+            # ROCR_VISIBLE_DEVICES if HIP unset, on AMD ROCm). We feed
+            # these IDs back into the subprocess as CVD, so visible
+            # ordinals must be translated to physical indices first;
+            # otherwise ``CUDA_VISIBLE_DEVICES=2,3`` gets rewritten to
+            # ``0,1`` and targets the wrong GPUs.
             physical_ids: Optional[list[int]] = None
-            # Match the codebase convention in
-            # ``utils/hardware/hardware.py::_get_parent_visible_gpu_spec``:
-            # treat an explicitly empty mask (``HIP_VISIBLE_DEVICES=""``)
-            # as "set to no GPUs" rather than falling through to the next
-            # var. ``or`` would coerce empty string to falsy and silently
+            # Match ``utils/hardware/hardware.py::
+            # _get_parent_visible_gpu_spec``: treat an empty mask
+            # (``HIP_VISIBLE_DEVICES=""``) as "no GPUs" rather than falling
+            # through to the next var. ``or`` would coerce "" to falsy and
             # promote the wrong source.
             if getattr(torch.version, "hip", None) is not None:
                 hip_v = os.environ.get("HIP_VISIBLE_DEVICES")
@@ -1342,9 +1326,9 @@ class LlamaCppBackend:
                 cvd = os.environ.get("CUDA_VISIBLE_DEVICES")
             if cvd is not None:
                 try:
-                    # Empty mask (CVD="") yields an empty list so the
-                    # below loop produces no GPUs, consistent with the
-                    # nvidia-smi path and utils/hardware/hardware.py.
+                    # Empty mask (CVD="") yields an empty list so the loop
+                    # produces no GPUs, consistent with the nvidia-smi path
+                    # and utils/hardware/hardware.py.
                     physical_ids = [int(x.strip()) for x in cvd.split(",") if x.strip()]
                 except ValueError:
                     physical_ids = None
@@ -1363,8 +1347,8 @@ class LlamaCppBackend:
             logger.debug(f"torch GPU probe failed: {e}")
             return []
 
-    # Skip the wait when the last kill is older than this; the GPU
-    # driver has already reclaimed the prior process's allocations.
+    # Skip the wait when the last kill is older than this; the driver has
+    # already reclaimed the prior process's allocations.
     _VRAM_SETTLE_WINDOW_S: float = 15.0
 
     @staticmethod
@@ -1376,18 +1360,17 @@ class LlamaCppBackend:
     ) -> None:
         """Poll ``_get_gpu_free_memory`` until free VRAM stabilises.
 
-        The GPU driver reclaims a dead process's allocations
-        asynchronously, so sampling free memory in the kill-to-spawn
-        window reads artificially low and pushes ``_select_gpus`` /
-        ``_fit_context_to_vram`` toward needless CPU offload -- on a
-        tight VRAM card this is the Apply-reload OOM that bare-shell
-        launches with the same flags never see.
+        The driver reclaims a dead process's allocations asynchronously, so
+        sampling free memory in the kill-to-spawn window reads artificially
+        low and pushes ``_select_gpus`` / ``_fit_context_to_vram`` toward
+        needless CPU offload -- on a tight VRAM card, the Apply-reload OOM
+        that bare-shell launches with the same flags never see.
 
-        Short-circuits on cold start (``since_kill`` zero) or stale
-        kill (older than ``_VRAM_SETTLE_WINDOW_S``); also on CPU-only
-        hosts (empty probe), probe exceptions, and GPU-set changes.
-        ``max_wait`` is a wall-clock bound that includes probe time,
-        so a wedged ``nvidia-smi`` cannot extend the reload.
+        Short-circuits on cold start (``since_kill`` zero), stale kill
+        (older than ``_VRAM_SETTLE_WINDOW_S``), CPU-only hosts (empty
+        probe), probe exceptions, and GPU-set changes. ``max_wait`` is a
+        wall-clock bound including probe time, so a wedged ``nvidia-smi``
+        cannot extend the reload.
         """
         now = time.monotonic()
         if since_kill <= 0.0:
@@ -1423,8 +1406,8 @@ class LlamaCppBackend:
                     stable = False
                     break
                 prev_free = prev_map[idx]
-                # Adaptive: 2 % of the larger sample dominates the
-                # 256 MiB floor on large-VRAM cards.
+                # Adaptive: 2% of the larger sample dominates the 256 MiB
+                # floor on large-VRAM cards.
                 per_gpu_tol = max(tolerance_mib, int(max(free, prev_free) * 0.02))
                 if abs(free - prev_free) >= per_gpu_tol:
                     stable = False
@@ -1433,11 +1416,10 @@ class LlamaCppBackend:
                 return
             prev = curr
 
-    # Free-VRAM fraction at which Studio pins the GPU directly instead
-    # of deferring to ``--fit on``. 5% headroom covers CUDA context +
-    # compute buffers; 0.90 was too conservative and dropped 91-94%
-    # fits to CPU offload (#5106). The fork's --fit on still catches
-    # the truly-too-large case.
+    # Free-VRAM fraction at which Studio pins the GPU directly instead of
+    # deferring to ``--fit on``. 5% headroom covers CUDA context + compute
+    # buffers; 0.90 was too conservative, dropping 91-94% fits to CPU
+    # offload (#5106). --fit on still catches the truly-too-large case.
     _GPU_PIN_VRAM_FRACTION = 0.95
 
     @staticmethod
@@ -1445,28 +1427,25 @@ class LlamaCppBackend:
         """Return DLL dirs from pip-installed CUDA wheels under
         ``<prefix>/Lib/site-packages/`` so llama-server.exe can load
         ``cudart64_X.dll`` / ``cublas64_X.dll`` without a system CUDA
-        toolkit. Mirrors the Linux ``nvidia/cu*/lib`` LD_LIBRARY_PATH
-        block, with parity for the Windows-specific wheel layouts seen
-        in the wild. Covered patterns:
+        toolkit. Mirrors the Linux ``nvidia/cu*/lib`` LD_LIBRARY_PATH block,
+        with parity for the Windows wheel layouts seen in the wild:
           * ``nvidia/<pkg>/bin`` -- legacy modular wheels
             (``nvidia-cuda-runtime-cu12``, ``nvidia-cublas-cu12``, etc.).
           * ``nvidia/<pkg>/bin/x86_64`` and ``.../bin/x64`` -- current
-            CUDA 13 wheel layout used by the unsuffixed
-            ``nvidia-cuda-runtime`` / ``nvidia-cublas`` packages, which
-            ship under ``nvidia/cu13/bin/x86_64/`` (#5106).
-          * ``nvidia/<pkg>/Library/bin`` (and arch subdirs) -- conda-
-            style wheel repacks.
-          * ``torch/lib`` -- PyTorch's own CUDA-bundled Windows wheel,
-            which can ship ``cudart64_*.dll`` directly here instead of
-            as separate ``nvidia-*`` wheels. The install-side helper
-            ``python_runtime_dirs`` in ``install_llama_prebuilt.py``
-            covers this path for the same reason.
+            CUDA 13 layout for the unsuffixed ``nvidia-cuda-runtime`` /
+            ``nvidia-cublas`` packages (under ``nvidia/cu13/bin/x86_64/``)
+            (#5106).
+          * ``nvidia/<pkg>/Library/bin`` (and arch subdirs) -- conda-style
+            wheel repacks.
+          * ``torch/lib`` -- PyTorch's CUDA-bundled Windows wheel can ship
+            ``cudart64_*.dll`` here instead of as separate ``nvidia-*``
+            wheels. The install-side ``python_runtime_dirs`` in
+            ``install_llama_prebuilt.py`` covers this for the same reason.
 
-        Walks the tree with ``Path.iterdir`` rather than ``glob.glob``
-        so the resolver is safe against Windows paths containing
-        ``[`` or ``]`` (valid in usernames; would otherwise be
-        interpreted as a glob character class and silently miss
-        existing dirs)."""
+        Walks the tree with ``Path.iterdir`` rather than ``glob.glob`` so
+        it's safe against Windows paths containing ``[`` or ``]`` (valid in
+        usernames; otherwise read as a glob character class, silently
+        missing existing dirs)."""
         site_packages = Path(prefix) / "Lib" / "site-packages"
         out: list[str] = []
         seen: set[str] = set()
@@ -1485,9 +1464,8 @@ class LlamaCppBackend:
             for pkg_dir in nvidia_root.iterdir():
                 if not pkg_dir.is_dir():
                     continue
-                # Order matters for PATH search: arch-specific subdirs
-                # first so the explicit cudart64_X.dll location wins
-                # over a sibling ``bin`` that might be empty.
+                # Order matters: arch-specific subdirs first so the explicit
+                # cudart64_X.dll location wins over an empty sibling ``bin``.
                 for sub in (
                     pkg_dir / "bin" / "x86_64",
                     pkg_dir / "bin" / "x64",
@@ -1505,7 +1483,7 @@ class LlamaCppBackend:
         """Ordered PATH entries the win32 branch of start_llama_server
         prepends so llama-server.exe resolves cudart / cublas DLLs:
         binary_dir, pip nvidia wheels, CUDA_PATH/bin, CUDA_PATH/bin/x64.
-        Extracted so test_windows_gpu_detection_mock asserts against
+        Extracted so test_windows_gpu_detection_mock asserts against the
         production logic, not a hand-copy. #5106."""
         path_dirs = [binary_dir]
         path_dirs.extend(LlamaCppBackend._windows_pip_nvidia_dll_dirs(prefix))
@@ -1522,16 +1500,16 @@ class LlamaCppBackend:
     def _select_gpus(
         model_size_bytes: int, gpus: list[tuple[int, int]]
     ) -> tuple[Optional[list[int]], bool]:
-        """Pick GPU(s) for a model based on estimated VRAM and free memory.
+        """Pick GPU(s) for a model from estimated VRAM and free memory.
 
-        ``model_size_bytes`` should include both model weights and estimated
-        KV cache.  The ``_GPU_PIN_VRAM_FRACTION`` threshold provides headroom
-        for compute buffers, CUDA context, and other runtime overhead.
+        ``model_size_bytes`` should include weights and estimated KV cache.
+        ``_GPU_PIN_VRAM_FRACTION`` provides headroom for compute buffers,
+        CUDA context, and other runtime overhead.
 
         Returns (gpu_indices, use_fit):
-          - ([1], False)       model fits on 1 GPU at the headroom threshold
-          - ([1, 2], False)    model needs 2 GPUs
-          - (None, True)       model too large, let --fit handle it
+          - ([1], False)       fits on 1 GPU at the headroom threshold
+          - ([1, 2], False)    needs 2 GPUs
+          - (None, True)       too large, let --fit handle it
         """
         if not gpus:
             return None, True
@@ -1542,11 +1520,11 @@ class LlamaCppBackend:
         # Sort GPUs by free memory descending
         ranked = sorted(gpus, key = lambda g: g[1], reverse = True)
 
-        # Try fitting on 1 GPU at the usable-VRAM threshold.
+        # Try 1 GPU at the usable-VRAM threshold.
         if ranked[0][1] * usable_fraction >= model_size_mib:
             return [ranked[0][0]], False
 
-        # Try fitting on N GPUs (accumulate free memory from most-free)
+        # Try N GPUs (accumulate free memory from most-free)
         cumulative = 0
         selected = []
         for idx, free_mib in ranked:
@@ -1555,7 +1533,7 @@ class LlamaCppBackend:
             if cumulative >= model_size_mib:
                 return sorted(selected), False
 
-        # Model is too large even for all GPUs, let --fit handle it
+        # Too large even for all GPUs; let --fit handle it
         logger.debug(
             "Model does not fit in available GPU memory, falling back to --fit",
             model_size_mib = round(model_size_mib, 2),
@@ -1569,10 +1547,10 @@ class LlamaCppBackend:
         """True if we have enough GGUF metadata to estimate KV cache size."""
         if self._n_layers is None:
             return False
-        # MLA: kv_lora_rank is sufficient (K-only cache)
+        # MLA: kv_lora_rank suffices (K-only cache)
         if self._kv_lora_rank is not None:
             return True
-        # New-style: need both explicit key AND value dimensions
+        # New-style: need explicit key AND value dimensions
         if self._kv_key_length is not None and self._kv_value_length is not None:
             return True
         # Legacy: need embedding_length + a head count (scalar or per-layer).
@@ -1599,7 +1577,7 @@ class LlamaCppBackend:
     ) -> int:
         """Estimate KV cache VRAM for a given context length.
 
-        Uses 5-path architecture-aware estimation:
+        5-path architecture-aware estimation:
           1. MLA      -- compressed KV latent + RoPE, K-only (no separate V)
           2. Hybrid   -- only attention layers need KV (Mamba layers don't)
           3. SWA      -- sliding-window layers cache min(ctx, window) tokens
@@ -1609,29 +1587,28 @@ class LlamaCppBackend:
         Server-flag knobs (mirror llama-server's CLI):
           swa_full        -- ``--swa-full``: force SWA layers to cache the
                              full ``n_ctx`` (collapses path 3 to path 4
-                             sizing for the SWA layers).
-          n_parallel      -- ``--parallel``: number of server slots.
-                             Verified empirically against llama-server:
-                             non-SWA layers stay constant (cells split
-                             across slots), SWA layers scale linearly
-                             (per-slot window).
-          kv_unified      -- ``--kv-unified`` (default on): retained for
-                             API forward-compat. Currently a no-op for
-                             memory math because the unified buffer total
-                             matches per-slot buffers in measured cases.
-          ctx_checkpoints -- ``--ctx-checkpoints``: SWA snapshot count per
-                             slot (PR #15293). Each snapshot stores one
-                             sliding-window of state per SWA layer.
+                             for SWA layers).
+          n_parallel      -- ``--parallel``: server slots. Verified against
+                             llama-server: non-SWA layers stay constant
+                             (cells split across slots), SWA layers scale
+                             linearly (per-slot window).
+          kv_unified      -- ``--kv-unified`` (default on): kept for API
+                             forward-compat. A no-op for memory math; the
+                             unified buffer total matches per-slot buffers
+                             in measured cases.
+          ctx_checkpoints -- ``--ctx-checkpoints``: SWA snapshots per slot
+                             (PR #15293). Each stores one sliding-window of
+                             state per SWA layer.
 
-        Returns 0 if metadata is insufficient for estimation.
+        Returns 0 if metadata is insufficient.
         """
         if not self._can_estimate_kv() or n_ctx <= 0:
             return 0
 
         n_layers = self._n_layers  # type: ignore[assignment]
-        # Gemma 3n / Gemma 4 reuse KV from earlier layers in the last
-        # ``shared_kv_layers`` blocks -- those don't allocate their own
-        # cache.  Floor at 1 so a misconfigured GGUF can't zero out KV.
+        # Gemma 3n / Gemma 4 reuse earlier layers' KV in the last
+        # ``shared_kv_layers`` blocks -- those allocate no cache. Floor at 1
+        # so a misconfigured GGUF can't zero out KV.
         shared = self._shared_kv_layers or 0
         n_layers_kv = max(1, n_layers - shared)
         n_kv = self._n_kv_heads or self._n_heads or 1  # type: ignore[assignment]
@@ -1652,11 +1629,11 @@ class LlamaCppBackend:
         slots = max(1, n_parallel)
 
         # Path 1: MLA (DeepSeek-V2/V3, GLM-4.7, GLM-5, Kimi-K2.5)
-        # MLA stores one compressed KV latent per token/layer (shared across heads).
-        # V is reconstructed from the latent on the fly -- no separate V cache.
-        # key_length = kv_lora_rank + rope_dim (the full compressed representation).
+        # Stores one compressed KV latent per token/layer (shared across
+        # heads); V is reconstructed from the latent, no separate V cache.
+        # key_length = kv_lora_rank + rope_dim (full compressed rep).
         # MLA GGUFs set head_count_kv=1; default to 1 if absent to avoid
-        # falling back to n_heads (e.g., 128 for DeepSeek-V3) which would 128x.
+        # falling back to n_heads (e.g. 128 for DeepSeek-V3) which 128x's.
         if self._kv_lora_rank is not None:
             n_kv_mla = self._n_kv_heads or 1
             rope_dim = self._key_length_mla or 64
@@ -1667,7 +1644,7 @@ class LlamaCppBackend:
         val_len = self._kv_value_length
 
         # Path 2: Hybrid Mamba/Attention (Qwen3.5-27B, Qwen3.5-35B-A3B)
-        # Only 1 in N layers is attention; the rest are Mamba (no KV cache).
+        # Only 1 in N layers is attention; rest are Mamba (no KV cache).
         if self._ssm_inner_size is not None and self._full_attention_interval is not None:
             fai = self._full_attention_interval
             n_attn = -(-n_layers // fai) if fai > 0 else n_layers  # ceiling division
@@ -1677,16 +1654,16 @@ class LlamaCppBackend:
             return int(n_attn * n_ctx * n_kv * 2 * head_dim * bpe)
 
         # Path 3: Sliding window (Gemma 2/3/3n/4, gpt-oss, Cohere2 ...).
-        # Pattern is filled in by the resolver at parse time; if absent,
-        # falls through to the legacy 1/4-global heuristic below.
-        # Per-layer-type ``--parallel N`` accounting (verified empirically
-        # against ``llama-server``):
+        # Pattern filled in by the resolver at parse time; if absent, falls
+        # through to the legacy 1/4-global heuristic below.
+        # Per-layer-type ``--parallel N`` accounting (verified against
+        # ``llama-server``):
         #   * non-SWA layers:    total cells = n_ctx, partitioned across
         #                         slots -> total memory CONSTANT in slots.
         #   * SWA layers:         per-slot cells = 2 * sliding_window
-        #                         (capped at n_ctx and at per_slot_ctx
-        #                         when ctx is split among many slots) ->
-        #                         total memory grows LINEARLY in slots.
+        #                         (capped at n_ctx and at per_slot_ctx when
+        #                         ctx is split among slots) -> total memory
+        #                         grows LINEARLY in slots.
         # ``--swa-full`` forces full n_ctx for SWA layers instead.
         # ``--ctx-checkpoints N`` adds N snapshots per SWA layer per slot.
         if (
@@ -1697,11 +1674,11 @@ class LlamaCppBackend:
         ):
             swa = self._sliding_window
             per_slot_ctx = max(1, n_ctx // slots)
-            # ``--swa-full`` makes SWA layers cache the full context just
-            # like non-SWA: cells get partitioned across slots, so per-slot
-            # cells = per_slot_ctx and the slots*per-slot product collapses
-            # back to the constant ``n_ctx`` total.  Otherwise SWA caches
-            # 2*sliding_window per slot, clamped at the per-slot ctx.
+            # ``--swa-full`` makes SWA layers cache the full context like
+            # non-SWA: cells partitioned across slots, so per-slot cells =
+            # per_slot_ctx and slots*per-slot collapses to the constant
+            # ``n_ctx`` total. Otherwise SWA caches 2*sliding_window per
+            # slot, clamped at the per-slot ctx.
             swa_cells_per_slot = per_slot_ctx if swa_full else min(n_ctx, 2 * swa, per_slot_ctx)
             key_len_swa = self._kv_key_length_swa or key_len
             val_len_swa = self._kv_value_length_swa or val_len
@@ -1709,8 +1686,8 @@ class LlamaCppBackend:
                 global_bytes = 0.0  # constant across slots
                 swa_bytes_per_slot = 0.0  # multiplied by slots
                 checkpoint_extra_per_slot = 0.0
-                # Iterate only over layers that allocate their own KV;
-                # the trailing ``shared`` layers reuse earlier caches.
+                # Only layers that allocate their own KV; trailing ``shared``
+                # layers reuse earlier caches.
                 for layer_idx in range(n_layers_kv):
                     layer_n_kv = self._kv_heads_for_layer(layer_idx, n_kv)
                     is_swa = (
@@ -1770,22 +1747,21 @@ class LlamaCppBackend:
     ) -> int:
         """Return the largest context length that fits in GPU VRAM.
 
-        Uses 90% of available VRAM as the ctx-fit budget. Tighter than
-        ``_GPU_PIN_VRAM_FRACTION`` on purpose: over-promising context
-        OOMs at runtime, while pinning conservatively just defers to
-        --fit on. If the weights alone don't fit, returns
-        ``requested_ctx`` unchanged.
+        Uses 90% of available VRAM as the ctx-fit budget -- tighter than
+        ``_GPU_PIN_VRAM_FRACTION`` on purpose: over-promising context OOMs
+        at runtime, while pinning conservatively just defers to --fit on. If
+        the weights alone don't fit, returns ``requested_ctx`` unchanged.
 
-        ``kv_on_gpu`` mirrors ``--kv-offload`` (default on). When False
-        the KV cache lives in CPU RAM and doesn't compete with weights
-        for VRAM; the requested context is honored verbatim. The other
-        keyword args mirror ``_estimate_kv_cache_bytes``.
+        ``kv_on_gpu`` mirrors ``--kv-offload`` (default on). When False the
+        KV cache lives in CPU RAM and doesn't compete with weights for VRAM;
+        the requested context is honored verbatim. Other keyword args mirror
+        ``_estimate_kv_cache_bytes``.
 
-        ``mtp_engaged`` reserves extra VRAM for the MTP draft model's
-        KV cache + compute graph buffers. llama.cpp's MTP path keeps a
+        ``mtp_engaged`` reserves extra VRAM for the MTP draft model's KV
+        cache + compute graph buffers. llama.cpp's MTP path keeps a
         secondary cache sized off the target's KV; on tight VRAM tiers
-        (e.g. 32 GB) auto-fit at native context would otherwise spill
-        and force llama-server into a slower partial-offload path.
+        (e.g. 32 GB) auto-fit at native context would otherwise spill and
+        force a slower partial-offload path.
         """
         if not self._can_estimate_kv():
             logger.debug(
@@ -1811,13 +1787,13 @@ class LlamaCppBackend:
         budget_bytes = available_mib * 1024 * 1024 * budget_frac
         model_footprint = model_size_bytes
 
-        # Check if requested context already fits
+        # Already fits?
         kv = self._estimate_kv_cache_bytes(requested_ctx, cache_type_kv, **kv_kwargs)
         if model_footprint + kv <= budget_bytes:
             return requested_ctx
 
-        # Model weights alone exceed budget -- can't help by reducing ctx.
-        # Return requested_ctx unchanged; --fit will handle VRAM management.
+        # Weights alone exceed budget -- reducing ctx can't help. Return
+        # requested_ctx unchanged; --fit will handle VRAM management.
         if model_footprint >= budget_bytes:
             logger.debug(
                 "Model footprint exceeds GPU budget before KV cache",
@@ -1841,7 +1817,7 @@ class LlamaCppBackend:
             else:
                 hi = mid - 1
 
-        # Round down to nearest 256 for alignment, but never exceed requested_ctx
+        # Round down to nearest 256 for alignment, never above requested_ctx
         best = (best // 256) * 256
         best = max(effective_min, best)
         best = min(best, requested_ctx)
@@ -1857,10 +1833,10 @@ class LlamaCppBackend:
     ) -> Optional[tuple[str, int]]:
         """Find the smallest GGUF variant (including all shards) that fits.
 
-        Groups split shards by variant prefix and sums their sizes.
-        For example, UD-Q4_K_XL with 9 shards of 50 GB each = 450 GB total.
+        Groups split shards by variant prefix and sums their sizes (e.g.
+        UD-Q4_K_XL with 9 shards of 50 GB each = 450 GB total).
 
-        Returns (first_shard_filename, total_size_bytes) or None if nothing fits.
+        Returns (first_shard_filename, total_size_bytes) or None.
         """
         try:
             from huggingface_hub import get_paths_info, list_repo_files
@@ -1870,11 +1846,11 @@ class LlamaCppBackend:
             if not gguf_files:
                 return None
 
-            # Get sizes for all GGUF files
+            # Sizes for all GGUF files
             path_infos = list(get_paths_info(hf_repo, gguf_files, token = hf_token))
             size_map = {p.path: (p.size or 0) for p in path_infos}
 
-            # Group files by variant: shards share a prefix before -NNNNN-of-NNNNN
+            # Group by variant: shards share a prefix before -NNNNN-of-NNNNN
             variants: dict[str, list[str]] = {}
             for f in gguf_files:
                 m = _SHARD_RE.match(f)
@@ -1888,7 +1864,7 @@ class LlamaCppBackend:
                 first = sorted(shard_files)[0]
                 variant_sizes.append((first, total, shard_files))
 
-            # Sort by total size ascending and pick the smallest that fits
+            # Smallest that fits
             variant_sizes.sort(key = lambda x: x[1])
             for first_file, total_size, _ in variant_sizes:
                 if total_size > 0 and total_size <= free_bytes:
@@ -1911,16 +1887,15 @@ class LlamaCppBackend:
 
     def _drain_stdout(self):
         """
-        Read lines from the subprocess stdout in a background thread.
+        Read subprocess stdout lines in a background thread.
 
-        This prevents a pipe-buffer deadlock on Windows where the default
-        pipe buffer is only ~4 KB.  Without draining, llama-server blocks
-        on writes and never becomes healthy.
+        Prevents a pipe-buffer deadlock on Windows (default buffer ~4 KB):
+        without draining, llama-server blocks on writes and never becomes
+        healthy.
 
-        Each line is also teed to ``self._llama_log_fh`` when set so a
-        post-mortem (especially in CI) has the full subprocess output
-        even if the crash predates the drain-thread join in
-        ``_wait_for_health``.
+        Each line is also teed to ``self._llama_log_fh`` when set, so a
+        post-mortem (especially in CI) has the full output even if the crash
+        predates the drain-thread join in ``_wait_for_health``.
         """
         try:
             for line in self._process.stdout:
@@ -1937,7 +1912,7 @@ class LlamaCppBackend:
                             # Log file closed under us; tee silently.
                             pass
         except (ValueError, OSError):
-            # Pipe closed — process is terminating
+            # Pipe closed -- process terminating
             pass
 
     # GGUF KV type sizes for fast skipping
@@ -1997,8 +1972,8 @@ class LlamaCppBackend:
         Parses only the KV pairs we need (~30ms even for multi-GB files).
         For split GGUFs, metadata is always in shard 1.
         """
-        # Reset metadata from any previously loaded model so stale flags
-        # (eg _supports_reasoning) do not carry over when switching models.
+        # Reset metadata so stale flags (e.g. _supports_reasoning) don't
+        # carry over when switching models.
         self._context_length = None
         self._chat_template = None
         self._supports_reasoning = False
@@ -2042,8 +2017,7 @@ class LlamaCppBackend:
                 "general.size_label",
                 "general.finetune",
             }
-            # Additional arch-specific keys are added dynamically once
-            # we know the architecture name.
+            # Arch-specific keys added dynamically once we know the arch.
             arch_keys: dict[str, str] = {}  # gguf_key -> attribute name
             arch = None
             sliding_window_pattern_period: Optional[int] = None
@@ -2057,10 +2031,9 @@ class LlamaCppBackend:
                 _tensor_count, kv_count = struct.unpack("<QQ", f.read(16))
 
                 for _ in range(kv_count):
-                    # Tolerate truncated input (e.g., a partial header
-                    # fetched via HTTP byte-range): bail out gracefully
-                    # so the resolver fallback still runs on whatever
-                    # we did manage to parse.
+                    # Tolerate truncated input (e.g. a partial header from an
+                    # HTTP byte-range fetch): bail out so the resolver
+                    # fallback runs on whatever we parsed.
                     try:
                         key_len_bytes = f.read(8)
                         if len(key_len_bytes) < 8:
@@ -2137,9 +2110,9 @@ class LlamaCppBackend:
                         else:
                             self._gguf_skip_value(f, vtype)
                     except (struct.error, UnicodeDecodeError):
-                        # Truncated input (e.g., HTTP byte-range fetch
-                        # of just the GGUF header); break so the
-                        # resolver fallback still runs on what we have.
+                        # Truncated input (e.g. HTTP byte-range header
+                        # fetch); break so the resolver fallback runs on
+                        # what we have.
                         break
 
             # Expand a scalar period straight from the GGUF first.
@@ -2153,7 +2126,7 @@ class LlamaCppBackend:
                 ]
 
             # Otherwise hand off to the resolver (cache / bootstrap /
-            # transformers / HF). See `_resolve_swa_pattern`.
+            # transformers / HF); see `_resolve_swa_pattern`.
             if self._sliding_window_pattern is None and self._sliding_window and self._n_layers:
                 hf_repo_candidates = (
                     general.get("general.source.huggingface.repository"),
@@ -2184,7 +2157,7 @@ class LlamaCppBackend:
                 logger.info(f"GGUF metadata: context_length={self._context_length}")
             if self._chat_template:
                 logger.info(f"GGUF metadata: chat_template={len(self._chat_template)} chars")
-                # Detect thinking/reasoning support from chat template
+                # Detect thinking/reasoning support from chat template.
                 flags = detect_reasoning_flags(
                     self._chat_template,
                     self._model_identifier,
@@ -2209,9 +2182,8 @@ class LlamaCppBackend:
     ) -> str:
         """Download GGUF file(s) from HuggingFace. Returns local path.
 
-        Runs WITHOUT self._lock so that unload_model() can set
-        _cancel_event at any time. Checks _cancel_event between
-        each shard download.
+        Runs WITHOUT self._lock so unload_model() can set _cancel_event at
+        any time; checks it between each shard download.
         """
         try:
             from huggingface_hub import hf_hub_download
@@ -2221,7 +2193,7 @@ class LlamaCppBackend:
                 "Install it with: pip install huggingface_hub"
             )
 
-        # Determine the filename from the variant
+        # Resolve the filename from the variant
         gguf_filename = None
         gguf_extra_shards: list[str] = []
         if hf_variant:
@@ -2250,10 +2222,10 @@ class LlamaCppBackend:
                 logger.warning(f"Could not list repo files: {e}")
 
             # Offline: resolve variant -> filename from the local HF cache.
-            # The heuristic below assumes filenames echo the repo name,
-            # which breaks for e.g. Qwen3.6-27B-MTP-GGUF (no "MTP" in file).
-            # Match against the rel path (not just basename) so subdir
-            # layouts like ``BF16/foo.gguf`` are findable.
+            # The heuristic below assumes filenames echo the repo name, which
+            # breaks for e.g. Qwen3.6-27B-MTP-GGUF (no "MTP" in file). Match
+            # against the rel path (not just basename) so subdir layouts like
+            # ``BF16/foo.gguf`` are findable.
             if not gguf_filename:
                 try:
                     from utils.models.model_config import _iter_hf_cache_snapshots
@@ -2297,7 +2269,7 @@ class LlamaCppBackend:
                 repo_name = hf_repo.split("/")[-1].replace("-GGUF", "")
                 gguf_filename = f"{repo_name}-{hf_variant}.gguf"
 
-        # Check disk space and fall back to a smaller variant if needed
+        # Check disk space; fall back to a smaller variant if needed
         all_gguf_files = [gguf_filename] + gguf_extra_shards
         try:
             from huggingface_hub import get_paths_info, try_to_load_from_cache
@@ -2305,11 +2277,11 @@ class LlamaCppBackend:
             path_infos = list(get_paths_info(hf_repo, all_gguf_files, token = hf_token))
             total_bytes = sum((p.size or 0) for p in path_infos)
 
-            # Subtract bytes already present in the HF cache so we only
-            # preflight against what we actually have to download. Without
-            # this, re-loading a cached large model (e.g. MiniMax-M2.7-GGUF
-            # at 131 GB) fails cold whenever free disk is below the full
-            # weight footprint, even though nothing needs downloading.
+            # Subtract bytes already in the HF cache so we only preflight
+            # against what we must download. Without this, re-loading a
+            # cached large model (e.g. MiniMax-M2.7-GGUF at 131 GB) fails
+            # cold whenever free disk is below the full weight footprint,
+            # even though nothing needs downloading.
             already_cached_bytes = 0
             for p in path_infos:
                 if not p.size:
@@ -2323,7 +2295,7 @@ class LlamaCppBackend:
                         on_disk = os.path.getsize(cached_path)
                     except OSError:
                         on_disk = 0
-                    # Count as satisfied only when the full blob is present.
+                    # Satisfied only when the full blob is present.
                     if on_disk >= p.size:
                         already_cached_bytes += p.size
 
@@ -2430,8 +2402,8 @@ class LlamaCppBackend:
     ) -> Optional[str]:
         """Download the mmproj (vision projection) file from a GGUF repo.
 
-        Prefers mmproj-F16.gguf, falls back to any mmproj*.gguf file.
-        Returns the local path, or None if no mmproj file exists.
+        Prefers mmproj-F16.gguf, else any mmproj*.gguf. Returns the local
+        path, or None if none exists.
         """
 
         def _pick_mmproj(candidates: list[str]) -> Optional[str]:
@@ -2454,8 +2426,8 @@ class LlamaCppBackend:
         except Exception as e:
             logger.debug(f"Could not list repo files for mmproj: {e}")
 
-        # Offline: resolve mmproj from the local HF cache snapshot, same
-        # shape as _download_gguf's offline fallback above.
+        # Offline: resolve mmproj from the local HF cache snapshot, same as
+        # _download_gguf's offline fallback above.
         if target is None:
             try:
                 from utils.models.model_config import _iter_hf_cache_snapshots
@@ -2490,7 +2462,7 @@ class LlamaCppBackend:
     ) -> Optional[str]:
         """Return mmproj_path iff it exists on disk AND matches the model family.
 
-        Returns None if mmproj_path is None, missing on disk, or family-mismatched.
+        None if mmproj_path is None, missing, or family-mismatched.
         """
         if not mmproj_path:
             return None
@@ -2519,8 +2491,8 @@ class LlamaCppBackend:
     # the patched stable-diffusion.cpp / ComfyUI-GGUF enums (LLM_ARCH_FLUX,
     # LLM_ARCH_QWEN_IMAGE, ...). Unsloth publishes FLUX and Qwen-Image GGUFs
     # under https://huggingface.co/collections/unsloth/unsloth-diffusion-ggufs.
-    # Matched exactly (not as a substring) so a chat arch merely containing a
-    # short token like "wan"/"sd1" (e.g. "taiwan") is not misrouted to Images.
+    # Matched exactly (not a substring) so a chat arch merely containing a
+    # short token like "wan"/"sd1" (e.g. "taiwan") isn't misrouted to Images.
     _DIFFUSION_ARCHES = frozenset(
         (
             "qwen_image",
@@ -2544,13 +2516,13 @@ class LlamaCppBackend:
     ) -> str:
         """Explain *why* llama-server failed to start, from its output.
 
-        Several distinct failures all otherwise collapse into the same
-        opaque "invalid GGUF or out of memory" message. The worst case is
-        a diffusion / image GGUF (FLUX, Qwen-Image, ...) loaded as a chat
-        model: the file is perfectly valid and there is plenty of memory,
-        but llama.cpp has no such architecture, so the user is told to free
-        memory that was never the problem (issue #5842). Pick the most
-        specific message the captured output supports.
+        Several distinct failures otherwise collapse into the same opaque
+        "invalid GGUF or out of memory" message. Worst case: a diffusion /
+        image GGUF (FLUX, Qwen-Image, ...) loaded as a chat model -- the
+        file is valid and memory is plentiful, but llama.cpp has no such
+        architecture, so the user is told to free memory that was never the
+        problem (issue #5842). Pick the most specific message the captured
+        output supports.
         """
         lowered = (output or "").lower()
 
@@ -2566,7 +2538,7 @@ class LlamaCppBackend:
 
         # "unknown model architecture: '<arch>'": diffusion -> Images page,
         # Ollama -> Ollama hint, else a precise "unsupported" message. Exact
-        # match so chat archs are never misrouted.
+        # match so chat archs aren't misrouted.
         arch_match = re.search(r"unknown model architecture:\s*'([^']+)'", lowered)
         if arch_match:
             arch = arch_match.group(1)
@@ -2589,7 +2561,7 @@ class LlamaCppBackend:
                 "be run with llama-server."
             )
 
-        # Other Ollama compat failures that do not name an arch. Only when
+        # Other Ollama compat failures that don't name an arch. Only when
         # the output shows a GGUF compat issue, not OOM / missing binaries.
         if is_ollama:
             gguf_compat_hints = (
@@ -2604,7 +2576,7 @@ class LlamaCppBackend:
                     "Ollama instead."
                 )
 
-        # Fallback: genuinely unknown failure (OOM, missing binary, ...).
+        # Fallback: genuinely unknown failure (OOM, missing binary ...).
         return (
             "llama-server failed to start. "
             "Check that the GGUF file is valid and you have enough memory."
@@ -2630,7 +2602,7 @@ class LlamaCppBackend:
         speculative_type: Optional[str] = None,
         spec_draft_n_max: Optional[int] = None,
         n_threads: Optional[int] = None,
-        n_gpu_layers: Optional[int] = None,  # Accepted for caller compat, unused
+        n_gpu_layers: Optional[int] = None,  # caller compat, unused
         n_parallel: int = 1,
         extra_args: Optional[List[str]] = None,
     ) -> bool:
@@ -2641,18 +2613,18 @@ class LlamaCppBackend:
         - Local: ``gguf_path="/path/to/model.gguf"`` → uses ``-m``
         - HF:    ``hf_repo="unsloth/gemma-3-4b-it-GGUF", hf_variant="Q4_K_M"`` → uses ``-hf``
 
-        In HF mode, llama-server handles downloading, caching, and
-        auto-loading mmproj files for vision models.
+        In HF mode, llama-server handles download, caching, and auto-loading
+        mmproj files for vision models.
 
-        Returns True if server started and health check passed.
+        Returns True if the server started and health check passed.
         """
-        # Serialise the whole load so concurrent /load calls never
-        # leave two llama-server processes alive (#5401 / #5161). Does
-        # not block /unload, /status, /load-progress.
+        # Serialise the whole load so concurrent /load calls never leave two
+        # llama-server processes alive (#5401 / #5161). Doesn't block
+        # /unload, /status, /load-progress.
         with self._serial_load_lock:
-            # Duplicate /load that raced past the route-level check
-            # (the first one hadn't published _healthy=True yet). If the
-            # live server already satisfies this request, do nothing.
+            # Duplicate /load that raced past the route-level check (first
+            # one hadn't published _healthy=True yet). If the live server
+            # already satisfies this request, do nothing.
             if self._already_in_target_state(
                 gguf_path = gguf_path,
                 model_identifier = model_identifier,
@@ -2669,7 +2641,7 @@ class LlamaCppBackend:
                     f"load_model: backend already in target state for "
                     f"'{model_identifier}', skipping reload"
                 )
-                # Retry probe only if a prior attempt didn't complete.
+                # Retry probe only if a prior attempt didn't finish.
                 if not self._audio_probed:
                     try:
                         detected = self._detect_audio_type_strict()
@@ -2695,8 +2667,8 @@ class LlamaCppBackend:
                                 return False
                     elif detected:
                         # csm / whisper / audio_vlm: track type but keep
-                        # _is_audio False -- GGUF TTS routing only fires
-                        # for snac/bicodec/dac.
+                        # _is_audio False -- GGUF TTS routing only fires for
+                        # snac/bicodec/dac.
                         with self._lock:
                             if not self._healthy:
                                 return False
@@ -2728,7 +2700,7 @@ class LlamaCppBackend:
             # ── Phase 2: download (NO lock held, so cancel can proceed) ──
             # Scope HF_HUB_OFFLINE to the download block only when DNS is
             # dead; cleanup runs even on exception so a transient hiccup
-            # at the start of one load cannot quarantine future loads.
+            # can't quarantine future loads.
             if hf_repo:
                 with _hf_offline_if_dns_dead():
                     model_path = self._download_gguf(
@@ -2752,7 +2724,7 @@ class LlamaCppBackend:
             # Set identifier early so _read_gguf_metadata can use it for DeepSeek detection
             self._model_identifier = model_identifier
 
-            # Read GGUF metadata (context_length, chat_template) -- fast, header only
+            # Read GGUF metadata (context_length, chat_template); fast, header only
             self._read_gguf_metadata(model_path)
 
             # Check cancel after download
@@ -2760,10 +2732,10 @@ class LlamaCppBackend:
                 logger.info("Load cancelled after download phase")
                 return False
 
-            # Outside ``self._lock`` so /unload, /cancel, /status are
-            # not blocked. ``unload_model`` also records the kill, so
-            # the frontend /unload+/load Apply path engages the wait
-            # here even though no in-process kill happened.
+            # Outside ``self._lock`` so /unload, /cancel, /status aren't
+            # blocked. ``unload_model`` also records the kill, so the
+            # frontend /unload+/load Apply path engages the wait here even
+            # without an in-process kill.
             self._wait_for_vram_settle(since_kill = self._last_kill_monotonic)
 
             # ── Phase 3: start llama-server (under lock) ──────────────
@@ -2775,9 +2747,9 @@ class LlamaCppBackend:
 
                 self._port = self._find_free_port()
 
-                # Select GPU(s) based on model size + estimated KV cache.
-                # Seed safe defaults before GPU probing so the except path
-                # still has valid state to publish.
+                # Select GPU(s) from model size + estimated KV cache. Seed
+                # safe defaults before probing so the except path has valid
+                # state to publish.
                 ctx_override = parse_ctx_override(extra_args)
                 requested_ctx = resolve_requested_ctx(extra_args, n_ctx)
                 cache_override = parse_cache_override(extra_args)
@@ -2793,9 +2765,9 @@ class LlamaCppBackend:
                     model_size = self._get_gguf_size_bytes(model_path)
                     gpus = self._get_gpu_free_memory()
 
-                    # Resolve effective context: 0 means let llama-server use the
-                    # model's native length.  Only expand to a known native length
-                    # if metadata is available; otherwise preserve 0 as a sentinel.
+                    # Resolve effective context: 0 means let llama-server use
+                    # the model's native length. Only expand to a known native
+                    # length if metadata exists; else keep 0 as a sentinel.
                     if requested_ctx > 0:
                         effective_ctx = requested_ctx
                     elif self._context_length is not None:
@@ -2803,18 +2775,17 @@ class LlamaCppBackend:
                     else:
                         effective_ctx = 0
                     original_ctx = effective_ctx
-                    # Default UI ceiling to the model's native context length.
-                    # GPU/VRAM-fit logic below may shrink this if hardware is limited.
+                    # Default UI ceiling to the native context length;
+                    # GPU/VRAM-fit logic below may shrink it on limited HW.
                     max_available_ctx = self._context_length or effective_ctx
 
-                    # Will MTP engage on this load? If so, the auto-fit
-                    # budget needs to reserve extra VRAM for the draft
-                    # model's KV cache + compute graph. Mirrors the
-                    # canonical-mode resolver in _build_speculative_flags:
-                    # forced mtp / mtp+ngram always engage; auto only
-                    # engages on an MTP GGUF >= 3B (sub-3B auto falls
-                    # back to ngram-mod which doesn't need headroom);
-                    # ngram / ngram-simple / off never engage MTP.
+                    # Will MTP engage on this load? If so, auto-fit must
+                    # reserve extra VRAM for the draft model's KV cache +
+                    # compute graph. Mirrors _build_speculative_flags'
+                    # canonical-mode resolver: forced mtp / mtp+ngram always
+                    # engage; auto only on an MTP GGUF >= 3B (sub-3B auto
+                    # falls back to ngram-mod, no headroom needed); ngram /
+                    # ngram-simple / off never engage MTP.
                     _mtp_canonical = _canonicalize_spec_mode(speculative_type)
                     _mtp_effective = _mtp_canonical or "auto"
                     _mtp_size_for_fit = _extract_model_size_b(model_identifier)
@@ -2834,26 +2805,23 @@ class LlamaCppBackend:
                         )
                     )
 
-                    # Auto-cap context to fit in GPU VRAM and select GPUs.
+                    # Auto-cap context to fit GPU VRAM and select GPUs.
+                    # Two policies by whether the user set n_ctx:
                     #
-                    # Two policies depending on whether the user set n_ctx:
+                    # Explicit n_ctx: honor it. Try the full requested context
+                    #   with _select_gpus (uses as many GPUs as needed); only
+                    #   cap if it doesn't fit on any GPU combination.
                     #
-                    # Explicit n_ctx (user chose a context length):
-                    #   Honor it. Try the full requested context with _select_gpus
-                    #   (which uses as many GPUs as needed). Only cap if it doesn't
-                    #   fit on any GPU combination.
-                    #
-                    # Auto n_ctx=0 (model's native context):
-                    #   Prefer fewer GPUs with reduced context over more GPUs,
-                    #   since multi-GPU is slower and the user didn't ask for a
-                    #   specific context length.
+                    # Auto n_ctx=0 (native context): prefer fewer GPUs with
+                    #   reduced context, since multi-GPU is slower and the user
+                    #   didn't ask for a specific length.
                     gpu_indices, use_fit = None, True
                     explicit_ctx = requested_ctx > 0
 
                     if gpus and self._can_estimate_kv() and effective_ctx > 0:
-                        # Compute the largest hardware-aware cap from the model's
-                        # native context across all usable GPU subsets (for UI
-                        # bounds), independent of the currently requested context.
+                        # Largest hardware-aware cap from the native context
+                        # across all usable GPU subsets (for UI bounds),
+                        # independent of the requested context.
                         native_ctx_for_cap = self._context_length or effective_ctx
                         if native_ctx_for_cap > 0:
                             ranked_for_cap = sorted(gpus, key = lambda g: g[1], reverse = True)
@@ -2879,30 +2847,28 @@ class LlamaCppBackend:
                                 max_available_ctx = best_cap
                             else:
                                 # Weights exceed 90% of every GPU subset's free
-                                # memory, so there is no fitting context. Anchor
-                                # the UI's "safe zone" threshold at 4096 (the
-                                # spec's default when the model cannot fit) so
-                                # the ctx slider shows the "might be slower"
-                                # warning as soon as the user drags above the
-                                # fallback default instead of never.
+                                # memory, so no context fits. Anchor the UI's
+                                # "safe zone" threshold at 4096 (the spec's
+                                # default when the model can't fit) so the ctx
+                                # slider shows the "might be slower" warning as
+                                # soon as the user drags above the fallback.
                                 max_available_ctx = min(4096, native_ctx_for_cap)
 
                         if explicit_ctx:
-                            # Honor the user's requested context verbatim. If it
-                            # fits, pin GPUs and skip --fit; if it doesn't, ship
+                            # Honor the requested context verbatim. If it fits,
+                            # pin GPUs and skip --fit; if not, ship
                             # -c <user_ctx> --fit on and let llama-server flex
-                            # -ngl (CPU layer offload). The UI is expected to
-                            # have surfaced the "might be slower" warning before
-                            # the user submitted a ctx above the fit ceiling.
+                            # -ngl (CPU layer offload). The UI should have
+                            # surfaced the "might be slower" warning before a
+                            # ctx above the fit ceiling was submitted.
                             requested_total = model_size + self._estimate_kv_cache_bytes(
                                 effective_ctx, cache_type_kv, n_parallel = n_parallel
                             )
                             gpu_indices, use_fit = self._select_gpus(requested_total, gpus)
                             # No silent shrink: effective_ctx stays == requested_ctx.
                         else:
-                            # Auto context: prefer fewer GPUs, cap context
-                            # to fit. Same headroom threshold as
-                            # _select_gpus (#5106).
+                            # Auto context: prefer fewer GPUs, cap to fit. Same
+                            # headroom threshold as _select_gpus (#5106).
                             ranked = sorted(gpus, key = lambda g: g[1], reverse = True)
                             pin_fraction = self._GPU_PIN_VRAM_FRACTION
                             for n_gpus in range(1, len(ranked) + 1):
@@ -2927,9 +2893,9 @@ class LlamaCppBackend:
                                     break
                             else:
                                 # Native ctx doesn't fit. Drop to 4096 and
-                                # re-check before deferring to --fit on:
-                                # a model that overflows at 131k may pin
-                                # comfortably with a 4096 KV cache (#5106).
+                                # re-check before deferring to --fit on: a model
+                                # that overflows at 131k may pin comfortably
+                                # with a 4096 KV cache (#5106).
                                 effective_ctx = min(4096, effective_ctx)
                                 if effective_ctx > 0:
                                     for n_gpus in range(1, len(ranked) + 1):
@@ -2947,9 +2913,9 @@ class LlamaCppBackend:
                                             break
 
                     elif gpus:
-                        # Can't estimate KV -- fall back to file-size-only check.
-                        # Without KV estimation we cannot prove a hardware cap, so
-                        # keep the ceiling at the native context (already the default).
+                        # Can't estimate KV -- file-size-only check. Without KV
+                        # estimation we can't prove a hardware cap, so keep the
+                        # ceiling at the native context (already the default).
                         logger.debug(
                             "Falling back to file-size-only GPU selection",
                             model_size_gb = round(model_size / (1024**3), 2),
@@ -2957,8 +2923,8 @@ class LlamaCppBackend:
                         gpu_indices, use_fit = self._select_gpus(model_size, gpus)
                         if use_fit and not explicit_ctx:
                             # Weights don't fit on any subset. Default the UI to
-                            # 4096 so the slider doesn't land on an unusable native
-                            # context. --fit on will flex -ngl at runtime.
+                            # 4096 so the slider doesn't land on an unusable
+                            # native context; --fit on flexes -ngl at runtime.
                             effective_ctx = min(4096, effective_ctx) if effective_ctx > 0 else 4096
 
                     if effective_ctx < original_ctx:
@@ -3032,15 +2998,16 @@ class LlamaCppBackend:
                 if use_fit:
                     cmd.extend(["--fit", "on"])
                 elif gpu_indices is not None:
-                    # Model fits on selected GPU(s) -- offload all layers
+                    # Fits on selected GPU(s) -- offload all layers
                     cmd.extend(["-ngl", "-1"])
 
-                # -1 = llama.cpp auto-detect (physical cores). Pass explicitly so we
-                # do not inherit llama-server's internal default, which has historically
-                # varied (hardware concurrency incl. hyperthreads on some builds).
+                # -1 = llama.cpp auto-detect (physical cores). Pass explicitly
+                # so we don't inherit llama-server's internal default, which
+                # has varied (hardware concurrency incl. hyperthreads on some
+                # builds).
                 cmd.extend(["--threads", str(n_threads if n_threads is not None else -1)])
 
-                # Always enable Jinja chat template rendering for proper template support
+                # Enable Jinja chat template rendering
                 cmd.extend(["--jinja"])
 
                 # KV cache data type
@@ -3069,11 +3036,11 @@ class LlamaCppBackend:
                 else:
                     self._cache_type_kv = None
 
-                # Speculative decoding (n-gram self-speculation, zero VRAM cost)
-                # ngram-mod: ~16 MB shared hash pool, constant memory/complexity,
-                # variable draft lengths.  Helps most when the model repeats
-                # existing text (code refactoring, summarization, reasoning).
-                # For general chat with low repetition, overhead is ~5 ms.
+                # Speculative decoding (n-gram self-speculation, zero VRAM).
+                # ngram-mod: ~16 MB shared hash pool, constant memory/
+                # complexity, variable draft lengths. Helps most when the
+                # model repeats existing text (code refactor, summarization,
+                # reasoning); for low-repetition chat, overhead is ~5 ms.
                 #
                 # Benchmarks from upstream llama.cpp speculative-decoding PRs:
                 #   Scenario                        | Without | With    | Speedup
@@ -3090,8 +3057,8 @@ class LlamaCppBackend:
                 # ref: https://github.com/ggml-org/llama.cpp/pull/18471
                 # draft-mtp: MTP heads on Unsloth's *-MTP GGUFs
                 # (llama.cpp #22673). Auto-enabled via nextn_predict_layers,
-                # fallback to -MTP in name. GPU: MTP-only. CPU/Mac: chain
-                # with ngram-mod. See unsloth.ai/docs/models/qwen3.6#mtp-guide.
+                # fallback to -MTP in name. GPU: MTP-only. CPU/Mac: chain with
+                # ngram-mod. See unsloth.ai/docs/models/qwen3.6#mtp-guide.
                 spec_flags = self._build_speculative_flags(
                     speculative_type = speculative_type,
                     spec_draft_n_max = spec_draft_n_max,
@@ -3103,7 +3070,7 @@ class LlamaCppBackend:
                 )
                 cmd.extend(spec_flags)
 
-                # Apply custom chat template override if provided
+                # Apply custom chat template override if provided.
                 self._chat_template_override = chat_template_override
                 if chat_template_override:
                     import tempfile
@@ -3130,10 +3097,9 @@ class LlamaCppBackend:
                     cmd.extend(["--chat-template-file", self._chat_template_file.name])
                     logger.info(f"Using custom chat template file: {self._chat_template_file.name}")
 
-                # For reasoning models, set default thinking mode.
-                # Qwen3.5/3.6 models below 9B (0.8B, 2B, 4B) disable thinking by default.
-                # Only 9B and larger enable thinking.
-                # Always-on templates ignore the kwarg entirely, so skip.
+                # For reasoning models, set default thinking mode. Qwen3.5/3.6
+                # below 9B (0.8B, 2B, 4B) disable thinking by default; 9B+
+                # enable it. Always-on templates ignore the kwarg, so skip.
                 if self._supports_reasoning and not self._reasoning_always_on:
                     thinking_default = True
                     mid = (model_identifier or "").lower()
@@ -3155,7 +3121,7 @@ class LlamaCppBackend:
                     cmd.extend(["--mmproj", launch_mmproj_path])
                     logger.info(f"Using mmproj for vision: {launch_mmproj_path}")
 
-                # Option C: add --api-key for direct client access when enabled
+                # Option C: --api-key for direct client access when enabled
                 import os as _os
                 import secrets as _secrets
 
@@ -3166,11 +3132,10 @@ class LlamaCppBackend:
                 else:
                     self._api_key = None
 
-                # User-supplied pass-through args go last so llama.cpp's
-                # last-wins flag parsing lets the user override Studio's
-                # auto-set tier-2 flags (e.g. --cache-type-k, --spec-type).
-                # The route layer has already validated this list against
-                # the managed-flag denylist via validate_extra_args().
+                # User pass-through args go last so llama.cpp's last-wins
+                # parsing lets the user override Studio's auto-set tier-2 flags
+                # (e.g. --cache-type-k, --spec-type). The route layer already
+                # validated this list via validate_extra_args().
                 if extra_args:
                     cmd.extend(str(a) for a in extra_args)
                     logger.info(f"Appending user extra args to llama-server: {list(extra_args)}")
@@ -3182,7 +3147,7 @@ class LlamaCppBackend:
                         _log_cmd[_ki] = "<redacted>"
                 logger.info(f"Starting llama-server: {' '.join(_log_cmd)}")
 
-                # Set library paths so llama-server can find its shared libs and CUDA DLLs
+                # Set library paths so llama-server finds its shared libs and CUDA DLLs
                 import os
                 import sys
 
@@ -3196,7 +3161,7 @@ class LlamaCppBackend:
                     logger.info("AMD unified-memory APU: set GGML_CUDA_ENABLE_UNIFIED_MEMORY=1")
 
                 if sys.platform == "win32":
-                    # See _build_windows_path_dirs for ordering. #5106.
+                    # Ordering: see _build_windows_path_dirs. #5106.
                     path_dirs = self._build_windows_path_dirs(
                         binary_dir,
                         sys.prefix,
@@ -3206,28 +3171,28 @@ class LlamaCppBackend:
                     env["PATH"] = ";".join(path_dirs) + ";" + existing_path
 
                     # ROCm: the llama.cpp prebuilt bundles its own rocblas.dll
-                    # but NOT the Tensile kernel library files it needs
-                    # (rocblas/library/TensileLibrary*.dat + *.hsaco).  The
-                    # bundled DLL searches relative to its own location by
-                    # default (i.e. <binary_dir>/rocblas/library/) which does
-                    # not exist, causing a silent crash on the first GEMM.
-                    # ROCBLAS_TENSILE_LIBPATH overrides that search to point at
-                    # the ROCm installation where the kernel files actually are.
+                    # but NOT the Tensile kernel files it needs
+                    # (rocblas/library/TensileLibrary*.dat + *.hsaco). The
+                    # bundled DLL searches relative to its own location
+                    # (<binary_dir>/rocblas/library/), which doesn't exist ->
+                    # silent crash on the first GEMM. ROCBLAS_TENSILE_LIBPATH
+                    # repoints that search at the ROCm install where the kernel
+                    # files actually are.
                     _hip_path = os.environ.get("HIP_PATH", os.environ.get("ROCM_PATH", ""))
                     if _hip_path:
                         _rocblas_lib = os.path.join(_hip_path, "bin", "rocblas", "library")
                         if os.path.isdir(_rocblas_lib):
                             env.setdefault("ROCBLAS_TENSILE_LIBPATH", _rocblas_lib)
                 else:
-                    # Linux: set LD_LIBRARY_PATH for shared libs next to the binary
-                    # and CUDA runtime libs (libcudart, libcublas, etc.)
+                    # Linux: LD_LIBRARY_PATH for shared libs next to the binary
+                    # plus CUDA runtime libs (libcudart, libcublas, etc.)
                     import platform
 
                     lib_dirs = [binary_dir]
                     _arch = platform.machine()  # x86_64, aarch64, etc.
 
                     # Pip-installed nvidia CUDA runtime libs (e.g. torch's
-                    # bundled cuda-bindings).  The prebuilt llama.cpp binary
+                    # bundled cuda-bindings). The prebuilt llama.cpp binary
                     # links against libcudart.so.13 / libcublas.so.13 which
                     # live here, not in /usr/local/cuda.
                     import glob as _glob
@@ -3269,8 +3234,7 @@ class LlamaCppBackend:
                         "/usr/local/cuda/lib64",
                         f"/usr/local/cuda/targets/{_arch}-linux/lib",
                         # Fallback CUDA compat paths (e.g. binary built with
-                        # CUDA 12 on a system where default /usr/local/cuda
-                        # points to CUDA 13+).
+                        # CUDA 12 where default /usr/local/cuda is CUDA 13+).
                         "/usr/local/cuda-12/lib64",
                         "/usr/local/cuda-12.8/lib64",
                         f"/usr/local/cuda-12/targets/{_arch}-linux/lib",
@@ -3283,9 +3247,9 @@ class LlamaCppBackend:
                     env["LD_LIBRARY_PATH"] = f"{new_ld}:{existing_ld}" if existing_ld else new_ld
 
                 # Pin to selected GPU(s). On ROCm, llama-server (and any torch
-                # in the subprocess) honors HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES;
-                # narrowing only CUDA_VISIBLE_DEVICES leaves an AMD child seeing
-                # the full HIP/ROCR set the parent inherited.
+                # in the subprocess) honors HIP_VISIBLE_DEVICES /
+                # ROCR_VISIBLE_DEVICES; narrowing only CUDA_VISIBLE_DEVICES
+                # leaves an AMD child seeing the full HIP/ROCR set inherited.
                 if gpu_indices is not None:
                     pinned = ",".join(str(i) for i in gpu_indices)
                     env["CUDA_VISIBLE_DEVICES"] = pinned
@@ -3298,18 +3262,17 @@ class LlamaCppBackend:
                         logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 
                 # Defensive kill: if a concurrent load slipped past Phase 1
-                # (because its `self._process` was None at the time) and
-                # already stored a Popen handle here, drop that orphan
-                # before we overwrite the reference. See issue #5161.
+                # (its `self._process` was None then) and already stored a
+                # Popen handle here, drop that orphan before we overwrite the
+                # reference. See issue #5161.
                 self._kill_process()
 
                 self._stdout_lines = []
                 # Tee llama-server output to a dedicated log file so a
-                # post-mortem in CI (or after a remote-debug session)
-                # has the full subprocess trail even when the parent
-                # only stored the last 50 lines. Path lives under the
-                # studio home so it ships in the same place all other
-                # Studio logs live.
+                # post-mortem in CI (or after a remote-debug session) has the
+                # full subprocess trail even when the parent only kept the last
+                # 50 lines. Path lives under the studio home alongside other
+                # Studio logs.
                 self._llama_log_fh = None
                 try:
                     log_dir = _swa_cache_path().parent / "logs" / "llama-server"
@@ -3337,20 +3300,19 @@ class LlamaCppBackend:
                     **_windows_hidden_subprocess_kwargs(),
                 )
 
-                # Start background thread to drain stdout and prevent pipe deadlock
+                # Background thread to drain stdout (prevents pipe deadlock)
                 self._stdout_thread = threading.Thread(
                     target = self._drain_stdout, daemon = True, name = "llama-stdout"
                 )
                 self._stdout_thread.start()
 
                 # Store the resolved on-disk path, not the caller's kwarg. In
-                # HF mode the caller passes gguf_path=None and the real path
-                # (``model_path``) is what llama-server is actually mmap'ing.
-                # Downstream consumers (load_progress, log lines, etc.) need
-                # the path that exists on disk.
+                # HF mode the caller passes gguf_path=None and ``model_path``
+                # is what llama-server actually mmap's. Downstream consumers
+                # (load_progress, log lines, etc.) need the real on-disk path.
                 self._gguf_path = model_path
                 self._hf_repo = hf_repo
-                # For local GGUF files, extract variant from filename if not provided
+                # For local GGUF files, extract variant from filename if absent
                 if hf_variant:
                     self._hf_variant = hf_variant
                 elif gguf_path:
@@ -3364,9 +3326,9 @@ class LlamaCppBackend:
                 self._is_vision = effective_is_vision
                 self._model_identifier = model_identifier
 
-                # Store the effective (possibly capped) context separately.
-                # Do NOT overwrite _context_length -- it holds the model's native
-                # context length from GGUF metadata and is used for display/info.
+                # Store the effective (possibly capped) context separately. Do
+                # NOT overwrite _context_length -- it holds the native context
+                # length from GGUF metadata, used for display/info.
                 self._effective_context_length = (
                     effective_ctx if effective_ctx > 0 else self._context_length
                 )
@@ -3374,7 +3336,7 @@ class LlamaCppBackend:
                     max_available_ctx if max_available_ctx > 0 else self._effective_context_length
                 )
 
-                # Wait for llama-server to become healthy
+                # Wait for llama-server to become healthy.
                 if not self._wait_for_health(timeout = 600.0):
                     self._kill_process()
                     raise RuntimeError(
@@ -3387,11 +3349,11 @@ class LlamaCppBackend:
 
                 self._healthy = True
 
-                # Commit caller intent only after _healthy=True so a
-                # failed startup can't poison the next inheritance check.
-                # None keeps prior, [] clears, list sets. Source records
-                # the caller's hf_variant (None for local files) so the
-                # route's same_source check stays symmetric.
+                # Commit caller intent only after _healthy=True so a failed
+                # startup can't poison the next inheritance check. None keeps
+                # prior, [] clears, list sets. Source records the caller's
+                # hf_variant (None for local files) so the route's same_source
+                # check stays symmetric.
                 if extra_args is not None:
                     self._extra_args = list(extra_args)
                     self._extra_args_source = (model_identifier, hf_variant)
@@ -3436,7 +3398,7 @@ class LlamaCppBackend:
                         self._is_audio = True
                         self._audio_type = detected
                     except Exception as exc:
-                        # Surface as HTTP 500 -- matches pre-PR contract.
+                        # Surface as HTTP 500 (matches pre-PR contract).
                         logger.warning(
                             "Failed to init audio codec '%s': %s",
                             detected,
@@ -3452,7 +3414,7 @@ class LlamaCppBackend:
                         return False
                     self._audio_type = detected
 
-            # Audio input = token probe (audio_vlm/whisper) OR mmproj audio encoder.
+            # Audio input = token probe (audio_vlm/whisper) OR mmproj encoder.
             from utils.models.model_config import is_audio_input_type
 
             self._has_audio_input = bool(is_audio_input_type(self._audio_type)) or bool(
@@ -3481,11 +3443,11 @@ class LlamaCppBackend:
         status round-trip), and ``self._spec_draft_n_max`` (user override
         only; None when the platform default applies).
 
-        Speculative decoding (n-gram self-speculation, zero VRAM cost):
+        Speculative decoding (n-gram self-speculation, zero VRAM):
         ngram-mod uses a ~16 MB shared hash pool, constant memory /
         complexity, variable draft lengths. Helps most when the model
-        repeats existing text (code refactor, summarisation, reasoning).
-        For general chat with low repetition, overhead is ~5 ms.
+        repeats existing text (code refactor, summarisation, reasoning);
+        for low-repetition chat, overhead is ~5 ms.
 
         Benchmarks from upstream llama.cpp speculative-decoding PRs:
           Scenario                        | Without | With    | Speedup
@@ -3493,18 +3455,17 @@ class LlamaCppBackend:
           Qwen3-235B offloaded            |  12 t/s |  21 t/s | 1.8x
           gpt-oss-120b repeat (92% accept)| 181 t/s | 814 t/s | 4.5x
 
-        Sub-3B dense MTP regresses vs spec-off because the draft head's
-        per-token cost exceeds the acceptance savings at this scale.
-        Q4_K_XL clean bench (each prompt once after an unrelated warmup)
-        on B200 + x86 CPU:
+        Sub-3B dense MTP regresses vs spec-off: the draft head's per-token
+        cost exceeds the acceptance savings at this scale. Q4_K_XL clean
+        bench (each prompt once after an unrelated warmup) on B200 + x86 CPU:
           0.8B GPU: draft-mtp n=2 = 0.58x vs OFF; ngram-only = 1.10x
           2B   GPU: draft-mtp n=2 = 0.82x vs OFF; OFF or ngram = 1.00x
           0.8B CPU: chained n=2   = 0.86x vs OFF; ngram-only = 1.19x
           2B   CPU: chained n=2   = 0.83x vs OFF; ngram-only = 1.01x
           4B+ GPU/CPU: spec on is a net win (1.08x-1.46x).
         Auto falls back to ngram-mod (zero-VRAM, near-zero idle cost on
-        diverse content); forced MTP variants engage anyway and just log
-        a warning per the user's choice.
+        diverse content); forced MTP variants engage anyway and just log a
+        warning per the user's choice.
         """
         flags: List[str] = []
         # Reset; emit branches re-set on the resolved emission.
@@ -3512,7 +3473,7 @@ class LlamaCppBackend:
         self._speculative_type = None
 
         # Canonical UI-facing requested mode: auto / mtp / ngram /
-        # mtp+ngram / off / ngram-simple. Legacy values are mapped via
+        # mtp+ngram / off / ngram-simple. Legacy values mapped via
         # _canonicalize_spec_mode (default->auto, draft-mtp->mtp,
         # ngram-mod->ngram, "ngram-mod,draft-mtp"->mtp+ngram).
         canonical_mode = _canonicalize_spec_mode(speculative_type)
@@ -3525,8 +3486,8 @@ class LlamaCppBackend:
 
         if user_owns_spec_type:
             # User --spec-type in extra_args wins outright; suppress
-            # auto-emit so we don't emit a duplicate / conflicting
-            # spec block. Record requested mode as None.
+            # auto-emit to avoid a duplicate / conflicting spec block.
+            # Record requested mode as None.
             self._requested_spec_mode = None
             return flags
 
@@ -3536,8 +3497,7 @@ class LlamaCppBackend:
         def _resolved_draft_n_max() -> int:
             # User override wins; else platform default (the B200 / x86
             # clean-sweep sweet spot from PR #5582 is n=2 GPU, n=3 CPU;
-            # raising past 3 starts to regress on essay-style
-            # low-acceptance prompts).
+            # past 3 regresses on essay-style low-acceptance prompts).
             if spec_draft_n_max is not None:
                 n = int(spec_draft_n_max)
                 self._spec_draft_n_max = n
@@ -3646,14 +3606,14 @@ class LlamaCppBackend:
             _emit_mtp(chain_ngram = True)
             return flags
 
-        # effective_mode == "auto": today's promotion path. llama.cpp
-        # #22673: MTP is compatible with mmproj, so there's no vision gate.
+        # effective_mode == "auto": the promotion path. llama.cpp #22673:
+        # MTP is compatible with mmproj, so there's no vision gate.
         if is_mtp_model and not _mtp_too_small:
             # GPU: MTP-only. CPU/Mac: chain ngram-mod + MTP.
             _emit_mtp(chain_ngram = not gpus)
         elif is_mtp_model and _mtp_too_small:
-            # Sub-3B fallback: drop the MTP draft head, keep ngram-mod
-            # when the binary supports it.
+            # Sub-3B fallback: drop the MTP draft head, keep ngram-mod when
+            # the binary supports it.
             _small_caps = self.probe_server_capabilities(binary)
             if _small_caps.get("supports_ngram_mod"):
                 logger.info(
@@ -3693,17 +3653,16 @@ class LlamaCppBackend:
     ) -> bool:
         """True iff the live server already satisfies these load kwargs.
 
-        Mirrors ``routes/inference.py:_request_matches_loaded_settings``
-        but compares raw kwargs so ``load_model`` can short-circuit a
-        duplicate /load that raced past the route-level check (#5401).
+        Mirrors ``routes/inference.py:_request_matches_loaded_settings`` but
+        compares raw kwargs so ``load_model`` can short-circuit a duplicate
+        /load that raced past the route-level check (#5401).
         """
         if not self.is_loaded:
             return False
         if (self._model_identifier or "").lower() != (model_identifier or "").lower():
             return False
-        # Direct-file loads pass hf_variant=None while the backend
-        # stores an extracted filename label; compare paths instead
-        # to keep the guard symmetric.
+        # Direct-file loads pass hf_variant=None while the backend stores an
+        # extracted filename label; compare paths to keep the guard symmetric.
         if gguf_path is not None and self._gguf_path:
             try:
                 if Path(self._gguf_path).resolve() != Path(gguf_path).resolve():
@@ -3726,11 +3685,10 @@ class LlamaCppBackend:
         if _norm(self._cache_type_kv) != _norm(cache_type_kv):
             return False
 
-        # Compare on the canonical UI-facing mode the user requested.
-        # When extra_args carries --spec-type, the route-layer code paths
-        # bypass the dropdown anyway and the backend stores
-        # _requested_spec_mode = None; the request mirrors that by
-        # canonicalising to None.
+        # Compare on the canonical UI-facing requested mode. When extra_args
+        # carries --spec-type, the route layer bypasses the dropdown and the
+        # backend stores _requested_spec_mode = None; the request mirrors
+        # that by canonicalising to None.
         if _extra_args_set_spec_type(extra_args):
             req_mode = None
         else:
@@ -3739,10 +3697,10 @@ class LlamaCppBackend:
         if req_mode != backend_mode:
             return False
 
-        # spec_draft_n_max only matters when an MTP variant is actually
-        # engaged. Compare on the resolved spec rather than the requested
-        # mode so an Auto request that auto-promoted to draft-mtp under
-        # the hood still bounces a reload when the user changes n_max.
+        # spec_draft_n_max only matters when an MTP variant is engaged.
+        # Compare on the resolved spec, not the requested mode, so an Auto
+        # request that auto-promoted to draft-mtp still bounces a reload
+        # when the user changes n_max.
         if (
             self._speculative_type == "draft-mtp"
             and spec_draft_n_max is not None
@@ -3753,8 +3711,8 @@ class LlamaCppBackend:
         if (self._chat_template_override or None) != (chat_template_override or None):
             return False
 
-        # extra_args=None means "no opinion" (inherit semantics handled
-        # at the route layer); only an explicit list forces equality.
+        # extra_args=None means "no opinion" (inherit handled at the route
+        # layer); only an explicit list forces equality.
         if extra_args is not None:
             current = list(self._extra_args) if self._extra_args is not None else []
             if list(extra_args) != current:
@@ -3765,13 +3723,13 @@ class LlamaCppBackend:
         self, expected_gpu: bool, detected_gpus: list[tuple[int, int]]
     ) -> Optional[bool]:
         """True if a GPU model buffer was allocated, False if only CPU
-        buffers landed despite GPU intent, None when there's no signal
-        (no GPU detected, no buffer-size lines, etc.)."""
+        buffers landed despite GPU intent, None when there's no signal (no
+        GPU detected, no buffer-size lines, etc.)."""
         if not detected_gpus or not expected_gpu:
             return None
-        # llama-server logs one ``... model buffer size = N MiB`` line
-        # per backend buffer; CUDA0 / ROCm0 / Metal / Vulkan0 /
-        # OpenCL0 / SYCL0 are GPU, CPU / CPU_Mapped are not.
+        # llama-server logs one ``... model buffer size = N MiB`` line per
+        # backend buffer; CUDA0 / ROCm0 / Metal / Vulkan0 / OpenCL0 / SYCL0
+        # are GPU, CPU / CPU_Mapped are not.
         gpu_markers = ("CUDA", "ROCm", "Metal", "Vulkan", "OpenCL", "SYCL")
         saw_buffer_line = False
         saw_gpu_buffer = False
@@ -3787,7 +3745,7 @@ class LlamaCppBackend:
         return saw_gpu_buffer
 
     def unload_model(self) -> bool:
-        """Terminate the llama-server subprocess and cancel any in-flight download."""
+        """Terminate the subprocess and cancel any in-flight download."""
         self._cancel_event.set()
         with self._lock:
             self._kill_process()
@@ -3837,7 +3795,7 @@ class LlamaCppBackend:
             self._ssm_state_size = None
             self._shared_kv_layers = None
             self._nextn_predict_layers = None
-            # Clean up temp chat template file
+            # Clean up temp chat template file.
             if hasattr(self, "_chat_template_file") and self._chat_template_file:
                 try:
                     import os
@@ -3845,7 +3803,7 @@ class LlamaCppBackend:
                 except Exception:
                     pass
                 self._chat_template_file = None
-            # Free audio codec GPU memory
+            # Free audio codec GPU memory.
             if LlamaCppBackend._codec_mgr is not None:
                 LlamaCppBackend._codec_mgr.unload()
                 LlamaCppBackend._codec_mgr = None
@@ -3871,12 +3829,12 @@ class LlamaCppBackend:
         finally:
             self._process = None
             # Clear healthy so a /load arriving during the replacement
-            # server's warm-up window cannot short-circuit against the
+            # server's warm-up window can't short-circuit against the
             # previous server's health (#5401).
             self._healthy = False
-            # Drives _wait_for_vram_settle in the next load_model;
-            # set in finally so both in-process and frontend
-            # /unload+/load Apply paths record the kill.
+            # Drives _wait_for_vram_settle in the next load_model; set in
+            # finally so both in-process and frontend /unload+/load Apply
+            # paths record the kill.
             self._last_kill_monotonic = time.monotonic()
             if self._stdout_thread is not None:
                 self._stdout_thread.join(timeout = 2)
@@ -3894,23 +3852,21 @@ class LlamaCppBackend:
         """Kill orphaned llama-server processes started by studio.
 
         Only kills processes whose resolved binary lives under a known
-        Studio install directory (or matches an exact env-var override)
-        to avoid terminating unrelated llama-server instances.
+        Studio install dir (or matches an exact env-var override), to avoid
+        terminating unrelated llama-server instances. Mirrors every location
+        _find_llama_server_binary() can return, so orphans from any
+        supported install path are cleaned up.
 
-        Mirrors every location that _find_llama_server_binary() can
-        return from so that orphans from any supported install path
-        are still cleaned up.
-
-        Uses psutil for cross-platform support (Linux, macOS, Windows).
-        Falls back to pgrep + /proc/<pid>/exe on Linux when psutil is
-        not installed.
+        Uses psutil for cross-platform support (Linux, macOS, Windows);
+        falls back to pgrep + /proc/<pid>/exe on Linux when psutil is
+        absent.
         """
         try:
             # -- Build the ownership allowlist --------------------------------
-            # Two kinds of matches:
+            # Two match kinds:
             #   exact_binaries  -- env var overrides (exact path match only)
-            #   install_roots   -- directory trees that are Studio-owned
-            #                      (binary must be *under* one of these)
+            #   install_roots   -- Studio-owned dir trees (binary must be
+            #                      *under* one of these)
             install_roots: list[Path] = []
 
             # Env-mode custom root (mirrors _find_llama_server_binary).
@@ -3930,12 +3886,12 @@ class LlamaCppBackend:
                 pass
 
             # Primary install dir (default mode only). Env-mode skips this so
-            # a custom-root Studio cannot kill a concurrent default-install
+            # a custom-root Studio can't kill a concurrent default-install
             # Studio's llama-server (same OS user, different install).
             if not _is_custom_root:
                 install_roots.append(Path.home() / ".unsloth" / "llama.cpp")
 
-            # Legacy in-tree build dirs (older setup.sh versions)
+            # Legacy in-tree build dirs (older setup.sh)
             project_root = Path(__file__).resolve().parents[4]
             install_roots.append(project_root / "llama.cpp")
 
@@ -3956,7 +3912,7 @@ class LlamaCppBackend:
                 except OSError:
                     pass
 
-            # Resolve all roots so is_relative_to works reliably
+            # Resolve all roots so is_relative_to works reliably.
             resolved_roots: list[Path] = []
             for root in install_roots:
                 try:
@@ -3967,8 +3923,8 @@ class LlamaCppBackend:
             my_pid = os.getpid()
 
             # -- Enumerate processes -------------------------------------------
-            # Prefer psutil (cross-platform).  Fall back to pgrep + /proc on
-            # Linux when psutil is not installed.
+            # Prefer psutil (cross-platform); fall back to pgrep + /proc on
+            # Linux when psutil is absent.
             try:
                 import psutil
                 has_psutil = True
@@ -3991,9 +3947,8 @@ class LlamaCppBackend:
 
                         exe_path = Path(exe).resolve()
 
-                        # Check ownership: exact binary match OR binary is
-                        # under a known install root (proper ancestry, not
-                        # substring).
+                        # Ownership: exact binary match OR binary under a
+                        # known install root (proper ancestry, not substring).
                         is_ours = exe_path in exact_binaries or any(
                             exe_path.is_relative_to(root) for root in resolved_roots
                         )
@@ -4032,11 +3987,10 @@ class LlamaCppBackend:
                     if pid == my_pid:
                         continue
 
-                    # Resolve the actual executable.  /proc/<pid>/exe is a
-                    # symlink to the real binary and avoids all cmdline-
-                    # parsing ambiguities (spaces in paths, argv rewriting).
-                    # Fall back to the first cmdline token when /proc is
-                    # unavailable.
+                    # Resolve the actual executable. /proc/<pid>/exe is a
+                    # symlink to the real binary and avoids cmdline-parsing
+                    # ambiguities (spaces in paths, argv rewriting). Fall back
+                    # to the first cmdline token when /proc is unavailable.
                     proc_exe = Path(f"/proc/{pid}/exe")
                     try:
                         binary = proc_exe.resolve(strict = True)
@@ -4075,15 +4029,15 @@ class LlamaCppBackend:
         """
         Poll llama-server's /health endpoint until it responds 200.
 
-        Also monitors subprocess for early exit/crash.
+        Also monitors the subprocess for early exit/crash.
         """
         deadline = time.monotonic() + timeout
         url = f"http://127.0.0.1:{self._port}/health"
 
         while time.monotonic() < deadline:
-            # Check if process crashed
+            # Process crashed?
             if self._process.poll() is not None:
-                # Give the drain thread a moment to collect final output
+                # Let the drain thread collect final output.
                 if self._stdout_thread is not None:
                     self._stdout_thread.join(timeout = 2)
                 output = "\n".join(self._stdout_lines[-50:])
@@ -4102,8 +4056,8 @@ class LlamaCppBackend:
                 httpx.TimeoutException,
                 # ReadError covers TCP RST mid-read while llama-server is
                 # still binding the port (Windows: WinError 10054). The
-                # crash-detection branch above catches a real exit; this
-                # one keeps a transient socket close from masking it.
+                # crash branch above catches a real exit; this keeps a
+                # transient socket close from masking it.
                 httpx.ReadError,
                 httpx.RemoteProtocolError,
                 httpx.WriteError,
@@ -4119,8 +4073,8 @@ class LlamaCppBackend:
 
     @staticmethod
     def _parse_tool_calls_from_text(content: str) -> list[dict]:
-        """Thin wrapper around the shared parser in tool_call_parser
-        so safetensors and llama_cpp pick up the same fixes."""
+        """Thin wrapper around the shared tool_call_parser so safetensors
+        and llama_cpp pick up the same fixes."""
         return _shared_parse_tool_calls_from_text(content)
 
     @staticmethod
@@ -4129,12 +4083,12 @@ class LlamaCppBackend:
         Build OpenAI-format messages, optionally injecting an image_url
         content part into the last user message for vision models.
 
-        If no image is provided, returns messages as-is.
+        Returns messages as-is if no image is provided.
         """
         if not image_b64:
             return messages
 
-        # Find the last user message and convert to multimodal content parts
+        # Convert the last user message to multimodal content parts
         result = [msg.copy() for msg in messages]
         last_user_idx = None
         for i, msg in enumerate(result):
@@ -4163,11 +4117,11 @@ class LlamaCppBackend:
     ) -> Generator[str, None, None]:
         """Iterate over an httpx streaming response with cancel support.
 
-        Checks cancel_event between chunks and on ReadTimeout.  The
-        cancel watcher in _stream_with_retry also calls response.close()
-        on cancel, which unblocks iter_text() once the response exists.
-        During normal streaming llama-server sends tokens frequently,
-        so the cancel check between chunks is the primary mechanism.
+        Checks cancel_event between chunks and on ReadTimeout. The cancel
+        watcher in _stream_with_retry also calls response.close() on cancel,
+        unblocking iter_text() once the response exists. During normal
+        streaming llama-server sends tokens frequently, so the between-chunk
+        check is the primary mechanism.
         """
         text_iter = response.iter_text()
         while True:
@@ -4180,8 +4134,8 @@ class LlamaCppBackend:
             except StopIteration:
                 return
             except httpx.ReadTimeout:
-                # No data within the timeout window -- just loop back
-                # and re-check cancel_event.
+                # No data within the timeout window -- loop back and re-check
+                # cancel_event.
                 continue
 
     @staticmethod
@@ -4195,21 +4149,18 @@ class LlamaCppBackend:
     ):
         """Open an httpx streaming POST with cancel support.
 
-        Sends the request once with a long read timeout (120 s) so
-        prompt processing (prefill) can finish without triggering a
-        retry storm.  The previous 0.5 s timeout caused duplicate POST
-        requests every half second, forcing llama-server to restart
-        processing each time.
+        Sends the request once with a long read timeout (120 s) so prefill
+        (prompt processing) can finish without a retry storm. The previous
+        0.5 s timeout caused duplicate POSTs every half second, forcing
+        llama-server to restart processing each time.
 
-        A background watcher thread provides cancel by closing the
-        response when cancel_event is set.  Limitation: httpx does not
-        allow interrupting a blocked read from another thread before
-        the response object exists, so cancel during the initial
-        header wait (prefill phase) only takes effect once headers
-        arrive.  After that, response.close() unblocks reads promptly.
-        In practice llama-server prefill is 1-5 s for typical prompts,
-        during which cancel is deferred -- still much better than the
-        old retry storm which made prefill slower.
+        A background watcher thread cancels by closing the response when
+        cancel_event is set. Limitation: httpx can't interrupt a blocked
+        read from another thread before the response object exists, so
+        cancel during the initial header wait (prefill) only takes effect
+        once headers arrive; after that response.close() unblocks reads
+        promptly. Prefill is 1-5 s for typical prompts, during which cancel
+        is deferred -- still much better than the old retry storm.
         """
         if cancel_event is not None and cancel_event.is_set():
             raise GeneratorExit
@@ -4222,9 +4173,9 @@ class LlamaCppBackend:
         def _cancel_watcher():
             while not _cancel_closed.is_set():
                 if cancel_event.wait(timeout = 0.3):
-                    # Cancel requested. Keep polling until the response object
-                    # exists so we can close it, or until the main thread
-                    # finishes on its own (_cancel_closed is set in finally).
+                    # Cancel requested. Poll until the response object exists
+                    # so we can close it, or until the main thread finishes
+                    # (_cancel_closed set in finally).
                     while not _cancel_closed.is_set():
                         r = _response_ref[0]
                         if r is not None:
@@ -4243,10 +4194,9 @@ class LlamaCppBackend:
             watcher.start()
 
         try:
-            # Long read timeout so prefill (prompt processing) can finish
-            # without triggering a retry storm.  Cancel during both
-            # prefill and streaming is handled by the watcher thread
-            # which closes the response, unblocking any httpx read.
+            # Long read timeout so prefill can finish without a retry storm.
+            # Cancel during prefill and streaming is handled by the watcher
+            # thread closing the response, unblocking any httpx read.
             prefill_timeout = httpx.Timeout(
                 connect = 30,
                 read = 120.0,
@@ -4291,10 +4241,10 @@ class LlamaCppBackend:
         preserve_thinking: Optional[bool] = None,
     ) -> Generator[str | dict, None, None]:
         """
-        Send a chat completion request to llama-server and stream tokens back.
+        Send a chat completion to llama-server and stream tokens back.
 
-        Uses /v1/chat/completions — llama-server handles chat template
-        application and vision (multimodal image_url parts) natively.
+        Uses /v1/chat/completions -- llama-server applies the chat template
+        and handles vision (multimodal image_url parts) natively.
 
         Yields cumulative text (matching InferenceBackend's convention).
         """
@@ -4313,15 +4263,14 @@ class LlamaCppBackend:
             "repeat_penalty": repetition_penalty,
             "presence_penalty": presence_penalty,
         }
-        # Pass enable_thinking / reasoning_effort / preserve_thinking per-request
+        # Per-request enable_thinking / reasoning_effort / preserve_thinking
         _reasoning_kw = self._request_reasoning_kwargs(
             enable_thinking, reasoning_effort, preserve_thinking
         )
         if _reasoning_kw is not None:
             payload["chat_template_kwargs"] = _reasoning_kw
-        # Default cap to the model's effective context length when known,
-        # otherwise the conservative floor. The wall-clock backstop below
-        # keeps a stuck model from running indefinitely either way.
+        # Cap to the effective context length when known, else the floor.
+        # The wall-clock backstop below stops a stuck model regardless.
         payload["max_tokens"] = (
             max_tokens
             if max_tokens is not None
@@ -4340,9 +4289,9 @@ class LlamaCppBackend:
         _metadata_timings = None
 
         try:
-            # _stream_with_retry uses a 120 s read timeout so prefill
-            # can finish.  Cancel during streaming is handled by the
-            # watcher thread (closes the response on cancel_event).
+            # _stream_with_retry uses a 120 s read timeout so prefill can
+            # finish. Cancel during streaming is handled by the watcher
+            # thread (closes the response on cancel_event).
             stream_timeout = httpx.Timeout(connect = 10, read = 0.5, write = 10, pool = 10)
             _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
             with httpx.Client(
@@ -4379,10 +4328,10 @@ class LlamaCppBackend:
                                         cumulative += "</think>"
                                         yield cumulative
                                     else:
-                                        # Only reasoning_content, no content tokens:
-                                        # the model put its entire reply in reasoning
-                                        # (e.g. Qwen3 always-think mode). Show it
-                                        # as the main response, not as a thinking block.
+                                        # Only reasoning_content, no content:
+                                        # model put its whole reply in reasoning
+                                        # (e.g. Qwen3 always-think). Show it as
+                                        # the main response, not a thinking block.
                                         cumulative = reasoning_text
                                         yield cumulative
                                 _stream_done = True
@@ -4392,7 +4341,7 @@ class LlamaCppBackend:
 
                             try:
                                 data = json.loads(line[6:])
-                                # Capture server timings/usage from final chunks
+                                # Capture server timings/usage from final chunks.
                                 _chunk_timings = data.get("timings")
                                 if _chunk_timings:
                                     _metadata_timings = _chunk_timings
@@ -4403,9 +4352,9 @@ class LlamaCppBackend:
                                 if choices:
                                     delta = choices[0].get("delta", {})
 
-                                    # Handle reasoning/thinking tokens
-                                    # llama-server sends these as "reasoning_content"
-                                    # Wrap in <think> tags for the frontend parser
+                                    # Reasoning/thinking tokens: llama-server
+                                    # sends these as "reasoning_content"; wrap
+                                    # in <think> tags for the frontend parser.
                                     reasoning = delta.get("reasoning_content", "")
                                     if reasoning:
                                         reasoning_text += reasoning
@@ -4470,7 +4419,7 @@ class LlamaCppBackend:
         """
         Agentic loop: let the model call tools, execute them, and continue.
 
-        Yields dicts with:
+        Yields dicts:
           {"type": "status", "text": "Searching: ..."/"Reading: ..."}   -- tool status updates
           {"type": "content", "text": "token"}            -- streamed content tokens (cumulative)
           {"type": "reasoning", "text": "token"}          -- streamed reasoning tokens (cumulative)
@@ -4491,38 +4440,37 @@ class LlamaCppBackend:
                 return text
             return strip_tool_call_markup(text, final = final)
 
-        # XML prefixes that signal a tool call in content.
-        # Empty when auto_heal is disabled so the buffer never
-        # speculatively holds content for XML detection.
+        # XML prefixes that signal a tool call in content. Empty when
+        # auto_heal is disabled so the buffer never speculatively holds
+        # content for XML detection.
         _TOOL_XML_SIGNALS = ("<tool_call>", "<function=") if auto_heal_tool_calls else ()
         _MAX_BUFFER_CHARS = 32
 
         # ── Duplicate tool-call detection ────────────────────────
-        # Track recent (tool_name, arguments) hashes to detect loops
-        # where the model repeats the exact same call.  Retries after
-        # a transient failure are allowed (only block when the previous
-        # identical call succeeded).
+        # Track recent (tool_name, arguments) hashes to detect loops where
+        # the model repeats the exact same call. Retries after a transient
+        # failure are allowed (only block when the prior identical call
+        # succeeded).
         _tool_call_history: list[tuple[str, bool]] = []  # (key, failed)
         _render_html_succeeded = False
 
         # ── Re-prompt on plan-without-action ─────────────────
         # When the model describes what it intends to do (forward-looking
-        # language) without actually calling a tool, re-prompt once.
-        # Only triggers on responses that signal intent/planning -- a
-        # direct answer like "4" or "Hello!" will not match.
-        # Pattern is compiled once at module level (_INTENT_SIGNAL).
+        # language) without calling a tool, re-prompt once. Only triggers on
+        # responses signaling intent/planning -- a direct answer like "4" or
+        # "Hello!" won't match. Pattern compiled at module level
+        # (_INTENT_SIGNAL).
         _reprompt_count = 0
 
-        # Reserve extra iterations for re-prompts so they don't
-        # consume the caller's tool-call budget.  Only add the
-        # extra slot when tool iterations are actually allowed.
+        # Reserve extra iterations for re-prompts so they don't consume the
+        # caller's tool-call budget; only when tool iterations are allowed.
         _extra = _MAX_REPROMPTS if max_tool_iterations > 0 else 0
         for iteration in range(max_tool_iterations + _extra):
             if cancel_event is not None and cancel_event.is_set():
                 return
 
-            # Build payload -- stream: True so we detect tool signals
-            # in the first 1-2 chunks without a non-streaming penalty.
+            # stream: True so we detect tool signals in the first 1-2 chunks
+            # without a non-streaming penalty.
             payload = {
                 "messages": conversation,
                 "stream": True,
@@ -4556,9 +4504,9 @@ class LlamaCppBackend:
                 )
 
                 # ── Speculative buffer state machine ──────────────────
-                # BUFFERING: accumulating content, checking for tool signals
-                # STREAMING: no tool detected, yielding tokens to caller
-                # DRAINING:  tool signal found, silently consuming rest
+                # BUFFERING: accumulate content, check for tool signals
+                # STREAMING: no tool detected, yield tokens to caller
+                # DRAINING:  tool signal found, silently consume rest
                 _S_BUFFERING = 0
                 _S_STREAMING = 1
                 _S_DRAINING = 2
@@ -4567,7 +4515,7 @@ class LlamaCppBackend:
                 content_buffer = ""  # Raw content held during BUFFERING
                 content_accum = ""  # All content tokens (for tool parsing)
                 reasoning_accum = ""
-                cumulative_display = ""  # Cumulative text yielded (with <think>)
+                cumulative_display = ""  # Cumulative yielded text (with <think>)
                 in_thinking = False
                 has_content_tokens = False
                 tool_calls_acc = {}  # Structured delta.tool_calls fragments
@@ -4655,8 +4603,8 @@ class LlamaCppBackend:
                                     tc_deltas = delta.get("tool_calls")
                                     if tc_deltas:
                                         # Once visible content has been
-                                        # emitted, do not reclassify this
-                                        # turn as a tool call.
+                                        # emitted, don't reclassify this turn
+                                        # as a tool call.
                                         if _last_emitted:
                                             continue
                                         has_structured_tc = True
@@ -4673,8 +4621,8 @@ class LlamaCppBackend:
                                                     },
                                                 }
                                             elif tc_d.get("id"):
-                                                # Update ID if real one
-                                                # arrives on a later delta
+                                                # Update ID if a real one
+                                                # arrives on a later delta.
                                                 tool_calls_acc[idx]["id"] = tc_d["id"]
                                             func = tc_d.get("function", {})
                                             if func.get("name"):
@@ -4712,10 +4660,10 @@ class LlamaCppBackend:
                                         continue
 
                                     # ── Reasoning tokens ──
-                                    # Only yield in STREAMING state. In BUFFERING
-                                    # and DRAINING, accumulate silently so we don't
+                                    # Yield only in STREAMING. In BUFFERING and
+                                    # DRAINING, accumulate silently so we don't
                                     # corrupt the consumer's prev_text tracker
-                                    # (routes/inference.py never resets prev_text
+                                    # (routes/inference.py never resets it
                                     # between tool iterations).
                                     reasoning = delta.get("reasoning_content", "")
                                     if reasoning:
@@ -4760,7 +4708,7 @@ class LlamaCppBackend:
                                             if not stripped_buf:
                                                 continue
 
-                                            # Check tool signal prefixes
+                                            # Check tool signal prefixes.
                                             is_prefix = False
                                             is_match = False
                                             for sig in _TOOL_XML_SIGNALS:
@@ -4780,8 +4728,8 @@ class LlamaCppBackend:
                                             else:
                                                 # Not a tool -- flush buffer
                                                 detect_state = _S_STREAMING
-                                                # Flush any reasoning accumulated
-                                                # during BUFFERING phase
+                                                # Flush reasoning accumulated
+                                                # during BUFFERING.
                                                 if reasoning_accum:
                                                     cumulative_display += "<think>"
                                                     cumulative_display += reasoning_accum
@@ -4814,7 +4762,7 @@ class LlamaCppBackend:
                     elif content_accum or reasoning_accum:
                         detect_state = _S_STREAMING
                         if content_buffer:
-                            # Flush any reasoning accumulated first
+                            # Flush reasoning first.
                             if reasoning_accum:
                                 cumulative_display += "<think>"
                                 cumulative_display += reasoning_accum
@@ -4828,9 +4776,8 @@ class LlamaCppBackend:
                                 ),
                             }
                         elif reasoning_accum and not has_content_tokens:
-                            # Reasoning-only response (no content tokens):
-                            # show reasoning as plain text, matching
-                            # the final streaming pass behavior for
+                            # Reasoning-only response: show reasoning as plain
+                            # text, matching the final streaming pass for
                             # models that put everything in reasoning.
                             cumulative_display = reasoning_accum
                             yield {
@@ -4842,10 +4789,10 @@ class LlamaCppBackend:
 
                 # ── STREAMING path: no tool call ──
                 if detect_state == _S_STREAMING:
-                    # Safety net: check for XML tool signals in content.
-                    # The route layer resets prev_text on tool_start, so
-                    # post-tool synthesis streams correctly even if
-                    # content was already emitted before the tool XML.
+                    # Safety net: check for XML tool signals in content. The
+                    # route layer resets prev_text on tool_start, so post-tool
+                    # synthesis streams correctly even if content was emitted
+                    # before the tool XML.
                     _safety_tc = None
                     if auto_heal_tool_calls and any(s in content_accum for s in _TOOL_XML_SIGNALS):
                         _safety_tc = self._parse_tool_calls_from_text(
@@ -4853,14 +4800,12 @@ class LlamaCppBackend:
                         )
                     if not _safety_tc:
                         # ── Re-prompt on plan-without-action ──
-                        # If the model described what it intends to do
-                        # (forward-looking language) without calling any
-                        # tool, nudge it to act.  Only fires once per
-                        # request and only on short responses that
-                        # contain intent signals -- a direct answer
-                        # like "4" or "Hello!" won't trigger this.
-                        # Use content if available, otherwise fall back
-                        # to reasoning text (reasoning-only stalls).
+                        # If the model described its intent (forward-looking
+                        # language) without calling a tool, nudge it to act.
+                        # Fires at most once per request, only on short
+                        # responses with intent signals -- "4" or "Hello!"
+                        # won't trigger it. Use content if available, else
+                        # fall back to reasoning text (reasoning-only stalls).
                         _stripped = content_accum.strip()
                         if not _stripped:
                             _stripped = reasoning_accum.strip()
@@ -4899,7 +4844,7 @@ class LlamaCppBackend:
                                     ),
                                 }
                             )
-                            # Accumulate tokens and timing from this iteration
+                            # Accumulate tokens and timing from this iteration.
                             _fu_r = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
                             _accumulated_completion_tokens += _fu_r.get("completion_tokens", 0)
                             _it_r = _iter_timings or {}
@@ -4908,7 +4853,7 @@ class LlamaCppBackend:
                             yield {"type": "status", "text": ""}
                             continue
 
-                        # Content was already streamed.  Yield metadata.
+                        # Content already streamed; yield metadata.
                         yield {"type": "status", "text": ""}
                         _fu = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
                         _fc = _fu.get("completion_tokens", 0)
@@ -4936,7 +4881,7 @@ class LlamaCppBackend:
                             }
                         return
 
-                    # Safety net caught tool XML -- treat as tool call
+                    # Safety net caught tool XML -- treat as tool call.
                     tool_calls = _safety_tc
                     content_text = _strip_tool_markup(
                         content_accum,
@@ -4951,8 +4896,8 @@ class LlamaCppBackend:
                     tool_calls = None
                     content_text = content_accum
                     if has_structured_tc:
-                        # Filter out incomplete fragments (e.g. from
-                        # truncation by max_tokens or disconnect).
+                        # Drop incomplete fragments (e.g. from max_tokens
+                        # truncation or disconnect).
                         tool_calls = [
                             tool_calls_acc[i]
                             for i in sorted(tool_calls_acc)
@@ -4977,12 +4922,12 @@ class LlamaCppBackend:
                             f"{'structured delta' if has_structured_tc else 'content text'}"
                         )
                     if not tool_calls:
-                        # DRAINING but no tool calls (false positive).
-                        # Merge accumulated metrics from prior tool
-                        # iterations so they are not silently dropped.
+                        # DRAINING but no tool calls (false positive). Merge
+                        # accumulated metrics from prior tool iterations so
+                        # they aren't silently dropped.
                         yield {"type": "status", "text": ""}
                         if content_accum:
-                            # Strip leaked tool-call XML before yielding
+                            # Strip leaked tool-call XML before yielding.
                             content_accum = _strip_tool_markup(content_accum, final = True)
                         if content_accum:
                             yield {"type": "content", "text": content_accum}
@@ -5083,7 +5028,7 @@ class LlamaCppBackend:
                         }
 
                     # ── Duplicate call detection ──────────────
-                    # str(dict) is stable here: arguments always comes from
+                    # str(dict) is stable here: arguments always come from
                     # json.loads on the same model output within one request,
                     # so insertion order is deterministic (Python 3.7+).
                     _tc_key = tool_name + str(arguments)
@@ -5103,11 +5048,10 @@ class LlamaCppBackend:
                         _effective_timeout = (
                             None if tool_call_timeout >= 9999 else tool_call_timeout
                         )
-                        # Guard against the model emitting a tool not in the
-                        # per-request advertised set: filtered MCP names, a
-                        # built-in the caller opted out of, or a stale name
-                        # from a prior turn. Mirrors the safetensors loop's
-                        # allowed_tool_names check.
+                        # Guard against a tool not in the per-request
+                        # advertised set: filtered MCP names, an opted-out
+                        # built-in, or a stale name from a prior turn. Mirrors
+                        # the safetensors loop's allowed_tool_names check.
                         _allowed = {
                             (t.get("function") or {}).get("name")
                             for t in (tools or [])
@@ -5136,7 +5080,7 @@ class LlamaCppBackend:
                             "result": result,
                         }
 
-                    # Nudge model to try a different approach on errors
+                    # Nudge the model toward a different approach on errors.
                     _error_prefixes = (
                         "Error",
                         "Search failed",
@@ -5153,8 +5097,8 @@ class LlamaCppBackend:
                     if tool_name == "render_html" and not _is_error:
                         _render_html_succeeded = True
                     _tool_call_history.append((_tc_key, _is_error))
-                    # Strip image sentinel before feeding result to the LLM
-                    # (the full result with sentinel is still yielded via
+                    # Strip image sentinel before feeding the result to the
+                    # LLM (the full result with sentinel is still yielded via
                     # tool_end so the frontend can extract image paths).
                     _result_content = result
                     if "\n__IMAGES__:" in _result_content:
@@ -5175,9 +5119,9 @@ class LlamaCppBackend:
                         tool_msg["tool_call_id"] = tool_call_id
                     conversation.append(tool_msg)
 
-                # Clear tool status badge before next generation iteration
+                # Clear tool status badge before the next generation.
                 yield {"type": "status", "text": ""}
-                # Continue the loop to let model respond with context
+                # Continue so the model responds with tool context.
                 continue
 
             except httpx.ConnectError:
@@ -5188,9 +5132,9 @@ class LlamaCppBackend:
                 raise
 
         # ── Tool iteration cap reached -- synthesize final answer ──
-        # The model used all iterations without producing a final text
-        # response. Inject a nudge so the final streaming pass produces
-        # a useful answer instead of continuing to request tools.
+        # The model used all iterations without a final text response. Nudge
+        # the final streaming pass to produce a useful answer instead of
+        # continuing to request tools.
         if max_tool_iterations > 0:
             conversation.append(
                 {
@@ -5203,10 +5147,10 @@ class LlamaCppBackend:
                 }
             )
 
-        # Clear status
+        # Clear status.
         yield {"type": "status", "text": ""}
 
-        # Final streaming pass with the full conversation context
+        # Final streaming pass with the full conversation context.
         stream_payload = {
             "messages": conversation,
             "stream": True,
@@ -5287,7 +5231,7 @@ class LlamaCppBackend:
 
                             try:
                                 chunk_data = json.loads(line[6:])
-                                # Capture server timings/usage from final chunks
+                                # Capture server timings/usage from final chunks.
                                 _chunk_timings = chunk_data.get("timings")
                                 if _chunk_timings:
                                     _metadata_timings = _chunk_timings
@@ -5315,7 +5259,7 @@ class LlamaCppBackend:
                                             in_thinking = False
                                         cumulative += token
                                         cleaned = _strip_tool_markup(cumulative)
-                                        # Only emit when cleaned text grows (monotonic).
+                                        # Emit only when cleaned text grows (monotonic).
                                         if len(cleaned) > len(_last_emitted):
                                             _last_emitted = cleaned
                                             yield {"type": "content", "text": cleaned}
@@ -5362,7 +5306,7 @@ class LlamaCppBackend:
     # ── TTS support ────────────────────────────────────────────
 
     def detect_audio_type(self) -> Optional[str]:
-        """Detect audio/TTS codec; swallows errors (use _strict variant to distinguish)."""
+        """Detect audio/TTS codec; swallows errors (use _strict to distinguish)."""
         try:
             return self._detect_audio_type_strict()
         except Exception as e:
@@ -5370,7 +5314,7 @@ class LlamaCppBackend:
             return None
 
     def _detect_audio_type_strict(self) -> Optional[str]:
-        """Codec name on match, None on definitive non-audio, raises on transport/JSON errors."""
+        """Codec name on match, None on non-audio, raises on transport/JSON errors."""
         if not self.is_loaded:
             return None
         _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
@@ -5393,7 +5337,7 @@ class LlamaCppBackend:
                     return []
                 return r.json().get("tokens", [])
 
-            # Check codec-specific tokens (not generic ones that may exist in non-audio models)
+            # Codec-specific tokens (not generic ones that non-audio models may have)
             if "<custom_token_" in _detok(128258) and "<custom_token_" in _detok(128259):
                 return "snac"
             if len(_tok("<|AUDIO|>")) == 1 and len(_tok("<|audio_eos|>")) == 1:
@@ -5409,8 +5353,8 @@ class LlamaCppBackend:
                 return "dac"
         return None
 
-    # Prompt format per codec: (template, stop_tokens, needs_token_ids)
-    # Matches prompts in InferenceBackend._generate_snac/bicodec/dac
+    # Prompt format per codec: (template, stop_tokens, needs_token_ids).
+    # Matches InferenceBackend._generate_snac/bicodec/dac.
     _TTS_PROMPTS = {
         "snac": (
             "<custom_token_3>{text}<|eot_id|><custom_token_4>",
@@ -5432,7 +5376,7 @@ class LlamaCppBackend:
     _codec_mgr = None  # Shared AudioCodecManager instance
 
     def init_audio_codec(self, audio_type: str) -> None:
-        """Load the audio codec at model load time (mirrors non-GGUF path)."""
+        """Load the audio codec at model load time (mirrors the non-GGUF path)."""
         import torch
         from core.inference.audio_codecs import AudioCodecManager
 
@@ -5442,7 +5386,7 @@ class LlamaCppBackend:
         device = "cuda" if torch.cuda.is_available() else "cpu"
         model_repo_path = None
 
-        # BiCodec needs a repo with BiCodec/ weights — download canonical SparkTTS
+        # BiCodec needs a repo with BiCodec/ weights -- download canonical SparkTTS
         if audio_type == "bicodec":
             from huggingface_hub import snapshot_download
             import os
@@ -5465,7 +5409,7 @@ class LlamaCppBackend:
         repetition_penalty: float = 1.1,
     ) -> tuple:
         """
-        Generate TTS audio via llama-server /completion + codec decoding.
+        Generate TTS audio via llama-server /completion + codec decode.
         Returns (wav_bytes, sample_rate).
         """
         if audio_type not in self._TTS_PROMPTS:
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index 66cd138d99..9d11157bf9 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -3,11 +3,10 @@
 
 """Boundary validator for user-supplied llama-server pass-through args.
 
-Reject only flags Studio manages (model identity, auth, network,
-parallel slots). Everything else (sampling, ``-c``, ``-ngl``,
-``--flash-attn``, ``--cache-type-*``, ``--spec-*``, ``--jinja``, ...)
-is appended after Studio's auto-set flags so llama.cpp's last-wins
-parser lets the user override.
+Reject only flags Studio manages (model identity, auth, network, parallel
+slots). Everything else (sampling, ``-c``, ``-ngl``, ``--flash-attn``,
+``--cache-type-*``, ``--spec-*``, ``--jinja``, ...) is appended after
+Studio's auto-set flags so llama.cpp's last-wins parser lets the user override.
 
 Ref: https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
 """
@@ -19,11 +18,11 @@ from typing import Iterable, Optional
 # Each group = every alias (short + long) of one hard-denied flag.
 # Extend the matching group when llama.cpp adds a new alias.
 _DENYLIST_GROUPS: tuple[frozenset[str], ...] = (
-    # Parallel slots: owned by typer --parallel; a pass-through would
-    # desync app.state.llama_parallel_slots from llama-server.
+    # Parallel slots: owned by typer --parallel; a pass-through would desync
+    # app.state.llama_parallel_slots from llama-server.
     frozenset({"-np", "--parallel", "--n-parallel"}),
-    # Model identity: Studio resolves it from LoadRequest; a second
-    # -m would load a different model than Studio thinks it loaded.
+    # Model identity: Studio resolves it from LoadRequest; a second -m would
+    # load a different model than Studio thinks it loaded.
     frozenset({"-m", "--model"}),
     frozenset({"-mu", "--model-url"}),
     frozenset({"-dr", "--docker-repo"}),
@@ -40,15 +39,15 @@ _DENYLIST_GROUPS: tuple[frozenset[str], ...] = (
     frozenset({"--path"}),
     frozenset({"--api-prefix"}),
     frozenset({"--reuse-port"}),
-    # Auth / TLS: Studio terminates auth; upstream --api-key / TLS
-    # shadows Studio's key and breaks the proxy hop.
+    # Auth / TLS: Studio terminates auth; upstream --api-key / TLS shadows
+    # Studio's key and breaks the proxy hop.
     frozenset({"--api-key"}),
     frozenset({"--api-key-file"}),
     frozenset({"--ssl-key-file"}),
     frozenset({"--ssl-cert-file"}),
-    # Built-in web UI. --webui/--no-webui is the legacy spelling;
-    # upstream renamed to --ui/--no-ui + --ui-*. Keep both so prebuilt
-    # and system llama.cpp binaries both match.
+    # Built-in web UI. --webui/--no-webui is the legacy spelling; upstream
+    # renamed to --ui/--no-ui + --ui-*. Keep both so prebuilt and system
+    # llama.cpp binaries match.
     frozenset({"--webui", "--no-webui"}),
     frozenset({"--ui", "--no-ui"}),
     frozenset({"--ui-config"}),
@@ -62,8 +61,8 @@ _DENYLIST_GROUPS: tuple[frozenset[str], ...] = (
     # those endpoints, breaking Studio's /v1/chat/completions hop.
     frozenset({"--embedding", "--embeddings"}),
     frozenset({"--rerank", "--reranking"}),
-    # llama-server's own built-in tools flag would silently stack on top
-    # of Studio's --enable-tools / --disable-tools policy resolver.
+    # llama-server's own built-in tools flag would silently stack on top of
+    # Studio's --enable-tools / --disable-tools policy resolver.
     frozenset({"--tools"}),
 )
 
@@ -74,10 +73,9 @@ def _flag_name(token: str) -> Optional[str]:
     """Flag name for ``token``, or None if it isn't a flag.
 
     Peels `--key=value` to `--key`, treats `-1` / `-0.5` as values
-    (llama-server shorts always start with a letter), strips
-    whitespace, and normalises attached `-np8` / signed `-np-1` /
-    digit-prefix-junk `-np8x` to `-np`. Mirrors the CLI's
-    `_expand_attached_np_short`.
+    (llama-server shorts always start with a letter), strips whitespace, and
+    normalises attached `-np8` / signed `-np-1` / digit-prefix-junk `-np8x`
+    to `-np`. Mirrors the CLI's `_expand_attached_np_short`.
     """
     token = token.strip()
     if not token.startswith("-") or token in {"-", "--"}:
@@ -95,9 +93,9 @@ def _flag_name(token: str) -> Optional[str]:
 
 
 def validate_extra_args(args: Optional[Iterable[str]]) -> list[str]:
-    """Validate user-supplied llama-server args. Returns a flat list
-    ready to extend the llama-server command; raises ``ValueError``
-    naming the offending flag on the first managed token."""
+    """Validate user-supplied llama-server args. Returns a flat list ready to
+    extend the llama-server command; raises ``ValueError`` naming the
+    offending flag on the first managed token."""
     if not args:
         return []
     out: list[str] = []
@@ -116,15 +114,15 @@ def validate_extra_args(args: Optional[Iterable[str]]) -> list[str]:
 
 
 def is_managed_flag(flag: str) -> bool:
-    """True if ``flag`` is Studio-managed. Normalises via ``_flag_name``
-    so `-np8` / `--parallel=8` classify like the canonical tokens."""
+    """True if ``flag`` is Studio-managed. Normalises via ``_flag_name`` so
+    `-np8` / `--parallel=8` classify like the canonical tokens."""
     normalised = _flag_name(flag)
     return normalised is not None and normalised in _DENYLIST
 
 
-# Pass-through flags that shadow first-class LoadRequest fields;
-# stripped from inherited extras so they can't last-wins-override an
-# Apply that re-sets the same field.
+# Pass-through flags that shadow first-class LoadRequest fields; stripped
+# from inherited extras so they can't last-wins-override an Apply that
+# re-sets the same field.
 _CONTEXT_FLAGS: frozenset[str] = frozenset({"-c", "--ctx-size"})
 _CACHE_FLAGS: frozenset[str] = frozenset({"-ctk", "--cache-type-k", "-ctv", "--cache-type-v"})
 _SPEC_FLAGS: frozenset[str] = frozenset(
@@ -157,16 +155,15 @@ _TEMPLATE_FLAGS: frozenset[str] = frozenset(
 
 _SHADOWING_FLAGS: frozenset[str] = _CONTEXT_FLAGS | _CACHE_FLAGS | _SPEC_FLAGS | _TEMPLATE_FLAGS
 
-# Shadowing flags that take no value -- strip the flag only, never the
-# following token.
+# Shadowing flags that take no value -- strip the flag only, not the next token.
 _BOOLEAN_SHADOWING_FLAGS: frozenset[str] = frozenset({"--spec-default", "--jinja", "--no-jinja"})
 
 
 def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
     """Return the last user-supplied ``-c`` / ``--ctx-size`` value.
 
-    Mirrors llama.cpp's last-wins flag parsing for the one pass-through
-    numeric knob Studio's load-time fit logic needs to see.
+    Mirrors llama.cpp's last-wins parsing for the one pass-through numeric
+    knob Studio's load-time fit logic needs to see.
     """
     if not args:
         return None
@@ -204,10 +201,10 @@ def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
 def resolve_requested_ctx(args: Optional[Iterable[str]], fallback_n_ctx: int) -> int:
     """Return the context size load_model should treat as requested.
 
-    Single source of truth for the two-line ``ctx_override = parse_ctx_override(...);
-    requested_ctx = ctx_override if ctx_override is not None else n_ctx`` pattern
-    used by ``load_model`` so tests don't have to reimplement the conditional
-    locally and then assert against their own reimplementation.
+    Single source of truth for the ``ctx_override = parse_ctx_override(...);
+    requested_ctx = ctx_override if ctx_override is not None else n_ctx``
+    pattern used by ``load_model``, so tests don't reimplement the
+    conditional and assert against their own reimplementation.
     """
     override = parse_ctx_override(args)
     return override if override is not None else fallback_n_ctx
@@ -216,10 +213,10 @@ def resolve_requested_ctx(args: Optional[Iterable[str]], fallback_n_ctx: int) ->
 def parse_cache_override(args: Optional[Iterable[str]]) -> Optional[str]:
     """Return the last-wins cache type if extras pass cache flags.
 
-    Mirrors parse_ctx_override but for cache type. Recognises both -ctk
-    (key) and -ctv (value). When both flags appear, returns the last-wins
-    value, treating key and value cache flags as the same setting because
-    Studio's KV estimate has a single cache_type_kv knob.
+    Like parse_ctx_override but for cache type. Recognises -ctk (key) and
+    -ctv (value); when both appear, returns the last-wins value, treating
+    key and value flags as one setting because Studio's KV estimate has a
+    single cache_type_kv knob.
     """
     if not args:
         return None
@@ -256,8 +253,7 @@ def resolve_cache_type_kv(
 ) -> Optional[str]:
     """Return the cache type load_model should treat as requested.
 
-    Single source of truth for the cache override conditional used by
-    ``load_model``.
+    Single source of truth for ``load_model``'s cache override conditional.
     """
     override = parse_cache_override(args)
     return override if override is not None else fallback_cache_type_kv
@@ -274,10 +270,9 @@ def strip_shadowing_flags(
     """Strip flags that shadow first-class Studio settings.
 
     Used when inheriting a previous load's ``llama_extra_args`` so an
-    inherited `-c 4096` can't override the current `max_seq_length`
-    (same for cache / spec / template). Each ``strip_*`` toggle
-    controls one group; the route only strips groups whose first-class
-    field the caller actually supplied.
+    inherited `-c 4096` can't override the current `max_seq_length` (same for
+    cache / spec / template). Each ``strip_*`` toggle controls one group; the
+    route only strips groups whose first-class field the caller supplied.
     """
     shadowing: set[str] = set()
     if strip_context:
@@ -299,8 +294,8 @@ def strip_shadowing_flags(
             out.append(tok)
             i += 1
             continue
-        # Drop the flag; consume the next token too unless it's
-        # boolean, already inline (`-c=4096`), or another flag.
+        # Drop the flag; also consume the next token unless it's boolean,
+        # already inline (`-c=4096`), or another flag.
         if flag in _BOOLEAN_SHADOWING_FLAGS or "=" in tok:
             i += 1
         elif i + 1 < n and _flag_name(tokens[i + 1]) is None:
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index ad5f67f325..d1a565b232 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -31,20 +31,20 @@ def parse_stdio_command(address: str) -> list[str]:
     posix = sys.platform != "win32"
     parts = shlex.split(address, posix = posix)
     if not posix:
-        # posix=False keeps backslash paths intact but also keeps the surrounding
-        # quotes on a token. Strip a matched pair so the argv reaches the
-        # subprocess clean ('"C:\\Program Files\\node"' -> C:\\Program Files\\node).
+        # posix=False keeps backslash paths intact but also keeps surrounding
+        # quotes on a token. Strip a matched pair so argv reaches the subprocess
+        # clean ('"C:\\Program Files\\node"' -> C:\\Program Files\\node).
         parts = [p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p for p in parts]
     return parts
 
 
 def stdio_mcp_enabled() -> bool:
-    """stdio MCP servers spawn local processes as the backend user (and bypass
-    the python/terminal sandbox), so they are only allowed when the backend
-    host is the user's own machine. The Tauri desktop app sets
+    """stdio MCP servers spawn local processes as the backend user (bypassing
+    the python/terminal sandbox), so they're allowed only when the backend host
+    is the user's own machine. The Tauri desktop app sets
     UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 (see main.py); advanced localhost /
-    self-hosted users can opt in with the same variable. It stays off for
-    Colab and any network (0.0.0.0) bind."""
+    self-hosted users can opt in with the same variable. Stays off for Colab
+    and any network (0.0.0.0) bind."""
     return os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") == "1"
 
 
@@ -63,8 +63,8 @@ def probe_timeout(address: str, use_oauth: bool) -> float:
 
 
 def parse_server_headers(server: dict) -> Optional[dict]:
-    """Parsed headers_json. For stdio servers this dict is the process
-    environment instead of HTTP headers (see _client)."""
+    """Parsed headers_json. For stdio servers this dict is the process env
+    instead of HTTP headers (see _client)."""
     raw = server.get("headers_json")
     if not raw:
         return None
@@ -83,7 +83,7 @@ def _oauth_store():
         from utils.paths.storage_roots import ensure_dir, studio_root
 
         # Hash keys/collections — fastmcp uses raw URLs like https://x.com as
-        # keys and FileTreeStore would treat the "://" as nested directories.
+        # keys, and FileTreeStore would treat the "://" as nested directories.
         _oauth_token_store = FileTreeStore(
             data_directory = ensure_dir(studio_root() / "mcp-oauth-tokens"),
             key_sanitization_strategy = AlwaysHashStrategy(),
@@ -93,12 +93,11 @@ def _oauth_store():
 
 
 async def clear_oauth_tokens_async(url: str) -> None:
-    """Drop any persisted OAuth tokens for ``url``. fastmcp keys tokens by
-    MCP URL, so on server delete / URL change / OAuth disable we have to
-    clear the old credentials explicitly. Otherwise re-registering the
-    same URL would silently reuse the old account's token. The entire
-    body runs inside the protected block -- store / OAuth construction
-    failing must not make the delete / update route 500."""
+    """Drop any persisted OAuth tokens for ``url``. fastmcp keys tokens by MCP
+    URL, so on server delete / URL change / OAuth disable we must clear old
+    credentials explicitly; otherwise re-registering the same URL silently
+    reuses the old account's token. The whole body is protected -- store / OAuth
+    construction failing must not 500 the delete / update route."""
     try:
         from fastmcp.client.auth import OAuth
         auth = OAuth(mcp_url = url, token_storage = _oauth_store())
@@ -124,9 +123,9 @@ def _client(
         parts = parse_stdio_command(url)
         if not parts:
             raise ValueError(f"Empty stdio command: {url!r}")
-        # env vars ride the headers field (merged over the SDK's safe default env).
-        # keep_alive=False tears the subprocess down on exit, so a one-shot
-        # probe/tool call never leaves an orphan process.
+        # env vars ride the headers field (merged over the SDK's safe default
+        # env). keep_alive=False tears the subprocess down on exit, so a
+        # one-shot probe/tool call never leaves an orphan.
         return Client(
             StdioTransport(
                 command = parts[0],
@@ -192,10 +191,10 @@ def call_tool_sync(
 ) -> str:
     """Synchronously call an MCP tool.
 
-    ``cancel_event``: optional ``threading.Event``. When set, the in-flight
-    HTTP call is cancelled and the function returns a cancellation Error.
-    Polled in parallel with the tool call via ``asyncio.wait`` so a /cancel
-    POST from the UI interrupts even mid-network-read.
+    ``cancel_event``: optional ``threading.Event``. When set, the in-flight HTTP
+    call is cancelled and a cancellation Error is returned. Polled in parallel
+    with the tool call via ``asyncio.wait`` so a /cancel POST from the UI
+    interrupts even mid-network-read.
     """
 
     async def _call() -> Any:
@@ -204,14 +203,14 @@ def call_tool_sync(
 
     async def _watch_cancel() -> None:
         # 50 ms cadence keeps cancellation responsive without busy-looping;
-        # matches the cadence routes/inference.py uses for cancel watchers.
+        # matches routes/inference.py's cancel watcher cadence.
         while cancel_event is not None and not cancel_event.is_set():
             await asyncio.sleep(0.05)
 
     async def _race() -> Any:
-        # Check cancellation before spawning the call task so a pre-set
-        # event short-circuits before opening the transport / HTTP
-        # connection (reviewer-reproduced race).
+        # Check cancellation before spawning the call task so a pre-set event
+        # short-circuits before opening the transport / HTTP connection
+        # (reviewer-reproduced race).
         if cancel_event is not None and cancel_event.is_set():
             raise _MCPCancelled
         call_task = asyncio.create_task(_call())
diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index 5913c29282..31bca0f5d6 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -65,10 +65,10 @@ class MLXInferenceBackend:
     def _configure_memory_limits(self):
         """Apply Metal memory caps before loading a model.
 
-        Mirrors MLXTrainer._configure_memory_limits's defaults:
+        Mirrors MLXTrainer._configure_memory_limits defaults:
         memory_limit = 85% of recommended working-set,
-        wired_limit = min(recommended, memory_limit). Recorded so unload
-        can lower wired_limit back to release pinned RAM.
+        wired_limit = min(recommended, memory_limit). Recorded so unload can
+        lower wired_limit back to release pinned RAM.
         """
         import mlx.core as mx
 
@@ -109,18 +109,16 @@ class MLXInferenceBackend:
         model_name = config.identifier if hasattr(config, "identifier") else str(config)
         is_vision = getattr(config, "is_vision", False)
 
-        # GGUF guard. GGUF models are served via llama-server in the
-        # parent process, NOT via mlx-lm in this MLX subprocess. The
-        # route at studio/backend/routes/inference.py:592 (`if config.
-        # is_gguf:`) is responsible for sending GGUF traffic to the
-        # llama-server backend before reaching the MLX orchestrator.
-        # If we end up here with is_gguf=True, the route's
-        # `detect_gguf_model_remote` returned None on its first call
-        # (transient HF Hub flake) but the subprocess re-detection
-        # succeeded. The subprocess cannot reach into the parent's
-        # llama-server, so all we can do is raise loudly so the caller
-        # gets a clear error instead of a cryptic
-        # "config.json does not exist" from mlx_lm.utils.load_model.
+        # GGUF guard. GGUF models are served via llama-server in the parent
+        # process, NOT via mlx-lm in this MLX subprocess. The route at
+        # studio/backend/routes/inference.py:592 (`if config.is_gguf:`) sends
+        # GGUF traffic to llama-server before reaching the MLX orchestrator.
+        # Reaching here with is_gguf=True means the route's
+        # `detect_gguf_model_remote` returned None on its first call (transient
+        # HF Hub flake) but the subprocess re-detection succeeded. The
+        # subprocess can't reach the parent's llama-server, so raise loudly to
+        # give the caller a clear error instead of a cryptic "config.json does
+        # not exist" from mlx_lm.utils.load_model.
         if getattr(config, "is_gguf", False):
             raise RuntimeError(
                 f"MLXInferenceBackend cannot load GGUF model '{model_name}': "
@@ -187,9 +185,9 @@ class MLXInferenceBackend:
             "audio_type": None,
             "has_audio_input": False,
         }
-        # Capture chat_template_info so the worker IPC reply can ship
-        # it back to the parent and the route layer classifies
-        # capabilities the same way as the transformers / GGUF paths.
+        # Capture chat_template_info so the worker IPC reply can ship it back
+        # to the parent and the route layer classifies capabilities the same
+        # way as the transformers / GGUF paths.
         self._populate_chat_template_info(model_name)
 
         logger.info("Model %s loaded successfully", model_name)
@@ -198,10 +196,9 @@ class MLXInferenceBackend:
     def _populate_chat_template_info(self, model_name: str) -> None:
         """Mirror InferenceBackend._load_chat_template_info for MLX.
 
-        Stores ``chat_template_info`` on ``self.models[model_name]``
-        with the resolved ``tokenizer.chat_template`` so
-        ``_detect_safetensors_features`` (route layer) sees the same
-        template the model actually uses."""
+        Stores ``chat_template_info`` on ``self.models[model_name]`` with the
+        resolved ``tokenizer.chat_template`` so ``_detect_safetensors_features``
+        (route layer) sees the template the model actually uses."""
         entry = self.models.get(model_name)
         if not entry:
             return
@@ -276,10 +273,9 @@ class MLXInferenceBackend:
         max_new_tokens = 256,
         repetition_penalty = 1.0,
         cancel_event = None,
-        # Reasoning / tool kwargs forwarded by the route + worker -- the
-        # MLX path renders the template via apply_chat_template_for_
-        # generation so these are honoured the same way as the
-        # transformers path.
+        # Reasoning / tool kwargs forwarded by the route + worker -- the MLX
+        # path renders the template via apply_chat_template_for_generation so
+        # these are honoured the same way as the transformers path.
         tools = None,
         enable_thinking = None,
         reasoning_effort = None,
@@ -308,7 +304,7 @@ class MLXInferenceBackend:
                             {"type": "text", "text": content},
                         ]
                     elif isinstance(content, list):
-                        # Prepend image if not already there
+                        # Prepend image if not already present
                         has_image = any(
                             p.get("type") == "image" for p in content if isinstance(p, dict)
                         )
@@ -389,8 +385,8 @@ class MLXInferenceBackend:
             min_p = float(min_p or 0.0),
             min_tokens_to_keep = 1,
         )
-        # Only build a logits processor when we actually have a non-trivial
-        # repetition penalty (1.0 is the no-op value).
+        # Only build a logits processor for a non-trivial repetition penalty
+        # (1.0 is the no-op value).
         logits_processors = None
         if repetition_penalty is not None and float(repetition_penalty) not in (
             0.0,
@@ -425,7 +421,7 @@ class MLXInferenceBackend:
                 ):
                     final_response = response
                     token_ids.append(response.token)
-                    # Decode full sequence with skip_special_tokens — same as GPU
+                    # Decode full sequence with skip_special_tokens — like GPU
                     cumulative = self._tokenizer.decode(
                         token_ids,
                         skip_special_tokens = True,
@@ -471,10 +467,9 @@ class MLXInferenceBackend:
             apply_chat_template_for_generation,
         )
 
-        # Pick the chat-template-aware caller: processors that expose
-        # their own apply_chat_template + chat_template attr (e.g.
-        # Qwen2.5-VL) use it directly; otherwise fall back to the
-        # nested tokenizer.
+        # Pick the chat-template-aware caller: processors that expose their own
+        # apply_chat_template + chat_template attr (e.g. Qwen2.5-VL) use it
+        # directly; otherwise fall back to the nested tokenizer.
         chat_target = self._processor
         if (
             getattr(self._processor, "apply_chat_template", None) is None
@@ -492,8 +487,8 @@ class MLXInferenceBackend:
             preserve_thinking = preserve_thinking,
         )
 
-        # For VLM: always use mlx_vlm's stream_generate which handles
-        # pixel_values properly (passes None for text-only, image for VLM)
+        # For VLM: always use mlx_vlm's stream_generate, which handles
+        # pixel_values properly (None for text-only, image for VLM)
         images = [image] if image is not None else None
 
         cumulative = ""
@@ -503,8 +498,8 @@ class MLXInferenceBackend:
             image is not None,
         )
         # mlx_vlm.stream_generate forwards **kwargs into generate_step, which
-        # accepts temp/top_p/top_k/repetition_penalty (and builds the sampler
-        # + logits_processors internally). Pass them through.
+        # accepts temp/top_p/top_k/repetition_penalty (building the sampler +
+        # logits_processors internally). Pass them through.
         # NOTE: mlx_vlm.generate_step expects ``temperature=`` (long form) —
         # passing ``temp=`` silently falls into **kwargs and is ignored,
         # leaving generation stuck at the default 0.0 (greedy).
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 1c132c3f52..d7fc1ef9a6 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -4,13 +4,12 @@
 """
 Inference orchestrator — subprocess-based.
 
-Provides the same API as InferenceBackend, but delegates all ML work
-to a persistent subprocess. The subprocess is spawned on first model load
-and stays alive for subsequent requests.
+Same API as InferenceBackend, but delegates all ML work to a persistent
+subprocess spawned on first model load and reused for later requests.
 
-When switching between models that need different transformers versions
-(e.g. GLM-4.7-Flash needs 5.x, Qwen needs 4.57.x), the old subprocess
-is killed and a new one is spawned with the correct version.
+When switching between models needing different transformers versions
+(e.g. GLM-4.7-Flash needs 5.x, Qwen needs 4.57.x), the old subprocess is
+killed and a new one spawned with the correct version.
 
 Pattern follows core/training/training.py.
 """
@@ -51,9 +50,8 @@ class InferenceOrchestrator:
     """
     Inference backend orchestrator — subprocess-based.
 
-    Exposes the same API surface as InferenceBackend so routes/inference.py
-    needs minimal changes. Internally, all heavy ML operations happen in
-    a persistent subprocess.
+    Same API surface as InferenceBackend (so routes/inference.py needs
+    minimal changes); all heavy ML work happens in a persistent subprocess.
     """
 
     def __init__(self):
@@ -66,9 +64,9 @@ class InferenceOrchestrator:
         self._gen_lock = threading.Lock()  # Serializes generation — one request at a time
 
         # Dispatcher state — for compare mode (adapter-controlled requests).
-        # Instead of serializing via _gen_lock, adapter-controlled requests
-        # send commands directly to the subprocess and read from per-request
-        # mailboxes. A dispatcher thread routes resp_queue events by request_id.
+        # These bypass _gen_lock: they send commands directly and read from
+        # per-request mailboxes. A dispatcher thread routes resp_queue events
+        # by request_id.
         self._mailboxes: dict[str, queue.Queue] = {}
         self._mailbox_lock = threading.Lock()  # Protects _mailboxes dict
         self._dispatcher_thread: Optional[threading.Thread] = None
@@ -92,7 +90,7 @@ class InferenceOrchestrator:
         atexit.register(self._cleanup)
         logger.info("InferenceOrchestrator initialized (subprocess mode)")
 
-        # Kick off background fetch of top models from HF
+        # Background fetch of top models from HF
         threading.Thread(target = self._fetch_top_models, daemon = True, name = "top-models").start()
 
     # ------------------------------------------------------------------
@@ -105,10 +103,9 @@ class InferenceOrchestrator:
         self._top_models_ready.wait(timeout = 5)
         top_gguf = self._top_gguf_cache or []
         top_hub = self._top_hub_cache or []
-        # Curated static defaults first (editorial picks like new models),
-        # then HF download-ranked models to backfill.
-        # Send extras so the frontend still has 4 per category
-        # after removing already-downloaded models.
+        # Curated static defaults first (editorial picks), then HF
+        # download-ranked models to backfill. Send extras so the frontend
+        # still has 4 per category after removing downloaded ones.
         result: list[str] = []
         seen: set[str] = set()
         for m in self._static_models + top_gguf + top_hub:
@@ -133,8 +130,8 @@ class InferenceOrchestrator:
             )
             if resp.status_code == 200:
                 models = resp.json()
-                # Top 40 GGUFs - frontend pages through them on-demand via
-                # infinite scroll, so we send a deep pool.
+                # Top 40 GGUFs - frontend pages through them via infinite
+                # scroll, so send a deep pool.
                 gguf_ids = [m["id"] for m in models if m.get("id", "").upper().endswith("-GGUF")][
                     :40
                 ]
@@ -201,7 +198,7 @@ class InferenceOrchestrator:
         self._cancel_generation()
         time.sleep(0.5)  # Brief wait for generation to stop
 
-        # 2. Drain stale responses from queue
+        # 2. Drain stale responses
         self._drain_queue()
 
         # 3. Send shutdown command
@@ -243,7 +240,7 @@ class InferenceOrchestrator:
         self._shutdown_subprocess(timeout = 5.0)
 
     def _ensure_subprocess_alive(self) -> bool:
-        """Check if subprocess is alive."""
+        """True if the subprocess is alive."""
         return self._proc is not None and self._proc.is_alive()
 
     # ------------------------------------------------------------------
@@ -277,14 +274,12 @@ class InferenceOrchestrator:
     ) -> dict:
         """Block until a response of the expected type arrives.
 
-        Also handles 'status' and 'error' events during the wait.
-        Returns the matching response dict.
-        Raises RuntimeError on timeout or subprocess crash.
+        Also handles 'status' and 'error' events during the wait. Returns the
+        matching response dict; raises RuntimeError on timeout or crash.
 
-        The *timeout* is an **inactivity** timeout: it resets whenever the
-        subprocess sends a status message, so long-running operations (large
-        downloads, slow model loads) won't be killed as long as the subprocess
-        keeps reporting progress.
+        *timeout* is an **inactivity** timeout: it resets on each status
+        message, so long-running operations (large downloads, slow loads)
+        survive as long as the subprocess keeps reporting progress.
         """
         deadline = time.monotonic() + timeout
 
@@ -345,8 +340,8 @@ class InferenceOrchestrator:
     def _drain_until_gen_done(self, timeout: float = 5.0) -> None:
         """Consume resp_queue events until gen_done/gen_error, discarding them.
 
-        Called after cancel to ensure stale tokens from the cancelled
-        generation don't leak into the next request.
+        Called after cancel so stale tokens from the cancelled generation
+        don't leak into the next request.
         """
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
@@ -367,10 +362,9 @@ class InferenceOrchestrator:
     def _start_dispatcher(self) -> None:
         """Start the dispatcher thread if not already running.
 
-        The dispatcher reads from the shared resp_queue and routes
-        responses to per-request mailbox queues. This allows multiple
-        adapter-controlled (compare) requests to be in-flight without
-        holding _gen_lock.
+        The dispatcher reads the shared resp_queue and routes responses to
+        per-request mailbox queues, letting multiple adapter-controlled
+        (compare) requests be in-flight without holding _gen_lock.
         """
         if self._dispatcher_thread is not None and self._dispatcher_thread.is_alive():
             return
@@ -422,9 +416,8 @@ class InferenceOrchestrator:
                     mbox.put(resp)
                     continue
 
-            # No matching mailbox — might be for a _gen_lock reader or orphaned
-            # Push it back so _read_resp can pick it up. But we can't un-get
-            # from mp.Queue, so log a warning.
+            # No matching mailbox — maybe for a _gen_lock reader or orphaned.
+            # Can't un-get from mp.Queue, so just log a warning.
             if rtype not in ("status",):
                 logger.debug(
                     "Dispatcher: no mailbox for request_id=%s type=%s, dropping",
@@ -453,13 +446,13 @@ class InferenceOrchestrator:
     ) -> Generator[str, None, None]:
         """Dispatched generation — sends command without holding _gen_lock.
 
-        Uses a per-request mailbox to receive tokens. This allows two
-        compare-mode requests to be queued in the subprocess simultaneously,
-        eliminating the inter-generation round-trip overhead.
+        Uses a per-request mailbox for tokens, so two compare-mode requests
+        can be queued in the subprocess at once, avoiding the
+        inter-generation round-trip overhead.
 
-        The subprocess processes commands sequentially from its cmd_queue,
-        so generation is still serialized at the GPU level — we just avoid
-        the orchestrator-level lock contention.
+        The subprocess runs commands sequentially from its cmd_queue, so
+        generation stays serialized at the GPU level — this only avoids
+        orchestrator-level lock contention.
         """
         if not self._ensure_subprocess_alive():
             yield "Error: Inference subprocess is not running"
@@ -532,7 +525,7 @@ class InferenceOrchestrator:
                 rtype = resp.get("type", "")
 
                 if rtype == "token":
-                    # Check cancel from route (e.g. SSE connection closed)
+                    # Cancel from route (e.g. SSE connection closed)
                     if cancel_event is not None and cancel_event.is_set():
                         self._cancel_generation()
                         # Drain remaining events for this request
@@ -574,8 +567,8 @@ class InferenceOrchestrator:
     def _wait_dispatcher_idle(self) -> None:
         """Wait for all dispatched requests to complete, then stop dispatcher.
 
-        Called by _generate_inner before using the _gen_lock path, to ensure
-        the dispatcher thread isn't competing for resp_queue reads.
+        Called by _generate_inner before the _gen_lock path so the dispatcher
+        thread isn't competing for resp_queue reads.
         """
         if self._dispatcher_thread is None or not self._dispatcher_thread.is_alive():
             return
@@ -588,9 +581,9 @@ class InferenceOrchestrator:
                     break
             time.sleep(0.1)
 
-        # Only stop dispatcher if all mailboxes drained.  If compare
-        # requests are still active, leave the dispatcher running so
-        # their token routing isn't killed mid-stream.
+        # Only stop dispatcher if all mailboxes drained. If compare requests
+        # are still active, leave it running so their token routing isn't
+        # killed mid-stream.
         with self._mailbox_lock:
             still_active = bool(self._mailboxes)
         if still_active:
@@ -618,9 +611,9 @@ class InferenceOrchestrator:
     ) -> bool:
         """Load a model for inference.
 
-        Always spawns a fresh subprocess for each model load. This ensures
-        a clean Python interpreter — no stale unsloth patches, torch.compile
-        caches, or inspect.getsource() failures from a previous model.
+        Always spawns a fresh subprocess per load for a clean interpreter —
+        no stale unsloth patches, torch.compile caches, or
+        inspect.getsource() failures from a previous model.
         """
         from utils.transformers_version import needs_transformers_5
 
@@ -649,9 +642,9 @@ class InferenceOrchestrator:
             sub_config["resolved_gpu_ids"] = resolved_gpu_ids
             sub_config["gpu_selection"] = gpu_selection
 
-            # Always kill existing subprocess and spawn fresh.
-            # Reusing a subprocess after unsloth patches torch internals
-            # causes inspect.getsource() failures on the next model load.
+            # Always kill the existing subprocess and spawn fresh: reusing one
+            # after unsloth patches torch internals causes
+            # inspect.getsource() failures on the next load.
             if self._ensure_subprocess_alive():
                 self._cancel_generation()
                 time.sleep(0.3)
@@ -680,7 +673,7 @@ class InferenceOrchestrator:
                 try:
                     resp = self._wait_response("loaded")
                 except DownloadStallError:
-                    # First stall and Xet was enabled -> retry with Xet disabled
+                    # First stall with Xet enabled -> retry with Xet disabled
                     if attempt == 0 and not disable_xet:
                         logger.warning(
                             "Download stalled for '%s' -- retrying with HF_HUB_DISABLE_XET=1",
@@ -689,7 +682,7 @@ class InferenceOrchestrator:
                         self._shutdown_subprocess(timeout = 5)
                         disable_xet = True
                         continue
-                    # Second stall (or already had xet disabled) -> give up
+                    # Second stall (or xet already disabled) -> give up
                     self._shutdown_subprocess(timeout = 5)
                     raise RuntimeError(
                         f"Download stalled for '{model_name}' even with "
@@ -745,7 +738,7 @@ class InferenceOrchestrator:
             return True
 
         if not self._ensure_subprocess_alive():
-            # No subprocess — just clear local state
+            # No subprocess — clear local state
             self.models.pop(model_name, None)
             if self.active_model_name == model_name:
                 self.active_model_name = None
@@ -797,13 +790,13 @@ class InferenceOrchestrator:
         """Generate response, streaming tokens from subprocess.
 
         Optional ``tools`` / ``enable_thinking`` / ``reasoning_effort`` /
-        ``preserve_thinking`` kwargs are forwarded into the worker so
+        ``preserve_thinking`` kwargs are forwarded to the worker so
         ``tokenizer.apply_chat_template`` can render tool schemas and
-        reasoning controls when the template understands them.
+        reasoning controls when the template supports them.
 
-        ``stats_holder``: caller-owned dict; on gen_done its "stats" key
-        receives the worker's usage/timings. Request-scoped by design so
-        concurrent streams cannot read each other's stats.
+        ``stats_holder``: caller-owned dict; on gen_done its "stats" key gets
+        the worker's usage/timings. Request-scoped so concurrent streams cannot
+        read each other's stats.
         """
         yield from self._generate_inner(
             messages = messages,
@@ -847,13 +840,12 @@ class InferenceOrchestrator:
         stats_holder: Optional[dict] = None,
         **_unused,
     ):
-        """Run the safetensors agentic tool loop in this (parent)
-        process, calling the worker for each generation turn.
+        """Run the safetensors agentic tool loop in this (parent) process,
+        calling the worker for each generation turn.
 
-        Yields the same event dicts as the GGUF tool loop so the route
-        layer can stream both backends through one helper. See
-        ``safetensors_agentic.run_safetensors_tool_loop`` for the
-        event protocol.
+        Yields the same event dicts as the GGUF tool loop so the route layer
+        can stream both backends through one helper. See
+        ``safetensors_agentic.run_safetensors_tool_loop`` for the protocol.
         """
         from core.inference.safetensors_agentic import run_safetensors_tool_loop
         from core.inference.tools import execute_tool
@@ -861,8 +853,8 @@ class InferenceOrchestrator:
         max_new_tokens = max_tokens if max_tokens and max_tokens > 0 else 2048
 
         def _single_turn(conv: list):
-            # ``conv`` already carries any system message because the
-            # loop appends to a list seeded with system+user above.
+            # ``conv`` already carries any system message: the loop appends
+            # to a list seeded with system+user above.
             common_kwargs = dict(
                 messages = conv,
                 system_prompt = "",
@@ -914,9 +906,9 @@ class InferenceOrchestrator:
     ) -> Generator[str, None, None]:
         """Generate with adapter control, streaming tokens from subprocess.
 
-        Uses the dispatcher path (no _gen_lock) so that compare-mode
-        requests don't block each other. The subprocess naturally
-        serializes them via its sequential command loop.
+        Uses the dispatcher path (no _gen_lock) so compare-mode requests
+        don't block each other; the subprocess serializes them via its
+        sequential command loop.
         """
         yield from self._generate_dispatched(
             use_adapter = use_adapter,
@@ -946,9 +938,8 @@ class InferenceOrchestrator:
     ) -> Generator[str, None, None]:
         """Inner generation logic — sends command to subprocess, yields tokens.
 
-        Serialized by _gen_lock: only one generation runs at a time.
-        This prevents concurrent readers from consuming each other's
-        tokens off the shared resp_queue.
+        Serialized by _gen_lock (one generation at a time) so concurrent
+        readers don't consume each other's tokens off the shared resp_queue.
         """
         if not self._ensure_subprocess_alive():
             yield "Error: Inference subprocess is not running"
@@ -959,13 +950,13 @@ class InferenceOrchestrator:
             return
 
         # If the dispatcher is running (from a previous compare-mode request),
-        # wait for all dispatched requests to finish, then stop the dispatcher
-        # so we can safely read from resp_queue directly.
+        # wait for dispatched requests to finish then stop it, so we can read
+        # from resp_queue directly.
         self._wait_dispatcher_idle()
 
-        # Serialize generation — single GPU, one generation at a time.
-        # Without this lock, two concurrent readers on the same resp_queue
-        # can consume and drop each other's token events.
+        # Serialize generation — single GPU, one generation at a time. Without
+        # this lock, two concurrent readers on the same resp_queue can consume
+        # and drop each other's token events.
         with self._gen_lock:
             yield from self._generate_locked(
                 messages = messages,
@@ -1029,8 +1020,8 @@ class InferenceOrchestrator:
 
         if use_adapter is not None:
             cmd["use_adapter"] = use_adapter
-        # Only forward template kwargs the caller actually set so older
-        # workers that ignore unknown keys still work.
+        # Only forward template kwargs the caller set, so older workers that
+        # ignore unknown keys still work.
         if tools is not None:
             cmd["tools"] = tools
         if enable_thinking is not None:
@@ -1046,8 +1037,8 @@ class InferenceOrchestrator:
             yield f"Error: {exc}"
             return
 
-        # Yield tokens from response queue — we are the only reader
-        # because _gen_lock is held.
+        # Yield tokens from response queue — we are the only reader since
+        # _gen_lock is held.
         while True:
             resp = self._read_resp(timeout = 30.0)
 
@@ -1071,10 +1062,10 @@ class InferenceOrchestrator:
                 return
 
             if rtype == "token":
-                # Check cancel from route (e.g. SSE connection closed)
+                # Cancel from route (e.g. SSE connection closed)
                 if cancel_event is not None and cancel_event.is_set():
                     self._cancel_generation()
-                    # Wait for the subprocess to acknowledge cancellation
+                    # Wait for the subprocess to ack cancellation
                     # (gen_done/gen_error) so stale events don't leak into
                     # the next generation request.
                     self._drain_until_gen_done(timeout = 5.0)
@@ -1117,7 +1108,7 @@ class InferenceOrchestrator:
     ) -> Tuple[bytes, int]:
         """Generate TTS audio. Returns (wav_bytes, sample_rate).
 
-        Blocking — sends command and waits for the complete audio response.
+        Blocking — sends command and waits for the full audio response.
         """
         if not self._ensure_subprocess_alive():
             raise RuntimeError("Inference subprocess is not running")
@@ -1242,7 +1233,7 @@ class InferenceOrchestrator:
 
             request_id = str(uuid.uuid4())
 
-            # Convert numpy array to list for mp.Queue serialization
+            # numpy array -> list for mp.Queue serialization
             audio_data = (
                 audio_array.tolist() if hasattr(audio_array, "tolist") else list(audio_array)
             )
@@ -1310,8 +1301,8 @@ class InferenceOrchestrator:
         img,
         max_size: int = 800,
     ):
-        """Resize image while maintaining aspect ratio.
-        No ML imports needed — runs locally in parent process.
+        """Resize image preserving aspect ratio.
+        No ML imports — runs locally in the parent process.
         """
         if img is None:
             return None
@@ -1331,26 +1322,26 @@ class InferenceOrchestrator:
         return base64.b64encode(buf.getvalue()).decode("ascii")
 
     def get_current_model(self) -> Optional[str]:
-        """Get currently active model name."""
+        """Currently active model name."""
         return self.active_model_name
 
     def is_model_loading(self) -> bool:
-        """Check if any model is currently loading."""
+        """True if any model is loading."""
         return len(self.loading_models) > 0
 
     def get_loading_model(self) -> Optional[str]:
-        """Get name of currently loading model."""
+        """Name of the currently loading model."""
         return next(iter(self.loading_models)) if self.loading_models else None
 
     def check_vision_model_compatibility(self) -> bool:
-        """Check if current model supports vision."""
+        """True if the current model supports vision."""
         if self.active_model_name and self.active_model_name in self.models:
             return self.models[self.active_model_name].get("is_vision", False)
         return False
 
     def _is_gpt_oss_model(self, model_name: str = None) -> bool:
-        """Parent-side gpt-oss detection so the safetensors route can run
-        the same guard without an IPC round-trip to the subprocess."""
+        """Parent-side gpt-oss detection so the safetensors route can run the
+        same guard without an IPC round-trip to the subprocess."""
         from utils.datasets import is_gpt_oss_model_name
         return is_gpt_oss_model_name(model_name or self.active_model_name or "")
 
@@ -1360,7 +1351,7 @@ _inference_backend = None
 
 
 def get_inference_backend() -> InferenceOrchestrator:
-    """Get global inference backend instance (orchestrator)."""
+    """Global inference backend instance (orchestrator)."""
     global _inference_backend
     if _inference_backend is None:
         _inference_backend = InferenceOrchestrator()
diff --git a/studio/backend/core/inference/pricing.py b/studio/backend/core/inference/pricing.py
index a604749c9c..efb9268170 100644
--- a/studio/backend/core/inference/pricing.py
+++ b/studio/backend/core/inference/pricing.py
@@ -1,8 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Static per-MTok pricing tables and ``calculate_cost`` helper for
-turning an upstream ``usage`` block into a USD figure.
+"""Per-MTok pricing tables and ``calculate_cost`` (usage block -> USD).
 
 Sources: Anthropic prompt-caching docs (5m write 1.25x, 1h write 2x,
 read 0.1x), web search ($10/1000), code execution; OpenAI pricing page.
@@ -12,13 +11,13 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
-# Per-MTok base pricing in USD. Cache multipliers are applied ON
-# `input_per_mtok` (not absolute prices), matching Anthropic's docs.
+# Per-MTok base USD. Cache multipliers apply to `input_per_mtok`
+# (not absolute prices), per Anthropic docs.
 ANTHROPIC_PRICING: dict[str, dict[str, float]] = {
     "claude-opus-4-7": {"input_per_mtok": 5.0, "output_per_mtok": 25.0},
     "claude-opus-4-6": {"input_per_mtok": 5.0, "output_per_mtok": 25.0},
-    # Alias both the bare id and dated id: backend defaults reference
-    # the bare form, which won't prefix-match the dated key.
+    # Alias bare + dated id: backend defaults use the bare form, which
+    # won't prefix-match the dated key.
     "claude-opus-4-5": {"input_per_mtok": 5.0, "output_per_mtok": 25.0},
     "claude-opus-4-5-20251101": {"input_per_mtok": 5.0, "output_per_mtok": 25.0},
     "claude-opus-4-1": {"input_per_mtok": 15.0, "output_per_mtok": 75.0},
@@ -34,8 +33,8 @@ ANTHROPIC_PRICING: dict[str, dict[str, float]] = {
 
 OPENAI_PRICING: dict[str, dict[str, float]] = {
     # Verified against developers.openai.com/api/docs/pricing.
-    # `long_context_*` keys apply once input exceeds the threshold
-    # (gpt-5.5/5.4: 272k); families without these keys ship a single rate.
+    # `long_context_*` keys apply past the threshold (gpt-5.5/5.4: 272k);
+    # families without them ship a single rate.
     "gpt-5.5": {
         "input_per_mtok": 5.0,
         "output_per_mtok": 30.0,
@@ -58,28 +57,28 @@ OPENAI_PRICING: dict[str, dict[str, float]] = {
     # chat-latest aliases gpt-5.5.
     "gpt-5.3-chat-latest": {"input_per_mtok": 5.0, "output_per_mtok": 30.0},
     "chat-latest": {"input_per_mtok": 5.0, "output_per_mtok": 30.0},
-    # o-series and gpt-4.5 are no longer on the pricing page; omit them
-    # so calculate_cost returns priced=False rather than silently $0.
+    # o-series / gpt-4.5 left off the pricing page: omit so calculate_cost
+    # returns priced=False instead of silently $0.
 }
 
-# Shared multipliers (same across every Anthropic model).
+# Shared multipliers (all Anthropic models).
 ANTHROPIC_CACHE_5M_WRITE_MULT = 1.25
 ANTHROPIC_CACHE_1H_WRITE_MULT = 2.0
 ANTHROPIC_CACHE_READ_MULT = 0.1
-# Anthropic fast-mode (Opus 4.6 / 4.7 only): 6x standard on input + output.
+# Anthropic fast-mode (Opus 4.6/4.7 only): 6x on input + output.
 # https://platform.claude.com/docs/en/build-with-claude/fast-mode#pricing
 ANTHROPIC_FAST_MODE_MULT = 6.0
 
-# OpenAI: cache reads 0.1x; cache writes pay normal input price.
+# OpenAI: cache reads 0.1x; cache writes pay input price.
 OPENAI_CACHE_READ_MULT = 0.1
 
-# Server-tool surcharges. Anthropic code_exec is $0.05/hr marginal
-# (50 free hours/day per org, not visible here).
+# Server-tool surcharges. Anthropic code_exec: $0.05/hr marginal
+# (50 free hours/day per org, not shown here).
 ANTHROPIC_WEB_SEARCH_USD_PER_1K = 10.0
 ANTHROPIC_CODE_EXEC_USD_PER_HOUR = 0.05
 
-# OpenAI container bills per memory tier; we report the 1g default
-# ($0.09/hour) since the tier isn't surfaced to the cost ledger.
+# OpenAI container bills per memory tier; report the 1g default
+# ($0.09/hr) since the tier isn't surfaced to the ledger.
 OPENAI_WEB_SEARCH_USD_PER_1K = 10.0
 OPENAI_CONTAINER_USD_PER_HOUR = 0.09  # 1g default tier
 
@@ -96,10 +95,9 @@ def _lookup(provider: str, model: str) -> Optional[dict[str, float]]:
         return None
     if model in table:
         return table[model]
-    # Longest-prefix match on a dash boundary: lets dated snapshots
-    # inherit canonical prices while preventing "claude-opus-4-15"
-    # from matching "claude-opus-4-1" or "gpt-5.5-prod" from matching
-    # "gpt-5.5-pro". Sort longest-first to pick the most specific row.
+    # Longest-prefix match on a dash boundary, longest-first: dated
+    # snapshots inherit canonical prices, but "claude-opus-4-15" won't
+    # match "claude-opus-4-1" nor "gpt-5.5-prod" match "gpt-5.5-pro".
     for key in sorted(table, key = len, reverse = True):
         if model.startswith(key) and (len(model) == len(key) or model[len(key)] == "-"):
             return table[key]
@@ -107,11 +105,10 @@ def _lookup(provider: str, model: str) -> Optional[dict[str, float]]:
 
 
 def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str, float]:
-    """Return a per-turn USD cost breakdown with per-bucket + total
-    fields so the frontend can render either a single number or a
-    tooltip without re-doing the math. When the model isn't in the
-    static table, ``priced`` is False and USD fields are 0.0 (token
-    counts still report).
+    """Return a per-turn USD cost breakdown (per-bucket + total) so the
+    frontend renders a number or tooltip without redoing the math.
+    Unknown model -> ``priced`` False and USD fields 0.0 (token counts
+    still report).
     """
     prices = _lookup(provider, model)
     out: dict[str, float] = {
@@ -128,22 +125,20 @@ def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str
     }
 
     # Accept raw (input_tokens/output_tokens) and Studio chat-style
-    # (prompt_tokens/completion_tokens) envelopes. Cache buckets
-    # behave differently per envelope:
+    # (prompt_tokens/completion_tokens) envelopes. Cache buckets differ:
     #   raw Anthropic:    input_tokens EXCLUDES cache buckets
     #   raw OpenAI:       input_tokens INCLUDES cache_read
     #   Studio Anthropic: prompt_tokens INCLUDES cache_creation + cache_read
     #   Studio OpenAI:    prompt_tokens == raw input_tokens
-    # Clamp tokens >=0 so corrupted payloads can't produce a negative bill.
+    # Clamp >=0 so corrupted payloads can't produce a negative bill.
     cache_creation = max(0, int(usage.get("cache_creation_input_tokens") or 0))
     cache_read_native_present = (
         "cache_read_input_tokens" in usage and usage.get("cache_read_input_tokens") is not None
     )
     cache_read = max(0, int(usage.get("cache_read_input_tokens") or 0))
-    # Fallback to mirrored prompt_tokens_details only when the native
-    # cache_read_input_tokens key is absent. An explicit native 0 is
-    # authoritative, so a stale mirrored block from a proxy can never
-    # inflate cache_read past the native count.
+    # Fall back to mirrored prompt_tokens_details only when native
+    # cache_read_input_tokens is absent; an explicit native 0 is
+    # authoritative, so a stale proxy mirror can't inflate cache_read.
     if not cache_read_native_present:
         details = usage.get("prompt_tokens_details") or {}
         if isinstance(details, dict):
@@ -152,22 +147,22 @@ def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str
     if has_input_tokens:
         input_tokens = max(0, int(usage.get("input_tokens") or 0))
     else:
-        # Chat-style: peel cache buckets back out for Anthropic to
-        # recover the raw uncached prompt count.
+        # Chat-style: peel cache buckets back out for Anthropic to get
+        # the raw uncached prompt count.
         prompt_tokens = max(0, int(usage.get("prompt_tokens") or 0))
         if provider == "anthropic":
             input_tokens = max(0, prompt_tokens - cache_creation - cache_read)
         else:
             input_tokens = prompt_tokens
-    # Prefer raw output_tokens even when 0 (an `or` fallback would
-    # silently pick a stale completion_tokens).
+    # Prefer raw output_tokens even when 0 (an `or` would pick a stale
+    # completion_tokens).
     if "output_tokens" in usage and usage.get("output_tokens") is not None:
         output_tokens = max(0, int(usage.get("output_tokens") or 0))
     else:
         output_tokens = max(0, int(usage.get("completion_tokens") or 0))
     if provider == "openai":
-        # Cached tokens land on either input_tokens_details (raw
-        # Responses) or prompt_tokens_details (Studio chat-style).
+        # Cached tokens land on input_tokens_details (raw Responses) or
+        # prompt_tokens_details (Studio chat-style).
         for key in ("input_tokens_details", "prompt_tokens_details"):
             details = usage.get(key) or {}
             if isinstance(details, dict):
@@ -200,8 +195,8 @@ def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str
         out_per = prices["output_per_mtok"]
 
     # Anthropic fast-mode: 6x on input + output. Cache multipliers stack
-    # on top of fast-mode, so applying once to (base, out_per) propagates
-    # into the cache_*_usd buckets computed below.
+    # on top, so applying once to (base, out_per) flows into the
+    # cache_*_usd buckets below.
     if provider == "anthropic" and usage.get("speed") == "fast":
         base *= ANTHROPIC_FAST_MODE_MULT
         out_per *= ANTHROPIC_FAST_MODE_MULT
@@ -235,15 +230,15 @@ def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str
                 + code_exec_hours * ANTHROPIC_CODE_EXEC_USD_PER_HOUR
             )
     else:
-        # OpenAI: cache writes pay base input; only cache reads get
-        # 0.1x. Subtract cached from already-counted input_usd to
-        # avoid double-billing (OpenAI folds cache into input_tokens).
+        # OpenAI: cache writes pay base input, only reads get 0.1x.
+        # Subtract cached from already-counted input_usd to avoid
+        # double-billing (OpenAI folds cache into input_tokens).
         if cache_read > 0:
             non_cached_input = max(0, input_tokens - cache_read)
             out["input_usd"] = (non_cached_input / 1_000_000.0) * base
             out["cache_read_usd"] = (cache_read / 1_000_000.0) * base * OPENAI_CACHE_READ_MULT
         # OpenAI server-tool surcharges arrive under `openai_tool_use`
-        # (normalised by the SSE finaliser from output array items).
+        # (normalised by the SSE finaliser from output items).
         srv = usage.get("openai_tool_use") or {}
         if isinstance(srv, dict):
             web_searches = int(srv.get("web_search_requests") or 0)
diff --git a/studio/backend/core/inference/providers.py b/studio/backend/core/inference/providers.py
index 19b776a6d9..9c98133f67 100644
--- a/studio/backend/core/inference/providers.py
+++ b/studio/backend/core/inference/providers.py
@@ -5,7 +5,7 @@
 Static registry of supported external LLM providers.
 
 All providers expose OpenAI-compatible /v1/chat/completions endpoints
-with Bearer token authentication and SSE streaming support.
+with Bearer token auth and SSE streaming.
 """
 
 import re
@@ -26,11 +26,10 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_tool_calling": True,
         "auth_header": "Authorization",
         "auth_prefix": "Bearer ",
-        # Keep the model picker scoped to the current generation. The remote
-        # /v1/models listing returns dozens of historical snapshots, fine-tunes
-        # and non-chat models (embeddings, TTS, image, moderation) that we
-        # never want to surface in the chat UI. Filtering here so backend
-        # is the single source of truth.
+        # Scope the picker to the current generation. /v1/models returns
+        # dozens of historical snapshots, fine-tunes, and non-chat models
+        # (embeddings, TTS, image, moderation) we never want in the chat
+        # UI. Filter here so the backend is the single source of truth.
         "model_id_allowlist": re.compile(r"^(gpt-5\.[345]|gpt-4\.5|o3)(?:[-.]|$)"),
         # Hide dated snapshots and the retired plain gpt-5.3 id.
         "model_id_denylist": re.compile(r"^(gpt-5\.3)$|-\d{4}-\d{2}-\d{2}$"),
@@ -48,9 +47,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         ],
         # Anthropic /v1/models returns dated snapshot ids alongside the
         # canonical names (e.g. claude-3-5-sonnet-20241022). Hide the
-        # YYYYMMDD-suffixed variants from the picker — same intent as the
-        # OpenAI denylist, just a different date format (no dashes between
-        # year/month/day).
+        # YYYYMMDD-suffixed variants — same intent as the OpenAI denylist,
+        # just a different date format (no dashes).
         "model_id_denylist": re.compile(r"-\d{8}$"),
         "supports_streaming": True,
         "supports_vision": True,
@@ -68,20 +66,18 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         # Native Gemini REST endpoint -- the Gemini API does NOT speak
         # OpenAI Chat Completions on this base. Requests/responses are
         # translated in `_stream_gemini` in external_provider.py.
-        # API reference: https://ai.google.dev/gemini-api/docs
+        # https://ai.google.dev/gemini-api/docs
         "base_url": "https://generativelanguage.googleapis.com/v1beta",
-        # Curated lineup -- the live ListModels response returns dozens
-        # of historical / experimental / embedding ids. Cap to the
-        # current chat-capable Gemini families (3.5 / 3.1 / 3 Flash /
-        # 2.5) plus the Nano Banana image trio and the rolling
-        # `*-latest` aliases. Excluded on purpose:
+        # Curated lineup -- live ListModels returns dozens of historical /
+        # experimental / embedding ids. Cap to current chat-capable Gemini
+        # families (3.5 / 3.1 / 3 Flash / 2.5) plus the Nano Banana image
+        # trio and the rolling `*-latest` aliases. Excluded on purpose:
         #   - `gemini-2.0-flash*` (Google retired 2026-06-01; 404 on use)
         #   - `gemini-3-pro-preview` (shut down 2026-03-09; auto-redirects
         #     to `gemini-3.1-pro-preview` per Google's deprecation notice,
         #     so we surface 3.1 directly and skip the redirect).
-        # The allowlist below blocks the retired ids from re-appearing
-        # via the live ListModels fetch. Verified against the live
-        # `/v1beta/models` catalog 2026-05-24.
+        # The allowlist below keeps the retired ids from re-appearing via
+        # live ListModels. Verified against `/v1beta/models` 2026-05-24.
         "default_models": [
             "gemini-3.1-pro-preview",
             "gemini-3.5-flash",
@@ -100,8 +96,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_streaming": True,
         "supports_vision": True,
         "supports_tool_calling": True,
-        # The native API takes the API key on the `x-goog-api-key`
-        # header. An empty `auth_prefix` ensures we send the bare key.
+        # Native API takes the key on `x-goog-api-key`; empty `auth_prefix`
+        # sends the bare key.
         "auth_header": "x-goog-api-key",
         "auth_prefix": "",
         "openai_compatible": False,
@@ -110,20 +106,19 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
             "API key from https://aistudio.google.com/apikey. "
             "See https://ai.google.dev/gemini-api/docs for endpoint shapes."
         ),
-        # Even after the regex match, drop ids that Google still
-        # returns from ListModels but routes via implicit redirect.
-        # gemini-3-pro-preview was shut down 2026-03-09 and is
-        # auto-aliased to gemini-3.1-pro-preview; we surface the
-        # canonical id only so users do not see two cards for the
-        # same underlying model.
+        # Even after the regex match, drop ids Google still returns from
+        # ListModels but routes via implicit redirect. gemini-3-pro-preview
+        # was shut down 2026-03-09 and auto-aliased to
+        # gemini-3.1-pro-preview; surface the canonical id only so users
+        # don't see two cards for the same model.
         "model_id_deny_exact": ("gemini-3-pro-preview",),
         # Matches the chat-capable 3.5 / 3.1 / 3 / 2.5 families plus the
-        # rolling *-latest aliases (which Google rolls forward as new
-        # generations ship). Image-tier ids (`-image`, `-image-preview`,
+        # rolling *-latest aliases (rolled forward as new generations ship).
+        # Image-tier ids (`-image`, `-image-preview`,
         # `nano-banana-pro-preview`) flow through the Nano Banana
-        # `responseModalities` path in `_stream_gemini`. Retired 2.0
-        # ids ARE NOT in this regex on purpose -- Google's ListModels
-        # would otherwise re-surface them and they 404 on use.
+        # `responseModalities` path in `_stream_gemini`. Retired 2.0 ids are
+        # excluded on purpose -- ListModels would re-surface them and they
+        # 404 on use.
         "model_id_allowlist": re.compile(
             r"^("
             r"gemini-3\.5-(?:flash|pro)(?:-preview)?|"
@@ -186,12 +181,12 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "base_url": "https://api.moonshot.ai/v1",
         # Current Kimi model lineup per the official docs:
         #   https://platform.kimi.ai/docs/models
-        # Listing/overview endpoints used to enumerate them:
+        # Listing/overview endpoints:
         #   https://platform.kimi.ai/docs/api/list-models
         #   https://platform.kimi.ai/docs/api/overview
         # kimi-k2.6 and kimi-k2.5 are the two SoTA multimodal models we
-        # surface in the picker; everything else (moonshot-v1-*, dated
-        # k2 previews) is filtered out by model_id_allowlist below.
+        # surface; everything else (moonshot-v1-*, dated k2 previews) is
+        # filtered out by model_id_allowlist below.
         "default_models": [
             "kimi-k2.6",
             "kimi-k2.5",
@@ -205,8 +200,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "model_id_allowlist": re.compile(r"^kimi-k2\.[56]$"),
         # Both k2.6 and k2.5 are reasoning-class. The API rejects custom
         # sampling: "invalid temperature: only 1 is allowed for this model"
-        # (and the same shape for top_p). Strip both fields from the
-        # outbound body so the server falls back to its required defaults.
+        # (same for top_p). Strip both fields from the outbound body so the
+        # server falls back to its required defaults.
         "body_omit": ("temperature", "top_p"),
     },
     "qwen": {
@@ -228,9 +223,9 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     "huggingface": {
         "display_name": "Hugging Face",
         "base_url": "https://router.huggingface.co/v1",
-        # Seed the picker with a few popular ids so something is selectable
-        # before the live /v1/models call resolves. The remote listing is
-        # the source of truth — see model_list_mode below.
+        # Seed the picker with popular ids so something is selectable before
+        # the live /v1/models call resolves. The remote listing is the
+        # source of truth -- see model_list_mode below.
         "default_models": [
             "openai/gpt-oss-120b",
             "deepseek-ai/DeepSeek-V3",
@@ -249,27 +244,26 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
             "https://huggingface.co/docs/inference-providers/index."
         ),
         # /v1/models works on the HF router and returns the full chat-model
-        # catalog (state.org/model[:policy] ids). Switch to remote so users
-        # see live availability — the picker has a search box, and
-        # loadModels() merges defaults so default_models entries remain
-        # visible if the remote call fails.
+        # catalog (state.org/model[:policy] ids). Remote so users see live
+        # availability -- the picker has search, and loadModels() merges
+        # defaults so default_models stay visible if the remote call fails.
         "model_list_mode": "remote",
-        # Scope the catalog to first-party org repos we trust as primary
-        # sources. The HF /v1/models response is otherwise hundreds of
-        # ids long (community fine-tunes, mirrors, fp8 variants, etc.).
+        # Scope to first-party org repos we trust as primary sources. The HF
+        # /v1/models response is otherwise hundreds of ids long (community
+        # fine-tunes, mirrors, fp8 variants, etc.).
         "model_id_allowlist": re.compile(
             r"^(openai|deepseek-ai|google|meta-llama|Qwen|moonshotai|mistralai|zai-org)/"
         ),
-        # Cap the post-filter list. /v1/models has no server-side limit
-        # or popularity sort, so this is just "first N matches" — pair it
-        # with the default_models seed so the most useful flagship ids
-        # are always among the top regardless of the API's order.
+        # Cap the post-filter list. /v1/models has no server-side limit or
+        # popularity sort, so this is just "first N matches"; the
+        # default_models seed keeps flagship ids near the top regardless of
+        # the API's order.
         "model_id_limit": 15,
     },
     "vllm": {
         "display_name": "vLLM",
-        # User-supplied via provider_base_url; the route layer already falls
-        # back to the payload's base_url when the registry entry has none.
+        # User-supplied via provider_base_url; the route layer falls back to
+        # the payload's base_url when the registry entry has none.
         "base_url": "",
         "default_models": [],
         "supports_streaming": True,
@@ -277,15 +271,14 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_tool_calling": True,
         "auth_header": "Authorization",
         "auth_prefix": "Bearer ",
-        # Force /v1/chat/completions in stream_chat_completion — vLLM's
-        # /v1/responses rebuilds messages and runs them through the loaded
-        # model's chat template, which 400s on strict-alternation templates
-        # (Gemma 3 raises "Conversation roles must alternate user/assistant
-        # /user/assistant/..."). The chat-completions path takes messages
-        # verbatim and avoids that template gauntlet.
+        # Force /v1/chat/completions in stream_chat_completion -- vLLM's
+        # /v1/responses rebuilds messages through the model's chat template,
+        # which 400s on strict-alternation templates (Gemma 3 raises
+        # "Conversation roles must alternate user/assistant/user/assistant
+        # /..."). The chat-completions path takes messages verbatim.
         "notes": "Self-hosted vLLM server. Always routed to /v1/chat/completions.",
-        # Surfaced through the frontend's CUSTOM_PROVIDER_PRESETS, not the
-        # /api/providers/registry dropdown — see list_available_providers.
+        # Surfaced via the frontend's CUSTOM_PROVIDER_PRESETS, not the
+        # /api/providers/registry dropdown -- see list_available_providers.
         "hidden": True,
     },
     "ollama": {
@@ -371,10 +364,10 @@ def get_base_url(provider_type: str) -> str | None:
 def list_available_providers() -> list[dict[str, Any]]:
     """Return all registered providers (for the /registry endpoint).
 
-    Hidden entries (``"hidden": True``) are filtered out — they exist in the
-    registry only for backend lookups (e.g. ``supports_vision`` for vLLM) and
-    are surfaced in the frontend via ``CUSTOM_PROVIDER_PRESETS`` instead of
-    the cloud-provider dropdown.
+    Hidden entries (``"hidden": True``) are filtered out: they exist only
+    for backend lookups (e.g. ``supports_vision`` for vLLM) and are
+    surfaced in the frontend via ``CUSTOM_PROVIDER_PRESETS`` instead of the
+    cloud-provider dropdown.
     """
     result = []
     for provider_type, info in PROVIDER_REGISTRY.items():
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index e4eb0cd100..954a2b3d19 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -4,17 +4,16 @@
 """
 Safetensors/transformers agentic tool loop.
 
-Wraps a single-turn cumulative-text generator (the existing
-``InferenceOrchestrator.generate_chat_response`` pipeline that streams
-from a worker subprocess) with the tool-calling, thinking-block,
-status, and metadata event protocol used by the GGUF path. Keeps the
-front-end SSE shape identical across backends so the chat UI does not
-care which engine actually ran the model.
+Wraps a single-turn cumulative-text generator (the
+``InferenceOrchestrator.generate_chat_response`` pipeline streaming from a
+worker subprocess) with the tool-calling, thinking-block, status, and
+metadata event protocol used by the GGUF path. The front-end SSE shape
+stays identical across backends, so the chat UI is engine-agnostic.
 
-The GGUF path lives in ``llama_cpp.py`` and talks to llama-server's
-structured ``delta.tool_calls`` directly. Native transformers has no
-such structured channel, so this loop parses tool calls from the
-cumulative text and dispatches them via ``core.inference.tools``.
+The GGUF path (``llama_cpp.py``) uses llama-server's structured
+``delta.tool_calls`` directly. Native transformers has no such channel, so
+this loop parses tool calls from the cumulative text and dispatches them
+via ``core.inference.tools``.
 """
 
 import json
@@ -41,7 +40,7 @@ from core.inference.tool_call_parser import (
 logger = get_logger(__name__)
 
 
-# Buffer cap while waiting to disambiguate a possible tool-call prefix.
+# Buffer cap while disambiguating a possible tool-call prefix.
 _MAX_BUFFER_CHARS = 32
 
 
@@ -105,10 +104,10 @@ def _coerce_arguments(
     """Normalise tool ``arguments`` to a dict.
 
     Some templates emit a JSON string, others a bare query string. With
-    ``heal=True`` we accept a bare string as ``{<canonical_key>: ...}``
-    so a Hermes-style call without proper JSON still runs the tool. The
-    canonical key is picked per tool: ``code`` for python, ``command``
-    for terminal, ``query`` for everything else (e.g. web_search).
+    ``heal=True`` a bare string becomes ``{<canonical_key>: ...}`` so a
+    Hermes-style call without proper JSON still runs. Canonical key per
+    tool: ``code`` for python, ``command`` for terminal, ``query`` otherwise
+    (e.g. web_search).
     """
     if isinstance(raw_args, dict):
         return raw_args
@@ -140,28 +139,23 @@ def run_safetensors_tool_loop(
 ) -> Generator[dict, None, None]:
     """Drive an agentic tool loop on top of a cumulative-text generator.
 
-    ``single_turn(messages)`` must yield cumulative assistant text
-    (each yield is a snapshot including all previously emitted tokens).
-    The loop:
+    ``single_turn(messages)`` must yield cumulative assistant text (each
+    yield is a snapshot of all tokens so far). The loop:
 
-    * Buffers the leading characters of every turn so it can decide
-      whether the model is about to emit a tool call. Plain content
-      starts streaming as soon as the buffer rules it out.
-    * On detecting ``<tool_call>`` or ``<function=`` in the cumulative
-      text, drains the rest of the turn silently and parses tool calls
-      out of the full content.
+    * Buffers each turn's leading chars to decide whether a tool call is
+      coming. Plain content streams once the buffer rules it out.
+    * On ``<tool_call>`` or ``<function=`` in the cumulative text, drains
+      the rest of the turn silently and parses tool calls from the content.
     * Executes each tool via ``execute_tool``, appends the assistant
-      tool-call message and the tool result to the conversation, and
-      re-enters ``single_turn`` for the next iteration.
-    * After ``max_tool_iterations`` turns without a final answer, asks
-      the model once more to produce a final answer with no tools.
+      tool-call message and tool result, and re-enters ``single_turn``.
+    * After ``max_tool_iterations`` turns without a final answer, asks once
+      more for a final answer with no tools.
 
     Yields event dicts matching the GGUF path:
 
     * ``{"type": "status", "text": ...}`` -- empty string clears the badge.
     * ``{"type": "content", "text": ...}`` -- cumulative cleaned text for
-      the current assistant turn (the consumer should diff against its
-      own ``prev_text`` cursor).
+      the current turn (consumer diffs against its own ``prev_text`` cursor).
     * ``{"type": "tool_start", "tool_name", "tool_call_id", "arguments"}``
     * ``{"type": "tool_end", "tool_name", "tool_call_id", "result"}``
     """
@@ -205,7 +199,7 @@ def run_safetensors_tool_loop(
                 return
 
             if not isinstance(cumulative, str):
-                continue  # defensive: pipeline only yields strings
+                continue  # defensive: pipeline yields only strings
 
             delta = cumulative[len(prev_cumulative) :]
             prev_cumulative = cumulative
@@ -308,7 +302,7 @@ def run_safetensors_tool_loop(
             return
 
         if detect_state == _state_buffering:
-            # Buffer never resolved -- tool XML or plain content.
+            # Buffer never resolved -- tool XML or plain content?
             stripped = content_buffer.lstrip()
             if stripped and has_tool_signal(stripped):
                 detect_state = _state_draining
@@ -331,9 +325,9 @@ def run_safetensors_tool_loop(
                     id_offset = next_call_id,
                 )
             if not safety_tc:
-                # Final answer: streaming already emitted content.
-                # Skip a final=True re-strip so literal "<tool_call>"
-                # in prose survives when no real tool call parsed.
+                # Final answer: streaming already emitted content. Skip the
+                # final=True re-strip so literal "<tool_call>" in prose
+                # survives when no real tool call parsed.
                 yield {"type": "status", "text": ""}
                 return
             tool_calls = safety_tc
@@ -349,8 +343,8 @@ def run_safetensors_tool_loop(
                 id_offset = next_call_id,
             )
             if not tool_calls and auto_heal_tool_calls:
-                # Parser found nothing -- surface raw content so any
-                # literal "<tool_call>" prose is preserved.
+                # Parser found nothing -- surface raw content so literal
+                # "<tool_call>" prose is preserved.
                 if content_accum:
                     yield {"type": "content", "text": content_accum}
                 if provisional_render_html_started:
@@ -436,9 +430,8 @@ def run_safetensors_tool_loop(
                 render_html_succeeded = True
             tool_call_history.append((tc_key, is_error))
 
-            # Strip frontend image sentinel from the model's view.
-            # Cut at the first occurrence so leading and consecutive
-            # sentinels are both removed.
+            # Strip frontend image sentinel from the model's view. Cut at the
+            # first occurrence so leading and consecutive sentinels both go.
             result_for_model = result
             if isinstance(result_for_model, str) and "__IMAGES__:" in result_for_model:
                 result_for_model = result_for_model.split("__IMAGES__:", 1)[0].rstrip()
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index 23b7d4c97a..1b453df0ff 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -13,9 +13,9 @@ import re
 
 # _TOOL_CLOSED_PATS: closed pairs only. _TOOL_ALL_PATS: also trailing
 # unclosed runs so truncated tails don't leak markup.
-# Function-name char set tracks OpenAI's ^[a-zA-Z0-9_-]{1,64}$ so MCP
-# tool names that contain a hyphen (e.g. mcp__srv__list-issues) parse
-# the same as the built-in web_search/python/terminal names.
+# Function-name char set tracks OpenAI's ^[a-zA-Z0-9_-]{1,64}$ so hyphenated
+# MCP tool names (e.g. mcp__srv__list-issues) parse the same as built-in
+# web_search/python/terminal names.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
     re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
@@ -72,8 +72,8 @@ _TC_JSON_START_RE = re.compile(r"<tool_call>\s*\{")
 _TC_FUNC_START_RE = re.compile(r"<function=([\w-]+)>\s*")
 _TC_END_TAG_RE = re.compile(r"</tool_call>")
 _TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
-# Parameter names can carry hyphens too (e.g. MCP tool schemas with
-# `issue-number`, `repo-name`); using `\w+` here dropped those keys.
+# Parameter names can carry hyphens too (e.g. MCP schemas with
+# `issue-number`, `repo-name`); `\w+` alone dropped those keys.
 _TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>\s*")
 _TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
 _PARAM_CLOSE_TAG = "</parameter>"
@@ -124,8 +124,8 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
     """
     tool_calls: list[dict] = []
 
-    # Pattern 1: <tool_call>{json}. Balanced-brace scan that skips
-    # braces inside JSON strings.
+    # Pattern 1: <tool_call>{json}. Balanced-brace scan skipping braces
+    # inside JSON strings.
     for m in _TC_JSON_START_RE.finditer(content):
         brace_start = m.end() - 1  # position of the opening {
         depth, i = 0, brace_start
@@ -165,9 +165,9 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
             except (json.JSONDecodeError, ValueError):
                 pass
 
-    # Pattern 2: <function=name><parameter=k>v... -- closing tags
-    # optional; don't use </function> as body boundary because code
-    # values can contain that literal.
+    # Pattern 2: <function=name><parameter=k>v... -- closing tags optional;
+    # don't use </function> as body boundary since code values can contain
+    # that literal.
     if not tool_calls:
         func_starts = [
             fm
@@ -190,8 +190,8 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
             arguments: dict = {}
             param_starts = list(_TC_PARAM_START_RE.finditer(body))
             if len(param_starts) == 1:
-                # Single param: take everything to body end so
-                # embedded </parameter> in code strings is preserved.
+                # Single param: take everything to body end so embedded
+                # </parameter> in code strings is preserved.
                 pm = param_starts[0]
                 val = body[pm.end() :]
                 val = _TC_PARAM_CLOSE_RE.sub("", val)
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 9be2276d3d..bc1897199f 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -4,7 +4,7 @@
 """
 Tool definitions and executors for LLM tool calling.
 
-Supports web search (DuckDuckGo), Python code execution, and terminal commands.
+Web search (DuckDuckGo), Python code execution, and terminal commands.
 """
 
 import ast
@@ -42,9 +42,8 @@ logger = get_logger(__name__)
 
 _EXEC_TIMEOUT = 300  # 5 minutes
 
-# Pre-import modules used in _sandbox_preexec at module level so that
-# the preexec_fn closure does not trigger the import machinery in the
-# forked child (which can deadlock in multi-threaded servers).
+# Pre-import _sandbox_preexec modules at module level so the preexec_fn closure
+# doesn't trigger imports in the forked child (can deadlock multi-threaded servers).
 _libc = None
 if sys.platform == "linux":
     try:
@@ -64,8 +63,8 @@ if sys.platform != "win32":
     except ImportError:
         pass
 
-# Strict raster-image allowlist for sandbox file serving.
-# No .svg (XSS risk via embedded scripts), no .html, no .pdf.
+# Raster-image allowlist for sandbox file serving.
+# No .svg (XSS via embedded scripts), no .html, no .pdf.
 _IMAGE_EXTS = frozenset({".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"})
 _MAX_OUTPUT_CHARS = 8000  # truncate long output
 _BLOCKED_COMMANDS_COMMON = frozenset(
@@ -122,9 +121,9 @@ _BLOCKED_COMMANDS = (
 
 
 _SHELL_SEPARATORS = frozenset({";", "&&", "||", "|", "&", "\n", "(", ")", "`", "{", "}"})
-# Bash keywords that introduce a new command position (then $cmd, do $cmd, etc.).
+# Bash keywords starting a new command position (then $cmd, do $cmd, etc.).
 _SHELL_KEYWORDS_AS_SEP = frozenset({"then", "do", "else", "elif"})
-# Wrappers whose next non-flag argument is itself the command Bash will exec.
+# Wrappers whose next non-flag argument is the command Bash will exec.
 _COMMAND_PREFIXES = frozenset(
     {
         "env",
@@ -152,21 +151,19 @@ _FIND_EXEC_FLAGS = frozenset({"-exec", "-execdir", "-ok", "-okdir"})
 def _find_blocked_commands(command: str) -> set[str]:
     """Detect blocked commands at shell command position only.
 
-    A token is at command position if it is the first token, or if the
-    preceding token is a shell separator / brace-group opener / keyword
-    that starts a new command (`then`, `do`, etc.), or a command-prefix
-    wrapper like `env` / `time` / `xargs` (the next token is the real
-    command). Tokens in argument position (`grep -r curl .`,
-    `echo source the data`, `ls /usr/bin/curl`) are passed through.
-    Also scans `find ... -exec CMD` and recurses into bash -c / cmd /c.
+    A token is at command position if it is the first token, or follows a
+    shell separator / brace-group opener / new-command keyword (`then`, `do`,
+    etc.), or a command-prefix wrapper like `env` / `time` / `xargs` (next
+    token is the real command). Tokens in argument position (`grep -r curl .`,
+    `echo source the data`, `ls /usr/bin/curl`) pass through. Also scans
+    `find ... -exec CMD` and recurses into bash -c / cmd /c.
     """
     blocked: set[str] = set()
 
     # shlex with punctuation_chars splits `;`, `&&`, `||`, `|`, `(`, `)`, `` ` ``
-    # off as their own tokens so we can detect command position even when a
-    # caller writes `echo done; rm -rf x` (no whitespace) or quote-splits the
-    # command name itself (`r''m` collapses to a single token `rm` at command
-    # position after the `;` separator).
+    # into their own tokens, so we detect command position even for
+    # `echo done; rm -rf x` (no whitespace) or quote-split command names
+    # (`r''m` collapses to `rm` at command position after `;`).
     try:
         if sys.platform == "win32":
             tokens = shlex.split(command, posix = False)
@@ -178,9 +175,8 @@ def _find_blocked_commands(command: str) -> set[str]:
         tokens = command.split()
 
     def _token_basename(tok: str) -> str:
-        # shlex may glue trailing meta-chars onto a token (`rm;`); strip them
-        # so the basename match still hits `rm`. Leading shell-state chars
-        # likewise.
+        # shlex may glue meta-chars onto a token (`rm;`); strip leading and
+        # trailing ones so the basename still matches `rm`.
         tok = tok.strip(";&|()`{}")
         base = os.path.basename(tok).lower()
         stem, ext = os.path.splitext(base)
@@ -189,33 +185,32 @@ def _find_blocked_commands(command: str) -> set[str]:
         return base
 
     expect_command = True  # start of string is a command position
-    prefix_pending = False  # last command-position token was env/time/timeout/xargs/...
+    prefix_pending = False  # last cmd-position token was a wrapper (env/time/xargs/...)
     for token in tokens:
         if token in _SHELL_SEPARATORS or token in _SHELL_KEYWORDS_AS_SEP:
             expect_command = True
             prefix_pending = False
             continue
         if token.startswith("-"):
-            # Flags belong to the active command. While a wrapper prefix is
-            # waiting for its command (`stdbuf -oL cmd`, `xargs -- cmd`),
-            # keep expect_command intact.
+            # Flags belong to the active command. While a wrapper prefix awaits
+            # its command (`stdbuf -oL cmd`, `xargs -- cmd`), keep expect_command.
             if not prefix_pending:
                 expect_command = False
             continue
         if not expect_command:
             continue
-        # FOO=bar prefix: assignment list, next non-assignment token is the command.
+        # FOO=bar assignment prefix; next non-assignment token is the command.
         if _ASSIGNMENT_RE.match(token):
             continue
-        # `timeout 1 cmd` / `nice -n 5 cmd` style numeric wrapper arg.
+        # Numeric wrapper arg: `timeout 1 cmd` / `nice -n 5 cmd`.
         if prefix_pending and token.lstrip("-").isdigit():
             continue
         base = _token_basename(token)
         if base in _BLOCKED_COMMANDS:
             blocked.add(base)
         # Wrappers (`env` / `time` / `xargs` / `sudo`) consume one command; the
-        # next non-flag, non-numeric token is the real command. `sudo` is
-        # already in _BLOCKED_COMMANDS, so it's flagged AND we keep walking.
+        # next non-flag, non-numeric token is the real command. `sudo` is in
+        # _BLOCKED_COMMANDS, so it's flagged AND we keep walking.
         if base in _COMMAND_PREFIXES:
             prefix_pending = True
             continue
@@ -229,10 +224,10 @@ def _find_blocked_commands(command: str) -> set[str]:
             if base in _BLOCKED_COMMANDS:
                 blocked.add(base)
 
-    # Regex: blocked words at shell command boundaries that shlex won't see,
-    # e.g. inside an unquoted $(rm -rf), <(rm), backtick chain, or appended to
-    # a separator with no whitespace ("foo;rm"). Anchored to command-position
-    # delimiters; does not match in argument position.
+    # Regex: blocked words at command boundaries shlex won't see, e.g. inside
+    # unquoted $(rm -rf), <(rm), backtick chains, or after a separator with no
+    # whitespace ("foo;rm"). Anchored to command-position delimiters; no match
+    # in argument position.
     lowered = command.lower()
     if _BLOCKED_COMMANDS:
         words_alt = "|".join(re.escape(w) for w in sorted(_BLOCKED_COMMANDS))
@@ -243,11 +238,10 @@ def _find_blocked_commands(command: str) -> set[str]:
         )
         blocked.update(re.findall(pattern, lowered))
 
-    # Nested shell invocations (bash -c 'sudo whoami',
-    #    bash -lc '...', bash --login -c '...', cmd /c '...').
-    #    When a -c or /c flag is found, look backwards for a shell name
-    #    (skipping intermediate flags like --login, -l, -x) and recursively
-    #    scan the nested command string.
+    # Nested shell invocations (bash -c 'sudo whoami', bash -lc '...',
+    #    bash --login -c '...', cmd /c '...'). On a -c or /c flag, look
+    #    backwards for a shell name (skipping flags like --login, -l, -x)
+    #    and recursively scan the nested command string.
     _SHELLS = {"bash", "sh", "zsh", "dash", "ksh", "csh", "tcsh", "fish"}
     _SHELLS_WIN = {"cmd", "cmd.exe"}
     for i, token in enumerate(tokens):
@@ -259,10 +253,9 @@ def _find_blocked_commands(command: str) -> set[str]:
         is_win_c = tok_lower == "/c"
         if not (is_unix_c or is_win_c) or i < 1 or i + 1 >= len(tokens):
             continue
-        # Look backwards past any flags to find the shell binary.
-        # On Unix, flags start with - (skip those). On Windows, flags
-        # start with / but so do absolute paths, so only skip short
-        # single-char /X flags (not /bin/bash style paths).
+        # Look backwards past flags to find the shell binary. Unix flags
+        # start with - (skip). Windows flags start with / but so do absolute
+        # paths, so only skip short single-char /X flags (not /bin/bash).
         for j in range(i - 1, -1, -1):
             prev = tokens[j]
             if prev.startswith("-"):
@@ -282,17 +275,15 @@ def _find_blocked_commands(command: str) -> set[str]:
 def _build_safe_env(workdir: str) -> dict[str, str]:
     """Build a minimal, credential-free environment for sandboxed subprocesses.
 
-    Whitelist-built from scratch -- the parent process env is NOT inherited.
-    Only PATH / HOME / TMPDIR / LANG / TERM / PYTHONIOENCODING (+ VIRTUAL_ENV
-    or Windows SystemRoot when applicable) reach the child. HF_TOKEN,
-    WANDB_API_KEY, AWS_*, GH_TOKEN, OPENAI_API_KEY, LD_PRELOAD, DYLD_*, and
-    every other parent var are absent by construction. HOME points at the
-    sandbox workdir so HF / wandb / aws SDKs cannot read cached credentials
-    from the operator's real ~/.
+    Whitelist-built from scratch; parent env is NOT inherited. Only PATH /
+    HOME / TMPDIR / LANG / TERM / PYTHONIOENCODING (+ VIRTUAL_ENV or Windows
+    SystemRoot when applicable) reach the child. HF_TOKEN, WANDB_API_KEY,
+    AWS_*, GH_TOKEN, OPENAI_API_KEY, LD_PRELOAD, DYLD_*, and all other parent
+    vars are absent. HOME points at the sandbox workdir so HF / wandb / aws
+    SDKs can't read cached credentials from the operator's real ~/.
     """
-    # Start with the directory containing the running Python interpreter
-    # so that subprocess calls to 'python', 'pip', etc. resolve to the
-    # same environment the Studio server is running in.
+    # Start with the running interpreter's directory so 'python', 'pip', etc.
+    # resolve to the same environment the Studio server runs in.
     exe_dir = os.path.dirname(sys.executable)
     path_entries = [exe_dir] if exe_dir else []
 
@@ -354,9 +345,9 @@ def _sandbox_preexec():
         except (OSError, AttributeError):
             pass
 
-        # CLONE_NEWNET intentionally not applied: where userns is enabled it
-        # blocks all egress, including allowlisted hosts. Network policy is
-        # enforced by the AST host check and the bash blocklist.
+        # CLONE_NEWNET not applied: with userns enabled it blocks all egress,
+        # including allowlisted hosts. Network policy is enforced by the AST
+        # host check and the bash blocklist.
 
     if _resource is not None:
         # RLIMIT_NPROC is per-real-UID, so the cap is well above normal usage.
@@ -381,10 +372,9 @@ def _sandbox_preexec():
             pass
         try:
             # Default high enough for multi-shard safetensors mmaps + Python's
-            # own handle count; tunable via env for installs that hit the cap.
-            # Clamp to the inherited hard limit so setrlimit doesn't ValueError
-            # on machines where the parent's hard cap is below the requested
-            # value (would otherwise leave NOFILE at the parent's default).
+            # handle count; tunable via env. Clamp to the inherited hard limit
+            # so setrlimit doesn't ValueError where the parent's hard cap is
+            # below the request (else NOFILE stays at the parent's default).
             nofile = int(os.environ.get("UNSLOTH_STUDIO_SANDBOX_NOFILE", "16384"))
             _soft_cur, hard_cur = _resource.getrlimit(_resource.RLIMIT_NOFILE)
             target = nofile if hard_cur == _resource.RLIM_INFINITY else min(nofile, hard_cur)
@@ -401,8 +391,7 @@ def _get_shell_cmd(command: str) -> list[str]:
 
 
 # Per-session working directories so each chat thread gets its own sandbox.
-# Falls back to a shared ~/studio_sandbox/_default for API callers without a
-# session_id.
+# Falls back to ~/studio_sandbox/_default for callers without a session_id.
 _workdirs: dict[str, str] = {}
 
 
@@ -681,10 +670,10 @@ def execute_tool(
     timeout: int | None = _TIMEOUT_UNSET,
     session_id: str | None = None,
 ) -> str:
-    """Execute a tool by name with the given arguments. Returns result as a string.
+    """Execute a tool by name with the given arguments. Returns a string.
 
-    ``timeout``: int sets per-call limit in seconds, ``None`` means no limit,
-    unset (default) uses ``_EXEC_TIMEOUT`` (300 s).
+    ``timeout``: int = per-call limit in seconds, ``None`` = no limit,
+    unset (default) = ``_EXEC_TIMEOUT`` (300 s).
     ``session_id``: optional thread/session ID for per-conversation sandbox isolation.
     """
     logger.info(f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}")
@@ -726,10 +715,10 @@ def execute_tool(
 
 
 _MAX_PAGE_CHARS = 16000  # limit fetched page text (after HTML-to-MD conversion)
-# Raw download cap.  Must be larger than _MAX_PAGE_CHARS because SSR pages
-# embed large <head> sections (CSS, JS, SVGs) that are stripped during
-# HTML-to-Markdown conversion.  512 KB is enough to reach article content
-# on GitBook / Next.js / Docusaurus pages whose <head> alone can be 200 KB.
+# Raw download cap. Larger than _MAX_PAGE_CHARS because SSR pages embed large
+# <head> sections (CSS, JS, SVGs) stripped during HTML-to-Markdown conversion.
+# 512 KB reaches article content on GitBook / Next.js / Docusaurus pages whose
+# <head> alone can be 200 KB.
 _MAX_FETCH_BYTES = 512 * 1024
 
 _USER_AGENTS = (
@@ -750,14 +739,13 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
 
 
 class _PinnedHTTPSConnection(http.client.HTTPSConnection):
-    """HTTPS connection that connects to a pinned IP but uses a different
-    hostname for SNI and certificate verification.
+    """HTTPS connection to a pinned IP, using a different hostname for SNI
+    and certificate verification.
 
-    The SSRF IP-pinning rewrites URLs to raw IPs.  A normal HTTPSConnection
-    would then send no SNI and verify the cert against the IP, both of which
-    fail.  This subclass splits the two concerns: TCP connects to the pinned
-    IP (``host`` parameter) while TLS uses ``sni_hostname`` for the
-    ClientHello and cert check.
+    SSRF IP-pinning rewrites URLs to raw IPs. A normal HTTPSConnection would
+    then send no SNI and verify the cert against the IP, both of which fail.
+    This subclass splits the concerns: TCP connects to the pinned IP (``host``)
+    while TLS uses ``sni_hostname`` for the ClientHello and cert check.
     """
 
     def __init__(self, host: str, *, sni_hostname: str, **kwargs):
@@ -765,8 +753,8 @@ class _PinnedHTTPSConnection(http.client.HTTPSConnection):
         self._sni_hostname = sni_hostname
 
     def connect(self):
-        # TCP connect to the pinned IP stored in self.host (+ tunnel if
-        # a proxy is configured via set_tunnel, though we do not use one).
+        # TCP connect to the pinned IP in self.host (+ tunnel if a proxy is set
+        # via set_tunnel, though we don't use one).
         http.client.HTTPConnection.connect(self)
         # TLS handshake with the real hostname for SNI + cert verification.
         self.sock = self._context.wrap_socket(
@@ -778,8 +766,8 @@ class _PinnedHTTPSConnection(http.client.HTTPSConnection):
 class _SNIHTTPSHandler(urllib.request.HTTPSHandler):
     """HTTPS handler that sends the correct SNI hostname during TLS handshake.
 
-    The SSRF IP-pinning rewrites URLs to raw IPs, which breaks SNI and cert
-    verification.  This handler returns a ``_PinnedHTTPSConnection`` that
+    SSRF IP-pinning rewrites URLs to raw IPs, breaking SNI and cert
+    verification. This handler returns a ``_PinnedHTTPSConnection`` that
     connects to the pinned IP but verifies TLS against the original hostname.
     """
 
@@ -798,9 +786,9 @@ class _SNIHTTPSHandler(urllib.request.HTTPSHandler):
 def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str]:
     """Resolve *hostname*, reject non-public IPs, return a pinned IP string.
 
-    Returns ``(ok, reason_or_empty, resolved_ip)``.  The caller should
-    connect to *resolved_ip* (with a ``Host`` header) to prevent DNS
-    rebinding between validation and the actual fetch.
+    Returns ``(ok, reason_or_empty, resolved_ip)``. The caller should connect
+    to *resolved_ip* (with a ``Host`` header) to prevent DNS rebinding between
+    validation and the actual fetch.
     """
     import ipaddress
     import socket
@@ -815,14 +803,14 @@ def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str
 
     for *_, sockaddr in infos:
         ip = ipaddress.ip_address(sockaddr[0])
-        # `not ip.is_global` rejects every category the denylist below
-        # also rejects PLUS shared address space (100.64.0.0/10 carrier-
-        # grade NAT) and benchmarking/documentation/exchange ranges that
-        # Python classifies with `is_private=False` and `is_global=False`
+        # `not ip.is_global` rejects every category the denylist below rejects
+        # PLUS shared address space (100.64.0.0/10 carrier-grade NAT) and
+        # benchmarking/documentation/exchange ranges Python marks
+        # `is_private=False` and `is_global=False`
         # (see https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_global).
-        # The explicit predicates after it give human-readable categories
-        # in the error message, but a single non-global check is the
-        # source of truth and prevents future ranges from leaking.
+        # The explicit predicates after it give human-readable categories in
+        # the error message; the non-global check is the source of truth and
+        # prevents future ranges from leaking.
         if (
             not ip.is_global
             or ip.is_private
@@ -872,8 +860,8 @@ def _fetch_page_text(
         ua = random.choice(_USER_AGENTS)
 
         for _hop in range(5):
-            # Pin to the validated IP to prevent DNS rebinding.
-            # Rewrite the URL to use the IP and set the Host header.
+            # Pin to the validated IP (prevents DNS rebinding): rewrite the URL
+            # to the IP and set the Host header.
             cp = urlparse(current_url)
             # Bracket IPv6 addresses so the netloc is valid in a URL.
             ip_str = f"[{pinned_ip}]" if ":" in pinned_ip else pinned_ip
@@ -926,7 +914,7 @@ def _fetch_page_text(
     except Exception as e:
         return f"Failed to fetch URL: {e}"
 
-    # Convert HTML to Markdown using the builtin converter (no external deps)
+    # Convert HTML to Markdown with the builtin converter (no external deps)
     from ._html_to_md import html_to_markdown
 
     text = html_to_markdown(raw_html)
@@ -981,7 +969,7 @@ def _web_search(
 
 def _check_signal_escape_patterns(code: str):
     """
-    Check if code contains patterns that could escape signal-based timeouts.
+    Check for patterns that could escape signal-based timeouts.
 
     Vendored from unsloth_zoo.rl_environments to avoid importing unsloth_zoo
     (which requires GPU drivers and fails on Mac/Apple Silicon).
@@ -1071,8 +1059,8 @@ def _check_signal_escape_patterns(code: str):
             return parts
         return []
 
-    # Keyword argument names that carry command content (as opposed to
-    # control flags like check=True, text=True, capture_output=True).
+    # Kwarg names that carry command content (not control flags like
+    # check=True, text=True, capture_output=True).
     _CMD_KWARGS = frozenset({"args", "command", "executable", "path", "file"})
 
     def _check_args_for_blocked(args_nodes):
@@ -1093,8 +1081,8 @@ def _check_signal_escape_patterns(code: str):
             self.signal_aliases = {"signal"}
             self.os_aliases = {"os"}
             self.subprocess_aliases = {"subprocess"}
-            # Maps bare function names to their fully-qualified form
-            # for from-import tracking (e.g. "system" -> "os.system")
+            # Maps bare function names to fully-qualified form for
+            # from-import tracking (e.g. "system" -> "os.system")
             self.shell_exec_aliases: dict[str, str] = {}
             self.loop_depth = 0
 
@@ -1197,7 +1185,7 @@ def _check_signal_escape_patterns(code: str):
                     )
 
             # --- Shell escape detection ---
-            # Resolve the fully qualified function name for os.*/subprocess.*
+            # Resolve the FQ function name for os.*/subprocess.*
             shell_func = None
             if isinstance(func, ast.Attribute):
                 if isinstance(func.value, ast.Name):
@@ -1229,7 +1217,7 @@ def _check_signal_escape_patterns(code: str):
                 blocked_in_args = _check_args_for_blocked(all_call_args)
 
                 if has_opaque_kwargs:
-                    # Can't inspect dynamic **kwargs -- flag as unsafe
+                    # Can't inspect dynamic **kwargs; flag as unsafe
                     shell_escapes.append(
                         {
                             "type": "shell_escape_dynamic",
@@ -1251,8 +1239,8 @@ def _check_signal_escape_patterns(code: str):
                 else:
                     # Only flag dynamic args for functions that interpret
                     # strings as shell commands, or when shell= might be
-                    # enabled.  Treat any non-literal-False shell= value
-                    # as potentially True (conservative).
+                    # enabled. Treat any non-literal-False shell= value as
+                    # potentially True (conservative).
                     _STRING_SHELL_FUNCS = frozenset(
                         {
                             "os.system",
@@ -1268,7 +1256,7 @@ def _check_signal_escape_patterns(code: str):
                     shell_safe = shell_node is None or (
                         isinstance(shell_node, ast.Constant) and shell_node.value is False
                     )
-                    # Dynamic shell-exec args (chr/format/concat bypasses).
+                    # Dynamic shell-exec args (chr/format/concat bypasses)
                     if (
                         shell_func in _STRING_SHELL_FUNCS
                         or shell_func in _SHELL_EXEC_FUNCS
@@ -1311,10 +1299,9 @@ def _check_signal_escape_patterns(code: str):
                 )
             elif isinstance(node.type, ast.Name):
                 # Only flag BaseException and TimeoutError, NOT Exception.
-                # except Exception does not catch SystemExit or
-                # KeyboardInterrupt, so it cannot suppress timeout
-                # enforcement.  Flagging Exception causes false positives
-                # on normal error-handling patterns.
+                # except Exception doesn't catch SystemExit/KeyboardInterrupt,
+                # so it can't suppress timeout enforcement; flagging it would
+                # false-positive on normal error handling.
                 if node.type.id in ("TimeoutError", "BaseException"):
                     exception_catching.append(
                         {
@@ -1342,9 +1329,9 @@ def _check_signal_escape_patterns(code: str):
     if visitor.imports_signal and not signal_tampering:
         warnings.append("Code imports 'signal' module - review manually for safety")
 
-    # Static host policy: block metadata hosts and any literal host outside
-    # the trusted allowlist; uploads blocked regardless of host. Dynamic hosts
-    # are caught by the bash blocklist instead.
+    # Static host policy: block metadata hosts and any literal host outside the
+    # trusted allowlist; uploads blocked regardless of host. Dynamic hosts are
+    # caught by the bash blocklist instead.
     network_calls: list[dict] = []
     sensitive_file_reads: list[dict] = []
     _NETWORK_FQ_PREFIXES = (
@@ -1591,9 +1578,9 @@ def _check_signal_escape_patterns(code: str):
         return False
 
     # Bare method-name fallback (`x.upload_file(...)`) is intentionally fuzzy,
-    # but should only fire when huggingface_hub / hf_api is actually imported
-    # somewhere in the snippet -- otherwise paramiko.upload_file, boto3
-    # create_commit, etc. hit a false positive. We pre-scan for the imports.
+    # but should only fire when huggingface_hub / hf_api is imported in the
+    # snippet; else paramiko.upload_file, boto3 create_commit, etc. would
+    # false-positive. We pre-scan for the imports.
     _HF_IMPORT_MODULES = (
         "huggingface_hub",
         "hf_api",
@@ -1611,8 +1598,8 @@ def _check_signal_escape_patterns(code: str):
                 if root in _HF_IMPORT_MODULES:
                     return True
             elif isinstance(n, ast.Call) and n.args:
-                # __import__('huggingface_hub'), importlib.import_module('huggingface_hub'),
-                # and bare import_module('huggingface_hub') (via `from importlib import ...`).
+                # __import__('huggingface_hub'), importlib.import_module(...),
+                # and bare import_module(...) (via `from importlib import ...`).
                 arg0 = n.args[0]
                 if not (isinstance(arg0, ast.Constant) and isinstance(arg0.value, str)):
                     continue
@@ -1635,8 +1622,8 @@ def _check_signal_escape_patterns(code: str):
 
         Catches `HfApi().upload_file(...)` (Attribute) and
         `from huggingface_hub import upload_file; upload_file(...)` (Name).
-        The bare-name branch fires only when an HF import is in scope, mirroring
-        the Attribute branch's gating so paramiko/boto3 do not false-positive.
+        The bare-name branch fires only when an HF import is in scope, so
+        paramiko/boto3 don't false-positive.
         """
         if not _hf_in_scope:
             return None
@@ -1649,7 +1636,7 @@ def _check_signal_escape_patterns(code: str):
 
     # Kwargs that ship a credential over the wire. Sandbox env strips HF_TOKEN
     # / WANDB_API_KEY / AWS_* up front, so any value here is hard-coded or
-    # lifted from the parent process.
+    # lifted from the parent.
     _HF_SENSITIVE_KWARGS = frozenset(
         {
             "token",
@@ -1674,14 +1661,14 @@ def _check_signal_escape_patterns(code: str):
     def _reads_env_or_secret(node: ast.AST | None) -> bool:
         """True if any node in the subtree resolves to an env / process read.
 
-        Walking the subtree (not just the root) means wrapper calls like
-        `str(os.environ)`, `json.dumps(os.environ)`, or
-        `'-'.join(os.environ.values())` are caught too.
+        Walking the subtree (not just the root) catches wrapper calls like
+        `str(os.environ)`, `json.dumps(os.environ)`,
+        `'-'.join(os.environ.values())`.
 
         Covers: `os.environ`, `os.environ[K]`, `os.environ.get(K)`, `os.getenv(K)`,
         bare `getenv(K)` (after `from os import getenv`), and
         `subprocess.{run,check_output,Popen,getoutput,getstatusoutput}` which
-        the LLM could use to lift parent env via `printenv` / `env` / `set`.
+        could lift parent env via `printenv` / `env` / `set`.
         """
         if node is None:
             return False
@@ -1729,7 +1716,7 @@ def _check_signal_escape_patterns(code: str):
         if node is None:
             return False
         if isinstance(node, ast.Constant) and isinstance(node.value, (bytes, bytearray)):
-            return True  # inline bytes, no file access
+            return True  # inline bytes; no file access
         if isinstance(node, ast.Constant) and isinstance(node.value, str):
             return _is_safe_relative_path(node.value)
         if isinstance(node, ast.Call):
@@ -1751,10 +1738,10 @@ def _check_signal_escape_patterns(code: str):
 
         Policy: HF uploads are allowed only when (a) no sensitive kwarg is set,
         (b) no positional / keyword value reads `os.environ` or related env
-        readers, and (c) the path argument is a sandbox-local literal -- a
-        relative string with no `..`, an `open(<literal>)`, or inline bytes.
-        Dynamic / variable paths are rejected; the policy cannot prove safety
-        statically and the cost of a wrong-allow is a credential exfiltration.
+        readers, and (c) the path arg is a sandbox-local literal: a relative
+        string with no `..`, an `open(<literal>)`, or inline bytes. Dynamic /
+        variable paths are rejected since safety can't be proven statically and
+        a wrong-allow means credential exfiltration.
         """
         for kw in node.keywords or []:
             if kw.arg in _HF_SENSITIVE_KWARGS:
@@ -1813,7 +1800,7 @@ def _check_signal_escape_patterns(code: str):
                         }
                     )
 
-            # Direct sock.connect((host, port)) bypasses the FQ-prefix branch below.
+            # Direct sock.connect((host, port)) bypasses the FQ-prefix branch.
             if isinstance(node.func, ast.Attribute) and node.func.attr == "connect" and node.args:
                 a0 = node.args[0]
                 host_lit = None
@@ -1947,9 +1934,8 @@ def _check_code_safety(code: str) -> str | None:
     """
     safe, info = _check_signal_escape_patterns(code)
     if not safe:
-        # SyntaxError from ast.parse -- let these through so the subprocess
-        # produces a normal Python traceback instead of a misleading
-        # "unsafe code detected" message.
+        # Let SyntaxError from ast.parse through so the subprocess produces a
+        # normal Python traceback instead of a misleading "unsafe code" message.
         if info.get("error"):
             return None
 
@@ -2032,7 +2018,7 @@ def _python_exec(
 
     tmp_path = None
     workdir = _get_workdir(session_id)
-    # Snapshot image mtimes so we detect both new and overwritten files.
+    # Snapshot image mtimes to detect new and overwritten files.
     _before: dict[str, int] = {}
     if os.path.isdir(workdir):
         for _name in os.listdir(workdir):
@@ -2088,7 +2074,7 @@ def _python_exec(
             result = f"Exit code {proc.returncode}:\n{result}"
         result = _truncate(result) if result.strip() else "(no output)"
 
-        # Detect new or overwritten image files and append sentinel for frontend
+        # Detect new/overwritten images and append sentinel for the frontend
         if session_id and os.path.isdir(workdir):
             new_images = []
             for _name in os.listdir(workdir):
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 525aa53a70..72783f1031 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -4,9 +4,9 @@
 """
 Inference subprocess entry point.
 
-Each inference session runs in a persistent subprocess (mp.get_context("spawn")).
-This gives us a clean Python interpreter with no stale module state —
-solving the transformers version-switching problem completely.
+Each inference session runs in a persistent subprocess
+(mp.get_context("spawn")), giving a clean Python interpreter with no stale
+module state — fully solving the transformers version-switching problem.
 
 The subprocess stays alive while a model is loaded, accepting commands
 (generate, load, unload) via mp.Queue. It exits on shutdown or unload.
@@ -35,7 +35,7 @@ from utils.hardware import apply_gpu_ids
 
 def _activate_transformers_version(model_name: str) -> None:
     """Activate the correct transformers version BEFORE any ML imports."""
-    # Ensure backend is on path for utils imports
+    # Ensure backend is on path for utils imports.
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -96,18 +96,16 @@ def _build_model_config(config: dict):
 def _get_hf_download_state(model_names: list[str] | None = None) -> tuple[int, bool] | None:
     """Return (total_bytes, has_incomplete) for the HF Hub cache, or None on error.
 
-    When *model_names* is provided, only those models' ``blobs/``
-    directories are checked instead of scanning every cached model --
-    much faster on systems with many models. Accepts multiple names so
-    that LoRA loads can watch both the adapter repo and the base model
-    repo simultaneously.
+    When *model_names* is provided, only those models' ``blobs/`` dirs are
+    checked instead of scanning every cached model -- much faster with many
+    models. Accepts multiple names so LoRA loads can watch both the adapter
+    repo and the base model repo at once.
 
     *has_incomplete* is True when any ``*.incomplete`` files exist in the
-    watched blobs directories, indicating that ``huggingface_hub`` is
-    actively downloading.
+    watched blobs dirs, indicating ``huggingface_hub`` is actively downloading.
 
-    Returns None if the state cannot be determined (import error,
-    permission error, etc.) so callers can skip stall logic.
+    Returns None if the state cannot be determined (import error, permission
+    error, etc.) so callers can skip stall logic.
     """
     try:
         from huggingface_hub.constants import HF_HUB_CACHE
@@ -127,12 +125,12 @@ def _get_hf_download_state(model_names: list[str] | None = None) -> tuple[int, b
                     continue
                 # Skip local filesystem paths -- HF model IDs use forward
                 # slashes (org/model) but never start with / . ~ or contain
-                # backslashes. This distinguishes them from absolute paths,
-                # relative paths, and Windows paths.
+                # backslashes, distinguishing them from absolute, relative,
+                # and Windows paths.
                 if name.startswith(("/", ".", "~")) or "\\" in name:
                     continue
                 name = resolve_cached_repo_id_case(name)
-                # HF cache dir format: models--org--name (slashes -> --)
+                # HF cache dir format: models--org--name (slashes -> --).
                 cache_dir_name = "models--" + name.replace("/", "--")
                 blobs_dir = cache / cache_dir_name / "blobs"
                 if blobs_dir.exists():
@@ -165,14 +163,14 @@ def _start_heartbeat(
 ) -> threading.Event:
     """Start a daemon thread that sends periodic status heartbeats.
 
-    Monitors the HF Hub cache directory for download activity. A stall
-    is only reported when ``*.incomplete`` files are present (indicating
-    ``huggingface_hub`` is actively downloading) **and** the total cache
-    size has not changed for *stall_timeout* seconds.
+    Monitors the HF Hub cache for download activity. A stall is reported only
+    when ``*.incomplete`` files are present (``huggingface_hub`` is actively
+    downloading) **and** the total cache size has not changed for
+    *stall_timeout* seconds.
 
-    Once the download finishes (no more ``.incomplete`` files), the stall
-    timer resets, so post-download initialization (quantization, GPU
-    weight loading) is never misclassified as a stalled download.
+    Once the download finishes (no more ``.incomplete`` files), the stall timer
+    resets, so post-download init (quantization, GPU weight loading) is never
+    misclassified as a stalled download.
 
     Returns a stop event -- set it to terminate the heartbeat thread.
     """
@@ -188,7 +186,7 @@ def _start_heartbeat(
             state = _get_hf_download_state(model_names)
             now = time.monotonic()
 
-            # Skip stall logic if we cannot measure the cache
+            # Skip stall logic if we cannot measure the cache.
             if state is None:
                 _send_response(
                     resp_queue,
@@ -206,9 +204,8 @@ def _start_heartbeat(
                 last_size = current_size
                 last_change = now
 
-            # Only fire stall when .incomplete files are present,
-            # confirming a download is actively in progress.
-            # Once downloads finish (no .incomplete), reset the timer
+            # Only fire stall when .incomplete files confirm a download is in
+            # progress. Once downloads finish (no .incomplete), reset the timer
             # so model init time is not counted as a stall.
             if not has_incomplete:
                 last_change = now
@@ -224,7 +221,7 @@ def _start_heartbeat(
                         "ts": time.time(),
                     },
                 )
-                # Only fire once -- the orchestrator will kill us
+                # Only fire once -- the orchestrator will kill us.
                 return
 
             _send_response(
@@ -249,7 +246,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
         hf_token = config.get("hf_token")
         hf_token = hf_token if hf_token and hf_token.strip() else None
 
-        # Auto-detect quantization for LoRA adapters
+        # Auto-detect quantization for LoRA adapters.
         load_in_4bit = config.get("load_in_4bit", True)
         if mc.is_lora and mc.path:
             import json
@@ -280,7 +277,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 except Exception as e:
                     logger.warning("Could not read adapter_config.json: %s", e)
 
-        # Auto-enable trust_remote_code for NemotronH/Nano models only.
+        # Auto-enable trust_remote_code for NemotronH/Nano models only:
         # NemotronH has config parsing bugs requiring trust_remote_code=True.
         # Other transformers 5.x models are native and do NOT need it.
         # NOTE: Must NOT match Llama-Nemotron (standard Llama architecture).
@@ -298,12 +295,12 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                     model_name,
                 )
 
-        # Send heartbeats every 30s so the orchestrator knows we're still alive
-        # (download / weight loading can take a long time on slow connections)
+        # Send heartbeats every 30s so the orchestrator knows we're alive
+        # (download/weight loading can be slow on slow connections).
         xet_disabled = os.environ.get("HF_HUB_DISABLE_XET") == "1"
 
-        # Watch both the model repo and base model repo (for LoRA loads
-        # where the base model download is the actual bottleneck)
+        # Watch both the model repo and base model repo (for LoRA loads where
+        # the base model download is the real bottleneck).
         watch_repos = [mc.identifier]
         base = getattr(mc, "base_model", None)
         if base and str(base) != mc.identifier:
@@ -328,7 +325,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
             heartbeat_stop.set()
 
         if success:
-            # Build model_info for the parent to mirror
+            # Build model_info for the parent to mirror.
             model_info = {
                 "identifier": mc.identifier,
                 "display_name": mc.display_name,
@@ -341,8 +338,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 "audio_type": getattr(mc, "audio_type", None),
                 "has_audio_input": getattr(mc, "has_audio_input", False),
             }
-            # Forward chat_template_info so the parent can classify
-            # capabilities without re-entering the subprocess.
+            # Forward chat_template_info so the parent can classify capabilities
+            # without re-entering the subprocess.
             try:
                 _bm = getattr(backend, "models", {}) or {}
                 _entry = (
@@ -397,22 +394,21 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
 def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
     """Handle a generate command: stream tokens back via resp_queue.
 
-    cancel_event is an mp.Event shared with the parent process.
-    The parent can set it at any time (e.g. user stops generation,
-    or user loads a new model while generating) and generation
-    stops within 1-2 tokens.
+    cancel_event is an mp.Event shared with the parent. The parent can set it
+    at any time (e.g. user stops generation, or loads a new model mid-generate)
+    and generation stops within 1-2 tokens.
     """
     request_id = cmd.get("request_id", "")
 
     try:
-        # Decode image if provided
+        # Decode image if provided.
         image = None
         image_b64 = cmd.get("image_base64")
         if image_b64:
             image = _decode_image(image_b64)
             image = _resize_image(image)
 
-        # Build generation kwargs
+        # Build generation kwargs.
         gen_kwargs = {
             "messages": cmd["messages"],
             "system_prompt": cmd.get("system_prompt", ""),
@@ -426,9 +422,8 @@ def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
             "cancel_event": cancel_event,
         }
 
-        # Optional template/tool plumbing: only forward keys that are
-        # actually present so the backend signature can evolve without
-        # breaking older command payloads.
+        # Optional template/tool plumbing: only forward keys that are present so
+        # the backend signature can evolve without breaking older payloads.
         for opt_key in (
             "tools",
             "enable_thinking",
@@ -438,7 +433,7 @@ def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
             if opt_key in cmd:
                 gen_kwargs[opt_key] = cmd[opt_key]
 
-        # Choose generation path
+        # Choose generation path.
         use_adapter = cmd.get("use_adapter")
         if use_adapter is not None:
             generator = backend.generate_with_adapter_control(
@@ -451,7 +446,7 @@ def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
         logger.info("Starting text generation for request_id=%s", request_id)
 
         for cumulative_text in generator:
-            # cancel_event is an mp.Event — checked instantly, no queue polling
+            # cancel_event is an mp.Event — checked instantly, no queue polling.
             if cancel_event.is_set():
                 logger.info("Generation cancelled for request %s", request_id)
                 break
@@ -508,7 +503,7 @@ def _handle_generate_audio(backend, cmd: dict, resp_queue: Any) -> None:
             use_adapter = cmd.get("use_adapter"),
         )
 
-        # Send WAV bytes as base64 (bytes can't go through mp.Queue directly)
+        # Send WAV bytes as base64 (bytes can't go through mp.Queue directly).
         _send_response(
             resp_queue,
             {
@@ -542,7 +537,7 @@ def _handle_generate_audio_input(backend, cmd: dict, resp_queue: Any, cancel_eve
     try:
         import numpy as np
 
-        # Decode audio array from list (numpy arrays can't go through mp.Queue)
+        # Decode audio array from list (numpy arrays can't go through mp.Queue).
         audio_array = np.array(cmd["audio_data"], dtype = np.float32)
 
         audio_type = cmd.get("audio_type")
@@ -638,12 +633,12 @@ def _handle_unload(backend, cmd: dict, resp_queue: Any) -> None:
 
 
 def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, config: dict) -> None:
-    """Subprocess entrypoint. Persistent — runs command loop until shutdown.
+    """Subprocess entrypoint. Persistent — runs the command loop until shutdown.
 
     Args:
         cmd_queue: mp.Queue for receiving commands from parent.
         resp_queue: mp.Queue for sending responses to parent.
-        cancel_event: mp.Event shared with parent — set by parent to cancel generation.
+        cancel_event: mp.Event the parent sets to cancel generation.
         config: Initial configuration dict with model info.
     """
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
@@ -668,7 +663,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
 
     model_name = config["model_name"]
 
-    # ── 0. MLX fast-path — skip torch/transformers entirely ──
+    # ── 0. MLX fast-path — skip torch/transformers ──
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -702,7 +697,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
             )
             return
 
-        # Enter same command loop as GPU path
+        # Enter the same command loop as the GPU path.
         logger.info("MLX inference subprocess ready, entering command loop")
         while True:
             try:
@@ -760,7 +755,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 )
         return
 
-    # ── 1. Activate correct transformers version BEFORE any ML imports ──
+    # ── 1. Activate transformers version BEFORE any ML imports ──
     try:
         _activate_transformers_version(model_name)
     except Exception as exc:
@@ -775,7 +770,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
         )
         return
 
-    # ── 1b. On Windows, check Triton availability (must be before import torch) ──
+    # ── 1b. Windows: check Triton availability (must precede import torch) ──
     if sys.platform == "win32":
         try:
             import triton  # noqa: F401
@@ -848,8 +843,8 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
         return
 
     # ── 4. Command loop — process commands until shutdown ──
-    # cancel_event is an mp.Event shared with parent — parent can set it
-    # at any time to cancel generation instantly (no queue polling needed).
+    # cancel_event is an mp.Event the parent can set anytime to cancel
+    # generation instantly (no queue polling needed).
     logger.info("Inference subprocess ready, entering command loop")
 
     while True:
@@ -873,8 +868,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 _handle_generate(backend, cmd, resp_queue, cancel_event)
 
             elif cmd_type == "load":
-                # Load a new model (reusing this subprocess)
-                # First unload current model
+                # Load a new model in this subprocess; unload the current one first.
                 if backend.active_model_name:
                     backend.unload_model(backend.active_model_name)
                 _handle_load(backend, cmd, resp_queue)
@@ -891,7 +885,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 _handle_unload(backend, cmd, resp_queue)
 
             elif cmd_type == "cancel":
-                # Redundant with mp.Event but handle gracefully
+                # Redundant with mp.Event but handle gracefully.
                 cancel_event.set()
                 logger.info("Cancel command received")
 
@@ -907,7 +901,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 )
 
             elif cmd_type == "status":
-                # Return current status
+                # Return current status.
                 _send_response(
                     resp_queue,
                     {
@@ -927,7 +921,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
 
             elif cmd_type == "shutdown":
                 logger.info("Shutdown command received, exiting")
-                # Unload all models
+                # Unload all models.
                 for model_name in list(backend.models.keys()):
                     try:
                         backend.unload_model(model_name)
diff --git a/studio/backend/core/tool_healing.py b/studio/backend/core/tool_healing.py
index 77619bcdb3..9ef60e00df 100644
--- a/studio/backend/core/tool_healing.py
+++ b/studio/backend/core/tool_healing.py
@@ -3,24 +3,24 @@
 
 """Tool-call XML parsing and stripping helpers.
 
-Extracted verbatim from studio/backend/core/inference/llama_cpp.py so that
+Extracted verbatim from studio/backend/core/inference/llama_cpp.py so
 external inference servers (llama-server wrappers, llama-swap, custom
-shims) can reuse the same logic without importing the inference
-orchestrator, structlog, httpx, or the rest of the studio backend.
+shims) can reuse the logic without importing the inference orchestrator,
+structlog, httpx, or the rest of the studio backend.
 
-The regexes and function bodies are byte-for-byte identical to the
-original inline implementation in llama_cpp.py. Any change made here must
-preserve that equivalence; tests/python/test_tool_healing_extraction_is_exact.py
+Regexes and function bodies are byte-for-byte identical to the original
+inline implementation in llama_cpp.py; any change must preserve that
+equivalence. tests/python/test_tool_healing_extraction_is_exact.py
 verifies it with AST comparison.
 """
 
 import json
 import re
 
-# Pre-compiled patterns for tool XML stripping. Hyphen in the
-# function/parameter name char-class tracks OpenAI's allowed set so
-# MCP tool names with dashes (mcp__srv__list-issues) and parameter
-# names with dashes (`issue-number`) parse alongside the built-ins.
+# Pre-compiled patterns for tool XML stripping. The hyphen in the
+# function/parameter name char-class tracks OpenAI's allowed set so MCP
+# tool names (mcp__srv__list-issues) and parameter names (`issue-number`)
+# with dashes parse alongside the built-ins.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
     re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
@@ -46,13 +46,13 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
     Handles formats like:
       <tool_call>{"name":"web_search","arguments":{"query":"..."}}</tool_call>
       <tool_call><function=web_search><parameter=query>...</parameter></function></tool_call>
-    Closing tags (</tool_call>, </function>, </parameter>) are all optional
-    since models frequently omit them.
+    Closing tags (</tool_call>, </function>, </parameter>) are all
+    optional since models frequently omit them.
     """
     tool_calls = []
 
-    # Pattern 1: JSON inside <tool_call> tags.
-    # Use balanced-brace extraction that skips braces inside JSON strings.
+    # Pattern 1: JSON inside <tool_call> tags. Balanced-brace extraction
+    # that skips braces inside JSON strings.
     for m in _TC_JSON_START_RE.finditer(content):
         brace_start = m.end() - 1  # position of the opening {
         depth, i = 0, brace_start
@@ -96,11 +96,10 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
     # All closing tags optional -- models frequently omit </parameter>,
     # </function>, and/or </tool_call>.
     if not tool_calls:
-        # Step 1: Find all <function=name> positions and extract their bodies.
-        # Body boundary: use only </tool_call> or next <function= as hard
-        # boundaries.  We avoid using </function> as a boundary because
-        # code parameter values can contain that literal string.
-        # After extracting, we trim a trailing </function> if present.
+        # Step 1: Find all <function=name> positions and extract bodies.
+        # Use only </tool_call> or the next <function= as hard boundaries;
+        # </function> is avoided since code values can contain it. Trim a
+        # trailing </function> afterwards if present.
         func_starts = list(_TC_FUNC_START_RE.finditer(content))
         for idx, fm in enumerate(func_starts):
             func_name = fm.group(1)
@@ -114,18 +113,18 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                 body_end = len(content)
             body_end = min(body_end, next_func)
             body = content[body_start:body_end]
-            # Trim trailing </function> if present (it's the real closing tag)
+            # Trim the real closing </function> tag if present
             body = _TC_FUNC_CLOSE_RE.sub("", body)
 
-            # Step 2: Extract parameters from body.
-            # For single-parameter functions (the common case: code, command,
-            # query), use body end as the only boundary to avoid false matches
-            # on </parameter> inside code strings.
+            # Step 2: Extract parameters from body. For single-parameter
+            # functions (the common code/command/query case), use body end
+            # as the only boundary to avoid matching </parameter> inside
+            # code strings.
             arguments = {}
             param_starts = list(_TC_PARAM_START_RE.finditer(body))
             if len(param_starts) == 1:
-                # Single parameter: value is everything from after the tag
-                # to end of body, trimming any trailing </parameter>.
+                # Single parameter: value is everything after the tag to
+                # end of body, trimming any trailing </parameter>.
                 pm = param_starts[0]
                 val = body[pm.end() :]
                 val = _TC_PARAM_CLOSE_RE.sub("", val)
@@ -134,7 +133,7 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                 for pidx, pm in enumerate(param_starts):
                     param_name = pm.group(1)
                     val_start = pm.end()
-                    # Value ends at next <parameter= or end of body
+                    # Value ends at the next <parameter= or end of body
                     next_param = (
                         param_starts[pidx + 1].start()
                         if pidx + 1 < len(param_starts)
diff --git a/studio/backend/core/training/__init__.py b/studio/backend/core/training/__init__.py
index 6e19805eb0..6ce85aab0d 100644
--- a/studio/backend/core/training/__init__.py
+++ b/studio/backend/core/training/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Training submodule - Training backends and trainer classes
-"""
+"""Training submodule: backends and trainer classes."""
 
 from .training import TrainingBackend, TrainingProgress, get_training_backend
 
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 781c18ff15..c43c269aed 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -3,7 +3,7 @@
 
 """
 Unsloth Training Backend
-Integrates Unsloth training capabilities with the FastAPI backend
+Integrates Unsloth training with the FastAPI backend.
 """
 
 import gc
@@ -14,12 +14,12 @@ import types
 # Prevent tokenizer parallelism deadlocks when datasets uses multiprocessing fork
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
-# Ensure compiled cache modules are importable by any subprocess.
-# On spawn-based platforms (Windows, macOS), spawned dataset.map() workers must
+# Make compiled cache modules importable by any subprocess.
+# On spawn-based platforms (Windows, macOS), spawned dataset.map() workers
 # re-import all top-level modules. The compiled cache's trainer files import
-# torch and unsloth_zoo (which initializes CUDA), making spawn impractical.
-# Propagating UNSLOTH_COMPILE_LOCATION via PYTHONPATH ensures any subprocess
-# (not just Pool workers) can find compiled modules.
+# torch and unsloth_zoo (which inits CUDA), making spawn impractical.
+# Propagating UNSLOTH_COMPILE_LOCATION via PYTHONPATH lets any subprocess
+# (not just Pool workers) find compiled modules.
 # NOTE: Do NOT import unsloth_zoo.compiler here -- it triggers heavy torch/triton imports.
 if sys.platform in ("win32", "darwin"):
     _compile_cache = os.environ.get("UNSLOTH_COMPILE_LOCATION", "unsloth_compiled_cache")
@@ -43,7 +43,7 @@ from utils.hardware import (
 )
 
 # recompile_limit was removed in some ROCm torch builds (e.g. pytorch.org/whl/rocm6.2).
-# Guard so training doesn't crash on RDNA2/RDNA3 with older ROCm torch wheels.
+# Guard so training doesn't crash on RDNA2/RDNA3 with older ROCm wheels.
 if hasattr(torch._dynamo.config, "recompile_limit"):
     torch._dynamo.config.recompile_limit = 64
 from unsloth import FastLanguageModel, FastVisionModel, is_bfloat16_supported
@@ -105,7 +105,7 @@ class TrainingProgress:
     is_training: bool = False
     is_completed: bool = False
     error: Optional[str] = None
-    status_message: str = "Ready to train"  # Current stage message
+    status_message: str = "Ready to train"  # Current stage
     elapsed_seconds: Optional[float] = None
     eta_seconds: Optional[float] = None
     grad_norm: Optional[float] = None
@@ -128,16 +128,16 @@ class UnslothTrainer:
         self.is_training = False
         self.should_stop = False
         self.save_on_stop = True
-        self.load_in_4bit = True  # Track quantization mode for metadata
+        self.load_in_4bit = True  # Quantization mode for metadata
 
         # Model state tracking
-        self.is_cpt = False  # Set to True for Continued Pretraining
+        self.is_cpt = False  # True for Continued Pretraining
         self.is_vlm = False
         self.is_audio = False
         self.is_audio_vlm = False  # Multimodal model (e.g. Gemma 3N) trained on audio data
         self._audio_type = None  # 'csm', 'whisper', 'snac', 'bicodec', 'dac'
         self._cuda_audio_used = False  # Set once after audio CUDA preprocessing; never cleared
-        self._spark_tts_repo_dir = None  # Path to downloaded Spark-TTS repo (for BiCodecTokenizer)
+        self._spark_tts_repo_dir = None  # Downloaded Spark-TTS repo path (for BiCodecTokenizer)
         self.model_name = None
 
         # Training metrics tracking
@@ -149,7 +149,7 @@ class UnslothTrainer:
         # Thread safety
         self._lock = threading.Lock()
 
-        # Store training context for later transfer
+        # Training context for later transfer
         self.training_context = {
             "base_model_name": None,
             "output_dir": None,
@@ -168,13 +168,12 @@ class UnslothTrainer:
         """Lightweight detection and tokenizer load — no model weights, no VRAM.
 
         Sets is_vlm, _audio_type, is_audio_vlm, model_name and loads a
-        lightweight tokenizer for dataset formatting.  Call this before
-        load_and_format_dataset() when you want to process the dataset
-        BEFORE loading the training model (avoids VRAM contention with
-        the LLM-assisted detection helper).
+        lightweight tokenizer for dataset formatting. Call before
+        load_and_format_dataset() to process the dataset BEFORE loading the
+        training model (avoids VRAM contention with the LLM-assisted detector).
 
-        load_model() may be called afterwards — it will re-detect and load
-        the full model + tokenizer, overwriting the lightweight one set here.
+        load_model() may run afterwards — it re-detects and loads the full
+        model + tokenizer, overwriting the lightweight one set here.
         """
         self.model_name = model_name
         self.max_seq_length = max_seq_length
@@ -209,8 +208,8 @@ class UnslothTrainer:
         )
 
         # --- Load lightweight tokenizer/processor (CPU only, no VRAM) ---
-        # Whisper needs AutoProcessor (has feature_extractor + tokenizer).
-        # All others work with AutoTokenizer (CSM loads its own processor inline).
+        # Whisper needs AutoProcessor (feature_extractor + tokenizer); others
+        # use AutoTokenizer (CSM loads its own processor inline).
         if self._audio_type == "whisper":
             from transformers import AutoProcessor
             self.tokenizer = AutoProcessor.from_pretrained(
@@ -239,7 +238,6 @@ class UnslothTrainer:
                 if hasattr(self.training_progress, key):
                     setattr(self.training_progress, key, value)
 
-            # Notify all callbacks
             for callback in self.progress_callbacks:
                 try:
                     callback(self.training_progress)
@@ -322,9 +320,9 @@ class UnslothTrainer:
         *,
         extra_args = None,
     ):
-        """Build training args dict for audio branches.
+        """Build the training args dict for audio branches.
 
-        Constructs the common config (batch size, lr, warmup, fp16/bf16, etc.)
+        Builds the common config (batch size, lr, warmup, fp16/bf16, etc.)
         and applies per-branch overrides via extra_args.
         """
         batch_size = training_args.get("batch_size", 2)
@@ -410,12 +408,12 @@ class UnslothTrainer:
             )
 
     def _cleanup_audio_artifacts(self):
-        """Remove sys.path entries and sys.modules from previous audio preprocessing.
+        """Remove sys.path/sys.modules entries from previous audio preprocessing.
 
-        After audio training, cloned repo dirs (OuteTTS, Spark-TTS) remain on
-        sys.path and heavy audio modules (snac, whisper, sparktts, outetts) stay
-        in sys.modules. When the next training run calls dataset.map(num_proc=N),
-        forked child processes inherit this stale state and deadlock.
+        After audio training, cloned repo dirs (OuteTTS, Spark-TTS) stay on
+        sys.path and heavy modules (snac, whisper, sparktts, outetts) stay in
+        sys.modules. On the next dataset.map(num_proc=N), forked children
+        inherit this stale state and deadlock.
         """
         # Remove cloned audio repo paths from sys.path
         base_dir = os.path.dirname(os.path.abspath(__file__))
@@ -450,10 +448,9 @@ class UnslothTrainer:
         dataset,
         custom_format_mapping: dict = None,
     ):
-        """Resolve audio, text, and speaker columns from user mapping or hardcoded fallback.
+        """Resolve audio/text/speaker columns from user mapping or fallback.
 
-        Returns:
-            dict with keys: audio_col, text_col, speaker_col (speaker_col may be None)
+        Returns dict with keys audio_col, text_col, speaker_col (may be None).
         """
         cols = dataset.column_names
 
@@ -468,7 +465,7 @@ class UnslothTrainer:
                     text_col = col
                 elif role == "speaker_id":
                     speaker_col = col
-            # Use mapping if both required columns exist in the dataset
+            # Use mapping if both required columns exist
             if audio_col and audio_col in cols and text_col and text_col in cols:
                 return {
                     "audio_col": audio_col,
@@ -476,7 +473,7 @@ class UnslothTrainer:
                     "speaker_col": speaker_col,
                 }
 
-        # Hardcoded fallback (existing behavior)
+        # Hardcoded fallback
         audio_col = next((c for c in cols if c.lower() in ("audio", "speech")), None)
         text_col = next(
             (c for c in cols if c.lower() in ("text", "sentence", "transcript", "transcription")),
@@ -508,7 +505,7 @@ class UnslothTrainer:
         gpu_ids: Optional[list[int]] = None,
     ) -> bool:
         """Load model for training (supports both text and vision models)"""
-        self.load_in_4bit = load_in_4bit  # Store for training_meta.json
+        self.load_in_4bit = load_in_4bit  # For training_meta.json
         self.trust_remote_code = trust_remote_code  # For AutoProcessor etc. used during training
         try:
             if self.model is not None:
@@ -522,16 +519,16 @@ class UnslothTrainer:
             logger.info("\nClearing GPU memory before training...")
             clear_gpu_cache()
 
-            # Clean up sys.path and sys.modules from previous audio preprocessing
-            # to prevent deadlocks when forking worker processes in dataset.map()
+            # Clean up sys.path/sys.modules from previous audio preprocessing
+            # to prevent deadlocks when forking dataset.map() workers
             self._cleanup_audio_artifacts()
 
-            # Reload Unsloth-patched transformers modeling modules before clearing
-            # the compiled cache. unsloth_compile_transformers() sets __UNSLOTH_PATCHED__
-            # on each modeling module and replaces methods with exec'd code.
-            # clear_unsloth_compiled_cache() deletes the disk cache, but the flag
-            # prevents re-compilation — leaving missing cache files. Reloading
-            # restores original class definitions so Unsloth can re-compile cleanly.
+            # Reload Unsloth-patched transformers modeling modules before
+            # clearing the compiled cache. unsloth_compile_transformers() sets
+            # __UNSLOTH_PATCHED__ and replaces methods with exec'd code.
+            # clear_unsloth_compiled_cache() deletes the disk cache, but the
+            # flag blocks re-compilation, leaving missing cache files. Reloading
+            # restores original class defs so Unsloth re-compiles cleanly.
             import importlib
 
             for _key, _mod in list(sys.modules.items()):
@@ -540,7 +537,7 @@ class UnslothTrainer:
                         try:
                             importlib.reload(_mod)
                         except Exception:
-                            pass  # Non-critical — Unsloth will handle stale modules
+                            pass  # Non-critical — Unsloth handles stale modules
 
             # Remove stale compiled cache so the new model gets a fresh one
             from utils.cache_cleanup import clear_unsloth_compiled_cache
@@ -549,7 +546,7 @@ class UnslothTrainer:
             clear_unsloth_compiled_cache(preserve_patterns = _preserve)
             # Detect audio model type dynamically (config.json + tokenizer)
             self._audio_type = detect_audio_type(model_name, hf_token)
-            # audio_vlm is detected as an audio_type now, handle it separately
+            # audio_vlm is detected as an audio_type now; handle separately
             if self._audio_type == "audio_vlm":
                 self.is_audio = False
                 self.is_audio_vlm = is_dataset_audio  # Only use audio VLM path if dataset has audio
@@ -561,7 +558,7 @@ class UnslothTrainer:
             if not self.is_audio and not self.is_audio_vlm:
                 self._cuda_audio_used = False
 
-            # VLM: vision model with image dataset (mutually exclusive with audio paths)
+            # VLM: vision model + image dataset (mutually exclusive with audio)
             vision = is_vision_model(model_name, hf_token = hf_token) if not self.is_audio else False
             self.is_vlm = not self.is_audio_vlm and vision and is_dataset_image
             self.model_name = model_name
@@ -583,7 +580,7 @@ class UnslothTrainer:
                 epoch = 0,
             )
 
-            # Update UI immediately with loading message
+            # Update UI with loading message
             model_display = model_name.split("/")[-1] if "/" in model_name else model_name
             model_type_label = "audio" if self.is_audio else ("vision" if self.is_vlm else "text")
             self._update_progress(
@@ -596,15 +593,15 @@ class UnslothTrainer:
             if hf_token:
                 os.environ["HF_TOKEN"] = hf_token
 
-            # Proactive gated-model check: verify access BEFORE from_pretrained.
-            # Catches ALL gated/private models (text, vision, audio) globally.
-            # Skip when offline -- from_pretrained will use the cache.
+            # Proactive gated-model check before from_pretrained. Catches ALL
+            # gated/private models (text, vision, audio) globally. Skip when
+            # offline -- from_pretrained uses the cache.
             if "/" in model_name and not _env_offline():
                 try:
                     from huggingface_hub import model_info as hf_model_info
                     info = hf_model_info(model_name, token = hf_token or None)
-                    # model_info succeeds even for gated repos (metadata is public),
-                    # but info.gated tells us if files require acceptance/token.
+                    # model_info succeeds for gated repos (metadata is public);
+                    # info.gated tells us if files require acceptance/token.
                     if info.gated and not hf_token:
                         friendly = (
                             f"Access denied for '{model_name}'. This model is gated. "
@@ -634,15 +631,15 @@ class UnslothTrainer:
                 f"Using device_map='{device_map}' ({get_visible_gpu_count()} GPU(s) visible)"
             )
 
-            # AMD ROCm hardware without native bfloat16 (e.g. RDNA2 / gfx103x)
-            # crashes with an LLVM error at the first bf16 kernel dispatch if
-            # dtype=None lets unsloth auto-pick bf16. Force float16 there so that
-            # path is never reached. NVIDIA keeps dtype=None so unsloth's own
-            # bf16/fp16/float32 auto-detection (including FORCE_FLOAT32 models) is
-            # honored -- older NVIDIA without bf16 (T4/V100) must NOT be coerced to
-            # float16 here, which the previous unconditional branch did wrongly.
-            # Derive ROCm inline (not hardware.IS_ROCM) because that flag is unset
-            # until detect_hardware() runs, which isn't guaranteed in this subprocess.
+            # AMD ROCm without native bfloat16 (e.g. RDNA2 / gfx103x) crashes
+            # with an LLVM error at the first bf16 kernel dispatch if dtype=None
+            # lets unsloth auto-pick bf16. Force float16 there. NVIDIA keeps
+            # dtype=None so unsloth's bf16/fp16/float32 auto-detection (incl.
+            # FORCE_FLOAT32 models) is honored -- older NVIDIA without bf16
+            # (T4/V100) must NOT be coerced to float16 (the previous
+            # unconditional branch did this wrongly). Derive ROCm inline (not
+            # hardware.IS_ROCM) since that flag is unset until detect_hardware()
+            # runs, not guaranteed in this subprocess.
             _is_rocm = (
                 bool(getattr(torch.version, "hip", None)) or "rocm" in torch.__version__.lower()
             )
@@ -650,7 +647,7 @@ class UnslothTrainer:
 
             # Branch based on model type
             if self._audio_type == "csm":
-                # CSM: FastModel + auto_model=CsmForConditionalGeneration + load_in_4bit=False
+                # CSM: FastModel, auto_model=CsmForConditionalGeneration, load_in_4bit=False
                 from unsloth import FastModel
                 from transformers import CsmForConditionalGeneration
 
@@ -668,7 +665,7 @@ class UnslothTrainer:
                 logger.info("Loaded CSM audio model")
 
             elif self._audio_type == "whisper":
-                # Whisper: FastModel + auto_model=WhisperForConditionalGeneration + load_in_4bit=False
+                # Whisper: FastModel, auto_model=WhisperForConditionalGeneration, load_in_4bit=False
                 from unsloth import FastModel
                 from transformers import WhisperForConditionalGeneration
 
@@ -684,7 +681,7 @@ class UnslothTrainer:
                     token = hf_token,
                     trust_remote_code = trust_remote_code,
                 )
-                # Configure generation settings (notebook lines 100-105)
+                # Generation settings (notebook lines 100-105)
                 self.model.generation_config.language = "<|en|>"
                 self.model.generation_config.task = "transcribe"
                 self.model.config.suppress_tokens = []
@@ -706,8 +703,8 @@ class UnslothTrainer:
                 logger.info(f"Loaded {self._audio_type} audio model (FastLanguageModel)")
 
             elif self._audio_type == "bicodec":
-                # Spark-TTS: download full repo (contains sparktts package + BiCodec weights),
-                # then load only the LLM subfolder with FastModel.
+                # Spark-TTS: download full repo (sparktts package + BiCodec
+                # weights), then load only the LLM subfolder with FastModel.
                 # model_name may be:
                 #   "Spark-TTS-0.5B/LLM"       (local-style, from YAML mapping)
                 #   "unsloth/Spark-TTS-0.5B"    (HF repo ID)
@@ -726,7 +723,7 @@ class UnslothTrainer:
                     llm_path = f"{local_dir}/LLM"
 
                 repo_path = snapshot_download(hf_repo, local_dir = local_dir)
-                self._spark_tts_repo_dir = os.path.abspath(repo_path)  # Absolute path for sys.path
+                self._spark_tts_repo_dir = os.path.abspath(repo_path)  # Absolute for sys.path
                 llm_path = os.path.join(self._spark_tts_repo_dir, "LLM")
 
                 self.model, self.tokenizer = FastModel.from_pretrained(
@@ -756,8 +753,8 @@ class UnslothTrainer:
                 logger.info("Loaded OuteTTS (dac) model (FastModel)")
 
             elif self.is_audio_vlm:
-                # Audio VLM: multimodal model trained on audio (e.g. Gemma 3N)
-                # Uses FastModel (general loader) — returns (model, processor)
+                # Audio VLM: multimodal model trained on audio (e.g. Gemma 3N).
+                # FastModel (general loader) returns (model, processor).
                 from unsloth import FastModel
                 self.model, self.tokenizer = FastModel.from_pretrained(
                     model_name = model_name,
@@ -785,7 +782,7 @@ class UnslothTrainer:
                 )
                 logger.info("Loaded vision model")
 
-                # Diagnostic: check if FastVisionModel returned a real Processor or a raw tokenizer
+                # Diagnostic: did FastVisionModel return a Processor or a raw tokenizer?
                 from transformers import ProcessorMixin
 
                 tok = self.tokenizer
@@ -818,8 +815,7 @@ class UnslothTrainer:
                 return False
 
             if full_finetuning:
-                # Enable training mode for full fine-tuning
-                # This ensures all model parameters are trainable; otherwise, they might be frozen.
+                # Enable training mode so all params are trainable (else frozen)
                 self.model.for_training()
 
             self._update_progress(status_message = "Model loaded successfully")
@@ -832,9 +828,9 @@ class UnslothTrainer:
             ):
                 # Unsloth's patching can leave stale state that makes
                 # inspect.getsource() fail when switching model families
-                # (e.g. gemma3 → gemma3n). The load always succeeds on a
-                # second attempt because the failed first call's partial
-                # imports clean up the stale state as a side effect.
+                # (e.g. gemma3 → gemma3n). The second attempt always succeeds
+                # because the failed first call's partial imports clean up the
+                # stale state as a side effect.
                 self._source_code_retried = True
                 logger.info(f"\n'could not get source code' — retrying once...\n")
                 return self.load_model(
@@ -870,7 +866,7 @@ class UnslothTrainer:
             return False
         except Exception as e:
             error_msg = str(e)
-            # Catch gated/auth errors and surface a friendly message
+            # Surface a friendly message for gated/auth errors
             error_lower = error_msg.lower()
             if any(
                 k in error_lower
@@ -918,14 +914,14 @@ class UnslothTrainer:
             if self.model is None:
                 raise ValueError("Model not loaded. Call load_model() first.")
 
-            # Full finetuning mode - skip PEFT entirely
+            # Full finetuning - skip PEFT entirely
             if not use_lora:
                 self._update_progress(status_message = "Full finetuning mode - no LoRA adapters")
                 logger.info("Full finetuning mode - training all parameters\n")
                 return True
 
-            # LoRA/QLoRA mode - apply PEFT
-            # "all-linear" is a PEFT keyword that targets every linear layer
+            # LoRA/QLoRA - apply PEFT.
+            # "all-linear" is a PEFT keyword targeting every linear layer.
             if isinstance(target_modules, list) and "all-linear" in target_modules:
                 if len(target_modules) == 1:
                     target_modules = "all-linear"
@@ -944,8 +940,7 @@ class UnslothTrainer:
                     "down_proj",
                 ]
 
-            # Validate and normalize gradient_checkpointing
-            # Must be one of: True, False, or "unsloth"
+            # Normalize gradient_checkpointing to True, False, or "unsloth"
             if isinstance(use_gradient_checkpointing, str):
                 use_gradient_checkpointing = use_gradient_checkpointing.strip().lower()
                 if use_gradient_checkpointing == "" or use_gradient_checkpointing == "unsloth":
@@ -955,13 +950,13 @@ class UnslothTrainer:
                 elif use_gradient_checkpointing in ("false", "0", "no"):
                     use_gradient_checkpointing = False
                 else:
-                    # Invalid value, default to "unsloth"
+                    # Invalid value -> "unsloth"
                     logger.warning(
                         f"Invalid gradient_checkpointing value: {use_gradient_checkpointing}, defaulting to 'unsloth'"
                     )
                     use_gradient_checkpointing = "unsloth"
             elif use_gradient_checkpointing not in (True, False, "unsloth"):
-                # Invalid type or value, default to "unsloth"
+                # Invalid type/value -> "unsloth"
                 logger.warning(
                     f"Invalid gradient_checkpointing type/value: {use_gradient_checkpointing}, defaulting to 'unsloth'"
                 )
@@ -974,7 +969,7 @@ class UnslothTrainer:
                 self._update_progress(error = error_msg)
                 return False
 
-            # Check if model has the expected attributes
+            # Check expected attributes
             if not hasattr(self.model, "config"):
                 error_msg = (
                     "Model does not have config attribute - model may not be loaded correctly"
@@ -988,9 +983,9 @@ class UnslothTrainer:
                 f"Gradient checkpointing: {use_gradient_checkpointing} (type: {type(use_gradient_checkpointing).__name__})\n"
             )
 
-            # Branch based on model type: audio, audio_vlm, vision, or text
+            # Branch by model type: audio, audio_vlm, vision, or text
             if self._audio_type in ("csm", "bicodec", "dac") or self.is_audio_vlm:
-                # Models using FastModel.get_peft_model (codec audio + audio VLM)
+                # Use FastModel.get_peft_model (codec audio + audio VLM)
                 from unsloth import FastModel
 
                 label = self._audio_type or "audio_vlm"
@@ -1026,7 +1021,7 @@ class UnslothTrainer:
                 self.model = FastModel.get_peft_model(self.model, **peft_kwargs)
 
             elif self._audio_type == "whisper":
-                # Phase 2: Whisper uses FastModel.get_peft_model with task_type=None
+                # Whisper: FastModel.get_peft_model with task_type=None
                 from unsloth import FastModel
 
                 logger.info(f"Audio model (whisper) LoRA configuration:")
@@ -1047,7 +1042,7 @@ class UnslothTrainer:
                 )
 
             elif self._audio_type == "snac":
-                # Orpheus uses FastLanguageModel.get_peft_model
+                # Orpheus: FastLanguageModel.get_peft_model
                 logger.info(f"Audio model ({self._audio_type}) LoRA configuration:")
                 logger.info(f"  - Target modules: {target_modules}\n")
 
@@ -1135,14 +1130,14 @@ class UnslothTrainer:
             return False
 
     def _apply_csm_forward_fix(self):
-        """Monkey-patch CsmForConditionalGeneration.forward to fix depth decoder kwargs.
+        """Monkey-patch CsmForConditionalGeneration.forward for depth decoder kwargs.
 
-        The original transformers forward passes raw **kwargs (num_items_in_batch,
-        causal_mask, etc.) from the Trainer/PEFT through to the depth decoder,
-        causing depth_decoder_loss=None and 'Tensor + NoneType' crash.
+        The original forward passes raw **kwargs (num_items_in_batch,
+        causal_mask, etc.) from Trainer/PEFT through to the depth decoder,
+        causing depth_decoder_loss=None and a 'Tensor + NoneType' crash.
 
-        We patch at both instance AND class level for maximum reliability,
-        and strip non-TransformersKwargs params that Unsloth/PEFT inject.
+        Patch at both instance AND class level for reliability, and strip
+        non-TransformersKwargs params that Unsloth/PEFT inject.
         """
         import torch
         import torch.nn as nn
@@ -1153,10 +1148,10 @@ class UnslothTrainer:
 
         base_csm = self.model.base_model.model  # CsmForConditionalGeneration
 
-        # Save original forward (the @can_return_tuple wrapped version)
+        # Original forward (@can_return_tuple wrapped version)
         _original_forward = CsmForConditionalGeneration.forward
 
-        # Keys that the depth decoder and its sub-layers actually understand
+        # Keys the depth decoder and its sub-layers understand
         _TRANSFORMERS_KWARGS = {
             "num_items_in_batch",
             "output_hidden_states",
@@ -1183,7 +1178,7 @@ class UnslothTrainer:
             logits_to_keep = 0,
             **kwargs,
         ):
-            # Strip non-standard kwargs injected by Unsloth/PEFT (causal_mask,
+            # Strip non-standard kwargs from Unsloth/PEFT (causal_mask,
             # num_logits_to_keep, task_ids, return_dict, etc.)
             output_attentions = kwargs.pop("output_attentions", None)
             output_hidden_states = kwargs.pop("output_hidden_states", None)
@@ -1247,9 +1242,9 @@ class UnslothTrainer:
                 ]
                 depth_decoder_labels = labels[train_mask]
 
-                # Build clean kwargs for depth decoder
+                # Clean kwargs for depth decoder; scale num_items_in_batch
+                # for its 31 codebooks
                 dd_kwargs = clean_kwargs.copy()
-                # Scale num_items_in_batch for depth decoder (31 codebooks)
                 if "num_items_in_batch" in dd_kwargs:
                     dd_kwargs["num_items_in_batch"] = dd_kwargs["num_items_in_batch"] * (
                         self.config.num_codebooks - 1
@@ -1273,7 +1268,7 @@ class UnslothTrainer:
                         f"labels shape={depth_decoder_labels.shape}, "
                         f"train_mask sum={train_mask.sum().item()}"
                     )
-                    # Fallback: use only backbone loss instead of crashing
+                    # Fallback: use only backbone loss to avoid crashing
                     loss = backbone_loss
                 else:
                     loss = backbone_loss + depth_decoder_loss
@@ -1300,10 +1295,10 @@ class UnslothTrainer:
                 ),
             )
 
-        # Patch at BOTH instance and class level for maximum reliability.
-        # Instance-level: catches calls via BaseTuner.forward -> self.model.forward()
+        # Patch BOTH instance and class level for reliability.
+        # Instance: catches calls via BaseTuner.forward -> self.model.forward()
         base_csm.forward = types.MethodType(_fixed_csm_forward, base_csm)
-        # Class-level: catches any path that resolves through the class dict
+        # Class: catches any path resolving through the class dict
         CsmForConditionalGeneration.forward = _fixed_csm_forward
         logger.info("Applied CSM forward fix (class + instance level)\n")
 
@@ -1322,9 +1317,10 @@ class UnslothTrainer:
             trust_remote_code = getattr(self, "trust_remote_code", False),
         )
 
-        # Strip pad_to_multiple_of from tokenizer init_kwargs — fine-tuned models
-        # (e.g. keanteng/sesame-csm-elise) save it in tokenizer_config.json, and
-        # _merge_kwargs leaks it into audio_kwargs where EncodecFeatureExtractor rejects it.
+        # Strip pad_to_multiple_of from tokenizer init_kwargs — fine-tuned
+        # models (e.g. keanteng/sesame-csm-elise) save it in
+        # tokenizer_config.json, and _merge_kwargs leaks it into audio_kwargs
+        # where EncodecFeatureExtractor rejects it.
         processor.tokenizer.init_kwargs.pop("pad_to_multiple_of", None)
 
         # Resolve columns from user mapping or hardcoded fallback
@@ -1376,7 +1372,7 @@ class UnslothTrainer:
                     }
                 ]
                 # NOTE: pad_to_multiple_of intentionally omitted from text_kwargs —
-                # CsmProcessor._merge_kwargs leaks it to EncodecFeatureExtractor which rejects it.
+                # CsmProcessor._merge_kwargs leaks it to EncodecFeatureExtractor, which rejects it.
                 model_inputs = processor.apply_chat_template(
                     conversation,
                     tokenize = True,
@@ -1433,8 +1429,8 @@ class UnslothTrainer:
     ):
         """Format dataset as audio chat messages for multimodal models (e.g. Gemma 3N).
 
-        Expects columns: audio (Audio), text (str).
-        Produces: messages column with system/user/assistant chat format.
+        Expects columns audio (Audio), text (str). Produces a messages column
+        with system/user/assistant chat format.
         """
         from datasets import Audio
 
@@ -1496,9 +1492,9 @@ class UnslothTrainer:
     ):
         """Preprocess dataset for Orpheus TTS training with SNAC codec.
 
-        Mirrors Orpheus_(3B)-TTS.ipynb: encode audio with SNAC (24kHz, 3 hierarchical
-        layers), interleave 7 codes per frame, wrap with Orpheus special tokens,
-        train on full sequence (no label masking).
+        Mirrors Orpheus_(3B)-TTS.ipynb: encode audio with SNAC (24kHz, 3
+        hierarchical layers), interleave 7 codes per frame, wrap with Orpheus
+        special tokens, train on full sequence (no label masking).
         """
         import torch
         import torchaudio.transforms as T
@@ -1529,12 +1525,12 @@ class UnslothTrainer:
                 f"SNAC dataset needs 'audio' and 'text' columns, got: {dataset.column_names}"
             )
 
-        # Cast audio column so datasets 4.x AudioDecoder objects are decoded to dicts
+        # Cast audio so datasets 4.x AudioDecoder objects decode to dicts
         from datasets import Audio
 
         dataset = dataset.cast_column(audio_col, Audio(sampling_rate = SNAC_SAMPLE_RATE))
 
-        # Get dataset sample rate from first example (after cast, always SNAC_SAMPLE_RATE)
+        # Sample rate from first example (after cast, always SNAC_SAMPLE_RATE)
         first_audio = dataset[0][audio_col]
         ds_sample_rate = (
             first_audio.get("sampling_rate", SNAC_SAMPLE_RATE)
@@ -1582,7 +1578,7 @@ class UnslothTrainer:
                     skipped += 1
                     continue
 
-                # --- Encode audio with SNAC (notebook lines 122-142) ---
+                # --- Encode audio with SNAC (notebook 122-142) ---
                 waveform = (
                     torch.from_numpy(audio_data["array"]).unsqueeze(0).to(dtype = torch.float32)
                 )
@@ -1593,7 +1589,7 @@ class UnslothTrainer:
                 with torch.inference_mode():
                     codes = snac_model.encode(waveform)
 
-                # Interleave 7 codes per frame with layer offsets (notebook lines 134-142)
+                # Interleave 7 codes per frame with layer offsets (notebook 134-142)
                 all_codes = []
                 for i in range(codes[0].shape[1]):
                     all_codes.append(codes[0][0][i].item() + AUDIO_OFFSET)
@@ -1608,14 +1604,14 @@ class UnslothTrainer:
                     skipped += 1
                     continue
 
-                # Deduplicate consecutive frames with same first code (notebook lines 185-207)
+                # Dedup consecutive frames with same first code (notebook 185-207)
                 deduped = all_codes[:7]
                 for i in range(7, len(all_codes), 7):
                     if all_codes[i] != deduped[-7]:
                         deduped.extend(all_codes[i : i + 7])
                 all_codes = deduped
 
-                # --- Build text tokens (notebook lines 217-224) ---
+                # --- Build text tokens (notebook 217-224) ---
                 text_prompt = (
                     f"{example[speaker_col]}: {text}"
                     if has_source and example.get(speaker_col)
@@ -1624,7 +1620,7 @@ class UnslothTrainer:
                 text_ids = tokenizer.encode(text_prompt, add_special_tokens = True)
                 text_ids.append(END_OF_TEXT)
 
-                # --- Build full input_ids (notebook lines 225-234) ---
+                # --- Build full input_ids (notebook 225-234) ---
                 input_ids = (
                     [START_OF_HUMAN]
                     + text_ids
@@ -1639,7 +1635,7 @@ class UnslothTrainer:
                 # Truncate to max_length
                 input_ids = input_ids[:max_length]
 
-                # Labels = input_ids (no masking — Orpheus trains on full sequence)
+                # Labels = input_ids (no masking; Orpheus trains full sequence)
                 labels = list(input_ids)
                 attention_mask = [1] * len(input_ids)
 
@@ -1685,8 +1681,9 @@ class UnslothTrainer:
     ):
         """Preprocess dataset for Spark-TTS training with BiCodec tokenizer.
 
-        Mirrors Spark_TTS_(0_5B).ipynb: encode audio with BiCodec (semantic + global tokens),
-        format as special-token text strings for SFTTrainer with dataset_text_field="text".
+        Mirrors Spark_TTS_(0_5B).ipynb: encode audio with BiCodec (semantic +
+        global tokens), format as special-token text strings for SFTTrainer
+        with dataset_text_field="text".
         """
         import torch
         import numpy as np
@@ -1694,8 +1691,8 @@ class UnslothTrainer:
 
         device = "cuda" if torch.cuda.is_available() else "cpu"
 
-        # The sparktts Python package lives in the SparkAudio/Spark-TTS GitHub repo,
-        # NOT in the unsloth/Spark-TTS-0.5B HF model repo. Clone it if needed.
+        # The sparktts package lives in the SparkAudio/Spark-TTS GitHub repo,
+        # NOT in the unsloth/Spark-TTS-0.5B HF model repo. Clone if needed.
         spark_code_dir = os.path.join(os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
@@ -1732,8 +1729,8 @@ class UnslothTrainer:
                 f"BiCodec dataset needs 'audio' and 'text' columns, got: {dataset.column_names}"
             )
 
-        # Cast audio column so datasets 4.x AudioDecoder objects are decoded to dicts.
-        # Don't resample here — BiCodec's target_sr may differ; the loop handles resampling.
+        # Cast audio so datasets 4.x AudioDecoder objects decode to dicts.
+        # Don't resample here — BiCodec's target_sr may differ; the loop does it.
         from datasets import Audio
 
         dataset = dataset.cast_column(audio_col, Audio())
@@ -1837,7 +1834,7 @@ class UnslothTrainer:
                     ]
                 )
 
-                # Format text with source prefix if available
+                # Prefix text with source if available
                 text_content = (
                     f"{example[speaker_col]}: {text}"
                     if has_source and example.get(speaker_col)
@@ -1891,7 +1888,7 @@ class UnslothTrainer:
             f"BiCodec preprocessing complete: {len(result_dataset)} examples "
             f"({skipped} skipped)\n"
         )
-        # Debug: show first example text (truncated)
+        # Debug: first example text (truncated)
         sample = result_dataset[0]["text"]
         logger.info(f"Sample text (first 200 chars): {sample[:200]}...\n")
         logger.info(f"Sample text length: {len(sample)} chars\n")
@@ -1904,9 +1901,10 @@ class UnslothTrainer:
     ):
         """Preprocess dataset for OuteTTS training with DAC codec.
 
-        Mirrors Oute_TTS_(1B).ipynb DataCreationV3: uses Whisper for word timings,
+        Mirrors Oute_TTS_(1B).ipynb DataCreationV3: Whisper for word timings,
         OuteTTS AudioProcessor for speaker representations, PromptProcessor for
-        training prompts. Outputs text strings for SFTTrainer with dataset_text_field="text".
+        training prompts. Outputs text strings for SFTTrainer with
+        dataset_text_field="text".
         """
         import io
         import tempfile
@@ -1964,7 +1962,7 @@ class UnslothTrainer:
                 f"DAC dataset needs 'audio' and 'text' columns, got: {dataset.column_names}"
             )
 
-        # Cast audio to 24kHz (notebook: dataset.cast_column("audio", Audio(sampling_rate=24000)))
+        # Cast audio to 24kHz (notebook: cast_column("audio", Audio(sampling_rate=24000)))
         from datasets import Audio
 
         dataset = dataset.cast_column(audio_col, Audio(sampling_rate = 24000))
@@ -2079,7 +2077,7 @@ class UnslothTrainer:
                     status_message = f"Preprocessing audio with OuteTTS... {idx + 1}/{len(dataset)}"
                 )
 
-        # Free Whisper from GPU (notebook: data_processor.whisper_model.to('cpu'))
+        # Free Whisper from GPU (notebook: whisper_model.to('cpu'))
         logger.info("Moving Whisper model to CPU...\n")
         whisper_model.to("cpu")
         del whisper_model
@@ -2110,8 +2108,8 @@ class UnslothTrainer:
         """Preprocess dataset for Whisper speech-to-text training.
 
         Mirrors Whisper.ipynb: extract audio features with Whisper's feature
-        extractor, tokenize text labels. Returns (train_data, eval_data) where
-        each is a list of dicts with 'input_features' and 'labels'.
+        extractor, tokenize text labels. Returns (train_data, eval_data),
+        each a list of dicts with 'input_features' and 'labels'.
         """
         from datasets import Audio
 
@@ -2157,11 +2155,11 @@ class UnslothTrainer:
                         skipped += 1
                         continue
 
-                    # Extract audio features (notebook line 112-115)
+                    # Extract audio features (notebook 112-115)
                     features = self.tokenizer.feature_extractor(
                         audio_data["array"], sampling_rate = audio_data["sampling_rate"]
                     )
-                    # Tokenize text (notebook line 116)
+                    # Tokenize text (notebook 116)
                     tokenized_text = self.tokenizer.tokenizer(text)
 
                     processed.append(
@@ -2254,14 +2252,13 @@ class UnslothTrainer:
         is_cpt: bool = False,
     ) -> Optional[tuple]:
         """
-        Load and prepare dataset for training.
+        Load and prepare a dataset for training.
 
         Strategy: format first, then split — ensures both train and eval
-        portions are properly formatted and templated.
+        portions are formatted and templated.
 
-        Returns:
-            Tuple of (dataset_info, eval_dataset) or None on error.
-            eval_dataset may be None if no eval split is available.
+        Returns (dataset_info, eval_dataset) or None on error; eval_dataset
+        may be None if no eval split is available.
         """
         try:
             dataset = None
@@ -2299,10 +2296,10 @@ class UnslothTrainer:
                 return result.dataset
 
             if local_datasets:
-                # Load local datasets using load_dataset() so the result is
-                # Arrow-backed (has cache files).  Dataset.from_list() creates
-                # an in-memory dataset with no cache, which forces num_proc=1
-                # during tokenization/map because sharding requires Arrow files.
+                # Use load_dataset() so the result is Arrow-backed (has cache
+                # files). Dataset.from_list() is in-memory with no cache, which
+                # forces num_proc=1 during tokenization/map (sharding needs
+                # Arrow files).
                 all_files = self._resolve_local_files(local_datasets)
 
                 if all_files:
@@ -2346,8 +2343,7 @@ class UnslothTrainer:
                     and dataset_slice_end >= 0
                     and dataset_slice_end >= _slice_start
                 ):
-                    # Manual slice — stream only the rows we need instead of
-                    # downloading the entire dataset.
+                    # Manual slice — stream only needed rows, not the whole dataset.
                     rows_to_stream = dataset_slice_end + 1
                     logger.info(
                         f"[dataset-slice] Manual slice specified "
@@ -2382,11 +2378,11 @@ class UnslothTrainer:
                     f"Loaded dataset from Hugging Face: {dataset_source} ({n_rows:,} rows)\n"
                 )
 
-                # Resolve eval split from a separate HF split (explicit or auto-detected)
+                # Resolve eval split from a separate HF split (explicit or auto)
                 if eval_enabled:
                     effective_train = train_split or "train"
                     if eval_split and eval_split != effective_train:
-                        # Explicit eval split provided - load it directly
+                        # Explicit eval split — load directly
                         logger.info(f"Loading explicit eval split: '{eval_split}'\n")
                         eval_load_kwargs = {"path": dataset_source, "split": eval_split}
                         if subset:
@@ -2397,12 +2393,12 @@ class UnslothTrainer:
                             f"Loaded eval split '{eval_split}' with {len(eval_dataset)} rows\n"
                         )
                     elif eval_split and eval_split == effective_train:
-                        # Same split as training — will do 80/20 split after formatting
+                        # Same split as training — split 80/20 after formatting
                         logger.info(
                             f"Eval split '{eval_split}' is the same as train split — will split 80/20\n"
                         )
                     else:
-                        # Auto-detect eval split from HF (returns a separate dataset, or None)
+                        # Auto-detect eval split from HF (separate dataset or None)
                         eval_dataset = self._auto_detect_eval_split_from_hf(
                             dataset_source = dataset_source,
                             subset = subset,
@@ -2415,7 +2411,7 @@ class UnslothTrainer:
             if dataset is None:
                 raise ValueError("No dataset provided")
 
-            # Apply index range slicing if requested (inclusive on both ends)
+            # Apply index range slicing if requested (inclusive both ends)
             if dataset_slice_start is not None or dataset_slice_end is not None:
                 total_rows = len(dataset)
                 start = dataset_slice_start if dataset_slice_start is not None else 0
@@ -2575,7 +2571,7 @@ class UnslothTrainer:
     def _auto_detect_eval_split_from_hf(
         self, dataset_source: str, subset: str
     ) -> Optional[Dataset]:
-        """Auto-detect an eval split from HF dataset (separate named split only)."""
+        """Auto-detect an eval split from an HF dataset (named split only)."""
         try:
             from datasets import get_dataset_split_names
 
@@ -2605,14 +2601,13 @@ class UnslothTrainer:
         except Exception as e:
             logger.warning(f"Could not check dataset splits: {e}")
 
-        # No separate HF eval split found — caller will handle programmatic splitting
+        # No separate HF eval split — caller handles programmatic splitting
         return None
 
     def _resolve_eval_split_from_dataset(self, dataset) -> Optional[tuple]:
         """Split a dataset into train and eval portions.
 
-        Returns:
-            Tuple of (train_dataset, eval_dataset), or None if dataset too small.
+        Returns (train_dataset, eval_dataset), or None if too small.
         """
         MIN_EVAL_ROWS = 16
         MIN_TOTAL_ROWS = 32  # Need at least 16 train + 16 eval
@@ -2623,7 +2618,7 @@ class UnslothTrainer:
             return None
 
         eval_size = max(MIN_EVAL_ROWS, min(128, int(0.05 * n)))
-        # Ensure we don't take more than half the dataset
+        # Don't take more than half the dataset
         eval_size = min(eval_size, n // 2)
 
         logger.info(f"Auto-splitting: {eval_size} rows for eval from {n} total\n")
@@ -2669,10 +2664,10 @@ class UnslothTrainer:
             self._update_progress(error = "Model not loaded")
             return False
 
-        # Pre-import heavy transformers modules on the main thread.
-        # Unsloth's patched_import hook (deepseek_v3_moe.py) is not thread-safe
-        # with Python's importlib cache, causing KeyError: 'size' if these are
-        # first imported inside the worker thread.
+        # Pre-import heavy transformers modules on the main thread. Unsloth's
+        # patched_import hook (deepseek_v3_moe.py) isn't thread-safe with
+        # importlib's cache, causing KeyError: 'size' if first imported in the
+        # worker thread.
         import transformers  # noqa: F401 – ensures submodules are cached
         from transformers import (  # noqa: F401
             Trainer as _HFTrainer,
@@ -2730,7 +2725,7 @@ class UnslothTrainer:
         """Worker function for training (runs in separate thread)"""
         try:
             # On spawn-based platforms (Windows, macOS), register all known
-            # compiled-cache directories on sys.path and PYTHONPATH before any
+            # compiled-cache dirs on sys.path/PYTHONPATH before any
             # dataset.map() call so spawned workers can import dynamically
             # compiled modules such as UnslothSFTTrainer.
             if sys.platform in ("win32", "darwin"):
@@ -2759,8 +2754,8 @@ class UnslothTrainer:
 
             # ========== AUDIO TRAINER BRANCH ==========
             if self._audio_type == "csm":
-                # CSM uses plain HF Trainer (NOT SFTTrainer)
-                # Needs remove_unused_columns=False for depth decoder (input_values + cutoffs)
+                # CSM uses plain HF Trainer (NOT SFTTrainer). Needs
+                # remove_unused_columns=False for depth decoder (input_values + cutoffs).
                 from transformers import Trainer as HFTrainer, TrainingArguments
 
                 self._apply_csm_forward_fix()
@@ -2796,9 +2791,9 @@ class UnslothTrainer:
                 return
 
             elif self._audio_type == "snac":
-                # Orpheus: language model with SNAC codec tokens — plain HF Trainer
-                # DataCollatorForSeq2Seq dynamically pads variable-length sequences per batch
-                # (text + audio codes vary in length) and pads labels with -100.
+                # Orpheus: LM with SNAC codec tokens — plain HF Trainer.
+                # DataCollatorForSeq2Seq pads variable-length sequences per
+                # batch (text + audio codes vary) and pads labels with -100.
                 from transformers import (
                     Trainer as HFTrainer,
                     TrainingArguments,
@@ -2890,7 +2885,6 @@ class UnslothTrainer:
                 )
 
             # ========== DATA COLLATOR SELECTION ==========
-            # Detect special model types
             model_name_lower = self.model_name.lower()
             is_deepseek_ocr = "deepseek" in model_name_lower and "ocr" in model_name_lower
 
@@ -2901,11 +2895,10 @@ class UnslothTrainer:
             )
             raw_text_mode = dataset_final_format == "raw_text"
 
-            data_collator = None  # Default to built-in data collator
+            data_collator = None  # Default: built-in collator
             if is_deepseek_ocr:
-                # Special DeepSeek OCR collator - auto-install if needed
+                # DeepSeek OCR collator - auto-install if needed
                 logger.info("Detected DeepSeek OCR model\n")
-                # Ensure DeepSeek OCR module is installed
                 if not _ensure_deepseek_ocr_installed():
                     error_msg = (
                         "Failed to install DeepSeek OCR module. "
@@ -2924,7 +2917,7 @@ class UnslothTrainer:
                     FastVisionModel.for_training(self.model)
                     # DeepSeek OCR's (image_size, base_size, crop_mode) is a
                     # coupled preset; changing image_size alone desyncs the
-                    # per-crop pixel grid from num_queries. Use Gundam.
+                    # per-crop pixel grid from num_queries. Use Gundam preset.
                     if training_args.get("vision_image_size") is not None:
                         logger.info(
                             "Vision image resize ignored for DeepSeek OCR "
@@ -2947,8 +2940,8 @@ class UnslothTrainer:
                     return
 
             elif self.is_audio_vlm and not raw_text_mode:
-                # Audio VLM collator (e.g. Gemma 3N with audio data)
-                # Mirrors the collate_fn from Gemma3N_(4B)-Audio notebook
+                # Audio VLM collator (e.g. Gemma 3N with audio).
+                # Mirrors the collate_fn from Gemma3N_(4B)-Audio notebook.
                 logger.info("Configuring audio VLM data collator...\n")
                 processor = self.tokenizer  # FastModel returns processor as tokenizer
 
@@ -3006,7 +2999,6 @@ class UnslothTrainer:
                 logger.info("Vision data collator configured\n")
 
             # ========== TRAINING CONFIGURATION ==========
-            # Handle warmup_steps vs warmup_ratio
             warmup_steps_val = training_args.get("warmup_steps", None)
             warmup_ratio_val = training_args.get("warmup_ratio", None)
 
@@ -3044,14 +3036,14 @@ class UnslothTrainer:
             )
 
             # On spawn-based platforms (Windows, macOS) with transformers 5.x,
-            # disable DataLoader multiprocessing to avoid issues with modified
-            # sys.path (.venv_t5) in spawned workers.
+            # disable DataLoader multiprocessing to avoid modified sys.path
+            # (.venv_t5) issues in spawned workers.
             if sys.platform in ("win32", "darwin"):
                 import transformers as _tf
                 if _tf.__version__.startswith("5."):
                     config_args["dataloader_num_workers"] = 0
 
-            # Add warmup parameter - use warmup_ratio if provided, otherwise warmup_steps
+            # Use warmup_ratio if provided, else warmup_steps
             if warmup_ratio_val is not None:
                 config_args["warmup_ratio"] = warmup_ratio_val
                 logger.info(f"Using warmup_ratio: {warmup_ratio_val}\n")
@@ -3059,7 +3051,7 @@ class UnslothTrainer:
                 config_args["warmup_steps"] = warmup_steps_val
                 logger.info(f"Using warmup_steps: {warmup_steps_val}\n")
             else:
-                # Default to warmup_steps if neither provided
+                # Default if neither provided
                 config_args["warmup_steps"] = 5
                 logger.info(f"Using default warmup_steps: 5\n")
 
@@ -3072,8 +3064,8 @@ class UnslothTrainer:
             #  If max_steps is specified, use it instead of epochs
             max_steps_val = training_args.get("max_steps", 0)
             if max_steps_val and max_steps_val > 0:
-                del config_args["num_train_epochs"]  # Remove epochs
-                config_args["max_steps"] = max_steps_val  # Use steps instead
+                del config_args["num_train_epochs"]
+                config_args["max_steps"] = max_steps_val
                 logger.info(f"Training for {max_steps_val} steps\n")
             else:
                 logger.info(f"Training for {config_args['num_train_epochs']} epochs\n")
@@ -3100,17 +3092,17 @@ class UnslothTrainer:
             else:
                 logger.info("No eval dataset — evaluation disabled\n")
 
-            # Add model-specific parameters
-            # Use optim and lr_scheduler_type from training_args if provided, otherwise use defaults
+            # Model-specific params: use training_args optim/lr_scheduler_type if given, else defaults
             optim_value = training_args.get("optim", "adamw_8bit")
             lr_scheduler_type_value = training_args.get("lr_scheduler_type", "linear")
 
             if (self.is_vlm or self.is_audio_vlm) and not raw_text_mode:
-                # Vision / audio VLM config (both need skip_prepare_dataset + remove_unused_columns)
-                # Raw-text runs on VLM-capable models are routed to the text path below.
+                # Vision / audio VLM config (both need skip_prepare_dataset +
+                # remove_unused_columns). Raw-text on VLM models goes to the
+                # text path below.
                 label = "audio VLM" if self.is_audio_vlm else "vision"
                 logger.info(f"Configuring {label} model training parameters\n")
-                # Use provided values or defaults for vision models
+                # Provided values or vision defaults
                 optim_value = training_args.get("optim", "adamw_torch_fused")
                 lr_scheduler_type_value = training_args.get("lr_scheduler_type", "cosine")
                 config_args.update(
@@ -3143,7 +3135,7 @@ class UnslothTrainer:
                     }
                 )
 
-                # Only add packing for text models (not DeepSeek OCR which is VLM)
+                # Packing for text models only (DeepSeek OCR is VLM)
                 if not is_deepseek_ocr:
                     packing_enabled = training_args.get("packing", False)
                     config_args["packing"] = packing_enabled
@@ -3164,9 +3156,10 @@ class UnslothTrainer:
             logger.info("Training configuration prepared\n")
             # ========== TRAINER INITIALIZATION ==========
             if self.is_audio_vlm and not raw_text_mode:
-                # Audio VLM (e.g. Gemma 3N + audio): raw Dataset from _format_audio_vlm_dataset
-                # Notebook uses processing_class=processor.tokenizer (text tokenizer only)
-                # Raw-text runs are routed to the text path below.
+                # Audio VLM (e.g. Gemma 3N + audio): raw Dataset from
+                # _format_audio_vlm_dataset. Notebook uses
+                # processing_class=processor.tokenizer (text tokenizer only).
+                # Raw-text runs go to the text path below.
                 train_dataset = dataset if isinstance(dataset, Dataset) else dataset["dataset"]
                 processing_class = (
                     self.tokenizer.tokenizer
@@ -3184,8 +3177,8 @@ class UnslothTrainer:
                     trainer_kwargs["eval_dataset"] = eval_dataset
                 self.trainer = SFTTrainer(**trainer_kwargs)
             elif self.is_vlm and not raw_text_mode:
-                # Image VLM: dataset is dict wrapper from format_and_template_dataset
-                # Raw-text runs are routed to the text path below.
+                # Image VLM: dataset is a dict wrapper from
+                # format_and_template_dataset. Raw-text runs go to the text path below.
                 train_dataset = dataset["dataset"] if isinstance(dataset, dict) else dataset
                 trainer_kwargs = {
                     "model": self.model,
@@ -3198,11 +3191,11 @@ class UnslothTrainer:
                     trainer_kwargs["eval_dataset"] = eval_dataset
                 self.trainer = SFTTrainer(**trainer_kwargs)
             else:
-                # For text-only training, if the tokenizer is actually a Processor
-                # (e.g., Gemma-3 returns a ProcessorMixin even for text), we must
-                # unwrap to the raw tokenizer. Otherwise Unsloth's SFTTrainer detects
-                # ProcessorMixin → sets _is_vlm=True → skips _prepare_dataset entirely,
-                # and the 'text' column never gets tokenized to 'input_ids'.
+                # For text-only training, if the tokenizer is actually a
+                # Processor (e.g. Gemma-3 returns ProcessorMixin even for text),
+                # unwrap to the raw tokenizer. Otherwise Unsloth's SFTTrainer
+                # sets _is_vlm=True, skips _prepare_dataset, and the 'text'
+                # column never gets tokenized to 'input_ids'.
                 from transformers import ProcessorMixin
 
                 sft_tokenizer = self.tokenizer
@@ -3256,14 +3249,13 @@ class UnslothTrainer:
                     if eval_dataset is not None:
                         trainer_kwargs["eval_dataset"] = eval_dataset
                     self.trainer = SFTTrainer(**trainer_kwargs)
-                # Restore the full processor as processing_class so checkpoint
-                # saves include preprocessor_config.json (needed for GGUF export).
+                # Restore full processor as processing_class so checkpoints
+                # include preprocessor_config.json (needed for GGUF export).
                 if sft_tokenizer is not self.tokenizer:
                     self.trainer.processing_class = self.tokenizer
             logger.info("Trainer initialized\n")
 
             # ========== TRAIN ON RESPONSES ONLY ==========
-            # Determine if we should train on responses only
             # Raw-text datasets always train on all tokens.
             instruction_part = None
             response_part = None
@@ -3292,7 +3284,7 @@ class UnslothTrainer:
                 try:
                     logger.info("Configuring train on responses only...\n")
 
-                    # Get the template mapping for this model
+                    # Template mapping for this model
                     model_name_lower = self.model_name.lower()
 
                     if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
@@ -3341,11 +3333,10 @@ class UnslothTrainer:
                     logger.info("Train on responses only configured successfully\n")
 
                     # ── Safety net: check if all samples were filtered out ──
-                    # Unsloth's train_on_responses_only masks non-response
-                    # tokens with -100. If max_seq_length is too short and the
-                    # response portion gets truncated away, EVERY sample ends
-                    # up with all labels == -100 and Unsloth removes them,
-                    # leaving 0 usable training samples.
+                    # train_on_responses_only masks non-response tokens with
+                    # -100. If max_seq_length is too short and the response is
+                    # truncated away, EVERY sample ends up all -100 and Unsloth
+                    # removes them, leaving 0 usable samples.
                     filtered_len = len(self.trainer.train_dataset)
                     original_len = len(dataset["dataset"])
                     dropped = original_len - filtered_len
@@ -3451,7 +3442,7 @@ class UnslothTrainer:
             with open(config_path, "r") as f:
                 config = json.load(f)
 
-            # Determine the training method
+            # Determine training method
             if self.is_cpt:
                 method = "CPT"
             elif self.load_in_4bit:
@@ -3481,7 +3472,7 @@ class UnslothTrainer:
         # If trainer exists, try to stop it gracefully
         if self.trainer:
             try:
-                # The callback will catch should_stop flag and stop the training loop
+                # The callback catches should_stop and stops the loop
                 logger.info("Training will stop at next step...\n")
             except Exception as e:
                 logger.error(f"Error stopping trainer: {e}")
@@ -3506,14 +3497,13 @@ class UnslothTrainer:
 
 def _ensure_deepseek_ocr_installed():
     """
-    Auto-install DeepSeek OCR module if not available.
-    Downloads from HuggingFace hub as a local module.
+    Auto-install the DeepSeek OCR module if missing (from HuggingFace hub as
+    a local module).
 
-    Returns:
-        bool: True if available (either already installed or just installed)
+    Returns True if available (already installed or just installed).
     """
     try:
-        # Try importing to see if already available
+        # Already available?
         from deepseek_ocr.modeling_deepseekocr import format_messages
         logger.info("DeepSeek OCR module already available")
         return True
@@ -3528,20 +3518,20 @@ def _ensure_deepseek_ocr_installed():
         import sys
         import os
 
-        # Get the script directory to install locally
+        # Install locally at project root
         script_dir = os.path.dirname(os.path.abspath(__file__))
-        parent_dir = os.path.dirname(script_dir)  # Go up to project root
+        parent_dir = os.path.dirname(script_dir)  # project root
 
         # Download to project root as 'deepseek_ocr' folder
         local_dir = os.path.join(parent_dir, "deepseek_ocr")
 
         snapshot_download("unsloth/DeepSeek-OCR", local_dir = local_dir, local_dir_use_symlinks = False)
 
-        # Add to sys.path if not already there
+        # Add to sys.path if needed
         if parent_dir not in sys.path:
             sys.path.insert(0, parent_dir)
 
-        # Try importing again
+        # Retry import
         from deepseek_ocr.modeling_deepseekocr import format_messages
 
         logger.info("DeepSeek OCR module installed successfully")
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index d27109aedb..5c5626625b 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -4,12 +4,12 @@
 """
 Training backend — subprocess orchestrator.
 
-Each training job runs in a fresh subprocess (mp.get_context("spawn")),
-solving the transformers version-switching problem. The old in-process
-UnslothTrainer singleton is only used inside the subprocess (worker.py).
+Each training job runs in a fresh subprocess (mp.get_context("spawn")), solving
+the transformers version-switching problem. The old in-process UnslothTrainer
+singleton is only used inside the subprocess (worker.py).
 
-This file orchestrates the subprocess lifecycle, pumps events from the
-worker's mp.Queue, and exposes the same API surface to routes/training.py.
+This file orchestrates the subprocess lifecycle, pumps events from the worker's
+mp.Queue, and exposes the same API surface to routes/training.py.
 
 Pattern follows core/data_recipe/jobs/manager.py.
 """
@@ -47,9 +47,9 @@ _HF_TMP_CHECKPOINT_RE = re.compile(r"^tmp-checkpoint-\d+$")
 def _cleanup_cancelled_checkpoints(output_dir: str | os.PathLike) -> None:
     """Remove only HF Trainer ``tmp-checkpoint-<step>/`` partials after a cancel.
 
-    Completed ``checkpoint-<int>/`` dirs and any non-numeric-suffix tmp dir
-    are user-owned and survive. Symlinked output_dir / children are skipped
-    so containment cannot be bypassed.
+    Completed ``checkpoint-<int>/`` dirs and any non-numeric-suffix tmp dir are
+    user-owned and survive. Symlinked output_dir / children are skipped so
+    containment can't be bypassed.
     """
     out = Path(output_dir)
     if not out.exists() or not out.is_dir() or out.is_symlink():
@@ -95,8 +95,8 @@ PLOT_HEIGHT = 3.5
 
 @dataclass
 class TrainingProgress:
-    """Mirror of trainer.TrainingProgress — kept here so the parent process
-    never needs to import the heavy ML modules."""
+    """Mirror of trainer.TrainingProgress — here so the parent process never
+    imports the heavy ML modules."""
 
     epoch: float = 0
     step: int = 0
@@ -118,7 +118,7 @@ class TrainingProgress:
 class TrainingBackend:
     """
     Training orchestration backend — subprocess-based.
-    Launches a fresh subprocess per training job, communicates via mp.Queue.
+    Launches a fresh subprocess per job, communicates via mp.Queue.
     """
 
     FLUSH_THRESHOLD: int = 10
@@ -136,7 +136,7 @@ class TrainingBackend:
         self._should_stop = False
         self._cancel_requested = False  # True only for stop(save=False)
 
-        # Training Metrics (consumed by routes for SSE and /metrics)
+        # Training metrics (consumed by routes for SSE and /metrics)
         self.loss_history: list = []
         self.lr_history: list = []
         self.step_history: list = []
@@ -169,7 +169,7 @@ class TrainingBackend:
         """Spawn a subprocess to run the full training pipeline.
 
         All kwargs are serialized into a config dict and sent to the worker.
-        Returns True if the subprocess was started successfully.
+        Returns True if the subprocess started successfully.
         """
         with self._lock:
             if self._proc is not None and self._proc.is_alive():
@@ -244,8 +244,8 @@ class TrainingBackend:
             "gpu_ids": kwargs.get("gpu_ids"),
         }
 
-        # Full finetuning always runs in 16-bit. LoRA/QLoRA and CPT preserve the
-        # explicit request so 4-bit adapter/raw-text runs remain possible.
+        # Full finetuning always runs in 16-bit. LoRA/QLoRA and CPT keep the
+        # explicit request so 4-bit adapter/raw-text runs stay possible.
         if config["training_type"] == "Full Finetuning":
             config["load_in_4bit"] = False
 
@@ -296,8 +296,7 @@ class TrainingBackend:
 
         logger.info("Training subprocess started (pid=%s)", proc.pid)
 
-        # Reset state — safe because old pump thread is confirmed dead
-        # and proc.start() succeeded
+        # Reset state — safe: old pump thread confirmed dead, proc.start() succeeded
         self.current_job_id = job_id
         self._should_stop = False
         self._cancel_requested = False
@@ -325,7 +324,7 @@ class TrainingBackend:
         self._stop_queue = stop_queue
         self._proc = proc
 
-        # Eagerly create DB run row so the run appears in history during model loading
+        # Eagerly create DB run row so it appears in history during model loading
         self._ensure_db_run_created()
 
         # Start event pump thread
@@ -368,7 +367,7 @@ class TrainingBackend:
                 proc.join(timeout = 2.0)
 
         # Wait for pump thread to finish DB finalization before returning
-        # (8s covers SQLite's default 5s lock timeout plus execution overhead)
+        # (8s covers SQLite's 5s lock timeout plus execution overhead)
         if self._pump_thread is not None and self._pump_thread.is_alive():
             self._pump_thread.join(timeout = 8.0)
 
@@ -399,7 +398,7 @@ class TrainingBackend:
             if p.is_completed or p.error:
                 return False
 
-            # Check status message for activity indicators
+            # Check status message for activity
             status_lower = (p.status_message or "").lower()
             if any(
                 k in status_lower
@@ -530,9 +529,8 @@ class TrainingBackend:
     def _handle_event(self, event: dict) -> None:
         """Apply a subprocess event to local state.
 
-        State updates happen inside self._lock; DB I/O happens after
-        releasing it so status-polling API endpoints are never blocked
-        by slow SQLite writes.
+        State updates happen inside self._lock; DB I/O happens after releasing
+        it so status-polling endpoints aren't blocked by slow SQLite writes.
         """
         etype = event.get("type")
         db_action: Optional[str] = None
@@ -542,7 +540,7 @@ class TrainingBackend:
             if etype == "progress":
                 self._progress.step = event.get("step", self._progress.step)
                 self._progress.epoch = event.get("epoch", self._progress.epoch)
-                # loss/lr are sanitized below; update progress after coercion
+                # loss/lr sanitized below; update progress after coercion
                 _raw_loss = event.get("loss")
                 _raw_lr = event.get("learning_rate")
                 try:
@@ -580,7 +578,7 @@ class TrainingBackend:
                 if status:
                     self._progress.status_message = status
 
-                # Update metric histories — reuse sanitized values from above
+                # Update metric histories — reuse sanitized values above
                 step = event.get("step", 0)
                 loss = _safe_loss
                 lr = _safe_lr
@@ -616,7 +614,7 @@ class TrainingBackend:
                     else:
                         eval_loss = None
 
-                # Buffer metric for DB flush (loss/lr already sanitized above)
+                # Buffer metric for DB flush (loss/lr already sanitized)
                 self._metric_buffer.append(
                     {
                         "step": step,
@@ -630,7 +628,7 @@ class TrainingBackend:
                     }
                 )
 
-                # Decide which DB action to take after releasing the lock
+                # Pick the DB action to run after releasing the lock
                 if not self._db_run_created and self.current_job_id and self._db_config:
                     db_action = "create_run"
                     db_action_kwargs = {
@@ -784,14 +782,14 @@ class TrainingBackend:
         """Flush buffered metrics to the database and update live progress."""
         if not self._metric_buffer or not self.current_job_id or not self._db_run_created:
             return
-        # Cap buffer to prevent unbounded memory growth
+        # Cap buffer to bound memory growth
         if len(self._metric_buffer) > 500:
             logger.warning(
                 "Metric buffer exceeded 500 entries (%d) — trimming oldest",
                 len(self._metric_buffer),
             )
             self._metric_buffer = self._metric_buffer[-500:]
-        # Snapshot before insert so metrics arriving during the write are preserved
+        # Snapshot before insert so metrics arriving during the write survive
         batch = list(self._metric_buffer)
         try:
             from storage.studio_db import insert_metrics_batch, update_run_progress
@@ -831,7 +829,7 @@ class TrainingBackend:
                 return events
 
     # ------------------------------------------------------------------
-    # Plot generation (unchanged from original)
+    # Plot generation
     # ------------------------------------------------------------------
 
     def _create_loss_plot(
@@ -954,9 +952,9 @@ class TrainingBackend:
     def _transfer_to_inference_backend(self) -> bool:
         """Transfer model to inference backend.
 
-        With subprocess-based training, the model lives in the subprocess
-        and is freed when it exits. Inference must load from the saved
-        checkpoint on disk. This is a no-op placeholder.
+        With subprocess-based training, the model lives in the subprocess and is
+        freed when it exits. Inference must load from the saved checkpoint on
+        disk. No-op placeholder.
         """
         logger.info(
             "_transfer_to_inference_backend: subprocess training — "
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index d5d8186815..e9d98909a6 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -4,11 +4,9 @@
 """
 Training subprocess entry point.
 
-Each training job runs in a fresh subprocess (mp.get_context("spawn")).
-This gives us a clean Python interpreter with no stale module state —
-solving the transformers version-switching problem completely.
-
-Pattern follows core/data_recipe/jobs/worker.py.
+Each job runs in a fresh subprocess (mp.get_context("spawn")): a clean
+interpreter with no stale module state, which solves transformers
+version-switching. Pattern follows core/data_recipe/jobs/worker.py.
 """
 
 from __future__ import annotations
@@ -57,7 +55,7 @@ _FLASH_ATTN_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_FLASHATTN_INSTALL"
 _TILELANG_PACKAGE_VERSION = "0.1.8"
 _APACHE_TVM_FFI_PACKAGE_VERSION = "0.1.9"
 _TILELANG_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_TILELANG_INSTALL"
-# Pin both so plain pip cannot silently upgrade torch under the worker (fla-core needs torch>=2.7).
+# Pin both so plain pip can't silently upgrade torch under the worker (fla-core needs torch>=2.7).
 _FLA_PACKAGE_VERSION = "0.5.0"
 _FLA_CORE_PACKAGE_VERSION = "0.5.0"
 _FLA_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_FLA_INSTALL"
@@ -72,14 +70,13 @@ _TVM_FFI_BROKEN_VERSIONS = ("0.1.10", "0.1.11")
 _FAST_PATH_HOOKS_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS"
 
 # Module-level handle so the torch.library.Library registration survives past
-# run_training_process() and is not garbage collected mid-run.
+# run_training_process() and isn't GC'd mid-run.
 _WINDOWS_ROCM_GROUPED_MM_LIB = None
 
-# Worker subprocesses inherit the parent env but not the parent's
-# os.add_dll_directory registrations. Replicate main.py's Windows ROCm DLL
-# setup at module load so the first `import torch` can find amdhip64.dll even
-# when HIP_PATH\bin is not on the system PATH. Handles retained at module
-# scope so they are not garbage collected.
+# Worker subprocesses inherit the parent env but not its os.add_dll_directory
+# registrations. Replicate main.py's Windows ROCm DLL setup at module load so
+# the first `import torch` finds amdhip64.dll even when HIP_PATH\bin is not on
+# PATH. Handles retained at module scope so they aren't GC'd.
 _ROCM_DLL_HANDLES: list = []
 if sys.platform == "win32":
 
@@ -147,21 +144,20 @@ def _model_wants_causal_conv1d(model_name: str) -> bool:
 
 def _hipcc_gcc_install_dir() -> str | None:
     """Return the highest-numbered ``/usr/lib/gcc/x86_64-linux-gnu/<N>`` that has
-    BOTH the gcc runtime dir AND the corresponding ``/usr/include/c++/<N>`` C++
-    headers, or ``None`` if no match (or non-Linux / non-x86_64).
+    BOTH the gcc runtime dir AND ``/usr/include/c++/<N>`` C++ headers, or
+    ``None`` if no match (or non-Linux / non-x86_64).
 
-    Ubuntu 24.04 ships ``/usr/lib/gcc/x86_64-linux-gnu/14/`` (gcc-14 runtime
-    objects) but does NOT ship ``/usr/include/c++/14`` in its default apt set;
-    libstdc++ headers come from ``libstdc++-13-dev``. ROCm clang-20 picks the
-    highest-numbered runtime dir by default, finds no ``<cstdlib>``, and the
-    HIP source build fails with::
+    Ubuntu 24.04 ships gcc-14 runtime objects but not ``/usr/include/c++/14`` in
+    its default apt set (libstdc++ headers come from ``libstdc++-13-dev``). ROCm
+    clang-20 picks the highest-numbered runtime dir, finds no ``<cstdlib>``, and
+    the HIP source build fails with::
 
         /opt/rocm-X.Y/lib/llvm/lib/clang/20/include/__clang_hip_runtime_wrapper.h:112:10:
           fatal error: 'cstdlib' file not found
 
     Returning a path lets the caller pass ``--gcc-install-dir=<path>`` to clang
-    via ``HIPCC_COMPILE_FLAGS_APPEND``. Mirrors the same loop ``bbf004c`` added
-    to ``studio/setup.sh`` for the llama.cpp HIP build branch (PR #5301).
+    via ``HIPCC_COMPILE_FLAGS_APPEND``. Mirrors the loop ``bbf004c`` added to
+    ``studio/setup.sh`` for the llama.cpp HIP build (PR #5301).
     """
     if not sys.platform.startswith("linux"):
         return None
@@ -300,11 +296,10 @@ def _install_package_wheel_first(
                 pypi_spec,
             ]
 
-    # Source compilation on ROCm can take 10-30 minutes; use a generous
-    # timeout. Non-HIP installs preserve the pre-existing "no timeout"
-    # behaviour so unrelated slow installs (e.g. causal-conv1d source
-    # build on Linux aarch64 or unsupported torch/CUDA combinations)
-    # are not aborted at 5 minutes by this PR.
+    # ROCm source compilation can take 10-30 min; use a generous timeout.
+    # Non-HIP installs keep the pre-existing "no timeout" behaviour so unrelated
+    # slow installs (e.g. causal-conv1d source build on Linux aarch64, or
+    # unsupported torch/CUDA combos) aren't aborted at 5 minutes.
     _run_kwargs: dict[str, Any] = {
         "stdout": _sp.PIPE,
         "stderr": _sp.STDOUT,
@@ -313,15 +308,14 @@ def _install_package_wheel_first(
     if is_hip:
         _run_kwargs["timeout"] = 1800
         # On Ubuntu 24.04 + ROCm clang-20, the HIP source build (causal-conv1d,
-        # mamba-ssm source fallback, flash-attn source fallback) defaults to
+        # mamba-ssm / flash-attn source fallbacks) defaults to
         # /usr/lib/gcc/x86_64-linux-gnu/14/ which has the runtime dir but no
         # /usr/include/c++/14 headers, and dies at:
         #   __clang_hip_runtime_wrapper.h:112:10:
         #     fatal error: 'cstdlib' file not found
-        # Inject --gcc-install-dir for a gcc whose C++ headers actually exist.
-        # Respect any pre-existing --gcc-install-dir in HIPCC_COMPILE_FLAGS_APPEND
-        # (user knows best); otherwise append. Mirrors the same fix bbf004c
-        # added to studio/setup.sh for the llama.cpp HIP build (PR #5301).
+        # Inject --gcc-install-dir for a gcc whose C++ headers exist. Respect any
+        # pre-existing --gcc-install-dir in HIPCC_COMPILE_FLAGS_APPEND; else
+        # append. Mirrors fix bbf004c in studio/setup.sh (llama.cpp HIP, PR #5301).
         _existing_flags = os.environ.get("HIPCC_COMPILE_FLAGS_APPEND", "")
         if "--gcc-install-dir" not in _existing_flags:
             _gcc_dir = _hipcc_gcc_install_dir()
@@ -369,9 +363,9 @@ def _install_package_wheel_first(
             )
         else:
             if sys.platform == "win32":
-                # No prebuilt wheel and no source build toolchain on Windows --
-                # this is expected for packages like causal-conv1d.  Log at
-                # info so users aren't alarmed by what looks like an error.
+                # No prebuilt wheel and no source toolchain on Windows --
+                # expected for packages like causal-conv1d. Log at info so
+                # users aren't alarmed by what looks like an error.
                 logger.info(
                     "%s is not available on Windows (no prebuilt wheel); skipping",
                     display_name,
@@ -487,7 +481,7 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
         )
         return False
 
-    # Probe once; reuse result so the --force-reinstall decision and the short-circuit
+    # Probe once; reuse so the --force-reinstall decision and the short-circuit
     # share the same call count (stable for tests).
     already_importable = _flash_linear_attention_importable()
     if already_importable and _flash_linear_attention_current(already_importable = True):
@@ -499,7 +493,7 @@ def _ensure_flash_linear_attention_unconditional(event_queue: Any) -> bool:
         f"Installing flash-linear-attention=={_FLA_PACKAGE_VERSION} for faster training...",
     )
 
-    # `--no-deps` blocks the silent torch upgrade; we bring the non-torch runtime deps in by hand.
+    # `--no-deps` blocks the silent torch upgrade; bring non-torch runtime deps in by hand.
     specs = [
         *_FLA_RUNTIME_DEPS,
         f"fla-core=={_FLA_CORE_PACKAGE_VERSION}",
@@ -616,7 +610,7 @@ _MODEL_NAME_SEP_CHARS = ("-", ".", "/", " ")
 
 
 def _discover_fla_model_types() -> frozenset[str]:
-    """Model_types in the installed transformers whose modeling file imports `from fla.*`."""
+    """Installed-transformers model_types whose modeling file imports `from fla.*`."""
     global _TRANSFORMERS_FLA_MODEL_TYPES_CACHE
     if _TRANSFORMERS_FLA_MODEL_TYPES_CACHE is not None:
         return _TRANSFORMERS_FLA_MODEL_TYPES_CACHE
@@ -690,17 +684,17 @@ def _torch_has_hip() -> bool:
 def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
     """Classify a ROCm device as unified-memory (APU) or discrete.
 
-    Returns ``(gcn_arch, is_unified)`` where:
-    - ``gcn_arch`` is the canonical arch string (e.g. ``"gfx1151"``) when a
-      known attribute is present, or ``""`` when all arch attrs are absent.
-    - ``is_unified`` is ``True`` for AMD APUs with a shared GPU/system-RAM pool
+    Returns ``(gcn_arch, is_unified)``:
+    - ``gcn_arch``: canonical arch string (e.g. ``"gfx1151"``) when a known
+      attribute is present, else ``""``.
+    - ``is_unified``: ``True`` for AMD APUs with a shared GPU/system-RAM pool
       (gfx1150 Strix Point, gfx1151 Strix Halo) — these need a lower
-      ``set_per_process_memory_fraction`` cap to leave headroom for the OS.
+      ``set_per_process_memory_fraction`` cap to leave OS headroom.
 
     Classification priority:
     1. ``gcnArchName`` / variant spellings (stable, naming-independent).
-    2. Device-name substring match as a last-resort fallback when all arch
-       attrs are absent (AMD SDK / Radeon wheels may not populate them):
+    2. Device-name substring match (last resort when all arch attrs absent;
+       AMD SDK / Radeon wheels may not populate them):
          - gfx1150 Strix Point: ``Radeon 890M``, ``Radeon 880M``
          - gfx1151 Strix Halo:  ``Radeon 8060S`` (Ryzen AI MAX+ 395),
                                 ``Radeon 8050S`` (cut-down SKU)
@@ -726,7 +720,7 @@ def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
 def _tilelang_platform_supported() -> bool:
     """True iff a tilelang 0.1.8 wheel will load: Linux x86_64/aarch64, non-HIP torch.
 
-    HIP excluded because tilelang 0.1.8 has no HIP GEMM instruction and crashes mid-backward.
+    HIP excluded: tilelang 0.1.8 has no HIP GEMM and crashes mid-backward.
     """
     import platform as _platform
 
@@ -770,9 +764,10 @@ def _run_pip(cmd: list[str], event_queue: Any, label: str) -> bool:
 def _ensure_tilelang_backend_unconditional(event_queue: Any) -> bool:
     """Install pinned tilelang + apache-tvm-ffi; two-step repair if a broken tvm-ffi is present.
 
-    Returns True iff both import post-call. Step 1 surgically downgrades a broken tvm-ffi
-    with --force-reinstall --no-deps so torch / CUDA stay untouched; step 2 is a regular
-    install for missing transitive deps. Bypass via UNSLOTH_STUDIO_SKIP_TILELANG_INSTALL=1.
+    Returns True iff both import post-call. Step 1 downgrades a broken tvm-ffi
+    with --force-reinstall --no-deps so torch / CUDA stay untouched; step 2 is a
+    regular install for missing transitive deps. Bypass via
+    UNSLOTH_STUDIO_SKIP_TILELANG_INSTALL=1.
     """
     if os.getenv(_TILELANG_SKIP_ENV) == "1":
         return False
@@ -800,7 +795,7 @@ def _ensure_tilelang_backend_unconditional(event_queue: Any) -> bool:
         logger.info("tilelang + apache-tvm-ffi already installed")
         return True
 
-    # Step 1: --no-deps keeps --force-reinstall from touching torch/CUDA via the dep graph.
+    # Step 1: --no-deps keeps --force-reinstall off torch/CUDA via the dep graph.
     if needs_repair:
         logger.info(
             "Forcing apache-tvm-ffi downgrade: %s is on the broken list",
@@ -822,7 +817,7 @@ def _ensure_tilelang_backend_unconditional(event_queue: Any) -> bool:
         if not _run_pip(repair_cmd, event_queue, "TileLang backend repair"):
             return False
 
-    # Step 2: regular install pulls in transitive deps (z3-solver, ml-dtypes) without touching torch.
+    # Step 2: regular install pulls transitive deps (z3-solver, ml-dtypes) without touching torch.
     _send_status(
         event_queue,
         f"Installing TileLang=={_TILELANG_PACKAGE_VERSION} for faster training...",
@@ -855,9 +850,9 @@ def _ensure_tilelang_backend(event_queue: Any, model_name: str) -> None:
 
 
 # ── Fast-path hooks ──
-# Wrap transformers' is_{flash_linear_attention,causal_conv1d}_available so the first call
-# (at modeling import time) drives the install. Any model that queries the gate gets the
-# install; models that never query it (Llama, Gemma, dense Qwen) pay nothing.
+# Wrap transformers' is_{flash_linear_attention,causal_conv1d}_available so the
+# first call (at modeling import) drives the install. Models that query the gate
+# get the install; those that never query it (Llama, Gemma, dense Qwen) pay nothing.
 # UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 falls back to the legacy substring path.
 
 
@@ -894,8 +889,8 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
         logger.info("Fast-path hooks disabled via env; using substring fallback")
         return
 
-    # On HIP torch, even already-installed tilelang crashes FLA's TileLang dispatch.
-    # User can override with FLA_TILELANG=1.
+    # On HIP torch, even installed tilelang crashes FLA's TileLang dispatch.
+    # Override with FLA_TILELANG=1.
     if _torch_has_hip() and os.environ.get("FLA_TILELANG") is None:
         os.environ["FLA_TILELANG"] = "0"
         logger.info(
@@ -937,8 +932,8 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
                     logger.warning("%s install raised: %s; falling back to torch", gate_name, exc)
                     ok = False
                 logger.info("%s hook done; available=%s", gate_name, ok)
-            # post_available_fn handles "gate already True but ancillary kernel broken" (e.g. tilelang
-            # missing while FLA imports fine); skip when install_fn already chained the follow-up.
+            # post_available_fn handles "gate already True but ancillary kernel broken"
+            # (e.g. tilelang missing while FLA imports); skip when install_fn already chained it.
             if ok and not ran_install and post_available_fn is not None:
                 try:
                     post_available_fn(event_queue)
@@ -966,7 +961,7 @@ def _install_fast_path_hooks(event_queue: Any, model_name: str) -> None:
         return True
 
     def _fla_post_available(eq: Any) -> None:
-        # FLA already imports; repair tilelang if missing or on the broken tvm-ffi list.
+        # FLA imports; repair tilelang if missing or on the broken tvm-ffi list.
         if not _model_wants_tilelang(model_name):
             return
         if _installed_tvm_ffi_version() not in _TVM_FFI_BROKEN_VERSIONS and _tilelang_importable():
@@ -1057,8 +1052,8 @@ def _mlx_vlm_max_resized_size(width: int, height: int, target: int) -> tuple[int
     largest_side = max(width, height)
     if largest_side <= target:
         return width, height
-    # Integer formula matches unsloth_zoo's collator (Python round() differs
-    # by 1px on half-pixel cases). max(1, _) avoids zero-side degenerate output.
+    # Integer formula matches unsloth_zoo's collator (Python round() differs by
+    # 1px on half-pixel cases). max(1, _) avoids a zero-side degenerate output.
     new_w = max(1, (width * target + largest_side // 2) // largest_side)
     new_h = max(1, (height * target + largest_side // 2) // largest_side)
     return new_w, new_h
@@ -1079,9 +1074,9 @@ def _resize_mlx_vlm_image(image, resize):
     if new_size != image.size:
         resampling = getattr(Image, "Resampling", Image).LANCZOS
         image = image.resize(new_size, resampling)
-    # When a resize is requested, hand mlx-vlm a writable RGB ndarray so its
-    # PIL-path square-resize is skipped and HF processors don't warn on
-    # non-writable views. resize=None (Default) above keeps the original PIL.
+    # On resize, hand mlx-vlm a writable RGB ndarray so its PIL-path
+    # square-resize is skipped and HF processors don't warn on non-writable
+    # views. resize=None above keeps the original PIL.
     return np.array(image, copy = True)
 
 
@@ -1092,12 +1087,12 @@ def _resize_mlx_vlm_images(value, resize):
 
 
 def _adapt_for_mlx_vlm(items, resize = None):
-    """Adapt GPU-path VLM dataset output for mlx-vlm consumption.
+    """Adapt GPU-path VLM dataset output for mlx-vlm.
 
-    The GPU path embeds PIL images inside messages content as
-    {"type": "image", "image": PIL_Image}. mlx-vlm's prepare_inputs
-    needs images at top-level to produce pixel_values — regardless of
-    model type. Extract them and leave bare {"type": "image"} placeholders.
+    The GPU path embeds PIL images in message content as
+    {"type": "image", "image": PIL_Image}, but mlx-vlm's prepare_inputs needs
+    images at top-level to produce pixel_values (any model type). Extract them
+    and leave bare {"type": "image"} placeholders.
     """
     adapted = []
     for item in items:
@@ -1218,8 +1213,8 @@ def _mlx_local_dataset_loader_for_files(files: list[str]) -> str:
 def _run_mlx_training(event_queue, stop_queue, config):
     """Self-contained MLX training path for Apple Silicon.
 
-    Uses MLXTrainer from unsloth_zoo directly -- no torch/SFTTrainer needed.
-    Mirrors the event_queue protocol so the parent process pump works unchanged.
+    Uses unsloth_zoo's MLXTrainer directly (no torch/SFTTrainer). Mirrors the
+    event_queue protocol so the parent process pump works unchanged.
     """
     import time
     import math
@@ -1276,8 +1271,8 @@ def _run_mlx_training(event_queue, stop_queue, config):
     lr_scheduler_type = _normalize_mlx_studio_scheduler(config.get("lr_scheduler_type", "linear"))
 
     # ── 1. Load model ──
-    # Force text-only if the dataset is not an image dataset, even if the model
-    # has vision capabilities (e.g. Qwen3.5-VL trained on plain alpaca text).
+    # Force text-only for non-image datasets even on vision-capable models
+    # (e.g. Qwen3.5-VL trained on plain alpaca text).
     _send("status", status_message = f"Loading {model_name}...")
     is_dataset_image = bool(config.get("is_dataset_image", False))
     training_type = config.get("training_type", "LoRA/QLoRA")
@@ -1314,8 +1309,8 @@ def _run_mlx_training(event_queue, stop_queue, config):
         )
 
     # ── 2. Apply LoRA / full FT ──
-    # Pass gradient_checkpointing as string ("mlx"/"unsloth"/"none"/etc.)
-    # get_peft_model and MLXTrainer both accept strings and handle them.
+    # gradient_checkpointing stays a string ("mlx"/"unsloth"/"none"/etc.);
+    # get_peft_model and MLXTrainer both accept and handle strings.
     gc_setting = config.get("gradient_checkpointing", "mlx")
     if isinstance(gc_setting, str):
         use_grad_checkpoint = (
@@ -1418,8 +1413,8 @@ def _run_mlx_training(event_queue, stop_queue, config):
         eval_dataset = _load_local(config["local_eval_datasets"])
 
     # ── 3b. Format dataset (VLM or text) ──
-    # Reuse the GPU path's format pipeline for both VLM (auto-detects OCR/caption/
-    # llava/sharegpt+images) and text (alpaca/sharegpt/chatml → "text" column).
+    # Reuse the GPU format pipeline for VLM (auto-detects OCR/caption/llava/
+    # sharegpt+images) and text (alpaca/sharegpt/chatml → "text" column).
     format_type = config.get("format_type", "")
     try:
         from utils.datasets import format_and_template_dataset
@@ -1511,7 +1506,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
     output_dir = config.get("output_dir", "")
     if not output_dir:
         output_dir = f"{model_name.replace('/', '_')}_{int(time.time())}"
-    # Resolve to ~/.unsloth/studio/outputs/ so the export page can find it
+    # Resolve to ~/.unsloth/studio/outputs/ so the export page finds it
     from utils.paths import resolve_output_dir, ensure_dir
 
     output_dir = str(resolve_output_dir(output_dir))
@@ -1525,9 +1520,9 @@ def _run_mlx_training(event_queue, stop_queue, config):
     else:
         eval_steps_val = int(eval_steps_val)
 
-    # MLX: per-element clip to [-1, 1]; norm clip disabled (it needs a
-    # global reduction that breaks MLX's eager pipeline). 1.0 (not 5.0):
-    # |g_i| > 5 rarely fires, so the historical 5.0 was effectively no-op.
+    # MLX: per-element clip to [-1, 1]; norm clip disabled (its global reduction
+    # breaks MLX's eager pipeline). 1.0 not 5.0: |g_i| > 5 rarely fires, so the
+    # historical 5.0 was effectively a no-op.
     max_grad_norm = 0.0
     max_grad_value = 1.0  # TODO: expose MLX grad-clip in Studio UI for power users
 
@@ -1561,7 +1556,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
         ),
     )
 
-    # Tell the parent that eval is configured so the frontend shows the eval chart
+    # Tell the parent eval is configured so the frontend shows the eval chart
     if eval_dataset is not None and eval_steps_val > 0:
         _send("eval_configured")
 
@@ -1716,7 +1711,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
             except _queue.Empty:
                 continue
             except (EOFError, OSError):
-                # why safe: pipe permanently broken, no further messages can arrive
+                # Safe: pipe permanently broken, no more messages can arrive.
                 return
 
     stop_thread = threading.Thread(target = _poll_stop, daemon = True)
@@ -1753,15 +1748,15 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     """Subprocess entrypoint. Fresh Python — no stale module state.
 
     Args:
-        event_queue: mp.Queue for sending progress/status/error events to parent.
-        stop_queue: mp.Queue for receiving stop commands from parent.
-        config: Training configuration dict with all parameters.
+        event_queue: mp.Queue for progress/status/error events to the parent.
+        stop_queue: mp.Queue for stop commands from the parent.
+        config: Training config dict with all parameters.
     """
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
     os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
 
-    # Offline auto-detect: skip ~25s of HF retries per call when DNS is
-    # dead. Scoped to this subprocess (orchestrator spawns a fresh one).
+    # Offline auto-detect: skip ~25s of HF retries per call when DNS is dead.
+    # Scoped to this subprocess (orchestrator spawns a fresh one).
     if "HF_HUB_OFFLINE" not in os.environ:
         import socket as _socket
         import threading as _threading
@@ -1807,7 +1802,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
 
     # ── 0. MLX FAST-PATH (must run before any torch/transformers imports) ──
     # Apple Silicon uses MLXTrainer directly -- skip transformers version
-    # activation, causal-conv1d install, and torch imports entirely.
+    # activation, causal-conv1d install, and torch imports.
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -1827,7 +1822,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             )
             return
         # Activate correct transformers version (Gemma-4 needs 5.5.0, etc.)
-        # Must happen before any transformers/mlx-lm imports in _run_mlx_training.
+        # before any transformers/mlx-lm imports in _run_mlx_training.
         try:
             _activate_transformers_version(model_name)
         except Exception:
@@ -1860,10 +1855,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         return
 
     # ── 1a. Auto-enable trust_remote_code for NemotronH/Nano models ──
-    # NemotronH has config parsing bugs in transformers that require
-    # trust_remote_code=True as a workaround. Other transformers 5.x models
-    # (Qwen3.5, Gemma 4, etc.) are native and do NOT need it — enabling it
-    # bypasses the compiler (disabling fused CE).
+    # NemotronH has transformers config-parsing bugs needing trust_remote_code=True
+    # as a workaround. Other transformers 5.x models (Qwen3.5, Gemma 4, etc.) are
+    # native and do NOT need it — enabling it bypasses the compiler (disabling fused CE).
     # NOTE: Must NOT match Llama-Nemotron (standard Llama architecture).
     _NEMOTRON_TRUST_SUBSTRINGS = ("nemotron_h", "nemotron-h", "nemotron-3-nano")
     _lowered = model_name.lower()
@@ -1880,19 +1874,17 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
 
     # ── 1b. Install fast-path kernel libraries for the chosen model.
     #
-    # 1) causal-conv1d ALWAYS runs eagerly via the substring path.
-    #    Some SSM modeling files (nemotron_h, falcon_h1, granitemoehybrid)
-    #    use `lazy_load_kernel("causal-conv1d")` directly and never call
-    #    transformers' `is_causal_conv1d_available()`, so the runtime
-    #    hook on that gate would not fire for them.
-    # 2) FLA + tilelang: primary gate is the runtime hook on transformers'
-    #    `is_flash_linear_attention_available`. Models whose architecture
-    #    queries that gate auto-trigger the install; others never pay.
-    #    `_install_fast_path_hooks` also wraps `is_causal_conv1d_available`
-    #    as a defence in depth for newer modeling files that do use it.
+    # 1) causal-conv1d ALWAYS runs eagerly via the substring path. Some SSM
+    #    modeling files (nemotron_h, falcon_h1, granitemoehybrid) call
+    #    `lazy_load_kernel("causal-conv1d")` directly and never call
+    #    `is_causal_conv1d_available()`, so the runtime hook wouldn't fire.
+    # 2) FLA + tilelang: primary gate is the runtime hook on
+    #    `is_flash_linear_attention_available`. Architectures that query it
+    #    auto-trigger the install; others never pay. `_install_fast_path_hooks`
+    #    also wraps `is_causal_conv1d_available` as defence in depth.
     # 3) mamba-ssm + flash-attn keep their existing substring / size gates.
-    # 4) `UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1` falls back to the
-    #    substring path for FLA / tilelang.
+    # 4) `UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1` falls back to the substring
+    #    path for FLA / tilelang.
     try:
         _ensure_causal_conv1d_fast_path(event_queue, model_name)
         if os.getenv(_FAST_PATH_HOOKS_SKIP_ENV) == "1":
@@ -1923,12 +1915,11 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         return
 
     # ── 1c. Set fork start method so dataset.map() can multiprocess ──
-    # The parent launched us via spawn (clean process), but the compiled
-    # SFTTrainer checks get_start_method() and disables num_proc if not "fork".
-    # Linux only: fork is the default start method and is safe here (no CUDA
-    # context exists yet). macOS defaults to spawn since Python 3.8 because
-    # fork is unsafe with macOS frameworks (Metal/MPS, CoreFoundation) --
-    # do NOT override on macOS. Windows has no fork at all.
+    # Parent launched us via spawn, but the compiled SFTTrainer checks
+    # get_start_method() and disables num_proc if not "fork". Linux only: fork
+    # is the default and safe here (no CUDA context yet). macOS defaults to spawn
+    # since Python 3.8 (fork unsafe with Metal/MPS, CoreFoundation) -- do NOT
+    # override there. Windows has no fork.
     if sys.platform == "linux":
         import multiprocessing as _mp
         try:
@@ -1951,15 +1942,15 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     # ── 1d. Stub torchao on Windows ROCm ──
     # Shared with the export worker; see core/_torchao_stub.py for the full
     # rationale (torchao -> torch.distributed._functional_collectives crashes on
-    # Windows ROCm because the RCCL backend is absent). No-op off Windows ROCm.
-    # Must run before any import of transformers / unsloth_zoo.
+    # Windows ROCm: no RCCL backend). No-op off Windows ROCm. Must run before any
+    # import of transformers / unsloth_zoo.
     from core._torchao_stub import install_torchao_windows_rocm_stub
 
     install_torchao_windows_rocm_stub()
 
     # ── 1e. Ensure torch.distributed helper attrs are present ──
-    # Single-GPU training never initialises the process group, so these helpers
-    # are never called — but transformers/trl import them unconditionally.
+    # Single-GPU training never inits the process group, so these helpers are
+    # never called — but transformers/trl import them unconditionally.
     _td_stubs = {
         "is_initialized": lambda: False,
         "is_available": lambda: False,
@@ -1989,16 +1980,14 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     # torch._grouped_mm has a null HIP kernel on gfx1200 (ROCm ≤ 7.12 Windows),
     # causing 0xC0000005 (access violation) during training.
     #
-    # Root cause: the JitDecomp autograd decomposition system (NOT torch.compile)
-    # dispatches _grouped_mm → _fused_adagrad_ → _grouped_mm HIP → null crash.
-    # TORCHDYNAMO_DISABLE=1 stops the compiler frontend but does NOT stop
-    # JitDecomp, so we must also override the CUDA dispatch key for _grouped_mm
-    # with a safe Python fallback.
+    # Root cause: JitDecomp autograd decomposition (NOT torch.compile) dispatches
+    # _grouped_mm → _fused_adagrad_ → _grouped_mm HIP → null crash.
+    # TORCHDYNAMO_DISABLE=1 stops the compiler frontend but not JitDecomp, so we
+    # also override the CUDA dispatch key for _grouped_mm with a Python fallback.
     #
-    # Fixed in AMD's wheel: torch==2.11.0+rocm7.13.0 — the 3-D batch and grouped
-    # (with offs) variants of _grouped_mm now have working HIP kernels on gfx1200.
-    # We gate the dispatch override on HIP < 7.13 so users on the fixed wheel get
-    # the real GPU kernel rather than our Python fallback.
+    # Fixed in torch==2.11.0+rocm7.13.0: the 3-D batch and grouped (with offs)
+    # variants now have working HIP kernels on gfx1200. We gate the override on
+    # HIP < 7.13 so the fixed wheel uses the real GPU kernel.
     #
     # Verified: null on torch==2.10.0+rocm7.12.0; fixed on torch==2.11.0+rocm7.13.0.
     #
@@ -2006,17 +1995,15 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     #                     Tensor? bias=None, ScalarType? out_dtype=None) -> Tensor
     #   offs: optional group-split offsets (MoE-style variable-size batches)
     #
-    # torch is already in sys.modules from section 1e's `import torch.distributed`.
-    # Module-level _WINDOWS_ROCM_GROUPED_MM_LIB keeps the registration alive past
-    # function return / mid-run GC.
+    # torch is already in sys.modules from section 1e. Module-level
+    # _WINDOWS_ROCM_GROUPED_MM_LIB keeps the registration alive past return / GC.
     global _WINDOWS_ROCM_GROUPED_MM_LIB
     if sys.platform == "win32":
         _torch_for_rocm = sys.modules.get("torch")
-        # Broad check: torch.version.hip OR "rocm" in torch.__version__.
-        # AMD SDK / Radeon Windows wheels do not always populate
-        # torch.version.hip; without the broad check the BNB version pin,
-        # dynamo-disable, and _grouped_mm fallback below silently skip
-        # (matches the torchao stub gate above and main.py).
+        # Broad check: torch.version.hip OR "rocm" in torch.__version__. AMD SDK /
+        # Radeon Windows wheels don't always populate torch.version.hip; without
+        # the broad check the BNB version pin, dynamo-disable, and _grouped_mm
+        # fallback below silently skip (matches the torchao stub gate and main.py).
         _build_version_for_rocm = (
             getattr(_torch_for_rocm, "__version__", "").lower()
             if _torch_for_rocm is not None
@@ -2030,20 +2017,19 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             )
         )
         if _is_win_rocm_torch:
-            # Disable dynamo (belt-and-suspenders; JitDecomp patch below is the
-            # real fix, but keeping dynamo off avoids any other compile paths).
+            # Disable dynamo (belt-and-suspenders; the JitDecomp patch below is
+            # the real fix, but dynamo off avoids any other compile paths).
             if "TORCHDYNAMO_DISABLE" not in os.environ:
                 os.environ["TORCHDYNAMO_DISABLE"] = "1"
                 logger.info("Windows ROCm: torch.compile (dynamo) disabled")
 
-            # BNB auto-detects the HIP version from torch.version.hip and uses
-            # it to choose which DLL to load (e.g. "7.13" → rocm713.dll).
-            # AMD's Windows BNB prerelease wheel ships only one rocm DLL, and its
-            # version suffix does not always match the torch HIP version (e.g.
-            # torch==2.11.0+rocm7.13.0 ships HIP 7.13, but the BNB wheel still
-            # ships rocm72.dll).  We detect the actual DLL name from the installed
-            # package and override BNB's auto-detection.  "72" is a safe fallback
-            # if detection fails.  Callers may override by pre-setting the var.
+            # BNB auto-detects the HIP version from torch.version.hip to pick a
+            # DLL (e.g. "7.13" → rocm713.dll). AMD's Windows BNB prerelease wheel
+            # ships only one rocm DLL whose version suffix may not match the torch
+            # HIP version (e.g. torch==2.11.0+rocm7.13.0 ships HIP 7.13, but the
+            # BNB wheel still ships rocm72.dll). Detect the actual DLL name from
+            # the installed package and override auto-detection. "72" is a safe
+            # fallback if detection fails. Callers may override by pre-setting the var.
             if "BNB_ROCM_VERSION" not in os.environ:
                 _bnb_rocm_ver = None
                 try:
@@ -2064,10 +2050,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                                 )
                                 if _m:
                                     _all_vers.append(_m.group(1))
-                        # Pick the highest numeric suffix so that e.g. "713"
-                        # wins over "72" when both variants are present.
-                        # Filesystem glob order is not guaranteed, so always
-                        # sort rather than stopping at the first match.
+                        # Pick the highest numeric suffix so "713" wins over
+                        # "72" when both are present. Glob order isn't guaranteed,
+                        # so always sort rather than take the first match.
                         if _all_vers:
                             _bnb_rocm_ver = max(_all_vers, key = lambda v: int(v))
                 except Exception:
@@ -2081,17 +2066,15 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                     _bnb_rocm_ver,
                 )
 
-            # Parse HIP version for the kernel-fix gate below.
-            # torch.version.hip can be "7.13.99004", "7.2.0", etc.
-            # AMD SDK / Radeon wheels may leave torch.version.hip unset and
-            # encode the ROCm version in torch.__version__ instead
-            # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back
-            # to that string when version.hip is missing.
+            # Parse HIP version for the kernel-fix gate below. torch.version.hip
+            # can be "7.13.99004", "7.2.0", etc. AMD SDK / Radeon wheels may leave
+            # it unset and encode the ROCm version in torch.__version__ instead
+            # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back to
+            # that string when version.hip is missing.
             def _hip_ver_at_least(major: int, minor: int) -> bool:
                 _hip_str = getattr(getattr(_torch_for_rocm, "version", None), "hip", None)
                 if not _hip_str:
-                    # Try the standard "+rocmX.Y.Z" embedded version first
-                    # (e.g. "2.11.0+rocm7.13.0").
+                    # Try the standard "+rocmX.Y.Z" embedded version first.
                     _ver_match = re.search(r"rocm(\d+)\.(\d+)", _build_version_for_rocm)
                     if _ver_match:
                         return (
@@ -2100,12 +2083,11 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                         ) >= (major, minor)
                     # AMD SDK / Radeon Windows wheels encode the build as
                     # "+rocmsdk<date>" (e.g. "2.9.0+rocmsdk20251116") with no
-                    # explicit rocmX.Y component. The rocmsdk format was
-                    # introduced after the gfx120X null-kernel fix landed in
-                    # ROCm 7.13, so any wheel with this suffix is new enough to
-                    # have working HIP kernels. Treat as >= 7.13 rather than
-                    # falling back to False and installing the Python workaround
-                    # on a wheel that doesn't need it.
+                    # explicit rocmX.Y. The rocmsdk format postdates the gfx120X
+                    # null-kernel fix (ROCm 7.13), so any such wheel has working
+                    # HIP kernels. Treat as >= 7.13 rather than returning False
+                    # and installing the Python workaround on a wheel that
+                    # doesn't need it.
                     if "rocmsdk" in _build_version_for_rocm:
                         logger.debug(
                             "Windows ROCm: AMD SDK wheel detected (%r); "
@@ -2139,10 +2121,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                     )
                     return False
 
-            # _grouped_mm HIP kernel was null on gfx1200 in ROCm ≤ 7.12,
-            # causing 0xC0000005.  AMD fixed it in ROCm 7.13 (torch 2.11+).
-            # Only install the Python fallback on the affected versions so users
-            # on 7.13+ get the real GPU kernel for MoE workloads.
+            # _grouped_mm HIP kernel was null on gfx1200 in ROCm ≤ 7.12 (causing
+            # 0xC0000005); fixed in ROCm 7.13 (torch 2.11+). Install the Python
+            # fallback only on affected versions so 7.13+ gets the real GPU kernel.
             if not _hip_ver_at_least(7, 13):
                 try:
                     import warnings as _warnings
@@ -2159,24 +2140,22 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                         """Python mm/bmm fallback for _grouped_mm on gfx1200 (null HIP kernel, ROCm ≤ 7.12)."""
                         _t = _torch_for_rocm
                         if offs is None:
-                            # No offsets: behave like the real op, which
-                            # accepts either (M, K) x (K, N) -> mm, or 3-D
-                            # batched inputs -> bmm. Picking torch.mm
-                            # unconditionally previously raised "self must be
-                            # a matrix" on 3-D MoE workloads.
+                            # No offsets: match the real op — (M, K) x (K, N) ->
+                            # mm, or 3-D batched -> bmm. An unconditional torch.mm
+                            # previously raised "self must be a matrix" on 3-D MoE.
                             if self.dim() == 3 and mat2.dim() == 3:
                                 result = _t.bmm(self.contiguous(), mat2.contiguous())
                             elif self.dim() == 3 and mat2.dim() == 2:
                                 # Broadcast 2-D mat2 across the batch dim.
                                 result = _t.matmul(self.contiguous(), mat2.contiguous())
                             elif self.dim() == 2 and mat2.dim() == 3:
-                                # Broadcast 2-D self across batch via matmul semantics.
+                                # Broadcast 2-D self across batch via matmul.
                                 result = _t.matmul(self.contiguous(), mat2.contiguous())
                             else:
                                 result = _t.mm(self.contiguous(), mat2.contiguous())
                         else:
-                            # Grouped case: offs[i] is the exclusive end-row of
-                            # group i in `self`; mat2 may be 3-D or 2-D.
+                            # Grouped: offs[i] is the exclusive end-row of group
+                            # i in `self`; mat2 may be 3-D or 2-D.
                             offs_list = offs.tolist()
                             pieces = []
                             prev = 0
@@ -2189,7 +2168,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                                     b_part = mat2.contiguous()
                                 pieces.append(_t.mm(a_part, b_part))
                                 prev = end
-                            # Include any trailing rows not covered by offs
+                            # Include trailing rows not covered by offs.
                             if prev < self.shape[0]:
                                 a_tail = self[prev:].contiguous()
                                 b_tail = (
@@ -2237,26 +2216,23 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 )
 
     # ── 1g. ROCm OOM guard ──
-    # On RDNA 4 (gfx1200/gfx1201) and other ROCm GPUs, exhausting VRAM can
-    # cause a HIP driver hang that freezes the entire system rather than
-    # raising a Python exception.  set_per_process_memory_fraction caps the
-    # HIP allocator so PyTorch raises OutOfMemoryError before hitting the
-    # hardware limit, giving the UI a clean error instead of a system freeze.
-    # Only applied on ROCm -- NVIDIA CUDA has a graceful OOM path and does
-    # not need this cap.
+    # On RDNA 4 (gfx1200/gfx1201) and other ROCm GPUs, exhausting VRAM can hang
+    # the HIP driver and freeze the whole system instead of raising. So
+    # set_per_process_memory_fraction caps the HIP allocator and PyTorch raises
+    # OutOfMemoryError before the hardware limit, giving the UI a clean error.
+    # ROCm only -- NVIDIA CUDA has a graceful OOM path.
     # Unified-memory APUs (gfx1150 Strix Point / gfx1151 Strix Halo) share GPU
-    # and system RAM in one pool: 0.90 of 128 GB starves the OS. Use 0.80 there.
-    # Primary classifier: gcnArchName from device properties — stable within a
-    # product family and naming-independent.  AMD SDK / Radeon wheels may omit
-    # gcnArchName or expose it under a variant spelling, so we try several attr
-    # names then fall back to known device-name markers as a last resort.
+    # and system RAM in one pool: 0.90 of 128 GB starves the OS, so use 0.80.
+    # Primary classifier: gcnArchName (stable within a product family,
+    # naming-independent). AMD SDK / Radeon wheels may omit it or use a variant
+    # spelling, so try several attrs then fall back to device-name markers.
     # Non-fatal: silently skipped if torch is not importable.
     if _hw.IS_ROCM:
         try:
             import torch as _torch_mem
             if _torch_mem.cuda.is_available():
-                # Classify unified vs discrete via _rocm_classify_unified_memory.
-                # See that function's docstring for classification priority.
+                # Classify unified vs discrete via _rocm_classify_unified_memory
+                # (see its docstring for classification priority).
                 _props = _torch_mem.cuda.get_device_properties(0)
                 _dev_name = _props.name
                 _gcn_arch, _is_unified = _rocm_classify_unified_memory(_props)
@@ -2310,9 +2286,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         return
 
     # ── 2b. EMBEDDING MODEL FAST-PATH ──
-    # Embedding models use a completely different pipeline (FastSentenceTransformer
-    # + SentenceTransformerTrainer + MultipleNegativesRankingLoss) so we branch
-    # early and handle the entire flow in a self-contained function.
+    # Embedding models use a different pipeline (FastSentenceTransformer +
+    # SentenceTransformerTrainer + MultipleNegativesRankingLoss), so branch early
+    # and handle the whole flow in a self-contained function.
     if config.get("is_embedding", False):
         try:
             _run_embedding_training(event_queue, stop_queue, config)
@@ -2380,9 +2356,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     stop_thread.start()
 
     # ── 4. Execute the training pipeline ──
-    # Order: detect → dataset → model → prepare → train
-    # Dataset processing (including LLM-assisted detection) runs BEFORE model
-    # loading so both never occupy VRAM at the same time.
+    # Order: detect → dataset → model → prepare → train. Dataset processing
+    # (incl. LLM-assisted detection) runs BEFORE model loading so both never
+    # occupy VRAM at once.
     try:
         hf_token = config.get("hf_token", "")
         hf_token = hf_token if hf_token and hf_token.strip() else None
@@ -2451,8 +2427,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         if eval_steps is not None and float(eval_steps) <= 0:
             eval_dataset = None
 
-        # Tell the parent process that eval is configured so the frontend
-        # shows "Waiting for first evaluation step..." instead of "not configured"
+        # Tell the parent eval is configured so the frontend shows
+        # "Waiting for first evaluation step..." instead of "not configured".
         if eval_dataset is not None:
             event_queue.put(
                 {
@@ -2475,7 +2451,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 )
             return
 
-        # ── Start tqdm monitor early so it captures download + tokenization bars ──
+        # ── Start tqdm monitor early to capture download + tokenization bars ──
         import threading as _th
 
         _tqdm_stop = _th.Event()
@@ -2533,9 +2509,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         # ── 4d. Prepare model (LoRA, full finetuning, or CPT) ──
         if is_cpt:
             _send_status(event_queue, "Configuring LoRA for continued pretraining...")
-            # embed_tokens (if the user included it) goes to modules_to_save —
-            # trained full-precision at embedding_learning_rate. lm_head stays as
-            # a LoRA target for merge compatibility (see unsloth PR #4106).
+            # embed_tokens (if included) goes to modules_to_save — trained
+            # full-precision at embedding_learning_rate. lm_head stays a LoRA
+            # target for merge compatibility (see unsloth PR #4106).
             _user_modules = config.get("target_modules") or []
             wants_embed = "embed_tokens" in _user_modules
             cpt_trains_embeddings = wants_embed
@@ -2610,13 +2586,13 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             )
             return
 
-        # embedding_learning_rate is validated by the Pydantic model (Optional[float],
-        # gt=0, lt=1.0); if present it is already a finite float in range.
+        # embedding_learning_rate is validated by Pydantic (Optional[float],
+        # gt=0, lt=1.0); if present it's already a finite float in range.
         embedding_lr_value = config.get("embedding_learning_rate")
         if is_cpt:
             if cpt_trains_embeddings:
                 if embedding_lr_value is None:
-                    # Default embedding_learning_rate = lr/10 per Unsloth's CPT notebook.
+                    # Default embedding_learning_rate = lr/10 (Unsloth CPT notebook).
                     embedding_lr_value = lr_value / 10.0
                     logger.info(
                         f"CPT: using default embedding_learning_rate={embedding_lr_value:.1e} "
@@ -2644,7 +2620,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             tensorboard_dir = str(resolve_tensorboard_dir(tensorboard_dir))
             ensure_dir(Path(tensorboard_dir))
 
-        # Start training (directly — no inner thread, we ARE the subprocess)
+        # Start training directly — no inner thread, we ARE the subprocess.
         dataset_display = config.get("hf_dataset", "") or config.get("uploaded_file", "") or ""
         _send_status(
             event_queue,
@@ -2761,10 +2737,8 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
     """Self-contained embedding model training pipeline.
 
     Uses FastSentenceTransformer + SentenceTransformerTrainer +
-    MultipleNegativesRankingLoss — completely separate from the
-    LLM/VLM/audio paths in UnslothTrainer.
-
-    Mirrors the pattern from the reference embedding notebooks:
+    MultipleNegativesRankingLoss — separate from UnslothTrainer's LLM/VLM/audio
+    paths. Mirrors the reference embedding notebooks:
       All_MiniLM_L6_v2.py, BGE_M3.py, EmbeddingGemma_300M.py,
       ModernBert.py, Qwen3_Embedding_0_6B.py
     """
@@ -2860,7 +2834,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
         _send_status(event_queue, "Configuring LoRA adapters (FEATURE_EXTRACTION)...")
         try:
             gradient_checkpointing = config.get("gradient_checkpointing", False)
-            # Normalize: "none" or empty → False
+            # Normalize "none"/empty → False.
             if gradient_checkpointing in ("none", "", None):
                 gradient_checkpointing = False
 
@@ -2913,8 +2887,8 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
                 token = hf_token,
             )
         elif local_datasets:
-            # Load from local file(s) — mirrors the non-embedding pipeline's
-            # directory handling so recipe outputs (parquet-files/) work.
+            # Load local file(s) — mirrors the non-embedding pipeline's directory
+            # handling so recipe outputs (parquet-files/) work.
             all_files: list[str] = []
             for dataset_file in local_datasets:
                 file_path = (
@@ -3050,7 +3024,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
     else:
         training_args_kwargs["num_train_epochs"] = num_epochs if num_epochs > 0 else 2
 
-    # warmup: prefer warmup_ratio (standard for embedding scripts), fallback to steps
+    # warmup: prefer warmup_ratio (standard for embedding scripts), else steps
     if warmup_ratio is not None and warmup_ratio > 0:
         training_args_kwargs["warmup_ratio"] = warmup_ratio
     elif warmup_steps_val is not None and warmup_steps_val > 0:
@@ -3074,7 +3048,7 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
 
     # ── 8. Create progress callback ──
     class _EmbeddingProgressCallback(TrainerCallback):
-        """Sends training progress events to the parent process via event_queue."""
+        """Send training progress events to the parent via event_queue."""
 
         def on_log(
             self,
diff --git a/studio/backend/loggers/config.py b/studio/backend/loggers/config.py
index 4a27f13d38..35e2764fe9 100644
--- a/studio/backend/loggers/config.py
+++ b/studio/backend/loggers/config.py
@@ -1,15 +1,14 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Logging configuration for structured logging with structlog.
+"""Structured logging configuration via structlog.
 
-This module provides centralized logging configuration with environment-specific
-formats and processors. Supports both development and production environments
-with consistent structured logging.
+Centralized config with environment-specific formats and processors for
+development and production.
 
-Key Features:
-- Environment-specific formatting (JSON for production, console for development)
-- Timestamp standardization (ISO format)
+Key features:
+- Environment-specific formatting (JSON for prod, console for dev)
+- ISO timestamps
 - Context variable integration
 - Log level filtering
 - Logger caching for performance
@@ -28,8 +27,8 @@ from loggers.handlers import filter_sensitive_data
 class LogConfig:
     """Structured logging configuration for the application.
 
-    Provides static method to configure structlog with environment-specific
-    formatting and processors for consistent structured logging.
+    Static method to configure structlog with environment-specific
+    formatting and processors.
     """
 
     @staticmethod
@@ -41,9 +40,8 @@ class LogConfig:
             service_name: Name of the service for logging identification
             env: Environment (development/production), affects logging format
         """
-        # Determine log level from environment
+        # Log level from environment; fall back to INFO if invalid.
         log_level_name = os.getenv("LOG_LEVEL", "INFO").upper()
-        # Fallback to INFO if an invalid level is provided
         log_level = getattr(logging, log_level_name, logging.INFO)
 
         if sys.platform == "win32":
@@ -56,13 +54,13 @@ class LogConfig:
 
         structlog.configure(
             processors = [
-                # Reorder processors to control field order
+                # Ordered to control output field order.
                 structlog.processors.TimeStamper(fmt = "iso"),  # timestamp first
                 structlog.processors.add_log_level,  # level second
                 structlog.contextvars.merge_contextvars,
                 structlog.processors.format_exc_info,
                 filter_sensitive_data,
-                # Custom processor to flatten the extra field
+                # Flatten the extra field into the main dict.
                 lambda logger, method_name, event_dict: {
                     "timestamp": event_dict.get("timestamp"),
                     "level": event_dict.get("level"),
diff --git a/studio/backend/loggers/handlers.py b/studio/backend/loggers/handlers.py
index e80bd4fafb..419e041a72 100644
--- a/studio/backend/loggers/handlers.py
+++ b/studio/backend/loggers/handlers.py
@@ -3,16 +3,16 @@
 
 """Logging handlers and middleware for structured logging.
 
-This module provides FastAPI middleware and structlog processors for:
+FastAPI middleware + structlog processors for:
 - Request/response logging with timing
-- Sensitive data filtering in logs
-- Structured logging configuration
-- Error handling with detailed context
+- Sensitive data filtering
+- Structured logging config
+- Error handling with context
 
-Key Components:
-- LoggingMiddleware: FastAPI middleware for request/response logging
-- filter_sensitive_data: Structlog processor for data sanitization
-- get_logger: Factory function for structured loggers
+Key components:
+- LoggingMiddleware: request/response logging
+- filter_sensitive_data: structlog processor for sanitization
+- get_logger: factory for structured loggers
 """
 
 import re
@@ -38,7 +38,6 @@ class LoggingMiddleware(BaseHTTPMiddleware):
         try:
             response = await call_next(request)
 
-            # Log response
             process_time = (time.time() - start_time) * 1000
 
             EXCLUDED_PATHS = {
@@ -108,10 +107,8 @@ def filter_sensitive_data(logger, method_name, event_dict):
 
 
 def get_logger(name: str) -> structlog.BoundLogger:
-    """Get a logger instance for a specific module.
+    """Get a bound structured logger for a module.
     Args:
         name: Usually __name__ of the module
-    Returns:
-        A bound structured logger
     """
     return structlog.get_logger(name)
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 8e3a118e27..1bc96c6206 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -9,20 +9,20 @@ import os
 import sys
 from pathlib import Path as _Path
 
-# Suppress annoying C-level dependency warnings globally
+# Suppress C-level dependency warnings globally
 os.environ["PYTHONWARNINGS"] = "ignore"
 
 # ── Windows AMD ROCm DLL injection ──────────────────────────────────────────
 # Python 3.8+ ignores PATH for extension modules; register ROCm bin dirs with
 # os.add_dll_directory() so amdhip64.dll etc. are found before any torch import.
 if sys.platform == "win32":
-    # Retained at module scope -- os.add_dll_directory returns a handle that
+    # Retained at module scope; os.add_dll_directory returns a handle that
     # removes the search-path entry when garbage collected.
     _ROCM_DLL_HANDLES: list = []
 
     def _add_rocm_dll_dirs() -> None:
         candidates = []
-        # 1. HIP_PATH / ROCM_PATH -- set by the AMD HIP SDK installer
+        # 1. HIP_PATH / ROCM_PATH set by the AMD HIP SDK installer
         for _var in ("HIP_PATH", "ROCM_PATH"):
             _val = os.environ.get(_var)
             if _val:
@@ -34,7 +34,7 @@ if sys.platform == "win32":
         )
 
         def _ver_key(name: str) -> tuple:
-            # Numeric tuple key so "10.0" sorts after "7.0"; non-numeric chunks fall back to string.
+            # Numeric tuple key so "10.0" sorts after "7.0"; non-numeric chunks fall back to string
             parts = []
             for chunk in name.split("."):
                 try:
@@ -62,16 +62,15 @@ if sys.platform == "win32":
     del _add_rocm_dll_dirs
 
     # ── Windows AMD ROCm: set BNB_ROCM_VERSION before any bitsandbytes import ─
-    # bitsandbytes on Windows ROCm tries to load libbitsandbytes_rocm<ver>.dll
-    # where <ver> comes from torch.version.hip (e.g. "7.13..." → "713").
-    # The installed BNB wheel ships rocm72.dll (not rocm713.dll), so without
-    # this the server process crashes with "Configured ROCm binary not found".
-    # Detect the available DLL, fall back to "72", and set BNB_ROCM_VERSION
-    # before any import that pulls in bitsandbytes (mirrors worker.py logic).
-    # Gate on the rocm bnb DLL (the exact file this configures) or HIP_PATH/
-    # ROCM_PATH, not on torch.version.hip: that needed importing torch on every
-    # Windows host (NVIDIA/CPU included), adding seconds to startup. Radeon
-    # wheels without HIP_PATH still ship the rocm bnb DLL, so they are covered.
+    # bitsandbytes on Windows ROCm loads libbitsandbytes_rocm<ver>.dll where
+    # <ver> comes from torch.version.hip (e.g. "7.13..." → "713"). The installed
+    # BNB wheel ships rocm72.dll (not rocm713.dll), so without this the server
+    # crashes with "Configured ROCm binary not found". Detect the available DLL,
+    # fall back to "72", and set BNB_ROCM_VERSION before any bitsandbytes import
+    # (mirrors worker.py). Gate on the rocm bnb DLL (the file this configures) or
+    # HIP_PATH/ROCM_PATH, not torch.version.hip: that needed importing torch on
+    # every Windows host (NVIDIA/CPU too), adding startup seconds. Radeon wheels
+    # without HIP_PATH still ship the rocm bnb DLL, so they're covered.
     if "BNB_ROCM_VERSION" not in os.environ:
         import glob as _glob
         import logging as _logging
@@ -82,7 +81,7 @@ if sys.platform == "win32":
         try:
             import importlib.util as _ilu
             _bnb_spec = _ilu.find_spec("bitsandbytes")
-            # submodule_search_locations (not spec.origin) handles editable installs.
+            # submodule_search_locations (not spec.origin) handles editable installs
             if _bnb_spec and _bnb_spec.submodule_search_locations:
                 import re as _re_bnb
 
@@ -102,7 +101,7 @@ if sys.platform == "win32":
                 "Windows ROCm: BNB DLL detection failed (%s); falling back to version '72'",
                 _e,
             )
-        # rocm bnb DLL present, or HIP_PATH/ROCM_PATH set (DLL unparsable -> "72").
+        # rocm bnb DLL present, or HIP_PATH/ROCM_PATH set (DLL unparsable -> "72")
         if _found_rocm_bnb or _hip_env:
             _bnb_rocm_ver_final = _bnb_rocm_ver or "72"
             os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver_final
@@ -111,8 +110,8 @@ if sys.platform == "win32":
                 _bnb_rocm_ver_final,
             )
 
-# Ensure backend dir is on sys.path so _platform_compat is importable when
-# main.py is launched directly (e.g. `uvicorn main:app`).
+# Put backend dir on sys.path so _platform_compat is importable when main.py
+# is launched directly (e.g. `uvicorn main:app`).
 _backend_dir = str(_Path(__file__).parent)
 if _backend_dir not in sys.path:
     sys.path.insert(0, _backend_dir)
@@ -126,14 +125,14 @@ except ValueError as exc:
     _raw = os.environ.get("UNSLOTH_CPU_THREADS")
     raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {_raw!r}: {exc}") from None
 
-# Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
-# any library imports that trigger attrs -> rich -> structlog -> platform crash.
+# Anaconda/conda-forge Python: seed platform._sys_version_cache before any
+# library import triggers attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
 import _platform_compat  # noqa: F401
 
 # Direct `uvicorn main:app` launches bypass run.py, so re-export here too
-# (mirrors run.py). Required BEFORE the unsloth-zoo import below, since
-# its LLAMA_CPP_DEFAULT_DIR binding is import-time.
+# (mirrors run.py). Required BEFORE the unsloth-zoo import below, whose
+# LLAMA_CPP_DEFAULT_DIR binding is import-time.
 from utils.paths.storage_roots import studio_root as _studio_root
 
 try:
@@ -166,15 +165,13 @@ _STUDIO_INSTALL_ID_RE = _re.compile(r"^[0-9a-f]{64}$")
 
 def _read_studio_install_id() -> str:
     """Per-install opaque id written by install.sh / install.ps1 at
-    $STUDIO_HOME/share/studio_install_id. Returns "" when the file is
-    absent (pre-PR install, fresh tree never run through the installer)
-    or contains anything other than a 64-char lowercase-hex token --
-    in which case /api/health emits "" and the launcher's _check_health
-    falls back to the existing "no baked id, accept any healthy
-    Unsloth backend" path. This intentionally replaces a previous
-    sha256(resolved_install_path) so the field carries no install-path
-    information for callers reaching /api/health (relevant when Studio
-    is run with -H 0.0.0.0)."""
+    $STUDIO_HOME/share/studio_install_id. Returns "" when the file is absent
+    (pre-PR install, or fresh tree never run through the installer) or holds
+    anything other than a 64-char lowercase-hex token; then /api/health emits
+    "" and the launcher's _check_health falls back to "no baked id, accept any
+    healthy Unsloth backend". Replaces a previous sha256(resolved_install_path)
+    so the field carries no install-path info for callers reaching /api/health
+    (relevant when Studio runs with -H 0.0.0.0)."""
     try:
         token = (_STUDIO_ROOT_RESOLVED / "share" / "studio_install_id").read_text().strip()
     except (OSError, ValueError):
@@ -186,29 +183,28 @@ _STUDIO_ROOT_ID_CACHE: str = _read_studio_install_id()
 
 
 def _studio_root_id() -> str:
-    """Same-install discriminator for /api/health: a per-install opaque
-    token written once by the installer and read once at module import.
-    Empty when no installer-written token is present; the launcher
-    contract treats "" as "no baked id, accept any healthy backend"."""
+    """Same-install discriminator for /api/health: a per-install opaque token
+    written once by the installer and read once at module import. Empty when no
+    installer token is present; the launcher contract treats "" as "no baked id,
+    accept any healthy backend"."""
     return _STUDIO_ROOT_ID_CACHE
 
 
-# Fix broken Windows registry MIME types.  Some Windows installs map .js to
-# "text/plain" in the registry (HKCR\.js\Content Type).  Python's mimetypes
-# module reads from the registry, and FastAPI/Starlette's StaticFiles uses
-# mimetypes.guess_type() to set Content-Type headers.  Browsers enforce strict
-# MIME checking for ES module scripts (<script type="module">) and will refuse
-# to execute .js files served as text/plain — resulting in a blank page.
-# Calling add_type() *before* StaticFiles is instantiated ensures the correct
-# types are used regardless of the OS registry.
+# Fix broken Windows registry MIME types. Some Windows installs map .js to
+# "text/plain" in the registry (HKCR\.js\Content Type). Python's mimetypes reads
+# from the registry, and Starlette's StaticFiles uses mimetypes.guess_type() for
+# Content-Type. Browsers strictly MIME-check ES module scripts
+# (<script type="module">) and refuse .js served as text/plain, giving a blank
+# page. Calling add_type() *before* StaticFiles is instantiated forces the
+# correct types regardless of the OS registry.
 if sys.platform == "win32":
     mimetypes.add_type("application/javascript", ".js")
     mimetypes.add_type("text/css", ".css")
 
-# Suppress annoying dependency warnings in production
+# Suppress dependency warnings in production
 if os.getenv("ENVIRONMENT_TYPE", "production") == "production":
     warnings.filterwarnings("ignore")
-    # Alternatively, you can be more specific:
+    # Or be more specific:
     # warnings.filterwarnings("ignore", category=DeprecationWarning)
     # warnings.filterwarnings("ignore", module="triton.*")
 
@@ -300,7 +296,7 @@ def _desktop_owner() -> dict[str, str] | None:
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Startup: detect hardware, seed default admin if needed. Shutdown: clean up compiled cache."""
-    # Clean up any stale compiled cache from previous runs
+    # Clean up stale compiled cache from previous runs
     clear_unsloth_compiled_cache()
 
     # Remove stale .venv_overlay from previous versions — no longer used.
@@ -354,8 +350,8 @@ async def lifespan(app: FastAPI):
         import structlog
         structlog.get_logger(__name__).warning("cleanup_orphaned_runs failed at startup: %s", exc)
 
-    # Pre-cache the helper GGUF model for LLM-assisted dataset detection.
-    # Runs in a background thread so it doesn't block server startup.
+    # Pre-cache the helper GGUF model for LLM-assisted dataset detection,
+    # in a background thread so it doesn't block server startup.
     import threading
 
     def _precache():
@@ -412,7 +408,7 @@ app.add_middleware(LoggingMiddleware)
 
 
 # Citation favicons load from www.google.com/s2/favicons; *.gstatic.com is
-# kept for legacy web-search faviconV2 paths. Everything else is same-origin.
+# kept for legacy web-search faviconV2 paths. All else is same-origin.
 from starlette.middleware.base import BaseHTTPMiddleware  # noqa: E402
 from starlette.requests import Request as _StarletteRequest  # noqa: E402
 
@@ -421,7 +417,7 @@ _CSP_SCRIPT_NONCE_HEADER = "x-internal-script-nonce"
 _ARTIFACT_PREVIEW_FRAME_PATH = "/api/inference/artifact-preview-frame"
 
 
-# /content is Colab's working directory — more reliable than env vars which
+# /content is Colab's working directory — more reliable than env vars, which
 # aren't always set depending on Colab runtime version.
 import importlib.util as _importlib_util
 
@@ -437,19 +433,18 @@ def _build_csp(script_nonce: "str | None" = None) -> str:
     if script_nonce:
         script_src += f" 'nonce-{script_nonce}'"
     # In Colab the parent frame can be colab.research.google.com, a multi-level
-    # *.prod.colab.dev subdomain (e.g. foo.region.prod.colab.dev — note: CSP
-    # wildcards only match one level, so *.prod.colab.dev misses these), or a
-    # sandboxed null-origin output iframe. Use '*' so any ancestor is allowed;
-    # Colab is already a sandboxed single-user environment.
+    # *.prod.colab.dev subdomain (e.g. foo.region.prod.colab.dev — CSP wildcards
+    # only match one level, so *.prod.colab.dev misses these), or a sandboxed
+    # null-origin output iframe. Use '*' to allow any ancestor; Colab is already
+    # a sandboxed single-user environment.
     frame_ancestors = "*" if _IS_COLAB else "'none'"
 
     # In Colab the frontend is served over the Colab reverse-proxy at an HTTPS
-    # *.prod.colab.dev URL. Colab's kernel communication layer and the output
-    # iframe scaffolding inject scripts from *.prod.colab.dev and
-    # *.googleusercontent.com, and make fetch/WebSocket connections to those
-    # same origins. Widen script-src and connect-src in Colab mode so those
-    # requests are not blocked. 'unsafe-inline' for scripts is still omitted;
-    # our own inline script uses a nonce.
+    # *.prod.colab.dev URL. Colab's kernel layer and output-iframe scaffolding
+    # inject scripts from *.prod.colab.dev and *.googleusercontent.com, and
+    # fetch/WebSocket to those origins. Widen script-src and connect-src in
+    # Colab mode so those aren't blocked. 'unsafe-inline' for scripts is still
+    # omitted; our inline script uses a nonce.
     if _IS_COLAB:
         script_src += " https://*.prod.colab.dev https://*.googleusercontent.com"
         connect_src = (
@@ -482,7 +477,7 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
 
     async def dispatch(self, request: _StarletteRequest, call_next):
         response = await call_next(request)
-        # Strip the internal nonce hand-off header so it never reaches the client.
+        # Strip the internal nonce hand-off header so it never reaches the client
         nonce = response.headers.get(_CSP_SCRIPT_NONCE_HEADER)
         if nonce is not None:
             del response.headers[_CSP_SCRIPT_NONCE_HEADER]
@@ -505,7 +500,7 @@ app.add_middleware(SecurityHeadersMiddleware)
 
 
 # Cap request bodies on protected POSTs. Upload routes get explicit multipart
-# headroom, while non-upload routes keep the default body cap.
+# headroom; non-upload routes keep the default body cap.
 import json as _json_for_413  # noqa: E402
 from utils.upload_limits import (  # noqa: E402
     UNSTRUCTURED_RECIPE_UPLOAD_MAX_BYTES,
@@ -651,7 +646,7 @@ class MaxBodyMiddleware:
             if mtype == "http.disconnect":
                 return
             if mtype != "http.request":
-                # Mid-stream unexpected frame: forwarding would corrupt downstream.
+                # Mid-stream unexpected frame: forwarding would corrupt downstream
                 return
             body = msg.get("body", b"") or b""
             if body:
@@ -730,13 +725,13 @@ app.include_router(training_router, prefix = "/api/train", tags = ["training"])
 app.include_router(models_router, prefix = "/api/models", tags = ["models"])
 app.include_router(chat_history_router, prefix = "/api/chat", tags = ["chat"])
 app.include_router(inference_router, prefix = "/api/inference", tags = ["inference"])
-# Studio-only inference endpoints (cancel, etc.) are intentionally NOT
-# exposed on the /v1 OpenAI-compat prefix below.
+# Studio-only inference endpoints (cancel, etc.) are NOT exposed on the /v1
+# OpenAI-compat prefix below.
 app.include_router(inference_studio_router, prefix = "/api/inference", tags = ["inference"])
 
-# OpenAI-compatible endpoints: mount the same inference router at /v1
-# so external tools (Open WebUI, SillyTavern, etc.) can use the
-# standard /v1/chat/completions path.
+# OpenAI-compatible endpoints: mount the same inference router at /v1 so
+# external tools (Open WebUI, SillyTavern, etc.) can use the standard
+# /v1/chat/completions path.
 app.include_router(inference_router, prefix = "/v1", tags = ["openai-compat"])
 app.include_router(providers_router, prefix = "/api/providers", tags = ["providers"])
 app.include_router(settings_router, prefix = "/api/settings", tags = ["settings"])
@@ -757,9 +752,9 @@ async def health_check(request: Request):
     Unauthenticated callers (Tauri watchdog, frontend bootstrap polls) need
     ``service`` / ``studio_root_id`` / ``chat_only`` / ``desktop_*`` / ``native_path_leases_supported``
     to (a) re-adopt a sibling backend across restarts and (b) gate UI surfaces
-    before any token is available. None of those leak install path or version.
-    ``version`` / ``studio_version`` / ``device_type`` still require a bearer
-    because they fingerprint the host.
+    before a token is available. None of those leak install path or version.
+    ``version`` / ``studio_version`` / ``device_type`` require a bearer since
+    they fingerprint the host.
     """
     base = {
         "status": "healthy",
@@ -783,7 +778,7 @@ async def health_check(request: Request):
         from fastapi.security import HTTPAuthorizationCredentials
 
         creds = HTTPAuthorizationCredentials(scheme = "Bearer", credentials = auth.split(" ", 1)[1])
-        # Must await: a bare coroutine is truthy and would skip the auth check.
+        # Must await: a bare coroutine is truthy and would skip the auth check
         subject = await _gcs(creds)
     except HTTPException:
         return base
@@ -819,7 +814,7 @@ async def shutdown_server(request: Request, current_subject: str = Depends(get_c
     """Gracefully shut down the Unsloth Studio server.
 
     Called by the frontend quit dialog so users can stop the server from the UI
-    without needing to use the CLI or kill the process manually.
+    without the CLI or killing the process manually.
     """
     import asyncio
 
@@ -842,11 +837,11 @@ async def shutdown_server(request: Request, current_subject: str = Depends(get_c
 async def get_system_info(current_subject: str = Depends(get_current_subject)):
     """Get system information.
 
-    Gated behind auth: the response includes platform, Python version,
-    GPU name, memory total, and ML package set -- enough to fingerprint
-    a host. Studio's chat-only-mode design assumes only the local user
-    reaches /api/system; in -H 0.0.0.0 / Colab / Tauri-relayed setups
-    that assumption breaks unless we require a bearer.
+    Gated behind auth: the response includes platform, Python version, GPU name,
+    memory total, and ML package set -- enough to fingerprint a host. Studio's
+    chat-only design assumes only the local user reaches /api/system; in
+    -H 0.0.0.0 / Colab / Tauri-relayed setups that breaks unless we require a
+    bearer.
     """
     import platform
     import psutil
@@ -865,9 +860,8 @@ async def get_system_info(current_subject: str = Depends(get_current_subject)):
     return {
         "platform": platform.platform(),
         "python_version": platform.python_version(),
-        # Use the centralized _backend_label helper so the /api/system
-        # endpoint reports "rocm" on AMD hosts instead of "cuda", matching
-        # the /api/hardware and /api/gpu-visibility endpoints.
+        # Centralized _backend_label so /api/system reports "rocm" on AMD hosts
+        # instead of "cuda", matching /api/hardware and /api/gpu-visibility.
         "device_backend": _backend_label(get_device()),
         "cpu_count": psutil.cpu_count(),
         "memory": {
@@ -888,8 +882,8 @@ async def get_gpu_visibility(current_subject: str = Depends(get_current_subject)
 async def get_hardware_info(current_subject: str = Depends(get_current_subject)):
     """Return GPU name, total VRAM, and key ML package versions.
 
-    Gated behind auth alongside /api/system -- same fingerprinting
-    concern. /api/system/gpu-visibility is also auth-gated already.
+    Gated behind auth alongside /api/system -- same fingerprinting concern.
+    /api/system/gpu-visibility is also auth-gated.
     """
     from utils.hardware import get_gpu_summary, get_package_versions
     return {
@@ -904,11 +898,10 @@ async def get_hardware_info(current_subject: str = Depends(get_current_subject))
 def _strip_crossorigin(html_bytes: bytes) -> bytes:
     """Remove ``crossorigin`` attributes from script/link tags.
 
-    Vite adds ``crossorigin`` by default which forces CORS mode on font
-    subresource loads.  When Studio is served over plain HTTP, Firefox
-    HTTPS-Only Mode does not exempt CORS font requests -- causing all
-    @font-face downloads to fail silently.  Stripping the attribute
-    makes them regular same-origin fetches that work on any protocol.
+    Vite adds ``crossorigin`` by default, forcing CORS mode on font subresource
+    loads. Over plain HTTP, Firefox HTTPS-Only Mode doesn't exempt CORS font
+    requests, so all @font-face downloads fail silently. Stripping the attribute
+    makes them same-origin fetches that work on any protocol.
     """
     html = html_bytes.decode("utf-8")
     html = _re.sub(r'\s+crossorigin(?:="[^"]*")?', "", html)
@@ -917,8 +910,8 @@ def _strip_crossorigin(html_bytes: bytes) -> bytes:
 
 def _inject_bootstrap(html_bytes: bytes, app: FastAPI):
     """Inject bootstrap credentials when password change is pending.
-    Returns ``(html_bytes, script_nonce_or_None)``; callers forward the
-    nonce via ``_CSP_SCRIPT_NONCE_HEADER`` so CSP allows the inline script.
+    Returns ``(html_bytes, script_nonce_or_None)``; callers forward the nonce
+    via ``_CSP_SCRIPT_NONCE_HEADER`` so CSP allows the inline script.
     """
     import json as _json
     import secrets as _secrets
@@ -949,9 +942,9 @@ _DEFAULT_PORTS = {"http": 80, "https": 443, "ws": 80, "wss": 443}
 def _canonical_origin(scheme: str, netloc: str) -> Optional[tuple[str, str, int]]:
     """Canonicalise an Origin to ``(scheme, host, port)`` for equality.
     Browsers strip default ports (RFC 6454 sec 6.1) and scheme/host are
-    case-insensitive (RFC 3986), so bare string compare misclassifies
-    same-origin requests as cross-origin. Returns ``None`` on unparseable
-    input so callers fall to the safer cross-origin default.
+    case-insensitive (RFC 3986), so a bare string compare misclassifies
+    same-origin requests as cross-origin. Returns ``None`` on unparseable input
+    so callers fall to the safer cross-origin default.
     """
     scheme = (scheme or "").strip().lower()
     if not scheme or not netloc:
@@ -960,7 +953,7 @@ def _canonical_origin(scheme: str, netloc: str) -> Optional[tuple[str, str, int]
     if "@" in netloc:
         netloc = netloc.rsplit("@", 1)[1]
     # IPv6 hosts use brackets (RFC 3986 sec 3.2.2): ``[::1]:8902``. Bare
-    # ``partition(":")`` mis-parses these and breaks ``unsloth studio -H ::1``.
+    # ``partition(":")`` mis-parses these, breaking ``unsloth studio -H ::1``.
     if netloc.startswith("["):
         close = netloc.find("]")
         if close == -1:
@@ -993,7 +986,7 @@ def _is_same_origin_request(request: Request) -> bool:
     Top-level same-document GETs omit Origin, so missing counts as same-origin.
     Callers must also emit ``Vary: Origin``. Both sides are canonicalised via
     :func:`_canonical_origin` so default-port stripping and scheme/host case
-    do not misclassify same-origin requests as cross-origin.
+    don't misclassify same-origin requests as cross-origin.
     """
     origin = request.headers.get("origin")
     if origin is None:
@@ -1064,7 +1057,7 @@ def setup_frontend(app: FastAPI, build_path: Path):
 
         file_path = (build_path / full_path).resolve()
 
-        # Block path traversal — ensure resolved path stays inside build_path
+        # Block path traversal — resolved path must stay inside build_path
         if not file_path.is_relative_to(build_path.resolve()):
             return Response(status_code = 403)
 
diff --git a/studio/backend/models/__init__.py b/studio/backend/models/__init__.py
index 7addca02ca..dbedeeca00 100644
--- a/studio/backend/models/__init__.py
+++ b/studio/backend/models/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic models for API request/response schemas
-"""
+"""Pydantic models for API request/response schemas."""
 
 from .training import (
     TrainingStartRequest,
diff --git a/studio/backend/models/auth.py b/studio/backend/models/auth.py
index 9550e354a8..f451f8d9dd 100644
--- a/studio/backend/models/auth.py
+++ b/studio/backend/models/auth.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for Authentication API
-"""
+"""Pydantic schemas for the Authentication API."""
 
 from typing import Optional
 
diff --git a/studio/backend/models/data_recipe.py b/studio/backend/models/data_recipe.py
index f3faddf843..e6f27e64df 100644
--- a/studio/backend/models/data_recipe.py
+++ b/studio/backend/models/data_recipe.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for Data Recipe (DataDesigner) API.
-"""
+"""Pydantic schemas for Data Recipe (DataDesigner) API."""
 
 from __future__ import annotations
 
diff --git a/studio/backend/models/datasets.py b/studio/backend/models/datasets.py
index f20d6f2d15..9a2d8e91cb 100644
--- a/studio/backend/models/datasets.py
+++ b/studio/backend/models/datasets.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Dataset-related Pydantic models for API requests and responses.
-"""
+"""Dataset Pydantic models for API requests and responses."""
 
 from typing import Any, Dict, List, Optional
 
diff --git a/studio/backend/models/export.py b/studio/backend/models/export.py
index 86ce2b05bf..0d54b435a6 100644
--- a/studio/backend/models/export.py
+++ b/studio/backend/models/export.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for Export API.
-"""
+"""Pydantic schemas for Export API."""
 
 from pathlib import Path
 
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index d2fa45dd92..d7ce674141 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for Inference API
-"""
+"""Pydantic schemas for the Inference API."""
 
 from __future__ import annotations
 
@@ -108,11 +106,8 @@ class UnloadRequest(BaseModel):
 
 
 class ValidateModelRequest(BaseModel):
-    """
-    Lightweight validation request to check whether a model identifier
-    *can be resolved* into a ModelConfig.
-
-    This does NOT actually load weights into GPU memory.
+    """Lightweight check whether a model identifier *can be resolved* into a
+    ModelConfig. Does NOT load weights into GPU memory.
     """
 
     model_path: str = Field(..., description = "Model identifier or local path")
@@ -126,8 +121,7 @@ class ValidateModelRequest(BaseModel):
 
 
 class ValidateModelResponse(BaseModel):
-    """
-    Result of model validation.
+    """Result of model validation.
 
     valid == True means ModelConfig.from_identifier() succeeded and basic
     introspection (GGUF / LoRA / vision flags) is available.
@@ -245,10 +239,9 @@ class UnloadResponse(BaseModel):
 class LoadProgressResponse(BaseModel):
     """Progress of the active GGUF load, sampled on demand.
 
-    Used by the UI to show a real progress bar during the
-    post-download warmup window (mmap + CUDA upload), rather than a
-    generic "Starting model..." spinner that freezes for minutes on
-    large MoE models.
+    Drives a real progress bar during the post-download warmup window
+    (mmap + CUDA upload), instead of a generic "Starting model..." spinner
+    that freezes for minutes on large MoE models.
     """
 
     phase: Optional[str] = Field(
@@ -409,10 +402,10 @@ class InputDocumentContentPart(BaseModel):
     Studio-normalised shape. The frontend sends either
     ``{type:"input_document", file_data:"data:application/pdf;base64,..."}``
     or ``{type:"input_document", file_url:"https://..."}``, plus optional
-    ``filename`` and ``media_type``. ``external_provider`` translates this
-    onto Anthropic's ``document`` block or OpenAI Responses' ``input_file``
-    block for vision-capable providers; non-vision providers drop the
-    part entirely (handled in ``_build_external_messages``).
+    ``filename`` and ``media_type``. ``external_provider`` maps this onto
+    Anthropic's ``document`` block or OpenAI Responses' ``input_file`` block
+    for vision-capable providers; non-vision providers drop the part
+    (handled in ``_build_external_messages``).
     """
 
     type: Literal["input_document"]
@@ -437,10 +430,10 @@ class InputDocumentContentPart(BaseModel):
 class OpenAIReasoningContentPart(BaseModel):
     """OpenAI Responses reasoning item paired with a tool output.
 
-    Reasoning models can require the previous ``reasoning`` output item
-    to be replayed immediately before an ``image_generation_call`` id
-    when manually managing Responses context. This part is OpenAI-only;
-    routes strip it for every other provider before proxying.
+    Reasoning models can require the previous ``reasoning`` output item to be
+    replayed immediately before an ``image_generation_call`` id when manually
+    managing Responses context. OpenAI-only; routes strip it for every other
+    provider before proxying.
     """
 
     type: Literal["reasoning"]
@@ -452,12 +445,12 @@ class OpenAIReasoningContentPart(BaseModel):
 class ImageGenerationCallContentPart(BaseModel):
     """OpenAI Responses image_generation call reference.
 
-    OpenAI accepts prior ``image_generation_call`` items in the next
-    Responses ``input`` array so follow-up prompts can edit or refine a
-    generated image without resending the base64 payload. The frontend
-    forwards this as a synthetic assistant content part when building
-    the next OpenAI Responses request; ``external_provider`` translates
-    it back to the provider-specific top-level input item.
+    OpenAI accepts prior ``image_generation_call`` items in the next Responses
+    ``input`` array so follow-up prompts can edit or refine a generated image
+    without resending the base64 payload. The frontend forwards this as a
+    synthetic assistant content part when building the next request;
+    ``external_provider`` maps it back to the provider-specific top-level
+    input item.
     """
 
     type: Literal["image_generation_call"]
@@ -472,14 +465,13 @@ class CompactionContentPart(BaseModel):
     """Anthropic server-side compaction state, attached to an assistant
     message for round-tripping on the next turn.
 
-    When Anthropic runs compaction during a request, the response
-    carries a ``{"type": "compaction", "content": "<summary>"}`` block
-    on the assistant message. The chat-adapter persists it onto the
-    stored message; the next turn's outbound request must forward it
-    back so Anthropic recognises the existing compaction state and
-    doesn't re-summarise the conversation from scratch. See
-    ``external_provider._stream_anthropic`` for the wire-side handling
-    and https://platform.claude.com/docs/en/build-with-claude/compaction
+    When Anthropic compacts during a request, the response carries a
+    ``{"type": "compaction", "content": "<summary>"}`` block on the assistant
+    message. The chat-adapter persists it; the next turn's outbound request
+    must forward it back so Anthropic recognises the existing compaction state
+    and doesn't re-summarise from scratch. See
+    ``external_provider._stream_anthropic`` for the wire-side handling and
+    https://platform.claude.com/docs/en/build-with-claude/compaction
     for the upstream contract.
     """
 
@@ -516,9 +508,9 @@ ContentPart = Annotated[
 class ChatMessage(BaseModel):
     """Single message in a chat conversation.
 
-    ``content`` is a string or a list of multimodal content parts. Assistant
-    messages with only ``tool_calls`` populated may set ``content=None``.
-    Missing ``tool_call_id`` on ``role="tool"`` is resolved at the
+    ``content`` is a string or list of multimodal content parts. Assistant
+    messages with only ``tool_calls`` may set ``content=None``. Missing
+    ``tool_call_id`` on ``role="tool"`` is resolved at the
     ``ChatCompletionRequest`` layer by walking back to the preceding assistant.
     """
 
@@ -571,16 +563,15 @@ class ChatMessage(BaseModel):
 
 
 class ChatCompletionRequest(BaseModel):
-    """
-    OpenAI-compatible chat completion request.
+    """OpenAI-compatible chat completion request.
 
-    Extensions (non-OpenAI fields) are marked with 'x-unsloth'.
+    Non-OpenAI extension fields are marked with 'x-unsloth'.
     """
 
-    # Accept unknown fields defensively so future OpenAI fields (seed,
-    # response_format, logprobs, frequency_penalty, etc.) don't get
-    # silently dropped by Pydantic before route code runs. Mirrors
-    # AnthropicMessagesRequest and ResponsesRequest.
+    # Accept unknown fields so future OpenAI fields (seed, response_format,
+    # logprobs, frequency_penalty, etc.) aren't silently dropped by Pydantic
+    # before route code runs. Mirrors AnthropicMessagesRequest and
+    # ResponsesRequest.
     model_config = {"extra": "allow"}
 
     model: str = Field(
@@ -738,18 +729,16 @@ class ChatCompletionRequest(BaseModel):
     @field_validator("enable_prompt_caching", mode = "before")
     @classmethod
     def _coerce_enable_prompt_caching(cls, value: Any) -> Any:
-        """Preserve the pre-PR coercion: the field used to be Optional[bool],
-        so callers historically sent JSON strings `"true"` / `"false"` and
-        Pydantic v1 coerced them. Widening to Optional[Union[bool, str]] for
-        Gemini cache resource names lets `"false"` slip through as a truthy
-        string. Coerce the canonical bool literals back so explicit opt-outs
-        stay opt-out."""
+        """Preserve the pre-PR coercion. The field was once Optional[bool], so
+        callers historically sent JSON strings `"true"` / `"false"` that
+        Pydantic v1 coerced. Widening to Optional[Union[bool, str]] for Gemini
+        cache resource names lets `"false"` slip through as truthy; coerce the
+        canonical bool literals back so explicit opt-outs stay opt-out."""
         if isinstance(value, str):
             lowered = value.strip().lower()
             # Match Pydantic v1's BooleanField coercion table (yes/y/on/t/1
-            # and no/n/off/f/0) so opt-outs that used to parse still parse.
-            # Anything else is preserved as a string for Gemini's
-            # cachedContent resource path.
+            # and no/n/off/f/0) so old opt-outs still parse. Anything else
+            # stays a string for Gemini's cachedContent resource path.
             if lowered in ("true", "t", "1", "yes", "y", "on"):
                 return True
             if lowered in ("false", "f", "0", "no", "n", "off"):
@@ -836,10 +825,10 @@ class ChatCompletionRequest(BaseModel):
 
         OpenAI / Anthropic passthrough require the result id to match the
         assistant's tool_calls[].id. Prefer function.name match, else first
-        unconsumed tool_call; synth random id only if no candidate exists.
-        Crossing a user turn breaks the lookup.
+        unconsumed tool_call; synth a random id only if none exists. A user
+        turn breaks the lookup.
         """
-        # Pre-mark explicit ids first so a sibling missing-id result does not
+        # Pre-mark explicit ids first so a sibling missing-id result doesn't
         # steal one already claimed by name.
         consumed: set[tuple[int, int]] = set()
 
@@ -902,12 +891,10 @@ class ChatCompletionRequest(BaseModel):
 
 
 class OpenAIContainerRequest(BaseModel):
-    """
-    Shared body for the three OpenAI container endpoints (list / create
-    / delete). Carries the encrypted API key + base URL so the route
-    handler can decrypt it and proxy to the user's OpenAI account.
-    Same pattern as the inference proxy endpoints — keeps the key off
-    persistent storage on the backend.
+    """Shared body for the three OpenAI container endpoints (list / create /
+    delete). Carries the encrypted API key + base URL so the route handler
+    can decrypt it and proxy to the user's OpenAI account. Same pattern as the
+    inference proxy endpoints — keeps the key off backend persistent storage.
     """
 
     encrypted_api_key: str = Field(
@@ -1055,10 +1042,10 @@ class ResponsesOutputTextPart(BaseModel):
     """Assistant ``output_text`` content part replayed on subsequent turns.
 
     When a client (OpenAI Codex CLI, OpenAI Python SDK agents) loops on a
-    stateless Responses endpoint, prior assistant messages are round-tripped
-    as ``{"role":"assistant","content":[{"type":"output_text","text":...,
-    "annotations":[],"logprobs":[]}]}``. We preserve the text and ignore
-    the annotations/logprobs metadata when flattening into Chat Completions.
+    stateless Responses endpoint, prior assistant messages round-trip as
+    ``{"role":"assistant","content":[{"type":"output_text","text":...,
+    "annotations":[],"logprobs":[]}]}``. We keep the text and ignore the
+    annotations/logprobs metadata when flattening into Chat Completions.
     """
 
     type: Literal["output_text"]
@@ -1073,8 +1060,8 @@ class ResponsesUnknownContentPart(BaseModel):
     """Catch-all for content-part types we don't model explicitly.
 
     Keeps validation green when a client sends newer part types (e.g.
-    ``input_audio``, ``input_file``) we haven't mapped; these are silently
-    skipped during normalisation rather than rejected with a 422.
+    ``input_audio``, ``input_file``) we haven't mapped; these are skipped
+    during normalisation rather than rejected with a 422.
     """
 
     type: str
@@ -1099,16 +1086,15 @@ class ResponsesInputMessage(BaseModel):
 
     # Codex (gpt-5.3-codex+) attaches a `phase` field ("commentary" |
     # "final_answer") to assistant messages and requires clients to preserve
-    # it on subsequent turns. We accept and round-trip it; llama-server does
-    # not care about it.
+    # it across turns. We accept and round-trip it; llama-server ignores it.
     model_config = {"extra": "allow"}
 
 
 class ResponsesFunctionCallInputItem(BaseModel):
-    """A prior assistant function_call being replayed in a multi-turn Responses input.
+    """A prior assistant function_call replayed in a multi-turn Responses input.
 
     The Responses API represents tool calls as top-level input items (not
-    nested inside assistant messages), correlated across turns by ``call_id``.
+    nested in assistant messages), correlated across turns by ``call_id``.
     """
 
     type: Literal["function_call"]
@@ -1125,7 +1111,7 @@ class ResponsesFunctionCallInputItem(BaseModel):
 class ResponsesFunctionCallOutputInputItem(BaseModel):
     """A tool result supplied by the client for a prior function_call.
 
-    Replaces Chat Completions' ``role="tool"`` message. Correlated to the
+    Replaces Chat Completions' ``role="tool"`` message. Correlated to its
     originating call by ``call_id``.
     """
 
@@ -1142,10 +1128,9 @@ class ResponsesUnknownInputItem(BaseModel):
     """Catch-all for Responses input item types we don't model explicitly.
 
     Covers ``reasoning`` items (replayed from prior o-series / gpt-5 turns)
-    and any future item types the client may send. These items are dropped
-    during normalisation — llama-server-backed GGUFs cannot consume them —
-    but keeping them in the request-model union stops unrelated turns from
-    failing validation with a 422.
+    and any future item types. Dropped during normalisation (llama-server
+    GGUFs can't consume them), but keeping them in the request-model union
+    stops unrelated turns from failing validation with a 422.
     """
 
     type: str
@@ -1156,12 +1141,11 @@ class ResponsesUnknownInputItem(BaseModel):
 def _responses_input_item_discriminator(v: Any) -> str:
     """Route a Responses input item to the correct tagged variant.
 
-    Pydantic's default smart-union matching fails when one variant in the
-    union is tagged with a strict ``Literal`` (``function_call`` /
-    ``function_call_output``) and the incoming dict uses a different
-    ``type`` — the other variants' validation errors are hidden and the
-    outer ``Union[str, list[...]]`` reports a misleading "Input should be a
-    valid string" error. An explicit discriminator makes the routing
+    Pydantic's smart-union matching fails when one union variant is tagged
+    with a strict ``Literal`` (``function_call`` / ``function_call_output``)
+    and the incoming dict has a different ``type``: other variants' errors are
+    hidden and the outer ``Union[str, list[...]]`` reports a misleading "Input
+    should be a valid string". An explicit discriminator makes routing
     deterministic and lets us fall through to the catch-all.
     """
     if isinstance(v, dict):
@@ -1191,12 +1175,12 @@ ResponsesInputItem = Annotated[
 
 
 class ResponsesFunctionTool(BaseModel):
-    """Flat function-tool definition used by the Responses API request.
+    """Flat function-tool definition for the Responses API request.
 
     Unlike Chat Completions (which nests ``{"name": ..., "parameters": ...}``
-    inside a ``"function"`` key), the Responses API uses a flat shape with
-    ``type``, ``name``, ``description``, ``parameters``, and ``strict`` at the
-    top level of each tool entry.
+    under a ``"function"`` key), the Responses API uses a flat shape with
+    ``type``, ``name``, ``description``, ``parameters``, ``strict`` at the top
+    level of each tool entry.
     """
 
     type: Literal["function"]
@@ -1220,11 +1204,11 @@ class ResponsesRequest(BaseModel):
     max_output_tokens: Optional[int] = Field(None, ge = 1)
     stream: bool = Field(False, description = "Whether to stream the response via SSE")
 
-    # OpenAI function-calling fields — forwarded to llama-server via the
-    # Chat Completions pass-through (see routes/inference.py). Typed as a
-    # plain list so built-in tool shapes (``web_search``, ``file_search``,
-    # ``mcp``, ...) round-trip without validation errors — the translator
-    # picks out only ``type=="function"`` entries for forwarding.
+    # OpenAI function-calling fields, forwarded to llama-server via the Chat
+    # Completions pass-through (see routes/inference.py). Plain list so
+    # built-in tool shapes (``web_search``, ``file_search``, ``mcp``, ...)
+    # round-trip without validation errors; the translator forwards only
+    # ``type=="function"`` entries.
     tools: Optional[list[dict]] = Field(
         None,
         description = (
@@ -1280,10 +1264,9 @@ class ResponsesOutputMessage(BaseModel):
 class ResponsesOutputFunctionCall(BaseModel):
     """A function-call output item in the Responses API response.
 
-    Unlike Chat Completions (which nests tool calls inside the assistant
-    message), the Responses API emits each tool call as its own top-level
-    ``output`` item so clients can correlate results via ``call_id`` on the
-    next turn.
+    Unlike Chat Completions (tool calls nested in the assistant message), the
+    Responses API emits each tool call as its own top-level ``output`` item so
+    clients can correlate results via ``call_id`` on the next turn.
     """
 
     type: Literal["function_call"] = "function_call"
@@ -1439,7 +1422,7 @@ class AnthropicMessagesRequest(BaseModel):
     top_k: Optional[int] = None
     stop_sequences: Optional[list[str]] = None
     metadata: Optional[dict] = None
-    # [x-unsloth] extensions — mirror the OpenAI endpoint convenience fields
+    # [x-unsloth] extensions mirroring the OpenAI endpoint convenience fields
     min_p: Optional[float] = Field(
         None, ge = 0.0, le = 1.0, description = "[x-unsloth] Min-p sampling threshold"
     )
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index 3dd8e779f7..ff00363ff8 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for Model Management API
-"""
+"""Pydantic schemas for Model Management API"""
 
 from pydantic import BaseModel, Field
 from typing import Optional, List, Dict, Any, Literal
@@ -56,7 +54,7 @@ class CheckpointListResponse(BaseModel):
 
 
 class ModelDetails(BaseModel):
-    """Detailed model configuration and metadata - can be used for both list and detail views"""
+    """Model configuration and metadata; used for both list and detail views"""
 
     id: str = Field(..., description = "Model identifier")
     model_name: Optional[str] = Field(
diff --git a/studio/backend/models/providers.py b/studio/backend/models/providers.py
index e9d2d859f5..8f90e19df6 100644
--- a/studio/backend/models/providers.py
+++ b/studio/backend/models/providers.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic schemas for the external LLM providers API.
-"""
+"""Pydantic schemas for the external LLM providers API."""
 
 from typing import Literal, Optional
 
diff --git a/studio/backend/models/responses.py b/studio/backend/models/responses.py
index f6357bf999..cc420c0f69 100644
--- a/studio/backend/models/responses.py
+++ b/studio/backend/models/responses.py
@@ -1,10 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Pydantic response schemas for endpoints that previously returned raw dicts.
-These are small response models for training and model management routes.
-"""
+"""Pydantic response models for training and model management routes
+(previously returned as raw dicts)."""
 
 from pydantic import BaseModel, Field
 from typing import Optional, List
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index cef0b8f36f..829be12c91 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -26,7 +26,7 @@ _MAX_LR_VALUE = 1.0
 _MAX_LORA_R = 16_384
 _MAX_LORA_ALPHA = 32_768
 _MIN_VISION_IMAGE_SIZE = 256
-# 2048 was the most I could get most llms to work at without getting unstable
+# 2048 is the highest most llms stay stable at
 _MAX_VISION_IMAGE_SIZE = 2048
 
 
@@ -343,7 +343,7 @@ class TrainingStartRequest(BaseModel):
     @model_validator(mode = "after")
     def _check_steps_or_epochs(self) -> "TrainingStartRequest":
         # num_epochs and max_steps each accept 0 as a "use the other one"
-        # sentinel. If both resolve to 0 there's nothing to train against.
+        # sentinel. Both 0 means nothing to train against.
         if (self.max_steps is None or self.max_steps == 0) and self.num_epochs == 0:
             raise ValueError("Either num_epochs or max_steps must be > 0; both cannot be 0.")
         return self
diff --git a/studio/backend/models/users.py b/studio/backend/models/users.py
index 6a28d3ea55..738c76c576 100644
--- a/studio/backend/models/users.py
+++ b/studio/backend/models/users.py
@@ -1,10 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Pydantic models for authentication tokens.
-
-This module defines the Token response model used by auth routes.
-"""
+"""Pydantic models for authentication tokens."""
 
 from pydantic import BaseModel, Field
 
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
index f57af4c6c3..fd3846dc21 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
@@ -3,5 +3,5 @@
 
 # Intentionally empty. Data-designer loads submodules lazily via qualified names
 # (impl_qualified_name / config_qualified_name in plugin.py), so importing this
-# package must NOT touch modules that depend on data_designer.engine.* during
+# package must NOT touch modules depending on data_designer.engine.* during
 # Studio's bootstrap (circular import).
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
index 5a38e26d6b..9190b6a738 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
@@ -17,13 +17,12 @@ from .scraper import ScrapeConfig, materialize_to_jsonl
 
 
 # In-process cache mapping a stable config signature to the JSONL materialization
-# path. A single recipe job invokes the seed reader multiple times (validation,
-# preview, per-column sampling), and the default flow re-scrapes the repo on
-# every call: for a 2-repo preview that is ~15s of redundant GitHub GraphQL
-# traffic before any generation fires. Memoize the materialization so the second
-# and third passes reuse the file the first pass wrote. Cache key excludes the
-# raw token and uses a short SHA-256 digest so token values never hit memory
-# twice and token rotation invalidates cleanly.
+# path. A recipe job calls the seed reader multiple times (validation, preview,
+# per-column sampling) and the default flow re-scrapes on every call: a 2-repo
+# preview is ~15s of redundant GitHub GraphQL traffic before any generation.
+# Memoize so later passes reuse the first pass's file. The key excludes the raw
+# token and uses a short SHA-256 digest, so token values never hit memory twice
+# and rotation invalidates cleanly.
 _SCRAPE_CACHE: dict[tuple, str] = {}
 _SCRAPE_CACHE_LOCK = threading.Lock()
 
@@ -47,8 +46,8 @@ def _lookup_cached_scrape(key: tuple) -> Optional[str]:
         path = _SCRAPE_CACHE.get(key)
     if path and Path(path).exists():
         return path
-    # Stale entry (tmp cleanup, user restarted, ...); drop it so the caller
-    # materializes a fresh file rather than returning a dangling path.
+    # Stale entry (tmp cleanup, restart, ...); drop it so the caller
+    # materializes a fresh file instead of returning a dangling path.
     if path:
         with _SCRAPE_CACHE_LOCK:
             _SCRAPE_CACHE.pop(key, None)
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
index d468db70d2..926606c24c 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
@@ -3,11 +3,10 @@
 
 """Multi-repo GitHub scraper for the Studio seed plugin.
 
-Drives the GraphQL-based scraper in `scraper_impl/` per repo. Each repo is
-scraped with a trial_limits cap so we stop at `limit` items per resource.
-After scraping, we read the per-resource JSONL shards and flatten them into
-a single unified JSONL with stable columns (`item_type`, `repo`, `number`,
-`title`, `body`, ...).
+Drives the GraphQL scraper in `scraper_impl/` per repo, capped via trial_limits
+to stop at `limit` items per resource. Then reads the per-resource JSONL shards
+and flattens them into one unified JSONL with stable columns (`item_type`,
+`repo`, `number`, `title`, `body`, ...).
 """
 
 from __future__ import annotations
@@ -166,7 +165,7 @@ def scrape(cfg: ScrapeConfig, base_dir: Path):
     client = GitHubClient(token = token.value, token_source = token.source)
     base_dir.mkdir(parents = True, exist_ok = True)
 
-    # Per-resource trial limits. limit <= 0 means "all": use a very large cap.
+    # Per-resource trial limits. limit <= 0 means "all": use a large cap.
     effective_limit = cfg.limit if cfg.limit and cfg.limit > 0 else 1_000_000
     trial_limits: dict[str, int] = {}
     if "issues" in cfg.item_types:
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
index eda242a6ea..9ab174c2d4 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
@@ -110,12 +110,11 @@ class GitHubClient:
         )
 
     def _is_auth_failure(self, r: "requests.Response") -> bool:
-        """Distinguish auth failures from rate limiting on 401/403 responses.
+        """Tell auth failures apart from rate limiting on 401/403.
 
         - 401: always an auth failure (invalid / expired / wrong-scope token).
-        - 403: an auth failure UNLESS the response carries a clear rate-limit signal
-          (Retry-After header, X-RateLimit-Remaining: 0, or GitHub's secondary /
-          abuse rate-limit response text).
+        - 403: auth failure UNLESS it carries a rate-limit signal (Retry-After,
+          X-RateLimit-Remaining: 0, or secondary / abuse rate-limit text).
         """
         if r.status_code == 401:
             return True
@@ -169,7 +168,7 @@ class GitHubClient:
                     timeout = 120,
                 )
                 self.calls_graphql += 1
-                # Update rate info from response headers
+                # Update rate info from headers
                 rem = r.headers.get("X-RateLimit-Remaining")
                 rst = r.headers.get("X-RateLimit-Reset")
                 if rem is not None:
@@ -190,7 +189,7 @@ class GitHubClient:
                 if self._is_auth_failure(r):
                     self._raise_auth_error(r, "GraphQL")
                 if r.status_code == 403 or r.status_code == 429:
-                    # Check for secondary/abuse
+                    # Secondary/abuse rate limit
                     retry_after = _retry_after_seconds(r.headers.get("Retry-After"))
                     if retry_after is not None:
                         log.warning("Secondary rate limit. Sleep %ds.", retry_after)
@@ -204,15 +203,14 @@ class GitHubClient:
                 r.raise_for_status()
                 data = r.json()
                 if "errors" in data and data["errors"]:
-                    # Surface errors but allow partial data
+                    # Surface errors but allow partial data; retry on RATE_LIMITED
                     errs = data["errors"]
-                    # Retry on RATE_LIMITED
                     for e in errs:
                         if e.get("type") == "RATE_LIMITED":
                             self._sleep_until((self.graphql_reset or int(time.time()) + 60))
                             break
                     else:
-                        # No rate-limit error, log and return partial
+                        # No rate-limit error: log and return partial
                         log.warning("GraphQL errors: %s", json.dumps(errs)[:400])
                         return data
                     continue
@@ -268,7 +266,7 @@ class GitHubClient:
                         log.warning("Secondary rate limit on REST. Sleep %ds.", retry_after)
                         time.sleep(retry_after + 2)
                         continue
-                    # Check if primary rate
+                    # Primary rate limit
                     if self.rest_remaining == 0 and self.rest_reset:
                         self._sleep_until(self.rest_reset)
                         continue
@@ -299,11 +297,11 @@ class GitHubClient:
                 return
             items = r.json()
             if isinstance(items, dict):
-                # Some endpoints return dict with list field
+                # Some endpoints wrap the list in an "items" field
                 items = items.get("items", [])
             for it in items:
                 yield it
-            # Follow link header
+            # Follow Link header
             link = r.headers.get("Link", "")
             nxt = None
             for part in link.split(","):
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/queries.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/queries.py
index 9dc7613db5..ff2a81d1c3 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/queries.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/queries.py
@@ -3,11 +3,11 @@
 
 """GraphQL queries for GitHub data scraping.
 
-GitHub's GraphQL rejects queries that define unused fragments, so each query
-only includes the fragments it actually references.
+GitHub's GraphQL rejects queries with unused fragments, so each query includes
+only the fragments it references.
 """
 
-# ---- Fragments (kept as raw strings, composed per query) ----
+# ---- Fragments (raw strings, composed per query) ----
 F_ACTOR = """
 fragment ActorFields on Actor {
   __typename
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
index 826ffc1256..08e2a28ceb 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Main scraper orchestration. Collects issues, PRs, discussions, commits, releases, etc.
+"""Scraper orchestration: issues, PRs, discussions, commits, releases, etc.
 
 Resumable via state file. Writes JSONL shards under data/{repo}/{resource}.jsonl.
 """
@@ -49,9 +49,9 @@ class RepoScraper:
         self.base_dir = base_dir
         self.client = client
         self.trial_limits = trial_limits or {}
-        # When light=True, use trimmed GraphQL queries (no reviewThreads,
-        # reviews, commits, timelineItems, files) so PR pages can be much
-        # larger without blowing GitHub's node-count ceiling.
+        # light=True uses trimmed GraphQL queries (no reviewThreads,
+        # reviews, commits, timelineItems, files) so PR pages can be larger
+        # without hitting GitHub's node-count ceiling.
         self.light = light
         self.repo_dir = base_dir / f"{owner}__{name}"
         self.repo_dir.mkdir(parents = True, exist_ok = True)
@@ -225,8 +225,8 @@ class RepoScraper:
         page = 0
         # Heavy nested PR query is capped at 3 per page (GitHub node-count
         # ceiling); light query skips reviewThreads/reviews/commits/etc and
-        # can safely go to 25 per page. Clamp by trial_limit for small
-        # previews so limit=1 does not fetch a whole 25-item page.
+        # goes to 25 per page. Clamp by trial_limit so limit=1 does not
+        # fetch a whole 25-item page.
         page_cap = 25 if self.light else 3
         trial_cap = self.trial_limits.get(key)
         per_page = min(page_cap, trial_cap) if trial_cap and trial_cap > 0 else page_cap
@@ -370,7 +370,7 @@ class RepoScraper:
                 f["_owner"] = self.owner
                 f["_repo"] = self.name
                 f["_prNumber"] = number
-                # files don't have id, synthesize one
+                # files have no id; synthesize one
                 f["_syntheticId"] = f"{self.owner}/{self.name}#{number}:{f.get('path')}"
                 self.writers[out_key].write(f)
             info = ff.get("pageInfo") or {}
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
index de9ccca82b..67107c285a 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/state_store.py
@@ -65,7 +65,7 @@ class JsonlWriter:
         self._lock = threading.Lock()
         self._fh = self.path.open("a", buffering = 1)
         self._count_seen_keys: set[str] = set()
-        # Preload seen keys if file exists (for dedup across resumes)
+        # Preload seen keys for dedup across resumes
         if self.path.exists() and self.path.stat().st_size > 0:
             try:
                 with self.path.open() as f:
diff --git a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
index 4da46634e5..e5c2f7a492 100644
--- a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
+++ b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
@@ -70,11 +70,11 @@ def build_multi_file_preview_rows(
 
 
 def _round_robin_preview(rows: list[dict[str, str]], preview_size: int) -> list[dict[str, str]]:
-    """Pick preview rows round-robin across source files so every file is represented."""
+    """Pick preview rows round-robin across source files so each is represented."""
     if not rows or preview_size <= 0:
         return []
 
-    # Group rows by source_file, preserving order of first appearance
+    # Group rows by source_file, preserving first-appearance order.
     from collections import OrderedDict
 
     grouped: OrderedDict[str, list[dict[str, str]]] = OrderedDict()
@@ -147,7 +147,7 @@ def materialize_multi_file_unstructured_seed(
     chunk_size: int,
     chunk_overlap: int,
 ) -> tuple[Path, list[dict[str, str]]]:
-    """Chunk multiple files and combine into one parquet dataset with source_file column."""
+    """Chunk multiple files into one parquet dataset with a source_file column."""
     chunk_size, chunk_overlap = resolve_chunking(chunk_size, chunk_overlap)
     cache_key = _compute_multi_file_cache_key(file_entries, chunk_size, chunk_overlap)
     cached = _CACHE_DIR / f"{cache_key}.parquet"
diff --git a/studio/backend/requirements/single-env/patch_metadata.py b/studio/backend/requirements/single-env/patch_metadata.py
index 7bcaa56ac8..6c3ee4af52 100644
--- a/studio/backend/requirements/single-env/patch_metadata.py
+++ b/studio/backend/requirements/single-env/patch_metadata.py
@@ -2,14 +2,14 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Relax strict metadata pins so pip check matches known working single-env stack.
+"""Relax strict metadata pins so pip check passes on the single-env stack.
 
 Why:
 - data-designer pins huggingface-hub>=1.0.1 and pyarrow<20.
 - unsloth/transformers pins huggingface-hub<1.
 - studio datasets pins pyarrow>=21.
 
-Runtime works in this app with hub 0.36.x + pyarrow 23.x, but metadata conflicts.
+Runtime works with hub 0.36.x + pyarrow 23.x; only the metadata conflicts.
 """
 
 from __future__ import annotations
diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index 7c60545595..c19560c529 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -43,17 +43,17 @@ router = APIRouter()
 def _reset_password_command() -> str:
     """Shell command shown in the 'incorrect password' hint.
 
-    Prefer the ABSOLUTE path to this install's ``unsloth`` launcher (a sibling
-    of the running interpreter) so the hint works even when the launcher's
-    directory is not on PATH -- e.g. a terminal opened before install, a stale
-    Windows PATH, or ``~/.local/bin`` not on PATH (the default on macOS) -- and
-    regardless of the current working directory.
+    Prefer the ABSOLUTE path to this install's ``unsloth`` launcher (sibling of
+    the running interpreter) so the hint works even when the launcher's dir
+    isn't on PATH -- e.g. a terminal opened before install, a stale Windows
+    PATH, or ``~/.local/bin`` not on PATH (the macOS default) -- regardless of
+    the cwd.
 
-    On POSIX the path is shell-quoted so spaces are handled. On Windows we only
-    use the bare absolute path when it has no spaces, because a quoted path needs
-    different syntax in cmd (``"..."``) vs PowerShell (``& "..."``); when it has
-    a space we fall back to the PATH-based form to stay unambiguous across
-    shells. If the launcher can't be located we fall back to the PATH form too.
+    On POSIX the path is shell-quoted to handle spaces. On Windows we use the
+    bare absolute path only when it has no spaces, since a quoted path needs
+    different syntax in cmd (``"..."``) vs PowerShell (``& "..."``); with a
+    space we fall back to the PATH-based form to stay unambiguous across shells.
+    We also fall back to the PATH form if the launcher can't be located.
     """
     try:
         bin_dir = os.path.dirname(os.path.abspath(sys.executable))
@@ -72,7 +72,7 @@ def _reset_password_command() -> str:
 
 # Per-(ip, username) bucket + per-IP aggregate. Account bucket stops one user's
 # typos from blocking others; the aggregate stops username-rotation spray.
-# Single-process only -- multi-worker deployments need a shared store.
+# Single-process only; multi-worker deployments need a shared store.
 _LOGIN_BUCKETS: dict[tuple[str, str], deque] = {}
 _LOGIN_IP_BUCKETS: dict[str, deque] = {}
 _LOGIN_BUCKETS_LOCK = threading.Lock()
@@ -80,18 +80,18 @@ _LOGIN_WINDOW_SECONDS = 60.0
 _LOGIN_MAX_FAILS = 5
 _LOGIN_IP_MAX_FAILS = 30
 _LOGIN_LOCKOUT_SECONDS = 60
-# Bucket-dict cap. On overflow we prune stale entries; if still full the
-# failure folds into the per-IP aggregate only.
+# Bucket-dict cap. On overflow, prune stale entries; if still full the failure
+# folds into the per-IP aggregate only.
 _LOGIN_MAX_BUCKETS = 4096
 # Unrepresentable as a real username (leading NUL); folds unknown-user attempts
-# into one slot so attacker cardinality cannot blow the bucket dict.
+# into one slot so attacker cardinality can't blow the bucket dict.
 _UNKNOWN_LOGIN_USER = "\x00unknown-user"
 
 
 def _trust_forwarded_for() -> bool:
     """Honour X-Forwarded-For only when UNSLOTH_STUDIO_TRUST_FORWARDED is set.
 
-    Off by default so a direct caller cannot spoof the header.
+    Off by default so a direct caller can't spoof the header.
     """
     return os.environ.get("UNSLOTH_STUDIO_TRUST_FORWARDED", "").lower() in (
         "1",
@@ -112,7 +112,7 @@ def _normalize_forwarded_addr(value: str) -> str:
             return ""
         host = value[1:end]
     elif value.count(":") == 1:
-        # IPv4:port. Bare IPv6 has multiple colons and takes the else branch.
+        # IPv4:port. Bare IPv6 has multiple colons → else branch.
         head, _, tail = value.rpartition(":")
         host = head if tail.isdigit() and head else value
     else:
@@ -144,7 +144,7 @@ def _client_ip(request: Request | None) -> str:
                 return normalized
         fwd = request.headers.get("forwarded", "")
         if fwd:
-            # First element only -- multi-element headers cannot fork buckets.
+            # First element only; multi-element headers can't fork buckets.
             normalized = _forwarded_for_from_element(fwd.split(",", 1)[0])
             if normalized:
                 return normalized
@@ -190,7 +190,7 @@ def _record_login_failure(key: tuple[str, str]) -> int:
             _prune_bucket(account_bucket, now)
             account_bucket.append(now)
             return len(account_bucket)
-        # Bucket dict is at its cap; per-IP cap still applies via ip_bucket.
+        # Bucket dict at cap; per-IP cap still applies via ip_bucket.
         return len(ip_bucket)
 
 
@@ -242,16 +242,16 @@ async def login(payload: AuthLoginRequest, request: Request) -> Token:
     if blocked_for > 0:
         raise HTTPException(
             status_code = status.HTTP_429_TOO_MANY_REQUESTS,
-            # IP is intentionally not interpolated into the body; behind a
-            # proxy or NAT it is either misleading or an info leak.
+            # IP not interpolated into the body; behind a proxy/NAT it's
+            # misleading or an info leak.
             detail = (f"Too many failed login attempts. " f"Try again in {blocked_for} seconds."),
             headers = {"Retry-After": str(blocked_for)},
         )
 
     record = storage.get_user_and_secret(payload.username)
     if record is None:
-        # Record under a single sentinel key per IP so attacker-controlled
-        # username cardinality does not allocate buckets without bound.
+        # Record under one sentinel key per IP so attacker-controlled username
+        # cardinality can't allocate unbounded buckets.
         _record_login_failure(unknown_key)
         raise HTTPException(
             status_code = status.HTTP_401_UNAUTHORIZED,
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 68d2c67ec8..8496c970d0 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -189,21 +189,20 @@ class ChatMessagesBatchResponse(BaseModel):
 
 
 class ChatImportLedgerResponse(BaseModel):
-    # Plain list of legacy thread ids. Keeping the payload key-less keeps
-    # the client diff to a single Set construction.
+    # Plain list of legacy thread ids; key-less payload keeps the client diff
+    # to a single Set construction.
     threadIds: list[str]
 
 
 class ChatImportLedgerRecordRequest(BaseModel):
-    # 10k cap keeps the request body bounded; real users have << 1k threads.
+    # 10k cap bounds the request body; real users have << 1k threads.
     threadIds: list[str] = Field(default_factory = list, max_length = 10_000)
 
 
 class ChatImportLedgerRecordResponse(BaseModel):
     # accepted: deduped non-empty input count. inserted: rows actually new
     # (ON CONFLICT DO NOTHING skips already-recorded ids). The client uses
-    # `accepted >= 0` as the "endpoint exists" signal and ignores the split
-    # otherwise.
+    # `accepted >= 0` as the "endpoint exists" signal and ignores the split.
     accepted: int
     inserted: int
 
@@ -353,7 +352,7 @@ async def batch_thread_messages(
     payload: ChatMessagesBatchRequest, current_subject: str = Depends(get_current_subject)
 ):
     """One round-trip per sidebar/search rebuild instead of N. Unknown thread
-    ids are returned as empty lists so callers don't need a pre-flight."""
+    ids return empty lists so callers don't need a pre-flight."""
     by_thread: dict[str, list[ChatMessage]] = {tid: [] for tid in payload.threadIds}
     for m in list_chat_messages_for_threads(payload.threadIds):
         tid = m["threadId"]
@@ -444,11 +443,10 @@ async def count_threads(current_subject: str = Depends(get_current_subject)):
 
 @router.get("/import-ledger", response_model = ChatImportLedgerResponse)
 async def get_import_ledger(current_subject: str = Depends(get_current_subject)):
-    """Legacy-Dexie import ledger. Returns the set of legacy thread ids
-    already copied into chat_threads / chat_messages. The frontend
-    uses this on every fresh tab open to decide whether to re-run the
-    Dexie -> studio.db import. Source of truth lives inside studio.db
-    so a studio.db wipe makes the import recoverable."""
+    """Legacy-Dexie import ledger. Returns the legacy thread ids already copied
+    into chat_threads / chat_messages. The frontend uses this on every fresh tab
+    open to decide whether to re-run the Dexie -> studio.db import. Source of
+    truth lives in studio.db, so a studio.db wipe makes the import recoverable."""
     return ChatImportLedgerResponse(threadIds = list_chat_legacy_imports())
 
 
@@ -480,8 +478,8 @@ async def put_settings(
         parsed = ChatSettingsPayload.model_validate(payload)
     except ValidationError as exc:
         raise HTTPException(status_code = 400, detail = exc.errors()) from exc
-    # Atomic read + deep-merge + write inside one BEGIN IMMEDIATE so two
-    # concurrent slider drags can't drop each other's updates.
+    # Atomic read + deep-merge + write in one BEGIN IMMEDIATE so concurrent
+    # slider drags can't drop each other's updates.
     try:
         return ChatSettingsResponse(
             settings = upsert_chat_settings_merge(parsed.model_dump(exclude_unset = True))
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index a2d41f87b0..01991cd865 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -36,14 +36,14 @@ def _resolve_local_v1_endpoint(request: Request) -> str:
     """Return the loopback /v1 URL for the actual backend listen port.
 
     Resolution order:
-      1. ``app.state.server_port`` - explicitly published by run.py after
-         the uvicorn server has bound. This is the most reliable source
-         because it survives reverse proxies, TLS terminators and tunnels.
+      1. ``app.state.server_port`` - published by run.py after uvicorn
+         binds. Most reliable; survives reverse proxies, TLS terminators,
+         and tunnels.
       2. ``request.scope["server"]`` - the real (host, port) tuple uvicorn
-         sets when the request is dispatched. Used when Studio is started
-         outside ``run_server`` (e.g. ``uvicorn studio.backend.main:app``).
-      3. ``request.base_url`` parsed - last resort for test fixtures that
-         do not route through a live uvicorn server.
+         sets per request. Used when Studio starts outside ``run_server``
+         (e.g. ``uvicorn studio.backend.main:app``).
+      3. ``request.base_url`` parsed - last resort for test fixtures with
+         no live uvicorn server.
     """
     port: Any = getattr(request.app.state, "server_port", None)
     if not isinstance(port, int) or port <= 0:
@@ -76,14 +76,14 @@ def _request_has_desktop_access_token(request: Request) -> bool:
 
 
 def _used_llm_model_aliases(recipe: dict[str, Any]) -> set[str]:
-    """Return the set of model_aliases that are actually referenced by an
-    LLM column. Used to narrow the "Chat model loaded" gate so that orphan
-    model_config nodes on the canvas do not block unrelated recipe runs.
+    """Return model_aliases actually referenced by an LLM column. Narrows
+    the "Chat model loaded" gate so orphan model_config nodes on the canvas
+    do not block unrelated recipe runs.
 
-    The ``llm-`` prefix matches the existing convention in
+    The ``llm-`` prefix matches the convention in
     ``core/data_recipe/service.py::_recipe_has_llm_columns`` and covers all
-    LLM column types emitted by the frontend (llm-text, llm-code,
-    llm-structured, llm-judge).
+    frontend LLM column types (llm-text, llm-code, llm-structured,
+    llm-judge).
     """
     aliases: set[str] = set()
     for column in recipe.get("columns", []):
@@ -180,18 +180,17 @@ def _ensure_selected_local_model_loaded(
 def _inject_local_structured_response_format(
     recipe: dict[str, Any], local_provider_names: set[str]
 ) -> None:
-    """For each llm-structured column that targets a local-provider model_config,
-    clone the model_config and inject an OpenAI ``response_format`` with the
-    column's ``output_format`` JSON schema. The column is rewritten to point at
-    the clone so llm-text / llm-judge columns that share the same alias keep
-    free-form sampling.
+    """For each llm-structured column targeting a local-provider model_config,
+    clone the config and inject an OpenAI ``response_format`` with the
+    column's ``output_format`` JSON schema. The column is repointed at the
+    clone so llm-text / llm-judge columns sharing the alias keep free-form
+    sampling.
 
     Without this, data_designer only injects a prompt-level "return JSON in a
-    ```json fence" instruction. Small GGUF models frequently break format,
-    wasting the full ``max_tokens`` budget per row and then failing to parse.
-    Forwarding ``response_format`` lets llama-server apply grammar-constrained
-    sampling from the JSON schema, which guarantees a parseable response and
-    terminates early.
+    ```json fence" instruction. Small GGUFs often break format, wasting the
+    full ``max_tokens`` budget per row and then failing to parse. Forwarding
+    ``response_format`` lets llama-server apply grammar-constrained sampling
+    from the schema, guaranteeing a parseable response and terminating early.
     """
     columns = recipe.get("columns")
     model_configs = recipe.get("model_configs")
@@ -210,8 +209,8 @@ def _inject_local_structured_response_format(
         return
 
     # Clone per (alias, column) so each llm-structured column gets its own
-    # schema without leaking response_format onto other columns that share the
-    # same base alias.
+    # schema without leaking response_format onto other columns sharing the
+    # base alias.
     seen_clone_aliases: set[str] = {
         mc.get("alias") for mc in model_configs if isinstance(mc.get("alias"), str)
     }
@@ -243,15 +242,14 @@ def _inject_local_structured_response_format(
         if not isinstance(params, dict):
             params = {}
             clone["inference_parameters"] = params
-        # data_designer's BaseInferenceParams is a pydantic model with
-        # extra="forbid", so response_format cannot sit at the top level of
-        # inference_parameters. It does expose an `extra_body: dict` pass-
-        # through that the OpenAI client spreads into the request body at the
-        # top level, which is where llama-server reads response_format from.
-        # llama.cpp server shape (tools/server/README.md): the schema sits
-        # directly under response_format, not nested in a json_schema object
-        # the way OpenAI's Chat Completions API expects. llama-server converts
-        # the schema to a GBNF grammar and applies it during sampling.
+        # data_designer's BaseInferenceParams is pydantic extra="forbid", so
+        # response_format cannot sit at the top level of inference_parameters.
+        # Its `extra_body: dict` passthrough is spread into the request body
+        # top level by the OpenAI client, where llama-server reads
+        # response_format. llama.cpp server shape (tools/server/README.md):
+        # the schema sits directly under response_format, not nested in a
+        # json_schema object like OpenAI's Chat Completions API expects.
+        # llama-server converts the schema to a GBNF grammar for sampling.
         extra_body = params.get("extra_body")
         if not isinstance(extra_body, dict):
             extra_body = {}
@@ -269,21 +267,21 @@ def _inject_local_structured_response_format(
 
 def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optional[int]:
     """
-    Mutate recipe dict in-place: for any provider with is_local=True,
-    fill in the endpoint pointing at this server and inject a short-lived
-    internal sk-unsloth-* API key for workflow auth.
+    Mutate recipe dict in-place: for any provider with is_local=True, set
+    the endpoint to this server and inject a short-lived internal
+    sk-unsloth-* API key for workflow auth.
 
-    Returns the row id of the minted internal key (so the caller can
-    revoke it on job completion) or ``None`` when no local provider is
-    actually reachable from an LLM column.
+    Returns the row id of the minted internal key (for the caller to revoke
+    on job completion) or ``None`` when no local provider is reachable from
+    an LLM column.
     """
     providers = recipe.get("model_providers")
     if not providers:
         return None
 
-    # Collect local providers and pop is_local from ALL dicts unconditionally.
-    # Strict `is True` guard so malformed payloads (is_local: 1,
-    # is_local: "true") do not accidentally trigger the loopback rewrite.
+    # Collect local providers and pop is_local from ALL dicts. Strict
+    # `is True` guard so malformed payloads (is_local: 1, is_local: "true")
+    # do not trigger the loopback rewrite.
     local_indices: list[int] = []
     for i, provider in enumerate(providers):
         if not isinstance(provider, dict):
@@ -297,10 +295,10 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
 
     endpoint = _resolve_local_v1_endpoint(request)
 
-    # Only gate on model-loaded if a local provider is actually reachable
-    # from an LLM column through a model_config. Orphan model_config nodes
-    # that reference a local provider but that no LLM column uses should
-    # not block runs; the recipe would never call /v1 for them.
+    # Only gate on model-loaded if a local provider is reachable from an LLM
+    # column via a model_config. Orphan model_config nodes referencing a
+    # local provider that no LLM column uses should not block runs; the
+    # recipe would never call /v1 for them.
     local_names = {providers[i].get("name") for i in local_indices if providers[i].get("name")}
     used_aliases = _used_llm_model_aliases(recipe)
     referenced_providers = {
@@ -313,19 +311,19 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
     internal_key_id: Optional[int] = None
     if local_names & referenced_providers:
         # Verify the selected local model is loaded before minting a workflow
-        # key. This still remains a point-in-time singleton-backend check
-        # (TOCTOU): a future generation token should bind frontend load and
-        # job creation, and the inference endpoint returns a clear 400 if the
-        # model is later unloaded or swapped before the subprocess calls /v1.
+        # key. Still a point-in-time singleton-backend check (TOCTOU): a
+        # future generation token should bind frontend load to job creation;
+        # the inference endpoint returns a clear 400 if the model is unloaded
+        # or swapped before the subprocess calls /v1.
         _ensure_selected_local_model_loaded(recipe, local_names)
 
         from auth import storage  # deferred: avoids circular import
 
-        # Mint an internal sk-unsloth-* key scoped to this workflow run.
-        # Uses the unified API-key issuance path (one mint/revoke/verify
-        # surface instead of a second JWT code path). The key is marked
-        # internal so it is hidden from the user's API-key list, and the
-        # caller revokes it when the job terminates.
+        # Mint an internal sk-unsloth-* key scoped to this workflow run via
+        # the unified API-key issuance path (one mint/revoke/verify surface
+        # instead of a second JWT code path). Marked internal so it is hidden
+        # from the user's API-key list; the caller revokes it when the job
+        # terminates.
         expires_at = (datetime.now(timezone.utc) + timedelta(hours = 24)).isoformat()
         token, row = storage.create_api_key(
             username = "unsloth",
@@ -335,11 +333,11 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
         )
         internal_key_id = int(row["id"])
 
-    # Defensively strip any stale "external"-only fields the frontend may
-    # have left on the dict (extra_headers/extra_body/api_key_env). The UI
-    # hides these inputs in local mode but the payload builder still serializes
-    # them, so a previously external provider that flipped to local can carry
-    # invalid JSON or rogue auth headers into the local /v1 call.
+    # Strip stale "external"-only fields the frontend may have left
+    # (extra_headers/extra_body/api_key_env). The UI hides these in local
+    # mode but the payload builder still serializes them, so a provider
+    # flipped from external to local could carry invalid JSON or rogue auth
+    # headers into the local /v1 call.
     for i in local_indices:
         providers[i]["endpoint"] = endpoint
         providers[i]["api_key"] = token
@@ -348,29 +346,27 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
         providers[i].pop("extra_headers", None)
         providers[i].pop("extra_body", None)
 
-    # Force skip_health_check on any model_config that references a local
-    # provider. The frontend now sends the explicit selected local model id,
-    # but llama-server's /v1/models response can still differ from that id
-    # for local paths, cache aliases, and GGUF variant loads. The recipe run
-    # has already gated on a loaded local inference backend above, so the
-    # data_designer model-list health check would be redundant and can reject
-    # valid local selections.
+    # Force skip_health_check on any model_config referencing a local
+    # provider. The frontend sends the explicit selected local model id, but
+    # llama-server's /v1/models response can differ from it for local paths,
+    # cache aliases, and GGUF variant loads. The run already gated on a
+    # loaded local backend above, so data_designer's model-list health check
+    # would be redundant and can reject valid local selections.
     for mc in recipe.get("model_configs", []):
         if not isinstance(mc, dict):
             continue
         if mc.get("provider") in local_names:
             mc["skip_health_check"] = True
             # Disable thinking for data-recipe inference on local providers.
-            # Reasoning models emit a <think>...</think> preamble before the
-            # answer, which roughly doubles generated token count per row and
-            # pushes the visible answer past data_designer's json-fence
-            # regex. Forward chat_template_kwargs={enable_thinking: False}
-            # through the OpenAI SDK's extra_body passthrough so llama-server
-            # renders the template without the reasoning preamble. Free-form
-            # llm-text columns benefit from the latency cut, and structured
-            # columns also stop leaking think tags into the grammar-
-            # constrained JSON (llama-server's GBNF path still enforces the
-            # schema either way).
+            # Reasoning models emit a <think>...</think> preamble that roughly
+            # doubles generated tokens per row and pushes the answer past
+            # data_designer's json-fence regex. Forward
+            # chat_template_kwargs={enable_thinking: False} via the OpenAI
+            # SDK's extra_body passthrough so llama-server renders the
+            # template without the preamble. llm-text columns get the latency
+            # cut; structured columns stop leaking think tags into the
+            # grammar-constrained JSON (GBNF still enforces the schema either
+            # way).
             params = mc.get("inference_parameters")
             if not isinstance(params, dict):
                 params = {}
@@ -387,7 +383,7 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
 
     # Forward each llm-structured column's output_format as an OpenAI
     # response_format so llama-server uses grammar-constrained sampling and
-    # small GGUFs stop wasting the full max_tokens budget on broken JSON.
+    # small GGUFs stop wasting the max_tokens budget on broken JSON.
     _inject_local_structured_response_format(recipe, local_names)
 
     return internal_key_id
@@ -446,11 +442,11 @@ def create_job(payload: RecipePayload, request: Request):
             log = logger,
         ) from exc
 
-    # Single try block covers get_job_manager() AND mgr.start() so a workflow
-    # key minted above never outlives the request even when an unexpected
+    # Single try covers get_job_manager() AND mgr.start() so a minted
+    # workflow key never outlives the request even on an unexpected
     # exception type (TypeError from a stale kwarg, OSError from a queue
-    # write, etc.) bubbles up. Without the bare except, such exceptions let
-    # the sk-unsloth-* key live until its 24h TTL.
+    # write, etc.). Without the bare except, those would let the
+    # sk-unsloth-* key live until its 24h TTL.
     try:
         mgr = get_job_manager()
         job_id = mgr.start(
@@ -488,7 +484,7 @@ def create_job(payload: RecipePayload, request: Request):
 
 def _revoke_internal_api_key_safe(key_id: int) -> None:
     """Best-effort revoke of a workflow-minted key; swallow any error so
-    that revocation failures never mask the caller's own error path."""
+    revocation failures never mask the caller's own error path."""
     try:
         from auth import storage  # deferred: avoids circular import
         storage.revoke_internal_api_key(key_id)
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index 6368585932..848ed7d557 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -394,7 +394,7 @@ def inspect_seed_dataset(payload: SeedInspectRequest) -> SeedInspectResponse:
 
 
 def _extract_text_from_file(file_path: Path, ext: str) -> str:
-    """Extract text from uploaded file based on extension, converting to markdown where possible."""
+    """Extract text from an uploaded file by extension, to markdown where possible."""
     if ext in {".txt", ".md"}:
         raw = file_path.read_text(encoding = "utf-8", errors = "ignore")
     elif ext == ".pdf":
@@ -581,7 +581,7 @@ def inspect_seed_upload(payload: SeedInspectUploadRequest) -> SeedInspectRespons
     seed_source_type = _normalize_optional_text(payload.seed_source_type) or "local"
     filename = _sanitize_filename(payload.filename)
     ext = Path(filename).suffix.lower()
-    # Legacy single-file unstructured path only supports .txt/.md
+    # Legacy single-file unstructured path supports only .txt/.md;
     # PDF/DOCX extraction uses the multi-file upload endpoint instead
     _LEGACY_UNSTRUCTURED_EXTS = {".txt", ".md"}
     if seed_source_type == "unstructured":
diff --git a/studio/backend/routes/data_recipe/validate.py b/studio/backend/routes/data_recipe/validate.py
index e26093d6bf..732fa902d6 100644
--- a/studio/backend/routes/data_recipe/validate.py
+++ b/studio/backend/routes/data_recipe/validate.py
@@ -121,9 +121,8 @@ def _collect_validation_errors(recipe: dict[str, Any]) -> list[ValidateError]:
 def _patch_local_providers(recipe: dict[str, Any]) -> None:
     """Strip is_local and fill a dummy endpoint so validation doesn't choke.
 
-    Uses a strict `is True` check to match _inject_local_providers in
-    jobs.py - malformed payloads with truthy but non-boolean is_local
-    values should not be treated as local.
+    Strict `is True` check matches _inject_local_providers in jobs.py:
+    truthy but non-boolean is_local values are not treated as local.
     """
     for provider in recipe.get("model_providers", []):
         if not isinstance(provider, dict):
@@ -152,13 +151,12 @@ def validate(payload: RecipePayload) -> ValidateResponse:
             build_config_builder(recipe)
         except ModuleNotFoundError as exc:
             # data_designer is an optional runtime dep. Static validation
-            # already passed; live access + full config validation are
-            # deferred to run start (per _GITHUB_VALIDATE_NOTE), so a missing
-            # optional import at validate time should not block the recipe.
-            # Restrict the bypass to the data_designer module specifically so
-            # other ImportErrors (e.g. broken internal imports or missing
-            # transitive deps after a package upgrade) still surface as
-            # validation failures instead of being silently swallowed.
+            # passed; live access + full config validation are deferred to
+            # run start (per _GITHUB_VALIDATE_NOTE), so a missing optional
+            # import here should not block the recipe. Restrict the bypass to
+            # the data_designer module so other ImportErrors (broken internal
+            # imports, missing transitive deps after an upgrade) still surface
+            # as validation failures instead of being swallowed.
             if not (exc.name or "").startswith("data_designer"):
                 raise
             logger.debug(
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 711e9723d5..1bf035b684 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -45,9 +45,9 @@ def _get_dataset_size_cached(repo_id: str) -> int:
 def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
     """Pick the most useful on-disk path for a HF cache repo dir.
 
-    Mirrors the helper in routes/models.py: prefer the most-recent
-    snapshot dir, fall back to the cache repo root, return resolved
-    realpath. Duplicated here to keep routes/datasets.py self-contained.
+    Mirrors routes/models.py: prefer the most-recent snapshot dir, else the
+    cache repo root, returned as a resolved realpath. Duplicated here to keep
+    routes/datasets.py self-contained.
     """
     try:
         snapshots_dir = repo_dir / "snapshots"
@@ -61,12 +61,12 @@ def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
         return None
 
 
-# Add backend directory to path
+# Add backend directory to path.
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Import dataset utilities
+# Import dataset utilities.
 from utils.datasets import check_dataset_format
 from utils.upload_limits import get_upload_limit_bytes, get_upload_limit_label
 from auth.authentication import get_current_subject
@@ -93,7 +93,7 @@ from utils.paths import (
 
 
 def _serialize_preview_value(value):
-    """make it json safe for client preview ⊂(◉‿◉)つ"""
+    """Make a value JSON-safe for the client preview."""
     if value is None or isinstance(value, (str, int, float, bool)):
         return value
 
@@ -130,10 +130,10 @@ def _serialize_preview_rows(rows):
 
 # --- Endpoints ---
 
-# Recognized data-file extensions for the single-file fallback approach.
-# Tabular formats are preferred over archives for Tier 1 preview because
-# archives (e.g. images.zip) may be loaded as ImageFolder datasets with
-# synthetic columns (image/label) that don't match the real dataset schema.
+# Recognized data-file extensions for the single-file fallback.
+# Tier 1 preview prefers tabular over archives: archives (e.g. images.zip) can
+# load as ImageFolder datasets with synthetic image/label columns that don't
+# match the real schema.
 _TABULAR_EXTS = (".parquet", ".json", ".jsonl", ".csv", ".tsv", ".arrow")
 _ARCHIVE_EXTS = (".tar", ".tar.gz", ".tgz", ".gz", ".zst", ".zip", ".txt")
 DATA_EXTS = _TABULAR_EXTS + _ARCHIVE_EXTS
@@ -331,9 +331,9 @@ async def upload_dataset(
     stored_name = f"{uuid4().hex}_{stem}{ext}"
     stored_path = DATASET_UPLOAD_DIR / stored_name
 
-    # Stream file to disk in chunks to avoid holding entire file in memory.
-    # Keep a route-level cap so users get a clear training-dataset-specific
-    # error and oversized partial files are not left in the Studio uploads directory.
+    # Stream to disk in chunks to avoid holding the whole file in memory. The
+    # route-level cap gives a clear training-dataset error and avoids leaving
+    # oversized partial files in the Studio uploads directory.
     upload_limit_bytes = get_upload_limit_bytes()
     total_bytes = 0
     upload_complete = False
@@ -378,12 +378,10 @@ async def get_dataset_download_progress(
     """Return download progress for a HuggingFace dataset repo.
 
     Mirrors ``GET /api/models/download-progress`` but scans the
-    ``datasets--owner--name`` cache directory under HF_HUB_CACHE.
-    Modern ``datasets``/``huggingface_hub`` caches both raw model and
-    raw dataset blobs in HF_HUB_CACHE; the ``datasets`` library writes
-    its processed Arrow shards elsewhere, but the in-progress *download*
-    bytes are observable here. Returns ``cache_path`` so the UI can
-    show users where the dataset blobs landed on disk.
+    ``datasets--owner--name`` cache directory under HF_HUB_CACHE. Modern
+    ``datasets``/``huggingface_hub`` cache raw dataset blobs there (processed
+    Arrow shards live elsewhere, but in-progress *download* bytes are visible
+    here). Returns ``cache_path`` so the UI can show where blobs landed.
     """
     _empty = {
         "downloaded_bytes": 0,
@@ -433,9 +431,9 @@ async def get_dataset_download_progress(
                 "cache_path": cache_path,
             }
 
-        # Same 95% completion threshold as the model endpoint -- HF blob
-        # dedup makes completed_bytes drift slightly under expected_bytes,
-        # and inter-file gaps would otherwise look like "done".
+        # Same 95% completion threshold as the model endpoint -- HF blob dedup
+        # makes completed_bytes drift slightly under expected_bytes, and
+        # inter-file gaps would otherwise look "done".
         if completed_bytes >= expected_bytes * 0.95:
             progress = 1.0
         else:
@@ -456,15 +454,13 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
     """
     Check if a dataset requires manual column mapping.
 
-    Strategy for HuggingFace datasets:
-      1. list_repo_files → pick the first data file → load_dataset(data_files=[…])
+    HuggingFace strategy:
+      1. list_repo_files → first data file → load_dataset(data_files=[…]).
          Avoids resolving thousands of files; typically ~2-4 s.
       2. Full streaming load_dataset as a last-resort fallback.
 
-    Local files are loaded directly.
-
-    Using a plain `def` (not async) so FastAPI runs this in a thread-pool,
-    preventing any blocking IO from freezing the event loop.
+    Local files load directly. Plain `def` (not async) so FastAPI runs it in a
+    thread-pool, keeping blocking IO off the event loop.
     """
     try:
         from itertools import islice
@@ -502,14 +498,14 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                 )
                 data_files = [f for f in repo_files if any(f.endswith(ext) for ext in DATA_EXTS)]
 
-                # Prefer tabular formats over archives (e.g. images.zip → ImageFolder
-                # with synthetic image/label columns that don't match the real schema).
+                # Prefer tabular over archives (e.g. images.zip → ImageFolder
+                # with synthetic image/label columns not in the real schema).
                 tabular_files = [
                     f for f in data_files if any(f.endswith(ext) for ext in _TABULAR_EXTS)
                 ]
                 candidates = tabular_files or data_files
 
-                # When a subset is specified, narrow to files whose name matches
+                # With a subset, narrow to files whose name matches
                 # (e.g. subset="testmini" → prefer "testmini.parquet").
                 if request.subset and candidates:
                     subset_matches = [f for f in candidates if request.subset in Path(f).stem]
@@ -560,26 +556,26 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                 preview_slice = Dataset.from_list(rows)
             total_rows = None
 
-        # Run lightweight format check on the preview slice
+        # Lightweight format check on the preview slice.
         result = check_dataset_format(preview_slice, is_vlm = request.is_vlm)
 
         logger.info(
             f"Format check result: requires_mapping={result['requires_manual_mapping']}, format={result['detected_format']}, is_image={result.get('is_image', False)}"
         )
 
-        # Generate preview samples
+        # Generate preview samples.
         preview_samples = None
         if not result["requires_manual_mapping"]:
             if result.get("suggested_mapping"):
                 # Heuristic-detected: show raw data so columns match the API response.
-                # Processing (column stripping) happens at training time, not preview.
+                # Column stripping happens at training time, not preview.
                 preview_samples = _serialize_preview_rows(preview_slice)
             else:
                 try:
                     format_result = format_dataset(
                         preview_slice,
                         format_type = "auto",
-                        num_proc = None,  # Only 10 preview rows -- no need for multiprocessing
+                        num_proc = None,  # Only 10 preview rows -- no multiprocessing needed
                     )
                     processed = format_result["dataset"]
                     preview_samples = _serialize_preview_rows(processed)
@@ -589,7 +585,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
         else:
             preview_samples = _serialize_preview_rows(preview_slice)
 
-        # Collect warnings: from check_dataset_format + URL-based image detection
+        # Collect warnings from check_dataset_format + URL-based image detection.
         warning = result.get("warning")
         image_col = result.get("detected_image_column")
         if image_col and image_col in (result.get("columns") or []):
@@ -636,17 +632,17 @@ def ai_assist_mapping(
     """
     Run LLM-assisted dataset conversion advisor (user-triggered).
 
-    Multi-pass analysis using a 7B helper model:
-      Pass 1: Classify dataset type from HF card + samples
-      Pass 2: Generate conversion strategy (system prompt, templates)
-      Pass 3: Validate conversion quality
+    Multi-pass analysis with a 7B helper model:
+      Pass 1: Classify dataset type from HF card + samples.
+      Pass 2: Generate conversion strategy (system prompt, templates).
+      Pass 3: Validate conversion quality.
 
     Falls back to simple column classification if the advisor fails.
     """
     try:
         from utils.datasets.llm_assist import llm_conversion_advisor
 
-        # Truncate sample values for the LLM prompt
+        # Truncate sample values for the LLM prompt.
         truncated = [
             {col: str(s.get(col, ""))[:200] for col in request.columns} for s in request.samples[:5]
         ]
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index 302d534874..d687a22f8e 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Export API routes: checkpoint discovery and model export operations.
-"""
+"""Export API routes: checkpoint discovery and model export operations."""
 
 import asyncio
 import json
@@ -28,7 +26,7 @@ from auth.authentication import get_current_subject
 
 from utils.utils import safe_error_detail
 
-# Import backend functions
+# Backend functions
 try:
     from core.export import get_export_backend
 except ImportError:
@@ -37,7 +35,7 @@ except ImportError:
         sys.path.insert(0, str(parent_backend))
     from core.export import get_export_backend
 
-# Import Pydantic models
+# Pydantic models
 from models import (
     LoadCheckpointRequest,
     ExportStatusResponse,
@@ -56,16 +54,12 @@ logger = get_logger(__name__)
 async def load_checkpoint(
     request: LoadCheckpointRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Load a checkpoint into the export backend.
-
-    Wraps ExportBackend.load_checkpoint.
-    """
+    """Load a checkpoint into the export backend (ExportBackend.load_checkpoint)."""
     try:
-        # Version switching is handled automatically by the subprocess-based
-        # export backend — no need for ensure_transformers_version() here.
+        # The subprocess-based export backend handles version switching
+        # automatically — no ensure_transformers_version() needed here.
 
-        # Free GPU memory: shut down any running inference/training subprocesses
+        # Free GPU memory: shut down running inference/training subprocesses
         # before loading the export checkpoint (they'd compete for VRAM).
         try:
             from core.inference import get_inference_backend
@@ -87,8 +81,8 @@ async def load_checkpoint(
             if trn.is_training_active():
                 logger.info("Stopping active training to free GPU memory for export")
                 trn.stop_training()
-                # Wait for training subprocess to actually exit before proceeding,
-                # otherwise it may still hold GPU memory when export tries to load.
+                # Wait for the training subprocess to exit; else it may still
+                # hold GPU memory when export tries to load.
                 for _ in range(60):  # up to 30s
                     if not trn.is_training_active():
                         break
@@ -101,8 +95,8 @@ async def load_checkpoint(
 
         backend = get_export_backend()
         # load_checkpoint spawns and waits on a subprocess and can take
-        # minutes. Run it in a worker thread so the event loop stays
-        # free to serve the live log SSE stream concurrently.
+        # minutes. Run it in a worker thread so the event loop stays free
+        # to serve the live log SSE stream concurrently.
         success, message = await asyncio.to_thread(
             backend.load_checkpoint,
             checkpoint_path = request.checkpoint_path,
@@ -127,11 +121,7 @@ async def load_checkpoint(
 
 @router.post("/cleanup", response_model = ExportOperationResponse)
 async def cleanup_export_memory(current_subject: str = Depends(get_current_subject)):
-    """
-    Cleanup export-related models from memory (GPU/CPU).
-
-    Wraps ExportBackend.cleanup_memory.
-    """
+    """Cleanup export-related models from memory (ExportBackend.cleanup_memory)."""
     try:
         backend = get_export_backend()
         success = await asyncio.to_thread(backend.cleanup_memory)
@@ -158,9 +148,7 @@ async def cleanup_export_memory(current_subject: str = Depends(get_current_subje
 
 @router.get("/status", response_model = ExportStatusResponse)
 async def get_export_status(current_subject: str = Depends(get_current_subject)):
-    """
-    Get current export backend status (loaded checkpoint, model type, PEFT flag).
-    """
+    """Get export backend status (loaded checkpoint, model type, PEFT flag)."""
     try:
         backend = get_export_backend()
         return ExportStatusResponse(
@@ -177,7 +165,7 @@ async def get_export_status(current_subject: str = Depends(get_current_subject))
 
 
 def _export_details(output_path: Optional[str]) -> Optional[Dict[str, Any]]:
-    """Return the export path relative to exports_root so the install path is not leaked."""
+    """Return the export path relative to exports_root, hiding the install path."""
     if not output_path:
         return None
     try:
@@ -195,8 +183,7 @@ def _export_details(output_path: Optional[str]) -> Optional[Dict[str, Any]]:
 async def export_merged_model(
     request: ExportMergedModelRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Export a merged PEFT model (e.g., 16-bit or 4-bit) and optionally push to Hub.
+    """Export a merged PEFT model (16-bit or 4-bit), optionally pushing to Hub.
 
     Wraps ExportBackend.export_merged_model.
     """
@@ -234,8 +221,7 @@ async def export_merged_model(
 async def export_base_model(
     request: ExportBaseModelRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Export a non-PEFT base model and optionally push to Hub.
+    """Export a non-PEFT base model, optionally pushing to Hub.
 
     Wraps ExportBackend.export_base_model.
     """
@@ -273,8 +259,7 @@ async def export_base_model(
 async def export_gguf(
     request: ExportGGUFRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Export the current model to GGUF format and optionally push to Hub.
+    """Export the current model to GGUF format, optionally pushing to Hub.
 
     Wraps ExportBackend.export_gguf.
     """
@@ -311,8 +296,7 @@ async def export_gguf(
 async def export_lora_adapter(
     request: ExportLoRAAdapterRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Export only the LoRA adapter (if the loaded model is PEFT).
+    """Export only the LoRA adapter (if the loaded model is PEFT).
 
     Wraps ExportBackend.export_lora_adapter.
     """
@@ -349,18 +333,18 @@ async def export_lora_adapter(
 # Live export log stream (Server-Sent Events)
 # ─────────────────────────────────────────────────────────────────────
 #
-# The export worker subprocess redirects its stdout/stderr into a pipe
-# that a reader thread forwards to the orchestrator as log entries (see
+# The export worker subprocess redirects its stdout/stderr into a pipe a
+# reader thread forwards to the orchestrator as log entries (see
 # core/export/worker.py::_setup_log_capture and
-# core/export/orchestrator.py::_append_log). This endpoint streams
-# those entries to the browser so the export dialog can show a live
-# terminal-style output panel while load_checkpoint / export_merged /
-# export_gguf / export_lora / export_base run.
+# core/export/orchestrator.py::_append_log). This endpoint streams those
+# entries to the browser so the export dialog shows a live terminal-style
+# panel while load_checkpoint / export_merged / export_gguf / export_lora /
+# export_base run.
 #
 # Shape follows the training progress SSE endpoint
-# (routes/training.py::stream_training_progress): each event carries
-# `id`, `event`, and `data` fields, the stream starts with a `retry:`
-# directive, and `Last-Event-ID` is honored on reconnect.
+# (routes/training.py::stream_training_progress): each event carries `id`,
+# `event`, `data` fields, the stream starts with a `retry:` directive, and
+# `Last-Event-ID` is honored on reconnect.
 
 
 def _format_sse(
@@ -389,28 +373,26 @@ async def stream_export_logs(
     current_subject: str = Depends(get_current_subject),
 ):
     """
-    Stream live stdout/stderr output from the export worker subprocess
-    as Server-Sent Events.
+    Stream live stdout/stderr from the export worker subprocess as
+    Server-Sent Events.
 
     Events:
       - `log`      : a single log line (data: {"stream","line","ts"})
       - `heartbeat`: periodic keepalive when no new lines are available
-      - `complete` : emitted once the export worker is idle and no new
-                     lines arrived for ~1 second. Clients should close.
+      - `complete` : once the worker is idle and no new lines arrived for
+                     ~1 second. Clients should close.
       - `error`    : unrecoverable server-side error
 
-    The `id:` field on each event is the log entry's monotonic seq
-    number so the browser can resume via `Last-Event-ID` on reconnect.
+    Each event's `id:` field is the log entry's monotonic seq number so the
+    browser can resume via `Last-Event-ID` on reconnect.
     """
     backend = get_export_backend()
 
-    # Determine starting cursor. Explicit `since` wins, then
-    # Last-Event-ID header on reconnect, otherwise start from the
-    # run-start snapshot captured by clear_logs() so the client sees
-    # every line emitted since the current run began -- even if the
-    # SSE connection opened after the POST that kicked off the export.
-    # Using get_current_log_seq() here would lose the early bootstrap
-    # lines that arrive in the gap between POST and SSE connect.
+    # Starting cursor: explicit `since` wins, then Last-Event-ID header on
+    # reconnect, else the run-start snapshot from clear_logs() so the client
+    # sees every line since the run began -- even if the SSE connection
+    # opened after the POST that kicked off the export. get_current_log_seq()
+    # would lose the early bootstrap lines arriving between POST and connect.
     last_event_id = request.headers.get("last-event-id")
     if since is None and last_event_id is not None:
         try:
@@ -425,8 +407,7 @@ async def stream_export_logs(
 
     async def event_generator() -> AsyncGenerator[str, None]:
         nonlocal cursor
-        # Tell the browser to reconnect after 3 seconds if the
-        # connection drops mid-export.
+        # Reconnect after 3 seconds if the connection drops mid-export.
         yield "retry: 3000\n\n"
 
         last_yield = time.monotonic()
@@ -460,9 +441,8 @@ async def stream_export_logs(
                         yield _format_sse("{}", event = "heartbeat")
                         last_yield = now
                     if not backend.is_export_active():
-                        # Give the reader thread a moment to drain any
-                        # trailing lines the worker process printed
-                        # just before signalling done.
+                        # Give the reader thread a moment to drain trailing
+                        # lines the worker printed just before signalling done.
                         if idle_since is None:
                             idle_since = now
                         elif now - idle_since > 1.0:
@@ -477,8 +457,8 @@ async def stream_export_logs(
 
                 await asyncio.sleep(0.1)
         except asyncio.CancelledError:
-            # Client disconnected mid-yield. Don't re-raise, just end
-            # the generator cleanly so StreamingResponse finalizes.
+            # Client disconnected mid-yield. Don't re-raise; end the
+            # generator cleanly so StreamingResponse finalizes.
             return
         except Exception as exc:
             logger.error("Export log stream failed: %s", exc, exc_info = True)
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 70a9aa27d0..86b4251d15 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -30,31 +30,27 @@ from utils.models import extract_model_size_b as _extract_model_size_b
 def _install_httpcore_asyncgen_silencer() -> None:
     """Silence benign httpx/httpcore asyncgen GC noise on Python 3.13.
 
-    When Studio proxies a streaming response from llama-server via httpx,
-    the innermost ``HTTP11ConnectionByteStream.__aiter__`` async generator
-    is finalised by Python's asyncgen GC hook on a task different from the
-    one that opened it. Its ``aclose`` path then calls
-    ``anyio.Lock.acquire`` → ``cancel_shielded_checkpoint`` which enters a
-    ``CancelScope`` on the finaliser task — Python 3.13 flags the
-    cross-task exit as ``"Attempted to exit cancel scope in a different
-    task"`` and prints ``"async generator ignored GeneratorExit"`` as an
-    unraisable warning.
+    When Studio proxies a llama-server stream via httpx, the innermost
+    ``HTTP11ConnectionByteStream.__aiter__`` async generator is finalised by
+    the asyncgen GC hook on a task different from the one that opened it. Its
+    ``aclose`` calls ``anyio.Lock.acquire`` → ``cancel_shielded_checkpoint``,
+    entering a ``CancelScope`` on the finaliser task; Python 3.13 flags the
+    cross-task exit as ``"Attempted to exit cancel scope in a different task"``
+    and prints ``"async generator ignored GeneratorExit"`` as an unraisable
+    warning.
 
-    This is a known httpx + httpcore + anyio interaction (see MCP SDK
-    python-sdk#831, agno #3556, chainlit #2361, langchain-mcp-adapters
-    #254). It is benign: the response has already been delivered with a
-    200. The streaming pass-throughs (``/v1/chat/completions``,
-    ``/v1/messages``, ``/v1/responses``, ``/v1/completions``) already
-    manage their httpx lifecycle inside a single task with explicit
-    ``aclose()`` of the lines iterator, response, and client; the errant
-    generator is not one we hold a reference to and therefore cannot
-    close ourselves.
+    Known httpx + httpcore + anyio interaction (MCP SDK python-sdk#831, agno
+    #3556, chainlit #2361, langchain-mcp-adapters #254). Benign: the 200
+    response is already delivered. The streaming pass-throughs
+    (``/v1/chat/completions``, ``/v1/messages``, ``/v1/responses``,
+    ``/v1/completions``) manage their httpx lifecycle in one task with explicit
+    ``aclose()``; we don't hold a reference to the errant generator and can't
+    close it ourselves.
 
-    We install a single process-wide unraisable hook that swallows just
-    this specific interaction — identified by the tuple of (RuntimeError
-    mentioning cancel scope / GeneratorExit) + (object repr referencing
-    HTTP11ConnectionByteStream) — and defers to the default hook for
-    everything else. The filter is idempotent.
+    Install one process-wide unraisable hook that swallows only this
+    interaction -- identified by (RuntimeError mentioning cancel scope /
+    GeneratorExit) + (object repr referencing HTTP11ConnectionByteStream) --
+    and defers to the default hook otherwise. Idempotent.
     """
     prior_hook = sys.unraisablehook
     if getattr(prior_hook, "_unsloth_httpcore_silencer", False):
@@ -85,12 +81,10 @@ _install_httpcore_asyncgen_silencer()
 
 def _friendly_error(exc: Exception) -> str:
     """Extract a user-friendly message from known llama-server errors."""
-    # httpx transport-layer failures reaching the managed llama-server —
-    # raised by the async pass-through helpers that talk to llama-server
-    # directly. Treat any RequestError subclass (ConnectError, ReadError,
-    # RemoteProtocolError, WriteError, PoolTimeout, ...) as "the upstream
-    # subprocess is unreachable", which for Studio always means the
-    # llama-server subprocess crashed or is still coming up.
+    # httpx transport failures from the async pass-through helpers. Any
+    # RequestError subclass (ConnectError, ReadError, RemoteProtocolError,
+    # WriteError, PoolTimeout, ...) means the llama-server subprocess is
+    # unreachable -- crashed or still coming up.
     if isinstance(exc, httpx.RequestError):
         return (
             "Lost connection to the model server. It may have crashed -- try reloading the model."
@@ -372,10 +366,9 @@ async def artifact_preview_frame(
 
 
 def _detect_safetensors_features(backend, chat_template: Optional[str]) -> dict:
-    """Classify reasoning/tool capabilities via the GGUF classifier so
-    flags match across backends. gpt-oss is overridden because Harmony
-    routes reasoning and tools through tokenizer channels, not template
-    markup."""
+    """Classify reasoning/tool capabilities via the GGUF classifier so flags
+    match across backends. gpt-oss is overridden: Harmony routes reasoning and
+    tools through tokenizer channels, not template markup."""
     model_id = getattr(backend, "active_model_name", None)
     flags = (
         detect_reasoning_flags(
@@ -392,11 +385,11 @@ def _detect_safetensors_features(backend, chat_template: Optional[str]) -> dict:
             "supports_tools": False,
         }
     )
-    # Our safetensors loop only parses <tool_call>{json}</tool_call>
-    # and <function=name>...</function>. Llama uses <|python_tag|>,
-    # Mistral uses [TOOL_CALLS]; advertising tools for those would
-    # enable a pill the parser cannot honour. GGUF is unaffected --
-    # llama-server normalises every format into structured deltas.
+    # Our safetensors loop only parses <tool_call>{json}</tool_call> and
+    # <function=name>...</function>. Llama uses <|python_tag|>, Mistral uses
+    # [TOOL_CALLS]; advertising tools for those enables a pill the parser
+    # can't honour. GGUF is unaffected -- llama-server normalises every
+    # format into structured deltas.
     if (
         flags.get("supports_tools")
         and chat_template
@@ -410,7 +403,7 @@ def _detect_safetensors_features(backend, chat_template: Optional[str]) -> dict:
         )
         flags["supports_tools"] = False
 
-    # gpt-oss: keep reasoning on, drop tools (Harmony channel, not
+    # gpt-oss: keep reasoning on, drop tools (Harmony channel, not the
     # <tool_call> XML this loop parses).
     try:
         if hasattr(backend, "_is_gpt_oss_model") and backend._is_gpt_oss_model():
@@ -426,7 +419,7 @@ def _effective_enable_tools(payload) -> Optional[bool]:
     """Resolve `payload.enable_tools` against the process-level tool policy.
 
     Returns the policy value when set (CLI hard-override from `unsloth run`),
-    otherwise the per-request value.
+    else the per-request value.
     """
     from state.tool_policy import get_tool_policy
 
@@ -434,15 +427,15 @@ def _effective_enable_tools(payload) -> Optional[bool]:
     return policy if policy is not None else payload.enable_tools
 
 
-# Cancel registry. Proxies (e.g. Colab) can swallow client fetch aborts
-# so is_disconnected() never fires. POST /inference/cancel looks up
-# in-flight cancel_events here by cancel_id (per-run) or session_id /
-# completion_id (fallbacks).
+# Cancel registry. Proxies (e.g. Colab) can swallow client fetch aborts so
+# is_disconnected() never fires. POST /inference/cancel looks up in-flight
+# cancel_events here by cancel_id (per-run) or session_id / completion_id
+# (fallbacks).
 _CANCEL_REGISTRY: dict[str, set[threading.Event]] = {}
 _CANCEL_LOCK = threading.Lock()
 
-# Cancel POSTs that arrive before registration are stashed; the next
-# matching __enter__ replays set() within the TTL.
+# Cancel POSTs arriving before registration are stashed; the next matching
+# __enter__ replays set() within the TTL.
 _PENDING_CANCELS: dict[str, float] = {}
 _PENDING_CANCEL_TTL_S = 30.0
 
@@ -460,8 +453,8 @@ class _TrackedCancel:
         self.keys = tuple(k for k in keys if k)
 
     def __enter__(self):
-        # Register + consume-pending must be one critical section to close
-        # the TOCTOU race against a concurrent cancel POST.
+        # Register + consume-pending in one critical section to close the
+        # TOCTOU race against a concurrent cancel POST.
         should_cancel = False
         with _CANCEL_LOCK:
             for k in self.keys:
@@ -489,9 +482,9 @@ class _TrackedCancel:
 
 def _cancel_by_keys(keys) -> int:
     """Set cancel_event for matching registry entries; no stash.
-    session_id/completion_id are shared across runs on the same thread,
-    so stashing them would ghost-cancel the user's next request. Only
-    cancel_id is per-run unique (see _cancel_by_cancel_id_or_stash)."""
+    session_id/completion_id are shared across runs on the same thread, so
+    stashing them would ghost-cancel the user's next request. Only cancel_id
+    is per-run unique (see _cancel_by_cancel_id_or_stash)."""
     if not keys:
         return 0
     events: set[threading.Event] = set()
@@ -526,17 +519,15 @@ def _cancel_by_cancel_id_or_stash(cancel_id: str) -> int:
 async def _await_cancel_then_close(cancel_event, resp) -> None:
     """Watch a threading.Event from asyncio and close ``resp`` when it fires.
 
-    Used by the passthrough streamers so a /cancel POST can interrupt
-    while the async iterator is blocked waiting for llama-server prefill.
-    Without this watcher the in-loop ``cancel_event.is_set()`` check is
-    unreachable until the first SSE chunk arrives, which is exactly the
-    proxy/Colab scenario the cancel POST exists to handle.
+    Used by passthrough streamers so a /cancel POST can interrupt while the
+    async iterator is blocked on llama-server prefill. Without it the in-loop
+    ``cancel_event.is_set()`` check is unreachable until the first SSE chunk
+    arrives -- exactly the proxy/Colab case the cancel POST exists for.
 
-    Polls a threading.Event because the cancel registry is keyed by
-    threading.Event so the synchronous /cancel handler can call .set().
-    50ms cadence adds at most that much latency to a prefill cancel; the
-    common-case streaming cancel path still observes the event in the
-    iterator's first iteration after the next chunk.
+    Polls a threading.Event since the cancel registry is keyed by
+    threading.Event (so the sync /cancel handler can call .set()). The 50ms
+    cadence adds at most that latency to a prefill cancel; the common
+    streaming-cancel path still sees the event on the iterator's next chunk.
     """
     try:
         while not cancel_event.is_set():
@@ -550,9 +541,9 @@ async def _await_cancel_then_close(cancel_event, resp) -> None:
 
 
 # Appended to tool-use nudge to discourage plan-without-action.
-# Keep render_html guidance gated to turns where the artifact tool is actually
-# present in the tool schema; otherwise small local models can hallucinate a
-# missing tool call instead of following the fenced-HTML fallback prompt.
+# Gate render_html guidance to turns where the artifact tool is in the schema;
+# otherwise small local models hallucinate a missing tool call instead of the
+# fenced-HTML fallback prompt.
 _TOOL_ACTION_NUDGE = (
     " IMPORTANT: Always call tools directly -- never write code yourself."
     " Never describe what you plan to do -- just call the tool immediately."
@@ -581,7 +572,7 @@ def _tool_action_nudge(has_artifact: bool) -> str:
 #      `\Z` so mid-text `<parameter>` in user code samples survives.
 _TOOL_XML_RE = _re.compile(
     # Hyphen in the name char-class matches MCP tool names with dashes
-    # (mcp__srv__list-issues) which would otherwise leak past this strip.
+    # (mcp__srv__list-issues) that would otherwise leak past this strip.
     r"<(?:tool_call|function=[\w-]+)>.*?(?:</(?:tool_call|function)>|\Z)"
     r"|</(?:tool_call|function)>"
     r"|</parameter>\s*\Z",
@@ -633,19 +624,19 @@ def _normalise_settings_str(value: Optional[str]) -> Optional[str]:
 
 
 def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaCppBackend) -> bool:
-    """True iff every runtime setting on the request matches the loaded
-    server. Caller has already checked model+variant+is_loaded. See #5401."""
-    # Compare requested n_ctx (not effective) so VRAM-cap doesn't mask
-    # an Auto-vs-explicit slider flip.
+    """True iff every runtime setting on the request matches the loaded server.
+    Caller has already checked model+variant+is_loaded. See #5401."""
+    # Compare requested n_ctx (not effective) so VRAM-cap doesn't mask an
+    # Auto-vs-explicit slider flip.
     if request.max_seq_length != llama_backend.requested_n_ctx:
         return False
     if _normalise_settings_str(request.cache_type_kv) != _normalise_settings_str(
         llama_backend.cache_type_kv
     ):
         return False
-    # Vision loads silently drop speculative decoding (llama_cpp.py gates
-    # spec on ``not is_vision``), so treat the request as ``off`` against
-    # the backend's ``None`` to avoid forcing a redundant reload.
+    # Vision loads silently drop speculative decoding (llama_cpp.py gates spec
+    # on ``not is_vision``), so treat the request as ``off`` against the
+    # backend's ``None`` to avoid a redundant reload.
     if llama_backend.is_vision:
         req_mode = "off"
     else:
@@ -653,17 +644,17 @@ def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaC
     backend_mode = llama_backend.requested_spec_mode or "auto"
     if req_mode != backend_mode:
         return False
-    # spec_draft_n_max only matters when an MTP variant is engaged; None
-    # means "platform default" and matches whatever the backend chose.
+    # spec_draft_n_max only matters with an MTP variant; None means "platform
+    # default" and matches whatever the backend chose.
     if backend_mode in ("mtp", "mtp+ngram") and request.spec_draft_n_max is not None:
         if int(request.spec_draft_n_max) != (llama_backend.spec_draft_n_max or 0):
             return False
     if (request.chat_template_override or None) != (llama_backend.chat_template_override or None):
         return False
-    # llama_extra_args=None means "inherit"; only an explicit list that
-    # differs forces a reload. On the inherit path, refuse to match if
-    # stored extras contain any shadow flag, so the reload path can
-    # strip them instead of leaving a stale override in effect.
+    # llama_extra_args=None means "inherit"; only an explicit differing list
+    # forces a reload. On the inherit path, refuse to match if stored extras
+    # contain any shadow flag, so the reload path strips them rather than
+    # leaving a stale override in effect.
     backend_extra = list(llama_backend.extra_args) if llama_backend.extra_args else []
     if request.llama_extra_args is None:
         if backend_extra and strip_shadowing_flags(backend_extra) != backend_extra:
@@ -716,17 +707,17 @@ async def load_model(
     """
     Load a model for inference.
 
-    The model_path should be a clean identifier from GET /models/list.
-    Returns inference configuration parameters (temperature, top_p, top_k, min_p)
-    from the model's YAML config, falling back to default.yaml for missing values.
+    model_path is a clean identifier from GET /models/list. Returns inference
+    config (temperature, top_p, top_k, min_p) from the model's YAML, falling
+    back to default.yaml for missing values.
 
-    GGUF models are loaded via llama-server (llama.cpp) instead of Unsloth.
+    GGUF models load via llama-server (llama.cpp) instead of Unsloth.
     """
     native_grant_backed = False
     model_log_label = request.model_path
     try:
-        # Validate user-supplied llama-server pass-through args up front
-        # so a managed-flag collision returns 400 before any model work.
+        # Validate user pass-through args up front so a managed-flag collision
+        # returns 400 before any model work.
         try:
             extra_llama_args = validate_extra_args(request.llama_extra_args)
         except ValueError as exc:
@@ -736,8 +727,8 @@ async def load_model(
                 status_code = 400,
                 detail = redact_native_paths(str(exc)),
             )
-        # Re-narrow []-from-None back to None so the inheritance path
-        # below can tell "caller omitted" from "caller explicit []".
+        # Re-narrow []-from-None back to None so the inheritance path below can
+        # tell "caller omitted" from "caller explicit []".
         extra_llama_args: Optional[list[str]] = (
             None if request.llama_extra_args is None else extra_llama_args
         )
@@ -745,8 +736,8 @@ async def load_model(
         model_identifier, model_log_label, native_grant_backed = (
             _resolve_model_identifier_for_request(request, operation = "load-model")
         )
-        # Version switching is handled automatically by the subprocess-based
-        # inference backend — no need for ensure_transformers_version() here.
+        # Version switching is handled by the subprocess-based inference
+        # backend -- no ensure_transformers_version() needed here.
 
         # ── Already-loaded check: skip reload if the exact model is active ──
         backend = get_inference_backend()
@@ -764,7 +755,7 @@ async def load_model(
                 and gguf_variant_matches
                 and llama_backend.model_identifier
                 and llama_backend.model_identifier.lower() == model_identifier.lower()
-                # Match runtime settings too so Apply isn't dropped (#5401).
+                # Match runtime settings so Apply isn't dropped (#5401).
                 and _request_matches_loaded_settings(request, llama_backend)
                 # Skip if a prior audio probe failed -- let load_model retry.
                 and getattr(llama_backend, "_audio_probed", True)
@@ -854,8 +845,8 @@ async def load_model(
                 )
 
         # is_lora auto-detected from adapter_config.json on disk/HF.
-        # DNS-probe wrap so offline loads skip 30-60s of soft-failed
-        # network checks before the worker starts.
+        # DNS-probe wrap so offline loads skip 30-60s of soft-failed network
+        # checks before the worker starts.
         with _hf_offline_if_dns_dead():
             config = ModelConfig.from_identifier(
                 model_id = model_identifier,
@@ -883,28 +874,26 @@ async def load_model(
             llama_backend = get_llama_cpp_backend()
             unsloth_backend = get_inference_backend()
 
-            # Unload any active Unsloth model first to free VRAM
+            # Unload any active Unsloth model to free VRAM
             if unsloth_backend.active_model_name:
                 logger.info(
                     f"Unloading Unsloth model '{unsloth_backend.active_model_name}' before loading GGUF"
                 )
                 unsloth_backend.unload_model(unsloth_backend.active_model_name)
 
-            # Inherit llama_extra_args from the previous load when the
-            # request omits the field (the chat-settings Apply path
-            # does not round-trip them; explicit [] still clears).
-            # Inheritance is gated on (model_identifier, hf_variant)
-            # to refuse cross-model pickup, and shadowing flags are
-            # stripped so an inherited override can't win the last-wins
-            # CLI parse against a freshly-supplied first-class field.
+            # Inherit llama_extra_args from the previous load when the request
+            # omits the field (the chat-settings Apply path doesn't round-trip
+            # them; explicit [] still clears). Gated on (model_identifier,
+            # hf_variant) to refuse cross-model pickup, and shadowing flags are
+            # stripped so an inherited override can't win the last-wins CLI
+            # parse against a freshly-supplied first-class field.
             if request.llama_extra_args is None and llama_backend.extra_args:
                 source = llama_backend.extra_args_source
-                # Compare against the resolved variant, not the request
-                # field: callers commonly omit gguf_variant for local
-                # ``.gguf`` paths and HF auto-pick flows. ``config.gguf_
-                # variant`` is the variant load_model was actually
-                # invoked with (see the HF / local branches below), so
-                # both sides of the comparison key off the same string.
+                # Compare against the resolved variant, not the request field:
+                # callers commonly omit gguf_variant for local ``.gguf`` paths
+                # and HF auto-pick flows. ``config.gguf_variant`` is the variant
+                # load_model was actually invoked with (see HF / local branches
+                # below), so both sides key off the same string.
                 resolved_variant = config.gguf_variant
                 same_source = bool(
                     source
@@ -918,14 +907,13 @@ async def load_model(
                         source,
                         (model_identifier, resolved_variant),
                     )
-                    # Cross-model: clear explicitly so the backend
-                    # doesn't inherit via "no opinion" semantics.
+                    # Cross-model: clear explicitly so the backend doesn't
+                    # inherit via "no opinion" semantics.
                     extra_llama_args = []
                 else:
-                    # Strip only the groups whose first-class field
-                    # was actually set by the caller, so an inherited
-                    # --chat-template-file survives an Apply that omits
-                    # chat_template_override.
+                    # Strip only the groups whose first-class field was set by
+                    # the caller, so an inherited --chat-template-file survives
+                    # an Apply that omits chat_template_override.
                     fields_set = getattr(request, "model_fields_set", set())
                     stripped = strip_shadowing_flags(
                         llama_backend.extra_args,
@@ -939,8 +927,8 @@ async def load_model(
                     try:
                         extra_llama_args = validate_extra_args(stripped)
                     except ValueError:
-                        # Should not happen on already-validated args; degrade
-                        # to no-extras rather than 400 if managed flags changed.
+                        # Shouldn't happen on already-validated args; degrade to
+                        # no-extras rather than 400 if managed flags changed.
                         logger.warning(
                             "Stored llama_extra_args failed revalidation; "
                             "loading without them: %s",
@@ -955,10 +943,9 @@ async def load_model(
                                 extra_llama_args,
                             )
 
-            # Route to HF mode or local mode based on config
-            # Run in a thread so the event loop stays free for progress
-            # polling and other requests during the (potentially long)
-            # GGUF download + llama-server startup.
+            # Route to HF or local mode based on config. Run in a thread so the
+            # event loop stays free for progress polling and other requests
+            # during the (potentially long) GGUF download + llama-server start.
             _n_parallel = getattr(fastapi_request.app.state, "llama_parallel_slots", 1)
 
             if config.gguf_hf_repo:
@@ -986,9 +973,9 @@ async def load_model(
                     llama_backend.load_model,
                     gguf_path = config.gguf_file,
                     mmproj_path = config.gguf_mmproj_file,
-                    # Pass the resolved variant so _extra_args_source
-                    # is keyed off the same string the inheritance
-                    # check at the top of /load uses (#5401 followup).
+                    # Pass the resolved variant so _extra_args_source keys off
+                    # the same string the inheritance check at the top of /load
+                    # uses (#5401 followup).
                     hf_variant = config.gguf_variant,
                     model_identifier = config.identifier,
                     is_vision = config.is_vision,
@@ -1069,9 +1056,9 @@ async def load_model(
         except Exception as e:
             logger.warning("Could not shut down export subprocess: %s", e)
 
-        # Auto-detect quantization for LoRA adapters from adapter_config.json
-        # The training pipeline patches this file with "unsloth_training_method"
-        # which is 'qlora' or 'lora'. Only LoRA (16-bit) needs load_in_4bit=False.
+        # Auto-detect quantization for LoRA adapters from adapter_config.json.
+        # The training pipeline writes "unsloth_training_method" ('qlora' or
+        # 'lora'); only LoRA (16-bit) needs load_in_4bit=False.
         load_in_4bit = request.load_in_4bit
         if config.is_lora and config.path:
             import json
@@ -1100,7 +1087,7 @@ async def load_model(
                             f"Training method: {training_method}, load_in_4bit={load_in_4bit}"
                         )
                     else:
-                        # No unsloth_training_method — fallback to base model name
+                        # No unsloth_training_method -- fall back to base model name
                         if (
                             config.base_model
                             and "-bnb-4bit" not in config.base_model.lower()
@@ -1115,8 +1102,8 @@ async def load_model(
                 except Exception as e:
                     logger.warning(f"Could not read adapter_config.json: {e}")
 
-        # Load the model in a thread so the event loop stays free
-        # for download progress polling and other requests.
+        # Load in a thread so the event loop stays free for download progress
+        # polling and other requests.
         success = await asyncio.to_thread(
             backend.load_model,
             config = config,
@@ -1128,7 +1115,7 @@ async def load_model(
         )
 
         if not success:
-            # Check if YAML says this model needs trust_remote_code
+            # Check if YAML says this model needs trust_remote_code.
             if not request.trust_remote_code:
                 model_defaults = load_model_defaults(config.identifier)
                 yaml_trust = model_defaults.get("inference", {}).get("trust_remote_code", False)
@@ -1199,7 +1186,7 @@ async def load_model(
         # User-facing validation (e.g. "Invalid gpu_ids [99]"): redact paths, keep detail.
         raise HTTPException(status_code = 400, detail = redact_native_paths(str(e)))
     except Exception as e:
-        # Surface a friendlier message for models that Unsloth cannot load
+        # Friendlier message for models Unsloth cannot load.
         not_supported_hints = [
             "No config file found",
             "not yet supported",
@@ -1234,8 +1221,8 @@ async def validate_model(
     """
     Lightweight validation endpoint for model identifiers.
 
-    This checks that ModelConfig.from_identifier() can resolve the given
-    model_path, but it does NOT actually load model weights into GPU memory.
+    Checks that ModelConfig.from_identifier() can resolve model_path, but does
+    NOT load model weights into GPU memory.
     """
     native_grant_backed = False
     model_log_label = request.model_path
@@ -1310,7 +1297,7 @@ async def unload_model(request: UnloadRequest, current_subject: str = Depends(ge
     Routes to the correct backend (llama-server for GGUF, Unsloth otherwise).
     """
     try:
-        # Check if the GGUF backend has this model loaded or is loading it
+        # Check if the GGUF backend has this model loaded or is loading it.
         llama_backend = get_llama_cpp_backend()
         if llama_backend.is_active and (
             llama_backend.model_identifier == request.model_path
@@ -1341,8 +1328,8 @@ async def cancel_inference(request: Request, current_subject: str = Depends(get_
       session_id   - fallback when cancel_id is absent.
       completion_id - fallback when cancel_id is absent.
 
-    A cancel_id arriving before its stream registers is stashed briefly
-    and replayed on registration. Returns {"cancelled": N}.
+    A cancel_id arriving before its stream registers is stashed briefly and
+    replayed on registration. Returns {"cancelled": N}.
     """
     try:
         body = await request.json()
@@ -1357,8 +1344,8 @@ async def cancel_inference(request: Request, current_subject: str = Depends(get_
         return {"cancelled": _cancel_by_cancel_id_or_stash(cancel_id)}
 
     keys = []
-    # `message_id` is the Anthropic passthrough's per-run identifier --
-    # included so /v1/messages clients can cancel by their native id.
+    # `message_id` is the Anthropic passthrough's per-run identifier, so
+    # /v1/messages clients can cancel by their native id.
     for k in ("completion_id", "session_id", "message_id"):
         v = body.get(k)
         if isinstance(v, str) and v:
@@ -1378,7 +1365,7 @@ async def generate_stream(
     """
     Generate a chat response with Server-Sent Events (SSE) streaming.
 
-    For vision models, provide image_base64 with the base64-encoded image.
+    For vision models, provide image_base64 (base64-encoded image).
     """
     backend = get_inference_backend()
 
@@ -1387,7 +1374,7 @@ async def generate_stream(
             status_code = 400, detail = "No model loaded. Call POST /inference/load first."
         )
 
-    # Decode image if provided (for vision models)
+    # Decode image if provided (vision models)
     image = None
     if request.image_base64:
         try:
@@ -1395,7 +1382,7 @@ async def generate_stream(
             from PIL import Image
             from io import BytesIO
 
-            # Check if current model supports vision
+            # Check current model supports vision
             model_info = backend.models.get(backend.active_model_name, {})
             if not model_info.get("is_vision"):
                 raise HTTPException(
@@ -1452,12 +1439,12 @@ async def generate_stream(
 async def get_status(current_subject: str = Depends(get_current_subject)):
     """
     Get current inference backend status.
-    Reports whichever backend (Unsloth or llama-server) is currently active.
+    Reports whichever backend (Unsloth or llama-server) is active.
     """
     try:
         llama_backend = get_llama_cpp_backend()
 
-        # MTP probe + freshness check (both cached). Drive the UI banner.
+        # MTP probe + freshness check (both cached); drive the UI banner.
         try:
             _bin = type(llama_backend)._find_llama_server_binary()
             _caps = type(llama_backend).probe_server_capabilities(_bin)
@@ -1585,15 +1572,13 @@ async def get_load_progress(current_subject: str = Depends(get_current_subject))
     """
     Return the active GGUF load's mmap/upload progress.
 
-    During the warmup window after a GGUF download -- when llama-server
-    is paging ~tens-to-hundreds of GB of shards into the page cache
-    before pushing layers to VRAM -- ``/api/inference/status`` only
-    shows a generic spinner. This endpoint exposes sampled progress so
-    the UI can render a real bar plus rate/ETA during that window.
+    During the warmup window after a GGUF download -- when llama-server pages
+    ~tens-to-hundreds of GB of shards into the page cache before pushing layers
+    to VRAM -- ``/api/inference/status`` only shows a generic spinner. This
+    exposes sampled progress so the UI can render a real bar plus rate/ETA.
 
-    Returns an empty payload (``phase=null, bytes=0``) when no load is
-    in flight. The frontend should stop polling once ``phase`` becomes
-    ``ready``.
+    Returns an empty payload (``phase=null, bytes=0``) when no load is in
+    flight. The frontend should stop polling once ``phase`` becomes ``ready``.
     """
     try:
         llama_backend = get_llama_cpp_backend()
@@ -1619,7 +1604,7 @@ async def generate_audio(
 ):
     """
     Generate audio (TTS) from the latest user message.
-    Returns a JSON response with base64-encoded WAV audio.
+    Returns JSON with base64-encoded WAV audio.
     Works with both GGUF (llama-server) and Unsloth/transformers backends.
     """
     import base64
@@ -1707,8 +1692,8 @@ def _decode_audio_base64(b64: str) -> np.ndarray:
     from utils.paths import ensure_dir, tmp_root
 
     raw = base64.b64decode(b64)
-    # torchaudio.load needs a file path or file-like object with format hint
-    # Write to a temp file so torchaudio can auto-detect the format
+    # torchaudio.load needs a path or file-like with a format hint; write a
+    # temp file so it can auto-detect the format.
     with tempfile.NamedTemporaryFile(
         suffix = ".audio",
         delete = False,
@@ -1741,9 +1726,9 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
     (``[{type: "text", ...}, {type: "image_url", ...}]``).
 
     Returns:
-        system_prompt:  The system message text (empty string if none provided).
+        system_prompt:  System message text (empty string if none).
         chat_messages:  Non-system messages with content flattened to strings.
-        image_base64:   Base64 data of the *first* image found, or ``None``.
+        image_base64:   Base64 of the *first* image found, or ``None``.
     """
     system_prompt = ""
     chat_messages: list[dict] = []
@@ -1772,7 +1757,7 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
                 elif part.type == "image_url" and first_image_b64 is None:
                     url = part.image_url.url
                     if url.startswith("data:"):
-                        # data:image/png;base64,<DATA> → extract <DATA>
+                        # data:image/png;base64,<DATA> -> extract <DATA>
                         first_image_b64 = url.split(",", 1)[1] if "," in url else None
                     else:
                         logger.warning(f"Remote image URLs not yet supported: {url[:80]}...")
@@ -1785,14 +1770,14 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
 # ── External provider proxy ──────────────────────────────────────
 
 
-# Providers whose stream helper translates `input_document` parts into
-# a native attachment block on the wire. For Anthropic the mapping is
-# `_stream_anthropic` -> {type:"document", source:...}; for OpenAI it
-# is `_stream_openai_responses` -> {type:"input_file", file_data|file_url}.
-# Every other provider (gemini / mistral / kimi / openrouter / deepseek /
-# custom OpenAI-compat) goes through the generic /chat/completions
-# passthrough that forwards messages verbatim, so handing them an
-# `input_document` part would 400 with an unknown content_part type.
+# Providers whose stream helper translates `input_document` parts into a
+# native attachment block on the wire. Anthropic: `_stream_anthropic` ->
+# {type:"document", source:...}; OpenAI: `_stream_openai_responses` ->
+# {type:"input_file", file_data|file_url}. Every other provider (gemini /
+# mistral / kimi / openrouter / deepseek / custom OpenAI-compat) goes through
+# the generic /chat/completions passthrough that forwards messages verbatim,
+# so handing them an `input_document` part would 400 with an unknown
+# content_part type.
 _INPUT_DOCUMENT_PROVIDERS = frozenset({"anthropic", "openai"})
 
 
@@ -1808,32 +1793,29 @@ def _build_external_messages(
     Behaviour per content-part type:
     - `text`: always preserved.
     - `image_url`: preserved on vision providers; stripped on non-vision.
-    - `input_document`: preserved ONLY when the provider's stream helper
-      has explicit translation logic for it (Anthropic + OpenAI today,
-      see ``_INPUT_DOCUMENT_PROVIDERS``). For every other provider the
-      part is stripped so the unknown content type doesn't reach generic
-      /chat/completions passthrough and 400 the request.
-    - `reasoning`: OpenAI-only Responses reasoning item paired with a
-      prior tool output. Forwarded ONLY when provider_type=="openai"
-      so follow-up image edits can replay the required reasoning item.
-    - `image_generation_call`: OpenAI-only Responses image reference.
-      Forwarded ONLY when provider_type=="openai" so follow-up image
-      edits can reference prior generated images.
+    - `input_document`: preserved ONLY when the provider's stream helper has
+      explicit translation logic (Anthropic + OpenAI today, see
+      ``_INPUT_DOCUMENT_PROVIDERS``). Stripped for every other provider so the
+      unknown type doesn't reach generic /chat/completions and 400.
+    - `reasoning`: OpenAI-only Responses reasoning item paired with a prior
+      tool output. Forwarded ONLY when provider_type=="openai" so follow-up
+      image edits can replay the required reasoning item.
+    - `image_generation_call`: OpenAI-only Responses image reference. Forwarded
+      ONLY when provider_type=="openai" so follow-up image edits can reference
+      prior generated images.
     - `compaction`: Anthropic-only synthetic part (round-trips server-side
       compaction state). Forwarded ONLY when provider_type=="anthropic";
-      stripped for every other provider so the unknown part doesn't
-      reach generic /chat/completions passthrough where it would 400
-      (e.g. DeepSeek, Mistral, Gemini, Kimi, OpenRouter, etc.).
+      stripped elsewhere so the unknown part doesn't reach generic
+      /chat/completions and 400 (DeepSeek, Mistral, Gemini, Kimi, OpenRouter).
     """
     document_provider = provider_type in _INPUT_DOCUMENT_PROVIDERS
     anthropic = provider_type == "anthropic"
     openai = provider_type == "openai"
-    # `extra_content` is a Gemini-specific carrier for the assistant's
-    # text-part `thoughtSignature` round-trip on the native
-    # streamGenerateContent endpoint. Custom Gemini OpenAI-compatible
-    # gateways (LiteLLM etc.) route through /chat/completions where
-    # the field is unknown and can be rejected -- gate strictly on the
-    # Google-hosted Gemini base.
+    # `extra_content` carries the assistant's text-part `thoughtSignature`
+    # round-trip on Gemini's native streamGenerateContent endpoint. Custom
+    # Gemini OpenAI-compat gateways (LiteLLM etc.) route through
+    # /chat/completions where the field is unknown and can be rejected -- gate
+    # strictly on the Google-hosted Gemini base.
     _native_gemini = False
     if provider_type == "gemini" and base_url:
         try:
@@ -1849,16 +1831,15 @@ def _build_external_messages(
     )
 
     def _is_marked_server_builtin_tool_call(tc: Any) -> bool:
-        """Return True iff `tc` is a synthetic provider-side tool card
-        with one of the canonical builtin names and either:
-          - the new `args._server_tool` marker stamped by the backend, or
-          - a Gemini `args.google.native_part` payload (durable replay
-            signal for code_execution / image_generation that predates
-            the marker).
-        Such cards must not be forwarded to non-native providers
-        because they are not real user functions and the receiving API
-        will reject the orphan tool history. Real user functions with
-        these names normally have neither signal.
+        """Return True iff `tc` is a synthetic provider-side tool card with a
+        canonical builtin name and either:
+          - the `args._server_tool` marker stamped by the backend, or
+          - a Gemini `args.google.native_part` payload (durable replay signal
+            for code_execution / image_generation that predates the marker).
+        Such cards must not be forwarded to non-native providers: they aren't
+        real user functions, so the receiving API rejects the orphan tool
+        history. Real user functions with these names normally have neither
+        signal.
         """
         if not isinstance(tc, dict):
             return False
@@ -1880,31 +1861,28 @@ def _build_external_messages(
         google = args.get("google")
         return isinstance(google, dict) and isinstance(google.get("native_part"), dict)
 
-    # When we drop a server-side builtin tool_call here, the matching
-    # `role="tool"` follow-up must also be dropped from the outbound
-    # history -- otherwise the provider receives an orphan
-    # tool_call_id with no matching assistant call, which OpenAI
-    # Responses and Anthropic both reject.
+    # When we drop a server-side builtin tool_call, the matching `role="tool"`
+    # follow-up must also be dropped -- else the provider gets an orphan
+    # tool_call_id with no matching assistant call, which OpenAI Responses and
+    # Anthropic both reject.
     dropped_server_builtin_tool_call_ids: set[str] = set()
 
     def _filter_tool_calls(tool_calls: Any) -> Optional[list]:
         """Sanitize assistant `tool_calls` for non-native-Gemini providers.
 
         Two concerns:
-          1. `tool_calls[i].extra_content` carries Gemini-only
-             thoughtSignature metadata; strip it for providers that
-             cannot parse the unknown key.
-          2. Marked server-side builtin cards (`_server_tool: true` on
-             a canonical builtin name, or a Gemini `native_part`
-             payload) are provider-internal Studio tool cards from a
-             prior native Gemini turn; forwarding them to OpenAI /
-             Anthropic / custom OAI-compat gateways sends an orphan
-             `tool_calls` entry (no matching tool declaration, often
-             no matching `role="tool"` reply) that can be rejected.
-             We record the dropped call_ids so the matching role=tool
-             message is also skipped below.
-        Native Gemini keeps both untouched so the native translator can
-        replay them via `native_part`.
+          1. `tool_calls[i].extra_content` carries Gemini-only thoughtSignature
+             metadata; strip it for providers that can't parse the unknown key.
+          2. Marked server-side builtin cards (`_server_tool: true` on a
+             canonical builtin name, or a Gemini `native_part` payload) are
+             Studio-internal tool cards from a prior native Gemini turn;
+             forwarding them to OpenAI / Anthropic / custom OAI-compat gateways
+             sends an orphan `tool_calls` entry (no matching tool declaration,
+             often no matching `role="tool"` reply) that can be rejected. We
+             record the dropped call_ids so the matching role=tool message is
+             skipped below.
+        Native Gemini keeps both untouched so the translator can replay them
+        via `native_part`.
         """
         if not tool_calls:
             return None
@@ -1931,10 +1909,9 @@ def _build_external_messages(
 
     result = []
     for msg in messages:
-        # Drop role=tool messages whose matching server-builtin
-        # tool_call was already filtered above. Forwarding an orphan
-        # tool_result with no matching tool_call would be rejected by
-        # OpenAI Responses and Anthropic.
+        # Drop role=tool messages whose matching server-builtin tool_call was
+        # filtered above. An orphan tool_result with no matching tool_call is
+        # rejected by OpenAI Responses and Anthropic.
         if (
             msg.role == "tool"
             and isinstance(msg.tool_call_id, str)
@@ -1942,10 +1919,10 @@ def _build_external_messages(
         ):
             continue
         if isinstance(msg.content, str):
-            # Drop bare assistant messages with no content AND no
-            # tool_calls (some providers reject empty assistant turns).
-            # Preserve assistant turns whose only payload is tool_calls
-            # so multi-turn function-call loops round-trip.
+            # Drop bare assistant messages with no content AND no tool_calls
+            # (some providers reject empty assistant turns). Preserve assistant
+            # turns whose only payload is tool_calls so multi-turn
+            # function-call loops round-trip.
             if msg.role == "assistant" and not msg.content.strip() and not msg.tool_calls:
                 continue
             out: dict[str, Any] = {"role": msg.role, "content": msg.content}
@@ -1954,10 +1931,10 @@ def _build_external_messages(
                 if _tcs:
                     out["tool_calls"] = _tcs
                 elif not msg.content.strip():
-                    # Every tool_call was a synthetic provider-side
-                    # card and was dropped; the assistant turn would
-                    # be an empty `{"role":"assistant","content":""}`
-                    # which some providers reject. Skip it entirely.
+                    # Every tool_call was a dropped synthetic provider card;
+                    # the turn would be an empty
+                    # `{"role":"assistant","content":""}` that some providers
+                    # reject. Skip it entirely.
                     continue
             if msg.role == "tool":
                 if msg.tool_call_id:
@@ -1968,15 +1945,14 @@ def _build_external_messages(
                 out["extra_content"] = msg.extra_content
             result.append(out)
             continue
-        # Assistant messages with content=None but populated tool_calls
-        # are valid (post-tool-call assistant turn). Forward them so the
-        # provider helper can rebuild the functionCall part.
+        # Assistant messages with content=None but populated tool_calls are
+        # valid (post-tool-call turn). Forward them so the provider helper can
+        # rebuild the functionCall part.
         if msg.content is None and msg.role == "assistant" and msg.tool_calls:
             _filtered_tcs = _filter_tool_calls(msg.tool_calls)
             if not _filtered_tcs:
-                # Every tool_call on this turn was provider-side
-                # synthetic and dropped; skipping the whole message
-                # avoids forwarding an empty assistant turn.
+                # Every tool_call was provider-side synthetic and dropped;
+                # skip the whole message to avoid an empty assistant turn.
                 continue
             _assistant_only: dict[str, Any] = {
                 "role": "assistant",
@@ -2015,16 +1991,15 @@ def _build_external_messages(
                         # ExternalProviderClient maps this onto a top-level
                         # Responses input item after the current user prompt,
                         # or onto `previous_response_id` when response_id is
-                        # available from the prior Responses turn.
+                        # available from the prior turn.
                         image_ref = {"type": "image_generation_call", "id": part.id}
                         if getattr(part, "response_id", None):
                             image_ref["response_id"] = part.response_id
                         parts.append(image_ref)
                     elif part.type == "input_document" and document_provider:
-                        # ExternalProviderClient maps this onto
-                        # Anthropic's `document` or OpenAI Responses'
-                        # `input_file` block per provider; every other
-                        # provider would 400 on the unknown part type.
+                        # ExternalProviderClient maps this onto Anthropic's
+                        # `document` or OpenAI Responses' `input_file` block;
+                        # every other provider would 400 on the unknown part.
                         doc: dict[str, Any] = {"type": "input_document"}
                         if part.file_data:
                             doc["file_data"] = part.file_data
@@ -2036,10 +2011,9 @@ def _build_external_messages(
                             doc["media_type"] = part.media_type
                         parts.append(doc)
                     elif part.type == "compaction" and anthropic:
-                        # Anthropic stream helper forwards this as a
-                        # native `compaction` block; every other
-                        # provider would 400 on the unknown part, so
-                        # gate by provider_type.
+                        # Anthropic stream helper forwards this as a native
+                        # `compaction` block; every other provider would 400 on
+                        # the unknown part, so gate by provider_type.
                         parts.append({"type": "compaction", "content": part.content})
                 entry: dict[str, Any] = {"role": msg.role, "content": parts}
                 if msg.role == "assistant" and msg.tool_calls:
@@ -2047,10 +2021,9 @@ def _build_external_messages(
                     if _tcs:
                         entry["tool_calls"] = _tcs
                     elif not parts:
-                        # All tool_calls were synthetic and dropped,
-                        # and no preserved content parts survived.
-                        # Skip rather than forward an empty assistant
-                        # turn that downstream providers reject.
+                        # All tool_calls were synthetic and dropped, and no
+                        # content parts survived. Skip rather than forward an
+                        # empty assistant turn that downstream providers reject.
                         continue
                 elif msg.role == "assistant" and not parts:
                     continue
@@ -2063,11 +2036,10 @@ def _build_external_messages(
                     entry["extra_content"] = msg.extra_content
                 result.append(entry)
             else:
-                # Non-vision provider: strip images / documents, keep
-                # text, optionally keep compaction (Anthropic only --
+                # Non-vision provider: strip images / documents, keep text,
+                # optionally keep compaction (Anthropic only --
                 # compaction-capable Anthropic models all report
-                # supports_vision=True today, but the gate is here for
-                # safety).
+                # supports_vision=True today, but gate here for safety).
                 preserved = []
                 for p in msg.content:
                     if p.type == "text":
@@ -2091,8 +2063,8 @@ def _build_external_messages(
                 if msg.role == "assistant" and not preserved:
                     continue
                 if len(preserved) == 1 and preserved[0]["type"] == "text":
-                    # Single text part collapses back to a string for
-                    # providers that don't accept content arrays.
+                    # Single text part collapses to a string for providers that
+                    # don't accept content arrays.
                     entry = {"role": msg.role, "content": preserved[0]["text"]}
                 else:
                     entry = {"role": msg.role, "content": preserved}
@@ -2101,8 +2073,8 @@ def _build_external_messages(
                     if _tcs:
                         entry["tool_calls"] = _tcs
                     else:
-                        # All tool_calls were synthetic and dropped;
-                        # skip if there's no surviving content either.
+                        # All tool_calls were synthetic and dropped; skip if no
+                        # content survived either.
                         _entry_content = entry.get("content")
                         _has_text = (
                             isinstance(_entry_content, str) and _entry_content.strip()
@@ -2126,8 +2098,8 @@ async def _proxy_to_external_provider(
     """
     Proxy a chat completion request to an external LLM provider.
 
-    Resolves provider config (from DB or registry), decrypts the API key,
-    and streams the response back in OpenAI SSE format.
+    Resolves provider config (DB or registry), decrypts the API key, and
+    streams the response back in OpenAI SSE format.
     """
     # Resolve provider type and base URL
     provider_type = payload.provider_type
@@ -2181,7 +2153,7 @@ async def _proxy_to_external_provider(
             detail = "external_model is required when using an external provider.",
         )
 
-    # Build messages preserving multimodal content for vision-capable providers
+    # Build messages, preserving multimodal content for vision providers
     from core.inference.providers import get_provider_info as _get_provider_info
 
     _pinfo = _get_provider_info(provider_type) or {}
@@ -2199,11 +2171,10 @@ async def _proxy_to_external_provider(
         api_key = api_key,
     )
 
-    # `top_k` defaults to 20 in ChatCompletionRequest because the local
-    # inference path expects an int, but the external-provider path
-    # should treat "field omitted from JSON" as "use provider default"
-    # so callers that send only model/messages do not silently get
-    # different sampling than before this PR. Pydantic's
+    # `top_k` defaults to 20 in ChatCompletionRequest because the local path
+    # expects an int, but the external-provider path treats "field omitted from
+    # JSON" as "use provider default" so callers sending only model/messages
+    # don't silently get different sampling than before this PR. Pydantic's
     # `model_fields_set` tracks explicit-vs-default per request.
     _top_k_explicit = payload.top_k if "top_k" in payload.model_fields_set else None
 
@@ -2261,11 +2232,11 @@ async def _proxy_to_external_provider(
 
 def _resolve_openai_cloud_client(body: OpenAIContainerRequest) -> ExternalProviderClient:
     """
-    Decrypt the API key + validate the base URL points at OpenAI cloud,
-    then build an ExternalProviderClient for the three container CRUD
-    endpoints below. The shell tool only exists on api.openai.com, so
-    rejecting non-cloud bases up front prevents confusing 404s on
-    ollama / llama.cpp / vLLM / custom presets.
+    Decrypt the API key + validate the base URL points at OpenAI cloud, then
+    build an ExternalProviderClient for the three container CRUD endpoints
+    below. The shell tool only exists on api.openai.com, so rejecting non-cloud
+    bases up front prevents confusing 404s on ollama / llama.cpp / vLLM /
+    custom presets.
     """
     base_url = body.provider_base_url or get_base_url("openai")
     if not base_url or "api.openai.com" not in base_url:
@@ -2337,9 +2308,9 @@ async def list_openai_containers(
                 event = "openai_container_list.transport_error",
                 log = logger,
             )
-        # OpenAI keeps expired containers in /v1/containers indefinitely
-        # with status="expired" — they're effectively dead but still
-        # listed. Hide them so the picker only shows usable containers.
+        # OpenAI keeps expired containers in /v1/containers indefinitely with
+        # status="expired" -- dead but still listed. Hide them so the picker
+        # only shows usable containers.
         return ListOpenAIContainersResponse(
             containers = [
                 _summarize_container(c)
@@ -2442,35 +2413,35 @@ async def openai_chat_completions(
     """
     OpenAI-compatible chat completions endpoint.
 
-    Supports multimodal messages: ``content`` may be a plain string or a
-    list of content parts (``text`` / ``image_url``).
+    Supports multimodal messages: ``content`` may be a plain string or a list
+    of content parts (``text`` / ``image_url``).
 
     Non-streaming (default): returns a single ChatCompletion JSON object.
     Streaming:               returns SSE chunks matching OpenAI's format.
 
-    ``stream`` defaults to ``false`` to match OpenAI's spec; clients opt
-    into SSE by sending ``stream: true``.
+    ``stream`` defaults to ``false`` per OpenAI's spec; clients opt into SSE by
+    sending ``stream: true``.
 
-    Automatically routes to the correct backend:
+    Routes to the correct backend automatically:
     - GGUF models → llama-server via LlamaCppBackend
     - Other models → Unsloth/transformers via InferenceBackend
     """
     # ── External provider routing ────────────────────────────────
-    # encrypted_api_key is optional — local providers (llama.cpp / vLLM / Ollama) may run without auth.
+    # encrypted_api_key is optional -- local providers (llama.cpp / vLLM / Ollama) may run without auth.
     if payload.provider_id or payload.provider_type:
         return await _proxy_to_external_provider(payload, request)
 
     llama_backend = get_llama_cpp_backend()
     using_gguf = llama_backend.is_loaded
 
-    # OpenAI-SDK clients send ``chat_template_kwargs`` via ``extra_body``,
-    # which the SDK spreads into the request body at the top level. Studio's
+    # OpenAI-SDK clients send ``chat_template_kwargs`` via ``extra_body``, which
+    # the SDK spreads into the request body at the top level. Studio's
     # ChatCompletionRequest has ``extra="allow"`` so pydantic stashes them in
-    # ``model_extra``, but the typed ``payload.enable_thinking`` path is what
-    # downstream generators actually consume. Lift ``enable_thinking`` from
-    # the extra-body chat_template_kwargs onto the typed field so clients
-    # that only know the OpenAI shape (data_designer recipe runs, etc.)
-    # can still control the reasoning preamble.
+    # ``model_extra``, but downstream generators consume the typed
+    # ``payload.enable_thinking``. Lift ``enable_thinking`` from the extra-body
+    # chat_template_kwargs onto the typed field so clients that only know the
+    # OpenAI shape (data_designer recipe runs, etc.) can still control the
+    # reasoning preamble.
     _extra = getattr(payload, "model_extra", None)
     if payload.enable_thinking is None and isinstance(_extra, dict):
         _tpl_kw = _extra.get("chat_template_kwargs")
@@ -2492,7 +2463,7 @@ async def openai_chat_completions(
         model_name = backend.active_model_name or payload.model
 
         # ── Audio TTS path: auto-route to audio generation ────
-        # (Whisper is ASR not TTS — handled below in audio input path)
+        # (Whisper is ASR not TTS -- handled below in audio input path)
         model_info = backend.models.get(backend.active_model_name, {})
         if model_info.get("is_audio") and model_info.get("audio_type") != "whisper":
             return await generate_audio(payload, request)
@@ -2620,21 +2591,19 @@ async def openai_chat_completions(
     # ── Standard OpenAI function-calling pass-through (GGUF only) ────
     # When a client (opencode / Claude Code via OpenAI compat / Cursor /
     # Continue / ...) sends standard OpenAI `tools` without Studio's
-    # `enable_tools` shorthand, forward the request to llama-server
-    # verbatim so structured `tool_calls` flow back to the client. This
-    # branch runs BEFORE `_extract_content_parts` because that helper is
-    # unaware of `role="tool"` messages and assistant messages that only
-    # carry `tool_calls` (content=None) — both of which are valid in
-    # multi-turn client-side tool loops.
+    # `enable_tools` shorthand, forward to llama-server verbatim so structured
+    # `tool_calls` flow back. Runs BEFORE `_extract_content_parts` because that
+    # helper is unaware of `role="tool"` messages and assistant messages that
+    # only carry `tool_calls` (content=None) -- both valid in multi-turn
+    # client-side tool loops.
     _has_tool_messages = any(m.role == "tool" or m.tool_calls for m in payload.messages)
     # Route guided-decoding requests through the verbatim passthrough so
-    # ``response_format`` (JSON schema) actually reaches llama-server and
-    # the model's GBNF-constrained output comes back unmodified. The
-    # non-passthrough GGUF path below calls ``generate_chat_completion``
-    # which has no response_format kwarg, so the schema gets silently
-    # dropped and data_designer falls back to free-form sampling. Guided
-    # decoding does not require ``supports_tools`` - the grammar machinery
-    # is independent of tool-call parsing.
+    # ``response_format`` (JSON schema) reaches llama-server and the model's
+    # GBNF-constrained output comes back unmodified. The non-passthrough GGUF
+    # path below calls ``generate_chat_completion`` which has no response_format
+    # kwarg, so the schema gets silently dropped and data_designer falls back to
+    # free-form sampling. Guided decoding does not require ``supports_tools`` --
+    # the grammar machinery is independent of tool-call parsing.
     _has_response_format = _extract_response_format(payload) is not None
     _tools_passthrough = llama_backend.supports_tools and (
         (payload.tools and len(payload.tools) > 0) or _has_tool_messages
@@ -2650,10 +2619,10 @@ async def openai_chat_completions(
                 detail = "Audio input is not supported for GGUF chat models yet.",
             )
 
-        # Preserve the vision guard that would otherwise run in the
-        # non-passthrough path below: text-only tool-capable GGUFs
-        # should return a clear 400 here rather than forwarding the
-        # image to llama-server and surfacing an opaque upstream error.
+        # Preserve the vision guard from the non-passthrough path below:
+        # text-only tool-capable GGUFs should return a clear 400 here rather
+        # than forwarding the image to llama-server and surfacing an opaque
+        # upstream error.
         if not llama_backend.is_vision and (
             payload.image_base64
             or any(
@@ -2670,8 +2639,8 @@ async def openai_chat_completions(
         cancel_event = threading.Event()
         completion_id = f"chatcmpl-{uuid.uuid4().hex[:12]}"
         # `stream` defaults to False on ChatCompletionRequest (OpenAI spec
-        # parity). Naive curl / .NET / System.Text.Json clients omitting
-        # the field used to get SSE here and choke on deserialization (#5047).
+        # parity). Naive curl / .NET / System.Text.Json clients omitting the
+        # field used to get SSE here and choke on deserialization (#5047).
         if payload.stream:
             return await _openai_passthrough_stream(
                 request,
@@ -2717,12 +2686,11 @@ async def openai_chat_completions(
 
         # ── Tool-calling path (agentic loop) ──────────────────
         # `_effective_enable_tools` lets `unsloth run --enable-tools/--disable-tools`
-        # hard-override the per-request value. Without a CLI override, falls
-        # back to `payload.enable_tools` (existing behavior). `mcp_enabled=true`
-        # also opens the tool loop so MCP-only callers do not have to flip a
-        # second flag, BUT must still honor a CLI `--disable-tools` policy --
-        # checking the raw policy here keeps `mcp_enabled` from re-enabling
-        # tools that the operator explicitly forbade.
+        # hard-override the per-request value, else falls back to
+        # `payload.enable_tools`. `mcp_enabled=true` also opens the tool loop so
+        # MCP-only callers needn't flip a second flag, BUT must still honor a
+        # CLI `--disable-tools` policy -- checking the raw policy here keeps
+        # `mcp_enabled` from re-enabling tools the operator explicitly forbade.
         from state.tool_policy import get_tool_policy as _get_tool_policy_g
 
         _cli_policy = _get_tool_policy_g()
@@ -2746,12 +2714,11 @@ async def openai_chat_completions(
             if _mcp_allowed:
                 tools_to_use = tools_to_use + await get_enabled_mcp_tools()
 
-            # Skip the tool loop when no tool actually survived, so the
-            # safetensors loop's "empty = allow all" semantic cannot reach
-            # built-in tools the caller did not opt into. Existing callers
-            # who omit enabled_tools still get ALL_TOOLS here, so this
-            # only suppresses the loop when discovery + opt-in left it
-            # genuinely empty.
+            # Skip the tool loop when no tool survived, so the safetensors
+            # loop's "empty = allow all" semantic can't reach built-in tools
+            # the caller didn't opt into. Callers who omit enabled_tools still
+            # get ALL_TOOLS here, so this only suppresses the loop when
+            # discovery + opt-in left it genuinely empty.
             if not tools_to_use:
                 use_tools = False
 
@@ -2764,8 +2731,8 @@ async def openai_chat_completions(
 
             _date_line = f"The current date is {_date.today().isoformat()}."
 
-            # Small models (<9B) struggle with multi-step search plans,
-            # so simplify the web tips to avoid plan-then-stall behavior.
+            # Small models (<9B) struggle with multi-step search plans, so
+            # simplify the web tips to avoid plan-then-stall behavior.
             _model_size_b = _extract_model_size_b(model_name)
             _is_small_model = _model_size_b is not None and _model_size_b < 9
 
@@ -2809,7 +2776,7 @@ async def openai_chat_completions(
 
             if _nudge:
                 _nudge += _tool_action_nudge(_has_artifact)
-                # Append nudge to system prompt (preserve user's prompt)
+                # Append nudge to system prompt (preserve the user's prompt)
                 if system_prompt:
                     system_prompt = system_prompt.rstrip() + "\n\n" + _nudge
                 else:
@@ -2869,8 +2836,8 @@ async def openai_chat_completions(
                     )
                     yield f"data: {first_chunk.model_dump_json(exclude_none = True)}\n\n"
 
-                    # Iterate the synchronous generator in a thread so
-                    # the event loop stays free for disconnect detection.
+                    # Iterate the sync generator in a thread so the event loop
+                    # stays free for disconnect detection.
                     gen = gguf_generate_with_tools()
                     prev_text = ""
                     _stream_usage = None
@@ -2887,14 +2854,14 @@ async def openai_chat_completions(
                             break
 
                         if event["type"] == "status":
-                            # Empty status marks an iteration boundary
-                            # in the GGUF tool loop (e.g. after a
-                            # re-prompt).  Reset the cumulative cursor
-                            # so the next assistant turn streams cleanly.
+                            # Empty status marks an iteration boundary in the
+                            # GGUF tool loop (e.g. after a re-prompt). Reset the
+                            # cumulative cursor so the next assistant turn
+                            # streams cleanly.
                             if not event["text"]:
                                 prev_text = ""
-                            # Emit tool status as a custom SSE event
-                            # (including empty ones to clear UI badges)
+                            # Emit tool status as a custom SSE event (including
+                            # empty ones to clear UI badges)
                             status_data = json.dumps(
                                 {
                                     "type": "tool_status",
@@ -2915,10 +2882,9 @@ async def openai_chat_completions(
                             _stream_timings = event.get("timings")
                             continue
 
-                        # "content" type -- cumulative text
-                        # Sanitize the full cumulative then diff against
-                        # the last sanitized snapshot so cross-chunk XML
-                        # tags are handled correctly.
+                        # "content" type -- cumulative text. Sanitize the full
+                        # cumulative then diff against the last sanitized
+                        # snapshot so cross-chunk XML tags are handled correctly.
                         raw_cumulative = event.get("text", "")
                         clean_cumulative = _TOOL_XML_RE.sub("", raw_cumulative)
                         new_text = clean_cumulative[len(prev_text) :]
@@ -2950,7 +2916,7 @@ async def openai_chat_completions(
                         ],
                     )
                     yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
-                    # Usage chunk (OpenAI-standard: choices=[], usage populated)
+                    # Usage chunk (OpenAI standard: choices=[], usage populated)
                     if _stream_usage or _stream_timings:
                         usage_obj = CompletionUsage(
                             prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
@@ -3038,8 +3004,8 @@ async def openai_chat_completions(
                     )
                     yield f"data: {first_chunk.model_dump_json(exclude_none = True)}\n\n"
 
-                    # Iterate the synchronous generator in a thread so
-                    # the event loop stays free for disconnect detection.
+                    # Iterate the sync generator in a thread so the event loop
+                    # stays free for disconnect detection.
                     gen = gguf_generate()
                     prev_text = ""
                     _stream_usage = None
@@ -3053,7 +3019,7 @@ async def openai_chat_completions(
                         cumulative = await asyncio.to_thread(next, gen, _gguf_sentinel)
                         if cumulative is _gguf_sentinel:
                             break
-                        # Capture server metadata for final usage chunk
+                        # Capture server metadata for the final usage chunk
                         if isinstance(cumulative, dict):
                             if cumulative.get("type") == "metadata":
                                 _stream_usage = cumulative.get("usage")
@@ -3094,7 +3060,7 @@ async def openai_chat_completions(
                         ],
                     )
                     yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
-                    # Usage chunk (OpenAI-standard: choices=[], usage populated)
+                    # Usage chunk (OpenAI standard: choices=[], usage populated)
                     if _stream_usage or _stream_timings:
                         usage_obj = CompletionUsage(
                             prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
@@ -3213,10 +3179,10 @@ async def openai_chat_completions(
     created = int(time.time())
 
     # ── Safetensors tool-calling path ─────────────────────────
-    # Mirrors the GGUF agentic loop's event shape. Disabled for
-    # vision turns (untested overlap with image render slot) and
-    # for gpt-oss (Harmony uses dedicated channels, not <tool_call>
-    # XML -- gpt-oss tools still work via the GGUF path).
+    # Mirrors the GGUF agentic loop's event shape. Disabled for vision turns
+    # (untested overlap with image render slot) and for gpt-oss (Harmony uses
+    # dedicated channels, not <tool_call> XML -- gpt-oss tools still work via
+    # the GGUF path).
     _sf_is_gptoss = False
     try:
         _sf_is_gptoss = bool(hasattr(backend, "_is_gpt_oss_model") and backend._is_gpt_oss_model())
@@ -3258,8 +3224,8 @@ async def openai_chat_completions(
             _sf_tools_to_use = _sf_tools_to_use + await get_enabled_mcp_tools()
 
         # Mirror the GGUF path: refuse to enter the tool loop when nothing
-        # survived, so a model-emitted built-in call cannot piggy-back on
-        # the empty allow-list.
+        # survived, so a model-emitted built-in call can't piggy-back on the
+        # empty allow-list.
         if not _sf_tools_to_use:
             _sf_use_tools = False
 
@@ -3474,8 +3440,8 @@ async def openai_chat_completions(
                 raise
             except Exception:
                 backend.reset_generation_state()
-                # Generic wire message; full trace stays in the log
-                # (CWE-209: transformers/torch errors may leak paths).
+                # Generic wire message; full trace stays in the log (CWE-209:
+                # transformers/torch errors may leak paths).
                 logger.exception("safetensors tool stream error")
                 error_chunk = {
                     "error": {
@@ -3547,8 +3513,8 @@ async def openai_chat_completions(
         max_new_tokens = payload.max_tokens or 2048,
         repetition_penalty = payload.repetition_penalty,
     )
-    # Forward reasoning kwargs; the worker/template wrapper peels off
-    # any the template doesn't accept.
+    # Forward reasoning kwargs; the worker/template wrapper peels off any the
+    # template doesn't accept.
     if payload.enable_thinking is not None:
         gen_kwargs["enable_thinking"] = payload.enable_thinking
     if payload.reasoning_effort is not None:
@@ -3599,12 +3565,12 @@ async def openai_chat_completions(
                 yield f"data: {first_chunk.model_dump_json(exclude_none = True)}\n\n"
 
                 prev_text = ""
-                # Run sync generator in thread pool to avoid blocking
-                # the event loop. Critical for compare mode: two SSE
-                # requests arrive concurrently but the orchestrator
-                # serializes them via _gen_lock. Without run_in_executor
-                # the second request's blocking lock acquisition would
-                # freeze the entire event loop, stalling both streams.
+                # Run the sync generator in a thread pool to avoid blocking the
+                # event loop. Critical for compare mode: two SSE requests arrive
+                # concurrently but the orchestrator serializes them via
+                # _gen_lock; without run_in_executor the second request's
+                # blocking lock acquisition would freeze the entire event loop,
+                # stalling both streams.
                 _DONE = object()  # sentinel for generator exhaustion
                 loop = asyncio.get_event_loop()
                 gen = generate()
@@ -3613,8 +3579,8 @@ async def openai_chat_completions(
                         backend.reset_generation_state()
                         break
                     # next(gen, _DONE) returns _DONE instead of raising
-                    # StopIteration — StopIteration cannot propagate
-                    # through asyncio futures (Python limitation).
+                    # StopIteration -- StopIteration can't propagate through
+                    # asyncio futures (Python limitation).
                     cumulative = await loop.run_in_executor(None, next, gen, _DONE)
                     if cumulative is _DONE:
                         break
@@ -3750,8 +3716,8 @@ async def serve_sandbox_file(
     """
     Serve image files created by Python tool execution.
 
-    Accepts auth via Authorization header OR ?token= query param
-    (needed because <img src> cannot send custom headers).
+    Accepts auth via Authorization header OR ?token= query param (needed
+    because <img src> cannot send custom headers).
     """
     from fastapi.responses import FileResponse
 
@@ -3863,8 +3829,8 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
     """
     OpenAI-compatible text completions endpoint (non-chat).
 
-    Transparently proxies to the running llama-server's ``/v1/completions``.
-    Only available when a GGUF model is loaded.
+    Proxies to the running llama-server's ``/v1/completions``. Only available
+    when a GGUF model is loaded.
     """
     llama_backend = get_llama_cpp_backend()
     if not llama_backend.is_loaded:
@@ -3880,15 +3846,14 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
     if is_stream:
 
         async def _stream():
-            # Manual httpx client/response lifecycle AND explicit
-            # aiter_bytes() iterator close — see _anthropic_passthrough_stream
-            # for the full rationale. Saving `bytes_iter = resp.aiter_bytes()`
-            # and `await bytes_iter.aclose()` in the finally block is the
-            # part that matters for avoiding the Python 3.13 + httpcore
-            # 1.0.x "Exception ignored in: <async_generator>" / anyio
-            # cancel-scope trace: an anonymous async for leaves the
-            # iterator unclosed, so Python's asyncgen GC finalizer runs
-            # cleanup on a later pass in a different asyncio task.
+            # Manual httpx client/response lifecycle AND explicit aiter_bytes()
+            # iterator close -- see _anthropic_passthrough_stream for the full
+            # rationale. Saving `bytes_iter = resp.aiter_bytes()` and `await
+            # bytes_iter.aclose()` in finally is what avoids the Python 3.13 +
+            # httpcore 1.0.x "Exception ignored in: <async_generator>" / anyio
+            # cancel-scope trace: an anonymous async for leaves the iterator
+            # unclosed, so the asyncgen GC finalizer runs cleanup later in a
+            # different asyncio task.
             client = httpx.AsyncClient(timeout = 600)
             resp = None
             bytes_iter = None
@@ -3937,10 +3902,10 @@ async def openai_embeddings(request: Request, current_subject: str = Depends(get
     """
     OpenAI-compatible embeddings endpoint.
 
-    Transparently proxies to the running llama-server's ``/v1/embeddings``.
-    Only available when a GGUF model is loaded.
-    Note: the loaded model must support pooling; otherwise llama-server
-    will return an error (expected).
+    Proxies to the running llama-server's ``/v1/embeddings``. Only available
+    when a GGUF model is loaded.
+    Note: the loaded model must support pooling, else llama-server returns an
+    error (expected).
     """
     llama_backend = get_llama_cpp_backend()
     if not llama_backend.is_loaded:
@@ -3981,9 +3946,9 @@ def _translate_responses_tools_to_chat(tools: Optional[list[dict]]) -> Optional[
                       "parameters": {...}, "strict": true}}
 
     Only ``type=="function"`` entries are forwarded. Built-in Responses tools
-    (``web_search``, ``file_search``, ``mcp``, ...) are dropped because
-    llama-server does not implement them server-side; keeping them in the
-    request would produce an opaque upstream 400.
+    (``web_search``, ``file_search``, ``mcp``, ...) are dropped: llama-server
+    doesn't implement them server-side, so keeping them would produce an opaque
+    upstream 400.
     """
     if not tools:
         return None
@@ -4010,8 +3975,8 @@ def _translate_responses_tool_choice_to_chat(tool_choice: Any) -> Any:
     """Translate a Responses-shape ``tool_choice`` to the Chat Completions shape.
 
     String values (``"auto"``/``"none"``/``"required"``) pass through unchanged.
-    The Responses forcing object ``{"type": "function", "name": "X"}`` is
-    converted to Chat Completions' ``{"type": "function", "function": {"name": "X"}}``.
+    The Responses forcing object ``{"type": "function", "name": "X"}`` becomes
+    Chat Completions' ``{"type": "function", "function": {"name": "X"}}``.
     Unknown / built-in tool choices are forwarded as-is; llama-server ignores
     what it doesn't recognise.
     """
@@ -4046,28 +4011,26 @@ def _responses_message_text(content: Union[str, list]) -> str:
 
 
 def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
-    """Convert a ResponsesRequest's ``input`` into Chat-format ``ChatMessage`` list.
+    """Convert a ResponsesRequest's ``input`` into a Chat-format ``ChatMessage`` list.
 
     Handles the three input item shapes allowed by the Responses API:
 
-    - ``ResponsesInputMessage`` — regular chat messages (text or multimodal).
-    - ``ResponsesFunctionCallInputItem`` — a prior assistant tool call replayed
-      on a follow-up turn. Converted into an assistant message carrying a
+    - ``ResponsesInputMessage`` -- regular chat messages (text or multimodal).
+    - ``ResponsesFunctionCallInputItem`` -- a prior assistant tool call
+      replayed on a follow-up turn. Becomes an assistant message carrying a
       Chat Completions ``tool_calls`` entry keyed by ``call_id``.
-    - ``ResponsesFunctionCallOutputInputItem`` — a tool result the client is
-      returning. Converted into a ``role="tool"`` message with ``tool_call_id``
-      set to the originating ``call_id`` so llama-server can reconcile the
-      call with its result.
+    - ``ResponsesFunctionCallOutputInputItem`` -- a tool result the client is
+      returning. Becomes a ``role="tool"`` message with ``tool_call_id`` set to
+      the originating ``call_id`` so llama-server can reconcile call with result.
 
-    System / developer content is collected from ``instructions`` *and* from
-    any ``role="system"`` / ``role="developer"`` entries in ``input``, then
-    merged into a single ``role="system"`` message placed at the top of the
-    returned list. This satisfies strict chat templates (harmony / gpt-oss,
-    Qwen3, ...) whose Jinja raises ``"System message must be at the
-    beginning."`` when more than one system message is present or when a
-    system message appears after a user turn — the exact pattern the OpenAI
-    Codex CLI hits, since Codex sets ``instructions`` *and* also sends a
-    developer message in ``input``.
+    System / developer content is collected from ``instructions`` *and* any
+    ``role="system"`` / ``role="developer"`` entries in ``input``, then merged
+    into a single top-of-list ``role="system"`` message. This satisfies strict
+    chat templates (harmony / gpt-oss, Qwen3, ...) whose Jinja raises
+    ``"System message must be at the beginning."`` when more than one system
+    message is present or a system message follows a user turn -- the exact
+    pattern the OpenAI Codex CLI hits, since Codex sets ``instructions`` *and*
+    also sends a developer message in ``input``.
     """
     system_parts: list[str] = []
     messages: list[ChatMessage] = []
@@ -4105,8 +4068,8 @@ def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
             continue
 
         if isinstance(item, ResponsesFunctionCallOutputInputItem):
-            # Chat Completions `role="tool"` requires a string content; if a
-            # Responses client sends a content-array output, serialize it.
+            # Chat Completions `role="tool"` requires string content; serialize
+            # a Responses content-array output.
             output = item.output
             if not isinstance(output, str):
                 output = json.dumps(output)
@@ -4120,13 +4083,13 @@ def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
             continue
 
         if isinstance(item, ResponsesUnknownInputItem):
-            # Reasoning items and any other unmodelled top-level Responses
-            # item types are silently dropped — llama-server-backed GGUFs
-            # cannot consume them and our lenient validation let them in so
-            # unrelated turns don't 422.
+            # Reasoning items and other unmodelled top-level Responses item
+            # types are silently dropped -- llama-server-backed GGUFs can't
+            # consume them; lenient validation lets them in so unrelated turns
+            # don't 422.
             continue
 
-        # ResponsesInputMessage — hoist system/developer to the top, merge.
+        # ResponsesInputMessage -- hoist system/developer to the top, merge.
         if item.role in ("system", "developer"):
             hoisted = _responses_message_text(item.content)
             if hoisted:
@@ -4139,16 +4102,16 @@ def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
 
         # Assistant-replay turns come back as content = [output_text, ...].
         # Chat Completions' assistant role expects a plain string, not a
-        # multimodal content array, so flatten output_text (and any stray
-        # input_text / unknown text) to a single string.
+        # multimodal array, so flatten output_text (and any stray input_text /
+        # unknown text) to a single string.
         if item.role == "assistant":
             text = _responses_message_text(item.content)
             if text:
                 messages.append(ChatMessage(role = "assistant", content = text))
             continue
 
-        # User (and any other remaining roles) — keep multimodal when
-        # present, drop unknown content parts silently.
+        # User (and any other remaining roles) -- keep multimodal when present,
+        # drop unknown content parts silently.
         parts: list = []
         for part in item.content:
             if isinstance(part, (ResponsesInputTextPart, ResponsesOutputTextPart)):
@@ -4162,9 +4125,8 @@ def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
                 )
             # ResponsesUnknownContentPart and anything else: drop.
         if parts:
-            # Collapse single-text-part content to a plain string so roles
-            # that reject multimodal arrays (e.g. legacy templates) still
-            # accept the message.
+            # Collapse single-text-part content to a plain string so roles that
+            # reject multimodal arrays (e.g. legacy templates) still accept it.
             if len(parts) == 1 and isinstance(parts[0], TextContentPart):
                 messages.append(ChatMessage(role = item.role, content = parts[0].text))
             else:
@@ -4183,8 +4145,7 @@ def _build_chat_request(
 
     Tools and ``tool_choice`` are translated from the flat Responses shape to
     the nested Chat Completions shape here so the existing #5099
-    ``/v1/chat/completions`` client-side pass-through picks them up without
-    further modification.
+    ``/v1/chat/completions`` client-side pass-through picks them up unchanged.
     """
     chat_kwargs: dict = dict(
         model = payload.model,
@@ -4207,11 +4168,11 @@ def _build_chat_request(
         chat_kwargs["tool_choice"] = chat_tool_choice
 
     req = ChatCompletionRequest(**chat_kwargs)
-    # `parallel_tool_calls` is not a first-class field on ChatCompletionRequest,
+    # `parallel_tool_calls` isn't a first-class field on ChatCompletionRequest,
     # but the model allows extras and _build_openai_passthrough_body forwards
-    # only explicitly-known fields. Llama-server does not currently implement
-    # parallel_tool_calls semantics, so we accept-and-ignore it on the
-    # Responses side to avoid breaking SDK clients that always send it.
+    # only known fields. Llama-server doesn't implement parallel_tool_calls
+    # semantics, so accept-and-ignore it on the Responses side to avoid breaking
+    # SDK clients that always send it.
     return req
 
 
@@ -4219,9 +4180,8 @@ def _chat_tool_calls_to_responses_output(tool_calls: list[dict]) -> list[dict]:
     """Map Chat Completions ``tool_calls`` into Responses ``function_call`` output items.
 
     The Chat Completions id (``call_xxx``) is the shared correlation key across
-    turns in the OpenAI Responses API — it is stored as ``call_id`` on the
-    output item and must be echoed back by the client as
-    ``function_call_output.call_id`` on the next turn.
+    turns in the Responses API -- stored as ``call_id`` on the output item and
+    echoed back by the client as ``function_call_output.call_id`` next turn.
     """
     items: list[dict] = []
     for tc in tool_calls:
@@ -4246,7 +4206,7 @@ async def _responses_non_streaming(
     chat_req = _build_chat_request(payload, messages, stream = False)
     result = await openai_chat_completions(chat_req, request)
 
-    # openai_chat_completions returns a JSONResponse for non-streaming
+    # openai_chat_completions returns a JSONResponse for non-streaming.
     if isinstance(result, JSONResponse):
         body = json.loads(result.body.decode())
     elif isinstance(result, Response):
@@ -4269,10 +4229,9 @@ async def _responses_non_streaming(
     resp_id = f"resp_{uuid.uuid4().hex[:12]}"
 
     # Responses API emits each tool call as its own top-level output item,
-    # alongside an optional assistant text message. Emit the text message
-    # only when the model actually produced content, so clients that expect
-    # a pure tool-call turn (finish_reason="tool_calls") don't see a spurious
-    # empty message item.
+    # plus an optional assistant text message. Emit the text message only when
+    # the model produced content, so clients expecting a pure tool-call turn
+    # (finish_reason="tool_calls") don't see a spurious empty message item.
     output_items: list[dict] = []
     if text:
         msg_id = f"msg_{uuid.uuid4().hex[:12]}"
@@ -4311,24 +4270,23 @@ async def _responses_stream(
     """Handle a streaming Responses API call, emitting named SSE events.
 
     For GGUF models the request goes directly to llama-server's
-    ``/v1/chat/completions`` endpoint from inside the StreamingResponse
-    child task — a single httpx lifecycle, a single async generator.
-    Wrapping the existing ``openai_chat_completions`` pass-through (which
-    already does its own httpx lifecycle) stacks two generators: Python
-    3.13 + httpcore 1.0.x then loses the close-propagation chain on the
-    innermost ``HTTP11ConnectionByteStream`` at asyncgen finalisation,
-    tripping "Attempted to exit cancel scope in a different task" /
-    "async generator ignored GeneratorExit". The direct path avoids that
-    altogether. Non-GGUF falls back to the wrapper (which doesn't use
-    httpx, so the issue doesn't apply).
+    ``/v1/chat/completions`` from inside the StreamingResponse child task -- one
+    httpx lifecycle, one async generator. Wrapping the existing
+    ``openai_chat_completions`` pass-through (which has its own httpx lifecycle)
+    stacks two generators: Python 3.13 + httpcore 1.0.x then loses the
+    close-propagation chain on the innermost ``HTTP11ConnectionByteStream`` at
+    asyncgen finalisation, tripping "Attempted to exit cancel scope in a
+    different task" / "async generator ignored GeneratorExit". The direct path
+    avoids that. Non-GGUF falls back to the wrapper (which doesn't use httpx, so
+    the issue doesn't apply).
 
     Text deltas arrive as ``response.output_text.delta`` on a single
     ``message`` output item at ``output_index=0``. Each tool call from
     ``delta.tool_calls[]`` is promoted to its own top-level ``function_call``
-    output item (one per distinct ``tool_calls[].index``), and relayed as
+    output item (one per distinct ``tool_calls[].index``) and relayed as
     ``response.function_call_arguments.delta`` / ``.done`` events so clients
-    (Codex, OpenAI Python SDK) can reconstruct the call incrementally and
-    reply with a ``function_call_output`` item on the next turn.
+    (Codex, OpenAI Python SDK) can reconstruct the call incrementally and reply
+    with a ``function_call_output`` item next turn.
     """
     resp_id = f"resp_{uuid.uuid4().hex[:12]}"
     msg_id = f"msg_{uuid.uuid4().hex[:12]}"
@@ -4338,13 +4296,12 @@ async def _responses_stream(
 
     llama_backend = get_llama_cpp_backend()
     if not llama_backend.is_loaded:
-        # The direct pass-through is GGUF-only. Non-GGUF /v1/responses
-        # streaming isn't a Codex-compatible path today and wrapping the
-        # transformers backend's streaming generator here would re-
-        # introduce the double-layer asyncgen close pattern that produces
-        # "Attempted to exit cancel scope in a different task" on Python
-        # 3.13. Surface a typed 400 so the client sees a useful error
-        # instead of a dangling stream.
+        # The direct pass-through is GGUF-only. Non-GGUF /v1/responses streaming
+        # isn't a Codex-compatible path today, and wrapping the transformers
+        # backend's streaming generator here would re-introduce the
+        # double-layer asyncgen close pattern that produces "Attempted to exit
+        # cancel scope in a different task" on Python 3.13. Surface a typed 400
+        # so the client sees a useful error instead of a dangling stream.
         raise HTTPException(
             status_code = 400,
             detail = (
@@ -4371,8 +4328,8 @@ async def _responses_stream(
         full_text = ""
         input_tokens = 0
         output_tokens = 0
-        # Per-tool-call state keyed by the Chat Completions `tool_calls[].index`
-        # which stays stable across chunks for the same call. Values are:
+        # Per-tool-call state keyed by Chat Completions `tool_calls[].index`,
+        # stable across chunks for the same call. Values:
         #   {output_index, item_id, call_id, name, arguments, opened}
         tool_call_state: dict[int, dict] = {}
         # Text message lives at output_index 0; tool calls claim 1, 2, ...
@@ -4426,11 +4383,11 @@ async def _responses_stream(
         yield f"event: response.content_part.added\ndata: {json.dumps({'type': 'response.content_part.added', 'item_id': msg_id, 'output_index': 0, 'content_index': 0, 'part': content_part})}\n\n"
 
         # ── Direct httpx lifecycle to llama-server ──
-        # Full same-task open + close, identical pattern to
-        # _openai_passthrough_stream and _anthropic_passthrough_stream:
-        # no `async with`, explicit aclose of lines_iter BEFORE resp /
-        # client so the innermost httpcore byte stream is finalised in
-        # this task (not via Python's asyncgen GC in a sibling task).
+        # Full same-task open + close, same pattern as
+        # _openai_passthrough_stream and _anthropic_passthrough_stream: no
+        # `async with`, explicit aclose of lines_iter BEFORE resp / client so
+        # the innermost httpcore byte stream is finalised in this task (not via
+        # the asyncgen GC in a sibling task).
         client = httpx.AsyncClient(timeout = 600)
         resp = None
         lines_iter = None
@@ -4496,7 +4453,7 @@ async def _responses_stream(
                     st = tool_call_state.get(idx)
                     fn = tc.get("function") or {}
                     if st is None:
-                        # First chunk for this tool call — allocate an
+                        # First chunk for this tool call -- allocate an
                         # output_index and emit output_item.added.
                         st = {
                             "output_index": next_output_index,
@@ -4509,8 +4466,8 @@ async def _responses_stream(
                         next_output_index += 1
                         tool_call_state[idx] = st
                     else:
-                        # Later chunks sometimes carry the id/name only
-                        # once; merge when present.
+                        # Later chunks sometimes carry id/name only once; merge
+                        # when present.
                         if tc.get("id") and not st["call_id"]:
                             st["call_id"] = tc["id"]
                         if fn.get("name") and not st["name"]:
@@ -4543,9 +4500,9 @@ async def _responses_stream(
                         }
                         yield f"event: response.function_call_arguments.delta\ndata: {json.dumps(args_delta_event)}\n\n"
                     elif arg_delta:
-                        # Buffer the args until we can open the item
-                        # (id/name arrive in the same chunk as the first
-                        # arg delta for some models — but if not, stash).
+                        # Buffer args until we can open the item (some models
+                        # send id/name in the same chunk as the first arg delta;
+                        # if not, stash).
                         st["arguments"] += arg_delta
 
                 usage = chunk_data.get("usage")
@@ -4572,8 +4529,8 @@ async def _responses_stream(
 
         # ── Closing events for tool calls ──
         for st in sorted(tool_call_state.values(), key = lambda s: s["output_index"]):
-            # If id/name never arrived (malformed upstream), synthesise so
-            # the client still sees a coherent frame sequence.
+            # If id/name never arrived (malformed upstream), synthesise so the
+            # client still sees a coherent frame sequence.
             if not st["opened"]:
                 if not st["call_id"]:
                     st["call_id"] = f"call_{uuid.uuid4().hex[:12]}"
@@ -4676,10 +4633,9 @@ async def openai_responses(
     """
     OpenAI Responses API endpoint.
 
-    Accepts the Responses-format request, converts it to a
-    ChatCompletionRequest internally, and returns a response
-    matching the OpenAI Responses API schema (output array,
-    input_tokens/output_tokens, named SSE events for streaming).
+    Accepts a Responses-format request, converts it to a ChatCompletionRequest
+    internally, and returns a response matching the Responses API schema
+    (output array, input_tokens/output_tokens, named SSE events for streaming).
     """
     messages = _normalise_responses_input(payload)
     if not messages:
@@ -4713,9 +4669,9 @@ def _anthropic_requested_studio_tools(tools: Optional[list]) -> set[str]:
         # Client tools always carry input_schema; server tools never do.
         if td.get("input_schema") is not None:
             continue
-        # Anthropic dispatches server tools by `type` (not by bare `name`);
-        # matching name too would let a malformed client tool like
-        # `{"name": "python"}` silently flip into server-execution mode.
+        # Anthropic dispatches server tools by `type`, not bare `name`; matching
+        # name too would let a malformed client tool like `{"name": "python"}`
+        # silently flip into server-execution mode.
         type_ = td.get("type")
         if isinstance(type_, str) and type_ in _STUDIO_ANTHROPIC_TOOL_ALIASES:
             requested.add(_STUDIO_ANTHROPIC_TOOL_ALIASES[type_])
@@ -4737,19 +4693,18 @@ def _select_anthropic_server_tools(
 
 
 def _normalize_anthropic_openai_images(openai_messages: list[dict], is_vision: bool) -> bool:
-    """Enforce the vision guard on translated Anthropic messages and
-    normalize any ``image_url`` parts with base64 data URLs to PNG.
+    """Enforce the vision guard on translated Anthropic messages and normalize
+    any base64-data-URL ``image_url`` parts to PNG.
 
     llama-server's stb_image only handles a few formats (JPEG/PNG/BMP/…);
-    Anthropic clients commonly send JPEG or WebP, and Claude Code sends
-    WebP. Re-encoding everything to PNG mirrors the behavior of
-    `_openai_messages_for_passthrough` / the GGUF branch of
-    `/v1/chat/completions` so the two endpoints agree.
+    Anthropic clients commonly send JPEG or WebP, and Claude Code sends WebP.
+    Re-encoding everything to PNG mirrors `_openai_messages_for_passthrough` /
+    the GGUF branch of `/v1/chat/completions` so the two endpoints agree.
 
-    Mutates ``openai_messages`` in place. Returns ``True`` when any
-    image part was seen (so the caller can skip a second scan). Raises
-    HTTPException(400) when images are present but the active model is
-    not a vision model, or when an image cannot be decoded.
+    Mutates ``openai_messages`` in place. Returns ``True`` when any image part
+    was seen (so the caller can skip a second scan). Raises HTTPException(400)
+    when images are present but the active model isn't a vision model, or when
+    an image cannot be decoded.
     """
     from PIL import Image
 
@@ -4815,10 +4770,10 @@ async def anthropic_messages(
     """
     Anthropic-compatible Messages API endpoint.
 
-    Translates Anthropic message format to internal OpenAI format, runs
-    through the existing agentic tool loop when tools are provided, and
-    returns responses in Anthropic Messages API format (streaming SSE or
-    non-streaming JSON).
+    Translates Anthropic message format to internal OpenAI format, runs through
+    the existing agentic tool loop when tools are provided, and returns
+    responses in Anthropic Messages API format (streaming SSE or non-streaming
+    JSON).
     """
     llama_backend = get_llama_cpp_backend()
     if not llama_backend.is_loaded:
@@ -4837,18 +4792,17 @@ async def anthropic_messages(
     )
     # Strip synthetic provider-side builtin tool history (web_search,
     # web_fetch, code_execution, image_generation cards tagged with
-    # _server_tool or extra_content.google.native_part) before handing
-    # off to local llama-server. The local /v1/chat/completions and
-    # GGUF passthrough builders apply the same strip; without it an
-    # Anthropic /v1/messages caller replaying a prior provider-side
-    # tool_use forwards fake builtin tool history to a backend that
-    # has no matching function declarations.
+    # _server_tool or extra_content.google.native_part) before handing off to
+    # local llama-server. The local /v1/chat/completions and GGUF passthrough
+    # builders apply the same strip; without it an Anthropic /v1/messages caller
+    # replaying a prior provider-side tool_use forwards fake builtin tool
+    # history to a backend with no matching function declarations.
     openai_messages = _strip_provider_synthetic_tool_history(
         _drop_empty_assistant_sentinels(openai_messages)
     )
 
-    # Enforce vision guard + re-encode embedded images to PNG so the
-    # Anthropic endpoint matches the behavior of /v1/chat/completions.
+    # Enforce vision guard + re-encode embedded images to PNG so the Anthropic
+    # endpoint matches /v1/chat/completions.
     _has_image = _normalize_anthropic_openai_images(openai_messages, llama_backend.is_vision)
 
     temperature = payload.temperature if payload.temperature is not None else 0.6
@@ -4861,9 +4815,8 @@ async def anthropic_messages(
     presence_penalty = payload.presence_penalty if payload.presence_penalty is not None else 0.0
     stop = payload.stop_sequences or None
 
-    # Translate Anthropic tool_choice to OpenAI format for forwarding to
-    # llama-server. Falls back to "auto" when unset or unrecognized, which
-    # matches the prior hardcoded behavior.
+    # Translate Anthropic tool_choice to OpenAI format for llama-server. Falls
+    # back to "auto" when unset or unrecognized (prior hardcoded behavior).
     openai_tool_choice = anthropic_tool_choice_to_openai(payload.tool_choice)
     if openai_tool_choice is None:
         openai_tool_choice = "auto"
@@ -4875,17 +4828,17 @@ async def anthropic_messages(
     # 1. enable_tools=true → server-side execution of built-in tools (Unsloth shorthand)
     # 2. tools=[...] only  → client-side pass-through (standard Anthropic behavior)
     # 3. neither           → plain chat
-    # Server-side agentic loop doesn't support multimodal input — matches
+    # The server-side agentic loop doesn't support multimodal input -- matches
     # the `not image_b64` gate in /v1/chat/completions.
     requested_studio_tools = _anthropic_requested_studio_tools(payload.tools)
 
-    # Reject malformed client tools at the boundary. AnthropicTool was
-    # relaxed to Optional[name]/Optional[input_schema] for server tools,
-    # so the converter silently drops incomplete entries — surface them
-    # as 400. A `type` field marks a server-tool declaration per spec
-    # (unrecognized server tools are accepted as no-ops); anything else
-    # without input_schema or name is malformed and must not be allowed
-    # to silently flip execution mode or disable tool calling.
+    # Reject malformed client tools at the boundary. AnthropicTool was relaxed
+    # to Optional[name]/Optional[input_schema] for server tools, so the
+    # converter silently drops incomplete entries -- surface them as 400. A
+    # `type` field marks a server-tool declaration per spec (unrecognized server
+    # tools are accepted as no-ops); anything else without input_schema or name
+    # is malformed and must not be allowed to silently flip execution mode or
+    # disable tool calling.
     for tool in payload.tools or []:
         td = tool if isinstance(tool, dict) else tool.model_dump()
         name, type_, schema = td.get("name"), td.get("type"), td.get("input_schema")
@@ -4900,17 +4853,17 @@ async def anthropic_messages(
                 detail = "Client tool is missing required field 'name'.",
             )
 
-    # Detect client tools from the raw payload (presence of input_schema)
-    # so the mixed-mode check below isn't fooled by a name collision with
-    # a server-tool alias that the post-filter would silently drop.
+    # Detect client tools from the raw payload (presence of input_schema) so the
+    # mixed-mode check below isn't fooled by a name collision with a server-tool
+    # alias that the post-filter would silently drop.
     _has_client_tool = any(
         (t if isinstance(t, dict) else t.model_dump()).get("input_schema") is not None
         for t in payload.tools or []
     )
 
-    # The server-tool agentic loop executes tools in-process and cannot
-    # relay unknown client functions back to the caller, so mixed requests
-    # would silently drop the client tools. Reject explicitly instead.
+    # The server-tool agentic loop executes tools in-process and can't relay
+    # unknown client functions back to the caller, so mixed requests would
+    # silently drop the client tools. Reject explicitly instead.
     if requested_studio_tools and _has_client_tool:
         raise HTTPException(
             status_code = 400,
@@ -4927,9 +4880,9 @@ async def anthropic_messages(
         if tool.get("function", {}).get("name") not in requested_studio_tools
     ]
 
-    # An Anthropic server-tool declaration implies server-tool mode, but
-    # only when tools aren't explicitly disabled (CLI --disable-tools or
-    # per-request enable_tools=false). Explicit False always wins.
+    # An Anthropic server-tool declaration implies server-tool mode, but only
+    # when tools aren't explicitly disabled (CLI --disable-tools or per-request
+    # enable_tools=false). Explicit False always wins.
     _enable = _effective_enable_tools(payload)
     server_tools = (
         (_enable or (_enable is None and bool(requested_studio_tools)))
@@ -4991,7 +4944,7 @@ async def anthropic_messages(
             payload.enabled_tools,
         )
 
-        # Build tool-use system prompt nudge (same logic as /chat/completions)
+        # Build tool-use system prompt nudge (same as /chat/completions)
         _tool_names = {t["function"]["name"] for t in openai_tools}
         _has_web = "web_search" in _tool_names
         _has_code = "python" in _tool_names or "terminal" in _tool_names
@@ -5205,15 +5158,14 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
     """Non-streaming response for the tool-calling path.
 
     Builds ``content_blocks`` in generation order (text → tool_use → text →
-    tool_use → ...), mirroring the streaming emitter's behavior. Deltas
-    within a single synthesis turn are merged into the trailing text block;
-    tool_use blocks interrupt the text sequence and open a new text block on
-    the next content event.
+    tool_use → ...), mirroring the streaming emitter. Deltas within one
+    synthesis turn merge into the trailing text block; tool_use blocks interrupt
+    the text sequence and open a new text block on the next content event.
 
     ``prev_text`` is reset on ``tool_end`` because
     ``generate_chat_completion_with_tools`` yields cumulative content *per
-    turn* — the first content event of turn N+1 must diff against an empty
-    baseline, not against turn N's final length.
+    turn* -- the first content event of turn N+1 must diff against an empty
+    baseline, not turn N's final length.
     """
     content_blocks: list = []
     tool_blocks_by_id: dict[str, AnthropicResponseToolUseBlock] = {}
@@ -5344,20 +5296,20 @@ def _build_passthrough_payload(
     if min_p is not None:
         body["min_p"] = min_p
     if repetition_penalty is not None:
-        # llama-server's field is "repeat_penalty", not "repetition_penalty"
+        # llama-server's field is "repeat_penalty", not "repetition_penalty".
         body["repeat_penalty"] = repetition_penalty
     if presence_penalty is not None:
         body["presence_penalty"] = presence_penalty
     if response_format is not None:
-        # llama-server applies a GBNF grammar derived from the JSON schema
-        # when response_format is present. Field is documented flat at the
-        # request root (tools/server/README.md), which is also what the
-        # OpenAI SDK produces by spreading extra_body into the body top.
+        # llama-server applies a GBNF grammar derived from the JSON schema when
+        # response_format is present. The field is documented flat at the
+        # request root (tools/server/README.md), which is also what the OpenAI
+        # SDK produces by spreading extra_body into the body top.
         body["response_format"] = response_format
     if chat_template_kwargs is not None:
-        # Propagate reasoning / template overrides (e.g. enable_thinking)
-        # so llama-server renders the Jinja template in the mode the caller
-        # asked for instead of whatever default the model was loaded with.
+        # Propagate reasoning / template overrides (e.g. enable_thinking) so
+        # llama-server renders the Jinja template in the caller's mode instead
+        # of the model's load-time default.
         body["chat_template_kwargs"] = chat_template_kwargs
     return body
 
@@ -5383,7 +5335,7 @@ async def _anthropic_passthrough_stream(
     cancel_id = None,
 ):
     """Streaming client-side pass-through: forward tools to llama-server and
-    translate its streaming response to Anthropic SSE without executing anything."""
+    translate its stream to Anthropic SSE without executing anything."""
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
     body = _build_passthrough_payload(
         openai_messages,
@@ -5401,8 +5353,8 @@ async def _anthropic_passthrough_stream(
         backend_ctx = llama_backend.context_length,
     )
 
-    # cancel_id mirrors the OpenAI passthrough so a per-run cancel POST
-    # works without the caller having to know the local message_id.
+    # cancel_id mirrors the OpenAI passthrough so a per-run cancel POST works
+    # without the caller knowing the local message_id.
     _tracker = _TrackedCancel(cancel_event, cancel_id, session_id, message_id)
     _tracker.__enter__()
 
@@ -5412,32 +5364,28 @@ async def _anthropic_passthrough_stream(
             yield line
 
         # Manage the httpx client, response, AND the aiter_lines() async
-        # generator MANUALLY — no `async with`, no anonymous iterator.
+        # generator MANUALLY -- no `async with`, no anonymous iterator.
         #
         # On Python 3.13 + httpcore 1.0.x, `async for raw_line in
-        # resp.aiter_lines():` creates an anonymous async generator. When
-        # the loop exits via `break` (or the generator is orphaned when a
-        # client disconnects mid-stream), Python's `async for` protocol
-        # does NOT auto-close the iterator the way a sync `for` loop
-        # would. The iterator remains reachable only from the current
-        # coroutine frame; once `_stream()` returns, the frame is GC'd
-        # and the iterator becomes unreachable. Python's asyncgen
-        # finalizer hook then runs its aclose() on a LATER GC pass in a
-        # DIFFERENT asyncio task, where httpcore's
-        # `HTTP11ConnectionByteStream.aclose()` enters
-        # `anyio.CancelScope.__exit__` with a mismatched task and prints
-        # `RuntimeError: Attempted to exit cancel scope in a different
-        # task` / `RuntimeError: async generator ignored GeneratorExit`
-        # as "Exception ignored in:" unraisable warnings.
+        # resp.aiter_lines():` creates an anonymous async generator. When the
+        # loop exits via `break` (or the generator is orphaned by a mid-stream
+        # client disconnect), `async for` does NOT auto-close the iterator like
+        # a sync `for` would. The iterator stays reachable only from the current
+        # coroutine frame; once `_stream()` returns, the frame is GC'd and the
+        # iterator becomes unreachable. The asyncgen finalizer then runs aclose()
+        # on a LATER GC pass in a DIFFERENT asyncio task, where httpcore's
+        # `HTTP11ConnectionByteStream.aclose()` enters `anyio.CancelScope.__exit__`
+        # with a mismatched task and prints `RuntimeError: Attempted to exit
+        # cancel scope in a different task` / `RuntimeError: async generator
+        # ignored GeneratorExit` as "Exception ignored in:" unraisable warnings.
         #
-        # The fix: save `resp.aiter_lines()` as `lines_iter`, and in the
-        # finally block explicitly `await lines_iter.aclose()` BEFORE
-        # `resp.aclose()` / `client.aclose()`. This closes the iterator
-        # inside our own task's event loop, so the internal httpcore
-        # byte-stream is cleaned up before Python's asyncgen finalizer
-        # has anything orphaned to finalize. Each aclose is wrapped in
-        # `try: ... except Exception: pass` so anyio cleanup noise from
-        # nested aclose paths can't bubble out.
+        # Fix: save `resp.aiter_lines()` as `lines_iter`, and in finally
+        # explicitly `await lines_iter.aclose()` BEFORE `resp.aclose()` /
+        # `client.aclose()`. This closes the iterator in our own task's event
+        # loop, cleaning up the httpcore byte-stream before the asyncgen
+        # finalizer has anything orphaned to finalize. Each aclose is wrapped in
+        # `try: ... except Exception: pass` so nested anyio cleanup noise can't
+        # bubble out.
         client = httpx.AsyncClient(
             timeout = 600,
             limits = httpx.Limits(max_keepalive_connections = 0),
@@ -5449,10 +5397,10 @@ async def _anthropic_passthrough_stream(
             req = client.build_request("POST", target_url, json = body)
             resp = await client.send(req, stream = True)
 
-            # See _openai_passthrough_stream for rationale: aiter_lines()
-            # blocks during llama-server prefill, so the in-loop cancel
-            # check is unreachable until the first SSE chunk arrives.
-            # The watcher closes `resp` on cancel, raising in aiter_lines.
+            # See _openai_passthrough_stream for rationale: aiter_lines() blocks
+            # during llama-server prefill, so the in-loop cancel check is
+            # unreachable until the first SSE chunk arrives. The watcher closes
+            # `resp` on cancel, raising in aiter_lines.
             cancel_watcher = asyncio.create_task(_await_cancel_then_close(cancel_event, resp))
             lines_iter = resp.aiter_lines()
             async for raw_line in lines_iter:
@@ -5629,19 +5577,18 @@ _LOCAL_SERVER_BUILTIN_TOOL_NAMES = frozenset(
 
 
 def _strip_provider_synthetic_tool_history(messages: list[dict]) -> list[dict]:
-    """Drop synthetic provider-side tool_calls + matching role=tool replies
-    on the local-backend (llama-server / GGUF) dispatch path.
+    """Drop synthetic provider-side tool_calls + matching role=tool replies on
+    the local-backend (llama-server / GGUF) dispatch path.
 
     A Gemini chat that ran code_execution / image_generation persists the
-    server-side tool card into thread history as an assistant tool_calls
-    entry tagged with ``args._server_tool`` (or a Gemini
-    ``args.google.native_part`` payload) plus a follow-up role=tool reply.
-    When the user switches the SAME thread to a local GGUF model, those
-    synthetic tool_calls are not real user functions, llama-server has no
-    matching declaration, and Gemini-only ``extra_content`` /
-    ``native_part`` payloads are meaningless. Forward only ordinary user
-    function calls; strip the matched role=tool replies too so the
-    backend does not see an orphan tool_call_id.
+    server-side tool card into history as an assistant tool_calls entry tagged
+    with ``args._server_tool`` (or a Gemini ``args.google.native_part`` payload)
+    plus a follow-up role=tool reply. When the user switches the SAME thread to
+    a local GGUF model, those synthetic tool_calls aren't real user functions,
+    llama-server has no matching declaration, and Gemini-only ``extra_content``
+    / ``native_part`` payloads are meaningless. Forward only ordinary user
+    function calls; strip the matched role=tool replies too so the backend never
+    sees an orphan tool_call_id.
     """
     dropped_ids: set[str] = set()
     sanitized_assistant: list[dict] = []
@@ -5653,12 +5600,10 @@ def _strip_provider_synthetic_tool_history(messages: list[dict]) -> list[dict]:
         if not isinstance(tool_calls, list) or not tool_calls:
             # Plain text Gemini reply: still strip message-level
             # `extra_content` (carries `google.thought_signature` replay
-            # metadata) so a text-only Gemini turn switched to a local
-            # GGUF backend does not leak Gemini-only fields to
-            # llama-server. ChatMessage previously did not have
-            # `extra_content`, so the field was implicitly dropped --
-            # round-22 added it to ChatMessage, which is what made this
-            # leak possible.
+            # metadata) so a text-only Gemini turn switched to a local GGUF
+            # backend doesn't leak Gemini-only fields to llama-server.
+            # ChatMessage didn't used to have `extra_content` (implicitly
+            # dropped); round-22 added it, which made this leak possible.
             if "extra_content" in m:
                 m = {k: v for k, v in m.items() if k != "extra_content"}
             sanitized_assistant.append(m)
@@ -5694,14 +5639,14 @@ def _strip_provider_synthetic_tool_history(messages: list[dict]) -> list[dict]:
                     if isinstance(tc_id, str) and tc_id:
                         dropped_ids.add(tc_id)
                     continue
-            # Strip Gemini-only `extra_content` on real user tool_calls
-            # too — llama-server has no use for it and may pass it
-            # through to the model unchanged.
+            # Strip Gemini-only `extra_content` on real user tool_calls too --
+            # llama-server has no use for it and may pass it to the model
+            # unchanged.
             if "extra_content" in tc:
                 tc = {k: v for k, v in tc.items() if k != "extra_content"}
             cleaned.append(tc)
-        # Drop top-level message-level `extra_content` (Gemini
-        # thoughtSignature replay metadata) on local dispatch.
+        # Drop message-level `extra_content` (Gemini thoughtSignature replay
+        # metadata) on local dispatch.
         m_clean = {k: v for k, v in m.items() if k != "extra_content"}
         if cleaned:
             m_clean["tool_calls"] = cleaned
@@ -5729,17 +5674,16 @@ def _openai_messages_for_passthrough(payload) -> list[dict]:
     """Build OpenAI-format message dicts for the /v1/chat/completions
     passthrough path.
 
-    Messages from ``payload.messages`` are dumped through Pydantic (dropping
-    unset optional fields) so they are already in standard OpenAI format
-    — including ``role="tool"`` tool-result messages and assistant messages
-    that carry structured ``tool_calls``. Content-parts images already in
-    the message list are left untouched.
+    ``payload.messages`` are dumped through Pydantic (dropping unset optional
+    fields), so they're already standard OpenAI format -- including
+    ``role="tool"`` tool-result messages and assistant messages carrying
+    structured ``tool_calls``. Content-parts images already in the list are
+    left untouched.
 
     When a client uses Studio's legacy ``image_base64`` top-level field, the
     image is re-encoded to PNG (llama-server's stb_image has limited format
-    support) and spliced into the last user message as an OpenAI
-    ``image_url`` content part so vision + function-calling requests work
-    transparently.
+    support) and spliced into the last user message as an OpenAI ``image_url``
+    content part so vision + function-calling requests work transparently.
     """
     messages = _strip_provider_synthetic_tool_history(
         _drop_empty_assistant_sentinels([m.model_dump(exclude_none = True) for m in payload.messages])
@@ -5787,9 +5731,9 @@ def _openai_messages_for_passthrough(payload) -> list[dict]:
 def _openai_messages_for_gguf_chat(payload, is_vision: bool) -> tuple[list[dict], bool]:
     """Build llama-server messages for the standard GGUF chat path.
 
-    llama-server accepts OpenAI multimodal content parts directly. Preserve
-    all per-turn ``image_url`` parts so multi-image chat history keeps each
-    image attached to its original turn.
+    llama-server accepts OpenAI multimodal content parts directly. Preserve all
+    per-turn ``image_url`` parts so multi-image chat history keeps each image
+    attached to its original turn.
     """
     messages = _strip_provider_synthetic_tool_history(
         _drop_empty_assistant_sentinels([m.model_dump(exclude_none = True) for m in payload.messages])
@@ -5827,10 +5771,10 @@ def _openai_messages_for_gguf_chat(payload, is_vision: bool) -> tuple[list[dict]
 
 def _extract_response_format(payload):
     """Return the ``response_format`` field on an incoming ChatCompletionRequest
-    (or None). The model is declared with ``extra="allow"`` so pydantic stashes
-    unknown top-level fields in ``model_extra``; OpenAI-SDK clients spread
-    ``extra_body`` into the request body top level, which is where guided-
-    decoding recipes park their JSON-schema response_format.
+    (or None). The model uses ``extra="allow"`` so pydantic stashes unknown
+    top-level fields in ``model_extra``; OpenAI-SDK clients spread ``extra_body``
+    into the request body top level, where guided-decoding recipes park their
+    JSON-schema response_format.
     """
     extra = getattr(payload, "model_extra", None)
     if not isinstance(extra, dict):
@@ -5842,15 +5786,15 @@ def _extract_response_format(payload):
 def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
     """Assemble the llama-server request body from a ChatCompletionRequest.
 
-    Only explicitly-known OpenAI / llama-server fields are forwarded so that
-    Studio-specific extensions (``enable_tools``, ``enabled_tools``,
-    ``session_id``, ...) never leak to the backend.
+    Only known OpenAI / llama-server fields are forwarded, so Studio-specific
+    extensions (``enable_tools``, ``enabled_tools``, ``session_id``, ...) never
+    leak to the backend.
     """
     messages = _openai_messages_for_passthrough(payload)
     tool_choice = payload.tool_choice if payload.tool_choice is not None else "auto"
-    # When the caller asked for a specific reasoning mode, forward it to
-    # llama-server via chat_template_kwargs so the Jinja template renders
-    # with (or without) the reasoning preamble.
+    # When the caller asked for a specific reasoning mode, forward it via
+    # chat_template_kwargs so the Jinja template renders with (or without) the
+    # reasoning preamble.
     tpl_kwargs = None
     if payload.enable_thinking is not None:
         tpl_kwargs = {"enable_thinking": bool(payload.enable_thinking)}
@@ -5879,10 +5823,10 @@ async def _openai_passthrough_stream(
     """Streaming client-side pass-through for /v1/chat/completions.
 
     Forwards the client's OpenAI function-calling request to llama-server and
-    relays the SSE stream back verbatim. This preserves llama-server's
-    native response ``id``, ``finish_reason`` (including ``"tool_calls"``),
-    ``delta.tool_calls``, and the trailing ``usage`` chunk so the client
-    observes a standard OpenAI response.
+    relays the SSE stream back verbatim, preserving llama-server's native
+    response ``id``, ``finish_reason`` (including ``"tool_calls"``),
+    ``delta.tool_calls``, and the trailing ``usage`` chunk so the client sees a
+    standard OpenAI response.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
     body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
@@ -5891,14 +5835,13 @@ async def _openai_passthrough_stream(
     _tracker = _TrackedCancel(cancel_event, *_cancel_keys)
     _tracker.__enter__()
 
-    # Outer guard: asyncio.CancelledError at `await client.send(...)` is
-    # a BaseException that bypasses `except httpx.RequestError`; without
-    # this the tracker leaks. The generator's finally only runs once
-    # iteration starts.
+    # Outer guard: asyncio.CancelledError at `await client.send(...)` is a
+    # BaseException that bypasses `except httpx.RequestError`; without this the
+    # tracker leaks. The generator's finally only runs once iteration starts.
     try:
-        # Dispatch BEFORE returning StreamingResponse so transport errors
-        # and non-200 upstream statuses surface as real HTTP errors --
-        # OpenAI SDKs rely on status codes to raise APIError/BadRequestError.
+        # Dispatch BEFORE returning StreamingResponse so transport errors and
+        # non-200 upstream statuses surface as real HTTP errors -- OpenAI SDKs
+        # rely on status codes to raise APIError/BadRequestError.
         client = httpx.AsyncClient(
             timeout = 600,
             limits = httpx.Limits(max_keepalive_connections = 0),
@@ -5908,7 +5851,7 @@ async def _openai_passthrough_stream(
             req = client.build_request("POST", target_url, json = body)
             resp = await client.send(req, stream = True)
         except httpx.RequestError as e:
-            # llama-server subprocess crashed / still starting / unreachable.
+            # llama-server subprocess crashed / starting / unreachable.
             logger.error("openai passthrough stream: upstream unreachable: %s", e)
             if resp is not None:
                 try:
@@ -5948,16 +5891,15 @@ async def _openai_passthrough_stream(
 
         async def _stream():
             # Same httpx lifecycle pattern as _anthropic_passthrough_stream:
-            # save resp.aiter_lines() so the finally block can aclose() it
-            # on our task. See that function for full rationale.
+            # save resp.aiter_lines() so the finally block can aclose() it on
+            # our task. See that function for full rationale.
             lines_iter = None
             # During llama-server prefill, `aiter_lines()` blocks until the
-            # first SSE chunk arrives. The in-loop `cancel_event` check
-            # cannot fire until then, which is the exact proxy/Colab
-            # scenario the cancel POST is meant to recover from. Run a
-            # tiny watcher that closes `resp` as soon as cancel fires,
-            # unblocking the iterator with a RemoteProtocolError caught
-            # in the except clause below.
+            # first SSE chunk arrives. The in-loop `cancel_event` check can't
+            # fire until then -- the exact proxy/Colab scenario the cancel POST
+            # recovers from. Run a tiny watcher that closes `resp` as soon as
+            # cancel fires, unblocking the iterator with a RemoteProtocolError
+            # caught in the except clause below.
             cancel_watcher = asyncio.create_task(_await_cancel_then_close(cancel_event, resp))
             try:
                 lines_iter = resp.aiter_lines()
@@ -5977,12 +5919,12 @@ async def _openai_passthrough_stream(
                     if raw_line[6:].strip() == "[DONE]":
                         break
             except (httpx.RemoteProtocolError, httpx.ReadError, httpx.CloseError):
-                # Watcher closed resp on cancel. Emit nothing extra; the
-                # client either initiated the cancel or already disconnected.
+                # Watcher closed resp on cancel. Emit nothing extra; the client
+                # initiated the cancel or already disconnected.
                 if not cancel_event.is_set():
                     raise
             except Exception as e:
-                # 200 headers are already flushed; errors must be in the SSE body.
+                # 200 headers already flushed; errors must go in the SSE body.
                 logger.error("openai passthrough stream error: %s", e)
                 err = {
                     "error": {
@@ -6029,10 +5971,9 @@ async def _openai_passthrough_stream(
 async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
     """Non-streaming client-side pass-through for /v1/chat/completions.
 
-    Returns llama-server's JSON response verbatim (via JSONResponse) so the
-    client sees the native response ``id``, ``finish_reason`` (including
-    ``"tool_calls"``), structured ``tool_calls``, and accurate ``usage``
-    token counts.
+    Returns llama-server's JSON response verbatim so the client sees the native
+    response ``id``, ``finish_reason`` (including ``"tool_calls"``), structured
+    ``tool_calls``, and accurate ``usage`` token counts.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
     body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
@@ -6041,9 +5982,9 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
         async with httpx.AsyncClient() as client:
             resp = await client.post(target_url, json = body, timeout = 600)
     except httpx.RequestError as e:
-        # llama-server subprocess crashed / still starting / unreachable.
-        # Surface the same friendly message the sync chat path emits so
-        # operators don't see a bare 500 with no diagnostic.
+        # llama-server subprocess crashed / starting / unreachable. Surface the
+        # same friendly message the sync chat path emits so operators don't see
+        # a bare 500 with no diagnostic.
         logger.error("openai passthrough non-streaming: upstream unreachable: %s", e)
         raise HTTPException(
             status_code = 502,
@@ -6056,12 +5997,11 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
             detail = f"llama-server error: {resp.text[:500]}",
         )
 
-    # Guided-decoding fence wrap. llama-server returns raw JSON that matches
-    # the schema (no surrounding markdown) because the GBNF grammar only
-    # emits the JSON object itself. data_designer's llm-structured parser
-    # looks for a ```json ... ``` markdown fence and discards unfenced
-    # output, which collapses a 100%-valid guided-decoding run to 0/N.
-    # Wrap each choice's content in the expected fence when the caller
+    # Guided-decoding fence wrap. llama-server returns raw JSON matching the
+    # schema (no markdown) since the GBNF grammar emits only the JSON object.
+    # data_designer's llm-structured parser looks for a ```json ... ``` fence
+    # and discards unfenced output, collapsing a 100%-valid guided-decoding run
+    # to 0/N. Wrap each choice's content in the expected fence when the caller
     # asked for guided decoding, leaving already-fenced content alone.
     if _extract_response_format(payload) is not None:
         try:
@@ -6084,15 +6024,14 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
             if changed:
                 return JSONResponse(content = data)
         except Exception as exc:
-            # Wrap is best-effort; fall through to the verbatim body if
-            # the response is not JSON-shaped or the structure is unusual.
+            # Wrap is best-effort; fall through to the verbatim body if the
+            # response isn't JSON-shaped or the structure is unusual.
             logger.warning(
                 "response_format fence wrap skipped: %s",
                 exc,
             )
 
-    # Pass the upstream body through as raw bytes — skips a redundant
-    # parse+re-serialize round-trip and keeps the response truly
-    # verbatim (matches the docstring). Status is guaranteed 200 by
-    # the check above.
+    # Pass the upstream body through as raw bytes -- skips a redundant
+    # parse+re-serialize round-trip and keeps the response truly verbatim
+    # (matches the docstring). Status is guaranteed 200 by the check above.
     return Response(content = resp.content, media_type = "application/json")
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index bf8550f583..1d8f73eb88 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -34,9 +34,9 @@ router = APIRouter()
 
 
 def _looks_like_command(value: str) -> bool:
-    """Whitespace is a one-way signal: a URL can't hold an unencoded space, so a
-    value with whitespace is definitely a command. No whitespace proves nothing
-    (a lone token may be a single-arg command or a scheme-less URL)."""
+    """Whitespace is a one-way signal: a URL can't hold an unencoded space, so
+    a value with whitespace is definitely a command. No whitespace proves
+    nothing (a lone token may be a single-arg command or a scheme-less URL)."""
     return any(ch.isspace() for ch in value)
 
 
@@ -46,8 +46,8 @@ def _validate_url(url: str) -> str:
         raise HTTPException(status_code = 400, detail = "url must not be empty")
     # When stdio is enabled on this host, a non-HTTP value is a local command.
     # Reuse this field so stdio servers ride the existing CRUD/storage with no
-    # schema change. A lone token (example.com, /usr/bin/srv) is ambiguous, so we
-    # keep the existing behaviour and treat any non-HTTP value as a command here.
+    # schema change. A lone token (example.com, /usr/bin/srv) is ambiguous, so
+    # keep existing behaviour and treat any non-HTTP value as a command here.
     if stdio_mcp_enabled() and is_stdio(trimmed):
         try:
             parts = parse_stdio_command(trimmed)
@@ -63,7 +63,7 @@ def _validate_url(url: str) -> str:
             raise HTTPException(status_code = 400, detail = "command must not be empty")
         if "://" in parts[0]:
             # A URL-scheme first token is a mistyped URL, not a command. Reject
-            # it cleanly instead of exec-ing it (mirrors the frontend check).
+            # cleanly instead of exec-ing it (mirrors the frontend check).
             raise HTTPException(
                 status_code = 400,
                 detail = "Enter an http(s):// URL, or a local command whose "
@@ -87,7 +87,7 @@ def _validate_url(url: str) -> str:
 
 
 def _normalize_headers(headers: dict[str, str] | None) -> dict[str, str] | None:
-    """Trim header names, drop empties, coerce values to str. None if nothing left."""
+    """Trim header names, drop empties, coerce values to str; None if empty."""
     if not headers:
         return None
     out: dict[str, str] = {}
@@ -126,7 +126,7 @@ async def create_mcp_server(
     url = _validate_url(payload.url)
     headers = _normalize_headers(payload.headers)
     # OAuth is HTTP-only; force it off for stdio commands so a stale flag can't
-    # push the probe onto the 305s OAuth timeout. Backend is the enforcer.
+    # push the probe onto the 305s OAuth timeout. Backend enforces this.
     use_oauth = payload.use_oauth and not is_stdio(url)
 
     server_id = uuid.uuid4().hex[:16]
@@ -182,7 +182,7 @@ async def update_mcp_server(
     if not changes:
         raise HTTPException(status_code = 400, detail = "No fields to update")
     # headers == HTTP headers (remote) or env vars (stdio). On a transport-type
-    # switch with no new headers, drop the old ones so env secrets are not
+    # switch with no new headers, drop the old ones so env secrets aren't
     # re-sent as HTTP headers (or vice versa).
     if (
         "url" in changes
@@ -190,9 +190,9 @@ async def update_mcp_server(
         and "headers_json" not in changes
     ):
         changes["headers_json"] = None
-    # Clear persisted OAuth tokens when the URL changes or OAuth is
-    # disabled; fastmcp keys tokens by URL and would otherwise let a
-    # re-pointed server silently inherit the old account's credentials.
+    # Clear persisted OAuth tokens when the URL changes or OAuth is disabled;
+    # fastmcp keys tokens by URL and would otherwise let a re-pointed server
+    # silently inherit the old account's credentials.
     if bool(old.get("use_oauth")) and (
         ("url" in changes and changes["url"] != old["url"]) or changes.get("use_oauth") is False
     ):
@@ -248,8 +248,8 @@ async def test_mcp_server(
     payload: McpServerTestRequest, current_subject: str = Depends(get_current_subject)
 ):
     # URL/header validation must surface as 400 like create/update so the
-    # frontend's create-form pre-flight gets the same error semantics as
-    # the actual save call. Only catch transport/timeout errors below.
+    # frontend's create-form pre-flight gets the same error semantics as the
+    # save call. Only catch transport/timeout errors below.
     url = _validate_url(payload.url)
     headers = _normalize_headers(payload.headers)
     try:
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 3871f579af..319330d428 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Model Management API routes
-"""
+"""Model management API routes."""
 
 import hashlib
 import json
@@ -28,14 +26,13 @@ def _is_valid_repo_id(repo_id: str) -> bool:
 
 
 def _safe_is_dir(path) -> bool:
-    """``Path.is_dir()`` that returns ``False`` instead of raising.
+    """``Path.is_dir()`` returning ``False`` instead of raising.
 
-    On Python >= 3.12 ``is_dir()``'s ``os.stat`` only suppresses
-    "not found"-class errors and now propagates ``PermissionError``
-    (EACCES); on Python <= 3.11 it returned ``False``. The folder-scan
-    endpoints probe well-known system locations (e.g. a root-owned,
-    mode-700 ``/usr/share/ollama/.ollama/models``) and must treat an
-    un-stat-able path as "not a directory", never 500.
+    Python >= 3.12's ``is_dir()`` propagates ``PermissionError``
+    (EACCES); <= 3.11 returned ``False``. Folder-scan endpoints probe
+    system locations (e.g. root-owned mode-700
+    ``/usr/share/ollama/.ollama/models``) and must treat an un-stat-able
+    path as "not a directory", never 500.
     """
     try:
         return Path(path).is_dir()
@@ -43,7 +40,7 @@ def _safe_is_dir(path) -> bool:
         return False
 
 
-# Add backend directory to path
+# Add backend dir to path
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
@@ -79,7 +76,7 @@ try:
         resolve_export_dir,
     )
 except ImportError:
-    # Fallback: try to import from parent directory
+    # Fallback: import from parent directory
     parent_backend = backend_path.parent / "backend"
     if str(parent_backend) not in sys.path:
         sys.path.insert(0, str(parent_backend))
@@ -167,15 +164,14 @@ def _resolve_hf_cache_dir() -> Path:
 def _is_model_directory(d: Path) -> bool:
     """Return ``True`` when *d* looks like a model directory.
 
-    A model directory must have **both** a config file (``config.json`` or
-    ``adapter_config.json``) **and** actual model weight files.  Both
-    conditions are required: a bare directory with only loose ``.gguf``
-    files (no config) might be a mixed collection, and a ``config.json``
-    alone (no weights) is not a model directory.
+    Requires **both** a config (``config.json`` or
+    ``adapter_config.json``) **and** weight files: loose ``.gguf`` files
+    without config may be a mixed collection, and config without weights
+    is not a model dir.
 
     Excludes ``mmproj`` GGUF files (vision projectors) and non-weight
-    ``.bin`` files (``tokenizer.bin``, ``vocab.bin``, etc.) from the
-    weight check to avoid false positives.
+    ``.bin`` files (``tokenizer.bin``, ``vocab.bin``, etc.) to avoid
+    false positives.
     """
 
     def _is_weight_file(f: Path) -> bool:
@@ -239,8 +235,8 @@ def _scan_models_dir(models_dir: Path, *, limit: int | None = None) -> List[Loca
                 or any(child.glob("*.gguf"))
             )
         except OSError:
-            # Skip individual children that are unreadable (permissions, broken
-            # symlinks, etc.) rather than failing the entire scan.
+            # Skip unreadable children (permissions, broken symlinks)
+            # rather than failing the whole scan.
             continue
         if not has_model_files:
             continue
@@ -257,7 +253,7 @@ def _scan_models_dir(models_dir: Path, *, limit: int | None = None) -> List[Loca
                 updated_at = updated_at,
             ),
         )
-    # Also scan for standalone .gguf files directly in the models directory
+    # Also scan standalone .gguf files in the models directory
     if limit is None or len(found) < limit:
         for gguf_file in models_dir.glob("*.gguf"):
             if limit is not None and len(found) >= limit:
@@ -315,16 +311,16 @@ def _scan_hf_cache(cache_dir: Path) -> List[LocalModelInfo]:
 def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
     """Scan an LM Studio models directory for model files.
 
-    LM Studio uses a ``publisher/model-name`` folder structure containing
-    GGUF files, or standalone GGUF files at the top level.
+    LM Studio uses a ``publisher/model-name`` folder structure with GGUF
+    files, or standalone GGUF files at the top level.
     """
     if not lm_dir.exists() or not lm_dir.is_dir():
         return []
 
-    # If the directory itself is a model directory (has config AND weight
-    # files), it is not an LM Studio publisher structure -- return it as a
-    # single model entry.  We cannot skip it silently because this function
-    # is the only scanner called for default LM Studio roots.
+    # If lm_dir is itself a model directory (config AND weights), it's
+    # not an LM Studio publisher structure -- return it as a single
+    # entry. Can't skip it silently: this is the only scanner called for
+    # default LM Studio roots.
     if _is_model_directory(lm_dir):
         try:
             updated_at = lm_dir.stat().st_mtime
@@ -360,9 +356,9 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
                     )
                 continue
 
-            # If the child directory itself looks like a model directory
-            # (has config AND weight files), surface it directly instead
-            # of descending into it as a publisher.
+            # If the child looks like a model directory (config AND
+            # weights), surface it directly instead of descending into
+            # it as a publisher.
             if _is_model_directory(child):
                 try:
                     updated_at = child.stat().st_mtime
@@ -379,7 +375,7 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
                 )
                 continue
 
-            # child is a publisher directory -- scan its sub-directories
+            # child is a publisher directory -- scan its subdirectories
             for model_dir in child.iterdir():
                 try:
                     if model_dir.is_dir():
@@ -430,11 +426,11 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
 def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
     """Return a writable directory for Ollama ``.gguf`` symlinks.
 
-    Prefers ``<ollama_dir>/.studio_links/`` so the links sit next to the
-    blobs they point at. Falls back to a per-ollama-dir namespace under
-    Studio's own cache when the models directory is read-only (common
-    for system installs under ``/usr/share/ollama`` or ``/var/lib/ollama``)
-    so we still surface Ollama models in those environments.
+    Prefers ``<ollama_dir>/.studio_links/`` so links sit next to their
+    blobs. Falls back to a per-ollama-dir namespace under Studio's cache
+    when the models dir is read-only (common for system installs under
+    ``/usr/share/ollama`` or ``/var/lib/ollama``) so Ollama models still
+    surface there.
     """
     from utils.paths.storage_roots import cache_root
 
@@ -449,9 +445,8 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
             e,
         )
 
-    # Fallback: namespace by a hash of the ollama_dir so two different
-    # Ollama roots don't collide. This is a cache path, not a security
-    # boundary.
+    # Fallback: namespace by a hash of ollama_dir so two Ollama roots
+    # don't collide. Cache path, not a security boundary.
     try:
         digest = hashlib.sha256(str(ollama_dir.resolve()).encode()).hexdigest()[:12]
     except OSError:
@@ -472,34 +467,29 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
 def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[LocalModelInfo]:
     """Scan an Ollama models directory for downloaded models.
 
-    Ollama stores models in a content-addressable layout::
+    Ollama uses a content-addressable layout::
 
         <ollama_dir>/manifests/<host>/<namespace>/<model>/<tag>
         <ollama_dir>/blobs/sha256-...
 
-    The default host is ``registry.ollama.ai`` with namespace
-    ``library`` (official models), but users can pull from custom
-    namespaces (``mradermacher/llama3``) or entirely different hosts
-    (``hf.co/org/repo:tag``).  We iterate all manifest files via
-    ``rglob`` so every layout depth is discovered.
+    Default host is ``registry.ollama.ai`` namespace ``library``
+    (official), but users can pull from custom namespaces
+    (``mradermacher/llama3``) or other hosts (``hf.co/org/repo:tag``).
+    We ``rglob`` all manifest files so every layout depth is found.
 
-    Each manifest is JSON with a ``layers`` array. The layer with
-    ``mediaType == "application/vnd.ollama.image.model"`` contains the
-    GGUF weights. Vision models also have a projector layer
-    (``application/vnd.ollama.image.projector``). We read the config
-    layer to extract family/size info.
+    Each manifest is JSON with a ``layers`` array. The
+    ``application/vnd.ollama.image.model`` layer holds the GGUF weights;
+    vision models add an ``application/vnd.ollama.image.projector``
+    layer. We read the config layer for family/size info.
 
-    Since Ollama blobs lack a ``.gguf`` extension (which the GGUF
-    loading pipeline requires), we create ``.gguf``-named links
-    pointing at the blobs so the existing ``detect_gguf_model`` and
-    ``llama-server -m`` paths work unchanged. Each model gets its
-    own subdirectory under the links dir (keyed by a short hash of
-    the manifest path) so that ``detect_mmproj_file`` only sees the
-    projector for *that* model.  Links are created as symlinks when
-    possible, falling back to hardlinks (Windows without Developer
-    Mode) as a last resort.  The link dir lives under
-    ``<ollama_dir>/.studio_links/`` when writable, otherwise under
-    Studio's own cache directory.
+    Ollama blobs lack the ``.gguf`` extension the loading pipeline
+    requires, so we create ``.gguf``-named links to them so
+    ``detect_gguf_model`` and ``llama-server -m`` work unchanged. Each
+    model gets its own subdir under the links dir (keyed by a short hash
+    of the manifest path) so ``detect_mmproj_file`` only sees that
+    model's projector. Links are symlinks when possible, falling back to
+    hardlinks (Windows without Developer Mode). The link dir is
+    ``<ollama_dir>/.studio_links/`` when writable, else Studio's cache.
     """
     manifests_root = ollama_dir / "manifests"
     if not manifests_root.is_dir():
@@ -518,10 +508,9 @@ def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[Loca
     def _make_link(link_dir: Path, link_name: str, target: Path) -> Optional[str]:
         """Create a .gguf-named link to an Ollama blob.
 
-        Tries symlink first, then hardlink (works on Windows without
-        Developer Mode when target is on the same filesystem).  Skips
-        the model if neither works -- a full file copy of a multi-GB
-        GGUF inside a synchronous API request would block the backend.
+        Tries symlink, then hardlink (Windows without Developer Mode,
+        same filesystem). Skips the model if neither works -- a full
+        multi-GB copy in a sync API request would block the backend.
 
         Idempotent: skips recreation when a valid link already exists.
         """
@@ -529,9 +518,9 @@ def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[Loca
         link_path = link_dir / link_name
         resolved = target.resolve()
 
-        # Skip if the link already points at the exact same blob.
-        # Only use samefile -- size-based checks can reuse stale links
-        # after `ollama pull` updates a tag to a same-sized blob.
+        # Skip if the link already points at the same blob. Use samefile
+        # only -- size checks can reuse stale links after `ollama pull`
+        # updates a tag to a same-sized blob.
         try:
             if link_path.exists() and os.path.samefile(str(link_path), str(resolved)):
                 return str(link_path)
@@ -700,9 +689,9 @@ async def list_local_models(
     hf_default = hf_default_cache_dir()
     lm_dirs = lmstudio_model_dirs()
 
-    # Validate models_dir against an allowlist of trusted directories.
-    # Only the trusted Path objects are used for filesystem access -- the
-    # user-supplied string is only used for matching, never for path construction.
+    # Validate models_dir against an allowlist of trusted dirs. Only the
+    # trusted Path objects are used for FS access; the user string is
+    # only used for matching, never for path construction.
     allowed_roots: list[Path] = [Path("./models").resolve(), hf_cache_dir]
     if legacy_hf.is_dir():
         allowed_roots.append(legacy_hf)
@@ -719,7 +708,7 @@ async def list_local_models(
     for root in allowed_roots:
         root_str = os.path.realpath(str(root))
         if requested == root_str or requested.startswith(root_str + os.sep):
-            models_root = root  # Use the trusted root, not the user-supplied path
+            models_root = root  # trusted root, not the user-supplied path
             break
     if models_root is None:
         raise HTTPException(
@@ -734,7 +723,7 @@ async def list_local_models(
         if legacy_hf.is_dir() and legacy_hf.resolve() != hf_cache_dir.resolve():
             local_models += _scan_hf_cache(legacy_hf)
 
-        # Scan HF system default cache (may differ when env vars are overridden)
+        # Scan HF system default cache (may differ under env overrides)
         if (
             hf_default.is_dir()
             and hf_default.resolve() != hf_cache_dir.resolve()
@@ -746,7 +735,7 @@ async def list_local_models(
         for lm_dir in lm_dirs:
             local_models += _scan_lmstudio_dir(lm_dir)
 
-        # Scan user-added custom folders (cap per-folder to avoid unbounded scans)
+        # Scan user-added custom folders (per-folder cap)
         from storage.studio_db import list_scan_folders
 
         _MAX_MODELS_PER_FOLDER = 200
@@ -758,9 +747,9 @@ async def list_local_models(
         for folder in custom_folders:
             folder_path = Path(folder["path"])
             try:
-                # Ollama scanner creates .studio_links/ with .gguf symlinks.
-                # Filter those from the generic scanners to avoid duplicates
-                # and leaking internal paths into the UI.
+                # Ollama scanner creates .studio_links/ with .gguf
+                # symlinks. Filter those from generic scanners to avoid
+                # duplicates and leaking internal paths into the UI.
                 _generic = [
                     m
                     for m in (
@@ -781,10 +770,10 @@ async def list_local_models(
                 continue
             local_models += [m.model_copy(update = {"source": "custom"}) for m in custom_models]
 
-        # Deduplicate models, but always keep custom folder entries so they
-        # appear in the "Custom Folders" UI section even when the same model
-        # also exists in the HF cache or default models directory.  Use a
-        # (id, source) key for custom entries to avoid collisions.
+        # Deduplicate, but always keep custom folder entries so they show
+        # in the "Custom Folders" UI section even when the same model is
+        # also in the HF cache or default models dir. Custom entries use
+        # an (id, source) key to avoid collisions.
         deduped: dict[str, LocalModelInfo] = {}
         for model in local_models:
             key = f"{model.id}\x00custom" if model.source == "custom" else model.id
@@ -855,11 +844,10 @@ async def remove_scan_folder_endpoint(
 async def get_recommended_folders(current_subject: str = Depends(get_current_subject)):
     """Return well-known model directories that exist on this machine.
 
-    Lightweight alternative to ``browse-folders`` for showing quick-pick
-    chips without the overhead of enumerating a directory tree.  Returns
-    paths that actually exist on disk (HF cache, LM Studio, Ollama,
-    ``~/models``, etc.) so the frontend can offer them as one-click
-    "Recommended" shortcuts in the Custom Folders section.
+    Lightweight alternative to ``browse-folders`` for quick-pick chips
+    without enumerating a directory tree. Returns paths that exist on
+    disk (HF cache, LM Studio, Ollama, ``~/models``, etc.) for the
+    frontend's one-click "Recommended" shortcuts.
     """
     from utils.paths.storage_roots import lmstudio_model_dirs
 
@@ -900,26 +888,25 @@ async def get_recommended_folders(current_subject: str = Depends(get_current_sub
     return {"folders": folders}
 
 
-# Heuristic ceiling on how many children to stat when checking whether a
-# directory "looks like" it contains models. Keeps the browser snappy
-# even when a directory has thousands of unrelated entries.
+# Max children to stat when checking if a directory "looks like" it
+# holds models. Keeps the browser snappy on dirs with thousands of
+# unrelated entries.
 _BROWSE_MODEL_HINT_PROBE = 64
-# Hard cap on how many subdirectory entries we send back. Pointing the
-# browser at something like ``/usr/lib`` or ``/proc`` must not stat-storm
-# the process or send tens of thousands of rows to the client.
+# Hard cap on subdirectory entries returned. Browsing ``/usr/lib`` or
+# ``/proc`` must not stat-storm the process or send tens of thousands of
+# rows to the client.
 _BROWSE_ENTRY_CAP = 2000
 
 
 def _count_model_files(directory: Path, cap: int = 200) -> int:
     """Count GGUF/safetensors files immediately inside *directory*.
-    Used to surface a count-hint on the response so the UI can tell
-    users that a leaf directory (no subdirs, only weights) is a valid
-    "Use this folder" target.
 
-    Bounded by *visited entries*, not by *match count*: in directories
-    with many non-model files (or many subdirectories) the scan still
-    stops after ``cap`` entries so a UI hint never costs more than a
-    bounded directory walk.
+    Surfaces a count-hint so the UI can mark a leaf directory (no
+    subdirs, only weights) as a valid "Use this folder" target.
+
+    Bounded by *visited entries*, not match count: the scan stops after
+    ``cap`` entries even in dirs full of non-model files/subdirs, so a UI
+    hint never costs more than a bounded directory walk.
     """
     n = 0
     visited = 0
@@ -945,10 +932,10 @@ def _count_model_files(directory: Path, cap: int = 200) -> int:
 
 
 def _has_direct_model_signal(directory: Path) -> bool:
-    """Return True if *directory* has an immediate child that signals
-    it holds a model: a GGUF/safetensors/config.json file, or a
-    `models--*` subdir (HF hub cache). Bounded by
-    ``_BROWSE_MODEL_HINT_PROBE`` to stay fast."""
+    """Return True if *directory* has an immediate child signalling a
+    model: a GGUF/safetensors/config.json file, or a `models--*` subdir
+    (HF hub cache). Bounded by ``_BROWSE_MODEL_HINT_PROBE`` to stay
+    fast."""
     try:
         it = directory.iterdir()
     except OSError:
@@ -975,23 +962,22 @@ def _has_direct_model_signal(directory: Path) -> bool:
 
 
 def _looks_like_model_dir(directory: Path) -> bool:
-    """Bounded heuristic used by the folder browser to flag directories
-    worth exploring. False negatives are fine; the real scanner is
+    """Bounded heuristic to flag directories worth exploring in the
+    folder browser. False negatives are fine; the real scanner is
     authoritative.
 
     Three signals, cheapest first:
 
-    1. Directory name itself: ``models--*`` is the HuggingFace hub cache
-       layout (``blobs``/``refs``/``snapshots`` children wouldn't match
-       the file-level probes below).
-    2. An immediate child is a weight file or config (handled by
+    1. Directory name ``models--*`` (HuggingFace hub cache layout; its
+       ``blobs``/``refs``/``snapshots`` children wouldn't match the
+       file-level probes below).
+    2. An immediate child is a weight file or config (via
        :func:`_has_direct_model_signal`).
-    3. A grandchild has a direct signal -- this catches the
-       ``publisher/model/weights.gguf`` layout used by LM Studio and
-       Ollama. We probe at most the first
-       ``_BROWSE_MODEL_HINT_PROBE`` child directories, each of which is
-       checked with a bounded :func:`_has_direct_model_signal` call,
-       so the total cost stays O(PROBE^2) worst-case.
+    3. A grandchild has a direct signal -- catches the
+       ``publisher/model/weights.gguf`` layout of LM Studio and Ollama.
+       Probes at most the first ``_BROWSE_MODEL_HINT_PROBE`` child dirs,
+       each via a bounded :func:`_has_direct_model_signal`, so total cost
+       is O(PROBE^2) worst-case.
     """
     if directory.name.startswith("models--"):
         return True
@@ -1011,7 +997,7 @@ def _looks_like_model_dir(directory: Path) -> bool:
                     continue
             except OSError:
                 continue
-            # Fast name check first
+            # Fast name check first.
             if child.name.startswith("models--"):
                 return True
             if _has_direct_model_signal(child):
@@ -1022,16 +1008,15 @@ def _looks_like_model_dir(directory: Path) -> bool:
 
 
 def _build_browse_allowlist() -> list[Path]:
-    """Return the list of root directories the folder browser is allowed
-    to walk. The same list is used to seed the sidebar suggestion chips,
-    so chip targets are always reachable.
+    """Return the root directories the folder browser may walk. The same
+    list seeds the sidebar suggestion chips, so chip targets are always
+    reachable.
 
-    Roots include the current user's HOME, the resolved HF cache dirs,
-    Studio's own outputs/exports/studio root, registered scan folders,
-    and well-known third-party local-LLM dirs (LM Studio, Ollama,
-    `~/models`). Each is added only if it currently resolves to a real
-    directory, so we never produce a "dead" sandbox boundary the user
-    can't navigate into.
+    Roots: the user's HOME, resolved HF cache dirs, Studio's
+    outputs/exports/studio root, registered scan folders, and well-known
+    third-party local-LLM dirs (LM Studio, Ollama, `~/models`). Each is
+    added only if it resolves to a real directory, so we never produce a
+    "dead" sandbox boundary.
     """
     from utils.paths import (
         hf_default_cache_dir,
@@ -1100,9 +1085,8 @@ def _build_browse_allowlist() -> list[Path]:
 
 
 def _is_path_inside_allowlist(target: Path, allowed_roots: list[Path]) -> bool:
-    """Return True if *target* equals or is a descendant of any allowed
-    root. The comparison uses ``os.path.realpath`` so symlinks cannot be
-    used to escape the sandbox.
+    """Return True if *target* equals or descends from any allowed root.
+    Uses ``os.path.realpath`` so symlinks can't escape the sandbox.
     """
     try:
         target_real = os.path.realpath(str(target))
@@ -1262,30 +1246,28 @@ async def browse_folders(
     """
     List immediate subdirectories of *path* for the Custom Folders picker.
 
-    The frontend uses this to render a modal folder browser without needing
-    a native OS dialog (Studio is served over HTTP, so the browser can't
-    reveal absolute paths on the host). The endpoint is read-only and does
-    not create, move, or delete anything. It simply enumerates visible
-    subdirectories so the user can click their way to a folder and hand
-    the resulting string back to POST `/api/models/scan-folders`.
+    Lets the frontend render a modal folder browser without a native OS
+    dialog (Studio is served over HTTP, so the browser can't reveal host
+    paths). Read-only: it only enumerates visible subdirectories so the
+    user can click to a folder and hand the string back to POST
+    `/api/models/scan-folders`.
 
-    Sandbox: requests are bounded to the allowlist returned by
+    Sandbox: bounded to the allowlist from
     :func:`_build_browse_allowlist` (HOME, HF cache, Studio dirs,
-    registered scan folders, well-known model dirs). Paths outside the
-    allowlist return 403 so users cannot probe ``/etc``, ``/proc``,
-    ``/root`` (when not HOME), or other sensitive system locations
-    even if the server process can read them. Symlinks are resolved
-    via ``os.path.realpath`` before the check, so symlink traversal
-    cannot escape the sandbox either.
+    registered scan folders, well-known model dirs). Paths outside it
+    return 403 so users can't probe ``/etc``, ``/proc``, ``/root`` (when
+    not HOME), or other sensitive locations even if the process can read
+    them. Symlinks are resolved via ``os.path.realpath`` first, so
+    traversal can't escape the sandbox.
 
-    Sorting: directories that look like they hold models come first, then
-    plain directories, then hidden entries (if `show_hidden=true`).
+    Sorting: model-bearing dirs first, then plain dirs, then hidden
+    entries (if `show_hidden=true`).
     """
     from utils.paths import hf_default_cache_dir, well_known_model_dirs
     from storage.studio_db import list_scan_folders
 
-    # Build the allowlist once -- both the sandbox check below and the
-    # suggestion chips use the same set, so chips are always navigable.
+    # Build the allowlist once -- the sandbox check and suggestion chips
+    # share it, so chips are always navigable.
     allowed_roots = _build_browse_allowlist()
 
     try:
@@ -1301,7 +1283,7 @@ async def browse_folders(
         raise
 
     # Enumerate immediate subdirectories with a bounded cap so a stray
-    # query against ``/usr/lib`` or ``/proc`` can't stat-storm the process.
+    # query against ``/usr/lib`` or ``/proc`` can't stat-storm us.
     entries: list[BrowseEntry] = []
     truncated = False
     visited = 0
@@ -1321,13 +1303,12 @@ async def browse_folders(
 
     try:
         for child in it:
-            # Bound by *visited entries*, not by *appended entries*: in
-            # directories full of files (or hidden subdirs when
-            # ``show_hidden=False``) the cap on ``len(entries)`` would
-            # never trigger and we'd still stat every child. Counting
-            # visits keeps the worst-case work to ``_BROWSE_ENTRY_CAP``
-            # iterdir/is_dir calls regardless of how many of them
-            # survive the filters below.
+            # Bound by *visited*, not *appended*: in dirs full of files
+            # (or hidden subdirs when ``show_hidden=False``) a cap on
+            # ``len(entries)`` would never trigger and we'd stat every
+            # child. Counting visits caps worst-case work at
+            # ``_BROWSE_ENTRY_CAP`` iterdir/is_dir calls regardless of
+            # how many survive the filters below.
             visited += 1
             if visited > _BROWSE_ENTRY_CAP:
                 truncated = True
@@ -1366,10 +1347,10 @@ async def browse_folders(
 
     entries.sort(key = _sort_key)
 
-    # Parent is None at the filesystem root (`p.parent == p`) AND when
-    # the parent would step outside the sandbox -- otherwise the up-row
-    # would 403 on click. Users can still hop to other allowed roots
-    # via the suggestion chips below.
+    # Parent is None at the filesystem root (`p.parent == p`) and when
+    # the parent would leave the sandbox -- otherwise the up-row would
+    # 403 on click. Users can still hop to other allowed roots via the
+    # suggestion chips below.
     parent: Optional[str]
     if target.parent == target or not _is_path_inside_allowlist(target.parent, allowed_roots):
         parent = None
@@ -1393,27 +1374,25 @@ async def browse_folders(
             seen_sug.add(resolved)
             suggestions.append(resolved)
 
-    # Home always comes first -- it's the safe fallback when everything
-    # else is cold.
+    # Home first -- the safe fallback when everything else is cold.
     _add_sug(Path.home())
     # The HF cache root the process is actually using.
     try:
         _add_sug(hf_default_cache_dir())
     except Exception:
         pass
-    # Already-registered scan folders (what the user has curated).
+    # Already-registered scan folders (user-curated).
     try:
         for folder in list_scan_folders():
             _add_sug(Path(folder.get("path", "")))
     except Exception as exc:
         logger.debug("browse-folders: could not load scan folders: %s", exc)
-    # Directories commonly used by other local-LLM tools: LM Studio
-    # (`~/.lmstudio/models` + legacy `~/.cache/lm-studio/models` +
-    # user-configured downloadsFolder from LM Studio's settings.json),
-    # Ollama (`~/.ollama/models` + common system paths + OLLAMA_MODELS
-    # env var), and generic user-choice spots (`~/models`, `~/Models`).
-    # Each helper only returns paths that currently exist so we never
-    # show dead chips.
+    # Dirs used by other local-LLM tools: LM Studio
+    # (`~/.lmstudio/models` + legacy `~/.cache/lm-studio/models` + LM
+    # Studio settings.json downloadsFolder), Ollama (`~/.ollama/models`
+    # + common system paths + OLLAMA_MODELS env var), and generic spots
+    # (`~/models`, `~/Models`). Each helper returns only existing paths
+    # so we never show dead chips.
     try:
         for p in well_known_model_dirs():
             _add_sug(p)
@@ -1441,18 +1420,12 @@ def _looks_like_mlx_repo(model_id: str) -> bool:
 
 @router.get("/list")
 async def list_models(current_subject: str = Depends(get_current_subject)):
-    """
-    List available models (default models and loaded models).
-
-    This endpoint returns the default models and any currently loaded models.
-    """
+    """List available models: default plus currently loaded."""
     try:
         inference_backend = get_inference_backend()
 
-        # Get default models
         default_models = inference_backend.default_models
 
-        # Get loaded models
         loaded_models = []
         for model_name, model_data in inference_backend.models.items():
             _is_vision = model_data.get("is_vision", False)
@@ -1470,7 +1443,7 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
             )
             loaded_models.append(model_info)
 
-        # Include active GGUF model (loaded via llama-server)
+        # Include active GGUF model (loaded via llama-server).
         from routes.inference import get_llama_cpp_backend
 
         llama_backend = get_llama_cpp_backend()
@@ -1486,12 +1459,11 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
                 )
             )
 
-        # Combine default and loaded models
+        # Combine default and loaded models.
         all_models = []
         seen_ids = set()
 
-        # Prefer loaded entries for duplicate ids so runtime flags
-        # (is_mlx, is_vision, is_audio, ...) are not lost.
+        # Prefer loaded entries for duplicate ids so runtime flags survive.
         loaded_by_id = {model_info.id: model_info for model_info in loaded_models}
 
         # Add default models
@@ -1506,7 +1478,7 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
                 all_models.append(model_info)
                 seen_ids.add(model_id)
 
-        # Add loaded models
+        # Add loaded models.
         for model_info in loaded_models:
             if model_info.id not in seen_ids:
                 all_models.append(model_info)
@@ -1525,7 +1497,7 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
 
 
 def _get_max_position_embeddings(config) -> Optional[int]:
-    """Extract max_position_embeddings from a model config, checking text_config fallback."""
+    """Extract max_position_embeddings from a config, with text_config fallback."""
     if hasattr(config, "max_position_embeddings"):
         return config.max_position_embeddings
     if hasattr(config, "text_config") and hasattr(config.text_config, "max_position_embeddings"):
@@ -1534,7 +1506,7 @@ def _get_max_position_embeddings(config) -> Optional[int]:
 
 
 def _get_model_size_bytes(model_name: str, hf_token: Optional[str] = None) -> Optional[int]:
-    """Get total size of model weight files from HF Hub."""
+    """Total size of model weight files from HF Hub."""
     try:
         from huggingface_hub import HfApi
 
@@ -1562,11 +1534,7 @@ async def get_model_config(
     hf_token: Optional[str] = Query(None),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    Get configuration for a specific model.
-
-    This endpoint wraps the backend load_model_defaults function.
-    """
+    """Get configuration for a specific model (wraps load_model_defaults)."""
     try:
         if not is_local_path(model_name):
             resolved = resolve_cached_repo_id_case(model_name)
@@ -1581,15 +1549,14 @@ async def get_model_config(
         logger.info(f"Getting model config for: {model_name}")
         from utils.models.model_config import detect_audio_type
 
-        # Load model defaults from backend
         config_dict = load_model_defaults(model_name)
 
-        # Detect model capabilities (pass HF token for gated models)
+        # Detect capabilities (pass HF token for gated models).
         is_vision = is_vision_model(model_name, hf_token = hf_token)
         is_embedding = is_embedding_model(model_name, hf_token = hf_token)
         audio_type = detect_audio_type(model_name, hf_token = hf_token)
 
-        # Check if it's a LoRA adapter
+        # Check if it's a LoRA adapter.
         is_lora = False
         base_model = None
         max_position_embeddings = None
@@ -1601,7 +1568,7 @@ async def get_model_config(
         except Exception:
             pass
 
-        # Fallback: try AutoConfig directly if not found yet
+        # Fallback: try AutoConfig directly if not found yet.
         if max_position_embeddings is None:
             try:
                 from transformers import AutoConfig as _AutoConfig
@@ -1653,18 +1620,17 @@ async def scan_loras(
     ),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    Scan for trained LoRA adapters and exported models.
+    """Scan for trained LoRA adapters and exported models.
 
-    Returns both training outputs (from outputs_dir) and exported models
-    (from exports_dir) in a single list, distinguished by source field.
+    Returns training outputs (outputs_dir) and exported models
+    (exports_dir) in one list, distinguished by the source field.
     """
     try:
         resolved_outputs_dir = str(resolve_output_dir(outputs_dir))
         resolved_exports_dir = str(resolve_export_dir(exports_dir))
         lora_list = []
 
-        # Scan training outputs
+        # Scan training outputs.
         trained_models = scan_trained_models(outputs_dir = resolved_outputs_dir)
         for display_name, model_path, model_type in trained_models:
             base_model = get_base_model_from_checkpoint(model_path)
@@ -1712,7 +1678,7 @@ def _is_path_under(path: Path, root: Path) -> bool:
 
 
 def _is_path_under_lexically(path: Path, root: Path) -> bool:
-    """Check containment without resolving the final path's symlink target."""
+    """Check containment without resolving the final path's symlink."""
     try:
         absolute_path = Path(os.path.abspath(str(path)))
         absolute_root = Path(os.path.abspath(str(root)))
@@ -1744,10 +1710,10 @@ def _loading_model_matches_deleted_path(loading_model: object, deleted_path: Pat
 
 
 def _prune_empty_parents(start: Path, stop_at: Path) -> None:
-    """Remove empty ancestor directories of ``start`` up to (but not including) ``stop_at``.
+    """Remove empty ancestors of ``start`` up to (not including) ``stop_at``.
 
-    Used after deleting a model checkpoint so the enclosing run directory does
-    not linger as an empty entry in scan results.
+    Used after deleting a checkpoint so the enclosing run dir doesn't
+    linger as an empty entry in scan results.
     """
     try:
         stop_resolved = stop_at.resolve()
@@ -1799,8 +1765,8 @@ async def delete_finetuned_model(
 ):
     """Delete a Studio-trained or exported model from disk.
 
-    Only paths under Studio's outputs/exports roots are accepted.  Exported
-    GGUF entries can delete one quantization variant at a time.
+    Only paths under Studio's outputs/exports roots are accepted.
+    Exported GGUF entries can delete one quant variant at a time.
     """
     if source not in {"training", "exported"}:
         raise HTTPException(
@@ -2126,18 +2092,16 @@ async def get_gguf_variants(
     hf_token: Optional[str] = Query(None, description = "HuggingFace token for private repos"),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    List available GGUF quantization variants for a HuggingFace repo
-    or a local directory (e.g. LM Studio model folder).
+    """List GGUF quantization variants for a HuggingFace repo or local
+    directory (e.g. LM Studio model folder).
 
-    Returns all available quantization variants (Q4_K_M, Q8_0, BF16, etc.)
-    with file sizes, whether the model supports vision, and the recommended
-    default variant.
+    Returns all variants (Q4_K_M, Q8_0, BF16, etc.) with file sizes,
+    whether the model supports vision, and the recommended default.
     """
     try:
         from utils.models.model_config import is_local_path, list_local_gguf_variants
 
-        # Local directory path (e.g. LM Studio models) — scan filesystem
+        # Local directory path (e.g. LM Studio models) — scan filesystem.
         if is_local_path(repo_id):
             variants, has_vision = list_local_gguf_variants(repo_id)
 
@@ -2160,26 +2124,25 @@ async def get_gguf_variants(
                 default_variant = default_variant,
             )
 
-        # Remote HuggingFace repo — query HF API
+        # Remote HuggingFace repo — query HF API.
         variants, has_vision = list_gguf_variants(repo_id, hf_token = hf_token)
 
-        # Determine default variant
+        # Determine default variant.
         filenames = [v.filename for v in variants]
         best = _pick_best_gguf(filenames)
         default_variant = _extract_quant_label(best) if best else None
 
-        # Check which variants are fully downloaded in the HF cache.
-        # For split GGUFs, ALL shards must be present -- sum cached bytes
-        # per variant and compare against the expected total.
-        # HF cache dir uses the exact case from the repo_id at download time,
-        # which may differ from the canonical HF repo_id, so do a
-        # case-insensitive match.
+        # Which variants are fully downloaded in the HF cache. For split
+        # GGUFs, ALL shards must be present -- sum cached bytes per
+        # variant vs. the expected total. The HF cache dir uses the
+        # repo_id casing from download time, which may differ from the
+        # canonical repo_id, so match case-insensitively.
         cached_bytes_by_quant: dict[str, int] = {}
         try:
             import re as _re
             from huggingface_hub import constants as hf_constants
 
-            # Sanitize repo_id: must be "owner/name" with safe chars only
+            # Sanitize repo_id: "owner/name" with safe chars only.
             if not _is_valid_repo_id(repo_id):
                 raise ValueError(f"Invalid repo_id format: {repo_id}")
 
@@ -2203,7 +2166,7 @@ async def get_gguf_variants(
             cached = cached_bytes_by_quant.get(variant.quant, 0)
             if cached == 0 or variant.size_bytes == 0:
                 return False
-            # Allow small rounding tolerance (symlinks vs real sizes)
+            # Small rounding tolerance (symlinks vs real sizes).
             return cached >= variant.size_bytes * 0.99
 
         return GgufVariantsResponse(
@@ -2236,10 +2199,10 @@ async def get_gguf_download_progress(
     expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
     current_subject: str = Depends(get_current_subject),
 ):
-    """Return download progress by checking cached GGUF files for a specific variant.
+    """Download progress from cached GGUF files for a specific variant.
 
-    Tracks completed shard downloads in snapshots and in-progress downloads
-    in the blobs directory (incomplete files).
+    Tracks completed shards in snapshots and in-progress (.incomplete)
+    downloads in the blobs directory.
     """
     try:
         if not _is_valid_repo_id(repo_id):
@@ -2258,12 +2221,12 @@ async def get_gguf_download_progress(
         in_progress_bytes = 0
         for entry in cache_dir.iterdir():
             if entry.name.lower() == target:
-                # Count completed .gguf files matching this variant in snapshots
+                # Completed .gguf files for this variant in snapshots.
                 for f in _iter_gguf_paths(entry):
                     fname = f.name.lower().replace("-", "").replace("_", "")
                     if not variant_lower or variant_lower in fname:
                         downloaded_bytes += f.stat().st_size
-                # Check blobs for in-progress downloads (.incomplete files)
+                # In-progress downloads (.incomplete) in blobs.
                 blobs_dir = entry / "blobs"
                 if blobs_dir.is_dir():
                     for f in blobs_dir.iterdir():
@@ -2273,7 +2236,7 @@ async def get_gguf_download_progress(
 
         total_progress_bytes = downloaded_bytes + in_progress_bytes
         progress = min(total_progress_bytes / expected_bytes, 0.99) if expected_bytes > 0 else 0
-        # Only report 1.0 when all bytes are in completed files (not in-progress)
+        # Report 1.0 only when all bytes are in completed files.
         if expected_bytes > 0 and downloaded_bytes >= expected_bytes:
             progress = 1.0
         return {
@@ -2288,9 +2251,9 @@ async def get_gguf_download_progress(
 def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
     """Pick the most useful on-disk path for a HF cache repo.
 
-    Prefers the most-recent snapshot dir (what `from_pretrained` actually
-    points at). Falls back to the cache repo root. Returns the resolved
-    realpath so symlinks under snapshots/ are followed back to blobs/.
+    Prefers the most-recent snapshot dir (what `from_pretrained` points
+    at), falling back to the cache repo root. Returns the resolved
+    realpath so symlinks under snapshots/ follow back to blobs/.
     """
     try:
         snapshots_dir = repo_dir / "snapshots"
@@ -2312,11 +2275,10 @@ async def get_download_progress(
     """Return download progress for any HuggingFace model repo.
 
     Checks the local HF cache for completed blobs and in-progress
-    (.incomplete) downloads. Uses the HF API to determine the expected
-    total size on the first call, then caches it for subsequent polls.
-    Also returns ``cache_path``: the realpath of the snapshot directory
-    (or the cache repo root if no snapshot exists yet) so the UI can
-    show users where the weights actually live on disk.
+    (.incomplete) downloads. Gets the expected total size from the HF API
+    on the first call, then caches it for later polls. Also returns
+    ``cache_path``: the realpath of the snapshot dir (or cache repo root
+    if no snapshot yet) so the UI can show where weights live on disk.
     """
     _empty = {
         "downloaded_bytes": 0,
@@ -2356,10 +2318,10 @@ async def get_download_progress(
         if downloaded_bytes == 0:
             return {**_empty, "cache_path": cache_path}
 
-        # Get expected size from HF API (cached per repo_id)
+        # Expected size from HF API (cached per repo_id).
         expected_bytes = _get_repo_size_cached(repo_id)
         if expected_bytes <= 0:
-            # Cannot determine total; report bytes only, no percentage
+            # Total unknown; report bytes only, no percentage.
             return {
                 "downloaded_bytes": downloaded_bytes,
                 "expected_bytes": 0,
@@ -2367,11 +2329,10 @@ async def get_download_progress(
                 "cache_path": cache_path,
             }
 
-        # Use 95% threshold for completion (blob deduplication can make
-        # completed_bytes differ slightly from expected_bytes).
-        # Do NOT use "no .incomplete files" as a completion signal --
-        # HF downloads files sequentially, so between files there are
-        # no .incomplete files even though the download is far from done.
+        # 95% completion threshold (blob dedup can make completed_bytes
+        # differ slightly from expected_bytes). Do NOT treat "no
+        # .incomplete files" as done -- HF downloads sequentially, so
+        # between files none exist even though it's far from finished.
         if completed_bytes >= expected_bytes * 0.95:
             progress = 1.0
         else:
@@ -2406,14 +2367,14 @@ def _get_repo_size_cached(repo_id: str) -> int:
 
 
 def _all_hf_cache_scans():
-    """Return scan_cache_dir results for the active, legacy, and default HF caches."""
+    """scan_cache_dir results for the active, legacy, and default HF caches."""
     from huggingface_hub import scan_cache_dir
     from utils.paths import legacy_hf_cache_dir, hf_default_cache_dir
 
     scans = [scan_cache_dir()]
     seen: set[str] = set()
     try:
-        # Resolve the active cache dir so we can dedup
+        # Resolve the active cache dir for deduplication.
         from huggingface_hub.constants import HF_HUB_CACHE
         seen.add(str(Path(HF_HUB_CACHE).resolve()))
     except Exception:
@@ -2435,14 +2396,14 @@ def _is_gguf_filename(name: str) -> bool:
 
 
 def _is_mmproj_filename(name: str) -> bool:
-    """Match GGUF vision-adapter (mmproj) files. Kept consistent with
+    """Match GGUF vision-adapter (mmproj) files. Consistent with
     ``utils.models.model_config._is_mmproj``."""
     return "mmproj" in name.lower()
 
 
 def _is_main_gguf_filename(name: str) -> bool:
-    """A GGUF file that is a primary weight artifact, not an mmproj
-    vision adapter."""
+    """A GGUF file that is a primary weight, not an mmproj vision
+    adapter."""
     return _is_gguf_filename(name) and not _is_mmproj_filename(name)
 
 
@@ -2453,17 +2414,16 @@ def _iter_gguf_paths(root: Path):
 
 
 def _repo_gguf_size_bytes(repo_info) -> int:
-    """Return the total on-disk size of primary GGUF weight files across
-    all revisions, excluding mmproj vision-adapter files.
+    """Total on-disk size of primary GGUF weight files across all
+    revisions, excluding mmproj vision-adapter files.
 
     Hugging Face hardlinks blobs shared between revisions, so this
-    deduplicates by blob path (or, as a fallback, by revision commit
-    hash + filename) to avoid double-counting the same bytes. Files
-    with an unknown size (``size_on_disk is None``, e.g. a partial or
-    interrupted download) are treated as zero bytes. mmproj files are
-    excluded so that repos whose only ``.gguf`` artifact is a vision
-    adapter are not classified as GGUF repos: the variant selector
-    filters mmproj out and would otherwise show zero pickable variants.
+    deduplicates by blob path (or revision commit hash + filename as a
+    fallback) to avoid double-counting. Unknown sizes (``size_on_disk is
+    None``, e.g. a partial download) count as zero. mmproj files are
+    excluded so repos whose only ``.gguf`` artifact is a vision adapter
+    aren't classed as GGUF repos: the variant selector filters mmproj
+    out and would otherwise show zero pickable variants.
     """
     unique_blobs: dict[str, int] = {}
     for revision in repo_info.revisions:
@@ -2480,9 +2440,9 @@ def _repo_gguf_size_bytes(repo_info) -> int:
 
 
 def _repo_has_gguf_files(repo_info) -> bool:
-    """Return True when any revision in a cached repo contains a
-    primary GGUF weight file. Repos whose only ``.gguf`` artifact is
-    an mmproj vision adapter are not treated as GGUF here."""
+    """True when any revision in a cached repo has a primary GGUF weight
+    file. Repos whose only ``.gguf`` artifact is an mmproj vision adapter
+    are not treated as GGUF here."""
     return _repo_gguf_size_bytes(repo_info) > 0
 
 
@@ -2576,14 +2536,14 @@ async def delete_cached_model(
 ):
     """Delete a cached model repo (or a specific GGUF variant) from the HF cache.
 
-    When *variant* is provided, only the GGUF files matching that quant label
-    are removed (e.g. ``UD-Q4_K_XL``).  Otherwise the entire repo is deleted.
-    Refuses if the model is currently loaded for inference.
+    With *variant*, only GGUF files matching that quant label are removed
+    (e.g. ``UD-Q4_K_XL``); otherwise the whole repo is deleted. Refuses
+    if the model is currently loaded for inference.
     """
     if not _is_valid_repo_id(repo_id):
         raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
 
-    # Check if model is currently loaded
+    # Refuse if the model is currently loaded.
     try:
         from routes.inference import get_llama_cpp_backend
         llama_backend = get_llama_cpp_backend()
@@ -2641,7 +2601,7 @@ async def delete_cached_model(
                     quant = _extract_quant_label(f.file_name)
                     if quant.lower() != variant.lower():
                         continue
-                    # Delete the blob (actual data) and the snapshot symlink
+                    # Delete the blob (data) and the snapshot symlink.
                     try:
                         blob = Path(f.blob_path)
                         snap = Path(f.file_path)
@@ -2700,8 +2660,7 @@ async def list_checkpoints(
     ),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    List available checkpoints in the outputs directory.
+    """List checkpoints in the outputs directory.
 
     Scans the outputs folder for training runs and their checkpoints.
     """
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index 5dd7038330..c78739be84 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -4,12 +4,12 @@
 """
 API routes for external LLM provider management.
 
-Provides endpoints for:
-  - Discovering available provider types (registry)
+Endpoints:
+  - Discover available provider types (registry)
   - CRUD for saved provider configurations (no API keys stored)
-  - Fetching the RSA public key for API key encryption
-  - Testing provider connectivity
-  - Listing models from a provider
+  - Fetch the RSA public key for API key encryption
+  - Test provider connectivity
+  - List models from a provider
 """
 
 import uuid
@@ -54,11 +54,10 @@ router = APIRouter()
 async def get_public_key(current_subject: str = Depends(get_current_subject)):
     """Return the RSA public key PEM for client-side API key encryption.
 
-    The ``fingerprint`` field is a short SHA256 of the PEM and is meant
-    purely for diagnostics — a mismatch between what the frontend
-    captured at encrypt time and what the server reports here is a
-    clear signal that the keypair rotated mid-flight (e.g. the server
-    re-ran ``init_key_pair`` for any reason).
+    The ``fingerprint`` field is a short SHA256 of the PEM, for diagnostics: a
+    mismatch between what the frontend captured at encrypt time and what the
+    server reports here signals the keypair rotated mid-flight (e.g. the server
+    re-ran ``init_key_pair``).
     """
     return {
         "public_key": get_public_key_pem(),
@@ -80,10 +79,10 @@ async def list_registry(current_subject: str = Depends(get_current_subject)):
 
 @router.get("/pricing")
 async def get_pricing_snapshot(current_subject: str = Depends(get_current_subject)):
-    """Static per-MTok pricing table the frontend uses to convert
-    upstream usage chunks into a per-turn USD cost. See
-    ``core/inference/pricing.py`` for sourcing notes; values reflect
-    the published prices as of the file's last update."""
+    """Static per-MTok pricing table the frontend uses to convert upstream
+    usage chunks into a per-turn USD cost. See ``core/inference/pricing.py``
+    for sourcing notes; values reflect the published prices as of the file's
+    last update."""
     return pricing_snapshot()
 
 
@@ -196,7 +195,7 @@ async def test_provider(
     Test connectivity to an external provider.
 
     Makes a lightweight GET /models call to verify the API key works.
-    The encrypted_api_key is decrypted server-side and never stored.
+    encrypted_api_key is decrypted server-side and never stored.
     """
     info = get_provider_info(payload.provider_type)
     if info is None:
@@ -267,7 +266,7 @@ async def list_provider_models(
     """
     List models available from an external provider.
 
-    The encrypted_api_key is decrypted server-side and never stored.
+    encrypted_api_key is decrypted server-side and never stored.
     """
     info = get_provider_info(payload.provider_type)
     if info is None:
@@ -308,16 +307,15 @@ async def list_provider_models(
 
     try:
         models = await client.list_models()
-        # Registry-level model-id filters are scoped to the canonical
-        # native Gemini base. A custom Gemini OAI-compatible proxy
-        # (LiteLLM, deployment gateway) returns IDs like
-        # `google/gemini-2.5-flash`, `gemini/gemini-2.5-flash`, or
-        # team-prefixed deployment aliases; the native allowlist regex
-        # would strip those out and leave the picker empty even though
-        # the chat path now routes them via the OAI-compatible
-        # dispatcher (the same gate ExternalProviderClient applies for
-        # request building). Match the host check here so the model
-        # list and chat dispatch agree on what counts as "native".
+        # Registry-level model-id filters are scoped to the canonical native
+        # Gemini base. A custom Gemini OAI-compatible proxy (LiteLLM, deployment
+        # gateway) returns IDs like `google/gemini-2.5-flash`,
+        # `gemini/gemini-2.5-flash`, or team-prefixed deployment aliases; the
+        # native allowlist regex would strip those and leave the picker empty,
+        # even though the chat path routes them via the OAI-compatible
+        # dispatcher (the same gate ExternalProviderClient applies for request
+        # building). Match the host check here so the model list and chat
+        # dispatch agree on what counts as "native".
         apply_registry_model_filters = True
         if payload.provider_type == "gemini":
             try:
@@ -344,11 +342,10 @@ async def list_provider_models(
             denylist = info.get("model_id_denylist")
             if denylist is not None:
                 models = [m for m in models if not denylist.search(m.get("id", ""))]
-        # Apply an optional cap after filtering so registry entries with a
-        # large remote catalog (e.g. HF Inference Providers) can stay
-        # picker-sized. No popularity sort happens server-side, so this is
-        # "first N matches" — pair with default_models for any must-have
-        # flagship ids.
+        # Optional cap after filtering so registry entries with a large remote
+        # catalog (e.g. HF Inference Providers) stay picker-sized. No
+        # server-side popularity sort, so this is "first N matches" — pair with
+        # default_models for any must-have flagship ids.
         limit = info.get("model_id_limit")
         if isinstance(limit, int) and limit > 0:
             models = models[:limit]
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index d62e0209b0..7ce086e5b2 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -16,13 +16,12 @@ import asyncio
 from datetime import datetime
 import uuid as _uuid
 
-# Add backend directory to path
-# The backend code should be in the same directory structure
+# Add backend directory to path (same directory structure).
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Import backend functions
+# Import backend functions.
 try:
     from core.training import get_training_backend
     from core.training.resume import (
@@ -34,7 +33,7 @@ try:
     from utils.models.model_config import load_model_defaults
     from utils.paths import resolve_dataset_path
 except ImportError:
-    # Fallback: try to import from parent directory
+    # Fallback: import from the parent directory.
     parent_backend = backend_path.parent / "backend"
     if str(parent_backend) not in sys.path:
         sys.path.insert(0, str(parent_backend))
@@ -95,10 +94,9 @@ def _validate_local_dataset_paths(paths: list[str], label: str = "Local dataset"
 @router.get("/hardware")
 async def get_hardware_utilization(current_subject: str = Depends(get_current_subject)):
     """
-    Get a live snapshot of GPU hardware utilization.
+    Live snapshot of GPU hardware utilization for the active backend.
 
-    Designed to be polled by the frontend during training.
-    Returns live GPU memory usage information for the active backend.
+    Polled by the frontend during training.
     """
     from utils.hardware import get_gpu_utilization
     return get_gpu_utilization()
@@ -117,8 +115,8 @@ async def start_training(
     """
     Start a training job.
 
-    This endpoint initiates training in the background and returns immediately.
-    Use the /status endpoint to check training progress.
+    Initiates training in the background and returns immediately. Use /status
+    to check progress.
     """
     try:
         logger.info(f"Starting training job with model: {request.model_name}")
@@ -129,7 +127,7 @@ async def start_training(
 
         backend = get_training_backend()
 
-        # Check if training is already active (before mutating any state)
+        # Check if training is already active (before mutating state).
         if backend.is_training_active():
             existing_job_id: Optional[str] = getattr(backend, "current_job_id", "")
             return TrainingJobResponse(
@@ -142,11 +140,11 @@ async def start_training(
                 error = "Training already active",
             )
 
-        # Generate job ID — passed into start_training() which sets it on the
-        # backend only after confirming the old pump thread is dead.
+        # Job ID — passed to start_training(), which sets it on the backend only
+        # after confirming the old pump thread is dead.
         job_id = f"job_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{_uuid.uuid4().hex[:8]}"
 
-        # Validate dataset paths if provided
+        # Validate dataset paths if provided.
         if request.local_datasets:
             request.local_datasets = _validate_local_dataset_paths(
                 request.local_datasets, "Local dataset"
@@ -178,7 +176,7 @@ async def start_training(
                 )
             request.resume_from_checkpoint = resume_checkpoint
 
-        # Convert request to kwargs for backend
+        # Convert request to backend kwargs.
         training_kwargs = {
             "model_name": request.model_name,
             "training_type": request.training_type,
@@ -242,8 +240,8 @@ async def start_training(
         }
 
         # Training page has no trust_remote_code toggle — the value comes from
-        # YAML model defaults applied when the user selects a model.  As a safety
-        # net, consult the YAML directly so models that need it always get it.
+        # YAML model defaults on model select. As a safety net, consult the YAML
+        # directly so models that need it always get it.
         if not training_kwargs["trust_remote_code"]:
             model_defaults = load_model_defaults(request.model_name)
             yaml_trust = model_defaults.get("training", {}).get("trust_remote_code", False)
@@ -252,7 +250,7 @@ async def start_training(
                 training_kwargs["trust_remote_code"] = True
 
         # Free GPU memory: shut down any running inference/export subprocesses
-        # before training starts (they'd compete for VRAM otherwise)
+        # before training (they'd compete for VRAM otherwise).
         try:
             from core.inference import get_inference_backend
             inf_backend = get_inference_backend()
@@ -279,7 +277,7 @@ async def start_training(
         except Exception as e:
             logger.warning("Could not shut down export subprocess: %s", e)
 
-        # start_training now spawns a subprocess (non-blocking)
+        # start_training spawns a subprocess (non-blocking).
         success = backend.start_training(job_id = job_id, **training_kwargs)
 
         if not success:
@@ -334,7 +332,6 @@ async def stop_training(
                 status = "idle", message = "No training job is currently running"
             )
 
-        # Call backend stop method
         backend.stop_training(save = body.save)
 
         return TrainingStopResponse(
@@ -354,16 +351,14 @@ async def stop_training(
 
 @router.post("/reset")
 async def reset_training(current_subject: str = Depends(get_current_subject)):
-    """
-    Reset training state so the user can return to configuration.
-    """
+    """Reset training state so the user can return to configuration."""
     try:
         backend = get_training_backend()
         is_active = backend.is_training_active()
 
         if is_active:
             if backend._cancel_requested:
-                # Cancel (save=False) was requested — force-terminate so we can reset immediately
+                # Cancel (save=False) requested — force-terminate to reset immediately.
                 logger.info("Force-terminating subprocess for immediate reset (cancel path)")
                 backend.force_terminate()
             else:
@@ -460,7 +455,7 @@ async def get_training_status(current_subject: str = Depends(get_current_subject
             if output_dir:
                 details["output_dir"] = output_dir
 
-        # Build metric history for chart recovery after SSE reconnection
+        # Metric history for chart recovery after SSE reconnection.
         metric_history = None
         if backend.step_history:
             metric_history = {
@@ -540,16 +535,15 @@ async def stream_training_progress(
     request: Request, current_subject: str = Depends(get_current_subject)
 ):
     """
-    Stream training progress updates using Server-Sent Events (SSE).
+    Stream training progress via Server-Sent Events (SSE).
 
-    This endpoint provides real-time updates on training progress.
-    Supports reconnection via the SSE spec:
-      - Sends `id:` with each event so the browser tracks position.
-      - Sends `retry:` to control reconnection interval.
-      - Sends named `event:` types (progress, heartbeat, complete, error).
-      - Reads `Last-Event-ID` header on reconnect to replay missed steps.
+    Real-time progress with reconnection support per the SSE spec:
+      - `id:` per event so the browser tracks position.
+      - `retry:` to control reconnection interval.
+      - Named `event:` types (progress, heartbeat, complete, error).
+      - Reads `Last-Event-ID` on reconnect to replay missed steps.
     """
-    # Read Last-Event-ID header for reconnection resume
+    # Read Last-Event-ID header for reconnection resume.
     last_event_id = request.headers.get("last-event-id")
     resume_from_step: Optional[int] = None
     if last_event_id is not None:
@@ -580,7 +574,7 @@ async def stream_training_progress(
             else:
                 progress_percent = float(step) / float(total) * 100.0 if total > 0 else 0.0
 
-            # Get actual values from progress object if available
+            # Pull values from the progress object if available.
             elapsed_seconds = getattr(progress, "elapsed_seconds", None) if progress else None
             eta_seconds = getattr(progress, "eta_seconds", None) if progress else None
             grad_norm = grad_norm_override
@@ -622,7 +616,7 @@ async def stream_training_progress(
             return "\n".join(lines)
 
         # ── Retry directive ──────────────────────────────────────
-        # Tell the browser to reconnect after 3 seconds if the connection drops
+        # Reconnect after 3 seconds if the connection drops.
         yield "retry: 3000\n\n"
 
         # ── Replay missed steps on reconnect ─────────────────────
@@ -707,7 +701,7 @@ async def stream_training_progress(
         # ── Live polling loop ────────────────────────────────────
         last_step = resume_from_step if resume_from_step is not None else -1
         no_update_count = 0
-        max_no_updates = 1800  # Timeout after 30 minutes (large models need time for compilation)
+        max_no_updates = 1800  # Timeout after 30 min (large models need compile time)
 
         while backend.is_training_active():
             try:
@@ -721,7 +715,7 @@ async def stream_training_progress(
                     )
                     current_epoch = getattr(tp_inner, "epoch", None) if tp_inner else None
 
-                    # Only send if step changed
+                    # Only send if the step changed.
                     if current_step != last_step:
                         progress_payload = build_progress(
                             current_step,
@@ -740,7 +734,7 @@ async def stream_training_progress(
                         no_update_count = 0
                     else:
                         no_update_count += 1
-                        # Send heartbeat every 10 seconds
+                        # Heartbeat every 10 seconds.
                         if no_update_count % 10 == 0:
                             heartbeat_payload = build_progress(
                                 current_step,
@@ -756,11 +750,11 @@ async def stream_training_progress(
                                 event_id = current_step,
                             )
                 else:
-                    # No steps yet, but training is active (model loading, etc.)
+                    # No steps yet, but training is active (model loading, etc.).
                     no_update_count += 1
                     if no_update_count % 5 == 0:
-                        # Pull total_steps and status from trainer so
-                        # the frontend can show "Tokenizing…" etc.
+                        # Pull total_steps + status from trainer so the frontend
+                        # can show "Tokenizing…" etc.
                         tp_prep = getattr(
                             getattr(backend, "trainer", None),
                             "training_progress",
diff --git a/studio/backend/run.py b/studio/backend/run.py
index 5cfc1822f7..b9f271b4be 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -1,9 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Run script for Unsloth UI Backend.
-Works independently and can be moved to any directory.
+"""Run script for Unsloth UI Backend.
+
+Self-contained; can be moved to any directory.
 """
 
 import os
@@ -11,10 +11,10 @@ import sys
 from pathlib import Path
 from typing import Optional
 
-# Suppress annoying C-level dependency warnings globally (e.g. SwigPyPacked)
+# Suppress C-level dependency warnings globally (e.g. SwigPyPacked).
 os.environ["PYTHONWARNINGS"] = "ignore"
 
-# Add the backend directory to Python path early so local modules are importable
+# Add the backend dir to sys.path early so local modules import.
 backend_dir = Path(__file__).parent
 if str(backend_dir) not in sys.path:
     sys.path.insert(0, str(backend_dir))
@@ -27,8 +27,8 @@ except ValueError as exc:
     configured = os.environ.get("UNSLOTH_CPU_THREADS")
     raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {exc}") from None
 
-# Fix for Anaconda/conda-forge Python: seed platform._sys_version_cache before
-# any library imports that trigger attrs -> rich -> structlog -> platform crash.
+# Anaconda/conda-forge Python: seed platform._sys_version_cache before
+# imports that trigger attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
 import _platform_compat  # noqa: F401
 
@@ -39,18 +39,17 @@ logger = get_logger(__name__)
 
 
 def _resolve_external_ip() -> str:
-    """
-    Resolve the machine's external IP address.
+    """Resolve the machine's external IP address.
 
-    Tries (in order):
-    1. GCE metadata server (instant, works on Google Cloud VMs)
-    2. ifconfig.me (works anywhere with internet)
+    Tries, in order:
+    1. GCE metadata server (instant on Google Cloud VMs)
+    2. ifconfig.me (anywhere with internet)
     3. LAN IP via UDP socket trick (fallback)
     """
     import urllib.request
     import socket
 
-    # 1. Try GCE metadata server (responds in <10ms on GCE, times out fast elsewhere)
+    # 1. GCE metadata server (<10ms on GCE, times out fast elsewhere).
     try:
         req = urllib.request.Request(
             "http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip",
@@ -63,7 +62,7 @@ def _resolve_external_ip() -> str:
     except Exception:
         pass
 
-    # 2. Try public IP service
+    # 2. Public IP service.
     try:
         with urllib.request.urlopen("https://ifconfig.me", timeout = 3) as resp:
             ip = resp.read().decode().strip()
@@ -84,9 +83,10 @@ def _resolve_external_ip() -> str:
 
 
 def _install_uvicorn_startup_log_rewrite(bind_host: str, display_host: str) -> None:
-    """Rewrite Uvicorn's startup log line: swap wildcard bind for the
-    externally-reachable address, replace the CTRL+C suffix with our Mac-aware
-    stop hint, and rename the prefix to "Unsloth Studio running on"."""
+    """Rewrite Uvicorn's startup log line: swap the wildcard bind for the
+    externally-reachable address, replace the CTRL+C suffix with our
+    Mac-aware stop hint, and rename the prefix to "Unsloth Studio running
+    on"."""
     import logging
     import re
 
@@ -137,7 +137,7 @@ def _local_port_open(
     port: int,
     timeout: float = 1.0,
 ) -> bool:
-    """Return True iff a TCP connection to (host, port) succeeds within timeout."""
+    """True iff a TCP connection to (host, port) succeeds within timeout."""
     import socket
     try:
         with socket.create_connection((host, port), timeout = timeout):
@@ -147,8 +147,8 @@ def _local_port_open(
 
 
 def _working_local_url(port: int) -> "str | None":
-    """Return a working loopback URL on this machine, or None if neither
-    127.0.0.1 nor ::1 responds. Used as a fallback when external reachability fails."""
+    """A working loopback URL on this machine, or None if neither
+    127.0.0.1 nor ::1 responds. Fallback when external reachability fails."""
     if _local_port_open("127.0.0.1", port):
         return f"http://127.0.0.1:{port}"
     if _local_port_open("::1", port):
@@ -157,13 +157,12 @@ def _working_local_url(port: int) -> "str | None":
 
 
 def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
-    """Return the IPv4 loopback URL when localhost will not reach 127.0.0.1.
+    """Return the IPv4 loopback URL when localhost won't reach 127.0.0.1.
 
-    Local Studio intentionally binds to 127.0.0.1. On hosts where localhost
-    resolves to IPv6 only (::1), a browser pointed at http://localhost:<port>
-    fails -- or worse, reaches a different process listening on ::1 -- even
-    though http://127.0.0.1:<port> works. Return the IPv4 URL so the caller can
-    tell the user which address to open.
+    Local Studio binds to 127.0.0.1. Where localhost resolves to IPv6
+    only (::1), http://localhost:<port> fails -- or worse, hits a
+    different process on ::1 -- even though http://127.0.0.1:<port> works.
+    Return the IPv4 URL so the caller can tell the user what to open.
     """
     import socket
 
@@ -172,7 +171,7 @@ def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
 
     ipv4_url = f"http://127.0.0.1:{port}"
 
-    # Only warn once Studio is confirmed answering on the IPv4 loopback.
+    # Only warn once Studio is confirmed answering on IPv4 loopback.
     if _working_local_url(port) != ipv4_url:
         return None
 
@@ -194,11 +193,11 @@ def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
             if host == "::1":
                 has_ipv6_loopback = True
 
-    # A successful connection to ::1 is NOT evidence that Studio is reachable
-    # there: Studio binds 127.0.0.1 only, so anything answering on ::1 is a
-    # different process -- which is exactly when the user must be steered to
-    # 127.0.0.1. Dual-stack localhost is fine (browsers fall back to 127.0.0.1
-    # when ::1 refuses), so only the IPv6-only case strands the user.
+    # A connection to ::1 is NOT evidence Studio is reachable there:
+    # Studio binds 127.0.0.1 only, so anything on ::1 is a different
+    # process -- exactly when to steer the user to 127.0.0.1. Dual-stack
+    # localhost is fine (browsers fall back to 127.0.0.1 when ::1
+    # refuses), so only the IPv6-only case strands the user.
     if has_ipv6_loopback and not has_ipv4_loopback:
         return ipv4_url
     return None
@@ -231,11 +230,11 @@ def _print_localhost_ipv6_mismatch_warning(local_url: str, port: int) -> None:
 
 
 def _verify_global_reachability(display_host: str, port: int) -> None:
-    """Probe check-host.net to confirm display_host:port is reachable from the
-    public internet. Synchronous so the caller can render output between the
-    banner URL section and the trailing stop hint. Bounded at ~15s; failures
-    are swallowed (the verifier failing is not Studio failing). Only meaningful
-    when bound to a wildcard host."""
+    """Probe check-host.net to confirm display_host:port is reachable
+    from the public internet. Synchronous so the caller can render output
+    between the banner URL section and the trailing stop hint. Bounded at
+    ~15s; failures are swallowed (verifier failing != Studio failing).
+    Only meaningful when bound to a wildcard host."""
     import ipaddress
     import json
     import time
@@ -256,7 +255,7 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
 
     url = f"http://{display_host}:{port}"
 
-    # Private / loopback / link-local addresses are not globally routable.
+    # Private/loopback/link-local addresses aren't globally routable.
     try:
         addr = ipaddress.ip_address(display_host)
         if addr.is_loopback or addr.is_private or addr.is_link_local:
@@ -304,7 +303,7 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
                 continue
             if results and all(v is not None for v in results.values()):
                 break
-            # Two decisive nodes is enough; stop polling early.
+            # Two decisive nodes is enough; stop early.
             decisive = [
                 v
                 for v in results.values()
@@ -373,7 +372,7 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
                 f"{dim}    then open http://localhost:{port}/ in your browser.{reset}",
                 flush = True,
             )
-            # Only offer the local URL if loopback actually answers.
+            # Only offer the local URL if loopback answers.
             local_url = _working_local_url(port)
             if local_url:
                 print(
@@ -388,7 +387,7 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
                 flush = True,
             )
     except urllib.error.URLError:
-        # Outbound HTTPS blocked; skip silently.
+        # Outbound HTTPS blocked; skip.
         pass
     except Exception:
         pass
@@ -397,16 +396,16 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
 def _emit_startup_output(host: str, port: int, display_host: str) -> None:
     """Print the access banner plus any post-startup warnings.
 
-    Extracted from ``_run`` so the banner/warning wiring is unit-testable. The
-    ``localhost``-to-::1 mismatch warning and the wildcard reachability check
-    are mutually exclusive (the mismatch helper returns None for any non
-    127.0.0.1 bind, and wildcard binds are never 127.0.0.1), so the trailing
-    stop hint is emitted exactly once.
+    Extracted from ``_run`` so the banner/warning wiring is testable. The
+    ``localhost``-to-::1 mismatch warning and the wildcard reachability
+    check are mutually exclusive (the mismatch helper returns None for any
+    non-127.0.0.1 bind, and wildcard binds are never 127.0.0.1), so the
+    trailing stop hint is emitted exactly once.
     """
     wildcard_bind = host in ("0.0.0.0", "::")
     localhost_mismatch_url = _localhost_ipv6_mismatch_url(host, port)
-    # For wildcard binds, run the reachability check between the URL section
-    # and the stop hint so the stop hint stays last on screen.
+    # For wildcard binds, run the reachability check between the URL
+    # section and the stop hint so the stop hint stays last.
     print_studio_access_banner(
         port = port,
         bind_host = host,
@@ -422,12 +421,11 @@ def _emit_startup_output(host: str, port: int, display_host: str) -> None:
 
 
 def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
-    """Return (pid, process_name) of the process listening on *port*, or None.
+    """Return (pid, process_name) listening on *port*, or None.
 
-    Uses psutil when available.  Falls back gracefully to None so callers
-    can still report the port conflict without process details.
-
-    Works on Windows, macOS, and Linux wherever psutil is installed.
+    Uses psutil when available, falling back to None so callers can still
+    report the conflict without process details. Works on Windows, macOS,
+    and Linux wherever psutil is installed.
     """
     try:
         import psutil
@@ -444,7 +442,7 @@ def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
                 except (psutil.NoSuchProcess, psutil.AccessDenied):
                     return (conn.pid, "<unknown>")
     except (psutil.AccessDenied, OSError) as e:
-        # psutil.net_connections() needs elevated privileges on some platforms
+        # net_connections() needs elevated privileges on some platforms.
         logger.debug("Failed to scan network connections for port %s: %s", port, e)
     return None
 
@@ -452,19 +450,17 @@ def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
 def _is_port_free(host: str, port: int) -> bool:
     """Check if a port is available for binding.
 
-    When *host* is ``0.0.0.0`` (wildcard), we also check whether anything
-    is already listening on ``127.0.0.1`` (and ``::1`` when IPv6 is
-    available).  An SSH tunnel or similar process may hold the loopback
-    address while our wildcard bind still succeeds, making Unsloth Studio
-    unreachable via ``localhost``.
+    When *host* is ``0.0.0.0`` (wildcard), also check whether anything is
+    already listening on ``127.0.0.1`` (and ``::1`` when IPv6 exists). An
+    SSH tunnel may hold the loopback address while our wildcard bind
+    succeeds, making Studio unreachable via ``localhost``.
 
     Works on Windows, macOS, and Linux.
     """
     import socket
 
-    # 1. Can we bind to the requested address?
-    #    Use getaddrinfo so both IPv4 ("0.0.0.0") and IPv6 ("::") hosts
-    #    resolve to the correct address family automatically.
+    # 1. Can we bind to the requested address? getaddrinfo resolves both
+    #    IPv4 ("0.0.0.0") and IPv6 ("::") to the right address family.
     try:
         addr_info = socket.getaddrinfo(host, port, socket.AF_UNSPEC, socket.SOCK_STREAM)
         family, socktype, proto, _, sockaddr = addr_info[0]
@@ -474,9 +470,9 @@ def _is_port_free(host: str, port: int) -> bool:
     except OSError:
         return False
 
-    # 2. When binding to all interfaces, verify that localhost is not
-    #    already claimed by another process (e.g. an SSH -L tunnel).
-    #    We attempt a TCP connect -- if it succeeds something is listening.
+    # 2. When binding to all interfaces, verify localhost isn't already
+    #    claimed by another process (e.g. an SSH -L tunnel). A successful
+    #    TCP connect means something is listening.
     if host in ("0.0.0.0", "::"):
         for loopback, family in [
             ("127.0.0.1", socket.AF_INET),
@@ -486,10 +482,10 @@ def _is_port_free(host: str, port: int) -> bool:
                 with socket.socket(family, socket.SOCK_STREAM) as s:
                     s.settimeout(1)
                     if s.connect_ex((loopback, port)) == 0:
-                        # Connection succeeded -- port is taken on loopback
+                        # Port is taken on loopback.
                         return False
             except OSError:
-                # IPv6 disabled or other OS-level restriction -- skip
+                # IPv6 disabled or other OS-level restriction -- skip.
                 continue
 
     return True
@@ -500,7 +496,7 @@ def _find_free_port(
     start: int,
     max_attempts: int = 20,
 ) -> int:
-    """Find a free port starting from `start`, trying up to max_attempts ports."""
+    """Find a free port from `start`, trying up to max_attempts ports."""
     for offset in range(max_attempts):
         candidate = start + offset
         if _is_port_free(host, candidate):
@@ -514,7 +510,7 @@ _PID_FILE = _studio_root() / "studio.pid"
 
 # Direct backend launches bypass the CLI's env re-export; do it here for
 # real custom roots so unsloth-zoo's import-time LLAMA_CPP_DEFAULT_DIR
-# picks up the custom build. Skip for legacy-default to avoid flipping
+# picks up the custom build. Skip legacy-default to avoid flipping
 # default-mode installs into env-override.
 try:
     _LEGACY_STUDIO_ROOT = (Path.home() / ".unsloth" / "studio").resolve()
@@ -552,20 +548,20 @@ def _remove_pid_file():
 
 
 def _graceful_shutdown(server = None):
-    """Explicitly shut down all subprocess backends and the uvicorn server.
+    """Shut down all subprocess backends and the uvicorn server.
 
-    Called from signal handlers to ensure child processes are cleaned up
-    before the parent exits. This is critical on Windows where atexit
-    handlers are unreliable after Ctrl+C.
+    Called from signal handlers to clean up child processes before the
+    parent exits. Critical on Windows where atexit handlers are
+    unreliable after Ctrl+C.
     """
     _remove_pid_file()
     logger.info("Graceful shutdown initiated — cleaning up subprocesses...")
 
-    # 1. Shut down uvicorn server (releases the listening socket)
+    # 1. Shut down uvicorn (releases the listening socket).
     if server is not None:
         server.should_exit = True
 
-    # 2. Clean up inference subprocess (if instantiated)
+    # 2. Clean up inference subprocess (if instantiated).
     try:
         from core.inference.orchestrator import _inference_backend
         if _inference_backend is not None:
@@ -573,7 +569,7 @@ def _graceful_shutdown(server = None):
     except Exception as e:
         logger.warning("Error shutting down inference subprocess: %s", e)
 
-    # 3. Clean up export subprocess (if instantiated)
+    # 3. Clean up export subprocess (if instantiated).
     try:
         from core.export.orchestrator import _export_backend
         if _export_backend is not None:
@@ -581,7 +577,7 @@ def _graceful_shutdown(server = None):
     except Exception as e:
         logger.warning("Error shutting down export subprocess: %s", e)
 
-    # 4. Clean up training subprocess (if active)
+    # 4. Clean up training subprocess (if active).
     try:
         from core.training.training import _training_backend
         if _training_backend is not None:
@@ -589,7 +585,7 @@ def _graceful_shutdown(server = None):
     except Exception as e:
         logger.warning("Error shutting down training subprocess: %s", e)
 
-    # 5. Kill llama-server subprocess (if loaded)
+    # 5. Kill llama-server subprocess (if loaded).
     try:
         from routes.inference import _llama_cpp_backend
         if _llama_cpp_backend is not None:
@@ -601,10 +597,10 @@ def _graceful_shutdown(server = None):
 
 
 # The uvicorn server instance -- set by run_server(), used by callers
-# that need to tell the server to exit (e.g. signal handlers).
+# that tell the server to exit (e.g. signal handlers).
 _server = None
 
-# Shutdown event -- used to wake the main loop on signal
+# Shutdown event -- wakes the main loop on signal.
 _shutdown_event = None
 
 
@@ -615,8 +611,8 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
     """Yield `studio/frontend/dist` paths to try when the default is missing.
 
     Covers PATH-shadowed binaries whose __file__ resolves into a
-    site-packages tree that never received a vite build (e.g. plain
-    `pip install unsloth` from PyPI).
+    site-packages tree with no vite build (e.g. plain `pip install
+    unsloth` from PyPI).
     """
     import ast
     import re
@@ -642,9 +638,9 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
                     src = finder.read_text(encoding = "utf-8")
                 except OSError:
                     continue
-                # Tolerate single- or multi-line dict literals; [^}]* still
-                # rejects nested dicts, which the setuptools template never
-                # emits for editable installs.
+                # Tolerate single- or multi-line dict literals; [^}]*
+                # still rejects nested dicts, which the setuptools
+                # template never emits for editable installs.
                 m = re.search(r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S)
                 if not m:
                     continue
@@ -652,8 +648,8 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
                     mapping = ast.literal_eval(m.group(1))
                 except (SyntaxError, ValueError):
                     continue
-                # Defensive: literal_eval can return a set / list / None if the
-                # matched literal is not a dict (regex captures `{...}`).
+                # Defensive: literal_eval can return a set/list/None if
+                # the matched `{...}` literal isn't a dict.
                 if not isinstance(mapping, dict):
                     continue
                 studio_pkg = mapping.get("studio")
@@ -663,10 +659,10 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
 
 
 def _resolve_frontend_path(frontend_path: Path) -> tuple[Optional[Path], list[Path]]:
-    """Pick a frontend dir that actually contains `index.html`.
+    """Pick a frontend dir that contains `index.html`.
 
     Returns (chosen, attempted). `chosen` is None if nothing servable was
-    found; `attempted` is the full ordered list for diagnostics.
+    found; `attempted` is the ordered list for diagnostics.
     """
     attempted: list[Path] = []
     seen: set[Path] = set()
@@ -706,25 +702,25 @@ def run_server(
         port: Port to bind to (auto-increments if in use)
         frontend_path: Path to frontend build directory (optional)
         silent: Suppress startup messages
-        api_only: Run API server only, no frontend serving (for Tauri desktop app)
-        llama_parallel_slots: Number of parallel slots for llama-server
+        api_only: API server only, no frontend (for Tauri desktop app)
+        llama_parallel_slots: parallel slots for llama-server
 
     Note:
-        Signal handlers are NOT registered here so that embedders
-        (e.g. Colab notebooks) keep their own interrupt semantics.
-        Standalone callers should register handlers after calling this.
+        Signal handlers are NOT registered here so embedders (e.g. Colab
+        notebooks) keep their own interrupt semantics. Standalone callers
+        should register handlers after calling this.
     """
     global _server, _shutdown_event
 
-    # On Windows the default console encoding (cp1252) cannot encode emoji.
-    # Reconfigure stdout to UTF-8 so startup messages do not crash the server.
+    # Windows console encoding (cp1252) can't encode emoji. Reconfigure
+    # stdout to UTF-8 so startup messages don't crash the server.
     if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
         try:
             sys.stdout.reconfigure(encoding = "utf-8", errors = "replace")
         except Exception:
             pass
 
-    # Set env var BEFORE importing main so CORS middleware picks it up
+    # Set env var BEFORE importing main so CORS middleware picks it up.
     if api_only:
         os.environ["UNSLOTH_API_ONLY"] = "1"
 
@@ -739,10 +735,10 @@ def run_server(
     from main import app, setup_frontend, _IS_COLAB
     from utils.paths import ensure_studio_directories
 
-    # Create all standard directories on startup
+    # Create all standard directories on startup.
     ensure_studio_directories()
 
-    # Auto-find free port if requested port is in use
+    # Auto-find a free port if the requested one is in use.
     if not _is_port_free(host, port):
         original_port = port
         blocker = _get_pid_on_port(port)
@@ -760,14 +756,14 @@ def run_server(
             print("=" * 50)
             print("")
 
-    # Setup frontend if path provided (skip in api-only mode).
-    # Falls back through alternate locations if the default lacks a built
-    # dist; errors out loudly rather than silently serving 404 on `/`.
+    # Setup frontend if path provided (skip in api-only mode). Falls back
+    # through alternate locations if the default lacks a built dist;
+    # errors loudly rather than serving 404 on `/`.
     if frontend_path and not api_only:
         chosen, attempted = _resolve_frontend_path(Path(frontend_path))
         if chosen is not None and setup_frontend(app, chosen):
             if not silent:
-                # Resolve so logs always show an absolute path for support.
+                # Resolve so logs show an absolute path for support.
                 try:
                     display = chosen.resolve()
                 except OSError:
@@ -779,8 +775,8 @@ def run_server(
                 or os.environ.get("STUDIO_HOME")
                 or str(Path.home() / ".unsloth" / "studio")
             )
-            # Windows ships the user-facing shim at $STUDIO_HOME/bin/unsloth.exe
-            # (a hardlink to the venv exe); Linux/macOS use the venv binary
+            # Windows ships the shim at $STUDIO_HOME/bin/unsloth.exe (a
+            # hardlink to the venv exe); Linux/macOS use the venv binary
             # at $STUDIO_HOME/unsloth_studio/bin/unsloth.
             home = Path(home_str).expanduser()
             if sys.platform == "win32":
@@ -803,7 +799,7 @@ def run_server(
                 "  - reinstall: curl -fsSL https://unsloth.ai/install.sh | sh"
             )
 
-    # Resolve once; shared by the log rewrite and the banner.
+    # Resolve once; shared by the log rewrite and banner.
     display_host = _resolve_external_ip() if host == "0.0.0.0" else host
     _install_uvicorn_startup_log_rewrite(host, display_host)
 
@@ -825,11 +821,11 @@ def run_server(
         access_log = False,
         server_header = False,
     )
-    # Only in Colab: trust X-Forwarded-* from Colab's reverse proxy so the app
-    # sees the real https origin. forwarded_allow_ips="*" is fine inside Colab's
-    # single-user sandbox, but would be an unwanted security relaxation for a
-    # normal local/standalone Studio, so leave uvicorn's safe defaults
-    # (forwarded headers trusted from loopback only) in place there.
+    # Colab only: trust X-Forwarded-* from Colab's reverse proxy so the
+    # app sees the real https origin. forwarded_allow_ips="*" is fine in
+    # Colab's single-user sandbox but an unwanted relaxation for a normal
+    # local/standalone Studio, so leave uvicorn's safe defaults
+    # (forwarded headers trusted from loopback only) elsewhere.
     if _IS_COLAB:
         config_kwargs["proxy_headers"] = True
         config_kwargs["forwarded_allow_ips"] = "*"
@@ -837,17 +833,16 @@ def run_server(
     _server = _ReadyServer(config)
     _shutdown_event = Event()
 
-    # Expose the actual bound port so request-handling code can build
-    # loopback URLs that point at the real backend, not whatever port a
-    # reverse proxy or tunnel exposed in the request URL. Only publish
-    # an explicit value when we know the concrete port; for ephemeral
-    # binds (port==0) leave it unset and let request handlers fall back
-    # to the ASGI request scope or request.base_url.
+    # Expose the actual bound port so request handlers build loopback
+    # URLs pointing at the real backend, not whatever port a proxy/tunnel
+    # exposed in the request URL. Only publish a concrete port; for
+    # ephemeral binds (port==0) leave it unset so handlers fall back to
+    # the ASGI request scope or request.base_url.
     app.state.server_port = port if port and port > 0 else None
     app.state.llama_parallel_slots = llama_parallel_slots
 
-    # Expose a shutdown callable via app.state before the server can accept
-    # requests so /api/shutdown is available as soon as readiness is published.
+    # Expose a shutdown callable via app.state before the server accepts
+    # requests so /api/shutdown is ready as soon as readiness publishes.
     def _trigger_shutdown():
         _graceful_shutdown(_server)
         if _shutdown_event is not None:
@@ -855,11 +850,10 @@ def run_server(
 
     app.state.trigger_shutdown = _trigger_shutdown
 
-    # Run server in a daemon thread.
-    # Use an explicit new_event_loop() + run_until_complete() instead of
-    # asyncio.run() to avoid nest_asyncio's global patches to asyncio.run
-    # interfering when called from a thread while Colab/IPython already has
-    # a running loop on the main thread.
+    # Run server in a daemon thread. Use explicit new_event_loop() +
+    # run_until_complete() rather than asyncio.run() so nest_asyncio's
+    # global patches to asyncio.run don't interfere when called from a
+    # thread while Colab/IPython already runs a loop on the main thread.
     def _run():
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
@@ -876,9 +870,9 @@ def run_server(
     thread = Thread(target = _run, daemon = True)
     thread.start()
 
-    # Wait until uvicorn has completed lifespan startup and bound sockets, or
-    # until the server exits/fails before startup. This intentionally has no
-    # correctness deadline: a slow but live startup should remain in progress.
+    # Wait until uvicorn finishes lifespan startup and binds sockets, or
+    # until the server exits/fails before startup. No correctness
+    # deadline: a slow but live startup should remain in progress.
     try:
         while not ready_event.is_set():
             if startup_failed.is_set() or not thread.is_alive():
@@ -898,8 +892,8 @@ def run_server(
 
     atexit.register(_remove_pid_file)
 
-    # Output port for Tauri to parse when in api-only mode. Emit only after
-    # uvicorn sockets are bound and FastAPI lifespan/startup has completed.
+    # Output port for Tauri to parse in api-only mode. Emit only after
+    # uvicorn sockets are bound and FastAPI startup completed.
     if api_only:
         print(f"TAURI_PORT={port}", flush = True)
 
@@ -909,13 +903,13 @@ def run_server(
     return app
 
 
-# For direct execution (also invoked by CLI via os.execvp / subprocess)
+# For direct execution (also invoked by CLI via os.execvp / subprocess).
 if __name__ == "__main__":
     import argparse
     import signal
     import traceback
 
-    # Ensure stderr can handle Unicode on Windows (tracebacks with non-ASCII paths)
+    # Ensure stderr handles Unicode on Windows (non-ASCII path tracebacks).
     if sys.platform == "win32" and hasattr(sys.stderr, "reconfigure"):
         try:
             sys.stderr.reconfigure(encoding = "utf-8", errors = "replace")
@@ -942,7 +936,7 @@ if __name__ == "__main__":
         help = "API server only, no frontend (for Tauri)",
     )
     # Mirror unsloth_cli/commands/studio.py's _PARALLEL_*. Default 1
-    # applies only to direct backend launches; `unsloth studio run`
+    # applies to direct backend launches only; `unsloth studio run`
     # always passes its own value (4) explicitly.
     _PARALLEL_MIN = 1
     _PARALLEL_MAX = 64
@@ -985,7 +979,7 @@ if __name__ == "__main__":
         sys.stderr.flush()
         sys.exit(1)
 
-    # Signal handler -- ensures subprocess cleanup on Ctrl+C
+    # Signal handler -- ensures subprocess cleanup on Ctrl+C.
     def _signal_handler(signum, frame):
         _graceful_shutdown(_server)
         _shutdown_event.set()
@@ -993,13 +987,13 @@ if __name__ == "__main__":
     signal.signal(signal.SIGINT, _signal_handler)
     signal.signal(signal.SIGTERM, _signal_handler)
 
-    # On Windows, some terminals send SIGBREAK for Ctrl+C / Ctrl+Break
+    # On Windows, some terminals send SIGBREAK for Ctrl+C / Ctrl+Break.
     if hasattr(signal, "SIGBREAK"):
         signal.signal(signal.SIGBREAK, _signal_handler)
 
     # Keep running until shutdown signal.
     # NOTE: Event.wait() without a timeout blocks at the C level on Linux,
-    # which prevents Python from delivering SIGINT (Ctrl+C).  Using a
-    # short timeout in a loop lets the interpreter process pending signals.
+    # preventing Python from delivering SIGINT (Ctrl+C). A short timeout
+    # in a loop lets the interpreter process pending signals.
     while not _shutdown_event.is_set():
         _shutdown_event.wait(timeout = 1)
diff --git a/studio/backend/startup_banner.py b/studio/backend/startup_banner.py
index 2bda4357ba..08ceae1b59 100644
--- a/studio/backend/startup_banner.py
+++ b/studio/backend/startup_banner.py
@@ -3,7 +3,7 @@
 
 """Terminal banner for Studio startup.
 
-Stdlib only — safe to import without the rest of the backend (no structlog/uvicorn).
+Stdlib only — safe to import without the rest of the backend.
 """
 
 from __future__ import annotations
@@ -34,7 +34,7 @@ def print_port_in_use_notice(original_port: int, new_port: int) -> None:
 
 
 def print_studio_stop_hint() -> None:
-    """Print the trailing stop hint + closing divider. Separate from the main
+    """Print the trailing stop hint + closing divider. Separate from the
     banner so callers can interleave content (e.g. a reachability check)."""
     use_color = stdout_supports_color()
     dim = "\033[38;5;245m"
@@ -67,7 +67,7 @@ def print_studio_access_banner(
     display_host: str,
     include_stop_hint: bool = True,
 ) -> None:
-    """Pretty-print URLs after the server is listening. Set
+    """Pretty-print URLs once the server is listening. Set
     ``include_stop_hint=False`` to omit the trailing stop block; pair with
     :func:`print_studio_stop_hint` after inserting your own content."""
     use_color = stdout_supports_color()
@@ -96,8 +96,8 @@ def print_studio_access_banner(
     listen_all = bind_host in ("0.0.0.0", "::")
     loopback_bind = bind_host in ("127.0.0.1", "localhost", "::1")
 
-    # Use loopback URL only when the server is reachable on loopback;
-    # otherwise show the actual bound address.
+    # Use the loopback URL only when reachable on loopback; otherwise show
+    # the actual bound address.
     primary_url = loopback_url if listen_all or loopback_bind else external_url
     tip_url = alt_local if listen_all or loopback_bind else external_url
     api_base = primary_url
diff --git a/studio/backend/storage/mcp_servers_db.py b/studio/backend/storage/mcp_servers_db.py
index 9dd90a58bb..bbd7186ed4 100644
--- a/studio/backend/storage/mcp_servers_db.py
+++ b/studio/backend/storage/mcp_servers_db.py
@@ -28,7 +28,7 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    # use_oauth was added after the first release; backfill for pre-existing DBs.
+    # use_oauth added after the first release; backfill for pre-existing DBs.
     cols = {r["name"] for r in conn.execute("PRAGMA table_info(mcp_servers)").fetchall()}
     if "use_oauth" not in cols:
         conn.execute("ALTER TABLE mcp_servers ADD COLUMN use_oauth INTEGER NOT NULL DEFAULT 0")
diff --git a/studio/backend/storage/providers_db.py b/studio/backend/storage/providers_db.py
index 3c6056fb8d..e58133090d 100644
--- a/studio/backend/storage/providers_db.py
+++ b/studio/backend/storage/providers_db.py
@@ -4,8 +4,8 @@
 """
 SQLite storage for external LLM provider configurations.
 
-Follows the same pattern as studio_db.py — module-level functions,
-raw sqlite3, WAL mode, per-function connections.
+Same pattern as studio_db.py: module-level functions, raw sqlite3, WAL
+mode, per-function connections.
 
 NOTE: API keys are NOT stored here. They live only in the browser
 (localStorage) and are sent encrypted per-request.
@@ -26,7 +26,7 @@ _schema_ready = False
 
 
 def _ensure_schema(conn: sqlite3.Connection) -> None:
-    """Create the llm_providers table if it doesn't exist. Called once per process."""
+    """Create the llm_providers table if absent. Called once per process."""
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute(
         """
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index 5f0d6449d5..d3900387d4 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -4,8 +4,8 @@
 """
 SQLite storage for training run history and metrics.
 
-Follows the same pattern as auth/storage.py — module-level functions,
-raw sqlite3, per-function connections. Enhancements over auth:
+Same pattern as auth/storage.py — module-level functions, raw sqlite3,
+per-function connections. Enhancements over auth:
   - WAL mode for concurrent read/write access
   - PRAGMA foreign_keys = ON for CASCADE deletes
 """
@@ -34,8 +34,8 @@ def _denied_path_prefixes() -> list[str]:
     if system == "Linux":
         return ["/proc", "/sys", "/dev", "/etc", "/boot", "/run"]
     if system == "Darwin":
-        # realpath() resolves /etc -> /private/etc, /tmp -> /private/tmp on macOS,
-        # so include the /private variants to avoid bypasses.
+        # realpath() resolves /etc -> /private/etc, /tmp -> /private/tmp on
+        # macOS, so include the /private variants to avoid bypasses.
         return [
             "/System",
             "/Library",
@@ -174,9 +174,9 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         """
     )
     conn.execute("CREATE INDEX IF NOT EXISTS idx_metrics_run_id ON training_metrics(run_id)")
-    # Use COLLATE NOCASE on Windows so C:\Models and c:\models dedup via the
-    # UNIQUE constraint.  On Linux/macOS (case-sensitive FS) keep the default
-    # BINARY collation so /Models and /models remain distinct.
+    # COLLATE NOCASE on Windows so C:\Models and c:\models dedup via the
+    # UNIQUE constraint. On Linux/macOS (case-sensitive FS) keep the default
+    # BINARY collation so /Models and /models stay distinct.
     collation = "COLLATE NOCASE" if platform.system() == "Windows" else ""
     conn.execute(
         f"""
@@ -287,15 +287,14 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    # Server-side import ledger so a studio.db wipe correctly re-triggers
-    # the legacy Dexie import. The previous boolean localStorage sentinel
-    # (`unsloth_chat_legacy_imported_to_studio_db`) is non-recoverable:
-    # if studio.db is recreated while the browser keeps the flag, legacy
-    # Dexie threads are silently hidden from the sidebar. The ledger
-    # lives inside studio.db so it disappears together with the data it
-    # is supposed to track, which is the recovery the boolean lacked.
-    # Keyed by legacy thread id; per-thread is sufficient because Dexie
-    # is read-only after this PR (a thread's message set does not grow).
+    # Server-side import ledger so a studio.db wipe re-triggers the legacy
+    # Dexie import. The old boolean localStorage sentinel
+    # (`unsloth_chat_legacy_imported_to_studio_db`) was non-recoverable: if
+    # studio.db is recreated while the browser keeps the flag, legacy Dexie
+    # threads are silently hidden from the sidebar. The ledger lives inside
+    # studio.db so it disappears with the data it tracks -- the recovery the
+    # boolean lacked. Keyed by legacy thread id; per-thread suffices because
+    # Dexie is read-only after this PR (a thread's message set doesn't grow).
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS chat_legacy_imports (
@@ -313,7 +312,7 @@ def get_connection() -> sqlite3.Connection:
     ensure_dir(db_path.parent)
     conn = sqlite3.connect(str(db_path))
     conn.row_factory = sqlite3.Row
-    # foreign_keys is session-scoped, must be set per connection
+    # foreign_keys is session-scoped; set per connection
     conn.execute("PRAGMA foreign_keys=ON")
     if not _schema_ready:
         with _schema_lock:
@@ -701,9 +700,9 @@ def add_scan_folder(path: str) -> dict:
     if not os.access(normalized, os.R_OK | os.X_OK):
         raise ValueError("Path is not readable")
 
-    # On Windows, use normcase for denylist comparison but store the
-    # original-cased path so downstream consumers see the native
-    # drive-letter casing the user expects (e.g. C:\Models, not c:\models).
+    # On Windows, normcase for the denylist comparison but store the
+    # original-cased path so downstream consumers see the native drive-letter
+    # casing the user expects (e.g. C:\Models, not c:\models).
     is_win = platform.system() == "Windows"
     check = os.path.normcase(normalized) if is_win else normalized
     for prefix in _denied_path_prefixes():
@@ -713,8 +712,8 @@ def add_scan_folder(path: str) -> dict:
     conn = get_connection()
     try:
         now = datetime.now(timezone.utc).isoformat()
-        # On Windows, use case-insensitive lookup so C:\Models and c:\models
-        # dedup correctly while preserving the originally-stored casing.
+        # On Windows, case-insensitive lookup so C:\Models and c:\models dedup
+        # while preserving the originally-stored casing.
         if is_win:
             existing = conn.execute(
                 "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE",
@@ -735,8 +734,8 @@ def add_scan_folder(path: str) -> dict:
             conn.commit()
         except sqlite3.IntegrityError:
             pass  # duplicate -- fall through to SELECT
-        # Use the same collation as the pre-check so we find the row even
-        # when a concurrent writer stored it with different casing (Windows).
+        # Same collation as the pre-check so we find the row even when a
+        # concurrent writer stored it with different casing (Windows).
         fallback_sql = (
             "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE"
             if is_win
@@ -1408,8 +1407,8 @@ def _deep_merge_settings(current: dict[str, Any], updates: dict[str, Any]) -> di
 
 
 def upsert_chat_settings_merge(updates: dict[str, Any]) -> dict[str, Any]:
-    """Atomic read-merge-write under BEGIN IMMEDIATE so two concurrent writers
-    cannot drop one another's updates."""
+    """Atomic read-merge-write under BEGIN IMMEDIATE so concurrent writers
+    cannot drop each other's updates."""
     if not updates:
         return list_chat_settings()
     conn = get_connection()
@@ -1457,8 +1456,8 @@ def upsert_chat_settings_merge(updates: dict[str, Any]) -> dict[str, Any]:
 def list_chat_legacy_imports() -> list[str]:
     """Return the legacy_thread_id of every thread already imported.
 
-    Cheap: scans a single small PK-only table. The frontend stuffs the
-    result into a Set before walking Dexie, so the diff is O(|Dexie|).
+    Cheap: scans one small PK-only table. The frontend puts the result in a
+    Set before walking Dexie, so the diff is O(|Dexie|).
     """
     conn = get_connection()
     try:
@@ -1472,13 +1471,13 @@ def upsert_chat_legacy_imports(legacy_thread_ids: list[str]) -> tuple[int, int]:
     """Mark each given legacy thread id as imported. Idempotent.
 
     Returns (accepted, inserted):
-      - accepted: number of non-empty deduped input ids
-      - inserted: number of rows that were actually new (not already in ledger)
+      - accepted: count of non-empty deduped input ids
+      - inserted: count of rows that were actually new (not already in ledger)
 
     ON CONFLICT DO NOTHING keeps the existing imported_at when an id is
-    recorded twice. INSERT...RETURNING reports only the rows that were
-    actually inserted, so callers can distinguish first-time imports
-    from idempotent re-runs without an extra SELECT.
+    recorded twice. INSERT...RETURNING reports only newly-inserted rows, so
+    callers distinguish first-time imports from idempotent re-runs without an
+    extra SELECT.
     """
     ids = list(dict.fromkeys(tid for tid in legacy_thread_ids if tid))
     if not ids:
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index 6aa6d314c1..d903e04514 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -7,19 +7,19 @@ Shared pytest configuration for the backend test suite.
 Responsibilities:
 1. Put the backend root on sys.path so `from models.inference import ...`
    (and similar flat imports) resolve in test modules — mirrors how the
-   app itself is launched.
+   app is launched.
 2. Provide a hybrid ``studio_server`` session fixture for end-to-end tests
-   (see ``test_studio_api.py``). The fixture supports two invocation modes:
+   (see ``test_studio_api.py``), supporting two invocation modes:
 
    a. **External server.** If ``UNSLOTH_E2E_BASE_URL`` is set, tests point
-      at an already-running Studio instance. ``UNSLOTH_E2E_API_KEY`` must
-      also be set. This is the fast-iteration mode: start the server once
-      with ``unsloth studio run ...``, then run pytest against it many
-      times with no per-run GGUF load cost.
+      at an already-running Studio instance (``UNSLOTH_E2E_API_KEY`` must
+      also be set). Fast-iteration mode: start the server once with
+      ``unsloth studio run ...``, then run pytest against it many times with
+      no per-run GGUF load cost.
 
-   b. **Fixture-managed server.** Otherwise, the fixture launches a fresh
-      server via ``_start_server`` and tears it down at session end. This
-      is the one-shot mode for CI or a clean-slate verification run.
+   b. **Fixture-managed server.** Otherwise the fixture launches a fresh
+      server via ``_start_server`` and tears it down at session end. One-shot
+      mode for CI or a clean-slate verification run.
 
    The model / variant for mode (b) come from ``--unsloth-model`` /
    ``--unsloth-gguf-variant`` pytest options, then ``UNSLOTH_E2E_MODEL`` /
@@ -80,16 +80,16 @@ def studio_server(request):
 
     Resolution order:
 
-    1. If ``UNSLOTH_E2E_BASE_URL`` is set → point at that server,
-       require ``UNSLOTH_E2E_API_KEY`` alongside (skip if missing).
-    2. Otherwise → start a fresh ``unsloth studio run`` subprocess via
-       the existing ``_start_server`` helper in ``test_studio_api.py``
-       and tear it down on session teardown.
+    1. If ``UNSLOTH_E2E_BASE_URL`` is set → point at that server, requiring
+       ``UNSLOTH_E2E_API_KEY`` alongside (skip if missing).
+    2. Otherwise → start a fresh ``unsloth studio run`` subprocess via the
+       ``_start_server`` helper in ``test_studio_api.py`` and tear it down on
+       session teardown.
 
-    Session-scoped so the expensive GGUF load happens at most once per
-    pytest invocation. Lazily instantiated — tests that don't request
-    the fixture (e.g. the unit tests in ``test_anthropic_messages.py``
-    or ``test_help_output``) do not trigger server startup.
+    Session-scoped so the expensive GGUF load happens at most once per pytest
+    invocation. Lazy — tests that don't request the fixture (e.g. the unit
+    tests in ``test_anthropic_messages.py`` or ``test_help_output``) don't
+    trigger server startup.
     """
     external_url = os.environ.get("UNSLOTH_E2E_BASE_URL")
     if external_url:
@@ -103,9 +103,9 @@ def studio_server(request):
         yield external_url, api_key
         return
 
-    # Lazy import: pytest has already loaded test_studio_api into
-    # sys.modules by the time any test requests this fixture, so this
-    # is a cache hit, not a re-execution.
+    # Lazy import: pytest has already loaded test_studio_api into sys.modules
+    # by the time any test requests this fixture, so this is a cache hit, not
+    # a re-execution.
     import test_studio_api as _e2e
 
     model = (
diff --git a/studio/backend/tests/test_anthropic_cache_ttl.py b/studio/backend/tests/test_anthropic_cache_ttl.py
index e5d806e3c2..895c598546 100644
--- a/studio/backend/tests/test_anthropic_cache_ttl.py
+++ b/studio/backend/tests/test_anthropic_cache_ttl.py
@@ -1,18 +1,17 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Unit tests for the prompt_cache_ttl threading on the Anthropic path.
+"""Unit tests for prompt_cache_ttl threading on the Anthropic path.
 
 Anthropic accepts an optional ``ttl`` on each ``cache_control`` marker:
-the default is the 5-minute ephemeral pool; ``ttl:"1h"`` writes into
-the 1-hour pool instead. The 1h pool is the right pick when
-conversations span multiple short bursts more than 5 minutes apart --
-1h writes are billed at 2x base input vs 1.25x for 5m, but reads stay
-at 0.1x for both, so one extra read pays off the premium.
+default is the 5-minute ephemeral pool; ``ttl:"1h"`` writes into the
+1-hour pool. The 1h pool fits conversations spanning short bursts more
+than 5 minutes apart -- 1h writes bill at 2x base input vs 1.25x for 5m,
+but reads stay at 0.1x for both, so one extra read pays the premium.
 
-These tests pin the outbound body shape: when prompt_cache_ttl="1h"
-both cache_control markers carry ``ttl:"1h"``; default omits the field
-entirely so the 5m pool is used; garbage values are silently dropped.
+These tests pin the outbound body shape: prompt_cache_ttl="1h" puts
+``ttl:"1h"`` on both markers; default omits the field (5m pool); garbage
+values are silently dropped.
 """
 
 import asyncio
@@ -128,13 +127,12 @@ def test_1h_ttl_writes_into_1h_pool(monkeypatch):
 
 
 def test_1h_ttl_does_not_send_extended_cache_ttl_beta_header(monkeypatch):
-    # The `extended-cache-ttl-2025-04-11` beta header that originally
-    # gated 1h cache TTL has been promoted to GA: verified live against
-    # api.anthropic.com on 2026-05-22 -- a request with
-    # `cache_control:{type:"ephemeral", ttl:"1h"}` and NO beta header
-    # returns 200 and populates `ephemeral_1h_input_tokens`. Pin the
-    # contract so we don't reintroduce the gate by accident; a future
-    # regression that re-adds the header would surface here.
+    # The `extended-cache-ttl-2025-04-11` beta header that originally gated
+    # 1h cache TTL is now GA: verified live against api.anthropic.com on
+    # 2026-05-22 -- a request with `cache_control:{type:"ephemeral",
+    # ttl:"1h"}` and NO beta header returns 200 and populates
+    # `ephemeral_1h_input_tokens`. Pin the contract so a regression that
+    # re-adds the header surfaces here.
     captured = _capture(monkeypatch, ttl = "1h")
     beta = captured["headers"].get("anthropic-beta", "")
     assert "extended-cache-ttl-2025-04-11" not in beta, beta
@@ -156,7 +154,7 @@ def test_unknown_ttl_silently_dropped(monkeypatch, bogus):
     assert len(ccs) == 2, ccs
     for cc in ccs:
         # Bogus TTLs must NOT round-trip; marker stays at the default
-        # (no `ttl` key, which means the 5m pool upstream).
+        # (no `ttl` key = 5m pool upstream).
         assert cc == {"type": "ephemeral"}, cc
 
 
diff --git a/studio/backend/tests/test_anthropic_citations.py b/studio/backend/tests/test_anthropic_citations.py
index ab5ba10b56..c6104f2425 100644
--- a/studio/backend/tests/test_anthropic_citations.py
+++ b/studio/backend/tests/test_anthropic_citations.py
@@ -3,11 +3,10 @@
 
 """Tests for Anthropic ``citations_delta`` handling in the streaming proxy.
 
-Verifies the proxy injects inline ``[N]`` markers after cited text,
-dedupes by type-specific anchor (char_location, page_location,
-content_block_location, search_result_location), forwards a synthetic
-``document_citations`` tool_event at message_stop, and stays inert when
-no citations_delta events fire. See
+Verifies the proxy injects inline ``[N]`` markers after cited text, dedupes by
+type-specific anchor (char_location, page_location, content_block_location,
+search_result_location), forwards a synthetic ``document_citations`` tool_event
+at message_stop, and stays inert when no citations_delta events fire. See
 https://platform.claude.com/docs/en/build-with-claude/citations
 """
 
diff --git a/studio/backend/tests/test_anthropic_citations_edge.py b/studio/backend/tests/test_anthropic_citations_edge.py
index 6b10600847..f89e5ebda8 100644
--- a/studio/backend/tests/test_anthropic_citations_edge.py
+++ b/studio/backend/tests/test_anthropic_citations_edge.py
@@ -50,10 +50,9 @@ def _capture(
     messages: list[dict] | None = None,
     captured_body: dict | None = None,
 ) -> list[str]:
-    """Drive ``stream_chat_completion`` against a mocked Anthropic
-    response and return the SSE lines. Pass ``captured_body`` to also
-    capture the outgoing request body for assertions on the translated
-    Anthropic shape.
+    """Drive ``stream_chat_completion`` against a mocked Anthropic response
+    and return the SSE lines. Pass ``captured_body`` to also capture the
+    outgoing request body for assertions on the translated Anthropic shape.
     """
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -147,8 +146,8 @@ def _joined(lines: list[str]) -> str:
 
 
 def _citation_payload(body: str) -> dict:
-    """Pull the ``document_citations`` synthetic tool_event from the
-    SSE body and return its payload. Raises if absent."""
+    """Return the ``document_citations`` synthetic tool_event payload from
+    the SSE body. Raises if absent."""
     assert "document_citations" in body, body
     for line in body.splitlines():
         if not line.startswith("data: "):
@@ -167,8 +166,8 @@ def _citation_payload(body: str) -> dict:
 
 
 def test_citation_with_no_preceding_text_still_emits_marker(monkeypatch):
-    """citations_delta before any text_delta must not crash; marker
-    lands at the start of the block."""
+    """citations_delta before any text_delta must not crash; marker lands
+    at the start of the block."""
     cit = {
         "type": "char_location",
         "document_index": 0,
@@ -195,8 +194,8 @@ def test_citation_with_no_preceding_text_still_emits_marker(monkeypatch):
 
 
 def test_citations_delta_with_non_dict_citation_is_ignored(monkeypatch):
-    """Non-dict ``delta.citation`` must not crash, emit a marker, or
-    poison the document_citations list."""
+    """Non-dict ``delta.citation`` must not crash, emit a marker, or poison
+    the document_citations list."""
     lines = _capture(
         monkeypatch,
         [
@@ -220,8 +219,8 @@ def test_citations_delta_with_non_dict_citation_is_ignored(monkeypatch):
 
 
 def test_citations_delta_with_missing_citation_field_is_ignored(monkeypatch):
-    """Missing ``citation`` field is treated like a non-dict citation:
-    skip without crashing."""
+    """Missing ``citation`` field is treated like a non-dict citation: skip
+    without crashing."""
     lines = _capture(
         monkeypatch,
         [
@@ -245,8 +244,8 @@ def test_citations_delta_with_missing_citation_field_is_ignored(monkeypatch):
 
 
 def test_char_location_with_reversed_indices_does_not_crash(monkeypatch):
-    """Malformed char_location with reversed indices must not crash;
-    the dedup key accepts any int pair and still surfaces a footnote."""
+    """Malformed char_location with reversed indices must not crash; the
+    dedup key accepts any int pair and still surfaces a footnote."""
     cit = {
         "type": "char_location",
         "document_index": 0,
@@ -275,8 +274,8 @@ def test_char_location_with_reversed_indices_does_not_crash(monkeypatch):
 
 
 def test_page_location_missing_document_index_does_not_crash(monkeypatch):
-    """page_location missing ``document_index`` still produces a
-    footnote; dedup key falls back to ``None`` for the missing field."""
+    """page_location missing ``document_index`` still produces a footnote;
+    dedup key falls back to ``None`` for the missing field."""
     cit = {
         "type": "page_location",
         "document_title": "Untitled PDF",
@@ -303,8 +302,8 @@ def test_page_location_missing_document_index_does_not_crash(monkeypatch):
 
 
 def test_content_block_location_with_non_int_block_index_does_not_crash(monkeypatch):
-    """content_block_location with string block indices must not crash;
-    dedup key tolerates non-int values."""
+    """content_block_location with string block indices must not crash; dedup
+    key tolerates non-int values."""
     cit = {
         "type": "content_block_location",
         "document_index": 0,
@@ -332,8 +331,8 @@ def test_content_block_location_with_non_int_block_index_does_not_crash(monkeypa
 
 
 def test_unknown_citation_type_falls_back_to_stringified_key(monkeypatch):
-    """Unknown citation ``type`` (forward-compat) still dedupes:
-    identical ones collapse, differing ones get distinct numbers."""
+    """Unknown citation ``type`` (forward-compat) still dedupes: identical
+    ones collapse, differing ones get distinct numbers."""
     cit_a = {
         "type": "future_shape_location",
         "anchor": "abc",
@@ -369,8 +368,8 @@ def test_unknown_citation_type_falls_back_to_stringified_key(monkeypatch):
 
 
 def test_mixed_citation_types_same_document_get_distinct_keys(monkeypatch):
-    """char_location and page_location on the same document_index are
-    distinct shapes; dedup key uses citation type as its first slot."""
+    """char_location and page_location on the same document_index are distinct
+    shapes; dedup key uses citation type as its first slot."""
     cit_char = {
         "type": "char_location",
         "document_index": 0,
@@ -406,9 +405,9 @@ def test_mixed_citation_types_same_document_get_distinct_keys(monkeypatch):
 
 
 def test_cited_text_is_preserved_in_synthetic_event(monkeypatch):
-    """``cited_text`` must survive into the synthetic event so the
-    Sources panel can render it as a tooltip. Anthropic does not bill
-    cited_text against output tokens, so preserving it is free."""
+    """``cited_text`` must survive into the synthetic event so the Sources
+    panel can render it as a tooltip. Anthropic does not bill cited_text
+    against output tokens, so preserving it is free."""
     cit = {
         "type": "char_location",
         "document_index": 0,
@@ -435,8 +434,8 @@ def test_cited_text_is_preserved_in_synthetic_event(monkeypatch):
 
 
 def test_internal_key_field_never_leaks_to_client(monkeypatch):
-    """The internal ``_key`` dedup sentinel must be stripped before
-    the synthetic event is forwarded; it is not an Anthropic field."""
+    """The internal ``_key`` dedup sentinel must be stripped before the
+    synthetic event is forwarded; it is not an Anthropic field."""
     cit = {
         "type": "char_location",
         "document_index": 0,
@@ -465,8 +464,8 @@ def test_internal_key_field_never_leaks_to_client(monkeypatch):
 
 
 def test_citation_across_multiple_content_blocks_numbers_continue(monkeypatch):
-    """Footnote numbering is per-message, not per-content-block:
-    citations across separate blocks emit [1] then [2]."""
+    """Footnote numbering is per-message, not per-content-block: citations
+    across separate blocks emit [1] then [2]."""
     cit_a = {
         "type": "char_location",
         "document_index": 0,
@@ -509,9 +508,9 @@ def test_citation_across_multiple_content_blocks_numbers_continue(monkeypatch):
 
 
 def test_inline_marker_lands_after_text_run(monkeypatch):
-    """Inline ``[N]`` must land AFTER the cited text run: Anthropic
-    streams text then citation, so the proxy emits ``"...green.[1]"``
-    not ``"[1]green"``."""
+    """Inline ``[N]`` must land AFTER the cited text run: Anthropic streams
+    text then citation, so the proxy emits ``"...green.[1]"`` not
+    ``"[1]green"``."""
     cit = {
         "type": "char_location",
         "document_index": 0,
@@ -541,8 +540,8 @@ def test_inline_marker_lands_after_text_run(monkeypatch):
 
 
 def test_no_synthetic_event_when_only_text_deltas(monkeypatch):
-    """No citations_delta means no synthetic ``document_citations``
-    event; Sources panel relies on absence to suppress the section."""
+    """No citations_delta means no synthetic ``document_citations`` event;
+    Sources panel relies on absence to suppress the section."""
     lines = _capture(
         monkeypatch,
         [
@@ -561,9 +560,9 @@ def test_no_synthetic_event_when_only_text_deltas(monkeypatch):
 
 
 def test_input_document_translation_enables_citations(monkeypatch):
-    """``input_document`` must translate to an Anthropic ``document``
-    block carrying ``citations: {enabled: true}`` (both base64 and url
-    source branches) so upstream emits citations_delta."""
+    """``input_document`` must translate to an Anthropic ``document`` block
+    carrying ``citations: {enabled: true}`` (both base64 and url source
+    branches) so upstream emits citations_delta."""
     captured_b64: dict = {}
     _capture(
         monkeypatch,
@@ -631,8 +630,8 @@ def test_input_document_translation_enables_citations(monkeypatch):
 
 
 def test_cited_text_truncated_in_synthetic_event(monkeypatch):
-    """``cited_text`` is capped server-side so multi-KB spans do not
-    balloon the SSE payload."""
+    """``cited_text`` is capped server-side so multi-KB spans don't balloon
+    the SSE payload."""
     from core.inference.external_provider import _CITED_TEXT_MAX_LEN
 
     long_quote = "x" * (_CITED_TEXT_MAX_LEN + 4000)
diff --git a/studio/backend/tests/test_anthropic_code_execution.py b/studio/backend/tests/test_anthropic_code_execution.py
index dd2f2eef6c..cc0fb21deb 100644
--- a/studio/backend/tests/test_anthropic_code_execution.py
+++ b/studio/backend/tests/test_anthropic_code_execution.py
@@ -6,20 +6,18 @@ Unit tests for Anthropic's server-side `code_execution_20250825` tool
 translation in `_stream_anthropic`.
 
 Covers:
-- Request body: when ``enabled_tools=["code_execution"]``, the outbound
-  ``tools`` array carries ``{"type": "code_execution_20250825", "name":
-  "code_execution"}`` and the ``anthropic-beta`` header includes
-  ``code-execution-2025-08-25``.
-- Combined request: ``enabled_tools=["web_search", "code_execution"]``
-  sends both tool entries; the beta header still merges the code-exec
-  flag onto whatever the registry contributed.
-- SSE translation: a `bash_code_execution` server_tool_use +
+- Request body: ``enabled_tools=["code_execution"]`` puts ``{"type":
+  "code_execution_20250825", "name": "code_execution"}`` in the outbound
+  ``tools`` and ``code-execution-2025-08-25`` in the ``anthropic-beta``
+  header.
+- Combined: ``["web_search", "code_execution"]`` sends both tool entries;
+  the beta header merges the code-exec flag onto the registry's.
+- SSE: a `bash_code_execution` server_tool_use +
   `bash_code_execution_tool_result` pair emits one tool_start and one
-  tool_end ``_toolEvent`` chunk with the expected arguments and result.
-- SSE translation: a `text_editor_code_execution` create + result emits
-  a tool_start with ``kind="text_editor"`` + parsed args, and tool_end
-  with ``"Created"`` (or ``"Updated"``) based on the ``is_file_update``
-  flag.
+  tool_end ``_toolEvent`` chunk with the expected args and result.
+- SSE: a `text_editor_code_execution` create + result emits a tool_start
+  with ``kind="text_editor"`` + parsed args, and tool_end with
+  ``"Created"`` (or ``"Updated"``) per the ``is_file_update`` flag.
 - Error path: a ``bash_code_execution_tool_result_error`` with
   ``error_code="container_expired"`` renders as ``"Error:
   container_expired"`` in the tool_end ``result``.
@@ -116,13 +114,13 @@ def test_code_execution_tool_appended_to_request_body(monkeypatch):
 
     body = captured["body"]
     tools = body.get("tools") or []
-    # Opus 4.7 gets the newer date-pinned variant (`_20260120`) that
-    # supports REPL state persistence + programmatic tool calling.
+    # Opus 4.7 gets the newer date-pinned variant (`_20260120`) with REPL
+    # state persistence + programmatic tool calling.
     assert {"type": "code_execution_20260120", "name": "code_execution"} in tools
     # No web_search entry when only code_execution is enabled.
     assert all("web_search" not in (t.get("type") or "") for t in tools)
-    # Beta header still carries the documented flag; both `_20250825`
-    # and `_20260120` are unlocked by the same header per upstream docs.
+    # Beta header still carries the flag; both `_20250825` and `_20260120`
+    # are unlocked by the same header per upstream docs.
     beta_header = captured["headers"].get("anthropic-beta", "")
     assert "code-execution-2025-08-25" in beta_header
 
@@ -193,11 +191,11 @@ def test_no_code_execution_tool_when_pill_off(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    # Pill off -- neither the legacy nor the new code_execution variant
-    # may appear on the wire.
+    # Pill off -- neither the legacy nor new code_execution variant may
+    # appear on the wire.
     assert all("code_execution" not in (t.get("type") or "") for t in tools)
-    # Beta header must NOT mention code-execution when the tool isn't on
-    # -- that flag is opt-in only.
+    # Beta header must NOT mention code-execution when the tool is off --
+    # that flag is opt-in only.
     assert "code-execution-2025-08-25" not in captured["headers"].get("anthropic-beta", "")
 
 
@@ -270,8 +268,8 @@ def test_bash_code_execution_emits_tool_start_and_end(monkeypatch):
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "code_execution"
     assert start["tool_call_id"] == "srvtoolu_1"
-    # `_server_tool: True` marks this as a provider-side synthetic
-    # tool card for the frontend's history serializer.
+    # `_server_tool: True` marks a provider-side synthetic tool card for
+    # the frontend's history serializer.
     assert start["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
 
     assert end["type"] == "tool_end"
diff --git a/studio/backend/tests/test_anthropic_compaction.py b/studio/backend/tests/test_anthropic_compaction.py
index 6da752eac4..5047a93979 100644
--- a/studio/backend/tests/test_anthropic_compaction.py
+++ b/studio/backend/tests/test_anthropic_compaction.py
@@ -4,15 +4,15 @@
 """Unit tests for Anthropic server-side context compaction wiring.
 
 Compaction is a beta feature (header ``compact-2026-01-12``) gated to
-Opus 4.6, Opus 4.7, Sonnet 4.6, and Mythos preview. When enabled,
-Studio attaches ``context_management.edits[{type:"compact_20260112",
-trigger:{type:"input_tokens", value:N}}]`` to the outbound body. The
-minimum upstream-accepted threshold is 50k tokens; lower values are
-clamped to 50k so the request doesn't 400.
+Opus 4.6, Opus 4.7, Sonnet 4.6, and Mythos preview. When enabled, Studio
+attaches ``context_management.edits[{type:"compact_20260112",
+trigger:{type:"input_tokens", value:N}}]`` to the outbound body. Minimum
+upstream threshold is 50k tokens; lower values are clamped to 50k so the
+request doesn't 400.
 
-These tests pin: the body shape per model, the beta header merge with
-the existing code-execution beta, threshold clamping, and silent no-op
-on unsupported models.
+These tests pin: body shape per model, the beta header merge with the
+code-execution beta, threshold clamping, and silent no-op on unsupported
+models.
 """
 
 import asyncio
@@ -168,10 +168,9 @@ def test_omitted_threshold_no_body_field(monkeypatch):
 
 
 def test_chat_completion_request_accepts_sub_50k_compaction_threshold():
-    # Codex P1 caught that ge=50_000 on the field caused FastAPI to
-    # 422 the request before the in-helper clamp could fire. The
-    # schema must accept any positive int and let _stream_anthropic
-    # clamp upward.
+    # Codex P1 caught that ge=50_000 on the field made FastAPI 422 the
+    # request before the in-helper clamp could fire. The schema must
+    # accept any positive int and let _stream_anthropic clamp upward.
     from models.inference import ChatCompletionRequest
 
     req = ChatCompletionRequest.model_validate(
@@ -209,13 +208,12 @@ def test_chat_completion_request_accepts_sub_50k_compaction_threshold():
 
 def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch, capsys):
     # When Anthropic compacts mid-stream, the SSE message_delta usage
-    # payload carries `iterations: [{type:"compaction", ...}, ...]`.
-    # The top-level input_tokens / output_tokens only account for the
-    # `message` iteration, so the cost surface needs the compaction
-    # totals exposed separately. The stream helper folds them into
-    # last_usage as `compaction_input_tokens` / `compaction_output_tokens`
-    # and surfaces them in the closing summary log so an operator can
-    # eyeball "did compaction cost us 180k tokens this turn?".
+    # carries `iterations: [{type:"compaction", ...}, ...]`. The top-level
+    # input_tokens / output_tokens only cover the `message` iteration, so
+    # compaction totals need to be exposed separately. The stream helper
+    # folds them into last_usage as `compaction_input_tokens` /
+    # `compaction_output_tokens` and surfaces them in the closing summary
+    # log so an operator can see "did compaction cost us 180k tokens?".
 
     def http_handler(request: httpx.Request) -> httpx.Response:
         body = (
@@ -258,8 +256,8 @@ def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch
 
     _drive(run())
 
-    # structlog renders the closing summary through the stdlib bridge,
-    # which lands on stdout. Capture and check the rendered line.
+    # structlog renders the closing summary via the stdlib bridge onto
+    # stdout. Capture and check the rendered line.
     out = capsys.readouterr().out
     summary = next(
         (line for line in out.splitlines() if "Anthropic stream complete" in line),
@@ -271,8 +269,8 @@ def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch
 
 def test_message_delta_no_iterations_leaves_compaction_keys_unset(monkeypatch, capsys):
     # Re-applying a previous compaction block does NOT emit a fresh
-    # iterations array. The helper must not invent compaction keys
-    # in that case (would otherwise double-bill).
+    # iterations array. The helper must not invent compaction keys then
+    # (would otherwise double-bill).
     def http_handler(request: httpx.Request) -> httpx.Response:
         body = (
             b"event: message_delta\n"
@@ -331,19 +329,17 @@ def _async_collect(agen):
 
 
 def test_compaction_block_emitted_as_tool_event(monkeypatch):
-    # Codex P1: once context_management is enabled and Anthropic runs
-    # compaction during a turn, the response carries a
-    # `{type:"compaction", content:"<summary>"}` block. The translator
-    # must surface it so the chat-adapter can persist it onto the
-    # assistant message; otherwise the next turn loses the state and
-    # Anthropic re-compacts from scratch.
+    # Codex P1: once context_management is enabled and Anthropic compacts
+    # during a turn, the response carries a `{type:"compaction",
+    # content:"<summary>"}` block. The translator must surface it so the
+    # chat-adapter persists it onto the assistant message; otherwise the
+    # next turn loses the state and Anthropic re-compacts from scratch.
 
     def http_handler(request: httpx.Request) -> httpx.Response:
-        # Anthropic ships compaction blocks as a content_block_start
-        # with `type:"compaction"`, then either includes the summary
-        # on that start event AND/OR streams it via text_delta events
-        # on the same block index. Test the streamed-delta path since
-        # it's the harder case.
+        # Anthropic ships compaction blocks as a content_block_start with
+        # `type:"compaction"`, then includes the summary on that start
+        # event AND/OR streams it via text_delta events on the same block
+        # index. Test the streamed-delta path since it's the harder case.
         body = (
             b"event: message_start\n"
             b'data: {"type":"message_start","message":{"usage":{}}}\n\n'
@@ -411,8 +407,8 @@ def test_compaction_block_emitted_as_tool_event(monkeypatch):
         except json.JSONDecodeError:
             continue
         # tool_event payloads ride inside chat.completion.chunk.choices[0].delta.content
-        # as a JSON-encoded string. The simpler path: look for the
-        # marker substring anywhere in the chunk.
+        # as a JSON-encoded string. Simpler: look for the marker substring
+        # anywhere in the chunk.
         if "compaction_block" in raw:
             events.append(raw)
     assert events, f"no compaction_block tool event found in {lines}"
@@ -445,10 +441,10 @@ def test_compaction_block_emitted_as_tool_event(monkeypatch):
 
 
 def test_compaction_block_round_trips_through_outbound_messages(monkeypatch):
-    # Once the prior turn persisted a compaction block onto the
-    # assistant message, the next turn's outbound body must forward
-    # the {type:"compaction", content:"..."} block to Anthropic
-    # verbatim so the API recognises the existing state.
+    # Once the prior turn persisted a compaction block onto the assistant
+    # message, the next turn's outbound body must forward the
+    # {type:"compaction", content:"..."} block to Anthropic verbatim so the
+    # API recognises the existing state.
     captured: dict = {}
 
     def http_handler(request: httpx.Request) -> httpx.Response:
@@ -527,10 +523,10 @@ def test_compaction_content_part_accepted_by_chat_message_schema():
 
 
 def test_build_external_messages_passes_compaction_for_anthropic_only():
-    # Compaction is an Anthropic-only synthetic content part. The
-    # builder MUST gate it on provider_type=="anthropic"; every other
-    # provider would 400 on the unknown content type via generic
-    # /chat/completions passthrough (Codex P1 follow-up).
+    # Compaction is an Anthropic-only synthetic content part. The builder
+    # MUST gate it on provider_type=="anthropic"; every other provider
+    # would 400 on the unknown content type via generic /chat/completions
+    # passthrough (Codex P1 follow-up).
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -554,7 +550,7 @@ def test_build_external_messages_passes_compaction_for_anthropic_only():
 
 def test_build_external_messages_strips_compaction_for_non_anthropic_providers():
     # Provider switch (or reused history) hands compaction blocks to a
-    # non-Anthropic provider. Those land on generic /chat/completions
+    # non-Anthropic provider, landing on generic /chat/completions
     # passthrough where the unknown content type fails the upstream
     # validator. Builder must strip the part for every non-anthropic
     # provider, including OpenAI/DeepSeek/Mistral/Gemini/Kimi/OpenRouter.
diff --git a/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py b/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
index 94a1ca4e2c..da0c0941ca 100644
--- a/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
+++ b/studio/backend/tests/test_anthropic_fast_mode_and_refusal.py
@@ -3,9 +3,9 @@
 
 """Tests for Anthropic fast-mode wiring and streaming refusal handling.
 
-fast_mode=True on Opus 4.6/4.7 attaches the ``fast-mode-2026-02-01``
-beta header and sets ``speed: "fast"``; unsupported models drop both.
-Streaming ``stop_reason: "refusal"`` surfaces a user notice before the
+fast_mode=True on Opus 4.6/4.7 attaches the ``fast-mode-2026-02-01`` beta
+header and sets ``speed: "fast"``; unsupported models drop both. Streaming
+``stop_reason: "refusal"`` surfaces a user notice before the
 ``content_filter`` finish chunk.
 https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals
 """
@@ -63,7 +63,7 @@ def _capture(
     sse: bytes = b"",
     **kwargs,
 ) -> tuple[dict, list[str]]:
-    """Install a MockTransport, drive one streamed call, return body+lines."""
+    """Install a MockTransport, drive one streamed call; return body+lines."""
     captured: dict = {}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -157,12 +157,12 @@ def test_refusal_emits_user_facing_notice_and_content_filter_finish(monkeypatch)
 
 def test_refusal_emits_tool_event_for_chat_adapter_drop(monkeypatch):
     """Refused turns emit an out-of-band `_toolEvent` that the chat-adapter
-    latches into assistant `metadata.custom.anthropicRefusal`, driving
-    the next-request prune. Tool event (not text) prevents spoofing.
+    latches into assistant `metadata.custom.anthropicRefusal`, driving the
+    next-request prune. Tool event (not text) prevents spoofing.
     """
     _, lines = _capture(monkeypatch, sse = _refusal_sse())
     body = "\n".join(lines)
     assert '"_toolEvent": {"type": "anthropic_refusal"}' in body, body
-    # Visible refusal text must not embed a sentinel that could spoof
-    # a context reset if echoed by another assistant message.
+    # Visible refusal text must not embed a sentinel that could spoof a
+    # context reset if echoed by another assistant message.
     assert "studio:anthropic-refusal" not in body, body
diff --git a/studio/backend/tests/test_anthropic_fast_mode_edge.py b/studio/backend/tests/test_anthropic_fast_mode_edge.py
index 116f58f7f2..dd69d77590 100644
--- a/studio/backend/tests/test_anthropic_fast_mode_edge.py
+++ b/studio/backend/tests/test_anthropic_fast_mode_edge.py
@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Edge-case coverage for the Anthropic fast-mode + refusal wiring.
+"""Edge-case coverage for Anthropic fast-mode + refusal wiring.
 
-Complements ``test_anthropic_fast_mode_and_refusal.py`` (happy path)
-with dated snapshots, strict opt-in (future Opus families do not
-auto-enable), multi-beta header merging, refusal stream ordering, and
-the non-destruction guarantee for unset/None fast_mode.
+Complements ``test_anthropic_fast_mode_and_refusal.py`` (happy path) with
+dated snapshots, strict opt-in (future Opus families do not auto-enable),
+multi-beta header merging, refusal stream ordering, and the
+non-destruction guarantee for unset/None fast_mode.
 """
 
 import asyncio
@@ -128,7 +128,7 @@ def test_fast_mode_attaches_on_dated_opus_4_6_snapshot(monkeypatch):
 
 # ──────────────────────────── strict opt-in semantics ────────────────────────────
 def test_fast_mode_does_not_auto_enable_on_future_opus_4_8(monkeypatch):
-    """Future ``claude-opus-4-8`` must not auto-enable; opt-in per family."""
+    """Future ``claude-opus-4-8`` must not auto-enable; per-family opt-in."""
     cap, _ = _capture(monkeypatch, fast_mode = True, model = "claude-opus-4-8")
     assert "speed" not in cap["body"], cap["body"]
     assert "fast-mode-2026-02-01" not in cap["headers"].get("anthropic-beta", "")
@@ -248,7 +248,7 @@ def test_fast_mode_unset_is_byte_identical_to_omitted(monkeypatch):
     _drive(run())
 
     assert cap_none["body"] == captured["body"], (cap_none["body"], captured["body"])
-    # Headers can vary by httpx-injected fields (host, connection); compare
+    # Headers vary by httpx-injected fields (host, connection); compare
     # the load-bearing ones.
     for key in ("anthropic-version", "x-api-key", "content-type"):
         assert cap_none["headers"].get(key) == captured["headers"].get(key), key
@@ -323,8 +323,7 @@ def test_refusal_chunk_is_proper_openai_delta_shape(monkeypatch):
     assert notice_chunk is not None, lines
     choice = notice_chunk["choices"][0]
     assert "delta" in choice and "content" in choice["delta"], notice_chunk
-    # Must NOT carry a finish_reason itself -- that comes on the next
-    # chunk.
+    # Must NOT carry a finish_reason itself -- that comes on the next chunk.
     assert choice.get("finish_reason") in (None,), notice_chunk
     # Refusal text is plain-spoken; no embedded sentinel.
     assert "studio:anthropic-refusal" not in choice["delta"]["content"]
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index ee19a96bca..c55ccbaaef 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -2,7 +2,7 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
 """
-Tests for the Anthropic Messages API schemas and translation layer.
+Tests for Anthropic Messages API schemas and translation layer.
 No running server or GPU required.
 """
 
@@ -1187,14 +1187,14 @@ class TestAnthropicRequestedStudioTools:
 
     def test_bare_name_without_type_is_not_treated_as_server_tool(self):
         # Anthropic dispatches server tools by `type`; bare-name matching
-        # would let a malformed client tool (e.g. user forgot input_schema)
-        # silently flip the request into server-execution mode.
+        # would let a malformed client tool (missing input_schema) silently
+        # flip the request into server-execution mode.
         tools = [{"name": "python"}]
         assert _anthropic_requested_studio_tools(tools) == set()
 
     def test_client_tool_named_python_is_not_misclassified(self):
-        # input_schema is the client-tool discriminator; presence of it
-        # must prevent the name from being treated as a Studio alias.
+        # input_schema is the client-tool discriminator; its presence must
+        # prevent the name from being treated as a Studio alias.
         tools = [
             {
                 "name": "python",
@@ -1239,8 +1239,8 @@ class _ToolPathCalled(Exception):
 def _mock_backend(monkeypatch, **overrides):
     """Install a minimal stub backend on routes.inference.
 
-    Generation methods raise sentinel exceptions so the caller can assert
-    which path the route entered.
+    Generation methods raise sentinels so the caller can assert which path
+    the route entered.
     """
     import routes.inference as inf_mod
 
@@ -1299,10 +1299,10 @@ class TestAnthropicMessagesToolRouting:
         assert "Mixing Anthropic server tools" in exc.value.detail
 
     def test_mixed_rejected_when_client_tool_name_collides_with_server_alias(self, monkeypatch):
-        # Regression: a client tool sharing a name with a mapped server
-        # tool (e.g. user defines their own "web_search") must still
-        # trigger the mixed-mode 400 — the post-name filter would
-        # otherwise drop the client tool and silently route to server-only.
+        # Regression: a client tool sharing a name with a mapped server tool
+        # (e.g. a custom "web_search") must still trigger the mixed-mode 400;
+        # otherwise the post-name filter drops the client tool and silently
+        # routes to server-only.
         _mock_backend(monkeypatch)
         payload = _basic_payload(
             tools = [
@@ -1329,10 +1329,10 @@ class TestAnthropicMessagesToolRouting:
 
     def test_client_tool_missing_name_rejected_with_400(self, monkeypatch):
         # Regression: AnthropicTool.name was relaxed to Optional for server
-        # tools, so a client-tool payload that has input_schema but omits
-        # `name` (e.g. typo) now parses successfully but would be silently
-        # dropped by anthropic_tools_to_openai, leaving the request with
-        # tool calling disabled. Reject at the boundary instead.
+        # tools, so a client-tool payload with input_schema but no `name`
+        # (typo) now parses but would be silently dropped by
+        # anthropic_tools_to_openai, leaving tool calling disabled. Reject at
+        # the boundary instead.
         _mock_backend(monkeypatch)
         payload = _basic_payload(
             tools = [{"input_schema": {"type": "object"}}],
@@ -1346,7 +1346,7 @@ class TestAnthropicMessagesToolRouting:
     def test_client_tool_empty_name_rejected_with_400(self, monkeypatch):
         # Same silent-disable class as missing-name: `name: ""` passes the
         # isinstance check but is dropped by anthropic_tools_to_openai's
-        # `if not name` guard. Reject at the boundary so the typo surfaces.
+        # `if not name` guard. Reject at the boundary so the typo shows.
         _mock_backend(monkeypatch)
         payload = _basic_payload(
             tools = [{"name": "", "input_schema": {"type": "object"}}],
@@ -1358,10 +1358,10 @@ class TestAnthropicMessagesToolRouting:
         assert "name" in exc.value.detail
 
     def test_alias_named_client_tool_without_schema_rejected_with_400(self, monkeypatch):
-        # Regression: a typo'd client tool whose name happens to collide
-        # with a Studio alias (e.g. user meant a custom "python" tool but
-        # forgot input_schema) must surface a 400, not silently switch
-        # the request into Studio's built-in python execution.
+        # Regression: a typo'd client tool whose name collides with a Studio
+        # alias (e.g. a custom "python" tool missing input_schema) must
+        # surface a 400, not silently switch into Studio's built-in python
+        # execution.
         _mock_backend(monkeypatch)
         payload = _basic_payload(tools = [{"name": "python"}])
 
@@ -1380,9 +1380,8 @@ class TestAnthropicMessagesToolRouting:
             _drive(anthropic_messages(payload, request = None, current_subject = "t"))
 
     def test_disable_tools_policy_overrides_server_tool_alias(self, monkeypatch):
-        # CLI `unsloth run --disable-tools` sets policy=False. A request
-        # carrying a Studio server-tool alias must NOT enter the agentic
-        # loop in that configuration.
+        # CLI `unsloth run --disable-tools` sets policy=False. A request with
+        # a Studio server-tool alias must NOT enter the agentic loop then.
         _mock_backend(monkeypatch)
         set_tool_policy(False)
         payload = _basic_payload(
diff --git a/studio/backend/tests/test_anthropic_thinking_translation.py b/studio/backend/tests/test_anthropic_thinking_translation.py
index 14f261ae6b..144de166f2 100644
--- a/studio/backend/tests/test_anthropic_thinking_translation.py
+++ b/studio/backend/tests/test_anthropic_thinking_translation.py
@@ -2,23 +2,19 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Unit tests for the Anthropic extended-thinking translation in
-external_provider.
+Unit tests for the Anthropic extended-thinking translation in external_provider.
 
 Covers:
 - Adaptive-mode request body nests effort under
-  ``output_config: {effort: "<level>"}`` per the Messages API
-  reference (a top-level ``effort`` field 400s with
-  "effort: Extra inputs are not permitted").
-- Streaming SSE: ``content_block_delta`` with
-  ``delta.type == "thinking_delta"`` is translated into inline
-  ``<think>...</think>`` chat-completion chunks so the frontend's
-  reasoning-panel pipeline lifts it correctly.
-- The ``<think>`` tag closes when the first ``text_delta`` arrives,
-  on ``content_block_stop``, on ``message_delta``, or on
-  ``message_stop``.
-- Thinking is paired with ``temperature=1`` and no ``top_p`` /
-  ``top_k`` on the wire (Anthropic extended-thinking contract).
+  ``output_config: {effort: "<level>"}`` per the Messages API reference (a
+  top-level ``effort`` field 400s with "effort: Extra inputs are not permitted").
+- Streaming SSE: ``content_block_delta`` with ``delta.type == "thinking_delta"``
+  is translated into inline ``<think>...</think>`` chat-completion chunks so the
+  frontend's reasoning-panel pipeline lifts it correctly.
+- The ``<think>`` tag closes when the first ``text_delta`` arrives, on
+  ``content_block_stop``, on ``message_delta``, or on ``message_stop``.
+- Thinking is paired with ``temperature=1`` and no ``top_p`` / ``top_k`` on the
+  wire (Anthropic extended-thinking contract).
 """
 
 import asyncio
@@ -113,9 +109,8 @@ def test_adaptive_thinking_body_uses_output_config_effort_shape(monkeypatch):
     # display=summarized is set explicitly so Opus 4.7 (which defaults to
     # "omitted") still emits thinking_delta events for the reasoning panel.
     assert body["thinking"] == {"type": "adaptive", "display": "summarized"}
-    # Documented shape: effort is nested under output_config.
-    # A top-level `effort` field produces a 400:
-    #   "effort: Extra inputs are not permitted".
+    # Documented shape: effort is nested under output_config. A top-level
+    # `effort` field produces a 400: "effort: Extra inputs are not permitted".
     assert body["output_config"] == {"effort": "medium"}
     assert "effort" not in body
     # Extended-thinking contract: temperature=1, no top_p / top_k.
@@ -258,10 +253,10 @@ def test_manual_thinking_body_uses_budget_tokens_on_4_5(monkeypatch):
     body = captured["body"]
     assert body["thinking"] == {"type": "enabled", "budget_tokens": 4096}
     # max_tokens must be strictly greater than budget_tokens; we shipped 1024
-    # and budget is 4096, so the wrapper should bump max_tokens.
+    # and budget is 4096, so the wrapper must bump max_tokens.
     assert body["max_tokens"] > body["thinking"]["budget_tokens"]
-    # Manual-thinking path does not use output_config / effort — those are
-    # the adaptive-mode controls (Claude 4.6 / 4.7).
+    # Manual-thinking path does not use output_config / effort — those are the
+    # adaptive-mode controls (Claude 4.6 / 4.7).
     assert "effort" not in body
     assert "output_config" not in body
 
@@ -338,8 +333,8 @@ def test_thinking_delta_wrapped_in_think_tags(monkeypatch):
         if isinstance(p, dict) and p["choices"][0]["delta"]
     )
 
-    # Reasoning text should be wrapped in <think>...</think>, followed by the
-    # answer text, and the stream should terminate with [DONE].
+    # Reasoning text is wrapped in <think>...</think>, then the answer text, and
+    # the stream terminates with [DONE].
     assert "<think>First I plan.</think>" in combined
     assert combined.endswith("Answer.")
     # signature_delta is intentionally dropped — no leaked signature text.
@@ -350,9 +345,9 @@ def test_thinking_delta_wrapped_in_think_tags(monkeypatch):
 def test_thinking_only_turn_closes_tag_without_text_delta(monkeypatch):
     """display=omitted on Claude 4.7 emits a signature_delta and no text.
 
-    The <think> open is still triggered by the (synthetic) thinking_delta;
-    we want content_block_stop to close it cleanly so the tag never leaks
-    into the next chunk."""
+    The <think> open is still triggered by the (synthetic) thinking_delta; we
+    want content_block_stop to close it cleanly so the tag never leaks into the
+    next chunk."""
 
     def handler(request: httpx.Request) -> httpx.Response:
         events = [
diff --git a/studio/backend/tests/test_anthropic_tool_versions.py b/studio/backend/tests/test_anthropic_tool_versions.py
index 8f5d3f7f46..f9ff448f66 100644
--- a/studio/backend/tests/test_anthropic_tool_versions.py
+++ b/studio/backend/tests/test_anthropic_tool_versions.py
@@ -7,13 +7,12 @@ helpers in ``core.inference.external_provider``.
 
 Anthropic ships date-pinned tool versions per model family. The newer
 ``_20260209`` web_search / web_fetch and ``_20260120`` code_execution
-variants only run on a subset of models; sending them to an older
-model returns a 400 from upstream, and sending the older
-``_20250305`` / ``_20250910`` / ``_20250825`` variants to a newer
-model misses dynamic filtering and the free-when-paired pricing. The
-helpers below decide which version goes out per model; this test pins
-the dispatch matrix so future model launches keep working without
-silently regressing the newer-version path.
+variants only run on a subset of models; sending them to an older model
+returns a 400 from upstream, and sending the older ``_20250305`` /
+``_20250910`` / ``_20250825`` variants to a newer model misses dynamic
+filtering and the free-when-paired pricing. The helpers below pick the
+version per model; this test pins the dispatch matrix so future model
+launches keep working without regressing the newer-version path.
 
 Covers:
 - ``_anthropic_web_search_version`` / ``_anthropic_web_fetch_version``
@@ -23,10 +22,10 @@ Covers:
 - ``_anthropic_code_execution_version`` picks ``_20260120`` for the
   Opus 4.5+ / Sonnet 4.5+ / Opus 4.7 / Sonnet 4.6 family and falls back
   to ``_20250825`` everywhere else (Haiku 4.5, 4.1, 4.0).
-- ``_stream_anthropic`` body integration: when ``enabled_tools=
-  ["web_search", "code_execution"]`` is set on Opus 4.7, the outbound
-  body carries the newer pinned versions; the same payload on Haiku
-  4.5 falls back to the legacy versions.
+- ``_stream_anthropic`` body integration: with ``enabled_tools=
+  ["web_search", "code_execution"]`` on Opus 4.7, the outbound body
+  carries the newer pinned versions; the same payload on Haiku 4.5 falls
+  back to the legacy versions.
 - The ``anthropic-beta: code-execution-2025-08-25`` header is sent
   unchanged for both code-execution variants (no header rev needed).
 """
@@ -165,9 +164,9 @@ def test_outbound_body_uses_new_versions_on_opus_4_7(monkeypatch):
     assert "code_execution_20260120" in tool_types
     assert "web_search_20250305" not in tool_types
     assert "code_execution_20250825" not in tool_types
-    # Beta header for code execution stays on the existing flag for
-    # both _20250825 and _20260120; the API uses one header to gate
-    # the feature, not the date.
+    # Beta header for code execution stays on the existing flag for both
+    # _20250825 and _20260120; the API gates the feature by one header, not
+    # the date.
     assert "code-execution-2025-08-25" in captured["headers"].get("anthropic-beta", "")
 
 
diff --git a/studio/backend/tests/test_anthropic_web_fetch.py b/studio/backend/tests/test_anthropic_web_fetch.py
index 7d754872cd..542048ebd4 100644
--- a/studio/backend/tests/test_anthropic_web_fetch.py
+++ b/studio/backend/tests/test_anthropic_web_fetch.py
@@ -1,12 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for Anthropic's `web_fetch_20250910` / `web_fetch_20260209`
+"""Unit tests for Anthropic's `web_fetch_20250910` / `web_fetch_20260209`
 translation in ``_stream_anthropic``. Covers request body emission
-(version picked by ``_anthropic_web_fetch_version``: ``_20260209`` for
-Opus 4.6/4.7 + Sonnet 4.6, ``_20250910`` otherwise), combined tool
-requests, off-by-default behavior, and SSE translation of success and
+(version from ``_anthropic_web_fetch_version``: ``_20260209`` for Opus
+4.6/4.7 + Sonnet 4.6, else ``_20250910``), combined tool requests,
+off-by-default behavior, and SSE translation of success and
 ``url_not_accessible`` error paths into ``tool_start`` / ``tool_end``.
 """
 
@@ -103,7 +102,7 @@ def test_web_fetch_tool_appended_to_request_body(monkeypatch):
 
     body = captured["body"]
     tools = body.get("tools") or []
-    # claude-opus-4-7 routes web_fetch to _20260209 (dynamic filtering).
+    # claude-opus-4-7 routes web_fetch to _20260209.
     assert {"type": "web_fetch_20260209", "name": "web_fetch", "max_uses": 5} in tools
     # web_fetch is GA; no beta header is required.
     assert "web-fetch" not in captured["headers"].get("anthropic-beta", "")
@@ -140,13 +139,13 @@ def test_web_fetch_combined_with_web_search_and_code_execution(monkeypatch):
 
     tools = captured["body"].get("tools") or []
     tool_types = [t.get("type") for t in tools]
-    # claude-opus-4-7 routes web_search and web_fetch to _20260209
-    # and code_execution to _20260120 (per PR 5679 dispatch).
+    # claude-opus-4-7 routes web_search/web_fetch to _20260209 and
+    # code_execution to _20260120 (per PR 5679 dispatch).
     assert "web_search_20260209" in tool_types, tool_types
     assert "web_fetch_20260209" in tool_types, tool_types
     assert "code_execution_20260120" in tool_types, tool_types
-    # Code-execution still adds its beta flag; web_fetch must not
-    # have accidentally stripped it.
+    # Code-execution still adds its beta flag; web_fetch must not have
+    # stripped it.
     assert "code-execution-2025-08-25" in captured["headers"].get("anthropic-beta", "")
 
 
@@ -263,8 +262,8 @@ def test_web_fetch_success_emits_tool_start_and_end(monkeypatch):
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "web_fetch"
     assert start["tool_call_id"] == "srvtoolu_wf1"
-    # `_server_tool: True` marks this as a provider-side synthetic
-    # tool card for the frontend's history serializer.
+    # `_server_tool: True` marks this a provider-side synthetic tool card
+    # for the frontend's history serializer.
     assert start["arguments"] == {"url": "https://example.com/article", "_server_tool": True}
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_wf1"
@@ -345,9 +344,10 @@ def test_web_fetch_error_renders_error_code(monkeypatch):
 
 
 def _finish_reasons(lines: list[str]) -> list:
-    """Return non-null finish_reason fields from each chat.completion.chunk.
-    Mid-stream content deltas carry ``finish_reason: None`` and are skipped
-    (the refusal path emits a notice delta before the content_filter chunk)."""
+    """Non-null finish_reason fields from each chat.completion.chunk.
+    Mid-stream content deltas carry ``finish_reason: None`` and are
+    skipped (refusal emits a notice delta before the content_filter
+    chunk)."""
     out: list = []
     for line in lines:
         if not line.startswith("data:"):
@@ -369,12 +369,12 @@ def _finish_reasons(lines: list[str]) -> list:
 
 
 def test_pause_turn_does_not_emit_finish_reason_chunk(monkeypatch):
-    # `pause_turn` is what Anthropic emits when a long server-tool turn
-    # (typically web_search / web_fetch) pauses and will resume on the
-    # next request. Treating it as finish_reason="stop" makes the
-    # OpenAI-formatted client truncate the rendered assistant message.
-    # The adapter must skip the chunk so the stream ends cleanly with
-    # [DONE] and no terminal finish_reason.
+    # Anthropic emits `pause_turn` when a long server-tool turn
+    # (typically web_search / web_fetch) pauses and resumes on the next
+    # request. Mapping it to finish_reason="stop" makes the
+    # OpenAI-formatted client truncate the assistant message. The adapter
+    # must skip the chunk so the stream ends cleanly with [DONE] and no
+    # terminal finish_reason.
     sse_events = [
         {"type": "message_start", "message": {"usage": {}}},
         {
@@ -408,15 +408,14 @@ def test_pause_turn_does_not_emit_finish_reason_chunk(monkeypatch):
         )
 
     lines = _drive(run())
-    # No finish_reason chunk for pause_turn -- the only completion
-    # signal is the [DONE] line.
+    # No finish_reason chunk for pause_turn -- only [DONE] signals
+    # completion.
     assert _finish_reasons(lines) == [], lines
     assert any(line.strip() == "data: [DONE]" for line in lines), lines
 
 
 def test_end_turn_still_emits_stop_finish_reason(monkeypatch):
-    # Sanity: the pause_turn -> None mapping must not regress normal
-    # end_turn handling.
+    # Sanity: pause_turn -> None mapping must not regress end_turn.
     sse_events = [
         {"type": "message_start", "message": {"usage": {}}},
         {
@@ -489,12 +488,11 @@ def test_refusal_maps_to_content_filter(monkeypatch):
 
 
 def test_web_fetch_titleless_document_falls_back_to_url(monkeypatch):
-    # Anthropic may omit `document.title` on pages where the HTML
-    # provides nothing usable. Without a fallback the formatter would
-    # emit `URL: ...\nSnippet: ...` only, and the frontend's
-    # parseSourcesFromResult skips entries that lack a `Title:` line,
-    # so the source pill silently disappears. Verify the formatter
-    # mirrors the web_search behaviour and falls back to the URL.
+    # Anthropic may omit `document.title` when the HTML has nothing
+    # usable. Without a fallback the formatter emits `URL: ...\nSnippet:
+    # ...` only, and the frontend's parseSourcesFromResult skips entries
+    # lacking a `Title:` line, so the source pill disappears. Verify the
+    # formatter mirrors web_search and falls back to the URL.
     sse_events = [
         {"type": "message_start", "message": {"usage": {}}},
         {
diff --git a/studio/backend/tests/test_audio_token_detection.py b/studio/backend/tests/test_audio_token_detection.py
index bf1217b231..02d4790519 100644
--- a/studio/backend/tests/test_audio_token_detection.py
+++ b/studio/backend/tests/test_audio_token_detection.py
@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Tests for tokenizer-based audio_type detection patterns, covering both
-Gemma 3n (<audio_soft_token>) and Gemma 4 (<|audio|>) audio-input tokens."""
+"""Tests for tokenizer-based audio_type detection, covering Gemma 3n
+(<audio_soft_token>) and Gemma 4 (<|audio|>) audio-input tokens."""
 
 from __future__ import annotations
 
@@ -10,8 +10,7 @@ from utils.models.model_config import _AUDIO_TOKEN_PATTERNS, is_audio_input_type
 
 
 def _classify(tokens: list[str]) -> str | None:
-    """Mirror _detect_audio_from_tokenizer._check_token_patterns: first match
-    in dict order wins."""
+    """Mirror _check_token_patterns: first match in dict order wins."""
     for audio_type, check in _AUDIO_TOKEN_PATTERNS.items():
         if check(tokens):
             return audio_type
diff --git a/studio/backend/tests/test_browse_folders_route.py b/studio/backend/tests/test_browse_folders_route.py
index 19a83987d3..3a607e6b10 100644
--- a/studio/backend/tests/test_browse_folders_route.py
+++ b/studio/backend/tests/test_browse_folders_route.py
@@ -9,8 +9,7 @@ from pathlib import Path
 import pytest
 from fastapi import HTTPException
 
-# Keep this test runnable in lightweight environments where optional logging
-# deps are not installed.
+# Keep runnable in lightweight environments lacking optional logging deps.
 if "structlog" not in sys.modules:
 
     class _DummyLogger:
diff --git a/studio/backend/tests/test_cache_case_resolution.py b/studio/backend/tests/test_cache_case_resolution.py
index 60963b4f7d..50340bda63 100644
--- a/studio/backend/tests/test_cache_case_resolution.py
+++ b/studio/backend/tests/test_cache_case_resolution.py
@@ -111,10 +111,10 @@ def test_resolve_cached_repo_id_case_late_cache_population(tmp_path, monkeypatch
     first = resolve_cached_repo_id_case("org/model")
     assert first == "org/model"
 
-    # Simulate cache being populated after first miss (e.g. another code path/download).
+    # Cache populated after first miss (e.g. another code path/download).
     _mk_cache_repo(tmp_path, "Org/Model")
 
     second = resolve_cached_repo_id_case("org/model")
 
-    # Desired behavior: second lookup should pick up the now-existing variant.
+    # Second lookup should pick up the now-existing variant.
     assert second == "Org/Model"
diff --git a/studio/backend/tests/test_cached_gguf_routes.py b/studio/backend/tests/test_cached_gguf_routes.py
index 980de216db..0274d5b4da 100644
--- a/studio/backend/tests/test_cached_gguf_routes.py
+++ b/studio/backend/tests/test_cached_gguf_routes.py
@@ -7,8 +7,8 @@ import types
 from pathlib import Path
 from types import SimpleNamespace
 
-# Keep this test runnable in lightweight environments where optional logging
-# deps are not installed.
+# Keep this test runnable in lightweight environments without optional
+# logging deps.
 if "structlog" not in sys.modules:
 
     class _DummyLogger:
@@ -212,7 +212,7 @@ def test_list_cached_models_skips_non_suffix_repo_when_gguf_files_exist(monkeypa
 
 def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(monkeypatch, tmp_path):
     """Mirror of the _skips_ test: the mixed repo should still surface in
-    cached-gguf so the picker can show it as a GGUF download."""
+    cached-gguf so the picker shows it as a GGUF download."""
     mixed = _repo(
         "Org/MixedRepo",
         [
@@ -241,8 +241,8 @@ def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(monkeypa
 
 def test_list_cached_gguf_handles_none_size_on_disk(monkeypatch, tmp_path):
     """A partial/interrupted GGUF download has ``size_on_disk = None``. The
-    route must treat the unknown bytes as zero instead of raising TypeError
-    out of ``sum()`` and wiping the entire response."""
+    route must treat unknown bytes as zero instead of raising TypeError from
+    ``sum()`` and wiping the whole response."""
     partial = _repo(
         "Org/PartialDownload",
         [_file("Q4_K_M.gguf", None), _file("Q6_K.gguf", 5_000)],
@@ -268,7 +268,7 @@ def test_list_cached_gguf_handles_none_size_on_disk(monkeypatch, tmp_path):
 
 def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(monkeypatch, tmp_path):
     """One repo raising during classification must not poison the response
-    for every other repo in the scan."""
+    for the other repos in the scan."""
 
     class _ExplodingRepo:
         repo_id = "Org/Broken"
@@ -303,9 +303,9 @@ def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(monkeypat
 
 
 def test_list_cached_gguf_skips_repo_with_only_mmproj_gguf(monkeypatch, tmp_path):
-    """A repo whose only ``.gguf`` artifact is an mmproj vision adapter
-    must not be classified as a GGUF repo: the variant selector filters
-    mmproj out and the picker would otherwise show zero variants."""
+    """A repo whose only ``.gguf`` artifact is an mmproj vision adapter must
+    not be classified as a GGUF repo: the variant selector filters mmproj
+    out and the picker would otherwise show zero variants."""
     mmproj_only = _repo(
         "Org/MmprojOnly",
         [
@@ -327,9 +327,9 @@ def test_list_cached_gguf_skips_repo_with_only_mmproj_gguf(monkeypatch, tmp_path
 
 
 def test_list_cached_models_includes_repo_with_only_mmproj_gguf(monkeypatch, tmp_path):
-    """Mirror of the cached-gguf skip: a safetensors repo with an
-    auxiliary mmproj vision adapter must still surface in cached-models
-    so the user can load it as a normal model."""
+    """Mirror of the cached-gguf skip: a safetensors repo with an auxiliary
+    mmproj vision adapter must still surface in cached-models so the user
+    can load it as a normal model."""
     mmproj_aux = _repo(
         "Org/MmprojAux",
         [
@@ -351,10 +351,10 @@ def test_list_cached_models_includes_repo_with_only_mmproj_gguf(monkeypatch, tmp
 
 
 def test_list_cached_gguf_includes_vision_repo_with_main_gguf_and_mmproj(monkeypatch, tmp_path):
-    """A vision-capable GGUF repo (main weight + mmproj adapter) is still
-    a GGUF repo. The reported size is the main weight size; mmproj is
-    excluded from the GGUF-size accounting because it is filtered out at
-    classification time."""
+    """A vision-capable GGUF repo (main weight + mmproj adapter) is still a
+    GGUF repo. Reported size is the main weight size; mmproj is excluded
+    from GGUF-size accounting since it is filtered out at classification
+    time."""
     vision_repo = _repo(
         "Org/VisionGguf",
         [
diff --git a/studio/backend/tests/test_chat_history_storage.py b/studio/backend/tests/test_chat_history_storage.py
index b79f8f8119..92cac1a50d 100644
--- a/studio/backend/tests/test_chat_history_storage.py
+++ b/studio/backend/tests/test_chat_history_storage.py
@@ -30,9 +30,9 @@ def _reset_studio_db(
 def workspace_projects_home(tmp_path):
     """Projects root outside the platform delete denylist.
 
-    tmp_path resolves under /private/tmp on macOS, which the workspace
-    delete guard refuses by design. Linux/Windows tmp is not denied and is
-    used as-is; only the denied case falls back to a home subdir.
+    tmp_path resolves under /private/tmp on macOS, which the workspace delete
+    guard refuses by design. Linux/Windows tmp is not denied and is used as-is;
+    only the denied case falls back to a home subdir.
     """
     candidate = tmp_path / "Projects"
     resolved = str(candidate.resolve())
@@ -367,8 +367,8 @@ def test_legacy_imports_dedups_input(tmp_path, monkeypatch):
     accepted, inserted = studio_db.upsert_chat_legacy_imports(
         ["x", "x", "y", "x"],
     )
-    # accepted is the deduped non-empty input size; inserted is the rows
-    # actually new in the ledger after ON CONFLICT DO NOTHING.
+    # accepted is the deduped non-empty input size; inserted is the rows newly
+    # added to the ledger after ON CONFLICT DO NOTHING.
     assert accepted == 2
     assert inserted == 2
     assert set(studio_db.list_chat_legacy_imports()) == {"x", "y"}
diff --git a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
index 3bb60336eb..138cda30d4 100644
--- a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
+++ b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
@@ -16,11 +16,11 @@ if str(_BACKEND_ROOT) not in sys.path:
 
 @pytest.fixture
 def outputs_setup(tmp_path, monkeypatch):
-    """Point outputs_root() at a temp dir so cleanup is allowed to run on it.
+    """Point outputs_root() at a temp dir so cleanup may run on it.
 
     The training module binds ``outputs_root`` at import time
-    (``from utils.paths import outputs_root``), so we have to patch
-    the symbol on the importer module, not on storage_roots.
+    (``from utils.paths import outputs_root``), so patch the symbol on the
+    importer module, not on storage_roots.
     """
     from core.training import training as training_mod
 
@@ -36,8 +36,8 @@ def _mk_dir(parent: Path, name: str) -> Path:
 
 
 def test_completed_checkpoints_are_preserved(outputs_setup):
-    """The big regression: prior to this fix, every completed
-    checkpoint-N/ was rmtree'd on Cancel, destroying resume points."""
+    """The big regression: before this fix, every completed checkpoint-N/
+    was rmtree'd on Cancel, destroying resume points."""
     from core.training.training import _cleanup_cancelled_checkpoints
 
     out = outputs_setup / "run-1"
diff --git a/studio/backend/tests/test_cpu_threads.py b/studio/backend/tests/test_cpu_threads.py
index b51d2bfb7d..2930c9f081 100644
--- a/studio/backend/tests/test_cpu_threads.py
+++ b/studio/backend/tests/test_cpu_threads.py
@@ -116,8 +116,8 @@ def _ast_line_of_platform_compat_import(source: str) -> int:
     raise AssertionError("_platform_compat import not found")
 
 
-# AST-based ordering: configure_cpu_threads() must precede _platform_compat
-# in both run.py and main.py. Robust to formatting / line shifts.
+# AST ordering: configure_cpu_threads() must precede _platform_compat in both
+# run.py and main.py. Robust to formatting / line shifts.
 @pytest.mark.parametrize("entry_point", [_RUN_PY, _MAIN_PY])
 def test_cpu_thread_configuration_runs_before_backend_imports(entry_point):
     source = entry_point.read_text()
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index 219d64145f..9d80c718cb 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -239,7 +239,7 @@ def test_consume_refresh_token_second_call_returns_none():
 
 
 def test_consume_refresh_token_concurrent_only_one_succeeds(tmp_path, monkeypatch):
-    """64-thread pile-up against one token; DELETE RETURNING permits one winner."""
+    """64-thread pile-up on one token; DELETE RETURNING permits one winner."""
     seed_user()
     from concurrent.futures import ThreadPoolExecutor
     from datetime import datetime, timedelta, timezone
@@ -254,7 +254,7 @@ def test_consume_refresh_token_concurrent_only_one_succeeds(tmp_path, monkeypatc
         try:
             return storage.consume_refresh_token(raw)
         except sqlite3.OperationalError:
-            # "database is locked" under heavy contention; treat as losing the race.
+            # "database is locked" under contention; treat as losing the race.
             return None
 
     with ThreadPoolExecutor(max_workers = workers) as pool:
@@ -293,9 +293,9 @@ def test_desktop_session_uses_real_admin_identity_for_api_keys():
 
 
 def test_local_recipe_token_authenticates_as_admin_for_desktop_user(loaded_local_model):
-    # _inject_local_providers mints an internal sk-unsloth-* API key (not a
-    # forwarded JWT). The unified API-key path validates as the real admin
-    # user regardless of whether the incoming session was desktop or web.
+    # _inject_local_providers mints an internal sk-unsloth-* API key (not
+    # a forwarded JWT). The unified API-key path validates as the real
+    # admin user whether the incoming session was desktop or web.
     from auth.authentication import create_access_token, get_current_subject
 
     seed_user(must_change_password = True)
@@ -318,8 +318,8 @@ def test_local_recipe_token_authenticates_as_admin_for_desktop_user(loaded_local
 
 
 def test_local_recipe_token_authenticates_as_admin_for_web_user(loaded_local_model):
-    # Mirror of the desktop variant: API-key issuance is identical for web
-    # and desktop incoming tokens; auth via get_current_subject works the same.
+    # Mirror of the desktop variant: API-key issuance is identical for
+    # web and desktop tokens; get_current_subject works the same.
     from auth.authentication import create_access_token, get_current_subject
 
     seed_user(must_change_password = False)
diff --git a/studio/backend/tests/test_detect_mmproj_file.py b/studio/backend/tests/test_detect_mmproj_file.py
index 9487db1e5b..64dd8ebd90 100644
--- a/studio/backend/tests/test_detect_mmproj_file.py
+++ b/studio/backend/tests/test_detect_mmproj_file.py
@@ -46,7 +46,7 @@ def test_returns_none_when_no_mmproj(tmp_path: Path):
 
 
 def test_single_matching_family_mmproj_picked(tmp_path: Path):
-    """Single same-family projector: returned (historical behaviour)."""
+    """Single same-family projector is returned (historical behaviour)."""
     model = _touch(tmp_path / "Qwen3.5-9B-Q4_K_M.gguf")
     mmproj = _touch(tmp_path / "Qwen3.5-9B-BF16-mmproj.gguf")
     assert detect_mmproj_file(str(model)) == str(mmproj.resolve())
diff --git a/studio/backend/tests/test_export_log_cursor.py b/studio/backend/tests/test_export_log_cursor.py
index 253922ce74..25f276b0f5 100644
--- a/studio/backend/tests/test_export_log_cursor.py
+++ b/studio/backend/tests/test_export_log_cursor.py
@@ -4,24 +4,21 @@
 """
 Regression tests for the export log ring-buffer cursor semantics.
 
-Context: the live export log SSE stream has a race where the frontend
-opens the SSE connection AFTER the POST that starts the export. Any
-lines the worker subprocess emits during the gap between POST and SSE
-connect get buffered with seqs 1..k, and then the SSE default cursor
-`get_current_log_seq()` returns k -- so lines 1..k are forever
-unreachable to that client.
+Context: the live export log SSE stream has a race where the frontend opens
+the SSE connection AFTER the POST that starts the export. Lines the worker
+emits in the gap between POST and SSE connect get buffered with seqs 1..k,
+and the SSE default cursor `get_current_log_seq()` returns k -- so lines
+1..k are forever unreachable to that client.
 
-Fix: `clear_logs()` snapshots the pre-run seq into `_run_start_seq`
-(exposed via `get_run_start_seq()`), and `routes/export.py` defaults
-the SSE cursor to that snapshot instead of the current seq. Every line
-appended during the current run has seq strictly greater than the
-snapshot, so the client sees the full run regardless of when it
-connects.
+Fix: `clear_logs()` snapshots the pre-run seq into `_run_start_seq` (exposed
+via `get_run_start_seq()`), and `routes/export.py` defaults the SSE cursor
+to that snapshot instead of the current seq. Every line appended during the
+run has seq strictly greater than the snapshot, so the client sees the full
+run regardless of when it connects.
 
-These tests exercise the orchestrator-side contract only (no
-subprocess, no FastAPI, no frontend). The routes-level integration
-with get_run_start_seq() is a one-line edit covered by manual testing
-and the frontend build.
+These tests exercise the orchestrator-side contract only (no subprocess,
+FastAPI, or frontend). The routes-level integration with get_run_start_seq()
+is a one-line edit covered by manual testing and the frontend build.
 """
 
 from __future__ import annotations
@@ -39,21 +36,17 @@ _BACKEND_DIR = Path(__file__).resolve().parent.parent
 if str(_BACKEND_DIR) not in sys.path:
     sys.path.insert(0, str(_BACKEND_DIR))
 
-# ExportOrchestrator imports structlog and a few heavy modules at the
-# top of orchestrator.py. Stub the ones we don't need in these unit
-# tests so the import succeeds on machines without the full studio
-# venv.
+# orchestrator.py imports structlog and a few heavy modules at the top. Stub
+# the ones we don't need so the import succeeds without the full studio venv.
 _loggers_stub = types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
 
-# structlog is only used for a module-level import; a bare stub is
-# enough because we never call into it in these tests.
+# structlog is only a module-level import here; a bare stub suffices.
 sys.modules.setdefault("structlog", types.ModuleType("structlog"))
 
-# utils.paths.outputs_root is only called inside scan_checkpoints which
-# we don't hit in these tests. Provide a stub module so the top-level
-# import in orchestrator.py resolves.
+# utils.paths.outputs_root is only called inside scan_checkpoints, which we
+# don't hit; stub it so orchestrator.py's top-level import resolves.
 _utils_pkg = types.ModuleType("utils")
 _utils_pkg.__path__ = []  # mark as package
 _utils_paths_stub = types.ModuleType("utils.paths")
@@ -84,14 +77,14 @@ def _append(
 
 
 def test_run_start_seq_is_zero_before_any_logs(orchestrator) -> None:
-    """A brand-new orchestrator must report run_start_seq == 0 so a
-    first SSE connection picks up every line from seq 1 onward."""
+    """New orchestrator must report run_start_seq == 0 so a first SSE
+    connection picks up every line from seq 1 onward."""
     assert orchestrator.get_run_start_seq() == 0
 
 
 def test_clear_logs_snapshots_current_seq(orchestrator) -> None:
-    """clear_logs() must capture _log_seq BEFORE clearing the buffer,
-    so subsequent runs can anchor their SSE cursor at the snapshot."""
+    """clear_logs() must capture _log_seq BEFORE clearing the buffer, so
+    subsequent runs can anchor their SSE cursor at the snapshot."""
     _append(orchestrator, "old run line 1")
     _append(orchestrator, "old run line 2")
     _append(orchestrator, "old run line 3")
@@ -109,13 +102,12 @@ def test_clear_logs_snapshots_current_seq(orchestrator) -> None:
 
 
 def test_sse_default_cursor_catches_all_current_run_lines(orchestrator) -> None:
-    """Simulate the POST-then-SSE race: worker starts emitting lines
-    immediately after clear_logs(), SSE connects several lines later.
-    Using get_run_start_seq() as the default cursor MUST return every
-    line emitted since clear_logs() ran.
+    """Simulate the POST-then-SSE race: worker emits lines right after
+    clear_logs(), SSE connects several lines later. get_run_start_seq() as
+    the default cursor MUST return every line emitted since clear_logs().
 
-    Pre-fix, the SSE defaulted to get_current_log_seq() at connect
-    time, which would return the last-seen seq and miss lines N+1..M.
+    Pre-fix, the SSE defaulted to get_current_log_seq() at connect time,
+    returning the last-seen seq and missing lines N+1..M.
     """
     # Previous run leaves some buffered lines.
     _append(orchestrator, "previous run line A")
@@ -130,8 +122,7 @@ def test_sse_default_cursor_catches_all_current_run_lines(orchestrator) -> None:
     _append(orchestrator, "Loading checkpoint: /foo/bar")
     _append(orchestrator, "Starting export...")
 
-    # SSE connects now and asks "give me everything after the run
-    # start cursor".
+    # SSE connects and asks for everything after the run start cursor.
     entries, new_cursor = orchestrator.get_logs_since(run_start)
 
     # All three early lines must be present. Pre-fix this was [].
@@ -145,9 +136,9 @@ def test_sse_default_cursor_catches_all_current_run_lines(orchestrator) -> None:
 
 
 def test_sse_default_cursor_excludes_previous_run(orchestrator) -> None:
-    """After clear_logs(), lines from the PREVIOUS run must not leak
-    into the new run's SSE stream. Pre-fix this worked correctly
-    (clear_logs cleared the deque); the fix must preserve it.
+    """After clear_logs(), PREVIOUS-run lines must not leak into the new
+    run's SSE stream. Pre-fix this worked (clear_logs cleared the deque);
+    the fix must preserve it.
     """
     _append(orchestrator, "previous run line 1")
     _append(orchestrator, "previous run line 2")
@@ -164,10 +155,9 @@ def test_sse_default_cursor_excludes_previous_run(orchestrator) -> None:
 
 
 def test_clear_logs_twice_advances_run_start(orchestrator) -> None:
-    """Back-to-back clear_logs() calls (e.g. cleanup -> load ->
-    export in the same dialog session) must each re-anchor run_start
-    at the current seq, so successive runs each start with a fresh
-    low-water mark."""
+    """Back-to-back clear_logs() calls (e.g. cleanup -> load -> export in one
+    dialog session) must each re-anchor run_start at the current seq, so
+    successive runs each start with a fresh low-water mark."""
     _append(orchestrator, "run 1 line a")
     _append(orchestrator, "run 1 line b")
 
diff --git a/studio/backend/tests/test_external_provider_usage_chunk.py b/studio/backend/tests/test_external_provider_usage_chunk.py
index afeb26e9e9..f462e1c8e9 100644
--- a/studio/backend/tests/test_external_provider_usage_chunk.py
+++ b/studio/backend/tests/test_external_provider_usage_chunk.py
@@ -2,14 +2,14 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Unit tests for the prompt-cache accounting chunk emitted by the external-
-provider streaming proxy.
+Unit tests for the prompt-cache accounting chunk emitted by the
+external-provider streaming proxy.
 
-The streaming Anthropic + OpenAI Responses paths now emit one extra
+The streaming Anthropic + OpenAI Responses paths emit one extra
 ``include_usage``-style SSE chunk (``choices: []`` with a populated
 ``usage`` block) just before ``[DONE]`` / after the final
-``finish_reason`` chunk. This lets clients surface cache savings
-without scraping the structlog stream.
+``finish_reason`` chunk, so clients see cache savings without scraping
+the structlog stream.
 
 Covers:
 - Helper alone: shape for Anthropic / OpenAI usage payloads, missing
@@ -20,8 +20,8 @@ Covers:
 - OpenAI Responses stream: ``response.completed.usage`` with
   ``input_tokens_details.cached_tokens`` produces the expected usage
   chunk after the ``stop`` finish_reason chunk.
-- OpenAI Responses ``response.incomplete`` also emits the usage chunk
-  so length-truncated turns still report cached tokens.
+- OpenAI Responses ``response.incomplete`` also emits the chunk so
+  length-truncated turns still report cached tokens.
 """
 
 import asyncio
@@ -57,9 +57,9 @@ def test_build_usage_chunk_anthropic_shape():
     assert payload["object"] == "chat.completion.chunk"
     assert payload["choices"] == []
     usage = payload["usage"]
-    # Anthropic's input_tokens excludes cache buckets; prompt_tokens
-    # must add all three input components together so downstream
-    # context / cost displays see the real prompt size.
+    # Anthropic's input_tokens excludes cache buckets; prompt_tokens must
+    # sum all three input components so downstream context/cost displays
+    # see the real prompt size.
     assert usage["prompt_tokens"] == 8 + 1367 + 18901
     assert usage["completion_tokens"] == 862
     assert usage["total_tokens"] == 8 + 1367 + 18901 + 862
@@ -92,9 +92,8 @@ def test_build_usage_chunk_openai_shape():
 
 
 def test_build_usage_chunk_missing_fields_default_to_zero():
-    # OpenAI Responses can return a usage object without
-    # input_tokens_details when prompt caching is unused; the helper
-    # should still emit a chunk with cached_tokens=0.
+    # OpenAI Responses can omit input_tokens_details when prompt caching is
+    # unused; the helper should still emit a chunk with cached_tokens=0.
     line = _build_usage_chunk(
         "chatcmpl-z",
         "openai",
@@ -107,7 +106,7 @@ def test_build_usage_chunk_missing_fields_default_to_zero():
 
 def test_build_usage_chunk_returns_none_when_all_zero():
     # If upstream errored before any usage event, suppress the chunk to
-    # avoid surfacing a misleading "0 tokens" line.
+    # avoid a misleading "0 tokens" line.
     assert _build_usage_chunk("id", "anthropic", {}) is None
     assert _build_usage_chunk("id", "anthropic", None) is None
     assert _build_usage_chunk("id", "openai", {}) is None
diff --git a/studio/backend/tests/test_frontend_resolution.py b/studio/backend/tests/test_frontend_resolution.py
index 3cdc755f7f..7224ee7a04 100644
--- a/studio/backend/tests/test_frontend_resolution.py
+++ b/studio/backend/tests/test_frontend_resolution.py
@@ -3,9 +3,8 @@
 
 """Tests for the frontend-dist resolver in studio/backend/run.py.
 
-Loads only the relevant helpers via importlib so the test does not pull in
-uvicorn / FastAPI / unsloth's full dependency tree. Pairs with the AST-style
-test_host_defaults.py.
+Loads only the relevant helpers via importlib to avoid pulling in
+uvicorn / FastAPI / unsloth's deps. Pairs with AST-style test_host_defaults.py.
 """
 
 import ast
@@ -19,7 +18,7 @@ _REPO_STUDIO_DIR = _RUN_PY.parent.parent  # studio/
 
 
 def _load_helpers_only():
-    """Import just the resolver helpers from run.py without executing the
+    """Import just the resolver helpers from run.py, skipping the
     server-side imports (uvicorn, structlog, etc.)."""
     source = _RUN_PY.read_text(encoding = "utf-8")
     tree = ast.parse(source)
@@ -91,7 +90,7 @@ def test_resolver_falls_back_to_studio_home_site_packages(tmp_path, monkeypatch)
 
 def test_resolver_falls_back_via_editable_pth(tmp_path, monkeypatch):
     """Simulates a `--local` install: dedicated venv with an editable .pth
-    pointing at a cloned repo that owns the built dist."""
+    pointing at a cloned repo owning the built dist."""
     studio_home = tmp_path / "studio_home"
     sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
     sp.mkdir(parents = True)
@@ -100,7 +99,7 @@ def test_resolver_falls_back_via_editable_pth(tmp_path, monkeypatch):
     repo_dist = repo_studio / "frontend" / "dist"
     repo_dist.mkdir(parents = True)
     (repo_dist / "index.html").write_text("<!doctype html>", encoding = "utf-8")
-    # Minimal `__editable___pkg_finder.py` carrying a MAPPING dict that
+    # Minimal `__editable___pkg_finder.py` with the MAPPING dict that
     # setuptools' editable install generator writes.
     finder = sp / "__editable___unsloth_0_0_0_finder.py"
     finder.write_text(
@@ -127,7 +126,7 @@ def test_iter_candidates_handles_missing_studio_home(tmp_path, monkeypatch):
 
 def test_resolver_falls_back_to_windows_layout_site_packages(tmp_path, monkeypatch):
     """Pins the `Lib/site-packages` (capital L) Windows venv layout
-    alongside the POSIX `lib/python*/site-packages` path."""
+    alongside the POSIX `lib/python*/site-packages`."""
     studio_home = tmp_path / "studio_home"
     sp_dist = (
         studio_home / "unsloth_studio" / "Lib" / "site-packages" / "studio" / "frontend" / "dist"
@@ -143,20 +142,19 @@ def test_resolver_falls_back_to_windows_layout_site_packages(tmp_path, monkeypat
 
 
 def test_resolver_does_not_crash_on_non_dict_mapping_literal(tmp_path, monkeypatch):
-    """A finder file whose MAPPING value is a set / list / non-dict literal
-    (theoretically possible if the regex matched a brace-delimited literal
-    that ast.literal_eval can parse) must not AttributeError. The resolver
-    should skip that finder and keep probing."""
+    """A finder whose MAPPING value is a set/list/non-dict literal (possible
+    if the regex matched a brace-delimited literal ast.literal_eval can parse)
+    must not AttributeError. The resolver should skip it and keep probing."""
     studio_home = tmp_path / "studio_home"
     sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
     sp.mkdir(parents = True)
-    # Bad finder: set literal, not a dict. ast.literal_eval parses it as set;
-    # any .get() call on it would raise AttributeError.
+    # Bad finder: set literal, not a dict. literal_eval parses it as a set,
+    # so any .get() call on it would raise AttributeError.
     (sp / "__editable___bad_0_0_0_finder.py").write_text(
         "MAPPING: dict[str, str] = {'studio', 'unsloth', 'unsloth_cli'}\n",
         encoding = "utf-8",
     )
-    # Good finder that should still be discovered after the bad one is skipped.
+    # Good finder, still discovered after the bad one is skipped.
     repo_root = tmp_path / "clone"
     repo_dist = repo_root / "studio" / "frontend" / "dist"
     repo_dist.mkdir(parents = True)
@@ -174,9 +172,8 @@ def test_resolver_does_not_crash_on_non_dict_mapping_literal(tmp_path, monkeypat
 
 
 def test_resolver_handles_multiline_mapping_dict(tmp_path, monkeypatch):
-    """A future setuptools / black reformat that wraps the MAPPING dict
-    across multiple lines must still parse and resolve. Locks in the
-    `[^}]*` + re.DOTALL behaviour."""
+    """A future setuptools/black reformat wrapping the MAPPING dict across
+    multiple lines must still parse and resolve. Locks in `[^}]*` + re.DOTALL."""
     studio_home = tmp_path / "studio_home"
     sp = studio_home / "unsloth_studio" / "lib" / "python3.13" / "site-packages"
     sp.mkdir(parents = True)
@@ -204,8 +201,8 @@ def test_resolver_handles_multiline_mapping_dict(tmp_path, monkeypatch):
 
 def test_systemexit_message_contains_actionable_fixes(tmp_path, monkeypatch):
     """The user-facing recovery message is a contract: it must surface the
-    attempted paths and every concrete fix. Pin its structure so a future
-    refactor doesn't drop one."""
+    attempted paths and every concrete fix. Pin its structure so a refactor
+    doesn't drop one."""
     import os
     import sys
 
diff --git a/studio/backend/tests/test_gemini_provider.py b/studio/backend/tests/test_gemini_provider.py
index 01ef2e16fd..85ceb04d27 100644
--- a/studio/backend/tests/test_gemini_provider.py
+++ b/studio/backend/tests/test_gemini_provider.py
@@ -24,9 +24,9 @@ Gemini does NOT speak OpenAI Chat Completions on its primary endpoint
         (delta.content for text, delta.tool_calls for functionCall,
          _toolEvent for image_b64/web_search, usage block before [DONE])
 
-These tests pin the outbound body shape AND the inbound translation
-using httpx.MockTransport (no live network). Mirrors the structure of
-test_anthropic_cache_ttl.py and test_openai_image_generation.py.
+These tests pin the outbound body shape AND the inbound translation via
+httpx.MockTransport (no live network). Mirrors test_anthropic_cache_ttl.py
+and test_openai_image_generation.py.
 """
 
 import asyncio
@@ -44,10 +44,9 @@ _active_mock_clients: list[httpx.AsyncClient] = []
 
 
 def _drive(coro):
-    # Create a fresh loop per drive so tests don't share asyncio state.
-    # Close mocked clients + shutdown async-generators inside this loop
-    # so Python 3.13 doesn't emit the
-    # `Response.aiter_*.aclose was never awaited` warning on GC.
+    # Fresh loop per drive so tests don't share asyncio state. Close mocked
+    # clients + shutdown async-generators inside this loop so Python 3.13
+    # doesn't emit `Response.aiter_*.aclose was never awaited` on GC.
     loop = asyncio.new_event_loop()
     try:
         result = loop.run_until_complete(coro)
@@ -75,8 +74,8 @@ def _make_gemini_client(
 def _mock_http(monkeypatch, handler):
     mock_client = httpx.AsyncClient(transport = httpx.MockTransport(handler))
     monkeypatch.setattr(ep_mod, "_http_client", mock_client)
-    # `_drive` will aclose this at the end of the run inside the same
-    # event loop so we do not leak an unawaited aclose() coroutine.
+    # `_drive` acloses this at end of run inside the same event loop, so we
+    # don't leak an unawaited aclose() coroutine.
     _active_mock_clients.append(mock_client)
 
 
@@ -98,7 +97,7 @@ def _capture_body(monkeypatch, **kwargs) -> dict:
         captured["headers"] = dict(request.headers)
         captured["url"] = str(request.url)
         captured["method"] = request.method
-        # Minimal valid Gemini stream so the helper can complete.
+        # Minimal valid Gemini stream so the helper completes.
         return httpx.Response(
             200,
             content = _gemini_sse(
@@ -262,7 +261,7 @@ def test_presence_penalty_forwarded_to_generation_config(monkeypatch):
     captured = _capture_body(monkeypatch, presence_penalty = 0.7)
     assert captured["body"]["generationConfig"]["presencePenalty"] == 0.7
 
-    # And the default of zero is omitted, matching top_k semantics.
+    # Default zero is omitted, matching top_k semantics.
     captured = _capture_body(monkeypatch, presence_penalty = 0.0)
     assert "presencePenalty" not in captured["body"]["generationConfig"]
 
@@ -282,7 +281,7 @@ def test_gemini25_flash_thinking_disabled_sets_budget_zero(monkeypatch):
 
 
 def test_gemini3_flash_thinking_disabled_uses_minimal_level(monkeypatch):
-    """Gemini 3 Flash migrated to thinkingLevel; "off" maps to minimal
+    """Gemini 3 Flash uses thinkingLevel; "off" maps to minimal
     (Gemini 3 cannot turn thinking fully off)."""
     captured = _capture_body(
         monkeypatch,
@@ -306,8 +305,8 @@ def test_gemini25_pro_thinking_disabled_uses_small_budget(monkeypatch):
 
 
 def test_gemini3_pro_thinking_disabled_uses_low_level(monkeypatch):
-    """Gemini 3 Pro uses thinkingLevel and rejects 'minimal' (Pro tier),
-    so 'off' coerces to 'low' (lowest the API accepts)."""
+    """Gemini 3 Pro uses thinkingLevel and rejects 'minimal' (Pro tier), so
+    'off' coerces to 'low' (lowest the API accepts)."""
     for model in (
         "gemini-3.1-pro-preview",
         "gemini-3-pro-preview",
@@ -402,16 +401,16 @@ def test_gemini3_flash_effort_none_maps_to_minimal(monkeypatch):
 
 
 def test_thinking_default_omits_thinking_config(monkeypatch):
-    """When neither knob is supplied, thinkingConfig is omitted entirely
-    (Google's server-side default applies)."""
+    """When neither knob is supplied, thinkingConfig is omitted (Google's
+    server-side default applies)."""
     captured = _capture_body(monkeypatch, model = "gemini-3.5-flash")
     gc = captured["body"]["generationConfig"]
     assert "thinkingConfig" not in gc, gc
 
 
 def test_nano_banana_alias_routes_through_image_modalities(monkeypatch):
-    """`nano-banana-pro-preview` is an alias for the Pro image model and
-    must set responseModalities=[TEXT,IMAGE] when the Images pill is on
+    """`nano-banana-pro-preview` aliases the Pro image model; must set
+    responseModalities=[TEXT,IMAGE] when the Images pill is on
     (enabled_tools includes "image_generation")."""
     captured = _capture_body(
         monkeypatch,
@@ -423,12 +422,11 @@ def test_nano_banana_alias_routes_through_image_modalities(monkeypatch):
 
 
 def test_image_capable_model_without_image_pill_stays_text_only(monkeypatch):
-    """When the Images pill is off (enabled_tools has no
-    image_generation), an image-capable model id (gemini-2.5-flash-image)
-    must force responseModalities=["TEXT"]. Google's image models
-    default to text+image when responseModalities is omitted, so
-    omitting it would silently bill image output the UI says is
-    disabled."""
+    """When the Images pill is off (no image_generation in enabled_tools), an
+    image-capable model id (gemini-2.5-flash-image) must force
+    responseModalities=["TEXT"]. Google's image models default to text+image
+    when responseModalities is omitted, so omitting it would silently bill
+    image output the UI says is disabled."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash-image",
@@ -439,9 +437,9 @@ def test_image_capable_model_without_image_pill_stays_text_only(monkeypatch):
 
 
 def test_image_models_skip_thinking_config(monkeypatch):
-    """Image-tier ids do not benefit from a visible thinking knob and
-    must NOT forward thinkingConfig even when stale UI state still
-    sends `reasoning_effort` or `enable_thinking=False`."""
+    """Image-tier ids have no visible thinking knob and must NOT forward
+    thinkingConfig even when stale UI state still sends `reasoning_effort` or
+    `enable_thinking=False`."""
     for model in (
         "gemini-2.5-flash-image",
         "gemini-3.1-flash-image-preview",
@@ -462,8 +460,8 @@ def test_image_models_skip_thinking_config(monkeypatch):
 def test_image_models_drop_code_execution(monkeypatch):
     """All image-tier ids reject `tools: [{codeExecution: {}}]`; drop
     silently. (Gemini 3 image models DO accept googleSearch -- see
-    test_gemini3_image_models_allow_google_search; older image models
-    drop everything.)"""
+    test_gemini3_image_models_allow_google_search; older ones drop
+    everything.)"""
     for model in (
         "gemini-2.5-flash-image",
         "gemini-3.1-flash-image-preview",
@@ -481,9 +479,8 @@ def test_image_models_drop_code_execution(monkeypatch):
 
 
 def test_gemini_35_pro_uses_thinking_level(monkeypatch):
-    """`gemini-3.5-pro` is part of the Gemini 3 family and uses
-    thinkingLevel (not thinkingBudget). "Off" maps to "low" because Pro
-    tier rejects "minimal"."""
+    """`gemini-3.5-pro` is Gemini 3 family and uses thinkingLevel (not
+    thinkingBudget). "Off" maps to "low" since Pro tier rejects "minimal"."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-3.5-pro",
@@ -525,9 +522,9 @@ def test_legacy_image_models_block_google_search(monkeypatch):
 
 
 def test_legacy_openai_base_url_normalized(monkeypatch):
-    """Saved Gemini providers carrying the legacy `/v1beta/openai` base
-    (from the pre-PR OpenAI-compat plumbing) now point at the native
-    endpoint without the user re-saving the connection."""
+    """Saved Gemini providers with the legacy `/v1beta/openai` base (from
+    pre-PR OpenAI-compat plumbing) now point at the native endpoint without
+    the user re-saving the connection."""
     client = ExternalProviderClient(
         provider_type = "gemini",
         base_url = "https://generativelanguage.googleapis.com/v1beta/openai",
@@ -538,7 +535,7 @@ def test_legacy_openai_base_url_normalized(monkeypatch):
 
 def test_finish_reason_swaps_to_tool_calls_when_function_call_emitted(monkeypatch):
     """Gemini emits finishReason="STOP" even for pure functionCall turns;
-    surface as `tool_calls` so OAI clients trigger tool execution."""
+    surface as `tool_calls` so OAI clients run the tool."""
     sse = [
         {
             "candidates": [
@@ -563,7 +560,7 @@ def test_finish_reason_swaps_to_tool_calls_when_function_call_emitted(monkeypatc
 
 def test_thought_signature_round_trips_into_gemini_function_call(monkeypatch):
     """An assistant tool_call carrying `extra_content.google.thought_signature`
-    must echo the value back as a sibling of the Gemini functionCall part."""
+    must echo it back as a sibling of the Gemini functionCall part."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -600,8 +597,8 @@ def test_thought_signature_round_trips_into_gemini_function_call(monkeypatch):
 
 
 def test_thought_signature_emitted_in_tool_call_delta(monkeypatch):
-    """A Gemini functionCall part with `thoughtSignature` must surface
-    that signature on the outbound OpenAI tool_calls delta via
+    """A Gemini functionCall part with `thoughtSignature` must surface it on
+    the outbound OpenAI tool_calls delta via
     `extra_content.google.thought_signature`."""
     sse = [
         {
@@ -637,10 +634,10 @@ def test_thought_signature_emitted_in_tool_call_delta(monkeypatch):
 
 
 def test_image_models_suppress_phantom_web_search_card(monkeypatch):
-    """When the image guard filters googleSearch out of the outbound
-    request, the inbound stream must NOT emit web_search tool_start /
-    tool_end (otherwise the UI shows a misleading 'Search complete'
-    card on a turn where Gemini never actually searched)."""
+    """When the image guard filters googleSearch out of the request, the
+    inbound stream must NOT emit web_search tool_start / tool_end (else the UI
+    shows a misleading 'Search complete' card on a turn Gemini never
+    searched)."""
     sse = [
         {
             "candidates": [
@@ -669,10 +666,10 @@ def test_image_models_suppress_phantom_web_search_card(monkeypatch):
 
 def test_image_generation_tool_on_image_model_drops_text_tools(monkeypatch):
     """`enabled_tools=["image_generation", "web_search", "code_execution"]`
-    on a Gemini IMAGE model flips responseModalities to TEXT+IMAGE; in
-    that mode codeExecution must NOT be forwarded (Gemini rejects text
-    code tools alongside image responseModalities). Older image
-    families also drop googleSearch."""
+    on a Gemini IMAGE model flips responseModalities to TEXT+IMAGE; in that
+    mode codeExecution must NOT be forwarded (Gemini rejects text code tools
+    alongside image responseModalities). Older image families also drop
+    googleSearch."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash-image",
@@ -687,8 +684,8 @@ def test_image_generation_tool_on_image_model_drops_text_tools(monkeypatch):
 
 
 def test_prompt_feedback_block_reason_surfaces_as_error(monkeypatch):
-    """`promptFeedback.blockReason` with zero candidates must produce
-    an error chunk, not a silent empty assistant reply."""
+    """`promptFeedback.blockReason` with zero candidates must produce an error
+    chunk, not a silent empty assistant reply."""
     sse = [
         {
             "promptFeedback": {"blockReason": "SAFETY"},
@@ -701,10 +698,10 @@ def test_prompt_feedback_block_reason_surfaces_as_error(monkeypatch):
 
 
 def test_usage_chunk_includes_thoughts_tokens(monkeypatch):
-    """`thoughtsTokenCount` is the hidden-reasoning slice of output;
-    roll it into `output_tokens` AND surface it on
-    `output_tokens_details.reasoning_tokens` so total_tokens reflects
-    the full billable spend."""
+    """`thoughtsTokenCount` is the hidden-reasoning slice of output; roll it
+    into `output_tokens` AND surface it on
+    `output_tokens_details.reasoning_tokens` so total_tokens reflects the full
+    billable spend."""
     sse = [
         {
             "candidates": [
@@ -918,16 +915,16 @@ def test_tool_message_translates_to_function_response_part(monkeypatch):
     ]
     captured = _capture_body(monkeypatch, messages = messages)
     contents = captured["body"]["contents"]
-    # Last turn must be a functionResponse part (Gemini wraps it as a
-    # role=user turn carrying the result).
+    # Last turn must be a functionResponse part (Gemini wraps it as a role=user
+    # turn carrying the result).
     last = contents[-1]
     assert last["role"] == "user", last
     fr = last["parts"][0].get("functionResponse")
     assert fr is not None, last
     assert fr["name"] == "get_weather"
     assert fr["response"] == {"temp_c": 18, "summary": "Sunny"}
-    # And the assistant turn carries the original functionCall so the
-    # model sees the round-trip context.
+    # And the assistant turn carries the original functionCall so the model
+    # sees the round-trip context.
     assistant_turn = [c for c in contents if c["role"] == "model"][0]
     fc_part = next(
         (p for p in assistant_turn["parts"] if "functionCall" in p),
@@ -940,8 +937,8 @@ def test_tool_message_translates_to_function_response_part(monkeypatch):
 
 def test_parallel_function_calls_get_distinct_tool_call_indices(monkeypatch):
     """Each emitted functionCall in one assistant turn needs its own
-    tool_calls[*].index. Hardcoding index=0 collapses parallel calls
-    onto a single slot in OpenAI-style reassemblers."""
+    tool_calls[*].index. Hardcoding index=0 collapses parallel calls onto one
+    slot in OpenAI-style reassemblers."""
     sse = [
         {
             "candidates": [
@@ -1117,8 +1114,8 @@ def test_code_execution_parts_translate_to_code_execution_tool_events(monkeypatc
     assert code_starts[0]["arguments"]["code"] == "print(2+2)"
     assert code_starts[0]["arguments"]["language"] == "python"
     assert len(code_ends) == 1, tool_events
-    # tool_start and tool_end must share the same tool_call_id so the
-    # frontend pairs them onto a single CodeExecutionToolUI block.
+    # tool_start and tool_end must share a tool_call_id so the frontend pairs
+    # them onto one CodeExecutionToolUI block.
     assert code_starts[0]["tool_call_id"] == code_ends[0]["tool_call_id"]
 
 
@@ -1360,8 +1357,8 @@ def test_grounding_metadata_surfaces_as_tool_end_citations(monkeypatch):
 
 
 def test_custom_gemini_proxy_base_url_not_rewritten():
-    """Only the Google-hosted /v1beta/openai base is normalized; a
-    custom gateway whose path ends in /openai must be left alone."""
+    """Only the Google-hosted /v1beta/openai base is normalized; a custom
+    gateway whose path ends in /openai must be left alone."""
     client = ExternalProviderClient(
         provider_type = "gemini",
         base_url = "https://proxy.example.com/team/openai",
@@ -1371,10 +1368,9 @@ def test_custom_gemini_proxy_base_url_not_rewritten():
 
 
 def test_custom_gemini_proxy_uses_openai_dispatch():
-    """Any non-Google Gemini base (LiteLLM, custom OpenAI-compat
-    routers) must route through the OpenAI-compatible forwarder, not
-    the native translator. Auth uses Authorization: Bearer ..., not
-    x-goog-api-key."""
+    """Any non-Google Gemini base (LiteLLM, custom OpenAI-compat routers) must
+    route through the OpenAI-compatible forwarder, not the native translator.
+    Auth uses Authorization: Bearer ..., not x-goog-api-key."""
     for base in (
         "https://proxy.example.com/team/openai",
         "https://proxy.example.com/v1",
@@ -1405,8 +1401,8 @@ def test_google_hosted_gemini_still_uses_native_dispatch():
 
 def test_invalid_gemini_model_id_rejected_before_request(monkeypatch):
     """Path-traversal model ids must be rejected before the URL is
-    interpolated so the configured API key isn't sent to unintended
-    Gemini endpoints."""
+    interpolated, so the configured API key isn't sent to unintended Gemini
+    endpoints."""
 
     captured: list[httpx.Request] = []
 
@@ -1442,17 +1438,16 @@ def test_invalid_gemini_model_id_rejected_before_request(monkeypatch):
 
 
 def test_top_k_omitted_when_not_explicit_default_for_gemini(monkeypatch):
-    """top_k=None means "use provider default"; helper must not emit
-    `topK` in generationConfig when the caller didn't pass it."""
+    """top_k=None means "use provider default"; helper must not emit `topK` in
+    generationConfig when the caller didn't pass it."""
     captured = _capture_body(monkeypatch, top_k = None)
     assert "topK" not in captured["body"]["generationConfig"], captured["body"]
 
 
 def test_text_model_image_generation_tool_silently_dropped(monkeypatch):
-    """A stale `enabled_tools=["image_generation"]` on a text-only
-    Gemini model (e.g. gemini-2.5-flash) must NOT switch the request
-    into image mode -- Google's API 400s on responseModalities for
-    text models."""
+    """A stale `enabled_tools=["image_generation"]` on a text-only Gemini
+    model (e.g. gemini-2.5-flash) must NOT switch the request into image mode
+    -- Google's API 400s on responseModalities for text models."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash",
@@ -1464,8 +1459,8 @@ def test_text_model_image_generation_tool_silently_dropped(monkeypatch):
 
 def test_empty_text_part_with_thought_signature_emits_extra_content(monkeypatch):
     """Gemini 3 can ship a content-free fragment whose only payload is
-    `thoughtSignature`. The translator must still surface that signature
-    on a delta.extra_content envelope so the next turn can replay it."""
+    `thoughtSignature`. The translator must still surface it on a
+    delta.extra_content envelope so the next turn can replay it."""
     sse = [
         {
             "candidates": [
@@ -1499,9 +1494,9 @@ def test_empty_text_part_with_thought_signature_emits_extra_content(monkeypatch)
 
 
 def test_enable_prompt_caching_false_string_coerces_to_bool():
-    """Pre-PR the field was Optional[bool]; widening to Union[bool,str]
-    must preserve historical coercion so callers sending `"false"`
-    still opt out of caching."""
+    """Pre-PR the field was Optional[bool]; widening to Union[bool,str] must
+    preserve historical coercion so callers sending `"false"` still opt out of
+    caching."""
     from models.inference import ChatCompletionRequest
 
     msg = {"role": "user", "content": "hi"}
@@ -1545,10 +1540,9 @@ def test_legacy_google_openai_base_url_is_rewritten():
 
 
 def test_remote_image_url_downloads_and_inlines_as_base64(monkeypatch):
-    """Round 14: arbitrary public HTTPS image URLs cannot be sent as
-    Gemini fileData (that path is reserved for Files API URIs and
-    YouTube). The translator must fetch the bytes server-side and
-    inline them as base64 inlineData."""
+    """Round 14: arbitrary public HTTPS image URLs cannot be sent as Gemini
+    fileData (reserved for Files API URIs and YouTube). The translator must
+    fetch the bytes server-side and inline them as base64 inlineData."""
     image_bytes = b"FAKEPNGBYTES"
 
     async def fake_fetch(
@@ -1586,10 +1580,9 @@ def test_remote_image_url_downloads_and_inlines_as_base64(monkeypatch):
 
 
 def test_remote_image_url_dropped_when_fetch_returns_none(monkeypatch):
-    """Round 15: if the SSRF guard rejects the URL (private host,
-    non-https, oversize, non-image), the helper returns None and the
-    image part is silently dropped instead of forwarding raw bytes
-    or a fileData fallback."""
+    """Round 15: if the SSRF guard rejects the URL (private host, non-https,
+    oversize, non-image), the helper returns None and the image part is
+    silently dropped, not forwarded as raw bytes or a fileData fallback."""
 
     async def fake_fetch_reject(
         url,
@@ -1628,8 +1621,8 @@ def test_safe_fetch_image_rejects_non_https():
 
 
 def test_safe_fetch_image_rejects_loopback_ip_literal():
-    """SSRF guard: refuse loopback / private IP literals before any
-    network call."""
+    """SSRF guard: refuse loopback / private IP literals before any network
+    call."""
     for url in (
         "https://127.0.0.1/x.png",
         "https://[::1]/x.png",
@@ -1658,9 +1651,9 @@ def test_safe_fetch_image_rejects_resolved_private_host(monkeypatch):
 
 
 def test_youtube_and_files_api_uris_stay_as_file_data(monkeypatch):
-    """Round 14: YouTube URLs and generativelanguage.googleapis.com
-    Files API URIs are the documented `fileData.fileUri` paths and
-    must NOT be downloaded; arbitrary public URLs do get fetched."""
+    """Round 14: YouTube URLs and generativelanguage.googleapis.com Files API
+    URIs are the documented `fileData.fileUri` paths and must NOT be
+    downloaded; arbitrary public URLs do get fetched."""
     captured: dict = {}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -1730,8 +1723,8 @@ def test_youtube_and_files_api_uris_stay_as_file_data(monkeypatch):
 
 
 def test_tool_use_prompt_tokens_added_to_input_tokens(monkeypatch):
-    """`toolUsePromptTokenCount` must roll into the OpenAI prompt
-    total -- otherwise tool turns silently undercount input tokens."""
+    """`toolUsePromptTokenCount` must roll into the OpenAI prompt total --
+    else tool turns silently undercount input tokens."""
     sse = [
         {
             "candidates": [
@@ -1763,8 +1756,9 @@ def test_tool_use_prompt_tokens_added_to_input_tokens(monkeypatch):
 
 
 def test_usage_chunk_reasoning_tokens_surfaced(monkeypatch):
-    """thoughtsTokenCount must surface as completion_tokens_details.
-    reasoning_tokens in the emitted OpenAI usage chunk."""
+    """thoughtsTokenCount must surface as
+    completion_tokens_details.reasoning_tokens in the emitted OpenAI usage
+    chunk."""
     sse = [
         {
             "candidates": [
@@ -1794,8 +1788,8 @@ def test_usage_chunk_reasoning_tokens_surfaced(monkeypatch):
 
 def test_prompt_block_pairs_web_search_tool_end(monkeypatch):
     """When `promptFeedback.blockReason` triggers after the synthetic
-    web_search tool_start, the helper must emit a matching tool_end so
-    the UI does not leave a "searching..." spinner stuck on screen."""
+    web_search tool_start, the helper must emit a matching tool_end so the UI
+    doesn't leave a "searching..." spinner stuck on screen."""
     sse = [
         {"promptFeedback": {"blockReason": "SAFETY"}},
     ]
@@ -1817,9 +1811,9 @@ def test_prompt_block_pairs_web_search_tool_end(monkeypatch):
 
 
 def test_code_execution_tool_events_stow_native_part(monkeypatch):
-    """executableCode / codeExecutionResult must round-trip native ids
-    and thoughtSignature in google.native_part so follow-up turns can
-    replay Gemini's required history shape."""
+    """executableCode / codeExecutionResult must round-trip native ids and
+    thoughtSignature in google.native_part so follow-up turns can replay
+    Gemini's required history shape."""
     sse = [
         {
             "candidates": [
@@ -1870,7 +1864,7 @@ def test_code_execution_tool_events_stow_native_part(monkeypatch):
     assert code_start is not None, starts
     assert code_start["tool_call_id"] == "code_a", code_start
     native = code_start["arguments"]["google"]["native_part"]
-    # Round 21: native_part now uses an ordered `parts` list so per-part
+    # Round 21: native_part uses an ordered `parts` list so per-part
     # `thoughtSignature` survives a frontend merge of executableCode +
     # codeExecutionResult into one tool-call card.
     start_parts = native["parts"]
@@ -1884,8 +1878,8 @@ def test_code_execution_tool_events_stow_native_part(monkeypatch):
 
 
 def test_inline_image_tool_end_carries_thought_signature(monkeypatch):
-    """Inline image parts with thoughtSignature must persist it on the
-    emitted tool_end so Gemini 3 image editing can echo it back."""
+    """Inline image parts with thoughtSignature must persist it on the emitted
+    tool_end so Gemini 3 image editing can echo it back."""
     sse = [
         {
             "candidates": [
@@ -1921,11 +1915,11 @@ def test_inline_image_tool_end_carries_thought_signature(monkeypatch):
     image_ends = [e for e in tool_events if e.get("type") == "tool_end" and e.get("image_b64")]
     assert image_ends, tool_events
     assert image_ends[0]["google"]["thought_signature"] == "SIG-IMG"
-    # Multi-turn image edit must replay the original inlineData part with
-    # its thoughtSignature; the outbound translator reads
-    # google.native_part.parts[].inlineData, so stow it on the tool_end
-    # too. Round 21 changed native_part to an ordered parts list so a
-    # per-part signature stays attached to inlineData only.
+    # Multi-turn image edit must replay the original inlineData part with its
+    # thoughtSignature; the outbound translator reads
+    # google.native_part.parts[].inlineData, so stow it on the tool_end too.
+    # Round 21 made native_part an ordered parts list so a per-part signature
+    # stays attached to inlineData only.
     native = image_ends[0]["google"]["native_part"]
     image_parts = native["parts"]
     assert image_parts[0]["inlineData"]["mimeType"] == "image/png"
@@ -1934,10 +1928,9 @@ def test_inline_image_tool_end_carries_thought_signature(monkeypatch):
 
 
 def test_code_execution_plot_attaches_inline_image_native_part(monkeypatch):
-    """A code_execution turn that returns a matplotlib plot must stow
-    the plot's inlineData on the secondary tool_end so the follow-up
-    turn can replay the image alongside executableCode and
-    codeExecutionResult."""
+    """A code_execution turn that returns a matplotlib plot must stow the
+    plot's inlineData on the secondary tool_end so the follow-up turn can
+    replay the image alongside executableCode and codeExecutionResult."""
     plot_data = base64.b64encode(b"PLOT").decode()
     sse = [
         {
@@ -1987,11 +1980,11 @@ def test_code_execution_plot_attaches_inline_image_native_part(monkeypatch):
     code_ends = [
         e for e in tool_events if e.get("type") == "tool_end" and e.get("tool_call_id") == "code_a"
     ]
-    # Two tool_end events on the same id: one for codeExecutionResult,
-    # one merging in the inlineData plot. The plot one must carry the
-    # native inlineData under google.native_part so the frontend
-    # tool_end merge union joins it with the prior executableCode and
-    # codeExecutionResult parts on the same card.
+    # Two tool_end events on the same id: one for codeExecutionResult, one
+    # merging in the inlineData plot. The plot one must carry the native
+    # inlineData under google.native_part so the frontend tool_end merge union
+    # joins it with the prior executableCode and codeExecutionResult parts on
+    # the same card.
     assert len(code_ends) == 2, code_ends
     image_end = next(
         (e for e in code_ends if "__IMAGES__:" in (e.get("result") or "")),
@@ -2005,8 +1998,8 @@ def test_code_execution_plot_attaches_inline_image_native_part(monkeypatch):
 
 
 def test_text_chunk_carries_thought_signature(monkeypatch):
-    """Text parts with thoughtSignature surface it on delta.extra_content
-    so frontend persistence can replay it on the follow-up turn."""
+    """Text parts with thoughtSignature surface it on delta.extra_content so
+    frontend persistence can replay it on the follow-up turn."""
     sse = [
         {
             "candidates": [
@@ -2040,8 +2033,8 @@ def test_text_chunk_carries_thought_signature(monkeypatch):
 
 
 def test_openai_tools_translated_into_function_declarations(monkeypatch):
-    """Standard ChatCompletionRequest.tools must be forwarded into
-    Gemini's tools[].functionDeclarations envelope."""
+    """Standard ChatCompletionRequest.tools must be forwarded into Gemini's
+    tools[].functionDeclarations envelope."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -2093,11 +2086,10 @@ def test_tool_choice_auto_maps_to_function_calling_mode_auto(monkeypatch):
 
 
 def test_code_exec_inline_image_attaches_to_code_execution_card(monkeypatch):
-    """A codeExecution sandbox plot (matplotlib) ships as an inline
-    image part right after the codeExecutionResult. Instead of spawning
-    a separate empty image_generation card, attach to the same
-    code_execution tool_end via the `__IMAGES__:` marker the chat
-    adapter already understands."""
+    """A codeExecution sandbox plot (matplotlib) ships as an inline image part
+    right after the codeExecutionResult. Instead of a separate empty
+    image_generation card, attach to the same code_execution tool_end via the
+    `__IMAGES__:` marker the chat adapter already understands."""
     sse = [
         {
             "candidates": [
@@ -2164,9 +2156,9 @@ def test_code_exec_inline_image_attaches_to_code_execution_card(monkeypatch):
 
 def test_code_execution_tool_call_replays_native_executable_code(monkeypatch):
     """An assistant tool_call with toolName=code_execution and
-    extra_content.google.native_part containing the originally-emitted
-    `executableCode` + `codeExecutionResult` must round-trip as native
-    Gemini parts (not a generic functionCall) on the next turn."""
+    extra_content.google.native_part holding the originally-emitted
+    `executableCode` + `codeExecutionResult` must round-trip as native Gemini
+    parts (not a generic functionCall) on the next turn."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -2220,10 +2212,9 @@ def test_code_execution_tool_call_replays_native_executable_code(monkeypatch):
 
 def test_image_generation_tool_call_replays_native_inline_data(monkeypatch):
     """An assistant tool_call with toolName=image_generation and
-    extra_content.google.native_part.inlineData must replay the prior
-    image as a native Gemini inlineData part (not a generic
-    functionCall) so multi-turn image editing keeps the image
-    context."""
+    extra_content.google.native_part.inlineData must replay the prior image as
+    a native Gemini inlineData part (not a generic functionCall) so multi-turn
+    image editing keeps the image context."""
     pixel = base64.b64encode(b"PNG").decode()
     captured = _capture_body(
         monkeypatch,
@@ -2273,11 +2264,11 @@ def test_image_generation_tool_call_replays_native_inline_data(monkeypatch):
 
 
 def test_assistant_text_thought_signature_replays_on_outbound_text_part(monkeypatch):
-    """Assistant text with extra_content.google.thought_signature must
-    attach `thoughtSignature` to the LAST text part of the replayed
-    Gemini history. Gemini 3 strict function-calling rejects history
-    that drops returned signatures, so the frontend stows the latest
-    signed-text signature and the backend pins it on the next turn."""
+    """Assistant text with extra_content.google.thought_signature must attach
+    `thoughtSignature` to the LAST text part of the replayed Gemini history.
+    Gemini 3 strict function-calling rejects history that drops returned
+    signatures, so the frontend stows the latest signed-text signature and the
+    backend pins it on the next turn."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -2303,10 +2294,10 @@ def test_assistant_text_thought_signature_replays_on_outbound_text_part(monkeypa
 
 
 def test_function_declarations_strip_openai_only_schema_keys(monkeypatch):
-    """OpenAI strict tools commonly include `additionalProperties`,
-    `$schema`, `$defs`, `strict`, etc. Gemini's Schema rejects those
-    with INVALID_ARGUMENT, so the translator must strip them while
-    keeping properties.<field>.type intact."""
+    """OpenAI strict tools commonly include `additionalProperties`, `$schema`,
+    `$defs`, `strict`, etc. Gemini's Schema rejects those with
+    INVALID_ARGUMENT, so the translator must strip them while keeping
+    properties.<field>.type intact."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -2349,12 +2340,12 @@ def test_function_declarations_strip_openai_only_schema_keys(monkeypatch):
 
 
 def test_function_declarations_inline_local_refs_into_gemini_schema(monkeypatch):
-    """Round 25: Pydantic-generated tool schemas hoist nested object
-    shapes into `$defs` and reference them with `{"$ref": "#/$defs/..."}`.
-    Gemini's OpenAPI subset has no $ref, so a naive allowlist sanitizer
-    drops the reference and reduces the nested property to `{}`, losing
-    its type, fields, and required keys. The sanitizer must resolve
-    local `#/...` pointers and inline the referenced schema."""
+    """Round 25: Pydantic-generated tool schemas hoist nested object shapes
+    into `$defs` and reference them with `{"$ref": "#/$defs/..."}`. Gemini's
+    OpenAPI subset has no $ref, so a naive allowlist sanitizer drops the
+    reference and reduces the nested property to `{}`, losing its type, fields,
+    and required keys. The sanitizer must resolve local `#/...` pointers and
+    inline the referenced schema."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -2401,9 +2392,8 @@ def test_function_declarations_inline_local_refs_into_gemini_schema(monkeypatch)
 
 
 def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch):
-    """The recursive inliner must reach through `anyOf` branches and
-    `items` (array element schemas) as well, not just top-level
-    property refs."""
+    """The recursive inliner must reach through `anyOf` branches and `items`
+    (array element schemas), not just top-level property refs."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -2446,8 +2436,8 @@ def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch)
     params = decls[0]["parameters"]
     primary = params["properties"]["primary"]
     # anyOf with single non-null branch + null collapses to inline +
-    # nullable: true, and the inlined branch must contain the resolved
-    # Address shape.
+    # nullable: true; the inlined branch must contain the resolved Address
+    # shape.
     assert primary.get("nullable") is True
     assert primary.get("type") == "object"
     assert primary.get("properties", {}).get("zip", {}).get("type") == "string"
@@ -2458,9 +2448,9 @@ def test_function_declarations_inline_local_refs_in_anyof_and_items(monkeypatch)
 
 
 def test_function_declarations_self_referential_schema_terminates(monkeypatch):
-    """Self-referential / cyclic JSON Schemas (a `Node` that contains
-    `children: [Node]`) must not infinite-loop. The inliner tracks the
-    set of refs in flight and short-circuits to `{}` on a cycle."""
+    """Self-referential / cyclic JSON Schemas (a `Node` with `children:
+    [Node]`) must not infinite-loop. The inliner tracks the set of refs in
+    flight and short-circuits to `{}` on a cycle."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -2503,10 +2493,10 @@ def test_function_declarations_self_referential_schema_terminates(monkeypatch):
 
 def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(monkeypatch):
     """Round 26: when the assistant-side synthetic web_search/web_fetch
-    tool_call is dropped from native Gemini history, the matching
-    role="tool" follow-up must also be dropped. Otherwise the outbound
-    body carries an orphan functionResponse with no preceding
-    functionCall, which 400s the Gemini turn."""
+    tool_call is dropped from native Gemini history, the matching role="tool"
+    follow-up must also be dropped. Otherwise the outbound body carries an
+    orphan functionResponse with no preceding functionCall, which 400s the
+    Gemini turn."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -2556,12 +2546,12 @@ def test_gemini_native_skips_orphan_function_response_for_dropped_builtin(monkey
 
 
 def test_gemini_native_skips_orphan_function_response_for_native_part_replay(monkeypatch):
-    """Round 26: code_execution / image_generation tool_calls are
-    replayed as Gemini-native executableCode / codeExecutionResult /
-    inlineData parts. The matching role="tool" follow-up must NOT then
-    be emitted as a functionResponse named code_execution -- there is
-    no declared user function with that name, and Gemini's history
-    rules already attribute the result to the native parts above."""
+    """Round 26: code_execution / image_generation tool_calls are replayed as
+    Gemini-native executableCode / codeExecutionResult / inlineData parts. The
+    matching role="tool" follow-up must NOT then be emitted as a
+    functionResponse named code_execution -- there is no declared user
+    function with that name, and Gemini's history rules already attribute the
+    result to the native parts above."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -2622,17 +2612,16 @@ def test_gemini_native_skips_orphan_function_response_for_native_part_replay(mon
 
 
 def test_gemini_native_part_falls_back_to_args_google(monkeypatch):
-    """Round 27: a direct OpenAI-compat API caller (or imported third-
-    party thread) cannot use Studio's non-standard
-    `tool_calls[].extra_content` field, so the native_part payload
-    round-trips through `function.arguments` as
-    `{"google": {"native_part": {...}}}`. The synthetic-builtin
-    detector recognizes that location, but the replay branch was only
-    reading from `tc.extra_content.google.native_part`. Result: the
-    round-25 guard saw a synthetic builtin with no _native_part and
-    dropped the entire assistant turn, losing the prior code/image
-    context. The translator must fall back to args.google.native_part
-    and still emit the native executableCode / inlineData parts."""
+    """Round 27: a direct OpenAI-compat API caller (or imported third-party
+    thread) cannot use Studio's non-standard `tool_calls[].extra_content`
+    field, so the native_part payload round-trips through `function.arguments`
+    as `{"google": {"native_part": {...}}}`. The synthetic-builtin detector
+    recognizes that location, but the replay branch was only reading from
+    `tc.extra_content.google.native_part`. Result: the round-25 guard saw a
+    synthetic builtin with no _native_part and dropped the entire assistant
+    turn, losing the prior code/image context. The translator must fall back
+    to args.google.native_part and still emit the native executableCode /
+    inlineData parts."""
     import json as _json
 
     captured = _capture_body(
@@ -2682,11 +2671,11 @@ def test_gemini_native_part_falls_back_to_args_google(monkeypatch):
 
 def test_gemini_native_skips_synthetic_server_builtin_replay(monkeypatch):
     """Round 25: Marked server-side builtin tool_calls (web_search /
-    web_fetch with `_server_tool` or `args.google.native_part`) must
-    not fall through to the generic Gemini `functionCall` replay path
-    when no replayable native part exists. Without this guard the
-    outbound body contains a fake `functionCall` whose name is not a
-    declared user function, and the Gemini turn 400s."""
+    web_fetch with `_server_tool` or `args.google.native_part`) must not fall
+    through to the generic Gemini `functionCall` replay path when no replayable
+    native part exists. Without this guard the outbound body contains a fake
+    `functionCall` whose name isn't a declared user function, and the Gemini
+    turn 400s."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -2736,10 +2725,10 @@ def test_gemini_native_skips_synthetic_server_builtin_replay(monkeypatch):
 
 
 def test_chat_message_extra_content_round_trips_through_validation():
-    """Round 9: ChatMessage was missing `extra_content`, so Pydantic
-    discarded the field during request validation and the text-part
-    signature replay path read nothing. The field must survive
-    model_validate and pass through _build_external_messages."""
+    """Round 9: ChatMessage was missing `extra_content`, so Pydantic discarded
+    it during request validation and the text-part signature replay path read
+    nothing. The field must survive model_validate and pass through
+    _build_external_messages."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -2774,16 +2763,16 @@ def test_chat_message_extra_content_round_trips_through_validation():
     assistant_out = built[1]
     assert assistant_out["extra_content"] == {"google": {"thought_signature": "SIG-TEXT"}}
     # Non-Gemini providers must NOT receive extra_content; Google's
-    # thought_signature field is unknown to OpenAI / Mistral / etc.
+    # thought_signature is unknown to OpenAI / Mistral / etc.
     built_openai = _build_external_messages(
         req.messages,
         supports_vision = True,
         provider_type = "openai",
     )
     assert "extra_content" not in built_openai[1], built_openai[1]
-    # Custom non-Google Gemini bases (LiteLLM / OAI-compat gateways)
-    # also must not receive Gemini-only extra_content because the
-    # backend dispatches them through /chat/completions.
+    # Custom non-Google Gemini bases (LiteLLM / OAI-compat gateways) also must
+    # not receive Gemini-only extra_content -- the backend dispatches them
+    # through /chat/completions.
     built_custom = _build_external_messages(
         req.messages,
         supports_vision = True,
@@ -2794,11 +2783,10 @@ def test_chat_message_extra_content_round_trips_through_validation():
 
 
 def test_parallel_tool_results_group_into_one_user_block(monkeypatch):
-    """Round 14: Gemini docs show parallel functionResponses grouped
-    in a single subsequent user content with multiple
-    functionResponse parts. Consecutive OpenAI role="tool" messages
-    must merge into one Gemini user block, not split into separate
-    user turns."""
+    """Round 14: Gemini docs group parallel functionResponses in a single
+    subsequent user content with multiple functionResponse parts. Consecutive
+    OpenAI role="tool" messages must merge into one Gemini user block, not
+    split into separate user turns."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -2850,10 +2838,9 @@ def test_parallel_tool_results_group_into_one_user_block(monkeypatch):
 
 
 def test_function_schema_nullable_type_array_flattens(monkeypatch):
-    """Round 14: OpenAI strict tools commonly use
-    `"type": ["string", "null"]` for optional fields. Gemini's
-    OpenAPI-style Schema rejects union types and expects
-    `"type": "string"` with `"nullable": true`. The sanitizer must
+    """Round 14: OpenAI strict tools commonly use `"type": ["string", "null"]`
+    for optional fields. Gemini's OpenAPI-style Schema rejects union types and
+    expects `"type": "string"` with `"nullable": true`. The sanitizer must
     translate the union form."""
     captured = _capture_body(
         monkeypatch,
@@ -2886,12 +2873,11 @@ def test_function_schema_nullable_type_array_flattens(monkeypatch):
 
 
 def test_image_picker_model_with_search_off_pill_strips_text_tools(monkeypatch):
-    """Round 11: image-tier model id rejects text-only tools and
-    thinkingConfig at the model level regardless of whether the Images
-    pill is on. Selecting gemini-2.5-flash-image + enabled_tools=
-    ["web_search"] with no image_generation must NOT forward
-    googleSearch or thinkingConfig (Gemini 400s on text tools for
-    legacy image ids)."""
+    """Round 11: image-tier model ids reject text-only tools and
+    thinkingConfig at the model level regardless of the Images pill. Selecting
+    gemini-2.5-flash-image + enabled_tools=["web_search"] with no
+    image_generation must NOT forward googleSearch or thinkingConfig (Gemini
+    400s on text tools for legacy image ids)."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash-image",
@@ -2904,7 +2890,7 @@ def test_image_picker_model_with_search_off_pill_strips_text_tools(monkeypatch):
 
 
 def test_image_models_drop_function_declarations(monkeypatch):
-    """Image-mode requests cannot mix tools with responseModalities so
+    """Image-mode requests cannot mix tools with responseModalities, so
     user-supplied function declarations must be dropped."""
     captured = _capture_body(
         monkeypatch,
@@ -2923,18 +2909,17 @@ def test_image_models_drop_function_declarations(monkeypatch):
 
 def test_safe_fetch_image_rejects_malformed_bracketed_url():
     """Round 17: bracketed IPv6 garbage like `https://[bad/x.png` makes
-    urlparse raise ValueError. The fetch helper must catch it and drop
-    the image rather than crashing the request mid-build."""
+    urlparse raise ValueError. The fetch helper must catch it and drop the
+    image rather than crashing the request mid-build."""
     res = _drive(ep_mod._safe_fetch_image_for_gemini("https://[bad/x.png", "image/png"))
     assert res is None
 
 
 def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(monkeypatch):
-    """Round 17: the fetch helper must pin the validated IP into the
-    outgoing request URL (with a Host header carrying the original
-    hostname). A second hostname-style getaddrinfo after the validate
-    step would be a DNS-rebinding gap, so we assert the urllib opener
-    is called with an IP-rewritten URL."""
+    """Round 17: the fetch helper must pin the validated IP into the outgoing
+    request URL (with a Host header carrying the original hostname). A second
+    hostname-style getaddrinfo after validate would be a DNS-rebinding gap, so
+    we assert the urllib opener is called with an IP-rewritten URL."""
     import socket
 
     captured: dict = {"requests": []}
@@ -2990,7 +2975,7 @@ def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(monkeypatch):
     res = _drive(ep_mod._safe_fetch_image_for_gemini("https://cdn.example.com/x.png", "image/png"))
     assert res is not None
     assert res[0] == "image/png"
-    # The outgoing URL must use the pinned IP literal, not the hostname.
+    # Outgoing URL must use the pinned IP literal, not the hostname.
     assert any("8.8.8.8" in r["url"] for r in captured["requests"]), captured
     assert all("cdn.example.com" not in r["url"] for r in captured["requests"]), captured
     # Host header still carries the original hostname for vhost/SNI.
@@ -2998,8 +2983,8 @@ def test_safe_fetch_image_pins_validated_ip_no_hostname_in_request(monkeypatch):
 
 
 def test_safe_fetch_image_redirect_to_private_host_rejected(monkeypatch):
-    """Round 17: each redirect hop must re-validate the new host. A
-    public hop that redirects to an internal address must be dropped."""
+    """Round 17: each redirect hop must re-validate the new host. A public hop
+    that redirects to an internal address must be dropped."""
     import socket
     import urllib.error
 
@@ -3052,11 +3037,11 @@ def test_safe_fetch_image_redirect_to_private_host_rejected(monkeypatch):
 
 
 def test_files_api_substring_url_not_misclassified_as_filedata(monkeypatch):
-    """Round 17: a CDN URL whose path/query merely contains the Files
-    API substring must NOT be sent as `fileData.fileUri`; it must be
-    routed through the safe-fetch path. Previously the substring check
-    `"generativelanguage.googleapis.com/" in url.lower()` matched any
-    URL carrying that text anywhere."""
+    """Round 17: a CDN URL whose path/query merely contains the Files API
+    substring must NOT be sent as `fileData.fileUri`; route it through the
+    safe-fetch path. The old substring check
+    `"generativelanguage.googleapis.com/" in url.lower()` matched any URL
+    carrying that text anywhere."""
     captured_outbound: dict = {}
     fetch_calls: list[str] = []
 
@@ -3109,8 +3094,8 @@ def test_files_api_substring_url_not_misclassified_as_filedata(monkeypatch):
                         {
                             "type": "image_url",
                             "image_url": {
-                                # Looks like a Files API URL in the path
-                                # but the host is an attacker CDN.
+                                # Files-API-looking path, but host is an
+                                # attacker CDN.
                                 "url": "https://evil.example/path/generativelanguage.googleapis.com/v1beta/files/abc.png",
                             },
                         },
@@ -3142,10 +3127,10 @@ def test_files_api_substring_url_not_misclassified_as_filedata(monkeypatch):
 
 
 def test_function_schema_anyof_null_variant_flattens_to_nullable(monkeypatch):
-    """Round 17: OpenAI/Pydantic emit `anyOf: [{X}, {"type":"null"}]`
-    for Optional[X]. Gemini's OpenAPI subset rejects `"type":"null"`
-    inside anyOf. The sanitizer must collapse a singleton-plus-null
-    union back to the non-null branch with `nullable: true`."""
+    """Round 17: OpenAI/Pydantic emit `anyOf: [{X}, {"type":"null"}]` for
+    Optional[X]. Gemini's OpenAPI subset rejects `"type":"null"` inside anyOf.
+    The sanitizer must collapse a singleton-plus-null union back to the
+    non-null branch with `nullable: true`."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -3188,10 +3173,10 @@ def test_function_schema_anyof_null_variant_flattens_to_nullable(monkeypatch):
 
 
 def test_legacy_gemini3_pro_medium_coerced_to_high(monkeypatch):
-    """Round 17: legacy `gemini-3-pro*` (including `-preview`, shut down
-    2026-03-09) only accepted low/high. 3.1+ Pro added medium. The
-    backend must coerce medium → high for the legacy model so stale UI
-    state does not 400 the request."""
+    """Round 17: legacy `gemini-3-pro*` (incl. `-preview`, shut down
+    2026-03-09) only accepted low/high. 3.1+ Pro added medium. The backend
+    must coerce medium → high for the legacy model so stale UI state doesn't
+    400 the request."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-3-pro-preview",
@@ -3201,8 +3186,8 @@ def test_legacy_gemini3_pro_medium_coerced_to_high(monkeypatch):
 
 
 def test_gemini_3_1_pro_medium_passes_through(monkeypatch):
-    """Round 17 regression: 3.1+ Pro accepts medium; coercion must NOT
-    apply when the model id is gemini-3.1-pro*."""
+    """Round 17 regression: 3.1+ Pro accepts medium; coercion must NOT apply
+    when the model id is gemini-3.1-pro*."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-3.1-pro-preview",
@@ -3214,8 +3199,8 @@ def test_gemini_3_1_pro_medium_passes_through(monkeypatch):
 def test_tool_calls_extra_content_stripped_for_non_native_gemini():
     """Round 17: per-tool-call `extra_content` (Gemini thoughtSignature
     carrier) must not leak through `_build_external_messages` to
-    non-native-Gemini providers; OpenAI / Anthropic / custom Gemini
-    OAI-compat gateways would 400 on the unknown key."""
+    non-native-Gemini providers; OpenAI / Anthropic / custom Gemini OAI-compat
+    gateways would 400 on the unknown key."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -3241,8 +3226,8 @@ def test_tool_calls_extra_content_stripped_for_non_native_gemini():
     }
     req = ChatCompletionRequest.model_validate(payload)
 
-    # Non-native providers (openai, custom Gemini OAI-compat proxy)
-    # must have extra_content stripped from the tool_call entry.
+    # Non-native providers (openai, custom Gemini OAI-compat proxy) must have
+    # extra_content stripped from the tool_call entry.
     for provider_type, base_url in [
         ("openai", None),
         ("gemini", "https://litellm.example/v1"),
@@ -3269,11 +3254,10 @@ def test_tool_calls_extra_content_stripped_for_non_native_gemini():
 
 
 def test_user_function_named_with_server_tool_arg_not_dropped(monkeypatch):
-    """Round 17: the OpenAI Responses translator must NOT drop a user
-    function whose JSON arguments happen to contain `_server_tool:
-    true` UNLESS the function name is also one of the canonical
-    builtin names. Otherwise a user schema with an `_server_tool` field
-    becomes invisible to the model."""
+    """Round 17: the OpenAI Responses translator must NOT drop a user function
+    whose JSON arguments contain `_server_tool: true` UNLESS the function name
+    is also a canonical builtin name. Otherwise a user schema with an
+    `_server_tool` field becomes invisible to the model."""
     captured: dict = {"input_items": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3331,15 +3315,14 @@ def test_user_function_named_with_server_tool_arg_not_dropped(monkeypatch):
     items = captured["input_items"] or []
     fn_calls = [i for i in items if i.get("type") == "function_call"]
     fn_outs = [i for i in items if i.get("type") == "function_call_output"]
-    # User function call must survive (matching call + output).
+    # User function call must survive (call + output).
     assert any(c.get("name") == "user_function" for c in fn_calls), items
     assert len(fn_outs) == 1, items
 
 
 def test_builtin_named_with_server_tool_marker_dropped(monkeypatch):
-    """Round 17 control: a builtin (web_search) tagged with
-    `_server_tool: true` continues to be filtered from outbound
-    history."""
+    """Round 17 control: a builtin (web_search) tagged with `_server_tool:
+    true` continues to be filtered from outbound history."""
     captured: dict = {"input_items": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3395,10 +3378,10 @@ def test_builtin_named_with_server_tool_marker_dropped(monkeypatch):
 
 
 def test_gemini_tool_choice_none_disables_hosted_builtins(monkeypatch):
-    """Round 18: `tool_choice="none"` must drop hosted Google Search /
-    code execution from the outbound Gemini body, not just user
-    function declarations. Otherwise an API client that opted out of
-    tool use still triggers grounded search (privacy + billing)."""
+    """Round 18: `tool_choice="none"` must drop hosted Google Search / code
+    execution from the Gemini body, not just user function declarations.
+    Otherwise an API client that opted out of tool use still triggers grounded
+    search (privacy + billing)."""
     captured = _capture_body(
         monkeypatch,
         enabled_tools = ["web_search", "code_execution"],
@@ -3408,8 +3391,8 @@ def test_gemini_tool_choice_none_disables_hosted_builtins(monkeypatch):
 
 
 def test_gemini_tool_choice_none_disables_function_declarations(monkeypatch):
-    """Round 18: `tool_choice="none"` must drop user function
-    declarations as well as hosted builtins from the Gemini body."""
+    """Round 18: `tool_choice="none"` must drop user function declarations as
+    well as hosted builtins from the Gemini body."""
     captured = _capture_body(
         monkeypatch,
         tool_choice = "none",
@@ -3424,10 +3407,9 @@ def test_gemini_tool_choice_none_disables_function_declarations(monkeypatch):
 
 
 def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(monkeypatch):
-    """Round 18: multi-branch unions with null (e.g.
-    `Union[str, int, None]`) must keep the slim anyOf without the null
-    branch and add `nullable: true`; Gemini rejects
-    `{"type":"null"}` inside anyOf."""
+    """Round 18: multi-branch unions with null (e.g. `Union[str, int, None]`)
+    must keep the slim anyOf without the null branch and add `nullable: true`;
+    Gemini rejects `{"type":"null"}` inside anyOf."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -3464,9 +3446,9 @@ def test_schema_anyof_multitype_with_null_keeps_anyof_and_nullable(monkeypatch):
 
 
 def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
-    """Round 18: when the upstream 302 Location is a malformed
-    bracketed-IPv6 URL, the helper must return None instead of letting
-    a urlparse ValueError abort the chat stream."""
+    """Round 18: when the upstream 302 Location is a malformed bracketed-IPv6
+    URL, the helper must return None instead of letting a urlparse ValueError
+    abort the chat stream."""
     import socket
     import urllib.error
 
@@ -3508,17 +3490,17 @@ def test_safe_fetch_image_redirect_malformed_url_no_crash(monkeypatch):
 
 
 def test_safe_fetch_image_malformed_port_no_crash():
-    """Round 18: a URL with a non-numeric port (`https://h:bad/x.png`)
-    must not raise; urlparse's port property lazily ValueErrors."""
+    """Round 18: a URL with a non-numeric port (`https://h:bad/x.png`) must
+    not raise; urlparse's port property lazily ValueErrors."""
     res = _drive(ep_mod._safe_fetch_image_for_gemini("https://example.com:bad/x.png", "image/png"))
     assert res is None
 
 
 def test_safe_fetch_image_missing_content_type_uses_fallback(monkeypatch):
-    """Round 18: when the server returns image bytes but no
-    Content-Type header, the helper must use the caller-provided
-    fallback MIME (guessed from URL extension) instead of dropping the
-    image as `non-image content-type=<none>`."""
+    """Round 18: when the server returns image bytes but no Content-Type
+    header, the helper must use the caller-provided fallback MIME (guessed from
+    URL extension) instead of dropping the image as `non-image
+    content-type=<none>`."""
     import socket
 
     original_getaddrinfo = socket.getaddrinfo
@@ -3569,11 +3551,11 @@ def test_safe_fetch_image_missing_content_type_uses_fallback(monkeypatch):
 
 
 def test_anthropic_translates_openai_tool_calls_into_tool_use_blocks(monkeypatch):
-    """Round 18: an assistant turn with OpenAI-style top-level
-    `tool_calls` must be translated into Anthropic native
-    `{type:"tool_use", id, name, input}` content blocks before being
-    forwarded. The OpenAI `role="tool"` follow-up must become a
-    `role:"user"` message with a `tool_result` content block."""
+    """Round 18: an assistant turn with OpenAI-style top-level `tool_calls`
+    must be translated into Anthropic native `{type:"tool_use", id, name,
+    input}` content blocks before forwarding. The OpenAI `role="tool"`
+    follow-up must become a `role:"user"` message with a `tool_result`
+    block."""
     captured: dict = {"messages": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3631,8 +3613,8 @@ def test_anthropic_translates_openai_tool_calls_into_tool_use_blocks(monkeypatch
     msgs = captured["messages"] or []
     # No top-level tool_calls should remain.
     assert all("tool_calls" not in m for m in msgs), msgs
-    # The assistant turn must now have content blocks including a
-    # tool_use block.
+    # The assistant turn must now have content blocks including a tool_use
+    # block.
     asst = [m for m in msgs if m.get("role") == "assistant"]
     assert asst and isinstance(asst[0]["content"], list), asst
     tool_uses = [b for b in asst[0]["content"] if b.get("type") == "tool_use"]
@@ -3651,10 +3633,10 @@ def test_anthropic_translates_openai_tool_calls_into_tool_use_blocks(monkeypatch
 
 
 def test_unmarked_user_web_search_function_survives_serialization():
-    """Round 18: a user-defined function literally named `web_search`
-    with NO `_server_tool` marker must survive `_build_external_messages`
-    when forwarded to a non-native provider; only marked synthetic
-    builtin cards may be dropped."""
+    """Round 18: a user-defined function literally named `web_search` with NO
+    `_server_tool` marker must survive `_build_external_messages` when
+    forwarded to a non-native provider; only marked synthetic builtin cards may
+    be dropped."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -3692,11 +3674,11 @@ def test_unmarked_user_web_search_function_survives_serialization():
 
 
 def test_marked_server_builtin_dropped_from_build_external_messages():
-    """Round 18: when a Gemini-native turn carrying a marked
-    `image_generation` server-tool card is forwarded to OpenAI / a
-    custom Gemini OAI-compat proxy, the tool_call must be dropped, not
-    just have its extra_content stripped. Forwarding an orphan
-    `image_generation` tool_call would 400 the receiving API."""
+    """Round 18: when a Gemini-native turn carrying a marked `image_generation`
+    server-tool card is forwarded to OpenAI / a custom Gemini OAI-compat proxy,
+    the tool_call must be dropped, not just have its extra_content stripped.
+    Forwarding an orphan `image_generation` tool_call would 400 the receiving
+    API."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -3722,8 +3704,8 @@ def test_marked_server_builtin_dropped_from_build_external_messages():
         "stream": True,
     }
     req = ChatCompletionRequest.model_validate(payload)
-    # Non-native providers: marked builtin tool_call must be dropped
-    # AND if it was the only payload, the whole message disappears.
+    # Non-native providers: marked builtin tool_call must be dropped, and if it
+    # was the only payload, the whole message disappears.
     for provider_type, base_url in [
         ("openai", None),
         ("gemini", "https://litellm.example/v1"),
@@ -3752,9 +3734,9 @@ def test_marked_server_builtin_dropped_from_build_external_messages():
 
 
 def test_openai_responses_tool_choice_none_drops_hosted_tools(monkeypatch):
-    """Round 18: `tool_choice="none"` must also drop hosted OpenAI
-    Responses builtins (web_search, code execution shell, image
-    generation), not just user function tools."""
+    """Round 18: `tool_choice="none"` must also drop hosted OpenAI Responses
+    builtins (web_search, code execution shell, image generation), not just
+    user function tools."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3791,9 +3773,9 @@ def test_openai_responses_tool_choice_none_drops_hosted_tools(monkeypatch):
 
 
 def test_anthropic_tool_choice_none_drops_hosted_tools(monkeypatch):
-    """Round 19: tool_choice="none" must opt out of Anthropic hosted
-    builtins (web_search, web_fetch, code_execution) just like it does
-    for Gemini and OpenAI Responses."""
+    """Round 19: tool_choice="none" must opt out of Anthropic hosted builtins
+    (web_search, web_fetch, code_execution) like it does for Gemini and OpenAI
+    Responses."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3830,9 +3812,9 @@ def test_anthropic_tool_choice_none_drops_hosted_tools(monkeypatch):
 
 
 def test_openrouter_tool_choice_none_drops_web_plugin(monkeypatch):
-    """Round 19: tool_choice="none" must drop the OpenRouter web
-    plugin so a request that opted out of tool use does not still
-    trigger hosted web search."""
+    """Round 19: tool_choice="none" must drop the OpenRouter web plugin so a
+    request that opted out of tool use doesn't still trigger hosted web
+    search."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -3869,10 +3851,9 @@ def test_openrouter_tool_choice_none_drops_web_plugin(monkeypatch):
 
 
 def test_kimi_tool_choice_none_skips_web_search_helper(monkeypatch):
-    """Round 19: when tool_choice="none" plus enabled_tools=
-    ["web_search"] on Kimi, the dispatcher must NOT route into
-    `_stream_kimi_web_search`. Falling through to the generic OAI-
-    compat path is the expected behavior."""
+    """Round 19: when tool_choice="none" plus enabled_tools=["web_search"] on
+    Kimi, the dispatcher must NOT route into `_stream_kimi_web_search`. Falling
+    through to the generic OAI-compat path is expected."""
     routed_to_helper = {"called": False}
 
     real_helper = ExternalProviderClient._stream_kimi_web_search
@@ -3926,10 +3907,9 @@ def test_kimi_tool_choice_none_skips_web_search_helper(monkeypatch):
 
 
 def test_user_code_execution_function_not_dropped():
-    """Round 19: a user-declared function literally named
-    `code_execution` with normal `code` arguments must survive
-    `_build_external_messages` -- round 17's shape heuristic dropped
-    it, which broke function-calling round-trips."""
+    """Round 19: a user-declared function literally named `code_execution` with
+    normal `code` arguments must survive `_build_external_messages` -- round
+    17's shape heuristic dropped it, breaking function-calling round-trips."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -3967,10 +3947,10 @@ def test_user_code_execution_function_not_dropped():
 
 
 def test_native_part_code_execution_treated_as_server_side():
-    """Round 19: a Gemini `code_execution` card persists its replay
-    payload at `args.google.native_part` (no `_server_tool` marker on
-    pre-PR cards). The backend filter must still drop it for non-native
-    providers because it is a synthetic card, not a real user function."""
+    """Round 19: a Gemini `code_execution` card persists its replay payload at
+    `args.google.native_part` (no `_server_tool` marker on pre-PR cards). The
+    backend filter must still drop it for non-native providers because it's a
+    synthetic card, not a real user function."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -4017,9 +3997,9 @@ def test_native_part_code_execution_treated_as_server_side():
 
 
 def test_remote_image_fetch_attempt_cap_includes_failures(monkeypatch):
-    """Round 19: the per-request image fetch count cap must count
-    ATTEMPTS, not just successes. Otherwise a request with 100
-    failing/slow URLs runs 100 fetches each up to the 15s timeout."""
+    """Round 19: the per-request image fetch count cap must count ATTEMPTS,
+    not just successes. Otherwise a request with 100 failing/slow URLs runs 100
+    fetches each up to the 15s timeout."""
     fetch_calls: list[str] = []
 
     async def fake_fetch(
@@ -4091,10 +4071,9 @@ def test_remote_image_fetch_attempt_cap_includes_failures(monkeypatch):
 
 
 def test_orphan_function_call_output_dropped_when_call_skipped(monkeypatch):
-    """Round 19: when a marked server-side builtin `function_call` is
-    dropped from OpenAI Responses input items, the matching role=tool
-    follow-up must also be dropped to avoid an orphan
-    `function_call_output`."""
+    """Round 19: when a marked server-side builtin `function_call` is dropped
+    from OpenAI Responses input items, the matching role=tool follow-up must
+    also be dropped to avoid an orphan `function_call_output`."""
     captured: dict = {"input_items": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4157,10 +4136,10 @@ def test_orphan_function_call_output_dropped_when_call_skipped(monkeypatch):
 
 
 def test_schema_multitype_union_with_null_preserves_anyof(monkeypatch):
-    """Round 19: a JSON Schema `"type": ["string","integer","null"]`
-    must be sanitized to anyOf:[{string},{integer}] + nullable:true.
-    Flattening to just `{"type":"string"}` silently drops the integer
-    branch and changes the function contract."""
+    """Round 19: a JSON Schema `"type": ["string","integer","null"]` must be
+    sanitized to anyOf:[{string},{integer}] + nullable:true. Flattening to just
+    `{"type":"string"}` silently drops the integer branch and changes the
+    function contract."""
     captured = _capture_body(
         monkeypatch,
         tools = [
@@ -4193,8 +4172,7 @@ def test_schema_multitype_union_with_null_preserves_anyof(monkeypatch):
 
 def test_invalid_gemini_model_rejected_before_image_fetch(monkeypatch):
     """Round 19: invalid Gemini model IDs are rejected at the top of
-    `_stream_gemini`, BEFORE any user-controlled remote image fetch
-    runs."""
+    `_stream_gemini`, BEFORE any user-controlled remote image fetch runs."""
     fetch_calls: list[str] = []
 
     async def fake_fetch(
@@ -4244,11 +4222,10 @@ def test_invalid_gemini_model_rejected_before_image_fetch(monkeypatch):
 
 
 def test_empty_assistant_turn_skipped_after_synthetic_tool_calls_dropped():
-    """Round 20: when `_filter_tool_calls` drops every synthetic
-    server-builtin tool_call on an empty-content assistant turn, the
-    whole message must be skipped. Forwarding
-    `{"role":"assistant","content":""}` is rejected by several
-    providers as an empty assistant turn."""
+    """Round 20: when `_filter_tool_calls` drops every synthetic server-builtin
+    tool_call on an empty-content assistant turn, the whole message must be
+    skipped. Several providers reject `{"role":"assistant","content":""}` as an
+    empty assistant turn."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -4284,16 +4261,16 @@ def test_empty_assistant_turn_skipped_after_synthetic_tool_calls_dropped():
             provider_type = provider_type,
             base_url = base_url,
         )
-        # The empty assistant turn (only a synthetic builtin) must
-        # NOT appear in the output at all.
+        # The empty assistant turn (only a synthetic builtin) must NOT appear
+        # in the output at all.
         assert result == [], (provider_type, result)
 
 
 def test_role_tool_dropped_when_matching_synthetic_call_filtered():
-    """Round 20: `_build_external_messages` drops the matching role=
-    tool follow-up when its tool_call was a synthetic builtin that
-    `_filter_tool_calls` removed. Otherwise the receiving provider
-    sees an orphan tool_result with no tool_call."""
+    """Round 20: `_build_external_messages` drops the matching role=tool
+    follow-up when its tool_call was a synthetic builtin that
+    `_filter_tool_calls` removed. Otherwise the receiving provider sees an
+    orphan tool_result with no tool_call."""
     from models.inference import ChatCompletionRequest
     from routes.inference import _build_external_messages
 
@@ -4338,10 +4315,9 @@ def test_role_tool_dropped_when_matching_synthetic_call_filtered():
 
 
 def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(monkeypatch):
-    """Round 20: OpenRouter dispatcher must not emit synthetic
-    web_search tool_start / tool_end events when tool_choice="none";
-    otherwise the chat UI shows a search card for a search that
-    never happened."""
+    """Round 20: OpenRouter dispatcher must not emit synthetic web_search
+    tool_start / tool_end events when tool_choice="none"; otherwise the chat UI
+    shows a search card for a search that never happened."""
     captured_events: list[dict] = []
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4377,10 +4353,9 @@ def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(monkeypatc
                 obj = json.loads(payload)
             except Exception:
                 continue
-            # Backend emits synthetic tool events as a top-level
-            # `_toolEvent` on the SSE payload (not nested inside
-            # `delta`). Read both shapes so a future format change
-            # cannot mask this regression.
+            # Backend emits synthetic tool events as a top-level `_toolEvent`
+            # on the SSE payload (not nested inside `delta`). Read both shapes
+            # so a future format change can't mask this regression.
             evt = obj.get("_toolEvent")
             if isinstance(evt, dict):
                 captured_events.append(evt)
@@ -4398,9 +4373,9 @@ def test_openrouter_no_synthetic_web_search_event_on_tool_choice_none(monkeypatc
 
 def test_anthropic_role_tool_list_content_translates_to_tool_result(monkeypatch):
     """Round 20: an OpenAI-shape role=tool message with list content
-    (`content=[{"type":"text","text":"result"}]`) must be translated
-    into Anthropic's native tool_result block, not forwarded as an
-    invalid role=tool message."""
+    (`content=[{"type":"text","text":"result"}]`) must be translated into
+    Anthropic's native tool_result block, not forwarded as an invalid role=tool
+    message."""
     captured: dict = {"messages": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4468,9 +4443,9 @@ def test_anthropic_role_tool_list_content_translates_to_tool_result(monkeypatch)
 
 
 def test_data_url_non_image_mime_dropped(monkeypatch):
-    """Round 20: a `data:text/html;base64,...` image_url must be
-    dropped from the outbound Gemini body, not forwarded as
-    `inlineData.mimeType="text/html"` which Gemini rejects."""
+    """Round 20: a `data:text/html;base64,...` image_url must be dropped from
+    the Gemini body, not forwarded as `inlineData.mimeType="text/html"` which
+    Gemini rejects."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -4493,8 +4468,8 @@ def test_data_url_non_image_mime_dropped(monkeypatch):
 
 
 def test_youtube_filedata_uses_video_mime(monkeypatch):
-    """Round 20: YouTube `fileData.fileUri` must declare a video
-    mimeType, not `image/jpeg` guessed from the URL path."""
+    """Round 20: YouTube `fileData.fileUri` must declare a video mimeType, not
+    `image/jpeg` guessed from the URL path."""
     captured = _capture_body(
         monkeypatch,
         messages = [
@@ -4519,12 +4494,11 @@ def test_youtube_filedata_uses_video_mime(monkeypatch):
 
 
 def test_openai_responses_assistant_text_serialized_before_function_call(monkeypatch):
-    """Round 20: in OpenAI Responses history, the assistant's
-    visible text for a turn that ALSO emitted a function_call must
-    serialize BEFORE the function_call item, matching the prior
-    response.output sequence. Otherwise function_call_output (the
-    role=tool follow-up) appears to follow an unrelated assistant
-    message."""
+    """Round 20: in OpenAI Responses history, the assistant's visible text for
+    a turn that ALSO emitted a function_call must serialize BEFORE the
+    function_call item, matching the prior response.output sequence. Otherwise
+    function_call_output (the role=tool follow-up) appears to follow an
+    unrelated assistant message."""
     captured: dict = {"input_items": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4593,9 +4567,9 @@ def test_openai_responses_assistant_text_serialized_before_function_call(monkeyp
 def test_gemini_tool_choice_none_disables_image_generation(monkeypatch):
     """Round 21: `tool_choice="none"` must also flip the implicit
     image-generation hosted tool off on image-tier models. Otherwise
-    `responseModalities=["TEXT","IMAGE"]` still rides on the outbound
-    body and the provider can generate (and bill for) image output
-    despite the explicit OpenAI tool opt-out."""
+    `responseModalities=["TEXT","IMAGE"]` still rides on the body and the
+    provider can generate (and bill for) image output despite the explicit
+    OpenAI tool opt-out."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash-image",
@@ -4608,11 +4582,11 @@ def test_gemini_tool_choice_none_disables_image_generation(monkeypatch):
 
 def test_gemini_forced_function_tool_choice_drops_hosted_builtins(monkeypatch):
     """Round 21: forced-function `tool_choice` (e.g.
-    `{"type":"function","function":{"name":"lookup"}}`) must suppress
-    hosted Google Search / code execution. Gemini's toolConfig only
-    constrains function declarations, not hosted tools, so leaving
-    `googleSearch`/`codeExecution` in `tools[]` lets them fire despite
-    the caller pinning a specific user function."""
+    `{"type":"function","function":{"name":"lookup"}}`) must suppress hosted
+    Google Search / code execution. Gemini's toolConfig only constrains
+    function declarations, not hosted tools, so leaving
+    `googleSearch`/`codeExecution` in `tools[]` lets them fire despite the
+    caller pinning a specific user function."""
     captured = _capture_body(
         monkeypatch,
         enabled_tools = ["web_search", "code_execution"],
@@ -4636,8 +4610,8 @@ def test_gemini_forced_function_tool_choice_drops_hosted_builtins(monkeypatch):
 
 
 def test_gemini_forced_function_tool_choice_drops_image_generation(monkeypatch):
-    """Round 21: forced-function `tool_choice` must also flip the
-    implicit image-generation hosted tool off on image-tier models."""
+    """Round 21: forced-function `tool_choice` must also flip the implicit
+    image-generation hosted tool off on image-tier models."""
     captured = _capture_body(
         monkeypatch,
         model = "gemini-2.5-flash-image",
@@ -4659,9 +4633,9 @@ def test_gemini_forced_function_tool_choice_drops_image_generation(monkeypatch):
 
 def test_gemini_code_execution_native_part_list_replays_per_part_signatures(monkeypatch):
     """Round 21: merged code-execution history must replay per-part
-    `thoughtSignature`s, not fan one top-level signature across every
-    native subpart. Gemini 3 strict validators reject a signature
-    placed on the wrong part."""
+    `thoughtSignature`s, not fan one top-level signature across every native
+    subpart. Gemini 3 strict validators reject a signature on the wrong
+    part."""
     history = [
         {"role": "user", "content": "plot 1+1"},
         {
@@ -4711,7 +4685,7 @@ def test_gemini_code_execution_native_part_list_replays_per_part_signatures(monk
     ]
     captured = _capture_body(monkeypatch, messages = history)
     contents = captured["body"]["contents"]
-    # Locate the assistant turn replayed as native code-exec parts.
+    # Find the assistant turn replayed as native code-exec parts.
     assistant_turn = next(c for c in contents if c["role"] == "model")
     parts = assistant_turn["parts"]
     exec_parts = [p for p in parts if "executableCode" in p]
@@ -4723,11 +4697,11 @@ def test_gemini_code_execution_native_part_list_replays_per_part_signatures(monk
 
 
 def test_gemini_code_execution_legacy_merged_signature_only_on_executable(monkeypatch):
-    """Round 21: backward compatibility for pre-round-21 persisted
-    history that stored merged `native_part` as a single object plus a
-    top-level `thoughtSignature`. The replay branch must attach that
-    signature only to `executableCode` (where Gemini 3 emits it), not
-    fan it across `codeExecutionResult` / `inlineData`."""
+    """Round 21: backward compat for pre-round-21 persisted history that stored
+    merged `native_part` as a single object plus a top-level
+    `thoughtSignature`. The replay branch must attach that signature only to
+    `executableCode` (where Gemini 3 emits it), not fan it across
+    `codeExecutionResult` / `inlineData`."""
     history = [
         {"role": "user", "content": "plot 1+1"},
         {
@@ -4779,10 +4753,10 @@ def test_gemini_code_execution_legacy_merged_signature_only_on_executable(monkey
 
 
 def test_gemini_role_tool_list_content_flattens_to_result_text(monkeypatch):
-    """Round 21: OpenAI-shape role=tool messages may carry list content
-    like `[{"type":"text","text":"result"}]`. Forwarding those parts
-    verbatim into `functionResponse.response.result` yields a list of
-    content-part objects instead of the actual tool output text."""
+    """Round 21: OpenAI-shape role=tool messages may carry list content like
+    `[{"type":"text","text":"result"}]`. Forwarding those parts verbatim into
+    `functionResponse.response.result` yields a list of content-part objects
+    instead of the actual tool output text."""
     history = [
         {"role": "user", "content": "look up"},
         {
@@ -4825,7 +4799,7 @@ def test_safe_fetch_image_threads_per_request_byte_budget(monkeypatch):
     """Round 21: the aggregate per-request byte cap must be passed into
     `_safe_fetch_image_for_gemini` so an oversize URL is refused via
     Content-Length (short-circuit) rather than fully downloaded then
-    discarded after the fact."""
+    discarded."""
     import socket
 
     captured: dict = {"reads": 0, "content_length_seen": None}
@@ -4889,10 +4863,10 @@ def test_safe_fetch_image_threads_per_request_byte_budget(monkeypatch):
 
 def test_openai_chat_delta_type_includes_tool_calls_and_extra_content():
     """Round 21: the frontend `OpenAIChatDelta` interface must expose
-    `tool_calls` and `extra_content` so TypeScript callers can consume
-    the Gemini-native stream fields without `any` casts. This test is
-    a static-string assertion against the .ts source; mirrors how other
-    frontend wire-contract tests are pinned from the backend suite."""
+    `tool_calls` and `extra_content` so TypeScript callers can consume the
+    Gemini-native stream fields without `any` casts. A static-string assertion
+    against the .ts source; mirrors how other frontend wire-contract tests are
+    pinned from the backend suite."""
     import os
 
     here = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -4905,11 +4879,11 @@ def test_openai_chat_delta_type_includes_tool_calls_and_extra_content():
 
 
 def test_anthropic_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
-    """Round 22: forced-function tool_choice must suppress Anthropic
-    hosted builtins the same way it does for Gemini. Pinning a user
-    function (`tool_choice={"type":"function","function":{"name":...}}`)
-    while also passing `enabled_tools=["web_search","web_fetch",
-    "code_execution"]` should not still fire those server-side."""
+    """Round 22: forced-function tool_choice must suppress Anthropic hosted
+    builtins like it does for Gemini. Pinning a user function
+    (`tool_choice={"type":"function","function":{"name":...}}`) while passing
+    `enabled_tools=["web_search","web_fetch","code_execution"]` should not still
+    fire those server-side."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4945,8 +4919,8 @@ def test_anthropic_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
 
     _drive(run())
     body = captured["body"] or {}
-    # No hosted tools should be in the body — only the caller's user-
-    # function declarations (which this test doesn't pass any of).
+    # No hosted tools in the body — only the caller's user-function
+    # declarations (none passed here).
     tools = body.get("tools") or []
     hosted_tool_names = {"web_search", "web_fetch", "code_execution"}
     for tool in tools:
@@ -4954,9 +4928,9 @@ def test_anthropic_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
 
 
 def test_openrouter_forced_function_tool_choice_drops_web_plugin(monkeypatch):
-    """Round 22: forced-function tool_choice must drop the OpenRouter
-    web plugin too — caller pinned a user function, OpenRouter must not
-    still attach the hosted web-search plugin."""
+    """Round 22: forced-function tool_choice must drop the OpenRouter web
+    plugin too — caller pinned a user function, so OpenRouter must not attach
+    the hosted web-search plugin."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -4996,10 +4970,10 @@ def test_openrouter_forced_function_tool_choice_drops_web_plugin(monkeypatch):
 
 
 def test_kimi_forced_function_tool_choice_skips_web_search_helper(monkeypatch):
-    """Round 22: forced-function tool_choice plus enabled_tools=
-    ["web_search"] on Kimi must NOT route into `_stream_kimi_web_search`.
-    Caller pinned a user function; hosted $web_search should be
-    suppressed for the same privacy/billing reason."""
+    """Round 22: forced-function tool_choice plus enabled_tools=["web_search"]
+    on Kimi must NOT route into `_stream_kimi_web_search`. Caller pinned a user
+    function; hosted $web_search should be suppressed for the same
+    privacy/billing reason."""
     routed_to_helper = {"called": False}
 
     async def fake_helper(self, *args, **kwargs):  # noqa: ARG001
@@ -5048,11 +5022,10 @@ def test_kimi_forced_function_tool_choice_skips_web_search_helper(monkeypatch):
 
 
 def test_openai_responses_forced_function_tool_choice_drops_hosted_tools(monkeypatch):
-    """Round 23: forced-function tool_choice on the OpenAI Responses
-    path must suppress hosted builtins (web_search, shell,
-    image_generation) the same way it does for Gemini / Anthropic /
-    OpenRouter / Kimi. User-defined function tools still flow through
-    so the pinned function can resolve."""
+    """Round 23: forced-function tool_choice on the OpenAI Responses path must
+    suppress hosted builtins (web_search, shell, image_generation) like it does
+    for Gemini / Anthropic / OpenRouter / Kimi. User-defined function tools
+    still flow through so the pinned function can resolve."""
     captured: dict = {"body": None}
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -5101,12 +5074,12 @@ def test_openai_responses_forced_function_tool_choice_drops_hosted_tools(monkeyp
     hosted_types = {"web_search", "shell", "image_generation"}
     hosted_seen = {t.get("type") for t in tools if isinstance(t, dict)}
     assert not (hosted_seen & hosted_types), body
-    # The user function declaration must still be present so the pin
-    # has something to target.
+    # The user function declaration must still be present so the pin has a
+    # target.
     user_function_seen = any(isinstance(t, dict) and t.get("type") == "function" for t in tools)
     assert user_function_seen, body
-    # And the forced-function tool_choice must be forwarded in Responses
-    # shape: `{type:"function", name:"..."}`.
+    # And the forced-function tool_choice must be forwarded in Responses shape:
+    # `{type:"function", name:"..."}`.
     tc = body.get("tool_choice")
     assert isinstance(tc, dict) and tc.get("type") == "function", body
     assert tc.get("name") == "lookup_record", body
@@ -5114,10 +5087,10 @@ def test_openai_responses_forced_function_tool_choice_drops_hosted_tools(monkeyp
 
 def test_strip_provider_synthetic_tool_history_drops_text_only_extra_content():
     """Round 24: a plain text Gemini reply (no tool_calls) carrying
-    `extra_content.google.thought_signature` must still have that
-    metadata stripped before being forwarded to a local llama-server
-    backend. Without this, switching a Gemini thread mid-stream to a
-    local GGUF model leaks Gemini-only fields to llama-server."""
+    `extra_content.google.thought_signature` must still have that metadata
+    stripped before being forwarded to a local llama-server backend. Without
+    it, switching a Gemini thread mid-stream to a local GGUF model leaks
+    Gemini-only fields to llama-server."""
     from routes.inference import _strip_provider_synthetic_tool_history
 
     messages = [
@@ -5139,10 +5112,10 @@ def test_strip_provider_synthetic_tool_history_drops_text_only_extra_content():
 
 def test_validate_and_resolve_host_blocks_shared_address_space():
     """Round 24 SSRF P1: 100.64.0.0/10 carrier-grade NAT addresses are
-    `is_private=False` AND `is_global=False` per Python's ipaddress
-    docs. The previous denylist (is_private/loopback/link_local/etc.)
-    missed them. Adding `not ip.is_global` as the primary gate covers
-    all non-public ranges, current and future."""
+    `is_private=False` AND `is_global=False` per Python's ipaddress docs. The
+    old denylist (is_private/loopback/link_local/etc.) missed them. Adding `not
+    ip.is_global` as the primary gate covers all non-public ranges, current and
+    future."""
     import socket as _socket
     from core.inference import tools as _tools
 
@@ -5171,13 +5144,12 @@ def test_validate_and_resolve_host_blocks_shared_address_space():
 
 
 def test_gemini_custom_oai_compat_base_skips_native_allowlist():
-    """Round 24: a custom Gemini OAI-compatible base (LiteLLM/proxy)
-    must NOT have its model list filtered through the native Gemini
-    allowlist regex. A LiteLLM gateway returning
-    `["google/gemini-2.5-flash", "my-team/gemini", "gemini-2.5-flash"]`
-    should be passed through; the native filter would strip the
-    prefixed IDs even though the chat dispatch routes them via the
-    OpenAI-compatible client."""
+    """Round 24: a custom Gemini OAI-compatible base (LiteLLM/proxy) must NOT
+    have its model list filtered through the native Gemini allowlist regex. A
+    LiteLLM gateway returning
+    `["google/gemini-2.5-flash", "my-team/gemini", "gemini-2.5-flash"]` should
+    pass through; the native filter would strip the prefixed IDs even though
+    chat dispatch routes them via the OpenAI-compatible client."""
     import asyncio as _asyncio
 
     from routes import providers as _providers
@@ -5213,18 +5185,18 @@ def test_gemini_custom_oai_compat_base_skips_native_allowlist():
     finally:
         _providers.ExternalProviderClient = orig
     ids = {m.id for m in result}
-    # All three IDs survive — the native allowlist was bypassed.
+    # All three IDs survive — native allowlist bypassed.
     assert "google/gemini-2.5-flash" in ids, ids
     assert "my-team/gemini" in ids, ids
     assert "gemini-2.5-flash" in ids, ids
 
 
 def test_strip_provider_synthetic_tool_history_drops_synthetic_only():
-    """Round 22: switching a thread from native Gemini (code_execution
-    / image_generation tool_cards in history) to a local GGUF backend
-    must strip the synthetic tool_calls + matching role=tool replies
-    before llama-server sees them. Real user-function tool_calls and
-    their matching tool replies must survive."""
+    """Round 22: switching a thread from native Gemini (code_execution /
+    image_generation tool_cards in history) to a local GGUF backend must strip
+    the synthetic tool_calls + matching role=tool replies before llama-server
+    sees them. Real user-function tool_calls and their matching tool replies
+    must survive."""
     from routes.inference import _strip_provider_synthetic_tool_history
 
     messages = [
@@ -5282,9 +5254,9 @@ def test_strip_provider_synthetic_tool_history_drops_synthetic_only():
 
 
 def test_strip_provider_synthetic_tool_history_drops_empty_assistant():
-    """If every tool_call was synthetic and the assistant turn had no
-    content, the entire turn must be dropped (llama-server rejects
-    empty assistant messages with no tool_calls)."""
+    """If every tool_call was synthetic and the assistant turn had no content,
+    the entire turn must be dropped (llama-server rejects empty assistant
+    messages with no tool_calls)."""
     from routes.inference import _strip_provider_synthetic_tool_history
 
     messages = [
@@ -5323,18 +5295,17 @@ def test_strip_provider_synthetic_tool_history_drops_empty_assistant():
     ]
     out = _strip_provider_synthetic_tool_history(messages)
     roles = [m.get("role") for m in out]
-    # The synthetic assistant + its tool reply are both gone; only the
-    # two user turns survive.
+    # Synthetic assistant + its tool reply are both gone; only the two user
+    # turns survive.
     assert roles == ["user", "user"], out
 
 
 def test_openrouter_no_synthetic_web_search_event_on_forced_function_tool_choice(monkeypatch):
-    """Round 22 sibling of the round-20 `tool_choice='none'` test: when
-    the caller forces a specific function via `tool_choice={"type":
-    "function", ...}` AND passes `enabled_tools=["web_search"]`, the
-    OpenRouter path must NOT synthesize a fake `web_search` tool card.
-    The plugin was not attached upstream so the UI must not see a
-    server-tool card."""
+    """Round 22 sibling of the round-20 `tool_choice='none'` test: when the
+    caller forces a specific function via `tool_choice={"type":"function", ...}`
+    AND passes `enabled_tools=["web_search"]`, the OpenRouter path must NOT
+    synthesize a fake `web_search` tool card. The plugin wasn't attached
+    upstream, so the UI must not see a server-tool card."""
     captured_events: list[dict] = []
 
     def handler(request: httpx.Request) -> httpx.Response:
diff --git a/studio/backend/tests/test_gguf_metadata.py b/studio/backend/tests/test_gguf_metadata.py
index 08f22edb18..d3d4387720 100644
--- a/studio/backend/tests/test_gguf_metadata.py
+++ b/studio/backend/tests/test_gguf_metadata.py
@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Tests for :mod:`utils.models.gguf_metadata`. Synthesise small GGUF
-headers in tmp dirs so we never depend on real model files."""
+"""Tests for :mod:`utils.models.gguf_metadata`. Synthesise small GGUF headers
+in tmp dirs so we never depend on real model files."""
 
 from __future__ import annotations
 
@@ -140,7 +140,7 @@ def test_metadata_is_cached(tmp_path: Path):
     )
     first = read_gguf_general_metadata(str(p))
     assert first == {"general.basename": "First"}
-    # Force size change so the (path, mtime, size) key invalidates.
+    # Change size so the (path, mtime, size) cache key invalidates.
     _write_synthetic_gguf(
         tmp_path / "model.gguf",
         {"general.basename": "Second", "general.organization": "X"},
diff --git a/studio/backend/tests/test_gguf_reload_inheritance.py b/studio/backend/tests/test_gguf_reload_inheritance.py
index 1a663725d9..500bfc2d4c 100644
--- a/studio/backend/tests/test_gguf_reload_inheritance.py
+++ b/studio/backend/tests/test_gguf_reload_inheritance.py
@@ -3,11 +3,10 @@
 
 """Backend contract for the GGUF reload duplicate-load guard.
 
-``LlamaCppBackend._already_in_target_state`` is the in-process
-short-circuit that prevents a serialised duplicate /load from killing
-the just-spawned llama-server. These tests pin the local-file
-identity, the HF-mode hf_variant fallback, and the ``extra_args``
-None-vs-[] inherit semantics so the guard cannot silently regress.
+``LlamaCppBackend._already_in_target_state`` is the in-process short-circuit
+preventing a serialised duplicate /load from killing the just-spawned
+llama-server. Pins local-file identity, the HF-mode hf_variant fallback, and
+``extra_args`` None-vs-[] inherit semantics so the guard cannot regress.
 """
 
 from __future__ import annotations
diff --git a/studio/backend/tests/test_gguf_routing.py b/studio/backend/tests/test_gguf_routing.py
index 1b299cba19..c640218943 100644
--- a/studio/backend/tests/test_gguf_routing.py
+++ b/studio/backend/tests/test_gguf_routing.py
@@ -4,10 +4,9 @@
 """
 Tests for GGUF routing in detect_gguf_model.
 
-Regression test for the bug where a .gguf file temporarily appears
-inaccessible on Windows during llama-server process teardown, causing
-is_file() to return False and the model to be routed to the transformers
-backend instead of llama-server.
+Regression test: on Windows a .gguf file can briefly appear inaccessible
+during llama-server teardown, making is_file() return False and routing
+the model to the transformers backend instead of llama-server.
 """
 
 import sys
@@ -16,7 +15,7 @@ import types
 from pathlib import Path
 from unittest.mock import patch
 
-# Stub structlog before importing backend modules (mirrors other tests in this suite)
+# Stub structlog before importing backend modules (as in other suite tests)
 if "structlog" not in sys.modules:
 
     class _DummyLogger:
@@ -44,10 +43,10 @@ def test_detects_gguf_file_normally(tmp_path):
 
 def test_detects_gguf_when_stat_raises_oserror(tmp_path):
     """
-    Regression: on Windows, both is_file() and exists() call stat() internally.
-    During the brief lock window after llama-server is killed, stat() raises
-    OSError, causing both to return False. detect_gguf_model must still route
-    to llama-server based on the file extension alone.
+    Regression: on Windows both is_file() and exists() call stat() internally.
+    In the brief lock window after llama-server is killed, stat() raises
+    OSError so both return False. detect_gguf_model must still route to
+    llama-server based on the file extension alone.
     """
     gguf = tmp_path / "gpt-oss-20b-MXFP4.gguf"
     gguf.write_bytes(b"")
diff --git a/studio/backend/tests/test_gpu_selection.py b/studio/backend/tests/test_gpu_selection.py
index 90020efe43..cb26330ed0 100644
--- a/studio/backend/tests/test_gpu_selection.py
+++ b/studio/backend/tests/test_gpu_selection.py
@@ -181,7 +181,7 @@ class TestVisibleGpuUtilization(_GpuCacheResetMixin, unittest.TestCase):
         self.assertAlmostEqual(result["devices"][1]["memory_total_gb"], 29.3, places = 1)
 
     def test_uuid_parent_visibility_falls_back_to_torch(self):
-        """UUID/MIG masks should fall through nvidia to torch fallback and
+        """UUID/MIG masks fall through nvidia to the torch fallback and
         still report visible devices using relative ordinals."""
         fake_torch_devices = [
             {
@@ -1338,7 +1338,7 @@ class TestEstimateFp16ModelSizeBytesPrefersLocalWeights(unittest.TestCase):
         self.assertEqual(src, "weight_bytes")
 
     def test_equal_local_and_config_keeps_config_label(self):
-        # why: tie-breaker is "local must be strictly larger" so an exact
+        # Tie-breaker is "local must be strictly larger", so an exact
         # match keeps the config-derived path.
         same = 8 * (1 << 30)
         bytes_, src = self._run(
diff --git a/studio/backend/tests/test_gpu_selection_sandbox.py b/studio/backend/tests/test_gpu_selection_sandbox.py
index 073f8d9437..733933271b 100644
--- a/studio/backend/tests/test_gpu_selection_sandbox.py
+++ b/studio/backend/tests/test_gpu_selection_sandbox.py
@@ -2,9 +2,9 @@
 """
 Sandbox test for multi-GPU selection logic.
 
-Tests the core GPU selection, memory estimation, and device_map logic
-in an isolated environment. Can be run on Linux, macOS, and Windows
-without requiring actual GPUs -- all hardware calls are mocked.
+Tests GPU selection, memory estimation, and device_map logic in
+isolation. Runs on Linux, macOS, and Windows without real GPUs -- all
+hardware calls are mocked.
 
 Usage:
     python -m pytest studio/backend/tests/test_gpu_selection_sandbox.py -v
@@ -18,7 +18,7 @@ import unittest
 from pathlib import Path
 from unittest.mock import patch, MagicMock
 
-# Ensure backend is on sys.path
+# Ensure backend is on sys.path.
 _backend_root = Path(__file__).resolve().parent.parent
 if str(_backend_root) not in sys.path:
     sys.path.insert(0, str(_backend_root))
@@ -33,7 +33,7 @@ def _make_fake_config(
     num_key_value_heads = 8,
     tie_word_embeddings = False,
 ):
-    """Create a fake HF config-like object for estimation tests."""
+    """Fake HF config-like object for estimation tests."""
     from types import SimpleNamespace
     return SimpleNamespace(
         vocab_size = vocab_size,
@@ -47,7 +47,7 @@ def _make_fake_config(
 
 
 class TestEstimateFP16ModelSizeFromConfig(unittest.TestCase):
-    """Test the config-based model size estimation."""
+    """Config-based model size estimation."""
 
     def test_llama_8b_size_reasonable(self):
         from utils.hardware.hardware import _estimate_fp16_model_size_bytes_from_config
@@ -90,7 +90,7 @@ class TestEstimateFP16ModelSizeFromConfig(unittest.TestCase):
         from utils.hardware.hardware import _estimate_fp16_model_size_bytes_from_config
         from types import SimpleNamespace
 
-        config = SimpleNamespace(vocab_size = 32000)  # Missing most fields
+        config = SimpleNamespace(vocab_size = 32000)  # most fields missing
         size = _estimate_fp16_model_size_bytes_from_config(config)
         self.assertIsNone(size)
 
@@ -117,7 +117,7 @@ class TestEstimateFP16ModelSizeFromConfig(unittest.TestCase):
 
 
 class TestEstimateRequiredModelMemory(unittest.TestCase):
-    """Test memory requirement estimation."""
+    """Memory requirement estimation."""
 
     def test_inference_fp16_uses_1_3x(self):
         from utils.hardware.hardware import estimate_required_model_memory_gb
@@ -189,10 +189,10 @@ class TestEstimateRequiredModelMemory(unittest.TestCase):
 
 
 class TestAutoSelectGpuIds(unittest.TestCase):
-    """Test automatic GPU selection based on model size and free memory."""
+    """Automatic GPU selection by model size and free memory."""
 
     def _make_utilization(self, devices):
-        """Create a fake utilization response."""
+        """Fake utilization response."""
         return {
             "available": True,
             "devices": [
@@ -304,7 +304,7 @@ class TestAutoSelectGpuIds(unittest.TestCase):
 
 
 class TestGetDeviceMap(unittest.TestCase):
-    """Test device_map string generation."""
+    """device_map string generation."""
 
     def test_single_gpu_returns_sequential(self):
         from utils.hardware.hardware import get_device_map
@@ -341,7 +341,7 @@ class TestGetDeviceMap(unittest.TestCase):
 
 
 class TestResolveRequestedGpuIds(unittest.TestCase):
-    """Test GPU ID validation."""
+    """GPU ID validation."""
 
     def test_none_returns_parent_visible(self):
         from utils.hardware.hardware import resolve_requested_gpu_ids
@@ -390,7 +390,7 @@ class TestResolveRequestedGpuIds(unittest.TestCase):
 
 
 class TestApplyGpuIds(unittest.TestCase):
-    """Test CUDA_VISIBLE_DEVICES environment variable setting."""
+    """CUDA_VISIBLE_DEVICES environment variable setting."""
 
     def test_apply_list(self):
         from utils.hardware.hardware import apply_gpu_ids
@@ -407,10 +407,10 @@ class TestApplyGpuIds(unittest.TestCase):
 
 
 class TestMultiGpuOverheadAccounting(unittest.TestCase):
-    """Test that multi-GPU overhead is applied correctly.
+    """Multi-GPU overhead is applied correctly.
 
-    The first GPU should keep its full free memory, and only
-    additional GPUs should have the overhead factor applied.
+    The first GPU keeps its full free memory; the overhead factor applies
+    only to additional GPUs.
     """
 
     def _make_utilization(self, devices):
diff --git a/studio/backend/tests/test_host_defaults.py b/studio/backend/tests/test_host_defaults.py
index 02bb54df56..c66385721e 100644
--- a/studio/backend/tests/test_host_defaults.py
+++ b/studio/backend/tests/test_host_defaults.py
@@ -35,10 +35,10 @@ def _parse_function_param_defaults(source: str, func_name: str) -> dict:
 
 
 def _parse_argparse_add_argument_default(source: str, option_name: str):
-    """Return the 'default' kwarg value for add_argument(option_name, ...) in *source*.
+    """Return the 'default' kwarg for add_argument(option_name, ...) in *source*.
 
-    Walks the entire module so the call can live in __main__ or in a helper
-    function — only handles ast.Constant defaults.
+    Walks the whole module so the call may live in __main__ or a helper;
+    only handles ast.Constant defaults.
     """
     tree = ast.parse(source)
     for node in ast.walk(tree):
@@ -59,12 +59,12 @@ def _parse_argparse_add_argument_default(source: str, option_name: str):
 
 
 def test_run_server_default_host_is_loopback():
-    """run_server() parameter default for 'host' must be 127.0.0.1, not 0.0.0.0.
+    """run_server() 'host' default must be 127.0.0.1, not 0.0.0.0.
 
-    Binding to 0.0.0.0 by default exposes the service on all network
-    interfaces, contradicting the documented "privacy first / 100% local"
-    guarantee.  Loopback (127.0.0.1) is the least-permissive default;
-    users who need network access can pass -H 0.0.0.0 explicitly.
+    Binding to 0.0.0.0 by default exposes the service on all interfaces,
+    contradicting the "privacy first / 100% local" guarantee. Loopback
+    (127.0.0.1) is the least-permissive default; users who need network
+    access can pass -H 0.0.0.0 explicitly.
     """
     source = _RUN_PY.read_text()
     defaults = _parse_function_param_defaults(source, "run_server")
@@ -81,7 +81,7 @@ def test_argparse_default_host_is_loopback():
     """argparse --host add_argument default must be 127.0.0.1.
 
     When run.py is invoked directly (python run.py), the argparse default
-    should match the function default so direct execution is equally safe.
+    must match the function default so direct execution is equally safe.
     """
     source = _RUN_PY.read_text()
     host_default = _parse_argparse_add_argument_default(source, "--host")
diff --git a/studio/backend/tests/test_index_bootstrap_origin.py b/studio/backend/tests/test_index_bootstrap_origin.py
index b36e3fcedd..85b785ee10 100644
--- a/studio/backend/tests/test_index_bootstrap_origin.py
+++ b/studio/backend/tests/test_index_bootstrap_origin.py
@@ -61,8 +61,8 @@ def test_is_same_origin_request_port_mismatch_is_cross_origin():
 
 
 def test_is_same_origin_request_https_default_port_stripped_on_origin():
-    """RFC 6454 strips default ports on Origin; Starlette's netloc may still
-    carry ``:443``. Canonicalise both sides so this stays same-origin.
+    """RFC 6454 strips default ports on Origin; Starlette netloc may keep
+    ``:443``. Canonicalise both sides so this stays same-origin.
     """
     from main import _is_same_origin_request
 
@@ -109,7 +109,7 @@ def test_is_same_origin_request_null_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_unparseable_origin_is_cross_origin():
-    """Garbage values without a host fall to cross-origin; a malformed header
+    """Hostless garbage falls to cross-origin; a malformed header
     must not leak the bootstrap.
     """
     from main import _is_same_origin_request
@@ -120,8 +120,7 @@ def test_is_same_origin_request_unparseable_origin_is_cross_origin():
 
 def test_is_same_origin_request_userinfo_in_netloc_ignored():
     """``user:pass@host:port`` netlocs (RFC 3986) must compare equal to the
-    credentials-less Origin.
-    """
+    credentials-less Origin."""
     from main import _is_same_origin_request
 
     req = _build_request("user:pass@example.com:80", origin = "http://example.com")
diff --git a/studio/backend/tests/test_index_bootstrap_origin_extra.py b/studio/backend/tests/test_index_bootstrap_origin_extra.py
index 71fdbad930..feda88c14c 100644
--- a/studio/backend/tests/test_index_bootstrap_origin_extra.py
+++ b/studio/backend/tests/test_index_bootstrap_origin_extra.py
@@ -2,9 +2,9 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """Extra edge-case coverage for the bootstrap-pw cross-origin gate.
-Companion to ``test_index_bootstrap_origin.py``: IPv6 netlocs, opaque
-origins (``data:``, ``blob:``), comma-joined multi-Origin headers, and
-the ``localhost`` vs ``127.0.0.1`` distinct-origin rule.
+Companion to ``test_index_bootstrap_origin.py``: IPv6 netlocs, opaque origins
+(``data:``, ``blob:``), comma-joined multi-Origin headers, and the
+``localhost`` vs ``127.0.0.1`` distinct-origin rule.
 """
 
 from unittest.mock import MagicMock
@@ -28,7 +28,7 @@ def _build_request(
 def test_is_same_origin_request_ipv6_loopback_same_origin():
     """Studio supports ``-H ::1`` binds; netloc is ``[::1]:8902``. Bare
     ``partition(":")`` mis-parses the bracketed form and would refuse the
-    bootstrap on legitimate same-origin nav.
+    bootstrap on legitimate same-origin navigation.
     """
     from main import _is_same_origin_request
 
@@ -88,9 +88,7 @@ def test_is_same_origin_request_ipv6_userinfo_stripped():
 
 
 def test_is_same_origin_request_data_url_origin_is_cross_origin():
-    """``data:`` URLs are opaque origins (HTML living standard); no host,
-    never same-origin.
-    """
+    """``data:`` URLs are opaque origins (HTML living standard); no host, never same-origin."""
     from main import _is_same_origin_request
 
     req = _build_request("127.0.0.1:8902", origin = "data:text/html,<script>alert(1)</script>")
@@ -98,9 +96,7 @@ def test_is_same_origin_request_data_url_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_blob_url_origin_is_cross_origin():
-    """``blob:`` URLs carry the inner origin only in non-canonical form; the
-    canonical comparison rejects them.
-    """
+    """``blob:`` URLs carry the inner origin only in non-canonical form; the canonical comparison rejects them."""
     from main import _is_same_origin_request
 
     req = _build_request("127.0.0.1:8902", origin = "blob:http://127.0.0.1:8902/uuid")
@@ -108,8 +104,8 @@ def test_is_same_origin_request_blob_url_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_file_url_origin_is_cross_origin():
-    """``file://`` pages usually send ``Origin: null``; historical engines
-    sent ``Origin: file://``. Neither is same-origin vs an http listener.
+    """``file://`` pages usually send ``Origin: null``; older engines sent
+    ``Origin: file://``. Neither is same-origin vs an http listener.
     """
     from main import _is_same_origin_request
 
@@ -121,8 +117,8 @@ def test_is_same_origin_request_file_url_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_comma_joined_origins_cross_origin():
-    """Starlette concatenates repeated headers with ``, ``; the canonical
-    parser can't safely split this, so it falls to cross-origin.
+    """Starlette joins repeated headers with ``, ``; the canonical parser can't
+    safely split this, so it falls to cross-origin.
     """
     from main import _is_same_origin_request
 
@@ -137,8 +133,8 @@ def test_is_same_origin_request_comma_joined_origins_cross_origin():
 
 
 def test_is_same_origin_request_localhost_vs_127_is_cross_origin():
-    """Browsers treat ``localhost`` and ``127.0.0.1`` as distinct origins;
-    the canonical comparison must not DNS-collapse them.
+    """Browsers treat ``localhost`` and ``127.0.0.1`` as distinct origins; the
+    canonical comparison must not DNS-collapse them.
     """
     from main import _is_same_origin_request
 
@@ -157,7 +153,7 @@ def test_is_same_origin_request_127_vs_localhost_is_cross_origin():
 
 def test_is_same_origin_request_malformed_ipv6_bracket_is_cross_origin():
     """``urlparse`` raises ``ValueError('Invalid IPv6 URL')`` on unclosed
-    brackets (CVE-2024-11168 hardening). The gate must swallow and fall to
+    brackets (CVE-2024-11168 hardening). The gate must swallow it and fall to
     cross-origin rather than 500 the SPA handler.
     """
     from main import _is_same_origin_request
@@ -184,8 +180,8 @@ def test_is_same_origin_request_bracket_with_trailing_garbage_is_cross_origin():
 
 
 def test_is_same_origin_request_empty_origin_header_is_cross_origin():
-    """Explicit empty ``Origin:`` is not a valid serialised origin and must
-    not be conflated with a missing header; cross-origin, bootstrap withheld.
+    """Explicit empty ``Origin:`` is not a valid serialised origin and must not
+    be conflated with a missing header; cross-origin, bootstrap withheld.
     """
     from main import _is_same_origin_request
 
diff --git a/studio/backend/tests/test_inference_model_validation.py b/studio/backend/tests/test_inference_model_validation.py
index faf5a67873..dddf5c8052 100644
--- a/studio/backend/tests/test_inference_model_validation.py
+++ b/studio/backend/tests/test_inference_model_validation.py
@@ -170,16 +170,15 @@ def test_walkback_does_not_cross_user_turn():
         ]
     )
     last = req.messages[-1].tool_call_id
-    # The walkback must NOT pick old_call because a user turn intervenes;
-    # falls back to synth.
+    # Walkback must NOT pick old_call across a user turn; falls back to synth.
     assert last is not None
     assert last != "old_call"
     assert last.startswith("call_")
 
 
 def test_walkback_skips_explicitly_consumed_tool_call_id():
-    """Sibling tool result with an explicit id must reserve its assistant
-    slot so a follow-up missing-id result picks the OTHER tool call."""
+    """An explicit-id tool result reserves its assistant slot so a
+    follow-up missing-id result picks the OTHER tool call."""
     req = _req(
         [
             {
diff --git a/studio/backend/tests/test_kv_cache_estimation.py b/studio/backend/tests/test_kv_cache_estimation.py
index 001b5f1bee..cd679b0bf1 100644
--- a/studio/backend/tests/test_kv_cache_estimation.py
+++ b/studio/backend/tests/test_kv_cache_estimation.py
@@ -7,8 +7,7 @@ Covers the GGUF metadata parser, _can_estimate_kv gate, all 5 estimation
 paths (MLA, Hybrid Mamba, Sliding Window, Standard GQA, Legacy), KV cache
 quantization, edge cases, and lifecycle (init/unload/reparse).
 
-Requires no GPU, network, or external libraries beyond pytest.
-Cross-platform: Linux, macOS, Windows, WSL.
+No GPU, network, or libraries beyond pytest. Cross-platform.
 """
 
 import io
@@ -21,8 +20,8 @@ from pathlib import Path
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test.  Same pattern as test_native_context_length.py.
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_native_context_length.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -38,11 +37,10 @@ sys.modules.setdefault("loggers", _loggers_stub)
 _structlog_stub = _types.ModuleType("structlog")
 sys.modules.setdefault("structlog", _structlog_stub)
 
-# httpx -- only stub when the real library isn't installed.  Stubbing
-# unconditionally would shadow ``HTTPError`` / ``Response`` etc. that
-# ``huggingface_hub.errors`` imports at module load time, which causes
-# the transformers introspection tier to silently return None inside
-# the test process.
+# httpx -- only stub when the real library isn't installed. Stubbing
+# unconditionally shadows ``HTTPError`` / ``Response`` etc. that
+# ``huggingface_hub.errors`` imports at load time, making the transformers
+# introspection tier silently return None in the test process.
 try:
     import httpx as _httpx_real  # noqa: F401
 except ImportError:
@@ -84,9 +82,9 @@ from core.inference.llama_cpp import LlamaCppBackend
 
 
 def _make_gguf_bytes(arch: str, kv_pairs: dict) -> bytes:
-    """Build a minimal GGUF v3 binary blob with the given KV metadata.
+    """Build a minimal GGUF v3 blob with the given KV metadata.
 
-    Supports the scalar and simple array metadata used by the parser.
+    Supports the scalar and simple array metadata the parser uses.
     """
     buf = io.BytesIO()
     # Header: magic, version, tensor_count, kv_count
@@ -134,9 +132,8 @@ def _backend_from_gguf(
 ) -> LlamaCppBackend:
     """Create a LlamaCppBackend with parsed GGUF metadata from given fields.
 
-    `general` lets a test inject extra `general.*` metadata (used to
-    verify the dynamic SWA resolver picks up source-repo hints from
-    GGUFs that ship them).
+    `general` injects extra `general.*` metadata, to verify the dynamic
+    SWA resolver picks up source-repo hints from GGUFs that ship them.
     """
     kv = {"general.architecture": arch}
     for k, v in (general or {}).items():
@@ -163,7 +160,7 @@ def _backend_from_gguf(
 
 
 class TestGGUFParserNewFields:
-    """Verify that architecture-aware fields are correctly parsed."""
+    """Architecture-aware fields are parsed correctly."""
 
     @pytest.mark.parametrize(
         "field,gguf_key,value",
@@ -217,9 +214,9 @@ class TestGGUFParserNewFields:
         )
         # Per-layer KV head count is preserved exactly...
         assert b._n_kv_heads_by_layer == [8, 8, 8, 8, 8, 2]
-        # ...and mirrored into the scalar field as a conservative max so
-        # non-SWA estimator paths and any caller using
-        # `n_kv = self._n_kv_heads or ...` get a safe upper bound.
+        # ...and mirrored into the scalar field as a conservative max, so
+        # non-SWA paths and callers using `n_kv = self._n_kv_heads or ...`
+        # get a safe upper bound.
         assert b._n_kv_heads == 8
         assert b._sliding_window_pattern == [True, True, True, True, True, False]
 
@@ -270,7 +267,7 @@ class TestArchSwaPatternDefaults:
         assert b._sliding_window_pattern is None
 
     def test_explicit_pattern_overrides_arch_default(self):
-        # Period=6 is the gemma3 default; the explicit array must win.
+        # gemma3 default is period=6; the explicit array must win.
         b = _backend_from_gguf(
             "gemma3",
             {
@@ -310,8 +307,8 @@ class TestArchSwaPatternDefaults:
         "arch", ["llama", "qwen2", "qwen3", "mistral", "mistral3", "glm4", "llama4"]
     )
     def test_non_swa_arch_uses_full_attention_path(self, arch):
-        # Pure-GQA arches: GGUF has no sliding_window, no synthetic
-        # pattern, estimator hits Path 4.
+        # Pure-GQA arches: no sliding_window, no synthetic pattern,
+        # estimator hits Path 4.
         b = _backend_from_gguf(
             arch,
             {
@@ -340,7 +337,7 @@ class TestArchSwaPatternDefaults:
             "embedding_length": 5376,
         }
         with_default = _backend_from_gguf("gemma3", common)
-        # Arch not in the table -> legacy 1/4 path.
+        # Arch not in table -> legacy 1/4 path.
         without_default = _backend_from_gguf("totallymadeupv7", common)
 
         kv_default = with_default._estimate_kv_cache_bytes(131072, "f16")
@@ -430,7 +427,7 @@ class TestDynamicSwaResolver:
     def test_period_from_layer_types_finds_smallest_period(self):
         from core.inference.llama_cpp import _period_from_layer_types
 
-        # gemma3 (1 global per 6), gpt-oss (alternating), gemma3n (1 per 5).
+        # gemma3 (1 global/6), gpt-oss (alternating), gemma3n (1/5).
         assert _period_from_layer_types((["sliding_attention"] * 5 + ["full_attention"]) * 4) == 6
         assert _period_from_layer_types(["sliding_attention", "full_attention"] * 12) == 2
         assert _period_from_layer_types((["sliding_attention"] * 4 + ["full_attention"]) * 7) == 5
@@ -481,14 +478,14 @@ class TestDynamicSwaResolver:
 
     def test_disk_cache_takes_precedence_over_bootstrap(self, monkeypatch, tmp_path):
         self._isolate_cache(monkeypatch, tmp_path)
-        # Override bootstrap=6 with a cached period=3.
+        # Cached period=3 overrides bootstrap=6.
         with open(tmp_path / "swa_cache.json", "w") as f:
             json.dump({"gemma3": 3}, f)
         b = _backend_from_gguf("gemma3", dict(_SWA_FIELDS, block_count = 18))
         assert b._sliding_window_pattern == [(i + 1) % 3 != 0 for i in range(18)]
 
     def test_disk_cache_supports_array_entries(self, monkeypatch, tmp_path):
-        # Aperiodic mask gets tiled across n_layers.
+        # Aperiodic mask is tiled across n_layers.
         self._isolate_cache(monkeypatch, tmp_path)
         mask = [True, False, True, True, False, True, False, False]
         with open(tmp_path / "swa_cache.json", "w") as f:
@@ -556,7 +553,7 @@ class TestDynamicSwaResolver:
         from core.inference import llama_cpp as lc
 
         monkeypatch.setattr(lc, "_fetch_swa_entry_from_hf", lambda repo_id: None)
-        # Force the failure into the Tier 3 path; bypass Tier 2.5.
+        # Force failure into Tier 3; bypass Tier 2.5.
         monkeypatch.setattr(lc, "_resolve_swa_entry_from_transformers", lambda arch: None)
         b = _backend_from_gguf(
             "newmodel",
@@ -639,7 +636,7 @@ class TestTransformersIntrospection:
         assert _resolve_swa_entry_from_transformers("totally-fake-arch-xyz") is None
 
     def test_full_resolver_uses_transformers_before_hf_fetch(self, monkeypatch, tmp_path):
-        # With bootstrap empty, Tier 2.5 must answer before Tier 3 fires.
+        # Bootstrap empty: Tier 2.5 must answer before Tier 3 fires.
         self._isolate_cache(monkeypatch, tmp_path)
         from core.inference import llama_cpp as lc
 
@@ -660,10 +657,10 @@ class TestTransformersIntrospection:
 
 
 class TestGGUFParserReset:
-    """Verify that fields are properly reset between parses."""
+    """Fields are reset between parses."""
 
     def test_reset_between_parses(self):
-        # First parse with all fields
+        # First parse: all fields set
         b = _backend_from_gguf(
             "arch1",
             {
@@ -685,7 +682,7 @@ class TestGGUFParserReset:
         assert b._kv_value_length_swa == 64
         assert b._ssm_inner_size == 4096
 
-        # Second parse without those fields -- they should be None
+        # Second parse without those fields -- they must be None
         kv = {"general.architecture": "arch2", "arch2.block_count": 64}
         import tempfile, os
 
@@ -713,7 +710,7 @@ class TestGGUFParserReset:
 
 
 class TestCanEstimateKV:
-    """Verify gate logic for all field combinations."""
+    """Gate logic for all field combinations."""
 
     def test_no_layers_returns_false(self):
         b = LlamaCppBackend()
@@ -729,7 +726,7 @@ class TestCanEstimateKV:
         assert b._can_estimate_kv()
 
     def test_key_length_alone_insufficient(self):
-        """key_length without value_length should NOT be enough."""
+        """key_length without value_length is NOT enough."""
         b = LlamaCppBackend()
         b._n_layers = 32
         b._kv_key_length = 128
@@ -799,33 +796,33 @@ class TestMLAEstimation:
         assert b._estimate_kv_cache_bytes(163840, "f16") == expected
 
     def test_mla_ignores_value_length(self):
-        """MLA should NOT add value_length -- V is reconstructed from the latent."""
+        """MLA must NOT add value_length -- V is reconstructed from the latent."""
         b = self._mla_backend()
         result = b._estimate_kv_cache_bytes(1000, "f16")
-        # Should be n_layers * ctx * 1 * key_len(576) * 2
+        # n_layers * ctx * 1 * key_len(576) * 2
         expected = 61 * 1000 * 1 * 576 * 2
         assert result == expected
 
     def test_mla_fallback_when_no_key_length(self):
-        """If key_length is missing, fallback to kv_lora_rank + key_length_mla."""
+        """No key_length: fall back to kv_lora_rank + key_length_mla."""
         b = self._mla_backend(_kv_key_length = None)
-        # _key_length_mla=192 in default, so rope_dim=192
+        # default _key_length_mla=192, so rope_dim=192
         result = b._estimate_kv_cache_bytes(1000, "f16")
         expected = 61 * 1000 * 1 * (512 + 192) * 2  # 704
         assert result == expected
 
     def test_mla_fallback_no_key_length_mla(self):
-        """If both key_length and key_length_mla are missing, fallback to +64."""
+        """No key_length and no key_length_mla: fall back to +64."""
         b = self._mla_backend(_kv_key_length = None, _key_length_mla = None)
         result = b._estimate_kv_cache_bytes(1000, "f16")
         expected = 61 * 1000 * 1 * (512 + 64) * 2  # 576
         assert result == expected
 
     def test_mla_defaults_n_kv_to_1_when_heads_absent(self):
-        """MLA should use n_kv=1 even if n_kv_heads is None (not n_heads)."""
+        """MLA uses n_kv=1 even if n_kv_heads is None (not n_heads)."""
         b = self._mla_backend(_n_kv_heads = None)  # n_heads=128 still set
         result = b._estimate_kv_cache_bytes(1000, "f16")
-        # Should use n_kv_mla=1, NOT n_heads=128
+        # Uses n_kv_mla=1, NOT n_heads=128
         expected = 61 * 1000 * 1 * 576 * 2
         assert result == expected
 
@@ -883,14 +880,14 @@ class TestHybridMambaEstimation:
         assert b._estimate_kv_cache_bytes(262144, "f16") == expected
 
     def test_hybrid_without_explicit_dims(self):
-        """Fallback to head_dim when key_length/value_length are missing."""
+        """Fall back to head_dim when key_length/value_length are missing."""
         b = self._hybrid_backend(_kv_key_length = None, _kv_value_length = None)
         head_dim = 5120 // 24  # 213
         expected = 16 * 4096 * 4 * 2 * head_dim * 2
         assert b._estimate_kv_cache_bytes(4096, "f16") == expected
 
     def test_fai_zero_safety(self):
-        """full_attention_interval=0 should not cause ZeroDivisionError."""
+        """full_attention_interval=0 must not ZeroDivisionError."""
         b = self._hybrid_backend(_full_attention_interval = 0)
         result = b._estimate_kv_cache_bytes(4096, "f16")
         # fai=0 -> n_attn = n_layers (all layers)
@@ -978,7 +975,7 @@ class TestSlidingWindowEstimation:
             assert b._estimate_kv_cache_bytes(ctx, "f16") == expected(ctx)
 
     def test_ctx_smaller_than_window(self):
-        """When context < 2 * sliding_window, SWA cache caps at ctx."""
+        """When ctx < 2 * sliding_window, SWA cache caps at ctx."""
         b = self._swa_backend(_sliding_window = 8192)
         n_global = max(1, 62 // 4)  # 15
         n_swa = 62 - n_global  # 47
@@ -1031,11 +1028,11 @@ class TestStandardGQAEstimation:
         assert b._estimate_kv_cache_bytes(4096, "f16") == expected
 
     def test_differs_from_legacy(self):
-        """GQA path should differ from legacy when key_length != embed//n_heads."""
+        """GQA path differs from legacy when key_length != embed//n_heads."""
         b = self._gqa_backend()
         head_dim = 1024 // 16  # 64
         gqa_result = b._estimate_kv_cache_bytes(4096, "f16")
-        # Legacy would use: 2 * 8 * 64 * 28 * 4096 * 2
+        # Legacy: 2 * 8 * 64 * 28 * 4096 * 2
         legacy_result = int(2 * 8 * head_dim * 28 * 4096 * 2)
         # GQA: 28 * 4096 * 8 * (128+128) * 2 -- uses actual key_length=128
         assert gqa_result != legacy_result
@@ -1077,7 +1074,7 @@ class TestLegacyEstimation:
         assert b._estimate_kv_cache_bytes(4096, "f16") == expected
 
     def test_legacy_identical_to_old_formula(self):
-        """Confirm legacy path produces the same result as the pre-PR formula."""
+        """Legacy path matches the pre-PR formula."""
         b = self._legacy_backend()
         n_layers = 32
         n_kv_heads = 8
@@ -1097,7 +1094,7 @@ class TestPathPriority:
     """Confirm: MLA > Hybrid Mamba > SWA > GQA > Legacy."""
 
     def test_mla_takes_priority_over_all(self):
-        """If kv_lora_rank is set, MLA path is used even if other fields are present."""
+        """If kv_lora_rank is set, MLA path wins even with other fields present."""
         b = LlamaCppBackend()
         b._n_layers = 61
         b._n_kv_heads = 1
@@ -1132,9 +1129,9 @@ class TestPathPriority:
         assert b._estimate_kv_cache_bytes(1000, "f16") == expected_hybrid
 
     def test_all_paths_produce_different_values(self):
-        """With carefully chosen params, each path should yield a distinct value."""
-        # Use embedding_length=768 so legacy head_dim (768//16=48) differs from
-        # key_length (256), and MLA key_len (256) != legacy K+V (2*48=96).
+        """With chosen params, each path yields a distinct value."""
+        # embedding_length=768 so legacy head_dim (768//16=48) != key_length
+        # (256), and MLA key_len (256) != legacy K+V (2*48=96).
         params = {
             "_n_layers": 40,
             "_n_kv_heads": 4,
@@ -1191,7 +1188,7 @@ class TestPathPriority:
 
 
 class TestQuantization:
-    """Verify all supported cache_type_kv values produce correct scaling."""
+    """All supported cache_type_kv values scale correctly."""
 
     @pytest.mark.parametrize(
         "cache_type,expected_bpe",
@@ -1332,7 +1329,7 @@ class TestServerFlags:
         b = self._swa_backend()
         ctx = 32_768
         flagged = b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True)
-        # With swa_full, every layer caches n_ctx -- equals path 4 sizing.
+        # swa_full: every layer caches n_ctx -- equals path 4 sizing.
         kv_per_token = 4 * (256 + 256) * 2  # n_kv_heads * (k+v) * f16
         expected = 26 * ctx * kv_per_token
         assert flagged == expected
@@ -1366,10 +1363,9 @@ class TestServerFlags:
         assert with_cp > b._estimate_kv_cache_bytes(8192, "f16")
 
     # ── --parallel + --kv-unified ──────────────────────────────────
-    # Empirically verified against llama-server: non-SWA caches partition
-    # n_ctx across slots (total memory constant); SWA layers are the only
-    # portion that scales with --parallel.  --kv-unified is currently a
-    # no-op for memory math (kept for API forward-compat).
+    # Verified against llama-server: non-SWA caches partition n_ctx across
+    # slots (total memory constant); only SWA layers scale with --parallel.
+    # --kv-unified is a no-op for memory math (kept for API forward-compat).
 
     def test_gqa_kv_constant_across_parallel(self):
         b = self._gqa_backend()
@@ -1394,7 +1390,7 @@ class TestServerFlags:
         b = self._swa_backend()
         ctx = 8192
         baseline = b._estimate_kv_cache_bytes(ctx, "f16")
-        # Decompose baseline by walking the same loop the estimator does.
+        # Decompose baseline by walking the estimator's own loop.
         swa = b._sliding_window
         per_token_global = 4 * (256 + 256) * 2  # n_kv * (k+v) * f16
         per_token_swa = 4 * (256 + 256) * 2  # k_swa/val_swa fall back
@@ -1409,10 +1405,10 @@ class TestServerFlags:
         )
         # Sanity: parallel=1 reproduces baseline exactly
         assert global_bytes + swa_bytes_per_slot == baseline
-        # Only SWA portion scales by parallel
+        # Only the SWA portion scales by parallel
         for slots in (1, 2, 3, 4):
             scaled = b._estimate_kv_cache_bytes(ctx, "f16", n_parallel = slots, kv_unified = False)
-            # SWA cells get clamped to per_slot_ctx when ctx/slots < 2*swa
+            # SWA cells clamp to per_slot_ctx when ctx/slots < 2*swa
             per_slot_ctx = max(1, ctx // slots)
             cells = min(ctx, 2 * swa, per_slot_ctx)
             swa_bps = sum(
@@ -1452,7 +1448,7 @@ class TestServerFlags:
         ctx = 8192
         baseline = b._estimate_kv_cache_bytes(ctx, "f16")
         flagged = b._estimate_kv_cache_bytes(ctx, "f16", ctx_checkpoints = 4)
-        # 22 SWA layers * 4 checkpoints * 512 cells * 4 heads * (256+256) * 2 bytes
+        # 22 SWA layers * 4 cps * 512 cells * 4 heads * (256+256) * 2 bytes
         n_swa_layers = sum(1 for f in [True, True, True, True, True, False] * 4 + [True, True] if f)
         per_layer = 4 * 512 * 4 * (256 + 256) * 2
         assert flagged == baseline + n_swa_layers * per_layer
@@ -1470,7 +1466,7 @@ class TestServerFlags:
 
     def test_ctx_checkpoints_compose_with_n_parallel(self):
         # Only the SWA + checkpoint portion scales by n_parallel; the
-        # global-layer portion stays constant.
+        # global-layer portion is constant.
         b = self._swa_backend()
         ctx = 8192
         swa = b._sliding_window
@@ -1493,7 +1489,7 @@ class TestServerFlags:
 
     def test_fit_returns_requested_when_kv_off_gpu(self):
         b = self._gqa_backend()
-        # Tiny VRAM budget -- normally would force a reduction.
+        # Tiny VRAM budget -- would normally force a reduction.
         fitted = b._fit_context_to_vram(
             requested_ctx = 32_768,
             available_mib = 1,
@@ -1515,8 +1511,8 @@ class TestServerFlags:
         assert fitted < 32_768
 
     def test_fit_mtp_engaged_returns_smaller_or_equal_context(self):
-        # MTP-engaged budget is 0.85 of available; non-MTP is 0.90.
-        # On a tight budget the MTP path must yield <= the non-MTP path.
+        # MTP budget is 0.85 of available, non-MTP is 0.90; on a tight
+        # budget MTP must yield <= non-MTP.
         b = self._gqa_backend()
         common = dict(
             requested_ctx = 32_768,
@@ -1529,7 +1525,7 @@ class TestServerFlags:
         assert mtp <= baseline
 
     def test_fit_mtp_engaged_unchanged_when_kv_off_gpu(self):
-        # kv_on_gpu=False short-circuits the fit; mtp_engaged is irrelevant.
+        # kv_on_gpu=False short-circuits the fit; mtp_engaged irrelevant.
         b = self._gqa_backend()
         fitted = b._fit_context_to_vram(
             requested_ctx = 32_768,
@@ -1548,7 +1544,7 @@ class TestServerFlags:
         kv_default = b._estimate_kv_cache_bytes(ctx, "f16")
         kv_full = b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True)
         assert kv_full > kv_default
-        # Budget = model + kv_default (rounded up) -- swa_full should not fit.
+        # Budget = model + kv_default (rounded up) -- swa_full must not fit.
         budget_mib = (1024 * 1024 + kv_default) / (1024 * 1024) / 0.90 + 1
         fitted_default = b._fit_context_to_vram(
             requested_ctx = ctx,
@@ -1573,16 +1569,16 @@ class TestServerFlags:
 
 
 class TestParallelSWAScaling:
-    """Verifies the per-layer-type scaling rule against the closed form
-    measured from llama-server. Empirical formula on Gemma-3 270m at
-    ctx=8192: total_kv = 24 + parallel * 15 (MiB).
+    """Per-layer-type scaling rule vs the closed form measured from
+    llama-server. Empirical formula on Gemma-3 270m at ctx=8192:
+    total_kv = 24 + parallel * 15 (MiB).
 
     Rule (verified vs ``llama-server`` log on real GGUFs):
       * non-SWA layers: total cells = n_ctx, partitioned across slots,
         memory CONSTANT in n_parallel.
       * SWA layers: per-slot cells = 2 * sliding_window (clamped at
         n_ctx and at per_slot_ctx); memory LINEAR in n_parallel.
-      * --kv-unified is a no-op for memory math; both modes yield the
+      * --kv-unified is a no-op for memory math; both modes give the
         same total in measured cases.
     """
 
@@ -1703,7 +1699,7 @@ class TestParallelSWAScaling:
 
     def test_swa_per_slot_clamped_when_ctx_lt_slots_x_2window(self):
         # ctx=4096 / slots=8 -> per_slot_ctx=512, but 2*sliding=1024.
-        # SWA cells should clamp at per_slot_ctx (512), not 2*sliding.
+        # SWA cells clamp at per_slot_ctx (512), not 2*sliding.
         b = self._swa_backend()
         ctx = 4096
         per_slot_ctx_at_8 = ctx // 8
@@ -1719,8 +1715,8 @@ class TestParallelSWAScaling:
         assert b._estimate_kv_cache_bytes(ctx, "f16", n_parallel = 8) == expected
 
     def test_swa_full_does_not_scale_under_parallel(self):
-        # swa_full forces every layer to n_ctx; result is the all-global
-        # GQA-style total, which is constant in parallel.
+        # swa_full forces every layer to n_ctx -> all-global GQA-style
+        # total, constant in parallel.
         b = self._swa_backend()
         ctx = 8192
         baseline = b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True)
@@ -1732,8 +1728,8 @@ class TestParallelSWAScaling:
     # ── kv_unified: no-op for memory math ──────────────────────────
 
     def test_kv_unified_is_no_op_for_memory_math(self):
-        # Both unified=True and unified=False must produce the same
-        # total bytes for every backend type and every parallel value.
+        # unified=True and unified=False must give the same total bytes
+        # for every backend type and parallel value.
         backends = [
             ("gqa", self._gqa_backend()),
             ("swa", self._swa_backend()),
@@ -1761,9 +1757,8 @@ class TestParallelSWAScaling:
         b._kv_key_length = 256
         b._kv_value_length = 256
         b._sliding_window = 512
-        # 5-period [swa,swa,swa,swa,full] * 3 + [swa,swa,swa]: mirrors the
-        # bootstrap-resolved pattern for gemma3 (period 6) on an 18-layer
-        # model (15 SWA, 3 global).
+        # Mirrors the bootstrap-resolved gemma3 pattern (period 6) on an
+        # 18-layer model: 15 SWA, 3 global.
         b._sliding_window_pattern = [(i + 1) % 6 != 0 for i in range(18)]
         n_global = 3
         n_swa = 15
@@ -1784,13 +1779,13 @@ class TestParallelSWAScaling:
 
 class TestSharedKVLayers:
     """``<arch>.attention.shared_kv_layers`` reduces the layer count that
-    actually allocates KV.  The trailing ``shared_kv_layers`` blocks reuse
-    earlier caches (Gemma 3n: 35 layers, 15 shared -> 20 allocate; Gemma 4
-    same field).  Unset on every other arch -> no behavioural change."""
+    allocates KV. The trailing ``shared_kv_layers`` blocks reuse earlier
+    caches (Gemma 3n: 35 layers, 15 shared -> 20 allocate; Gemma 4 same
+    field). Unset on every other arch -> no behavioural change."""
 
     def _gemma3n_backend(self, **overrides):
-        # Mirrors google/gemma-3n-E4B-it: 35 layers, 15 shared,
-        # SWA window 1024, period 5 (4 sliding + 1 full repeating).
+        # Mirrors google/gemma-3n-E4B-it: 35 layers, 15 shared, SWA window
+        # 1024, period 5 (4 sliding + 1 full repeating).
         defaults = {
             "_n_layers": 35,
             "_n_kv_heads": 4,
@@ -1873,9 +1868,8 @@ class TestSharedKVLayers:
     def test_path3_pattern_loops_only_unshared_layers(self):
         b = self._gemma3n_backend()
         ctx = 8192
-        # First 20 layers contribute; layers 20..34 are skipped.
-        # Pattern: [s,s,s,s,F] repeated.  In layers 0..19:
-        #   sliding: 16, full: 4
+        # First 20 layers contribute; layers 20..34 skipped. Pattern
+        # [s,s,s,s,F] repeated -> in layers 0..19: sliding 16, full 4.
         sliding_in_unshared = sum(b._sliding_window_pattern[:20])
         full_in_unshared = 20 - sliding_in_unshared
         assert sliding_in_unshared == 16
@@ -1890,7 +1884,7 @@ class TestSharedKVLayers:
         with_shared = b._estimate_kv_cache_bytes(8192, "f16")
         b._shared_kv_layers = 0
         without_shared = b._estimate_kv_cache_bytes(8192, "f16")
-        # 20/35 = 0.571 of the work; expect ~43% reduction.
+        # 20/35 = 0.571 of the work; ~43% reduction.
         ratio = with_shared / without_shared
         assert 0.5 < ratio < 0.65
 
@@ -1898,8 +1892,8 @@ class TestSharedKVLayers:
         b = self._gemma3n_backend()
         ctx = 8192
         flagged = b._estimate_kv_cache_bytes(ctx, "f16", swa_full = True)
-        # Every unshared layer caches n_ctx; equals path-4-style sizing
-        # over only the 20 unshared layers.
+        # Every unshared layer caches n_ctx -> path-4-style sizing over
+        # only the 20 unshared layers.
         kv_per = 4 * (256 + 256) * 2
         assert flagged == 20 * ctx * kv_per
 
@@ -1917,15 +1911,15 @@ class TestSharedKVLayers:
         assert b._estimate_kv_cache_bytes(ctx, "f16") == expected
 
     def test_shared_floors_at_one_layer(self):
-        # Pathological: shared >= n_layers should not zero out the cache.
+        # Pathological: shared >= n_layers must not zero out the cache.
         b = self._gqa_backend(_shared_kv_layers = 99)
         ctx = 4096
         kv_per = 8 * (128 + 128) * 2
         assert b._estimate_kv_cache_bytes(ctx, "f16") == 1 * ctx * kv_per
 
     def test_composes_with_n_parallel(self):
-        # Only the SWA portion of the unshared layers scales by n_parallel;
-        # the global portion stays constant.
+        # Only the SWA portion of unshared layers scales by n_parallel;
+        # the global portion is constant.
         b = self._gemma3n_backend()
         ctx = 8192
         swa = b._sliding_window
@@ -1946,7 +1940,7 @@ class TestSharedKVLayers:
         ctx = 8192
         baseline = b._estimate_kv_cache_bytes(ctx, "f16")
         with_cp = b._estimate_kv_cache_bytes(ctx, "f16", ctx_checkpoints = 4)
-        # Checkpoints only count over UNSHARED SWA layers (16 of them).
+        # Checkpoints count only over UNSHARED SWA layers (16 of them).
         sliding_in_unshared = sum(b._sliding_window_pattern[:20])
         per_cp_layer = 4 * 1024 * 4 * (256 + 256) * 2  # cps * swa * heads * (k+v) * bpe
         assert with_cp == baseline + sliding_in_unshared * per_cp_layer
@@ -2017,7 +2011,7 @@ class TestLifecycle:
         assert b._n_kv_heads_by_layer is None
 
     def test_end_to_end_synthetic_mla(self):
-        """Full round-trip: write GGUF -> parse -> estimate."""
+        """Round-trip: write GGUF -> parse -> estimate."""
         b = _backend_from_gguf(
             "deepseek2",
             {
@@ -2075,8 +2069,8 @@ class TestLifecycle:
         )
         assert b._can_estimate_kv()
         result = b._estimate_kv_cache_bytes(131072, "f16")
-        # gemma3 -> period 6 from the bootstrap table, SWA cache
-        # double-buffered to 2 * sliding_window cells.
+        # gemma3 -> period 6 from bootstrap; SWA cache double-buffered to
+        # 2 * sliding_window cells.
         period = 6
         kv_per = 16 * 256 * 2
         expected = 0
@@ -2104,13 +2098,13 @@ class TestLifecycle:
         )
         assert b._can_estimate_kv()
         assert b._shared_kv_layers == 15
-        # Bootstrap table for gemma3n_text -> period 5; the resolver
-        # synthesises a 35-entry bool array.  The first 20 entries
-        # (n_layers - shared) are the only ones that allocate KV.
+        # Bootstrap for gemma3n_text -> period 5; resolver synthesises a
+        # 35-entry bool array. Only the first 20 (n_layers - shared)
+        # allocate KV.
         result = b._estimate_kv_cache_bytes(8192, "f16")
         assert result > 0
-        # Sanity: setting shared back to 0 must produce a strictly larger
-        # estimate (more layers allocate).
+        # Sanity: shared back to 0 -> strictly larger estimate (more
+        # layers allocate).
         b._shared_kv_layers = 0
         unshared = b._estimate_kv_cache_bytes(8192, "f16")
         assert unshared > result
diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
index f887f7747c..8fca27dfe1 100644
--- a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -1,11 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Validates that the installer correctly resolves lemonade ROCm prebuilt assets.
+"""Validates that the installer resolves lemonade ROCm prebuilt assets.
 
-Uses a faked HostInfo so no AMD GPU is needed. Network calls to the lemonade
-GitHub API are stubbed out so the suite runs without internet access and is
-not subject to rate limits.
+Uses a faked HostInfo so no AMD GPU is needed. The lemonade GitHub API calls
+are stubbed so the suite runs offline and isn't subject to rate limits.
 """
 
 from __future__ import annotations
@@ -33,7 +32,7 @@ if resolve_lemonade_rocm_choice is None or _LEMONADE_GFX_FAMILIES is None:
 @pytest.fixture(autouse = True)
 def _clear_lemonade_release_cache():
     """Prevent cross-test pollution of the lemonade release lru_cache when
-    future tests vary the fetch_json mock return value."""
+    tests vary the fetch_json mock return value."""
     _cache = getattr(_mod, "_fetch_lemonade_release_cached", None)
     if _cache is not None and hasattr(_cache, "cache_clear"):
         _cache.cache_clear()
@@ -157,10 +156,9 @@ direct_upstream_release_plan = getattr(_mod, "direct_upstream_release_plan", Non
 
 
 def _stub_unsloth_release(release_tag: str = "b9022") -> dict:
-    # Minimal payload that parse_direct_linux_release_bundle accepts. It
-    # requires at least one `app-{label}-linux-x64*.tar.gz` asset for the
-    # bundle to be recognised; we ship a bare CPU one so the planner has a
-    # baseline non-ROCm attempt to fall through to.
+    # Minimal payload parse_direct_linux_release_bundle accepts. It needs at
+    # least one `app-{label}-linux-x64*.tar.gz` asset to recognise the bundle;
+    # we ship a bare CPU one so the planner has a baseline non-ROCm fallback.
     asset_name = f"app-{release_tag}-linux-x64.tar.gz"
     return {
         "tag_name": release_tag,
@@ -255,9 +253,8 @@ def test_lemonade_release_api_url_pinned_tag():
 
 
 def test_lemonade_release_api_url_encodes_tag():
-    """Unexpected slashes / hashes in the tag must be URL-encoded so the URL
-    cannot be reshaped (defence in depth -- tags should already be sanitised
-    upstream)."""
+    """Slashes / hashes in the tag must be URL-encoded so the URL can't be
+    reshaped (defence in depth -- tags should already be sanitised upstream)."""
     url = _mod._lemonade_release_api_for("b1260/../latest")
     assert "/releases/tags/b1260%2F..%2Flatest" in url
     assert "//latest" not in url.split("/releases/tags/", 1)[1]
@@ -272,9 +269,9 @@ def test_lemonade_resolver_skipped_by_opt_out_env(monkeypatch):
 
 
 def test_lemonade_resolver_rejects_non_github_url(monkeypatch):
-    """If the GitHub API response somehow contained an off-host download URL,
-    the resolver must refuse to use it (lemonade assets are not in the
-    approved-hash manifest)."""
+    """If the GitHub API response contained an off-host download URL, the
+    resolver must refuse it (lemonade assets aren't in the approved-hash
+    manifest)."""
     bad_release = {
         "tag_name": _STUB_TAG,
         "assets": [
@@ -298,7 +295,7 @@ def test_lemonade_resolver_rejects_http_scheme():
 
 
 def test_lemonade_resolver_accepts_github_cdn():
-    # Real GitHub release CDN URLs carry the /github-production-release-asset- prefix.
+    # Real GitHub release CDN URLs carry the /github-production-release-asset- prefix
     assert _mod._is_trusted_github_release_url(
         "https://objects.githubusercontent.com/github-production-release-asset-abc123/456/789?token=x",
         "lemonade-sdk/llamacpp-rocm",
@@ -306,7 +303,7 @@ def test_lemonade_resolver_accepts_github_cdn():
 
 
 def test_lemonade_resolver_rejects_arbitrary_cdn_path():
-    # A CDN URL without the release-asset path prefix must be rejected.
+    # A CDN URL without the release-asset path prefix must be rejected
     assert not _mod._is_trusted_github_release_url(
         "https://objects.githubusercontent.com/abc/def",
         "lemonade-sdk/llamacpp-rocm",
@@ -348,7 +345,7 @@ def test_lemonade_runtime_patterns_include_hip_runtime():
 
     Lemonade ZIPs carry transitive deps (libamd_comgr, libLLVM, libclang-cpp,
     ...) whose names change across ROCm releases. A broad ``lib*.so*`` glob
-    avoids having to enumerate every transitive dependency by name.
+    avoids enumerating every transitive dependency by name.
     """
     from install_llama_prebuilt import runtime_patterns_for_choice, AssetChoice
 
@@ -362,7 +359,7 @@ def test_lemonade_runtime_patterns_include_hip_runtime():
     )
     pats = runtime_patterns_for_choice(choice)
     # The broad glob must be present so every .so in the lemonade bundle
-    # (including transitive deps added in future ROCm releases) gets overlaid.
+    # (including future transitive deps) gets overlaid.
     assert "lib*.so*" in pats, f"'lib*.so*' missing from linux-rocm patterns: {pats}"
 
 
@@ -374,9 +371,9 @@ _pick_rocm_gfx_target = getattr(_mod, "_pick_rocm_gfx_target", None)
     reason = "_pick_rocm_gfx_target not present on this branch",
 )
 def test_pick_rocm_gfx_target_honors_cuda_visible_devices(monkeypatch):
-    """AMD HIP honours CUDA_VISIBLE_DEVICES identically to HIP_VISIBLE_DEVICES;
-    on a gfx1151 + gfx1100 mixed host, CUDA_VISIBLE_DEVICES=1 must select gfx1100."""
-    # Two GPUs; rocminfo reports each token twice (as in the real tool output).
+    """AMD HIP honours CUDA_VISIBLE_DEVICES like HIP_VISIBLE_DEVICES; on a
+    gfx1151 + gfx1100 mixed host, CUDA_VISIBLE_DEVICES=1 must select gfx1100."""
+    # Two GPUs; rocminfo reports each token twice (as in real tool output).
     probe_out = "gfx1151\ngfx1151\ngfx1100\ngfx1100"
     monkeypatch.delenv("HIP_VISIBLE_DEVICES", raising = False)
     monkeypatch.delenv("ROCR_VISIBLE_DEVICES", raising = False)
@@ -405,7 +402,7 @@ def test_pick_rocm_gfx_target_same_arch_multi_gpu(monkeypatch):
     """Regression: [gfx1100, gfx1100, gfx1151] with HIP_VISIBLE_DEVICES=2 must
     return gfx1151, not fall back to GPU 0 due to dict.fromkeys collapsing the
     two gfx1100 entries into one and making index 2 out of range."""
-    # Simulate rocminfo output for 3 GPUs (2x gfx1100 dGPU + 1x gfx1151 APU).
+    # rocminfo output for 3 GPUs (2x gfx1100 dGPU + 1x gfx1151 APU).
     # Each GPU gets its own Agent section with a few token mentions.
     probe_out = (
         "***\nAgent 1\n***\n  gfx1100 some info\n  gfx1100\n"
diff --git a/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py b/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
index 255c04a956..215936bd20 100644
--- a/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
+++ b/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
@@ -5,17 +5,14 @@
 ``LlamaCppBackend.load_model``.
 
 The preflight used to compare the repo's total GGUF download size against
-free disk without accounting for bytes already present in the Hugging
-Face cache. That made re-loading a cached large model (e.g.
-``unsloth/MiniMax-M2.7-GGUF`` at 131 GB) fail cold whenever free disk was
-below the full weight footprint, even though nothing needed
-downloading.
+free disk without accounting for bytes already in the Hugging Face cache.
+That made re-loading a cached large model (e.g. ``unsloth/MiniMax-M2.7-GGUF``
+at 131 GB) fail cold whenever free disk was below the full weight footprint,
+even though nothing needed downloading.
 
 These tests exercise the preflight arithmetic in isolation by driving
 ``get_paths_info`` and ``try_to_load_from_cache`` through ``mock.patch``.
-No network, GPU, or subprocess use.
-
-Cross-platform: Linux, macOS, Windows, WSL.
+No network, GPU, or subprocess use. Cross-platform: Linux, macOS, Windows, WSL.
 """
 
 from __future__ import annotations
@@ -29,8 +26,8 @@ from unittest.mock import patch
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test.  Same pattern as test_kv_cache_estimation.py.
+# Stub heavy / unavailable external deps before importing the module under
+# test. Same pattern as test_kv_cache_estimation.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -99,11 +96,11 @@ def _preflight(
     hf_repo = "unsloth/Example-GGUF",
     hf_token = None,
 ):
-    """Run the preflight arithmetic as written in llama_cpp.py and return
-    the decision outcome as a dict.
+    """Run the preflight arithmetic as in llama_cpp.py; return the decision
+    outcome as a dict.
 
     ``repo_files``: list of (filename, remote_bytes).
-    ``cached_files``: dict {filename: on_disk_bytes} for files already in cache.
+    ``cached_files``: dict {filename: on_disk_bytes} for files already cached.
     ``free_bytes``: value returned by shutil.disk_usage(cache_dir).free.
     """
     import os
@@ -112,22 +109,21 @@ def _preflight(
     path_infos = [_FakePathInfo(name, size) for name, size in repo_files]
 
     with tempfile.TemporaryDirectory() as tmp:
-        # Create SPARSE files for the cached ones so os.path.exists /
-        # os.path.getsize pass without actually allocating bytes on disk.
-        # This is critical when simulating multi-GB models.
+        # SPARSE files for the cached ones so os.path.exists / os.path.getsize
+        # pass without allocating bytes on disk -- critical for multi-GB models.
         cache_paths = {}
         for name, sz in cached_files.items():
             p = Path(tmp) / name.replace("/", "_")
             with open(p, "wb") as fh:
                 if sz > 0:
-                    fh.truncate(sz)  # sparse allocation: no data blocks written
+                    fh.truncate(sz)  # sparse: no data blocks written
             cache_paths[name] = str(p)
 
         def fake_try_to_load_from_cache(repo_id, filename):
             return cache_paths.get(filename)
 
-        # Mirror the same variable names and control flow as the real code
-        # so behavioral drift is caught immediately.
+        # Mirror the real code's variable names and control flow so behavioral
+        # drift is caught immediately.
         total_bytes = sum((p.size or 0) for p in path_infos)
         already_cached_bytes = 0
         for p in path_infos:
@@ -189,8 +185,8 @@ class TestCacheAwarePreflight:
         assert out["would_raise_disk_error"] is False
 
     def test_partial_cache_insufficient_disk_for_rest_still_raises(self):
-        """Two of four shards cached; remaining 70 GB still bigger than
-        free disk -> preflight correctly wants to raise."""
+        """Two of four shards cached; remaining 70 GB still exceeds free
+        disk -> preflight correctly wants to raise."""
         shards = [(f"UD-Q4_K_XL/shard-{i}.gguf", 35 * GIB) for i in range(4)]
         cached = {
             shards[0][0]: shards[0][1],
@@ -217,8 +213,8 @@ class TestCacheAwarePreflight:
         assert out["would_raise_disk_error"] is False
 
     def test_incomplete_cached_blob_is_not_credited(self):
-        """A partial file on disk (e.g. interrupted download) is not
-        counted as cached -- we still require bytes for it."""
+        """A partial file on disk (e.g. interrupted download) isn't counted
+        as cached -- we still require bytes for it."""
         shards = [("UD-Q4_K_XL/shard-0.gguf", 40 * GIB)]
         partial = {"UD-Q4_K_XL/shard-0.gguf": 10 * GIB}
         out = _preflight(
@@ -231,7 +227,7 @@ class TestCacheAwarePreflight:
         assert out["would_raise_disk_error"] is False
 
     def test_zero_size_path_infos_do_not_crash(self):
-        """A path_info with size=0 should not be credited or break the
+        """A path_info with size=0 must not be credited or break the
         arithmetic."""
         shards = [("mmproj.gguf", 0), ("UD-Q4_K_XL/shard-0.gguf", 40 * GIB)]
         out = _preflight(
diff --git a/studio/backend/tests/test_llama_cpp_context_fit.py b/studio/backend/tests/test_llama_cpp_context_fit.py
index ee8d54443a..ec66411bfd 100644
--- a/studio/backend/tests/test_llama_cpp_context_fit.py
+++ b/studio/backend/tests/test_llama_cpp_context_fit.py
@@ -5,26 +5,24 @@
 
 Guards two regressions in ``LlamaCppBackend.load_model``:
 
-1. **Auto mode on weights-exceed-VRAM** (``n_ctx == 0``): when the model
-   weights alone exceed 90% of every GPU subset's free memory, the
-   auto-pick loop used to exit without matching, leaving
-   ``effective_ctx`` at the model's native context (e.g. 196608 for
-   MiniMax-M2.7). The intended default per Studio's UI spec is 4096 so
-   the slider lands on a usable value; the user can still drag higher
-   and trigger ``--fit on`` with a warning.
+1. **Auto mode on weights-exceed-VRAM** (``n_ctx == 0``): when weights
+   alone exceed 90% of every GPU subset's free memory, the auto-pick loop
+   used to exit without matching, leaving ``effective_ctx`` at the native
+   context (e.g. 196608 for MiniMax-M2.7). Studio's UI spec wants 4096 so
+   the slider lands on a usable value; the user can still drag higher and
+   trigger ``--fit on`` with a warning.
 
 2. **Explicit ctx silently shrunk when KV overflows**: with fittable
-   weights but a requested ctx whose KV cache pushes total memory over
-   90% of VRAM, the old code binary-searched a smaller ctx and emitted
-   ``-c <capped> -ngl -1`` without informing the caller. The UI had
-   already surfaced its "might be slower" warning and expects the user's
-   explicit ctx to be honored with ``--fit on`` flexing ``-ngl`` instead.
+   weights but a ctx whose KV cache pushes total memory over 90% of VRAM,
+   the old code binary-searched a smaller ctx and emitted ``-c <capped>
+   -ngl -1`` without telling the caller. The UI already showed its "might
+   be slower" warning and expects the explicit ctx honored with ``--fit
+   on`` flexing ``-ngl`` instead.
 
-Tests avoid GPU probing, subprocess spawning, and GGUF I/O by driving the
+Avoids GPU probing, subprocess spawning, and GGUF I/O by driving the
 post-metadata decision block directly against a stubbed instance.
 
-Requires no GPU, network, or external libraries beyond pytest.
-Cross-platform: Linux, macOS, Windows, WSL.
+No GPU, network, or libraries beyond pytest. Cross-platform.
 """
 
 from __future__ import annotations
@@ -36,8 +34,8 @@ from pathlib import Path
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test.  Same pattern as test_kv_cache_estimation.py.
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_kv_cache_estimation.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -103,8 +101,8 @@ def _make_backend(
     kv_key_length = 128,
     kv_value_length = 128,
 ):
-    """Create a LlamaCppBackend instance with GGUF metadata fields set and
-    the helpers used by the decision block stubbed out."""
+    """LlamaCppBackend with GGUF metadata fields set and the decision
+    block's helpers stubbed out."""
     inst = LlamaCppBackend.__new__(LlamaCppBackend)
     inst._context_length = native_ctx
     inst._n_layers = n_layers
@@ -136,8 +134,8 @@ def _drive(
 ):
     """Drive the post-metadata portion of load_model with stubbed inputs.
 
-    Mirrors the decision block at llama_cpp.py:1137-1296 so we can assert
-    the command that would be built, without subprocesses or GPU probes.
+    Mirrors the decision block at llama_cpp.py:1137-1296 to assert the
+    command that would be built, without subprocesses or GPU probes.
     """
     inst = _make_backend(native_ctx = native_ctx)
     model_size = int(model_gib * GIB)
@@ -154,9 +152,8 @@ def _drive(
     inst._can_estimate_kv = lambda: can_estimate_kv
 
     context_length = inst._context_length
-    # Use the production helper instead of reimplementing the conditional
-    # locally; reimplementing makes the test pass for the test's own logic
-    # rather than production's, and silent drift won't be caught.
+    # Use the production helper, not a local reimplementation: a local copy
+    # would test the test's own logic, not production's, and hide drift.
     ctx_override = parse_ctx_override(extra_args)
     requested_ctx = resolve_requested_ctx(extra_args, n_ctx)
 
@@ -267,8 +264,8 @@ class TestAutoModeWeightsExceedVRAM:
         assert plan["c_arg"] == FALLBACK_CTX
         assert plan["use_fit"] is True
         assert plan["gpu_indices"] is None
-        # UI slider ceiling stays at native: user can still drag higher
-        # and get the "might be slower" path.
+        # UI slider ceiling stays at native: user can drag higher and get
+        # the "might be slower" path.
         assert plan["max_available_ctx"] == 196608
 
     def test_multi_gpu_all_subsets_fail(self):
@@ -304,9 +301,8 @@ class TestExplicitCtxRespectsUser:
     """``n_ctx > 0`` must never be silently shrunk."""
 
     def test_fittable_weights_oversized_kv(self):
-        # 8 GB weights + 131k ctx KV on 24 GB VRAM.
-        # Budget = 21.6 GB, KV at 131k >> 13.6 GB remaining, so
-        # _select_gpus flips use_fit=True.
+        # 8 GB weights + 131k ctx KV on 24 GB VRAM. Budget = 21.6 GB, KV
+        # at 131k >> 13.6 GB remaining, so _select_gpus flips use_fit=True.
         plan = _drive(
             n_ctx = 131072,
             model_gib = 8,
@@ -350,7 +346,7 @@ class TestExplicitCtxRespectsUser:
         assert plan["use_fit"] is True
 
     def test_explicit_below_floor_honored(self):
-        # 2048 is below --fit-ctx default; still honored since user set it.
+        # 2048 is below --fit-ctx default; honored since user set it.
         plan = _drive(
             n_ctx = 2048,
             model_gib = 8,
@@ -451,8 +447,8 @@ class TestTightFitPinsToGPU:
     """Models that fit at 91-95% of free VRAM must use the GPU."""
 
     def test_rtx_4090_qwen_24gb_class(self):
-        # noahterbest's #5106 log: 20.8 GB model on 22805 MiB free
-        # GPU, ctx=4096 -> ~94% utilization, ~1.4 GiB headroom.
+        # noahterbest's #5106 log: 20.8 GB model on 22805 MiB free GPU,
+        # ctx=4096 -> ~94% utilization, ~1.4 GiB headroom.
         plan = _drive(
             n_ctx = 0,
             model_gib = 20.8,
@@ -495,9 +491,9 @@ class TestTightFitPinsToGPU:
 
 @pytest.mark.parametrize("platform_tag", ["linux", "windows", "mac", "rocm"])
 def test_identical_decision_across_platforms(platform_tag):
-    """The decision function takes ``[(gpu_idx, free_mib), ...]`` regardless
-    of how upstream (nvidia-smi / nvidia-smi.exe / Metal / rocm-smi) produced
-    it. Identical inputs must yield identical plans."""
+    """The decision takes ``[(gpu_idx, free_mib), ...]`` regardless of the
+    source (nvidia-smi / nvidia-smi.exe / Metal / rocm-smi). Identical
+    inputs must yield identical plans."""
     plan_a = _drive(n_ctx = 0, model_gib = 8, gpus = [(0, 24_000)])
     plan_b = _drive(n_ctx = 0, model_gib = 8, gpus = [(0, 24_000)])
     assert plan_a == plan_b, platform_tag
@@ -525,8 +521,8 @@ class TestClassifyGpuOffload:
         assert inst._classify_gpu_offload(True, [(0, 22805)]) is True
 
     def test_cpu_only_buffer_returns_false(self):
-        # llama-server printed buffer lines but only CPU buffers --
-        # this is the silent CPU fallback symptom we want to catch.
+        # Buffer lines printed but only CPU buffers -- the silent CPU
+        # fallback symptom we want to catch.
         inst = self._backend(
             [
                 "load_tensors:   CPU_Mapped model buffer size = 21000.0 MiB",
@@ -555,8 +551,7 @@ class TestClassifyGpuOffload:
         assert inst._classify_gpu_offload(False, []) is None
 
     def test_user_did_not_intend_gpu_returns_none(self):
-        # Studio called start_llama_server without expecting GPU use;
-        # don't warn.
+        # Studio called start_llama_server without expecting GPU; don't warn.
         inst = self._backend(
             [
                 "load_tensors:   CPU_Mapped model buffer size = 21000.0 MiB",
diff --git a/studio/backend/tests/test_llama_cpp_freshness.py b/studio/backend/tests/test_llama_cpp_freshness.py
index c7dd111ee3..25bcf851b4 100644
--- a/studio/backend/tests/test_llama_cpp_freshness.py
+++ b/studio/backend/tests/test_llama_cpp_freshness.py
@@ -3,8 +3,8 @@
 
 """Tests for the llama.cpp prebuilt freshness check.
 
-Pins the marker parser, the disk+memory cache, the stale decision
-matrix, and fail-open behaviour on missing data.
+Pins the marker parser, disk+memory cache, stale-decision matrix, and
+fail-open behaviour on missing data.
 """
 
 from __future__ import annotations
@@ -57,7 +57,7 @@ def _write_marker(install_dir: Path, **overrides) -> Path:
 
 
 def _fake_binary(install_dir: Path, *, layout: str = "cmake") -> Path:
-    """Stub llama-server under one of the supported install layouts."""
+    """Stub llama-server under a supported install layout."""
     if layout == "cmake":
         bin_dir = install_dir / "build" / "bin"
         bin_name = "llama-server"
@@ -77,7 +77,7 @@ def _fake_binary(install_dir: Path, *, layout: str = "cmake") -> Path:
 
 @pytest.fixture(autouse = True)
 def _reset(monkeypatch, tmp_path):
-    # Isolate disk cache per-test; never touch the user's real cache.
+    # Isolate disk cache per-test; never touch the real cache.
     monkeypatch.setattr(fr, "_cache_dir", lambda: tmp_path / ".freshness")
     fr.reset_caches()
     yield
@@ -107,8 +107,8 @@ def test_read_install_marker_finds_root_layout(tmp_path):
 
 
 def test_read_install_marker_finds_windows_cmake_layout(tmp_path):
-    # Windows cmake puts the .exe under build/bin/Release/, so the
-    # marker is four levels above the binary.
+    # Windows cmake puts the .exe under build/bin/Release/, so the marker
+    # is four levels above the binary.
     install_dir = tmp_path / "llama.cpp"
     _write_marker(install_dir, tag = "b8888")
     bin_path = _fake_binary(install_dir, layout = "windows")
@@ -121,8 +121,8 @@ def test_read_install_marker_finds_windows_cmake_layout(tmp_path):
 def test_read_install_marker_carries_published_repo_dynamically(tmp_path, repo):
     # The freshness check queries whichever release repo the marker
     # records, so CUDA Linux (unslothai), CPU Linux x86_64 / macOS
-    # (ggml-org), and ROCm source-build (unslothai upstream label)
-    # all surface the right "latest" tag.
+    # (ggml-org), and ROCm source-build all surface the right "latest"
+    # tag.
     install_dir = tmp_path / "llama.cpp"
     _write_marker(install_dir, tag = "b9000", published_repo = repo)
     bin_path = _fake_binary(install_dir, layout = "cmake")
diff --git a/studio/backend/tests/test_llama_cpp_load_progress.py b/studio/backend/tests/test_llama_cpp_load_progress.py
index f95d8bf1a4..dcbe16be50 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress.py
@@ -4,18 +4,17 @@
 """Tests for ``LlamaCppBackend.load_progress()``.
 
 The chat settings flow and the training overlay both show a generic
-"Starting model..." spinner during the window after a GGUF download
-finishes and before llama-server reports healthy. For small models
-that window is a second or two and nobody notices. For large MoE GGUFs
-(MiniMax-M2.7, Qwen3.5-397B-A17B, etc.) the llama-server process spends
-minutes in kernel state D, paging tens or hundreds of GB of shards
-into the page cache. The UI has no way to show a real progress bar,
-rate, or ETA during that window.
+"Starting model..." spinner in the window after a GGUF download finishes
+and before llama-server reports healthy. For small models that window is a
+second or two and nobody notices. For large MoE GGUFs (MiniMax-M2.7,
+Qwen3.5-397B-A17B, etc.) llama-server spends minutes in kernel state D,
+paging tens or hundreds of GB of shards into the page cache. The UI has no
+way to show a real progress bar, rate, or ETA during that window.
 
-``load_progress()`` samples ``/proc/<pid>/status VmRSS`` (what the
-kernel has actually paged in) against the total shard file size on
-disk, so the frontend can render a real bar plus rate/ETA. This
-module pins that contract:
+``load_progress()`` samples ``/proc/<pid>/status VmRSS`` (what the kernel
+actually paged in) against the total shard file size on disk, so the
+frontend can render a real bar plus rate/ETA. This module pins that
+contract:
 
   * returns ``None`` when no load is in flight
   * returns ``{"phase": "mmap", ...}`` while the subprocess is alive
@@ -27,10 +26,9 @@ module pins that contract:
   * ``bytes_loaded`` is VmRSS in bytes, capped by total, rounded
   * ``fraction`` is clamped to 0..1 and rounded to 4 decimal places
 
-Linux-only via ``/proc``. On platforms without ``/proc`` the method
-returns ``None`` instead of raising.
-Cross-platform test: skips cleanly on macOS / Windows if ``/proc`` is
-not available.
+Linux-only via ``/proc``; without ``/proc`` the method returns ``None``
+instead of raising. Cross-platform test: skips cleanly on macOS / Windows
+when ``/proc`` is unavailable.
 """
 
 from __future__ import annotations
@@ -45,8 +43,8 @@ from unittest.mock import patch
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test. Same pattern as test_kv_cache_estimation.py.
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_kv_cache_estimation.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -106,7 +104,7 @@ def _make_instance():
 
 
 class _FakeProc:
-    """Minimal stand-in for subprocess.Popen that just carries a pid."""
+    """Minimal stand-in for subprocess.Popen carrying just a pid."""
 
     def __init__(self, pid: int):
         self.pid = pid
@@ -188,7 +186,7 @@ class TestLoadProgressSingleShard:
 
 
 class TestLoadProgressMultiShard:
-    """Shard-aware total: for ``*-00001-of-00004.gguf`` primaries the
+    """Shard-aware total: for ``*-00001-of-00004.gguf`` primaries, the
     method sums sibling files with the same prefix."""
 
     def test_sharded_total_aggregates_siblings(self, tmp_path):
@@ -197,7 +195,7 @@ class TestLoadProgressMultiShard:
                 tmp_path / f"model-{i:05d}-of-00004.gguf",
                 size_bytes = 20 * 1024**3,
             )
-        # Drop an unrelated .gguf in the same folder -- must not be counted.
+        # An unrelated .gguf in the same folder -- must not be counted.
         _write_sparse_file(tmp_path / "mmproj-BF16.gguf", 2 * 1024**3)
 
         inst = _make_instance()
diff --git a/studio/backend/tests/test_llama_cpp_load_progress_live.py b/studio/backend/tests/test_llama_cpp_load_progress_live.py
index 44a8f00834..ce9dd509bf 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress_live.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress_live.py
@@ -4,17 +4,15 @@
 """Live, no-mock integration test for ``LlamaCppBackend.load_progress()``.
 
 The companion files (``test_llama_cpp_load_progress.py`` and
-``test_llama_cpp_load_progress_matrix.py``) patch ``builtins.open`` to
-feed synthetic VmRSS values. This file is the opposite: it uses **real**
-subprocesses, **real** file sizes, and the **real** ``/proc``
-interface. It is the sanity check that the contract we keep in the
-mocked tests still maps to what the kernel actually returns on a live
-Linux system.
+``test_llama_cpp_load_progress_matrix.py``) patch ``builtins.open`` to feed
+synthetic VmRSS values. This file is the opposite: it uses **real**
+subprocesses, **real** file sizes, and the **real** ``/proc`` interface,
+checking that the contract from the mocked tests still maps to what the kernel
+returns on a live Linux system.
 
-Why both: the mocked tests can be fooled by a buggy implementation that
-parses ``/proc`` output in a format the kernel no longer uses, or that
-makes assumptions about ``Path.stat()`` vs ``os.path.getsize``. This
-file hits the real APIs so any format drift gets caught.
+Why both: the mocked tests can be fooled by an implementation that parses
+``/proc`` in a format the kernel no longer uses, or assumes ``Path.stat()`` vs
+``os.path.getsize``. This file hits the real APIs so format drift gets caught.
 
 Skipped cleanly on non-Linux (no ``/proc``).
 """
@@ -31,8 +29,8 @@ from pathlib import Path
 import pytest
 
 # ---------------------------------------------------------------------------
-# Same stubs as the matrix file (keep self-contained so the file can be
-# run standalone as well as via the full suite).
+# Same stubs as the matrix file (self-contained so this file runs standalone
+# and via the full suite).
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -88,8 +86,8 @@ def _make_backend(
 
 
 def test_live_rss_matches_kernel_vmrss(tmp_path):
-    """Spawn a real child, let it allocate real bytes, confirm
-    ``bytes_loaded`` tracks the kernel's VmRSS within a sane tolerance."""
+    """Spawn a real child, let it allocate real bytes, confirm ``bytes_loaded``
+    tracks the kernel's VmRSS within a sane tolerance."""
     # Child that allocates ~100 MB of zero'd bytes and then idles.
     script = tmp_path / "burn.py"
     script.write_text(
@@ -112,7 +110,7 @@ def test_live_rss_matches_kernel_vmrss(tmp_path):
         ready = proc.stdout.readline()
         assert ready.strip() == b"ready"
 
-        # Create a fake 200 MB sparse gguf so bytes_total is concrete.
+        # Fake 200 MB sparse gguf so bytes_total is concrete.
         gguf = tmp_path / "model.gguf"
         with open(gguf, "wb") as f:
             f.truncate(200 * 1024 * 1024)
@@ -123,8 +121,8 @@ def test_live_rss_matches_kernel_vmrss(tmp_path):
         assert out is not None, "load_progress returned None for live pid"
         assert out["phase"] == "mmap"
         assert out["bytes_total"] == 200 * 1024 * 1024
-        # VmRSS for the Python child includes the interpreter + the 100MB
-        # buffer, so a realistic floor is 50 MB and ceiling is 200 MB.
+        # VmRSS for the Python child includes the interpreter + 100MB buffer,
+        # so a realistic floor is 50 MB and ceiling is 200 MB.
         assert (
             out["bytes_loaded"] >= 50 * 1024 * 1024
         ), f"bytes_loaded unexpectedly low: {out['bytes_loaded']}"
@@ -153,8 +151,8 @@ def test_live_ready_phase_when_healthy(tmp_path):
 
 
 def test_live_dead_pid_returns_none(tmp_path):
-    """A recently-dead pid may linger in /proc for ms; use a clearly
-    invalid id so the read reliably fails."""
+    """A recently-dead pid may linger in /proc for ms; use a clearly invalid id
+    so the read reliably fails."""
     gguf = tmp_path / "m.gguf"
     gguf.touch()
 
@@ -164,8 +162,8 @@ def test_live_dead_pid_returns_none(tmp_path):
 
 
 def test_live_shard_aggregation_counts_real_files(tmp_path):
-    """With 4 real sibling shards on disk, ``bytes_total`` equals their
-    summed size to the byte."""
+    """With 4 real sibling shards on disk, ``bytes_total`` equals their summed
+    size to the byte."""
     shard_size = 7 * 1024 * 1024  # 7 MB each
     for i in range(1, 5):
         f = tmp_path / f"model-{i:05d}-of-00004.gguf"
@@ -186,8 +184,8 @@ def test_live_shard_aggregation_counts_real_files(tmp_path):
 
 
 def test_live_repeated_polling_stays_sane(tmp_path):
-    """Sampling the same backend 20 times should not raise or produce
-    non-numeric output, even under normal kernel RSS jitter."""
+    """Sampling the same backend 20 times must not raise or produce non-numeric
+    output, even under normal kernel RSS jitter."""
     gguf = tmp_path / "m.gguf"
     with open(gguf, "wb") as f:
         f.truncate(500 * 1024 * 1024)
diff --git a/studio/backend/tests/test_llama_cpp_load_progress_matrix.py b/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
index a88450ec0b..1a698d3613 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
@@ -3,29 +3,29 @@
 
 """Extended test matrix for ``LlamaCppBackend.load_progress()``.
 
-Companion to ``test_llama_cpp_load_progress.py`` (which pins the basic
-contract). This file widens coverage to the edge cases that bit users
-or were hypothesized to bite them on cross-platform installs:
+Companion to ``test_llama_cpp_load_progress.py`` (basic contract). Widens
+coverage to edge cases that bit (or were thought to bite) cross-platform
+installs:
 
-  * Platform matrix — macOS/Windows simulation via ``/proc`` absence.
+  * Platform matrix — macOS/Windows via ``/proc`` absence.
   * ``VmRSS`` parsing — tab vs space delimiter, missing line, malformed
     integer.
   * Filesystem edges — HF-cache symlinks, broken symlinks, nonexistent
     paths, relative paths.
-  * Shard aggregation — partial multi-shard downloads where some shards
-    are still ``.incomplete``, two shard series in the same dir,
+  * Shard aggregation — partial multi-shard downloads with some shards
+    still ``.incomplete``, two shard series in one dir,
     ``mmproj-*.gguf`` sibling exclusion for non-sharded primaries,
     single-file models.
-  * Lifecycle races — process set before ``_gguf_path`` is assigned,
-    process dead mid-sample, ``_healthy`` flipped to True.
-  * Concurrent sampling — 10 threads × 50 iterations against a single
-    backend, hitting real ``/proc`` (no mocks — see the note in
+  * Lifecycle races — process set before ``_gguf_path``, process dead
+    mid-sample, ``_healthy`` flipped to True.
+  * Concurrent sampling — 10 threads × 50 iterations against one
+    backend, hitting real ``/proc`` (no mocks — see
     ``TestConcurrentSampling`` for why).
   * Fraction bounds — capped at 1.0 when RSS exceeds total; 0.0 when
     total is zero.
 
-All tests are Linux-only in practice (we stub ``/proc`` where needed).
-The stable subset runs in well under a second.
+Linux-only in practice (``/proc`` stubbed where needed). The stable
+subset runs in well under a second.
 """
 
 from __future__ import annotations
@@ -41,8 +41,8 @@ from unittest.mock import patch
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test. Same pattern as test_llama_cpp_load_progress.py.
+# Stub heavy/unavailable deps before importing the module under test.
+# Same pattern as test_llama_cpp_load_progress.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -113,7 +113,7 @@ def _sparse(path, size):
 
 
 def _fake_proc_reader(rss_kb):
-    """Return an ``open()`` replacement that fakes /proc reads with a VmRSS line."""
+    """An ``open()`` replacement faking /proc reads with a VmRSS line."""
 
     def fake_open(path, *args, **kwargs):
         if str(path).startswith("/proc/"):
@@ -129,8 +129,8 @@ def _fake_proc_reader(rss_kb):
 
 
 class TestPlatformMatrix:
-    """The method is Linux-first via /proc. On macOS/Windows it must
-    degrade to None rather than crash."""
+    """Linux-first via /proc. On macOS/Windows must degrade to None
+    rather than crash."""
 
     def test_linux_live_proc_is_self_pid(self, tmp_path):
         """Self-pid /proc read uses the real kernel interface."""
@@ -144,7 +144,7 @@ class TestPlatformMatrix:
         assert out is not None
         assert out["phase"] == "mmap"
         assert out["bytes_total"] == 1 * 1024**3
-        # Our Python process has some RSS -- just sanity-check positive.
+        # Our process has some RSS -- sanity-check it's positive.
         assert out["bytes_loaded"] > 0
 
     def test_macos_no_proc_returns_none(self, tmp_path):
@@ -199,7 +199,7 @@ class TestVmRSSParsing:
         assert out["bytes_loaded"] == 2 * 1024**3
 
     def test_space_separated_fallback(self, tmp_path):
-        """Some kernels emit single-space rather than tab."""
+        """Some kernels emit a single space, not a tab."""
         gguf = tmp_path / "m.gguf"
         _sparse(gguf, 4 * 1024**3)
         inst = _make()
@@ -235,8 +235,8 @@ class TestVmRSSParsing:
         assert out["fraction"] == 0.0
 
     def test_malformed_vmrss_value(self, tmp_path):
-        """Non-integer VmRSS value should be treated as if the line were
-        absent (early ValueError caught)."""
+        """Non-integer VmRSS is treated like an absent line (ValueError
+        caught)."""
         gguf = tmp_path / "m.gguf"
         _sparse(gguf, 1 * 1024**3)
         inst = _make()
@@ -250,7 +250,7 @@ class TestVmRSSParsing:
 
         with patch("builtins.open", side_effect = fake_open):
             out = inst.load_progress()
-        # The implementation catches ValueError on int() and returns None.
+        # int() ValueError is caught and returns None.
         assert out is None
 
 
@@ -262,7 +262,7 @@ class TestVmRSSParsing:
 class TestFilesystemEdges:
     def test_symlink_primary_follows_to_blob(self, tmp_path):
         """HF cache stores blobs under blobs/ and symlinks them from
-        snapshots/. The method must follow the symlink."""
+        snapshots/. Must follow the symlink."""
         blob = tmp_path / "blob"
         _sparse(blob, 12 * 1024**3)
         snap = tmp_path / "snap"
@@ -300,7 +300,7 @@ class TestFilesystemEdges:
 
     def test_relative_gguf_path(self, tmp_path):
         """Relative paths shouldn't crash; behaviour depends on CWD but
-        the method must not raise."""
+        must not raise."""
         cwd = os.getcwd()
         try:
             os.chdir(tmp_path)
@@ -323,11 +323,11 @@ class TestFilesystemEdges:
 
 class TestShardAggregation:
     def test_partial_multi_shard_download(self, tmp_path):
-        """Primary present but shards 2..N still downloading as
-        ``.incomplete``. Sums only the fully-arrived ``.gguf`` files."""
+        """Primary present but shards 2..N still ``.incomplete``. Sums
+        only the fully-arrived ``.gguf`` files."""
         _sparse(tmp_path / "m-00001-of-00004.gguf", 30 * 1024**3)
         _sparse(tmp_path / "m-00002-of-00004.gguf", 30 * 1024**3)
-        # 3 and 4 still downloading as .incomplete
+        # 3 and 4 still downloading as .incomplete.
         _sparse(tmp_path / "m-00003-of-00004.gguf.incomplete", 5 * 1024**3)
         inst = _make()
         inst._process = _Proc(os.getpid())
@@ -337,8 +337,8 @@ class TestShardAggregation:
         assert out["bytes_total"] == 60 * 1024**3  # only the .gguf siblings
 
     def test_two_shard_series_in_same_dir(self, tmp_path):
-        """Defensive: if two quant series share a dir, prefix filter
-        only sums siblings of the chosen primary."""
+        """Defensive: when two quant series share a dir, the prefix
+        filter sums only siblings of the chosen primary."""
         for i in range(1, 3):
             _sparse(tmp_path / f"m_q4-{i:05d}-of-00002.gguf", 10 * 1024**3)
             _sparse(tmp_path / f"m_q8-{i:05d}-of-00002.gguf", 20 * 1024**3)
@@ -351,7 +351,7 @@ class TestShardAggregation:
 
     def test_mmproj_sibling_not_counted(self, tmp_path):
         """Vision models drop an ``mmproj-*.gguf`` alongside. For a
-        single-file (non-sharded) primary we only count the primary."""
+        single-file (non-sharded) primary, count only the primary."""
         _sparse(tmp_path / "m.gguf", 8 * 1024**3)
         _sparse(tmp_path / "mmproj-BF16.gguf", 2 * 1024**3)
         inst = _make()
@@ -359,7 +359,7 @@ class TestShardAggregation:
         inst._gguf_path = str(tmp_path / "m.gguf")
         with patch("builtins.open", side_effect = _fake_proc_reader(0)):
             out = inst.load_progress()
-        # Non-sharded primary: only the primary is counted.
+        # Non-sharded: only the primary is counted.
         assert out["bytes_total"] == 8 * 1024**3
 
     def test_single_file_model(self, tmp_path):
@@ -381,7 +381,7 @@ class TestShardAggregation:
 
 class TestLifecycleRaces:
     def test_process_set_but_gguf_path_not_yet(self, tmp_path):
-        """Moment between Popen and self._gguf_path=model_path."""
+        """Window between Popen and self._gguf_path=model_path."""
         inst = _make()
         inst._process = _Proc(os.getpid())
         inst._gguf_path = None
@@ -418,14 +418,13 @@ class TestLifecycleRaces:
 
 class TestConcurrentSampling:
     def test_parallel_invocations_never_raise(self, tmp_path):
-        """Many concurrent samplers hitting the same backend must not raise.
+        """Many concurrent samplers on one backend must not raise.
 
-        We intentionally do NOT patch ``builtins.open`` here because
-        ``unittest.mock.patch`` is not thread-safe: interleaved
-        enter/exit across threads can leak a Mock into ``builtins.open``
-        and poison every subsequent test in the session. Instead, we
-        let each thread hit the real ``/proc/self/status`` of the test
-        process, which is exactly the code path that matters in prod.
+        We do NOT patch ``builtins.open`` here: ``unittest.mock.patch``
+        is not thread-safe -- interleaved enter/exit across threads can
+        leak a Mock into ``builtins.open`` and poison later tests.
+        Instead each thread hits the real ``/proc/self/status``, the
+        code path that matters in prod.
         """
         _sparse(tmp_path / "m.gguf", 1 * 1024**3)
         inst = _make()
diff --git a/studio/backend/tests/test_llama_cpp_max_context_threshold.py b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
index aa0198892f..30131991ae 100644
--- a/studio/backend/tests/test_llama_cpp_max_context_threshold.py
+++ b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
@@ -3,22 +3,20 @@
 
 """Tests for the ``max_context_length`` warning-threshold semantics.
 
-``/api/inference/status.max_context_length`` is what the ctx slider in
-the chat settings sheet reads to decide when to render the "Exceeds
-estimated VRAM capacity. The model may use system RAM." warning:
+The ctx slider in the chat settings sheet reads
+``/api/inference/status.max_context_length`` to decide when to render the
+"Exceeds estimated VRAM capacity. The model may use system RAM." warning:
 
     ctxDisplayValue > ggufMaxContextLength → show warning
 
-For models whose weights fit on some GPU subset, the warning threshold
-is the largest ctx that fits fully in VRAM (the binary-search cap from
-``_fit_context_to_vram``). For models whose weights exceed 90% of every
-GPU subset's free memory, the warning must fire as soon as the user
-drags above the 4096 spec default (otherwise a user loading e.g.
-MiniMax-M2.7 on a 97 GB GPU sees a slider up to 196608 with no
-indication that any value above 4096 will trigger ``--fit on`` and
-degrade performance).
+When weights fit on some GPU subset, the threshold is the largest ctx that
+fits fully in VRAM (the binary-search cap from ``_fit_context_to_vram``).
+When weights exceed 90% of every GPU subset's free memory, the warning must
+fire as soon as the user drags above the 4096 spec default (otherwise loading
+e.g. MiniMax-M2.7 on a 97 GB GPU shows a slider up to 196608 with no hint that
+any value above 4096 triggers ``--fit on`` and degrades performance).
 
-These tests pin both cases. No GPU probing, no subprocess, no GGUF I/O.
+These tests pin both cases. No GPU probing, subprocess, or GGUF I/O.
 Cross-platform: Linux, macOS, Windows, WSL.
 """
 
@@ -31,8 +29,8 @@ from pathlib import Path
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test.  Same pattern as test_kv_cache_estimation.py.
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_kv_cache_estimation.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -115,9 +113,8 @@ def _compute_max_available_ctx(
     gpus,
     kv_per_token_bytes = 325_000,
 ):
-    """Run the ceiling-probe block from load_model and return the final
-    ``max_available_ctx`` value the backend would assign to
-    ``_max_context_length``.
+    """Run load_model's ceiling-probe block and return the final
+    ``max_available_ctx`` the backend would assign to ``_max_context_length``.
     """
     inst = _make_backend(native_ctx = native_ctx)
     model_size = int(model_gib * GIB)
@@ -163,8 +160,8 @@ def _compute_max_available_ctx(
 
 
 class TestMaxContextLengthForWeightsExceedVRAM:
-    """The UI ``max_context_length`` threshold must fall back to 4096 so
-    the warning fires as soon as the user drags above the spec default.
+    """UI ``max_context_length`` must fall back to 4096 so the warning fires
+    as soon as the user drags above the spec default.
     """
 
     def test_minimax_like(self):
@@ -186,8 +183,8 @@ class TestMaxContextLengthForWeightsExceedVRAM:
         assert got == 4096
 
     def test_native_below_fallback_is_preserved(self):
-        """If the model's native ctx is itself smaller than 4096, do not
-        advertise a larger value than the model supports."""
+        """If native ctx is itself below 4096, don't advertise a larger value
+        than the model supports."""
         got = _compute_max_available_ctx(
             native_ctx = 2048,
             model_gib = 200,
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index 9e7944913a..fc21c48b76 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -187,9 +187,9 @@ def _mtp_backend(**overrides):
     backend._requested_n_ctx = 8192
     backend._cache_type_kv = None
     backend._speculative_type = "draft-mtp"
-    # Default fixture simulates Auto having auto-promoted to draft-mtp.
-    # Individual tests override _requested_spec_mode when they want a
-    # forced mode or the user---spec-type-extra-args path.
+    # Fixture simulates Auto having auto-promoted to draft-mtp. Tests
+    # override _requested_spec_mode for a forced mode or the
+    # user---spec-type-extra-args path.
     backend._requested_spec_mode = "auto"
     backend._chat_template_override = None
     backend._is_vision = False
@@ -239,11 +239,10 @@ def test_already_in_target_state_matches_when_request_uses_default_for_mtp_model
 
 
 def test_already_in_target_state_auto_request_matches_auto_backend_for_non_mtp_model():
-    # Under the requested-mode round-trip model, Auto requested against an
-    # Auto-recorded backend matches regardless of model name. The underlying
-    # resolved emission (--spec-default vs draft-mtp) is handled by the
-    # backend's own load path and reflected in _speculative_type; the
-    # short-circuit comparison only cares whether the *intent* changed.
+    # In the requested-mode round-trip model, Auto-vs-Auto matches regardless
+    # of model name. The resolved emission (--spec-default vs draft-mtp) is
+    # handled by the load path and reflected in _speculative_type; the
+    # short-circuit only cares whether the *intent* changed.
     backend = _mtp_backend(
         _model_identifier = "unsloth/Qwen3.6-27B-GGUF",
         _speculative_type = "default",
@@ -404,10 +403,10 @@ def test_already_in_target_state_vision_mtp_default_matches():
 
 def test_already_in_target_state_vision_off_matches_vision_backend():
     # Vision loads silently drop speculative decoding at the route level
-    # (_request_matches_loaded_settings overrides req to "off"). At the
-    # llama_cpp.py level, _already_in_target_state compares canonical
-    # requested modes; a vision backend recorded with _requested_spec_mode
-    # = "off" matches a req of "off" or None+vision.
+    # (_request_matches_loaded_settings overrides req to "off"). In
+    # llama_cpp.py, _already_in_target_state compares canonical requested
+    # modes; a vision backend recorded with _requested_spec_mode = "off"
+    # matches a req of "off" or None+vision.
     backend = _mtp_backend(
         _model_identifier = "unsloth/Qwen3-VL-4B-Instruct-GGUF",
         _is_vision = True,
@@ -616,9 +615,8 @@ def test_probe_detects_legacy_ngram_mod_flavor(tmp_path):
 
 @_NEEDS_BASH
 def test_probe_ignores_removal_stub_descriptions(tmp_path):
-    # Post-rename binary: legacy flags are present but with
-    # "argument has been removed" descriptions; must not be detected
-    # as legacy.
+    # Post-rename binary: legacy flags present but with "argument has been
+    # removed" descriptions; must not be detected as legacy.
     fake = _make_fake_llama_server(tmp_path / "llama-server", _POST_RENAME_HELP)
     _clear_caps_cache()
     caps = LlamaCppBackend.probe_server_capabilities(str(fake))
@@ -784,16 +782,15 @@ def test_already_in_target_state_draft_n_max_ignored_when_not_mtp():
     )
 
 
-# Sub-3B MTP gate -- tiny dense models regress with the MTP draft
-# head, so load_model falls back to ngram-mod (when the binary supports
-# it) instead of draft-mtp. The reload-skip mirror must follow the
-# same fallback so a sub-3B reload-with-default does not bounce a
-# correctly-configured ngram-mod / off backend.
+# Sub-3B MTP gate -- tiny dense models regress with the MTP draft head, so
+# load_model falls back to ngram-mod (when the binary supports it) instead of
+# draft-mtp. The reload-skip mirror must follow the same fallback so a sub-3B
+# reload-with-default doesn't bounce a correctly-configured ngram-mod/off backend.
 
 
 def _patch_probe(monkeypatch, ngram_supported):
-    """Force probe_server_capabilities to a deterministic result so
-    tests don't depend on whatever llama-server happens to be on PATH."""
+    """Force probe_server_capabilities to a deterministic result so tests
+    don't depend on whatever llama-server is on PATH."""
     fake = {
         "found": True,
         "mtp_token": "draft-mtp",
@@ -815,8 +812,8 @@ def _patch_probe(monkeypatch, ngram_supported):
 
 
 def test_already_in_target_state_sub_3b_falls_back_to_ngram_mod_when_supported(monkeypatch):
-    # 0.8B MTP request -- load_model would have promoted to ngram-mod
-    # (no MTP head); reload check must match a ngram-mod backend.
+    # 0.8B MTP request -- load_model would have promoted to ngram-mod (no MTP
+    # head); reload check must match a ngram-mod backend.
     _patch_probe(monkeypatch, ngram_supported = True)
     backend = _mtp_backend(
         _model_identifier = "unsloth/Qwen3.5-0.8B-MTP-GGUF",
@@ -888,8 +885,8 @@ def test_already_in_target_state_4b_mtp_request_promotes_as_before(monkeypatch):
 
 
 def test_already_in_target_state_2b_falls_back_to_ngram_below_threshold(monkeypatch):
-    # 2.0B is below the 3B threshold -> ngram-mod fallback, not
-    # draft-mtp. Clean-bench shows 2B regresses with draft-mtp.
+    # 2.0B is below the 3B threshold -> ngram-mod fallback, not draft-mtp.
+    # Clean-bench shows 2B regresses with draft-mtp.
     _patch_probe(monkeypatch, ngram_supported = True)
     backend = _mtp_backend(
         _model_identifier = "unsloth/Qwen3.5-2B-MTP-GGUF",
@@ -1023,9 +1020,9 @@ def _resolver_backend(
 
 
 def _flags_dict(flags):
-    """Parse the spec-flag list into a small {flag: value} dict; collapses
-    repeated flags by keeping the last (only --spec-type can repeat and
-    never does in our resolver)."""
+    """Parse the spec-flag list into a {flag: value} dict; collapses repeated
+    flags by keeping the last (only --spec-type can repeat, and never does
+    in our resolver)."""
     out = {}
     i = 0
     while i < len(flags):
@@ -1125,8 +1122,8 @@ def test_build_speculative_flags_user_extra_args_owns_spec_type(monkeypatch):
         gpus = True,
         binary = "/fake/llama-server",
     )
-    # No flags emitted by the resolver -- the user's extra_args carries
-    # the --spec-type, and the resolver records requested_spec_mode = None.
+    # Resolver emits nothing -- the user's extra_args carries the --spec-type,
+    # and the resolver records requested_spec_mode = None.
     assert flags == []
     assert backend.requested_spec_mode is None
     assert backend.speculative_type is None
@@ -1179,7 +1176,7 @@ def test_build_speculative_flags_mtp_token_missing_logs_and_skips(monkeypatch):
         binary = "/fake/llama-server",
     )
     assert "--spec-type" not in flags
-    # _speculative_type stays None (resolved emission was none), but
-    # _requested_spec_mode still reflects the user's choice.
+    # _speculative_type stays None (resolved emission was none); the user's
+    # choice is still reflected in _requested_spec_mode.
     assert backend.requested_spec_mode == "mtp"
     assert backend.speculative_type is None
diff --git a/studio/backend/tests/test_llama_cpp_no_context_shift.py b/studio/backend/tests/test_llama_cpp_no_context_shift.py
index b9f25faf88..312adea83e 100644
--- a/studio/backend/tests/test_llama_cpp_no_context_shift.py
+++ b/studio/backend/tests/test_llama_cpp_no_context_shift.py
@@ -3,17 +3,15 @@
 
 """``--no-context-shift`` launch-flag contract.
 
-When llama-server runs with its default context-shift behavior, the UI
-has no way to tell the user that the KV cache has been rotated --
-earlier turns silently vanish from the conversation. The Studio
-backend always passes ``--no-context-shift`` so the server returns a
+With llama-server's default context-shift behavior, the UI cannot tell the user
+the KV cache was rotated -- earlier turns silently vanish from the conversation.
+The Studio backend always passes ``--no-context-shift`` so the server returns a
 clean error instead, and the chat adapter can point the user at the
 ``Context Length`` input in the settings panel.
 
-This file is a static read of the launch command: we ask
-``LlamaCppBackend`` to assemble its ``cmd`` list and assert the flag
-is always present. Testing via the real subprocess would require an
-actual GGUF on disk, which is out of scope for the fast test suite.
+This file statically reads the launch command: we ask ``LlamaCppBackend`` to
+assemble its ``cmd`` list and assert the flag is present. Testing via the real
+subprocess would need an actual GGUF on disk, out of scope for the fast suite.
 """
 
 from __future__ import annotations
@@ -68,11 +66,10 @@ from core.inference import llama_cpp as llama_cpp_module
 def _load_model_source() -> str:
     """Return the source of ``LlamaCppBackend.load_model``.
 
-    Using ``inspect.getsource`` instead of reading the file directly
-    scopes the assertions to the function that actually launches
-    llama-server, so neither the presence check nor the location check
-    can be fooled by a stray occurrence of ``"--no-context-shift"``
-    elsewhere in the module.
+    Using ``inspect.getsource`` instead of reading the file scopes the assertions
+    to the function that launches llama-server, so neither the presence nor the
+    location check can be fooled by a stray ``"--no-context-shift"`` elsewhere in
+    the module.
     """
     return inspect.getsource(llama_cpp_module.LlamaCppBackend.load_model)
 
@@ -80,10 +77,9 @@ def _load_model_source() -> str:
 def test_no_context_shift_is_in_load_model():
     """The flag is part of the static launch-command template.
 
-    We check the source of ``load_model`` rather than mocking the whole
-    call chain (GPU probing, GGUF stat, etc.): the flag is written as
-    a literal in one place and any regression has to delete it, which
-    a text search will catch.
+    We check the source of ``load_model`` rather than mocking the whole call
+    chain (GPU probing, GGUF stat, etc.): the flag is a literal in one place and
+    any regression must delete it, which a text search catches.
     """
     assert '"--no-context-shift"' in _load_model_source(), (
         "llama-server must be launched with --no-context-shift so the "
@@ -93,21 +89,20 @@ def test_no_context_shift_is_in_load_model():
 
 
 def test_flag_sits_inside_the_base_cmd_list():
-    """Pin the flag's location so a future refactor can't accidentally
-    move it into a branch that only fires on some code paths.
+    """Pin the flag's location so a refactor can't move it into a branch that
+    only fires on some code paths.
 
-    We slice from ``cmd = [`` to the first ``]`` at the same indent.
-    Using ``inspect.getsource`` means the function lives in its own
-    string and there are no siblings to worry about, so a plain
-    bracket search would also work -- anchoring on the trailing indent
-    just keeps the slice from wandering into a later expression if the
-    opening literal ever grows an in-line comment trailing it.
+    We slice from ``cmd = [`` to the first ``]`` at the same indent. Since
+    ``inspect.getsource`` gives the function its own string with no siblings, a
+    plain bracket search would also work -- anchoring on the trailing indent just
+    keeps the slice from wandering into a later expression if the opening literal
+    ever grows a trailing in-line comment.
     """
     source = _load_model_source()
     start = source.find("cmd = [")
     assert start >= 0, "could not find the base cmd = [...] block"
-    # Find the first line containing only ``]`` (possibly indented).
-    # Works for any indentation style the formatter picks.
+    # Find the first line containing only ``]`` (possibly indented); works for
+    # any indentation style the formatter picks.
     rest = source[start:]
     end_rel = -1
     for line_start, line in _iter_lines_with_offset(rest):
@@ -124,7 +119,7 @@ def test_flag_sits_inside_the_base_cmd_list():
         "conditional branch -- otherwise some code paths would still "
         "run with silent context shift enabled."
     )
-    # Also pin that it is next to -c / --ctx so the grouping makes sense.
+    # Also pin that it sits next to -c / --ctx so the grouping makes sense.
     assert '"-c"' in block
     assert '"--flash-attn"' in block
 
diff --git a/studio/backend/tests/test_llama_cpp_start_failure_classification.py b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
index 202fd36c86..8d88a61ae3 100644
--- a/studio/backend/tests/test_llama_cpp_start_failure_classification.py
+++ b/studio/backend/tests/test_llama_cpp_start_failure_classification.py
@@ -4,10 +4,10 @@
 """Tests for LlamaCppBackend._classify_llama_start_failure.
 
 When llama-server exits before becoming healthy, load_model turns its
-captured stdout/stderr into a user-facing reason. A diffusion / image
-GGUF (FLUX, Qwen-Image, ...) is a valid file with plenty of memory, so
-the generic "invalid file or out of memory" message is actively
-misleading (issue #5842). These tests pin the classification.
+captured stdout/stderr into a user-facing reason. A diffusion/image GGUF
+(FLUX, Qwen-Image, ...) is a valid file with plenty of memory, so the
+generic "invalid file or out of memory" message is misleading (issue
+#5842). These tests pin the classification.
 """
 
 from __future__ import annotations
@@ -22,8 +22,8 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Match the stubbing pattern in sibling tests so the module imports in a
-# lightweight env without fastapi.
+# Match sibling tests' stubbing so the module imports in a lightweight
+# env without fastapi.
 _loggers_stub = _types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_health.py b/studio/backend/tests/test_llama_cpp_wait_for_health.py
index bcf2eb1683..d787107d39 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_health.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_health.py
@@ -3,10 +3,10 @@
 
 """Tests for LlamaCppBackend._wait_for_health resilience.
 
-The probe loop must swallow transient httpx errors and fall through to
-the subprocess.poll() branch so a crashed llama-server surfaces a
-structured "exited with code X" log instead of bubbling an opaque
-exception up to the /api/inference/load route.
+The probe loop must swallow transient httpx errors and fall through to the
+subprocess.poll() branch so a crashed llama-server surfaces a structured
+"exited with code X" log instead of bubbling an opaque exception up to the
+/api/inference/load route.
 """
 
 from __future__ import annotations
@@ -22,8 +22,7 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Match the stubbing pattern in sibling tests so the module imports in
-# a lightweight env without fastapi.
+# Mirror sibling tests' stubbing so the module imports without fastapi.
 _loggers_stub = _types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
@@ -33,11 +32,10 @@ import httpx  # noqa: E402
 
 from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
 
-# Sibling tests in this directory install lightweight httpx stubs via
-# sys.modules.setdefault. When collected together, our `httpx` symbol
-# may be one of those stubs, which lacks `get`. Ensure the production
-# code finds a working `httpx.get` and the standard exception types
-# regardless of collection order by adding the missing attributes.
+# Sibling tests install lightweight httpx stubs via sys.modules.setdefault.
+# When collected together, our `httpx` may be such a stub lacking `get`. Add
+# the missing attributes so production code finds a working `httpx.get` and
+# the standard exception types regardless of collection order.
 if not hasattr(httpx, "get"):
     httpx.get = None  # placeholder; every test below monkeypatches it
 for _exc_name in (
@@ -52,9 +50,9 @@ for _exc_name in (
 
 
 def _make_backend(port: int = 12345) -> LlamaCppBackend:
-    """Build a barebones LlamaCppBackend instance with only the
-    attributes _wait_for_health touches. Bypasses __init__ so we do not
-    pull in the full subprocess + logging stack."""
+    """Barebones LlamaCppBackend with only the attributes
+    _wait_for_health touches. Bypasses __init__ to avoid the full
+    subprocess + logging stack."""
     b = LlamaCppBackend.__new__(LlamaCppBackend)
     b._port = port
     b._stdout_thread = None
@@ -72,14 +70,12 @@ class TestWaitForHealthResilience:
         assert b._wait_for_health(timeout = 1.0, interval = 0.01) is True
 
     def test_read_error_loops_to_subprocess_poll(self, monkeypatch):
-        """WinError 10054 maps to httpx.ReadError. The loop must swallow
-        it and the next iteration must detect the dead subprocess via
-        poll() != None, returning False with a structured exit-code log
-        instead of bubbling the ReadError."""
+        """WinError 10054 maps to httpx.ReadError. The loop must swallow it;
+        the next iteration detects the dead subprocess via poll() != None and
+        returns False with a structured exit-code log, not the ReadError."""
         b = _make_backend()
-        # First iteration: process alive (so we reach the httpx probe).
-        # Second iteration: process has exited (so we hit the structured
-        # exit-code branch and return False).
+        # Iter 1: process alive (reach the httpx probe).
+        # Iter 2: process exited (hit the exit-code branch, return False).
         b._process.poll.side_effect = [None, 1]
         b._process.returncode = 1
         b._stdout_lines = ["llama-server: ggml-cuda.dll failed to load"]
@@ -89,12 +85,12 @@ class TestWaitForHealthResilience:
 
         monkeypatch.setattr(httpx, "get", raise_read_error)
         assert b._wait_for_health(timeout = 5.0, interval = 0.01) is False
-        # Both iterations of the loop ran -- the ReadError did not bubble.
+        # Both loop iterations ran -- the ReadError did not bubble.
         assert b._process.poll.call_count >= 2
 
     def test_remote_protocol_error_also_swallowed(self, monkeypatch):
-        """Partial / malformed response on the probe (server crashed
-        mid-headers) raises RemoteProtocolError -- also non-fatal."""
+        """A partial/malformed probe response (server crashed mid-headers)
+        raises RemoteProtocolError -- also non-fatal."""
         b = _make_backend()
         b._process.poll.side_effect = [None, -1]
         b._process.returncode = -1
@@ -121,8 +117,8 @@ class TestWaitForHealthResilience:
         assert b._process.poll.call_count >= 2
 
     def test_connect_error_swallowed_until_success(self, monkeypatch):
-        """Sanity: existing ConnectError swallowing still works -- the
-        loop retries until llama-server eventually answers 200."""
+        """Sanity: existing ConnectError swallowing still works -- the loop
+        retries until llama-server answers 200."""
         b = _make_backend()
         b._process.poll.return_value = None
         calls = {"n": 0}
@@ -139,8 +135,8 @@ class TestWaitForHealthResilience:
         assert calls["n"] >= 3
 
     def test_dead_process_before_probe_returns_false(self, monkeypatch):
-        """If poll() != None on entry, _wait_for_health must return
-        False immediately without calling httpx at all."""
+        """poll() != None on entry: _wait_for_health returns False
+        immediately without calling httpx."""
         b = _make_backend()
         b._process.poll.return_value = 137
         b._process.returncode = 137
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
index 125b13782a..5183553607 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
@@ -3,9 +3,9 @@
 
 """``_wait_for_vram_settle`` helper contract.
 
-Pins the bounded poll over ``_get_gpu_free_memory`` that bridges the
-kill -> spawn VRAM-reclaim window. Patches ``_get_gpu_free_memory``;
-no real llama-server or nvidia-smi involved.
+Pins the bounded poll over ``_get_gpu_free_memory`` bridging the kill -> spawn
+VRAM-reclaim window. Patches ``_get_gpu_free_memory``; no real llama-server or
+nvidia-smi involved.
 """
 
 from __future__ import annotations
@@ -20,8 +20,8 @@ import pytest
 
 
 # ---------------------------------------------------------------------------
-# Same external-dep stubs as the other llama_cpp tests so this module
-# imports cleanly without httpx / structlog / loggers installed.
+# Same external-dep stubs as the other llama_cpp tests so this module imports
+# without httpx / structlog / loggers installed.
 # ---------------------------------------------------------------------------
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
@@ -34,8 +34,8 @@ sys.modules.setdefault("loggers", _loggers_stub)
 _structlog_stub = _types.ModuleType("structlog")
 _structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("stub")
 sys.modules.setdefault("structlog", _structlog_stub)
-# Ensure get_logger is set even if a previous test module already
-# inserted a bare ``structlog`` stub via ``setdefault``.
+# Set get_logger even if a prior test inserted a bare ``structlog`` stub
+# via ``setdefault``.
 if not hasattr(sys.modules["structlog"], "get_logger"):
     sys.modules["structlog"].get_logger = _structlog_stub.get_logger
 
@@ -74,8 +74,8 @@ def _patch_probe(samples):
     """Patch ``_get_gpu_free_memory`` to yield ``samples`` in order.
 
     Each entry is a list[(idx, free_mib)], a callable, or an exception
-    (instance or class). Calls past the end repeat the last entry so
-    tests can assert "stopped polling" via the call count.
+    (instance or class). Calls past the end repeat the last entry so tests
+    can assert "stopped polling" via the call count.
     """
     state = {"i": 0, "calls": 0}
 
@@ -112,8 +112,8 @@ def _kw(**extra):
 
 
 def test_cold_start_returns_immediately_without_probing():
-    """Default ``since_kill=0.0`` is cold-start: no kill recorded,
-    helper short-circuits without ever invoking the probe."""
+    """Default ``since_kill=0.0`` is cold-start: no kill recorded, so the
+    helper short-circuits without invoking the probe."""
     ctx, state = _patch_probe([[(0, 10000)], [(0, 10000)]])
     with ctx:
         start = time.monotonic()
@@ -154,8 +154,8 @@ def test_first_probe_raises_returns_without_polling():
 
 
 def test_two_consecutive_samples_within_tolerance_settles():
-    """The reclaim ramp from 10000 → 11500 → 11550: third sample within
-    256 MiB of the second so the helper returns after exactly three probes."""
+    """Reclaim ramp 10000 → 11500 → 11550: third sample within 256 MiB of
+    the second, so the helper returns after exactly three probes."""
     ctx, state = _patch_probe(
         [
             [(0, 10000)],
@@ -168,7 +168,7 @@ def test_two_consecutive_samples_within_tolerance_settles():
         LlamaCppBackend._wait_for_vram_settle(**_kw(max_wait = 2.0, interval = 0.05))
         elapsed = time.monotonic() - start
     assert state["calls"] == 3
-    # interval * 2 sleeps = 0.10; allow generous slack for scheduler jitter.
+    # interval * 2 sleeps = 0.10; allow slack for scheduler jitter.
     assert elapsed < 1.0
 
 
@@ -199,7 +199,7 @@ def test_max_wait_respected_when_never_settles():
         start = time.monotonic()
         LlamaCppBackend._wait_for_vram_settle(**_kw(max_wait = 0.5, interval = 0.1))
         elapsed = time.monotonic() - start
-    # We must stop near max_wait, not run forever. Generous upper bound for CI.
+    # Must stop near max_wait, not run forever. Generous upper bound for CI.
     assert 0.3 <= elapsed < 2.0, f"helper ignored max_wait: elapsed={elapsed:.3f}s"
 
 
@@ -217,8 +217,8 @@ def test_max_wait_respected_when_probe_is_slow():
             **_kw(max_wait = 0.4, interval = 0.25),
         )
         elapsed = time.monotonic() - start
-    # First probe (0.30 s) + at most one short clipped sleep + bail.
-    # Hard cap well below the old behaviour of 0.30 + 0.25 + 0.30 = 0.85.
+    # First probe (0.30 s) + at most one clipped sleep + bail.
+    # Hard cap well below the old 0.30 + 0.25 + 0.30 = 0.85.
     assert elapsed < 0.85, f"helper exceeded the deadline due to slow probes: {elapsed:.3f}s"
 
 
@@ -264,8 +264,8 @@ def test_tolerance_two_percent_for_large_cards():
 
 
 def test_load_model_calls_helper_outside_lock_and_uses_last_kill_timestamp():
-    """Pin the call site: outside Phase 3 lock, gated on the timestamp,
-    no ``had_live_process`` in-band flag regression. Mirrors the
+    """Pin the call site: outside Phase 3 lock, gated on the timestamp, no
+    ``had_live_process`` in-band flag regression. Mirrors the
     ``inspect.getsource`` pattern from ``test_llama_cpp_no_context_shift``.
     """
     import inspect
@@ -274,11 +274,11 @@ def test_load_model_calls_helper_outside_lock_and_uses_last_kill_timestamp():
     assert "_wait_for_vram_settle" in src
     assert "since_kill" in src
     assert "self._last_kill_monotonic" in src
-    # Must be invoked before Phase 3's broad lock so /unload, /cancel,
-    # /status are not blocked during the wait.
+    # Must run before Phase 3's broad lock so /unload, /cancel, /status
+    # are not blocked during the wait.
     assert src.index("_wait_for_vram_settle") < src.index("# ── Phase 3:")
-    # An in-band ``had_live_process`` flag would silently regress the
-    # frontend /unload+/load Apply path; use the timestamp instead.
+    # An in-band ``had_live_process`` flag would regress the frontend
+    # /unload+/load Apply path; use the timestamp instead.
     assert "had_live_process" not in src
 
 
diff --git a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
index a5c9d2255f..4fa7d2f8e6 100644
--- a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
+++ b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
@@ -4,9 +4,9 @@
 """Tests for the Windows pip-nvidia DLL dir resolver.
 
 Studio installs torch with bundled CUDA wheels (nvidia-cuda-runtime-cu13,
-nvidia-cublas-cu13, etc.) and the prebuilt llama-server.exe must find
-those DLLs at runtime to load CUDA. Mirrors the Linux LD_LIBRARY_PATH
-block. See unslothai/unsloth#5106.
+nvidia-cublas-cu13, etc.) and the prebuilt llama-server.exe must find those
+DLLs at runtime to load CUDA. Mirrors the Linux LD_LIBRARY_PATH block.
+See unslothai/unsloth#5106.
 """
 
 from __future__ import annotations
@@ -61,7 +61,7 @@ from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
 
 def _make_nvidia_layout(prefix: Path, pkgs_with_layout: dict[str, str]):
     """Build a fake <prefix>/Lib/site-packages/nvidia/<pkg>/{bin|Library/bin}
-    tree with a stub DLL inside each leaf so isdir() picks them up."""
+    tree with a stub DLL in each leaf so isdir() picks them up."""
     nv = prefix / "Lib" / "site-packages" / "nvidia"
     for pkg, layout in pkgs_with_layout.items():
         if layout == "bin":
@@ -124,9 +124,8 @@ class TestWindowsPipNvidiaDllDirs:
         assert len(result) == 4
 
     def test_does_not_walk_outside_known_paths(self, tmp_path):
-        # Only nvidia/<pkg>/{bin,Library/bin} and torch/lib are picked
-        # up. Unrelated site-packages contents (numpy, scipy, ...) must
-        # be ignored.
+        # Only nvidia/<pkg>/{bin,Library/bin} and torch/lib are picked up.
+        # Unrelated site-packages contents (numpy, scipy, ...) are ignored.
         site = tmp_path / "Lib" / "site-packages"
         (site / "numpy").mkdir(parents = True)
         (site / "scipy" / "linalg").mkdir(parents = True)
@@ -135,9 +134,9 @@ class TestWindowsPipNvidiaDllDirs:
 
     def test_picks_up_torch_lib(self, tmp_path):
         # PyTorch's Windows CUDA wheel bundles cudart64_X.dll /
-        # cublas64_X.dll directly under Lib/site-packages/torch/lib/
-        # instead of as separate nvidia-* wheels. Without this, users
-        # on torch-bundled-CUDA installs still hit #5106.
+        # cublas64_X.dll directly under Lib/site-packages/torch/lib/ rather
+        # than as separate nvidia-* wheels. Without this, torch-bundled-CUDA
+        # installs still hit #5106.
         torch_lib = tmp_path / "Lib" / "site-packages" / "torch" / "lib"
         torch_lib.mkdir(parents = True)
         (torch_lib / "cudart64_12.dll").write_bytes(b"")
@@ -146,8 +145,7 @@ class TestWindowsPipNvidiaDllDirs:
         assert Path(result[0]) == torch_lib
 
     def test_torch_lib_combined_with_nvidia_wheels(self, tmp_path):
-        # Both modular nvidia-* wheels and torch/lib are returned when
-        # present together.
+        # Both modular nvidia-* wheels and torch/lib are returned together.
         _make_nvidia_layout(
             tmp_path,
             {
@@ -165,8 +163,7 @@ class TestWindowsPipNvidiaDllDirs:
         assert any(Path(p) == torch_lib for p in result)
 
     def test_torch_lib_must_be_a_directory(self, tmp_path):
-        # If torch/lib exists as a file (broken install), it is
-        # ignored, not returned.
+        # If torch/lib exists as a file (broken install), it is ignored.
         site = tmp_path / "Lib" / "site-packages" / "torch"
         site.mkdir(parents = True)
         (site / "lib").write_bytes(b"not a dir")
@@ -176,24 +173,22 @@ class TestWindowsPipNvidiaDllDirs:
     def test_skips_non_directories(self, tmp_path):
         nv = tmp_path / "Lib" / "site-packages" / "nvidia"
         (nv / "cuda_runtime").mkdir(parents = True)
-        # Create a regular file at the path where 'bin' would normally be a dir
+        # Regular file where 'bin' would normally be a dir
         (nv / "cuda_runtime" / "bin").write_bytes(b"not a dir")
         result = LlamaCppBackend._windows_pip_nvidia_dll_dirs(str(tmp_path))
         assert result == []
 
     def test_missing_prefix_does_not_raise(self):
-        # If sys.prefix points to a path that doesn't exist (unusual,
-        # but possible during test setup), the resolver must just
-        # return [] rather than raising.
+        # If sys.prefix points to a nonexistent path (unusual but possible
+        # during test setup), the resolver must return [], not raise.
         result = LlamaCppBackend._windows_pip_nvidia_dll_dirs("/this/path/does/not/exist/anywhere")
         assert result == []
 
     def test_picks_up_cu13_bin_x86_64_layout(self, tmp_path):
-        # Current ``nvidia-cuda-runtime`` 13.x and ``nvidia-cublas``
-        # 13.x Windows wheels ship DLLs under
-        # ``nvidia/cu13/bin/x86_64/`` instead of ``nvidia/<pkg>/bin/``.
-        # Without this, users on the new CUDA 13 wheel generation hit
-        # the original #5106 failure mode.
+        # Current ``nvidia-cuda-runtime`` 13.x and ``nvidia-cublas`` 13.x
+        # Windows wheels ship DLLs under ``nvidia/cu13/bin/x86_64/`` instead
+        # of ``nvidia/<pkg>/bin/``. Without this, the new CUDA 13 wheel
+        # generation hits the original #5106 failure mode.
         dll_dir = tmp_path / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
         dll_dir.mkdir(parents = True)
         for name in ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll"):
@@ -203,7 +198,7 @@ class TestWindowsPipNvidiaDllDirs:
 
     def test_picks_up_bin_x64_layout(self, tmp_path):
         # Some repackaged wheels use ``bin/x64`` (Windows-x64 convention)
-        # instead of ``bin/x86_64`` (NVIDIA-internal convention).
+        # rather than ``bin/x86_64`` (NVIDIA-internal convention).
         dll_dir = tmp_path / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x64"
         dll_dir.mkdir(parents = True)
         (dll_dir / "cudart64_13.dll").write_bytes(b"")
@@ -211,9 +206,8 @@ class TestWindowsPipNvidiaDllDirs:
         assert str(dll_dir) in result
 
     def test_mixed_cu12_and_cu13_layouts(self, tmp_path):
-        # A venv could have both the modular cu12 wheels (legacy) and
-        # the unsuffixed cu13 wheel installed side by side. Both must
-        # be reachable.
+        # A venv could have both the modular cu12 wheels (legacy) and the
+        # unsuffixed cu13 wheel side by side. Both must be reachable.
         site = tmp_path / "Lib" / "site-packages"
         cu12_bin = site / "nvidia" / "cuda_runtime" / "bin"
         cu13_arch = site / "nvidia" / "cu13" / "bin" / "x86_64"
@@ -225,10 +219,10 @@ class TestWindowsPipNvidiaDllDirs:
         assert cu13_arch in result_set
 
     def test_glob_meta_in_prefix_is_safe(self, tmp_path):
-        # Windows usernames / install paths can contain ``[`` or ``]``.
-        # A glob-based resolver would interpret these as a character
-        # class and silently return [] even when DLL dirs exist. The
-        # iterdir-based implementation must work on such paths.
+        # Windows usernames / install paths can contain ``[`` or ``]``. A
+        # glob-based resolver would read these as a character class and
+        # return [] even when DLL dirs exist. The iterdir-based
+        # implementation must work on such paths.
         prefix = tmp_path / "studio_[gpu]_install"
         dll_dir = prefix / "Lib" / "site-packages" / "nvidia" / "cuda_runtime" / "bin"
         dll_dir.mkdir(parents = True)
@@ -237,18 +231,17 @@ class TestWindowsPipNvidiaDllDirs:
         assert str(dll_dir) in result, f"bracket-prefixed path returned empty: {result}"
 
     def test_arch_subdir_listed_before_parent_bin(self, tmp_path):
-        # When both ``nvidia/<pkg>/bin/`` and
-        # ``nvidia/<pkg>/bin/x86_64/`` exist, the arch-specific subdir
-        # must be listed first so Windows DLL search picks up the
-        # cudart64_X.dll location even if the parent ``bin`` is empty.
+        # When both ``nvidia/<pkg>/bin/`` and ``nvidia/<pkg>/bin/x86_64/``
+        # exist, the arch-specific subdir must be listed first so the Windows
+        # DLL search finds cudart64_X.dll even if the parent ``bin`` is empty.
         site = tmp_path / "Lib" / "site-packages"
         outer_bin = site / "nvidia" / "cu13" / "bin"
         arch_bin = outer_bin / "x86_64"
         arch_bin.mkdir(parents = True)
         (arch_bin / "cudart64_13.dll").write_bytes(b"")
         result = LlamaCppBackend._windows_pip_nvidia_dll_dirs(str(tmp_path))
-        # outer_bin exists as a directory (it contains arch_bin); the
-        # arch-specific subdir should come first in the list.
+        # outer_bin exists as a dir (it holds arch_bin); the arch-specific
+        # subdir should come first in the list.
         result_paths = [Path(p) for p in result]
         assert arch_bin in result_paths
         assert outer_bin in result_paths
diff --git a/studio/backend/tests/test_llama_server_args.py b/studio/backend/tests/test_llama_server_args.py
index 2c7362a9ff..60d4fb0bc3 100644
--- a/studio/backend/tests/test_llama_server_args.py
+++ b/studio/backend/tests/test_llama_server_args.py
@@ -4,8 +4,8 @@
 """Unit tests for the llama-server pass-through args validator.
 
 The validator is the boundary between user CLI/HTTP input and the
-llama-server subprocess. These tests pin denylist behaviour so it
-doesn't quietly regress when new managed flags are added.
+llama-server subprocess. These tests pin denylist behaviour so it doesn't
+regress when new managed flags are added.
 """
 
 from __future__ import annotations
@@ -16,10 +16,10 @@ from pathlib import Path
 
 import pytest
 
-# Load llama_server_args.py directly so this test doesn't drag in the
-# full backend chain (fastapi / structlog / loggers / utils.hardware)
-# via core/inference/__init__.py. The validator is intentionally
-# dependency-free and unit-tests should reflect that.
+# Load llama_server_args.py directly so this test doesn't drag in the full
+# backend chain (fastapi / structlog / loggers / utils.hardware) via
+# core/inference/__init__.py. The validator is intentionally dependency-free
+# and unit tests should reflect that.
 _LSA_PATH = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_server_args.py"
 _spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
 _lsa = importlib.util.module_from_spec(_spec)
@@ -72,10 +72,10 @@ validate_extra_args = _lsa.validate_extra_args
         # Reasoning controls
         ["--reasoning-format", "deepseek"],
         ["-rea", "auto"],
-        # Soft-managed: user-supplied flags last-wins-override Studio's
-        # auto-set version. --parallel / -np / --n-parallel are NOT
-        # here -- they're hard-denied (KV-cache + slot count would
-        # desync). Use `unsloth studio run --parallel N` instead.
+        # Soft-managed: user flags last-wins-override Studio's auto-set
+        # version. --parallel / -np / --n-parallel are NOT here -- they're
+        # hard-denied (KV-cache + slot count would desync). Use
+        # `unsloth studio run --parallel N` instead.
         ["-c", "131072"],
         ["--ctx-size", "8192"],
         ["--flash-attn", "off"],
@@ -124,8 +124,8 @@ def test_non_flag_token_passes_through():
         "-np",
         "--parallel",
         "--n-parallel",
-        # Model identity (every alias; bumping llama.cpp must keep
-        # every form rejected, not just the long).
+        # Model identity (every alias; bumping llama.cpp must keep every
+        # form rejected, not just the long one).
         "-m",
         "--model",
         "-mu",
@@ -173,8 +173,8 @@ def test_non_flag_token_passes_through():
         "--models-max",
         "--models-autoload",
         "--no-models-autoload",
-        # Server-mode flips: --embedding / --rerank would restrict
-        # llama-server to those endpoints and break Studio's chat hop.
+        # Server-mode flips: --embedding / --rerank restrict llama-server to
+        # those endpoints and break Studio's chat hop.
         "--embedding",
         "--embeddings",
         "--rerank",
@@ -191,16 +191,16 @@ def test_denylist_rejects_all_aliases(denied):
 @pytest.mark.parametrize(
     "args,offending",
     [
-        # Pass-through --parallel would last-wins-override the real
-        # slot count while Studio's KV-cache fit + llama_parallel_slots
-        # stay at the typer value -- plan vs. process disagree.
+        # Pass-through --parallel would last-wins-override the real slot
+        # count while Studio's KV-cache fit + llama_parallel_slots stay at
+        # the typer value -- plan vs. process disagree.
         (["--parallel", "8"], "--parallel"),
         (["--parallel=8"], "--parallel"),
         (["--n-parallel", "16"], "--n-parallel"),
         (["--n-parallel=16"], "--n-parallel"),
         (["-np", "32"], "-np"),
-        # Attached short form: Click clusters it CLI-side; HTTP /load
-        # with `["-np8"]` must still resolve to managed.
+        # Attached short form: Click clusters it CLI-side; HTTP /load with
+        # `["-np8"]` must still resolve to managed.
         (["-np8"], "-np"),
         (["-np64"], "-np"),
         # Out-of-range values that would bypass the typer 1..64 guard.
@@ -227,8 +227,8 @@ def test_denylist_rejects_equals_form():
     [" --parallel", "--parallel ", "\t--parallel", "  -np", "-np \n", "-np\t"],
 )
 def test_denylist_rejects_whitespace_padded_forms(padded):
-    # `_flag_name` trims whitespace before lookup; otherwise a trailing
-    # space could slip a managed flag past the boundary.
+    # `_flag_name` trims whitespace before lookup; else a trailing space
+    # could slip a managed flag past the boundary.
     with pytest.raises(ValueError, match = "parallel|np"):
         validate_extra_args([padded, "8"])
 
@@ -238,15 +238,15 @@ def test_denylist_rejects_whitespace_padded_forms(padded):
     ["-np8x", "-np-1foo", "-np+1bar", "-np9zzz"],
 )
 def test_denylist_rejects_np_with_digit_prefix_and_junk(attached):
-    # Backend `_flag_name` must classify the same forms the CLI
-    # rewriter expands, else HTTP /load could smuggle `-np8x` through.
+    # Backend `_flag_name` must classify the same forms the CLI rewriter
+    # expands, else HTTP /load could smuggle `-np8x` through.
     with pytest.raises(ValueError, match = "np"):
         validate_extra_args([attached])
 
 
 def test_denylist_rejects_short_form_when_long_is_denied():
-    # `-m` is the short form of --model; rejecting only the long
-    # form would leave a trivial bypass.
+    # `-m` is the short form of --model; rejecting only the long form
+    # would leave a trivial bypass.
     with pytest.raises(ValueError, match = "-m"):
         validate_extra_args(["-m", "/some/other/path.gguf"])
 
diff --git a/studio/backend/tests/test_log_filter_no_truncation.py b/studio/backend/tests/test_log_filter_no_truncation.py
index d9a6e2bc4a..52ffa2ba32 100644
--- a/studio/backend/tests/test_log_filter_no_truncation.py
+++ b/studio/backend/tests/test_log_filter_no_truncation.py
@@ -4,9 +4,9 @@
 """
 Regression tests for loggers.handlers.filter_sensitive_data.
 
-Pins two properties: (1) long strings with commas/slashes pass through
-unchanged (the base64-truncation heuristic from PR #5246 was too aggressive),
-and (2) native-path lease redaction still fires for both inline and dict-key forms.
+Pins two properties: (1) long strings with commas/slashes pass through unchanged
+(the base64-truncation heuristic from PR #5246 was too aggressive), and
+(2) native-path lease redaction still fires for inline and dict-key forms.
 """
 
 from loggers.handlers import filter_sensitive_data
diff --git a/studio/backend/tests/test_login_rate_limit.py b/studio/backend/tests/test_login_rate_limit.py
index 1b084cf436..6f2d2c7d94 100644
--- a/studio/backend/tests/test_login_rate_limit.py
+++ b/studio/backend/tests/test_login_rate_limit.py
@@ -4,11 +4,11 @@
 """Tests for the per-(ip, username) login rate limiter.
 
 Covers:
-  - bucket key composition is (client-ip, username.lower())
-  - X-Forwarded-For is honoured only when UNSLOTH_STUDIO_TRUST_FORWARDED is set
+  - bucket key is (client-ip, username.lower())
+  - X-Forwarded-For honoured only when UNSLOTH_STUDIO_TRUST_FORWARDED is set
   - 429 detail body does NOT leak the client IP
-  - One username failing does not lock out a different user from the same IP
-  - One IP failing does not lock out the same user from a different IP
+  - One username failing doesn't lock out a different user from the same IP
+  - One IP failing doesn't lock out the same user from a different IP
 """
 
 import os
@@ -69,8 +69,8 @@ class TestClientIp:
             "127.0.0.1",
             {"x-forwarded-for": "198.51.100.7, 10.0.0.1"},
         )
-        # The proxy header could be spoofed; without the opt-in we
-        # only trust the direct connection.
+        # Proxy header can be spoofed; without the opt-in, trust only the
+        # direct connection.
         assert _client_ip(req) == "127.0.0.1"
 
     def test_honours_first_xff_when_trust_on(self, env_trust_proxy):
@@ -123,8 +123,8 @@ class TestClientIp:
     def test_forwarded_isolates_first_element(self, env_trust_proxy):
         from routes.auth import _client_ip
 
-        # Multi-element Forwarded must pick the first element only,
-        # otherwise suffix variations create attacker-controlled buckets.
+        # Multi-element Forwarded must pick the first element only, else suffix
+        # variations create attacker-controlled buckets.
         req = _FakeRequest(
             "127.0.0.1",
             {"forwarded": "for=198.51.100.42, for=10.0.0.1;proto=https"},
@@ -155,7 +155,7 @@ class TestBucketKeyAndBlocking:
         for _ in range(_LOGIN_MAX_FAILS):
             _record_login_failure(_bucket_key(req, "alice"))
         assert _login_blocked(_bucket_key(req, "alice")) > 0
-        # bob's account from the same IP is unaffected by alice's typos.
+        # bob's account from the same IP is unaffected by alice's typos
         assert _login_blocked(_bucket_key(req, "bob")) == 0
 
     def test_record_per_ip_isolates_other_ips(self, env_no_proxy):
@@ -189,8 +189,8 @@ class TestBucketKeyAndBlocking:
         req = _FakeRequest("203.0.113.10")
         for idx in range(5):
             auth_routes._record_login_failure(auth_routes._unknown_user_key(req))
-            # Different "username" each attempt would not have throttled
-            # under per-(ip,username) only; the IP aggregate must.
+            # A different "username" each attempt wouldn't throttle under
+            # per-(ip,username) only; the IP aggregate must.
         # The next missing-user attempt is blocked.
         assert auth_routes._login_blocked(auth_routes._unknown_user_key(req)) > 0
 
@@ -202,8 +202,8 @@ class TestBucketKeyAndBlocking:
         unknown_key = auth_routes._unknown_user_key(req)
         for _ in range(20):
             auth_routes._record_login_failure(unknown_key)
-        # Account bucket cardinality stays at exactly one sentinel entry
-        # for this IP regardless of how many distinct usernames sprayed.
+        # Account bucket cardinality stays at exactly one sentinel entry for
+        # this IP regardless of how many distinct usernames sprayed.
         ip_keys = [k for k in auth_routes._LOGIN_BUCKETS if k[0] == "203.0.113.11"]
         assert len(ip_keys) == 1
         assert ip_keys[0][1].startswith("\x00")
@@ -216,7 +216,7 @@ class TestBucketKeyAndBlocking:
         req = _FakeRequest("203.0.113.12")
         for idx in range(50):
             auth_routes._record_login_failure((req.client.host, f"user-{idx}"))
-        # Hard cap respected; further keys do not allocate.
+        # Hard cap respected; further keys don't allocate.
         assert len(auth_routes._LOGIN_BUCKETS) <= 10
 
 
@@ -249,7 +249,7 @@ class TestLogin429Body:
     def test_429_detail_does_not_leak_ip(self, env_no_proxy, login_client):
         from routes.auth import _LOGIN_MAX_FAILS
 
-        # Drive 6 failures from the same client IP / username.
+        # Drive 6 failures from the same client IP / username
         for _ in range(_LOGIN_MAX_FAILS):
             r = login_client.post(
                 "/api/auth/login",
@@ -262,8 +262,8 @@ class TestLogin429Body:
         )
         assert r.status_code == 429
         detail = r.json()["detail"]
-        # The 429 body must not interpolate the source IP.
+        # The 429 body must not interpolate the source IP
         assert "127.0.0.1" not in detail
         assert "Too many" in detail
-        # Retry-After header is still set for clients.
+        # Retry-After header is still set for clients
         assert "Retry-After" in r.headers
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index 0d263d7630..9def1619d7 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -151,8 +151,8 @@ def test_execute_tool_disabled_server(tmp_path, monkeypatch):
 
 
 def test_mcp_specs_skip_invalid_openai_function_names():
-    """OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; tools whose
-    names contain '.', '/', spaces, etc. would 400 the whole request."""
+    """OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; names with '.',
+    '/', spaces, etc. would 400 the whole request."""
     from core.inference.tools import _mcp_specs_for_server
 
     server = {"id": "srv", "display_name": "S"}
@@ -178,7 +178,7 @@ def test_mcp_specs_skip_empty_tool_name():
 
 def test_mcp_specs_drops_duplicate_names():
     """Same tool name twice from one MCP server -> OpenAI rejects the
-    request as 'duplicates'. Drop the duplicate before forwarding."""
+    request as 'duplicates'. Drop duplicates before forwarding."""
     from core.inference.tools import _mcp_specs_for_server
 
     server = {"id": "srv", "display_name": "S"}
@@ -188,8 +188,8 @@ def test_mcp_specs_drops_duplicate_names():
 
 
 def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
-    """cancel_event already set before the call -> immediate Error: cancelled
-    without making a network round-trip."""
+    """cancel_event set before the call -> immediate Error: cancelled, no
+    network round-trip."""
     import threading
     from core.inference import mcp_client
 
@@ -203,7 +203,7 @@ def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
 
         async def call_tool(self, name, args):
             import asyncio as _asyncio
-            await _asyncio.sleep(30)  # never finishes within the test
+            await _asyncio.sleep(30)  # never finishes during the test
 
     monkeypatch.setattr(mcp_client, "_client", lambda *a, **kw: _StubClient())
 
@@ -221,8 +221,8 @@ def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
 
 
 def test_clear_oauth_tokens_async_no_op_safe(tmp_path, monkeypatch):
-    """clear_oauth_tokens_async on a URL with no stored token must not raise --
-    the delete + update handlers call it best-effort regardless of prior state."""
+    """clear_oauth_tokens_async on a URL with no stored token must not raise;
+    the delete + update handlers call it best-effort regardless of state."""
     import asyncio
 
     monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
@@ -233,7 +233,7 @@ def test_clear_oauth_tokens_async_no_op_safe(tmp_path, monkeypatch):
 
 
 def test_delete_server_calls_oauth_cleanup_when_oauth_was_on(tmp_path, monkeypatch):
-    """delete_mcp_server route helper should invoke clear_oauth_tokens_async
+    """delete_mcp_server route helper must call clear_oauth_tokens_async
     when the deleted row had use_oauth=true."""
     import asyncio
 
@@ -255,7 +255,7 @@ def test_delete_server_calls_oauth_cleanup_when_oauth_was_on(tmp_path, monkeypat
         calls.append(url)
 
     monkeypatch.setattr(mcp_client, "clear_oauth_tokens_async", fake_clear)
-    # Re-import the route's binding through the module so the patch is seen.
+    # Patch the route's module binding too so it's seen.
     import routes.mcp_servers as routes_mcp
 
     monkeypatch.setattr(routes_mcp, "clear_oauth_tokens_async", fake_clear)
@@ -292,7 +292,7 @@ def test_delete_server_skips_oauth_cleanup_when_oauth_off(tmp_path, monkeypatch)
 
 def test_update_server_clears_oauth_on_url_change(tmp_path, monkeypatch):
     """Changing the URL on an OAuth server must drop the old URL's tokens
-    so the new URL doesn't silently inherit credentials."""
+    so the new URL doesn't inherit credentials."""
     import asyncio
 
     _reset_db(tmp_path, monkeypatch)
@@ -381,7 +381,7 @@ def test_changes_from_payload_rejects_null_use_oauth():
 
 def test_test_endpoint_surfaces_url_validation_as_400(tmp_path, monkeypatch):
     """POST /api/mcp/servers/test must 400 on invalid URL like create/update;
-    previously the same input returned 200 with {"ok": false}."""
+    it previously returned 200 with {"ok": false}."""
     import asyncio
 
     _reset_db(tmp_path, monkeypatch)
@@ -399,9 +399,9 @@ def test_test_endpoint_surfaces_url_validation_as_400(tmp_path, monkeypatch):
 
 
 def test_tool_xml_parser_handles_hyphenated_parameter_names():
-    """MCP tool schemas commonly use hyphenated property names like
+    """MCP tool schemas often use hyphenated property names like
     `issue-number` / `repo-name`; the XML parser's `<parameter=\\w+>` regex
-    dropped those keys. Verify hyphenated parameter names round-trip."""
+    dropped those keys. Verify hyphenated names round-trip."""
     from core.inference.tool_call_parser import parse_tool_calls_from_text
     import json as _json
 
@@ -428,9 +428,9 @@ def test_tool_healing_strip_handles_hyphenated_function_names():
 
 
 def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
-    """When the model emits a tool call not in the per-request tool list
-    the GGUF agentic loop must refuse to dispatch -- mirroring the
-    safetensors path. Previously execute_tool ran the call regardless."""
+    """When the model emits a tool call not in the per-request tool list,
+    the GGUF agentic loop must refuse to dispatch (mirroring the
+    safetensors path). execute_tool previously ran the call regardless."""
     from core.inference import tools as tools_mod
 
     captured: list[str] = []
@@ -441,8 +441,8 @@ def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
 
     monkeypatch.setattr(tools_mod, "execute_tool", fake_execute)
 
-    # Re-create the allow-list check inline so we can unit-test the
-    # behavior without spinning up llama-server.
+    # Re-create the allow-list check inline to unit-test the behavior
+    # without spinning up llama-server.
     def _gate(tools_advertised, called_name, args):
         allowed = {
             (t.get("function") or {}).get("name")
@@ -472,9 +472,9 @@ def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
 
 
 def test_call_tool_sync_short_circuits_on_pre_set_cancel(monkeypatch):
-    """cancel_event set BEFORE call_tool_sync runs -> no HTTP request
-    is made. Previously the call task was created before the cancel
-    check, opening a transport that the watcher then had to cancel."""
+    """cancel_event set BEFORE call_tool_sync runs -> no HTTP request made.
+    The call task was previously created before the cancel check, opening a
+    transport that the watcher then had to cancel."""
     from core.inference import mcp_client
 
     opened: list[str] = []
@@ -510,9 +510,9 @@ def test_call_tool_sync_short_circuits_on_pre_set_cancel(monkeypatch):
 
 
 def test_clear_oauth_tokens_swallows_constructor_errors(tmp_path, monkeypatch):
-    """clear_oauth_tokens_async is best-effort; an OAuth constructor
-    failure (e.g. missing fastmcp.client.auth) must not bubble out into
-    a 500 from the delete / update routes."""
+    """clear_oauth_tokens_async is best-effort; an OAuth constructor failure
+    (e.g. missing fastmcp.client.auth) must not bubble into a 500 from the
+    delete / update routes."""
     import asyncio
     from core.inference import mcp_client
 
@@ -535,8 +535,8 @@ def test_clear_oauth_tokens_swallows_constructor_errors(tmp_path, monkeypatch):
 
 def test_tool_xml_parser_handles_hyphenated_function_names():
     """MCP tool names are advertised as `mcp__srv__list-issues` (the regex
-    fix allows '-'); the XML tool-call parser must parse them too,
-    otherwise the model can call the tool but Studio cannot dispatch."""
+    fix allows '-'); the XML tool-call parser must parse them too, else the
+    model can call the tool but Studio cannot dispatch."""
     from core.inference.tool_call_parser import parse_tool_calls_from_text
 
     calls = parse_tool_calls_from_text(
@@ -552,7 +552,7 @@ def test_tool_xml_parser_handles_hyphenated_function_names():
 
 def test_tool_xml_strip_handles_hyphenated_function_names():
     """routes/inference.py:_TOOL_XML_RE must strip a `<function=name-with-dash>`
-    block; otherwise hyphenated MCP tool-call XML leaks into chat history."""
+    block; else hyphenated MCP tool-call XML leaks into chat history."""
     import re as _re
     from pathlib import Path
 
@@ -570,11 +570,10 @@ def test_tool_xml_strip_handles_hyphenated_function_names():
 
 
 def test_safetensors_agentic_empty_allowlist_still_means_allow_all():
-    """Document existing contract: at the safetensors_agentic layer,
-    tools=[] is still treated as "no constraint" (so existing callers
-    work unchanged). The real fix for the MCP-only-no-discovery case
-    lives at the route level in inference.py, which refuses to enter
-    use_tools when the resolved tool list is empty."""
+    """Document the contract: at the safetensors_agentic layer, tools=[] is
+    still "no constraint" (existing callers work unchanged). The real fix
+    for the MCP-only-no-discovery case lives at the route level in
+    inference.py, which refuses use_tools when the resolved list is empty."""
     import threading
     from core.inference.safetensors_agentic import run_safetensors_tool_loop
 
diff --git a/studio/backend/tests/test_mcp_stdio_improvements.py b/studio/backend/tests/test_mcp_stdio_improvements.py
index 515e39d5b6..bec4f9393e 100644
--- a/studio/backend/tests/test_mcp_stdio_improvements.py
+++ b/studio/backend/tests/test_mcp_stdio_improvements.py
@@ -1,8 +1,8 @@
 """Tests for the proposed PR #5863 improvements.
 
 Covers: _client() self-gating + keep_alive, OAuth normalised off for stdio
-(create + update), env/header dropped on a transport-type switch, and the
-backend rejecting a command whose first token is a URL scheme.
+(create + update), env/header dropped on a transport-type switch, and rejecting
+a command whose first token is a URL scheme.
 
 Run from studio/backend:  python -m pytest tests/test_mcp_stdio_improvements.py -q
 """
@@ -41,7 +41,7 @@ def test_client_refuses_stdio_when_disabled(monkeypatch):
 def test_client_builds_stdio_when_enabled_without_spawning(monkeypatch):
     _enable(monkeypatch)
     # Constructing the Client must not spawn the subprocess (spawn happens on
-    # __aenter__); we only assert it builds.
+    # __aenter__); only assert it builds.
     client = mcp_client._client("npx -y server /tmp", {"K": "v"})
     assert client is not None
 
@@ -122,7 +122,7 @@ def test_switch_stdio_to_http_drops_env(tmp_path, monkeypatch):
             "s1", McpServerUpdate(url = "https://remote/mcp"), current_subject = "u"
         )
     )
-    # the stdio env must NOT survive as HTTP headers on the remote endpoint
+    # stdio env must NOT survive as HTTP headers on the remote endpoint
     assert resp.headers == {}
     assert mcp_servers_db.get_server("s1")["headers_json"] is None
 
@@ -161,7 +161,7 @@ def test_same_transport_edit_keeps_headers(tmp_path, monkeypatch):
         url = "npx server",
         headers_json = '{"API_KEY": "secret"}',
     )
-    # editing only the display name (still stdio) must not wipe env vars
+    # editing only the display name (still stdio) must keep env vars
     resp = asyncio.run(
         routes_mcp.update_mcp_server("s1", McpServerUpdate(display_name = "B"), current_subject = "u")
     )
@@ -183,13 +183,13 @@ def test_validate_url_rejects_url_scheme_command_when_enabled(monkeypatch):
 def test_validate_url_allows_url_in_argument(monkeypatch):
     from routes.mcp_servers import _validate_url
     _enable(monkeypatch)
-    # :// inside an ARGUMENT (not the first token) is still a valid command
+    # :// inside an ARGUMENT (not the first token) is a valid command
     assert _validate_url("npx server --url https://x/mcp") == ("npx server --url https://x/mcp")
 
 
 # ── P6: Data Recipe stdio path obeys the same host gate ─────────────
-# build_mcp_providers needs the data_designer plugin, which is only installed in
-# the Studio test job; skip there rather than fail the core matrix.
+# build_mcp_providers needs the data_designer plugin, installed only in the
+# Studio test job; skip there rather than fail the core matrix.
 
 _STDIO_RECIPE = {
     "mcp_providers": [
@@ -209,7 +209,7 @@ def test_data_recipe_skips_stdio_when_disabled(monkeypatch):
     _disable(monkeypatch)
     from core.data_recipe.service import build_mcp_providers
 
-    # gate off -> the stdio provider is dropped (no subprocess can be spawned)
+    # gate off -> the stdio provider is dropped (no subprocess spawned)
     assert build_mcp_providers(_STDIO_RECIPE) == []
 
 
diff --git a/studio/backend/tests/test_mcp_stdio_pr5863.py b/studio/backend/tests/test_mcp_stdio_pr5863.py
index 277306836b..d744c07b14 100644
--- a/studio/backend/tests/test_mcp_stdio_pr5863.py
+++ b/studio/backend/tests/test_mcp_stdio_pr5863.py
@@ -2,10 +2,10 @@
 
 Covers the pure helpers (is_stdio / parse_stdio_command / stdio_mcp_enabled /
 probe_timeout), the route-level _validate_url gate, and - most importantly -
-that the UNSLOTH_STUDIO_ALLOW_STDIO_MCP gate blocks the stdio transport at all
-five enforcement points (create, update, test, refresh, discovery, execute)
-when disabled, and reaches it when enabled. The transport (_client) is stubbed
-so no real subprocess is spawned; a recorder asserts whether it was reached.
+that the UNSLOTH_STUDIO_ALLOW_STDIO_MCP gate blocks the stdio transport at
+every enforcement point (create, update, test, refresh, discovery, execute)
+when disabled and reaches it when enabled. The transport (_client) is stubbed
+so no real subprocess spawns; a recorder asserts whether it was reached.
 
 Run from studio/backend:  python -m pytest tests/test_mcp_stdio_pr5863.py -q
 """
@@ -57,7 +57,7 @@ class _FakeResult:
 
 
 class _RecordingClient:
-    """Stands in for fastmcp.Client; records that the transport was opened."""
+    """Stand-in for fastmcp.Client; records that the transport was opened."""
 
     def __init__(self, url, headers, use_oauth, recorder):
         recorder.append({"url": url, "headers": headers, "use_oauth": use_oauth})
@@ -78,7 +78,7 @@ class _RecordingClient:
 @pytest.fixture
 def transport(monkeypatch):
     """Patch mcp_client._client with a recorder. Returns the recorder list;
-    empty == the stdio transport was never reached."""
+    empty == stdio transport never reached."""
     recorder = []
     monkeypatch.setattr(
         mcp_client,
@@ -156,8 +156,8 @@ def test_parse_unclosed_quote_raises_valueerror():
 
 
 def test_parse_windows_strips_wrapping_quotes(monkeypatch):
-    # gemini "medium": posix=False keeps backslash paths but also the wrapping
-    # quotes; the PR strips a matched pair so argv[0] reaches the OS clean.
+    # gemini "medium": posix=False keeps backslash paths but also the
+    # wrapping quotes; the PR strips a matched pair so argv[0] is clean.
     monkeypatch.setattr(sys, "platform", "win32")
     parts = mcp_client.parse_stdio_command(r'"C:\Program Files\node\node.exe" server.js')
     assert parts[0] == r"C:\Program Files\node\node.exe"
@@ -214,8 +214,8 @@ def test_validate_url_gate_off_rejects_stdio(monkeypatch):
 
 
 def test_validate_url_gate_off_message_depends_on_whitespace(monkeypatch):
-    # The message names a command only when the value has whitespace, and never
-    # says "desktop app only" (self-hosted hosts can opt in via the env var).
+    # The message names a command only when the value has whitespace, and
+    # never says "desktop app only" (self-hosted can opt in via the env var).
     _disable(monkeypatch)
     from routes.mcp_servers import _validate_url
 
@@ -242,8 +242,8 @@ def test_validate_url_gate_on_accepts_stdio(monkeypatch):
     assert _validate_url("https://x/mcp") == "https://x/mcp"
     # url-bearing argument accepted as a command
     assert _validate_url("npx server --url https://x/mcp") == ("npx server --url https://x/mcp")
-    # A lone token is ambiguous; keep the prior behaviour and accept it as a
-    # command rather than guessing it's a URL (no regression for single binaries).
+    # A lone token is ambiguous; accept it as a command rather than
+    # guessing it's a URL (no regression for single binaries).
     assert _validate_url("/usr/local/bin/my-mcp-server") == "/usr/local/bin/my-mcp-server"
     assert _validate_url("mcp-server-sqlite") == "mcp-server-sqlite"
     # empty / unparseable still rejected
@@ -284,7 +284,7 @@ def test_update_http_to_stdio_blocked_when_off(tmp_path, monkeypatch):
     _reset_db(tmp_path, monkeypatch)
     _disable(monkeypatch)
     mcp_servers_db.create_server(id = "s1", display_name = "A", url = "https://a/mcp")
-    # editing url -> stdio command must 400 (http->stdio edit bypass closed)
+    # editing url -> stdio command must 400 (http->stdio bypass closed)
     with pytest.raises(HTTPException) as exc:
         asyncio.run(
             routes_mcp.update_mcp_server(
@@ -321,7 +321,7 @@ def test_refresh_route_gate(tmp_path, monkeypatch, transport):
     import routes.mcp_servers as routes_mcp
 
     _reset_db(tmp_path, monkeypatch)
-    # a stdio row as if carried over from a desktop DB
+    # a stdio row, as if carried over from a desktop DB
     mcp_servers_db.create_server(id = "stdio1", display_name = "FS", url = "npx server")
 
     _disable(monkeypatch)
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 2d6efa9f8b..2ff7acfbd0 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -109,8 +109,8 @@ class TestMaxBodyMiddleware:
         assert "too large" in r.json()["detail"].lower()
 
     def test_chunked_upload_over_cap_rejected(self, main_module):
-        # Regression: declared-Content-Length-only check could be bypassed
-        # by chunked transfer-encoding.
+        # Regression: declared-Content-Length-only check could be bypassed by
+        # chunked transfer-encoding.
         app = _make_protected_app(1024, main_module)
         c = TestClient(app)
 
@@ -282,13 +282,13 @@ class TestSecurityHeadersMiddleware:
 
     def test_img_src_allows_google_favicons(self, main_module):
         # sources.tsx fetches https://www.google.com/s2/favicons?... ; without
-        # this allowlist entry citation favicons fall back to gray initials.
+        # this allowlist entry, citation favicons fall back to gray initials.
         csp = main_module._build_csp()
         img_directive = next(
             chunk.strip() for chunk in csp.split(";") if chunk.strip().startswith("img-src ")
         )
-        # Tokenise and compare with `==` so CodeQL's URL-substring rule does
-        # not read directive-string `in` membership as URL sanitisation.
+        # Tokenise and compare with `==` so CodeQL's URL-substring rule
+        # doesn't read directive-string `in` membership as URL sanitisation.
         img_sources = img_directive.split()
         assert any(src == "https://www.google.com" for src in img_sources)
         # Pre-existing favicon CDNs stay allowed.
@@ -332,9 +332,9 @@ def health_app(tmp_path, monkeypatch):
 
 
 class TestHealthAuthGate:
-    # Launcher / frontend bootstrap fields are available unauth so the Tauri
-    # watchdog can re-adopt a sibling backend and the SPA can detect chat-only
-    # mode before any token exists. Version / device_type still require a bearer.
+    # Launcher / frontend bootstrap fields are unauth so the Tauri watchdog can
+    # re-adopt a sibling backend and the SPA can detect chat-only mode before
+    # any token exists. Version / device_type still require a bearer.
     LAUNCHER_BITS = (
         "service",
         "studio_root_id",
@@ -361,7 +361,7 @@ class TestHealthAuthGate:
             assert forbidden not in body
 
     def test_invalid_bearer_returns_launcher_bits_only(self, health_app):
-        # Regression: calling the async dep without await made any Bearer header pass.
+        # Regression: calling the async dep without await let any Bearer header pass.
         c = TestClient(health_app)
         r = c.get(
             "/api/health",
diff --git a/studio/backend/tests/test_mlx_inference_backend.py b/studio/backend/tests/test_mlx_inference_backend.py
index 49afab048d..9871965ce8 100644
--- a/studio/backend/tests/test_mlx_inference_backend.py
+++ b/studio/backend/tests/test_mlx_inference_backend.py
@@ -159,10 +159,9 @@ def test_mlx_inference_vlm_lora_uses_unsloth_loader_without_native_adapter_rewri
     assert isinstance(backend._tokenizer, _DummyTokenizer)
 
 
-# Regression: MLXInferenceBackend.generate_chat_response must accept the
-# four template kwargs (tools / enable_thinking / reasoning_effort /
-# preserve_thinking) so the route layer can forward what the user
-# toggled in the UI. The previous signature raised
+# Regression: generate_chat_response must accept the four template kwargs
+# (tools / enable_thinking / reasoning_effort / preserve_thinking) so the route
+# layer can forward UI toggles. The old signature raised
 # "got an unexpected keyword argument 'tools'" on Mac.
 
 
@@ -184,8 +183,8 @@ def test_mlx_generate_chat_response_accepts_template_kwargs():
 
 
 def test_mlx_generate_text_forwards_kwargs_into_template_helper(monkeypatch):
-    """The Mac text path must route through apply_chat_template_for_
-    generation so reasoning / tool kwargs reach the tokenizer."""
+    """Mac text path must route through apply_chat_template_for_generation so
+    reasoning / tool kwargs reach the tokenizer."""
     _install_fake_mlx(monkeypatch)
     from core.inference.mlx_inference import MLXInferenceBackend
 
@@ -203,9 +202,8 @@ def test_mlx_generate_text_forwards_kwargs_into_template_helper(monkeypatch):
         raising = True,
     )
 
-    # mlx_lm.stream_generate yields response objects with .token; make a
-    # one-token generator so _generate_text returns without touching the
-    # real stack.
+    # mlx_lm.stream_generate yields response objects with .token; use a
+    # one-token generator so _generate_text returns without the real stack.
     import types as _types
 
     mlx_lm_pkg = _types.ModuleType("mlx_lm")
@@ -250,7 +248,7 @@ def test_mlx_generate_text_forwards_kwargs_into_template_helper(monkeypatch):
         )
     )
     assert out == ["hi"]
-    # The kwargs the user toggled must reach the chat-template helper.
+    # The toggled kwargs must reach the chat-template helper.
     assert captured["kwargs"]["tools"] == [{"function": {"name": "web_search"}}]
     assert captured["kwargs"]["enable_thinking"] is True
     assert captured["kwargs"]["reasoning_effort"] == "medium"
diff --git a/studio/backend/tests/test_multimodal_document.py b/studio/backend/tests/test_multimodal_document.py
index b2986f2c3a..29926299ce 100644
--- a/studio/backend/tests/test_multimodal_document.py
+++ b/studio/backend/tests/test_multimodal_document.py
@@ -3,17 +3,16 @@
 
 """Tests for PDF / document attachment translation on external providers.
 
-Studio introduces a normalised `input_document` content part on
-ChatCompletionRequest so the frontend doesn't have to know the
-per-provider attachment shape:
+Studio adds a normalised `input_document` content part on
+ChatCompletionRequest so the frontend needn't know the per-provider
+attachment shape:
 
-- Anthropic: translates to `{type:"document", source:{type:"base64"|"url", ...}}`
-- OpenAI Responses: translates to `{type:"input_file", file_data|file_url, filename?}`
+- Anthropic: `{type:"document", source:{type:"base64"|"url", ...}}`
+- OpenAI Responses: `{type:"input_file", file_data|file_url, filename?}`
 
-These tests pin the translation shape on both paths for base64 data
-URIs and remote URLs, with optional filename metadata, and confirm
-unknown / empty document parts are dropped without breaking the
-request.
+Pins the translation shape on both paths for base64 data URIs and remote
+URLs (with optional filename), and confirms unknown / empty document
+parts are dropped without breaking the request.
 """
 
 import asyncio
@@ -87,9 +86,8 @@ _PDF_DATA_URI = f"data:application/pdf;base64,{_TINY_PDF_B64}"
 
 def _strip_cache(p: dict) -> dict:
     # Studio's prompt-cache wiring attaches cache_control:{type:ephemeral}
-    # to the tail block of the last user message; strip it before
-    # comparing the document core fields so this test stays focused
-    # on the translation, not the caching layer.
+    # to the tail block of the last user message; strip it so this test
+    # focuses on translation, not the caching layer.
     return {k: v for k, v in p.items() if k != "cache_control"}
 
 
@@ -117,7 +115,7 @@ def test_anthropic_base64_pdf_becomes_document_block(monkeypatch):
     types = [p.get("type") for p in parts]
     assert "document" in types, parts
     doc = _strip_cache(next(p for p in parts if p.get("type") == "document"))
-    # citations: {enabled: true} opts into Anthropic's natural-citation
+    # citations:{enabled:true} opts into Anthropic's natural-citation
     # pipeline; without it the citations_delta handler is a no-op.
     assert doc == {
         "type": "document",
@@ -179,9 +177,9 @@ def test_anthropic_empty_document_part_is_dropped(monkeypatch):
 
 
 def test_anthropic_empty_only_document_drops_whole_message(monkeypatch):
-    # If the ONLY part in a user message is an unparseable input_document,
-    # the helper must NOT append an empty-content message to the outbound
-    # body (Anthropic 400s on "at least one block is required").
+    # If the ONLY part is an unparseable input_document, the helper must
+    # NOT append an empty-content message (Anthropic 400s on "at least
+    # one block is required").
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -192,14 +190,14 @@ def test_anthropic_empty_only_document_drops_whole_message(monkeypatch):
         ],
     )
     msgs = captured["body"]["messages"]
-    # The empty-content message must be skipped; only the second remains.
+    # Empty-content message skipped; only the second remains.
     assert len(msgs) == 1, msgs
 
 
 def test_anthropic_empty_data_uri_payload_is_dropped(monkeypatch):
-    # Codex P2: `data:application/pdf;base64,` with no payload (or
-    # whitespace-only) would create an empty `source.data` that
-    # Anthropic 400s on. Must be filtered before the wire.
+    # Codex P2: `data:application/pdf;base64,` with no (or whitespace-only)
+    # payload would make an empty `source.data` that Anthropic 400s on.
+    # Must be filtered before the wire.
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -228,12 +226,11 @@ def test_anthropic_empty_data_uri_payload_is_dropped(monkeypatch):
 
 
 def test_anthropic_empty_data_uri_falls_back_to_file_url(monkeypatch):
-    # Codex P2 follow-up: my previous fix added the empty-data-URI ->
-    # file_url fallback to the OpenAI side but missed the Anthropic
-    # side, where the empty-payload branch did `continue` and discarded
-    # an otherwise-valid file_url on the same part. Mirror the OpenAI
-    # behavior so a malformed inline payload + remote URL still
-    # attaches.
+    # Codex P2 follow-up: the empty-data-URI -> file_url fallback was on
+    # the OpenAI side but missing on Anthropic, where the empty-payload
+    # branch did `continue` and discarded a valid file_url on the same
+    # part. Mirror OpenAI so a malformed inline payload + remote URL
+    # still attaches.
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -255,7 +252,7 @@ def test_anthropic_empty_data_uri_falls_back_to_file_url(monkeypatch):
     )
     parts = captured["body"]["messages"][0]["content"]
     doc = _strip_cache(next(p for p in parts if p.get("type") == "document"))
-    # base64 source MUST NOT have landed on the wire; URL source survived.
+    # base64 source MUST NOT reach the wire; URL source survives.
     assert doc == {
         "type": "document",
         "source": {"type": "url", "url": "https://example.com/doc.pdf"},
@@ -344,11 +341,10 @@ def test_openai_url_pdf_becomes_input_file(monkeypatch):
 
 
 def test_openai_empty_data_uri_falls_back_to_file_url(monkeypatch):
-    # Codex P2 follow-up: an empty `data:application/pdf;base64,`
-    # payload was being preferred over a perfectly valid `file_url`
-    # in the same part, sending `file_data=""` to OpenAI and 400ing
-    # the whole turn. The translator must treat empty data URIs as
-    # missing and recover via file_url.
+    # Codex P2 follow-up: an empty `data:application/pdf;base64,` payload
+    # was preferred over a valid `file_url` in the same part, sending
+    # `file_data=""` and 400ing the turn. The translator must treat empty
+    # data URIs as missing and recover via file_url.
     captured = _capture(
         monkeypatch,
         provider = "openai",
@@ -370,7 +366,7 @@ def test_openai_empty_data_uri_falls_back_to_file_url(monkeypatch):
     )
     parts = captured["body"]["input"][0]["content"]
     fileblk = next(p for p in parts if p.get("type") == "input_file")
-    # file_data MUST NOT be on the wire; file_url survives.
+    # file_data MUST NOT reach the wire; file_url survives.
     assert "file_data" not in fileblk, fileblk
     assert fileblk["file_url"] == "https://example.com/doc.pdf"
     assert fileblk["filename"] == "doc.pdf"
@@ -402,8 +398,8 @@ def test_openai_whitespace_only_data_uri_falls_back_to_file_url(monkeypatch):
 
 
 def test_openai_empty_data_uri_without_fallback_is_dropped(monkeypatch):
-    # If the only signal is an empty data URI (no file_url), the
-    # whole part is skipped rather than sent as `file_data=""`.
+    # Only signal is an empty data URI (no file_url): skip the whole part
+    # rather than send `file_data=""`.
     captured = _capture(
         monkeypatch,
         provider = "openai",
@@ -449,12 +445,11 @@ def test_openai_empty_document_part_is_dropped(monkeypatch):
 
 # ── Pydantic schema + builder pass-through ──────────────────────────
 #
-# The translation tests above call the external-provider client directly
-# with hand-built dicts, which bypasses BOTH ChatCompletionRequest's
-# discriminated Union AND routes/inference._build_external_messages. The
-# tests below close that gap: parse an input_document part through the
-# real request schema, run the builder, and assert the part survives to
-# the dict the client would receive.
+# The translation tests above call the client directly with hand-built
+# dicts, bypassing both ChatCompletionRequest's discriminated Union and
+# routes/inference._build_external_messages. The tests below close that
+# gap: parse an input_document part through the real schema, run the
+# builder, and assert the part survives to the dict the client receives.
 
 
 def test_chat_message_accepts_input_document_part():
@@ -482,10 +477,9 @@ def test_chat_message_accepts_input_document_part():
 
 
 def test_build_external_messages_passes_input_document_for_anthropic_and_openai():
-    # Both providers' stream helpers have explicit input_document
-    # translation logic (Anthropic -> {type:"document"}, OpenAI
-    # Responses -> {type:"input_file"}), so the part round-trips
-    # through the builder unchanged on those routes.
+    # Both providers' stream helpers translate input_document (Anthropic ->
+    # {type:"document"}, OpenAI Responses -> {type:"input_file"}), so the
+    # part round-trips through the builder unchanged on those routes.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -518,10 +512,10 @@ def test_build_external_messages_passes_input_document_for_anthropic_and_openai(
 
 def test_build_external_messages_strips_input_document_for_unmapped_providers():
     # Codex P1 follow-up: gemini / mistral / kimi / openrouter / deepseek
-    # / custom go through generic /chat/completions passthrough that
-    # forwards `messages` verbatim. Handing them an `input_document`
-    # part fails the upstream validator. Builder must strip the part
-    # for every provider whose stream helper doesn't translate it.
+    # / custom use generic /chat/completions passthrough that forwards
+    # `messages` verbatim, so an `input_document` part fails the upstream
+    # validator. The builder must strip it for any provider whose stream
+    # helper doesn't translate it.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -551,8 +545,8 @@ def test_build_external_messages_strips_input_document_for_unmapped_providers():
 
 
 def test_build_external_messages_strips_input_document_when_provider_type_unknown():
-    # Defensive: legacy callers that don't pass provider_type must
-    # not leak the part to an unknown destination.
+    # Defensive: legacy callers without provider_type must not leak the
+    # part to an unknown destination.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
diff --git a/studio/backend/tests/test_native_context_length.py b/studio/backend/tests/test_native_context_length.py
index 01c05d3ec6..0290bb1308 100644
--- a/studio/backend/tests/test_native_context_length.py
+++ b/studio/backend/tests/test_native_context_length.py
@@ -3,11 +3,11 @@
 
 """Tests for the native_context_length feature (PR #4746).
 
-Verifies that the new `native_context_length` property on LlamaCppBackend
-and the corresponding Pydantic model fields work correctly.  The raw GGUF
-`_context_length` must never be overwritten by VRAM-capping logic.
+Verifies the `native_context_length` property on LlamaCppBackend and the
+matching Pydantic fields. The raw GGUF `_context_length` must never be
+overwritten by VRAM-capping logic.
 
-Requires no GPU, network, or external libraries beyond pytest and pydantic.
+Needs no GPU, network, or libraries beyond pytest and pydantic.
 """
 
 import io
@@ -21,8 +21,8 @@ from unittest.mock import patch
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable external dependencies before importing the
-# module under test.  Same pattern as test_kv_cache_estimation.py.
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_kv_cache_estimation.py.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
@@ -38,7 +38,7 @@ sys.modules.setdefault("loggers", _loggers_stub)
 _structlog_stub = _types.ModuleType("structlog")
 sys.modules.setdefault("structlog", _structlog_stub)
 
-# httpx -- stub only the names referenced at import / class-definition time
+# httpx -- stub only names referenced at import / class-definition time
 _httpx_stub = _types.ModuleType("httpx")
 for _exc_name in (
     "ConnectError",
@@ -227,7 +227,7 @@ class TestContextValueSeparation:
     def test_all_equal_when_uncapped(self, backend):
         """All three equal when no VRAM constraint."""
         backend._context_length = 8192
-        # No effective or max set -- properties fall back to _context_length
+        # No effective/max set -- properties fall back to _context_length.
         assert backend.native_context_length == 8192
         assert backend.max_context_length == 8192
         assert backend.context_length == 8192
@@ -241,16 +241,16 @@ class TestContextValueSeparation:
         backend._embedding_length = 4096
         original = backend._context_length
 
-        # Simulate a very small VRAM budget that forces capping
+        # Tiny VRAM budget forces capping.
         result = backend._fit_context_to_vram(
             requested_ctx = 131072,
             available_mib = 512,  # very small
             model_size_bytes = 0,
         )
-        # _fit_context_to_vram returns the capped value, not modifying _context_length
+        # Returns the capped value without modifying _context_length.
         assert backend._context_length == original
         assert backend.native_context_length == original
-        # The returned capped value should be <= requested
+        # Capped value must be <= requested.
         assert result <= 131072
 
     def test_native_gt_context_when_capped(self, backend):
@@ -370,7 +370,7 @@ class TestRouteCompleteness:
             start = self._source.find(f"{class_name}(", idx)
             if start == -1:
                 break
-            # Find matching closing paren (simple depth counter)
+            # Find the matching closing paren via a depth counter.
             depth = 0
             end = start
             for i, ch in enumerate(self._source[start:], start):
@@ -401,8 +401,8 @@ class TestRouteCompleteness:
         """Non-GGUF LoadResponse blocks do not set native_context_length (defaults to None)."""
         blocks = self._find_construction_blocks("LoadResponse")
         non_gguf = [b for b in blocks if "is_gguf = True" not in b and "is_gguf=True" not in b]
-        # Non-GGUF paths should not reference native_context_length
-        # (Pydantic defaults it to None, so not setting it is correct)
+        # Non-GGUF paths shouldn't reference native_context_length
+        # (Pydantic defaults it to None, so omitting it is correct).
         for block in non_gguf:
             assert (
                 "native_context_length" not in block
@@ -476,7 +476,7 @@ class TestNativeContextEdgeCases:
         backend._read_gguf_metadata(path)
         assert backend.native_context_length == 131072
 
-        # Simulate VRAM capping by setting effective and max
+        # Simulate VRAM capping via effective and max.
         backend._effective_context_length = 16384
         backend._max_context_length = 32768
         assert backend.native_context_length == 131072
diff --git a/studio/backend/tests/test_offline_gguf_cache_fallback.py b/studio/backend/tests/test_offline_gguf_cache_fallback.py
index df7652a590..2856bb7cad 100644
--- a/studio/backend/tests/test_offline_gguf_cache_fallback.py
+++ b/studio/backend/tests/test_offline_gguf_cache_fallback.py
@@ -3,27 +3,25 @@
 
 """Regression tests for the offline GGUF cache fallback path (#5505).
 
-Three failure modes hit users when ``huggingface.co`` is unreachable
-but the requested GGUF repo is fully cached locally:
+Three failure modes hit users when ``huggingface.co`` is unreachable but the
+requested GGUF repo is fully cached locally:
 
-* ``list_gguf_variants`` raised through ``HTTPException(500)`` so the
-  variant dropdown sat empty.
-* ``detect_gguf_model_remote`` returned ``None`` so a GGUF-only repo
-  was misrouted into the transformers/Unsloth backend (on macOS this
-  surfaced as a hardware error).
-* ``_download_gguf`` fell back to a synthetic ``{repo}-{variant}.gguf``
-  name that did not exist in cache when the in-repo filename did not
-  echo the repo name (e.g. ``unsloth/Qwen3.6-27B-MTP-GGUF`` ships
+* ``list_gguf_variants`` raised ``HTTPException(500)`` so the variant
+  dropdown sat empty.
+* ``detect_gguf_model_remote`` returned ``None`` so a GGUF-only repo was
+  misrouted into the transformers/Unsloth backend (a hardware error on macOS).
+* ``_download_gguf`` fell back to a synthetic ``{repo}-{variant}.gguf`` name
+  absent from cache when the in-repo filename did not echo the repo name
+  (e.g. ``unsloth/Qwen3.6-27B-MTP-GGUF`` ships
   ``Qwen3.6-27B-UD-Q4_K_XL.gguf`` with no ``MTP`` token).
 
-Two follow-up regressions covered here:
+Two follow-up regressions also covered:
 
-* P1 #1: the cache-side variant filter must match the snapshot-relative
-  path, not just the basename, so subdir layouts like
-  ``BF16/foo.gguf`` are findable.
-* P1 #2: the DNS auto-detect must scope ``HF_HUB_OFFLINE`` to one load
-  via try/finally so a transient resolver hiccup cannot lock the
-  long-lived ``LlamaCppBackend`` singleton offline forever.
+* P1 #1: the cache-side variant filter must match the snapshot-relative path,
+  not just the basename, so subdir layouts like ``BF16/foo.gguf`` are findable.
+* P1 #2: the DNS auto-detect must scope ``HF_HUB_OFFLINE`` to one load via
+  try/finally so a transient resolver hiccup cannot lock the long-lived
+  ``LlamaCppBackend`` singleton offline forever.
 
 No GPU, no network, no subprocess. Linux, macOS, Windows compatible.
 """
@@ -44,8 +42,8 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Stub heavy/unavailable external deps before importing the modules
-# under test (same pattern as other studio backend tests).
+# Stub heavy/unavailable external deps before importing the modules under
+# test (same pattern as other studio backend tests).
 _loggers_stub = _types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
@@ -182,7 +180,7 @@ class TestIterHfCacheSnapshots:
 
     def test_repo_id_match_is_case_insensitive(self, hf_cache):
         _build_cache(hf_cache, "unsloth/Foo-GGUF", {"Foo-Q4_K_M.gguf": 1})
-        # Lookup with a different casing of the org/name still resolves
+        # Lookup with different org/name casing still resolves
         out = list(_iter_hf_cache_snapshots("UNSLOTH/foo-gguf"))
         assert len(out) == 1
 
@@ -272,9 +270,9 @@ class TestDetectGgufFromCache:
 
     def test_subdir_only_quant_resolves(self, hf_cache):
         """P1 #1 regression: ``BF16/foo.gguf`` (quant only in directory).
-        Before the fix, the offline cache scan matched on basename and
-        missed this layout, falling through to the synthetic
-        ``{repo}-{variant}.gguf`` heuristic."""
+        The pre-fix cache scan matched on basename, missing this layout
+        and falling through to the synthetic ``{repo}-{variant}.gguf``
+        heuristic."""
         _build_cache(
             hf_cache,
             "unsloth/gpt-oss-20b-BF16",
@@ -316,7 +314,7 @@ class TestDetectGgufModelRemoteOffline:
         assert out == "a-Q4_K_M.gguf"
 
     def test_repository_not_found_does_not_consult_cache(self, hf_cache, clean_offline_env):
-        # Cache has a file but the API explicitly says repo is gone.
+        # Cache has a file but the API says the repo is gone.
         _build_cache(hf_cache, "unsloth/a", {"a-Q4_K_M.gguf": 1})
 
         class RepositoryNotFoundError(Exception):
@@ -442,9 +440,9 @@ class TestHfOfflineIfDnsDead:
 
 
 class TestExtractQuantLabelSubdir:
-    """``_extract_quant_label`` must consider the parent directories when
-    the basename has no quant token. Subdir layouts like ``BF16/foo.gguf``
-    are documented in this codebase and surface through the cache scan."""
+    """``_extract_quant_label`` must consider parent directories when the
+    basename has no quant token. Subdir layouts like ``BF16/foo.gguf`` are
+    documented here and surface through the cache scan."""
 
     def test_quant_in_basename_unchanged(self):
         assert _extract_quant_label("BF16/foo-BF16.gguf") == "BF16"
@@ -457,17 +455,15 @@ class TestExtractQuantLabelSubdir:
         assert _extract_quant_label("UD-Q4_K_XL/weight.gguf") == "UD-Q4_K_XL"
 
     def test_deeper_nesting_picks_nearest_quant_dir(self):
-        # When multiple parent segments could match, prefer the one closest
-        # to the file (innermost). This matches how repos like
-        # ``models/MXFP4_MOE/foo.gguf`` are laid out.
+        # When multiple parent segments match, prefer the innermost (closest
+        # to the file), matching repos like ``models/MXFP4_MOE/foo.gguf``.
         assert _extract_quant_label("models/MXFP4_MOE/foo.gguf") == "MXFP4_MOE"
 
 
 class TestDownloadMmprojOfflineCacheFallback:
-    """``LlamaCppBackend._download_mmproj`` must resolve cached mmproj
-    GGUFs offline, same shape as ``_download_gguf``. Without this the
-    offline vision GGUF load path returns ``None`` even when the mmproj
-    is present in cache."""
+    """``LlamaCppBackend._download_mmproj`` must resolve cached mmproj GGUFs
+    offline, same shape as ``_download_gguf``. Without this the offline vision
+    GGUF load path returns ``None`` even when the mmproj is cached."""
 
     def test_cache_lookup_returns_cached_mmproj_when_list_repo_files_fails(self, hf_cache):
         _build_cache(
@@ -559,7 +555,7 @@ class TestDownloadMmprojOfflineCacheFallback:
 
 class TestListLocalGgufVariantsSubdir:
     """Subdir layouts like ``BF16/foo.gguf`` and ``Q4_K_M/foo.gguf`` must
-    produce distinct quant labels, not collapse on basename."""
+    yield distinct quant labels, not collapse on basename."""
 
     def test_two_subdir_variants_do_not_collapse(self, tmp_path):
         from utils.models.model_config import list_local_gguf_variants
@@ -642,8 +638,8 @@ class TestListGgufVariantsPermanentErrors:
 
 
 class TestDetectGgufFromCacheExcludesMmproj:
-    """A partial cache with only a vision projector must not route the
-    projector as the main model."""
+    """A partial cache with only a vision projector must not route it as
+    the main model."""
 
     def test_mmproj_only_returns_none(self, hf_cache):
         from utils.models.model_config import _detect_gguf_from_hf_cache
@@ -672,7 +668,7 @@ class TestDetectGgufFromCacheExcludesMmproj:
 
 class TestProbeDnsDeadNoGlobalTimeoutMutation:
     """``_probe_dns_dead`` must not change ``socket.setdefaulttimeout``
-    process-wide -- concurrent sockets without explicit timeout would
+    process-wide -- concurrent sockets without an explicit timeout would
     inherit it for the probe window."""
 
     def test_default_timeout_unchanged_when_dns_up(self, monkeypatch):
@@ -694,7 +690,7 @@ class TestProbeDnsDeadNoGlobalTimeoutMutation:
         try:
             _probe_dns_dead("example.invalid", timeout = 0.5)
         finally:
-            # Restore exact state regardless of any test-side mutation.
+            # Restore exact state regardless of test-side mutation.
             original_set(prev)
 
         assert set_calls == [], (
@@ -717,8 +713,8 @@ class TestProbeDnsDeadNoGlobalTimeoutMutation:
 
 class TestWaitForHealthRetriesOnReadError:
     """A TCP RST mid-read while llama-server is still binding the port
-    (Windows: WinError 10054) must not abort the health-poll loop --
-    that masks a legitimate 'still warming up' state as a fatal load."""
+    (Windows: WinError 10054) must not abort the health-poll loop -- that
+    masks a legitimate 'still warming up' state as a fatal load."""
 
     def test_read_error_then_success(self, monkeypatch):
         import httpx
diff --git a/studio/backend/tests/test_offline_inference_parent.py b/studio/backend/tests/test_offline_inference_parent.py
index fbb0aa8999..71331220d6 100644
--- a/studio/backend/tests/test_offline_inference_parent.py
+++ b/studio/backend/tests/test_offline_inference_parent.py
@@ -140,7 +140,7 @@ class TestLoraDetectOffline:
         monkeypatch.setenv("HF_HUB_OFFLINE", "1")
 
         # Studio catches Exception broadly; pin that the call still happens
-        # (so cached LoRAs aren't missed) and returns fast via mock.
+        # (so cached LoRAs aren't missed) and returns fast via the mock.
         class _OfflineModeIsEnabled(Exception):
             pass
 
diff --git a/studio/backend/tests/test_openai_citation_markers.py b/studio/backend/tests/test_openai_citation_markers.py
index ccc17be329..dafcffc8bd 100644
--- a/studio/backend/tests/test_openai_citation_markers.py
+++ b/studio/backend/tests/test_openai_citation_markers.py
@@ -4,8 +4,8 @@
 """Tests for the OpenAI Responses-API citation marker rewriter.
 
 The stream interleaves text deltas with ``\\ue200cite\\ue202SOURCE_ID\\ue201``
-markers. The rewriter resolves each to `[N](URL)` when the annotation has
-arrived and drops it otherwise; the URL list still flows to Sources via
+markers. The rewriter resolves each to `[N](URL)` once the annotation arrives
+and drops it otherwise; the URL list still flows to Sources via
 `_record_url_citation`.
 
 Reference: https://developers.openai.com/api/docs/guides/citation-formatting
@@ -58,8 +58,7 @@ def test_marker_rewritten_to_link_when_annotation_known():
 def test_unknown_source_marker_dropped_silently():
     text = f"Foo {_marker('turn9view9')} bar."
     out = _replace_openai_citation_markers(text, [])
-    # Marker stripped, no garbled "E202" glyph leaks through, and the
-    # surrounding text stays intact.
+    # Marker stripped, no garbled "E202" glyph leaks, surrounding text intact.
     assert not _has_marker_codepoints(out)
     assert "E202" not in out
     assert "turn9view9" not in out
@@ -67,8 +66,8 @@ def test_unknown_source_marker_dropped_silently():
 
 
 def test_multiple_concatenated_markers_resolved_in_order():
-    """Real-world wire shape: a string of markers butted up against each other
-    after a sentence, as in the user-reported bug."""
+    """Real-world wire shape: markers butted together after a sentence,
+    as in the user-reported bug."""
     markers = "".join(_marker(f"turn{i}view{j}") for i, j in [(1, 0), (1, 1), (3, 0)])
     text = f"All animals ranked. {markers}"
     citations = [
@@ -150,8 +149,8 @@ def test_multiple_source_id_aliases_resolve_to_same_url():
         },
     ]
     out = _replace_openai_citation_markers(text, citations)
-    # All three aliases collapse onto citation [1] -- the URL is the
-    # same so it would be misleading to show three different numbers.
+    # All three aliases collapse onto citation [1] -- same URL, so showing
+    # three different numbers would mislead.
     assert out.count("[[1]](https://example.com/paris)") == 3
     assert not _has_marker_codepoints(out)
 
@@ -176,7 +175,7 @@ def test_source_ids_list_and_legacy_source_id_both_resolve():
 
 # ---------------------------------------------------------------------------
 # _rewrite_citation_markers_partial: deferred-annotation tests. OpenAI emits
-# url_citation annotations on a subsequent SSE event; this helper reports
+# url_citation annotations on a later SSE event; this helper reports
 # `has_unresolved` so the stream loop defers emission. See PR #5713 audit.
 # ---------------------------------------------------------------------------
 
@@ -216,15 +215,15 @@ def test_partial_resolves_after_late_annotation():
 def test_partial_multi_source_partial_resolution_keeps_marker_pending():
     """Any unresolved token in a multi-source marker leaves the whole marker
     verbatim with ``unresolved`` True; defer until every id resolves or
-    end-of-stream forces a flush (dropping unresolved tokens then)."""
+    end-of-stream forces a flush (dropping unresolved tokens)."""
     cite = f"{CITE_START}cite{CITE_DELIM}known{CITE_DELIM}locator{CITE_STOP}"
     text = f"Pre {cite} post."
     citations = [{"source_id": "known", "url": "https://example.com/y"}]
     out, unresolved = _rewrite_citation_markers_partial(text, citations)
     assert unresolved is True
     assert cite in out
-    # End-of-stream force flush: drop the unresolved token, keep the
-    # resolved link. The streamer routes pending segments through
+    # End-of-stream force flush: drop the unresolved token, keep the resolved
+    # link. The streamer routes pending segments through
     # `_replace_openai_citation_markers` at force=True for this.
     forced = _replace_openai_citation_markers(out, citations)
     assert "[[1]](https://example.com/y)" in forced
diff --git a/studio/backend/tests/test_openai_citation_markers_edge.py b/studio/backend/tests/test_openai_citation_markers_edge.py
index e8d0be6246..f44975ce33 100644
--- a/studio/backend/tests/test_openai_citation_markers_edge.py
+++ b/studio/backend/tests/test_openai_citation_markers_edge.py
@@ -13,8 +13,8 @@ Reference: https://developers.openai.com/api/docs/guides/citation-formatting
 import importlib
 
 
-# Streaming integration is exercised by ``_simulate_delta_stream`` further
-# down, mirroring the head/buffer/flush dance from ``_stream_openai_responses``.
+# Streaming is exercised by ``_simulate_delta_stream`` below, mirroring the
+# head/buffer/flush dance from ``_stream_openai_responses``.
 _module = importlib.import_module("core.inference.external_provider")
 _replace_openai_citation_markers = _module._replace_openai_citation_markers
 _split_pending_citation_tail = _module._split_pending_citation_tail
@@ -27,7 +27,7 @@ CITE_DELIM = ""
 
 def _marker(*source_ids: str, locator: str | None = None) -> str:
     """Build a ``\\ue200cite\\ue202<sid>[\\ue202<sid>...][\\ue202<loc>]\\ue201``
-    marker. Accepts one or many ``source_ids`` plus an optional ``locator``."""
+    marker from one or more ``source_ids`` plus an optional ``locator``."""
     payload = f"{CITE_START}cite{CITE_DELIM}" + CITE_DELIM.join(source_ids)
     if locator:
         payload = f"{payload}{CITE_DELIM}{locator}"
@@ -39,7 +39,7 @@ def _no_private_use(text: str) -> bool:
 
 
 # Harness mirroring the head/pending-tail/flush dance in
-# `_stream_openai_responses`, so streaming tests skip the httpx mock.
+# `_stream_openai_responses` so streaming tests skip the httpx mock.
 def _simulate_delta_stream(
     deltas: list[str],
     citations: list[dict],
@@ -56,8 +56,8 @@ def _simulate_delta_stream(
             if head:
                 emitted.append(head)
     if flush and pending:
-        # Mirror `_flush_pending_marker_tail`: drop the tail entirely if no
-        # closing stop byte arrived; the literal ``cite<sid>`` would leak otherwise.
+        # Mirror `_flush_pending_marker_tail`: drop the tail if no closing stop
+        # byte arrived; the literal ``cite<sid>`` would leak otherwise.
         if CITE_STOP not in pending:
             rendered = ""
         else:
@@ -79,7 +79,7 @@ def _simulate_delta_stream(
 
 def test_multi_source_marker_all_resolve():
     """\\ue200cite\\ue202id1\\ue202id2\\ue202id3\\ue201 expands to three links
-    when every id is known. Earlier regex captured only id1 and dropped id2/id3."""
+    when every id is known. Earlier regex captured only id1."""
     text = f"All three: {_marker('id1', 'id2', 'id3')}"
     citations = [
         {"source_id": "id1", "url": "https://example.com/1"},
@@ -136,14 +136,14 @@ def test_marker_with_range_locator():
 
 
 def test_marker_split_in_source_id():
-    """Delta-1 ends mid-source-id (``\\ue200cite\\ue202tu``), delta-2 starts
-    with the rest (``rn0view0\\ue201``). The buffer stitches the halves
-    back together so they resolve to one link instead of leaking."""
+    """Delta-1 ends mid-source-id (``\\ue200cite\\ue202tu``), delta-2 has the
+    rest (``rn0view0\\ue201``). The buffer stitches the halves so they resolve
+    to one link instead of leaking."""
     full = f"See {_marker('turn0view0')} now."
     # Cut right after the second delim + "tu" inside the source id.
     cut = full.index("tu", full.index(CITE_START)) + len("tu")
     d1, d2 = full[:cut], full[cut:]
-    # Sanity check: delta-1 actually contains a partial marker.
+    # Sanity: delta-1 contains a partial marker.
     assert CITE_START in d1 and CITE_STOP not in d1
     assert CITE_STOP in d2
     citations = [{"source_id": "turn0view0", "url": "https://x"}]
@@ -153,8 +153,8 @@ def test_marker_split_in_source_id():
 
 
 def test_marker_split_at_start_byte():
-    """Split exactly after the opening ``\\ue200`` byte; the buffer must
-    hold the lone open byte until the rest arrives."""
+    """Split right after the opening ``\\ue200`` byte; the buffer must hold the
+    lone open byte until the rest arrives."""
     full = f"Text {_marker('sid')} done"
     cut = full.index(CITE_START) + 1  # right AFTER the open byte
     d1, d2 = full[:cut], full[cut:]
@@ -167,7 +167,7 @@ def test_marker_split_at_start_byte():
 def test_marker_split_across_three_deltas():
     """Worst case: marker chopped into three pieces across three deltas."""
     full = f"A {_marker('threesplit')} B"
-    # cut at two points inside the marker
+    # Cut at two points inside the marker.
     open_pos = full.index(CITE_START)
     stop_pos = full.index(CITE_STOP)
     cut1 = open_pos + 4
@@ -206,21 +206,20 @@ def test_split_marker_unknown_source_is_dropped_cleanly():
 
 
 def test_unterminated_marker_at_stream_end_dropped_on_flush():
-    """Stream ends mid-marker (e.g. response.incomplete); the tail is
-    flushed with private-use bytes stripped, no `E202` text leaks."""
+    """Stream ends mid-marker (e.g. response.incomplete); the flushed tail
+    strips private-use bytes, no `E202` text leaks."""
     deltas = ["Some text ", f"{CITE_START}citetu", "rn0view0"]  # no STOP ever
     out = _simulate_delta_stream(deltas, [], flush = True)
     assert _no_private_use(out)
     assert "E200" not in out and "E202" not in out
-    # Surrounding prose stays; we don't assert exact marker remainder.
+    # Surrounding prose stays; don't assert exact marker remainder.
     assert "Some text " in out
 
 
 def test_flush_resolves_marker_when_late_annotation_arrives():
-    """Marker in a delta, matching annotation arrives later (on
-    response.output_text.annotation.added after the final delta). The
-    rewriter reads ``all_url_citations`` LIVE at flush, so the buffered
-    marker still resolves."""
+    """Marker in a delta; the matching annotation arrives later (on
+    response.output_text.annotation.added after the final delta). The rewriter
+    reads ``all_url_citations`` LIVE at flush, so the buffered marker resolves."""
     deltas = ["Look ", f"{CITE_START}cite{CITE_DELIM}late_sid"]
     pending = ""
     citations: list[dict] = []
@@ -291,8 +290,8 @@ def test_rewriter_idempotent_on_marker_free_text():
 
 
 def test_only_marker_no_surrounding_text():
-    """A delta that is JUST a marker (no prose) still renders correctly;
-    used to leak without the empty-string short-circuit in the split helper."""
+    """A delta that is JUST a marker (no prose) renders correctly; it leaked
+    before the empty-string short-circuit in the split helper."""
     text = _marker("solo")
     citations = [{"source_id": "solo", "url": "https://solo.example"}]
     out = _replace_openai_citation_markers(text, citations)
@@ -311,15 +310,15 @@ def test_back_to_back_markers_with_no_separator():
 
 
 def test_split_helper_buffers_only_after_last_open_byte():
-    """A complete marker followed by an unterminated one: head includes
-    the complete marker, buffer holds only the trailing partial."""
+    """Complete marker followed by an unterminated one: head includes the
+    complete marker, buffer holds only the trailing partial."""
     complete = _marker("done")
     partial = f"{CITE_START}cite{CITE_DELIM}half"  # no STOP
     text = f"pre {complete} mid {partial}"
     head, tail = _split_pending_citation_tail(text)
     assert head == f"pre {complete} mid "
     assert tail == partial
-    # And the head, once rewritten, drops every private-use byte.
+    # Head, once rewritten, drops every private-use byte.
     rewritten = _replace_openai_citation_markers(head, [{"source_id": "done", "url": "https://d"}])
     assert rewritten == "pre [[1]](https://d) mid "
 
@@ -355,7 +354,7 @@ def test_unknown_marker_does_not_perturb_citation_indexing():
         {"source_id": "real_b", "url": "https://example.com/b"},
     ]
     out = _replace_openai_citation_markers(text, citations)
-    # real_a is index 1; unknown does not take a slot.
+    # real_a is index 1; unknown takes no slot.
     assert "[[1]](https://example.com/a)" in out
     assert "[[2]](https://example.com/b)" in out
     assert _no_private_use(out)
@@ -368,8 +367,8 @@ def test_unknown_marker_does_not_perturb_citation_indexing():
 
 
 def test_unterminated_marker_does_not_leak_cite_residue():
-    """Stream ends mid-marker: drop the whole tail rather than strip
-    codepoints and leave ``cite<sid>`` behind."""
+    """Stream ends mid-marker: drop the whole tail rather than strip codepoints
+    and leave ``cite<sid>`` behind."""
     half = f"Hi there {CITE_START}cite{CITE_DELIM}turn0view0"
     out = _simulate_delta_stream([half], [], flush = True)
     # Prose before the marker stays; no private-use bytes or cite residue.
diff --git a/studio/backend/tests/test_openai_code_execution.py b/studio/backend/tests/test_openai_code_execution.py
index d4f814856b..e1b66b4050 100644
--- a/studio/backend/tests/test_openai_code_execution.py
+++ b/studio/backend/tests/test_openai_code_execution.py
@@ -6,23 +6,22 @@ Unit tests for OpenAI's server-side `shell` tool translation in
 `_stream_openai_responses`.
 
 Covers:
-- Request body: ``enabled_tools=["code_execution"]`` on the OpenAI
-  cloud base_url appends ``{"type": "shell", "environment": {"type":
+- Request body: ``enabled_tools=["code_execution"]`` on the OpenAI cloud
+  base_url appends ``{"type": "shell", "environment": {"type":
   "container_auto"}}`` to ``tools``.
-- Container reuse: when ``openai_code_exec_container_id`` is provided,
-  the outgoing ``environment.type`` flips to ``"container_reference"``
-  and the id propagates.
-- Cloud guard: code_execution on a non-cloud base_url (e.g. a local
-  OpenAI-compat preset / ollama / llama.cpp / vLLM) does NOT add the
-  shell tool, preventing a guaranteed 400 from those servers.
+- Container reuse: with ``openai_code_exec_container_id``, the outgoing
+  ``environment.type`` flips to ``"container_reference"`` and the id
+  propagates.
+- Cloud guard: code_execution on a non-cloud base_url (local
+  OpenAI-compat / ollama / llama.cpp / vLLM) does NOT add the shell tool,
+  avoiding a guaranteed 400 from those servers.
 - SSE translation: a `shell_call` + `shell_call_output` pair emits one
   ``_toolEvent`` `tool_start` (`tool_name="code_execution"`,
-  `arguments.kind="bash"`) and one `tool_end` whose `result` contains
-  the joined stdout from the shell_call_output entries.
-- Container surfacing: container_id captured from
+  `arguments.kind="bash"`) and one `tool_end` whose `result` is the
+  joined stdout from the shell_call_output entries.
+- Container surfacing: container_id from
   `response.completed.container_id` is emitted as a synthetic
-  `container_ready` `_toolEvent` (only when it differs from the
-  inbound id).
+  `container_ready` `_toolEvent` (only when it differs from the inbound id).
 - Stale-container handling: 400 with "container expired" body emits a
   `container_invalidated` event before propagating the error.
 """
@@ -192,8 +191,8 @@ def test_shell_tool_refused_for_non_cloud_base_url(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    # Shell tool must NOT leak to local OpenAI-compat servers — those
-    # 400 on the unknown tool type.
+    # Shell tool must NOT leak to local OpenAI-compat servers — they 400
+    # on the unknown tool type.
     assert all(t.get("type") != "shell" for t in tools)
 
 
@@ -266,10 +265,9 @@ def test_shell_call_emits_tool_start_and_end(monkeypatch):
     assert len(ends) == 1
     assert starts[0]["tool_name"] == "code_execution"
     assert starts[0]["tool_call_id"] == "scall_1"
-    # `_server_tool: True` is the synthetic-builtin marker the
-    # backend stamps onto every provider-side tool_start so the
-    # frontend serializer can distinguish hosted tools from
-    # user-declared functions on history replay.
+    # `_server_tool: True` marks a synthetic builtin: stamped onto every
+    # provider-side tool_start so the frontend serializer can tell hosted
+    # tools from user-declared functions on history replay.
     assert starts[0]["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
     assert ends[0]["tool_call_id"] == "scall_1"
     assert "total 24" in ends[0]["result"]
@@ -395,21 +393,21 @@ def test_stale_container_emits_invalidated(monkeypatch):
 def test_expired_container_triggers_transparent_retry(monkeypatch):
     """When OpenAI 400s with 'Container is expired' on a request that
     carried container_reference, the streamer retries once with the
-    container field stripped. The user never sees an error line — only
-    container_invalidated, then the normal stream from the retry.
+    container field stripped. The user sees only container_invalidated,
+    then the normal stream from the retry — never an error line.
     """
     calls: list[dict] = []
 
     def handler(request: httpx.Request) -> httpx.Response:
         body = json.loads(request.content.decode("utf-8"))
         calls.append(body)
-        # Find the shell tool entry to inspect environment.type.
+        # Inspect the shell tool's environment.type.
         shell_env_type = None
         for tool in body.get("tools", []) or []:
             if tool.get("type") == "shell":
                 shell_env_type = tool.get("environment", {}).get("type")
                 break
-        # First call carries container_reference -> 400 expired.
+        # First call has container_reference -> 400 expired.
         # Retry omits container -> normal SSE stream.
         if shell_env_type == "container_reference":
             return httpx.Response(
@@ -424,8 +422,8 @@ def test_expired_container_triggers_transparent_retry(monkeypatch):
                 ).encode("utf-8"),
                 headers = {"content-type": "application/json"},
             )
-        # Successful retry: minimal SSE — a completed response with a
-        # fresh container_id so container_ready latches.
+        # Successful retry: minimal SSE — completed response with a fresh
+        # container_id so container_ready latches.
         sse = _openai_sse(
             [
                 {
@@ -461,8 +459,8 @@ def test_expired_container_triggers_transparent_retry(monkeypatch):
     lines = _drive(run())
     events = _tool_events(lines)
 
-    # Two outbound HTTP calls were made: the expired-container attempt
-    # then the retry without the container field.
+    # Two outbound calls: the expired-container attempt, then the retry
+    # without the container field.
     assert len(calls) == 2
     shell_types = []
     for body in calls:
@@ -471,14 +469,14 @@ def test_expired_container_triggers_transparent_retry(monkeypatch):
                 shell_types.append(tool.get("environment", {}).get("type"))
     assert shell_types == ["container_reference", "container_auto"]
 
-    # container_invalidated emitted (frontend will null its stored id).
+    # container_invalidated emitted (frontend nulls its stored id).
     assert any(e.get("type") == "container_invalidated" for e in events)
     # container_ready emitted from the retry stream with the fresh id.
     assert any(
         e.get("type") == "container_ready" and e.get("container_id") == "cntr_fresh_111"
         for e in events
     )
-    # CRUCIALLY: no SSE error line surfaced to the chat — only completion.
+    # CRUCIALLY: no SSE error line surfaced to the chat.
     error_lines = [
         line
         for line in lines
@@ -488,8 +486,8 @@ def test_expired_container_triggers_transparent_retry(monkeypatch):
 
 
 def test_expired_container_retries_only_once(monkeypatch):
-    """If the retry ALSO fails (any 4xx, expired or otherwise), the
-    error is surfaced normally — no infinite retry loop.
+    """If the retry ALSO fails (any 4xx), the error surfaces normally —
+    no infinite retry loop.
     """
     call_count = {"n": 0}
 
@@ -528,8 +526,7 @@ def test_expired_container_retries_only_once(monkeypatch):
 
     lines = _drive(run())
 
-    # Exactly two calls (first + one retry). Third would mean an
-    # infinite loop.
+    # Exactly two calls (first + one retry); a third would be a loop.
     assert call_count["n"] == 2
     # The second failure surfaces normally as an error SSE line.
     error_lines = [line for line in lines if '"error"' in line and "_toolEvent" not in line]
diff --git a/studio/backend/tests/test_openai_compaction.py b/studio/backend/tests/test_openai_compaction.py
index f0599952c6..c7de0a9aed 100644
--- a/studio/backend/tests/test_openai_compaction.py
+++ b/studio/backend/tests/test_openai_compaction.py
@@ -4,14 +4,13 @@
 """Unit tests for OpenAI Responses API context_management wiring.
 
 OpenAI's Responses API supports server-side compaction via
-``context_management: [{type:"compaction", compact_threshold:N}]``.
-There is no beta header and no dated version pin; the threshold is
-silently accepted and the API runs the compaction step when the
-rendered prompt crosses it.
+``context_management: [{type:"compaction", compact_threshold:N}]``. No
+beta header, no dated version pin; the threshold is silently accepted and
+compaction runs when the rendered prompt crosses it.
 
-These tests pin: the body shape when threshold is set on cloud OpenAI,
-the silent no-op when the base URL is non-cloud, and the
-omitted-threshold pass-through.
+These pin: the body shape when threshold is set on cloud OpenAI, the
+silent no-op on non-cloud base URLs, and the omitted-threshold
+pass-through.
 """
 
 import asyncio
@@ -32,8 +31,7 @@ def _capture(monkeypatch, *, base_url: str, threshold) -> dict:
 
     def handler(request: httpx.Request) -> httpx.Response:
         captured["body"] = json.loads(request.content.decode("utf-8"))
-        # Send an empty Responses-shaped SSE stream so the helper exits
-        # cleanly.
+        # Empty Responses-shaped SSE stream so the helper exits cleanly.
         return httpx.Response(
             200,
             content = (
@@ -88,8 +86,8 @@ def test_cloud_openai_sets_compaction_block(monkeypatch):
 
 
 def test_cloud_openai_below_default_threshold_passes_through(monkeypatch):
-    # Studio doesn't clamp the OpenAI side -- the API accepts whatever
-    # the caller sends, so a small probe like 60k still goes through.
+    # Studio doesn't clamp the OpenAI side -- the API accepts whatever the
+    # caller sends, so a small probe like 60k still goes through.
     captured = _capture(
         monkeypatch,
         base_url = "https://api.openai.com/v1",
@@ -105,8 +103,8 @@ def test_cloud_openai_below_default_threshold_passes_through(monkeypatch):
 
 def test_non_cloud_base_silently_drops_compaction(monkeypatch):
     # ollama / llama.cpp / "custom" presets collapse to provider="openai"
-    # but don't implement context_management. Sending the field would
-    # 400 those servers, so it must NOT appear on the wire.
+    # but lack context_management. Sending the field would 400 them, so it
+    # must NOT appear on the wire.
     captured = _capture(
         monkeypatch,
         base_url = "http://127.0.0.1:11434/v1",
@@ -120,9 +118,9 @@ def test_non_cloud_base_silently_drops_compaction(monkeypatch):
 
 def test_azure_openai_base_url_carries_compaction_block(monkeypatch):
     # Azure OpenAI Foundry exposes the same /v1/responses extensions
-    # (context_management, prompt_cache_retention, container shell)
-    # under a *.openai.azure.com base URL. Treat it as cloud so the
-    # compaction field actually reaches the API.
+    # (context_management, prompt_cache_retention, container shell) under
+    # a *.openai.azure.com base URL. Treat it as cloud so the compaction
+    # field reaches the API.
     captured = _capture(
         monkeypatch,
         base_url = "https://my-resource.openai.azure.com/openai/v1",
@@ -132,14 +130,14 @@ def test_azure_openai_base_url_carries_compaction_block(monkeypatch):
         {"type": "compaction", "compact_threshold": 200_000}
     ]
     # Sibling Azure-cloud extension: prompt_cache_retention should also
-    # be set so caching works the same way on Azure deployments.
+    # be set so caching works the same on Azure deployments.
     assert captured["body"].get("prompt_cache_retention") == "24h"
 
 
 def test_azure_openai_mixed_case_base_url_matches(monkeypatch):
-    # The match is case-insensitive so URLs copy-pasted from the Azure
-    # portal (which sometimes capitalise the resource name) still get
-    # the cloud-only fields.
+    # Case-insensitive match so URLs copy-pasted from the Azure portal
+    # (which sometimes capitalise the resource name) still get the
+    # cloud-only fields.
     captured = _capture(
         monkeypatch,
         base_url = "https://My-Resource.OpenAI.Azure.Com/openai/v1",
@@ -151,12 +149,11 @@ def test_azure_openai_mixed_case_base_url_matches(monkeypatch):
 
 
 def test_cloud_gate_uses_hostname_not_substring(monkeypatch):
-    # CodeQL py/incomplete-url-substring-sanitization: an attacker who
-    # controls the configured base_url could embed `api.openai.com` or
-    # `.openai.azure.com` as part of a path or a subdomain on an
-    # arbitrary host to slip the cloud-only request body fields to a
-    # server they control. The hostname-anchored helper must reject
-    # both shapes.
+    # CodeQL py/incomplete-url-substring-sanitization: an attacker
+    # controlling base_url could embed `api.openai.com` or
+    # `.openai.azure.com` in a path or subdomain on an arbitrary host to
+    # slip cloud-only body fields to their own server. The
+    # hostname-anchored helper must reject both shapes.
     for evil in [
         "https://evil.com/api.openai.com/v1",
         "https://api.openai.com.attacker.com/v1",
@@ -188,19 +185,17 @@ def test_omitted_threshold_no_body_field(monkeypatch):
 
 
 def test_chat_completion_request_accepts_any_positive_compaction_threshold():
-    # Codex follow-up: the field is documented as a no-op for non-cloud
-    # OpenAI bases and every non-OpenAI provider, so a cross-provider
-    # schema floor would 422 perfectly valid Anthropic / ollama /
-    # llama.cpp requests that happen to carry the field. Keep schema
-    # floor at ge=1 (any positive int) and rely on per-provider
-    # helpers (_stream_openai_responses / _stream_anthropic) to
-    # enforce or clamp the real floor.
+    # Codex follow-up: the field is a no-op for non-cloud OpenAI bases and
+    # every non-OpenAI provider, so a cross-provider schema floor would
+    # 422 valid Anthropic / ollama / llama.cpp requests carrying it. Keep
+    # the schema floor at ge=1 (any positive int) and let per-provider
+    # helpers (_stream_openai_responses / _stream_anthropic) enforce or
+    # clamp the real floor.
     import pytest as _pytest
 
     from models.inference import ChatCompletionRequest
 
-    # Non-positive values still rejected so blank-string posts don't
-    # sneak through.
+    # Non-positive values rejected so blank-string posts don't sneak in.
     with _pytest.raises(Exception):
         ChatCompletionRequest.model_validate(
             {
@@ -211,10 +206,10 @@ def test_chat_completion_request_accepts_any_positive_compaction_threshold():
         )
 
     # Any positive int passes schema validation, including values that
-    # would be no-ops on the OpenAI cloud path. This is intentional --
-    # the OpenAI helper drops the field on non-cloud bases and
-    # forwards-as-is on cloud bases; if the value is below the model's
-    # effective floor, the upstream API surfaces the error.
+    # are no-ops on the OpenAI cloud path. Intentional -- the OpenAI
+    # helper drops the field on non-cloud bases and forwards as-is on
+    # cloud bases; if it's below the model's effective floor, the upstream
+    # API surfaces the error.
     for v in (1, 5_000, 9_999, 10_000, 200_000):
         req = ChatCompletionRequest.model_validate(
             {
diff --git a/studio/backend/tests/test_openai_container_crud.py b/studio/backend/tests/test_openai_container_crud.py
index 48acf97e1f..e0604527fd 100644
--- a/studio/backend/tests/test_openai_container_crud.py
+++ b/studio/backend/tests/test_openai_container_crud.py
@@ -4,11 +4,11 @@
 """Unit tests for the /v1/containers CRUD client methods.
 
 Covers:
-- All three calls (list / create / delete) send
-  ``OpenAI-Beta: containers=v1``. Without it, OpenAI silently no-ops
-  the DELETE while still returning 200 ``{"deleted": true}``.
-- ``delete_openai_container`` raises when the response body does not
-  report ``{"deleted": true}``, even on a 2xx response.
+- list / create / delete all send ``OpenAI-Beta: containers=v1``. Without
+  it, OpenAI silently no-ops the DELETE but still returns 200
+  ``{"deleted": true}``.
+- ``delete_openai_container`` raises when the body omits
+  ``{"deleted": true}``, even on a 2xx response.
 """
 
 from __future__ import annotations
@@ -28,11 +28,10 @@ def _drive(coro):
 
 
 def _mock_http_client(monkeypatch, handler):
-    """Wire `handler` for both the shared `_http_client` AND any
-    per-call `httpx.AsyncClient(...)` instances. delete_openai_container
-    intentionally creates a fresh AsyncClient (see comment in
-    external_provider.delete_openai_container) so the test must
-    also intercept that constructor."""
+    """Wire `handler` for the shared `_http_client` AND any per-call
+    `httpx.AsyncClient(...)`. delete_openai_container creates a fresh
+    AsyncClient (see external_provider.delete_openai_container), so we
+    must also intercept that constructor."""
     transport = httpx.MockTransport(handler)
     monkeypatch.setattr(ep_mod, "_http_client", httpx.AsyncClient(transport = transport))
     real_async_client = httpx.AsyncClient
@@ -110,13 +109,12 @@ def test_delete_sends_openai_beta_header_and_accepts_confirmation(monkeypatch):
 
 def test_delete_raises_when_response_lacks_deleted_true(monkeypatch):
     """OpenAI returns 200 ``{"deleted": true}`` even when the request is
-    silently rejected (e.g. before we started sending OpenAI-Beta).
-    Defensive guard: when the body omits ``deleted: true``, surface it
-    as an error so the UI can report the failure instead of falsely
-    reporting success."""
+    silently rejected (e.g. before we sent OpenAI-Beta). Guard: when the
+    body omits ``deleted: true``, surface an error so the UI reports the
+    failure instead of false success."""
 
     def handler(request: httpx.Request) -> httpx.Response:
-        # 200 but no deleted flag — simulate an unexpected payload shape.
+        # 200 but no deleted flag — unexpected payload shape.
         return httpx.Response(200, json = {"id": "cntr_x", "object": "container"})
 
     _mock_http_client(monkeypatch, handler)
@@ -159,10 +157,9 @@ def test_delete_propagates_openai_4xx(monkeypatch):
 
 
 def test_list_route_filters_expired_containers(monkeypatch):
-    """OpenAI keeps containers in /v1/containers indefinitely with
-    status="expired" after their idle TTL passes — they can't be
-    used but still show up. The list route must drop them so the
-    picker only surfaces usable containers."""
+    """OpenAI keeps containers in /v1/containers with status="expired"
+    after their idle TTL passes — unusable but still listed. The list
+    route must drop them so the picker shows only usable containers."""
     from routes import inference as inf_mod
     from models.inference import OpenAIContainerRequest
 
diff --git a/studio/backend/tests/test_openai_image_generation.py b/studio/backend/tests/test_openai_image_generation.py
index f5dee2561a..39cf672dc1 100644
--- a/studio/backend/tests/test_openai_image_generation.py
+++ b/studio/backend/tests/test_openai_image_generation.py
@@ -4,17 +4,16 @@
 """Unit tests for OpenAI Responses API image_generation tool wiring.
 
 The image_generation tool is a server-side Responses-API tool:
-``{type: "image_generation"}`` in the request's tools array, and the
-result comes back as an ``image_generation_call`` output item carrying
-the base64 image on ``result``. Studio translates the output item
-into ``_toolEvent`` chunks (``tool_start`` with `kind:"image"`,
-``tool_end`` with ``image_b64`` + ``image_mime``) so the chat adapter
-can render the image inline.
+``{type: "image_generation"}`` in the request's tools array; the result
+returns as an ``image_generation_call`` output item carrying the base64 image
+on ``result``. Studio translates that item into ``_toolEvent`` chunks
+(``tool_start`` with `kind:"image"`, ``tool_end`` with ``image_b64`` +
+``image_mime``) so the chat adapter renders the image inline.
 
-These tests pin: the tool is added to the outbound body only when the
-caller asks for it on a cloud OpenAI base; the SSE output_item.done
-for ``image_generation_call`` produces the expected _toolEvent chunks;
-non-cloud bases drop the tool silently.
+These tests pin: the tool is added to the outbound body only when the caller
+asks for it on a cloud OpenAI base; the SSE output_item.done for
+``image_generation_call`` produces the expected _toolEvent chunks; non-cloud
+bases drop the tool silently.
 """
 
 import asyncio
@@ -75,8 +74,8 @@ def _capture_body(monkeypatch, *, base_url: str, enabled_tools) -> dict:
 
 
 def _collect_tool_events(monkeypatch) -> list[dict]:
-    """Drive a Responses stream that emits one image_generation_call done
-    event and return the parsed _toolEvent chunks."""
+    """Drive a Responses stream with one image_generation_call done event and
+    return the parsed _toolEvent chunks."""
 
     sse = (
         b"event: response.output_item.done\n"
@@ -207,8 +206,8 @@ def test_image_generation_done_emits_tool_event_chunks(monkeypatch):
     ends = [e for e in image_events if e.get("type") == "tool_end"]
     assert len(starts) == 1, image_events
     assert len(ends) == 1, image_events
-    # `_server_tool: True` marks this as a provider-side synthetic
-    # tool card on the frontend's history serializer.
+    # `_server_tool: True` marks this as a provider-side synthetic tool card
+    # for the frontend's history serializer.
     assert starts[0]["arguments"] == {
         "kind": "image",
         "prompt": "A photorealistic cat sitting",
diff --git a/studio/backend/tests/test_openai_responses_translation.py b/studio/backend/tests/test_openai_responses_translation.py
index 95e9b2d63c..19d4959aa1 100644
--- a/studio/backend/tests/test_openai_responses_translation.py
+++ b/studio/backend/tests/test_openai_responses_translation.py
@@ -5,14 +5,14 @@
 Unit tests for the OpenAI `/v1/responses` translation in external_provider.
 
 Covers:
-- Request body shape: system messages collapse into `instructions`, user/
-  assistant messages go into `input`, sampling knobs Responses does not
-  support (presence_penalty, top_k) are not forwarded.
-- SSE translation: `response.output_text.delta` events become OpenAI Chat
-  Completions chunks, `response.completed` emits a `finish_reason: stop`
-  chunk, the stream terminates with `data: [DONE]`.
-- Image parts in user content are rewritten from Chat Completions
-  `{type: image_url, image_url: {url}}` into Responses
+- Request body shape: system messages collapse into `instructions`,
+  user/assistant messages go into `input`, and unsupported sampling knobs
+  (presence_penalty, top_k) are not forwarded.
+- SSE translation: `response.output_text.delta` → Chat Completions chunks,
+  `response.completed` → a `finish_reason: stop` chunk, stream ends with
+  `data: [DONE]`.
+- Image parts rewritten from Chat Completions
+  `{type: image_url, image_url: {url}}` to Responses
   `{type: input_image, image_url: <url>}`.
 """
 
@@ -101,9 +101,9 @@ def test_responses_request_body_uses_input_and_instructions(monkeypatch):
     assert body["input"] == [{"role": "user", "content": "Hi"}]
     assert body["max_output_tokens"] == 512
     assert body["stream"] is True
-    # Responses API on reasoning-class models (gpt-5.x / o3 / gpt-4.5 — the
-    # only OpenAI ids the registry allowlist exposes) rejects these as
-    # `Unsupported parameter`. Make sure we never silently forward them.
+    # Responses API on reasoning-class models (gpt-5.x / o3 / gpt-4.5 — the only
+    # OpenAI ids the registry allowlist exposes) rejects these as `Unsupported
+    # parameter`. Never silently forward them.
     assert "temperature" not in body
     assert "top_p" not in body
     assert "presence_penalty" not in body
@@ -213,11 +213,11 @@ def test_responses_sse_translates_to_chat_completions_chunks(monkeypatch):
 
 
 def test_responses_function_call_output_translates_to_delta_tool_calls(monkeypatch):
-    """Round 12: caller-supplied function tools forwarded into /v1/responses
-    must have their `function_call` output items translated back into Chat
-    Completions delta.tool_calls, and the terminal chunk must emit
-    finish_reason="tool_calls" so the frontend's accumulator runs the
-    function instead of seeing finish_reason="stop"."""
+    """Round 12: function tools forwarded into /v1/responses must have their
+    `function_call` output items translated back into Chat Completions
+    delta.tool_calls, and the terminal chunk must emit
+    finish_reason="tool_calls" (not "stop") so the frontend's accumulator runs
+    the function."""
 
     def handler(request: httpx.Request) -> httpx.Response:
         events = [
@@ -288,7 +288,7 @@ def test_responses_function_call_output_translates_to_delta_tool_calls(monkeypat
     assert tc["id"] == "call_xyz"
     assert tc["function"]["name"] == "get_weather"
     assert tc["function"]["arguments"] == '{"city":"SF"}'
-    # Final chunk reports tool_calls instead of stop.
+    # Final chunk reports tool_calls, not stop.
     terminal = next(
         p
         for p in payloads
@@ -301,8 +301,8 @@ def test_responses_function_call_output_translates_to_delta_tool_calls(monkeypat
 
 def test_responses_parallel_function_calls_get_distinct_indices(monkeypatch):
     """Round 13: parallel function_call items must land on distinct
-    delta.tool_calls[].index slots so index-keyed clients don't
-    collapse the second call into the first."""
+    delta.tool_calls[].index slots so index-keyed clients don't collapse the
+    second call into the first."""
 
     def handler(request: httpx.Request) -> httpx.Response:
         events = [
@@ -388,10 +388,10 @@ def test_responses_parallel_function_calls_get_distinct_indices(monkeypatch):
 
 
 def test_responses_follow_up_tool_result_uses_function_call_output_items(monkeypatch):
-    """Round 13: a second turn after a Responses function call must
-    serialize the tool_calls history and tool result as Responses
-    `function_call` / `function_call_output` input items, not as
-    Chat Completions role="tool" content."""
+    """Round 13: a second turn after a Responses function call must serialize
+    the tool_calls history and tool result as Responses `function_call` /
+    `function_call_output` input items, not Chat Completions role="tool"
+    content."""
     captured: dict = {}
 
     def handler(request: httpx.Request) -> httpx.Response:
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 7d488ae4c9..b9f086a4b9 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -10,8 +10,7 @@ Covers:
   with `content: None` + `tool_calls`.
 - ChatCompletionRequest carries unknown fields via `extra="allow"`.
 - anthropic_tool_choice_to_openai() covers all four Anthropic shapes.
-- _build_passthrough_payload() honors a caller-supplied tool_choice and
-  defaults to "auto" when unset.
+- _build_passthrough_payload() honors a caller tool_choice, defaults to "auto".
 - _friendly_error() maps httpx transport errors to a "Lost connection"
   message so passthrough failures are legible instead of bare 500s.
 
@@ -120,8 +119,8 @@ class TestChatMessageToolRoles:
             ChatMessage(role = "function", content = "x")
 
     def test_content_absent_on_assistant_tool_call_defaults_to_none(self):
-        # Assistant messages that carry only tool_calls are the one
-        # documented case where `content=None` is permitted.
+        # Assistant messages carrying only tool_calls are the one documented
+        # case where `content=None` is permitted.
         msg = ChatMessage(
             role = "assistant",
             tool_calls = [
@@ -136,9 +135,9 @@ class TestChatMessageToolRoles:
 
     def test_tool_role_missing_tool_call_id_left_for_request_validator(self):
         # Per-message: missing tool_call_id is now allowed at this layer.
-        # ChatCompletionRequest's walkback fills it in from the prior
-        # assistant tool_calls; see test_inference_model_validation.py for
-        # the resolution coverage.
+        # ChatCompletionRequest's walkback fills it from the prior assistant
+        # tool_calls; see test_inference_model_validation.py for resolution
+        # coverage.
         msg = ChatMessage(role = "tool", content = '{"temperature": 72}')
         assert msg.tool_call_id is None
         assert msg.content == '{"temperature": 72}'
@@ -173,7 +172,7 @@ class TestChatMessageToolRoles:
         assert "content" in str(exc_info.value)
 
     def test_assistant_without_content_or_tool_calls_tolerated(self):
-        # Stop-button leaves an empty assistant turn; tolerate so replay round-trips.
+        # Stop-button leaves an empty assistant turn; tolerate for replay.
         msg = ChatMessage(role = "assistant")
         assert msg.content is None
         assert msg.tool_calls is None
@@ -280,9 +279,8 @@ class TestChatCompletionRequestToolFields:
         assert req.stop is None
 
     def test_extra_fields_accepted(self):
-        # `frequency_penalty`, `seed`, `response_format` are not yet
-        # explicitly declared but must survive Pydantic parsing now that
-        # extra="allow" is set.
+        # `frequency_penalty`, `seed`, `response_format` aren't explicitly
+        # declared but must survive Pydantic parsing now that extra="allow".
         req = self._make(
             frequency_penalty = 0.5,
             seed = 42,
@@ -306,24 +304,22 @@ class TestChatCompletionRequestToolFields:
 
     def test_stream_defaults_false_matching_openai_spec(self):
         # OpenAI's /v1/chat/completions spec defaults `stream` to false.
-        # Studio previously defaulted to true, which broke naive curl
-        # clients (and .NET / System.Text.Json SDKs per #5047) that omit
-        # `stream` -- they expect a JSON blob, got SSE.
-        # Pin the corrected default so it can't silently regress.
+        # Studio previously defaulted to true, breaking naive curl clients
+        # (and .NET / System.Text.Json SDKs per #5047) that omit `stream`:
+        # they expect a JSON blob, got SSE. Pin the corrected default so it
+        # can't silently regress.
         req = self._make()
         assert req.stream is False
 
     def test_post_without_stream_field_decodes_to_stream_false_over_http(self, monkeypatch):
         # Wire-level guard for the same default: a POST body that omits
-        # `stream` entirely (the exact shape naive curl / .NET clients
-        # send) must deserialise into stream=False *and* the response
-        # must be `application/json`, never `text/event-stream`.
-        # Mounts the real `routes.inference.router` so this catches
-        # regressions in middleware/aliasing on the actual endpoint
-        # (e.g. someone adding a request layer that injects stream=True
-        # before pydantic builds the model). Backends are bypassed by
-        # routing through `provider_type` and stubbing the external
-        # provider proxy.
+        # `stream` (the exact shape naive curl / .NET clients send) must
+        # deserialise into stream=False *and* return `application/json`, never
+        # `text/event-stream`. Mounts the real `routes.inference.router` so
+        # this catches middleware/aliasing regressions on the actual endpoint
+        # (e.g. a request layer that injects stream=True before pydantic builds
+        # the model). Backends are bypassed via `provider_type` + a stubbed
+        # external provider proxy.
         from fastapi import FastAPI
         from fastapi.responses import JSONResponse
         from fastapi.testclient import TestClient
@@ -487,12 +483,12 @@ class TestBuildPassthroughPayloadToolChoice:
 
 class TestFriendlyErrorHttpx:
     """The async pass-through helpers talk to llama-server via httpx.
-    When the subprocess is down, httpx raises RequestError subclasses
-    whose string form (``"All connection attempts failed"``, ``"[Errno 111]
-    Connection refused"``, ...) does NOT contain the substring
-    ``"Lost connection to llama-server"`` the sync path uses, so the
-    previous substring-only `_friendly_error` returned a useless generic
-    message. These tests pin the new isinstance-based mapping.
+    When the subprocess is down, httpx raises RequestError subclasses whose
+    string form (``"All connection attempts failed"``, ``"[Errno 111]
+    Connection refused"``, ...) lacks the ``"Lost connection to llama-server"``
+    substring the sync path uses, so the old substring-only `_friendly_error`
+    returned a useless generic message. These tests pin the new
+    isinstance-based mapping.
     """
 
     def _req(self):
@@ -515,9 +511,8 @@ class TestFriendlyErrorHttpx:
         assert "Lost connection" in _friendly_error(exc)
 
     def test_non_httpx_unchanged(self):
-        # Non-httpx exceptions still fall through to the existing substring
-        # heuristics — a context-size message must still produce the
-        # "Message too long" path.
+        # Non-httpx exceptions still fall through to the substring heuristics
+        # — a context-size message must still produce "Message too long".
         ctx_msg = "request (4096 tokens) exceeds the available context size (2048 tokens)"
         assert "Message too long" in _friendly_error(ValueError(ctx_msg))
 
@@ -543,7 +538,7 @@ class TestDropEmptyAssistantSentinels:
         assert out == [{"role": "user", "content": "hi"}, {"role": "user", "content": "again"}]
 
     def test_drops_assistant_with_no_content_key(self):
-        # exclude_none=True strips the content key entirely; filter must catch this.
+        # exclude_none=True strips the content key entirely; filter must catch it.
         msgs = [
             {"role": "user", "content": "hi"},
             {"role": "assistant"},
@@ -658,8 +653,8 @@ class TestGgufVisionMessages:
         assert len(messages[2]["content"]) == 2
         assert isinstance(messages[1]["content"], str)
 
-        # Legacy top-level image_base64 must be ignored when any message-level
-        # image already exists; otherwise turn 2 ends up with two image parts.
+        # Legacy top-level image_base64 must be ignored when a message-level
+        # image exists; otherwise turn 2 ends up with two image parts.
         for msg in messages:
             content = msg.get("content")
             if isinstance(content, list):
diff --git a/studio/backend/tests/test_openai_tool_result_fallbacks.py b/studio/backend/tests/test_openai_tool_result_fallbacks.py
index 7c033bc348..5ea812441f 100644
--- a/studio/backend/tests/test_openai_tool_result_fallbacks.py
+++ b/studio/backend/tests/test_openai_tool_result_fallbacks.py
@@ -3,8 +3,8 @@
 
 """Regression tests for OpenAI Responses tool-result rendering.
 
-Covers two bug classes: empty web_search cards (per-card result seeded
-with "Searching: <query>") and orphan shell_call cards (bundled-output
+Two bug classes: empty web_search cards (per-card result seeded with
+"Searching: <query>") and orphan shell_call cards (bundled-output
 fallback + final flush at response.completed / response.incomplete).
 """
 
@@ -137,8 +137,8 @@ def test_web_search_each_call_carries_its_own_query_as_result(monkeypatch):
 
 
 def test_web_search_last_call_overwritten_with_citations(monkeypatch):
-    """Last call still gets the aggregated citation list; earlier calls
-    keep their per-call `Searching:` text."""
+    """Last call gets the aggregated citations; earlier calls keep their
+    per-call `Searching:` text."""
     sse_events = [
         {
             "type": "response.output_item.done",
@@ -170,12 +170,12 @@ def test_web_search_last_call_overwritten_with_citations(monkeypatch):
     events = _tool_events(lines)
     ends = [e for e in events if e["type"] == "tool_end"]
     by_id: dict = {}
-    # Keep the LAST tool_end per id (the citation overwrite for ws_2).
+    # Keep the LAST tool_end per id (citation overwrite for ws_2).
     for e in ends:
         by_id[e["tool_call_id"]] = e
     # First call keeps its own query.
     assert by_id["ws_1"]["result"] == "Searching: first query"
-    # Last call gets overwritten with the citation block.
+    # Last call overwritten with the citation block.
     assert "Title: Example A" in by_id["ws_2"]["result"]
     assert "URL: https://example.com/a" in by_id["ws_2"]["result"]
 
diff --git a/studio/backend/tests/test_pricing.py b/studio/backend/tests/test_pricing.py
index d669747b1a..8cd7796f14 100644
--- a/studio/backend/tests/test_pricing.py
+++ b/studio/backend/tests/test_pricing.py
@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Unit tests for the per-session cost calculator. Verifies math
-against ``core/inference/pricing.py`` and graceful degradation."""
+"""Unit tests for the per-session cost calculator: math against
+``core/inference/pricing.py`` plus graceful degradation."""
 
 import math
 
@@ -462,12 +462,12 @@ def test_snapshot_contains_provider_buckets_and_multipliers():
 
 
 # ── longest-prefix match: dated mini variant must not collide with the
-#    shorter family prefix. ──
+#    shorter family prefix ──
 
 
 def test_longest_prefix_match_wins_for_dated_mini_snapshot():
-    """`gpt-5.4-mini-2026-...` must inherit the mini rate, not the
-    shorter `gpt-5.4` rate (longest prefix wins)."""
+    """`gpt-5.4-mini-2026-...` inherits the mini rate, not the shorter
+    `gpt-5.4` rate (longest prefix wins)."""
     out = calculate_cost(
         "openai",
         "gpt-5.4-mini-2026-04-23",
@@ -493,7 +493,7 @@ def test_longest_prefix_match_wins_for_dated_pro_snapshot():
 
 
 def test_openai_chat_style_usage_keys_priced_correctly():
-    """Chat-style envelope (`prompt_tokens` / `completion_tokens`) must
+    """Chat-style envelope (`prompt_tokens`/`completion_tokens`) must
     produce a non-zero cost (previously silently zeroed)."""
     out = calculate_cost(
         "openai",
@@ -577,7 +577,7 @@ def test_openai_chat_style_prompt_tokens_keeps_cache_read_semantics():
 
 def test_openai_chat_style_envelope_reads_cache_from_prompt_tokens_details():
     """Chat-style envelope ships cached under prompt_tokens_details;
-    calculator must honour both this and input_tokens_details."""
+    calculator must honour both that and input_tokens_details."""
     base = OPENAI_PRICING["gpt-5.5"]["input_per_mtok"]
     raw = calculate_cost(
         "openai",
diff --git a/studio/backend/tests/test_pricing_edge.py b/studio/backend/tests/test_pricing_edge.py
index 5818b42e8a..4197d8c9f0 100644
--- a/studio/backend/tests/test_pricing_edge.py
+++ b/studio/backend/tests/test_pricing_edge.py
@@ -30,8 +30,8 @@ def _isclose(
 
 
 def test_prefix_match_requires_dash_boundary_opus_variant():
-    # `claude-opus-4-15` must not inherit `claude-opus-4-1` pricing;
-    # next char must be `-` or end-of-string.
+    # `claude-opus-4-15` must not inherit `claude-opus-4-1` pricing; the next
+    # char must be `-` or end-of-string.
     assert _lookup("anthropic", "claude-opus-4-15") is None
     out = calculate_cost(
         "anthropic",
@@ -55,8 +55,8 @@ def test_prefix_match_requires_dash_boundary_gpt_variant():
 
 
 def test_prefix_match_requires_dash_boundary_pro_lookalike():
-    # `gpt-5.5-prod` must fall through `gpt-5.5-pro` (6x overcharge)
-    # and land on the canonical `gpt-5.5` row.
+    # `gpt-5.5-prod` must fall through `gpt-5.5-pro` (6x overcharge) and land on
+    # the canonical `gpt-5.5` row.
     prices = _lookup("openai", "gpt-5.5-prod")
     assert prices is not None
     assert (
@@ -81,7 +81,7 @@ def test_prefix_match_still_resolves_legit_dated_snapshots():
     assert out["priced"] is True
     assert _isclose(out["input_usd"], 0.75)
 
-    # And Anthropic dated snapshot still resolves to canonical row.
+    # Anthropic dated snapshot still resolves to the canonical row.
     out = calculate_cost(
         "anthropic",
         "claude-opus-4-7-20260414",
@@ -95,7 +95,7 @@ def test_prefix_match_still_resolves_legit_dated_snapshots():
 
 
 def test_explicit_zero_input_tokens_wins_over_stale_prompt_tokens():
-    # Input-side mirror of the output zero precedence test.
+    # Input-side mirror of the output zero-precedence test.
     out = calculate_cost(
         "openai",
         "gpt-5.5",
@@ -110,7 +110,7 @@ def test_explicit_zero_input_tokens_wins_over_stale_prompt_tokens():
 
 
 def test_none_input_tokens_falls_through_to_prompt_tokens():
-    # `None` is "key present but unset"; chat-style mirror wins.
+    # `None` means "key present but unset"; chat-style mirror wins.
     out = calculate_cost(
         "openai",
         "gpt-5.5",
@@ -176,8 +176,8 @@ def test_negative_prompt_tokens_chat_style_clamp():
 
 
 def test_anthropic_chat_cache_read_exceeds_prompt_no_negative_billable():
-    # cache_read > prompt_tokens clamps uncached_input at 0; billable
-    # still reflects cache buckets (we charge for what we got).
+    # cache_read > prompt_tokens clamps uncached_input at 0; billable still
+    # reflects cache buckets (we charge for what we got).
     out = calculate_cost(
         "anthropic",
         "claude-opus-4-7",
@@ -216,8 +216,8 @@ def test_openai_raw_cached_tokens_exceeds_input_clamp_non_cached():
 
 
 def test_openai_long_context_triggers_on_cache_creation_inflated_billable():
-    # cache_creation pushes billable past 272k -> long-context tier
-    # must fire to avoid undercounting.
+    # cache_creation pushes billable past 272k -> long-context tier must fire to
+    # avoid undercounting.
     out = calculate_cost(
         "openai",
         "gpt-5.5",
@@ -272,8 +272,8 @@ def test_openai_chat_envelope_long_context_parity_with_raw():
 
 
 def test_cache_creation_as_int_does_not_crash():
-    # Proxies sometimes fold cache_creation to an int; tolerate it
-    # and fall back to the 5m default.
+    # Proxies sometimes fold cache_creation to an int; tolerate it and fall back
+    # to the 5m default.
     base = ANTHROPIC_PRICING["claude-opus-4-7"]["input_per_mtok"]
     out = calculate_cost(
         "anthropic",
@@ -363,16 +363,16 @@ def test_empty_usage_dict_zero_bill():
 
 
 def test_anthropic_prompt_tokens_details_fallback_when_native_key_missing():
-    """Chat-style envelope without `cache_read_input_tokens` but with
-    mirrored `prompt_tokens_details.cached_tokens` should still apply
-    the cache_read discount."""
+    """Chat-style envelope without `cache_read_input_tokens` but with mirrored
+    `prompt_tokens_details.cached_tokens` should still apply the cache_read
+    discount."""
     r = calculate_cost(
         provider = "anthropic",
         model = "claude-opus-4-7",
         usage = {
             "prompt_tokens": 1_000_000,
             "completion_tokens": 0,
-            # Only the mirrored shape (no native key).
+            # Mirrored shape only (no native key).
             "prompt_tokens_details": {"cached_tokens": 1_000_000},
             "cache_creation_input_tokens": 0,
         },
@@ -383,8 +383,8 @@ def test_anthropic_prompt_tokens_details_fallback_when_native_key_missing():
 
 
 def test_anthropic_native_key_takes_precedence_over_mirrored():
-    """When both native and mirrored cache-read fields are present,
-    the native Anthropic field wins (mirror is fallback-only)."""
+    """When both native and mirrored cache-read fields are present, the native
+    Anthropic field wins (mirror is fallback-only)."""
     r = calculate_cost(
         provider = "anthropic",
         model = "claude-opus-4-7",
@@ -403,8 +403,8 @@ def test_anthropic_native_key_takes_precedence_over_mirrored():
 
 
 def test_anthropic_native_zero_takes_precedence_over_mirrored():
-    """Explicit `cache_read_input_tokens: 0` is authoritative; a stale
-    mirrored block from a proxy must not inflate cache_read past it."""
+    """Explicit `cache_read_input_tokens: 0` is authoritative; a stale mirrored
+    block from a proxy must not inflate cache_read past it."""
     r = calculate_cost(
         provider = "anthropic",
         model = "claude-opus-4-7",
@@ -429,8 +429,8 @@ def test_anthropic_native_zero_takes_precedence_over_mirrored():
 
 
 def test_build_usage_chunk_forwards_anthropic_cache_creation_breakdown():
-    """Chat-style envelope must carry the 5m/1h cache-write breakdown
-    so downstream cost calc applies the 2x 1h premium."""
+    """Chat-style envelope must carry the 5m/1h cache-write breakdown so
+    downstream cost calc applies the 2x 1h premium."""
     import json
     from core.inference.external_provider import _build_usage_chunk
 
diff --git a/studio/backend/tests/test_providers_api.py b/studio/backend/tests/test_providers_api.py
index 88df886b6c..f343cef635 100644
--- a/studio/backend/tests/test_providers_api.py
+++ b/studio/backend/tests/test_providers_api.py
@@ -4,13 +4,13 @@
 """
 Integration tests for the external providers API.
 
-Requires a running Unsloth Studio server. Configure via environment variables:
+Requires a running Unsloth Studio server. Configure via env vars:
 
     export STUDIO_TEST_URL="http://localhost:8888"   # default
     export STUDIO_TEST_USER="unsloth"                # default
     export STUDIO_TEST_PASSWORD="..."                # required — see .bootstrap_password
 
-    # Provider API keys — any left unset will have their tests automatically skipped
+    # Provider API keys — tests skip when their key is unset
     export OPENAI_API_KEY="sk-..."
     export MISTRAL_API_KEY="..."
     export GOOGLE_API_KEY="..."
@@ -38,15 +38,14 @@ BASE_URL = os.getenv("STUDIO_TEST_URL", "http://localhost:8000")
 USERNAME = os.getenv("STUDIO_TEST_USER", "unsloth")
 PASSWORD = os.getenv("STUDIO_TEST_PASSWORD", "")
 
-# These tests require a live Studio server reachable at BASE_URL with a known
-# bootstrap password. Skip the whole module when that environment is missing
-# (e.g. on CI runners) so pytest discovery does not error out.
+# Skip the whole module when no live Studio server / bootstrap password is
+# available (e.g. on CI) so pytest discovery does not error out.
 pytestmark = pytest.mark.skipif(
     not PASSWORD,
     reason = "Integration test requires a running Studio server; set STUDIO_TEST_PASSWORD to enable.",
 )
 
-# Map provider_type → (env var name, model to use for inference test)
+# provider_type → (env var name, model for inference test)
 _PROVIDER_CONFIGS: dict[str, tuple[str, str]] = {
     "openai": ("OPENAI_API_KEY", "gpt-4o-mini"),
     "mistral": ("MISTRAL_API_KEY", "mistral-small-2506"),
@@ -74,10 +73,10 @@ def _url(path: str) -> str:
 
 def _parse_sse_stream(response: requests.Response) -> tuple[str, bool]:
     """
-    Read a streaming SSE response and return (assembled_text, saw_done).
+    Read an SSE response, return (assembled_text, saw_done).
 
-    Each chunk is a JSON object with choices[0].delta.content.
-    The stream ends with `data: [DONE]`.
+    Each chunk is JSON with choices[0].delta.content; stream ends with
+    `data: [DONE]`.
     """
     reply_parts: list[str] = []
     saw_done = False
@@ -93,7 +92,7 @@ def _parse_sse_stream(response: requests.Response) -> tuple[str, bool]:
             break
         try:
             chunk = json.loads(data)
-            # Handle both error payloads and normal chunks
+            # Handle error payloads and normal chunks
             if "error" in chunk:
                 raise RuntimeError(f"Provider error in stream: {chunk['error']}")
             delta = chunk.get("choices", [{}])[0].get("delta", {})
@@ -114,13 +113,12 @@ def auth_headers() -> dict[str, str]:
     """
     Log in once per session and return auth headers.
 
-    On a fresh Studio install the bootstrap password triggers a forced password
-    change (must_change_password=True).  Any subsequent API call using that token
-    returns 403 "Password change required".  This fixture detects that state,
-    automatically completes the change-password flow, and re-logs in so all other
-    tests get a fully usable token.
+    On a fresh install the bootstrap password forces a change
+    (must_change_password=True); calls with that token return 403 "Password
+    change required". This fixture detects that, auto-completes the change, and
+    re-logs in so other tests get a usable token.
 
-    The new password used during auto-change is:
+    The auto-change new password is:
         STUDIO_TEST_NEW_PASSWORD  (env var, optional)
         or PASSWORD + "-test"     (derived default)
 
@@ -142,8 +140,8 @@ def auth_headers() -> dict[str, str]:
     assert token, "access_token is empty"
 
     if body.get("must_change_password"):
-        # Bootstrap token is restricted — only /api/auth/change-password works with it.
-        # Auto-complete the forced change so the rest of the tests get a full token.
+        # Bootstrap token only works with /api/auth/change-password; auto-complete
+        # the forced change so the rest of the tests get a full token.
         new_password = os.getenv("STUDIO_TEST_NEW_PASSWORD") or f"{PASSWORD}-test"
         change_resp = requests.post(
             _url("/api/auth/change-password"),
@@ -176,11 +174,11 @@ def public_key_pem(auth_headers: dict[str, str]) -> str:
 @pytest.fixture(scope = "session")
 def vision_image_data_url() -> str:
     """
-    Download the sloth image once per session and return it as a base64 data URI.
+    Download the sloth image once per session as a base64 data URI.
 
-    Using a data URI instead of a remote URL ensures every provider receives
-    the image inline — Gemini's OpenAI-compatible layer does not fetch external
-    HTTP URLs, so raw image_url links silently produce empty replies for Gemini.
+    A data URI sends the image inline to every provider; Gemini's
+    OpenAI-compatible layer does not fetch external HTTP URLs, so raw image_url
+    links silently produce empty Gemini replies.
     """
     resp = requests.get(_VISION_IMAGE_URL, timeout = 30)
     resp.raise_for_status()
@@ -192,10 +190,10 @@ def vision_image_data_url() -> str:
 @pytest.fixture(scope = "session")
 def encrypt_key(public_key_pem: str):
     """
-    Return a callable encrypt_key(plaintext: str) -> str (base64 RSA-OAEP ciphertext).
-    Uses the backend's RSA public key — mirrors what the frontend does.
+    Return encrypt_key(plaintext: str) -> str (base64 RSA-OAEP ciphertext).
+    Uses the backend's RSA public key — mirrors the frontend.
     """
-    # Decode PEM → load RSA public key
+    # Load RSA public key from PEM
     pem_bytes = public_key_pem.encode("utf-8")
     rsa_pub = serialization.load_pem_public_key(pem_bytes)
 
@@ -298,8 +296,8 @@ class TestRegistry:
 
 class TestProviderCRUD:
     """
-    These tests run sequentially within the class and share state via class variables.
-    They create, read, update, and delete a single test provider config.
+    Run sequentially, sharing state via class variables. Create, read, update,
+    and delete a single test provider config.
     """
 
     _created_id: str = ""
@@ -356,7 +354,7 @@ class TestProviderCRUD:
         )
         assert resp.status_code == 204, f"Delete failed ({resp.status_code}): {resp.text}"
 
-        # Confirm gone from list
+        # Confirm gone
         list_resp = requests.get(_url("/api/providers/"), headers = auth_headers, timeout = 10)
         ids = [p["id"] for p in list_resp.json()]
         assert TestProviderCRUD._created_id not in ids, "Deleted provider still in list"
@@ -366,7 +364,7 @@ class TestProviderCRUD:
 # ── TestProviderInference ────────────────────────────────────────────
 
 
-# Build parametrize list: (provider_type, model, api_key) for configured providers only
+# Parametrize (provider_type, model, api_key) for configured providers
 _INFERENCE_PARAMS = [
     pytest.param(
         ptype,
@@ -384,8 +382,8 @@ _INFERENCE_PARAMS = [
 
 class TestProviderInference:
     """
-    Live inference tests — one parametrized set per provider.
-    Each test is automatically skipped when the provider's API key env var is not set.
+    Live inference tests, one parametrized set per provider. Each is skipped
+    when the provider's API key env var is unset.
     """
 
     @pytest.mark.parametrize("provider_type,model,api_key", _INFERENCE_PARAMS)
@@ -475,7 +473,7 @@ class TestProviderInference:
 
 # ── TestVisionInference ─────────────────────────────────────────────
 
-# Sloth photo — used to test vision routing across providers
+# Sloth photo for testing vision routing across providers
 _VISION_IMAGE_URL = "https://www.travelexcellence.com/images/where-to-see-sloths-in-costa-rica.jpg"
 
 _VISION_PARAMS = [
@@ -496,8 +494,8 @@ _VISION_PARAMS = [
 
 class TestVisionInference:
     """
-    Send a 1×1 white PNG alongside a text question to each vision-capable provider.
-    Verifies that image content parts survive the proxy and the provider replies.
+    Send a 1×1 white PNG plus a text question to each vision-capable provider.
+    Verifies image content parts survive the proxy and the provider replies.
     """
 
     @pytest.mark.parametrize("provider_type,model,api_key", _VISION_PARAMS)
@@ -559,9 +557,9 @@ class TestLocalInferenceUnaffected:
         """
         POST /v1/chat/completions without provider fields must not return 422 or 500.
 
-        200 = a local model is loaded and responded.
-        503 = no model loaded (expected in test environment — that's fine).
-        Any other 4xx/5xx (except 503) = regression in request handling.
+        200 = local model loaded and responded.
+        503 = no model loaded (expected in test env — fine).
+        Any other 4xx/5xx (except 503) = request-handling regression.
         """
         resp = requests.post(
             _url("/v1/chat/completions"),
diff --git a/studio/backend/tests/test_pytorch_mirror.py b/studio/backend/tests/test_pytorch_mirror.py
index 5844f209b6..f1574fb31e 100644
--- a/studio/backend/tests/test_pytorch_mirror.py
+++ b/studio/backend/tests/test_pytorch_mirror.py
@@ -19,8 +19,8 @@ OFFICIAL_URL = "https://download.pytorch.org/whl"
 
 
 def _reload_whl_base(monkeypatch, mirror_value = None):
-    """(Re-)import install_python_stack with a controlled env and return _PYTORCH_WHL_BASE."""
-    # Remove cached module so the module-level assignment re-executes
+    """(Re-)import install_python_stack with a controlled env, return _PYTORCH_WHL_BASE."""
+    # Drop cached module so the module-level assignment re-executes
     sys.modules.pop("install_python_stack", None)
 
     if mirror_value is None:
@@ -28,7 +28,7 @@ def _reload_whl_base(monkeypatch, mirror_value = None):
     else:
         monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", mirror_value)
 
-    # Temporarily add the script's directory to sys.path for import
+    # Add the script's directory to sys.path for import
     script_dir = str(_INSTALL_SCRIPT.parent)
     monkeypatch.syspath_prepend(script_dir)
 
diff --git a/studio/backend/tests/test_recommended_folders_permission.py b/studio/backend/tests/test_recommended_folders_permission.py
index 659c3b547d..ffe8c65ac0 100644
--- a/studio/backend/tests/test_recommended_folders_permission.py
+++ b/studio/backend/tests/test_recommended_folders_permission.py
@@ -6,17 +6,16 @@ Regression test for the /recommended-folders (and /browse-folders) 500
 caused by an unreadable model directory, e.g. a stock root-owned
 ``ollama`` install at ``/usr/share/ollama/.ollama/models``.
 
-Root cause: the folder-scan helpers in ``routes.models`` probed candidate
-paths with a bare ``Path(p).is_dir()``. On Python <= 3.11 that returned
-``False`` for an unreadable path; on Python >= 3.12 ``is_dir()`` propagates
+Root cause: ``routes.models`` folder-scan helpers probed candidates with a
+bare ``Path(p).is_dir()``. On Python <= 3.11 that returned ``False`` for an
+unreadable path; on Python >= 3.12 ``is_dir()`` propagates
 ``PermissionError`` (EACCES), so the endpoint 500-ed through the whole
-middleware stack instead of just skipping the directory. The probes now go
-through the module-level ``_safe_is_dir`` helper.
+middleware stack instead of skipping the directory. Probes now go through
+the module-level ``_safe_is_dir`` helper.
 
-``routes.models`` pulls the full backend dependency tree (fastapi,
-structlog, the models package, ...), so rather than stand up the app we
-extract the real ``_safe_is_dir`` definition from the source file and
-exercise that exact function in isolation. The test therefore stays
+``routes.models`` pulls the full backend dep tree (fastapi, structlog, the
+models package, ...), so rather than stand up the app we extract the real
+``_safe_is_dir`` from the source file and exercise it in isolation —
 dependency-free while still running the shipped code.
 
 Run:
@@ -36,7 +35,7 @@ _models_src = _backend_root / "routes" / "models.py"
 
 def _load_safe_is_dir():
     """Return the real ``_safe_is_dir`` from routes/models.py without
-    importing the (heavily dependency-laden) module."""
+    importing the dependency-laden module."""
     tree = ast.parse(_models_src.read_text())
     fn = next(
         node
@@ -51,8 +50,8 @@ def _load_safe_is_dir():
 
 safe_is_dir = _load_safe_is_dir()
 
-# Permission bits are bypassed for the superuser, so the chmod-000 setup
-# below would not actually deny access when running as root.
+# The superuser bypasses permission bits, so the chmod-000 setup below
+# would not deny access when running as root.
 _skip_as_root = pytest.mark.skipif(
     hasattr(os, "geteuid") and os.geteuid() == 0,
     reason = "root bypasses filesystem permission bits",
@@ -60,8 +59,8 @@ _skip_as_root = pytest.mark.skipif(
 
 
 def test_helper_exists_in_source():
-    # Guards against a refactor silently dropping the helper the fix
-    # depends on (the extractor would then raise StopIteration).
+    # Guard against a refactor silently dropping the helper the fix needs
+    # (the extractor would then raise StopIteration).
     assert callable(safe_is_dir)
 
 
@@ -83,8 +82,8 @@ def test_file_is_false(tmp_path):
 def test_mode000_dir_itself_is_still_a_dir(tmp_path):
     """A mode-000 directory is still stat-able via its (traversable)
     parent, so _safe_is_dir reports True without raising. Filtering out
-    dirs we cannot actually *read* is the caller's separate
-    os.access(R_OK|X_OK) check, not this helper's job."""
+    dirs we can't *read* is the caller's separate os.access(R_OK|X_OK)
+    check, not this helper's job."""
     locked = tmp_path / "locked"
     locked.mkdir()
     os.chmod(locked, 0o000)
@@ -96,8 +95,8 @@ def test_mode000_dir_itself_is_still_a_dir(tmp_path):
 
 @_skip_as_root
 def test_path_under_unreadable_parent_returns_false_not_raises(tmp_path):
-    """The exact production scenario: stat()-ing a child of a mode-700
-    system directory, e.g. ``/usr/share/ollama/.ollama/models``."""
+    """The production scenario: stat()-ing a child of a mode-700 system
+    directory, e.g. ``/usr/share/ollama/.ollama/models``."""
     parent = tmp_path / "ollama"
     parent.mkdir()
     os.chmod(parent, 0o000)
@@ -113,8 +112,8 @@ def test_path_under_unreadable_parent_returns_false_not_raises(tmp_path):
     reason = "is_dir() only propagates PermissionError on Python >= 3.12",
 )
 def test_demonstrates_the_underlying_stdlib_regression(tmp_path):
-    """Documents *why* _safe_is_dir exists: the old bare pattern raises
-    on the interpreters Studio ships on (3.12+)."""
+    """Documents *why* _safe_is_dir exists: the old bare pattern raises on
+    the interpreters Studio ships on (3.12+)."""
     parent = tmp_path / "ollama"
     parent.mkdir()
     os.chmod(parent, 0o000)
diff --git a/studio/backend/tests/test_responses_api.py b/studio/backend/tests/test_responses_api.py
index c0ec876ad0..6ef874bd98 100644
--- a/studio/backend/tests/test_responses_api.py
+++ b/studio/backend/tests/test_responses_api.py
@@ -2,9 +2,9 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
 """
-Tests for the OpenAI Responses API schemas and input normalisation.
-These tests do NOT require a running server or GPU -- they validate
-the Pydantic models and the _normalise_responses_input helper.
+Tests for OpenAI Responses API schemas and input normalisation.
+No running server or GPU required -- validates the Pydantic models and
+the _normalise_responses_input helper.
 """
 
 import sys
@@ -12,7 +12,7 @@ import os
 import json
 import re
 
-# Ensure backend is on path
+# Ensure backend is on path.
 _backend = os.path.join(os.path.dirname(__file__), "..")
 sys.path.insert(0, _backend)
 
@@ -34,33 +34,32 @@ from models.inference import (
 
 
 # ── _normalise_responses_input: copied from routes/inference.py ──
-# We cannot import routes.inference directly because routes/__init__.py
-# pulls in heavy dependencies (structlog/twisted/torch). This is a
-# direct copy of the function for testing purposes.
+# Can't import routes.inference directly: routes/__init__.py pulls in
+# heavy deps (structlog/twisted/torch). This is a direct copy for tests.
 
 
 def _normalise_responses_input(payload: ResponsesRequest) -> list:
-    """Convert a ResponsesRequest into a list of ChatMessage for the completions backend."""
+    """Convert a ResponsesRequest into ChatMessages for the completions backend."""
     messages = []
 
-    # System / developer instructions
+    # System / developer instructions.
     if payload.instructions:
         messages.append(ChatMessage(role = "system", content = payload.instructions))
 
-    # Simple string input
+    # Simple string input.
     if isinstance(payload.input, str):
         if payload.input:
             messages.append(ChatMessage(role = "user", content = payload.input))
         return messages
 
-    # List of ResponsesInputMessage
+    # List of ResponsesInputMessage.
     for msg in payload.input:
         role = "system" if msg.role == "developer" else msg.role
 
         if isinstance(msg.content, str):
             messages.append(ChatMessage(role = role, content = msg.content))
         else:
-            # Convert Responses content parts -> Chat content parts
+            # Convert Responses content parts -> Chat content parts.
             parts = []
             for part in msg.content:
                 if isinstance(part, ResponsesInputTextPart):
@@ -130,7 +129,7 @@ class TestResponsesRequest:
         assert req.instructions == "You are a helpful assistant."
 
     def test_extra_fields_accepted(self):
-        """OpenAI SDK may send fields we don't model -- extra='allow' should pass."""
+        """OpenAI SDK may send unmodeled fields -- extra='allow' must pass."""
         req = ResponsesRequest(
             input = "test",
             tools = [{"type": "web_search_preview"}],
@@ -167,7 +166,7 @@ class TestResponsesRequest:
 
 
 class TestResponsesResponse:
-    """Validate response models serialise correctly."""
+    """Response models serialise correctly."""
 
     def test_basic_response(self):
         resp = ResponsesResponse(
@@ -224,7 +223,7 @@ class TestResponsesResponse:
 
 
 class TestNormaliseResponsesInput:
-    """Test _normalise_responses_input converts Responses input to ChatMessages."""
+    """_normalise_responses_input converts Responses input to ChatMessages."""
 
     def test_string_input(self):
         payload = ResponsesRequest(input = "Hello world")
diff --git a/studio/backend/tests/test_responses_tool_passthrough.py b/studio/backend/tests/test_responses_tool_passthrough.py
index 146d6017d0..c182e3d6d0 100644
--- a/studio/backend/tests/test_responses_tool_passthrough.py
+++ b/studio/backend/tests/test_responses_tool_passthrough.py
@@ -6,19 +6,19 @@ Tests for the OpenAI /v1/responses client-side function-calling pass-through.
 
 Covers:
 - ResponsesRequest accepts Responses-shape `tools`, `tool_choice`,
-  `parallel_tool_calls`, and the `function_call` / `function_call_output`
-  input items used for multi-turn tool loops.
-- _translate_responses_tools_to_chat() converts the flat Responses tool
-  shape to the nested Chat Completions shape, drops non-function built-in
-  tools, and returns None for empty lists.
-- _translate_responses_tool_choice_to_chat() passes string choices through
-  and converts {type:function,name:X} to Chat Completions' nested shape.
-- _normalise_responses_input() maps function_call_output items to
+  `parallel_tool_calls`, and `function_call` / `function_call_output`
+  input items for multi-turn tool loops.
+- _translate_responses_tools_to_chat(): flat Responses tool shape ->
+  nested Chat Completions shape, drops non-function built-in tools,
+  returns None for empty lists.
+- _translate_responses_tool_choice_to_chat(): passes string choices
+  through, converts {type:function,name:X} to the nested shape.
+- _normalise_responses_input(): maps function_call_output items to
   role="tool" ChatMessages with tool_call_id, and function_call items to
   assistant messages with tool_calls.
-- _chat_tool_calls_to_responses_output() preserves call_id and drops
+- _chat_tool_calls_to_responses_output(): keeps call_id, drops
   non-function tool calls.
-- ResponsesOutputFunctionCall and ResponsesResponse round-trip tool-call
+- ResponsesOutputFunctionCall / ResponsesResponse round-trip tool-call
   outputs without losing fields.
 
 No running server or GPU required.
@@ -104,9 +104,9 @@ class TestResponsesRequestTools:
         assert req.parallel_tool_calls is True
 
     def test_builtin_tool_type_passes_validation(self):
-        """Non-function built-in tools (web_search, file_search, mcp, ...) must
-        not raise at request validation so SDKs that default to them don't
-        fail on Studio; they are filtered out during translation."""
+        """Non-function built-in tools (web_search, file_search, mcp, ...)
+        must not raise at validation so SDKs that default to them don't
+        fail on Studio; they're filtered out during translation."""
         req = ResponsesRequest(
             input = "hi",
             tools = [{"type": "web_search_preview"}],
@@ -249,8 +249,8 @@ class TestToolChoiceTranslation:
         ) == {"type": "function", "function": {"name": "get_weather"}}
 
     def test_already_chat_nested_shape_passes_through(self):
-        """If a client happens to send the Chat Completions nested shape,
-        we don't double-wrap it."""
+        """A client sending the Chat Completions nested shape isn't
+        double-wrapped."""
         already_nested = {"type": "function", "function": {"name": "get_weather"}}
         assert _translate_responses_tool_choice_to_chat(already_nested) == already_nested
 
@@ -297,10 +297,10 @@ class TestNormaliseResponsesInputWithTools:
 
     def test_instructions_plus_developer_message_are_merged(self):
         """Codex CLI sends `instructions` (system prompt) AND a developer
-        message in `input`. Strict chat templates (harmony / gpt-oss, Qwen3,
-        ...) raise "System message must be at the beginning" when two
-        separate system-role messages appear, so we must emit exactly one
-        merged system message at the top.
+        message in `input`. Strict chat templates (harmony / gpt-oss,
+        Qwen3, ...) raise "System message must be at the beginning" on two
+        separate system-role messages, so we emit exactly one merged
+        system message at the top.
         """
         payload = ResponsesRequest(
             instructions = "Base instructions.",
@@ -314,14 +314,14 @@ class TestNormaliseResponsesInputWithTools:
         assert len(system_roles) == 1
         assert "Base instructions." in system_roles[0].content
         assert "Developer override." in system_roles[0].content
-        # System must be the very first message for strict templates.
+        # System must be the first message for strict templates.
         assert msgs[0].role == "system"
         assert msgs[1].role == "user"
 
     def test_developer_message_after_user_is_still_hoisted(self):
-        """Multi-turn conversations where a developer message appears after
-        user turns must still produce a single leading system message, not
-        a mid-conversation system that strict templates reject."""
+        """A developer message appearing after user turns must still
+        produce a single leading system message, not a mid-conversation
+        system that strict templates reject."""
         payload = ResponsesRequest(
             input = [
                 {"role": "user", "content": "Hello"},
@@ -486,8 +486,8 @@ class TestCodexStyleRequestShapes:
     """Regression tests for the request shapes OpenAI Codex CLI sends."""
 
     def test_assistant_replay_output_text_accepted(self):
-        """Codex replays prior assistant turns with `output_text` content.
-        Before, this triggered a 422 on every turn after the first."""
+        """Codex replays prior assistant turns with `output_text` content;
+        this used to 422 on every turn after the first."""
         req = ResponsesRequest(
             input = [
                 {"role": "user", "content": "Hi"},
@@ -514,7 +514,7 @@ class TestCodexStyleRequestShapes:
 
     def test_reasoning_item_accepted_as_unknown(self):
         """`reasoning` items replayed from prior o-series turns must not
-        fail validation — Codex preserves them in multi-turn."""
+        fail validation — Codex keeps them in multi-turn."""
         req = ResponsesRequest(
             input = [
                 {"role": "user", "content": "Hi"},
@@ -532,7 +532,7 @@ class TestCodexStyleRequestShapes:
 
     def test_unknown_content_part_type_accepted(self):
         """Unknown content-part types (e.g. future input_audio) validate as
-        ResponsesUnknownContentPart so the whole request doesn't 422."""
+        ResponsesUnknownContentPart so the request doesn't 422."""
         req = ResponsesRequest(
             input = [
                 {
@@ -596,15 +596,15 @@ class TestCodexStyleRequestShapes:
             ],
         )
         msgs = _normalise_responses_input(payload)
-        # Single leading merged system; no mid-conversation system.
+        # One leading merged system; no mid-conversation system.
         assert msgs[0].role == "system"
         assert sum(1 for m in msgs if m.role == "system") == 1
         assert "Base instructions." in msgs[0].content
         assert "Dev override." in msgs[0].content
 
         roles = [m.role for m in msgs[1:]]
-        # Reasoning item is dropped. Order: user, assistant(tool_calls),
-        # tool, assistant(text), user.
+        # Reasoning dropped. Order: user, assistant(tool_calls), tool,
+        # assistant(text), user.
         assert roles == ["user", "assistant", "tool", "assistant", "user"]
         assert msgs[2].tool_calls is not None
         assert msgs[3].role == "tool"
@@ -612,9 +612,9 @@ class TestCodexStyleRequestShapes:
         assert msgs[4].content == "It's 20°C."
 
     def test_single_output_text_part_flattens_to_string(self):
-        """ChatMessage assistant role prefers plain string content — tests
-        confirm we don't forward a single-part array that would otherwise
-        force legacy chat templates into multimodal handling."""
+        """ChatMessage assistant role prefers plain string content — we
+        don't forward a single-part array that would force legacy chat
+        templates into multimodal handling."""
         payload = ResponsesRequest(
             input = [
                 {
@@ -630,9 +630,9 @@ class TestCodexStyleRequestShapes:
 
 
 class TestTranslatedMessagesValidate:
-    """Verify that the messages produced by _normalise_responses_input
-    satisfy ChatMessage's role-shape validator so the downstream /v1/chat/
-    completions pass-through does not reject them."""
+    """Messages from _normalise_responses_input satisfy ChatMessage's
+    role-shape validator so the downstream /v1/chat/completions
+    pass-through doesn't reject them."""
 
     def test_round_trip_multi_turn(self):
         payload = ResponsesRequest(
@@ -654,6 +654,6 @@ class TestTranslatedMessagesValidate:
         )
         msgs = _normalise_responses_input(payload)
         for m in msgs:
-            # Constructing a fresh ChatMessage from the dump round-trips the
-            # role-shape validator — the key invariant for the passthrough.
+            # Building a fresh ChatMessage from the dump round-trips the
+            # role-shape validator — the passthrough's key invariant.
             ChatMessage(**m.model_dump(exclude_none = True))
diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.py
index d27ee83f1d..6b2c6aa84f 100644
--- a/studio/backend/tests/test_rocm_oom_guard.py
+++ b/studio/backend/tests/test_rocm_oom_guard.py
@@ -3,16 +3,16 @@
 
 """Unit tests for _rocm_classify_unified_memory (ROCm OOM-guard classifier).
 
-Covers the three classification paths:
+Three classification paths:
   Path 1 – canonical gcnArchName attribute present.
   Path 2 – gcnArchName absent, alternate-spelling attribute present.
   Path 3 – ALL arch attrs absent; falls back to device-name substring match.
 
-Regression for: Strix Halo (gfx1151) misclassified as discrete on AMD SDK /
-Radeon wheels that populate props.name = "Radeon 8060S Graphics" but do NOT
-set any gcnArchName attribute.  Without the 8060s/8050s name patterns the
-fallback returned is_unified=False, applying the 0.90 fraction instead of
-0.80 and leaving only ~12.8 GiB OS headroom on a 128 GiB unified-memory pool.
+Regression: Strix Halo (gfx1151) misclassified as discrete on AMD SDK / Radeon
+wheels that set props.name = "Radeon 8060S Graphics" but no gcnArchName attr.
+Without the 8060s/8050s name patterns the fallback returned is_unified=False,
+applying 0.90 instead of 0.80 and leaving only ~12.8 GiB OS headroom on a
+128 GiB unified-memory pool.
 """
 
 from __future__ import annotations
@@ -62,7 +62,7 @@ class TestCanonicalGcnArchName:
         assert is_unified is True
 
     def test_canonical_attr_wins_over_name(self) -> None:
-        """Arch attr takes priority; device name should be ignored."""
+        """Arch attr takes priority; device name is ignored."""
         # Discrete arch, but name looks like a unified SKU — arch must win.
         props = _props(gcnArchName = "gfx1100", name = "Radeon 890M")
         gcn, is_unified = _rocm_classify_unified_memory(props)
@@ -97,7 +97,7 @@ class TestAlternateSpellingFallback:
         assert is_unified is False
 
     def test_first_non_empty_attr_wins(self) -> None:
-        """When multiple alternate attrs are present the first non-empty one wins."""
+        """With multiple alternate attrs, the first non-empty one wins."""
         props = _props(gcn_arch_name = "gfx1151", arch_name = "gfx1100", name = "irrelevant")
         gcn, is_unified = _rocm_classify_unified_memory(props)
         assert gcn == "gfx1151"
@@ -147,7 +147,7 @@ class TestDeviceNameFallback:
             "Radeon RX 6900 XT",
             "Radeon Pro W7900",
             "AMD Instinct MI300X",
-            # Names that contain superficially similar substrings but are discrete
+            # Superficially similar substrings but discrete
             "Radeon RX 580",
             "Radeon VII",
         ],
@@ -161,7 +161,7 @@ class TestDeviceNameFallback:
         ), f"discrete device {device_name!r} should NOT be classified as unified-memory"
 
     def test_empty_name_returns_false(self) -> None:
-        """Completely absent name must not crash and must default to discrete."""
+        """Absent name must not crash and must default to discrete."""
         props = _props()  # no 'name' attr at all
         gcn, is_unified = _rocm_classify_unified_memory(props)
         assert gcn == ""
diff --git a/studio/backend/tests/test_safetensors_capability_advertise.py b/studio/backend/tests/test_safetensors_capability_advertise.py
index 5e3d2cc9d1..1e40f376f3 100644
--- a/studio/backend/tests/test_safetensors_capability_advertise.py
+++ b/studio/backend/tests/test_safetensors_capability_advertise.py
@@ -2,9 +2,8 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Capability advertisement contract: classifier honesty, worker→
-orchestrator IPC hop, and route-layer end-to-end. Pure helpers + fakes;
-no torch / transformers import.
+Capability advertisement contract: classifier honesty, worker→orchestrator
+IPC hop, route-layer end-to-end. Pure helpers + fakes; no torch/transformers.
 """
 
 from __future__ import annotations
@@ -116,7 +115,7 @@ def test_detect_safetensors_features_none_template_returns_all_false():
 
 
 def test_detect_safetensors_features_gptoss_disables_tools():
-    """gpt-oss Harmony: tools intentionally off even if template marks it."""
+    """gpt-oss Harmony: tools off even if template marks it."""
     from routes.inference import _detect_safetensors_features
 
     backend = MagicMock()
@@ -129,11 +128,10 @@ def test_detect_safetensors_features_gptoss_disables_tools():
     assert flags["supports_tools"] is False
 
 
-# Llama-3 / Mistral templates advertise tool handling but the model emits
-# tool calls in <|python_tag|> / [TOOL_CALLS] format -- not the
-# <tool_call> / <function= our parser understands. The route helper must
-# refuse to flip supports_tools=True for those families so the UI does
-# not enable a pill the agentic loop cannot honour.
+# Llama-3 / Mistral templates advertise tools but emit calls in
+# <|python_tag|> / [TOOL_CALLS] format -- not the <tool_call> / <function=
+# our parser understands. The route helper must not flip supports_tools=True
+# for those families, else the UI enables a pill the agentic loop can't honour.
 
 LLAMA3_TEMPLATE = """
 {%- if tools %}
@@ -207,10 +205,10 @@ def test_detect_safetensors_features_function_xml_format_keeps_tools_on():
     assert flags["supports_tools"] is True
 
 
-# Qwen3.5 family pins -- the live GGUF + safetensors templates fetched
-# from the unsloth/Qwen3.5-0.8B(-GGUF) repos both wrap tool calls as
-# ``<tool_call>\n<function=name>...``. Capture a faithful slice so the
-# classifier never silently regresses for this family.
+# Qwen3.5 family pins -- the live GGUF + safetensors templates from the
+# unsloth/Qwen3.5-0.8B(-GGUF) repos both wrap tool calls as
+# ``<tool_call>\n<function=name>...``. Faithful slice so the classifier
+# never silently regresses for this family.
 
 QWEN35_TOOL_INSTRUCTION = (
     "{%- if tools %}\n"
@@ -234,7 +232,7 @@ QWEN35_TOOL_INSTRUCTION = (
 
 
 def test_detect_safetensors_features_qwen35_keeps_tools_on():
-    """unsloth/Qwen3.5-0.8B family must surface tools+reasoning enabled."""
+    """unsloth/Qwen3.5-0.8B family must surface tools+reasoning on."""
     from routes.inference import _detect_safetensors_features
 
     backend = SimpleNamespace(active_model_name = "unsloth/Qwen3.5-0.8B")
@@ -248,7 +246,7 @@ def test_detect_safetensors_features_qwen35_keeps_tools_on():
 
 
 def test_orchestrator_mirrors_chat_template_info_into_models_dict():
-    """Worker → orchestrator must copy chat_template_info verbatim."""
+    """Worker → orchestrator copies chat_template_info verbatim."""
     from core.inference.orchestrator import InferenceOrchestrator
 
     orch = InferenceOrchestrator.__new__(InferenceOrchestrator)
@@ -274,7 +272,7 @@ def test_orchestrator_mirrors_chat_template_info_into_models_dict():
         },
     }
 
-    # Replay orchestrator.load_model's mirror block verbatim.
+    # Replay orchestrator.load_model's mirror block.
     orch.active_model_name = model_info["identifier"]
     orch.models[orch.active_model_name] = {
         "is_vision": model_info.get("is_vision", False),
@@ -386,7 +384,7 @@ def test_worker_load_reply_payload_includes_chat_template_info():
 
 
 def test_worker_load_reply_payload_survives_missing_template():
-    """Tokenizer with no chat_template still produces a valid reply."""
+    """Tokenizer with no chat_template still yields a valid reply."""
 
     class _StubBackend:
         def __init__(self):
@@ -421,7 +419,7 @@ def test_worker_load_reply_payload_survives_missing_template():
 
 
 def test_route_layer_emits_supports_tools_true_for_qwen3_safetensors():
-    """End-to-end: Qwen3 safetensors flips supports_tools=True."""
+    """E2E: Qwen3 safetensors flips supports_tools=True."""
     from routes.inference import _detect_safetensors_features
 
     backend = SimpleNamespace(
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index ff5653c742..526ea2d19f 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -4,27 +4,26 @@
 """
 Tests for the safetensors agentic tool loop.
 
-Covers the shared ``tool_call_parser`` helpers and the cumulative-text
-state machine inside ``safetensors_agentic.run_safetensors_tool_loop``.
-The loop is exercised with hand-crafted fake single-turn generators so
-no model load is needed; the tests run in CI under a few seconds.
+Covers the shared ``tool_call_parser`` helpers and the cumulative-text state
+machine in ``safetensors_agentic.run_safetensors_tool_loop``. The loop runs
+against hand-crafted fake single-turn generators, so no model load is needed;
+the tests finish in CI within a few seconds.
 
-Edge cases under coverage:
+Edge cases covered:
 * Plain answers (no tool calls) flush full content.
 * Single ``<tool_call>{json}</tool_call>`` triggers the tool and re-enters.
 * Single ``<function=name>...`` XML form triggers the same path.
 * Truncated unclosed ``<tool_call>`` is still parsed.
 * Tool result is fed back as ``role=tool`` for the next iteration.
-* Bad JSON inside ``<tool_call>`` does not raise and (when healed) is
-  routed as a ``{"query": ...}`` web search call.
-* Duplicate tool calls produce a synthetic "do not repeat" result the
-  second time.
+* Bad JSON inside ``<tool_call>`` does not raise and (when healed) routes as a
+  ``{"query": ...}`` web search call.
+* Duplicate tool calls produce a synthetic "do not repeat" result the 2nd time.
 * ``__IMAGES__`` sentinel is stripped before the model sees the result.
-* Tool execution errors are tagged so the model gets a nudge but the
-  loop keeps streaming.
+* Tool execution errors are tagged so the model gets a nudge but the loop keeps
+  streaming.
 * Cancel is honoured between iterations.
-* ``max_tool_iterations`` cap is respected and a final-answer attempt
-  closes the stream cleanly.
+* ``max_tool_iterations`` cap is respected and a final-answer attempt closes the
+  stream cleanly.
 """
 
 import threading
@@ -64,7 +63,7 @@ class TestParser:
         assert "hello" in tc["function"]["arguments"]
 
     def test_json_tool_call_unclosed(self):
-        # No </tool_call>; balanced-brace extractor must still close.
+        # No </tool_call>; balanced-brace extractor must still close it.
         text = '<tool_call>{"name":"python","arguments":{"code":"print(1)"}}'
         result = parse_tool_calls_from_text(text)
         assert len(result) == 1
@@ -86,9 +85,9 @@ class TestParser:
         assert "ls -la" in result[0]["function"]["arguments"]
 
     def test_code_with_embedded_xml(self):
-        # A code parameter contains the literal </parameter>. Must not
-        # truncate the value because the parser uses end-of-body as the
-        # only boundary for single-parameter calls.
+        # A code parameter contains the literal </parameter>. Must not truncate
+        # the value: the parser uses end-of-body as the only boundary for
+        # single-parameter calls.
         text = (
             "<function=python><parameter=code>html = '<a></a>'\n"
             "print('hi')</parameter></function>"
@@ -121,7 +120,7 @@ class TestParser:
     def test_bad_json_does_not_raise(self):
         text = "<tool_call>{not valid json}</tool_call>"
         result = parse_tool_calls_from_text(text)
-        # Bad JSON is silently dropped; caller can fall back to text.
+        # Bad JSON is dropped silently; caller can fall back to text.
         assert result == []
 
     def test_has_tool_signal(self):
@@ -147,7 +146,7 @@ class TestParser:
 
     def test_strip_markup_unclosed_final(self):
         text = "before <tool_call>{partial"
-        # With final=True the trailing run is dropped.
+        # final=True drops the trailing run.
         assert strip_tool_markup(text, final = True) == "before"
         # Without final=True the unclosed run is preserved.
         assert "partial" in strip_tool_markup(text)
@@ -220,8 +219,7 @@ def _make_loop(
 ):
     """Build a configured loop with a multi-turn fake generator.
 
-    ``turns`` is a list of chunk-lists; iteration N yields chunks from
-    ``turns[N]``.
+    ``turns`` is a list of chunk-lists; iteration N yields chunks from ``turns[N]``.
     """
     turn_iter = iter(turns)
 
@@ -260,7 +258,7 @@ class TestLoopBasic:
         contents = [e for e in events if e["type"] == "content"]
         statuses = [e for e in events if e["type"] == "status"]
         assert contents, "expected at least one content event"
-        # Final cumulative content should contain the answer.
+        # Final cumulative content must contain the answer.
         final_text = contents[-1]["text"]
         assert "Hello world!" in final_text
         assert statuses and statuses[-1]["text"] == ""
@@ -284,7 +282,7 @@ class TestLoopBasic:
 
         assert "tool_start" in kinds
         assert "tool_end" in kinds
-        # Tool was actually called with the parsed arguments.
+        # Tool was called with the parsed arguments.
         assert exec_fn.calls == [("web_search", {"query": "weather"})]
 
         tool_start = next(e for e in events if e["type"] == "tool_start")
@@ -402,8 +400,8 @@ class TestLoopBasic:
     def test_truncated_unclosed_tool_call(self):
         loop, exec_fn = _make_loop(
             turns = [
-                # No </tool_call>; balanced-brace parser must still
-                # succeed because the JSON itself is balanced.
+                # No </tool_call>; balanced-brace parser still succeeds because
+                # the JSON itself is balanced.
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}'],
                 ["done"],
             ],
@@ -413,14 +411,13 @@ class TestLoopBasic:
         assert exec_fn.calls == [("web_search", {"query": "x"})]
 
     def test_bad_json_healed_to_query(self):
-        # Tool call with non-JSON string arguments. With auto_heal_tool_calls
-        # the string is routed as {"query": ...}.
+        # Tool call with non-JSON string arguments. With auto_heal_tool_calls,
+        # the string routes as {"query": ...}.
         loop, exec_fn = _make_loop(
             turns = [
-                # JSON inside the tool call is well-formed; the
-                # ``arguments`` is a string that is not itself valid
-                # JSON for ``_coerce_arguments`` to parse, so the
-                # heal path runs.
+                # JSON inside the tool call is well-formed, but ``arguments`` is
+                # a string that ``_coerce_arguments`` cannot parse as JSON, so
+                # the heal path runs.
                 ['<tool_call>{"name":"web_search","arguments":"hello world"}</tool_call>'],
                 ["ok"],
             ],
@@ -433,9 +430,8 @@ class TestLoopBasic:
 
 class TestLoopBehaviour:
     def test_duplicate_tool_call_synthetic_result(self):
-        # Two identical successful calls in a row: the second is short-
-        # circuited with a "do not repeat" message and execute_tool is
-        # called only once.
+        # Two identical successful calls in a row: the second is short-circuited
+        # with a "do not repeat" message and execute_tool runs only once.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
@@ -452,9 +448,9 @@ class TestLoopBehaviour:
         assert "do not repeat" in tool_end_events[1]["result"].lower()
 
     def test_image_sentinel_stripped_from_model_feed(self):
-        # The tool result has a frontend image sentinel that should be
-        # stripped before being fed back into the next turn, BUT the
-        # tool_end event still carries the raw result for the UI.
+        # The tool result's frontend image sentinel must be stripped before
+        # being fed into the next turn, BUT the tool_end event still carries the
+        # raw result for the UI.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"python","arguments":{"code":"plot()"}}</tool_call>'],
@@ -490,7 +486,7 @@ class TestLoopBehaviour:
                 auto_heal_tool_calls = True,
             )
         )
-        # Model's second turn must not see "__IMAGES__".
+        # The model's second turn must not see "__IMAGES__".
         assert len(captured) >= 2
         tool_msgs = [m for m in captured[1] if m.get("role") == "tool"]
         assert tool_msgs, "no tool message reached the model"
@@ -539,7 +535,7 @@ class TestLoopBehaviour:
         events = _collect_events(loop)
         tool_end = next(e for e in events if e["type"] == "tool_end")
         assert tool_end["result"].startswith("Error")
-        # The loop must still produce a content event after the failure.
+        # The loop must still emit a content event after the failure.
         contents = [e for e in events if e["type"] == "content"]
         assert contents
 
@@ -560,8 +556,8 @@ class TestLoopControl:
     def test_cancel_event_breaks_loop(self):
         cancel = threading.Event()
         cancel.set()
-        # Even with a fake stream that emits tool calls, the loop must
-        # bail before invoking execute_tool when cancel is set.
+        # Even with a fake stream that emits tool calls, the loop must bail
+        # before invoking execute_tool when cancel is set.
         exec_fn = FakeExecuteTool([])
         events = list(
             run_safetensors_tool_loop(
@@ -578,8 +574,8 @@ class TestLoopControl:
         assert exec_fn.calls == []
 
     def test_max_iterations_caps_loop(self):
-        # The loop should stop after max_tool_iterations even if the
-        # model keeps asking for tools, then emit a final-attempt round.
+        # The loop stops after max_tool_iterations even if the model keeps
+        # asking for tools, then emits a final-attempt round.
         loop, exec_fn = _make_loop(
             turns = [
                 # : tool call (executes once)
@@ -592,13 +588,13 @@ class TestLoopControl:
         )
         events = _collect_events(loop)
         contents = [e for e in events if e["type"] == "content"]
-        # Final content must include the final answer.
+        # Final content must contain the final answer.
         assert contents and "final answer" in contents[-1]["text"]
 
 
 class TestStatusFormatting:
     def test_status_for_known_tools(self):
-        # Use the private helper directly to verify status formatting.
+        # Call the private helper directly to verify status formatting.
         assert (
             safetensors_agentic._status_for_tool("web_search", {"query": "abc"}) == "Searching: abc"
         )
@@ -617,10 +613,10 @@ class TestStatusFormatting:
 
 class TestProseMentioningToolCall:
     def test_assistant_prose_with_literal_tool_call_text_survives(self):
-        # Regression: if the assistant text legitimately mentions
-        # ``<tool_call>`` as a literal string and the parser finds no
-        # actual call, the loop must surface the full content instead
-        # of silently stripping everything past the literal marker.
+        # Regression: if assistant text legitimately mentions ``<tool_call>`` as
+        # a literal string and the parser finds no actual call, the loop must
+        # surface the full content instead of stripping everything past the
+        # literal marker.
         loop, exec_fn = _make_loop(
             turns = [
                 # : a real tool call so the loop moves to
@@ -640,9 +636,9 @@ class TestProseMentioningToolCall:
         ), f"prose mentioning <tool_call> should not be truncated; got {final!r}"
 
     def test_tool_result_with_tool_call_text_does_not_retrigger(self):
-        # Tool result text contains the literal ``<tool_call>`` string.
-        # The loop must only parse the MODEL output, not the tool
-        # result, so we should see exactly one call.
+        # Tool result text contains the literal ``<tool_call>`` string. The loop
+        # must parse only the MODEL output, not the tool result, so we see
+        # exactly one call.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
diff --git a/studio/backend/tests/test_sandbox_tools.py b/studio/backend/tests/test_sandbox_tools.py
index 92fee2e8e5..1841d084b9 100644
--- a/studio/backend/tests/test_sandbox_tools.py
+++ b/studio/backend/tests/test_sandbox_tools.py
@@ -117,7 +117,7 @@ class TestUntrustedHostBlock:
         )
 
     def test_dynamic_url_not_statically_blocked(self):
-        # Static AST cannot resolve runtime URLs; bash blocklist is the fallback.
+        # Static AST can't resolve runtime URLs; bash blocklist is the fallback.
         _ok('import requests; url = "https://example.com/"; requests.get(url)')
 
 
@@ -225,8 +225,8 @@ class TestUploadDenylist:
 class TestSandboxEnvIsolation:
     """The sandbox subprocess env is built from a whitelist, not by stripping.
 
-    Confirm every credential-shaped parent var is absent regardless of how the
-    operator's process is configured. Covers Linux/macOS/WSL/Windows shapes.
+    Confirm every credential-shaped parent var is absent regardless of the
+    operator's process config. Covers Linux/macOS/WSL/Windows shapes.
     """
 
     _SECRET_KEYS = (
@@ -313,8 +313,8 @@ class TestSandboxEnvIsolation:
     def test_term_is_dumb(self, tmp_path):
         from core.inference.tools import _build_safe_env
 
-        # Prevents the sandbox from re-using the operator's TERM (e.g. xterm-256color)
-        # which could trigger color-escape parsing in downstream tools.
+        # Avoid re-using the operator's TERM (e.g. xterm-256color) that
+        # could trigger color-escape parsing in downstream tools.
         env = _build_safe_env(str(tmp_path))
         assert env["TERM"] == "dumb"
 
@@ -348,9 +348,9 @@ class TestMaxBodyDefault:
 class TestBashBlocklistPosition:
     """The blocklist must fire at command position only.
 
-    Pre-fix the per-token loop fired on any token, so `grep -r curl .`
+    Pre-fix, the per-token loop fired on any token, so `grep -r curl .`
     and `echo source` were rejected. The position-anchored regex plus a
-    shlex-aware command-position-only token check is sufficient.
+    shlex-aware command-position-only token check fixes this.
     """
 
     @staticmethod
@@ -366,8 +366,7 @@ class TestBashBlocklistPosition:
         assert self._find()("echo source the data") == set()
 
     def test_cat_with_word_source_allowed(self):
-        # The 'source' word is an argument to echo; not blocked.
-        # `echo` itself isn't blocked. Only legit allowed tokens here.
+        # 'source' is an argument to echo, and echo isn't blocked either.
         assert self._find()("cat README.md && echo source") == set()
         assert "source" not in self._find()("cat README.md && echo source")
         assert "echo" not in self._find()("cat README.md && echo source")
@@ -397,14 +396,14 @@ class TestBashBlocklistPosition:
         assert "wget" in self._find()("cd /tmp && wget https://bad")
 
     def test_split_quotes_obfuscation_blocked(self):
-        # shlex collapses 'r''m' -> 'rm' as a single token at command position.
+        # shlex collapses 'r''m' -> 'rm' at command position.
         assert "rm" in self._find()("r''m -rf /")
 
     def test_path_prefixed_command_blocked(self):
         assert "sudo" in self._find()("/usr/bin/sudo whoami")
 
     def test_nested_bash_c_blocked(self):
-        # Recursion into the nested command string still catches command-position curl.
+        # Recursion into the nested command string catches command-position curl.
         assert "curl" in self._find()("bash -c 'curl https://x'")
 
     def test_subshell_command_blocked(self):
@@ -465,9 +464,9 @@ class TestBashBlocklistPosition:
 
 
 class TestHfUploadImportGate:
-    """HfApi-style upload-method blocking should require an HF import in
-    scope; otherwise paramiko / boto3 / internal SDKs with the same
-    method names hit a false positive."""
+    """HfApi-style upload-method blocking requires an HF import in scope;
+    otherwise paramiko / boto3 / internal SDKs with the same method names
+    false-positive."""
 
     def test_paramiko_upload_file_allowed_without_hf_import(self):
         _ok("import paramiko; sftp=None; sftp.upload_file('a','b')")
@@ -476,14 +475,14 @@ class TestHfUploadImportGate:
         _ok("client=None; client.create_commit(Repo='x')")
 
     def test_hf_api_upload_safe_path_allowed(self):
-        # Sandbox-local relative path -- the call shape we want to permit.
+        # Sandbox-local relative path -- the permitted call shape.
         _ok("from huggingface_hub import HfApi; HfApi().upload_file('a','b','c')")
 
     def test_hf_upload_file_fq_safe_path_allowed(self):
         _ok("import huggingface_hub; huggingface_hub.upload_file('a','b','c')")
 
     def test_dynamic_builtin_import_safe_path_allowed(self):
-        # `__import__('huggingface_hub')` puts HF in scope; relative-literal path is safe.
+        # `__import__('huggingface_hub')` puts HF in scope; relative literal is safe.
         _ok("hf=__import__('huggingface_hub'); hf.HfApi().upload_file('a','b','c')")
 
     def test_dynamic_importlib_safe_path_allowed(self):
@@ -499,8 +498,8 @@ class TestHfUploadImportGate:
         )
 
     def test_hf_bare_name_upload_safe_path_allowed(self):
-        # `from huggingface_hub import upload_file` then bare `upload_file(...)`
-        # with a sandbox-local relative-path literal is allowed.
+        # Bare `upload_file(...)` (imported from huggingface_hub) with a
+        # sandbox-local relative-path literal is allowed.
         _ok(
             "from huggingface_hub import upload_file;"
             " upload_file(path_or_fileobj='x', path_in_repo='x', repo_id='r')"
@@ -519,15 +518,15 @@ class TestHfUploadImportGate:
         )
 
     def test_bare_name_upload_file_without_hf_import_allowed(self):
-        # No HF import -- local helper named upload_file should pass.
+        # No HF import -- local helper named upload_file passes.
         _ok("def upload_file(*a, **k):\n    pass\nupload_file('x', 'y', 'z')")
 
 
 class TestHfUploadSandboxLocalPaths:
-    """The HF upload gate must only allow uploads of files that already live in
-    the sandbox workdir. Absolute paths, `..` traversal, home expansion, and
-    Windows drive letters are rejected because the LLM can use them to lift
-    secrets from outside the sandbox."""
+    """The HF upload gate allows only files already in the sandbox workdir.
+    Absolute paths, `..` traversal, home expansion, and Windows drive
+    letters are rejected — the LLM could use them to lift secrets from
+    outside the sandbox."""
 
     def test_relative_literal_allowed(self):
         _ok(
@@ -621,8 +620,8 @@ class TestHfUploadSandboxLocalPaths:
         )
 
     def test_dynamic_variable_path_blocked(self):
-        # A non-literal expression could resolve to any path at runtime;
-        # the static checker cannot prove safety, so block.
+        # A non-literal expr could resolve to any path at runtime; the
+        # static checker can't prove safety, so block.
         _blocked(
             "import huggingface_hub, os\n"
             "p = os.path.join('outputs', 'x.bin')\n"
@@ -674,11 +673,11 @@ class TestHfUploadSandboxLocalPaths:
 
 
 class TestHfUploadEnvAndSecretLeakBlock:
-    """The HF upload gate must reject any positional / keyword arg sourced from
-    `os.environ` / `os.getenv` / subprocess env reads. Even though
-    `_build_safe_env` strips HF_TOKEN/WANDB/AWS upfront for the sandbox shell,
-    a Python script can still reach the parent process env if it bypasses the
-    safe-env wrapper at the source -- so block statically."""
+    """The HF upload gate rejects any positional / keyword arg sourced from
+    `os.environ` / `os.getenv` / subprocess env reads. `_build_safe_env`
+    strips HF_TOKEN/WANDB/AWS for the sandbox shell, but a Python script
+    can still reach the parent env if it bypasses the safe-env wrapper at
+    the source -- so block statically."""
 
     def test_path_from_os_environ_subscript_blocked(self):
         _blocked(
@@ -756,7 +755,7 @@ class TestHfUploadEnvAndSecretLeakBlock:
         )
 
     def test_env_dict_unpacked_via_environ_attr_blocked(self):
-        # `os.environ` as a bare reference (passed somewhere it gets serialized).
+        # Bare `os.environ` reference (passed somewhere it gets serialized).
         _blocked(
             "import huggingface_hub, os\n"
             "huggingface_hub.upload_file(path_or_fileobj=str(os.environ),"
@@ -765,8 +764,8 @@ class TestHfUploadEnvAndSecretLeakBlock:
         )
 
     def test_repo_id_from_env_also_blocked(self):
-        # Even non-path args must not source env vars -- an attacker could
-        # encode secrets in repo_id or path_in_repo.
+        # Non-path args must not source env vars either -- an attacker
+        # could encode secrets in repo_id or path_in_repo.
         _blocked(
             "import huggingface_hub, os\n"
             'huggingface_hub.upload_file(path_or_fileobj="x.bin",'
diff --git a/studio/backend/tests/test_studio_api.py b/studio/backend/tests/test_studio_api.py
index 70a103a2f8..c40729d9a8 100644
--- a/studio/backend/tests/test_studio_api.py
+++ b/studio/backend/tests/test_studio_api.py
@@ -4,9 +4,9 @@
 """
 End-to-end tests for Unsloth Studio's HTTP API surface.
 
-Covers the OpenAI-compatible and Anthropic-compatible endpoints exposed
-by the server that ``unsloth studio run`` boots, plus API key
-authentication and the CLI's ``--help`` output:
+Covers the OpenAI- and Anthropic-compatible endpoints exposed by the
+server that ``unsloth studio run`` boots, plus API key authentication and
+the CLI's ``--help`` output:
 
     1. curl -- basic chat completions (non-streaming)
     2. curl -- streaming chat completions
@@ -38,14 +38,14 @@ Usage:
     export UNSLOTH_E2E_API_KEY=sk-unsloth-...   # from the server banner
     pytest tests/test_studio_api.py -v
 
-    # Pytest mode, fixture-managed server — pytest launches and tears
-    # down the server itself. One-shot verification, CI-friendly.
+    # Pytest mode, fixture-managed server — pytest launches and tears down
+    # the server itself. One-shot verification, CI-friendly.
     pytest tests/test_studio_api.py -v \\
         --unsloth-model unsloth/Qwen3-1.7B-GGUF \\
         --unsloth-gguf-variant UD-Q4_K_XL
 
-The ``base_url`` / ``api_key`` parameters on the test functions resolve
-via the ``studio_server`` session fixture in ``conftest.py``.
+The ``base_url`` / ``api_key`` parameters on the test functions resolve via
+the ``studio_server`` session fixture in ``conftest.py``.
 
 Requires a GPU and ~2 GB of disk for the GGUF download.
 """
@@ -233,10 +233,10 @@ def test_openai_sdk(base_url: str, api_key: str):
 def test_curl_with_tools(base_url: str, api_key: str):
     """Example 4: chat completion with tool calling enabled.
 
-    Note: when ``enable_tools`` is set the server always returns SSE
-    streaming regardless of the ``stream`` flag, so we parse SSE chunks.
-    The model may or may not produce visible content -- tool orchestration
-    can intercept the response -- so we only assert the endpoint succeeds.
+    When ``enable_tools`` is set the server always returns SSE streaming
+    regardless of the ``stream`` flag, so we parse SSE chunks. The model may
+    not produce visible content (tool orchestration can intercept the
+    response), so we only assert the endpoint succeeds.
     """
     status, chunks = _stream_http(
         f"{base_url}/v1/chat/completions",
@@ -268,16 +268,16 @@ def test_curl_with_tools(base_url: str, api_key: str):
 # ── Standard OpenAI function-calling pass-through tests ─────────────
 #
 # Regression coverage for unslothai/unsloth#4999: Studio's
-# /v1/chat/completions used to silently strip standard OpenAI `tools`
-# and `tool_choice` fields, so clients (opencode, Claude Code, Cursor,
-# Continue, ...) could never get structured tool_calls back. These
-# tests exercise the client-side pass-through path that forwards those
-# fields to llama-server verbatim.
+# /v1/chat/completions used to silently strip standard OpenAI `tools` and
+# `tool_choice` fields, so clients (opencode, Claude Code, Cursor,
+# Continue, ...) never got structured tool_calls back. These tests exercise
+# the client-side pass-through path that forwards those fields to
+# llama-server verbatim.
 #
-# They require a tool-capable GGUF (``supports_tools=True`` — e.g.
-# Qwen3, Qwen2.5-Coder, Llama-3.1-Instruct). The default test model
-# ``unsloth/Qwen3-1.7B-GGUF`` advertises tool support via its chat
-# template metadata.
+# They require a tool-capable GGUF (``supports_tools=True`` — e.g. Qwen3,
+# Qwen2.5-Coder, Llama-3.1-Instruct). The default test model
+# ``unsloth/Qwen3-1.7B-GGUF`` advertises tool support via its chat template
+# metadata.
 
 _WEATHER_TOOL = {
     "type": "function",
@@ -301,9 +301,9 @@ _WEATHER_TOOL = {
 def _collect_streamed_tool_calls(chunks: list[dict]) -> list[dict]:
     """Reassemble OpenAI streaming delta.tool_calls into full tool calls.
 
-    OpenAI streams partial tool calls across chunks — the first chunk for
-    a given index carries ``id`` + ``function.name``, and subsequent
-    chunks append fragments to ``function.arguments``.
+    OpenAI streams partial tool calls across chunks — the first chunk for a
+    given index carries ``id`` + ``function.name``, and later chunks append
+    fragments to ``function.arguments``.
     """
     by_index: dict[int, dict] = {}
     for c in chunks:
@@ -346,8 +346,8 @@ def _final_finish_reason(chunks: list[dict]) -> str | None:
 def test_openai_tools_nonstream(base_url: str, api_key: str):
     """Standard OpenAI function calling, non-streaming, tool_choice='required'.
 
-    Regression: before the fix, Studio silently stripped `tools` and the
-    model returned plain text with finish_reason='stop'. After the fix,
+    Regression: before the fix, Studio stripped `tools` and the model
+    returned plain text with finish_reason='stop'. After the fix,
     llama-server's response is forwarded verbatim so the client sees
     finish_reason='tool_calls' with a structured tool_calls array and
     non-zero usage.prompt_tokens.
@@ -428,9 +428,9 @@ def test_openai_tools_multiturn(base_url: str, api_key: str):
     messages and assistant messages carrying tool_calls are accepted.
 
     Regression: before the fix, ChatMessage.role was restricted to
-    {system,user,assistant} and rejected role='tool' at the Pydantic
-    validation stage. This test sends a full round trip so the model
-    receives the simulated tool result and responds with final text.
+    {system,user,assistant} and rejected role='tool' at Pydantic
+    validation. This test sends a full round trip so the model receives the
+    simulated tool result and responds with final text.
     """
     status, text = _http(
         "POST",
@@ -467,7 +467,7 @@ def test_openai_tools_multiturn(base_url: str, api_key: str):
     assert status == 200, f"Expected 200, got {status}: {text[:500]}"
     data = json.loads(text)
     msg = data["choices"][0]["message"]
-    # The model should respond with text now that it has the tool result
+    # The model should respond with text now it has the tool result
     content = msg.get("content") or ""
     assert len(content) > 0 or msg.get(
         "tool_calls"
@@ -701,9 +701,9 @@ def test_anthropic_tool_choice_any(base_url: str, api_key: str):
     """Anthropic Messages API: ``tool_choice: {"type": "any"}`` must be
     honored (forwarded as OpenAI ``tool_choice: "required"`` to
     llama-server). Regression for the secondary fix bundled with #4999 —
-    previously this field was accepted on the request model but silently
-    dropped with a warning log, so the model was free to answer from
-    memory instead of using the tool.
+    previously this field was accepted on the request model but dropped with
+    a warning log, so the model could answer from memory instead of using
+    the tool.
     """
     status, events = _stream_anthropic_http(
         f"{base_url}/v1/messages",
@@ -711,7 +711,7 @@ def test_anthropic_tool_choice_any(base_url: str, api_key: str):
             "model": "default",
             "max_tokens": 256,
             "messages": [
-                # A question the model could easily answer from memory if
+                # A question the model could answer from memory if
                 # tool_choice were not enforced.
                 {
                     "role": "user",
@@ -740,7 +740,7 @@ def test_anthropic_tool_choice_any(base_url: str, api_key: str):
     assert status == 200, f"Expected 200, got {status}"
     assert len(events) > 0, "No SSE events received"
 
-    # With tool_choice=any, stop_reason must be tool_use (not end_turn)
+    # With tool_choice=any, stop_reason must be tool_use, not end_turn
     stop_reason = None
     for etype, data in events:
         if etype == "message_delta":
@@ -870,7 +870,7 @@ def main():
             failed += 1
             print(f"  ERROR {fn.__name__}: {type(exc).__name__}: {exc}")
 
-    # ── 1. Test --help (no server needed) ────────────────────────────
+    # ── 1. --help (no server needed) ────────────────────────────
     print("\n[1/16] Testing --help output")
     run_test(test_help_output)
 
diff --git a/studio/backend/tests/test_studio_train_validation.py b/studio/backend/tests/test_studio_train_validation.py
index 6df491610b..ed33c07689 100644
--- a/studio/backend/tests/test_studio_train_validation.py
+++ b/studio/backend/tests/test_studio_train_validation.py
@@ -24,7 +24,7 @@ from models.training import (
 
 
 def _check_field(field_name: str, value):
-    """Run the field validator without constructing a full TrainingStartRequest."""
+    """Run the field validator without building a full TrainingStartRequest."""
     from models.training import TrainingStartRequest
 
     schema_field = TrainingStartRequest.model_fields[field_name]
@@ -87,7 +87,7 @@ class TestVisionImageSizeCap:
 
     @pytest.mark.parametrize("value", [True, False])
     def test_bool_error_says_integer_not_range(self, value):
-        # Regression guard: bools must say "integer or null", not "in [256, 2048]".
+        # Regression guard: bools say "integer or null", not "in [256, 2048]".
         with pytest.raises(ValidationError) as exc:
             _check_field("vision_image_size", value)
         assert "integer or null" in str(exc.value)
@@ -95,7 +95,7 @@ class TestVisionImageSizeCap:
     @pytest.mark.parametrize("value", ["++512", "--256", "+-+512", "+", "-"])
     def test_multi_sign_string_says_integer_not_raw(self, value):
         # Regression guard: multi-sign strings must not leak int()'s raw
-        # "invalid literal" message; precise contract is "integer or null".
+        # "invalid literal" message; contract is "integer or null".
         with pytest.raises(ValidationError) as exc:
             _check_field("vision_image_size", value)
         assert "integer or null" in str(exc.value)
diff --git a/studio/backend/tests/test_tool_policy_gates.py b/studio/backend/tests/test_tool_policy_gates.py
index 01f6bbbc3f..fad121a4a1 100644
--- a/studio/backend/tests/test_tool_policy_gates.py
+++ b/studio/backend/tests/test_tool_policy_gates.py
@@ -2,8 +2,8 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
 """
-Tests for `_effective_enable_tools` -- the helper that folds the
-process-level `tool_policy` over a request's `enable_tools` field.
+Tests for `_effective_enable_tools` -- folds the process-level `tool_policy`
+over a request's `enable_tools` field.
 
 Truth table (policy x payload.enable_tools -> effective):
   policy=None  + payload=None  -> None
diff --git a/studio/backend/tests/test_tool_xml_strip.py b/studio/backend/tests/test_tool_xml_strip.py
index 857302d543..6cc01f2595 100644
--- a/studio/backend/tests/test_tool_xml_strip.py
+++ b/studio/backend/tests/test_tool_xml_strip.py
@@ -1,9 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Tests for `_TOOL_XML_RE` (routes/inference.py) -- strips tool-call
-XML that leaks past the speculative buffer in core/inference/llama_cpp.py
-when the open/close pair is split across the visible/DRAIN boundary.
+"""Tests for `_TOOL_XML_RE` (routes/inference.py) -- strips tool-call XML that
+leaks past the speculative buffer in core/inference/llama_cpp.py when the
+open/close pair is split across the visible/DRAIN boundary.
 """
 
 from __future__ import annotations
@@ -134,7 +134,7 @@ def test_strips_tail_only_parameter_orphan_no_trailing_ws():
 
 
 def test_preserves_mid_string_parameter_in_code_sample():
-    # Tail-anchor on `</parameter>` is required so doc/example prose survives.
+    # Tail-anchor on `</parameter>` so doc/example prose survives.
     text = (
         "Here is the Qwen tool-call format:\n"
         "```xml\n"
@@ -207,8 +207,8 @@ def test_real_world_sweep_leaks_get_stripped(leak):
 # ── Real-world tail-only </parameter> from gdpval sweep ──────────
 
 
-# All end-anchored: outer </function></tool_call> truncated by EOS,
-# inner <parameter=...> open DRAINED, leaving bare </parameter> tail.
+# All end-anchored: outer </function></tool_call> truncated by EOS, inner
+# <parameter=...> open DRAINED, leaving bare </parameter> tail.
 GDPVAL_PARAMETER_LEAKS = [
     # Qwen3.5-27B Q8_0 / worldbank s00
     "the page contains image data and the text is not readable.\n</parameter>\n\n",
diff --git a/studio/backend/tests/test_training_worker_flash_attn.py b/studio/backend/tests/test_training_worker_flash_attn.py
index edc47c705e..5b7b70eefe 100644
--- a/studio/backend/tests/test_training_worker_flash_attn.py
+++ b/studio/backend/tests/test_training_worker_flash_attn.py
@@ -221,7 +221,7 @@ def test_mamba_ssm_path_preserves_wheel_first_install_args(monkeypatch):
 
 
 def _force_missing_fla_imports(monkeypatch):
-    """Make fla.modules / fla.ops.gated_delta_rule imports raise ImportError."""
+    """Force fla.modules / fla.ops imports to raise ImportError."""
     real_import = builtins.__import__
 
     def fake_import(name, *a, **kw):
@@ -267,8 +267,8 @@ def test_flash_linear_attention_skips_for_unrelated_models(monkeypatch):
 
 
 def test_flash_linear_attention_skips_for_ssm_only_models(monkeypatch):
-    # Nemotron-H / Falcon-H1 / Granite-H / LFM2 take the mamba_ssm path
-    # and never call FLA's gated_delta_rule kernels.
+    # Nemotron-H / Falcon-H1 / Granite-H / LFM2 take the mamba_ssm path,
+    # never FLA's gated_delta_rule kernels.
     run_mock = mock.Mock(return_value = mock.Mock(returncode = 0, stdout = ""))
     monkeypatch.setattr(worker._sp, "run", run_mock)
 
@@ -289,7 +289,7 @@ def test_flash_linear_attention_matches_full_qwen3_family(monkeypatch):
     monkeypatch.setattr(worker._sp, "run", run_mock)
     _force_missing_fla_imports(monkeypatch)
     monkeypatch.setattr(worker, "_send_status", lambda *a, **k: None)
-    # Hermetic discovery: pretend installed transformers ships all the Qwen GDN families.
+    # Hermetic discovery: pretend transformers ships all Qwen GDN families.
     monkeypatch.setattr(
         worker,
         "_discover_fla_model_types",
@@ -370,9 +370,9 @@ def test_flash_linear_attention_install_includes_einops(monkeypatch):
 
     args = run_mock.call_args[0][0]
     assert "--no-deps" in args
-    # einops is declared by fla-core; packaging and triton are pulled in
-    # because fla/utils.py imports them at module load but neither is
-    # declared in fla-core's METADATA (an upstream FLA gap).
+    # einops is declared by fla-core; packaging and triton are added
+    # because fla/utils.py imports them at load but neither is in
+    # fla-core's METADATA (an upstream FLA gap).
     assert "einops" in args
     assert "packaging" in args
     assert "triton" in args
@@ -389,8 +389,8 @@ def test_flash_linear_attention_logs_post_install_import_failure(monkeypatch):
 
     def fake_importable():
         import_calls["count"] += 1
-        # First call (pre-install probe) -> False so we attempt install.
-        # Second call (post-install verify) -> still False.
+        # Pre-install probe -> False (attempt install); post-install
+        # verify -> still False.
         return False
 
     monkeypatch.setattr(worker, "_flash_linear_attention_importable", fake_importable)
@@ -433,13 +433,13 @@ def test_tilelang_backend_pins_only_binary(monkeypatch):
     run_mock = mock.Mock(return_value = mock.Mock(returncode = 0, stdout = ""))
     monkeypatch.setattr(worker._sp, "run", run_mock)
     monkeypatch.setattr(worker, "_send_status", lambda *a, **k: None)
-    # Need to bypass the post-install probe too.
+    # Bypass the post-install probe too.
     probe_calls = {"count": 0}
 
     def fake_probe():
         probe_calls["count"] += 1
-        # First probe (pre-install): False so install runs.
-        # Second probe (post-install): True so success branch taken.
+        # Pre-install probe: False (install runs); post-install: True
+        # (success branch taken).
         return probe_calls["count"] > 1
 
     monkeypatch.setattr(worker, "_tilelang_importable", fake_probe)
@@ -492,13 +492,13 @@ def test_tilelang_backend_reinstalls_when_tvm_ffi_is_broken(monkeypatch):
     """Repair path issues TWO pip calls:
 
     Call 1 (repair): `--force-reinstall --no-deps apache-tvm-ffi==0.1.9`
-      — surgically downgrades the broken package only. `--no-deps` here
-      is REQUIRED to prevent --force-reinstall from cascading through
-      apache-tvm-ffi's dep graph and replacing torch / the CUDA stack.
+      — downgrades only the broken package. `--no-deps` is REQUIRED so
+      --force-reinstall doesn't cascade through apache-tvm-ffi's dep
+      graph and replace torch / the CUDA stack.
 
     Call 2 (install): plain `apache-tvm-ffi==0.1.9 tilelang==0.1.8`
       — resolves missing transitive deps (z3-solver, ml-dtypes) without
-      --force-reinstall, so it never replaces already-correct packages.
+      --force-reinstall, so it never replaces correct packages.
     """
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
@@ -515,14 +515,14 @@ def test_tilelang_backend_reinstalls_when_tvm_ffi_is_broken(monkeypatch):
     assert run_mock.call_count == 2
     repair_args, install_args = (call[0][0] for call in run_mock.call_args_list)
 
-    # Repair: --force-reinstall --no-deps, apache-tvm-ffi ONLY (no tilelang).
+    # Repair: --force-reinstall --no-deps, apache-tvm-ffi ONLY.
     assert "--force-reinstall" in repair_args
     assert "--no-deps" in repair_args, "Repair MUST use --no-deps to avoid replacing torch / CUDA"
     assert "--only-binary=:all:" in repair_args
     assert f"apache-tvm-ffi=={worker._APACHE_TVM_FFI_PACKAGE_VERSION}" in repair_args
     assert all("tilelang" not in a for a in repair_args), "Repair MUST only touch apache-tvm-ffi"
 
-    # Install: regular dep-resolving install, NO --force-reinstall.
+    # Install: regular dep-resolving install, no --force-reinstall.
     assert "--force-reinstall" not in install_args
     assert "--no-deps" not in install_args
     assert "--only-binary=:all:" in install_args
@@ -573,7 +573,7 @@ def test_tilelang_backend_swallows_install_timeout(monkeypatch):
     statuses: list[str] = []
     monkeypatch.setattr(worker, "_send_status", lambda queue, msg: statuses.append(msg))
 
-    # Should not raise.
+    # Must not raise.
     worker._ensure_tilelang_backend(
         event_queue = [],
         model_name = "unsloth/Qwen3.5-2B",
@@ -588,7 +588,7 @@ def test_tilelang_backend_skipped_for_ssm_models(monkeypatch):
     monkeypatch.setattr(worker._sp, "run", run_mock)
 
     # Nemotron-H / Falcon-H1 / Granite-H take the mamba_ssm path, not FLA's
-    # gated_delta_rule -> tilelang has no effect on them.
+    # gated_delta_rule -> tilelang doesn't affect them.
     for name in (
         "tiiuae/Falcon-H1-0.5B-Instruct",
         "nvidia/Nemotron-H-8B-Base",
@@ -635,25 +635,24 @@ def test_tilelang_backend_swallows_install_failure(monkeypatch):
 
 # ───────────────────────────────────────────────────────────────────
 # Runtime hook on `is_flash_linear_attention_available` /
-# `is_causal_conv1d_available`. These are the primary gate in
-# normal operation; the substring tests above cover the
+# `is_causal_conv1d_available` — the primary gate in normal operation.
+# The substring tests above cover the
 # UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 fallback.
 # ───────────────────────────────────────────────────────────────────
 
 
 class _FakeQueue(list):
-    """List with `.put` so worker._send_status can send into it during tests."""
+    """List with `.put` so worker._send_status can send into it in tests."""
 
     def put(self, item):
         self.append(item)
 
 
 def _make_fake_gate(initial_return: bool):
-    """Build a callable that mimics transformers' lru_cache-decorated gates.
+    """Callable mimicking transformers' lru_cache-decorated gates.
 
-    Tracks call count and exposes a `cache_clear` attribute. The return
-    value can be flipped to mimic install-then-True behaviour by setting
-    `.next_return`.
+    Tracks call count and exposes `cache_clear`. Flip `.next_return` to
+    mimic install-then-True behaviour.
     """
 
     class Gate:
@@ -707,7 +706,7 @@ def test_hook_installs_when_gate_returns_false(monkeypatch):
 
     from transformers.utils import import_utils as _iu
 
-    # Both gates are now wrapped. Call them — the hook should drive the install.
+    # Both gates wrapped; calling them should drive the install.
     assert _iu.is_flash_linear_attention_available() is True
     fla_install.assert_called_once()
     tile_install.assert_called_once()
@@ -716,9 +715,9 @@ def test_hook_installs_when_gate_returns_false(monkeypatch):
 
 
 def test_hook_skips_install_when_gate_already_true(monkeypatch):
-    """When both gates are already True AND tilelang is healthy, the hook
-    must do zero install work. (Tilelang repair on the already-True path
-    is covered by test_hook_runs_tilelang_repair_when_fla_already_true.)
+    """Both gates already True AND tilelang healthy -> zero install work.
+    (Tilelang repair on the already-True path is covered by
+    test_hook_runs_tilelang_repair_when_fla_already_true.)
     """
     fla_gate = _make_fake_gate(initial_return = True)
     conv_gate = _make_fake_gate(initial_return = True)
@@ -730,9 +729,8 @@ def test_hook_skips_install_when_gate_already_true(monkeypatch):
     monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
     monkeypatch.setattr(worker, "_install_package_wheel_first", conv_install)
-    # Tilelang healthy so the post_available path is a no-op (otherwise
-    # it would call tile_install, which is correct behaviour but
-    # outside the scope of this test).
+    # Tilelang healthy -> post_available path is a no-op (otherwise it
+    # would call tile_install, correct but out of scope here).
     monkeypatch.setattr(worker, "_tilelang_importable", lambda: True)
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.9")
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
@@ -776,7 +774,7 @@ def test_hook_idempotent_on_repeat_call(monkeypatch):
 
     # First call: hook fires.
     _iu.is_flash_linear_attention_available()
-    # Subsequent calls: must not re-trigger the installer.
+    # Later calls: must not re-trigger the installer.
     _iu.is_flash_linear_attention_available()
     _iu.is_flash_linear_attention_available()
     assert fla_install.call_count == 1
@@ -800,7 +798,7 @@ def test_hook_handles_install_failure_gracefully(monkeypatch):
 
     from transformers.utils import import_utils as _iu
 
-    # Must not raise; returns False so transformers falls back to torch loop.
+    # Must not raise; returns False so transformers uses the torch loop.
     assert _iu.is_flash_linear_attention_available() is False
 
 
@@ -817,7 +815,7 @@ def test_hook_can_be_disabled_via_env(monkeypatch):
 
     from transformers.utils import import_utils as _iu
 
-    # Hook should NOT have been installed; gates remain the fakes.
+    # Hook not installed; gates remain the fakes.
     assert _iu.is_flash_linear_attention_available is fla_gate
     assert _iu.is_causal_conv1d_available is conv_gate
     fla_install.assert_not_called()
@@ -837,21 +835,21 @@ def test_hook_clears_lru_cache_before_first_check(monkeypatch):
     from transformers.utils import import_utils as _iu
 
     _iu.is_flash_linear_attention_available()
-    # The wrapper called cache_clear at least once before delegating.
+    # Wrapper called cache_clear at least once before delegating.
     assert fla_gate.cache_clear_count >= 1
 
 
 def test_hook_rewrites_previously_imported_module_bindings(monkeypatch):
     """Modeling files bind `is_flash_linear_attention_available` locally
     via `from ... import is_X`. Reassigning the attribute on
-    transformers.utils.import_utils alone does NOT reach those local
-    bindings. The hook installer sweeps sys.modules and rebinds them.
+    transformers.utils.import_utils alone misses those local bindings;
+    the hook installer sweeps sys.modules and rebinds them.
     """
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
 
-    # Create a fake modeling module that did `from ... import is_flash_linear_attention_available`.
+    # Fake modeling module that did `from ... import is_flash_linear_attention_available`.
     fake_mod = sys.modules.setdefault(
         "_test_fake_modeling_qwen35", type(sys)("_test_fake_modeling_qwen35")
     )
@@ -868,9 +866,9 @@ def test_hook_rewrites_previously_imported_module_bindings(monkeypatch):
 
     worker._install_fast_path_hooks(event_queue = _FakeQueue(), model_name = "unsloth/Qwen3.5-2B")
 
-    # The fake module's local binding has been rewritten to the wrapper.
+    # The fake module's local binding is rewritten to the wrapper.
     assert fake_mod.is_flash_linear_attention_available is not fla_gate
-    # Calling through the fake module's reference triggers the install.
+    # Calling through the fake module's reference triggers install.
     assert fake_mod.is_flash_linear_attention_available() is True
 
     del sys.modules["_test_fake_modeling_qwen35"]
@@ -894,7 +892,7 @@ def test_hook_skips_when_import_utils_unavailable(monkeypatch):
 
 
 def test_substring_fallback_unchanged_when_hook_skipped(monkeypatch):
-    """Hook disabled -> legacy gate falls back to auto-discovered model types."""
+    """Hook disabled -> legacy gate falls back to auto-discovered types."""
     install_mock = mock.Mock()
     monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", install_mock)
     monkeypatch.setattr(worker, "_discover_fla_model_types", lambda: frozenset({"qwen3_5"}))
@@ -921,8 +919,8 @@ def test_substring_fallback_unchanged_when_hook_skipped(monkeypatch):
 
 
 def test_hook_does_not_install_tilelang_for_model_outside_allowlist(monkeypatch):
-    """A model whose name is not in the auto-discovered FLA allowlist calls
-    is_flash_linear_attention_available but should NOT get tilelang."""
+    """A model not in the auto-discovered FLA allowlist calls
+    is_flash_linear_attention_available but must NOT get tilelang."""
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
@@ -939,7 +937,7 @@ def test_hook_does_not_install_tilelang_for_model_outside_allowlist(monkeypatch)
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
     # Hermetize the auto-discovered set so the test stays valid as new
     # transformers releases add FLA-using model_types (eg olmo_hybrid in
-    # 5.4.0). The semantic under test is "outside-allowlist -> no tilelang".
+    # 5.4.0). Test semantic: "outside-allowlist -> no tilelang".
     monkeypatch.setattr(
         worker,
         "_discover_fla_model_types",
@@ -986,7 +984,7 @@ def test_hook_does_install_tilelang_for_qwen35(monkeypatch):
 
 def test_tilelang_repair_does_not_touch_torch_cuda_stack(monkeypatch):
     """Finding #2: the broken-tvm-ffi repair must use --no-deps on the
-    forced step so --force-reinstall does not cascade through
+    forced step so --force-reinstall doesn't cascade through
     apache-tvm-ffi's dep graph and pull a different torch wheel.
     """
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
@@ -1000,9 +998,9 @@ def test_tilelang_repair_does_not_touch_torch_cuda_stack(monkeypatch):
 
     assert run_mock.call_count == 2
     repair_args = run_mock.call_args_list[0][0][0]
-    # The forced step MUST be --no-deps so torch / CUDA stack is untouched.
+    # Forced step MUST be --no-deps so torch / CUDA stack is untouched.
     assert "--force-reinstall" in repair_args and "--no-deps" in repair_args
-    # And it touches ONLY apache-tvm-ffi, not tilelang / torch.
+    # Touches ONLY apache-tvm-ffi, not tilelang / torch.
     assert all("tilelang" not in a for a in repair_args)
     assert all("torch" not in a for a in repair_args)
 
@@ -1010,25 +1008,24 @@ def test_tilelang_repair_does_not_touch_torch_cuda_stack(monkeypatch):
 def test_hook_trusts_installer_bool_not_metadata(monkeypatch):
     """Finding #3: if pip exits 0 but deep imports fail, the installer
     returns False; the hook must propagate False even if the underlying
-    `original()` gate (which only checks metadata) returns True after
-    pip succeeds.
+    `original()` gate (metadata-only) returns True after pip succeeds.
 
-    Setup mirrors the real bug:
-      1. Pre-install: gate=False (FLA not present) → wrapper triggers install.
+    Mirrors the real bug:
+      1. Pre-install: gate=False (FLA absent) → wrapper triggers install.
       2. Installer's `_flash_linear_attention_importable` post-probe fails,
-         so the installer returns False. (pip exited 0 but `import fla.modules`
-         raised because of a missing transitive dep.)
-      3. Post-install: gate would return True (metadata check sees fla-core
-         version) — but the wrapper must IGNORE that and use the installer's
-         False so transformers takes the torch fallback.
+         so it returns False. (pip exited 0 but `import fla.modules` raised
+         due to a missing transitive dep.)
+      3. Post-install: gate would return True (metadata sees fla-core) — but
+         the wrapper must IGNORE that and use the installer's False so
+         transformers takes the torch fallback.
     """
     # Gate flips True after install (simulating "metadata sees fla").
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
 
-    # Installer "succeeds" at pip, AND flips the gate to True (metadata
-    # sees fla post-install), BUT returns False (deep import broken).
+    # Installer "succeeds" at pip and flips the gate to True (metadata
+    # sees fla post-install), but returns False (deep import broken).
     def _bad_install(eq):
         fla_gate.next_return = True  # metadata says yes after pip
         return False  # but deep import is broken
@@ -1051,9 +1048,9 @@ def test_hook_trusts_installer_bool_not_metadata(monkeypatch):
 
 
 def test_rebind_does_not_trigger_module_getattr(monkeypatch):
-    """Finding #5: the rebind sweep must use __dict__, not getattr(),
-    to avoid invoking transformers' lazy module __getattr__ which spits
-    out hundreds of "Accessing X from .models..." warnings.
+    """Finding #5: the rebind sweep must use __dict__, not getattr(), to
+    avoid invoking transformers' lazy module __getattr__ which spits out
+    hundreds of "Accessing X from .models..." warnings.
     """
     original = object()
     replacement = object()
@@ -1068,8 +1065,8 @@ def test_rebind_does_not_trigger_module_getattr(monkeypatch):
     lazy = _GetattrTripwire("_lazy_test_module")
     sys.modules["_lazy_test_module"] = lazy
     try:
-        # No module-level binding to `is_flash_linear_attention_available`
-        # in __dict__, so the sweep must NOT trip the tripwire.
+        # No `is_flash_linear_attention_available` in __dict__, so the
+        # sweep must NOT trip the tripwire.
         worker._rebind_in_already_imported_modules(
             attr_name = "is_flash_linear_attention_available",
             old_obj = original,
@@ -1085,7 +1082,7 @@ def test_rebind_does_not_trigger_module_getattr(monkeypatch):
 def test_hook_skips_tilelang_when_fla_install_is_skipped(monkeypatch):
     """Finding #6: env-skipped FLA returns False from
     _ensure_flash_linear_attention_unconditional; tilelang must NOT
-    install in that case.
+    install then.
     """
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
@@ -1107,9 +1104,9 @@ def test_hook_skips_tilelang_when_fla_install_is_skipped(monkeypatch):
 
 
 def test_hook_runs_tilelang_repair_when_fla_already_true(monkeypatch):
-    """Finding #7: when FLA is already importable (gate returns True at
-    first probe) but tilelang is missing or apache-tvm-ffi is on the
-    broken list, the post-available action must still run tilelang.
+    """Finding #7: when FLA is already importable (gate True at first
+    probe) but tilelang is missing or apache-tvm-ffi is on the broken
+    list, the post-available action must still run tilelang.
     """
     fla_gate = _make_fake_gate(initial_return = True)
     conv_gate = _make_fake_gate(initial_return = True)
@@ -1120,7 +1117,7 @@ def test_hook_runs_tilelang_repair_when_fla_already_true(monkeypatch):
     monkeypatch.setattr(worker, "_ensure_flash_linear_attention_unconditional", fla_install)
     monkeypatch.setattr(worker, "_ensure_tilelang_backend_unconditional", tile_install)
     monkeypatch.setattr(worker, "_install_package_wheel_first", mock.Mock(return_value = True))
-    # tilelang missing AND tvm-ffi is on broken list — both trigger repair.
+    # tilelang missing AND tvm-ffi on broken list — both trigger repair.
     monkeypatch.setattr(worker, "_tilelang_importable", lambda: False)
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.11")
     monkeypatch.delenv(worker._FAST_PATH_HOOKS_SKIP_ENV, raising = False)
@@ -1130,19 +1127,19 @@ def test_hook_runs_tilelang_repair_when_fla_already_true(monkeypatch):
     from transformers.utils import import_utils as _iu
 
     _iu.is_flash_linear_attention_available()
-    # FLA install was NOT needed; tilelang repair WAS still triggered.
+    # FLA install NOT needed; tilelang repair still triggered.
     fla_install.assert_not_called()
     tile_install.assert_called_once()
 
 
 def test_fla_installer_force_reinstalls_when_older_version_present(monkeypatch):
-    """Finding #8: when an older `flash-linear-attention` is importable
-    but below the pin, the installer must force a reinstall (not no-op).
+    """Finding #8: an older `flash-linear-attention` that is importable
+    but below the pin must force a reinstall (not no-op).
     """
     monkeypatch.delenv(worker._FLA_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_torch_version_tuple", lambda: (2, 9))
-    # Importable but stale (current() reports False even though importable() is True).
+    # Importable but stale (current()=False though importable()=True).
     monkeypatch.setattr(worker, "_flash_linear_attention_importable", lambda: True)
     monkeypatch.setattr(worker, "_flash_linear_attention_current", lambda **kw: False)
     run_mock = mock.Mock(return_value = mock.Mock(returncode = 0, stdout = ""))
@@ -1162,22 +1159,22 @@ def test_fla_installer_force_reinstalls_when_older_version_present(monkeypatch):
 
 def test_run_training_process_eagerly_installs_causal_conv1d_in_normal_mode():
     """Finding #4: SSM modeling files use `lazy_load_kernel("causal-conv1d")`
-    and never call `is_causal_conv1d_available()`, so the hook would not
-    fire for them. The orchestrator must always run the eager
-    substring installer regardless of hook mode.
+    and never call `is_causal_conv1d_available()`, so the hook won't fire
+    for them. The orchestrator must always run the eager substring
+    installer regardless of hook mode.
 
-    This test reads the worker source rather than running the full
-    orchestrator (which requires a configured training config). It
-    asserts the eager install is OUTSIDE the if/else hook branch.
+    Reads the worker source rather than running the full orchestrator
+    (which needs a configured training config), asserting the eager
+    install is OUTSIDE the if/else hook branch.
     """
     import inspect
 
     src = inspect.getsource(worker.run_training_process)
-    # Find the orchestration block.
+    # Orchestration block.
     assert "_ensure_causal_conv1d_fast_path(event_queue, model_name)" in src
     assert "_install_fast_path_hooks(event_queue, model_name)" in src
-    # The eager causal_conv1d call must appear BEFORE the hook-mode if/else,
-    # not nested inside the `if _FAST_PATH_HOOKS_SKIP_ENV` branch.
+    # Eager causal_conv1d call must come BEFORE the hook-mode if/else, not
+    # nested inside the `if _FAST_PATH_HOOKS_SKIP_ENV` branch.
     eager_pos = src.find("_ensure_causal_conv1d_fast_path(event_queue, model_name)")
     skip_check_pos = src.find('os.getenv(_FAST_PATH_HOOKS_SKIP_ENV) == "1"')
     assert eager_pos < skip_check_pos, (
@@ -1189,17 +1186,17 @@ def test_run_training_process_eagerly_installs_causal_conv1d_in_normal_mode():
 
 # ───────────────────────────────────────────────────────────────────
 # HIP / ROCm regression coverage (h34v3nzc0dex Strix Halo report).
-# tilelang 0.1.8 has no HIP GEMM backend; FLA's TileLang dispatch
-# crashes mid-backward on AMD with "Unsupported target for gemm: hip".
-# The fix: skip the install on HIP-built torch AND setdefault
-# FLA_TILELANG=0 so already-installed tilelang doesn't get used either.
+# tilelang 0.1.8 has no HIP GEMM backend; FLA's TileLang dispatch crashes
+# mid-backward on AMD with "Unsupported target for gemm: hip". Fix: skip
+# install on HIP-built torch AND setdefault FLA_TILELANG=0 so an
+# already-installed tilelang isn't used either.
 # ───────────────────────────────────────────────────────────────────
 
 
 def test_tilelang_platform_unsupported_on_hip_torch(monkeypatch):
-    """Strix Halo / MI300 with ROCm torch: linux + x86_64 looks
-    identical to a CUDA box at the OS level, so the platform check
-    must consult torch.version.hip explicitly.
+    """Strix Halo / MI300 with ROCm torch: linux + x86_64 looks identical
+    to a CUDA box at the OS level, so the platform check must consult
+    torch.version.hip explicitly.
     """
     monkeypatch.setattr(worker, "_torch_has_hip", lambda: True)
     assert worker._tilelang_platform_supported() is False
@@ -1220,9 +1217,9 @@ def test_tilelang_install_skipped_on_hip_torch(monkeypatch):
 
 
 def test_install_fast_path_hooks_sets_fla_tilelang_zero_on_hip(monkeypatch):
-    """When HIP torch is detected, hook installer must set
-    FLA_TILELANG=0 (via setdefault — respects user override) so any
-    PRE-EXISTING tilelang install isn't used by FLA's dispatcher.
+    """On HIP torch, the hook installer must setdefault FLA_TILELANG=0
+    (respecting user override) so a PRE-EXISTING tilelang install isn't
+    used by FLA's dispatcher.
     """
     import os as _os
 
@@ -1239,8 +1236,8 @@ def test_install_fast_path_hooks_sets_fla_tilelang_zero_on_hip(monkeypatch):
 
 
 def test_install_fast_path_hooks_respects_user_fla_tilelang_override(monkeypatch):
-    """If the user explicitly set FLA_TILELANG (even on HIP), don't
-    overwrite — they may know they have a HIP-aware tilelang fork.
+    """If the user set FLA_TILELANG (even on HIP), don't overwrite — they
+    may have a HIP-aware tilelang fork.
     """
     import os as _os
 
@@ -1278,7 +1275,7 @@ def test_install_fast_path_hooks_does_not_set_fla_tilelang_on_cuda(monkeypatch):
 
 
 def _make_fake_transformers_tree(tmp_path, fla_types: list[str], non_fla_types: list[str]):
-    """Lay out a tmp dir as `transformers/models/{type}/modeling_{type}.py`."""
+    """Lay out tmp dir as `transformers/models/{type}/modeling_{type}.py`."""
     pkg = tmp_path / "transformers"
     models = pkg / "models"
     models.mkdir(parents = True)
@@ -1341,7 +1338,7 @@ def test_discover_fla_model_types_caches_across_calls(tmp_path, monkeypatch):
     second = worker._discover_fla_model_types()
 
     assert first == second
-    assert read_calls[0] == after_first  # cache hit: no extra disk reads
+    assert read_calls[0] == after_first  # cache hit: no extra reads
 
 
 def test_discover_fla_model_types_handles_missing_transformers(monkeypatch):
@@ -1382,7 +1379,7 @@ def test_discover_fla_model_types_handles_unreadable_file(tmp_path, monkeypatch)
 
     monkeypatch.setattr(_Path, "read_text", boom_read)
     result = worker._discover_fla_model_types()
-    assert result == frozenset()  # unreadable file simply doesn't contribute
+    assert result == frozenset()  # unreadable file doesn't contribute
 
 
 def test_model_wants_tilelang_handles_real_repo_names(monkeypatch):
@@ -1425,20 +1422,19 @@ def test_model_wants_tilelang_normalizes_separators(monkeypatch):
 
 # ────────────────────────────────────────────────────────────────────
 # HIP source-build gcc-install-dir coverage (h34v3nzc0dex Strix Halo).
-# Ubuntu 24.04 ships gcc-14's runtime dir without /usr/include/c++/14,
-# so ROCm clang-20 picks it and fails with 'cstdlib' file not found
-# when building causal-conv1d (or any other HIP source fallback).
-# _hipcc_gcc_install_dir() finds a gcc dir that has both halves; the
+# Ubuntu 24.04 ships gcc-14's runtime dir without /usr/include/c++/14, so
+# ROCm clang-20 picks it and fails with 'cstdlib' file not found when
+# building causal-conv1d (or any HIP source fallback).
+# _hipcc_gcc_install_dir() finds a gcc dir with both halves; the
 # _install_package_wheel_first HIP branch passes it to clang via
-# HIPCC_COMPILE_FLAGS_APPEND. Parallel to bbf004c's setup.sh fix for
-# the llama.cpp HIP build (PR #5301).
+# HIPCC_COMPILE_FLAGS_APPEND. Parallel to bbf004c's setup.sh fix for the
+# llama.cpp HIP build (PR #5301).
 # ────────────────────────────────────────────────────────────────────
 
 
 def _isdir_for_layout(*existing: str):
-    """Return an os.path.isdir replacement that only treats the given
-    absolute paths as directories. Lets a test simulate exactly which
-    gcc runtime dirs and C++ header dirs exist on the host."""
+    """os.path.isdir replacement treating only the given absolute paths as
+    directories, to simulate which gcc runtime / C++ header dirs exist."""
     valid = set(existing)
 
     def fake_isdir(path: str) -> bool:
@@ -1449,7 +1445,7 @@ def _isdir_for_layout(*existing: str):
 
 def test_hipcc_gcc_install_dir_picks_highest_with_headers(monkeypatch):
     """gcc-14 has runtime but no /usr/include/c++/14; loop falls through
-    to gcc-13 which has both. This is the exact Ubuntu 24.04 layout."""
+    to gcc-13 which has both. The exact Ubuntu 24.04 layout."""
     monkeypatch.setattr(sys, "platform", "linux")
     import platform as _platform
 
@@ -1485,8 +1481,8 @@ def test_hipcc_gcc_install_dir_picks_14_when_headers_exist(monkeypatch):
 
 
 def test_hipcc_gcc_install_dir_returns_none_when_no_match(monkeypatch):
-    """No gcc dir has both halves → return None and skip the env injection
-    rather than guessing wrong and surfacing a confusing build failure."""
+    """No gcc dir has both halves → return None and skip env injection
+    rather than guessing wrong and causing a confusing build failure."""
     monkeypatch.setattr(sys, "platform", "linux")
     import platform as _platform
 
@@ -1516,10 +1512,9 @@ def test_hipcc_gcc_install_dir_returns_none_on_non_x86_64(monkeypatch):
 
 
 def _make_hip_install_env(monkeypatch, *, gcc_dir: str | None):
-    """Common scaffolding for tests that exercise the HIP source-build
-    branch of _install_package_wheel_first end-to-end. The package isn't
-    installed yet, no prebuilt wheel exists, hipcc is on PATH, and the
-    fake env reports an HIP torch."""
+    """Scaffolding for end-to-end tests of the HIP source-build branch of
+    _install_package_wheel_first: package not installed, no prebuilt
+    wheel, hipcc on PATH, fake env reports HIP torch."""
     monkeypatch.setattr(builtins, "__import__", _missing_module_import("causal_conv1d"))
     monkeypatch.setattr(
         worker,
@@ -1574,8 +1569,8 @@ def test_install_injects_gcc_install_dir_on_hip_source_build(monkeypatch):
 
 
 def test_install_appends_to_existing_hipcc_compile_flags(monkeypatch):
-    """User has HIPCC_COMPILE_FLAGS_APPEND='-O3 -DFOO' set → final value
-    keeps the user's flags AND adds --gcc-install-dir at the end."""
+    """User has HIPCC_COMPILE_FLAGS_APPEND='-O3 -DFOO' → final value keeps
+    the user's flags AND appends --gcc-install-dir."""
     monkeypatch.setenv("HIPCC_COMPILE_FLAGS_APPEND", "-O3 -DFOO")
     _make_hip_install_env(monkeypatch, gcc_dir = "/usr/lib/gcc/x86_64-linux-gnu/13")
 
@@ -1636,9 +1631,9 @@ def test_install_respects_user_gcc_install_dir(monkeypatch):
         release_base_url = "https://example.com",
     )
 
-    # subprocess.run was invoked without env override (the user already
-    # set HIPCC_COMPILE_FLAGS_APPEND with --gcc-install-dir, so we left
-    # the env alone — the existing value is inherited normally).
+    # subprocess.run invoked without env override (user already set
+    # HIPCC_COMPILE_FLAGS_APPEND with --gcc-install-dir, so we left the
+    # env alone — the existing value is inherited).
     assert captured == {"_called": "yes_no_env"}
 
 
@@ -1660,7 +1655,7 @@ def test_install_does_not_inject_env_on_cuda(monkeypatch):
     monkeypatch.setattr(worker, "direct_wheel_url", lambda **kw: None)
     monkeypatch.setattr(worker.shutil, "which", lambda name: None)
     monkeypatch.setattr(worker, "_send_status", lambda *a, **k: None)
-    # If _hipcc_gcc_install_dir were called on CUDA we'd want to know.
+    # _hipcc_gcc_install_dir must not be called on CUDA.
     monkeypatch.setattr(
         worker,
         "_hipcc_gcc_install_dir",
diff --git a/studio/backend/tests/test_transformers_version.py b/studio/backend/tests/test_transformers_version.py
index ff5e1f1381..c8d6a4fd10 100644
--- a/studio/backend/tests/test_transformers_version.py
+++ b/studio/backend/tests/test_transformers_version.py
@@ -10,9 +10,8 @@ from unittest.mock import patch
 
 
 # ---------------------------------------------------------------------------
-# We need to be able to import the module under test.  The studio backend
-# uses relative-style imports (``from utils.…``), so we add the backend
-# directory to *sys.path* if it is not already there.
+# The studio backend uses relative-style imports (``from utils.…``), so
+# add the backend directory to *sys.path* if not already present.
 # ---------------------------------------------------------------------------
 import sys
 
@@ -20,8 +19,8 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Stub the custom logger before importing the module under test so it
-# doesn't fail on the ``from loggers import get_logger`` line.
+# Stub the custom logger before import so ``from loggers import
+# get_logger`` doesn't fail.
 import types as _types
 
 _loggers_stub = _types.ModuleType("loggers")
@@ -90,7 +89,7 @@ class TestResolveBaseModel:
         (tmp_path / "config.json").write_text(json.dumps(config_cfg))
 
         result = _resolve_base_model(str(tmp_path))
-        # Should fall through, not return the self-referencing path
+        # Falls through; does not return the self-referencing path.
         assert result == str(tmp_path)
 
     def test_no_config_files(self, tmp_path: Path):
@@ -174,7 +173,7 @@ class TestNeedsTransformers5:
 
     def test_llama_does_not_need_v5(self):
         """Standard models should not trigger v5."""
-        # Patch network call to avoid real fetch
+        # Patch network call to avoid a real fetch.
         with patch(
             "utils.transformers_version._check_tokenizer_config_needs_v5",
             return_value = False,
@@ -182,13 +181,13 @@ class TestNeedsTransformers5:
             assert needs_transformers_5("meta-llama/Llama-3-8B") is False
 
     def test_local_checkpoint_resolved_via_config(self, tmp_path: Path):
-        """A local checkpoint with config.json pointing to Qwen3.5 should need v5."""
+        """Local checkpoint with config.json pointing to Qwen3.5 needs v5."""
         config_cfg = {"model_name": "Qwen/Qwen3.5-9B"}
         (tmp_path / "config.json").write_text(json.dumps(config_cfg))
 
-        # _resolve_base_model is called by ensure_transformers_version,
-        # but needs_transformers_5 just does substring matching.
-        # We test the full resolution chain here:
+        # ensure_transformers_version calls _resolve_base_model, but
+        # needs_transformers_5 just does substring matching. Test the
+        # full resolution chain here.
         resolved = _resolve_base_model(str(tmp_path))
         assert needs_transformers_5(resolved) is True
 
@@ -230,7 +229,7 @@ class TestCheckConfigNeeds550:
 
     def test_no_config_json(self, tmp_path: Path):
         """Missing config.json should return False (fail-open)."""
-        # Patch network call to avoid real fetch
+        # Patch network call to avoid a real fetch.
         with patch("urllib.request.urlopen") as mock_urlopen:
             mock_urlopen.side_effect = Exception("no network")
             assert _check_config_needs_550(str(tmp_path)) is False
@@ -311,8 +310,8 @@ class TestGetTransformersTier:
             assert get_transformers_tier("meta-llama/Llama-3-8B") == "default"
 
     def test_550_checked_before_530(self):
-        """Ensure 5.5.0 is checked first — a model matching both should get 550."""
-        # This shouldn't happen in practice, but verifies priority
+        """5.5.0 is checked first — a model matching both gets 550."""
+        # Shouldn't happen in practice, but verifies priority.
         assert get_transformers_tier("gemma-4-model") == "550"
 
     def test_needs_transformers_5_compat(self):
diff --git a/studio/backend/tests/test_utils.py b/studio/backend/tests/test_utils.py
index bdb1cd2ce8..765235bd32 100644
--- a/studio/backend/tests/test_utils.py
+++ b/studio/backend/tests/test_utils.py
@@ -4,13 +4,13 @@
 """
 Tests for utils/hardware and utils/utils — device detection, GPU memory, error formatting.
 
-These tests are designed to pass on ANY platform:
+Designed to pass on ANY platform:
   • NVIDIA GPU  (CUDA backend, requires torch)
   • Apple Silicon (MLX backend, requires mlx)
   • CPU-only     (no GPU at all)
 
-No ML framework is imported at the top level.
-Tests that need torch/mlx internals for mocking are skipped when unavailable.
+No ML framework is imported at the top level; tests needing torch/mlx
+internals for mocking are skipped when unavailable.
 
 Run with:
     cd studio/backend
@@ -189,10 +189,9 @@ class TestGetGpuMemoryInfo:
         assert "backend" in get_gpu_memory_info()
 
     def test_backend_matches_device(self):
-        # The backend field uses _backend_label, which swaps "cuda" for
-        # "rocm" when running on an AMD host (IS_ROCM=True) so the UI
-        # can render the correct label. On CUDA / XPU / MLX / CPU hosts
-        # it is equivalent to `get_device().value`.
+        # backend uses _backend_label, which swaps "cuda" for "rocm" on
+        # AMD hosts (IS_ROCM=True) for the UI label. On CUDA/XPU/MLX/CPU
+        # hosts it equals `get_device().value`.
         from utils.hardware.hardware import _backend_label
         result = get_gpu_memory_info()
         assert result["backend"] == _backend_label(get_device())
diff --git a/studio/backend/tests/test_vision_cache.py b/studio/backend/tests/test_vision_cache.py
index 78f88fd7ea..0df474b586 100644
--- a/studio/backend/tests/test_vision_cache.py
+++ b/studio/backend/tests/test_vision_cache.py
@@ -3,14 +3,13 @@
 
 """Tests for is_vision_model() caching behaviour.
 
-The vision detection cache (``_vision_detection_cache``) mirrors the existing
-``_audio_detection_cache`` pattern used by ``detect_audio_type()``.  These
-tests verify that:
+``_vision_detection_cache`` mirrors the ``_audio_detection_cache``
+pattern used by ``detect_audio_type()``. These tests verify:
 
-* Repeated calls for the same model hit the cache (no redundant work).
+* Repeated calls for the same model hit the cache.
 * Different models each trigger their own detection.
 * Both True and False results are cached.
-* The subprocess path (transformers 5.x models) is also cached.
+* The subprocess path (transformers 5.x models) is cached.
 * Exceptions that fall back to False are cached.
 """
 
@@ -62,8 +61,7 @@ class TestVisionCacheHitMiss:
 
     @patch("utils.models.model_config._is_vision_model_uncached", return_value = True)
     def test_second_call_uses_cache(self, mock_uncached):
-        """Calling is_vision_model() twice for the same model should invoke
-        the uncached function only once."""
+        """Two calls for the same model invoke the uncached fn once."""
         assert is_vision_model("org/my-vlm") is True
         assert is_vision_model("org/my-vlm") is True
         mock_uncached.assert_called_once_with("org/my-vlm", None)
@@ -101,15 +99,15 @@ class TestVisionCacheStoresFalse:
 
 
 class TestVisionCacheSubprocessPath:
-    """Models needing transformers 5.x go through _is_vision_model_subprocess.
-    The cache should prevent the subprocess from being spawned more than once
-    per model per process."""
+    """transformers 5.x models go through _is_vision_model_subprocess.
+    The cache should spawn the subprocess at most once per model per
+    process."""
 
     @patch("utils.models.model_config._is_vision_model_subprocess", return_value = True)
     @patch("utils.transformers_version.needs_transformers_5", return_value = True)
     def test_subprocess_called_once_with_cache(self, mock_needs_t5, mock_subprocess):
-        """Subprocess should only fire on the first call; second is cached."""
-        # First call: goes through uncached → subprocess
+        """Subprocess fires only on the first call; second is cached."""
+        # First call: uncached → subprocess
         assert is_vision_model("unsloth/Qwen3.5-2B") is True
         # Second call: cache hit, no subprocess
         assert is_vision_model("unsloth/Qwen3.5-2B") is True
@@ -136,10 +134,9 @@ class TestVisionCacheSubprocessPath:
 
 
 class TestVisionCacheOnException:
-    """When detection raises an exception, _is_vision_model_uncached
-    distinguishes permanent failures (cached as False) from transient
-    failures (returned as None, not cached so the next call can retry).
-    Verify both contracts."""
+    """On exception, _is_vision_model_uncached distinguishes permanent
+    failures (cached as False) from transient ones (returned as None,
+    not cached, so the next call retries). Verify both contracts."""
 
     @patch(
         "utils.models.model_config.load_model_config",
@@ -148,13 +145,12 @@ class TestVisionCacheOnException:
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
     def test_permanent_exception_result_cached(self, mock_needs_t5, mock_load_config):
         """A permanent failure (ValueError / RepositoryNotFoundError /
-        GatedRepoError / JSONDecodeError) should be caught, return False,
-        and that False should be cached so subsequent calls don't retry.
+        GatedRepoError / JSONDecodeError) is caught, returns False, and
+        that False is cached so subsequent calls don't retry.
 
-        ValueError is used here because it's the simplest of the
-        code-path's cacheable exception types and does not require an
-        import of huggingface_hub errors (whose module path varies
-        across versions)."""
+        ValueError is used as the simplest cacheable exception type that
+        avoids importing huggingface_hub errors (whose module path
+        varies across versions)."""
         # First call: load_model_config raises -> except branch -> False.
         assert is_vision_model("broken/model") is False
         # Second call: cache hit, load_model_config not called again.
@@ -167,17 +163,15 @@ class TestVisionCacheOnException:
     )
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
     def test_transient_exception_not_cached(self, mock_needs_t5, mock_load_config):
-        """A transient failure (OSError, timeouts) should return None from
-        _is_vision_model_uncached, surface as False to the caller, and
-        NOT be cached, so the next call retries detection.  This matches
-        the documented behaviour on _vision_detection_cache:
-        'transient failures (network errors, timeouts) are NOT cached so
-        they can be retried.'"""
-        # First call: load_model_config raises OSError -> uncached None
-        # -> caller returns False without caching.
+        """A transient failure (OSError, timeouts) returns None from
+        _is_vision_model_uncached, surfaces as False to the caller, and
+        is NOT cached, so the next call retries. Matches the documented
+        _vision_detection_cache behaviour: 'transient failures (network
+        errors, timeouts) are NOT cached so they can be retried.'"""
+        # First call: OSError -> uncached None -> caller returns False,
+        # no caching.
         assert is_vision_model("broken/model") is False
-        # Second call: cache miss again, load_model_config called a
-        # second time.
+        # Second call: cache miss again, load_model_config called twice.
         assert is_vision_model("broken/model") is False
         assert mock_load_config.call_count == 2
 
@@ -188,7 +182,7 @@ class TestVisionCacheOnException:
 
 
 class TestVisionCacheDirectPath:
-    """For models that do NOT need transformers 5.x, the detection goes through
+    """Models that do NOT need transformers 5.x detect via
     load_model_config directly. The cache must work the same way."""
 
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
@@ -214,7 +208,7 @@ class TestVisionCacheDirectPath:
         cfg.architectures = ["LlamaForCausalLM"]
         mock_load_config.return_value = cfg
 
-        # LlamaForCausalLM doesn't end with VLM suffixes, no vision_config, etc.
+        # No VLM suffix, no vision_config, etc.
         assert is_vision_model("meta-llama/Llama-3-8B") is False
         assert is_vision_model("meta-llama/Llama-3-8B") is False
         mock_load_config.assert_called_once()
@@ -290,15 +284,14 @@ class TestVisionCacheDirectPath:
 
 
 class TestVisionCacheTokenHandling:
-    """The cache is keyed on (model_name, hf_token).
-    Different tokens for the same model should trigger separate detections
-    to handle gated models correctly."""
+    """The cache is keyed on (model_name, hf_token). Different tokens
+    for the same model trigger separate detections for gated models."""
 
     @patch("utils.models.model_config._is_vision_model_uncached", return_value = True)
     def test_different_tokens_trigger_new_detection(self, mock_uncached):
-        """Calls with different tokens should trigger separate detections to
-        handle gated models correctly (e.g. unauthenticated probe → False,
-        then authenticated call should re-check)."""
+        """Different tokens trigger separate detections for gated models
+        (e.g. unauthenticated probe → False, then authenticated
+        re-check)."""
         assert is_vision_model("gated/model", hf_token = "token-a") is True
         assert is_vision_model("gated/model", hf_token = "token-b") is True
         assert mock_uncached.call_count == 2
diff --git a/studio/backend/tests/test_vram_estimation.py b/studio/backend/tests/test_vram_estimation.py
index 65964908d7..2def8738e2 100644
--- a/studio/backend/tests/test_vram_estimation.py
+++ b/studio/backend/tests/test_vram_estimation.py
@@ -531,7 +531,7 @@ class TestQuantizationSkips(unittest.TestCase):
         )
 
     def test_vlm_prefix_skip_module_does_not_match_text_alias(self):
-        # vision_tower-prefixed skips must not shadow text aliases sharing the
+        # vision_tower-prefixed skips must not shadow text aliases with the
         # same suffix.
         baseline = replace(QUANT_SKIP_STRUCTURED, quantization_skip_modules = [])
         vlm_skip = replace(
@@ -995,9 +995,9 @@ class TestParallelDenseMoE(unittest.TestCase):
             + with_parallel.num_experts * with_parallel.hidden_size
         )
         dense_only = with_parallel.hidden_size * with_parallel.intermediate_size * 3
-        # why: under gemma4 enable_moe_block, the layer's `self.experts` is a
-        # sibling of `self.mlp`; the `text.layers.<i>.mlp` aggregate must
-        # cover the dense path only, with experts in their own aggregate.
+        # why: under gemma4 enable_moe_block, `self.experts` is a sibling of
+        # `self.mlp`; the `text.layers.<i>.mlp` aggregate covers the dense path
+        # only, with experts in their own aggregate.
         self.assertEqual(elements["text.layers.0.mlp"], dense_only)
         self.assertEqual(elements["text.layers.0.experts"], moe_only)
 
@@ -1148,9 +1148,9 @@ class TestPerLayerInputAccounting(unittest.TestCase):
     def test_per_layer_input_modules_count_quantizable_block(self):
         with_ple = self._arch()
         without_ple = replace(with_ple, hidden_size_per_layer_input = 0)
-        # The PLE block adds: model_projection (hd*nl*pli), per_layer_input_gate
-        # (hd*pli per layer) + per_layer_projection (pli*hd per layer) as
-        # quantizable text linears.
+        # PLE block adds these quantizable text linears: model_projection
+        # (hd*nl*pli), per_layer_input_gate (hd*pli per layer),
+        # per_layer_projection (pli*hd per layer).
         n_layers = with_ple.num_hidden_layers
         hd = with_ple.hidden_size
         pli = with_ple.hidden_size_per_layer_input
@@ -1161,10 +1161,10 @@ class TestPerLayerInputAccounting(unittest.TestCase):
         self.assertGreaterEqual(delta, expected_quantizable_extra)
 
     def test_all_linear_lora_excludes_per_layer_input_modules(self):
-        # why: Unsloth's get_peft_regex requires module names to contain a
-        # component tag (mlp/attn/...); PLE module names (per_layer_input_gate,
-        # per_layer_projection, per_layer_model_projection) lack any tag, so
-        # all-linear training does NOT attach LoRA to them.
+        # why: Unsloth's get_peft_regex requires a component tag (mlp/attn/...)
+        # in module names; PLE names (per_layer_input_gate, per_layer_projection,
+        # per_layer_model_projection) lack one, so all-linear does NOT attach
+        # LoRA to them.
         arch = self._arch()
         without_ple = replace(arch, hidden_size_per_layer_input = 0)
         self.assertEqual(
@@ -1234,11 +1234,10 @@ class TestExpertsSkipGranularity(unittest.TestCase):
         bytes_skip_experts = compute_model_weights_bytes(skip_experts, "qlora", True)
         bytes_skip_mlp = compute_model_weights_bytes(skip_full_mlp, "qlora", True)
         # why: under gemma4 enable_moe_block, `self.experts` is a sibling of
-        # `self.mlp`; skipping `model.layers.0.mlp` should cover only the
-        # dense MLP, while `model.layers.0.mlp.experts` covers the routed
-        # experts. Routed experts have far more params than the dense MLP,
-        # so skipping experts must add more bytes than skipping the dense
-        # path.
+        # `self.mlp`; skipping `model.layers.0.mlp` covers only the dense MLP,
+        # while `model.layers.0.mlp.experts` covers the routed experts. Routed
+        # experts have far more params than the dense MLP, so skipping experts
+        # must add more bytes than skipping the dense path.
         self.assertGreater(bytes_skip_experts, bytes_no_skip)
         self.assertGreater(bytes_skip_mlp, bytes_no_skip)
         self.assertGreater(bytes_skip_experts, bytes_skip_mlp)
@@ -1485,8 +1484,8 @@ class TestPerLayerInputSkipAlias(unittest.TestCase):
         )
 
         arch_with = extract_arch_config(self._hf(["model.layers.0"]))
-        # The text.layers.0 aggregate must include the PLE per-layer modules,
-        # so the same skip on a config without PLE produces a smaller value.
+        # text.layers.0 aggregate includes the PLE per-layer modules, so the
+        # same skip on a no-PLE config produces a smaller value.
         arch_without = extract_arch_config(
             SimpleNamespace(
                 text_config = SimpleNamespace(
@@ -1558,7 +1557,7 @@ class TestSharedExpertVariants(unittest.TestCase):
         arch_separate = extract_arch_config(self._hf(shared_expert_intermediate_size = 64))
         arch_implicit = extract_arch_config(self._hf(n_shared_experts = 1))
         # Different shared sizes (64 vs default moe_intermediate_size=128) must
-        # produce different MoE element counts.
+        # give different MoE element counts.
         self.assertNotEqual(
             _compute_moe_mlp_elements(arch_separate),
             _compute_moe_mlp_elements(arch_implicit),
@@ -1567,7 +1566,7 @@ class TestSharedExpertVariants(unittest.TestCase):
     def test_shared_expert_gate_counted_only_for_qwen_style(self):
         from utils.hardware.vram_estimation import _compute_moe_mlp_elements
 
-        # Qwen-style: shared_expert_intermediate_size set -> shared_expert_gate counted.
+        # Qwen-style: shared_expert_intermediate_size set -> gate counted.
         qwen_arch = extract_arch_config(self._hf(shared_expert_intermediate_size = 64))
         hd = qwen_arch.hidden_size
         ms = qwen_arch.moe_intermediate_size
@@ -1624,8 +1623,8 @@ class TestSharedExpertActivation(unittest.TestCase):
         )
 
     def test_shared_expert_plus_dense_block_compose(self):
-        # gemma4 enable_moe_block with hypothetical shared expert: dense + routed
-        # + shared all live per layer; mlp_size should sum all three terms.
+        # gemma4 enable_moe_block with a hypothetical shared expert: dense +
+        # routed + shared all live per layer; mlp_size sums all three.
         from utils.hardware.vram_estimation import _layer_qkv_mlp_sizes
 
         arch = self._make(
@@ -1773,7 +1772,7 @@ class TestSparseMoeSkipAliases(unittest.TestCase):
                 shared_expert_intermediate_size = 32,
             )
         )
-        # shared_expert delta only -- routed mlp.experts is NOT skipped.
+        # shared_expert delta only -- routed mlp.experts NOT skipped.
         delta = _compute_skipped_quantizable_elements(arch)
         self.assertGreater(delta, 0)
         full_layer = extract_arch_config(
@@ -1944,10 +1943,10 @@ class TestErnieMoEListConfig(unittest.TestCase):
                 moe_intermediate_size = [1536, 512],
             )
         )
-        # why: ERNIE 4.5 VL MoE encodes [text_routed, vision_routed]; the
-        # second element is the vision-routed expert width, not the shared
-        # expert width. Shared experts are sized from the text-routed width
-        # (= moe_intermediate_size[0]) when moe_num_shared_experts is set.
+        # why: ERNIE 4.5 VL MoE encodes [text_routed, vision_routed]; element 1
+        # is the vision-routed width, not the shared-expert width. Shared
+        # experts size from the text-routed width (moe_intermediate_size[0])
+        # when moe_num_shared_experts is set.
         self.assertEqual(arch.moe_intermediate_size, 1536)
         self.assertIsNone(arch.shared_expert_intermediate_size)
         self.assertEqual(arch.n_shared_experts, 0)
@@ -2070,7 +2069,7 @@ class TestMultimodalFullModelBytes(unittest.TestCase):
                 load_in_4bit = True,
             )
         self.assertEqual(metadata.get("estimation_mode"), "detailed")
-        # model_weights_gb must reflect the extra non-text bytes (>5 GB
+        # model_weights_gb must reflect the extra non-text bytes (>5 GB,
         # since text-only arch_fp16 is small for these dims).
         self.assertGreater(metadata["vram_breakdown"]["model_weights_gb"], 5.0)
 
diff --git a/studio/backend/tests/test_windows_gpu_detection_mock.py b/studio/backend/tests/test_windows_gpu_detection_mock.py
index bc887f8cc5..3a82541a31 100644
--- a/studio/backend/tests/test_windows_gpu_detection_mock.py
+++ b/studio/backend/tests/test_windows_gpu_detection_mock.py
@@ -3,12 +3,12 @@
 
 """Windows GPU-detection regression test on a synthetic layout.
 
-The bug (#5106): on Windows without a system CUDA toolkit, the prebuilt
-llama-server.exe could not LoadLibrary cudart64_X / cublas64_X /
+Bug (#5106): on Windows without a system CUDA toolkit, the prebuilt
+llama-server.exe couldn't LoadLibrary cudart64_X / cublas64_X /
 cublasLt64_X, so ggml-cuda.dll's static import on cublas64_X.dll failed
 and the model fell back to CPU even when nvidia-smi reported the GPU.
 
-The fix:
+Fix:
   * #5322 overlays upstream's paired cudart bundle into
     install_dir/build/bin/Release/ next to llama-server.exe.
   * #5324 prepends pip-installed nvidia/<pkg>/{bin,bin/x86_64,Library/
@@ -34,13 +34,12 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Stub heavy deps only if they actually fail to import -- unconditional
-# stubs would shadow the real module for sibling tests in this dir.
-# Use try-import rather than find_spec: loggers/__init__.py re-exports
-# handlers.get_logger, which does `from fastapi import Request,
-# Response` at module load. find_spec("loggers") returns a spec even
-# without fastapi, but the import then raises. CI has fastapi, so this
-# is dev-machine ergonomics only.
+# Stub heavy deps only if they fail to import -- unconditional stubs
+# would shadow the real module for sibling tests here. Use try-import,
+# not find_spec: loggers/__init__.py re-exports handlers.get_logger,
+# which does `from fastapi import Request, Response` at load. find_spec
+# returns a spec even without fastapi, but the import then raises. CI has
+# fastapi, so this is dev-machine ergonomics only.
 import importlib as _importlib  # noqa: E402
 
 
@@ -100,7 +99,7 @@ from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
 
 
 # Upstream b9103 cudart bundle: exactly these three DLLs per CUDA major,
-# no executables, no subdirectories. Verified by direct unzip.
+# no executables or subdirectories. Verified by direct unzip.
 REAL_UPSTREAM_CUDART_BUNDLE = {
     "12.4": ("cudart64_12.dll", "cublas64_12.dll", "cublasLt64_12.dll"),
     "13.1": ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll"),
@@ -133,15 +132,15 @@ REAL_PIP_NVIDIA_WHEEL_LAYOUTS = {
 
 def _populate_studio_venv(prefix: Path) -> None:
     """Lay out fake nvidia + torch wheels in <prefix>/Lib/site-packages
-    matching the real win_amd64 wheel layouts. Contents are stub bytes;
-    only directory structure matters."""
+    matching real win_amd64 layouts. Contents are stub bytes; only
+    directory structure matters."""
     site = prefix / "Lib" / "site-packages"
     for rel, dlls in REAL_PIP_NVIDIA_WHEEL_LAYOUTS.items():
         d = site / Path(rel)
         d.mkdir(parents = True, exist_ok = True)
         for name in dlls:
             (d / name).write_bytes(b"PE-stub")
-    # install_python_stack always installs torch alongside nvidia.
+    # install_python_stack always installs torch beside nvidia.
     (site / "torch" / "lib").mkdir(parents = True, exist_ok = True)
     for fn in ("c10.dll", "torch.dll", "torch_cpu.dll", "torch_python.dll"):
         (site / "torch" / "lib" / fn).write_bytes(b"PE-stub")
@@ -149,7 +148,7 @@ def _populate_studio_venv(prefix: Path) -> None:
 
 def _populate_studio_install(install_dir: Path, runtime: str = "13.1") -> None:
     """Lay out install_dir/build/bin/Release/ as #5322 leaves it: main
-    archive payload + paired cudart bundle overlay."""
+    archive payload + cudart bundle overlay."""
     rel = install_dir / "build" / "bin" / "Release"
     rel.mkdir(parents = True, exist_ok = True)
     for fn in (
@@ -163,7 +162,7 @@ def _populate_studio_install(install_dir: Path, runtime: str = "13.1") -> None:
         "mtmd.dll",
     ):
         (rel / fn).write_bytes(b"PE-stub")
-    # The cudart overlay #5322 contributes.
+    # The cudart overlay from #5322.
     for fn in REAL_UPSTREAM_CUDART_BUNDLE[runtime]:
         (rel / fn).write_bytes(b"PE-stub")
 
@@ -173,15 +172,15 @@ def _build_path_dirs_like_start_llama_server(
     prefix: Path,
     cuda_path: str = "",
 ) -> list[str]:
-    """Path-friendly wrapper around LlamaCppBackend._build_windows_path_dirs.
-    Asserting against the staticmethod (not a hand-copy) is the point:
-    if the win32 PATH order drops _windows_pip_nvidia_dll_dirs, tests fail."""
+    """Path-friendly wrapper around _build_windows_path_dirs. Asserting
+    against the real staticmethod (not a hand-copy) is the point: if the
+    win32 PATH order drops _windows_pip_nvidia_dll_dirs, tests fail."""
     return LlamaCppBackend._build_windows_path_dirs(str(binary_dir), str(prefix), cuda_path)
 
 
 def _mock_nvidia_smi_run(fake_output: str, returncode: int = 0) -> "mock._patch":
     """Patch subprocess.run so the nvidia-smi probe returns fake_output;
-    other subprocess.run calls pass through."""
+    other calls pass through."""
     real_run = subprocess.run
 
     def fake_run(cmd, *args, **kwargs):
@@ -199,11 +198,11 @@ def _mock_nvidia_smi_run(fake_output: str, returncode: int = 0) -> "mock._patch"
 # --------------------------------------------------------------------- #
 class TestWindowsGpuDetectionAfter5106Fix:
     """End-to-end #5106 fix on a synthetic Windows layout. nvidia-smi
-    mocked; resolver, PATH builder and install layout exercised live."""
+    mocked; resolver, PATH builder, and install layout run live."""
 
     def test_nvidia_smi_probe_reports_synthetic_gpu(self, monkeypatch):
         """Probe parses CSV output and returns (index, free_mib)."""
-        # Clear inherited masks so the synthetic CSV is not filtered.
+        # Clear inherited masks so the synthetic CSV isn't filtered.
         monkeypatch.delenv("CUDA_VISIBLE_DEVICES", raising = False)
         monkeypatch.delenv("NVIDIA_VISIBLE_DEVICES", raising = False)
         # The #5106 reporter's exact reproducer: RTX 4090, 22805 MiB.
@@ -222,7 +221,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
 
     def test_windows_install_dir_has_all_three_cudart_dlls(self, tmp_path):
         """All three bundle DLLs must land in install_dir/build/bin/
-        Release; missing any one breaks ggml-cuda.dll's PE import chain."""
+        Release; any missing one breaks ggml-cuda.dll's PE import chain."""
         install = tmp_path / "studio_install"
         _populate_studio_install(install, runtime = "13.1")
         rel = install / "build" / "bin" / "Release"
@@ -232,8 +231,8 @@ class TestWindowsGpuDetectionAfter5106Fix:
         assert (rel / "ggml-cuda.dll").exists()
 
     def test_resolver_finds_real_pypi_wheel_layouts(self, tmp_path):
-        """Resolver must pick up every real-world wheel layout:
-        nvidia/<pkg>/bin, nvidia/<pkg>/bin/x86_64, torch/lib."""
+        """Resolver must pick up every wheel layout: nvidia/<pkg>/bin,
+        nvidia/<pkg>/bin/x86_64, torch/lib."""
         prefix = tmp_path / "studio_venv"
         _populate_studio_venv(prefix)
         out = LlamaCppBackend._windows_pip_nvidia_dll_dirs(str(prefix))
@@ -249,8 +248,8 @@ class TestWindowsGpuDetectionAfter5106Fix:
 
     def test_path_assembly_makes_cudart_reachable_without_toolkit(self, tmp_path):
         """The #5106 scenario: GPU detected, pip nvidia wheels present,
-        no system CUDA toolkit. cudart must be reachable from PATH, and
-        from BOTH binary_dir (#5322) and a pip nvidia dir (#5324)."""
+        no system CUDA toolkit. cudart must be reachable from PATH via
+        BOTH binary_dir (#5322) and a pip nvidia dir (#5324)."""
         prefix = tmp_path / "studio_venv"
         install = tmp_path / "studio_install"
         _populate_studio_venv(prefix)
@@ -278,7 +277,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         ), f"#5324's pip nvidia dir not contributing cudart: {cudart_locations}"
 
     def test_cublas_and_cublasLt_also_reachable(self, tmp_path):
-        """ggml-cuda imports cublas64; cublas64 imports cublasLt64. All
+        """ggml-cuda imports cublas64, which imports cublasLt64. All
         three must resolve or LoadLibrary returns NULL."""
         prefix = tmp_path / "studio_venv"
         install = tmp_path / "studio_install"
@@ -293,7 +292,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
             )
 
     def test_no_pip_nvidia_wheels_still_works_via_install_dir(self, tmp_path):
-        """No pip nvidia wheels (CPU-only torch / unsloth run standalone):
+        """No pip nvidia wheels (CPU-only torch / standalone unsloth):
         cudart still resolves via #5322's binary_dir drop."""
         prefix = tmp_path / "bare_venv"
         prefix.mkdir()
@@ -309,7 +308,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
 
     def test_no_install_dir_still_works_via_pip_wheels(self, tmp_path):
         """Pre-#5322 install (binary_dir lacks cudart): #5324's pip
-        wheel directories on PATH still resolve cudart."""
+        wheel dirs on PATH still resolve cudart."""
         prefix = tmp_path / "studio_venv"
         _populate_studio_venv(prefix)
         install = tmp_path / "studio_install_pre5322"
@@ -339,9 +338,9 @@ class TestWindowsGpuDetectionAfter5106Fix:
         assert cublas_reachable, "cublas unreachable on cudart-less install"
 
     def test_pre_pr_scenario_would_have_failed(self, tmp_path):
-        """Negative control: pre-#5322 + pre-#5324 world leaves cudart
+        """Negative control: pre-#5322 + pre-#5324 leaves cudart
         unreachable -- the original failure mode. Confirms the test
-        actually catches a regression."""
+        catches a regression."""
         prefix = tmp_path / "studio_venv"
         _populate_studio_venv(prefix)
         install = tmp_path / "pre_pr_install"
@@ -349,7 +348,7 @@ class TestWindowsGpuDetectionAfter5106Fix:
         rel.mkdir(parents = True)
         for fn in ("llama-server.exe", "llama.dll", "ggml-cuda.dll"):
             (rel / fn).write_bytes(b"PE-stub")
-        # Pre-PR PATH: binary_dir only. No pip nvidia dirs, no toolkit.
+        # Pre-PR PATH: binary_dir only, no pip nvidia dirs, no toolkit.
         pre_pr_path_dirs = [str(rel)]
         cudart_reachable_pre = any(
             (Path(d) / "cudart64_12.dll").exists() or (Path(d) / "cudart64_13.dll").exists()
@@ -362,9 +361,9 @@ class TestWindowsGpuDetectionAfter5106Fix:
 
 
 class TestWindowsSysPlatformMocked:
-    """Confirm the win32 branch in start_llama_server is what we test
-    (not the linux fallback). Patches sys.platform and re-runs the
-    branch-selecting helper."""
+    """Confirm we test the win32 branch in start_llama_server, not the
+    linux fallback. Patches sys.platform and re-runs the branch-selecting
+    helper."""
 
     def test_sys_platform_win32_uses_pip_nvidia_resolver(self, monkeypatch, tmp_path):
         monkeypatch.setattr(sys, "platform", "win32")
diff --git a/studio/backend/utils/cache_cleanup.py b/studio/backend/utils/cache_cleanup.py
index 9d01b40add..4e582ae926 100644
--- a/studio/backend/utils/cache_cleanup.py
+++ b/studio/backend/utils/cache_cleanup.py
@@ -4,11 +4,11 @@
 """
 Utility for cleaning up the Unsloth compiled cache directory.
 
-The unsloth_compiled_cache is created by unsloth_zoo/compiler.py during
-FastModel.from_pretrained() and contains model-type-specific compiled Python
-files. It should be selectively cleared between model loads to avoid stale
-artefacts, while preserving model-agnostic components (like Trainers) needed
-by spawned subprocesses.
+unsloth_compiled_cache is created by unsloth_zoo/compiler.py during
+FastModel.from_pretrained() and holds model-type-specific compiled Python files.
+Clear it selectively between model loads to avoid stale artefacts, while
+preserving model-agnostic components (like Trainers) needed by spawned
+subprocesses.
 """
 
 import shutil
@@ -38,9 +38,8 @@ def get_existing_cache_dirs() -> List[Path]:
 def register_compiled_cache_on_path() -> None:
     """Add all existing compiled-cache directories to sys.path and PYTHONPATH.
 
-    This ensures spawned workers (on platforms using the 'spawn' start method,
-    i.e. Windows and macOS) can import dynamically compiled modules such as
-    UnslothSFTTrainer.
+    Ensures spawned workers (on 'spawn'-start platforms, i.e. Windows and macOS)
+    can import dynamically compiled modules such as UnslothSFTTrainer.
     """
     import os
     import sys
@@ -48,8 +47,8 @@ def register_compiled_cache_on_path() -> None:
     pypath = os.environ.get("PYTHONPATH", "")
     pypath_entries = [p for p in pypath.split(os.pathsep) if p]
 
-    # Iterate in reverse so that earlier _CACHE_DIRS entries (higher priority)
-    # are inserted last and therefore end up first in sys.path / PYTHONPATH.
+    # Iterate in reverse so earlier _CACHE_DIRS entries (higher priority) are
+    # inserted last and thus end up first in sys.path / PYTHONPATH.
     for cache_dir in reversed(get_existing_cache_dirs()):
         resolved = str(cache_dir.resolve())
         if resolved not in sys.path:
@@ -65,7 +64,7 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
     Remove compiled files from the cache directory (idempotent).
 
     Args:
-        preserve_patterns: A list of glob patterns for files to keep
+        preserve_patterns: glob patterns for files to keep
                            (e.g., ["Unsloth*Trainer.py"]). If None or empty,
                            the entire cache directory is deleted (legacy behavior).
     """
@@ -80,7 +79,7 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
 
             for item in cache_dir.iterdir():
                 if item.is_file():
-                    # Check if the file matches any of the patterns we want to keep
+                    # Keep the file if it matches any preserve pattern
                     preserve = any(item.match(pattern) for pattern in preserve_patterns)
                     if not preserve:
                         try:
@@ -92,6 +91,6 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
                     # Always clear __pycache__ and other subdirectories
                     shutil.rmtree(item, ignore_errors = True)
         else:
-            # Legacy behavior: nuke the entire directory
+            # Legacy behavior: remove the entire directory
             logger.info(f"Removing unsloth compiled cache: {cache_dir}")
             shutil.rmtree(cache_dir, ignore_errors = True)
diff --git a/studio/backend/utils/cpu_threads.py b/studio/backend/utils/cpu_threads.py
index 922f95ce55..5cf2ff1ce2 100644
--- a/studio/backend/utils/cpu_threads.py
+++ b/studio/backend/utils/cpu_threads.py
@@ -18,9 +18,9 @@ _THREAD_POOL_ENV_VARS = (
 def configure_cpu_threads(env: Optional[MutableMapping[str, str]] = None) -> None:
     """Apply ``UNSLOTH_CPU_THREADS`` to native CPU pools when configured.
 
-    This must run before importing libraries that initialize an OpenMP or
-    BLAS thread pool. Library-specific variables are left untouched so users
-    can override a single runtime independently.
+    Must run before importing libraries that initialize an OpenMP or BLAS
+    thread pool. Library-specific variables are left untouched so users can
+    override a single runtime independently.
     """
     environ = os.environ if env is None else env
     configured = environ.get("UNSLOTH_CPU_THREADS", "").strip()
diff --git a/studio/backend/utils/datasets/__init__.py b/studio/backend/utils/datasets/__init__.py
index 7988b09972..3ecb085478 100644
--- a/studio/backend/utils/datasets/__init__.py
+++ b/studio/backend/utils/datasets/__init__.py
@@ -2,10 +2,8 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Dataset utilities package.
-
-This package provides utilities for dataset format detection, conversion,
-and processing for LLM and VLM fine-tuning workflows.
+Dataset utilities for LLM/VLM fine-tuning: format detection, conversion,
+and processing.
 
 Modules:
 - format_detection: Detect dataset formats (Alpaca, ShareGPT, ChatML)
@@ -62,8 +60,7 @@ from .model_mappings import (
     is_gpt_oss_model_name,
 )
 
-# Legacy imports from the original dataset_utils.py for backward compatibility
-# These functions have not yet been refactored into separate modules
+# Legacy imports from dataset_utils.py (not yet refactored) for backward compat
 from .dataset_utils import (
     check_dataset_format,
     format_and_template_dataset,
diff --git a/studio/backend/utils/datasets/chat_templates.py b/studio/backend/utils/datasets/chat_templates.py
index cfdd811853..4b8ee93e9c 100644
--- a/studio/backend/utils/datasets/chat_templates.py
+++ b/studio/backend/utils/datasets/chat_templates.py
@@ -1,11 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Chat template application utilities for dataset processing.
+"""Chat template utilities for dataset processing.
 
-This module contains functions for applying chat templates to datasets
-and generating dataset info summaries.
+Apply chat templates to datasets and generate dataset info summaries.
 """
 
 from .format_detection import detect_dataset_format, detect_multimodal_dataset, detect_custom_format_heuristic
@@ -47,29 +45,27 @@ def _chat_template_kwargs() -> dict:
 
 def get_tokenizer_chat_template(tokenizer, model_name):
     """
-    Gets appropriate chat template for tokenizer based on model.
-    Uses Unsloth's get_chat_template if model is in the mapper.
+    Get the chat template for a tokenizer based on the model.
+    Uses Unsloth's get_chat_template if the model is in the mapper.
 
     Args:
         tokenizer: HuggingFace tokenizer
         model_name: Model class name (e.g., "Gemma3ForCausalLM")
 
     Returns:
-        tokenizer: Tokenizer with appropriate chat template applied
+        tokenizer: Tokenizer with the chat template applied
     """
     try:
         from unsloth.chat_templates import get_chat_template
     except ImportError:
-        # Unsloth not available, return tokenizer as-is
+        # Unsloth not available; return tokenizer as-is.
         return tokenizer
 
-    # Normalize model_name to lowercase for matching
     model_name_lower = model_name.lower()
 
-    # Check if model matches any template in mapper
     matched_template = None
 
-    # Direct match in MODEL_TO_TEMPLATE_MAPPER
+    # Direct match in MODEL_TO_TEMPLATE_MAPPER.
     if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
         matched_template = MODEL_TO_TEMPLATE_MAPPER[model_name_lower]
         logger.info(f"📝 Applying Unsloth chat template: {matched_template}")
@@ -83,7 +79,7 @@ def get_tokenizer_chat_template(tokenizer, model_name):
             logger.info(f"⚠️ Failed to apply Unsloth template '{matched_template}': {e}")
             logger.info(f"   Falling back to tokenizer's default chat template")
     else:
-        # Check if tokenizer actually has a chat_template set
+        # Check whether the tokenizer has a chat_template set.
         has_chat_template = (
             hasattr(tokenizer, 'chat_template')
             and tokenizer.chat_template is not None
@@ -91,7 +87,7 @@ def get_tokenizer_chat_template(tokenizer, model_name):
         if has_chat_template:
             logger.info(f"📝 Using tokenizer's own chat template (no Unsloth template match)")
         else:
-            # Base model with no chat template — apply default ChatML
+            # Base model with no chat template — apply default ChatML.
             logger.info(f"📝 No chat template found — applying default ChatML template (base model)")
             try:
                 tokenizer = get_chat_template(
@@ -107,9 +103,7 @@ def get_tokenizer_chat_template(tokenizer, model_name):
 
 
 def get_dataset_info_summary(dataset_info):
-    """
-    Returns a human-readable summary for UI display.
-    """
+    """Return a human-readable summary for UI display."""
     detected_format = dataset_info["detected_format"]
     final_format = dataset_info["final_format"]
 
@@ -147,14 +141,14 @@ def apply_chat_template_to_dataset(
     progress_callback = None,
 ):
     """
-    Applies chat template to dataset based on its format.
+    Apply the chat template to a dataset based on its format.
 
     Args:
         dataset_info: Output from format_dataset() with metadata
         tokenizer: Tokenizer with chat template
         custom_prompt_template: Optional string template for custom formatting
-        add_eos_token: If True, appends tokenizer.eos_token to each text
-        remove_bos_prefix: If True, removes '<bos>' prefix (for Gemma, etc.)
+        add_eos_token: If True, append tokenizer.eos_token to each text
+        remove_bos_prefix: If True, remove '<bos>' prefix (Gemma, etc.)
         custom_format_mapping: Dict mapping custom columns to standard format
         batch_size: Batch size for processing
         num_proc: Number of processes
@@ -170,7 +164,7 @@ def apply_chat_template_to_dataset(
     warnings = list(dataset_info.get("warnings", []))
     errors = []
 
-    # Get EOS token if needed
+    # Get EOS token if needed.
     eos_token = ""
     if add_eos_token:
         if hasattr(tokenizer, 'eos_token') and tokenizer.eos_token:
@@ -180,9 +174,9 @@ def apply_chat_template_to_dataset(
 
     # CUSTOM FORMAT MAPPING (for non-standard datasets)
     if final_format == "unknown":
-        # Try auto-detection if no custom mapping provided
+        # Auto-detect if no custom mapping was provided.
         if custom_format_mapping is None and auto_detect_mapping:
-            # Check if format_dataset already tried and failed
+            # Skip if format_dataset already tried and failed.
             if not dataset_info.get("auto_detection_attempted", False):
                 custom_format_mapping = detect_custom_format_heuristic(dataset)
                 if custom_format_mapping:
@@ -196,7 +190,7 @@ def apply_chat_template_to_dataset(
                         "errors": errors
                     }
             else:
-                # Already failed once in format_dataset, don't retry
+                # Already failed once in format_dataset; don't retry.
                 errors.append(
                     "Format remains unknown after detection attempts. "
                     "Please provide custom_format_mapping to specify column roles manually."
@@ -216,7 +210,7 @@ def apply_chat_template_to_dataset(
                 conversations = []
                 num_examples = len(examples[list(examples.keys())[0]])
 
-                # Only preserve unmapped columns if auto-detected
+                # Preserve unmapped columns only if auto-detected.
                 preserved_columns = {}
                 if not is_user_provided:
                     all_columns = set(examples.keys())
@@ -236,10 +230,10 @@ def apply_chat_template_to_dataset(
                                 content = examples[col_name][i]
 
                                 if is_user_provided:
-                                    # User explicitly mapped - include even if empty
+                                    # User-mapped: include even if empty.
                                     convo.append({"role": role, "content": str(content) if content else ""})
                                 else:
-                                    # Auto-detected - skip empty
+                                    # Auto-detected: skip empty.
                                     if content and str(content).strip():
                                         convo.append({"role": role, "content": str(content)})
 
@@ -252,7 +246,7 @@ def apply_chat_template_to_dataset(
 
             try:
                 dataset = dataset.map(_apply_custom_mapping, batched = True, batch_size = batch_size)
-                # Update to use conversations format
+                # Switch to conversations format.
                 final_format = "chatml_conversations"
                 chat_column = "conversations"
                 is_standardized = True
@@ -269,8 +263,8 @@ def apply_chat_template_to_dataset(
     # ALPACA FORMAT
     if final_format == "alpaca":
 
-        # Set alpaca chat template on tokenizer for saving (if not already set)
-        # This ensures the template is saved with the model for inference
+        # Set alpaca chat template on the tokenizer (if unset) so it's
+        # saved with the model for inference.
         if not (hasattr(tokenizer, 'chat_template') and tokenizer.chat_template):
             try:
                 from unsloth.chat_templates import get_chat_template
@@ -283,7 +277,7 @@ def apply_chat_template_to_dataset(
             except Exception as e:
                 logger.info(f"⚠️ Could not set alpaca template on tokenizer: {e}")
 
-        # Use custom template if provided
+        # Use custom template if provided.
         def _format_alpaca_custom(examples):
             texts = []
             for i in range(len(examples["instruction"])):
@@ -349,7 +343,7 @@ def apply_chat_template_to_dataset(
         if not is_standardized:
             warnings.append("Dataset may not be fully standardized")
 
-        # Apply Unsloth chat template if model matches
+        # Apply Unsloth chat template if the model matches.
         if model_name:
             tokenizer = get_tokenizer_chat_template(tokenizer, model_name)
 
@@ -398,7 +392,7 @@ def apply_chat_template_to_dataset(
                 dataset_map_kwargs['num_proc'] = num_proc
                 dataset_map_kwargs['desc'] = f"Applying chat template to {final_format}"
 
-            # Monitor tqdm progress from dataset.map() and relay to callback
+            # Monitor tqdm progress from dataset.map() and relay it.
             _tqdm_monitor_stop = None
             if progress_callback and not _is_torch_iterable:
                 import threading
diff --git a/studio/backend/utils/datasets/data_collators.py b/studio/backend/utils/datasets/data_collators.py
index 2955ec9023..5f249b32f9 100644
--- a/studio/backend/utils/datasets/data_collators.py
+++ b/studio/backend/utils/datasets/data_collators.py
@@ -4,8 +4,7 @@
 """
 Data collators for dataset processing.
 
-This module contains custom data collators for training,
-particularly for VLM/OCR processing.
+Custom training collators, particularly for VLM/OCR processing.
 """
 
 from dataclasses import dataclass
@@ -20,9 +19,9 @@ class DataCollatorSpeechSeq2SeqWithPadding:
     """
     Data collator for Whisper speech-to-text training.
 
-    Pads input features (audio) and label sequences (text) separately,
-    masks padding in labels with -100, and strips leading BOS token.
-    Mirrors the collator from the Whisper.ipynb notebook.
+    Pads audio input features and text labels separately, masks label padding
+    with -100, and strips the leading BOS token. Mirrors the Whisper.ipynb
+    notebook collator.
     """
 
     processor: Any
@@ -71,7 +70,7 @@ class DeepSeekOCRDataCollator:
         """
         from PIL import Image
 
-        # Extract messages and images
+        # Extract messages and images.
         all_messages = []
         all_images = []
 
@@ -79,7 +78,7 @@ class DeepSeekOCRDataCollator:
             messages = sample["messages"]
             all_messages.append(messages)
 
-            # Extract PIL images from content
+            # Extract PIL images from content.
             for msg in messages:
                 content = msg.get("content", [])
                 if isinstance(content, list):
@@ -89,9 +88,9 @@ class DeepSeekOCRDataCollator:
                             if img is not None and hasattr(img, "size"):  # PIL Image
                                 all_images.append(img)
 
-        # Process with the VL processor
+        # Process with the VL processor.
         try:
-            # Qwen2VL style processing
+            # Qwen2VL-style processing.
             texts = [
                 self.processor.apply_chat_template(
                     msgs, tokenize = False, add_generation_prompt = False
@@ -99,7 +98,7 @@ class DeepSeekOCRDataCollator:
                 for msgs in all_messages
             ]
 
-            # Process with images
+            # Process with images.
             inputs = self.processor(
                 text = texts,
                 images = all_images if all_images else None,
@@ -109,10 +108,10 @@ class DeepSeekOCRDataCollator:
                 max_length = self.max_length,
             )
 
-            # Create labels (mask input, keep output)
+            # Create labels (mask input, keep output).
             labels = inputs["input_ids"].clone()
 
-            # Simple masking: mask padding tokens
+            # Mask padding tokens.
             labels[labels == self.processor.tokenizer.pad_token_id] = self.ignore_index
 
             inputs["labels"] = labels
@@ -138,7 +137,7 @@ class VLMDataCollator:
     processor: Any
     max_length: int = 2048
     ignore_index: int = -100
-    mask_input_tokens: bool = True  # Whether to mask user tokens in labels
+    mask_input_tokens: bool = True  # Mask user tokens in labels
 
     def __call__(self, batch: List[dict]) -> dict:
         """
@@ -151,7 +150,7 @@ class VLMDataCollator:
             messages = sample.get("messages", [])
             all_messages.append(messages)
 
-            # Extract images
+            # Extract images.
             for msg in messages:
                 content = msg.get("content", [])
                 if isinstance(content, list):
@@ -161,13 +160,13 @@ class VLMDataCollator:
                             if img is not None:
                                 all_images.append(img)
 
-        # Apply chat template
+        # Apply chat template.
         texts = [
             self.processor.apply_chat_template(msgs, tokenize = False, add_generation_prompt = False)
             for msgs in all_messages
         ]
 
-        # Process inputs
+        # Process inputs.
         inputs = self.processor(
             text = texts,
             images = all_images if all_images else None,
@@ -177,10 +176,10 @@ class VLMDataCollator:
             max_length = self.max_length,
         )
 
-        # Create labels
+        # Create labels.
         labels = inputs["input_ids"].clone()
 
-        # Mask padding
+        # Mask padding.
         if hasattr(self.processor, "tokenizer"):
             pad_token_id = self.processor.tokenizer.pad_token_id
         else:
diff --git a/studio/backend/utils/datasets/dataset_none_detect.py b/studio/backend/utils/datasets/dataset_none_detect.py
index e48e153fb8..354fd360d3 100644
--- a/studio/backend/utils/datasets/dataset_none_detect.py
+++ b/studio/backend/utils/datasets/dataset_none_detect.py
@@ -1,8 +1,8 @@
 """
 dataset_none_detect.py
 
-Detect None/empty content turns in conversation datasets.
-Reports findings without modifying data.
+Detect None/empty content turns in conversation datasets. Reports findings
+without modifying data.
 
 Usage:
     from .dataset_none_detect import scan_dataset, print_report
@@ -18,8 +18,8 @@ Supported formats (via FORMAT_REGISTRY):
     sharegpt   conversations                 from/value per turn
     gptoss     messages (alias: gpt-oss)     role/content; has a developer turn
 
-Any role/content chat template matches the chatml entry, so new templates need
-no change; add a FORMAT_REGISTRY entry only for a genuinely new column/turn shape.
+Any role/content chat template matches chatml, so new templates need no change;
+add a FORMAT_REGISTRY entry only for a genuinely new column/turn shape.
 """
 
 from datasets import Dataset
@@ -31,7 +31,7 @@ from datasets import Dataset
 # Candidate column names for conversational datasets, checked in priority order.
 CONVERSATION_COLUMNS = ("messages", "conversations", "texts")
 
-# Minimum turn key sets that identify a column as conversational (not e.g. messages=[{"id":1}]).
+# Minimum turn key sets identifying a column as conversational (not e.g. messages=[{"id":1}]).
 _CHAT_KEY_SETS = (frozenset({"role", "content"}), frozenset({"from", "value"}))
 
 
@@ -39,13 +39,13 @@ def _probe_conversation(dataset: Dataset, candidates = None):
     """
     Probe a dataset for its conversation column and turn structure.
 
-    candidates - iterable of column names to try, in priority order.
+    candidates - column names to try, in priority order.
                  Defaults to CONVERSATION_COLUMNS when None.
 
     Returns a dict with:
-        column    - name of the conversation column found
-        turn_keys - set of keys present in the first turn dict
-        roles     - set of all role values seen across the first few samples
+        column    - conversation column found
+        turn_keys - keys present in the first turn dict
+        roles     - all role values seen across the first few samples
 
     Returns None if no conversation column is found.
     """
@@ -53,12 +53,12 @@ def _probe_conversation(dataset: Dataset, candidates = None):
         candidates = CONVERSATION_COLUMNS
     columns = set(dataset.column_names)
     # Remember the first all-corrupt candidate, but keep probing: a later column
-    # may be healthy and should win (e.g. bad messages, good conversations).
+    # may be healthy and win (e.g. bad messages, good conversations).
     all_corrupt_fallback = None
     for col in candidates:
         if col not in columns:
             continue
-        # Scan up to 100 rows - row 0 alone may be empty or malformed.
+        # Scan up to 100 rows - row 0 alone may be empty/malformed.
         first = None
         for i in range(min(len(dataset), 100)):
             sample = dataset[i][col]
@@ -71,9 +71,9 @@ def _probe_conversation(dataset: Dataset, candidates = None):
                 break
         if first is None:
             # No usable dict turn in 100 rows. Record an all_corrupt fallback,
-            # marking it plausible only if we saw turn-shaped data (a None cell or
-            # a list holding a dict/None turn); scalars and list-of-strings must
-            # not look like chatml. Upgrade a non-plausible fallback when a later
+            # plausible only if we saw turn-shaped data (a None cell or a list
+            # holding a dict/None turn); scalars and list-of-strings must not
+            # look like chatml. Upgrade a non-plausible fallback when a later
             # candidate is plausible, so probe order keeps the best match.
             if all_corrupt_fallback is None or not all_corrupt_fallback.get("has_plausible_turns"):
                 has_plausible_turns = False
@@ -86,8 +86,8 @@ def _probe_conversation(dataset: Dataset, candidates = None):
                     # not chat: leave it for "unknown format", matching
                     # format_detection.py.
                     if isinstance(cell, list):
-                        # Plausible only if the list holds a dict/None turn; empty
-                        # lists and list-of-strings are not chat data.
+                        # Plausible only if the list holds a dict/None turn;
+                        # empty lists and list-of-strings are not chat data.
                         if any(t is None or isinstance(t, dict) for t in cell):
                             has_plausible_turns = True
                             break
@@ -112,11 +112,11 @@ def _probe_conversation(dataset: Dataset, candidates = None):
                         r = t.get("role") or t.get("from")
                         if r:
                             roles.add(str(r))
-        # Column lacks a full chat key pair. If it still has a conversational key
-        # (role/from/content/value) it is a corrupt-but-real chat column, so save
-        # a plausible fallback for find_none_chatml to flag. Pure metadata (e.g.
-        # [{"id":1}]) is not plausible, so a later real-but-corrupt column (e.g.
-        # conversations=None) can still win.
+        # Column lacks a full chat key pair. If it has a conversational key
+        # (role/from/content/value) it is a corrupt-but-real chat column, so
+        # save a plausible fallback for find_none_chatml to flag. Pure metadata
+        # (e.g. [{"id":1}]) is not plausible, so a later real-but-corrupt column
+        # (e.g. conversations=None) can still win.
         _CONV_KEYS = {"role", "from", "content", "value"}
         if not any(keys <= turn_keys for keys in _CHAT_KEY_SETS):
             schema_less_plausible = bool(turn_keys & _CONV_KEYS)
@@ -143,7 +143,7 @@ def is_none_or_empty(value) -> bool:
     if value is None:
         return True
     if isinstance(value, str):
-        # Treat zero-width/BOM chars (U+FEFF/200B/200C/200D/2060) as empty too;
+        # Treat zero-width/BOM chars (U+FEFF/200B/200C/200D/2060) as empty;
         # they render invisibly. Two-pass strip (ws, invisibles, ws) catches
         # mixed cases like "\u200b \u200b".
         stripped = value.strip().strip("\ufeff\u200b\u200c\u200d\u2060").strip()
@@ -156,7 +156,7 @@ def is_none_or_empty(value) -> bool:
         # exists (an image-only turn is valid).
         if len(value) == 0:
             return True
-        # No dict blocks at all (e.g. [None], ['  ']) -> malformed/empty.
+        # No dict blocks (e.g. [None], ['  ']) -> malformed/empty.
         dict_blocks = [item for item in value if isinstance(item, dict)]
         if not dict_blocks:
             return True
@@ -190,7 +190,7 @@ def _classify_empty(value) -> str:
         if len(value) == 0:
             return "empty_list"
         return "empty_vlm_content"
-    return "valid"  # should not reach here if is_none_or_empty was True
+    return "valid"  # unreachable if is_none_or_empty was True
 
 
 # ---------------------------------------------------------------------------
@@ -201,7 +201,7 @@ def _classify_empty(value) -> str:
 def find_none_alpaca(dataset: Dataset) -> dict:
     """
     Scan alpaca dataset for None/empty instruction or output fields.
-    Returns stats dict with a detailed 'findings' list.
+    Returns a stats dict with a detailed 'findings' list.
     """
     stats = {
         "total_rows": len(dataset),
@@ -242,8 +242,8 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
     Scan chatml/sharegpt/gptoss dataset for turns with None/empty content.
     Auto-detects the conversation column if col=None.
 
-    Returns a stats dict that includes a complete 'findings' list - one entry
-    per bad turn with row_index, turn_index, role, value_type, and raw_value.
+    Returns a stats dict with a complete 'findings' list - one entry per bad
+    turn with row_index, turn_index, role, value_type, and raw_value.
     """
     if col is None:
         # Reuse _probe_conversation so the all_corrupt path is handled here too.
@@ -292,7 +292,7 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
             continue
 
         if len(conversation) == 0:
-            # Zero-turn conversation: flag so it does not scan as clean.
+            # Zero-turn conversation: flag so it doesn't scan as clean.
             stats["bad_row_indices"].append(i)
             stats["rows_with_none_turns"] += 1
             stats["total_none_turns"] += 1
@@ -340,8 +340,8 @@ def find_none_chatml(dataset: Dataset, col: str = None) -> dict:
                 role = r
             else:
                 role = str(r)
-            # Pick the content key: from+value -> value (ShareGPT, even if role is
-            # also set); role -> content (or value); from only -> value (None when
+            # Pick the content key: from+value -> value (ShareGPT, even if role
+            # is set); role -> content (or value); from only -> value (None when
             # missing, so it is flagged); neither -> content then value.
             if "from" in turn and "value" in turn:
                 content = turn.get("value")
@@ -388,7 +388,7 @@ def find_none_sharegpt(dataset: Dataset, col: str = None) -> dict:
     """ShareGPT uses 'from'/'value' keys - same scan logic handles both."""
     if col is None:
         # ShareGPT lives in 'conversations'; probe only that column so a corrupt
-        # one is still scanned, not replaced by a healthy 'messages' (P1 fix).
+        # one is still scanned, not replaced by healthy 'messages' (P1 fix).
         conv_info = _probe_conversation(dataset, candidates = ("conversations",))
         if conv_info is None:
             raise ValueError(
@@ -403,7 +403,7 @@ def find_none_gptoss(dataset: Dataset, col: str = None) -> dict:
     """gptoss: role/content plus optional thinking/tool_calls. Only content checked."""
     if col is None:
         # gptoss lives in 'messages': target it whenever present (even if
-        # corrupt), and fall back to 'conversations' only if 'messages' is absent.
+        # corrupt); fall back to 'conversations' only if 'messages' is absent.
         if "messages" in dataset.column_names:
             conv_info = _probe_conversation(dataset, candidates = ("messages",))
         else:
@@ -420,7 +420,7 @@ def find_none_gptoss(dataset: Dataset, col: str = None) -> dict:
 # ---------------------------------------------------------------------------
 # Format registry - first match wins; detect_format() auto-scales.
 # Each entry: name (label/--format value), match(dataset, conv_info) -> bool,
-# scan (find_none_* function). Put specific formats before generalisations
+# scan (find_none_* function). Put specific formats before general ones
 # (gptoss before chatml, since gptoss is chatml with a 'developer' role).
 # To add a format: write find_none_<name>() (or reuse find_none_chatml) and
 # append an entry; detect_format(), --format, and scan_dataset() pick it up.
@@ -460,7 +460,7 @@ FORMAT_REGISTRY = [
             and (
                 {"role", "content"} <= conv["turn_keys"]
                 # all_corrupt: column found but every row malformed; require
-                # has_plausible_turns so scalar/string columns are not chatml.
+                # has_plausible_turns so scalar/string columns aren't chatml.
                 or (conv.get("all_corrupt") and conv.get("has_plausible_turns"))
             )
         ),
@@ -479,7 +479,7 @@ def detect_format(dataset: Dataset) -> str:
     """
     Auto-detect dataset format by probing columns and turn structure.
 
-    Returns one of the format names in FORMAT_REGISTRY, or 'unknown'.
+    Returns a format name from FORMAT_REGISTRY, or 'unknown'.
     Walks the registry in order; first match wins.
     """
     conv_info = _probe_conversation(dataset)
@@ -507,7 +507,7 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
     # Reject a DatasetDict / IterableDatasetDict (load_dataset without split):
     # its column_names is a split map and would yield a confusing "unknown
     # format". Check both (IterableDatasetDict is not a DatasetDict subclass);
-    # import locally so this module never hard-requires those symbols.
+    # import locally so this module never hard-requires them.
     _dict_types = []
     try:
         from datasets import DatasetDict as _DatasetDict
@@ -526,7 +526,7 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
             "Pass dataset[<split>] or use load_dataset(..., split='train')."
         )
     # Streaming IterableDataset has no len()/column_names; give a clear error
-    # instead of a confusing TypeError downstream.
+    # instead of a confusing downstream TypeError.
     try:
         from datasets import IterableDataset as _IterableDataset
         if isinstance(dataset, _IterableDataset):
@@ -555,8 +555,8 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
             if entry["match"](dataset, conv_info):
                 fmt = entry["name"]
                 break
-        # No format matched: return clean stats (format="unknown") rather than
-        # raise, so callers can branch on stats["format"].
+        # No format matched: return clean stats (format="unknown") instead of
+        # raising, so callers can branch on stats["format"].
         if fmt == "unknown":
             return {
                 "format": "unknown",
@@ -567,7 +567,7 @@ def scan_dataset(dataset: Dataset, fmt: str = "auto") -> dict:
     scanner = get_scanner(fmt)
     if scanner is None:
         raise ValueError(f"Unknown or unsupported format: '{fmt}'")
-    # Column forwarding: on auto-detect pass the probed column (already the best
+    # Column forwarding: on auto-detect pass the probed column (the best
     # choice). On an explicit format let that scanner pick its own column, so
     # e.g. fmt='sharegpt' always scans 'conversations', not 'messages' (P1 fix);
     # gptoss has its own messages-first rule. alpaca never takes a column.
@@ -620,7 +620,7 @@ def _print_summary_header(stats: dict, fmt: str) -> bool:
         if rows_all:
             print(f"  Rows ALL bad: {rows_all} (every turn is None/empty)")
 
-    # Rows with no Nones - compute the count directly instead of allocating a
+    # Rows with no Nones - compute the count directly rather than allocating a
     # full set of row indices, which OOMs on large (10M+ row) datasets.
     bad_indices = set(stats.get("bad_row_indices", []))
     clean_count = total - len(bad_indices)
@@ -696,8 +696,8 @@ def show_row(
         print(f"  Row {ri}")
         print(f"{'=' * 64}")
 
-        # Print non-conversation columns. For alpaca, skip the fields the
-        # alpaca block below prints with status markers (avoid double render).
+        # Print non-conversation columns. For alpaca, skip fields the alpaca
+        # block below prints with status markers (avoid double render).
         _ALPACA_FIELDS = {"instruction", "input", "output"}
         for key in dataset.column_names:
             if key == col:
@@ -732,7 +732,7 @@ def show_row(
                         c = t.get("value")
                     else:
                         c = t.get("content") if "content" in t else t.get("value")
-                    # Mirror scanner logic: tool_calls exemption is assistant-only;
+                    # Mirror scanner: tool_calls exemption is assistant-only;
                     # other roles with empty content + tool_calls are still bad.
                     r = t.get("role") if t.get("role") is not None else t.get("from")
                     if is_none_or_empty(c) and not (str(r) == "assistant" and t.get("tool_calls")):
@@ -743,7 +743,7 @@ def show_row(
                 print(f"  {col}: {len(conversation)} turns ({none_count} None)")
                 print(f"  {'-' * 60}")
                 for i, turn in enumerate(conversation):
-                    # Non-dict turn - can't extract role or content normally.
+                    # Non-dict turn - can't extract role/content normally.
                     if not isinstance(turn, dict):
                         label = "None" if turn is None else "invalid_type"
                         print(f"  [{i:>3d}] {'unknown':<12s} [{label}]  << NONE")
diff --git a/studio/backend/utils/datasets/dataset_utils.py b/studio/backend/utils/datasets/dataset_utils.py
index 792e0ea9bc..03387e5331 100644
--- a/studio/backend/utils/datasets/dataset_utils.py
+++ b/studio/backend/utils/datasets/dataset_utils.py
@@ -4,12 +4,12 @@
 """
 Dataset utilities for format detection, conversion, and template application.
 
-This module provides the main entry points for dataset processing:
-- check_dataset_format: Lightweight check if manual mapping is needed (for frontend)
-- format_dataset: Detects and normalizes dataset formats
-- format_and_template_dataset: End-to-end processing with chat template application
+Main entry points for dataset processing:
+- check_dataset_format: lightweight check if manual mapping is needed (frontend)
+- format_dataset: detects and normalizes dataset formats
+- format_and_template_dataset: end-to-end processing with chat template
 
-All internal utilities have been moved to separate modules:
+Internal utilities live in separate modules:
 - format_detection: detect_dataset_format, detect_multimodal_dataset, etc.
 - format_conversion: standardize_chat_format, convert_chatml_to_alpaca, etc.
 - chat_templates: apply_chat_template_to_dataset, get_tokenizer_chat_template, etc.
@@ -54,8 +54,8 @@ def check_dataset_format(dataset, is_vlm: bool = False) -> dict:
     """
     Lightweight format check without processing - for frontend validation.
 
-    Use this to quickly determine if user needs to manually map columns
-    before calling the full format_and_template_dataset().
+    Quickly determines if the user must manually map columns before the full
+    format_and_template_dataset().
 
     Args:
         dataset: HuggingFace dataset
@@ -121,7 +121,7 @@ def check_dataset_format(dataset, is_vlm: bool = False) -> dict:
         }
 
     if is_audio:
-        # Audio dataset — require manual mapping only when columns can't be auto-detected
+        # Audio dataset — require manual mapping only when columns aren't auto-detected
         detected_audio = multimodal_info.get("detected_audio_column")
         detected_text = multimodal_info.get("detected_text_column")
         needs_mapping = not detected_audio or not detected_text
@@ -211,9 +211,9 @@ def _apply_user_mapping(
     Apply user-provided column mapping to convert dataset to conversations format.
 
     Accepts chatml (user/assistant/system), sharegpt (human/gpt/system), and
-    alpaca (instruction/input/output) role names — all normalised to chatml output.
+    alpaca (instruction/input/output) role names — all normalised to chatml.
 
-    If the mapping contains ``__``-prefixed metadata keys (from the conversion
+    If the mapping has ``__``-prefixed metadata keys (from the conversion
     advisor), routes to template-based conversion instead of simple role mapping.
 
     Returns:
@@ -262,7 +262,7 @@ def _apply_user_mapping(
 
 def _extract_column_value(val, col: str, label_mapping: dict) -> str:
     """Extract a string value from a column, handling complex types and label mapping."""
-    # Handle complex types (dicts, lists) — extract useful text instead of raw repr
+    # Complex types (dicts, lists): extract useful text instead of raw repr
     if isinstance(val, dict):
         # Common pattern: {"text": [...]} in QA datasets
         if "text" in val:
@@ -291,10 +291,9 @@ def _apply_template_mapping(
     """
     Apply advisor-driven mapping for non-conversational datasets.
 
-    Groups columns by their assigned role (user/assistant), concatenates
-    values within each role into a single message, and injects an optional
-    system prompt.  Label mapping is applied to convert integer labels
-    to human-readable strings.
+    Groups columns by assigned role (user/assistant), concatenates values
+    within each role into one message, and injects an optional system prompt.
+    Label mapping converts integer labels to human-readable strings.
 
     Returns:
         Dataset with single 'conversations' column
@@ -327,7 +326,7 @@ def _apply_template_mapping(
             if system_prompt:
                 convo.append({"role": "system", "content": system_prompt})
 
-            # User message: concatenate all user-role column values
+            # User message: concatenate user-role column values
             user_parts = []
             for col in role_groups["user"]:
                 if col in examples:
@@ -335,7 +334,7 @@ def _apply_template_mapping(
             if user_parts:
                 convo.append({"role": "user", "content": "\n".join(user_parts)})
 
-            # Assistant message: concatenate all assistant-role column values
+            # Assistant message: concatenate assistant-role column values
             asst_parts = []
             for col in role_groups["assistant"]:
                 if col in examples:
@@ -433,7 +432,7 @@ def format_dataset(
             "final_format": final format after processing,
             "chat_column": column name with chat data,
             "is_standardized": whether role names are standardized,
-            "requires_manual_mapping": True if format detection failed and user must map columns,
+            "requires_manual_mapping": True if detection failed and user must map columns,
             "warnings": list of warning messages
         }
     """
@@ -455,7 +454,7 @@ def format_dataset(
             "warnings": [notice.message for notice in raw_result.notices],
         }
 
-    # If user provided explicit mapping, skip detection and apply in the requested format
+    # If user provided explicit mapping, skip detection and apply it
     if custom_format_mapping:
         try:
             if format_type == "alpaca":
@@ -465,8 +464,8 @@ def format_dataset(
                 final_format = "alpaca"
                 chat_column = None
             else:
-                # auto / chatml / sharegpt / conversational — all produce chatml conversations
-                # (sharegpt is always standardized to role/content internally)
+                # auto / chatml / sharegpt / conversational all produce chatml
+                # conversations (sharegpt standardized to role/content internally)
                 mapped_dataset = _apply_user_mapping(dataset, custom_format_mapping, batch_size)
                 final_format = "chatml_conversations"
                 chat_column = "conversations"
@@ -577,11 +576,11 @@ def format_dataset(
                 "warnings": warnings,
             }
 
-        # Unknown - try standardization, if fails pass as is
+        # Unknown - try standardization, pass as-is on failure
         else:
             warnings.append(f"Unknown format detected. Keys found: {detected['sample_keys']}")
 
-            # NEW: Try heuristic detection
+            # Try heuristic detection
             if auto_detect_custom:
                 custom_mapping = detect_custom_format_heuristic(dataset)
                 if custom_mapping:
@@ -853,8 +852,8 @@ def format_and_template_dataset(
     progress_callback = None,
 ):
     """
-    Convenience function that combines format_dataset and apply_chat_template_to_dataset.
-    Perfect for UI workflows - one function does everything!
+    Combines format_dataset and apply_chat_template_to_dataset. Convenient for
+    UI workflows: one function does everything.
 
     Returns:
         dict: {
@@ -862,7 +861,7 @@ def format_and_template_dataset(
             "detected_format": Original format,
             "final_format": Format after processing,
             "success": Whether template application succeeded,
-            "requires_manual_mapping": True if format detection failed and user must map columns,
+            "requires_manual_mapping": True if detection failed and user must map columns,
             "warnings": List of warnings,
             "errors": List of errors,
             "summary": Human-readable summary
@@ -876,7 +875,7 @@ def format_and_template_dataset(
 
         multimodal_info = detect_multimodal_dataset(dataset)
 
-        # NEW: If user provided explicit mapping for VLM, use it directly
+        # If user provided explicit mapping for VLM, use it directly
         if custom_format_mapping:
             # Expect mapping like: {"image_col": "image", "caption_col": "text"}
             user_vlm_image_column = None
@@ -916,15 +915,15 @@ def format_and_template_dataset(
                         "errors": [],
                     }
                 except Exception as e:
-                    # User mapping failed — fall back to auto-detection instead
-                    # of giving up (handles stale cached mappings gracefully)
+                    # User mapping failed — fall back to auto-detection rather
+                    # than give up (handles stale cached mappings gracefully)
                     warnings.append(
                         f"User VLM mapping (image='{user_vlm_image_column}', "
                         f"text='{user_vlm_text_column}') failed: {e} — "
                         f"falling back to auto-detection"
                     )
                     logger.info(f"⚠️ User VLM mapping failed, falling back to auto-detection...")
-                    custom_format_mapping = None  # clear so auto-detection runs below
+                    custom_format_mapping = None  # so auto-detection runs below
             else:
                 errors.append(
                     f"Invalid VLM mapping: need 'image' and 'text' roles. Got: {custom_format_mapping}"
@@ -967,7 +966,7 @@ def format_and_template_dataset(
                     "errors": errors,
                 }
 
-        # Handle ShareGPT/ChatML + image column (e.g. ShareGPT4V, LLaVA-style)
+        # ShareGPT/ChatML + image column (e.g. ShareGPT4V, LLaVA-style)
         elif vlm_structure["format"] == "sharegpt_with_images":
             try:
                 dataset = convert_sharegpt_with_images_to_vlm_format(
@@ -1087,7 +1086,7 @@ def format_and_template_dataset(
             "errors": errors,
         }
 
-    # LLM FLOW (Existing code)
+    # LLM FLOW
     else:
         # Step 1: Format the dataset
         n_rows = len(dataset) if hasattr(dataset, "__len__") else None
@@ -1127,7 +1126,7 @@ def format_and_template_dataset(
             progress_callback(
                 status_message = f"Applying chat template to {detected} ({n_rows:,} rows)..."
             )
-        # Gemma emits a leading <bos> that must be stripped for text-only chatml/sharegpt.
+        # Gemma emits a leading <bos>, stripped for text-only chatml/sharegpt.
         is_alpaca = format_type == "alpaca" or (
             format_type == "auto" and dataset_info["detected_format"] == "alpaca"
         )
@@ -1156,7 +1155,7 @@ def format_and_template_dataset(
         all_errors = template_result.get("errors", [])
 
         # If format_dataset returned "unknown" but apply_chat_template rescued
-        # it via heuristic detection, update final_format to reflect reality.
+        # it via heuristic detection, update final_format accordingly.
         final_format = dataset_info["final_format"]
         requires_manual = dataset_info.get("requires_manual_mapping", False)
         if final_format == "unknown" and template_result["success"]:
@@ -1170,7 +1169,7 @@ def format_and_template_dataset(
             "detected_format": dataset_info["detected_format"],
             "final_format": final_format,
             "chat_column": dataset_info.get("chat_column"),
-            "is_vlm": False,  # This is LLM flow
+            "is_vlm": False,  # LLM flow
             "success": template_result["success"],
             "requires_manual_mapping": requires_manual,
             "warnings": all_warnings,
diff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.py
index 5433d3115c..09521e160c 100644
--- a/studio/backend/utils/datasets/format_conversion.py
+++ b/studio/backend/utils/datasets/format_conversion.py
@@ -2,10 +2,8 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """
-Format conversion utilities for dataset processing.
-
-This module contains functions for converting between dataset formats
-(Alpaca, ShareGPT, ChatML) and standardizing chat formats.
+Dataset format conversion: convert between Alpaca, ShareGPT, and ChatML,
+and standardize chat formats.
 """
 
 import os
@@ -36,14 +34,14 @@ def standardize_chat_format(
     num_proc = None,
 ):
     """
-    Our own standardization function that handles BOTH messages and conversations.
-    Converts non-standard role names and keys to standard format.
+    Standardize BOTH messages and conversations: map non-standard role
+    names and keys to the standard format.
     """
     import collections
     import itertools
     from datasets import IterableDataset
 
-    # Check if vision tokenizer is used
+    # Detect a vision tokenizer
     is_vlm = False
     if tokenizer is not None:
         if hasattr(tokenizer, "image_processor") or hasattr(tokenizer, "tokenizer"):
@@ -51,7 +49,7 @@ def standardize_chat_format(
 
     column_names = set(next(iter(dataset)).keys())
 
-    #   Check for both 'conversations' and 'messages'
+    # Find the chat column
     chat_column = None
     if "conversations" in column_names:
         chat_column = "conversations"
@@ -69,7 +67,7 @@ def standardize_chat_format(
         for message in example[chat_column]:
             for key, value in message.items():
                 if type(value) is not str:
-                    continue  # Skip non-string values
+                    continue  # Skip non-strings
                 uniques[key].append(value)
 
     if len(uniques.keys()) != 2:
@@ -79,7 +77,7 @@ def standardize_chat_format(
     length_first = len(set(uniques[keys[0]]))
     length_second = len(set(uniques[keys[1]]))
 
-    # Determine which is role and which is content
+    # Fewer unique values => role; the other => content
     if length_first < length_second:
         role_key = keys[0]
         content_key = keys[1]
@@ -102,18 +100,15 @@ def standardize_chat_format(
         for convo in convos:
             new_convo = []
             for message in convo:
-                # Get original role and content
                 original_role = message.get(role_key, "")
                 original_content = message.get(content_key, "")
 
-                # Map to standard role name
                 standard_role = aliases_mapping.get(original_role, original_role)
 
-                # Handle VLM format
                 if is_vlm:
                     original_content = [{"type": "text", "text": original_content}]
 
-                # Create dict with EXPLICIT ORDER
+                # Keep EXPLICIT key order
                 new_message = {"role": standard_role, "content": original_content}
                 new_convo.append(new_message)
 
@@ -146,8 +141,7 @@ def convert_chatml_to_alpaca(
     num_proc = None,
 ):
     """
-    Converts ChatML format (messages OR conversations) to Alpaca format.
-    Handles both standardized and ShareGPT formats.
+    Convert ChatML (messages OR conversations) to Alpaca format.
 
     Supports:
     - "messages" or "conversations" column
@@ -160,7 +154,7 @@ def convert_chatml_to_alpaca(
         _is_torch_iterable = False
 
     def _convert(examples):
-        # Auto-detect which column name is used
+        # Auto-detect the column name
         chatml_data = (
             examples.get("messages") or examples.get("conversations") or examples.get("texts")
         )
@@ -177,20 +171,20 @@ def convert_chatml_to_alpaca(
             output = ""
 
             for msg in convo:
-                # Handle both standard and ShareGPT formats
+                # Standard and ShareGPT key names
                 role = msg.get("role") or msg.get("from")
                 content = msg.get("content") or msg.get("value")
 
-                # Get first user message as instruction
+                # First user message -> instruction
                 if role in ["user", "human", "input"] and not instruction:
                     instruction = content
-                # Get first assistant message as output
+                # First assistant message -> output
                 elif role in ["assistant", "gpt", "output"] and not output:
                     output = content
                     break  # Stop after first assistant response
 
             instructions.append(instruction)
-            inputs.append("")  # Alpaca typically has empty input
+            inputs.append("")  # Alpaca input usually empty
             outputs.append(output)
 
         return {"instruction": instructions, "input": inputs, "output": outputs}
@@ -220,9 +214,9 @@ def convert_alpaca_to_chatml(
     num_proc = None,
 ):
     """
-    Converts Alpaca format to ChatML format.
+    Convert Alpaca format to ChatML format.
 
-    Output format: Uses 'conversations' column with standard 'role'/'content' structure.
+    Output: 'conversations' column with standard 'role'/'content' dicts.
     """
     try:
         from torch.utils.data import IterableDataset
@@ -238,13 +232,12 @@ def convert_alpaca_to_chatml(
             input_text = examples.get("input", [""] * len(examples["instruction"]))[i]
             output = examples["output"][i]
 
-            # Combine instruction and input (if exists) for user message
+            # User message = instruction + input (if any)
             if input_text and input_text.strip():
                 user_content = f"{instruction}\n\n{input_text}".strip()
             else:
                 user_content = instruction
 
-            # Build conversation in standard ChatML format
             convo = [
                 {"role": "user", "content": user_content},
                 {"role": "assistant", "content": output},
@@ -294,17 +287,17 @@ def convert_to_vlm_format(
     progress_callback = None,
 ):
     """
-    Converts simple {image, text} format to VLM messages format.
+    Convert simple {image, text} format to VLM messages format.
 
     Returns a LIST, not a HuggingFace Dataset (to preserve PIL Images).
 
-    For URL-based image datasets, runs a 200-sample parallel probe first to
-    estimate download speed and failure rate, then reports time estimate or
-    warning through progress_callback before proceeding with the full conversion.
+    For URL-based image datasets, runs a 200-sample parallel probe first
+    to estimate download speed and failure rate, reporting a time
+    estimate or warning via progress_callback before the full conversion.
 
     Args:
-        progress_callback: Optional callable(status_message=str) to report
-                          progress to the training overlay.
+        progress_callback: Optional callable(status_message=str) to
+                          report progress to the training overlay.
 
     Returns:
         list: List of dicts with 'messages' field
@@ -313,11 +306,11 @@ def convert_to_vlm_format(
     from .vlm_processing import generate_smart_vlm_instruction
 
     def _notify(msg):
-        """Send status update to the training overlay if callback is available."""
+        """Send a status update to the training overlay if callback set."""
         if progress_callback:
             progress_callback(status_message = msg)
 
-    # Generate smart instruction if not provided
+    # Generate a smart instruction if none provided
     if instruction is None:
         instruction_info = generate_smart_vlm_instruction(
             dataset,
@@ -342,7 +335,7 @@ def convert_to_vlm_format(
 
     def _convert_single_sample(sample):
         """Convert a single sample to VLM format."""
-        # Get image (might be PIL Image, local path, URL, or bare filename)
+        # Image may be a PIL Image, local path, URL, or bare filename
         image_data = sample[image_column]
 
         if isinstance(image_data, str):
@@ -363,19 +356,18 @@ def convert_to_vlm_format(
             else:
                 image_data = Image.open(image_data).convert("RGB")
 
-        # Get text (if list of strings, pick a random one — e.g. multiple captions)
+        # Text: if a list (e.g. multiple captions), pick one at random
         text_data = sample[text_column]
         if isinstance(text_data, list) and len(text_data) > 0:
             import random
             text_data = random.choice(text_data)
 
-        # Get instruction (static or dynamic)
+        # Instruction: static or dynamic
         if uses_dynamic and instruction_column:
             current_instruction = sample[instruction_column]
         else:
             current_instruction = instruction
 
-        # Build VLM messages - simple structure
         messages = [
             {
                 "role": "user",
@@ -387,16 +379,15 @@ def convert_to_vlm_format(
             {"role": "assistant", "content": [{"type": "text", "text": text_data}]},
         ]
 
-        # Return dict with messages
         return {"messages": messages}
 
     total = len(dataset)
     first_image = next(iter(dataset))[image_column]
     has_urls = isinstance(first_image, str) and first_image.startswith(("http://", "https://"))
 
-    # ── Bare-filename detection: images stored as filenames (e.g. "img_001.png")
-    #    that don't exist locally.  Build a basename→repo_path lookup so we can
-    #    resolve them via hf_hub_download during conversion.
+    # ── Bare-filename detection: images stored as filenames (e.g.
+    #    "img_001.png") not present locally. Build a basename→repo_path
+    #    lookup to resolve them via hf_hub_download during conversion.
     _image_lookup = None
     _IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff")
     if (
@@ -431,7 +422,7 @@ def convert_to_vlm_format(
             logger.info(f"⚠️ Failed to build HF repo image lookup: {e}")
             _image_lookup = None
 
-    # ── URL probe: 200 samples with parallel workers to estimate speed + failure rate ──
+    # ── URL probe: 200 parallel samples to estimate speed + failure rate ──
     PROBE_SIZE = 200
     MAX_FAIL_RATE = 0.3
 
@@ -468,7 +459,7 @@ def convert_to_vlm_format(
                 f"{fail_rate:.0%} of the first {PROBE_SIZE} image URLs failed to download ({probe_fail}/{probe_total})",
                 "Images are external URLs, not embedded in the dataset",
             ]
-            # Try LLM-friendly warning
+            # LLM-friendly warning
             friendly = None
             try:
                 from .llm_assist import llm_generate_dataset_warning
@@ -490,7 +481,7 @@ def convert_to_vlm_format(
             _notify(msg)
             raise ValueError(msg)
 
-        # Estimate total time for remaining samples
+        # Estimate time for remaining samples
         remaining = total - PROBE_SIZE
         estimated_seconds = remaining / throughput if throughput > 0 else 0
         eta_str = _format_eta(estimated_seconds)
@@ -546,7 +537,7 @@ def convert_to_vlm_format(
 
             converted_list.extend(r for r in batch_results if r is not None)
 
-            # Progress update every batch
+            # Per-batch progress update
             elapsed = time.time() - start_time
             done = batch_end
             rate = done / elapsed if elapsed > 0 else 0
@@ -558,7 +549,7 @@ def convert_to_vlm_format(
             )
             _notify(progress_msg)
     else:
-        # Sequential conversion for local/embedded images (fast, no I/O bottleneck)
+        # Sequential conversion for local/embedded images (no I/O bottleneck)
         pbar = tqdm(dataset, total = total, desc = "Converting VLM samples", unit = "sample")
         for sample in pbar:
             try:
@@ -576,7 +567,7 @@ def convert_to_vlm_format(
         logger.info(
             f"⚠️ Skipped {failed_count}/{total} ({fail_rate:.0%}) samples with broken/unreachable images"
         )
-        # For datasets that skipped the probe (small URL datasets), check fail rate now
+        # Small URL datasets skip the probe; check fail rate here
         if has_urls and fail_rate >= MAX_FAIL_RATE:
             issues = [
                 f"{fail_rate:.0%} of images failed to download ({failed_count}/{total})",
@@ -629,7 +620,7 @@ def convert_to_vlm_format(
     logger.info(f"✅ Converted {len(converted_list)}/{total} samples")
     _notify(f"Converted {len(converted_list):,}/{total:,} images successfully")
 
-    # Return list, NOT Dataset
+    # Return list, NOT a Dataset
     return converted_list
 
 
@@ -641,8 +632,8 @@ def convert_sharegpt_with_images_to_vlm_format(
     progress_callback = None,
 ):
     """
-    Converts ShareGPT/ChatML datasets that have a separate image column and
-    ``<image>`` placeholders inside the conversation text.
+    Convert ShareGPT/ChatML datasets with a separate image column and
+    ``<image>`` placeholders in the conversation text.
 
     Example input::
 
@@ -672,7 +663,7 @@ def convert_sharegpt_with_images_to_vlm_format(
         if progress_callback:
             progress_callback(status_message = msg)
 
-    # ── Resolve image loading strategy (same 3-tier as convert_to_vlm_format) ──
+    # ── Resolve image loading (same 3-tier as convert_to_vlm_format) ──
     total = len(dataset)
     first_image = next(iter(dataset))[image_column]
 
@@ -696,7 +687,7 @@ def convert_sharegpt_with_images_to_vlm_format(
                 for f in repo_files
                 if any(f.lower().endswith(ext) for ext in _IMAGE_EXTS)
             }
-            # Also add the full relative paths as keys (for paths like "sam/images/sa_545504.jpg")
+            # Also key by full relative path (e.g. "sam/images/sa_545504.jpg")
             for f in repo_files:
                 if any(f.lower().endswith(ext) for ext in _IMAGE_EXTS):
                     _image_lookup[f] = f
@@ -714,7 +705,7 @@ def convert_sharegpt_with_images_to_vlm_format(
             _image_lookup = None
 
     def _resolve_image(image_data):
-        """Resolve image data to a PIL Image object."""
+        """Resolve image data to a PIL Image."""
         if hasattr(image_data, "size") and hasattr(image_data, "mode"):
             return image_data  # Already PIL
         if isinstance(image_data, str):
@@ -742,7 +733,7 @@ def convert_sharegpt_with_images_to_vlm_format(
         raise ValueError(f"Cannot resolve image: {type(image_data)}")
 
     def _convert_single_sample(sample):
-        """Convert a single ShareGPT+image sample to standard VLM format."""
+        """Convert one ShareGPT+image sample to standard VLM format."""
         pil_image = _resolve_image(sample[image_column])
         conversation = sample[messages_column]
 
@@ -752,7 +743,7 @@ def convert_sharegpt_with_images_to_vlm_format(
             role = _ROLE_MAP.get(role_raw.lower(), role_raw.lower())
             text = msg.get("value") or msg.get("content") or ""
 
-            # Split on <image> to interleave text and image content blocks
+            # Interleave text and image blocks around <image>
             if "<image>" in text:
                 parts = text.split("<image>")
                 content = []
@@ -762,7 +753,7 @@ def convert_sharegpt_with_images_to_vlm_format(
                         content.append({"type": "text", "text": part})
                     if i < len(parts) - 1:
                         content.append({"type": "image", "image": pil_image})
-                # If <image> was the entire text, content might just be the image
+                # If text was only <image>, content is just the image
                 if not content:
                     content.append({"type": "image", "image": pil_image})
             else:
@@ -804,7 +795,7 @@ def convert_sharegpt_with_images_to_vlm_format(
 
 def convert_llava_to_vlm_format(dataset):
     """
-    Converts Llava format to standard VLM format.
+    Convert Llava format to standard VLM format.
 
     Llava format:
     - messages: [{'content': [{'type': 'image', 'index': 0}, {'type': 'text', 'text': '...'}]}]
@@ -818,23 +809,22 @@ def convert_llava_to_vlm_format(dataset):
     logger.info(f"🔄 Converting {len(dataset)} samples from Llava format to standard VLM format...")
 
     def _convert_single_sample(sample):
-        """Convert a single llava sample to standard VLM format."""
+        """Convert one llava sample to standard VLM format."""
         messages = sample["messages"]
         images = sample.get("images", [])
 
-        # Process each message
         new_messages = []
         for msg in messages:
             new_content = []
 
             for item in msg["content"]:
                 if item["type"] == "image":
-                    # Replace index with actual PIL image
+                    # Replace index with the actual PIL image
                     if "index" in item and item["index"] is not None:
                         img_idx = item["index"]
                         if img_idx < len(images):
                             pil_image = images[img_idx]
-                            # Ensure it's PIL
+                            # Ensure PIL
                             if isinstance(pil_image, str):
                                 pil_image = Image.open(pil_image).convert("RGB")
 
@@ -845,7 +835,7 @@ def convert_llava_to_vlm_format(dataset):
                                 }
                             )
                     else:
-                        # No index, try to use first image
+                        # No index: use the first image
                         if len(images) > 0:
                             pil_image = images[0]
                             if isinstance(pil_image, str):
@@ -854,14 +844,12 @@ def convert_llava_to_vlm_format(dataset):
                             new_content.append({"type": "image", "image": pil_image})
 
                 elif item["type"] == "text":
-                    # Keep text as-is (only type + text)
                     new_content.append({"type": "text", "text": item.get("text", "")})
 
             new_messages.append({"role": msg["role"], "content": new_content})
 
         return {"messages": new_messages}
 
-    # Convert using list comprehension
     converted_list = [_convert_single_sample(sample) for sample in dataset]
 
     logger.info(f"✅ Converted {len(converted_list)} samples")
diff --git a/studio/backend/utils/datasets/format_detection.py b/studio/backend/utils/datasets/format_detection.py
index 829838064a..72f8f48cf7 100644
--- a/studio/backend/utils/datasets/format_detection.py
+++ b/studio/backend/utils/datasets/format_detection.py
@@ -1,11 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Format detection utilities for dataset processing.
+"""Format detection utilities for dataset processing.
 
-This module contains functions for detecting dataset formats (Alpaca, ShareGPT, ChatML),
-detecting multimodal/VLM dataset structures, and heuristic-based column mapping.
+Detects dataset formats (Alpaca, ShareGPT, ChatML), multimodal/VLM
+structures, and heuristic column mapping.
 """
 
 import re
@@ -17,8 +16,7 @@ def _keyword_in_column(keyword: str, col_name: str) -> bool:
 
 
 def detect_dataset_format(dataset):
-    """
-    Detects dataset format by inspecting structure.
+    """Detect dataset format by inspecting structure.
 
     Returns:
         dict: {
@@ -30,7 +28,7 @@ def detect_dataset_format(dataset):
     """
     column_names = set(next(iter(dataset)).keys())
 
-    # Check for Alpaca
+    # Alpaca
     alpaca_columns = {"instruction", "output"}
     if alpaca_columns.issubset(column_names):
         return {
@@ -40,7 +38,7 @@ def detect_dataset_format(dataset):
             "sample_keys": [],
         }
 
-    # Check for chat-based formats (messages or conversations)
+    # Chat-based formats (messages or conversations)
     chat_column = None
     if "messages" in column_names:
         chat_column = "messages"
@@ -50,7 +48,7 @@ def detect_dataset_format(dataset):
         chat_column = "texts"
 
     if chat_column:
-        # Inspect the structure to determine if ShareGPT or ChatML
+        # Inspect structure: ShareGPT or ChatML?
         try:
             sample = next(iter(dataset))
             chat_data = sample[chat_column]
@@ -77,7 +75,7 @@ def detect_dataset_format(dataset):
                         "sample_keys": list(msg_keys),
                     }
 
-                # Unknown structure but has chat column
+                # Has chat column but unknown structure
                 else:
                     return {
                         "format": "unknown",
@@ -104,8 +102,7 @@ def detect_dataset_format(dataset):
 
 
 def detect_custom_format_heuristic(dataset):
-    """
-    Smart detection with priority scoring.
+    """Detection with priority scoring.
 
     Strategy for ambiguous keywords like 'task':
     1. Detect assistant first (unambiguous)
@@ -159,7 +156,7 @@ def detect_custom_format_heuristic(dataset):
         "persona",
         "role",
         "template",
-        "task",  # Also in system
+        "task",  # also a system keyword
     ]
 
     # Metadata columns to ignore
@@ -197,7 +194,7 @@ def detect_custom_format_heuristic(dataset):
     }
 
     def has_keyword(col_name, keywords):
-        """Check if any keyword appears in column name."""
+        """True if any keyword appears in the column name."""
         col_lower = col_name.lower()
         col_normalized = col_lower.replace("_", "").replace("-", "").replace(" ", "")
 
@@ -207,7 +204,7 @@ def detect_custom_format_heuristic(dataset):
         return False
 
     def is_metadata(col_name):
-        """Check if column is likely metadata."""
+        """True if the column is likely metadata."""
         col_lower = col_name.lower()
 
         if col_lower in metadata_exact_match:
@@ -229,7 +226,7 @@ def detect_custom_format_heuristic(dataset):
         return False
 
     def get_priority_score(col_name):
-        """Calculate priority score based on column name patterns."""
+        """Priority score from column-name patterns."""
         col_lower = col_name.lower()
         score = 0
 
@@ -240,7 +237,7 @@ def detect_custom_format_heuristic(dataset):
         return score
 
     def get_content_length(col_name):
-        """Get average content length for this column."""
+        """Average content length for this column."""
         try:
             if col_name in sample and sample[col_name]:
                 content = str(sample[col_name])
@@ -250,7 +247,7 @@ def detect_custom_format_heuristic(dataset):
             return 0
 
     def score_column(col_name, keywords, role_type, num_candidates):
-        """Score a column for how likely it is to be a particular role."""
+        """Score how likely a column is to be a given role."""
         if not has_keyword(col_name, keywords):
             return 0
 
@@ -260,7 +257,7 @@ def detect_custom_format_heuristic(dataset):
         # Penalize ambiguous keywords when scoring for user
         if role_type == "user":
             col_lower = col_name.lower()
-            # If column is ONLY "task" (or task_xxx), give it lower priority for user role
+            # ONLY "task" (or task_xxx): lower priority for user role
             if "task" in col_lower and not any(kw in col_lower for kw in user_words_high_priority):
                 score -= 15  # Significant penalty so other user columns win
 
@@ -289,10 +286,10 @@ def detect_custom_format_heuristic(dataset):
 
         return score
 
-    # Filter out metadata columns
+    # Drop metadata columns
     content_columns = [col for col in all_columns if not is_metadata(col)]
 
-    # Count candidates first
+    # Count candidates
     assistant_potential = [col for col in content_columns if has_keyword(col, assistant_words)]
     user_potential = [col for col in content_columns if has_keyword(col, user_words)]
 
@@ -332,7 +329,7 @@ def detect_custom_format_heuristic(dataset):
     system_col = None
     for col in remaining_columns:
         if has_keyword(col, system_words):
-            # Found a system match in remaining columns
+            # System match found
             mapping[col] = "system"
             system_col = col
             break
@@ -344,17 +341,17 @@ def detect_custom_format_heuristic(dataset):
     if len(remaining_columns) >= 1:
         remaining_col = remaining_columns[0]
 
-        # If no strong keyword match, decide based on what's missing
+        # No strong keyword match: decide by what's missing
         if not has_keyword(remaining_col, user_words + assistant_words):
             mapping[remaining_col] = "system"
         elif user_col is None:
-            # No user column yet, assign this as user
+            # No user column yet: assign this as user
             mapping[remaining_col] = "user"
         else:
-            # Already have user + assistant, treat as system context
+            # Already have user + assistant: treat as system context
             mapping[remaining_col] = "system"
 
-    # VALIDATION: Ensure we have at least user + assistant
+    # Ensure we have at least user + assistant
     has_user = any(role == "user" for role in mapping.values())
     has_assistant = any(role == "assistant" for role in mapping.values())
 
@@ -372,12 +369,11 @@ def detect_custom_format_heuristic(dataset):
 
 
 def detect_multimodal_dataset(dataset):
-    """
-    Detects if dataset contains multimodal data (images and/or audio).
+    """Detect multimodal data (images and/or audio) in a dataset.
 
-    Two-pass approach for each modality:
-      1. Column-name heuristic (fast): checks for keywords.
-      2. Value-type inspection (reliable): checks actual sample values.
+    Two passes per modality:
+      1. Column-name heuristic (fast): keyword match.
+      2. Value-type inspection (reliable): check actual sample values.
 
     Returns:
         dict: {
@@ -393,7 +389,7 @@ def detect_multimodal_dataset(dataset):
     sample = next(iter(dataset))
     column_names = list(sample.keys())
 
-    # Keywords that indicate image data
+    # Image keywords
     image_keywords = [
         "image",
         "img",
@@ -414,7 +410,7 @@ def detect_multimodal_dataset(dataset):
         "filename",
     ]
 
-    # Keywords that indicate audio data
+    # Audio keywords
     audio_keywords = ["audio", "speech", "wav", "waveform", "sound"]
 
     multimodal_columns = []
@@ -422,8 +418,8 @@ def detect_multimodal_dataset(dataset):
     modality_types = set()
 
     # ── Image detection ─────────────────────────────────────
-    # Pass 1: column-name heuristic (word-boundary match to avoid
-    #          false positives like 'pic' in 'topic')
+    # Pass 1: column-name heuristic (word-boundary match avoids false
+    #          positives like 'pic' in 'topic')
     for col_name in column_names:
         for keyword in image_keywords:
             if _keyword_in_column(keyword, col_name):
@@ -460,13 +456,13 @@ def detect_multimodal_dataset(dataset):
             audio_columns.append(col_name)
             modality_types.add("audio")
 
-    # Filter out columns that are actually audio from the image list
-    # (e.g. a column named "audio" with {"bytes", "path"} could match _is_image_value)
+    # Drop audio columns from the image list (e.g. a column named "audio"
+    # with {"bytes", "path"} could match _is_image_value)
     if audio_columns:
         audio_set = set(audio_columns)
         multimodal_columns = [c for c in multimodal_columns if c not in audio_set]
 
-    # Detect text column for audio datasets
+    # Text column for audio datasets
     detected_text_col = None
     if audio_columns:
         text_keywords = ["text", "sentence", "transcript", "transcription", "label"]
@@ -477,7 +473,7 @@ def detect_multimodal_dataset(dataset):
 
     is_audio = len(audio_columns) > 0
 
-    # Detect speaker_id column for TTS datasets (CSM, Orpheus, Spark)
+    # speaker_id column for TTS datasets (CSM, Orpheus, Spark)
     detected_speaker_col = None
     if audio_columns:
         speaker_keywords = ["source", "speaker", "speaker_id"]
@@ -511,14 +507,13 @@ def _is_image_value(value) -> bool:
     except ImportError:
         pass
 
-    # HF datasets Image feature stores decoded images as PIL or dicts with
-    # {"bytes": b"...", "path": "..."} when not yet decoded.
+    # HF Image feature: decoded as PIL, or {"bytes", "path"} when undecoded.
     # Exclude audio dicts (decoded audio has "array" + "sampling_rate").
     if isinstance(value, dict):
         if "array" in value and "sampling_rate" in value:
-            return False  # This is audio, not image
+            return False  # audio, not image
         if "bytes" in value and "path" in value:
-            # Check path extension to exclude audio files
+            # Use path extension to exclude audio files
             path = value.get("path") or ""
             if isinstance(path, str) and any(
                 path.lower().endswith(ext) for ext in _AUDIO_EXTENSIONS
@@ -539,7 +534,7 @@ def _is_image_value(value) -> bool:
             lower.split("?")[0].endswith(ext) for ext in _IMAGE_EXTS
         ):
             return True
-        # Image file path (relative or absolute path ending in image extension)
+        # Image file path (relative or absolute)
         if any(lower.endswith(ext) for ext in _IMAGE_EXTS):
             return True
 
@@ -564,11 +559,11 @@ def _is_audio_value(value) -> bool:
     if value is None:
         return False
 
-    # HF datasets Audio feature: decoded → {"array": np.ndarray, "sampling_rate": int}
+    # HF Audio feature: decoded → {"array": np.ndarray, "sampling_rate": int}
     if isinstance(value, dict):
         if "array" in value and "sampling_rate" in value:
             return True
-        # Undecoded/streaming → {"bytes": b"...", "path": "some.wav"}
+        # Undecoded/streaming → {"bytes", "path": "some.wav"}
         if "bytes" in value or "path" in value:
             path = value.get("path") or ""
             if isinstance(path, str) and any(
@@ -602,9 +597,8 @@ def _has_image_header(data: bytes) -> bool:
 
 
 def detect_vlm_dataset_structure(dataset):
-    """
-    Detects if VLM dataset is:
-    - Standard VLM messages format (image objects in content)
+    """Detect which VLM dataset shape this is:
+    - Standard VLM messages (image objects in content)
     - Llava format (image indices + separate images column)
     - Simple format needing conversion (image + text columns)
     """
@@ -621,7 +615,7 @@ def detect_vlm_dataset_structure(dataset):
 
     column_names = set(sample.keys())
 
-    # Check if has messages column
+    # Has messages column?
     if "messages" in column_names:
         messages = sample["messages"]
 
@@ -632,7 +626,7 @@ def detect_vlm_dataset_structure(dataset):
 
                 if isinstance(content, list) and len(content) > 0:
                     if isinstance(content[0], dict) and "type" in content[0]:
-                        # Check for llava format
+                        # Llava format?
                         has_index = any(
                             "index" in item for item in content if isinstance(item, dict)
                         )
@@ -660,8 +654,8 @@ def detect_vlm_dataset_structure(dataset):
                                 "text_column": None,
                             }
 
-    # Check for ShareGPT/ChatML conversations with <image> placeholder + companion image column
-    # (e.g. Lin-Chen/ShareGPT4V, LLaVA-style datasets)
+    # ShareGPT/ChatML conversations with <image> placeholder + companion
+    # image column (e.g. Lin-Chen/ShareGPT4V, LLaVA-style datasets)
     for chat_col in ("conversations", "messages"):
         if chat_col not in column_names:
             continue
@@ -671,11 +665,11 @@ def detect_vlm_dataset_structure(dataset):
         first_msg = chat_data[0]
         if not isinstance(first_msg, dict):
             continue
-        # Detect ShareGPT (from/value) or ChatML (role/content) keys
+        # ShareGPT (from/value) or ChatML (role/content) keys
         msg_text = first_msg.get("value") or first_msg.get("content")
         if not isinstance(msg_text, str):
             continue
-        # Check for <image> placeholder anywhere in the conversation
+        # <image> placeholder anywhere in the conversation?
         has_image_placeholder = any(
             "<image>" in str(m.get("value", "") or m.get("content", ""))
             for m in chat_data
@@ -700,9 +694,7 @@ def detect_vlm_dataset_structure(dataset):
                 "messages_column": chat_col,
             }
 
-    # Find image and text columns using metadata filtering
-
-    # Define metadata patterns to EXCLUDE
+    # Find image and text columns, filtering out metadata patterns
     metadata_patterns = {
         "suffixes": [
             "_id",
@@ -726,7 +718,7 @@ def detect_vlm_dataset_structure(dataset):
         ],
     }
 
-    # Image-related keywords
+    # Image keywords
     image_keywords = [
         "image",
         "img",
@@ -739,7 +731,7 @@ def detect_vlm_dataset_structure(dataset):
         "filename",
     ]
 
-    # Text-related keywords
+    # Text keywords
     text_keywords = [
         "text",
         "caption",
@@ -752,14 +744,14 @@ def detect_vlm_dataset_structure(dataset):
     ]
 
     def is_metadata_column(col_name):
-        """Check if column name looks like metadata."""
+        """True if the column name looks like metadata."""
         col_lower = col_name.lower()
 
-        # Check suffixes
+        # Suffixes
         if any(col_lower.endswith(suffix) for suffix in metadata_patterns["suffixes"]):
             return True
 
-        # Check prefixes
+        # Prefixes
         if any(col_lower.startswith(prefix) for prefix in metadata_patterns["prefixes"]):
             return True
 
@@ -767,16 +759,16 @@ def detect_vlm_dataset_structure(dataset):
 
     def _score_image_candidate(col, sample_value):
         """Score a candidate image column by how resolvable its value is."""
-        # PIL Image object (highest priority - already loaded)
+        # PIL Image object (already loaded -> highest)
         if hasattr(sample_value, "size") and hasattr(sample_value, "mode"):
             return 100
 
-        # Dict with image data (bytes/path from HF Image feature)
+        # Dict with bytes/path from HF Image feature
         if isinstance(sample_value, dict) and ("bytes" in sample_value or "path" in sample_value):
             return 75
 
         if isinstance(sample_value, str):
-            # URL strings
+            # URL
             if sample_value.startswith(("http://", "https://")):
                 return 70 if not is_metadata_column(col) else 55
             # Bare file path
@@ -787,8 +779,8 @@ def detect_vlm_dataset_structure(dataset):
         return 0
 
     def _probe_image_candidate(col, sample_value):
-        """Quick probe to check if an image candidate is actually reachable.
-        Returns True if likely valid, False if definitely broken."""
+        """Probe whether an image candidate is reachable.
+        True if likely valid, False if definitely broken."""
         import os
 
         # PIL / dict — already loaded, always valid
@@ -799,7 +791,7 @@ def detect_vlm_dataset_structure(dataset):
         if not sample_value.startswith(("http://", "https://")):
             return os.path.exists(sample_value)  # bare filenames return False here, that's OK
 
-        # URL — quick HEAD request with short timeout
+        # URL — quick HEAD with short timeout
         try:
             import urllib.request
 
@@ -810,8 +802,8 @@ def detect_vlm_dataset_structure(dataset):
             return False
 
     def find_image_column():
-        """Find image column by keyword match + value-based fallback.
-        When multiple candidates exist, probes them to find one that works."""
+        """Find image column by keyword match + value-based fallback,
+        probing candidates to find one that works."""
         candidates = []
 
         # Pass 1: keyword-matched columns
@@ -822,8 +814,8 @@ def detect_vlm_dataset_structure(dataset):
                 if score > 0:
                     candidates.append((col, score))
 
-        # Pass 2: value-based fallback — find columns with image URLs/paths
-        # even if the column name doesn't match image keywords
+        # Pass 2: value-based fallback — columns with image URLs/paths
+        # even if the name doesn't match image keywords
         already = {c[0] for c in candidates}
         for col in column_names:
             if col in already:
@@ -831,7 +823,7 @@ def detect_vlm_dataset_structure(dataset):
             sample_value = sample[col]
             if _is_image_value(sample_value):
                 score = _score_image_candidate(col, sample_value)
-                # Slightly penalise non-keyword columns so keyword matches win on ties
+                # Penalise non-keyword columns so keyword matches win on ties
                 candidates.append((col, max(score - 5, 1)))
 
         if not candidates:
@@ -839,48 +831,47 @@ def detect_vlm_dataset_structure(dataset):
 
         candidates.sort(key = lambda x: x[1], reverse = True)
 
-        # Single candidate or top candidate is PIL/dict — no probing needed
+        # Single candidate or top is PIL/dict — no probing needed
         if len(candidates) == 1 or candidates[0][1] >= 75:
             return candidates[0][0]
 
-        # Multiple string-based candidates — probe to find one that actually works
+        # Multiple string candidates — probe for one that works
         for col, score in candidates:
             sample_value = sample[col]
             if _probe_image_candidate(col, sample_value):
                 return col
 
-        # Nothing probed successfully — return highest-scored anyway and let
-        # conversion handle the error (it may still resolve via hf_hub_download)
+        # None probed OK — return highest-scored and let conversion handle
+        # the error (it may still resolve via hf_hub_download)
         return candidates[0][0]
 
     def find_text_column():
-        """Find text column by filtering out metadata and checking keywords."""
+        """Find text column: skip metadata, match keywords."""
         candidates = []
 
         for col in column_names:
-            # Skip metadata columns
             if is_metadata_column(col):
                 continue
 
-            # Check if contains text keywords (word-boundary match)
+            # Text keyword (word-boundary match)
             if any(_keyword_in_column(keyword, col) for keyword in text_keywords):
                 # Verify it's actually text
                 sample_value = sample[col]
 
                 if isinstance(sample_value, str) and len(sample_value) > 0:
-                    # Longer text = higher priority (likely content, not just a label)
-                    priority = min(len(sample_value), 1000)  # Cap at 1000
+                    # Longer text = higher priority (content, not a label)
+                    priority = min(len(sample_value), 1000)  # cap at 1000
                     candidates.append((col, priority))
                 elif (
                     isinstance(sample_value, list)
                     and len(sample_value) > 0
                     and isinstance(sample_value[0], str)
                 ):
-                    # List of strings (e.g. captions list) — lower priority than plain strings
+                    # List of strings (e.g. captions) — lower priority than plain str
                     priority = min(len(sample_value[0]), 1000) // 2
                     candidates.append((col, priority))
 
-        # Return highest priority candidate
+        # Highest-priority candidate
         if candidates:
             candidates.sort(key = lambda x: x[1], reverse = True)
             return candidates[0][0]
diff --git a/studio/backend/utils/datasets/llm_assist.py b/studio/backend/utils/datasets/llm_assist.py
index 10004ce3db..d6bb0dc91d 100644
--- a/studio/backend/utils/datasets/llm_assist.py
+++ b/studio/backend/utils/datasets/llm_assist.py
@@ -4,13 +4,13 @@
 """
 LLM-assisted dataset analysis using an ephemeral GGUF helper model.
 
-Complements heuristic-based detection in format_detection.py and
-vlm_processing.py.  Only invoked when heuristics are uncertain.
+Complements heuristic detection in format_detection.py and vlm_processing.py.
+Only invoked when heuristics are uncertain.
 
 Architecture:
   - Instantiates LlamaCppBackend, loads model, runs completion(s), unloads.
   - Not kept warm — VRAM is freed immediately after use.
-  - Gracefully degrades: returns None when unavailable (no binary, OOM, disabled).
+  - Degrades gracefully: returns None when unavailable (no binary, OOM, disabled).
 """
 
 import json
@@ -35,20 +35,19 @@ README_MAX_CHARS = 1500
 def _strip_think_tags(text: str) -> str:
     """Strip <think>...</think> reasoning blocks emitted by some models.
 
-    If the model places its actual answer OUTSIDE the think block, we
-    discard the think block and keep the rest.  If the entire response
-    is INSIDE a think block (nothing useful outside), we extract and
-    return the inner content instead of discarding everything.
+    If the answer is OUTSIDE the think block, discard the block and keep the
+    rest. If the entire response is INSIDE a think block (nothing useful
+    outside), return the inner content instead of discarding everything.
     """
     if "<think>" not in text:
         return text
 
-    # Try stripping think blocks — keep content outside them
+    # Strip think blocks — keep content outside them
     stripped = re.sub(r"<think>.*?</think>\s*", "", text, flags = re.DOTALL).strip()
     if stripped:
         return stripped
 
-    # Everything was inside <think> tags — extract the inner content of the last block
+    # Everything was inside <think> tags — return the last block's inner content
     matches = re.findall(r"<think>(.*?)</think>", text, flags = re.DOTALL)
     if matches:
         return matches[-1].strip()
@@ -60,9 +59,9 @@ def precache_helper_gguf():
     """
     Pre-download the helper GGUF to HF cache.
 
-    Called on FastAPI startup in a background thread so subsequent
+    Called on FastAPI startup in a background thread so later
     ``_run_with_helper()`` calls skip the download and only pay for
-    llama-server startup.  No-op if already cached or disabled.
+    llama-server startup. No-op if already cached or disabled.
     """
     if os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in ("1", "true"):
         return
@@ -82,7 +81,7 @@ def precache_helper_gguf():
         files = api.list_repo_files(repo, repo_type = "model")
         gguf_files = [f for f in files if f.endswith(".gguf")]
 
-        # Find all GGUF files matching the variant (may be split into shards)
+        # All GGUF files matching the variant (may be split into shards)
         variant_lower = variant.lower().replace("-", "_")
         matching = sorted(f for f in gguf_files if variant_lower in f.lower().replace("-", "_"))
 
@@ -150,7 +149,7 @@ def _run_with_helper(prompt: str, max_tokens: int = 256) -> Optional[str]:
         ):
             if isinstance(chunk, dict):
                 continue  # skip metadata events
-            cumulative = chunk  # cumulative — last value is full text
+            cumulative = chunk  # cumulative; last value is full text
 
         result = cumulative.strip()
         result = _strip_think_tags(result)
@@ -181,8 +180,8 @@ def llm_generate_vlm_instruction(
     """
     Ask a helper LLM to generate a task-specific VLM instruction.
 
-    Called when heuristic instruction generation returns low confidence
-    or falls back to generic.
+    Called when heuristic instruction generation returns low confidence or
+    falls back to generic.
 
     Args:
         column_names: Column names in the dataset.
@@ -218,9 +217,9 @@ def llm_generate_vlm_instruction(
     if not result:
         return None
 
-    # Clean up: strip quotes, ensure it's a single sentence
+    # Strip quotes; ensure a single sentence
     instruction = result.strip().strip('"').strip("'").strip()
-    # Reject obviously bad outputs (too short, too long, or multi-line)
+    # Reject bad outputs (too short, too long, or multi-line)
     if len(instruction) < 10 or len(instruction) > 200 or "\n" in instruction:
         logger.warning(f"Helper model returned unusable instruction: {instruction!r}")
         return None
@@ -243,8 +242,7 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
         samples: 3-5 sample rows with values truncated to 200 chars.
 
     Returns:
-        Dict mapping column_name → role ("user"|"assistant"|"system"|"metadata"),
-        or None on failure.
+        Dict mapping column_name → role ("user"|"assistant"|"system"|"metadata"), or None.
     """
     formatted = ""
     for i, row in enumerate(samples[:5], 1):
@@ -281,7 +279,7 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
     try:
         mapping = json.loads(text)
     except json.JSONDecodeError:
-        # Try to find JSON object in the response
+        # Find a JSON object in the response
         import re
         match = re.search(r"\{[^}]+\}", text)
         if match:
@@ -324,7 +322,7 @@ def llm_generate_dataset_warning(
     column_names: Optional[list[str]] = None,
 ) -> Optional[str]:
     """
-    Ask the helper LLM to turn technical dataset issues into a user-friendly warning.
+    Ask the helper LLM to turn technical dataset issues into a friendly warning.
 
     Works for all modalities (text, vision, audio).
 
@@ -359,7 +357,7 @@ def llm_generate_dataset_warning(
         return None
 
     warning = result.strip()
-    # Reject obviously bad outputs
+    # Reject bad outputs
     if len(warning) < 10 or len(warning) > 500:
         return None
 
@@ -489,7 +487,7 @@ def _run_multi_pass_advisor(
     """
     Multi-pass LLM analysis: classify → convert → validate.
 
-    Keeps model loaded across all passes. Returns combined result dict or None.
+    Keeps the model loaded across passes. Returns combined result dict or None.
     """
     if os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in ("1", "true"):
         return None
@@ -619,7 +617,7 @@ def _run_multi_pass_advisor(
             logger.warning(f"Advisor Pass 1 failed to produce JSON: {raw1[:200]}")
             return None
 
-        # If dataset is already conversational, skip passes 2-3
+        # Already conversational: skip passes 2-3
         if pass1.get("is_conversational") and not pass1.get("needs_conversion"):
             return {
                 "success": True,
@@ -724,7 +722,7 @@ def _run_multi_pass_advisor(
         column_roles = pass2.get("column_roles", {})
         label_map = pass2.get("label_mapping") or {}  # may be null
 
-        # Validate: must have at least one user AND one assistant
+        # Must have at least one user AND one assistant
         roles_present = set(column_roles.values())
         if "user" not in roles_present or "assistant" not in roles_present:
             logger.warning(f"Pass 2 sanity fail: missing user or assistant role: {column_roles}")
@@ -739,7 +737,7 @@ def _run_multi_pass_advisor(
             logger.info("Pass 3: Generating system prompt...")
             t3 = time.monotonic()
 
-            # Format label mapping info for the prompt
+            # Format label mapping for the prompt
             label_info = ""
             if label_map:
                 for col, mapping in label_map.items():
@@ -782,12 +780,12 @@ def _run_multi_pass_advisor(
             )
 
             if raw3:
-                # Pass 3 returns raw text, not JSON — clean it up
+                # Pass 3 returns raw text, not JSON — clean it
                 cleaned = raw3.strip().strip('"').strip("'").strip()
                 if len(cleaned) >= 20 and cleaned.lower() not in ("null", "none", ""):
                     sys_prompt = cleaned
 
-        # Build suggested_mapping (column → role, for the frontend dropdowns)
+        # Build suggested_mapping (column → role) for the frontend dropdowns
         suggested_mapping = {}
         for col, role in column_roles.items():
             if col in columns and role in ("user", "assistant", "system"):
@@ -855,7 +853,7 @@ def llm_conversion_advisor(
     if dataset_name and "/" in dataset_name:
         dataset_card, dataset_metadata = fetch_hf_dataset_card(dataset_name, hf_token)
 
-    # Try multi-pass advisor
+    # Try the multi-pass advisor
     result = _run_multi_pass_advisor(
         columns = column_names,
         samples = samples,
diff --git a/studio/backend/utils/datasets/model_mappings.py b/studio/backend/utils/datasets/model_mappings.py
index eb2e5482c9..b550dc81bd 100644
--- a/studio/backend/utils/datasets/model_mappings.py
+++ b/studio/backend/utils/datasets/model_mappings.py
@@ -1,11 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Model and template mappings for dataset processing.
+"""Model and template mappings for dataset processing.
 
-This module contains the mapping dictionaries that associate model names
-with their corresponding chat templates and response markers.
+Maps model names to their chat templates and response markers.
 """
 
 TEMPLATE_TO_MODEL_MAPPER = {
@@ -445,8 +443,8 @@ for key, values in TEMPLATE_TO_MODEL_MAPPER.items():
 def is_gpt_oss_model_name(name: str) -> bool:
     """Name-based check for gpt-oss / harmony models.
 
-    Used by both the in-process backend and the parent-process
-    orchestrator to detect harmony models without an IPC round-trip.
+    Used by the in-process backend and the parent orchestrator to detect
+    harmony models without an IPC round-trip.
     """
     name = (name or "").lower()
     if not name:
diff --git a/studio/backend/utils/datasets/vlm_processing.py b/studio/backend/utils/datasets/vlm_processing.py
index a0f1fd9f99..4919b8884d 100644
--- a/studio/backend/utils/datasets/vlm_processing.py
+++ b/studio/backend/utils/datasets/vlm_processing.py
@@ -4,8 +4,8 @@
 """
 VLM (Vision-Language Model) processing utilities.
 
-This module contains functions for generating smart instructions
-for VLM datasets based on content analysis and heuristics.
+Generates smart instructions for VLM datasets via content analysis and
+heuristics.
 """
 
 import re
@@ -19,19 +19,19 @@ def generate_smart_vlm_instruction(
     dataset_name = None,
 ):
     """
-    Generate smart, context-aware instruction for VLM datasets using heuristics.
+    Generate a smart, context-aware instruction for VLM datasets via heuristics.
 
     Strategy:
-    1. Check for explicit question/instruction columns → use that
+    1. Explicit question/instruction column → use that
     2. Infer from text column name + sample content
     3. Analyze dataset name for task hints
-    4. Fall back to generic instruction
+    4. Generic fallback
 
     Returns:
         dict: {
             "instruction": str or None,  # None means use column content
             "instruction_type": "explicit" | "inferred" | "generic",
-            "uses_dynamic_instruction": bool,  # True if instruction varies per sample
+            "uses_dynamic_instruction": bool,  # True if it varies per sample
             "confidence": float,  # 0.0 to 1.0
         }
     """
@@ -39,16 +39,16 @@ def generate_smart_vlm_instruction(
     sample = next(iter(dataset))
 
     # ===== LEVEL 1: Explicit Instruction Columns =====
-    # Check for columns that contain per-sample instructions
+    # Columns that hold per-sample instructions
     question_columns = ["question", "query", "prompt", "instruction", "user_prompt"]
 
     for col in question_columns:
         if col in column_names:
-            # Check if this column has varied content (not just empty/same)
+            # Use it only if it has non-empty content
             sample_content = sample[col]
             if sample_content and str(sample_content).strip():
                 return {
-                    "instruction": None,  # Signal to use column content
+                    "instruction": None,  # use column content
                     "instruction_column": col,
                     "instruction_type": "explicit",
                     "uses_dynamic_instruction": True,
@@ -58,7 +58,7 @@ def generate_smart_vlm_instruction(
     # ===== LEVEL 2: Infer from Column Names + Content =====
     text_col_lower = text_column.lower()
 
-    # Sample the text content to detect patterns
+    # Sample text content for pattern detection
     text_sample = str(sample.get(text_column, ""))[:500]  # First 500 chars
 
     # Task-specific keywords and their instructions
@@ -122,24 +122,24 @@ def generate_smart_vlm_instruction(
         },
     }
 
-    # Check column name matches
+    # Score each task by column/dataset name and content matches
     best_match = None
     best_score = 0.0
 
     for task_name, task_info in task_patterns.items():
         score = 0.0
 
-        # Check column name
+        # Column name
         if any(keyword in text_col_lower for keyword in task_info["keywords"]):
             score += 0.5
 
-        # Check dataset name if provided
+        # Dataset name if provided
         if dataset_name and any(
             keyword in dataset_name.lower() for keyword in task_info["keywords"]
         ):
             score += 0.3
 
-        # Check content patterns
+        # Content patterns
         for pattern in task_info["content_hints"]:
             if re.search(pattern, text_sample, re.IGNORECASE):
                 score += 0.4
@@ -162,7 +162,6 @@ def generate_smart_vlm_instruction(
     if dataset_name:
         name_lower = dataset_name.lower()
 
-        # Common dataset name patterns
         if "vqa" in name_lower or "question" in name_lower:
             return {
                 "instruction": "Answer the question about this image.",
diff --git a/studio/backend/utils/hardware/__init__.py b/studio/backend/utils/hardware/__init__.py
index 400b5dd066..7ccba6315e 100644
--- a/studio/backend/utils/hardware/__init__.py
+++ b/studio/backend/utils/hardware/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Hardware detection and GPU utilities
-"""
+"""Hardware detection and GPU utilities."""
 
 from . import hardware as _hardware
 from .hardware import (
@@ -86,8 +84,8 @@ __all__ = [
 
 
 def __getattr__(name: str):
-    """Resolve IS_ROCM at access time so callers always see the live value
-    after detect_hardware() runs (it flips the flag in hardware.py)."""
+    """Resolve IS_ROCM at access time so callers see the live value after
+    detect_hardware() runs (it flips the flag in hardware.py)."""
     if name == "IS_ROCM":
         return getattr(_hardware, "IS_ROCM")
     raise AttributeError(name)
diff --git a/studio/backend/utils/hardware/amd.py b/studio/backend/utils/hardware/amd.py
index 04b9494a29..41ee9f3fbe 100644
--- a/studio/backend/utils/hardware/amd.py
+++ b/studio/backend/utils/hardware/amd.py
@@ -3,9 +3,8 @@
 
 """AMD GPU monitoring via amd-smi.
 
-Mirrors the nvidia.py module structure so hardware.py can swap backends
-based on IS_ROCM. All functions return the same dict shapes as their
-nvidia.py counterparts.
+Mirrors nvidia.py so hardware.py can swap backends based on IS_ROCM.
+All functions return the same dict shapes as their nvidia.py counterparts.
 """
 
 import json
@@ -23,20 +22,20 @@ from utils.subprocess_compat import windows_hidden_subprocess_kwargs
 
 logger = get_logger(__name__)
 
-# amd-smi on Windows must initialise the full ROCm runtime on first call, which
-# can take 15-25 s on cold hardware.  Linux is consistently < 2 s.
+# amd-smi on Windows initialises the full ROCm runtime on first call, which
+# can take 15-25 s on cold hardware. Linux is consistently < 2 s.
 _AMD_SMI_DEFAULT_TIMEOUT = 30 if platform.system() == "Windows" else 10
 
 # Circuit breaker: stop calling amd-smi after this many consecutive failures.
 # On Windows, each failed call spawns a process that may show a UAC/DiskPart
-# elevation prompt.  Once we know amd-smi doesn't work we stop polling it.
+# elevation prompt. Once we know amd-smi doesn't work, stop polling it.
 _AMD_SMI_FAILURE_LIMIT = 3
 _amd_smi_consecutive_failures = 0
 _amd_smi_disabled = False
 
 
 def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optional[Any]:
-    """Run amd-smi with the given arguments and return parsed JSON, or None."""
+    """Run amd-smi with the given args and return parsed JSON, or None."""
     global _amd_smi_consecutive_failures, _amd_smi_disabled
     if _amd_smi_disabled:
         return None
@@ -52,7 +51,7 @@ def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optiona
     except (OSError, subprocess.TimeoutExpired) as e:
         if isinstance(e, FileNotFoundError):
             # amd-smi ships with Adrenalin, not the HIP SDK -- absence is
-            # expected on HIP SDK-only Windows setups.  Log at debug only.
+            # expected on HIP SDK-only Windows setups. Log at debug only.
             logger.debug("amd-smi not found (not in PATH): %s", e)
         else:
             logger.warning("amd-smi query failed: %s", e)
@@ -75,9 +74,9 @@ def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optiona
             _amd_smi_disabled = True
         return None
     if not result.stdout.strip():
-        # amd-smi exited successfully but produced no output (e.g. no GPUs
-        # visible on this query, or a version that emits nothing for --json).
-        # This is not a tool failure, so don't count against the circuit breaker.
+        # amd-smi exited 0 but produced no output (e.g. no GPUs visible on
+        # this query, or a version that emits nothing for --json). Not a tool
+        # failure, so don't count against the circuit breaker.
         logger.debug("amd-smi exited 0 but returned no output")
         return None
     _amd_smi_consecutive_failures = 0  # reset on success
@@ -89,7 +88,7 @@ def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optiona
 
 
 def _parse_numeric(value: Any) -> Optional[float]:
-    """Extract a numeric value from amd-smi output (may be str, int, float, or dict)."""
+    """Extract a numeric value from amd-smi output (str, int, float, or dict)."""
     if value is None:
         return None
     # Newer amd-smi versions emit {"value": 10, "unit": "W"}
@@ -114,9 +113,8 @@ def _parse_memory_mb(value: Any) -> Optional[float]:
     """Parse a memory value from amd-smi output and return MB.
 
     Handles bare numbers (assumed MB -- the amd-smi convention on every
-    version we have seen), dict-shaped values with explicit units
-    (``{"value": 192, "unit": "GiB"}`` on newer releases), and plain
-    strings like ``"8192 MiB"``.
+    version seen), dict values with explicit units (``{"value": 192,
+    "unit": "GiB"}`` on newer releases), and strings like ``"8192 MiB"``.
     """
     unit = ""
     raw_value = value
@@ -134,8 +132,8 @@ def _parse_memory_mb(value: Any) -> Optional[float]:
     if num is None:
         return None
 
-    # Unit conversion -- GPU tools (including amd-smi) use binary units even
-    # when labeling them "GB" or "MB", so treat GB/GiB and MB/MiB the same.
+    # Unit conversion -- GPU tools (incl. amd-smi) use binary units even when
+    # labeled "GB" or "MB", so treat GB/GiB and MB/MiB the same.
     if "gib" in unit or "gb" in unit:
         return num * 1024
     if "mib" in unit or "mb" in unit:
@@ -146,27 +144,27 @@ def _parse_memory_mb(value: Any) -> Optional[float]:
         # Plain bytes
         return num / (1024 * 1024)
 
-    # No explicit unit -- default to MB, which is the amd-smi convention
-    # for bare numeric values. A previous heuristic assumed values above
-    # ~10M were bytes, but that misclassifies small VRAM allocations
-    # (e.g. 5 MB = 5,242,880 reported without a unit) as ~5 TB. Modern
-    # amd-smi always ships explicit units, so the heuristic branch only
-    # fired for legacy output where MB was already the convention.
+    # No explicit unit -- default to MB, the amd-smi convention for bare
+    # numeric values. A previous heuristic assumed values above ~10M were
+    # bytes, but that misclassifies small VRAM allocations (e.g. 5 MB =
+    # 5,242,880 reported without a unit) as ~5 TB. Modern amd-smi always
+    # ships explicit units, so the heuristic only fired for legacy output
+    # where MB was already the convention.
     return num
 
 
 def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
     """Extract standardized metrics from a single GPU's amd-smi data."""
-    # amd-smi metric output structure varies by version; try common paths
+    # Output structure varies by version; try common paths
     usage = gpu_data.get("usage", gpu_data.get("gpu_activity", {}))
     if isinstance(usage, dict):
         gpu_util = _parse_numeric(usage.get("gfx_activity", usage.get("gpu_use_percent")))
     else:
         gpu_util = _parse_numeric(usage)
 
-    # Temperature -- try multiple keys in priority order.
-    # dict.get() returns "N/A" strings rather than falling through,
-    # so we must try each key and check if it parses to a real number.
+    # Temperature -- try keys in priority order. dict.get() returns "N/A"
+    # strings rather than falling through, so try each key and check it
+    # parses to a real number.
     temp_data = gpu_data.get("temperature", {})
     temp = None
     if isinstance(temp_data, dict):
@@ -191,10 +189,10 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
         power_draw = None
         power_limit = None
 
-    # VRAM -- unit-aware parsing to handle varying amd-smi output formats.
-    # Newer amd-smi versions may return {"value": 192, "unit": "GiB"}.
-    # Newer amd-smi uses "mem_usage" with "total_vram" / "used_vram" keys;
-    # older versions use "vram" or "fb_memory_usage" with "used" / "total".
+    # VRAM -- unit-aware parsing for varying amd-smi output formats.
+    # Newer versions may return {"value": 192, "unit": "GiB"} and use
+    # "mem_usage" with "total_vram" / "used_vram" keys; older versions use
+    # "vram" or "fb_memory_usage" with "used" / "total".
     vram_data = gpu_data.get(
         "mem_usage",
         gpu_data.get("vram", gpu_data.get("fb_memory_usage", {})),
@@ -239,11 +237,10 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
 def _has_real_metrics(metrics: dict[str, Any]) -> bool:
     """Return True when ``metrics`` contains at least one non-None value.
 
-    ``amd-smi`` can return a zero-exit JSON envelope that is missing every
-    expected field (error response, unsupported card, hipless container).
-    In that case ``_extract_gpu_metrics`` produces a dict where every value
-    is ``None`` -- callers must surface this as ``available: False`` rather
-    than ``available: True`` with empty data.
+    ``amd-smi`` can return a zero-exit JSON envelope missing every expected
+    field (error response, unsupported card, hipless container). Then
+    ``_extract_gpu_metrics`` produces an all-``None`` dict -- callers must
+    surface this as ``available: False``, not ``available: True`` with empty data.
     """
     return any(value is not None for value in metrics.values())
 
@@ -255,9 +252,9 @@ def get_physical_gpu_count() -> Optional[int]:
         return None
     if isinstance(data, list):
         return len(data)
-    # Some versions return a dict with a "gpu" / "gpus" key. Guard the
-    # .get() access with an isinstance check so a malformed scalar /
-    # string response from amd-smi cannot raise AttributeError.
+    # Some versions return a dict with a "gpu" / "gpus" key. Guard .get()
+    # with isinstance so a malformed scalar/string response cannot raise
+    # AttributeError.
     if not isinstance(data, dict):
         return None
     gpus = data.get("gpu", data.get("gpus", []))
@@ -267,12 +264,12 @@ def get_physical_gpu_count() -> Optional[int]:
 
 
 def _first_visible_amd_gpu_id() -> Optional[str]:
-    """Return the physical AMD GPU id that should be treated as 'primary'.
+    """Return the physical AMD GPU id treated as 'primary'.
 
     Honours HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES / CUDA_VISIBLE_DEVICES
-    in that order (HIP respects all three). Returns ``"0"`` when none are
-    set, and ``None`` when the env var explicitly narrows to zero GPUs
-    ("" or "-1"), so callers can short-circuit to "available: False".
+    in that order (HIP respects all three). Returns ``"0"`` when none are set,
+    and ``None`` when the env var narrows to zero GPUs ("" or "-1"), so callers
+    can short-circuit to "available: False".
     """
     for env_name in (
         "HIP_VISIBLE_DEVICES",
@@ -285,11 +282,10 @@ def _first_visible_amd_gpu_id() -> Optional[str]:
         raw = raw.strip()
         if raw == "" or raw == "-1":
             return None
-        # Filter out empty tokens after splitting. This tolerates minor
-        # typos like ``HIP_VISIBLE_DEVICES=",1"`` (leading comma, user
-        # clearly meant to narrow to device 1) while still falling
-        # through to the next env var when every token is empty
-        # (e.g. ``,,,``).
+        # Drop empty tokens after splitting. Tolerates minor typos like
+        # ``HIP_VISIBLE_DEVICES=",1"`` (leading comma, clearly meant device 1)
+        # while still falling through to the next env var when every token is
+        # empty (e.g. ``,,,``).
         tokens = [t.strip() for t in raw.split(",") if t.strip()]
         if tokens:
             return tokens[0]
@@ -320,10 +316,9 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 
     metrics = _extract_gpu_metrics(gpu_data)
     if not _has_real_metrics(metrics):
-        # amd-smi returned a JSON envelope with no usable fields (error
-        # response or unsupported card). Surface as unavailable rather
-        # than available-with-empty-data so the UI does not render a
-        # ghost device.
+        # JSON envelope with no usable fields (error response or unsupported
+        # card). Surface as unavailable rather than available-with-empty-data
+        # so the UI does not render a ghost device.
         return {"available": False}
     metrics["available"] = True
     return metrics
@@ -352,11 +347,10 @@ def get_visible_gpu_utilization(
             "index_kind": "physical",
         }
 
-    # Extract a device list from amd-smi's envelope. Newer versions return
-    # a JSON array directly, older versions return a dict with a "gpus" /
-    # "gpu" key wrapping the list. Guard non-dict / non-list envelopes
-    # (scalar / string fallbacks from malformed output) so the .get()
-    # access cannot raise AttributeError on an unexpected shape.
+    # Extract a device list from amd-smi's envelope. Newer versions return a
+    # JSON array directly; older versions wrap the list in a dict under
+    # "gpus" / "gpu". Guard non-dict / non-list envelopes (scalar/string
+    # fallbacks from malformed output) so .get() cannot raise AttributeError.
     if isinstance(data, list):
         gpu_list = data
     elif isinstance(data, dict):
@@ -369,17 +363,15 @@ def get_visible_gpu_utilization(
 
     devices = []
     for fallback_idx, gpu_data in enumerate(gpu_list):
-        # Skip non-dict entries defensively: if amd-smi ever ships a
-        # scalar inside its "gpus" array (observed on some malformed
-        # output), _extract_gpu_metrics would raise AttributeError on
-        # the first .get() call.
+        # Skip non-dict entries: a scalar inside the "gpus" array (seen on
+        # some malformed output) would make _extract_gpu_metrics raise
+        # AttributeError on the first .get() call.
         if not isinstance(gpu_data, dict):
             continue
-        # Use AMD-reported GPU ID when available, fall back to enumeration
-        # index. Newer amd-smi versions wrap scalars as ``{"value": 0,
-        # "unit": "none"}``, so route raw_id through ``_parse_numeric``
-        # which already handles bare ints, floats, strings, and that
-        # dict shape uniformly.
+        # Use AMD-reported GPU ID when available, else the enumeration index.
+        # Newer amd-smi wraps scalars as ``{"value": 0, "unit": "none"}``, so
+        # route raw_id through ``_parse_numeric`` which handles bare ints,
+        # floats, strings, and that dict shape uniformly.
         raw_id = gpu_data.get("gpu", gpu_data.get("gpu_id", gpu_data.get("id", fallback_idx)))
         parsed_id = _parse_numeric(raw_id)
         if parsed_id is None:
@@ -403,10 +395,9 @@ def get_visible_gpu_utilization(
             continue
         metrics = _extract_gpu_metrics(gpu_data)
         if not _has_real_metrics(metrics):
-            # Skip ghost entries: an amd-smi response that decodes to a
-            # dict but contains no usable fields (error envelope, etc.)
-            # would otherwise show up as a device row with all-None
-            # numbers in the UI.
+            # Skip ghost entries: a dict response with no usable fields
+            # (error envelope, etc.) would otherwise show up as a device row
+            # with all-None numbers in the UI.
             continue
         metrics["index"] = idx
         metrics["index_kind"] = "physical"
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index 3f2823302a..df3fbac47a 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -39,7 +39,7 @@ logger = get_logger(__name__)
 
 
 class DeviceType(str, Enum):
-    """Supported compute backends. Inherits from str so it serializes cleanly in JSON."""
+    """Supported compute backends. str subclass for clean JSON serialization."""
 
     CUDA = "cuda"
     XPU = "xpu"
@@ -57,14 +57,11 @@ IS_ROCM: bool = False  # True when running on AMD ROCm (HIP) -- routes GPU monit
 def _backend_label(device: DeviceType) -> str:
     """Return the user-facing backend name for API responses.
 
-    Internally we still represent ROCm hosts as ``DeviceType.CUDA`` because
-    ROCm torch sets ``torch.cuda.is_available() = True`` and reuses the whole
-    ``torch.cuda.*`` API surface, so branching on ``DeviceType`` stays
-    consistent with the rest of the codebase. For the JSON responses served
-    to the Studio frontend and other clients, however, "cuda" is misleading
-    on an AMD machine. This helper swaps the label to ``"rocm"`` when the
-    module-level ``IS_ROCM`` flag is set so the UI can render the correct
-    backend name without every caller having to duplicate the check.
+    ROCm hosts stay ``DeviceType.CUDA`` internally (ROCm torch sets
+    ``torch.cuda.is_available() = True`` and reuses ``torch.cuda.*``), so
+    branching on ``DeviceType`` stays consistent. But "cuda" is misleading
+    in JSON responses on an AMD machine, so this swaps the label to
+    ``"rocm"`` when ``IS_ROCM`` is set, sparing callers the check.
     """
     if IS_ROCM and device == DeviceType.CUDA:
         return "rocm"
@@ -75,12 +72,12 @@ def _backend_label(device: DeviceType) -> str:
 
 
 def is_apple_silicon() -> bool:
-    """Check if running on Apple Silicon hardware (pure platform check, no ML imports)."""
+    """True on Apple Silicon (pure platform check, no ML imports)."""
     return platform.system() == "Darwin" and platform.machine() == "arm64"
 
 
 def _has_torch() -> bool:
-    """Check if PyTorch is importable."""
+    """True if PyTorch is importable."""
     try:
         import torch
         return True
@@ -89,7 +86,7 @@ def _has_torch() -> bool:
 
 
 def _has_mlx() -> bool:
-    """Check if MLX is importable."""
+    """True if MLX is importable."""
     try:
         import mlx.core
         return True
@@ -99,10 +96,9 @@ def _has_mlx() -> bool:
 
 def detect_hardware() -> DeviceType:
     """
-    Detect the best available compute device and set the module-level DEVICE global.
+    Detect the best compute device and set the module-level DEVICE global.
 
-    Should be called exactly once during FastAPI lifespan startup.
-    Safe to call multiple times (idempotent).
+    Call once at FastAPI lifespan startup; idempotent.
 
     Detection order:
       1. CUDA  (NVIDIA GPU, requires torch)
@@ -121,10 +117,10 @@ def detect_hardware() -> DeviceType:
             CHAT_ONLY = False
             device_name = torch.cuda.get_device_properties(0).name
 
-            # Distinguish AMD ROCm (HIP) from NVIDIA CUDA for display purposes.
+            # Distinguish AMD ROCm (HIP) from NVIDIA CUDA for display only;
             # DeviceType stays CUDA since torch.cuda.* works on ROCm via HIP.
-            # AMD's repo.radeon.com SDK wheels (e.g. 2.9.0+rocmsdk20251116) do
-            # not set torch.version.hip, so fall back to checking __version__.
+            # AMD's repo.radeon.com SDK wheels (e.g. 2.9.0+rocmsdk20251116)
+            # don't set torch.version.hip, so fall back to __version__.
             _hip_ver = getattr(torch.version, "hip", None)
             if _hip_ver is not None or "rocm" in torch.__version__.lower():
                 IS_ROCM = True
@@ -148,9 +144,9 @@ def detect_hardware() -> DeviceType:
     if is_apple_silicon() and _has_mlx():
         DEVICE = DeviceType.MLX
         CHAT_ONLY = False
-        # platform.processor() runs `uname -p` which returns "i386" on most
-        # universal2 / Rosetta-shaped Python builds even on native arm64.
-        # platform.machine() is "arm64" once is_apple_silicon() has gated us.
+        # platform.processor() (`uname -p`) returns "i386" on most
+        # universal2 / Rosetta Python builds even on native arm64.
+        # platform.machine() is "arm64" once is_apple_silicon() gated us.
         chip = platform.machine() or "arm64"
         print(f"Hardware detected: MLX — Apple Silicon ({chip})")
         return DEVICE
@@ -166,8 +162,8 @@ def detect_hardware() -> DeviceType:
 
 def get_device() -> DeviceType:
     """
-    Return the detected device. Auto-detects if detect_hardware() hasn't been called yet.
-    Prefer calling detect_hardware() explicitly at startup instead.
+    Return the detected device, auto-detecting if detect_hardware() hasn't run.
+    Prefer calling detect_hardware() explicitly at startup.
     """
     global DEVICE
     if DEVICE is None:
@@ -178,7 +174,7 @@ def get_device() -> DeviceType:
 def clear_gpu_cache():
     """
     Clear GPU memory cache for the current device.
-    Safe to call on any platform — no-ops gracefully.
+    Safe on any platform — no-ops gracefully.
     """
     gc.collect()
 
@@ -195,15 +191,15 @@ def clear_gpu_cache():
         torch.xpu.synchronize()
         torch.xpu.empty_cache()
     elif device == DeviceType.MLX:
-        # MLX manages memory automatically; no explicit cache clear needed.
-        # mlx.core has no empty_cache equivalent — gc.collect() above is enough.
+        # MLX manages memory automatically; no empty_cache equivalent,
+        # so the gc.collect() above is enough.
         pass
 
 
 def get_gpu_memory_info() -> Dict[str, Any]:
     """
-    Get GPU memory information.
-    Supports CUDA (NVIDIA), MLX (Apple Silicon), and CPU-only environments.
+    Get GPU memory info.
+    Supports CUDA (NVIDIA), MLX (Apple Silicon), and CPU-only.
     """
     device = get_device()
 
@@ -275,8 +271,8 @@ def get_gpu_memory_info() -> Dict[str, Any]:
             import mlx.core as mx
             import psutil
 
-            # MLX uses unified memory. Total = system RAM. GPU memory used
-            # comes from IORegistry's AGXAccelerator (system-wide, no sudo).
+            # MLX uses unified memory: total = system RAM, GPU used comes
+            # from IORegistry's AGXAccelerator (system-wide, no sudo).
             total = psutil.virtual_memory().total
             agx = _read_apple_gpu_stats()
             allocated = agx.get("vram_used_bytes", 0) if agx else 0
@@ -284,7 +280,7 @@ def get_gpu_memory_info() -> Dict[str, Any]:
             try:
                 info = mx.device_info()
                 # See detect_hardware(): platform.processor() can return "i386"
-                # on native arm64 Python builds, so prefer machine() as fallback.
+                # on native arm64 builds, so prefer machine() as fallback.
                 gpu_name = info.get("device_name") or platform.machine() or "arm64"
             except Exception:
                 gpu_name = platform.machine() or "arm64"
@@ -352,13 +348,11 @@ def get_gpu_summary() -> Dict[str, Any]:
 
 def get_package_versions() -> Dict[str, Optional[str]]:
     """
-    Return the installed versions of key ML packages.
+    Return installed versions of key ML packages.
 
-    Uses importlib.metadata (stdlib) so no subprocess is needed.
-    CUDA version comes from torch.version.cuda.
-
-    Returns dict with keys: unsloth, torch, transformers, cuda.
-    Missing packages yield None.
+    Uses importlib.metadata (stdlib), no subprocess. CUDA version from
+    torch.version.cuda. Returns dict keyed unsloth/torch/transformers/cuda;
+    missing packages yield None.
     """
     packages = ("unsloth", "torch", "transformers")
     versions: Dict[str, Optional[str]] = {}
@@ -418,8 +412,8 @@ def _torch_get_per_device_info(device_indices: list[int]) -> list[Dict[str, Any]
             # torch uses 0-based ordinals relative to CUDA_VISIBLE_DEVICES
             props = mod.get_device_properties(ordinal)
             total_bytes = props.total_memory
-            # Prefer mem_get_info (reports system-wide usage, not just this
-            # process) so auto-selection accounts for other GPU consumers.
+            # Prefer mem_get_info (system-wide usage, not just this process)
+            # so auto-selection accounts for other GPU consumers.
             if hasattr(mod, "mem_get_info"):
                 free_bytes, total_bytes = mod.mem_get_info(ordinal)
                 used_bytes = total_bytes - free_bytes
@@ -443,9 +437,9 @@ def _torch_get_per_device_info(device_indices: list[int]) -> list[Dict[str, Any]
 
 
 def _smi_query(func_name: str, *args, **kwargs) -> Optional[Dict[str, Any]]:
-    """Run a query against the appropriate SMI backend (amd-smi or nvidia-smi).
+    """Query the appropriate SMI backend (amd-smi or nvidia-smi).
 
-    Returns the result dict if available, or None on failure/unavailability.
+    Returns the result dict if available, else None.
     """
     if IS_ROCM:
         backend_name = "amd-smi"
@@ -474,8 +468,8 @@ def _smi_query(func_name: str, *args, **kwargs) -> Optional[Dict[str, Any]]:
 def _read_apple_gpu_stats() -> Dict[str, Any]:
     """Query macOS IORegistry for AGX (Apple GPU) live stats. No sudo needed.
 
-    Returns dict with utilization_pct, vram_used_bytes (system-wide GPU memory).
-    Returns empty dict on failure.
+    Returns dict with utilization_pct, vram_used_bytes (system-wide GPU
+    memory), or empty dict on failure.
     """
     try:
         result = subprocess.run(
@@ -574,7 +568,7 @@ def _rocm_windows_perf_counter_gpu_util_pct() -> Optional[float]:
 def _rocm_linux_sysfs_vram_gb() -> tuple[Optional[float], Optional[float]]:
     """Query system-wide AMD GPU VRAM via Linux DRM sysfs.
 
-    Reads /sys/class/drm/card*/device/mem_info_vram_* which the kernel
+    Reads /sys/class/drm/card*/device/mem_info_vram_*, which the kernel
     updates in real-time across all processes. No tools required.
     Returns (used_gb, total_gb) or (None, None) on failure.
     """
@@ -597,8 +591,8 @@ def _rocm_linux_sysfs_vram_gb() -> tuple[Optional[float], Optional[float]]:
 def _rocm_windows_perf_counter_vram_gb() -> tuple[Optional[float], Optional[float]]:
     """Query system-wide dedicated GPU VRAM via Windows Performance Counters.
 
-    Uses the same data source as Task Manager so it reflects cross-process
-    usage accurately. Works for any GPU vendor without amd-smi or nvidia-smi.
+    Same data source as Task Manager, so cross-process usage is accurate.
+    Works for any GPU vendor without amd-smi or nvidia-smi.
     Returns (used_gb, total_gb) or (None, None) on failure.
     """
     if platform.system() != "Windows":
@@ -640,10 +634,10 @@ def get_gpu_utilization() -> Dict[str, Any]:
                 # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
                 _reconcile_primary_rocm_unified_memory(result, _get_parent_visible_gpu_spec())
             return result
-        # SMI tool unavailable or returned no usable data. On Windows, query
+        # SMI tool unavailable or returned nothing usable. On Windows, query
         # the Performance Counter API (same source as Task Manager) for
         # system-wide dedicated VRAM — covers cross-process usage that
-        # torch.cuda.mem_get_info cannot see from the Studio server process.
+        # torch.cuda.mem_get_info can't see from the Studio server process.
         if IS_ROCM and platform.system() == "Windows":
             _win_used, _win_total = _rocm_windows_perf_counter_vram_gb()
             if _win_used is not None and _win_total is not None:
@@ -705,8 +699,8 @@ def get_gpu_utilization() -> Dict[str, Any]:
                 "power_utilization_pct": None,
             }
 
-    # MLX path: single _read_apple_gpu_stats() call carries both VRAM-used
-    # bytes and GPU utilization %. psutil for unified-memory total is cheap.
+    # MLX path: one _read_apple_gpu_stats() call carries both VRAM-used bytes
+    # and GPU utilization %. psutil for unified-memory total is cheap.
     if device == DeviceType.MLX:
         try:
             import psutil
@@ -772,8 +766,8 @@ def _apply_unified_memory_correction(
     """Per-device reconciliation: when torch reports a larger memory total
     than amd-smi, overwrite the smi VRAM fields in place.
 
-    Used by both the multi-device and primary-device reconciliation helpers
-    so the two endpoints stay in sync on AMD iGPUs with unified memory.
+    Used by both the multi-device and primary-device reconcilers so the two
+    endpoints stay in sync on AMD iGPUs with unified memory.
     """
     torch_total_gb = torch_info["total_gb"]
     smi_total_gb = device_metrics.get("vram_total_gb") or 0.0
@@ -798,7 +792,7 @@ def _reconcile_rocm_unified_memory(utilization: Dict[str, Any], device_indices:
 
     amd-smi reports only the dedicated slice (~512 MB); torch sees the full
     GTT pool (~128 GB). When torch total > smi total, overwrite per-device
-    VRAM fields so GPU selection uses the real available memory.
+    VRAM fields so GPU selection uses real available memory.
     """
     torch_devices = _torch_get_per_device_info(device_indices)
     if not torch_devices:
@@ -820,10 +814,9 @@ def _reconcile_primary_rocm_unified_memory(
         # No visibility env var set: torch ordinal 0 is the primary device.
         primary_idx = [0]
     elif len(numeric_ids) == 0:
-        # Empty mask (HIP_VISIBLE_DEVICES="" or "-1"): no GPU is visible to
-        # this process. Querying torch device 0 would raise a RuntimeError or
-        # return stale/wrong data, so bail out rather than writing bad values
-        # into the utilization dict.
+        # Empty mask (HIP_VISIBLE_DEVICES="" or "-1"): no GPU visible to this
+        # process. Querying torch device 0 would raise or return stale data,
+        # so bail rather than write bad values into the utilization dict.
         return
     else:
         primary_idx = [int(numeric_ids[0])]
@@ -942,14 +935,14 @@ _visible_gpu_count: Optional[int] = None
 
 
 def _get_parent_visible_gpu_spec() -> Dict[str, Any]:
-    # ROCm uses HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES in addition to
-    # CUDA_VISIBLE_DEVICES (which HIP also respects).  Check ROCm-specific
-    # env vars first so multi-GPU AMD setups are handled correctly.
-    # Use explicit None checks (not `or`) so empty string "" is honoured
-    # as "no visible GPUs" rather than falling through to CUDA_VISIBLE_DEVICES.
+    # ROCm uses HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES on top of
+    # CUDA_VISIBLE_DEVICES (which HIP also respects). Check ROCm env vars
+    # first for multi-GPU AMD setups. Use explicit None checks (not `or`)
+    # so empty string "" is honoured as "no visible GPUs" rather than
+    # falling through to CUDA_VISIBLE_DEVICES.
     cuda_visible = None
     # Prefer ROCm masks only on a ROCm host, or when no CUDA mask is set, so a
-    # stale HIP_VISIBLE_DEVICES on an NVIDIA host can't override CUDA_VISIBLE_DEVICES.
+    # stale HIP_VISIBLE_DEVICES on NVIDIA can't override CUDA_VISIBLE_DEVICES.
     _is_rocm_spec = IS_ROCM or (
         "CUDA_VISIBLE_DEVICES" not in os.environ
         and ("HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ)
@@ -1027,7 +1020,7 @@ def resolve_requested_gpu_ids(gpu_ids: Optional[list[int]]) -> list[int]:
             f"Parent-visible GPUs: {parent_visible_ids}"
         )
 
-    # Reject negative IDs unconditionally.
+    # Reject negative IDs.
     negative_ids = [gpu_id for gpu_id in requested_ids if gpu_id < 0]
     if negative_ids:
         raise ValueError(
@@ -1035,12 +1028,11 @@ def resolve_requested_gpu_ids(gpu_ids: Optional[list[int]]) -> list[int]:
             f"Rejected IDs: {negative_ids}. Parent-visible GPUs: {parent_visible_ids}"
         )
 
-    # Only enforce the physical upper bound when we have a reliable count
-    # from nvidia-smi. When the count comes from torch, it reflects visible
-    # devices (filtered by CUDA_VISIBLE_DEVICES), not the physical total,
-    # so high physical indices like 3 would be falsely rejected on a
-    # CUDA_VISIBLE_DEVICES="2,3" machine that reports device_count()=2.
-    # The parent-visible check below is authoritative in all cases.
+    # Only enforce the physical upper bound when the count is reliable
+    # (from nvidia-smi). A torch count reflects visible devices (filtered by
+    # CUDA_VISIBLE_DEVICES), not the physical total, so e.g. index 3 would be
+    # falsely rejected on a CUDA_VISIBLE_DEVICES="2,3" host reporting
+    # device_count()=2. The parent-visible check below is always authoritative.
     if physical_gpu_count > 0 and parent_visible_ids:
         max_parent_id = max(parent_visible_ids)
         if physical_gpu_count > max_parent_id:
@@ -1123,13 +1115,13 @@ def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = Non
 
 
 def _determine_attention_impl_for_gpu_estimate(config) -> str:
-    # torch.distributed is incomplete on Windows ROCm — torch._C is a C
-    # extension (not a package), so Python cannot import the submodule
-    # torch._C._distributed_c10d that torch.distributed depends on.
-    # Inject an empty stub into sys.modules BEFORE importing torch.distributed
-    # so the import succeeds, then patch the missing process-group helpers.
+    # torch.distributed is incomplete on Windows ROCm: torch._C is a C
+    # extension (not a package), so the submodule torch._C._distributed_c10d
+    # that torch.distributed depends on can't be imported. Inject an empty
+    # stub into sys.modules BEFORE importing torch.distributed so the import
+    # succeeds, then patch the missing process-group helpers.
     if sys.platform == "win32" and IS_ROCM:
-        # Dummy class for any name torch.distributed tries to import from these stubs
+        # Dummy for any name torch.distributed imports from these stubs
         class _Dummy:
             pass
 
@@ -1177,11 +1169,11 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
     from unsloth.models._utils import resolve_attention_implementation
     from transformers import AutoModel, AutoModelForCausalLM
 
-    # why: resolve_attention_implementation calls _set_attn_impl which writes
+    # why: resolve_attention_implementation calls _set_attn_impl, which writes
     # _attn_implementation onto the config; PreTrainedConfig's setter walks
     # `sub_configs` and propagates to nested text_config / sub-configs, so a
-    # shallow copy still mutates those shared inner objects on the cached
-    # config returned by _load_config_for_gpu_estimate. Deepcopy isolates them.
+    # shallow copy would still mutate those shared inner objects on the cached
+    # config from _load_config_for_gpu_estimate. Deepcopy isolates them.
     config_copy = copy.deepcopy(config)
 
     model_class = None
@@ -1357,15 +1349,15 @@ def estimate_required_model_memory_gb(
                 config
             )
         except Exception as e:
-            # Log at debug: on Windows ROCm the torch.distributed stub does
-            # not implement Store, so this fires on every estimate call.
-            # It is expected and non-actionable -- eager is the safe fallback.
+            # Debug-level: on Windows ROCm the torch.distributed stub lacks
+            # Store, so this fires every estimate call. Expected and
+            # non-actionable -- eager is the safe fallback.
             logger.debug(
                 "Could not resolve attention implementation for '%s': %s",
                 estimate_model,
                 e,
             )
-            # why: if we cannot prove flash attention is usable, charge the
+            # why: if flash attention can't be proven usable, charge the
             # quadratic non-flash activation path so GPU selection stays
             # conservative.
             vram_config.attention_implementation = "eager"
@@ -1374,14 +1366,14 @@ def estimate_required_model_memory_gb(
     if arch is not None:
         breakdown = estimate_training_vram(arch, vram_config)
         # why: extract_arch_config only sees text_config; safetensors include
-        # vision/audio tower bytes that the text-arch fp16 total misses.
+        # vision/audio tower bytes the text-arch fp16 total misses.
         arch_fp16_bytes = compute_total_params(arch) * 2
         extra_bytes = max(0, int(model_size_bytes) - arch_fp16_bytes)
         if extra_bytes > 0:
             breakdown.model_weights += extra_bytes
             if training_method == "full":
                 # why: full fine-tuning makes the extra (vision/audio) params
-                # trainable; optimizer + gradient bytes scale with them too.
+                # trainable; optimizer + gradient bytes scale with them.
                 extra_params = extra_bytes // 2
                 breakdown.optimizer_states += compute_optimizer_bytes(
                     extra_params,
@@ -1460,9 +1452,8 @@ def auto_select_gpu_ids(
         return None, metadata
 
     if required_gb is None:
-        # Cannot estimate model size -- fall back to all visible GPUs
-        # rather than risk loading on a single GPU that may not have
-        # enough memory.
+        # Cannot estimate model size -- fall back to all visible GPUs rather
+        # than risk loading on a single GPU that may lack memory.
         parent_ids = get_parent_visible_gpu_ids()
         metadata["selection_mode"] = "fallback_all"
         metadata["selected_gpu_ids"] = parent_ids
@@ -1500,17 +1491,16 @@ def auto_select_gpu_ids(
     free_by_index = {item["index"]: item["free_gb"] for item in ranked}
     selected: list[int] = []
     usable_gb = 0.0
-    # Multi-GPU sharding has overhead from inter-GPU communication (NCCL
-    # all-reduce, PCIe/NVLink transfers, synchronization barriers), so each
-    # additional GPU contributes less than its raw free memory. The first GPU
-    # keeps its full capacity (no cross-device overhead). 0.85 was calibrated
-    # empirically on 2-8 GPU setups with NVLink and PCIe topologies -- the
-    # 15% discount accounts for NCCL buffers (~2-5% of VRAM), pipeline bubble
-    # overhead, and memory fragmentation from non-uniform shard sizes.
+    # Multi-GPU sharding has inter-GPU communication overhead (NCCL
+    # all-reduce, PCIe/NVLink transfers, sync barriers), so each extra GPU
+    # contributes less than its raw free memory; the first GPU keeps full
+    # capacity. 0.85 was calibrated empirically on 2-8 GPU NVLink/PCIe
+    # setups -- the 15% discount covers NCCL buffers (~2-5% of VRAM),
+    # pipeline bubble overhead, and fragmentation from non-uniform shards.
     multi_gpu_overhead = 0.85
 
     # Per-GPU check: activations don't shard, so each GPU needs its weight
-    # shard + full activation cost. Use precomputed min_per_gpu_N values.
+    # shard + full activation cost. Uses precomputed min_per_gpu_N values.
     vram_breakdown = estimate_metadata.get("vram_breakdown", {})
 
     for candidate in ranked:
@@ -1547,7 +1537,7 @@ def auto_select_gpu_ids(
             )
             return selected, metadata
 
-    # Use only GPUs with verified VRAM data (from gpu_candidates, not raw devices)
+    # Use only GPUs with verified VRAM data (gpu_candidates, not raw devices)
     fallback_all = [c["index"] for c in gpu_candidates] if gpu_candidates else parent_ids
     metadata["selection_mode"] = "fallback_all"
     if ranked:
@@ -1586,18 +1576,17 @@ def prepare_gpu_selection(
     """Resolve which physical GPUs to use for a model load.
 
     GPU selection modes:
-      - **Explicit** (``gpu_ids=[5, 6, 7]``): the caller chooses exact GPUs.
-        All listed GPUs are used and the model is sharded across them via
-        ``device_map="balanced"``, regardless of whether the model would fit
-        on fewer GPUs.  IDs are validated against the parent-visible set.
-      - **Auto** (``gpu_ids=None`` or ``[]``): ``auto_select_gpu_ids`` estimates
-        VRAM requirements and picks the *minimum* number of GPUs needed,
-        preferring GPUs with the most free memory.
+      - **Explicit** (``gpu_ids=[5, 6, 7]``): caller chooses exact GPUs.
+        All listed GPUs are used and the model is sharded via
+        ``device_map="balanced"``, even if it would fit on fewer. IDs are
+        validated against the parent-visible set.
+      - **Auto** (``gpu_ids=None`` or ``[]``): ``auto_select_gpu_ids``
+        estimates VRAM needs and picks the *minimum* GPUs needed,
+        preferring those with the most free memory.
 
-    The returned ``gpu_ids`` list is later passed to ``get_device_map()`` which
-    maps it to a Hugging Face ``device_map`` string, and to ``apply_gpu_ids()``
-    in the worker subprocess which narrows ``CUDA_VISIBLE_DEVICES`` before any
-    torch/CUDA initialisation.
+    The returned ``gpu_ids`` is later passed to ``get_device_map()`` (maps it
+    to a Hugging Face ``device_map`` string) and to ``apply_gpu_ids()`` in the
+    worker subprocess (narrows ``CUDA_VISIBLE_DEVICES`` before torch/CUDA init).
     """
     if gpu_ids and get_device() != DeviceType.CUDA:
         raise ValueError(
@@ -1633,8 +1622,7 @@ def get_physical_gpu_count() -> int:
     Return the number of physical GPUs on the machine.
 
     Uses ``nvidia-smi -L`` on NVIDIA (unaffected by CUDA_VISIBLE_DEVICES),
-    with a torch-based fallback for AMD ROCm and Intel XPU.
-    Result is cached after the first call.
+    with a torch fallback for AMD ROCm and Intel XPU. Cached after first call.
     """
     global _physical_gpu_count
     if _physical_gpu_count is not None:
@@ -1676,10 +1664,10 @@ def get_physical_gpu_count() -> int:
 def _backend_visible_devices_env() -> Optional[str]:
     """Return the raw visibility env string that applies to this backend.
 
-    On ROCm, HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES take precedence
-    over CUDA_VISIBLE_DEVICES; the helper mirrors the resolution logic in
-    ``_get_parent_visible_gpu_spec`` so ``backend_cuda_visible_devices``
-    reports the value that is actually narrowing the visible device set.
+    On ROCm, HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES take precedence over
+    CUDA_VISIBLE_DEVICES; this mirrors ``_get_parent_visible_gpu_spec`` so
+    ``backend_cuda_visible_devices`` reports the value actually narrowing the
+    visible device set.
     """
     if IS_ROCM:
         return _get_parent_visible_gpu_spec().get("raw")
@@ -1706,7 +1694,7 @@ def get_backend_visible_gpu_info() -> Dict[str, Any]:
             except Exception as e:
                 logger.warning("Backend GPU visibility query failed: %s", e)
 
-        # Torch fallback (AMD ROCm, Intel XPU, nvidia-smi missing/failed)
+        # Torch fallback (AMD ROCm, Intel XPU, nvidia-smi missing/failed).
         # When parent_visible_ids is empty (UUID/MIG mask), enumerate by
         # torch ordinal so the UI still shows devices.
         if parent_visible_ids:
@@ -1789,15 +1777,15 @@ def get_visible_gpu_count() -> int:
     Return the number of GPUs visible to this process.
 
     Respects ``CUDA_VISIBLE_DEVICES`` -- if set, only those GPUs count.
-    Falls back to physical count if the env var is unset or torch is
-    unavailable.  Result is cached after the first call.
+    Falls back to physical count if unset or torch is unavailable.
+    Cached after the first call.
     """
     global _visible_gpu_count
     if _visible_gpu_count is not None:
         return _visible_gpu_count
 
-    # Use _get_parent_visible_gpu_spec() which already handles
-    # HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES on ROCm.
+    # _get_parent_visible_gpu_spec() already handles HIP_VISIBLE_DEVICES /
+    # ROCR_VISIBLE_DEVICES on ROCm.
     visible_spec = _get_parent_visible_gpu_spec()
     if visible_spec["raw"] is not None:
         raw = visible_spec["raw"].strip()
@@ -1809,7 +1797,7 @@ def get_visible_gpu_count() -> int:
             _visible_gpu_count = len([x for x in raw.split(",") if x.strip()])
         return _visible_gpu_count
 
-    # No visibility env var set -- try torch, fall back to physical count
+    # No visibility env var set -- try torch, else physical count
     try:
         import torch
         if get_device() == DeviceType.XPU and hasattr(torch, "xpu"):
@@ -1826,9 +1814,9 @@ def apply_gpu_ids(gpu_ids) -> None:
     if gpu_ids is None:
         return
 
-    # Empty list means "no GPUs visible" -- treat the same as None
-    # (inherit parent) to avoid setting CUDA_VISIBLE_DEVICES="" which
-    # disables CUDA entirely and crashes downstream torch calls.
+    # Empty list means "no GPUs visible" -- treat like None (inherit parent)
+    # to avoid setting CUDA_VISIBLE_DEVICES="", which disables CUDA entirely
+    # and crashes downstream torch calls.
     if isinstance(gpu_ids, (list, tuple)) and len(gpu_ids) == 0:
         return
 
@@ -1841,22 +1829,21 @@ def apply_gpu_ids(gpu_ids) -> None:
 
     os.environ["CUDA_VISIBLE_DEVICES"] = value
     # Keep ROCm visibility env vars in sync so _get_parent_visible_gpu_spec()
-    # picks up the narrowed set on AMD systems. Workers can call
-    # apply_gpu_ids() before detect_hardware() runs (so IS_ROCM is still
-    # its default False), so also mirror the selection whenever the
-    # parent process already set a ROCm visibility variable -- that
-    # way a downstream ROCm process inherits the narrowed mask even
-    # before Studio's hardware detection has classified the host.
-    # Final fallback: probe torch.version.hip so AMD workers without
-    # HIP_VISIBLE_DEVICES still get the correct ROCm visibility mask.
+    # picks up the narrowed set on AMD. Workers may call apply_gpu_ids()
+    # before detect_hardware() runs (IS_ROCM still default False), so also
+    # mirror the selection whenever the parent already set a ROCm visibility
+    # var -- a downstream ROCm process then inherits the narrowed mask before
+    # hardware detection classifies the host. Final fallback: probe
+    # torch.version.hip so AMD workers without HIP_VISIBLE_DEVICES still get
+    # the correct ROCm visibility mask.
     _inherits_rocm_visibility = (
         "HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ
     )
     _is_rocm = IS_ROCM or _inherits_rocm_visibility
     if not _is_rocm:
         # torch.version.hip is a non-empty string on ROCm, None on CUDA.
-        # AMD SDK / Radeon ROCm wheels can leave torch.version.hip unset but
-        # still encode "rocm" in torch.__version__, matching detect_hardware().
+        # AMD SDK / Radeon ROCm wheels may leave it unset but still encode
+        # "rocm" in torch.__version__ (matching detect_hardware()).
         # Broad except: a probe failure must never crash a training worker.
         try:
             import torch as _torch
@@ -1886,22 +1873,21 @@ def get_device_map(gpu_ids: Optional[list[int]] = None) -> str:
     Returns ``"balanced"`` (shard evenly across GPUs) when:
       - ``gpu_ids`` explicitly lists >1 GPU, **or**
       - ``CUDA_VISIBLE_DEVICES`` uses UUID/MIG identifiers (non-numeric) and
-        more than one GPU is visible (fallback: we cannot resolve numeric IDs,
-        so we assume the caller intends multi-GPU).
+        >1 GPU is visible (fallback: numeric IDs unresolvable, so assume
+        multi-GPU is intended).
 
-    Returns ``"sequential"`` (single device) in all other cases, including
-    non-CUDA backends (CPU, MLX).
+    Returns ``"sequential"`` (single device) otherwise, including non-CUDA
+    backends (CPU, MLX).
 
-    Callers should use ``prepare_gpu_selection()`` upstream to determine the
-    ``gpu_ids`` list -- that function handles the smart auto-selection of the
-    minimum number of GPUs needed for a given model.
+    Use ``prepare_gpu_selection()`` upstream to determine ``gpu_ids`` -- it
+    handles auto-selecting the minimum GPUs needed for a model.
     """
     device = get_device()
     if device == DeviceType.CUDA:
         multi_gpu = gpu_ids is not None and len(gpu_ids) > 1
 
         if not multi_gpu:
-            # UUID/MIG masks cannot be split into numeric IDs, so if multiple
+            # UUID/MIG masks can't be split into numeric IDs, so if multiple
             # GPUs are visible we assume multi-GPU sharding is intended.
             parent_visible_spec = _get_parent_visible_gpu_spec()
             if parent_visible_spec["numeric_ids"] is None and get_visible_gpu_count() > 1:
@@ -1944,18 +1930,14 @@ def safe_num_proc(desired: Optional[int] = None) -> int:
     """
     Return a safe ``num_proc`` for ``dataset.map()`` calls.
 
-    On Windows, always returns 1 because Python uses ``spawn`` instead of
-    ``fork`` for multiprocessing -- the overhead of re-importing torch,
-    transformers, unsloth etc. per worker is typically slower than
-    single-process for normal dataset sizes.
+    On Windows always returns 1: Python uses ``spawn`` not ``fork``, so
+    re-importing torch/transformers/unsloth per worker is typically slower
+    than single-process for normal dataset sizes.
 
-    On multi-GPU machines (where multiple GPUs are *visible* to this
-    process) the NVIDIA driver spawns extra background threads, making
-    ``os.fork()`` prone to deadlocks when many workers are created.
-    This helper caps ``num_proc`` to 4 on such machines.
-
-    When ``CUDA_VISIBLE_DEVICES`` restricts to a single GPU, the cap
-    does not apply.
+    On multi-GPU machines (multiple GPUs *visible* to this process) the
+    NVIDIA driver spawns extra background threads, making ``os.fork()``
+    deadlock-prone with many workers, so this caps ``num_proc`` to 4.
+    The cap does not apply when ``CUDA_VISIBLE_DEVICES`` restricts to one GPU.
 
     Args:
         desired: The num_proc you *want*. If None, auto-computes from
@@ -1964,9 +1946,8 @@ def safe_num_proc(desired: Optional[int] = None) -> int:
     Returns:
         A safe integer ≥ 1.
     """
-    # Windows and macOS use 'spawn' for multiprocessing -- the overhead of
-    # re-importing torch/transformers/unsloth per worker is typically slower
-    # than single-process.
+    # Windows/macOS use 'spawn'; re-importing torch/transformers/unsloth per
+    # worker is typically slower than single-process.
     if sys.platform in ("win32", "darwin"):
         return 1
 
@@ -1989,9 +1970,8 @@ def safe_thread_num_proc(desired: Optional[int] = None) -> int:
     """
     Return a safe worker count for ``ThreadPoolExecutor`` calls.
 
-    Unlike ``safe_num_proc()``, this does NOT cap to 1 on macOS/Windows.
-    Threads share the parent process address space and are unaffected by
-    the ``spawn`` vs ``fork`` distinction.
+    Unlike ``safe_num_proc()``, does NOT cap to 1 on macOS/Windows: threads
+    share the parent address space, unaffected by ``spawn`` vs ``fork``.
 
     Args:
         desired: The thread count you *want*. If None, auto-computes
@@ -2010,9 +1990,9 @@ def dataset_map_num_proc(desired: Optional[int] = None) -> Optional[int]:
     """
     Return a safe ``num_proc`` for ``Dataset.map()`` and ``Dataset.filter()``.
 
-    Returns ``None`` on spawn-based platforms (Windows, macOS) because
-    ``datasets`` treats ``num_proc=1`` as multiprocessing (creates ``Pool(1)``).
-    Only ``num_proc=None`` guarantees in-process execution.
+    Returns ``None`` on spawn platforms (Windows, macOS) because ``datasets``
+    treats ``num_proc=1`` as multiprocessing (creates ``Pool(1)``); only
+    ``num_proc=None`` guarantees in-process execution.
     """
     if sys.platform in ("win32", "darwin"):
         return None
diff --git a/studio/backend/utils/hardware/nvidia.py b/studio/backend/utils/hardware/nvidia.py
index 6cead61f08..b8f307df9e 100644
--- a/studio/backend/utils/hardware/nvidia.py
+++ b/studio/backend/utils/hardware/nvidia.py
@@ -110,9 +110,9 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 def get_visible_gpu_utilization(
     parent_visible_ids: Optional[list[int]], parent_cuda_visible_devices: Optional[str] = None
 ) -> dict[str, Any]:
-    # When parent_visible_ids is None (UUID/MIG mask), we cannot safely
-    # map nvidia-smi rows to the process's visible devices. Return empty
-    # instead of exposing all physical GPUs.
+    # parent_visible_ids None (UUID/MIG mask): can't safely map
+    # nvidia-smi rows to visible devices. Return empty rather than
+    # exposing all physical GPUs.
     if parent_visible_ids is None:
         return {
             "available": False,
@@ -196,8 +196,8 @@ def get_visible_gpu_utilization(
 def get_backend_visible_gpu_info(
     parent_visible_ids: Optional[list[int]], backend_cuda_visible_devices: Optional[str]
 ) -> dict[str, Any]:
-    # When parent_visible_ids is None (UUID/MIG mask), we cannot safely
-    # map nvidia-smi rows to the process's visible devices.
+    # parent_visible_ids None (UUID/MIG mask): can't safely map
+    # nvidia-smi rows to visible devices.
     if parent_visible_ids is None:
         return {
             "available": False,
@@ -249,7 +249,7 @@ def get_backend_visible_gpu_info(
             continue
         if visible_ordinals is not None and idx not in visible_ordinals:
             continue
-        # Use split with limit to handle GPU names containing commas
+        # Rejoin in case the GPU name contains commas
         name = parts[1] if len(parts) == 3 else ", ".join(parts[1:-1])
         try:
             mem_total_mb = int(parts[-1])
diff --git a/studio/backend/utils/hardware/vram_estimation.py b/studio/backend/utils/hardware/vram_estimation.py
index ddc39733e3..51903e0c97 100644
--- a/studio/backend/utils/hardware/vram_estimation.py
+++ b/studio/backend/utils/hardware/vram_estimation.py
@@ -59,8 +59,8 @@ OPTIMIZER_BYTES_PER_PARAM: Dict[str, int] = {
 }
 
 # (full_ft_multiplier, lora_multiplier) — fraction of num_layers.
-# LoRA: frozen base layers skip activation storage, but you always need
-# at least ~1 layer in flight during backprop recomputation.
+# LoRA: frozen base layers skip activation storage, but ~1 layer is always
+# in flight during backprop recomputation.
 GC_LAYER_MULTIPLIERS = {
     "none": (None, None),
     "true": (2.0, 1.0),
@@ -125,8 +125,7 @@ class VramBreakdown:
     gradients: int
     activations: int
     cuda_overhead: int
-    # Equals `activations`; retained for backward compatibility with
-    # consumers that read this field.
+    # Equals `activations`; kept for backward compat with field consumers.
     activations_computed: int = 0
 
     @property
@@ -141,10 +140,10 @@ class VramBreakdown:
         )
 
     def min_gpu_vram(self, n_gpus: int) -> int:
-        """Minimum VRAM a single GPU needs: its shard + non-shardable costs.
+        """Min VRAM one GPU needs: its shard + non-shardable costs.
 
-        Weights/LoRA/optimizer/gradients shard across GPUs.
-        Activations do NOT shard (the GPU running a layer holds them).
+        Weights/LoRA/optimizer/gradients shard across GPUs; activations do
+        NOT (the GPU running a layer holds them).
         """
         shardable = self.model_weights + self.lora_adapters + self.optimizer_states + self.gradients
         per_gpu_fixed = self.activations + self.cuda_overhead
@@ -163,7 +162,7 @@ class VramBreakdown:
 
 
 def _first_scalar(value):
-    # why: ERNIE MoE configs ship moe_intermediate_size / moe_num_experts as
+    # ERNIE MoE ships moe_intermediate_size / moe_num_experts as
     # [routed, shared] lists; downstream arithmetic needs the routed scalar.
     if isinstance(value, (list, tuple)):
         return value[0] if value else None
@@ -171,8 +170,8 @@ def _first_scalar(value):
 
 
 def _max_scalar(value):
-    # why: Hunyuan-V1-MoE moe_topk can be a per-layer list; activation
-    # accounting uses the max top-k as a conservative upper bound.
+    # Hunyuan-V1-MoE moe_topk can be a per-layer list; activation accounting
+    # uses max top-k as a conservative upper bound.
     if isinstance(value, (list, tuple)):
         items = [v for v in value if v is not None]
         return max(items) if items else None
@@ -181,8 +180,8 @@ def _max_scalar(value):
 
 def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
     """Layer indices that use dense MLP instead of MoE. Position matters."""
-    # why: transformers Exaone-MoE / Laguna / Hy_v3 / GLM-MoE-DSA / GLM4-MoE-Lite /
-    # Ernie4_5_VL_MoE prefer per-position `mlp_layer_types` over the prefix-style
+    # Exaone-MoE / Laguna / Hy_v3 / GLM-MoE-DSA / GLM4-MoE-Lite / Ernie4_5_VL_MoE
+    # prefer per-position `mlp_layer_types` over prefix-style
     # `first_k_dense_replace` and may omit `decoder_sparse_step` entirely.
     layer_types = getattr(text_config, "mlp_layer_types", None)
     if layer_types:
@@ -190,7 +189,7 @@ def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
             i for i, t in enumerate(layer_types[:total_layers]) if str(t).lower() == "dense"
         )
 
-    # why: Llama4TextConfig.__init__ auto-populates self.moe_layers from
+    # Llama4TextConfig.__init__ auto-populates self.moe_layers from
     # interleave_moe_layer_step; Llama4TextDecoderLayer dispatches via
     # `layer_idx in config.moe_layers` (modeling_llama4.py).
     llama4_moe_layers = getattr(text_config, "moe_layers", None)
@@ -198,9 +197,9 @@ def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
         moe_indices = {int(i) for i in llama4_moe_layers}
         return tuple(i for i in range(total_layers) if i not in moe_indices)
 
-    # why: transformers ERNIE 4.5 MoE / ERNIE 4.5 VL MoE declare MoE layers
-    # via moe_layer_start_index / moe_layer_end_index / moe_layer_interval;
-    # the model's per-layer guard is `(layer_idx + 1) % interval == 0` with
+    # ERNIE 4.5 MoE / ERNIE 4.5 VL MoE declare MoE layers via
+    # moe_layer_start_index / moe_layer_end_index / moe_layer_interval; the
+    # per-layer guard is `(layer_idx + 1) % interval == 0` with
     # start <= layer_idx <= end (modeling_ernie4_5_moe.py).
     moe_start = getattr(text_config, "moe_layer_start_index", None)
     moe_interval = getattr(text_config, "moe_layer_interval", None)
@@ -261,8 +260,8 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
 
     num_kv_heads = getattr(text_config, "num_key_value_heads", num_heads)
 
-    # why: DBRX places its MoE attrs on the DbrxFFNConfig sub-config; probe
-    # ffn_config as a secondary source so DBRX is not misclassified as dense.
+    # DBRX places its MoE attrs on the DbrxFFNConfig sub-config; probe
+    # ffn_config as a secondary source so DBRX isn't misclassified as dense.
     ffn_config = getattr(text_config, "ffn_config", None)
 
     def _moe_attr(name):
@@ -286,8 +285,8 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
     if moe_intermediate_raw is None:
         moe_intermediate_raw = _moe_attr("ffn_hidden_size")
     moe_intermediate = _first_scalar(moe_intermediate_raw)
-    # why: Exaone-MoE / ERNIE families alias num_shared_experts /
-    # moe_num_shared_experts to the canonical n_shared_experts.
+    # Exaone-MoE / ERNIE alias num_shared_experts / moe_num_shared_experts
+    # to the canonical n_shared_experts.
     n_shared_experts = (
         _first_scalar(_moe_attr("n_shared_experts"))
         or _first_scalar(_moe_attr("num_shared_experts"))
@@ -297,9 +296,9 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
     shared_expert_intermediate_size = _moe_attr("shared_expert_intermediate_size")
     if shared_expert_intermediate_size and n_shared_experts == 0:
         n_shared_experts = 1
-    # why: DBRX exposes moe_top_k, Hunyuan-V1-MoE exposes moe_topk (which can
-    # be a per-layer list); _max_scalar normalizes list values to the worst
-    # case so int(...) below cannot crash on the canonical attribute_map path.
+    # DBRX exposes moe_top_k; Hunyuan-V1-MoE exposes moe_topk (can be a
+    # per-layer list). _max_scalar normalizes lists to the worst case so
+    # int(...) below cannot crash on the canonical attribute_map path.
     num_experts_per_tok = (
         _max_scalar(_moe_attr("num_experts_per_tok"))
         or _max_scalar(_moe_attr("top_k_experts"))
@@ -313,9 +312,9 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
         dense_layer_indices = _compute_dense_layer_indices(text_config, num_layers)
     num_dense_layers = len(dense_layer_indices)
 
-    # why: Llama4 dense layers use intermediate_size_mlp; routed and shared
-    # experts use intermediate_size. Llama4TextMoe builds one shared_expert
-    # per MoE layer (modeling_llama4.py).
+    # Llama4 dense layers use intermediate_size_mlp; routed/shared experts use
+    # intermediate_size. Llama4TextMoe builds one shared_expert per MoE layer
+    # (modeling_llama4.py).
     intermediate_size_mlp_raw = _first_scalar(_moe_attr("intermediate_size_mlp"))
     dense_intermediate_size = (
         int(intermediate_size_mlp_raw) if intermediate_size_mlp_raw is not None else None
@@ -386,8 +385,8 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
 
 
 def _targets_all_linear(target_modules) -> bool:
-    # why: peft LoraConfig accepts target_modules="all-linear" as a bare
-    # string; iterating a string yields chars and never matches the set.
+    # peft LoraConfig accepts target_modules="all-linear" as a bare string;
+    # iterating a string yields chars and never matches the set.
     if isinstance(target_modules, str):
         target_modules = [target_modules]
     normalized = {str(module).lower().replace("_", "-") for module in target_modules}
@@ -425,10 +424,9 @@ def _is_kv_shared_layer(arch: ModelArchConfig, layer_idx: int) -> bool:
     if arch.num_kv_shared_layers <= 0:
         return False
     first_shared = arch.num_hidden_layers - arch.num_kv_shared_layers
-    # why: transformers Gemma4 (modeling_gemma4.py:1031, modular_gemma4.py:863)
-    # uses the same `> 0` guard so a fully-shared config raises during model
-    # construction; matching upstream avoids producing a detailed estimate
-    # for a shape the actual model code rejects.
+    # Gemma4 (modeling_gemma4.py:1031, modular_gemma4.py:863) uses the same
+    # `> 0` guard so a fully-shared config raises at model construction;
+    # matching upstream avoids estimating a shape the model code rejects.
     return layer_idx >= first_shared > 0
 
 
@@ -439,9 +437,9 @@ def _is_dense_mlp_layer(arch: ModelArchConfig, layer_idx: int) -> bool:
 
 
 def _per_layer_input_quantizable(arch: ModelArchConfig) -> int:
-    # why: Gemma4 PLE block adds per_layer_model_projection (single Linear),
+    # Gemma4 PLE block adds per_layer_model_projection (single Linear),
     # per_layer_input_gate (per layer), and per_layer_projection (per layer);
-    # see transformers gemma4/modular_gemma4.py:1077-1083 and :1247-1253.
+    # see gemma4/modular_gemma4.py:1077-1083 and :1247-1253.
     pli = arch.hidden_size_per_layer_input
     if pli <= 0:
         return 0
@@ -460,10 +458,10 @@ def _per_layer_input_norm_elements(arch: ModelArchConfig) -> int:
 
 
 def _per_layer_input_lora_params(arch: ModelArchConfig, r: int, target_modules) -> int:
-    # why: Unsloth's get_peft_regex (unsloth_zoo/peft_utils.py) requires module
-    # names to contain a component tag (mlp/attn/...); PLE module names lack
-    # any tag, so all-linear training does NOT attach LoRA to them. Only count
-    # PLE LoRA when the user explicitly names PLE modules.
+    # Unsloth's get_peft_regex (unsloth_zoo/peft_utils.py) requires module
+    # names to contain a component tag (mlp/attn/...); PLE names lack any tag,
+    # so all-linear does NOT attach LoRA to them. Only count PLE LoRA when the
+    # user explicitly names PLE modules.
     pli = arch.hidden_size_per_layer_input
     if pli <= 0:
         return 0
@@ -543,17 +541,17 @@ def _module_path_matches(skip_module: str, alias: str) -> bool:
     if alias_parts[0] == "layers":
         return skip_parts == alias_parts
     if len(skip_parts) <= len(alias_parts):
-        # why: transformers BNB quantizer suffix-matches short skip entries
-        # like ["q_proj"] / ["lm_head"] against full module paths, so a skip
-        # shorter than the alias is a tail match.
+        # BNB quantizer suffix-matches short skip entries like ["q_proj"] /
+        # ["lm_head"] against full paths, so a skip shorter than the alias is
+        # a tail match.
         return alias_parts[-len(skip_parts) :] == skip_parts
     if skip_parts[-len(alias_parts) :] != alias_parts:
         return False
     prefix_parts = skip_parts[: len(skip_parts) - len(alias_parts)]
     if not prefix_parts:
         return True
-    # why: bound the prefix to known text-tower roots so VLM skip names like
-    # vision_tower.model.layers.<i>.self_attn.q_proj do not shadow the text
+    # Bound the prefix to known text-tower roots so VLM skip names like
+    # vision_tower.model.layers.<i>.self_attn.q_proj don't shadow the text
     # alias model.layers.<i>.self_attn.q_proj.
     return ".".join(prefix_parts) in _SKIP_MODULE_TEXT_PREFIXES
 
@@ -587,9 +585,9 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
         mlp_dims = {name: dim for name, dim in dims.items() if name in MLP_TARGET_MODULES}
 
         if is_mla:
-            # why: _text_linear_dims uses (hd, hd) for q/o; MLA actually splits
-            # into q_a/q_b/kv_a/kv_b, so emit a single self_attn aggregate at
-            # the authoritative MLA per-layer total.
+            # _text_linear_dims uses (hd, hd) for q/o; MLA splits into
+            # q_a/q_b/kv_a/kv_b, so emit a single self_attn aggregate at the
+            # authoritative MLA per-layer total.
             layer_modules["self_attn"] = _compute_attn_elements(arch)
         else:
             for name, (in_dim, out_dim) in attn_dims.items():
@@ -607,17 +605,17 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
                 layer_modules["mlp.experts"] = _compute_routed_moe_elements(arch)
                 shared_moe = _compute_shared_moe_elements(arch)
                 if shared_moe:
-                    # why: Qwen3.5-MoE exposes shared expert as
-                    # mlp.shared_expert; Exaone-MoE/Laguna/GLM-style configs use
-                    # mlp.shared_experts. Register both names so child-path
-                    # llm_int8_skip_modules entries match the right shared block.
+                    # Qwen3.5-MoE exposes shared expert as mlp.shared_expert;
+                    # Exaone-MoE/Laguna/GLM-style use mlp.shared_experts.
+                    # Register both names so child-path llm_int8_skip_modules
+                    # entries match the right shared block.
                     layer_modules["mlp.shared_expert"] = shared_moe
                 if arch.moe_has_dense_mlp:
-                    # why: enable_moe_block runs the dense MLP and the MoE
-                    # experts in parallel; register both for skip matching.
-                    # Non-structured _text_linear_dims returns mlp_size from
-                    # _get_mlp_size which prefers moe_intermediate_size, so
-                    # rebuild dense dims from arch.intermediate_size directly.
+                    # enable_moe_block runs the dense MLP and MoE experts in
+                    # parallel; register both for skip matching. Non-structured
+                    # _text_linear_dims returns mlp_size from _get_mlp_size
+                    # (prefers moe_intermediate_size), so rebuild dense dims
+                    # from arch.intermediate_size directly.
                     if _uses_structured_layer_shapes(arch):
                         dense_dims = mlp_dims
                     else:
@@ -640,8 +638,8 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
             )
 
         if pli > 0:
-            # why: register PLE per-layer linears so llm_int8_skip_modules
-            # entries like model.layers.0.per_layer_input_gate match.
+            # Register PLE per-layer linears so llm_int8_skip_modules entries
+            # like model.layers.0.per_layer_input_gate match.
             layer_modules["per_layer_input_gate"] = hd_global * pli
             layer_modules["per_layer_projection"] = pli * hd_global
 
@@ -650,10 +648,10 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
             for name, value in layer_modules.items()
             if name == "self_attn" or name.startswith("self_attn.")
         )
-        # why: gemma4 enable_moe_block puts routed experts at the sibling
+        # gemma4 enable_moe_block puts routed experts at the sibling
         # layers.<i>.experts attribute, not under self.mlp; the layer's "mlp"
         # aggregate must reflect only the dense MLP path so a skip module
-        # `model.layers.0.mlp` does not over-skip into the experts block.
+        # `model.layers.0.mlp` doesn't over-skip into the experts block.
         is_sibling_experts = bool(arch.moe_has_dense_mlp)
         mlp_total = sum(
             value
@@ -683,11 +681,11 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
             elements[canonical] = value
             _add_module_aliases(aliases, canonical, canonical.removeprefix("text."))
             if name == "mlp.experts" and arch.moe_has_dense_mlp:
-                # why: gemma4 enable_moe_block exposes routed experts at
+                # gemma4 enable_moe_block exposes routed experts at
                 # layers.<i>.experts (sibling of self.mlp), not under mlp.
                 _add_module_aliases(aliases, canonical, f"layers.{layer_idx}.experts")
             elif name == "mlp.shared_expert":
-                # why: Exaone-MoE / Laguna / GLM-style configs use the plural
+                # Exaone-MoE / Laguna / GLM-style use the plural
                 # `shared_experts` attribute name; register both spellings.
                 _add_module_aliases(
                     aliases,
@@ -733,8 +731,8 @@ def _get_mlp_size(arch: ModelArchConfig) -> int:
 
 
 def _dense_mlp_size(arch: ModelArchConfig) -> int:
-    # why: Llama4 dense layers use intermediate_size_mlp; routed/shared
-    # experts use intermediate_size. Other configs leave the field None.
+    # Llama4 dense layers use intermediate_size_mlp; routed/shared experts use
+    # intermediate_size. Other configs leave the field None.
     return arch.dense_intermediate_size or arch.intermediate_size
 
 
@@ -764,7 +762,7 @@ def _compute_dense_mlp_elements(arch: ModelArchConfig) -> int:
 
 
 def _shared_expert_size(arch: ModelArchConfig) -> int:
-    # why: Qwen3.5-MoE shared expert has its own intermediate_size (default 512)
+    # Qwen3.5-MoE shared expert has its own intermediate_size (default 512)
     # distinct from moe_intermediate_size; fall back to routed mlp_size for
     # families that share it (deepseek-style configs).
     return arch.shared_expert_intermediate_size or _get_mlp_size(arch)
@@ -782,10 +780,10 @@ def _compute_shared_moe_elements(arch: ModelArchConfig) -> int:
     hd = arch.hidden_size
     shared_size = _shared_expert_size(arch)
     total = hd * shared_size * 3 * arch.n_shared_experts
-    # why: only Qwen2-MoE / Qwen3.5-MoE define a shared_expert_gate Linear
-    # (hidden_size→1); other families (Exaone-MoE, HY-V3, GLM4-MoE-Lite, Laguna)
-    # have shared_experts without a gate. shared_expert_intermediate_size is the
-    # Qwen-style discriminator.
+    # Only Qwen2-MoE / Qwen3.5-MoE define a shared_expert_gate Linear
+    # (hidden_size->1); other families (Exaone-MoE, HY-V3, GLM4-MoE-Lite,
+    # Laguna) have shared_experts without a gate.
+    # shared_expert_intermediate_size is the Qwen-style discriminator.
     if arch.shared_expert_intermediate_size:
         total += arch.n_shared_experts * hd
     return total
@@ -824,8 +822,8 @@ def _compute_layer_elements(arch: ModelArchConfig):
             n_moe = n_layers - n_dense
             moe_mlp_total = _compute_moe_mlp_elements(arch) * n_moe
             if arch.moe_has_dense_mlp:
-                # why: enable_moe_block runs dense MLP and MoE experts in
-                # parallel; count dense for every layer alongside MoE.
+                # enable_moe_block runs dense MLP and MoE experts in parallel;
+                # count dense for every layer alongside MoE.
                 mlp_total = sum(per_layer_dense_mlp) + moe_mlp_total
             else:
                 dense_only_total = sum(
@@ -958,11 +956,10 @@ def compute_lora_params(arch: ModelArchConfig, lora_rank: int, target_modules: l
         if n_experts > 1:
             n_dense = arch.num_dense_layers
             n_moe = n_layers - n_dense
-            # why: peft "all-linear" attaches LoRA to nn.Linear only;
-            # routed experts are nn.Parameter and need explicit
-            # gate_proj/up_proj/down_proj naming via Unsloth's
-            # get_moe_target_parameters. Shared experts are nn.Linear and
-            # are picked up by get_peft_regex.
+            # peft "all-linear" attaches LoRA to nn.Linear only; routed experts
+            # are nn.Parameter and need explicit gate_proj/up_proj/down_proj
+            # naming via Unsloth's get_moe_target_parameters. Shared experts are
+            # nn.Linear, picked up by get_peft_regex.
             routed_moe = (
                 0
                 if all_linear
@@ -983,7 +980,7 @@ def compute_lora_params(arch: ModelArchConfig, lora_rank: int, target_modules: l
             )
             moe_mlp = routed_moe + shared_moe
             if arch.moe_has_dense_mlp:
-                # why: parallel dense MLP coexists with MoE on every layer.
+                # Parallel dense MLP coexists with MoE on every layer.
                 mlp_total = structured_dense_mlp + moe_mlp * n_moe
             else:
                 dense_only = sum(
@@ -999,7 +996,7 @@ def compute_lora_params(arch: ModelArchConfig, lora_rank: int, target_modules: l
         attn_total = _lora_attn_elements(arch, r, selected_modules) * n_layers
         n_dense = arch.num_dense_layers
         n_moe = n_layers - n_dense
-        # why: routed and shared experts may use different intermediate sizes
+        # Routed and shared experts may use different intermediate sizes
         # (Qwen3.5-MoE: routed mlp_size != shared_expert_intermediate_size).
         # See structured branch for the all-linear exclusion rationale; only
         # routed (nn.Parameter) experts are excluded under all-linear.
@@ -1064,7 +1061,7 @@ def compute_gradient_bytes(trainable_params: int) -> int:
 
 
 def _is_linear_attention(attention_implementation: Optional[str]) -> bool:
-    # why: PyTorch SDPA dispatches to flash/memory-efficient O(n) backends; only
+    # PyTorch SDPA dispatches to flash/memory-efficient O(n) backends; only
     # eager (and other non-flash impls) need the quadratic correction.
     return attention_implementation in LINEAR_ATTENTION_IMPLS
 
@@ -1081,16 +1078,16 @@ def _layer_qkv_mlp_sizes(arch: ModelArchConfig, layer_idx: int) -> tuple:
     is_moe_layer = n_experts > 1 and not _is_dense_mlp_layer(arch, layer_idx)
     if _uses_structured_layer_shapes(arch):
         q_size, kv_size, _has_k, _has_v = _layer_attention_dims(arch, layer_idx)
-        # why: KV-shared layers (Gemma4/Gemma3n) drop k_proj/v_proj WEIGHTS but
-        # the donor layer's K/V tensors stay alive across the shared range, so
-        # activation memory still pays for kv_size; only the weight path uses
+        # KV-shared layers (Gemma4/Gemma3n) drop k_proj/v_proj WEIGHTS but the
+        # donor layer's K/V tensors stay alive across the shared range, so
+        # activation memory still pays kv_size; only the weight path uses
         # has_k/has_v.
         layer_type = _layer_types(arch)[layer_idx]
         use_alt_attention = arch.attention_k_eq_v and layer_type != "sliding_attention"
         kv_count = 1 if use_alt_attention else 2
         qkv_size = q_size + kv_size * kv_count
         if is_moe_layer:
-            # why: each token routes through `num_experts_per_tok` experts; their
+            # Each token routes through `num_experts_per_tok` experts; their
             # gate/up/down intermediates are all live during MLP forward.
             mlp_size = _get_mlp_size(arch) * arch.num_experts_per_tok
             if arch.n_shared_experts:
@@ -1119,9 +1116,9 @@ def _per_layer_activation_bytes(
     activation_qkv = seq_len * batch_size * qkv_size
     residual_memory = (seq_len * batch_size) * 2
     activation_mlp = seq_len * batch_size * (mlp_size + mlp_size)
-    # why: per_layer_input_gate (hd-sized) and per_layer_projection (pli-sized)
-    # outputs materialize once per decoder layer when hidden_size_per_layer_input
-    # is set; see gemma4/modular_gemma4.py:1141-1145.
+    # per_layer_input_gate (hd-sized) and per_layer_projection (pli-sized)
+    # outputs materialize once per decoder layer when
+    # hidden_size_per_layer_input is set; see gemma4/modular_gemma4.py:1141-1145.
     pli = arch.hidden_size_per_layer_input
     activation_ple = seq_len * batch_size * (arch.hidden_size + pli) if pli > 0 else 0
     return int((activation_qkv + residual_memory + activation_mlp + activation_ple) * 2 * 1.25)
@@ -1154,8 +1151,8 @@ def compute_activation_bytes(
         )
         linear_bytes = int(max_layer_bytes * effective_layers)
 
-    # why: gemma4 per_layer_model_projection runs once outside the per-decoder
-    # loop and materializes a [B, S, L, PLI] tensor; see modular_gemma4.py:1247.
+    # gemma4 per_layer_model_projection runs once outside the per-decoder loop
+    # and materializes a [B, S, L, PLI] tensor; see modular_gemma4.py:1247.
     pli = arch.hidden_size_per_layer_input
     if pli > 0:
         linear_bytes += int(seq_len * batch_size * n_layers * pli * 2 * 1.25)
diff --git a/studio/backend/utils/inference/inference_config.py b/studio/backend/utils/inference/inference_config.py
index e07bc62cfd..87e2aac833 100644
--- a/studio/backend/utils/inference/inference_config.py
+++ b/studio/backend/utils/inference/inference_config.py
@@ -4,9 +4,9 @@
 """
 Inference configuration loading utilities.
 
-This module provides functions to load inference parameters (temperature, top_p, top_k, min_p)
-from model YAML configuration files, with fallback to default.yaml.
-Includes family-based lookup from inference_defaults.json for GGUF models.
+Loads inference parameters (temperature, top_p, top_k, min_p) from model YAML
+configs, falling back to default.yaml. Includes family-based lookup from
+inference_defaults.json for GGUF models.
 """
 
 from pathlib import Path
@@ -51,8 +51,8 @@ def get_family_inference_params(model_id: str) -> Dict[str, Any]:
     """
     Look up recommended inference parameters by model family.
 
-    Extracts the model family from the identifier (e.g. "unsloth/Qwen3.5-9B-GGUF" -> "qwen3.5")
-    and returns the matching parameters from inference_defaults.json.
+    Extracts the family from the identifier (e.g. "unsloth/Qwen3.5-9B-GGUF" ->
+    "qwen3.5") and returns the matching params from inference_defaults.json.
 
     Args:
         model_id: Model identifier (e.g. "unsloth/Qwen3.5-9B-GGUF")
@@ -65,12 +65,12 @@ def get_family_inference_params(model_id: str) -> Dict[str, Any]:
     if not _FAMILY_PATTERNS or not _FAMILY_DEFAULTS:
         return {}
 
-    # Normalize: lowercase, strip org prefix
+    # Normalize: lowercase, strip org prefix.
     normalized = model_id.lower()
     if "/" in normalized:
         normalized = normalized.split("/", 1)[1]
 
-    # Match against patterns (ordered longest-match-first in the JSON)
+    # Match patterns (ordered longest-match-first in the JSON).
     for pattern in _FAMILY_PATTERNS:
         if pattern in normalized:
             params = _FAMILY_DEFAULTS.get(pattern, {})
@@ -87,14 +87,13 @@ def _has_specific_yaml(model_identifier: str) -> bool:
     script_dir = Path(__file__).parent.parent.parent
     defaults_dir = script_dir / "assets" / "configs" / "model_defaults"
 
-    # Check the mapping
+    # Check the mapping.
     if model_identifier.lower() in _REVERSE_MODEL_MAPPING:
         return True
 
-    # For local filesystem paths (e.g. C:\Users\...\model on Windows),
-    # normalize backslashes so Path().parts splits correctly on POSIX/WSL,
-    # then try matching the last 1-2 path components against the registry
-    # (mirrors the logic in load_model_defaults).
+    # For local paths (e.g. C:\Users\...\model on Windows), normalize backslashes
+    # so Path().parts splits correctly on POSIX/WSL, then match the last 1-2 path
+    # components against the registry (mirrors load_model_defaults).
     _is_local = is_local_path(model_identifier)
     _normalized = normalize_path(model_identifier) if _is_local else model_identifier
 
@@ -109,9 +108,8 @@ def _has_specific_yaml(model_identifier: str) -> bool:
     else:
         _lookup = model_identifier
 
-    # Check for exact filename match (basename for local paths to avoid
-    # passing absolute paths into rglob which raises
-    # "Non-relative patterns are unsupported" on Windows).
+    # Exact filename match (basename for local paths; passing absolute paths to
+    # rglob raises "Non-relative patterns are unsupported" on Windows).
     model_filename = _lookup.replace("/", "_") + ".yaml"
     for config_path in defaults_dir.rglob(model_filename):
         if config_path.is_file():
@@ -125,15 +123,15 @@ def load_inference_config(model_identifier: str) -> Dict[str, Any]:
     Load inference configuration parameters for a model.
 
     Priority chain:
-    1. Model-specific YAML (if it exists and has inference params)
-    2. Family-based defaults from inference_defaults.json
-    3. default.yaml fallback
+    1. Model-specific YAML (if it exists and has inference params).
+    2. Family-based defaults from inference_defaults.json.
+    3. default.yaml fallback.
 
     Args:
         model_identifier: Model identifier (e.g., "unsloth/llama-3-8b-bnb-4bit")
 
     Returns:
-        Dictionary containing inference parameters:
+        Dict of inference parameters:
         {
             "temperature": float,
             "top_p": float,
@@ -141,10 +139,10 @@ def load_inference_config(model_identifier: str) -> Dict[str, Any]:
             "min_p": float
         }
     """
-    # Load model defaults to get inference parameters
+    # Model defaults for inference parameters.
     model_defaults = load_model_defaults(model_identifier)
 
-    # Load default.yaml for fallback values
+    # default.yaml for fallback values.
     script_dir = Path(__file__).parent.parent.parent
     defaults_dir = script_dir / "assets" / "configs" / "model_defaults"
     default_config_path = defaults_dir / "default.yaml"
@@ -158,18 +156,18 @@ def load_inference_config(model_identifier: str) -> Dict[str, Any]:
         except Exception as e:
             logger.warning(f"Failed to load default.yaml: {e}")
 
-    # Family-based defaults from inference_defaults.json
+    # Family-based defaults from inference_defaults.json.
     family_params = get_family_inference_params(model_identifier)
 
     model_inference = model_defaults.get("inference", {})
 
-    # If the model has its own YAML config, those values take priority over family defaults.
-    # If it only fell back to default.yaml, family defaults take priority.
+    # Model's own YAML beats family defaults; if it only fell back to
+    # default.yaml, family defaults win.
     has_own_yaml = _has_specific_yaml(model_identifier)
 
     def _get_param(key, hardcoded_default):
         if has_own_yaml:
-            # Model-specific YAML wins, then family fills gaps, then default.yaml
+            # Model-specific YAML wins, then family fills gaps, then default.yaml.
             val = model_inference.get(key)
             if val is not None and isinstance(val, (int, float)):
                 return val
@@ -177,7 +175,7 @@ def load_inference_config(model_identifier: str) -> Dict[str, Any]:
                 return family_params[key]
             return default_inference.get(key, hardcoded_default)
         else:
-            # No model-specific YAML: family wins, then default.yaml
+            # No model-specific YAML: family wins, then default.yaml.
             if key in family_params:
                 return family_params[key]
             return default_inference.get(key, hardcoded_default)
diff --git a/studio/backend/utils/llama_cpp_freshness.py b/studio/backend/utils/llama_cpp_freshness.py
index f0e642a38e..3635969c73 100644
--- a/studio/backend/utils/llama_cpp_freshness.py
+++ b/studio/backend/utils/llama_cpp_freshness.py
@@ -45,7 +45,7 @@ def _cache_dir() -> Path:
 
 def read_install_marker(binary_path: Optional[str]) -> Optional[dict]:
     """Walk up from binary_path to find UNSLOTH_PREBUILT_INFO.json.
-    None means no marker (source build / custom path) or invalid JSON."""
+    None = no marker (source build / custom path) or invalid JSON."""
     if not binary_path:
         return None
     cached = _marker_cache.get(binary_path)
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index 99770ce7a6..80312af0f7 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Checkpoint scanning utilities for discovering training runs and their checkpoints.
-"""
+"""Checkpoint scanning utilities for discovering training runs and checkpoints."""
 
 import json
 import structlog
@@ -17,7 +15,7 @@ logger = get_logger(__name__)
 
 def _read_checkpoint_loss(checkpoint_path: Path) -> Optional[float]:
     """
-    Read the training loss from a checkpoint's trainer_state.json.
+    Read training loss from a checkpoint's trainer_state.json.
 
     Returns the loss from the last log_history entry, or None if unavailable.
     """
@@ -91,8 +89,8 @@ def scan_checkpoints(
             except Exception:
                 pass
 
-            # Fallback: extract base model name from folder name
-            # e.g. "unsloth_Llama-3.2-3B-Instruct_1771227800" → "unsloth/Llama-3.2-3B-Instruct"
+            # Fallback: extract base model name from the folder name, e.g.
+            # "unsloth_Llama-3.2-3B-Instruct_1771227800" → "unsloth/Llama-3.2-3B-Instruct"
             if not metadata.get("base_model"):
                 parts = item.name.rsplit("_", 1)
                 if len(parts) == 2 and parts[1].isdigit():
@@ -103,13 +101,13 @@ def scan_checkpoints(
                     else:
                         metadata["base_model"] = name_part
 
-            # This is a valid training run
+            # Valid training run.
             checkpoints = []
 
-            # Placeholder for the main adapter — loss filled from last checkpoint below
+            # Main adapter placeholder — loss filled from the last checkpoint below.
             checkpoints.append((item.name, str(item), None))
 
-            # Scan for intermediate checkpoints (checkpoint-N subdirs)
+            # Scan for intermediate checkpoints (checkpoint-N subdirs).
             for sub in sorted(item.iterdir()):
                 if not sub.is_dir() or not sub.name.startswith("checkpoint-"):
                     continue
@@ -119,7 +117,7 @@ def scan_checkpoints(
                     loss = _read_checkpoint_loss(sub)
                     checkpoints.append((sub.name, str(sub), loss))
 
-            # Assign the last checkpoint's loss to the main adapter entry
+            # Assign the last checkpoint's loss to the main adapter entry.
             if len(checkpoints) > 1:
                 last_checkpoint_loss = checkpoints[-1][2]
                 checkpoints[0] = (
diff --git a/studio/backend/utils/models/gguf_metadata.py b/studio/backend/utils/models/gguf_metadata.py
index 32618773b7..a2912cc843 100644
--- a/studio/backend/utils/models/gguf_metadata.py
+++ b/studio/backend/utils/models/gguf_metadata.py
@@ -1,10 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Free-function ``general.*`` reader for GGUF headers, used by
-``detect_mmproj_file`` to pair weights and projectors via
-``general.base_model.0.repo_url``. ~30 ms per file, cached by
-(path, mtime, size)."""
+"""``general.*`` reader for GGUF headers, used by ``detect_mmproj_file`` to
+pair weights and projectors via ``general.base_model.0.repo_url``. ~30 ms
+per file, cached by (path, mtime, size)."""
 
 from __future__ import annotations
 
@@ -65,9 +64,9 @@ def _cache_key(path: str) -> Optional[_CacheKey]:
 
 
 def read_gguf_general_metadata(path: str) -> Optional[Dict[str, str]]:
-    """Return ``general.*`` strings from a GGUF header, or ``None`` if
-    the file is missing, unreadable, or not a GGUF. ``{}`` means the
-    file is valid but carries none of the wanted keys."""
+    """Return ``general.*`` strings from a GGUF header, or ``None`` if the
+    file is missing, unreadable, or not a GGUF. ``{}`` means valid but
+    carrying none of the wanted keys."""
     key = _cache_key(path)
     if key is None:
         return None
@@ -156,9 +155,9 @@ _FIXED_VTYPE_SIZES: Dict[int, int] = {
 
 
 def _skip_gguf_value(f, vtype: int) -> bool:
-    """Advance past one GGUF value. ``f.seek(.., 1)`` past EOF is legal
-    on a regular file so truncation is detected on the next read; we
-    only return False for unknown types or sanity-bound overflow."""
+    """Advance past one GGUF value. ``f.seek(.., 1)`` past EOF is legal on a
+    regular file, so truncation is caught on the next read; return False only
+    for unknown types or sanity-bound overflow."""
     if vtype == 8:  # STRING
         slen_bytes = f.read(8)
         if len(slen_bytes) < 8:
@@ -265,9 +264,9 @@ def _read_gguf_bool(path: str, wanted_key: str) -> Optional[bool]:
 
 
 def read_mmproj_audio_capability(path: str) -> Optional[bool]:
-    """``clip.has_audio_encoder`` from an mmproj GGUF (e.g. Gemma 4's gemma4ua):
-    ``True``/``False`` if present, ``None`` if absent / unreadable. Flags
-    audio-input models independently of tokenizer token names."""
+    """``clip.has_audio_encoder`` from an mmproj GGUF (e.g. Gemma 4's
+    gemma4ua): ``True``/``False`` if present, ``None`` if absent/unreadable.
+    Flags audio-input models independently of tokenizer token names."""
     return _read_gguf_bool(path, "clip.has_audio_encoder")
 
 
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 2947bab3d3..abddd07367 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Model and LoRA configuration handling
-"""
+"""Model and LoRA configuration handling."""
 
 from dataclasses import dataclass
 from typing import Optional, Dict, Any
@@ -58,7 +56,7 @@ def _env_offline() -> bool:
 import re as _re
 
 _MODEL_SIZE_RE = _re.compile(r"(?:^|[-_/])(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
-# MoE active-parameter pattern: matches "A3B", "A3.5B", etc.
+# MoE active-parameter pattern: "A3B", "A3.5B", etc.
 _ACTIVE_SIZE_RE = _re.compile(r"(?:^|[-_/])a(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
 
 
@@ -66,8 +64,8 @@ def extract_model_size_b(model_id: str) -> float | None:
     """Extract model size in billions from a model identifier.
 
     Prefers MoE active-parameter notation (e.g. ``A3B`` in
-    ``Qwen3.5-35B-A3B``) over the total parameter count.
-    Handles both ``B`` (billions) and ``M`` (millions) suffixes.
+    ``Qwen3.5-35B-A3B``) over total params. Handles ``B`` (billions)
+    and ``M`` (millions) suffixes.
     """
     mid = (model_id or "").lower()
     active = _ACTIVE_SIZE_RE.search(mid)
@@ -81,9 +79,9 @@ def extract_model_size_b(model_id: str) -> float | None:
     return val / 1000.0 if size.group(2).lower() == "m" else val
 
 
-# Model name mapping: maps all equivalent model names to their canonical YAML config file
-# Format: "canonical_model_name.yaml": [list of all equivalent model names]
-# Based on the model mapper provided - canonical filename is based on the first model name in the mapper
+# Maps equivalent model names to their canonical YAML config file.
+# Format: "canonical_model_name.yaml": [equivalent model names].
+# Canonical filename derives from the first model name in each list.
 MODEL_NAME_MAPPING = {
     # ── Embedding models ──
     "unsloth_all-MiniLM-L6-v2.yaml": [
@@ -457,7 +455,7 @@ MODEL_NAME_MAPPING = {
     ],
 }
 
-# Reverse mapping for quick lookup: model_name -> canonical_filename
+# Reverse lookup: model_name -> canonical_filename
 _REVERSE_MODEL_MAPPING = {}
 for canonical_file, model_names in MODEL_NAME_MAPPING.items():
     for model_name in model_names:
@@ -470,19 +468,17 @@ def load_model_config(
     token: Optional[str] = None,
     trust_remote_code: bool = True,
 ):
-    """
-    Load model config with optional authentication control.
-    """
+    """Load model config with optional authentication control."""
     from transformers import AutoConfig
 
     if token:
-        # Explicit token provided - use it
+        # Explicit token provided
         return AutoConfig.from_pretrained(
             model_name, trust_remote_code = trust_remote_code, token = token
         )
 
     if not use_auth:
-        # Load without any authentication (for public model checks)
+        # No authentication (for public model checks)
         with without_hf_auth():
             return AutoConfig.from_pretrained(
                 model_name,
@@ -490,7 +486,7 @@ def load_model_config(
                 token = None,
             )
 
-    # Use default authentication (cached tokens)
+    # Default authentication (cached tokens)
     return AutoConfig.from_pretrained(
         model_name,
         trust_remote_code = trust_remote_code,
@@ -588,8 +584,8 @@ _VISION_CHECK_INLINE_HELPERS = (
     "    )\n"
 )
 
-# Inline script executed in a subprocess with transformers 5.x activated.
-# Receives model_name and token via argv, prints JSON result to stdout.
+# Subprocess script run with transformers 5.x active. Takes model_name and
+# token via argv, prints JSON result to stdout.
 _VISION_CHECK_SCRIPT = (
     r"""
 import sys, os, json
@@ -636,10 +632,10 @@ def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None)
     with .venv_t5/ prepended to sys.path so AutoConfig recognizes newer
     architectures (glm4_moe_lite, etc.).
 
-    Returns True/False for definitive results, or None for transient failures
-    (timeouts, subprocess errors) so callers can decide whether to cache
-    the result. Subprocess failures are treated as transient because they
-    can be caused by temporary HF/auth/network issues.
+    Returns True/False for definitive results, or None for transient
+    failures (timeouts, subprocess errors) so callers can decide whether
+    to cache. Subprocess failures are treated as transient since they may
+    stem from temporary HF/auth/network issues.
     """
     token_arg = hf_token or ""
 
@@ -699,7 +695,7 @@ def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None)
 
 
 def _token_fingerprint(token: Optional[str]) -> Optional[str]:
-    """Return a SHA256 digest of the token for use as a cache key.
+    """SHA256 digest of the token for use as a cache key.
 
     Avoids storing the raw bearer token in process memory as a dict key.
     """
@@ -708,26 +704,26 @@ def _token_fingerprint(token: Optional[str]) -> Optional[str]:
     return hashlib.sha256(token.encode("utf-8")).hexdigest()
 
 
-# Cache vision detection results per session to avoid repeated subprocess spawns.
-# Keyed by (normalized_model_name, token_fingerprint) to handle gated models correctly.
-# Only definitive results (True/False from successful detection) are cached;
-# transient failures (network errors, timeouts) are NOT cached so they can be retried.
+# Cache vision detection per session to avoid repeated subprocess spawns.
+# Keyed by (normalized_model_name, token_fingerprint) to handle gated models.
+# Only definitive results are cached; transient failures (network, timeouts)
+# are NOT cached so they can be retried.
 _vision_detection_cache: Dict[Tuple[str, Optional[str]], bool] = {}
 _vision_cache_lock = threading.Lock()
 
 
 def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
     """
-    Detect vision-language models (VLMs) by checking architecture in config.
+    Detect vision-language models (VLMs) via architecture in config.
     Works for fine-tuned models since they inherit the base architecture.
 
     For models that require transformers 5.x (e.g. GLM-4.7-Flash), the check
     runs in a subprocess with .venv_t5/ activated -- same pattern as the
     training and inference workers.
 
-    Results are cached per (model_name, token_fingerprint) for the lifetime of
-    the process to avoid repeated subprocess spawns and HuggingFace API calls.
-    Transient failures are not cached so they can be retried on the next call.
+    Results are cached per (model_name, token_fingerprint) for the process
+    lifetime to avoid repeated subprocess spawns and HuggingFace API calls.
+    Transient failures are not cached so they can be retried.
 
     Args:
         model_name: Model identifier (HF repo or local path)
@@ -749,21 +745,21 @@ def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
         resolved_name = model_name
     cache_key = (resolved_name, _token_fingerprint(hf_token))
 
-    # Lock-free fast path for cache hits. Uses a sentinel to distinguish
-    # "key not found" from "value is False" in a single atomic dict.get() call.
+    # Lock-free fast path for cache hits. Sentinel distinguishes "key not
+    # found" from "value is False" in a single atomic dict.get() call.
     _MISS = object()
     cached = _vision_detection_cache.get(cache_key, _MISS)
     if cached is not _MISS:
         return cached
 
     # Compute outside the lock to avoid serializing long-running detection
-    # (subprocess spawns with 60s timeout, HF API calls) across all models.
-    # The tradeoff: two concurrent calls for the same uncached model may
-    # both run detection, but they produce the same result and the second
-    # write is a benign no-op.
+    # (60s-timeout subprocess spawns, HF API calls) across all models.
+    # Tradeoff: two concurrent calls for the same uncached model may both
+    # run detection, but produce the same result and the second write is a
+    # benign no-op.
     result = _is_vision_model_uncached(resolved_name, hf_token)
-    # Only cache definitive results; None means a transient failure occurred
-    # and we should retry on the next call instead of locking in a wrong answer.
+    # Only cache definitive results; None means a transient failure, so
+    # retry on the next call instead of locking in a wrong answer.
     if result is not None:
         with _vision_cache_lock:
             _vision_detection_cache[cache_key] = result
@@ -774,13 +770,12 @@ def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
 def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
     """Uncached vision model detection -- called by is_vision_model().
 
-    Returns True/False for definitive results, or None when detection failed
-    due to a transient error (network, timeout, subprocess failure) so the
-    caller knows not to cache the result.
+    Returns True/False for definitive results, or None on transient errors
+    (network, timeout, subprocess failure) so the caller knows not to cache.
 
     Do not call directly; use is_vision_model() instead.
     """
-    # Models that need transformers 5.x must be checked in a subprocess
+    # Models needing transformers 5.x must be checked in a subprocess
     # because AutoConfig in the main process (transformers 4.57.x) doesn't
     # recognize their architectures.
     from utils.transformers_version import needs_transformers_5
@@ -798,7 +793,7 @@ def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -
     try:
         config = load_model_config(model_name, use_auth = True, token = hf_token)
 
-        # Exclude audio-only models that share ForConditionalGeneration suffix
+        # Exclude audio-only models sharing the ForConditionalGeneration suffix
         # (e.g. CsmForConditionalGeneration, WhisperForConditionalGeneration)
         model_type = getattr(config, "model_type", None)
         if model_type in _AUDIO_ONLY_MODEL_TYPES:
@@ -818,8 +813,8 @@ def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -
 
     except Exception as e:
         logger.warning(f"Could not determine if {model_name} is vision model: {e}")
-        # Permanent failures (model not found, gated, bad config) should be
-        # cached as False. Transient failures (network, timeout) should not.
+        # Permanent failures (not found, gated, bad config) cache as False;
+        # transient failures (network, timeout) should not.
         try:
             from huggingface_hub.errors import RepositoryNotFoundError, GatedRepoError
         except ImportError:
@@ -841,10 +836,10 @@ def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -
 
 VALID_AUDIO_TYPES = ("snac", "csm", "bicodec", "dac", "whisper", "audio_vlm")
 
-# Cache detection results per session to avoid repeated API calls
+# Cache detection per session to avoid repeated API calls
 _audio_detection_cache: Dict[str, Optional[str]] = {}
 
-# Tokenizer token patterns → audio_type (all 6 types detected from tokenizer_config.json)
+# Tokenizer token patterns → audio_type (all 6 types from tokenizer_config.json)
 _AUDIO_TOKEN_PATTERNS = {
     "csm": lambda tokens: "<|AUDIO|>" in tokens and "<|audio_eos|>" in tokens,
     "whisper": lambda tokens: "<|startoftranscript|>" in tokens,
@@ -863,10 +858,10 @@ _AUDIO_TOKEN_PATTERNS = {
 
 def detect_audio_type(model_name: str, hf_token: Optional[str] = None) -> Optional[str]:
     """
-    Dynamically detect if a model is an audio model and return its type.
+    Detect if a model is an audio model and return its type.
 
-    Fully dynamic — works for any model, not just known ones.
-    Uses tokenizer_config.json special tokens to detect all 6 audio types.
+    Works for any model, not just known ones. Uses tokenizer_config.json
+    special tokens to detect all 6 audio types.
 
     Returns: audio_type string ('snac', 'csm', 'bicodec', 'dac', 'whisper', 'audio_vlm') or None.
     """
@@ -882,10 +877,10 @@ def detect_audio_type(model_name: str, hf_token: Optional[str] = None) -> Option
 
 
 def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None) -> Optional[str]:
-    """Detect audio type from tokenizer special tokens (for LLM-based audio models).
+    """Detect audio type from tokenizer special tokens (LLM-based audio models).
 
-    First checks local HF cache, then fetches tokenizer_config.json from HuggingFace.
-    Checks added_tokens_decoder for distinctive patterns.
+    Checks local HF cache first, then fetches tokenizer_config.json from
+    HuggingFace. Examines added_tokens_decoder for distinctive patterns.
     """
 
     def _check_token_patterns(tok_config: dict) -> Optional[str]:
@@ -898,7 +893,7 @@ def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None
                 return audio_type
         return None
 
-    # 1) Check local HF cache first (works for gated/offline models)
+    # 1) Local HF cache first (works for gated/offline models)
     try:
         repo_dir = get_cache_path(model_name)
         if repo_dir is not None and repo_dir.exists():
@@ -924,7 +919,7 @@ def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None
         import os
 
         paths_to_try = ["tokenizer_config.json", "LLM/tokenizer_config.json"]
-        # Use provided token, or fall back to env
+        # Use provided token, else env
         token = hf_token or os.environ.get("HF_TOKEN")
         headers = {}
         if token:
@@ -994,7 +989,7 @@ _MODEL_FAMILY_TOKENS: tuple[str, ...] = (
 )
 
 
-# Word-bounded match: any letter on either side disqualifies. Stops
+# Word-bounded match: a letter on either side disqualifies. Stops
 # ``phi`` matching ``sapphire``, ``yi`` matching ``tiny``, etc.
 _FAMILY_TOKEN_RE_CACHE: Dict[str, "_re.Pattern[str]"] = {}
 
@@ -1022,8 +1017,8 @@ def _detect_family_token(filename: str) -> Optional[str]:
 
 
 def mmproj_matches_model_family(model_path: str, mmproj_path: str) -> bool:
-    """Defense-in-depth guard for the launcher: True unless both filenames
-    carry recognised family tokens that disagree."""
+    """Launcher guard: True unless both filenames carry recognised family
+    tokens that disagree."""
     model_fam = _detect_family_token(Path(model_path).name)
     mmproj_fam = _detect_family_token(Path(mmproj_path).name)
     if model_fam is None or mmproj_fam is None:
@@ -1116,7 +1111,7 @@ def detect_mmproj_file(path: str, search_root: Optional[str] = None) -> Optional
                 continue
             if resolved in seen_resolved:
                 continue
-            # Prefer ``general.type=='mmproj'``; fall back to filename.
+            # Prefer ``general.type=='mmproj'``, else filename.
             meta = read_gguf_general_metadata(str(resolved))
             by_meta = is_mmproj_by_metadata(meta)
             if by_meta is True or (by_meta is None and _is_mmproj(f.name)):
@@ -1211,12 +1206,10 @@ def detect_gguf_model(path: str) -> Optional[str]:
     return None
 
 
-# Preferred GGUF quantization levels, in descending priority.
-# Q4_K_M is a good default: small, fast, acceptable quality.
-# UD (Unsloth Dynamic) variants are always preferred over standard quants
-# because they provide better quality per bit. If the repo has no UD variants
-# (e.g., bartowski repos), the standard quants are used as fallback.
-# Ordered by best size/quality tradeoff, not raw quality.
+# Preferred GGUF quant levels, descending priority. Q4_K_M is a good default
+# (small, fast, acceptable quality). UD (Unsloth Dynamic) variants beat
+# standard quants on quality per bit; repos without UD (e.g. bartowski) fall
+# back to standard quants. Ordered by size/quality tradeoff, not raw quality.
 _GGUF_QUANT_PREFERENCE = [
     # UD variants (best quality per bit) -- Q4 is the sweet spot
     "UD-Q4_K_XL",
@@ -1263,8 +1256,7 @@ def _pick_best_gguf(filenames: list[str]) -> Optional[str]:
     """
     Pick the best GGUF file from a list of filenames.
 
-    Prefers quantization levels in _GGUF_QUANT_PREFERENCE order.
-    Falls back to the first .gguf file found.
+    Prefers quant levels in _GGUF_QUANT_PREFERENCE order; else the first .gguf.
     """
     gguf_files = [f for f in filenames if f.lower().endswith(".gguf")]
     if not gguf_files:
@@ -1291,7 +1283,7 @@ class GgufVariantInfo:
 
 def _extract_quant_label(filename: str) -> str:
     """
-    Extract quantization label like Q4_K_M, IQ4_XS, BF16 from a GGUF filename.
+    Extract quant label like Q4_K_M, IQ4_XS, BF16 from a GGUF filename.
 
     Examples:
         "gemma-3-4b-it-Q4_K_M.gguf"          → "Q4_K_M"
@@ -1318,8 +1310,8 @@ def _extract_quant_label(filename: str) -> str:
     )
     match = re.search(quant_re, stem, re.IGNORECASE)
     # Subdir layouts like ``BF16/foo.gguf`` keep the quant in the directory,
-    # not the basename. Look at the parent dirs too so the variant label
-    # matches the snapshot-relative path produced elsewhere.
+    # not the basename. Check parent dirs too so the label matches the
+    # snapshot-relative path produced elsewhere.
     if not match and "/" in filename:
         parents = filename.rsplit("/", 1)[0]
         for segment in reversed(parents.split("/")):
@@ -1330,16 +1322,16 @@ def _extract_quant_label(filename: str) -> str:
     if match:
         prefix = match.group(1) or ""
         return f"{prefix}{match.group(2)}"
-    # Fallback: last segment after hyphen
+    # Fallback: last hyphen-separated segment
     return stem.split("-")[-1]
 
 
 def _iter_hf_cache_snapshots(repo_id: str):
     """Yield HF cache snapshot dirs for *repo_id*, newest first.
 
-    Empty generator if HF_HUB_CACHE is missing, the repo isn't cached,
-    or has no snapshots. Repo name match is case-insensitive to handle
-    casing drift between download time and lookup.
+    Empty if HF_HUB_CACHE is missing, the repo isn't cached, or has no
+    snapshots. Repo name match is case-insensitive to handle casing drift
+    between download time and lookup.
     """
     try:
         from huggingface_hub import constants as hf_constants
@@ -1389,8 +1381,8 @@ def list_gguf_variants(
     """
     List all GGUF quantization variants in a HuggingFace repo.
 
-    Separates main model files from mmproj (vision projection) files.
-    The presence of mmproj files indicates a vision-capable model.
+    Separates main model files from mmproj (vision projection) files;
+    mmproj presence indicates a vision-capable model.
 
     Returns:
         (variants, has_vision): list of non-mmproj GGUF variants + vision flag.
@@ -1406,9 +1398,9 @@ def list_gguf_variants(
     try:
         info = hf_model_info(repo_id, token = hf_token, files_metadata = True)
     except Exception as e:
-        # Permanent errors (deleted/gated/bad revision) must surface to
-        # the caller; serving stale cache here would mask the real cause.
-        # Matches the early-return in ``detect_gguf_model_remote``.
+        # Permanent errors (deleted/gated/bad revision) must surface to the
+        # caller; serving stale cache would mask the real cause. Matches the
+        # early-return in ``detect_gguf_model_remote``.
         if type(e).__name__ in (
             "RepositoryNotFoundError",
             "GatedRepoError",
@@ -1438,7 +1430,7 @@ def list_gguf_variants(
             continue
         size = sibling.size or 0
 
-        # mmproj files are vision projection models, not main model files
+        # mmproj files are vision projections, not main model files
         if "mmproj" in fname.lower():
             has_vision = True
             continue
@@ -1457,9 +1449,8 @@ def list_gguf_variants(
             )
         )
 
-    # Sort by size descending (largest = best quality first).
-    # Recommended pinning and OOM demotion are handled client-side
-    # where GPU VRAM info is available.
+    # Sort by size descending (largest = best quality first). Recommended
+    # pinning and OOM demotion happen client-side where GPU VRAM info exists.
     variants.sort(key = lambda v: -v.size_bytes)
 
     return variants, has_vision
@@ -1468,11 +1459,10 @@ def list_gguf_variants(
 def _resolve_gguf_dir(p: Path) -> Optional[Path]:
     """Resolve a path to the directory containing GGUF variants.
 
-    If *p* is already a directory, returns it directly.  If *p* is a ``.gguf``
-    file whose parent directory has model metadata (``config.json`` or
-    ``adapter_config.json``), returns the parent -- all GGUFs in that
-    directory belong to the same model.  Returns ``None`` for loose standalone
-    GGUFs (no config) to avoid cross-wiring unrelated models.
+    Directory *p* returns directly. A ``.gguf`` file whose parent dir has
+    model metadata (``config.json`` or ``adapter_config.json``) returns the
+    parent -- all GGUFs there belong to the same model. Returns ``None`` for
+    loose standalone GGUFs (no config) to avoid cross-wiring unrelated models.
     """
     if p.is_dir():
         return p
@@ -1490,9 +1480,9 @@ def _resolve_gguf_dir(p: Path) -> Optional[Path]:
 def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], bool]:
     """List GGUF quantization variants in a local directory.
 
-    Mirrors :func:`list_gguf_variants` but reads from the filesystem
-    instead of the HuggingFace API.  Aggregates shard sizes by quant
-    label so that split GGUFs appear as a single variant.
+    Mirrors :func:`list_gguf_variants` but reads the filesystem instead of
+    the HuggingFace API. Aggregates shard sizes by quant label so split
+    GGUFs appear as a single variant.
 
     Returns:
         (variants, has_vision): list of non-mmproj GGUF variants + vision flag.
@@ -1505,10 +1495,10 @@ def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], boo
     quant_first_file: dict[str, str] = {}
     has_vision = False
 
-    # Recurse so variant-specific subdirectories (e.g. ``BF16/...gguf``
-    # used by some HF GGUF repos for the largest quants) are picked up.
-    # Filenames in the result preserve the relative subpath so that
-    # ``_find_local_gguf_by_variant`` can locate the file again.
+    # Recurse so variant-specific subdirs (e.g. ``BF16/...gguf`` used by
+    # some HF GGUF repos for the largest quants) are picked up. Result
+    # filenames keep the relative subpath so ``_find_local_gguf_by_variant``
+    # can locate the file again.
     for f in sorted(_iter_gguf_files(p, recursive = True)):
         if _is_mmproj(f.name):
             has_vision = True
@@ -1517,8 +1507,8 @@ def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], boo
             size = f.stat().st_size
         except OSError:
             size = 0
-        # Pass the relative path so ``BF16/foo.gguf`` and ``Q4_K_M/foo.gguf``
-        # produce distinct quant labels instead of collapsing on basename.
+        # Use the relative path so ``BF16/foo.gguf`` and ``Q4_K_M/foo.gguf``
+        # get distinct quant labels instead of collapsing on basename.
         rel = f.relative_to(p).as_posix()
         quant = _extract_quant_label(rel)
         quant_totals[quant] = quant_totals.get(quant, 0) + size
@@ -1540,8 +1530,8 @@ def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], boo
 def _find_local_gguf_by_variant(directory: str, variant: str) -> Optional[str]:
     """Find the GGUF file in *directory* matching a quantization *variant*.
 
-    For sharded GGUFs (multiple files with the same quant label), returns
-    the first shard (sorted by name) which is what ``llama-server -m`` expects.
+    For sharded GGUFs (multiple files sharing a quant label), returns the
+    first shard (sorted by name), which is what ``llama-server -m`` expects.
 
     Returns the resolved absolute path, or ``None`` if no match.
     """
@@ -1549,10 +1539,10 @@ def _find_local_gguf_by_variant(directory: str, variant: str) -> Optional[str]:
     if p is None:
         return None
 
-    # Recurse into subdirectories so variants stored under a quant-named
-    # subdir (e.g. ``BF16/foo-BF16-00001-of-00002.gguf``) are found.
-    # Match against the relative path so the quant label can come from
-    # the directory name when the basename omits it.
+    # Recurse so variants under a quant-named subdir (e.g.
+    # ``BF16/foo-BF16-00001-of-00002.gguf``) are found. Match the relative
+    # path so the quant label can come from the dir name when the basename
+    # omits it.
     matches = sorted(
         f
         for f in _iter_gguf_files(p, recursive = True)
@@ -1566,8 +1556,8 @@ def _find_local_gguf_by_variant(directory: str, variant: str) -> Optional[str]:
 def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
     """Best GGUF filename for *repo_id* from the local HF cache, or None.
 
-    Excludes mmproj (vision projector) files so a partial cache that
-    only has the projector cannot route the projector as the main model.
+    Excludes mmproj (vision projector) files so a partial cache holding only
+    the projector cannot route it as the main model.
     """
     for snap in _iter_hf_cache_snapshots(repo_id):
         rel_files = [
@@ -1586,16 +1576,15 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op
 
     Returns the filename of the best GGUF file in the repo, or None.
 
-    Retries on transient HF Hub failures (network hiccups, 5xx, slow
-    cold-start of the API). Without retry, a single transient failure
-    here returns None silently and the caller treats the repo as
-    non-GGUF -- which on Apple Silicon (Mac UI route) means falling
-    through to the MLX backend, which then fails opening a non-existent
-    config.json on the GGUF-only repo. Three attempts with 1s/2s/4s
-    backoff covers the typical free-runner HF Hub flakiness.
+    Retries on transient HF Hub failures (network hiccups, 5xx, slow API
+    cold-start). Without retry, a single transient failure returns None
+    silently and the caller treats the repo as non-GGUF -- which on Apple
+    Silicon (Mac UI route) falls through to the MLX backend, which then
+    fails opening a non-existent config.json on the GGUF-only repo. Three
+    attempts with 1s/2s/4s backoff covers typical free-runner HF Hub flakiness.
 
-    When offline, falls back to the local HF cache so a downloaded
-    repo is still routed to llama-server (not MLX/Unsloth).
+    When offline, falls back to the local HF cache so a downloaded repo is
+    still routed to llama-server (not MLX/Unsloth).
     """
     import time
     from huggingface_hub import model_info as hf_model_info
@@ -1613,7 +1602,7 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op
             return _pick_best_gguf(repo_files)
         except Exception as e:
             last_err = e
-            # 404 / RepoNotFound is permanent -- don't waste attempts.
+            # 404 / RepoNotFound is permanent -- don't retry.
             err_name = type(e).__name__
             if err_name in (
                 "RepositoryNotFoundError",
@@ -1660,20 +1649,20 @@ def download_gguf_file(
     return local_path
 
 
-# Cache embedding detection results per session to avoid repeated HF API calls
+# Cache embedding detection per session to avoid repeated HF API calls
 _embedding_detection_cache: Dict[tuple, bool] = {}
 
 
 def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
     """
-    Detect embedding/sentence-transformer models using HuggingFace model metadata.
+    Detect embedding/sentence-transformer models via HuggingFace metadata.
 
-    Uses a belt-and-suspenders approach combining three signals:
+    Combines three signals:
       1. "sentence-transformers" in model tags
       2. "feature-extraction" in model tags
       3. pipeline_tag is "sentence-similarity" or "feature-extraction"
 
-    This catches all known embedding models including those like gte-modernbert
+    Catches all known embedding models, including ones like gte-modernbert
     whose library_name is "transformers" rather than "sentence-transformers".
 
     Args:
@@ -1681,8 +1670,8 @@ def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
         hf_token: Optional HF token for accessing gated/private models
 
     Returns:
-        True if the model is an embedding model, False otherwise.
-        Defaults to False for local paths or on errors.
+        True if embedding model, else False. Defaults to False for local
+        paths or on errors.
     """
     cache_key = (model_name, hf_token)
     if cache_key in _embedding_detection_cache:
@@ -1774,8 +1763,8 @@ def scan_trained_models(outputs_dir: str = str(outputs_root())) -> List[Tuple[st
     Scan outputs folder for trained Studio models.
 
     Returns:
-        List of tuples: [(display_name, model_path, model_type), ...]
-        model_type is "lora" for adapter runs and "merged" for full finetunes.
+        List of [(display_name, model_path, model_type), ...].
+        model_type is "lora" for adapter runs, "merged" for full finetunes.
     """
     trained_models = []
     outputs_path = resolve_output_dir(outputs_dir)
@@ -1796,7 +1785,7 @@ def scan_trained_models(outputs_dir: str = str(outputs_root())) -> List[Tuple[st
                 trained_models.append((display_name, model_path, model_type))
                 logger.debug("Found trained model: %s (%s)", display_name, model_type)
 
-        # Sort by modification time (newest first)
+        # Sort by mtime, newest first
         trained_models.sort(key = lambda x: Path(x[1]).stat().st_mtime, reverse = True)
 
         logger.info(
@@ -1822,7 +1811,7 @@ def scan_exported_models(
       - Flat:      {name}-finetune-gguf/  (GGUF exports)
 
     Returns:
-        List of tuples: [(display_name, model_path, export_type, base_model), ...]
+        List of [(display_name, model_path, export_type, base_model), ...].
         export_type: "lora" | "merged" | "gguf"
     """
     results = []
@@ -1836,8 +1825,8 @@ def scan_exported_models(
             if not run_dir.is_dir():
                 continue
 
-            # Check for flat GGUF export (e.g. exports/gemma-3-4b-it-finetune-gguf/)
-            # Filter out mmproj (vision projection) files — they aren't loadable as main models
+            # Flat GGUF export (e.g. exports/gemma-3-4b-it-finetune-gguf/).
+            # Skip mmproj (vision projection) files — not loadable as main models.
             gguf_files = [f for f in _iter_gguf_files(run_dir) if not _is_mmproj(f.name)]
             if gguf_files:
                 base_model = None
@@ -1850,7 +1839,7 @@ def scan_exported_models(
                     pass
 
                 display_name = run_dir.name
-                model_path = str(gguf_files[0])  # path to the .gguf file
+                model_path = str(gguf_files[0])  # the .gguf file
                 results.append((display_name, model_path, "gguf", base_model))
                 logger.debug(f"Found GGUF export: {display_name}")
                 continue
@@ -1889,8 +1878,8 @@ def scan_exported_models(
                 elif has_gguf:
                     export_type = "gguf"
                     gguf_list = list(_iter_gguf_files(checkpoint_dir))
-                    # Check checkpoint_dir first, then fall back to parent run_dir
-                    # (export.py writes metadata to the top-level export directory)
+                    # Check checkpoint_dir first, then parent run_dir
+                    # (export.py writes metadata to the top-level export dir)
                     for meta_dir in (checkpoint_dir, run_dir):
                         export_meta = meta_dir / "export_metadata.json"
                         try:
@@ -1910,7 +1899,7 @@ def scan_exported_models(
                 else:
                     continue
 
-                # Fallback: read base model from the original training run's
+                # Fallback: read base model from the training run's
                 # adapter_config.json in ./outputs/{run_name}/
                 if not base_model:
                     outputs_adapter_cfg = resolve_output_dir(run_dir.name) / "adapter_config.json"
@@ -2012,7 +2001,7 @@ def get_base_model_from_lora(lora_path: str) -> Optional[str]:
         if not _looks_like_lora_adapter(lora_path_obj):
             return None
 
-        # Try adapter_config.json first
+        # adapter_config.json first
         adapter_config_path = lora_path_obj / "adapter_config.json"
         if adapter_config_path.exists():
             with open(adapter_config_path, "r") as f:
@@ -2043,7 +2032,7 @@ def get_base_model_from_lora(lora_path: str) -> Optional[str]:
         # Format: unsloth_Meta-Llama-3.1-8B-Instruct-bnb-4bit_timestamp
         dir_name = lora_path_obj.name
         if dir_name.startswith("unsloth_"):
-            # Remove timestamp suffix (usually _1234567890)
+            # Drop timestamp suffix (usually _1234567890)
             parts = dir_name.split("_")
             # Reconstruct model name
             if len(parts) >= 2:
@@ -2072,21 +2061,21 @@ def load_model_defaults(model_name: str) -> Dict[str, Any]:
         model_name: Model identifier (e.g., "unsloth/Meta-Llama-3.1-8B-bnb-4bit")
 
     Returns:
-        Dictionary with default parameters from YAML file, or empty dict if not found
+        Dict of default parameters from the YAML file, or empty dict if none.
 
-    The function looks for a YAML file in configs/model_defaults/ (including subfolders)
-    based on the model name or its aliases from MODEL_NAME_MAPPING.
-    If no specific file exists, it falls back to default.yaml.
+    Looks for a YAML in configs/model_defaults/ (including subfolders) by the
+    model name or its aliases from MODEL_NAME_MAPPING, else falls back to
+    default.yaml.
     """
     try:
-        # Get the script directory to locate configs
+        # Locate configs relative to the script dir
         script_dir = Path(__file__).parent.parent.parent
         defaults_dir = script_dir / "assets" / "configs" / "model_defaults"
 
-        # First, check if model is in the mapping
+        # Check the mapping first
         if model_name.lower() in _REVERSE_MODEL_MAPPING:
             canonical_file = _REVERSE_MODEL_MAPPING[model_name.lower()]
-            # Search in subfolders and root
+            # Search subfolders and root
             for config_path in defaults_dir.rglob(canonical_file):
                 if config_path.is_file():
                     with open(config_path, "r", encoding = "utf-8") as f:
@@ -2094,10 +2083,9 @@ def load_model_defaults(model_name: str) -> Dict[str, Any]:
                         logger.info(f"Loaded model defaults from {config_path} (via mapping)")
                         return config
 
-        # If model_name is a local path (e.g. /home/.../Spark-TTS-0.5B/LLM from
-        # adapter_config.json, or C:\Users\...\model on Windows), try matching
-        # the last 1-2 path components against the registry
-        # (e.g. "Spark-TTS-0.5B/LLM").
+        # For local paths (e.g. /home/.../Spark-TTS-0.5B/LLM from
+        # adapter_config.json, or C:\Users\...\model on Windows), match the
+        # last 1-2 path components against the registry (e.g. "Spark-TTS-0.5B/LLM").
         _is_local_path = is_local_path(model_name)
         # Normalize Windows backslash paths so Path().parts splits correctly
         # on POSIX/WSL hosts (pathlib treats backslashes as literals on Linux).
@@ -2118,13 +2106,13 @@ def load_model_defaults(model_name: str) -> Dict[str, Any]:
                                     )
                                     return config
 
-        # Try exact model name match (for backward compatibility).
-        # For local filesystem paths, use only the directory basename to
-        # avoid passing absolute paths (e.g. C:\...) into rglob which
-        # raises "Non-relative patterns are unsupported" on Windows.
+        # Exact model name match (backward compatibility). For local paths,
+        # use only the dir basename to avoid passing absolute paths (e.g.
+        # C:\...) into rglob, which raises "Non-relative patterns are
+        # unsupported" on Windows.
         _lookup_name = Path(_normalized).name if _is_local_path else model_name
         model_filename = _lookup_name.replace("/", "_") + ".yaml"
-        # Search in subfolders and root
+        # Search subfolders and root
         for config_path in defaults_dir.rglob(model_filename):
             if config_path.is_file():
                 with open(config_path, "r", encoding = "utf-8") as f:
@@ -2150,17 +2138,17 @@ def load_model_defaults(model_name: str) -> Dict[str, Any]:
 
 @dataclass
 class ModelConfig:
-    """Configuration for a model to load"""
+    """Configuration for a model to load."""
 
     identifier: str  # Clean model identifier (org/name or path)
     display_name: str  # Original UI display name
     path: str  # Normalized filesystem path
-    is_local: bool  # Is this a local file vs HF model?
-    is_cached: bool  # Is this already in HF cache?
-    is_vision: bool  # Is this a vision model?
-    is_lora: bool  # Is this a lora adapter?
-    is_gguf: bool = False  # Is this a GGUF model?
-    is_audio: bool = False  # Is this a TTS audio model?
+    is_local: bool  # Local file vs HF model?
+    is_cached: bool  # Already in HF cache?
+    is_vision: bool  # Vision model?
+    is_lora: bool  # LoRA adapter?
+    is_gguf: bool = False  # GGUF model?
+    is_audio: bool = False  # TTS audio model?
     audio_type: Optional[str] = None  # Audio codec type: 'snac', 'csm', 'bicodec', 'dac'
     has_audio_input: bool = False  # Accepts audio input (ASR/speech understanding)
     gguf_file: Optional[str] = None  # Full path to the .gguf file (local mode)
@@ -2180,7 +2168,7 @@ class ModelConfig:
         """
         Create ModelConfig from a local LoRA adapter path.
 
-        Automatically detects the base model from adapter config.
+        Auto-detects the base model from adapter config.
 
         Args:
             lora_path: Path to LoRA adapter (e.g., "./outputs/unsloth_Meta-Llama-3.1_.../")
@@ -2196,27 +2184,23 @@ class ModelConfig:
                 logger.error(f"LoRA path does not exist: {lora_path}")
                 return None
 
-            # Get base model
             base_model = get_base_model_from_lora(lora_path)
             if not base_model:
                 logger.error(f"Could not determine base model for LoRA: {lora_path}")
                 return None
 
-            # Check if base model is vision
             is_vision = is_vision_model(base_model, hf_token = hf_token)
-
-            # Check if base model is audio
             audio_type = detect_audio_type(base_model, hf_token = hf_token)
 
             display_name = lora_path_obj.name
-            identifier = lora_path  # Use path as identifier for local LoRAs
+            identifier = lora_path  # path as identifier for local LoRAs
 
             return cls(
                 identifier = identifier,
                 display_name = display_name,
                 path = lora_path,
                 is_local = True,
-                is_cached = True,  # Local LoRAs are always "cached"
+                is_cached = True,  # local LoRAs are always "cached"
                 is_vision = is_vision,
                 is_lora = True,
                 is_audio = audio_type is not None and audio_type != "audio_vlm",
@@ -2241,7 +2225,7 @@ class ModelConfig:
         Create ModelConfig from a clean model identifier.
 
         For FastAPI routes where the frontend sends sanitized model paths.
-        No Gradio dropdown parsing - expects clean identifiers like:
+        No Gradio dropdown parsing; expects clean identifiers like:
         - "unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit"
         - "./outputs/my_lora_adapter"
         - "/absolute/path/to/model"
@@ -2250,9 +2234,9 @@ class ModelConfig:
             model_id: Clean model identifier (HF repo name or local path)
             hf_token: Optional HF token for vision detection on gated models
             is_lora: Whether this is a LoRA adapter
-            gguf_variant: Optional GGUF quantization variant (e.g. "Q4_K_M").
-                For remote GGUF repos, specifies which quant to load via -hf.
-                If None, auto-selects using _pick_best_gguf().
+            gguf_variant: Optional GGUF quant variant (e.g. "Q4_K_M"). For
+                remote GGUF repos, sets which quant to load via -hf. If None,
+                auto-selects via _pick_best_gguf().
 
         Returns:
             ModelConfig or None if configuration cannot be created
@@ -2269,8 +2253,9 @@ class ModelConfig:
             identifier = f"unsloth/{identifier}"
             path = identifier
 
-        # Preserve requested casing, but if a case-variant already exists in local HF cache,
-        # reuse that exact repo_id spelling to avoid one-time re-downloads after #2592.
+        # Preserve requested casing, but if a case-variant already exists in
+        # local HF cache, reuse that exact repo_id spelling to avoid one-time
+        # re-downloads after #2592.
         if not is_local:
             resolved_identifier = resolve_cached_repo_id_case(identifier)
             if resolved_identifier != identifier:
@@ -2292,12 +2277,12 @@ class ModelConfig:
                 display_name = Path(gguf_file).stem
                 logger.info(f"Detected local GGUF model: {gguf_file}")
 
-                # Detect vision: check if base model is vision, then look for mmproj
+                # Vision: check base model, then look for mmproj
                 mmproj_file = None
                 gguf_is_vision = False
                 gguf_dir = Path(gguf_file).parent
 
-                # Determine if this is a vision model from export metadata
+                # Is this a vision model, per export metadata?
                 base_is_vision = False
                 meta_path = gguf_dir / "export_metadata.json"
                 if meta_path.exists():
@@ -2310,15 +2295,12 @@ class ModelConfig:
                     except Exception as e:
                         logger.debug(f"Could not read export metadata: {e}")
 
-                # If vision (or mmproj happens to exist), find the mmproj
-                # file. The recursive variant scan in
-                # ``_find_local_gguf_by_variant`` may have returned a
-                # weight file inside a quant-named subdir (e.g.
-                # ``.../BF16/foo.gguf``) while ``mmproj-*.gguf`` lives
-                # at the snapshot root. Pass ``search_root=path`` so
-                # ``detect_mmproj_file`` walks up to the snapshot root
-                # instead of seeing only the weight file's immediate
-                # parent.
+                # Find the mmproj file. The recursive variant scan in
+                # ``_find_local_gguf_by_variant`` may have returned a weight
+                # file inside a quant-named subdir (e.g. ``.../BF16/foo.gguf``)
+                # while ``mmproj-*.gguf`` lives at the snapshot root. Pass
+                # ``search_root=path`` so ``detect_mmproj_file`` walks up to
+                # the snapshot root instead of only the weight's parent.
                 mmproj_file = detect_mmproj_file(gguf_file, search_root = path)
                 if mmproj_file:
                     gguf_is_vision = True
@@ -2339,11 +2321,11 @@ class ModelConfig:
                     gguf_mmproj_file = mmproj_file,
                 )
         else:
-            # Check if the HF repo contains GGUF files
+            # Does the HF repo contain GGUF files?
             gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)
             if gguf_filename:
-                # Preflight: verify llama-server binary exists BEFORE user waits
-                # for a multi-GB download that llama-server handles natively
+                # Preflight: verify llama-server binary exists BEFORE the user
+                # waits for a multi-GB download llama-server handles natively
                 from core.inference.llama_cpp import LlamaCppBackend
 
                 if not LlamaCppBackend._find_llama_server_binary():
@@ -2352,7 +2334,7 @@ class ModelConfig:
                         "Run setup.sh to build it, or set LLAMA_SERVER_PATH."
                     )
 
-                # Use list_gguf_variants() to detect vision & resolve variant
+                # list_gguf_variants() detects vision & resolves the variant
                 variants, has_vision = list_gguf_variants(identifier, hf_token = hf_token)
                 variant = gguf_variant
                 if not variant:
@@ -2383,7 +2365,7 @@ class ModelConfig:
                     gguf_variant = variant,
                 )
 
-        # Auto-detect LoRA for local paths (check adapter_config.json on disk)
+        # Auto-detect LoRA for local paths (adapter_config.json on disk)
         if not is_lora and is_local:
             detected_base = (
                 get_base_model_from_lora(path) if _looks_like_lora_adapter(Path(path)) else None
@@ -2406,7 +2388,7 @@ class ModelConfig:
             except Exception as e:
                 logger.debug(f"Could not check remote LoRA status for '{identifier}': {e}")
 
-            # API may have failed; adapter_config.json may still be cached.
+            # API may have failed; adapter_config.json could still be cached.
             if not is_lora:
                 for snap in _iter_hf_cache_snapshots(identifier):
                     if (snap / "adapter_config.json").is_file():
@@ -2421,7 +2403,7 @@ class ModelConfig:
                 # Local LoRA: read adapter_config.json from disk
                 base_model = get_base_model_from_lora(path)
             else:
-                # Remote LoRA: download adapter_config.json from HF
+                # Remote LoRA: fetch adapter_config.json from HF
                 try:
                     from huggingface_hub import hf_hub_download
 
@@ -2473,7 +2455,7 @@ class ModelConfig:
         is_lora: bool = False,
     ) -> Optional["ModelConfig"]:
         """
-        Create a universal ModelConfig from UI dropdown/search selections.
+        Create a ModelConfig from UI dropdown/search selections.
         Handles base models and LoRA adapters.
         """
         selected = None
@@ -2487,7 +2469,7 @@ class ModelConfig:
 
         display_name = selected
 
-        #  Use the correct 'local_models' parameter to resolve display names
+        # Resolve display names via the 'local_models' parameter
         if " (Active)" in selected or " (Ready)" in selected:
             clean_display_name = selected.replace(" (Active)", "").replace(" (Ready)", "")
             if local_models:
@@ -2496,7 +2478,7 @@ class ModelConfig:
                         selected = local_path
                         break
 
-        # Clean all UI status indicators to get the final identifier
+        # Strip all UI status indicators to get the final identifier
         identifier = selected
         for status in UI_STATUS_INDICATORS:
             identifier = identifier.replace(status, "")
@@ -2516,23 +2498,23 @@ class ModelConfig:
                 identifier = resolved_identifier
                 path = resolved_identifier
 
-        # --- Logic for Base Model and Vision Detection ---
+        # --- Base Model and Vision Detection ---
         base_model = None
         is_vision = False
 
         if is_lora:
-            # For a LoRA, we MUST find its base model.
+            # A LoRA MUST have a base model.
             base_model = get_base_model_from_lora(path)
             if not base_model:
                 logger.warning(
                     f"Could not determine base model for LoRA '{path}'. Cannot create config."
                 )
-                return None  # Cannot proceed without a base model
+                return None  # cannot proceed without a base model
 
-            # A LoRA's vision capability is determined by its base model.
+            # A LoRA's vision capability comes from its base model.
             is_vision = is_vision_model(base_model, hf_token = hf_token)
         else:
-            # For a base model, just check its own vision status.
+            # Base model: check its own vision status.
             is_vision = is_vision_model(identifier, hf_token = hf_token)
 
         from utils.paths import is_model_cached
@@ -2547,5 +2529,5 @@ class ModelConfig:
             is_cached = is_cached,
             is_vision = is_vision,
             is_lora = is_lora,
-            base_model = base_model,  # This will be None for base models, and populated for LoRAs
+            base_model = base_model,  # None for base models, set for LoRAs
         )
diff --git a/studio/backend/utils/paths/__init__.py b/studio/backend/utils/paths/__init__.py
index eba7a9de6c..8805308829 100644
--- a/studio/backend/utils/paths/__init__.py
+++ b/studio/backend/utils/paths/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Path utilities for model and dataset handling
-"""
+"""Path utilities for model and dataset handling."""
 
 from .path_utils import (
     normalize_path,
@@ -46,8 +44,8 @@ from .storage_roots import (
     resolve_dataset_path,
 )
 
-# Re-export shim: name-load the project-path helpers so the import-hoist
-# safety net sees them used here, not just listed in __all__ as strings.
+# Re-export shim: reference the project-path helpers by name so the
+# import-hoist safety net sees them used, not just named in __all__.
 _REEXPORTED = (documents_root, project_workspaces_root)
 
 __all__ = [
diff --git a/studio/backend/utils/paths/path_utils.py b/studio/backend/utils/paths/path_utils.py
index 22c6c46ee1..a065250154 100644
--- a/studio/backend/utils/paths/path_utils.py
+++ b/studio/backend/utils/paths/path_utils.py
@@ -17,7 +17,7 @@ logger = get_logger(__name__)
 # Per-process cache to avoid repeated cache-dir scans for the same identifier.
 _CACHE_CASE_RESOLUTION_MEMO: dict[str, str] = {}
 
-# Lightweight instrumentation counters for operational visibility.
+# Instrumentation counters for operational visibility.
 _CACHE_CASE_RESOLUTION_STATS: dict[str, int] = {
     "calls": 0,
     "memo_hits": 0,
@@ -63,8 +63,7 @@ def normalize_path(path: str) -> str:
 
     # Handle Windows drive letters (C:\\ or c:\\)
     if len(path) >= 3 and path[1] == ":" and path[2] in ("\\", "/"):
-        # Only map to /mnt/<drive>/ when running under WSL;
-        # on native Windows the drive letter must be preserved.
+        # Map to /mnt/<drive>/ only under WSL; native Windows keeps the drive letter.
         if _IS_WSL:
             drive = path[0].lower()
             rest = path[3:].replace("\\", "/")
@@ -86,7 +85,7 @@ def is_local_path(path: str) -> bool:
     if not path:
         return False
 
-    # If it exists on disk, treat as local (covers relative paths like "outputs/foo").
+    # Exists on disk → local (covers relative paths like "outputs/foo").
     try:
         if Path(normalize_path(path)).expanduser().exists():
             return True
@@ -122,7 +121,7 @@ def is_model_cached(model_name: str) -> bool:
     if not cache_path:
         return False
 
-    # Check for actual model files
+    # Check for model files
     for suffix in [".safetensors", ".bin", ".json"]:
         if list(cache_path.rglob(f"*{suffix}")):
             return True
@@ -146,9 +145,9 @@ def _hf_hub_cache_dir() -> Path:
 def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
     """Resolve repo_id to the exact casing already present in local HF cache.
 
-    Policy: prefer the requested/canonical repo_id, but if a case-variant already
-    exists in local HF cache, reuse that exact cached spelling. This avoids
-    duplicate downloads while preserving user intent whenever possible.
+    Policy: prefer the requested/canonical repo_id, but reuse a case-variant's
+    exact cached spelling if one already exists in local HF cache. Avoids
+    duplicate downloads while preserving user intent where possible.
     """
     _CACHE_CASE_RESOLUTION_STATS["calls"] += 1
 
@@ -163,8 +162,8 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
 
     expected_dir = f"models--{model_name.replace('/', '--')}"
 
-    # Always check the exact-case path first so a newly-appeared exact match
-    # wins over any previously memoized variant.
+    # Check the exact-case path first so a newly-appeared exact match wins over
+    # any previously memoized variant.
     exact_path = cache_dir / expected_dir
     if exact_path.is_dir():
         if use_memo:
@@ -172,8 +171,8 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
         _CACHE_CASE_RESOLUTION_STATS["exact_hits"] += 1
         return model_name
 
-    # Validate memoized entries still exist on disk before returning them.
-    # This prevents stale results when cache dirs are deleted/recreated.
+    # Validate memoized entries still exist on disk before returning them,
+    # preventing stale results when cache dirs are deleted/recreated.
     if use_memo:
         cached = _CACHE_CASE_RESOLUTION_MEMO.get(model_name)
         if cached is not None:
@@ -181,7 +180,7 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
             if cached_path.is_dir():
                 _CACHE_CASE_RESOLUTION_STATS["memo_hits"] += 1
                 return cached
-            # Stale entry -- drop it and re-scan below.
+            # Stale entry -- drop it and re-scan below
             _CACHE_CASE_RESOLUTION_MEMO.pop(model_name, None)
 
     expected_lower = expected_dir.lower()
@@ -200,7 +199,7 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
             candidates.append(repo_part.replace("--", "/"))
 
         if candidates:
-            # Deterministic tie-break if multiple case variants coexist.
+            # Deterministic tie-break if multiple case variants coexist
             resolved = sorted(candidates)[0]
             if len(candidates) > 1:
                 _CACHE_CASE_RESOLUTION_STATS["tie_breaks"] += 1
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index b254c20f97..de88a0bf31 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -11,9 +11,9 @@ import tempfile
 
 
 def _infer_studio_home_from_venv() -> Path | None:
-    """Return parent dir of sys.prefix as STUDIO_HOME if running from an
+    """Return parent of sys.prefix as STUDIO_HOME when running from an
     installer-managed unsloth_studio venv. Sentinel-gated (share/studio.conf
-    or bin shim) so a developer venv named unsloth_studio is not misidentified.
+    or bin shim) so a dev venv named unsloth_studio isn't misidentified.
     """
     try:
         prefix = Path(sys.prefix).resolve()
@@ -38,8 +38,8 @@ def studio_root() -> Path:
     """Studio install root.
 
     Priority: UNSLOTH_STUDIO_HOME, then STUDIO_HOME alias, then sys.prefix
-    inference, then legacy ~/.unsloth/studio. UNSLOTH_STUDIO_HOME wins when
-    both are set (the more specific signal beats the generic alias).
+    inference, then legacy ~/.unsloth/studio. UNSLOTH_STUDIO_HOME wins if
+    both are set (specific signal beats generic alias).
     """
     override = (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip()
     if not override:
@@ -56,7 +56,7 @@ def studio_root() -> Path:
 
 
 def cache_root() -> Path:
-    """Central cache directory for all studio downloads (models, datasets, etc.)."""
+    """Central cache dir for all studio downloads (models, datasets, etc.)."""
     return studio_root() / "cache"
 
 
@@ -158,16 +158,15 @@ def ensure_dir(path: Path) -> Path:
 
 
 def legacy_hf_cache_dir() -> Path:
-    """Old Unsloth-specific HF hub cache, kept for backward-compat scanning."""
+    """Old Unsloth-specific HF hub cache, kept for backward-compat scans."""
     return cache_root() / "huggingface" / "hub"
 
 
 def hf_default_cache_dir() -> Path:
-    """Return the platform default HuggingFace hub cache (ignoring env overrides).
+    """Platform default HuggingFace hub cache (ignoring env overrides).
 
-    This is the location HF uses when no ``HF_HUB_CACHE`` / ``HF_HOME``
-    env var is set.  We scan it so that models a user downloaded *before*
-    installing Unsloth Studio are still discovered.
+    Where HF caches when no ``HF_HUB_CACHE`` / ``HF_HOME`` is set. Scanned
+    so models downloaded *before* installing Unsloth Studio are discovered.
     """
     return Path.home() / ".cache" / "huggingface" / "hub"
 
@@ -183,7 +182,7 @@ def lmstudio_model_dirs() -> list[Path]:
             seen.add(resolved)
             dirs.append(p)
 
-    # 1. Check LM Studio settings.json for custom downloads folder
+    # 1. LM Studio settings.json custom downloads folder
     settings_path = Path.home() / ".lmstudio" / "settings.json"
     if settings_path.is_file():
         try:
@@ -207,17 +206,17 @@ def lmstudio_model_dirs() -> list[Path]:
 def well_known_model_dirs() -> list[Path]:
     """Return directories commonly used by other local LLM tools.
 
-    Used by the folder browser to offer quick-pick chips. Returns only
-    paths that exist on disk, so the UI never shows dead chips. Order
-    reflects a rough "likelihood the user has models here" -- LM Studio
-    and Ollama first, then the generic fallbacks.
+    Backs the folder browser's quick-pick chips. Returns only paths that
+    exist on disk, so the UI never shows dead chips. Order reflects rough
+    likelihood of models being there -- LM Studio and Ollama first, then
+    generic fallbacks.
     """
     candidates: list[Path] = []
 
     # LM Studio (reuses the logic above, including settings.json override)
     candidates.extend(lmstudio_model_dirs())
 
-    # Ollama -- both the user-level and common system-wide install paths
+    # Ollama -- user-level and common system-wide install paths
     # (https://github.com/ollama/ollama/issues/733).
     ollama_env = os.environ.get("OLLAMA_MODELS")
     if ollama_env:
@@ -229,7 +228,7 @@ def well_known_model_dirs() -> list[Path]:
     # HF hub cache root (separate from the explicit HF cache chip)
     candidates.append(Path.home() / ".cache" / "huggingface" / "hub")
 
-    # Generic "my models" spots users tend to drop things into
+    # Generic "my models" spots users drop things into
     for name in ("models", "Models"):
         candidates.append(Path.home() / name)
 
@@ -253,14 +252,12 @@ def _setup_cache_env() -> None:
     """Set cache environment variables for HuggingFace, uv, and vLLM.
 
     Respects the standard HF cache resolution chain: explicit ``HF_HOME``
-    / ``HF_HUB_CACHE`` env vars take priority, then ``XDG_CACHE_HOME``,
-    then the platform default (``~/.cache/huggingface``).  The legacy
-    Unsloth cache is still *scanned* for models but is never set as the
-    active download target.
+    / ``HF_HUB_CACHE`` win, then ``XDG_CACHE_HOME``, then the platform
+    default (``~/.cache/huggingface``). The legacy Unsloth cache is still
+    *scanned* for models but never set as the active download target.
 
-    Only sets variables that are not already set by the user, so
-    explicit overrides (e.g. HF_HOME=/data/hf) are respected.
-    Works on Linux, macOS, and Windows.
+    Only sets variables not already set by the user, so explicit overrides
+    (e.g. HF_HOME=/data/hf) are respected. Works on Linux, macOS, Windows.
     """
     root = cache_root()
     xdg_cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")).expanduser()
@@ -327,8 +324,8 @@ def resolve_under_root(
 ) -> Path:
     """Resolve ``path_value`` and assert the result is under ``root``.
 
-    Absolutes are accepted only if already contained (so internal pre-resolved
-    paths re-enter idempotently); user-facing schemas reject absolutes upstream.
+    Absolutes are accepted only if already contained (so pre-resolved
+    internal paths re-enter idempotently); schemas reject absolutes upstream.
     """
     if not path_value or not str(path_value).strip():
         return root
diff --git a/studio/backend/utils/studio_version.py b/studio/backend/utils/studio_version.py
index e59439a2cc..98c48fe45c 100644
--- a/studio/backend/utils/studio_version.py
+++ b/studio/backend/utils/studio_version.py
@@ -74,8 +74,8 @@ def _exact_git_studio_tag(repo_root: Path) -> str | None:
 def get_studio_version(repo_root: Path | None = None) -> str:
     """Return the installed Studio release tag for display, or ``dev``.
 
-    This value is intentionally separate from the PyPI ``unsloth`` package
-    version used by update checks. It never performs network requests.
+    Intentionally separate from the PyPI ``unsloth`` package version used by
+    update checks. Never performs network requests.
     """
     resolved_repo_root = repo_root or _repo_root()
 
diff --git a/studio/backend/utils/subprocess_compat.py b/studio/backend/utils/subprocess_compat.py
index bedf8cf2e6..b7fe906e91 100644
--- a/studio/backend/utils/subprocess_compat.py
+++ b/studio/backend/utils/subprocess_compat.py
@@ -10,8 +10,8 @@ import sys
 def windows_hidden_subprocess_kwargs() -> dict[str, object]:
     """Return Windows-only subprocess kwargs that suppress console windows.
 
-    On non-Windows platforms returns an empty dict so callers can always
-    unpack the result into ``subprocess.run`` / ``subprocess.Popen`` via
+    Returns an empty dict off Windows so callers can always unpack it into
+    ``subprocess.run`` / ``subprocess.Popen`` via
     ``**windows_hidden_subprocess_kwargs()``.
     """
     if sys.platform != "win32":
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index 16f964d628..7c1bc361b6 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -4,26 +4,24 @@
 """
 Automatic transformers version switching.
 
-Some newer model architectures (Ministral-3, GLM-4.7-Flash, Qwen3-30B-A3B MoE,
-tiny_qwen3_moe) require transformers>=5.3.0, while Gemma 4 models require
-transformers>=5.5.0.  Everything else needs the default 4.57.x that ships
-with Unsloth.
+Some newer architectures (Ministral-3, GLM-4.7-Flash, Qwen3-30B-A3B MoE,
+tiny_qwen3_moe) need transformers>=5.3.0; Gemma 4 needs >=5.5.0. Everything
+else uses the default 4.57.x that ships with Unsloth.
 
-Two separate target directories are maintained:
+Two target directories:
   - .venv_t5_530/  — transformers 5.3.0 (Ministral-3, GLM, Qwen3 MoE, etc.)
   - .venv_t5_550/  — transformers 5.5.0 (Gemma 4)
 
-When loading a LoRA adapter with a custom name, we resolve the base model from
-``adapter_config.json`` and check *that* against the model list.
+For a custom-named LoRA adapter, the base model is resolved from
+``adapter_config.json`` and checked against the model list.
 
 Strategy:
-  Training and inference run in subprocesses that activate the correct version
-  via sys.path (prepending the appropriate .venv_t5_*/ directory). See:
-    - core/training/worker.py
-    - core/inference/worker.py
+  Training and inference run in subprocesses that activate the right version
+  via sys.path (prepending the appropriate .venv_t5_*/ dir). See
+  core/training/worker.py and core/inference/worker.py.
 
-  For export (still in-process), ensure_transformers_version() does a lightweight
-  sys.path swap using the same directories pre-installed by setup.sh.
+  For export (in-process), ensure_transformers_version() does a lightweight
+  sys.path swap using the same setup.sh-installed directories.
 """
 
 import importlib
@@ -57,8 +55,7 @@ def _env_offline() -> bool:
 # Detection
 # ---------------------------------------------------------------------------
 
-# Lowercase substrings — if ANY appears anywhere in the lowered model name,
-# we need transformers 5.3.0.
+# Lowercase substrings — any match in the lowered model name needs transformers 5.3.0.
 TRANSFORMERS_5_MODEL_SUBSTRINGS: tuple[str, ...] = (
     "ministral-3-",  # Ministral-3-{3,8,14}B-{Instruct,Reasoning,Base}-2512
     "glm-4.7-flash",  # GLM-4.7-Flash
@@ -85,15 +82,15 @@ _TRANSFORMERS_550_MODEL_TYPES: set[str] = {
     "gemma4",
 }
 
-# Tokenizer classes that only exist in transformers>=5.x
+# Tokenizer classes that only exist in transformers>=5.x.
 _TRANSFORMERS_5_TOKENIZER_CLASSES: set[str] = {
     "TokenizersBackend",
 }
 
-# Cache for dynamic tokenizer_config.json lookups to avoid repeated fetches
+# Cache for dynamic tokenizer_config.json lookups (avoids repeated fetches).
 _tokenizer_class_cache: dict[str, bool] = {}
 
-# Cache for dynamic config.json lookups (architecture/model_type checks)
+# Cache for dynamic config.json lookups (architecture/model_type checks).
 _config_needs_550_cache: dict[str, bool] = {}
 
 # Versions
@@ -116,12 +113,10 @@ _VENV_T5_DIR = _VENV_T5_550_DIR
 def activate_transformers_for_subprocess(model_name: str) -> None:
     """Activate the correct transformers version in a subprocess worker.
 
-    Call this BEFORE any ML imports. Resolves LoRA adapters to their base
-    model, determines the required tier, and prepends the appropriate
-    ``.venv_t5_*`` directory to ``sys.path``.  Also propagates the path
-    via ``PYTHONPATH`` for child processes (e.g. GGUF converter).
-
-    Used by training, inference, and export workers.
+    Call BEFORE any ML imports. Resolves LoRA adapters to their base model,
+    determines the required tier, prepends the appropriate ``.venv_t5_*`` dir to
+    ``sys.path``, and propagates it via ``PYTHONPATH`` for child processes
+    (e.g. GGUF converter). Used by training, inference, and export workers.
     """
     resolved = _resolve_base_model(model_name)
     tier = get_transformers_tier(resolved)
@@ -155,11 +150,10 @@ def activate_transformers_for_subprocess(model_name: str) -> None:
 def _resolve_base_model(model_name: str) -> str:
     """If *model_name* points to a LoRA adapter, return its base model.
 
-    Checks for ``adapter_config.json`` locally first.  Only calls the heavier
-    ``get_base_model_from_lora`` for paths that are actual local directories
-    (avoids noisy warnings for plain HF model IDs).
-
-    Returns the original *model_name* unchanged if it is not a LoRA adapter.
+    Checks ``adapter_config.json`` locally first. Only calls the heavier
+    ``get_base_model_from_lora`` for real local directories (avoids noisy
+    warnings for plain HF model IDs). Returns *model_name* unchanged if not a
+    LoRA adapter.
     """
     # --- Fast local check ---------------------------------------------------
     local_path = Path(model_name)
@@ -221,11 +215,11 @@ def _resolve_base_model(model_name: str) -> str:
 
 
 def _check_tokenizer_config_needs_v5(model_name: str) -> bool:
-    """Fetch tokenizer_config.json from HuggingFace and check if the
-    tokenizer_class requires transformers 5.x.
+    """True if the model's tokenizer_class requires transformers 5.x.
 
-    Results are cached in ``_tokenizer_class_cache`` to avoid repeated fetches.
-    Returns False on any network/parse error (fail-open to default version).
+    Checks local tokenizer_config.json, else fetches from HuggingFace. Cached in
+    ``_tokenizer_class_cache``. Returns False on any network/parse error
+    (fail-open to default version).
     """
     if model_name in _tokenizer_class_cache:
         return _tokenizer_class_cache[model_name]
@@ -280,12 +274,11 @@ def _check_tokenizer_config_needs_v5(model_name: str) -> bool:
 
 
 def _check_config_needs_550(model_name: str) -> bool:
-    """Check ``config.json`` for architectures or model_type that require
-    transformers 5.5.0 (e.g. Gemma 4).
+    """True if ``config.json`` has architectures/model_type needing transformers
+    5.5.0 (e.g. Gemma 4).
 
-    Checks locally first, then falls back to fetching from HuggingFace.
-    Results are cached in ``_config_needs_550_cache``.
-    Returns False on any error (fail-open to lower tier).
+    Checks locally first, else fetches from HuggingFace. Cached in
+    ``_config_needs_550_cache``. Returns False on any error (fail-open to lower tier).
     """
     if model_name in _config_needs_550_cache:
         return _config_needs_550_cache[model_name]
@@ -352,10 +345,8 @@ def _check_config_needs_550(model_name: str) -> bool:
 def get_transformers_tier(model_name: str) -> str:
     """Return the transformers tier required for *model_name*.
 
-    Returns ``"550"`` for models needing transformers 5.5.0 (e.g. Gemma 4),
-    ``"530"`` for models needing transformers 5.3.0 (e.g. Ministral-3, Qwen3 MoE),
-    or ``"default"`` for everything else (4.57.x).
-
+    ``"550"`` for transformers 5.5.0 (e.g. Gemma 4), ``"530"`` for 5.3.0
+    (e.g. Ministral-3, Qwen3 MoE), or ``"default"`` for everything else (4.57.x).
     The 5.5.0 check runs first, then 5.3.0.
     """
     lowered = model_name.lower()
@@ -407,9 +398,9 @@ _PURGE_PREFIXES = (
     "accelerate",
     "auto_gptq",
     # NOTE: bitsandbytes is intentionally EXCLUDED — it registers torch custom
-    # operators at import time via torch.library.define(). Those registrations
-    # live in torch's global operator registry which survives module purge.
-    # Re-importing bitsandbytes after purge → duplicate registration → crash.
+    # operators at import via torch.library.define() into torch's global
+    # registry, which survives module purge. Re-importing it after purge →
+    # duplicate registration → crash.
     # Our own modules that import from transformers at module level
     # (e.g. model_config.py: `from transformers import AutoConfig`)
     "utils.models",
@@ -462,15 +453,15 @@ def _venv_dir_is_valid(venv_dir: str, packages: tuple[str, ...]) -> bool:
         pkg_name = parts[0]
         pkg_version = parts[1] if len(parts) > 1 else None
         pkg_name_norm = pkg_name.replace("-", "_")
-        # Check directory exists
+        # Directory must exist.
         if not any(
             (Path(venv_dir) / d).is_dir() for d in (pkg_name_norm, pkg_name_norm.replace("_", "-"))
         ):
             return False
-        # For unpinned packages, existence is enough
+        # Unpinned packages: existence is enough.
         if pkg_version is None:
             continue
-        # Check version via .dist-info metadata
+        # Check version via .dist-info metadata.
         dist_info_found = False
         for di in Path(venv_dir).glob(f"{pkg_name_norm}-*.dist-info"):
             metadata = di / "METADATA"
@@ -504,7 +495,7 @@ def _venv_t5_is_valid() -> bool:
 
 def _install_to_dir(pkg: str, target_dir: str) -> bool:
     """Install a single package into *target_dir*, preferring uv then pip."""
-    # Try uv first (faster) if already on PATH -- do NOT install uv at runtime
+    # Try uv first (faster) if on PATH -- do NOT install uv at runtime.
     if shutil.which("uv"):
         result = subprocess.run(
             [
@@ -529,7 +520,7 @@ def _install_to_dir(pkg: str, target_dir: str) -> bool:
             return True
         logger.warning("uv install of %s failed, falling back to pip", pkg)
 
-    # Fallback to pip
+    # Fallback to pip.
     result = subprocess.run(
         [
             sys.executable,
@@ -621,13 +612,13 @@ def ensure_transformers_version(model_name: str) -> None:
       • Need 5.3.0 → prepend .venv_t5_530/ to sys.path, purge modules.
       • Need 4.x  → remove all .venv_t5_*/ from sys.path, purge modules.
 
-    For LoRA adapters with custom names, the base model is resolved from
+    For custom-named LoRA adapters, the base model is resolved from
     ``adapter_config.json`` before checking.
 
-    NOTE: Training and inference use subprocess isolation instead of this
-    function. This is only used by the export path (routes/export.py).
+    NOTE: Training and inference use subprocess isolation instead. Used only by
+    the export path (routes/export.py).
     """
-    # Resolve LoRA adapters to their base model for accurate detection
+    # Resolve LoRA adapters to their base model for accurate detection.
     resolved = _resolve_base_model(model_name)
     tier = get_transformers_tier(resolved)
 
@@ -666,10 +657,10 @@ def ensure_transformers_version(model_name: str) -> None:
                 model_name,
             )
             return
-        # Different 5.x → need to switch (e.g. 5.3.0 loaded but need 5.5.0)
+        # Different 5.x → must switch (e.g. 5.3.0 loaded but need 5.5.0).
         in_memory_major = int(in_memory.split(".")[0])
         if in_memory_major == target_major and venv_dir is None:
-            # Both are default (4.x) — close enough
+            # Both are default (4.x) — close enough.
             logger.info(
                 "transformers %s already loaded — correct for '%s'",
                 in_memory,
@@ -679,7 +670,7 @@ def ensure_transformers_version(model_name: str) -> None:
 
     # --- Switch version -----------------------------------------------------
     if venv_dir is not None:
-        # First remove any other 5.x venv from sys.path
+        # First remove any other 5.x venv from sys.path.
         _deactivate_5x()
         if not ensure_fn():
             raise RuntimeError(
diff --git a/studio/backend/utils/update_status.py b/studio/backend/utils/update_status.py
index 9b71ff31a0..ad9dabcf36 100644
--- a/studio/backend/utils/update_status.py
+++ b/studio/backend/utils/update_status.py
@@ -3,9 +3,8 @@
 
 """Web update status helpers for browser-served Unsloth Studio.
 
-This module is intentionally side-effect light: no network work happens at
-import time or from /api/health. The PyPI check is lazy, cached, and only used
-for normal PyPI-managed installs.
+Side-effect light: no network work at import time or from /api/health.
+The PyPI check is lazy, cached, and only for PyPI-managed installs.
 """
 
 from __future__ import annotations
@@ -66,9 +65,9 @@ def reset_update_status_cache() -> None:
 def detect_install_source() -> str:
     """Return a coarse install source without exposing local paths.
 
-    Sources are intentionally conservative. PEP 610 local/vcs metadata wins.
-    Legacy source installs are treated as local only when package files resolve
-    outside site-packages/dist-packages and under a Git checkout.
+    Conservative: PEP 610 local/vcs metadata wins. Legacy source
+    installs count as local only when package files resolve outside
+    site-packages/dist-packages and under a Git checkout.
     """
     try:
         dist = distribution(PACKAGE_NAME)
diff --git a/studio/backend/utils/utils.py b/studio/backend/utils/utils.py
index 7a7774be40..c51fc267f2 100644
--- a/studio/backend/utils/utils.py
+++ b/studio/backend/utils/utils.py
@@ -77,14 +77,14 @@ def log_and_http_error(
 @contextmanager
 def without_hf_auth():
     """
-    Context manager to temporarily disable HuggingFace authentication.
+    Temporarily disable HuggingFace authentication.
 
     Usage:
         with without_hf_auth():
             # Code that should run without cached tokens
             model_info(model_name, token=None)
     """
-    # Save environment variables
+    # Save and clear env vars
     saved_env = {}
     env_vars = ["HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_HOME"]
     for var in env_vars:
@@ -92,11 +92,10 @@ def without_hf_auth():
             saved_env[var] = os.environ[var]
             del os.environ[var]
 
-    # Save disable flag
     saved_disable = os.environ.get("HF_HUB_DISABLE_IMPLICIT_TOKEN")
     os.environ["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "1"
 
-    # Move token files temporarily
+    # Move token files aside temporarily
     token_files = []
     token_locations = [
         Path.home() / ".cache" / "huggingface" / "token",
@@ -121,7 +120,7 @@ def without_hf_auth():
             except Exception as e:
                 logger.error(f"Failed to restore token {original}: {e}")
 
-        # Restore environment
+        # Restore env
         for var, value in saved_env.items():
             os.environ[var] = value
 
@@ -133,14 +132,11 @@ def without_hf_auth():
 
 def format_error_message(error: Exception, model_name: str) -> str:
     """
-    Format user-friendly error messages for common issues.
+    Format a user-friendly error message for common load issues.
 
     Args:
         error: The exception that occurred
         model_name: Name of the model being loaded
-
-    Returns:
-        User-friendly error string
     """
     error_str = str(error).lower()
     model_short = model_name.split("/")[-1] if "/" in model_name else model_name
@@ -171,5 +167,4 @@ def format_error_message(error: Exception, model_name: str) -> str:
         )
         return f"Not enough {device_label} memory to load '{model_short}'. Try a smaller model or free memory."
 
-    # Generic fallback
     return str(error)
diff --git a/studio/backend/utils/wheel_utils.py b/studio/backend/utils/wheel_utils.py
index cca30bfd44..59632963b7 100644
--- a/studio/backend/utils/wheel_utils.py
+++ b/studio/backend/utils/wheel_utils.py
@@ -27,12 +27,12 @@ def has_blackwell_gpu() -> bool:
     """Return True if any visible NVIDIA GPU has compute capability >= 10.0
     (Blackwell: sm_100, sm_120, sm_121, ...).
 
-    Dao-AILab does not publish prebuilt flash-attention wheels for these
-    architectures, and the older-arch wheels fail to load on Blackwell, so
-    callers use this gate to skip the flash-attn install/upgrade path.
+    Dao-AILab publishes no prebuilt flash-attention wheels for these archs,
+    and older-arch wheels fail to load on Blackwell, so callers use this gate
+    to skip the flash-attn install/upgrade path.
 
-    Result is cached for the process lifetime since GPU hardware does not
-    change. Tests that mock subprocess/nvidia-smi must call
+    Cached for the process lifetime since GPU hardware doesn't change. Tests
+    that mock subprocess/nvidia-smi must call
     ``has_blackwell_gpu.cache_clear()`` before each invocation.
     """
     exe = shutil.which("nvidia-smi")
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 09953843f0..80e5257c8d 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -89,9 +89,9 @@ def env_int(
     return value
 
 
-# Prefer "latest" over "master" -- "master" bypasses the prebuilt resolver
+# Prefer "latest" over "master": "master" bypasses the prebuilt resolver
 # (no matching GitHub release), forces a source build, and causes HTTP 422
-# errors. Only use "master" temporarily when the latest release is missing
+# errors. Use "master" only temporarily when the latest release lacks
 # support for a new model architecture.
 DEFAULT_LLAMA_TAG = os.environ.get("UNSLOTH_LLAMA_TAG", "latest")
 # Default published repo for prebuilt release resolution. Linux uses
@@ -113,21 +113,19 @@ LEMONADE_ROCM_RELEASES_API = f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}
 
 
 def _lemonade_release_api_for(llama_tag: str) -> str:
-    """Return the GitHub API URL for the lemonade release that matches a
-    requested llama.cpp tag.
+    """Return the GitHub API URL for the lemonade release matching a llama.cpp tag.
 
-    When llama_tag is unset or "latest", point at /releases/latest. When the
-    caller has pinned a specific tag (e.g. "b1260"), point at the same tag in
-    lemonade. Lemonade tracks `ggml-org/llama.cpp` build tags (e.g. "b1260")
-    but is NOT guaranteed to publish every upstream build -- lemonade may be
-    several builds behind ggml-org. Pinning to a specific tag that lemonade
-    skipped will produce a 404 and the caller falls through to the upstream
-    tarball; that is intentional so pinned installs stay reproducible.
-    Do NOT pass a `unslothai/llama.cpp` fork tag -- the fork uses its own
-    namespace and will always 404 against lemonade.
+    When llama_tag is unset or "latest", point at /releases/latest. When
+    pinned (e.g. "b1260"), point at the same tag in lemonade. Lemonade
+    tracks `ggml-org/llama.cpp` build tags but is NOT guaranteed to publish
+    every upstream build -- it may be several builds behind. Pinning a tag
+    lemonade skipped produces a 404 and the caller falls through to the
+    upstream tarball; intentional so pinned installs stay reproducible.
+    Do NOT pass a `unslothai/llama.cpp` fork tag -- the fork's namespace
+    always 404s against lemonade.
 
-    The tag is URL-encoded with `safe=""` so an unexpected slash / hash / query
-    character cannot reshape the URL.
+    The tag is URL-encoded with `safe=""` so a stray slash / hash / query
+    char cannot reshape the URL.
     """
     normalized = (llama_tag or "").strip()
     if not normalized or normalized.lower() == "latest":
@@ -162,25 +160,25 @@ DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS = env_int(
     2,
     minimum = 1,
 )
-# Deeper macOS-only walk-back: upstream can ship a run of prebuilts built for a
-# newer macOS than the host, only caught at validate time, so an older host must
-# skip the whole run. Free on new hosts (first plan validates, extras unused).
+# Deeper macOS-only walk-back: upstream can ship a run of prebuilts built for
+# a newer macOS than the host, caught only at validate time, so an older host
+# must skip the whole run. Free on new hosts (first plan validates).
 DEFAULT_MAX_MACOS_RELEASE_FALLBACKS = env_int(
     "UNSLOTH_LLAMA_MAX_MACOS_RELEASE_FALLBACKS",
     16,
     minimum = 1,
 )
 # Deterministic macOS pin. At b9428 ggml-org's macOS runner moved to macOS 26
-# (Tahoe), so b9428+ prebuilts only load on macOS 26+. b9415 is the last build
-# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on macOS 13.3/14/15/26.
+# (Tahoe), so b9428+ prebuilts load only on macOS 26+. b9415 is the last build
+# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on 13.3/14/15/26.
 _PINNED_MACOS_FALLBACK_TAG = "b9415"
 _PINNED_MACOS_LATEST_FLOOR = (26, 0)
 FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master")
 
 # sm_103 (B300 / GB300 Blackwell Ultra) is not built natively but runs on the
 # bundled base compute_100 PTX, which the driver JIT-compiles forward to sm_103.
-# It is listed in every bundle that ships the sm_100 build (the "newer" and
-# "portable" classes) so those hosts get a prebuilt instead of a source compile.
+# Listed in every bundle that ships the sm_100 build (the "newer" and
+# "portable" classes) so those hosts get a prebuilt, not a source compile.
 DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
     "cuda12-older": {
         "runtime_line": "cuda12",
@@ -234,18 +232,18 @@ DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
 
 # Lowest CUDA major we ship prebuilts for, and the highest major we probe for
 # installed runtime libraries. Detection and runtime-line derivation are
-# generated per major so a new toolkit (cuda14, ...) needs no code change while
-# llama.cpp keeps the cudart64_<major>.dll / libcudart.so.<major> naming.
+# generated per major so a new toolkit (cuda14, ...) needs no code change as
+# long as llama.cpp keeps the cudart64_<major>.dll / libcudart.so.<major> naming.
 _MIN_CUDA_MAJOR = 12
 _MAX_PROBE_CUDA_MAJOR = 19
 
 # Last ggml-org release whose Windows win-cuda-13 build is still sub-13.3
 # (cuda-13.1, b9360, 2026-05-27). Upstream bumped win-cuda-13 to 13.3 at b9365
 # and now ships only cuda-12.4 + cuda-13.3. cuda-12.4 predates Blackwell (ggml
-# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a 13.0/13.1/13.2
-# driver is gated off 13.3 and would drop to a CPU-only 12.4 build. b9360 is
-# immutable, so we pin its cuda-13.1 build (plus paired cudart) as a GPU
-# fallback for exactly those hosts. See unslothai/unsloth#5887.
+# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a
+# 13.0/13.1/13.2 driver is gated off 13.3 and would drop to CPU-only 12.4.
+# b9360 is immutable, so we pin its cuda-13.1 build (plus paired cudart) as a
+# GPU fallback for exactly those hosts. See unslothai/unsloth#5887.
 _PINNED_BLACKWELL_FALLBACK_TAG = "b9360"
 _PINNED_BLACKWELL_FALLBACK_RUNTIME = "13.1"
 # Floor at 13.0: b9360 ships native sm_120a SASS (no PTX/JIT) and a bundled
@@ -255,15 +253,15 @@ _PINNED_BLACKWELL_DRIVER_FLOOR = (13, 0)
 _BLACKWELL_MIN_SM = 120
 # ggml compiles Blackwell sm_120 only at toolkit >= 12.8, so an in-release
 # windows-cuda build at or above this already covers Blackwell and makes the
-# older pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
+# pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
 _BLACKWELL_MIN_TOOLKIT = (12, 8)
 _PINNED_BLACKWELL_LLAMA_SHA256 = "31ddb8b42d7ab4a47cab8c48c397519f580ca502df7e73f3ab396eacc16c8e8d"
 _PINNED_BLACKWELL_CUDART_SHA256 = "f96935e7e385e3b2d0189239077c10fe8fd7e95690fea4afec455b1b6c7e3f18"
 
 
 def _cuda_runtime_lines_for_major(major: int) -> list[str]:
-    """Runtime lines a driver of this CUDA major can use, newest major first
-    down to the minimum we ship. A driver runs its own major and any older one
+    """Runtime lines a driver of this CUDA major can use, newest first down to
+    the minimum we ship. A driver runs its own major and any older one
     (backward compatibility)."""
     return [f"cuda{m}" for m in range(major, _MIN_CUDA_MAJOR - 1, -1)]
 
@@ -272,7 +270,7 @@ def _resolve_linux_bundle_profile(bundle_profile: str) -> "dict[str, Any] | None
     """Profile (runtime line + sm coverage) for a linux-x64-cuda<major>-<class>
     bundle. Known majors use their published coverage; an unknown future major
     reuses the newest known major's coverage for the same class as a forward
-    default, with the post-build GPU smoke test as the backstop."""
+    default, with the post-build GPU smoke test as backstop."""
     known = DIRECT_LINUX_BUNDLE_PROFILES.get(bundle_profile)
     if known is not None:
         return known
@@ -325,8 +323,8 @@ class AssetChoice:
     url: str
     source_label: str
     # Paired runtime archive (Windows CUDA cudart bundle). When set,
-    # install_from_archives also downloads it and overlays its DLLs on
-    # top of the main install. See unslothai/unsloth#5106.
+    # install_from_archives also downloads it and overlays its DLLs on top
+    # of the main install. See unslothai/unsloth#5106.
     runtime_name: str | None = None
     runtime_url: str | None = None
     runtime_sha256: str | None = None
@@ -553,14 +551,13 @@ def is_github_api_url(url: str | None) -> bool:
 
 def is_retryable_url_error(exc: Exception) -> bool:
     if isinstance(exc, urllib.error.HTTPError):
-        # GitHub returns 403 (not the standard 429) when the API rate
-        # limit is hit. Anonymous calls share a 60-req/hour bucket per
-        # runner IP, which CI fleets can exhaust trivially. Treat 403
-        # against api.github.com as retryable so we get one or two
-        # backoff cycles before the source-build fallback fires; honour
-        # Retry-After / X-RateLimit-Reset in sleep_backoff for accurate
-        # waits. Real 403s on other hosts (private artefact downloads,
-        # auth failures) stay non-retryable.
+        # GitHub returns 403 (not 429) when the API rate limit is hit.
+        # Anonymous calls share a 60-req/hour bucket per runner IP, which
+        # CI fleets exhaust trivially. Treat 403 against api.github.com as
+        # retryable so we get a backoff cycle or two before the source-build
+        # fallback fires; sleep_backoff honours Retry-After /
+        # X-RateLimit-Reset for accurate waits. Real 403s on other hosts
+        # (private artefact downloads, auth failures) stay non-retryable.
         if exc.code == 403:
             return is_github_api_url(getattr(exc, "url", None))
         return exc.code in RETRYABLE_HTTP_STATUS
@@ -579,9 +576,9 @@ _RATE_LIMIT_WAIT_CAP_SECONDS = 60.0
 def _http_error_retry_delay(exc: Exception) -> float | None:
     """Extract a recommended wait from rate-limit headers on a 403/429.
 
-    Returns None when no header is present or the indicated wait is
-    longer than _RATE_LIMIT_WAIT_CAP_SECONDS (in which case the caller
-    should not block on it -- the source-build fallback is faster).
+    Returns None when no header is present or the wait exceeds
+    _RATE_LIMIT_WAIT_CAP_SECONDS (the caller should not block then -- the
+    source-build fallback is faster).
     """
     if not isinstance(exc, urllib.error.HTTPError):
         return None
@@ -790,12 +787,12 @@ def refs_match(candidate_ref: str | None, requested_ref: str | None) -> bool:
 
 
 def checkout_friendly_ref(ref_kind: str | None, ref: str | None) -> str | None:
-    """Normalize a source ref to a form that ``git clone --branch`` accepts.
+    """Normalize a source ref to a form ``git clone --branch`` accepts.
 
-    Fully qualified branch refs like ``refs/heads/main`` are stripped to
-    ``main``; tag refs like ``refs/tags/b8508`` are stripped to ``b8508``.
-    Pull refs like ``refs/pull/123/head`` are left as-is since they are
-    always fetched explicitly rather than cloned with ``--branch``.
+    Fully qualified branch refs (``refs/heads/main``) are stripped to
+    ``main``; tag refs (``refs/tags/b8508``) to ``b8508``. Pull refs
+    (``refs/pull/123/head``) are left as-is since they are fetched
+    explicitly rather than cloned with ``--branch``.
     """
     if not isinstance(ref, str) or not ref:
         return ref
@@ -845,8 +842,8 @@ def _published_windows_cuda_runtime(
     """Highest cuda-<major>.<minor> published upstream that `driver` can run by
     default CUDA compatibility, i.e. (major, minor) <= driver. None if nothing
     qualifies. Gating on the driver (not just the major) keeps a 13.3 build off
-    a driver that only advertises 13.1, where it would otherwise rely on the
-    unguaranteed minor-version-compatibility path."""
+    a 13.1-only driver, where it would rely on the unguaranteed
+    minor-version-compatibility path."""
     if driver is None:
         return None
     best: int | None = None
@@ -1361,8 +1358,8 @@ def direct_linux_release_plan(
     attempts: list[AssetChoice] = []
     if host.has_usable_nvidia:
         # Prefer the cudart major Studio loads at runtime (torch's bundled
-        # libcudart), not the newest detected on disk. Without this a stray
-        # cuda13 runtime outranks the torch cuda12 the binary links against.
+        # libcudart), not the newest on disk. Otherwise a stray cuda13
+        # runtime outranks the torch cuda12 the binary links against.
         torch_preference = detect_torch_cuda_runtime_preference(host)
         selection = linux_cuda_choice_from_release(
             host,
@@ -1375,14 +1372,13 @@ def direct_linux_release_plan(
     if host.has_rocm and not host.has_usable_nvidia:
         # Per-GPU lemonade prebuilts ship the ROCm runtime libs alongside
         # llama.cpp, so they install cleanly even on hosts (e.g. gfx1151
-        # Strix Halo) that the upstream combined-ROCm tarball doesn't cover.
-        # The "ubuntu" label is lemonade's asset naming convention only --
-        # the binary is a manylinux-style glibc build that runs on Arch,
-        # Fedora, openSUSE, etc. as long as the host glibc is recent enough.
-        # Do NOT append the CPU asset for ROCm-only hosts: if lemonade fails
-        # validation we want validate_prebuilt_attempts to raise PrebuiltFallback
-        # so the caller triggers the HIP source build, not silently install a
-        # CPU-only binary.
+        # Strix Halo) the upstream combined-ROCm tarball doesn't cover.
+        # "ubuntu" is lemonade's asset naming convention only -- the binary
+        # is a manylinux-style glibc build that runs on Arch, Fedora,
+        # openSUSE, etc. with a recent-enough glibc. Do NOT append the CPU
+        # asset for ROCm-only hosts: if lemonade fails validation we want
+        # validate_prebuilt_attempts to raise PrebuiltFallback so the caller
+        # triggers the HIP source build, not silently install a CPU binary.
         lemonade_choice = resolve_lemonade_rocm_choice(
             host, "ubuntu", "linux-rocm", llama_tag = requested_tag
         )
@@ -1405,9 +1401,9 @@ def direct_linux_release_plan(
     ):
         approved_checksums = load_approved_release_checksums(repo, bundle.release_tag)
         # Require exact source provenance for branch/pull/commit releases.
-        # Mirrors validated_checksums_for_bundle so incomplete metadata
-        # fails closed instead of degrading to the legacy branch-as-tag
-        # source hydration path that this PR is meant to eliminate.
+        # Mirrors validated_checksums_for_bundle so incomplete metadata fails
+        # closed instead of degrading to the legacy branch-as-tag source
+        # hydration path this PR eliminates.
         if (
             not approved_checksums.source_commit
             or exact_source_archive_hash(approved_checksums) is None
@@ -1455,7 +1451,7 @@ def direct_upstream_release_plan(
                 )
             )
             # Blackwell on a 13.1/13.2 driver: prefer the pinned cuda-13.1 GPU
-            # build over the CPU-only cuda-12.4 the in-release gating leaves.
+            # build over the CPU-only cuda-12.4 left by in-release gating.
             pinned = _pinned_windows_cuda_fallback(host, attempts)
             if pinned is not None:
                 attempts.insert(0, pinned)
@@ -1493,9 +1489,9 @@ def direct_upstream_release_plan(
             )
     elif host.is_windows and host.is_arm64:
         # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-win-cpu-arm64.zip
-        # (visible in the b9334 release manifest). Without this branch the
-        # selector returned 0 attempts and the installer fell back to a
-        # source build on every Windows ARM64 host.
+        # (in the b9334 release manifest). Without this branch the selector
+        # returned 0 attempts and fell back to a source build on every
+        # Windows ARM64 host.
         cpu_asset = f"llama-{release_tag}-bin-win-cpu-arm64.zip"
         cpu_url = assets.get(cpu_asset)
         if cpu_url:
@@ -1553,10 +1549,10 @@ def direct_upstream_release_plan(
             )
     elif host.is_linux and host.is_arm64 and not host.has_usable_nvidia:
         # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-ubuntu-arm64.tar.gz
-        # (visible in the b9334 release manifest). Without this branch the
-        # selector returned 0 attempts and the installer fell back to a
-        # source build on every Linux ARM64 host (DGX Spark, Ampere
-        # Altra, GitHub-hosted ubuntu-24.04-arm runners, etc.).
+        # (in the b9334 release manifest). Without this branch the selector
+        # returned 0 attempts and fell back to a source build on every Linux
+        # ARM64 host (DGX Spark, Ampere Altra, GitHub ubuntu-24.04-arm
+        # runners, etc.).
         asset_name = f"llama-{release_tag}-bin-ubuntu-arm64.tar.gz"
         asset_url = assets.get(asset_name)
         if asset_url:
@@ -1586,9 +1582,9 @@ def direct_upstream_release_plan(
 
 
 def pinned_macos_release_tag(host: HostInfo, repo: str) -> str | None:
-    """Pin b9415 (the last upstream macOS build that loads below macOS 26) for a
-    known pre-26 host on ggml-org upstream; return None to keep latest selection.
-    The unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64
+    """Pin b9415 (last upstream macOS build that loads below macOS 26) for a
+    known pre-26 host on ggml-org upstream; None keeps latest selection. The
+    unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64
     minos 13.3) and needs no pin, so this is a no-op there and for macOS 26+,
     unknown version, non-macOS."""
     if repo != UPSTREAM_REPO:
@@ -1614,9 +1610,9 @@ def resolve_simple_install_release_plans(
     repo = published_repo or DEFAULT_PUBLISHED_REPO
     requested_tag = normalized_requested_llama_tag(llama_tag)
     # The unslothai/llama.cpp fork ships only linux-x64 bundles. An arm64 Linux
-    # host with a GPU (GH200/GB200/DGX Spark) routes here; it must not install an
-    # x64 binary, so fall back to a source build that targets the GPU rather than
-    # selecting the wrong arch (or silently dropping to a CPU arm64 build).
+    # host with a GPU (GH200/GB200/DGX Spark) routes here; it must not install
+    # an x64 binary, so fall back to a GPU-targeting source build rather than
+    # the wrong arch (or silently dropping to a CPU arm64 build).
     if host.is_linux and not host.is_x86_64 and repo == DEFAULT_PUBLISHED_REPO:
         raise PrebuiltFallback(
             f"{repo} ships only linux-x64 prebuilts; "
@@ -1625,7 +1621,7 @@ def resolve_simple_install_release_plans(
     allow_older_release_fallback = requested_tag == "latest" and not published_release_tag
     # macOS: pin the last upstream build that loads on a pre-26 host instead of
     # fetching the latest (macOS 26 only) build and walking back release by
-    # release. No-op on macOS 26+, unknown version, non-macOS, and the fork.
+    # release. No-op on macOS 26+, unknown version, non-macOS, the fork.
     if allow_older_release_fallback:
         pinned_macos = pinned_macos_release_tag(host, repo)
         if pinned_macos is not None:
@@ -1940,8 +1936,8 @@ def parse_published_release_bundle(
     if not manifest_url:
         return None
 
-    # Mixed repos are filtered by an explicit release-side manifest rather than
-    # by release tag or asset filename conventions.
+    # Mixed repos are filtered by an explicit release-side manifest, not by
+    # release tag or asset filename conventions.
     manifest_bytes = download_bytes(
         manifest_url,
         timeout = 30,
@@ -2393,9 +2389,9 @@ def validated_checksums_for_bundle(
             raise PrebuiltFallback(
                 "published manifest checksum did not match the approved checksum asset"
             )
-    # Accept bundles that carry only an exact-commit source archive
-    # (e.g. llama.cpp-source-commit-<sha>.tar.gz) without requiring the
-    # legacy llama.cpp-source-<upstream_tag>.tar.gz entry.
+    # Accept bundles carrying only an exact-commit source archive
+    # (llama.cpp-source-commit-<sha>.tar.gz) without requiring the legacy
+    # llama.cpp-source-<upstream_tag>.tar.gz entry.
     if exact_source_archive_hash(checksums) is None:
         require_approved_source_hash(checksums, bundle.upstream_tag)
     return checksums
@@ -2531,23 +2527,22 @@ def resolve_requested_llama_tag(
 
     Resolution order:
       1. Concrete tag (e.g. "b8508") -- returned as-is.
-      2. "latest" with published_repo -- resolve the latest usable Unsloth
-         published release bundle and return its upstream_tag. This is the
-         preferred version that matches the published prebuilt metadata.
-      3. "latest" without published_repo or if (2) fails -- query the upstream
-         ggml-org/llama.cpp repo. This may return a newer, untested tag.
+      2. "latest" with published_repo -- the latest usable Unsloth published
+         bundle's upstream_tag (matches the published prebuilt metadata).
+      3. "latest" without published_repo, or if (2) fails -- query upstream
+         ggml-org/llama.cpp. May return a newer, untested tag.
 
-    The Unsloth repo is preferred because its releases are pinned to specific
-    upstream tags that have been validated with Unsloth Studio. Using the
-    upstream bleeding-edge tag risks API/ABI incompatibilities.
+    The Unsloth repo is preferred because its releases are pinned to upstream
+    tags validated with Unsloth Studio; the upstream bleeding-edge tag risks
+    API/ABI incompatibilities.
     """
     normalized_requested = normalized_requested_llama_tag(requested_tag)
     if normalized_requested != "latest":
         return normalized_requested
     # Prefer the Unsloth release repo tag (tested/approved) over bleeding-edge
-    # upstream. For example, unslothai/llama.cpp may publish b8508 while
-    # ggml-org/llama.cpp latest is b8514. The source-build fallback should
-    # compile the same version the prebuilt path would have installed.
+    # upstream. E.g. unslothai/llama.cpp may publish b8508 while ggml-org
+    # latest is b8514. The source-build fallback should compile the same
+    # version the prebuilt path would have installed.
     if published_repo:
         try:
             return resolve_published_release(
@@ -2557,7 +2552,7 @@ def resolve_requested_llama_tag(
             ).bundle.upstream_tag
         except Exception:
             pass
-    # Fall back to upstream ggml-org latest release tag
+    # Fall back to the upstream ggml-org latest release tag
     return latest_upstream_release_tag()
 
 
@@ -2704,38 +2699,38 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
     A bare first-match picked the wrong device on mixed APU + dGPU hosts
     (e.g. Strix Halo gfx1151 + discrete RX 7900 gfx1100). Respect
     HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES / CUDA_VISIBLE_DEVICES so the
-    asset matches what HIP actually runs on. Falls back to the first GPU when
-    no env var is set.
+    asset matches what HIP runs on; falls back to the first GPU with no env
+    var set.
 
     rocminfo / hipinfo print the same gfx token multiple times per GPU (Name,
-    ISA, marketing-name). We first try to split the output on per-GPU section
-    headers (rocminfo: "Agent N" blocks, hipinfo: "device#N" entries) and take
-    exactly one gfx token per section. This gives the correct per-GPU list even
-    on same-arch multi-GPU hosts (e.g. two RX 7900 XTX cards) where global
-    dict.fromkeys dedup would collapse both cards to a single entry and make
-    HIP_VISIBLE_DEVICES=1 point out of range.
+    ISA, marketing-name). We first split the output on per-GPU section headers
+    (rocminfo: "Agent N" blocks, hipinfo: "device#N" entries) and take exactly
+    one gfx token per section -- this gives the correct per-GPU list even on
+    same-arch multi-GPU hosts (e.g. two RX 7900 XTX) where global dict.fromkeys
+    dedup would collapse both to one entry and make HIP_VISIBLE_DEVICES=1 point
+    out of range.
 
     Falls back to insertion-order dedup when the output has no recognisable
     section markers (flat gfx-string inputs, unit-test stubs, etc.).
 
     Empty / "-1" env values mean no AMD GPU is visible to HIP: return None.
     """
-    # Try to build a per-GPU token list by splitting on section boundaries.
-    # rocminfo sections are introduced by "Agent N" lines (optionally between
-    # rows of asterisks). hipinfo sections start with "device#N".
+    # Build a per-GPU token list by splitting on section boundaries. rocminfo
+    # sections start with "Agent N" lines (optionally between rows of
+    # asterisks); hipinfo sections with "device#N".
     _sections = re.split(
         r"(?mi)^\s*\*+\s*$\s*agent\s+\d+\s*$|\bdevice\s*#\s*\d+\b",
         out,
     )
     if len(_sections) > 1:
-        # Section-based: one gfx token per GPU section preserves physical order.
+        # One gfx token per GPU section preserves physical order.
         _tokens: list[str] = []
         for _sec in _sections[1:]:
             _m = re.search(r"gfx[1-9][0-9a-z]{2,3}", _sec.lower())
             if _m:
                 _tokens.append(_m.group(0))
     else:
-        # Fallback: insertion-order dedup (handles flat strings / unknown formats).
+        # Fallback: insertion-order dedup (flat strings / unknown formats).
         _raw = re.findall(r"gfx[1-9][0-9a-z]{2,3}", out.lower())
         _tokens = list(dict.fromkeys(_raw))
 
@@ -2751,7 +2746,7 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
             break
     if _vis_raw is not None:
         _vis = _vis_raw.strip()
-        # Empty or "-1" means "no AMD GPU visible" (matches the rest of Studio).
+        # Empty or "-1" means "no AMD GPU visible" (matches the rest of Studio)
         if _vis == "" or _vis == "-1":
             return None
         _first = _vis.split(",")[0].strip()
@@ -2783,11 +2778,10 @@ def detect_host() -> HostInfo:
     has_physical_nvidia = False
     has_usable_nvidia = False
     if nvidia_smi:
-        # Require `nvidia-smi -L` to actually list a GPU before treating the
-        # host as NVIDIA. The banner text "NVIDIA-SMI ..." is printed even
-        # when the command fails to communicate with the driver (e.g. stale
-        # container leftovers), which would otherwise misclassify an AMD
-        # ROCm host as NVIDIA and short-circuit the ROCm path.
+        # Require `nvidia-smi -L` to list a GPU before treating the host as
+        # NVIDIA. The "NVIDIA-SMI ..." banner prints even when the command
+        # can't reach the driver (e.g. stale container leftovers), which
+        # would misclassify an AMD ROCm host as NVIDIA and skip the ROCm path.
         try:
             listing = run_capture([nvidia_smi, "-L"], timeout = 20)
             gpu_lines = [line for line in listing.stdout.splitlines() if line.startswith("GPU ")]
@@ -2800,9 +2794,9 @@ def detect_host() -> HostInfo:
         try:
             result = run_capture([nvidia_smi], timeout = 20)
             merged = "\n".join(part for part in (result.stdout, result.stderr) if part)
-            # Newer NVIDIA drivers (e.g. 610.x on Windows) print
-            # "CUDA UMD Version: X.Y" instead of the legacy
-            # "CUDA Version: X.Y"; accept both spellings.
+            # Newer NVIDIA drivers (e.g. 610.x on Windows) print "CUDA UMD
+            # Version: X.Y" instead of the legacy "CUDA Version: X.Y"; accept
+            # both spellings.
             cuda_match = re.search(
                 r"CUDA(?: UMD)? Version:\s*(\d+)\.(\d+)",
                 merged,
@@ -2845,10 +2839,10 @@ def detect_host() -> HostInfo:
 
             if visible_gpu_rows:
                 has_usable_nvidia = True
-                # Older nvidia-smi versions (pre -L support) hit the
-                # except in the first try block but still succeed here,
-                # leaving has_physical_nvidia unset. Mirror the -L path
-                # so downstream diagnostics on line ~4390 still run.
+                # Older nvidia-smi (pre -L support) hits the except in the
+                # first try block but still succeeds here, leaving
+                # has_physical_nvidia unset. Mirror the -L path so downstream
+                # diagnostics on line ~4390 still run.
                 if not has_physical_nvidia:
                     has_physical_nvidia = True
             elif visible_device_tokens == []:
@@ -2870,10 +2864,10 @@ def detect_host() -> HostInfo:
     rocm_gfx_target: str | None = None
     if is_linux:
         for _cmd, _check in (
-            # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
-            # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines like
-            # "gfx11-generic" or "gfx9-4-generic" which only have 1-2 digits before
-            # the dash and must not be treated as a real GPU.
+            # rocminfo: a real gfx GPU id (3-4 chars, nonzero first digit).
+            # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines
+            # ("gfx11-generic", "gfx9-4-generic") with only 1-2 digits before
+            # the dash, which must not be treated as a real GPU.
             (
                 ["rocminfo"],
                 lambda out: bool(re.search(r"gfx[1-9][0-9a-z]{2,3}", out.lower())),
@@ -2893,14 +2887,13 @@ def detect_host() -> HostInfo:
                     rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
     elif is_windows:
-        # Windows: prefer active probes that validate GPU presence.
-        # hipinfo / amd-smi are often NOT on PATH -- the HIP SDK installer
-        # sets HIP_PATH / ROCM_PATH but does not always add the bin dir to
-        # the system PATH.  Mirror setup.ps1's fallback: check the env-var
-        # bin dirs before giving up so that `has_rocm` is not silently False
-        # on machines where the PATH is not yet updated.
+        # Windows: prefer active probes that validate GPU presence. hipinfo /
+        # amd-smi are often NOT on PATH -- the HIP SDK installer sets HIP_PATH
+        # / ROCM_PATH but doesn't always add the bin dir to PATH. Mirror
+        # setup.ps1's fallback: check the env-var bin dirs before giving up so
+        # `has_rocm` isn't silently False when PATH isn't updated yet.
         def _resolve_exe(name: str) -> str | None:
-            """Return full path to `name`, checking PATH then HIP_PATH/ROCM_PATH bin."""
+            """Full path to `name`, checking PATH then HIP_PATH/ROCM_PATH bin."""
             found = shutil.which(name)
             if found:
                 return found
@@ -2929,8 +2922,8 @@ def detect_host() -> HostInfo:
                     # hipinfo reports "gcnArchName: gfx1100" -- extract if present
                     rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
-        # Note: amdhip64.dll presence alone is NOT treated as GPU evidence
-        # since the HIP SDK can be installed without an AMD GPU.
+        # Note: amdhip64.dll presence alone is NOT GPU evidence -- the HIP SDK
+        # can be installed without an AMD GPU.
 
     return HostInfo(
         system = system,
@@ -2955,7 +2948,7 @@ def detect_host() -> HostInfo:
 def _normalize_forwarded_gfx(value: str | None) -> str | None:
     """Extract a single gfx token from a forwarded --rocm-gfx / env value.
     setup.sh/setup.ps1 already picked the active GPU, so take the token as-is
-    without re-applying visible-device selection. Ignore anything malformed."""
+    without re-applying visible-device selection. Ignore malformed input."""
     if not value:
         return None
     m = re.search(r"gfx[1-9][0-9a-z]{2,3}", value.lower())
@@ -2971,8 +2964,8 @@ def _apply_host_overrides(
 ) -> HostInfo:
     """Fold setup.sh/setup.ps1's forwarded detection into the host profile.
     A forwarded gfx (--rocm-gfx or UNSLOTH_ROCM_GFX_ARCH) is authoritative and
-    implies ROCm: the installer's own hipinfo/amd-smi probe can miss the arch on
-    amd-smi-only hosts or when setup inferred it from the GPU name, leaving
+    implies ROCm: the installer's own hipinfo/amd-smi probe can miss the arch
+    on amd-smi-only hosts or when setup inferred it from the GPU name, leaving
     rocm_gfx_target None and no lemonade prebuilt selected. force_cpu is the
     opposite explicit signal (arm64 Linux GPU host whose source build failed):
     drop GPU attributes so the CPU prebuilt for this OS/arch is selected."""
@@ -3014,7 +3007,7 @@ def compatible_linux_runtime_lines(host: HostInfo) -> list[str]:
 
 def windows_runtime_line_info() -> dict[str, tuple[str, ...]]:
     # Generated per CUDA major (newest first) so a new toolkit is detected
-    # without a code change while the cudart64_<major>.dll naming holds.
+    # without code changes while the cudart64_<major>.dll naming holds.
     return {
         f"cuda{m}": (
             f"cudart64_{m}*.dll",
@@ -3041,7 +3034,7 @@ def compatible_windows_runtime_lines(host: HostInfo) -> list[str]:
     if not host.driver_cuda_version:
         return []
     major, minor = host.driver_cuda_version
-    # cuda12 prebuilts need a 12.4+ driver; cuda13+ any minor of the major.
+    # cuda12 prebuilts need a 12.4+ driver; cuda13+ any minor.
     if major < _MIN_CUDA_MAJOR or (major == _MIN_CUDA_MAJOR and minor < 4):
         return []
     return _cuda_runtime_lines_for_major(major)
@@ -3181,8 +3174,8 @@ def windows_cuda_attempts(
     runtime_order.extend(
         runtime_line for runtime_line in normal_runtime_lines if runtime_line not in runtime_order
     )
-    # Keep every driver-compatible line reachable as a fallback, so a line gated
-    # out by the driver version still drops to an older major (cuda13 -> cuda12).
+    # Keep every driver-compatible line reachable as a fallback, so a line
+    # gated out by driver version still drops to an older major (cuda13->cuda12).
     runtime_order.extend(
         runtime_line
         for runtime_line in compatible_runtime_lines
@@ -3201,7 +3194,7 @@ def windows_cuda_attempts(
     for runtime_line in runtime_order:
         major = int(runtime_line.removeprefix("cuda"))
         # Track whatever minor llama.cpp actually ships for this major
-        # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release has no
+        # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release lacks a
         # matching asset instead of guessing a now-missing name.
         runtime = _published_windows_cuda_runtime(upstream_assets, major, host.driver_cuda_version)
         if runtime is None:
@@ -3222,10 +3215,10 @@ def windows_cuda_attempts(
                 + ",".join(windows_cuda_upstream_asset_names(llama_tag, runtime))
             )
             continue
-        # Pair the cudart bundle when upstream ships it. Without this
-        # the binary needs a system CUDA toolkit on PATH at runtime
-        # (#5106). Only pair when the selected main archive is the
-        # binary archive, not the cudart archive itself.
+        # Pair the cudart bundle when upstream ships it; otherwise the binary
+        # needs a system CUDA toolkit on PATH at runtime (#5106). Only pair
+        # when the selected main archive is the binary archive, not the cudart
+        # archive itself.
         runtime_archive_name: str | None = None
         runtime_archive_url: str | None = None
         if selected_name.startswith("llama-"):
@@ -3264,8 +3257,8 @@ def windows_cuda_attempts(
 
 
 def _windows_cuda_attempt_covers_blackwell(attempt: AssetChoice) -> bool:
-    """True if an in-release windows-cuda attempt is built with a toolkit that
-    covers Blackwell sm_120 (>= 12.8), read from its asset name's CUDA minor."""
+    """True if an in-release windows-cuda attempt's toolkit covers Blackwell
+    sm_120 (>= 12.8), read from its asset name's CUDA minor."""
     if attempt.install_kind != "windows-cuda":
         return False
     m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
@@ -3276,16 +3269,16 @@ def _pinned_windows_cuda_fallback(
     host: HostInfo, existing_cuda_attempts: list[AssetChoice]
 ) -> AssetChoice | None:
     """Pinned GPU fallback for a Blackwell host the in-release build gates off.
-    Upstream stopped publishing a sub-13.3 Windows cuda13 build after b9360, and
-    cuda-12.4 cannot offload sm_120, so a 13.1/13.2 driver would land on CPU.
-    b9360's cuda-13.1 build is immutable and runs on those drivers. Returns None
-    (dormant) whenever the in-release selection already offers a Blackwell-capable
-    build (toolkit >= 12.8, e.g. a runnable cuda13/cuda14), so it self-disables
-    once upstream ships a driver-runnable build again.
+    Upstream stopped publishing a sub-13.3 Windows cuda13 build after b9360,
+    and cuda-12.4 cannot offload sm_120, so a 13.1/13.2 driver would land on
+    CPU. b9360's cuda-13.1 build is immutable and runs on those drivers.
+    Returns None (dormant) whenever the in-release selection already offers a
+    Blackwell-capable build (toolkit >= 12.8, e.g. a runnable cuda13/cuda14),
+    so it self-disables once upstream ships a driver-runnable build again.
 
-    The b9360 binary reuses the current release's source tree and convert scripts
-    and is recorded via binary_release_tag, the same binary/source split used for
-    the lemonade prebuilt."""
+    The b9360 binary reuses the current release's source tree and convert
+    scripts and is recorded via binary_release_tag, the same binary/source
+    split used for the lemonade prebuilt."""
     if not (host.is_windows and host.is_x86_64 and host.has_usable_nvidia):
         return None
     driver = host.driver_cuda_version
@@ -3327,8 +3320,8 @@ def _pinned_windows_cuda_fallback(
 def _augment_checksums_with_pin(
     checksums: ApprovedReleaseChecksums, pin: AssetChoice
 ) -> ApprovedReleaseChecksums:
-    """Add the pin's own verified hashes to a copy of the approved checksums so
-    apply_approved_hashes keeps it on the published path (b9360 is not in the
+    """Add the pin's verified hashes to a copy of the approved checksums so
+    apply_approved_hashes keeps it on the published path (b9360 isn't in the
     release manifest)."""
     artifacts = dict(checksums.artifacts)
     if pin.expected_sha256:
@@ -3352,7 +3345,7 @@ def _with_pinned_windows_cuda_fallback(
     host: HostInfo, attempts: list[AssetChoice], checksums: ApprovedReleaseChecksums
 ) -> tuple[list[AssetChoice], ApprovedReleaseChecksums]:
     """Insert the Blackwell pin ahead of the Windows CUDA attempts and keep it
-    through apply_approved_hashes, or return the inputs unchanged when dormant.
+    through apply_approved_hashes, or return inputs unchanged when dormant.
     Gives the published install path the same GPU fallback as the simple path."""
     pin = _pinned_windows_cuda_fallback(host, attempts)
     if pin is None:
@@ -3369,7 +3362,7 @@ def published_windows_cuda_attempts(
     selection_log = list(release.selection_log) + list(selection_preamble)
     # Seed the runtime-line ordering from the real published windows-cuda minors
     # (their names encode the minor), so a future CUDA major published here is
-    # ordered too instead of a hardcoded cuda12/cuda13 pair. Keys mirror the
+    # ordered too rather than a hardcoded cuda12/cuda13 pair. Keys mirror the
     # upstream naming so windows_cuda_attempts can match them; fall back to the
     # long-standing default when the release lists no windows-cuda asset.
     published_minors: list[str] = []
@@ -3414,8 +3407,8 @@ def published_windows_cuda_attempts(
             if not asset_url:
                 continue
             am = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", artifact.asset_name)
-            # Gate the real published minor against the driver, so a published
-            # windows-cuda artifact can never bypass the driver-version gate.
+            # Gate the published minor against the driver so it can never
+            # bypass the driver-version gate.
             if (
                 am is not None
                 and host.driver_cuda_version is not None
@@ -3516,9 +3509,9 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
     """Return (major, minor) of the installed ROCm runtime, or None.
 
     Best-effort read from /opt/rocm/.info/version, amd-smi version, and
-    hipconfig --version. Used to pick a compatible upstream llama.cpp
-    ROCm prebuilt rather than always taking the numerically newest one
-    (which can be newer than the host runtime).
+    hipconfig --version. Used to pick a compatible upstream llama.cpp ROCm
+    prebuilt rather than the numerically newest one (which can be newer than
+    the host runtime).
     """
     rocm_root = os.environ.get("ROCM_PATH") or "/opt/rocm"
     for path in (
@@ -3528,9 +3521,9 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
         try:
             with open(path) as fh:
                 parts = fh.read().strip().split("-")[0].split(".")
-            # Explicit length guard avoids relying on the broad except
-            # below to swallow IndexError when the version file contains
-            # a single component (e.g. "6\n" on a partial install).
+            # Explicit length guard so we don't rely on the broad except
+            # below to swallow IndexError when the version file has a single
+            # component (e.g. "6\n" on a partial install).
             if len(parts) >= 2:
                 return int(parts[0]), int(parts[1])
         except Exception:
@@ -3571,8 +3564,8 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
 
     # Distro package-manager fallbacks. Mirrors install.sh::get_torch_index_url
     # and _detect_rocm_version() in install_python_stack.py so package-managed
-    # ROCm hosts without /opt/rocm/.info/version still report a usable version
-    # and the <= host version filter in resolve_upstream_asset_choice picks
+    # ROCm hosts without /opt/rocm/.info/version still report a usable version,
+    # letting the <= host version filter in resolve_upstream_asset_choice pick
     # the correct upstream prebuilt instead of the newest-regardless fallback.
     for _cmd in (
         ["dpkg-query", "-W", "-f=${Version}\n", "rocm-core"],
@@ -3594,7 +3587,7 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
         if _result.returncode != 0 or not _result.stdout.strip():
             continue
         _raw = _result.stdout.strip()
-        # dpkg can prepend an epoch ("1:6.3.0-1"); strip it before parsing.
+        # dpkg can prepend an epoch ("1:6.3.0-1"); strip it first.
         _raw = re.sub(r"^\d+:", "", _raw)
         _m = re.match(r"(\d+)[.-](\d+)", _raw)
         if _m:
@@ -3603,7 +3596,7 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
 
 
 # Map detected gfx IDs to lemonade-sdk asset family suffixes.
-# More-specific prefixes must come before shorter ones (e.g. gfx1151 before gfx110).
+# More-specific prefixes must precede shorter ones (e.g. gfx1151 before gfx110).
 _LEMONADE_GFX_FAMILIES: list[tuple[str, str]] = [
     ("gfx1151", "gfx1151"),
     ("gfx1150", "gfx1150"),
@@ -3627,9 +3620,8 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
     Accepts:
       https://github.com/{expected_repo}/releases/download/...
       https://objects.githubusercontent.com/...   (GitHub's release CDN)
-    Anything else (including http://, raw.githubusercontent.com, gist, etc.)
-    is rejected so a malicious API response cannot redirect downloads to an
-    attacker-chosen host.
+    Anything else (http://, raw.githubusercontent.com, gist, etc.) is rejected
+    so a malicious API response can't redirect downloads to an attacker host.
     """
     if not isinstance(url, str) or not url:
         return False
@@ -3642,8 +3634,8 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
     host = (parsed.netloc or "").lower()
     if host == "objects.githubusercontent.com":
         # GitHub's release CDN. Restrict to release-asset paths so a tampered
-        # API response pointing at an arbitrary CDN object is still rejected.
-        # Real release asset URLs carry the "/github-production-release-asset-"
+        # API response pointing at an arbitrary CDN object is rejected. Real
+        # release asset URLs carry the "/github-production-release-asset-"
         # prefix; gist / raw / avatar CDN paths do not.
         return parsed.path.startswith("/github-production-release-asset-")
     if host == "github.com":
@@ -3655,12 +3647,12 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
 def _fetch_lemonade_release_cached(api_url: str, llama_tag: str) -> "dict | None":
     """Cached wrapper around fetch_json for lemonade release lookups.
 
-    resolve_lemonade_rocm_choice() is called twice per install (once from the
-    direct planner, once from resolve_upstream_asset_choice) with identical
-    arguments. Without memoisation, each install hits api.github.com twice,
-    doubling the rate-limit failure surface on busy CI runners. Cache is
-    process-scoped; tests that need to vary fetch_json's return value across
-    invocations should call cache_clear().
+    resolve_lemonade_rocm_choice() is called twice per install (direct planner
+    + resolve_upstream_asset_choice) with identical arguments. Without
+    memoisation each install hits api.github.com twice, doubling the
+    rate-limit failure surface on busy CI runners. Cache is process-scoped;
+    tests that vary fetch_json's return value across calls should call
+    cache_clear().
     """
     try:
         return fetch_json(api_url)
@@ -3686,23 +3678,21 @@ def resolve_lemonade_rocm_choice(
 
     os_prefix:   lemonade's asset filename label, NOT a host-distro filter.
                  Pass "ubuntu" for any Linux host (Arch, Fedora, openSUSE,
-                 Debian, ...) -- lemonade only publishes one Linux variant
-                 and it is a manylinux-style glibc build that runs on any
-                 distro with a recent-enough glibc. Pass "windows" for
-                 Windows hosts.
+                 Debian, ...) -- lemonade publishes one Linux variant, a
+                 manylinux-style glibc build that runs on any distro with a
+                 recent-enough glibc. Pass "windows" for Windows hosts.
     install_kind: "linux-rocm" or "windows-hip"
     llama_tag:   the requested upstream llama.cpp tag ("latest" or a pinned
-                 release like "b1260"). When pinned, the resolver fetches
-                 the matching lemonade release. When the pinned tag is not
-                 published by lemonade we skip silently (and the caller
-                 falls through to upstream) rather than drift to whatever
-                 lemonade ships as latest.
+                 release like "b1260"). When pinned, fetch the matching
+                 lemonade release; if lemonade hasn't published that tag, skip
+                 silently (caller falls through to upstream) rather than drift
+                 to whatever lemonade ships as latest.
     """
     if not host.rocm_gfx_target:
         return None
     # Opt-out for users who want the upstream HIP build path only -- lemonade
-    # binaries are downloaded without entries in the approved-hash manifest, so
-    # the integrity gate is functional validation only.
+    # binaries lack approved-hash manifest entries, so their integrity gate is
+    # functional validation only.
     if os.environ.get("UNSLOTH_DISABLE_LEMONADE_ROCM", "").strip().lower() in (
         "1",
         "true",
@@ -3735,7 +3725,7 @@ def resolve_lemonade_rocm_choice(
         return None
     asset_url = assets[asset_name]
     if not asset_url:
-        # release_asset_map defaults to "" when an asset row is missing
+        # release_asset_map defaults to "" when an asset row lacks
         # browser_download_url; skip cleanly instead of letting
         # download_file("") raise a less obvious error downstream.
         log(
@@ -3744,9 +3734,9 @@ def resolve_lemonade_rocm_choice(
         )
         return None
     # Defence in depth: lemonade browser_download_url should be on github.com
-    # or githubusercontent.com. A compromised GitHub API response that
-    # redirects to an attacker-chosen host would otherwise be honoured
-    # silently (lemonade assets are not in the approved-hash manifest).
+    # or githubusercontent.com. A compromised GitHub API response redirecting
+    # to an attacker host would otherwise be honoured silently (lemonade
+    # assets are not in the approved-hash manifest).
     if not _is_trusted_github_release_url(asset_url, LEMONADE_ROCM_REPO):
         log(
             f"{LEMONADE_ROCM_REPO}@{release_tag} asset {asset_name!r} points "
@@ -3754,9 +3744,9 @@ def resolve_lemonade_rocm_choice(
             "lemonade prebuilt"
         )
         return None
-    # Note: lemonade tags Linux assets with "ubuntu" but the binary is a
-    # generic glibc build that runs on any distro (Arch, Fedora, ...), so
-    # this attempt is selected for all Linux ROCm hosts, not just Ubuntu.
+    # Note: lemonade tags Linux assets "ubuntu" but the binary is a generic
+    # glibc build that runs on any distro (Arch, Fedora, ...), so this attempt
+    # is selected for all Linux ROCm hosts, not just Ubuntu.
     log(
         f"AMD GPU {host.rocm_gfx_target!r} ({gfx_family}) -- "
         f"trying lemonade-sdk ROCm prebuilt {asset_name} "
@@ -3782,28 +3772,27 @@ def resolve_lemonade_rocm_choice(
 def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice:
     upstream_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
     if host.is_linux and host.is_x86_64:
-        # AMD ROCm: try upstream ROCm prebuilt first, then fall back to source build.
-        # Source build (via setup.sh) compiles with -DGGML_HIP=ON and auto-detects
-        # the exact GPU target via rocminfo, which is more reliable for consumer
-        # GPUs (e.g. gfx1151) that may not be in the prebuilt.
+        # AMD ROCm: try upstream ROCm prebuilt first, then a source build. The
+        # source build (via setup.sh) compiles with -DGGML_HIP=ON and
+        # auto-detects the exact GPU target via rocminfo, more reliable for
+        # consumer GPUs (e.g. gfx1151) that may not be in the prebuilt.
         if host.has_rocm and not host.has_usable_nvidia:
-            # Try lemonade-sdk per-GPU prebuilt first: these are built against
-            # specific gfx targets and bundle all required ROCm runtime libs.
+            # Try lemonade-sdk per-GPU prebuilt first: built against specific
+            # gfx targets and bundle all required ROCm runtime libs.
             lemonade_choice = resolve_lemonade_rocm_choice(
                 host, "ubuntu", "linux-rocm", llama_tag = llama_tag
             )
             if lemonade_choice is not None:
                 return lemonade_choice
 
-            # Fall back to upstream combined ROCm tarball.
-            # Scan upstream assets for any rocm-<version> prebuilt. When the
-            # host ROCm runtime version is known, pick the newest candidate
-            # whose major.minor is <= host version -- otherwise a ROCm 6.4
-            # host would download the rocm-7.2 tarball, fail preflight, and
-            # fall back to a source build even though a compatible 6.4
-            # prebuilt exists. If no compatible candidate matches (e.g. host
-            # runtime is older than every published prebuilt), fall back to
-            # the numerically newest so we at least try something.
+            # Fall back to the upstream combined ROCm tarball. Scan for any
+            # rocm-<version> prebuilt; when the host ROCm version is known,
+            # pick the newest candidate whose major.minor is <= host version
+            # -- otherwise a ROCm 6.4 host downloads the rocm-7.2 tarball,
+            # fails preflight, and source-builds even though a 6.4 prebuilt
+            # exists. If none is compatible (host older than every published
+            # prebuilt), fall back to the numerically newest so we try
+            # something.
             _rocm_pattern = re.compile(
                 rf"llama-{re.escape(llama_tag)}-bin-ubuntu-rocm-([0-9]+(?:\.[0-9]+)*)-x64\.tar\.gz"
             )
@@ -3822,10 +3811,10 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                     item for item in rocm_candidates if item[0][:2] <= _host_rocm_version
                 ]
             if rocm_candidates and not _compatible:
-                # Fall back to the newest candidate so a source build is
-                # not forced when the host runtime is older than every
-                # published prebuilt: preflight will still catch a true
-                # incompatibility and trigger a fallback.
+                # Fall back to the newest candidate so we don't force a source
+                # build when the host runtime is older than every published
+                # prebuilt: preflight still catches a true incompatibility and
+                # triggers a fallback.
                 _compatible = rocm_candidates[:1]
             if _compatible:
                 rocm_name = _compatible[0][1]
@@ -3848,7 +3837,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                     source_label = "upstream",
                     install_kind = "linux-rocm",
                 )
-            # No ROCm prebuilt available -- fall back to source build
+            # No ROCm prebuilt available -- fall back to a source build
             raise PrebuiltFallback(
                 "AMD ROCm detected but no upstream ROCm prebuilt found; "
                 "falling back to source build with HIP support"
@@ -3978,12 +3967,11 @@ def resolve_release_asset_choice(
 
     published_choice: AssetChoice | None = None
     if host.is_windows and host.is_x86_64:
-        # AMD Windows hosts should prefer a hash-approved published
-        # Windows HIP bundle when one exists, but otherwise fall through
-        # to resolve_asset_choice() so the upstream HIP prebuilt is
-        # tried before the CPU fallback. Hard-pinning the published
-        # windows-cpu bundle here would make the new HIP path
-        # unreachable.
+        # AMD Windows hosts prefer a hash-approved published Windows HIP
+        # bundle when one exists, otherwise fall through to
+        # resolve_asset_choice() so the upstream HIP prebuilt is tried before
+        # the CPU fallback. Hard-pinning the published windows-cpu bundle here
+        # would make the HIP path unreachable.
         if host.has_rocm:
             published_choice = published_asset_choice_for_kind(release, "windows-hip")
         else:
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 5ff8e8572b..0cff45daef 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -5,9 +5,8 @@
 
 """Cross-platform Python dependency installer for Unsloth Studio.
 
-Called by both setup.sh (Linux / WSL) and setup.ps1 (Windows) after the
-virtual environment is already activated.  Expects `pip` and `python` on
-PATH to point at the venv.
+Called by setup.sh (Linux/WSL) and setup.ps1 (Windows) after the venv is
+activated. Expects `pip` and `python` on PATH to point at the venv.
 """
 
 from __future__ import annotations
@@ -42,11 +41,10 @@ IS_MAC_INTEL = IS_MACOS and platform.machine() == "x86_64"
 IS_MAC_ARM = IS_MACOS and platform.machine() == "arm64"
 IS_LINUX = sys.platform.startswith("linux")
 # torchcodec ships wheels only for manylinux_2_28_x86_64,
-# macosx_12_0_arm64, and win_amd64 (visible in the 0.10.0 PyPI page).
-# Trying to install it on any other host fails the whole
-# extras-no-deps step. `unsloth studio update` does not have a
-# --no-torch flag, so on these hosts the audio extras must be
-# filtered out independent of the NO_TORCH env var.
+# macosx_12_0_arm64, and win_amd64 (per the 0.10.0 PyPI page). Installing
+# on any other host fails the whole extras-no-deps step. `unsloth studio
+# update` has no --no-torch flag, so on these hosts the audio extras must
+# be filtered out regardless of the NO_TORCH env var.
 PLATFORM_LACKS_TORCHCODEC_WHEEL = (
     (IS_LINUX and platform.machine() in {"aarch64", "arm64"})
     or (IS_WINDOWS and platform.machine().lower() in {"arm64", "aarch64"})
@@ -54,8 +52,8 @@ PLATFORM_LACKS_TORCHCODEC_WHEEL = (
 )
 
 # ── ROCm / AMD GPU support ─────────────────────────────────────────────────────
-# Mapping from detected ROCm (major, minor) to the best PyTorch wheel tag on
-# download.pytorch.org.  Entries are checked newest-first (>=).
+# Detected ROCm (major, minor) -> best PyTorch wheel tag on
+# download.pytorch.org. Checked newest-first (>=).
 _ROCM_TORCH_INDEX: dict[tuple[int, int], str] = {
     (7, 2): "rocm7.2",  # torch 2.11.0
     (7, 1): "rocm7.1",  # torch 2.10.0
@@ -85,15 +83,15 @@ _PYTORCH_WHL_BASE = (
     os.environ.get("UNSLOTH_PYTORCH_MIRROR") or "https://download.pytorch.org/whl"
 ).rstrip("/")
 
-# AMD Windows ROCm wheels — repo.amd.com (arch-specific pip index)
+# AMD Windows ROCm wheels — repo.amd.com (arch-specific pip index).
 # Format: https://repo.amd.com/rocm/whl/{arch_family}/
-# Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped / mirror installs.
+# Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped/mirror installs.
 _ROCM_WINDOWS_INDEX_BASE = (
     os.environ.get("UNSLOTH_ROCM_WINDOWS_MIRROR") or "https://repo.amd.com/rocm/whl"
 ).rstrip("/")
 
-# Maps gfx arch → AMD index arch-family suffix.
-# Each family is a separate pip index on repo.amd.com.
+# gfx arch → AMD index arch-family suffix; each family is a separate
+# pip index on repo.amd.com.
 _GFX_TO_AMD_INDEX_ARCH: dict[str, str] = {
     "gfx1201": "gfx120X-all",
     "gfx1200": "gfx120X-all",  # RDNA 4
@@ -122,9 +120,9 @@ _BNB_ROCM_PRERELEASE_URLS: dict[str, str] = {
         "bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_aarch64.whl"
     ),
     # Windows ROCm wheel — ships libbitsandbytes_rocm{VER}.dll.
-    # BNB auto-detects HIP version from torch.version.hip, which does not always
-    # match the DLL suffix in this prerelease wheel (e.g. torch 7.13 with a rocm72
-    # DLL).  We scan the installed wheel for the actual DLL name and set
+    # BNB auto-detects HIP version from torch.version.hip, which may not match
+    # the DLL suffix in this prerelease wheel (e.g. torch 7.13 with a rocm72
+    # DLL). We scan the installed wheel for the real DLL name and set
     # BNB_ROCM_VERSION accordingly in _install_bnb_windows_rocm() and worker.py.
     "win_amd64": (
         "https://github.com/bitsandbytes-foundation/bitsandbytes/releases/"
@@ -136,8 +134,8 @@ _BNB_ROCM_PYPI_FALLBACK = "bitsandbytes>=0.49.1"
 
 
 def _bnb_rocm_prerelease_url() -> str | None:
-    """Return the continuous-release_main bnb wheel URL for the current
-    architecture, or None when no pre-release wheel is available.
+    """Return the continuous-release_main bnb wheel URL for the current arch,
+    or None when no pre-release wheel is available.
     """
     arch = platform.machine().lower()
     arch = {"amd64": "x86_64", "arm64": "aarch64"}.get(arch, arch)
@@ -155,9 +153,9 @@ def _detect_rocm_version() -> tuple[int, int] | None:
         try:
             with open(path) as fh:
                 parts = fh.read().strip().split("-")[0].split(".")
-            # Explicit length guard avoids relying on the broad except
-            # below to swallow IndexError when the version file contains
-            # a single component (e.g. "6\n" on a partial install).
+            # Explicit length guard so we don't rely on the broad except
+            # below to swallow IndexError when the version file has a
+            # single component (e.g. "6\n" on a partial install).
             if len(parts) >= 2:
                 return int(parts[0]), int(parts[1])
         except Exception:
@@ -201,11 +199,10 @@ def _detect_rocm_version() -> tuple[int, int] | None:
             pass
 
     # Distro package-manager fallbacks. Package-managed ROCm installs can
-    # expose GPUs via rocminfo / amd-smi but still lack /opt/rocm/.info/version
-    # and hipconfig, so probe dpkg (Debian/Ubuntu) and rpm (RHEL/Fedora/SUSE)
-    # for the rocm-core package version. Matches the chain in
-    # install.sh::get_torch_index_url so `unsloth studio update` behaves
-    # the same as a fresh `curl | sh` install.
+    # expose GPUs via rocminfo/amd-smi but lack /opt/rocm/.info/version and
+    # hipconfig, so probe dpkg (Debian/Ubuntu) and rpm (RHEL/Fedora/SUSE)
+    # for the rocm-core version. Matches install.sh::get_torch_index_url so
+    # `unsloth studio update` behaves like a fresh `curl | sh` install.
     for cmd in (
         ["dpkg-query", "-W", "-f=${Version}\n", "rocm-core"],
         ["rpm", "-q", "--qf", "%{VERSION}\n", "rocm-core"],
@@ -236,9 +233,9 @@ def _detect_rocm_version() -> tuple[int, int] | None:
 
 
 def _pick_visible_index(num_tokens: int) -> int:
-    """Resolve HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES to an integer
-    index into a list of length num_tokens. Returns 0 (first GPU) for
-    unset, empty, '-1', UUID-style, or out-of-range values."""
+    """Resolve HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES to an index into a
+    list of length num_tokens. Returns 0 (first GPU) for unset, empty, '-1',
+    UUID-style, or out-of-range values."""
     for _env in ("HIP_VISIBLE_DEVICES", "ROCR_VISIBLE_DEVICES"):
         _val = os.environ.get(_env)
         if _val is None:
@@ -260,14 +257,14 @@ def _pick_visible_index(num_tokens: int) -> int:
 def _detect_windows_gfx_arch() -> str | None:
     """Return the gcnArchName on Windows (e.g. 'gfx1200'), or None.
 
-    Probe order matches the PowerShell installer: env-var override first,
-    then hipinfo (PATH or HIP_PATH / ROCM_PATH bin), then amd-smi. Without
-    the amd-smi fallback, runtime-only AMD installs without hipinfo on PATH
+    Probe order matches the PowerShell installer: env-var override, then
+    hipinfo (PATH or HIP_PATH/ROCM_PATH bin), then amd-smi. Without the
+    amd-smi fallback, runtime-only AMD installs lacking hipinfo on PATH
     return early and `studio update` cannot repair a CPU-only venv.
 
-    On multi-GPU hosts, all detected gfx tokens are deduplicated (preserving
-    enumeration order) and HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES selects
-    which one to install for. The first GPU is used when no env var is set.
+    On multi-GPU hosts, detected gfx tokens are deduplicated (preserving
+    enumeration order) and HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES picks
+    which to install for. The first GPU is used when no env var is set.
     """
     # 1. Explicit override (matches PowerShell installer's env-var path).
     _override = os.environ.get("UNSLOTH_ROCM_GFX_ARCH")
@@ -277,8 +274,8 @@ def _detect_windows_gfx_arch() -> str | None:
     def _dedup_pick(tokens: list[str]) -> "str | None":
         if not tokens:
             return None
-        # Index into the full (ordered) list first so HIP_VISIBLE_DEVICES
-        # correctly addresses GPU N on mixed-arch hosts, then return that arch.
+        # Index into the full ordered list so HIP_VISIBLE_DEVICES addresses
+        # GPU N on mixed-arch hosts, then return that arch.
         return tokens[_pick_visible_index(len(tokens))]
 
     # 2. hipinfo via PATH, then HIP_PATH\bin / ROCM_PATH\bin.
@@ -301,8 +298,8 @@ def _detect_windows_gfx_arch() -> str | None:
             )
             if result.returncode == 0:
                 text = result.stdout.decode(errors = "replace")
-                # findall picks every gcnArchName line so multi-GPU hosts
-                # are enumerable and HIP_VISIBLE_DEVICES selects correctly.
+                # findall gets every gcnArchName line so multi-GPU hosts are
+                # enumerable and HIP_VISIBLE_DEVICES selects correctly.
                 _tokens = [
                     t.strip().lower() for t in re.findall(r"(?im)^\s*gcnArchName\s*:\s*(\S+)", text)
                 ]
@@ -353,10 +350,10 @@ def _windows_rocm_index_url(gfx_arch: str | None) -> str | None:
 def _detect_bnb_rocm_dll_ver() -> str | None:
     """Scan the installed bitsandbytes package for libbitsandbytes_rocm{VER}.dll.
 
-    Returns the version suffix string (e.g. ``"72"``, ``"713"``) or ``None``
-    if bitsandbytes is not installed or no ROCm DLL is found.  Does NOT import
-    bitsandbytes — uses importlib.util.find_spec so it is safe to call before
-    BNB is imported.
+    Returns the version suffix (e.g. ``"72"``, ``"713"``) or ``None`` if
+    bitsandbytes is not installed or no ROCm DLL is found. Does NOT import
+    bitsandbytes — uses importlib.util.find_spec, so it is safe to call
+    before BNB is imported.
     """
     import importlib.util
 
@@ -369,9 +366,9 @@ def _detect_bnb_rocm_dll_ver() -> str | None:
             m = re.search(r"libbitsandbytes_rocm(\d+)\.dll", os.path.basename(dll))
             if m:
                 all_vers.append(m.group(1))
-    # Pick the highest numeric suffix so that e.g. "713" wins over "72" when
-    # both variants are present in the wheel.  Filesystem glob order is not
-    # guaranteed, so always sort rather than stopping at the first match.
+    # Pick the highest numeric suffix so e.g. "713" wins over "72" when both
+    # variants are present. Glob order is not guaranteed, so always sort
+    # rather than stopping at the first match.
     return max(all_vers, key = lambda v: int(v)) if all_vers else None
 
 
@@ -380,8 +377,8 @@ def _has_rocm_gpu() -> bool:
     for cmd, check_fn in (
         # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
         # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines like
-        # "gfx11-generic" or "gfx9-4-generic" which only have 1-2 digits before
-        # the dash and must not be treated as a real GPU.
+        # "gfx11-generic"/"gfx9-4-generic" with only 1-2 digits before the dash,
+        # which must not be treated as a real GPU.
         (
             ["rocminfo"],
             lambda out: bool(re.search(r"gfx[1-9][0-9a-z]{2,3}", out.lower())),
@@ -410,9 +407,8 @@ def _has_rocm_gpu() -> bool:
                 return True
     # sysfs KFD topology fallback (Linux only) -- matches install.sh's
     # runtime-only detection. On minimal package-managed installs (no
-    # rocminfo / no amd-smi GUI tools), the kernel exposes AMD GPUs via
-    # /sys/class/kfd so `studio update` can still detect the GPU and
-    # repair the venv.
+    # rocminfo / no amd-smi tools), the kernel exposes AMD GPUs via
+    # /sys/class/kfd so `studio update` can still detect and repair.
     if sys.platform != "win32":
         try:
             kfd_nodes = "/sys/class/kfd/kfd/topology/nodes"
@@ -450,12 +446,11 @@ def _has_usable_nvidia_gpu() -> bool:
 
 
 def _detect_amd_gfx_codes() -> list[str]:
-    """Return the list of AMD gfx ISA strings visible to ROCm (e.g. ['gfx1151']).
+    """Return the AMD gfx ISA strings visible to ROCm (e.g. ['gfx1151']).
 
-    Probes rocminfo first, then falls back to ``amd-smi list`` and
-    ``amd-smi static --asic`` for runtime-only Radeon hosts that ship
-    amd-smi but no rocminfo. Returns an empty list when no probe yields
-    a gfx target.
+    Probes rocminfo, then falls back to ``amd-smi list`` and ``amd-smi
+    static --asic`` for runtime-only Radeon hosts that ship amd-smi but no
+    rocminfo. Returns an empty list when no probe yields a gfx target.
     """
 
     def _extract(text: str) -> list[str]:
@@ -495,13 +490,13 @@ def _install_bnb_windows_rocm() -> bool:
     """Install the AMD Windows BNB prerelease wheel. Returns True on success.
 
     The continuous-release wheel is intentionally mismatched: the filename
-    encodes version 1.33.7.preview (parsed as 1.33.7rc0 by PEP 440) while the
-    wheel metadata reports 0.50.0.dev0.  uv rejects this filename/metadata
-    mismatch -- and bypassing it with UV_SKIP_WHEEL_FILENAME_CHECK still leaves
-    uv mangling the bitsandbytes install. Per the AMD install guide
+    encodes 1.33.7.preview (parsed as 1.33.7rc0 by PEP 440) while the wheel
+    metadata reports 0.50.0.dev0. uv rejects this filename/metadata mismatch,
+    and bypassing it with UV_SKIP_WHEEL_FILENAME_CHECK still leaves uv mangling
+    the bitsandbytes install. Per the AMD install guide
     (https://unsloth.ai/docs/get-started/install/amd/amd-hackathon) the wheel
-    must be installed with plain pip, not uv, so we force pip here
-    (force_pip=True). plain pip performs no wheel filename/metadata check.
+    must be installed with plain pip, not uv, so we force pip (force_pip=True);
+    plain pip performs no wheel filename/metadata check.
     """
     _bnb_win_url = _BNB_ROCM_PRERELEASE_URLS.get("win_amd64")
     if _bnb_win_url is None:
@@ -517,13 +512,12 @@ def _install_bnb_windows_rocm() -> bool:
     )
     if not _ok:
         return False
-    # After install: detect the actual ROCm DLL suffix shipped in the wheel and
-    # set BNB_ROCM_VERSION so bitsandbytes loads the correct DLL regardless of
-    # what torch.version.hip reports.  The wheel may ship an older suffix (e.g.
-    # "72") while torch reports a newer HIP version (e.g. 7.13); the env var
-    # override ensures bitsandbytes does not fail looking for a non-existent DLL.
-    # The worker subprocess inherits this env var automatically.
-    # Fall back to "72" if detection fails (e.g. install was a no-op / dry-run).
+    # After install: detect the actual ROCm DLL suffix in the wheel and set
+    # BNB_ROCM_VERSION so bitsandbytes loads the correct DLL regardless of what
+    # torch.version.hip reports. The wheel may ship an older suffix (e.g. "72")
+    # while torch reports a newer HIP version (e.g. 7.13); the override stops
+    # bitsandbytes from failing on a non-existent DLL. The worker subprocess
+    # inherits this env var. Fall back to "72" if detection fails (no-op/dry-run).
     if "BNB_ROCM_VERSION" not in os.environ:
         _ver = _detect_bnb_rocm_dll_ver() or "72"
         os.environ["BNB_ROCM_VERSION"] = _ver
@@ -540,9 +534,9 @@ def _ensure_rocm_torch() -> None:
     Uses pip_install() to respect uv, constraints, and --python targeting.
     """
     global _rocm_windows_torch_installed
-    # setup.ps1 sets this when it already installed AMD wheels; skip the probe
-    # only when torch is actually importable as ROCm. If the venv was wiped
-    # between runs, the stale env-var would suppress a needed reinstall.
+    # setup.ps1 sets this after installing AMD wheels; skip the probe only when
+    # torch is actually importable as ROCm. If the venv was wiped between runs,
+    # the stale env-var would suppress a needed reinstall.
     if os.environ.get("UNSLOTH_ROCM_TORCH_INSTALLED") == "1":
         _torch_ok = False
         try:
@@ -566,9 +560,9 @@ def _ensure_rocm_torch() -> None:
             pass
         if _torch_ok:
             _rocm_windows_torch_installed = True
-            # setup.ps1 already installed ROCm torch, but we still need to install
-            # the AMD Windows BNB wheel here -- the PyPI bitsandbytes wheel ships
-            # only CUDA DLLs and will fail to load on ROCm.
+            # setup.ps1 already installed ROCm torch, but we still need the AMD
+            # Windows BNB wheel here -- the PyPI bitsandbytes wheel ships only
+            # CUDA DLLs and fails to load on ROCm.
             _install_bnb_windows_rocm()
             return
         # torch was wiped between runs; fall through to the full install path
@@ -619,14 +613,14 @@ def _ensure_rocm_torch() -> None:
                 "torchaudio",
                 constrain = False,
             )
-        # ROCm torch is installed (or already was); flag it so later install
-        # phases do not overwrite it with the generic CPU torch wheel. BNB is
-        # a separate dependency -- a BNB install failure must NOT roll the
-        # torch ROCm install back.
+        # ROCm torch is installed (or already was); flag it so later phases
+        # do not overwrite it with the generic CPU torch wheel. BNB is a
+        # separate dependency -- a BNB install failure must NOT roll back the
+        # torch ROCm install.
         _rocm_windows_torch_installed = True
         # Always install AMD Windows bitsandbytes -- the PyPI wheel ships only
-        # CUDA DLLs and will fail to load on ROCm.  Install even when torch was
-        # already a ROCm build so that `studio update` repairs a broken bnb.
+        # CUDA DLLs and fails on ROCm. Install even when torch was already a
+        # ROCm build so `studio update` repairs a broken bnb.
         if not _install_bnb_windows_rocm():
             print(
                 "   Warning: AMD Windows bitsandbytes install failed; "
@@ -637,16 +631,15 @@ def _ensure_rocm_torch() -> None:
     # ── Linux x86_64 only: PyTorch ROCm wheels are not published for aarch64 ──
     if platform.machine().lower() not in {"x86_64", "amd64"}:
         return
-    # NVIDIA takes precedence on mixed hosts -- but only if an actual GPU is usable
+    # NVIDIA takes precedence on mixed hosts -- but only if a GPU is usable
     if _has_usable_nvidia_gpu():
         return
-    # Rely on _has_rocm_gpu() (rocminfo / amd-smi GPU data rows) as the
-    # authoritative "is this actually an AMD ROCm host?" signal. The old
-    # gate required /opt/rocm or hipcc to exist, which breaks on
-    # runtime-only ROCm installs (package-managed minimal installs,
-    # Radeon software) that ship amd-smi/rocminfo without /opt/rocm or
-    # hipcc, and leaves `unsloth studio update` unable to repair a
-    # CPU-only venv on those systems.
+    # Use _has_rocm_gpu() (rocminfo / amd-smi GPU data rows) as the
+    # authoritative "is this an AMD ROCm host?" signal. The old gate required
+    # /opt/rocm or hipcc to exist, which breaks runtime-only ROCm installs
+    # (minimal package-managed installs, Radeon software) that ship
+    # amd-smi/rocminfo without /opt/rocm or hipcc, leaving `unsloth studio
+    # update` unable to repair a CPU-only venv on those systems.
     if not _has_rocm_gpu():
         return  # no AMD GPU visible
 
@@ -655,9 +648,9 @@ def _ensure_rocm_torch() -> None:
         print("   ROCm detected but version unreadable -- skipping torch reinstall")
         return
 
-    # Probe whether torch already links against HIP (ROCm is already working).
-    # Do NOT skip for CUDA-only builds since they are unusable on AMD-only
-    # hosts (the NVIDIA check above already handled mixed AMD+NVIDIA setups).
+    # Probe whether torch already links against HIP (ROCm already working).
+    # Do NOT skip for CUDA-only builds: they are unusable on AMD-only hosts
+    # (the NVIDIA check above already handled mixed AMD+NVIDIA setups).
     try:
         probe = subprocess.run(
             [
@@ -667,7 +660,7 @@ def _ensure_rocm_torch() -> None:
                     "import torch; "
                     "hip=getattr(torch.version,'hip','') or ''; "
                     "ver=getattr(torch,'__version__','').lower(); "
-                    # Print the HIP version when present (back-compat), else
+                    # Print the HIP version when present (back-compat), else a
                     # "rocm" sentinel when only torch.__version__ flags ROCm
                     # (AMD SDK / Radeon wheels). Empty string = CPU/CUDA.
                     "print(hip if hip else ('rocm' if 'rocm' in ver else ''))"
@@ -689,10 +682,9 @@ def _ensure_rocm_torch() -> None:
     # in torch._grouped_mm. AMD's per-gfx repo ships torch 2.11.0+rocm7.13.0
     # with the real fix, so route those hosts there instead of the generic
     # pytorch.org rocm7.1 wheel. Mirrors install.sh's Strix override.
-    # On mixed hosts (Strix iGPU + non-Strix dGPU), only route to the AMD
-    # per-gfx index when the GPU HIP will actually run on is the Strix one --
-    # otherwise the dGPU would get an incompatible wheel. Use HIP_VISIBLE_DEVICES
-    # to determine the runtime target.
+    # On mixed hosts (Strix iGPU + non-Strix dGPU), route to the AMD per-gfx
+    # index only when HIP's runtime GPU is the Strix one -- else the dGPU gets
+    # an incompatible wheel. Use HIP_VISIBLE_DEVICES for the runtime target.
     _strix_override_url: "str | None" = None
     _strix_override_pkgs: "tuple[str, str, str] | None" = None
     if ver < (7, 2):
@@ -700,10 +692,9 @@ def _ensure_rocm_torch() -> None:
         _strix_gfx = {"gfx1151", "gfx1150"}
         _detected_strix = _strix_gfx.intersection(gfx_codes)
         if _detected_strix:
-            # Pick the runtime-visible GPU. If HIP_VISIBLE_DEVICES selects a
-            # specific index into gfx_codes, use that gfx; else default to the
-            # first listed GPU. Skip the override unless the resolved GPU is
-            # Strix.
+            # Pick the runtime-visible GPU: use the HIP_VISIBLE_DEVICES index
+            # into gfx_codes, else default to the first GPU. Skip the override
+            # unless the resolved GPU is Strix.
             _runtime_gfx = gfx_codes[_pick_visible_index(len(gfx_codes))] if gfx_codes else None
             if _runtime_gfx in _strix_gfx:
                 _selected_gfx = _runtime_gfx
@@ -715,10 +706,10 @@ def _ensure_rocm_torch() -> None:
                     "torch>=2.11.0,<2.12.0",
                     # Pin torchvision/torchaudio to the 2.11.x-compatible range.
                     # The install uses --index-url (exclusive, no PyPI fallback),
-                    # so bare unversioned names risk resolving a build from AMD's
-                    # index that targets a different torch major (e.g. 0.27 built
-                    # against torch 2.12), which would fail at runtime with an
-                    # ABI/version mismatch. Matches _ROCM_TORCH_CONSTRAINT["rocm7.2"].
+                    # so bare unversioned names risk resolving an AMD-index build
+                    # targeting a different torch major (e.g. 0.27 built against
+                    # torch 2.12), which fails at runtime with an ABI/version
+                    # mismatch. Matches _ROCM_TORCH_CONSTRAINT["rocm7.2"].
                     "torchvision>=0.26.0,<0.27.0",
                     "torchaudio>=2.11.0,<2.12.0",
                 )
@@ -740,8 +731,8 @@ def _ensure_rocm_torch() -> None:
 
     # Strix override on ROCm 7.1 must fire even when has_hip_torch is True --
     # an existing torch with `torch.version.hip == "7.1"` is exactly the broken
-    # combo the override is meant to repair, so skipping it leaves users on
-    # the known _grouped_mm segfault.
+    # combo the override repairs, so skipping it leaves users on the known
+    # _grouped_mm segfault.
     if _strix_override_url is not None and _strix_override_pkgs is not None:
         index_url = _strix_override_url
         _torch_pkg, _vision_pkg, _audio_pkg = _strix_override_pkgs
@@ -790,10 +781,9 @@ def _ensure_rocm_torch() -> None:
             rocm_torch_ready = True
 
     # Install bitsandbytes only when torch links against ROCm. Prefers the
-    # continuous-release_main wheel (bnb PR #1887 4-bit GEMV fix) and falls
-    # back to PyPI when the pre-release wheel cannot be installed. Use pip for
-    # the pre-release wheel because uv rejects the wheel's filename/metadata
-    # version mismatch.
+    # continuous-release_main wheel (bnb PR #1887 4-bit GEMV fix), falling back
+    # to PyPI when the pre-release wheel won't install. Use pip for the
+    # pre-release wheel because uv rejects its filename/metadata version mismatch.
     if rocm_torch_ready:
         _bnb_url = _bnb_rocm_prerelease_url()
         _bnb_installed = False
@@ -871,10 +861,9 @@ def _windows_hidden_subprocess_kwargs() -> dict[str, object]:
 def _infer_no_torch() -> bool:
     """Determine whether to run in no-torch (GGUF-only) mode.
 
-    Checks UNSLOTH_NO_TORCH env var first.  When unset, falls back to
-    platform detection so that Intel Macs automatically use GGUF-only
-    mode even when invoked from ``unsloth studio update`` (which does
-    not inject the env var).
+    Checks UNSLOTH_NO_TORCH first. When unset, falls back to platform
+    detection so Intel Macs use GGUF-only mode even when invoked from
+    ``unsloth studio update`` (which does not inject the env var).
     """
     env = os.environ.get("UNSLOTH_NO_TORCH")
     if env is not None:
@@ -886,15 +875,15 @@ NO_TORCH = _infer_no_torch()
 
 
 # -- Verbosity control ----------------------------------------------------------
-# By default the installer shows a minimal progress bar (one line, in-place).
-# Set UNSLOTH_VERBOSE=1 in the environment to restore full per-step output:
+# By default the installer shows a minimal in-place one-line progress bar.
+# Set UNSLOTH_VERBOSE=1 to restore full per-step output:
 #   CLI:        unsloth studio setup --verbose
 #   Linux/Mac:  UNSLOTH_VERBOSE=1 ./studio/setup.sh
 #   Windows:    $env:UNSLOTH_VERBOSE="1" ; .\studio\setup.ps1
 VERBOSE: bool = os.environ.get("UNSLOTH_VERBOSE", "0") == "1"
 
-# Progress bar state -- updated by _progress() as each install step runs.
-# Update _TOTAL here if you add or remove install steps in install_python_stack().
+# Progress bar state -- updated by _progress() per install step.
+# Update _TOTAL if you add/remove steps in install_python_stack().
 _STEP: int = 0
 _TOTAL: int = 0  # set at runtime in install_python_stack() based on platform
 
@@ -908,16 +897,15 @@ LOCAL_DD_UNSTRUCTURED_PLUGIN = (
 )
 LOCAL_DD_GITHUB_PLUGIN = SCRIPT_DIR / "backend" / "plugins" / "data-designer-github-repo-seed"
 
-# Apple Silicon: override mlx-vlm/mlx-lm's transformers pin (see overrides file).
+# Apple Silicon: override mlx-vlm/mlx-lm's transformers pin (see overrides).
 _MLX_OVERRIDES = SINGLE_ENV / "overrides-darwin-arm64.txt"
 if IS_MAC_ARM and _MLX_OVERRIDES.is_file():
     os.environ.setdefault("UV_OVERRIDE", str(_MLX_OVERRIDES))
 
 # -- Unicode-safe printing ---------------------------------------------
-# On Windows the default console encoding can be a legacy code page
-# (e.g. CP1252) that cannot represent Unicode glyphs such as ✅ or ❌.
-# _safe_print() gracefully degrades to ASCII equivalents so the
-# installer never crashes just because of a status glyph.
+# On Windows the console encoding may be a legacy code page (e.g. CP1252)
+# that cannot represent glyphs like ✅ or ❌. _safe_print() degrades to ASCII
+# equivalents so the installer never crashes over a status glyph.
 
 _UNICODE_TO_ASCII: dict[str, str] = {
     "\u2705": "[OK]",  # ✅
@@ -934,11 +922,11 @@ def _safe_print(*args: object, **kwargs: object) -> None:
     except OSError:
         return
     except UnicodeEncodeError:
-        # Stringify, then swap emoji for ASCII equivalents
+        # Stringify, then swap emoji for ASCII equivalents.
         text = " ".join(str(a) for a in args)
         for uni, ascii_alt in _UNICODE_TO_ASCII.items():
             text = text.replace(uni, ascii_alt)
-        # Final fallback: replace any remaining unencodable chars
+        # Final fallback: replace any remaining unencodable chars.
         print(
             text.encode(sys.stdout.encoding or "ascii", errors = "replace").decode(
                 sys.stdout.encoding or "ascii", errors = "replace"
@@ -1065,16 +1053,14 @@ def run(
 WINDOWS_SKIP_PACKAGES = {"open_spiel", "triton_kernels"}
 
 # Packages to skip when torch is unavailable (Intel Mac GGUF-only mode).
-# These packages either *are* torch extensions or have unconditional
-# ``Requires-Dist: torch`` in their published metadata, so installing
-# them would pull torch back into the environment. ``librosa`` also
-# lives in this set even though it does not itself require torch:
-# upstream ``llvmlite`` dropped its macOS x86_64 wheel between 0.42.0
-# and 0.46.0+ (see https://pypi.org/project/llvmlite/0.47.0/#files --
-# only macosx_arm64 / manylinux / win_amd64 remain), so on Intel Mac
-# the librosa -> numba -> llvmlite chain triggers a from-source build
-# that fails inside CI and on the host without LLVM 14/15 headers.
-# Tracked separately in unslothai/unsloth#5046.
+# These either *are* torch extensions or have unconditional
+# ``Requires-Dist: torch``, so installing them would pull torch back in.
+# ``librosa`` is here too despite not requiring torch: upstream ``llvmlite``
+# dropped its macOS x86_64 wheel between 0.42.0 and 0.46.0+ (see
+# https://pypi.org/project/llvmlite/0.47.0/#files -- only
+# macosx_arm64 / manylinux / win_amd64 remain), so on Intel Mac the
+# librosa -> numba -> llvmlite chain triggers a from-source build that fails
+# in CI and on hosts without LLVM 14/15 headers. Tracked in unslothai/unsloth#5046.
 NO_TORCH_SKIP_PACKAGES = {
     "torch-stoi",
     "timm",
@@ -1238,14 +1224,14 @@ def _build_uv_cmd(args: tuple[str, ...]) -> list[str]:
     cmd = ["uv", "pip", "install"]
     if UV_NEEDS_SYSTEM:
         cmd.append("--system")
-    # Always pass --python so uv targets the correct environment.
-    # Without this, uv can ignore an activated venv and install into
-    # the system Python (observed on Colab and similar environments).
+    # Always pass --python so uv targets the right environment. Without it, uv
+    # can ignore an activated venv and install into the system Python (seen on
+    # Colab and similar).
     cmd.extend(["--python", sys.executable])
     cmd.extend(_translate_pip_args_for_uv(args))
-    # Torch is pre-installed by install.sh/setup.ps1.  Do not add
-    # --torch-backend by default -- it can cause solver dead-ends on
-    # CPU-only machines.  Callers that need it can set UV_TORCH_BACKEND.
+    # Torch is pre-installed by install.sh/setup.ps1. Do not add
+    # --torch-backend by default -- it can cause solver dead-ends on CPU-only
+    # machines. Callers that need it can set UV_TORCH_BACKEND.
     _tb = os.environ.get("UV_TORCH_BACKEND", "")
     if _tb:
         cmd.append(f"--torch-backend={_tb}")
@@ -1259,7 +1245,7 @@ def pip_install_try(
     force_pip: bool = False,
 ) -> bool:
     """Like pip_install but returns False on failure instead of exiting.
-    For optional installs with a follow-up fallback.
+    For optional installs that have a follow-up fallback.
     """
     constraint_args_pip: list[str] = []
     constraint_args_uv: list[str] = []
@@ -1384,14 +1370,14 @@ def install_python_stack() -> int:
     global USE_UV, _STEP, _TOTAL
     _STEP = 0
 
-    # When called from install.sh (which already installed unsloth into the venv),
-    # SKIP_STUDIO_BASE=1 is set to avoid redundant reinstallation of base packages.
-    # When called from "unsloth studio update", it is NOT set so base packages
-    # (unsloth + unsloth-zoo) are always reinstalled to pick up new versions.
+    # install.sh (which already installed unsloth) sets SKIP_STUDIO_BASE=1 to
+    # avoid reinstalling base packages. "unsloth studio update" does NOT set it,
+    # so base packages (unsloth + unsloth-zoo) are reinstalled to pick up new
+    # versions.
     skip_base = os.environ.get("SKIP_STUDIO_BASE", "0") == "1"
-    # When --package is used, install a different package name (for testing)
+    # --package installs a different package name (for testing).
     package_name = os.environ.get("STUDIO_PACKAGE_NAME", "unsloth")
-    # When --local is used, overlay a local repo checkout after updating deps
+    # --local overlays a local repo checkout after updating deps.
     local_repo = os.environ.get("STUDIO_LOCAL_REPO", "")
     base_total = 10 if IS_WINDOWS else 11
     if IS_MACOS:
@@ -1402,11 +1388,11 @@ def install_python_stack() -> int:
             base_total += 2  # flash-attn (line 1620) + ROCm torch final (line 1705) -- Linux only
     _TOTAL = (base_total - 1) if skip_base else base_total
 
-    # 1. Try to use uv for faster installs (must happen before pip upgrade
-    #    because uv venvs don't include pip by default)
+    # 1. Try uv for faster installs (before pip upgrade -- uv venvs don't
+    #    include pip by default).
     USE_UV = _bootstrap_uv()
 
-    # 2. Ensure pip is available (uv venvs created by install.sh don't include pip)
+    # 2. Ensure pip is available (uv venvs from install.sh omit pip).
     _progress("pip bootstrap")
     if USE_UV:
         run(
@@ -1421,9 +1407,8 @@ def install_python_stack() -> int:
             ],
         )
     else:
-        # pip may not exist yet (uv-created venvs omit it). Try ensurepip
-        # first, then upgrade. Only fall back to a direct upgrade when pip
-        # is already present.
+        # pip may not exist yet (uv-created venvs omit it). Try ensurepip,
+        # then upgrade. Direct upgrade only when pip is already present.
         _has_pip = (
             subprocess.run(
                 [sys.executable, "-m", "pip", "--version"],
@@ -1464,8 +1449,8 @@ def install_python_stack() -> int:
         pass
     elif NO_TORCH:
         # No-torch update path: install unsloth + unsloth-zoo with --no-deps
-        # (current PyPI metadata still declares torch as a hard dep), then
-        # runtime deps with --no-deps (avoids transitive torch).
+        # (PyPI metadata still declares torch as a hard dep), then runtime deps
+        # with --no-deps (avoids transitive torch).
         _progress("base packages (no torch)")
         pip_install(
             f"Updating {package_name} + unsloth-zoo (no-torch mode)",
@@ -1478,11 +1463,10 @@ def install_python_stack() -> int:
             package_name,
             "unsloth-zoo",
         )
-        # Resolve pydantic WITH deps so pip pins pydantic-core to the
-        # exact version pydantic's metadata declares. Under --no-deps
-        # alone pip picks the latest of each and trips pydantic's
-        # _ensure_pydantic_core_version check. Transitive deps are
-        # torch-free.
+        # Resolve pydantic WITH deps so pip pins pydantic-core to the exact
+        # version pydantic's metadata declares. Under --no-deps pip picks the
+        # latest of each and trips pydantic's _ensure_pydantic_core_version
+        # check. Transitive deps are torch-free.
         pip_install(
             "Installing pydantic (with deps for compatible core)",
             "--no-cache-dir",
@@ -1514,9 +1498,8 @@ def install_python_stack() -> int:
                 constrain = False,
             )
     elif local_repo:
-        # Local dev install: update deps from base.txt, then overlay the
-        # local checkout as an editable install (--no-deps so torch is
-        # never re-resolved).
+        # Local dev install: update deps from base.txt, then overlay the local
+        # checkout as an editable install (--no-deps so torch is not re-resolved).
         _progress("base packages")
         pip_install(
             "Updating base packages",
@@ -1546,7 +1529,7 @@ def install_python_stack() -> int:
             constrain = False,
         )
     elif package_name != "unsloth":
-        # Custom package name (for testing), install directly
+        # Custom package name (for testing): install directly.
         _progress("base packages")
         pip_install(
             f"Installing {package_name}",
@@ -1554,9 +1537,9 @@ def install_python_stack() -> int:
             package_name,
         )
     else:
-        # Update path: upgrade only unsloth + unsloth-zoo while preserving
-        # existing torch/CUDA installations.  Torch is pre-installed by
-        # install.sh / setup.ps1; --upgrade-package targets only base pkgs.
+        # Update path: upgrade only unsloth + unsloth-zoo, preserving existing
+        # torch/CUDA installs. Torch is pre-installed by install.sh/setup.ps1;
+        # --upgrade-package targets only base pkgs.
         _progress("base packages")
         pip_install(
             "Updating base packages",
@@ -1569,16 +1552,16 @@ def install_python_stack() -> int:
         )
 
     # 2b. AMD ROCm: reinstall torch with HIP wheels if the host has ROCm but the
-    #     venv received CPU-only torch (common when pip resolves torch from PyPI).
-    #     Must come immediately after base packages so torch is present for inspection.
+    #     venv got CPU-only torch (common when pip resolves torch from PyPI).
+    #     Must follow base packages so torch is present for inspection.
     if not IS_MACOS and not NO_TORCH:
         _progress("ROCm torch check")
         _ensure_rocm_torch()
 
-    # Windows + AMD GPU: if ROCm torch was not installed (wrong Python version
-    # or unknown ROCm version), warn the user.
+    # Windows + AMD GPU: warn if ROCm torch was not installed (wrong Python
+    # version or unknown ROCm version).
     if IS_WINDOWS and not NO_TORCH and not _has_usable_nvidia_gpu():
-        # Validate actual AMD GPU presence (not just tool existence)
+        # Validate actual AMD GPU presence (not just tool existence).
         import re as _re_win
 
         def _win_amd_smi_has_gpu(stdout: str) -> bool:
@@ -1632,9 +1615,9 @@ def install_python_stack() -> int:
         req = REQ_ROOT / "extras-no-deps.txt",
     )
 
-    # 4. Overrides (torchao, transformers) -- force-reinstall
-    #    Skip entirely when torch is unavailable (e.g. Intel Mac GGUF-only mode)
-    #    because overrides.txt contains torchao which requires torch.
+    # 4. Overrides (torchao, transformers) -- force-reinstall.
+    #    Skip when torch is unavailable (e.g. Intel Mac GGUF-only mode):
+    #    overrides.txt contains torchao, which requires torch.
     if NO_TORCH:
         _progress("dependency overrides (skipped, no torch)")
     else:
@@ -1642,8 +1625,8 @@ def install_python_stack() -> int:
         _override_extra_args: tuple[str, ...] = ()
         if _rocm_windows_torch_installed:
             # torchao in overrides.txt declares torch as a dependency; without
-            # --no-deps uv would resolve and install CPU torch from PyPI,
-            # overwriting the AMD ROCm wheels we just installed.
+            # --no-deps uv would install CPU torch from PyPI, overwriting the
+            # AMD ROCm wheels we just installed.
             _override_extra_args = ("--no-deps",)
         pip_install(
             "Installing dependency overrides",
@@ -1653,8 +1636,8 @@ def install_python_stack() -> int:
             req = REQ_ROOT / "overrides.txt",
         )
 
-    # 5. Triton kernels (no-deps, from source)
-    #    Skip on Windows (no support) and macOS (no support).
+    # 5. Triton kernels (no-deps, from source). Skip on Windows and macOS
+    #    (no support).
     if not IS_WINDOWS and not IS_MACOS:
         _progress("triton kernels")
         pip_install(
@@ -1745,11 +1728,10 @@ def install_python_stack() -> int:
         [sys.executable, str(SINGLE_ENV / "patch_metadata.py")],
     )
 
-    # 13. AMD ROCm: final torch repair.  Multiple install steps above can
-    #     pull in CUDA torch from PyPI (base packages, extras, overrides,
-    #     studio deps, etc.).  Running the repair as the very last step
-    #     ensures ROCm torch is in place at runtime, regardless of which
-    #     intermediate step clobbered it.
+    # 13. AMD ROCm: final torch repair. Several steps above can pull in CUDA
+    #     torch from PyPI (base packages, extras, overrides, studio deps, etc.).
+    #     Running the repair last ensures ROCm torch is in place at runtime,
+    #     whichever intermediate step clobbered it.
     if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:
         _progress("ROCm torch (final)")
         _ensure_rocm_torch()

From 187144d4e74a0cb54c06e1aba11b6a3507195997 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 23:09:51 -0700
Subject: [PATCH 116/222] Reduce and tighten code comments and docstrings
 repo-wide (#6095)

Trim and tighten code comments and docstrings across the repository. Comment-only: every changed file verified code-identical to main via AST/token comparison.
---
 scripts/check_frontend_dep_removal.py         | 329 +++-----
 scripts/check_new_install_scripts.py          |  77 +-
 scripts/enforce_kwargs_spacing.py             | 116 +--
 scripts/lint_workflow_triggers.py             |  40 +-
 scripts/lockfile_supply_chain_audit.py        | 211 ++---
 scripts/notebook_to_python.py                 |  69 +-
 scripts/notebook_validator.py                 | 138 ++--
 scripts/run_ruff_format.py                    |   6 +-
 scripts/scan_npm_packages.py                  | 215 ++----
 scripts/scan_packages.py                      | 261 ++-----
 scripts/stamp_studio_release.py               |   7 +-
 scripts/verify_comment_only_diff.py           |  13 +-
 scripts/verify_import_hoist.py                |  64 +-
 studio/backend/_platform_compat.py            |  15 +-
 studio/backend/auth/authentication.py         |  10 +-
 studio/backend/auth/hashing.py                |   2 +-
 studio/backend/auth/storage.py                |  51 +-
 studio/backend/colab.py                       |  42 +-
 studio/backend/core/__init__.py               |   4 +-
 studio/backend/core/_torchao_stub.py          |  43 +-
 studio/backend/core/data_recipe/__init__.py   |   4 +-
 .../backend/core/data_recipe/huggingface.py   |   3 +-
 .../backend/core/data_recipe/jobs/manager.py  |  14 +-
 studio/backend/core/data_recipe/jobs/parse.py |   2 +-
 studio/backend/core/data_recipe/jobs/types.py |   5 +-
 .../backend/core/data_recipe/jobs/worker.py   |   6 +-
 .../data_recipe/local_callable_validators.py  |   2 +-
 studio/backend/core/data_recipe/service.py    |  11 +-
 studio/backend/core/export/__init__.py        |   9 +-
 studio/backend/core/export/export.py          |  58 +-
 studio/backend/core/export/orchestrator.py    |  76 +-
 studio/backend/core/export/worker.py          | 101 +--
 studio/backend/core/inference/_html_to_md.py  |  56 +-
 .../core/inference/anthropic_compat.py        |  14 +-
 studio/backend/core/inference/audio_codecs.py |  38 +-
 studio/backend/core/inference/defaults.py     |   2 +-
 .../core/inference/external_provider.py       | 722 ++++++------------
 studio/backend/core/inference/inference.py    | 150 ++--
 studio/backend/core/inference/key_exchange.py |   9 +-
 studio/backend/core/inference/llama_cpp.py    | 627 ++++++---------
 .../core/inference/llama_server_args.py       |  26 +-
 studio/backend/core/inference/mcp_client.py   |  41 +-
 .../backend/core/inference/mlx_inference.py   |  56 +-
 studio/backend/core/inference/orchestrator.py | 112 ++-
 studio/backend/core/inference/pricing.py      |  12 +-
 studio/backend/core/inference/providers.py    | 116 +--
 .../core/inference/safetensors_agentic.py     |  16 +-
 .../core/inference/tool_call_parser.py        |  22 +-
 studio/backend/core/inference/tools.py        | 239 +++---
 studio/backend/core/inference/worker.py       |  85 +--
 studio/backend/core/tool_healing.py           |  53 +-
 studio/backend/core/training/__init__.py      |   2 +-
 studio/backend/core/training/trainer.py       | 212 +++--
 studio/backend/core/training/training.py      |  65 +-
 studio/backend/core/training/worker.py        | 223 ++----
 studio/backend/loggers/config.py              |  17 +-
 studio/backend/loggers/handlers.py            |  20 +-
 studio/backend/main.py                        | 120 ++-
 studio/backend/models/inference.py            | 143 ++--
 studio/backend/models/training.py             |  11 +-
 .../__init__.py                               |   5 +-
 .../data_designer_github_repo_seed/impl.py    |  14 +-
 .../data_designer_github_repo_seed/scraper.py |   4 +-
 .../scraper_impl/gh_client.py                 |   9 +-
 .../scraper_impl/scraper.py                   |  18 +-
 .../chunking.py                               |   2 +-
 studio/backend/routes/auth.py                 |  19 +-
 studio/backend/routes/chat_history.py         |  19 +-
 studio/backend/routes/data_recipe/jobs.py     | 139 ++--
 studio/backend/routes/data_recipe/seed.py     |   3 +-
 studio/backend/routes/data_recipe/validate.py |  15 +-
 studio/backend/routes/datasets.py             |  67 +-
 studio/backend/routes/export.py               |  49 +-
 studio/backend/routes/inference.py            |   2 -
 studio/backend/routes/mcp_servers.py          |   9 +-
 studio/backend/routes/models.py               | 306 +++-----
 studio/backend/routes/providers.py            |  29 +-
 studio/backend/routes/training.py             |  30 +-
 studio/backend/run.py                         | 149 ++--
 studio/backend/startup_banner.py              |   2 +-
 studio/backend/storage/mcp_servers_db.py      |   2 +-
 studio/backend/storage/providers_db.py        |  11 +-
 studio/backend/storage/studio_db.py           |  58 +-
 studio/backend/tests/conftest.py              |  55 +-
 .../backend/tests/test_anthropic_cache_ttl.py |  21 +-
 .../backend/tests/test_anthropic_citations.py |   3 +-
 .../tests/test_anthropic_code_execution.py    |  39 +-
 .../tests/test_anthropic_compaction.py        |  91 +--
 .../backend/tests/test_anthropic_messages.py  |   5 +-
 .../test_anthropic_thinking_translation.py    |  20 +-
 .../tests/test_anthropic_tool_versions.py     |  37 +-
 .../backend/tests/test_anthropic_web_fetch.py |  18 +-
 .../tests/test_cache_case_resolution.py       |   3 +-
 .../backend/tests/test_cached_gguf_routes.py  |  30 +-
 .../tests/test_chat_history_storage.py        |   3 +-
 .../test_cleanup_cancelled_checkpoints.py     |   9 +-
 studio/backend/tests/test_desktop_auth.py     |   8 +-
 .../backend/tests/test_export_log_cursor.py   |  58 +-
 .../test_external_provider_usage_chunk.py     |  25 +-
 .../backend/tests/test_frontend_resolution.py |   4 +-
 .../tests/test_gguf_reload_inheritance.py     |   7 +-
 studio/backend/tests/test_gguf_routing.py     |   7 +-
 studio/backend/tests/test_host_defaults.py    |   6 +-
 .../tests/test_index_bootstrap_origin.py      |  16 +-
 .../tests/test_inference_model_validation.py  |   2 +-
 .../backend/tests/test_kv_cache_estimation.py |  39 +-
 .../test_lemonade_llamacpp_rocm_bins_mock.py  |  10 +-
 .../test_llama_cpp_cache_aware_disk_check.py  |  36 +-
 .../tests/test_llama_cpp_context_fit.py       |  45 +-
 .../backend/tests/test_llama_cpp_freshness.py |   7 +-
 .../tests/test_llama_cpp_load_progress.py     |  37 +-
 .../test_llama_cpp_load_progress_live.py      |  21 +-
 .../test_llama_cpp_load_progress_matrix.py    |  37 +-
 .../test_llama_cpp_max_context_threshold.py   |  10 -
 .../tests/test_llama_cpp_mtp_detection.py     |   8 +-
 .../tests/test_llama_cpp_no_context_shift.py  |   5 +-
 .../tests/test_llama_cpp_wait_for_health.py   |  11 +-
 .../test_llama_cpp_wait_for_vram_settle.py    |  12 +-
 .../test_llama_cpp_windows_nvidia_path.py     |  29 +-
 .../backend/tests/test_llama_server_args.py   |  13 +-
 studio/backend/tests/test_login_rate_limit.py |  14 +-
 studio/backend/tests/test_mcp_servers.py      |  44 +-
 .../tests/test_mcp_stdio_improvements.py      |   3 +-
 studio/backend/tests/test_mcp_stdio_pr5863.py |  13 +-
 studio/backend/tests/test_middleware.py       |   6 -
 .../backend/tests/test_multimodal_document.py |  43 +-
 .../tests/test_offline_gguf_cache_fallback.py |  56 +-
 .../tests/test_openai_citation_markers.py     |  17 +-
 .../tests/test_openai_code_execution.py       |  44 +-
 .../tests/test_openai_image_generation.py     |  16 +-
 .../test_openai_responses_translation.py      |   2 +-
 .../tests/test_openai_tool_passthrough.py     |  48 +-
 studio/backend/tests/test_pricing_edge.py     |   1 -
 studio/backend/tests/test_providers_api.py    |  50 +-
 studio/backend/tests/test_pytorch_mirror.py   |   4 +-
 .../test_recommended_folders_permission.py    |   3 +-
 studio/backend/tests/test_responses_api.py    |  12 +-
 studio/backend/tests/test_rocm_oom_guard.py   |  14 +-
 .../test_safetensors_capability_advertise.py  |  20 +-
 .../tests/test_safetensors_tool_loop.py       |  76 +-
 studio/backend/tests/test_sandbox_tools.py    |  35 +-
 studio/backend/tests/test_studio_api.py       |  42 +-
 .../tests/test_studio_train_validation.py     |   6 +-
 .../tests/test_training_worker_flash_attn.py  |  89 +--
 .../tests/test_transformers_version.py        |   6 +-
 studio/backend/tests/test_utils.py            |  21 +-
 studio/backend/tests/test_vision_cache.py     |  34 +-
 .../tests/test_windows_gpu_detection_mock.py  |  20 +-
 studio/backend/utils/cache_cleanup.py         |  15 +-
 studio/backend/utils/cpu_threads.py           |   4 +-
 studio/backend/utils/datasets/__init__.py     |  22 +-
 .../backend/utils/datasets/chat_templates.py  |  24 +-
 .../backend/utils/datasets/data_collators.py  |  40 +-
 .../utils/datasets/dataset_none_detect.py     |   8 +-
 .../backend/utils/datasets/dataset_utils.py   |   7 +-
 .../utils/datasets/format_conversion.py       |  19 +-
 .../utils/datasets/format_detection.py        | 152 ++--
 studio/backend/utils/datasets/llm_assist.py   | 140 +---
 .../backend/utils/datasets/model_mappings.py  |   2 +-
 studio/backend/utils/datasets/raw_text.py     |   4 +-
 .../backend/utils/datasets/vlm_processing.py  |   6 +-
 studio/backend/utils/hardware/__init__.py     |   4 +-
 studio/backend/utils/hardware/amd.py          |  86 +--
 studio/backend/utils/hardware/hardware.py     | 171 ++---
 studio/backend/utils/hardware/nvidia.py       |   9 +-
 .../backend/utils/hardware/vram_estimation.py |  91 +--
 .../utils/inference/inference_config.py       |  52 +-
 studio/backend/utils/llama_cpp_freshness.py   |   5 +-
 studio/backend/utils/models/__init__.py       |   4 +-
 studio/backend/utils/models/checkpoints.py    |  21 +-
 studio/backend/utils/models/model_config.py   | 314 +++-----
 studio/backend/utils/paths/__init__.py        |   4 +-
 studio/backend/utils/paths/path_utils.py      |  21 +-
 studio/backend/utils/paths/storage_roots.py   |  20 +-
 studio/backend/utils/subprocess_compat.py     |   5 +-
 studio/backend/utils/transformers_version.py  |  36 +-
 studio/backend/utils/utils.py                 |  23 +-
 studio/backend/utils/wheel_utils.py           |  14 +-
 studio/install_llama_prebuilt.py              |  18 +-
 studio/install_python_stack.py                |  20 +-
 tests/_zoo_aggressive_cuda_spoof.py           |  57 +-
 tests/conftest.py                             |  13 +-
 tests/python/test_cross_platform_parity.py    |   3 +-
 tests/python/test_e2e_no_torch_sandbox.py     |  26 +-
 ...sentence_transformer_redirect_lifecycle.py |   4 +-
 tests/python/test_install_python_stack.py     |   5 +-
 tests/python/test_studio_import_no_torch.py   |   1 -
 .../test_tokenizers_and_torch_constraint.py   |   7 +-
 .../saving/gpt-oss-merge/test_merged_model.py |   2 +-
 tests/saving/gpt-oss-merge/train_and_merge.py |   3 +-
 .../test_merge_4bit_validation.py             |   5 +-
 .../test_merge_model_perplexity_llama-3.2.py  |  20 +-
 .../test_merge_model_perplexity_mistral.py    |  28 +-
 .../test_merge_model_perplexity_phi_4.py      |  23 +-
 ...st_merged_model_perplexity_llama-3.1-8b.py |  20 +-
 .../test_merged_model_perplexity_qwen_2.5.py  |  25 +-
 .../test_push_to_hub_merged.py                |   3 +-
 ...t_push_to_hub_merged_sharded_index_file.py |   1 -
 .../test_save_merged_grpo_model.py            |  37 +-
 .../saving/non_peft/test_mistral_non_peft.py  |   5 +-
 .../saving/non_peft/test_whisper_non_peft.py  |   3 -
 tests/saving/test_unsloth_save.py             |  39 +-
 .../saving/text_to_speech_models/test_csm.py  |   6 +-
 .../text_to_speech_models/test_orpheus.py     |   4 +-
 .../text_to_speech_models/test_whisper.py     |   4 +-
 .../test_index_file_sharded_model.py          |  25 +-
 .../vision_models/test_push_to_hub_merged.py  |   7 +-
 ..._merge_qwen2.5vl32B_model_ocr_benchmark.py |  24 +-
 ...t_save_merge_vision_model_ocr_benchmark.py |  40 +-
 tests/security/conftest.py                    |  19 +-
 tests/security/fixtures/_build.py             |  25 +-
 .../test_lockfile_supply_chain_audit.py       |  56 +-
 tests/security/test_new_install_scripts.py    |   8 +-
 tests/security/test_scan_npm_packages.py      |  31 +-
 tests/security/test_scan_packages.py          |  46 +-
 tests/studio/_playwright_robust.py            | 245 ++----
 .../smoke_test_parallel_studio_home.py        |  53 +-
 .../install/test_llama_pr_force_and_source.py |  11 +-
 tests/studio/install/test_rocm_support.py     |  65 +-
 tests/studio/install/test_selection_logic.py  |  48 --
 tests/studio/load_freeze/llama_server_shim.py |   4 +-
 .../load_freeze/test_load_orchestrator.py     |  20 -
 tests/studio/playwright_chat_ime_i18n.py      |  97 +--
 tests/studio/run_real_mlx_smoke.py            | 125 +--
 tests/studio/test_auth_form_input_count.py    |  22 +-
 tests/studio/test_cancel_id_wiring.py         |  16 +-
 tests/studio/test_cli_studio_defaults.py      |   6 +-
 .../test_composer_rtl_bidi_attribute.py       |   7 +-
 tests/studio/test_frontend_dep_removal.py     |  42 +-
 tests/studio/test_hardware_dispatch_matrix.py |  76 +-
 tests/studio/test_is_mlx_dispatch_gate.py     |  18 +-
 .../test_stream_cancel_registration_timing.py |  77 +-
 tests/test_cli_export_unpacking.py            |  47 +-
 tests/test_enforce_kwargs_spacing.py          |   2 +-
 tests/test_finetune_last_n_layers.py          |  13 +-
 tests/test_import_fixes_drift.py              |  30 -
 tests/test_model_registry.py                  |  10 +-
 tests/test_multi_image_grpo_chunking.py       |   6 +-
 tests/test_public_api_surface.py              |  33 +-
 tests/test_raw_text.py                        |   4 +-
 tests/test_studio_install_workspace_guard.py  |  23 +-
 tests/utils/aime_eval.py                      |  42 +-
 tests/utils/cleanup_utils.py                  |  34 +-
 tests/utils/data_utils.py                     |  36 +-
 tests/utils/generate_dataset_with_none.py     |  35 +-
 tests/utils/ocr_eval.py                       |  37 +-
 tests/utils/os_utils.py                       |   4 +-
 tests/utils/perplexity_eval.py                |  17 +-
 tests/utils/run_none_detect_tests.py          |  21 +-
 tests/utils/test_packing.py                   |   2 +-
 tests/utils/test_q_galore.py                  |   9 +-
 tests/version_compat/_fetch.py                |  33 +-
 .../test_bitsandbytes_pinned_symbols.py       |  17 +-
 .../test_peft_pinned_symbols.py               |  85 +--
 ...st_sentence_transformers_pinned_symbols.py |  42 +-
 .../test_trl_grpo_pinned_symbols.py           |  44 --
 .../test_extended_module_imports.py           |  66 +-
 tests/vllm_compat/test_unsloth_zoo_imports.py |  76 +-
 unsloth-cli.py                                |  26 +-
 unsloth/__init__.py                           |  28 +-
 unsloth/_gpu_init.py                          |  32 +-
 unsloth/chat_templates.py                     |  19 +-
 unsloth/dataprep/raw_text.py                  |  29 +-
 unsloth/dataprep/synthetic.py                 |   3 +-
 unsloth/device_type.py                        |   7 +-
 unsloth/import_fixes.py                       |  65 +-
 unsloth/kernels/__init__.py                   |   2 +-
 unsloth/kernels/cross_entropy_loss.py         |   7 +-
 unsloth/kernels/fast_lora.py                  |   7 +-
 unsloth/kernels/fp8.py                        |  79 +-
 unsloth/kernels/moe/autotune_cache.py         |  27 +-
 .../moe/benchmark/benchmark_fused_moe.py      |  20 +-
 unsloth/kernels/moe/grouped_gemm/interface.py |  33 +-
 .../moe/grouped_gemm/kernels/autotuning.py    |   5 +-
 .../moe/grouped_gemm/kernels/backward.py      |   5 +-
 .../moe/grouped_gemm/kernels/tuning.py        |   5 +-
 .../reference/layers/llama4_moe.py            |  15 +-
 .../reference/layers/qwen3_moe.py             |  23 +-
 unsloth/kernels/moe/tests/moe_utils.py        |  26 +-
 .../kernels/moe/tests/test_grouped_gemm.py    |   8 +-
 unsloth/kernels/utils.py                      |  16 +-
 unsloth/models/__init__.py                    |   2 +-
 unsloth/models/_utils.py                      |  18 +-
 unsloth/models/falcon_h1.py                   |   7 +-
 unsloth/models/gemma2.py                      |   7 +-
 unsloth/models/glm4_moe.py                    |  47 +-
 unsloth/models/granite.py                     |   5 +-
 unsloth/models/llama.py                       | 100 +--
 unsloth/models/loader.py                      |  18 +-
 unsloth/models/loader_utils.py                |  43 +-
 unsloth/models/mistral.py                     |  10 +-
 unsloth/models/qwen3.py                       |  44 +-
 unsloth/models/qwen3_moe.py                   |  15 +-
 unsloth/models/rl.py                          |  82 +-
 unsloth/models/sentence_transformer.py        | 160 +---
 unsloth/models/vision.py                      |   6 +-
 unsloth/optimizers/q_galore_adamw.py          |  35 +-
 unsloth/optimizers/q_galore_projector.py      |  24 +-
 unsloth/registry/__init__.py                  |   7 +-
 unsloth/registry/registry.py                  |   6 +-
 unsloth/save.py                               |  22 +-
 unsloth/tokenizer_utils.py                    |  24 +-
 unsloth/trainer.py                            |  38 +-
 unsloth/utils/attention_dispatch.py           |  27 +-
 unsloth/utils/hf_hub.py                       |  14 +-
 unsloth_cli/_tool_policy.py                   |  19 +-
 unsloth_cli/commands/studio.py                |  42 +-
 unsloth_cli/commands/train.py                 |   6 +-
 unsloth_cli/config.py                         |   3 +-
 unsloth_cli/options.py                        |   4 +-
 .../test_studio_run_short_alias_clashes.py    |   6 +-
 311 files changed, 4052 insertions(+), 8662 deletions(-)

diff --git a/scripts/check_frontend_dep_removal.py b/scripts/check_frontend_dep_removal.py
index 3ec4e9037f..b95c4ca7f6 100644
--- a/scripts/check_frontend_dep_removal.py
+++ b/scripts/check_frontend_dep_removal.py
@@ -43,7 +43,7 @@ DEP_FIELDS = (
     "optionalDependencies",
 )
 
-# Sources where seeing a package name does NOT count as usage.
+# Files where seeing a package name does NOT count as usage.
 EXPECTED_NOISE_FILES = {
     "studio/frontend/package.json",
     "studio/frontend/package-lock.json",
@@ -51,17 +51,15 @@ EXPECTED_NOISE_FILES = {
     "studio/backend/core/data_recipe/oxc-validator/package-lock.json",
 }
 
-# Only quoted-string occurrences in these file types can be module specifiers.
+# File types where a quoted string can be a module specifier.
 JS_LIKE_EXT = re.compile(r"\.(ts|tsx|js|jsx|mjs|cjs|html|htm|css|scss|sass|json|jsonc)$")
-# Files where JS-syntactic import patterns (static/dynamic/require/re-export)
-# could be a real module reference. Markdown gets a separate gate (.mdx is
+# Files where JS import patterns could be a real module reference (.mdx is
 # real ESM; .md code fences are not).
 SCRIPT_LIKE_EXT = re.compile(r"\.(ts|tsx|js|jsx|mjs|cjs|mdx)$")
 STYLE_EXT = re.compile(r"\.(css|scss|sass)$")
 HTML_EXT = re.compile(r"\.(html|htm)$")
 TS_LIKE_EXT = re.compile(r"\.(ts|tsx|mts|cts|mdx)$")
-# Files where a removed package's CLI binary could be invoked (npx, bunx,
-# yarn dlx, pnpm exec, or a bare `pkg --flag` shell call).
+# Files where a removed package's CLI binary could be invoked.
 COMMAND_LIKE_EXT = re.compile(r"(\.(ya?ml|sh|ps1|bat)$|(^|/)Dockerfile[^/]*$)")
 
 GREP_INCLUDES = [
@@ -102,7 +100,7 @@ GREP_EXCLUDES = [
     "--exclude-dir=venv",
 ]
 
-# A pip-installed playwright reference is the PyPI package, not npm.
+# A pip-installed playwright ref is the PyPI package, not npm.
 PIP_PLAYWRIGHT = re.compile(
     r"(pip\s+install\s+['\"]?playwright"
     r"|python\s+-m\s+playwright"
@@ -153,9 +151,8 @@ def all_decl_names(pkg: dict) -> set[str]:
 
 
 def _resolve_install_path(parent_path: str, name: str, pkgs: dict) -> str | None:
-    """Walk up the nested node_modules chain from `parent_path` to find
-    where `name` actually resolves. Mirrors Node module resolution.
-    """
+    """Walk up the nested node_modules chain from `parent_path` to find where
+    `name` resolves, mirroring Node module resolution."""
     parts = parent_path.split("/node_modules/")
     for i in range(len(parts), 0, -1):
         prefix = "/node_modules/".join(parts[:i])
@@ -168,11 +165,8 @@ def _resolve_install_path(parent_path: str, name: str, pkgs: dict) -> str | None
 
 
 def _deps_of(meta: dict) -> dict:
-    """Deps npm actually installs. Optional peers are skipped: npm only
-    installs them when another package declares the same dep, so for the
-    purpose of "is this package still reachable" they cannot keep a
-    removed top-level dep alive on their own.
-    """
+    """Deps npm actually installs. Optional peers are skipped: they can't keep
+    a removed top-level dep reachable on their own."""
     out = {}
     for field in ("dependencies", "optionalDependencies"):
         out.update(meta.get(field) or {})
@@ -185,10 +179,8 @@ def _deps_of(meta: dict) -> dict:
 
 
 def reachable_from_head(head_pkg: dict, lock: dict) -> set[str]:
-    """BFS the lockfile dep graph starting from `head_pkg`'s top-level
-    declared deps. Returns the set of lockfile install paths that survive.
-    Stale lockfile entries (orphaned by the new package.json) are excluded.
-    """
+    """BFS the lockfile dep graph from `head_pkg`'s top-level deps. Returns the
+    surviving install paths, excluding stale (orphaned) lockfile entries."""
     pkgs = lock.get("packages", {})
     if not pkgs:
         return set()
@@ -215,23 +207,17 @@ def reachable_from_head(head_pkg: dict, lock: dict) -> set[str]:
 def classify(pkg: str, file: str, content: str) -> str | None:
     """Return why `content` references `pkg`, or None.
 
-    `content` may span multiple lines (for multi-line imports/exports);
-    each pattern uses re.DOTALL where it matters. The bare-spec
-    regexes use a word-boundary check on the package name so that
-    `foobar` does not match `foo`.
-
-    File-type gating: JS-syntactic patterns only fire on .ts/.tsx/.js/.jsx/
-    .mjs/.cjs/.mdx files, so an `import x from "pkg"` snippet inside a
-    Python test fixture or a Markdown code block is not mistaken for a
-    real npm usage. CSS patterns only fire on .css/.scss/.sass. HTML
-    patterns only fire on .html/.htm.
+    `content` may span multiple lines (multi-line imports/exports use re.DOTALL).
+    Bare-spec regexes word-boundary the package name so `foobar` doesn't match
+    `foo`. File-type gating restricts JS patterns to .ts/.tsx/.js/.jsx/.mjs/
+    .cjs/.mdx, CSS to .css/.scss/.sass, HTML to .html/.htm, so a snippet inside
+    a Python fixture or Markdown code block isn't mistaken for real npm usage.
     """
     if file in EXPECTED_NOISE_FILES:
         return None
 
     esc = re.escape(pkg)
-    # Subpath gate: after the package name, the next char must be either
-    # the closing quote, `/`, or end-of-string. Prevents foo matching foobar.
+    # Subpath gate: pkg must be followed by quote, `/`, or end-of-string.
     sub = r"(?:/[^'\"`]*)?"
 
     flags_dotall = re.DOTALL | re.MULTILINE
@@ -241,30 +227,22 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     is_html = bool(HTML_EXT.search(file))
     is_ts = bool(TS_LIKE_EXT.search(file))
 
-    # If the file is none of script / style / html / json (which is the
-    # quoted-string fallback surface) and is not an mdx file, no classify
-    # rule applies. This is what gates out Python fixtures, Markdown code
-    # blocks, shell snippets, etc.
+    # Gate out Python fixtures, Markdown code blocks, shell snippets, etc.
     is_json = file.endswith(".json") or file.endswith(".jsonc")
     if not (is_script or is_style or is_html or is_json):
         return None
 
-    # CSS @import is checked first so it does not collide with the
-    # side-effect-import regex below.
+    # CSS @import first so it doesn't collide with side-effect-import below.
     if is_style and re.search(rf"@import\s+['\"]{esc}{sub}['\"]", content):
         return "css_import"
-    # Static imports: handle multi-line `import { ... } from "pkg"` by
-    # allowing arbitrary content (newlines included) between `import`
-    # and `from`. The non-greedy match plus the required `from` keeps
-    # this scoped to a single statement.
+    # Static imports, including multi-line `import { ... } from "pkg"`.
     if is_script and re.search(
         rf"(?<!@)\bimport\b[^;'\"]*?\bfrom\s+['\"]{esc}{sub}['\"]",
         content,
         flags_dotall,
     ):
         return "static_import"
-    # Side-effect import: `import "pkg"` (no `from`). The negative
-    # lookbehind rules out CSS `@import` lines.
+    # Side-effect import `import "pkg"` (no `from`); lookbehind rules out @import.
     if is_script and re.search(rf"(?<!@)\bimport\s+['\"]{esc}{sub}['\"]", content):
         return "side_effect_import"
     # Dynamic import: `import("pkg")` and `await import("pkg")`.
@@ -273,17 +251,15 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     # require / require.resolve
     if is_script and re.search(rf"\brequire(?:\.resolve)?\(\s*['\"]{esc}{sub}['\"]\s*\)", content):
         return "require"
-    # Re-exports: `export * from "pkg"`, `export { x } from "pkg"`,
-    # `export type { Foo } from "pkg"`. Multi-line supported.
+    # Re-exports: `export * from`, `export { x } from`, `export type { Foo } from`.
     if is_script and re.search(
         rf"\bexport\b[^;'\"]*?\bfrom\s+['\"]{esc}{sub}['\"]",
         content,
         flags_dotall,
     ):
         return "re_export"
-    # HTML script / link. Match the package name as a complete path
-    # segment bounded by a quote / `#` / `?` or a subpath `/`, so
-    # `/node_modules/foo-extra/...` is NOT treated as usage of `foo`.
+    # HTML script / link. Match pkg as a complete path segment so
+    # `/node_modules/foo-extra/...` is not treated as usage of `foo`.
     html_pkg = rf"{esc}(?:/[^'\"#?]*)?(?=['\"#?])"
     if is_html and re.search(rf"<script[^>]*src\s*=\s*['\"][^'\"]*/{html_pkg}", content):
         return "html_script"
@@ -295,8 +271,7 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     # new URL("pkg/...", import.meta.url)
     if is_script and re.search(rf"\bnew\s+URL\(\s*['\"]{esc}{sub}['\"]", content):
         return "new_url"
-    # CSS url(...). Accept quoted ("pkg/x") AND unquoted (pkg/x) variants,
-    # bounded by a path-segment lookahead so `pkg-extra` does not match.
+    # CSS url(...), quoted and unquoted, bounded so `pkg-extra` doesn't match.
     if is_style and re.search(
         rf"\burl\(\s*['\"]?(?:[^)'\"\s]+/)?{esc}(?:/[^)'\"`]*)?['\"]?\s*\)",
         content,
@@ -309,20 +284,18 @@ def classify(pkg: str, file: str, content: str) -> str | None:
     if is_script and re.search(rf"@import\(\s*['\"]{esc}{sub}['\"]\s*\)", content):
         return "jsdoc_import"
     # Bare quoted-string fallback (config plugin lists, vite aliases,
-    # tsconfig paths, biome config plugin arrays, shadcn registries).
+    # tsconfig paths, biome plugin arrays, shadcn registries).
     if not JS_LIKE_EXT.search(file):
         return None
-    # Boundary: pkg must be followed by `'`, `"`, or `/` to avoid
-    # matching `foo` inside `foobar`.
+    # pkg must be followed by `'`, `"`, or `/` so `foo` doesn't match `foobar`.
     if re.search(rf"['\"]{esc}(?:['\"]|/)", content):
         return "string_literal"
     return None
 
 
 def lockfile_root_sync(head_pkg: dict, head_lock: dict) -> list[str]:
-    """Return a list of warnings if package-lock.json's <root> dep map
-    disagrees with package.json (i.e., npm install was not re-run).
-    """
+    """Warn if package-lock.json's <root> dep map disagrees with package.json
+    (i.e. npm install was not re-run)."""
     warnings = []
     if not head_lock:
         return warnings
@@ -350,10 +323,8 @@ def lockfile_root_sync(head_pkg: dict, head_lock: dict) -> list[str]:
 
 
 def types_orphan_warnings(head_pkg: dict) -> list[str]:
-    """Flag @types/<X> deps where <X> is no longer declared anywhere
-    in package.json. Removing X without also dropping @types/X leaves
-    dangling type packages.
-    """
+    """Flag @types/<X> deps where <X> is no longer declared in package.json,
+    which leaves dangling type packages."""
     decl = set()
     for f in DEP_FIELDS:
         decl.update((head_pkg.get(f) or {}).keys())
@@ -361,9 +332,7 @@ def types_orphan_warnings(head_pkg: dict) -> list[str]:
     for name in decl:
         if not name.startswith("@types/"):
             continue
-        # @types/foo provides types for `foo`
-        # @types/foo-bar provides types for `foo-bar`
-        # @types/scope__pkg provides types for `@scope/pkg`
+        # @types/scope__pkg provides types for @scope/pkg.
         target = name[len("@types/") :]
         if "__" in target:
             scope, sub = target.split("__", 1)
@@ -386,8 +355,7 @@ _PKG_JSON_SKIP_KEYS = {
     "bundledDependencies",
 }
 
-# Top-level fields whose contents are never package references. We walk
-# everything else recursively.
+# Top-level fields whose contents are never package references.
 _PKG_JSON_OPAQUE_KEYS = {
     "browserslist",  # browser queries
     "keywords",  # free-form strings
@@ -429,20 +397,12 @@ _PKG_JSON_OPAQUE_KEYS = {
 
 
 def package_json_extra_refs(pkg: dict, target: str) -> list[str]:
-    """Walk every key/value in package.json EXCEPT the dep declaration
-    blocks, and return citations for string values or dict keys that
-    equal `target` (or `target/subpath`).
+    """Walk package.json (except dep declaration blocks) and return citations
+    for string values or dict keys equal to `target` (or `target/subpath`).
 
-    Catches the patterns the public dep-checker tools commonly miss:
-      - `overrides` / `resolutions` / `pnpm.overrides` keys
-      - `pnpm.patchedDependencies` keys
-      - `peerDependenciesMeta` keys
-      - `prettier`: "@my/prettier-config"
-      - `eslintConfig.extends`: ["..."] / "..."
-      - `stylelint.extends` / `stylelint.plugins`
-      - `babel.presets` / `babel.plugins`
-      - `jest.preset` / `jest.setupFiles` / `jest.transform`
-      - `commitlint.extends`, `renovate.extends`, `remarkConfig.plugins`
+    Catches refs that public dep-checkers commonly miss: overrides/resolutions/
+    pnpm.overrides keys, pnpm.patchedDependencies, peerDependenciesMeta,
+    prettier, eslintConfig.extends, stylelint, babel, jest, commitlint, etc.
     """
     target_sub = target + "/"
     cites: list[str] = []
@@ -453,14 +413,11 @@ def package_json_extra_refs(pkg: dict, target: str) -> list[str]:
     def walk(obj: object, path: str) -> None:
         if isinstance(obj, dict):
             for k, v in obj.items():
-                # Skip top-level dep declaration fields entirely.
                 if path == "" and k in _PKG_JSON_SKIP_KEYS:
                     continue
-                # Top-level fields whose contents are never package refs.
                 if path == "" and k in _PKG_JSON_OPAQUE_KEYS:
                     continue
-                # Inside `overrides` / `resolutions` / etc., the KEY itself
-                # is a package reference.
+                # Inside overrides/resolutions/etc., the KEY is a package ref.
                 if matches(k):
                     cites.append(f"{path}.{k}" if path else k)
                 walk(v, f"{path}.{k}" if path else k)
@@ -476,9 +433,8 @@ def package_json_extra_refs(pkg: dict, target: str) -> list[str]:
 
 
 def build_bin_to_pkg(head_lock: dict) -> dict[str, str]:
-    """Map a binary name (e.g. 'vite', 'tsc', 'eslint') to the package
-    that provides it. Built from each lockfile entry's `bin` field.
-    """
+    """Map a binary name (e.g. 'vite', 'eslint') to its providing package,
+    from each lockfile entry's `bin` field."""
     out: dict[str, str] = {}
     if not head_lock:
         return out
@@ -497,42 +453,29 @@ def build_bin_to_pkg(head_lock: dict) -> dict[str, str]:
 
 _SCRIPT_TOKENIZE = re.compile(r"\s*(?:&&|\|\||;|\|(?!\|))\s*")
 
-# Wrappers that delegate to a real CLI in the same shell word list.
-# After stripping env prefixes and (optionally) `npx`/`pnpm exec`/`yarn dlx`/
-# `bunx`, if the leading token is one of these we advance past the
-# wrapper's own flags and any further env-prefix tokens, then re-check.
-# `cross-env` is the common one; `dotenv-cli` / `dotenvx` use `--` as a
-# separator. Wrappers that operate on named npm-scripts (concurrently,
-# npm-run-all, run-s, run-p, wireit, turbo, nx) intentionally aren't
-# here -- they reference script names, not bin names, so the real bin
-# is in the *target* script's chunk which we already tokenize.
+# Wrappers that delegate to a real CLI in the same shell word list; we skip
+# past them and their flags to find the wrapped bin. Script-name wrappers
+# (concurrently, npm-run-all, turbo, nx) are excluded: they reference script
+# names, so the real bin lives in the target script's chunk we already tokenize.
 _SCRIPT_WRAPPERS = {"cross-env", "dotenv", "dotenvx", "env-cmd"}
 _ENV_PREFIX_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
 
 
 def _next_real_bin(words: list[str], idx: int) -> str | None:
-    """Walk `words` from `idx`, peeling env-prefix tokens, the leading
-    package-manager runner (`npx`, `pnpm exec`, etc.), and the known
-    wrapper bins. Return the next token that looks like the real CLI
-    binary, or None if the chunk has nothing to look up.
-
-    Recursion depth is bounded by the chunk's word count, so the loop
-    cannot run away on a pathological wrapper chain.
-    """
+    """Walk `words` from `idx`, peeling env-prefix tokens, the package-manager
+    runner (npx, pnpm exec, etc.), and known wrapper bins. Return the next
+    real CLI binary, or None. Bounded by the chunk's word count."""
     seen_wrappers: set[str] = set()
     while idx < len(words):
-        # 1. env-prefix run: `FOO=bar BAZ="a b" cmd ...`. shlex has
-        # already collapsed quoted values into one word, so this
-        # tokenizer is safe for them.
+        # 1. env-prefix run `FOO=bar BAZ="a b" cmd ...` (shlex pre-collapsed).
         while idx < len(words) and _ENV_PREFIX_RE.match(words[idx]):
             idx += 1
         if idx >= len(words):
             return None
 
         first = words[idx]
-        # 2. Package-manager runner: `npx <pkg> args`, `pnpm exec <pkg>`,
-        # `yarn dlx <pkg>`, `bunx <pkg>`. Strip and continue (so the
-        # wrapped command goes through the same unwrap loop).
+        # 2. Package-manager runner (npx/pnpm exec/yarn dlx/bunx): strip and
+        # continue so the wrapped command re-enters the unwrap loop.
         if first in {"npx", "pnpx", "bunx"} and idx + 1 < len(words):
             idx += 1
             continue
@@ -540,21 +483,17 @@ def _next_real_bin(words: list[str], idx: int) -> str | None:
             idx += 2
             continue
 
-        # 3. Wrapper bin (cross-env, dotenv, etc.). Skip the wrapper's
-        # own flags and any subsequent env-prefix tokens, then re-loop.
+        # 3. Wrapper bin (cross-env, dotenv): skip its flags and env prefixes.
         bin_token = first.removeprefix("./node_modules/.bin/").removeprefix("node_modules/.bin/")
         if bin_token in _SCRIPT_WRAPPERS and bin_token not in seen_wrappers:
             seen_wrappers.add(bin_token)
             idx += 1
-            # cross-env / env-cmd: no flags; just more env-prefix tokens.
-            # dotenv / dotenvx: skip `-e <file>` style flags and the
-            # optional `--` separator before the wrapped command.
+            # dotenv/dotenvx use `-e <file>` flags and an optional `--`.
             while idx < len(words):
                 tok = words[idx]
                 if tok.startswith("-") and tok != "--":
                     idx += 1
-                    # `-e .env` style: also skip the flag's argument
-                    # when it does not look like another flag.
+                    # `-e .env`: also skip the flag's argument.
                     if (
                         idx < len(words)
                         and not words[idx].startswith("-")
@@ -572,18 +511,12 @@ def _next_real_bin(words: list[str], idx: int) -> str | None:
 
 
 def scripts_bin_refs(head_pkg: dict, bin_to_pkg: dict[str, str]) -> dict[str, list[str]]:
-    """Return `{package_name: ['scripts.X: cmd', ...]}` listing every
-    package referenced via its bin name in package.json scripts.
+    """Return `{package_name: ['scripts.X: cmd', ...]}` for every package
+    referenced via its bin name in package.json scripts.
 
-    Each script value is split on shell separators (`&&`, `||`, `;`,
-    `|`). Within each chunk, `_next_real_bin()` unwraps env prefixes,
-    package-manager runners (`npx` / `pnpm exec` / `yarn dlx` / `bunx`),
-    and wrapper bins like `cross-env` / `dotenv` so that
-    `cross-env CI=1 biome check` correctly credits `biome` to its
-    declaring package.
-
-    Tokenization uses shlex.split so quoted env values
-    (`FOO="a b" biome`) survive unbroken.
+    Each script is split on shell separators; `_next_real_bin()` unwraps env
+    prefixes, package-manager runners, and wrapper bins so `cross-env CI=1
+    biome check` credits `biome`. Uses shlex.split so quoted env values survive.
     """
     import shlex
 
@@ -599,7 +532,7 @@ def scripts_bin_refs(head_pkg: dict, bin_to_pkg: dict[str, str]) -> dict[str, li
             try:
                 words = shlex.split(chunk, posix = True)
             except ValueError:
-                # Unbalanced quotes -- fall back to plain split.
+                # Unbalanced quotes: fall back to plain split.
                 words = chunk.split()
             if not words:
                 continue
@@ -613,11 +546,8 @@ def scripts_bin_refs(head_pkg: dict, bin_to_pkg: dict[str, str]) -> dict[str, li
 
 
 def tsconfig_compiler_types_refs() -> set[str]:
-    """Read studio/frontend/tsconfig*.json and return the set of
-    package names referenced in compilerOptions.types arrays. These are
-    implicitly loaded by tsc and count as a real use even though they
-    have no explicit import.
-    """
+    """Return package names in tsconfig*.json compilerOptions.types arrays.
+    These are implicitly loaded by tsc and count as real uses."""
     out: set[str] = set()
     base = REPO_ROOT / "studio/frontend"
     for name in ("tsconfig.json", "tsconfig.app.json", "tsconfig.node.json"):
@@ -635,26 +565,16 @@ def tsconfig_compiler_types_refs() -> set[str]:
         for t in types:
             if not isinstance(t, str):
                 continue
-            # `vite/client` resolves to `vite` package.
+            # `vite/client` resolves to the `vite` package.
             pkg = t.split("/", 1)[0] if not t.startswith("@") else "/".join(t.split("/", 2)[:2])
             out.add(pkg)
     return out
 
 
 def enumerate_dep_usage(head_pkg: dict, head_lock: dict) -> dict[str, list]:
-    """For every declared dep, classify whether it appears used. Returns
-    a dict with these categories:
-      - used:                 has at least one detected usage in src/,
-                              config files, scripts.bin, package.json
-                              field refs, or tsconfig types
-      - unused:               no detected usage anywhere
-      - type_pkg_kept:        @types/X where X is still declared
-      - type_pkg_orphan:      @types/X where X is no longer declared
-                              (or X is removed) -- candidate for removal
-
-    Each entry is the package name. The categorisation is opinionated;
-    `unused` is a CANDIDATE list, not a guarantee. The caller should
-    verify before deletion.
+    """For every declared dep, classify usage into a dict of package-name lists:
+    used, unused, type_pkg_kept (@types/X with X declared), type_pkg_orphan
+    (@types/X with X gone). `unused` is a CANDIDATE list; verify before deletion.
     """
     decl = all_decl_names(head_pkg)
     bin_to_pkg = build_bin_to_pkg(head_lock) if head_lock else {}
@@ -683,11 +603,8 @@ def enumerate_dep_usage(head_pkg: dict, head_lock: dict) -> dict[str, list]:
         # Real-source-usage check
         hits = find_usage(name)
         used = bool(hits)
-        # CLI usage in shell / workflow / Dockerfile surfaces. Skip for
-        # `@types/*` packages because they never expose a CLI binary and
-        # the unscoped-tail bin name candidate would scan workflow files
-        # for the bare runtime name (a removed `@types/foo` would look
-        # for invocations of `foo`).
+        # CLI usage in shell/workflow/Dockerfile. Skipped for @types/* (no CLI
+        # binary; the bare-name bin candidate would false-match the runtime).
         if not used and not name.startswith("@types/") and find_command_usage(name):
             used = True
         # Bin scripts
@@ -707,28 +624,15 @@ def enumerate_dep_usage(head_pkg: dict, head_lock: dict) -> dict[str, list]:
 
 
 def find_imports_without_decl(head_pkg: dict) -> list[tuple[str, int, str]]:
-    """Reverse check: find bare-specifier imports in studio/frontend/src
-    that don't correspond to any declared package.json dep. Catches the
-    case where someone adds an import but forgets the dep declaration.
-    Returns (file, line, spec) tuples.
-
-    Match shapes covered:
-      import "pkg"
-      import Foo from "pkg"
-      import { Foo } from "pkg"
-      import type { Foo } from "pkg"
-      const x = require("pkg")
-      const x = await import("pkg")
+    """Reverse check: find bare-specifier imports in studio/frontend/src with
+    no matching package.json dep (import added but dep declaration forgotten).
+    Covers import/require/dynamic-import shapes. Returns (file, line, spec).
     """
     decl = set()
     for f in DEP_FIELDS:
         decl.update((head_pkg.get(f) or {}).keys())
-    # Also: anything tsconfig path-aliases (just '@/...' here) is internal.
-    # The capture group is the specifier; the leading alternation accepts
-    # any of: `from "..."`, bare side-effect `import "..."`,
-    # `import("..."), or `require("...")`. We exclude relative paths and
-    # the `@/` alias prefix by requiring the first char of the specifier
-    # to be neither `.` nor `/`.
+    # Exclude relative paths and the `@/` alias by requiring the specifier's
+    # first char to be neither `.` nor `/`. Capture group is the specifier.
     pattern = (
         r"(?:\bfrom\s+|"
         r"\bimport\s+(?:\(\s*)?|"
@@ -754,7 +658,7 @@ def find_imports_without_decl(head_pkg: dict) -> list[tuple[str, int, str]]:
         file, ln, content = m.group(1), int(m.group(2)), m.group(3)
         for spec_match in re.finditer(pattern, content):
             spec = spec_match.group(1)
-            # Resolve to package name (strip subpath)
+            # Resolve to package name (strip subpath).
             if spec.startswith("@"):
                 parts = spec.split("/", 2)
                 pkg_name = "/".join(parts[:2]) if len(parts) >= 2 else spec
@@ -762,7 +666,7 @@ def find_imports_without_decl(head_pkg: dict) -> list[tuple[str, int, str]]:
                 pkg_name = spec.split("/", 1)[0]
             if pkg_name in decl:
                 continue
-            # Internal aliases like '@/foo' or starts with builtin names
+            # Internal aliases like '@/foo' or builtin names.
             if pkg_name == "@":
                 continue
             if pkg_name in {
@@ -807,11 +711,10 @@ def _read_file(path: str) -> list[str]:
 
 
 def find_usage(pkg: str) -> list[Hit]:
-    """Return real usages of `pkg`. Filters pip-playwright separately.
+    """Return real usages of `pkg` (pip-playwright filtered separately).
 
-    For each filename returned by grep, also feed a multi-line window
-    around the matching line into classify() so multi-line imports
-    (`import {\n a\n} from "pkg"`) get picked up.
+    For each grep hit, also feed a multi-line window into classify() so
+    multi-line imports get picked up.
     """
     rows = grep_repo(re.escape(pkg))
     hits = []
@@ -822,10 +725,8 @@ def find_usage(pkg: str) -> list[Hit]:
         # Try the single-line classify first.
         kind = classify(pkg, file, content)
         if not kind:
-            # Multi-line window: a generous 25 lines above + the line +
-            # 25 below so Prettier's one-import-per-line formatting for
-            # 12-20+ named imports still includes the `import` keyword
-            # in the same window as the `from "pkg"` clause.
+            # Multi-line window (25 lines each side) so Prettier's
+            # one-import-per-line formatting still pairs `import` with `from`.
             lines = _read_file(file)
             lo = max(0, lineno - 26)
             hi = min(len(lines), lineno + 25)
@@ -841,28 +742,21 @@ def find_usage(pkg: str) -> list[Hit]:
 
 
 def _candidate_bin_names(pkg: str) -> set[str]:
-    """Names a removed package's CLI could be invoked under in shell
-    scripts and workflow files. Most npm CLIs use the package name
-    (`vite`, `eslint`, `playwright`); scoped CLI packages commonly
-    expose an unscoped binary name (`@biomejs/biome` -> `biome`).
-    """
+    """Bin names a removed package's CLI could be invoked under. Most npm CLIs
+    use the package name; scoped ones expose an unscoped bin (@biomejs/biome ->
+    biome)."""
     return {pkg, pkg.rsplit("/", 1)[-1]}
 
 
 def find_command_usage(pkg: str) -> list[Hit]:
-    """Find package CLI invocations in shell / workflow / Dockerfile
-    surfaces: `npx pkg`, `bunx pkg`, `pnpm exec pkg`, `yarn dlx pkg`,
-    or a bare `pkg --flag`. Returns Hit("command_bin").
-
-    Detection is bounded to COMMAND_LIKE_EXT files so a JS string that
-    happens to contain `npx foo` inside a TS test fixture is not
-    mistaken for a real invocation.
+    """Find package CLI invocations in shell/workflow/Dockerfile surfaces (npx,
+    bunx, pnpm exec, yarn dlx, or bare `pkg --flag`). Bounded to
+    COMMAND_LIKE_EXT so `npx foo` in a TS fixture isn't mistaken for real use.
     """
     bins = sorted(_candidate_bin_names(pkg), key = len, reverse = True)
     esc_bins = "|".join(re.escape(b) for b in bins)
-    # grep ERE pattern (POSIX classes for whitespace/word boundaries).
-    # Build without f-strings to avoid f-string-vs-{} confusion with the
-    # POSIX `[[:space:]]` literals and trailing `})}` boundary class.
+    # grep ERE pattern. Built without f-strings to avoid clashing with the
+    # POSIX `[[:space:]]` literals.
     grep_pat = (
         r"(^|[[:space:]:;&|(\[])"
         r"(npx[[:space:]]+|pnpm[[:space:]]+exec[[:space:]]+"
@@ -894,10 +788,8 @@ def find_command_usage(pkg: str) -> list[Hit]:
 
 
 def types_target_name(pkg: str) -> str | None:
-    """Strip `@types/` prefix and decode the npm scope-encoding so the
-    return value matches the runtime package name. `@types/foo` -> `foo`,
-    `@types/foo__bar` -> `@foo/bar`. Returns None for non-@types packages.
-    """
+    """Strip `@types/` and decode scope-encoding to the runtime package name
+    (`@types/foo__bar` -> `@foo/bar`). None for non-@types packages."""
     if not pkg.startswith("@types/"):
         return None
     target = pkg[len("@types/") :]
@@ -908,11 +800,8 @@ def types_target_name(pkg: str) -> str | None:
 
 
 def find_types_runtime_usage(pkg: str, tsc_types: set[str]) -> list[Hit]:
-    """For a removed `@types/X`, find usages of `X` itself: explicit
-    `/// <reference types="X" />`, `tsconfig.compilerOptions.types: ["X"]`,
-    and runtime `import "X"` shapes. The whole point of `@types/X` is to
-    type one of those; if any are present, the type package must stay.
-    """
+    """For a removed `@types/X`, find usages of `X` itself (triple-slash
+    reference, tsconfig types, runtime import). If any exist, @types/X stays."""
     target = types_target_name(pkg)
     if target is None:
         return []
@@ -997,10 +886,9 @@ def main() -> int:
         return 2
     head_lock = read_pkg_file(head_lock_path)
 
-    # Base lockfile is best-effort. We use it only to recover the
-    # bin -> package mapping for packages the PR is removing -- so a
-    # `scripts.biome:check` cite still fires when `@biomejs/biome` is
-    # being dropped and the head lockfile no longer has it.
+    # Base lockfile is best-effort: only used to recover the bin -> package
+    # mapping for packages the PR removes, so a scripts.biome cite still fires
+    # when @biomejs/biome is dropped from the head lockfile.
     if args.base_lock:
         base_lock_path = Path(args.base_lock)
         base_lock = read_pkg_file(base_lock_path) if base_lock_path.exists() else {}
@@ -1011,9 +899,8 @@ def main() -> int:
     head_names = all_decl_names(head_pkg)
     removed = sorted(base_names - head_names)
 
-    # All hygiene checks compute up front so they can run on both the
-    # removal-present and removal-empty paths (so `--strict` actually
-    # fails when only hygiene issues exist).
+    # Hygiene checks compute up front so they run on both the removal-present
+    # and removal-empty paths (so --strict fails on hygiene-only issues).
     sync_warns = lockfile_root_sync(head_pkg, head_lock)
     types_warns = types_orphan_warnings(head_pkg)
     missing_imports = find_imports_without_decl(head_pkg)
@@ -1074,12 +961,9 @@ def main() -> int:
     print()
 
     reachable_paths = reachable_from_head(head_pkg, head_lock) if head_lock else set()
-    # bin -> package map: start from the head lockfile, then layer the
-    # base lockfile's entries on top for packages this PR is removing.
-    # A correct removal updates the head lockfile to drop node_modules/foo,
-    # so build_bin_to_pkg(head_lock) loses the mapping; we recover it
-    # from the base lockfile so `scripts.biome:check` still flags as a
-    # usage when `@biomejs/biome` is being dropped.
+    # bin -> package map from the head lockfile, layering base-lockfile entries
+    # for removed packages so scripts.biome still flags when @biomejs/biome is
+    # dropped (head lockfile no longer maps it).
     bin_to_pkg = build_bin_to_pkg(head_lock) if head_lock else {}
     base_bin_to_pkg = build_bin_to_pkg(base_lock) if base_lock else {}
     removed_set = set(removed)
@@ -1091,9 +975,8 @@ def main() -> int:
 
     def reachable_install_paths(name: str) -> tuple[str | None, list[str]]:
         """Return (top_level_path, nested_paths). top_level is what bare
-        `import "name"` from src/ actually resolves to; nested copies are
-        only visible inside the parent package that nested them.
-        """
+        `import "name"` resolves to; nested copies are only visible inside
+        their parent package."""
         top = f"node_modules/{name}"
         top_path = top if top in reachable_paths else None
         nested = sorted(
@@ -1106,8 +989,7 @@ def main() -> int:
         hits = find_usage(name)
         # CLI invocations in shell scripts / workflows / Dockerfiles.
         hits.extend(find_command_usage(name))
-        # @types/X is "used" if X is referenced as a type or as a
-        # runtime import elsewhere in the repo.
+        # @types/X is "used" if X is referenced as a type or runtime import.
         hits.extend(find_types_runtime_usage(name, tsc_types))
         for cite in script_refs.get(name, []):
             hits.append(Hit("studio/frontend/package.json", 0, "script_bin", cite))
@@ -1115,9 +997,8 @@ def main() -> int:
             hits.append(Hit("studio/frontend/package.json", 0, "pkg_json_field", cite))
         top, nested = reachable_install_paths(name)
         importable_top_level = top is not None
-        # Source imports of bare specifier `name` resolve ONLY to top-level
-        # node_modules/<name>. Nested copies under another package are
-        # invisible to src/ files.
+        # Bare specifier `name` resolves ONLY to top-level node_modules/<name>;
+        # nested copies are invisible to src/ files.
         if hits and not importable_top_level:
             status = "FAIL"
         elif hits and importable_top_level:
diff --git a/scripts/check_new_install_scripts.py b/scripts/check_new_install_scripts.py
index 2beaada0bf..604d9b9f90 100644
--- a/scripts/check_new_install_scripts.py
+++ b/scripts/check_new_install_scripts.py
@@ -4,33 +4,18 @@
 
 """Diff two `package-lock.json` files and flag NEW install-script deps.
 
-A package with `"hasInstallScript": true` runs `preinstall` / `install` /
-`postinstall` lifecycle hooks every time `npm ci` lays it down. Every
-npm supply-chain compromise of the last 18 months (Shai-Hulud,
-TanStack, axios-style, ArmorCode hijacks) leveraged exactly this lever:
-the attacker publishes a new malicious version of a dep we already
-trust, and the post-install hook runs the next time CI installs.
+A `"hasInstallScript": true` package runs preinstall/install/postinstall
+hooks on every `npm ci` -- the lever behind recent npm supply-chain
+compromises (attacker publishes a malicious version of a trusted dep).
+This refuses to land a newly-introduced install-script dep without a
+maintainer eyeball; pre-existing ones are not re-flagged.
 
-This scanner refuses to allow a newly-introduced install-script dep to
-land without a maintainer eyeball on the lifecycle script body.
-Existing install-script deps are NOT re-flagged -- if `node-gyp` has
-been in the lockfile since day one, it's not part of this PR's threat
-model. Only new entries are surfaced.
+Supports lockfileVersion 1 (recursive `dependencies`) and 2/3 (flat
+`packages` with `node_modules/.../node_modules/...` nesting). For each
+new entry we best-effort fetch the registry metadata to recover the
+postinstall command body; the finding is still emitted if unreachable.
 
-Supports lockfileVersion 1 (`dependencies` key, recursive), 2 and 3
-(flat `packages` key with `node_modules/<a>/node_modules/<b>` nesting
-for transitive entries). For each NEW install-script package we
-attempt a stdlib-only fetch of
-`https://registry.npmjs.org/<name>/<version>` to recover the actual
-postinstall command body. If the network is blocked we still emit the
-finding -- the lifecycle command body is informational, not
-load-bearing.
-
-Exit codes
-==========
-  0  no newly-added install-script deps
-  1  one or more newly-added install-script deps; listed on stderr
-  2  internal error (missing lockfile, malformed JSON, etc.)
+Exit codes: 0 = none; 1 = one or more (on stderr); 2 = internal error.
 """
 
 from __future__ import annotations
@@ -68,21 +53,14 @@ class Finding:
         )
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Lockfile parsing.
-# ─────────────────────────────────────────────────────────────────────
 
 
 def _strip_nm_prefix(key: str) -> str:
-    """Convert a v2/v3 `packages` key into a bare package name.
-
-    `node_modules/foo` -> `foo`; `node_modules/foo/node_modules/bar` ->
-    `bar`. The empty key (`""`) is the project root and returns "".
-    """
+    """Convert a v2/v3 `packages` key into a bare package name (leaf after last `node_modules/`)."""
     if not key:
         return ""
-    # Use the LAST `node_modules/` segment so transitives map to their
-    # leaf name, matching how npm install resolves a postinstall.
+    # LAST node_modules/ segment so transitives map to their leaf name.
     marker = "node_modules/"
     idx = key.rfind(marker)
     if idx == -1:
@@ -91,14 +69,9 @@ def _strip_nm_prefix(key: str) -> str:
 
 
 def _collect_install_script_entries(lock: dict) -> dict[str, str]:
-    """Walk a parsed lockfile and return {package_name: version} for
-    every entry with `hasInstallScript: true` (v2/v3) OR a
-    non-empty `scripts.preinstall|install|postinstall` (v1).
+    """Return {name@version: name} for entries with hasInstallScript (v2/v3) or a lifecycle script (v1).
 
-    The same package may appear at multiple versions in a single
-    lockfile (de-duplicated copies under different parents); we key by
-    `name@version` so we don't lose either copy. Returns a dict keyed
-    by `name@version` -> the same string for convenience.
+    Keyed by name@version so dup copies at different versions aren't lost.
     """
     seen: dict[str, str] = {}
     version = lock.get("lockfileVersion")
@@ -118,10 +91,7 @@ def _collect_install_script_entries(lock: dict) -> dict[str, str]:
         ver = entry.get("version") or "<unversioned>"
         seen[f"{name}@{ver}"] = name
 
-    # v1 also embeds a `dependencies` tree; v2/v3 carry both for
-    # backwards-compat but `packages` is canonical for them. For v1
-    # there is no `hasInstallScript` flag, so look for a non-empty
-    # `scripts.preinstall|install|postinstall` directly.
+    # v1 has no hasInstallScript flag; detect lifecycle scripts directly.
     def _walk_v1(deps: dict, depth: int = 0) -> None:
         if depth > 64 or not isinstance(deps, dict):
             return
@@ -133,8 +103,6 @@ def _collect_install_script_entries(lock: dict) -> dict[str, str]:
                 isinstance(scripts, dict) and scripts.get(hook)
                 for hook in ("preinstall", "install", "postinstall")
             )
-            # v1 also sets `requires` only on the parent, no flag, so
-            # the lifecycle-script presence is the only signal.
             if lifecycle:
                 ver = entry.get("version") or "<unversioned>"
                 seen[f"{name}@{ver}"] = name
@@ -155,19 +123,11 @@ def _load_lockfile(path: Path) -> dict:
         raise ValueError(f"{path}: not valid JSON: {exc}") from exc
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Registry lookup for the postinstall command body (best-effort).
-# ─────────────────────────────────────────────────────────────────────
 
 
 def _fetch_registry_scripts(name: str, version: str) -> dict[str, str] | None:
-    """Return {hook: command} for any of preinstall / install /
-    postinstall published in the registry metadata for this name@ver.
-
-    Returns None on any error (network blocked, 404, malformed JSON).
-    Never raises; the caller treats absence as "could not enrich, emit
-    finding anyway".
-    """
+    """Return {hook: command} for lifecycle hooks in registry metadata; None on any error (never raises)."""
     safe_name = urllib.parse.quote(name, safe = "@/")
     url = f"{REGISTRY_BASE}{safe_name}/{urllib.parse.quote(version)}"
     try:
@@ -190,9 +150,7 @@ def _fetch_registry_scripts(name: str, version: str) -> dict[str, str] | None:
     return keep or None
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Diff.
-# ─────────────────────────────────────────────────────────────────────
 
 
 def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
@@ -203,7 +161,6 @@ def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
         if key in base:
             continue  # pre-existing install-script dep; not in scope
         name = head[key]
-        # key is "name@version"; rsplit("@", 1) handles scoped names.
         version = key[len(name) + 1 :] if key.startswith(name + "@") else "<unversioned>"
         scripts = _fetch_registry_scripts(name, version)
         if scripts:
@@ -226,9 +183,7 @@ def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
     return findings
 
 
-# ─────────────────────────────────────────────────────────────────────
 # CLI.
-# ─────────────────────────────────────────────────────────────────────
 
 
 def main(argv: list[str] | None = None) -> int:
diff --git a/scripts/enforce_kwargs_spacing.py b/scripts/enforce_kwargs_spacing.py
index fdef950d7f..dc4a6d6821 100755
--- a/scripts/enforce_kwargs_spacing.py
+++ b/scripts/enforce_kwargs_spacing.py
@@ -20,13 +20,8 @@ from pathlib import Path
 
 
 def _atomic_write_text(path: Path, data: str, encoding: str) -> None:
-    """Write ``data`` to ``path`` atomically.
-
-    Stages a tmp file in the same directory (so it's on the same
-    filesystem as the destination), fsyncs, then `os.replace`s into
-    place. A crash mid-write therefore leaves either the previous
-    content or the fully new content -- never a truncated source file.
-    """
+    """Write ``data`` to ``path`` atomically via same-dir tmp + fsync + os.replace,
+    so a crash mid-write leaves either the old or full new content, never a truncation."""
     dirpath = str(path.parent) or "."
     fd, tmp_path = tempfile.mkstemp(prefix=".kwargs_fix.", dir=dirpath)
     try:
@@ -142,7 +137,7 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
             lines[start] = segment if segment.strip() else ""
             continue
 
-        # Defensive fall-back for unexpected multi-line 'pass'.
+        # Fall-back for unexpected multi-line 'pass'.
         prefix = lines[start][: node.col_offset]
         lines[start] = prefix if prefix.strip() else ""
         for idx in range(start + 1, end):
@@ -164,15 +159,12 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
 
 
 def remove_blank_after_short_import(text: str) -> tuple[str, bool]:
-    """Drop blank line(s) after an import block in a *small* nested suite.
+    """Drop blank line(s) after an import block in a small nested suite.
 
-    Inside an indented suite of <= 3 statements (function/try/if/with/etc., never
-    module level), when a run of consecutive ``import`` / ``from ... import``
-    statements is directly followed -- across one or more blank lines and nothing
-    else -- by another statement in the same suite, remove those blank lines so
-    the import sits next to the code that uses it. A comment in the gap blocks the
-    rule. Removing blank lines never changes the AST, so this is always
-    semantics-preserving.
+    In an indented suite of <= 3 statements (never module level), when consecutive
+    imports are followed across blank lines (nothing else) by another statement,
+    remove those blanks. A comment in the gap blocks the rule. Removing blank lines
+    never changes the AST.
     """
     try:
         tree = ast.parse(text)
@@ -226,12 +218,11 @@ _DEF_MIN_PARAMS_FOR_MULTILINE = 3  # signatures with < this many params stay one
 
 
 def _def_specs_by_line(tree: ast.AST) -> dict[int, tuple[int, bool]]:
-    """Map the line of each def keyword to (param count, has-any-default).
+    """Map each def keyword line to (param count, has-any-default).
 
-    One def per line, so the line is a stable key. ``*`` / ``/`` markers are not
-    parameters and are not counted. A default exists if any positional default
-    is present or any keyword-only default is not ``None`` (a ``None`` entry in
-    ``kw_defaults`` means a required keyword-only arg).
+    ``*`` / ``/`` markers aren't counted. A default exists if any positional default
+    is present or any keyword-only default is not ``None`` (``None`` in ``kw_defaults``
+    means a required keyword-only arg).
     """
     out: dict[int, tuple[int, bool]] = {}
     for node in ast.walk(tree):
@@ -250,20 +241,12 @@ def _def_specs_by_line(tree: ast.AST) -> dict[int, tuple[int, bool]]:
 
 
 def normalize_def_trailing_comma(text: str) -> tuple[str, bool]:
-    """Force a def / async-def signature one-per-line iff it has >= 3 parameters
-    AND at least one default value; otherwise keep it collapsible.
+    """Force a def signature one-per-line iff >= 3 params AND a default; else collapsible.
 
-    Rationale: signatures with defaults read better one parameter per line, but
-    only once they are non-trivial (< 3 params always stay on one line). A
-    signature with >= 3 params and a default gets a magic trailing comma added
-    (ruff then wraps it one-per-line regardless of length); every other
-    signature has its trailing comma stripped so ruff collapses it onto one line
-    when it fits (and wraps a genuinely long one by length alone).
-
-    Function-definition parameter lists only, never call sites or collection
-    literals. Parameter counts and defaults come from the AST. Run BEFORE ruff
-    format. Adding or removing a def trailing comma never changes the AST, which
-    is re-checked before returning.
+    A qualifying signature gets a magic trailing comma added (ruff wraps it
+    one-per-line); every other signature has its trailing comma stripped so ruff
+    collapses it when it fits. Def parameter lists only, never call sites or
+    collection literals. Run BEFORE ruff format. Never changes the AST (re-checked).
     """
     try:
         tree = ast.parse(text)
@@ -332,12 +315,10 @@ def normalize_def_trailing_comma(text: str) -> tuple[str, bool]:
 
 
 def _split_string_token(s: str) -> tuple[str, str, str] | None:
-    """Split a string literal's source into (prefix, quote, body).
+    """Split a string literal source into (prefix, quote, body).
 
-    ``prefix`` is the letters before the opening quote (``r``/``f``/``b``/``u``
-    in any case/order), ``quote`` is the opening delimiter (``'``, ``"``,
-    ``'''`` or ``\"\"\"``) and ``body`` is everything between the delimiters.
-    Returns ``None`` if ``s`` is not a recognizable string literal.
+    ``prefix`` is the letters before the opening quote, ``quote`` the delimiter,
+    ``body`` everything between. ``None`` if not a recognizable string literal.
     """
     i = 0
     while i < len(s) and s[i] not in ("'", '"'):
@@ -393,15 +374,12 @@ def _string_pieces(
 def _merge_string_run(pieces: list[tuple[str, str]]) -> str | None:
     """Merge a run of adjacent string pieces into one literal's source text.
 
-    ``pieces`` is a list of ``(kind, raw_source)`` where kind is ``"str"`` or
-    ``"f"``. Rules: bytes are left side-by-side (return ``None``); a run with no
-    f-string merges plain/raw/unicode pieces sharing one prefix+quote by simple
-    body concatenation; a run mixing an f-string with at least one plain string
-    (and no bytes, no raw) folds into a single f-string -- f pieces keep their
-    bodies verbatim and plain pieces have their braces escaped (``{`` -> ``{{``).
-    Runs of only f-strings are left side-by-side. The caller re-checks the file
-    AST and drops the change if it differs, so any subtle case (e.g. ``\\N{...}``)
-    that this would mis-handle is caught and skipped.
+    ``pieces`` is ``(kind, raw_source)`` with kind ``"str"`` or ``"f"``. Bytes are
+    left side-by-side (``None``); a run with no f-string merges plain/raw/unicode
+    sharing one prefix+quote by body concatenation; a run mixing an f-string with a
+    plain string (no bytes, no raw) folds into one f-string with plain braces escaped.
+    Runs of only f-strings are left alone. Caller re-checks the AST and drops a
+    differing change, so subtle cases are caught.
     """
     parsed = []
     for kind, raw in pieces:
@@ -455,13 +433,10 @@ def _fold_collapses(
 ) -> bool:
     """Whether an f-string fold at ``row[c0:c1]`` -> ``merged`` is safe to apply.
 
-    Only ``assert`` statements wrap awkwardly when a message is folded: ruff
-    parenthesizes the *condition* once ``assert cond, msg`` no longer fits on one
-    line. For every other construct (call argument, ``raise``, assignment, ...) a
-    folded long message wraps acceptably, so the fold is always allowed. For an
-    ``assert`` the fold is allowed only when the statement is already one physical
-    line, or its estimated one-line length after folding fits the line length;
-    otherwise the message is left side-by-side.
+    Only ``assert`` wraps awkwardly when a message folds (ruff parenthesizes the
+    condition once it no longer fits one line); every other construct wraps
+    acceptably so is always allowed. An ``assert`` fold is allowed only if already
+    one line, or its estimated folded one-line length fits the line length.
     """
     stmt = _enclosing_stmt(tree, row)
     if not isinstance(stmt, ast.Assert):
@@ -483,15 +458,12 @@ def _fold_collapses(
 
 
 def merge_adjacent_string_literals(text: str) -> tuple[str, bool]:
-    """Merge a run of adjacent string literals on ONE physical line into a single
-    literal (the ``"a" "b"`` form ruff emits when it collapses an implicit
-    concatenation). Plain/raw/unicode runs merge by concatenation; a run mixing
-    an f-string with a plain string folds into one f-string (plain parts' braces
-    escaped) -- but only when the statement still fits on one line, so a long
-    message is left side-by-side rather than forcing the statement to re-wrap.
-    Runs of only f-strings, and bytes, are left side-by-side. The whole file's AST
-    is re-checked and the change is dropped if it would differ, so the transform
-    can never change meaning.
+    """Merge adjacent string literals on ONE physical line into a single literal.
+
+    Plain/raw/unicode runs merge by concatenation; an f-string + plain string folds
+    into one f-string (plain braces escaped) only while the statement still fits one
+    line. Runs of only f-strings, and bytes, are left side-by-side. The file AST is
+    re-checked and a differing change dropped, so meaning never changes.
     """
     try:
         toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
@@ -552,17 +524,11 @@ def merge_adjacent_string_literals(text: str) -> tuple[str, bool]:
 def collapse_short_asserts(text: str) -> tuple[str, bool]:
     """Collapse a multi-line ``assert`` onto one line when it would fit.
 
-    An ``assert`` is often kept multi-line only by a magic trailing comma inside
-    a collection / call / tuple-message (``assert x == {\"a\": 1,}`` written
-    across lines). When the whole statement's estimated one-line length fits the
-    line length, strip those trailing commas (the comma before a ``)`` / ``]`` /
-    ``}``) so ruff joins it back onto one line on the following format pass.
-
-    Run BEFORE ruff format. Skips any assert that contains a comment (a comment
-    forces ruff to keep it multi-line, which would oscillate). Stripping a
-    trailing comma is non-semantic except for a one-element tuple ``(x,)``; the
-    file AST is re-checked and any assert whose strip would change it is left
-    alone.
+    When the statement's estimated one-line length fits, strip the magic trailing
+    commas (comma before a closer) holding it open so ruff rejoins it. Run BEFORE
+    ruff format. Skips asserts with a comment (would oscillate). Stripping is
+    non-semantic except for a one-element tuple; AST is re-checked and changing
+    asserts left alone.
     """
     try:
         tree = ast.parse(text)
diff --git a/scripts/lint_workflow_triggers.py b/scripts/lint_workflow_triggers.py
index 34868b7d68..0688f6c65c 100644
--- a/scripts/lint_workflow_triggers.py
+++ b/scripts/lint_workflow_triggers.py
@@ -4,37 +4,19 @@
 
 """Refuse dangerous GitHub Actions trigger patterns at PR time.
 
-Two patterns are banned outright, both of which powered the TanStack
-GHSA-g7cv-rxg3-hmpx supply-chain compromise:
+Bans patterns behind the TanStack GHSA-g7cv-rxg3-hmpx compromise:
 
-1.  `pull_request_target` -- runs a fork's workflow YAML against the
-    BASE repository's secrets and permissions. The fork can inject
-    arbitrary code into the base context. The TanStack worm used this
-    to land base-context execution from a fork PR. There is essentially
-    no safe use of this trigger for a public open-source project;
-    `pull_request` is the safe alternative.
+1.  `pull_request_target` -- runs a fork's workflow against the base
+    repo's secrets/permissions; use `pull_request` instead.
+2.  `workflow_run` chained to a PR-triggered workflow -- same trust
+    boundary problem one hop later (poisoned artifacts/caches run with
+    elevated permissions).
+3.  Cache keys shared between PR-triggered and publish/release/push
+    workflows -- a fork PR could poison a cache the publish workflow
+    restores. Partition the key namespaces.
 
-2.  `workflow_run` chained to a PR-triggered workflow -- carries the
-    same trust boundary problem one hop later. If a PR-triggered
-    workflow can poison artifacts/caches and a `workflow_run` trigger
-    fires off the result with elevated permissions, the attacker still
-    reaches the trusted context.
-
-3.  Shared cache keys between PR-triggered workflows and publish /
-    release / push-triggered workflows. The TanStack worm poisoned the
-    Actions cache from a fork PR and the legitimate release workflow
-    then restored the poisoned cache. Cache keys must be partitioned
-    so that nothing a PR can write is ever read by a workflow that
-    holds secrets.
-
-Exit codes
-==========
-
-  0   no findings
-  1   one or more findings; stderr lists each with file path
-
-Run from repo root:
-    python3 scripts/lint_workflow_triggers.py
+Exit codes: 0 = no findings, 1 = findings (listed on stderr).
+Run from repo root: python3 scripts/lint_workflow_triggers.py
 """
 
 from __future__ import annotations
diff --git a/scripts/lockfile_supply_chain_audit.py b/scripts/lockfile_supply_chain_audit.py
index 5b503dcffe..66b48c094d 100644
--- a/scripts/lockfile_supply_chain_audit.py
+++ b/scripts/lockfile_supply_chain_audit.py
@@ -5,64 +5,21 @@
 """Lockfile supply-chain audit for the Studio frontend and Tauri shell.
 
 Runs BEFORE `npm ci` / `cargo fetch` in CI. Refuses to proceed when a
-lockfile contains patterns that indicate the kind of supply-chain
-injection seen in the npm Shai-Hulud waves and the cargo
-crates.io brand-squat attempts.
+lockfile contains patterns indicating supply-chain injection (npm
+Shai-Hulud waves, cargo crates.io brand-squats).
 
-What it checks
-==============
+Checks package-lock.json (lockfileVersion 2/3): `resolved` URL must be
+the npm registry (direct git/github/file refs are the injection vector);
+`integrity` SHA must be present; known IOC substrings grepped from the
+body. Checks Cargo.lock: `source` must be the crates.io registry index;
+known cargo IOC substrings.
 
-studio/frontend/package-lock.json (lockfileVersion 2 or 3):
+Exit codes: 0 = clean (or skip env var set to a justification >=5 chars,
+not '1'/'true'); 1 = findings; 2 = internal error.
 
-  1. `resolved` URL origin. Every entry must resolve through
-     `https://registry.npmjs.org/`. Direct GitHub-hosted dependencies
-     (`git+ssh://`, `git+https://`, `github:owner/repo#sha`,
-     `file:`, `http://`) are refused -- npm's TanStack incident used
-     exactly this vector to land an unaudited GitHub commit hash as
-     an optional dependency.
-
-  2. `integrity` field presence. Every non-workspace entry must carry
-     an `integrity` SHA. A missing integrity means the registry can
-     swap the tarball after lockfile generation and CI will not
-     notice.
-
-  3. Known IOC strings. A hardcoded set of indicator-of-compromise
-     substrings is grepped across the entire lockfile body (file
-     names, dependency keys, URLs). The list is updated as new
-     campaigns surface. Catching one means the local install was
-     about to pull a publicly-known malicious release.
-
-studio/src-tauri/Cargo.lock:
-
-  4. `source` field origin. Every entry with a `source` must point at
-     `registry+https://github.com/rust-lang/crates.io-index`. Direct
-     git sources (`git+https://...`) and `path+...` for cross-crate
-     paths warrant manual review and are flagged.
-
-  5. Known cargo IOC strings. Same idea as (3), separate list.
-
-Exit codes
-==========
-
-  0  no findings, or an opt-out env var (UNSLOTH_LOCKFILE_AUDIT_SKIP)
-     is set to a justification string (>=5 chars, not '1'/'true'/etc).
-     A value like '1' or 'true' is now REJECTED loudly and the audit
-     runs normally
-  1  one or more findings; stderr lists them with file path and line
-     number where derivable
-  2  internal error (missing dependency, malformed JSON, etc.)
-
-Operational stance
-==================
-
-This scanner only PARSES the lockfiles -- it never executes anything
-in them, never resolves anything against the network. Safe to run
-ahead of every `npm ci`. The IOC list is short by design; this
-complements (not replaces) `npm audit`, OSV-Scanner, and the
-advisory-DB pipeline in `.github/workflows/security-audit.yml`. The
-shape of the catch is "we refuse to proceed because the lockfile
-itself is shaped wrong", which fires before any third-party install
-script gets a chance to run on the runner.
+Only PARSES the lockfiles, never executes or networks. Complements (not
+replaces) `npm audit` / OSV-Scanner / the advisory-DB pipeline. Fires
+before any third-party install script runs on the runner.
 """
 
 from __future__ import annotations
@@ -77,14 +34,9 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[1]
 
 
-# ─────────────────────────────────────────────────────────────────────
-# Known IOC strings (case-sensitive substring match).
-# ─────────────────────────────────────────────────────────────────────
-#
-# Keep these short and FACTUAL. Each entry is tied to a public advisory
-# and is the literal string an attacker would have to embed for the
-# attack to work. Adding speculative or generic patterns here would
-# generate false positives on dependency upgrades.
+# Known IOC strings (case-sensitive substring match). Each is tied to a
+# public advisory; speculative/generic patterns would false-positive on
+# upgrades.
 NPM_IOC_STRINGS: tuple[str, ...] = (
     # Shai-Hulud TanStack wave -- May 11, 2026 (GHSA-g7cv-rxg3-hmpx).
     "router_init.js",
@@ -328,36 +280,22 @@ BLOCKED_NPM_VERSIONS: dict[str, set[str]] = {
 }
 
 CARGO_IOC_STRINGS: tuple[str, ...] = (
-    # Reserved for future cargo-side incidents. Empty by default --
-    # `source` origin check below catches the structural pattern.
+    # Empty by default; the `source` origin check catches the structural
+    # pattern. Reserved for future cargo-side incidents.
 )
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Allowed lockfile origins.
-# ─────────────────────────────────────────────────────────────────────
 NPM_REGISTRY_PREFIX = "https://registry.npmjs.org/"
-
-# Tarballs are also fetched from this mirror on some GH Actions cached
-# runs (npm rewrites the resolved URL on cache hit). Allow either.
 NPM_REGISTRY_PREFIXES_ALLOWED: tuple[str, ...] = (NPM_REGISTRY_PREFIX,)
 
 CARGO_REGISTRY_SOURCE = "registry+https://github.com/rust-lang/crates.io-index"
 
 
-# ─────────────────────────────────────────────────────────────────────
-# Cargo non-registry source allowlist.
-# ─────────────────────────────────────────────────────────────────────
-#
-# Each entry is `(crate_name, exact_source_string)`. The crate must
-# match by name AND the source must match the full pinned-SHA string
-# verbatim. Bumping the commit SHA forces a re-review here: the
-# scanner fires until the new SHA is appended.
-#
-# Studio's Tauri shell pulls `fix-path-env` directly from
-# tauri-apps/fix-path-env-rs because the crate is not published to
-# crates.io. The pinned commit (c4c45d5) was reviewed at the time it
-# landed; future bumps need explicit approval.
+# Cargo non-registry source allowlist: `(crate_name, exact_source_string)`.
+# Both must match verbatim; bumping the pinned SHA forces a re-review.
+# Studio's Tauri shell pulls `fix-path-env` from git because it is not
+# published to crates.io; commit c4c45d5 was reviewed when it landed.
 CARGO_SOURCE_ALLOWLIST: tuple[tuple[str, str], ...] = (
     (
         "fix-path-env",
@@ -367,11 +305,6 @@ CARGO_SOURCE_ALLOWLIST: tuple[tuple[str, str], ...] = (
 )
 
 
-# ─────────────────────────────────────────────────────────────────────
-# Finding container.
-# ─────────────────────────────────────────────────────────────────────
-
-
 class Finding:
     __slots__ = ("path", "package", "kind", "detail")
 
@@ -390,27 +323,19 @@ class Finding:
 
 
 def _gha_escape(text: str) -> str:
-    """Escape a string for use in a GitHub Actions `::warning::` /
-    `::error::` workflow command message. GH Actions truncates
-    annotation messages at the first newline unless `\\n` is
-    escaped as `%0A`; carriage returns and the percent sign need
-    matching escapes per the workflow-commands spec. Order matters:
-    `%` must be replaced first so the subsequent `%0A` / `%0D`
-    sequences are not double-encoded.
+    """Escape a string for a GH Actions `::warning::`/`::error::` message.
+
+    GH Actions truncates at the first newline unless `\\n`/`\\r` are
+    escaped as `%0A`/`%0D`. `%` must be replaced first to avoid
+    double-encoding the subsequent escapes.
     """
     return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
 
 
-# ─────────────────────────────────────────────────────────────────────
-# package-lock.json audit.
-# ─────────────────────────────────────────────────────────────────────
-
-
 def audit_npm_lockfile(path: Path) -> list[Finding]:
     findings: list[Finding] = []
     if not path.exists():
-        # A missing requested lockfile is a config error, not a clean
-        # audit; surface it so a deleted default cannot pass silently.
+        # Missing lockfile is a config error, not a clean audit.
         findings.append(
             Finding(
                 path = str(path),
@@ -427,8 +352,7 @@ def audit_npm_lockfile(path: Path) -> list[Finding]:
     try:
         raw = path.read_text(encoding = "utf-8")
     except OSError as exc:
-        # Permission denied, is-a-directory, broken-pipe etc. -- surface
-        # as a finding instead of crashing CI with a raw traceback.
+        # Surface as a finding instead of crashing CI with a traceback.
         findings.append(
             Finding(
                 path = str(path),
@@ -464,9 +388,7 @@ def audit_npm_lockfile(path: Path) -> list[Finding]:
 
     packages = lock.get("packages") or {}
     for key, entry in packages.items():
-        # The empty key "" is the project root; workspace entries use
-        # keys like "node_modules/foo" or "studio/frontend/sub-pkg".
-        # Skip the project root (it has no `resolved`).
+        # Empty key "" is the project root (no `resolved`); skip it.
         if key == "":
             continue
         if entry.get("link"):
@@ -474,12 +396,8 @@ def audit_npm_lockfile(path: Path) -> list[Finding]:
             continue
 
         resolved = entry.get("resolved")
-        # Entries living inside another package's `node_modules/`
-        # tree are bundled fold-ins -- the parent's tarball ships
-        # their source verbatim and the parent's `integrity` covers
-        # the whole subtree. npm represents them in lockfileVersion 3
-        # as nested entries with no `resolved` and no `integrity` of
-        # their own. Treat them as transparent to this audit.
+        # Entries nested in another package's node_modules are bundled
+        # fold-ins covered by the parent's integrity; treat as transparent.
         nested = key.count("/node_modules/") >= 1
 
         # 1. resolved-URL origin.
@@ -545,12 +463,10 @@ def audit_npm_lockfile(path: Path) -> list[Finding]:
                 )
             )
 
-    # 4. Known IOC strings: scan the raw file body so we hit fields the
-    #    structural pass above doesn't enumerate (scripts, optional
-    #    dependencies, etc.). Cheap and complete.
+    # 4. Known IOC strings: scan the raw body to catch fields the
+    #    structural pass doesn't enumerate (scripts, optional deps, etc.).
     for ioc in NPM_IOC_STRINGS:
         if ioc in raw:
-            # Best-effort line number lookup.
             line_no = _first_line_containing(raw, ioc)
             findings.append(
                 Finding(
@@ -575,14 +491,7 @@ def _first_line_containing(text: str, needle: str) -> int | None:
     return None
 
 
-# ─────────────────────────────────────────────────────────────────────
-# Cargo.lock audit.
-# ─────────────────────────────────────────────────────────────────────
-
-
-# Cargo.lock is TOML; parse with stdlib tomllib (Python 3.11+). The
-# studio's Tauri shell already requires a modern toolchain so this is
-# always available where CI runs.
+# Cargo.lock is TOML; parsed with stdlib tomllib (Python 3.11+).
 _PACKAGE_HEADER = re.compile(r"^\[\[package\]\]\s*$")
 
 
@@ -706,24 +615,15 @@ def audit_cargo_lockfile(path: Path) -> list[Finding]:
     return findings
 
 
-# ─────────────────────────────────────────────────────────────────────
-# CLI.
-# ─────────────────────────────────────────────────────────────────────
-
-
 # Finding kinds split into BLOCKING vs ADVISORY for the default run mode.
-# Blocking findings come from public supply-chain attack indicators (a
-# version we know is malicious, a string an attacker would have to embed
-# for an attack to work). Advisory findings are structural lockfile
-# anomalies (missing integrity, non-default registry, etc.) -- they
-# WARN the maintainer but do not block merges. Pass --strict to make
-# every finding blocking (PR-5479-style behavior for opt-in adopters).
+# Blocking = public attack indicators (known-malicious version, IOC
+# string). Advisory = structural anomalies that warn but don't block.
+# --strict makes every finding blocking.
 BLOCKING_KINDS: frozenset[str] = frozenset(
     {
         "blocked-known-malicious",
         "known-ioc-string",
-        # Internal-failure kinds: a structurally broken lockfile MIGHT
-        # be hiding a real attack, so we keep these blocking too.
+        # A structurally broken lockfile might hide a real attack.
         "malformed-lockfile",
         "missing-lockfile",
         "unreadable-lockfile",
@@ -779,15 +679,9 @@ def main(argv: list[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
-    # SF4: require a real justification (e.g. JIRA ticket id) for the
-    # skip env var. Treat the trivially-set values ("1", "true", "yes",
-    # "on", empty) as INVALID -- they look like accidental flips and
-    # silently bypassed the supply-chain audit. A valid value is a
-    # non-empty string >=5 chars after stripping that does not match
-    # any of the boolean-shaped tokens above. An invalid value emits a
-    # loud GitHub Actions warning to stderr and FALLS THROUGH to run
-    # the audit normally (fail-safe). A valid value emits a warning
-    # naming the reason and skips with rc=0 (compat).
+    # Require a real justification (>=5 chars, not a boolean-shaped token)
+    # for the skip env var. An invalid value warns and falls through to
+    # run the audit (fail-safe); a valid one warns and skips with rc=0.
     _skip_raw = os.environ.get("UNSLOTH_LOCKFILE_AUDIT_SKIP")
     if _skip_raw is not None:
         _skip = _skip_raw.strip()
@@ -809,8 +703,7 @@ def main(argv: list[str] | None = None) -> int:
             return 0
 
     root = Path(args.root).resolve()
-    # Explicit --npm-lockfile/--cargo-lockfile scopes the scan to those
-    # paths; defaults apply only to the no-args CI invocation.
+    # Explicit flags scope the scan; defaults apply only to no-args CI.
     _user_explicit = args.npm_lockfile is not None or args.cargo_lockfile is not None
     if _user_explicit:
         npm_paths = [root / p for p in (args.npm_lockfile or ())]
@@ -835,11 +728,9 @@ def main(argv: list[str] | None = None) -> int:
         )
         return 0
 
-    # Split findings into blocking (known-malicious / IOC / structurally
-    # broken) and advisory (everything else, e.g. missing integrity on a
-    # registry-published tarball). In default mode advisory findings are
-    # printed but do not change the exit code; --strict treats every
-    # finding as blocking.
+    # Split into blocking (known-malicious / IOC / structurally broken)
+    # and advisory (everything else). Default mode prints advisories
+    # without changing the exit code; --strict makes all blocking.
     blocking = [f for f in all_findings if f.kind in BLOCKING_KINDS]
     advisory = [f for f in all_findings if f.kind not in BLOCKING_KINDS]
 
@@ -854,12 +745,8 @@ def main(argv: list[str] | None = None) -> int:
             file = sys.stderr,
         )
         for f in advisory:
-            # Surface in GitHub Actions UI as a warning annotation when run
-            # under Actions; harmless prefix elsewhere. GH Actions
-            # truncates annotation messages at the first newline unless
-            # newlines are escaped as `%0A`, so the full multi-line
-            # Finding (kind + path + package + detail) only renders in
-            # the UI after _gha_escape collapses it onto one line.
+            # GH Actions warning annotation; _gha_escape collapses the
+            # multi-line Finding onto one line so it renders fully in the UI.
             print(f"::warning::{_gha_escape(str(f))}", file = sys.stderr)
             print(file = sys.stderr)
 
@@ -876,9 +763,7 @@ def main(argv: list[str] | None = None) -> int:
         file = sys.stderr,
     )
     for f in blocking:
-        # Same %-encoding rationale as the advisory branch above: the
-        # GH Actions annotation is truncated at the first newline
-        # unless the message is escaped.
+        # Same %-encoding rationale as the advisory branch above.
         print(f"::error::{_gha_escape(str(f))}", file = sys.stderr)
         print(file = sys.stderr)
     print(
diff --git a/scripts/notebook_to_python.py b/scripts/notebook_to_python.py
index cc9dc0acda..4b64123d6a 100644
--- a/scripts/notebook_to_python.py
+++ b/scripts/notebook_to_python.py
@@ -22,19 +22,14 @@ import urllib.parse
 from pathlib import Path
 
 
-# Hosts we are willing to fetch raw notebook JSON from. Anything else
-# is rejected before `urlopen` so a typoed / hostile URL cannot pull
-# code from arbitrary infrastructure.
+# Allowlist of hosts for raw notebook fetches; anything else rejected before urlopen.
 _ALLOWED_NOTEBOOK_HOSTS = {
     "raw.githubusercontent.com",
     "gist.githubusercontent.com",
 }
 
 
-# Shell metacharacters that imply the cell's `!cmd` line cannot be
-# parsed as a flat argv. If any of these appears, `shlex.split` would
-# either fail or, worse, silently strip the operator -- so we keep
-# `shell=True` for that command and emit a review marker.
+# Metacharacters that mean a `!cmd` line can't be a flat argv -> keep shell=True + review marker.
 _SHELL_METACHARS_RE = re.compile(r"\$\(|`|\|\||\||&&|>>?|<<?|\*|\?|;")
 
 
@@ -46,12 +41,8 @@ def needs_fstring(cmd: str) -> bool:
 
 def github_blob_to_raw(url: str) -> str:
     """Convert GitHub blob URL to raw URL."""
-    # https://github.com/user/repo/blob/branch/path
-    #   -> https://raw.githubusercontent.com/user/repo/branch/path
-    # Compare the parsed host exactly (not as a substring) so a URL
-    # like https://attacker.example.com/github.com/blob/... does NOT
-    # get rewritten to a github raw URL. Closes CodeQL alert
-    # py/incomplete-url-substring-sanitization.
+    # github.com/user/repo/blob/branch/path -> raw.githubusercontent.com/user/repo/branch/path
+    # Exact host match (not substring) so attacker.example.com/github.com/blob/... is not rewritten.
     parsed = urllib.parse.urlparse(url)
     if parsed.netloc != "github.com" or "/blob/" not in parsed.path:
         return url
@@ -63,18 +54,12 @@ def github_blob_to_raw(url: str) -> str:
 
 def download_notebook(url: str) -> tuple[str, str]:
     """Download notebook from URL. Returns (content, filename)."""
-    # Convert blob URL to raw if needed
     raw_url = github_blob_to_raw(url)
 
-    # Extract filename from URL
     parsed = urllib.parse.urlparse(raw_url)
     filename = os.path.basename(urllib.parse.unquote(parsed.path))
 
-    # Host allowlist. Refuse to fetch from anywhere the campaign IOC
-    # tables flag (or just anywhere we don't recognise). The blob->raw
-    # conversion above only emits `raw.githubusercontent.com`, so a
-    # rejection here means the caller hand-typed a URL pointing
-    # somewhere we don't trust.
+    # Host allowlist: refuse to fetch from anything we don't recognise.
     host = parsed.hostname
     if host not in _ALLOWED_NOTEBOOK_HOSTS:
         raise ValueError(
@@ -82,7 +67,6 @@ def download_notebook(url: str) -> tuple[str, str]:
             f"{sorted(_ALLOWED_NOTEBOOK_HOSTS)}"
         )
 
-    # Download
     print(f"Downloading {url}...")
     with urllib.request.urlopen(raw_url, timeout = 60) as response:
         content = response.read().decode("utf-8")
@@ -97,29 +81,18 @@ def is_url(path: str) -> bool:
 
 def replace_colab_paths(source: str) -> str:
     """Replace Colab-specific /content/ paths with current working directory."""
-    # Replace /content/ with f-string using _WORKING_DIR
     source = source.replace('"/content/', 'f"{_WORKING_DIR}/')
     source = source.replace("'/content/", "f'{_WORKING_DIR}/")
     return source
 
 
 def _emit_shell_command(indent: str, full_cmd: str, *, allow_shell: bool) -> list[str]:
-    """Render a `!cmd` notebook line as one or more Python statements.
+    """Render a `!cmd` notebook line as Python statements.
 
-    When the command body is f-string-interpolated, contains shell
-    metacharacters, or spans multiple lines, falling back to
-    `shell=True` is the only correct option -- `shlex.split` would
-    either drop operators or fail outright. We surface that with a
-    `# WARNING: shell=True; reviewed for hostile input` comment so a
-    reviewer cannot miss it.
-
-    Otherwise we emit `subprocess.run(shlex.split(cmd), shell=False)`
-    so the converted script is not a re-injection vector if the
-    notebook ever interpolates user-controlled data.
-
-    `allow_shell` defaults to True at the CLI for backwards
-    compatibility. Setting it to False makes `shell=True` emission a
-    hard error (no surprise behaviour).
+    f-string interpolation, shell metacharacters, or multiline force
+    shell=True (shlex.split would drop operators), flagged with a
+    WARNING comment. Otherwise emit shell=False argv form. allow_shell
+    False makes shell=True emission a hard error.
     """
     needs_f = needs_fstring(full_cmd)
     has_meta = bool(_SHELL_METACHARS_RE.search(full_cmd))
@@ -144,7 +117,6 @@ def _emit_shell_command(indent: str, full_cmd: str, *, allow_shell: bool) -> lis
             stmt = f"{indent}subprocess.run({f_prefix}{full_cmd!r}, shell=True)"
         return [warn, stmt]
 
-    # Shell-safe argv form.
     return [f"{indent}subprocess.run(shlex.split({full_cmd!r}), shell=False)"]
 
 
@@ -159,12 +131,10 @@ def convert_cell_to_python(source: str, *, allow_shell: bool = True) -> str:
         stripped = line.strip()
         indent = line[: len(line) - len(line.lstrip())]
 
-        # Skip %%capture
         if stripped.startswith("%%capture"):
             i += 1
             continue
 
-        # Handle %%file magic
         if stripped.startswith("%%file "):
             filename = stripped[7:].strip()
             file_lines = []
@@ -178,7 +148,6 @@ def convert_cell_to_python(source: str, *, allow_shell: bool = True) -> str:
             result.append(f'{indent}    _f.write("""{file_content}""")')
             continue
 
-        # Handle ! shell commands
         if stripped.startswith("!"):
             cmd_lines = [stripped[1:]]
             while cmd_lines[-1].rstrip().endswith("\\") and i + 1 < len(lines):
@@ -308,21 +277,16 @@ def convert_notebook_to_script(
             content = f.read()
         source_name = source
 
-    # Generate output filename
     output_filename = filename.replace(".ipynb", ".py")
-    # Clean up filename
     output_filename = output_filename.replace("(", "").replace(")", "").replace("-", "_")
 
-    # Add output directory if specified
     if output_dir:
         output_path = os.path.join(output_dir, output_filename)
     else:
         output_path = output_filename
 
-    # Convert
     script = convert_notebook(content, source_name, allow_shell = allow_shell)
 
-    # Write output
     with open(output_path, "w", encoding = "utf-8") as f:
         f.write(script)
 
@@ -349,11 +313,7 @@ Examples:
     )
     parser.add_argument("notebooks", nargs = "+", help = "Notebook files or URLs to convert.")
     parser.add_argument("-o", "--output", dest = "output_dir", default = ".", help = "Output directory.")
-    # Default True for backwards compatibility: existing Colab notebooks
-    # routinely use pipes / redirection / interpolation in `!cmd` lines
-    # and the converted script needs to keep working. Operators who
-    # convert untrusted notebooks should pass --no-allow-shell to force
-    # a hard error on every metacharacter-bearing cell.
+    # Default True for backwards compat; pass --no-allow-shell for untrusted notebooks.
     parser.add_argument(
         "--allow-shell",
         dest = "allow_shell",
@@ -371,14 +331,9 @@ Examples:
 
     args = parser.parse_args()
 
-    # Create output directory if needed
     os.makedirs(args.output_dir, exist_ok = True)
 
-    # SF2: track per-notebook failures so a CI invocation that converts
-    # 10 notebooks but silently fails on 3 is no longer reported as
-    # success. Each failure is collected and the loop continues so the
-    # caller sees the full set; final exit status is 1 if anything
-    # failed.
+    # Track per-notebook failures; continue the loop and exit 1 if any failed.
     failures: list[tuple[str, str]] = []
     ok = 0
     total = len(args.notebooks)
diff --git a/scripts/notebook_validator.py b/scripts/notebook_validator.py
index 74bfaa8d41..c1be7a63a4 100644
--- a/scripts/notebook_validator.py
+++ b/scripts/notebook_validator.py
@@ -49,12 +49,9 @@ from typing import Any, Iterable, Iterator
 
 
 def _atomic_write_bytes(path: pathlib.Path, data: bytes) -> None:
-    """Atomic write helper. See `scripts/scan_packages.py::update_req_file`.
-
-    A crash between `mkstemp` and `os.replace` leaves the prior file
-    untouched, so a half-downloaded PyPI metadata cache file cannot
-    poison subsequent runs of the validator.
-    """
+    """Atomic write (see scripts/scan_packages.py::update_req_file). A crash
+    between mkstemp and os.replace leaves the prior file intact, so a
+    half-downloaded cache file can't poison later runs."""
     path.parent.mkdir(parents = True, exist_ok = True)
     dirpath = str(path.parent) or "."
     fd, tmp_path = tempfile.mkstemp(prefix = ".nb_val.", dir = dirpath)
@@ -81,12 +78,10 @@ COLAB_PIP_FREEZE_URL = (
 )
 COLAB_FALLBACK_FILE = DATA_DIR / "colab_pip_freeze.gpu.txt"
 
-# Oracle files we snapshot from googlecolab/backend-info. The diff
-# subcommand fetches each, compares against the committed snapshot,
-# and surfaces NEW / REMOVED / CHANGED entries so upstream Colab base
-# image rotations land in CI within ~24h instead of when a notebook
-# breaks. Every rule in this validator that resolves against the
-# Colab preinstall (R-INST-002/003/004/005) gets earlier signal.
+# Oracle files snapshotted from googlecolab/backend-info. The colab-diff
+# subcommand surfaces NEW/REMOVED/CHANGED entries so upstream Colab base
+# image rotations land in CI within ~24h, giving R-INST-002/003/004/005
+# earlier signal.
 COLAB_ORACLE_FILES: dict[str, str] = {
     "pip-freeze.gpu.txt": "colab_pip_freeze.gpu.txt",
     "apt-list-gpu.txt": "colab_apt_list.gpu.txt",
@@ -145,9 +140,8 @@ class Finding:
 def iter_notebooks(
     notebooks_dir: pathlib.Path, include_templates: bool = False
 ) -> Iterator[pathlib.Path]:
-    """Yield user-facing .ipynb files under nb/ and kaggle/. Pass
-    include_templates=True to also walk original_template/ (used by the
-    convert subcommand which doesn't lint install cells)."""
+    """Yield user-facing .ipynb files under nb/ and kaggle/.
+    include_templates=True also walks original_template/ (for convert)."""
     subs = ("nb", "kaggle")
     if include_templates:
         subs = ("nb", "kaggle", "original_template")
@@ -198,11 +192,8 @@ def install_cells(nb: dict[str, Any]) -> list[tuple[int, str]]:
     return out
 
 
-# Notebook target environment. The Colab oracle (pip-freeze.gpu.txt) only
-# applies to notebooks that actually run on Colab; AMD-Dev-Cloud,
-# Kaggle, HuggingFace-Course, and DGX-Spark notebooks have their own
-# preinstalled environments and the Colab-vs-cell rules are not
-# applicable to them.
+# Colab oracle only applies to notebooks that run on Colab; AMD, Kaggle,
+# DGX-Spark have their own preinstalls and the Colab-vs-cell rules don't apply.
 def target_environment(notebook_name: str) -> str:
     parts = pathlib.PurePath(notebook_name).parts
     base = parts[-1] if parts else notebook_name
@@ -466,19 +457,12 @@ def constraint_satisfied(version: str, ops: list[tuple[str, str]]) -> bool:
 
 
 def resolved_set(install_cell: str, colab: dict[str, str]) -> dict[str, str]:
-    """Merge install-cell explicit constraints with Colab pip-freeze. Cell
-    wins.
+    """Merge install-cell constraints with Colab pip-freeze (cell wins).
 
-    Resolution order per package, when more than one form is present:
-      1. Exact `==V` pin in any install line  (definitive).
-      2. Upper-bound `<=V` constraint         (pip picks the highest
-                                                allowed; that's V).
-      3. Colab pip-freeze fallback.
-
-    The lower-bound `>=V` is intentionally NOT reflected here — a `>=V`
-    by itself doesn't change the resolved version when a higher
-    Colab-preinstalled version is already in scope. (R-INST-003 calls
-    `_install_cell_lower_bound` separately to model that case.)
+    Resolution order per package: (1) exact `==V` pin, (2) upper-bound `<=V`
+    (pip picks the highest allowed = V), (3) Colab fallback. Lower-bound `>=V`
+    is intentionally NOT reflected (it doesn't lower an already-higher Colab
+    version); R-INST-003 models that via `_install_cell_lower_bound`.
     """
     out = dict(colab)
     pinned: set[str] = set()
@@ -543,8 +527,7 @@ def rule_inst_002_no_deps_transitive(
             v = explicit_pin(sp)
             if v is None:
                 continue
-            # Check transitive constraints on a curated short list of pkgs we
-            # care about (transformers/peft/trl/accelerate/torchao/torchcodec).
+            # Check transitive constraints on a curated short list of pkgs.
             for target in (
                 "tokenizers",
                 "torchao",
@@ -575,10 +558,9 @@ def rule_inst_002_no_deps_transitive(
 
 
 def _install_cell_lower_bound(install_cell: str, target: str) -> str | None:
-    """Return the highest LOWER bound that any install line places on `target`,
-    or None if no constraint is present. Treats `==V` as both lower and upper.
-    Used by R-INST-003: a `pip install torchao>=0.16.0` line is enough to
-    satisfy a `torchao>=0.16.0` floor even though it's not a `==` pin."""
+    """Return the highest lower bound any install line places on `target`
+    (treating `==V` as both bounds), or None. Used by R-INST-003 so a
+    `torchao>=0.16.0` line satisfies the floor without a `==` pin."""
     best: str | None = None
     for inv in iter_pip_invocations(install_cell):
         for raw in inv.packages:
@@ -652,20 +634,17 @@ def rule_inst_004_torchcodec_torch(
 def rule_inst_005_transformers_tokenizers(
     install_cell: str, colab: dict[str, str], file: str, cell_idx: int
 ) -> list[Finding]:
-    """Fires only when transformers is installed with `--no-deps`. Without
-    `--no-deps`, pip resolves the correct tokenizers transitively, so the
-    rule would be a false positive (this is the case for older notebooks
-    that pin `transformers==4.51.3` but rely on pip's transitive resolver).
-    The rule targets the exact pattern PR #261b / #264 fixed:
-    `pip install --no-deps transformers==X` next to a Colab preinstall
-    `tokenizers` outside transformers's window."""
+    """Fires only when transformers is installed with `--no-deps` (otherwise
+    pip resolves tokenizers transitively and flagging would be a false
+    positive). Targets the PR #261b/#264 pattern: `--no-deps transformers==X`
+    next to a Colab `tokenizers` outside transformers's window."""
     findings: list[Finding] = []
     res = resolved_set(install_cell, colab)
     tf = res.get("transformers")
     tok = res.get("tokenizers")
     if not tf or tok is None:
         return findings
-    # Find the install line that pins transformers and check for --no-deps.
+    # Find the transformers pin and check for --no-deps.
     transformers_line_no_deps = False
     for inv in iter_pip_invocations(install_cell):
         for raw in inv.packages:
@@ -724,11 +703,9 @@ def rule_inst_006_double_bang(install_cell: str, file: str, cell_idx: int) -> li
 
 class _APIScanner(ast.NodeVisitor):
     """Scan user-facing code cells for known deprecated patterns. R-API-001
-    (`for_training`/`for_inference`) is intentionally absent: those helpers
-    are still part of the live unsloth surface as of 2026-05; PR #221 removed
-    the calls cosmetically from Vision notebooks but did not deprecate the
-    methods. R-API-004 (live API surface diff) catches actual removals
-    dynamically without us hand-coding them."""
+    (`for_training`/`for_inference`) is intentionally absent: those helpers are
+    still live as of 2026-05 (PR #221 removed them cosmetically, not as a
+    deprecation). R-API-004 catches actual removals dynamically."""
 
     def __init__(self, file: str, cell_idx: int):
         self.file = file
@@ -736,14 +713,10 @@ class _APIScanner(ast.NodeVisitor):
         self.findings: list[Finding] = []
 
     def visit_Call(self, node: ast.Call) -> None:
-        # SFTConfig with suboptimal optim  (R-API-003).
-        # NOTE: PR #221 also stripped `gradient_checkpointing` /
-        # `gradient_checkpointing_kwargs` from a handful of vision notebooks,
-        # but those kwargs are still accepted by live TRL (verified against
-        # trl==0.25.1 in the unsloth workspace) so removing them was
-        # cosmetic, not a deprecation. We do NOT flag them. R-API-004 (live
-        # API surface diff in the api subcommand) is the right way to catch
-        # actual TRL signature drift.
+        # SFTConfig with suboptimal optim (R-API-003).
+        # NOTE: PR #221 also stripped gradient_checkpointing kwargs from some
+        # vision notebooks, but they're still accepted by live TRL (trl==0.25.1)
+        # so that was cosmetic. We don't flag them; R-API-004 catches real drift.
         if isinstance(node.func, ast.Name) and node.func.id == "SFTConfig":
             for kw in node.keywords:
                 if (
@@ -799,13 +772,9 @@ POLICY_CLAUSES_DEFAULT = [
 
 
 def extract_policy_clauses(update_script: pathlib.Path) -> list[tuple[str, re.Pattern[str], Any]]:
-    """Best-effort: scan update_all_notebooks.py for canonical phrases used by
-    multiple templates. Falls back to POLICY_CLAUSES_DEFAULT.
-
-    Today we use POLICY_CLAUSES_DEFAULT directly; the regex form is
-    intentionally permissive so a template-side reword (e.g. comment changes)
-    doesn't cause false positives. New clauses become 1-line PRs to this list.
-    """
+    """Best-effort scan of update_all_notebooks.py for canonical phrases;
+    falls back to POLICY_CLAUSES_DEFAULT (which we use directly today). The
+    permissive regexes avoid false positives on template rewords."""
     return list(POLICY_CLAUSES_DEFAULT)
 
 
@@ -868,14 +837,9 @@ def cmd_drift(args: argparse.Namespace) -> int:
         check = False,
         capture_output = True,
     )
-    # SF3: the restore MUST run even on SystemExit / KeyboardInterrupt /
-    # segfault-propagated exception, otherwise the user's working tree
-    # silently stays rolled back into the stash. A bare try/finally
-    # (NOT try/except/finally) preserves the original exception and
-    # still runs the cleanup. The pre-existing try/except around
-    # `subprocess.run` of the updater is folded inside the new outer
-    # try so its early returns still happen, but the stash pop is
-    # protected.
+    # The restore MUST run even on SystemExit/KeyboardInterrupt, else the
+    # working tree stays rolled back into the stash. A bare try/finally keeps
+    # the original exception while still running the cleanup (stash pop).
     findings: list[Finding] = []
     rc: int
     try:
@@ -920,8 +884,7 @@ def cmd_drift(args: argparse.Namespace) -> int:
                         )
                 rc = 0 if not findings else 1
     finally:
-        # Restore the working tree. Both commands MUST run regardless of
-        # how the try block exited (including SystemExit/KeyboardInterrupt).
+        # Restore the working tree (both commands run regardless of exit path).
         subprocess.run(
             ["git", "-C", str(nbdir), "checkout", "."],
             check = False,
@@ -1004,19 +967,16 @@ def cmd_lint(args: argparse.Namespace) -> int:
             continue
         rel = str(path.relative_to(nbdir))
         env = target_environment(rel)
-        # The Colab oracle is the source of truth ONLY for Colab notebooks.
-        # Other targets (amd / kaggle / dgx_spark) have their own runtime
-        # preinstall sets that aren't tracked here yet, so we apply the
-        # environment-agnostic rules and skip the Colab-specific ones.
+        # Colab oracle applies only to Colab notebooks; other targets get the
+        # environment-agnostic rules only (their preinstalls aren't tracked).
         oracle = colab if env == "colab" else {}
         cells = install_cells(nb)
-        # Per-cell rules: forbid-pattern checks scoped to a single line.
+        # Per-cell forbid-pattern checks.
         for idx, cell in cells:
             findings += rule_inst_001_git_plus(cell, rel, idx)
             findings += rule_inst_006_double_bang(cell, rel, idx)
-        # Whole-notebook rules: a notebook's install steps are sometimes split
-        # across multiple cells (initial install + post-install bumps). Merge
-        # all install cells before resolving compat against Colab.
+        # Whole-notebook rules: install steps may span multiple cells, so merge
+        # before resolving compat against Colab.
         merged = "\n".join(c for _, c in cells)
         if env == "colab" and merged:
             first_cell = cells[0][0] if cells else None
@@ -1147,8 +1107,7 @@ def _parse_apt_lines(text: str) -> dict[str, str]:
 
 
 def _parse_os_lines(text: str) -> dict[str, str]:
-    """Free-form `<tool> <version>` lines. Skip comments. The key is the
-    first token lower-cased; the value is the rest of the line."""
+    """Free-form `<tool> <version>` lines -> {tool_lower: rest}."""
     out: dict[str, str] = {}
     for line in text.splitlines():
         line = line.strip()
@@ -1185,10 +1144,9 @@ def _diff_oracle(
 
 
 def cmd_colab_diff(args: argparse.Namespace) -> int:
-    """Fetch every Colab oracle file in COLAB_ORACLE_FILES, diff against
-    the committed snapshot, and print NEW / REMOVED / CHANGED. Advisory
-    by default (rc=0); --strict promotes any diff to rc=1 so the daily
-    cron can fail loudly when upstream rotates."""
+    """Diff each Colab oracle file against its committed snapshot and print
+    NEW/REMOVED/CHANGED. Advisory (rc=0) by default; --strict makes any diff
+    rc=1 so the daily cron fails loudly on upstream rotation."""
     snapshot_dir = pathlib.Path(args.snapshot_dir).resolve()
     any_diff = False
     for upstream_name, snapshot_name in COLAB_ORACLE_FILES.items():
diff --git a/scripts/run_ruff_format.py b/scripts/run_ruff_format.py
index 2f0a6c6bba..817565eddf 100755
--- a/scripts/run_ruff_format.py
+++ b/scripts/run_ruff_format.py
@@ -19,10 +19,8 @@ def main(argv: list[str]) -> int:
 
     spacing_script = HERE / "enforce_kwargs_spacing.py"
 
-    # Pre-ruff: normalize def-signature trailing commas (>=3 params with a
-    # default -> one-per-line; everything else collapsible) and strip the magic
-    # comma from a short multi-line assert, so ruff wraps signatures accordingly
-    # and joins the assert back onto one line.
+    # Pre-ruff: normalize def-signature magic commas and strip the magic comma
+    # from short multi-line asserts so ruff wraps/joins accordingly.
     pre_cmd = [sys.executable, str(spacing_script), "--pre", *files]
     pre_proc = subprocess.run(pre_cmd)
     if pre_proc.returncode != 0:
diff --git a/scripts/scan_npm_packages.py b/scripts/scan_npm_packages.py
index 14a3cd6560..fe90afa7e6 100644
--- a/scripts/scan_npm_packages.py
+++ b/scripts/scan_npm_packages.py
@@ -7,73 +7,32 @@
 
 """scan_npm_packages.py -- npm-side content scanner.
 
-Counterpart to scripts/scan_packages.py for the pip ecosystem. Reads
+npm counterpart to scripts/scan_packages.py. Reads
 studio/frontend/package-lock.json, downloads each resolved tarball
 DIRECTLY from registry.npmjs.org (never via `npm install` -- no
-lifecycle scripts ever run), verifies the lockfile integrity hash,
-unpacks each tarball into a sandboxed temp dir behind size / count /
-path-escape / symlink guards, and pattern-scans the extracted file
-contents for the signatures common to npm supply-chain attacks:
+lifecycle scripts run), verifies the lockfile integrity hash, unpacks
+each into a sandboxed temp dir behind size/count/path-escape/symlink
+guards, and pattern-scans extracted contents for npm supply-chain
+attack signatures: malicious lifecycle scripts, C2 / exfil hosts,
+credential-stealing references, known IOC filenames, and obfuscation
+shapes.
 
-  - Lifecycle (preinstall / install / postinstall / prepare) scripts
-    in any package.json that fetch + execute external code.
-  - C2 / exfiltration hosts (getsession.org, AWS IMDS endpoints,
-    Kubernetes ServiceAccount token paths, GitHub Actions OIDC,
-    HashiCorp Vault endpoints).
-  - Credential-stealing references (~/.npmrc, ~/.aws/credentials,
-    GITHUB_TOKEN / NPM_TOKEN in JS sources).
-  - Known IOC filenames from public advisories
-    (router_init.js, tanstack_runner.js, router_runtime.js).
-  - Obfuscation shapes (large single JS in package root with a low
-    whitespace ratio + Function/eval against a base64-decoded blob).
-
-Safety stance
-=============
-
-This script ingests attacker-controlled archives. Every parse path
-assumes the worst:
-
-  1. Downloads ONLY from `registry.npmjs.org`. Any tarball URL with a
-     different hostname is refused without fetching.
-  2. Tarball download is size-capped (HARD_MAX_TARBALL_BYTES default
-     64 MiB). HEAD-style probe via the Content-Length response header
-     plus a chunked read that aborts on overflow.
+Safety stance (ingests attacker-controlled archives; assumes worst):
+  1. Downloads ONLY from registry.npmjs.org; other hosts refused.
+  2. Tarball download size-capped via Content-Length probe + chunked
+     read that aborts on overflow.
   3. SHA-512 integrity verified against the lockfile entry BEFORE the
-     tarball is even opened. A mismatch aborts that package -- the
-     scanner does not "fall back" to the registry-published hash.
-  4. tar extraction goes through `safe_extract`:
-        - rejects symbolic links (`SYMTYPE`, `LNKTYPE`)
-        - rejects absolute paths, `..` traversal, paths outside the
-          extract root after resolution
-        - rejects character / block / FIFO devices
-        - per-file uncompressed size cap (HARD_MAX_FILE_BYTES, default
-          8 MiB) AND cumulative cap (HARD_MAX_TOTAL_BYTES, default
-          128 MiB) AND member-count cap (HARD_MAX_MEMBERS, default
-          50_000)
-        - tar reads happen via `tarfile.open(mode='r|gz')` streaming
-          so an oversized file is detected before write
-  5. NOTHING from the extracted tree is ever executed. Files are read
-     as raw bytes, decoded with `errors='replace'`, and grepped. We
-     never call `node`, `eval`, `compile`, `subprocess.run`,
-     `os.system`, or anything that would touch the tarball's
-     declared scripts.
-  6. Tempdir is created with `tempfile.mkdtemp(prefix='npm-scan-')`,
-     fully resolved with .resolve(), and registered with atexit to be
-     wiped on every termination path.
-  7. Stdlib only. No third-party deps -- adding one would itself be a
-     supply-chain liability.
+     tarball is opened; mismatch aborts that package (no fallback).
+  4. tar extraction via `safe_extract`: rejects symlinks, absolute /
+     `..` paths, device files; enforces per-file, cumulative, and
+     member-count caps; streams (`r|gz`) so oversize is caught early.
+  5. NOTHING extracted is executed -- files are read as bytes and
+     grepped only.
+  6. Tempdir resolved and atexit-wiped on every termination path.
+  7. Stdlib only (a dep would be a supply-chain liability itself).
 
-Exit codes
-==========
-
-  0  no findings of severity HIGH or higher
-  1  one or more HIGH/CRITICAL findings (or pre-scan structural
-     anomalies -- non-registry resolved URL, missing integrity)
-  2  internal error (lockfile missing, integrity mismatch on
-     download, malformed tarball, etc.)
-
-The script is meant to be run in CI on every PR that touches
-package-lock.json and on a nightly schedule.
+Exit codes: 0 = no HIGH+ findings; 1 = HIGH/CRITICAL or pre-scan
+structural anomaly; 2 = internal error. Run in CI per-PR and nightly.
 """
 
 from __future__ import annotations
@@ -565,12 +524,9 @@ CRED_HOST_NEEDS_CONTEXT: tuple[tuple[str, str], ...] = (
     ),
 )
 
-# Credentials a frontend package should NEVER need to read. Bare
-# substring match is too noisy (object-treeify ships a `docker` dev
-# script that mounts ~/.npmrc -- legitimate dev tooling, never run
-# at install time). We instead surface these only when they appear
-# inside a LIFECYCLE script (preinstall / install / postinstall /
-# prepare), which is the only path that runs automatically on
+# Credentials a frontend package should never read. Bare substring
+# match is too noisy (legit dev tooling mounts ~/.npmrc), so we flag
+# these only inside lifecycle scripts -- the only auto-run path on
 # `npm ci`. See `scan_package_json` below.
 CRED_PATH_SUBSTRINGS: tuple[tuple[str, str], ...] = (
     ("/.npmrc", "npm credentials file"),
@@ -603,9 +559,8 @@ _JS_FETCH_EVAL = re.compile(
     """,
 )
 
-# `process.env.GITHUB_TOKEN` / `NPM_TOKEN` / `AWS_*` access in
-# top-level / install-time code is suspicious. We also catch
-# `os.environ["GITHUB_TOKEN"]` for the rare Python-in-npm postinstall.
+# Token env access in install-time code; also catches os.environ[...]
+# for the rare Python-in-npm postinstall.
 _JS_ENV_TOKEN = re.compile(
     r"""(process\.env\.|os\.environ\[?['"])(?:
         GITHUB_TOKEN | GH_TOKEN | NPM_TOKEN | NODE_AUTH_TOKEN
@@ -616,11 +571,9 @@ _JS_ENV_TOKEN = re.compile(
     re.VERBOSE,
 )
 
-# Suspicious lifecycle-script payloads. Anything in a package.json
-# `scripts` field that wgets/curls an external resource and executes
-# it. We do NOT block ALL curl/wget in scripts (some legit packages
-# fetch test fixtures into devDependencies), but we DO block the
-# fetch+exec chain.
+# Lifecycle-script fetch+exec chain: curl/wget an external resource
+# and run it. Bare curl/wget is allowed (legit fixture fetches); only
+# the fetch+exec chain is blocked.
 _LIFECYCLE_FETCH_EXEC = re.compile(
     r"""(?xs)
     (?:curl|wget|fetch|http\.get|axios\.get)\s+ # fetch verb
@@ -634,9 +587,8 @@ _LIFECYCLE_FETCH_EXEC = re.compile(
     """,
 )
 
-# Obfuscation: large JS file that is mostly one line of base64-ish
-# blob with a Function() / eval() bookend. Tuned against the
-# router_init.js shape (2.3 MB obfuscated single-blob).
+# Obfuscation: large single-line base64-ish blob behind Function()/
+# eval(). Tuned against the router_init.js shape (2.3 MB blob).
 _OBFUSC_BLOB = re.compile(
     r"""(?xs)
     (?:Function|eval)\s*\(\s*['"`]?
@@ -653,11 +605,9 @@ _OBFUSC_BLOB = re.compile(
 def parse_lockfile(path: Path) -> tuple[list[PackageEntry], list[Finding]]:
     """Return (entries, structural_findings).
 
-    Structural findings here are HIGH-severity refusals that should
-    short-circuit the scan -- a lockfile with non-registry resolved
-    URLs is itself a finding (covered by scripts/lockfile_supply_chain
-    _audit.py in detail; we surface a summary here so this scanner is
-    standalone-runnable).
+    Structural findings are HIGH-severity refusals that short-circuit
+    the scan (e.g. non-registry resolved URLs). A summary is surfaced
+    here so this scanner is standalone-runnable.
     """
     entries: list[PackageEntry] = []
     findings: list[Finding] = []
@@ -701,9 +651,8 @@ def parse_lockfile(path: Path) -> tuple[list[PackageEntry], list[Finding]]:
         resolved = entry.get("resolved")
         if not resolved:
             continue
-        # Strict registry origin check. lockfile_supply_chain_audit
-        # already catches this; double-defend here so this scanner
-        # cannot be tricked into fetching from an attacker-chosen URL.
+        # Strict registry origin check so this scanner can't be tricked
+        # into fetching from an attacker-chosen URL.
         parsed = urllib.parse.urlparse(resolved)
         if parsed.scheme != "https" or parsed.hostname != ALLOWED_DOWNLOAD_HOST:
             findings.append(
@@ -775,16 +724,12 @@ def download_tarball(
     timeout: float = HARD_HTTP_TIMEOUT_S,
     max_bytes: int = HARD_MAX_TARBALL_BYTES,
 ) -> tuple[Path, str | None]:
-    """Stream-download entry.resolved to dest. Verify SRI integrity.
+    """Stream-download entry.resolved to dest and verify SRI integrity.
 
-    Returns (downloaded_path, error_or_none). On any error the
-    returned path may not exist. Network access is restricted to
-    https://{ALLOWED_DOWNLOAD_HOST}/ -- the caller passes a Request
-    we already validated.
+    Returns (downloaded_path, error_or_none); on error the path may not
+    exist. Network access is restricted to ALLOWED_DOWNLOAD_HOST.
     """
-    # Re-assert hostname; the entry was validated at parse time but a
-    # defence-in-depth check here means a future refactor cannot
-    # accidentally bypass it.
+    # Re-assert hostname (defence-in-depth against a future refactor).
     parsed = urllib.parse.urlparse(entry.resolved)
     if parsed.scheme != "https" or parsed.hostname != ALLOWED_DOWNLOAD_HOST:
         return dest, (f"refused download from non-allowlisted URL {entry.resolved!r}")
@@ -873,8 +818,7 @@ def safe_extract(
     total = 0
     count = 0
     try:
-        # Open in streaming mode so we never seek backwards in the
-        # input. `r|gz` rejects malformed gzip frames immediately.
+        # Streaming mode (no backward seeks); `r|gz` rejects bad gzip.
         with tarfile.open(tarball_path, mode = "r|gz") as tf:
             for member in tf:
                 count += 1
@@ -889,9 +833,8 @@ def safe_extract(
                     return f"refused link member {name!r} (sym/lnk)"
                 if member.isdev() or member.isfifo():
                     return f"refused special member {name!r}"
-                # Cumulative cap is checked against DECLARED size up
-                # front to short-circuit obvious bombs without reading
-                # the body.
+                # Check declared size up front to short-circuit bombs
+                # without reading the body.
                 declared = max(member.size, 0)
                 if declared > HARD_MAX_BINARY_FILE_BYTES:
                     return (
@@ -903,9 +846,8 @@ def safe_extract(
                         f"cumulative bytes {total + declared} > cap "
                         f"{max_total_bytes} at {name!r}"
                     )
-                # Strip leading "package/" -- the npm convention. We do
-                # NOT trust npm to be right, so we explicitly resolve
-                # the destination and refuse anything that escapes.
+                # Resolve destination and refuse anything escaping root
+                # (don't trust the npm "package/" convention).
                 dest = extract_root / name
                 if not _is_within(extract_root, dest):
                     return f"refused escape: {name!r} resolved outside root"
@@ -919,10 +861,8 @@ def safe_extract(
                 src = tf.extractfile(member)
                 if src is None:
                     continue
-                # Sniff first 16 bytes to classify text vs binary.
-                # Text-cap members get the tight 16 MiB limit; binary
-                # members (executables, .node, .wasm, native libs)
-                # get the generous binary cap. We bound BOTH cases.
+                # Sniff first 16 bytes to classify text vs binary;
+                # each gets its own cap (both are bounded).
                 header = src.read(16)
                 is_binary = _looks_binary(name, header)
                 file_cap = HARD_MAX_BINARY_FILE_BYTES if is_binary else HARD_MAX_TEXT_FILE_BYTES
@@ -941,8 +881,7 @@ def safe_extract(
                         f"({'binary' if is_binary else 'text'})"
                     )
                 total += len(data)
-                # Write with restrictive mode (rw-r--r--) so even if
-                # someone runs the extract dir nothing is executable.
+                # Restrictive mode (rw-r--r--): nothing executable.
                 with open(dest, "wb") as out:
                     out.write(data)
                 os.chmod(dest, 0o644)
@@ -1008,10 +947,8 @@ def scan_package_json(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
                     ),
                 )
             )
-        # Credential file paths inside a lifecycle script are
-        # exfiltration prep -- npm runs these scripts automatically
-        # on `npm ci`. Manual `scripts.*` entries (like a `docker`
-        # dev script) are out of scope: npm does not run them.
+        # Cred file paths in a lifecycle script are exfil prep (npm
+        # auto-runs these on `npm ci`); manual scripts are out of scope.
         for path_substr, why in CRED_PATH_SUBSTRINGS:
             if path_substr in body:
                 findings.append(
@@ -1071,20 +1008,12 @@ def scan_package_json(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
 
 
 def _host_in_outbound_context(text: str, host: str) -> bool:
-    """True if `host` appears in a way consistent with an outbound call.
+    """True if `host` appears consistent with an outbound call.
 
-    A bare `"169.254.169.254"` array literal (defensive blocklist) is
-    safe; a `fetch("http://169.254.169.254/...")` is not. The signal
-    is co-occurrence with either an HTTP URL scheme or a fetch verb
-    within a short window.
-
-    A defensive blocklist looks like:
-        const CLOUD_METADATA_IPS = ["169.254.169.254", "169.254.170.2"];
-    An exfil call looks like:
-        fetch("http://169.254.169.254/latest/meta-data/...")
-        http.request({ host: "169.254.169.254", path: "/..." })
+    A bare array literal (defensive blocklist) is safe; co-occurrence
+    with an HTTP URL scheme or a fetch verb in a short window is not.
     """
-    # Esc for use in a regex (IPs contain dots).
+    # Escape for regex (IPs contain dots).
     host_re = re.escape(host)
     # 1. URL form: http://host or https://host or //host/ or //host"
     url_form = re.compile(
@@ -1127,8 +1056,7 @@ def scan_text_blob(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
                 )
             )
 
-    # Credential surfaces. Tier 1: hosts with no legitimate use,
-    # bare substring is enough.
+    # Cred surfaces, tier 1: hosts with no legit use; bare substring.
     for needle, why in CRED_HOST_ALWAYS_BAD:
         if needle in text:
             findings.append(
@@ -1145,8 +1073,8 @@ def scan_text_blob(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
                 )
             )
 
-    # Credential surfaces. Tier 2: hosts that do appear in defensive
-    # code; require co-occurrence with a fetch verb or URL prefix.
+    # Cred surfaces, tier 2: hosts that appear in defensive code too;
+    # require co-occurrence with a fetch verb or URL prefix.
     for needle, why in CRED_HOST_NEEDS_CONTEXT:
         if needle in text and _host_in_outbound_context(text, needle):
             findings.append(
@@ -1164,11 +1092,8 @@ def scan_text_blob(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
                 )
             )
 
-    # Credential PATHS are deliberately not scanned here; they have
-    # too high a false-positive rate at file scope (defensive code,
-    # docker mounts, AWS SDK docs strings). `scan_package_json`
-    # catches the malicious case -- credential paths inside a
-    # lifecycle script run automatically on `npm ci`.
+    # Credential PATHS aren't scanned here (too many FPs at file
+    # scope); scan_package_json catches them inside lifecycle scripts.
 
     # JS-specific regex.
     if _JS_FETCH_EVAL.search(text):
@@ -1211,9 +1136,8 @@ def scan_text_blob(pkg: PackageEntry, rel: str, text: str) -> list[Finding]:
     return findings
 
 
-# Filename suffix decides which scanners run. We deliberately treat
-# *.cjs/*.mjs/*.ts the same as *.js -- attackers use whichever
-# extension the consumer's bundler / loader resolves.
+# Filename suffix decides which scanners run; .cjs/.mjs/.ts are
+# treated like .js (attackers use whichever the loader resolves).
 _TEXT_SUFFIXES = (
     ".js",
     ".mjs",
@@ -1241,12 +1165,9 @@ def scan_extracted_tree(pkg: PackageEntry, root: Path) -> list[Finding]:
         rel = path.relative_to(root).as_posix()
         lower = rel.lower()
         if not lower.endswith(_TEXT_SUFFIXES):
-            # Skip native binaries entirely -- regex over compiled
-            # machine code is just noise (false positives in WASM
-            # opcodes, .node BSS segments, image pixel data). Use
-            # content-magic detection so extensionless executables
-            # (eg `package/biome`) and versioned shared libraries
-            # are also skipped.
+            # Skip native binaries (regex over machine code is noise);
+            # content-magic detection also skips extensionless
+            # executables and versioned shared libraries.
             try:
                 if path.stat().st_size > HARD_MAX_TEXT_FILE_BYTES:
                     continue
@@ -1288,12 +1209,12 @@ def scan_extracted_tree(pkg: PackageEntry, root: Path) -> list[Finding]:
 
 
 def scan_one(pkg: PackageEntry, workspace: Path) -> tuple[list[Finding], str | None]:
-    """Download + extract + scan a single package. Cleans up its dir.
+    """Download + extract + scan a single package; cleans up its dir.
 
     Returns (findings, error). `error` is non-None only on hard
-    failures (download error, integrity mismatch, malformed tarball);
-    on a clean run with findings the error is None and the caller
-    decides exit code based on severity.
+    failures (download, integrity mismatch, malformed tarball); on a
+    clean run with findings, error is None and the caller decides the
+    exit code from severity.
     """
     pkg_dir = workspace / f"{pkg.name.replace('/', '_')}-{pkg.version}"
     pkg_dir.mkdir(parents = True, exist_ok = True)
diff --git a/scripts/scan_packages.py b/scripts/scan_packages.py
index d753a17e49..861b35617b 100644
--- a/scripts/scan_packages.py
+++ b/scripts/scan_packages.py
@@ -56,27 +56,22 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 
-# ---------------------------------------------------------------------------
 # Severity
-# ---------------------------------------------------------------------------
 CRITICAL = "CRITICAL"
 HIGH = "HIGH"
 MEDIUM = "MEDIUM"
 
 SEVERITY_ORDER = {CRITICAL: 0, HIGH: 1, MEDIUM: 2}
 
-# Hard pin-blocks for publicly confirmed malicious PyPI versions.
-# Source: Socket.dev 2026-05-12 disclosure (Mini Shai-Hulud May-12 wave) and
-# earlier Semgrep / Endor reports for the `lightning` entries.
+# Hard pin-blocks for confirmed malicious PyPI versions (Socket.dev 2026-05-12
+# Mini Shai-Hulud wave; earlier Semgrep/Endor reports for `lightning`).
 BLOCKED_PYPI_VERSIONS: dict[str, set[str]] = {
     "guardrails-ai": {"0.10.1"},
     "mistralai": {"2.4.6"},
     "lightning": {"2.6.2", "2.6.3"},
 }
 
-# ---------------------------------------------------------------------------
 # Pattern definitions
-# ---------------------------------------------------------------------------
 
 # Subprocess / OS exec patterns
 RE_SUBPROCESS = re.compile(
@@ -312,10 +307,8 @@ RE_C2_POLLING = re.compile(
     re.DOTALL,
 )
 
-# Developer-tool persistence hooks. The PyTorch Lightning 2.6.x compromise
-# planted SessionStart hooks into Claude Code, VS Code tasks, and Cursor
-# settings so the payload re-attached on every editor open. Catches any
-# package writing into a known dev-tool config that supports auto-run.
+# Developer-tool persistence hooks. Lightning 2.6.x planted SessionStart hooks
+# into Claude Code / VS Code / Cursor so the payload re-attached on editor open.
 RE_DEV_TOOL_HIJACK = re.compile(
     r"\.claude/settings\.json"
     r"|\.cursor/.*hooks"
@@ -326,9 +319,8 @@ RE_DEV_TOOL_HIJACK = re.compile(
     r"|\bautomator\b.*\.workflow\b",
 )
 
-# Hard-coded credential / API-token regexes embedded in source. Packages
-# that ship regexes for OTHER people's secrets are nearly always
-# stealers (litellm 1.82.7, elementary-data 0.23.3, Shai-Hulud).
+# Hard-coded credential / API-token regexes embedded in source. Packages that
+# ship regexes for OTHER people's secrets are nearly always stealers.
 RE_TOKEN_REGEX = re.compile(
     r"\bgh[psoru]_[A-Za-z0-9_]{20,}"  # GitHub PAT/OAuth/etc.
     r"|\bgithub_pat_[A-Za-z0-9_]{20,}"
@@ -342,20 +334,16 @@ RE_TOKEN_REGEX = re.compile(
     r"|\bglpat-[0-9A-Za-z_-]{20,}",  # GitLab PAT
 )
 
-# Mini Shai-Hulud May-12 2026 wave indicators. The dropper artifact name
-# `transformers.pyz` is high-confidence (no legit PyPI package ships a `.pyz`
-# named after `transformers`); the host + slogans are CRITICAL.
+# Mini Shai-Hulud May-12 2026 wave indicators. `transformers.pyz` dropper name
+# is high-confidence; the host + slogans are CRITICAL.
 RE_MAY12_IOC = re.compile(
     r"(git-tanstack\.com|/tmp/transformers\.pyz|transformers\.pyz"
     r"|With Love TeamPCP|We've been online over 2 hours)",
     re.IGNORECASE,
 )
 
-# JavaScript-side obfuscation. The npm chalk/debug compromise and the
-# Lightning router_runtime.js use the same minifier-style hex-var name
-# pattern; a bundle full of `_0x1f2e3d` identifiers is a near-universal
-# tell for a malicious npm payload (and very rare in legit minified code
-# that ships in PyPI wheels).
+# JavaScript-side obfuscation. A bundle full of `_0x1f2e3d` hex-var identifiers
+# is a near-universal tell for a malicious npm payload, rare in legit wheels.
 RE_JS_OBFUSCATION = re.compile(
     r"_0x[a-f0-9]{4,6}\s*=\s*function"
     r"|var\s+_0x[a-f0-9]{4,6}\b"
@@ -363,9 +351,8 @@ RE_JS_OBFUSCATION = re.compile(
     r"|String\.fromCharCode\s*\(\s*\d+\s*(?:,\s*\d+\s*){10,}\)",
 )
 
-# Web3 / wallet-hijack pattern. The Qix npm phish overrode fetch /
-# XMLHttpRequest and attached a `window.ethereum` listener that
-# Levenshtein-swapped recipient addresses on the way to the network.
+# Web3 / wallet-hijack pattern. The Qix npm phish overrode fetch/XMLHttpRequest
+# and swapped recipient addresses via a `window.ethereum` listener.
 RE_WEB3_HIJACK = re.compile(
     r"\bwindow\.ethereum\b"
     r"|\bweb3\.eth\.\w+\s*\("
@@ -374,11 +361,9 @@ RE_WEB3_HIJACK = re.compile(
     r"|TronWeb|solanaWeb3",
 )
 
-# Self-propagating supply-chain worms (Shai-Hulud, ForceMemo) plant
-# their own GitHub workflow in every repo they can reach, and lean on
-# trufflehog/gitleaks for credential discovery. The combo of any of
-# these strings inside a *package payload* is overwhelming evidence of
-# repo-takeover intent.
+# Self-propagating worms (Shai-Hulud, ForceMemo) plant their own GitHub workflow
+# in every repo they reach and use trufflehog/gitleaks for credential discovery.
+# Any of these strings in a package payload is strong repo-takeover evidence.
 RE_WORKFLOW_INJECT = re.compile(
     r"\.github/workflows/[^\"\']*\.ya?ml"
     r"|\btrufflehog\b|\bgitleaks\b"
@@ -388,9 +373,8 @@ RE_WORKFLOW_INJECT = re.compile(
     re.IGNORECASE | re.DOTALL,
 )
 
-# Shell-side patterns specific to install.sh / postinstall scripts that
-# pipe remote code into a shell. `curl ... | sh` and friends are the
-# canonical npm postinstall dropper.
+# install.sh / postinstall scripts piping remote code into a shell.
+# `curl ... | sh` is the canonical npm postinstall dropper.
 RE_SHELL_DROPPER = re.compile(
     r"\bcurl\b[^\n|]*\|\s*(?:sh|bash|zsh)\b"
     r"|\bwget\b[^\n|]*-O-\s*\|\s*(?:sh|bash|zsh)\b"
@@ -400,9 +384,6 @@ RE_SHELL_DROPPER = re.compile(
 )
 
 
-# ---------------------------------------------------------------------------
-# Finding dataclass
-# ---------------------------------------------------------------------------
 @dataclass
 class Finding:
     severity: str
@@ -412,9 +393,7 @@ class Finding:
     evidence: str = ""
 
 
-# ---------------------------------------------------------------------------
 # Checkers
-# ---------------------------------------------------------------------------
 
 
 def check_pth_file(content: str, filename: str, package: str) -> list[Finding]:
@@ -425,7 +404,7 @@ def check_pth_file(content: str, filename: str, package: str) -> list[Finding]:
     """
     findings = []
 
-    # Only care about .pth files that have import lines (executable)
+    # Only .pth files with import lines are executable
     import_lines = [line for line in content.splitlines() if RE_PTH_IMPORT.match(line)]
     if not import_lines:
         return findings  # Pure path entries, inert
@@ -470,7 +449,7 @@ def check_pth_file(content: str, filename: str, package: str) -> list[Finding]:
                 )
             )
 
-    # Large base64 blob (special handling for blob size)
+    # Large base64 blob
     if RE_LARGE_BLOB.search(content):
         blob = RE_LARGE_BLOB.search(content).group()
         findings.append(
@@ -483,7 +462,7 @@ def check_pth_file(content: str, filename: str, package: str) -> list[Finding]:
             )
         )
 
-    # Catch-all: any import line at all in .pth (if nothing else triggered)
+    # Catch-all: any import line in .pth if nothing else triggered
     if not findings and import_lines:
         evidence = "\n".join(import_lines[:5])
         if len(import_lines) > 5:
@@ -521,7 +500,7 @@ def check_py_file(content: str, filename: str, package: str) -> list[Finding]:
     is_setup = basename in ("setup.py", "setup.cfg")
     is_init = basename == "__init__.py"
 
-    # Pre-compute all pattern matches
+    # Pre-compute pattern matches
     has_network = bool(RE_NETWORK.search(content))
     has_subprocess = bool(RE_SUBPROCESS.search(content))
     has_base64 = bool(RE_BASE64.search(content))
@@ -546,9 +525,7 @@ def check_py_file(content: str, filename: str, package: str) -> list[Finding]:
     has_c2_polling = bool(RE_C2_POLLING.search(content))
     has_may12_ioc = bool(RE_MAY12_IOC.search(content))
 
-    # ---------------------------------------------------------------
     # CRITICAL: combination patterns that strongly indicate malice
-    # ---------------------------------------------------------------
 
     # base64 decode + subprocess execution (staged payload)
     if has_base64 and has_subprocess:
@@ -740,9 +717,7 @@ def check_py_file(content: str, filename: str, package: str) -> list[Finding]:
             )
         )
 
-    # ---------------------------------------------------------------
     # HIGH: single strong signals or weaker combinations
-    # ---------------------------------------------------------------
 
     # Obfuscated payload: base64 + exec/eval + large blob
     if has_base64 and has_exec_eval and has_blob:
@@ -879,9 +854,7 @@ def check_py_file(content: str, filename: str, package: str) -> list[Finding]:
                 )
             )
 
-    # ---------------------------------------------------------------
     # MEDIUM: standalone signals (informational, may be legitimate)
-    # ---------------------------------------------------------------
 
     # base64 + exec/eval without blob
     if has_base64 and has_exec_eval and not has_blob:
@@ -978,23 +951,18 @@ def _extract_evidence(
     return " | ".join(matches) if matches else ""
 
 
-# ---------------------------------------------------------------------------
 # Non-Python checkers
-# ---------------------------------------------------------------------------
-# Several recent PyPI compromises (PyTorch Lightning 2.6.x, ForceMemo)
-# carried the active payload in a bundled .js / .sh / workflow yaml so
-# the Python imports looked clean on first glance. These checkers scan
-# those file types when they appear inside a Python wheel/sdist.
+# Recent PyPI compromises (Lightning 2.6.x, ForceMemo) carried the payload in a
+# bundled .js / .sh / workflow yaml so the Python imports looked clean. These
+# checkers scan those file types when they appear inside a wheel/sdist.
 
 
 def check_js_file(content: str, filename: str, package: str) -> list[Finding]:
     """Run JS-side checks. Triggered by .js / .mjs / .cjs / .ts."""
     findings = []
 
-    # A JS file *inside a Python wheel* that's larger than 100 KB is
-    # itself anomalous (legit Python packages don't ship hand-written
-    # JS bundles). Combined with ANY of the other JS heuristics it is
-    # CRITICAL; standalone it is HIGH.
+    # A >100 KB JS file inside a Python wheel is anomalous: CRITICAL combined
+    # with any other JS heuristic, HIGH standalone.
     is_large = len(content) > 100 * 1024
     has_obf = bool(RE_JS_OBFUSCATION.search(content))
     has_web3 = bool(RE_WEB3_HIJACK.search(content))
@@ -1119,10 +1087,8 @@ def check_shell_file(content: str, filename: str, package: str) -> list[Finding]
 def check_workflow_file(content: str, filename: str, package: str) -> list[Finding]:
     """Run GitHub-Actions workflow checks. Triggered by .github/workflows/*.yml."""
     findings = []
-    # A GitHub workflow file inside a *PyPI package* is itself
-    # suspicious (Shai-Hulud's whole MO is to plant `shai-hulud.yml`
-    # in every repo it can write to). Anything matching the workflow
-    # injection signature gets flagged CRITICAL.
+    # A workflow file inside a PyPI package is suspicious (Shai-Hulud plants
+    # `shai-hulud.yml` everywhere); injection-signature matches are CRITICAL.
     if RE_WORKFLOW_INJECT.search(content):
         findings.append(
             Finding(
@@ -1166,15 +1132,11 @@ def check_workflow_file(content: str, filename: str, package: str) -> list[Findi
     return findings
 
 
-# ---------------------------------------------------------------------------
 # Archive handling
-# ---------------------------------------------------------------------------
 
 # Tarbomb caps, mirrored from scripts/scan_npm_packages.py::safe_extract.
-# Refuses zip-of-death / tar-of-death archives so a hostile sdist or
-# wheel cannot exhaust memory or fill the temp dir before content
-# scanning even starts. Keep these constants in sync with the npm side;
-# we duplicate rather than import to keep `scan_packages.py` standalone.
+# Refuses zip/tar-of-death so a hostile archive cannot exhaust memory before
+# scanning. Keep in sync with the npm side; duplicated to stay standalone.
 HARD_MAX_FILE_BYTES = 64 * 1024 * 1024  # 64 MiB per member
 HARD_MAX_TOTAL_BYTES = 512 * 1024 * 1024  # 512 MiB cumulative
 HARD_MAX_MEMBERS = 50_000  # entries per archive
@@ -1183,11 +1145,8 @@ HARD_MAX_MEMBERS = 50_000  # entries per archive
 def _refuse_unsafe_member_name(name: str) -> str | None:
     """Return a refusal reason for a member name, or None if safe.
 
-    Mirrors `scan_npm_packages.py::safe_extract` semantics: no absolute
-    paths, no `..` traversal segments. The caller is responsible for
-    checking the resolved path lands inside the extract root, but for
-    iter_archive_files we never write to disk so the name-shape check
-    plus the in-memory size cap is sufficient.
+    Mirrors `safe_extract`: no absolute paths, no `..` traversal. We never write
+    to disk, so the name-shape check plus the in-memory size cap is sufficient.
     """
     if name.startswith("/") or ".." in Path(name).parts:
         return f"unsafe member name {name!r}"
@@ -1197,9 +1156,8 @@ def _refuse_unsafe_member_name(name: str) -> str | None:
 def iter_archive_files(archive_path: str):
     """Yield (filename, text_content) for every file in a wheel/sdist.
 
-    Streams members with size + count caps applied at the member level
-    so a tarbomb / zipbomb cannot blow up the scanner's memory budget.
-    On cap breach we emit a `[WARN]` log and short-circuit the archive.
+    Streams members with per-member size + count caps so a tarbomb/zipbomb can't
+    blow the memory budget. On cap breach, emits a `[WARN]` and short-circuits.
     """
     path = Path(archive_path)
 
@@ -1225,7 +1183,7 @@ def iter_archive_files(archive_path: str):
                         file = sys.stderr,
                     )
                     continue
-                # Declared (uncompressed) size cap.
+                # Declared (uncompressed) size cap
                 if info.file_size > HARD_MAX_FILE_BYTES:
                     print(
                         f"  [WARN] {path.name}: skipped {info.filename!r} "
@@ -1262,9 +1220,8 @@ def iter_archive_files(archive_path: str):
                         file = sys.stderr,
                     )
                     return
-                # Refuse symlinks / hardlinks / devices outright -- the
-                # scanner never writes them anyway, but tar parsers
-                # have historically dereferenced them on extract.
+                # Refuse symlinks/hardlinks/devices: tar parsers have
+                # historically dereferenced them on extract.
                 if member.issym() or member.islnk():
                     print(
                         f"  [WARN] {path.name}: refused link member " f"{member.name!r}",
@@ -1305,8 +1262,7 @@ def iter_archive_files(archive_path: str):
                     f = tf.extractfile(member)
                     if f is None:
                         continue
-                    # Bound the read so a tar header that lies about
-                    # size cannot OOM us.
+                    # Bound the read: a tar header may lie about size
                     data = f.read(HARD_MAX_FILE_BYTES + 1)
                     if len(data) > HARD_MAX_FILE_BYTES:
                         print(
@@ -1327,11 +1283,9 @@ def iter_archive_files(archive_path: str):
 def scan_archive(archive_path: str, package: str) -> list[Finding]:
     """Scan all files in an archive for malicious patterns.
 
-    A corrupted archive container (truncated wheel, bad gzip header,
-    etc.) used to be silently skipped by an ``except Exception: continue``
-    inside ``iter_archive_files``. Per the silent-failure hardening
-    (SF1) it now emits a CRITICAL ``archive_corrupted`` finding so the
-    main loop counts and surfaces it rather than reporting "0 findings".
+    A corrupted archive container (truncated wheel, bad gzip header, etc.) emits
+    a CRITICAL ``archive_corrupted`` finding rather than being silently skipped
+    and reported as "0 findings" (silent-failure hardening SF1).
     """
     findings: list[Finding] = []
     try:
@@ -1342,22 +1296,17 @@ def scan_archive(archive_path: str, package: str) -> list[Finding]:
             elif lower.endswith(".py"):
                 findings.extend(check_py_file(content, filename, package))
             elif lower.endswith((".js", ".mjs", ".cjs", ".ts")):
-                # Lightning 2.6.x hid its real payload in a 14.8 MB
-                # router_runtime.js inside a Python wheel. Without this
-                # branch we'd have only seen the small Python loader.
+                # Lightning 2.6.x hid its payload in a 14.8 MB router_runtime.js;
+                # without this branch we'd only see the small Python loader.
                 findings.extend(check_js_file(content, filename, package))
             elif lower.endswith((".sh", ".bash")):
                 findings.extend(check_shell_file(content, filename, package))
             elif "/.github/workflows/" in lower and lower.endswith((".yml", ".yaml")):
-                # Shai-Hulud / ForceMemo plant their own GHA workflow.
-                # A workflow file inside a *PyPI package* is on its own
-                # already a yellow flag; pattern-match the worm signatures.
+                # Shai-Hulud/ForceMemo plant their own GHA workflow
                 findings.extend(check_workflow_file(content, filename, package))
     except (zipfile.BadZipFile, tarfile.TarError, EOFError, OSError) as exc:
-        # The archive cannot be opened or is structurally broken. A
-        # benign wheel/sdist always opens; a malformed one is either a
-        # transport corruption (treat as scan failure) or a deliberate
-        # attempt to bypass scanners that swallow archive errors.
+        # Archive cannot be opened / is structurally broken: either transport
+        # corruption or a deliberate attempt to bypass error-swallowing scanners.
         findings.append(
             Finding(
                 CRITICAL,
@@ -1370,9 +1319,7 @@ def scan_archive(archive_path: str, package: str) -> list[Finding]:
     return findings
 
 
-# ---------------------------------------------------------------------------
 # Download packages
-# ---------------------------------------------------------------------------
 
 
 _RE_PYPI_SPEC_VERSION = re.compile(r"==\s*([A-Za-z0-9_.\-+!]+)")
@@ -1382,10 +1329,8 @@ def _check_blocked_pypi_versions(specs: list[str]) -> tuple[list[str], list[Find
     """Filter ``specs`` against ``BLOCKED_PYPI_VERSIONS``.
 
     Returns ``(safe_specs, findings)``. Each blocked spec emits a CRITICAL
-    ``Finding`` and is removed from the returned spec list so the caller
-    never fetches the malicious tarball. Specs without an ``==X.Y.Z`` pin
-    pass through unchanged -- pip will resolve them at download time and
-    the existing scanners will catch the payload via the IOC regexes.
+    ``Finding`` and is dropped so the malicious tarball is never fetched. Specs
+    without an ``==X.Y.Z`` pin pass through; the IOC regexes catch them later.
     """
     safe: list[str] = []
     findings: list[Finding] = []
@@ -1407,7 +1352,7 @@ def _check_blocked_pypi_versions(specs: list[str]) -> tuple[list[str], list[Find
                     f"{name}=={version} is on the BLOCKED_PYPI_VERSIONS list",
                 )
             )
-            # Drop the spec; do not download.
+            # Drop the spec; do not download
             continue
         safe.append(spec)
     return safe, findings
@@ -1416,14 +1361,11 @@ def _check_blocked_pypi_versions(specs: list[str]) -> tuple[list[str], list[Find
 def _pip_download_env() -> dict[str, str]:
     """Return a scrubbed environment for invoking `pip download`.
 
-    Hostile shells / CI configs can override the index with PIP_INDEX_URL,
-    PIP_EXTRA_INDEX_URL, or a user `pip.conf`. We strip every PIP_*
-    override and route the resolver explicitly at PyPI. PIP_CONFIG_FILE
-    is forced to /dev/null so a stray ~/.pip/pip.conf with an
-    extra-index-url cannot bypass the pin.
+    Strips every PIP_* override and forces the resolver at PyPI; PIP_CONFIG_FILE
+    is /dev/null so a stray pip.conf extra-index-url cannot bypass the pin.
     """
     env = {**os.environ}
-    # Drop any user override.
+    # Drop any user override
     for key in [k for k in env if k.startswith("PIP_")]:
         env.pop(key, None)
     env["PIP_INDEX_URL"] = "https://pypi.org/simple"
@@ -1433,10 +1375,8 @@ def _pip_download_env() -> dict[str, str]:
     return env
 
 
-# Pip resolver flags shared by both download branches. Pinning the
-# index URL on the CLI is belt + braces with the env scrub above.
-# `--no-build-isolation` is deliberately NOT set; we never invoke
-# setup.py at all because of `--only-binary :all:`.
+# Pip resolver flags shared by both download branches. CLI index-URL pin is
+# belt + braces with the env scrub; `--only-binary :all:` avoids running setup.py.
 _PIP_DOWNLOAD_PIN_FLAGS = [
     "--index-url",
     "https://pypi.org/simple",
@@ -1445,9 +1385,8 @@ _PIP_DOWNLOAD_PIN_FLAGS = [
 ]
 
 
-# Strip any character that could escape `dest` via `os.path.join`. This
-# is the last line of defence before `pkg_dir = os.path.join(dest, ...)`
-# so a spec like `../../etc/foo==1.0` cannot land outside the temp tree.
+# Strip characters that could escape `dest` via `os.path.join`, so a spec like
+# `../../etc/foo==1.0` cannot land outside the temp tree.
 _RE_PKG_NAME_SANITIZE = re.compile(r"[^A-Za-z0-9._-]")
 
 
@@ -1459,27 +1398,21 @@ def download_packages(
 ) -> tuple[list[tuple[str, str]], list[str]]:
     """Download packages to dest using pip download. NEVER installs.
 
-    Returns ``(results, download_errors)`` where ``results`` is a list of
-    ``(spec_or_name, filepath)`` for every downloaded archive and
-    ``download_errors`` is a list of one-line transport-failure summaries.
-    A non-empty ``download_errors`` MUST cause the caller to exit non-zero
-    even if no findings were produced; a silent ``0 findings, scan
-    incomplete`` is the bug class this return-shape was widened to fix.
+    Returns ``(results, download_errors)``: ``results`` is ``(spec_or_name,
+    filepath)`` per archive; ``download_errors`` is one-line transport-failure
+    summaries. A non-empty ``download_errors`` MUST make the caller exit
+    non-zero so a partial scan can't masquerade as "0 findings, all clean".
 
-    When with_deps=True, downloads the full transitive dependency tree
-    in a single pip invocation (all archives land in one flat dir).
-    When with_deps=False (default), downloads each spec individually
-    with --no-deps.
+    with_deps=True downloads the full transitive tree in one pip call (flat dir);
+    with_deps=False (default) downloads each spec individually with --no-deps.
     """
     results: list[tuple[str, str]] = []
     download_errors: list[str] = []
     env = _pip_download_env()
 
     if with_deps:
-        # Single pip download call for all specs + their transitive deps.
-        # `--only-binary :all:` refuses sdists so we never execute a
-        # setup.py just to learn dependency metadata; combined with the
-        # scrubbed env, pip is wired hard at pypi.org.
+        # Single pip download for all specs + transitive deps. `--only-binary
+        # :all:` refuses sdists so we never execute setup.py for metadata.
         os.makedirs(dest, exist_ok = True)
         cmd = [
             sys.executable,
@@ -1495,7 +1428,7 @@ def download_packages(
                 cmd,
                 capture_output = True,
                 text = True,
-                timeout = 600,  # transitive resolution can be slow
+                timeout = 600,  # transitive resolution is slow
                 env = env,
             )
             if proc.returncode != 0:
@@ -1511,14 +1444,12 @@ def download_packages(
         for fname in sorted(os.listdir(dest)):
             fpath = os.path.join(dest, fname)
             if os.path.isfile(fpath):
-                # Derive package name from filename
                 pkg_name = fname.split("-")[0].replace("_", "-").lower()
                 results.append((pkg_name, fpath))
     else:
         for spec in specs:
             raw_name = _extract_pkg_name(spec)
-            # Sanitize before joining into `dest` so a hostile spec
-            # cannot path-traverse out of the destination directory.
+            # Sanitize before joining into `dest` to prevent path traversal
             safe_name = _RE_PKG_NAME_SANITIZE.sub("_", raw_name) or "_pkg"
             pkg_dir = os.path.join(dest, safe_name)
             os.makedirs(pkg_dir, exist_ok = True)
@@ -1552,7 +1483,6 @@ def download_packages(
                 download_errors.append(msg)
                 continue
 
-            # Find downloaded file(s)
             for fname in os.listdir(pkg_dir):
                 fpath = os.path.join(pkg_dir, fname)
                 if os.path.isfile(fpath):
@@ -1560,9 +1490,7 @@ def download_packages(
     return results, download_errors
 
 
-# ---------------------------------------------------------------------------
 # Parse requirements files
-# ---------------------------------------------------------------------------
 
 _RE_NAME = re.compile(r"^([A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)")
 
@@ -1591,7 +1519,7 @@ def parse_requirements(req_files: list[str]) -> list[dict]:
                     if not line or line.startswith("#") or line.startswith("-"):
                         continue
                     is_git = line.startswith("git+") or "git+" in line.split("#")[0]
-                    # Strip inline comments and environment markers for spec
+                    # Strip inline comments and env markers
                     spec = line.split("#")[0].strip()
                     spec = spec.split(";")[0].strip()
                     if not spec:
@@ -1624,7 +1552,7 @@ def get_downloaded_version(archive_path: str) -> str | None:
         parts = basename[:-4].split("-")
         if len(parts) >= 2:
             return parts[1]
-    # Sdist: name-version.tar.gz / .tar.bz2 / .zip
+    # Sdist: name-version.<ext>
     for ext in (".tar.gz", ".tar.bz2", ".tar.xz", ".tar", ".zip"):
         if basename.endswith(ext):
             stem = basename[: -len(ext)]
@@ -1634,9 +1562,7 @@ def get_downloaded_version(archive_path: str) -> str | None:
     return None
 
 
-# ---------------------------------------------------------------------------
 # Display
-# ---------------------------------------------------------------------------
 
 
 def severity_color(sev: str) -> str:
@@ -1652,7 +1578,6 @@ def print_findings(findings: list[Finding]) -> None:
         print("\n  All clean. No suspicious patterns found.")
         return
 
-    # Sort by severity
     findings.sort(key = lambda f: SEVERITY_ORDER.get(f.severity, 99))
 
     print(f"\n  {'=' * 72}")
@@ -1682,9 +1607,7 @@ def print_findings(findings: list[Finding]) -> None:
     print(f"  Summary: {', '.join(parts)}")
 
 
-# ---------------------------------------------------------------------------
 # PyPI version queries and --fix logic
-# ---------------------------------------------------------------------------
 
 
 def version_sort_key(v: str) -> tuple:
@@ -1708,15 +1631,13 @@ def version_sort_key(v: str) -> tuple:
     base = v_clean[0]
     suffix = v[len(base) :]
 
-    # Parse numeric parts
     parts = []
     for seg in base.split("."):
         try:
             parts.append(int(seg))
         except ValueError:
             parts.append(0)
-    # Pad to at least 3 parts
-    while len(parts) < 3:
+    while len(parts) < 3:  # pad to at least 3 parts
         parts.append(0)
 
     # Suffix ordering: dev < alpha < beta < rc < (none) < post
@@ -1732,7 +1653,7 @@ def version_sort_key(v: str) -> tuple:
     elif suffix_lower.startswith("post"):
         suffix_rank = 1
     else:
-        suffix_rank = 0  # stable release
+        suffix_rank = 0  # stable
 
     return (epoch, tuple(parts), suffix_rank, suffix)
 
@@ -1772,11 +1693,10 @@ def find_safe_version(
         print(f"  [WARN] No versions found on PyPI for {name}", file = sys.stderr)
         return None
 
-    # Find index of bad version
     try:
         bad_idx = versions.index(bad_ver)
     except ValueError:
-        # bad_ver might have been resolved to a different string; search by sort key
+        # bad_ver may resolve to a different string; search by sort key
         bad_key = version_sort_key(bad_ver)
         bad_idx = None
         for i, v in enumerate(versions):
@@ -1820,7 +1740,6 @@ def find_safe_version(
                 print(f"    {ver} -- CRITICAL finding(s), skipping")
                 break
 
-        # Clean up scan dir for this version
         shutil.rmtree(scan_dir, ignore_errors = True)
 
         if clean:
@@ -1850,8 +1769,7 @@ def update_req_line(raw_line: str, safe_ver: str, old_ver: str | None) -> str:
         code_part, marker = code_part.split(";", 1)
         marker = ";" + marker
 
-    # Replace version specifier
-    # Match patterns like ==1.2.3, >=1.2, ~=1.0, <=2.0, !=1.1, or bare name
+    # Replace version specifier (==1.2.3, >=1.2, ~=1.0, !=1.1, or bare name)
     rewritten = re.sub(
         r"([A-Za-z0-9._-]+)\s*(?:[><=!~]=?[^;#,\s]*(?:\s*,\s*[><=!~]=?[^;#,\s]*)*)?",
         lambda m: f"{m.group(1)}=={safe_ver}",
@@ -1870,12 +1788,8 @@ def update_req_file(filepath: str, updates: dict[int, str]) -> None:
 
     updates: {line_num (1-indexed): new_line_text}
 
-    Writes atomically: stage in a sibling tmp file on the same
-    filesystem, fsync, then `os.replace` over the original. A SIGKILL
-    or power loss mid-write therefore either leaves the original
-    intact or leaves the fully new file -- never a half-written
-    requirements file (which would silently re-introduce a malicious
-    pin).
+    Writes atomically (sibling tmp file, fsync, os.replace) so a crash mid-write
+    never leaves a half-written file that re-introduces a malicious pin.
     """
     with open(filepath) as f:
         lines = f.readlines()
@@ -1883,8 +1797,7 @@ def update_req_file(filepath: str, updates: dict[int, str]) -> None:
     for line_num, new_text in updates.items():
         idx = line_num - 1
         if 0 <= idx < len(lines):
-            # Preserve original line ending
-            ending = "\n" if lines[idx].endswith("\n") else ""
+            ending = "\n" if lines[idx].endswith("\n") else ""  # preserve line ending
             lines[idx] = new_text + ending
 
     dirpath = os.path.dirname(os.path.abspath(filepath)) or "."
@@ -1909,7 +1822,7 @@ def update_req_file(filepath: str, updates: dict[int, str]) -> None:
 
 def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> None:
     """Run the --fix flow: find safe versions, update requirements files."""
-    # Map package names to their entries for source tracking
+    # Map package names to entries for source tracking
     pkg_entries: dict[str, list[dict]] = {}
     for e in entries:
         norm = e["name"].lower().replace("-", "_").replace(".", "_")
@@ -1931,8 +1844,7 @@ def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> N
                     changes_summary.append(f"  SKIP  {pkg_name} (git URL)")
                 continue
 
-            # Get the currently resolved version
-            # Try to extract from the spec (e.g. name==1.2.3)
+            # Resolved version: try to extract from the spec (name==1.2.3)
             current_ver = None
             for e in related:
                 spec = e["spec"]
@@ -1947,7 +1859,6 @@ def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> N
                 downloaded = download_packages([pkg_name], dl_dir)
                 if downloaded:
                     current_ver = get_downloaded_version(downloaded[0][1])
-                # Delete resolution download immediately
                 shutil.rmtree(dl_dir, ignore_errors = True)
 
             if not current_ver:
@@ -1986,7 +1897,6 @@ def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> N
             for filepath, updates in file_updates.items():
                 update_req_file(filepath, updates)
 
-    # Print summary
     print(f"\n  {'=' * 72}")
     print(f"  FIX SUMMARY")
     print(f"  {'=' * 72}")
@@ -1995,9 +1905,7 @@ def _run_fix(critical_pkgs: set[str], entries: list[dict], max_search: int) -> N
     print(f"\n  Re-run without --fix to verify the scan is clean.")
 
 
-# ---------------------------------------------------------------------------
 # Directory scanning
-# ---------------------------------------------------------------------------
 
 
 def _find_requirements_files(root: str) -> list[str]:
@@ -2014,7 +1922,7 @@ def _find_requirements_files(root: str) -> list[str]:
     skip_dirs = {"__pycache__", "node_modules", "venv", ".venv", "site-packages"}
     results = []
     for dirpath, dirnames, filenames in os.walk(root):
-        # Skip hidden dirs and known non-requirement dirs
+        # Skip hidden and known non-requirement dirs
         dirnames[:] = [
             d
             for d in dirnames
@@ -2024,18 +1932,15 @@ def _find_requirements_files(root: str) -> list[str]:
         for fname in sorted(filenames):
             if not fname.endswith(".txt"):
                 continue
-            # Match requirements*.txt anywhere
             if fnmatch.fnmatch(fname.lower(), "requirements*.txt"):
                 results.append(os.path.join(dirpath, fname))
-            # Match *.txt inside a directory named "requirements"
+            # *.txt inside a directory named "requirements"
             elif dirname == "requirements":
                 results.append(os.path.join(dirpath, fname))
     return sorted(results)
 
 
-# ---------------------------------------------------------------------------
 # Main
-# ---------------------------------------------------------------------------
 
 
 def main() -> int:
@@ -2134,7 +2039,7 @@ def main() -> int:
 
     all_findings: list[Finding] = []
 
-    # Hard pin-block: refuse to download known-malicious PyPI versions.
+    # Hard pin-block: refuse to download known-malicious PyPI versions
     specs, blocked_findings = _check_blocked_pypi_versions(specs)
     all_findings.extend(blocked_findings)
 
@@ -2172,10 +2077,8 @@ def main() -> int:
             )
             _run_fix(critical_pkgs, entries, args.max_search)
 
-    # Surface any pip-download failures BEFORE the scan-result exit code so
-    # an empty / partial download cannot mask itself as "0 findings, all
-    # clean". This is item (4) of the silent-failure hardening: an
-    # unresolvable spec or PyPI timeout used to print to stderr and exit 0.
+    # Surface pip-download failures BEFORE the exit code so a partial download
+    # can't masquerade as "0 findings, all clean" (silent-failure hardening 4).
     if download_errors:
         print(
             f"\n  {'=' * 72}\n"
diff --git a/scripts/stamp_studio_release.py b/scripts/stamp_studio_release.py
index a3c8712a6e..7dab35ea8a 100644
--- a/scripts/stamp_studio_release.py
+++ b/scripts/stamp_studio_release.py
@@ -22,11 +22,8 @@ def _atomic_write_text(
     data: str,
     encoding: str = "utf-8",
 ) -> None:
-    """Atomic version of ``Path.write_text``.
-
-    A crash or signal mid-write leaves the prior file intact; the
-    Studio build never reads a partial ``_studio_release_build.py``.
-    """
+    """Atomic ``Path.write_text``: a crash mid-write leaves the prior file
+    intact, so the build never reads a partial ``_studio_release_build.py``."""
     dirpath = str(path.parent) or "."
     path.parent.mkdir(parents = True, exist_ok = True)
     fd, tmp_path = tempfile.mkstemp(prefix = ".stamp_studio.", dir = dirpath)
diff --git a/scripts/verify_comment_only_diff.py b/scripts/verify_comment_only_diff.py
index b661f76859..23d06b85df 100644
--- a/scripts/verify_comment_only_diff.py
+++ b/scripts/verify_comment_only_diff.py
@@ -57,9 +57,7 @@ def _git_show(rev: str, path: str) -> str:
 
 
 def _strip_docstrings(tree: ast.AST) -> ast.AST:
-    """Remove every string-literal docstring (Module / FunctionDef /
-    AsyncFunctionDef / ClassDef). Empty body becomes ``pass`` so
-    ast.unparse stays valid."""
+    """Remove docstrings; empty bodies become ``pass`` so unparse stays valid."""
     for node in ast.walk(tree):
         if isinstance(
             node,
@@ -87,9 +85,8 @@ def _normalize_py(src: str) -> str:
 
 
 def _strip_shell_comments(s: str) -> str:
-    """Strip pure-comment lines and inline trailing comments from a shell
-    snippet, then collapse runs of blank lines. Heuristic only: leaves a
-    line untouched if it has an odd quote count (open string)."""
+    """Strip shell comments and collapse blank lines. Heuristic: skips lines
+    with an odd quote count (open string)."""
     out = []
     for line in s.splitlines():
         stripped = line.lstrip()
@@ -116,9 +113,7 @@ def _strip_shell_comments(s: str) -> str:
 
 
 def _normalize_yaml_run_strings(obj: Any) -> Any:
-    """Walk the parsed YAML object; for any multi-line string (i.e. a
-    ``run: |`` script body), strip shell comments. Returns a normalised
-    copy."""
+    """Strip shell comments from any multi-line string (``run: |`` body)."""
     if isinstance(obj, dict):
         return {k: _normalize_yaml_run_strings(v) for k, v in obj.items()}
     if isinstance(obj, list):
diff --git a/scripts/verify_import_hoist.py b/scripts/verify_import_hoist.py
index 6f5b452f3c..b8cb0573fe 100644
--- a/scripts/verify_import_hoist.py
+++ b/scripts/verify_import_hoist.py
@@ -122,16 +122,13 @@ class _Builder(ast.NodeVisitor):
 
     def __init__(self):
         self.module = Scope("module", "<module>", None)
-        self.uses: list[tuple[Scope, str, int]] = []  # (scope, name, lineno) hard loads
-        self.soft_uses: list[tuple[Scope, str, int]] = []  # annotations: count as "used"
-        #                                                     but never as "unresolved"
-        #                                                     (forward refs / string annos)
+        self.uses: list[tuple[Scope, str, int]] = []  # hard loads
+        # annotations: count as "used" but never as "unresolved" (forward refs)
+        self.soft_uses: list[tuple[Scope, str, int]] = []
 
     def _visit_annotation(self, node, scope: Scope) -> None:
-        """Annotation context: with `from __future__ import annotations` these are
-        never evaluated (strings), and even otherwise they routinely contain forward
-        references. Record contained names as SOFT uses so an import used only in an
-        annotation still counts as used, but a forward-ref name is never 'unresolved'."""
+        """Record annotation names as SOFT uses: an import used only in an annotation
+        counts as used, but a forward-ref name is never 'unresolved'."""
         if node is None:
             return
         for n in ast.walk(node):
@@ -189,7 +186,7 @@ class _Builder(ast.NodeVisitor):
             child = Scope("function", f"{scope.qualname}.{node.name}", scope)
             self._bind_type_params(node, child)
             self._bind_args(node.args, child)
-            # arg + return annotations: soft uses (may be strings / forward refs)
+            # arg + return annotations: soft uses
             for a in self._all_args(node.args):
                 self._visit_annotation(a.annotation, child)
             self._visit_annotation(getattr(node, "returns", None), child)
@@ -355,7 +352,7 @@ class _Builder(ast.NodeVisitor):
         if isinstance(node, (ast.ListComp, ast.SetComp, ast.GeneratorExp, ast.DictComp)):
             child = Scope("comp", f"{scope.qualname}.<comp>", scope)
             for i, gen in enumerate(node.generators):
-                # first iterable is evaluated in the enclosing scope
+                # first iterable evaluates in the enclosing scope
                 self._visit_expr(gen.iter, scope if i == 0 else child)
                 self._bind_targets(child, gen.target)
                 for cond in gen.ifs:
@@ -394,9 +391,8 @@ def _any_star(scope: Scope) -> bool:
 
 
 def _resolve(scope: Scope, name: str):
-    """LEGB resolution. Returns (status, bindings) where status in
+    """LEGB resolution. Returns (status, bindings); status in
     {'local','import','other','builtin','star','unresolved'}."""
-    # global / nonlocal redirection
     start = scope
     if name in scope.globals:
         chain = [_module_of(scope)]
@@ -441,7 +437,7 @@ def _legb_chain(scope: Scope) -> list[Scope]:
     chain = [scope]
     p = scope.parent
     while p is not None:
-        if p.kind != "class" or p.parent is None:  # module-level class never happens; keep module
+        if p.kind != "class" or p.parent is None:  # skip class scopes, keep module
             if p.kind != "class":
                 chain.append(p)
         p = p.parent
@@ -455,7 +451,7 @@ def _analyze(src: str):
     tree = ast.parse(src)
     b = _Builder()
     b.run(tree)
-    # Per-scope: unresolved load names, and import targets it resolves to.
+    # Per-scope: unresolved load names + import targets it resolves to.
     unresolved: dict[str, set[str]] = {}
     targets_by_scope: dict[str, set[str]] = {}
     target_by_use: dict[tuple[str, str], set[str]] = {}
@@ -467,7 +463,7 @@ def _analyze(src: str):
             tids = {bd.target for bd in binds if bd.target}
             targets_by_scope.setdefault(scope.qualname, set()).update(tids)
             target_by_use.setdefault((scope.qualname, name), set()).update(tids)
-    # soft uses (annotations): only contribute to "used", never to "unresolved"
+    # soft uses (annotations): contribute to "used" only, never "unresolved"
     for scope, name, _ln in b.soft_uses:
         status, binds = _resolve(scope, name)
         if status == "import":
@@ -495,7 +491,7 @@ def _analyze(src: str):
                 x.kind not in ("import", "importfrom") for x in bs
             ):
                 ambiguous.setdefault(scope.qualname, set()).add(n)
-        # scope tree isn't stored; rebuild via uses is hard. We approximate with module only.
+        # scope tree isn't stored; approximate with module only.
 
     walk_scopes(module)
     return {
@@ -524,14 +520,9 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
 
     Blocker signals (precise, no relocation false-positives):
       UNRESOLVED-NEW    - a load became undefined (dangling alias / removed import).
-      NEW-UNUSED-HOIST  - a module-level import added by THIS change is resolved by
-                          NO load. A correct hoist always wires its new import to a
-                          reference; if the alias was left un-normalized OR renamed
-                          to the wrong name, the hoisted import ends up unused. This
-                          single signal catches BOTH user-described failure modes and
-                          does NOT fire for code merely relocated to another file
-                          (that removes the import, it doesn't add an unused one).
-      TARGET-CHANGED    - the same (scope, name) load resolves to a different import
+      NEW-UNUSED-HOIST  - a module-level import added by this change is resolved by
+                          NO load (un-normalized alias or wrong rename target).
+      TARGET-CHANGED    - same (scope, name) load resolves to a different import
                           target before vs after (a same-name re-point).
     """
     a = _analyze(before_src)
@@ -566,14 +557,13 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
                 )
             )
 
-    # 2. HOISTED-IMPORT-UNUSED  (the core botched-hoist / wrong-rename signal)
-    #    A module-level import in AFTER that NO load resolves to, and which was
-    #    either newly added by this change OR was actually used before. Excludes:
-    #      - relocation (the import is REMOVED, so it's not in after at all)
-    #      - stable pre-existing re-exports (unused before AND after, not newly added)
+    # 2. HOISTED-IMPORT-UNUSED  (core botched-hoist / wrong-rename signal)
+    #    A module-level import in AFTER that NO load resolves to, that was either
+    #    newly added by this change OR actually used before. Excludes relocation
+    #    (import removed) and stable pre-existing re-exports.
     for n, tids in b["module_import_targets"].items():
         if tids & after_used:
-            continue  # resolved by something -> fine
+            continue  # resolved -> fine
         newly_added = bool(tids - before_module_targets)
         was_used_before = bool(tids & before_used)
         if newly_added or was_used_before:
@@ -619,8 +609,7 @@ def compare(before_src: str, after_src: str, path: str) -> list[tuple[str, str]]
             findings.append(("WARN", f"{path}: AMBIGUOUS-BIND '{n}' import+non-import in {scope}"))
 
     # 6. TARGET-MISSING (informational): a scope stopped resolving to an import
-    #    target. Real bugs are already covered above; remaining cases are code
-    #    relocated to another file (e.g. a moved helper). Shown for transparency.
+    #    target. Real bugs are covered above; remaining cases are relocated code.
     for scope, tbefore in a["targets_by_scope"].items():
         tafter = b["targets_by_scope"].get(scope, set())
         for t in sorted(tbefore - tafter):
@@ -667,13 +656,13 @@ _SELF_TESTS = {
         "BLOCKER",
     ),
     "local_var_clash": (
-        # _b renamed to b, but b is a LOCAL variable in f -> import silently unused
+        # _b renamed to b, but b is a LOCAL var in f -> import silently unused
         "def f(b):\n    import re as _b\n    return _b.compile(b)\n",
         "import re\ndef f(b):\n    return b.compile(b)\n",  # 'b' is the param, not the module
         "BLOCKER",
     ),
     "substring_safe": (
-        # correct _copy->copy rename while a config_copy var exists: NO false positive
+        # correct _copy->copy rename while config_copy var exists: NO false positive
         "def f(config):\n"
         "    import copy as _copy\n"
         "    config_copy = _copy.deepcopy(config)\n"
@@ -728,10 +717,9 @@ def _pyflakes_undefined(path: str) -> set[str] | None:
 
 
 def audit_files(paths: list[str]) -> int:
-    """Single-version robustness audit. For every file: confirm the analyzer does
-    not crash, then cross-check its 'unresolved' names against pyflakes. Any name
-    the resolver flags that pyflakes does NOT call undefined is a tool FALSE
-    POSITIVE (a resolver gap to fix)."""
+    """Single-version robustness audit: confirm the analyzer doesn't crash, then
+    cross-check its 'unresolved' names against pyflakes. A name the resolver flags
+    that pyflakes accepts is a tool false positive."""
     n_files = n_err = n_fp = n_syntax = 0
     fp_detail: dict[str, set[str]] = {}
     err_detail: dict[str, str] = {}
diff --git a/studio/backend/_platform_compat.py b/studio/backend/_platform_compat.py
index 37bf5e3fb5..013667d5ca 100644
--- a/studio/backend/_platform_compat.py
+++ b/studio/backend/_platform_compat.py
@@ -5,16 +5,15 @@
 Compatibility shim for Anaconda/conda-forge Python builds.
 
 Anaconda puts distributor metadata between pipes in sys.version, e.g.
-'3.12.4 | packaged by Anaconda, Inc. | (main, ...) [MSC ...]'. The hardcoded
-regex in platform._sys_version() can't parse this and raises ValueError;
-CPython closed it as "not planned" (cpython#102396).
+'3.12.4 | packaged by Anaconda, Inc. | (main, ...) [MSC ...]'. The regex in
+platform._sys_version() can't parse this and raises ValueError (cpython#102396,
+closed as "not planned").
 
 We seed platform._sys_version_cache so the stdlib parser never sees the bad
 string, fixing the import chain:
     structlog -> rich.pretty -> attrs._compat -> platform.python_implementation()
 
-Import before any library that may trigger that chain. Idempotent (no-op if the
-cache is already seeded or there are no pipes).
+Import before any library that may trigger that chain. Idempotent.
 """
 
 import platform
@@ -23,14 +22,13 @@ import sys
 
 
 def _seed_sys_version_cache() -> None:
-    """One-shot cache prime: parse a cleaned sys.version and seed the cache."""
+    """Parse a cleaned sys.version and seed the cache once."""
     raw = sys.version
 
     # Strip paired |...| segments (Anaconda, conda-forge metadata)
     cleaned = re.sub(r"\s*\|[^|]*\|\s*", " ", raw).strip()
 
-    # Format B: "ver (build) | label | (build_dup) \n[compiler]" leaves two
-    # consecutive (...) groups after pipe-strip; drop the second.
+    # Pipe-strip can leave two consecutive (...) groups; drop the second.
     cleaned = re.sub(r"(\([^)]*\))\s+\([^)]*\)", r"\1", cleaned)
 
     if "|" in cleaned:
@@ -43,7 +41,6 @@ def _seed_sys_version_cache() -> None:
     if cleaned == raw:
         return  # Nothing to fix
 
-    # Parse the cleaned string through the real stdlib parser
     try:
         result = platform._sys_version(cleaned)
     except ValueError:
diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index 6509cb6825..9dd56489eb 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -156,15 +156,7 @@ async def get_current_subject_allow_password_change(
 async def _get_current_subject(
     credentials: HTTPAuthorizationCredentials, *, allow_password_change: bool
 ) -> str:
-    """
-    FastAPI dependency: validate the JWT and return the subject.
-
-    Use as a dependency on protected routes, e.g.:
-
-        @router.get("/secure")
-        async def secure_endpoint(current_subject: str = Depends(get_current_subject)):
-            ...
-    """
+    """FastAPI dependency: validate the JWT and return the subject. Use on protected routes."""
     token = credentials.credentials
 
     # --- API key path (sk-unsloth-...) ---
diff --git a/studio/backend/auth/hashing.py b/studio/backend/auth/hashing.py
index 873381db04..0a1b0c15be 100644
--- a/studio/backend/auth/hashing.py
+++ b/studio/backend/auth/hashing.py
@@ -23,7 +23,7 @@ def hash_password(password: str, salt: str | None = None) -> Tuple[str, str]:
         "sha256",
         password.encode("utf-8"),
         salt.encode("utf-8"),
-        100_000,  # 100k iterations
+        100_000,
     )
     return salt, dk.hex()
 
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index 42e2de7450..fa5b985513 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -26,30 +26,29 @@ _bootstrap_password: Optional[str] = None
 def generate_bootstrap_password() -> str:
     """Generate a 4-word diceware passphrase and persist it to disk.
 
-    Written to ``_BOOTSTRAP_PW_PATH`` so it survives restarts (the DB only
-    stores the *hash*). Later calls / restarts return the persisted value.
+    Persisted (the DB stores only the hash) so it survives restarts; later
+    calls return the persisted value.
     """
     global _bootstrap_password
 
-    # 1. Already cached in this process?
+    # Cached in this process?
     if _bootstrap_password is not None:
         return _bootstrap_password
 
-    # 2. Already persisted from a previous run?
+    # Persisted from a previous run?
     if _BOOTSTRAP_PW_PATH.is_file():
         _bootstrap_password = _BOOTSTRAP_PW_PATH.read_text().strip()
         if _bootstrap_password:
             return _bootstrap_password
 
-    # 3. First-ever startup — generate a fresh passphrase.
+    # First startup: generate a fresh passphrase.
     import diceware
 
     _bootstrap_password = diceware.get_passphrase(
         options = diceware.handle_options(args = ["-n", "4", "-d", "", "-c"])
     )
 
-    # Persist so the *same* passphrase is reused if the server restarts
-    # before the user changes the password.
+    # Persist so the same passphrase survives restarts until password change.
     ensure_dir(_BOOTSTRAP_PW_PATH.parent)
     _BOOTSTRAP_PW_PATH.write_text(_bootstrap_password)
     try:
@@ -87,17 +86,10 @@ def clear_bootstrap_password() -> None:
 def _hash_token(token: str) -> str:
     """SHA-256 hash helper for refresh token storage.
 
-    Plain SHA-256 is intentional: refresh tokens are high-entropy random
-    strings from ``secrets.token_urlsafe(48)`` (384 bits), so a slow KDF
-    (Argon2 / bcrypt / PBKDF2) adds zero security (2^384 is unbruteforceable
-    regardless of hash speed) while costing tens of ms per refresh. See the
-    OWASP Password Storage Cheat Sheet on hashing high-entropy inputs.
-
-    API keys use the separate ``_pbkdf2_api_key`` helper (PBKDF2-HMAC-SHA256
-    with a persistent server-side salt) — not for crypto reasons (128-bit
-    random tokens don't need slow hashing) but because CodeQL's
-    ``py/weak-sensitive-data-hashing`` query mislabels them as passwords and
-    demands a KDF.
+    Plain SHA-256 is intentional: refresh tokens are 384-bit random strings, so
+    a slow KDF adds no security while costing per-refresh latency. API keys use
+    the separate ``_pbkdf2_api_key`` helper, only to satisfy CodeQL's
+    ``py/weak-sensitive-data-hashing`` query, not for crypto reasons.
     """
     return hashlib.sha256(token.encode("utf-8")).hexdigest()
 
@@ -182,9 +174,8 @@ _api_key_pbkdf2_salt_cache: Optional[bytes] = None
 def _get_or_create_api_key_pbkdf2_salt() -> bytes:
     """Return the persistent API-key PBKDF2 salt, generating it once if missing.
 
-    Stored as a hex-encoded 32-byte random value in ``app_secrets`` under key
-    ``"api_key_pbkdf2_salt"``. Regenerated only when the row is missing (fresh
-    install, or operator deleted it and accepts invalidating existing keys).
+    Hex-encoded 32-byte random value in ``app_secrets``. Regenerated only when
+    the row is missing (fresh install, or operator deleted it).
     """
     global _api_key_pbkdf2_salt_cache
     if _api_key_pbkdf2_salt_cache is not None:
@@ -226,18 +217,10 @@ _DESKTOP_SECRET_CREATED_AT_KEY = "desktop_secret_created_at"
 def _pbkdf2_api_key(raw_key: str) -> str:
     """PBKDF2-HMAC-SHA256 an API key with a persistent server-side salt.
 
-    For API-key storage ONLY, not refresh tokens. Matches the PBKDF2 algorithm
-    + iteration count used by the password hasher in ``auth/hashing.py`` so
-    the codebase is consistent on its credential-storage KDF.
-
-    The slow KDF here is *only* a CodeQL appeasement, not a crypto
-    requirement: API keys are random 128-bit tokens (``secrets.token_hex``),
-    so brute force against 2^128 is infeasible regardless of hash speed.
-    CodeQL's ``py/weak-sensitive-data-hashing`` query mislabels them as
-    "password" data and demands a KDF from its allowlist (Argon2 / scrypt /
-    bcrypt / PBKDF2); we use PBKDF2 per its recommendation page. The salt is
-    still loaded from ``app_secrets`` so dumping the ``api_keys`` table alone
-    can't derive hashes for candidate tokens without the salt row.
+    For API-key storage ONLY, not refresh tokens. The slow KDF is only to
+    appease CodeQL's ``py/weak-sensitive-data-hashing`` query, not a crypto
+    requirement (API keys are random 128-bit tokens). The salt lives in
+    ``app_secrets`` so dumping ``api_keys`` alone can't derive hashes.
     """
     salt = _get_or_create_api_key_pbkdf2_salt()
     dk = hashlib.pbkdf2_hmac(
@@ -502,7 +485,7 @@ def verify_refresh_token(token: str) -> Optional[Tuple[str, bool]]:
     token_hash = _hash_token(token)
     conn = get_connection()
     try:
-        # Clean up any expired tokens while we're here
+        # Opportunistically clean up expired tokens
         conn.execute(
             "DELETE FROM refresh_tokens WHERE expires_at < ?",
             (datetime.now(timezone.utc).isoformat(),),
diff --git a/studio/backend/colab.py b/studio/backend/colab.py
index 1f618a34ab..ba46c52a6a 100644
--- a/studio/backend/colab.py
+++ b/studio/backend/colab.py
@@ -8,8 +8,7 @@ Colab helpers for Unsloth Studio. Uses Colab's built-in proxy.
 from pathlib import Path
 import sys
 
-# Anaconda/conda-forge Python: seed platform._sys_version_cache before any
-# import that triggers attrs -> rich -> structlog -> platform crash.
+# Seed platform._sys_version_cache before attrs->rich->structlog->platform crash on conda Python.
 # See: https://github.com/python/cpython/issues/102396
 _backend_dir = str(Path(__file__).parent)
 if _backend_dir not in sys.path:
@@ -41,7 +40,7 @@ def get_colab_url(port: int = 8888) -> str:
     for attempt in range(3):
         try:
             url = eval_js(f"google.colab.kernel.proxyPort({port})", timeout_sec = 10)
-            # Valid Colab proxy URL starts with https:// and embeds the port.
+            # Valid proxy URL is https:// and embeds the port.
             if url and isinstance(url, str) and url.startswith("https://") and str(port) in url:
                 return url.rstrip("/")
         except Exception as e:
@@ -59,16 +58,13 @@ def get_colab_url(port: int = 8888) -> str:
 def show_link(port: int = 8888, *, _url: "str | None" = None):
     """Display a styled clickable link to the UI.
 
-    *_url* is an optional pre-fetched Colab proxy URL; when omitted,
-    ``get_colab_url(port)`` is called. Pass it from ``_show_and_embed`` to
-    avoid a second ``eval_js`` round-trip.
+    *_url* is an optional pre-fetched proxy URL; pass it to avoid a second eval_js round-trip.
     """
     from IPython.display import display, HTML
 
     url = _url if _url is not None else get_colab_url(port)
 
-    # Truncated display URL. try/except so an unexpected URL shape never
-    # prevents the link from rendering.
+    # Truncated display URL; try/except so an odd URL shape still renders the link.
     try:
         port_prefix = f"{port}-"
         idx = url.index(port_prefix)
@@ -77,7 +73,7 @@ def show_link(port: int = 8888, *, _url: "str | None" = None):
     except (ValueError, IndexError):
         short_url = url
 
-    # Plain-text line so the URL is visible even if HTML display fails.
+    # Plain-text line so the URL shows even if HTML display fails.
     logger.info(f"🌐 Unsloth Studio URL: {url}")
 
     html = f"""
@@ -120,10 +116,8 @@ def _is_studio_healthy(port: int, timeout: float = 2.0) -> bool:
 def _show_and_embed(port: int):
     """Embed the Studio inline for *port* with a branded header bar.
 
-    Fetches the Colab proxy URL once (also registering the port with Colab's
-    reverse-proxy) then renders a header bar + full-height iframe as one HTML
-    block. Falls back to ``serve_kernel_port_as_iframe`` if
-    ``IPython.display.HTML`` is unavailable.
+    Fetches the proxy URL once (registering the port), then renders header bar +
+    iframe. Falls back to serve_kernel_port_as_iframe if IPython HTML is unavailable.
     """
     url = get_colab_url(port)
     logger.info(f"🌐 Unsloth Studio URL: {url}")
@@ -162,7 +156,7 @@ def _show_and_embed(port: int):
 """)
         )
     except Exception:
-        # Fallback: Colab's built-in helper (less control, but always works)
+        # Fallback: Colab's built-in helper.
         try:
             from google.colab import output as colab_output
             colab_output.serve_kernel_port_as_iframe(port, height = 900, width = "100%")
@@ -182,9 +176,8 @@ def start(port: int = 8888):
 
     logger.info("🦥 Starting Unsloth Studio...")
 
-    # --- Fast path: Studio is already running (cell re-run) ---
-    # Re-launching would collide on the port or silently shift to a new one.
-    # Just re-show the link and iframe instead.
+    # Fast path: Studio already running (cell re-run). Re-launching would collide on
+    # the port, so just re-show the link and iframe.
     if _is_studio_healthy(port):
         logger.info(f"   Studio is already running on port {port} — reusing existing server.")
         _show_and_embed(port)
@@ -217,16 +210,14 @@ def start(port: int = 8888):
         logger.error(f"❌ Unsloth Studio failed to start: {exc}")
         return
 
-    # run_server auto-increments the port if the requested one is in use (e.g.
-    # Jupyter on 8888). Read back the bound port so the Colab proxy URL and
-    # iframe point at the right place.
+    # run_server auto-increments the port if in use; read back the bound port so the
+    # proxy URL and iframe point at the right place.
     actual_port: int = getattr(getattr(app, "state", None), "server_port", None) or port
 
     logger.info(f"   Server started on port {actual_port}!")
 
-    # Poll health endpoint to confirm reachability before showing the link and
-    # registering the iframe — avoids the race where ready_event fires but the
-    # process hasn't finished binding.
+    # Poll health endpoint before showing the link — avoids the race where ready_event
+    # fires but the process hasn't finished binding.
     import urllib.request
 
     server_ready = False
@@ -247,9 +238,8 @@ def start(port: int = 8888):
 
     _show_and_embed(actual_port)
 
-    # Keep kernel alive so the daemon server thread stays running. Handle
-    # KeyboardInterrupt cleanly so interrupting the cell gives a readable
-    # message, not a raw traceback.
+    # Keep kernel alive so the daemon server thread runs; handle KeyboardInterrupt
+    # cleanly so interrupting the cell gives a readable message.
     try:
         for _ in range(10000):
             time.sleep(300)
diff --git a/studio/backend/core/__init__.py b/studio/backend/core/__init__.py
index 5400ef0d35..30ecb27f81 100644
--- a/studio/backend/core/__init__.py
+++ b/studio/backend/core/__init__.py
@@ -12,8 +12,8 @@ torch) before the version-activation code runs.
 import sys
 from pathlib import Path
 
-# Put the backend dir on sys.path so bare "from utils.*" imports work when core
-# is imported as a package (e.g. CLI: "from studio.backend.core import ModelConfig").
+# Add backend dir to sys.path so bare "from utils.*" imports work when core
+# is imported as a package.
 _backend_dir = str(Path(__file__).resolve().parent.parent)
 if _backend_dir not in sys.path:
     sys.path.insert(0, _backend_dir)
diff --git a/studio/backend/core/_torchao_stub.py b/studio/backend/core/_torchao_stub.py
index 4a62004bac..6336954bd5 100644
--- a/studio/backend/core/_torchao_stub.py
+++ b/studio/backend/core/_torchao_stub.py
@@ -3,17 +3,11 @@
 
 """Shared torchao Windows-ROCm import stub.
 
-torchao (pulled in by transformers.quantizers) imports
-torch.distributed._functional_collectives at module level, which imports
-distributed_c10d.py unconditionally — that file crashes on Windows ROCm because
-torch._C._distributed_c10d (the RCCL backend) is absent. `import
-torch.distributed` alone is safe (guarded by `if is_available()`); the crash
-only comes via torchao's import chain, so stubbing torchao short-circuits it.
-_StubSubpackageFinder handles any depth of torchao.xxx.yyy imports.
-
-Previously duplicated inline in run_export_process() and run_training_process();
-now both worker subprocesses call the single
-`install_torchao_windows_rocm_stub()` entrypoint before importing
+torchao (pulled in by transformers.quantizers) imports distributed_c10d.py
+unconditionally, which crashes on Windows ROCm because the RCCL backend
+(torch._C._distributed_c10d) is absent. Stubbing torchao short-circuits its
+import chain; _StubSubpackageFinder handles any depth of torchao.xxx.yyy.
+Worker subprocesses call install_torchao_windows_rocm_stub() before importing
 transformers / unsloth_zoo.
 """
 
@@ -27,12 +21,9 @@ import importlib.machinery
 _STUB_SENTINEL = object()
 
 
-# Metaclass for stub types so isinstance(x, StubClass) returns False instead
-# of raising TypeError ("arg 2 must be a type"). peft/tuners/lora/torchao.py
-# does:
-#   from torchao.dtypes import AffineQuantizedTensor, LinearActivationQuantizedTensor
-#   isinstance(weight, (AffineQuantizedTensor, LinearActivationQuantizedTensor))
-# If those names resolve to stub modules rather than types, isinstance() raises.
+# Metaclass for stub types so isinstance(x, StubClass) returns False instead of
+# raising TypeError -- peft's lora/torchao.py does isinstance() against torchao
+# types, which fails if those names resolve to stub modules rather than types.
 class _StubTypeMeta(type):
     def __instancecheck__(cls, instance):
         return False
@@ -70,8 +61,7 @@ def _make_mod_stub(mod_name):
     ):
         if attr.startswith("__"):
             raise AttributeError(attr)
-        # Return a stub CLASS (not a module) so isinstance(x, attr) returns
-        # False instead of raising TypeError.
+        # Return a stub CLASS (not module) so isinstance() returns False, not TypeError.
         child = _make_stub_type(f"{_n}.{attr}")
         setattr(_m, attr, child)
         return child
@@ -113,14 +103,12 @@ class _StubSubpackageFinder(importlib.abc.MetaPathFinder):
 def install_torchao_windows_rocm_stub() -> None:
     """Pre-stub torchao on Windows ROCm so transformers/peft imports don't crash.
 
-    No-op on every other platform (incl. Windows CUDA — there torchao is real
-    and shadowing it would break torchao quantization paths). Must run before
-    any import of transformers / unsloth_zoo. Safe to call once per worker.
+    No-op elsewhere (incl. Windows CUDA, where torchao is real). Must run before
+    importing transformers / unsloth_zoo. Safe to call once per worker.
     """
-    # Gate on the active torch runtime, not env-var presence -- HIP_PATH /
-    # ROCM_PATH stay set after installing the HIP SDK and reverting to a CUDA
-    # torch wheel. AMD SDK / Radeon ROCm wheels may not set torch.version.hip
-    # but still encode "rocm" in torch.__version__, so accept either.
+    # Gate on the active torch runtime, not env-var presence -- HIP_PATH/ROCM_PATH
+    # persist after reverting to a CUDA wheel. Some ROCm wheels lack
+    # torch.version.hip but still encode "rocm" in __version__, so accept either.
     _is_win32_rocm = False
     if sys.platform == "win32":
         try:
@@ -133,8 +121,7 @@ def install_torchao_windows_rocm_stub() -> None:
         except Exception:
             pass
     if _is_win32_rocm:
-        # Register the finder only on Windows ROCm -- elsewhere no stub modules
-        # are seeded, so appending would be pure accumulation.
+        # Register the finder only on Windows ROCm.
         sys.meta_path.append(_StubSubpackageFinder())
         # Seed torchao top-level + key submodules; the finder handles the rest.
         for _tao_name in (
diff --git a/studio/backend/core/data_recipe/__init__.py b/studio/backend/core/data_recipe/__init__.py
index 239e406300..ebc2798375 100644
--- a/studio/backend/core/data_recipe/__init__.py
+++ b/studio/backend/core/data_recipe/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Data Recipe core (DataDesigner wrapper + job runner).
-"""
+"""Data Recipe core (DataDesigner wrapper + job runner)."""
 
 from .jobs import JobManager, get_job_manager
 
diff --git a/studio/backend/core/data_recipe/huggingface.py b/studio/backend/core/data_recipe/huggingface.py
index 3012fed1ea..7a1219b2c3 100644
--- a/studio/backend/core/data_recipe/huggingface.py
+++ b/studio/backend/core/data_recipe/huggingface.py
@@ -95,8 +95,7 @@ def publish_recipe_dataset(
             tags = None,
         )
         card.text = card.text.replace(_DATA_DESIGNER_FOOTER, _UNSLOTH_STUDIO_FOOTER)
-        # Data Designer drops the explicit token when pushing the dataset
-        # card, so push it ourselves to keep auth request-local.
+        # Data Designer drops the explicit token, so push the card ourselves to keep auth request-local.
         card.push_to_hub(repo_id, token = hf_token, repo_type = "dataset")
 
         client._upload_main_dataset_files(
diff --git a/studio/backend/core/data_recipe/jobs/manager.py b/studio/backend/core/data_recipe/jobs/manager.py
index 71c2b7468f..32523e469e 100644
--- a/studio/backend/core/data_recipe/jobs/manager.py
+++ b/studio/backend/core/data_recipe/jobs/manager.py
@@ -132,10 +132,9 @@ class JobManager:
     ) -> str:
         """Spawn the job subprocess (one at a time, no cap).
 
-        ``internal_api_key_id`` is the row id of a workflow-scoped
-        sk-unsloth-* key minted by the route layer for local providers.
-        JobManager revokes it on terminal state so the key's live window is
-        no longer than the run.
+        ``internal_api_key_id`` is a workflow-scoped sk-unsloth-* key row id
+        minted by the route layer; revoked on terminal state so the key's
+        live window is no longer than the run.
         """
         llm_columns = recipe.get("columns") or []
         llm_column_count = 0
@@ -537,15 +536,14 @@ class JobManager:
     def _retire_workflow_key(self, job: Job) -> None:
         """Revoke the workflow-scoped sk-unsloth-* key, if one was minted.
 
-        Best-effort: revocation failures are swallowed. The key expires on
-        its own after 24h, so a missed revoke is a latency concern, not a
-        correctness one.
+        Best-effort: failures are swallowed. The key expires after 24h, so a
+        missed revoke is a latency, not correctness, concern.
         """
         key_id = getattr(job, "internal_api_key_id", None)
         if not key_id:
             return
         try:
-            from auth import storage  # deferred: avoids circular import
+            from auth import storage  # deferred: avoid circular import
             storage.revoke_internal_api_key(int(key_id))
         except Exception:
             pass
diff --git a/studio/backend/core/data_recipe/jobs/parse.py b/studio/backend/core/data_recipe/jobs/parse.py
index e37d7064ed..3be830d0e4 100644
--- a/studio/backend/core/data_recipe/jobs/parse.py
+++ b/studio/backend/core/data_recipe/jobs/parse.py
@@ -327,7 +327,7 @@ def apply_update(job: Job, update: ParsedUpdate) -> None:
         _apply_source_progress(job, update.source_progress)
 
     if update.stage in USAGE_RESET_STAGES:
-        # Usage summary is a short block; reset on entering the next stage.
+        # Usage summary is a short block; reset on the next stage.
         job._in_usage_summary = False
 
     if update.usage_section_start is not None:
diff --git a/studio/backend/core/data_recipe/jobs/types.py b/studio/backend/core/data_recipe/jobs/types.py
index 6dd4db5973..c30606b2d1 100644
--- a/studio/backend/core/data_recipe/jobs/types.py
+++ b/studio/backend/core/data_recipe/jobs/types.py
@@ -90,9 +90,8 @@ class Job:
     progress_columns_total: int | None = None
     source_progress_estimated_total: int | None = None
     completed_columns: list[str] = field(default_factory = list)
-    # Id of the internal sk-unsloth-* API key minted for a local-model
-    # workflow. Revoked when the job ends so the key's window matches the
-    # run rather than its 24h TTL.
+    # Id of the internal sk-unsloth-* API key minted for a local-model workflow.
+    # Revoked when the job ends so the key's window matches the run, not its 24h TTL.
     internal_api_key_id: int | None = None
     _current_usage_model: str | None = None
     _in_usage_summary: bool = False
diff --git a/studio/backend/core/data_recipe/jobs/worker.py b/studio/backend/core/data_recipe/jobs/worker.py
index 27d08e90fe..4073288cb3 100644
--- a/studio/backend/core/data_recipe/jobs/worker.py
+++ b/studio/backend/core/data_recipe/jobs/worker.py
@@ -76,7 +76,7 @@ def run_job_process(*, event_queue, recipe: dict[str, Any], run: dict[str, Any])
     """Subprocess entrypoint. Sends events to `event_queue`."""
     import os
 
-    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
+    os.environ["PYTHONWARNINGS"] = "ignore"  # suppress C-level warnings before imports
 
     import warnings
     from loggers.config import LogConfig
@@ -112,8 +112,8 @@ def run_job_process(*, event_queue, recipe: dict[str, Any], run: dict[str, Any])
         builder = build_config_builder(recipe)
         designer = create_data_designer(recipe, artifact_path = str(_ARTIFACT_ROOT))
 
-        # DataDesigner configures root logging in __init__. Attach the queue
-        # logger to `data_designer` directly so parser events survive root resets.
+        # DataDesigner resets root logging in __init__; attach the queue handler
+        # to the named loggers directly so parser events survive.
         handler = _QueueLogHandler(event_queue)
         handler.setLevel(logging.INFO)
         for logger_name in (
diff --git a/studio/backend/core/data_recipe/local_callable_validators.py b/studio/backend/core/data_recipe/local_callable_validators.py
index a40261fa92..fbe847f9ce 100644
--- a/studio/backend/core/data_recipe/local_callable_validators.py
+++ b/studio/backend/core/data_recipe/local_callable_validators.py
@@ -184,7 +184,7 @@ def _build_oxc_validation_function(lang: str, validation_mode: str, code_shape:
     normalized_code_shape = code_shape if code_shape in _OXC_CODE_SHAPES else "auto"
 
     def _validator(df):
-        import pandas as pd  # imported lazily for local callable runtime
+        import pandas as pd  # lazy import for local callable runtime
 
         row_count = int(len(df.index))
         if row_count == 0:
diff --git a/studio/backend/core/data_recipe/service.py b/studio/backend/core/data_recipe/service.py
index addbe8f848..9d8ca5cfcc 100644
--- a/studio/backend/core/data_recipe/service.py
+++ b/studio/backend/core/data_recipe/service.py
@@ -167,10 +167,8 @@ def _validate_recipe_runtime_support(recipe: dict[str, Any], model_providers: li
 def build_mcp_providers(recipe: dict[str, Any]) -> list:
     from data_designer.config.mcp import LocalStdioMCPProvider, MCPProvider  # pyright: ignore[reportMissingImports]
 
-    # Same gate as the chat MCP path: stdio providers spawn a local
-    # subprocess, so build them only when this host allows it (desktop /
-    # explicit opt-in). Otherwise a recipe carried onto a hosted host
-    # cannot spawn.
+    # Same gate as the chat MCP path: stdio providers spawn a local subprocess,
+    # so build them only when this host allows it (desktop / explicit opt-in).
     from core.inference.mcp_client import stdio_mcp_enabled
 
     stdio_allowed = stdio_mcp_enabled()
@@ -283,9 +281,8 @@ def create_data_designer(recipe: dict[str, Any], *, artifact_path: str | None =
     model_providers = build_model_providers(recipe)
     _validate_recipe_runtime_support(recipe, model_providers)
 
-    # DataDesigner requires at least one model provider in its registry even
-    # when the pipeline has no LLM columns. Supply a lightweight stub so
-    # sampler/expression-only recipes can run without a real provider.
+    # DataDesigner requires >=1 model provider even with no LLM columns; stub
+    # one so sampler/expression-only recipes run without a real provider.
     if not model_providers:
         from data_designer.config.models import ModelProvider  # pyright: ignore[reportMissingImports]
         model_providers = [
diff --git a/studio/backend/core/export/__init__.py b/studio/backend/core/export/__init__.py
index db9d1b352c..f7241cd925 100644
--- a/studio/backend/core/export/__init__.py
+++ b/studio/backend/core/export/__init__.py
@@ -1,12 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Export submodule - Model export operations
+"""Export submodule - model export operations.
 
-The default get_export_backend() returns an ExportOrchestrator that
-delegates to a subprocess. The original ExportBackend runs inside the
-subprocess and can be imported directly from .export when needed.
+get_export_backend() returns an ExportOrchestrator that delegates to a
+subprocess. The original ExportBackend runs inside the subprocess and can be
+imported directly from .export when needed.
 """
 
 from .orchestrator import ExportOrchestrator, get_export_backend
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index aaae8002fc..d5a3de06df 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-# backend/export.py
 """Export backend - exports models in various formats."""
 
 import glob
@@ -44,10 +43,8 @@ def _is_wsl():
 def _apply_wsl_sudo_patch():
     """On WSL, monkey-patch do_we_need_sudo() to return False.
 
-    WSL lacks passwordless sudo, and do_we_need_sudo() runs
-    `sudo apt-get update`, which hangs on a stdin password in a
-    non-interactive subprocess. setup.sh pre-installs the build deps on
-    WSL, so sudo isn't needed at runtime.
+    WSL lacks passwordless sudo and do_we_need_sudo()'s `sudo apt-get update`
+    hangs on a stdin password; setup.sh pre-installs the build deps anyway.
     """
     if not _is_wsl():
         return
@@ -108,18 +105,15 @@ class ExportBackend:
         try:
             logger.info("Starting memory cleanup...")
 
-            # Unload all inference-backend models
             model_names = list(self.inference_backend.models.keys())
             for model_name in model_names:
                 self.inference_backend.unload_model(model_name)
 
-            # Clear current export state
             self.current_model = None
             self.current_tokenizer = None
             self.current_checkpoint = None
             self._audio_type = None
 
-            # Clear GPU cache (handles gc + backend-specific cleanup)
             clear_gpu_cache()
 
             logger.info("Memory cleanup completed successfully")
@@ -156,7 +150,6 @@ class ExportBackend:
         try:
             logger.info(f"Loading checkpoint: {checkpoint_path}")
 
-            # Cleanup existing models first
             self.cleanup_memory()
 
             checkpoint_path_obj = Path(checkpoint_path)
@@ -171,11 +164,9 @@ class ExportBackend:
 
             model_id = base_model or checkpoint_path
 
-            # Detect audio type and vision
             self._audio_type = detect_audio_type(model_id)
             self.is_vision = not self._audio_type and is_vision_model(model_id)
 
-            # Load model based on type
             if self._audio_type == "csm":
                 from unsloth import FastModel
                 from transformers import CsmForConditionalGeneration
@@ -255,7 +246,6 @@ class ExportBackend:
                     trust_remote_code = trust_remote_code,
                 )
 
-            # Detect PEFT / LoRA model
             if _IS_MLX:
                 # MLX doesn't use PeftModel — detect LoRA via adapter_config.json
                 self.is_peft = adapter_config.exists()
@@ -345,7 +335,6 @@ class ExportBackend:
                 else:
                     save_method = "merged_16bit"
 
-            # Save locally if requested
             if save_directory:
                 save_directory = str(resolve_export_dir(save_directory))
                 logger.info(f"Saving merged model locally to: {save_directory}")
@@ -366,7 +355,6 @@ class ExportBackend:
                 logger.info(f"Model saved successfully to {save_directory}")
                 output_path = str(Path(save_directory).resolve())
 
-            # Push to hub if requested
             if push_to_hub:
                 if not repo_id or not hf_token:
                     return (
@@ -447,7 +435,6 @@ class ExportBackend:
 
         output_path: Optional[str] = None
         try:
-            # Save locally if requested
             if save_directory:
                 save_directory = str(resolve_export_dir(save_directory))
                 logger.info(f"Saving base model locally to: {save_directory}")
@@ -470,7 +457,6 @@ class ExportBackend:
                 logger.info(f"Model saved successfully to {save_directory}")
                 output_path = str(Path(save_directory).resolve())
 
-            # Push to hub if requested
             if push_to_hub:
                 if not repo_id or not hf_token:
                     return (
@@ -519,7 +505,6 @@ class ExportBackend:
                     )
                     username = repo_id.split("/")[0]
 
-                    # Build and push model card
                     content = MODEL_CARD.format(
                         username = username,
                         base_model = base_model,
@@ -530,7 +515,6 @@ class ExportBackend:
                     card = ModelCard(content)
                     card.push_to_hub(repo_id, token = hf_token, commit_message = "Unsloth Model Card")
 
-                    # Upload files
                     if save_directory:
                         hf_api.upload_folder(
                             folder_path = save_directory,
@@ -583,10 +567,8 @@ class ExportBackend:
             # unsloth expects lowercase quant method
             quant_method = quantization_method.lower()
 
-            # Pin convert_hf_to_gguf.py to the same llama.cpp ref as the
-            # llama-quantize binary (Studio installs at a tagged ref via
-            # setup.sh) so it can't drift past the pinned binary's gguf API.
-            # Set before both branches; hub-only export has save_directory == "".
+            # Pin convert_hf_to_gguf.py to setup.sh's tagged llama.cpp ref so it
+            # can't drift past the pinned llama-quantize binary's gguf API.
             global _LLAMA_CPP_SCRIPTS_WARNING_EMITTED
             try:
                 from unsloth_zoo.llama_cpp import (
@@ -605,12 +587,10 @@ class ExportBackend:
                     )
                     _LLAMA_CPP_SCRIPTS_WARNING_EMITTED = True
 
-            # Save locally if requested
             if save_directory:
                 save_directory = str(resolve_export_dir(save_directory))
-                # Use absolute path so unsloth's relative-path internals
-                # (check_llama_cpp, use_local_gguf, _download_convert_hf_to_gguf)
-                # resolve against the repo root cwd, NOT the export directory.
+                # Absolute path so unsloth's relative-path internals resolve
+                # against the repo root cwd, not the export directory.
                 abs_save_dir = os.path.abspath(save_directory)
                 logger.info(f"Saving GGUF model locally to: {abs_save_dir}")
 
@@ -619,15 +599,11 @@ class ExportBackend:
                 # On WSL, patch out sudo check before llama.cpp build
                 _apply_wsl_sudo_patch()
 
-                # Snapshot existing .gguf files in cwd before conversion;
-                # unsloth's convert_to_gguf writes output relative to cwd
-                # (repo root), so we diff afterwards and relocate.
+                # convert_to_gguf writes output relative to cwd (repo root);
+                # snapshot existing .gguf so we can diff and relocate afterwards.
                 cwd = os.getcwd()
                 pre_existing_ggufs = set(glob.glob(os.path.join(cwd, "*.gguf")))
 
-                # Absolute path — no os.chdir needed. unsloth saves intermediate
-                # HF model files into model_save_path; unsloth-zoo's
-                # check_llama_cpp() uses ~/.unsloth/llama.cpp by default.
                 model_save_path = os.path.join(abs_save_dir, "model")
                 self.current_model.save_pretrained_gguf(
                     model_save_path,
@@ -635,18 +611,14 @@ class ExportBackend:
                     quantization_method = quant_method,
                 )
 
-                # Relocate GGUF artifacts into the export directory.
-                # convert_to_gguf writes .gguf to cwd (repo root) because
-                # --outfile is a relative path like "model.Q4_K_M.gguf".
+                # Relocate the .gguf that convert_to_gguf wrote to cwd (repo root).
                 new_ggufs = set(glob.glob(os.path.join(cwd, "*.gguf"))) - pre_existing_ggufs
                 for src in sorted(new_ggufs):
                     dest = os.path.join(abs_save_dir, os.path.basename(src))
                     shutil.move(src, dest)
                     logger.info(f"Relocated GGUF: {os.path.basename(src)} → {abs_save_dir}/")
 
-                # Flatten any .gguf from subdirs into abs_save_dir.
-                # save_pretrained_gguf may create subdirs (e.g. model_gguf/)
-                # named differently from model_save_path.
+                # Flatten any .gguf from subdirs (e.g. model_gguf/) into abs_save_dir.
                 for sub in list(Path(abs_save_dir).iterdir()):
                     if not sub.is_dir():
                         continue
@@ -654,13 +626,11 @@ class ExportBackend:
                         dest = os.path.join(abs_save_dir, src.name)
                         shutil.move(str(src), dest)
                         logger.info(f"Relocated GGUF: {src.name} → {abs_save_dir}/")
-                    # Clean up the subdir (intermediate HF files, etc.)
                     shutil.rmtree(str(sub), ignore_errors = True)
                     logger.info(f"Cleaned up subdirectory: {sub.name}")
 
-                # For non-PEFT models, save_pretrained_gguf redirects to the
-                # checkpoint path, leaving a *_gguf dir in outputs/. Relocate
-                # any GGUFs from there and clean it up.
+                # For non-PEFT models, save_pretrained_gguf leaves a *_gguf dir at
+                # the checkpoint path; relocate its GGUFs and clean it up.
                 if self.current_checkpoint:
                     ckpt = Path(self.current_checkpoint)
                     gguf_dir = ckpt.parent / f"{ckpt.name}_gguf"
@@ -680,7 +650,6 @@ class ExportBackend:
                 # Write export metadata so the Chat page can identify the base model
                 self._write_export_metadata(abs_save_dir)
 
-                # Log final file locations (post-relocation).
                 final_ggufs = sorted(glob.glob(os.path.join(abs_save_dir, "*.gguf")))
                 logger.info(
                     "GGUF export complete. Final files in %s:\n  %s",
@@ -689,7 +658,6 @@ class ExportBackend:
                 )
                 output_path = str(Path(abs_save_dir).resolve())
 
-            # Push to hub if requested
             if push_to_hub:
                 if not repo_id or not hf_token:
                     return (
@@ -743,7 +711,6 @@ class ExportBackend:
 
         output_path: Optional[str] = None
         try:
-            # Save locally if requested
             if save_directory:
                 save_directory = str(resolve_export_dir(save_directory))
                 logger.info(f"Saving LoRA adapter locally to: {save_directory}")
@@ -759,7 +726,6 @@ class ExportBackend:
                 logger.info(f"Adapter saved successfully to {save_directory}")
                 output_path = str(Path(save_directory).resolve())
 
-            # Push to hub if requested
             if push_to_hub:
                 if not repo_id or not hf_token:
                     return (
diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.py
index 49c1af8822..20158d1891 100644
--- a/studio/backend/core/export/orchestrator.py
+++ b/studio/backend/core/export/orchestrator.py
@@ -28,9 +28,7 @@ logger = get_logger(__name__)
 
 _CTX = mp.get_context("spawn")
 
-# Max captured log lines kept in memory per export orchestrator;
-# scrollback for the live export log panel. 4000 lines is ~1 MB
-# worst-case at 256 chars/line.
+# Max log lines kept per orchestrator (live log panel scrollback); ~1 MB worst-case.
 _LOG_BUFFER_MAXLEN = 4000
 
 
@@ -44,13 +42,10 @@ class ExportOrchestrator:
     """
 
     def __init__(self):
-        # Subprocess state.
         self._proc: Optional[mp.Process] = None
         self._cmd_queue: Any = None
         self._resp_queue: Any = None
-        # Serializes export ops (load_checkpoint, export_*, cleanup) so
-        # concurrent HTTP requests can't interleave commands on the
-        # subprocess queue.
+        # Serializes export ops so concurrent HTTP requests can't interleave commands.
         self._lock = threading.Lock()
 
         # Local state mirrors (updated from subprocess responses).
@@ -58,25 +53,15 @@ class ExportOrchestrator:
         self.is_vision: bool = False
         self.is_peft: bool = False
 
-        # ── Live log capture ─────────────────────────────────────
-        # Thread-safe ring buffer of log lines from the worker
-        # subprocess. Powers the GET /api/export/logs/stream SSE
-        # endpoint the export dialog consumes.
+        # Thread-safe ring buffer of worker log lines; powers the export logs SSE endpoint.
         self._log_buffer: Deque[Dict[str, Any]] = deque(maxlen = _LOG_BUFFER_MAXLEN)
         self._log_lock = threading.Lock()
-        # Monotonic sequence number. Never reset across operations, so
-        # SSE clients can use it as a stable cursor even if clear_logs()
-        # runs mid-session.
+        # Monotonic seq, never reset, so SSE clients have a stable cursor across clear_logs().
         self._log_seq: int = 0
-        # Snapshot of _log_seq at the start of the current run (set by
-        # clear_logs()). The SSE endpoint defaults its cursor here so a
-        # client connecting AFTER the worker's first lines still sees the
-        # full run. Lines in the current run have seq > _run_start_seq;
-        # prior-run lines have seq <= it.
+        # _log_seq snapshot at the current run's start; SSE defaults its cursor here so a
+        # late-connecting client still sees the full run. Current run has seq > this.
         self._run_start_seq: int = 0
-        # True while an export op (load/export/cleanup) is running. The
-        # SSE endpoint ends the stream 1s after this flips False to drain
-        # trailing log lines.
+        # True while an export op runs; SSE ends the stream 1s after this flips False.
         self._export_active: bool = False
 
         atexit.register(self._cleanup)
@@ -87,12 +72,7 @@ class ExportOrchestrator:
     # ------------------------------------------------------------------
 
     def _append_log(self, entry: Dict[str, Any]) -> None:
-        """Append a worker-subprocess log line to the buffer.
-
-        Entries look like {"type": "log", "stream": "stdout"|"stderr",
-        "line": "...", "ts": ...}. Each gets a monotonic seq number so
-        SSE clients can cursor through new lines.
-        """
+        """Append a worker log line to the buffer, stamped with a monotonic seq."""
         line = entry.get("line")
         if not line:
             return
@@ -108,17 +88,10 @@ class ExportOrchestrator:
             )
 
     def clear_logs(self) -> None:
-        """Drop buffered log lines from a previous operation.
+        """Drop buffered log lines from a previous op so the UI shows only this run.
 
-        Called at the start of each export op so the UI shows only the
-        current run. The seq counter is NOT reset, so an SSE client that
-        captured the cursor before clear_logs() still sees new lines
-        (with strictly greater seq).
-
-        Also snapshots the current seq into ``_run_start_seq`` so the SSE
-        endpoint can anchor its default cursor at this run's start.
-        Anything appended after has seq > the snapshot, reachable via
-        ``get_logs_since(get_run_start_seq())``.
+        The seq counter is NOT reset (clients keep a stable cursor); the current seq
+        is snapshotted into ``_run_start_seq`` to anchor the SSE default cursor.
         """
         with self._log_lock:
             self._log_buffer.clear()
@@ -138,12 +111,7 @@ class ExportOrchestrator:
             return self._log_seq
 
     def get_run_start_seq(self) -> int:
-        """Return the seq captured at the start of the current run.
-
-        The SSE endpoint uses this as the default cursor so a client
-        connecting AFTER the worker started emitting still sees every
-        line from the current run.
-        """
+        """Return the seq captured at the current run's start (SSE default cursor)."""
         with self._log_lock:
             return self._run_start_seq
 
@@ -187,22 +155,19 @@ class ExportOrchestrator:
             self._proc = None
             return
 
-        # 1. Drain stale responses.
         self._drain_queue()
 
-        # 2. Send shutdown command.
         try:
             self._cmd_queue.put({"type": "shutdown"})
         except (OSError, ValueError):
             pass
 
-        # 3. Wait for graceful shutdown.
         try:
             self._proc.join(timeout = timeout)
         except Exception:
             pass
 
-        # 4. Force kill if still alive.
+        # Force kill if still alive.
         if self._proc is not None and self._proc.is_alive():
             logger.warning("Export subprocess did not exit gracefully, terminating")
             try:
@@ -272,7 +237,6 @@ class ExportOrchestrator:
             resp = self._read_resp(timeout = min(remaining, 2.0))
 
             if resp is None:
-                # Check subprocess health.
                 if not self._ensure_subprocess_alive():
                     raise RuntimeError("Export subprocess crashed during wait")
                 continue
@@ -294,9 +258,7 @@ class ExportOrchestrator:
             if rtype == "status":
                 message = resp.get("message", "")
                 logger.info("Export subprocess status: %s", message)
-                # Surface status in the live log panel too so users see
-                # high-level progress (e.g. "Importing Unsloth...",
-                # "Loading checkpoint: ...") alongside subprocess output.
+                # Surface status in the live log panel for high-level progress.
                 if message:
                     self._append_log(
                         {
@@ -477,13 +439,10 @@ class ExportOrchestrator:
         )
 
     def _run_export(self, export_type: str, params: dict) -> Tuple[bool, str, Optional[str]]:
-        """Send an export command to the subprocess and wait for result.
+        """Send an export command and wait for the result.
 
-        Returns ``(success, message, output_path)``. ``output_path`` is
-        the resolved on-disk dir the worker wrote to (None when the
-        export only pushed to Hub or failed before writing). Surfaced via
-        the export route's ``details.output_path`` so the dialog's success
-        screen shows where the model landed.
+        Returns ``(success, message, output_path)``. ``output_path`` is the on-disk
+        dir the worker wrote to (None if it only pushed to Hub or failed pre-write).
         """
         with self._lock:
             if not self._ensure_subprocess_alive():
@@ -517,7 +476,6 @@ class ExportOrchestrator:
         """Cleanup export-related models from memory."""
         with self._lock:
             if not self._ensure_subprocess_alive():
-                # No subprocess — clear local state.
                 self.current_checkpoint = None
                 self.is_vision = False
                 self.is_peft = False
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index a517d6d7b1..fb2a893014 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -1,16 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Export subprocess entry point.
+"""Export subprocess entry point.
 
-Each export session runs in a persistent subprocess (mp.get_context("spawn")),
-giving a clean interpreter with no stale module state — solving the
-transformers version-switching problem completely.
-
-The subprocess stays alive while a model is loaded, accepting commands
-(load, export_merged, export_base, export_gguf, export_lora, cleanup,
-shutdown) via mp.Queue.
+Each export session runs in a persistent subprocess (mp spawn), giving a clean
+interpreter with no stale module state, which solves transformers version
+switching. The subprocess stays alive while a model is loaded, accepting commands
+(load, export_*, cleanup, shutdown) via mp.Queue.
 
 Pattern follows core/inference/worker.py and core/training/worker.py.
 """
@@ -31,40 +27,31 @@ from typing import Any
 logger = get_logger(__name__)
 
 
-# Gate controlling whether captured stdout/stderr lines are forwarded to
-# the parent's resp_queue (and on to the export-dialog SSE stream). Closed
-# by default so the noisy bootstrap phase -- transformers venv activation,
-# Unsloth/torch imports, base-model resolution, "Top GGUF/hub models" lists,
-# vision detection, weight loading bars -- is suppressed in the UI.
-# _handle_export() opens the gate when actual export work starts and leaves
-# it open; the orchestrator spawns a fresh subprocess for the next checkpoint
-# load (see orchestrator._spawn_subprocess), resetting this state.
-#
-# Lines dropped while the gate is closed are still echoed to the saved
-# original stdout/stderr fds so the server console / log file keeps the full
-# output for debugging.
+# Gate controlling whether captured stdout/stderr lines are forwarded to the
+# parent's resp_queue (and on to the export-dialog SSE stream). Closed by default
+# so the noisy bootstrap phase (imports, model resolution, loading bars) is
+# suppressed in the UI; _handle_export() opens it when export work starts. The
+# orchestrator spawns a fresh subprocess per checkpoint load, resetting this.
+# Dropped lines are still echoed to the saved fds so the server log keeps them.
 _log_forward_gate = threading.Event()
 
 
 def _setup_log_capture(resp_queue: Any) -> None:
-    """Redirect fds 1 and 2 through pipes so every line printed by this
-    worker and any child it spawns is forwarded to the parent via resp_queue
-    as {"type": "log", ...} messages.
+    """Redirect fds 1 and 2 through pipes so every line printed by this worker
+    and any child it spawns is forwarded to the parent via resp_queue as
+    {"type": "log", ...} messages.
 
     Must run BEFORE LogConfig.setup_logging and any ML imports, else library
     handlers may capture the original stderr reference and bypass the pipe.
-
-    Lines are also echoed back to the original stdout/stderr so the server
-    console keeps the full subprocess output, even while
-    ``_log_forward_gate`` is closed.
+    Lines are also echoed back to the original fds so the server console keeps
+    the full output even while ``_log_forward_gate`` is closed.
     """
 
     try:
         saved_out_fd = os.dup(1)
         saved_err_fd = os.dup(2)
     except OSError:
-        # dup failed (exotic platforms) - give up quietly; export still
-        # works, just no live log streaming.
+        # dup failed; give up quietly (export still works, no live streaming).
         return
 
     try:
@@ -86,13 +73,11 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 pass
         return
 
-    # Close the write ends we just dup2'd (fds 1 and 2 are now the real
-    # write ends).
+    # Close the write ends we just dup2'd (fds 1 and 2 are the real write ends).
     os.close(w_out)
     os.close(w_err)
 
-    # Replace sys.stdout/sys.stderr with line-buffered writers bound to the
-    # (now-redirected) fds 1 and 2.
+    # Replace sys.stdout/sys.stderr with line-buffered writers on fds 1 and 2.
     try:
         sys.stdout = os.fdopen(1, "w", buffering = 1, encoding = "utf-8", errors = "replace")
         sys.stderr = os.fdopen(2, "w", buffering = 1, encoding = "utf-8", errors = "replace")
@@ -110,8 +95,7 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 continue
             if not chunk:
                 break
-            # Echo to the original fd so the server console keeps the
-            # full output.
+            # Echo to the original fd so the server console keeps the full output.
             try:
                 os.write(echo_fd, chunk)
             except OSError:
@@ -131,9 +115,8 @@ def _setup_log_capture(resp_queue: Any) -> None:
                 if not line:
                     continue
                 if not _log_forward_gate.is_set():
-                    # Gate closed (bootstrap) -- already echoed to the saved
-                    # console fd above; drop the line so the export dialog
-                    # doesn't see import / vendoring noise.
+                    # Gate closed (bootstrap): already echoed above; drop the
+                    # line so the export dialog skips import noise.
                     continue
                 try:
                     resp_queue.put_nowait(
@@ -145,8 +128,7 @@ def _setup_log_capture(resp_queue: Any) -> None:
                         }
                     )
                 except Exception:
-                    # Queue put failed (full, closed, etc.) - drop the line
-                    # rather than crash the reader thread.
+                    # Queue put failed; drop the line rather than crash the thread.
                     pass
         if buf and _log_forward_gate.is_set():
             try:
@@ -179,7 +161,7 @@ def _setup_log_capture(resp_queue: Any) -> None:
 
 def _activate_transformers_version(model_name: str) -> None:
     """Activate the correct transformers version BEFORE any ML imports."""
-    # Ensure backend is on sys.path for utils imports
+    # Ensure backend is on sys.path for utils imports.
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -265,11 +247,9 @@ def _handle_export(backend, cmd: dict, resp_queue: Any) -> None:
     export_type = cmd["export_type"]  # "merged", "base", "gguf", "lora"
     response_type = f"export_{export_type}_done"
 
-    # Open the log forwarding gate so the user sees actual export progress
-    # (Unsloth merge bars, file copies, GGUF conversion, etc.) in the live
-    # log panel. The gate stays open for the rest of this subprocess's life;
-    # the orchestrator spawns a fresh subprocess for the next checkpoint
-    # load, which resets the gate to closed.
+    # Open the log forwarding gate so the user sees export progress in the live
+    # log panel. Stays open for the rest of this subprocess's life; the
+    # orchestrator spawns a fresh subprocess per checkpoint load, resetting it.
     _log_forward_gate.set()
 
     output_path: Any = None
@@ -370,23 +350,16 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
     """
     import queue as _queue
 
-    # Install fd-level stdout/stderr capture FIRST so every subsequent print
-    # and every child process inherits the redirected fds. This powers the
-    # live export log stream in the UI.
+    # Install fd-level stdout/stderr capture FIRST so every subsequent print and
+    # every child process inherits the redirected fds (powers the live log stream).
     _setup_log_capture(resp_queue)
 
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
-    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
-    # Force unbuffered output from child Python processes (e.g. the GGUF
-    # converter) so their prints surface in the log stream as they happen,
-    # not at the end.
+    os.environ["PYTHONWARNINGS"] = "ignore"  # suppress C-level warnings before imports
+    # Unbuffered output from child Python (e.g. GGUF converter) so prints surface live.
     os.environ["PYTHONUNBUFFERED"] = "1"
-    # tqdm defaults to a 10-second mininterval when stdout is not a tty
-    # (it isn't -- we redirected fd 1/2 to a pipe), making multi-step
-    # progress bars look frozen in the export log panel. Force frequent
-    # flushes so the user sees movement during merge / GGUF conversion. No
-    # effect on single-step bars (e.g. "Copying 1 files") which only emit
-    # start/end events anyway.
+    # tqdm defaults to a 10s mininterval when stdout isn't a tty (we redirected
+    # fd 1/2 to a pipe), making multi-step bars look frozen; force frequent flushes.
     os.environ.setdefault("TQDM_MININTERVAL", "0.5")
 
     import warnings
@@ -430,10 +403,8 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
             )
 
     # ── 1c. Stub torchao on Windows ROCm ──
-    # Shared with the training worker; see core/_torchao_stub.py for the full
-    # rationale (torchao -> torch.distributed._functional_collectives crashes
-    # on Windows ROCm: RCCL backend absent). No-op off Windows ROCm. Must run
-    # before importing transformers / unsloth_zoo.
+    # See core/_torchao_stub.py: torchao crashes on Windows ROCm (RCCL absent).
+    # No-op off Windows ROCm. Must run before importing transformers / unsloth_zoo.
     from core._torchao_stub import install_torchao_windows_rocm_stub
 
     install_torchao_windows_rocm_stub()
@@ -509,7 +480,7 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
 
         try:
             if cmd_type == "load":
-                # Load a new checkpoint, reusing this subprocess
+                # Load a new checkpoint, reusing this subprocess.
                 backend.cleanup_memory()
                 _handle_load(backend, cmd, resp_queue)
 
diff --git a/studio/backend/core/inference/_html_to_md.py b/studio/backend/core/inference/_html_to_md.py
index b6262d9974..e7de4a5312 100644
--- a/studio/backend/core/inference/_html_to_md.py
+++ b/studio/backend/core/inference/_html_to_md.py
@@ -81,9 +81,7 @@ class _MarkdownRenderer(HTMLParser):
         self._pre_parts: list[str] = []
         self._in_inline_code: bool = False
 
-        # Blockquote state -- stack of output buffers so nested blockquotes
-        # each collect their own content and get prefixed with the correct
-        # number of ">" markers on close.
+        # Blockquote state: stack of buffers so nested blockquotes get the right ">" depth.
         self._bq_stack: list[list[str]] = []
 
     # ------------------------------------------------------------------
@@ -116,10 +114,7 @@ class _MarkdownRenderer(HTMLParser):
                 prefixed.append(">")
         return "\n".join(prefixed)
 
-    # ------------------------------------------------------------------
-    # Table helpers -- flush open cells/rows so HTML with omitted optional
-    # end tags (</td>, </tr>) does not lose data.
-    # ------------------------------------------------------------------
+    # Table helpers: flush open cells/rows so omitted </td>/</tr> don't lose data.
     def _finish_cell(self) -> None:
         if not self._in_cell:
             return
@@ -142,10 +137,7 @@ class _MarkdownRenderer(HTMLParser):
         self._current_row = []
         self._row_has_th = False
 
-    # ------------------------------------------------------------------
-    # Link text helper -- normalize whitespace so block-level content inside
-    # an <a> does not produce multiline Markdown link labels.
-    # ------------------------------------------------------------------
+    # Link text helper: normalize whitespace so block content in <a> stays single-line.
     def _finish_link(self) -> None:
         text = re.sub(r"\s+", " ", "".join(self._link_text_parts)).strip()
         href = self._link_href or ""
@@ -234,22 +226,19 @@ class _MarkdownRenderer(HTMLParser):
             self._emit("\n\n")
 
         elif tag == "tr":
-            # Flush any open cell/row from a previous row that omitted its
-            # optional </td> or </tr> end tags.
+            # Flush open cell/row from a prior row that omitted </td>/</tr>.
             self._finish_cell()
             self._finish_row()
 
         elif tag in ("th", "td"):
-            # Flush any open cell (handles omitted </td>/<th>).
-            self._finish_cell()
+            self._finish_cell()  # handles omitted </td>/</th>
             self._cell_parts = []
             self._in_cell = True
             if tag == "th":
                 self._row_has_th = True
 
         elif tag == "img":
-            # Skip images -- keeps page text focused on readable content and
-            # avoids data-URI amplification.
+            # Skip images: keeps text readable, avoids data-URI amplification.
             return
 
     def handle_endtag(self, tag: str) -> None:
@@ -310,7 +299,7 @@ class _MarkdownRenderer(HTMLParser):
             self._finish_row()
 
         elif tag == "table":
-            # Flush any remaining row (handles omitted </tr>).
+            # Flush remaining row (handles omitted </tr>).
             self._finish_cell()
             self._finish_row()
             self._in_table = False
@@ -331,9 +320,7 @@ class _MarkdownRenderer(HTMLParser):
             return
         # Collapse all whitespace (including newlines) per HTML rules.
         text = re.sub(r"\s+", " ", data)
-        # Suppress whitespace-only text nodes between table structural elements
-        # (source indentation) so leading spaces don't break Markdown table
-        # row alignment.
+        # Suppress whitespace-only nodes between table elements (source indentation).
         if self._in_table and not self._in_cell and not text.strip():
             return
         self._emit(text)
@@ -348,18 +335,10 @@ class _MarkdownRenderer(HTMLParser):
             return
         self._emit(html.unescape(f"&#{name};"))
 
-    # ------------------------------------------------------------------
     # Flush pending buffers (handles truncated HTML from capped fetches)
-    # ------------------------------------------------------------------
     def flush_pending(self) -> None:
-        """Flush any open side-buffers into ``_out``.
-
-        Called after ``close()`` to recover content from truncated HTML where
-        closing tags were never seen (common when ``_fetch_page_text`` caps the
-        download by byte count).
-        """
+        """Flush open side-buffers into ``_out`` after close(), recovering truncated HTML."""
         # Flush innermost buffers first so their content propagates outward.
-
         if self._in_link:
             self._finish_link()
 
@@ -388,15 +367,9 @@ class _MarkdownRenderer(HTMLParser):
                 self._out.append("\n\n" + prefixed + "\n\n")
 
 
-# ------------------------------------------------------------------
 # Post-processing
-# ------------------------------------------------------------------
 def _cleanup(text: str) -> str:
-    """Normalize whitespace and blank lines in the final output.
-
-    Preserves content inside fenced code blocks verbatim so intentional blank
-    lines in ``<pre>`` content are not collapsed.
-    """
+    """Normalize whitespace and blank lines, preserving fenced code blocks verbatim."""
     lines = text.split("\n")
     out: list[str] = []
     in_fence = False
@@ -411,7 +384,6 @@ def _cleanup(text: str) -> str:
             continue
 
         if in_fence:
-            # Preserve code block content exactly as-is.
             out.append(line)
             continue
 
@@ -427,15 +399,11 @@ def _cleanup(text: str) -> str:
     return "\n".join(out).strip()
 
 
-# ------------------------------------------------------------------
 # Public API
-# ------------------------------------------------------------------
 def html_to_markdown(source_html: str) -> str:
-    """Convert an HTML string to Markdown.
+    """Convert HTML to Markdown (headings, links, emphasis, lists, tables, blockquotes, code, entities).
 
-    Handles headings, links, bold/italic, ordered/unordered lists, tables,
-    blockquotes, code blocks, and HTML entities. ``<script>``, ``<style>``,
-    and ``<head>`` sections are stripped entirely.
+    ``<script>``, ``<style>``, and ``<head>`` are stripped entirely.
     """
     # Normalize line endings before parsing.
     source_html = source_html.replace("\r\n", "\n").replace("\r", "\n")
diff --git a/studio/backend/core/inference/anthropic_compat.py b/studio/backend/core/inference/anthropic_compat.py
index ce5f5c220f..c1f1c6b81e 100644
--- a/studio/backend/core/inference/anthropic_compat.py
+++ b/studio/backend/core/inference/anthropic_compat.py
@@ -75,8 +75,7 @@ def anthropic_messages_to_openai(
             continue
 
         if role == "assistant":
-            # Assistant content carries text + tool_use; images aren't
-            # part of Anthropic's assistant content model.
+            # Assistant content: text + tool_use only (no images in Anthropic's model).
             text_parts: list[str] = []
             tool_calls: list[dict] = []
             for block in content:
@@ -104,9 +103,7 @@ def anthropic_messages_to_openai(
             continue
 
         if role == "user":
-            # Ordered part list to preserve text/image interleaving (e.g.
-            # [text, image, text, image]). tool_result blocks become their
-            # own OpenAI "tool" role messages.
+            # Ordered parts preserve text/image interleaving; tool_result -> own "tool" messages.
             user_parts: list[dict] = []
             has_image = False
             tool_results: list[dict] = []
@@ -137,8 +134,7 @@ def anthropic_messages_to_openai(
             if has_image:
                 result.append({"role": "user", "content": user_parts})
             else:
-                # No images: collapse text parts to a plain string so
-                # text-only callers keep their simple shape.
+                # No images: collapse text parts to a plain string.
                 text = "\n".join(p["text"] for p in user_parts)
                 if text:
                     result.append({"role": "user", "content": text})
@@ -317,11 +313,9 @@ class AnthropicStreamEmitter:
             return self._tool_arguments_delta(args)
 
         events = []
-        # Close current text block if open.
         if self._text_block_open:
             events.append(self._close_block())
-        # Defensive: if a different tool_start arrives while a tool_use
-        # block is open, close the stale block before starting another.
+        # Defensive: close a stale open tool_use block before starting another.
         elif self._open_tool_call_id is not None:
             events.append(self._close_block())
             self._open_tool_call_id = None
diff --git a/studio/backend/core/inference/audio_codecs.py b/studio/backend/core/inference/audio_codecs.py
index c6d87d44f0..93c7da72cb 100644
--- a/studio/backend/core/inference/audio_codecs.py
+++ b/studio/backend/core/inference/audio_codecs.py
@@ -90,8 +90,8 @@ class AudioCodecManager:
         import os
         import sys
 
-        # Clone SparkAudio/Spark-TTS for the sparktts package (same as
-        # training; the HF model repos don't contain it)
+        # Clone SparkAudio/Spark-TTS for the sparktts package (HF model repos
+        # don't contain it)
         spark_code_dir = os.path.join(os.path.dirname(model_repo_path or "."), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
@@ -127,9 +127,8 @@ class AudioCodecManager:
         import os
         import sys
 
-        # Clone OuteTTS (same pattern as Spark-TTS / BiCodec). The pip
-        # package has problematic deps; the notebook clones and removes
-        # gguf_model.py, interface.py, __init__.py before importing.
+        # Clone OuteTTS (the pip package has problematic deps; we remove
+        # gguf_model.py, interface.py, __init__.py before importing).
         base_dir = os.path.dirname(os.path.abspath(__file__))
         outetts_code_dir = os.path.join(base_dir, "OuteTTS")
         outetts_pkg = os.path.join(outetts_code_dir, "outetts")
@@ -148,8 +147,7 @@ class AudioCodecManager:
                 env = child_env_without_native_path_secret(),
                 **_windows_hidden_subprocess_kwargs(),
             )
-            # Remove files pulling in heavy / incompatible deps (matches
-            # notebook: gguf_model.py under models/, others under outetts/)
+            # Remove files pulling in heavy / incompatible deps
             remove_paths = [
                 os.path.join(outetts_pkg, "models", "gguf_model.py"),
                 os.path.join(outetts_pkg, "interface.py"),
@@ -178,13 +176,10 @@ class AudioCodecManager:
     # ── Decoders ─────────────────────────────────────────────────
 
     def decode_snac(self, generated_ids: torch.Tensor, device: str) -> Tuple[bytes, int]:
-        """
-        Decode SNAC tokens (Orpheus) into WAV bytes.
-
-        generated_ids: full model output including prompt tokens. Finds the
-        START_OF_SPEECH (128257) marker, extracts codes after it, strips EOS
-        (128258), redistributes 7-per-frame codes into 3 SNAC layers.
+        """Decode SNAC tokens (Orpheus) into WAV bytes.
 
+        Finds the START_OF_SPEECH (128257) marker, extracts codes after it,
+        strips EOS (128258), redistributes 7-per-frame codes into 3 SNAC layers.
         Returns (wav_bytes, 24000).
         """
         # Find START_OF_SPEECH token (128257)
@@ -229,16 +224,13 @@ class AudioCodecManager:
         return _numpy_to_wav_bytes(waveform, 24000), 24000
 
     def decode_csm(self, audio_values: torch.Tensor) -> Tuple[bytes, int]:
-        """
-        Decode CSM output (already a waveform from model.generate(output_audio=True)).
-        Returns (wav_bytes, 24000).
-        """
+        """Decode CSM output (already a waveform). Returns (wav_bytes, 24000)."""
         waveform = audio_values[0].to(torch.float32).cpu().numpy()
         return _numpy_to_wav_bytes(waveform, 24000), 24000
 
     def decode_bicodec(self, generated_text: str, device: str) -> Tuple[bytes, int]:
-        """
-        Decode BiCodec tokens (Spark-TTS) from generated text.
+        """Decode BiCodec tokens (Spark-TTS) from generated text.
+
         Extracts bicodec_semantic_N and bicodec_global_N tokens via regex.
         Returns (wav_bytes, sample_rate).
         """
@@ -256,8 +248,8 @@ class AudioCodecManager:
 
         semantic_ids = torch.tensor([int(t) for t in semantic_matches]).long().unsqueeze(0)
 
-        # Speaker encoder expects exactly 32 global tokens (token_num=32 in
-        # BiCodec config). Pad with zeros or truncate to 32.
+        # Speaker encoder expects exactly 32 global tokens (token_num=32);
+        # pad with zeros or truncate.
         GLOBAL_TOKEN_NUM = 32
         if global_matches:
             raw = [int(t) for t in global_matches]
@@ -279,8 +271,8 @@ class AudioCodecManager:
         return _numpy_to_wav_bytes(wav_np, sr), sr
 
     def decode_dac(self, generated_text: str, device: str) -> Tuple[bytes, int]:
-        """
-        Decode DAC tokens (OuteTTS) from generated text.
+        """Decode DAC tokens (OuteTTS) from generated text.
+
         Extracts c1_N and c2_N codec code tokens via regex.
         Returns (wav_bytes, 24000).
         """
diff --git a/studio/backend/core/inference/defaults.py b/studio/backend/core/inference/defaults.py
index f14c03dad2..b64605e16f 100644
--- a/studio/backend/core/inference/defaults.py
+++ b/studio/backend/core/inference/defaults.py
@@ -49,7 +49,7 @@ DEFAULT_MODELS_STANDARD = [
 
 
 def get_default_models() -> list[str]:
-    hw.get_device()  # ensure detect_hardware() has run
+    hw.get_device()  # ensures detect_hardware() has run
     if hw.CHAT_ONLY:
         return list(DEFAULT_MODELS_GGUF)
     return list(DEFAULT_MODELS_STANDARD)
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index 3132ad6f86..a7d44b992d 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -19,36 +19,25 @@ from urllib.parse import urlparse
 import httpx
 import structlog
 
-# Use structlog so INFO diagnostics surface in the backend's JSON log
-# stream. The stdlib root logger defaults to WARNING with no handlers, so
-# `logging.getLogger(__name__).info(...)` was silently dropped (only
-# WARNING/ERROR reached uvicorn's stderr capture). Existing call sites use
-# printf-style positional args, which structlog accepts.
+# structlog so INFO diagnostics reach the backend's JSON log stream (the
+# stdlib root logger defaults to WARNING with no handlers). It accepts the
+# existing printf-style positional args.
 logger = structlog.get_logger(__name__)
 
 
-# Claude 4.7 (Opus/Sonnet/Haiku) removed temperature, top_p, and top_k —
-# the API returns 400 "<param> is deprecated for this model" if any is set
-# to a non-default value. Authoritative ref ("Sampling parameters removed"):
+# Claude 4.7 (Opus/Sonnet/Haiku) removed temperature/top_p/top_k — the API
+# 400s "<param> is deprecated for this model" on a non-default value. 3.x and
+# 4.5/4.6 still accept them, so match the 4-7 line strictly. Ref:
 #   https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7
-# 3.x and 4.5/4.6 still accept all three; match the 4-7 line strictly so the
-# knobs keep working on earlier families. The -4-7[-.]/EOL anchor keeps
-# future versions (e.g. claude-opus-5) unaffected.
 def _is_openai_family_cloud(base_url: Optional[str]) -> bool:
     """True iff ``base_url`` points at OpenAI cloud or Azure OpenAI Foundry.
 
-    Anchored to the URL host so the gate can't be bypassed with a path or
-    subdomain like ``https://evil.com/api.openai.com/v1`` or
-    ``https://api.openai.com.attacker.com/v1`` (CodeQL py/incomplete-url-
-    substring-sanitization). Scopes cloud-only Responses-API extensions
-    (prompt_cache_retention, context_management compaction, container shell
-    tool) that 400 on non-cloud OpenAI-compatible servers (ollama /
-    llama.cpp / vLLM).
-
-    Azure Foundry resources live at ``<resource-name>.openai.azure.com``;
-    match any subdomain via `endswith` on the lowercased host, with the
-    leading dot so `openai.azure.com` itself doesn't slip through (no
-    apex-hosted Azure Foundry endpoint exists).
+    Anchored to the URL host so a path/subdomain like
+    ``https://api.openai.com.attacker.com/v1`` can't bypass it (CodeQL
+    py/incomplete-url-substring-sanitization). Scopes cloud-only Responses-API
+    extensions that 400 on non-cloud OAI-compat servers (ollama/llama.cpp/vLLM).
+    Azure Foundry resources live at ``<resource>.openai.azure.com``; the leading
+    dot on `endswith` stops `openai.azure.com` apex from matching.
     """
     if not base_url:
         return False
@@ -263,14 +252,12 @@ def _anthropic_thinking_spec(model: str) -> Optional[_AnthropicThinkingSpec]:
     return None
 
 
-# Anthropic ships date-pinned tool versions per model family. Per the
-# tool-reference docs (https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference)
-# the newer `_20260209` / `_20260120` variants only run on Opus 4.6/4.7
-# and Sonnet 4.6 (web_search / web_fetch) or Opus 4.5+ and Sonnet 4.5+
-# (code_execution). New versions on an older model return 400 "tool not
-# supported"; old versions on a new model miss the dynamic-filtering and
-# free-with-search pricing path. Pick the newest combination the model
-# accepts, else the GA (`_20250305` / `_20250910` / `_20250825`) defaults.
+# Anthropic ships date-pinned tool versions per model family: the newer
+# `_20260209`/`_20260120` variants only run on recent models (400 "tool not
+# supported" elsewhere), and old versions on a new model miss dynamic
+# filtering and free-with-search pricing. Pick the newest combo the model
+# accepts, else the GA `_20250305`/`_20250910`/`_20250825` defaults. Ref:
+# https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
 _ANTHROPIC_NEW_WEB_PREFIXES = (
     "claude-opus-4-7",
     "claude-opus-4-6",
@@ -315,12 +302,10 @@ def _anthropic_code_execution_version(model: str) -> str:
 _ANTHROPIC_CODE_EXECUTION_BETA = "code-execution-2025-08-25"
 
 
-# Anthropic server-side context compaction (beta as of compact-2026-01-12).
-# The compaction tool currently supports Opus 4.6, Opus 4.7, Sonnet 4.6 and
-# Mythos Preview. The beta header is the same for every supported model; the
-# dated `compact_20260112` type lives in the body's
-# `context_management.edits` array. Models outside this prefix list are
-# silently ignored so we don't 400 upstream.
+# Anthropic server-side context compaction (beta compact-2026-01-12), supported
+# on Opus 4.6/4.7, Sonnet 4.6 and Mythos Preview. Same beta header for all; the
+# dated `compact_20260112` type lives in body `context_management.edits`. Models
+# outside the prefix list are silently ignored so we don't 400 upstream.
 _ANTHROPIC_COMPACTION_PREFIXES = (
     "claude-opus-4-7",
     "claude-opus-4-6",
@@ -1490,12 +1475,8 @@ class ExternalProviderClient:
             first_args = _json.loads(first_args_raw)
         except Exception:
             first_args = {}
-        # Log the raw arguments to confirm the server ran the search. The shape
-        # is loosely documented but in practice the model emits
-        # `{"search_result":{"search_id":...}, "usage":{"total_tokens":N}}` —
-        # an opaque receipt where N is the token cost of the injected search
-        # context. The query string is NOT present; Kimi runs the search
-        # server-side during the first call and bakes the results into context.
+        # Args are an opaque receipt (`{"search_result":..., "usage":{"total_tokens":N}}`),
+        # not a query — Kimi runs the search server-side and bakes results into context.
         logger.info(
             "Kimi $web_search: %d tool_call(s), args[0]=%s",
             len(search_calls),
@@ -1516,13 +1497,8 @@ class ExternalProviderClient:
                 "arguments": first_args if isinstance(first_args, dict) else {},
             }
         )
-        # Kimi's search has already run server-side by the time the first call
-        # returns (the tool_call envelope encodes the search result reference,
-        # not a query for us to dispatch). Emit tool_end NOW so the UI's
-        # web-search card transitions to "complete" before the second call
-        # streams the answer — otherwise the card sits in "running" through the
-        # whole answer and the user perceives the model answering before search
-        # finishes.
+        # The search already ran server-side, so emit tool_end now — otherwise the
+        # UI card sits in "running" through the whole second-call answer.
         yield _build_kimi_tool_end(_synthetic_chunk, tool_call_id, [])
 
         # ---- Second call: echo the tool_calls back and stream answer ----
@@ -1542,14 +1518,10 @@ class ExternalProviderClient:
         ]
         followup_body = dict(body)
         followup_body["messages"] = list(messages) + [assistant_msg] + tool_msgs
-        # Ask the SSE stream for a final `usage` block so we see prompt_tokens
-        # (which jumps to thousands when the server injects search context).
-        # Without this, OpenAI-compat streams omit usage entirely; Kimi follows
-        # the same convention.
+        # Request a final `usage` block (OAI-compat streams omit it otherwise) so
+        # we can see prompt_tokens jump when search context is injected.
         followup_body["stream_options"] = {"include_usage": True}
-        # Keep the tool definition on the second call so the model can search
-        # again mid-turn if needed. Kimi's doc shows the same tools array on
-        # every step.
+        # Keep the tool on the second call so the model can search again mid-turn.
 
         try:
             async with _http_client.stream(
@@ -1571,10 +1543,8 @@ class ExternalProviderClient:
                     return
 
                 lines_gen = response.aiter_lines().__aiter__()
-                # Diagnostics: latch usage.prompt_tokens from the final chunk.
-                # Kimi docs say search results count toward prompt_tokens, so a
-                # big value here is direct evidence the server injected results
-                # into context.
+                # Latch final usage; a big prompt_tokens is evidence the server
+                # injected search results into context.
                 last_usage: Optional[dict[str, Any]] = None
                 annotation_shapes: set[str] = set()
                 try:
@@ -1596,11 +1566,9 @@ class ExternalProviderClient:
                                     usage = parsed.get("usage")
                                     if isinstance(usage, dict):
                                         last_usage = usage
-                                    # Scan annotations only for diagnostics —
-                                    # Kimi today doesn't emit url_citation, but
-                                    # if a future version does we'll see the
-                                    # type name in the final log line and can
-                                    # wire it into the tool_end payload.
+                                    # Scan annotations for diagnostics only; Kimi
+                                    # doesn't emit url_citation today, but a future
+                                    # version's type name would show in the log.
                                     for choice in parsed.get("choices") or []:
                                         if not isinstance(choice, dict):
                                             continue
@@ -1733,12 +1701,8 @@ class ExternalProviderClient:
                     if part.get("type") == "text":
                         anthropic_parts.append({"type": "text", "text": part["text"]})
                     elif part.get("type") == "compaction":
-                        # Round-trip the compaction block. When the prior
-                        # assistant turn ran server-side compaction, that block
-                        # must land back on this turn's assistant message so
-                        # Anthropic skips re-compaction from scratch. Forward
-                        # verbatim under the {type:"compaction", content:"..."}
-                        # shape the API expects. See
+                        # Round-trip a prior turn's compaction block back onto this
+                        # assistant message so Anthropic skips re-compaction. Ref:
                         #   https://platform.claude.com/docs/en/build-with-claude/compaction
                         summary = part.get("content") or ""
                         if isinstance(summary, str) and summary:
@@ -1772,20 +1736,13 @@ class ExternalProviderClient:
                                 }
                             )
                     elif part.get("type") == "input_document":
-                        # `input_document` is Studio's normalised content type
-                        # for PDFs / docs. The frontend sends either
-                        # `{type:"input_document", file_data:"data:application/pdf;base64,..."}`
-                        # or `{type:"input_document", file_url:"https://..."}`,
-                        # plus optional `filename` and `media_type`. Translate
-                        # to Anthropic's native `document` block.
+                        # Studio's normalised PDF/doc type (file_data data-URI or
+                        # file_url) -> Anthropic's native `document` block.
                         url = part.get("file_url") or ""
                         data_uri = part.get("file_data") or ""
                         title = part.get("filename")
-                        # Treat any "data:" URI with no actual base64 payload
-                        # (`data:application/pdf;base64,` or whitespace-only) as
-                        # missing so the file_url branch below can take over.
-                        # Matches the OpenAI-side fallback so a malformed inline
-                        # payload + valid remote URL still attaches.
+                        # Treat a "data:" URI with no base64 payload as missing so
+                        # the file_url branch can take over (matches OpenAI side).
                         data_uri_valid = False
                         b64data = ""
                         header = ""
@@ -1923,12 +1880,9 @@ class ExternalProviderClient:
                     continue
                 filtered.append(msg)
 
-        # Claude 4.7 family removed temperature / top_p / top_k entirely. The
-        # earlier guard only handled top_k; temperature is now also rejected
-        # with 400 "temperature is deprecated for this model". Latch the match
-        # once and reuse it everywhere temperature or top_k would be set —
-        # including the thinking-mode override below, which used to force
-        # temperature=1.
+        # Claude 4.7 removed temperature/top_p/top_k entirely (400 "deprecated
+        # for this model"). Latch the match and reuse it wherever those are set,
+        # including the thinking-mode override below that used to force temp=1.
         sampling_removed = bool(_ANTHROPIC_4_7_SAMPLING_REMOVED.match(model))
 
         body: dict[str, Any] = {
@@ -1941,14 +1895,11 @@ class ExternalProviderClient:
             body["temperature"] = temperature
         if top_k is not None and top_k > 0 and not sampling_removed:
             body["top_k"] = top_k
-        # Anthropic only caches a prefix when at least one cache_control marker
-        # is attached. The frontend defaults enable_prompt_caching to True for
-        # Anthropic, so treat `None` as True here (callers that don't set the
-        # flag still get caching). Pass False explicitly to opt out.
+        # Anthropic caches a prefix only with a cache_control marker. Treat None
+        # as True (frontend default); pass False to opt out.
         prompt_caching_enabled = enable_prompt_caching is not False
-        # Optional 1h cache TTL is GA as of 2026-05 (no beta header). 1h writes
-        # are 2x vs 5m's 1.25x but reads are 0.1x for both, so 1h wins after a
-        # single extra hit. Unknown TTL strings drop.
+        # Optional 1h cache TTL is GA (no beta header). 1h writes cost 2x vs 5m's
+        # 1.25x but reads are 0.1x for both, so 1h wins after one extra hit.
         cache_marker: dict[str, Any] = {"type": "ephemeral"}
         if prompt_cache_ttl in ("5m", "1h"):
             cache_marker["ttl"] = prompt_cache_ttl
@@ -1967,14 +1918,10 @@ class ExternalProviderClient:
                 body["system"] = system
 
         if prompt_caching_enabled and filtered:
-            # Second breakpoint at the end of the conversation. Anthropic caches
-            # the longest matching prefix up to a cache_control marker; placing
-            # one on the latest message means turn N+1 rehydrates everything
-            # through turn N from cache instead of recomputing. This makes
-            # caching work when the system prompt is empty or shorter than
-            # Anthropic's ~1024-token cache floor — the conversation history
-            # carries the bulk of input tokens. Anthropic allows up to 4
-            # breakpoints per request; we use at most 2 (system + tail).
+            # Second breakpoint on the latest message so turn N+1 rehydrates
+            # through turn N from cache. Covers the case where the system prompt
+            # is below Anthropic's ~1024-token cache floor. (Max 4 breakpoints;
+            # we use 2: system + tail.)
             last_msg = filtered[-1]
             content = last_msg.get("content")
             if isinstance(content, str):
@@ -1986,10 +1933,8 @@ class ExternalProviderClient:
                     }
                 ]
             elif isinstance(content, list) and content:
-                # Don't mutate the caller's list. Rebuild the tail with
-                # cache_control on the final block so an upstream image-bearing
-                # turn still cleanly slots into the cache as part of the
-                # conversational prefix.
+                # Rebuild the tail (don't mutate the caller's list) with
+                # cache_control on the final block.
                 head = list(content[:-1])
                 tail = content[-1]
                 if isinstance(tail, dict):
@@ -2002,10 +1947,8 @@ class ExternalProviderClient:
             thinking_spec.efforts if thinking_spec else ("none", "low", "medium", "high")
         )
         effort = reasoning_effort if reasoning_effort in allowed_efforts else None
-        # Claude 4.6 Opus/Sonnet accept top-tier adaptive effort as "max" only;
-        # "xhigh" is rejected (supported on Claude 4.7). Map our shared "xhigh"
-        # to "max" for 4.6 outbound requests while still accepting both in
-        # ``allowed_efforts`` for persisted / cross-provider UI state.
+        # Claude 4.6 takes top-tier adaptive effort as "max" only ("xhigh" is
+        # 4.7-only), so map "xhigh" -> "max" for 4.6 outbound requests.
         if effort == "xhigh" and model.startswith(("claude-opus-4-6", "claude-sonnet-4-6")):
             effort = "max"
         if effort is None:
@@ -2018,30 +1961,20 @@ class ExternalProviderClient:
         if effort and effort != "none":
             # Anthropic rejects top_k whenever thinking is enabled.
             body.pop("top_k", None)
-            # Earlier families (4.5/4.6) require temperature=1 when thinking is
-            # enabled and forbid top_p in the same request:
-            #   "temperature and top_p cannot both be specified for this
-            #    model. Please use only one."
-            # On Claude 4.7, temperature was removed entirely — any value
-            # (including 1) returns 400 — so skip the override there and let
-            # the model use its default sampling.
+            # 4.5/4.6 require temperature=1 with thinking and forbid top_p in the
+            # same request; 4.7 removed temperature entirely (any value 400s), so
+            # skip the override there.
             if not sampling_removed:
                 body["temperature"] = 1
             body.pop("top_p", None)
             if thinking_spec and thinking_spec.kind == "adaptive":
-                # `display` defaults to "omitted" on Claude Opus 4.7 (per the
-                # adaptive-thinking docs) — without an explicit opt-in the API
-                # emits an empty thinking block plus a signature_delta, so our
-                # SSE handler would surface a stray <think></think> and the
-                # reasoning panel would stay blank. Force "summarized" so 4.7
-                # streams thinking_delta events like 4.6 does. On 4.6 / Sonnet
-                # 4.6 this is the default, so setting it is harmless.
+                # Force display="summarized": it defaults to "omitted" on Opus 4.7,
+                # which emits an empty thinking block and leaves the panel blank.
+                # Harmless no-op on 4.6.
                 body["thinking"] = {"type": "adaptive", "display": "summarized"}
-                # Per the Messages API reference, the effort knob for adaptive
-                # thinking lives under `output_config.effort` — NOT as a
-                # top-level field. Sending `effort: ...` directly produces a 400
-                # "effort: Extra inputs are not permitted". Allowed values:
-                # low | medium | high | xhigh | max. See:
+                # Adaptive effort lives under `output_config.effort`, not top-level
+                # (top-level 400s "Extra inputs are not permitted"). Allowed:
+                # low|medium|high|xhigh|max. See
                 # https://platform.claude.com/docs/en/api/messages
                 body["output_config"] = {"effort": effort}
             elif thinking_spec and thinking_spec.kind == "manual":
@@ -2099,10 +2032,9 @@ class ExternalProviderClient:
             )
             body["tools"] = anthropic_tools
 
-        # Anthropic server-side code execution — see
+        # Anthropic server-side code execution (date-pinned type per model, both
+        # unlocked by the same beta header set below). See
         # https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
-        # Date-pinned tool type per model; both unlock via the same
-        # `code-execution-2025-08-25` beta header set below.
         code_execution_enabled = bool(
             _anthropic_hosted_builtins_allowed
             and enabled_tools
@@ -2282,14 +2214,9 @@ class ExternalProviderClient:
                 # document_citations tool_event on message_stop for the Sources
                 # panel.
                 document_citations: list[dict[str, Any]] = []
-                # Counts surfaced in the final log line so reports of
-                # "Code execution did nothing" can be triaged at a
-                # glance. generated_files_count is interesting for the
-                # future Files API PR — when bash creates files inside
-                # the container, they show up as file_id entries on
-                # bash_code_execution_result.content, and v1 drops
-                # them. Track the count so we know how often it would
-                # have mattered.
+                # Surfaced in the final log line. generated_files_count tracks
+                # file_id entries on bash_code_execution_result.content that v1
+                # drops, to gauge how often the future Files API PR would matter.
                 code_execution_generated_files = 0
                 # Container id captured from `message_start.message.container.id`
                 # when code_execution is enabled. Emit a `container_ready`
@@ -2298,12 +2225,9 @@ class ExternalProviderClient:
                 # from the inbound id — no churn on reuse.
                 latched_container_id: Optional[str] = None
                 container_id_emitted = False
-                # Cache usage tracking. message_start carries input accounting
-                # (incl. cache_creation_input_tokens and
-                # cache_read_input_tokens); message_delta carries cumulative
-                # output_tokens. Both surface in the "stream complete" log so
-                # prompt caching can be verified per-request without opening the
-                # Anthropic dashboard.
+                # Cache usage from message_start (cache_creation/read_input_tokens)
+                # and message_delta (output_tokens), logged on stream complete so
+                # caching is verifiable per-request without the dashboard.
                 last_usage: dict[str, Any] = {}
 
                 def _content_chunk(text: str) -> str:
@@ -2464,11 +2388,8 @@ class ExternalProviderClient:
                             key = event_type or "<unknown>"
                         event_counts[key] = event_counts.get(key, 0) + 1
 
-                        # message_start carries the input-side usage block incl.
-                        # cache_creation_input_tokens and
-                        # cache_read_input_tokens. message_delta updates
-                        # output_tokens (and may overwrite the input fields with
-                        # final values). Merge both into last_usage.
+                        # Merge input-side usage from message_start with
+                        # message_delta's output_tokens into last_usage.
                         if event_type == "message_start":
                             start_usage = (event.get("message") or {}).get("usage")
                             if isinstance(start_usage, dict):
@@ -2544,12 +2465,9 @@ class ExternalProviderClient:
                                 "bash_code_execution_tool_result",
                                 "text_editor_code_execution_tool_result",
                             ):
-                                # Anthropic ships the full result content on the
-                                # start event for code-exec result blocks
-                                # (unlike web_search, which can split across
-                                # deltas). Capture it and finalize on
-                                # content_block_stop so ordering matches the
-                                # web_search path.
+                                # Code-exec result content arrives whole on the
+                                # start event; finalize on content_block_stop to
+                                # match the web_search ordering.
                                 tool_use_id = content_block.get("tool_use_id", "")
                                 inner = content_block.get("content") or {}
                                 current_code_exec_result = {
@@ -2615,13 +2533,9 @@ class ExternalProviderClient:
                                         idx_for_marker = len(document_citations)
                                     yield _content_chunk(f"[{idx_for_marker}]")
                             elif delta_type == "input_json_delta":
-                                # Streamed partial_json carrying tool inputs —
-                                # the search query for web_search, or
-                                # command/path/etc. for code execution. Route to
-                                # whichever buffer is open. The state slots are
-                                # exclusive in practice (Anthropic doesn't
-                                # interleave tool input streams), but checking
-                                # all keeps the dispatch robust if that changes.
+                                # partial_json carrying tool inputs (web_search
+                                # query, code-exec command, etc.); route to
+                                # whichever buffer is open.
                                 partial = delta.get("partial_json", "")
                                 if current_server_tool_use is not None:
                                     current_server_tool_use["buffer"] += partial
@@ -2711,13 +2625,9 @@ class ExternalProviderClient:
                                 )
                                 current_code_exec_use = None
                             elif current_compaction is not None:
-                                # End of a compaction block. Emit it as a
-                                # synthetic tool_event so the chat-adapter can
-                                # persist the {type:"compaction", content:"..."}
-                                # payload onto the assistant message. The next
-                                # turn's request body forwards the content_part
-                                # verbatim and Anthropic recognises it as the
-                                # prior compaction state.
+                                # End of a compaction block: emit a synthetic
+                                # tool_event so the chat-adapter persists it onto
+                                # the assistant message for next-turn round-trip.
                                 compaction_blocks_seen += 1
                                 yield _emit_tool_event(
                                     {
@@ -2787,14 +2697,8 @@ class ExternalProviderClient:
                                 )
                                 current_web_fetch_use = None
                             elif current_web_fetch_result is not None:
-                                # End of the web_fetch_tool_result — format Title
-                                # / URL / snippet for the frontend source pill
-                                # and emit tool_end. `inner` is sanitised to a
-                                # dict at the matching content_block_start, and
-                                # the formatter always returns a non-empty string
-                                # (defaulting to "(fetch complete)" when no
-                                # fields are present), so no extra fallback is
-                                # needed here.
+                                # End of the web_fetch_tool_result — format the
+                                # source pill and emit tool_end.
                                 tool_use_id = current_web_fetch_result["tool_use_id"]
                                 result_text = _format_web_fetch_result(
                                     current_web_fetch_result["inner"]
@@ -2835,14 +2739,10 @@ class ExternalProviderClient:
                                     if c_in or c_out:
                                         last_usage["compaction_input_tokens"] = c_in
                                         last_usage["compaction_output_tokens"] = c_out
-                            # Anthropic reports the code_execution container id
-                            # on `message_delta.delta.container.{id,
-                            # expires_at}` (NOT on message_start — at start the
-                            # container isn't provisioned yet). Latch on first
-                            # sight and emit container_ready only when the value
-                            # differs from the inbound id, so steady-state reuse
-                            # doesn't re-write the same id to the thread record
-                            # every turn.
+                            # Container id is on message_delta.delta.container
+                            # (not message_start; not provisioned yet there).
+                            # Emit container_ready only when it differs from the
+                            # inbound id so reuse doesn't re-write it every turn.
                             delta_obj = event.get("delta") or {}
                             container_obj = delta_obj.get("container")
                             if isinstance(container_obj, dict) and latched_container_id is None:
@@ -2946,20 +2846,15 @@ class ExternalProviderClient:
                     await lines_gen.aclose()  # now safe — aclose() is a no-op
                     raise
                 finally:
-                    # Surface per-event-type counts + web_search summary so
-                    # reports of "no reasoning panel content" / "Search didn't
-                    # do anything" can be triaged at a glance.
+                    # Per-event-type counts + web_search summary for triage.
                     web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                     web_search_invocations = len(web_search_calls)
                     total_results = sum(
                         len(sc.get("results") or []) for sc in web_search_calls.values()
                     )
                     queries = [sc["query"] for sc in web_search_calls.values() if sc.get("query")]
-                    # cache_read_input_tokens > 0 on turn N proves the
-                    # cache_control marker on the system block is working —
-                    # turn 1 shows cache_creation > 0 instead. cache_creation
-                    # tokens are billed at a small premium; cache_read tokens
-                    # at a discount.
+                    # cache_read_input_tokens > 0 proves the cache_control marker
+                    # works (turn 1 shows cache_creation instead).
                     code_execution_invocations = len(code_execution_calls)
                     code_execution_results = sum(
                         1 for c in code_execution_calls.values() if c.get("result") is not None
@@ -3088,12 +2983,9 @@ class ExternalProviderClient:
         """
         import json as _json
 
-        # Validate the user-controlled model id BEFORE any message translation.
-        # A model like `../cachedContents/x` is path-traversal landing in
-        # `/v1beta/cachedContents/...`; rejecting it here also avoids triggering
-        # user-controlled outbound fetches (remote image_url inlining) on a
-        # request we'll error out anyway. Documented catalog ids match
-        # `[A-Za-z0-9._-]+`.
+        # Validate the user-controlled model id first: `../cachedContents/x` is
+        # path traversal, and rejecting early avoids attacker-triggered outbound
+        # image fetches on a doomed request. Catalog ids match `[A-Za-z0-9._-]+`.
         if not re.fullmatch(r"[A-Za-z0-9._-]+", model):
             yield _error_sse_line(
                 400,
@@ -3160,11 +3052,9 @@ class ExternalProviderClient:
                                 header.split(";")[0].replace("data:", "").strip().lower()
                                 or "image/jpeg"
                             )
-                            # Symmetry with the fetched remote image path, which
-                            # already rejects non-image Content-Type. A
-                            # `data:text/html;base64,...` URL otherwise lands as
-                            # Gemini inlineData with mimeType="text/html" and
-                            # 400s the whole request.
+                            # Reject non-image data URLs (e.g. data:text/html);
+                            # they'd 400 the request as inlineData. Mirrors the
+                            # remote-fetch path's Content-Type check.
                             if not media_type.startswith("image/"):
                                 logger.info(
                                     "Gemini inlineData: refusing non-image data URL media_type=%s",
@@ -3199,10 +3089,9 @@ class ExternalProviderClient:
                                     )
                         elif url:
                             # fileData.fileUri only accepts Files-API URIs and
-                            # YouTube; everything else must be downloaded and
-                            # inlined. Parse fields explicitly so attacker URLs
-                            # like https://evil.com/youtube.com/x aren't
-                            # misclassified as YouTube.
+                            # YouTube; everything else is downloaded and inlined.
+                            # Parse host explicitly so e.g.
+                            # https://evil.com/youtube.com/x isn't mis-detected.
                             try:
                                 _parsed_image_url = urlparse(url)
                             except (ValueError, UnicodeError):
@@ -3472,12 +3361,9 @@ class ExternalProviderClient:
                         fc_part["thoughtSignature"] = sig
                     parts.append(fc_part)
             if role == "tool":
-                # If the matching assistant-side tool_call was dropped
-                # (synthetic server-tool with no native part) or already
-                # replayed as Gemini-native parts
-                # (code_execution/image_generation native_part), drop the
-                # follow-up too. Emitting it as a functionResponse would be
-                # orphaned or duplicate the native result.
+                # Drop the follow-up if its assistant-side tool_call was dropped
+                # or already replayed as native parts; else it would be an
+                # orphan/duplicate functionResponse.
                 _tc_id_for_skip = msg.get("tool_call_id")
                 if (
                     isinstance(_tc_id_for_skip, str)
@@ -3496,13 +3382,8 @@ class ExternalProviderClient:
                         tool_name = tool_call_names[tc_id]
                 response_payload: Any
                 if isinstance(content, list):
-                    # OpenAI tool messages may carry list-form content
-                    # (`[{"type":"text","text":"..."}]`). Forwarding the
-                    # content-part objects verbatim into Gemini's
-                    # `functionResponse.response.result` yields
-                    # `result:[{"type":"text","text":"..."}]` instead of the
-                    # actual tool output text; flatten text parts so the result
-                    # mirrors the string-content path.
+                    # Flatten list-form tool content to text so the
+                    # functionResponse result matches the string-content path.
                     _flat_parts: list[str] = []
                     for _cpart in content:
                         if (
@@ -3540,12 +3421,8 @@ class ExternalProviderClient:
                 parts = [{"functionResponse": function_response_part}]
                 gemini_role = "user"
             if parts:
-                # Gemini expects parallel functionResponses (multiple OpenAI
-                # role="tool" messages in a row) to ride on a single user
-                # content with multiple functionResponse parts -- the docs show
-                # parallel responses grouped in the next turn. Merge consecutive
-                # functionResponse-only user blocks so realistic parallel tool
-                # loops round-trip correctly.
+                # Merge consecutive functionResponse-only user blocks: Gemini
+                # wants parallel tool responses grouped into one user turn.
                 if (
                     role == "tool"
                     and contents
@@ -3581,21 +3458,14 @@ class ExternalProviderClient:
         if max_tokens is not None:
             gen_config["maxOutputTokens"] = max_tokens
 
-        # Nano Banana image generation. Gemini only accepts
-        # `responseModalities: ["TEXT","IMAGE"]` on the image-capable model
-        # family (id contains `-image` or `nano-banana`). Text-only models such
-        # as `gemini-2.5-flash` 400 on the same body, so only force image mode
-        # when the selected model supports it -- a stale
-        # `enabled_tools=["image_generation"]` on a text model is silently
-        # treated as a regular turn.
+        # Nano Banana image generation: only image-capable models (id contains
+        # `-image`/`nano-banana`) accept responseModalities=["TEXT","IMAGE"];
+        # text models 400 on it, so a stale image_generation pill is ignored.
         # https://ai.google.dev/gemini-api/docs/image-generation
         model_lc = model.lower()
         is_image_picker_model = "-image" in model_lc or "nano-banana" in model_lc
-        # tool_choice="none" / forced-function tool_choice must also suppress
-        # the implicit image-generation hosted tool. Otherwise an explicit
-        # OpenAI-style opt-out (or user-function pin) still flips
-        # `responseModalities=["TEXT","IMAGE"]` on image-tier models and bills
-        # for image output.
+        # tool_choice="none"/forced-function also suppresses implicit image
+        # generation, else an explicit opt-out still bills for image output.
         _tool_choice_disabled = (
             isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
         )
@@ -3606,14 +3476,9 @@ class ExternalProviderClient:
             and bool(tool_choice["function"].get("name"))
         )
         _hosted_builtins_allowed = not _tool_choice_disabled and not _tool_choice_forced_function
-        # Image-tier model IDs reject text-only tools (code_execution, user
-        # functions) and thinkingConfig regardless of the Images pill -- those
-        # are model-level constraints documented by Google. The pill only
-        # controls whether we ask Gemini to emit image output via
-        # `responseModalities: ["TEXT","IMAGE"]`. Decoupling the two avoids the
-        # case where Images off + Code/Search on forwards
-        # `tools: [{codeExecution: {}}]` plus `thinkingConfig` to an image model
-        # and 400s.
+        # Image-tier models reject text-only tools and thinkingConfig regardless
+        # of the pill (model-level constraint); the pill only controls image
+        # output. Decouple the two so Images-off + Code/Search-on doesn't 400.
         image_tool_requested = bool(
             _hosted_builtins_allowed and enabled_tools and "image_generation" in enabled_tools
         )
@@ -3748,13 +3613,12 @@ class ExternalProviderClient:
             and code_execution_allowed
         ):
             tools_array.append({"codeExecution": {}})
-        # OpenAI-style function declarations -> Gemini functionDeclarations.
-        # https://ai.google.dev/gemini-api/docs/function-calling#step_1
-        # Gemini's Schema accepts only the OpenAPI 3.0 subset documented at
-        # https://ai.google.dev/api/caching#Schema; OpenAI's strict tool
-        # definitions routinely include `additionalProperties`, `$schema`,
-        # `$defs`, `strict`, `examples`, and similar keys which 400 the request
-        # as INVALID_ARGUMENT. Strip them recursively before forwarding.
+        # OpenAI function declarations -> Gemini functionDeclarations
+        # (https://ai.google.dev/gemini-api/docs/function-calling#step_1). Gemini's
+        # Schema accepts only the OpenAPI 3.0 subset; OpenAI strict tools include
+        # keys (additionalProperties, $schema, $defs, ...) that 400 as
+        # INVALID_ARGUMENT, so strip recursively. Ref:
+        # https://ai.google.dev/api/caching#Schema
         _GEMINI_ALLOWED_SCHEMA_KEYS = frozenset(
             {
                 "type",
@@ -3804,27 +3668,16 @@ class ExternalProviderClient:
             root: Optional[dict[str, Any]] = None,
             _seen_refs: Optional[frozenset[str]] = None,
         ) -> Any:
-            # Recursively filter to Gemini's OpenAPI 3.0 subset. At a
-            # Schema-keyword dict layer we drop keys not in the allowlist; under
-            # `properties` the keys are user-defined field names and the values
-            # are Schemas; under `items` / `anyOf` the values are also Schemas.
-            # OpenAI strict tools commonly use JSON Schema's
-            # `"type": ["string", "null"]` form for nullable fields; Gemini's
-            # OpenAPI Schema uses `"type": "string"` plus `"nullable": true`.
-            # Translate that here.
+            # Recursively filter to Gemini's OpenAPI 3.0 subset (drop non-allowlist
+            # keys) and translate JSON Schema `type:[X,"null"]` into
+            # `type:X` + `nullable:true`.
             if root is None and isinstance(node, dict):
                 root = node
             if _seen_refs is None:
                 _seen_refs = frozenset()
             if isinstance(node, dict):
-                # Pydantic / OpenAI strict tools commonly hoist nested object
-                # schemas into `$defs` and reference them via
-                # `{"$ref": "#/$defs/Address"}`. Gemini's OpenAPI subset has no
-                # $ref and drops anything not in the allowlist, so the
-                # referenced shape would vanish if we didn't inline it here.
-                # Recurse into the resolved target with local siblings
-                # overriding the reference (normal JSON Schema composition),
-                # guarding against ref cycles.
+                # Inline `$ref` targets (Gemini's subset has no $ref), with local
+                # siblings overriding and a cycle guard.
                 _ref = node.get("$ref")
                 if isinstance(_ref, str):
                     if _ref in _seen_refs:
@@ -4042,11 +3895,8 @@ class ExternalProviderClient:
         # Completions contract; an OAI client that sees a tool_calls delta
         # followed by finish_reason="stop" never executes the tool).
         emitted_any_function_call = False
-        # web_search_active drives the tool_start / tool_end envelope. Keyed on
-        # whether `googleSearch` was actually forwarded above, not raw caller
-        # intent -- image-mode requests filter the tool out, and a phantom
-        # "search complete" card on a turn where Gemini was never told to search
-        # confuses the UI.
+        # Keyed on whether `googleSearch` was actually forwarded (not caller
+        # intent) so image-mode turns don't show a phantom "search complete".
         web_search_active = any("googleSearch" in t for t in tools_array)
         web_search_tool_id = "gemini_web_search"
         web_search_tool_started = False
@@ -4128,12 +3978,9 @@ class ExternalProviderClient:
                         if isinstance(usage_meta, dict):
                             last_usage = usage_meta
 
-                        # Prompt-level safety block: Gemini ships zero candidates
-                        # plus a `promptFeedback.blockReason` (e.g. SAFETY). The
-                        # downstream OAI client would otherwise see an empty
-                        # successful assistant response. Surface as a
-                        # content_filter error event so the UI can render the
-                        # block reason.
+                        # Prompt-level safety block (zero candidates +
+                        # promptFeedback.blockReason): surface as an error so the
+                        # client doesn't see an empty successful response.
                         prompt_feedback = event.get("promptFeedback")
                         if isinstance(prompt_feedback, dict) and prompt_feedback.get("blockReason"):
                             block_reason = str(prompt_feedback.get("blockReason"))
@@ -4241,13 +4088,9 @@ class ExternalProviderClient:
                                         if fc_id in emitted_function_call_ids:
                                             continue
                                         emitted_function_call_ids.add(fc_id)
-                                        # Each distinct functionCall in an
-                                        # assistant turn needs its own
-                                        # tool_calls[*].index. Consumers that
-                                        # reassemble tool_calls by index collapse
-                                        # all calls onto one slot if this is
-                                        # hardcoded to 0, breaking
-                                        # parallel/multi-tool turns.
+                                        # Each functionCall needs its own
+                                        # tool_calls[*].index, else index-based
+                                        # consumers collapse parallel calls.
                                         tc_index = len(emitted_function_call_ids) - 1
                                         tool_call_delta: dict[str, Any] = {
                                             "index": tc_index,
@@ -4258,14 +4101,9 @@ class ExternalProviderClient:
                                                 "arguments": _json.dumps(fc_args),
                                             },
                                         }
-                                        # Gemini 3 function-calling: the
-                                        # part-level `thoughtSignature` must be
-                                        # echoed on the next turn or the model
-                                        # rejects the tool-result envelope. Stow
-                                        # it on `extra_content.google` so the
-                                        # frontend can persist it and our
-                                        # outbound translator (below) can replay
-                                        # it.
+                                        # Gemini 3 requires the part-level
+                                        # thoughtSignature echoed next turn; stow
+                                        # it on extra_content.google for replay.
                                         thought_sig = part.get("thoughtSignature") or part.get(
                                             "thought_signature"
                                         )
@@ -4527,11 +4365,8 @@ class ExternalProviderClient:
                                 if mapped is not None:
                                     final_finish_reason = mapped
 
-                    # End-of-stream emission order: web_search tool_end (with
-                    # citations) -> finish_reason chunk -> usage chunk -> [DONE].
-                    # Matches the Anthropic / OpenAI helpers' contract so the
-                    # frontend handler needs no provider-specific ordering
-                    # knowledge.
+                    # End-of-stream order: web_search tool_end -> finish_reason ->
+                    # usage -> [DONE], matching the Anthropic/OpenAI helpers.
                     if web_search_active and web_search_tool_started and not web_search_tool_ended:
                         blocks: list[str] = []
                         for cit in web_search_citations:
@@ -4551,10 +4386,8 @@ class ExternalProviderClient:
                         web_search_tool_ended = True
 
                     if final_finish_reason:
-                        # OpenAI clients trigger tool execution when
-                        # finish_reason="tool_calls". Gemini emits "STOP" even
-                        # for a pure functionCall request, so override after the
-                        # fact to match the OAI contract.
+                        # Gemini emits "STOP" even for a pure functionCall turn;
+                        # override to "tool_calls" so OAI clients run the tool.
                         if emitted_any_function_call and final_finish_reason == "stop":
                             final_finish_reason = "tool_calls"
                         finish_chunk = {
@@ -4598,9 +4431,7 @@ class ExternalProviderClient:
 
                     yield "data: [DONE]"
                 finally:
-                    # Close response first so lines_gen.aclose() becomes a no-op
-                    # (avoids the httpcore 1.0 GeneratorExit path and the
-                    # aclose-never-awaited RuntimeWarning).
+                    # Close response first so lines_gen.aclose() is a no-op.
                     await response.aclose()
                     await lines_gen.aclose()
 
@@ -4712,12 +4543,9 @@ class ExternalProviderClient:
                             instructions_parts.append(part["text"])
                 continue
 
-            # OpenAI Responses uses item-shape history for function calling:
-            # assistant turns that invoked user tools must serialize each call
-            # as a `function_call` input item, and each role="tool" follow-up as
-            # a `function_call_output` item keyed by the matching `call_id`.
-            # Without this the second turn after a function call sends Chat
-            # Completions shape and Responses 400s the request.
+            # Responses uses item-shape history: each assistant call is a
+            # `function_call` item and each role="tool" follow-up a
+            # `function_call_output` keyed by call_id (Chat Completions shape 400s).
             if role == "tool":
                 _call_id = msg.get("tool_call_id") or ""
                 # If the matching assistant `function_call` was a server-side
@@ -4743,21 +4571,12 @@ class ExternalProviderClient:
                     )
                 continue
 
-            # Assistant turns that returned tool_calls translate each call as a
-            # `function_call` item (name + JSON arguments + call_id). Skip
-            # builtin server-side cards (canonical builtin name +
-            # `args._server_tool` marker) which never round-trip as user
-            # functions. Both checks are required so a user function literally
-            # named `_server_tool` in its argument schema isn't dropped.
+            # Translate assistant tool_calls into `function_call` items, skipping
+            # server-side builtin cards (builtin name + `_server_tool` marker).
             _tool_calls = msg.get("tool_calls") if isinstance(msg, dict) else None
             if role == "assistant" and isinstance(_tool_calls, list):
-                # Preserve the prior `response.output` ordering: the model's text
-                # precedes its function_call items, and the matching role=tool
-                # follow-up arrives AFTER the call. Without this guard, history
-                # replay puts function_call -> assistant text ->
-                # function_call_output, which can place tool output after an
-                # unrelated assistant message and confuse multi-turn function
-                # calling.
+                # Emit assistant text before its function_call items to preserve
+                # the original response.output ordering.
                 if isinstance(content, str) and content:
                     input_items.append({"role": "assistant", "content": content})
                 elif isinstance(content, list):
@@ -4872,23 +4691,13 @@ class ExternalProviderClient:
                                 {"type": "image_generation_call", "id": call_id}
                             )
                     elif part_type == "input_document":
-                        # OpenAI Responses accepts PDFs / docs as
-                        # `{type:"input_file", file_data:"data:application/pdf;base64,..."}`
-                        # or `{type:"input_file", file_url:"https://..."}`,
-                        # with optional `filename`. See
+                        # Map Studio's `input_document` onto Responses' `input_file`.
                         # https://developers.openai.com/api/docs/guides/images-vision
-                        # Map Studio's normalised `input_document` onto
-                        # Responses' `input_file`.
                         file_url = part.get("file_url")
                         file_data = part.get("file_data")
                         filename = part.get("filename")
-                        # Mirror the Anthropic-side guard: any "data:" URI
-                        # without an actual base64 payload (`data:application/pdf;base64,`
-                        # or whitespace-only) would otherwise be forwarded to
-                        # OpenAI as `file_data=""`, which 400s the turn. Treat
-                        # such payloads as missing AND fall back to file_url if
-                        # present, so a recoverable remote URL isn't discarded in
-                        # favour of a malformed inline payload.
+                        # Treat a "data:" URI with no base64 payload as missing
+                        # (else file_data="" 400s) and fall back to file_url.
                         file_data_valid = bool(
                             isinstance(file_data, str)
                             and file_data
@@ -4960,15 +4769,10 @@ class ExternalProviderClient:
                     break
             input_items[insert_at:insert_at] = openai_replay_items
 
-        # NOTE: gpt-5.x / o3 / gpt-4.5 are reasoning-class models. They reject
-        # temperature and top_p with `Unsupported parameter` 400s on
-        # /v1/responses (and /v1/chat/completions for the same families). The
-        # PROVIDER_REGISTRY['openai'] model_id_allowlist already scopes the
-        # picker to those families, so we never send sampling knobs here.
-        # ``reasoning.effort`` defaults to "medium" server-side if omitted —
-        # surface it in a future commit if a knob is wanted.
-        del temperature, top_p  # explicit drop — params are accepted for
-        # API symmetry with the other stream methods but not forwarded.
+        # gpt-5.x / o3 / gpt-4.5 reject temperature/top_p (400 "Unsupported
+        # parameter"); the openai allowlist scopes the picker to these families,
+        # so never forward sampling knobs.
+        del temperature, top_p  # accepted for API symmetry, not forwarded.
 
         body: dict[str, Any] = {
             "model": model,
@@ -4978,11 +4782,8 @@ class ExternalProviderClient:
         if previous_response_id:
             body["previous_response_id"] = previous_response_id
         # `summary: "auto"` is what makes /v1/responses emit reasoning summary
-        # events — without it OpenAI returns no thinking text on most reasoning
-        # models, the SSE handler has no <think>…</think> to wrap, and the chat
-        # reasoning panel stays blank. Always pair an explicit effort with
-        # summary except for the "off" case (effort: "none"), where summaries
-        # are pointless.
+        # events; without it the reasoning panel stays blank. Pair it with any
+        # explicit effort except "none".
         summary_unsupported = bool(
             _OPENAI_REASONING_SUMMARY_UNSUPPORTED.match(model.strip().lower())
         )
@@ -5162,10 +4963,8 @@ class ExternalProviderClient:
             return attempt_body
 
         def _is_openai_container_expired_error(error_text: str) -> bool:
-            """Match the substring patterns OpenAI uses for expired / missing
-            code-exec containers. No official error code exists in the public
-            docs, so substring-match a small set.
-            """
+            """Substring-match OpenAI's expired/missing code-exec container errors
+            (no official error code exists)."""
             lowered = error_text.lower()
             if "container" not in lowered:
                 return False
@@ -5331,14 +5130,9 @@ class ExternalProviderClient:
                         return f"data: {_json.dumps(chunk)}"
 
                     def _format_shell_output(output: Any) -> str:
-                        """Render an OpenAI `shell_call_output.output` list as the
-                        preformatted text payload the frontend's
-                        CodeExecutionToolUI displays inside a <pre>. Each entry
-                        has stdout/stderr/outcome — concatenate them with a
-                        separator block per entry and append `return_code` /
-                        `(timeout)` annotations only when they convey info beyond
-                        "succeeded".
-                        """
+                        """Render `shell_call_output.output` (stdout/stderr/outcome
+                        per entry) as the preformatted text CodeExecutionToolUI
+                        shows; append return_code/(timeout) only when informative."""
                         if not isinstance(output, list):
                             return ""
                         parts: list[str] = []
@@ -5366,14 +5160,10 @@ class ExternalProviderClient:
                         return "\n--- next command ---\n".join(parts) if parts else "(no output)"
 
                     def _record_url_citation(payload: dict[str, Any]) -> None:
-                        """Append a url_citation onto the shared all_url_citations
-                        list. Dedup by URL — the same URL can be cited many times
-                        under different ``source_id`` aliases (one per
-                        span/locator), so collect every alias onto the matching
-                        entry's ``source_ids`` list. The delta-text rewriter
-                        resolves any alias back to this entry's URL. The id may
-                        live under ``source_id``, ``id``, or ``locator`` across
-                        Responses API revisions."""
+                        """Append a url_citation, deduped by URL: collect every
+                        source_id alias onto the entry's ``source_ids`` so the
+                        rewriter can resolve any alias. The id lives under
+                        source_id/id/locator across API revisions."""
                         if payload.get("type") != "url_citation":
                             return
                         url = payload.get("url", "")
@@ -5665,15 +5455,10 @@ class ExternalProviderClient:
                                         yield _chunk_with_text(summary_text)
                                         reasoning_emitted = True
                                 elif item.get("type") == "web_search_call":
-                                    # done is the canonical place to read the
-                                    # query, so emit both tool_start and tool_end
-                                    # here. Frontend then renders a card per call
-                                    # with the "Searching: <query>" label.
-                                    # Citations are aggregated separately and the
-                                    # *last* call's result is overwritten at
-                                    # response.completed with the citation list
-                                    # (so source-pill extraction at message tail
-                                    # surfaces them once).
+                                    # done carries the query; emit tool_start +
+                                    # tool_end here. Citations are aggregated and
+                                    # the last call's result is overwritten at
+                                    # response.completed.
                                     item_id = item.get("id", "") or (f"ws_{len(web_search_calls)}")
                                     action = item.get("action")
                                     query = (
@@ -5699,13 +5484,10 @@ class ExternalProviderClient:
                                         }
                                     )
                                 elif item.get("type") == "shell_call":
-                                    # OpenAI ships the commands array on the
-                                    # action field. Join them onto one command
-                                    # string for the tool card — the renderer is
-                                    # shared with Anthropic bash, which carries a
-                                    # single `command`. Multiple commands in one
-                                    # shell_call are joined with newlines so they
-                                    # still render as one card.
+                                    # Join the action.commands array into one
+                                    # newline-separated string (the card renderer,
+                                    # shared with Anthropic bash, wants a single
+                                    # `command`).
                                     item_id = item.get("id", "") or (f"sc_{len(shell_calls)}")
                                     action = item.get("action") or {}
                                     commands = (
@@ -5874,12 +5656,9 @@ class ExternalProviderClient:
                                 completed_usage = (event.get("response") or {}).get("usage")
                                 if isinstance(completed_usage, dict):
                                     last_usage = completed_usage
-                                # Flush any unterminated citation tail held over
-                                # from the last delta. By now every annotation is
-                                # recorded so a late-arriving source_id may
-                                # resolve; if not, the helper strips the
-                                # private-use bytes so no garbled glyph reaches
-                                # the user.
+                                # Flush any unterminated citation tail; by now all
+                                # annotations are recorded, else private-use bytes
+                                # are stripped.
                                 if pending_marker_tail:
                                     flushed = _flush_pending_marker_tail(pending_marker_tail)
                                     pending_marker_tail = ""
@@ -5888,8 +5667,7 @@ class ExternalProviderClient:
                                             yield _chunk_with_text("</think>")
                                             reasoning_open = False
                                         yield _chunk_with_text(flushed)
-                                # Force-drain any segment still awaiting an
-                                # annotation; lingering codepoints drop.
+                                # Force-drain segments still awaiting an annotation.
                                 tail_flushed = _drain_pending_segments(
                                     force = True,
                                 )
@@ -5901,12 +5679,9 @@ class ExternalProviderClient:
                                 if reasoning_open:
                                     yield _chunk_with_text("</think>")
                                     reasoning_open = False
-                                # Probe response.container_id (top-level) and
-                                # response.container.id for the shell-tool
-                                # container id. OpenAI's docs don't pin the exact
-                                # field, so scan both. Emit `container_ready` only
-                                # when the value differs from the inbound one — no
-                                # churn on reuse.
+                                # Scan response.container_id and response.container.id
+                                # (docs don't pin the field); emit container_ready
+                                # only when it differs from the inbound id.
                                 response_obj = event.get("response") or {}
                                 if isinstance(response_obj, dict):
                                     probe_id = response_obj.get("container_id")
@@ -5932,10 +5707,8 @@ class ExternalProviderClient:
                                         }
                                     )
                                     container_id_emitted = True
-                                # Overwrite the last web_search call with the
-                                # citation list; the source-pill extractor
-                                # flatMaps across cards. Earlier cards keep their
-                                # per-call "Searching:" text.
+                                # Overwrite the last web_search card with the
+                                # citation list (the extractor flatMaps cards).
                                 if web_search_calls and all_url_citations:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks: list[str] = []
@@ -6018,12 +5791,7 @@ class ExternalProviderClient:
                                 if reasoning_open:
                                     yield _chunk_with_text("</think>")
                                     reasoning_open = False
-                                # Same backfill as response.completed — apply
-                                # whatever citations we gathered before
-                                # truncation onto the last call. Earlier tool
-                                # cards already have their query + empty
-                                # placeholder result from the output_item.done
-                                # emissions above.
+                                # Same citation backfill as response.completed.
                                 if web_search_calls and all_url_citations:
                                     last_id = list(web_search_calls.keys())[-1]
                                     blocks = []
@@ -6096,22 +5864,16 @@ class ExternalProviderClient:
                         await lines_gen.aclose()
                         raise
                     finally:
-                        # Summarise what the model did this turn so support
-                        # reports of "I clicked Search and got nothing" can be
-                        # triaged at a glance: was the tool requested, did OpenAI
-                        # invoke it, and how many sources came back?
+                        # Per-turn tool summary for triage.
                         web_search_requested = bool(enabled_tools and "web_search" in enabled_tools)
                         web_search_invocations = len(web_search_calls)
                         total_citations = len(all_url_citations)
                         queries = [
                             sc["query"] for sc in web_search_calls.values() if sc.get("query")
                         ]
-                        # cached_input_tokens > 0 on turn N proves
-                        # prompt_cache_retention="24h" is letting the previous
-                        # turn's prefix hit the cache instead of being
-                        # recomputed. On /v1/responses the field is nested at
+                        # On /v1/responses cached tokens live at
                         # usage.input_tokens_details.cached_tokens (not
-                        # prompt_tokens_details, the /v1/chat/completions shape).
+                        # prompt_tokens_details, the chat/completions shape).
                         cached_input_tokens = None
                         if isinstance(last_usage, dict):
                             details = last_usage.get("input_tokens_details")
@@ -6212,15 +5974,11 @@ class ExternalProviderClient:
         return response.json()
 
     async def list_models(self) -> list[dict[str, Any]]:
-        """
-        Call GET /models on the provider to discover available models.
+        """GET /models to discover available models.
 
-        Returns model dicts with at least 'id' and optionally 'created',
-        'owned_by', etc.
-
-        All supported providers expose a /models endpoint:
-        - OpenAI-compatible: standard {"data": [...]} response
-        - Anthropic: https://api.anthropic.com/v1/models — same {"data": [...]} shape
+        Returns dicts with at least 'id'. All providers expose /models with the
+        OpenAI {"data": [...]} shape (Anthropic included:
+        https://api.anthropic.com/v1/models).
         """
         try:
             response = await _http_client.get(
@@ -6230,7 +5988,6 @@ class ExternalProviderClient:
             )
             response.raise_for_status()
             data = response.json()
-            # OpenAI format: {"data": [{"id": "...", ...}, ...]}
             # Some local servers (Ollama with no models) return data: null.
             models: list[dict[str, Any]] = []
             if isinstance(data, dict):
@@ -6239,10 +5996,8 @@ class ExternalProviderClient:
                     models = [model for model in raw_models if isinstance(model, dict)]
             if not models and self.provider_type == "ollama":
                 models = await self._list_ollama_native_models()
-            # Gemini's native /v1beta/models returns
-            # {"models": [{"name": "models/gemini-2.5-flash", ...}]}
-            # -- repackage into the OpenAI-compatible shape the rest of Studio
-            # expects so dynamic model discovery works.
+            # Gemini's native /v1beta/models uses a different shape; repackage
+            # into the OpenAI-compatible one Studio expects.
             if not models and self.provider_type == "gemini":
                 models = self._parse_gemini_models(data)
             return models
@@ -6252,17 +6007,9 @@ class ExternalProviderClient:
 
     @staticmethod
     def _parse_gemini_models(payload: Any) -> list[dict[str, Any]]:
-        """Translate Gemini's native /v1beta/models payload to OpenAI shape.
-
-        Native response:
-          {"models": [{"name": "models/gemini-2.5-flash",
-                       "baseModelId": "gemini-2.5-flash",
-                       "displayName": "Gemini 2.5 Flash",
-                       "supportedGenerationMethods": [...]}]}
-
-        We only keep entries that advertise ``generateContent`` /
-        ``streamGenerateContent`` so the picker doesn't surface embedding-only
-        models the chat path can't drive.
+        """Translate Gemini's native /v1beta/models payload to OpenAI shape,
+        keeping only entries advertising generateContent / streamGenerateContent
+        so embedding-only models don't reach the chat picker.
         """
         if not isinstance(payload, dict):
             return []
@@ -6349,29 +6096,16 @@ class ExternalProviderClient:
             raise
 
     def _container_headers(self) -> dict[str, str]:
-        """Auth headers plus the OpenAI-Beta opt-in for /v1/containers.
-
-        OpenAI's containers API requires ``OpenAI-Beta: containers=v1``. Without
-        it, DELETE silently no-ops: the API returns 200 with a
-        ``{"deleted": true}`` body but doesn't actually remove the container
-        (verified 2026-05-15). The header is required for list / create / delete
-        to behave consistently.
-        """
+        """Auth headers plus the required ``OpenAI-Beta: containers=v1`` opt-in;
+        without it DELETE silently no-ops (returns deleted:true but keeps the
+        container, verified 2026-05-15)."""
         headers = self._auth_headers()
         headers["OpenAI-Beta"] = "containers=v1"
         return headers
 
     async def list_openai_containers(self) -> list[dict[str, Any]]:
-        """
-        GET /v1/containers on the user's OpenAI account.
-
-        Returns the raw container records (id, name, created_at, last_active_at,
-        expires_after, status). The route layer reshapes these into the UI
-        summary shape.
-
-        Only valid against api.openai.com — non-cloud OpenAI-compat servers
-        don't implement /v1/containers and would 404 here. Caller is responsible
-        for the is_openai_cloud guard.
+        """GET /v1/containers; returns raw container records (the route reshapes
+        them). Only valid against api.openai.com (caller guards is_openai_cloud).
         """
         response = await _http_client.get(
             f"{self.base_url}/containers",
@@ -6412,17 +6146,11 @@ class ExternalProviderClient:
         return response.json()
 
     async def delete_openai_container(self, container_id: str) -> None:
-        """DELETE /v1/containers/{id}. 404s are surfaced as HTTPError.
+        """DELETE /v1/containers/{id}. 404s surface as HTTPError.
 
-        Uses a fresh httpx client (not the shared ``_http_client``) so
-        connection-pool state from earlier chat requests can't interfere —
-        observed that DELETEs over the shared pool returned ``deleted: true``
-        while the container persisted in later /containers list calls, even
-        though the same DELETE from a fresh client genuinely removed it.
-
-        Verifies the response body reports ``deleted: true``. OpenAI returns a
-        2xx ``deleted: true`` body even when the request is silently rejected
-        (e.g. missing OpenAI-Beta header), so a status-only check isn't enough.
+        Uses a fresh httpx client (shared-pool DELETEs returned deleted:true but
+        left the container alive). Also verifies the body reports deleted:true,
+        since OpenAI 2xx-returns that even when silently rejecting the request.
         """
         url = f"{self.base_url}/containers/{container_id}"
         headers = self._container_headers()
@@ -6513,35 +6241,17 @@ def _build_usage_chunk(
     """Build an OpenAI ``include_usage``-style SSE chunk carrying upstream
     prompt-cache accounting back to the client.
 
-    Studio captured ``cache_creation_input_tokens`` /
-    ``cache_read_input_tokens`` (Anthropic) and
-    ``input_tokens_details.cached_tokens`` (OpenAI Responses) on ``last_usage``
-    but only wrote them to the structlog stream. Browser / SDK clients couldn't
-    see how many tokens hit the cache, so the "you saved $X" UX was impossible
-    without scraping the server log.
+    Emits the standard chunk shape (``choices: []`` + ``usage`` block) so
+    ``stream_options={"include_usage": true}`` clients keep working, plus the
+    Anthropic-native counts as extra keys:
+        usage.prompt_tokens_details.cached_tokens  (both providers)
+        usage.cache_creation_input_tokens          (Anthropic-only)
+        usage.cache_read_input_tokens              (Anthropic-only)
 
-    This emits the standard OpenAI chunk shape -- ``choices: []`` with a
-    populated ``usage`` block -- so any client consuming
-    ``stream_options={"include_usage": true}`` keeps working, with the
-    Anthropic-native counts surfaced as extra keys on the same ``usage`` dict:
+    Anthropic's ``input_tokens`` excludes the cache buckets, so prompt_tokens
+    sums all three (OpenAI Responses already folds cached tokens in).
 
-        usage.prompt_tokens_details.cached_tokens
-            normalised cache-read count, present for both providers.
-        usage.cache_creation_input_tokens
-            Anthropic-only; tokens billed at the cache-write premium.
-        usage.cache_read_input_tokens
-            Anthropic-only; same value as cached_tokens, kept for callers
-            that key off the native Anthropic name.
-
-    Anthropic's ``input_tokens`` excludes the cache buckets -- real prompt size
-    is ``input_tokens + cache_creation_input_tokens + cache_read_input_tokens``.
-    Emitting ``input_tokens`` alone as ``prompt_tokens`` undercounts cache-heavy
-    turns and breaks downstream context / cost displays, so we sum all three
-    input buckets. OpenAI Responses already folds cached tokens into
-    ``input_tokens`` so no extra arithmetic is needed there.
-
-    Returns ``None`` when there are no usage numbers to report (e.g. an upstream
-    error before ``message_start`` / ``response.completed``).
+    Returns ``None`` when there are no usage numbers to report.
     """
     if not isinstance(last_usage, dict):
         return None
diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index 0cef6c41ff..c44db7485d 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -36,23 +36,13 @@ logger = get_logger(__name__)
 class HarmonyTextStreamer:
     """Streaming text decoder for the gpt-oss harmony channel protocol.
 
-    gpt-oss emits multi-channel output via special tokens like
-    ``<|channel|>analysis<|message|>...`` / ``<|channel|>final<|message|>...``.
-    A plain ``TextIteratorStreamer(skip_special_tokens=True)`` drops the tokens
-    but leaves channel names glued to content, producing garbled output like
-    ``analysisWe need to respond...assistantfinalHello!``.
-
-    This streamer decodes with ``skip_special_tokens=False`` so the harmony
-    markup is visible, then uses stateful incremental parsing:
-
-    - ``<think>`` once when ``analysis`` channel is first seen
-    - analysis content streamed incrementally
-    - ``</think>`` once when ``final`` channel is first seen
-    - final content streamed incrementally
-
-    This avoids the delta-on-transformed bug where wrapping tags shift
-    position as content grows. Implements the same ``put`` / ``end`` / iterator
-    interface as ``TextIteratorStreamer`` for drop-in use in ``generate_stream``.
+    gpt-oss emits multi-channel output via ``<|channel|>analysis<|message|>...``
+    / ``<|channel|>final<|message|>...``. Plain skip_special_tokens streaming
+    glues channel names to content. This decodes with skip_special_tokens=False
+    and parses statefully: emit ``<think>`` on first analysis, stream analysis,
+    emit ``</think>`` on first final, stream final. Tracking per-channel lengths
+    avoids the delta-on-transformed bug where wrapping tags shift position.
+    Same put/end/iterator interface as TextIteratorStreamer.
     """
 
     import re as _re
@@ -87,9 +77,7 @@ class HarmonyTextStreamer:
         self._analysis_emitted: int = 0  # chars of analysis content emitted
         self._final_emitted: int = 0  # chars of final content emitted
 
-    # ------------------------------------------------------------------
     # put / end — called from the generation thread
-    # ------------------------------------------------------------------
 
     def put(self, value):
         """Receive new token IDs from model.generate()."""
@@ -104,7 +92,7 @@ class HarmonyTextStreamer:
             ids = [value]
 
         if self._is_first_put and self.skip_prompt:
-            # First call is the full prompt; remember its length
+            # First call is the full prompt; remember its length.
             self._prompt_len = len(ids)
             self._token_ids = list(ids)
             self._is_first_put = False
@@ -112,20 +100,20 @@ class HarmonyTextStreamer:
 
         self._token_ids.extend(ids)
 
-        # Decode only the generated part (after the prompt)
+        # Decode only the generated part (after the prompt).
         gen_ids = self._token_ids[self._prompt_len :]
         raw = self.tokenizer.decode(gen_ids, skip_special_tokens = False)
         self._process_incremental(raw)
 
     def end(self):
         """Signal generation is complete."""
-        # Final decode to capture remaining content
+        # Final decode to capture remaining content.
         gen_ids = self._token_ids[self._prompt_len :]
         if gen_ids:
             raw = self.tokenizer.decode(gen_ids, skip_special_tokens = False)
             self._process_incremental(raw)
 
-        # Close any open think tags
+        # Close any open think tags.
         if self._emitted_think_open and not self._emitted_think_close:
             self._queue.put("</think>")
             self._emitted_think_close = True
@@ -133,9 +121,7 @@ class HarmonyTextStreamer:
         self._stop = True
         self._queue.put(None)  # sentinel
 
-    # ------------------------------------------------------------------
     # Iterator interface — consumed by the streaming loop
-    # ------------------------------------------------------------------
 
     def __iter__(self):
         return self
@@ -153,33 +139,19 @@ class HarmonyTextStreamer:
                 raise StopIteration
             return val
 
-    # ------------------------------------------------------------------
     # Stateful incremental harmony protocol parsing
-    # ------------------------------------------------------------------
 
     def _process_incremental(self, raw: str) -> None:
-        """Parse harmony channels and emit per-channel deltas.
-
-        Tracks per-channel content lengths (instead of diffing transformed
-        whole-text, which breaks when wrapping ``<think>`` tags shift position)
-        and emits:
-
-        - ``<think>`` once when analysis channel first appears
-        - analysis content deltas (computed on channel content directly)
-        - ``</think>`` once when final channel first appears
-        - final content deltas
-        """
-        # raw has <|channel|> but no complete channel+message pair yet:
-        # buffer silently, don't emit partial channel names as text.
+        """Parse harmony channels and emit per-channel deltas (tracked by length, not whole-text diff)."""
+        # If raw has <|channel|> but no complete channel+message pair yet, buffer.
         has_channel_token = "<|channel|>" in raw
         matches = list(self._HARMONY_RE.finditer(raw))
 
         if has_channel_token and not matches:
-            # Partial harmony markup still building — wait for more tokens
+            # Partial harmony markup still building — wait for more tokens.
             return
 
         if not has_channel_token and not matches:
-            # No harmony protocol (shouldn't happen for gpt-oss) — emit nothing
             return
 
         for m in matches:
@@ -221,11 +193,9 @@ class InferenceBackend:
         self.device = get_device().value
         self._audio_codec_manager = AudioCodecManager()
 
-        # _generation_lock serializes model.generate() calls. Must be a plain
-        # Lock (NOT RLock): in async FastAPI requests share one event-loop
-        # thread, so RLock reentrancy would let concurrent compare-mode
-        # requests race on the GPU. Acquired by the *background generation
-        # thread*, not the event-loop.
+        # _generation_lock serializes model.generate(). Plain Lock (NOT RLock):
+        # RLock reentrancy would let concurrent compare-mode requests race on
+        # the GPU. Acquired by the background generation thread, not the event-loop.
         import threading
 
         self._generation_lock = threading.Lock()
@@ -313,14 +283,13 @@ class InferenceBackend:
                     from unsloth import FastModel
 
                     if config.is_lora and config.base_model:
-                        # LoRA adapter from local path. base_model is e.g.
-                        # /home/.../Spark-TTS-0.5B/LLM; BiCodec weights live in
-                        # the parent dir (Spark-TTS-0.5B/).
+                        # LoRA adapter: base_model is .../Spark-TTS-0.5B/LLM;
+                        # BiCodec weights live in the parent dir.
                         base_path = config.base_model
                         if os.path.isdir(base_path):
                             abs_repo_path = os.path.abspath(os.path.dirname(base_path))
                         else:
-                            # base_model is an HF ID — download it
+                            # base_model is an HF ID — download it.
                             from huggingface_hub import snapshot_download
 
                             local_dir = base_path.split("/")[-1]
@@ -463,17 +432,14 @@ class InferenceBackend:
 
                 FastVisionModel.for_inference(model)
 
-                # FastVisionModel may return a raw tokenizer (e.g.
-                # GemmaTokenizerFast) instead of a proper Processor for some
-                # models (e.g. Gemma-3). If so, load the real processor from
-                # the base model.
+                # FastVisionModel may return a raw tokenizer instead of a
+                # Processor for some models (e.g. Gemma-3); load the real one.
                 from transformers import ProcessorMixin
 
                 if not (
                     isinstance(processor, ProcessorMixin) or hasattr(processor, "image_processor")
                 ):
-                    # LoRA adapters: use the base model. Local merged exports:
-                    # read export_metadata.json for the original base model.
+                    # LoRA adapters: use base model. Local merged exports: read base from export_metadata.json.
                     processor_source = config.base_model if config.is_lora else config.identifier
                     if not config.is_lora and config.is_local:
                         _meta_path = Path(config.path) / "export_metadata.json"
@@ -557,9 +523,8 @@ class InferenceBackend:
 
                 clear_gpu_cache()
 
-                # Drop stale compiled cache so the next model gets a fresh one.
-                # On spawn-based platforms, preserve trainer files so concurrent
-                # training dataset.map() workers can still import them.
+                # Drop stale compiled cache for the next model. On spawn platforms,
+                # preserve trainer files so concurrent dataset.map() workers can import them.
                 import sys as _sys
                 from utils.cache_cleanup import clear_unsloth_compiled_cache
 
@@ -593,9 +558,8 @@ class InferenceBackend:
                 self.models[base_model_name]["model"] = unwrapped_base_model
                 model = unwrapped_base_model
 
-            # Clear any lingering peft_config. model.unload() can leave a
-            # peft_config attribute; removing it gives PeftModel.from_pretrained()
-            # a clean base model without "multiple adapters" warnings.
+            # model.unload() can leave a peft_config; removing it avoids
+            # "multiple adapters" warnings on the next from_pretrained().
             if hasattr(model, "peft_config"):
                 del model.peft_config
 
@@ -701,8 +665,7 @@ class InferenceBackend:
             return False
 
     def set_active_adapter(self, base_model_name: str, adapter_name: str) -> bool:
-        """Set the active adapter for generation (replaces the flawed
-        'enable_adapter')."""
+        """Set the active adapter for generation."""
         model = self.models[base_model_name].get("model")
         try:
             logger.info(f"Setting active adapter to: '{adapter_name}'")
@@ -715,16 +678,11 @@ class InferenceBackend:
             return False
 
     def _apply_adapter_state(self, use_adapter: Optional[Union[bool, str]]) -> None:
-        """Apply adapter state before generation. Must hold _generation_lock.
+        """Apply adapter state before generation (must hold _generation_lock).
 
-        Uses PEFT's disable_adapter_layers() / enable_adapter_layers(), which
-        toggle a flag (proj.disable_adapters) on each LoRA layer; Unsloth's
-        fast_linear_forward checks it and skips LoRA when True. Non-destructive,
-        no unload/reload.
-
-        Args:
-            use_adapter: None = no change, False = disable (base model),
-                         True = enable current adapter, str = enable specific adapter.
+        Toggles PEFT enable/disable_adapter_layers (non-destructive, no reload).
+        use_adapter: None = no change, False = base model, True = current adapter,
+        str = named adapter.
         """
         if use_adapter is None:
             return
@@ -739,7 +697,7 @@ class InferenceBackend:
             return
 
         if use_adapter is False:
-            # Disable LoRA layers → base model output
+            # Disable LoRA layers -> base model output.
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
                 logger.info(
                     f"Compare mode: disabling adapters on '{base}' for base model generation"
@@ -749,7 +707,7 @@ class InferenceBackend:
                 logger.info(f"Compare mode: model '{base}' is not a PeftModel, already base")
 
         elif use_adapter is True:
-            # Re-enable LoRA layers → adapter output
+            # Re-enable LoRA layers -> adapter output.
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
                 logger.info(f"Compare mode: enabling adapters on '{base}' for LoRA generation")
                 model.base_model.enable_adapter_layers()
@@ -757,7 +715,7 @@ class InferenceBackend:
                 logger.warning("use_adapter=true but model is not a PeftModel")
 
         elif isinstance(use_adapter, str):
-            # Enable adapters and set the named one active
+            # Enable adapters and set the named one active.
             if isinstance(model, (PeftModel, PeftModelForCausalLM)):
                 logger.info(f"Compare mode: enabling adapter '{use_adapter}' on '{base}'")
                 model.base_model.enable_adapter_layers()
@@ -773,14 +731,9 @@ class InferenceBackend:
     ) -> Generator[str, None, None]:
         """Thread-safe generation with optional adapter toggling.
 
-        The adapter toggle + model.generate() are serialized by _generation_lock
-        in the background generation thread, NOT the event-loop thread. Prevents
-        the RLock-reentrant race when two async SSE handlers share one
-        event-loop thread.
-
-        Args:
-            use_adapter: Adapter control (None/False/True/str). See _apply_adapter_state.
-            **gen_kwargs: Forwarded to generate_chat_response.
+        Adapter toggle + model.generate() are serialized by _generation_lock in
+        the background thread, avoiding the RLock-reentrant race when two async
+        SSE handlers share one event-loop thread. use_adapter: see _apply_adapter_state.
         """
         yield from self._generate_chat_response_inner(
             cancel_event = cancel_event, _adapter_state = use_adapter, **gen_kwargs
@@ -870,14 +823,11 @@ class InferenceBackend:
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
     ) -> Generator[str, None, None]:
-        """Generate response for text or vision models.
-        The generation lock is acquired by the background generation thread.
+        """Generate response for text or vision models (lock held by background thread).
 
-        ``tools`` / ``enable_thinking`` / ``reasoning_effort`` /
-        ``preserve_thinking`` are forwarded into
-        ``tokenizer.apply_chat_template`` so templates that understand them
-        (Qwen3, Llama 3.1+, gpt-oss harmony, ...) advertise the tool schemas
-        and reasoning controls to the model.
+        ``tools`` / ``enable_thinking`` / ``reasoning_effort`` / ``preserve_thinking``
+        are forwarded into ``apply_chat_template`` so templates that understand them
+        (Qwen3, Llama 3.1+, gpt-oss harmony) advertise tool schemas / reasoning controls.
         """
         yield from self._generate_chat_response_inner(
             messages = messages,
@@ -927,15 +877,13 @@ class InferenceBackend:
         model_info = self.models[self.active_model_name]
         is_vision = model_info.get("is_vision", False)
         tokenizer = model_info.get("tokenizer") or model_info.get("processor")
-        # Unwrap processor → raw tokenizer for VLMs on the text path
+        # Unwrap processor -> raw tokenizer for VLMs on the text path.
         tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
         top_k = self._normalize_top_k(top_k)
 
         if is_vision and image:
-            # Vision generation (only with an actual image). Verify the stored
-            # processor can handle images — FastVisionModel may return a raw
-            # tokenizer (e.g. GemmaTokenizerFast) instead of a ProcessorMixin
-            # for some models (e.g. Gemma-3).
+            # Verify the stored processor can handle images; FastVisionModel may
+            # return a raw tokenizer instead of a ProcessorMixin (e.g. Gemma-3).
             from transformers import ProcessorMixin
 
             processor = model_info.get("processor")
@@ -963,10 +911,9 @@ class InferenceBackend:
                     f"falling back to text-only generation (image will be ignored)."
                 )
 
-        # Text path: training-pipeline approach. Messages are already in
-        # ChatML format from eval.py.
+        # Text path: messages are already in ChatML format from eval.py.
 
-        # Step 1: apply get_chat_template if model is in mapper
+        # Step 1: apply get_chat_template if model is in mapper.
         try:
             from utils.datasets import (
                 MODEL_TO_TEMPLATE_MAPPER,
@@ -980,7 +927,6 @@ class InferenceBackend:
                     f"Applying chat template '{template_name}' for {self.active_model_name}"
                 )
 
-                # Sets the correct template on the tokenizer
                 tokenizer = get_chat_template(
                     tokenizer,
                     chat_template = template_name,
@@ -992,7 +938,7 @@ class InferenceBackend:
         except Exception as e:
             logger.warning(f"Could not apply get_chat_template: {e}")
 
-        # Step 2: format with tokenizer.apply_chat_template()
+        # Step 2: format with tokenizer.apply_chat_template().
         if system_prompt:
             template_messages = [{"role": "system", "content": system_prompt}] + messages
         else:
diff --git a/studio/backend/core/inference/key_exchange.py b/studio/backend/core/inference/key_exchange.py
index ddc726751d..15ebf0e4c0 100644
--- a/studio/backend/core/inference/key_exchange.py
+++ b/studio/backend/core/inference/key_exchange.py
@@ -36,9 +36,7 @@ def init_key_pair() -> None:
     """Generate an RSA-2048 key pair. Called once at server startup."""
     global _private_key, _public_key_pem, _public_key_fingerprint
     if _private_key is not None:
-        # Re-entry is suspicious — a fresh keypair invalidates all in-flight
-        # ciphertext encrypted against the previous public key. Log loudly so a
-        # regression that calls init twice is visible.
+        # Re-entry invalidates in-flight ciphertext from the old public key; log loudly.
         logger.warning(
             "init_key_pair called again — replacing existing RSA keypair "
             "(previous fingerprint=%s). Any frontend that cached the old "
@@ -111,9 +109,8 @@ def decrypt_api_key(encrypted_b64: str) -> str:
             ),
         )
     except Exception as exc:
-        # Surface enough state to tell a key mismatch (wrong public key used on
-        # encrypt) from a padding/algo mismatch or corrupted bytes. Expected
-        # RSA-2048 ciphertext length is exactly 256 bytes.
+        # Log state to distinguish key mismatch from padding/algo mismatch or
+        # corrupted bytes. RSA-2048 ciphertext is exactly 256 bytes.
         logger.warning(
             "decrypt_api_key: RSA decrypt failed (ciphertext_len=%d, expected=256, "
             "fingerprint=%s, exc=%s): %s",
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index e2b2533d2e..4d4ae57afe 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -1,11 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-llama-server inference backend for GGUF models.
+"""llama-server inference backend for GGUF models.
 
-Manages a llama-server subprocess and proxies chat completions through
-its OpenAI-compatible /v1/chat/completions endpoint.
+Manages a llama-server subprocess and proxies chat completions through its
+OpenAI-compatible /v1/chat/completions endpoint.
 """
 
 import atexit
@@ -79,17 +78,13 @@ _INTENT_SIGNAL = re.compile(
 )
 _MAX_REPROMPTS = 3
 
-# Without max_tokens, llama-server defaults n_predict = n_ctx (up to
-# 262144 for Qwen3.5), producing many-minute zombie decodes when cancel
-# fails. t_max_predict_ms is an unconditional wall-clock backstop, but the
-# llama.cpp README notes it ONLY fires after a newline -- a model stuck in
-# a long non-newline sequence is unbounded by it. So we keep a token cap
-# as the front-line limiter.
-#
-# The cap is the model's effective context length when known, else a
-# generous floor. 4096 was too low: Qwen3 / gpt-oss reasoning traces
-# exceed it, and any OpenAI-API caller omitting max_tokens (langchain,
-# llama-index, raw curl) sees responses truncated mid-sentence.
+# Without max_tokens, llama-server defaults n_predict = n_ctx (up to 262144 for
+# Qwen3.5), causing many-minute zombie decodes when cancel fails.
+# t_max_predict_ms is a wall-clock backstop but per the llama.cpp README only
+# fires after a newline, so we keep a token cap as the front-line limiter.
+# The cap is the effective context length when known, else this floor. 4096 was
+# too low: Qwen3 / gpt-oss reasoning traces and max_tokens-omitting OpenAI-API
+# callers (langchain, llama-index, curl) got truncated mid-sentence.
 _DEFAULT_MAX_TOKENS_FLOOR = 32768
 _DEFAULT_T_MAX_PREDICT_MS = 600_000  # 10 min
 _REPROMPT_MAX_CHARS = 2000
@@ -123,8 +118,8 @@ _SWA_CACHE_LOCK = threading.Lock()
 
 
 def _probe_dns_dead(host: str = "huggingface.co", timeout: float = 2.0) -> bool:
-    """Quick DNS check on a daemon thread, so concurrent sockets in the
-    same process aren't affected by socket.setdefaulttimeout."""
+    """Quick DNS check on a daemon thread, so concurrent sockets aren't
+    affected by socket.setdefaulttimeout."""
     result: list[Optional[bool]] = [None]
 
     def _probe() -> None:
@@ -143,9 +138,9 @@ def _probe_dns_dead(host: str = "huggingface.co", timeout: float = 2.0) -> bool:
 
 @contextlib.contextmanager
 def _hf_offline_if_dns_dead():
-    """Set HF_HUB_OFFLINE for this block only when DNS to huggingface.co
-    fails. Restores the env on exit so a transient resolver hiccup can't
-    quarantine the whole process. No-op if the user already set it."""
+    """Set HF_HUB_OFFLINE for this block only when DNS to huggingface.co fails;
+    restores env on exit so a transient hiccup can't quarantine the process.
+    No-op if the user already set it."""
     if "HF_HUB_OFFLINE" in os.environ:
         yield False
         return
@@ -200,8 +195,7 @@ def _save_swa_cache(cache: dict) -> None:
 
 
 def _period_from_layer_types(layer_types: list) -> Optional[int]:
-    """Smallest period N where `(i+1) % N != 0` matches the SWA mask, or
-    None if no fixed period fits."""
+    """Smallest period N where `(i+1) % N != 0` matches the SWA mask, else None."""
     if not layer_types:
         return None
     is_swa = ["full" not in str(t).lower() for t in layer_types]
@@ -368,7 +362,6 @@ def _hf_repo_from_url(url: Optional[str]) -> Optional[str]:
 
 
 # Lazy import to avoid pulling transformers in at module level.
-# See PR description for the full explanation.
 def _extract_model_size_b(model_id: str):
     from utils.models import extract_model_size_b
     return extract_model_size_b(model_id)
@@ -589,8 +582,7 @@ def _backfill_usage_from_timings(usage, timings):
 
 
 class LlamaCppBackend:
-    """
-    Manages a llama-server subprocess for GGUF model inference.
+    """Manages a llama-server subprocess for GGUF model inference.
 
     Lifecycle:
         1. load_model() — start llama-server with the GGUF file
@@ -622,11 +614,10 @@ class LlamaCppBackend:
         self._cache_type_kv: Optional[str] = None
         self._reasoning_default: bool = True
         self._speculative_type: Optional[str] = None
-        # Canonical UI-facing mode the user requested:
-        # ``auto``/``mtp``/``ngram``/``mtp+ngram``/``off``/``ngram-simple``.
-        # Round-tripped through the status API so the dropdown reflects the
-        # picked mode, not the resolved internal flag set (auto on a 27B MTP
-        # GGUF resolves to draft-mtp but the dropdown still reads "Auto").
+        # Canonical UI-facing mode the user requested
+        # (auto/mtp/ngram/mtp+ngram/off/ngram-simple). Round-tripped through the
+        # status API so the dropdown reflects the picked mode, not the resolved
+        # flag set (auto on a 27B MTP GGUF resolves to draft-mtp but reads "Auto").
         self._requested_spec_mode: Optional[str] = None
         # User --spec-draft-n-max override (None = platform default).
         self._spec_draft_n_max: Optional[int] = None
@@ -654,14 +645,13 @@ class LlamaCppBackend:
         # MTP head count (llama.cpp #22673); >0 enables --spec-type draft-mtp.
         self._nextn_predict_layers: Optional[int] = None
         self._lock = threading.Lock()
-        # Wraps load_model() end-to-end so concurrent loads serialise and
-        # never coexist as two llama-server processes (#5401).
+        # Wraps load_model() end-to-end so concurrent loads serialise and never
+        # coexist as two llama-server processes (#5401).
         self._serial_load_lock = threading.Lock()
-        # Last extra_args / requested n_ctx, preserved across unload so the
-        # chat UI's /unload+/load Apply path can inherit them (#5401).
-        # ``_extra_args_source`` records the (model_identifier, hf_variant)
-        # the stored args came from so the route can refuse cross-model
-        # inheritance.
+        # Last extra_args / requested n_ctx, preserved across unload so the chat
+        # UI's /unload+/load Apply path can inherit them (#5401).
+        # ``_extra_args_source`` records the (model_identifier, hf_variant) the
+        # stored args came from so the route can refuse cross-model inheritance.
         self._extra_args: Optional[List[str]] = None
         self._extra_args_source: Optional[tuple[str, Optional[str]]] = None
         self._requested_n_ctx: int = 0
@@ -742,12 +732,10 @@ class LlamaCppBackend:
     def max_context_length(self) -> Optional[int]:
         """Return the largest context that fits on this hardware at load time.
 
-        The UI's "safe zone" warning threshold. If the weights fit on some
-        GPU subset, it's the binary-search cap from ``_fit_context_to_vram``
-        for that subset; if they exceed 90% of every subset, it's the 4096
-        fallback (the spec's default when the model won't fit). The UI
-        slider ceiling is ``native_context_length``; dragging above
-        ``max_context_length`` triggers the "might be slower" warning.
+        The UI's "safe zone" warning threshold: the ``_fit_context_to_vram``
+        binary-search cap for the best GPU subset, or the 4096 fallback if the
+        weights exceed 90% of every subset. The slider ceiling is
+        ``native_context_length``; dragging above this triggers the warning.
         """
         return self._max_context_length or self._context_length
 
@@ -759,16 +747,11 @@ class LlamaCppBackend:
     def load_progress(self) -> Optional[dict]:
         """Return live model-load progress, or None if not loading.
 
-        While llama-server warms up, its process is typically in kernel
-        state D (disk sleep) mmap'ing weight shards into page cache before
-        pushing layers to VRAM. During that window
-        ``/api/inference/status`` only reports ``loading``, so the UI has
-        nothing but a spinner that looks stuck for minutes on large MoEs.
-
-        Samples ``/proc/<pid>/status VmRSS`` against the sum of GGUF shard
-        sizes so the UI can render a real bar and compute rate / ETA.
-        Returns ``None`` when no load is in flight (no process, or already
-        healthy).
+        During warm-up llama-server mmaps weight shards into page cache before
+        pushing layers to VRAM, a window where status only reports ``loading``
+        and the UI spinner looks stuck for minutes on large MoEs. Samples
+        ``/proc/<pid>/status VmRSS`` against the sum of GGUF shard sizes for a
+        real progress bar. Returns ``None`` when no load is in flight.
 
         Shape::
 
@@ -779,8 +762,7 @@ class LlamaCppBackend:
                 "fraction": float,     # bytes_loaded / bytes_total, 0..1
             }
 
-        Linux-only for now; returns ``None`` where ``/proc/<pid>/status``
-        is unavailable (macOS/Windows would need a different API).
+        Linux-only; returns ``None`` where ``/proc/<pid>/status`` is unavailable.
         """
         proc = self._process
         if proc is None:
@@ -799,8 +781,7 @@ class LlamaCppBackend:
                     bytes_total += primary.stat().st_size
             except OSError:
                 pass
-            # Extra shards share the primary's prefix before the shard
-            # index (e.g. ``-00001-of-00004.gguf``).
+            # Extra shards share the primary's prefix before the shard index.
             try:
                 parent = primary.parent
                 stem = primary.name
@@ -1209,10 +1190,9 @@ class LlamaCppBackend:
     @staticmethod
     def _amd_apu_wants_unified_memory() -> bool:
         """True only for AMD unified-memory APUs (gfx1150/gfx1151), where
-        GGML_CUDA_ENABLE_UNIFIED_MEMORY lets llama.cpp use shared system
-        RAM. False for discrete AMD, NVIDIA, CPU and macOS (the env hurts
-        discrete GPUs). ROCm reuses torch.cuda.*; gcnArchName suffix is
-        stripped."""
+        GGML_CUDA_ENABLE_UNIFIED_MEMORY lets llama.cpp use shared system RAM.
+        False elsewhere (the env hurts discrete GPUs). ROCm reuses torch.cuda.*;
+        gcnArchName suffix is stripped."""
         try:
             import torch
 
@@ -1266,11 +1246,9 @@ class LlamaCppBackend:
                 cvd = os.environ.get("CUDA_VISIBLE_DEVICES")
                 if cvd is not None:
                     try:
-                        # `if x.strip()` filters trailing-comma masks like
-                        # "0,1," that would raise ValueError on an empty
-                        # token. An empty mask (CVD="") yields an empty
-                        # `allowed` set so all GPUs are filtered out, per
-                        # the codebase convention.
+                        # `if x.strip()` filters trailing-comma masks ("0,1,").
+                        # Empty mask (CVD="") yields an empty set -> all GPUs
+                        # filtered out, per codebase convention.
                         allowed = set(int(x.strip()) for x in cvd.split(",") if x.strip())
                     except ValueError:
                         pass
@@ -1283,8 +1261,7 @@ class LlamaCppBackend:
                         if allowed is not None and idx not in allowed:
                             continue
                         gpus.append((idx, free_mib))
-                # Match the docstring's sort-by-id guarantee; nvidia-smi
-                # output is usually sorted but driver order isn't guaranteed.
+                # Match the docstring's sort-by-id guarantee (driver order isn't).
                 gpus.sort(key = lambda g: g[0])
                 if gpus:
                     return gpus
@@ -1299,19 +1276,14 @@ class LlamaCppBackend:
                 return []
             if not hasattr(torch.cuda, "mem_get_info"):
                 return []
-            # torch.cuda enumerates GPUs RELATIVE to the visibility mask
-            # (CUDA_VISIBLE_DEVICES on NVIDIA; HIP_VISIBLE_DEVICES, or
-            # ROCR_VISIBLE_DEVICES if HIP unset, on AMD ROCm). We feed
-            # these IDs back into the subprocess as CVD, so visible
-            # ordinals must be translated to physical indices first;
-            # otherwise ``CUDA_VISIBLE_DEVICES=2,3`` gets rewritten to
-            # ``0,1`` and targets the wrong GPUs.
+            # torch.cuda enumerates GPUs RELATIVE to the visibility mask. We
+            # feed these IDs back into the subprocess as CVD, so visible ordinals
+            # must be translated to physical indices first; otherwise CVD=2,3
+            # gets rewritten to 0,1 and targets the wrong GPUs.
             physical_ids: Optional[list[int]] = None
-            # Match ``utils/hardware/hardware.py::
-            # _get_parent_visible_gpu_spec``: treat an empty mask
-            # (``HIP_VISIBLE_DEVICES=""``) as "no GPUs" rather than falling
-            # through to the next var. ``or`` would coerce "" to falsy and
-            # promote the wrong source.
+            # Match utils/hardware/hardware.py::_get_parent_visible_gpu_spec:
+            # treat an empty mask (HIP_VISIBLE_DEVICES="") as "no GPUs" rather
+            # than falling through. ``or`` would coerce "" to the wrong source.
             if getattr(torch.version, "hip", None) is not None:
                 hip_v = os.environ.get("HIP_VISIBLE_DEVICES")
                 rocr_v = os.environ.get("ROCR_VISIBLE_DEVICES")
@@ -1326,9 +1298,8 @@ class LlamaCppBackend:
                 cvd = os.environ.get("CUDA_VISIBLE_DEVICES")
             if cvd is not None:
                 try:
-                    # Empty mask (CVD="") yields an empty list so the loop
-                    # produces no GPUs, consistent with the nvidia-smi path
-                    # and utils/hardware/hardware.py.
+                    # Empty mask (CVD="") yields an empty list -> no GPUs,
+                    # consistent with the nvidia-smi path.
                     physical_ids = [int(x.strip()) for x in cvd.split(",") if x.strip()]
                 except ValueError:
                     physical_ids = None
@@ -1361,16 +1332,14 @@ class LlamaCppBackend:
         """Poll ``_get_gpu_free_memory`` until free VRAM stabilises.
 
         The driver reclaims a dead process's allocations asynchronously, so
-        sampling free memory in the kill-to-spawn window reads artificially
-        low and pushes ``_select_gpus`` / ``_fit_context_to_vram`` toward
-        needless CPU offload -- on a tight VRAM card, the Apply-reload OOM
-        that bare-shell launches with the same flags never see.
+        sampling free memory in the kill-to-spawn window reads artificially low
+        and pushes GPU selection toward needless CPU offload (the Apply-reload
+        OOM bare-shell launches never see).
 
-        Short-circuits on cold start (``since_kill`` zero), stale kill
-        (older than ``_VRAM_SETTLE_WINDOW_S``), CPU-only hosts (empty
-        probe), probe exceptions, and GPU-set changes. ``max_wait`` is a
-        wall-clock bound including probe time, so a wedged ``nvidia-smi``
-        cannot extend the reload.
+        Short-circuits on cold start, stale kill (older than
+        ``_VRAM_SETTLE_WINDOW_S``), CPU-only hosts, probe exceptions, and GPU-set
+        changes. ``max_wait`` bounds wall-clock time so a wedged ``nvidia-smi``
+        can't extend the reload.
         """
         now = time.monotonic()
         if since_kill <= 0.0:
@@ -1406,8 +1375,7 @@ class LlamaCppBackend:
                     stable = False
                     break
                 prev_free = prev_map[idx]
-                # Adaptive: 2% of the larger sample dominates the 256 MiB
-                # floor on large-VRAM cards.
+                # Adaptive: 2% of the larger sample dominates the 256 MiB floor.
                 per_gpu_tol = max(tolerance_mib, int(max(free, prev_free) * 0.02))
                 if abs(free - prev_free) >= per_gpu_tol:
                     stable = False
@@ -1418,34 +1386,25 @@ class LlamaCppBackend:
 
     # Free-VRAM fraction at which Studio pins the GPU directly instead of
     # deferring to ``--fit on``. 5% headroom covers CUDA context + compute
-    # buffers; 0.90 was too conservative, dropping 91-94% fits to CPU
-    # offload (#5106). --fit on still catches the truly-too-large case.
+    # buffers; 0.90 dropped 91-94% fits to CPU offload (#5106).
     _GPU_PIN_VRAM_FRACTION = 0.95
 
     @staticmethod
     def _windows_pip_nvidia_dll_dirs(prefix: str) -> list[str]:
         """Return DLL dirs from pip-installed CUDA wheels under
         ``<prefix>/Lib/site-packages/`` so llama-server.exe can load
-        ``cudart64_X.dll`` / ``cublas64_X.dll`` without a system CUDA
-        toolkit. Mirrors the Linux ``nvidia/cu*/lib`` LD_LIBRARY_PATH block,
-        with parity for the Windows wheel layouts seen in the wild:
-          * ``nvidia/<pkg>/bin`` -- legacy modular wheels
-            (``nvidia-cuda-runtime-cu12``, ``nvidia-cublas-cu12``, etc.).
-          * ``nvidia/<pkg>/bin/x86_64`` and ``.../bin/x64`` -- current
-            CUDA 13 layout for the unsuffixed ``nvidia-cuda-runtime`` /
-            ``nvidia-cublas`` packages (under ``nvidia/cu13/bin/x86_64/``)
-            (#5106).
-          * ``nvidia/<pkg>/Library/bin`` (and arch subdirs) -- conda-style
-            wheel repacks.
-          * ``torch/lib`` -- PyTorch's CUDA-bundled Windows wheel can ship
-            ``cudart64_*.dll`` here instead of as separate ``nvidia-*``
-            wheels. The install-side ``python_runtime_dirs`` in
-            ``install_llama_prebuilt.py`` covers this for the same reason.
+        ``cudart64_X.dll`` / ``cublas64_X.dll`` without a system CUDA toolkit.
+        Mirrors the Linux ``nvidia/cu*/lib`` LD_LIBRARY_PATH block, covering the
+        Windows wheel layouts seen in the wild:
+          * ``nvidia/<pkg>/bin`` -- legacy modular wheels.
+          * ``nvidia/<pkg>/bin/x86_64`` and ``.../bin/x64`` -- CUDA 13 layout
+            for unsuffixed packages (#5106).
+          * ``nvidia/<pkg>/Library/bin`` (and arch subdirs) -- conda repacks.
+          * ``torch/lib`` -- PyTorch's CUDA-bundled wheel can ship
+            ``cudart64_*.dll`` here; mirrors install_llama_prebuilt.py.
 
-        Walks the tree with ``Path.iterdir`` rather than ``glob.glob`` so
-        it's safe against Windows paths containing ``[`` or ``]`` (valid in
-        usernames; otherwise read as a glob character class, silently
-        missing existing dirs)."""
+        Walks with ``Path.iterdir`` not ``glob.glob`` so it's safe against
+        Windows paths containing ``[`` or ``]`` (valid in usernames)."""
         site_packages = Path(prefix) / "Lib" / "site-packages"
         out: list[str] = []
         seen: set[str] = set()
@@ -1464,8 +1423,8 @@ class LlamaCppBackend:
             for pkg_dir in nvidia_root.iterdir():
                 if not pkg_dir.is_dir():
                     continue
-                # Order matters: arch-specific subdirs first so the explicit
-                # cudart64_X.dll location wins over an empty sibling ``bin``.
+                # Arch-specific subdirs first so the explicit cudart64_X.dll
+                # location wins over an empty sibling ``bin``.
                 for sub in (
                     pkg_dir / "bin" / "x86_64",
                     pkg_dir / "bin" / "x64",
@@ -1480,11 +1439,9 @@ class LlamaCppBackend:
 
     @staticmethod
     def _build_windows_path_dirs(binary_dir: str, prefix: str, cuda_path: str) -> list[str]:
-        """Ordered PATH entries the win32 branch of start_llama_server
-        prepends so llama-server.exe resolves cudart / cublas DLLs:
-        binary_dir, pip nvidia wheels, CUDA_PATH/bin, CUDA_PATH/bin/x64.
-        Extracted so test_windows_gpu_detection_mock asserts against the
-        production logic, not a hand-copy. #5106."""
+        """Ordered PATH entries prepended so llama-server.exe resolves cudart /
+        cublas DLLs: binary_dir, pip nvidia wheels, CUDA_PATH/bin, .../bin/x64.
+        Extracted so test_windows_gpu_detection_mock tests the real logic. #5106."""
         path_dirs = [binary_dir]
         path_dirs.extend(LlamaCppBackend._windows_pip_nvidia_dll_dirs(prefix))
         if cuda_path:
@@ -1547,10 +1504,10 @@ class LlamaCppBackend:
         """True if we have enough GGUF metadata to estimate KV cache size."""
         if self._n_layers is None:
             return False
-        # MLA: kv_lora_rank suffices (K-only cache)
+        # MLA: kv_lora_rank suffices (K-only cache).
         if self._kv_lora_rank is not None:
             return True
-        # New-style: need explicit key AND value dimensions
+        # New-style: need explicit key AND value dimensions.
         if self._kv_key_length is not None and self._kv_value_length is not None:
             return True
         # Legacy: need embedding_length + a head count (scalar or per-layer).
@@ -1585,20 +1542,14 @@ class LlamaCppBackend:
           5. Legacy   -- fallback using embed // n_heads
 
         Server-flag knobs (mirror llama-server's CLI):
-          swa_full        -- ``--swa-full``: force SWA layers to cache the
-                             full ``n_ctx`` (collapses path 3 to path 4
-                             for SWA layers).
-          n_parallel      -- ``--parallel``: server slots. Verified against
-                             llama-server: non-SWA layers stay constant
-                             (cells split across slots), SWA layers scale
-                             linearly (per-slot window).
-          kv_unified      -- ``--kv-unified`` (default on): kept for API
-                             forward-compat. A no-op for memory math; the
-                             unified buffer total matches per-slot buffers
-                             in measured cases.
-          ctx_checkpoints -- ``--ctx-checkpoints``: SWA snapshots per slot
-                             (PR #15293). Each stores one sliding-window of
-                             state per SWA layer.
+          swa_full        -- ``--swa-full``: force SWA layers to cache full
+                             ``n_ctx`` (collapses path 3 to path 4 for them).
+          n_parallel      -- ``--parallel`` slots: non-SWA layers stay constant
+                             (cells split across slots), SWA layers scale linearly.
+          kv_unified      -- ``--kv-unified`` (default on): no-op for memory math;
+                             kept for API forward-compat.
+          ctx_checkpoints -- ``--ctx-checkpoints`` (PR #15293): N SWA snapshots
+                             per slot, one sliding-window of state per SWA layer.
 
         Returns 0 if metadata is insufficient.
         """
@@ -1606,9 +1557,8 @@ class LlamaCppBackend:
             return 0
 
         n_layers = self._n_layers  # type: ignore[assignment]
-        # Gemma 3n / Gemma 4 reuse earlier layers' KV in the last
-        # ``shared_kv_layers`` blocks -- those allocate no cache. Floor at 1
-        # so a misconfigured GGUF can't zero out KV.
+        # Gemma 3n / Gemma 4 reuse earlier KV in the last ``shared_kv_layers``
+        # blocks (no cache). Floor at 1 so a bad GGUF can't zero out KV.
         shared = self._shared_kv_layers or 0
         n_layers_kv = max(1, n_layers - shared)
         n_kv = self._n_kv_heads or self._n_heads or 1  # type: ignore[assignment]
@@ -1629,11 +1579,10 @@ class LlamaCppBackend:
         slots = max(1, n_parallel)
 
         # Path 1: MLA (DeepSeek-V2/V3, GLM-4.7, GLM-5, Kimi-K2.5)
-        # Stores one compressed KV latent per token/layer (shared across
-        # heads); V is reconstructed from the latent, no separate V cache.
-        # key_length = kv_lora_rank + rope_dim (full compressed rep).
-        # MLA GGUFs set head_count_kv=1; default to 1 if absent to avoid
-        # falling back to n_heads (e.g. 128 for DeepSeek-V3) which 128x's.
+        # One compressed KV latent per token/layer (shared across heads); V is
+        # reconstructed from it, no separate V cache. key_length = kv_lora_rank
+        # + rope_dim. MLA GGUFs set head_count_kv=1; default to 1 if absent to
+        # avoid falling back to n_heads (e.g. 128 for DeepSeek-V3) which 128x's.
         if self._kv_lora_rank is not None:
             n_kv_mla = self._n_kv_heads or 1
             rope_dim = self._key_length_mla or 64
@@ -1644,7 +1593,7 @@ class LlamaCppBackend:
         val_len = self._kv_value_length
 
         # Path 2: Hybrid Mamba/Attention (Qwen3.5-27B, Qwen3.5-35B-A3B)
-        # Only 1 in N layers is attention; rest are Mamba (no KV cache).
+        # Only 1 in N layers is attention; the rest are Mamba (no KV cache).
         if self._ssm_inner_size is not None and self._full_attention_interval is not None:
             fai = self._full_attention_interval
             n_attn = -(-n_layers // fai) if fai > 0 else n_layers  # ceiling division
@@ -1654,18 +1603,14 @@ class LlamaCppBackend:
             return int(n_attn * n_ctx * n_kv * 2 * head_dim * bpe)
 
         # Path 3: Sliding window (Gemma 2/3/3n/4, gpt-oss, Cohere2 ...).
-        # Pattern filled in by the resolver at parse time; if absent, falls
-        # through to the legacy 1/4-global heuristic below.
-        # Per-layer-type ``--parallel N`` accounting (verified against
-        # ``llama-server``):
-        #   * non-SWA layers:    total cells = n_ctx, partitioned across
-        #                         slots -> total memory CONSTANT in slots.
-        #   * SWA layers:         per-slot cells = 2 * sliding_window
-        #                         (capped at n_ctx and at per_slot_ctx when
-        #                         ctx is split among slots) -> total memory
-        #                         grows LINEARLY in slots.
-        # ``--swa-full`` forces full n_ctx for SWA layers instead.
-        # ``--ctx-checkpoints N`` adds N snapshots per SWA layer per slot.
+        # Pattern filled by the resolver at parse time; if absent, falls through
+        # to the legacy 1/4-global heuristic below. Per-layer-type --parallel N
+        # accounting (verified against llama-server):
+        #   * non-SWA layers: total cells = n_ctx split across slots -> CONSTANT.
+        #   * SWA layers:     per-slot cells = 2*sliding_window (capped at n_ctx
+        #                     and per_slot_ctx) -> grows LINEARLY in slots.
+        # --swa-full forces full n_ctx for SWA layers; --ctx-checkpoints N adds
+        # N snapshots per SWA layer per slot.
         if (
             self._sliding_window is not None
             and self._sliding_window > 0
@@ -1674,11 +1619,9 @@ class LlamaCppBackend:
         ):
             swa = self._sliding_window
             per_slot_ctx = max(1, n_ctx // slots)
-            # ``--swa-full`` makes SWA layers cache the full context like
-            # non-SWA: cells partitioned across slots, so per-slot cells =
-            # per_slot_ctx and slots*per-slot collapses to the constant
-            # ``n_ctx`` total. Otherwise SWA caches 2*sliding_window per
-            # slot, clamped at the per-slot ctx.
+            # --swa-full caches full context like non-SWA (per-slot cells =
+            # per_slot_ctx, collapsing to constant n_ctx total); otherwise SWA
+            # caches 2*sliding_window per slot, clamped at per-slot ctx.
             swa_cells_per_slot = per_slot_ctx if swa_full else min(n_ctx, 2 * swa, per_slot_ctx)
             key_len_swa = self._kv_key_length_swa or key_len
             val_len_swa = self._kv_value_length_swa or val_len
@@ -1686,8 +1629,8 @@ class LlamaCppBackend:
                 global_bytes = 0.0  # constant across slots
                 swa_bytes_per_slot = 0.0  # multiplied by slots
                 checkpoint_extra_per_slot = 0.0
-                # Only layers that allocate their own KV; trailing ``shared``
-                # layers reuse earlier caches.
+                # Only layers that allocate their own KV; trailing shared layers
+                # reuse earlier caches.
                 for layer_idx in range(n_layers_kv):
                     layer_n_kv = self._kv_heads_for_layer(layer_idx, n_kv)
                     is_swa = (
@@ -1748,20 +1691,15 @@ class LlamaCppBackend:
         """Return the largest context length that fits in GPU VRAM.
 
         Uses 90% of available VRAM as the ctx-fit budget -- tighter than
-        ``_GPU_PIN_VRAM_FRACTION`` on purpose: over-promising context OOMs
-        at runtime, while pinning conservatively just defers to --fit on. If
-        the weights alone don't fit, returns ``requested_ctx`` unchanged.
+        ``_GPU_PIN_VRAM_FRACTION`` on purpose (over-promising context OOMs at
+        runtime). If the weights alone don't fit, returns ``requested_ctx``.
 
-        ``kv_on_gpu`` mirrors ``--kv-offload`` (default on). When False the
-        KV cache lives in CPU RAM and doesn't compete with weights for VRAM;
-        the requested context is honored verbatim. Other keyword args mirror
-        ``_estimate_kv_cache_bytes``.
+        ``kv_on_gpu`` mirrors ``--kv-offload`` (default on); when False the KV
+        cache lives in CPU RAM and the requested context is honored verbatim.
+        Other keyword args mirror ``_estimate_kv_cache_bytes``.
 
-        ``mtp_engaged`` reserves extra VRAM for the MTP draft model's KV
-        cache + compute graph buffers. llama.cpp's MTP path keeps a
-        secondary cache sized off the target's KV; on tight VRAM tiers
-        (e.g. 32 GB) auto-fit at native context would otherwise spill and
-        force a slower partial-offload path.
+        ``mtp_engaged`` reserves extra VRAM for the MTP draft model's KV cache +
+        compute buffers, else tight tiers (e.g. 32 GB) spill to a slower path.
         """
         if not self._can_estimate_kv():
             logger.debug(
@@ -1792,8 +1730,7 @@ class LlamaCppBackend:
         if model_footprint + kv <= budget_bytes:
             return requested_ctx
 
-        # Weights alone exceed budget -- reducing ctx can't help. Return
-        # requested_ctx unchanged; --fit will handle VRAM management.
+        # Weights alone exceed budget -- reducing ctx can't help; --fit handles it.
         if model_footprint >= budget_bytes:
             logger.debug(
                 "Model footprint exceeds GPU budget before KV cache",
@@ -1886,16 +1823,13 @@ class LlamaCppBackend:
     # ── Stdout drain (prevents pipe deadlock on Windows) ─────────
 
     def _drain_stdout(self):
-        """
-        Read subprocess stdout lines in a background thread.
-
-        Prevents a pipe-buffer deadlock on Windows (default buffer ~4 KB):
-        without draining, llama-server blocks on writes and never becomes
-        healthy.
+        """Read subprocess stdout lines in a background thread.
 
+        Prevents a pipe-buffer deadlock on Windows (~4 KB buffer): without
+        draining, llama-server blocks on writes and never becomes healthy.
         Each line is also teed to ``self._llama_log_fh`` when set, so a
-        post-mortem (especially in CI) has the full output even if the crash
-        predates the drain-thread join in ``_wait_for_health``.
+        post-mortem has the full output even if the crash predates the
+        drain-thread join in ``_wait_for_health``.
         """
         try:
             for line in self._process.stdout:
@@ -1912,7 +1846,7 @@ class LlamaCppBackend:
                             # Log file closed under us; tee silently.
                             pass
         except (ValueError, OSError):
-            # Pipe closed -- process terminating
+            # Pipe closed -- process terminating.
             pass
 
     # GGUF KV type sizes for fast skipping
@@ -2486,13 +2420,13 @@ class LlamaCppBackend:
     # ── Lifecycle ─────────────────────────────────────────────────
 
     # GGUF ``general.architecture`` values for diffusion / image models.
-    # llama.cpp proper has no such architectures, so loading one as a chat
-    # model dies with "unknown model architecture: '<arch>'". These match
-    # the patched stable-diffusion.cpp / ComfyUI-GGUF enums (LLM_ARCH_FLUX,
-    # LLM_ARCH_QWEN_IMAGE, ...). Unsloth publishes FLUX and Qwen-Image GGUFs
-    # under https://huggingface.co/collections/unsloth/unsloth-diffusion-ggufs.
-    # Matched exactly (not a substring) so a chat arch merely containing a
-    # short token like "wan"/"sd1" (e.g. "taiwan") isn't misrouted to Images.
+    # llama.cpp has no such architectures, so loading one as a chat model dies
+    # with "unknown model architecture: '<arch>'". These match the patched
+    # stable-diffusion.cpp / ComfyUI-GGUF enums. Unsloth publishes FLUX and
+    # Qwen-Image GGUFs under
+    # https://huggingface.co/collections/unsloth/unsloth-diffusion-ggufs.
+    # Matched exactly (not a substring) so a chat arch containing "wan"/"sd1"
+    # (e.g. "taiwan") isn't misrouted to Images.
     _DIFFUSION_ARCHES = frozenset(
         (
             "qwen_image",
@@ -2517,12 +2451,10 @@ class LlamaCppBackend:
         """Explain *why* llama-server failed to start, from its output.
 
         Several distinct failures otherwise collapse into the same opaque
-        "invalid GGUF or out of memory" message. Worst case: a diffusion /
-        image GGUF (FLUX, Qwen-Image, ...) loaded as a chat model -- the
-        file is valid and memory is plentiful, but llama.cpp has no such
-        architecture, so the user is told to free memory that was never the
-        problem (issue #5842). Pick the most specific message the captured
-        output supports.
+        "invalid GGUF or out of memory" message. Worst case: a diffusion GGUF
+        loaded as a chat model -- valid file, plenty of memory, but llama.cpp
+        has no such architecture, so the user is told to free memory that was
+        never the problem (#5842). Pick the most specific message we can.
         """
         lowered = (output or "").lower()
 
@@ -2606,25 +2538,19 @@ class LlamaCppBackend:
         n_parallel: int = 1,
         extra_args: Optional[List[str]] = None,
     ) -> bool:
-        """
-        Start llama-server with a GGUF model.
+        """Start llama-server with a GGUF model.
 
         Two modes:
         - Local: ``gguf_path="/path/to/model.gguf"`` → uses ``-m``
-        - HF:    ``hf_repo="unsloth/gemma-3-4b-it-GGUF", hf_variant="Q4_K_M"`` → uses ``-hf``
+        - HF:    ``hf_repo="...-GGUF", hf_variant="Q4_K_M"`` → uses ``-hf``
 
-        In HF mode, llama-server handles download, caching, and auto-loading
-        mmproj files for vision models.
-
-        Returns True if the server started and health check passed.
+        Returns True if the server started and the health check passed.
         """
         # Serialise the whole load so concurrent /load calls never leave two
-        # llama-server processes alive (#5401 / #5161). Doesn't block
-        # /unload, /status, /load-progress.
+        # llama-server processes alive (#5401 / #5161). Doesn't block /unload.
         with self._serial_load_lock:
-            # Duplicate /load that raced past the route-level check (first
-            # one hadn't published _healthy=True yet). If the live server
-            # already satisfies this request, do nothing.
+            # Duplicate /load that raced past the route check: do nothing if the
+            # live server already satisfies this request.
             if self._already_in_target_state(
                 gguf_path = gguf_path,
                 model_identifier = model_identifier,
@@ -2721,13 +2647,12 @@ class LlamaCppBackend:
             else:
                 raise ValueError("Either gguf_path or hf_repo must be provided")
 
-            # Set identifier early so _read_gguf_metadata can use it for DeepSeek detection
+            # Set identifier early so _read_gguf_metadata can use it (DeepSeek).
             self._model_identifier = model_identifier
 
-            # Read GGUF metadata (context_length, chat_template); fast, header only
+            # Read GGUF metadata (context_length, chat_template); header-only.
             self._read_gguf_metadata(model_path)
 
-            # Check cancel after download
             if self._cancel_event.is_set():
                 logger.info("Load cancelled after download phase")
                 return False
@@ -2779,12 +2704,10 @@ class LlamaCppBackend:
                     # GPU/VRAM-fit logic below may shrink it on limited HW.
                     max_available_ctx = self._context_length or effective_ctx
 
-                    # Will MTP engage on this load? If so, auto-fit must
-                    # reserve extra VRAM for the draft model's KV cache +
-                    # compute graph. Mirrors _build_speculative_flags'
-                    # canonical-mode resolver: forced mtp / mtp+ngram always
-                    # engage; auto only on an MTP GGUF >= 3B (sub-3B auto
-                    # falls back to ngram-mod, no headroom needed); ngram /
+                    # Will MTP engage on this load? If so, auto-fit reserves
+                    # extra VRAM for the draft model. Mirrors
+                    # _build_speculative_flags' resolver: forced mtp / mtp+ngram
+                    # always engage; auto only on an MTP GGUF >= 3B; ngram /
                     # ngram-simple / off never engage MTP.
                     _mtp_canonical = _canonicalize_spec_mode(speculative_type)
                     _mtp_effective = _mtp_canonical or "auto"
@@ -2805,16 +2728,13 @@ class LlamaCppBackend:
                         )
                     )
 
-                    # Auto-cap context to fit GPU VRAM and select GPUs.
-                    # Two policies by whether the user set n_ctx:
-                    #
-                    # Explicit n_ctx: honor it. Try the full requested context
-                    #   with _select_gpus (uses as many GPUs as needed); only
-                    #   cap if it doesn't fit on any GPU combination.
-                    #
-                    # Auto n_ctx=0 (native context): prefer fewer GPUs with
-                    #   reduced context, since multi-GPU is slower and the user
-                    #   didn't ask for a specific length.
+                    # Auto-cap context to fit GPU VRAM and select GPUs. Two
+                    # policies by whether the user set n_ctx:
+                    #   Explicit n_ctx: honor it. Try the full context with
+                    #     _select_gpus (as many GPUs as needed); cap only if it
+                    #     doesn't fit on any combination.
+                    #   Auto n_ctx=0 (native): prefer fewer GPUs with reduced
+                    #     context, since multi-GPU is slower.
                     gpu_indices, use_fit = None, True
                     explicit_ctx = requested_ctx > 0
 
@@ -2846,21 +2766,15 @@ class LlamaCppBackend:
                             if best_cap > 0:
                                 max_available_ctx = best_cap
                             else:
-                                # Weights exceed 90% of every GPU subset's free
-                                # memory, so no context fits. Anchor the UI's
-                                # "safe zone" threshold at 4096 (the spec's
-                                # default when the model can't fit) so the ctx
-                                # slider shows the "might be slower" warning as
-                                # soon as the user drags above the fallback.
+                                # Weights exceed 90% of every GPU subset, so no
+                                # context fits. Anchor the UI "safe zone" at 4096
+                                # so the slider warns above the fallback.
                                 max_available_ctx = min(4096, native_ctx_for_cap)
 
                         if explicit_ctx:
                             # Honor the requested context verbatim. If it fits,
-                            # pin GPUs and skip --fit; if not, ship
-                            # -c <user_ctx> --fit on and let llama-server flex
-                            # -ngl (CPU layer offload). The UI should have
-                            # surfaced the "might be slower" warning before a
-                            # ctx above the fit ceiling was submitted.
+                            # pin GPUs and skip --fit; else ship -c <ctx> --fit
+                            # on and let llama-server flex -ngl (CPU offload).
                             requested_total = model_size + self._estimate_kv_cache_bytes(
                                 effective_ctx, cache_type_kv, n_parallel = n_parallel
                             )
@@ -2893,9 +2807,8 @@ class LlamaCppBackend:
                                     break
                             else:
                                 # Native ctx doesn't fit. Drop to 4096 and
-                                # re-check before deferring to --fit on: a model
-                                # that overflows at 131k may pin comfortably
-                                # with a 4096 KV cache (#5106).
+                                # re-check before --fit on: a model overflowing
+                                # at 131k may pin fine with a 4096 KV (#5106).
                                 effective_ctx = min(4096, effective_ctx)
                                 if effective_ctx > 0:
                                     for n_gpus in range(1, len(ranked) + 1):
@@ -2913,18 +2826,16 @@ class LlamaCppBackend:
                                             break
 
                     elif gpus:
-                        # Can't estimate KV -- file-size-only check. Without KV
-                        # estimation we can't prove a hardware cap, so keep the
-                        # ceiling at the native context (already the default).
+                        # Can't estimate KV -- file-size-only check; keep the
+                        # ceiling at native context (already the default).
                         logger.debug(
                             "Falling back to file-size-only GPU selection",
                             model_size_gb = round(model_size / (1024**3), 2),
                         )
                         gpu_indices, use_fit = self._select_gpus(model_size, gpus)
                         if use_fit and not explicit_ctx:
-                            # Weights don't fit on any subset. Default the UI to
-                            # 4096 so the slider doesn't land on an unusable
-                            # native context; --fit on flexes -ngl at runtime.
+                            # Weights don't fit on any subset; default UI to 4096
+                            # so the slider isn't on an unusable native ctx.
                             effective_ctx = min(4096, effective_ctx) if effective_ctx > 0 else 4096
 
                     if effective_ctx < original_ctx:
@@ -3036,29 +2947,8 @@ class LlamaCppBackend:
                 else:
                     self._cache_type_kv = None
 
-                # Speculative decoding (n-gram self-speculation, zero VRAM).
-                # ngram-mod: ~16 MB shared hash pool, constant memory/
-                # complexity, variable draft lengths. Helps most when the
-                # model repeats existing text (code refactor, summarization,
-                # reasoning); for low-repetition chat, overhead is ~5 ms.
-                #
-                # Benchmarks from upstream llama.cpp speculative-decoding PRs:
-                #   Scenario                        | Without | With    | Speedup
-                #   gpt-oss-120b code refactor      | 181 t/s | 446 t/s | 2.5x
-                #   Qwen3-235B offloaded            |  12 t/s |  21 t/s | 1.8x
-                #   gpt-oss-120b repeat (92% accept)| 181 t/s | 814 t/s | 4.5x
-                #
-                # Params from llama.cpp server README:
-                #   --spec-ngram-mod-n-match 24 (lookup length)
-                #   --spec-ngram-mod-n-min 48 --spec-ngram-mod-n-max 64
-                #   (MoEs need long drafts; dense models can reduce these)
-                # ref: https://github.com/ggml-org/llama.cpp/blob/master/docs/speculative.md
-                # ref: https://github.com/ggml-org/llama.cpp/pull/19164
-                # ref: https://github.com/ggml-org/llama.cpp/pull/18471
-                # draft-mtp: MTP heads on Unsloth's *-MTP GGUFs
-                # (llama.cpp #22673). Auto-enabled via nextn_predict_layers,
-                # fallback to -MTP in name. GPU: MTP-only. CPU/Mac: chain with
-                # ngram-mod. See unsloth.ai/docs/models/qwen3.6#mtp-guide.
+                # Speculative decoding. See _build_speculative_flags for the
+                # mode resolution, benchmarks, and llama.cpp references.
                 spec_flags = self._build_speculative_flags(
                     speculative_type = speculative_type,
                     spec_draft_n_max = spec_draft_n_max,
@@ -3097,9 +2987,9 @@ class LlamaCppBackend:
                     cmd.extend(["--chat-template-file", self._chat_template_file.name])
                     logger.info(f"Using custom chat template file: {self._chat_template_file.name}")
 
-                # For reasoning models, set default thinking mode. Qwen3.5/3.6
-                # below 9B (0.8B, 2B, 4B) disable thinking by default; 9B+
-                # enable it. Always-on templates ignore the kwarg, so skip.
+                # Default thinking mode for reasoning models. Qwen3.5/3.6 below
+                # 9B disable thinking by default; 9B+ enable it. Always-on
+                # templates ignore the kwarg, so skip.
                 if self._supports_reasoning and not self._reasoning_always_on:
                     thinking_default = True
                     mid = (model_identifier or "").lower()
@@ -3132,10 +3022,9 @@ class LlamaCppBackend:
                 else:
                     self._api_key = None
 
-                # User pass-through args go last so llama.cpp's last-wins
-                # parsing lets the user override Studio's auto-set tier-2 flags
-                # (e.g. --cache-type-k, --spec-type). The route layer already
-                # validated this list via validate_extra_args().
+                # User pass-through args go last so llama.cpp's last-wins parsing
+                # lets the user override Studio's auto-set flags. Already
+                # validated by the route via validate_extra_args().
                 if extra_args:
                     cmd.extend(str(a) for a in extra_args)
                     logger.info(f"Appending user extra args to llama-server: {list(extra_args)}")
@@ -3147,7 +3036,7 @@ class LlamaCppBackend:
                         _log_cmd[_ki] = "<redacted>"
                 logger.info(f"Starting llama-server: {' '.join(_log_cmd)}")
 
-                # Set library paths so llama-server finds its shared libs and CUDA DLLs
+                # Library paths so llama-server finds its shared libs and CUDA DLLs.
                 import os
                 import sys
 
@@ -3170,14 +3059,11 @@ class LlamaCppBackend:
                     existing_path = env.get("PATH", "")
                     env["PATH"] = ";".join(path_dirs) + ";" + existing_path
 
-                    # ROCm: the llama.cpp prebuilt bundles its own rocblas.dll
-                    # but NOT the Tensile kernel files it needs
-                    # (rocblas/library/TensileLibrary*.dat + *.hsaco). The
-                    # bundled DLL searches relative to its own location
-                    # (<binary_dir>/rocblas/library/), which doesn't exist ->
-                    # silent crash on the first GEMM. ROCBLAS_TENSILE_LIBPATH
-                    # repoints that search at the ROCm install where the kernel
-                    # files actually are.
+                    # ROCm: the prebuilt bundles rocblas.dll but NOT the Tensile
+                    # kernel files (rocblas/library/*.dat + *.hsaco); the DLL
+                    # searches <binary_dir>/rocblas/library/ which doesn't exist
+                    # -> silent crash on the first GEMM. ROCBLAS_TENSILE_LIBPATH
+                    # repoints that search at the ROCm install.
                     _hip_path = os.environ.get("HIP_PATH", os.environ.get("ROCM_PATH", ""))
                     if _hip_path:
                         _rocblas_lib = os.path.join(_hip_path, "bin", "rocblas", "library")
@@ -3191,10 +3077,9 @@ class LlamaCppBackend:
                     lib_dirs = [binary_dir]
                     _arch = platform.machine()  # x86_64, aarch64, etc.
 
-                    # Pip-installed nvidia CUDA runtime libs (e.g. torch's
-                    # bundled cuda-bindings). The prebuilt llama.cpp binary
-                    # links against libcudart.so.13 / libcublas.so.13 which
-                    # live here, not in /usr/local/cuda.
+                    # Pip-installed nvidia CUDA runtime libs. The prebuilt
+                    # binary links libcudart.so.13 / libcublas.so.13 which live
+                    # here, not in /usr/local/cuda.
                     import glob as _glob
 
                     for _nv_pattern in [
@@ -3246,10 +3131,9 @@ class LlamaCppBackend:
                     new_ld = ":".join(lib_dirs)
                     env["LD_LIBRARY_PATH"] = f"{new_ld}:{existing_ld}" if existing_ld else new_ld
 
-                # Pin to selected GPU(s). On ROCm, llama-server (and any torch
-                # in the subprocess) honors HIP_VISIBLE_DEVICES /
-                # ROCR_VISIBLE_DEVICES; narrowing only CUDA_VISIBLE_DEVICES
-                # leaves an AMD child seeing the full HIP/ROCR set inherited.
+                # Pin to selected GPU(s). On ROCm, narrowing only
+                # CUDA_VISIBLE_DEVICES leaves an AMD child seeing the full
+                # HIP/ROCR set, so set those too.
                 if gpu_indices is not None:
                     pinned = ",".join(str(i) for i in gpu_indices)
                     env["CUDA_VISIBLE_DEVICES"] = pinned
@@ -3261,18 +3145,14 @@ class LlamaCppBackend:
                     except Exception as e:
                         logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 
-                # Defensive kill: if a concurrent load slipped past Phase 1
-                # (its `self._process` was None then) and already stored a
-                # Popen handle here, drop that orphan before we overwrite the
-                # reference. See issue #5161.
+                # Defensive kill: drop an orphan Popen a concurrent load may
+                # have stored before we overwrite the reference (#5161).
                 self._kill_process()
 
                 self._stdout_lines = []
                 # Tee llama-server output to a dedicated log file so a
-                # post-mortem in CI (or after a remote-debug session) has the
-                # full subprocess trail even when the parent only kept the last
-                # 50 lines. Path lives under the studio home alongside other
-                # Studio logs.
+                # post-mortem has the full trail even when the parent only kept
+                # the last 50 lines. Path is under the studio home.
                 self._llama_log_fh = None
                 try:
                     log_dir = _swa_cache_path().parent / "logs" / "llama-server"
@@ -3306,10 +3186,9 @@ class LlamaCppBackend:
                 )
                 self._stdout_thread.start()
 
-                # Store the resolved on-disk path, not the caller's kwarg. In
-                # HF mode the caller passes gguf_path=None and ``model_path``
-                # is what llama-server actually mmap's. Downstream consumers
-                # (load_progress, log lines, etc.) need the real on-disk path.
+                # Store the resolved on-disk path, not the caller's kwarg: in
+                # HF mode gguf_path is None and ``model_path`` is what
+                # llama-server mmap's, which downstream consumers need.
                 self._gguf_path = model_path
                 self._hf_repo = hf_repo
                 # For local GGUF files, extract variant from filename if absent
@@ -3326,9 +3205,8 @@ class LlamaCppBackend:
                 self._is_vision = effective_is_vision
                 self._model_identifier = model_identifier
 
-                # Store the effective (possibly capped) context separately. Do
-                # NOT overwrite _context_length -- it holds the native context
-                # length from GGUF metadata, used for display/info.
+                # Store the effective (possibly capped) context separately; do
+                # NOT overwrite _context_length (the native length for display).
                 self._effective_context_length = (
                     effective_ctx if effective_ctx > 0 else self._context_length
                 )
@@ -3349,11 +3227,10 @@ class LlamaCppBackend:
 
                 self._healthy = True
 
-                # Commit caller intent only after _healthy=True so a failed
-                # startup can't poison the next inheritance check. None keeps
-                # prior, [] clears, list sets. Source records the caller's
-                # hf_variant (None for local files) so the route's same_source
-                # check stays symmetric.
+                # Commit caller intent only after _healthy=True so a failed start
+                # can't poison the next inheritance check. None keeps prior, []
+                # clears, list sets. Source records hf_variant for the route's
+                # same_source check.
                 if extra_args is not None:
                     self._extra_args = list(extra_args)
                     self._extra_args_source = (model_identifier, hf_variant)
@@ -3454,6 +3331,10 @@ class LlamaCppBackend:
           gpt-oss-120b code refactor      | 181 t/s | 446 t/s | 2.5x
           Qwen3-235B offloaded            |  12 t/s |  21 t/s | 1.8x
           gpt-oss-120b repeat (92% accept)| 181 t/s | 814 t/s | 4.5x
+        Refs: https://github.com/ggml-org/llama.cpp/blob/master/docs/speculative.md
+              https://github.com/ggml-org/llama.cpp/pull/19164
+              https://github.com/ggml-org/llama.cpp/pull/18471
+              MTP guide: unsloth.ai/docs/models/qwen3.6#mtp-guide
 
         Sub-3B dense MTP regresses vs spec-off: the draft head's per-token
         cost exceeds the acceptance savings at this scale. Q4_K_XL clean
@@ -3472,10 +3353,8 @@ class LlamaCppBackend:
         self._spec_draft_n_max = None
         self._speculative_type = None
 
-        # Canonical UI-facing requested mode: auto / mtp / ngram /
-        # mtp+ngram / off / ngram-simple. Legacy values mapped via
-        # _canonicalize_spec_mode (default->auto, draft-mtp->mtp,
-        # ngram-mod->ngram, "ngram-mod,draft-mtp"->mtp+ngram).
+        # Canonical UI-facing requested mode (legacy values mapped via
+        # _canonicalize_spec_mode).
         canonical_mode = _canonicalize_spec_mode(speculative_type)
         is_mtp_model = bool(self._nextn_predict_layers) or (
             _is_mtp_model_name(model_identifier, model_path)
@@ -3485,9 +3364,8 @@ class LlamaCppBackend:
         _mtp_too_small = _mtp_size_b is not None and _mtp_size_b < 3.0
 
         if user_owns_spec_type:
-            # User --spec-type in extra_args wins outright; suppress
-            # auto-emit to avoid a duplicate / conflicting spec block.
-            # Record requested mode as None.
+            # User --spec-type wins outright; suppress auto-emit to avoid a
+            # duplicate spec block.
             self._requested_spec_mode = None
             return flags
 
@@ -3685,10 +3563,8 @@ class LlamaCppBackend:
         if _norm(self._cache_type_kv) != _norm(cache_type_kv):
             return False
 
-        # Compare on the canonical UI-facing requested mode. When extra_args
-        # carries --spec-type, the route layer bypasses the dropdown and the
-        # backend stores _requested_spec_mode = None; the request mirrors
-        # that by canonicalising to None.
+        # Compare on the canonical requested mode. With --spec-type in
+        # extra_args the backend stores None; mirror that here.
         if _extra_args_set_spec_type(extra_args):
             req_mode = None
         else:
@@ -3697,10 +3573,9 @@ class LlamaCppBackend:
         if req_mode != backend_mode:
             return False
 
-        # spec_draft_n_max only matters when an MTP variant is engaged.
-        # Compare on the resolved spec, not the requested mode, so an Auto
-        # request that auto-promoted to draft-mtp still bounces a reload
-        # when the user changes n_max.
+        # spec_draft_n_max only matters when an MTP variant is engaged. Compare
+        # on the resolved spec so an Auto request promoted to draft-mtp still
+        # bounces a reload when n_max changes.
         if (
             self._speculative_type == "draft-mtp"
             and spec_draft_n_max is not None
@@ -3727,9 +3602,8 @@ class LlamaCppBackend:
         GPU detected, no buffer-size lines, etc.)."""
         if not detected_gpus or not expected_gpu:
             return None
-        # llama-server logs one ``... model buffer size = N MiB`` line per
-        # backend buffer; CUDA0 / ROCm0 / Metal / Vulkan0 / OpenCL0 / SYCL0
-        # are GPU, CPU / CPU_Mapped are not.
+        # llama-server logs one "model buffer size = N MiB" line per backend
+        # buffer; CUDA/ROCm/Metal/Vulkan/OpenCL/SYCL are GPU, CPU* are not.
         gpu_markers = ("CUDA", "ROCm", "Metal", "Vulkan", "OpenCL", "SYCL")
         saw_buffer_line = False
         saw_gpu_buffer = False
@@ -3828,13 +3702,11 @@ class LlamaCppBackend:
             logger.warning(f"Error killing llama-server process: {e}")
         finally:
             self._process = None
-            # Clear healthy so a /load arriving during the replacement
-            # server's warm-up window can't short-circuit against the
-            # previous server's health (#5401).
+            # Clear healthy so a /load during the replacement's warm-up can't
+            # short-circuit against the previous server's health (#5401).
             self._healthy = False
-            # Drives _wait_for_vram_settle in the next load_model; set in
-            # finally so both in-process and frontend /unload+/load Apply
-            # paths record the kill.
+            # Drives _wait_for_vram_settle in the next load_model; set in finally
+            # so both in-process and frontend Apply paths record the kill.
             self._last_kill_monotonic = time.monotonic()
             if self._stdout_thread is not None:
                 self._stdout_thread.join(timeout = 2)
@@ -3863,10 +3735,8 @@ class LlamaCppBackend:
         """
         try:
             # -- Build the ownership allowlist --------------------------------
-            # Two match kinds:
-            #   exact_binaries  -- env var overrides (exact path match only)
-            #   install_roots   -- Studio-owned dir trees (binary must be
-            #                      *under* one of these)
+            # exact_binaries -- env var overrides (exact path match).
+            # install_roots  -- Studio-owned dir trees (binary must be under one).
             install_roots: list[Path] = []
 
             # Env-mode custom root (mirrors _find_llama_server_binary).
@@ -3885,9 +3755,8 @@ class LlamaCppBackend:
             except (ImportError, OSError, ValueError):
                 pass
 
-            # Primary install dir (default mode only). Env-mode skips this so
-            # a custom-root Studio can't kill a concurrent default-install
-            # Studio's llama-server (same OS user, different install).
+            # Primary install dir (default mode only). Env-mode skips this so a
+            # custom-root Studio can't kill a default-install Studio's server.
             if not _is_custom_root:
                 install_roots.append(Path.home() / ".unsloth" / "llama.cpp")
 
@@ -3947,8 +3816,7 @@ class LlamaCppBackend:
 
                         exe_path = Path(exe).resolve()
 
-                        # Ownership: exact binary match OR binary under a
-                        # known install root (proper ancestry, not substring).
+                        # Ownership: exact match OR binary under a known root.
                         is_ours = exe_path in exact_binaries or any(
                             exe_path.is_relative_to(root) for root in resolved_roots
                         )
@@ -3987,10 +3855,9 @@ class LlamaCppBackend:
                     if pid == my_pid:
                         continue
 
-                    # Resolve the actual executable. /proc/<pid>/exe is a
-                    # symlink to the real binary and avoids cmdline-parsing
-                    # ambiguities (spaces in paths, argv rewriting). Fall back
-                    # to the first cmdline token when /proc is unavailable.
+                    # /proc/<pid>/exe symlinks the real binary, avoiding
+                    # cmdline-parsing ambiguities; fall back to the first
+                    # cmdline token when /proc is unavailable.
                     proc_exe = Path(f"/proc/{pid}/exe")
                     try:
                         binary = proc_exe.resolve(strict = True)
@@ -4026,11 +3893,7 @@ class LlamaCppBackend:
         timeout: float = 120.0,
         interval: float = 0.5,
     ) -> bool:
-        """
-        Poll llama-server's /health endpoint until it responds 200.
-
-        Also monitors the subprocess for early exit/crash.
-        """
+        """Poll llama-server's /health until 200; also detect early exit/crash."""
         deadline = time.monotonic() + timeout
         url = f"http://127.0.0.1:{self._port}/health"
 
@@ -4054,10 +3917,8 @@ class LlamaCppBackend:
             except (
                 httpx.ConnectError,
                 httpx.TimeoutException,
-                # ReadError covers TCP RST mid-read while llama-server is
-                # still binding the port (Windows: WinError 10054). The
-                # crash branch above catches a real exit; this keeps a
-                # transient socket close from masking it.
+                # ReadError covers TCP RST mid-read while still binding the port
+                # (Windows: WinError 10054); the crash branch catches real exits.
                 httpx.ReadError,
                 httpx.RemoteProtocolError,
                 httpx.WriteError,
@@ -4079,12 +3940,8 @@ class LlamaCppBackend:
 
     @staticmethod
     def _build_openai_messages(messages: list[dict], image_b64: Optional[str] = None) -> list[dict]:
-        """
-        Build OpenAI-format messages, optionally injecting an image_url
-        content part into the last user message for vision models.
-
-        Returns messages as-is if no image is provided.
-        """
+        """Build OpenAI-format messages, optionally injecting an image_url part
+        into the last user message for vision models. As-is if no image."""
         if not image_b64:
             return messages
 
@@ -4115,13 +3972,10 @@ class LlamaCppBackend:
     def _iter_text_cancellable(
         response: "httpx.Response", cancel_event: Optional[threading.Event] = None
     ) -> Generator[str, None, None]:
-        """Iterate over an httpx streaming response with cancel support.
+        """Iterate an httpx streaming response with cancel support.
 
-        Checks cancel_event between chunks and on ReadTimeout. The cancel
-        watcher in _stream_with_retry also calls response.close() on cancel,
-        unblocking iter_text() once the response exists. During normal
-        streaming llama-server sends tokens frequently, so the between-chunk
-        check is the primary mechanism.
+        Checks cancel_event between chunks and on ReadTimeout; the
+        _stream_with_retry watcher also closes the response on cancel.
         """
         text_iter = response.iter_text()
         while True:
@@ -4149,18 +4003,11 @@ class LlamaCppBackend:
     ):
         """Open an httpx streaming POST with cancel support.
 
-        Sends the request once with a long read timeout (120 s) so prefill
-        (prompt processing) can finish without a retry storm. The previous
-        0.5 s timeout caused duplicate POSTs every half second, forcing
-        llama-server to restart processing each time.
-
-        A background watcher thread cancels by closing the response when
-        cancel_event is set. Limitation: httpx can't interrupt a blocked
-        read from another thread before the response object exists, so
-        cancel during the initial header wait (prefill) only takes effect
-        once headers arrive; after that response.close() unblocks reads
-        promptly. Prefill is 1-5 s for typical prompts, during which cancel
-        is deferred -- still much better than the old retry storm.
+        Sends once with a long read timeout (120 s) so prefill finishes without
+        a retry storm (the old 0.5 s timeout caused duplicate POSTs every half
+        second). A watcher thread cancels by closing the response. httpx can't
+        interrupt a blocked read before the response exists, so cancel during
+        the header wait (1-5 s prefill) is deferred until headers arrive.
         """
         if cancel_event is not None and cancel_event.is_set():
             raise GeneratorExit
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index 9d11157bf9..66c7f10d42 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -72,10 +72,9 @@ _DENYLIST: frozenset[str] = frozenset().union(*_DENYLIST_GROUPS)
 def _flag_name(token: str) -> Optional[str]:
     """Flag name for ``token``, or None if it isn't a flag.
 
-    Peels `--key=value` to `--key`, treats `-1` / `-0.5` as values
-    (llama-server shorts always start with a letter), strips whitespace, and
-    normalises attached `-np8` / signed `-np-1` / digit-prefix-junk `-np8x`
-    to `-np`. Mirrors the CLI's `_expand_attached_np_short`.
+    Peels `--key=value` to `--key`, treats `-1`/`-0.5` as values (shorts
+    always start with a letter), and normalises attached `-np8` / `-np-1` /
+    `-np8x` to `-np`. Mirrors the CLI's `_expand_attached_np_short`.
     """
     token = token.strip()
     if not token.startswith("-") or token in {"-", "--"}:
@@ -162,8 +161,8 @@ _BOOLEAN_SHADOWING_FLAGS: frozenset[str] = frozenset({"--spec-default", "--jinja
 def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
     """Return the last user-supplied ``-c`` / ``--ctx-size`` value.
 
-    Mirrors llama.cpp's last-wins parsing for the one pass-through numeric
-    knob Studio's load-time fit logic needs to see.
+    Mirrors llama.cpp's last-wins parsing for the one numeric knob Studio's
+    load-time fit logic needs.
     """
     if not args:
         return None
@@ -201,10 +200,8 @@ def parse_ctx_override(args: Optional[Iterable[str]]) -> Optional[int]:
 def resolve_requested_ctx(args: Optional[Iterable[str]], fallback_n_ctx: int) -> int:
     """Return the context size load_model should treat as requested.
 
-    Single source of truth for the ``ctx_override = parse_ctx_override(...);
-    requested_ctx = ctx_override if ctx_override is not None else n_ctx``
-    pattern used by ``load_model``, so tests don't reimplement the
-    conditional and assert against their own reimplementation.
+    Single source of truth for load_model's ctx-override conditional so
+    tests don't reimplement and assert against their own logic.
     """
     override = parse_ctx_override(args)
     return override if override is not None else fallback_n_ctx
@@ -213,10 +210,8 @@ def resolve_requested_ctx(args: Optional[Iterable[str]], fallback_n_ctx: int) ->
 def parse_cache_override(args: Optional[Iterable[str]]) -> Optional[str]:
     """Return the last-wins cache type if extras pass cache flags.
 
-    Like parse_ctx_override but for cache type. Recognises -ctk (key) and
-    -ctv (value); when both appear, returns the last-wins value, treating
-    key and value flags as one setting because Studio's KV estimate has a
-    single cache_type_kv knob.
+    Recognises -ctk (key) and -ctv (value); treats both as one setting,
+    since Studio's KV estimate has a single cache_type_kv knob.
     """
     if not args:
         return None
@@ -271,8 +266,7 @@ def strip_shadowing_flags(
 
     Used when inheriting a previous load's ``llama_extra_args`` so an
     inherited `-c 4096` can't override the current `max_seq_length` (same for
-    cache / spec / template). Each ``strip_*`` toggle controls one group; the
-    route only strips groups whose first-class field the caller supplied.
+    cache / spec / template). Each ``strip_*`` toggle controls one group.
     """
     shadowing: set[str] = set()
     if strip_context:
diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index d1a565b232..9a7fd1f074 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -31,20 +31,17 @@ def parse_stdio_command(address: str) -> list[str]:
     posix = sys.platform != "win32"
     parts = shlex.split(address, posix = posix)
     if not posix:
-        # posix=False keeps backslash paths intact but also keeps surrounding
-        # quotes on a token. Strip a matched pair so argv reaches the subprocess
-        # clean ('"C:\\Program Files\\node"' -> C:\\Program Files\\node).
+        # posix=False keeps backslash paths but also keeps surrounding quotes;
+        # strip a matched pair so argv reaches the subprocess clean.
         parts = [p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p for p in parts]
     return parts
 
 
 def stdio_mcp_enabled() -> bool:
-    """stdio MCP servers spawn local processes as the backend user (bypassing
-    the python/terminal sandbox), so they're allowed only when the backend host
-    is the user's own machine. The Tauri desktop app sets
-    UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 (see main.py); advanced localhost /
-    self-hosted users can opt in with the same variable. Stays off for Colab
-    and any network (0.0.0.0) bind."""
+    """stdio MCP servers spawn local processes as the backend user (bypassing the
+    sandbox), so allowed only when the host is the user's own machine. The Tauri
+    app sets UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1; localhost/self-hosted users can opt
+    in with the same var. Off for Colab and any network (0.0.0.0) bind."""
     return os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") == "1"
 
 
@@ -82,8 +79,8 @@ def _oauth_store():
         from key_value.aio.stores.filetree import FileTreeStore
         from utils.paths.storage_roots import ensure_dir, studio_root
 
-        # Hash keys/collections — fastmcp uses raw URLs like https://x.com as
-        # keys, and FileTreeStore would treat the "://" as nested directories.
+        # Hash keys/collections — fastmcp uses raw URLs as keys, and FileTreeStore
+        # would treat the "://" as nested directories.
         _oauth_token_store = FileTreeStore(
             data_directory = ensure_dir(studio_root() / "mcp-oauth-tokens"),
             key_sanitization_strategy = AlwaysHashStrategy(),
@@ -94,10 +91,9 @@ def _oauth_store():
 
 async def clear_oauth_tokens_async(url: str) -> None:
     """Drop any persisted OAuth tokens for ``url``. fastmcp keys tokens by MCP
-    URL, so on server delete / URL change / OAuth disable we must clear old
-    credentials explicitly; otherwise re-registering the same URL silently
-    reuses the old account's token. The whole body is protected -- store / OAuth
-    construction failing must not 500 the delete / update route."""
+    URL, so on server delete / URL change / OAuth disable we must clear them, else
+    re-registering the same URL reuses the old account's token. Best-effort: store
+    / OAuth failures must not 500 the delete / update route."""
     try:
         from fastmcp.client.auth import OAuth
         auth = OAuth(mcp_url = url, token_storage = _oauth_store())
@@ -123,9 +119,8 @@ def _client(
         parts = parse_stdio_command(url)
         if not parts:
             raise ValueError(f"Empty stdio command: {url!r}")
-        # env vars ride the headers field (merged over the SDK's safe default
-        # env). keep_alive=False tears the subprocess down on exit, so a
-        # one-shot probe/tool call never leaves an orphan.
+        # env vars ride the headers field (merged over the SDK default env).
+        # keep_alive=False tears the subprocess down so a one-shot call leaves no orphan.
         return Client(
             StdioTransport(
                 command = parts[0],
@@ -191,10 +186,9 @@ def call_tool_sync(
 ) -> str:
     """Synchronously call an MCP tool.
 
-    ``cancel_event``: optional ``threading.Event``. When set, the in-flight HTTP
-    call is cancelled and a cancellation Error is returned. Polled in parallel
-    with the tool call via ``asyncio.wait`` so a /cancel POST from the UI
-    interrupts even mid-network-read.
+    ``cancel_event``: optional ``threading.Event``. When set, the in-flight call is
+    cancelled and a cancellation Error returned. Polled alongside the tool call via
+    ``asyncio.wait`` so a /cancel POST interrupts even mid-network-read.
     """
 
     async def _call() -> Any:
@@ -209,8 +203,7 @@ def call_tool_sync(
 
     async def _race() -> Any:
         # Check cancellation before spawning the call task so a pre-set event
-        # short-circuits before opening the transport / HTTP connection
-        # (reviewer-reproduced race).
+        # short-circuits before opening the transport / HTTP connection.
         if cancel_event is not None and cancel_event.is_set():
             raise _MCPCancelled
         call_task = asyncio.create_task(_call())
diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index 31bca0f5d6..fbbdb9a773 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -13,8 +13,7 @@ logger = get_logger(__name__)
 
 
 def _build_generation_stats(prompt_n, prompt_tps, gen_n, gen_tps):
-    """Map mlx_lm / mlx_vlm stream stats onto the usage/timings shape
-    llama-server emits so the chat speed popover renders the same."""
+    """Map mlx stream stats onto the usage/timings shape llama-server emits."""
     prompt_n = int(prompt_n or 0)
     gen_n = int(gen_n or 0)
     prompt_tps = float(prompt_tps or 0.0)
@@ -52,7 +51,6 @@ class MLXInferenceBackend:
         # usage/timings of the latest generation; shipped on gen_done.
         self.last_generation_stats = None
 
-        # MLX state
         self._model = None
         self._tokenizer = None
         self._processor = None
@@ -65,8 +63,7 @@ class MLXInferenceBackend:
     def _configure_memory_limits(self):
         """Apply Metal memory caps before loading a model.
 
-        Mirrors MLXTrainer._configure_memory_limits defaults:
-        memory_limit = 85% of recommended working-set,
+        memory_limit = 85% of recommended working-set;
         wired_limit = min(recommended, memory_limit). Recorded so unload can
         lower wired_limit back to release pinned RAM.
         """
@@ -109,16 +106,10 @@ class MLXInferenceBackend:
         model_name = config.identifier if hasattr(config, "identifier") else str(config)
         is_vision = getattr(config, "is_vision", False)
 
-        # GGUF guard. GGUF models are served via llama-server in the parent
-        # process, NOT via mlx-lm in this MLX subprocess. The route at
-        # studio/backend/routes/inference.py:592 (`if config.is_gguf:`) sends
-        # GGUF traffic to llama-server before reaching the MLX orchestrator.
-        # Reaching here with is_gguf=True means the route's
-        # `detect_gguf_model_remote` returned None on its first call (transient
-        # HF Hub flake) but the subprocess re-detection succeeded. The
-        # subprocess can't reach the parent's llama-server, so raise loudly to
-        # give the caller a clear error instead of a cryptic "config.json does
-        # not exist" from mlx_lm.utils.load_model.
+        # GGUF guard. GGUF models are served by llama-server in the parent
+        # process, not mlx-lm here. Reaching this with is_gguf=True means the
+        # route's first detection flaked (transient HF Hub) but the subprocess
+        # re-detected GGUF; raise loudly instead of a cryptic mlx_lm error.
         if getattr(config, "is_gguf", False):
             raise RuntimeError(
                 f"MLXInferenceBackend cannot load GGUF model '{model_name}': "
@@ -185,9 +176,8 @@ class MLXInferenceBackend:
             "audio_type": None,
             "has_audio_input": False,
         }
-        # Capture chat_template_info so the worker IPC reply can ship it back
-        # to the parent and the route layer classifies capabilities the same
-        # way as the transformers / GGUF paths.
+        # Capture chat_template_info so the worker IPC reply ships it back and
+        # the route layer classifies capabilities like the other paths.
         self._populate_chat_template_info(model_name)
 
         logger.info("Model %s loaded successfully", model_name)
@@ -197,8 +187,7 @@ class MLXInferenceBackend:
         """Mirror InferenceBackend._load_chat_template_info for MLX.
 
         Stores ``chat_template_info`` on ``self.models[model_name]`` with the
-        resolved ``tokenizer.chat_template`` so ``_detect_safetensors_features``
-        (route layer) sees the template the model actually uses."""
+        resolved ``tokenizer.chat_template``."""
         entry = self.models.get(model_name)
         if not entry:
             return
@@ -273,9 +262,8 @@ class MLXInferenceBackend:
         max_new_tokens = 256,
         repetition_penalty = 1.0,
         cancel_event = None,
-        # Reasoning / tool kwargs forwarded by the route + worker -- the MLX
-        # path renders the template via apply_chat_template_for_generation so
-        # these are honoured the same way as the transformers path.
+        # Reasoning / tool kwargs forwarded by the route + worker; rendered via
+        # apply_chat_template_for_generation like the transformers path.
         tools = None,
         enable_thinking = None,
         reasoning_effort = None,
@@ -385,8 +373,7 @@ class MLXInferenceBackend:
             min_p = float(min_p or 0.0),
             min_tokens_to_keep = 1,
         )
-        # Only build a logits processor for a non-trivial repetition penalty
-        # (1.0 is the no-op value).
+        # Only build a logits processor for a non-trivial repetition penalty.
         logits_processors = None
         if repetition_penalty is not None and float(repetition_penalty) not in (
             0.0,
@@ -421,7 +408,7 @@ class MLXInferenceBackend:
                 ):
                     final_response = response
                     token_ids.append(response.token)
-                    # Decode full sequence with skip_special_tokens — like GPU
+                    # Decode full sequence with skip_special_tokens
                     cumulative = self._tokenizer.decode(
                         token_ids,
                         skip_special_tokens = True,
@@ -467,9 +454,9 @@ class MLXInferenceBackend:
             apply_chat_template_for_generation,
         )
 
-        # Pick the chat-template-aware caller: processors that expose their own
-        # apply_chat_template + chat_template attr (e.g. Qwen2.5-VL) use it
-        # directly; otherwise fall back to the nested tokenizer.
+        # Pick the chat-template-aware caller: processors with their own
+        # apply_chat_template + chat_template (e.g. Qwen2.5-VL) use it
+        # directly; else fall back to the nested tokenizer.
         chat_target = self._processor
         if (
             getattr(self._processor, "apply_chat_template", None) is None
@@ -487,8 +474,7 @@ class MLXInferenceBackend:
             preserve_thinking = preserve_thinking,
         )
 
-        # For VLM: always use mlx_vlm's stream_generate, which handles
-        # pixel_values properly (None for text-only, image for VLM)
+        # mlx_vlm's stream_generate handles pixel_values (None for text-only)
         images = [image] if image is not None else None
 
         cumulative = ""
@@ -498,11 +484,9 @@ class MLXInferenceBackend:
             image is not None,
         )
         # mlx_vlm.stream_generate forwards **kwargs into generate_step, which
-        # accepts temp/top_p/top_k/repetition_penalty (building the sampler +
-        # logits_processors internally). Pass them through.
-        # NOTE: mlx_vlm.generate_step expects ``temperature=`` (long form) —
-        # passing ``temp=`` silently falls into **kwargs and is ignored,
-        # leaving generation stuck at the default 0.0 (greedy).
+        # builds the sampler + logits_processors internally.
+        # GOTCHA: generate_step expects ``temperature=`` (long form); ``temp=``
+        # silently falls into **kwargs and is ignored, stuck at greedy 0.0.
         vlm_kwargs = dict(
             max_tokens = max_new_tokens,
             temperature = temperature,
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index d7fc1ef9a6..0cbdea1337 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -59,16 +59,15 @@ class InferenceOrchestrator:
         self._proc: Optional[mp.Process] = None
         self._cmd_queue: Any = None
         self._resp_queue: Any = None
-        self._cancel_event: Any = None  # mp.Event — set to cancel generation instantly
+        self._cancel_event: Any = None  # mp.Event — set to cancel generation
         self._lock = threading.Lock()
-        self._gen_lock = threading.Lock()  # Serializes generation — one request at a time
+        self._gen_lock = threading.Lock()  # Serializes generation
 
-        # Dispatcher state — for compare mode (adapter-controlled requests).
-        # These bypass _gen_lock: they send commands directly and read from
-        # per-request mailboxes. A dispatcher thread routes resp_queue events
-        # by request_id.
+        # Dispatcher state for compare mode (adapter-controlled requests):
+        # bypass _gen_lock, send commands directly, read from per-request
+        # mailboxes routed by a dispatcher thread on request_id.
         self._mailboxes: dict[str, queue.Queue] = {}
-        self._mailbox_lock = threading.Lock()  # Protects _mailboxes dict
+        self._mailbox_lock = threading.Lock()
         self._dispatcher_thread: Optional[threading.Thread] = None
         self._dispatcher_stop = threading.Event()
 
@@ -84,13 +83,11 @@ class InferenceOrchestrator:
         self._top_hub_cache: Optional[list[str]] = None
         self._top_models_ready = threading.Event()
 
-        # Version tracking for subprocess reuse
         self._current_transformers_major: Optional[str] = None  # "4" or "5"
 
         atexit.register(self._cleanup)
         logger.info("InferenceOrchestrator initialized (subprocess mode)")
 
-        # Background fetch of top models from HF
         threading.Thread(target = self._fetch_top_models, daemon = True, name = "top-models").start()
 
     # ------------------------------------------------------------------
@@ -99,13 +96,13 @@ class InferenceOrchestrator:
 
     @property
     def default_models(self) -> list[str]:
-        # Wait up to 5s for background HF fetch to finish
+        # Wait up to 5s for background HF fetch
         self._top_models_ready.wait(timeout = 5)
         top_gguf = self._top_gguf_cache or []
         top_hub = self._top_hub_cache or []
-        # Curated static defaults first (editorial picks), then HF
-        # download-ranked models to backfill. Send extras so the frontend
-        # still has 4 per category after removing downloaded ones.
+        # Curated static defaults first, then HF download-ranked to backfill.
+        # Send extras so the frontend keeps 4 per category after removing
+        # downloaded ones.
         result: list[str] = []
         seen: set[str] = set()
         for m in self._static_models + top_gguf + top_hub:
@@ -130,8 +127,7 @@ class InferenceOrchestrator:
             )
             if resp.status_code == 200:
                 models = resp.json()
-                # Top 40 GGUFs - frontend pages through them via infinite
-                # scroll, so send a deep pool.
+                # Top 40 GGUFs (deep pool for frontend infinite scroll)
                 gguf_ids = [m["id"] for m in models if m.get("id", "").upper().endswith("-GGUF")][
                     :40
                 ]
@@ -189,14 +185,14 @@ class InferenceOrchestrator:
 
     def _shutdown_subprocess(self, timeout: float = 10.0) -> None:
         """Gracefully shut down the inference subprocess."""
-        self._stop_dispatcher()  # Stop dispatcher before killing subprocess
+        self._stop_dispatcher()  # before killing subprocess
         if self._proc is None or not self._proc.is_alive():
             self._proc = None
             return
 
         # 1. Cancel any ongoing generation first (instant via mp.Event)
         self._cancel_generation()
-        time.sleep(0.5)  # Brief wait for generation to stop
+        time.sleep(0.5)
 
         # 2. Drain stale responses
         self._drain_queue()
@@ -416,8 +412,8 @@ class InferenceOrchestrator:
                     mbox.put(resp)
                     continue
 
-            # No matching mailbox — maybe for a _gen_lock reader or orphaned.
-            # Can't un-get from mp.Queue, so just log a warning.
+            # No matching mailbox (a _gen_lock reader or orphaned). Can't
+            # un-get from mp.Queue, so just log.
             if rtype not in ("status",):
                 logger.debug(
                     "Dispatcher: no mailbox for request_id=%s type=%s, dropping",
@@ -446,13 +442,9 @@ class InferenceOrchestrator:
     ) -> Generator[str, None, None]:
         """Dispatched generation — sends command without holding _gen_lock.
 
-        Uses a per-request mailbox for tokens, so two compare-mode requests
-        can be queued in the subprocess at once, avoiding the
-        inter-generation round-trip overhead.
-
-        The subprocess runs commands sequentially from its cmd_queue, so
-        generation stays serialized at the GPU level — this only avoids
-        orchestrator-level lock contention.
+        Uses a per-request mailbox for tokens so two compare-mode requests can
+        be queued at once. The subprocess still runs commands sequentially, so
+        GPU work stays serialized; this only avoids orchestrator lock contention.
         """
         if not self._ensure_subprocess_alive():
             yield "Error: Inference subprocess is not running"
@@ -528,7 +520,6 @@ class InferenceOrchestrator:
                     # Cancel from route (e.g. SSE connection closed)
                     if cancel_event is not None and cancel_event.is_set():
                         self._cancel_generation()
-                        # Drain remaining events for this request
                         self._drain_mailbox(mailbox, timeout = 5.0)
                         return
                     yield resp.get("text", "")
@@ -611,9 +602,8 @@ class InferenceOrchestrator:
     ) -> bool:
         """Load a model for inference.
 
-        Always spawns a fresh subprocess per load for a clean interpreter —
-        no stale unsloth patches, torch.compile caches, or
-        inspect.getsource() failures from a previous model.
+        Always spawns a fresh subprocess per load for a clean interpreter (no
+        stale unsloth patches, torch.compile caches, or getsource failures).
         """
         from utils.transformers_version import needs_transformers_5
 
@@ -643,15 +633,13 @@ class InferenceOrchestrator:
             sub_config["gpu_selection"] = gpu_selection
 
             # Always kill the existing subprocess and spawn fresh: reusing one
-            # after unsloth patches torch internals causes
-            # inspect.getsource() failures on the next load.
+            # after unsloth patches torch internals breaks getsource on reload.
             if self._ensure_subprocess_alive():
                 self._cancel_generation()
                 time.sleep(0.3)
                 self._shutdown_subprocess()
 
             elif self._proc is not None:
-                # Dead subprocess — clean up
                 self._shutdown_subprocess(timeout = 2)
 
             disable_xet = sub_config.get("disable_xet", False) or (
@@ -673,7 +661,7 @@ class InferenceOrchestrator:
                 try:
                     resp = self._wait_response("loaded")
                 except DownloadStallError:
-                    # First stall with Xet enabled -> retry with Xet disabled
+                    # First stall with Xet on -> retry with Xet disabled
                     if attempt == 0 and not disable_xet:
                         logger.warning(
                             "Download stalled for '%s' -- retrying with HF_HUB_DISABLE_XET=1",
@@ -682,14 +670,13 @@ class InferenceOrchestrator:
                         self._shutdown_subprocess(timeout = 5)
                         disable_xet = True
                         continue
-                    # Second stall (or xet already disabled) -> give up
+                    # Second stall (or xet already off) -> give up
                     self._shutdown_subprocess(timeout = 5)
                     raise RuntimeError(
                         f"Download stalled for '{model_name}' even with "
                         f"HF_HUB_DISABLE_XET=1 -- check your network connection"
                     )
 
-                # Got a response — check success
                 if resp.get("success"):
                     self._current_transformers_major = needed_major
                     model_info = resp.get("model_info", {})
@@ -703,8 +690,8 @@ class InferenceOrchestrator:
                         "audio_type": model_info.get("audio_type"),
                         "has_audio_input": model_info.get("has_audio_input", False),
                     }
-                    # Mirror chat_template_info so routes can classify
-                    # capabilities without re-entering the subprocess.
+                    # Mirror chat_template_info so routes can classify caps
+                    # without re-entering the subprocess.
                     _tpl_info = model_info.get("chat_template_info")
                     if isinstance(_tpl_info, dict):
                         self.models[self.active_model_name]["chat_template_info"] = _tpl_info
@@ -789,14 +776,12 @@ class InferenceOrchestrator:
     ) -> Generator[str, None, None]:
         """Generate response, streaming tokens from subprocess.
 
-        Optional ``tools`` / ``enable_thinking`` / ``reasoning_effort`` /
-        ``preserve_thinking`` kwargs are forwarded to the worker so
-        ``tokenizer.apply_chat_template`` can render tool schemas and
-        reasoning controls when the template supports them.
+        ``tools`` / ``enable_thinking`` / ``reasoning_effort`` /
+        ``preserve_thinking`` are forwarded so the template can render tool
+        schemas and reasoning controls.
 
         ``stats_holder``: caller-owned dict; on gen_done its "stats" key gets
-        the worker's usage/timings. Request-scoped so concurrent streams cannot
-        read each other's stats.
+        the worker's usage/timings. Request-scoped to avoid cross-stream reads.
         """
         yield from self._generate_inner(
             messages = messages,
@@ -840,12 +825,11 @@ class InferenceOrchestrator:
         stats_holder: Optional[dict] = None,
         **_unused,
     ):
-        """Run the safetensors agentic tool loop in this (parent) process,
-        calling the worker for each generation turn.
+        """Run the safetensors agentic tool loop in the parent process,
+        calling the worker for each turn.
 
         Yields the same event dicts as the GGUF tool loop so the route layer
-        can stream both backends through one helper. See
-        ``safetensors_agentic.run_safetensors_tool_loop`` for the protocol.
+        can stream both backends through one helper.
         """
         from core.inference.safetensors_agentic import run_safetensors_tool_loop
         from core.inference.tools import execute_tool
@@ -853,8 +837,7 @@ class InferenceOrchestrator:
         max_new_tokens = max_tokens if max_tokens and max_tokens > 0 else 2048
 
         def _single_turn(conv: list):
-            # ``conv`` already carries any system message: the loop appends
-            # to a list seeded with system+user above.
+            # ``conv`` already carries any system message.
             common_kwargs = dict(
                 messages = conv,
                 system_prompt = "",
@@ -870,7 +853,7 @@ class InferenceOrchestrator:
                 enable_thinking = enable_thinking,
                 reasoning_effort = reasoning_effort,
                 preserve_thinking = preserve_thinking,
-                # last turn wins, same as the GGUF tool loop's metadata
+                # last turn wins, like the GGUF tool loop
                 stats_holder = stats_holder,
             )
             if use_adapter is not None:
@@ -949,14 +932,11 @@ class InferenceOrchestrator:
             yield "Error: No active model"
             return
 
-        # If the dispatcher is running (from a previous compare-mode request),
-        # wait for dispatched requests to finish then stop it, so we can read
-        # from resp_queue directly.
+        # Drain any prior compare-mode dispatcher so we can read resp_queue.
         self._wait_dispatcher_idle()
 
-        # Serialize generation — single GPU, one generation at a time. Without
-        # this lock, two concurrent readers on the same resp_queue can consume
-        # and drop each other's token events.
+        # Serialize generation: two concurrent readers on resp_queue would
+        # consume and drop each other's token events.
         with self._gen_lock:
             yield from self._generate_locked(
                 messages = messages,
@@ -1020,8 +1000,7 @@ class InferenceOrchestrator:
 
         if use_adapter is not None:
             cmd["use_adapter"] = use_adapter
-        # Only forward template kwargs the caller set, so older workers that
-        # ignore unknown keys still work.
+        # Only forward template kwargs the caller set, for older worker compat.
         if tools is not None:
             cmd["tools"] = tools
         if enable_thinking is not None:
@@ -1037,8 +1016,7 @@ class InferenceOrchestrator:
             yield f"Error: {exc}"
             return
 
-        # Yield tokens from response queue — we are the only reader since
-        # _gen_lock is held.
+        # We are the only resp_queue reader (under _gen_lock).
         while True:
             resp = self._read_resp(timeout = 30.0)
 
@@ -1065,9 +1043,8 @@ class InferenceOrchestrator:
                 # Cancel from route (e.g. SSE connection closed)
                 if cancel_event is not None and cancel_event.is_set():
                     self._cancel_generation()
-                    # Wait for the subprocess to ack cancellation
-                    # (gen_done/gen_error) so stale events don't leak into
-                    # the next generation request.
+                    # Wait for the cancel ack so stale events don't leak into
+                    # the next request.
                     self._drain_until_gen_done(timeout = 5.0)
                     return
                 yield resp.get("text", "")
@@ -1301,9 +1278,7 @@ class InferenceOrchestrator:
         img,
         max_size: int = 800,
     ):
-        """Resize image preserving aspect ratio.
-        No ML imports — runs locally in the parent process.
-        """
+        """Resize image preserving aspect ratio (runs locally, no ML imports)."""
         if img is None:
             return None
         if img.size[0] > max_size or img.size[1] > max_size:
@@ -1340,8 +1315,7 @@ class InferenceOrchestrator:
         return False
 
     def _is_gpt_oss_model(self, model_name: str = None) -> bool:
-        """Parent-side gpt-oss detection so the safetensors route can run the
-        same guard without an IPC round-trip to the subprocess."""
+        """Parent-side gpt-oss detection so the route avoids an IPC round-trip."""
         from utils.datasets import is_gpt_oss_model_name
         return is_gpt_oss_model_name(model_name or self.active_model_name or "")
 
diff --git a/studio/backend/core/inference/pricing.py b/studio/backend/core/inference/pricing.py
index efb9268170..3b611d3596 100644
--- a/studio/backend/core/inference/pricing.py
+++ b/studio/backend/core/inference/pricing.py
@@ -95,9 +95,8 @@ def _lookup(provider: str, model: str) -> Optional[dict[str, float]]:
         return None
     if model in table:
         return table[model]
-    # Longest-prefix match on a dash boundary, longest-first: dated
-    # snapshots inherit canonical prices, but "claude-opus-4-15" won't
-    # match "claude-opus-4-1" nor "gpt-5.5-prod" match "gpt-5.5-pro".
+    # Longest-prefix match on a dash boundary: dated snapshots inherit
+    # canonical prices, but "claude-opus-4-15" won't match "claude-opus-4-1".
     for key in sorted(table, key = len, reverse = True):
         if model.startswith(key) and (len(model) == len(key) or model[len(key)] == "-"):
             return table[key]
@@ -105,10 +104,9 @@ def _lookup(provider: str, model: str) -> Optional[dict[str, float]]:
 
 
 def calculate_cost(provider: str, model: str, usage: dict[str, Any]) -> dict[str, float]:
-    """Return a per-turn USD cost breakdown (per-bucket + total) so the
-    frontend renders a number or tooltip without redoing the math.
-    Unknown model -> ``priced`` False and USD fields 0.0 (token counts
-    still report).
+    """Return a per-turn USD cost breakdown (per-bucket + total).
+
+    Unknown model -> ``priced`` False and USD fields 0.0 (token counts still report).
     """
     prices = _lookup(provider, model)
     out: dict[str, float] = {
diff --git a/studio/backend/core/inference/providers.py b/studio/backend/core/inference/providers.py
index 9c98133f67..f7a2da2833 100644
--- a/studio/backend/core/inference/providers.py
+++ b/studio/backend/core/inference/providers.py
@@ -26,10 +26,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_tool_calling": True,
         "auth_header": "Authorization",
         "auth_prefix": "Bearer ",
-        # Scope the picker to the current generation. /v1/models returns
-        # dozens of historical snapshots, fine-tunes, and non-chat models
-        # (embeddings, TTS, image, moderation) we never want in the chat
-        # UI. Filter here so the backend is the single source of truth.
+        # Scope the picker to the current generation. /v1/models returns many
+        # historical snapshots, fine-tunes, and non-chat models we don't want.
         "model_id_allowlist": re.compile(r"^(gpt-5\.[345]|gpt-4\.5|o3)(?:[-.]|$)"),
         # Hide dated snapshots and the retired plain gpt-5.3 id.
         "model_id_denylist": re.compile(r"^(gpt-5\.3)$|-\d{4}-\d{2}-\d{2}$"),
@@ -45,10 +43,7 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
             "claude-sonnet-4-5",
             "claude-haiku-4-5",
         ],
-        # Anthropic /v1/models returns dated snapshot ids alongside the
-        # canonical names (e.g. claude-3-5-sonnet-20241022). Hide the
-        # YYYYMMDD-suffixed variants — same intent as the OpenAI denylist,
-        # just a different date format (no dashes).
+        # Hide YYYYMMDD-suffixed snapshot ids (e.g. claude-3-5-sonnet-20241022).
         "model_id_denylist": re.compile(r"-\d{8}$"),
         "supports_streaming": True,
         "supports_vision": True,
@@ -63,21 +58,15 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     },
     "gemini": {
         "display_name": "Google Gemini",
-        # Native Gemini REST endpoint -- the Gemini API does NOT speak
-        # OpenAI Chat Completions on this base. Requests/responses are
-        # translated in `_stream_gemini` in external_provider.py.
+        # Native Gemini REST endpoint -- does NOT speak OpenAI Chat Completions;
+        # translated in `_stream_gemini` (external_provider.py).
         # https://ai.google.dev/gemini-api/docs
         "base_url": "https://generativelanguage.googleapis.com/v1beta",
-        # Curated lineup -- live ListModels returns dozens of historical /
-        # experimental / embedding ids. Cap to current chat-capable Gemini
-        # families (3.5 / 3.1 / 3 Flash / 2.5) plus the Nano Banana image
-        # trio and the rolling `*-latest` aliases. Excluded on purpose:
-        #   - `gemini-2.0-flash*` (Google retired 2026-06-01; 404 on use)
-        #   - `gemini-3-pro-preview` (shut down 2026-03-09; auto-redirects
-        #     to `gemini-3.1-pro-preview` per Google's deprecation notice,
-        #     so we surface 3.1 directly and skip the redirect).
-        # The allowlist below keeps the retired ids from re-appearing via
-        # live ListModels. Verified against `/v1beta/models` 2026-05-24.
+        # Curated lineup (ListModels returns many historical/experimental ids).
+        # Excluded on purpose:
+        #   - `gemini-2.0-flash*` (retired 2026-06-01; 404 on use)
+        #   - `gemini-3-pro-preview` (shut down 2026-03-09; auto-redirects to
+        #     `gemini-3.1-pro-preview`, so we surface 3.1 directly).
         "default_models": [
             "gemini-3.1-pro-preview",
             "gemini-3.5-flash",
@@ -96,8 +85,7 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_streaming": True,
         "supports_vision": True,
         "supports_tool_calling": True,
-        # Native API takes the key on `x-goog-api-key`; empty `auth_prefix`
-        # sends the bare key.
+        # Native API takes the bare key on `x-goog-api-key`.
         "auth_header": "x-goog-api-key",
         "auth_prefix": "",
         "openai_compatible": False,
@@ -106,19 +94,13 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
             "API key from https://aistudio.google.com/apikey. "
             "See https://ai.google.dev/gemini-api/docs for endpoint shapes."
         ),
-        # Even after the regex match, drop ids Google still returns from
-        # ListModels but routes via implicit redirect. gemini-3-pro-preview
-        # was shut down 2026-03-09 and auto-aliased to
-        # gemini-3.1-pro-preview; surface the canonical id only so users
-        # don't see two cards for the same model.
+        # gemini-3-pro-preview was shut down 2026-03-09 and auto-aliased to
+        # gemini-3.1-pro-preview; drop it so users see one canonical card.
         "model_id_deny_exact": ("gemini-3-pro-preview",),
-        # Matches the chat-capable 3.5 / 3.1 / 3 / 2.5 families plus the
-        # rolling *-latest aliases (rolled forward as new generations ship).
-        # Image-tier ids (`-image`, `-image-preview`,
-        # `nano-banana-pro-preview`) flow through the Nano Banana
-        # `responseModalities` path in `_stream_gemini`. Retired 2.0 ids are
-        # excluded on purpose -- ListModels would re-surface them and they
-        # 404 on use.
+        # Chat-capable 3.5 / 3.1 / 3 / 2.5 families plus rolling *-latest
+        # aliases. Image-tier ids flow through the Nano Banana
+        # `responseModalities` path in `_stream_gemini`. Retired 2.0 ids
+        # excluded (they 404 on use).
         "model_id_allowlist": re.compile(
             r"^("
             r"gemini-3\.5-(?:flash|pro)(?:-preview)?|"
@@ -179,14 +161,11 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     "kimi": {
         "display_name": "Kimi",
         "base_url": "https://api.moonshot.ai/v1",
-        # Current Kimi model lineup per the official docs:
-        #   https://platform.kimi.ai/docs/models
-        # Listing/overview endpoints:
-        #   https://platform.kimi.ai/docs/api/list-models
-        #   https://platform.kimi.ai/docs/api/overview
-        # kimi-k2.6 and kimi-k2.5 are the two SoTA multimodal models we
-        # surface; everything else (moonshot-v1-*, dated k2 previews) is
-        # filtered out by model_id_allowlist below.
+        # Surface only the two SoTA multimodal models (kimi-k2.6/k2.5);
+        # moonshot-v1-* and dated k2 previews are filtered by the allowlist.
+        # Docs: https://platform.kimi.ai/docs/models
+        # Listing/overview: https://platform.kimi.ai/docs/api/list-models
+        #                   https://platform.kimi.ai/docs/api/overview
         "default_models": [
             "kimi-k2.6",
             "kimi-k2.5",
@@ -198,10 +177,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "auth_prefix": "Bearer ",
         "notes": "Moonshot API key. China: use base URL https://api.moonshot.cn/v1",
         "model_id_allowlist": re.compile(r"^kimi-k2\.[56]$"),
-        # Both k2.6 and k2.5 are reasoning-class. The API rejects custom
-        # sampling: "invalid temperature: only 1 is allowed for this model"
-        # (same for top_p). Strip both fields from the outbound body so the
-        # server falls back to its required defaults.
+        # Reasoning-class: the API rejects custom temperature/top_p ("only 1
+        # is allowed"). Strip both so the server uses its required defaults.
         "body_omit": ("temperature", "top_p"),
     },
     "qwen": {
@@ -223,9 +200,8 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     "huggingface": {
         "display_name": "Hugging Face",
         "base_url": "https://router.huggingface.co/v1",
-        # Seed the picker with popular ids so something is selectable before
-        # the live /v1/models call resolves. The remote listing is the
-        # source of truth -- see model_list_mode below.
+        # Seed the picker before the live /v1/models call resolves; the remote
+        # listing (see model_list_mode) is the source of truth.
         "default_models": [
             "openai/gpt-oss-120b",
             "deepseek-ai/DeepSeek-V3",
@@ -243,27 +219,22 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
             "returns the cross-provider chat catalog. See "
             "https://huggingface.co/docs/inference-providers/index."
         ),
-        # /v1/models works on the HF router and returns the full chat-model
-        # catalog (state.org/model[:policy] ids). Remote so users see live
-        # availability -- the picker has search, and loadModels() merges
-        # defaults so default_models stay visible if the remote call fails.
+        # Remote so users see live availability; loadModels() merges defaults
+        # so they stay visible if the remote call fails.
         "model_list_mode": "remote",
-        # Scope to first-party org repos we trust as primary sources. The HF
-        # /v1/models response is otherwise hundreds of ids long (community
-        # fine-tunes, mirrors, fp8 variants, etc.).
+        # Scope to trusted first-party org repos (the response is otherwise
+        # hundreds of community fine-tunes, mirrors, fp8 variants).
         "model_id_allowlist": re.compile(
             r"^(openai|deepseek-ai|google|meta-llama|Qwen|moonshotai|mistralai|zai-org)/"
         ),
-        # Cap the post-filter list. /v1/models has no server-side limit or
-        # popularity sort, so this is just "first N matches"; the
-        # default_models seed keeps flagship ids near the top regardless of
-        # the API's order.
+        # Cap the post-filter list to first N matches (no server-side sort);
+        # default_models keeps flagship ids near the top.
         "model_id_limit": 15,
     },
     "vllm": {
         "display_name": "vLLM",
-        # User-supplied via provider_base_url; the route layer falls back to
-        # the payload's base_url when the registry entry has none.
+        # User-supplied via provider_base_url; the route falls back to the
+        # payload's base_url when the registry entry has none.
         "base_url": "",
         "default_models": [],
         "supports_streaming": True,
@@ -271,14 +242,11 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
         "supports_tool_calling": True,
         "auth_header": "Authorization",
         "auth_prefix": "Bearer ",
-        # Force /v1/chat/completions in stream_chat_completion -- vLLM's
-        # /v1/responses rebuilds messages through the model's chat template,
-        # which 400s on strict-alternation templates (Gemma 3 raises
-        # "Conversation roles must alternate user/assistant/user/assistant
-        # /..."). The chat-completions path takes messages verbatim.
+        # Force /v1/chat/completions -- vLLM's /v1/responses rebuilds messages
+        # through the chat template, 400ing on strict-alternation templates
+        # (Gemma 3). The chat-completions path takes messages verbatim.
         "notes": "Self-hosted vLLM server. Always routed to /v1/chat/completions.",
-        # Surfaced via the frontend's CUSTOM_PROVIDER_PRESETS, not the
-        # /api/providers/registry dropdown -- see list_available_providers.
+        # Surfaced via the frontend's CUSTOM_PROVIDER_PRESETS, not the dropdown.
         "hidden": True,
     },
     "ollama": {
@@ -314,7 +282,7 @@ PROVIDER_REGISTRY: dict[str, dict[str, Any]] = {
     "openrouter": {
         "display_name": "OpenRouter",
         "base_url": "https://openrouter.ai/api/v1",
-        # Curated list for Studio's picker (explicitly locked, not live /models).
+        # Curated picker list (locked, not live /models).
         "default_models": [
             "openrouter/free",
             "openai/gpt-4o",
@@ -364,10 +332,8 @@ def get_base_url(provider_type: str) -> str | None:
 def list_available_providers() -> list[dict[str, Any]]:
     """Return all registered providers (for the /registry endpoint).
 
-    Hidden entries (``"hidden": True``) are filtered out: they exist only
-    for backend lookups (e.g. ``supports_vision`` for vLLM) and are
-    surfaced in the frontend via ``CUSTOM_PROVIDER_PRESETS`` instead of the
-    cloud-provider dropdown.
+    Hidden entries are filtered out: they exist only for backend lookups and
+    are surfaced via ``CUSTOM_PROVIDER_PRESETS`` instead of the dropdown.
     """
     result = []
     for provider_type, info in PROVIDER_REGISTRY.items():
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index 954a2b3d19..acf6bd9eda 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -4,16 +4,14 @@
 """
 Safetensors/transformers agentic tool loop.
 
-Wraps a single-turn cumulative-text generator (the
-``InferenceOrchestrator.generate_chat_response`` pipeline streaming from a
-worker subprocess) with the tool-calling, thinking-block, status, and
-metadata event protocol used by the GGUF path. The front-end SSE shape
-stays identical across backends, so the chat UI is engine-agnostic.
+Wraps a single-turn cumulative-text generator with the same tool-calling,
+thinking-block, status, and metadata event protocol the GGUF path uses, so
+the front-end SSE shape is identical across backends.
 
-The GGUF path (``llama_cpp.py``) uses llama-server's structured
-``delta.tool_calls`` directly. Native transformers has no such channel, so
-this loop parses tool calls from the cumulative text and dispatches them
-via ``core.inference.tools``.
+Unlike the GGUF path (``llama_cpp.py``), which uses llama-server's structured
+``delta.tool_calls``, native transformers has no such channel, so this loop
+parses tool calls from the cumulative text and dispatches via
+``core.inference.tools``.
 """
 
 import json
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index 1b453df0ff..601cd9f92b 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -11,11 +11,9 @@ import json
 import re
 
 
-# _TOOL_CLOSED_PATS: closed pairs only. _TOOL_ALL_PATS: also trailing
-# unclosed runs so truncated tails don't leak markup.
-# Function-name char set tracks OpenAI's ^[a-zA-Z0-9_-]{1,64}$ so hyphenated
-# MCP tool names (e.g. mcp__srv__list-issues) parse the same as built-in
-# web_search/python/terminal names.
+# _TOOL_CLOSED_PATS: closed pairs only. _TOOL_ALL_PATS: also trailing unclosed
+# runs so truncated tails don't leak markup. The [\w-] name set matches OpenAI's
+# so hyphenated MCP tool names (mcp__srv__list-issues) parse like built-ins.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
     re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
@@ -72,8 +70,7 @@ _TC_JSON_START_RE = re.compile(r"<tool_call>\s*\{")
 _TC_FUNC_START_RE = re.compile(r"<function=([\w-]+)>\s*")
 _TC_END_TAG_RE = re.compile(r"</tool_call>")
 _TC_FUNC_CLOSE_RE = re.compile(r"\s*</function>\s*$")
-# Parameter names can carry hyphens too (e.g. MCP schemas with
-# `issue-number`, `repo-name`); `\w+` alone dropped those keys.
+# [\w-] so hyphenated MCP param names (issue-number) aren't dropped.
 _TC_PARAM_START_RE = re.compile(r"<parameter=([\w-]+)>\s*")
 _TC_PARAM_CLOSE_RE = re.compile(r"\s*</parameter>\s*$")
 _PARAM_CLOSE_TAG = "</parameter>"
@@ -124,10 +121,10 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
     """
     tool_calls: list[dict] = []
 
-    # Pattern 1: <tool_call>{json}. Balanced-brace scan skipping braces
-    # inside JSON strings.
+    # Pattern 1: <tool_call>{json}. Balanced-brace scan, skipping braces in
+    # JSON strings.
     for m in _TC_JSON_START_RE.finditer(content):
-        brace_start = m.end() - 1  # position of the opening {
+        brace_start = m.end() - 1  # opening {
         depth, i = 0, brace_start
         in_string = False
         while i < len(content):
@@ -166,8 +163,7 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                 pass
 
     # Pattern 2: <function=name><parameter=k>v... -- closing tags optional;
-    # don't use </function> as body boundary since code values can contain
-    # that literal.
+    # </function> isn't a body boundary since code values can contain it.
     if not tool_calls:
         func_starts = [
             fm
@@ -190,7 +186,7 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
             arguments: dict = {}
             param_starts = list(_TC_PARAM_START_RE.finditer(body))
             if len(param_starts) == 1:
-                # Single param: take everything to body end so embedded
+                # Single param: take everything to body end so an embedded
                 # </parameter> in code strings is preserved.
                 pm = param_starts[0]
                 val = body[pm.end() :]
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index bc1897199f..023cab3e5e 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -1,11 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Tool definitions and executors for LLM tool calling.
-
-Web search (DuckDuckGo), Python code execution, and terminal commands.
-"""
+"""Tool definitions and executors for LLM tool calling: web search
+(DuckDuckGo), Python code execution, and terminal commands."""
 
 import ast
 import http.client
@@ -42,8 +39,8 @@ logger = get_logger(__name__)
 
 _EXEC_TIMEOUT = 300  # 5 minutes
 
-# Pre-import _sandbox_preexec modules at module level so the preexec_fn closure
-# doesn't trigger imports in the forked child (can deadlock multi-threaded servers).
+# Import these at module level so the preexec_fn closure triggers no imports in
+# the forked child (which can deadlock multi-threaded servers).
 _libc = None
 if sys.platform == "linux":
     try:
@@ -160,10 +157,9 @@ def _find_blocked_commands(command: str) -> set[str]:
     """
     blocked: set[str] = set()
 
-    # shlex with punctuation_chars splits `;`, `&&`, `||`, `|`, `(`, `)`, `` ` ``
-    # into their own tokens, so we detect command position even for
-    # `echo done; rm -rf x` (no whitespace) or quote-split command names
-    # (`r''m` collapses to `rm` at command position after `;`).
+    # punctuation_chars splits separators into their own tokens, so command
+    # position is detected even in `echo done; rm -rf x` (no whitespace) or
+    # quote-split names (`r''m` collapses to `rm` after `;`).
     try:
         if sys.platform == "win32":
             tokens = shlex.split(command, posix = False)
@@ -175,8 +171,7 @@ def _find_blocked_commands(command: str) -> set[str]:
         tokens = command.split()
 
     def _token_basename(tok: str) -> str:
-        # shlex may glue meta-chars onto a token (`rm;`); strip leading and
-        # trailing ones so the basename still matches `rm`.
+        # Strip glued-on meta-chars (`rm;`) so the basename still matches `rm`.
         tok = tok.strip(";&|()`{}")
         base = os.path.basename(tok).lower()
         stem, ext = os.path.splitext(base)
@@ -192,8 +187,8 @@ def _find_blocked_commands(command: str) -> set[str]:
             prefix_pending = False
             continue
         if token.startswith("-"):
-            # Flags belong to the active command. While a wrapper prefix awaits
-            # its command (`stdbuf -oL cmd`, `xargs -- cmd`), keep expect_command.
+            # Flags belong to the active command, but keep expect_command while a
+            # wrapper prefix awaits its command (`stdbuf -oL cmd`, `xargs -- cmd`).
             if not prefix_pending:
                 expect_command = False
             continue
@@ -208,9 +203,8 @@ def _find_blocked_commands(command: str) -> set[str]:
         base = _token_basename(token)
         if base in _BLOCKED_COMMANDS:
             blocked.add(base)
-        # Wrappers (`env` / `time` / `xargs` / `sudo`) consume one command; the
-        # next non-flag, non-numeric token is the real command. `sudo` is in
-        # _BLOCKED_COMMANDS, so it's flagged AND we keep walking.
+        # Wrappers (env/time/xargs/sudo) consume one command; the next non-flag,
+        # non-numeric token is the real command. sudo is also in _BLOCKED_COMMANDS.
         if base in _COMMAND_PREFIXES:
             prefix_pending = True
             continue
@@ -224,10 +218,9 @@ def _find_blocked_commands(command: str) -> set[str]:
             if base in _BLOCKED_COMMANDS:
                 blocked.add(base)
 
-    # Regex: blocked words at command boundaries shlex won't see, e.g. inside
-    # unquoted $(rm -rf), <(rm), backtick chains, or after a separator with no
-    # whitespace ("foo;rm"). Anchored to command-position delimiters; no match
-    # in argument position.
+    # Regex catches blocked words at command boundaries shlex misses: inside
+    # $(rm -rf), <(rm), backtick chains, or "foo;rm". Anchored to command-position
+    # delimiters, so it doesn't match in argument position.
     lowered = command.lower()
     if _BLOCKED_COMMANDS:
         words_alt = "|".join(re.escape(w) for w in sorted(_BLOCKED_COMMANDS))
@@ -238,10 +231,9 @@ def _find_blocked_commands(command: str) -> set[str]:
         )
         blocked.update(re.findall(pattern, lowered))
 
-    # Nested shell invocations (bash -c 'sudo whoami', bash -lc '...',
-    #    bash --login -c '...', cmd /c '...'). On a -c or /c flag, look
-    #    backwards for a shell name (skipping flags like --login, -l, -x)
-    #    and recursively scan the nested command string.
+    # Nested shell invocations (bash -c '...', bash -lc '...', cmd /c '...'):
+    # on a -c/-/c flag, look back for a shell name (skipping flags) and
+    # recursively scan the nested command string.
     _SHELLS = {"bash", "sh", "zsh", "dash", "ksh", "csh", "tcsh", "fish"}
     _SHELLS_WIN = {"cmd", "cmd.exe"}
     for i, token in enumerate(tokens):
@@ -253,9 +245,8 @@ def _find_blocked_commands(command: str) -> set[str]:
         is_win_c = tok_lower == "/c"
         if not (is_unix_c or is_win_c) or i < 1 or i + 1 >= len(tokens):
             continue
-        # Look backwards past flags to find the shell binary. Unix flags
-        # start with - (skip). Windows flags start with / but so do absolute
-        # paths, so only skip short single-char /X flags (not /bin/bash).
+        # Look back past flags for the shell binary. Windows flags and absolute
+        # paths both start with /, so only skip short /X flags (not /bin/bash).
         for j in range(i - 1, -1, -1):
             prev = tokens[j]
             if prev.startswith("-"):
@@ -275,15 +266,13 @@ def _find_blocked_commands(command: str) -> set[str]:
 def _build_safe_env(workdir: str) -> dict[str, str]:
     """Build a minimal, credential-free environment for sandboxed subprocesses.
 
-    Whitelist-built from scratch; parent env is NOT inherited. Only PATH /
-    HOME / TMPDIR / LANG / TERM / PYTHONIOENCODING (+ VIRTUAL_ENV or Windows
-    SystemRoot when applicable) reach the child. HF_TOKEN, WANDB_API_KEY,
-    AWS_*, GH_TOKEN, OPENAI_API_KEY, LD_PRELOAD, DYLD_*, and all other parent
-    vars are absent. HOME points at the sandbox workdir so HF / wandb / aws
-    SDKs can't read cached credentials from the operator's real ~/.
+    Whitelist-built from scratch (parent env NOT inherited): only PATH/HOME/
+    TMPDIR/LANG/TERM/PYTHONIOENCODING (+VIRTUAL_ENV or Windows SystemRoot) reach
+    the child; all credential vars (HF_TOKEN, AWS_*, etc.) are absent. HOME
+    points at the sandbox workdir so SDKs can't read the operator's cached creds.
     """
-    # Start with the running interpreter's directory so 'python', 'pip', etc.
-    # resolve to the same environment the Studio server runs in.
+    # Start from the running interpreter's dir so 'python'/'pip' resolve to the
+    # same environment the Studio server runs in.
     exe_dir = os.path.dirname(sys.executable)
     path_entries = [exe_dir] if exe_dir else []
 
@@ -300,7 +289,7 @@ def _build_safe_env(workdir: str) -> dict[str, str]:
     else:
         path_entries.extend(["/usr/local/bin", "/usr/bin", "/bin"])
 
-    # Deduplicate while preserving order
+    # Deduplicate, preserving order.
     deduped = list(dict.fromkeys(p for p in path_entries if p))
 
     env = {
@@ -313,17 +302,15 @@ def _build_safe_env(workdir: str) -> dict[str, str]:
     }
     if venv:
         env["VIRTUAL_ENV"] = venv
-    # Windows needs SystemRoot for Python/subprocess to work
+    # Windows needs SystemRoot for Python/subprocess to work.
     if sys.platform == "win32":
         env["SystemRoot"] = os.environ.get("SystemRoot", r"C:\Windows")
     return env
 
 
 def _sandbox_preexec():
-    """Best-effort sandbox setup for sandboxed subprocesses.
-
-    Modules are resolved at import time so the forked child runs no imports.
-    """
+    """Best-effort sandbox setup for sandboxed subprocesses (modules are
+    resolved at import time so the forked child runs no imports)."""
     try:
         os.setsid()
     except OSError:
@@ -371,10 +358,9 @@ def _sandbox_preexec():
         except (ValueError, OSError, AttributeError):
             pass
         try:
-            # Default high enough for multi-shard safetensors mmaps + Python's
-            # handle count; tunable via env. Clamp to the inherited hard limit
-            # so setrlimit doesn't ValueError where the parent's hard cap is
-            # below the request (else NOFILE stays at the parent's default).
+            # High enough for multi-shard safetensors mmaps; tunable via env.
+            # Clamp to the inherited hard limit so setrlimit doesn't ValueError
+            # when the parent's hard cap is below the request.
             nofile = int(os.environ.get("UNSLOTH_STUDIO_SANDBOX_NOFILE", "16384"))
             _soft_cur, hard_cur = _resource.getrlimit(_resource.RLIMIT_NOFILE)
             target = nofile if hard_cur == _resource.RLIM_INFINITY else min(nofile, hard_cur)
@@ -556,10 +542,9 @@ RENDER_HTML_TOOL = {
 ALL_TOOLS = [WEB_SEARCH_TOOL, PYTHON_TOOL, TERMINAL_TOOL, RENDER_HTML_TOOL]
 
 
-# OpenAI's function.name regex: ^[a-zA-Z0-9_-]{1,64}$ -- enforced before
-# streaming starts. MCP servers can return tool names containing '.', '/',
-# spaces, etc., which the prefix scheme would forward to OpenAI verbatim
-# and 400 the whole request. Validate up front and skip with a warning.
+# OpenAI's function.name regex ^[a-zA-Z0-9_-]{1,64}$, enforced before streaming.
+# MCP tool names with '.', '/', spaces, etc. would 400 the whole request, so we
+# validate up front and skip with a warning.
 _OPENAI_FN_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
 
 
@@ -574,9 +559,8 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
             logger.warning("Skipping MCP tool on '%s': empty name.", display)
             continue
         name = f"{MCP_TOOL_PREFIX}{server['id']}__{raw_name}"
-        # OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; bad chars
-        # (., /, spaces, etc.) or oversized names would 400 the whole
-        # request. Skip + warn so the rest of the tools still ship.
+        # Bad chars or oversized names would 400 the whole request; skip + warn
+        # so the rest of the tools still ship.
         if not _OPENAI_FN_NAME_RE.fullmatch(name):
             logger.warning(
                 "Skipping MCP tool '%s' on '%s': composed name '%s' is not "
@@ -586,8 +570,7 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
                 name,
             )
             continue
-        # Same MCP server returning duplicate tool names would also 400
-        # OpenAI ("tools[N].function.name duplicates ..."). Drop dupes.
+        # Duplicate tool names would also 400 OpenAI; drop dupes.
         if name in seen_names:
             logger.warning("Skipping duplicate MCP tool '%s' on '%s'.", raw_name, display)
             continue
@@ -608,7 +591,7 @@ def _mcp_specs_for_server(server: dict, mcp_tools: list[dict]) -> list[dict]:
 async def get_enabled_mcp_tools() -> list[dict]:
     servers = [s for s in mcp_servers_db.list_servers() if s.get("is_enabled")]
     # Never spawn stdio servers when stdio is disabled on this host (e.g. a DB
-    # carried over from a desktop install onto a Colab / network deployment).
+    # carried from a desktop install onto a Colab/network deployment).
     if not stdio_mcp_enabled():
         servers = [s for s in servers if not is_stdio(s["url"])]
     if not servers:
@@ -670,11 +653,10 @@ def execute_tool(
     timeout: int | None = _TIMEOUT_UNSET,
     session_id: str | None = None,
 ) -> str:
-    """Execute a tool by name with the given arguments. Returns a string.
+    """Execute a tool by name with the given arguments; returns a string.
 
-    ``timeout``: int = per-call limit in seconds, ``None`` = no limit,
-    unset (default) = ``_EXEC_TIMEOUT`` (300 s).
-    ``session_id``: optional thread/session ID for per-conversation sandbox isolation.
+    ``timeout``: int seconds, ``None`` = no limit, unset = ``_EXEC_TIMEOUT``.
+    ``session_id``: optional ID for per-conversation sandbox isolation.
     """
     logger.info(f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}")
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
@@ -714,11 +696,10 @@ def execute_tool(
     return f"Unknown tool: {name}"
 
 
-_MAX_PAGE_CHARS = 16000  # limit fetched page text (after HTML-to-MD conversion)
-# Raw download cap. Larger than _MAX_PAGE_CHARS because SSR pages embed large
-# <head> sections (CSS, JS, SVGs) stripped during HTML-to-Markdown conversion.
-# 512 KB reaches article content on GitBook / Next.js / Docusaurus pages whose
-# <head> alone can be 200 KB.
+_MAX_PAGE_CHARS = 16000  # cap fetched page text (after HTML-to-MD conversion)
+# Raw download cap > _MAX_PAGE_CHARS because SSR pages embed large <head>
+# sections stripped during conversion; 512 KB reaches article content even
+# where <head> alone is ~200 KB.
 _MAX_FETCH_BYTES = 512 * 1024
 
 _USER_AGENTS = (
@@ -739,13 +720,12 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
 
 
 class _PinnedHTTPSConnection(http.client.HTTPSConnection):
-    """HTTPS connection to a pinned IP, using a different hostname for SNI
-    and certificate verification.
+    """HTTPS connection to a pinned IP, using a different hostname for SNI and
+    cert verification.
 
-    SSRF IP-pinning rewrites URLs to raw IPs. A normal HTTPSConnection would
-    then send no SNI and verify the cert against the IP, both of which fail.
-    This subclass splits the concerns: TCP connects to the pinned IP (``host``)
-    while TLS uses ``sni_hostname`` for the ClientHello and cert check.
+    SSRF IP-pinning rewrites URLs to raw IPs; a normal HTTPSConnection would then
+    send no SNI and verify the cert against the IP (both fail). This splits the
+    concerns: TCP connects to the pinned IP (``host``), TLS uses ``sni_hostname``.
     """
 
     def __init__(self, host: str, *, sni_hostname: str, **kwargs):
@@ -753,8 +733,7 @@ class _PinnedHTTPSConnection(http.client.HTTPSConnection):
         self._sni_hostname = sni_hostname
 
     def connect(self):
-        # TCP connect to the pinned IP in self.host (+ tunnel if a proxy is set
-        # via set_tunnel, though we don't use one).
+        # TCP connect to the pinned IP in self.host.
         http.client.HTTPConnection.connect(self)
         # TLS handshake with the real hostname for SNI + cert verification.
         self.sock = self._context.wrap_socket(
@@ -764,11 +743,11 @@ class _PinnedHTTPSConnection(http.client.HTTPSConnection):
 
 
 class _SNIHTTPSHandler(urllib.request.HTTPSHandler):
-    """HTTPS handler that sends the correct SNI hostname during TLS handshake.
+    """HTTPS handler sending the correct SNI hostname during TLS handshake.
 
-    SSRF IP-pinning rewrites URLs to raw IPs, breaking SNI and cert
-    verification. This handler returns a ``_PinnedHTTPSConnection`` that
-    connects to the pinned IP but verifies TLS against the original hostname.
+    SSRF IP-pinning breaks SNI and cert verification; this returns a
+    ``_PinnedHTTPSConnection`` that connects to the pinned IP but verifies TLS
+    against the original hostname.
     """
 
     def __init__(self, hostname: str):
@@ -803,14 +782,10 @@ def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str
 
     for *_, sockaddr in infos:
         ip = ipaddress.ip_address(sockaddr[0])
-        # `not ip.is_global` rejects every category the denylist below rejects
-        # PLUS shared address space (100.64.0.0/10 carrier-grade NAT) and
-        # benchmarking/documentation/exchange ranges Python marks
-        # `is_private=False` and `is_global=False`
-        # (see https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_global).
-        # The explicit predicates after it give human-readable categories in
-        # the error message; the non-global check is the source of truth and
-        # prevents future ranges from leaking.
+        # `not ip.is_global` is the source of truth: it rejects every category
+        # below PLUS shared/CGNAT (100.64.0.0/10) and benchmarking/doc ranges
+        # Python marks is_private=False and is_global=False. The explicit
+        # predicates only give human-readable categories in the error message.
         if (
             not ip.is_global
             or ip.is_private
@@ -822,7 +797,7 @@ def _validate_and_resolve_host(hostname: str, port: int) -> tuple[bool, str, str
         ):
             return False, f"Blocked: refusing to fetch non-public address {ip}.", ""
 
-    # Return the first resolved address for pinning
+    # Return the first resolved address for pinning.
     first_ip = infos[0][4][0]
     return True, "", first_ip
 
@@ -860,8 +835,8 @@ def _fetch_page_text(
         ua = random.choice(_USER_AGENTS)
 
         for _hop in range(5):
-            # Pin to the validated IP (prevents DNS rebinding): rewrite the URL
-            # to the IP and set the Host header.
+            # Pin to the validated IP (prevents DNS rebinding): rewrite URL to
+            # the IP, set the Host header.
             cp = urlparse(current_url)
             # Bracket IPv6 addresses so the netloc is valid in a URL.
             ip_str = f"[{pinned_ip}]" if ":" in pinned_ip else pinned_ip
@@ -901,7 +876,7 @@ def _fetch_page_text(
                     return reason2
                 current_host = rp.hostname
                 continue
-            # Success -- read capped body
+            # Success: read capped body.
             raw_bytes = resp.read(max_bytes)
             break
         else:
@@ -914,7 +889,7 @@ def _fetch_page_text(
     except Exception as e:
         return f"Failed to fetch URL: {e}"
 
-    # Convert HTML to Markdown with the builtin converter (no external deps)
+    # Convert HTML to Markdown with the builtin converter (no external deps).
     from ._html_to_md import html_to_markdown
 
     text = html_to_markdown(raw_html)
@@ -936,7 +911,7 @@ def _web_search(
 
     If ``url`` is provided, fetches that page directly instead of searching.
     """
-    # Direct URL fetch mode
+    # Direct URL fetch mode.
     if url and url.strip():
         fetch_timeout = 60 if timeout is None else min(timeout, 60)
         return _fetch_page_text(url.strip(), timeout = fetch_timeout)
@@ -968,14 +943,9 @@ def _web_search(
 
 
 def _check_signal_escape_patterns(code: str):
-    """
-    Check for patterns that could escape signal-based timeouts.
-
-    Vendored from unsloth_zoo.rl_environments to avoid importing unsloth_zoo
-    (which requires GPU drivers and fails on Mac/Apple Silicon).
-
-    Returns (safe: bool, details: dict)
-    """
+    """Check for patterns that could escape signal-based timeouts. Returns
+    (safe: bool, details: dict). Vendored from unsloth_zoo.rl_environments to
+    avoid importing unsloth_zoo (needs GPU drivers; fails on Apple Silicon)."""
     try:
         tree = ast.parse(code)
     except SyntaxError as e:
@@ -1006,7 +976,7 @@ def _check_signal_escape_patterns(code: str):
             return full_name in names
         return False
 
-    # Dangerous os/subprocess functions that can execute shell commands
+    # Dangerous os/subprocess functions that can execute shell commands.
     _SHELL_EXEC_FUNCS = frozenset(
         {
             "os.system",
@@ -1081,8 +1051,8 @@ def _check_signal_escape_patterns(code: str):
             self.signal_aliases = {"signal"}
             self.os_aliases = {"os"}
             self.subprocess_aliases = {"subprocess"}
-            # Maps bare function names to fully-qualified form for
-            # from-import tracking (e.g. "system" -> "os.system")
+            # Bare name -> fully-qualified form for from-import tracking
+            # (e.g. "system" -> "os.system").
             self.shell_exec_aliases: dict[str, str] = {}
             self.loop_depth = 0
 
@@ -1118,7 +1088,7 @@ def _check_signal_escape_patterns(code: str):
                     self.os_aliases.add("os")
                 else:
                     self.subprocess_aliases.add("subprocess")
-                # Track from-imports of dangerous functions
+                # Track from-imports of dangerous functions.
                 for alias in node.names:
                     fq = f"{node.module}.{alias.name}"
                     if fq in _SHELL_EXEC_FUNCS:
@@ -1194,11 +1164,11 @@ def _check_signal_escape_patterns(code: str):
                     elif func.value.id in self.subprocess_aliases:
                         shell_func = f"subprocess.{func.attr}"
             elif isinstance(func, ast.Name):
-                # Check from-import aliases: from os import system; system(...)
+                # from-import aliases: from os import system; system(...)
                 shell_func = self.shell_exec_aliases.get(func.id)
 
             if shell_func and shell_func in _SHELL_EXEC_FUNCS:
-                # Expand **kwargs dicts to inspect their keys
+                # Expand **kwargs dicts to inspect their keys.
                 expanded_kwargs: dict[str, ast.AST] = {}
                 has_opaque_kwargs = False
                 for kw in node.keywords:
@@ -1217,7 +1187,7 @@ def _check_signal_escape_patterns(code: str):
                 blocked_in_args = _check_args_for_blocked(all_call_args)
 
                 if has_opaque_kwargs:
-                    # Can't inspect dynamic **kwargs; flag as unsafe
+                    # Can't inspect dynamic **kwargs; flag as unsafe.
                     shell_escapes.append(
                         {
                             "type": "shell_escape_dynamic",
@@ -1237,10 +1207,9 @@ def _check_signal_escape_patterns(code: str):
                         }
                     )
                 else:
-                    # Only flag dynamic args for functions that interpret
-                    # strings as shell commands, or when shell= might be
-                    # enabled. Treat any non-literal-False shell= value as
-                    # potentially True (conservative).
+                    # Only flag dynamic args for funcs that interpret strings as
+                    # shell commands, or when shell= might be on. Any non-literal-
+                    # False shell= is treated as potentially True (conservative).
                     _STRING_SHELL_FUNCS = frozenset(
                         {
                             "os.system",
@@ -1256,7 +1225,7 @@ def _check_signal_escape_patterns(code: str):
                     shell_safe = shell_node is None or (
                         isinstance(shell_node, ast.Constant) and shell_node.value is False
                     )
-                    # Dynamic shell-exec args (chr/format/concat bypasses)
+                    # Dynamic shell-exec args (chr/format/concat bypasses).
                     if (
                         shell_func in _STRING_SHELL_FUNCS
                         or shell_func in _SHELL_EXEC_FUNCS
@@ -1298,10 +1267,9 @@ def _check_signal_escape_patterns(code: str):
                     }
                 )
             elif isinstance(node.type, ast.Name):
-                # Only flag BaseException and TimeoutError, NOT Exception.
-                # except Exception doesn't catch SystemExit/KeyboardInterrupt,
-                # so it can't suppress timeout enforcement; flagging it would
-                # false-positive on normal error handling.
+                # Flag BaseException/TimeoutError but NOT Exception: `except
+                # Exception` can't catch SystemExit/KeyboardInterrupt, so it
+                # can't suppress timeout enforcement.
                 if node.type.id in ("TimeoutError", "BaseException"):
                     exception_catching.append(
                         {
@@ -1331,7 +1299,7 @@ def _check_signal_escape_patterns(code: str):
 
     # Static host policy: block metadata hosts and any literal host outside the
     # trusted allowlist; uploads blocked regardless of host. Dynamic hosts are
-    # caught by the bash blocklist instead.
+    # caught by the bash blocklist.
     network_calls: list[dict] = []
     sensitive_file_reads: list[dict] = []
     _NETWORK_FQ_PREFIXES = (
@@ -1577,10 +1545,9 @@ def _check_signal_escape_patterns(code: str):
                     return True
         return False
 
-    # Bare method-name fallback (`x.upload_file(...)`) is intentionally fuzzy,
-    # but should only fire when huggingface_hub / hf_api is imported in the
-    # snippet; else paramiko.upload_file, boto3 create_commit, etc. would
-    # false-positive. We pre-scan for the imports.
+    # Bare method-name fallback (`x.upload_file(...)`) is fuzzy, so it fires only
+    # when huggingface_hub/hf_api is imported; else paramiko.upload_file,
+    # boto3.create_commit, etc. would false-positive. Pre-scan for the imports.
     _HF_IMPORT_MODULES = (
         "huggingface_hub",
         "hf_api",
@@ -1618,13 +1585,9 @@ def _check_signal_escape_patterns(code: str):
     _hf_in_scope = _module_has_hf_import(tree)
 
     def _method_call_hf_upload_name(node: ast.Call) -> str | None:
-        """Return the HF upload method name (`upload_file`, ...) or None.
-
-        Catches `HfApi().upload_file(...)` (Attribute) and
-        `from huggingface_hub import upload_file; upload_file(...)` (Name).
-        The bare-name branch fires only when an HF import is in scope, so
-        paramiko/boto3 don't false-positive.
-        """
+        """Return the HF upload method name (`upload_file`, ...) or None. Covers
+        the Attribute and bare-Name forms; the bare-name branch fires only when
+        an HF import is in scope so paramiko/boto3 don't false-positive."""
         if not _hf_in_scope:
             return None
         f = node.func
@@ -1634,9 +1597,8 @@ def _check_signal_escape_patterns(code: str):
             return f.id
         return None
 
-    # Kwargs that ship a credential over the wire. Sandbox env strips HF_TOKEN
-    # / WANDB_API_KEY / AWS_* up front, so any value here is hard-coded or
-    # lifted from the parent.
+    # Kwargs that ship a credential over the wire. The sandbox env strips
+    # credentials up front, so any value here is hard-coded or lifted from parent.
     _HF_SENSITIVE_KWARGS = frozenset(
         {
             "token",
@@ -1659,16 +1621,11 @@ def _check_signal_escape_patterns(code: str):
         )
 
     def _reads_env_or_secret(node: ast.AST | None) -> bool:
-        """True if any node in the subtree resolves to an env / process read.
+        """True if any node in the subtree resolves to an env/process read.
 
-        Walking the subtree (not just the root) catches wrapper calls like
-        `str(os.environ)`, `json.dumps(os.environ)`,
-        `'-'.join(os.environ.values())`.
-
-        Covers: `os.environ`, `os.environ[K]`, `os.environ.get(K)`, `os.getenv(K)`,
-        bare `getenv(K)` (after `from os import getenv`), and
-        `subprocess.{run,check_output,Popen,getoutput,getstatusoutput}` which
-        could lift parent env via `printenv` / `env` / `set`.
+        Walks the whole subtree (not just the root) to catch wrappers like
+        `str(os.environ)`. Covers os.environ[/.get]/os.getenv, bare getenv, and
+        subprocess.{run,check_output,...} that could lift parent env via printenv.
         """
         if node is None:
             return False
@@ -1716,7 +1673,7 @@ def _check_signal_escape_patterns(code: str):
         if node is None:
             return False
         if isinstance(node, ast.Constant) and isinstance(node.value, (bytes, bytearray)):
-            return True  # inline bytes; no file access
+            return True  # inline bytes, no file access
         if isinstance(node, ast.Constant) and isinstance(node.value, str):
             return _is_safe_relative_path(node.value)
         if isinstance(node, ast.Call):
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 72783f1031..4f5b985234 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -4,14 +4,10 @@
 """
 Inference subprocess entry point.
 
-Each inference session runs in a persistent subprocess
-(mp.get_context("spawn")), giving a clean Python interpreter with no stale
-module state — fully solving the transformers version-switching problem.
-
-The subprocess stays alive while a model is loaded, accepting commands
-(generate, load, unload) via mp.Queue. It exits on shutdown or unload.
-
-Pattern follows core/training/worker.py.
+Each session runs in a persistent spawn subprocess, giving a clean interpreter
+with no stale module state (solves transformers version-switching). It stays
+alive while a model is loaded, taking commands (generate, load, unload) via
+mp.Queue, and exits on shutdown or unload. Pattern follows core/training/worker.py.
 """
 
 from __future__ import annotations
@@ -96,16 +92,10 @@ def _build_model_config(config: dict):
 def _get_hf_download_state(model_names: list[str] | None = None) -> tuple[int, bool] | None:
     """Return (total_bytes, has_incomplete) for the HF Hub cache, or None on error.
 
-    When *model_names* is provided, only those models' ``blobs/`` dirs are
-    checked instead of scanning every cached model -- much faster with many
-    models. Accepts multiple names so LoRA loads can watch both the adapter
-    repo and the base model repo at once.
-
-    *has_incomplete* is True when any ``*.incomplete`` files exist in the
-    watched blobs dirs, indicating ``huggingface_hub`` is actively downloading.
-
-    Returns None if the state cannot be determined (import error, permission
-    error, etc.) so callers can skip stall logic.
+    With *model_names*, only those models' ``blobs/`` dirs are checked (faster);
+    accepts multiple names so LoRA loads can watch adapter + base repos at once.
+    *has_incomplete* is True when any ``*.incomplete`` files exist (download
+    active). None means state could not be determined, so callers skip stall logic.
     """
     try:
         from huggingface_hub.constants import HF_HUB_CACHE
@@ -123,10 +113,8 @@ def _get_hf_download_state(model_names: list[str] | None = None) -> tuple[int, b
             for name in model_names:
                 if not name:
                     continue
-                # Skip local filesystem paths -- HF model IDs use forward
-                # slashes (org/model) but never start with / . ~ or contain
-                # backslashes, distinguishing them from absolute, relative,
-                # and Windows paths.
+                # Skip local filesystem paths -- HF IDs (org/model) never start
+                # with / . ~ or contain backslashes.
                 if name.startswith(("/", ".", "~")) or "\\" in name:
                     continue
                 name = resolve_cached_repo_id_case(name)
@@ -163,16 +151,10 @@ def _start_heartbeat(
 ) -> threading.Event:
     """Start a daemon thread that sends periodic status heartbeats.
 
-    Monitors the HF Hub cache for download activity. A stall is reported only
-    when ``*.incomplete`` files are present (``huggingface_hub`` is actively
-    downloading) **and** the total cache size has not changed for
-    *stall_timeout* seconds.
-
-    Once the download finishes (no more ``.incomplete`` files), the stall timer
-    resets, so post-download init (quantization, GPU weight loading) is never
-    misclassified as a stalled download.
-
-    Returns a stop event -- set it to terminate the heartbeat thread.
+    A stall is reported only when ``*.incomplete`` files are present (download
+    active) AND cache size hasn't changed for *stall_timeout* seconds. When the
+    download finishes the timer resets, so post-download init (quantization, GPU
+    weight load) isn't misclassified as a stall. Returns a stop event.
     """
     stop = threading.Event()
     transport = "https" if xet_disabled else "xet"
@@ -204,9 +186,8 @@ def _start_heartbeat(
                 last_size = current_size
                 last_change = now
 
-            # Only fire stall when .incomplete files confirm a download is in
-            # progress. Once downloads finish (no .incomplete), reset the timer
-            # so model init time is not counted as a stall.
+            # Only fire stall while .incomplete files confirm an active download;
+            # reset the timer otherwise so model init isn't counted as a stall.
             if not has_incomplete:
                 last_change = now
             elif now - last_change >= stall_timeout:
@@ -221,7 +202,7 @@ def _start_heartbeat(
                         "ts": time.time(),
                     },
                 )
-                # Only fire once -- the orchestrator will kill us.
+                # fire once -- the orchestrator will kill us
                 return
 
             _send_response(
@@ -277,10 +258,8 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 except Exception as e:
                     logger.warning("Could not read adapter_config.json: %s", e)
 
-        # Auto-enable trust_remote_code for NemotronH/Nano models only:
-        # NemotronH has config parsing bugs requiring trust_remote_code=True.
-        # Other transformers 5.x models are native and do NOT need it.
-        # NOTE: Must NOT match Llama-Nemotron (standard Llama architecture).
+        # Auto-enable trust_remote_code only for NemotronH/Nano (config parsing
+        # bugs require it). Must NOT match Llama-Nemotron (standard Llama arch).
         _NEMOTRON_TRUST_SUBSTRINGS = ("nemotron_h", "nemotron-h", "nemotron-3-nano")
         trust_remote_code = config.get("trust_remote_code", False)
         if not trust_remote_code:
@@ -295,12 +274,10 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                     model_name,
                 )
 
-        # Send heartbeats every 30s so the orchestrator knows we're alive
-        # (download/weight loading can be slow on slow connections).
+        # Heartbeat every 30s so the orchestrator knows we're alive during slow loads.
         xet_disabled = os.environ.get("HF_HUB_DISABLE_XET") == "1"
 
-        # Watch both the model repo and base model repo (for LoRA loads where
-        # the base model download is the real bottleneck).
+        # Watch model + base repos (base download is the LoRA bottleneck).
         watch_repos = [mc.identifier]
         base = getattr(mc, "base_model", None)
         if base and str(base) != mc.identifier:
@@ -338,8 +315,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 "audio_type": getattr(mc, "audio_type", None),
                 "has_audio_input": getattr(mc, "has_audio_input", False),
             }
-            # Forward chat_template_info so the parent can classify capabilities
-            # without re-entering the subprocess.
+            # Forward chat_template_info so the parent can classify capabilities.
             try:
                 _bm = getattr(backend, "models", {}) or {}
                 _entry = (
@@ -394,21 +370,18 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
 def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
     """Handle a generate command: stream tokens back via resp_queue.
 
-    cancel_event is an mp.Event shared with the parent. The parent can set it
-    at any time (e.g. user stops generation, or loads a new model mid-generate)
-    and generation stops within 1-2 tokens.
+    cancel_event is an mp.Event the parent can set anytime (user stop, or new
+    model load mid-generate); generation stops within 1-2 tokens.
     """
     request_id = cmd.get("request_id", "")
 
     try:
-        # Decode image if provided.
         image = None
         image_b64 = cmd.get("image_base64")
         if image_b64:
             image = _decode_image(image_b64)
             image = _resize_image(image)
 
-        # Build generation kwargs.
         gen_kwargs = {
             "messages": cmd["messages"],
             "system_prompt": cmd.get("system_prompt", ""),
@@ -422,8 +395,7 @@ def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
             "cancel_event": cancel_event,
         }
 
-        # Optional template/tool plumbing: only forward keys that are present so
-        # the backend signature can evolve without breaking older payloads.
+        # Forward only present optional keys so the backend signature can evolve.
         for opt_key in (
             "tools",
             "enable_thinking",
@@ -433,7 +405,6 @@ def _handle_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> None:
             if opt_key in cmd:
                 gen_kwargs[opt_key] = cmd[opt_key]
 
-        # Choose generation path.
         use_adapter = cmd.get("use_adapter")
         if use_adapter is not None:
             generator = backend.generate_with_adapter_control(
@@ -537,7 +508,7 @@ def _handle_generate_audio_input(backend, cmd: dict, resp_queue: Any, cancel_eve
     try:
         import numpy as np
 
-        # Decode audio array from list (numpy arrays can't go through mp.Queue).
+        # numpy arrays can't go through mp.Queue, so decode from list.
         audio_array = np.array(cmd["audio_data"], dtype = np.float32)
 
         audio_type = cmd.get("audio_type")
@@ -868,7 +839,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 _handle_generate(backend, cmd, resp_queue, cancel_event)
 
             elif cmd_type == "load":
-                # Load a new model in this subprocess; unload the current one first.
+                # Unload the current model before loading the new one.
                 if backend.active_model_name:
                     backend.unload_model(backend.active_model_name)
                 _handle_load(backend, cmd, resp_queue)
@@ -901,7 +872,6 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                 )
 
             elif cmd_type == "status":
-                # Return current status.
                 _send_response(
                     resp_queue,
                     {
@@ -921,7 +891,6 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
 
             elif cmd_type == "shutdown":
                 logger.info("Shutdown command received, exiting")
-                # Unload all models.
                 for model_name in list(backend.models.keys()):
                     try:
                         backend.unload_model(model_name)
diff --git a/studio/backend/core/tool_healing.py b/studio/backend/core/tool_healing.py
index 9ef60e00df..973520d5cd 100644
--- a/studio/backend/core/tool_healing.py
+++ b/studio/backend/core/tool_healing.py
@@ -3,24 +3,20 @@
 
 """Tool-call XML parsing and stripping helpers.
 
-Extracted verbatim from studio/backend/core/inference/llama_cpp.py so
-external inference servers (llama-server wrappers, llama-swap, custom
-shims) can reuse the logic without importing the inference orchestrator,
-structlog, httpx, or the rest of the studio backend.
+Extracted verbatim from studio/backend/core/inference/llama_cpp.py so external
+inference servers can reuse the logic without importing the inference
+orchestrator, structlog, httpx, or the rest of the studio backend.
 
-Regexes and function bodies are byte-for-byte identical to the original
-inline implementation in llama_cpp.py; any change must preserve that
-equivalence. tests/python/test_tool_healing_extraction_is_exact.py
-verifies it with AST comparison.
+Regexes and bodies are byte-for-byte identical to the original; any change must
+preserve that. test_tool_healing_extraction_is_exact.py verifies via AST.
 """
 
 import json
 import re
 
-# Pre-compiled patterns for tool XML stripping. The hyphen in the
-# function/parameter name char-class tracks OpenAI's allowed set so MCP
-# tool names (mcp__srv__list-issues) and parameter names (`issue-number`)
-# with dashes parse alongside the built-ins.
+# Pre-compiled patterns for tool XML stripping. The hyphen in the name
+# char-class lets dashed MCP tool/parameter names (mcp__srv__list-issues,
+# issue-number) parse alongside the built-ins.
 _TOOL_CLOSED_PATS = [
     re.compile(r"<tool_call>.*?</tool_call>", re.DOTALL),
     re.compile(r"<function=[\w-]+>.*?</function>", re.DOTALL),
@@ -51,8 +47,8 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
     """
     tool_calls = []
 
-    # Pattern 1: JSON inside <tool_call> tags. Balanced-brace extraction
-    # that skips braces inside JSON strings.
+    # Pattern 1: JSON inside <tool_call> tags. Balanced-brace extraction that
+    # skips braces inside JSON strings.
     for m in _TC_JSON_START_RE.finditer(content):
         brace_start = m.end() - 1  # position of the opening {
         depth, i = 0, brace_start
@@ -93,18 +89,16 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                 pass
 
     # Pattern 2: XML-style <function=name><parameter=key>value</parameter></function>
-    # All closing tags optional -- models frequently omit </parameter>,
-    # </function>, and/or </tool_call>.
+    # All closing tags optional; models frequently omit them.
     if not tool_calls:
-        # Step 1: Find all <function=name> positions and extract bodies.
-        # Use only </tool_call> or the next <function= as hard boundaries;
-        # </function> is avoided since code values can contain it. Trim a
-        # trailing </function> afterwards if present.
+        # Step 1: Find <function=name> positions and extract bodies. Use only
+        # </tool_call> or the next <function= as hard boundaries (</function>
+        # can appear in code values); trim a trailing </function> afterwards.
         func_starts = list(_TC_FUNC_START_RE.finditer(content))
         for idx, fm in enumerate(func_starts):
             func_name = fm.group(1)
             body_start = fm.end()
-            # Hard boundaries: next <function= tag or </tool_call>
+            # Boundaries: next <function= tag or </tool_call>
             next_func = func_starts[idx + 1].start() if idx + 1 < len(func_starts) else len(content)
             end_tag = _TC_END_TAG_RE.search(content[body_start:])
             if end_tag:
@@ -113,18 +107,16 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                 body_end = len(content)
             body_end = min(body_end, next_func)
             body = content[body_start:body_end]
-            # Trim the real closing </function> tag if present
-            body = _TC_FUNC_CLOSE_RE.sub("", body)
+            body = _TC_FUNC_CLOSE_RE.sub("", body)  # trim closing </function>
 
             # Step 2: Extract parameters from body. For single-parameter
-            # functions (the common code/command/query case), use body end
-            # as the only boundary to avoid matching </parameter> inside
-            # code strings.
+            # functions, use body end as the only boundary to avoid matching
+            # </parameter> inside code strings.
             arguments = {}
             param_starts = list(_TC_PARAM_START_RE.finditer(body))
             if len(param_starts) == 1:
-                # Single parameter: value is everything after the tag to
-                # end of body, trimming any trailing </parameter>.
+                # Value is everything after the tag to end of body, less a
+                # trailing </parameter>.
                 pm = param_starts[0]
                 val = body[pm.end() :]
                 val = _TC_PARAM_CLOSE_RE.sub("", val)
@@ -133,15 +125,14 @@ def parse_tool_calls_from_text(content: str) -> list[dict]:
                 for pidx, pm in enumerate(param_starts):
                     param_name = pm.group(1)
                     val_start = pm.end()
-                    # Value ends at the next <parameter= or end of body
+                    # Value ends at next <parameter= or end of body
                     next_param = (
                         param_starts[pidx + 1].start()
                         if pidx + 1 < len(param_starts)
                         else len(body)
                     )
                     val = body[val_start:next_param]
-                    # Trim trailing </parameter> if present
-                    val = _TC_PARAM_CLOSE_RE.sub("", val)
+                    val = _TC_PARAM_CLOSE_RE.sub("", val)  # trim trailing </parameter>
                     arguments[param_name] = val.strip()
 
             tc = {
diff --git a/studio/backend/core/training/__init__.py b/studio/backend/core/training/__init__.py
index 6ce85aab0d..f0e4113ac3 100644
--- a/studio/backend/core/training/__init__.py
+++ b/studio/backend/core/training/__init__.py
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Training submodule: backends and trainer classes."""
+"""Training backends and trainer classes."""
 
 from .training import TrainingBackend, TrainingProgress, get_training_backend
 
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index c43c269aed..3d6ab2411c 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -11,16 +11,14 @@ import os
 import sys
 import types
 
-# Prevent tokenizer parallelism deadlocks when datasets uses multiprocessing fork
+# Prevent tokenizer parallelism deadlocks when datasets forks.
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
-# Make compiled cache modules importable by any subprocess.
-# On spawn-based platforms (Windows, macOS), spawned dataset.map() workers
-# re-import all top-level modules. The compiled cache's trainer files import
-# torch and unsloth_zoo (which inits CUDA), making spawn impractical.
-# Propagating UNSLOTH_COMPILE_LOCATION via PYTHONPATH lets any subprocess
-# (not just Pool workers) find compiled modules.
-# NOTE: Do NOT import unsloth_zoo.compiler here -- it triggers heavy torch/triton imports.
+# Make compiled cache modules importable by any subprocess. On spawn platforms
+# (Windows/macOS) spawned dataset.map() workers re-import top-level modules, and
+# the cache's trainer files import torch + unsloth_zoo (inits CUDA). Propagating
+# UNSLOTH_COMPILE_LOCATION via PYTHONPATH lets any subprocess find them.
+# Do NOT import unsloth_zoo.compiler here -- it triggers heavy torch/triton imports.
 if sys.platform in ("win32", "darwin"):
     _compile_cache = os.environ.get("UNSLOTH_COMPILE_LOCATION", "unsloth_compiled_cache")
     if not os.path.isabs(_compile_cache):
@@ -42,8 +40,8 @@ from utils.hardware import (
     get_visible_gpu_count,
 )
 
-# recompile_limit was removed in some ROCm torch builds (e.g. pytorch.org/whl/rocm6.2).
-# Guard so training doesn't crash on RDNA2/RDNA3 with older ROCm wheels.
+# recompile_limit was removed in some ROCm torch builds; guard so training
+# doesn't crash on RDNA2/RDNA3 with older ROCm wheels.
 if hasattr(torch._dynamo.config, "recompile_limit"):
     torch._dynamo.config.recompile_limit = 64
 from unsloth import FastLanguageModel, FastVisionModel, is_bfloat16_supported
@@ -167,13 +165,11 @@ class UnslothTrainer:
     ) -> None:
         """Lightweight detection and tokenizer load — no model weights, no VRAM.
 
-        Sets is_vlm, _audio_type, is_audio_vlm, model_name and loads a
-        lightweight tokenizer for dataset formatting. Call before
-        load_and_format_dataset() to process the dataset BEFORE loading the
-        training model (avoids VRAM contention with the LLM-assisted detector).
-
-        load_model() may run afterwards — it re-detects and loads the full
-        model + tokenizer, overwriting the lightweight one set here.
+        Sets is_vlm, _audio_type, is_audio_vlm, model_name and loads a lightweight
+        tokenizer for dataset formatting. Call before load_and_format_dataset() so
+        the dataset is processed before the training model loads (avoids VRAM
+        contention). load_model() later re-detects and loads the full model +
+        tokenizer, overwriting the lightweight one set here.
         """
         self.model_name = model_name
         self.max_seq_length = max_seq_length
@@ -208,8 +204,8 @@ class UnslothTrainer:
         )
 
         # --- Load lightweight tokenizer/processor (CPU only, no VRAM) ---
-        # Whisper needs AutoProcessor (feature_extractor + tokenizer); others
-        # use AutoTokenizer (CSM loads its own processor inline).
+        # Whisper needs AutoProcessor; others use AutoTokenizer (CSM loads its
+        # own processor inline).
         if self._audio_type == "whisper":
             from transformers import AutoProcessor
             self.tokenizer = AutoProcessor.from_pretrained(
@@ -320,10 +316,8 @@ class UnslothTrainer:
         *,
         extra_args = None,
     ):
-        """Build the training args dict for audio branches.
-
-        Builds the common config (batch size, lr, warmup, fp16/bf16, etc.)
-        and applies per-branch overrides via extra_args.
+        """Build the training args dict for audio branches: common config (batch
+        size, lr, warmup, fp16/bf16, etc.) with per-branch overrides via extra_args.
         """
         batch_size = training_args.get("batch_size", 2)
         gradient_accumulation_steps = training_args.get("gradient_accumulation_steps", 4)
@@ -410,10 +404,10 @@ class UnslothTrainer:
     def _cleanup_audio_artifacts(self):
         """Remove sys.path/sys.modules entries from previous audio preprocessing.
 
-        After audio training, cloned repo dirs (OuteTTS, Spark-TTS) stay on
-        sys.path and heavy modules (snac, whisper, sparktts, outetts) stay in
-        sys.modules. On the next dataset.map(num_proc=N), forked children
-        inherit this stale state and deadlock.
+        After audio training, cloned repo dirs (OuteTTS, Spark-TTS) and heavy
+        modules (snac, whisper, sparktts, outetts) linger; the next
+        dataset.map(num_proc=N) forks children that inherit this stale state and
+        deadlock.
         """
         # Remove cloned audio repo paths from sys.path
         base_dir = os.path.dirname(os.path.abspath(__file__))
@@ -523,12 +517,10 @@ class UnslothTrainer:
             # to prevent deadlocks when forking dataset.map() workers
             self._cleanup_audio_artifacts()
 
-            # Reload Unsloth-patched transformers modeling modules before
-            # clearing the compiled cache. unsloth_compile_transformers() sets
-            # __UNSLOTH_PATCHED__ and replaces methods with exec'd code.
-            # clear_unsloth_compiled_cache() deletes the disk cache, but the
-            # flag blocks re-compilation, leaving missing cache files. Reloading
-            # restores original class defs so Unsloth re-compiles cleanly.
+            # Reload Unsloth-patched modeling modules before clearing the cache.
+            # __UNSLOTH_PATCHED__ blocks re-compilation, so clearing the disk
+            # cache alone would leave files missing; reloading restores original
+            # class defs so Unsloth re-compiles cleanly.
             import importlib
 
             for _key, _mod in list(sys.modules.items()):
@@ -589,13 +581,11 @@ class UnslothTrainer:
 
             logger.info(f"\nLoading {model_type_label} model: {model_name}")
 
-            # Set HF token if provided
             if hf_token:
                 os.environ["HF_TOKEN"] = hf_token
 
-            # Proactive gated-model check before from_pretrained. Catches ALL
-            # gated/private models (text, vision, audio) globally. Skip when
-            # offline -- from_pretrained uses the cache.
+            # Proactive gated-model check before from_pretrained (catches all
+            # gated/private models). Skip when offline -- it uses the cache.
             if "/" in model_name and not _env_offline():
                 try:
                     from huggingface_hub import model_info as hf_model_info
@@ -631,15 +621,11 @@ class UnslothTrainer:
                 f"Using device_map='{device_map}' ({get_visible_gpu_count()} GPU(s) visible)"
             )
 
-            # AMD ROCm without native bfloat16 (e.g. RDNA2 / gfx103x) crashes
-            # with an LLVM error at the first bf16 kernel dispatch if dtype=None
-            # lets unsloth auto-pick bf16. Force float16 there. NVIDIA keeps
-            # dtype=None so unsloth's bf16/fp16/float32 auto-detection (incl.
-            # FORCE_FLOAT32 models) is honored -- older NVIDIA without bf16
-            # (T4/V100) must NOT be coerced to float16 (the previous
-            # unconditional branch did this wrongly). Derive ROCm inline (not
-            # hardware.IS_ROCM) since that flag is unset until detect_hardware()
-            # runs, not guaranteed in this subprocess.
+            # AMD ROCm without native bf16 (e.g. RDNA2/gfx103x) crashes with an
+            # LLVM error on the first bf16 kernel if dtype=None auto-picks bf16, so
+            # force float16 there. NVIDIA keeps dtype=None so unsloth's auto-detect
+            # (incl. FORCE_FLOAT32) is honored -- T4/V100 must NOT be coerced to
+            # float16. Derive ROCm inline since hardware.IS_ROCM may be unset here.
             _is_rocm = (
                 bool(getattr(torch.version, "hip", None)) or "rocm" in torch.__version__.lower()
             )
@@ -703,11 +689,9 @@ class UnslothTrainer:
                 logger.info(f"Loaded {self._audio_type} audio model (FastLanguageModel)")
 
             elif self._audio_type == "bicodec":
-                # Spark-TTS: download full repo (sparktts package + BiCodec
-                # weights), then load only the LLM subfolder with FastModel.
-                # model_name may be:
-                #   "Spark-TTS-0.5B/LLM"       (local-style, from YAML mapping)
-                #   "unsloth/Spark-TTS-0.5B"    (HF repo ID)
+                # Spark-TTS: download full repo (sparktts + BiCodec weights), then
+                # load only the LLM subfolder. model_name may be
+                # "Spark-TTS-0.5B/LLM" (YAML mapping) or "unsloth/Spark-TTS-0.5B".
                 from unsloth import FastModel
                 from huggingface_hub import snapshot_download
 
@@ -782,7 +766,7 @@ class UnslothTrainer:
                 )
                 logger.info("Loaded vision model")
 
-                # Diagnostic: did FastVisionModel return a Processor or a raw tokenizer?
+                # Did FastVisionModel return a Processor or a raw tokenizer?
                 from transformers import ProcessorMixin
 
                 tok = self.tokenizer
@@ -826,11 +810,9 @@ class UnslothTrainer:
             if "could not get source code" in str(e) and not getattr(
                 self, "_source_code_retried", False
             ):
-                # Unsloth's patching can leave stale state that makes
-                # inspect.getsource() fail when switching model families
-                # (e.g. gemma3 → gemma3n). The second attempt always succeeds
-                # because the failed first call's partial imports clean up the
-                # stale state as a side effect.
+                # Unsloth patching can leave stale state that breaks
+                # inspect.getsource() when switching model families (e.g. gemma3 →
+                # gemma3n); the first failure clears it, so a retry succeeds.
                 self._source_code_retried = True
                 logger.info(f"\n'could not get source code' — retrying once...\n")
                 return self.load_model(
@@ -1132,12 +1114,10 @@ class UnslothTrainer:
     def _apply_csm_forward_fix(self):
         """Monkey-patch CsmForConditionalGeneration.forward for depth decoder kwargs.
 
-        The original forward passes raw **kwargs (num_items_in_batch,
-        causal_mask, etc.) from Trainer/PEFT through to the depth decoder,
-        causing depth_decoder_loss=None and a 'Tensor + NoneType' crash.
-
-        Patch at both instance AND class level for reliability, and strip
-        non-TransformersKwargs params that Unsloth/PEFT inject.
+        The original forward leaks raw **kwargs (num_items_in_batch, causal_mask,
+        etc.) from Trainer/PEFT into the depth decoder, causing
+        depth_decoder_loss=None and a 'Tensor + NoneType' crash. Patch at both
+        instance and class level and strip non-TransformersKwargs params.
         """
         import torch
         import torch.nn as nn
@@ -1178,8 +1158,7 @@ class UnslothTrainer:
             logits_to_keep = 0,
             **kwargs,
         ):
-            # Strip non-standard kwargs from Unsloth/PEFT (causal_mask,
-            # num_logits_to_keep, task_ids, return_dict, etc.)
+            # Strip non-standard kwargs from Unsloth/PEFT.
             output_attentions = kwargs.pop("output_attentions", None)
             output_hidden_states = kwargs.pop("output_hidden_states", None)
             kwargs.pop("return_dict", None)
@@ -1242,8 +1221,7 @@ class UnslothTrainer:
                 ]
                 depth_decoder_labels = labels[train_mask]
 
-                # Clean kwargs for depth decoder; scale num_items_in_batch
-                # for its 31 codebooks
+                # Scale num_items_in_batch for the depth decoder's 31 codebooks.
                 dd_kwargs = clean_kwargs.copy()
                 if "num_items_in_batch" in dd_kwargs:
                     dd_kwargs["num_items_in_batch"] = dd_kwargs["num_items_in_batch"] * (
@@ -1295,10 +1273,9 @@ class UnslothTrainer:
                 ),
             )
 
-        # Patch BOTH instance and class level for reliability.
-        # Instance: catches calls via BaseTuner.forward -> self.model.forward()
+        # Instance level: catches BaseTuner.forward -> self.model.forward().
         base_csm.forward = types.MethodType(_fixed_csm_forward, base_csm)
-        # Class: catches any path resolving through the class dict
+        # Class level: catches paths resolving through the class dict.
         CsmForConditionalGeneration.forward = _fixed_csm_forward
         logger.info("Applied CSM forward fix (class + instance level)\n")
 
@@ -1317,10 +1294,9 @@ class UnslothTrainer:
             trust_remote_code = getattr(self, "trust_remote_code", False),
         )
 
-        # Strip pad_to_multiple_of from tokenizer init_kwargs — fine-tuned
-        # models (e.g. keanteng/sesame-csm-elise) save it in
-        # tokenizer_config.json, and _merge_kwargs leaks it into audio_kwargs
-        # where EncodecFeatureExtractor rejects it.
+        # Strip pad_to_multiple_of from tokenizer init_kwargs — some fine-tuned
+        # models save it in tokenizer_config.json, and _merge_kwargs leaks it into
+        # audio_kwargs where EncodecFeatureExtractor rejects it.
         processor.tokenizer.init_kwargs.pop("pad_to_multiple_of", None)
 
         # Resolve columns from user mapping or hardcoded fallback
@@ -1371,8 +1347,8 @@ class UnslothTrainer:
                         ],
                     }
                 ]
-                # NOTE: pad_to_multiple_of intentionally omitted from text_kwargs —
-                # CsmProcessor._merge_kwargs leaks it to EncodecFeatureExtractor, which rejects it.
+                # pad_to_multiple_of omitted: _merge_kwargs leaks it to
+                # EncodecFeatureExtractor, which rejects it.
                 model_inputs = processor.apply_chat_template(
                     conversation,
                     tokenize = True,
@@ -1691,8 +1667,8 @@ class UnslothTrainer:
 
         device = "cuda" if torch.cuda.is_available() else "cpu"
 
-        # The sparktts package lives in the SparkAudio/Spark-TTS GitHub repo,
-        # NOT in the unsloth/Spark-TTS-0.5B HF model repo. Clone if needed.
+        # sparktts lives in the SparkAudio/Spark-TTS GitHub repo, not the HF model
+        # repo. Clone if needed.
         spark_code_dir = os.path.join(os.path.dirname(self._spark_tts_repo_dir), "Spark-TTS")
         sparktts_pkg = os.path.join(spark_code_dir, "sparktts")
         if not os.path.isdir(sparktts_pkg):
@@ -2296,10 +2272,9 @@ class UnslothTrainer:
                 return result.dataset
 
             if local_datasets:
-                # Use load_dataset() so the result is Arrow-backed (has cache
-                # files). Dataset.from_list() is in-memory with no cache, which
-                # forces num_proc=1 during tokenization/map (sharding needs
-                # Arrow files).
+                # Use load_dataset() for an Arrow-backed result; in-memory
+                # Dataset.from_list() has no cache and forces num_proc=1 during
+                # tokenization/map (sharding needs Arrow files).
                 all_files = self._resolve_local_files(local_datasets)
 
                 if all_files:
@@ -2665,9 +2640,8 @@ class UnslothTrainer:
             return False
 
         # Pre-import heavy transformers modules on the main thread. Unsloth's
-        # patched_import hook (deepseek_v3_moe.py) isn't thread-safe with
-        # importlib's cache, causing KeyError: 'size' if first imported in the
-        # worker thread.
+        # patched_import hook isn't thread-safe with importlib's cache, causing
+        # KeyError: 'size' if first imported in the worker thread.
         import transformers  # noqa: F401 – ensures submodules are cached
         from transformers import (  # noqa: F401
             Trainer as _HFTrainer,
@@ -2724,10 +2698,9 @@ class UnslothTrainer:
     def _train_worker(self, dataset: Dataset, **training_args):
         """Worker function for training (runs in separate thread)"""
         try:
-            # On spawn-based platforms (Windows, macOS), register all known
-            # compiled-cache dirs on sys.path/PYTHONPATH before any
-            # dataset.map() call so spawned workers can import dynamically
-            # compiled modules such as UnslothSFTTrainer.
+            # On spawn platforms, register compiled-cache dirs on sys.path/PYTHONPATH
+            # before any dataset.map() so spawned workers can import compiled
+            # modules such as UnslothSFTTrainer.
             if sys.platform in ("win32", "darwin"):
                 from utils.cache_cleanup import register_compiled_cache_on_path
                 register_compiled_cache_on_path()
@@ -2754,8 +2727,8 @@ class UnslothTrainer:
 
             # ========== AUDIO TRAINER BRANCH ==========
             if self._audio_type == "csm":
-                # CSM uses plain HF Trainer (NOT SFTTrainer). Needs
-                # remove_unused_columns=False for depth decoder (input_values + cutoffs).
+                # CSM uses plain HF Trainer (not SFTTrainer) with
+                # remove_unused_columns=False for the depth decoder.
                 from transformers import Trainer as HFTrainer, TrainingArguments
 
                 self._apply_csm_forward_fix()
@@ -2792,8 +2765,8 @@ class UnslothTrainer:
 
             elif self._audio_type == "snac":
                 # Orpheus: LM with SNAC codec tokens — plain HF Trainer.
-                # DataCollatorForSeq2Seq pads variable-length sequences per
-                # batch (text + audio codes vary) and pads labels with -100.
+                # DataCollatorForSeq2Seq pads variable-length sequences per batch
+                # and pads labels with -100.
                 from transformers import (
                     Trainer as HFTrainer,
                     TrainingArguments,
@@ -2915,9 +2888,9 @@ class UnslothTrainer:
 
                     logger.info("Configuring DeepSeek OCR data collator...\n")
                     FastVisionModel.for_training(self.model)
-                    # DeepSeek OCR's (image_size, base_size, crop_mode) is a
-                    # coupled preset; changing image_size alone desyncs the
-                    # per-crop pixel grid from num_queries. Use Gundam preset.
+                    # (image_size, base_size, crop_mode) is a coupled preset;
+                    # changing image_size alone desyncs the per-crop grid from
+                    # num_queries. Use Gundam preset.
                     if training_args.get("vision_image_size") is not None:
                         logger.info(
                             "Vision image resize ignored for DeepSeek OCR "
@@ -2940,8 +2913,8 @@ class UnslothTrainer:
                     return
 
             elif self.is_audio_vlm and not raw_text_mode:
-                # Audio VLM collator (e.g. Gemma 3N with audio).
-                # Mirrors the collate_fn from Gemma3N_(4B)-Audio notebook.
+                # Audio VLM collator (e.g. Gemma 3N), mirrors the
+                # Gemma3N_(4B)-Audio notebook collate_fn.
                 logger.info("Configuring audio VLM data collator...\n")
                 processor = self.tokenizer  # FastModel returns processor as tokenizer
 
@@ -3035,9 +3008,8 @@ class UnslothTrainer:
                 f"[DEBUG] dataset_num_proc={config_args['dataset_num_proc']} (is_audio={self.is_audio}, is_audio_vlm={self.is_audio_vlm}, _cuda_audio_used={self._cuda_audio_used})"
             )
 
-            # On spawn-based platforms (Windows, macOS) with transformers 5.x,
-            # disable DataLoader multiprocessing to avoid modified sys.path
-            # (.venv_t5) issues in spawned workers.
+            # On spawn platforms with transformers 5.x, disable DataLoader
+            # multiprocessing to avoid modified sys.path issues in spawned workers.
             if sys.platform in ("win32", "darwin"):
                 import transformers as _tf
                 if _tf.__version__.startswith("5."):
@@ -3098,8 +3070,7 @@ class UnslothTrainer:
 
             if (self.is_vlm or self.is_audio_vlm) and not raw_text_mode:
                 # Vision / audio VLM config (both need skip_prepare_dataset +
-                # remove_unused_columns). Raw-text on VLM models goes to the
-                # text path below.
+                # remove_unused_columns); raw-text VLM goes to the text path below.
                 label = "audio VLM" if self.is_audio_vlm else "vision"
                 logger.info(f"Configuring {label} model training parameters\n")
                 # Provided values or vision defaults
@@ -3156,9 +3127,8 @@ class UnslothTrainer:
             logger.info("Training configuration prepared\n")
             # ========== TRAINER INITIALIZATION ==========
             if self.is_audio_vlm and not raw_text_mode:
-                # Audio VLM (e.g. Gemma 3N + audio): raw Dataset from
-                # _format_audio_vlm_dataset. Notebook uses
-                # processing_class=processor.tokenizer (text tokenizer only).
+                # Audio VLM (e.g. Gemma 3N): raw Dataset from
+                # _format_audio_vlm_dataset, processing_class=processor.tokenizer.
                 # Raw-text runs go to the text path below.
                 train_dataset = dataset if isinstance(dataset, Dataset) else dataset["dataset"]
                 processing_class = (
@@ -3191,11 +3161,10 @@ class UnslothTrainer:
                     trainer_kwargs["eval_dataset"] = eval_dataset
                 self.trainer = SFTTrainer(**trainer_kwargs)
             else:
-                # For text-only training, if the tokenizer is actually a
-                # Processor (e.g. Gemma-3 returns ProcessorMixin even for text),
-                # unwrap to the raw tokenizer. Otherwise Unsloth's SFTTrainer
-                # sets _is_vlm=True, skips _prepare_dataset, and the 'text'
-                # column never gets tokenized to 'input_ids'.
+                # For text-only training, unwrap a Processor (e.g. Gemma-3 returns
+                # ProcessorMixin even for text) to the raw tokenizer; else SFTTrainer
+                # sets _is_vlm=True, skips _prepare_dataset, and 'text' never gets
+                # tokenized to 'input_ids'.
                 from transformers import ProcessorMixin
 
                 sft_tokenizer = self.tokenizer
@@ -3249,8 +3218,8 @@ class UnslothTrainer:
                     if eval_dataset is not None:
                         trainer_kwargs["eval_dataset"] = eval_dataset
                     self.trainer = SFTTrainer(**trainer_kwargs)
-                # Restore full processor as processing_class so checkpoints
-                # include preprocessor_config.json (needed for GGUF export).
+                # Restore full processor so checkpoints include
+                # preprocessor_config.json (needed for GGUF export).
                 if sft_tokenizer is not self.tokenizer:
                     self.trainer.processing_class = self.tokenizer
             logger.info("Trainer initialized\n")
@@ -3332,11 +3301,10 @@ class UnslothTrainer:
                     )
                     logger.info("Train on responses only configured successfully\n")
 
-                    # ── Safety net: check if all samples were filtered out ──
-                    # train_on_responses_only masks non-response tokens with
-                    # -100. If max_seq_length is too short and the response is
-                    # truncated away, EVERY sample ends up all -100 and Unsloth
-                    # removes them, leaving 0 usable samples.
+                    # Safety net: train_on_responses_only masks non-response
+                    # tokens with -100. If max_seq_length is too short, the
+                    # response is truncated away, every sample becomes all -100,
+                    # and Unsloth drops them, leaving 0 usable samples.
                     filtered_len = len(self.trainer.train_dataset)
                     original_len = len(dataset["dataset"])
                     dropped = original_len - filtered_len
@@ -3496,14 +3464,11 @@ class UnslothTrainer:
 
 
 def _ensure_deepseek_ocr_installed():
-    """
-    Auto-install the DeepSeek OCR module if missing (from HuggingFace hub as
-    a local module).
+    """Auto-install the DeepSeek OCR module from HF hub if missing.
 
     Returns True if available (already installed or just installed).
     """
     try:
-        # Already available?
         from deepseek_ocr.modeling_deepseekocr import format_messages
         logger.info("DeepSeek OCR module already available")
         return True
@@ -3518,7 +3483,6 @@ def _ensure_deepseek_ocr_installed():
         import sys
         import os
 
-        # Install locally at project root
         script_dir = os.path.dirname(os.path.abspath(__file__))
         parent_dir = os.path.dirname(script_dir)  # project root
 
@@ -3527,11 +3491,9 @@ def _ensure_deepseek_ocr_installed():
 
         snapshot_download("unsloth/DeepSeek-OCR", local_dir = local_dir, local_dir_use_symlinks = False)
 
-        # Add to sys.path if needed
         if parent_dir not in sys.path:
             sys.path.insert(0, parent_dir)
 
-        # Retry import
         from deepseek_ocr.modeling_deepseekocr import format_messages
 
         logger.info("DeepSeek OCR module installed successfully")
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index 5c5626625b..c5bc3dbad5 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -4,14 +4,10 @@
 """
 Training backend — subprocess orchestrator.
 
-Each training job runs in a fresh subprocess (mp.get_context("spawn")), solving
-the transformers version-switching problem. The old in-process UnslothTrainer
-singleton is only used inside the subprocess (worker.py).
-
-This file orchestrates the subprocess lifecycle, pumps events from the worker's
-mp.Queue, and exposes the same API surface to routes/training.py.
-
-Pattern follows core/data_recipe/jobs/manager.py.
+Each job runs in a fresh spawn subprocess (solving transformers version-switching);
+the in-process UnslothTrainer singleton is only used inside the worker. This file
+orchestrates the subprocess lifecycle, pumps events from the worker's mp.Queue, and
+exposes the same API to routes/training.py. Pattern follows data_recipe/jobs/manager.py.
 """
 
 import json as _json
@@ -47,9 +43,8 @@ _HF_TMP_CHECKPOINT_RE = re.compile(r"^tmp-checkpoint-\d+$")
 def _cleanup_cancelled_checkpoints(output_dir: str | os.PathLike) -> None:
     """Remove only HF Trainer ``tmp-checkpoint-<step>/`` partials after a cancel.
 
-    Completed ``checkpoint-<int>/`` dirs and any non-numeric-suffix tmp dir are
-    user-owned and survive. Symlinked output_dir / children are skipped so
-    containment can't be bypassed.
+    Completed ``checkpoint-<int>/`` dirs survive. Symlinked output_dir / children
+    are skipped so containment can't be bypassed.
     """
     out = Path(output_dir)
     if not out.exists() or not out.is_dir() or out.is_symlink():
@@ -95,8 +90,7 @@ PLOT_HEIGHT = 3.5
 
 @dataclass
 class TrainingProgress:
-    """Mirror of trainer.TrainingProgress — here so the parent process never
-    imports the heavy ML modules."""
+    """Mirror of trainer.TrainingProgress so the parent never imports heavy ML modules."""
 
     epoch: float = 0
     step: int = 0
@@ -244,12 +238,11 @@ class TrainingBackend:
             "gpu_ids": kwargs.get("gpu_ids"),
         }
 
-        # Full finetuning always runs in 16-bit. LoRA/QLoRA and CPT keep the
-        # explicit request so 4-bit adapter/raw-text runs stay possible.
+        # Full finetuning always runs in 16-bit; LoRA/QLoRA/CPT keep the request.
         if config["training_type"] == "Full Finetuning":
             config["load_in_4bit"] = False
 
-        # Spawn subprocess — use locals so state is untouched on failure
+        # Spawn into locals so state is untouched on failure.
         from utils.hardware import hardware as _hw
 
         if _hw.DEVICE == _hw.DeviceType.MLX:
@@ -296,7 +289,7 @@ class TrainingBackend:
 
         logger.info("Training subprocess started (pid=%s)", proc.pid)
 
-        # Reset state — safe: old pump thread confirmed dead, proc.start() succeeded
+        # Reset state (old pump thread dead, proc.start() succeeded).
         self.current_job_id = job_id
         self._should_stop = False
         self._cancel_requested = False
@@ -319,15 +312,14 @@ class TrainingBackend:
         self._db_config = {k: v for k, v in config.items() if k not in {"hf_token", "wandb_token"}}
         self._db_started_at = datetime.now(timezone.utc).isoformat()
 
-        # Assign subprocess handles after state reset
+        # Assign subprocess handles after state reset.
         self._event_queue = event_queue
         self._stop_queue = stop_queue
         self._proc = proc
 
-        # Eagerly create DB run row so it appears in history during model loading
+        # Eagerly create DB run row so it appears in history during model loading.
         self._ensure_db_run_created()
 
-        # Start event pump thread
         self._pump_thread = threading.Thread(target = self._pump_loop, daemon = True)
         self._pump_thread.start()
 
@@ -344,7 +336,7 @@ class TrainingBackend:
                     self._stop_queue.put({"type": "stop", "save": save})
                 except (OSError, ValueError):
                     pass
-            # Update progress immediately for responsive UI
+            # Update progress immediately for responsive UI.
             self._progress.status_message = (
                 "Stopping training and saving checkpoint..." if save else "Cancelling training..."
             )
@@ -366,8 +358,7 @@ class TrainingBackend:
                 proc.kill()
                 proc.join(timeout = 2.0)
 
-        # Wait for pump thread to finish DB finalization before returning
-        # (8s covers SQLite's 5s lock timeout plus execution overhead)
+        # Wait for pump thread to finish DB finalization (8s covers SQLite's 5s lock timeout).
         if self._pump_thread is not None and self._pump_thread.is_alive():
             self._pump_thread.join(timeout = 8.0)
 
@@ -383,22 +374,19 @@ class TrainingBackend:
     def is_training_active(self) -> bool:
         """Check if training is currently active."""
         with self._lock:
-            # Subprocess alive = active
             if self._proc is not None and self._proc.is_alive():
                 return True
 
-            # Stop was requested and process exited → inactive
             if self._should_stop:
                 return False
 
-            # Check progress state
             p = self._progress
             if p.is_training:
                 return True
             if p.is_completed or p.error:
                 return False
 
-            # Check status message for activity
+            # Infer activity from the status message.
             status_lower = (p.status_message or "").lower()
             if any(
                 k in status_lower
@@ -491,21 +479,19 @@ class TrainingBackend:
             if self._proc is None or self._event_queue is None:
                 return
 
-            # Try to read an event
             event = self._read_queue(self._event_queue, timeout_sec = 0.25)
             if event is not None:
                 self._handle_event(event)
                 continue
 
-            # No event — check if process is still alive
             if self._proc.is_alive():
                 continue
 
-            # Process exited — drain remaining events
+            # Process exited — drain remaining events.
             for e in self._drain_queue(self._event_queue):
                 self._handle_event(e)
 
-            # Mark as done if no explicit complete/error was received
+            # Mark done if no explicit complete/error was received.
             with self._lock:
                 if self._progress.is_training:
                     if self._should_stop:
@@ -540,7 +526,7 @@ class TrainingBackend:
             if etype == "progress":
                 self._progress.step = event.get("step", self._progress.step)
                 self._progress.epoch = event.get("epoch", self._progress.epoch)
-                # loss/lr sanitized below; update progress after coercion
+                # loss/lr sanitized below.
                 _raw_loss = event.get("loss")
                 _raw_lr = event.get("learning_rate")
                 try:
@@ -578,7 +564,7 @@ class TrainingBackend:
                 if status:
                     self._progress.status_message = status
 
-                # Update metric histories — reuse sanitized values above
+                # Update metric histories using sanitized values.
                 step = event.get("step", 0)
                 loss = _safe_loss
                 lr = _safe_lr
@@ -614,7 +600,7 @@ class TrainingBackend:
                     else:
                         eval_loss = None
 
-                # Buffer metric for DB flush (loss/lr already sanitized)
+                # Buffer metric for DB flush.
                 self._metric_buffer.append(
                     {
                         "step": step,
@@ -628,7 +614,7 @@ class TrainingBackend:
                     }
                 )
 
-                # Pick the DB action to run after releasing the lock
+                # Pick the DB action to run after releasing the lock.
                 if not self._db_run_created and self.current_job_id and self._db_config:
                     db_action = "create_run"
                     db_action_kwargs = {
@@ -782,14 +768,14 @@ class TrainingBackend:
         """Flush buffered metrics to the database and update live progress."""
         if not self._metric_buffer or not self.current_job_id or not self._db_run_created:
             return
-        # Cap buffer to bound memory growth
+        # Cap buffer to bound memory growth.
         if len(self._metric_buffer) > 500:
             logger.warning(
                 "Metric buffer exceeded 500 entries (%d) — trimming oldest",
                 len(self._metric_buffer),
             )
             self._metric_buffer = self._metric_buffer[-500:]
-        # Snapshot before insert so metrics arriving during the write survive
+        # Snapshot before insert so metrics arriving during the write survive.
         batch = list(self._metric_buffer)
         try:
             from storage.studio_db import insert_metrics_batch, update_run_progress
@@ -952,9 +938,8 @@ class TrainingBackend:
     def _transfer_to_inference_backend(self) -> bool:
         """Transfer model to inference backend.
 
-        With subprocess-based training, the model lives in the subprocess and is
-        freed when it exits. Inference must load from the saved checkpoint on
-        disk. No-op placeholder.
+        No-op: with subprocess training the model is freed on exit, so inference
+        must load from the saved checkpoint on disk.
         """
         logger.info(
             "_transfer_to_inference_backend: subprocess training — "
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index e9d98909a6..50323478b2 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -73,10 +73,9 @@ _FAST_PATH_HOOKS_SKIP_ENV = "UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS"
 # run_training_process() and isn't GC'd mid-run.
 _WINDOWS_ROCM_GROUPED_MM_LIB = None
 
-# Worker subprocesses inherit the parent env but not its os.add_dll_directory
-# registrations. Replicate main.py's Windows ROCm DLL setup at module load so
-# the first `import torch` finds amdhip64.dll even when HIP_PATH\bin is not on
-# PATH. Handles retained at module scope so they aren't GC'd.
+# Subprocesses don't inherit os.add_dll_directory registrations. Replicate
+# main.py's Windows ROCm DLL setup so the first `import torch` finds
+# amdhip64.dll. Handles retained at module scope so they aren't GC'd.
 _ROCM_DLL_HANDLES: list = []
 if sys.platform == "win32":
 
@@ -91,7 +90,7 @@ if sys.platform == "win32":
         )
 
         def _ver_key(name: str) -> tuple:
-            # Numeric tuple key so "10.0" sorts after "7.0"; non-numeric chunks fall back to string.
+            # Numeric tuple key so "10.0" sorts after "7.0".
             parts = []
             for chunk in name.split("."):
                 try:
@@ -143,21 +142,13 @@ def _model_wants_causal_conv1d(model_name: str) -> bool:
 
 
 def _hipcc_gcc_install_dir() -> str | None:
-    """Return the highest-numbered ``/usr/lib/gcc/x86_64-linux-gnu/<N>`` that has
-    BOTH the gcc runtime dir AND ``/usr/include/c++/<N>`` C++ headers, or
-    ``None`` if no match (or non-Linux / non-x86_64).
+    """Highest-numbered ``/usr/lib/gcc/x86_64-linux-gnu/<N>`` that has BOTH the
+    gcc runtime dir AND ``/usr/include/c++/<N>`` headers, or None.
 
-    Ubuntu 24.04 ships gcc-14 runtime objects but not ``/usr/include/c++/14`` in
-    its default apt set (libstdc++ headers come from ``libstdc++-13-dev``). ROCm
-    clang-20 picks the highest-numbered runtime dir, finds no ``<cstdlib>``, and
-    the HIP source build fails with::
-
-        /opt/rocm-X.Y/lib/llvm/lib/clang/20/include/__clang_hip_runtime_wrapper.h:112:10:
-          fatal error: 'cstdlib' file not found
-
-    Returning a path lets the caller pass ``--gcc-install-dir=<path>`` to clang
-    via ``HIPCC_COMPILE_FLAGS_APPEND``. Mirrors the loop ``bbf004c`` added to
-    ``studio/setup.sh`` for the llama.cpp HIP build (PR #5301).
+    Ubuntu 24.04 ships gcc-14 runtime but not ``/usr/include/c++/14``; ROCm
+    clang-20 picks the highest runtime dir, finds no ``<cstdlib>``, and the HIP
+    build fails. The returned path is passed to clang via
+    ``--gcc-install-dir``. Mirrors bbf004c in studio/setup.sh (PR #5301).
     """
     if not sys.platform.startswith("linux"):
         return None
@@ -307,15 +298,10 @@ def _install_package_wheel_first(
     }
     if is_hip:
         _run_kwargs["timeout"] = 1800
-        # On Ubuntu 24.04 + ROCm clang-20, the HIP source build (causal-conv1d,
-        # mamba-ssm / flash-attn source fallbacks) defaults to
-        # /usr/lib/gcc/x86_64-linux-gnu/14/ which has the runtime dir but no
-        # /usr/include/c++/14 headers, and dies at:
-        #   __clang_hip_runtime_wrapper.h:112:10:
-        #     fatal error: 'cstdlib' file not found
-        # Inject --gcc-install-dir for a gcc whose C++ headers exist. Respect any
-        # pre-existing --gcc-install-dir in HIPCC_COMPILE_FLAGS_APPEND; else
-        # append. Mirrors fix bbf004c in studio/setup.sh (llama.cpp HIP, PR #5301).
+        # On Ubuntu 24.04 + ROCm clang-20 the HIP source build dies on a missing
+        # <cstdlib> (gcc-14 runtime dir lacks C++ headers). Inject
+        # --gcc-install-dir for a gcc whose headers exist, respecting any
+        # pre-existing one. Mirrors bbf004c in studio/setup.sh (PR #5301).
         _existing_flags = os.environ.get("HIPCC_COMPILE_FLAGS_APPEND", "")
         if "--gcc-install-dir" not in _existing_flags:
             _gcc_dir = _hipcc_gcc_install_dir()
@@ -851,16 +837,16 @@ def _ensure_tilelang_backend(event_queue: Any, model_name: str) -> None:
 
 # ── Fast-path hooks ──
 # Wrap transformers' is_{flash_linear_attention,causal_conv1d}_available so the
-# first call (at modeling import) drives the install. Models that query the gate
-# get the install; those that never query it (Llama, Gemma, dense Qwen) pay nothing.
-# UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 falls back to the legacy substring path.
+# first call (at modeling import) drives the install. Models that never query
+# the gate (Llama, Gemma, dense Qwen) pay nothing.
+# UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 falls back to the substring path.
 
 
 def _rebind_in_already_imported_modules(*, attr_name: str, old_obj: Any, new_obj: Any) -> int:
-    """Rebind `attr_name -> new_obj` in every module that already imported `old_obj`.
+    """Rebind `attr_name -> new_obj` in every module that imported `old_obj`.
 
     `from X import Y` creates a local binding that reassigning X.Y won't reach.
-    Uses `__dict__.get` (not `getattr`) to skip lazy `__getattr__` aliases.
+    Uses `__dict__.get` to skip lazy `__getattr__` aliases.
     """
     count = 0
     missing = object()
@@ -1753,10 +1739,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         config: Training config dict with all parameters.
     """
     os.environ["TOKENIZERS_PARALLELISM"] = "false"
-    os.environ["PYTHONWARNINGS"] = "ignore"  # Suppress warnings at C-level before imports
+    os.environ["PYTHONWARNINGS"] = "ignore"  # before imports
 
     # Offline auto-detect: skip ~25s of HF retries per call when DNS is dead.
-    # Scoped to this subprocess (orchestrator spawns a fresh one).
     if "HF_HUB_OFFLINE" not in os.environ:
         import socket as _socket
         import threading as _threading
@@ -1801,8 +1786,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     model_name = config["model_name"]
 
     # ── 0. MLX FAST-PATH (must run before any torch/transformers imports) ──
-    # Apple Silicon uses MLXTrainer directly -- skip transformers version
-    # activation, causal-conv1d install, and torch imports.
+    # Apple Silicon uses MLXTrainer directly -- skip torch imports / installs.
     backend_path = str(Path(__file__).resolve().parent.parent.parent)
     if backend_path not in sys.path:
         sys.path.insert(0, backend_path)
@@ -1855,10 +1839,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         return
 
     # ── 1a. Auto-enable trust_remote_code for NemotronH/Nano models ──
-    # NemotronH has transformers config-parsing bugs needing trust_remote_code=True
-    # as a workaround. Other transformers 5.x models (Qwen3.5, Gemma 4, etc.) are
-    # native and do NOT need it — enabling it bypasses the compiler (disabling fused CE).
-    # NOTE: Must NOT match Llama-Nemotron (standard Llama architecture).
+    # NemotronH needs trust_remote_code=True to work around config-parsing bugs.
+    # Other 5.x models are native and don't need it (it bypasses the compiler,
+    # disabling fused CE). Must NOT match Llama-Nemotron (standard Llama arch).
     _NEMOTRON_TRUST_SUBSTRINGS = ("nemotron_h", "nemotron-h", "nemotron-3-nano")
     _lowered = model_name.lower()
     if (
@@ -1873,18 +1856,12 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         )
 
     # ── 1b. Install fast-path kernel libraries for the chosen model.
-    #
-    # 1) causal-conv1d ALWAYS runs eagerly via the substring path. Some SSM
-    #    modeling files (nemotron_h, falcon_h1, granitemoehybrid) call
-    #    `lazy_load_kernel("causal-conv1d")` directly and never call
-    #    `is_causal_conv1d_available()`, so the runtime hook wouldn't fire.
-    # 2) FLA + tilelang: primary gate is the runtime hook on
-    #    `is_flash_linear_attention_available`. Architectures that query it
-    #    auto-trigger the install; others never pay. `_install_fast_path_hooks`
-    #    also wraps `is_causal_conv1d_available` as defence in depth.
-    # 3) mamba-ssm + flash-attn keep their existing substring / size gates.
-    # 4) `UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1` falls back to the substring
-    #    path for FLA / tilelang.
+    # 1) causal-conv1d ALWAYS runs eagerly via the substring path: some SSM
+    #    modeling files lazy_load it without calling is_causal_conv1d_available.
+    # 2) FLA + tilelang: gated by the runtime hook on
+    #    is_flash_linear_attention_available (hooks also wrap causal-conv1d).
+    # 3) mamba-ssm + flash-attn keep their substring / size gates.
+    # 4) UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 falls back to the substring path.
     try:
         _ensure_causal_conv1d_fast_path(event_queue, model_name)
         if os.getenv(_FAST_PATH_HOOKS_SKIP_ENV) == "1":
@@ -1915,11 +1892,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
         return
 
     # ── 1c. Set fork start method so dataset.map() can multiprocess ──
-    # Parent launched us via spawn, but the compiled SFTTrainer checks
-    # get_start_method() and disables num_proc if not "fork". Linux only: fork
-    # is the default and safe here (no CUDA context yet). macOS defaults to spawn
-    # since Python 3.8 (fork unsafe with Metal/MPS, CoreFoundation) -- do NOT
-    # override there. Windows has no fork.
+    # The compiled SFTTrainer disables num_proc if start method isn't "fork".
+    # Linux only and safe here (no CUDA context yet); macOS/Windows excluded.
     if sys.platform == "linux":
         import multiprocessing as _mp
         try:
@@ -1940,17 +1914,15 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             )
 
     # ── 1d. Stub torchao on Windows ROCm ──
-    # Shared with the export worker; see core/_torchao_stub.py for the full
-    # rationale (torchao -> torch.distributed._functional_collectives crashes on
-    # Windows ROCm: no RCCL backend). No-op off Windows ROCm. Must run before any
-    # import of transformers / unsloth_zoo.
+    # See core/_torchao_stub.py for the rationale (no RCCL backend on Windows
+    # ROCm). No-op elsewhere. Must run before importing transformers/unsloth_zoo.
     from core._torchao_stub import install_torchao_windows_rocm_stub
 
     install_torchao_windows_rocm_stub()
 
     # ── 1e. Ensure torch.distributed helper attrs are present ──
-    # Single-GPU training never inits the process group, so these helpers are
-    # never called — but transformers/trl import them unconditionally.
+    # Single-GPU never inits the process group, but transformers/trl import
+    # these unconditionally.
     _td_stubs = {
         "is_initialized": lambda: False,
         "is_available": lambda: False,
@@ -1978,32 +1950,19 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
 
     # ── 1f. Windows ROCm runtime patches ──
     # torch._grouped_mm has a null HIP kernel on gfx1200 (ROCm ≤ 7.12 Windows),
-    # causing 0xC0000005 (access violation) during training.
-    #
-    # Root cause: JitDecomp autograd decomposition (NOT torch.compile) dispatches
-    # _grouped_mm → _fused_adagrad_ → _grouped_mm HIP → null crash.
-    # TORCHDYNAMO_DISABLE=1 stops the compiler frontend but not JitDecomp, so we
-    # also override the CUDA dispatch key for _grouped_mm with a Python fallback.
-    #
-    # Fixed in torch==2.11.0+rocm7.13.0: the 3-D batch and grouped (with offs)
-    # variants now have working HIP kernels on gfx1200. We gate the override on
-    # HIP < 7.13 so the fixed wheel uses the real GPU kernel.
-    #
-    # Verified: null on torch==2.10.0+rocm7.12.0; fixed on torch==2.11.0+rocm7.13.0.
-    #
-    # Schema: _grouped_mm(Tensor self, Tensor mat2, Tensor? offs=None,
-    #                     Tensor? bias=None, ScalarType? out_dtype=None) -> Tensor
-    #   offs: optional group-split offsets (MoE-style variable-size batches)
-    #
-    # torch is already in sys.modules from section 1e. Module-level
-    # _WINDOWS_ROCM_GROUPED_MM_LIB keeps the registration alive past return / GC.
+    # causing 0xC0000005 during training. Root cause: JitDecomp (not
+    # torch.compile) dispatches _grouped_mm → null crash; TORCHDYNAMO_DISABLE
+    # doesn't cover JitDecomp, so we also override the CUDA dispatch key with a
+    # Python fallback. Fixed in torch==2.11.0+rocm7.13.0, so gate on HIP < 7.13.
+    # Schema: _grouped_mm(self, mat2, offs=None, bias=None, out_dtype=None);
+    #   offs: optional group-split offsets (MoE-style variable-size batches).
+    # _WINDOWS_ROCM_GROUPED_MM_LIB keeps the registration alive past return/GC.
     global _WINDOWS_ROCM_GROUPED_MM_LIB
     if sys.platform == "win32":
         _torch_for_rocm = sys.modules.get("torch")
-        # Broad check: torch.version.hip OR "rocm" in torch.__version__. AMD SDK /
-        # Radeon Windows wheels don't always populate torch.version.hip; without
-        # the broad check the BNB version pin, dynamo-disable, and _grouped_mm
-        # fallback below silently skip (matches the torchao stub gate and main.py).
+        # Broad check (torch.version.hip OR "rocm" in __version__): AMD SDK /
+        # Radeon wheels don't always set torch.version.hip, and without it the
+        # BNB pin, dynamo-disable, and _grouped_mm fallback would silently skip.
         _build_version_for_rocm = (
             getattr(_torch_for_rocm, "__version__", "").lower()
             if _torch_for_rocm is not None
@@ -2017,19 +1976,16 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             )
         )
         if _is_win_rocm_torch:
-            # Disable dynamo (belt-and-suspenders; the JitDecomp patch below is
-            # the real fix, but dynamo off avoids any other compile paths).
+            # Disable dynamo (belt-and-suspenders; the JitDecomp patch is the
+            # real fix, but this avoids other compile paths).
             if "TORCHDYNAMO_DISABLE" not in os.environ:
                 os.environ["TORCHDYNAMO_DISABLE"] = "1"
                 logger.info("Windows ROCm: torch.compile (dynamo) disabled")
 
-            # BNB auto-detects the HIP version from torch.version.hip to pick a
-            # DLL (e.g. "7.13" → rocm713.dll). AMD's Windows BNB prerelease wheel
-            # ships only one rocm DLL whose version suffix may not match the torch
-            # HIP version (e.g. torch==2.11.0+rocm7.13.0 ships HIP 7.13, but the
-            # BNB wheel still ships rocm72.dll). Detect the actual DLL name from
-            # the installed package and override auto-detection. "72" is a safe
-            # fallback if detection fails. Callers may override by pre-setting the var.
+            # BNB picks a rocm DLL from torch.version.hip, but AMD's Windows BNB
+            # wheel may ship a DLL whose suffix doesn't match. Detect the actual
+            # DLL name and override; "72" is a safe fallback. Callers may
+            # pre-set the var to override.
             if "BNB_ROCM_VERSION" not in os.environ:
                 _bnb_rocm_ver = None
                 try:
@@ -2050,9 +2006,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                                 )
                                 if _m:
                                     _all_vers.append(_m.group(1))
-                        # Pick the highest numeric suffix so "713" wins over
-                        # "72" when both are present. Glob order isn't guaranteed,
-                        # so always sort rather than take the first match.
+                        # Highest numeric suffix wins (glob order isn't sorted).
                         if _all_vers:
                             _bnb_rocm_ver = max(_all_vers, key = lambda v: int(v))
                 except Exception:
@@ -2066,11 +2020,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                     _bnb_rocm_ver,
                 )
 
-            # Parse HIP version for the kernel-fix gate below. torch.version.hip
-            # can be "7.13.99004", "7.2.0", etc. AMD SDK / Radeon wheels may leave
-            # it unset and encode the ROCm version in torch.__version__ instead
-            # (e.g. "2.11.0+rocm7.13.0" or "2.9.0+rocmsdk20251116"); fall back to
-            # that string when version.hip is missing.
+            # Parse HIP version for the kernel-fix gate below, falling back to
+            # the rocm version embedded in torch.__version__ when version.hip is
+            # unset (AMD SDK / Radeon wheels).
             def _hip_ver_at_least(major: int, minor: int) -> bool:
                 _hip_str = getattr(getattr(_torch_for_rocm, "version", None), "hip", None)
                 if not _hip_str:
@@ -2081,13 +2033,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                             int(_ver_match.group(1)),
                             int(_ver_match.group(2)),
                         ) >= (major, minor)
-                    # AMD SDK / Radeon Windows wheels encode the build as
-                    # "+rocmsdk<date>" (e.g. "2.9.0+rocmsdk20251116") with no
-                    # explicit rocmX.Y. The rocmsdk format postdates the gfx120X
-                    # null-kernel fix (ROCm 7.13), so any such wheel has working
-                    # HIP kernels. Treat as >= 7.13 rather than returning False
-                    # and installing the Python workaround on a wheel that
-                    # doesn't need it.
+                    # "+rocmsdk<date>" wheels postdate the gfx120X null-kernel
+                    # fix (ROCm 7.13), so treat them as >= 7.13 (no workaround).
                     if "rocmsdk" in _build_version_for_rocm:
                         logger.debug(
                             "Windows ROCm: AMD SDK wheel detected (%r); "
@@ -2121,9 +2068,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                     )
                     return False
 
-            # _grouped_mm HIP kernel was null on gfx1200 in ROCm ≤ 7.12 (causing
-            # 0xC0000005); fixed in ROCm 7.13 (torch 2.11+). Install the Python
-            # fallback only on affected versions so 7.13+ gets the real GPU kernel.
+            # Install the Python fallback only on affected versions (ROCm ≤ 7.12)
+            # so 7.13+ uses the real GPU kernel.
             if not _hip_ver_at_least(7, 13):
                 try:
                     import warnings as _warnings
@@ -2140,9 +2086,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                         """Python mm/bmm fallback for _grouped_mm on gfx1200 (null HIP kernel, ROCm ≤ 7.12)."""
                         _t = _torch_for_rocm
                         if offs is None:
-                            # No offsets: match the real op — (M, K) x (K, N) ->
-                            # mm, or 3-D batched -> bmm. An unconditional torch.mm
-                            # previously raised "self must be a matrix" on 3-D MoE.
+                            # No offsets: 2-D -> mm, 3-D batched -> bmm
+                            # (unconditional mm broke 3-D MoE).
                             if self.dim() == 3 and mat2.dim() == 3:
                                 result = _t.bmm(self.contiguous(), mat2.contiguous())
                             elif self.dim() == 3 and mat2.dim() == 2:
@@ -2154,8 +2099,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                             else:
                                 result = _t.mm(self.contiguous(), mat2.contiguous())
                         else:
-                            # Grouped: offs[i] is the exclusive end-row of group
-                            # i in `self`; mat2 may be 3-D or 2-D.
+                            # Grouped: offs[i] is the exclusive end-row of group i.
                             offs_list = offs.tolist()
                             pieces = []
                             prev = 0
@@ -2216,17 +2160,12 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 )
 
     # ── 1g. ROCm OOM guard ──
-    # On RDNA 4 (gfx1200/gfx1201) and other ROCm GPUs, exhausting VRAM can hang
-    # the HIP driver and freeze the whole system instead of raising. So
-    # set_per_process_memory_fraction caps the HIP allocator and PyTorch raises
-    # OutOfMemoryError before the hardware limit, giving the UI a clean error.
-    # ROCm only -- NVIDIA CUDA has a graceful OOM path.
-    # Unified-memory APUs (gfx1150 Strix Point / gfx1151 Strix Halo) share GPU
-    # and system RAM in one pool: 0.90 of 128 GB starves the OS, so use 0.80.
-    # Primary classifier: gcnArchName (stable within a product family,
-    # naming-independent). AMD SDK / Radeon wheels may omit it or use a variant
-    # spelling, so try several attrs then fall back to device-name markers.
-    # Non-fatal: silently skipped if torch is not importable.
+    # On ROCm, exhausting VRAM can hang the HIP driver instead of raising.
+    # set_per_process_memory_fraction caps the allocator so PyTorch raises
+    # OutOfMemoryError first (NVIDIA already has a graceful OOM path).
+    # Unified-memory APUs (gfx1150/gfx1151) share GPU+system RAM, so use 0.80
+    # vs 0.90 for discrete. Classify via gcnArchName, else device-name markers.
+    # Non-fatal: skipped if torch is not importable.
     if _hw.IS_ROCM:
         try:
             import torch as _torch_mem
@@ -2356,9 +2295,8 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
     stop_thread.start()
 
     # ── 4. Execute the training pipeline ──
-    # Order: detect → dataset → model → prepare → train. Dataset processing
-    # (incl. LLM-assisted detection) runs BEFORE model loading so both never
-    # occupy VRAM at once.
+    # Order: detect → dataset → model → prepare → train. Dataset processing runs
+    # BEFORE model loading so both never occupy VRAM at once.
     try:
         hf_token = config.get("hf_token", "")
         hf_token = hf_token if hf_token and hf_token.strip() else None
@@ -2403,25 +2341,6 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
             dataset = dataset_result
             eval_dataset = None
 
-        # [DEBUG] Print first sample before model is loaded
-        # dataset is a dict {"dataset": <Dataset>, "detected_format": ..., ...}
-        # or a raw Dataset for audio paths
-        # try:
-        #     ds = dataset["dataset"] if isinstance(dataset, dict) else dataset
-        #     print(
-        #         f"\n[DEBUG] Dataset loaded BEFORE model. type={type(ds).__name__}, len={len(ds)}",
-        #         flush = True,
-        #     )
-        #     print(f"[DEBUG] Columns: {ds.column_names}", flush = True)
-        #     sample = ds[0]
-        #     preview = {k: str(v)[:300] for k, v in sample.items()}
-        #     print(f"[DEBUG] First sample: {preview}\n", flush = True)
-        # except Exception as e:
-        #     print(
-        #         f"[DEBUG] Could not preview first sample: {type(e).__name__}: {e}",
-        #         flush = True,
-        #     )
-
         # Disable eval if eval_steps <= 0
         eval_steps = config.get("eval_steps", 0.00)
         if eval_steps is not None and float(eval_steps) <= 0:
diff --git a/studio/backend/loggers/config.py b/studio/backend/loggers/config.py
index 35e2764fe9..8977ab4907 100644
--- a/studio/backend/loggers/config.py
+++ b/studio/backend/loggers/config.py
@@ -3,15 +3,8 @@
 
 """Structured logging configuration via structlog.
 
-Centralized config with environment-specific formats and processors for
-development and production.
-
-Key features:
-- Environment-specific formatting (JSON for prod, console for dev)
-- ISO timestamps
-- Context variable integration
-- Log level filtering
-- Logger caching for performance
+Environment-specific formats (JSON for prod, console for dev), ISO timestamps,
+context-var integration, log-level filtering, and logger caching.
 """
 
 import logging
@@ -25,11 +18,7 @@ from loggers.handlers import filter_sensitive_data
 
 
 class LogConfig:
-    """Structured logging configuration for the application.
-
-    Static method to configure structlog with environment-specific
-    formatting and processors.
-    """
+    """Structured logging configuration for the application."""
 
     @staticmethod
     def setup_logging(
diff --git a/studio/backend/loggers/handlers.py b/studio/backend/loggers/handlers.py
index 419e041a72..f03af7b40e 100644
--- a/studio/backend/loggers/handlers.py
+++ b/studio/backend/loggers/handlers.py
@@ -1,18 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Logging handlers and middleware for structured logging.
+"""Structured logging handlers and middleware.
 
-FastAPI middleware + structlog processors for:
-- Request/response logging with timing
-- Sensitive data filtering
-- Structured logging config
-- Error handling with context
-
-Key components:
-- LoggingMiddleware: request/response logging
-- filter_sensitive_data: structlog processor for sanitization
-- get_logger: factory for structured loggers
+LoggingMiddleware (request/response logging with timing),
+filter_sensitive_data (structlog processor for sanitization), and
+get_logger (factory for structured loggers).
 """
 
 import re
@@ -107,8 +100,5 @@ def filter_sensitive_data(logger, method_name, event_dict):
 
 
 def get_logger(name: str) -> structlog.BoundLogger:
-    """Get a bound structured logger for a module.
-    Args:
-        name: Usually __name__ of the module
-    """
+    """Get a bound structured logger for a module (name is usually __name__)."""
     return structlog.get_logger(name)
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 1bc96c6206..104d557eea 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -27,8 +27,7 @@ if sys.platform == "win32":
             _val = os.environ.get(_var)
             if _val:
                 candidates.append(os.path.join(_val, "bin"))
-        # 2. Standard AMD installer location: C:\Program Files\AMD\ROCm\<ver>\bin
-        #    Scan all installed versions, newest first.
+        # 2. AMD installer: C:\Program Files\AMD\ROCm\<ver>\bin, newest first.
         _default_root = os.path.join(
             os.environ.get("ProgramFiles", r"C:\Program Files"), "AMD", "ROCm"
         )
@@ -62,15 +61,11 @@ if sys.platform == "win32":
     del _add_rocm_dll_dirs
 
     # ── Windows AMD ROCm: set BNB_ROCM_VERSION before any bitsandbytes import ─
-    # bitsandbytes on Windows ROCm loads libbitsandbytes_rocm<ver>.dll where
-    # <ver> comes from torch.version.hip (e.g. "7.13..." → "713"). The installed
-    # BNB wheel ships rocm72.dll (not rocm713.dll), so without this the server
-    # crashes with "Configured ROCm binary not found". Detect the available DLL,
-    # fall back to "72", and set BNB_ROCM_VERSION before any bitsandbytes import
-    # (mirrors worker.py). Gate on the rocm bnb DLL (the file this configures) or
-    # HIP_PATH/ROCM_PATH, not torch.version.hip: that needed importing torch on
-    # every Windows host (NVIDIA/CPU too), adding startup seconds. Radeon wheels
-    # without HIP_PATH still ship the rocm bnb DLL, so they're covered.
+    # bitsandbytes derives the rocm<ver>.dll name from torch.version.hip, but the
+    # wheel ships rocm72.dll, so the server crashes ("Configured ROCm binary not
+    # found") without this. Detect the shipped DLL and fall back to "72" (mirrors
+    # worker.py). Gate on the rocm bnb DLL / HIP_PATH rather than torch.version.hip
+    # to avoid importing torch on every Windows host.
     if "BNB_ROCM_VERSION" not in os.environ:
         import glob as _glob
         import logging as _logging
@@ -164,14 +159,11 @@ _STUDIO_INSTALL_ID_RE = _re.compile(r"^[0-9a-f]{64}$")
 
 
 def _read_studio_install_id() -> str:
-    """Per-install opaque id written by install.sh / install.ps1 at
-    $STUDIO_HOME/share/studio_install_id. Returns "" when the file is absent
-    (pre-PR install, or fresh tree never run through the installer) or holds
-    anything other than a 64-char lowercase-hex token; then /api/health emits
-    "" and the launcher's _check_health falls back to "no baked id, accept any
-    healthy Unsloth backend". Replaces a previous sha256(resolved_install_path)
-    so the field carries no install-path info for callers reaching /api/health
-    (relevant when Studio runs with -H 0.0.0.0)."""
+    """Per-install opaque id at $STUDIO_HOME/share/studio_install_id.
+
+    Returns "" when absent or not a 64-char lowercase-hex token; then
+    /api/health emits "" and the launcher accepts any healthy backend.
+    Carries no install-path info (matters when Studio runs -H 0.0.0.0)."""
     try:
         token = (_STUDIO_ROOT_RESOLVED / "share" / "studio_install_id").read_text().strip()
     except (OSError, ValueError):
@@ -183,20 +175,16 @@ _STUDIO_ROOT_ID_CACHE: str = _read_studio_install_id()
 
 
 def _studio_root_id() -> str:
-    """Same-install discriminator for /api/health: a per-install opaque token
-    written once by the installer and read once at module import. Empty when no
-    installer token is present; the launcher contract treats "" as "no baked id,
-    accept any healthy backend"."""
+    """Same-install discriminator for /api/health (cached at import).
+
+    Empty when no installer token is present; the launcher treats "" as
+    "accept any healthy backend"."""
     return _STUDIO_ROOT_ID_CACHE
 
 
-# Fix broken Windows registry MIME types. Some Windows installs map .js to
-# "text/plain" in the registry (HKCR\.js\Content Type). Python's mimetypes reads
-# from the registry, and Starlette's StaticFiles uses mimetypes.guess_type() for
-# Content-Type. Browsers strictly MIME-check ES module scripts
-# (<script type="module">) and refuse .js served as text/plain, giving a blank
-# page. Calling add_type() *before* StaticFiles is instantiated forces the
-# correct types regardless of the OS registry.
+# Fix broken Windows registry MIME types: some installs map .js to text/plain,
+# which mimetypes (hence StaticFiles) inherits and browsers reject for ES
+# modules. add_type() before StaticFiles forces correct types.
 if sys.platform == "win32":
     mimetypes.add_type("application/javascript", ".js")
     mimetypes.add_type("text/css", ".css")
@@ -215,7 +203,6 @@ from fastapi.responses import FileResponse, HTMLResponse, Response
 from pathlib import Path
 from datetime import datetime
 
-# Import routers
 from routes import (
     auth_router,
     chat_history_router,
@@ -296,16 +283,14 @@ def _desktop_owner() -> dict[str, str] | None:
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Startup: detect hardware, seed default admin if needed. Shutdown: clean up compiled cache."""
-    # Clean up stale compiled cache from previous runs
     clear_unsloth_compiled_cache()
 
-    # Remove stale .venv_overlay from previous versions — no longer used.
-    # Version switching now uses .venv_t5/ (pre-installed by setup.sh).
+    # Remove stale .venv_overlay from old versions; switching now uses .venv_t5/.
     overlay_dir = Path(__file__).resolve().parent.parent.parent / ".venv_overlay"
     if overlay_dir.is_dir():
         shutil.rmtree(overlay_dir, ignore_errors = True)
 
-    # Detect hardware first — sets DEVICE global used everywhere
+    # Detect hardware first — sets the DEVICE global used everywhere.
     detect_hardware()
 
     # llama.cpp probes: capability (MTP support) + freshness (release age).
@@ -382,12 +367,10 @@ async def lifespan(app: FastAPI):
     else:
         app.state.bootstrap_password = storage.get_bootstrap_password()
     yield
-    # Cleanup
     _hw_module.DEVICE = None
     clear_unsloth_compiled_cache()
 
 
-# Create FastAPI app
 app = FastAPI(
     title = "Unsloth UI Backend",
     version = UNSLOTH_VERSION,
@@ -395,7 +378,6 @@ app = FastAPI(
     lifespan = lifespan,
 )
 
-# Initialize structured logging
 from loggers.config import LogConfig
 from loggers.handlers import LoggingMiddleware
 
@@ -432,19 +414,14 @@ def _build_csp(script_nonce: "str | None" = None) -> str:
     script_src = "script-src 'self'"
     if script_nonce:
         script_src += f" 'nonce-{script_nonce}'"
-    # In Colab the parent frame can be colab.research.google.com, a multi-level
-    # *.prod.colab.dev subdomain (e.g. foo.region.prod.colab.dev — CSP wildcards
-    # only match one level, so *.prod.colab.dev misses these), or a sandboxed
-    # null-origin output iframe. Use '*' to allow any ancestor; Colab is already
-    # a sandboxed single-user environment.
+    # Colab parent frames span multi-level *.prod.colab.dev subdomains (CSP
+    # wildcards match one level only) and null-origin iframes; use '*' since
+    # Colab is already a sandboxed single-user environment.
     frame_ancestors = "*" if _IS_COLAB else "'none'"
 
-    # In Colab the frontend is served over the Colab reverse-proxy at an HTTPS
-    # *.prod.colab.dev URL. Colab's kernel layer and output-iframe scaffolding
-    # inject scripts from *.prod.colab.dev and *.googleusercontent.com, and
-    # fetch/WebSocket to those origins. Widen script-src and connect-src in
-    # Colab mode so those aren't blocked. 'unsafe-inline' for scripts is still
-    # omitted; our inline script uses a nonce.
+    # In Colab, the kernel/output scaffolding injects scripts and fetch/WS from
+    # *.prod.colab.dev and *.googleusercontent.com, so widen script-src and
+    # connect-src for those. Scripts still use a nonce, not 'unsafe-inline'.
     if _IS_COLAB:
         script_src += " https://*.prod.colab.dev https://*.googleusercontent.com"
         connect_src = (
@@ -693,7 +670,6 @@ async def _recipes_redirect(rest: str = ""):
     return _RedirectResponse(url = target, status_code = 308)
 
 
-# CORS middleware
 _api_only = os.environ.get("UNSLOTH_API_ONLY") == "1"
 _cors_origins = ["*"]
 if _api_only:
@@ -729,9 +705,7 @@ app.include_router(inference_router, prefix = "/api/inference", tags = ["inferen
 # OpenAI-compat prefix below.
 app.include_router(inference_studio_router, prefix = "/api/inference", tags = ["inference"])
 
-# OpenAI-compatible endpoints: mount the same inference router at /v1 so
-# external tools (Open WebUI, SillyTavern, etc.) can use the standard
-# /v1/chat/completions path.
+# OpenAI-compatible: mount the inference router at /v1 for external tools.
 app.include_router(inference_router, prefix = "/v1", tags = ["openai-compat"])
 app.include_router(providers_router, prefix = "/api/providers", tags = ["providers"])
 app.include_router(settings_router, prefix = "/api/settings", tags = ["settings"])
@@ -747,14 +721,12 @@ app.include_router(training_history_router, prefix = "/api/train", tags = ["trai
 
 @app.get("/api/health")
 async def health_check(request: Request):
-    """Liveness plus launcher capability bits; install fingerprint gated on a valid bearer.
+    """Liveness plus launcher capability bits; host fingerprint gated on a bearer.
 
-    Unauthenticated callers (Tauri watchdog, frontend bootstrap polls) need
-    ``service`` / ``studio_root_id`` / ``chat_only`` / ``desktop_*`` / ``native_path_leases_supported``
-    to (a) re-adopt a sibling backend across restarts and (b) gate UI surfaces
-    before a token is available. None of those leak install path or version.
-    ``version`` / ``studio_version`` / ``device_type`` require a bearer since
-    they fingerprint the host.
+    Unauthenticated callers get non-sensitive fields (service, studio_root_id,
+    chat_only, desktop_*, native_path_leases_supported) to re-adopt a sibling
+    backend and gate UI before a token exists. version / studio_version /
+    device_type require a bearer since they fingerprint the host.
     """
     base = {
         "status": "healthy",
@@ -837,11 +809,9 @@ async def shutdown_server(request: Request, current_subject: str = Depends(get_c
 async def get_system_info(current_subject: str = Depends(get_current_subject)):
     """Get system information.
 
-    Gated behind auth: the response includes platform, Python version, GPU name,
-    memory total, and ML package set -- enough to fingerprint a host. Studio's
-    chat-only design assumes only the local user reaches /api/system; in
-    -H 0.0.0.0 / Colab / Tauri-relayed setups that breaks unless we require a
-    bearer.
+    Auth-gated: the response (platform, Python/GPU, memory, ML packages) can
+    fingerprint a host, which matters in -H 0.0.0.0 / Colab / Tauri-relayed
+    setups where remote callers can reach /api/system.
     """
     import platform
     import psutil
@@ -860,8 +830,8 @@ async def get_system_info(current_subject: str = Depends(get_current_subject)):
     return {
         "platform": platform.platform(),
         "python_version": platform.python_version(),
-        # Centralized _backend_label so /api/system reports "rocm" on AMD hosts
-        # instead of "cuda", matching /api/hardware and /api/gpu-visibility.
+        # _backend_label so /api/system reports "rocm" (not "cuda") on AMD,
+        # matching /api/hardware and /api/gpu-visibility.
         "device_backend": _backend_label(get_device()),
         "cpu_count": psutil.cpu_count(),
         "memory": {
@@ -898,10 +868,9 @@ async def get_hardware_info(current_subject: str = Depends(get_current_subject))
 def _strip_crossorigin(html_bytes: bytes) -> bytes:
     """Remove ``crossorigin`` attributes from script/link tags.
 
-    Vite adds ``crossorigin`` by default, forcing CORS mode on font subresource
-    loads. Over plain HTTP, Firefox HTTPS-Only Mode doesn't exempt CORS font
-    requests, so all @font-face downloads fail silently. Stripping the attribute
-    makes them same-origin fetches that work on any protocol.
+    Vite's default ``crossorigin`` forces CORS mode on font loads, which
+    Firefox HTTPS-Only Mode breaks over plain HTTP; stripping it makes them
+    same-origin fetches that work on any protocol.
     """
     html = html_bytes.decode("utf-8")
     html = _re.sub(r'\s+crossorigin(?:="[^"]*")?', "", html)
@@ -983,10 +952,10 @@ def _canonical_origin(scheme: str, netloc: str) -> Optional[tuple[str, str, int]
 
 def _is_same_origin_request(request: Request) -> bool:
     """True when Origin is missing or matches request's scheme://host:port.
-    Top-level same-document GETs omit Origin, so missing counts as same-origin.
-    Callers must also emit ``Vary: Origin``. Both sides are canonicalised via
-    :func:`_canonical_origin` so default-port stripping and scheme/host case
-    don't misclassify same-origin requests as cross-origin.
+
+    Missing Origin counts as same-origin (top-level GETs omit it). Both sides
+    are canonicalised via :func:`_canonical_origin`; callers must emit
+    ``Vary: Origin``.
     """
     origin = request.headers.get("origin")
     if origin is None:
@@ -1021,7 +990,6 @@ def setup_frontend(app: FastAPI, build_path: Path):
     if not build_path.exists():
         return False
 
-    # Mount assets
     assets_dir = build_path / "assets"
     if assets_dir.exists():
         app.mount("/assets", StaticFiles(directory = assets_dir), name = "assets")
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index d7ce674141..9005f087be 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -106,9 +106,7 @@ class UnloadRequest(BaseModel):
 
 
 class ValidateModelRequest(BaseModel):
-    """Lightweight check whether a model identifier *can be resolved* into a
-    ModelConfig. Does NOT load weights into GPU memory.
-    """
+    """Check whether an identifier resolves to a ModelConfig; does NOT load weights."""
 
     model_path: str = Field(..., description = "Model identifier or local path")
     native_path_lease: Optional[str] = Field(
@@ -123,8 +121,7 @@ class ValidateModelRequest(BaseModel):
 class ValidateModelResponse(BaseModel):
     """Result of model validation.
 
-    valid == True means ModelConfig.from_identifier() succeeded and basic
-    introspection (GGUF / LoRA / vision flags) is available.
+    valid == True means from_identifier() succeeded and GGUF/LoRA/vision flags are available.
     """
 
     valid: bool = Field(..., description = "Whether the model identifier looks valid")
@@ -239,9 +236,8 @@ class UnloadResponse(BaseModel):
 class LoadProgressResponse(BaseModel):
     """Progress of the active GGUF load, sampled on demand.
 
-    Drives a real progress bar during the post-download warmup window
-    (mmap + CUDA upload), instead of a generic "Starting model..." spinner
-    that freezes for minutes on large MoE models.
+    Drives a real progress bar during the post-download warmup (mmap + CUDA upload)
+    instead of a spinner that freezes for minutes on large MoE models.
     """
 
     phase: Optional[str] = Field(
@@ -399,13 +395,9 @@ class ImageContentPart(BaseModel):
 class InputDocumentContentPart(BaseModel):
     """Document (PDF / file) content part in a multimodal message.
 
-    Studio-normalised shape. The frontend sends either
-    ``{type:"input_document", file_data:"data:application/pdf;base64,..."}``
-    or ``{type:"input_document", file_url:"https://..."}``, plus optional
-    ``filename`` and ``media_type``. ``external_provider`` maps this onto
-    Anthropic's ``document`` block or OpenAI Responses' ``input_file`` block
-    for vision-capable providers; non-vision providers drop the part
-    (handled in ``_build_external_messages``).
+    Studio-normalised shape (file_data or file_url, plus optional filename/media_type).
+    Mapped onto Anthropic ``document`` / OpenAI ``input_file`` for vision providers;
+    dropped for non-vision providers.
     """
 
     type: Literal["input_document"]
@@ -430,10 +422,8 @@ class InputDocumentContentPart(BaseModel):
 class OpenAIReasoningContentPart(BaseModel):
     """OpenAI Responses reasoning item paired with a tool output.
 
-    Reasoning models can require the previous ``reasoning`` output item to be
-    replayed immediately before an ``image_generation_call`` id when manually
-    managing Responses context. OpenAI-only; routes strip it for every other
-    provider before proxying.
+    Reasoning models may require this replayed before an ``image_generation_call``
+    id. OpenAI-only; routes strip it for other providers before proxying.
     """
 
     type: Literal["reasoning"]
@@ -445,12 +435,9 @@ class OpenAIReasoningContentPart(BaseModel):
 class ImageGenerationCallContentPart(BaseModel):
     """OpenAI Responses image_generation call reference.
 
-    OpenAI accepts prior ``image_generation_call`` items in the next Responses
-    ``input`` array so follow-up prompts can edit or refine a generated image
-    without resending the base64 payload. The frontend forwards this as a
-    synthetic assistant content part when building the next request;
-    ``external_provider`` maps it back to the provider-specific top-level
-    input item.
+    Prior ``image_generation_call`` items let follow-up prompts edit a generated
+    image without resending the payload. The frontend forwards it as a synthetic
+    assistant part; ``external_provider`` maps it back to a top-level input item.
     """
 
     type: Literal["image_generation_call"]
@@ -462,17 +449,12 @@ class ImageGenerationCallContentPart(BaseModel):
 
 
 class CompactionContentPart(BaseModel):
-    """Anthropic server-side compaction state, attached to an assistant
-    message for round-tripping on the next turn.
+    """Anthropic server-side compaction state, round-tripped on the next turn.
 
-    When Anthropic compacts during a request, the response carries a
-    ``{"type": "compaction", "content": "<summary>"}`` block on the assistant
-    message. The chat-adapter persists it; the next turn's outbound request
-    must forward it back so Anthropic recognises the existing compaction state
-    and doesn't re-summarise from scratch. See
-    ``external_provider._stream_anthropic`` for the wire-side handling and
+    Anthropic returns a ``compaction`` block on the assistant message; the next
+    request must forward it back so Anthropic reuses the compaction state instead
+    of re-summarising. See ``external_provider._stream_anthropic`` and
     https://platform.claude.com/docs/en/build-with-claude/compaction
-    for the upstream contract.
     """
 
     type: Literal["compaction"]
@@ -508,10 +490,9 @@ ContentPart = Annotated[
 class ChatMessage(BaseModel):
     """Single message in a chat conversation.
 
-    ``content`` is a string or list of multimodal content parts. Assistant
-    messages with only ``tool_calls`` may set ``content=None``. Missing
-    ``tool_call_id`` on ``role="tool"`` is resolved at the
-    ``ChatCompletionRequest`` layer by walking back to the preceding assistant.
+    ``content`` is a string or list of multimodal parts. Assistant messages with
+    only ``tool_calls`` may set ``content=None``. Missing ``tool_call_id`` on
+    ``role="tool"`` is resolved at the ``ChatCompletionRequest`` layer.
     """
 
     role: Literal["system", "user", "assistant", "tool"] = Field(..., description = "Message role")
@@ -568,10 +549,8 @@ class ChatCompletionRequest(BaseModel):
     Non-OpenAI extension fields are marked with 'x-unsloth'.
     """
 
-    # Accept unknown fields so future OpenAI fields (seed, response_format,
-    # logprobs, frequency_penalty, etc.) aren't silently dropped by Pydantic
-    # before route code runs. Mirrors AnthropicMessagesRequest and
-    # ResponsesRequest.
+    # Accept unknown fields so future OpenAI fields aren't dropped before route
+    # code runs. Mirrors AnthropicMessagesRequest and ResponsesRequest.
     model_config = {"extra": "allow"}
 
     model: str = Field(
@@ -729,16 +708,13 @@ class ChatCompletionRequest(BaseModel):
     @field_validator("enable_prompt_caching", mode = "before")
     @classmethod
     def _coerce_enable_prompt_caching(cls, value: Any) -> Any:
-        """Preserve the pre-PR coercion. The field was once Optional[bool], so
-        callers historically sent JSON strings `"true"` / `"false"` that
-        Pydantic v1 coerced. Widening to Optional[Union[bool, str]] for Gemini
-        cache resource names lets `"false"` slip through as truthy; coerce the
-        canonical bool literals back so explicit opt-outs stay opt-out."""
+        """Coerce JSON bool strings back to bool. Widening to Union[bool, str] for
+        Gemini cache names would let `"false"` read as truthy, so canonical bool
+        literals are coerced to keep explicit opt-outs working."""
         if isinstance(value, str):
             lowered = value.strip().lower()
-            # Match Pydantic v1's BooleanField coercion table (yes/y/on/t/1
-            # and no/n/off/f/0) so old opt-outs still parse. Anything else
-            # stays a string for Gemini's cachedContent resource path.
+            # Match Pydantic v1's bool coercion table; anything else stays a
+            # string for Gemini's cachedContent resource path.
             if lowered in ("true", "t", "1", "yes", "y", "on"):
                 return True
             if lowered in ("false", "f", "0", "no", "n", "off"):
@@ -828,8 +804,7 @@ class ChatCompletionRequest(BaseModel):
         unconsumed tool_call; synth a random id only if none exists. A user
         turn breaks the lookup.
         """
-        # Pre-mark explicit ids first so a sibling missing-id result doesn't
-        # steal one already claimed by name.
+        # Pre-mark explicit ids so a missing-id sibling can't steal a claimed one.
         consumed: set[tuple[int, int]] = set()
 
         def _mark_consumed(start_idx: int, tool_call_id: str) -> None:
@@ -891,10 +866,10 @@ class ChatCompletionRequest(BaseModel):
 
 
 class OpenAIContainerRequest(BaseModel):
-    """Shared body for the three OpenAI container endpoints (list / create /
-    delete). Carries the encrypted API key + base URL so the route handler
-    can decrypt it and proxy to the user's OpenAI account. Same pattern as the
-    inference proxy endpoints — keeps the key off backend persistent storage.
+    """Shared body for the OpenAI container endpoints (list / create / delete).
+
+    Carries the encrypted API key + base URL so the route can decrypt and proxy
+    to the user's account, keeping the key off backend persistent storage.
     """
 
     encrypted_api_key: str = Field(
@@ -1041,11 +1016,9 @@ class ResponsesInputImagePart(BaseModel):
 class ResponsesOutputTextPart(BaseModel):
     """Assistant ``output_text`` content part replayed on subsequent turns.
 
-    When a client (OpenAI Codex CLI, OpenAI Python SDK agents) loops on a
-    stateless Responses endpoint, prior assistant messages round-trip as
-    ``{"role":"assistant","content":[{"type":"output_text","text":...,
-    "annotations":[],"logprobs":[]}]}``. We keep the text and ignore the
-    annotations/logprobs metadata when flattening into Chat Completions.
+    Clients looping on a stateless Responses endpoint round-trip prior assistant
+    messages as ``output_text`` parts; we keep the text and ignore the
+    annotations/logprobs when flattening into Chat Completions.
     """
 
     type: Literal["output_text"]
@@ -1057,10 +1030,9 @@ class ResponsesOutputTextPart(BaseModel):
 
 
 class ResponsesUnknownContentPart(BaseModel):
-    """Catch-all for content-part types we don't model explicitly.
+    """Catch-all for unmodelled content-part types.
 
-    Keeps validation green when a client sends newer part types (e.g.
-    ``input_audio``, ``input_file``) we haven't mapped; these are skipped
+    Keeps validation green for newer part types (e.g. ``input_audio``); skipped
     during normalisation rather than rejected with a 422.
     """
 
@@ -1084,17 +1056,15 @@ class ResponsesInputMessage(BaseModel):
     role: Literal["system", "user", "assistant", "developer"]
     content: Union[str, list[ResponsesContentPart]]
 
-    # Codex (gpt-5.3-codex+) attaches a `phase` field ("commentary" |
-    # "final_answer") to assistant messages and requires clients to preserve
-    # it across turns. We accept and round-trip it; llama-server ignores it.
+    # Codex attaches a `phase` field to assistant messages and requires clients
+    # to preserve it across turns; we round-trip it, llama-server ignores it.
     model_config = {"extra": "allow"}
 
 
 class ResponsesFunctionCallInputItem(BaseModel):
     """A prior assistant function_call replayed in a multi-turn Responses input.
 
-    The Responses API represents tool calls as top-level input items (not
-    nested in assistant messages), correlated across turns by ``call_id``.
+    Tool calls are top-level input items (not nested), correlated by ``call_id``.
     """
 
     type: Literal["function_call"]
@@ -1125,12 +1095,10 @@ class ResponsesFunctionCallOutputInputItem(BaseModel):
 
 
 class ResponsesUnknownInputItem(BaseModel):
-    """Catch-all for Responses input item types we don't model explicitly.
+    """Catch-all for unmodelled Responses input item types.
 
-    Covers ``reasoning`` items (replayed from prior o-series / gpt-5 turns)
-    and any future item types. Dropped during normalisation (llama-server
-    GGUFs can't consume them), but keeping them in the request-model union
-    stops unrelated turns from failing validation with a 422.
+    Covers ``reasoning`` items and future types. Dropped during normalisation
+    (GGUFs can't consume them), but kept in the union so unrelated turns don't 422.
     """
 
     type: str
@@ -1141,12 +1109,9 @@ class ResponsesUnknownInputItem(BaseModel):
 def _responses_input_item_discriminator(v: Any) -> str:
     """Route a Responses input item to the correct tagged variant.
 
-    Pydantic's smart-union matching fails when one union variant is tagged
-    with a strict ``Literal`` (``function_call`` / ``function_call_output``)
-    and the incoming dict has a different ``type``: other variants' errors are
-    hidden and the outer ``Union[str, list[...]]`` reports a misleading "Input
-    should be a valid string". An explicit discriminator makes routing
-    deterministic and lets us fall through to the catch-all.
+    Pydantic's smart-union matching misreports errors when a strict-``Literal``
+    variant doesn't match; an explicit discriminator makes routing deterministic
+    and falls through to the catch-all.
     """
     if isinstance(v, dict):
         t = v.get("type")
@@ -1177,10 +1142,8 @@ ResponsesInputItem = Annotated[
 class ResponsesFunctionTool(BaseModel):
     """Flat function-tool definition for the Responses API request.
 
-    Unlike Chat Completions (which nests ``{"name": ..., "parameters": ...}``
-    under a ``"function"`` key), the Responses API uses a flat shape with
-    ``type``, ``name``, ``description``, ``parameters``, ``strict`` at the top
-    level of each tool entry.
+    Unlike Chat Completions (nested under a ``"function"`` key), this uses a flat
+    shape with ``type``/``name``/``description``/``parameters``/``strict`` at top level.
     """
 
     type: Literal["function"]
@@ -1204,11 +1167,9 @@ class ResponsesRequest(BaseModel):
     max_output_tokens: Optional[int] = Field(None, ge = 1)
     stream: bool = Field(False, description = "Whether to stream the response via SSE")
 
-    # OpenAI function-calling fields, forwarded to llama-server via the Chat
-    # Completions pass-through (see routes/inference.py). Plain list so
-    # built-in tool shapes (``web_search``, ``file_search``, ``mcp``, ...)
-    # round-trip without validation errors; the translator forwards only
-    # ``type=="function"`` entries.
+    # OpenAI function-calling fields, forwarded via the Chat Completions
+    # pass-through. Plain list so built-in tool shapes round-trip without
+    # validation errors; the translator forwards only ``type=="function"`` entries.
     tools: Optional[list[dict]] = Field(
         None,
         description = (
@@ -1264,9 +1225,7 @@ class ResponsesOutputMessage(BaseModel):
 class ResponsesOutputFunctionCall(BaseModel):
     """A function-call output item in the Responses API response.
 
-    Unlike Chat Completions (tool calls nested in the assistant message), the
-    Responses API emits each tool call as its own top-level ``output`` item so
-    clients can correlate results via ``call_id`` on the next turn.
+    Each tool call is its own top-level ``output`` item, correlated via ``call_id``.
     """
 
     type: Literal["function_call"] = "function_call"
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index 829be12c91..4a3303c734 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -10,9 +10,8 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 from typing import Any, Optional, List, Dict, Literal
 
 
-# ASCII integer with an optional single sign. Used by _check_vision_image_size
-# to reject "++512", "--256", and Unicode-digit strings ("５１２", "٥١٢") that
-# would otherwise slip through str.isdigit() + int().
+# ASCII integer, optional single sign. Rejects "++512" and Unicode digits
+# ("５１２") that slip through str.isdigit() + int().
 _INT_RE = re.compile(r"[+-]?[0-9]+")
 
 
@@ -131,8 +130,7 @@ class TrainingStartRequest(BaseModel):
     @field_validator("num_epochs")
     @classmethod
     def _check_num_epochs(cls, v: int) -> int:
-        # 0 is a sentinel meaning "use max_steps instead"; the frontend's
-        # steps-vs-epochs toggle sends it.
+        # 0 is a sentinel for "use max_steps instead" (frontend toggle).
         if v is None:
             return 1
         if v < 0 or v > _MAX_EPOCHS:
@@ -342,8 +340,7 @@ class TrainingStartRequest(BaseModel):
 
     @model_validator(mode = "after")
     def _check_steps_or_epochs(self) -> "TrainingStartRequest":
-        # num_epochs and max_steps each accept 0 as a "use the other one"
-        # sentinel. Both 0 means nothing to train against.
+        # Each accepts 0 as "use the other"; both 0 means nothing to train.
         if (self.max_steps is None or self.max_steps == 0) and self.num_epochs == 0:
             raise ValueError("Either num_epochs or max_steps must be > 0; both cannot be 0.")
         return self
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
index fd3846dc21..62ecb2e280 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/__init__.py
@@ -2,6 +2,5 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 # Intentionally empty. Data-designer loads submodules lazily via qualified names
-# (impl_qualified_name / config_qualified_name in plugin.py), so importing this
-# package must NOT touch modules depending on data_designer.engine.* during
-# Studio's bootstrap (circular import).
+# in plugin.py, so importing this package must not touch data_designer.engine.*
+# during Studio bootstrap (circular import).
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
index 9190b6a738..330e917f3f 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/impl.py
@@ -16,13 +16,10 @@ from .config import GitHubRepoSeedSource
 from .scraper import ScrapeConfig, materialize_to_jsonl
 
 
-# In-process cache mapping a stable config signature to the JSONL materialization
-# path. A recipe job calls the seed reader multiple times (validation, preview,
-# per-column sampling) and the default flow re-scrapes on every call: a 2-repo
-# preview is ~15s of redundant GitHub GraphQL traffic before any generation.
-# Memoize so later passes reuse the first pass's file. The key excludes the raw
-# token and uses a short SHA-256 digest, so token values never hit memory twice
-# and rotation invalidates cleanly.
+# In-process cache: config signature -> JSONL path. A recipe job reads the seed
+# multiple times (validation, preview, sampling); memoize to avoid re-scraping
+# GitHub on each call. Key uses a short SHA-256 of the token (never the raw value)
+# so token never hits memory twice and rotation invalidates cleanly.
 _SCRAPE_CACHE: dict[tuple, str] = {}
 _SCRAPE_CACHE_LOCK = threading.Lock()
 
@@ -46,8 +43,7 @@ def _lookup_cached_scrape(key: tuple) -> Optional[str]:
         path = _SCRAPE_CACHE.get(key)
     if path and Path(path).exists():
         return path
-    # Stale entry (tmp cleanup, restart, ...); drop it so the caller
-    # materializes a fresh file instead of returning a dangling path.
+    # Stale entry (tmp cleanup/restart); drop it so the caller re-materializes.
     if path:
         with _SCRAPE_CACHE_LOCK:
             _SCRAPE_CACHE.pop(key, None)
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
index 926606c24c..637193e8b3 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper.py
@@ -19,7 +19,7 @@ import uuid
 from dataclasses import dataclass
 from pathlib import Path
 
-# Defer scraper_impl imports until `scrape()` runs with a resolved token.
+# Defer scraper_impl imports until scrape() has a resolved token.
 _IMPL_DIR = Path(__file__).parent / "scraper_impl"
 
 
@@ -165,7 +165,7 @@ def scrape(cfg: ScrapeConfig, base_dir: Path):
     client = GitHubClient(token = token.value, token_source = token.source)
     base_dir.mkdir(parents = True, exist_ok = True)
 
-    # Per-resource trial limits. limit <= 0 means "all": use a large cap.
+    # Per-resource limits; limit <= 0 means "all" (large cap).
     effective_limit = cfg.limit if cfg.limit and cfg.limit > 0 else 1_000_000
     trial_limits: dict[str, int] = {}
     if "issues" in cfg.item_types:
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
index 9ab174c2d4..0ba3394ca3 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/gh_client.py
@@ -112,9 +112,8 @@ class GitHubClient:
     def _is_auth_failure(self, r: "requests.Response") -> bool:
         """Tell auth failures apart from rate limiting on 401/403.
 
-        - 401: always an auth failure (invalid / expired / wrong-scope token).
-        - 403: auth failure UNLESS it carries a rate-limit signal (Retry-After,
-          X-RateLimit-Remaining: 0, or secondary / abuse rate-limit text).
+        401 is always auth; 403 is auth unless it carries a rate-limit signal
+        (Retry-After, X-RateLimit-Remaining: 0, or abuse/secondary text).
         """
         if r.status_code == 401:
             return True
@@ -168,7 +167,6 @@ class GitHubClient:
                     timeout = 120,
                 )
                 self.calls_graphql += 1
-                # Update rate info from headers
                 rem = r.headers.get("X-RateLimit-Remaining")
                 rst = r.headers.get("X-RateLimit-Reset")
                 if rem is not None:
@@ -203,7 +201,7 @@ class GitHubClient:
                 r.raise_for_status()
                 data = r.json()
                 if "errors" in data and data["errors"]:
-                    # Surface errors but allow partial data; retry on RATE_LIMITED
+                    # Allow partial data; retry on RATE_LIMITED
                     errs = data["errors"]
                     for e in errs:
                         if e.get("type") == "RATE_LIMITED":
@@ -301,7 +299,6 @@ class GitHubClient:
                 items = items.get("items", [])
             for it in items:
                 yield it
-            # Follow Link header
             link = r.headers.get("Link", "")
             nxt = None
             for part in link.split(","):
diff --git a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
index 08e2a28ceb..a7ddaef5fe 100644
--- a/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
+++ b/studio/backend/plugins/data-designer-github-repo-seed/src/data_designer_github_repo_seed/scraper_impl/scraper.py
@@ -49,9 +49,9 @@ class RepoScraper:
         self.base_dir = base_dir
         self.client = client
         self.trial_limits = trial_limits or {}
-        # light=True uses trimmed GraphQL queries (no reviewThreads,
-        # reviews, commits, timelineItems, files) so PR pages can be larger
-        # without hitting GitHub's node-count ceiling.
+        # light=True uses trimmed GraphQL queries (no reviewThreads/reviews/
+        # commits/timelineItems/files) so PR pages can be larger without
+        # hitting GitHub's node-count ceiling.
         self.light = light
         self.repo_dir = base_dir / f"{owner}__{name}"
         self.repo_dir.mkdir(parents = True, exist_ok = True)
@@ -115,9 +115,8 @@ class RepoScraper:
             return 0
         total_new = 0
         page = 0
-        # Light query skips heavy nested fields; safe at 50 per page.
-        # Clamp by trial_limit so e.g. limit=1 asks GitHub for first:1
-        # instead of fetching a full 50-item page and discarding 49.
+        # Light query skips heavy nested fields; safe at 50/page. Clamp by
+        # trial_limit so limit=1 asks for first:1, not a full 50-item page.
         page_cap = 50 if self.light else 15
         trial_cap = self.trial_limits.get(key)
         per_page = min(page_cap, trial_cap) if trial_cap and trial_cap > 0 else page_cap
@@ -223,10 +222,9 @@ class RepoScraper:
             return 0
         total_new = 0
         page = 0
-        # Heavy nested PR query is capped at 3 per page (GitHub node-count
-        # ceiling); light query skips reviewThreads/reviews/commits/etc and
-        # goes to 25 per page. Clamp by trial_limit so limit=1 does not
-        # fetch a whole 25-item page.
+        # Heavy nested PR query caps at 3/page (GitHub node-count ceiling);
+        # light query skips nested fields and goes to 25/page. Clamp by
+        # trial_limit so limit=1 does not fetch a whole 25-item page.
         page_cap = 25 if self.light else 3
         trial_cap = self.trial_limits.get(key)
         per_page = min(page_cap, trial_cap) if trial_cap and trial_cap > 0 else page_cap
diff --git a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
index e5c2f7a492..ee7d8727fc 100644
--- a/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
+++ b/studio/backend/plugins/data-designer-unstructured-seed/src/data_designer_unstructured_seed/chunking.py
@@ -74,7 +74,7 @@ def _round_robin_preview(rows: list[dict[str, str]], preview_size: int) -> list[
     if not rows or preview_size <= 0:
         return []
 
-    # Group rows by source_file, preserving first-appearance order.
+    # Group by source_file, preserving first-appearance order.
     from collections import OrderedDict
 
     grouped: OrderedDict[str, list[dict[str, str]]] = OrderedDict()
diff --git a/studio/backend/routes/auth.py b/studio/backend/routes/auth.py
index c19560c529..3ac85380fe 100644
--- a/studio/backend/routes/auth.py
+++ b/studio/backend/routes/auth.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Authentication API routes
-"""
+"""Authentication API routes."""
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 
@@ -43,17 +41,12 @@ router = APIRouter()
 def _reset_password_command() -> str:
     """Shell command shown in the 'incorrect password' hint.
 
-    Prefer the ABSOLUTE path to this install's ``unsloth`` launcher (sibling of
-    the running interpreter) so the hint works even when the launcher's dir
-    isn't on PATH -- e.g. a terminal opened before install, a stale Windows
-    PATH, or ``~/.local/bin`` not on PATH (the macOS default) -- regardless of
-    the cwd.
+    Prefer the absolute path to this install's ``unsloth`` launcher (sibling of
+    the running interpreter) so the hint works even when its dir isn't on PATH.
 
-    On POSIX the path is shell-quoted to handle spaces. On Windows we use the
-    bare absolute path only when it has no spaces, since a quoted path needs
-    different syntax in cmd (``"..."``) vs PowerShell (``& "..."``); with a
-    space we fall back to the PATH-based form to stay unambiguous across shells.
-    We also fall back to the PATH form if the launcher can't be located.
+    POSIX paths are shell-quoted. On Windows we use the bare absolute path only
+    when it has no spaces (a quoted path differs between cmd and PowerShell);
+    otherwise, or if the launcher can't be located, fall back to the PATH form.
     """
     try:
         bin_dir = os.path.dirname(os.path.abspath(sys.executable))
diff --git a/studio/backend/routes/chat_history.py b/studio/backend/routes/chat_history.py
index 8496c970d0..782bba3be0 100644
--- a/studio/backend/routes/chat_history.py
+++ b/studio/backend/routes/chat_history.py
@@ -189,8 +189,6 @@ class ChatMessagesBatchResponse(BaseModel):
 
 
 class ChatImportLedgerResponse(BaseModel):
-    # Plain list of legacy thread ids; key-less payload keeps the client diff
-    # to a single Set construction.
     threadIds: list[str]
 
 
@@ -201,8 +199,7 @@ class ChatImportLedgerRecordRequest(BaseModel):
 
 class ChatImportLedgerRecordResponse(BaseModel):
     # accepted: deduped non-empty input count. inserted: rows actually new
-    # (ON CONFLICT DO NOTHING skips already-recorded ids). The client uses
-    # `accepted >= 0` as the "endpoint exists" signal and ignores the split.
+    # (ON CONFLICT DO NOTHING skips already-recorded ids).
     accepted: int
     inserted: int
 
@@ -351,8 +348,7 @@ async def get_thread_messages(thread_id: str, current_subject: str = Depends(get
 async def batch_thread_messages(
     payload: ChatMessagesBatchRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """One round-trip per sidebar/search rebuild instead of N. Unknown thread
-    ids return empty lists so callers don't need a pre-flight."""
+    """One round-trip per sidebar/search rebuild instead of N. Unknown thread ids return empty lists."""
     by_thread: dict[str, list[ChatMessage]] = {tid: [] for tid in payload.threadIds}
     for m in list_chat_messages_for_threads(payload.threadIds):
         tid = m["threadId"]
@@ -443,10 +439,10 @@ async def count_threads(current_subject: str = Depends(get_current_subject)):
 
 @router.get("/import-ledger", response_model = ChatImportLedgerResponse)
 async def get_import_ledger(current_subject: str = Depends(get_current_subject)):
-    """Legacy-Dexie import ledger. Returns the legacy thread ids already copied
-    into chat_threads / chat_messages. The frontend uses this on every fresh tab
-    open to decide whether to re-run the Dexie -> studio.db import. Source of
-    truth lives in studio.db, so a studio.db wipe makes the import recoverable."""
+    """Legacy-Dexie import ledger: legacy thread ids already copied into chat tables.
+
+    The frontend checks this on tab open to decide whether to re-run the Dexie -> studio.db import.
+    """
     return ChatImportLedgerResponse(threadIds = list_chat_legacy_imports())
 
 
@@ -478,8 +474,7 @@ async def put_settings(
         parsed = ChatSettingsPayload.model_validate(payload)
     except ValidationError as exc:
         raise HTTPException(status_code = 400, detail = exc.errors()) from exc
-    # Atomic read + deep-merge + write in one BEGIN IMMEDIATE so concurrent
-    # slider drags can't drop each other's updates.
+    # Atomic read + deep-merge + write in one BEGIN IMMEDIATE so concurrent updates don't clobber.
     try:
         return ChatSettingsResponse(
             settings = upsert_chat_settings_merge(parsed.model_dump(exclude_unset = True))
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index 01991cd865..3874bd587c 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -36,14 +36,9 @@ def _resolve_local_v1_endpoint(request: Request) -> str:
     """Return the loopback /v1 URL for the actual backend listen port.
 
     Resolution order:
-      1. ``app.state.server_port`` - published by run.py after uvicorn
-         binds. Most reliable; survives reverse proxies, TLS terminators,
-         and tunnels.
-      2. ``request.scope["server"]`` - the real (host, port) tuple uvicorn
-         sets per request. Used when Studio starts outside ``run_server``
-         (e.g. ``uvicorn studio.backend.main:app``).
-      3. ``request.base_url`` parsed - last resort for test fixtures with
-         no live uvicorn server.
+      1. ``app.state.server_port`` (run.py, post-bind) - survives proxies/tunnels.
+      2. ``request.scope["server"]`` - when Studio starts outside ``run_server``.
+      3. parsed ``request.base_url`` - last resort for test fixtures.
     """
     port: Any = getattr(request.app.state, "server_port", None)
     if not isinstance(port, int) or port <= 0:
@@ -76,14 +71,11 @@ def _request_has_desktop_access_token(request: Request) -> bool:
 
 
 def _used_llm_model_aliases(recipe: dict[str, Any]) -> set[str]:
-    """Return model_aliases actually referenced by an LLM column. Narrows
-    the "Chat model loaded" gate so orphan model_config nodes on the canvas
-    do not block unrelated recipe runs.
+    """Return model_aliases actually referenced by an LLM column.
 
-    The ``llm-`` prefix matches the convention in
-    ``core/data_recipe/service.py::_recipe_has_llm_columns`` and covers all
-    frontend LLM column types (llm-text, llm-code, llm-structured,
-    llm-judge).
+    Narrows the "Chat model loaded" gate so orphan model_config nodes don't
+    block unrelated runs. The ``llm-`` prefix matches
+    ``service.py::_recipe_has_llm_columns`` and covers all LLM column types.
     """
     aliases: set[str] = set()
     for column in recipe.get("columns", []):
@@ -180,17 +172,13 @@ def _ensure_selected_local_model_loaded(
 def _inject_local_structured_response_format(
     recipe: dict[str, Any], local_provider_names: set[str]
 ) -> None:
-    """For each llm-structured column targeting a local-provider model_config,
-    clone the config and inject an OpenAI ``response_format`` with the
-    column's ``output_format`` JSON schema. The column is repointed at the
-    clone so llm-text / llm-judge columns sharing the alias keep free-form
-    sampling.
+    """Inject an OpenAI ``response_format`` for each local llm-structured column.
 
-    Without this, data_designer only injects a prompt-level "return JSON in a
-    ```json fence" instruction. Small GGUFs often break format, wasting the
-    full ``max_tokens`` budget per row and then failing to parse. Forwarding
-    ``response_format`` lets llama-server apply grammar-constrained sampling
-    from the schema, guaranteeing a parseable response and terminating early.
+    Clones the model_config and repoints the column at the clone so llm-text /
+    llm-judge columns sharing the alias keep free-form sampling. Without this,
+    data_designer only adds a prompt-level "return JSON" hint, which small GGUFs
+    often break. Forwarding ``response_format`` lets llama-server apply
+    grammar-constrained sampling, guaranteeing parseable output.
     """
     columns = recipe.get("columns")
     model_configs = recipe.get("model_configs")
@@ -242,14 +230,12 @@ def _inject_local_structured_response_format(
         if not isinstance(params, dict):
             params = {}
             clone["inference_parameters"] = params
-        # data_designer's BaseInferenceParams is pydantic extra="forbid", so
-        # response_format cannot sit at the top level of inference_parameters.
-        # Its `extra_body: dict` passthrough is spread into the request body
-        # top level by the OpenAI client, where llama-server reads
-        # response_format. llama.cpp server shape (tools/server/README.md):
-        # the schema sits directly under response_format, not nested in a
-        # json_schema object like OpenAI's Chat Completions API expects.
-        # llama-server converts the schema to a GBNF grammar for sampling.
+        # BaseInferenceParams is extra="forbid", so response_format can't sit at
+        # the top level. Its `extra_body` passthrough is spread into the request
+        # body top level by the OpenAI client, where llama-server reads
+        # response_format. Per tools/server/README.md the schema sits directly
+        # under response_format (not nested in a json_schema object as OpenAI
+        # expects) and is converted to a GBNF grammar for sampling.
         extra_body = params.get("extra_body")
         if not isinstance(extra_body, dict):
             extra_body = {}
@@ -266,22 +252,18 @@ def _inject_local_structured_response_format(
 
 
 def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optional[int]:
-    """
-    Mutate recipe dict in-place: for any provider with is_local=True, set
-    the endpoint to this server and inject a short-lived internal
-    sk-unsloth-* API key for workflow auth.
+    """Mutate recipe in-place: point is_local providers at this server and mint
+    a short-lived internal sk-unsloth-* key for workflow auth.
 
-    Returns the row id of the minted internal key (for the caller to revoke
-    on job completion) or ``None`` when no local provider is reachable from
-    an LLM column.
+    Returns the minted key's row id (for the caller to revoke on completion), or
+    ``None`` when no local provider is reachable from an LLM column.
     """
     providers = recipe.get("model_providers")
     if not providers:
         return None
 
-    # Collect local providers and pop is_local from ALL dicts. Strict
-    # `is True` guard so malformed payloads (is_local: 1, is_local: "true")
-    # do not trigger the loopback rewrite.
+    # Collect local providers and pop is_local from ALL dicts. Strict `is True`
+    # guard so malformed payloads (1, "true") don't trigger the loopback rewrite.
     local_indices: list[int] = []
     for i, provider in enumerate(providers):
         if not isinstance(provider, dict):
@@ -296,9 +278,8 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
     endpoint = _resolve_local_v1_endpoint(request)
 
     # Only gate on model-loaded if a local provider is reachable from an LLM
-    # column via a model_config. Orphan model_config nodes referencing a
-    # local provider that no LLM column uses should not block runs; the
-    # recipe would never call /v1 for them.
+    # column via a model_config. Orphan model_config nodes shouldn't block runs;
+    # the recipe never calls /v1 for them.
     local_names = {providers[i].get("name") for i in local_indices if providers[i].get("name")}
     used_aliases = _used_llm_model_aliases(recipe)
     referenced_providers = {
@@ -310,20 +291,16 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
     token = ""
     internal_key_id: Optional[int] = None
     if local_names & referenced_providers:
-        # Verify the selected local model is loaded before minting a workflow
-        # key. Still a point-in-time singleton-backend check (TOCTOU): a
-        # future generation token should bind frontend load to job creation;
-        # the inference endpoint returns a clear 400 if the model is unloaded
-        # or swapped before the subprocess calls /v1.
+        # Verify the selected local model is loaded before minting a key. Still
+        # a point-in-time check (TOCTOU); the /v1 endpoint returns a clear 400 if
+        # the model is unloaded or swapped before the subprocess calls it.
         _ensure_selected_local_model_loaded(recipe, local_names)
 
         from auth import storage  # deferred: avoids circular import
 
-        # Mint an internal sk-unsloth-* key scoped to this workflow run via
-        # the unified API-key issuance path (one mint/revoke/verify surface
-        # instead of a second JWT code path). Marked internal so it is hidden
-        # from the user's API-key list; the caller revokes it when the job
-        # terminates.
+        # Mint an internal sk-unsloth-* key scoped to this run via the unified
+        # API-key path. Marked internal so it's hidden from the user's key list;
+        # the caller revokes it when the job terminates.
         expires_at = (datetime.now(timezone.utc) + timedelta(hours = 24)).isoformat()
         token, row = storage.create_api_key(
             username = "unsloth",
@@ -333,11 +310,9 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
         )
         internal_key_id = int(row["id"])
 
-    # Strip stale "external"-only fields the frontend may have left
-    # (extra_headers/extra_body/api_key_env). The UI hides these in local
-    # mode but the payload builder still serializes them, so a provider
-    # flipped from external to local could carry invalid JSON or rogue auth
-    # headers into the local /v1 call.
+    # Strip stale "external"-only fields (extra_headers/extra_body/api_key_env)
+    # the frontend may have serialized; a provider flipped from external to local
+    # could otherwise carry invalid JSON or rogue auth headers into the /v1 call.
     for i in local_indices:
         providers[i]["endpoint"] = endpoint
         providers[i]["api_key"] = token
@@ -346,27 +321,21 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
         providers[i].pop("extra_headers", None)
         providers[i].pop("extra_body", None)
 
-    # Force skip_health_check on any model_config referencing a local
-    # provider. The frontend sends the explicit selected local model id, but
-    # llama-server's /v1/models response can differ from it for local paths,
-    # cache aliases, and GGUF variant loads. The run already gated on a
-    # loaded local backend above, so data_designer's model-list health check
-    # would be redundant and can reject valid local selections.
+    # Force skip_health_check on local model_configs. llama-server's /v1/models
+    # response can differ from the selected id (cache aliases, GGUF variants),
+    # and we already gated on a loaded backend, so the health check would be
+    # redundant and could reject valid local selections.
     for mc in recipe.get("model_configs", []):
         if not isinstance(mc, dict):
             continue
         if mc.get("provider") in local_names:
             mc["skip_health_check"] = True
-            # Disable thinking for data-recipe inference on local providers.
-            # Reasoning models emit a <think>...</think> preamble that roughly
-            # doubles generated tokens per row and pushes the answer past
-            # data_designer's json-fence regex. Forward
-            # chat_template_kwargs={enable_thinking: False} via the OpenAI
-            # SDK's extra_body passthrough so llama-server renders the
-            # template without the preamble. llm-text columns get the latency
-            # cut; structured columns stop leaking think tags into the
-            # grammar-constrained JSON (GBNF still enforces the schema either
-            # way).
+            # Disable thinking for local data-recipe inference. The
+            # <think>...</think> preamble roughly doubles tokens per row and
+            # pushes answers past data_designer's json-fence regex. Forward
+            # chat_template_kwargs={enable_thinking: False} via extra_body so
+            # llama-server renders the template without it: llm-text columns get
+            # the latency cut, structured columns stop leaking think tags.
             params = mc.get("inference_parameters")
             if not isinstance(params, dict):
                 params = {}
@@ -381,9 +350,8 @@ def _inject_local_providers(recipe: dict[str, Any], request: Request) -> Optiona
             extra_body["chat_template_kwargs"] = tpl_kwargs
             params["extra_body"] = extra_body
 
-    # Forward each llm-structured column's output_format as an OpenAI
-    # response_format so llama-server uses grammar-constrained sampling and
-    # small GGUFs stop wasting the max_tokens budget on broken JSON.
+    # Forward each llm-structured column's output_format as a response_format so
+    # llama-server uses grammar-constrained sampling instead of broken JSON.
     _inject_local_structured_response_format(recipe, local_names)
 
     return internal_key_id
@@ -442,11 +410,9 @@ def create_job(payload: RecipePayload, request: Request):
             log = logger,
         ) from exc
 
-    # Single try covers get_job_manager() AND mgr.start() so a minted
-    # workflow key never outlives the request even on an unexpected
-    # exception type (TypeError from a stale kwarg, OSError from a queue
-    # write, etc.). Without the bare except, those would let the
-    # sk-unsloth-* key live until its 24h TTL.
+    # Single try over get_job_manager() AND mgr.start() so a minted key never
+    # outlives the request on an unexpected exception; without the bare except it
+    # would live until its 24h TTL.
     try:
         mgr = get_job_manager()
         job_id = mgr.start(
@@ -483,8 +449,7 @@ def create_job(payload: RecipePayload, request: Request):
 
 
 def _revoke_internal_api_key_safe(key_id: int) -> None:
-    """Best-effort revoke of a workflow-minted key; swallow any error so
-    revocation failures never mask the caller's own error path."""
+    """Best-effort revoke of a workflow-minted key; never mask the caller's error."""
     try:
         from auth import storage  # deferred: avoids circular import
         storage.revoke_internal_api_key(key_id)
diff --git a/studio/backend/routes/data_recipe/seed.py b/studio/backend/routes/data_recipe/seed.py
index 848ed7d557..8fb034ea4e 100644
--- a/studio/backend/routes/data_recipe/seed.py
+++ b/studio/backend/routes/data_recipe/seed.py
@@ -581,8 +581,7 @@ def inspect_seed_upload(payload: SeedInspectUploadRequest) -> SeedInspectRespons
     seed_source_type = _normalize_optional_text(payload.seed_source_type) or "local"
     filename = _sanitize_filename(payload.filename)
     ext = Path(filename).suffix.lower()
-    # Legacy single-file unstructured path supports only .txt/.md;
-    # PDF/DOCX extraction uses the multi-file upload endpoint instead
+    # Legacy single-file path is .txt/.md only; PDF/DOCX use multi-file upload
     _LEGACY_UNSTRUCTURED_EXTS = {".txt", ".md"}
     if seed_source_type == "unstructured":
         if ext not in _LEGACY_UNSTRUCTURED_EXTS:
diff --git a/studio/backend/routes/data_recipe/validate.py b/studio/backend/routes/data_recipe/validate.py
index 732fa902d6..ffe36ba69e 100644
--- a/studio/backend/routes/data_recipe/validate.py
+++ b/studio/backend/routes/data_recipe/validate.py
@@ -121,8 +121,8 @@ def _collect_validation_errors(recipe: dict[str, Any]) -> list[ValidateError]:
 def _patch_local_providers(recipe: dict[str, Any]) -> None:
     """Strip is_local and fill a dummy endpoint so validation doesn't choke.
 
-    Strict `is True` check matches _inject_local_providers in jobs.py:
-    truthy but non-boolean is_local values are not treated as local.
+    Strict `is True` matches _inject_local_providers: truthy non-boolean values
+    aren't treated as local.
     """
     for provider in recipe.get("model_providers", []):
         if not isinstance(provider, dict):
@@ -150,13 +150,10 @@ def validate(payload: RecipePayload) -> ValidateResponse:
         try:
             build_config_builder(recipe)
         except ModuleNotFoundError as exc:
-            # data_designer is an optional runtime dep. Static validation
-            # passed; live access + full config validation are deferred to
-            # run start (per _GITHUB_VALIDATE_NOTE), so a missing optional
-            # import here should not block the recipe. Restrict the bypass to
-            # the data_designer module so other ImportErrors (broken internal
-            # imports, missing transitive deps after an upgrade) still surface
-            # as validation failures instead of being swallowed.
+            # data_designer is an optional runtime dep; static validation passed
+            # and full validation is deferred to run start, so a missing import
+            # shouldn't block the recipe. Restrict the bypass to data_designer so
+            # other ImportErrors still surface as failures.
             if not (exc.name or "").startswith("data_designer"):
                 raise
             logger.debug(
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 1bf035b684..b755bf9d4a 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Datasets API routes
-"""
+"""Datasets API routes."""
 
 import base64
 import io
@@ -43,11 +41,9 @@ def _get_dataset_size_cached(repo_id: str) -> int:
 
 
 def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
-    """Pick the most useful on-disk path for a HF cache repo dir.
+    """Resolved realpath for a HF cache repo dir: most-recent snapshot, else cache root.
 
-    Mirrors routes/models.py: prefer the most-recent snapshot dir, else the
-    cache repo root, returned as a resolved realpath. Duplicated here to keep
-    routes/datasets.py self-contained.
+    Mirrors routes/models.py; duplicated here to keep this module self-contained.
     """
     try:
         snapshots_dir = repo_dir / "snapshots"
@@ -61,12 +57,10 @@ def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
         return None
 
 
-# Add backend directory to path.
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Import dataset utilities.
 from utils.datasets import check_dataset_format
 from utils.upload_limits import get_upload_limit_bytes, get_upload_limit_label
 from auth.authentication import get_current_subject
@@ -128,12 +122,9 @@ def _serialize_preview_rows(rows):
     ]
 
 
-# --- Endpoints ---
-
-# Recognized data-file extensions for the single-file fallback.
-# Tier 1 preview prefers tabular over archives: archives (e.g. images.zip) can
-# load as ImageFolder datasets with synthetic image/label columns that don't
-# match the real schema.
+# Data-file extensions for the single-file fallback. Tier 1 preview prefers
+# tabular over archives: archives (e.g. images.zip) load as ImageFolder with
+# synthetic image/label columns that don't match the real schema.
 _TABULAR_EXTS = (".parquet", ".json", ".jsonl", ".csv", ".tsv", ".arrow")
 _ARCHIVE_EXTS = (".tar", ".tar.gz", ".tgz", ".gz", ".zst", ".zip", ".txt")
 DATA_EXTS = _TABULAR_EXTS + _ARCHIVE_EXTS
@@ -378,10 +369,8 @@ async def get_dataset_download_progress(
     """Return download progress for a HuggingFace dataset repo.
 
     Mirrors ``GET /api/models/download-progress`` but scans the
-    ``datasets--owner--name`` cache directory under HF_HUB_CACHE. Modern
-    ``datasets``/``huggingface_hub`` cache raw dataset blobs there (processed
-    Arrow shards live elsewhere, but in-progress *download* bytes are visible
-    here). Returns ``cache_path`` so the UI can show where blobs landed.
+    ``datasets--owner--name`` cache dir under HF_HUB_CACHE, where in-progress
+    download bytes are visible. Returns ``cache_path`` so the UI can show it.
     """
     _empty = {
         "downloaded_bytes": 0,
@@ -431,9 +420,8 @@ async def get_dataset_download_progress(
                 "cache_path": cache_path,
             }
 
-        # Same 95% completion threshold as the model endpoint -- HF blob dedup
-        # makes completed_bytes drift slightly under expected_bytes, and
-        # inter-file gaps would otherwise look "done".
+        # 95% threshold (as in the model endpoint): HF blob dedup makes
+        # completed_bytes drift under expected_bytes; inter-file gaps look "done".
         if completed_bytes >= expected_bytes * 0.95:
             progress = 1.0
         else:
@@ -451,12 +439,10 @@ async def get_dataset_download_progress(
 
 @router.post("/check-format", response_model = CheckFormatResponse)
 def check_format(request: CheckFormatRequest, current_subject: str = Depends(get_current_subject)):
-    """
-    Check if a dataset requires manual column mapping.
+    """Check if a dataset requires manual column mapping.
 
     HuggingFace strategy:
-      1. list_repo_files → first data file → load_dataset(data_files=[…]).
-         Avoids resolving thousands of files; typically ~2-4 s.
+      1. list_repo_files -> first data file -> load_dataset (avoids resolving thousands of files; ~2-4 s).
       2. Full streaming load_dataset as a last-resort fallback.
 
     Local files load directly. Plain `def` (not async) so FastAPI runs it in a
@@ -484,7 +470,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
             )
         else:
             # ── HuggingFace dataset ─────────────────────────────────
-            # Tier 1: list_repo_files → load only the first data file
+            # Tier 1: load only the first data file from list_repo_files
             preview_slice = None
 
             try:
@@ -498,15 +484,14 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                 )
                 data_files = [f for f in repo_files if any(f.endswith(ext) for ext in DATA_EXTS)]
 
-                # Prefer tabular over archives (e.g. images.zip → ImageFolder
-                # with synthetic image/label columns not in the real schema).
+                # Prefer tabular over archives (e.g. images.zip -> ImageFolder
+                # with synthetic columns not in the real schema).
                 tabular_files = [
                     f for f in data_files if any(f.endswith(ext) for ext in _TABULAR_EXTS)
                 ]
                 candidates = tabular_files or data_files
 
-                # With a subset, narrow to files whose name matches
-                # (e.g. subset="testmini" → prefer "testmini.parquet").
+                # With a subset, narrow to files whose name matches it.
                 if request.subset and candidates:
                     subset_matches = [f for f in candidates if request.subset in Path(f).stem]
                     if subset_matches:
@@ -532,7 +517,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                 logger.warning(f"Tier 1 (single-file) failed: {e}")
 
             if preview_slice is None:
-                # Tier 2: full streaming (resolves all files — slow for large repos)
+                # Tier 2: full streaming (resolves all files; slow for large repos)
                 logger.info("Tier 2: falling back to full streaming load_dataset")
                 load_kwargs = {
                     "path": request.dataset_name,
@@ -556,14 +541,12 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                 preview_slice = Dataset.from_list(rows)
             total_rows = None
 
-        # Lightweight format check on the preview slice.
         result = check_dataset_format(preview_slice, is_vlm = request.is_vlm)
 
         logger.info(
             f"Format check result: requires_mapping={result['requires_manual_mapping']}, format={result['detected_format']}, is_image={result.get('is_image', False)}"
         )
 
-        # Generate preview samples.
         preview_samples = None
         if not result["requires_manual_mapping"]:
             if result.get("suggested_mapping"):
@@ -575,7 +558,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                     format_result = format_dataset(
                         preview_slice,
                         format_type = "auto",
-                        num_proc = None,  # Only 10 preview rows -- no multiprocessing needed
+                        num_proc = None,  # Only 10 preview rows
                     )
                     processed = format_result["dataset"]
                     preview_samples = _serialize_preview_rows(processed)
@@ -585,7 +568,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
         else:
             preview_samples = _serialize_preview_rows(preview_slice)
 
-        # Collect warnings from check_dataset_format + URL-based image detection.
+        # Warnings from check_dataset_format plus URL-based image detection.
         warning = result.get("warning")
         image_col = result.get("detected_image_column")
         if image_col and image_col in (result.get("columns") or []):
@@ -629,15 +612,11 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
 def ai_assist_mapping(
     request: AiAssistMappingRequest, current_subject: str = Depends(get_current_subject)
 ):
-    """
-    Run LLM-assisted dataset conversion advisor (user-triggered).
+    """Run LLM-assisted dataset conversion advisor (user-triggered).
 
-    Multi-pass analysis with a 7B helper model:
-      Pass 1: Classify dataset type from HF card + samples.
-      Pass 2: Generate conversion strategy (system prompt, templates).
-      Pass 3: Validate conversion quality.
-
-    Falls back to simple column classification if the advisor fails.
+    Multi-pass analysis with a 7B helper model: classify dataset type, generate
+    conversion strategy, validate quality. Falls back to simple column
+    classification if the advisor fails.
     """
     try:
         from utils.datasets.llm_assist import llm_conversion_advisor
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index d687a22f8e..abb89a13da 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -16,17 +16,14 @@ from fastapi.responses import StreamingResponse
 import structlog
 from loggers import get_logger
 
-# Add backend directory to path
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Auth
 from auth.authentication import get_current_subject
 
 from utils.utils import safe_error_detail
 
-# Backend functions
 try:
     from core.export import get_export_backend
 except ImportError:
@@ -35,7 +32,6 @@ except ImportError:
         sys.path.insert(0, str(parent_backend))
     from core.export import get_export_backend
 
-# Pydantic models
 from models import (
     LoadCheckpointRequest,
     ExportStatusResponse,
@@ -56,9 +52,6 @@ async def load_checkpoint(
 ):
     """Load a checkpoint into the export backend (ExportBackend.load_checkpoint)."""
     try:
-        # The subprocess-based export backend handles version switching
-        # automatically — no ensure_transformers_version() needed here.
-
         # Free GPU memory: shut down running inference/training subprocesses
         # before loading the export checkpoint (they'd compete for VRAM).
         try:
@@ -81,8 +74,7 @@ async def load_checkpoint(
             if trn.is_training_active():
                 logger.info("Stopping active training to free GPU memory for export")
                 trn.stop_training()
-                # Wait for the training subprocess to exit; else it may still
-                # hold GPU memory when export tries to load.
+                # Wait for the training subprocess to exit, else it may still hold GPU memory.
                 for _ in range(60):  # up to 30s
                     if not trn.is_training_active():
                         break
@@ -94,9 +86,8 @@ async def load_checkpoint(
             logger.warning("Could not stop training: %s", e)
 
         backend = get_export_backend()
-        # load_checkpoint spawns and waits on a subprocess and can take
-        # minutes. Run it in a worker thread so the event loop stays free
-        # to serve the live log SSE stream concurrently.
+        # Run in a worker thread (spawns and waits on a subprocess, can take
+        # minutes) so the event loop stays free to serve the live log SSE stream.
         success, message = await asyncio.to_thread(
             backend.load_checkpoint,
             checkpoint_path = request.checkpoint_path,
@@ -329,21 +320,14 @@ async def export_lora_adapter(
         )
 
 
-# ─────────────────────────────────────────────────────────────────────
-# Live export log stream (Server-Sent Events)
-# ─────────────────────────────────────────────────────────────────────
+# Live export log stream (Server-Sent Events).
 #
-# The export worker subprocess redirects its stdout/stderr into a pipe a
-# reader thread forwards to the orchestrator as log entries (see
-# core/export/worker.py::_setup_log_capture and
-# core/export/orchestrator.py::_append_log). This endpoint streams those
-# entries to the browser so the export dialog shows a live terminal-style
-# panel while load_checkpoint / export_merged / export_gguf / export_lora /
-# export_base run.
+# The export worker's stdout/stderr is piped to the orchestrator as log
+# entries (core/export/worker.py, orchestrator.py); this endpoint streams
+# them to the browser for a live terminal panel during export operations.
 #
-# Shape follows the training progress SSE endpoint
-# (routes/training.py::stream_training_progress): each event carries `id`,
-# `event`, `data` fields, the stream starts with a `retry:` directive, and
+# Shape follows routes/training.py::stream_training_progress: each event
+# carries id/event/data, the stream starts with a `retry:` directive, and
 # `Last-Event-ID` is honored on reconnect.
 
 
@@ -388,11 +372,9 @@ async def stream_export_logs(
     """
     backend = get_export_backend()
 
-    # Starting cursor: explicit `since` wins, then Last-Event-ID header on
-    # reconnect, else the run-start snapshot from clear_logs() so the client
-    # sees every line since the run began -- even if the SSE connection
-    # opened after the POST that kicked off the export. get_current_log_seq()
-    # would lose the early bootstrap lines arriving between POST and connect.
+    # Starting cursor: explicit `since` wins, then Last-Event-ID on reconnect,
+    # else the run-start snapshot so the client sees every line since the run
+    # began even if the SSE connection opened after the export-kickoff POST.
     last_event_id = request.headers.get("last-event-id")
     if since is None and last_event_id is not None:
         try:
@@ -441,8 +423,8 @@ async def stream_export_logs(
                         yield _format_sse("{}", event = "heartbeat")
                         last_yield = now
                     if not backend.is_export_active():
-                        # Give the reader thread a moment to drain trailing
-                        # lines the worker printed just before signalling done.
+                        # Let the reader thread drain trailing lines printed just
+                        # before the worker signalled done.
                         if idle_since is None:
                             idle_since = now
                         elif now - idle_since > 1.0:
@@ -457,8 +439,7 @@ async def stream_export_logs(
 
                 await asyncio.sleep(0.1)
         except asyncio.CancelledError:
-            # Client disconnected mid-yield. Don't re-raise; end the
-            # generator cleanly so StreamingResponse finalizes.
+            # Client disconnected mid-yield: end cleanly so StreamingResponse finalizes.
             return
         except Exception as exc:
             logger.error("Export log stream failed: %s", exc, exc_info = True)
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 86b4251d15..cf264d0dc9 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -107,12 +107,10 @@ def _friendly_error(exc: Exception) -> str:
     return "An internal error occurred"
 
 
-# Add backend directory to path
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Import backend functions
 try:
     from core.inference import get_inference_backend
     from core.inference.llama_cpp import (
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 1d8f73eb88..098c64fe39 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -44,10 +44,8 @@ def _validate_url(url: str) -> str:
     trimmed = (url or "").strip()
     if not trimmed:
         raise HTTPException(status_code = 400, detail = "url must not be empty")
-    # When stdio is enabled on this host, a non-HTTP value is a local command.
-    # Reuse this field so stdio servers ride the existing CRUD/storage with no
-    # schema change. A lone token (example.com, /usr/bin/srv) is ambiguous, so
-    # keep existing behaviour and treat any non-HTTP value as a command here.
+    # When stdio is enabled, a non-HTTP value is a local command (reuses this
+    # field so stdio servers ride existing CRUD/storage).
     if stdio_mcp_enabled() and is_stdio(trimmed):
         try:
             parts = parse_stdio_command(trimmed)
@@ -76,8 +74,7 @@ def _validate_url(url: str) -> str:
             "MCP server address must start with http:// or https:// "
             "(for example https://example.com/mcp)."
         )
-        # Host-scoped wording ("this server"), not "desktop only": self-hosted
-        # hosts can opt in via the env var.
+        # Host-scoped wording: self-hosted hosts can opt in via the env var.
         if _looks_like_command(trimmed):
             detail += " Running a local command is not enabled on this server."
         raise HTTPException(status_code = 400, detail = detail)
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 319330d428..ce4e41a062 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -28,11 +28,10 @@ def _is_valid_repo_id(repo_id: str) -> bool:
 def _safe_is_dir(path) -> bool:
     """``Path.is_dir()`` returning ``False`` instead of raising.
 
-    Python >= 3.12's ``is_dir()`` propagates ``PermissionError``
-    (EACCES); <= 3.11 returned ``False``. Folder-scan endpoints probe
-    system locations (e.g. root-owned mode-700
-    ``/usr/share/ollama/.ollama/models``) and must treat an un-stat-able
-    path as "not a directory", never 500.
+    Python >= 3.12 propagates ``PermissionError`` from ``is_dir()``;
+    folder-scan endpoints probe system locations (e.g. root-owned
+    ``/usr/share/ollama``) and must treat un-stat-able paths as "not a
+    directory", never 500.
     """
     try:
         return Path(path).is_dir()
@@ -40,14 +39,12 @@ def _safe_is_dir(path) -> bool:
         return False
 
 
-# Add backend dir to path
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
 from auth.authentication import get_current_subject
 
-# Import backend functions
 try:
     from utils.models import (
         scan_trained_models,
@@ -76,7 +73,7 @@ try:
         resolve_export_dir,
     )
 except ImportError:
-    # Fallback: import from parent directory
+    # Fallback: import from parent directory.
     parent_backend = backend_path.parent / "backend"
     if str(parent_backend) not in sys.path:
         sys.path.insert(0, str(parent_backend))
@@ -164,14 +161,10 @@ def _resolve_hf_cache_dir() -> Path:
 def _is_model_directory(d: Path) -> bool:
     """Return ``True`` when *d* looks like a model directory.
 
-    Requires **both** a config (``config.json`` or
-    ``adapter_config.json``) **and** weight files: loose ``.gguf`` files
-    without config may be a mixed collection, and config without weights
-    is not a model dir.
-
-    Excludes ``mmproj`` GGUF files (vision projectors) and non-weight
-    ``.bin`` files (``tokenizer.bin``, ``vocab.bin``, etc.) to avoid
-    false positives.
+    Requires both a config (``config.json``/``adapter_config.json``) and
+    weight files. Excludes ``mmproj`` GGUFs (vision projectors) and
+    non-weight ``.bin`` files (``tokenizer.bin`` etc.) to avoid false
+    positives.
     """
 
     def _is_weight_file(f: Path) -> bool:
@@ -235,8 +228,7 @@ def _scan_models_dir(models_dir: Path, *, limit: int | None = None) -> List[Loca
                 or any(child.glob("*.gguf"))
             )
         except OSError:
-            # Skip unreadable children (permissions, broken symlinks)
-            # rather than failing the whole scan.
+            # Skip unreadable children rather than failing the scan.
             continue
         if not has_model_files:
             continue
@@ -253,7 +245,7 @@ def _scan_models_dir(models_dir: Path, *, limit: int | None = None) -> List[Loca
                 updated_at = updated_at,
             ),
         )
-    # Also scan standalone .gguf files in the models directory
+    # Also scan standalone .gguf files in the models directory.
     if limit is None or len(found) < limit:
         for gguf_file in models_dir.glob("*.gguf"):
             if limit is not None and len(found) >= limit:
@@ -317,10 +309,8 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
     if not lm_dir.exists() or not lm_dir.is_dir():
         return []
 
-    # If lm_dir is itself a model directory (config AND weights), it's
-    # not an LM Studio publisher structure -- return it as a single
-    # entry. Can't skip it silently: this is the only scanner called for
-    # default LM Studio roots.
+    # If lm_dir is itself a model directory (not a publisher structure),
+    # return it as a single entry rather than skipping it silently.
     if _is_model_directory(lm_dir):
         try:
             updated_at = lm_dir.stat().st_mtime
@@ -356,9 +346,8 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
                     )
                 continue
 
-            # If the child looks like a model directory (config AND
-            # weights), surface it directly instead of descending into
-            # it as a publisher.
+            # Surface a model-directory child directly instead of
+            # descending into it as a publisher.
             if _is_model_directory(child):
                 try:
                     updated_at = child.stat().st_mtime
@@ -375,7 +364,7 @@ def _scan_lmstudio_dir(lm_dir: Path) -> List[LocalModelInfo]:
                 )
                 continue
 
-            # child is a publisher directory -- scan its subdirectories
+            # child is a publisher directory; scan its subdirectories.
             for model_dir in child.iterdir():
                 try:
                     if model_dir.is_dir():
@@ -427,10 +416,8 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
     """Return a writable directory for Ollama ``.gguf`` symlinks.
 
     Prefers ``<ollama_dir>/.studio_links/`` so links sit next to their
-    blobs. Falls back to a per-ollama-dir namespace under Studio's cache
-    when the models dir is read-only (common for system installs under
-    ``/usr/share/ollama`` or ``/var/lib/ollama``) so Ollama models still
-    surface there.
+    blobs; falls back to a per-ollama-dir namespace under Studio's cache
+    when the models dir is read-only (common for system installs).
     """
     from utils.paths.storage_roots import cache_root
 
@@ -445,8 +432,8 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
             e,
         )
 
-    # Fallback: namespace by a hash of ollama_dir so two Ollama roots
-    # don't collide. Cache path, not a security boundary.
+    # Fallback: namespace by a hash of ollama_dir so two roots don't
+    # collide. Cache path, not a security boundary.
     try:
         digest = hashlib.sha256(str(ollama_dir.resolve()).encode()).hexdigest()[:12]
     except OSError:
@@ -467,29 +454,19 @@ def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
 def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[LocalModelInfo]:
     """Scan an Ollama models directory for downloaded models.
 
-    Ollama uses a content-addressable layout::
-
-        <ollama_dir>/manifests/<host>/<namespace>/<model>/<tag>
-        <ollama_dir>/blobs/sha256-...
-
-    Default host is ``registry.ollama.ai`` namespace ``library``
-    (official), but users can pull from custom namespaces
-    (``mradermacher/llama3``) or other hosts (``hf.co/org/repo:tag``).
-    We ``rglob`` all manifest files so every layout depth is found.
-
-    Each manifest is JSON with a ``layers`` array. The
-    ``application/vnd.ollama.image.model`` layer holds the GGUF weights;
-    vision models add an ``application/vnd.ollama.image.projector``
-    layer. We read the config layer for family/size info.
+    Ollama uses a content-addressable layout
+    (``manifests/<host>/<namespace>/<model>/<tag>`` + ``blobs/sha256-...``);
+    we ``rglob`` all manifests so every layout depth is found. Each
+    manifest is JSON with a ``layers`` array: the
+    ``application/vnd.ollama.image.model`` layer holds the GGUF weights
+    and ``...image.projector`` is the vision adapter.
 
     Ollama blobs lack the ``.gguf`` extension the loading pipeline
-    requires, so we create ``.gguf``-named links to them so
-    ``detect_gguf_model`` and ``llama-server -m`` work unchanged. Each
-    model gets its own subdir under the links dir (keyed by a short hash
-    of the manifest path) so ``detect_mmproj_file`` only sees that
-    model's projector. Links are symlinks when possible, falling back to
-    hardlinks (Windows without Developer Mode). The link dir is
-    ``<ollama_dir>/.studio_links/`` when writable, else Studio's cache.
+    requires, so we create ``.gguf``-named links to them (one subdir per
+    model, keyed by a short hash of the manifest path, so
+    ``detect_mmproj_file`` only sees that model's projector). Links are
+    symlinks when possible, else hardlinks; the link dir is
+    ``.studio_links/`` when writable, else Studio's cache.
     """
     manifests_root = ollama_dir / "manifests"
     if not manifests_root.is_dir():
@@ -508,10 +485,8 @@ def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[Loca
     def _make_link(link_dir: Path, link_name: str, target: Path) -> Optional[str]:
         """Create a .gguf-named link to an Ollama blob.
 
-        Tries symlink, then hardlink (Windows without Developer Mode,
-        same filesystem). Skips the model if neither works -- a full
-        multi-GB copy in a sync API request would block the backend.
-
+        Tries symlink, then hardlink; skips the model if neither works
+        (a multi-GB copy in a sync request would block the backend).
         Idempotent: skips recreation when a valid link already exists.
         """
         link_dir.mkdir(parents = True, exist_ok = True)
@@ -519,8 +494,7 @@ def _scan_ollama_dir(ollama_dir: Path, limit: Optional[int] = None) -> List[Loca
         resolved = target.resolve()
 
         # Skip if the link already points at the same blob. Use samefile
-        # only -- size checks can reuse stale links after `ollama pull`
-        # updates a tag to a same-sized blob.
+        # only; size checks can reuse stale links after `ollama pull`.
         try:
             if link_path.exists() and os.path.samefile(str(link_path), str(resolved)):
                 return str(link_path)
@@ -673,10 +647,7 @@ async def list_local_models(
     ),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    List local model candidates from custom models dir, HF cache,
-    legacy Unsloth HF cache, and LM Studio directories.
-    """
+    """List local model candidates from the models dir, HF caches, and LM Studio dirs."""
     from utils.paths import (
         legacy_hf_cache_dir,
         hf_default_cache_dir,
@@ -691,7 +662,7 @@ async def list_local_models(
 
     # Validate models_dir against an allowlist of trusted dirs. Only the
     # trusted Path objects are used for FS access; the user string is
-    # only used for matching, never for path construction.
+    # used for matching only, never for path construction.
     allowed_roots: list[Path] = [Path("./models").resolve(), hf_cache_dir]
     if legacy_hf.is_dir():
         allowed_roots.append(legacy_hf)
@@ -719,11 +690,11 @@ async def list_local_models(
     try:
         local_models = _scan_models_dir(models_root) + _scan_hf_cache(hf_cache_dir)
 
-        # Scan legacy Unsloth HF cache for backward compatibility
+        # Scan legacy Unsloth HF cache for backward compatibility.
         if legacy_hf.is_dir() and legacy_hf.resolve() != hf_cache_dir.resolve():
             local_models += _scan_hf_cache(legacy_hf)
 
-        # Scan HF system default cache (may differ under env overrides)
+        # Scan HF system default cache (may differ under env overrides).
         if (
             hf_default.is_dir()
             and hf_default.resolve() != hf_cache_dir.resolve()
@@ -731,11 +702,11 @@ async def list_local_models(
         ):
             local_models += _scan_hf_cache(hf_default)
 
-        # Scan LM Studio directories
+        # Scan LM Studio directories.
         for lm_dir in lm_dirs:
             local_models += _scan_lmstudio_dir(lm_dir)
 
-        # Scan user-added custom folders (per-folder cap)
+        # Scan user-added custom folders (per-folder cap).
         from storage.studio_db import list_scan_folders
 
         _MAX_MODELS_PER_FOLDER = 200
@@ -747,9 +718,8 @@ async def list_local_models(
         for folder in custom_folders:
             folder_path = Path(folder["path"])
             try:
-                # Ollama scanner creates .studio_links/ with .gguf
-                # symlinks. Filter those from generic scanners to avoid
-                # duplicates and leaking internal paths into the UI.
+                # Filter Ollama .studio_links/ from generic scanners to
+                # avoid duplicates and leaking internal paths into the UI.
                 _generic = [
                     m
                     for m in (
@@ -770,10 +740,9 @@ async def list_local_models(
                 continue
             local_models += [m.model_copy(update = {"source": "custom"}) for m in custom_models]
 
-        # Deduplicate, but always keep custom folder entries so they show
-        # in the "Custom Folders" UI section even when the same model is
-        # also in the HF cache or default models dir. Custom entries use
-        # an (id, source) key to avoid collisions.
+        # Deduplicate, but always keep custom folder entries (keyed by
+        # (id, source)) so they show in the "Custom Folders" UI section
+        # even when the model is also in the HF cache.
         deduped: dict[str, LocalModelInfo] = {}
         for model in local_models:
             key = f"{model.id}\x00custom" if model.source == "custom" else model.id
@@ -820,8 +789,7 @@ async def add_scan_folder_endpoint(
         folder = add_scan_folder(body.path)
     except ValueError as e:
         logger.warning("Scan folder rejected: %s (path=%s)", e, body.path)
-        # Curated, path-free validation message (e.g. "Path does not exist"):
-        # forward the text, not the raw exception.
+        # Forward the curated, path-free validation message.
         rejection_message = str(e)
         raise HTTPException(status_code = 400, detail = rejection_message)
     logger.info("Scan folder added: %s", folder.get("path"))
@@ -844,10 +812,9 @@ async def remove_scan_folder_endpoint(
 async def get_recommended_folders(current_subject: str = Depends(get_current_subject)):
     """Return well-known model directories that exist on this machine.
 
-    Lightweight alternative to ``browse-folders`` for quick-pick chips
-    without enumerating a directory tree. Returns paths that exist on
-    disk (HF cache, LM Studio, Ollama, ``~/models``, etc.) for the
-    frontend's one-click "Recommended" shortcuts.
+    Lightweight alternative to ``browse-folders`` for the frontend's
+    one-click "Recommended" chips; returns existing paths only (HF
+    cache, LM Studio, Ollama, ``~/models``, etc.).
     """
     from utils.paths.storage_roots import lmstudio_model_dirs
 
@@ -867,14 +834,14 @@ async def get_recommended_folders(current_subject: str = Depends(get_current_sub
             seen.add(resolved)
             folders.append(resolved)
 
-    # LM Studio model directories
+    # LM Studio model directories.
     try:
         for p in lmstudio_model_dirs():
             _add(p)
     except Exception as e:
         logger.warning("Failed to scan for LM Studio model directories: %s", e)
 
-    # Ollama model directories
+    # Ollama model directories.
     ollama_env = os.environ.get("OLLAMA_MODELS")
     if ollama_env:
         _add(Path(ollama_env).expanduser())
@@ -889,24 +856,19 @@ async def get_recommended_folders(current_subject: str = Depends(get_current_sub
 
 
 # Max children to stat when checking if a directory "looks like" it
-# holds models. Keeps the browser snappy on dirs with thousands of
-# unrelated entries.
+# holds models; keeps the browser snappy on huge dirs.
 _BROWSE_MODEL_HINT_PROBE = 64
-# Hard cap on subdirectory entries returned. Browsing ``/usr/lib`` or
-# ``/proc`` must not stat-storm the process or send tens of thousands of
-# rows to the client.
+# Hard cap on subdirectory entries returned, so browsing ``/usr/lib``
+# can't stat-storm the process or flood the client.
 _BROWSE_ENTRY_CAP = 2000
 
 
 def _count_model_files(directory: Path, cap: int = 200) -> int:
     """Count GGUF/safetensors files immediately inside *directory*.
 
-    Surfaces a count-hint so the UI can mark a leaf directory (no
-    subdirs, only weights) as a valid "Use this folder" target.
-
-    Bounded by *visited entries*, not match count: the scan stops after
-    ``cap`` entries even in dirs full of non-model files/subdirs, so a UI
-    hint never costs more than a bounded directory walk.
+    Surfaces a count-hint so the UI can mark a weights-only leaf dir as a
+    valid "Use this folder" target. Bounded by *visited entries* (stops
+    after ``cap``), so the hint never costs more than a bounded walk.
     """
     n = 0
     visited = 0
@@ -932,10 +894,9 @@ def _count_model_files(directory: Path, cap: int = 200) -> int:
 
 
 def _has_direct_model_signal(directory: Path) -> bool:
-    """Return True if *directory* has an immediate child signalling a
-    model: a GGUF/safetensors/config.json file, or a `models--*` subdir
-    (HF hub cache). Bounded by ``_BROWSE_MODEL_HINT_PROBE`` to stay
-    fast."""
+    """Return True if an immediate child signals a model: a
+    GGUF/safetensors/config.json file or a ``models--*`` subdir (HF
+    cache). Bounded by ``_BROWSE_MODEL_HINT_PROBE``."""
     try:
         it = directory.iterdir()
     except OSError:
@@ -962,22 +923,13 @@ def _has_direct_model_signal(directory: Path) -> bool:
 
 
 def _looks_like_model_dir(directory: Path) -> bool:
-    """Bounded heuristic to flag directories worth exploring in the
-    folder browser. False negatives are fine; the real scanner is
-    authoritative.
+    """Bounded heuristic to flag dirs worth exploring in the browser.
 
-    Three signals, cheapest first:
-
-    1. Directory name ``models--*`` (HuggingFace hub cache layout; its
-       ``blobs``/``refs``/``snapshots`` children wouldn't match the
-       file-level probes below).
-    2. An immediate child is a weight file or config (via
-       :func:`_has_direct_model_signal`).
-    3. A grandchild has a direct signal -- catches the
-       ``publisher/model/weights.gguf`` layout of LM Studio and Ollama.
-       Probes at most the first ``_BROWSE_MODEL_HINT_PROBE`` child dirs,
-       each via a bounded :func:`_has_direct_model_signal`, so total cost
-       is O(PROBE^2) worst-case.
+    False negatives are fine (the real scanner is authoritative). Three
+    signals, cheapest first: (1) name ``models--*`` (HF cache layout),
+    (2) an immediate child weight/config file, (3) a grandchild with a
+    direct signal (LM Studio / Ollama ``publisher/model`` layout, probing
+    the first ``_BROWSE_MODEL_HINT_PROBE`` child dirs).
     """
     if directory.name.startswith("models--"):
         return True
@@ -997,7 +949,6 @@ def _looks_like_model_dir(directory: Path) -> bool:
                     continue
             except OSError:
                 continue
-            # Fast name check first.
             if child.name.startswith("models--"):
                 return True
             if _has_direct_model_signal(child):
@@ -1008,15 +959,13 @@ def _looks_like_model_dir(directory: Path) -> bool:
 
 
 def _build_browse_allowlist() -> list[Path]:
-    """Return the root directories the folder browser may walk. The same
-    list seeds the sidebar suggestion chips, so chip targets are always
-    reachable.
+    """Return the root directories the folder browser may walk.
 
-    Roots: the user's HOME, resolved HF cache dirs, Studio's
+    The same list seeds the sidebar suggestion chips, so chip targets are
+    always reachable. Roots: HOME, resolved HF cache dirs, Studio's
     outputs/exports/studio root, registered scan folders, and well-known
-    third-party local-LLM dirs (LM Studio, Ollama, `~/models`). Each is
-    added only if it resolves to a real directory, so we never produce a
-    "dead" sandbox boundary.
+    local-LLM dirs (LM Studio, Ollama, ``~/models``); each added only if
+    it resolves to a real directory.
     """
     from utils.paths import (
         hf_default_cache_dir,
@@ -1085,7 +1034,8 @@ def _build_browse_allowlist() -> list[Path]:
 
 
 def _is_path_inside_allowlist(target: Path, allowed_roots: list[Path]) -> bool:
-    """Return True if *target* equals or descends from any allowed root.
+    """True if *target* equals or descends from any allowed root.
+
     Uses ``os.path.realpath`` so symlinks can't escape the sandbox.
     """
     try:
@@ -1243,31 +1193,21 @@ async def browse_folders(
     ),
     current_subject: str = Depends(get_current_subject),
 ):
-    """
-    List immediate subdirectories of *path* for the Custom Folders picker.
+    """List immediate subdirectories of *path* for the Custom Folders picker.
 
     Lets the frontend render a modal folder browser without a native OS
-    dialog (Studio is served over HTTP, so the browser can't reveal host
-    paths). Read-only: it only enumerates visible subdirectories so the
-    user can click to a folder and hand the string back to POST
-    `/api/models/scan-folders`.
+    dialog. Read-only: enumerates visible subdirectories so the user can
+    click to a folder and hand the string to POST /api/models/scan-folders.
 
-    Sandbox: bounded to the allowlist from
-    :func:`_build_browse_allowlist` (HOME, HF cache, Studio dirs,
-    registered scan folders, well-known model dirs). Paths outside it
-    return 403 so users can't probe ``/etc``, ``/proc``, ``/root`` (when
-    not HOME), or other sensitive locations even if the process can read
-    them. Symlinks are resolved via ``os.path.realpath`` first, so
-    traversal can't escape the sandbox.
-
-    Sorting: model-bearing dirs first, then plain dirs, then hidden
-    entries (if `show_hidden=true`).
+    Sandbox: bounded to :func:`_build_browse_allowlist`; paths outside it
+    return 403, and symlinks are resolved via ``os.path.realpath`` first
+    so traversal can't escape. Sorting: model-bearing dirs, then plain,
+    then hidden (if ``show_hidden=true``).
     """
     from utils.paths import hf_default_cache_dir, well_known_model_dirs
     from storage.studio_db import list_scan_folders
 
-    # Build the allowlist once -- the sandbox check and suggestion chips
-    # share it, so chips are always navigable.
+    # Build once; the sandbox check and suggestion chips share it.
     allowed_roots = _build_browse_allowlist()
 
     try:
@@ -1282,8 +1222,7 @@ async def browse_folders(
             )
         raise
 
-    # Enumerate immediate subdirectories with a bounded cap so a stray
-    # query against ``/usr/lib`` or ``/proc`` can't stat-storm us.
+    # Enumerate immediate subdirectories with a bounded cap.
     entries: list[BrowseEntry] = []
     truncated = False
     visited = 0
@@ -1303,12 +1242,9 @@ async def browse_folders(
 
     try:
         for child in it:
-            # Bound by *visited*, not *appended*: in dirs full of files
-            # (or hidden subdirs when ``show_hidden=False``) a cap on
-            # ``len(entries)`` would never trigger and we'd stat every
-            # child. Counting visits caps worst-case work at
-            # ``_BROWSE_ENTRY_CAP`` iterdir/is_dir calls regardless of
-            # how many survive the filters below.
+            # Bound by *visited*, not *appended*: a cap on len(entries)
+            # would never trigger in dirs full of files. Counting visits
+            # caps worst-case work at ``_BROWSE_ENTRY_CAP`` calls.
             visited += 1
             if visited > _BROWSE_ENTRY_CAP:
                 truncated = True
@@ -1336,10 +1272,10 @@ async def browse_folders(
             exc,
         )
     except OSError as exc:
-        # Rare: iterdir succeeded but reading a specific entry failed.
+        # Rare: iterdir succeeded but reading an entry failed.
         logger.warning("browse-folders: partial enumeration of %s: %s", target, exc)
 
-    # Model-bearing dirs first, then plain, then hidden; case-insensitive
+    # Model-bearing first, then plain, then hidden; case-insensitive
     # alphabetical within each bucket.
     def _sort_key(e: BrowseEntry) -> tuple[int, str]:
         bucket = 0 if e.has_models else (2 if e.hidden else 1)
@@ -1347,10 +1283,9 @@ async def browse_folders(
 
     entries.sort(key = _sort_key)
 
-    # Parent is None at the filesystem root (`p.parent == p`) and when
-    # the parent would leave the sandbox -- otherwise the up-row would
-    # 403 on click. Users can still hop to other allowed roots via the
-    # suggestion chips below.
+    # Parent is None at the filesystem root and when it would leave the
+    # sandbox (else the up-row would 403 on click); users can still hop
+    # to other allowed roots via the suggestion chips.
     parent: Optional[str]
     if target.parent == target or not _is_path_inside_allowlist(target.parent, allowed_roots):
         parent = None
@@ -1387,12 +1322,8 @@ async def browse_folders(
             _add_sug(Path(folder.get("path", "")))
     except Exception as exc:
         logger.debug("browse-folders: could not load scan folders: %s", exc)
-    # Dirs used by other local-LLM tools: LM Studio
-    # (`~/.lmstudio/models` + legacy `~/.cache/lm-studio/models` + LM
-    # Studio settings.json downloadsFolder), Ollama (`~/.ollama/models`
-    # + common system paths + OLLAMA_MODELS env var), and generic spots
-    # (`~/models`, `~/Models`). Each helper returns only existing paths
-    # so we never show dead chips.
+    # Dirs used by other local-LLM tools (LM Studio, Ollama, ~/models);
+    # the helper returns only existing paths, so no dead chips.
     try:
         for p in well_known_model_dirs():
             _add_sug(p)
@@ -1410,8 +1341,8 @@ async def browse_folders(
 
 
 def _looks_like_mlx_repo(model_id: str) -> bool:
-    """Name heuristic for unloaded models, mirrors the -GGUF suffix check.
-    Tokenized so MLX only matches as a whole name segment."""
+    """Name heuristic for unloaded models (mirrors the -GGUF suffix check);
+    tokenized so MLX only matches as a whole name segment."""
     if model_id.lower().startswith("mlx-community/"):
         return True
     tail = model_id.split("/")[-1]
@@ -1459,14 +1390,12 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
                 )
             )
 
-        # Combine default and loaded models.
+        # Combine default and loaded; prefer loaded entries for duplicate
+        # ids so runtime flags survive.
         all_models = []
         seen_ids = set()
-
-        # Prefer loaded entries for duplicate ids so runtime flags survive.
         loaded_by_id = {model_info.id: model_info for model_info in loaded_models}
 
-        # Add default models
         for model_id in default_models:
             if model_id not in seen_ids:
                 model_info = loaded_by_id.get(model_id) or ModelDetails(
@@ -1478,7 +1407,6 @@ async def list_models(current_subject: str = Depends(get_current_subject)):
                 all_models.append(model_info)
                 seen_ids.add(model_id)
 
-        # Add loaded models.
         for model_info in loaded_models:
             if model_info.id not in seen_ids:
                 all_models.append(model_info)
@@ -1551,12 +1479,11 @@ async def get_model_config(
 
         config_dict = load_model_defaults(model_name)
 
-        # Detect capabilities (pass HF token for gated models).
+        # Detect capabilities (HF token for gated models).
         is_vision = is_vision_model(model_name, hf_token = hf_token)
         is_embedding = is_embedding_model(model_name, hf_token = hf_token)
         audio_type = detect_audio_type(model_name, hf_token = hf_token)
 
-        # Check if it's a LoRA adapter.
         is_lora = False
         base_model = None
         max_position_embeddings = None
@@ -1568,7 +1495,7 @@ async def get_model_config(
         except Exception:
             pass
 
-        # Fallback: try AutoConfig directly if not found yet.
+        # Fallback: try AutoConfig directly.
         if max_position_embeddings is None:
             try:
                 from transformers import AutoConfig as _AutoConfig
@@ -1630,7 +1557,6 @@ async def scan_loras(
         resolved_exports_dir = str(resolve_export_dir(exports_dir))
         lora_list = []
 
-        # Scan training outputs.
         trained_models = scan_trained_models(outputs_dir = resolved_outputs_dir)
         for display_name, model_path, model_type in trained_models:
             base_model = get_base_model_from_checkpoint(model_path)
@@ -2092,16 +2018,15 @@ async def get_gguf_variants(
     hf_token: Optional[str] = Query(None, description = "HuggingFace token for private repos"),
     current_subject: str = Depends(get_current_subject),
 ):
-    """List GGUF quantization variants for a HuggingFace repo or local
-    directory (e.g. LM Studio model folder).
+    """List GGUF quantization variants for a HF repo or local directory.
 
-    Returns all variants (Q4_K_M, Q8_0, BF16, etc.) with file sizes,
-    whether the model supports vision, and the recommended default.
+    Returns all variants with file sizes, vision support, and the
+    recommended default.
     """
     try:
         from utils.models.model_config import is_local_path, list_local_gguf_variants
 
-        # Local directory path (e.g. LM Studio models) — scan filesystem.
+        # Local directory path — scan filesystem.
         if is_local_path(repo_id):
             variants, has_vision = list_local_gguf_variants(repo_id)
 
@@ -2127,22 +2052,19 @@ async def get_gguf_variants(
         # Remote HuggingFace repo — query HF API.
         variants, has_vision = list_gguf_variants(repo_id, hf_token = hf_token)
 
-        # Determine default variant.
         filenames = [v.filename for v in variants]
         best = _pick_best_gguf(filenames)
         default_variant = _extract_quant_label(best) if best else None
 
         # Which variants are fully downloaded in the HF cache. For split
-        # GGUFs, ALL shards must be present -- sum cached bytes per
-        # variant vs. the expected total. The HF cache dir uses the
-        # repo_id casing from download time, which may differ from the
+        # GGUFs ALL shards must be present, so sum cached bytes per variant
+        # vs. the expected total. Cache dir casing may differ from the
         # canonical repo_id, so match case-insensitively.
         cached_bytes_by_quant: dict[str, int] = {}
         try:
             import re as _re
             from huggingface_hub import constants as hf_constants
 
-            # Sanitize repo_id: "owner/name" with safe chars only.
             if not _is_valid_repo_id(repo_id):
                 raise ValueError(f"Invalid repo_id format: {repo_id}")
 
@@ -2166,7 +2088,7 @@ async def get_gguf_variants(
             cached = cached_bytes_by_quant.get(variant.quant, 0)
             if cached == 0 or variant.size_bytes == 0:
                 return False
-            # Small rounding tolerance (symlinks vs real sizes).
+            # Rounding tolerance (symlinks vs real sizes).
             return cached >= variant.size_bytes * 0.99
 
         return GgufVariantsResponse(
@@ -2226,7 +2148,7 @@ async def get_gguf_download_progress(
                     fname = f.name.lower().replace("-", "").replace("_", "")
                     if not variant_lower or variant_lower in fname:
                         downloaded_bytes += f.stat().st_size
-                # In-progress downloads (.incomplete) in blobs.
+                # In-progress (.incomplete) downloads in blobs.
                 blobs_dir = entry / "blobs"
                 if blobs_dir.is_dir():
                     for f in blobs_dir.iterdir():
@@ -2251,9 +2173,9 @@ async def get_gguf_download_progress(
 def _resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
     """Pick the most useful on-disk path for a HF cache repo.
 
-    Prefers the most-recent snapshot dir (what `from_pretrained` points
-    at), falling back to the cache repo root. Returns the resolved
-    realpath so symlinks under snapshots/ follow back to blobs/.
+    Prefers the most-recent snapshot dir (what ``from_pretrained`` uses),
+    falling back to the cache repo root. Returns the resolved realpath so
+    snapshot symlinks follow back to blobs/.
     """
     try:
         snapshots_dir = repo_dir / "snapshots"
@@ -2318,7 +2240,6 @@ async def get_download_progress(
         if downloaded_bytes == 0:
             return {**_empty, "cache_path": cache_path}
 
-        # Expected size from HF API (cached per repo_id).
         expected_bytes = _get_repo_size_cached(repo_id)
         if expected_bytes <= 0:
             # Total unknown; report bytes only, no percentage.
@@ -2329,10 +2250,9 @@ async def get_download_progress(
                 "cache_path": cache_path,
             }
 
-        # 95% completion threshold (blob dedup can make completed_bytes
-        # differ slightly from expected_bytes). Do NOT treat "no
-        # .incomplete files" as done -- HF downloads sequentially, so
-        # between files none exist even though it's far from finished.
+        # 95% threshold (blob dedup can skew completed_bytes). Do NOT
+        # treat "no .incomplete files" as done: HF downloads sequentially,
+        # so none exist between files even when far from finished.
         if completed_bytes >= expected_bytes * 0.95:
             progress = 1.0
         else:
@@ -2374,7 +2294,7 @@ def _all_hf_cache_scans():
     scans = [scan_cache_dir()]
     seen: set[str] = set()
     try:
-        # Resolve the active cache dir for deduplication.
+        # Resolve the active cache dir for dedup.
         from huggingface_hub.constants import HF_HUB_CACHE
         seen.add(str(Path(HF_HUB_CACHE).resolve()))
     except Exception:
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index c78739be84..64d1c3eab3 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -54,10 +54,8 @@ router = APIRouter()
 async def get_public_key(current_subject: str = Depends(get_current_subject)):
     """Return the RSA public key PEM for client-side API key encryption.
 
-    The ``fingerprint`` field is a short SHA256 of the PEM, for diagnostics: a
-    mismatch between what the frontend captured at encrypt time and what the
-    server reports here signals the keypair rotated mid-flight (e.g. the server
-    re-ran ``init_key_pair``).
+    ``fingerprint`` is a short SHA256 of the PEM; a mismatch with what the
+    frontend captured at encrypt time signals the keypair rotated mid-flight.
     """
     return {
         "public_key": get_public_key_pem(),
@@ -80,9 +78,7 @@ async def list_registry(current_subject: str = Depends(get_current_subject)):
 @router.get("/pricing")
 async def get_pricing_snapshot(current_subject: str = Depends(get_current_subject)):
     """Static per-MTok pricing table the frontend uses to convert upstream
-    usage chunks into a per-turn USD cost. See ``core/inference/pricing.py``
-    for sourcing notes; values reflect the published prices as of the file's
-    last update."""
+    usage into per-turn USD cost. See ``core/inference/pricing.py`` for sourcing."""
     return pricing_snapshot()
 
 
@@ -307,15 +303,10 @@ async def list_provider_models(
 
     try:
         models = await client.list_models()
-        # Registry-level model-id filters are scoped to the canonical native
-        # Gemini base. A custom Gemini OAI-compatible proxy (LiteLLM, deployment
-        # gateway) returns IDs like `google/gemini-2.5-flash`,
-        # `gemini/gemini-2.5-flash`, or team-prefixed deployment aliases; the
-        # native allowlist regex would strip those and leave the picker empty,
-        # even though the chat path routes them via the OAI-compatible
-        # dispatcher (the same gate ExternalProviderClient applies for request
-        # building). Match the host check here so the model list and chat
-        # dispatch agree on what counts as "native".
+        # Registry model-id filters only apply to the native Gemini base. A
+        # custom OAI-compatible proxy returns prefixed IDs the native allowlist
+        # would strip, leaving the picker empty; match the host check here so the
+        # model list and chat dispatch agree on what counts as "native".
         apply_registry_model_filters = True
         if payload.provider_type == "gemini":
             try:
@@ -342,10 +333,8 @@ async def list_provider_models(
             denylist = info.get("model_id_denylist")
             if denylist is not None:
                 models = [m for m in models if not denylist.search(m.get("id", ""))]
-        # Optional cap after filtering so registry entries with a large remote
-        # catalog (e.g. HF Inference Providers) stay picker-sized. No
-        # server-side popularity sort, so this is "first N matches" — pair with
-        # default_models for any must-have flagship ids.
+        # Optional cap after filtering to keep large catalogs picker-sized.
+        # Unsorted, so "first N matches"; pair with default_models for flagships.
         limit = info.get("model_id_limit")
         if isinstance(limit, int) and limit > 0:
             models = models[:limit]
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 7ce086e5b2..96403e21a5 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -16,12 +16,11 @@ import asyncio
 from datetime import datetime
 import uuid as _uuid
 
-# Add backend directory to path (same directory structure).
+# Add backend directory to path.
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
 
-# Import backend functions.
 try:
     from core.training import get_training_backend
     from core.training.resume import (
@@ -33,7 +32,7 @@ try:
     from utils.models.model_config import load_model_defaults
     from utils.paths import resolve_dataset_path
 except ImportError:
-    # Fallback: import from the parent directory.
+    # Fallback: parent directory.
     parent_backend = backend_path.parent / "backend"
     if str(parent_backend) not in sys.path:
         sys.path.insert(0, str(parent_backend))
@@ -121,13 +120,12 @@ async def start_training(
     try:
         logger.info(f"Starting training job with model: {request.model_name}")
 
-        # NOTE: No in-process ensure_transformers_version() call here.
-        # The subprocess (worker.py) activates the correct version in a
-        # fresh Python interpreter before importing any ML libraries.
+        # No in-process ensure_transformers_version(): the subprocess
+        # (worker.py) activates the correct version before importing ML libs.
 
         backend = get_training_backend()
 
-        # Check if training is already active (before mutating state).
+        # Check before mutating state.
         if backend.is_training_active():
             existing_job_id: Optional[str] = getattr(backend, "current_job_id", "")
             return TrainingJobResponse(
@@ -140,8 +138,8 @@ async def start_training(
                 error = "Training already active",
             )
 
-        # Job ID — passed to start_training(), which sets it on the backend only
-        # after confirming the old pump thread is dead.
+        # Job ID; start_training() sets it on the backend only after the old
+        # pump thread is dead.
         job_id = f"job_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{_uuid.uuid4().hex[:8]}"
 
         # Validate dataset paths if provided.
@@ -239,9 +237,8 @@ async def start_training(
             "gpu_ids": request.gpu_ids,
         }
 
-        # Training page has no trust_remote_code toggle — the value comes from
-        # YAML model defaults on model select. As a safety net, consult the YAML
-        # directly so models that need it always get it.
+        # Training page has no trust_remote_code toggle; as a safety net consult
+        # YAML model defaults directly so models that need it always get it.
         if not training_kwargs["trust_remote_code"]:
             model_defaults = load_model_defaults(request.model_name)
             yaml_trust = model_defaults.get("training", {}).get("trust_remote_code", False)
@@ -407,10 +404,8 @@ async def get_training_status(current_subject: str = Depends(get_current_subject
         backend = get_training_backend()
         job_id: str = getattr(backend, "current_job_id", "") or ""
 
-        # Check if training is active
         is_active = backend.is_training_active()
 
-        # Get progress info from trainer
         try:
             progress = backend.trainer.get_training_progress()
         except Exception:
@@ -421,7 +416,6 @@ async def get_training_status(current_subject: str = Depends(get_current_subject
         ) or "Ready to train"
         error_message = getattr(progress, "error", None) if progress else None
 
-        # Check if training was stopped by user
         trainer_stopped = getattr(backend, "_should_stop", False)
 
         # Derive high-level phase
@@ -497,14 +491,12 @@ async def get_training_metrics(current_subject: str = Depends(get_current_subjec
     try:
         backend = get_training_backend()
 
-        # Get metrics from backend
         loss_history = backend.loss_history
         lr_history = backend.lr_history
         step_history = backend.step_history
         grad_norm_history = getattr(backend, "grad_norm_history", [])
         grad_norm_step_history = getattr(backend, "grad_norm_step_history", [])
 
-        # Get current values
         current_loss = loss_history[-1] if loss_history else None
         current_lr = lr_history[-1] if lr_history else None
         current_step = step_history[-1] if step_history else None
@@ -753,8 +745,8 @@ async def stream_training_progress(
                     # No steps yet, but training is active (model loading, etc.).
                     no_update_count += 1
                     if no_update_count % 5 == 0:
-                        # Pull total_steps + status from trainer so the frontend
-                        # can show "Tokenizing…" etc.
+                        # Pull total_steps + status so the frontend can show
+                        # "Tokenizing…" etc.
                         tp_prep = getattr(
                             getattr(backend, "trainer", None),
                             "training_progress",
diff --git a/studio/backend/run.py b/studio/backend/run.py
index b9f271b4be..c992a4bec2 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -27,8 +27,8 @@ except ValueError as exc:
     configured = os.environ.get("UNSLOTH_CPU_THREADS")
     raise SystemExit(f"Error: Invalid UNSLOTH_CPU_THREADS value {configured!r}: {exc}") from None
 
-# Anaconda/conda-forge Python: seed platform._sys_version_cache before
-# imports that trigger attrs -> rich -> structlog -> platform crash.
+# Anaconda/conda-forge Python: seed platform._sys_version_cache before imports
+# that trigger attrs -> rich -> structlog -> platform crash.
 # See: https://github.com/python/cpython/issues/102396
 import _platform_compat  # noqa: F401
 
@@ -83,10 +83,9 @@ def _resolve_external_ip() -> str:
 
 
 def _install_uvicorn_startup_log_rewrite(bind_host: str, display_host: str) -> None:
-    """Rewrite Uvicorn's startup log line: swap the wildcard bind for the
-    externally-reachable address, replace the CTRL+C suffix with our
-    Mac-aware stop hint, and rename the prefix to "Unsloth Studio running
-    on"."""
+    """Rewrite Uvicorn's startup log line: swap wildcard bind for the
+    externally-reachable address, use our Mac-aware stop hint, and rename the
+    prefix to "Unsloth Studio running on"."""
     import logging
     import re
 
@@ -147,8 +146,8 @@ def _local_port_open(
 
 
 def _working_local_url(port: int) -> "str | None":
-    """A working loopback URL on this machine, or None if neither
-    127.0.0.1 nor ::1 responds. Fallback when external reachability fails."""
+    """A working loopback URL on this machine, or None if neither 127.0.0.1 nor
+    ::1 responds. Fallback when external reachability fails."""
     if _local_port_open("127.0.0.1", port):
         return f"http://127.0.0.1:{port}"
     if _local_port_open("::1", port):
@@ -159,10 +158,9 @@ def _working_local_url(port: int) -> "str | None":
 def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
     """Return the IPv4 loopback URL when localhost won't reach 127.0.0.1.
 
-    Local Studio binds to 127.0.0.1. Where localhost resolves to IPv6
-    only (::1), http://localhost:<port> fails -- or worse, hits a
-    different process on ::1 -- even though http://127.0.0.1:<port> works.
-    Return the IPv4 URL so the caller can tell the user what to open.
+    Local Studio binds to 127.0.0.1. Where localhost resolves to IPv6 only (::1),
+    http://localhost:<port> fails (or hits a different process on ::1) even though
+    http://127.0.0.1:<port> works. Return the IPv4 URL for the caller to surface.
     """
     import socket
 
@@ -193,11 +191,10 @@ def _localhost_ipv6_mismatch_url(bind_host: str, port: int) -> "str | None":
             if host == "::1":
                 has_ipv6_loopback = True
 
-    # A connection to ::1 is NOT evidence Studio is reachable there:
-    # Studio binds 127.0.0.1 only, so anything on ::1 is a different
-    # process -- exactly when to steer the user to 127.0.0.1. Dual-stack
-    # localhost is fine (browsers fall back to 127.0.0.1 when ::1
-    # refuses), so only the IPv6-only case strands the user.
+    # A connection to ::1 is NOT evidence Studio is reachable there: Studio binds
+    # 127.0.0.1 only, so anything on ::1 is a different process. Dual-stack
+    # localhost is fine (browsers fall back to 127.0.0.1), so only the IPv6-only
+    # case strands the user.
     if has_ipv6_loopback and not has_ipv4_loopback:
         return ipv4_url
     return None
@@ -230,11 +227,10 @@ def _print_localhost_ipv6_mismatch_warning(local_url: str, port: int) -> None:
 
 
 def _verify_global_reachability(display_host: str, port: int) -> None:
-    """Probe check-host.net to confirm display_host:port is reachable
-    from the public internet. Synchronous so the caller can render output
-    between the banner URL section and the trailing stop hint. Bounded at
-    ~15s; failures are swallowed (verifier failing != Studio failing).
-    Only meaningful when bound to a wildcard host."""
+    """Probe check-host.net to confirm display_host:port is reachable from the
+    public internet. Synchronous so output lands between the banner URLs and the
+    stop hint. Bounded at ~15s; failures swallowed (verifier failing != Studio
+    failing). Only meaningful for a wildcard bind."""
     import ipaddress
     import json
     import time
@@ -423,9 +419,8 @@ def _emit_startup_output(host: str, port: int, display_host: str) -> None:
 def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
     """Return (pid, process_name) listening on *port*, or None.
 
-    Uses psutil when available, falling back to None so callers can still
-    report the conflict without process details. Works on Windows, macOS,
-    and Linux wherever psutil is installed.
+    Uses psutil when available, else None so callers can still report the conflict
+    without process details.
     """
     try:
         import psutil
@@ -450,17 +445,14 @@ def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
 def _is_port_free(host: str, port: int) -> bool:
     """Check if a port is available for binding.
 
-    When *host* is ``0.0.0.0`` (wildcard), also check whether anything is
-    already listening on ``127.0.0.1`` (and ``::1`` when IPv6 exists). An
-    SSH tunnel may hold the loopback address while our wildcard bind
-    succeeds, making Studio unreachable via ``localhost``.
-
-    Works on Windows, macOS, and Linux.
+    For a ``0.0.0.0`` wildcard host, also check whether anything is listening on
+    ``127.0.0.1`` (and ``::1`` when IPv6 exists): an SSH tunnel may hold loopback
+    while the wildcard bind succeeds, making Studio unreachable via ``localhost``.
     """
     import socket
 
     # 1. Can we bind to the requested address? getaddrinfo resolves both
-    #    IPv4 ("0.0.0.0") and IPv6 ("::") to the right address family.
+    #    IPv4 and IPv6 to the right address family.
     try:
         addr_info = socket.getaddrinfo(host, port, socket.AF_UNSPEC, socket.SOCK_STREAM)
         family, socktype, proto, _, sockaddr = addr_info[0]
@@ -470,9 +462,8 @@ def _is_port_free(host: str, port: int) -> bool:
     except OSError:
         return False
 
-    # 2. When binding to all interfaces, verify localhost isn't already
-    #    claimed by another process (e.g. an SSH -L tunnel). A successful
-    #    TCP connect means something is listening.
+    # 2. On a wildcard bind, verify localhost isn't already claimed by another
+    #    process (e.g. an SSH -L tunnel); a successful connect means it is.
     if host in ("0.0.0.0", "::"):
         for loopback, family in [
             ("127.0.0.1", socket.AF_INET),
@@ -550,9 +541,8 @@ def _remove_pid_file():
 def _graceful_shutdown(server = None):
     """Shut down all subprocess backends and the uvicorn server.
 
-    Called from signal handlers to clean up child processes before the
-    parent exits. Critical on Windows where atexit handlers are
-    unreliable after Ctrl+C.
+    Called from signal handlers to clean up children before exit. Critical on
+    Windows where atexit handlers are unreliable after Ctrl+C.
     """
     _remove_pid_file()
     logger.info("Graceful shutdown initiated — cleaning up subprocesses...")
@@ -610,9 +600,8 @@ _DEFAULT_FRONTEND_PATH = Path(__file__).resolve().parent.parent / "frontend" / "
 def _iter_frontend_fallback_candidates() -> "list[Path]":
     """Yield `studio/frontend/dist` paths to try when the default is missing.
 
-    Covers PATH-shadowed binaries whose __file__ resolves into a
-    site-packages tree with no vite build (e.g. plain `pip install
-    unsloth` from PyPI).
+    Covers PATH-shadowed binaries whose __file__ resolves into a site-packages
+    tree with no vite build (e.g. plain `pip install unsloth`).
     """
     import ast
     import re
@@ -638,9 +627,8 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
                     src = finder.read_text(encoding = "utf-8")
                 except OSError:
                     continue
-                # Tolerate single- or multi-line dict literals; [^}]*
-                # still rejects nested dicts, which the setuptools
-                # template never emits for editable installs.
+                # Tolerate single/multi-line dict literals; [^}]* rejects nested
+                # dicts, which the setuptools editable template never emits.
                 m = re.search(r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S)
                 if not m:
                     continue
@@ -648,8 +636,7 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
                     mapping = ast.literal_eval(m.group(1))
                 except (SyntaxError, ValueError):
                     continue
-                # Defensive: literal_eval can return a set/list/None if
-                # the matched `{...}` literal isn't a dict.
+                # literal_eval can return a set/list/None if `{...}` isn't a dict.
                 if not isinstance(mapping, dict):
                     continue
                 studio_pkg = mapping.get("studio")
@@ -661,8 +648,8 @@ def _iter_frontend_fallback_candidates() -> "list[Path]":
 def _resolve_frontend_path(frontend_path: Path) -> tuple[Optional[Path], list[Path]]:
     """Pick a frontend dir that contains `index.html`.
 
-    Returns (chosen, attempted). `chosen` is None if nothing servable was
-    found; `attempted` is the ordered list for diagnostics.
+    Returns (chosen, attempted). `chosen` is None if nothing servable was found;
+    `attempted` is the ordered list for diagnostics.
     """
     attempted: list[Path] = []
     seen: set[Path] = set()
@@ -706,14 +693,12 @@ def run_server(
         llama_parallel_slots: parallel slots for llama-server
 
     Note:
-        Signal handlers are NOT registered here so embedders (e.g. Colab
-        notebooks) keep their own interrupt semantics. Standalone callers
-        should register handlers after calling this.
+        Signal handlers are NOT registered here so embedders (e.g. Colab) keep
+        their own interrupt semantics; standalone callers register them after.
     """
     global _server, _shutdown_event
 
-    # Windows console encoding (cp1252) can't encode emoji. Reconfigure
-    # stdout to UTF-8 so startup messages don't crash the server.
+    # Windows cp1252 can't encode emoji; reconfigure stdout to UTF-8.
     if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
         try:
             sys.stdout.reconfigure(encoding = "utf-8", errors = "replace")
@@ -756,9 +741,8 @@ def run_server(
             print("=" * 50)
             print("")
 
-    # Setup frontend if path provided (skip in api-only mode). Falls back
-    # through alternate locations if the default lacks a built dist;
-    # errors loudly rather than serving 404 on `/`.
+    # Setup frontend (skip in api-only). Falls back through alternate locations if
+    # the default lacks a built dist; errors loudly rather than 404 on `/`.
     if frontend_path and not api_only:
         chosen, attempted = _resolve_frontend_path(Path(frontend_path))
         if chosen is not None and setup_frontend(app, chosen):
@@ -775,9 +759,8 @@ def run_server(
                 or os.environ.get("STUDIO_HOME")
                 or str(Path.home() / ".unsloth" / "studio")
             )
-            # Windows ships the shim at $STUDIO_HOME/bin/unsloth.exe (a
-            # hardlink to the venv exe); Linux/macOS use the venv binary
-            # at $STUDIO_HOME/unsloth_studio/bin/unsloth.
+            # Windows shim: $STUDIO_HOME/bin/unsloth.exe; Linux/macOS venv binary:
+            # $STUDIO_HOME/unsloth_studio/bin/unsloth.
             home = Path(home_str).expanduser()
             if sys.platform == "win32":
                 installer_bin = home / "bin" / "unsloth.exe"
@@ -821,11 +804,10 @@ def run_server(
         access_log = False,
         server_header = False,
     )
-    # Colab only: trust X-Forwarded-* from Colab's reverse proxy so the
-    # app sees the real https origin. forwarded_allow_ips="*" is fine in
-    # Colab's single-user sandbox but an unwanted relaxation for a normal
-    # local/standalone Studio, so leave uvicorn's safe defaults
-    # (forwarded headers trusted from loopback only) elsewhere.
+    # Colab only: trust X-Forwarded-* from Colab's reverse proxy so the app sees
+    # the real https origin. forwarded_allow_ips="*" is safe in Colab's
+    # single-user sandbox but too lax for local/standalone, so leave uvicorn's
+    # loopback-only default elsewhere.
     if _IS_COLAB:
         config_kwargs["proxy_headers"] = True
         config_kwargs["forwarded_allow_ips"] = "*"
@@ -833,16 +815,14 @@ def run_server(
     _server = _ReadyServer(config)
     _shutdown_event = Event()
 
-    # Expose the actual bound port so request handlers build loopback
-    # URLs pointing at the real backend, not whatever port a proxy/tunnel
-    # exposed in the request URL. Only publish a concrete port; for
-    # ephemeral binds (port==0) leave it unset so handlers fall back to
-    # the ASGI request scope or request.base_url.
+    # Expose the actual bound port so handlers build loopback URLs at the real
+    # backend, not whatever a proxy/tunnel exposed. For ephemeral binds (port==0)
+    # leave it unset so handlers fall back to the request scope / base_url.
     app.state.server_port = port if port and port > 0 else None
     app.state.llama_parallel_slots = llama_parallel_slots
 
-    # Expose a shutdown callable via app.state before the server accepts
-    # requests so /api/shutdown is ready as soon as readiness publishes.
+    # Expose a shutdown callable before the server accepts requests so
+    # /api/shutdown is ready as soon as readiness publishes.
     def _trigger_shutdown():
         _graceful_shutdown(_server)
         if _shutdown_event is not None:
@@ -850,10 +830,9 @@ def run_server(
 
     app.state.trigger_shutdown = _trigger_shutdown
 
-    # Run server in a daemon thread. Use explicit new_event_loop() +
-    # run_until_complete() rather than asyncio.run() so nest_asyncio's
-    # global patches to asyncio.run don't interfere when called from a
-    # thread while Colab/IPython already runs a loop on the main thread.
+    # Run server in a daemon thread with explicit new_event_loop() +
+    # run_until_complete() (not asyncio.run) so nest_asyncio's patches don't
+    # interfere when Colab/IPython already runs a loop on the main thread.
     def _run():
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
@@ -870,9 +849,8 @@ def run_server(
     thread = Thread(target = _run, daemon = True)
     thread.start()
 
-    # Wait until uvicorn finishes lifespan startup and binds sockets, or
-    # until the server exits/fails before startup. No correctness
-    # deadline: a slow but live startup should remain in progress.
+    # Wait until uvicorn finishes lifespan startup and binds sockets, or until it
+    # exits/fails first. No deadline: a slow but live startup stays in progress.
     try:
         while not ready_event.is_set():
             if startup_failed.is_set() or not thread.is_alive():
@@ -892,8 +870,7 @@ def run_server(
 
     atexit.register(_remove_pid_file)
 
-    # Output port for Tauri to parse in api-only mode. Emit only after
-    # uvicorn sockets are bound and FastAPI startup completed.
+    # Output port for Tauri (api-only), only after sockets bind and startup done.
     if api_only:
         print(f"TAURI_PORT={port}", flush = True)
 
@@ -935,9 +912,8 @@ if __name__ == "__main__":
         action = "store_true",
         help = "API server only, no frontend (for Tauri)",
     )
-    # Mirror unsloth_cli/commands/studio.py's _PARALLEL_*. Default 1
-    # applies to direct backend launches only; `unsloth studio run`
-    # always passes its own value (4) explicitly.
+    # Mirror unsloth_cli/commands/studio.py's _PARALLEL_*. Default 1 is for direct
+    # backend launches; `unsloth studio run` always passes its own value (4).
     _PARALLEL_MIN = 1
     _PARALLEL_MAX = 64
     _PARALLEL_DEFAULT_PLAIN = 1
@@ -991,9 +967,8 @@ if __name__ == "__main__":
     if hasattr(signal, "SIGBREAK"):
         signal.signal(signal.SIGBREAK, _signal_handler)
 
-    # Keep running until shutdown signal.
-    # NOTE: Event.wait() without a timeout blocks at the C level on Linux,
-    # preventing Python from delivering SIGINT (Ctrl+C). A short timeout
-    # in a loop lets the interpreter process pending signals.
+    # Keep running until shutdown signal. Event.wait() without a timeout blocks at
+    # the C level on Linux, preventing SIGINT delivery; a short timeout in a loop
+    # lets the interpreter process pending signals.
     while not _shutdown_event.is_set():
         _shutdown_event.wait(timeout = 1)
diff --git a/studio/backend/startup_banner.py b/studio/backend/startup_banner.py
index 08ceae1b59..7bfca61b73 100644
--- a/studio/backend/startup_banner.py
+++ b/studio/backend/startup_banner.py
@@ -34,7 +34,7 @@ def print_port_in_use_notice(original_port: int, new_port: int) -> None:
 
 
 def print_studio_stop_hint() -> None:
-    """Print the trailing stop hint + closing divider. Separate from the
+    """Print the trailing stop hint + closing divider, separate from the
     banner so callers can interleave content (e.g. a reachability check)."""
     use_color = stdout_supports_color()
     dim = "\033[38;5;245m"
diff --git a/studio/backend/storage/mcp_servers_db.py b/studio/backend/storage/mcp_servers_db.py
index bbd7186ed4..6482bae140 100644
--- a/studio/backend/storage/mcp_servers_db.py
+++ b/studio/backend/storage/mcp_servers_db.py
@@ -28,7 +28,7 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    # use_oauth added after the first release; backfill for pre-existing DBs.
+    # Backfill use_oauth for pre-existing DBs.
     cols = {r["name"] for r in conn.execute("PRAGMA table_info(mcp_servers)").fetchall()}
     if "use_oauth" not in cols:
         conn.execute("ALTER TABLE mcp_servers ADD COLUMN use_oauth INTEGER NOT NULL DEFAULT 0")
diff --git a/studio/backend/storage/providers_db.py b/studio/backend/storage/providers_db.py
index e58133090d..07165cbe70 100644
--- a/studio/backend/storage/providers_db.py
+++ b/studio/backend/storage/providers_db.py
@@ -1,14 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-SQLite storage for external LLM provider configurations.
+"""SQLite storage for external LLM provider configurations.
 
-Same pattern as studio_db.py: module-level functions, raw sqlite3, WAL
-mode, per-function connections.
-
-NOTE: API keys are NOT stored here. They live only in the browser
-(localStorage) and are sent encrypted per-request.
+Same pattern as studio_db.py (module-level functions, raw sqlite3, WAL,
+per-function connections). API keys are NOT stored here: they live only in
+the browser (localStorage) and are sent encrypted per-request.
 """
 
 import logging
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index d3900387d4..a9b17fc7f5 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -1,13 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-SQLite storage for training run history and metrics.
+"""SQLite storage for training run history and metrics.
 
-Same pattern as auth/storage.py — module-level functions, raw sqlite3,
-per-function connections. Enhancements over auth:
-  - WAL mode for concurrent read/write access
-  - PRAGMA foreign_keys = ON for CASCADE deletes
+Like auth/storage.py (module-level functions, raw sqlite3, per-function
+connections) plus WAL mode and PRAGMA foreign_keys = ON for CASCADE deletes.
 """
 
 import json
@@ -34,8 +31,7 @@ def _denied_path_prefixes() -> list[str]:
     if system == "Linux":
         return ["/proc", "/sys", "/dev", "/etc", "/boot", "/run"]
     if system == "Darwin":
-        # realpath() resolves /etc -> /private/etc, /tmp -> /private/tmp on
-        # macOS, so include the /private variants to avoid bypasses.
+        # macOS realpath() resolves /etc -> /private/etc etc; include /private variants.
         return [
             "/System",
             "/Library",
@@ -174,9 +170,8 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         """
     )
     conn.execute("CREATE INDEX IF NOT EXISTS idx_metrics_run_id ON training_metrics(run_id)")
-    # COLLATE NOCASE on Windows so C:\Models and c:\models dedup via the
-    # UNIQUE constraint. On Linux/macOS (case-sensitive FS) keep the default
-    # BINARY collation so /Models and /models stay distinct.
+    # Windows: COLLATE NOCASE so C:\Models and c:\models dedup. Elsewhere keep
+    # case-sensitive BINARY so /Models and /models stay distinct.
     collation = "COLLATE NOCASE" if platform.system() == "Windows" else ""
     conn.execute(
         f"""
@@ -287,14 +282,9 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         )
         """
     )
-    # Server-side import ledger so a studio.db wipe re-triggers the legacy
-    # Dexie import. The old boolean localStorage sentinel
-    # (`unsloth_chat_legacy_imported_to_studio_db`) was non-recoverable: if
-    # studio.db is recreated while the browser keeps the flag, legacy Dexie
-    # threads are silently hidden from the sidebar. The ledger lives inside
-    # studio.db so it disappears with the data it tracks -- the recovery the
-    # boolean lacked. Keyed by legacy thread id; per-thread suffices because
-    # Dexie is read-only after this PR (a thread's message set doesn't grow).
+    # Import ledger inside studio.db (vs. a localStorage boolean) so a db wipe
+    # re-triggers the legacy Dexie import instead of silently hiding threads.
+    # Keyed by legacy thread id; Dexie is read-only so per-thread suffices.
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS chat_legacy_imports (
@@ -700,9 +690,8 @@ def add_scan_folder(path: str) -> dict:
     if not os.access(normalized, os.R_OK | os.X_OK):
         raise ValueError("Path is not readable")
 
-    # On Windows, normcase for the denylist comparison but store the
-    # original-cased path so downstream consumers see the native drive-letter
-    # casing the user expects (e.g. C:\Models, not c:\models).
+    # Windows: normcase for the denylist check but store original casing
+    # so consumers see the native drive-letter casing (e.g. C:\Models).
     is_win = platform.system() == "Windows"
     check = os.path.normcase(normalized) if is_win else normalized
     for prefix in _denied_path_prefixes():
@@ -712,8 +701,7 @@ def add_scan_folder(path: str) -> dict:
     conn = get_connection()
     try:
         now = datetime.now(timezone.utc).isoformat()
-        # On Windows, case-insensitive lookup so C:\Models and c:\models dedup
-        # while preserving the originally-stored casing.
+        # Windows: case-insensitive lookup so C:\Models and c:\models dedup.
         if is_win:
             existing = conn.execute(
                 "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE",
@@ -733,9 +721,8 @@ def add_scan_folder(path: str) -> dict:
             )
             conn.commit()
         except sqlite3.IntegrityError:
-            pass  # duplicate -- fall through to SELECT
-        # Same collation as the pre-check so we find the row even when a
-        # concurrent writer stored it with different casing (Windows).
+            pass  # duplicate; fall through to SELECT
+        # Same collation as the pre-check to catch concurrent writes (Windows).
         fallback_sql = (
             "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE"
             if is_win
@@ -1454,11 +1441,7 @@ def upsert_chat_settings_merge(updates: dict[str, Any]) -> dict[str, Any]:
 
 
 def list_chat_legacy_imports() -> list[str]:
-    """Return the legacy_thread_id of every thread already imported.
-
-    Cheap: scans one small PK-only table. The frontend puts the result in a
-    Set before walking Dexie, so the diff is O(|Dexie|).
-    """
+    """Return the legacy_thread_id of every thread already imported."""
     conn = get_connection()
     try:
         rows = conn.execute("SELECT legacy_thread_id FROM chat_legacy_imports").fetchall()
@@ -1470,14 +1453,9 @@ def list_chat_legacy_imports() -> list[str]:
 def upsert_chat_legacy_imports(legacy_thread_ids: list[str]) -> tuple[int, int]:
     """Mark each given legacy thread id as imported. Idempotent.
 
-    Returns (accepted, inserted):
-      - accepted: count of non-empty deduped input ids
-      - inserted: count of rows that were actually new (not already in ledger)
-
-    ON CONFLICT DO NOTHING keeps the existing imported_at when an id is
-    recorded twice. INSERT...RETURNING reports only newly-inserted rows, so
-    callers distinguish first-time imports from idempotent re-runs without an
-    extra SELECT.
+    Returns (accepted, inserted): count of deduped non-empty input ids, and
+    count of rows actually new. RETURNING lets callers tell first-time imports
+    from idempotent re-runs without an extra SELECT.
     """
     ids = list(dict.fromkeys(tid for tid in legacy_thread_ids if tid))
     if not ids:
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index d903e04514..a9fc185536 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -1,30 +1,14 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Shared pytest configuration for the backend test suite.
+"""Shared pytest configuration for the backend test suite.
 
-Responsibilities:
-1. Put the backend root on sys.path so `from models.inference import ...`
-   (and similar flat imports) resolve in test modules — mirrors how the
-   app is launched.
-2. Provide a hybrid ``studio_server`` session fixture for end-to-end tests
-   (see ``test_studio_api.py``), supporting two invocation modes:
-
-   a. **External server.** If ``UNSLOTH_E2E_BASE_URL`` is set, tests point
-      at an already-running Studio instance (``UNSLOTH_E2E_API_KEY`` must
-      also be set). Fast-iteration mode: start the server once with
-      ``unsloth studio run ...``, then run pytest against it many times with
-      no per-run GGUF load cost.
-
-   b. **Fixture-managed server.** Otherwise the fixture launches a fresh
-      server via ``_start_server`` and tears it down at session end. One-shot
-      mode for CI or a clean-slate verification run.
-
-   The model / variant for mode (b) come from ``--unsloth-model`` /
-   ``--unsloth-gguf-variant`` pytest options, then ``UNSLOTH_E2E_MODEL`` /
-   ``UNSLOTH_E2E_VARIANT`` env vars, then the defaults in
-   ``test_studio_api.py``.
+Puts the backend root on sys.path (mirrors app launch) and provides a hybrid
+``studio_server`` session fixture for end-to-end tests with two modes:
+external server (``UNSLOTH_E2E_BASE_URL``/``UNSLOTH_E2E_API_KEY``) for fast
+iteration, or a fixture-managed server started/torn down per session for CI.
+Model/variant for the managed mode resolve from ``--unsloth-model`` /
+``--unsloth-gguf-variant``, then env vars, then ``test_studio_api.py`` defaults.
 """
 
 import os
@@ -33,13 +17,13 @@ from pathlib import Path
 
 import pytest
 
-# Add backend root to sys.path (mirrors how the app itself is launched)
+# Add backend root to sys.path (mirrors app launch)
 _backend_root = Path(__file__).resolve().parent.parent
 if str(_backend_root) not in sys.path:
     sys.path.insert(0, str(_backend_root))
 
 
-# ── Pytest CLI options ───────────────────────────────────────────────
+# Pytest CLI options
 
 
 def pytest_addoption(parser):
@@ -71,25 +55,16 @@ def pytest_addoption(parser):
     )
 
 
-# ── E2E server fixtures ──────────────────────────────────────────────
+# E2E server fixtures
 
 
 @pytest.fixture(scope = "session")
 def studio_server(request):
     """Yield ``(base_url, api_key)`` for e2e tests.
 
-    Resolution order:
-
-    1. If ``UNSLOTH_E2E_BASE_URL`` is set → point at that server, requiring
-       ``UNSLOTH_E2E_API_KEY`` alongside (skip if missing).
-    2. Otherwise → start a fresh ``unsloth studio run`` subprocess via the
-       ``_start_server`` helper in ``test_studio_api.py`` and tear it down on
-       session teardown.
-
-    Session-scoped so the expensive GGUF load happens at most once per pytest
-    invocation. Lazy — tests that don't request the fixture (e.g. the unit
-    tests in ``test_anthropic_messages.py`` or ``test_help_output``) don't
-    trigger server startup.
+    Uses ``UNSLOTH_E2E_BASE_URL`` (requires ``UNSLOTH_E2E_API_KEY``) if set,
+    else starts/tears down a fresh server via ``_start_server``. Session-scoped
+    and lazy so the GGUF load happens at most once and only when requested.
     """
     external_url = os.environ.get("UNSLOTH_E2E_BASE_URL")
     if external_url:
@@ -103,9 +78,7 @@ def studio_server(request):
         yield external_url, api_key
         return
 
-    # Lazy import: pytest has already loaded test_studio_api into sys.modules
-    # by the time any test requests this fixture, so this is a cache hit, not
-    # a re-execution.
+    # Lazy import; pytest has already loaded test_studio_api, so this is a cache hit.
     import test_studio_api as _e2e
 
     model = (
diff --git a/studio/backend/tests/test_anthropic_cache_ttl.py b/studio/backend/tests/test_anthropic_cache_ttl.py
index 895c598546..d39d0e9384 100644
--- a/studio/backend/tests/test_anthropic_cache_ttl.py
+++ b/studio/backend/tests/test_anthropic_cache_ttl.py
@@ -3,14 +3,9 @@
 
 """Unit tests for prompt_cache_ttl threading on the Anthropic path.
 
-Anthropic accepts an optional ``ttl`` on each ``cache_control`` marker:
-default is the 5-minute ephemeral pool; ``ttl:"1h"`` writes into the
-1-hour pool. The 1h pool fits conversations spanning short bursts more
-than 5 minutes apart -- 1h writes bill at 2x base input vs 1.25x for 5m,
-but reads stay at 0.1x for both, so one extra read pays the premium.
-
-These tests pin the outbound body shape: prompt_cache_ttl="1h" puts
-``ttl:"1h"`` on both markers; default omits the field (5m pool); garbage
+Anthropic's ``cache_control`` marker takes an optional ``ttl``: default 5m
+pool, ``ttl:"1h"`` the 1h pool. These tests pin the outbound body shape:
+"1h" puts ``ttl:"1h"`` on both markers; default omits the field; garbage
 values are silently dropped.
 """
 
@@ -127,11 +122,8 @@ def test_1h_ttl_writes_into_1h_pool(monkeypatch):
 
 
 def test_1h_ttl_does_not_send_extended_cache_ttl_beta_header(monkeypatch):
-    # The `extended-cache-ttl-2025-04-11` beta header that originally gated
-    # 1h cache TTL is now GA: verified live against api.anthropic.com on
-    # 2026-05-22 -- a request with `cache_control:{type:"ephemeral",
-    # ttl:"1h"}` and NO beta header returns 200 and populates
-    # `ephemeral_1h_input_tokens`. Pin the contract so a regression that
+    # The extended-cache-ttl-2025-04-11 beta header is now GA (verified live
+    # 2026-05-22); 1h TTL works with no beta header. Pin so a regression that
     # re-adds the header surfaces here.
     captured = _capture(monkeypatch, ttl = "1h")
     beta = captured["headers"].get("anthropic-beta", "")
@@ -153,8 +145,7 @@ def test_unknown_ttl_silently_dropped(monkeypatch, bogus):
     ccs = _cache_controls(captured["body"])
     assert len(ccs) == 2, ccs
     for cc in ccs:
-        # Bogus TTLs must NOT round-trip; marker stays at the default
-        # (no `ttl` key = 5m pool upstream).
+        # Bogus TTLs must not round-trip; marker stays at default (no ttl = 5m).
         assert cc == {"type": "ephemeral"}, cc
 
 
diff --git a/studio/backend/tests/test_anthropic_citations.py b/studio/backend/tests/test_anthropic_citations.py
index c6104f2425..25d5f5e886 100644
--- a/studio/backend/tests/test_anthropic_citations.py
+++ b/studio/backend/tests/test_anthropic_citations.py
@@ -126,8 +126,7 @@ def _joined(lines: list[str]) -> str:
 
 
 def test_no_citations_stream_unchanged(monkeypatch):
-    """Plain text streams pass through with no inline markers and no
-    document_citations tool_event."""
+    """Plain text passes through with no inline markers or document_citations."""
     lines = _capture(
         monkeypatch,
         [
diff --git a/studio/backend/tests/test_anthropic_code_execution.py b/studio/backend/tests/test_anthropic_code_execution.py
index cc0fb21deb..22bbb19125 100644
--- a/studio/backend/tests/test_anthropic_code_execution.py
+++ b/studio/backend/tests/test_anthropic_code_execution.py
@@ -1,27 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for Anthropic's server-side `code_execution_20250825` tool
-translation in `_stream_anthropic`.
-
-Covers:
-- Request body: ``enabled_tools=["code_execution"]`` puts ``{"type":
-  "code_execution_20250825", "name": "code_execution"}`` in the outbound
-  ``tools`` and ``code-execution-2025-08-25`` in the ``anthropic-beta``
-  header.
-- Combined: ``["web_search", "code_execution"]`` sends both tool entries;
-  the beta header merges the code-exec flag onto the registry's.
-- SSE: a `bash_code_execution` server_tool_use +
-  `bash_code_execution_tool_result` pair emits one tool_start and one
-  tool_end ``_toolEvent`` chunk with the expected args and result.
-- SSE: a `text_editor_code_execution` create + result emits a tool_start
-  with ``kind="text_editor"`` + parsed args, and tool_end with
-  ``"Created"`` (or ``"Updated"``) per the ``is_file_update`` flag.
-- Error path: a ``bash_code_execution_tool_result_error`` with
-  ``error_code="container_expired"`` renders as ``"Error:
-  container_expired"`` in the tool_end ``result``.
-"""
+"""Tests for Anthropic server-side `code_execution` tool translation in
+`_stream_anthropic`: request body/beta header, combined web_search,
+bash/text_editor SSE tool events, and the container_expired error path."""
 
 import asyncio
 import json
@@ -114,13 +96,11 @@ def test_code_execution_tool_appended_to_request_body(monkeypatch):
 
     body = captured["body"]
     tools = body.get("tools") or []
-    # Opus 4.7 gets the newer date-pinned variant (`_20260120`) with REPL
-    # state persistence + programmatic tool calling.
+    # Opus 4.7 gets the newer date-pinned variant with REPL persistence.
     assert {"type": "code_execution_20260120", "name": "code_execution"} in tools
     # No web_search entry when only code_execution is enabled.
     assert all("web_search" not in (t.get("type") or "") for t in tools)
-    # Beta header still carries the flag; both `_20250825` and `_20260120`
-    # are unlocked by the same header per upstream docs.
+    # Same beta header unlocks both _20250825 and _20260120.
     beta_header = captured["headers"].get("anthropic-beta", "")
     assert "code-execution-2025-08-25" in beta_header
 
@@ -191,11 +171,9 @@ def test_no_code_execution_tool_when_pill_off(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    # Pill off -- neither the legacy nor new code_execution variant may
-    # appear on the wire.
+    # Pill off: no code_execution variant on the wire.
     assert all("code_execution" not in (t.get("type") or "") for t in tools)
-    # Beta header must NOT mention code-execution when the tool is off --
-    # that flag is opt-in only.
+    # Beta header must omit code-execution when the tool is off (opt-in only).
     assert "code-execution-2025-08-25" not in captured["headers"].get("anthropic-beta", "")
 
 
@@ -268,8 +246,7 @@ def test_bash_code_execution_emits_tool_start_and_end(monkeypatch):
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "code_execution"
     assert start["tool_call_id"] == "srvtoolu_1"
-    # `_server_tool: True` marks a provider-side synthetic tool card for
-    # the frontend's history serializer.
+    # `_server_tool: True` marks a provider-side synthetic tool card.
     assert start["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
 
     assert end["type"] == "tool_end"
diff --git a/studio/backend/tests/test_anthropic_compaction.py b/studio/backend/tests/test_anthropic_compaction.py
index 5047a93979..1528eebe8b 100644
--- a/studio/backend/tests/test_anthropic_compaction.py
+++ b/studio/backend/tests/test_anthropic_compaction.py
@@ -3,16 +3,13 @@
 
 """Unit tests for Anthropic server-side context compaction wiring.
 
-Compaction is a beta feature (header ``compact-2026-01-12``) gated to
-Opus 4.6, Opus 4.7, Sonnet 4.6, and Mythos preview. When enabled, Studio
-attaches ``context_management.edits[{type:"compact_20260112",
-trigger:{type:"input_tokens", value:N}}]`` to the outbound body. Minimum
-upstream threshold is 50k tokens; lower values are clamped to 50k so the
-request doesn't 400.
+Compaction is a beta (header ``compact-2026-01-12``) gated to Opus 4.6/4.7,
+Sonnet 4.6, and Mythos preview. When enabled, Studio attaches
+``context_management.edits[{type:"compact_20260112", trigger:{type:"input_tokens",
+value:N}}]``; the 50k-token minimum is clamped up so the request doesn't 400.
 
-These tests pin: body shape per model, the beta header merge with the
-code-execution beta, threshold clamping, and silent no-op on unsupported
-models.
+Pins body shape per model, beta header merge with code-execution, threshold
+clamping, and silent no-op on unsupported models.
 """
 
 import asyncio
@@ -168,9 +165,8 @@ def test_omitted_threshold_no_body_field(monkeypatch):
 
 
 def test_chat_completion_request_accepts_sub_50k_compaction_threshold():
-    # Codex P1 caught that ge=50_000 on the field made FastAPI 422 the
-    # request before the in-helper clamp could fire. The schema must
-    # accept any positive int and let _stream_anthropic clamp upward.
+    # ge=50_000 on the field would 422 before the in-helper clamp fires; the
+    # schema must accept any positive int and let _stream_anthropic clamp up.
     from models.inference import ChatCompletionRequest
 
     req = ChatCompletionRequest.model_validate(
@@ -207,13 +203,10 @@ def test_chat_completion_request_accepts_sub_50k_compaction_threshold():
 
 
 def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch, capsys):
-    # When Anthropic compacts mid-stream, the SSE message_delta usage
-    # carries `iterations: [{type:"compaction", ...}, ...]`. The top-level
-    # input_tokens / output_tokens only cover the `message` iteration, so
-    # compaction totals need to be exposed separately. The stream helper
-    # folds them into last_usage as `compaction_input_tokens` /
-    # `compaction_output_tokens` and surfaces them in the closing summary
-    # log so an operator can see "did compaction cost us 180k tokens?".
+    # On mid-stream compaction the message_delta usage carries
+    # `iterations: [{type:"compaction", ...}, ...]`. Top-level tokens only cover
+    # the `message` iteration, so the helper folds compaction totals into
+    # last_usage and surfaces them in the closing summary log.
 
     def http_handler(request: httpx.Request) -> httpx.Response:
         body = (
@@ -256,8 +249,7 @@ def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch
 
     _drive(run())
 
-    # structlog renders the closing summary via the stdlib bridge onto
-    # stdout. Capture and check the rendered line.
+    # structlog renders the closing summary onto stdout; check the rendered line.
     out = capsys.readouterr().out
     summary = next(
         (line for line in out.splitlines() if "Anthropic stream complete" in line),
@@ -268,9 +260,8 @@ def test_message_delta_iterations_array_aggregates_compaction_tokens(monkeypatch
 
 
 def test_message_delta_no_iterations_leaves_compaction_keys_unset(monkeypatch, capsys):
-    # Re-applying a previous compaction block does NOT emit a fresh
-    # iterations array. The helper must not invent compaction keys then
-    # (would otherwise double-bill).
+    # Re-applying a prior compaction block emits no fresh iterations array;
+    # the helper must not invent compaction keys (would double-bill).
     def http_handler(request: httpx.Request) -> httpx.Response:
         body = (
             b"event: message_delta\n"
@@ -329,17 +320,14 @@ def _async_collect(agen):
 
 
 def test_compaction_block_emitted_as_tool_event(monkeypatch):
-    # Codex P1: once context_management is enabled and Anthropic compacts
-    # during a turn, the response carries a `{type:"compaction",
-    # content:"<summary>"}` block. The translator must surface it so the
-    # chat-adapter persists it onto the assistant message; otherwise the
-    # next turn loses the state and Anthropic re-compacts from scratch.
+    # When Anthropic compacts during a turn, the response carries a
+    # `{type:"compaction", content:"<summary>"}` block. The translator must surface
+    # it so the chat-adapter persists it; else the next turn loses state and re-compacts.
 
     def http_handler(request: httpx.Request) -> httpx.Response:
-        # Anthropic ships compaction blocks as a content_block_start with
-        # `type:"compaction"`, then includes the summary on that start
-        # event AND/OR streams it via text_delta events on the same block
-        # index. Test the streamed-delta path since it's the harder case.
+        # Compaction blocks arrive as a content_block_start with type:"compaction",
+        # with the summary on the start event AND/OR streamed via text_delta on the
+        # same index. Test the streamed-delta path (harder case).
         body = (
             b"event: message_start\n"
             b'data: {"type":"message_start","message":{"usage":{}}}\n\n'
@@ -406,9 +394,7 @@ def test_compaction_block_emitted_as_tool_event(monkeypatch):
             parsed = json.loads(raw)
         except json.JSONDecodeError:
             continue
-        # tool_event payloads ride inside chat.completion.chunk.choices[0].delta.content
-        # as a JSON-encoded string. Simpler: look for the marker substring
-        # anywhere in the chunk.
+        # tool_event payloads ride inside the chunk as JSON; just match the marker.
         if "compaction_block" in raw:
             events.append(raw)
     assert events, f"no compaction_block tool event found in {lines}"
@@ -441,10 +427,8 @@ def test_compaction_block_emitted_as_tool_event(monkeypatch):
 
 
 def test_compaction_block_round_trips_through_outbound_messages(monkeypatch):
-    # Once the prior turn persisted a compaction block onto the assistant
-    # message, the next turn's outbound body must forward the
-    # {type:"compaction", content:"..."} block to Anthropic verbatim so the
-    # API recognises the existing state.
+    # The next turn's outbound body must forward a persisted
+    # {type:"compaction", content:"..."} block verbatim so the API recognises the state.
     captured: dict = {}
 
     def http_handler(request: httpx.Request) -> httpx.Response:
@@ -502,9 +486,7 @@ def test_compaction_block_round_trips_through_outbound_messages(monkeypatch):
 
 
 def test_compaction_content_part_accepted_by_chat_message_schema():
-    # Without this Pydantic Tag the discriminated Union would 422 the
-    # request at parse time and the round-trip would never reach the
-    # translator.
+    # Without the Pydantic Tag the discriminated Union would 422 at parse time.
     from models.inference import ChatMessage
 
     msg = ChatMessage.model_validate(
@@ -523,10 +505,8 @@ def test_compaction_content_part_accepted_by_chat_message_schema():
 
 
 def test_build_external_messages_passes_compaction_for_anthropic_only():
-    # Compaction is an Anthropic-only synthetic content part. The builder
-    # MUST gate it on provider_type=="anthropic"; every other provider
-    # would 400 on the unknown content type via generic /chat/completions
-    # passthrough (Codex P1 follow-up).
+    # Compaction is Anthropic-only; the builder must gate it on
+    # provider_type=="anthropic" since others 400 on the unknown content type.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -549,11 +529,9 @@ def test_build_external_messages_passes_compaction_for_anthropic_only():
 
 
 def test_build_external_messages_strips_compaction_for_non_anthropic_providers():
-    # Provider switch (or reused history) hands compaction blocks to a
-    # non-Anthropic provider, landing on generic /chat/completions
-    # passthrough where the unknown content type fails the upstream
-    # validator. Builder must strip the part for every non-anthropic
-    # provider, including OpenAI/DeepSeek/Mistral/Gemini/Kimi/OpenRouter.
+    # A provider switch or reused history can hand compaction blocks to a
+    # non-Anthropic provider whose validator rejects the unknown type, so the
+    # builder must strip the part for every non-anthropic provider.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -579,9 +557,7 @@ def test_build_external_messages_strips_compaction_for_non_anthropic_providers()
 
 
 def test_build_external_messages_strips_compaction_when_provider_type_unknown():
-    # Defensive: if provider_type is None (legacy path) the part must
-    # also be stripped -- forwarding to an unknown destination is
-    # never safe.
+    # Defensive: provider_type=None (legacy path) must also strip the part.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
@@ -603,9 +579,8 @@ def test_build_external_messages_strips_compaction_when_provider_type_unknown():
 
 
 def test_build_external_messages_non_vision_anthropic_keeps_compaction():
-    # Defensive: even though compaction-capable Anthropic models all
-    # currently report supports_vision=True, gate the non-vision branch
-    # by provider_type too so future config changes don't drop it.
+    # Defensive: gate the non-vision branch by provider_type too, so future
+    # config changes don't drop compaction for Anthropic.
     from models.inference import ChatMessage
     from routes.inference import _build_external_messages
 
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index c55ccbaaef..77b0b21212 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -1,10 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
-"""
-Tests for Anthropic Messages API schemas and translation layer.
-No running server or GPU required.
-"""
+"""Tests for Anthropic Messages API schemas and translation layer (no server/GPU)."""
 
 import sys
 import os
diff --git a/studio/backend/tests/test_anthropic_thinking_translation.py b/studio/backend/tests/test_anthropic_thinking_translation.py
index 144de166f2..02c4893735 100644
--- a/studio/backend/tests/test_anthropic_thinking_translation.py
+++ b/studio/backend/tests/test_anthropic_thinking_translation.py
@@ -1,20 +1,16 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for the Anthropic extended-thinking translation in external_provider.
+"""Unit tests for Anthropic extended-thinking translation in external_provider.
 
 Covers:
-- Adaptive-mode request body nests effort under
-  ``output_config: {effort: "<level>"}`` per the Messages API reference (a
-  top-level ``effort`` field 400s with "effort: Extra inputs are not permitted").
-- Streaming SSE: ``content_block_delta`` with ``delta.type == "thinking_delta"``
-  is translated into inline ``<think>...</think>`` chat-completion chunks so the
-  frontend's reasoning-panel pipeline lifts it correctly.
-- The ``<think>`` tag closes when the first ``text_delta`` arrives, on
-  ``content_block_stop``, on ``message_delta``, or on ``message_stop``.
-- Thinking is paired with ``temperature=1`` and no ``top_p`` / ``top_k`` on the
-  wire (Anthropic extended-thinking contract).
+- Adaptive-mode body nests effort under ``output_config: {effort}`` (a
+  top-level ``effort`` field 400s).
+- Streaming ``thinking_delta`` is translated into inline ``<think>...</think>``
+  chunks for the frontend reasoning panel.
+- The ``<think>`` tag closes on the first ``text_delta``, ``content_block_stop``,
+  ``message_delta``, or ``message_stop``.
+- Thinking forces ``temperature=1`` with no ``top_p`` / ``top_k`` (contract).
 """
 
 import asyncio
diff --git a/studio/backend/tests/test_anthropic_tool_versions.py b/studio/backend/tests/test_anthropic_tool_versions.py
index f9ff448f66..fe2da26d73 100644
--- a/studio/backend/tests/test_anthropic_tool_versions.py
+++ b/studio/backend/tests/test_anthropic_tool_versions.py
@@ -1,34 +1,13 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for the per-model Anthropic server-side tool-version dispatch
-helpers in ``core.inference.external_provider``.
+"""Tests for the per-model Anthropic tool-version dispatch helpers in
+``core.inference.external_provider``.
 
-Anthropic ships date-pinned tool versions per model family. The newer
-``_20260209`` web_search / web_fetch and ``_20260120`` code_execution
-variants only run on a subset of models; sending them to an older model
-returns a 400 from upstream, and sending the older ``_20250305`` /
-``_20250910`` / ``_20250825`` variants to a newer model misses dynamic
-filtering and the free-when-paired pricing. The helpers below pick the
-version per model; this test pins the dispatch matrix so future model
-launches keep working without regressing the newer-version path.
-
-Covers:
-- ``_anthropic_web_search_version`` / ``_anthropic_web_fetch_version``
-  pick ``_20260209`` for Opus 4.6+, Opus 4.7, Sonnet 4.6 and fall back
-  to ``_20250305`` / ``_20250910`` for everything else (4.5 family,
-  Haiku 4.5, 4.1, 4.0).
-- ``_anthropic_code_execution_version`` picks ``_20260120`` for the
-  Opus 4.5+ / Sonnet 4.5+ / Opus 4.7 / Sonnet 4.6 family and falls back
-  to ``_20250825`` everywhere else (Haiku 4.5, 4.1, 4.0).
-- ``_stream_anthropic`` body integration: with ``enabled_tools=
-  ["web_search", "code_execution"]`` on Opus 4.7, the outbound body
-  carries the newer pinned versions; the same payload on Haiku 4.5 falls
-  back to the legacy versions.
-- The ``anthropic-beta: code-execution-2025-08-25`` header is sent
-  unchanged for both code-execution variants (no header rev needed).
-"""
+Anthropic ships date-pinned tool versions per model family; sending the
+wrong-dated variant to a model 400s upstream. Pins the dispatch matrix for
+web_search/web_fetch/code_execution helpers, the ``_stream_anthropic`` body
+integration, and the unchanged code-execution beta header."""
 
 import asyncio
 import json
@@ -164,9 +143,7 @@ def test_outbound_body_uses_new_versions_on_opus_4_7(monkeypatch):
     assert "code_execution_20260120" in tool_types
     assert "web_search_20250305" not in tool_types
     assert "code_execution_20250825" not in tool_types
-    # Beta header for code execution stays on the existing flag for both
-    # _20250825 and _20260120; the API gates the feature by one header, not
-    # the date.
+    # One beta header gates both _20250825 and _20260120.
     assert "code-execution-2025-08-25" in captured["headers"].get("anthropic-beta", "")
 
 
diff --git a/studio/backend/tests/test_anthropic_web_fetch.py b/studio/backend/tests/test_anthropic_web_fetch.py
index 542048ebd4..bf24175256 100644
--- a/studio/backend/tests/test_anthropic_web_fetch.py
+++ b/studio/backend/tests/test_anthropic_web_fetch.py
@@ -369,12 +369,10 @@ def _finish_reasons(lines: list[str]) -> list:
 
 
 def test_pause_turn_does_not_emit_finish_reason_chunk(monkeypatch):
-    # Anthropic emits `pause_turn` when a long server-tool turn
-    # (typically web_search / web_fetch) pauses and resumes on the next
-    # request. Mapping it to finish_reason="stop" makes the
-    # OpenAI-formatted client truncate the assistant message. The adapter
-    # must skip the chunk so the stream ends cleanly with [DONE] and no
-    # terminal finish_reason.
+    # Anthropic emits `pause_turn` when a long server-tool turn pauses and
+    # resumes next request. Mapping it to finish_reason="stop" truncates the
+    # OpenAI client's message, so the adapter must skip the chunk and end
+    # cleanly with [DONE] and no terminal finish_reason.
     sse_events = [
         {"type": "message_start", "message": {"usage": {}}},
         {
@@ -488,11 +486,9 @@ def test_refusal_maps_to_content_filter(monkeypatch):
 
 
 def test_web_fetch_titleless_document_falls_back_to_url(monkeypatch):
-    # Anthropic may omit `document.title` when the HTML has nothing
-    # usable. Without a fallback the formatter emits `URL: ...\nSnippet:
-    # ...` only, and the frontend's parseSourcesFromResult skips entries
-    # lacking a `Title:` line, so the source pill disappears. Verify the
-    # formatter mirrors web_search and falls back to the URL.
+    # Anthropic may omit `document.title`. Without a fallback the formatter
+    # emits no `Title:` line, and the frontend's parseSourcesFromResult drops
+    # those entries (source pill disappears). Verify it falls back to the URL.
     sse_events = [
         {"type": "message_start", "message": {"usage": {}}},
         {
diff --git a/studio/backend/tests/test_cache_case_resolution.py b/studio/backend/tests/test_cache_case_resolution.py
index 50340bda63..22e961891e 100644
--- a/studio/backend/tests/test_cache_case_resolution.py
+++ b/studio/backend/tests/test_cache_case_resolution.py
@@ -5,8 +5,7 @@ from pathlib import Path
 import sys
 import types
 
-# Keep this test runnable in lightweight environments where optional logging
-# deps are not installed.
+# Stub structlog so this test runs where the optional dep is absent.
 if "structlog" not in sys.modules:
 
     class _DummyLogger:
diff --git a/studio/backend/tests/test_cached_gguf_routes.py b/studio/backend/tests/test_cached_gguf_routes.py
index 0274d5b4da..20aa37a2b4 100644
--- a/studio/backend/tests/test_cached_gguf_routes.py
+++ b/studio/backend/tests/test_cached_gguf_routes.py
@@ -7,8 +7,7 @@ import types
 from pathlib import Path
 from types import SimpleNamespace
 
-# Keep this test runnable in lightweight environments without optional
-# logging deps.
+# Keep this test runnable without optional logging deps.
 if "structlog" not in sys.modules:
 
     class _DummyLogger:
@@ -211,8 +210,7 @@ def test_list_cached_models_skips_non_suffix_repo_when_gguf_files_exist(monkeypa
 
 
 def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(monkeypatch, tmp_path):
-    """Mirror of the _skips_ test: the mixed repo should still surface in
-    cached-gguf so the picker shows it as a GGUF download."""
+    """Mixed repo still surfaces in cached-gguf as a GGUF download."""
     mixed = _repo(
         "Org/MixedRepo",
         [
@@ -240,9 +238,8 @@ def test_list_cached_gguf_includes_mixed_repo_with_gguf_and_safetensors(monkeypa
 
 
 def test_list_cached_gguf_handles_none_size_on_disk(monkeypatch, tmp_path):
-    """A partial/interrupted GGUF download has ``size_on_disk = None``. The
-    route must treat unknown bytes as zero instead of raising TypeError from
-    ``sum()`` and wiping the whole response."""
+    """``size_on_disk = None`` (partial download) is treated as zero, not a
+    TypeError from ``sum()`` that wipes the response."""
     partial = _repo(
         "Org/PartialDownload",
         [_file("Q4_K_M.gguf", None), _file("Q6_K.gguf", 5_000)],
@@ -267,8 +264,7 @@ def test_list_cached_gguf_handles_none_size_on_disk(monkeypatch, tmp_path):
 
 
 def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(monkeypatch, tmp_path):
-    """One repo raising during classification must not poison the response
-    for the other repos in the scan."""
+    """One repo raising during classification must not poison the response."""
 
     class _ExplodingRepo:
         repo_id = "Org/Broken"
@@ -303,9 +299,8 @@ def test_list_cached_gguf_skips_malformed_repo_without_wiping_response(monkeypat
 
 
 def test_list_cached_gguf_skips_repo_with_only_mmproj_gguf(monkeypatch, tmp_path):
-    """A repo whose only ``.gguf`` artifact is an mmproj vision adapter must
-    not be classified as a GGUF repo: the variant selector filters mmproj
-    out and the picker would otherwise show zero variants."""
+    """A repo whose only ``.gguf`` is an mmproj vision adapter is not a GGUF
+    repo: mmproj is filtered out, leaving zero variants."""
     mmproj_only = _repo(
         "Org/MmprojOnly",
         [
@@ -327,9 +322,8 @@ def test_list_cached_gguf_skips_repo_with_only_mmproj_gguf(monkeypatch, tmp_path
 
 
 def test_list_cached_models_includes_repo_with_only_mmproj_gguf(monkeypatch, tmp_path):
-    """Mirror of the cached-gguf skip: a safetensors repo with an auxiliary
-    mmproj vision adapter must still surface in cached-models so the user
-    can load it as a normal model."""
+    """A safetensors repo with an auxiliary mmproj adapter still surfaces in
+    cached-models as a normal model."""
     mmproj_aux = _repo(
         "Org/MmprojAux",
         [
@@ -351,10 +345,8 @@ def test_list_cached_models_includes_repo_with_only_mmproj_gguf(monkeypatch, tmp
 
 
 def test_list_cached_gguf_includes_vision_repo_with_main_gguf_and_mmproj(monkeypatch, tmp_path):
-    """A vision-capable GGUF repo (main weight + mmproj adapter) is still a
-    GGUF repo. Reported size is the main weight size; mmproj is excluded
-    from GGUF-size accounting since it is filtered out at classification
-    time."""
+    """A vision GGUF repo (main weight + mmproj) is a GGUF repo; reported size
+    is the main weight only, since mmproj is filtered at classification."""
     vision_repo = _repo(
         "Org/VisionGguf",
         [
diff --git a/studio/backend/tests/test_chat_history_storage.py b/studio/backend/tests/test_chat_history_storage.py
index 92cac1a50d..bc74ec172a 100644
--- a/studio/backend/tests/test_chat_history_storage.py
+++ b/studio/backend/tests/test_chat_history_storage.py
@@ -30,8 +30,7 @@ def _reset_studio_db(
 def workspace_projects_home(tmp_path):
     """Projects root outside the platform delete denylist.
 
-    tmp_path resolves under /private/tmp on macOS, which the workspace delete
-    guard refuses by design. Linux/Windows tmp is not denied and is used as-is;
+    macOS tmp_path resolves under /private/tmp, which the delete guard refuses;
     only the denied case falls back to a home subdir.
     """
     candidate = tmp_path / "Projects"
diff --git a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
index 138cda30d4..3799a4f91b 100644
--- a/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
+++ b/studio/backend/tests/test_cleanup_cancelled_checkpoints.py
@@ -18,9 +18,8 @@ if str(_BACKEND_ROOT) not in sys.path:
 def outputs_setup(tmp_path, monkeypatch):
     """Point outputs_root() at a temp dir so cleanup may run on it.
 
-    The training module binds ``outputs_root`` at import time
-    (``from utils.paths import outputs_root``), so patch the symbol on the
-    importer module, not on storage_roots.
+    training binds ``outputs_root`` at import time, so patch the symbol on
+    the importer module, not on storage_roots.
     """
     from core.training import training as training_mod
 
@@ -36,8 +35,8 @@ def _mk_dir(parent: Path, name: str) -> Path:
 
 
 def test_completed_checkpoints_are_preserved(outputs_setup):
-    """The big regression: before this fix, every completed checkpoint-N/
-    was rmtree'd on Cancel, destroying resume points."""
+    """Regression: completed checkpoint-N/ used to be rmtree'd on Cancel,
+    destroying resume points."""
     from core.training.training import _cleanup_cancelled_checkpoints
 
     out = outputs_setup / "run-1"
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index 9d80c718cb..e7022ee435 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -293,9 +293,8 @@ def test_desktop_session_uses_real_admin_identity_for_api_keys():
 
 
 def test_local_recipe_token_authenticates_as_admin_for_desktop_user(loaded_local_model):
-    # _inject_local_providers mints an internal sk-unsloth-* API key (not
-    # a forwarded JWT). The unified API-key path validates as the real
-    # admin user whether the incoming session was desktop or web.
+    # _inject_local_providers mints an internal sk-unsloth-* API key (not a
+    # forwarded JWT) that validates as admin whether the session was desktop or web.
     from auth.authentication import create_access_token, get_current_subject
 
     seed_user(must_change_password = True)
@@ -318,8 +317,7 @@ def test_local_recipe_token_authenticates_as_admin_for_desktop_user(loaded_local
 
 
 def test_local_recipe_token_authenticates_as_admin_for_web_user(loaded_local_model):
-    # Mirror of the desktop variant: API-key issuance is identical for
-    # web and desktop tokens; get_current_subject works the same.
+    # Mirror of the desktop variant: API-key issuance is identical for web/desktop tokens.
     from auth.authentication import create_access_token, get_current_subject
 
     seed_user(must_change_password = False)
diff --git a/studio/backend/tests/test_export_log_cursor.py b/studio/backend/tests/test_export_log_cursor.py
index 25f276b0f5..5b614ab9c8 100644
--- a/studio/backend/tests/test_export_log_cursor.py
+++ b/studio/backend/tests/test_export_log_cursor.py
@@ -4,21 +4,15 @@
 """
 Regression tests for the export log ring-buffer cursor semantics.
 
-Context: the live export log SSE stream has a race where the frontend opens
-the SSE connection AFTER the POST that starts the export. Lines the worker
-emits in the gap between POST and SSE connect get buffered with seqs 1..k,
-and the SSE default cursor `get_current_log_seq()` returns k -- so lines
-1..k are forever unreachable to that client.
+Race: the frontend opens the SSE connection AFTER the POST that starts the
+export, so lines emitted in the gap (seqs 1..k) are unreachable when the SSE
+default cursor `get_current_log_seq()` returns k.
 
-Fix: `clear_logs()` snapshots the pre-run seq into `_run_start_seq` (exposed
-via `get_run_start_seq()`), and `routes/export.py` defaults the SSE cursor
-to that snapshot instead of the current seq. Every line appended during the
-run has seq strictly greater than the snapshot, so the client sees the full
-run regardless of when it connects.
+Fix: `clear_logs()` snapshots the pre-run seq into `_run_start_seq` (via
+`get_run_start_seq()`), and the SSE cursor defaults to that snapshot, so the
+client sees the full run regardless of connect time.
 
-These tests exercise the orchestrator-side contract only (no subprocess,
-FastAPI, or frontend). The routes-level integration with get_run_start_seq()
-is a one-line edit covered by manual testing and the frontend build.
+These tests exercise the orchestrator contract only (no subprocess/FastAPI).
 """
 
 from __future__ import annotations
@@ -30,14 +24,12 @@ from pathlib import Path
 import pytest
 
 
-# Backend root on sys.path so `from core.export.orchestrator import ...`
-# and friends resolve without the studio app bootstrap.
+# Backend root on sys.path so core.export.orchestrator resolves without bootstrap.
 _BACKEND_DIR = Path(__file__).resolve().parent.parent
 if str(_BACKEND_DIR) not in sys.path:
     sys.path.insert(0, str(_BACKEND_DIR))
 
-# orchestrator.py imports structlog and a few heavy modules at the top. Stub
-# the ones we don't need so the import succeeds without the full studio venv.
+# Stub orchestrator.py's heavy top-level imports so it loads without the venv.
 _loggers_stub = types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
@@ -45,8 +37,7 @@ sys.modules.setdefault("loggers", _loggers_stub)
 # structlog is only a module-level import here; a bare stub suffices.
 sys.modules.setdefault("structlog", types.ModuleType("structlog"))
 
-# utils.paths.outputs_root is only called inside scan_checkpoints, which we
-# don't hit; stub it so orchestrator.py's top-level import resolves.
+# Stub utils.paths so orchestrator.py's top-level import resolves.
 _utils_pkg = types.ModuleType("utils")
 _utils_pkg.__path__ = []  # mark as package
 _utils_paths_stub = types.ModuleType("utils.paths")
@@ -77,14 +68,14 @@ def _append(
 
 
 def test_run_start_seq_is_zero_before_any_logs(orchestrator) -> None:
-    """New orchestrator must report run_start_seq == 0 so a first SSE
-    connection picks up every line from seq 1 onward."""
+    """run_start_seq == 0 on a new orchestrator, so the first SSE picks up
+    every line from seq 1 onward."""
     assert orchestrator.get_run_start_seq() == 0
 
 
 def test_clear_logs_snapshots_current_seq(orchestrator) -> None:
-    """clear_logs() must capture _log_seq BEFORE clearing the buffer, so
-    subsequent runs can anchor their SSE cursor at the snapshot."""
+    """clear_logs() captures _log_seq BEFORE clearing, so the next run can
+    anchor its SSE cursor at the snapshot."""
     _append(orchestrator, "old run line 1")
     _append(orchestrator, "old run line 2")
     _append(orchestrator, "old run line 3")
@@ -102,13 +93,9 @@ def test_clear_logs_snapshots_current_seq(orchestrator) -> None:
 
 
 def test_sse_default_cursor_catches_all_current_run_lines(orchestrator) -> None:
-    """Simulate the POST-then-SSE race: worker emits lines right after
-    clear_logs(), SSE connects several lines later. get_run_start_seq() as
-    the default cursor MUST return every line emitted since clear_logs().
-
-    Pre-fix, the SSE defaulted to get_current_log_seq() at connect time,
-    returning the last-seen seq and missing lines N+1..M.
-    """
+    """POST-then-SSE race: worker emits lines right after clear_logs(), SSE
+    connects later. get_run_start_seq() as the default cursor returns every
+    line since clear_logs() (pre-fix it missed them)."""
     # Previous run leaves some buffered lines.
     _append(orchestrator, "previous run line A")
     _append(orchestrator, "previous run line B")
@@ -136,10 +123,8 @@ def test_sse_default_cursor_catches_all_current_run_lines(orchestrator) -> None:
 
 
 def test_sse_default_cursor_excludes_previous_run(orchestrator) -> None:
-    """After clear_logs(), PREVIOUS-run lines must not leak into the new
-    run's SSE stream. Pre-fix this worked (clear_logs cleared the deque);
-    the fix must preserve it.
-    """
+    """After clear_logs(), previous-run lines must not leak into the new
+    run's SSE stream (the fix must preserve this)."""
     _append(orchestrator, "previous run line 1")
     _append(orchestrator, "previous run line 2")
     _append(orchestrator, "previous run line 3")
@@ -155,9 +140,8 @@ def test_sse_default_cursor_excludes_previous_run(orchestrator) -> None:
 
 
 def test_clear_logs_twice_advances_run_start(orchestrator) -> None:
-    """Back-to-back clear_logs() calls (e.g. cleanup -> load -> export in one
-    dialog session) must each re-anchor run_start at the current seq, so
-    successive runs each start with a fresh low-water mark."""
+    """Back-to-back clear_logs() calls each re-anchor run_start at the current
+    seq, giving successive runs a fresh low-water mark."""
     _append(orchestrator, "run 1 line a")
     _append(orchestrator, "run 1 line b")
 
diff --git a/studio/backend/tests/test_external_provider_usage_chunk.py b/studio/backend/tests/test_external_provider_usage_chunk.py
index f462e1c8e9..ebfd6a8f50 100644
--- a/studio/backend/tests/test_external_provider_usage_chunk.py
+++ b/studio/backend/tests/test_external_provider_usage_chunk.py
@@ -1,27 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for the prompt-cache accounting chunk emitted by the
-external-provider streaming proxy.
+"""Unit tests for the prompt-cache accounting chunk from the external-provider proxy.
 
-The streaming Anthropic + OpenAI Responses paths emit one extra
-``include_usage``-style SSE chunk (``choices: []`` with a populated
-``usage`` block) just before ``[DONE]`` / after the final
-``finish_reason`` chunk, so clients see cache savings without scraping
-the structlog stream.
-
-Covers:
-- Helper alone: shape for Anthropic / OpenAI usage payloads, missing
-  fields treated as 0, all-zero usage suppressed.
-- Anthropic stream: ``message_start.usage`` + ``message_delta.usage``
-  with ``cache_creation_input_tokens`` and ``cache_read_input_tokens``
-  produce the expected usage chunk before ``[DONE]``.
-- OpenAI Responses stream: ``response.completed.usage`` with
-  ``input_tokens_details.cached_tokens`` produces the expected usage
-  chunk after the ``stop`` finish_reason chunk.
-- OpenAI Responses ``response.incomplete`` also emits the chunk so
-  length-truncated turns still report cached tokens.
+The streaming Anthropic + OpenAI Responses paths emit one extra include_usage
+SSE chunk (``choices: []`` with a ``usage`` block) before ``[DONE]`` so clients
+see cache savings. Covers the helper directly plus the Anthropic stream and the
+OpenAI Responses completed/incomplete streams.
 """
 
 import asyncio
diff --git a/studio/backend/tests/test_frontend_resolution.py b/studio/backend/tests/test_frontend_resolution.py
index 7224ee7a04..c3e0524a30 100644
--- a/studio/backend/tests/test_frontend_resolution.py
+++ b/studio/backend/tests/test_frontend_resolution.py
@@ -18,8 +18,8 @@ _REPO_STUDIO_DIR = _RUN_PY.parent.parent  # studio/
 
 
 def _load_helpers_only():
-    """Import just the resolver helpers from run.py, skipping the
-    server-side imports (uvicorn, structlog, etc.)."""
+    """Import just the resolver helpers from run.py, skipping server-side
+    imports (uvicorn, structlog, etc.)."""
     source = _RUN_PY.read_text(encoding = "utf-8")
     tree = ast.parse(source)
     keep = []
diff --git a/studio/backend/tests/test_gguf_reload_inheritance.py b/studio/backend/tests/test_gguf_reload_inheritance.py
index 500bfc2d4c..5d5f3c5a83 100644
--- a/studio/backend/tests/test_gguf_reload_inheritance.py
+++ b/studio/backend/tests/test_gguf_reload_inheritance.py
@@ -3,10 +3,9 @@
 
 """Backend contract for the GGUF reload duplicate-load guard.
 
-``LlamaCppBackend._already_in_target_state`` is the in-process short-circuit
-preventing a serialised duplicate /load from killing the just-spawned
-llama-server. Pins local-file identity, the HF-mode hf_variant fallback, and
-``extra_args`` None-vs-[] inherit semantics so the guard cannot regress.
+``LlamaCppBackend._already_in_target_state`` short-circuits a duplicate /load so
+it cannot kill the just-spawned llama-server. Pins local-file identity, the
+HF-mode hf_variant fallback, and ``extra_args`` None-vs-[] inherit semantics.
 """
 
 from __future__ import annotations
diff --git a/studio/backend/tests/test_gguf_routing.py b/studio/backend/tests/test_gguf_routing.py
index c640218943..8a8bff69aa 100644
--- a/studio/backend/tests/test_gguf_routing.py
+++ b/studio/backend/tests/test_gguf_routing.py
@@ -43,10 +43,9 @@ def test_detects_gguf_file_normally(tmp_path):
 
 def test_detects_gguf_when_stat_raises_oserror(tmp_path):
     """
-    Regression: on Windows both is_file() and exists() call stat() internally.
-    In the brief lock window after llama-server is killed, stat() raises
-    OSError so both return False. detect_gguf_model must still route to
-    llama-server based on the file extension alone.
+    Regression: on Windows is_file()/exists() call stat(), which raises OSError
+    in the brief lock window after llama-server is killed. detect_gguf_model must
+    still route to llama-server by file extension alone.
     """
     gguf = tmp_path / "gpt-oss-20b-MXFP4.gguf"
     gguf.write_bytes(b"")
diff --git a/studio/backend/tests/test_host_defaults.py b/studio/backend/tests/test_host_defaults.py
index c66385721e..5c7129bc65 100644
--- a/studio/backend/tests/test_host_defaults.py
+++ b/studio/backend/tests/test_host_defaults.py
@@ -61,10 +61,8 @@ def _parse_argparse_add_argument_default(source: str, option_name: str):
 def test_run_server_default_host_is_loopback():
     """run_server() 'host' default must be 127.0.0.1, not 0.0.0.0.
 
-    Binding to 0.0.0.0 by default exposes the service on all interfaces,
-    contradicting the "privacy first / 100% local" guarantee. Loopback
-    (127.0.0.1) is the least-permissive default; users who need network
-    access can pass -H 0.0.0.0 explicitly.
+    0.0.0.0 exposes the service on all interfaces; loopback is the
+    least-permissive default. Users needing network access pass -H 0.0.0.0.
     """
     source = _RUN_PY.read_text()
     defaults = _parse_function_param_defaults(source, "run_server")
diff --git a/studio/backend/tests/test_index_bootstrap_origin.py b/studio/backend/tests/test_index_bootstrap_origin.py
index 85b785ee10..b9d7f58867 100644
--- a/studio/backend/tests/test_index_bootstrap_origin.py
+++ b/studio/backend/tests/test_index_bootstrap_origin.py
@@ -2,8 +2,9 @@
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 """Regression coverage for the bootstrap-pw cross-origin leak (PR 5739).
-``_is_same_origin_request`` gates ``_inject_bootstrap`` so the seeded
-admin password only ships to same-origin callers.
+
+``_is_same_origin_request`` gates ``_inject_bootstrap`` so the seeded admin
+password only ships to same-origin callers.
 """
 
 import os
@@ -61,9 +62,7 @@ def test_is_same_origin_request_port_mismatch_is_cross_origin():
 
 
 def test_is_same_origin_request_https_default_port_stripped_on_origin():
-    """RFC 6454 strips default ports on Origin; Starlette netloc may keep
-    ``:443``. Canonicalise both sides so this stays same-origin.
-    """
+    """RFC 6454 strips default ports on Origin; canonicalise both sides so this stays same-origin."""
     from main import _is_same_origin_request
 
     req = _build_request("example.com:443", origin = "https://example.com", scheme = "https")
@@ -109,9 +108,7 @@ def test_is_same_origin_request_null_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_unparseable_origin_is_cross_origin():
-    """Hostless garbage falls to cross-origin; a malformed header
-    must not leak the bootstrap.
-    """
+    """Hostless garbage falls to cross-origin so a malformed header can't leak the bootstrap."""
     from main import _is_same_origin_request
 
     req = _build_request("example.com", origin = "not-a-url")
@@ -119,8 +116,7 @@ def test_is_same_origin_request_unparseable_origin_is_cross_origin():
 
 
 def test_is_same_origin_request_userinfo_in_netloc_ignored():
-    """``user:pass@host:port`` netlocs (RFC 3986) must compare equal to the
-    credentials-less Origin."""
+    """``user:pass@host:port`` netlocs (RFC 3986) must compare equal to the credentials-less Origin."""
     from main import _is_same_origin_request
 
     req = _build_request("user:pass@example.com:80", origin = "http://example.com")
diff --git a/studio/backend/tests/test_inference_model_validation.py b/studio/backend/tests/test_inference_model_validation.py
index dddf5c8052..2427ad35fa 100644
--- a/studio/backend/tests/test_inference_model_validation.py
+++ b/studio/backend/tests/test_inference_model_validation.py
@@ -206,7 +206,7 @@ def test_walkback_skips_explicitly_consumed_tool_call_id():
 
 def test_walkback_handles_malformed_function_string():
     """A tool_call with ``function`` as a string (provider quirk) must not
-    raise; resolution falls back to fallback id selection."""
+    raise; resolution falls back to id selection."""
     req = _req(
         [
             {
diff --git a/studio/backend/tests/test_kv_cache_estimation.py b/studio/backend/tests/test_kv_cache_estimation.py
index cd679b0bf1..cd834b345b 100644
--- a/studio/backend/tests/test_kv_cache_estimation.py
+++ b/studio/backend/tests/test_kv_cache_estimation.py
@@ -19,10 +19,8 @@ from pathlib import Path
 
 import pytest
 
-# ---------------------------------------------------------------------------
 # Stub heavy / unavailable deps before importing the module under test.
 # Same pattern as test_native_context_length.py.
-# ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
@@ -37,10 +35,9 @@ sys.modules.setdefault("loggers", _loggers_stub)
 _structlog_stub = _types.ModuleType("structlog")
 sys.modules.setdefault("structlog", _structlog_stub)
 
-# httpx -- only stub when the real library isn't installed. Stubbing
-# unconditionally shadows ``HTTPError`` / ``Response`` etc. that
-# ``huggingface_hub.errors`` imports at load time, making the transformers
-# introspection tier silently return None in the test process.
+# httpx -- only stub when the real library is missing. Unconditional stubbing
+# shadows HTTPError/Response that huggingface_hub.errors imports at load time,
+# silently breaking the transformers introspection tier.
 try:
     import httpx as _httpx_real  # noqa: F401
 except ImportError:
@@ -76,9 +73,7 @@ except ImportError:
 
 from core.inference.llama_cpp import LlamaCppBackend
 
-# ---------------------------------------------------------------------------
 # Helpers
-# ---------------------------------------------------------------------------
 
 
 def _make_gguf_bytes(arch: str, kv_pairs: dict) -> bytes:
@@ -154,9 +149,7 @@ def _backend_from_gguf(
         os.unlink(path)
 
 
-# ---------------------------------------------------------------------------
 # A. GGUF Parser Tests
-# ---------------------------------------------------------------------------
 
 
 class TestGGUFParserNewFields:
@@ -704,9 +697,7 @@ class TestGGUFParserReset:
         assert b._n_layers == 64
 
 
-# ---------------------------------------------------------------------------
 # B. _can_estimate_kv Gate Tests
-# ---------------------------------------------------------------------------
 
 
 class TestCanEstimateKV:
@@ -764,9 +755,7 @@ class TestCanEstimateKV:
         assert not b._can_estimate_kv()
 
 
-# ---------------------------------------------------------------------------
 # C. Path 1: MLA Estimation
-# ---------------------------------------------------------------------------
 
 
 class TestMLAEstimation:
@@ -835,9 +824,7 @@ class TestMLAEstimation:
         assert result_q4 == int(61 * 1000 * 1 * 576 * 0.5625)
 
 
-# ---------------------------------------------------------------------------
 # D. Path 2: Hybrid Mamba Estimation
-# ---------------------------------------------------------------------------
 
 
 class TestHybridMambaEstimation:
@@ -895,9 +882,7 @@ class TestHybridMambaEstimation:
         assert result == expected
 
 
-# ---------------------------------------------------------------------------
 # E. Path 3: Sliding Window Estimation
-# ---------------------------------------------------------------------------
 
 
 class TestSlidingWindowEstimation:
@@ -993,9 +978,7 @@ class TestSlidingWindowEstimation:
         assert b._estimate_kv_cache_bytes(1000, "f16") == expected
 
 
-# ---------------------------------------------------------------------------
 # F. Path 4: Standard GQA Estimation
-# ---------------------------------------------------------------------------
 
 
 class TestStandardGQAEstimation:
@@ -1039,9 +1022,7 @@ class TestStandardGQAEstimation:
         assert gqa_result > legacy_result  # key_length (128) > head_dim (64)
 
 
-# ---------------------------------------------------------------------------
 # G. Path 5: Legacy Fallback Estimation
-# ---------------------------------------------------------------------------
 
 
 class TestLegacyEstimation:
@@ -1085,9 +1066,7 @@ class TestLegacyEstimation:
         assert b._estimate_kv_cache_bytes(n_ctx, "f16") == old_formula
 
 
-# ---------------------------------------------------------------------------
 # H. Path Priority (selection order)
-# ---------------------------------------------------------------------------
 
 
 class TestPathPriority:
@@ -1182,9 +1161,7 @@ class TestPathPriority:
         assert len(set(values)) == 5, f"Expected 5 distinct values, got {values}"
 
 
-# ---------------------------------------------------------------------------
 # I. KV Cache Quantization
-# ---------------------------------------------------------------------------
 
 
 class TestQuantization:
@@ -1219,9 +1196,7 @@ class TestQuantization:
         assert result == expected
 
 
-# ---------------------------------------------------------------------------
 # J. Edge Cases
-# ---------------------------------------------------------------------------
 
 
 class TestEdgeCases:
@@ -1282,10 +1257,8 @@ class TestEdgeCases:
         assert result == expected
 
 
-# ---------------------------------------------------------------------------
 # J2. Server-flag knobs (--swa-full, --kv-unified/--parallel,
 #     --ctx-checkpoints, --kv-offload)
-# ---------------------------------------------------------------------------
 
 
 class TestServerFlags:
@@ -1563,9 +1536,7 @@ class TestServerFlags:
         assert fitted_full < ctx
 
 
-# ---------------------------------------------------------------------------
 # J2.5. --parallel N memory accounting (per-layer-type scaling rule)
-# ---------------------------------------------------------------------------
 
 
 class TestParallelSWAScaling:
@@ -1772,9 +1743,7 @@ class TestParallelSWAScaling:
             ), f"slots={slots}: got {got_mib} MiB, expected {expected_mib} MiB"
 
 
-# ---------------------------------------------------------------------------
 # J3. shared_kv_layers (Gemma 3n / Gemma 4)
-# ---------------------------------------------------------------------------
 
 
 class TestSharedKVLayers:
@@ -1952,9 +1921,7 @@ class TestSharedKVLayers:
         assert b._shared_kv_layers is None
 
 
-# ---------------------------------------------------------------------------
 # K. Lifecycle Tests
-# ---------------------------------------------------------------------------
 
 
 class TestLifecycle:
diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
index 8fca27dfe1..3443f53a12 100644
--- a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -89,9 +89,7 @@ def _lookup_family(gfx: str) -> str | None:
     return None
 
 
-# ---------------------------------------------------------------------------
 # GPU family mapping
-# ---------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -113,9 +111,7 @@ def test_unknown_gpu_not_in_families():
     assert _lookup_family("gfx999") is None
 
 
-# ---------------------------------------------------------------------------
 # Asset resolution - hits real lemonade GitHub API
-# ---------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -145,11 +141,9 @@ def test_unknown_gpu_falls_through_to_upstream():
     assert result is None
 
 
-# ---------------------------------------------------------------------------
 # Simple-policy dispatcher must plan a lemonade ROCm attempt for AMD-only hosts.
-# This is the path setup.sh actually invokes (via --simple-policy), so the
-# lemonade integration is useless if it isn't wired in here.
-# ---------------------------------------------------------------------------
+# This is the path setup.sh invokes (via --simple-policy), so the lemonade
+# integration is useless if it isn't wired in here.
 
 direct_linux_release_plan = getattr(_mod, "direct_linux_release_plan", None)
 direct_upstream_release_plan = getattr(_mod, "direct_upstream_release_plan", None)
diff --git a/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py b/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
index 215936bd20..666a503dbb 100644
--- a/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
+++ b/studio/backend/tests/test_llama_cpp_cache_aware_disk_check.py
@@ -1,18 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Tests for the cache-aware disk-space preflight in
-``LlamaCppBackend.load_model``.
+"""Tests for the cache-aware disk-space preflight in ``LlamaCppBackend.load_model``.
 
-The preflight used to compare the repo's total GGUF download size against
-free disk without accounting for bytes already in the Hugging Face cache.
-That made re-loading a cached large model (e.g. ``unsloth/MiniMax-M2.7-GGUF``
-at 131 GB) fail cold whenever free disk was below the full weight footprint,
-even though nothing needed downloading.
-
-These tests exercise the preflight arithmetic in isolation by driving
-``get_paths_info`` and ``try_to_load_from_cache`` through ``mock.patch``.
-No network, GPU, or subprocess use. Cross-platform: Linux, macOS, Windows, WSL.
+The preflight used to compare the repo's total GGUF size against free disk
+without counting bytes already in the HF cache, so re-loading a cached large
+model failed cold even though nothing needed downloading. These tests exercise
+the preflight arithmetic in isolation (no network/GPU/subprocess).
 """
 
 from __future__ import annotations
@@ -25,10 +19,8 @@ from unittest.mock import patch
 
 import pytest
 
-# ---------------------------------------------------------------------------
-# Stub heavy / unavailable external deps before importing the module under
-# test. Same pattern as test_kv_cache_estimation.py.
-# ---------------------------------------------------------------------------
+# Stub heavy / unavailable deps before importing the module under test.
+# Same pattern as test_kv_cache_estimation.py.
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
@@ -96,12 +88,11 @@ def _preflight(
     hf_repo = "unsloth/Example-GGUF",
     hf_token = None,
 ):
-    """Run the preflight arithmetic as in llama_cpp.py; return the decision
-    outcome as a dict.
+    """Run the llama_cpp.py preflight arithmetic; return the decision as a dict.
 
     ``repo_files``: list of (filename, remote_bytes).
-    ``cached_files``: dict {filename: on_disk_bytes} for files already cached.
-    ``free_bytes``: value returned by shutil.disk_usage(cache_dir).free.
+    ``cached_files``: {filename: on_disk_bytes} for files already cached.
+    ``free_bytes``: shutil.disk_usage(cache_dir).free.
     """
     import os
     import shutil
@@ -109,8 +100,8 @@ def _preflight(
     path_infos = [_FakePathInfo(name, size) for name, size in repo_files]
 
     with tempfile.TemporaryDirectory() as tmp:
-        # SPARSE files for the cached ones so os.path.exists / os.path.getsize
-        # pass without allocating bytes on disk -- critical for multi-GB models.
+        # Sparse files so exists/getsize pass without allocating bytes on disk
+        # (critical for multi-GB models).
         cache_paths = {}
         for name, sz in cached_files.items():
             p = Path(tmp) / name.replace("/", "_")
@@ -122,8 +113,7 @@ def _preflight(
         def fake_try_to_load_from_cache(repo_id, filename):
             return cache_paths.get(filename)
 
-        # Mirror the real code's variable names and control flow so behavioral
-        # drift is caught immediately.
+        # Mirror the real code's names and control flow so drift is caught.
         total_bytes = sum((p.size or 0) for p in path_infos)
         already_cached_bytes = 0
         for p in path_infos:
diff --git a/studio/backend/tests/test_llama_cpp_context_fit.py b/studio/backend/tests/test_llama_cpp_context_fit.py
index ec66411bfd..58226f938c 100644
--- a/studio/backend/tests/test_llama_cpp_context_fit.py
+++ b/studio/backend/tests/test_llama_cpp_context_fit.py
@@ -5,24 +5,14 @@
 
 Guards two regressions in ``LlamaCppBackend.load_model``:
 
-1. **Auto mode on weights-exceed-VRAM** (``n_ctx == 0``): when weights
-   alone exceed 90% of every GPU subset's free memory, the auto-pick loop
-   used to exit without matching, leaving ``effective_ctx`` at the native
-   context (e.g. 196608 for MiniMax-M2.7). Studio's UI spec wants 4096 so
-   the slider lands on a usable value; the user can still drag higher and
-   trigger ``--fit on`` with a warning.
+1. Auto mode (``n_ctx == 0``) when weights exceed every GPU subset's free
+   memory: auto-pick should fall back to 4096 (a usable slider value) rather
+   than leaving native ctx. User can still drag higher onto ``--fit on``.
+2. Explicit ctx must never be silently shrunk: when KV overflows fittable
+   weights, honor the explicit ctx with ``--fit on`` flexing ``-ngl``.
 
-2. **Explicit ctx silently shrunk when KV overflows**: with fittable
-   weights but a ctx whose KV cache pushes total memory over 90% of VRAM,
-   the old code binary-searched a smaller ctx and emitted ``-c <capped>
-   -ngl -1`` without telling the caller. The UI already showed its "might
-   be slower" warning and expects the explicit ctx honored with ``--fit
-   on`` flexing ``-ngl`` instead.
-
-Avoids GPU probing, subprocess spawning, and GGUF I/O by driving the
-post-metadata decision block directly against a stubbed instance.
-
-No GPU, network, or libraries beyond pytest. Cross-platform.
+Drives the post-metadata decision block against a stubbed instance: no GPU,
+network, subprocess, or GGUF I/O. Cross-platform.
 """
 
 from __future__ import annotations
@@ -34,24 +24,20 @@ from pathlib import Path
 import pytest
 
 # ---------------------------------------------------------------------------
-# Stub heavy / unavailable deps before importing the module under test.
-# Same pattern as test_kv_cache_estimation.py.
+# Stub heavy/unavailable deps before importing the module under test.
 # ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# loggers
 _loggers_stub = _types.ModuleType("loggers")
 _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
 sys.modules.setdefault("loggers", _loggers_stub)
 
-# structlog
 _structlog_stub = _types.ModuleType("structlog")
 sys.modules.setdefault("structlog", _structlog_stub)
 
-# httpx
 _httpx_stub = _types.ModuleType("httpx")
 for _exc_name in (
     "ConnectError",
@@ -101,8 +87,7 @@ def _make_backend(
     kv_key_length = 128,
     kv_value_length = 128,
 ):
-    """LlamaCppBackend with GGUF metadata fields set and the decision
-    block's helpers stubbed out."""
+    """LlamaCppBackend with GGUF metadata set and decision helpers stubbed."""
     inst = LlamaCppBackend.__new__(LlamaCppBackend)
     inst._context_length = native_ctx
     inst._n_layers = n_layers
@@ -134,8 +119,8 @@ def _drive(
 ):
     """Drive the post-metadata portion of load_model with stubbed inputs.
 
-    Mirrors the decision block at llama_cpp.py:1137-1296 to assert the
-    command that would be built, without subprocesses or GPU probes.
+    Mirrors llama_cpp.py:1137-1296 to assert the built command, without
+    subprocesses or GPU probes.
     """
     inst = _make_backend(native_ctx = native_ctx)
     model_size = int(model_gib * GIB)
@@ -152,8 +137,7 @@ def _drive(
     inst._can_estimate_kv = lambda: can_estimate_kv
 
     context_length = inst._context_length
-    # Use the production helper, not a local reimplementation: a local copy
-    # would test the test's own logic, not production's, and hide drift.
+    # Use the production helper, not a reimplementation, to avoid testing our own logic.
     ctx_override = parse_ctx_override(extra_args)
     requested_ctx = resolve_requested_ctx(extra_args, n_ctx)
 
@@ -491,9 +475,8 @@ class TestTightFitPinsToGPU:
 
 @pytest.mark.parametrize("platform_tag", ["linux", "windows", "mac", "rocm"])
 def test_identical_decision_across_platforms(platform_tag):
-    """The decision takes ``[(gpu_idx, free_mib), ...]`` regardless of the
-    source (nvidia-smi / nvidia-smi.exe / Metal / rocm-smi). Identical
-    inputs must yield identical plans."""
+    """Decision takes ``[(gpu_idx, free_mib), ...]`` regardless of source;
+    identical inputs must yield identical plans."""
     plan_a = _drive(n_ctx = 0, model_gib = 8, gpus = [(0, 24_000)])
     plan_b = _drive(n_ctx = 0, model_gib = 8, gpus = [(0, 24_000)])
     assert plan_a == plan_b, platform_tag
diff --git a/studio/backend/tests/test_llama_cpp_freshness.py b/studio/backend/tests/test_llama_cpp_freshness.py
index 25bcf851b4..cb17e0d5e7 100644
--- a/studio/backend/tests/test_llama_cpp_freshness.py
+++ b/studio/backend/tests/test_llama_cpp_freshness.py
@@ -119,10 +119,9 @@ def test_read_install_marker_finds_windows_cmake_layout(tmp_path):
 
 @pytest.mark.parametrize("repo", ["unslothai/llama.cpp", "ggml-org/llama.cpp"])
 def test_read_install_marker_carries_published_repo_dynamically(tmp_path, repo):
-    # The freshness check queries whichever release repo the marker
-    # records, so CUDA Linux (unslothai), CPU Linux x86_64 / macOS
-    # (ggml-org), and ROCm source-build all surface the right "latest"
-    # tag.
+    # The freshness check queries whichever release repo the marker records,
+    # so CUDA (unslothai), CPU/macOS (ggml-org), and ROCm all get the right
+    # "latest" tag.
     install_dir = tmp_path / "llama.cpp"
     _write_marker(install_dir, tag = "b9000", published_repo = repo)
     bin_path = _fake_binary(install_dir, layout = "cmake")
diff --git a/studio/backend/tests/test_llama_cpp_load_progress.py b/studio/backend/tests/test_llama_cpp_load_progress.py
index dcbe16be50..cc1c6256a8 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress.py
@@ -3,32 +3,20 @@
 
 """Tests for ``LlamaCppBackend.load_progress()``.
 
-The chat settings flow and the training overlay both show a generic
-"Starting model..." spinner in the window after a GGUF download finishes
-and before llama-server reports healthy. For small models that window is a
-second or two and nobody notices. For large MoE GGUFs (MiniMax-M2.7,
-Qwen3.5-397B-A17B, etc.) llama-server spends minutes in kernel state D,
-paging tens or hundreds of GB of shards into the page cache. The UI has no
-way to show a real progress bar, rate, or ETA during that window.
+For large MoE GGUFs, llama-server spends minutes paging shards into the page
+cache after download. ``load_progress()`` samples ``/proc/<pid>/status VmRSS``
+against the total shard size on disk so the UI can render a real bar plus
+rate/ETA. Contract pinned here:
 
-``load_progress()`` samples ``/proc/<pid>/status VmRSS`` (what the kernel
-actually paged in) against the total shard file size on disk, so the
-frontend can render a real bar plus rate/ETA. This module pins that
-contract:
-
-  * returns ``None`` when no load is in flight
-  * returns ``{"phase": "mmap", ...}`` while the subprocess is alive
-    but ``_healthy`` is False
-  * returns ``{"phase": "ready", ...}`` once ``_healthy`` flips
-  * ``bytes_total`` is derived from the resolved on-disk path
-    (which the paired fix assigns to ``self._gguf_path`` on both the
-    local-GGUF and HF-download code paths)
+  * ``None`` when no load is in flight
+  * ``{"phase": "mmap", ...}`` while the subprocess is alive but ``_healthy`` is False
+  * ``{"phase": "ready", ...}`` once ``_healthy`` flips
+  * ``bytes_total`` derived from the resolved on-disk path (``self._gguf_path``)
   * ``bytes_loaded`` is VmRSS in bytes, capped by total, rounded
-  * ``fraction`` is clamped to 0..1 and rounded to 4 decimal places
+  * ``fraction`` clamped to 0..1, rounded to 4 dp
 
-Linux-only via ``/proc``; without ``/proc`` the method returns ``None``
-instead of raising. Cross-platform test: skips cleanly on macOS / Windows
-when ``/proc`` is unavailable.
+Linux-only via ``/proc``; returns ``None`` (not raises) without it, so tests
+skip cleanly on macOS / Windows.
 """
 
 from __future__ import annotations
@@ -42,10 +30,7 @@ from unittest.mock import patch
 
 import pytest
 
-# ---------------------------------------------------------------------------
 # Stub heavy / unavailable deps before importing the module under test.
-# Same pattern as test_kv_cache_estimation.py.
-# ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
diff --git a/studio/backend/tests/test_llama_cpp_load_progress_live.py b/studio/backend/tests/test_llama_cpp_load_progress_live.py
index ce9dd509bf..98e19944dd 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress_live.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress_live.py
@@ -3,18 +3,10 @@
 
 """Live, no-mock integration test for ``LlamaCppBackend.load_progress()``.
 
-The companion files (``test_llama_cpp_load_progress.py`` and
-``test_llama_cpp_load_progress_matrix.py``) patch ``builtins.open`` to feed
-synthetic VmRSS values. This file is the opposite: it uses **real**
-subprocesses, **real** file sizes, and the **real** ``/proc`` interface,
-checking that the contract from the mocked tests still maps to what the kernel
-returns on a live Linux system.
-
-Why both: the mocked tests can be fooled by an implementation that parses
-``/proc`` in a format the kernel no longer uses, or assumes ``Path.stat()`` vs
-``os.path.getsize``. This file hits the real APIs so format drift gets caught.
-
-Skipped cleanly on non-Linux (no ``/proc``).
+The companion mocked tests patch ``builtins.open`` for synthetic VmRSS values;
+this one uses real subprocesses, file sizes, and ``/proc`` so format drift the
+mocks can't see (kernel ``/proc`` layout, stat vs getsize) gets caught. Skipped
+on non-Linux (no ``/proc``).
 """
 
 from __future__ import annotations
@@ -28,10 +20,7 @@ from pathlib import Path
 
 import pytest
 
-# ---------------------------------------------------------------------------
-# Same stubs as the matrix file (self-contained so this file runs standalone
-# and via the full suite).
-# ---------------------------------------------------------------------------
+# Same stubs as the matrix file (self-contained for standalone + full-suite runs).
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
diff --git a/studio/backend/tests/test_llama_cpp_load_progress_matrix.py b/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
index 1a698d3613..5c4d9106d8 100644
--- a/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
+++ b/studio/backend/tests/test_llama_cpp_load_progress_matrix.py
@@ -3,29 +3,12 @@
 
 """Extended test matrix for ``LlamaCppBackend.load_progress()``.
 
-Companion to ``test_llama_cpp_load_progress.py`` (basic contract). Widens
-coverage to edge cases that bit (or were thought to bite) cross-platform
-installs:
+Companion to ``test_llama_cpp_load_progress.py`` (basic contract). Covers
+cross-platform edge cases: platform matrix (/proc absence), VmRSS parsing,
+filesystem edges (HF-cache symlinks, broken/missing/relative paths), shard
+aggregation, lifecycle races, concurrent sampling, and fraction bounds.
 
-  * Platform matrix — macOS/Windows via ``/proc`` absence.
-  * ``VmRSS`` parsing — tab vs space delimiter, missing line, malformed
-    integer.
-  * Filesystem edges — HF-cache symlinks, broken symlinks, nonexistent
-    paths, relative paths.
-  * Shard aggregation — partial multi-shard downloads with some shards
-    still ``.incomplete``, two shard series in one dir,
-    ``mmproj-*.gguf`` sibling exclusion for non-sharded primaries,
-    single-file models.
-  * Lifecycle races — process set before ``_gguf_path``, process dead
-    mid-sample, ``_healthy`` flipped to True.
-  * Concurrent sampling — 10 threads × 50 iterations against one
-    backend, hitting real ``/proc`` (no mocks — see
-    ``TestConcurrentSampling`` for why).
-  * Fraction bounds — capped at 1.0 when RSS exceeds total; 0.0 when
-    total is zero.
-
-Linux-only in practice (``/proc`` stubbed where needed). The stable
-subset runs in well under a second.
+Linux-only in practice (``/proc`` stubbed where needed).
 """
 
 from __future__ import annotations
@@ -40,10 +23,7 @@ from unittest.mock import patch
 
 import pytest
 
-# ---------------------------------------------------------------------------
 # Stub heavy/unavailable deps before importing the module under test.
-# Same pattern as test_llama_cpp_load_progress.py.
-# ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
@@ -420,11 +400,8 @@ class TestConcurrentSampling:
     def test_parallel_invocations_never_raise(self, tmp_path):
         """Many concurrent samplers on one backend must not raise.
 
-        We do NOT patch ``builtins.open`` here: ``unittest.mock.patch``
-        is not thread-safe -- interleaved enter/exit across threads can
-        leak a Mock into ``builtins.open`` and poison later tests.
-        Instead each thread hits the real ``/proc/self/status``, the
-        code path that matters in prod.
+        No ``builtins.open`` patch: ``mock.patch`` isn't thread-safe and could
+        leak a Mock into ``open``. Each thread hits the real ``/proc/self/status``.
         """
         _sparse(tmp_path / "m.gguf", 1 * 1024**3)
         inst = _make()
diff --git a/studio/backend/tests/test_llama_cpp_max_context_threshold.py b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
index 30131991ae..310aaf6c0f 100644
--- a/studio/backend/tests/test_llama_cpp_max_context_threshold.py
+++ b/studio/backend/tests/test_llama_cpp_max_context_threshold.py
@@ -28,10 +28,8 @@ from pathlib import Path
 
 import pytest
 
-# ---------------------------------------------------------------------------
 # Stub heavy / unavailable deps before importing the module under test.
 # Same pattern as test_kv_cache_estimation.py.
-# ---------------------------------------------------------------------------
 
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
@@ -79,9 +77,7 @@ sys.modules.setdefault("httpx", _httpx_stub)
 from core.inference.llama_cpp import LlamaCppBackend
 
 
-# ---------------------------------------------------------------------------
 # Helpers
-# ---------------------------------------------------------------------------
 
 GIB = 1024**3
 
@@ -154,9 +150,7 @@ def _compute_max_available_ctx(
     return max_available_ctx
 
 
-# ---------------------------------------------------------------------------
 # Weights exceed every GPU subset's VRAM  (MiniMax-M2.7-like)
-# ---------------------------------------------------------------------------
 
 
 class TestMaxContextLengthForWeightsExceedVRAM:
@@ -193,9 +187,7 @@ class TestMaxContextLengthForWeightsExceedVRAM:
         assert got == 2048
 
 
-# ---------------------------------------------------------------------------
 # Fittable models (regression guard)
-# ---------------------------------------------------------------------------
 
 
 class TestMaxContextLengthForFittableModels:
@@ -233,9 +225,7 @@ class TestMaxContextLengthForFittableModels:
         assert got >= 131072 - 256  # rounded to 256 boundary
 
 
-# ---------------------------------------------------------------------------
 # Property plumbing
-# ---------------------------------------------------------------------------
 
 
 class TestMaxContextLengthProperty:
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index fc21c48b76..784ab1b259 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -402,11 +402,9 @@ def test_already_in_target_state_vision_mtp_default_matches():
 
 
 def test_already_in_target_state_vision_off_matches_vision_backend():
-    # Vision loads silently drop speculative decoding at the route level
-    # (_request_matches_loaded_settings overrides req to "off"). In
-    # llama_cpp.py, _already_in_target_state compares canonical requested
-    # modes; a vision backend recorded with _requested_spec_mode = "off"
-    # matches a req of "off" or None+vision.
+    # Vision loads drop speculative decoding at the route level (req -> "off").
+    # _already_in_target_state compares canonical requested modes; a vision
+    # backend with _requested_spec_mode="off" matches req "off" or None+vision.
     backend = _mtp_backend(
         _model_identifier = "unsloth/Qwen3-VL-4B-Instruct-GGUF",
         _is_vision = True,
diff --git a/studio/backend/tests/test_llama_cpp_no_context_shift.py b/studio/backend/tests/test_llama_cpp_no_context_shift.py
index 312adea83e..10b1dc7ff6 100644
--- a/studio/backend/tests/test_llama_cpp_no_context_shift.py
+++ b/studio/backend/tests/test_llama_cpp_no_context_shift.py
@@ -101,8 +101,7 @@ def test_flag_sits_inside_the_base_cmd_list():
     source = _load_model_source()
     start = source.find("cmd = [")
     assert start >= 0, "could not find the base cmd = [...] block"
-    # Find the first line containing only ``]`` (possibly indented); works for
-    # any indentation style the formatter picks.
+    # Find the first line containing only ``]`` (possibly indented).
     rest = source[start:]
     end_rel = -1
     for line_start, line in _iter_lines_with_offset(rest):
@@ -119,7 +118,7 @@ def test_flag_sits_inside_the_base_cmd_list():
         "conditional branch -- otherwise some code paths would still "
         "run with silent context shift enabled."
     )
-    # Also pin that it sits next to -c / --ctx so the grouping makes sense.
+    # Pin that it sits next to -c / --ctx so the grouping makes sense.
     assert '"-c"' in block
     assert '"--flash-attn"' in block
 
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_health.py b/studio/backend/tests/test_llama_cpp_wait_for_health.py
index d787107d39..33f9e9d803 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_health.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_health.py
@@ -50,9 +50,7 @@ for _exc_name in (
 
 
 def _make_backend(port: int = 12345) -> LlamaCppBackend:
-    """Barebones LlamaCppBackend with only the attributes
-    _wait_for_health touches. Bypasses __init__ to avoid the full
-    subprocess + logging stack."""
+    """Barebones LlamaCppBackend with only the attributes _wait_for_health touches (bypasses __init__)."""
     b = LlamaCppBackend.__new__(LlamaCppBackend)
     b._port = port
     b._stdout_thread = None
@@ -70,12 +68,9 @@ class TestWaitForHealthResilience:
         assert b._wait_for_health(timeout = 1.0, interval = 0.01) is True
 
     def test_read_error_loops_to_subprocess_poll(self, monkeypatch):
-        """WinError 10054 maps to httpx.ReadError. The loop must swallow it;
-        the next iteration detects the dead subprocess via poll() != None and
-        returns False with a structured exit-code log, not the ReadError."""
+        """WinError 10054 (httpx.ReadError) must be swallowed; the next iteration sees the dead subprocess and returns False with a structured exit-code log."""
         b = _make_backend()
-        # Iter 1: process alive (reach the httpx probe).
-        # Iter 2: process exited (hit the exit-code branch, return False).
+        # Iter 1: alive (reach probe); iter 2: exited (exit-code branch -> False).
         b._process.poll.side_effect = [None, 1]
         b._process.returncode = 1
         b._stdout_lines = ["llama-server: ggml-cuda.dll failed to load"]
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
index 5183553607..493bb93e8c 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_vram_settle.py
@@ -19,10 +19,7 @@ from unittest.mock import patch
 import pytest
 
 
-# ---------------------------------------------------------------------------
-# Same external-dep stubs as the other llama_cpp tests so this module imports
-# without httpx / structlog / loggers installed.
-# ---------------------------------------------------------------------------
+# External-dep stubs so this module imports without httpx / structlog / loggers.
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
@@ -34,8 +31,7 @@ sys.modules.setdefault("loggers", _loggers_stub)
 _structlog_stub = _types.ModuleType("structlog")
 _structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("stub")
 sys.modules.setdefault("structlog", _structlog_stub)
-# Set get_logger even if a prior test inserted a bare ``structlog`` stub
-# via ``setdefault``.
+# Set get_logger even if a prior test inserted a bare ``structlog`` stub.
 if not hasattr(sys.modules["structlog"], "get_logger"):
     sys.modules["structlog"].get_logger = _structlog_stub.get_logger
 
@@ -265,9 +261,7 @@ def test_tolerance_two_percent_for_large_cards():
 
 def test_load_model_calls_helper_outside_lock_and_uses_last_kill_timestamp():
     """Pin the call site: outside Phase 3 lock, gated on the timestamp, no
-    ``had_live_process`` in-band flag regression. Mirrors the
-    ``inspect.getsource`` pattern from ``test_llama_cpp_no_context_shift``.
-    """
+    ``had_live_process`` in-band flag regression."""
     import inspect
 
     src = inspect.getsource(LlamaCppBackend.load_model)
diff --git a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
index 4fa7d2f8e6..957de4bad6 100644
--- a/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
+++ b/studio/backend/tests/test_llama_cpp_windows_nvidia_path.py
@@ -60,8 +60,7 @@ from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
 
 
 def _make_nvidia_layout(prefix: Path, pkgs_with_layout: dict[str, str]):
-    """Build a fake <prefix>/Lib/site-packages/nvidia/<pkg>/{bin|Library/bin}
-    tree with a stub DLL in each leaf so isdir() picks them up."""
+    """Build a fake nvidia/<pkg>/{bin|Library/bin} tree with a stub DLL per leaf."""
     nv = prefix / "Lib" / "site-packages" / "nvidia"
     for pkg, layout in pkgs_with_layout.items():
         if layout == "bin":
@@ -133,10 +132,8 @@ class TestWindowsPipNvidiaDllDirs:
         assert result == []
 
     def test_picks_up_torch_lib(self, tmp_path):
-        # PyTorch's Windows CUDA wheel bundles cudart64_X.dll /
-        # cublas64_X.dll directly under Lib/site-packages/torch/lib/ rather
-        # than as separate nvidia-* wheels. Without this, torch-bundled-CUDA
-        # installs still hit #5106.
+        # PyTorch's Windows CUDA wheel bundles cudart64/cublas64 DLLs under
+        # torch/lib/ rather than as nvidia-* wheels; else still hits #5106.
         torch_lib = tmp_path / "Lib" / "site-packages" / "torch" / "lib"
         torch_lib.mkdir(parents = True)
         (torch_lib / "cudart64_12.dll").write_bytes(b"")
@@ -179,16 +176,13 @@ class TestWindowsPipNvidiaDllDirs:
         assert result == []
 
     def test_missing_prefix_does_not_raise(self):
-        # If sys.prefix points to a nonexistent path (unusual but possible
-        # during test setup), the resolver must return [], not raise.
+        # Nonexistent sys.prefix: resolver must return [], not raise.
         result = LlamaCppBackend._windows_pip_nvidia_dll_dirs("/this/path/does/not/exist/anywhere")
         assert result == []
 
     def test_picks_up_cu13_bin_x86_64_layout(self, tmp_path):
-        # Current ``nvidia-cuda-runtime`` 13.x and ``nvidia-cublas`` 13.x
-        # Windows wheels ship DLLs under ``nvidia/cu13/bin/x86_64/`` instead
-        # of ``nvidia/<pkg>/bin/``. Without this, the new CUDA 13 wheel
-        # generation hits the original #5106 failure mode.
+        # nvidia 13.x Windows wheels ship DLLs under nvidia/cu13/bin/x86_64/
+        # not nvidia/<pkg>/bin/; else the new CUDA 13 wheels hit #5106.
         dll_dir = tmp_path / "Lib" / "site-packages" / "nvidia" / "cu13" / "bin" / "x86_64"
         dll_dir.mkdir(parents = True)
         for name in ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll"):
@@ -219,10 +213,8 @@ class TestWindowsPipNvidiaDllDirs:
         assert cu13_arch in result_set
 
     def test_glob_meta_in_prefix_is_safe(self, tmp_path):
-        # Windows usernames / install paths can contain ``[`` or ``]``. A
-        # glob-based resolver would read these as a character class and
-        # return [] even when DLL dirs exist. The iterdir-based
-        # implementation must work on such paths.
+        # Windows paths can contain ``[``/``]``; a glob-based resolver would
+        # read these as a character class. The iterdir impl must handle them.
         prefix = tmp_path / "studio_[gpu]_install"
         dll_dir = prefix / "Lib" / "site-packages" / "nvidia" / "cuda_runtime" / "bin"
         dll_dir.mkdir(parents = True)
@@ -231,9 +223,8 @@ class TestWindowsPipNvidiaDllDirs:
         assert str(dll_dir) in result, f"bracket-prefixed path returned empty: {result}"
 
     def test_arch_subdir_listed_before_parent_bin(self, tmp_path):
-        # When both ``nvidia/<pkg>/bin/`` and ``nvidia/<pkg>/bin/x86_64/``
-        # exist, the arch-specific subdir must be listed first so the Windows
-        # DLL search finds cudart64_X.dll even if the parent ``bin`` is empty.
+        # When both bin/ and bin/x86_64/ exist, the arch subdir must come first
+        # so the Windows DLL search finds cudart64_X.dll if parent bin is empty.
         site = tmp_path / "Lib" / "site-packages"
         outer_bin = site / "nvidia" / "cu13" / "bin"
         arch_bin = outer_bin / "x86_64"
diff --git a/studio/backend/tests/test_llama_server_args.py b/studio/backend/tests/test_llama_server_args.py
index 60d4fb0bc3..52e3848157 100644
--- a/studio/backend/tests/test_llama_server_args.py
+++ b/studio/backend/tests/test_llama_server_args.py
@@ -16,10 +16,8 @@ from pathlib import Path
 
 import pytest
 
-# Load llama_server_args.py directly so this test doesn't drag in the full
-# backend chain (fastapi / structlog / loggers / utils.hardware) via
-# core/inference/__init__.py. The validator is intentionally dependency-free
-# and unit tests should reflect that.
+# Load llama_server_args.py directly to avoid dragging in the full backend
+# chain via core/inference/__init__.py. The validator is dependency-free.
 _LSA_PATH = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_server_args.py"
 _spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
 _lsa = importlib.util.module_from_spec(_spec)
@@ -72,10 +70,9 @@ validate_extra_args = _lsa.validate_extra_args
         # Reasoning controls
         ["--reasoning-format", "deepseek"],
         ["-rea", "auto"],
-        # Soft-managed: user flags last-wins-override Studio's auto-set
-        # version. --parallel / -np / --n-parallel are NOT here -- they're
-        # hard-denied (KV-cache + slot count would desync). Use
-        # `unsloth studio run --parallel N` instead.
+        # Soft-managed: user flags last-wins over Studio's auto-set version.
+        # --parallel / -np / --n-parallel are hard-denied (KV-cache + slot
+        # count would desync); use `unsloth studio run --parallel N` instead.
         ["-c", "131072"],
         ["--ctx-size", "8192"],
         ["--flash-attn", "off"],
diff --git a/studio/backend/tests/test_login_rate_limit.py b/studio/backend/tests/test_login_rate_limit.py
index 6f2d2c7d94..14b10576da 100644
--- a/studio/backend/tests/test_login_rate_limit.py
+++ b/studio/backend/tests/test_login_rate_limit.py
@@ -69,8 +69,7 @@ class TestClientIp:
             "127.0.0.1",
             {"x-forwarded-for": "198.51.100.7, 10.0.0.1"},
         )
-        # Proxy header can be spoofed; without the opt-in, trust only the
-        # direct connection.
+        # Proxy header is spoofable; without the opt-in, trust the direct connection.
         assert _client_ip(req) == "127.0.0.1"
 
     def test_honours_first_xff_when_trust_on(self, env_trust_proxy):
@@ -123,8 +122,8 @@ class TestClientIp:
     def test_forwarded_isolates_first_element(self, env_trust_proxy):
         from routes.auth import _client_ip
 
-        # Multi-element Forwarded must pick the first element only, else suffix
-        # variations create attacker-controlled buckets.
+        # Pick the first Forwarded element only, else suffix variations create
+        # attacker-controlled buckets.
         req = _FakeRequest(
             "127.0.0.1",
             {"forwarded": "for=198.51.100.42, for=10.0.0.1;proto=https"},
@@ -189,9 +188,7 @@ class TestBucketKeyAndBlocking:
         req = _FakeRequest("203.0.113.10")
         for idx in range(5):
             auth_routes._record_login_failure(auth_routes._unknown_user_key(req))
-            # A different "username" each attempt wouldn't throttle under
-            # per-(ip,username) only; the IP aggregate must.
-        # The next missing-user attempt is blocked.
+            # Per-(ip,username) alone wouldn't throttle distinct usernames; the IP aggregate must.
         assert auth_routes._login_blocked(auth_routes._unknown_user_key(req)) > 0
 
     def test_unknown_user_bucket_is_single_sentinel(self, env_no_proxy):
@@ -202,8 +199,7 @@ class TestBucketKeyAndBlocking:
         unknown_key = auth_routes._unknown_user_key(req)
         for _ in range(20):
             auth_routes._record_login_failure(unknown_key)
-        # Account bucket cardinality stays at exactly one sentinel entry for
-        # this IP regardless of how many distinct usernames sprayed.
+        # Exactly one sentinel bucket for this IP regardless of usernames sprayed.
         ip_keys = [k for k in auth_routes._LOGIN_BUCKETS if k[0] == "203.0.113.11"]
         assert len(ip_keys) == 1
         assert ip_keys[0][1].startswith("\x00")
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index 9def1619d7..ede3cf15d4 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -151,8 +151,7 @@ def test_execute_tool_disabled_server(tmp_path, monkeypatch):
 
 
 def test_mcp_specs_skip_invalid_openai_function_names():
-    """OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; names with '.',
-    '/', spaces, etc. would 400 the whole request."""
+    """OpenAI requires function.name ^[a-zA-Z0-9_-]{1,64}$; bad names 400 the request."""
     from core.inference.tools import _mcp_specs_for_server
 
     server = {"id": "srv", "display_name": "S"}
@@ -177,8 +176,7 @@ def test_mcp_specs_skip_empty_tool_name():
 
 
 def test_mcp_specs_drops_duplicate_names():
-    """Same tool name twice from one MCP server -> OpenAI rejects the
-    request as 'duplicates'. Drop duplicates before forwarding."""
+    """Duplicate tool names from one server -> OpenAI rejects; drop before forwarding."""
     from core.inference.tools import _mcp_specs_for_server
 
     server = {"id": "srv", "display_name": "S"}
@@ -188,8 +186,7 @@ def test_mcp_specs_drops_duplicate_names():
 
 
 def test_call_tool_sync_respects_pre_set_cancel_event(monkeypatch):
-    """cancel_event set before the call -> immediate Error: cancelled, no
-    network round-trip."""
+    """Pre-set cancel_event -> immediate cancellation, no network round-trip."""
     import threading
     from core.inference import mcp_client
 
@@ -399,9 +396,8 @@ def test_test_endpoint_surfaces_url_validation_as_400(tmp_path, monkeypatch):
 
 
 def test_tool_xml_parser_handles_hyphenated_parameter_names():
-    """MCP tool schemas often use hyphenated property names like
-    `issue-number` / `repo-name`; the XML parser's `<parameter=\\w+>` regex
-    dropped those keys. Verify hyphenated names round-trip."""
+    """Hyphenated property names like `issue-number` must round-trip through the
+    XML parser (the old `<parameter=\\w+>` regex dropped them)."""
     from core.inference.tool_call_parser import parse_tool_calls_from_text
     import json as _json
 
@@ -417,8 +413,8 @@ def test_tool_xml_parser_handles_hyphenated_parameter_names():
 
 
 def test_tool_healing_strip_handles_hyphenated_function_names():
-    """GGUF's core/tool_healing.py has its own copy of the XML strip
-    regex; the round-4 fix to the shared parser missed this file."""
+    """core/tool_healing.py has its own copy of the XML strip regex that the
+    shared-parser fix missed."""
     from core.tool_healing import strip_tool_call_markup
 
     out = strip_tool_call_markup(
@@ -428,9 +424,8 @@ def test_tool_healing_strip_handles_hyphenated_function_names():
 
 
 def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
-    """When the model emits a tool call not in the per-request tool list,
-    the GGUF agentic loop must refuse to dispatch (mirroring the
-    safetensors path). execute_tool previously ran the call regardless."""
+    """A tool call not in the per-request list must be refused by the GGUF
+    agentic loop (mirroring the safetensors path)."""
     from core.inference import tools as tools_mod
 
     captured: list[str] = []
@@ -441,8 +436,7 @@ def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
 
     monkeypatch.setattr(tools_mod, "execute_tool", fake_execute)
 
-    # Re-create the allow-list check inline to unit-test the behavior
-    # without spinning up llama-server.
+    # Inline allow-list check to unit-test behavior without llama-server.
     def _gate(tools_advertised, called_name, args):
         allowed = {
             (t.get("function") or {}).get("name")
@@ -472,9 +466,8 @@ def test_gguf_allow_list_blocks_unadvertised_tool(monkeypatch):
 
 
 def test_call_tool_sync_short_circuits_on_pre_set_cancel(monkeypatch):
-    """cancel_event set BEFORE call_tool_sync runs -> no HTTP request made.
-    The call task was previously created before the cancel check, opening a
-    transport that the watcher then had to cancel."""
+    """Pre-set cancel_event -> no HTTP request (task used to open a transport
+    before the cancel check)."""
     from core.inference import mcp_client
 
     opened: list[str] = []
@@ -511,8 +504,7 @@ def test_call_tool_sync_short_circuits_on_pre_set_cancel(monkeypatch):
 
 def test_clear_oauth_tokens_swallows_constructor_errors(tmp_path, monkeypatch):
     """clear_oauth_tokens_async is best-effort; an OAuth constructor failure
-    (e.g. missing fastmcp.client.auth) must not bubble into a 500 from the
-    delete / update routes."""
+    must not bubble into a 500 from the delete/update routes."""
     import asyncio
     from core.inference import mcp_client
 
@@ -534,9 +526,8 @@ def test_clear_oauth_tokens_swallows_constructor_errors(tmp_path, monkeypatch):
 
 
 def test_tool_xml_parser_handles_hyphenated_function_names():
-    """MCP tool names are advertised as `mcp__srv__list-issues` (the regex
-    fix allows '-'); the XML tool-call parser must parse them too, else the
-    model can call the tool but Studio cannot dispatch."""
+    """Hyphenated tool names like `mcp__srv__list-issues` must parse, else the
+    model can call the tool but Studio can't dispatch."""
     from core.inference.tool_call_parser import parse_tool_calls_from_text
 
     calls = parse_tool_calls_from_text(
@@ -570,9 +561,8 @@ def test_tool_xml_strip_handles_hyphenated_function_names():
 
 
 def test_safetensors_agentic_empty_allowlist_still_means_allow_all():
-    """Document the contract: at the safetensors_agentic layer, tools=[] is
-    still "no constraint" (existing callers work unchanged). The real fix
-    for the MCP-only-no-discovery case lives at the route level in
+    """Contract: at the safetensors_agentic layer tools=[] means "no
+    constraint". The MCP-only-no-discovery fix lives at the route level in
     inference.py, which refuses use_tools when the resolved list is empty."""
     import threading
     from core.inference.safetensors_agentic import run_safetensors_tool_loop
diff --git a/studio/backend/tests/test_mcp_stdio_improvements.py b/studio/backend/tests/test_mcp_stdio_improvements.py
index bec4f9393e..b0bfd45135 100644
--- a/studio/backend/tests/test_mcp_stdio_improvements.py
+++ b/studio/backend/tests/test_mcp_stdio_improvements.py
@@ -188,8 +188,7 @@ def test_validate_url_allows_url_in_argument(monkeypatch):
 
 
 # ── P6: Data Recipe stdio path obeys the same host gate ─────────────
-# build_mcp_providers needs the data_designer plugin, installed only in the
-# Studio test job; skip there rather than fail the core matrix.
+# build_mcp_providers needs the Studio-only data_designer plugin; skip if absent.
 
 _STDIO_RECIPE = {
     "mcp_providers": [
diff --git a/studio/backend/tests/test_mcp_stdio_pr5863.py b/studio/backend/tests/test_mcp_stdio_pr5863.py
index d744c07b14..c6a4898d5d 100644
--- a/studio/backend/tests/test_mcp_stdio_pr5863.py
+++ b/studio/backend/tests/test_mcp_stdio_pr5863.py
@@ -1,13 +1,10 @@
 """Verification tests for PR #5863 (stdio MCP server support).
 
-Covers the pure helpers (is_stdio / parse_stdio_command / stdio_mcp_enabled /
-probe_timeout), the route-level _validate_url gate, and - most importantly -
-that the UNSLOTH_STUDIO_ALLOW_STDIO_MCP gate blocks the stdio transport at
-every enforcement point (create, update, test, refresh, discovery, execute)
-when disabled and reaches it when enabled. The transport (_client) is stubbed
-so no real subprocess spawns; a recorder asserts whether it was reached.
-
-Run from studio/backend:  python -m pytest tests/test_mcp_stdio_pr5863.py -q
+Covers the pure helpers, the route-level _validate_url gate, and that the
+UNSLOTH_STUDIO_ALLOW_STDIO_MCP gate blocks the stdio transport at every
+enforcement point (create/update/test/refresh/discovery/execute) when disabled
+and reaches it when enabled. The transport is stubbed so no subprocess spawns;
+a recorder asserts whether it was reached.
 """
 
 import sys
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 2ff7acfbd0..16a7bbc46d 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -27,9 +27,7 @@ def main_module():
     return _main
 
 
-# =====================================================================
 # MaxBodyMiddleware
-# =====================================================================
 
 
 def _make_protected_app(
@@ -205,9 +203,7 @@ class TestMaxBodyMiddleware:
         assert "Content-Length" in r.json()["detail"]
 
 
-# =====================================================================
 # SecurityHeadersMiddleware / CSP
-# =====================================================================
 
 
 def _make_csp_app(main_module, attach_nonce: str | None = None):
@@ -301,9 +297,7 @@ class TestSecurityHeadersMiddleware:
             assert any(src == host for src in img_sources)
 
 
-# =====================================================================
 # /api/health auth gate
-# =====================================================================
 
 
 @pytest.fixture
diff --git a/studio/backend/tests/test_multimodal_document.py b/studio/backend/tests/test_multimodal_document.py
index 29926299ce..5cd7c876cc 100644
--- a/studio/backend/tests/test_multimodal_document.py
+++ b/studio/backend/tests/test_multimodal_document.py
@@ -85,9 +85,8 @@ _PDF_DATA_URI = f"data:application/pdf;base64,{_TINY_PDF_B64}"
 
 
 def _strip_cache(p: dict) -> dict:
-    # Studio's prompt-cache wiring attaches cache_control:{type:ephemeral}
-    # to the tail block of the last user message; strip it so this test
-    # focuses on translation, not the caching layer.
+    # Strip the prompt-cache cache_control off the last user block so this
+    # test focuses on translation, not the caching layer.
     return {k: v for k, v in p.items() if k != "cache_control"}
 
 
@@ -115,8 +114,8 @@ def test_anthropic_base64_pdf_becomes_document_block(monkeypatch):
     types = [p.get("type") for p in parts]
     assert "document" in types, parts
     doc = _strip_cache(next(p for p in parts if p.get("type") == "document"))
-    # citations:{enabled:true} opts into Anthropic's natural-citation
-    # pipeline; without it the citations_delta handler is a no-op.
+    # citations:{enabled:true} opts into Anthropic's citation pipeline;
+    # without it the citations_delta handler is a no-op.
     assert doc == {
         "type": "document",
         "source": {
@@ -177,9 +176,8 @@ def test_anthropic_empty_document_part_is_dropped(monkeypatch):
 
 
 def test_anthropic_empty_only_document_drops_whole_message(monkeypatch):
-    # If the ONLY part is an unparseable input_document, the helper must
-    # NOT append an empty-content message (Anthropic 400s on "at least
-    # one block is required").
+    # If the only part is an unparseable input_document, the helper must not
+    # append an empty-content message (Anthropic 400s on "at least one block").
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -195,9 +193,8 @@ def test_anthropic_empty_only_document_drops_whole_message(monkeypatch):
 
 
 def test_anthropic_empty_data_uri_payload_is_dropped(monkeypatch):
-    # Codex P2: `data:application/pdf;base64,` with no (or whitespace-only)
-    # payload would make an empty `source.data` that Anthropic 400s on.
-    # Must be filtered before the wire.
+    # A `data:application/pdf;base64,` with empty/whitespace payload makes an
+    # empty `source.data` that Anthropic 400s on; filter it before the wire.
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -226,11 +223,9 @@ def test_anthropic_empty_data_uri_payload_is_dropped(monkeypatch):
 
 
 def test_anthropic_empty_data_uri_falls_back_to_file_url(monkeypatch):
-    # Codex P2 follow-up: the empty-data-URI -> file_url fallback was on
-    # the OpenAI side but missing on Anthropic, where the empty-payload
-    # branch did `continue` and discarded a valid file_url on the same
-    # part. Mirror OpenAI so a malformed inline payload + remote URL
-    # still attaches.
+    # The empty-data-URI -> file_url fallback existed on OpenAI but not
+    # Anthropic, which discarded a valid file_url on the same part. Mirror
+    # OpenAI so a malformed inline payload + remote URL still attaches.
     captured = _capture(
         monkeypatch,
         provider = "anthropic",
@@ -341,10 +336,9 @@ def test_openai_url_pdf_becomes_input_file(monkeypatch):
 
 
 def test_openai_empty_data_uri_falls_back_to_file_url(monkeypatch):
-    # Codex P2 follow-up: an empty `data:application/pdf;base64,` payload
-    # was preferred over a valid `file_url` in the same part, sending
-    # `file_data=""` and 400ing the turn. The translator must treat empty
-    # data URIs as missing and recover via file_url.
+    # An empty `data:application/pdf;base64,` payload was preferred over a valid
+    # `file_url` in the same part, sending `file_data=""` and 400ing. The
+    # translator must treat empty data URIs as missing and recover via file_url.
     captured = _capture(
         monkeypatch,
         provider = "openai",
@@ -444,12 +438,9 @@ def test_openai_empty_document_part_is_dropped(monkeypatch):
 
 
 # ── Pydantic schema + builder pass-through ──────────────────────────
-#
-# The translation tests above call the client directly with hand-built
-# dicts, bypassing both ChatCompletionRequest's discriminated Union and
-# routes/inference._build_external_messages. The tests below close that
-# gap: parse an input_document part through the real schema, run the
-# builder, and assert the part survives to the dict the client receives.
+# The tests above call the client with hand-built dicts, bypassing the schema
+# and _build_external_messages. The tests below parse an input_document part
+# through the real schema + builder and assert it survives to the client dict.
 
 
 def test_chat_message_accepts_input_document_part():
diff --git a/studio/backend/tests/test_offline_gguf_cache_fallback.py b/studio/backend/tests/test_offline_gguf_cache_fallback.py
index 2856bb7cad..aab58adfff 100644
--- a/studio/backend/tests/test_offline_gguf_cache_fallback.py
+++ b/studio/backend/tests/test_offline_gguf_cache_fallback.py
@@ -3,27 +3,14 @@
 
 """Regression tests for the offline GGUF cache fallback path (#5505).
 
-Three failure modes hit users when ``huggingface.co`` is unreachable but the
-requested GGUF repo is fully cached locally:
+When ``huggingface.co`` is unreachable but the repo is cached, three failures
+hit: ``list_gguf_variants`` 500'd (empty dropdown), ``detect_gguf_model_remote``
+returned None (GGUF-only repo misrouted), and ``_download_gguf`` synthesised a
+name absent from cache. Follow-ups: the cache filter matches the snapshot-relative
+path (subdir layouts findable), and DNS auto-detect scopes ``HF_HUB_OFFLINE`` to
+one load so a transient hiccup can't pin the singleton offline.
 
-* ``list_gguf_variants`` raised ``HTTPException(500)`` so the variant
-  dropdown sat empty.
-* ``detect_gguf_model_remote`` returned ``None`` so a GGUF-only repo was
-  misrouted into the transformers/Unsloth backend (a hardware error on macOS).
-* ``_download_gguf`` fell back to a synthetic ``{repo}-{variant}.gguf`` name
-  absent from cache when the in-repo filename did not echo the repo name
-  (e.g. ``unsloth/Qwen3.6-27B-MTP-GGUF`` ships
-  ``Qwen3.6-27B-UD-Q4_K_XL.gguf`` with no ``MTP`` token).
-
-Two follow-up regressions also covered:
-
-* P1 #1: the cache-side variant filter must match the snapshot-relative path,
-  not just the basename, so subdir layouts like ``BF16/foo.gguf`` are findable.
-* P1 #2: the DNS auto-detect must scope ``HF_HUB_OFFLINE`` to one load via
-  try/finally so a transient resolver hiccup cannot lock the long-lived
-  ``LlamaCppBackend`` singleton offline forever.
-
-No GPU, no network, no subprocess. Linux, macOS, Windows compatible.
+No GPU, no network, no subprocess. Linux/macOS/Windows compatible.
 """
 
 from __future__ import annotations
@@ -269,10 +256,8 @@ class TestDetectGgufFromCache:
         assert _detect_gguf_from_hf_cache("unsloth/a") == "a-UD-Q4_K_XL.gguf"
 
     def test_subdir_only_quant_resolves(self, hf_cache):
-        """P1 #1 regression: ``BF16/foo.gguf`` (quant only in directory).
-        The pre-fix cache scan matched on basename, missing this layout
-        and falling through to the synthetic ``{repo}-{variant}.gguf``
-        heuristic."""
+        """Regression: ``BF16/foo.gguf`` (quant only in directory). The pre-fix
+        cache scan matched on basename and missed this layout."""
         _build_cache(
             hf_cache,
             "unsloth/gpt-oss-20b-BF16",
@@ -440,9 +425,8 @@ class TestHfOfflineIfDnsDead:
 
 
 class TestExtractQuantLabelSubdir:
-    """``_extract_quant_label`` must consider parent directories when the
-    basename has no quant token. Subdir layouts like ``BF16/foo.gguf`` are
-    documented here and surface through the cache scan."""
+    """``_extract_quant_label`` must consider parent dirs when the basename has
+    no quant token (subdir layouts like ``BF16/foo.gguf``)."""
 
     def test_quant_in_basename_unchanged(self):
         assert _extract_quant_label("BF16/foo-BF16.gguf") == "BF16"
@@ -455,15 +439,13 @@ class TestExtractQuantLabelSubdir:
         assert _extract_quant_label("UD-Q4_K_XL/weight.gguf") == "UD-Q4_K_XL"
 
     def test_deeper_nesting_picks_nearest_quant_dir(self):
-        # When multiple parent segments match, prefer the innermost (closest
-        # to the file), matching repos like ``models/MXFP4_MOE/foo.gguf``.
+        # Multiple matching parents: prefer the innermost (closest to the file).
         assert _extract_quant_label("models/MXFP4_MOE/foo.gguf") == "MXFP4_MOE"
 
 
 class TestDownloadMmprojOfflineCacheFallback:
-    """``LlamaCppBackend._download_mmproj`` must resolve cached mmproj GGUFs
-    offline, same shape as ``_download_gguf``. Without this the offline vision
-    GGUF load path returns ``None`` even when the mmproj is cached."""
+    """``_download_mmproj`` must resolve cached mmproj GGUFs offline, like
+    ``_download_gguf``; else the offline vision load returns None despite a cache hit."""
 
     def test_cache_lookup_returns_cached_mmproj_when_list_repo_files_fails(self, hf_cache):
         _build_cache(
@@ -667,9 +649,8 @@ class TestDetectGgufFromCacheExcludesMmproj:
 
 
 class TestProbeDnsDeadNoGlobalTimeoutMutation:
-    """``_probe_dns_dead`` must not change ``socket.setdefaulttimeout``
-    process-wide -- concurrent sockets without an explicit timeout would
-    inherit it for the probe window."""
+    """``_probe_dns_dead`` must not change ``socket.setdefaulttimeout`` process-wide;
+    concurrent sockets would inherit it during the probe window."""
 
     def test_default_timeout_unchanged_when_dns_up(self, monkeypatch):
         import socket as _socket
@@ -712,9 +693,8 @@ class TestProbeDnsDeadNoGlobalTimeoutMutation:
 
 
 class TestWaitForHealthRetriesOnReadError:
-    """A TCP RST mid-read while llama-server is still binding the port
-    (Windows: WinError 10054) must not abort the health-poll loop -- that
-    masks a legitimate 'still warming up' state as a fatal load."""
+    """A TCP RST mid-read while llama-server is still binding (Windows: WinError
+    10054) must not abort the health-poll loop and mask warmup as a fatal load."""
 
     def test_read_error_then_success(self, monkeypatch):
         import httpx
diff --git a/studio/backend/tests/test_openai_citation_markers.py b/studio/backend/tests/test_openai_citation_markers.py
index dafcffc8bd..3549a5993e 100644
--- a/studio/backend/tests/test_openai_citation_markers.py
+++ b/studio/backend/tests/test_openai_citation_markers.py
@@ -66,8 +66,7 @@ def test_unknown_source_marker_dropped_silently():
 
 
 def test_multiple_concatenated_markers_resolved_in_order():
-    """Real-world wire shape: markers butted together after a sentence,
-    as in the user-reported bug."""
+    """Real-world wire shape: markers butted together after a sentence (user-reported bug)."""
     markers = "".join(_marker(f"turn{i}view{j}") for i, j in [(1, 0), (1, 1), (3, 0)])
     text = f"All animals ranked. {markers}"
     citations = [
@@ -135,8 +134,7 @@ def test_citation_without_source_id_does_not_crash(citation):
 
 
 def test_multiple_source_id_aliases_resolve_to_same_url():
-    """Every alias for the same URL must resolve, not just the first.
-    Regression for the Codex P1 on the original PR."""
+    """Every alias for the same URL must resolve, not just the first (Codex P1 regression)."""
     a = _marker("turn0view0")
     b = _marker("turn0view0_span_1")
     c = _marker("turn0view0_span_2")
@@ -156,8 +154,7 @@ def test_multiple_source_id_aliases_resolve_to_same_url():
 
 
 def test_source_ids_list_and_legacy_source_id_both_resolve():
-    """Mixed-shape citation: legacy ``source_id`` plus newer
-    ``source_ids`` aliases both resolve."""
+    """Mixed-shape citation: legacy ``source_id`` plus newer ``source_ids`` aliases both resolve."""
     legacy = _marker("legacy_id")
     alias = _marker("alias_id")
     text = f"Both {legacy} and {alias} work."
@@ -173,11 +170,9 @@ def test_source_ids_list_and_legacy_source_id_both_resolve():
     assert not _has_marker_codepoints(out)
 
 
-# ---------------------------------------------------------------------------
 # _rewrite_citation_markers_partial: deferred-annotation tests. OpenAI emits
 # url_citation annotations on a later SSE event; this helper reports
 # `has_unresolved` so the stream loop defers emission. See PR #5713 audit.
-# ---------------------------------------------------------------------------
 
 
 def test_partial_known_marker_resolves_and_clears_unresolved():
@@ -201,7 +196,7 @@ def test_partial_unknown_marker_preserves_verbatim_and_flags():
 
 
 def test_partial_resolves_after_late_annotation():
-    """Two-pass: first call sees no citations, second resolves after annotation."""
+    """Two-pass: first call sees no citations; second resolves after annotation."""
     text = f"See {_marker('s1')} for details."
     out1, unresolved1 = _rewrite_citation_markers_partial(text, [])
     assert unresolved1 is True
@@ -213,9 +208,7 @@ def test_partial_resolves_after_late_annotation():
 
 
 def test_partial_multi_source_partial_resolution_keeps_marker_pending():
-    """Any unresolved token in a multi-source marker leaves the whole marker
-    verbatim with ``unresolved`` True; defer until every id resolves or
-    end-of-stream forces a flush (dropping unresolved tokens)."""
+    """Any unresolved token in a multi-source marker leaves the whole marker verbatim with ``unresolved`` True until every id resolves or end-of-stream flushes."""
     cite = f"{CITE_START}cite{CITE_DELIM}known{CITE_DELIM}locator{CITE_STOP}"
     text = f"Pre {cite} post."
     citations = [{"source_id": "known", "url": "https://example.com/y"}]
diff --git a/studio/backend/tests/test_openai_code_execution.py b/studio/backend/tests/test_openai_code_execution.py
index e1b66b4050..63e94613ed 100644
--- a/studio/backend/tests/test_openai_code_execution.py
+++ b/studio/backend/tests/test_openai_code_execution.py
@@ -1,29 +1,13 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Unit tests for OpenAI's server-side `shell` tool translation in
+"""Unit tests for OpenAI's server-side `shell` tool translation in
 `_stream_openai_responses`.
 
-Covers:
-- Request body: ``enabled_tools=["code_execution"]`` on the OpenAI cloud
-  base_url appends ``{"type": "shell", "environment": {"type":
-  "container_auto"}}`` to ``tools``.
-- Container reuse: with ``openai_code_exec_container_id``, the outgoing
-  ``environment.type`` flips to ``"container_reference"`` and the id
-  propagates.
-- Cloud guard: code_execution on a non-cloud base_url (local
-  OpenAI-compat / ollama / llama.cpp / vLLM) does NOT add the shell tool,
-  avoiding a guaranteed 400 from those servers.
-- SSE translation: a `shell_call` + `shell_call_output` pair emits one
-  ``_toolEvent`` `tool_start` (`tool_name="code_execution"`,
-  `arguments.kind="bash"`) and one `tool_end` whose `result` is the
-  joined stdout from the shell_call_output entries.
-- Container surfacing: container_id from
-  `response.completed.container_id` is emitted as a synthetic
-  `container_ready` `_toolEvent` (only when it differs from the inbound id).
-- Stale-container handling: 400 with "container expired" body emits a
-  `container_invalidated` event before propagating the error.
+Covers: request body shaping (container_auto, container_reference), the cloud
+guard (no shell tool on non-cloud base_urls), SSE translation of a
+shell_call/shell_call_output pair into tool_start/tool_end events, container_id
+surfacing as container_ready, and stale-container invalidation.
 """
 
 import asyncio
@@ -191,8 +175,7 @@ def test_shell_tool_refused_for_non_cloud_base_url(monkeypatch):
     _drive(run())
 
     tools = captured["body"].get("tools") or []
-    # Shell tool must NOT leak to local OpenAI-compat servers — they 400
-    # on the unknown tool type.
+    # Shell tool must not leak to local OpenAI-compat servers (they 400 on it).
     assert all(t.get("type") != "shell" for t in tools)
 
 
@@ -265,9 +248,8 @@ def test_shell_call_emits_tool_start_and_end(monkeypatch):
     assert len(ends) == 1
     assert starts[0]["tool_name"] == "code_execution"
     assert starts[0]["tool_call_id"] == "scall_1"
-    # `_server_tool: True` marks a synthetic builtin: stamped onto every
-    # provider-side tool_start so the frontend serializer can tell hosted
-    # tools from user-declared functions on history replay.
+    # `_server_tool: True` marks a synthetic builtin so the frontend can tell
+    # hosted tools from user-declared functions on history replay.
     assert starts[0]["arguments"] == {"kind": "bash", "command": "ls -la", "_server_tool": True}
     assert ends[0]["tool_call_id"] == "scall_1"
     assert "total 24" in ends[0]["result"]
@@ -391,10 +373,9 @@ def test_stale_container_emits_invalidated(monkeypatch):
 
 
 def test_expired_container_triggers_transparent_retry(monkeypatch):
-    """When OpenAI 400s with 'Container is expired' on a request that
-    carried container_reference, the streamer retries once with the
-    container field stripped. The user sees only container_invalidated,
-    then the normal stream from the retry — never an error line.
+    """On a 'Container is expired' 400 for a container_reference request, the
+    streamer retries once with the container stripped; the user sees only
+    container_invalidated then the retry stream, never an error line.
     """
     calls: list[dict] = []
 
@@ -407,8 +388,7 @@ def test_expired_container_triggers_transparent_retry(monkeypatch):
             if tool.get("type") == "shell":
                 shell_env_type = tool.get("environment", {}).get("type")
                 break
-        # First call has container_reference -> 400 expired.
-        # Retry omits container -> normal SSE stream.
+        # container_reference -> 400 expired; retry omits container -> normal stream.
         if shell_env_type == "container_reference":
             return httpx.Response(
                 400,
diff --git a/studio/backend/tests/test_openai_image_generation.py b/studio/backend/tests/test_openai_image_generation.py
index 39cf672dc1..ace57588d3 100644
--- a/studio/backend/tests/test_openai_image_generation.py
+++ b/studio/backend/tests/test_openai_image_generation.py
@@ -3,17 +3,11 @@
 
 """Unit tests for OpenAI Responses API image_generation tool wiring.
 
-The image_generation tool is a server-side Responses-API tool:
-``{type: "image_generation"}`` in the request's tools array; the result
-returns as an ``image_generation_call`` output item carrying the base64 image
-on ``result``. Studio translates that item into ``_toolEvent`` chunks
-(``tool_start`` with `kind:"image"`, ``tool_end`` with ``image_b64`` +
-``image_mime``) so the chat adapter renders the image inline.
-
-These tests pin: the tool is added to the outbound body only when the caller
-asks for it on a cloud OpenAI base; the SSE output_item.done for
-``image_generation_call`` produces the expected _toolEvent chunks; non-cloud
-bases drop the tool silently.
+The tool is a server-side Responses-API tool (``{type: "image_generation"}``);
+the result comes back as an ``image_generation_call`` output item, which Studio
+translates into ``_toolEvent`` chunks so the chat adapter renders it inline.
+Tests pin: the tool is added to the body only on a cloud OpenAI base when asked
+for, the done event produces the expected chunks, and non-cloud bases drop it.
 """
 
 import asyncio
diff --git a/studio/backend/tests/test_openai_responses_translation.py b/studio/backend/tests/test_openai_responses_translation.py
index 19d4959aa1..f7d7e83a43 100644
--- a/studio/backend/tests/test_openai_responses_translation.py
+++ b/studio/backend/tests/test_openai_responses_translation.py
@@ -193,7 +193,7 @@ def test_responses_sse_translates_to_chat_completions_chunks(monkeypatch):
 
     lines = _drive(run())
 
-    # Drop empty / non-data lines for assertion clarity.
+    # Keep only data lines for assertion clarity.
     data_lines = [line for line in lines if line.startswith("data:")]
     payloads = []
     for line in data_lines:
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index b9f086a4b9..4437bf2212 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -1,20 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
-"""
-Tests for the OpenAI /v1/chat/completions client-side tool pass-through.
+"""Tests for the OpenAI /v1/chat/completions client-side tool pass-through.
 
-Covers:
-- ChatCompletionRequest accepts standard OpenAI `tools` / `tool_choice` / `stop`.
-- ChatMessage accepts role="tool" with `tool_call_id` and role="assistant"
-  with `content: None` + `tool_calls`.
-- ChatCompletionRequest carries unknown fields via `extra="allow"`.
-- anthropic_tool_choice_to_openai() covers all four Anthropic shapes.
-- _build_passthrough_payload() honors a caller tool_choice, defaults to "auto".
-- _friendly_error() maps httpx transport errors to a "Lost connection"
-  message so passthrough failures are legible instead of bare 500s.
-
-No running server or GPU required.
+Covers ChatMessage tool/assistant roles, ChatCompletionRequest tool fields and
+extra="allow", anthropic_tool_choice_to_openai, _build_passthrough_payload
+tool_choice propagation, and _friendly_error's httpx-to-"Lost connection"
+mapping. No server or GPU required.
 """
 
 import os
@@ -303,23 +295,16 @@ class TestChatCompletionRequestToolFields:
         assert req.session_id == "abc"
 
     def test_stream_defaults_false_matching_openai_spec(self):
-        # OpenAI's /v1/chat/completions spec defaults `stream` to false.
-        # Studio previously defaulted to true, breaking naive curl clients
-        # (and .NET / System.Text.Json SDKs per #5047) that omit `stream`:
-        # they expect a JSON blob, got SSE. Pin the corrected default so it
-        # can't silently regress.
+        # OpenAI defaults `stream` to false. Studio used to default true,
+        # breaking naive curl/.NET clients (#5047) that omit it. Pin the fix.
         req = self._make()
         assert req.stream is False
 
     def test_post_without_stream_field_decodes_to_stream_false_over_http(self, monkeypatch):
-        # Wire-level guard for the same default: a POST body that omits
-        # `stream` (the exact shape naive curl / .NET clients send) must
-        # deserialise into stream=False *and* return `application/json`, never
-        # `text/event-stream`. Mounts the real `routes.inference.router` so
-        # this catches middleware/aliasing regressions on the actual endpoint
-        # (e.g. a request layer that injects stream=True before pydantic builds
-        # the model). Backends are bypassed via `provider_type` + a stubbed
-        # external provider proxy.
+        # Wire-level guard: a POST body omitting `stream` must deserialise to
+        # stream=False and return application/json, never text/event-stream.
+        # Mounts the real router to catch middleware/aliasing regressions;
+        # backends are bypassed via provider_type + a stubbed proxy.
         from fastapi import FastAPI
         from fastapi.responses import JSONResponse
         from fastapi.testclient import TestClient
@@ -482,13 +467,10 @@ class TestBuildPassthroughPayloadToolChoice:
 
 
 class TestFriendlyErrorHttpx:
-    """The async pass-through helpers talk to llama-server via httpx.
-    When the subprocess is down, httpx raises RequestError subclasses whose
-    string form (``"All connection attempts failed"``, ``"[Errno 111]
-    Connection refused"``, ...) lacks the ``"Lost connection to llama-server"``
-    substring the sync path uses, so the old substring-only `_friendly_error`
-    returned a useless generic message. These tests pin the new
-    isinstance-based mapping.
+    """When llama-server is down, httpx RequestError strings lack the
+    "Lost connection to llama-server" substring the sync path keys off, so the
+    old substring-only `_friendly_error` returned a useless generic message.
+    These tests pin the new isinstance-based mapping.
     """
 
     def _req(self):
diff --git a/studio/backend/tests/test_pricing_edge.py b/studio/backend/tests/test_pricing_edge.py
index 4197d8c9f0..1fcc428f90 100644
--- a/studio/backend/tests/test_pricing_edge.py
+++ b/studio/backend/tests/test_pricing_edge.py
@@ -95,7 +95,6 @@ def test_prefix_match_still_resolves_legit_dated_snapshots():
 
 
 def test_explicit_zero_input_tokens_wins_over_stale_prompt_tokens():
-    # Input-side mirror of the output zero-precedence test.
     out = calculate_cost(
         "openai",
         "gpt-5.5",
diff --git a/studio/backend/tests/test_providers_api.py b/studio/backend/tests/test_providers_api.py
index f343cef635..5e24ed752d 100644
--- a/studio/backend/tests/test_providers_api.py
+++ b/studio/backend/tests/test_providers_api.py
@@ -72,11 +72,9 @@ def _url(path: str) -> str:
 
 
 def _parse_sse_stream(response: requests.Response) -> tuple[str, bool]:
-    """
-    Read an SSE response, return (assembled_text, saw_done).
+    """Read an SSE response, return (assembled_text, saw_done).
 
-    Each chunk is JSON with choices[0].delta.content; stream ends with
-    `data: [DONE]`.
+    Each chunk is JSON with choices[0].delta.content; stream ends at `data: [DONE]`.
     """
     reply_parts: list[str] = []
     saw_done = False
@@ -110,19 +108,12 @@ def _parse_sse_stream(response: requests.Response) -> tuple[str, bool]:
 
 @pytest.fixture(scope = "session")
 def auth_headers() -> dict[str, str]:
-    """
-    Log in once per session and return auth headers.
+    """Log in once per session and return auth headers.
 
-    On a fresh install the bootstrap password forces a change
-    (must_change_password=True); calls with that token return 403 "Password
-    change required". This fixture detects that, auto-completes the change, and
-    re-logs in so other tests get a usable token.
-
-    The auto-change new password is:
-        STUDIO_TEST_NEW_PASSWORD  (env var, optional)
-        or PASSWORD + "-test"     (derived default)
-
-    On the second run, set STUDIO_TEST_PASSWORD to the new password.
+    On a fresh install the bootstrap password forces a change; this fixture
+    detects must_change_password, auto-completes the change (new password =
+    STUDIO_TEST_NEW_PASSWORD or PASSWORD + "-test"), and re-logs in. On the
+    second run, set STUDIO_TEST_PASSWORD to the new password.
     """
     assert PASSWORD, (
         "STUDIO_TEST_PASSWORD is not set.\n"
@@ -140,8 +131,8 @@ def auth_headers() -> dict[str, str]:
     assert token, "access_token is empty"
 
     if body.get("must_change_password"):
-        # Bootstrap token only works with /api/auth/change-password; auto-complete
-        # the forced change so the rest of the tests get a full token.
+        # Bootstrap token only works with change-password; auto-complete the
+        # forced change so the rest of the tests get a full token.
         new_password = os.getenv("STUDIO_TEST_NEW_PASSWORD") or f"{PASSWORD}-test"
         change_resp = requests.post(
             _url("/api/auth/change-password"),
@@ -173,12 +164,10 @@ def public_key_pem(auth_headers: dict[str, str]) -> str:
 
 @pytest.fixture(scope = "session")
 def vision_image_data_url() -> str:
-    """
-    Download the sloth image once per session as a base64 data URI.
+    """Download the sloth image once per session as a base64 data URI.
 
-    A data URI sends the image inline to every provider; Gemini's
-    OpenAI-compatible layer does not fetch external HTTP URLs, so raw image_url
-    links silently produce empty Gemini replies.
+    A data URI sends the image inline; Gemini's OpenAI-compatible layer doesn't
+    fetch external HTTP URLs, so raw image_url links give empty Gemini replies.
     """
     resp = requests.get(_VISION_IMAGE_URL, timeout = 30)
     resp.raise_for_status()
@@ -189,11 +178,10 @@ def vision_image_data_url() -> str:
 
 @pytest.fixture(scope = "session")
 def encrypt_key(public_key_pem: str):
+    """Return encrypt_key(plaintext) -> base64 RSA-OAEP ciphertext.
+
+    Uses the backend's RSA public key; mirrors the frontend.
     """
-    Return encrypt_key(plaintext: str) -> str (base64 RSA-OAEP ciphertext).
-    Uses the backend's RSA public key — mirrors the frontend.
-    """
-    # Load RSA public key from PEM
     pem_bytes = public_key_pem.encode("utf-8")
     rsa_pub = serialization.load_pem_public_key(pem_bytes)
 
@@ -554,12 +542,10 @@ class TestVisionInference:
 
 class TestLocalInferenceUnaffected:
     def test_chat_without_provider(self, auth_headers: dict[str, str]):
-        """
-        POST /v1/chat/completions without provider fields must not return 422 or 500.
+        """POST /v1/chat/completions without provider fields must not 422/500.
 
-        200 = local model loaded and responded.
-        503 = no model loaded (expected in test env — fine).
-        Any other 4xx/5xx (except 503) = request-handling regression.
+        200 = local model responded; 503 = no model loaded (fine in tests);
+        any other 4xx/5xx = request-handling regression.
         """
         resp = requests.post(
             _url("/v1/chat/completions"),
diff --git a/studio/backend/tests/test_pytorch_mirror.py b/studio/backend/tests/test_pytorch_mirror.py
index f1574fb31e..59842214ef 100644
--- a/studio/backend/tests/test_pytorch_mirror.py
+++ b/studio/backend/tests/test_pytorch_mirror.py
@@ -20,7 +20,7 @@ OFFICIAL_URL = "https://download.pytorch.org/whl"
 
 def _reload_whl_base(monkeypatch, mirror_value = None):
     """(Re-)import install_python_stack with a controlled env, return _PYTORCH_WHL_BASE."""
-    # Drop cached module so the module-level assignment re-executes
+    # Drop cached module so the module-level assignment re-executes.
     sys.modules.pop("install_python_stack", None)
 
     if mirror_value is None:
@@ -28,7 +28,7 @@ def _reload_whl_base(monkeypatch, mirror_value = None):
     else:
         monkeypatch.setenv("UNSLOTH_PYTORCH_MIRROR", mirror_value)
 
-    # Add the script's directory to sys.path for import
+    # Add the script's directory to sys.path for import.
     script_dir = str(_INSTALL_SCRIPT.parent)
     monkeypatch.syspath_prepend(script_dir)
 
diff --git a/studio/backend/tests/test_recommended_folders_permission.py b/studio/backend/tests/test_recommended_folders_permission.py
index ffe8c65ac0..33a457755e 100644
--- a/studio/backend/tests/test_recommended_folders_permission.py
+++ b/studio/backend/tests/test_recommended_folders_permission.py
@@ -59,8 +59,7 @@ _skip_as_root = pytest.mark.skipif(
 
 
 def test_helper_exists_in_source():
-    # Guard against a refactor silently dropping the helper the fix needs
-    # (the extractor would then raise StopIteration).
+    # Guard against a refactor silently dropping the helper the fix needs.
     assert callable(safe_is_dir)
 
 
diff --git a/studio/backend/tests/test_responses_api.py b/studio/backend/tests/test_responses_api.py
index 6ef874bd98..693e832113 100644
--- a/studio/backend/tests/test_responses_api.py
+++ b/studio/backend/tests/test_responses_api.py
@@ -1,11 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
 
-"""
-Tests for OpenAI Responses API schemas and input normalisation.
-No running server or GPU required -- validates the Pydantic models and
-the _normalise_responses_input helper.
-"""
+"""Tests for OpenAI Responses API Pydantic schemas and the
+_normalise_responses_input helper. No server or GPU required."""
 
 import sys
 import os
@@ -33,9 +30,8 @@ from models.inference import (
 )
 
 
-# ── _normalise_responses_input: copied from routes/inference.py ──
-# Can't import routes.inference directly: routes/__init__.py pulls in
-# heavy deps (structlog/twisted/torch). This is a direct copy for tests.
+# Copied from routes/inference.py: can't import it directly because
+# routes/__init__.py pulls in heavy deps (structlog/twisted/torch).
 
 
 def _normalise_responses_input(payload: ResponsesRequest) -> list:
diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.py
index 6b2c6aa84f..21edabd142 100644
--- a/studio/backend/tests/test_rocm_oom_guard.py
+++ b/studio/backend/tests/test_rocm_oom_guard.py
@@ -3,16 +3,12 @@
 
 """Unit tests for _rocm_classify_unified_memory (ROCm OOM-guard classifier).
 
-Three classification paths:
-  Path 1 – canonical gcnArchName attribute present.
-  Path 2 – gcnArchName absent, alternate-spelling attribute present.
-  Path 3 – ALL arch attrs absent; falls back to device-name substring match.
+Three paths: (1) canonical gcnArchName, (2) alternate-spelling attr, (3) all
+arch attrs absent -> device-name substring match.
 
-Regression: Strix Halo (gfx1151) misclassified as discrete on AMD SDK / Radeon
-wheels that set props.name = "Radeon 8060S Graphics" but no gcnArchName attr.
-Without the 8060s/8050s name patterns the fallback returned is_unified=False,
-applying 0.90 instead of 0.80 and leaving only ~12.8 GiB OS headroom on a
-128 GiB unified-memory pool.
+Regression: Strix Halo (gfx1151) was misclassified as discrete on Radeon wheels
+that set props.name="Radeon 8060S Graphics" but no gcnArchName, applying the
+wrong headroom factor on a 128 GiB unified-memory pool.
 """
 
 from __future__ import annotations
diff --git a/studio/backend/tests/test_safetensors_capability_advertise.py b/studio/backend/tests/test_safetensors_capability_advertise.py
index 1e40f376f3..1e8fb9e2b2 100644
--- a/studio/backend/tests/test_safetensors_capability_advertise.py
+++ b/studio/backend/tests/test_safetensors_capability_advertise.py
@@ -1,10 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Capability advertisement contract: classifier honesty, worker→orchestrator
-IPC hop, route-layer end-to-end. Pure helpers + fakes; no torch/transformers.
-"""
+"""Capability advertisement contract: classifier honesty, worker->orchestrator
+IPC hop, route-layer end-to-end. Pure helpers + fakes; no torch/transformers."""
 
 from __future__ import annotations
 
@@ -128,10 +126,9 @@ def test_detect_safetensors_features_gptoss_disables_tools():
     assert flags["supports_tools"] is False
 
 
-# Llama-3 / Mistral templates advertise tools but emit calls in
-# <|python_tag|> / [TOOL_CALLS] format -- not the <tool_call> / <function=
-# our parser understands. The route helper must not flip supports_tools=True
-# for those families, else the UI enables a pill the agentic loop can't honour.
+# Llama-3 / Mistral advertise tools but emit <|python_tag|> / [TOOL_CALLS],
+# which our parser can't read. The route helper must not flip supports_tools=True
+# for them, else the UI enables a pill the agentic loop can't honour.
 
 LLAMA3_TEMPLATE = """
 {%- if tools %}
@@ -205,10 +202,9 @@ def test_detect_safetensors_features_function_xml_format_keeps_tools_on():
     assert flags["supports_tools"] is True
 
 
-# Qwen3.5 family pins -- the live GGUF + safetensors templates from the
-# unsloth/Qwen3.5-0.8B(-GGUF) repos both wrap tool calls as
-# ``<tool_call>\n<function=name>...``. Faithful slice so the classifier
-# never silently regresses for this family.
+# Qwen3.5 family pin: the live GGUF + safetensors templates both wrap tool
+# calls as ``<tool_call>\n<function=name>...``. Faithful slice so the
+# classifier never silently regresses for this family.
 
 QWEN35_TOOL_INSTRUCTION = (
     "{%- if tools %}\n"
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index 526ea2d19f..55d2a48df1 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -1,29 +1,13 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Tests for the safetensors agentic tool loop.
+"""Tests for the safetensors agentic tool loop.
 
-Covers the shared ``tool_call_parser`` helpers and the cumulative-text state
-machine in ``safetensors_agentic.run_safetensors_tool_loop``. The loop runs
-against hand-crafted fake single-turn generators, so no model load is needed;
-the tests finish in CI within a few seconds.
-
-Edge cases covered:
-* Plain answers (no tool calls) flush full content.
-* Single ``<tool_call>{json}</tool_call>`` triggers the tool and re-enters.
-* Single ``<function=name>...`` XML form triggers the same path.
-* Truncated unclosed ``<tool_call>`` is still parsed.
-* Tool result is fed back as ``role=tool`` for the next iteration.
-* Bad JSON inside ``<tool_call>`` does not raise and (when healed) routes as a
-  ``{"query": ...}`` web search call.
-* Duplicate tool calls produce a synthetic "do not repeat" result the 2nd time.
-* ``__IMAGES__`` sentinel is stripped before the model sees the result.
-* Tool execution errors are tagged so the model gets a nudge but the loop keeps
-  streaming.
-* Cancel is honoured between iterations.
-* ``max_tool_iterations`` cap is respected and a final-answer attempt closes the
-  stream cleanly.
+Covers the ``tool_call_parser`` helpers and the cumulative-text state machine in
+``run_safetensors_tool_loop``, run against fake single-turn generators (no model
+load). Edge cases: plain answers, JSON and XML tool-call forms, truncated/unclosed
+calls, tool-result feedback, bad-JSON heal, duplicate-call short-circuit,
+``__IMAGES__`` sentinel stripping, executor errors, cancel, and the iteration cap.
 """
 
 import threading
@@ -85,9 +69,8 @@ class TestParser:
         assert "ls -la" in result[0]["function"]["arguments"]
 
     def test_code_with_embedded_xml(self):
-        # A code parameter contains the literal </parameter>. Must not truncate
-        # the value: the parser uses end-of-body as the only boundary for
-        # single-parameter calls.
+        # A code parameter with a literal </parameter> must not truncate: the
+        # parser uses end-of-body as the only boundary for single-param calls.
         text = (
             "<function=python><parameter=code>html = '<a></a>'\n"
             "print('hi')</parameter></function>"
@@ -266,13 +249,13 @@ class TestLoopBasic:
     def test_single_tool_then_answer(self):
         loop, exec_fn = _make_loop(
             turns = [
-                # : tool call only.
+                # Tool call only.
                 [
                     '<tool_call>{"name":"web_search",',
                     '"arguments":{"query":"weather"}}',
                     "</tool_call>",
                 ],
-                # : final answer.
+                # Final answer.
                 ["The ", "weather is ", "sunny."],
             ],
             exec_results = ["Sunny and 22C"],
@@ -411,13 +394,10 @@ class TestLoopBasic:
         assert exec_fn.calls == [("web_search", {"query": "x"})]
 
     def test_bad_json_healed_to_query(self):
-        # Tool call with non-JSON string arguments. With auto_heal_tool_calls,
-        # the string routes as {"query": ...}.
+        # Non-JSON string arguments heal to {"query": ...} under auto_heal_tool_calls.
         loop, exec_fn = _make_loop(
             turns = [
-                # JSON inside the tool call is well-formed, but ``arguments`` is
-                # a string that ``_coerce_arguments`` cannot parse as JSON, so
-                # the heal path runs.
+                # ``arguments`` is a string _coerce_arguments can't parse, so heal runs.
                 ['<tool_call>{"name":"web_search","arguments":"hello world"}</tool_call>'],
                 ["ok"],
             ],
@@ -430,8 +410,8 @@ class TestLoopBasic:
 
 class TestLoopBehaviour:
     def test_duplicate_tool_call_synthetic_result(self):
-        # Two identical successful calls in a row: the second is short-circuited
-        # with a "do not repeat" message and execute_tool runs only once.
+        # Two identical calls in a row: the second short-circuits with a "do not
+        # repeat" message; execute_tool runs once.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
@@ -448,9 +428,8 @@ class TestLoopBehaviour:
         assert "do not repeat" in tool_end_events[1]["result"].lower()
 
     def test_image_sentinel_stripped_from_model_feed(self):
-        # The tool result's frontend image sentinel must be stripped before
-        # being fed into the next turn, BUT the tool_end event still carries the
-        # raw result for the UI.
+        # The image sentinel is stripped before the next turn, but tool_end still
+        # carries the raw result for the UI.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"python","arguments":{"code":"plot()"}}</tool_call>'],
@@ -556,8 +535,7 @@ class TestLoopControl:
     def test_cancel_event_breaks_loop(self):
         cancel = threading.Event()
         cancel.set()
-        # Even with a fake stream that emits tool calls, the loop must bail
-        # before invoking execute_tool when cancel is set.
+        # With cancel set, the loop bails before invoking execute_tool.
         exec_fn = FakeExecuteTool([])
         events = list(
             run_safetensors_tool_loop(
@@ -578,9 +556,9 @@ class TestLoopControl:
         # asking for tools, then emits a final-attempt round.
         loop, exec_fn = _make_loop(
             turns = [
-                # : tool call (executes once)
+                # Tool call (executes once).
                 ['<tool_call>{"name":"web_search","arguments":{"query":"a"}}</tool_call>'],
-                # : model gives a final answer when nudged.
+                # Model gives a final answer when nudged.
                 ["here is the final answer"],
             ],
             exec_results = ["result"],
@@ -613,16 +591,13 @@ class TestStatusFormatting:
 
 class TestProseMentioningToolCall:
     def test_assistant_prose_with_literal_tool_call_text_survives(self):
-        # Regression: if assistant text legitimately mentions ``<tool_call>`` as
-        # a literal string and the parser finds no actual call, the loop must
-        # surface the full content instead of stripping everything past the
-        # literal marker.
+        # Regression: prose that mentions a literal ``<tool_call>`` (no real call)
+        # must surface in full, not be stripped past the marker.
         loop, exec_fn = _make_loop(
             turns = [
-                # : a real tool call so the loop moves to
-                # .
+                # A real tool call so the loop advances a turn.
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
-                # : prose that mentions the literal text.
+                # Prose that mentions the literal text.
                 ["the docs say <tool_call> means an LLM tool call wrapper"],
             ],
             exec_results = ["result"],
@@ -636,9 +611,8 @@ class TestProseMentioningToolCall:
         ), f"prose mentioning <tool_call> should not be truncated; got {final!r}"
 
     def test_tool_result_with_tool_call_text_does_not_retrigger(self):
-        # Tool result text contains the literal ``<tool_call>`` string. The loop
-        # must parse only the MODEL output, not the tool result, so we see
-        # exactly one call.
+        # A literal ``<tool_call>`` in the tool result must not re-trigger: the
+        # loop parses only model output, so exactly one call.
         loop, exec_fn = _make_loop(
             turns = [
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
diff --git a/studio/backend/tests/test_sandbox_tools.py b/studio/backend/tests/test_sandbox_tools.py
index 1841d084b9..24b1da1772 100644
--- a/studio/backend/tests/test_sandbox_tools.py
+++ b/studio/backend/tests/test_sandbox_tools.py
@@ -223,11 +223,8 @@ class TestUploadDenylist:
 
 
 class TestSandboxEnvIsolation:
-    """The sandbox subprocess env is built from a whitelist, not by stripping.
-
-    Confirm every credential-shaped parent var is absent regardless of the
-    operator's process config. Covers Linux/macOS/WSL/Windows shapes.
-    """
+    """Sandbox env is built from a whitelist, so credential-shaped parent
+    vars stay absent regardless of operator config (Linux/macOS/WSL/Windows)."""
 
     _SECRET_KEYS = (
         # HF + ML tooling
@@ -346,12 +343,8 @@ class TestMaxBodyDefault:
 
 
 class TestBashBlocklistPosition:
-    """The blocklist must fire at command position only.
-
-    Pre-fix, the per-token loop fired on any token, so `grep -r curl .`
-    and `echo source` were rejected. The position-anchored regex plus a
-    shlex-aware command-position-only token check fixes this.
-    """
+    """The blocklist must fire at command position only, so args like
+    `grep -r curl .` and `echo source` are not falsely rejected."""
 
     @staticmethod
     def _find():
@@ -464,9 +457,8 @@ class TestBashBlocklistPosition:
 
 
 class TestHfUploadImportGate:
-    """HfApi-style upload-method blocking requires an HF import in scope;
-    otherwise paramiko / boto3 / internal SDKs with the same method names
-    false-positive."""
+    """Upload-method blocking requires an HF import in scope, so paramiko /
+    boto3 / internal SDKs with the same method names don't false-positive."""
 
     def test_paramiko_upload_file_allowed_without_hf_import(self):
         _ok("import paramiko; sftp=None; sftp.upload_file('a','b')")
@@ -523,10 +515,9 @@ class TestHfUploadImportGate:
 
 
 class TestHfUploadSandboxLocalPaths:
-    """The HF upload gate allows only files already in the sandbox workdir.
-    Absolute paths, `..` traversal, home expansion, and Windows drive
-    letters are rejected — the LLM could use them to lift secrets from
-    outside the sandbox."""
+    """HF upload gate allows only files in the sandbox workdir. Absolute paths,
+    `..` traversal, home expansion, and Windows drives are rejected (they could
+    lift secrets from outside the sandbox)."""
 
     def test_relative_literal_allowed(self):
         _ok(
@@ -673,11 +664,9 @@ class TestHfUploadSandboxLocalPaths:
 
 
 class TestHfUploadEnvAndSecretLeakBlock:
-    """The HF upload gate rejects any positional / keyword arg sourced from
-    `os.environ` / `os.getenv` / subprocess env reads. `_build_safe_env`
-    strips HF_TOKEN/WANDB/AWS for the sandbox shell, but a Python script
-    can still reach the parent env if it bypasses the safe-env wrapper at
-    the source -- so block statically."""
+    """HF upload gate rejects any arg sourced from os.environ / os.getenv /
+    subprocess env reads, since a script can reach the parent env directly
+    despite the safe-env shell wrapper."""
 
     def test_path_from_os_environ_subscript_blocked(self):
         _blocked(
diff --git a/studio/backend/tests/test_studio_api.py b/studio/backend/tests/test_studio_api.py
index c40729d9a8..27f695b744 100644
--- a/studio/backend/tests/test_studio_api.py
+++ b/studio/backend/tests/test_studio_api.py
@@ -65,17 +65,17 @@ import urllib.request
 from pathlib import Path
 
 
-# ── Configuration ────────────────────────────────────────────────────
+# Configuration
 
 DEFAULT_MODEL = "unsloth/Qwen3-1.7B-GGUF"
 DEFAULT_VARIANT = "UD-Q4_K_XL"
 PORT = 18222  # high port unlikely to collide
 HOST = "127.0.0.1"
-STARTUP_TIMEOUT = 120  # seconds to wait for banner
+STARTUP_TIMEOUT = 120  # seconds
 LOG_FILE = Path(__file__).resolve().parent.parent.parent.parent / "temp" / "test_studio_api.log"
 
 
-# ── Helpers ──────────────────────────────────────────────────────────
+# Helpers
 
 
 def _http(
@@ -125,7 +125,7 @@ def _stream_http(
         return exc.code, []
 
 
-# ── Test functions ───────────────────────────────────────────────────
+# Test functions
 
 
 def test_help_output():
@@ -265,19 +265,13 @@ def test_curl_with_tools(base_url: str, api_key: str):
     print(f"  PASS  curl with tools: {len(chunks)} chunks, {len(full)} chars content")
 
 
-# ── Standard OpenAI function-calling pass-through tests ─────────────
+# Standard OpenAI function-calling pass-through tests.
 #
-# Regression coverage for unslothai/unsloth#4999: Studio's
-# /v1/chat/completions used to silently strip standard OpenAI `tools` and
-# `tool_choice` fields, so clients (opencode, Claude Code, Cursor,
-# Continue, ...) never got structured tool_calls back. These tests exercise
-# the client-side pass-through path that forwards those fields to
-# llama-server verbatim.
-#
-# They require a tool-capable GGUF (``supports_tools=True`` — e.g. Qwen3,
-# Qwen2.5-Coder, Llama-3.1-Instruct). The default test model
-# ``unsloth/Qwen3-1.7B-GGUF`` advertises tool support via its chat template
-# metadata.
+# Regression coverage for unslothai/unsloth#4999: /v1/chat/completions used
+# to strip standard OpenAI `tools`/`tool_choice`, so clients never got
+# structured tool_calls back. These exercise the pass-through that forwards
+# those fields to llama-server verbatim. Require a tool-capable GGUF
+# (supports_tools=True); the default unsloth/Qwen3-1.7B-GGUF qualifies.
 
 _WEATHER_TOOL = {
     "type": "function",
@@ -532,7 +526,7 @@ def test_no_key_rejected(base_url: str):
     print(f"  PASS  no API key rejected ({status})")
 
 
-# ── Anthropic SSE helper ─────────────────────────────────────────────
+# Anthropic SSE helper
 
 
 def _stream_anthropic_http(
@@ -580,7 +574,7 @@ def _collect_anthropic_text(events: list[tuple[str, dict]]) -> str:
     return "".join(parts)
 
 
-# ── Anthropic /v1/messages test functions ────────────────────────────
+# Anthropic /v1/messages test functions
 
 
 def test_anthropic_basic(base_url: str, api_key: str):
@@ -763,7 +757,7 @@ def test_anthropic_tool_choice_any(base_url: str, api_key: str):
     )
 
 
-# ── Server lifecycle ─────────────────────────────────────────────────
+# Server lifecycle
 
 
 def _start_server(model: str, variant: str | None) -> tuple[subprocess.Popen, str]:
@@ -837,7 +831,7 @@ def _kill_server(proc: subprocess.Popen):
         proc.wait(timeout = 5)
 
 
-# ── Main ─────────────────────────────────────────────────────────────
+# Main
 
 
 def main():
@@ -870,11 +864,11 @@ def main():
             failed += 1
             print(f"  ERROR {fn.__name__}: {type(exc).__name__}: {exc}")
 
-    # ── 1. --help (no server needed) ────────────────────────────
+    # 1. --help (no server needed)
     print("\n[1/16] Testing --help output")
     run_test(test_help_output)
 
-    # ── 2-16. Start server and run API tests ─────────────────────────
+    # 2-16. Start server and run API tests
     print(f"\nStarting server: {args.model} (variant={args.gguf_variant}) on port {PORT}...")
     proc = None
     try:
@@ -929,14 +923,14 @@ def main():
 
     except RuntimeError as exc:
         print(f"\nFATAL: Server failed to start: {exc}")
-        failed += 16  # count remaining tests as failed
+        failed += 16  # remaining tests count as failed
     finally:
         if proc:
             print("\nStopping server...")
             _kill_server(proc)
             print("Server stopped.")
 
-    # ── Summary ──────────────────────────────────────────────────────
+    # Summary
     total = passed + failed
     print(f"\n{'=' * 40}")
     print(f"Results: {passed}/{total} passed, {failed} failed")
diff --git a/studio/backend/tests/test_studio_train_validation.py b/studio/backend/tests/test_studio_train_validation.py
index ed33c07689..0ffecb3ce4 100644
--- a/studio/backend/tests/test_studio_train_validation.py
+++ b/studio/backend/tests/test_studio_train_validation.py
@@ -94,8 +94,7 @@ class TestVisionImageSizeCap:
 
     @pytest.mark.parametrize("value", ["++512", "--256", "+-+512", "+", "-"])
     def test_multi_sign_string_says_integer_not_raw(self, value):
-        # Regression guard: multi-sign strings must not leak int()'s raw
-        # "invalid literal" message; contract is "integer or null".
+        # Regression guard: multi-sign strings say "integer or null", not int()'s raw message.
         with pytest.raises(ValidationError) as exc:
             _check_field("vision_image_size", value)
         assert "integer or null" in str(exc.value)
@@ -103,8 +102,7 @@ class TestVisionImageSizeCap:
 
     @pytest.mark.parametrize("value", ["５１２", "٥١٢", "१०२४"])
     def test_unicode_digit_string_rejected(self, value):
-        # Full-width / Arabic-Indic / Devanagari digits must be rejected so the
-        # value reaching the backend equals the ASCII the user typed.
+        # Reject non-ASCII (full-width/Arabic-Indic/Devanagari) digits.
         with pytest.raises(ValidationError) as exc:
             _check_field("vision_image_size", value)
         assert "integer or null" in str(exc.value)
diff --git a/studio/backend/tests/test_training_worker_flash_attn.py b/studio/backend/tests/test_training_worker_flash_attn.py
index 5b7b70eefe..3c5d6cd094 100644
--- a/studio/backend/tests/test_training_worker_flash_attn.py
+++ b/studio/backend/tests/test_training_worker_flash_attn.py
@@ -370,9 +370,8 @@ def test_flash_linear_attention_install_includes_einops(monkeypatch):
 
     args = run_mock.call_args[0][0]
     assert "--no-deps" in args
-    # einops is declared by fla-core; packaging and triton are added
-    # because fla/utils.py imports them at load but neither is in
-    # fla-core's METADATA (an upstream FLA gap).
+    # packaging and triton are added because fla/utils.py imports them at load
+    # but neither is in fla-core's METADATA (an upstream FLA gap).
     assert "einops" in args
     assert "packaging" in args
     assert "triton" in args
@@ -491,14 +490,10 @@ def test_tilelang_backend_installs_pinned_pair_for_qwen3_5(monkeypatch):
 def test_tilelang_backend_reinstalls_when_tvm_ffi_is_broken(monkeypatch):
     """Repair path issues TWO pip calls:
 
-    Call 1 (repair): `--force-reinstall --no-deps apache-tvm-ffi==0.1.9`
-      — downgrades only the broken package. `--no-deps` is REQUIRED so
-      --force-reinstall doesn't cascade through apache-tvm-ffi's dep
-      graph and replace torch / the CUDA stack.
-
-    Call 2 (install): plain `apache-tvm-ffi==0.1.9 tilelang==0.1.8`
-      — resolves missing transitive deps (z3-solver, ml-dtypes) without
-      --force-reinstall, so it never replaces correct packages.
+    1 (repair): --force-reinstall --no-deps apache-tvm-ffi -- downgrades only
+      the broken package; --no-deps stops the cascade through its deps to torch.
+    2 (install): plain apache-tvm-ffi + tilelang -- resolves missing transitive
+      deps without --force-reinstall, so it never replaces correct packages.
     """
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
@@ -633,12 +628,9 @@ def test_tilelang_backend_swallows_install_failure(monkeypatch):
     assert any("failed" in s.lower() for s in statuses)
 
 
-# ───────────────────────────────────────────────────────────────────
-# Runtime hook on `is_flash_linear_attention_available` /
-# `is_causal_conv1d_available` — the primary gate in normal operation.
-# The substring tests above cover the
-# UNSLOTH_STUDIO_SKIP_FAST_PATH_HOOKS=1 fallback.
-# ───────────────────────────────────────────────────────────────────
+# Runtime hook on is_flash_linear_attention_available /
+# is_causal_conv1d_available -- the primary gate in normal operation. The
+# substring tests above cover the SKIP_FAST_PATH_HOOKS=1 fallback.
 
 
 class _FakeQueue(list):
@@ -840,10 +832,9 @@ def test_hook_clears_lru_cache_before_first_check(monkeypatch):
 
 
 def test_hook_rewrites_previously_imported_module_bindings(monkeypatch):
-    """Modeling files bind `is_flash_linear_attention_available` locally
-    via `from ... import is_X`. Reassigning the attribute on
-    transformers.utils.import_utils alone misses those local bindings;
-    the hook installer sweeps sys.modules and rebinds them.
+    """Modeling files bind is_flash_linear_attention_available locally via
+    `from ... import is_X`. Reassigning the attribute on import_utils alone
+    misses those; the hook installer sweeps sys.modules and rebinds them.
     """
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
@@ -905,8 +896,7 @@ def test_substring_fallback_unchanged_when_hook_skipped(monkeypatch):
     assert install_mock.call_count == 1
 
 
-# ───────────────────────────────────────────────────────────────────
-# Regression tests for the 10-reviewer findings:
+# Regression tests for the reviewer findings:
 #   1. tilelang Qwen-guard on hook path (non-Qwen FLA models)
 #   2. tilelang repair must not replace torch / CUDA stack
 #   3. hook must trust installer's bool, not transformers metadata
@@ -915,7 +905,6 @@ def test_substring_fallback_unchanged_when_hook_skipped(monkeypatch):
 #   6. tilelang skipped when FLA was skipped / failed
 #   7. tilelang repair runs when FLA is already True
 #   8. older FLA detected as stale and reinstalled
-# ───────────────────────────────────────────────────────────────────
 
 
 def test_hook_does_not_install_tilelang_for_model_outside_allowlist(monkeypatch):
@@ -1006,18 +995,9 @@ def test_tilelang_repair_does_not_touch_torch_cuda_stack(monkeypatch):
 
 
 def test_hook_trusts_installer_bool_not_metadata(monkeypatch):
-    """Finding #3: if pip exits 0 but deep imports fail, the installer
-    returns False; the hook must propagate False even if the underlying
-    `original()` gate (metadata-only) returns True after pip succeeds.
-
-    Mirrors the real bug:
-      1. Pre-install: gate=False (FLA absent) → wrapper triggers install.
-      2. Installer's `_flash_linear_attention_importable` post-probe fails,
-         so it returns False. (pip exited 0 but `import fla.modules` raised
-         due to a missing transitive dep.)
-      3. Post-install: gate would return True (metadata sees fla-core) — but
-         the wrapper must IGNORE that and use the installer's False so
-         transformers takes the torch fallback.
+    """Finding #3: if pip exits 0 but deep imports fail, the installer returns
+    False; the hook must propagate that False even if the metadata-only gate
+    returns True after pip succeeds, so transformers takes the torch fallback.
     """
     # Gate flips True after install (simulating "metadata sees fla").
     fla_gate = _make_fake_gate(initial_return = False)
@@ -1158,14 +1138,10 @@ def test_fla_installer_force_reinstalls_when_older_version_present(monkeypatch):
 
 
 def test_run_training_process_eagerly_installs_causal_conv1d_in_normal_mode():
-    """Finding #4: SSM modeling files use `lazy_load_kernel("causal-conv1d")`
-    and never call `is_causal_conv1d_available()`, so the hook won't fire
-    for them. The orchestrator must always run the eager substring
-    installer regardless of hook mode.
-
-    Reads the worker source rather than running the full orchestrator
-    (which needs a configured training config), asserting the eager
-    install is OUTSIDE the if/else hook branch.
+    """Finding #4: SSM modeling files use lazy_load_kernel and never call
+    is_causal_conv1d_available(), so the hook won't fire; the orchestrator must
+    always run the eager installer regardless of hook mode. Reads the worker
+    source and asserts the eager install is OUTSIDE the if/else hook branch.
     """
     import inspect
 
@@ -1184,13 +1160,10 @@ def test_run_training_process_eagerly_installs_causal_conv1d_in_normal_mode():
     )
 
 
-# ───────────────────────────────────────────────────────────────────
-# HIP / ROCm regression coverage (h34v3nzc0dex Strix Halo report).
+# HIP / ROCm regression coverage (Strix Halo report).
 # tilelang 0.1.8 has no HIP GEMM backend; FLA's TileLang dispatch crashes
-# mid-backward on AMD with "Unsupported target for gemm: hip". Fix: skip
-# install on HIP-built torch AND setdefault FLA_TILELANG=0 so an
-# already-installed tilelang isn't used either.
-# ───────────────────────────────────────────────────────────────────
+# mid-backward on AMD ("Unsupported target for gemm: hip"). Fix: skip install on
+# HIP torch AND setdefault FLA_TILELANG=0 so an existing tilelang isn't used.
 
 
 def test_tilelang_platform_unsupported_on_hip_torch(monkeypatch):
@@ -1420,16 +1393,12 @@ def test_model_wants_tilelang_normalizes_separators(monkeypatch):
         assert worker._model_wants_tilelang(variant) is True, variant
 
 
-# ────────────────────────────────────────────────────────────────────
-# HIP source-build gcc-install-dir coverage (h34v3nzc0dex Strix Halo).
-# Ubuntu 24.04 ships gcc-14's runtime dir without /usr/include/c++/14, so
-# ROCm clang-20 picks it and fails with 'cstdlib' file not found when
-# building causal-conv1d (or any HIP source fallback).
-# _hipcc_gcc_install_dir() finds a gcc dir with both halves; the
-# _install_package_wheel_first HIP branch passes it to clang via
-# HIPCC_COMPILE_FLAGS_APPEND. Parallel to bbf004c's setup.sh fix for the
-# llama.cpp HIP build (PR #5301).
-# ────────────────────────────────────────────────────────────────────
+# HIP source-build gcc-install-dir coverage (Strix Halo).
+# Ubuntu 24.04 ships gcc-14's runtime dir without /usr/include/c++/14, so ROCm
+# clang-20 picks it and fails ('cstdlib' not found) building causal-conv1d.
+# _hipcc_gcc_install_dir() finds a gcc dir with both halves; the HIP branch of
+# _install_package_wheel_first passes it via HIPCC_COMPILE_FLAGS_APPEND.
+# Parallels bbf004c's setup.sh fix for the llama.cpp HIP build (PR #5301).
 
 
 def _isdir_for_layout(*existing: str):
diff --git a/studio/backend/tests/test_transformers_version.py b/studio/backend/tests/test_transformers_version.py
index c8d6a4fd10..915bc4b13b 100644
--- a/studio/backend/tests/test_transformers_version.py
+++ b/studio/backend/tests/test_transformers_version.py
@@ -185,9 +185,8 @@ class TestNeedsTransformers5:
         config_cfg = {"model_name": "Qwen/Qwen3.5-9B"}
         (tmp_path / "config.json").write_text(json.dumps(config_cfg))
 
-        # ensure_transformers_version calls _resolve_base_model, but
-        # needs_transformers_5 just does substring matching. Test the
-        # full resolution chain here.
+        # needs_transformers_5 only does substring matching, so test the
+        # full resolution chain via _resolve_base_model here.
         resolved = _resolve_base_model(str(tmp_path))
         assert needs_transformers_5(resolved) is True
 
@@ -311,7 +310,6 @@ class TestGetTransformersTier:
 
     def test_550_checked_before_530(self):
         """5.5.0 is checked first — a model matching both gets 550."""
-        # Shouldn't happen in practice, but verifies priority.
         assert get_transformers_tier("gemma-4-model") == "550"
 
     def test_needs_transformers_5_compat(self):
diff --git a/studio/backend/tests/test_utils.py b/studio/backend/tests/test_utils.py
index 765235bd32..c66d56528a 100644
--- a/studio/backend/tests/test_utils.py
+++ b/studio/backend/tests/test_utils.py
@@ -1,20 +1,10 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Tests for utils/hardware and utils/utils — device detection, GPU memory, error formatting.
+"""Tests for utils/hardware and utils/utils: device detection, GPU memory, error formatting.
 
-Designed to pass on ANY platform:
-  • NVIDIA GPU  (CUDA backend, requires torch)
-  • Apple Silicon (MLX backend, requires mlx)
-  • CPU-only     (no GPU at all)
-
-No ML framework is imported at the top level; tests needing torch/mlx
-internals for mocking are skipped when unavailable.
-
-Run with:
-    cd studio/backend
-    python -m pytest tests/test_utils.py -v
+Passes on any platform (NVIDIA/CUDA, Apple Silicon/MLX, CPU-only). No ML framework
+is imported at top level; tests needing torch/mlx internals skip when unavailable.
 """
 
 import platform
@@ -189,9 +179,8 @@ class TestGetGpuMemoryInfo:
         assert "backend" in get_gpu_memory_info()
 
     def test_backend_matches_device(self):
-        # backend uses _backend_label, which swaps "cuda" for "rocm" on
-        # AMD hosts (IS_ROCM=True) for the UI label. On CUDA/XPU/MLX/CPU
-        # hosts it equals `get_device().value`.
+        # _backend_label swaps "cuda" for "rocm" on AMD hosts; elsewhere it
+        # equals get_device().value.
         from utils.hardware.hardware import _backend_label
         result = get_gpu_memory_info()
         assert result["backend"] == _backend_label(get_device())
diff --git a/studio/backend/tests/test_vision_cache.py b/studio/backend/tests/test_vision_cache.py
index 0df474b586..2fee50d842 100644
--- a/studio/backend/tests/test_vision_cache.py
+++ b/studio/backend/tests/test_vision_cache.py
@@ -20,9 +20,7 @@ from unittest.mock import patch, MagicMock
 
 import pytest
 
-# ---------------------------------------------------------------------------
 # sys.path + logger stub — same pattern as the rest of the test suite
-# ---------------------------------------------------------------------------
 _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
@@ -38,9 +36,7 @@ from utils.models.model_config import (
 )
 
 
-# ---------------------------------------------------------------------------
 # Helpers
-# ---------------------------------------------------------------------------
 
 
 @pytest.fixture(autouse = True)
@@ -51,9 +47,7 @@ def _clear_vision_cache():
     _vision_detection_cache.clear()
 
 
-# ---------------------------------------------------------------------------
 # Cache hit / miss tests
-# ---------------------------------------------------------------------------
 
 
 class TestVisionCacheHitMiss:
@@ -93,9 +87,7 @@ class TestVisionCacheStoresFalse:
         assert _vision_detection_cache[("org/text-only", None)] is False
 
 
-# ---------------------------------------------------------------------------
 # Subprocess path (transformers 5.x) caching
-# ---------------------------------------------------------------------------
 
 
 class TestVisionCacheSubprocessPath:
@@ -128,9 +120,7 @@ class TestVisionCacheSubprocessPath:
         mock_raw_config.assert_called_once_with("unsloth/gemma-4-E4B-it", hf_token = None)
 
 
-# ---------------------------------------------------------------------------
 # Exception handling — cache the False fallback
-# ---------------------------------------------------------------------------
 
 
 class TestVisionCacheOnException:
@@ -146,14 +136,10 @@ class TestVisionCacheOnException:
     def test_permanent_exception_result_cached(self, mock_needs_t5, mock_load_config):
         """A permanent failure (ValueError / RepositoryNotFoundError /
         GatedRepoError / JSONDecodeError) is caught, returns False, and
-        that False is cached so subsequent calls don't retry.
-
-        ValueError is used as the simplest cacheable exception type that
-        avoids importing huggingface_hub errors (whose module path
-        varies across versions)."""
-        # First call: load_model_config raises -> except branch -> False.
+        that False is cached so subsequent calls don't retry. ValueError
+        stands in as the simplest cacheable exception type."""
+        # First call raises -> False; second is a cache hit.
         assert is_vision_model("broken/model") is False
-        # Second call: cache hit, load_model_config not called again.
         assert is_vision_model("broken/model") is False
         mock_load_config.assert_called_once()
 
@@ -164,21 +150,15 @@ class TestVisionCacheOnException:
     @patch("utils.transformers_version.needs_transformers_5", return_value = False)
     def test_transient_exception_not_cached(self, mock_needs_t5, mock_load_config):
         """A transient failure (OSError, timeouts) returns None from
-        _is_vision_model_uncached, surfaces as False to the caller, and
-        is NOT cached, so the next call retries. Matches the documented
-        _vision_detection_cache behaviour: 'transient failures (network
-        errors, timeouts) are NOT cached so they can be retried.'"""
-        # First call: OSError -> uncached None -> caller returns False,
-        # no caching.
+        _is_vision_model_uncached, surfaces as False, and is NOT cached
+        so the next call retries."""
+        # First call: OSError -> False, not cached; second call retries.
         assert is_vision_model("broken/model") is False
-        # Second call: cache miss again, load_model_config called twice.
         assert is_vision_model("broken/model") is False
         assert mock_load_config.call_count == 2
 
 
-# ---------------------------------------------------------------------------
 # Direct detection path (non-transformers-5 models) caching
-# ---------------------------------------------------------------------------
 
 
 class TestVisionCacheDirectPath:
@@ -278,9 +258,7 @@ class TestVisionCacheDirectPath:
         mock_load_config.assert_called_once()
 
 
-# ---------------------------------------------------------------------------
 # hf_token handling
-# ---------------------------------------------------------------------------
 
 
 class TestVisionCacheTokenHandling:
diff --git a/studio/backend/tests/test_windows_gpu_detection_mock.py b/studio/backend/tests/test_windows_gpu_detection_mock.py
index 3a82541a31..88a1a28d14 100644
--- a/studio/backend/tests/test_windows_gpu_detection_mock.py
+++ b/studio/backend/tests/test_windows_gpu_detection_mock.py
@@ -34,12 +34,9 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
-# Stub heavy deps only if they fail to import -- unconditional stubs
-# would shadow the real module for sibling tests here. Use try-import,
-# not find_spec: loggers/__init__.py re-exports handlers.get_logger,
-# which does `from fastapi import Request, Response` at load. find_spec
-# returns a spec even without fastapi, but the import then raises. CI has
-# fastapi, so this is dev-machine ergonomics only.
+# Stub heavy deps only if they fail to import (unconditional stubs would shadow
+# the real module for sibling tests). Use try-import, not find_spec: loggers
+# imports fastapi at load, so find_spec succeeds but the import then raises.
 import importlib as _importlib  # noqa: E402
 
 
@@ -131,9 +128,7 @@ REAL_PIP_NVIDIA_WHEEL_LAYOUTS = {
 
 
 def _populate_studio_venv(prefix: Path) -> None:
-    """Lay out fake nvidia + torch wheels in <prefix>/Lib/site-packages
-    matching real win_amd64 layouts. Contents are stub bytes; only
-    directory structure matters."""
+    """Lay out fake nvidia + torch wheels matching real win_amd64 layouts (stub bytes)."""
     site = prefix / "Lib" / "site-packages"
     for rel, dlls in REAL_PIP_NVIDIA_WHEEL_LAYOUTS.items():
         d = site / Path(rel)
@@ -147,8 +142,7 @@ def _populate_studio_venv(prefix: Path) -> None:
 
 
 def _populate_studio_install(install_dir: Path, runtime: str = "13.1") -> None:
-    """Lay out install_dir/build/bin/Release/ as #5322 leaves it: main
-    archive payload + cudart bundle overlay."""
+    """Lay out install_dir/build/bin/Release/ as #5322 leaves it: payload + cudart overlay."""
     rel = install_dir / "build" / "bin" / "Release"
     rel.mkdir(parents = True, exist_ok = True)
     for fn in (
@@ -172,9 +166,7 @@ def _build_path_dirs_like_start_llama_server(
     prefix: Path,
     cuda_path: str = "",
 ) -> list[str]:
-    """Path-friendly wrapper around _build_windows_path_dirs. Asserting
-    against the real staticmethod (not a hand-copy) is the point: if the
-    win32 PATH order drops _windows_pip_nvidia_dll_dirs, tests fail."""
+    """Wrapper around the real _build_windows_path_dirs staticmethod."""
     return LlamaCppBackend._build_windows_path_dirs(str(binary_dir), str(prefix), cuda_path)
 
 
diff --git a/studio/backend/utils/cache_cleanup.py b/studio/backend/utils/cache_cleanup.py
index 4e582ae926..210735973d 100644
--- a/studio/backend/utils/cache_cleanup.py
+++ b/studio/backend/utils/cache_cleanup.py
@@ -1,14 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Utility for cleaning up the Unsloth compiled cache directory.
+"""Clean up the Unsloth compiled cache directory.
 
-unsloth_compiled_cache is created by unsloth_zoo/compiler.py during
-FastModel.from_pretrained() and holds model-type-specific compiled Python files.
-Clear it selectively between model loads to avoid stale artefacts, while
-preserving model-agnostic components (like Trainers) needed by spawned
-subprocesses.
+unsloth_compiled_cache (created by unsloth_zoo/compiler.py during
+FastModel.from_pretrained) holds model-type-specific compiled files. Clear it
+selectively between model loads, preserving model-agnostic components (Trainers)
+that spawned subprocesses need.
 """
 
 import shutil
@@ -79,7 +77,6 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
 
             for item in cache_dir.iterdir():
                 if item.is_file():
-                    # Keep the file if it matches any preserve pattern
                     preserve = any(item.match(pattern) for pattern in preserve_patterns)
                     if not preserve:
                         try:
@@ -91,6 +88,6 @@ def clear_unsloth_compiled_cache(preserve_patterns: Optional[List[str]] = None)
                     # Always clear __pycache__ and other subdirectories
                     shutil.rmtree(item, ignore_errors = True)
         else:
-            # Legacy behavior: remove the entire directory
+            # Legacy: remove the entire directory
             logger.info(f"Removing unsloth compiled cache: {cache_dir}")
             shutil.rmtree(cache_dir, ignore_errors = True)
diff --git a/studio/backend/utils/cpu_threads.py b/studio/backend/utils/cpu_threads.py
index 5cf2ff1ce2..4ed0021054 100644
--- a/studio/backend/utils/cpu_threads.py
+++ b/studio/backend/utils/cpu_threads.py
@@ -19,8 +19,8 @@ def configure_cpu_threads(env: Optional[MutableMapping[str, str]] = None) -> Non
     """Apply ``UNSLOTH_CPU_THREADS`` to native CPU pools when configured.
 
     Must run before importing libraries that initialize an OpenMP or BLAS
-    thread pool. Library-specific variables are left untouched so users can
-    override a single runtime independently.
+    pool. Library-specific vars are left untouched so users can override a
+    single runtime independently.
     """
     environ = os.environ if env is None else env
     configured = environ.get("UNSLOTH_CPU_THREADS", "").strip()
diff --git a/studio/backend/utils/datasets/__init__.py b/studio/backend/utils/datasets/__init__.py
index 3ecb085478..caa471bde5 100644
--- a/studio/backend/utils/datasets/__init__.py
+++ b/studio/backend/utils/datasets/__init__.py
@@ -1,20 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Dataset utilities for LLM/VLM fine-tuning: format detection, conversion,
-and processing.
+"""Dataset utilities for LLM/VLM fine-tuning: detection, conversion, templating, collators, mappings."""
 
-Modules:
-- format_detection: Detect dataset formats (Alpaca, ShareGPT, ChatML)
-- format_conversion: Convert between dataset formats
-- chat_templates: Apply chat templates to datasets
-- vlm_processing: Vision-Language Model processing utilities
-- data_collators: Custom data collators for training
-- model_mappings: Model-to-template mapping constants
-"""
-
-# Format detection
 from .format_detection import (
     detect_dataset_format,
     detect_custom_format_heuristic,
@@ -22,7 +10,6 @@ from .format_detection import (
     detect_vlm_dataset_structure,
 )
 
-# Format conversion
 from .format_conversion import (
     standardize_chat_format,
     convert_chatml_to_alpaca,
@@ -32,7 +19,6 @@ from .format_conversion import (
     convert_sharegpt_with_images_to_vlm_format,
 )
 
-# Chat templates
 from .chat_templates import (
     apply_chat_template_to_dataset,
     get_dataset_info_summary,
@@ -40,19 +26,16 @@ from .chat_templates import (
     DEFAULT_ALPACA_TEMPLATE,
 )
 
-# VLM processing
 from .vlm_processing import (
     generate_smart_vlm_instruction,
 )
 
-# Data collators
 from .data_collators import (
     DataCollatorSpeechSeq2SeqWithPadding,
     DeepSeekOCRDataCollator,
     VLMDataCollator,
 )
 
-# Model mappings (constants)
 from .model_mappings import (
     TEMPLATE_TO_MODEL_MAPPER,
     MODEL_TO_TEMPLATE_MAPPER,
@@ -60,14 +43,13 @@ from .model_mappings import (
     is_gpt_oss_model_name,
 )
 
-# Legacy imports from dataset_utils.py (not yet refactored) for backward compat
+# Legacy dataset_utils.py imports kept for backward compat
 from .dataset_utils import (
     check_dataset_format,
     format_and_template_dataset,
     format_dataset,
 )
 
-# Public API
 __all__ = [
     # Detection
     "detect_dataset_format",
diff --git a/studio/backend/utils/datasets/chat_templates.py b/studio/backend/utils/datasets/chat_templates.py
index 4b8ee93e9c..82a30fd55b 100644
--- a/studio/backend/utils/datasets/chat_templates.py
+++ b/studio/backend/utils/datasets/chat_templates.py
@@ -44,28 +44,25 @@ def _chat_template_kwargs() -> dict:
 
 
 def get_tokenizer_chat_template(tokenizer, model_name):
-    """
-    Get the chat template for a tokenizer based on the model.
-    Uses Unsloth's get_chat_template if the model is in the mapper.
+    """Apply a chat template to the tokenizer, using Unsloth's
+    get_chat_template when the model class name is in the mapper.
 
     Args:
         tokenizer: HuggingFace tokenizer
         model_name: Model class name (e.g., "Gemma3ForCausalLM")
 
     Returns:
-        tokenizer: Tokenizer with the chat template applied
+        tokenizer with the chat template applied
     """
     try:
         from unsloth.chat_templates import get_chat_template
     except ImportError:
-        # Unsloth not available; return tokenizer as-is.
         return tokenizer
 
     model_name_lower = model_name.lower()
 
     matched_template = None
 
-    # Direct match in MODEL_TO_TEMPLATE_MAPPER.
     if model_name_lower in MODEL_TO_TEMPLATE_MAPPER:
         matched_template = MODEL_TO_TEMPLATE_MAPPER[model_name_lower]
         logger.info(f"📝 Applying Unsloth chat template: {matched_template}")
@@ -79,7 +76,6 @@ def get_tokenizer_chat_template(tokenizer, model_name):
             logger.info(f"⚠️ Failed to apply Unsloth template '{matched_template}': {e}")
             logger.info(f"   Falling back to tokenizer's default chat template")
     else:
-        # Check whether the tokenizer has a chat_template set.
         has_chat_template = (
             hasattr(tokenizer, 'chat_template')
             and tokenizer.chat_template is not None
@@ -87,7 +83,7 @@ def get_tokenizer_chat_template(tokenizer, model_name):
         if has_chat_template:
             logger.info(f"📝 Using tokenizer's own chat template (no Unsloth template match)")
         else:
-            # Base model with no chat template — apply default ChatML.
+            # Base model with no chat template: apply default ChatML.
             logger.info(f"📝 No chat template found — applying default ChatML template (base model)")
             try:
                 tokenizer = get_chat_template(
@@ -140,8 +136,7 @@ def apply_chat_template_to_dataset(
     num_proc = None,
     progress_callback = None,
 ):
-    """
-    Apply the chat template to a dataset based on its format.
+    """Apply the chat template to a dataset based on its format.
 
     Args:
         dataset_info: Output from format_dataset() with metadata
@@ -164,7 +159,6 @@ def apply_chat_template_to_dataset(
     warnings = list(dataset_info.get("warnings", []))
     errors = []
 
-    # Get EOS token if needed.
     eos_token = ""
     if add_eos_token:
         if hasattr(tokenizer, 'eos_token') and tokenizer.eos_token:
@@ -174,7 +168,6 @@ def apply_chat_template_to_dataset(
 
     # CUSTOM FORMAT MAPPING (for non-standard datasets)
     if final_format == "unknown":
-        # Auto-detect if no custom mapping was provided.
         if custom_format_mapping is None and auto_detect_mapping:
             # Skip if format_dataset already tried and failed.
             if not dataset_info.get("auto_detection_attempted", False):
@@ -246,7 +239,6 @@ def apply_chat_template_to_dataset(
 
             try:
                 dataset = dataset.map(_apply_custom_mapping, batched = True, batch_size = batch_size)
-                # Switch to conversations format.
                 final_format = "chatml_conversations"
                 chat_column = "conversations"
                 is_standardized = True
@@ -263,8 +255,7 @@ def apply_chat_template_to_dataset(
     # ALPACA FORMAT
     if final_format == "alpaca":
 
-        # Set alpaca chat template on the tokenizer (if unset) so it's
-        # saved with the model for inference.
+        # Set alpaca chat template (if unset) so it's saved for inference.
         if not (hasattr(tokenizer, 'chat_template') and tokenizer.chat_template):
             try:
                 from unsloth.chat_templates import get_chat_template
@@ -277,7 +268,6 @@ def apply_chat_template_to_dataset(
             except Exception as e:
                 logger.info(f"⚠️ Could not set alpaca template on tokenizer: {e}")
 
-        # Use custom template if provided.
         def _format_alpaca_custom(examples):
             texts = []
             for i in range(len(examples["instruction"])):
@@ -392,7 +382,7 @@ def apply_chat_template_to_dataset(
                 dataset_map_kwargs['num_proc'] = num_proc
                 dataset_map_kwargs['desc'] = f"Applying chat template to {final_format}"
 
-            # Monitor tqdm progress from dataset.map() and relay it.
+            # Monitor dataset.map() tqdm progress and relay it.
             _tqdm_monitor_stop = None
             if progress_callback and not _is_torch_iterable:
                 import threading
diff --git a/studio/backend/utils/datasets/data_collators.py b/studio/backend/utils/datasets/data_collators.py
index 5f249b32f9..9bfb60ba17 100644
--- a/studio/backend/utils/datasets/data_collators.py
+++ b/studio/backend/utils/datasets/data_collators.py
@@ -1,11 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Data collators for dataset processing.
-
-Custom training collators, particularly for VLM/OCR processing.
-"""
+"""Custom training data collators, particularly for VLM/OCR processing."""
 
 from dataclasses import dataclass
 from typing import Any, List, Optional, Union
@@ -44,13 +40,10 @@ class DataCollatorSpeechSeq2SeqWithPadding:
 
 @dataclass
 class DeepSeekOCRDataCollator:
-    """
-    Data collator for DeepSeek OCR VLM training.
+    """Data collator for DeepSeek OCR VLM training.
 
-    Handles:
-    - Image processing via processor
-    - Text tokenization
-    - Proper label masking for instruction fine-tuning
+    Handles image processing, text tokenization, and label masking for
+    instruction fine-tuning.
     """
 
     processor: Any  # Qwen2VLProcessor or similar
@@ -70,7 +63,6 @@ class DeepSeekOCRDataCollator:
         """
         from PIL import Image
 
-        # Extract messages and images.
         all_messages = []
         all_images = []
 
@@ -78,7 +70,6 @@ class DeepSeekOCRDataCollator:
             messages = sample["messages"]
             all_messages.append(messages)
 
-            # Extract PIL images from content.
             for msg in messages:
                 content = msg.get("content", [])
                 if isinstance(content, list):
@@ -88,9 +79,7 @@ class DeepSeekOCRDataCollator:
                             if img is not None and hasattr(img, "size"):  # PIL Image
                                 all_images.append(img)
 
-        # Process with the VL processor.
         try:
-            # Qwen2VL-style processing.
             texts = [
                 self.processor.apply_chat_template(
                     msgs, tokenize = False, add_generation_prompt = False
@@ -98,7 +87,6 @@ class DeepSeekOCRDataCollator:
                 for msgs in all_messages
             ]
 
-            # Process with images.
             inputs = self.processor(
                 text = texts,
                 images = all_images if all_images else None,
@@ -108,10 +96,7 @@ class DeepSeekOCRDataCollator:
                 max_length = self.max_length,
             )
 
-            # Create labels (mask input, keep output).
             labels = inputs["input_ids"].clone()
-
-            # Mask padding tokens.
             labels[labels == self.processor.tokenizer.pad_token_id] = self.ignore_index
 
             inputs["labels"] = labels
@@ -125,14 +110,7 @@ class DeepSeekOCRDataCollator:
 
 @dataclass
 class VLMDataCollator:
-    """
-    Generic VLM data collator that works with various processors.
-
-    Supports:
-    - Qwen2VL
-    - LLaVA
-    - Other VL models with compatible processors
-    """
+    """Generic VLM data collator for various processors (Qwen2VL, LLaVA, etc.)."""
 
     processor: Any
     max_length: int = 2048
@@ -140,9 +118,7 @@ class VLMDataCollator:
     mask_input_tokens: bool = True  # Mask user tokens in labels
 
     def __call__(self, batch: List[dict]) -> dict:
-        """
-        Collate a batch of VLM samples.
-        """
+        """Collate a batch of VLM samples."""
         all_messages = []
         all_images = []
 
@@ -150,7 +126,6 @@ class VLMDataCollator:
             messages = sample.get("messages", [])
             all_messages.append(messages)
 
-            # Extract images.
             for msg in messages:
                 content = msg.get("content", [])
                 if isinstance(content, list):
@@ -160,13 +135,11 @@ class VLMDataCollator:
                             if img is not None:
                                 all_images.append(img)
 
-        # Apply chat template.
         texts = [
             self.processor.apply_chat_template(msgs, tokenize = False, add_generation_prompt = False)
             for msgs in all_messages
         ]
 
-        # Process inputs.
         inputs = self.processor(
             text = texts,
             images = all_images if all_images else None,
@@ -176,7 +149,6 @@ class VLMDataCollator:
             max_length = self.max_length,
         )
 
-        # Create labels.
         labels = inputs["input_ids"].clone()
 
         # Mask padding.
diff --git a/studio/backend/utils/datasets/dataset_none_detect.py b/studio/backend/utils/datasets/dataset_none_detect.py
index 354fd360d3..a2fd8ef667 100644
--- a/studio/backend/utils/datasets/dataset_none_detect.py
+++ b/studio/backend/utils/datasets/dataset_none_detect.py
@@ -1,6 +1,4 @@
 """
-dataset_none_detect.py
-
 Detect None/empty content turns in conversation datasets. Reports findings
 without modifying data.
 
@@ -71,10 +69,8 @@ def _probe_conversation(dataset: Dataset, candidates = None):
                 break
         if first is None:
             # No usable dict turn in 100 rows. Record an all_corrupt fallback,
-            # plausible only if we saw turn-shaped data (a None cell or a list
-            # holding a dict/None turn); scalars and list-of-strings must not
-            # look like chatml. Upgrade a non-plausible fallback when a later
-            # candidate is plausible, so probe order keeps the best match.
+            # plausible only with turn-shaped data (None cell or list of dict/None
+            # turns); a later plausible candidate upgrades a non-plausible one.
             if all_corrupt_fallback is None or not all_corrupt_fallback.get("has_plausible_turns"):
                 has_plausible_turns = False
                 for i in range(min(len(dataset), 100)):
diff --git a/studio/backend/utils/datasets/dataset_utils.py b/studio/backend/utils/datasets/dataset_utils.py
index 03387e5331..2d65b6ecbc 100644
--- a/studio/backend/utils/datasets/dataset_utils.py
+++ b/studio/backend/utils/datasets/dataset_utils.py
@@ -20,7 +20,6 @@ Internal utilities live in separate modules:
 
 import json
 
-# Import from modular files
 from .format_detection import (
     detect_dataset_format,
     detect_multimodal_dataset,
@@ -915,8 +914,7 @@ def format_and_template_dataset(
                         "errors": [],
                     }
                 except Exception as e:
-                    # User mapping failed — fall back to auto-detection rather
-                    # than give up (handles stale cached mappings gracefully)
+                    # User mapping failed; fall back to auto-detection (handles stale cached mappings).
                     warnings.append(
                         f"User VLM mapping (image='{user_vlm_image_column}', "
                         f"text='{user_vlm_text_column}') failed: {e} — "
@@ -1154,8 +1152,7 @@ def format_and_template_dataset(
         all_warnings = dataset_info.get("warnings", []) + template_result.get("warnings", [])
         all_errors = template_result.get("errors", [])
 
-        # If format_dataset returned "unknown" but apply_chat_template rescued
-        # it via heuristic detection, update final_format accordingly.
+        # If apply_chat_template rescued an "unknown" format, update final_format.
         final_format = dataset_info["final_format"]
         requires_manual = dataset_info.get("requires_manual_mapping", False)
         if final_format == "unknown" and template_result["success"]:
diff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.py
index 09521e160c..7a556a9745 100644
--- a/studio/backend/utils/datasets/format_conversion.py
+++ b/studio/backend/utils/datasets/format_conversion.py
@@ -1,10 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Dataset format conversion: convert between Alpaca, ShareGPT, and ChatML,
-and standardize chat formats.
-"""
+"""Dataset format conversion between Alpaca, ShareGPT, and ChatML."""
 
 import os
 
@@ -290,14 +287,11 @@ def convert_to_vlm_format(
     Convert simple {image, text} format to VLM messages format.
 
     Returns a LIST, not a HuggingFace Dataset (to preserve PIL Images).
-
-    For URL-based image datasets, runs a 200-sample parallel probe first
-    to estimate download speed and failure rate, reporting a time
-    estimate or warning via progress_callback before the full conversion.
+    For URL-based datasets, runs a 200-sample parallel probe first to
+    estimate speed/failure rate via progress_callback.
 
     Args:
-        progress_callback: Optional callable(status_message=str) to
-                          report progress to the training overlay.
+        progress_callback: Optional callable(status_message=str) for progress.
 
     Returns:
         list: List of dicts with 'messages' field
@@ -385,9 +379,8 @@ def convert_to_vlm_format(
     first_image = next(iter(dataset))[image_column]
     has_urls = isinstance(first_image, str) and first_image.startswith(("http://", "https://"))
 
-    # ── Bare-filename detection: images stored as filenames (e.g.
-    #    "img_001.png") not present locally. Build a basename→repo_path
-    #    lookup to resolve them via hf_hub_download during conversion.
+    # ── Bare-filename detection: build a basename→repo_path lookup so
+    #    filename-only images resolve via hf_hub_download during conversion.
     _image_lookup = None
     _IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff")
     if (
diff --git a/studio/backend/utils/datasets/format_detection.py b/studio/backend/utils/datasets/format_detection.py
index 72f8f48cf7..b3a4e3d6d5 100644
--- a/studio/backend/utils/datasets/format_detection.py
+++ b/studio/backend/utils/datasets/format_detection.py
@@ -1,11 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Format detection utilities for dataset processing.
-
-Detects dataset formats (Alpaca, ShareGPT, ChatML), multimodal/VLM
-structures, and heuristic column mapping.
-"""
+"""Dataset format detection: Alpaca/ShareGPT/ChatML, multimodal/VLM structures, heuristic column mapping."""
 
 import re
 
@@ -48,7 +44,6 @@ def detect_dataset_format(dataset):
         chat_column = "texts"
 
     if chat_column:
-        # Inspect structure: ShareGPT or ChatML?
         try:
             sample = next(iter(dataset))
             chat_data = sample[chat_column]
@@ -57,7 +52,7 @@ def detect_dataset_format(dataset):
                 first_msg = chat_data[0]
                 msg_keys = set(first_msg.keys())
 
-                # ShareGPT uses "from" and "value"
+                # ShareGPT: "from"/"value"
                 if "from" in msg_keys or "value" in msg_keys:
                     return {
                         "format": "sharegpt",
@@ -66,7 +61,7 @@ def detect_dataset_format(dataset):
                         "sample_keys": list(msg_keys),
                     }
 
-                # ChatML uses "role" and "content"
+                # ChatML: "role"/"content"
                 elif "role" in msg_keys and "content" in msg_keys:
                     return {
                         "format": "chatml",
@@ -75,7 +70,6 @@ def detect_dataset_format(dataset):
                         "sample_keys": list(msg_keys),
                     }
 
-                # Has chat column but unknown structure
                 else:
                     return {
                         "format": "unknown",
@@ -92,7 +86,6 @@ def detect_dataset_format(dataset):
                 "error": str(e),
             }
 
-    # No recognized format
     return {
         "format": "unknown",
         "chat_column": None,
@@ -115,7 +108,6 @@ def detect_custom_format_heuristic(dataset):
 
     mapping = {}
 
-    # Keywords
     assistant_words = [
         "output",
         "answer",
@@ -132,7 +124,6 @@ def detect_custom_format_heuristic(dataset):
         "solve",
     ]
 
-    # Split into high/low priority
     user_words_high_priority = [
         "input",
         "question",
@@ -159,7 +150,7 @@ def detect_custom_format_heuristic(dataset):
         "task",  # also a system keyword
     ]
 
-    # Metadata columns to ignore
+    # Metadata columns to ignore.
     metadata_exact_match = {
         "id",
         "idx",
@@ -254,12 +245,11 @@ def detect_custom_format_heuristic(dataset):
         score = 0
         score += 10
 
-        # Penalize ambiguous keywords when scoring for user
+        # Penalize ambiguous "task" so other user columns win.
         if role_type == "user":
             col_lower = col_name.lower()
-            # ONLY "task" (or task_xxx): lower priority for user role
             if "task" in col_lower and not any(kw in col_lower for kw in user_words_high_priority):
-                score -= 15  # Significant penalty so other user columns win
+                score -= 15
 
         priority_bonus = get_priority_score(col_name)
         score += priority_bonus
@@ -286,14 +276,12 @@ def detect_custom_format_heuristic(dataset):
 
         return score
 
-    # Drop metadata columns
     content_columns = [col for col in all_columns if not is_metadata(col)]
 
-    # Count candidates
     assistant_potential = [col for col in content_columns if has_keyword(col, assistant_words)]
     user_potential = [col for col in content_columns if has_keyword(col, user_words)]
 
-    # STEP 1: Find best ASSISTANT column
+    # STEP 1: best ASSISTANT column
     assistant_candidates = []
     for col in assistant_potential:
         score = score_column(col, assistant_words, "assistant", len(assistant_potential))
@@ -307,7 +295,7 @@ def detect_custom_format_heuristic(dataset):
     else:
         assistant_col = None
 
-    # STEP 2: Find best USER column (with penalty for ambiguous keywords)
+    # STEP 2: best USER column (penalizing ambiguous keywords)
     user_candidates = []
     for col in user_potential:
         if col == assistant_col:
@@ -323,35 +311,32 @@ def detect_custom_format_heuristic(dataset):
     else:
         user_col = None
 
-    # STEP 3: Check ALL remaining columns for SYSTEM matches (priority check)
+    # STEP 3: check remaining columns for SYSTEM matches
     remaining_columns = [col for col in content_columns if col not in mapping]
 
     system_col = None
     for col in remaining_columns:
         if has_keyword(col, system_words):
-            # System match found
             mapping[col] = "system"
             system_col = col
             break
 
-    # STEP 4: Handle any additional remaining columns
+    # STEP 4: handle any additional remaining columns
     if system_col:
         remaining_columns = [col for col in remaining_columns if col != system_col]
 
     if len(remaining_columns) >= 1:
         remaining_col = remaining_columns[0]
 
-        # No strong keyword match: decide by what's missing
+        # No strong keyword match: decide by what's missing.
         if not has_keyword(remaining_col, user_words + assistant_words):
             mapping[remaining_col] = "system"
         elif user_col is None:
-            # No user column yet: assign this as user
             mapping[remaining_col] = "user"
         else:
-            # Already have user + assistant: treat as system context
             mapping[remaining_col] = "system"
 
-    # Ensure we have at least user + assistant
+    # Ensure at least user + assistant.
     has_user = any(role == "user" for role in mapping.values())
     has_assistant = any(role == "assistant" for role in mapping.values())
 
@@ -371,25 +356,13 @@ def detect_custom_format_heuristic(dataset):
 def detect_multimodal_dataset(dataset):
     """Detect multimodal data (images and/or audio) in a dataset.
 
-    Two passes per modality:
-      1. Column-name heuristic (fast): keyword match.
-      2. Value-type inspection (reliable): check actual sample values.
-
-    Returns:
-        dict: {
-            "is_image": bool,
-            "multimodal_columns": list of column names containing image data,
-            "modality_types": list of detected types (e.g., ["image", "audio"]),
-            "is_audio": bool,
-            "audio_columns": list of column names containing audio data,
-            "detected_audio_column": str or None,
-            "detected_text_column": str or None,
-        }
+    Two passes per modality: column-name keyword heuristic, then value-type
+    inspection. Returns a dict with is_image/is_audio flags, detected columns,
+    modality types, and detected audio/text/speaker columns.
     """
     sample = next(iter(dataset))
     column_names = list(sample.keys())
 
-    # Image keywords
     image_keywords = [
         "image",
         "img",
@@ -410,7 +383,6 @@ def detect_multimodal_dataset(dataset):
         "filename",
     ]
 
-    # Audio keywords
     audio_keywords = ["audio", "speech", "wav", "waveform", "sound"]
 
     multimodal_columns = []
@@ -418,8 +390,7 @@ def detect_multimodal_dataset(dataset):
     modality_types = set()
 
     # ── Image detection ─────────────────────────────────────
-    # Pass 1: column-name heuristic (word-boundary match avoids false
-    #          positives like 'pic' in 'topic')
+    # Pass 1: column-name heuristic (word-boundary match)
     for col_name in column_names:
         for keyword in image_keywords:
             if _keyword_in_column(keyword, col_name):
@@ -456,13 +427,13 @@ def detect_multimodal_dataset(dataset):
             audio_columns.append(col_name)
             modality_types.add("audio")
 
-    # Drop audio columns from the image list (e.g. a column named "audio"
-    # with {"bytes", "path"} could match _is_image_value)
+    # Drop audio columns from the image list (a {"bytes","path"} audio column
+    # can match _is_image_value).
     if audio_columns:
         audio_set = set(audio_columns)
         multimodal_columns = [c for c in multimodal_columns if c not in audio_set]
 
-    # Text column for audio datasets
+    # Text column for audio datasets.
     detected_text_col = None
     if audio_columns:
         text_keywords = ["text", "sentence", "transcript", "transcription", "label"]
@@ -499,7 +470,6 @@ def _is_image_value(value) -> bool:
     if value is None:
         return False
 
-    # PIL Image instance
     try:
         from PIL.Image import Image as PILImage
         if isinstance(value, PILImage):
@@ -513,7 +483,7 @@ def _is_image_value(value) -> bool:
         if "array" in value and "sampling_rate" in value:
             return False  # audio, not image
         if "bytes" in value and "path" in value:
-            # Use path extension to exclude audio files
+            # Use path extension to exclude audio files.
             path = value.get("path") or ""
             if isinstance(path, str) and any(
                 path.lower().endswith(ext) for ext in _AUDIO_EXTENSIONS
@@ -521,20 +491,17 @@ def _is_image_value(value) -> bool:
                 return False
             return True
 
-    # Raw bytes with a known image magic header
     if isinstance(value, (bytes, bytearray)):
         return _has_image_header(value)
 
-    # String that looks like an image file path or URL
+    # String that looks like an image file path or URL.
     _IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff", ".svg")
     if isinstance(value, str) and len(value) < 1000:
         lower = value.strip().lower()
-        # Image URL (http://... ending in image extension)
         if lower.startswith(("http://", "https://")) and any(
             lower.split("?")[0].endswith(ext) for ext in _IMAGE_EXTS
         ):
             return True
-        # Image file path (relative or absolute)
         if any(lower.endswith(ext) for ext in _IMAGE_EXTS):
             return True
 
@@ -559,11 +526,10 @@ def _is_audio_value(value) -> bool:
     if value is None:
         return False
 
-    # HF Audio feature: decoded → {"array": np.ndarray, "sampling_rate": int}
+    # HF Audio feature: decoded -> {"array", "sampling_rate"}; undecoded -> {"bytes", "path"}.
     if isinstance(value, dict):
         if "array" in value and "sampling_rate" in value:
             return True
-        # Undecoded/streaming → {"bytes", "path": "some.wav"}
         if "bytes" in value or "path" in value:
             path = value.get("path") or ""
             if isinstance(path, str) and any(
@@ -578,20 +544,15 @@ def _has_image_header(data: bytes) -> bool:
     """Quick magic-byte check for common image formats."""
     if len(data) < 4:
         return False
-    # JPEG
-    if data[:2] == b"\xff\xd8":
+    if data[:2] == b"\xff\xd8":  # JPEG
         return True
-    # PNG
-    if data[:4] == b"\x89PNG":
+    if data[:4] == b"\x89PNG":  # PNG
         return True
-    # GIF
-    if data[:3] == b"GIF":
+    if data[:3] == b"GIF":  # GIF
         return True
-    # WebP
-    if data[:4] == b"RIFF" and len(data) >= 12 and data[8:12] == b"WEBP":
+    if data[:4] == b"RIFF" and len(data) >= 12 and data[8:12] == b"WEBP":  # WebP
         return True
-    # BMP
-    if data[:2] == b"BM":
+    if data[:2] == b"BM":  # BMP
         return True
     return False
 
@@ -615,7 +576,6 @@ def detect_vlm_dataset_structure(dataset):
 
     column_names = set(sample.keys())
 
-    # Has messages column?
     if "messages" in column_names:
         messages = sample["messages"]
 
@@ -665,11 +625,10 @@ def detect_vlm_dataset_structure(dataset):
         first_msg = chat_data[0]
         if not isinstance(first_msg, dict):
             continue
-        # ShareGPT (from/value) or ChatML (role/content) keys
+        # ShareGPT (from/value) or ChatML (role/content).
         msg_text = first_msg.get("value") or first_msg.get("content")
         if not isinstance(msg_text, str):
             continue
-        # <image> placeholder anywhere in the conversation?
         has_image_placeholder = any(
             "<image>" in str(m.get("value", "") or m.get("content", ""))
             for m in chat_data
@@ -677,7 +636,7 @@ def detect_vlm_dataset_structure(dataset):
         )
         if not has_image_placeholder:
             continue
-        # Find companion image column
+        # Find companion image column.
         image_col = None
         for col in column_names:
             if col == chat_col:
@@ -718,7 +677,6 @@ def detect_vlm_dataset_structure(dataset):
         ],
     }
 
-    # Image keywords
     image_keywords = [
         "image",
         "img",
@@ -731,7 +689,6 @@ def detect_vlm_dataset_structure(dataset):
         "filename",
     ]
 
-    # Text keywords
     text_keywords = [
         "text",
         "caption",
@@ -747,11 +704,8 @@ def detect_vlm_dataset_structure(dataset):
         """True if the column name looks like metadata."""
         col_lower = col_name.lower()
 
-        # Suffixes
         if any(col_lower.endswith(suffix) for suffix in metadata_patterns["suffixes"]):
             return True
-
-        # Prefixes
         if any(col_lower.startswith(prefix) for prefix in metadata_patterns["prefixes"]):
             return True
 
@@ -759,39 +713,36 @@ def detect_vlm_dataset_structure(dataset):
 
     def _score_image_candidate(col, sample_value):
         """Score a candidate image column by how resolvable its value is."""
-        # PIL Image object (already loaded -> highest)
+        # PIL Image (already loaded) -> highest.
         if hasattr(sample_value, "size") and hasattr(sample_value, "mode"):
             return 100
 
-        # Dict with bytes/path from HF Image feature
+        # HF Image feature dict.
         if isinstance(sample_value, dict) and ("bytes" in sample_value or "path" in sample_value):
             return 75
 
         if isinstance(sample_value, str):
-            # URL
-            if sample_value.startswith(("http://", "https://")):
+            if sample_value.startswith(("http://", "https://")):  # URL
                 return 70 if not is_metadata_column(col) else 55
-            # Bare file path
-            if is_metadata_column(col):
+            if is_metadata_column(col):  # bare file path
                 return 30
             return 50
 
         return 0
 
     def _probe_image_candidate(col, sample_value):
-        """Probe whether an image candidate is reachable.
-        True if likely valid, False if definitely broken."""
+        """Probe whether an image candidate is reachable (True unless definitely broken)."""
         import os
 
-        # PIL / dict — already loaded, always valid
+        # PIL / dict — already loaded.
         if not isinstance(sample_value, str):
             return True
 
-        # Local file — check it exists
+        # Local file — check it exists.
         if not sample_value.startswith(("http://", "https://")):
-            return os.path.exists(sample_value)  # bare filenames return False here, that's OK
+            return os.path.exists(sample_value)  # bare filenames return False, that's OK
 
-        # URL — quick HEAD with short timeout
+        # URL — quick HEAD with short timeout.
         try:
             import urllib.request
 
@@ -802,11 +753,10 @@ def detect_vlm_dataset_structure(dataset):
             return False
 
     def find_image_column():
-        """Find image column by keyword match + value-based fallback,
-        probing candidates to find one that works."""
+        """Find image column by keyword match + value-based fallback, probing for one that works."""
         candidates = []
 
-        # Pass 1: keyword-matched columns
+        # Pass 1: keyword-matched columns.
         for col in column_names:
             if any(_keyword_in_column(keyword, col) for keyword in image_keywords):
                 sample_value = sample[col]
@@ -814,8 +764,8 @@ def detect_vlm_dataset_structure(dataset):
                 if score > 0:
                     candidates.append((col, score))
 
-        # Pass 2: value-based fallback — columns with image URLs/paths
-        # even if the name doesn't match image keywords
+        # Pass 2: value-based fallback for image URLs/paths even when the name
+        # doesn't match keywords.
         already = {c[0] for c in candidates}
         for col in column_names:
             if col in already:
@@ -823,7 +773,7 @@ def detect_vlm_dataset_structure(dataset):
             sample_value = sample[col]
             if _is_image_value(sample_value):
                 score = _score_image_candidate(col, sample_value)
-                # Penalise non-keyword columns so keyword matches win on ties
+                # Penalise non-keyword columns so keyword matches win on ties.
                 candidates.append((col, max(score - 5, 1)))
 
         if not candidates:
@@ -831,18 +781,17 @@ def detect_vlm_dataset_structure(dataset):
 
         candidates.sort(key = lambda x: x[1], reverse = True)
 
-        # Single candidate or top is PIL/dict — no probing needed
+        # Single candidate or top is PIL/dict — no probing needed.
         if len(candidates) == 1 or candidates[0][1] >= 75:
             return candidates[0][0]
 
-        # Multiple string candidates — probe for one that works
+        # Multiple string candidates — probe for one that works.
         for col, score in candidates:
             sample_value = sample[col]
             if _probe_image_candidate(col, sample_value):
                 return col
 
-        # None probed OK — return highest-scored and let conversion handle
-        # the error (it may still resolve via hf_hub_download)
+        # None probed OK — return highest-scored; conversion may still resolve it.
         return candidates[0][0]
 
     def find_text_column():
@@ -853,25 +802,22 @@ def detect_vlm_dataset_structure(dataset):
             if is_metadata_column(col):
                 continue
 
-            # Text keyword (word-boundary match)
             if any(_keyword_in_column(keyword, col) for keyword in text_keywords):
-                # Verify it's actually text
                 sample_value = sample[col]
 
                 if isinstance(sample_value, str) and len(sample_value) > 0:
-                    # Longer text = higher priority (content, not a label)
-                    priority = min(len(sample_value), 1000)  # cap at 1000
+                    # Longer text = higher priority (content, not a label).
+                    priority = min(len(sample_value), 1000)
                     candidates.append((col, priority))
                 elif (
                     isinstance(sample_value, list)
                     and len(sample_value) > 0
                     and isinstance(sample_value[0], str)
                 ):
-                    # List of strings (e.g. captions) — lower priority than plain str
+                    # List of strings (e.g. captions) — lower priority than plain str.
                     priority = min(len(sample_value[0]), 1000) // 2
                     candidates.append((col, priority))
 
-        # Highest-priority candidate
         if candidates:
             candidates.sort(key = lambda x: x[1], reverse = True)
             return candidates[0][0]
diff --git a/studio/backend/utils/datasets/llm_assist.py b/studio/backend/utils/datasets/llm_assist.py
index d6bb0dc91d..f7b35e2869 100644
--- a/studio/backend/utils/datasets/llm_assist.py
+++ b/studio/backend/utils/datasets/llm_assist.py
@@ -1,16 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-LLM-assisted dataset analysis using an ephemeral GGUF helper model.
+"""LLM-assisted dataset analysis using an ephemeral GGUF helper model.
 
-Complements heuristic detection in format_detection.py and vlm_processing.py.
-Only invoked when heuristics are uncertain.
-
-Architecture:
-  - Instantiates LlamaCppBackend, loads model, runs completion(s), unloads.
-  - Not kept warm — VRAM is freed immediately after use.
-  - Degrades gracefully: returns None when unavailable (no binary, OOM, disabled).
+Complements heuristic detection (format_detection.py, vlm_processing.py); only
+invoked when heuristics are uncertain. Loads LlamaCppBackend, runs completion(s),
+unloads (VRAM freed immediately). Degrades gracefully to None when unavailable.
 """
 
 import json
@@ -33,21 +28,15 @@ README_MAX_CHARS = 1500
 
 
 def _strip_think_tags(text: str) -> str:
-    """Strip <think>...</think> reasoning blocks emitted by some models.
-
-    If the answer is OUTSIDE the think block, discard the block and keep the
-    rest. If the entire response is INSIDE a think block (nothing useful
-    outside), return the inner content instead of discarding everything.
-    """
+    """Strip <think>...</think> blocks, keeping content outside; if all inside, return the inner."""
     if "<think>" not in text:
         return text
 
-    # Strip think blocks — keep content outside them
     stripped = re.sub(r"<think>.*?</think>\s*", "", text, flags = re.DOTALL).strip()
     if stripped:
         return stripped
 
-    # Everything was inside <think> tags — return the last block's inner content
+    # Everything was inside <think> tags: return the last block's inner content.
     matches = re.findall(r"<think>(.*?)</think>", text, flags = re.DOTALL)
     if matches:
         return matches[-1].strip()
@@ -56,12 +45,9 @@ def _strip_think_tags(text: str) -> str:
 
 
 def precache_helper_gguf():
-    """
-    Pre-download the helper GGUF to HF cache.
+    """Pre-download the helper GGUF to HF cache (on startup, background thread).
 
-    Called on FastAPI startup in a background thread so later
-    ``_run_with_helper()`` calls skip the download and only pay for
-    llama-server startup. No-op if already cached or disabled.
+    Lets later ``_run_with_helper()`` calls skip the download. No-op if cached or disabled.
     """
     if os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in ("1", "true"):
         return
@@ -76,12 +62,11 @@ def precache_helper_gguf():
         disable_progress_bars()
         logging.getLogger("huggingface_hub").setLevel(logging.WARNING)
 
-        # Find the GGUF file matching the variant
         api = HfApi()
         files = api.list_repo_files(repo, repo_type = "model")
         gguf_files = [f for f in files if f.endswith(".gguf")]
 
-        # All GGUF files matching the variant (may be split into shards)
+        # GGUF files matching the variant (may be split into shards).
         variant_lower = variant.lower().replace("-", "_")
         matching = sorted(f for f in gguf_files if variant_lower in f.lower().replace("-", "_"))
 
@@ -105,11 +90,7 @@ def precache_helper_gguf():
 
 
 def _run_with_helper(prompt: str, max_tokens: int = 256) -> Optional[str]:
-    """
-    Load helper model, run one chat completion, unload.
-
-    Returns the completion text, or None on any failure.
-    """
+    """Load helper model, run one chat completion, unload. Returns text or None on failure."""
     if os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in ("1", "true"):
         return None
 
@@ -149,7 +130,7 @@ def _run_with_helper(prompt: str, max_tokens: int = 256) -> Optional[str]:
         ):
             if isinstance(chunk, dict):
                 continue  # skip metadata events
-            cumulative = chunk  # cumulative; last value is full text
+            cumulative = chunk  # last value is full text
 
         result = cumulative.strip()
         result = _strip_think_tags(result)
@@ -177,21 +158,10 @@ def llm_generate_vlm_instruction(
     samples: list[dict],
     dataset_name: Optional[str] = None,
 ) -> Optional[dict]:
+    """Ask a helper LLM for a task-specific VLM instruction (when heuristics are low-confidence).
+
+    Returns {"instruction": str, "confidence": 0.85} or None.
     """
-    Ask a helper LLM to generate a task-specific VLM instruction.
-
-    Called when heuristic instruction generation returns low confidence or
-    falls back to generic.
-
-    Args:
-        column_names: Column names in the dataset.
-        samples: 3-5 sample rows with text values (images replaced by "<image>").
-        dataset_name: Optional HF dataset identifier for context.
-
-    Returns:
-        {"instruction": str, "confidence": 0.85} or None.
-    """
-    # Format samples for the prompt
     formatted = ""
     for i, row in enumerate(samples[:5], 1):
         parts = []
@@ -217,9 +187,8 @@ def llm_generate_vlm_instruction(
     if not result:
         return None
 
-    # Strip quotes; ensure a single sentence
     instruction = result.strip().strip('"').strip("'").strip()
-    # Reject bad outputs (too short, too long, or multi-line)
+    # Reject bad outputs (too short, too long, or multi-line).
     if len(instruction) < 10 or len(instruction) > 200 or "\n" in instruction:
         logger.warning(f"Helper model returned unusable instruction: {instruction!r}")
         return None
@@ -232,17 +201,9 @@ def llm_generate_vlm_instruction(
 
 
 def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Optional[dict[str, str]]:
-    """
-    Ask a helper LLM to classify dataset columns into roles.
+    """Ask a helper LLM to classify columns into roles (when heuristic detection fails).
 
-    Called when heuristic column detection fails (returns None).
-
-    Args:
-        column_names: Column names in the dataset.
-        samples: 3-5 sample rows with values truncated to 200 chars.
-
-    Returns:
-        Dict mapping column_name → role ("user"|"assistant"|"system"|"metadata"), or None.
+    Returns {column_name: role} for roles user|assistant|system|metadata, or None.
     """
     formatted = ""
     for i, row in enumerate(samples[:5], 1):
@@ -268,10 +229,9 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
     if not result:
         return None
 
-    # Parse JSON from response (may have markdown fences)
+    # Parse JSON from response (may have markdown fences).
     text = result.strip()
     if text.startswith("```"):
-        # Strip markdown code fence
         lines = text.split("\n")
         text = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])
         text = text.strip()
@@ -279,7 +239,6 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
     try:
         mapping = json.loads(text)
     except json.JSONDecodeError:
-        # Find a JSON object in the response
         import re
         match = re.search(r"\{[^}]+\}", text)
         if match:
@@ -295,7 +254,7 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
     if not isinstance(mapping, dict):
         return None
 
-    # Validate: all values must be valid roles
+    # Keep only valid roles.
     valid_roles = {"user", "assistant", "system", "metadata"}
     cleaned = {}
     for col, role in mapping.items():
@@ -305,7 +264,7 @@ def llm_classify_columns(column_names: list[str], samples: list[dict]) -> Option
     if not cleaned:
         return None
 
-    # Must have at least user + assistant
+    # Must have at least user + assistant.
     roles_present = set(cleaned.values())
     if "user" not in roles_present or "assistant" not in roles_present:
         logger.warning(f"Helper model mapping missing user/assistant: {cleaned}")
@@ -321,19 +280,9 @@ def llm_generate_dataset_warning(
     modality: str = "text",
     column_names: Optional[list[str]] = None,
 ) -> Optional[str]:
-    """
-    Ask the helper LLM to turn technical dataset issues into a friendly warning.
+    """Ask the helper LLM to turn technical dataset issues into a friendly warning (any modality).
 
-    Works for all modalities (text, vision, audio).
-
-    Args:
-        issues: List of technical issue descriptions found during analysis.
-        dataset_name: Optional HF dataset name.
-        modality: "text", "vision", or "audio".
-        column_names: Optional list of column names for context.
-
-    Returns:
-        A human-friendly warning string, or None on failure.
+    Returns a human-friendly warning string, or None on failure.
     """
     if not issues:
         return None
@@ -357,7 +306,6 @@ def llm_generate_dataset_warning(
         return None
 
     warning = result.strip()
-    # Reject bad outputs
     if len(warning) < 10 or len(warning) > 500:
         return None
 
@@ -417,7 +365,7 @@ def _generate_with_backend(
         top_k = 20,
         max_tokens = max_tokens,
         repetition_penalty = 1.0,
-        enable_thinking = False,  # Always disable thinking for AI Assist
+        enable_thinking = False,  # disable thinking for AI Assist
     ):
         if isinstance(chunk, dict):
             continue  # skip metadata events
@@ -430,12 +378,7 @@ def _generate_with_backend(
 def fetch_hf_dataset_card(
     dataset_name: str, hf_token: Optional[str] = None
 ) -> tuple[Optional[str], Optional[dict]]:
-    """
-    Fetch HF dataset card (README) and metadata.
-
-    Returns:
-        (readme_text, metadata_dict) or (None, None) on failure.
-    """
+    """Fetch HF dataset card (README) and metadata. Returns (readme, metadata) or (None, None)."""
     try:
         from huggingface_hub import DatasetCard
 
@@ -450,7 +393,7 @@ def fetch_hf_dataset_card(
             else:
                 readme = readme[:README_MAX_CHARS] + "\n[...truncated]"
 
-        # Extract metadata from YAML frontmatter
+        # Extract metadata from YAML frontmatter.
         metadata = {}
         if card.data:
             for key in (
@@ -484,10 +427,9 @@ def _run_multi_pass_advisor(
     model_type: Optional[str] = None,
     hf_token: Optional[str] = None,
 ) -> Optional[dict[str, Any]]:
-    """
-    Multi-pass LLM analysis: classify → convert → validate.
+    """Multi-pass LLM analysis (classify -> convert -> validate), model loaded across passes.
 
-    Keeps the model loaded across passes. Returns combined result dict or None.
+    Returns combined result dict or None.
     """
     if os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in ("1", "true"):
         return None
@@ -617,7 +559,7 @@ def _run_multi_pass_advisor(
             logger.warning(f"Advisor Pass 1 failed to produce JSON: {raw1[:200]}")
             return None
 
-        # Already conversational: skip passes 2-3
+        # Already conversational: skip passes 2-3.
         if pass1.get("is_conversational") and not pass1.get("needs_conversion"):
             return {
                 "success": True,
@@ -726,7 +668,7 @@ def _run_multi_pass_advisor(
         roles_present = set(column_roles.values())
         if "user" not in roles_present or "assistant" not in roles_present:
             logger.warning(f"Pass 2 sanity fail: missing user or assistant role: {column_roles}")
-            return None  # triggers fallback to simple classification
+            return None  # falls back to simple classification
 
         # ── Pass 3: System prompt (non-conversational datasets only) ──
         sys_prompt = ""
@@ -737,7 +679,7 @@ def _run_multi_pass_advisor(
             logger.info("Pass 3: Generating system prompt...")
             t3 = time.monotonic()
 
-            # Format label mapping for the prompt
+            # Format label mapping for the prompt.
             label_info = ""
             if label_map:
                 for col, mapping in label_map.items():
@@ -745,7 +687,6 @@ def _run_multi_pass_advisor(
                         pairs = ", ".join(f"{k} = {v}" for k, v in mapping.items())
                         label_info += f"\nLabel mapping for '{col}': {pairs}"
 
-            # Describe the role assignments for context
             user_cols = [c for c, r in column_roles.items() if r == "user"]
             asst_cols = [c for c, r in column_roles.items() if r == "assistant"]
             task_desc = pass1.get("task_description") or pass1.get("description", "")
@@ -780,18 +721,18 @@ def _run_multi_pass_advisor(
             )
 
             if raw3:
-                # Pass 3 returns raw text, not JSON — clean it
+                # Pass 3 returns raw text, not JSON.
                 cleaned = raw3.strip().strip('"').strip("'").strip()
                 if len(cleaned) >= 20 and cleaned.lower() not in ("null", "none", ""):
                     sys_prompt = cleaned
 
-        # Build suggested_mapping (column → role) for the frontend dropdowns
+        # Build suggested_mapping (column -> role) for the frontend dropdowns.
         suggested_mapping = {}
         for col, role in column_roles.items():
             if col in columns and role in ("user", "assistant", "system"):
                 suggested_mapping[col] = role
 
-        # Build user notification from Pass 1 classification
+        # Build user notification from Pass 1 classification.
         desc = pass1.get("task_description") or pass1.get("description", "")
         note_parts = [f"This is a {dtype} dataset (not conversational)."]
         if desc:
@@ -837,23 +778,18 @@ def llm_conversion_advisor(
     model_name: Optional[str] = None,
     model_type: Optional[str] = None,
 ) -> Optional[dict[str, Any]]:
-    """
-    Full conversion advisor: fetch HF card → multi-pass LLM analysis.
+    """Full conversion advisor: fetch HF card -> multi-pass LLM analysis.
 
     Falls back to simple llm_classify_columns() if the multi-pass advisor fails.
-
-    Returns:
-        Dict with keys: success, suggested_mapping, system_prompt, user_template,
-        assistant_template, label_mapping, dataset_type, is_conversational,
-        user_notification. Or None on complete failure.
+    Returns a result dict (success, suggested_mapping, system_prompt, label_mapping,
+    dataset_type, is_conversational, user_notification, ...) or None.
     """
-    # Fetch HF dataset card if this looks like a HF dataset (has a slash)
+    # Fetch HF dataset card if this looks like a HF dataset (has a slash).
     dataset_card = None
     dataset_metadata = None
     if dataset_name and "/" in dataset_name:
         dataset_card, dataset_metadata = fetch_hf_dataset_card(dataset_name, hf_token)
 
-    # Try the multi-pass advisor
     result = _run_multi_pass_advisor(
         columns = column_names,
         samples = samples,
@@ -869,7 +805,7 @@ def llm_conversion_advisor(
         logger.info(f"Conversion advisor succeeded: type={result.get('dataset_type')}")
         return result
 
-    # Fallback: simple column classification
+    # Fallback: simple column classification.
     logger.info("Advisor failed, falling back to simple column classification")
     simple_mapping = llm_classify_columns(column_names, samples)
     if simple_mapping:
diff --git a/studio/backend/utils/datasets/model_mappings.py b/studio/backend/utils/datasets/model_mappings.py
index b550dc81bd..463d26a692 100644
--- a/studio/backend/utils/datasets/model_mappings.py
+++ b/studio/backend/utils/datasets/model_mappings.py
@@ -434,7 +434,7 @@ for key, values in TEMPLATE_TO_MODEL_MAPPER.items():
     for value in values:
         MODEL_TO_TEMPLATE_MAPPER[value] = key
 
-    # Get lowercased
+    # Also map lowercased names.
     lowered_key = key.lower()
     for value in values:
         MODEL_TO_TEMPLATE_MAPPER[value.lower()] = lowered_key
diff --git a/studio/backend/utils/datasets/raw_text.py b/studio/backend/utils/datasets/raw_text.py
index 86b1963fc1..03315fb287 100644
--- a/studio/backend/utils/datasets/raw_text.py
+++ b/studio/backend/utils/datasets/raw_text.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Shared helpers for raw-text dataset preparation.
-"""
+"""Shared helpers for raw-text dataset preparation."""
 
 from dataclasses import dataclass
 from typing import Literal
diff --git a/studio/backend/utils/datasets/vlm_processing.py b/studio/backend/utils/datasets/vlm_processing.py
index 4919b8884d..f018913fa8 100644
--- a/studio/backend/utils/datasets/vlm_processing.py
+++ b/studio/backend/utils/datasets/vlm_processing.py
@@ -58,7 +58,6 @@ def generate_smart_vlm_instruction(
     # ===== LEVEL 2: Infer from Column Names + Content =====
     text_col_lower = text_column.lower()
 
-    # Sample text content for pattern detection
     text_sample = str(sample.get(text_column, ""))[:500]  # First 500 chars
 
     # Task-specific keywords and their instructions
@@ -66,7 +65,7 @@ def generate_smart_vlm_instruction(
         # OCR / Transcription
         "ocr": {
             "keywords": ["ocr", "transcribe", "transcript"],
-            "content_hints": [r"[A-Za-z\u0600-\u06FF]{10,}"],  # Long text passages (Latin/Arabic)
+            "content_hints": [r"[A-Za-z\u0600-\u06FF]{10,}"],  # Long Latin/Arabic passages
             "instruction": "Transcribe all the text shown in this image.",
             "confidence": 0.9,
         },
@@ -129,17 +128,14 @@ def generate_smart_vlm_instruction(
     for task_name, task_info in task_patterns.items():
         score = 0.0
 
-        # Column name
         if any(keyword in text_col_lower for keyword in task_info["keywords"]):
             score += 0.5
 
-        # Dataset name if provided
         if dataset_name and any(
             keyword in dataset_name.lower() for keyword in task_info["keywords"]
         ):
             score += 0.3
 
-        # Content patterns
         for pattern in task_info["content_hints"]:
             if re.search(pattern, text_sample, re.IGNORECASE):
                 score += 0.4
diff --git a/studio/backend/utils/hardware/__init__.py b/studio/backend/utils/hardware/__init__.py
index 7ccba6315e..5f2b2abbcf 100644
--- a/studio/backend/utils/hardware/__init__.py
+++ b/studio/backend/utils/hardware/__init__.py
@@ -84,8 +84,8 @@ __all__ = [
 
 
 def __getattr__(name: str):
-    """Resolve IS_ROCM at access time so callers see the live value after
-    detect_hardware() runs (it flips the flag in hardware.py)."""
+    """Resolve IS_ROCM lazily so callers see the live value detect_hardware()
+    sets in hardware.py."""
     if name == "IS_ROCM":
         return getattr(_hardware, "IS_ROCM")
     raise AttributeError(name)
diff --git a/studio/backend/utils/hardware/amd.py b/studio/backend/utils/hardware/amd.py
index 41ee9f3fbe..39aafe0489 100644
--- a/studio/backend/utils/hardware/amd.py
+++ b/studio/backend/utils/hardware/amd.py
@@ -26,9 +26,8 @@ logger = get_logger(__name__)
 # can take 15-25 s on cold hardware. Linux is consistently < 2 s.
 _AMD_SMI_DEFAULT_TIMEOUT = 30 if platform.system() == "Windows" else 10
 
-# Circuit breaker: stop calling amd-smi after this many consecutive failures.
-# On Windows, each failed call spawns a process that may show a UAC/DiskPart
-# elevation prompt. Once we know amd-smi doesn't work, stop polling it.
+# Circuit breaker: stop polling amd-smi after this many consecutive failures
+# (each Windows failure may pop a UAC/DiskPart elevation prompt).
 _AMD_SMI_FAILURE_LIMIT = 3
 _amd_smi_consecutive_failures = 0
 _amd_smi_disabled = False
@@ -50,8 +49,8 @@ def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optiona
         )
     except (OSError, subprocess.TimeoutExpired) as e:
         if isinstance(e, FileNotFoundError):
-            # amd-smi ships with Adrenalin, not the HIP SDK -- absence is
-            # expected on HIP SDK-only Windows setups. Log at debug only.
+            # amd-smi ships with Adrenalin, not the HIP SDK; absence is expected
+            # on HIP SDK-only Windows setups.
             logger.debug("amd-smi not found (not in PATH): %s", e)
         else:
             logger.warning("amd-smi query failed: %s", e)
@@ -74,9 +73,8 @@ def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optiona
             _amd_smi_disabled = True
         return None
     if not result.stdout.strip():
-        # amd-smi exited 0 but produced no output (e.g. no GPUs visible on
-        # this query, or a version that emits nothing for --json). Not a tool
-        # failure, so don't count against the circuit breaker.
+        # Exit 0 with no output (no GPUs visible, or a version emitting nothing
+        # for --json). Not a tool failure, so don't trip the circuit breaker.
         logger.debug("amd-smi exited 0 but returned no output")
         return None
     _amd_smi_consecutive_failures = 0  # reset on success
@@ -132,8 +130,8 @@ def _parse_memory_mb(value: Any) -> Optional[float]:
     if num is None:
         return None
 
-    # Unit conversion -- GPU tools (incl. amd-smi) use binary units even when
-    # labeled "GB" or "MB", so treat GB/GiB and MB/MiB the same.
+    # GPU tools use binary units even when labeled "GB"/"MB", so treat GB/GiB
+    # and MB/MiB the same.
     if "gib" in unit or "gb" in unit:
         return num * 1024
     if "mib" in unit or "mb" in unit:
@@ -144,12 +142,9 @@ def _parse_memory_mb(value: Any) -> Optional[float]:
         # Plain bytes
         return num / (1024 * 1024)
 
-    # No explicit unit -- default to MB, the amd-smi convention for bare
-    # numeric values. A previous heuristic assumed values above ~10M were
-    # bytes, but that misclassifies small VRAM allocations (e.g. 5 MB =
-    # 5,242,880 reported without a unit) as ~5 TB. Modern amd-smi always
-    # ships explicit units, so the heuristic only fired for legacy output
-    # where MB was already the convention.
+    # No explicit unit: default to MB (the amd-smi convention for bare numbers).
+    # A bytes-above-~10M heuristic was dropped because it misclassified small
+    # VRAM allocations; modern amd-smi always ships explicit units.
     return num
 
 
@@ -162,9 +157,8 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
     else:
         gpu_util = _parse_numeric(usage)
 
-    # Temperature -- try keys in priority order. dict.get() returns "N/A"
-    # strings rather than falling through, so try each key and check it
-    # parses to a real number.
+    # Temperature: try keys in priority order, checking each parses to a real
+    # number (dict.get() can return "N/A" strings rather than falling through).
     temp_data = gpu_data.get("temperature", {})
     temp = None
     if isinstance(temp_data, dict):
@@ -189,10 +183,9 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
         power_draw = None
         power_limit = None
 
-    # VRAM -- unit-aware parsing for varying amd-smi output formats.
-    # Newer versions may return {"value": 192, "unit": "GiB"} and use
-    # "mem_usage" with "total_vram" / "used_vram" keys; older versions use
-    # "vram" or "fb_memory_usage" with "used" / "total".
+    # VRAM: unit-aware parsing across amd-smi formats. Newer versions use
+    # "mem_usage" with "total_vram"/"used_vram"; older use "vram" or
+    # "fb_memory_usage" with "used"/"total".
     vram_data = gpu_data.get(
         "mem_usage",
         gpu_data.get("vram", gpu_data.get("fb_memory_usage", {})),
@@ -235,12 +228,11 @@ def _extract_gpu_metrics(gpu_data: dict) -> dict[str, Any]:
 
 
 def _has_real_metrics(metrics: dict[str, Any]) -> bool:
-    """Return True when ``metrics`` contains at least one non-None value.
+    """Return True when ``metrics`` has at least one non-None value.
 
-    ``amd-smi`` can return a zero-exit JSON envelope missing every expected
-    field (error response, unsupported card, hipless container). Then
-    ``_extract_gpu_metrics`` produces an all-``None`` dict -- callers must
-    surface this as ``available: False``, not ``available: True`` with empty data.
+    amd-smi can return a zero-exit envelope missing every field (error,
+    unsupported card, hipless container), yielding an all-None dict; callers must
+    surface that as ``available: False``.
     """
     return any(value is not None for value in metrics.values())
 
@@ -252,9 +244,8 @@ def get_physical_gpu_count() -> Optional[int]:
         return None
     if isinstance(data, list):
         return len(data)
-    # Some versions return a dict with a "gpu" / "gpus" key. Guard .get()
-    # with isinstance so a malformed scalar/string response cannot raise
-    # AttributeError.
+    # Some versions return a dict with a "gpu"/"gpus" key; guard with isinstance
+    # so a malformed scalar/string response can't raise AttributeError.
     if not isinstance(data, dict):
         return None
     gpus = data.get("gpu", data.get("gpus", []))
@@ -282,10 +273,8 @@ def _first_visible_amd_gpu_id() -> Optional[str]:
         raw = raw.strip()
         if raw == "" or raw == "-1":
             return None
-        # Drop empty tokens after splitting. Tolerates minor typos like
-        # ``HIP_VISIBLE_DEVICES=",1"`` (leading comma, clearly meant device 1)
-        # while still falling through to the next env var when every token is
-        # empty (e.g. ``,,,``).
+        # Drop empty tokens, tolerating typos like ``",1"`` while still falling
+        # through to the next env var when every token is empty (``,,,``).
         tokens = [t.strip() for t in raw.split(",") if t.strip()]
         if tokens:
             return tokens[0]
@@ -316,9 +305,8 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 
     metrics = _extract_gpu_metrics(gpu_data)
     if not _has_real_metrics(metrics):
-        # JSON envelope with no usable fields (error response or unsupported
-        # card). Surface as unavailable rather than available-with-empty-data
-        # so the UI does not render a ghost device.
+        # Envelope with no usable fields: surface as unavailable so the UI
+        # doesn't render a ghost device.
         return {"available": False}
     metrics["available"] = True
     return metrics
@@ -347,14 +335,11 @@ def get_visible_gpu_utilization(
             "index_kind": "physical",
         }
 
-    # Extract a device list from amd-smi's envelope. Newer versions return a
-    # JSON array directly; older versions wrap the list in a dict under
-    # "gpus" / "gpu". Guard non-dict / non-list envelopes (scalar/string
-    # fallbacks from malformed output) so .get() cannot raise AttributeError.
+    # Extract a device list across envelope shapes: a JSON array, a dict under
+    # "gpu_data"/"gpus"/"gpu", or a guarded scalar/string fallback.
     if isinstance(data, list):
         gpu_list = data
     elif isinstance(data, dict):
-        # Newer amd-smi wraps output in {"gpu_data": [...]}
         gpu_list = data.get("gpu_data", data.get("gpus", data.get("gpu", [data])))
     else:
         gpu_list = [data]
@@ -363,15 +348,11 @@ def get_visible_gpu_utilization(
 
     devices = []
     for fallback_idx, gpu_data in enumerate(gpu_list):
-        # Skip non-dict entries: a scalar inside the "gpus" array (seen on
-        # some malformed output) would make _extract_gpu_metrics raise
-        # AttributeError on the first .get() call.
+        # Skip non-dict entries (a scalar in the array would raise AttributeError).
         if not isinstance(gpu_data, dict):
             continue
-        # Use AMD-reported GPU ID when available, else the enumeration index.
-        # Newer amd-smi wraps scalars as ``{"value": 0, "unit": "none"}``, so
-        # route raw_id through ``_parse_numeric`` which handles bare ints,
-        # floats, strings, and that dict shape uniformly.
+        # Use the AMD-reported GPU ID, else the enumeration index. _parse_numeric
+        # handles bare ints/floats/strings and the {"value", "unit"} dict shape.
         raw_id = gpu_data.get("gpu", gpu_data.get("gpu_id", gpu_data.get("id", fallback_idx)))
         parsed_id = _parse_numeric(raw_id)
         if parsed_id is None:
@@ -395,9 +376,8 @@ def get_visible_gpu_utilization(
             continue
         metrics = _extract_gpu_metrics(gpu_data)
         if not _has_real_metrics(metrics):
-            # Skip ghost entries: a dict response with no usable fields
-            # (error envelope, etc.) would otherwise show up as a device row
-            # with all-None numbers in the UI.
+            # Skip ghost entries (no usable fields) so the UI doesn't show an
+            # all-None device row.
             continue
         metrics["index"] = idx
         metrics["index_kind"] = "physical"
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index df3fbac47a..7292fa185f 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -57,11 +57,8 @@ IS_ROCM: bool = False  # True when running on AMD ROCm (HIP) -- routes GPU monit
 def _backend_label(device: DeviceType) -> str:
     """Return the user-facing backend name for API responses.
 
-    ROCm hosts stay ``DeviceType.CUDA`` internally (ROCm torch sets
-    ``torch.cuda.is_available() = True`` and reuses ``torch.cuda.*``), so
-    branching on ``DeviceType`` stays consistent. But "cuda" is misleading
-    in JSON responses on an AMD machine, so this swaps the label to
-    ``"rocm"`` when ``IS_ROCM`` is set, sparing callers the check.
+    ROCm hosts stay ``DeviceType.CUDA`` internally (ROCm reuses ``torch.cuda.*``),
+    but "cuda" is misleading in JSON, so swap to ``"rocm"`` when ``IS_ROCM`` is set.
     """
     if IS_ROCM and device == DeviceType.CUDA:
         return "rocm"
@@ -117,10 +114,8 @@ def detect_hardware() -> DeviceType:
             CHAT_ONLY = False
             device_name = torch.cuda.get_device_properties(0).name
 
-            # Distinguish AMD ROCm (HIP) from NVIDIA CUDA for display only;
-            # DeviceType stays CUDA since torch.cuda.* works on ROCm via HIP.
-            # AMD's repo.radeon.com SDK wheels (e.g. 2.9.0+rocmsdk20251116)
-            # don't set torch.version.hip, so fall back to __version__.
+            # Distinguish ROCm from CUDA for display only (DeviceType stays CUDA).
+            # AMD SDK wheels don't set torch.version.hip, so fall back to __version__.
             _hip_ver = getattr(torch.version, "hip", None)
             if _hip_ver is not None or "rocm" in torch.__version__.lower():
                 IS_ROCM = True
@@ -144,9 +139,8 @@ def detect_hardware() -> DeviceType:
     if is_apple_silicon() and _has_mlx():
         DEVICE = DeviceType.MLX
         CHAT_ONLY = False
-        # platform.processor() (`uname -p`) returns "i386" on most
-        # universal2 / Rosetta Python builds even on native arm64.
-        # platform.machine() is "arm64" once is_apple_silicon() gated us.
+        # Use platform.machine() ("arm64"); platform.processor() returns "i386"
+        # on universal2 / Rosetta builds even on native arm64.
         chip = platform.machine() or "arm64"
         print(f"Hardware detected: MLX — Apple Silicon ({chip})")
         return DEVICE
@@ -191,8 +185,7 @@ def clear_gpu_cache():
         torch.xpu.synchronize()
         torch.xpu.empty_cache()
     elif device == DeviceType.MLX:
-        # MLX manages memory automatically; no empty_cache equivalent,
-        # so the gc.collect() above is enough.
+        # MLX manages memory automatically; gc.collect() above is enough.
         pass
 
 
@@ -271,16 +264,14 @@ def get_gpu_memory_info() -> Dict[str, Any]:
             import mlx.core as mx
             import psutil
 
-            # MLX uses unified memory: total = system RAM, GPU used comes
-            # from IORegistry's AGXAccelerator (system-wide, no sudo).
+            # Unified memory: total = system RAM, GPU used from IORegistry AGX.
             total = psutil.virtual_memory().total
             agx = _read_apple_gpu_stats()
             allocated = agx.get("vram_used_bytes", 0) if agx else 0
 
             try:
                 info = mx.device_info()
-                # See detect_hardware(): platform.processor() can return "i386"
-                # on native arm64 builds, so prefer machine() as fallback.
+                # prefer machine(); processor() can return "i386" on native arm64.
                 gpu_name = info.get("device_name") or platform.machine() or "arm64"
             except Exception:
                 gpu_name = platform.machine() or "arm64"
@@ -409,11 +400,10 @@ def _torch_get_per_device_info(device_indices: list[int]) -> list[Dict[str, Any]
     devices = []
     for ordinal, phys_idx in enumerate(device_indices):
         try:
-            # torch uses 0-based ordinals relative to CUDA_VISIBLE_DEVICES
+            # torch ordinals are 0-based relative to CUDA_VISIBLE_DEVICES.
             props = mod.get_device_properties(ordinal)
             total_bytes = props.total_memory
-            # Prefer mem_get_info (system-wide usage, not just this process)
-            # so auto-selection accounts for other GPU consumers.
+            # Prefer mem_get_info (system-wide) so auto-select sees other consumers.
             if hasattr(mod, "mem_get_info"):
                 free_bytes, total_bytes = mod.mem_get_info(ordinal)
                 used_bytes = total_bytes - free_bytes
@@ -631,13 +621,11 @@ def get_gpu_utilization() -> Dict[str, Any]:
         if result is not None:
             result["backend"] = _backend_label(device)
             if IS_ROCM:
-                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
+                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.).
                 _reconcile_primary_rocm_unified_memory(result, _get_parent_visible_gpu_spec())
             return result
-        # SMI tool unavailable or returned nothing usable. On Windows, query
-        # the Performance Counter API (same source as Task Manager) for
-        # system-wide dedicated VRAM — covers cross-process usage that
-        # torch.cuda.mem_get_info can't see from the Studio server process.
+        # SMI unavailable. On Windows, use Performance Counters (Task Manager
+        # source) for system-wide VRAM, covering cross-process usage torch can't see.
         if IS_ROCM and platform.system() == "Windows":
             _win_used, _win_total = _rocm_windows_perf_counter_vram_gb()
             if _win_used is not None and _win_total is not None:
@@ -699,8 +687,7 @@ def get_gpu_utilization() -> Dict[str, Any]:
                 "power_utilization_pct": None,
             }
 
-    # MLX path: one _read_apple_gpu_stats() call carries both VRAM-used bytes
-    # and GPU utilization %. psutil for unified-memory total is cheap.
+    # MLX: _read_apple_gpu_stats() carries both VRAM-used and GPU util%.
     if device == DeviceType.MLX:
         try:
             import psutil
@@ -790,9 +777,8 @@ def _apply_unified_memory_correction(
 def _reconcile_rocm_unified_memory(utilization: Dict[str, Any], device_indices: list[int]) -> None:
     """Fix amd-smi VRAM for ROCm unified-memory GPUs (e.g. Strix Halo).
 
-    amd-smi reports only the dedicated slice (~512 MB); torch sees the full
-    GTT pool (~128 GB). When torch total > smi total, overwrite per-device
-    VRAM fields so GPU selection uses real available memory.
+    amd-smi reports only the dedicated slice; torch sees the full GTT pool. When
+    torch total > smi total, overwrite per-device VRAM fields with the real value.
     """
     torch_devices = _torch_get_per_device_info(device_indices)
     if not torch_devices:
@@ -814,9 +800,8 @@ def _reconcile_primary_rocm_unified_memory(
         # No visibility env var set: torch ordinal 0 is the primary device.
         primary_idx = [0]
     elif len(numeric_ids) == 0:
-        # Empty mask (HIP_VISIBLE_DEVICES="" or "-1"): no GPU visible to this
-        # process. Querying torch device 0 would raise or return stale data,
-        # so bail rather than write bad values into the utilization dict.
+        # Empty mask: no GPU visible. Querying torch device 0 would raise or
+        # return stale data, so bail rather than write bad values.
         return
     else:
         primary_idx = [int(numeric_ids[0])]
@@ -840,15 +825,14 @@ def get_visible_gpu_utilization() -> Dict[str, Any]:
             result["backend"] = _backend_label(device)
             numeric_ids = parent_visible_spec.get("numeric_ids")
             if IS_ROCM and numeric_ids is not None:
-                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.)
+                # Fix unified-memory VRAM on AMD iGPUs (Strix Halo etc.).
                 _reconcile_rocm_unified_memory(result, numeric_ids)
             return result
 
     # Torch-based fallback for CUDA (nvidia-smi unavailable, AMD ROCm) and XPU (Intel)
     if device in (DeviceType.CUDA, DeviceType.XPU):
         parent_ids = get_parent_visible_gpu_ids()
-        # When parent_visible_ids is empty (UUID/MIG mask or no CVD set),
-        # enumerate torch-visible ordinals so the UI still shows devices.
+        # Empty parent_ids (UUID/MIG mask or no CVD): enumerate torch ordinals.
         if parent_ids:
             torch_indices = parent_ids
             index_kind = "physical"
@@ -935,13 +919,10 @@ _visible_gpu_count: Optional[int] = None
 
 
 def _get_parent_visible_gpu_spec() -> Dict[str, Any]:
-    # ROCm uses HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES on top of
-    # CUDA_VISIBLE_DEVICES (which HIP also respects). Check ROCm env vars
-    # first for multi-GPU AMD setups. Use explicit None checks (not `or`)
-    # so empty string "" is honoured as "no visible GPUs" rather than
-    # falling through to CUDA_VISIBLE_DEVICES.
+    # ROCm uses HIP/ROCR_VISIBLE_DEVICES on top of CUDA_VISIBLE_DEVICES; check
+    # them first. Explicit None checks (not `or`) so "" reads as "no visible GPUs".
     cuda_visible = None
-    # Prefer ROCm masks only on a ROCm host, or when no CUDA mask is set, so a
+    # Prefer ROCm masks only on a ROCm host or when no CUDA mask is set, so a
     # stale HIP_VISIBLE_DEVICES on NVIDIA can't override CUDA_VISIBLE_DEVICES.
     _is_rocm_spec = IS_ROCM or (
         "CUDA_VISIBLE_DEVICES" not in os.environ
@@ -1028,15 +1009,13 @@ def resolve_requested_gpu_ids(gpu_ids: Optional[list[int]]) -> list[int]:
             f"Rejected IDs: {negative_ids}. Parent-visible GPUs: {parent_visible_ids}"
         )
 
-    # Only enforce the physical upper bound when the count is reliable
-    # (from nvidia-smi). A torch count reflects visible devices (filtered by
-    # CUDA_VISIBLE_DEVICES), not the physical total, so e.g. index 3 would be
-    # falsely rejected on a CUDA_VISIBLE_DEVICES="2,3" host reporting
-    # device_count()=2. The parent-visible check below is always authoritative.
+    # Only enforce the physical upper bound when the count is reliable (nvidia-smi).
+    # A torch count reflects only visible devices, so it could falsely reject valid
+    # physical indices. The parent-visible check below is always authoritative.
     if physical_gpu_count > 0 and parent_visible_ids:
         max_parent_id = max(parent_visible_ids)
         if physical_gpu_count > max_parent_id:
-            # Count is plausibly physical (not just visible), so enforce it
+            # Count is plausibly physical, so enforce it.
             out_of_range = [gpu_id for gpu_id in requested_ids if gpu_id >= physical_gpu_count]
             if out_of_range:
                 raise ValueError(
@@ -1115,13 +1094,11 @@ def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = Non
 
 
 def _determine_attention_impl_for_gpu_estimate(config) -> str:
-    # torch.distributed is incomplete on Windows ROCm: torch._C is a C
-    # extension (not a package), so the submodule torch._C._distributed_c10d
-    # that torch.distributed depends on can't be imported. Inject an empty
-    # stub into sys.modules BEFORE importing torch.distributed so the import
-    # succeeds, then patch the missing process-group helpers.
+    # torch.distributed is incomplete on Windows ROCm (torch._C._distributed_c10d
+    # can't be imported). Inject stubs into sys.modules before importing
+    # torch.distributed, then patch the missing process-group helpers.
     if sys.platform == "win32" and IS_ROCM:
-        # Dummy for any name torch.distributed imports from these stubs
+        # Dummy for any name torch.distributed imports from these stubs.
         class _Dummy:
             pass
 
@@ -1132,8 +1109,7 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
         ):
             if _c10d_name not in sys.modules:
                 _stub = types.ModuleType(_c10d_name)
-                # torch.distributed imports these names from _distributed_c10d;
-                # provide no-op dummies so the import doesn't raise AttributeError.
+                # No-op dummies for names torch.distributed imports from _distributed_c10d.
                 for _sym in (
                     "FakeProcessGroup",
                     "ProcessGroup",
@@ -1169,11 +1145,9 @@ def _determine_attention_impl_for_gpu_estimate(config) -> str:
     from unsloth.models._utils import resolve_attention_implementation
     from transformers import AutoModel, AutoModelForCausalLM
 
-    # why: resolve_attention_implementation calls _set_attn_impl, which writes
-    # _attn_implementation onto the config; PreTrainedConfig's setter walks
-    # `sub_configs` and propagates to nested text_config / sub-configs, so a
-    # shallow copy would still mutate those shared inner objects on the cached
-    # config from _load_config_for_gpu_estimate. Deepcopy isolates them.
+    # why: resolve_attention_implementation writes _attn_implementation onto the
+    # config and propagates to nested sub-configs; a shallow copy would still
+    # mutate the cached config's shared inner objects. Deepcopy isolates them.
     config_copy = copy.deepcopy(config)
 
     model_class = None
@@ -1349,31 +1323,29 @@ def estimate_required_model_memory_gb(
                 config
             )
         except Exception as e:
-            # Debug-level: on Windows ROCm the torch.distributed stub lacks
-            # Store, so this fires every estimate call. Expected and
-            # non-actionable -- eager is the safe fallback.
+            # Debug-level: fires every estimate on Windows ROCm (stub lacks Store);
+            # expected and non-actionable -- eager is the safe fallback.
             logger.debug(
                 "Could not resolve attention implementation for '%s': %s",
                 estimate_model,
                 e,
             )
-            # why: if flash attention can't be proven usable, charge the
-            # quadratic non-flash activation path so GPU selection stays
-            # conservative.
+            # why: charge the quadratic non-flash activation path so GPU
+            # selection stays conservative when flash attn isn't proven usable.
             vram_config.attention_implementation = "eager"
     arch = extract_arch_config(config) if config is not None else None
 
     if arch is not None:
         breakdown = estimate_training_vram(arch, vram_config)
-        # why: extract_arch_config only sees text_config; safetensors include
-        # vision/audio tower bytes the text-arch fp16 total misses.
+        # why: extract_arch_config only sees text_config; add the vision/audio
+        # tower bytes that the text-arch fp16 total misses.
         arch_fp16_bytes = compute_total_params(arch) * 2
         extra_bytes = max(0, int(model_size_bytes) - arch_fp16_bytes)
         if extra_bytes > 0:
             breakdown.model_weights += extra_bytes
             if training_method == "full":
-                # why: full fine-tuning makes the extra (vision/audio) params
-                # trainable; optimizer + gradient bytes scale with them.
+                # why: full fine-tuning makes extra params trainable; optimizer +
+                # gradient bytes scale with them.
                 extra_params = extra_bytes // 2
                 breakdown.optimizer_states += compute_optimizer_bytes(
                     extra_params,
@@ -1392,7 +1364,7 @@ def estimate_required_model_memory_gb(
             )
         return required_gb, metadata
 
-    # Fallback when model config is unavailable
+    # Fallback when model config is unavailable.
     overhead_gb = CUDA_OVERHEAD_BYTES / (1024**3)
     if training_method == "full":
         required_gb = model_size_gb * 3.5 + overhead_gb
@@ -1452,8 +1424,7 @@ def auto_select_gpu_ids(
         return None, metadata
 
     if required_gb is None:
-        # Cannot estimate model size -- fall back to all visible GPUs rather
-        # than risk loading on a single GPU that may lack memory.
+        # Can't estimate size -- use all visible GPUs rather than risk one too small.
         parent_ids = get_parent_visible_gpu_ids()
         metadata["selection_mode"] = "fallback_all"
         metadata["selected_gpu_ids"] = parent_ids
@@ -1491,16 +1462,13 @@ def auto_select_gpu_ids(
     free_by_index = {item["index"]: item["free_gb"] for item in ranked}
     selected: list[int] = []
     usable_gb = 0.0
-    # Multi-GPU sharding has inter-GPU communication overhead (NCCL
-    # all-reduce, PCIe/NVLink transfers, sync barriers), so each extra GPU
-    # contributes less than its raw free memory; the first GPU keeps full
-    # capacity. 0.85 was calibrated empirically on 2-8 GPU NVLink/PCIe
-    # setups -- the 15% discount covers NCCL buffers (~2-5% of VRAM),
-    # pipeline bubble overhead, and fragmentation from non-uniform shards.
+    # Sharding has inter-GPU overhead, so each extra GPU contributes less than
+    # its raw free memory (first GPU keeps full capacity). 0.85 is empirical on
+    # 2-8 GPU setups: covers NCCL buffers, pipeline bubbles, fragmentation.
     multi_gpu_overhead = 0.85
 
-    # Per-GPU check: activations don't shard, so each GPU needs its weight
-    # shard + full activation cost. Uses precomputed min_per_gpu_N values.
+    # Per-GPU check: activations don't shard, so each GPU needs its weight shard
+    # + full activation cost. Uses precomputed min_per_gpu_N values.
     vram_breakdown = estimate_metadata.get("vram_breakdown", {})
 
     for candidate in ranked:
@@ -1537,7 +1505,7 @@ def auto_select_gpu_ids(
             )
             return selected, metadata
 
-    # Use only GPUs with verified VRAM data (gpu_candidates, not raw devices)
+    # Use only GPUs with verified VRAM data.
     fallback_all = [c["index"] for c in gpu_candidates] if gpu_candidates else parent_ids
     metadata["selection_mode"] = "fallback_all"
     if ranked:
@@ -1642,7 +1610,7 @@ def get_physical_gpu_count() -> int:
                 return _physical_gpu_count
         except Exception:
             pass
-        # SMI tool unavailable or failed -- fall back to torch
+        # SMI unavailable -- fall back to torch.
         count = _torch_get_physical_gpu_count()
         _physical_gpu_count = count if count is not None else 1
         return _physical_gpu_count
@@ -1678,7 +1646,7 @@ def get_backend_visible_gpu_info() -> Dict[str, Any]:
     device = get_device()
     if device in (DeviceType.CUDA, DeviceType.XPU):
         parent_visible_ids = get_parent_visible_gpu_ids()
-        # Try native SMI tool first (nvidia-smi for NVIDIA, skipped for ROCm)
+        # Try native SMI first (nvidia-smi; skipped for ROCm).
         if device == DeviceType.CUDA and not IS_ROCM:
             try:
                 from . import nvidia
@@ -1694,9 +1662,8 @@ def get_backend_visible_gpu_info() -> Dict[str, Any]:
             except Exception as e:
                 logger.warning("Backend GPU visibility query failed: %s", e)
 
-        # Torch fallback (AMD ROCm, Intel XPU, nvidia-smi missing/failed).
-        # When parent_visible_ids is empty (UUID/MIG mask), enumerate by
-        # torch ordinal so the UI still shows devices.
+        # Torch fallback (ROCm, XPU, nvidia-smi missing). Empty parent_visible_ids
+        # (UUID/MIG mask) -> enumerate by torch ordinal so the UI shows devices.
         if parent_visible_ids:
             torch_indices = parent_visible_ids
             index_kind = "physical"
@@ -1814,9 +1781,8 @@ def apply_gpu_ids(gpu_ids) -> None:
     if gpu_ids is None:
         return
 
-    # Empty list means "no GPUs visible" -- treat like None (inherit parent)
-    # to avoid setting CUDA_VISIBLE_DEVICES="", which disables CUDA entirely
-    # and crashes downstream torch calls.
+    # Empty list -> treat like None (inherit parent); setting CUDA_VISIBLE_DEVICES=""
+    # disables CUDA entirely and crashes downstream torch calls.
     if isinstance(gpu_ids, (list, tuple)) and len(gpu_ids) == 0:
         return
 
@@ -1828,23 +1794,16 @@ def apply_gpu_ids(gpu_ids) -> None:
         value = str(gpu_ids)
 
     os.environ["CUDA_VISIBLE_DEVICES"] = value
-    # Keep ROCm visibility env vars in sync so _get_parent_visible_gpu_spec()
-    # picks up the narrowed set on AMD. Workers may call apply_gpu_ids()
-    # before detect_hardware() runs (IS_ROCM still default False), so also
-    # mirror the selection whenever the parent already set a ROCm visibility
-    # var -- a downstream ROCm process then inherits the narrowed mask before
-    # hardware detection classifies the host. Final fallback: probe
-    # torch.version.hip so AMD workers without HIP_VISIBLE_DEVICES still get
-    # the correct ROCm visibility mask.
+    # Keep ROCm visibility env vars in sync. Workers may call apply_gpu_ids()
+    # before detect_hardware() (IS_ROCM still False), so also mirror when the
+    # parent set a ROCm visibility var, with a torch.version.hip probe fallback.
     _inherits_rocm_visibility = (
         "HIP_VISIBLE_DEVICES" in os.environ or "ROCR_VISIBLE_DEVICES" in os.environ
     )
     _is_rocm = IS_ROCM or _inherits_rocm_visibility
     if not _is_rocm:
-        # torch.version.hip is a non-empty string on ROCm, None on CUDA.
-        # AMD SDK / Radeon ROCm wheels may leave it unset but still encode
-        # "rocm" in torch.__version__ (matching detect_hardware()).
-        # Broad except: a probe failure must never crash a training worker.
+        # torch.version.hip is set on ROCm, None on CUDA; AMD SDK wheels may leave
+        # it unset but encode "rocm" in __version__. Broad except: never crash a worker.
         try:
             import torch as _torch
             _is_rocm = (
@@ -1887,8 +1846,8 @@ def get_device_map(gpu_ids: Optional[list[int]] = None) -> str:
         multi_gpu = gpu_ids is not None and len(gpu_ids) > 1
 
         if not multi_gpu:
-            # UUID/MIG masks can't be split into numeric IDs, so if multiple
-            # GPUs are visible we assume multi-GPU sharding is intended.
+            # UUID/MIG masks can't be split into numeric IDs; >1 visible GPU
+            # means multi-GPU sharding is intended.
             parent_visible_spec = _get_parent_visible_gpu_spec()
             if parent_visible_spec["numeric_ids"] is None and get_visible_gpu_count() > 1:
                 multi_gpu = True
diff --git a/studio/backend/utils/hardware/nvidia.py b/studio/backend/utils/hardware/nvidia.py
index b8f307df9e..f98ca4343e 100644
--- a/studio/backend/utils/hardware/nvidia.py
+++ b/studio/backend/utils/hardware/nvidia.py
@@ -110,9 +110,8 @@ def get_primary_gpu_utilization() -> dict[str, Any]:
 def get_visible_gpu_utilization(
     parent_visible_ids: Optional[list[int]], parent_cuda_visible_devices: Optional[str] = None
 ) -> dict[str, Any]:
-    # parent_visible_ids None (UUID/MIG mask): can't safely map
-    # nvidia-smi rows to visible devices. Return empty rather than
-    # exposing all physical GPUs.
+    # parent_visible_ids None (UUID/MIG mask): can't map nvidia-smi rows to
+    # visible devices, so return empty rather than exposing all physical GPUs.
     if parent_visible_ids is None:
         return {
             "available": False,
@@ -196,8 +195,8 @@ def get_visible_gpu_utilization(
 def get_backend_visible_gpu_info(
     parent_visible_ids: Optional[list[int]], backend_cuda_visible_devices: Optional[str]
 ) -> dict[str, Any]:
-    # parent_visible_ids None (UUID/MIG mask): can't safely map
-    # nvidia-smi rows to visible devices.
+    # parent_visible_ids None (UUID/MIG mask): can't map nvidia-smi rows to
+    # visible devices.
     if parent_visible_ids is None:
         return {
             "available": False,
diff --git a/studio/backend/utils/hardware/vram_estimation.py b/studio/backend/utils/hardware/vram_estimation.py
index 51903e0c97..86069ead3d 100644
--- a/studio/backend/utils/hardware/vram_estimation.py
+++ b/studio/backend/utils/hardware/vram_estimation.py
@@ -59,8 +59,7 @@ OPTIMIZER_BYTES_PER_PARAM: Dict[str, int] = {
 }
 
 # (full_ft_multiplier, lora_multiplier) — fraction of num_layers.
-# LoRA: frozen base layers skip activation storage, but ~1 layer is always
-# in flight during backprop recomputation.
+# LoRA: frozen layers skip activation storage, but ~1 is in flight during backprop.
 GC_LAYER_MULTIPLIERS = {
     "none": (None, None),
     "true": (2.0, 1.0),
@@ -181,8 +180,7 @@ def _max_scalar(value):
 def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
     """Layer indices that use dense MLP instead of MoE. Position matters."""
     # Exaone-MoE / Laguna / Hy_v3 / GLM-MoE-DSA / GLM4-MoE-Lite / Ernie4_5_VL_MoE
-    # prefer per-position `mlp_layer_types` over prefix-style
-    # `first_k_dense_replace` and may omit `decoder_sparse_step` entirely.
+    # prefer per-position `mlp_layer_types` over prefix `first_k_dense_replace`.
     layer_types = getattr(text_config, "mlp_layer_types", None)
     if layer_types:
         return tuple(
@@ -197,10 +195,9 @@ def _compute_dense_layer_indices(text_config, total_layers: int) -> tuple:
         moe_indices = {int(i) for i in llama4_moe_layers}
         return tuple(i for i in range(total_layers) if i not in moe_indices)
 
-    # ERNIE 4.5 MoE / ERNIE 4.5 VL MoE declare MoE layers via
-    # moe_layer_start_index / moe_layer_end_index / moe_layer_interval; the
-    # per-layer guard is `(layer_idx + 1) % interval == 0` with
-    # start <= layer_idx <= end (modeling_ernie4_5_moe.py).
+    # ERNIE 4.5 (VL) MoE: layers via moe_layer_start/end_index + interval;
+    # per-layer guard `(layer_idx+1) % interval == 0` within [start, end]
+    # (modeling_ernie4_5_moe.py).
     moe_start = getattr(text_config, "moe_layer_start_index", None)
     moe_interval = getattr(text_config, "moe_layer_interval", None)
     if moe_start is not None and moe_interval is not None and int(moe_interval) > 0:
@@ -296,9 +293,8 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
     shared_expert_intermediate_size = _moe_attr("shared_expert_intermediate_size")
     if shared_expert_intermediate_size and n_shared_experts == 0:
         n_shared_experts = 1
-    # DBRX exposes moe_top_k; Hunyuan-V1-MoE exposes moe_topk (can be a
-    # per-layer list). _max_scalar normalizes lists to the worst case so
-    # int(...) below cannot crash on the canonical attribute_map path.
+    # DBRX moe_top_k; Hunyuan-V1-MoE moe_topk (may be a per-layer list).
+    # _max_scalar normalizes lists to the worst case so int(...) can't crash.
     num_experts_per_tok = (
         _max_scalar(_moe_attr("num_experts_per_tok"))
         or _max_scalar(_moe_attr("top_k_experts"))
@@ -312,9 +308,8 @@ def extract_arch_config(hf_config) -> Optional[ModelArchConfig]:
         dense_layer_indices = _compute_dense_layer_indices(text_config, num_layers)
     num_dense_layers = len(dense_layer_indices)
 
-    # Llama4 dense layers use intermediate_size_mlp; routed/shared experts use
-    # intermediate_size. Llama4TextMoe builds one shared_expert per MoE layer
-    # (modeling_llama4.py).
+    # Llama4 dense layers use intermediate_size_mlp; experts use
+    # intermediate_size. One shared_expert per MoE layer (modeling_llama4.py).
     intermediate_size_mlp_raw = _first_scalar(_moe_attr("intermediate_size_mlp"))
     dense_intermediate_size = (
         int(intermediate_size_mlp_raw) if intermediate_size_mlp_raw is not None else None
@@ -458,10 +453,8 @@ def _per_layer_input_norm_elements(arch: ModelArchConfig) -> int:
 
 
 def _per_layer_input_lora_params(arch: ModelArchConfig, r: int, target_modules) -> int:
-    # Unsloth's get_peft_regex (unsloth_zoo/peft_utils.py) requires module
-    # names to contain a component tag (mlp/attn/...); PLE names lack any tag,
-    # so all-linear does NOT attach LoRA to them. Only count PLE LoRA when the
-    # user explicitly names PLE modules.
+    # get_peft_regex requires a component tag (mlp/attn/...); PLE names lack
+    # one, so all-linear skips them. Count PLE LoRA only when named explicitly.
     pli = arch.hidden_size_per_layer_input
     if pli <= 0:
         return 0
@@ -541,18 +534,16 @@ def _module_path_matches(skip_module: str, alias: str) -> bool:
     if alias_parts[0] == "layers":
         return skip_parts == alias_parts
     if len(skip_parts) <= len(alias_parts):
-        # BNB quantizer suffix-matches short skip entries like ["q_proj"] /
-        # ["lm_head"] against full paths, so a skip shorter than the alias is
-        # a tail match.
+        # BNB suffix-matches short skip entries (["q_proj"], ["lm_head"]) so a
+        # skip shorter than the alias is a tail match.
         return alias_parts[-len(skip_parts) :] == skip_parts
     if skip_parts[-len(alias_parts) :] != alias_parts:
         return False
     prefix_parts = skip_parts[: len(skip_parts) - len(alias_parts)]
     if not prefix_parts:
         return True
-    # Bound the prefix to known text-tower roots so VLM skip names like
-    # vision_tower.model.layers.<i>.self_attn.q_proj don't shadow the text
-    # alias model.layers.<i>.self_attn.q_proj.
+    # Bound the prefix to text-tower roots so VLM skips like
+    # vision_tower.model.layers... don't shadow the text alias.
     return ".".join(prefix_parts) in _SKIP_MODULE_TEXT_PREFIXES
 
 
@@ -585,9 +576,8 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
         mlp_dims = {name: dim for name, dim in dims.items() if name in MLP_TARGET_MODULES}
 
         if is_mla:
-            # _text_linear_dims uses (hd, hd) for q/o; MLA splits into
-            # q_a/q_b/kv_a/kv_b, so emit a single self_attn aggregate at the
-            # authoritative MLA per-layer total.
+            # MLA splits q/o into q_a/q_b/kv_a/kv_b; emit a single self_attn
+            # aggregate at the authoritative MLA per-layer total.
             layer_modules["self_attn"] = _compute_attn_elements(arch)
         else:
             for name, (in_dim, out_dim) in attn_dims.items():
@@ -605,17 +595,13 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
                 layer_modules["mlp.experts"] = _compute_routed_moe_elements(arch)
                 shared_moe = _compute_shared_moe_elements(arch)
                 if shared_moe:
-                    # Qwen3.5-MoE exposes shared expert as mlp.shared_expert;
-                    # Exaone-MoE/Laguna/GLM-style use mlp.shared_experts.
-                    # Register both names so child-path llm_int8_skip_modules
-                    # entries match the right shared block.
+                    # Qwen3.5-MoE: mlp.shared_expert; Exaone-MoE/Laguna/GLM:
+                    # mlp.shared_experts. Register both so skip_modules match.
                     layer_modules["mlp.shared_expert"] = shared_moe
                 if arch.moe_has_dense_mlp:
-                    # enable_moe_block runs the dense MLP and MoE experts in
-                    # parallel; register both for skip matching. Non-structured
-                    # _text_linear_dims returns mlp_size from _get_mlp_size
-                    # (prefers moe_intermediate_size), so rebuild dense dims
-                    # from arch.intermediate_size directly.
+                    # enable_moe_block runs dense MLP and experts in parallel;
+                    # register both. Non-structured _get_mlp_size prefers
+                    # moe_intermediate_size, so rebuild dense dims directly.
                     if _uses_structured_layer_shapes(arch):
                         dense_dims = mlp_dims
                     else:
@@ -648,10 +634,9 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
             for name, value in layer_modules.items()
             if name == "self_attn" or name.startswith("self_attn.")
         )
-        # gemma4 enable_moe_block puts routed experts at the sibling
-        # layers.<i>.experts attribute, not under self.mlp; the layer's "mlp"
-        # aggregate must reflect only the dense MLP path so a skip module
-        # `model.layers.0.mlp` doesn't over-skip into the experts block.
+        # gemma4 enable_moe_block puts routed experts at sibling
+        # layers.<i>.experts, not under self.mlp; keep the "mlp" aggregate to
+        # the dense path so a `model.layers.0.mlp` skip doesn't over-skip.
         is_sibling_experts = bool(arch.moe_has_dense_mlp)
         mlp_total = sum(
             value
@@ -681,12 +666,10 @@ def _build_text_module_elements(arch: ModelArchConfig) -> tuple[Dict[str, int],
             elements[canonical] = value
             _add_module_aliases(aliases, canonical, canonical.removeprefix("text."))
             if name == "mlp.experts" and arch.moe_has_dense_mlp:
-                # gemma4 enable_moe_block exposes routed experts at
-                # layers.<i>.experts (sibling of self.mlp), not under mlp.
+                # gemma4: routed experts at sibling layers.<i>.experts, not mlp.
                 _add_module_aliases(aliases, canonical, f"layers.{layer_idx}.experts")
             elif name == "mlp.shared_expert":
-                # Exaone-MoE / Laguna / GLM-style use the plural
-                # `shared_experts` attribute name; register both spellings.
+                # Exaone-MoE/Laguna/GLM use plural `shared_experts`; add both.
                 _add_module_aliases(
                     aliases,
                     canonical,
@@ -780,9 +763,7 @@ def _compute_shared_moe_elements(arch: ModelArchConfig) -> int:
     hd = arch.hidden_size
     shared_size = _shared_expert_size(arch)
     total = hd * shared_size * 3 * arch.n_shared_experts
-    # Only Qwen2-MoE / Qwen3.5-MoE define a shared_expert_gate Linear
-    # (hidden_size->1); other families (Exaone-MoE, HY-V3, GLM4-MoE-Lite,
-    # Laguna) have shared_experts without a gate.
+    # Only Qwen2/Qwen3.5-MoE add a shared_expert_gate Linear (hidden_size->1);
     # shared_expert_intermediate_size is the Qwen-style discriminator.
     if arch.shared_expert_intermediate_size:
         total += arch.n_shared_experts * hd
@@ -1078,17 +1059,16 @@ def _layer_qkv_mlp_sizes(arch: ModelArchConfig, layer_idx: int) -> tuple:
     is_moe_layer = n_experts > 1 and not _is_dense_mlp_layer(arch, layer_idx)
     if _uses_structured_layer_shapes(arch):
         q_size, kv_size, _has_k, _has_v = _layer_attention_dims(arch, layer_idx)
-        # KV-shared layers (Gemma4/Gemma3n) drop k_proj/v_proj WEIGHTS but the
-        # donor layer's K/V tensors stay alive across the shared range, so
-        # activation memory still pays kv_size; only the weight path uses
-        # has_k/has_v.
+        # KV-shared layers (Gemma4/Gemma3n) drop k/v WEIGHTS but the donor's
+        # K/V tensors stay alive, so activations still pay kv_size; only the
+        # weight path uses has_k/has_v.
         layer_type = _layer_types(arch)[layer_idx]
         use_alt_attention = arch.attention_k_eq_v and layer_type != "sliding_attention"
         kv_count = 1 if use_alt_attention else 2
         qkv_size = q_size + kv_size * kv_count
         if is_moe_layer:
-            # Each token routes through `num_experts_per_tok` experts; their
-            # gate/up/down intermediates are all live during MLP forward.
+            # Each token routes through num_experts_per_tok experts; all their
+            # gate/up/down intermediates are live during MLP forward.
             mlp_size = _get_mlp_size(arch) * arch.num_experts_per_tok
             if arch.n_shared_experts:
                 mlp_size += _shared_expert_size(arch) * arch.n_shared_experts
@@ -1116,9 +1096,8 @@ def _per_layer_activation_bytes(
     activation_qkv = seq_len * batch_size * qkv_size
     residual_memory = (seq_len * batch_size) * 2
     activation_mlp = seq_len * batch_size * (mlp_size + mlp_size)
-    # per_layer_input_gate (hd-sized) and per_layer_projection (pli-sized)
-    # outputs materialize once per decoder layer when
-    # hidden_size_per_layer_input is set; see gemma4/modular_gemma4.py:1141-1145.
+    # PLE gate (hd) + projection (pli) outputs materialize once per decoder
+    # layer when hidden_size_per_layer_input is set (gemma4 modular:1141-1145).
     pli = arch.hidden_size_per_layer_input
     activation_ple = seq_len * batch_size * (arch.hidden_size + pli) if pli > 0 else 0
     return int((activation_qkv + residual_memory + activation_mlp + activation_ple) * 2 * 1.25)
diff --git a/studio/backend/utils/inference/inference_config.py b/studio/backend/utils/inference/inference_config.py
index 87e2aac833..05eb08067c 100644
--- a/studio/backend/utils/inference/inference_config.py
+++ b/studio/backend/utils/inference/inference_config.py
@@ -1,13 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Inference configuration loading utilities.
-
-Loads inference parameters (temperature, top_p, top_k, min_p) from model YAML
-configs, falling back to default.yaml. Includes family-based lookup from
-inference_defaults.json for GGUF models.
-"""
+"""Load inference params (temperature, top_p, top_k, min_p) from model YAML, family defaults, or default.yaml."""
 
 from pathlib import Path
 from typing import Dict, Any, Optional
@@ -48,17 +42,10 @@ def _load_family_defaults():
 
 
 def get_family_inference_params(model_id: str) -> Dict[str, Any]:
-    """
-    Look up recommended inference parameters by model family.
+    """Look up recommended inference params by model family.
 
     Extracts the family from the identifier (e.g. "unsloth/Qwen3.5-9B-GGUF" ->
-    "qwen3.5") and returns the matching params from inference_defaults.json.
-
-    Args:
-        model_id: Model identifier (e.g. "unsloth/Qwen3.5-9B-GGUF")
-
-    Returns:
-        Dict with inference params, or empty dict if no family match.
+    "qwen3.5") and returns matching params from inference_defaults.json, or {}.
     """
     _load_family_defaults()
 
@@ -87,13 +74,11 @@ def _has_specific_yaml(model_identifier: str) -> bool:
     script_dir = Path(__file__).parent.parent.parent
     defaults_dir = script_dir / "assets" / "configs" / "model_defaults"
 
-    # Check the mapping.
     if model_identifier.lower() in _REVERSE_MODEL_MAPPING:
         return True
 
-    # For local paths (e.g. C:\Users\...\model on Windows), normalize backslashes
-    # so Path().parts splits correctly on POSIX/WSL, then match the last 1-2 path
-    # components against the registry (mirrors load_model_defaults).
+    # For local paths, normalize backslashes so Path().parts splits correctly,
+    # then match the last 1-2 components against the registry (mirrors load_model_defaults).
     _is_local = is_local_path(model_identifier)
     _normalized = normalize_path(model_identifier) if _is_local else model_identifier
 
@@ -108,8 +93,7 @@ def _has_specific_yaml(model_identifier: str) -> bool:
     else:
         _lookup = model_identifier
 
-    # Exact filename match (basename for local paths; passing absolute paths to
-    # rglob raises "Non-relative patterns are unsupported" on Windows).
+    # Exact filename match (basename for local paths; absolute paths break rglob on Windows).
     model_filename = _lookup.replace("/", "_") + ".yaml"
     for config_path in defaults_dir.rglob(model_filename):
         if config_path.is_file():
@@ -119,27 +103,11 @@ def _has_specific_yaml(model_identifier: str) -> bool:
 
 
 def load_inference_config(model_identifier: str) -> Dict[str, Any]:
+    """Load inference params for a model.
+
+    Priority: model-specific YAML, then family defaults (inference_defaults.json),
+    then default.yaml. Returns a dict of temperature/top_p/top_k/min_p/etc.
     """
-    Load inference configuration parameters for a model.
-
-    Priority chain:
-    1. Model-specific YAML (if it exists and has inference params).
-    2. Family-based defaults from inference_defaults.json.
-    3. default.yaml fallback.
-
-    Args:
-        model_identifier: Model identifier (e.g., "unsloth/llama-3-8b-bnb-4bit")
-
-    Returns:
-        Dict of inference parameters:
-        {
-            "temperature": float,
-            "top_p": float,
-            "top_k": int,
-            "min_p": float
-        }
-    """
-    # Model defaults for inference parameters.
     model_defaults = load_model_defaults(model_identifier)
 
     # default.yaml for fallback values.
diff --git a/studio/backend/utils/llama_cpp_freshness.py b/studio/backend/utils/llama_cpp_freshness.py
index 3635969c73..3e5066ca2d 100644
--- a/studio/backend/utils/llama_cpp_freshness.py
+++ b/studio/backend/utils/llama_cpp_freshness.py
@@ -53,10 +53,7 @@ def read_install_marker(binary_path: Optional[str]) -> Optional[dict]:
         return cached
     p = Path(binary_path)
     marker: Optional[dict] = None
-    # Cover all _find_llama_server_binary layouts:
-    #   <install>/llama-server                          (1 up)
-    #   <install>/build/bin/llama-server                (3 up, Linux/macOS cmake)
-    #   <install>/build/bin/Release/llama-server.exe   (4 up, Windows cmake)
+    # Cover all _find_llama_server_binary layouts (binary is 1-4 dirs deep):
     for parent in p.parents[:5]:
         candidate = parent / _INSTALL_MARKER_NAME
         if candidate.is_file():
diff --git a/studio/backend/utils/models/__init__.py b/studio/backend/utils/models/__init__.py
index 808e2b012e..74d08ac116 100644
--- a/studio/backend/utils/models/__init__.py
+++ b/studio/backend/utils/models/__init__.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Model and LoRA configuration handling
-"""
+"""Model and LoRA configuration handling."""
 
 from .model_config import (
     ModelConfig,
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index 80312af0f7..5a992926ec 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -14,11 +14,7 @@ logger = get_logger(__name__)
 
 
 def _read_checkpoint_loss(checkpoint_path: Path) -> Optional[float]:
-    """
-    Read training loss from a checkpoint's trainer_state.json.
-
-    Returns the loss from the last log_history entry, or None if unavailable.
-    """
+    """Read loss from the last log_history entry of trainer_state.json, or None."""
     trainer_state = checkpoint_path / "trainer_state.json"
     if not trainer_state.exists():
         return None
@@ -36,14 +32,13 @@ def _read_checkpoint_loss(checkpoint_path: Path) -> Optional[float]:
 def scan_checkpoints(
     outputs_dir: str = str(outputs_root()),
 ) -> List[Tuple[str, List[Tuple[str, str, Optional[float]]], dict]]:
-    """
-    Scan outputs folder for training runs and their checkpoints.
+    """Scan outputs folder for training runs and their checkpoints.
 
     Returns:
-        List of tuples: [(model_name, [(display_name, checkpoint_path, loss), ...], metadata), ...]
-        metadata keys: base_model, peft_type, lora_rank (all optional)
-        The first entry in each checkpoint list is the main adapter; its loss is
-        set to the loss of the last (highest-step) intermediate checkpoint.
+        [(model_name, [(display_name, checkpoint_path, loss), ...], metadata), ...]
+        metadata keys (optional): base_model, peft_type, lora_rank.
+        First checkpoint entry is the main adapter; its loss mirrors the last
+        (highest-step) intermediate checkpoint.
     """
     models = []
     outputs_path = resolve_output_dir(outputs_dir)
@@ -63,7 +58,7 @@ def scan_checkpoints(
             if not (config_file.exists() or adapter_config.exists()):
                 continue
 
-            # Extract training metadata from adapter_config.json / config.json
+            # Training metadata from adapter_config.json / config.json
             metadata: dict = {}
             try:
                 if adapter_config.exists():
@@ -75,7 +70,7 @@ def scan_checkpoints(
                     cfg = json.loads(config_file.read_text())
                     metadata["base_model"] = cfg.get("_name_or_path")
 
-                # Detect BNB quantization from config.json (present in both cases)
+                # Detect BNB quantization from config.json
                 if config_file.exists():
                     if "cfg" not in dir():
                         cfg = json.loads(config_file.read_text())
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index abddd07367..0df7a1a477 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -472,13 +472,12 @@ def load_model_config(
     from transformers import AutoConfig
 
     if token:
-        # Explicit token provided
         return AutoConfig.from_pretrained(
             model_name, trust_remote_code = trust_remote_code, token = token
         )
 
     if not use_auth:
-        # No authentication (for public model checks)
+        # No auth, for public model checks
         with without_hf_auth():
             return AutoConfig.from_pretrained(
                 model_name,
@@ -486,7 +485,7 @@ def load_model_config(
                 token = None,
             )
 
-    # Default authentication (cached tokens)
+    # Default auth (cached tokens)
     return AutoConfig.from_pretrained(
         model_name,
         trust_remote_code = trust_remote_code,
@@ -626,16 +625,12 @@ except Exception as exc:
 
 
 def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
-    """Run is_vision_model check in a subprocess with transformers 5.x.
+    """Run is_vision_model in a subprocess with transformers 5.x.
 
-    Same pattern as training/inference workers: spawn a clean subprocess
-    with .venv_t5/ prepended to sys.path so AutoConfig recognizes newer
-    architectures (glm4_moe_lite, etc.).
-
-    Returns True/False for definitive results, or None for transient
-    failures (timeouts, subprocess errors) so callers can decide whether
-    to cache. Subprocess failures are treated as transient since they may
-    stem from temporary HF/auth/network issues.
+    Spawns a clean subprocess with .venv_t5/ on sys.path so AutoConfig
+    recognizes newer architectures. Returns True/False for definitive results,
+    or None for transient failures (timeouts, subprocess errors), which are not
+    cached so they can be retried.
     """
     token_arg = hf_token or ""
 
@@ -695,10 +690,8 @@ def _is_vision_model_subprocess(model_name: str, hf_token: Optional[str] = None)
 
 
 def _token_fingerprint(token: Optional[str]) -> Optional[str]:
-    """SHA256 digest of the token for use as a cache key.
-
-    Avoids storing the raw bearer token in process memory as a dict key.
-    """
+    """SHA256 digest of the token for use as a cache key (avoids storing the
+    raw bearer token in process memory)."""
     if token is None:
         return None
     return hashlib.sha256(token.encode("utf-8")).hexdigest()
@@ -714,23 +707,18 @@ _vision_cache_lock = threading.Lock()
 
 def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
     """
-    Detect vision-language models (VLMs) via architecture in config.
-    Works for fine-tuned models since they inherit the base architecture.
-
-    For models that require transformers 5.x (e.g. GLM-4.7-Flash), the check
-    runs in a subprocess with .venv_t5/ activated -- same pattern as the
-    training and inference workers.
+    Detect vision-language models (VLMs) via architecture in config. Works for
+    fine-tuned models since they inherit the base architecture.
 
+    Models needing transformers 5.x are checked in a .venv_t5/ subprocess.
     Results are cached per (model_name, token_fingerprint) for the process
-    lifetime to avoid repeated subprocess spawns and HuggingFace API calls.
-    Transient failures are not cached so they can be retried.
+    lifetime; transient failures are not cached so they can be retried.
 
     Args:
         model_name: Model identifier (HF repo or local path)
-        hf_token: Optional HF token for accessing gated/private models
+        hf_token: Optional HF token for gated/private models
     """
-    # Normalize model name for cache key to avoid duplicate entries for
-    # different casings of the same HF repo (e.g. "Org/Model" vs "org/model").
+    # Normalize model name so different casings of the same repo share a key
     try:
         if is_local_path(model_name):
             resolved_name = normalize_path(model_name)
@@ -745,21 +733,17 @@ def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
         resolved_name = model_name
     cache_key = (resolved_name, _token_fingerprint(hf_token))
 
-    # Lock-free fast path for cache hits. Sentinel distinguishes "key not
-    # found" from "value is False" in a single atomic dict.get() call.
+    # Lock-free fast path for cache hits. Sentinel distinguishes "key not found"
+    # from "value is False" in a single atomic dict.get() call.
     _MISS = object()
     cached = _vision_detection_cache.get(cache_key, _MISS)
     if cached is not _MISS:
         return cached
 
-    # Compute outside the lock to avoid serializing long-running detection
-    # (60s-timeout subprocess spawns, HF API calls) across all models.
-    # Tradeoff: two concurrent calls for the same uncached model may both
-    # run detection, but produce the same result and the second write is a
-    # benign no-op.
+    # Compute outside the lock so long-running detection isn't serialized across
+    # models. Two concurrent calls may both run, but produce the same result.
     result = _is_vision_model_uncached(resolved_name, hf_token)
-    # Only cache definitive results; None means a transient failure, so
-    # retry on the next call instead of locking in a wrong answer.
+    # Only cache definitive results; None is a transient failure, retry later.
     if result is not None:
         with _vision_cache_lock:
             _vision_detection_cache[cache_key] = result
@@ -768,16 +752,13 @@ def is_vision_model(model_name: str, hf_token: Optional[str] = None) -> bool:
 
 
 def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -> Optional[bool]:
-    """Uncached vision model detection -- called by is_vision_model().
+    """Uncached vision detection; use is_vision_model() instead.
 
     Returns True/False for definitive results, or None on transient errors
     (network, timeout, subprocess failure) so the caller knows not to cache.
-
-    Do not call directly; use is_vision_model() instead.
     """
-    # Models needing transformers 5.x must be checked in a subprocess
-    # because AutoConfig in the main process (transformers 4.57.x) doesn't
-    # recognize their architectures.
+    # Models needing transformers 5.x must be checked in a subprocess: the main
+    # process (transformers 4.57.x) doesn't recognize their architectures.
     from utils.transformers_version import needs_transformers_5
 
     if needs_transformers_5(model_name):
@@ -814,7 +795,7 @@ def _is_vision_model_uncached(model_name: str, hf_token: Optional[str] = None) -
     except Exception as e:
         logger.warning(f"Could not determine if {model_name} is vision model: {e}")
         # Permanent failures (not found, gated, bad config) cache as False;
-        # transient failures (network, timeout) should not.
+        # transient ones (network, timeout) should not.
         try:
             from huggingface_hub.errors import RepositoryNotFoundError, GatedRepoError
         except ImportError:
@@ -857,13 +838,11 @@ _AUDIO_TOKEN_PATTERNS = {
 
 
 def detect_audio_type(model_name: str, hf_token: Optional[str] = None) -> Optional[str]:
-    """
-    Detect if a model is an audio model and return its type.
+    """Detect if a model is an audio model and return its type.
 
-    Works for any model, not just known ones. Uses tokenizer_config.json
-    special tokens to detect all 6 audio types.
-
-    Returns: audio_type string ('snac', 'csm', 'bicodec', 'dac', 'whisper', 'audio_vlm') or None.
+    Works for any model via tokenizer_config.json special tokens.
+    Returns an audio_type string ('snac', 'csm', 'bicodec', 'dac', 'whisper',
+    'audio_vlm') or None.
     """
     if model_name in _audio_detection_cache:
         return _audio_detection_cache[model_name]
@@ -877,10 +856,10 @@ def detect_audio_type(model_name: str, hf_token: Optional[str] = None) -> Option
 
 
 def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None) -> Optional[str]:
-    """Detect audio type from tokenizer special tokens (LLM-based audio models).
+    """Detect audio type from tokenizer special tokens.
 
-    Checks local HF cache first, then fetches tokenizer_config.json from
-    HuggingFace. Examines added_tokens_decoder for distinctive patterns.
+    Checks local HF cache first, then fetches tokenizer_config.json from HF;
+    examines added_tokens_decoder for distinctive patterns.
     """
 
     def _check_token_patterns(tok_config: dict) -> Optional[str]:
@@ -919,7 +898,6 @@ def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None
         import os
 
         paths_to_try = ["tokenizer_config.json", "LLM/tokenizer_config.json"]
-        # Use provided token, else env
         token = hf_token or os.environ.get("HF_TOKEN")
         headers = {}
         if token:
@@ -943,10 +921,7 @@ def _detect_audio_from_tokenizer(model_name: str, hf_token: Optional[str] = None
 
 
 def is_audio_input_type(audio_type: Optional[str]) -> bool:
-    """Check if an audio_type accepts audio input (ASR/speech understanding).
-
-    Whisper (ASR) and audio_vlm (Gemma3n) accept audio input.
-    """
+    """True if an audio_type accepts audio input: whisper (ASR), audio_vlm (Gemma3n)."""
     return audio_type in ("whisper", "audio_vlm")
 
 
@@ -955,8 +930,7 @@ def _is_mmproj(filename: str) -> bool:
     return "mmproj" in filename.lower()
 
 
-# Family tokens for #5347's filename fallback. Lowercase. Order does not
-# matter (see ``_detect_family_token``).
+# Family tokens for #5347's filename fallback. Lowercase; order irrelevant.
 _MODEL_FAMILY_TOKENS: tuple[str, ...] = (
     "qwen",
     "gemma",
@@ -989,8 +963,8 @@ _MODEL_FAMILY_TOKENS: tuple[str, ...] = (
 )
 
 
-# Word-bounded match: a letter on either side disqualifies. Stops
-# ``phi`` matching ``sapphire``, ``yi`` matching ``tiny``, etc.
+# Word-bounded match: a letter on either side disqualifies (stops ``phi``
+# matching ``sapphire``, ``yi`` matching ``tiny``).
 _FAMILY_TOKEN_RE_CACHE: Dict[str, "_re.Pattern[str]"] = {}
 
 
@@ -1164,18 +1138,11 @@ def detect_mmproj_file(path: str, search_root: Optional[str] = None) -> Optional
 
 
 def detect_gguf_model(path: str) -> Optional[str]:
-    """
-    Check if the given local path is or contains a GGUF model file.
+    """Check if a local path is or contains a GGUF model file.
 
-    Handles two cases:
-    1. path is a direct .gguf file path
-    2. path is a directory containing .gguf files
-
-    Skips mmproj (vision projection) files — those must be passed via
-    ``--mmproj``, not ``-m``.  Use :func:`detect_mmproj_file` instead.
-
-    Returns the full path to the .gguf file if found, None otherwise.
-    For HuggingFace repo detection, use detect_gguf_model_remote() instead.
+    Handles a direct .gguf path or a directory of .gguf files. Skips mmproj
+    files (pass those via ``--mmproj``; see :func:`detect_mmproj_file`). Returns
+    the .gguf path or None. For HF repos, use detect_gguf_model_remote().
     """
     p = Path(path)
 
@@ -1206,10 +1173,9 @@ def detect_gguf_model(path: str) -> Optional[str]:
     return None
 
 
-# Preferred GGUF quant levels, descending priority. Q4_K_M is a good default
-# (small, fast, acceptable quality). UD (Unsloth Dynamic) variants beat
-# standard quants on quality per bit; repos without UD (e.g. bartowski) fall
-# back to standard quants. Ordered by size/quality tradeoff, not raw quality.
+# Preferred GGUF quant levels, descending priority. UD (Unsloth Dynamic)
+# variants beat standard quants on quality per bit; repos without UD fall back
+# to standard quants. Ordered by size/quality tradeoff, not raw quality.
 _GGUF_QUANT_PREFERENCE = [
     # UD variants (best quality per bit) -- Q4 is the sweet spot
     "UD-Q4_K_XL",
@@ -1253,22 +1219,16 @@ _GGUF_QUANT_PREFERENCE = [
 
 
 def _pick_best_gguf(filenames: list[str]) -> Optional[str]:
-    """
-    Pick the best GGUF file from a list of filenames.
-
-    Prefers quant levels in _GGUF_QUANT_PREFERENCE order; else the first .gguf.
-    """
+    """Pick the best GGUF file: quant levels in _GGUF_QUANT_PREFERENCE order, else first .gguf."""
     gguf_files = [f for f in filenames if f.lower().endswith(".gguf")]
     if not gguf_files:
         return None
 
-    # Try preferred quantization levels
     for quant in _GGUF_QUANT_PREFERENCE:
         for f in gguf_files:
             if quant in f:
                 return f
 
-    # Fallback: first GGUF file
     return gguf_files[0]
 
 
@@ -1378,18 +1338,17 @@ def _list_gguf_variants_from_hf_cache(repo_id: str) -> Optional[tuple[list[GgufV
 def list_gguf_variants(
     repo_id: str, hf_token: Optional[str] = None
 ) -> tuple[list[GgufVariantInfo], bool]:
-    """
-    List all GGUF quantization variants in a HuggingFace repo.
+    """List all GGUF quant variants in a HF repo.
 
-    Separates main model files from mmproj (vision projection) files;
-    mmproj presence indicates a vision-capable model.
+    Separates main model files from mmproj (vision projection) files; mmproj
+    presence flags a vision-capable model.
 
     Returns:
-        (variants, has_vision): list of non-mmproj GGUF variants + vision flag.
+        (variants, has_vision): non-mmproj GGUF variants + vision flag.
     """
     from huggingface_hub import model_info as hf_model_info
 
-    # Offline: skip the API and serve from cache.
+    # Offline: skip the API and serve from cache
     if _env_offline():
         cached = _list_gguf_variants_from_hf_cache(repo_id)
         if cached is not None:
@@ -1422,7 +1381,7 @@ def list_gguf_variants(
     has_vision = False
 
     quant_totals: dict[str, int] = {}  # quant -> total bytes
-    quant_first_file: dict[str, str] = {}  # quant -> first filename (for display)
+    quant_first_file: dict[str, str] = {}  # quant -> first filename (display)
 
     for sibling in info.siblings:
         fname = sibling.rfilename
@@ -1449,8 +1408,8 @@ def list_gguf_variants(
             )
         )
 
-    # Sort by size descending (largest = best quality first). Recommended
-    # pinning and OOM demotion happen client-side where GPU VRAM info exists.
+    # Sort by size descending (largest = best quality first); pinning and OOM
+    # demotion happen client-side where GPU VRAM info exists.
     variants.sort(key = lambda v: -v.size_bytes)
 
     return variants, has_vision
@@ -1478,14 +1437,13 @@ def _resolve_gguf_dir(p: Path) -> Optional[Path]:
 
 
 def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], bool]:
-    """List GGUF quantization variants in a local directory.
+    """List GGUF quant variants in a local directory.
 
-    Mirrors :func:`list_gguf_variants` but reads the filesystem instead of
-    the HuggingFace API. Aggregates shard sizes by quant label so split
-    GGUFs appear as a single variant.
+    Like :func:`list_gguf_variants` but reads the filesystem. Aggregates shard
+    sizes by quant label so split GGUFs appear as one variant.
 
     Returns:
-        (variants, has_vision): list of non-mmproj GGUF variants + vision flag.
+        (variants, has_vision): non-mmproj GGUF variants + vision flag.
     """
     p = _resolve_gguf_dir(Path(directory))
     if p is None:
@@ -1571,20 +1529,11 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
 
 
 def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Optional[str]:
-    """
-    Check if a HuggingFace repo contains GGUF files.
+    """Return the best GGUF filename in a HF repo, or None.
 
-    Returns the filename of the best GGUF file in the repo, or None.
-
-    Retries on transient HF Hub failures (network hiccups, 5xx, slow API
-    cold-start). Without retry, a single transient failure returns None
-    silently and the caller treats the repo as non-GGUF -- which on Apple
-    Silicon (Mac UI route) falls through to the MLX backend, which then
-    fails opening a non-existent config.json on the GGUF-only repo. Three
-    attempts with 1s/2s/4s backoff covers typical free-runner HF Hub flakiness.
-
-    When offline, falls back to the local HF cache so a downloaded repo is
-    still routed to llama-server (not MLX/Unsloth).
+    Retries (3 attempts, 1s/2s/4s backoff) on transient HF Hub failures: a
+    silent None would make the caller treat a GGUF-only repo as non-GGUF and
+    fall through to MLX on Apple Silicon. Offline falls back to the local cache.
     """
     import time
     from huggingface_hub import model_info as hf_model_info
@@ -1602,7 +1551,7 @@ def detect_gguf_model_remote(repo_id: str, hf_token: Optional[str] = None) -> Op
             return _pick_best_gguf(repo_files)
         except Exception as e:
             last_err = e
-            # 404 / RepoNotFound is permanent -- don't retry.
+            # 404 / RepoNotFound is permanent -- don't retry
             err_name = type(e).__name__
             if err_name in (
                 "RepositoryNotFoundError",
@@ -1634,11 +1583,7 @@ def download_gguf_file(
     filename: str,
     hf_token: Optional[str] = None,
 ) -> str:
-    """
-    Download a specific GGUF file from a HuggingFace repo.
-
-    Returns the local path to the downloaded file.
-    """
+    """Download a specific GGUF file from a HF repo; returns the local path."""
     from huggingface_hub import hf_hub_download
 
     local_path = hf_hub_download(
@@ -1654,30 +1599,24 @@ _embedding_detection_cache: Dict[tuple, bool] = {}
 
 
 def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
-    """
-    Detect embedding/sentence-transformer models via HuggingFace metadata.
+    """Detect embedding/sentence-transformer models via HF metadata.
 
-    Combines three signals:
-      1. "sentence-transformers" in model tags
-      2. "feature-extraction" in model tags
-      3. pipeline_tag is "sentence-similarity" or "feature-extraction"
-
-    Catches all known embedding models, including ones like gte-modernbert
-    whose library_name is "transformers" rather than "sentence-transformers".
+    Combines three signals: "sentence-transformers" or "feature-extraction" in
+    tags, or pipeline_tag in {"sentence-similarity", "feature-extraction"}.
+    Catches models like gte-modernbert whose library_name is "transformers".
 
     Args:
         model_name: Model identifier (HF repo or local path)
-        hf_token: Optional HF token for accessing gated/private models
+        hf_token: Optional HF token for gated/private models
 
     Returns:
-        True if embedding model, else False. Defaults to False for local
-        paths or on errors.
+        True if embedding model, else False (default for local paths or errors).
     """
     cache_key = (model_name, hf_token)
     if cache_key in _embedding_detection_cache:
         return _embedding_detection_cache[cache_key]
 
-    # Local paths: check for sentence-transformer marker file (modules.json)
+    # Local paths: check for sentence-transformer marker (modules.json)
     if is_local_path(model_name):
         local_dir = normalize_path(model_name)
         is_emb = os.path.isfile(os.path.join(local_dir, "modules.json"))
@@ -1759,12 +1698,11 @@ def _looks_like_lora_adapter(model_dir: Path) -> bool:
 
 
 def scan_trained_models(outputs_dir: str = str(outputs_root())) -> List[Tuple[str, str, str]]:
-    """
-    Scan outputs folder for trained Studio models.
+    """Scan outputs folder for trained Studio models.
 
     Returns:
-        List of [(display_name, model_path, model_type), ...].
-        model_type is "lora" for adapter runs, "merged" for full finetunes.
+        List of (display_name, model_path, model_type), where model_type is
+        "lora" for adapter runs or "merged" for full finetunes.
     """
     trained_models = []
     outputs_path = resolve_output_dir(outputs_dir)
@@ -1803,16 +1741,14 @@ def scan_trained_models(outputs_dir: str = str(outputs_root())) -> List[Tuple[st
 def scan_exported_models(
     exports_dir: str = str(exports_root()),
 ) -> List[Tuple[str, str, str, Optional[str]]]:
-    """
-    Scan exports folder for exported models (merged, LoRA, GGUF).
+    """Scan exports folder for exported models (merged, LoRA, GGUF).
 
-    Supports two directory layouts:
-      - Two-level: {run}/{checkpoint}/  (merged & LoRA exports)
-      - Flat:      {name}-finetune-gguf/  (GGUF exports)
+    Supports two layouts: two-level {run}/{checkpoint}/ (merged & LoRA) and
+    flat {name}-finetune-gguf/ (GGUF).
 
     Returns:
-        List of [(display_name, model_path, export_type, base_model), ...].
-        export_type: "lora" | "merged" | "gguf"
+        List of (display_name, model_path, export_type, base_model), where
+        export_type is "lora" | "merged" | "gguf".
     """
     results = []
     exports_path = resolve_export_dir(exports_dir)
@@ -1839,7 +1775,7 @@ def scan_exported_models(
                     pass
 
                 display_name = run_dir.name
-                model_path = str(gguf_files[0])  # the .gguf file
+                model_path = str(gguf_files[0])
                 results.append((display_name, model_path, "gguf", base_model))
                 logger.debug(f"Found GGUF export: {display_name}")
                 continue
@@ -1878,8 +1814,8 @@ def scan_exported_models(
                 elif has_gguf:
                     export_type = "gguf"
                     gguf_list = list(_iter_gguf_files(checkpoint_dir))
-                    # Check checkpoint_dir first, then parent run_dir
-                    # (export.py writes metadata to the top-level export dir)
+                    # checkpoint_dir first, then run_dir (export.py writes
+                    # metadata to the top-level export dir)
                     for meta_dir in (checkpoint_dir, run_dir):
                         export_meta = meta_dir / "export_metadata.json"
                         try:
@@ -1899,8 +1835,7 @@ def scan_exported_models(
                 else:
                     continue
 
-                # Fallback: read base model from the training run's
-                # adapter_config.json in ./outputs/{run_name}/
+                # Fallback: base model from ./outputs/{run_name}/adapter_config.json
                 if not base_model:
                     outputs_adapter_cfg = resolve_output_dir(run_dir.name) / "adapter_config.json"
                     try:
@@ -1986,15 +1921,7 @@ def get_base_model_from_checkpoint(checkpoint_path: str) -> Optional[str]:
 
 
 def get_base_model_from_lora(lora_path: str) -> Optional[str]:
-    """
-    Read the base model name from a LoRA adapter's config.
-
-    Args:
-        lora_path: Path to the LoRA adapter directory
-
-    Returns:
-        Base model identifier or None if not found
-    """
+    """Read the base model name from a LoRA adapter's config, or None."""
     try:
         lora_path_obj = Path(lora_path)
 
@@ -2028,13 +1955,10 @@ def get_base_model_from_lora(lora_path: str) -> Optional[str]:
         #     except Exception as e:
         #         logger.warning(f"Could not load training_args.bin: {e}")
 
-        # Last resort: parse from directory name
-        # Format: unsloth_Meta-Llama-3.1-8B-Instruct-bnb-4bit_timestamp
+        # Last resort: parse from dir name (unsloth_<model>_<timestamp>)
         dir_name = lora_path_obj.name
         if dir_name.startswith("unsloth_"):
-            # Drop timestamp suffix (usually _1234567890)
             parts = dir_name.split("_")
-            # Reconstruct model name
             if len(parts) >= 2:
                 model_parts = parts[1:-1]  # Skip "unsloth" and timestamp
                 base_model = "unsloth/" + "_".join(model_parts)
@@ -2054,28 +1978,19 @@ UI_STATUS_INDICATORS = [" (Ready)", " (Loading...)", " (Active)", "↓ "]
 
 
 def load_model_defaults(model_name: str) -> Dict[str, Any]:
-    """
-    Load default training parameters for a model from YAML file.
+    """Load default training parameters for a model from a YAML file.
 
-    Args:
-        model_name: Model identifier (e.g., "unsloth/Meta-Llama-3.1-8B-bnb-4bit")
-
-    Returns:
-        Dict of default parameters from the YAML file, or empty dict if none.
-
-    Looks for a YAML in configs/model_defaults/ (including subfolders) by the
-    model name or its aliases from MODEL_NAME_MAPPING, else falls back to
-    default.yaml.
+    Looks in configs/model_defaults/ (incl. subfolders) by model name or its
+    MODEL_NAME_MAPPING aliases, else falls back to default.yaml. Returns the
+    parameter dict, or {} if none found.
     """
     try:
-        # Locate configs relative to the script dir
         script_dir = Path(__file__).parent.parent.parent
         defaults_dir = script_dir / "assets" / "configs" / "model_defaults"
 
         # Check the mapping first
         if model_name.lower() in _REVERSE_MODEL_MAPPING:
             canonical_file = _REVERSE_MODEL_MAPPING[model_name.lower()]
-            # Search subfolders and root
             for config_path in defaults_dir.rglob(canonical_file):
                 if config_path.is_file():
                     with open(config_path, "r", encoding = "utf-8") as f:
@@ -2165,17 +2080,12 @@ class ModelConfig:
         lora_path: str,
         hf_token: Optional[str] = None,
     ) -> Optional["ModelConfig"]:
-        """
-        Create ModelConfig from a local LoRA adapter path.
-
-        Auto-detects the base model from adapter config.
+        """Create ModelConfig from a local LoRA adapter path, auto-detecting the
+        base model from adapter config.
 
         Args:
-            lora_path: Path to LoRA adapter (e.g., "./outputs/unsloth_Meta-Llama-3.1_.../")
+            lora_path: Path to the LoRA adapter directory
             hf_token: HF token for vision detection
-
-        Returns:
-            ModelConfig for the LoRA adapter
         """
         try:
             lora_path_obj = Path(lora_path)
@@ -2193,14 +2103,14 @@ class ModelConfig:
             audio_type = detect_audio_type(base_model, hf_token = hf_token)
 
             display_name = lora_path_obj.name
-            identifier = lora_path  # path as identifier for local LoRAs
+            identifier = lora_path  # path is the identifier for local LoRAs
 
             return cls(
                 identifier = identifier,
                 display_name = display_name,
                 path = lora_path,
                 is_local = True,
-                is_cached = True,  # local LoRAs are always "cached"
+                is_cached = True,  # local LoRAs are always cached
                 is_vision = is_vision,
                 is_lora = True,
                 is_audio = audio_type is not None and audio_type != "audio_vlm",
@@ -2221,25 +2131,18 @@ class ModelConfig:
         is_lora: bool = False,
         gguf_variant: Optional[str] = None,
     ) -> Optional["ModelConfig"]:
-        """
-        Create ModelConfig from a clean model identifier.
-
-        For FastAPI routes where the frontend sends sanitized model paths.
-        No Gradio dropdown parsing; expects clean identifiers like:
-        - "unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit"
-        - "./outputs/my_lora_adapter"
-        - "/absolute/path/to/model"
+        """Create ModelConfig from a clean model identifier (HF repo or local
+        path), for FastAPI routes that send sanitized paths.
 
         Args:
             model_id: Clean model identifier (HF repo name or local path)
             hf_token: Optional HF token for vision detection on gated models
             is_lora: Whether this is a LoRA adapter
-            gguf_variant: Optional GGUF quant variant (e.g. "Q4_K_M"). For
-                remote GGUF repos, sets which quant to load via -hf. If None,
-                auto-selects via _pick_best_gguf().
+            gguf_variant: Optional GGUF quant variant (e.g. "Q4_K_M") to load
+                via -hf for remote repos; None auto-selects via _pick_best_gguf().
 
         Returns:
-            ModelConfig or None if configuration cannot be created
+            ModelConfig or None if it cannot be created.
         """
         if not model_id or not model_id.strip():
             return None
@@ -2253,9 +2156,8 @@ class ModelConfig:
             identifier = f"unsloth/{identifier}"
             path = identifier
 
-        # Preserve requested casing, but if a case-variant already exists in
-        # local HF cache, reuse that exact repo_id spelling to avoid one-time
-        # re-downloads after #2592.
+        # Reuse a cached case-variant's exact repo_id spelling to avoid
+        # one-time re-downloads after #2592.
         if not is_local:
             resolved_identifier = resolve_cached_repo_id_case(identifier)
             if resolved_identifier != identifier:
@@ -2295,12 +2197,9 @@ class ModelConfig:
                     except Exception as e:
                         logger.debug(f"Could not read export metadata: {e}")
 
-                # Find the mmproj file. The recursive variant scan in
-                # ``_find_local_gguf_by_variant`` may have returned a weight
-                # file inside a quant-named subdir (e.g. ``.../BF16/foo.gguf``)
-                # while ``mmproj-*.gguf`` lives at the snapshot root. Pass
-                # ``search_root=path`` so ``detect_mmproj_file`` walks up to
-                # the snapshot root instead of only the weight's parent.
+                # Pass search_root=path so detect_mmproj_file walks up to the
+                # snapshot root: the weight may sit in a quant subdir while
+                # mmproj-*.gguf lives at the root.
                 mmproj_file = detect_mmproj_file(gguf_file, search_root = path)
                 if mmproj_file:
                     gguf_is_vision = True
@@ -2324,8 +2223,7 @@ class ModelConfig:
             # Does the HF repo contain GGUF files?
             gguf_filename = detect_gguf_model_remote(identifier, hf_token = hf_token)
             if gguf_filename:
-                # Preflight: verify llama-server binary exists BEFORE the user
-                # waits for a multi-GB download llama-server handles natively
+                # Preflight: verify llama-server binary exists before a multi-GB download
                 from core.inference.llama_cpp import LlamaCppBackend
 
                 if not LlamaCppBackend._find_llama_server_binary():
@@ -2337,8 +2235,7 @@ class ModelConfig:
                 # list_gguf_variants() detects vision & resolves the variant
                 variants, has_vision = list_gguf_variants(identifier, hf_token = hf_token)
                 variant = gguf_variant
-                if not variant:
-                    # Auto-select best quantization
+                if not variant:  # auto-select best quant
                     variant_filenames = [v.filename for v in variants]
                     best = _pick_best_gguf(variant_filenames)
                     if best:
@@ -2454,10 +2351,7 @@ class ModelConfig:
         hf_token: Optional[str] = None,
         is_lora: bool = False,
     ) -> Optional["ModelConfig"]:
-        """
-        Create a ModelConfig from UI dropdown/search selections.
-        Handles base models and LoRA adapters.
-        """
+        """Create a ModelConfig from UI dropdown/search selections (base models and LoRAs)."""
         selected = None
         if search_value and search_value.strip():
             selected = search_value.strip()
diff --git a/studio/backend/utils/paths/__init__.py b/studio/backend/utils/paths/__init__.py
index 8805308829..1dcc9191fd 100644
--- a/studio/backend/utils/paths/__init__.py
+++ b/studio/backend/utils/paths/__init__.py
@@ -44,8 +44,8 @@ from .storage_roots import (
     resolve_dataset_path,
 )
 
-# Re-export shim: reference the project-path helpers by name so the
-# import-hoist safety net sees them used, not just named in __all__.
+# Re-export shim: mark project-path helpers as used so the import-hoist
+# safety net does not flag them as unused.
 _REEXPORTED = (documents_root, project_workspaces_root)
 
 __all__ = [
diff --git a/studio/backend/utils/paths/path_utils.py b/studio/backend/utils/paths/path_utils.py
index a065250154..e8dabc8954 100644
--- a/studio/backend/utils/paths/path_utils.py
+++ b/studio/backend/utils/paths/path_utils.py
@@ -44,19 +44,10 @@ _IS_WSL: bool = _is_wsl()
 
 
 def normalize_path(path: str) -> str:
-    """
-    Normalize filesystem paths for cross-platform use.
+    """Normalize filesystem paths for cross-platform use.
 
-    On WSL, converts Windows drive-letter paths to ``/mnt/<drive>/...``.
-    On native Windows, keeps the drive letter and normalizes separators.
-    On Linux/macOS (non-WSL), paths are returned with forward slashes.
-
-    Examples (WSL):
-        C:\\Users\\... -> /mnt/c/Users/...
-    Examples (native Windows):
-        C:\\Users\\... -> C:/Users/...
-    Examples (Linux/macOS):
-        /home/user/... -> /home/user/... (unchanged)
+    WSL maps drive-letter paths to ``/mnt/<drive>/...``; native Windows keeps
+    the drive and normalizes separators; elsewhere slashes are forward-only.
     """
     if not path:
         return path
@@ -162,8 +153,7 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
 
     expected_dir = f"models--{model_name.replace('/', '--')}"
 
-    # Check the exact-case path first so a newly-appeared exact match wins over
-    # any previously memoized variant.
+    # Exact-case path first so a new exact match beats a memoized variant.
     exact_path = cache_dir / expected_dir
     if exact_path.is_dir():
         if use_memo:
@@ -171,8 +161,7 @@ def resolve_cached_repo_id_case(model_name: str, use_memo: bool = True) -> str:
         _CACHE_CASE_RESOLUTION_STATS["exact_hits"] += 1
         return model_name
 
-    # Validate memoized entries still exist on disk before returning them,
-    # preventing stale results when cache dirs are deleted/recreated.
+    # Revalidate memoized entries on disk to avoid stale results.
     if use_memo:
         cached = _CACHE_CASE_RESOLUTION_MEMO.get(model_name)
         if cached is not None:
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index de88a0bf31..63d24afd0c 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -182,7 +182,7 @@ def lmstudio_model_dirs() -> list[Path]:
             seen.add(resolved)
             dirs.append(p)
 
-    # 1. LM Studio settings.json custom downloads folder
+    # LM Studio settings.json custom downloads folder
     settings_path = Path.home() / ".lmstudio" / "settings.json"
     if settings_path.is_file():
         try:
@@ -194,10 +194,10 @@ def lmstudio_model_dirs() -> list[Path]:
         except Exception:
             pass
 
-    # 2. LM Studio current default models directory (all platforms)
+    # LM Studio default models directory (all platforms)
     _add(Path.home() / ".lmstudio" / "models")
 
-    # 3. Legacy LM Studio cache location
+    # Legacy LM Studio cache location
     _add(Path.home() / ".cache" / "lm-studio" / "models")
 
     return dirs
@@ -232,7 +232,7 @@ def well_known_model_dirs() -> list[Path]:
     for name in ("models", "Models"):
         candidates.append(Path.home() / name)
 
-    # Deduplicate while preserving order; keep only extant dirs
+    # Dedupe preserving order; keep only extant dirs
     out: list[Path] = []
     seen: set[str] = set()
     for p in candidates:
@@ -249,15 +249,11 @@ def well_known_model_dirs() -> list[Path]:
 
 
 def _setup_cache_env() -> None:
-    """Set cache environment variables for HuggingFace, uv, and vLLM.
+    """Set cache env vars for HuggingFace, uv, and vLLM.
 
-    Respects the standard HF cache resolution chain: explicit ``HF_HOME``
-    / ``HF_HUB_CACHE`` win, then ``XDG_CACHE_HOME``, then the platform
-    default (``~/.cache/huggingface``). The legacy Unsloth cache is still
-    *scanned* for models but never set as the active download target.
-
-    Only sets variables not already set by the user, so explicit overrides
-    (e.g. HF_HOME=/data/hf) are respected. Works on Linux, macOS, Windows.
+    Respects the standard HF cache chain (explicit HF_HOME / HF_HUB_CACHE,
+    then XDG_CACHE_HOME, then ~/.cache/huggingface) and only sets vars the
+    user hasn't, so explicit overrides are honored.
     """
     root = cache_root()
     xdg_cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")).expanduser()
diff --git a/studio/backend/utils/subprocess_compat.py b/studio/backend/utils/subprocess_compat.py
index b7fe906e91..f2fa6eadc7 100644
--- a/studio/backend/utils/subprocess_compat.py
+++ b/studio/backend/utils/subprocess_compat.py
@@ -8,10 +8,9 @@ import sys
 
 
 def windows_hidden_subprocess_kwargs() -> dict[str, object]:
-    """Return Windows-only subprocess kwargs that suppress console windows.
+    """Windows-only subprocess kwargs that suppress console windows.
 
-    Returns an empty dict off Windows so callers can always unpack it into
-    ``subprocess.run`` / ``subprocess.Popen`` via
+    Empty dict off Windows, so callers can always unpack via
     ``**windows_hidden_subprocess_kwargs()``.
     """
     if sys.platform != "win32":
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index 7c1bc361b6..bf8d14b7cb 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -1,27 +1,14 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Automatic transformers version switching.
+"""Automatic transformers version switching.
 
-Some newer architectures (Ministral-3, GLM-4.7-Flash, Qwen3-30B-A3B MoE,
-tiny_qwen3_moe) need transformers>=5.3.0; Gemma 4 needs >=5.5.0. Everything
-else uses the default 4.57.x that ships with Unsloth.
+Some newer architectures need transformers>=5.3.0 (.venv_t5_530/); Gemma 4
+needs >=5.5.0 (.venv_t5_550/). Everything else uses the default 4.57.x. A
+custom-named LoRA adapter's base model is resolved from adapter_config.json.
 
-Two target directories:
-  - .venv_t5_530/  — transformers 5.3.0 (Ministral-3, GLM, Qwen3 MoE, etc.)
-  - .venv_t5_550/  — transformers 5.5.0 (Gemma 4)
-
-For a custom-named LoRA adapter, the base model is resolved from
-``adapter_config.json`` and checked against the model list.
-
-Strategy:
-  Training and inference run in subprocesses that activate the right version
-  via sys.path (prepending the appropriate .venv_t5_*/ dir). See
-  core/training/worker.py and core/inference/worker.py.
-
-  For export (in-process), ensure_transformers_version() does a lightweight
-  sys.path swap using the same setup.sh-installed directories.
+Training/inference run in subprocesses that activate the right version via
+sys.path; export (in-process) uses ensure_transformers_version() for the swap.
 """
 
 import importlib
@@ -397,12 +384,11 @@ _PURGE_PREFIXES = (
     "trl",
     "accelerate",
     "auto_gptq",
-    # NOTE: bitsandbytes is intentionally EXCLUDED — it registers torch custom
-    # operators at import via torch.library.define() into torch's global
-    # registry, which survives module purge. Re-importing it after purge →
-    # duplicate registration → crash.
-    # Our own modules that import from transformers at module level
-    # (e.g. model_config.py: `from transformers import AutoConfig`)
+    # NOTE: bitsandbytes is intentionally EXCLUDED -- it registers torch custom
+    # operators via torch.library.define() into torch's global registry, which
+    # survives module purge; re-importing after purge -> duplicate registration
+    # -> crash.
+    # Our own modules that import from transformers at module level.
     "utils.models",
     "core.training",
     "core.inference",
diff --git a/studio/backend/utils/utils.py b/studio/backend/utils/utils.py
index c51fc267f2..3818253ac9 100644
--- a/studio/backend/utils/utils.py
+++ b/studio/backend/utils/utils.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Shared backend utilities
-"""
+"""Shared backend utilities."""
 
 import os
 import structlog
@@ -18,16 +16,12 @@ logger = get_logger(__name__)
 
 
 # ── Client-safe error helpers ───────────────────────────────────
-# Never return raw exception text to clients (it can leak paths/internals);
-# log the full exception server-side and return a generic message.
+# Never return raw exception text to clients; log server-side, return generic.
 
 
 def safe_error_detail(error: Exception, fallback: str = "An internal error occurred") -> str:
-    """Map a caught exception to a generic, client-safe message.
-
-    Never includes raw ``str(error)`` (which can leak internal paths or stack
-    detail); known transient conditions get a friendlier hint. Always log the
-    real exception server-side (e.g. via ``log_and_http_error``) for diagnosis.
+    """Map an exception to a generic, client-safe message (never raw
+    ``str(error)``, which can leak paths). Log the real exception server-side.
     """
     text = str(error).lower()
     if (
@@ -43,10 +37,10 @@ def safe_error_detail(error: Exception, fallback: str = "An internal error occur
 
 
 def safe_curated_detail(error: Exception, fallback: str = "An internal error occurred") -> str:
-    """Client-safe text for curated domain/validation exceptions meant for the user.
+    """Client-safe text for curated domain/validation exceptions.
 
-    Keeps the message (paths stripped) instead of a generic fallback; use for known
-    exception types, keep ``safe_error_detail`` for generic ``Exception``.
+    Keeps the message (paths stripped) instead of a generic fallback; for known
+    exception types only (use ``safe_error_detail`` for generic ``Exception``).
     """
     from utils.native_path_leases import redact_native_paths
 
@@ -69,7 +63,7 @@ def log_and_http_error(
     """
     from fastapi import HTTPException
 
-    # Works for both structlog and stdlib loggers; exc_info=error logs its traceback.
+    # exc_info=error works for both structlog and stdlib loggers.
     (log or logger).error(f"{event}: {error}", exc_info = error)
     return HTTPException(status_code = status_code, detail = public_message)
 
@@ -84,7 +78,6 @@ def without_hf_auth():
             # Code that should run without cached tokens
             model_info(model_name, token=None)
     """
-    # Save and clear env vars
     saved_env = {}
     env_vars = ["HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_HOME"]
     for var in env_vars:
diff --git a/studio/backend/utils/wheel_utils.py b/studio/backend/utils/wheel_utils.py
index 59632963b7..98697df83c 100644
--- a/studio/backend/utils/wheel_utils.py
+++ b/studio/backend/utils/wheel_utils.py
@@ -24,16 +24,12 @@ FLASH_ATTN_RELEASE_BASE_URL = "https://github.com/Dao-AILab/flash-attention/rele
 
 @functools.lru_cache(maxsize = 1)
 def has_blackwell_gpu() -> bool:
-    """Return True if any visible NVIDIA GPU has compute capability >= 10.0
-    (Blackwell: sm_100, sm_120, sm_121, ...).
+    """Return True if any visible NVIDIA GPU has compute capability >= 10.0 (Blackwell).
 
-    Dao-AILab publishes no prebuilt flash-attention wheels for these archs,
-    and older-arch wheels fail to load on Blackwell, so callers use this gate
-    to skip the flash-attn install/upgrade path.
-
-    Cached for the process lifetime since GPU hardware doesn't change. Tests
-    that mock subprocess/nvidia-smi must call
-    ``has_blackwell_gpu.cache_clear()`` before each invocation.
+    Dao-AILab ships no flash-attention wheels for these archs and older-arch wheels
+    fail to load, so callers use this to skip the flash-attn install path. Cached
+    for the process lifetime; tests mocking nvidia-smi must call
+    ``has_blackwell_gpu.cache_clear()`` first.
     """
     exe = shutil.which("nvidia-smi")
     if not exe:
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 80e5257c8d..5d3f0ed339 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -113,19 +113,13 @@ LEMONADE_ROCM_RELEASES_API = f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}
 
 
 def _lemonade_release_api_for(llama_tag: str) -> str:
-    """Return the GitHub API URL for the lemonade release matching a llama.cpp tag.
+    """GitHub API URL for the lemonade release matching a llama.cpp tag.
 
-    When llama_tag is unset or "latest", point at /releases/latest. When
-    pinned (e.g. "b1260"), point at the same tag in lemonade. Lemonade
-    tracks `ggml-org/llama.cpp` build tags but is NOT guaranteed to publish
-    every upstream build -- it may be several builds behind. Pinning a tag
-    lemonade skipped produces a 404 and the caller falls through to the
-    upstream tarball; intentional so pinned installs stay reproducible.
-    Do NOT pass a `unslothai/llama.cpp` fork tag -- the fork's namespace
-    always 404s against lemonade.
-
-    The tag is URL-encoded with `safe=""` so a stray slash / hash / query
-    char cannot reshape the URL.
+    "latest"/unset -> /releases/latest; a pinned tag -> the same lemonade tag.
+    Lemonade tracks ggml-org build tags but may lag, so a tag it skipped 404s
+    and the caller falls back to the upstream tarball (keeps pinned installs
+    reproducible). Do NOT pass a fork tag -- the fork namespace always 404s.
+    Tag is URL-encoded (safe="") to prevent URL injection.
     """
     normalized = (llama_tag or "").strip()
     if not normalized or normalized.lower() == "latest":
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 0cff45daef..2c8f6228d4 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -40,11 +40,9 @@ IS_MACOS = sys.platform == "darwin"
 IS_MAC_INTEL = IS_MACOS and platform.machine() == "x86_64"
 IS_MAC_ARM = IS_MACOS and platform.machine() == "arm64"
 IS_LINUX = sys.platform.startswith("linux")
-# torchcodec ships wheels only for manylinux_2_28_x86_64,
-# macosx_12_0_arm64, and win_amd64 (per the 0.10.0 PyPI page). Installing
-# on any other host fails the whole extras-no-deps step. `unsloth studio
-# update` has no --no-torch flag, so on these hosts the audio extras must
-# be filtered out regardless of the NO_TORCH env var.
+# torchcodec ships wheels only for manylinux_2_28_x86_64, macosx_12_0_arm64,
+# and win_amd64. On other hosts the audio extras must be filtered out (the
+# extras-no-deps step would otherwise fail), regardless of NO_TORCH.
 PLATFORM_LACKS_TORCHCODEC_WHEEL = (
     (IS_LINUX and platform.machine() in {"aarch64", "arm64"})
     or (IS_WINDOWS and platform.machine().lower() in {"arm64", "aarch64"})
@@ -83,8 +81,7 @@ _PYTORCH_WHL_BASE = (
     os.environ.get("UNSLOTH_PYTORCH_MIRROR") or "https://download.pytorch.org/whl"
 ).rstrip("/")
 
-# AMD Windows ROCm wheels — repo.amd.com (arch-specific pip index).
-# Format: https://repo.amd.com/rocm/whl/{arch_family}/
+# AMD Windows ROCm wheels (repo.amd.com/rocm/whl/{arch_family}/).
 # Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped/mirror installs.
 _ROCM_WINDOWS_INDEX_BASE = (
     os.environ.get("UNSLOTH_ROCM_WINDOWS_MIRROR") or "https://repo.amd.com/rocm/whl"
@@ -119,11 +116,9 @@ _BNB_ROCM_PRERELEASE_URLS: dict[str, str] = {
         "download/continuous-release_main/"
         "bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_aarch64.whl"
     ),
-    # Windows ROCm wheel — ships libbitsandbytes_rocm{VER}.dll.
-    # BNB auto-detects HIP version from torch.version.hip, which may not match
-    # the DLL suffix in this prerelease wheel (e.g. torch 7.13 with a rocm72
-    # DLL). We scan the installed wheel for the real DLL name and set
-    # BNB_ROCM_VERSION accordingly in _install_bnb_windows_rocm() and worker.py.
+    # Windows ROCm wheel ships libbitsandbytes_rocm{VER}.dll. BNB's HIP
+    # auto-detect may mismatch the DLL suffix, so we scan the wheel and set
+    # BNB_ROCM_VERSION in _install_bnb_windows_rocm() and worker.py.
     "win_amd64": (
         "https://github.com/bitsandbytes-foundation/bitsandbytes/releases/"
         "download/continuous-release_main/"
@@ -144,7 +139,6 @@ def _bnb_rocm_prerelease_url() -> str | None:
 
 def _detect_rocm_version() -> tuple[int, int] | None:
     """Return (major, minor) of the installed ROCm stack, or None."""
-    # Check /opt/rocm/.info/version or ROCM_PATH equivalent
     rocm_root = os.environ.get("ROCM_PATH") or "/opt/rocm"
     for path in (
         os.path.join(rocm_root, ".info", "version"),
diff --git a/tests/_zoo_aggressive_cuda_spoof.py b/tests/_zoo_aggressive_cuda_spoof.py
index 9111aa9519..dafe81c829 100644
--- a/tests/_zoo_aggressive_cuda_spoof.py
+++ b/tests/_zoo_aggressive_cuda_spoof.py
@@ -1,15 +1,12 @@
 # Auto-generated by .github/workflows/consolidated-tests-ci.yml.
 # Aggressive CUDA spoof for the consolidated CPU-only CI job. Extends
-# tests/conftest.py:84-141's import-time harness with deeper patches that
-# unblock more patch_* functions and unsloth_zoo init paths on a GPU-less
-# runner. Imported by every shim test file in this workflow before any
-# unsloth / unsloth_zoo / transformers import.
+# tests/conftest.py's import-time harness with deeper patches that unblock
+# more patch_* and unsloth_zoo init paths on a GPU-less runner. Imported by
+# every shim test file before any unsloth / unsloth_zoo / transformers import.
 #
-# Design: only no-op or value-returning patches. We do NOT replace tensor
-# allocators. The single exception is `pin_memory=True` kwarg dropping,
-# which converts a hard CUDA-required call into a CPU-OK call -- the
-# intent of pin_memory is a CUDA-host fast-copy, which simply has no
-# meaning on this runner; downgrading silently is the right behavior here.
+# Only no-op or value-returning patches; tensor allocators are NOT replaced.
+# The one exception is dropping `pin_memory=True` (a CUDA-host fast-copy hint
+# that is meaningless here), which downgrades a CUDA-required call to CPU-OK.
 
 from __future__ import annotations
 
@@ -25,7 +22,7 @@ def apply() -> None:
     if getattr(torch.cuda, "_unsloth_consolidated_spoof", False):
         return
 
-    # ----- device probes (cheap, value-returning) -------------------------
+    # Device probes (cheap, value-returning)
     torch.cuda.is_available = lambda: True
     torch.cuda.device_count = lambda: 1
     torch.cuda.current_device = lambda: 0
@@ -49,7 +46,7 @@ def apply() -> None:
 
     torch.cuda.get_device_properties = lambda *a, **k: _Props()  # type: ignore[assignment]
 
-    # ----- cudart() wrapper -----------------------------------------------
+    # cudart() wrapper
     class _CudaRt:
         @staticmethod
         def cudaMemGetInfo(device: int = 0):
@@ -57,7 +54,7 @@ def apply() -> None:
 
         @staticmethod
         def cudaGetDeviceCount(*_a, **_k):
-            return 0  # Not used on the spoof path
+            return 0  # unused on the spoof path
 
         @staticmethod
         def cudaSetDevice(*_a, **_k):
@@ -65,7 +62,7 @@ def apply() -> None:
 
     torch.cuda.cudart = lambda: _CudaRt()  # type: ignore[assignment]
 
-    # ----- memory module --------------------------------------------------
+    # memory module
     try:
         import torch.cuda.memory as _cuda_memory  # type: ignore
 
@@ -79,7 +76,7 @@ def apply() -> None:
     except Exception:
         pass
 
-    # ----- nvtx no-op stub ------------------------------------------------
+    # nvtx no-op stub
     nvtx_stub = types.ModuleType("torch.cuda.nvtx")
     nvtx_stub.range_push = lambda *a, **k: None  # type: ignore[attr-defined]
     nvtx_stub.range_pop = lambda *a, **k: None  # type: ignore[attr-defined]
@@ -87,18 +84,15 @@ def apply() -> None:
     sys.modules.setdefault("torch.cuda.nvtx", nvtx_stub)
     torch.cuda.nvtx = nvtx_stub  # type: ignore[attr-defined]
 
-    # ----- random API ----------------------------------------------------
-    # CRITICAL: torch.manual_seed() internally calls torch.cuda.manual_seed_all(),
-    # so routing the cuda seed APIs back through torch.manual_seed would
-    # infinite-recurse (observed as RecursionError in run #8 cells 2/3 of the
-    # consolidated CI matrix). No-op them: callers that explicitly seed CUDA
-    # have already paid the cost of seeding CPU via torch.manual_seed; the
-    # CUDA-side seeding has no meaning on a GPU-less runner.
+    # random API
+    # CRITICAL: torch.manual_seed() calls torch.cuda.manual_seed_all(), so
+    # routing the cuda seed APIs back through torch.manual_seed would
+    # infinite-recurse (RecursionError in CI). No-op them; CUDA-side seeding
+    # is meaningless on a GPU-less runner.
     torch.cuda.manual_seed = lambda *a, **k: None  # type: ignore[assignment]
     torch.cuda.manual_seed_all = lambda *a, **k: None  # type: ignore[assignment]
-    # rng_state APIs: return a CPU-shaped placeholder and accept anything for
-    # set; do NOT route through torch.set_rng_state / get_rng_state -- those
-    # operate on the CPU RNG directly and are independent of the cuda surface.
+    # rng_state APIs: return a CPU-shaped placeholder, accept anything for set;
+    # do NOT route through torch.{get,set}_rng_state (those touch the CPU RNG).
     import torch as _t
 
     _empty_rng_state = _t.empty(0, dtype = _t.uint8)
@@ -110,7 +104,7 @@ def apply() -> None:
     torch.cuda.seed = lambda *a, **k: None  # type: ignore[assignment]
     torch.cuda.seed_all = lambda *a, **k: None  # type: ignore[assignment]
 
-    # ----- Stream / Event no-op classes -----------------------------------
+    # Stream / Event no-op classes
     class _NoopStream:
         def __init__(self, *a, **k): ...
         def __enter__(self):
@@ -141,9 +135,8 @@ def apply() -> None:
     torch.cuda.current_stream = lambda *a, **k: _NoopStream()  # type: ignore[assignment]
     torch.cuda.default_stream = lambda *a, **k: _NoopStream()  # type: ignore[assignment]
 
-    # ----- pin_memory drop -------------------------------------------------
-    # `torch.empty(..., pin_memory=True)` and friends raise on a CPU-only
-    # build. Strip the kwarg — pin_memory has no meaning here.
+    # pin_memory drop: torch.empty(..., pin_memory=True) and friends raise on
+    # a CPU-only build; strip the kwarg since pin_memory has no meaning here.
     for _name in (
         "empty",
         "zeros",
@@ -175,10 +168,8 @@ def apply() -> None:
     if hasattr(torch.Tensor, "is_pinned"):
         torch.Tensor.is_pinned = lambda self, *a, **k: False  # type: ignore[assignment]
 
-    # ----- amp.GradScaler: use the real one if torch ships a CPU-friendly
-    # path, else stub. Newer torch ships torch.amp.GradScaler that handles
-    # CPU; torch.cuda.amp.GradScaler is a wrapper. Both should work; just
-    # guard against import error.
+    # amp.GradScaler: use the real one if importable (newer torch handles CPU),
+    # else stub.
     try:
         import torch.cuda.amp  # type: ignore
     except Exception:
@@ -209,7 +200,7 @@ def apply() -> None:
         sys.modules.setdefault("torch.cuda.amp", cuda_amp)
         torch.cuda.amp = cuda_amp  # type: ignore[attr-defined]
 
-    # ----- Sentinel ------------------------------------------------------
+    # Sentinel
     torch.cuda._unsloth_consolidated_spoof = True  # type: ignore[attr-defined]
 
 
diff --git a/tests/conftest.py b/tests/conftest.py
index ad58cb9706..4b7081b30b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -140,14 +140,11 @@ if not _has_real_accelerator():
 
 
 # ---------------------------------------------------------------------------
-# Apply ALL upstream-drift fixes (vllm GuidedDecodingParams alias, triton
-# CompiledKernel attr wrap, peft transformers_weight_conversion stub, etc.)
-# by triggering ``import unsloth``. Fixes live on ``unsloth/import_fixes.py``
-# and apply at unsloth import time. The GPU-free harness above pre-spoofs
-# the device-type chain so ``import unsloth`` survives on a CPU-only runner.
-# Suites without unsloth installed (e.g. security-only) keep passing --
-# the ImportError is swallowed and the drift detectors will surface any
-# pathology the missing patches would have hidden.
+# Apply upstream-drift fixes (vllm/triton/peft) by triggering ``import
+# unsloth``; they live in ``unsloth/import_fixes.py`` and run at import time.
+# The GPU-free harness above lets ``import unsloth`` survive CPU-only runners.
+# Suites without unsloth keep passing -- the ImportError is swallowed and the
+# drift detectors surface anything the missing patches would have hidden.
 # ---------------------------------------------------------------------------
 
 
diff --git a/tests/python/test_cross_platform_parity.py b/tests/python/test_cross_platform_parity.py
index 6c504579ce..0f2e73257a 100644
--- a/tests/python/test_cross_platform_parity.py
+++ b/tests/python/test_cross_platform_parity.py
@@ -21,8 +21,7 @@ class TestNoTorchBackendAutoInInstallSh:
 
     def test_no_torch_backend_auto_outside_fallback(self):
         lines = INSTALL_SH.read_text().splitlines()
-        # Find the fallback block: starts with the "else" after the
-        # TORCH_INDEX_URL check and ends at the next "fi".
+        # Fallback block: from "GPU detection failed" to the next "fi".
         fallback_start = None
         fallback_end = None
         for i, line in enumerate(lines):
diff --git a/tests/python/test_e2e_no_torch_sandbox.py b/tests/python/test_e2e_no_torch_sandbox.py
index 382d0afe4e..9b3bda133f 100644
--- a/tests/python/test_e2e_no_torch_sandbox.py
+++ b/tests/python/test_e2e_no_torch_sandbox.py
@@ -1,19 +1,11 @@
-"""Comprehensive E2E sandbox tests for PR #4624 (fix/install-mac-intel-no-torch).
-
-Proves that:
-- The BEFORE state (top-level torch imports) crashes without torch
-- The AFTER state (lazy/removed imports) works without torch
-- Edge cases (broken torch, partial torch) are handled gracefully
-- Hardware detection falls back to CPU without torch
-- install.sh flag parsing and platform detection work correctly
-- install_python_stack.py NO_TORCH filtering is correct
-- Live server starts and responds without torch (optional, requires studio venv)
+"""E2E sandbox tests for PR #4624 (fix/install-mac-intel-no-torch): BEFORE
+(top-level torch) crashes, AFTER (lazy imports) works, broken/partial torch,
+CPU hardware fallback, install.sh parsing, NO_TORCH filtering, and live server.
 
 Run:
-    # Lightweight tests (Groups 1-6, ~26 tests):
+    # Lightweight (Groups 1-6):
     python -m pytest tests/python/test_e2e_no_torch_sandbox.py -v -k "not server"
-
-    # Server tests (Group 7, 4 tests, requires studio venv):
+    # Server (Group 7, requires studio venv):
     python -m pytest tests/python/test_e2e_no_torch_sandbox.py -v -m server
 """
 
@@ -212,12 +204,8 @@ def no_torch_venv(request, tmp_path_factory):
 
 
 class TestBeforeAfterImportChain:
-    """Prove the bug exists in BEFORE state and is fixed in AFTER state.
-
-    BEFORE = PR branch files with top-level torch import synthetically prepended
-             (simulates the main branch).
-    AFTER  = PR branch files as-is (lazy imports / torch import removed).
-    """
+    """BEFORE (PR files with a synthetic top-level torch import, simulating
+    main) crashes; AFTER (PR files as-is, lazy imports) works."""
 
     # -- BEFORE: crashes --
 
diff --git a/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py b/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
index 3f5f235aae..6fa7d06ec3 100644
--- a/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
+++ b/tests/python/test_fast_sentence_transformer_redirect_lifecycle.py
@@ -18,8 +18,8 @@ import pytest
 
 
 def _stub_module(name: str) -> types.ModuleType:
-    # __spec__ must be set so importlib.util.find_spec(name) does not raise
-    # ValueError if a downstream test imports the real package.
+    # __spec__ set so find_spec(name) doesn't raise if a later test imports
+    # the real package.
     mod = types.ModuleType(name)
     mod.__spec__ = importlib.util.spec_from_loader(name, loader = None)
     return mod
diff --git a/tests/python/test_install_python_stack.py b/tests/python/test_install_python_stack.py
index 16538ae42b..64373cb4b8 100644
--- a/tests/python/test_install_python_stack.py
+++ b/tests/python/test_install_python_stack.py
@@ -10,12 +10,11 @@ from unittest import mock
 
 import pytest
 
-# Add the studio directory so we can import install_python_stack
+# Add the studio directory so we can import install_python_stack.
 STUDIO_DIR = Path(__file__).resolve().parents[2] / "studio"
 sys.path.insert(0, str(STUDIO_DIR))
 
-# _build_uv_cmd lives at module level; import after path setup.
-# We need to mock parts of the module that do work at import time.
+# Import after path setup.
 import install_python_stack as ips
 
 
diff --git a/tests/python/test_studio_import_no_torch.py b/tests/python/test_studio_import_no_torch.py
index c8b67023f5..7b7a7103d2 100644
--- a/tests/python/test_studio_import_no_torch.py
+++ b/tests/python/test_studio_import_no_torch.py
@@ -61,7 +61,6 @@ def no_torch_venv(request, tmp_path_factory):
     if venv_python is None:
         pytest.skip(f"Could not create Python {py_version} venv")
 
-    # Verify torch is NOT importable
     check = subprocess.run(
         [str(venv_python), "-c", "import torch"],
         capture_output = True,
diff --git a/tests/python/test_tokenizers_and_torch_constraint.py b/tests/python/test_tokenizers_and_torch_constraint.py
index 17f2d17f94..40924efca2 100644
--- a/tests/python/test_tokenizers_and_torch_constraint.py
+++ b/tests/python/test_tokenizers_and_torch_constraint.py
@@ -1,7 +1,6 @@
-"""
-Tests for two install fixes:
-  1. tokenizers added to no-torch-runtime.txt  (prevents AutoConfig crash)
-  2. TORCH_CONSTRAINT variable in install.sh    (arm64 macOS + py313+ -> torch>=2.6)
+"""Tests for two install fixes:
+1. tokenizers in no-torch-runtime.txt (prevents AutoConfig crash)
+2. TORCH_CONSTRAINT in install.sh (arm64 macOS + py313+ -> torch>=2.6)
 """
 
 from __future__ import annotations
diff --git a/tests/saving/gpt-oss-merge/test_merged_model.py b/tests/saving/gpt-oss-merge/test_merged_model.py
index 497c74debf..024d48f276 100644
--- a/tests/saving/gpt-oss-merge/test_merged_model.py
+++ b/tests/saving/gpt-oss-merge/test_merged_model.py
@@ -39,7 +39,7 @@ inputs = merged_tokenizer.apply_chat_template(
     add_generation_prompt = True,
     return_tensors = "pt",
     return_dict = True,
-    reasoning_effort = "low",  # **NEW!** Set reasoning effort to low, medium or high
+    reasoning_effort = "low",  # low, medium or high
 ).to(merged_model.device)
 
 _ = merged_model.generate(**inputs, max_new_tokens = 512, streamer = TextStreamer(merged_tokenizer))
diff --git a/tests/saving/gpt-oss-merge/train_and_merge.py b/tests/saving/gpt-oss-merge/train_and_merge.py
index 8c76ff9662..1d35c6759d 100644
--- a/tests/saving/gpt-oss-merge/train_and_merge.py
+++ b/tests/saving/gpt-oss-merge/train_and_merge.py
@@ -1,4 +1,3 @@
-# train_and_merge.py
 from unsloth import FastLanguageModel
 from trl import SFTTrainer, SFTConfig
 from datasets import load_dataset
@@ -21,7 +20,7 @@ def safe_remove_directory(path):
         return False
 
 
-# This tokenizer will be used by the mapping function
+# Used by the mapping function below.
 tokenizer = None
 
 
diff --git a/tests/saving/language_models/test_merge_4bit_validation.py b/tests/saving/language_models/test_merge_4bit_validation.py
index c889001706..2e2e823bd3 100644
--- a/tests/saving/language_models/test_merge_4bit_validation.py
+++ b/tests/saving/language_models/test_merge_4bit_validation.py
@@ -48,7 +48,6 @@ tokenizer = get_chat_template(
     chat_template = "llama-3.1",
 )
 
-# Load small dataset for quick training
 dataset_train = load_dataset("allenai/openassistant-guanaco-reformatted", split = "train[:100]")
 dataset_train = dataset_train.map(formatting_prompts_func, batched = True)
 
@@ -126,7 +125,6 @@ print(f"\n{'='*80}")
 print("🔍 PHASE 4: Loading 4bit Model and Second Fine-tuning")
 print(f"{'='*80}")
 
-# Clean up first model
 del model
 del tokenizer
 torch.cuda.empty_cache()
@@ -146,7 +144,7 @@ tokenizer_4bit = get_chat_template(
 
 print("✅ 4bit model loaded successfully!")
 
-# Add LoRA adapters to the 4bit model
+# Add LoRA adapters
 model_4bit = FastLanguageModel.get_peft_model(
     model_4bit,
     r = 16,
@@ -233,7 +231,6 @@ print(f"\n{'='*80}")
 print("🔍 CLEANUP")
 print(f"{'='*80}")
 
-# Cleanup
 safe_remove_directory("./outputs")
 safe_remove_directory("./outputs_4bit")
 safe_remove_directory("./unsloth_compiled_cache")
diff --git a/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py b/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
index 3f2b811b07..f8f81c550e 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_llama-3.2.py
@@ -31,7 +31,6 @@ from tests.utils.perplexity_eval import (
 )
 
 
-# Define helper functions outside of main
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
@@ -51,14 +50,12 @@ def load_and_compute_8bit_ppl(
     from unsloth.chat_templates import get_chat_template
     from tests.utils.perplexity_eval import ppl_model
 
-    # Load model
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_llama_text_model",
         max_seq_length = 2048,
         load_in_4bit = load_in_4bit,
         load_in_8bit = load_in_8bit,
     )
-    # Set up tokenizer
     merged_tokenizer = get_chat_template(
         merged_tokenizer,
         chat_template = "llama-3.1",
@@ -67,7 +64,6 @@ def load_and_compute_8bit_ppl(
     # Load dataset fresh in subprocess
     dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
-    # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
@@ -78,21 +74,18 @@ def load_and_compute_8bit_ppl(
 
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
 
-    # Compute perplexity using the passed dataset
     ppl_value = ppl_model(merged_model, merged_tokenizer, dataset_ppl)
 
-    # IMPORTANT: Convert to Python float if it's a tensor
+    # Coerce to a plain Python float for cross-process transfer
     if torch.is_tensor(ppl_value):
-        ppl_value = ppl_value.cpu().item()  # Move to CPU and convert to Python scalar
+        ppl_value = ppl_value.cpu().item()
     elif hasattr(ppl_value, "item"):
-        ppl_value = ppl_value.item()  # Convert numpy or other array types
+        ppl_value = ppl_value.item()
     else:
-        ppl_value = float(ppl_value)  # Ensure it's a float
+        ppl_value = float(ppl_value)
 
-    # Return only the perplexity value
     result_queue.put(ppl_value)
 
-    # Clean up
     del merged_model
     del merged_tokenizer
     del dataset_ppl
@@ -100,7 +93,6 @@ def load_and_compute_8bit_ppl(
     gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 if __name__ == "__main__":
     mp.set_start_method("spawn", force = True)
 
@@ -193,12 +185,10 @@ if __name__ == "__main__":
         response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
     )
 
-    # run training
     trainer_stats = trainer.train()
 
     add_to_comparison("Qlora model", ppl_model(model, tokenizer, dataset_ppl))
 
-    # saving and merging the model to local disk
     print("merge and save to local disk")
     model.save_pretrained_merged(
         save_directory = "./unsloth_out/merged_llama_text_model", tokenizer = tokenizer
@@ -210,7 +200,6 @@ if __name__ == "__main__":
     # torch.cuda.empty_cache()
     # gc.collect()
 
-    # load model from local disk and test
     print("Loading merged model in 4 bit for perplexity test")
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_llama_text_model",
@@ -247,7 +236,6 @@ if __name__ == "__main__":
 
     print_model_comparison()
 
-    # final cleanup
     safe_remove_directory("./outputs")
     safe_remove_directory("./unsloth_compiled_cache")
     safe_remove_directory("./unsloth_out")
diff --git a/tests/saving/language_models/test_merge_model_perplexity_mistral.py b/tests/saving/language_models/test_merge_model_perplexity_mistral.py
index d17a20d755..d467089a47 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_mistral.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_mistral.py
@@ -39,20 +39,18 @@ def load_and_compute_8bit_ppl(
     from unsloth import FastLanguageModel
     from tests.utils.perplexity_eval import ppl_model
 
-    # Load model
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_mistral_text_model",
         max_seq_length = 2048,
         load_in_4bit = load_in_4bit,
         load_in_8bit = load_in_8bit,
     )
-    # Set up tokenizer
     # merged_tokenizer = get_chat_template(
     #     merged_tokenizer,
     #     chat_template="llama-3.1",
     # )
 
-    # Load dataset fresh in subprocess
+    # Load dataset fresh in subprocess.
     dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
     alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.
@@ -75,7 +73,6 @@ def load_and_compute_8bit_ppl(
         texts = []
 
         for conversation in examples["messages"]:
-            # Extract user message and assistant response
             user_message = ""
             assistant_message = ""
 
@@ -85,13 +82,11 @@ def load_and_compute_8bit_ppl(
                 elif turn["role"] == "assistant":
                     assistant_message = turn["content"]
 
-            # Store intermediate format
             instruction = "Complete the statement"
             instructions.append(instruction)
             inputs.append(user_message)
             outputs.append(assistant_message)
 
-            # Create formatted text
             text = alpaca_prompt.format(instruction, user_message, assistant_message) + EOS_TOKEN
             texts.append(text)
 
@@ -104,21 +99,18 @@ def load_and_compute_8bit_ppl(
 
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
 
-    # Compute perplexity using the passed dataset
     ppl_value = ppl_model(merged_model, merged_tokenizer, dataset_ppl)
 
-    # IMPORTANT: Convert to Python float if it's a tensor
+    # Convert to Python float if it's a tensor.
     if torch.is_tensor(ppl_value):
-        ppl_value = ppl_value.cpu().item()  # Move to CPU and convert to Python scalar
+        ppl_value = ppl_value.cpu().item()
     elif hasattr(ppl_value, "item"):
-        ppl_value = ppl_value.item()  # Convert numpy or other array types
+        ppl_value = ppl_value.item()
     else:
-        ppl_value = float(ppl_value)  # Ensure it's a float
+        ppl_value = float(ppl_value)
 
-    # Return only the perplexity value
     result_queue.put(ppl_value)
 
-    # Clean up
     del merged_model
     del merged_tokenizer
     del dataset_ppl
@@ -126,7 +118,6 @@ def load_and_compute_8bit_ppl(
     gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 if __name__ == "__main__":
     mp.set_start_method("spawn", force = True)
 
@@ -160,7 +151,6 @@ if __name__ == "__main__":
     ### Response:
     {}"""
 
-    # Define helper functions outside of main
     def formatting_prompts_func(examples):
         instructions = []
         inputs = []
@@ -168,7 +158,6 @@ if __name__ == "__main__":
         texts = []
 
         for conversation in examples["messages"]:
-            # Extract user message and assistant response
             user_message = ""
             assistant_message = ""
 
@@ -178,13 +167,11 @@ if __name__ == "__main__":
                 elif turn["role"] == "assistant":
                     assistant_message = turn["content"]
 
-            # Store intermediate format
             instruction = "Complete the statement"
             instructions.append(instruction)
             inputs.append(user_message)
             outputs.append(assistant_message)
 
-            # Create formatted text
             text = alpaca_prompt.format(instruction, user_message, assistant_message) + EOS_TOKEN
             texts.append(text)
 
@@ -251,12 +238,11 @@ if __name__ == "__main__":
         ),
     )
 
-    # run training
     trainer_stats = trainer.train()
 
     add_to_comparison("Qlora model", ppl_model(model, tokenizer, dataset_ppl))
 
-    # saving and merging the model to local disk
+    # Merge and save to local disk.
     print("merge and save to local disk")
     model.save_pretrained_merged(
         save_directory = "./unsloth_out/merged_mistral_text_model", tokenizer = tokenizer
@@ -268,7 +254,7 @@ if __name__ == "__main__":
     # torch.cuda.empty_cache()
     # gc.collect()
 
-    # load model from local disk and test
+    # Load merged model from disk and test.
     print("Loading merged model in 4 bit for perplexity test")
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_mistral_text_model",
diff --git a/tests/saving/language_models/test_merge_model_perplexity_phi_4.py b/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
index 6dbdf36032..391d1b90db 100644
--- a/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
+++ b/tests/saving/language_models/test_merge_model_perplexity_phi_4.py
@@ -31,7 +31,6 @@ from tests.utils.perplexity_eval import (
 )
 
 
-# Define helper functions outside of main
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
@@ -48,19 +47,17 @@ def load_and_compute_8bit_ppl(
     load_in_4bit = False,
     load_in_8bit = False,
 ):
-    """Load model and compute perplexity in subprocess"""
+    """Load model and compute perplexity in subprocess."""
     from unsloth import FastLanguageModel
     from unsloth.chat_templates import get_chat_template
     from tests.utils.perplexity_eval import ppl_model
 
-    # Load model
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_phi4_text_model",
         max_seq_length = 2048,
         load_in_4bit = load_in_4bit,
         load_in_8bit = load_in_8bit,
     )
-    # Set up tokenizer
     merged_tokenizer = get_chat_template(
         merged_tokenizer,
         chat_template = "phi-4",
@@ -69,7 +66,6 @@ def load_and_compute_8bit_ppl(
     # Load dataset fresh in subprocess
     dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
-    # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
@@ -80,21 +76,18 @@ def load_and_compute_8bit_ppl(
 
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
 
-    # Compute perplexity using the passed dataset
     ppl_value = ppl_model(merged_model, merged_tokenizer, dataset_ppl)
 
-    # IMPORTANT: Convert to Python float if it's a tensor
+    # Coerce to a Python float regardless of source type.
     if torch.is_tensor(ppl_value):
-        ppl_value = ppl_value.cpu().item()  # Move to CPU and convert to Python scalar
+        ppl_value = ppl_value.cpu().item()
     elif hasattr(ppl_value, "item"):
-        ppl_value = ppl_value.item()  # Convert numpy or other array types
+        ppl_value = ppl_value.item()
     else:
-        ppl_value = float(ppl_value)  # Ensure it's a float
+        ppl_value = float(ppl_value)
 
-    # Return only the perplexity value
     result_queue.put(ppl_value)
 
-    # Clean up
     del merged_model
     del merged_tokenizer
     del dataset_ppl
@@ -102,7 +95,6 @@ def load_and_compute_8bit_ppl(
     gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 if __name__ == "__main__":
     mp.set_start_method("spawn", force = True)
 
@@ -193,12 +185,11 @@ if __name__ == "__main__":
         response_part = "<|im_start|>assistant<|im_sep|>\n\n",
     )
 
-    # run training
     trainer_stats = trainer.train()
 
     add_to_comparison("Qlora model", ppl_model(model, tokenizer, dataset_ppl))
 
-    # saving and merging the model to local disk
+    # Merge and save to local disk.
     print("merge and save to local disk")
     model.save_pretrained_merged(
         save_directory = "./unsloth_out/merged_phi4_text_model", tokenizer = tokenizer
@@ -210,7 +201,6 @@ if __name__ == "__main__":
     # torch.cuda.empty_cache()
     # gc.collect()
 
-    # load model from local disk and test
     print("Loading merged model in 4 bit for perplexity test")
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_phi4_text_model",
@@ -247,7 +237,6 @@ if __name__ == "__main__":
 
     print_model_comparison()
 
-    # final cleanup
     safe_remove_directory("./outputs")
     safe_remove_directory("./unsloth_compiled_cache")
     safe_remove_directory("./unsloth_out")
diff --git a/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py b/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
index a0624f0c2c..9c2c1acb41 100644
--- a/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
+++ b/tests/saving/language_models/test_merged_model_perplexity_llama-3.1-8b.py
@@ -50,14 +50,12 @@ def load_and_compute_8bit_ppl(
     from unsloth.chat_templates import get_chat_template
     from tests.utils.perplexity_eval import ppl_model
 
-    # Load model
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_llama_text_model",
         max_seq_length = 2048,
         load_in_4bit = load_in_4bit,
         load_in_8bit = load_in_8bit,
     )
-    # Set up tokenizer
     merged_tokenizer = get_chat_template(
         merged_tokenizer,
         chat_template = "llama-3.1",
@@ -66,7 +64,6 @@ def load_and_compute_8bit_ppl(
     # Load dataset fresh in subprocess
     dataset_ppl = load_dataset("allenai/openassistant-guanaco-reformatted", split = "eval")
 
-    # Format the dataset
     def formatting_prompts_func(examples):
         convos = examples["messages"]
         texts = [
@@ -77,21 +74,18 @@ def load_and_compute_8bit_ppl(
 
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
 
-    # Compute perplexity using the passed dataset
     ppl_value = ppl_model(merged_model, merged_tokenizer, dataset_ppl)
 
-    # IMPORTANT: Convert to Python float if it's a tensor
+    # Convert to a Python float (tensor / numpy / other)
     if torch.is_tensor(ppl_value):
-        ppl_value = ppl_value.cpu().item()  # Move to CPU and convert to Python scalar
+        ppl_value = ppl_value.cpu().item()
     elif hasattr(ppl_value, "item"):
-        ppl_value = ppl_value.item()  # Convert numpy or other array types
+        ppl_value = ppl_value.item()
     else:
-        ppl_value = float(ppl_value)  # Ensure it's a float
+        ppl_value = float(ppl_value)
 
-    # Return only the perplexity value
     result_queue.put(ppl_value)
 
-    # Clean up
     del merged_model
     del merged_tokenizer
     del dataset_ppl
@@ -99,7 +93,6 @@ def load_and_compute_8bit_ppl(
     gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 if __name__ == "__main__":
     mp.set_start_method("spawn", force = True)
 
@@ -197,12 +190,11 @@ if __name__ == "__main__":
 
     tokenizer.decode(trainer.train_dataset[0]["input_ids"])
 
-    # run training
     trainer_stats = trainer.train()
 
     add_to_comparison("Qlora model", ppl_model(model, tokenizer, dataset_ppl))
 
-    # saving and merging the model to local disk
+    # save and merge the model to local disk
     print("merge and save to local disk")
     model.save_pretrained_merged(
         save_directory = "./unsloth_out/merged_llama_text_model", tokenizer = tokenizer
@@ -214,7 +206,6 @@ if __name__ == "__main__":
     # torch.cuda.empty_cache()
     # gc.collect()
 
-    # load model from local disk and test
     print("Loading merged model in 4 bit for perplexity test")
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_llama_text_model",
@@ -251,7 +242,6 @@ if __name__ == "__main__":
 
     print_model_comparison()
 
-    # final cleanup
     safe_remove_directory("./outputs")
     safe_remove_directory("./unsloth_compiled_cache")
     safe_remove_directory("./unsloth_out")
diff --git a/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py b/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
index 0b377eca81..cdbad174a4 100644
--- a/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
+++ b/tests/saving/language_models/test_merged_model_perplexity_qwen_2.5.py
@@ -42,7 +42,6 @@ alpaca_prompt = """Below is an instruction that describes a task, paired with an
 {}"""
 
 
-# Define helper functions outside of main
 def formatting_prompts_func(examples):
     instructions = []
     inputs = []
@@ -50,7 +49,6 @@ def formatting_prompts_func(examples):
     texts = []
 
     for conversation in examples["messages"]:
-        # Extract user message and assistant response
         user_message = ""
         assistant_message = ""
 
@@ -60,13 +58,11 @@ def formatting_prompts_func(examples):
             elif turn["role"] == "assistant":
                 assistant_message = turn["content"]
 
-        # Store intermediate format
         instruction = "Complete the statement"
         instructions.append(instruction)
         inputs.append(user_message)
         outputs.append(assistant_message)
 
-        # Create formatted text
         text = alpaca_prompt.format(instruction, user_message, assistant_message)
         texts.append(text)
 
@@ -83,11 +79,10 @@ def load_and_compute_8bit_ppl(
     load_in_4bit = False,
     load_in_8bit = False,
 ):
-    """Load model and compute perplexity in subprocess"""
+    """Load model and compute perplexity in subprocess."""
     from unsloth import FastLanguageModel
     from tests.utils.perplexity_eval import ppl_model
 
-    # Load model
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_qwen_text_model",
         max_seq_length = 2048,
@@ -121,7 +116,6 @@ def load_and_compute_8bit_ppl(
         texts = []
 
         for conversation in examples["messages"]:
-            # Extract user message and assistant response
             user_message = ""
             assistant_message = ""
 
@@ -131,13 +125,11 @@ def load_and_compute_8bit_ppl(
                 elif turn["role"] == "assistant":
                     assistant_message = turn["content"]
 
-            # Store intermediate format
             instruction = "Complete the statement"
             instructions.append(instruction)
             inputs.append(user_message)
             outputs.append(assistant_message)
 
-            # Create formatted text
             text = alpaca_prompt.format(instruction, user_message, assistant_message)
             texts.append(text)
 
@@ -150,18 +142,16 @@ def load_and_compute_8bit_ppl(
 
     dataset_ppl = dataset_ppl.map(formatting_prompts_func, batched = True)
 
-    # Compute perplexity using the passed dataset
     ppl_value = ppl_model(merged_model, merged_tokenizer, dataset_ppl)
 
-    # IMPORTANT: Convert to Python float if it's a tensor
+    # Coerce to a Python float regardless of source type.
     if torch.is_tensor(ppl_value):
-        ppl_value = ppl_value.cpu().item()  # Move to CPU and convert to Python scalar
+        ppl_value = ppl_value.cpu().item()
     elif hasattr(ppl_value, "item"):
-        ppl_value = ppl_value.item()  # Convert numpy or other array types
+        ppl_value = ppl_value.item()
     else:
-        ppl_value = float(ppl_value)  # Ensure it's a float
+        ppl_value = float(ppl_value)
 
-    # Return only the perplexity value
     result_queue.put(ppl_value)
 
     # Clean up
@@ -172,7 +162,6 @@ def load_and_compute_8bit_ppl(
     # gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 if __name__ == "__main__":
     mp.set_start_method("spawn", force = True)
 
@@ -250,12 +239,11 @@ if __name__ == "__main__":
         ),
     )
 
-    # run training
     trainer_stats = trainer.train()
 
     add_to_comparison("Qlora model", ppl_model(model, tokenizer, dataset_ppl))
 
-    # saving and merging the model to local disk
+    # Merge and save to local disk.
     print("merge and save to local disk")
     model.save_pretrained_merged(
         save_directory = "./unsloth_out/merged_qwen_text_model", tokenizer = tokenizer
@@ -267,7 +255,6 @@ if __name__ == "__main__":
     # torch.cuda.empty_cache()
     # gc.collect()
 
-    # load model from local disk and test
     print("Loading merged model in 4 bit for perplexity test")
     merged_model, merged_tokenizer = FastLanguageModel.from_pretrained(
         model_name = "./unsloth_out/merged_qwen_text_model",
diff --git a/tests/saving/language_models/test_push_to_hub_merged.py b/tests/saving/language_models/test_push_to_hub_merged.py
index aa79394556..cacb1e2a10 100644
--- a/tests/saving/language_models/test_push_to_hub_merged.py
+++ b/tests/saving/language_models/test_push_to_hub_merged.py
@@ -32,7 +32,6 @@ from tests.utils.perplexity_eval import (
 )
 
 
-# Define helper functions outside of main
 def formatting_prompts_func(examples):
     convos = examples["messages"]
     texts = [
@@ -135,7 +134,7 @@ trainer = train_on_responses_only(
 trainer_stats = trainer.train()
 
 
-# saving and merging the model to local disk
+# save and merge the model to local disk
 hf_username = os.environ.get("HF_USER", "")
 if not hf_username:
     hf_username = input("Please enter your Hugging Face username: ").strip()
diff --git a/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py b/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
index 38b82c5469..59a09f06ec 100644
--- a/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
+++ b/tests/saving/language_models/test_push_to_hub_merged_sharded_index_file.py
@@ -131,7 +131,6 @@ trainer = train_on_responses_only(
     response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
 )
 
-# run training
 trainer_stats = trainer.train()
 
 
diff --git a/tests/saving/language_models/test_save_merged_grpo_model.py b/tests/saving/language_models/test_save_merged_grpo_model.py
index b5d8025fcb..63e4b970a6 100644
--- a/tests/saving/language_models/test_save_merged_grpo_model.py
+++ b/tests/saving/language_models/test_save_merged_grpo_model.py
@@ -75,7 +75,6 @@ def evaluate_merged_model(
     gc.collect()
 
 
-# Main execution code should be wrapped in this guard
 def training_run(result_queue):
     model, tokenizer = FastLanguageModel.from_pretrained(
         model_name = "meta-llama/Llama-3.2-3B-Instruct",
@@ -145,12 +144,10 @@ def training_run(result_queue):
     </answer>"""
 
         def format_limo(example):
-            # Create the assistant response
             assistant_response = f"<reasoning>\n{example['solution']}\n</reasoning>\n<answer>\n{example['answer']}\n</answer>"
 
-            # Return a DICTIONARY with the conversation in a field
             return {
-                "prompt": [  # ← This is the key change - wrap in a dict
+                "prompt": [
                     {"role": "system", "content": system_prompt},
                     {"role": "user", "content": example["question"]},
                     {"role": "assistant", "content": assistant_response},
@@ -379,7 +376,6 @@ def training_run(result_queue):
         print("COMPREHENSIVE MODEL COMPARISON")
         print(f"{'='*80}")
 
-        # Main table
         print(
             f"{'Model':<15} {'Format %':<10} {'Exact %':<10} {'Plausible %':<12} {'Confidence':<12}"
         )
@@ -394,7 +390,6 @@ def training_run(result_queue):
                 f"{result['avg_confidence']:<12.3f}"
             )
 
-        # Improvement analysis
         if len(all_results) > 1:
             print(f"\n{'='*50}")
             print("IMPROVEMENT ANALYSIS")
@@ -415,7 +410,6 @@ def training_run(result_queue):
                 print(f"  Exact matches:     {exact_improvement:+.1f}%")
                 print(f"  Plausible matches: {plausible_improvement:+.1f}%")
 
-        # Save comparison
         comparison_data = {
             "summary": all_results,
             "best_model": max(all_results, key = lambda x: x["exact_match_pct"]),
@@ -445,23 +439,18 @@ def training_run(result_queue):
 
     from datasets import load_dataset
 
-    # Load GSM8K
     gsm8k_dataset = load_dataset("openai/gsm8k", "main", split = "train")
-
-    # Load LIMO (adjust this based on your access method)
     limo_train = load_dataset("GAIR/LIMO", split = "train")
 
-    # Prepare datasets
     gsm8k_train = prepare_gsm8k_dataset(gsm8k_dataset)
     limo_train = prepare_limo_dataset(limo_train)
 
     print(f"  GSM8K train: {len(gsm8k_train)}")
     print(f"  LIMO train:  {len(limo_train) if limo_train else 0}")
 
-    # Store results
     all_results = []
 
-    # Single temperature evaluation on combined dataset
+    # Single temperature evaluation on combined dataset.
     results = evaluate_model_aime(
         model = model,
         tokenizer = tokenizer,
@@ -557,16 +546,13 @@ def training_run(result_queue):
             response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
         )
 
-        # Train
         print(f"🚂 Starting SFT training on {len(limo_train)} examples...")
         trainer.train()
 
-        # Save checkpoint
         model.save_pretrained("qlora_checkpoint")
         tokenizer.save_pretrained("qlora_checkpoint")
         print("💾 Qlora checkpoint saved!")
 
-        # Cleanup
         del trainer
         cleanup_memory()
 
@@ -574,7 +560,6 @@ def training_run(result_queue):
     else:
         print("⚠️ Skipping Qlora training - no LIMO dataset available")
 
-    # Cleanup
     cleanup_memory()
 
     global PRINTED_TIMES
@@ -596,7 +581,7 @@ def training_run(result_queue):
         ]
 
         scores = []
-        # Print only every few steps
+        # Print only every few steps.
         global PRINTED_TIMES
         global PRINT_EVERY_STEPS
         if PRINTED_TIMES % PRINT_EVERY_STEPS == 0:
@@ -613,10 +598,9 @@ def training_run(result_queue):
             if guess is None:
                 scores.append(0)
                 continue
-            # Convert to numbers
             try:
                 true_answer = float(true_answer.strip())
-                # Remove commas like in 123,456
+                # Remove commas like in 123,456.
                 guess = float(guess.strip().replace(",", ""))
                 scores.append(1.5 if guess == true_answer else -0.5)
             except:
@@ -628,7 +612,6 @@ def training_run(result_queue):
     print("🎯 STAGE 2: GRPO Fine-Tuning on GSM8K")
     print(f"{'*'*60}")
 
-    # Get max prompt length
     max_prompt_length, _ = get_max_prompt_length(gsm8k_train, tokenizer)
     max_prompt_length = min(max_prompt_length + 10, 512)  # Add buffer, cap at 512
 
@@ -670,16 +653,13 @@ def training_run(result_queue):
         train_dataset = gsm8k_train,
     )
 
-    # Train
     print(f"🚂 Starting GRPO training on {len(gsm8k_train)} examples...")
     trainer.train()
 
-    # Save checkpoint
     model.save_pretrained("grpo_checkpoint")
     tokenizer.save_pretrained("grpo_checkpoint")
     print("💾 GRPO checkpoint saved!")
 
-    # Cleanup
     del trainer
     del training_args
     cleanup_memory()
@@ -708,7 +688,6 @@ def training_run(result_queue):
     print("💾 SAVING FINAL MODEL")
     print(f"{'='*60}")
 
-    # Save as merged model
     try:
         model.save_pretrained_merged("final_merged_model", tokenizer, save_method = "merged_16bit")
         print("✅ Merged model saved to: final_merged_model/")
@@ -722,7 +701,6 @@ def training_run(result_queue):
 
     result_queue.put(results)
 
-    # Clean up
     del model
     del tokenizer
     torch.cuda.empty_cache()
@@ -771,7 +749,7 @@ if __name__ == "__main__":
     result_queue = mp.Queue()
     all_results = []
 
-    # run main finetuning and grpo loop
+    # Run main finetuning and GRPO loop.
     p = mp.Process(target = training_run, args = (result_queue,))
     p.start()
     p.join()
@@ -779,7 +757,7 @@ if __name__ == "__main__":
     results = result_queue.get()
     all_results = results
 
-    # evaluate merged model loaded 16bits
+    # Evaluate merged model loaded 16bits.
     p = mp.Process(target = evaluate_merged_model, args = (result_queue, False, False))
     p.start()
     p.join()
@@ -808,11 +786,8 @@ if __name__ == "__main__":
 
     safe_remove_directory("./unsloth_compiled_cache")
 
-    # AIME-specific comparison function
-
     print(f"\n{'='*80}")
     print("🏆 FINAL TRAINING PIPELINE RESULTS")
     print(f"{'='*80}")
 
-    # Use the AIME-specific comparison
     compare_aime_results(all_results)
diff --git a/tests/saving/non_peft/test_mistral_non_peft.py b/tests/saving/non_peft/test_mistral_non_peft.py
index b2610360fe..0ace3dd352 100644
--- a/tests/saving/non_peft/test_mistral_non_peft.py
+++ b/tests/saving/non_peft/test_mistral_non_peft.py
@@ -27,8 +27,6 @@ model, tokenizer = FastLanguageModel.from_pretrained(
 
 print("✅ Base model loaded successfully!")
 
-### Attempting save merge
-
 
 print(f"\n{'='*80}")
 print("🔍 PHASE 2: Attempting save_pretrained_merged (Should Warn)")
@@ -38,7 +36,6 @@ with warnings.catch_warnings(record = True) as w:
     warnings.simplefilter("always")
     model.save_pretrained_merged("test_output", tokenizer)
 
-    # Verify warning
     assert len(w) >= 1, "Expected warning but none raised"
     warning_msg = str(w[0].message)
     expected_msg = "Model is not a PeftModel (no Lora adapters detected). Skipping Merge. Please use save_pretrained() or push_to_hub() instead!"
@@ -55,7 +52,7 @@ print(f"{'='*80}")
 
 try:
     with warnings.catch_warnings():
-        warnings.simplefilter("error")  # Treat warnings as errors here
+        warnings.simplefilter("error")  # Treat warnings as errors
         model.save_pretrained("test_output")
         print("✅ Standard save_pretrained completed successfully!")
 except Exception as e:
diff --git a/tests/saving/non_peft/test_whisper_non_peft.py b/tests/saving/non_peft/test_whisper_non_peft.py
index 2d5676ec9c..b0f2b2e751 100644
--- a/tests/saving/non_peft/test_whisper_non_peft.py
+++ b/tests/saving/non_peft/test_whisper_non_peft.py
@@ -27,8 +27,6 @@ model, tokenizer = FastModel.from_pretrained(
 
 print("✅ Base model loaded successfully!")
 
-### Attempting save merge
-
 
 print(f"\n{'='*80}")
 print("🔍 PHASE 2: Attempting save_pretrained_merged (Should Warn)")
@@ -38,7 +36,6 @@ with warnings.catch_warnings(record = True) as w:
     warnings.simplefilter("always")
     model.save_pretrained_merged("test_output", tokenizer)
 
-    # Verify warning
     assert len(w) >= 1, "Expected warning but none raised"
     warning_msg = str(w[0].message)
     expected_msg = "Model is not a PeftModel (no Lora adapters detected). Skipping Merge. Please use save_pretrained() or push_to_hub() instead!"
diff --git a/tests/saving/test_unsloth_save.py b/tests/saving/test_unsloth_save.py
index c7dd712734..a85c119e04 100644
--- a/tests/saving/test_unsloth_save.py
+++ b/tests/saving/test_unsloth_save.py
@@ -31,7 +31,6 @@ torchao_models = [
 ]
 
 
-# Variables
 save_file_sizes = {}
 save_file_sizes["merged_16bit"] = {}
 save_file_sizes["merged_4bit"] = {}
@@ -55,7 +54,6 @@ def loaded_model_tokenizer(request):
         load_in_4bit = True,
     )
 
-    # Apply LoRA
     model = FastModel.get_peft_model(
         model,
         r = 16,
@@ -80,7 +78,6 @@ def fp16_model_tokenizer(request):
         load_in_4bit = False,  # No BnB quantization
     )
 
-    # Apply LoRA
     model = FastModel.get_peft_model(
         model,
         r = 16,
@@ -112,7 +109,6 @@ def temp_save_dir():
 
 
 def delete_quantization_config(model):
-    # Since merged, edit quantization_config
     old_config = model.config
     new_config = model.config.to_dict()
     if "quantization_config" in new_config:
@@ -134,7 +130,6 @@ def test_save_merged_16bit(model, tokenizer, temp_save_dir: str):
 
     model.save_pretrained_merged(save_path, tokenizer = tokenizer, save_method = "merged_16bit")
 
-    # Check model files
     assert os.path.isdir(save_path), f"Directory {save_path} does not exist."
     assert os.path.isfile(os.path.join(save_path, "config.json")), "config.json not found."
 
@@ -143,25 +138,23 @@ def test_save_merged_16bit(model, tokenizer, temp_save_dir: str):
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
-    # Check tokenizer files
     for file in tokenizer_files:
         assert os.path.isfile(
             os.path.join(save_path, file)
         ), f"{file} not found in the save directory."
 
-    # Check config to see if it is 16bit by checking for quantization config
+    # 16bit if there's no quantization config
     config_path = os.path.join(save_path, "config.json")
     with open(config_path, "r") as f:
         config = json.load(f)
 
     assert "quantization_config" not in config, "Quantization config not found in the model config."
 
-    # Store the size of the model files
     total_size = sum(os.path.getsize(os.path.join(save_path, f)) for f in weight_files)
     save_file_sizes["merged_16bit"][model.config._name_or_path] = total_size
     print(f"Total size of merged_16bit files: {total_size} bytes")
 
-    # Test loading the model from the saved path
+    # Verify the saved model loads
     loaded_model, loaded_tokenizer = FastLanguageModel.from_pretrained(
         save_path,
         max_seq_length = 128,
@@ -179,7 +172,6 @@ def test_save_merged_4bit(model, tokenizer, temp_save_dir: str):
 
     model.save_pretrained_merged(save_path, tokenizer = tokenizer, save_method = "merged_4bit_forced")
 
-    # Check model files
     assert os.path.isdir(save_path), f"Directory {save_path} does not exist."
     assert os.path.isfile(os.path.join(save_path, "config.json")), "config.json not found."
 
@@ -188,13 +180,11 @@ def test_save_merged_4bit(model, tokenizer, temp_save_dir: str):
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
-    # Check tokenizer files
     for file in tokenizer_files:
         assert os.path.isfile(
             os.path.join(save_path, file)
         ), f"{file} not found in the save directory."
 
-    # Store the size of the model files
     total_size = sum(os.path.getsize(os.path.join(save_path, f)) for f in weight_files)
     save_file_sizes["merged_4bit"][model.config._name_or_path] = total_size
 
@@ -204,14 +194,14 @@ def test_save_merged_4bit(model, tokenizer, temp_save_dir: str):
         total_size < save_file_sizes["merged_16bit"][model.config._name_or_path]
     ), "Merged 4bit files are larger than merged 16bit files."
 
-    # Check config to see if it is 4bit
+    # 4bit if there's a quantization config
     config_path = os.path.join(save_path, "config.json")
     with open(config_path, "r") as f:
         config = json.load(f)
 
     assert "quantization_config" in config, "Quantization config not found in the model config."
 
-    # Test loading the model from the saved path
+    # Verify the saved model loads
     loaded_model, loaded_tokenizer = FastModel.from_pretrained(
         save_path,
         max_seq_length = 128,
@@ -248,7 +238,6 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
 
     torchao_save_path = save_path + "-torchao"
 
-    # Check model files
     assert os.path.isdir(torchao_save_path), f"Directory {torchao_save_path} does not exist."
     assert os.path.isfile(os.path.join(torchao_save_path, "config.json")), "config.json not found."
 
@@ -257,13 +246,11 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
     ]
     assert len(weight_files) > 0, "No weight files found in the save directory."
 
-    # Check tokenizer files
     for file in tokenizer_files:
         assert os.path.isfile(
             os.path.join(torchao_save_path, file)
         ), f"{file} not found in the save directory."
 
-    # Store the size of the model files
     total_size = sum(os.path.getsize(os.path.join(torchao_save_path, f)) for f in weight_files)
     save_file_sizes["torchao"][model.config._name_or_path] = total_size
 
@@ -271,16 +258,14 @@ def test_save_torchao(fp16_model_tokenizer, temp_save_dir: str):
         total_size < save_file_sizes["merged_16bit"][model.config._name_or_path]
     ), "torchao files are larger than merged 16bit files."
 
-    # Check config to see if it is quantized with torchao
     config_path = os.path.join(torchao_save_path, "config.json")
     with open(config_path, "r") as f:
         config = json.load(f)
 
     assert "quantization_config" in config, "Quantization config not found in the model config."
 
-    # Test loading the model from the saved path
-    # can't set `load_in_4bit` to True because the model is torchao quantized
-    # can't quantize again with bitsandbytes
+    # load_in_4bit must stay False: a torchao-quantized model can't be
+    # re-quantized with bitsandbytes.
     import torch.serialization
 
     with torch.serialization.safe_globals([getattr]):
@@ -308,7 +293,6 @@ def test_save_and_inference_torchao(fp16_model_tokenizer, temp_save_dir: str):
 
     torchao_config = Int8DynamicActivationInt8WeightConfig()
 
-    # Save with TorchAO
     model.save_pretrained_torchao(
         save_path,
         tokenizer = tokenizer,
@@ -318,12 +302,10 @@ def test_save_and_inference_torchao(fp16_model_tokenizer, temp_save_dir: str):
 
     torchao_save_path = save_path + "-torchao"
 
-    # Verify files exist
     assert os.path.isdir(
         torchao_save_path
     ), f"TorchAO directory {torchao_save_path} does not exist."
 
-    # Load with safe globals
     import torch.serialization
 
     with torch.serialization.safe_globals([getattr]):
@@ -334,7 +316,7 @@ def test_save_and_inference_torchao(fp16_model_tokenizer, temp_save_dir: str):
             load_in_4bit = False,
         )
 
-    FastModel.for_inference(loaded_model)  # Enable native 2x faster inference
+    FastModel.for_inference(loaded_model)
 
     messages = [
         {
@@ -345,21 +327,20 @@ def test_save_and_inference_torchao(fp16_model_tokenizer, temp_save_dir: str):
     inputs = loaded_tokenizer.apply_chat_template(
         messages,
         tokenize = True,
-        add_generation_prompt = True,  # Must add for generation
+        add_generation_prompt = True,  # required for generation
         return_tensors = "pt",
     ).to("cuda")
 
-    outputs = loaded_model.generate(  # ← Use loaded_model, not model
+    outputs = loaded_model.generate(
         input_ids = inputs,
         max_new_tokens = 64,
-        use_cache = False,  # Avoid cache issues
+        use_cache = False,  # avoid cache issues
         temperature = 1.5,
         min_p = 0.1,
         do_sample = True,
         pad_token_id = loaded_tokenizer.pad_token_id or loaded_tokenizer.eos_token_id,
     )
 
-    # Decode with the LOADED tokenizer
     generated_text = loaded_tokenizer.decode(outputs[0], skip_special_tokens = True)
     input_text = loaded_tokenizer.decode(inputs[0], skip_special_tokens = True)
     response_part = generated_text[len(input_text) :].strip()
diff --git a/tests/saving/text_to_speech_models/test_csm.py b/tests/saving/text_to_speech_models/test_csm.py
index dd2287d1d6..3d04bc39cb 100644
--- a/tests/saving/text_to_speech_models/test_csm.py
+++ b/tests/saving/text_to_speech_models/test_csm.py
@@ -139,15 +139,13 @@ try:
     inputs = processor(f"[{speaker_id}]{text}", add_special_tokens = True).to("cuda")
     audio_values = model.generate(
         **inputs,
-        max_new_tokens = 125,  # 125 tokens is 10 seconds of audio, for longer speech increase this
-        # play with these parameters to get the best results
+        max_new_tokens = 125,  # 125 tokens ~= 10 seconds of audio
         depth_decoder_temperature = 0.6,
         depth_decoder_top_k = 0,
         depth_decoder_top_p = 0.9,
         temperature = 0.8,
         top_k = 50,
         top_p = 1.0,
-        #########################################################
         output_audio = True,
     )
     audio = audio_values[0].to(torch.float32).cpu().numpy()
@@ -157,8 +155,6 @@ except Exception as e:
     assert False, f"Inference failed with exception: {e}"
 
 
-## assert that transcribed_text contains The birch canoe slid on the smooth planks. Glued the sheet to the dark blue background. It's easy to tell the depth of a well. Four hours of steady work faced us.
-
 print("✅ All sections passed successfully!")
 
 
diff --git a/tests/saving/text_to_speech_models/test_orpheus.py b/tests/saving/text_to_speech_models/test_orpheus.py
index 2915749d99..83adaf8dbc 100644
--- a/tests/saving/text_to_speech_models/test_orpheus.py
+++ b/tests/saving/text_to_speech_models/test_orpheus.py
@@ -99,7 +99,7 @@ print("🔍 SECTION 4: Saving and Merging Model")
 print(f"{'='*80}")
 
 with warnings.catch_warnings():
-    warnings.simplefilter("error")  # Treat warnings as errors
+    warnings.simplefilter("error")
     try:
         model.save_pretrained_merged("orpheus", tokenizer)
         print("✅ Model saved and merged successfully without warnings!")
@@ -135,7 +135,6 @@ print(f"{'='*80}")
 
 FastLanguageModel.for_inference(model)  # Enable native 2x faster inference
 
-# Moving snac_model cuda to cpu
 snac_model.to("cpu")
 prompts = [
     "Hey there my name is Elise, <giggles> and I'm a speech generation model that can sound like a person.",
@@ -263,7 +262,6 @@ try:
 except Exception as e:
     assert False, f"Inference failed with exception: {e}"
 
-# Verify the file exists
 import os
 
 assert os.path.exists(output_path), f"Audio file not found at {output_path}"
diff --git a/tests/saving/text_to_speech_models/test_whisper.py b/tests/saving/text_to_speech_models/test_whisper.py
index d0eeb49d17..e0271d098e 100644
--- a/tests/saving/text_to_speech_models/test_whisper.py
+++ b/tests/saving/text_to_speech_models/test_whisper.py
@@ -153,7 +153,6 @@ import torch
 
 FastModel.for_inference(model)
 model.eval()
-# Create pipeline without specifying the device
 whisper = pipeline(
     "automatic-speech-recognition",
     model = model,
@@ -161,9 +160,8 @@ whisper = pipeline(
     feature_extractor = tokenizer.feature_extractor,
     processor = tokenizer,
     return_language = True,
-    torch_dtype = torch.float16,  # Remove the device parameter
+    torch_dtype = torch.float16,
 )
-# Example usage
 audio_file = "Speech_12dB_s16.flac"
 transcribed_text = whisper(audio_file)
 # audio, sr = sf.read(audio_file)
diff --git a/tests/saving/vision_models/test_index_file_sharded_model.py b/tests/saving/vision_models/test_index_file_sharded_model.py
index 79a25ec666..6f2d0ff782 100644
--- a/tests/saving/vision_models/test_index_file_sharded_model.py
+++ b/tests/saving/vision_models/test_index_file_sharded_model.py
@@ -1,5 +1,3 @@
-## Import required libraries
-
 from unsloth import FastVisionModel, is_bf16_supported
 from unsloth.trainer import UnslothVisionDataCollator
 
@@ -18,14 +16,10 @@ sys.path.insert(0, str(REPO_ROOT))
 from tests.utils.cleanup_utils import safe_remove_directory
 
 
-## Dataset Preparation"""
-
 print("\n📊 Loading and preparing dataset...")
 dataset = load_dataset("lbourdois/OCR-liboaccn-OPUS-MIT-5M-clean", "en", split = "train")
-# To select the first 2000 examples
 train_dataset = dataset.select(range(2000))
 
-# To select the next 200 examples for evaluation
 eval_dataset = dataset.select(range(2000, 2200))
 
 print(f"✅ Dataset loaded successfully!")
@@ -33,7 +27,7 @@ print(f"   📈 Training samples: {len(train_dataset)}")
 print(f"   📊 Evaluation samples: {len(eval_dataset)}")
 
 
-# Convert dataset to OAI messages
+# Convert dataset to OAI messages.
 def format_data(sample):
     return {
         "messages": [
@@ -64,8 +58,7 @@ def format_data(sample):
 
 print("\n🔄 Formatting dataset for vision training...")
 system_message = "You are an expert french ocr system."
-# Convert dataset to OAI messages
-# need to use list comprehension to keep Pil.Image type, .map convert image to bytes
+# List comprehension (not .map) keeps PIL.Image type; .map would convert images to bytes.
 train_dataset = [format_data(sample) for sample in train_dataset]
 eval_dataset = [format_data(sample) for sample in eval_dataset]
 print("✅ Dataset formatting completed!")
@@ -76,11 +69,9 @@ print("✅ Dataset formatting completed!")
 print("\n" + "=" * 80)
 print("=== MODEL LOADING AND SETUP ===".center(80))
 print("=" * 80 + "\n")
-# Load Base Model
 print("🤖 Loading base vision model...")
 try:
     model, tokenizer = FastVisionModel.from_pretrained(
-        # model_name = "unsloth/Qwen2-VL-7B-Instruct",
         model_name = "unsloth/Qwen2-VL-7B-Instruct",
         max_seq_length = 2048,  # Choose any for long context!
         load_in_4bit = True,  # 4 bit quantization to reduce memory
@@ -92,7 +83,6 @@ except Exception as e:
     raise
 
 print("\n🔧 Setting up LoRA configuration...")
-## Lora Finetuning
 try:
     model = FastVisionModel.get_peft_model(
         model,
@@ -175,7 +165,6 @@ except Exception as e:
 print("\n" + "=" * 80)
 print("=== STARTING TRAINING ===".center(80))
 print("=" * 80 + "\n")
-# run training
 try:
     print("🚀 Starting training process...")
     trainer_stats = trainer.train()
@@ -213,7 +202,7 @@ success = {
     "safetensors_check": False,
     "download": False,
 }
-# Stage 1: Upload model to Hub
+# Stage 1: upload model to Hub
 try:
     print("\n" + "=" * 80)
     print("=== UPLOADING MODEL TO HUB ===".center(80))
@@ -226,7 +215,7 @@ except Exception as e:
     print(f"❌ Failed to upload model: {e}")
     raise Exception("Model upload failed.")
 
-# Stage 2: Verify safetensors.index.json exists
+# Stage 2: verify safetensors.index.json exists
 try:
     print("\n" + "=" * 80)
     print("=== VERIFYING REPO CONTENTS ===".center(80))
@@ -245,7 +234,7 @@ except Exception as e:
     print(f"❌ Verification failed: {e}")
     raise Exception("Repo verification failed.")
 
-# test downloading model even if cached
+# Stage 3: test download even if cached
 safe_remove_directory(f"./{hf_username}")
 
 try:
@@ -253,19 +242,16 @@ try:
     print("=== TESTING MODEL DOWNLOAD ===".center(80))
     print("=" * 80 + "\n")
     print("📥 Testing model download...")
-    # Force download even if cached
     test_model, test_tokenizer = FastVisionModel.from_pretrained(repo_name)
     success["download"] = True
     print("✅ Model downloaded successfully!")
 
-    # Clean up test model
     del test_model, test_tokenizer
     torch.cuda.empty_cache()
 except Exception as e:
     print(f"❌ Download failed: {e}")
     raise Exception("Model download failed.")
 
-# Final report
 print("\n" + "=" * 80)
 print("=== VALIDATION REPORT ===".center(80))
 print("=" * 80 + "\n")
@@ -281,7 +267,6 @@ else:
     raise Exception("Validation failed for one or more stages.")
 
 
-# Final cleanup
 print("\n🧹 Cleaning up temporary files...")
 safe_remove_directory("./checkpoints")
 safe_remove_directory("./unsloth_compiled_cache")
diff --git a/tests/saving/vision_models/test_push_to_hub_merged.py b/tests/saving/vision_models/test_push_to_hub_merged.py
index 86c7b56cf2..d83c66de4b 100644
--- a/tests/saving/vision_models/test_push_to_hub_merged.py
+++ b/tests/saving/vision_models/test_push_to_hub_merged.py
@@ -23,10 +23,10 @@ from tests.utils.cleanup_utils import safe_remove_directory
 
 print("\n📊 Loading and preparing dataset...")
 dataset = load_dataset("lbourdois/OCR-liboaccn-OPUS-MIT-5M-clean", "en", split = "train")
-# To select the first 2000 examples
+# First 2000 examples for training
 train_dataset = dataset.select(range(2000))
 
-# To select the next 200 examples for evaluation
+# Next 200 examples for evaluation
 eval_dataset = dataset.select(range(2000, 2200))
 
 print(f"✅ Dataset loaded successfully!")
@@ -65,8 +65,7 @@ def format_data(sample):
 
 print("\n🔄 Formatting dataset for vision training...")
 system_message = "You are an expert french ocr system."
-# Convert dataset to OAI messages
-# need to use list comprehension to keep Pil.Image type, .map convert image to bytes
+# Use a list comprehension (not .map) to keep PIL.Image type; .map converts images to bytes.
 train_dataset = [format_data(sample) for sample in train_dataset]
 eval_dataset = [format_data(sample) for sample in eval_dataset]
 print("✅ Dataset formatting completed!")
diff --git a/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py b/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
index 391d7bacca..548e6bfc37 100644
--- a/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
+++ b/tests/saving/vision_models/test_save_merge_qwen2.5vl32B_model_ocr_benchmark.py
@@ -23,10 +23,7 @@ from tests.utils.ocr_eval import OCRModelEvaluator
 from datasets import load_dataset
 
 dataset = load_dataset("lbourdois/OCR-liboaccn-OPUS-MIT-5M-clean", "en", split = "train")
-# To select the first 2000 examples
 train_dataset = dataset.select(range(2000))
-
-# To select the next 200 examples for evaluation
 eval_dataset = dataset.select(range(2000, 2200))
 
 
@@ -60,8 +57,7 @@ def format_data(sample):
 
 
 system_message = "You are an expert french ocr system."
-# Convert dataset to OAI messages
-# need to use list comprehension to keep Pil.Image type, .map convert image to bytes
+# List comprehension (not .map) to keep PIL.Image type; .map converts images to bytes.
 train_dataset = [format_data(sample) for sample in train_dataset]
 eval_dataset = [format_data(sample) for sample in eval_dataset]
 
@@ -73,12 +69,10 @@ import pandas as pd
 from jiwer import wer, cer
 from qwen_vl_utils import process_vision_info
 
-#
 ocr_evaluator = OCRModelEvaluator()
 model_comparison_results = {}
 
 ## Finetuning Setup and Run
-# Load Base Model
 
 model, tokenizer = FastVisionModel.from_pretrained(
     model_name = "unsloth/Qwen2.5-VL-32B-Instruct-bnb-4bit",
@@ -88,7 +82,7 @@ model, tokenizer = FastVisionModel.from_pretrained(
     full_finetuning = False,  # [NEW!] We have full finetuning now!
 )
 
-# benchmark base model performance
+# Benchmark base model
 model_name = "Unsloth Base model"
 FastVisionModel.for_inference(model)
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
@@ -119,7 +113,7 @@ model = FastVisionModel.get_peft_model(
 from unsloth import is_bf16_supported
 from unsloth.trainer import UnslothVisionDataCollator
 
-FastVisionModel.for_training(model)  # Enable for training!
+FastVisionModel.for_training(model)
 model.config.use_cache = False
 
 
@@ -159,7 +153,6 @@ trainer = SFTTrainer(
     ),
 )
 
-# run training
 trainer_stats = trainer.train()
 
 model.save_pretrained("unsloth-qwen2.5-vl-32b-french-ocr-adapter", tokenizer)
@@ -167,7 +160,6 @@ tokenizer.save_pretrained("unsloth-qwen2.5-vl-32b-french-ocr-adapter")
 
 ## Measure Adapter Performance
 
-# benchmark lora model performance
 model_name = "Unsloth lora adapter model"
 FastVisionModel.for_inference(model)
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
@@ -191,7 +183,7 @@ base = find_lora_base_model(model)
 
 print((base.__class__.__name__))
 
-# merge default 16 bits
+# Merge to 16-bit (default)
 model.save_pretrained_merged(
     save_directory = "qwen2.5-ocr-merged-finetune-merge-16bit", tokenizer = tokenizer
 )
@@ -205,7 +197,6 @@ model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2.5-ocr-merged-finetune-merge-16bit", load_in_4bit = False, load_in_8bit = False
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-16bits"
 model.config.use_cache = True
 
@@ -217,12 +208,11 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-# load 16bits-merged model in 4 bits
+# Load 16bits-merged model in 4 bits
 model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2.5-ocr-merged-finetune-merge-16bit", load_in_4bit = True, load_in_8bit = False
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-4bits"
 model.config.use_cache = True
 
@@ -234,12 +224,11 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-# load model in 8 bits
+# Load 16bits-merged model in 8 bits
 model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2.5-ocr-merged-finetune-merge-16bit", load_in_4bit = False, load_in_8bit = True
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-8bits"
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
     model,
@@ -270,7 +259,6 @@ ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 # ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
 # Model comparison report
-# print model comparison
 ocr_evaluator.print_model_comparison()
 
 
diff --git a/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py b/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
index b4812cdfa8..66064600ea 100644
--- a/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
+++ b/tests/saving/vision_models/test_save_merge_vision_model_ocr_benchmark.py
@@ -19,18 +19,15 @@ from tests.utils.cleanup_utils import safe_remove_directory
 from tests.utils.ocr_eval import OCRModelEvaluator
 
 
-## Dataset Preparation
 from datasets import load_dataset
 
 dataset = load_dataset("lbourdois/OCR-liboaccn-OPUS-MIT-5M-clean", "en", split = "train")
-# To select the first 2000 examples
 train_dataset = dataset.select(range(2000))
 
-# To select the next 200 examples for evaluation
 eval_dataset = dataset.select(range(2000, 2200))
 
 
-# Convert dataset to OAI messages
+# Convert dataset to OAI messages.
 def format_data(sample):
     return {
         "messages": [
@@ -60,12 +57,10 @@ def format_data(sample):
 
 
 system_message = "You are an expert french ocr system."
-# Convert dataset to OAI messages
-# need to use list comprehension to keep Pil.Image type, .map convert image to bytes
+# List comprehension (not .map) keeps PIL.Image type; .map would convert images to bytes.
 train_dataset = [format_data(sample) for sample in train_dataset]
 eval_dataset = [format_data(sample) for sample in eval_dataset]
 
-## Setup OCR main evaluation function and helpers
 import os
 import torch
 from tqdm import tqdm
@@ -73,13 +68,9 @@ import pandas as pd
 from jiwer import wer, cer
 from qwen_vl_utils import process_vision_info
 
-#
 ocr_evaluator = OCRModelEvaluator()
 model_comparison_results = {}
 
-## Finetuning Setup and Run
-# Load Base Model
-
 model, tokenizer = FastVisionModel.from_pretrained(
     model_name = "unsloth/Qwen2-VL-7B-Instruct",
     max_seq_length = 2048,  # Choose any for long context!
@@ -88,7 +79,7 @@ model, tokenizer = FastVisionModel.from_pretrained(
     full_finetuning = False,  # [NEW!] We have full finetuning now!
 )
 
-# benchmark base model performance
+# Benchmark base model performance.
 model_name = "Unsloth Base model"
 FastVisionModel.for_inference(model)
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
@@ -96,7 +87,6 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-## Lora Finetuning
 model = FastVisionModel.get_peft_model(
     model,
     finetune_vision_layers = True,  # Turn off for just text!
@@ -159,15 +149,12 @@ trainer = SFTTrainer(
     ),
 )
 
-# run training
 trainer_stats = trainer.train()
 
 model.save_pretrained("unsloth-qwen2-7vl-french-ocr-adapter", tokenizer)
 tokenizer.save_pretrained("unsloth-qwen2-7vl-french-ocr-adapter")
 
-## Measure Adapter Performance
-
-# benchmark lora model performance
+# Benchmark lora adapter model performance.
 model_name = "Unsloth lora adapter model"
 FastVisionModel.for_inference(model)
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
@@ -175,8 +162,6 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-## Merge Model
-
 
 def find_lora_base_model(model_to_inspect):
     current = model_to_inspect
@@ -191,21 +176,17 @@ base = find_lora_base_model(model)
 
 print((base.__class__.__name__))
 
-# merge default 16 bits
+# Merge at default 16 bits.
 model.save_pretrained_merged(
     save_directory = "qwen2-ocr-merged-finetune-merge-16bit", tokenizer = tokenizer
 )
 
 
-## Benchmark merged model performance
-
-### 16 bits merged model
-
+# Benchmark 16-bit merged model loaded at various precisions.
 model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2-ocr-merged-finetune-merge-16bit", load_in_4bit = False, load_in_8bit = False
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-16bits"
 model.config.use_cache = True
 
@@ -217,12 +198,11 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-# load 16bits-merged model in 4 bits
+# Load 16bits-merged model in 4 bits.
 model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2-ocr-merged-finetune-merge-16bit", load_in_4bit = True, load_in_8bit = False
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-4bits"
 model.config.use_cache = True
 
@@ -234,12 +214,11 @@ avg_wer, avg_cer = ocr_evaluator.evaluate_model(
 )
 ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-# load model in 8 bits
+# Load 16bits-merged model in 8 bits.
 model, tokenizer = FastVisionModel.from_pretrained(
     "./qwen2-ocr-merged-finetune-merge-16bit", load_in_4bit = False, load_in_8bit = True
 )
 
-# benchmark 4bit loaded, 16bits merged model performance
 model_name = "Unsloth 16bits-merged model load-8bits"
 avg_wer, avg_cer = ocr_evaluator.evaluate_model(
     model,
@@ -269,12 +248,9 @@ ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 # avg_wer, avg_cer = ocr_evaluator.evaluate_model(model, tokenizer, eval_dataset, output_dir="unsloth_4bits_merged_model_load_8bits_results")
 # ocr_evaluator.add_to_comparison(model_name, avg_wer, avg_cer)
 
-# Model comparison report
-# print model comparison
 ocr_evaluator.print_model_comparison()
 
 
-# Final cleanup
 print("\n🧹 Cleaning up temporary files...")
 safe_remove_directory("./unsloth-qwen2-7vl-french-ocr-adapter")
 safe_remove_directory("./unsloth-qwen2-7vl-french-ocr-checkpoints")
diff --git a/tests/security/conftest.py b/tests/security/conftest.py
index 6febeec3e7..c5071842e5 100644
--- a/tests/security/conftest.py
+++ b/tests/security/conftest.py
@@ -1,11 +1,8 @@
 """Shared fixtures for the security regression suite.
 
-The scanner scripts under audit are designed to be offline-safe. Pin
-that invariant by autouse-installing a session-scoped network blocker
-that refuses any non-loopback `socket.connect()` from inside the test
-process. If a future test (or a scanner regression) accidentally tries
-to reach the public internet, pytest fails loudly instead of leaking
-the request.
+The scanners under audit must be offline-safe. An autouse session-scoped network
+blocker refuses any non-loopback `socket.connect()` so a regression that reaches
+the internet fails loudly instead of leaking the request.
 """
 
 from __future__ import annotations
@@ -17,8 +14,7 @@ from pathlib import Path
 import pytest
 
 
-# Make `scripts/` importable as a package so tests can grab the scanner
-# constants directly. The repo root sits two levels above this file.
+# Make `scripts/` importable so tests can grab scanner constants directly
 REPO_ROOT = Path(__file__).resolve().parents[2]
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
@@ -70,11 +66,8 @@ class _BlockedSocket(socket.socket):
 
 @pytest.fixture(scope = "session", autouse = True)
 def network_blocker():
-    """Session-scoped fixture; replaces `socket.socket` with a blocker.
-
-    Yields nothing; the swap is the side effect. Restored at teardown
-    so other test sessions (run interleaved) see a clean module.
-    """
+    """Session-scoped fixture; swaps `socket.socket` for a blocker, restored at
+    teardown so interleaved sessions see a clean module."""
     original = socket.socket
     socket.socket = _BlockedSocket  # type: ignore[assignment]
     try:
diff --git a/tests/security/fixtures/_build.py b/tests/security/fixtures/_build.py
index b2f862a23e..4cbda6aab5 100644
--- a/tests/security/fixtures/_build.py
+++ b/tests/security/fixtures/_build.py
@@ -1,20 +1,12 @@
 """Deterministic builder for the wheel + sdist binary fixtures.
 
-This script is NOT run from CI; the produced .whl / .tar.gz bytes are
-committed alongside it. Re-run only when the IOC literal changes.
+Not run from CI; the produced .whl / .tar.gz bytes are committed alongside
+it. Re-run only when the IOC literal changes.
 
-Determinism strategy
---------------------
-- All member timestamps fixed to `SOURCE_DATE_EPOCH=0` (Unix epoch).
-- All members written with uid=0, gid=0, uname="", gname="".
-- Permission bits fixed: 0o644 for files, 0o755 for directories.
-- Members emitted in sorted order so the archive byte stream does not
-  depend on filesystem iteration order.
-- `zipfile.ZipFile` is invoked with `compresslevel=6` (default DEFLATE)
-  to keep output stable across stdlib versions.
-
-Re-running this script and diffing the .whl bytes against git is the
-regression test for determinism (also asserted in test_scan_packages).
+Determinism: fixed timestamps (SOURCE_DATE_EPOCH=0), uid/gid=0, empty
+uname/gname, fixed perms (0o644 files / 0o755 dirs), sorted member order,
+and DEFLATE compresslevel=6 for stability across stdlib versions. Diffing
+re-built .whl bytes against git is the regression test (see test_scan_packages).
 """
 
 from __future__ import annotations
@@ -33,9 +25,8 @@ _ZIP_DOS_EPOCH = (1980, 1, 1, 0, 0, 0)
 HERE = Path(__file__).resolve().parent
 
 
-# The IOC literal that scan_packages.py must trip on. Keep this in
-# sync with KNOWN_IOC_STRINGS in scripts/scan_npm_packages.py and
-# RE_MAY12_IOC in scripts/scan_packages.py.
+# IOC literal scan_packages.py must trip on. Keep in sync with
+# KNOWN_IOC_STRINGS (scan_npm_packages.py) and RE_MAY12_IOC (scan_packages.py).
 MALICIOUS_SETUP_PY = '''"""Test fixture: do NOT install.
 
 This file embeds the May-12 Mini Shai-Hulud IOC literal so the
diff --git a/tests/security/test_lockfile_supply_chain_audit.py b/tests/security/test_lockfile_supply_chain_audit.py
index cec07aea28..905c4afcac 100644
--- a/tests/security/test_lockfile_supply_chain_audit.py
+++ b/tests/security/test_lockfile_supply_chain_audit.py
@@ -51,10 +51,8 @@ def _run_auditor(
 
 
 def test_malicious_lockfile_exits_1(tmp_path):
-    """The malicious fixture combines a non-registry resolved URL, a
-    known IOC substring (`filev2.getsession.org`), and a missing
-    integrity hash. The auditor must refuse with exit 1.
-    """
+    """Fixture combines a non-registry resolved URL, a known IOC substring
+    (`filev2.getsession.org`), and a missing integrity hash: auditor exits 1."""
     fixture = FIXTURES / "malicious_lockfile.json"
     assert fixture.is_file()
     proc = _run_auditor(root = tmp_path, npm_lockfiles = [fixture])
@@ -66,13 +64,9 @@ def test_malicious_lockfile_exits_1(tmp_path):
     assert "non-registry-resolved-url" in combined
     assert "missing-integrity-hash" in combined
     assert "known-ioc-string" in combined
-    # Verify the scanner WROTE the IOC name into its stdout/stderr. The
-    # literal is constructed at runtime so CodeQL's
-    # py/incomplete-url-substring-sanitization rule (which fires on
-    # source-literal + `in` even when the operand is the scanner's own
-    # output, not a URL being sanitized) does not false-positive across
-    # pre-commit reformatting that may split the assert onto multiple
-    # lines and detach an inline lgtm comment from the operator.
+    # IOC literal built at runtime so CodeQL's
+    # py/incomplete-url-substring-sanitization rule doesn't false-positive on
+    # the source-literal + `in` (the operand is the scanner's own output).
     _ioc_host = "filev2." + "getsession.org"
     assert _ioc_host in combined
 
@@ -170,15 +164,9 @@ checksum = "0000000000000000000000000000000000000000000000000000000000000000"
 
 
 def test_malicious_cargo_lockfile_refused(tmp_path):
-    """Inline Cargo.lock with `source = "git+https://example.com/..."`
-    must trip the `non-registry-cargo-source` check.
-
-    `non-registry-cargo-source` is an advisory finding kind in the
-    auditor's default mode (per the audit script's BLOCKING_KINDS
-    set). To exercise the historical "refuse to install" behavior we
-    pass --strict here; that promotes every finding to blocking and
-    keeps the test honest about its intent (detection + refusal).
-    """
+    """Inline Cargo.lock with a `git+https://...` source must trip the
+    `non-registry-cargo-source` check. It's advisory in default mode, so
+    --strict promotes it to blocking to exercise the refuse-to-install path."""
     lockfile = tmp_path / "Cargo.lock"
     lockfile.write_text(_MALICIOUS_CARGO_LOCK)
     proc = _run_auditor(
@@ -231,13 +219,9 @@ def test_audit_cargo_lockfile_direct_call(tmp_path):
 
 
 def test_gha_escape_collapses_finding_to_one_line():
-    """`_gha_escape()` must collapse newlines (`%0A`), carriage
-    returns (`%0D`), and percent signs (`%25`) so that
-    `::warning::<msg>` / `::error::<msg>` render the full finding
-    in the GitHub Actions UI annotation instead of being truncated
-    at the first newline. The `%` replacement must happen first or
-    the subsequent `%0A` / `%0D` escapes get double-encoded.
-    """
+    """`_gha_escape()` collapses newlines (`%0A`), carriage returns (`%0D`),
+    and percent signs (`%25`) so GHA annotations aren't truncated at the first
+    newline. `%` must escape first or the `%0A`/`%0D` escapes double-encode."""
     assert lsa._gha_escape("a\nb\nc") == "a%0Ab%0Ac"
     assert lsa._gha_escape("a\rb") == "a%0Db"
     assert lsa._gha_escape("100%") == "100%25"
@@ -260,13 +244,9 @@ def test_gha_escape_collapses_finding_to_one_line():
 
 
 def test_advisory_finding_emitted_as_single_line_annotation(tmp_path):
-    """End-to-end check: the `::warning::` line emitted for an
-    advisory finding must be a SINGLE physical line (the rest of
-    the Finding is `%0A`-escaped inside the message). Regression
-    test for the gemini-code-assist review on PR #5604: without
-    `_gha_escape`, GitHub Actions truncates the annotation after
-    `[kind] path` and the package + detail fields never render.
-    """
+    """The `::warning::` line for an advisory finding must be a SINGLE physical
+    line (rest of the Finding `%0A`-escaped). Regression for PR #5604: without
+    `_gha_escape`, GHA truncates after `[kind] path` and drops package/detail."""
     lockfile = tmp_path / "Cargo.lock"
     lockfile.write_text(_MALICIOUS_CARGO_LOCK)
     proc = _run_auditor(
@@ -296,11 +276,9 @@ def test_advisory_finding_emitted_as_single_line_annotation(tmp_path):
 
 
 def test_skip_env_var_with_short_value_rejected(tmp_path):
-    """`UNSLOTH_LOCKFILE_AUDIT_SKIP=1` used to silently bypass the
-    audit. Per SF4 it must instead emit a `::warning::` to stderr and
-    fall through to run the audit. A real justification value
-    (>=5 chars, not a boolean shape) is still honored.
-    """
+    """`UNSLOTH_LOCKFILE_AUDIT_SKIP=1` must no longer silently bypass: per SF4
+    it warns and falls through to run the audit. A real justification value
+    (>=5 chars, not a boolean shape) is still honored."""
     fixture = FIXTURES / "clean_lockfile.json"
 
     # Case 1 -- "1" rejected, audit RUNS.
diff --git a/tests/security/test_new_install_scripts.py b/tests/security/test_new_install_scripts.py
index 9a73f4b0d9..e71659dd88 100644
--- a/tests/security/test_new_install_scripts.py
+++ b/tests/security/test_new_install_scripts.py
@@ -44,9 +44,7 @@ def _write(path: Path, content: dict) -> Path:
     return path
 
 
-# ---------------------------------------------------------------------------
-# Lockfile fixtures.
-# ---------------------------------------------------------------------------
+# Lockfile fixtures
 
 
 def _v3_lockfile(packages: dict) -> dict:
@@ -70,9 +68,7 @@ def _v2_lockfile(packages: dict, dependencies: dict) -> dict:
     }
 
 
-# ---------------------------------------------------------------------------
-# Tests.
-# ---------------------------------------------------------------------------
+# Tests
 
 
 def test_no_new_install_scripts_exit_0(tmp_path: Path):
diff --git a/tests/security/test_scan_npm_packages.py b/tests/security/test_scan_npm_packages.py
index fb575b730d..2c79b9c3ed 100644
--- a/tests/security/test_scan_npm_packages.py
+++ b/tests/security/test_scan_npm_packages.py
@@ -46,14 +46,9 @@ def _run_scanner(lockfile: Path, *, timeout: int = 30) -> subprocess.CompletedPr
 
 
 def test_malicious_lockfile_exits_1():
-    """Structural IOCs alone must fail the scanner.
-
-    `structural_only_lockfile.json` contains: (a) a non-registry
-    `resolved` URL (filev2.getsession.org), (b) an entry missing
-    its `integrity` field. Both are caught in `parse_lockfile()`
-    before any tarball download attempt -- so the test is fully
-    offline.
-    """
+    """Structural IOCs alone must fail the scanner. The fixture has a
+    non-registry `resolved` URL and a missing `integrity` field, both caught in
+    `parse_lockfile()` before any tarball download, so the test is offline."""
     fixture = FIXTURES / "structural_only_lockfile.json"
     assert fixture.is_file(), fixture
     proc = _run_scanner(fixture)
@@ -166,12 +161,8 @@ def test_blocked_npm_versions_complete():
     reason = "Fork 1 (BLOCKED_NPM_VERSIONS pre-fetch hook) not merged yet",
 )
 def test_blocked_npm_versions_short_circuits_download():
-    """With Fork 1's pre-fetch hook, the malicious tanstack entry
-    must produce a `blocked-known-malicious` finding without ever
-    calling out to the npm registry. The full malicious fixture
-    contains the tanstack entry; the test asserts exit 1 and that
-    the new finding pattern appears in scanner output.
-    """
+    """The pre-fetch hook must flag the malicious tanstack entry as
+    `blocked-known-malicious` (exit 1) without hitting the npm registry."""
     fixture = FIXTURES / "malicious_lockfile.json"
     proc = _run_scanner(fixture, timeout = 10)
     assert proc.returncode == 1
@@ -203,10 +194,8 @@ def _extract_pkg_with_ioc(ioc: str, tmp_path: Path) -> Path:
 
 
 def test_every_known_ioc_string_caught(tmp_path):
-    """For every entry in `KNOWN_IOC_STRINGS`, embed the IOC in a
-    one-file package tree and confirm `scan_extracted_tree()`
-    surfaces it. Guards against silent regex / table drift.
-    """
+    """Embed each `KNOWN_IOC_STRINGS` entry in a one-file package tree and
+    confirm `scan_extracted_tree()` surfaces it. Guards against table drift."""
     iocs = snp.KNOWN_IOC_STRINGS
     assert iocs, "KNOWN_IOC_STRINGS unexpectedly empty"
 
@@ -234,10 +223,8 @@ def test_every_known_ioc_string_caught(tmp_path):
 
 
 def test_parse_lockfile_structural_findings():
-    """`parse_lockfile()` returns (entries, structural_findings). The
-    structural-only fixture should produce 2 structural findings and
-    0 entries (because both bad entries are `continue`d).
-    """
+    """The structural-only fixture yields 2 structural findings and 0 entries
+    (both bad entries are `continue`d in `parse_lockfile()`)."""
     entries, struct = snp.parse_lockfile(FIXTURES / "structural_only_lockfile.json")
     assert entries == []
     patterns = {f.pattern for f in struct}
diff --git a/tests/security/test_scan_packages.py b/tests/security/test_scan_packages.py
index b35d89ce48..5b6e115213 100644
--- a/tests/security/test_scan_packages.py
+++ b/tests/security/test_scan_packages.py
@@ -1,9 +1,8 @@
 """Regression tests for `scripts/scan_packages.py`.
 
-The scanner's primary entry point (`download_packages`) reaches PyPI;
-to keep the suite offline we exercise it via the module's public
-in-process helpers (`scan_archive`) and assert against the binary
-wheel / sdist fixtures committed under `tests/security/fixtures/`.
+`download_packages` reaches PyPI; to stay offline we drive the in-process
+`scan_archive` helper against the wheel/sdist fixtures under
+`tests/security/fixtures/`.
 """
 
 from __future__ import annotations
@@ -37,9 +36,8 @@ def test_fixture_files_exist():
 def test_fixture_bytes_are_deterministic(tmp_path):
     """Re-running `_build.py` must produce byte-identical archives.
 
-    The build helper sets every member's mtime/uid/gid/mode and emits
-    members in sorted order. We rebuild into a temp dir and compare
-    SHA-256 against the committed bytes.
+    The build helper pins each member's mtime/uid/gid/mode and sorts members.
+    Rebuild into a temp dir and compare SHA-256 against the committed bytes.
     """
     # Snapshot committed hashes.
     expected: dict[str, str] = {}
@@ -53,7 +51,7 @@ def test_fixture_bytes_are_deterministic(tmp_path):
     builder_src = (FIXTURES / "_build.py").read_text()
     rebuilt_helper = rebuild_dir / "_build.py"
     rebuilt_helper.write_text(builder_src)
-    # Run with SOURCE_DATE_EPOCH=0 and HERE-override via a tiny shim.
+    # Run with SOURCE_DATE_EPOCH=0 and HERE override via a tiny shim.
     shim = rebuild_dir / "run.py"
     shim.write_text(
         "import sys, pathlib\n"
@@ -168,20 +166,16 @@ def test_re_may12_ioc_catches_each_literal():
     reason = "Fork 1 (RE_MAY12_IOC integration) not merged yet",
 )
 def test_may12_ioc_caught_by_scan_archive():
-    """Once RE_MAY12_IOC is wired into check_py_file (per Fork 1's
-    plan), the malicious wheel's setup.py must produce a finding
-    that explicitly references the May-12 IOC string.
+    """Once RE_MAY12_IOC is wired into check_py_file, the malicious wheel's
+    setup.py must produce a finding referencing the May-12 IOC string.
     """
     findings = sp.scan_archive(
         str(FIXTURES / "malicious_wheel.whl"),
         "malicious_fixture",
     )
-    # The IOC literals are built at runtime so CodeQL's
-    # py/incomplete-url-substring-sanitization rule does not false-
-    # positive on the (literal `in` operand) pattern -- the operand is
-    # the scanner's own evidence string, not a URL being sanitized.
-    # Runtime construction also survives pre-commit reformatting that
-    # would otherwise detach an inline lgtm comment from the operator.
+    # IOC literals built at runtime so CodeQL's url-substring-sanitization
+    # rule doesn't false-positive on the `in` operand (it's evidence, not a
+    # URL), and so reformatting can't detach an inline lgtm comment.
     _ioc_host = "git-tanstack." + "com"
     _ioc_drop = "transformers." + "pyz"
     hit = any(
@@ -202,16 +196,11 @@ def test_may12_ioc_caught_by_scan_archive():
 
 
 def test_scan_packages_pip_download_failure_propagates(tmp_path):
-    """A pip download failure must NOT be silently swallowed into a
-    `0 findings, exit 0` report. Item (4) of the silent-failure
-    hardening: an obviously unresolvable spec is fed to the scanner
-    as a subprocess; the orchestrator must exit 2 (scan incomplete)
-    and the stderr must carry the SCAN INCOMPLETE banner.
+    """A pip download failure must NOT be swallowed into `0 findings, exit 0`.
 
-    The spec name is deliberately long + random-looking so it cannot
-    accidentally resolve on any real package index. We do not rely on
-    network reachability: even an offline runner will get a clean
-    "could not resolve" failure from pip.
+    Feeds an unresolvable spec to the scanner subprocess; it must exit 2
+    (scan incomplete) with a SCAN INCOMPLETE banner on stderr. The spec name
+    is long/random so it can't resolve on any index, even offline.
     """
     script = REPO_ROOT / "scripts" / "scan_packages.py"
     assert script.is_file(), script
@@ -233,9 +222,8 @@ def test_scan_packages_pip_download_failure_propagates(tmp_path):
 
 
 def test_archive_corruption_produces_critical_finding(tmp_path):
-    """SF1: a corrupted wheel (truncated bytes) used to be silently
-    skipped by `except Exception: continue` inside iter_archive_files.
-    It must now yield a CRITICAL `archive_corrupted` finding.
+    """SF1: a corrupted wheel was silently skipped by `except: continue` in
+    iter_archive_files; it must now yield a CRITICAL `archive_corrupted`.
     """
     bad = tmp_path / "broken-0.0.1-py3-none-any.whl"
     bad.write_bytes(b"X")  # 1-byte "wheel" -- not a valid zip container
diff --git a/tests/studio/_playwright_robust.py b/tests/studio/_playwright_robust.py
index 831153bf96..bc0e3f783b 100644
--- a/tests/studio/_playwright_robust.py
+++ b/tests/studio/_playwright_robust.py
@@ -1,21 +1,17 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Shared robustness helpers for the Studio Playwright tests.
+"""Shared robustness helpers for the Studio Playwright tests, the single
+point of truth for the CI-runner workarounds (Chromium flags, view-transition
+killer, page recovery, post-action response wait) that both
+`playwright_chat_ui.py` and `playwright_extra_ui.py` need.
 
-Both `playwright_chat_ui.py` and `playwright_extra_ui.py` re-implemented
-the same set of CI-runner workarounds (Chromium launch flags, view-
-transition CSS killer, change-password retry / page-recovery, post-
-action response wait). When one diverged the other slowly rotted; the
-mac/win/linux failure modes are mostly identical so the cure is the
-same. This module is the single point of truth.
-
-Importable directly by the standalone scripts via:
+Importable directly by the standalone scripts:
 
     sys.path.insert(0, str(Path(__file__).parent))
     from _playwright_robust import (...)
 
-It does NOT depend on pytest -- both consumers run as plain Python.
+Does NOT depend on pytest -- both consumers run as plain Python.
 """
 
 from __future__ import annotations
@@ -30,28 +26,16 @@ import urllib.request
 from pathlib import Path
 from typing import Any, Callable
 
-# ─────────────────────────────────────────────────────────────────────
 # Chromium launch args.
-# ─────────────────────────────────────────────────────────────────────
 #
-# Base set works on every CI runner. The four "throttling" flags fight
-# Chromium's tendency to deprioritise CPU + timers when it thinks the
-# window is backgrounded -- which CI runners routinely flag because
-# the headless context has no real focus. Without these, gemma-3-270m
-# inference on Mac slowed to a crawl mid-test (run 25586583024 had a
-# turn budget that never released the Stop button) and the React
-# render queue stalled long enough for `wait_for_function` waits to
-# crowd their per-turn budget.
+# The throttling flags stop Chromium deprioritising CPU/timers when it thinks
+# the headless window is backgrounded (run 25586583024 stalled gemma-3-270m
+# inference and the React render queue mid-test). TranslateUI strips a popup
+# that intercepts pointer events; ipc-flooding-protection off lets rapid clicks
+# through during the slider sweep.
 #
-# `--disable-features=TranslateUI` strips the translate prompt that
-# occasionally adds a popup which intercepts pointer events.
-# `--disable-ipc-flooding-protection` lets us send rapid-fire clicks
-# during the slider sweep without Chromium queuing them.
-#
-# `--single-process` is darwin-only. On Mac it is the documented free-
-# runner fix for the pipeTransport.js JSON-RPC crash; on Win/Linux it
-# strictly destabilises the renderer-isolation safety net so any
-# crash takes the whole context down.
+# `--single-process` is darwin-only: the documented free-runner fix for the
+# pipeTransport.js JSON-RPC crash; on Win/Linux it destabilises the renderer.
 _BASE_CHROMIUM_ARGS = (
     "--disable-dev-shm-usage",
     "--no-sandbox",
@@ -65,11 +49,8 @@ _BASE_CHROMIUM_ARGS = (
 
 
 def chromium_launch_args(platform: str | None = None) -> list[str]:
-    """Return the Chromium launch arg list appropriate for `platform`.
-
-    Defaults to the running interpreter's `sys.platform`. Pass a
-    string to test the darwin branch on Linux.
-    """
+    """Return Chromium launch args for `platform` (defaults to `sys.platform`;
+    pass a string to test the darwin branch on Linux)."""
     p = sys.platform if platform is None else platform
     args = list(_BASE_CHROMIUM_ARGS)
     if p == "darwin":
@@ -77,19 +58,14 @@ def chromium_launch_args(platform: str | None = None) -> list[str]:
     return args
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Init scripts injected into every Playwright context.
-# ─────────────────────────────────────────────────────────────────────
 #
-# CSS view-transitions are otherwise rendered as a full-window
-# pseudo-element that intercepts pointer events for a beat after each
-# theme/route swap. Even with `reduced_motion = "reduce"` set on the
-# context, Studio's components run their own startViewTransition() in
-# a few places (theme toggle, sidebar collapse) and Playwright's
-# actionability check then reports `<html> intercepts pointer events`
-# on the next click. Killing the pseudo-elements + monkey-patching
-# document.startViewTransition into a synchronous shim removes both
-# failure modes. Idempotent and safe to install on every page.
+# CSS view-transitions render a full-window pseudo-element that intercepts
+# pointer events for a beat after each theme/route swap, so Playwright reports
+# `<html> intercepts pointer events` on the next click (even with
+# reduced_motion, since Studio calls startViewTransition() directly). Killing
+# the pseudo-elements + shimming startViewTransition synchronously fixes both.
+# Idempotent and safe to install on every page.
 _VIEW_TRANSITION_KILLER_JS = """
 (function () {
     try {
@@ -130,16 +106,11 @@ def install_view_transition_killer(ctx: Any) -> None:
     ctx.add_init_script(_VIEW_TRANSITION_KILLER_JS)
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Server health pre-flight.
-# ─────────────────────────────────────────────────────────────────────
 #
-# Both workflows already wait for /api/health at the bash level before
-# launching the Python script, but the macos-14 free runner has been
-# observed to surface a brief window where /api/health responds 200
-# yet /api/auth endpoints still 503 because the auth DB hasn't
-# finished migrating. A second probe inside the script catches that
-# narrow gap before we sink 60s into a change-password timeout.
+# The bash wait already gates on /api/health, but on the macos-14 free runner
+# /api/health can return 200 while /api/auth still 503s (auth DB mid-migration).
+# A second in-script probe catches that gap before a 60s change-password timeout.
 
 
 def _http_get_status_and_body(url: str, timeout: float) -> tuple[int, dict | None]:
@@ -162,13 +133,9 @@ def wait_for_health(
     timeout: float = 30.0,
     info: Callable[[str], None] | None = None,
 ) -> bool:
-    """Poll {base_url}/api/health until status==200 with healthy body.
-
-    Returns True on success, False on timeout. Never raises -- the
-    caller decides whether to fail. The test scripts use the boolean
-    only for diagnostic logging, since the workflow's own /api/health
-    wait is the authoritative gate.
-    """
+    """Poll {base_url}/api/health until status==200. Returns True on success,
+    False on timeout; never raises. Diagnostic only -- the workflow's own
+    /api/health wait is the authoritative gate."""
     deadline = time.monotonic() + timeout
     last_status: int | None = None
     last_body: dict | None = None
@@ -193,14 +160,11 @@ def wait_for_health(
     return False
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Page recovery.
-# ─────────────────────────────────────────────────────────────────────
 #
-# The single canonical "did the page die mid-test" recovery path. Used
-# by every retry block in both scripts. If the page is closed, opens a
-# fresh one in the same context (auth state in localStorage survives);
-# otherwise leaves the page alone. Optionally re-navigates.
+# Canonical "did the page die mid-test" path used by every retry block. If the
+# page is closed, opens a fresh one in the same context (localStorage auth
+# survives); otherwise leaves it alone. Optionally re-navigates.
 
 
 def recover_or_replace_page(
@@ -212,13 +176,9 @@ def recover_or_replace_page(
     settle_networkidle: bool = True,
     info: Callable[[str], None] | None = None,
 ) -> Any:
-    """Return a usable page. Replaces `page` if it is closed.
-
-    If `goto_url` is provided, navigates the (possibly new) page there
-    and best-effort waits for networkidle. Errors during recovery are
-    logged through `info` (if provided) and swallowed -- the caller
-    handles a still-broken page on the next retry iteration.
-    """
+    """Return a usable page, replacing `page` if it is closed. If `goto_url` is
+    given, navigates there and best-effort waits for networkidle. Recovery
+    errors are logged and swallowed; the caller retries a still-broken page."""
     try:
         if page.is_closed():
             page = ctx.new_page()
@@ -254,15 +214,10 @@ def click_and_wait_for_response(
     timeout_ms: int = 30_000,
     info: Callable[[str], None] | None = None,
 ) -> tuple[int | None, Exception | None]:
-    """Click + wait for the matching XHR/fetch response in one step.
-
-    Returns (status, err). On success: (status, None). On failure to
-    capture the response: (None, exception). Callers typically check
-    `status >= 400` to surface a server-side rejection immediately
-    rather than discovering it 60s later via a downstream wait_for.
-    Falls back to a fire-and-forget click on any wait error so the
-    outer retry loop still runs.
-    """
+    """Click + wait for the matching XHR/fetch response. Returns (status, None)
+    on success or (None, exception) on capture failure. Callers check
+    `status >= 400` to surface server rejections immediately. Falls back to a
+    fire-and-forget click on any wait error so the outer retry loop runs."""
     try:
         with page.expect_response(
             lambda r: url_substr in r.url and r.request.method == method,
@@ -284,19 +239,13 @@ def click_and_wait_for_response(
         return None, exc
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Console-error / page-error filtering.
-# ─────────────────────────────────────────────────────────────────────
 #
-# Two categories:
-#   - BENIGN_PAGE_ERROR_PATTERNS: thrown JS errors that fire as a side
-#     effect of slow CI infra (server timeouts, request races) and have
-#     no user-visible consequence. The page-error gate at the end of
-#     each test should NOT count these.
-#   - BENIGN_CONSOLE_ERROR_PATTERNS: console.error events that fire
-#     for the same reason. Tests don't gate on console.error today
-#     (they only count for diagnostics), but the same list is useful
-#     for filtering noise out of the diagnostic dumps.
+#   - BENIGN_PAGE_ERROR_PATTERNS: JS errors from slow CI infra (timeouts,
+#     request races) with no user-visible effect; the page-error gate must not
+#     count these.
+#   - BENIGN_CONSOLE_ERROR_PATTERNS: same-cause console.error events, used only
+#     to filter noise from diagnostic dumps (tests don't gate on console.error).
 
 BENIGN_PAGE_ERROR_PATTERNS: tuple[str, ...] = (
     "Request failed (422)",
@@ -308,21 +257,15 @@ BENIGN_PAGE_ERROR_PATTERNS: tuple[str, ...] = (
 )
 
 BENIGN_CONSOLE_ERROR_PATTERNS: tuple[str, ...] = (
-    # macos-14 free runner buffer-exhaustion under --single-process
-    # Chromium. The browser surfaces this on resource fetches but the
-    # test catches the underlying request failure via expect_response
-    # and retries; the console line itself is informational.
+    # macos-14 buffer-exhaustion under --single-process; the test catches the
+    # underlying request failure via expect_response and retries.
     "net::ERR_NO_BUFFER_SPACE",
-    # Chromium emits a console.error every time a fetch is aborted,
-    # even when the abort is intentional (component unmount, route
-    # change). All four scripts trigger several of these per run.
+    # Intentional fetch aborts (unmount, route change) log a console.error.
     "AbortError",
     "The user aborted a request",
-    # Same shape: lazy-loaded chunk that's no longer needed because
-    # the user navigated away mid-load.
+    # Lazy chunk no longer needed because the user navigated away mid-load.
     "Loading chunk",
-    # Filtered as a benign page-error too; included here for the
-    # parallel diagnostic dump path.
+    # Also a benign page-error; here for the diagnostic dump path.
     "Failed to fetch",
 )
 
@@ -348,14 +291,9 @@ def dump_diagnostics(
     info: Callable[[str], None] | None = None,
     extra: dict | None = None,
 ) -> None:
-    """Write a screenshot + URL/title + body excerpt + storage dump.
-
-    Diagnostic only. Never raises. The screenshot path lives in
-    `art_dir/{name}.png`; the JSON sidecar lives in `art_dir/{name}.json`.
-    The screenshot is wrapped in try/except because Page.screenshot
-    waits for webfonts to load and can crowd CI font load on macos-14
-    even at 90s. The JSON sidecar is best-effort too.
-    """
+    """Write a screenshot (`art_dir/{name}.png`) + a JSON sidecar
+    (`art_dir/{name}.json`) with URL/title/body/storage. Diagnostic only, never
+    raises; both are best-effort (screenshot can crowd CI font load on macos-14)."""
     art = Path(art_dir)
     try:
         art.mkdir(parents = True, exist_ok = True)
@@ -404,26 +342,13 @@ def dump_diagnostics(
             info(f"diagnostics: json sidecar {name} failed: {exc}")
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Bounded in-page fetch.
-# ─────────────────────────────────────────────────────────────────────
 #
-# Playwright's `page.evaluate(...)` has no `timeout=` argument. If the
-# JS body awaits a fetch that never resolves (the renderer's network
-# thread wedges, the server accepts the connection but never replies,
-# the macos-14 free runner under --single-process Chromium loses its
-# IPC pipe), the entire Python script hangs until the runner-level
-# timeout fires. Run 25696797934 / job 75446949358 on PR #5387 showed
-# this exact failure: studio.log went idle after the chat surface
-# mounted, no further requests reached the server, and Playwright
-# burned 27+ minutes on a single page.evaluate(fetch /api/inference/
-# load) before the 30-min runner cancel.
-#
-# `evaluate_fetch` wraps the fetch in an AbortController.signal so the
-# JS side resolves either with a real response or with a synthetic
-# `{status: 0, error: "AbortError..."}` after `timeout_ms` ms. Either
-# way page.evaluate returns and the script proceeds (or fails) with
-# a debuggable signal instead of a silent wedge.
+# `page.evaluate(...)` has no `timeout=`, so a fetch that never resolves hangs
+# the whole script until the runner timeout (run 25696797934 / PR #5387 burned
+# 27+ min on one page.evaluate). `evaluate_fetch` wraps the fetch in an
+# AbortController.signal so the JS side always resolves -- with a real response
+# or a synthetic `{status: 0, error: "AbortError..."}` after `timeout_ms`.
 def evaluate_fetch(
     page: Any,
     url: str,
@@ -435,18 +360,11 @@ def evaluate_fetch(
     transport_retries: int = 2,
     transport_backoff_ms: int = 250,
 ) -> dict[str, Any]:
-    """Run `fetch(url, opts)` inside the page with an AbortSignal deadline.
-
-    Returns `{"status": int, "body": parsed_or_text, "error": str|None}`.
-    On AbortSignal timeout returns `{"status": 0, "body": None, "error":
-    "AbortError: ..."}`. Callers should treat `status == 0` (or any
-    non-None `error`) as a transport failure rather than an HTTP
-    response.
-
-    `body` may be a `str` (sent verbatim) or a `dict`/`list` (JSON-
-    encoded here). Pass headers explicitly when you need
-    `Content-Type: application/json` or an `Authorization` bearer.
-    """
+    """Run `fetch(url, opts)` in the page with an AbortSignal deadline. Returns
+    `{"status", "body", "error"}`; on timeout `status==0` with an AbortError
+    string. Treat `status == 0` or a non-None `error` as transport failure, not
+    an HTTP response. `body` may be a str (verbatim) or dict/list (JSON-encoded
+    here); pass headers explicitly for Content-Type / Authorization."""
     body_arg: str | None
     if body is None:
         body_arg = None
@@ -487,13 +405,11 @@ def evaluate_fetch(
         "body": body_arg,
         "timeoutMs": int(timeout_ms),
     }
-    # Bounded retry on transport failures only.
-    #   status != 0  -> real HTTP response (incl. 4xx/5xx); propagate.
-    #   AbortError   -> caller's deadline; propagate.
-    #   else (==0)   -> stale-keepalive / "TypeError: Failed to fetch"
-    #                   on macos-14 right after auth rotations close
-    #                   existing sessions. Retry after backoff so the
-    #                   browser pool evicts the dead socket.
+    # Bounded retry on transport failures only:
+    #   status != 0 -> real HTTP response (incl. 4xx/5xx); propagate.
+    #   AbortError  -> caller's deadline; propagate.
+    #   else (==0)  -> stale-keepalive / "Failed to fetch" after auth rotation;
+    #                  retry after backoff so the pool evicts the dead socket.
     last: dict[str, Any] | None = None
     attempts = max(1, int(transport_retries) + 1)
     for attempt in range(attempts):
@@ -523,36 +439,23 @@ def evaluate_fetch(
     return last or {"status": 0, "body": None, "error": "no attempt made"}
 
 
-# ─────────────────────────────────────────────────────────────────────
 # Wall-clock watchdog.
-# ─────────────────────────────────────────────────────────────────────
 #
-# Even with every action and fetch bounded, a sufficiently strange
-# wedge inside the browser (a CPU-pinned JS infinite loop, a renderer
-# crash that doesn't propagate to Playwright, an asyncio deadlock in
-# the sync wrapper) can still hang the script. The watchdog is a
-# daemon Timer that calls `os._exit(2)` after `deadline_s` seconds,
-# printing the wedge location to stderr so the CI log shows where the
-# script was at force-kill time. The exit code matches "test failure
-# by deadline" so the workflow's `set -e` propagates correctly.
-#
-# Pick `deadline_s` generously enough to cover the slowest healthy
-# run -- macos-14 free runners with cold caches measure ~7-9 min for
-# the comprehensive chat UI test. 12 minutes (720 s) leaves headroom
-# without amplifying every real wedge to the 30-min runner-level cap.
+# Even with every action/fetch bounded, a strange browser wedge (CPU-pinned JS
+# loop, renderer crash that doesn't propagate, asyncio deadlock) can hang the
+# script. A daemon Timer calls `os._exit(2)` after `deadline_s`, printing the
+# wedge location to stderr; exit code 2 lets the workflow's `set -e` propagate.
+# Pick `deadline_s` above the slowest healthy run (macos-14 cold cache ~7-9 min;
+# 720s leaves headroom without nearing the 30-min runner cap).
 def install_wall_clock_watchdog(
     deadline_s: float,
     *,
     label: str = "playwright",
     info: Callable[[str], None] | None = None,
 ) -> threading.Timer:
-    """Start a daemon Timer that hard-exits the process at `deadline_s`.
-
-    Returns the Timer so the caller can `.cancel()` it on clean exit.
-    The Timer is daemonised; if the script exits normally before the
-    deadline the Timer dies with the process even without an explicit
-    cancel.
-    """
+    """Start a daemon Timer that hard-exits the process at `deadline_s`. Returns
+    it so the caller can `.cancel()` on clean exit; being daemonised, it also
+    dies with the process if the script exits first."""
 
     def _kaboom() -> None:
         msg = (
diff --git a/tests/studio/install/smoke_test_parallel_studio_home.py b/tests/studio/install/smoke_test_parallel_studio_home.py
index c4fc250655..be01147740 100644
--- a/tests/studio/install/smoke_test_parallel_studio_home.py
+++ b/tests/studio/install/smoke_test_parallel_studio_home.py
@@ -1,50 +1,29 @@
 #!/usr/bin/env python3
 """Smoke test: N parallel install.sh runs with distinct UNSLOTH_STUDIO_HOME
-values must produce N fully isolated installs whose backends can run
-side by side without clashing.
+values must produce N fully isolated installs whose backends run side by side.
 
-Covers the env-override path added in #5190:
+Covers the env-override path from #5190:
 
     install-time
-        * N concurrent ``install.sh --local --no-torch`` runs against
-          this checkout, each pinned to its own UNSLOTH_STUDIO_HOME and
-          a redirected HOME, all exit 0.
-        * Each STUDIO_HOME contains its own bin/, share/, llama.cpp/
-          and unsloth_studio/ venv, with no cross-install absolute
-          paths.
-        * share/studio_install_id is unique across the N installs.
-        * share/studio.conf exports UNSLOTH_EXE, UNSLOTH_STUDIO_HOME
-          and UNSLOTH_LLAMA_CPP_PATH, all pointing inside this install.
-        * share/launch-studio.sh has @@DATA_DIR@@ substituted to its
-          own share/ at install time.
-        * bin/unsloth is a symlink that resolves into its own venv.
-        * The redirected HOME is left clean: no shell-rc append, no
-          .desktop file, no Studio.app stub, no shared marker.
+        * N concurrent ``install.sh --local --no-torch`` runs, each pinned to
+          its own UNSLOTH_STUDIO_HOME + redirected HOME, all exit 0.
+        * Each STUDIO_HOME has its own bin/share/llama.cpp/unsloth_studio venv,
+          a unique share/studio_install_id, and a studio.conf / launch-studio.sh
+          pointing only inside this install. bin/unsloth resolves into its venv.
+        * The redirected HOME is left clean (no rc append, .desktop, app stub).
 
     runtime
-        * N concurrent ``bin/unsloth studio`` launches each bind their
-          own dynamically allocated free port and stay healthy.
-        * /api/health is 200, status is healthy, chat_only is true
-          under --no-torch.
-        * The studio_root_id reported by /api/health on each backend
-          equals that install's share/studio_install_id, so the
-          runtime resolver agrees with the install-time write.
-        * studio_root_id values are pairwise distinct.
-        * GET / and GET /api/chat are 200 on every backend.
-        * The Python interpreter behind each PID is the install's own
-          venv python (the bin/unsloth shim does not cross-resolve).
+        * N ``bin/unsloth studio`` launches each bind a free port and report
+          /api/health 200, healthy, chat_only true under --no-torch.
+        * studio_root_id equals the install's studio_install_id and is pairwise
+          distinct; GET / and /api/chat are 200; each PID's python is its venv.
 
-This is an integration smoke runner, not a pytest unit test. It does
-real installs (~1 minute end to end on a warm uv cache) and is meant
-to be invoked explicitly:
+Integration smoke runner (not pytest); ~1 minute on a warm uv cache. Invoke:
 
-    python tests/studio/install/smoke_test_parallel_studio_home.py
-    python tests/studio/install/smoke_test_parallel_studio_home.py --n 6 --keep
+    python tests/studio/install/smoke_test_parallel_studio_home.py [--n 6 --keep]
 
-Exits 0 on PASS, 1 on FAIL, 2 on infrastructure error. Artifacts land
-under a temporary directory and are removed on PASS unless --keep is
-set; on FAIL or ERROR they are kept regardless so logs can be
-inspected.
+Exits 0 PASS / 1 FAIL / 2 error. Artifacts removed on PASS unless --keep;
+kept on FAIL/ERROR for inspection.
 """
 
 from __future__ import annotations
diff --git a/tests/studio/install/test_llama_pr_force_and_source.py b/tests/studio/install/test_llama_pr_force_and_source.py
index 17c58cba51..8e2a56ae39 100644
--- a/tests/studio/install/test_llama_pr_force_and_source.py
+++ b/tests/studio/install/test_llama_pr_force_and_source.py
@@ -40,9 +40,8 @@ def run_bash(
     timeout: int = 60,
     env: dict | None = None,
 ) -> subprocess.CompletedProcess:
-    """Run a bash script fragment and return the CompletedProcess.
-    60s default tolerates slow shell startup on heavily-loaded CI
-    runners; the scripts themselves run in well under a second."""
+    """Run a bash script fragment. 60s default tolerates slow CI shell
+    startup; the scripts themselves run in well under a second."""
     run_env = os.environ.copy()
     if env:
         run_env.update(env)
@@ -61,10 +60,8 @@ def run_pwsh(
     timeout: int = 60,
     env: dict | None = None,
 ) -> subprocess.CompletedProcess:
-    """Run a PowerShell script fragment and return the CompletedProcess.
-    60s default tolerates slow pwsh startup on heavily-loaded CI
-    runners; the scripts themselves run in well under a second.
-    A 10s budget previously surfaced as a flaky TimeoutExpired."""
+    """Run a PowerShell script fragment. 60s default tolerates slow CI pwsh
+    startup (a 10s budget was flaky); the scripts run in under a second."""
     run_env = os.environ.copy()
     run_env["NO_COLOR"] = "1"
     if env:
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index bcfc42c69f..e0309dbd35 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -232,9 +232,7 @@ UPSTREAM_ASSETS = {
 }
 
 
-# =============================================================================
 # TEST: install_llama_prebuilt.py -- resolve_upstream_asset_choice
-# =============================================================================
 
 
 class TestResolveUpstreamAssetChoice:
@@ -332,9 +330,7 @@ class TestResolveUpstreamAssetChoice:
             resolve_upstream_asset_choice(host, LLAMA_TAG)
 
 
-# =============================================================================
 # TEST: install_llama_prebuilt.py -- runtime_patterns_for_choice
-# =============================================================================
 
 
 class TestRuntimePatterns:
@@ -398,9 +394,7 @@ class TestRuntimePatterns:
         assert "lib*.dylib" in patterns
 
 
-# =============================================================================
 # TEST: install_llama_prebuilt.py -- HostInfo.has_rocm field
-# =============================================================================
 
 
 class TestHostInfoRocm:
@@ -449,9 +443,7 @@ class TestHostInfoRocm:
         assert "hipinfo" in source or "amd-smi" in source
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _detect_rocm_version
-# =============================================================================
 
 
 class TestDetectRocmVersion:
@@ -548,9 +540,7 @@ class TestDetectRocmVersion:
                     assert result is None
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _ensure_rocm_torch
-# =============================================================================
 
 
 class TestEnsureRocmTorch:
@@ -707,9 +697,7 @@ class TestEnsureRocmTorch:
         mock_pip.assert_not_called()
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _ROCM_TORCH_INDEX mapping
-# =============================================================================
 
 
 class TestRocmTorchIndex:
@@ -766,9 +754,7 @@ class TestRocmTorchIndex:
         assert tag == "rocm6.4"
 
 
-# =============================================================================
 # TEST: hardware.py -- IS_ROCM flag and detect_hardware
-# =============================================================================
 
 
 class TestHardwareRocmFlag:
@@ -850,9 +836,7 @@ class TestHardwareRocmFlag:
             assert attr in source, f"distributed stub for '{attr}' missing from hardware.py"
 
 
-# =============================================================================
 # TEST: tokenizer_utils.py -- error message
-# =============================================================================
 
 
 class TestTokenizerErrorMessage:
@@ -871,9 +855,7 @@ class TestTokenizerErrorMessage:
         assert "docs.unsloth.ai" in source or "No GPU detected" in source
 
 
-# =============================================================================
 # TEST: install.sh -- structural checks
-# =============================================================================
 
 
 class TestInstallShStructure:
@@ -1003,9 +985,7 @@ class TestInstallShStructure:
         assert darwin_pos < rocm_pos, "macOS check should come before ROCm detection"
 
 
-# =============================================================================
 # TEST: Live regression on current host (NVIDIA B200 expected)
-# =============================================================================
 
 
 class TestLiveRegression:
@@ -1051,9 +1031,7 @@ class TestLiveRegression:
         assert "cu1" in url or "cuda" in url.lower(), f"Expected CUDA URL, got: {url}"
 
 
-# =============================================================================
 # TEST: worker.py -- ROCm Mamba/SSM source build path
-# =============================================================================
 
 # Load worker.py module
 _WORKER_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "training" / "worker.py"
@@ -1140,9 +1118,7 @@ class TestWorkerRocmMambaSsm:
         assert "timeout" in source
 
 
-# =============================================================================
 # TEST: amd.py -- AMD GPU monitoring
-# =============================================================================
 
 
 class TestAmdGpuMonitoring:
@@ -1217,9 +1193,8 @@ class TestAmdGpuMonitoring:
             pytest.skip("Could not load amd module")
 
         # _first_visible_amd_gpu_id() short-circuits to None when any of
-        # HIP / ROCR / CUDA_VISIBLE_DEVICES is set to "" or "-1". CI runners
-        # often unset CUDA at the env level by setting CUDA_VISIBLE_DEVICES
-        # to "" so the test must not inherit that.
+        # HIP / ROCR / CUDA_VISIBLE_DEVICES is "" or "-1". CI often sets
+        # CUDA_VISIBLE_DEVICES="", so the test must not inherit that.
         for var in (
             "HIP_VISIBLE_DEVICES",
             "ROCR_VISIBLE_DEVICES",
@@ -1292,9 +1267,7 @@ class TestAmdGpuMonitoring:
         assert result["available"] is False
 
 
-# =============================================================================
 # TEST: hardware.py -- IS_ROCM branching to amd.py
-# =============================================================================
 
 
 class TestHardwareAmdBranching:
@@ -1349,9 +1322,7 @@ class TestHardwareAmdBranching:
         assert "from . import amd" in func_body
 
 
-# =============================================================================
 # TEST: hardware.py -- apply_gpu_ids ROCm fallback (issue #5180)
-# =============================================================================
 
 
 class TestApplyGpuIdsRocmFallback:
@@ -1385,9 +1356,7 @@ class TestApplyGpuIdsRocmFallback:
         assert "except Exception" in func_body
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- Windows AMD warning
-# =============================================================================
 
 
 class TestWindowsRocmWarning:
@@ -1410,9 +1379,7 @@ class TestWindowsRocmWarning:
         assert "docs.unsloth.ai/get-started/install-and-update/amd" in source
 
 
-# =============================================================================
 # TEST: unsloth/kernels/utils.py -- is_rdna() expansion
-# =============================================================================
 
 
 class TestIsRdnaExpansion:
@@ -1477,9 +1444,7 @@ class TestIsRdnaExpansion:
         assert "gfx1100" not in func_body
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _windows_rocm_index_url arch mapping
-# =============================================================================
 
 
 class TestWindowsRocmIndexUrl:
@@ -1536,9 +1501,7 @@ class TestWindowsRocmIndexUrl:
         assert url is not None
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _detect_windows_gfx_arch
-# =============================================================================
 
 
 class TestDetectWindowsGfxArch:
@@ -1595,9 +1558,7 @@ class TestDetectWindowsGfxArch:
         assert result == "gfx1201"
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _install_bnb_windows_rocm
-# =============================================================================
 
 
 class TestInstallBnbWindowsRocm:
@@ -1742,9 +1703,7 @@ class TestDetectBnbRocmDllVer:
             assert stack_mod._detect_bnb_rocm_dll_ver() == "713"
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- UNSLOTH_ROCM_TORCH_INSTALLED early-return path
-# =============================================================================
 
 
 class TestRocmTorchInstalledEnvVar:
@@ -1813,9 +1772,7 @@ class TestRocmTorchInstalledEnvVar:
         mock_bnb.assert_not_called()
 
 
-# =============================================================================
 # TEST: worker.py -- Windows ROCm patches (source-level checks)
-# =============================================================================
 
 
 class TestWorkerWindowsRocmPatches:
@@ -1951,9 +1908,7 @@ class TestWorkerWindowsRocmPatches:
         assert 'split(".")[:2]' in source or ".split('.')[:2]" in source
 
 
-# =============================================================================
 # TEST: install_python_stack.py -- _ROCM_TORCH_PKG_SPECS mapping
-# =============================================================================
 
 
 class TestRocmTorchPkgSpecs:
@@ -2000,9 +1955,7 @@ class TestRocmTorchPkgSpecs:
             assert mapping.get(arch) == "gfx110X-all", f"{arch} missing from mapping"
 
 
-# =============================================================================
 # TEST: setup.ps1 / install.ps1 -- Strix Halo gfx arch detection
-# =============================================================================
 
 _SETUP_PS1_PATH = PACKAGE_ROOT / "studio" / "setup.ps1"
 _INSTALL_PS1_PATH = PACKAGE_ROOT / "install.ps1"
@@ -2084,9 +2037,7 @@ class TestStrixHaloGfxArchDetection:
             ), f"gfx arch regex not found in {path.name}"
 
 
-# =============================================================================
 # TEST: HIP SDK tool path resolution via HIP_PATH / ROCM_PATH env vars
-# =============================================================================
 
 
 class TestHipSdkEnvPathResolution:
@@ -2203,9 +2154,7 @@ class TestHipSdkEnvPathResolution:
         assert "PATH" in source and ("SetEnvironmentVariable" in source or "Add" in source)
 
 
-# =============================================================================
 # TEST: HIP SDK detected substep -- path + hipconfig version shown in terminal
-# =============================================================================
 
 
 class TestHipSdkDetectedSubstep:
@@ -2258,9 +2207,7 @@ class TestHipSdkDetectedSubstep:
         assert "ROCmVersionFull" in source and "rocm" in source
 
 
-# =============================================================================
 # TEST: install.sh -- Strix Halo rocm7.1 → rocm7.2 override
-# =============================================================================
 
 _INSTALL_SH_PATH = PACKAGE_ROOT / "install.sh"
 _SETUP_SH_PATH = PACKAGE_ROOT / "studio" / "setup.sh"
@@ -2324,9 +2271,7 @@ class TestStrixRocm71Override:
         assert "rocm/whl/gfx" in source
 
 
-# =============================================================================
 # TEST: setup.sh -- gcc-install-dir fix for Ubuntu 24.04 + ROCm 7.x clang-20
-# =============================================================================
 
 
 class TestSetupShGccInstallDir:
@@ -2365,9 +2310,7 @@ class TestSetupShGccInstallDir:
         assert "gcc install dir" in source or "GCC_INSTALL_DIR" in source
 
 
-# =============================================================================
 # TEST: main.py -- BNB_ROCM_VERSION server startup + distributed stubs
-# =============================================================================
 
 _MAIN_PY_PATH = PACKAGE_ROOT / "studio" / "backend" / "main.py"
 _HARDWARE_PY_PATH = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
@@ -2455,9 +2398,7 @@ class TestServerStartupRocmFixes:
         assert "_distributed_rpc" in source
 
 
-# =============================================================================
 # TEST: install.ps1 / setup.ps1 -- HipSdkInstalled flag (SDK found, device inaccessible)
-# =============================================================================
 
 
 class TestHipSdkInstalledButDeviceInaccessible:
@@ -2527,11 +2468,9 @@ class TestHipSdkInstalledButDeviceInaccessible:
         assert "GPU not ROCm-accessible" in source
 
 
-# =============================================================================
 # TEST: --rocm-gfx forwarding -- setup.sh/setup.ps1 hand their resolved gfx arch
 # to install_llama_prebuilt.py so the lemonade HIP prebuilt is selected even when
 # the installer's own hipinfo/amd-smi probe cannot report it.
-# =============================================================================
 
 _SETUP_SH_PATH = PACKAGE_ROOT / "studio" / "setup.sh"
 
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 1ada35888c..27cf30496f 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -111,9 +111,7 @@ def load_studio_run_module(monkeypatch):
     return module
 
 
-# ---------------------------------------------------------------------------
 # Helper factories
-# ---------------------------------------------------------------------------
 
 
 def make_host(**overrides):
@@ -271,9 +269,7 @@ def mock_windows_runtime(monkeypatch, lines):
     )
 
 
-# ===========================================================================
 # Studio run.py localhost warning
-# ===========================================================================
 
 
 class TestStudioLocalhostIpv6Warning:
@@ -454,9 +450,7 @@ class TestStudioLocalhostIpv6Warning:
         assert calls["stop_hint"] == 1
 
 
-# ===========================================================================
 # A. normalize_compute_cap
-# ===========================================================================
 
 
 class TestNormalizeComputeCap:
@@ -488,9 +482,7 @@ class TestNormalizeComputeCap:
         assert normalize_compute_cap("9.0") == "90"
 
 
-# ===========================================================================
 # B. normalize_compute_caps
-# ===========================================================================
 
 
 class TestNormalizeComputeCaps:
@@ -507,9 +499,7 @@ class TestNormalizeComputeCaps:
         assert normalize_compute_caps([]) == []
 
 
-# ===========================================================================
 # C. parse_cuda_visible_devices
-# ===========================================================================
 
 
 class TestParseCudaVisibleDevices:
@@ -532,9 +522,7 @@ class TestParseCudaVisibleDevices:
         assert parse_cuda_visible_devices(" 0 , 1 ") == ["0", "1"]
 
 
-# ===========================================================================
 # D. supports_explicit_visible_device_matching
-# ===========================================================================
 
 
 class TestSupportsExplicitVisibleDeviceMatching:
@@ -554,9 +542,7 @@ class TestSupportsExplicitVisibleDeviceMatching:
         assert supports_explicit_visible_device_matching(["0", "MIG-device"]) is False
 
 
-# ===========================================================================
 # E. select_visible_gpu_rows
-# ===========================================================================
 
 
 class TestSelectVisibleGpuRows:
@@ -589,9 +575,7 @@ class TestSelectVisibleGpuRows:
         assert result == []
 
 
-# ===========================================================================
 # F. compatible_linux_runtime_lines
-# ===========================================================================
 
 
 class TestCompatibleLinuxRuntimeLines:
@@ -648,9 +632,7 @@ class TestParseDirectLinuxReleaseBundle:
         assert art.max_sm == 120  # inherited from cuda13-newer
 
 
-# ===========================================================================
 # G. pick_windows_cuda_runtime + compatible_windows_runtime_lines
-# ===========================================================================
 
 
 class TestPickWindowsCudaRuntime:
@@ -697,9 +679,7 @@ class TestCompatibleWindowsRuntimeLines:
         assert compatible_windows_runtime_lines(host) == ["cuda14", "cuda13", "cuda12"]
 
 
-# ===========================================================================
 # H. runtime_line_from_cuda_version
-# ===========================================================================
 
 
 class TestRuntimeLineFromCudaVersion:
@@ -719,9 +699,7 @@ class TestRuntimeLineFromCudaVersion:
         assert runtime_line_from_cuda_version("") is None
 
 
-# ===========================================================================
 # I. apply_approved_hashes
-# ===========================================================================
 
 
 class TestApplyApprovedHashes:
@@ -835,9 +813,7 @@ class TestApplyApprovedHashes:
             apply_approved_hashes([], checksums)
 
 
-# ===========================================================================
 # J. published release resolution
-# ===========================================================================
 
 
 class TestPublishedReleaseResolution:
@@ -1171,9 +1147,7 @@ class TestValidatedChecksumsForBundle:
             validated_checksums_for_bundle("unslothai/llama.cpp", bundle)
 
 
-# ===========================================================================
 # K. linux_cuda_choice_from_release -- core selection
-# ===========================================================================
 
 
 class TestLinuxCudaChoiceFromRelease:
@@ -1500,9 +1474,7 @@ class TestBlackwellUltraSm103Coverage:
         assert result is None
 
 
-# ===========================================================================
 # L. resolve_install_attempts
-# ===========================================================================
 
 
 class TestResolveInstallAttempts:
@@ -2023,9 +1995,7 @@ class TestResolveInstallReleasePlans:
             sys.modules.pop(spec.name, None)
 
 
-# ===========================================================================
 # N. windows_cuda_attempts
-# ===========================================================================
 
 
 class TestWindowsCudaAttempts:
@@ -2243,9 +2213,7 @@ class TestWindowsCudaAttempts:
         assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
 
 
-# ===========================================================================
 # N.1b. _pinned_windows_cuda_fallback -- pinned b9360 cuda-13.1 Blackwell fallback
-# ===========================================================================
 
 
 class TestPinnedBlackwellCudaFallback:
@@ -2387,9 +2355,7 @@ class TestPinnedBlackwellCudaFallback:
         assert _windows_cuda_attempt_covers_blackwell(cpu) is False
 
 
-# ===========================================================================
 # N.1c. direct_upstream_release_plan -- pinned Blackwell fallback ordering
-# ===========================================================================
 
 
 class TestDirectUpstreamBlackwellPin:
@@ -2453,9 +2419,7 @@ class TestDirectUpstreamBlackwellPin:
         assert plan.attempts[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
 
 
-# ===========================================================================
 # N.1d. published_windows_cuda_attempts -- version-dynamic ordering seed
-# ===========================================================================
 
 
 class TestPublishedWindowsCudaAttemptsDynamicMajor:
@@ -2521,9 +2485,7 @@ class TestPublishedWindowsCudaAttemptsDynamicMajor:
         assert result[0].runtime_line == "cuda12"
 
 
-# ===========================================================================
 # N.1e. resolve_release_asset_choice -- pin on the published install path
-# ===========================================================================
 
 
 class TestResolveReleaseAssetChoicePin:
@@ -2616,9 +2578,7 @@ class TestResolveReleaseAssetChoicePin:
         assert "b9360" not in [a.tag for a in result]
 
 
-# ===========================================================================
 # N.1. apply_approved_hashes -- runtime archive checksum threading
-# ===========================================================================
 
 
 class TestApplyApprovedHashesRuntimePair:
@@ -2690,9 +2650,7 @@ class TestApplyApprovedHashesRuntimePair:
         assert result[0].runtime_sha256 is None
 
 
-# ===========================================================================
 # O. resolve_upstream_asset_choice -- platform routing
-# ===========================================================================
 
 
 class TestResolveUpstreamAssetChoice:
@@ -2835,9 +2793,7 @@ class TestResolveUpstreamAssetChoice:
         assert result.name == cuda_name
 
 
-# ===========================================================================
 # N.2. Deterministic macOS prebuilt pin (b9415)
-# ===========================================================================
 
 
 def _macos_host(machine = "arm64", version = (15, 5)):
@@ -2960,9 +2916,7 @@ class TestResolveSimpleMacosPin:
         assert calls[0][2] == "latest"
 
 
-# ===========================================================================
 # Linux arm64 + GPU must not install the x64-only fork bundle
-# ===========================================================================
 
 
 class TestLinuxArm64ForkFallsBackToSource:
@@ -3016,9 +2970,7 @@ class TestLinuxArm64ForkFallsBackToSource:
         assert "linux-x64 prebuilts" not in str(exc.value)
 
 
-# ===========================================================================
 # arm64 Linux GPU: CPU prebuilt fallback after a failed source build (--cpu-fallback)
-# ===========================================================================
 
 
 class TestCpuFallback:
diff --git a/tests/studio/load_freeze/llama_server_shim.py b/tests/studio/load_freeze/llama_server_shim.py
index bb9e119820..4030fcd6c4 100644
--- a/tests/studio/load_freeze/llama_server_shim.py
+++ b/tests/studio/load_freeze/llama_server_shim.py
@@ -224,8 +224,8 @@ class FakeLlamaServer:
         self._thread: Optional[threading.Thread] = None
 
     def start(self) -> "FakeLlamaServer":
-        # port=0 lets ThreadingHTTPServer pick a free port atomically
-        # (avoids find-port-then-bind race); read back via server_address[1].
+        # port=0 lets ThreadingHTTPServer pick a free port atomically (no
+        # find-then-bind race); read back via server_address[1].
         self._server = FakeLlamaServer._Server((self.host, self._requested_port), _Handler)
         self._server.config = self.config
         bound_port = self._server.server_address[1]
diff --git a/tests/studio/load_freeze/test_load_orchestrator.py b/tests/studio/load_freeze/test_load_orchestrator.py
index b76c4c361b..d091e56e70 100644
--- a/tests/studio/load_freeze/test_load_orchestrator.py
+++ b/tests/studio/load_freeze/test_load_orchestrator.py
@@ -33,9 +33,7 @@ from pathlib import Path
 import pytest
 
 
-# ---------------------------------------------------------------------------
 # Repo discovery
-# ---------------------------------------------------------------------------
 
 
 def _find_repo_root() -> Path | None:
@@ -79,9 +77,7 @@ from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
 from llama_server_shim import FakeLlamaServer  # noqa: E402
 
 
-# ---------------------------------------------------------------------------
 # Fixtures / helpers
-# ---------------------------------------------------------------------------
 
 
 def _make_backend(port: int, *, loaded: bool = True) -> LlamaCppBackend:
@@ -208,9 +204,7 @@ def _drive_concurrent_probe_and_health(
     return max(latencies), elapsed, latencies
 
 
-# ---------------------------------------------------------------------------
 # (1) Behavioural canary
-# ---------------------------------------------------------------------------
 
 
 def test_buggy_route_blocks_event_loop():
@@ -239,9 +233,7 @@ def test_fixed_route_keeps_event_loop_responsive():
     assert max_lat < 0.25, f"expected <0.25s; got {max_lat:.3f}s (all: {lats})"
 
 
-# ---------------------------------------------------------------------------
 # (2) Functional equivalence -- sync == to_thread for each codec branch
-# ---------------------------------------------------------------------------
 
 
 @pytest.fixture
@@ -366,9 +358,7 @@ def test_functional_equivalence_bicodec_match():
     assert sync_result == threaded
 
 
-# ---------------------------------------------------------------------------
 # (3) Failure modes
-# ---------------------------------------------------------------------------
 
 
 def test_shim_returns_500_on_tokenize_returns_none():
@@ -432,9 +422,7 @@ def test_backend_not_loaded_short_circuits():
     assert threaded_t < 0.05
 
 
-# ---------------------------------------------------------------------------
 # (4) Stress / concurrency
-# ---------------------------------------------------------------------------
 
 
 def test_50_concurrent_probes_complete_without_deadlock():
@@ -499,9 +487,7 @@ def test_100_concurrent_healths_during_slow_probe_all_responsive():
     assert max_lat < 0.35, f"100-burst max latency {max_lat:.3f}s exceeds 350 ms"
 
 
-# ---------------------------------------------------------------------------
 # (5) Drift / regression guards on the production source
-# ---------------------------------------------------------------------------
 
 
 def test_load_model_caches_audio_type_inside_serial_load_lock():
@@ -588,9 +574,7 @@ def test_no_other_async_route_calls_detect_audio_type_unwrapped():
     )
 
 
-# ---------------------------------------------------------------------------
 # (6) Timing budgets
-# ---------------------------------------------------------------------------
 
 
 def test_load_response_under_2s_with_fast_shim():
@@ -624,9 +608,7 @@ def test_repeated_loads_bounded_total_time():
     assert elapsed < 10.0
 
 
-# ---------------------------------------------------------------------------
 # (7) Browser-compatibility surface
-# ---------------------------------------------------------------------------
 
 
 def test_response_is_valid_browser_parseable_json():
@@ -692,9 +674,7 @@ def test_response_shape_matches_pre_fix_for_no_match():
             assert body == {"audio_type": None}
 
 
-# ---------------------------------------------------------------------------
 # (8) Cancellation
-# ---------------------------------------------------------------------------
 
 
 def test_client_disconnect_during_probe_does_not_crash_server():
diff --git a/tests/studio/playwright_chat_ime_i18n.py b/tests/studio/playwright_chat_ime_i18n.py
index 828187d462..f27266193d 100644
--- a/tests/studio/playwright_chat_ime_i18n.py
+++ b/tests/studio/playwright_chat_ime_i18n.py
@@ -4,20 +4,15 @@
 """Studio chat composer IME + multilingual regression smoke.
 
 Covers three surfaces:
-  A. Stuck IME composition (issue #5318 / PR #5327): duplicate
-     compositionstart with no compositionend left isComposing=true,
-     dropping all subsequent keystrokes including ASCII.
-  B. Multilingual paste round-trip across 31 scripts -- guards the
-     controlled-textarea / React state plumbing against Unicode mangling.
-  C. Stuck compositionend (issue #5546): Chrome on Windows over WSL
-     fires compositionstart + compositionupdate but never compositionend,
-     wedging Send disabled after the IME commits. Verifies the
-     watchdog in useImeComposerInputHandlers releases the flag.
+  A. Stuck IME composition (#5318 / PR #5327): duplicate compositionstart with
+     no compositionend left isComposing=true, dropping keystrokes.
+  B. Multilingual paste round-trip across 31 scripts (Unicode plumbing).
+  C. Stuck compositionend (#5546): WSL Chrome never fires compositionend,
+     wedging Send disabled; the useImeComposerInputHandlers watchdog releases it.
 
 Model-free; the bug surface is the composer, not inference.
-
-Env contract matches playwright_chat_ui.py:
-  BASE_URL, STUDIO_NEW_PW, PW_ART_DIR, STUDIO_UI_STRICT.
+Env contract matches playwright_chat_ui.py: BASE_URL, STUDIO_NEW_PW, PW_ART_DIR,
+STUDIO_UI_STRICT.
 """
 
 import os
@@ -49,8 +44,7 @@ STRICT = os.environ.get("STUDIO_UI_STRICT", "0") == "1"
 WALL_TIMEOUT_S = float(os.environ.get("STUDIO_IME_WALL_TIMEOUT_S", "300"))
 
 
-# One short greeting + arithmetic per script (ordered by speaker count) --
-# each entry catches a distinct class of Unicode regression.
+# One greeting + arithmetic per script; each catches a distinct Unicode class.
 I18N_SAMPLES = [
     ("en", "English", "Hello, 1+1=2"),
     ("zh-CN", "Chinese (Simplified)", "你好，1+1=2"),
@@ -156,8 +150,8 @@ with sync_playwright() as p:
         except Exception as _shoot_err:
             info(f"WARN: screenshot {name} failed: {_shoot_err}")
 
-    # 1. Bootstrap auth via /change-password (mirrors playwright_chat_ui.py
-    #    retry-on-rerender to absorb React form-detach races).
+    # 1. Bootstrap auth via /change-password (retry-on-rerender absorbs React
+    #    form-detach races, mirroring playwright_chat_ui.py).
     step("change-password through UI (Setup your account)")
     form_err: Exception | None = None
     for _form_attempt in range(3):
@@ -205,7 +199,7 @@ with sync_playwright() as p:
     if form_err is not None:
         raise form_err
 
-    # 2. Wait for composer mount. No GGUF: the bug surface is React state, not inference.
+    # 2. Wait for composer mount (no GGUF: the bug is React state, not inference).
     step("wait for composer to mount")
     try:
         page.wait_for_load_state("networkidle", timeout = 30_000)
@@ -251,8 +245,8 @@ with sync_playwright() as p:
     else:
         info('composer dir="auto" present')
 
-    # Source-level guard for the edit and compare composers (neither
-    # is mounted here): grep the JSX for dir="auto" inside each block.
+    # Source-level guard for the unmounted edit/compare composers: grep their
+    # JSX for dir="auto".
     _repo_root = Path(__file__).resolve().parents[2]
     _thread_src = (
         _repo_root / "studio/frontend/src/components/assistant-ui/thread.tsx"
@@ -276,9 +270,9 @@ with sync_playwright() as p:
         return composer.evaluate("(el) => el.value")
 
     def set_value_via_setter(s: str) -> str:
-        """Write via React's monkey-patched setter + paste input event,
-        then await two rAFs so the controlled value is committed before
-        readback (plain `.value=s` would be overwritten on next render)."""
+        """Write via React's setter + paste input event, then await two rAFs so the
+        controlled value commits before readback (plain `.value=s` is overwritten
+        on next render)."""
         return composer.evaluate(
             """async (el, v) => {
                 const setter = Object.getOwnPropertyDescriptor(
@@ -369,9 +363,9 @@ with sync_playwright() as p:
     shoot("05-normal-composition")
     clear()
 
-    # 6. Stuck IME repro for issue #5318: duplicate compositionstart with
-    #    no compositionend wedged isComposing=true and dropped ASCII keys.
-    #    PR #5327 cleared the stale state on non-composing input.
+    # 6. Stuck IME repro (#5318): duplicate compositionstart with no
+    #    compositionend wedged isComposing=true; PR #5327 clears it on
+    #    non-composing input.
     step("BUG REPRO: stuck IME composition recovery (issue #5318)")
     clear()
     composer.click()
@@ -385,9 +379,8 @@ with sync_playwright() as p:
             el.dispatchEvent(new CompositionEvent('compositionstart', {bubbles:true, data:''}));
         }"""
     )
-    # Drive the real keyboard path; on the broken build React drops
-    # 'abcd' and reconciles el.value back to ''. wait_for_function
-    # crosses the microtask boundary so we see committed React state.
+    # On the broken build React drops 'abcd' and reconciles el.value to ''.
+    # wait_for_function crosses the microtask boundary to see committed state.
     page.keyboard.type("abcd")
     try:
         page.wait_for_function(
@@ -424,12 +417,9 @@ with sync_playwright() as p:
     info("stuck-composition recovery PASS")
     clear()
 
-    # 6b. WSL + Windows Chrome repro for issue #5546: Chrome never emits
-    #     compositionend after the IME commit, so the watchdog has to
-    #     release the composing flag on its own once the events go silent.
-    #     This dispatches a realistic "compose, commit, then nothing"
-    #     sequence — no compositionend, no follow-up keystrokes — and
-    #     waits for the Send button to come back enabled.
+    # 6b. WSL+Chrome repro (#5546): Chrome never emits compositionend after the
+    #     IME commit, so the watchdog must release the composing flag once events
+    #     go silent. Dispatch "compose, commit, then nothing" and wait for Send.
     step("BUG REPRO: stuck compositionend recovery (issue #5546)")
     clear()
     composer.click()
@@ -473,13 +463,10 @@ with sync_playwright() as p:
     info("compositionend watchdog recovery PASS")
     clear()
 
-    # 6c. Watchdog-race repro: after the watchdog clears composingRef during a
-    #     long candidate pause, a subsequent IME keydown (browser still sees
-    #     isComposing=true / keyCode 229) must not slip preedit text through
-    #     the form submit. The onKeyDown gate re-pins composingRef so the
-    #     handleSubmit / blockSend guards keep refusing. The Send button stays
-    #     visually enabled (watchdog has already cleared the React state); the
-    #     refusal happens at form.requestSubmit() time, not at the button.
+    # 6c. Watchdog-race repro: after the watchdog clears composingRef, a later
+    #     IME keydown (isComposing=true / keyCode 229) must not slip preedit text
+    #     through submit. The onKeyDown gate re-pins composingRef so handleSubmit
+    #     refuses at form.requestSubmit() time, not at the (enabled) button.
     step("BUG REPRO: keydown re-pin after watchdog cleared composing (issue #5546 follow-up)")
     clear()
     composer.click()
@@ -504,10 +491,9 @@ with sync_playwright() as p:
         expect(send_btn_keydown).not_to_be_disabled(timeout = 8_000)
     except Exception:
         soft_fail("watchdog did not clear before keydown re-pin test")
-    # Fire the IME-confirm Enter (keyCode 229, isComposing=true) then trigger
-    # the form submit synchronously. With the keydown gate, composingRef is
-    # re-pinned before handleSubmit runs and the submit is prevented; the
-    # textarea must still hold the preedit text.
+    # Fire the IME-confirm Enter (keyCode 229) then submit synchronously. The
+    # keydown gate re-pins composingRef before handleSubmit, preventing submit;
+    # the textarea must still hold the preedit text.
     submit_probe = composer.evaluate(
         """(el) => {
             el.focus();
@@ -533,11 +519,9 @@ with sync_playwright() as p:
     clear()
 
     # 6d. Keydown re-pin must also re-arm the watchdog. On the WSL+Chrome
-    #     stuck-compositionend path the IME never fires a follow-up
-    #     compositionend or non-composing input, so after the IME keydown
-    #     re-pins composingRef the watchdog has to take it back to false on
-    #     its own — otherwise Send re-locks permanently after the very
-    #     scenario this PR was supposed to fix. (Codex P1, commit 597af0d0.)
+    #     stuck-compositionend path no follow-up event arrives, so after keydown
+    #     re-pins composingRef the watchdog must clear it again or Send re-locks
+    #     permanently. (Codex P1, commit 597af0d0.)
     step("BUG REPRO: keydown re-pin re-arms watchdog (#5546 follow-up regression)")
     clear()
     composer.click()
@@ -563,8 +547,7 @@ with sync_playwright() as p:
     except Exception:
         soft_fail("watchdog did not clear before re-arm test (first cycle)")
     # IME-confirm keydown re-pins composingRef. Without the re-arm fix the
-    # watchdog would never run again and Send would stay blocked at the
-    # submit-time guard forever, even though no follow-up IME event arrives.
+    # watchdog never runs again and Send stays blocked forever.
     composer.evaluate(
         """(el) => {
             el.focus();
@@ -574,9 +557,9 @@ with sync_playwright() as p:
             }));
         }"""
     )
-    # Second watchdog cycle: a real submit attempt now must eventually be
-    # allowed. Trigger requestSubmit() after the re-armed watchdog window
-    # plus a little slack; on the buggy build the form stays gated forever.
+    # Second watchdog cycle: a real submit must eventually be allowed. Trigger
+    # requestSubmit() after the re-armed window plus slack; the buggy build stays
+    # gated forever.
     rearm_probe = page.evaluate(
         """async (selector) => {
             const ta = document.querySelector(selector);
@@ -609,8 +592,8 @@ with sync_playwright() as p:
     info("keydown re-pin re-arm PASS")
     clear()
 
-    # 7. Final state. The change-password redirect emits benign 401 noise,
-    #    so we filter via is_benign_* and only fail on real errors.
+    # 7. Final state. Filter benign 401 noise from the change-password redirect
+    #    via is_benign_*; fail only on real errors.
     shoot("07-final")
     real_page_errors = [e for e in page_errors if not is_benign_page_error(e)]
     real_console_errors = [e for e in console_errors if not is_benign_console_error(e)]
diff --git a/tests/studio/run_real_mlx_smoke.py b/tests/studio/run_real_mlx_smoke.py
index 3b494a4272..6bf0288206 100644
--- a/tests/studio/run_real_mlx_smoke.py
+++ b/tests/studio/run_real_mlx_smoke.py
@@ -4,58 +4,24 @@
 """
 End-to-end MLX smoke test on real Apple Silicon -- multi-process driver.
 
-Two subcommands so the workflow can drive cold-start reloads in fresh
-Python processes (the way real users hit the load path):
+Two subcommands let the workflow drive cold-start reloads in fresh
+processes (the way real users hit the load path):
 
     python run_real_mlx_smoke.py train  --workdir DIR
     python run_real_mlx_smoke.py reload --format {lora|merged|gguf} --dir D
 
-The `train` subcommand:
-  1. Loads `unsloth/gemma-3-270m-it` via FastMLXModel.from_pretrained.
-  2. Applies LoRA r=8 on q/k/v/o.
-  3. Computes pre-training loss + grad norm via mx.nn.value_and_grad.
-  4. Trains 7 deterministic steps on a dataset of the SAME row repeated
-     ("<<HELLO!!>> My name is Unsloth!"), with batch_size=2 and
-     gradient_accumulation_steps=3 so each step processes 6 sequences
-     and the run sees 42 sequences total.
-  5. Computes post-training loss + grad norm.
-  6. Generates from "<<HELLO!!>> My name is " and asserts "Unsloth"
-     appears in the in-memory completion.
-  7. Saves the trained model in three formats:
-       - LoRA adapter (save_pretrained_merged save_method="lora")
-       - Merged 16-bit (save_pretrained_merged save_method="merged_16bit")
-       - GGUF (save_pretrained_gguf, best-effort -- skipped with a
-         clear reason if save raises; e.g. llama.cpp's
-         convert_hf_to_gguf currently asserts on Gemma-3-270m's
-         tokenizer vocab. Soft-skipped so the LoRA + merged checks
-         continue to gate the PR.)
-  8. Emits `train_metrics.json` with per-phase timing / peak GPU /
-     peak RSS / per-step losses / pre+post grad norms / generations
-     / gguf_supported flag, for regression detection across CI runs.
+`train` loads gemma-3-270m-it, applies LoRA, probes pre/post loss+grad,
+overfits one repeated row, generates, saves in lora/merged_16bit/gguf
+(gguf best-effort), and writes train_metrics.json. `reload` reopens each
+saved format in a fresh process and writes <format>_reload_metrics.json.
 
-Reloads run as separate workflow steps so each is a fresh Python
-process. For lora / merged the reload uses
-FastMLXModel.from_pretrained directly. For gguf the reload spawns
-the llama-cli binary built by save_pretrained_gguf and parses
-stdout. Each subcommand emits `<format>_reload_metrics.json` next
-to the saved dir.
+GGUF export and LoRA reload fixes land in unslothai/unsloth-zoo#627.
 
-The two upstream unsloth_zoo bugs the earlier draft of this script
-worked around are fixed in unslothai/unsloth-zoo#627: GGUF export
-no longer raises NotImplementedError on Apple Silicon (llama_cpp.py
-catches it from the device_type module-level call) and LoRA reload
-via FastMLXModel.from_pretrained(lora_dir) works without an external
-config.json copy (mlx_loader.py preserves local_path when config.json
-is missing so the adapter_config.json branch can run).
+Determinism: seeds random/numpy/mlx.core.random and forwards SEED to
+from_pretrained / get_peft_model / MLXTrainingConfig. Metal has minor
+reduction-order nondeterminism, so loss assertions are bounds, not exact.
 
-Determinism: seeds Python `random`, `numpy`, and `mlx.core.random` in
-every process before any MLX operation. Forwards `random_state=SEED`
-to FastMLXModel.from_pretrained / get_peft_model and `seed=SEED` to
-MLXTrainingConfig. Metal still has minor reduction-order
-nondeterminism, so loss assertions are bounds rather than exact.
-
-Only runnable on a real Apple Silicon host; invoked from
-.github/workflows/mlx-ci.yml on the macos-14 runner.
+Apple-Silicon only; invoked from .github/workflows/mlx-ci.yml.
 """
 
 from __future__ import annotations
@@ -99,10 +65,7 @@ def _peak_gpu_gb() -> float:
 
     if not mx.metal.is_available():
         return 0.0
-    # Newer MLX deprecates mx.metal.get_peak_memory in favour of the
-    # top-level mx.get_peak_memory; fall back to the old API for
-    # compatibility with older MLX versions still present in the
-    # environment.
+    # Newer MLX moved get_peak_memory to top-level; fall back to mx.metal for old versions.
     getter = getattr(mx, "get_peak_memory", None) or getattr(mx.metal, "get_peak_memory", None)
     if getter is None:
         return 0.0
@@ -113,8 +76,7 @@ def _peak_gpu_gb() -> float:
 
 
 def _peak_rss_gb() -> float:
-    """Peak resident set size for this process. macOS getrusage returns
-    bytes; Linux returns kilobytes."""
+    """Peak RSS for this process (macOS getrusage = bytes, Linux = KB)."""
     rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
     if sys.platform == "darwin":
         return float(rss) / (1024**3)
@@ -122,8 +84,7 @@ def _peak_rss_gb() -> float:
 
 
 class Phase:
-    """Wall-clock + memory tracker for a named phase. Records into a
-    metrics dict so we can later JSON-dump for regression detection."""
+    """Wall-clock + memory tracker for a named phase; records into a metrics dict."""
 
     def __init__(self, name: str, metrics: dict):
         self.name = name
@@ -154,8 +115,7 @@ class Phase:
 
 
 def _compute_loss_and_grad_norm(model, tokenizer, text: str) -> tuple[float, float]:
-    """One forward+backward of next-token cross-entropy on `text`.
-    Returns (loss, ||grad||_2)."""
+    """One fwd+bwd of next-token CE on `text`. Returns (loss, ||grad||_2)."""
     import mlx.core as mx
     import mlx.nn as nn
     from mlx.utils import tree_flatten
@@ -185,23 +145,12 @@ def _compute_loss_and_grad_norm(model, tokenizer, text: str) -> tuple[float, flo
 
 
 def _teacher_forced_completion_loss(model, tokenizer, prompt: str, completion: str) -> float:
-    """Mean next-token CE loss on `completion` tokens given `prompt` (teacher
-    forced -- no decoding, no sampling, no greedy argmax).
+    """Mean next-token CE on `completion` given `prompt`, teacher-forced.
 
-    Decouples the memorisation check from greedy-decode geometry. A 47-round,
-    13-seed sweep on this fixture showed greedy `completion in output` lands
-    in the 46-77% range across MLX configs (config-fragile), while
-    post_train_loss is < 0.1 in 100% of configs that reach the basin. Teacher-
-    forced completion loss is a subset of post_train_loss so it inherits the
-    same reliability AND is more specific: it asserts *what* the model
-    memorised, not just *that* it reached low loss on the full row.
-
-    Args:
-      model:       the LoRA-trained MLX model
-      tokenizer:   the tokenizer used during training (must match)
-      prompt:      the conditioning text (e.g. PROMPT)
-      completion:  the substring the model should have learnt to emit
-                   after `prompt` (e.g. EXPECT_IN_OUTPUT + "!")
+    Decouples the memorisation check from greedy-decode geometry: a sweep
+    found greedy `completion in output` lands at 46-77% across MLX configs
+    while post_train_loss is < 0.1 whenever the run reaches the basin. This
+    asserts *what* the model memorised, not just that loss is low.
 
     Returns mean cross-entropy over the completion's tokens.
     """
@@ -275,13 +224,9 @@ def cmd_train(args) -> int:
     mx.random.seed(SEED)
 
     with Phase("apply_lora", metrics):
-        # Standard unsloth LoRA target set (q/k/v/o + gate/up/down).
-        # With bs=2 grad_accum=3 (effective batch 6) the q/k/v/o-only
-        # LoRA collapsed in 7 steps -- training loss kept dropping but
-        # inference output the structural skeleton ("My name") without
-        # recovering the specific "Unsloth" token. Including the MLP
-        # projections gives the LoRA enough capacity to memorize the
-        # training row at the larger effective batch.
+        # Standard unsloth LoRA target set (q/k/v/o + gate/up/down). q/k/v/o
+        # alone collapsed in 7 steps (loss dropped but "Unsloth" wasn't
+        # recovered); MLP projections add the capacity to memorize the row.
         model = FastMLXModel.get_peft_model(
             model,
             r = 8,
@@ -314,29 +259,19 @@ def cmd_train(args) -> int:
         config = MLXTrainingConfig(
             per_device_train_batch_size = 2,
             gradient_accumulation_steps = 3,
-            # 47-round mlx-parity-probes sweep (PR #5498 / staging-2#119)
-            # found 7 steps is below the convergence horizon at any clip
-            # setting -- the trainer hasn't memorized the train row yet
-            # when the smoke probes loss/generation. At 30 steps every
-            # seed tested hits post_train_loss=0 across all clip
-            # configurations, so 30 is the seed-robust gate.
+            # Sweep (PR #5498) found 7 steps is below the convergence horizon
+            # at any clip; at 30 steps every seed hits post_train_loss=0, so
+            # 30 is the seed-robust gate.
             max_steps = 30,
             learning_rate = 1e-3,
             warmup_steps = 0,
             lr_scheduler_type = "constant",
             optim = "adamw",
             weight_decay = 0.0,
-            # max_grad_value (elementwise) is materially cheaper than
-            # max_grad_norm on MLX -- norm clip needs a cross-tree
-            # reduction + materializing all grad tensors at full
-            # precision, value clip is tree_map(mx.clip) per leaf.
-            # MLXTrainingConfig defaults to max_grad_value=1.0 for
-            # exactly this reason; pin both explicitly here so the
-            # configured clip matches what runs (the trainer prints a
-            # notice when both > 0 and value wins, so disable norm).
-            # Empirical 13-seed pass rate at this fixture: value=1.0
-            # 62%, norm=1.0 46%, value=5.0 33%, value=0.5 77% -- the
-            # cheaper default is also the higher-pass-rate default.
+            # Elementwise value clip is cheaper than norm clip on MLX (no
+            # cross-tree reduction) and has a higher 13-seed pass rate at this
+            # fixture (value=1.0 62%, norm=1.0 46%). Pin both: value wins when
+            # both > 0, so disable norm.
             max_grad_norm = 0.0,
             max_grad_value = 1.0,
             logging_steps = 1,
diff --git a/tests/studio/test_auth_form_input_count.py b/tests/studio/test_auth_form_input_count.py
index b80f59d960..80f73e4065 100644
--- a/tests/studio/test_auth_form_input_count.py
+++ b/tests/studio/test_auth_form_input_count.py
@@ -3,21 +3,15 @@
 
 """Pin the auth-form input-count contract on the change-password page.
 
-PR #5490 added a third visible "Current password" input so the
-admin-forced must_change_password reset path (where no bootstrap
-script is injected) could supply a current password. The side
-effect was that the dominant first-boot UX, where the backend
-injects window.__UNSLOTH_BOOTSTRAP__ and the form silently reuses
-that password, now showed three visible inputs instead of the two
-it had before. PR #5545 restores the two-input first-boot UX by
-rendering the Current password input only when
-window.__UNSLOTH_BOOTSTRAP__ is absent.
+PR #5490 added a third "Current password" input for the admin-forced reset
+path; this regressed the first-boot UX (which reuses the injected
+window.__UNSLOTH_BOOTSTRAP__ password) to three visible inputs. PR #5545
+restores two inputs by rendering Current password only when BOOTSTRAP is
+absent.
 
-These tests inspect the auth-form source file directly. They never
-boot Studio, never spawn a browser, and have no network or device
-dependencies, so they are fully deterministic and run on any CI
-runner without a JS toolchain. The companion Playwright probe lives
-in tests/studio/playwright_chat_ui.py and covers the runtime side.
+These tests inspect the auth-form source directly (no Studio, browser, or
+network), so they run deterministically on any CI runner. The runtime side
+is covered by tests/studio/playwright_chat_ui.py.
 """
 
 from __future__ import annotations
diff --git a/tests/studio/test_cancel_id_wiring.py b/tests/studio/test_cancel_id_wiring.py
index b6f75c0be9..d821786431 100644
--- a/tests/studio/test_cancel_id_wiring.py
+++ b/tests/studio/test_cancel_id_wiring.py
@@ -51,11 +51,10 @@ def test_chat_completion_request_has_cancel_id_field():
 
 
 def test_cancel_route_matches_cancel_id_exclusively_when_present():
-    # A stale cancel POST carrying cancel_id AND session_id must not
-    # cancel a later run on the same thread via the shared session_id.
-    # Enforce this by requiring the handler to early-return through an
-    # exclusive-cancel_id path -- either an atomic helper or a keys
-    # list containing ONLY cancel_id (never session_id).
+    # A stale cancel POST carrying cancel_id AND session_id must not cancel a
+    # later run via the shared session_id. Require the handler to early-return
+    # through an exclusive-cancel_id path (atomic helper, or keys list with
+    # ONLY cancel_id, never session_id).
     for node in ast.walk(ast.parse(ROUTES_SRC)):
         if isinstance(node, ast.AsyncFunctionDef) and node.name == "cancel_inference":
             break
@@ -137,10 +136,9 @@ def test_chat_adapter_sends_cancel_id_in_abort_cancel_post():
 
 
 def test_abort_cancel_post_uses_plain_fetch_with_manual_auth_header():
-    # authFetch redirects to login on 401, which would kick the user to
-    # the login page mid-stop if the access token expired during a long
-    # stream. Use plain fetch + manual Authorization header for a
-    # best-effort cancel that never triggers the refresh/redirect flow.
+    # authFetch redirects to login on 401, kicking the user out mid-stop if
+    # the token expired during a long stream. Use plain fetch + manual
+    # Authorization header for a best-effort cancel with no refresh/redirect.
     start = ADAPTER_SRC.find("const onAbortCancel")
     assert start >= 0, "onAbortCancel handler missing"
     rest = ADAPTER_SRC[start:]
diff --git a/tests/studio/test_cli_studio_defaults.py b/tests/studio/test_cli_studio_defaults.py
index a83a62f586..ed1bd37c3d 100644
--- a/tests/studio/test_cli_studio_defaults.py
+++ b/tests/studio/test_cli_studio_defaults.py
@@ -23,13 +23,10 @@ def _find_typer_option_default(source: str, func_name: str, long_option: str):
             continue
         if func_node.name != func_name:
             continue
-        # Walk both regular args and kwonly args, each paired with its default.
         all_args = func_node.args.args + func_node.args.kwonlyargs
         all_defaults = func_node.args.defaults + [
             d for d in func_node.args.kw_defaults if d is not None
         ]
-        # ast pads defaults right-aligned against args (ignoring kwonly). We
-        # iterate calls directly, which is simpler and robust.
         for default in all_defaults:
             if not isinstance(default, ast.Call):
                 continue
@@ -42,8 +39,7 @@ def _find_typer_option_default(source: str, func_name: str, long_option: str):
             )
             if not is_typer_option:
                 continue
-            # First positional is the default value; remaining positionals are
-            # option flags like "--host", "-H".
+            # First positional is the default; the rest are flags like "--host".
             if not default.args:
                 continue
             flags = [
diff --git a/tests/studio/test_composer_rtl_bidi_attribute.py b/tests/studio/test_composer_rtl_bidi_attribute.py
index e4273c8731..33e5c450cf 100644
--- a/tests/studio/test_composer_rtl_bidi_attribute.py
+++ b/tests/studio/test_composer_rtl_bidi_attribute.py
@@ -133,10 +133,9 @@ def _extract_block(
     opener: str = "(",
     closer: str = ")",
 ) -> str:
-    """Return the source between the first balanced opener/closer that
-    starts at or after `anchor`. Used to scope assertions to a specific
-    handler so a re-arm call in some other function does not satisfy
-    the gate test."""
+    """Return the source within the first balanced opener/closer at or
+    after `anchor`. Scopes assertions to one handler so a re-arm call
+    elsewhere does not satisfy the gate test."""
     start = src.find(anchor)
     assert start != -1, f"anchor {anchor!r} not found"
     open_idx = src.find(opener, start)
diff --git a/tests/studio/test_frontend_dep_removal.py b/tests/studio/test_frontend_dep_removal.py
index 138ffb4ba0..d1835c2bac 100644
--- a/tests/studio/test_frontend_dep_removal.py
+++ b/tests/studio/test_frontend_dep_removal.py
@@ -315,14 +315,10 @@ def run_case(case: Case, head_pkg: dict) -> tuple[bool, str]:
     )
 
 
-# ---------------------------------------------------------------------------
-# Classifier unit tests: feed hand-crafted snippets directly into classify()
-# and assert the returned kind. Covers sneaky import shapes that an
-# adversarial / careless dev might use to obscure a real usage.
-# ---------------------------------------------------------------------------
+# Classifier unit tests: feed hand-crafted snippets into classify() and assert
+# the returned kind. Covers sneaky import shapes used to obscure a real usage.
 
-# Import the script's classify() by file path so this test does not need
-# the package to be installed.
+# Import classify() by file path so this test needs no installed package.
 import importlib.util as _ilu
 
 _spec = _ilu.spec_from_file_location("_dep_check", str(SCRIPT))
@@ -739,11 +735,9 @@ def run_classify_unit_tests() -> int:
     return 0 if passed == len(CLASSIFY_CASES) else 1
 
 
-# ---------------------------------------------------------------------------
-# Adversarial end-to-end cases: drop a sneaky synthetic file into src/,
-# run the checker, then clean up. Catches the case where pattern detection
-# regresses for a real grep+classify pipeline (not just classify in isolation).
-# ---------------------------------------------------------------------------
+# Adversarial end-to-end cases: drop a sneaky synthetic file into src/, run the
+# checker, then clean up. Catches detection regressions in the full
+# grep+classify pipeline (not just classify in isolation).
 
 ADVERSARIAL_TMP_DIR = REPO / "studio/frontend/src/__dep_check_adversarial__"
 
@@ -894,14 +888,9 @@ ADV_CASES: list[AdvCase] = [
 ]
 
 
-# ---------------------------------------------------------------------------
 # package.json field-reference cases: simulate `prettier: "@x/config"`,
-# `eslintConfig.extends`, `overrides`, `peerDependenciesMeta`, etc.
-# These test the package_json_extra_refs() coverage. Cross-checked against
-# the patterns used by Tailwind, Stylelint, Prettier, Next.js, Astro,
-# TypeScript, ESLint, SvelteKit, Storybook, Vite, and TanStack/Query
-# manifests.
-# ---------------------------------------------------------------------------
+# `eslintConfig.extends`, `overrides`, `peerDependenciesMeta`, etc., testing
+# package_json_extra_refs() coverage across common tool manifests.
 
 
 @dataclass
@@ -1205,9 +1194,7 @@ def run_adversarial_cases() -> int:
     return 0 if passed == len(ADV_CASES) else 1
 
 
-# ---------------------------------------------------------------------------
-# Dead-dep enumeration cases.
-# ---------------------------------------------------------------------------
+# Dead-dep enumeration cases
 
 
 @dataclass
@@ -1383,14 +1370,9 @@ def run_enum_cases() -> int:
     return 0 if passed == len(ENUM_CASES) else 1
 
 
-# ---------------------------------------------------------------------------
-# Script-wrapper cases: exercise scripts_bin_refs / _next_real_bin so a
-# package.json script like `cross-env CI=1 biome check` correctly credits
-# `@biomejs/biome` rather than the wrapper itself. The 10x reviewer flagged
-# the original "first non-env token" heuristic as too narrow: any project
-# using cross-env / dotenv / dotenvx / env-cmd / a quoted env value would
-# bypass the bin-name check.
-# ---------------------------------------------------------------------------
+# Script-wrapper cases: exercise scripts_bin_refs / _next_real_bin so a script
+# like `cross-env CI=1 biome check` credits `@biomejs/biome`, not the wrapper.
+# The original "first non-env token" heuristic missed cross-env / dotenv / etc.
 
 
 @dataclass
diff --git a/tests/studio/test_hardware_dispatch_matrix.py b/tests/studio/test_hardware_dispatch_matrix.py
index 8864075dd7..edb8a66b93 100644
--- a/tests/studio/test_hardware_dispatch_matrix.py
+++ b/tests/studio/test_hardware_dispatch_matrix.py
@@ -1,35 +1,12 @@
 # SPDX-License-Identifier: AGPL-3.0-only
-"""
-Comprehensive hardware dispatch matrix for Studio.
+"""Hardware dispatch matrix for Studio.
 
-Drives every supported hardware profile from a single test host by
-spoofing platform / torch.cuda / torch.xpu / sys.modules['mlx'] so we
-can exercise the CUDA, ROCm, XPU, MLX, and CPU dispatch paths
-deterministically without real hardware.
-
-Profiles checked:
-
-    nvidia_cuda          Linux x86_64 + torch.cuda.is_available()=True,
-                         torch.version.hip=None
-    amd_rocm             Linux x86_64 + torch.cuda.is_available()=True,
-                         torch.version.hip="6.1"   (PyTorch ROCm aliases
-                         torch.cuda.* over HIP)
-    intel_xpu            Linux x86_64 + torch.cuda off, torch.xpu.is_available()=True
-    apple_silicon_mlx    Darwin arm64 + cuda off + xpu off + mlx importable
-    apple_silicon_no_mlx Darwin arm64 + everything off (no mlx pkg)
-    linux_arm64_with_mlx Linux arm64 + mlx importable -- gate must NOT activate
-                         (canary against accidental Linux-arm64 hijack)
-    cpu_only             Linux x86_64 + nothing -- pure CPU fallback
-
-For each profile we assert three contracts:
-
-  1. ``unsloth._IS_MLX`` (re-evaluated under the spoof).
-  2. ``utils.hardware.detect_hardware()`` ``DeviceType`` and ``IS_ROCM``.
-  3. ``utils.hardware.is_apple_silicon()``.
-
-Add a row to ``PROFILES`` to extend coverage; tests parametrize over it
-automatically. No real hardware required.
-"""
+Spoofs platform / torch.cuda / torch.xpu / sys.modules['mlx'] to exercise the
+CUDA, ROCm, XPU, MLX, and CPU dispatch paths deterministically without real
+hardware. Each profile in ``PROFILES`` (CUDA, ROCm, XPU, Apple+/-mlx, the
+linux-arm64-with-mlx canary, CPU) asserts three contracts: ``unsloth._IS_MLX``,
+``detect_hardware()`` DeviceType + ``IS_ROCM``, and ``is_apple_silicon()``.
+Add a row to ``PROFILES`` to extend coverage; tests parametrize over it."""
 
 from __future__ import annotations
 
@@ -189,10 +166,7 @@ PROFILE_IDS = [p.name for p in PROFILES]
 @pytest.fixture
 def spoof_hardware(monkeypatch):
     """Return a function that applies a HardwareProfile to the live process.
-
-    Idempotent: each call re-applies the profile. Cleanup happens
-    automatically when the test exits via monkeypatch.
-    """
+    Idempotent; monkeypatch cleans up on test exit."""
 
     def _apply(profile: HardwareProfile) -> None:
         import platform
@@ -202,12 +176,9 @@ def spoof_hardware(monkeypatch):
         monkeypatch.setattr(platform, "system", lambda: profile.system)
         monkeypatch.setattr(platform, "machine", lambda: profile.machine)
 
-        # torch.cuda.is_available
         monkeypatch.setattr(torch.cuda, "is_available", lambda: profile.cuda_available)
-        # detect_hardware reads torch.cuda.get_device_properties(0).name when
-        # cuda_available is True. On a CPU CI runner that triggers _cuda_init
-        # and crashes with "No CUDA GPUs are available". Stub it so the
-        # dispatch path under test runs end-to-end.
+        # Stub get_device_properties: detect_hardware reads .name when CUDA is
+        # available, which crashes on a CPU CI runner ("No CUDA GPUs").
         if profile.cuda_available:
             stub_props = types.SimpleNamespace(
                 name = "Stub GPU" if not profile.hip_version else "Stub AMD GPU",
@@ -219,13 +190,12 @@ def spoof_hardware(monkeypatch):
                 raising = False,
             )
 
-        # torch.version.hip — None on NVIDIA, "6.1" etc. on ROCm
+        # torch.version.hip: None on NVIDIA, "6.1" etc. on ROCm
         torch_version = torch.version
         monkeypatch.setattr(torch_version, "hip", profile.hip_version, raising = False)
 
-        # torch.xpu.is_available + get_device_name -- detect_hardware reads both.
-        # Real torch.xpu.get_device_name requires the XPU-compiled torch build,
-        # so always stub it under the spoof to keep tests hardware-agnostic.
+        # Stub torch.xpu.* (detect_hardware reads both); real get_device_name
+        # needs the XPU torch build, so always stub to stay hardware-agnostic.
         if hasattr(torch, "xpu"):
             monkeypatch.setattr(torch.xpu, "is_available", lambda: profile.xpu_available)
             monkeypatch.setattr(
@@ -255,8 +225,7 @@ def spoof_hardware(monkeypatch):
             monkeypatch.setitem(sys.modules, "mlx", fake_mlx)
             monkeypatch.setitem(sys.modules, "mlx.core", fake_mlx_core)
         else:
-            # Drop any cached mlx modules and patch find_spec so the
-            # unsloth gate (which uses importlib.util.find_spec) sees
+            # Drop cached mlx and patch find_spec so the unsloth gate sees
             # mlx as absent.
             monkeypatch.delitem(sys.modules, "mlx", raising = False)
             monkeypatch.delitem(sys.modules, "mlx.core", raising = False)
@@ -269,11 +238,9 @@ def spoof_hardware(monkeypatch):
 
             monkeypatch.setattr(importlib.util, "find_spec", _no_mlx)
 
-            # Studio's _has_mlx() literally does `import mlx.core`, not
-            # find_spec, so on a real Apple Silicon host with mlx
-            # genuinely installed the import would still succeed. Block
-            # it via a meta_path finder that raises ImportError for any
-            # `mlx` / `mlx.*` import while this profile is active.
+            # Studio's _has_mlx() does `import mlx.core`, not find_spec, so on a
+            # real Apple Silicon host with mlx installed it would still succeed.
+            # Block it via a meta_path finder that raises ImportError for mlx.*.
             class _BlockMLXFinder:
                 def find_spec(
                     self_inner,
@@ -288,8 +255,7 @@ def spoof_hardware(monkeypatch):
                     return None
 
             blocker = _BlockMLXFinder()
-            # Replace meta_path with a NEW list so monkeypatch can fully
-            # restore the original on teardown (mutating the list in
+            # New list so monkeypatch fully restores on teardown (mutating in
             # place would survive the test).
             monkeypatch.setattr(
                 sys,
@@ -373,10 +339,8 @@ def test_studio_is_apple_silicon_matches_profile(profile, spoof_hardware):
 
 
 def test_cuda_takes_priority_over_mlx_when_both_available(spoof_hardware):
-    """If both CUDA and MLX are available, Studio MUST pick CUDA. This is the
-    canary that protects every existing GPU user from being silently routed
-    to MLX after future refactors.
-    """
+    """If both CUDA and MLX are available, Studio MUST pick CUDA: the canary
+    guarding GPU users from being silently routed to MLX after refactors."""
     profile = HardwareProfile(
         name = "cuda_plus_mlx",
         system = "Darwin",
diff --git a/tests/studio/test_is_mlx_dispatch_gate.py b/tests/studio/test_is_mlx_dispatch_gate.py
index 4e379aa976..594ab39076 100644
--- a/tests/studio/test_is_mlx_dispatch_gate.py
+++ b/tests/studio/test_is_mlx_dispatch_gate.py
@@ -42,16 +42,11 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 UNSLOTH_INIT = REPO_ROOT / "unsloth" / "__init__.py"
 
 
-# ---------------------------------------------------------------------------
 # 1. Source-level structure check on _IS_MLX (no platform dependencies).
-# ---------------------------------------------------------------------------
 
 
 def test_is_mlx_gate_uses_three_required_predicates():
-    """The _IS_MLX assignment must AND together exactly the three checks
-    that Studio depends on: Darwin OS, arm64 machine, and an importable
-    mlx package. Dropping any one of them silently breaks dispatch.
-    """
+    """_IS_MLX must AND the three checks Studio depends on (Darwin, arm64, importable mlx); dropping any breaks dispatch."""
     tree = ast.parse(UNSLOTH_INIT.read_text())
 
     target = None
@@ -95,18 +90,13 @@ def test_is_mlx_gate_uses_three_required_predicates():
     ), "_IS_MLX helper must run the local MLX precheck before importing zoo"
 
 
-# ---------------------------------------------------------------------------
 # 2. Runtime gate behavior with the platform spoofed to Apple Silicon and a
-#    fake mlx module in sys.modules.  Re-evaluates the same expression
-#    rather than reloading unsloth (which would cascade-reload torch).
-# ---------------------------------------------------------------------------
+#    fake mlx module in sys.modules. Re-evaluates the same expression rather
+#    than reloading unsloth (which would cascade-reload torch).
 
 
 def _evaluate_is_mlx_precheck(platform_module, importlib_util, os_module):
-    """Re-evaluate the local _is_mlx_available precheck using injected dependencies.
-
-    Mirrors only the cheap import barrier before unsloth imports unsloth_zoo.
-    """
+    """Re-evaluate the local _is_mlx_available precheck (the import barrier before zoo) with injected deps."""
     return (
         os_module.environ.get("UNSLOTH_FORCE_GPU_PATH", "0") != "1"
         and platform_module.system() == "Darwin"
diff --git a/tests/studio/test_stream_cancel_registration_timing.py b/tests/studio/test_stream_cancel_registration_timing.py
index 6906e9b7d2..6bd74f00de 100644
--- a/tests/studio/test_stream_cancel_registration_timing.py
+++ b/tests/studio/test_stream_cancel_registration_timing.py
@@ -1,43 +1,19 @@
-"""
-Tests that the cancel tracker is registered BEFORE StreamingResponse is
-returned, and that cleanup runs via a `finally` block inside each
-async generator.
+"""Tests that the cancel tracker is registered BEFORE StreamingResponse is
+returned and that cleanup runs in a `finally` inside each async generator.
 
-The zombie-generation scenario is: user clicks Stop during prefill /
-warmup / proxy buffering, before the first SSE chunk. If _tracker
-__enter__ lives inside the async generator body, the registry is empty
-at the moment /api/inference/cancel lands -- so cancel returns 0 and
-the decode runs to completion.
+Zombie scenario: Stop during prefill/warmup/proxy buffering (before the first
+SSE chunk). If _tracker.__enter__ ran inside the generator body, the registry
+would be empty when /api/inference/cancel lands, so cancel returns 0 and decode
+runs to completion. The fix registers in the sync body of
+openai_chat_completions and cleans up in each generator's `finally` -- a
+BackgroundTask would be skipped when stream_response raises.
 
-The fix moves _tracker = _TrackedCancel(...) and _tracker.__enter__()
-to the synchronous body of openai_chat_completions (before the
-StreamingResponse is returned) and places _tracker.__exit__ inside
-each generator's `finally` block. Using a generator `finally` (rather
-than a Starlette BackgroundTask) guarantees cleanup on every
-termination path -- normal exhaustion, CancelledError from
-ClientDisconnect, and OSError / BrokenPipeError during send() --
-because Starlette skips `background` callbacks when stream_response
-raises.
-
-Structural verifies:
-  - No `async def ...:` body contains `_tracker.__enter__()` in
-    routes/inference.py (registration moved to sync body).
-  - Each of the four async generators (gguf_tool_stream,
-    gguf_stream_chunks, stream_chunks, audio_input_stream) contains
-    `_tracker.__exit__(None, None, None)` inside a try/finally block.
-  - No StreamingResponse in openai_chat_completions passes
-    `background=` (cleanup now lives in the generator finally).
-
-Behavioral verifies (extracting `_TrackedCancel` from source and
-exercising the actual runtime semantics):
-  - `finally: _tracker.__exit__(...)` runs on normal completion,
-    mid-stream exception (OSError / BrokenPipeError from send()),
-    and aclose() from Starlette ClientDisconnect.
-  - A pre-set cancel_event (from `_TrackedCancel.__enter__` replaying
-    a pending cancel POST) lets the GGUF while-loop break cleanly
-    and emit final_chunk + [DONE] instead of propagating
-    `GeneratorExit` out of `_stream_with_retry` into the async
-    generator's `except Exception` (which would not catch it).
+Structural verifies: no `_tracker.__enter__()` inside the async generators;
+each of the four generators has `_tracker.__exit__(...)` in a try/finally; no
+StreamingResponse passes `background=`. Behavioral verifies (running the
+extracted `_TrackedCancel`): finally cleanup on normal completion, mid-stream
+OSError, and aclose() from ClientDisconnect; and a pre-set cancel_event lets
+the GGUF loop break cleanly emitting final_chunk + [DONE].
 """
 
 from __future__ import annotations
@@ -328,11 +304,9 @@ def test_finally_cleanup_on_aclose():
 
 
 def test_preset_cancel_event_exits_cleanly_with_done():
-    # Pending-replay: POST /cancel arrived before the stream registered,
-    # was stashed, then consumed by _TrackedCancel.__enter__ which set
-    # cancel_event. The generator must break out of the loop cleanly
-    # and emit final_chunk + [DONE] rather than calling next(gen) and
-    # propagating `GeneratorExit` out of the GGUF stream wrapper.
+    # Pending-replay: a stashed cancel set cancel_event via __enter__. The
+    # generator must break cleanly and emit final_chunk + [DONE] rather than
+    # calling next(gen) and propagating GeneratorExit out of the GGUF wrapper.
     ev = threading.Event()
     ev.set()
     chunks = asyncio.run(_consume(_post_fix_gguf_loop(ev)))
@@ -465,11 +439,9 @@ def test_audio_input_stream_offloads_blocking_next_to_thread():
 
 
 def test_stream_chunks_cancel_branch_resets_backend_state():
-    # The Unsloth path's cancel branch must flush GPU / KV-cache state
-    # via `backend.reset_generation_state()` -- the orchestrator's
-    # internal cancel path does not do this, so a cancel-via-POST that
-    # only broke the loop would leave the subprocess in a dirty state
-    # for the next request.
+    # The Unsloth cancel branch must call backend.reset_generation_state() to
+    # flush GPU/KV-cache state, else a cancel-via-POST leaves the subprocess
+    # dirty for the next request.
     fn = None
     top = None
     for n in ast.walk(_TREE):
@@ -618,12 +590,9 @@ def test_audio_stream_stays_responsive_under_blocking_next():
 
 
 def test_unsloth_stream_loop_emits_zero_tokens_on_preset_cancel():
-    # Pending-cancel replay: _TrackedCancel.__enter__ already set
-    # cancel_event before the generator body starts iterating. The
-    # top-of-loop check must short-circuit the very first iteration so
-    # no token is emitted. Catches a regression that moves the check
-    # below `next()` -- the mid-loop test would still pass but this
-    # test would observe one extra token leak.
+    # Pending-cancel replay: cancel_event was pre-set before iterating, so the
+    # top-of-loop check must short-circuit iteration 1 (zero tokens). Catches a
+    # regression that moves the check below next() (leaks one extra token).
     cancel_event = threading.Event()
     cancel_event.set()
     reset_calls = [0]
diff --git a/tests/test_cli_export_unpacking.py b/tests/test_cli_export_unpacking.py
index 3dbab90b5a..626ff41bc1 100644
--- a/tests/test_cli_export_unpacking.py
+++ b/tests/test_cli_export_unpacking.py
@@ -1,24 +1,14 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""
-Regression tests for unsloth_cli.commands.export.
+"""Regression tests for unsloth_cli.commands.export.
 
-Context: the studio export dialog live-logs work changed
-ExportOrchestrator.export_{merged_model,base_model,gguf,lora_adapter}
-to return (success, message, output_path) instead of (success, message)
-so the frontend can show the on-disk realpath on the success screen.
-The CLI at unsloth_cli/commands/export.py still unpacks two values,
-so every `unsloth export --format ...` crashes with:
-
-    ValueError: too many values to unpack (expected 2)
-
-These tests pin the CLI to the 3-tuple contract by invoking it against
-a fake ExportBackend and asserting exit_code == 0 for each --format.
-No real ML imports; the fake is installed via sys.modules injection so
-the CLI's deferred `from studio.backend.core.export import ExportBackend`
-binds to it.
-"""
+ExportOrchestrator.export_* now returns (success, message, output_path) so the
+frontend can show the realpath, but the CLI still unpacked two values, crashing
+every `unsloth export` with "too many values to unpack (expected 2)". These
+tests pin the CLI to the 3-tuple contract via a fake ExportBackend injected into
+sys.modules (the CLI's deferred import binds to it), asserting exit_code == 0
+per --format."""
 
 from __future__ import annotations
 
@@ -37,11 +27,8 @@ from typer.testing import CliRunner
 
 
 class _FakeExportBackend:
-    """Stand-in for studio.backend.core.export.ExportBackend.
-
-    All export_* methods return the new 3-tuple contract. load_checkpoint
-    keeps its 2-tuple shape (unchanged by the live-logs work).
-    """
+    """Stand-in for ExportBackend: export_* return the new 3-tuple;
+    load_checkpoint keeps its 2-tuple shape."""
 
     def __init__(self) -> None:
         self.loaded: str | None = None
@@ -67,15 +54,9 @@ class _FakeExportBackend:
 
 
 def _install_fake_studio_backend(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Inject fake studio.backend.core.export into sys.modules.
-
-    The CLI imports ExportBackend lazily inside the command function, so
-    patching sys.modules before invoking the command is sufficient to
-    steer the `from studio.backend.core.export import ExportBackend`
-    statement at the fake. Parent packages (studio, studio.backend,
-    studio.backend.core) are stubbed too so Python's import machinery
-    doesn't try to resolve the real (structlog-dependent) tree.
-    """
+    """Inject fake studio.backend.core.export into sys.modules. The CLI imports
+    ExportBackend lazily, so this steers it at the fake; parent packages are
+    stubbed too so import machinery skips the real structlog-dependent tree."""
     for name in ("studio", "studio.backend", "studio.backend.core"):
         monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
 
@@ -83,9 +64,7 @@ def _install_fake_studio_backend(monkeypatch: pytest.MonkeyPatch) -> None:
     fake_mod.ExportBackend = _FakeExportBackend
     monkeypatch.setitem(sys.modules, "studio.backend.core.export", fake_mod)
 
-    # Drop any cached import of the CLI module so the deferred import
-    # inside export() re-resolves against our fake module rather than a
-    # previously cached real one.
+    # Drop cached CLI module so export()'s deferred import re-resolves the fake.
     monkeypatch.delitem(sys.modules, "unsloth_cli.commands.export", raising = False)
 
 
diff --git a/tests/test_enforce_kwargs_spacing.py b/tests/test_enforce_kwargs_spacing.py
index 5e135c982c..4521b0362d 100644
--- a/tests/test_enforce_kwargs_spacing.py
+++ b/tests/test_enforce_kwargs_spacing.py
@@ -82,7 +82,7 @@ def test_blank_removed_for_small_import_block(name):
     out, changed = remove_blank_after_short_import(src)
     assert changed is True
     assert out != src
-    # The import line and the following statement are now adjacent (no blank between).
+    # Import and following statement now adjacent (no blank between).
     assert "\n\n" not in out or out.count("\n\n") < src.count("\n\n")
     # Semantics preserved and idempotent.
     assert ast.dump(ast.parse(out)) == ast.dump(ast.parse(src))
diff --git a/tests/test_finetune_last_n_layers.py b/tests/test_finetune_last_n_layers.py
index e2dafb7638..fa708ddd3e 100644
--- a/tests/test_finetune_last_n_layers.py
+++ b/tests/test_finetune_last_n_layers.py
@@ -1,16 +1,9 @@
 # Unsloth - 2x faster, 70% less memory LLM finetuning
 # Tests for the `finetune_last_n_layers` parity knob (CUDA side).
 #
-# Mirrors unsloth-zoo's `FastMLXModel.get_peft_model` parameter.
-# mlx-lm CLI's CONFIG_DEFAULTS['num_layers']=16 applies LoRA to the
-# last 16 transformer blocks only. On the CUDA path, PEFT exposes
-# `layers_to_transform` to do the same. This convenience knob fills
-# `layers_to_transform` for the user when set, matching mlx-lm CLI
-# AND unsloth-zoo's MLX path with a single config value.
-#
-# The tests intentionally avoid pulling in CUDA / a real model
-# checkpoint — they exercise only the helper that translates
-# `finetune_last_n_layers` into `layers_to_transform`.
+# Mirrors unsloth-zoo's MLX path: fills PEFT's `layers_to_transform` so LoRA
+# applies to the last N transformer blocks, matching mlx-lm CLI's num_layers.
+# Exercises only the translation helper, no CUDA / real checkpoint.
 
 from __future__ import annotations
 
diff --git a/tests/test_import_fixes_drift.py b/tests/test_import_fixes_drift.py
index bf033d0235..373830ae4a 100644
--- a/tests/test_import_fixes_drift.py
+++ b/tests/test_import_fixes_drift.py
@@ -48,9 +48,7 @@ def _safe_version(raw):
         return _PkgVersion(match.group(0))
 
 
-# ===========================================================================
 # protobuf
-# ===========================================================================
 
 
 def test_protobuf_message_factory_get_prototype_or_get_message_class_present():
@@ -73,9 +71,7 @@ def test_protobuf_message_factory_get_prototype_or_get_message_class_present():
     assert has_get_prototype or has_get_message_class
 
 
-# ===========================================================================
 # datasets
-# ===========================================================================
 
 
 def test_datasets_version_not_in_broken_recursion_range():
@@ -92,9 +88,7 @@ def test_datasets_version_not_in_broken_recursion_range():
     )
 
 
-# ===========================================================================
 # trl
-# ===========================================================================
 
 
 def test_trl_is_x_available_returns_bool_not_tuple():
@@ -165,9 +159,7 @@ def test_trl_cached_available_flags_are_not_tuples():
         )
 
 
-# ===========================================================================
 # transformers
-# ===========================================================================
 
 
 def test_pretrained_model_enable_input_require_grads_uses_old_pattern():
@@ -234,9 +226,7 @@ def test_transformers_is_causal_conv1d_available_symbol_present():
         )
 
 
-# ===========================================================================
 # transformers + accelerate (wandb checkers)
-# ===========================================================================
 
 
 def test_transformers_and_accelerate_is_wandb_available_callable():
@@ -266,9 +256,7 @@ def test_transformers_and_accelerate_is_wandb_available_callable():
     )
 
 
-# ===========================================================================
 # peft
-# ===========================================================================
 
 
 def test_peft_transformers_weight_conversion_importable_and_signature():
@@ -298,9 +286,7 @@ def test_peft_transformers_weight_conversion_importable_and_signature():
     )
 
 
-# ===========================================================================
 # triton
-# ===========================================================================
 
 
 def test_triton_compiled_kernel_has_num_ctas_and_cluster_dims():
@@ -335,9 +321,7 @@ def test_triton_compiled_kernel_has_num_ctas_and_cluster_dims():
     )
 
 
-# ===========================================================================
 # torch + torchvision pairing table
-# ===========================================================================
 
 
 # Mirrors TORCH_TORCHVISION_COMPAT in torchvision_compatibility_check
@@ -401,9 +385,7 @@ def test_installed_torch_torchvision_pair_is_compatible():
     )
 
 
-# ===========================================================================
 # vllm
-# ===========================================================================
 
 
 def test_vllm_guided_decoding_params_or_structured_outputs_present():
@@ -447,9 +429,7 @@ def test_vllm_aimv2_ovis_config_is_past_fix_version():
         )
 
 
-# ===========================================================================
 # huggingface_hub
-# ===========================================================================
 
 
 def test_huggingface_hub_is_offline_mode_or_hf_hub_offline_present():
@@ -477,9 +457,7 @@ def test_huggingface_hub_is_offline_mode_or_hf_hub_offline_present():
     )
 
 
-# ===========================================================================
 # torch
-# ===========================================================================
 
 
 def test_torch_nn_init_trunc_normal_exists():
@@ -494,9 +472,7 @@ def test_torch_nn_init_trunc_normal_exists():
     )
 
 
-# ===========================================================================
 # xformers
-# ===========================================================================
 
 
 def test_xformers_is_post_num_splits_key_fix_or_not_installed():
@@ -515,9 +491,7 @@ def test_xformers_is_post_num_splits_key_fix_or_not_installed():
         )
 
 
-# ===========================================================================
 # transformers (PreTrainedModel base import sanity)
-# ===========================================================================
 
 
 def test_transformers_pretrained_model_has_get_input_embeddings():
@@ -533,18 +507,14 @@ def test_transformers_pretrained_model_has_get_input_embeddings():
     )
 
 
-# ===========================================================================
 # accelerate -- ``is_X_available`` API stability used across the fixes
-# ===========================================================================
 
 
-# ===========================================================================
 # transformers LOSS_MAPPING -- patch_loss_functions() coverage
 # Regression for https://github.com/unslothai/unsloth/issues/4188:
 # Qwen3_5ForConditionalGeneration has loss_type='ForConditionalGeneration',
 # a separate LOSS_MAPPING key that was never patched, leaving the model with
 # the stock ForCausalLMLoss which does logits.float() and OOMs on <=24 GB GPUs.
-# ===========================================================================
 
 
 def _reset_loss_mapping(mapping, saved):
diff --git a/tests/test_model_registry.py b/tests/test_model_registry.py
index 3d34e783ba..bbcfdd8aa9 100644
--- a/tests/test_model_registry.py
+++ b/tests/test_model_registry.py
@@ -1,11 +1,7 @@
-"""
-
-Test model registration methods
-Checks that model registration methods work for respective models as well as all models
-The check is performed
-- by registering the models
-- checking that the instantiated models can be found on huggingface hub by querying for the model id
+"""Test model registration methods.
 
+Registers each model set and checks the registered model ids exist on the
+Hugging Face Hub.
 """
 
 from dataclasses import dataclass
diff --git a/tests/test_multi_image_grpo_chunking.py b/tests/test_multi_image_grpo_chunking.py
index 07ad95d5d7..ccd10f905a 100644
--- a/tests/test_multi_image_grpo_chunking.py
+++ b/tests/test_multi_image_grpo_chunking.py
@@ -16,7 +16,7 @@ def _read_source() -> str:
         return fh.read()
 
 
-# ---------- Per-chunk slicing fixes (cum_rows, cum_imgs, axes) ----------
+# Per-chunk slicing fixes (cum_rows, cum_imgs, axes)
 
 
 def test_cum_rows_materialized_on_cpu():
@@ -60,7 +60,7 @@ def test_image_sizes_chunked_after_branch_decision():
     )
 
 
-# ---------- Behavioral simulation of chunk math ----------
+# Behavioral simulation of chunk math
 
 
 def _simulate_chunk_indices(num_images, B):
@@ -106,7 +106,7 @@ def test_simulate_pixel_attention_mask_axis_decision():
     assert select_axis(2, 2, 2, 2, False) == "sample"
 
 
-# ---------- Zoo compatibility guard ----------
+# Zoo compatibility guard
 
 
 def test_zoo_guard_branch_present():
diff --git a/tests/test_public_api_surface.py b/tests/test_public_api_surface.py
index 50cc504749..140fda99f5 100644
--- a/tests/test_public_api_surface.py
+++ b/tests/test_public_api_surface.py
@@ -13,14 +13,10 @@
 
 """Public-API surface drift detectors for unsloth itself.
 
-Companion to tests/test_import_fixes_drift.py: that file catches drift
-in THIRD-PARTY libraries (transformers / trl / triton / peft / etc.)
-that unsloth's import_fixes patches around. This file catches drift in
-unsloth's OWN public-surface API -- the top-10 symbols and classmethods
-that the unslothai/notebooks tree (and therefore every user on Colab)
-calls. If a refactor on this repo renames FastLanguageModel.from_pretrained
-or drops one of the documented kwargs, the test fires DRIFT DETECTED
-here BEFORE the breakage reaches users.
+Companion to tests/test_import_fixes_drift.py (which catches THIRD-PARTY drift):
+this catches drift in unsloth's OWN public surface -- the top symbols and
+classmethods the unslothai/notebooks tree calls -- so a rename or dropped kwarg
+fires DRIFT DETECTED here before it reaches users.
 
 Call-site counts measured against unslothai/notebooks @ main:
   FastLanguageModel.from_pretrained   506
@@ -33,10 +29,9 @@ Call-site counts measured against unslothai/notebooks @ main:
   FastModel.from_pretrained           103
   FastModel.get_peft_model             67
 
-Mirrors the unsloth-zoo / unsloth drift-detector skeleton:
-``pytest.importorskip("unsloth")`` to gate, assert the healthy upstream
-shape, ``pytest.fail("DRIFT DETECTED: ...")`` (never ``pytest.skip``) on
-regression so the matrix cell goes red.
+Mirrors the drift-detector skeleton: gate on ``pytest.importorskip("unsloth")``,
+assert the healthy shape, and ``pytest.fail("DRIFT DETECTED: ...")`` (never skip)
+on regression so the matrix cell goes red.
 """
 
 from __future__ import annotations
@@ -70,10 +65,8 @@ def _accepts(callable_obj, kwargs: set[str]) -> tuple[bool, set[str]]:
     return (not missing), missing
 
 
-# ===========================================================================
-# FastLanguageModel: the headline class. 506 from_pretrained + 370
-# for_inference + 304 get_peft_model call sites across the notebooks.
-# ===========================================================================
+# FastLanguageModel: headline class (506 from_pretrained + 370 for_inference +
+# 304 get_peft_model call sites).
 
 
 def test_fast_language_model_class_present():
@@ -126,9 +119,7 @@ def test_fast_language_model_for_inference_callable():
         )
 
 
-# ===========================================================================
 # FastVisionModel: 183 + 176 + 99 + 60 call sites across vision notebooks.
-# ===========================================================================
 
 
 def test_fast_vision_model_class_and_methods():
@@ -165,9 +156,7 @@ def test_fast_vision_model_get_peft_model_vision_kwargs():
         )
 
 
-# ===========================================================================
-# FastModel: the modern unified entry point. 103 + 67 call sites.
-# ===========================================================================
+# FastModel: modern unified entry point. 103 + 67 call sites.
 
 
 def test_fast_model_class_and_methods():
@@ -197,9 +186,7 @@ def test_fast_model_from_pretrained_kwargs():
         )
 
 
-# ===========================================================================
 # Bf16 helper alias (renamed once already; keep both accepted).
-# ===========================================================================
 
 
 def test_is_bf16_supported_or_alias_callable():
diff --git a/tests/test_raw_text.py b/tests/test_raw_text.py
index dda8de9a5e..b930e7ab31 100644
--- a/tests/test_raw_text.py
+++ b/tests/test_raw_text.py
@@ -22,10 +22,10 @@ class MockDataset:
 
     def __getitem__(self, idx):
         if isinstance(idx, str):
-            # Allow accessing columns by name like dataset['text']
+            # Access columns by name, e.g. dataset['text']
             return self.data[idx]
         elif isinstance(idx, int):
-            # Allow accessing individual rows by index
+            # Access individual rows by index
             return {key: values[idx] for key, values in self.data.items()}
         else:
             raise TypeError(f"Invalid index type: {type(idx)}")
diff --git a/tests/test_studio_install_workspace_guard.py b/tests/test_studio_install_workspace_guard.py
index a0093adb12..7d93645ca9 100644
--- a/tests/test_studio_install_workspace_guard.py
+++ b/tests/test_studio_install_workspace_guard.py
@@ -16,12 +16,10 @@ INSTALL_PS1 = REPO_ROOT / "install.ps1"
 SETUP_PS1 = REPO_ROOT / "studio" / "setup.ps1"
 SETUP_SH = REPO_ROOT / "studio" / "setup.sh"
 
-# Stubs for helpers that the extracted install.sh guard block calls in real
-# installs (`substep` for status output, `_start_studio_venv_replacement` for
-# the rollback-managed move). The tests run the block in isolation, so we
-# stand in a minimal `mv`-based replacement that exercises the same observable
-# effect (venv directory is no longer present at $VENV_DIR after a permitted
-# cleanup) without dragging in install.sh's full rollback machinery.
+# Stubs for helpers the extracted install.sh guard block calls (`substep`,
+# `_start_studio_venv_replacement`). Tests run the block in isolation, so a
+# minimal `mv`-based replacement reproduces the observable effect (venv gone
+# from $VENV_DIR after permitted cleanup) without the full rollback machinery.
 _INSTALL_GUARD_STUBS = (
     "substep() { :; }\n"
     "_start_studio_venv_replacement() {\n"
@@ -623,11 +621,9 @@ def test_tauri_preflight_scrubs_studio_home_env():
     """All three Tauri CLI-spawn sites that lacked the scrub must now
     env_remove UNSLOTH_STUDIO_HOME and STUDIO_HOME, mirroring
     process.rs / install.rs / desktop_auth.rs / update.rs."""
-    # preflight was originally a single .rs file; PR #5341 split it into
-    # a directory of submodules (backend / managed / types / version).
-    # Read whichever shape is on disk so the guard stays valid through
-    # future reorgs as long as the scrub calls live somewhere under
-    # studio/src-tauri/src/preflight*.
+    # preflight was one .rs file; PR #5341 split it into a submodule dir. Read
+    # whichever shape is on disk so the guard survives reorgs, as long as the
+    # scrub calls live under studio/src-tauri/src/preflight*.
     preflight_root = REPO_ROOT / "studio" / "src-tauri" / "src"
     preflight_paths = [
         preflight_root / "preflight.rs",
@@ -908,9 +904,8 @@ def test_install_sh_install_id_survives_symlinked_studio_home(tmp_path):
     # Write a stub install id at the canonical location.
     valid_id = "ab12" * 16
     (studio_home / "share" / "studio_install_id").write_text(valid_id)
-    # Read it back via both the canonical and the symlinked path; both must
-    # see the SAME content (which is what makes install.sh's cat and the
-    # backend's read_text agree without any canonicalization dance).
+    # Read back via canonical and symlinked path; both must see the SAME
+    # content so install.sh's cat and the backend's read_text agree.
     raw_via_link = link / ".unsloth" / "studio" / "share" / "studio_install_id"
     raw_direct = studio_home / "share" / "studio_install_id"
     assert raw_via_link.read_text() == valid_id
diff --git a/tests/utils/aime_eval.py b/tests/utils/aime_eval.py
index 8fd0207180..6b7db2026d 100644
--- a/tests/utils/aime_eval.py
+++ b/tests/utils/aime_eval.py
@@ -1,7 +1,5 @@
 """
-AIME Dataset Evaluation Module
-
-This module provides functions to evaluate language models on the combined AIME dataset
+Evaluate language models on the combined AIME dataset
 (test2024 + test2025-I + test2025-II).
 """
 
@@ -27,7 +25,6 @@ def download_and_combine_aime_datasets(data_dir: str = "./data/aime") -> str:
     os.makedirs(data_dir, exist_ok = True)
     combined_filepath = os.path.join(data_dir, "aime.jsonl")
 
-    # Check if combined file already exists
     if os.path.exists(combined_filepath):
         print(f"Combined AIME dataset already exists at {combined_filepath}")
         return combined_filepath
@@ -44,12 +41,11 @@ def download_and_combine_aime_datasets(data_dir: str = "./data/aime") -> str:
             response = requests.get(url)
             response.raise_for_status()
 
-            # Parse each line and add source information
+            # Parse each line and tag with source + global ID
             for line_num, line in enumerate(response.text.strip().split("\n")):
                 if line.strip():
                     try:
                         data = json.loads(line)
-                        # Add source dataset information and global ID
                         data["source_dataset"] = dataset_name
                         data["original_id"] = data.get("id", line_num)
                         data["global_id"] = global_id
@@ -65,7 +61,6 @@ def download_and_combine_aime_datasets(data_dir: str = "./data/aime") -> str:
             print(f"    Error downloading {dataset_name}: {e}")
             continue
 
-    # Write combined dataset
     if all_problems:
         with open(combined_filepath, "w", encoding = "utf-8") as f:
             for problem in all_problems:
@@ -74,7 +69,6 @@ def download_and_combine_aime_datasets(data_dir: str = "./data/aime") -> str:
         print(f"✅ Combined {len(all_problems)} problems from {len(datasets)} datasets")
         print(f"   Saved to: {combined_filepath}")
 
-        # Print summary by dataset
         for dataset_name in datasets.keys():
             count = sum(1 for p in all_problems if p["source_dataset"] == dataset_name)
             print(f"   {dataset_name}: {count} problems")
@@ -88,7 +82,6 @@ def download_and_combine_aime_datasets(data_dir: str = "./data/aime") -> str:
 def load_aime_dataset(data_dir: str = "./data/aime") -> List[Dict[str, Any]]:
     """Load combined AIME dataset and format for evaluation"""
 
-    # Download and combine if needed
     filepath = download_and_combine_aime_datasets(data_dir)
 
     examples = []
@@ -99,7 +92,6 @@ def load_aime_dataset(data_dir: str = "./data/aime") -> List[Dict[str, Any]]:
                 try:
                     data = json.loads(line)
 
-                    # Format as expected by our evaluation
                     formatted_example = {
                         "global_id": data.get("global_id", line_num),
                         "original_id": data.get("original_id", data.get("id", line_num)),
@@ -128,7 +120,6 @@ def load_aime_dataset(data_dir: str = "./data/aime") -> List[Dict[str, Any]]:
 
     print(f"Loaded {len(examples)} problems from combined AIME dataset")
 
-    # Print breakdown by source
     source_counts = {}
     for example in examples:
         source = example["source_dataset"]
@@ -143,8 +134,7 @@ def load_aime_dataset(data_dir: str = "./data/aime") -> List[Dict[str, Any]]:
 def extract_aime_answer(response: str) -> str:
     """Extract numerical answer from AIME response"""
 
-    # AIME answers are integers from 0-999
-    # Look for patterns like "The answer is 123" or just standalone numbers
+    # AIME answers are integers 0-999; match "The answer is 123" etc.
     patterns = [
         r"(?:the )?(?:final )?answer is (\d{1,3})",
         r"(?:therefore|thus|so),?\s*(?:the )?(?:final )?answer is (\d{1,3})",
@@ -159,19 +149,18 @@ def extract_aime_answer(response: str) -> str:
     for pattern in patterns:
         matches = re.findall(pattern, response_lower, re.MULTILINE | re.IGNORECASE)
         if matches:
-            # Get the last match (most likely to be final answer)
-            answer = matches[-1]
+            answer = matches[-1]  # last match is most likely the final answer
             try:
                 num = int(answer)
-                if 0 <= num <= 999:  # AIME answers are in range 0-999
+                if 0 <= num <= 999:
                     return str(num)
             except ValueError:
                 continue
 
-    # If no clear pattern found, try to extract any 1-3 digit number
+    # Fallback: any 1-3 digit number, scanning from the end
     numbers = re.findall(r"\b(\d{1,3})\b", response)
     if numbers:
-        for num_str in reversed(numbers):  # Check from end
+        for num_str in reversed(numbers):
             try:
                 num = int(num_str)
                 if 0 <= num <= 999:
@@ -208,7 +197,6 @@ def evaluate_model_aime(
     print(f"Combined Dataset: test2024 + test2025-I + test2025-II")
     print(f"{'='*70}")
 
-    # Load combined AIME dataset
     try:
         eval_dataset = load_aime_dataset()
     except Exception as e:
@@ -219,7 +207,6 @@ def evaluate_model_aime(
         print("No examples found in dataset")
         return None
 
-    # Initialize tracking variables
     records = {}
     input_tokens = []
     output_tokens = []
@@ -268,11 +255,9 @@ def evaluate_model_aime(
     try:
         print(f"\n🚀 Evaluating {len(eval_dataset)} problems...")
 
-        # Main evaluation loop
         with tqdm(total = len(eval_dataset), desc = "Processing AIME problems", unit = "problem") as pbar:
             for task_id, item in enumerate(eval_dataset):
                 try:
-                    # Prepare prompt
                     prompt_text = tokenizer.apply_chat_template(
                         item["prompt"], add_generation_prompt = True, tokenize = False
                     )
@@ -287,17 +272,15 @@ def evaluate_model_aime(
                         use_tqdm = False,
                     )[0].outputs
 
-                    # Process all generated responses
                     responses = [output.text for output in outputs]
                     extracted_answers = [extract_aime_answer(response) for response in responses]
 
-                    # Calculate total output tokens
                     total_output_tokens = sum(
                         get_num_tokens(response, tokenizer) for response in responses
                     )
                     output_tokens.append(total_output_tokens)
 
-                    # Check if any answer is correct
+                    # Correct if any sample matches ground truth
                     ground_truth = item["answer"]
                     correct_responses = [ans == ground_truth for ans in extracted_answers]
                     is_correct = any(correct_responses)
@@ -306,7 +289,6 @@ def evaluate_model_aime(
                         correct_answers += 1
                         source_stats[item["source_dataset"]]["correct"] += 1
 
-                    # Store detailed record
                     records[task_id] = {
                         "global_id": item["global_id"],
                         "original_id": item["original_id"],
@@ -325,7 +307,6 @@ def evaluate_model_aime(
                         "url": item.get("url", ""),
                     }
 
-                    # Update progress
                     current_accuracy = correct_answers / (task_id + 1) * 100
                     pbar.set_postfix(
                         {
@@ -355,11 +336,10 @@ def evaluate_model_aime(
         for logger_name, level in original_levels.items():
             logging.getLogger(logger_name).setLevel(level)
 
-    # Calculate metrics
     total_problems = len(eval_dataset)
     accuracy = correct_answers / total_problems * 100
 
-    # Calculate Pass@k (probability that at least one of k samples is correct)
+    # Pass@k: probability at least one of k samples is correct
     pass_at_k_scores = []
     for record in records.values():
         if "n_correct" in record and "n_total" in record:
@@ -372,7 +352,7 @@ def evaluate_model_aime(
 
     pass_at_k = sum(pass_at_k_scores) / len(pass_at_k_scores) if pass_at_k_scores else 0
 
-    # Calculate per-source accuracies
+    # Per-source accuracies
     source_accuracies = {}
     for source, stats in source_stats.items():
         source_accuracies[source] = (
@@ -399,12 +379,10 @@ def evaluate_model_aime(
         "max_output_tokens": max(output_tokens) if output_tokens else 0,
     }
 
-    # Save results
     filename = f"aime_eval_combined_{model_type}_t{temperature}_n{n_sampling}.json"
     with open(filename, "w", encoding = "utf-8") as f:
         json.dump({"results": results, "records": records}, f, indent = 4)
 
-    # Print comprehensive summary
     print(f"\n{'='*70}")
     print(f"📊 AIME EVALUATION RESULTS - {model_type.upper()}")
     print(f"{'='*70}")
diff --git a/tests/utils/cleanup_utils.py b/tests/utils/cleanup_utils.py
index dbe5dbd556..c04523a7a4 100644
--- a/tests/utils/cleanup_utils.py
+++ b/tests/utils/cleanup_utils.py
@@ -21,7 +21,7 @@ def clear_memory(
         clear_all_caches: Clear all types of caches (recommended for memory leaks)
     """
 
-    # Save current logging levels
+    # Save logging levels to restore later
     saved_log_levels = {}
     for name, logger in logging.Logger.manager.loggerDict.items():
         if isinstance(logger, logging.Logger):
@@ -42,11 +42,11 @@ def clear_memory(
             "bnb_config",
         ]
 
-    # 1. Clear LRU caches FIRST (very important for memory leaks)
+    # Clear LRU caches first (important for memory leaks)
     if clear_all_caches:
         clear_all_lru_caches(verbose)
 
-    # 2. Delete specified variables
+    # Delete specified variables
     g = globals()
     deleted_vars = []
     for var in variables_to_clear:
@@ -57,24 +57,21 @@ def clear_memory(
     if verbose and deleted_vars:
         print(f"Deleted variables: {deleted_vars}")
 
-    # 3. Multiple garbage collection passes (important for circular references)
+    # Multiple GC passes (important for circular references)
     for i in range(3):
         collected = gc.collect()
         if verbose and collected > 0:
             print(f"GC pass {i+1}: collected {collected} objects")
 
-    # 4. CUDA cleanup
+    # CUDA cleanup
     if torch.cuda.is_available():
-        # Get memory before cleanup
         if verbose:
             mem_before = torch.cuda.memory_allocated() / 1024**3
 
         torch.cuda.empty_cache()
         torch.cuda.synchronize()
 
-        # Additional CUDA cleanup for persistent leaks
         if clear_all_caches:
-            # Reset memory stats
             torch.cuda.reset_peak_memory_stats()
             torch.cuda.reset_accumulated_memory_stats()
 
@@ -82,10 +79,8 @@ def clear_memory(
             if hasattr(torch.jit, "_state") and hasattr(torch.jit._state, "_clear_class_state"):
                 torch.jit._state._clear_class_state()
 
-            # Force another CUDA cache clear
             torch.cuda.empty_cache()
 
-        # Final garbage collection
         gc.collect()
 
         if verbose:
@@ -96,7 +91,7 @@ def clear_memory(
             if mem_before > 0:
                 print(f"Memory freed: {mem_before - mem_after:.2f} GB")
 
-    # restore original logging levels
+    # Restore original logging levels
     logging.getLogger().setLevel(root_level)
     for name, level in saved_log_levels.items():
         if name in logging.Logger.manager.loggerDict:
@@ -108,7 +103,7 @@ def clear_all_lru_caches(verbose = True):
     """Clear all LRU caches in loaded modules."""
     cleared_caches = []
 
-    # Modules to skip to avoid warnings
+    # Skip these to avoid warnings
     skip_modules = {
         "torch.distributed",
         "torchaudio",
@@ -117,20 +112,18 @@ def clear_all_lru_caches(verbose = True):
         "torchaudio.backend",
     }
 
-    # Create a static list of modules to avoid RuntimeError
+    # Static list to avoid RuntimeError during iteration
     modules = list(sys.modules.items())
 
-    # Method 1: Clear caches in all loaded modules
+    # Clear caches in all loaded modules
     for module_name, module in modules:
         if module is None:
             continue
 
-        # Skip problematic modules
         if any(module_name.startswith(skip) for skip in skip_modules):
             continue
 
         try:
-            # Look for functions with lru_cache
             for attr_name in dir(module):
                 try:
                     # Suppress warnings when checking attributes
@@ -144,11 +137,11 @@ def clear_all_lru_caches(verbose = True):
                         attr.cache_clear()
                         cleared_caches.append(f"{module_name}.{attr_name}")
                 except Exception:
-                    continue  # Skip problematic attributes
+                    continue
         except Exception:
-            continue  # Skip problematic modules
+            continue
 
-    # Method 2: Clear specific known caches
+    # Clear specific known caches
     known_caches = [
         "transformers.utils.hub.cached_file",
         "transformers.tokenization_utils_base.get_tokenizer",
@@ -169,7 +162,7 @@ def clear_all_lru_caches(verbose = True):
                     obj.cache_clear()
                     cleared_caches.append(cache_path)
         except Exception:
-            continue  # Skip problematic caches
+            continue
 
     if verbose and cleared_caches:
         print(f"Cleared {len(cleared_caches)} LRU caches")
@@ -183,7 +176,6 @@ def clear_specific_lru_cache(func):
     return False
 
 
-# Additional utility for monitoring cache sizes
 def monitor_cache_sizes():
     """Monitor LRU cache sizes across modules."""
     cache_info = []
diff --git a/tests/utils/data_utils.py b/tests/utils/data_utils.py
index 48d732b5f8..aa36a2afb4 100644
--- a/tests/utils/data_utils.py
+++ b/tests/utils/data_utils.py
@@ -57,29 +57,10 @@ def describe_param(
     as_str: bool = True,
 ) -> dict:
     """
-    Provide a statistical summary of a 2D weight matrix or tensor.
-    If as_str is True, the summary is returned as a formatted string.
-    Parameters:
-        param: torch.Tensor
-        include_l1 (bool): Whether to include the L1 norm (sum of absolute values).
-        include_l2 (bool): Whether to include the L2 norm (Frobenius norm).
-        include_infinity (bool): Whether to include the infinity norm (max absolute value).
-        as_str (bool): Whether to return the summary as a formatted string.
+    Statistical summary (shape, mean, std, min/max, percentiles) of a tensor.
 
-    Returns:
-        dict: A dictionary with the following statistics:
-              - shape: Dimensions of the matrix.
-              - mean: Average value.
-              - median: Median value.
-              - std: Standard deviation.
-              - min: Minimum value.
-              - max: Maximum value.
-              - percentile_25: 25th percentile.
-              - percentile_75: 75th percentile.
-              Additionally, if enabled:
-              - L1_norm: Sum of absolute values.
-              - L2_norm: Euclidean (Frobenius) norm.
-              - infinity_norm: Maximum absolute value.
+    Optionally includes L1/L2/infinity norms. Returns a formatted string when
+    as_str is True, else a dict.
     """
 
     param = param.float()
@@ -105,16 +86,7 @@ def describe_param(
 
 
 def format_summary(stats: dict, precision: int = 6) -> str:
-    """
-    Format the statistical summary dictionary for printing.
-
-    Parameters:
-        stats (dict): The dictionary returned by describe_param.
-        precision (int): Number of decimal places for floating point numbers.
-
-    Returns:
-        str: A formatted string representing the summary.
-    """
+    """Format the describe_param summary dict into a printable string."""
     lines = []
     for key, value in stats.items():
         if isinstance(value, float):
diff --git a/tests/utils/generate_dataset_with_none.py b/tests/utils/generate_dataset_with_none.py
index decda5d5a6..64df3f8626 100644
--- a/tests/utils/generate_dataset_with_none.py
+++ b/tests/utils/generate_dataset_with_none.py
@@ -1,28 +1,18 @@
 """
-generate_dataset_with_none.py
+Generate a small synthetic dataset with intentional None/empty turns so
+dataset_none_detect.py can be verified end-to-end.
 
-Generates a small synthetic dataset that intentionally contains None/empty
-turns so dataset_none_detect.py can be verified end-to-end.
-
-Produces three formats:
-  - chatml  (messages column, role/content turns)
-  - sharegpt (conversations column, from/value turns)
-  - alpaca  (instruction/output columns)
-
-Each format gets ~20 rows; roughly half have at least one bad turn.
-
-No heavy dependencies -- just `datasets`.
+Three formats: chatml (messages, role/content), sharegpt (conversations,
+from/value), and alpaca (instruction/output). ~20 rows each; roughly half
+have at least one bad turn. Only depends on `datasets`.
 """
 
 from datasets import Dataset
 
-# ---------------------------------------------------------------------------
 # ChatML (messages, role/content)
-# ---------------------------------------------------------------------------
 
-# NOTE: pyarrow requires uniform types in a column, so rows with messages=None
-# or messages="not a list" (P1 cases) live in a SEPARATE dataset (see
-# make_chatml_p1_dataset below) so pyarrow can infer the column type correctly.
+# pyarrow requires uniform types in a column, so messages=None / non-list (P1)
+# rows live in a SEPARATE dataset so pyarrow can infer the column type.
 
 _CHATML_ROWS = [
     # clean rows
@@ -133,10 +123,9 @@ _CHATML_ROWS = [
     {"messages": [None, {"role": "assistant", "content": "Reply"}]},  # None turn element
 ]
 
-# P1 test rows: messages is None or non-list.
-# Stored as a plain list of dicts rather than an HF Dataset because pyarrow
-# cannot mix list and non-list values in the same column.  The test runner
-# uses a lightweight mock to exercise find_none_chatml directly.
+# P1 test rows: messages is None or non-list. Stored as plain dicts (not an
+# HF Dataset) since pyarrow can't mix list and non-list values in one column;
+# the test runner mocks find_none_chatml directly.
 _CHATML_P1_ROWS = [
     {"messages": None},  # whole column None
     {"messages": "not a list"},  # wrong type
@@ -148,9 +137,7 @@ def make_chatml_p1_rows() -> list:
     return list(_CHATML_P1_ROWS)
 
 
-# ---------------------------------------------------------------------------
 # ShareGPT (conversations, from/value)
-# ---------------------------------------------------------------------------
 
 _SHAREGPT_ROWS = [
     # clean
@@ -207,9 +194,7 @@ _SHAREGPT_ROWS = [
     {"conversations": [None, {"from": "gpt", "value": "Hi"}]},
 ]
 
-# ---------------------------------------------------------------------------
 # Alpaca (instruction / output columns)
-# ---------------------------------------------------------------------------
 
 _ALPACA_ROWS = [
     # clean
diff --git a/tests/utils/ocr_eval.py b/tests/utils/ocr_eval.py
index 05c56982f8..f02cd5a26a 100644
--- a/tests/utils/ocr_eval.py
+++ b/tests/utils/ocr_eval.py
@@ -40,21 +40,16 @@ class OCRModelEvaluator:
         """
         Evaluate a model on an OCR dataset.
         """
-        # Create output directory if it doesn't exist
         os.makedirs(output_dir, exist_ok = True)
 
-        # Initialize results storage
         results = []
 
-        # Process each sample in the dataset
         for i, sample in enumerate(
             tqdm(dataset, desc = "Evaluating OCR performance", disable = not verbose)
         ):
             try:
-                # Extract components from sample
                 messages = sample["messages"]
 
-                # Get ground truth, image, and question
                 ground_truth, image, question, input_messages = self._extract_sample_components(
                     messages, i, verbose
                 )
@@ -62,16 +57,13 @@ class OCRModelEvaluator:
                 if ground_truth is None or image is None or question is None:
                     continue
 
-                # Generate model response
                 generated_response = self._generate_response(
                     model, processor, input_messages, max_new_tokens, temperature, min_p
                 )
 
-                # Calculate metrics
                 word_error = wer(ground_truth, generated_response)
                 char_error = cer(ground_truth, generated_response)
 
-                # Save individual result
                 self._save_individual_result(
                     output_dir,
                     i,
@@ -82,7 +74,6 @@ class OCRModelEvaluator:
                     char_error,
                 )
 
-                # Store results for summary
                 results.append(
                     {
                         "sample_id": i,
@@ -99,7 +90,6 @@ class OCRModelEvaluator:
                     print(f"Error processing sample {i}: {str(e)}")
                     traceback.print_exc()
 
-        # Generate summary report
         return self._generate_summary_report(results, output_dir, verbose)
 
     def _extract_sample_components(
@@ -107,24 +97,20 @@ class OCRModelEvaluator:
     ) -> Tuple[Optional[str], Optional[Any], Optional[str], List[Dict]]:
         """Extract ground truth, image, question, and input messages from sample."""
 
-        # Extract system message (if present)
         system_message = next((msg for msg in messages if msg["role"] == "system"), None)
 
-        # Extract user message with the image and question
         user_message = next((msg for msg in messages if msg["role"] == "user"), None)
         if not user_message:
             if verbose:
                 print(f"Skipping sample {sample_idx}: No user message found")
             return None, None, None, []
 
-        # Extract assistant message with ground truth
         assistant_message = next((msg for msg in messages if msg["role"] == "assistant"), None)
         if not assistant_message:
             if verbose:
                 print(f"Skipping sample {sample_idx}: No assistant message (ground truth) found")
             return None, None, None, []
 
-        # Extract ground truth text
         ground_truth = None
         for content_item in assistant_message["content"]:
             if content_item["type"] == "text":
@@ -139,7 +125,6 @@ class OCRModelEvaluator:
         # Extract image and question from user message
         image = None
         question = None
-
         for content_item in user_message["content"]:
             if content_item["type"] == "image":
                 image = content_item["image"]
@@ -156,7 +141,7 @@ class OCRModelEvaluator:
                 print(f"Skipping sample {sample_idx}: No question found in user message")
             return None, None, None, []
 
-        # Construct messages for the model input (excluding assistant message)
+        # Model input excludes the assistant message
         input_messages = []
         if system_message:
             input_messages.append(system_message)
@@ -175,15 +160,12 @@ class OCRModelEvaluator:
     ) -> str:
         """Generate response from the model."""
 
-        # Preparation for inference using Qwen's specific processing
         text = processor.apply_chat_template(
             input_messages, tokenize = False, add_generation_prompt = True
         )
 
-        # Process vision info (images/videos) from messages
         image_inputs, video_inputs = process_vision_info(input_messages)
 
-        # Create model inputs
         inputs = processor(
             text = [text],
             images = image_inputs,
@@ -193,7 +175,6 @@ class OCRModelEvaluator:
         )
         inputs = inputs.to(model.device)
 
-        # Generate response
         with torch.no_grad():
             generated_ids = model.generate(
                 **inputs,
@@ -203,12 +184,11 @@ class OCRModelEvaluator:
                 use_cache = True,
             )
 
-        # Extract only the generated part (not the input)
+        # Keep only the generated part, not the input
         generated_ids_trimmed = [
             out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
         ]
 
-        # Decode the generated text
         generated_response = processor.batch_decode(
             generated_ids_trimmed,
             skip_special_tokens = True,
@@ -247,16 +227,13 @@ class OCRModelEvaluator:
 
         df = pd.DataFrame(results)
 
-        # Calculate overall averages
         avg_wer = df["wer"].mean()
         avg_cer = df["cer"].mean()
 
-        # Save average metrics
         with open(os.path.join(output_dir, "avg_metrics.txt"), "w") as f:
             f.write(f"Average WER: {avg_wer:.4f}\n")
             f.write(f"Average CER: {avg_cer:.4f}\n")
 
-        # Save detailed results
         df.to_csv(os.path.join(output_dir, "detailed_results.csv"), index = False)
 
         if verbose:
@@ -283,7 +260,6 @@ class OCRModelEvaluator:
 
         print("\n==== MODEL COMPARISON REPORT ====")
 
-        # Create a comparison dataframe
         comparison_df = pd.DataFrame(
             {
                 "Model": list(self.model_comparison_results.keys()),
@@ -292,20 +268,17 @@ class OCRModelEvaluator:
             }
         )
 
-        # Sort by WER (best performance first)
+        # Sort by WER (best first)
         comparison_df = comparison_df.sort_values("WER")
 
-        # Display the comparison table
         print("\nComparison Table (sorted by WER):")
         print(comparison_df.to_string(index = False))
 
-        # Save the comparison table
         if save_csv:
             comparison_file = "model_comparison_results.csv"
             comparison_df.to_csv(comparison_file, index = False)
             print(f"\nComparison table saved to {comparison_file}")
 
-        # Generate a bar chart visualization
         if save_plot:
             self._create_comparison_plot(comparison_df)
 
@@ -353,9 +326,7 @@ def evaluate_ocr_model(
     output_dir = "ocr_evaluation_results",
     **kwargs,
 ):
-    """
-    Convenience function that maintains backward compatibility with the original function.
-    """
+    """Convenience wrapper kept for backward compatibility."""
     evaluator = OCRModelEvaluator()
     return evaluator.evaluate_model(model, processor, dataset, output_dir, **kwargs)
 
diff --git a/tests/utils/os_utils.py b/tests/utils/os_utils.py
index 7bf0821200..2dcd9c732e 100644
--- a/tests/utils/os_utils.py
+++ b/tests/utils/os_utils.py
@@ -60,13 +60,12 @@ def check_package_installed(package_name, package_manager = None):
 def require_package(package_name, executable_name = None):
     """Require a package to be installed, exit if not found"""
 
-    # First check if executable is in PATH (most reliable)
+    # Executable in PATH is the most reliable signal
     if executable_name:
         if shutil.which(executable_name):
             print(f"✓ {executable_name} is available")
             return
 
-    # Then check with package manager
     pm = detect_package_manager()
     is_installed = check_package_installed(package_name, pm)
 
@@ -74,7 +73,6 @@ def require_package(package_name, executable_name = None):
         print(f"✓ Package {package_name} is installed")
         return
 
-    # Package not found - show installation instructions
     print(f"❌ Error: {package_name} is not installed")
     print(f"\nPlease install {package_name} using your system package manager:")
 
diff --git a/tests/utils/perplexity_eval.py b/tests/utils/perplexity_eval.py
index bebc5ed99c..83c632a0a7 100644
--- a/tests/utils/perplexity_eval.py
+++ b/tests/utils/perplexity_eval.py
@@ -3,10 +3,9 @@ import torch
 import pandas as pd
 
 model_comparison_results = {}
-# return the perplexity of the model on the dataset
-# The perplexity is computed on each example, individually, with a sliding window for examples longer than 512 tokens.
 
 
+# Per-example perplexity, sliding window for examples longer than 512 tokens.
 def ppl_model(model, tokenizer, dataset):
     nlls = []
     max_length = 2048
@@ -21,7 +20,6 @@ def ppl_model(model, tokenizer, dataset):
             input_ids = encodings.input_ids[:, begin_loc:end_loc].to("cuda")
             target_ids = input_ids.clone()
             target_ids[:, :-trg_len] = -100
-            # Create attention mask based on pad token id
             pad_token_id = tokenizer.pad_token_id if tokenizer.pad_token_id is not None else 0
             attention_mask = (input_ids != pad_token_id).long()
             with torch.no_grad():
@@ -35,20 +33,14 @@ def ppl_model(model, tokenizer, dataset):
     return ppl
 
 
-# --------------------------------------------------------------------
+# ----------- Reporting helpers ----------- #
 
 
-## ----------- Reporting helper function ----------- ##
-
-
-# Create a simple function to add results to the comparison
 def add_to_comparison(model_name, ppl):
     """Add model results to the comparison tracker"""
     model_comparison_results[model_name] = {"ppl": ppl}
-    # return model_comparison_results
 
 
-# Create a function to print the comparison report whenever needed
 def print_model_comparison():
     """Print a comparison of all models evaluated so far"""
     if not model_comparison_results:
@@ -57,19 +49,16 @@ def print_model_comparison():
 
     print("\n==== MODEL COMPARISON REPORT ====")
 
-    # Create a comparison dataframe
     comparison_df = pd.DataFrame(
         {
             "Model": list(model_comparison_results.keys()),
-            # "Perplexity": [results["ppl"] for results in model_comparison_results.values()],
             "Perplexity": [
-                # Convert tensors to CPU and then to float if needed
+                # Tensors to CPU float if needed.
                 results["ppl"].cpu().item() if torch.is_tensor(results["ppl"]) else results["ppl"]
                 for results in model_comparison_results.values()
             ],
         }
     )
 
-    # Display the comparison table
     print("\nComparison Table:")
     print(comparison_df.to_string(index = False))
diff --git a/tests/utils/run_none_detect_tests.py b/tests/utils/run_none_detect_tests.py
index 979d3865c9..2afea75bab 100644
--- a/tests/utils/run_none_detect_tests.py
+++ b/tests/utils/run_none_detect_tests.py
@@ -21,10 +21,8 @@ from datetime import datetime
 from io import StringIO
 from pathlib import Path
 
-# Allow running from repo root without install.
-# Insert the datasets directory directly so dataset_none_detect is imported
-# as a top-level module, bypassing utils/datasets/__init__.py which pulls in
-# torch, fastapi, and other heavy studio deps not needed for this utility.
+# Import dataset_none_detect as a top-level module, bypassing
+# utils/datasets/__init__.py which pulls in torch, fastapi, and other heavy deps.
 REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(REPO_ROOT / "studio" / "backend" / "utils" / "datasets"))
 
@@ -38,9 +36,7 @@ LOG_DIR = REPO_ROOT / "tests" / "logs"
 LOG_DIR.mkdir(parents = True, exist_ok = True)
 LOG_PATH = LOG_DIR / "none_detect_results.log"
 
-# ---------------------------------------------------------------------------
 # Helpers
-# ---------------------------------------------------------------------------
 
 
 class Tee:
@@ -108,15 +104,10 @@ def assert_exact_recall(stats: dict, expected_bad: set, label: str):
     return all_caught
 
 
-# ---------------------------------------------------------------------------
 # 1. Synthetic datasets
-# ---------------------------------------------------------------------------
 
-
-# ---------------------------------------------------------------------------
 # Minimal mock so find_none_chatml can be called with hand-crafted rows that
 # pyarrow can't represent (e.g. messages=None, messages="not a list").
-# ---------------------------------------------------------------------------
 
 
 class _MockDataset:
@@ -468,9 +459,7 @@ def test_synthetic():
     return results
 
 
-# ---------------------------------------------------------------------------
 # 2. HuggingFace: peteromallet/dataclaw-peteromallet
-# ---------------------------------------------------------------------------
 
 
 def _brute_force_bad_rows(ds, fmt: str) -> set:
@@ -576,9 +565,7 @@ def test_dataclaw():
         return None
 
 
-# ---------------------------------------------------------------------------
 # 3. HuggingFace: peteromallet/my-personal-codex-data
-# ---------------------------------------------------------------------------
 
 
 def test_codex_data():
@@ -613,9 +600,7 @@ def test_codex_data():
         return None
 
 
-# ---------------------------------------------------------------------------
 # Main
-# ---------------------------------------------------------------------------
 
 
 def main():
@@ -648,9 +633,7 @@ def main():
         all_results["dataclaw"] = test_dataclaw()
         all_results["codex_data"] = test_codex_data()
 
-        # ---------------------------------------------------------------------------
         # Summary table
-        # ---------------------------------------------------------------------------
         section("SUMMARY")
         rows = [
             ("Dataset", "Format", "Total rows", "Bad rows", "Bad turns"),
diff --git a/tests/utils/test_packing.py b/tests/utils/test_packing.py
index 590419ad52..6fa6ae8d34 100644
--- a/tests/utils/test_packing.py
+++ b/tests/utils/test_packing.py
@@ -194,7 +194,7 @@ class _DummyTrainer:
                 break
             except TypeError:
                 continue
-        # Ensure attributes exist even if the constructor did not accept them
+        # Ensure attributes exist even if the constructor rejected them.
         if not hasattr(self.data_collator, "padding_free"):
             self.data_collator.padding_free = True
         if not hasattr(self.data_collator, "return_position_ids"):
diff --git a/tests/utils/test_q_galore.py b/tests/utils/test_q_galore.py
index 3a2925fca1..7248e60a93 100644
--- a/tests/utils/test_q_galore.py
+++ b/tests/utils/test_q_galore.py
@@ -104,7 +104,6 @@ class TestGaLoreProjector:
         low = proj.project(grad, step = 0)
         assert low.shape == (16, 4)
 
-        # The projection matrix should be stored as uint8
         assert proj.ortho_matrix.dtype == torch.uint8
 
     def test_quantized_projection_int4(self):
@@ -165,7 +164,7 @@ class TestQuantizationUtils:
         q, scales, zeros, shape = _quantize(w, n_bit = 8)
         w_hat = _dequantize(q, scales, zeros, shape)
 
-        # Error should be bounded by the quantization step size
+        # Error bounded by the quantization step size.
         error = (w - w_hat).abs().max()
         assert error < 0.1, f"Max error {error} exceeds threshold"
 
@@ -215,7 +214,6 @@ class TestParamGroupHelper:
     def test_param_group_separation(self):
         """GaLore vs non-GaLore params are correctly separated."""
 
-        # Create a mini-transformer-like model
         model = nn.Module()
         model.q_proj = nn.Linear(64, 64, bias = False)
         model.k_proj = nn.Linear(64, 64, bias = False)
@@ -224,15 +222,14 @@ class TestParamGroupHelper:
 
         groups = make_q_galore_param_groups(model, rank = 8, weight_quant = False)
 
-        # Should have 2 groups: galore and non-galore
+        # galore + non-galore.
         assert len(groups) == 2
 
         galore_group = [g for g in groups if "rank" in g][0]
         non_galore_group = [g for g in groups if "rank" not in g][0]
 
-        # q_proj and k_proj should be in galore group (2 params)
+        # q_proj + k_proj in galore group.
         assert len(galore_group["params"]) == 2
-        # embed and norm should be in non-galore group
         assert len(non_galore_group["params"]) == 3  # embed weight + norm weight + norm bias
 
     def test_custom_target_modules(self):
diff --git a/tests/version_compat/_fetch.py b/tests/version_compat/_fetch.py
index be96823016..9688780be5 100644
--- a/tests/version_compat/_fetch.py
+++ b/tests/version_compat/_fetch.py
@@ -1,15 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team.
 """Shared helpers for the version-compat suites: fetch a file from
-GitHub raw at a specific tag/branch, and grep for class / def / module
-symbols without ast.parse so a single non-importable line doesn't
-false-fail us. Mirrors tests/vllm_compat/test_vllm_pinned_symbols.py.
+GitHub raw at a tag/branch, and grep for class/def/module symbols
+without ast.parse so one non-importable line doesn't false-fail us.
+Mirrors tests/vllm_compat/test_vllm_pinned_symbols.py.
 
-Used by:
-  - tests/version_compat/test_trl_grpo_pinned_symbols.py
-  - tests/version_compat/test_peft_pinned_symbols.py
-  - tests/version_compat/test_sentence_transformers_pinned_symbols.py
-  - tests/version_compat/test_bitsandbytes_pinned_symbols.py
+Used by the test_*_pinned_symbols.py suites under tests/version_compat/.
 """
 
 from __future__ import annotations
@@ -23,10 +19,8 @@ import pytest
 
 
 def fetch_text(repo: str, ref: str, path: str) -> str | None:
-    """Fetch a file from GitHub raw. None on 404 (the path was renamed
-    or removed in this version, which is informational and the caller
-    decides whether that's fatal). Skips the test on transient network
-    errors so we don't make CI flaky."""
+    """Fetch a file from GitHub raw. None on 404 (caller decides if
+    fatal). Skips the test on transient network errors to avoid CI flake."""
     url = f"https://raw.githubusercontent.com/{repo}/{ref}/{path}"
     req = urllib.request.Request(url)
     token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
@@ -48,13 +42,9 @@ def has_def(
     name: str,
     kind: str = "any",
 ) -> bool:
-    """Heuristic AST-equivalent grep for `class Name`, `def name`,
-    or `Name = ...` — at any indent level. We avoid a full ast.parse
-    so a single non-importable line (e.g. `# type: ignore` after an
-    unresolved alias) doesn't false-fail us. Indented matches are
-    accepted because most class methods we want to verify live four
-    spaces in (and tests should pass for `class.method` definitions
-    just as much as for module-level `def`)."""
+    """Heuristic grep for `class Name`, `def name`, or `Name = ...` at
+    any indent level. Avoids ast.parse so one non-importable line doesn't
+    false-fail us; indented matches are accepted so class methods count too."""
     if kind in ("any", "class") and re.search(
         rf"^\s*class\s+{re.escape(name)}\b", src, re.MULTILINE
     ):
@@ -69,9 +59,8 @@ def has_def(
 
 
 def first_match(repo: str, ref: str, paths: list[str]) -> tuple[str, str] | None:
-    """Try a list of candidate paths; return (path, src) for the first
-    one that exists, or None if none do. Useful when upstream split or
-    moved a module across versions."""
+    """Return (path, src) for the first existing candidate path, else
+    None. Useful when upstream moved a module across versions."""
     for p in paths:
         src = fetch_text(repo, ref, p)
         if src is not None:
diff --git a/tests/version_compat/test_bitsandbytes_pinned_symbols.py b/tests/version_compat/test_bitsandbytes_pinned_symbols.py
index ec6e5fdaa1..247cc7e6b9 100644
--- a/tests/version_compat/test_bitsandbytes_pinned_symbols.py
+++ b/tests/version_compat/test_bitsandbytes_pinned_symbols.py
@@ -36,11 +36,8 @@ BNB_TAGS = [
 ]
 
 
-# -------------------------------------------------------------------------
-# bnb.functional: dequantize_4bit / quantize_4bit are the public 4-bit
-# surface unsloth's compiled kernels and unsloth-zoo's vllm_utils
-# bnb-loader patches all call into.
-# -------------------------------------------------------------------------
+# bnb.functional: dequantize_4bit / quantize_4bit are the public 4-bit surface
+# unsloth's compiled kernels and unsloth-zoo's vllm_utils bnb-loader call into.
 
 
 @pytest.mark.parametrize("tag", BNB_TAGS)
@@ -59,10 +56,8 @@ def test_bnb_functional_4bit(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # bnb.nn.Linear4bit / Params4bit: the two classes peft and unsloth
 # isinstance-check against. Renaming either silently breaks 4-bit LoRA.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", BNB_TAGS)
@@ -89,16 +84,12 @@ def test_bnb_nn_linear4bit_classes(tag: str):
     )
 
 
-# =========================================================================
-# Coverage extension (added 2026-05): every bnb symbol unsloth +
-# unsloth-zoo touch, derived from a full grep of both repos.
-# =========================================================================
+# Coverage extension (added 2026-05): every bnb symbol unsloth + unsloth-zoo
+# touch, derived from a full grep of both repos.
 
 
-# -------------------------------------------------------------------------
 # Top-level convenience export. unsloth/kernels/utils.py + unsloth-zoo
 # vllm_utils.py call `bnb.matmul_4bit(x, w, bias=, quant_state=)`.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", BNB_TAGS)
diff --git a/tests/version_compat/test_peft_pinned_symbols.py b/tests/version_compat/test_peft_pinned_symbols.py
index 10fc690d80..7e29aa62ac 100644
--- a/tests/version_compat/test_peft_pinned_symbols.py
+++ b/tests/version_compat/test_peft_pinned_symbols.py
@@ -45,11 +45,9 @@ PEFT_TAGS = [
 ]
 
 
-# -------------------------------------------------------------------------
 # Top-level public re-exports. unsloth/models/sentence_transformer.py:1948
 # does `from peft import LoraConfig, get_peft_model as peft_get_peft_model`.
 # unsloth_zoo's saving_utils + lora extractors hit `peft.PeftModel`.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -69,12 +67,9 @@ def test_peft_top_level_exports(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # LoraConfig at the canonical sub-module path: peft.tuners.lora.LoraConfig
-# (or peft.tuners.lora.config.LoraConfig). unsloth-zoo's LoraConfig
-# normaliser inspects it via getattr() and dataclass field
-# introspection.
-# -------------------------------------------------------------------------
+# (or peft.tuners.lora.config.LoraConfig). unsloth-zoo's normaliser inspects
+# it via getattr() and dataclass field introspection.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -92,9 +87,7 @@ def test_peft_lora_config_class(tag: str):
     assert found_in, f"{tag}: peft.tuners.lora.LoraConfig not in any of {candidates}"
 
 
-# -------------------------------------------------------------------------
 # get_peft_model: top-level helper used by sentence_transformer.py:2043.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -114,12 +107,8 @@ def test_get_peft_model_function(tag: str):
     pytest.fail(f"{tag}: def get_peft_model(...) not found in any of {candidates}")
 
 
-# -------------------------------------------------------------------------
-# LoraLayer base class: unsloth-zoo's MoE LoRA extractor walks subclasses
-# of peft.tuners.lora.LoraLayer to find quantised LoRA modules. If the
-# class is renamed or moved, the walk silently returns 0 modules (the
-# pytest tests mentioned in the audit report exercise exactly this).
-# -------------------------------------------------------------------------
+# LoraLayer base class: unsloth-zoo's MoE LoRA extractor walks subclasses of
+# peft.tuners.lora.LoraLayer. A rename/move makes the walk silently return 0.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -140,12 +129,8 @@ def test_peft_lora_layer_class(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
-# bnb-aware LoRA: peft.tuners.lora.bnb is the integration point with
-# bitsandbytes. unsloth + unsloth-zoo dispatch to this when the user
-# loads a 4-bit base. Missing this module -> 4bit LoRA silently falls
-# back to fp16 LoRA (silently bigger memory footprint).
-# -------------------------------------------------------------------------
+# bnb-aware LoRA: peft.tuners.lora.bnb is the bitsandbytes integration point.
+# Missing it -> 4bit LoRA silently falls back to fp16 (bigger memory footprint).
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -177,16 +162,12 @@ def test_peft_lora_bnb_integration(tag: str):
     )
 
 
-# =========================================================================
 # Coverage extension (added 2026-05): symbols from the 8-PR audit
 #   unsloth#5015, #5167, #5036, #4807 + unsloth-zoo#618, #596, #482, #430.
-# =========================================================================
 
 
-# -------------------------------------------------------------------------
 # 1. peft.tuners.lora.layer.VARIANT_KWARG_KEYS — added in peft 0.18.
 #    unsloth-zoo#430 injects the import into the compiled forward.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -201,12 +182,8 @@ def test_peft_variant_kwarg_keys_const(tag: str):
         )
 
 
-# -------------------------------------------------------------------------
-# 2. peft.tuners.lora.layer.ParamWrapper — peft 0.18 added the class
-#    for MoE 3D-parameter LoRA. Required attrs: parameter_name, lora_A,
-#    forward, get_base_layer. peft 0.19 also added _did_swap_in_out_features.
-#    unsloth-zoo#618 monkey-patches the MoE LoRA extractor.
-# -------------------------------------------------------------------------
+# 2. peft.tuners.lora.layer.ParamWrapper — peft 0.18 added the class for MoE
+#    3D-parameter LoRA. unsloth-zoo#618 monkey-patches the MoE LoRA extractor.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -219,17 +196,13 @@ def test_peft_param_wrapper_class(tag: str):
         f"unsloth_zoo/temporary_patches/qwen3_moe.py:43-130 + "
         f"moe_utils.py:757 ImportError (unsloth-zoo#618)"
     )
-    # Required member names — informational only; the class may
-    # legitimately move some to a base class. The bug we want to
-    # catch is full-class-removal.
+    # Member names: informational only; the real bug to catch is full removal.
     for name in ("parameter_name", "forward", "lora_A", "get_base_layer"):
         _present = name in src
 
 
-# -------------------------------------------------------------------------
-# 3. peft.tuners.lora.LoraConfig.target_parameters — peft 0.19+. Used
-#    by unsloth-zoo's MoE target-parameter extractor.
-# -------------------------------------------------------------------------
+# 3. peft.tuners.lora.LoraConfig.target_parameters — peft 0.19+. Used by
+#    unsloth-zoo's MoE target-parameter extractor.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -237,8 +210,7 @@ def test_peft_lora_config_target_parameters(tag: str):
     src = fetch_text("huggingface/peft", tag, "src/peft/tuners/lora/config.py")
     if src is None:
         pytest.skip(f"{tag}: src/peft/tuners/lora/config.py missing")
-    # Optional on 0.18.x; required from 0.19.0+. Don't fail older
-    # versions; the test is informational below the floor.
+    # Optional on 0.18.x, required from 0.19.0+
     has_it = "target_parameters" in src
     if "0.18" in tag and not has_it:
         pytest.skip(f"{tag}: target_parameters not yet introduced (peft 0.18)")
@@ -248,10 +220,8 @@ def test_peft_lora_config_target_parameters(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 4. peft.tuners.lora.model.LoraModel._create_and_replace — unsloth#4807
-#    monkey-patches this for Gemma4ClippableLinear. Signature pin.
-# -------------------------------------------------------------------------
+#    monkey-patches this for Gemma4ClippableLinear.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -266,12 +236,8 @@ def test_peft_lora_model_create_and_replace(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
-# 5. peft.utils.transformers_weight_conversion.{build_peft_weight_mapping,
-#    WeightConversion} — unsloth#5167 wraps build_peft_weight_mapping
-#    to handle WeightConversion.__init__ kwargs (distributed_operation,
-#    quantization_operation).
-# -------------------------------------------------------------------------
+# 5. peft.utils.transformers_weight_conversion.build_peft_weight_mapping —
+#    unsloth#5167 wraps it to handle WeightConversion.__init__ kwargs.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -292,10 +258,8 @@ def test_peft_transformers_weight_conversion_module(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 6. peft.utils.integrations.dequantize_module_weight — used by 3 unsloth/
-#    unsloth-zoo callsites. Function name + module path.
-# -------------------------------------------------------------------------
+#    unsloth-zoo callsites.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -314,9 +278,7 @@ def test_peft_integrations_dequantize_module_weight(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 7. peft.PeftType.LORA — used by unsloth-zoo vllm_utils.py:2520-2559.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -340,10 +302,8 @@ def test_peft_type_lora_enum(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 8. peft.utils.ModulesToSaveWrapper — both peft.utils.* and
 #    peft.utils.other.* import paths used.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
@@ -365,34 +325,27 @@ def test_peft_modules_to_save_wrapper(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
-# 9. peft.PeftModel.from_pretrained signature pin — unsloth#4807
-#    call site uses (model, name, token, revision, is_trainable,
-#    trust_remote_code).
-# -------------------------------------------------------------------------
+# 9. peft.PeftModel.from_pretrained signature pin — unsloth#4807.
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
 def test_peft_peft_model_from_pretrained_signature(tag: str):
     src = fetch_text("huggingface/peft", tag, "src/peft/peft_model.py")
     assert src is not None, f"{tag}: src/peft/peft_model.py missing"
-    # We expect `def from_pretrained` in PeftModel class. Just check
-    # the method name exists; full kwarg list is too brittle.
+    # Just check the method name; the full kwarg list is too brittle.
     assert has_def(
         src, "from_pretrained", "func"
     ), f"{tag}: PeftModel.from_pretrained missing in peft_model.py"
 
 
-# -------------------------------------------------------------------------
 # 10. peft.__version__ exported via known mechanism.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", PEFT_TAGS)
 def test_peft_version_parseable(tag: str):
     src = fetch_text("huggingface/peft", tag, "src/peft/__init__.py")
     assert src is not None
-    # Same gates as the TRL test: literal / submodule / metadata / VERSION file.
+    # Same gates as the TRL test: literal / submodule / metadata
     has_literal = bool(re.search(r'^__version__\s*=\s*["\']', src, re.MULTILINE))
     has_subimport = bool(re.search(r"^from\s+\.version\s+import\s+__version__", src, re.MULTILINE))
     has_metadata = bool(
diff --git a/tests/version_compat/test_sentence_transformers_pinned_symbols.py b/tests/version_compat/test_sentence_transformers_pinned_symbols.py
index c0cb1a6d96..87b358724b 100644
--- a/tests/version_compat/test_sentence_transformers_pinned_symbols.py
+++ b/tests/version_compat/test_sentence_transformers_pinned_symbols.py
@@ -15,9 +15,8 @@ unsloth/models/sentence_transformer.py that:
     sentence_transformers.models.transformer.Transformer; lines
     1169-1171) — at least ONE must resolve.
 
-Strategy: GitHub raw fetch + symbol grep (no pip install, runs CPU-only
-on every PR + daily cron). Versioning policy: ST is unpinned in
-unsloth/pyproject.toml; cover the most recent minors (5.x line) plus
+Strategy: GitHub raw fetch + symbol grep (no pip install, CPU-only).
+ST is unpinned in unsloth/pyproject.toml; cover recent 5.x minors plus
 `main`.
 """
 
@@ -42,10 +41,8 @@ ST_TAGS = [
 ]
 
 
-# -------------------------------------------------------------------------
 # Top-level public surface: SentenceTransformer + SentenceTransformerTrainer
 # must be importable as `from sentence_transformers import X`.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", ST_TAGS)
@@ -60,22 +57,17 @@ def test_st_top_level_exports(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # Sub-modules: Transformer / Pooling / Normalize. unsloth walks
 # `sentence_transformers.models` to introspect these (line 1016, 1206).
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", ST_TAGS)
 def test_st_models_re_exports(tag: str):
     """Transformer / Pooling / Normalize must be reachable through
-    `sentence_transformers.models`. ST 5.4 reorganised the package
-    (no more top-level `models/` dir; modules live under
-    `sentence_transformer/` and `base/modules/`), but the public
-    re-export at `sentence_transformers/__init__.py` still has to
-    surface these three so user code (and unsloth/models/sentence_transformer.py:1016,1206,1467)
-    can `from sentence_transformers.models import Transformer` (or
-    equivalently `from sentence_transformers import models`)."""
+    `sentence_transformers.models`. ST 5.4 reorganised the package, but
+    the top-level re-export must still surface these three so user code
+    (and unsloth/models/sentence_transformer.py:1016,1206,1467) can
+    `from sentence_transformers.models import Transformer`."""
     # Layout 1 (legacy &lt; 5.4): sentence_transformers/models[.py|/__init__.py].
     # Layout 2 (&gt;= 5.4): top-level __init__.py re-exports the symbols
     # plus the modules live under base/modules and sentence_transformer/.
@@ -95,14 +87,10 @@ def test_st_models_re_exports(tag: str):
         )
         return
 
-    # ST 5.4+ modular layout: classes moved under
-    #   - sentence_transformers/base/modules/transformer.py             (Transformer)
-    #   - sentence_transformers/sentence_transformer/modules/pooling.py (Pooling)
-    #   - sentence_transformers/sentence_transformer/modules/normalize.py (Normalize)
-    # Backward compatibility for `from sentence_transformers.models
-    # import X` is set up at import time via
-    # `sentence_transformers.util.deprecated_import.setup_deprecated_module_imports`
-    # called from sentence_transformers/__init__.py.
+    # ST 5.4+ modular layout: classes moved under base/modules and
+    # sentence_transformer/modules. Backward compat for
+    # `from sentence_transformers.models import X` is wired at import via
+    # setup_deprecated_module_imports in sentence_transformers/__init__.py.
     expected_paths = {
         "Transformer": [
             "sentence_transformers/base/modules/transformer.py",
@@ -142,10 +130,8 @@ def test_st_models_re_exports(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # Transformer base class: unsloth checks two alternate paths at
 # sentence_transformer.py:1169-1171. At least ONE must resolve.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", ST_TAGS)
@@ -167,20 +153,16 @@ def test_st_transformer_base_class_either_path(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # sentence_transformers.util: import_from_string + load_dir_path are the
 # two helpers unsloth.models.sentence_transformer:1177,1205 calls.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", ST_TAGS)
 def test_st_util_helpers(tag: str):
     """`sentence_transformers.util.{import_from_string, load_dir_path}` —
     used by unsloth.models.sentence_transformer:1177,1205. ST 5.4+ moved
-    util into a package; we accept either layout. We also accept the
-    function being defined in any submodule of the util package, since
-    `from sentence_transformers.util import import_from_string` works
-    when util/__init__.py re-exports."""
+    util into a package; accept either layout, or a re-export from any
+    util submodule."""
     candidates = [
         "sentence_transformers/util.py",
         "sentence_transformers/util/__init__.py",
diff --git a/tests/version_compat/test_trl_grpo_pinned_symbols.py b/tests/version_compat/test_trl_grpo_pinned_symbols.py
index ce5e2644fd..f84a4fd669 100644
--- a/tests/version_compat/test_trl_grpo_pinned_symbols.py
+++ b/tests/version_compat/test_trl_grpo_pinned_symbols.py
@@ -88,10 +88,8 @@ TRL_TAGS = [
 ]
 
 
-# -------------------------------------------------------------------------
 # HARD-import top-level: from trl import X must keep working for these.
 # unsloth/trainer.py + unsloth/models/rl.py rebind these by name.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -107,11 +105,9 @@ def test_trl_top_level_grpo_sft(tag: str):
         )
 
 
-# -------------------------------------------------------------------------
 # trl.trainer.grpo_trainer.GRPOTrainer -- the canonical class. unsloth's
 # RL patcher discovers it via `eval(f"trl.trainer.{trainer_file}.{name}")`
 # in unsloth/models/rl.py:548-594.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -141,11 +137,9 @@ def test_grpo_config_class_canonical_path(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # DataCollatorForPreference: unsloth.models.rl_replacements:318 hard-imports
 # from trl.trainer.dpo_trainer. Some old TRL versions had it in
 # trl.trainer.utils; modern ones moved to trl.trainer.dpo_trainer.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -168,10 +162,8 @@ def test_data_collator_for_preference_resolvable(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # trl.trainer.utils.pad: emitted into the GRPO compile cell as
 # _unsloth_trl_pad (rl_replacements.py:326).
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -189,11 +181,9 @@ def test_trl_trainer_utils_pad(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # trl.models.unwrap_model_for_generation -- moved between submodules
 # across releases. unsloth/models/rl.py:152-155 handles both paths.
 # Assert at least one resolves on every tag.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -219,11 +209,9 @@ def test_unwrap_model_for_generation_either_path(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # trl.experimental.openenv: gated import (rl_replacements.py:1765-1770
 # wraps in try/except). When present, must export the symbols unsloth
 # patches.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -241,11 +229,9 @@ def test_trl_experimental_openenv_gated(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # trl.generation.vllm_generation: gated import for the fast_inference
 # server mode (rl_replacements.py:1846-1848). When present, must define
 # at least one symbol unsloth patches against.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -270,11 +256,9 @@ def test_trl_generation_vllm_generation_gated(tag: str):
         )
 
 
-# -------------------------------------------------------------------------
 # Sanity: TRL's __version__ string is parseable. unsloth/models/rl.py:63
 # does `from trl import __version__ as trl_version_raw` and string-
 # matches on it.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -307,15 +291,11 @@ def test_trl_version_parseable(tag: str):
     )
 
 
-# =========================================================================
 # Coverage extension (added 2026-05): symbols / source-string contracts
 # unsloth + unsloth-zoo touch but the original suite missed.
-# =========================================================================
 
 
-# -------------------------------------------------------------------------
 # 1. trl.is_conversational — soft import in unsloth-zoo dataset_utils.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -328,10 +308,8 @@ def test_trl_is_conversational_export(tag: str):
         pytest.skip(f"{tag}: trl.is_conversational not exported (legacy TRL)")
 
 
-# -------------------------------------------------------------------------
 # 2-4. trl.trainer.sft_trainer module surface used by unsloth tokenizer
 #      utils + tests.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -351,10 +329,8 @@ def test_trl_sft_trainer_module_internals(tag: str):
         pass
 
 
-# -------------------------------------------------------------------------
 # 5-6. trl.trainer.dpo_trainer module + MODEL_FOR_VISION_2_SEQ_MAPPING_NAMES
 #      — patched by unsloth-zoo/temporary_patches/misc.py:1376-1379.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -367,11 +343,9 @@ def test_trl_dpo_trainer_module_exists(tag: str):
     assert has_def(src, "DPOTrainer", "class"), f"{tag}: class DPOTrainer missing in dpo_trainer.py"
 
 
-# -------------------------------------------------------------------------
 # 7. trl.trainer.utils.ConstantLengthDataset — soft import in
 #    unsloth-zoo/dataset_utils.py:596. Optional (TRL 0.20.0 removed it
 #    on some paths).
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -390,12 +364,10 @@ def test_trl_constant_length_dataset_optional(tag: str):
         )
 
 
-# -------------------------------------------------------------------------
 # 8. trl.models.utils.disable_gradient_checkpointing — added in TRL
 #    1.0.0+. unsloth/models/rl.py:1976-1994 uses hasattr() for gating;
 #    we still want the assertion that the symbol exists from 1.0.0
 #    onwards so a future removal gets caught.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -423,11 +395,9 @@ def test_trl_models_utils_disable_gradient_checkpointing(tag: str):
         )
 
 
-# -------------------------------------------------------------------------
 # 9. trl.import_utils + the `_*_available` cache pattern — used by
 #    unsloth/import_fixes.py:508-516 to clear cached `is_X_available`
 #    booleans so vllm-ascend imports work.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -450,11 +420,9 @@ def test_trl_import_utils_available_pattern(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 10. trl.experimental.openenv.utils generators — at least one of the
 #     two function names must exist (unsloth/models/rl_replacements.py
 #     :1775-1781 calls getattr() to find one).
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -471,12 +439,10 @@ def test_trl_openenv_utils_generators(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 11-16. GRPOTrainer required method names. unsloth/models/rl_replacements
 #        .py uses function_name == "..." dispatch keys; if a method is
 #        renamed, the patch silently doesn't apply. List of methods is
 #        the precise dispatch key set.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -508,7 +474,6 @@ def test_trl_grpo_trainer_required_methods(tag: str):
         _ = _present
 
 
-# -------------------------------------------------------------------------
 # Source-string contracts on trl/trainer/grpo_trainer.py. Each substring
 # is one half of a `function.replace(old, new)` rewrite — if the
 # substring no longer appears in TRL source, the rewrite is a no-op
@@ -516,7 +481,6 @@ def test_trl_grpo_trainer_required_methods(tag: str):
 #
 # Broken into per-version-window tests because some patterns only apply
 # to a subset of TRL minors.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -535,10 +499,8 @@ def test_trl_grpo_source_inference_mode_unwrap(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 17. KTOTrainer.get_batch_logps + the literal raise message rewriter
 #     hits.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -586,12 +548,10 @@ def test_trl_kto_get_batch_logps_signature(tag: str):
     )
 
 
-# -------------------------------------------------------------------------
 # 18. SFTTrainer.__init__ literal `dict_args.pop("push_to_hub_token")`
 #     OR our shim must short-circuit. transformers 5.0 removed this
 #     kwarg; if TRL stops emitting the bare pop, our patch becomes
 #     a no-op AND TRL itself crashes on transformers 5.0.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -606,9 +566,7 @@ def test_trl_sft_trainer_class(tag: str):
     assert has_def(src, "SFTTrainer", "class"), f"{tag}: class SFTTrainer missing"
 
 
-# -------------------------------------------------------------------------
 # 19-21. DPOTrainer methods unsloth-zoo's rl_replacements rewrites.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
@@ -641,14 +599,12 @@ def test_trl_dpo_trainer_methods(tag: str):
         _ = _present  # informational; rewriter no-ops cleanly when absent
 
 
-# -------------------------------------------------------------------------
 # 22-23. trl.trainer.grpo_trainer must IMPORT or DEFINE the helpers
 #        unsloth's source rewriters reference: profiling_context,
 #        maybe_apply_chat_template, truncate_with_protected_tokens.
 #        Either the symbol is locally defined OR imported from elsewhere
 #        in trl.* — the rewriter only needs the NAME to be in scope at
 #        the call site.
-# -------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize("tag", TRL_TAGS)
diff --git a/tests/vllm_compat/test_extended_module_imports.py b/tests/vllm_compat/test_extended_module_imports.py
index cbf6a7e301..d6d3263827 100644
--- a/tests/vllm_compat/test_extended_module_imports.py
+++ b/tests/vllm_compat/test_extended_module_imports.py
@@ -97,10 +97,8 @@ def _has_unsloth() -> bool:
     return importlib.util.find_spec("unsloth") is not None
 
 
-# -------------------------------------------------------------------------
 # Extended unsloth-zoo module list. Modules with no top-level vllm/CUDA
 # import are expected to load cleanly on a CPU spoof runner.
-# -------------------------------------------------------------------------
 
 
 _ZOO_VLLM_FREE_MODULES = [
@@ -130,11 +128,9 @@ _ZOO_VLLM_FREE_MODULES = [
 @pytest.mark.skipif(not _has_unsloth_zoo(), reason = "unsloth_zoo not installed")
 @pytest.mark.parametrize("modname", _ZOO_VLLM_FREE_MODULES)
 def test_unsloth_zoo_module_imports_under_spoof(modname: str):
-    """Each unsloth_zoo module must import cleanly on a CPU-only spoof
-    runner. Catches transformers/peft/bnb symbol drift that pins fail
-    at import time (vs runtime)."""
-    # Force fresh resolution: drops stale partial-import state from
-    # a previous module's failure.
+    """Each unsloth_zoo module must import cleanly on a CPU-only spoof runner.
+    Catches transformers/peft/bnb symbol drift that fails at import time."""
+    # Force fresh resolution: drop stale partial-import state from a prior failure
     sys.modules.pop(modname, None)
     try:
         importlib.import_module(modname)
@@ -144,10 +140,8 @@ def test_unsloth_zoo_module_imports_under_spoof(modname: str):
         )
 
 
-# -------------------------------------------------------------------------
 # Spoof correctness: _IS_MLX must remain False on a non-Mac runner
-# AND _IS_CUDA / DEVICE_TYPE must reflect the spoofed CUDA layer.
-# -------------------------------------------------------------------------
+# and _IS_CUDA / DEVICE_TYPE must reflect the spoofed CUDA layer.
 
 
 @pytest.mark.skipif(not _has_unsloth(), reason = "unsloth not installed")
@@ -163,11 +157,8 @@ def test_unsloth_is_mlx_false_under_spoof():
     )
 
 
-# -------------------------------------------------------------------------
-# unsloth.models.* — the core RL + sentence-transformer surfaces. These
-# are the entry points unsloth/__init__.py loads transitively when a
-# user does `from unsloth import FastLanguageModel`.
-# -------------------------------------------------------------------------
+# unsloth.models.* — core RL + sentence-transformer surfaces, loaded
+# transitively by `from unsloth import FastLanguageModel`.
 
 
 _UNSLOTH_CORE_MODULES = [
@@ -184,14 +175,11 @@ _UNSLOTH_CORE_MODULES = [
 @pytest.mark.skipif(not _has_unsloth(), reason = "unsloth not installed")
 @pytest.mark.parametrize("modname", _UNSLOTH_CORE_MODULES)
 def test_unsloth_core_module_imports_under_spoof(modname: str):
-    """Core unsloth modules must import on a CPU-only runner under
-    the CUDA spoof. Drift in transformers/peft/trl symbols pinned at
-    module-top crashes here BEFORE any user-visible call.
+    """Core unsloth modules must import on a CPU-only runner under the CUDA
+    spoof; module-top symbol drift crashes here before any user-visible call.
 
-    Bootstraps via `import unsloth` first, since most sub-modules
-    require the package's _gpu_init side effects. Without that, every
-    `import unsloth.models.*` raises a guard `Please restructure your
-    imports with 'import unsloth' at the top of your file.`"""
+    Bootstraps via `import unsloth` first, since most sub-modules need the
+    package's _gpu_init side effects (else an import-guard fires)."""
     try:
         import unsloth  # noqa: F401  -- triggers _gpu_init side effects
     except Exception as e:
@@ -210,11 +198,8 @@ def test_unsloth_core_module_imports_under_spoof(modname: str):
         )
 
 
-# -------------------------------------------------------------------------
-# Public API surface dump for FastLanguageModel / FastVisionModel /
-# FastModel under spoof. Asserts the surface is non-empty and that
-# the patch hooks unsloth-zoo's RL surface relies on are present.
-# -------------------------------------------------------------------------
+# Public API surface for FastLanguageModel / FastVisionModel / FastModel under
+# spoof: surface must be non-empty and the notebook-relied methods present.
 
 
 @pytest.mark.skipif(not _has_unsloth(), reason = "unsloth not installed")
@@ -229,9 +214,7 @@ def test_fast_model_class_surface_under_spoof():
             continue
         found_at_least_one = True
         public = sorted(n for n in dir(cls) if not n.startswith("_"))
-        # Notebooks rely on these methods. Loss of any one is a regression
-        # the existing api-introspect notebook job would catch a step
-        # later — but here at the import / spoof layer.
+        # Notebooks rely on these methods; loss of any one is a regression
         for method in ("from_pretrained", "get_peft_model"):
             assert method in public, (
                 f"unsloth.{cls_name}.{method} missing under spoof; "
@@ -243,12 +226,9 @@ def test_fast_model_class_surface_under_spoof():
     )
 
 
-# -------------------------------------------------------------------------
-# RL surface drill-down: GRPO, SFT, DPO classes must be reachable AND
-# the source-rewriter dispatch table must be populated. Catches the
-# scenario where unsloth.models.rl_replacements imports cleanly but
-# RL_FUNCTIONS or RL_REPLACEMENTS is silently empty.
-# -------------------------------------------------------------------------
+# RL surface drill-down: GRPO/SFT/DPO classes must be reachable and the
+# source-rewriter dispatch table populated. Catches rl_replacements importing
+# cleanly while RL_FUNCTIONS / RL_REPLACEMENTS is silently empty.
 
 
 @pytest.mark.skipif(not _has_unsloth(), reason = "unsloth not installed")
@@ -277,11 +257,8 @@ def test_unsloth_rl_replacements_dispatch_populated():
         ), f"RL_FUNCTIONS[{key!r}] is empty list; rewrites no-op"
 
 
-# -------------------------------------------------------------------------
-# unsloth-zoo compiler test_apply_fused_lm_head — exercises the actual
-# fused-LM-head emit path with a tiny fixture. Already covered as a
-# named test in compiler.py:1983; we just call it.
-# -------------------------------------------------------------------------
+# unsloth-zoo compiler test_apply_fused_lm_head — the fused-LM-head emit path
+# (named test in compiler.py:1983); we just confirm it's callable.
 
 
 @pytest.mark.skipif(not _has_unsloth_zoo(), reason = "unsloth_zoo not installed")
@@ -295,11 +272,8 @@ def test_zoo_compiler_apply_fused_lm_head_callable():
     )
 
 
-# -------------------------------------------------------------------------
-# Spot-check signature stability of FastModel.from_pretrained — every
-# notebook call site relies on these kwargs. A removed kwarg silently
-# becomes positional drift.
-# -------------------------------------------------------------------------
+# Spot-check signature stability of FastModel.from_pretrained — every notebook
+# call site relies on these kwargs; a removal becomes silent positional drift.
 
 
 @pytest.mark.skipif(not _has_unsloth(), reason = "unsloth not installed")
diff --git a/tests/vllm_compat/test_unsloth_zoo_imports.py b/tests/vllm_compat/test_unsloth_zoo_imports.py
index cc93bb904d..3f1f5a287d 100644
--- a/tests/vllm_compat/test_unsloth_zoo_imports.py
+++ b/tests/vllm_compat/test_unsloth_zoo_imports.py
@@ -1,32 +1,23 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team.
 """
-CPU-only smoke imports for the unsloth_zoo modules that interact with
-vLLM and GRPO + fast_inference=True. Asserts each module imports
-cleanly under the existing tests/_zoo_aggressive_cuda_spoof harness.
+CPU-only smoke imports for the unsloth_zoo modules touching vLLM and
+GRPO + fast_inference=True, under the tests/_zoo_aggressive_cuda_spoof
+harness.
 
-Two modules in scope are vllm-free by design (verified by the
-upstream survey: rl_replacements has zero `import vllm` lines;
-empty_model operates on already-built vllm_internals objects passed
-in). Those two MUST import on CPU with no vllm installed -- this
-file proves it.
+rl_replacements and empty_model are vllm-free by design and MUST import
+on CPU with no vllm installed -- this file proves it. The other three
+(vllm_utils, vllm_lora_request, vllm_lora_worker_manager) hard-import
+vllm and are skipped without it; test_vllm_pinned_symbols.py covers them
+statically against pinned vLLM source.
 
-The remaining three modules (vllm_utils, vllm_lora_request,
-vllm_lora_worker_manager) hard-import multiple vllm submodules at
-module top. We do not attempt to import them on a runner without
-vllm; the symbol-presence test in test_vllm_pinned_symbols.py
-covers that path against pinned vLLM source.
-
-Cross-references:
-- unsloth_zoo PRs that fixed bugs surfaced here:
+Cross-references (unsloth_zoo commits that fixed bugs surfaced here):
   e3072a23 (WorkerLoRAManager.supports_tower_connector_lora missing),
   0c95753a (_call_create_lora_manager TypeError on vLLM 0.9.x),
   2a80d543 (vLLM 0.15 LoRA manager compat),
   ec186187 (vLLM PR #30253 vllm.lora.models split),
-  e915bca1 (LoRA embeddings= arg removed; lora_extra_vocab_size
-  optional),
-  fa82dcc2 / 664e52ea (UNSLOTH_VLLM_STANDBY hard-error windows on
-  vLLM 0.10.x and 0.14.x).
+  e915bca1 (LoRA embeddings= arg removed; lora_extra_vocab_size optional),
+  fa82dcc2 / 664e52ea (UNSLOTH_VLLM_STANDBY hard-error on vLLM 0.10/0.14).
 """
 
 from __future__ import annotations
@@ -40,9 +31,9 @@ from pathlib import Path
 import pytest
 
 
-# Apply the consolidated CPU spoof at module import time, mirroring how
+# Apply the consolidated CPU spoof at import time, like
 # .github/workflows/consolidated-tests-ci.yml shims unsloth before any
-# unsloth-touching import (lines 309/417/536/626/826/1081/1586/1998).
+# unsloth-touching import.
 _SPOOF_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(_SPOOF_DIR))
 import _zoo_aggressive_cuda_spoof as _spoof  # noqa: E402
@@ -50,9 +41,8 @@ import _zoo_aggressive_cuda_spoof as _spoof  # noqa: E402
 _spoof.apply()
 
 
-# Some unsloth_zoo modules read pynvml at import for memory probes.
-# pynvml may not be installed on the runner; stub it here. Same for
-# triton (vLLM transitively expects it for kernel JIT).
+# Some unsloth_zoo modules read pynvml at import for memory probes; it may
+# not be installed on the runner, so stub it.
 def _stub_module(name: str, attrs: dict | None = None) -> None:
     if name in sys.modules:
         return
@@ -103,30 +93,24 @@ def _has_vllm() -> bool:
     return importlib.util.find_spec("vllm") is not None
 
 
-# -------------------------------------------------------------------------
 # rl_replacements: zero direct vllm imports; must import on a vllm-less
-# CPU runner. This is the GRPO + fast_inference user-facing surface.
-# -------------------------------------------------------------------------
+# CPU runner. The GRPO + fast_inference user-facing surface.
 
 
 @pytest.mark.skipif(not _has_unsloth_zoo(), reason = "unsloth_zoo not installed")
 def test_rl_replacements_imports_without_vllm():
-    """unsloth_zoo.rl_replacements must NOT pull in vllm at import time.
-    The user-facing GRPOConfig / GRPOTrainer surface depends only on the
-    use_vllm / vllm_importance_sampling_* keyword flags, which are
-    re-exported as plain Python and never touch the vllm package on a
-    fast_inference=False training run."""
+    """unsloth_zoo.rl_replacements must NOT pull in vllm at import time;
+    the GRPOConfig/GRPOTrainer surface relies only on plain-Python keyword
+    flags and never touches vllm on a fast_inference=False run."""
     sys.modules.pop("unsloth_zoo.rl_replacements", None)
     rl = importlib.import_module("unsloth_zoo.rl_replacements")
-    # If vllm WAS imported as a side-effect, the rl path on Colab without
-    # vllm installed crashes at GRPOTrainer construction. Refuse a
-    # transitive import.
+    # A transitive vllm import crashes GRPOTrainer construction on Colab.
     assert "vllm" not in sys.modules, (
         "unsloth_zoo.rl_replacements imported vllm transitively; this breaks "
         "GRPO on environments without vllm installed (the use_vllm=False path "
         "is supposed to work without vllm)."
     )
-    # Spot-check a known public surface:
+    # Spot-check a known public surface
     assert (
         hasattr(rl, "RL_REPLACEMENTS")
         or hasattr(rl, "RL_FUNCTIONS")
@@ -134,11 +118,8 @@ def test_rl_replacements_imports_without_vllm():
     ), "expected at least one GRPO-related export in rl_replacements"
 
 
-# -------------------------------------------------------------------------
 # empty_model: no vllm import either; pure builder for the
-# fast_inference=True path that creates an empty TRL/PEFT model and
-# fills it from a vLLM internals dict passed in by patch_vllm.
-# -------------------------------------------------------------------------
+# fast_inference=True path, filled from a vLLM internals dict by patch_vllm.
 
 
 @pytest.mark.skipif(not _has_unsloth_zoo(), reason = "unsloth_zoo not installed")
@@ -148,7 +129,7 @@ def test_empty_model_imports_without_vllm():
     assert (
         "vllm" not in sys.modules
     ), "unsloth_zoo.empty_model imported vllm transitively; expected to be vllm-free"
-    # Public function the GRPO + fast_inference path relies on:
+    # Public function the GRPO + fast_inference path relies on
     assert (
         hasattr(em, "create_empty_causal_lm")
         or hasattr(em, "create_empty_model")
@@ -156,11 +137,9 @@ def test_empty_model_imports_without_vllm():
     ), "expected a create_empty_* helper in empty_model"
 
 
-# -------------------------------------------------------------------------
 # vllm_lora_request / vllm_lora_worker_manager / vllm_utils: hard-import
-# vllm. Skip if vllm isn't on the runner. The pinned-symbols test below
-# covers the version compatibility statically without needing pip install.
-# -------------------------------------------------------------------------
+# vllm; skip if it isn't on the runner. The pinned-symbols test covers
+# version compatibility statically.
 
 
 @pytest.mark.skipif(
@@ -177,9 +156,8 @@ def test_vllm_lora_request_imports():
 def test_vllm_lora_worker_manager_imports():
     sys.modules.pop("unsloth_zoo.vllm_lora_worker_manager", None)
     mod = importlib.import_module("unsloth_zoo.vllm_lora_worker_manager")
-    # commit e3072a23 added supports_tower_connector_lora to handle
-    # vLLM 0.14's gpu_model_runner that calls it unconditionally on
-    # any LoRA-VLM. Assert the patched class exposes it.
+    # e3072a23 added supports_tower_connector_lora for vLLM 0.14's
+    # gpu_model_runner; assert the patched class exposes it.
     cls = getattr(mod, "WorkerLoRAManager", None)
     if cls is not None:
         assert (
diff --git a/unsloth-cli.py b/unsloth-cli.py
index 4ebc36164f..f0b386286f 100644
--- a/unsloth-cli.py
+++ b/unsloth-cli.py
@@ -3,18 +3,10 @@
 """
 🦥 Starter Script for Fine-Tuning FastLanguageModel with Unsloth
 
-This script is designed as a starting point for fine-tuning your models using unsloth.
-It includes configurable options for model loading, PEFT parameters, training arguments, 
-and model saving/pushing functionalities.
+Configurable options for model loading, PEFT, training, and saving/pushing.
+Customize the dataset loading/preprocessing and the save/push config for your case.
 
-You will likely want to customize this script to suit your specific use case 
-and requirements.
-
-Here are a few suggestions for customization:
-    - Modify the dataset loading and preprocessing steps to match your data.
-    - Customize the model saving and pushing configurations.
-
-Usage: (most of the options have valid default values this is an extended example for demonstration purposes)
+Usage (most options have sensible defaults; this is an extended example):
     python unsloth-cli.py --model_name "unsloth/llama-3-8b" --max_seq_length 8192 --dtype None --load_in_4bit \
     --r 64 --lora_alpha 32 --lora_dropout 0.1 --bias "none" --use_gradient_checkpointing "unsloth" \
     --random_state 3407 --use_rslora --per_device_train_batch_size 4 --gradient_accumulation_steps 8 \
@@ -23,10 +15,7 @@ Usage: (most of the options have valid default values this is an extended exampl
     --report_to "tensorboard" --save_model --save_path "model" --quantization_method "f16" \
     --push_model --hub_path "hf/model" --hub_token "your_hf_token"
 
-To see a full list of configurable options, use:
-    python unsloth-cli.py --help
-
-Happy fine-tuning!
+Run `python unsloth-cli.py --help` for the full list of options.
 """
 
 import argparse
@@ -103,7 +92,6 @@ def run(args):
     def load_dataset_smart(args):
         from transformers.utils import strtobool
         if args.raw_text_file:
-            # Use raw text loader
             loader = RawTextDataLoader(tokenizer, args.chunk_size, args.stride)
             dataset = loader.load_from_file(args.raw_text_file)
         elif args.dataset.endswith((".txt", ".md", ".json", ".jsonl")):
@@ -111,16 +99,14 @@ def run(args):
             loader = RawTextDataLoader(tokenizer)
             dataset = loader.load_from_file(args.dataset)
         else:
-            # Check for modelscope usage
             use_modelscope = strtobool(os.environ.get("UNSLOTH_USE_MODELSCOPE", "False"))
             if use_modelscope:
                 from modelscope import MsDataset
                 dataset = MsDataset.load(args.dataset, split = "train")
             else:
-                # Existing HuggingFace dataset logic
                 dataset = load_dataset(args.dataset, split = "train")
 
-            # Apply formatting for structured datasets
+            # Format structured datasets
             dataset = dataset.map(formatting_prompts_func, batched = True)
         return dataset
 
@@ -163,7 +149,7 @@ def run(args):
 
     # Save model
     if args.save_model:
-        # if args.quantization_method is a list, we will save the model for each quantization method
+        # If args.quantization is a list, save once per quantization method
         if args.save_gguf:
             if isinstance(args.quantization, list):
                 for quantization_method in args.quantization:
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index b723611c5a..8202195ca8 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -17,14 +17,10 @@ import os, importlib.util, platform
 os.environ["UNSLOTH_IS_PRESENT"] = "1"
 
 # ── Windows console UTF-8 safety ─────────────────────────────────────────────
-# Legacy Windows consoles use a non-UTF-8 code page (e.g. cp1252) that cannot
-# encode the emoji / box-drawing glyphs Unsloth prints, so a bare
-# print("\U0001f9a5 ...") raises UnicodeEncodeError and aborts (observed at
-# SFTTrainer init, unsloth/trainer.py). Reconfigure stdout/stderr to UTF-8 ONLY
-# on Windows and ONLY when they are not already UTF-8 -- this is a no-op when
-# PYTHONUTF8 / PYTHONIOENCODING is set (Unsloth Studio worker, modern terminals)
-# and is never touched on Linux/macOS, so it cannot change their behaviour.
-# errors="replace" guarantees we can never crash on an unencodable glyph.
+# Legacy Windows consoles (cp1252) can't encode Unsloth's emoji/box-drawing
+# glyphs and crash with UnicodeEncodeError. Force stdout/stderr to UTF-8 only on
+# Windows and only when not already UTF-8; no-op elsewhere. errors="replace"
+# guarantees we never crash on an unencodable glyph.
 if platform.system() == "Windows":
     import sys as _sys
     for _name in ("stdout", "stderr"):
@@ -38,11 +34,9 @@ if platform.system() == "Windows":
 
 
 def _is_mlx_available():
-    # Transitional import barrier: while the paired unsloth-zoo MLX runtime
-    # rollout is in flight, keep non-Apple-Silicon imports from touching
-    # unsloth_zoo here. After both PRs are released together and
-    # unsloth_zoo.mlx is guaranteed to be import-safe on GPU hosts,
-    # this helper can collapse back to the centralized zoo runtime call below.
+    # Transitional import barrier: keep non-Apple-Silicon imports from touching
+    # unsloth_zoo until unsloth_zoo.mlx is import-safe on GPU hosts. Then this
+    # can collapse back to the centralized zoo runtime call below.
     if (
         os.environ.get("UNSLOTH_FORCE_GPU_PATH", "0") == "1"
         or platform.system() != "Darwin"
@@ -68,11 +62,9 @@ if _IS_MLX:
             "Unsloth: MLX support requires `unsloth-zoo` with MLX modules. "
             "Reinstall with `pip install unsloth-zoo` or rerun install.sh."
         ) from _e
-    # The mlx.trainer / mlx.loader submodules ship with unsloth-zoo's MLX
-    # support. An older installed unsloth-zoo (e.g. from PyPI before the
-    # MLX release lands) will satisfy `import unsloth_zoo` but be missing
-    # these submodules. Surface the same friendly install hint instead of
-    # a raw ImportError on the submodule path.
+    # An older unsloth-zoo satisfies `import unsloth_zoo` but lacks the
+    # mlx.trainer / mlx.loader submodules. Surface a friendly install hint
+    # instead of a raw ImportError on the submodule path.
     try:
         from unsloth_zoo.mlx.trainer import MLXTrainer, MLXTrainingConfig
         from unsloth_zoo.mlx.loader import FastMLXModel
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 3a84b8b012..172c69c5d8 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -17,10 +17,9 @@ from packaging.version import Version
 import os, re, subprocess, inspect, functools
 import numpy as np
 
-# Log Unsloth is being used
 os.environ["UNSLOTH_IS_PRESENT"] = "1"
 
-# Check if modules that need patching are already imported
+# Modules that need patching but may already be imported
 critical_modules = ["trl", "transformers", "peft"]
 already_imported = [mod for mod in critical_modules if mod in sys.modules]
 
@@ -54,13 +53,10 @@ del torchvision_compatibility_check
 del fix_diffusers_warnings
 del fix_huggingface_hub
 
-# This check is critical because Unsloth optimizes these libraries by modifying
-# their code at import time. If they're imported first, the original (slower,
-# more memory-intensive) implementations will be used instead of Unsloth's
-# optimized versions, potentially causing OOM errors or slower training.
+# Unsloth patches these libraries at import time; if imported first, the
+# unoptimized versions run, risking OOM or slower training.
 if already_imported:
-    # stacklevel=2 makes warning point to user's import line rather than this library code,
-    # showing them exactly where to fix the import order in their script
+    # stacklevel=2 points the warning at the user's import line
     warnings.warn(
         f"WARNING: Unsloth should be imported before [{', '.join(already_imported)}] "
         f"to ensure all optimizations are applied. Your code may run slower or encounter "
@@ -70,10 +66,7 @@ if already_imported:
     )
 del already_imported, critical_modules
 
-# Unsloth currently does not work on multi GPU setups - sadly we are a 2 brother team so
-# enabling it will require much more work, so we have to prioritize. Please understand!
-# We do have a beta version, which you can contact us about!
-# Thank you for your understanding and we appreciate it immensely!
+# Multi-GPU is not yet supported (beta available on request).
 
 # Fixes https://github.com/unslothai/unsloth/issues/1266
 os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python"
@@ -178,10 +171,9 @@ patch_vllm_for_notebooks()
 patch_torchcodec_audio_decoder()
 disable_torchcodec_if_broken()
 disable_broken_wandb()
-# Must run before patch_peft_weight_converter_compatibility -- stubs the
-# transformers v5 submodules peft 0.19.x imports unconditionally, so the
-# next patch can actually wrap build_peft_weight_mapping instead of being
-# swallowed by its bare ImportError except.
+# Must run before patch_peft_weight_converter_compatibility: stubs the
+# transformers v5 submodules peft 0.19.x imports, so the next patch can wrap
+# build_peft_weight_mapping instead of being swallowed by its ImportError.
 fix_peft_transformers_weight_conversion_import()
 patch_peft_weight_converter_compatibility()
 
@@ -345,10 +337,8 @@ from unsloth_zoo.rl_environments import (
     launch_openenv,
 )
 
-# Patch TRL trainers for backwards compatibility.
-# Skipped under UNSLOTH_ALLOW_CPU=1 (CPU-only CI) because rebinding
-# trl.SFTTrainer.__init__ to a generic wrapper changes
-# inspect.getsource(SFTTrainer.__init__) and corrupts downstream
-# drift detectors that anchor on the pristine upstream source.
+# Patch TRL trainers for backwards compatibility. Skipped under
+# UNSLOTH_ALLOW_CPU=1 (CPU-only CI): rebinding trl.SFTTrainer.__init__
+# changes inspect.getsource() and corrupts downstream drift detectors.
 if os.environ.get("UNSLOTH_ALLOW_CPU", "0") != "1":
     _patch_trl_trainer()
diff --git a/unsloth/chat_templates.py b/unsloth/chat_templates.py
index 956fcb2392..b96f8cb7a0 100644
--- a/unsloth/chat_templates.py
+++ b/unsloth/chat_templates.py
@@ -1964,11 +1964,8 @@ def get_chat_template(
         elif map_eos_token and (stop_word != "eos_token"):
             logger.warning_once(f"Unsloth: Will map {stop_word} to EOS = {tokenizer.eos_token}.")
 
-            # Replaces the old EOS token with a new one.
-            # Useful for ChatML <|im_end|> for example.
-            # Usually we train 2 more tokens <|im_start|> and <|im_end|>
-            # But training the lm_head and embeddings are slow!
-            # This is a HACK!
+            # HACK: replace old EOS with a new one (e.g. ChatML <|im_end|>) to
+            # avoid the slow lm_head/embedding retraining of new tokens.
             # Idea from https://huggingface.co/cognitivecomputations/dolphin-2.6-mistral-7b-dpo-laser
 
             old_bos_token = getattr(tokenizer, "bos_token", None)
@@ -2193,18 +2190,14 @@ def to_sharegpt(
     random_state = 3407,
 ):
     """
-    Converts a dataset to ShareGPT style.
-    ShareGPT requires only 1 input and 1 output field.
-    This means one has to merge multiple columns into 1 for 1 input field.
-    Use `conversation_extension` to increase the length of each conversation by randomnly
-    selecting a few and packing them into 1.
+    Converts a dataset to ShareGPT style (1 input + 1 output field).
+    Merge multiple columns into 1 input via `merged_prompt`; use
+    `conversation_extension` to pack several convos into one.
 
     merged_prompt = "",                 Prompt to merge columns into 1 input
     merged_column_name = "instruction", Final column name for the input  field
     output_column_name = "output",      Final column name for the output field
-    remove_unused_columns = True,
-    conversation_extension = 1,         Automatically combines `conversation_extension` convos into 1
-    random_state = 3407,
+    conversation_extension = 1,         Combines this many convos into 1
     """
     if "conversations" in dataset.column_names:
         convo = dataset[0]["conversations"]
diff --git a/unsloth/dataprep/raw_text.py b/unsloth/dataprep/raw_text.py
index 3abb6df6cd..076a781d4b 100644
--- a/unsloth/dataprep/raw_text.py
+++ b/unsloth/dataprep/raw_text.py
@@ -102,11 +102,10 @@ class RawTextDataLoader:
     def create_causal_dataset(self, chunks):
         """Create dataset for causal language modeling"""
         if chunks and isinstance(chunks[0], dict):
-            # If chunks are already tokenized (dict with input_ids, attention_mask)
-            # Reorganize the data structure for Dataset.from_dict
+            # Already-tokenized chunks: reshape for Dataset.from_dict
             input_ids = [chunk["input_ids"] for chunk in chunks]
             attention_mask = [chunk["attention_mask"] for chunk in chunks]
-            # Labels are same as input_ids for causal LM training
+            # Labels == input_ids for causal LM
             labels = [list(ids) for ids in input_ids]
             return Dataset.from_dict(
                 {
@@ -116,7 +115,7 @@ class RawTextDataLoader:
                 }
             )
         else:
-            # If chunks are text strings (backward compatibility)
+            # Text strings (backward compatibility)
             return Dataset.from_dict({"text": chunks})
 
     def smart_chunk_text(
@@ -133,29 +132,26 @@ class RawTextDataLoader:
         3. Maintains context with stride overlap
         4. Returns tokenized chunks directly (more efficient) or text chunks
         """
-        # First pass: tokenize the entire text to get accurate token counts
+        # Tokenize the whole text once for accurate token counts
         tokenized = self.tokenizer(text, return_tensors = "pt", add_special_tokens = False)
         tokens = tokenized["input_ids"]
 
-        # Handle different tokenizer return formats
+        # Normalise tokenizer return formats
         if hasattr(tokens, "__len__") and len(tokens) > 0:
-            # If it's a nested structure, get the first element
             if hasattr(tokens[0], "__len__"):
                 tokens = tokens[0]
         elif isinstance(tokens, int):
-            # If tokenizer returns just a count, create a simple range
+            # Tokenizer returned a count; build a range
             tokens = list(range(tokens))
 
         if len(tokens) <= chunk_size:
-            # Text is small enough to fit in one chunk
+            # Fits in a single chunk
             if return_tokenized:
-                # Add EOS token to the tokens if available
                 eos_token_id = getattr(self.tokenizer, "eos_token_id", None)
                 if eos_token_id is not None:
                     tokens = tokens.tolist() if hasattr(tokens, "tolist") else list(tokens)
                     tokens.append(eos_token_id)
 
-                # Create attention mask
                 attention_mask = [1] * len(tokens)
                 return [{"input_ids": tokens, "attention_mask": attention_mask}]
             else:
@@ -166,25 +162,20 @@ class RawTextDataLoader:
         start_idx = 0
 
         while start_idx < len(tokens):
-            # Calculate end index for this chunk
             end_idx = min(start_idx + chunk_size, len(tokens))
-
-            # Extract tokens for this chunk
             chunk_tokens = tokens[start_idx:end_idx]
 
             if return_tokenized:
-                # Convert to list if it's a tensor
                 chunk_tokens_list = (
                     chunk_tokens.tolist() if hasattr(chunk_tokens, "tolist") else list(chunk_tokens)
                 )
 
-                # Add EOS token if it's the last chunk or chunk is complete
+                # Append EOS on the last or a full chunk
                 if end_idx == len(tokens) or len(chunk_tokens_list) == chunk_size:
                     eos_token_id = getattr(self.tokenizer, "eos_token_id", None)
                     if eos_token_id is not None:
                         chunk_tokens_list.append(eos_token_id)
 
-                # Create attention mask (all tokens are attended to)
                 attention_mask = [1] * len(chunk_tokens_list)
 
                 chunks.append({"input_ids": chunk_tokens_list, "attention_mask": attention_mask})
@@ -192,14 +183,14 @@ class RawTextDataLoader:
                 # Decode back to text (backward compatibility)
                 chunk_text = self.tokenizer.decode(chunk_tokens, skip_special_tokens = True)
 
-                # Add EOS token if it's the last chunk or chunk is complete
+                # Append EOS on the last or a full chunk
                 if end_idx == len(tokens) or len(chunk_tokens) == chunk_size:
                     eos_token = self.tokenizer.eos_token if self.tokenizer.eos_token else ""
                     chunk_text += eos_token
 
                 chunks.append(chunk_text)
 
-            # Move to next chunk with stride overlap
+            # Advance with stride overlap
             if end_idx == len(tokens):
                 break
             start_idx += chunk_size - stride
diff --git a/unsloth/dataprep/synthetic.py b/unsloth/dataprep/synthetic.py
index 9d9143254b..90021c0c8d 100644
--- a/unsloth/dataprep/synthetic.py
+++ b/unsloth/dataprep/synthetic.py
@@ -217,7 +217,7 @@ class SyntheticDataKit:
             elif dtype_val == torch.float32:
                 dtype_val = "float32"
             engine_args["dtype"] = dtype_val
-            # Convert torch.bfloat16, torch.float16, etc. to valid CLI string
+            # Convert torch dtype to valid CLI string
             if hasattr(dtype_val, "name"):
                 engine_args["dtype"] = dtype_val.name
             elif isinstance(dtype_val, str) and dtype_val.startswith("torch."):
@@ -412,7 +412,6 @@ class SyntheticDataKit:
         boundaries = np.stack((boundaries[:-1], (boundaries + self.overlap)[1:])).T
         boundaries = np.minimum(boundaries, length).tolist()
 
-        # Get extension of filename like .txt
         filename, extension = os.path.splitext(filename)
         if filename.endswith("/"):
             filename = filename[:-1]
diff --git a/unsloth/device_type.py b/unsloth/device_type.py
index 170d5541f4..0e425e2001 100644
--- a/unsloth/device_type.py
+++ b/unsloth/device_type.py
@@ -52,11 +52,8 @@ def is_hip():
 
 @functools.cache
 def get_device_type():
-    # Test-only CPU fallback. Short-circuits the detection chain so the
-    # rest of the function -- and every DEVICE_TYPE == "cuda" branch in
-    # the codebase -- behaves identically to a real CUDA host. The env
-    # var is read exactly once per process because get_device_type is
-    # @functools.cache'd, so production hosts pay no runtime cost.
+    # Test-only CPU fallback: report "cuda" so every DEVICE_TYPE == "cuda"
+    # branch behaves identically. Read once per process (function is cached).
     if os.environ.get("UNSLOTH_ALLOW_CPU", "0") == "1":
         return "cuda"
     if _IS_MLX:
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index c8be78bc3c..25f5fdb9d2 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -106,11 +106,10 @@ except Exception:
 def suppress_cuda_printf():
     """Suppress CUDA device-side printf by redirecting stdout/stderr fds to /dev/null.
 
-    CUDA device printf (eg CUTLASS "Arch conditional MMA" errors on Blackwell)
-    writes to stdout fd 1 at the C level, bypassing Python sys.stdout entirely.
-    The existing HidePrintMessage filter on sys.stderr cannot catch these since
-    they go to a different fd at a different layer. This context manager redirects
-    both fd 1 and fd 2 at the OS level, syncs CUDA, then restores them.
+    CUDA device printf (e.g. CUTLASS "Arch conditional MMA" errors on Blackwell)
+    writes to fd 1 at the C level, bypassing Python's sys.stdout, so the
+    HidePrintMessage filter can't catch it. Redirect fd 1 and 2 at the OS level,
+    sync CUDA, then restore.
     """
     sys.stdout.flush()
     sys.stderr.flush()
@@ -575,22 +574,18 @@ def check_fbgemm_gpu_version():
 
 
 def patch_enable_input_require_grads():
-    """
-    Patch transformers PreTrainedModel.enable_input_require_grads to handle vision models
-    that raise NotImplementedError from get_input_embeddings().
-
-    """
+    """Patch PreTrainedModel.enable_input_require_grads to tolerate vision models
+    that raise NotImplementedError from get_input_embeddings()."""
     import inspect
     from transformers import PreTrainedModel
 
-    # Check if the original function iterates over self.modules() instead of just returning the enable_input_require_grads
+    # Only patch the new variant that iterates over self.modules().
     # Ref: https://github.com/huggingface/transformers/pull/41993/files#diff-6b72b98c4c2dcfc6cc606843917733f5d858374fbc22a735ff483bbc0c1e63eaL1979-R1996
     try:
         original_source = inspect.getsource(PreTrainedModel.enable_input_require_grads)
     except:
         return
 
-    # Only patch if the new pattern exists (iterating over self.modules())
     if "for module in self.modules()" not in original_source:
         return
 
@@ -610,8 +605,8 @@ def patch_enable_input_require_grads():
             try:
                 input_embeddings = module.get_input_embeddings()
             except NotImplementedError:
-                # Vision models may not implement get_input_embeddings - skip them
-                # For GLM V4.6 for example, this skips only `self.visual`
+                # Vision models may not implement get_input_embeddings (e.g. GLM
+                # V4.6 skips only `self.visual`); skip them
                 continue
 
             if input_embeddings is None:
@@ -635,11 +630,10 @@ def patch_enable_input_require_grads():
 
 def _is_custom_torch_build(raw_version_str):
     """Check if a raw version string indicates a custom or source build.
-    Must operate on the raw string from importlib_version(), not the parsed
-    Version object, since our custom Version() strips local identifiers.
 
-    Standard PyTorch releases use: +cu124, +rocm6.3, +cpu, +xpu
-    Source/custom builds use: +gitXXXXXXX, +HEXHASH, or other suffixes.
+    Operates on the raw importlib_version() string (our Version() strips local
+    identifiers). Standard releases use +cu124/+rocm6.3/+cpu/+xpu; custom builds
+    use +gitXXXX or other suffixes.
     """
     if "+" not in raw_version_str:
         return False
@@ -701,13 +695,12 @@ def torchvision_compatibility_check():
         (2, 4): (0, 19),
     }
 
-    # Extract major.minor from the parsed version
     torch_release = torch_v.release
     if len(torch_release) < 2:
         return
     torch_major, torch_minor = torch_release[0], torch_release[1]
 
-    # Try known table first, then fall back to formula for forward compatibility
+    # Known table first, then the formula for forward compatibility
     required = TORCH_TORCHVISION_COMPAT.get((torch_major, torch_minor))
 
     if required is None:
@@ -1018,11 +1011,10 @@ def check_vllm_torch_sm100_compatibility():
     This check runs early (before vLLM import) to provide a helpful error message
     instead of a cryptic std::bad_alloc crash.
     """
-    # Check if vLLM is installed (without importing it)
+    # vLLM installed? (without importing it)
     if importlib.util.find_spec("vllm") is None:
         return
 
-    # Check torch version
     try:
         torch_version = Version(importlib_version("torch"))
         if torch_version >= Version("2.9.0"):
@@ -1030,7 +1022,7 @@ def check_vllm_torch_sm100_compatibility():
     except Exception:
         return  # Can't determine torch version, skip check
 
-    # Check if any CUDA GPU is SM100 (Blackwell)
+    # Any SM100 (Blackwell) GPU?
     try:
         import torch
 
@@ -1051,13 +1043,12 @@ def check_vllm_torch_sm100_compatibility():
     except Exception:
         return
 
-    # Get vLLM version for the error message
     try:
         vllm_version = importlib_version("vllm")
     except Exception:
         vllm_version = "unknown"
 
-    # Incompatible combination detected - raise helpful error
+    # Incompatible combination: raise a helpful error
     raise RuntimeError(
         f"Unsloth: Incompatible configuration detected.\n\n"
         f"  GPU: {sm100_gpu_name} (SM100 / Blackwell architecture)\n"
@@ -1085,14 +1076,13 @@ def fix_vllm_pdl_blackwell():
     if importlib.util.find_spec("vllm") is None:
         return
 
-    # Check if any CUDA GPU is SM100 (Blackwell)
+    # Any SM100 (Blackwell) GPU? Fix applies globally via env var + monkey-patch.
     try:
         import torch
 
         if not torch.cuda.is_available():
             return
 
-        # Scan all GPUs for SM100 - fix applies globally via env var and monkey-patch
         has_sm100 = False
         sm100_gpu_name = None
         for i in range(torch.cuda.device_count()):
@@ -1107,14 +1097,13 @@ def fix_vllm_pdl_blackwell():
     except Exception:
         return
 
-    # Helper to check if module spec exists
     def _spec_exists(name):
         try:
             return importlib.util.find_spec(name) is not None
         except (ImportError, OSError, ModuleNotFoundError, ValueError):
             return False
 
-    # Check if vLLM has the PDL-related modules before doing internet check
+    # PDL-related modules present?
     has_utils = _spec_exists("vllm.lora.ops.triton_ops.utils")
     has_expand_op = _spec_exists("vllm.lora.ops.triton_ops.lora_expand_op")
     has_shrink_op = _spec_exists("vllm.lora.ops.triton_ops.lora_shrink_op")
@@ -1123,7 +1112,7 @@ def fix_vllm_pdl_blackwell():
         # Old vLLM version without PDL support - nothing to patch
         return
 
-    # Check if vLLM version includes the fix
+    # vLLM version already includes the fix?
     VLLM_PDL_FIX_VERSION = "0.15.0"
     try:
         vllm_version = Version(importlib_version("vllm"))
@@ -1150,9 +1139,8 @@ def fix_vllm_pdl_blackwell():
             patched.append(name)
             patched_names.add(name)
 
-    # First, patch the source module (utils.py) where supports_pdl is defined.
-    # This is critical because supports_pdl uses @lru_cache - we must clear the
-    # cache to prevent stale cached results from the original function.
+    # Patch the source module (utils.py) where supports_pdl is defined. It uses
+    # @lru_cache, so clear the cache to avoid stale results.
     try:
         utils_module = importlib.import_module("vllm.lora.ops.triton_ops.utils")
         if hasattr(utils_module, "supports_pdl"):
@@ -1164,9 +1152,7 @@ def fix_vllm_pdl_blackwell():
     except (ImportError, ModuleNotFoundError, AttributeError):
         pass
 
-    # Also patch the consumer modules that import supports_pdl from utils.
-    # This ensures the patched function is used even if the module was already
-    # imported before this fix runs.
+    # Also patch consumer modules that imported supports_pdl before this ran.
     consumer_modules = {
         "lora_expand_op": "vllm.lora.ops.triton_ops.lora_expand_op",
         "lora_shrink_op": "vllm.lora.ops.triton_ops.lora_shrink_op",
@@ -1328,10 +1314,9 @@ def disable_broken_wandb():
             tf_integration.is_wandb_available = _wandb_false
         except (ImportError, AttributeError):
             pass
-        # Patch accelerate's is_wandb_available (used by trl/trainer/callbacks.py).
-        # Must patch both the source module AND the re-export namespace since
-        # `from accelerate.utils import is_wandb_available` reads from
-        # accelerate.utils, not accelerate.utils.imports.
+        # Patch accelerate's is_wandb_available. Patch both the source module and
+        # the re-export namespace, since `from accelerate.utils import
+        # is_wandb_available` reads accelerate.utils, not accelerate.utils.imports.
         try:
             import accelerate.utils.imports as acc_imports
             acc_imports.is_wandb_available = _wandb_false
diff --git a/unsloth/kernels/__init__.py b/unsloth/kernels/__init__.py
index d46e0f4d59..7ff472112f 100644
--- a/unsloth/kernels/__init__.py
+++ b/unsloth/kernels/__init__.py
@@ -44,7 +44,7 @@ from .fast_lora import (
     apply_lora_o,
     fast_lora_forward,
 )
-from .fp8 import *  # This step is to ensure that we patch the FbgmemFP8Linear and FP8Linear's forward functions before the execution of model creation so that this applies to compiled non fast inference models as well
+from .fp8 import *  # Patch FbgmemFP8Linear/FP8Linear forwards before model creation, so compiled non-fast-inference models are covered too
 from .utils import (
     fast_dequantize,
     fast_gemv,
diff --git a/unsloth/kernels/cross_entropy_loss.py b/unsloth/kernels/cross_entropy_loss.py
index a170ed3dcf..39446ec639 100644
--- a/unsloth/kernels/cross_entropy_loss.py
+++ b/unsloth/kernels/cross_entropy_loss.py
@@ -462,10 +462,9 @@ if (Version(torch.__version__) < Version("2.4.0")) and not hasattr(
 def patch_loss_functions(torch_compile = True):
     _patch_loss_functions(fast_cross_entropy_loss, torch_compile = torch_compile)
 
-    # Defense-in-depth sweep for LOSS_MAPPING aliases still pointing at the
-    # stock ForCausalLMLoss (e.g. ForConditionalGeneration for Qwen3.5,
-    # CsmForConditionalGeneration). unsloth_zoo also does this; remove once
-    # the floor pin moves past unslothai/unsloth-zoo#656.
+    # Redirect LOSS_MAPPING aliases still pointing at stock ForCausalLMLoss
+    # (e.g. ForConditionalGeneration for Qwen3.5, Csm...). unsloth_zoo also
+    # does this; remove once the floor pin passes unslothai/unsloth-zoo#656.
     try:
         import transformers.loss.loss_utils as _lu
         _unsloth_loss = _lu.LOSS_MAPPING.get("ForCausalLM")
diff --git a/unsloth/kernels/fast_lora.py b/unsloth/kernels/fast_lora.py
index a49a9e04e8..f5d85e8088 100644
--- a/unsloth/kernels/fast_lora.py
+++ b/unsloth/kernels/fast_lora.py
@@ -692,11 +692,8 @@ def fast_lora_forward(self, x: torch.Tensor, *args, **kwargs) -> torch.Tensor:
         pass
 
         result = self.base_layer(x, *args, **kwargs)
-        # As per Tim Dettmers, for 4bit, we need to defensively clone here.
-        # The reason is that in some cases, an error can occur that backprop
-        # does not work on a manipulated view. This issue may be solved with
-        # newer PyTorch versions but this would need extensive testing to be
-        # sure.
+        # Per Tim Dettmers: for 4bit, defensively clone -- backprop can fail on a
+        # manipulated view (may be fixed in newer PyTorch, untested).
         result = result.clone()
 
         for active_adapter in self.active_adapters:
diff --git a/unsloth/kernels/fp8.py b/unsloth/kernels/fp8.py
index 81dfe9880d..ca608fa01b 100644
--- a/unsloth/kernels/fp8.py
+++ b/unsloth/kernels/fp8.py
@@ -128,9 +128,8 @@ def act_quant_kernel(x_ptr, y_ptr, s_ptr, BLOCK_SIZE: tl.constexpr):
     offs = pid * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
     x = tl.load(x_ptr + offs).to(tl.float32)
     s = tl.max(tl.abs(x)) / 448.0
-    # For a row of all zeros, lets return zeros as is
-    # for LoRA, there are cases where dY has 0 in it and we should not let it be NaN
-    # this is a deviation from the original implementation.
+    # All-zero row: keep scale at 1 so LoRA's zero dY doesn't become NaN
+    # (a deviation from the original implementation).
     s = 1.0 if s == 0 else s
     y = x / s
     y = y.to(y_ptr.dtype.element_ty)
@@ -320,9 +319,9 @@ def torchao_block_matmul(
     return out.to(output_dtype)
 
 
-# Note that older versions of fbgemm (<=1.3.0) cause numerical imprecisions resulting in NaNs especially when X has high values in it.
-# So our preference order is fbgemm (>=1.4.0) > torchao > triton. All of these have similar outputs/losses. Never use fbgemm (<=1.3.0) for block quantized FP8 matmul.
-# This torchao FP8 matmul seems to be ~3x faster than the w8a8_block_fp8_matmul_triton. Though torchao is 15-30% slower than fbgemm implementation (on H100 GPUs).
+# fbgemm <=1.3.0 causes NaNs for high X values, so never use it for block FP8.
+# Preference: fbgemm (>=1.4.0) > torchao > triton (similar outputs/losses).
+# torchao is ~3x faster than the triton kernel but 15-30% slower than fbgemm (H100).
 fp8_block_matmul = (
     torchao_block_matmul if torchao_blockwise_gemm is not None else w8a8_block_fp8_matmul_triton
 )
@@ -333,13 +332,12 @@ class FP8BlockQuantLinear(torch.autograd.Function):
     def forward(ctx, X, weight, weight_scale):
         m, n = weight.shape
 
-        # Save original scale for backward (before any transformation)
+        # Original scale, saved for backward before any transformation
         original_weight_scale = weight_scale
 
-        # Handle per-tensor quantization: expand scalar to block scale shape
+        # Per-tensor quant: expand scalar to (ceil(m/128), ceil(n/128)) block shape
         if weight_scale.numel() == 1:
             block_size = [128, 128]
-            # Expand scalar to (ceil(m/128), ceil(n/128)) - same value for all blocks
             num_blocks_m = triton.cdiv(m, block_size[0])
             num_blocks_n = triton.cdiv(n, block_size[1])
             weight_scale = weight_scale.expand(num_blocks_m, num_blocks_n).contiguous()
@@ -362,7 +360,6 @@ class FP8BlockQuantLinear(torch.autograd.Function):
         if not weight.is_contiguous():
             weight = weight.contiguous()
 
-        # Quantize input and run FP8 matmul
         qinput, scale = act_quant(X, block_size[1])
         output = fp8_block_matmul(
             qinput,
@@ -401,23 +398,19 @@ class FbgemmFp8Linear_matmul(torch.autograd.Function):
         if weight.shape[0] == weight_scale.shape[0] and (
             weight.shape[0] % 8 == 0 and weight.shape[1] % 8 == 0
         ):
-            # Edit: The kernel seems to expect that the weight has dimensions divisible by 8. Otherwise it throws `RuntimeError: cutlass cannot implement`
-            # One thing we can do is to pad the weight and weight scale to multiple of 8 and perform a F8F8BF16 operation.
-            # I tried benchmarking that for speed but observed that dequantize+bf16 matmul is significantly faster than padding+f8f8bf16 matmul. So we'll go that route.
-            # So essentially, f8f8bf16_rowise only happens when shapes are proper (no transposes) and divisible by 8.
+            # The kernel needs weight dims divisible by 8 (else `cutlass cannot
+            # implement`). Padding + f8f8bf16 is slower than dequant + bf16 matmul,
+            # so f8f8bf16_rowwise runs only for proper, divisible-by-8 shapes.
 
-            # quantize_fp8_per_row will squash the leading dimensions, so save the desired shape here
+            # quantize_fp8_per_row squashes leading dims; save the shape first
             output_shape = (*x.shape[:-1], -1)
-            # x_quantized and x_scale are not necessarily on the same device as x, this is an issue.
-            # https://github.com/pytorch/FBGEMM/blob/e08af8539c391437f447173863df0f3f6f6f1855/fbgemm_gpu/experimental/gen_ai/src/quantize/quantize.cu#L1237C3-L1237C45
+            # x_quantized/x_scale may land on a different device than x (FBGEMM
+            # quantize.cu#L1237). Moving them here produces gibberish; move the
+            # output instead. Compute runs on weight's device regardless.
             x_quantized, x_scale = torch.ops.fbgemm.quantize_fp8_per_row(
                 x.view(-1, x.shape[-1]).contiguous(),
                 scale_ub = getattr(weight, "input_scale_ub", None),
             )
-            # moving x_quantized, x_scale here creates glibberish output ... However, if we move the output, it works
-            # x_quantized, x_scale = x_quantized.to(x.device), x_scale.to(x.device)
-
-            # The computation still happens on the device where self.weight is even if x_quantized is not on the same device as self.weight
             weight_scale_float32 = weight_scale.to(torch.float32)
 
             if not weight.is_contiguous():
@@ -429,17 +422,15 @@ class FbgemmFp8Linear_matmul(torch.autograd.Function):
                 x_quantized, weight, x_scale, weight_scale_float32, use_fast_accum = True
             )
             output = output + bias if bias is not None else output
-            # Hacky for now, we have the output to the device of x
+            # Move output back to x's device (the move-input path produced gibberish)
             output = output.to(x.device, x.dtype)
             output = output.reshape(output_shape)
             del x_quantized, x_scale
         elif (
             weight.shape[0] != weight_scale.shape[0] and weight.shape[1] == weight_scale.shape[0]
         ) or (weight.shape[0] % 8 != 0 or weight.shape[1] % 8 != 0):
-            # Either the weight/scale is transposed or its shape is not divisible by 8. Both cases, dequantizing is the preferred way.
-            # The transpose case is generally noticed in backward pass when we do dY@W instead of @W.T as we do for forward.
-            # The shape case, I noticed to happen in MLP of Qwen 2.5 VL 7B where the gate proj is of shape (3420, 1280) and 3420/8=427.5
-
+            # Transposed weight/scale (backward dY@W) or non-divisible-by-8 shape
+            # (e.g. Qwen 2.5 VL 7B gate proj 3420x1280): dequant is preferred.
             W_deq = weight_dequant(weight, weight_scale).T
             output = torch_matmul(x, W_deq)
             output = output + bias if bias is not None else output
@@ -493,8 +484,8 @@ class FP8_fbgemm_block_linear(torch.autograd.Function):
 
         if triton.cdiv(m, bs_n) != p or triton.cdiv(n, bs_k) != q:
             if triton.cdiv(m, bs_n) == q and triton.cdiv(n, bs_k) == p:
-                # weights are transposed during backward pass for training :)
-                # We transpose weight scale to counter that. Note that transposing weight would cause issues with matmul with input X
+                # Backward transposes the weight; transpose the scale to match
+                # (transposing the weight itself would break matmul with X).
                 weight_scale = weight_scale.T
             else:
                 raise ValueError(
@@ -502,10 +493,9 @@ class FP8_fbgemm_block_linear(torch.autograd.Function):
                 )
 
         xq, xs = triton_quantize_fp8_block(X, bs_m, bs_n, None)
-        ## TODO: Investigate and resolve the high divergence of this output from baseline
-        # WARNING: This causes the outputs to diverge from expected when X has high values in it.
-        # That results in the model producing gibberish, especially on longer sequences and training loss starting at high values like 8 instead of <1 ideally
-        # Please refrain from using this till this issue is resolved. This exists here just for a future headstart.
+        # TODO: WARNING - diverges from baseline for high X values, producing
+        # gibberish / high starting loss. Do not use until resolved; kept for a
+        # future headstart.
         output = torch.ops.fbgemm.f8f8bf16_blockwise(
             xq, weight.contiguous(), xs, weight_scale.contiguous(), bs_m, bs_n, bs_k
         )
@@ -540,9 +530,8 @@ def fp8_fbgemm_block_linear(
 
 
 def test_has_fbgemm():
-    # We must manually check if the faster FBGEMM works on the specific GPU
-    # For example RTX 5090 and RTX 4090 does not work
-    # Also SM100 (Blackwell B200/B100) GPUs fail with CUTLASS SM90 kernels
+    # Probe whether the faster FBGEMM works on this GPU. RTX 4090/5090 and
+    # SM100 (Blackwell B200/B100) fail with CUTLASS SM90 kernels.
     # [TODO] Investigate with TorchAO why FBGEMM fails on consumer GPUs
     M, N, K = 128, 128, 128
     xq = torch.ones(M, K, dtype = torch.float8_e4m3fn, device = "cuda")
@@ -558,8 +547,7 @@ def test_has_fbgemm():
         del out
     except Exception as e:
         error_str = str(e).lower()
-        # Catch any CUTLASS/CUDA errors and disable FBGEMM
-        # This includes MMA instruction errors, architecture mismatches, kernel launch failures, etc.
+        # Disable FBGEMM on any CUTLASS/CUDA error (MMA, arch mismatch, launch, etc.)
         cutlass_cuda_errors = (
             "cutlass",
             "cuda error",
@@ -591,15 +579,11 @@ if "UNSLOTH_HAS_FBGEMM" not in os.environ:
 try:
     import fbgemm_gpu
 
-    # Older versions cause numerical imprecisions resulting in NaNs especially when X has high values in it.
-    # This is both fast and accurate hence preferred.
-    # This makes it 15% faster than the torchao implementation.
+    # >=1.4.0 is fast and accurate (older versions NaN on high X); ~15% faster
+    # than torchao. Must probe blockwise FBGEMM since consumer GPUs fail.
     if Version(fbgemm_gpu.__version__) >= Version("1.4.0"):
-        # We must manually confirm if blockwise FBGEMM works!
-        # This check is a must for consumer grade GPUs which fail
-        # Suppress CUDA device printf during probe -- on Blackwell (SM100) GPUs,
-        # FBGEMM's CUTLASS blockwise kernel (hardcoded SM90) fires thousands of
-        # "Arch conditional MMA" lines to stdout fd 1 before aborting.
+        # Suppress CUDA printf during probe: on Blackwell (SM100), FBGEMM's
+        # SM90 CUTLASS kernel floods stdout with "Arch conditional MMA" before aborting.
         from unsloth.import_fixes import suppress_cuda_printf
         with suppress_cuda_printf():
             _has_fbgemm = test_has_fbgemm()
@@ -620,11 +604,10 @@ def fp8_linear(
     weight_scale,
     bias = None,
 ):
-    # Per-tensor quantization: single scalar scale for entire weight
-    # Block quantized FP8: 2D scale tensor with multiple columns
+    # Per-tensor (scalar scale) or block FP8 (2D scale, multiple columns)
     if weight_scale.numel() == 1 or (weight_scale.ndim == 2 and weight_scale.shape[1] > 1):
         out = fp8_block_quant_linear(X, weight, weight_scale)
-    # Row/channel quantized FP8: 2D scale with shape (n, 1)
+    # Row/channel FP8: 2D scale shaped (n, 1)
     else:
         out = fbgemm_fp8_linear(X, weight, weight_scale, bias)
     return out
diff --git a/unsloth/kernels/moe/autotune_cache.py b/unsloth/kernels/moe/autotune_cache.py
index 5756a9c416..775c67d2ab 100644
--- a/unsloth/kernels/moe/autotune_cache.py
+++ b/unsloth/kernels/moe/autotune_cache.py
@@ -29,7 +29,6 @@ import triton
 
 logger = logging.getLogger(__name__)
 
-# Global cache for kernel configurations
 _kernel_config_cache: Dict[str, Any] = {}
 _autotune_completed: Dict[str, bool] = {}
 
@@ -74,7 +73,7 @@ def load_cached_config(cache_key: str) -> Optional[Dict[str, Any]]:
         with open(cache_file, "r", encoding = "utf-8") as f:
             cached_data = json.load(f)
 
-        # Verify cache is still valid (same device, etc.)
+        # Invalidate if device capability changed
         current_device_capability = torch.cuda.get_device_capability()
         if cached_data.get("device_capability") != current_device_capability:
             logger.info("Device capability changed, invalidating cache")
@@ -158,7 +157,7 @@ def get_or_autotune_moe_kernels(
         seq_len,
     )
 
-    # 0. Check for environment variable override to DISABLE autotuning
+    # Env override to disable autotuning
     if os.environ.get("UNSLOTH_MOE_DISABLE_AUTOTUNE", "0") == "1":
         logger.info(
             f"UNSLOTH_MOE_DISABLE_AUTOTUNE=1: Using Heuristic (Safe) MoE kernel configs for SM{device_capability[0]}{device_capability[1]}"
@@ -172,7 +171,7 @@ def get_or_autotune_moe_kernels(
     if not force_autotune:
         cached_data = load_cached_config(cache_key)
         if cached_data is not None:
-            # Reconstruct config objects from cached data
+            # Reconstruct config objects from cache
             try:
                 from .grouped_gemm.kernels.tuning import (
                     KernelConfigForward,
@@ -190,7 +189,6 @@ def get_or_autotune_moe_kernels(
             except Exception as e:
                 logger.warning(f"Failed to reconstruct cached configs: {e}")
 
-    # Run autotuning
     if cache_key in _autotune_completed and not force_autotune:
         logger.info(f"Autotuning already completed for: {cache_key}")
         return _kernel_config_cache[cache_key]
@@ -205,7 +203,6 @@ def get_or_autotune_moe_kernels(
             num_experts, hidden_dim, intermediate_dim, top_k, dtype, seq_len
         )
 
-        # Cache the results
         _kernel_config_cache[cache_key] = configs
         _autotune_completed[cache_key] = True
 
@@ -246,18 +243,13 @@ def _run_moe_autotuning(
 ) -> Tuple[Any, Any, Any]:
     """Run the actual auto-tuning for MoE kernels."""
 
-    # Create dummy inputs for tuning
     device = "cuda"
-    # Use a fixed, safe number of tokens for autotuning to avoid OOMs and dependency on seq_len
-    # 4096 is standard for finding good kernels without consuming 10GB+ VRAM
-    # We ignore the passed seq_len for the actual allocation to satisfy user request
+    # Fixed token count avoids OOMs and seq_len dependency; we ignore the passed seq_len here
     num_tokens = 4096
     total_tokens = num_tokens * top_k
 
-    # Create dummy tensors
     hidden_states = torch.randn(num_tokens, hidden_dim, device = device, dtype = dtype)
 
-    # Create dummy weights
     gate_up_weights = torch.randn(
         num_experts, 2 * intermediate_dim, hidden_dim, device = device, dtype = dtype
     )
@@ -265,10 +257,10 @@ def _run_moe_autotuning(
         num_experts, hidden_dim, intermediate_dim, device = device, dtype = dtype
     )
 
-    # Create dummy routing data
+    # Dummy routing data
     m_sizes = torch.randint(1, total_tokens // num_experts + 1, (num_experts,), device = device)
     m_sizes = m_sizes * (total_tokens // m_sizes.sum().item())
-    # Adjust to ensure exact total
+    # Adjust to exact total
     diff = total_tokens - m_sizes.sum().item()
     if diff != 0:
         m_sizes[0] += diff
@@ -276,8 +268,7 @@ def _run_moe_autotuning(
     gather_indices = torch.arange(total_tokens, device = device)
     torch.randperm(total_tokens, out = gather_indices)
 
-    # Autotune forward kernel - use the interface function with autotune=True
-    # This properly invokes the kernel and lets triton handle the autotuning
+    # Autotune via the interface function with autotune=True (lets triton tune)
     from .grouped_gemm.interface import (
         grouped_gemm_forward,
         grouped_gemm_dX,
@@ -295,7 +286,6 @@ def _run_moe_autotuning(
     )
 
     logger.info("Autotuning forward kernel (first GEMM)...")
-    # Run with autotune=True to trigger autotuning
     _ = grouped_gemm_forward(
         X = hidden_states,
         W = gate_up_weights,
@@ -308,7 +298,6 @@ def _run_moe_autotuning(
     )
     triton_config_fwd = _autotuned_grouped_gemm_forward_kernel.best_config
 
-    # Convert triton.Config to KernelConfigForward
     config_fwd = KernelConfigForward(
         BLOCK_SIZE_M = triton_config_fwd.kwargs["BLOCK_SIZE_M"],
         BLOCK_SIZE_N = triton_config_fwd.kwargs["BLOCK_SIZE_N"],
@@ -335,7 +324,6 @@ def _run_moe_autotuning(
     )
     triton_config_bwd_dx = _autotuned_grouped_gemm_dX_kernel.best_config
 
-    # Convert triton.Config to KernelConfigBackward_dX
     config_bwd_dx = KernelConfigBackward_dX(
         BLOCK_SIZE_M = triton_config_bwd_dx.kwargs["BLOCK_SIZE_M"],
         BLOCK_SIZE_N = triton_config_bwd_dx.kwargs["BLOCK_SIZE_N"],
@@ -361,7 +349,6 @@ def _run_moe_autotuning(
     )
     triton_config_bwd_dw = _autotuned_grouped_gemm_dW_kernel.best_config
 
-    # Convert triton.Config to KernelConfigBackward_dW
     config_bwd_dw = KernelConfigBackward_dW(
         BLOCK_SIZE_M = triton_config_bwd_dw.kwargs["BLOCK_SIZE_M"],
         BLOCK_SIZE_N = triton_config_bwd_dw.kwargs["BLOCK_SIZE_N"],
diff --git a/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py b/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
index a5ea4a4e71..ce62701240 100644
--- a/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
+++ b/unsloth/kernels/moe/benchmark/benchmark_fused_moe.py
@@ -49,9 +49,7 @@ def run_benchmark_forward(
     kernel_config_fwd: KernelConfigForward = None,
     bs: int = 1,
 ):
-    torch.manual_seed(
-        SEED
-    )  # Should not be needed when running using pytest -- autouse fixture in conftest.py
+    torch.manual_seed(SEED)  # Redundant under pytest (autouse fixture in conftest.py)
     device = "cuda"
     hidden_size = config.hidden_size
 
@@ -89,9 +87,7 @@ def run_benchmark_backward(
     dtype: torch.dtype,
     bs = 1,
 ):
-    torch.manual_seed(
-        SEED
-    )  # Should not be needed when running using pytest -- autouse fixture in conftest.py
+    torch.manual_seed(SEED)  # Redundant under pytest (autouse fixture in conftest.py)
     device = "cuda"
     hidden_size = config.hidden_size
 
@@ -279,13 +275,13 @@ if __name__ == "__main__":
     )
     parser.add_argument(
         "--use_tma_load_w", action = "store_true"
-    )  # No need to specify, will automatically parametrize these for each kernel config
+    )  # Auto-parametrized per kernel config; no need to specify
     parser.add_argument(
         "--use_tma_load_x", action = "store_true"
-    )  # No need to specify, will automatically parametrize these for each kernel config
+    )  # Auto-parametrized per kernel config; no need to specify
     parser.add_argument(
         "--use_tma_load_dy", action = "store_true"
-    )  # No need to specify, will automatically parametrize these for each kernel config
+    )  # Auto-parametrized per kernel config; no need to specify
     parser.add_argument(
         "--mode",
         type = str,
@@ -321,9 +317,9 @@ if __name__ == "__main__":
         end_time = time.time()
         print(f"Total time: {end_time - start_time:.4f} seconds")
 
-    # NOTE: better to use autotuner for now, since the MoE block needs 2 different kernel configs for forward (2 grouped gemms, gate_up_proj and down_proj)
-    # and the backward pass needs 4 different kernel configs (2 grouped gemms each for dW and dX)
-    # The benchmark only supports 1 kernel config at a time so the same config will be used for both grouped gemms, which is suboptimal.
+    # NOTE: prefer the autotuner for now. The MoE block needs 2 forward
+    # configs (gate_up_proj, down_proj) and 4 backward (dW + dX each); this
+    # benchmark only supports 1 config at a time, so it's suboptimal here.
     else:
         assert False, "Use autotune for now"
         kernel_configs = create_kernel_configs(args, args.permute_x, args.permute_y)
diff --git a/unsloth/kernels/moe/grouped_gemm/interface.py b/unsloth/kernels/moe/grouped_gemm/interface.py
index 86b1558ff9..a404b726dc 100644
--- a/unsloth/kernels/moe/grouped_gemm/interface.py
+++ b/unsloth/kernels/moe/grouped_gemm/interface.py
@@ -26,10 +26,8 @@ from .kernels.tuning import (
 )
 
 logger = logging.getLogger(__name__)
-# Set formatter to include timestamp, pathname and lineno
 formatter = logging.Formatter("%(asctime)s::%(levelname)s,%(pathname)s:%(lineno)d:: %(message)s")
 
-# Add console handler
 ch = logging.StreamHandler()
 ch.setFormatter(formatter)
 logger.addHandler(ch)
@@ -45,7 +43,7 @@ def _check_tma_support():
     import triton.language as tl
 
     gpu_supports_tma = torch.cuda.get_device_capability()[0] >= 9
-    # Check for both old experimental and new stable API names
+    # Support both old experimental and new stable API names
     triton_has_tma_api = hasattr(tl, "make_tensor_descriptor") or hasattr(
         tl, "_experimental_make_tensor_descriptor"
     )
@@ -62,23 +60,18 @@ def supports_tma():
     return _SUPPORTS_TMA
 
 
-# Helper to support allow_in_graph
 try:
     from torch.compiler import allow_in_graph
 except ImportError:
     from torch._dynamo import allow_in_graph
 
 
-# Helper to detect if we're in tracing/compilation mode
 def _is_tracing(*tensors):
     """
-    Check if tensors are fake tensors used during torch.compile tracing.
-    During tracing, tensors are FakeTensor/FunctionalTensor and we can't run Triton kernels.
-    During execution, tensors are real Tensors and we MUST run the kernels.
+    True if tensors are fake tensors used during torch.compile tracing (Triton can't run).
 
-    NOTE: We do NOT use torch.compiler.is_compiling() because it returns True
-    during both tracing AND execution. We only want to skip kernels during tracing
-    when tensors are actually fake.
+    NOTE: We do NOT use torch.compiler.is_compiling() because it returns True during both
+    tracing AND execution; we only want to skip kernels during tracing on fake tensors.
     """
     for t in tensors:
         name = type(t).__name__
@@ -129,9 +122,9 @@ def grouped_gemm_forward(
     permute_x: bool = False,
     permute_y: bool = False,
     fuse_mul_post: bool = False,
-    # Autotuning - manual kernel params will be ignored if autotune is True
+    # Autotuning -- overrides manual kernel params when True
     autotune: bool = False,
-    # Kernel tuning params if not autotuning -- NOTE: these params need to be tuned, otherwise performance will be poor
+    # Kernel tuning params (must be tuned, else poor performance)
     BLOCK_SIZE_M: int = 32,
     BLOCK_SIZE_N: int = 32,
     BLOCK_SIZE_K: int = 32,
@@ -140,7 +133,7 @@ def grouped_gemm_forward(
     use_tma_load_w: bool = False,
     use_tma_load_x: bool = False,
     use_tma_store: bool = False,
-    # software pipelining -- set to True for now, won't impact until loop is re-written
+    # software pipelining; no effect until loop is re-written
     flatten: bool = True,
     # debugging
     debug: bool = False,
@@ -829,9 +822,7 @@ def check_valid_config_fwd(
     fuse_mul_post,
     is_first_gemm,
 ):
-    """
-    Check if the configuration is valid for the forward pass.
-    """
+    """Check if the configuration is valid for the forward pass."""
     is_second_gemm = not is_first_gemm
 
     assert not (permute_x and permute_y), "Cannot permute both X and Y"
@@ -855,9 +846,7 @@ def check_valid_config_bwd_dW(
     fuse_mul_post,
     is_first_gemm,
 ):
-    """
-    Check if the configuration is valid for the backward pass of dW.
-    """
+    """Check if the configuration is valid for the backward pass of dW."""
     is_second_gemm = not is_first_gemm
     if fuse_mul_post:
         assert False, "Cannot fuse_mul is not supported for backward pass"
@@ -876,9 +865,7 @@ def check_valid_config_bwd_dX(
     fuse_mul_post,
     is_first_gemm,
 ):
-    """
-    Check if the configuration is valid for the backward pass of dW.
-    """
+    """Check if the configuration is valid for the backward pass of dW."""
     is_second_gemm = not is_first_gemm
     if fuse_mul_post:
         assert False, "Cannot fuse_mul is not supported for backward pass"
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py b/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
index 7c1b25e234..bea59a4548 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/autotuning.py
@@ -59,9 +59,8 @@ def _triton_supports_tma():
     )
 
 
-# Precompute at module import
-# NOTE: TMA is disabled for now due to compatibility issues with permute_x/permute_y settings
-# in the MoE grouped GEMM forward/backward passes. Re-enable once these are resolved.
+# TMA disabled for now: incompatible with permute_x/permute_y in the MoE
+# grouped GEMM passes. Re-enable once resolved.
 _TRITON_HAS_TMA = False  # _triton_supports_tma()
 
 
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/backward.py b/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
index 8c3c8fd13e..b78ea58bd0 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/backward.py
@@ -128,9 +128,8 @@ def _grouped_gemm_dX_kernel(
                     block_shape = [BLOCK_SIZE_M, BLOCK_SIZE_K],
                 )
 
-            # Lower bound and upper bound are defined relative to the total tiles processed so far
-            # This ensures that we are only processing tiles for the current expert group AND
-            # we never exceed the total number of tiles for all expert groups
+            # Bounds are relative to tiles processed so far, so we only handle
+            # this expert's tiles and never exceed the total across experts.
             while tidx >= processed_tiles and tidx < (processed_tiles + num_tiles_per_expert):
                 group_index = tidx - processed_tiles
 
diff --git a/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py b/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
index c1962c1116..35d6ff7504 100644
--- a/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
+++ b/unsloth/kernels/moe/grouped_gemm/kernels/tuning.py
@@ -1,9 +1,7 @@
 # SPDX-License-Identifier: GNU Affero General Public License v3.0
 # Copyright 2023-present the Unsloth team. All rights reserved.
 
-"""
-Manual tuning utils
-"""
+"""Manual tuning utils."""
 
 from collections import OrderedDict
 from dataclasses import asdict, dataclass, fields
@@ -258,7 +256,6 @@ class TritonTuningContext:
         self.success = True
 
     def __enter__(self):
-        # Setup code can be added here if needed
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py b/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
index 863765b0b8..a1d94d2c7d 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/layers/llama4_moe.py
@@ -189,13 +189,13 @@ class Llama4GroupedGemmTextMoe(Llama4TextMoe):
             hidden_states = hidden_states.sum(dim = 1)
         hidden_states_after_weight_merge = hidden_states.view(-1, hidden_dim)
 
-        # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
-        # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
+        # Token counts per expert + gather indices (token->expert order).
+        # Auxiliary structs; not recorded in the autograd graph.
         token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
             selected_experts
         )
 
-        # 2. Permute tokens from token order to expert order
+        # Permute tokens into expert order
         hidden_states = permute(hidden_states_after_weight_merge, gather_indices, self.top_k)
         assert hidden_states.shape == (total_tokens, hidden_dim)
 
@@ -365,13 +365,13 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
             hidden_states = hidden_states.sum(dim = 1)
         hidden_states = hidden_states.view(-1, hidden_dim)
 
-        # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
-        # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
+        # Token counts per expert + gather indices (token->expert order).
+        # Auxiliary structs; not recorded in the autograd graph.
         token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
             selected_experts
         )
 
-        # 2. Permute tokens from token order to expert order
+        # Permute tokens into expert order
         hidden_states = permute(hidden_states, gather_indices, self.top_k)
         assert hidden_states.shape == (total_tokens, hidden_dim)
 
@@ -410,8 +410,7 @@ class Llama4TritonTextMoe(Llama4GroupedGemmTextMoe):
             dX_only = self.dX_only,
         )
 
-        # Post-processing
-        # 1. Unpermute from expert order to token order
+        # Unpermute from expert order back to token order
         if not self.permute_y:
             hidden_states = unpermute(hidden_states, gather_indices)
         hidden_states += shared_expert_out
diff --git a/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py b/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
index bd51cac377..da3faa5f93 100644
--- a/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
+++ b/unsloth/kernels/moe/grouped_gemm/reference/layers/qwen3_moe.py
@@ -157,13 +157,13 @@ class Qwen3MoeGroupedGEMMBlock(torch.nn.Module):
 
         router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
 
-        # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
-        # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
+        # Token counts per expert + gather indices (token->expert order).
+        # Auxiliary structs; not recorded in the autograd graph.
         token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
             selected_experts
         )
 
-        # 2. Permute tokens from token order to expert order
+        # Permute tokens into expert order
         hidden_states = permute(hidden_states, gather_indices, self.top_k)
         assert hidden_states.shape == (total_tokens, hidden_dim)
 
@@ -179,12 +179,11 @@ class Qwen3MoeGroupedGEMMBlock(torch.nn.Module):
         )
         assert second_gemm.shape == (total_tokens, hidden_dim)
 
-        # Post-processing
-        # 1. Unpermute from expert order to token order
+        # Unpermute from expert order back to token order
         hidden_states_unpermute = unpermute(second_gemm, gather_indices)
         assert hidden_states_unpermute.shape == (total_tokens, hidden_dim)
 
-        # 2. Merge topk weights
+        # Merge topk weights
         hidden_states = (
             hidden_states_unpermute.view(num_tokens, self.top_k, hidden_dim)
             * routing_weights[..., None]
@@ -275,14 +274,13 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         hidden_states = hidden_states.view(-1, hidden_dim)
 
         router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
-        # Pre-processing
-        # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
-        # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
+        # Token counts per expert + gather indices (token->expert order).
+        # Auxiliary structs; not recorded in the autograd graph.
         token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
             selected_experts
         )
 
-        # 2. permute_x -> permutation will be fused in prologue of first grouped gemm
+        # When permute_x is set, the permute fuses into the first gemm prologue
         if not self.permute_x:
             hidden_states = permute(hidden_states, gather_indices, self.top_k)
         # Start expert computation
@@ -320,12 +318,11 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
             dX_only = self.dX_only,
         )
 
-        # Post-processing
-        # 1. Unpermute from expert order to token order
+        # Unpermute from expert order back to token order
         if not self.permute_y:
             hidden_states = unpermute(hidden_states, gather_indices)
 
-        # 2. Merge topk weights
+        # Merge topk weights
         hidden_states = (
             hidden_states.view(num_tokens, self.top_k, hidden_dim) * routing_weights[..., None]
         )
diff --git a/unsloth/kernels/moe/tests/moe_utils.py b/unsloth/kernels/moe/tests/moe_utils.py
index 71f5873510..3b87fe45a4 100644
--- a/unsloth/kernels/moe/tests/moe_utils.py
+++ b/unsloth/kernels/moe/tests/moe_utils.py
@@ -34,13 +34,13 @@ def rebind_experts_to_shared_buffer(moe_block: Qwen3MoeSparseMoeBlock, config: Q
     buffer_gate = torch.empty(num_experts, interm_size, hidden_size, device = device, dtype = dtype)
     buffer_down = torch.empty(num_experts, hidden_size, interm_size, device = device, dtype = dtype)
 
-    # Step 2: Copy existing expert weights into buffers
+    # Copy existing expert weights into buffers
     for i, expert in enumerate(moe_block.experts):
         buffer_up[i].copy_(expert.up_proj.weight.data)
         buffer_gate[i].copy_(expert.gate_proj.weight.data)
         buffer_down[i].copy_(expert.down_proj.weight.data)
 
-    # Step 3: Rebind expert weights to views in shared buffer
+    # Rebind expert weights to views in the shared buffer
     for i, expert in enumerate(moe_block.experts):
         expert.up_proj.weight = torch.nn.Parameter(buffer_up[i])
         expert.gate_proj.weight = torch.nn.Parameter(buffer_gate[i])
@@ -332,13 +332,11 @@ def run_backward(
 
 
 class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
-    """
-    Reference implementation of MoE block using grouped gemm.
+    """Reference MoE block using triton grouped gemm.
 
-    This is the same as the Qwen3MoeGroupedGEMMBlock but with triton grouped gemm in place of torch-native grouped gemm implementation.
-
-    NOTE: This is NOT to be used for production as it contains many extra checks and saves all intermediate results for debugging.
-    See grouped_gemm/reference/moe_block.py for a cleaner implementation.
+    Like Qwen3MoeGroupedGEMMBlock but with triton (not torch-native) grouped gemm.
+    NOT for production: it saves intermediate results and runs extra checks for
+    debugging. See grouped_gemm/reference/moe_block.py for a cleaner version.
     """
 
     def __init__(
@@ -406,14 +404,13 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         hidden_states = hidden_states.view(-1, hidden_dim)
 
         router_logits, routing_weights, selected_experts = self.run_router(hidden_states)
-        # Pre-processing
-        # 1. Compute tokens per expert and indices for gathering tokes from token order to expert order
-        # NOTE: these are auxiliary data structs which don't need to be recorded in autograd graph
+        # Pre-processing: token counts per expert + token-order -> expert-order
+        # gather indices (auxiliary, not recorded in the autograd graph).
         token_counts_by_expert, gather_indices = self.get_token_counts_and_gather_indices(
             selected_experts
         )
 
-        # 2. permute_x -> permutation will be fused in prologue of first grouped gemm
+        # permute_x fuses the permutation into the first grouped gemm's prologue
         if not self.permute_x:
             hidden_states = permute(hidden_states, gather_indices, self.top_k)
             assert hidden_states.shape == (total_tokens, hidden_dim)
@@ -452,15 +449,14 @@ class Qwen3MoeFusedGroupedGEMMBlock(Qwen3MoeGroupedGEMMBlock):
         )
         assert second_gemm.shape == (total_tokens, hidden_dim)
 
-        # Post-processing
-        # 1. Unpermute from expert order to token order
+        # Post-processing: unpermute expert order -> token order
         if not self.permute_y:
             hidden_states_unpermute = unpermute(second_gemm, gather_indices)
             assert hidden_states_unpermute.shape == (total_tokens, hidden_dim)
         else:
             hidden_states_unpermute = second_gemm
 
-        # 2. Merge topk weights
+        # Merge topk weights
         hidden_states = (
             hidden_states_unpermute.view(num_tokens, self.top_k, hidden_dim)
             * routing_weights[..., None]
diff --git a/unsloth/kernels/moe/tests/test_grouped_gemm.py b/unsloth/kernels/moe/tests/test_grouped_gemm.py
index 35de6fca51..7ff47d0767 100644
--- a/unsloth/kernels/moe/tests/test_grouped_gemm.py
+++ b/unsloth/kernels/moe/tests/test_grouped_gemm.py
@@ -43,12 +43,8 @@ from .common import (
 SEED = 0
 
 
-# Only certain combinations of permute_x, permute_y, use_W1 are valid.
-# use_W1 => first grouped GEMM in a fused MoE MLP
-# use_W2 => second grouped GEMM in a fused MoE MLP
-# permute_x => permute the input to the grouped GEMM, only done for the first grouped GEMM
-# permute_y => permute the output of the grouped GEMM, only done for the second grouped GEMM
-# fuse_mul_post => fuse the multiplication of topk weights in the epilogue of the second grouped GEMM; only used for inference, not currently tested
+# Only certain (permute_x, permute_y, use_W1) combinations are valid; see the
+# module string below for the full rationale.
 def check_valid_config(
     permute_x,
     permute_y,
diff --git a/unsloth/kernels/utils.py b/unsloth/kernels/utils.py
index 0db97aabcb..43ed198a4a 100644
--- a/unsloth/kernels/utils.py
+++ b/unsloth/kernels/utils.py
@@ -283,9 +283,8 @@ def QUANT_STATE(W):
 
 
 def get_lora_parameters(proj):
-    """
-    Return a 5-tuple of (weight, weight quant_state, lora A, lora B, and lora scale).
-    If QAT is enabled, additionally fake quantize the base layer and lora weights.
+    """Return (weight, weight quant_state, lora A, lora B, lora scale).
+    With QAT enabled, also fake-quantizes the base layer and lora weights.
     """
     # For DPO or disabled adapters
     base_layer = getattr(
@@ -382,10 +381,8 @@ def get_lora_parameters_bias(proj):
 
 
 def _maybe_fake_quantize_activations(X: torch.Tensor, proj: torch.nn.Module) -> torch.Tensor:
-    """
-    If QAT is enabled, fake quantize the input activations.
-    Otherwise, just return the input activations as is.
-    Weights are fake quantized separately in `get_lora_parameters`.
+    """Fake-quantize input activations if QAT is enabled, else return as-is.
+    Weights are fake-quantized separately in `get_lora_parameters`.
     """
     base_layer = getattr(proj, "base_layer", proj)
     activation_fake_quantizer = getattr(base_layer, "activation_fake_quantizer", None)
@@ -1089,9 +1086,8 @@ def matmul_lora(
     if isinstance(W, Float8Tensor):
         assert W.ndim == 2
         if W.block_size[0] == W.shape[0] and W.block_size[1] == 1:
-            # In the backward pass, rowwise scaled becomes colwise scaled after we
-            # transpose the weight tensor. Use this case to detect backward.
-            # TODO: would be simpler if we simply don't call `matmul_lora` in backward
+            # Rowwise scaling becomes colwise after transpose, so this detects
+            # the backward pass. TODO: avoid calling matmul_lora in backward.
             W = W.dequantize()
         else:
             W = W.contiguous()
diff --git a/unsloth/models/__init__.py b/unsloth/models/__init__.py
index 138f309032..dc7e309109 100644
--- a/unsloth/models/__init__.py
+++ b/unsloth/models/__init__.py
@@ -24,7 +24,7 @@ from .sentence_transformer import FastSentenceTransformer
 try:
     from .falcon_h1 import FastFalconH1Model
 except:
-    # transformers_version < 4.53.0 does not have falcon_h1 so silently skip it for now
+    # falcon_h1 absent before transformers 4.53.0; skip
     pass
 from .dpo import PatchDPOTrainer, PatchKTOTrainer
 from ._utils import is_bfloat16_supported, is_vLLM_available, __version__
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index f8324bf8e0..486a907478 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -196,8 +196,7 @@ def apply_unsloth_gradient_checkpointing(use_gradient_checkpointing, max_seq_len
     """
     Apply gradient checkpointing with smart heuristics.
 
-    For seq < 512, the overhead of gradient offloading in gc="unsloth" mode
-    is not worth it. Benchmarks show standard gc is faster for small sequences.
+    For seq < 512, gc="unsloth" offloading overhead isn't worth it; standard gc is faster.
 
     Args:
         use_gradient_checkpointing: "unsloth", True, False, or None
@@ -208,9 +207,7 @@ def apply_unsloth_gradient_checkpointing(use_gradient_checkpointing, max_seq_len
         The effective use_gradient_checkpointing value (may change from "unsloth" to True)
     """
     if use_gradient_checkpointing == "unsloth":
-        # Gradient offloading overhead is not worth it for small sequences.
-        # Benchmarks show crossover point is around seq_len 384-512.
-        # For seq < 512, standard gradient checkpointing is faster.
+        # Offloading not worth it below ~512; standard gc is faster (crossover ~384-512).
         if max_seq_length < 512:
             unpatch_unsloth_smart_gradient_checkpointing()
             return True
@@ -1807,16 +1804,7 @@ if DEVICE_COUNT == 1 and int(os.environ.get("WORLD_SIZE", "1")) <= 1:
 
 # to move multiple tensors to the same device
 def move_to_device(target_device, *tensors):
-    """
-    Move multiple tensors to target device if they're not already there.
-
-    Args:
-        target_device: The target device to move tensors to
-        *tensors: Variable number of tensors to potentially move
-
-    Returns:
-        tuple: The tensors on the target device (same objects if already on device, new if moved)
-    """
+    """Move tensors to target_device (returns same objects if already there)."""
     if isinstance(target_device, int):
         target_device = torch.device(target_device)
     elif isinstance(target_device, str):
diff --git a/unsloth/models/falcon_h1.py b/unsloth/models/falcon_h1.py
index 3b03333241..b940c95c68 100644
--- a/unsloth/models/falcon_h1.py
+++ b/unsloth/models/falcon_h1.py
@@ -62,9 +62,7 @@ try:
         FalconH1Attention,
     )
 except ModuleNotFoundError:
-    # if we are on an old version of transformers technically it should fail in the try except above
-    # but if somehow we make it here, we need to raise an error since FalconH1Attention is not available
-    # or renamed
+    # FalconH1Attention unavailable or renamed (old transformers).
     raise ImportError(
         "Unsloth: Could not import FalconH1Attention from transformers.models.falcon_h1.modeling_falcon_h1."
     )
@@ -487,8 +485,7 @@ def _FalconH1_fast_forward_inference(
     attention_fast_forward_inference = FalconH1Attention_fast_forward_inference,
     mlp_fast_forward_inference = fast_swiglu_inference,
 ):
-    # This makes the attention and MLP customisable.
-    # Now for models like qwen3 or cohere which use custom attention operations, we can use this function
+    # Makes attention and MLP customisable (e.g. qwen3/cohere custom attention).
     def FalconH1Model_fast_forward_inference_custom(
         self,
         input_ids,
diff --git a/unsloth/models/gemma2.py b/unsloth/models/gemma2.py
index c3398d6554..68b9ebe22f 100644
--- a/unsloth/models/gemma2.py
+++ b/unsloth/models/gemma2.py
@@ -421,10 +421,9 @@ def Gemma2Attention_fast_forward_inference(
         Vnn = Vnn.reshape(bsz, n_heads, cached_len, head_dim)
 
     # Attention
-    # [TODO] Gemma2 uses manual matmul for all batch sizes because SDPA does
-    # not support softcapping (tanh logit scaling). If a future PyTorch adds
-    # a softcap param to scaled_dot_product_attention, consider using SDPA
-    # for bsz > 1 to match the llama/qwen3 pattern.
+    # [TODO] Gemma2 uses manual matmul for all batch sizes since SDPA lacks
+    # softcapping (tanh logit scaling). If PyTorch adds a softcap param to
+    # SDPA, consider SDPA for bsz > 1 to match the llama/qwen3 pattern.
     Qn *= (
         self.scalar
     )  # See https://github.com/ggerganov/llama.cpp/issues/7805#issuecomment-2153349963
diff --git a/unsloth/models/glm4_moe.py b/unsloth/models/glm4_moe.py
index e5fd88acbc..793a1beb06 100644
--- a/unsloth/models/glm4_moe.py
+++ b/unsloth/models/glm4_moe.py
@@ -42,22 +42,20 @@ import torch.nn.functional as F
 from typing import Optional, Tuple
 from ..kernels import fast_rms_layernorm
 
-# Import the grouped gemm utilities from unsloth kernels
-# The grouped_gemm module expects its parent directory to be in sys.path
+# grouped_gemm expects its parent dir on sys.path
 HAS_GROUPED_GEMM = False
 try:
     import sys
     import os
 
-    # Add the moe directory (parent of grouped_gemm) to sys.path
     _moe_path = os.path.join(
         os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "kernels", "moe"
     )
     if _moe_path not in sys.path:
         sys.path.insert(0, _moe_path)
 
-    # Import grouped_gemm package first to apply TMA compatibility shim
-    # This patches triton.language to support both old and new TMA API names
+    # Import first to apply the TMA compatibility shim (patches triton.language
+    # for both old and new TMA API names)
     import grouped_gemm  # noqa: F401 - triggers TMA compatibility shim
 
     from grouped_gemm.interface import grouped_gemm
@@ -134,30 +132,23 @@ def Glm4MoeLiteMoE_fast_forward(self, hidden_states):
     batch_size, seq_len, hidden_dim = orig_shape
     num_tokens = batch_size * seq_len
 
-    # Flatten hidden states for routing
     hidden_states = hidden_states.view(-1, hidden_dim)
 
-    # Router computation
     router_logits = self.gate(hidden_states)  # [num_tokens, n_routed_experts]
     topk_indices, topk_weights = self.route_tokens_to_experts(router_logits)
-    # Cast routing weights to match hidden_states dtype (Qwen3 pattern)
-    # Sigmoid router returns fp32, but hidden_states may be bf16
+    # Sigmoid router returns fp32; cast weights to hidden_states dtype (e.g. bf16)
     topk_weights = topk_weights.to(hidden_states.dtype)
 
-    # Get routing indices for grouped GEMM
     with torch.no_grad():
         token_counts_by_expert, gather_indices = get_routing_indices(
             topk_indices, self.n_routed_experts
         )
 
-    # Use grouped GEMM for expert computation
     if HAS_GROUPED_GEMM:
-        # Cast hidden_states to match expert weights dtype
-        # Under autocast, hidden_states may be fp32 while weights are bf16
+        # Under autocast hidden_states may be fp32 while weights are bf16
         hidden_states = hidden_states.to(self.experts.gate_up_proj.dtype)
 
-        # First grouped GEMM: gate_up_proj with permute_x
-        # Input: [num_tokens, hidden_dim] -> Output: [total_tokens, 2*intermediate_dim]
+        # gate_up_proj: [num_tokens, hidden_dim] -> [total_tokens, 2*intermediate_dim]
         intermediate = grouped_gemm(
             X = hidden_states,
             W = self.experts.gate_up_proj,
@@ -174,8 +165,7 @@ def Glm4MoeLiteMoE_fast_forward(self, hidden_states):
         gate, up = intermediate.chunk(2, dim = -1)
         intermediate = torch_nn_functional_silu(gate) * up
 
-        # Second grouped GEMM: down_proj with permute_y
-        # Input: [total_tokens, intermediate_dim] -> Output: [total_tokens, hidden_dim]
+        # down_proj: [total_tokens, intermediate_dim] -> [total_tokens, hidden_dim]
         expert_output = grouped_gemm(
             X = intermediate,
             W = self.experts.down_proj,
@@ -193,7 +183,6 @@ def Glm4MoeLiteMoE_fast_forward(self, hidden_states):
             expert_output.view(num_tokens, self.top_k, hidden_dim) * topk_weights.unsqueeze(-1)
         ).sum(dim = 1)
     else:
-        # Fallback to naive implementation
         hidden_states = self.experts(hidden_states, topk_indices, topk_weights)
 
     # Add shared expert output
@@ -218,11 +207,9 @@ def Glm4MoeLiteNaiveMoe_fast_forward(
     """
     num_tokens, hidden_dim = hidden_states.shape
     top_k = top_k_index.shape[1]
-    # Cast routing weights to match hidden_states dtype (Qwen3 pattern)
     top_k_weights = top_k_weights.to(hidden_states.dtype)
 
     if not HAS_GROUPED_GEMM:
-        # Fallback to original naive implementation
         final_hidden_states = torch.zeros_like(hidden_states)
         with torch.no_grad():
             expert_mask = torch.nn.functional.one_hot(top_k_index, num_classes = self.num_experts)
@@ -251,12 +238,10 @@ def Glm4MoeLiteNaiveMoe_fast_forward(
 
         return final_hidden_states
 
-    # Get routing indices for grouped GEMM
     with torch.no_grad():
         token_counts_by_expert, gather_indices = get_routing_indices(top_k_index, self.num_experts)
 
-    # Cast hidden_states to match expert weights dtype
-    # Under autocast, hidden_states may be fp32 while weights are bf16
+    # Under autocast hidden_states may be fp32 while weights are bf16
     hidden_states = hidden_states.to(self.gate_up_proj.dtype)
 
     # First grouped GEMM: gate_up_proj
@@ -311,7 +296,6 @@ def Glm4MoeLiteDecoderLayer_fast_forward(
     """
     Optimized decoder layer forward with fast RMS layernorm.
     """
-    # Check if we're in inference mode
     is_inference = use_cache and hasattr(self, "_flag_for_generation")
 
     if is_inference:
@@ -385,18 +369,15 @@ class FastGLM47Model(FastLlamaModel):
                 "Please upgrade with: pip install --upgrade transformers"
             )
 
-        # Patch MoE forward with grouped GEMM optimization
-        # TMA compatibility is handled by grouped_gemm/__init__.py which patches
-        # triton.language to support both old (_experimental_make_tensor_descriptor)
-        # and new (make_tensor_descriptor) API names
+        # Patch MoE forward with grouped GEMM (TMA compat handled by
+        # grouped_gemm/__init__.py)
         if HAS_GROUPED_GEMM:
             Glm4MoeLiteNaiveMoe.forward = Glm4MoeLiteNaiveMoe_fast_forward
             Glm4MoeLiteMoE.forward = Glm4MoeLiteMoE_fast_forward
 
-        # Note: We don't patch the following for GLM4 MoE because:
-        # - GLM4 uses MLA (Multi-head Latent Attention) which has different projection names
-        # - Glm4MoeLiteRotaryEmbedding doesn't have extend_rope_embedding method
-        # - The decoder layer and model forward functions assume Llama-compatible infrastructure
+        # Attention/rope/decoder/model forwards are NOT patched: GLM4 uses MLA
+        # with different projection names and lacks extend_rope_embedding, so the
+        # Llama-compatible infrastructure doesn't apply.
 
         return
 
@@ -415,7 +396,7 @@ class FastGLM47Model(FastLlamaModel):
         trust_remote_code = False,
         **kwargs,
     ):
-        # Pop kwargs that are used by loader but not passed to model
+        # Used by loader, not passed to model
         kwargs.pop("unsloth_force_compile", None)
 
         return FastLlamaModel.from_pretrained(
diff --git a/unsloth/models/granite.py b/unsloth/models/granite.py
index 084dc7722f..f5b0f57aa6 100644
--- a/unsloth/models/granite.py
+++ b/unsloth/models/granite.py
@@ -493,10 +493,9 @@ class GraniteRotaryEmbedding(LlamaRotaryEmbedding):
 
 def patched_init(original_init):
     def new_init(self, *args, **kwargs):
-        # we can use self.residual_multiplier arg in GraniteDecoderLayer_fast_forward as mentioned here
+        # GraniteModel_fast_forward_inference can't reach residual_multiplier/config,
+        # so stash the whole config here to pass it around. See:
         # https://github.com/huggingface/transformers/blob/e5fd865ebae062b7cf03a81b8c6affeb39f30bec/src/transformers/models/granite/modeling_granite.py#L243
-        # The problem is, we don't have access to either the value or config in GraniteModel_fast_forward_inference
-        # So we need a way to pass this value around. It is probably better to pass on entire config just in case we need it later
         config = kwargs.get("config", args[0] if args else None)
         if config is not None:
             self.config = config
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 17d485f9f9..6018a4ccb4 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -156,34 +156,13 @@ def _offload_frozen_module_for_training(
     device_type: str,
     offload_device: Optional[str] = "cpu",
 ) -> None:
+    """Move the trainable copy to ``device_type`` and offload the frozen original.
+
+    float16 is promoted to float32 for GPU compatibility (e.g. Tesla T4).
+    ``offload_device`` currently only supports "cpu"; None leaves the frozen
+    module in place. Modifies ``module`` in-place.
+    See https://github.com/unslothai/unsloth/pull/1200 (Tesla T4 float32).
     """
-    Offload frozen module to CPU and configure trainable copy for mixed precision training.
-
-    This function optimizes memory usage by:
-    1. Moving the trainable copy to the target device with appropriate precision
-    2. Optionally offloading the original frozen module to CPU/disk to free VRAM
-    3. Converting float16 to float32 for compatibility with certain GPUs (e.g., Tesla T4)
-
-    Args:
-        module: The module to configure. Must be a ModulesToSaveWrapper with a
-            `modules_to_save` attribute containing trainable and original modules.
-        device_type: Target device string for training (e.g., "cuda:0", "xpu:0")
-        offload_device: Device to offload frozen parameters (default: "cpu").
-            If None, the original frozen module remains on its current device.
-            Note: Currently only "cpu" is supported; disk offloading is planned.
-
-    Returns:
-        None (modifies module in-place)
-
-    Note:
-        - Float16 weights are automatically promoted to float32 for GPU compatibility
-        - When offload_device is specified, frozen parameters are moved to free VRAM
-        - Future versions will support disk-based offloading for even larger models
-
-    See Also:
-        - https://github.com/unslothai/unsloth/pull/1200 (Tesla T4 float32 requirement)
-    """
-    # Early return with explicit None if module doesn't support mixed precision training
     if not hasattr(module, "modules_to_save"):
         return None
 
@@ -213,8 +192,7 @@ def _fast_prepare_inputs_for_generation(
     past_key_values = kwargs.get("past_key_values", None)
     original_attention_mask = attention_mask
 
-    # Handle inputs_embeds - only use on FIRST generation step (no cache)
-    # This fixes GitHub issue #3798: inputs_embeds was ignored
+    # Only use inputs_embeds on the first step (no cache). Fixes issue #3798.
     use_inputs_embeds = inputs_embeds is not None and past_key_values is None
 
     if input_ids is not None and input_ids.numel() > 0:
@@ -470,11 +448,10 @@ def LlamaAttention_fast_forward_inference(
 
     # Need to do it prior 2 steps before hitting full on short KV cache
     # or else error
-    # ensure correct shape
     if position_ids.dim() == 1:
         position_ids = position_ids[:, None]
-    # Transformers 5.x generate() accumulates position_ids as [batch, full_seq_len]
-    # across decode steps. In single-token inference we only need the last position.
+    # Transformers 5.x accumulates position_ids as [batch, full_seq_len] across
+    # decode steps; single-token inference only needs the last position.
     if position_ids.shape[-1] > 1:
         position_ids = position_ids[:, -1:]
     position_ids = position_ids.to(Qn.device)
@@ -1152,12 +1129,8 @@ def LlamaModel_fast_forward(
         IS_ATTENTION_REFACTOR
         and (hasattr(self, "rotary_emb") or not hasattr(self.layers[0].self_attn, "rotary_emb"))
     ) or IS_GRANITE:
-        # Transformers main has made it mandatory to pass position_embeddings
-        # https://github.com/huggingface/transformers/pull/34858
-        # Also, transformers 4.45.0 supports granite but with the attention refactor (it always had the refactor)
-        # unsloth's check for granite too has "version >= 4.45.0 (rightly so)".
-        # so let granite always use the attention refactor implementation.
-
+        # position_embeddings is mandatory on main: https://github.com/huggingface/transformers/pull/34858
+        # granite always had the attention refactor, so let it always use this path.
         self.rotary_emb.extend_rope_embedding(hidden_states, self.config.max_position_embeddings)
         position_embeddings = self.rotary_emb.get_cached(
             self.config.max_position_embeddings, hidden_states.device.index
@@ -1264,8 +1237,7 @@ def _LlamaModel_fast_forward_inference(
     attention_fast_forward_inference = LlamaAttention_fast_forward_inference,
     mlp_fast_forward_inference = fast_swiglu_inference,
 ):
-    # This makes the attention and MLP customisable.
-    # Now for models like qwen3 or cohere which use custom attention operations, we can use this function
+    # Makes attention and MLP customisable for models like qwen3/cohere.
     def LlamaModel_fast_forward_inference_custom(
         self,
         input_ids,
@@ -1533,8 +1505,7 @@ def CausalLM_fast_forward(fast_forward_inference):
         logit_softcapping = getattr(self.config, "final_logit_softcapping", 0)
         logit_scaling = getattr(self.config, "logit_scale", 0)
         if self.config.model_type == "granite":
-            # granite uses logit_scaling as key and they divide by the scale unlike cohere
-            # notice that for granite, logits_scale is 16 and for cohere it is 0.125 (aka 1/8) in their respective configs
+            # granite divides by logits_scaling (16) unlike cohere which multiplies by 0.125.
             # granite: https://github.com/huggingface/transformers/blob/4d1d0f29a493098e6bc6b904b82e29cb331827f5/src/transformers/models/granite/modeling_granite.py#L1103
             # cohere: https://github.com/huggingface/transformers/blob/4d1d0f29a493098e6bc6b904b82e29cb331827f5/src/transformers/models/cohere/modeling_cohere.py#L1176
             logit_scaling = 1 / getattr(self.config, "logits_scaling", 1)
@@ -2019,11 +1990,10 @@ class LongRopeRotaryEmbedding(torch.nn.Module):
 
 
 def unsloth_fast_generate(self, *args, **kwargs):
-    # If the model starts out in training mode, restore training mode after generation
+    # Restore training mode after generation if we started in it
     restore_training_mode = self.training
-    # why: snapshot the actual GC mode value (e.g. "unsloth") before for_inference
-    # clears it, so the post-generate restore preserves the caller's configured GC
-    # mode rather than collapsing it to a plain bool.
+    # Snapshot the real GC mode (e.g. "unsloth") before for_inference clears it,
+    # so the restore preserves it rather than collapsing to a plain bool.
     use_gradient_checkpointing = next(
         (v for v in (getattr(m, "gradient_checkpointing", False) for m in self.modules()) if v),
         False,
@@ -2031,11 +2001,9 @@ def unsloth_fast_generate(self, *args, **kwargs):
 
     FastLlamaModel.for_inference(self)
 
-    # Unpack BatchEncoding passed as input_ids for backwards compatibility.
-    # Old notebooks do model.generate(input_ids=tokenizer(...)) where the tokenizer
-    # output is a BatchEncoding (dict-like). Transformers v5 generate() calls
-    # .shape on it directly and crashes. Unpack into separate kwargs so both
-    # v4 and v5 work transparently.
+    # Unpack BatchEncoding passed as input_ids (old notebooks do
+    # generate(input_ids=tokenizer(...))). v5 generate() calls .shape on it and
+    # crashes; unpack into separate kwargs so v4 and v5 both work.
     _maybe_encoding = kwargs.get("input_ids", None)
     if (
         _maybe_encoding is not None
@@ -2067,8 +2035,8 @@ def unsloth_fast_generate(self, *args, **kwargs):
 
     # For newer HF
     kwargs["cache_implementation"] = "dynamic"
-    # transformers 4.50 renamed num_logits_to_keep -> logits_to_keep.
-    # Pop both, re-emit under the spelling forward() accepts.
+    # transformers 4.50 renamed num_logits_to_keep -> logits_to_keep; pop both,
+    # re-emit under the spelling forward() accepts.
     _provided_num = kwargs.pop("num_logits_to_keep", None)
     _provided_logits = kwargs.pop("logits_to_keep", None)
     _provided = _provided_logits if _provided_logits is not None else _provided_num
@@ -2378,12 +2346,10 @@ class FastLlamaModel:
                 bnb_4bit_compute_dtype = dtype,
                 llm_int8_skip_modules = llm_int8_skip_modules,
             )
-            # For pre-quantized checkpoints (e.g. unsloth/Qwen3-4B-bnb-4bit),
-            # transformers uses the quantization_config baked into the
-            # checkpoint's config.json and ignores the runtime BitsAndBytesConfig
-            # we pass via kwargs. Merge our skip list into that bundled config
-            # so task heads like `score` (for *ForSequenceClassification) stay
-            # in the compute dtype. See unslothai/unsloth#5027.
+            # Pre-quantized checkpoints (e.g. unsloth/Qwen3-4B-bnb-4bit) use the
+            # quantization_config baked into config.json, ignoring our runtime
+            # BitsAndBytesConfig. Merge our skip list into the bundled config so
+            # task heads like `score` stay in compute dtype. See unslothai/unsloth#5027.
             if _ckpt_quant_method == "bitsandbytes" and _ckpt_qcfg is not None:
                 if isinstance(_ckpt_qcfg, dict):
                     _ckpt_skip = list(_ckpt_qcfg.get("llm_int8_skip_modules") or [])
@@ -2436,10 +2402,8 @@ class FastLlamaModel:
                 attn_implementation = preferred_attn_impl,
                 **kwargs,
             )
-            # Defensive: make sure the task head ended up in a floating dtype.
-            # The primary protection is SKIP_QUANTIZATION_MODULES plus the skip
-            # list merge above; this guards against a downstream path accidentally
-            # leaving the head in an integer storage. See unslothai/unsloth#5027.
+            # Defensive: ensure the task head is in a floating dtype, guarding
+            # against any path leaving it as integer storage. See unslothai/unsloth#5027.
             for _head_name in ("score", "classifier", "qa_outputs"):
                 _head = getattr(model, _head_name, None)
                 if (
@@ -2712,12 +2676,10 @@ class FastLlamaModel:
             model._old_generate = model.generate
             unsloth_fast_generate.__doc__ = model._old_generate.__doc__
             model.generate = types.MethodType(unsloth_fast_generate, model)
-        # Set weight[padding_idx] = 0 for embeddings that are NOT tied with the
-        # lm_head. When weights are tied, zeroing the padding row also zeros
-        # the corresponding lm_head row, forcing logit = 0 for the pad token.
-        # This is higher than the (negative) logits for real tokens in models
-        # like Gemma, causing the decoder to emit <pad> and produce gibberish.
-        # Skip entirely if eos_token == pad_token to avoid zeroing EOS embedding.
+        # Zero weight[padding_idx] only for embeddings NOT tied to lm_head: when
+        # tied, zeroing the row forces pad logit = 0, which beats the (negative)
+        # logits of real tokens (e.g. Gemma) and makes the decoder emit <pad>.
+        # Skip if eos_token == pad_token to avoid zeroing the EOS embedding.
         eos_token_id = getattr(tokenizer, "eos_token_id", None) if tokenizer is not None else None
         pad_token_id = getattr(tokenizer, "pad_token_id", None) if tokenizer is not None else None
         if tokenizer is not None and eos_token_id != pad_token_id:
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 34514e7013..b0ce28969e 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -147,19 +147,11 @@ DISABLE_SDPA_MODEL_NAMES = [
 def _fix_rope_inv_freq(model):
     """Fix inv_freq corruption caused by transformers v5 meta-device loading.
 
-    Transformers v5 initializes models on the meta device, then
-    _move_missing_keys_from_meta_to_device() (modeling_utils.py) replaces ALL
-    non-persistent buffers with torch.empty_like() -- uninitialized memory.
-
-    Vanilla transformers restores inv_freq via _init_weights() which checks for
-    hasattr(module, "original_inv_freq"). Unsloth's LlamaRotaryEmbedding and
-    subclasses do not have this attribute, so inv_freq stays corrupted. This
-    produces wrong positional encodings and causes 5-11x higher training loss.
-
-    This function recomputes inv_freq from the stored base and dim, applies
-    any model-specific scaling, and rebuilds the cos/sin caches.
-
-    Only runs on transformers >= 5.0.0. No-op on v4.
+    v5 inits on meta then replaces all non-persistent buffers with uninitialized
+    memory. Vanilla restores inv_freq via _init_weights() (needs original_inv_freq),
+    but Unsloth rotary classes lack that attr, so inv_freq stays corrupted -> wrong
+    positional encodings and 5-11x higher training loss. Here we recompute inv_freq
+    from base/dim, apply scaling, and rebuild cos/sin caches. No-op on v4.
     """
     if not _NEEDS_ROPE_FIX:
         return model
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index d304bb454e..98458ad307 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -49,7 +49,7 @@ BAD_MAPPINGS = {
 
 
 def _get_torchao_fp8_config(fp8_mode):
-    # Import lazily so an optional, broken vLLM install does not break plain `import unsloth`.
+    # Lazy import so a broken optional vLLM install doesn't break `import unsloth`.
     from unsloth_zoo.vllm_utils import _get_torchao_fp8_config as _impl
     return _impl(fp8_mode)
 
@@ -126,10 +126,8 @@ def __get_model_name(
         else:
             if lower_model_name in FLOAT_TO_FP8_BLOCK_MAPPER:
                 return FLOAT_TO_FP8_BLOCK_MAPPER[lower_model_name]
-        # Mapper didn't find a pre-quantized model.
-        # For vllm >= 0.12.0, we can quantize the model to FP8 on the fly,
-        # so just return the original model name. Older vllm versions will
-        # fall through to offline quantization via _offline_quantize_to_fp8.
+        # No pre-quantized model found. vllm >= 0.12.0 quantizes to FP8 on the
+        # fly (return original name); older vllm falls through to offline quant.
         if importlib.util.find_spec("vllm") is not None:
             import vllm
             if Version(vllm.__version__) >= Version("0.12.0"):
@@ -160,8 +158,7 @@ def __get_model_name(
         return new_model_name
 
     elif load_in_4bit and SUPPORTS_FOURBIT and lower_model_name in FLOAT_TO_INT_MAPPER:
-        # Support returning original full -bnb-4bit name if specified specifically
-        # since we'll map it to the dynamic version instead
+        # Keep an explicit -bnb-4bit name; otherwise map to the dynamic version.
         if lower_model_name.endswith("-bnb-4bit"):
             return model_name
 
@@ -232,8 +229,7 @@ def get_model_name(
         float_to_int = FLOAT_TO_INT_MAPPER,
         map_to_unsloth_16bit = MAP_TO_UNSLOTH_16bit,
     )
-    # In the rare case, we convert bad model names to other names
-    # For eg too large dynamic quants or MoEs
+    # Remap "bad" names (e.g. oversized dynamic quants or MoEs)
     if (
         new_model_name is not None
         and type(new_model_name) is str
@@ -269,16 +265,10 @@ def get_model_name(
 
 
 def _offline_quantize_to_fp8(model_name: str, fp8_mode: str) -> str:
-    """
-    Quantizes the model to fp8 using torchao and saving the quantized model to a
-    temporary location. Return the path to the quantized model.
+    """Quantize the model to fp8 via torchao, save to a temp dir, return its path.
 
-    Note: For vllm >= 0.12.0, we should dynamically quantize the model in vllm instead:
-
-      llm = LLM(
-        ...
-        hf_overrides={"quantization_config_file": "torchao_config.json"},
-      )
+    For vllm >= 0.12.0, prefer dynamic quantization in vllm instead (via
+    hf_overrides={"quantization_config_file": "torchao_config.json"}).
     """
     temp_dir = tempfile.gettempdir()
     new_model_name = model_name.split("/")[-1] + "-fp8-" + fp8_mode
@@ -322,9 +312,7 @@ def _offline_quantize_to_fp8(model_name: str, fp8_mode: str) -> str:
 
 
 def _tag_model_with_fp8_torchao_config(model: torch.nn.Module, fp8_mode: str):
-    """
-    Tag a model with a `TorchAOConfig` so downstream callers will know what to do with it.
-    """
+    """Tag a model with a `TorchAOConfig` so downstream callers know how to handle it."""
     try:
         base_config = _get_torchao_fp8_config(fp8_mode)
         model.torchao_config = TorchAOConfig(
@@ -384,16 +372,9 @@ def _get_fp8_mode_and_check_settings(
     load_in_8bit: bool = False,
     load_in_16bit: bool = False,
 ) -> str:
-    """
-    Assuming `load_in_fp8` is enabled, raise appropriate errors on incompatible settings
-    and environment. Currently this feature requires:
-
-    1. H100 GPUs or after
-    2. torchao 0.15.0+ (or nightly)
-    3. torch 2.9.0+
-    4. If fbgemm_gpu_genai is installed, require 1.4.1+
-
-    Returns the fp8 mode, one of "row" or "block".
+    """Validate `load_in_fp8` settings/environment and return the fp8 mode
+    ("row" or "block"). Requires H100+, torchao 0.15.0+, torch 2.9.0+, and
+    fbgemm_gpu_genai 1.4.1+ if installed.
     """
     assert load_in_fp8 is not False
     if load_in_fp8 is True:
diff --git a/unsloth/models/mistral.py b/unsloth/models/mistral.py
index cd6dd2ed1a..74f7acbb03 100644
--- a/unsloth/models/mistral.py
+++ b/unsloth/models/mistral.py
@@ -179,13 +179,9 @@ def MistralForCausalLM_fast_forward(
             # If attention_mask exists, it will be handled in the attention forward
 
         elif self.training:
-            # During training, LlamaModel_fast_forward's DPO embed-masking
-            # block requires a 2D attention_mask (it does
-            # inputs_embeds *= attention_mask.unsqueeze(0).transpose(0, 1).transpose(1, 2)).
-            # Afterwards, LlamaModel_fast_forward sets attention_mask=None
-            # before the attention layers anyway, so leaving the 2D mask
-            # untouched here is safe and avoids converting to 4D (which would
-            # crash the DPO block).
+            # LlamaModel_fast_forward's DPO embed-masking block needs the 2D
+            # attention_mask; it nulls the mask before attention anyway, so
+            # leaving it 2D is safe and avoids a 4D conversion that crashes DPO.
             pass
 
         else:
diff --git a/unsloth/models/qwen3.py b/unsloth/models/qwen3.py
index c515347b5b..e28e72d3ea 100644
--- a/unsloth/models/qwen3.py
+++ b/unsloth/models/qwen3.py
@@ -103,10 +103,8 @@ def Qwen3Attention_fast_forward(
     V = V.view(bsz, q_len, n_kv_heads, head_dim).transpose(1, 2)
     seq_info = get_packed_info_from_kwargs(kwargs, hidden_states.device)
 
-    # Qwen3 has QKNorm. This seems to be the only difference from Qwen2.
-    # Note that using fast_layernorm_compiled causes issues as the dimensions don't match up.
-    # I tried to add a compiled version of the new norm but the numbers don't match up with Transformers
-    # TODO: Check on the differences here.
+    # Qwen3 adds QKNorm (the only difference from Qwen2). A compiled norm
+    # mismatches Transformers' numbers, so use fast_rms_layernorm. TODO: investigate.
     Q = fast_rms_layernorm(self.q_norm, Q)
     K = fast_rms_layernorm(self.k_norm, K)
 
@@ -180,33 +178,12 @@ def Qwen3Attention_fast_forward_inference(
     attention_mask = None,
     **kwargs,
 ):
-    """
-    https://github.com/huggingface/transformers/blob/main/src/transformers/models/llama/modeling_llama.py#L406
-    Fast inference using KV cache.
-    QK^T can be computed in 4 chunks
+    """Fast inference using the KV cache.
 
-    [Q, q] @ [K, k].T where q, k are the new tokens.
-    [QK^T, Qk^T]
-    [qK^T, qk^T]
-
-    Since the attention mask wipes Qk^T, we just get
-    [QK^T,    0]
-    [qK^T, qk^T]
-
-    Since softmax is row-wise, we get
-    softmax([QK^T,    0])
-    softmax([qK^T, qk^T])
-
-    We then multiply by   [V]
-                          [v]
-    softmax([QK^T,    0]) [softmax(QK^T)V] *
-    softmax([qK^T, qk^T]) [softmax([qK^T, qk^T]) @ [V, v]]
-
-    But notice * [softmax(QK^T)V] is just the last attention.
-    We just need to compute the last final row.
-
-    This means we can pass in a row of Q, but we need to
-    remember K and V, which are called the KV cache.
+    QK^T splits into 4 chunks; the mask zeroes Qk^T and softmax is row-wise, so
+    softmax(QK^T)V is just the prior step's attention. We therefore only compute
+    the final row: pass one row of Q while remembering K and V (the KV cache).
+    Ref: https://github.com/huggingface/transformers/blob/main/src/transformers/models/llama/modeling_llama.py#L406
     """
     Xn = hidden_states
     bsz, _, hd = hidden_states.size()
@@ -417,11 +394,8 @@ class FastQwen3Model(FastLlamaModel):
         PeftModelForCausalLM.forward = PeftModel_fast_forward
         fix_prepare_inputs_for_generation(Qwen3ForCausalLM)
 
-        # Solves https://github.com/unslothai/unsloth/issues/168
-        # Static KV Cache was introduced in 4.38.0, causing training to be much slower.
-        # Inference can now be CUDAGraphed, but we shall retain the old rotary embeddings.
-        # https://github.com/huggingface/transformers/pull/27931
-        # https://github.com/huggingface/transformers/blob/v4.37.2/src/transformers/models/llama/modeling_llama.py
+        # Retain old rotary embeddings; static KV cache (transformers 4.38.0)
+        # slowed training. See unslothai/unsloth#168 and transformers#27931.
         import transformers.models.qwen3.modeling_qwen3
 
         transformers.models.qwen3.modeling_qwen3.Qwen3RotaryEmbedding = LlamaRotaryEmbedding
diff --git a/unsloth/models/qwen3_moe.py b/unsloth/models/qwen3_moe.py
index 8e692e46ea..7a5dcbd889 100644
--- a/unsloth/models/qwen3_moe.py
+++ b/unsloth/models/qwen3_moe.py
@@ -67,31 +67,26 @@ def Qwen3MoeSparseMoeBlock_fast_forward(
     routing_weights = torch_nn_functional_softmax(router_logits, dim = -1, dtype = torch.float32)
     routing_weights, selected_experts = torch.topk(routing_weights, self.top_k, dim = -1)
     routing_weights /= routing_weights.sum(dim = -1, keepdim = True)
-    # we cast back to the input dtype
+    # cast back to the input dtype
     routing_weights = routing_weights.to(X.dtype)
     final_X = torch.zeros((bsz * seq_len, hd), dtype = torch.float32, device = X.device)
 
-    # One hot encode the selected experts to create an expert mask
-    # this will be used to easily index which expert is going to be sollicitated
+    # One-hot the selected experts into a mask to index which expert is used
     expert_mask = torch.nn.functional.one_hot(
         selected_experts, num_classes = self.num_experts
     ).permute(2, 1, 0)
 
-    # Loop over all available experts in the model and perform the computation on each expert
     for expert_idx in range(self.num_experts):
         expert_layer = self.experts[expert_idx]
         idx, top_x = torch.where(expert_mask[expert_idx])
 
-        # Index the correct hidden states and compute the expert hidden state for
-        # the current expert. We need to make sure to multiply the output hidden
-        # states by `routing_weights` on the corresponding tokens (top-1 and top-2)
+        # Index hidden states for this expert and scale by routing_weights
         current_state = X[None, top_x].reshape(-1, hd)
         current_X = (
             expert_layer(current_state) * routing_weights[top_x, idx, None]
-        )  # Qwen3MoeMLP.forward = fast_swiglu_inference takes care of making this faster. Analogous to Dense models' MLP
+        )  # Qwen3MoeMLP.forward = fast_swiglu_inference speeds this up
 
-        # However `index_add_` only support torch tensors for indexing so we'll use
-        # the `top_x` tensor here.
+        # index_add_ needs a tensor index, so use top_x
         final_X.index_add_(0, top_x, current_X.to(X.dtype))
     final_X = final_X.reshape(bsz, seq_len, hd)
     return final_X, router_logits
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index a9d2a90b8a..5fb8cf6ddc 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -1643,13 +1643,11 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
                 flags = re.DOTALL,
             )
 
-    # Remove TRL's unconditional bfloat16 cast of trainable params (added in
-    # TRL 0.26.0). TRL hardcodes bfloat16 for QLoRA per the original paper's
-    # recommendation, but this is wrong: it ignores the user's requested dtype
-    # and breaks GradScaler when training with fp16=True. Unsloth already
-    # handles adapter dtype correctly via patch_model_and_tokenizer, so the
-    # entire block is unnecessary. For GRPOTrainer the enclosing peft init
-    # block is already removed above, making this a no-op for GRPO.
+    # Remove TRL 0.26.0's unconditional bfloat16 cast of trainable params. It
+    # hardcodes bfloat16 for QLoRA, ignoring the user's dtype and breaking
+    # GradScaler with fp16=True. Unsloth already handles adapter dtype via
+    # patch_model_and_tokenizer, so the block is unnecessary (and already a
+    # no-op for GRPO, whose peft init block is removed above).
     RLTrainer_source = RLTrainer_source.replace(
         'if getattr(model, "is_loaded_in_4bit", False) or getattr(model, "is_loaded_in_8bit", False):',
         "if False:",
@@ -1664,13 +1662,11 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         )
         RLTrainer_source = RLTrainer_source.replace(original_text, new_text)
 
-        # Do NOT override _is_vlm -- let TRL detect VLM models naturally.
-        # In TRL 0.27.1+, forcing _is_vlm=False causes a ValueError when
-        # vision datasets are used with VLM models.
-        #
-        # However, some notebooks pass a bare tokenizer (processor.tokenizer) as
-        # processing_class. TRL then sets _is_vlm=False even for VLM models.
-        # Add a model-architecture-based override before the validation check.
+        # Do NOT override _is_vlm -- let TRL detect VLM models naturally
+        # (forcing _is_vlm=False errors on vision datasets in TRL 0.27.1+).
+        # But some notebooks pass a bare tokenizer as processing_class, so TRL
+        # sets _is_vlm=False even for VLMs; add an architecture-based override
+        # before the validation check.
         _vlm_check_original = (
             '        self._is_vision_dataset = "image" in dataset_sample or "images" in dataset_sample\n'
             "        if self._is_vision_dataset and not self._is_vlm:"
@@ -1689,13 +1685,11 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
         if _vlm_check_original in RLTrainer_source:
             RLTrainer_source = RLTrainer_source.replace(_vlm_check_original, _vlm_check_patched)
 
-        # Fix TRL 0.22.x: VLM models with text-only datasets.
-        # TRL 0.22.x checks _is_vlm (model type) not _is_vision_dataset (dataset
-        # content, added in 0.25.1+). When _is_vlm=True, signature columns are
-        # vision-only ["messages","prompt","completion","images"], which have zero
-        # overlap with tokenized text columns. Fix: merge both column sets into the
-        # VLM branch. Extra columns not in the dataset are harmlessly ignored by
-        # _remove_unused_columns (it only raises when zero columns match).
+        # Fix TRL 0.22.x: VLM models with text-only datasets. It checks _is_vlm
+        # (model type), not _is_vision_dataset (added in 0.25.1+); with
+        # _is_vlm=True the vision-only signature columns don't overlap tokenized
+        # text columns. Fix: merge both column sets into the VLM branch. Extra
+        # columns are ignored by _remove_unused_columns (raises only on zero match).
         _sig_vlm_old = 'self._signature_columns = ["messages", "prompt", "completion", "images"]'
         _sig_vlm_new = (
             'self._signature_columns = ["messages", "prompt", "completion", "images",'
@@ -2161,26 +2155,15 @@ def patch_trl_rl_trainers():
 def patch_trl_disable_gradient_checkpointing():
     # TRL 1.0.0+ wraps generation in:
     #   with torch.no_grad(), disable_gradient_checkpointing(self.model, ...):
-    # The toggle exists only to suppress a cosmetic PyTorch warning
-    # ("None of the inputs have requires_grad=True"). Inside torch.no_grad()
-    # the gradient checkpointing state has no functional effect on the
-    # forward pass.
+    # The toggle only suppresses a cosmetic PyTorch warning; under no_grad it
+    # has no functional effect. But on exit it calls
+    # gradient_checkpointing_enable(), overwriting Unsloth's custom
+    # "unsloth" wrapper -- for Gemma-4 this corrupts forward numerics and
+    # blows GRPO KL divergence up to ~10^12 at step 1.
     #
-    # On exit, the context manager calls model.gradient_checkpointing_enable()
-    # which dispatches to HuggingFace's generic implementation and overwrites
-    # Unsloth's custom `use_gradient_checkpointing="unsloth"` wrapper. For
-    # Gemma-4 (and likely other models) this corrupts the forward numerics
-    # enough to make GRPO KL divergence explode to ~10^12 at step 1.
-    #
-    # Replacing the context manager with a no-op preserves Unsloth's custom
-    # gradient checkpointing wrapper across generation/inference passes.
-    #
-    # Backwards compatibility:
-    #   - trl < 1.0.0 (no disable_gradient_checkpointing): early return.
-    #   - trl >= 1.0.0: noop is functionally equivalent for forward
-    #     correctness. The only loss is a cosmetic warning being emitted
-    #     by PyTorch when use_reentrant=True (which is exactly the warning
-    #     TRL added the toggle to suppress in the first place).
+    # Replacing the context manager with a no-op preserves Unsloth's wrapper.
+    # trl < 1.0.0 (no disable_gradient_checkpointing): early return.
+    # trl >= 1.0.0: noop is correct; only loss is the cosmetic warning.
     try:
         import trl.models.utils as _tmu
     except ImportError:
@@ -2203,12 +2186,9 @@ def patch_trl_disable_gradient_checkpointing():
     _tmu.disable_gradient_checkpointing = _noop_disable_gradient_checkpointing
 
     # Also rebind any trl.* module that already imported the symbol by
-    # reference, so the noop applies even when the trainer module cached the
-    # original at import time. We walk sys.modules dynamically rather than
-    # hardcoding a list, so this picks up every trainer that does
-    # `from ...models.utils import disable_gradient_checkpointing`
-    # (grpo, dpo, rloo, dppo, gfpo, grpo_with_replay_buffer, and any future
-    # TRL trainer module).
+    # reference (cached at import time). Walk sys.modules dynamically so this
+    # catches every trainer doing
+    # `from ...models.utils import disable_gradient_checkpointing`.
     for _mod_name, _mod in list(sys.modules.items()):
         if _mod is None or not _mod_name.startswith("trl."):
             continue
@@ -2272,12 +2252,10 @@ def PatchFastRL(algorithm = None, FastLanguageModel = None):
     if os.environ.get("UNSLOTH_ALLOW_CPU", "0") == "1":
         return
     # Install the disable_gradient_checkpointing noop BEFORE
-    # patch_trl_rl_trainers. patch_trl_rl_trainers imports extra trl.* trainer
-    # submodules while generating the compiled cache; any new trl.* modules
-    # imported after the sys.modules walk would keep their original (broken)
-    # binding of disable_gradient_checkpointing. Running the noop install
-    # first ensures the canonical trl.models.utils symbol is already replaced
-    # before those submodules bind it.
+    # patch_trl_rl_trainers, which imports extra trl.* submodules; any module
+    # imported after the sys.modules walk would keep the original broken
+    # binding. Installing first ensures the canonical symbol is replaced before
+    # those submodules bind it.
     patch_trl_disable_gradient_checkpointing()
     patch_trl_rl_trainers()
     patch_trl_openenv()
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index a42340f282..7e43442bfd 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -56,7 +56,6 @@ def _save_pretrained_torchao(
 ):
     self.save_pretrained(save_directory)
 
-    # grab inner model
     inner_model = self[0].auto_model
     if hasattr(inner_model, "_orig_mod"):
         inner_model = inner_model._orig_mod
@@ -65,7 +64,6 @@ def _save_pretrained_torchao(
     if hasattr(inner_model, "merge_and_unload"):
         inner_model = inner_model.merge_and_unload()
 
-    # confirm Transformer path
     transformer_path = "0_Transformer"
     modules_path = os.path.join(save_directory, "modules.json")
     if os.path.exists(modules_path):
@@ -96,7 +94,6 @@ def _save_pretrained_torchao(
         try:
             yield
         finally:
-            # unpatch
             transformers.AutoModelForCausalLM = original_causal
             shutil.rmtree = original_rmtree
 
@@ -116,7 +113,6 @@ def _save_pretrained_torchao(
         if not os.path.exists(transformer_dir):
             os.makedirs(transformer_dir, exist_ok = True)
 
-        # move contents
         for item in os.listdir(torchao_dir):
             s = os.path.join(torchao_dir, item)
             d = os.path.join(transformer_dir, item)
@@ -125,7 +121,6 @@ def _save_pretrained_torchao(
             else:
                 shutil.copy2(s, d)
 
-        # remove torchao dir
         shutil.rmtree(torchao_dir)
 
         # remove conflicting safetensors if we brought in bin
@@ -164,14 +159,11 @@ def _save_pretrained_gguf(
     # 1. Save standard SentenceTransformer structure (configs, modules.json, etc.)
     self.save_pretrained(save_directory)
 
-    # 2. Extract inner transformer model
+    # 2. Extract inner transformer model (PEFT merge handled by the gguf saver)
     inner_model = self[0].auto_model
     if hasattr(inner_model, "_orig_mod"):
         inner_model = inner_model._orig_mod
 
-    # If it's a PEFT model, unsloth_save_pretrained_gguf handles merging,
-    # but we pass the inner model wrapper.
-
     # 3. Identify where the transformer weights are stored
     transformer_path = "0_Transformer"
     modules_path = os.path.join(save_directory, "modules.json")
@@ -186,18 +178,17 @@ def _save_pretrained_gguf(
         except:
             pass
 
-    # This is where Unsloth will perform the save + conversion operations
+    # Unsloth saves + converts here; absolute for later commonpath comparison
     transformer_dir = os.path.join(save_directory, transformer_path)
-    # Ensure this path is absolute for consistent comparison later
     transformer_dir = os.path.abspath(transformer_dir)
 
     if tokenizer is None:
         tokenizer = self.tokenizer
 
-    # 4. Patch environment to ensure Unsloth treats this embedding model correctly
+    # 4. Patch environment so Unsloth treats this embedding model correctly
     @contextlib.contextmanager
     def patch_unsloth_gguf_save():
-        # Prevent deletion of the directory we just created via self.save_pretrained
+        # Prevent deletion of the directory self.save_pretrained just created
         original_rmtree = shutil.rmtree
         try:
             yield
@@ -229,27 +220,24 @@ def _save_pretrained_gguf(
             filename = os.path.basename(gguf_file)
             dest_path = os.path.join(save_directory, filename)
 
-            # Convert to absolute path to avoid mixing relative/absolute in commonpath
             abs_gguf_file = os.path.abspath(gguf_file)
 
-            # Check if file is inside transformer_dir (subpath)
             try:
                 is_subpath = os.path.commonpath([abs_gguf_file, transformer_dir]) == transformer_dir
             except ValueError:
-                # Can happen on Windows with different drives, or mix of absolute/relative (handled by abspath above)
+                # Windows different-drive commonpath raises
                 is_subpath = False
 
             if is_subpath:
-                # If the GGUF file is inside the transformer_dir, move it out to root
+                # Move the GGUF out of transformer_dir to root
                 shutil.move(gguf_file, dest_path)
                 new_gguf_locations.append(dest_path)
             else:
-                # If it's elsewhere, move it to root if not already there
+                # Elsewhere: move to root if not already there
                 if os.path.abspath(dest_path) != abs_gguf_file:
                     shutil.move(gguf_file, dest_path)
                 new_gguf_locations.append(dest_path)
 
-    # Update result with new locations
     result["gguf_files"] = new_gguf_locations
 
     # 7. Add branding
@@ -364,7 +352,6 @@ def _push_to_hub_gguf(
 
     api = HfApi(token = token)
 
-    # Determine full repo_id
     if "/" not in repo_id:
         username = api.whoami()["name"]
         full_repo_id = f"{username}/{repo_id}"
@@ -373,7 +360,6 @@ def _push_to_hub_gguf(
 
     model_name = full_repo_id.split("/")[-1]
 
-    # Create repo
     try:
         api.create_repo(
             repo_id = full_repo_id,
@@ -384,11 +370,10 @@ def _push_to_hub_gguf(
     except Exception as e:
         print(f"Unsloth Warning: Could not create repo: {e}")
 
-    # Save to temporary directory first
+    # Convert locally in a temp dir, then upload
     with tempfile.TemporaryDirectory(prefix = "unsloth_st_gguf_") as temp_dir:
         print(f"Unsloth: Converting SentenceTransformer to GGUF format...")
 
-        # Call save_pretrained_gguf to do the local conversion
         result = _save_pretrained_gguf(
             self,
             save_directory = temp_dir,
@@ -522,12 +507,10 @@ This sentence-transformers model was finetuned and converted to GGUF format usin
 class FastSentenceTransformer(FastModel):
     @staticmethod
     def _save_base_config_for_processor_resume(config, output_path):
-        """
-        sentence-transformers >= 5.4 reloads Transformer modules through
-        AutoProcessor. Tokenizer-only checkpoint roots make AutoProcessor fall
-        back to AutoConfig, so PEFT adapter checkpoints still need the base
-        config.json next to adapter_config.json.
-        """
+        """sentence-transformers >= 5.4 reloads Transformer modules via
+        AutoProcessor, which falls back to AutoConfig for tokenizer-only
+        roots -- so PEFT adapter checkpoints still need base config.json
+        next to adapter_config.json."""
         if config is None or not getattr(config, "model_type", None):
             return
         if hasattr(config, "save_pretrained"):
@@ -559,9 +542,7 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _read_pooling_mode(model_name, token):
-        """
-        Read the pooling mode from the modules.json file if it exists, otherwise return "mean".
-        """
+        """Read the pooling mode from modules.json, else return "mean"."""
         try:
             if os.path.exists(model_name) and os.path.exists(
                 os.path.join(model_name, "modules.json")
@@ -578,7 +559,7 @@ class FastSentenceTransformer(FastModel):
                 if module.get("type", "") == "sentence_transformers.models.Pooling":
                     pooling_path = module.get("path", "")
                     if pooling_path:
-                        # try to find config.json for pooling module
+                        # find config.json for the pooling module
                         if os.path.exists(model_name) and os.path.exists(
                             os.path.join(model_name, pooling_path, "config.json")
                         ):
@@ -621,16 +602,11 @@ class FastSentenceTransformer(FastModel):
     # should prolly be done upstream instead of this hackfest here
     @staticmethod
     def _patch_mpnet_v4():
-        """
-        Patch the MPNetModel to support gradient checkpointing.
-        Supports transformers 4.
-        """
+        """Patch MPNetModel for gradient checkpointing (transformers 4)."""
         from transformers.models.mpnet import modeling_mpnet
 
-        # add supports_gradient_checkpointing flag
         modeling_mpnet.MPNetModel.supports_gradient_checkpointing = True
 
-        # add _set_gradient_checkpointing method
         def _set_gradient_checkpointing(
             self,
             module = None,
@@ -643,8 +619,7 @@ class FastSentenceTransformer(FastModel):
 
         modeling_mpnet.MPNetModel._set_gradient_checkpointing = _set_gradient_checkpointing
 
-        # patch MPNetEncoder.forward to support checkpointing
-        # based on:
+        # patch MPNetEncoder.forward for checkpointing; based on:
         # https://github.com/huggingface/transformers/blob/v4.57.3/src/transformers/models/mpnet/modeling_mpnet.py#L321
         def forward(
             self,
@@ -664,11 +639,9 @@ class FastSentenceTransformer(FastModel):
                 if output_hidden_states:
                     all_hidden_states = all_hidden_states + (hidden_states,)
 
-                # do gradient checkpointing if enabled and training
                 if getattr(self, "gradient_checkpointing", False) and self.training:
 
                     def create_custom_forward(module):
-                        # bog standard checkpoint
                         def custom_forward(*inputs):
                             return module(*inputs, output_attentions = output_attentions)
 
@@ -683,7 +656,6 @@ class FastSentenceTransformer(FastModel):
                         use_reentrant = True,  # fix for torch 2.9
                     )
                 else:
-                    # original code from here on
                     layer_outputs = layer_module(
                         hidden_states,
                         attention_mask,
@@ -711,21 +683,15 @@ class FastSentenceTransformer(FastModel):
                 attentions = all_attentions,
             )
 
-        # assign the patched forward
         modeling_mpnet.MPNetEncoder.forward = forward
 
     @staticmethod
     def _patch_mpnet_v5():
-        """
-        Patch the MPNetModel to support gradient checkpointing.
-        Supports transformers 5.
-        """
+        """Patch MPNetModel for gradient checkpointing (transformers 5)."""
         from transformers.models.mpnet import modeling_mpnet
 
-        # add supports_gradient_checkpointing flag
         modeling_mpnet.MPNetModel.supports_gradient_checkpointing = True
 
-        # add _set_gradient_checkpointing method
         def _set_gradient_checkpointing(
             self,
             module = None,
@@ -738,8 +704,7 @@ class FastSentenceTransformer(FastModel):
 
         modeling_mpnet.MPNetModel._set_gradient_checkpointing = _set_gradient_checkpointing
 
-        # patch MPNetEncoder.forward to support checkpointing
-        # based on:
+        # patch MPNetEncoder.forward for checkpointing; based on:
         # https://github.com/huggingface/transformers/blob/v5.0.0rc1/src/transformers/models/mpnet/modeling_mpnet.py#L284
         def forward(
             self,
@@ -758,11 +723,9 @@ class FastSentenceTransformer(FastModel):
                 if output_hidden_states:
                     all_hidden_states = all_hidden_states + (hidden_states,)
 
-                # do gradient checkpointing if enabled and training
                 if getattr(self, "gradient_checkpointing", False) and self.training:
 
                     def create_custom_forward(module):
-                        # checkpoint
                         def custom_forward(*inputs):
                             return module(*inputs, output_attentions = output_attentions)
 
@@ -776,7 +739,6 @@ class FastSentenceTransformer(FastModel):
                         use_reentrant = True,  # required for torch >= 2.9
                     )
                 else:
-                    # original code from here on
                     layer_outputs = layer_module(
                         hidden_states,
                         attention_mask,
@@ -808,14 +770,10 @@ class FastSentenceTransformer(FastModel):
     @staticmethod
     def _patch_distilbert_v4():
         # change kwargs to positional args to be compatible with peft_utils
-        """
-        Patch the forward method of the DistilBertModel to use positional arguments instead of keyword arguments.
-        Transformers 4 version.
-        """
+        """Patch DistilBertModel.forward to use positional args (transformers 4)."""
 
         # based on:
         # https://github.com/huggingface/transformers/blob/v4.57.3/src/transformers/models/distilbert/modeling_distilbert.py#L666
-        # original code from here on:
         def forward(
             self,
             input_ids: Optional[torch.Tensor] = None,
@@ -853,7 +811,6 @@ class FastSentenceTransformer(FastModel):
             device = input_ids.device if input_ids is not None else inputs_embeds.device
 
             head_mask_is_none = head_mask is None
-            # Prepare head mask if needed
             head_mask = self.get_head_mask(head_mask, self.config.num_hidden_layers)
 
             embeddings = self.embeddings(input_ids, inputs_embeds)  # (bs, seq_length, dim)
@@ -888,13 +845,10 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _has_add_pooling_layer(config, auto_model_class = None):
-        """
-        Checks if the model class supports the `add_pooling_layer` argument
-        """
+        """Check if the model class accepts the `add_pooling_layer` argument."""
         try:
             if auto_model_class is None:
                 auto_model_class = AutoModel
-            # try to resolve the class
             model_class = resolve_model_class(auto_model_class, config)
 
             if model_class:
@@ -907,13 +861,9 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _patch_distilbert_v5():
-        """
-        Patch the forward method of the DistilBertModel to use positional arguments instead of keyword arguments.
-        Transformers 5 version.
-        """
+        """Patch DistilBertModel.forward to use positional args (transformers 5)."""
         # based on:
         # https://github.com/huggingface/transformers/blob/v5.0.0rc1/src/transformers/models/distilbert/modeling_distilbert.py#L386
-        # original code from here on:
         from transformers.masking_utils import create_bidirectional_mask
 
         def forward(
@@ -950,9 +900,7 @@ class FastSentenceTransformer(FastModel):
         token,
         tags = None,
     ):
-        """
-        Add Unsloth and sentence-transformers tags to the Hugging Face Hub repository.
-        """
+        """Add Unsloth + sentence-transformers tags to the HF Hub repo."""
         from huggingface_hub import HfApi
 
         api = HfApi(token = token)
@@ -970,9 +918,7 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _add_unsloth_branding(save_directory):
-        """
-        Add Unsloth branding to the README.md file generated by sentence-transformers.
-        """
+        """Add Unsloth branding to the sentence-transformers-generated README.md."""
         readme_path = os.path.join(save_directory, "README.md")
         if not os.path.exists(readme_path):
             return
@@ -984,18 +930,16 @@ class FastSentenceTransformer(FastModel):
         if "---\ntags:\n" in content:
             content = content.replace("---\ntags:\n", "---\ntags:\n- unsloth\n")
         else:
-            # if tags exist but not right at start, use regex to append
+            # tags exist but not at the start: append via regex
             pattern = r"(^tags:\s*\n)"
             if re.search(pattern, content, re.MULTILINE):
                 content = re.sub(pattern, r"\1- unsloth\n", content, count = 1, flags = re.MULTILINE)
 
-        # add branding badge and text
         branding = (
             "\n\nThis model was finetuned with [Unsloth](https://github.com/unslothai/unsloth).\n\n"
             '[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)\n'
         )
 
-        # add to description
         if "# SentenceTransformer" in content:
             parts = content.split("# SentenceTransformer", 1)
             content = parts[0] + "# SentenceTransformer" + branding + parts[1]
@@ -1007,9 +951,7 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _module_path(model_name, token = None):
-        """
-        Returns the path to the modules.json file or None
-        """
+        """Return the path to the modules.json file, or None."""
         try:
             if os.path.exists(model_name) and os.path.isdir(model_name):
                 path = os.path.join(model_name, "modules.json")
@@ -1027,13 +969,11 @@ class FastSentenceTransformer(FastModel):
         """Helper to create and configure a Transformer module."""
         from sentence_transformers.models import Transformer
 
-        # prevents sentence-transformers from loading the model a second time, thanks Etherl
-        # Also redirect AutoProcessor / AutoTokenizer so the Transformer.__init__
-        # picks up our pre-fixed tokenizer. On sentence-transformers >=5.4 the
-        # `tokenizer` attribute became a read-only @property backed by `self.processor`,
-        # so a post-init assignment raises AttributeError; redirecting the constructor's
-        # AutoProcessor.from_pretrained call sets self.processor correctly and keeps
-        # downstream state (input_formatter) consistent.
+        # Prevents loading the model a second time and redirects AutoProcessor/
+        # AutoTokenizer so Transformer.__init__ picks up our pre-fixed tokenizer.
+        # On sentence-transformers >=5.4 `tokenizer` is a read-only @property
+        # backed by `self.processor`, so a post-init assignment raises; the
+        # constructor redirect sets self.processor correctly instead.
         from transformers import AutoProcessor, AutoTokenizer
 
         def is_requested_model_name(args, kwargs):
@@ -1112,10 +1052,9 @@ class FastSentenceTransformer(FastModel):
                 elif "tokenizer_args" in transformer_init_params:
                     transformer_kwargs["tokenizer_args"] = trust_remote_code_kwargs.copy()
 
-                # Initialize Transformer
                 transformer_module = Transformer(model_name, **transformer_kwargs)
             finally:
-                # Restore original functionality immediately
+                # Restore original Auto* loading immediately
                 AutoModel.from_pretrained = original_model_from_pretrained
                 AutoProcessor.from_pretrained = original_processor_from_pretrained
                 AutoTokenizer.from_pretrained = original_tokenizer_from_pretrained
@@ -1197,8 +1136,7 @@ class FastSentenceTransformer(FastModel):
         pooling_mode,
         trust_remote_code = False,
     ) -> tuple[OrderedDict, bool]:
-        """
-        Load modules from modules.json if available, otherwise fallback to hard-coded modules.
+        """Load modules from modules.json, else fall back to hard-coded modules.
 
         Returns:
             tuple[OrderedDict, bool]: (modules, no_modules_json)
@@ -1286,19 +1224,12 @@ class FastSentenceTransformer(FastModel):
         grad_accum = None,
         max_seq_length = None,
     ):
-        """
-        Estimate the minimum training steps needed for torch.compile to be beneficial.
-        Returns the threshold with a 1.2x safety margin built in.
+        """Estimate the minimum training steps for torch.compile to pay off
+        (with a 1.2x safety margin), from empirical benchmarks.
 
-        Based on empirical benchmarks:
-        - Larger models have lower breakeven (more time saved per step)
-        - Warmup time scales with model size but speedup also increases
-
-        Optional inputs (batch_size, grad_accum, max_seq_length) allow
-        a coarse pre-run adjustment. These are intentionally conservative
-        and avoid any runtime measurements.
+        Optional batch_size / grad_accum / max_seq_length give a coarse,
+        conservative pre-run adjustment with no runtime measurements.
         """
-        # Get parameter count from inner model
         if hasattr(model, "__getitem__"):
             try:
                 inner = model[0].auto_model
@@ -1399,10 +1330,8 @@ class FastSentenceTransformer(FastModel):
 
     @staticmethod
     def _apply_torch_compile(model, mode = "default"):
-        """
-        Apply torch.compile to a SentenceTransformer model.
-        Includes workaround for accelerate's unwrap_model bug.
-        """
+        """Apply torch.compile to a SentenceTransformer model (with an
+        accelerate unwrap_model bug workaround)."""
         if hasattr(model, "__getitem__"):
             inner_model = model[0].auto_model
             compiled = torch.compile(inner_model, mode = mode)
@@ -1465,12 +1394,10 @@ class FastSentenceTransformer(FastModel):
             ):
                 st_device = None
 
-            # this was added because when loading for inference it was defaulting to float32
-            # propagate dtype to model_kwargs, default to "auto"
+            # Propagate dtype to model_kwargs (else inference defaults to float32)
             model_kwargs = kwargs.get("model_kwargs", {})
             model_kwargs["dtype"] = dtype if dtype is not None else "auto"
 
-            # filter kwargs for SentenceTransformer
             st_kwargs = {
                 "device": st_device,
                 "trust_remote_code": trust_remote_code,
@@ -1479,7 +1406,6 @@ class FastSentenceTransformer(FastModel):
                 "model_kwargs": model_kwargs,
             }
 
-            # add other known kwargs if present
             known_keys = [
                 "cache_folder",
                 "truncate_dim",
@@ -1694,7 +1620,7 @@ class FastSentenceTransformer(FastModel):
             if supported:
                 kwargs["add_pooling_layer"] = False
 
-        # forces fp8 to be False since it's not supported
+        # fp8 is not supported, force it off
         fp8 = kwargs.pop("load_in_fp8", None)
         if fp8:
             logging.info("Unsloth: Disabling fp8 for model")
@@ -1718,9 +1644,8 @@ class FastSentenceTransformer(FastModel):
         elif is_mpnet:
             FastSentenceTransformer._patch_mpnet_v5()
 
-        # check if modules.json exists - if not, force 16-bit training
-        # why? because i have to implement saving myself for these models, and i don't feel like adding dequantization
-        # to the save_pretrained_merged for a model that really should be trained in 16-bit anyway
+        # No modules.json -> force 16-bit: saving is custom for these models and
+        # 4-bit would need dequant in save_pretrained_merged, not worth it.
         has_modules_json = FastSentenceTransformer._module_path(model_name, token) is not None
 
         if not has_modules_json and load_in_4bit:
@@ -1762,7 +1687,6 @@ class FastSentenceTransformer(FastModel):
         finally:
             os.environ["UNSLOTH_WARN_UNINITIALIZED"] = old_environ
 
-        # try to load modules, otherwise fallback to old hard-coded modules
         from sentence_transformers import SentenceTransformer
 
         modules, no_modules = FastSentenceTransformer._load_modules(
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 3e779a46b1..500c6509a4 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -299,7 +299,6 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
     if do_bfloat16_mixed_precision:
         dtype = torch.bfloat16
 
-    # Check if VLM
     is_vlm = any(
         x.endswith(("ForConditionalGeneration", "ForVisionText2Text"))
         for x in self.config.architectures
@@ -319,8 +318,7 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
     global NUM_LOGITS_TO_KEEP
     if arch not in NUM_LOGITS_TO_KEEP:
         m = self
-        # Find which is needed ie
-        # num_logits_to_keep or logits_to_keep
+        # Find which is used: num_logits_to_keep or logits_to_keep
         while hasattr(m, "model"):
             if hasattr(m, "forward"):
                 keys = inspect.signature(m.forward).parameters.keys()
@@ -337,7 +335,6 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
     if key is not None and key not in kwargs:
         kwargs[key] = 1
 
-    # Check pad_token
     model_eos_token_id = getattr(self.config, "eos_token_id", None)
     if model_eos_token_id is not None and hasattr(model_eos_token_id, "__iter__"):
         model_eos_token_id = model_eos_token_id[0]
@@ -424,7 +421,6 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
             except:
                 pass
 
-    # DO INFERENCE
     with torch.inference_mode(), autocaster:
         output = self._old_generate(*args, **kwargs)
 
diff --git a/unsloth/optimizers/q_galore_adamw.py b/unsloth/optimizers/q_galore_adamw.py
index 1f4219d69a..9acd597f61 100644
--- a/unsloth/optimizers/q_galore_adamw.py
+++ b/unsloth/optimizers/q_galore_adamw.py
@@ -34,7 +34,7 @@ try:
     _HAS_BNB = True
 except ImportError:
     _HAS_BNB = False
-    # Provide a fallback base so the module can at least be imported.
+    # Fallback base so the module can still be imported.
     Optimizer2State = torch.optim.Optimizer
 
 
@@ -99,10 +99,6 @@ class QGaLoreAdamW8bit(Optimizer2State):
             is_paged = is_paged,
         )
 
-    # ------------------------------------------------------------------
-    # Core step
-    # ------------------------------------------------------------------
-
     @torch.no_grad()
     def step(self, closure = None):
         """Perform a single optimization step.
@@ -173,8 +169,7 @@ class QGaLoreAdamW8bit(Optimizer2State):
 
                     grad = state["projector"].project(p.grad, state["step"])
 
-                    # Save current weight; replace p.data with zeros so
-                    # the 8-bit update writes the pure weight delta.
+                    # Zero p.data so the 8-bit update writes the pure delta.
                     p._saved_data = p.data.clone()
                     p.data = torch.zeros_like(grad, dtype = p.data.dtype, device = p.data.device)
                     p.grad = grad
@@ -213,9 +208,9 @@ class QGaLoreAdamW8bit(Optimizer2State):
                     p._q_scales = scales
                     p._q_zeros = zeros
                     p._q_shape = shape
-                    # Replace p.data with a scalar placeholder to free float memory.
-                    # A forward pre-hook (install_weight_quant_hooks) will
-                    # dequantize back to float before the next forward pass.
+                    # Scalar placeholder to free float memory; the forward
+                    # pre-hook (install_weight_quant_hooks) dequantizes before
+                    # the next forward pass.
                     p.data = torch.empty(1, dtype = p.data.dtype, device = p.data.device)
 
                 state["step"] += 1
@@ -225,10 +220,6 @@ class QGaLoreAdamW8bit(Optimizer2State):
 
         return loss
 
-    # ------------------------------------------------------------------
-    # Helpers
-    # ------------------------------------------------------------------
-
     @staticmethod
     def _has_weight_quant(p: torch.Tensor, group: dict) -> bool:
         """Check if this parameter uses INT8 weight quantization."""
@@ -260,10 +251,9 @@ class QGaLoreAdamW8bit(Optimizer2State):
 
         for name, p in model.named_parameters():
             if id(p) in weight_quant_params:
-                # Store quantization metadata WITHOUT converting weights to
-                # uint8.  The first optimizer.step() will quantize after the
-                # update.  We store dummy scales/zeros so _has_weight_quant()
-                # returns True on the first step.
+                # Store metadata without converting weights to uint8; the first
+                # step() quantizes after the update. Dummy scales/zeros keep
+                # _has_weight_quant() True on the first step.
                 p._q_scales = None
                 p._q_zeros = None
                 p._q_shape = p.data.shape
@@ -298,10 +288,6 @@ def install_weight_quant_hooks(model: torch.nn.Module) -> list:
     return handles
 
 
-# ======================================================================
-# Param-group construction helper
-# ======================================================================
-
 # Default linear layer names in transformer blocks that should use GaLore.
 _DEFAULT_GALORE_TARGETS = {
     "q_proj",
@@ -369,9 +355,8 @@ def make_q_galore_param_groups(
         if not param.requires_grad:
             continue
 
-        # Check if any target module name appears as a component in the param name.
-        # Exclude 1-D parameters (biases, norms) because GaLoreProjector.project
-        # requires 2-D gradients.
+        # Match target module names; exclude 1-D params (biases, norms) since
+        # GaLoreProjector.project requires 2-D gradients.
         name_parts = name.split(".")
         is_galore = param.dim() >= 2 and any(t in name_parts for t in targets)
 
diff --git a/unsloth/optimizers/q_galore_projector.py b/unsloth/optimizers/q_galore_projector.py
index 809e15512c..3fba75e5b3 100644
--- a/unsloth/optimizers/q_galore_projector.py
+++ b/unsloth/optimizers/q_galore_projector.py
@@ -27,22 +27,16 @@ class GaLoreProjector:
     """Low-rank gradient projector with optional INT4/INT8 quantized projection
     matrices and layer-adaptive subspace update scheduling.
 
-    The projector computes an SVD of the gradient to obtain an orthogonal basis
-    for the top-``rank`` subspace.  Gradients are projected into this subspace
-    for the optimizer step, then projected back to full rank for the weight
-    update.
+    SVD of the gradient gives an orthogonal basis for the top-``rank`` subspace.
+    Gradients are projected in for the optimizer step, then back to full rank for
+    the weight update. Two Q-GaLore innovations:
 
-    Two key Q-GaLore innovations are implemented:
-
-    1. **Quantized projection matrices** — when ``quant=True``, the orthogonal
-       matrix is stored in INT4/INT8, reducing the memory cost of keeping the
-       projector state.
-
-    2. **Layer-adaptive update scheduling** — a rolling queue of cosine
-       similarities between consecutive orthogonal vectors is maintained.  When
-       the average exceeds ``cos_threshold``, ``update_proj_gap`` is multiplied
-       by ``gamma_proj``, effectively reducing the frequency of expensive SVD
-       recomputations for layers whose subspace has stabilized.
+    1. Quantized projection matrices: with ``quant=True`` the orthogonal matrix
+       is stored in INT4/INT8 to cut projector-state memory.
+    2. Layer-adaptive update scheduling: when the rolling-average cosine
+       similarity of consecutive orthogonal vectors exceeds ``cos_threshold``,
+       ``update_proj_gap`` is multiplied by ``gamma_proj`` to recompute SVD less
+       often for stabilized layers.
 
     Args:
         rank: Target rank for the low-rank projection.
diff --git a/unsloth/registry/__init__.py b/unsloth/registry/__init__.py
index dede85329f..6880f80f85 100644
--- a/unsloth/registry/__init__.py
+++ b/unsloth/registry/__init__.py
@@ -33,12 +33,9 @@ def search_models(
     search_pattern: str = None,
 ) -> list[ModelInfo]:
     """
-    Get model info from the registry.
-
-    See registry.ModelInfo for more fields.
-
-    If search_pattern is provided, the full model path will be matched against the pattern, where the model path is the model_id on huggingface hub.
+    Get model info from the registry. See registry.ModelInfo for more fields.
 
+    search_pattern is matched against the full model path (the HF hub model_id).
     """
     if not _ARE_MODELS_REGISTERED:
         register_models()
diff --git a/unsloth/registry/registry.py b/unsloth/registry/registry.py
index 009223088c..b6aa5038de 100644
--- a/unsloth/registry/registry.py
+++ b/unsloth/registry/registry.py
@@ -33,9 +33,7 @@ class ModelInfo:
     base_name: str
     version: str
     size: int
-    name: str = (
-        None  # full model name, constructed from base_name, version, and size unless provided
-    )
+    name: str = None  # constructed from base_name, version, size unless provided
     is_multimodal: bool = False
     instruct_tag: str = None
     quant_type: QuantType = None
@@ -168,7 +166,7 @@ def _register_models(model_meta: ModelMeta, include_original_model: bool = False
                 _quant_types = quant_types
             for quant_type in _quant_types:
                 # NOTE: models registered with org="unsloth" and QUANT_TYPE.NONE are aliases of QUANT_TYPE.UNSLOTH
-                _org = "unsloth"  # unsloth models -- these are all quantized versions of the original model
+                _org = "unsloth"  # quantized versions of the original model
                 register_model(
                     model_info_cls = model_info_cls,
                     org = _org,
diff --git a/unsloth/save.py b/unsloth/save.py
index a44f186e40..4ff56cc477 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -160,10 +160,8 @@ def _quantize_q2_k_l(
     n_threads: int,
     print_output: bool = True,
 ):
-    # "Q2_K_L" is a Unsloth-side preset, not a native llama.cpp ftype. It
-    # maps to the `q2_k` ftype with `--output-tensor-type q8_0` and
-    # `--token-embedding-type q8_0` so the output/embedding tensors retain
-    # higher precision than a plain Q2_K quant.
+    # "Q2_K_L" is an Unsloth preset, not a native llama.cpp ftype: q2_k with
+    # output/token-embedding tensors kept at q8_0 for higher precision.
     command = [
         str(quantizer_location),
         "--output-tensor-type",
@@ -1045,9 +1043,8 @@ def unsloth_save_model(
     # Check if pushing to an organization
     if save_pretrained_settings["push_to_hub"] and (username != actual_username):
         print(f"Unsloth: Saving to organization with address {new_save_directory}")
-        # Pushing to organization!
-        # Sadly .save_pretrained doesn't work :(
-        # We first save it via .save_pretrained, then upload manually!
+        # Pushing to organization: .save_pretrained doesn't work, so save
+        # locally first then upload manually.
         save_pretrained_settings["save_directory"] = new_save_directory
         save_pretrained_settings["push_to_hub"] = False
         internal_model.save_pretrained(**save_pretrained_settings)
@@ -2226,9 +2223,8 @@ def unsloth_save_pretrained_gguf(
         except Exception as e:
             raise RuntimeError(f"Failed to save/merge model: {e}")
     else:
-        # Non-PEFT model — checkpoint files already exist on disk.
-        # Point save_to_gguf at the original checkpoint path instead of
-        # re-saving to a temporary "model" subdirectory.
+        # Non-PEFT model: checkpoint files already exist; point save_to_gguf
+        # at the original path instead of re-saving to a temp subdir.
         original_path = getattr(self.config, "_name_or_path", None)
         if original_path and os.path.isdir(original_path):
             print(
@@ -3004,10 +3000,8 @@ def unsloth_generic_save(
     elif save_method == "merged_4bit_forced":
         save_method = "merged_4bit"
 
-    # Full-finetuned models (no LoRA) cannot use merge_and_overwrite_lora
-    # since there are no adapters to merge. Fall back to save_pretrained.
-    # This mirrors the non-PeftModel handling in save_pretrained_torchao
-    # and the GGUF save path.
+    # Full-finetuned models (no LoRA) have no adapters to merge, so fall back
+    # to save_pretrained, mirroring the torchao and GGUF save paths.
     _is_peft = isinstance(model, PeftModel)
     if not _is_peft:
         if not is_main_process:
diff --git a/unsloth/tokenizer_utils.py b/unsloth/tokenizer_utils.py
index 556b2e53e2..f454d5c504 100644
--- a/unsloth/tokenizer_utils.py
+++ b/unsloth/tokenizer_utils.py
@@ -419,15 +419,13 @@ def fix_sentencepiece_tokenizer(
 
 def fix_sentencepiece_gguf(saved_location):
     """
-    Fixes sentencepiece tokenizers which did not extend the vocabulary with
-    user defined tokens.
-    Inspiration from https://github.com/ggerganov/llama.cpp/blob/master/convert_hf_to_gguf.py
+    Fix sentencepiece tokenizers that didn't extend the vocab with user-defined
+    tokens. Inspired by llama.cpp's convert_hf_to_gguf.py.
 
-    Also fixes special tokens (e.g. Gemma 3's <start_of_turn>/<end_of_turn>) that are
-    already present in the sentencepiece model but are incorrectly typed as NORMAL instead
-    of CONTROL. This causes them to be written to GGUF with token_type=1 (NORMAL) instead
-    of token_type=3 (CONTROL), which breaks chat inference in llama.cpp since parse_special
-    only matches CONTROL tokens.
+    Also retypes special tokens (e.g. Gemma 3's <start_of_turn>/<end_of_turn>)
+    that exist in the sentencepiece model but are typed NORMAL instead of CONTROL.
+    NORMAL writes token_type=1 to GGUF, breaking llama.cpp chat inference since
+    parse_special only matches CONTROL (type=3).
     """
     from copy import deepcopy
     import sys
@@ -1436,9 +1434,8 @@ def check_tokenizer(
 def get_tokenizer_info(tokenizer) -> dict:
     """Return a concise diagnostic summary of a tokenizer instance.
 
-    Collects key properties into a plain dict suitable for logging, debugging,
-    or displaying in the Unsloth Studio UI. All fields are safe to access —
-    missing attributes fall back to ``None`` rather than raising.
+    Collects key properties into a JSON-safe dict for logging, debugging, or the
+    Studio UI. Missing attributes fall back to ``None`` rather than raising.
 
     Example output::
 
@@ -1459,11 +1456,10 @@ def get_tokenizer_info(tokenizer) -> dict:
         }
 
     Args:
-        tokenizer: Any HuggingFace ``PreTrainedTokenizer`` or
-                   ``PreTrainedTokenizerFast`` instance.
+        tokenizer: Any HuggingFace ``PreTrainedTokenizer(Fast)`` instance.
 
     Returns:
-        A ``dict`` of tokenizer properties. Safe to serialize to JSON.
+        A ``dict`` of tokenizer properties.
     """
     return {
         "name_or_path": getattr(tokenizer, "name_or_path", None),
diff --git a/unsloth/trainer.py b/unsloth/trainer.py
index c5df9516df..9b80b10705 100644
--- a/unsloth/trainer.py
+++ b/unsloth/trainer.py
@@ -268,20 +268,19 @@ class UnslothTrainer(SFTTrainer):
 
         # --- Split embedding params with custom LR (Fix #2) ---
         if embedding_lr is not None:
-            # Build a fast param->name lookup (O(N) instead of O(N*M))
+            # Fast param->name lookup (O(N) instead of O(N*M))
             param_to_name = {id(p): name for name, p in self.model.named_parameters()}
 
             new_groups = []
             for group in param_groups:
                 if "rank" in group:
-                    # GaLore group — keep as-is (embeddings are never in here)
+                    # GaLore group: keep as-is (no embeddings here)
                     new_groups.append(group)
                     continue
                 # Non-GaLore group: split out embedding params
                 embed_params = []
                 other_params = []
                 for p in group["params"]:
-                    # Check if this param belongs to a modules_to_save embedding
                     name = param_to_name.get(id(p))
                     if name and name.endswith("modules_to_save.default.weight"):
                         partial_name = name[: -len(".modules_to_save.default.weight")]
@@ -312,7 +311,6 @@ class UnslothTrainer(SFTTrainer):
             eps = self.args.adam_epsilon,
         )
 
-        # Initialize INT8 weight quantization if enabled
         if config.weight_quant:
             QGaLoreAdamW8bit.init_weight_quantization(
                 self.model,
@@ -320,9 +318,8 @@ class UnslothTrainer(SFTTrainer):
                 group_size = config.weight_group_size,
                 stochastic = config.stochastic_round,
             )
-            # Forward pre-hooks dequantize INT8 weights to float before each
-            # forward pass, allowing the optimizer to free float weight memory
-            # between steps.
+            # Pre-hooks dequantize INT8 weights to float before each forward,
+            # letting the optimizer free float weight memory between steps.
             install_weight_quant_hooks(self.model)
 
         n_galore = sum(len(g["params"]) for g in param_groups if "rank" in g)
@@ -341,9 +338,8 @@ class UnslothTrainer(SFTTrainer):
 def _resolve_trainer_params(trainer_class, init_fn):
     """Resolve the real named parameters for a trainer __init__.
 
-    Some TRL trainers (e.g., ORPOTrainer in TRL 0.27.1) are thin wrappers
-    with only ``def __init__(self, *args, **kwargs)``.  For those, walk the
-    MRO and return the first parent class that has real named parameters.
+    Some TRL trainers are thin ``*args, **kwargs`` wrappers; for those, walk the
+    MRO and return the first parent with real named parameters.
     """
     params = inspect.signature(init_fn).parameters
     named = {
@@ -386,7 +382,7 @@ def _backwards_compatible_trainer(trainer_class, config_class):
 
     @wraps(original_init)
     def new_init(self, *args, **kwargs):
-        # All Trainer tokenizer are now called processing_class
+        # tokenizer is now processing_class
         trainer_params = _resolve_trainer_params(trainer_class, original_init)
 
         if "processing_class" in trainer_params and "tokenizer" in kwargs:
@@ -395,23 +391,21 @@ def _backwards_compatible_trainer(trainer_class, config_class):
         if ("args" in kwargs) and (Version(trl) >= Version("0.13.0.dev0")):
             training_args = kwargs.pop("args", None)
 
-            # Get parameters that Trainer.__init__ actually expects
             trainer_params.remove("self")
             trainer_params.remove("args")
 
-            # Get fields that should be passed to Config init
+            # Fields that should be passed to Config init
             config_fields = {
                 field.name: field for field in dataclasses.fields(config_class) if field.init
             }
 
-            # Create config dict with valid fields from training_args
             config_dict = {
                 name: getattr(training_args, name)
                 for name in config_fields
                 if hasattr(training_args, name)
             }
 
-            # Get parameters that exist in Config but not in TrainingArguments
+            # Params in Config but not in TrainingArguments
             from transformers import TrainingArguments
 
             moved_params = set(inspect.signature(config_class).parameters.keys()) - set(
@@ -430,14 +424,11 @@ def _backwards_compatible_trainer(trainer_class, config_class):
                 else:
                     additional_config_kwargs[key] = value
 
-            # Update config_dict with additional kwargs
             config_dict.update(additional_config_kwargs)
 
-            # Create Config with all the collected parameters
-            # Reinitialising config class with parameters (that were none initially but populated on first init)
-            # causes the 2nd init to fail as there are mutual exclusive checks on pairs of parameters.
-            # Refer: https://github.com/huggingface/trl/blob/main/trl/trainer/grpo_config.py#L499-L502 for example
-            # So we only create config class if the previous init was not TrainingArguments
+            # Only build the config if the previous init wasn't TrainingArguments:
+            # reinitialising it would re-trigger mutually-exclusive param checks.
+            # See https://github.com/huggingface/trl/blob/main/trl/trainer/grpo_config.py#L499-L502
             if not isinstance(training_args, TrainingArguments):
                 config = config_class(**config_dict)
             else:
@@ -468,7 +459,6 @@ def _patch_sft_trainer_auto_packing(trl_module):
         else:
             config_arg = kwargs.get("args")
 
-        # Check if model type is unsupported for padding_free
         model = kwargs.get("model")
         is_unsupported_model = False
         is_vlm = False
@@ -476,10 +466,8 @@ def _patch_sft_trainer_auto_packing(trl_module):
             model_config = getattr(model, "config", None)
             if model_config is not None:
                 model_types = get_transformers_model_type(model_config)
-                # Blocklist: models that don't work correctly with padding_free
                 is_unsupported_model = any(x in PADDING_FREE_BLOCKLIST for x in model_types)
 
-                # Check if VLM
                 architectures = getattr(model_config, "architectures", None)
                 if architectures is None:
                     architectures = []
@@ -489,7 +477,7 @@ def _patch_sft_trainer_auto_packing(trl_module):
         processing_class = kwargs.get("processing_class") or kwargs.get("tokenizer")
         data_collator = kwargs.get("data_collator")
 
-        # We also disable vision language models for padding free collators
+        # Disable padding-free for VLMs / custom collators / blocklisted models
         blocked = (
             (data_collator is not None)
             or isinstance(processing_class, ProcessorMixin)
diff --git a/unsloth/utils/attention_dispatch.py b/unsloth/utils/attention_dispatch.py
index 8f10d7570a..3ff581b7fc 100644
--- a/unsloth/utils/attention_dispatch.py
+++ b/unsloth/utils/attention_dispatch.py
@@ -56,11 +56,9 @@ class AttentionConfig:
     """
     Per-layer attention metadata.
 
-    NOTE(djsaunde): I had originally intended this to be populated once per layer, but
-        we're currently constructing it on every forward pass since it can possibly be
-        invalid from one forward pass to the next (e.g., switching from training to
-        inference). For now, I'm keeping separate from AttentionContext for the sake of
-        better grouping of params.
+    NOTE(djsaunde): Constructed on every forward pass (not once per layer) since
+        it can be invalid across passes (e.g. switching training/inference). Kept
+        separate from AttentionContext to group params.
     """
 
     backend: str
@@ -107,25 +105,18 @@ def run_attention(
     """
     Run attention using config / context info.
 
-    Backend choice is prioritized for speed: FlashAttention when installed
-    (`flash_varlen` for packed/variable-length inputs with `seq_info`, otherwise dense
-    flash), then xFormers if flash is unavailable, with PyTorch SDPA as the final
-    fallback (e.g., CPU or no fused kernels).
-
-    Varlen flash is preferred when packing metadata is present because it avoids padding
-    and keeps peak memory low. xFormers and SDPA can also handle packed batches (we
-    pass a block-diagonal mask into each).
+    Backend priority (speed): FlashAttention if installed (varlen for packed
+    inputs with `seq_info`, else dense), then xFormers, then SDPA as fallback.
+    Varlen flash is preferred for packed batches as it avoids padding; xFormers
+    and SDPA handle packing via a block-diagonal mask.
     """
 
     backend = config.backend
     if backend == FLASH_VARLEN and context.seq_info is None:
         backend = FLASH_DENSE if HAS_FLASH_ATTENTION else SDPA
 
-    # [TODO] Flash attention does not support arbitrary attention masks (only
-    # causal via flag). When a padding mask is present (e.g. left-padded
-    # batched generation), fall back to SDPA which consumes attn_mask.
-    # xFormers also does not thread context.attention_mask through, so the
-    # same fallback applies.
+    # [TODO] Flash/xFormers don't support arbitrary attn masks; with a padding
+    # mask present (e.g. left-padded generation), fall back to SDPA.
     if context.attention_mask is not None and backend in (
         FLASH_DENSE,
         FLASH_VARLEN,
diff --git a/unsloth/utils/hf_hub.py b/unsloth/utils/hf_hub.py
index e3960ba0ce..b349e568f6 100644
--- a/unsloth/utils/hf_hub.py
+++ b/unsloth/utils/hf_hub.py
@@ -30,9 +30,8 @@ def get_model_info(
     """
     Get the model info for a specific model.
 
-    properties: list[str] = See https://huggingface.co/docs/huggingface_hub/api-ref/hf_hub/hf_api/model_info
-    Default properties: ["safetensors", "lastModified"], only retrieves minimal information.
-    Set to None to retrieve the full model information.
+    properties: see https://huggingface.co/docs/huggingface_hub/api-ref/hf_hub/hf_api/model_info
+    Defaults to minimal info; set to None for the full model information.
     """
     global _HFAPI
     if _HFAPI is None:
@@ -56,12 +55,9 @@ def list_models(
     """
     Retrieve model information from the Hugging Face Hub.
 
-    properties: list[str] = See https://huggingface.co/docs/huggingface_hub/api-ref/hf_hub/hf_api/list_models
-    full: bool = Whether to retrieve the full model information, if True properties will be ignored.
-    sort: str = The sort order.
-    author: str = The author of the model.
-    search: str = The search query for filtering models.
-
+    properties: see https://huggingface.co/docs/huggingface_hub/api-ref/hf_hub/hf_api/list_models
+    full: retrieve full model info; if True, properties is ignored.
+    sort/author/search: sort order, model author, and search filter.
     """
     global _HFAPI
     if _HFAPI is None:
diff --git a/unsloth_cli/_tool_policy.py b/unsloth_cli/_tool_policy.py
index 5dd6c70d9f..58caacbff0 100644
--- a/unsloth_cli/_tool_policy.py
+++ b/unsloth_cli/_tool_policy.py
@@ -10,12 +10,10 @@ from typing import Callable, Optional
 
 import typer
 
-# Claude Code brand orange — used so the security warning stands out
-# in a crowded terminal.
+# Orange so the security warning stands out in a crowded terminal.
 _PROMPT_FG = (217, 119, 87)
 
-# Loopback aliases. Any other bind address (0.0.0.0, ::, a specific
-# LAN IP, a hostname, ...) is treated as network-reachable.
+# Loopback aliases; any other bind address is treated as network-reachable.
 _LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
 
 
@@ -47,14 +45,11 @@ def resolve_tool_policy(
     """Return the resolved server-side tool policy.
 
     Args:
-        host: The bind address (e.g. "127.0.0.1", "0.0.0.0", or a
-              specific network IP).
-        flag: Tri-state from `--enable-tools/--disable-tools`
-              (None when neither was passed).
-        yes:  True if the operator passed `--yes/-y`.
-        silent: True if the operator passed `--silent/-q`.
-        prompt: Callable used for the network-bind + on confirmation
-                (injected for testability; defaults to ``typer.confirm``).
+        host: The bind address.
+        flag: Tri-state from `--enable-tools/--disable-tools` (None if neither passed).
+        yes: True if `--yes/-y` was passed.
+        silent: True if `--silent/-q` was passed.
+        prompt: Confirmation callable (injected for testability).
 
     Raises:
         typer.Exit: when the operator declines the confirmation.
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index b889a1e3bc..a458f195b4 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -738,11 +738,10 @@ def _split_repo_variant(model_arg: str) -> tuple[str, Optional[str]]:
 
 
 def _expand_attached_np_short() -> None:
-    # Click clusters `-np8` as `-n -p 8` (-p = --port), dropping the
-    # parallel value. Split to `-np <N>` so typer's alias matches.
-    # Stops at `--`; accepts signed and digit-prefix-junk forms so
-    # typer can report a clean error against `-np`. Kept in lockstep
-    # with the backend `_flag_name` recogniser.
+    # Click clusters `-np8` as `-n -p 8` (-p = --port), dropping the parallel
+    # value. Split to `-np <N>` so typer's alias matches. Stops at `--`;
+    # accepts signed/junk forms so typer reports a clean error against `-np`.
+    # Kept in lockstep with the backend `_flag_name` recogniser.
     i = 0
     while i < len(sys.argv):
         tok = sys.argv[i]
@@ -1210,14 +1209,10 @@ def _run_setup_script(*, verbose: bool = False) -> None:
             powershell_args.extend(
                 ["-NoLogo", "-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden"]
             )
-        # Use -Command + `*>&1` instead of -File so setup.ps1's
-        # Write-Host output (PowerShell Information stream / #6) is
-        # merged into the success stream and reaches the parent's
-        # stdout. With -File, Information stream output is dropped
-        # whenever stdout is a pipe, which is exactly the situation
-        # CI hits with `unsloth studio update --local 2>&1 | tee
-        # logs/update.log`. Single-quote escaping handles paths that
-        # contain apostrophes.
+        # Use -Command + `*>&1` (not -File) so setup.ps1's Write-Host output
+        # (Information stream #6) merges into stdout. -File drops it when
+        # stdout is a pipe, e.g. `unsloth studio update --local 2>&1 | tee`.
+        # Single-quote escaping handles paths containing apostrophes.
         script_pwsh_literal = str(script).replace("'", "''")
         powershell_args.extend(
             [
@@ -1227,20 +1222,13 @@ def _run_setup_script(*, verbose: bool = False) -> None:
                 f"& '{script_pwsh_literal}' *>&1",
             ]
         )
-        # Explicitly hand stdin/stdout/stderr to the child so the
-        # CI tee actually sees setup.ps1's output. Without this,
-        # subprocess.run on Windows uses close_fds=True (default,
-        # since Python 3.7) which sets bInheritHandles=False on
-        # CreateProcess. With CREATE_NO_WINDOW also set (via
-        # _windows_hidden_subprocess_kwargs in non-TTY runs), the
-        # child has neither a console nor any inherited std
-        # handles, so PowerShell's Write-Host -- and even
-        # [Console]::Out.WriteLine -- writes to nothing. Passing
-        # stdout=sys.stdout / stderr=sys.stderr makes Python set up
-        # PROC_THREAD_ATTRIBUTE_HANDLE_LIST with the std handles
-        # explicitly inheritable, which works alongside
-        # CREATE_NO_WINDOW. Empty update.log on the windows-latest
-        # CI was the smoking gun (run 25533694490 and 25534292239).
+        # Explicitly hand std handles to the child so CI tee sees setup.ps1's
+        # output. On Windows, subprocess.run defaults to close_fds=True
+        # (bInheritHandles=False); combined with CREATE_NO_WINDOW the child
+        # has no console and no inherited handles, so Write-Host writes to
+        # nothing. Passing stdout/stderr makes Python mark the std handles
+        # inheritable via PROC_THREAD_ATTRIBUTE_HANDLE_LIST. Empty update.log
+        # on windows-latest CI was the smoking gun (runs 25533694490/25534292239).
         result = subprocess.run(
             powershell_args,
             env = env,
diff --git a/unsloth_cli/commands/train.py b/unsloth_cli/commands/train.py
index 88a9594639..9d47a574d5 100644
--- a/unsloth_cli/commands/train.py
+++ b/unsloth_cli/commands/train.py
@@ -41,8 +41,8 @@ def train(
 
     cfg.apply_overrides(**config_overrides)
 
-    # CLI/env tokens take precedence over config
-    # Handle case where typer.Option isn't resolved (decorator interaction)
+    # CLI/env tokens take precedence; guard against unresolved typer.Option
+    # (decorator interaction)
     from typer.models import OptionInfo
 
     if isinstance(hf_token, OptionInfo):
@@ -68,7 +68,7 @@ def train(
         typer.echo("Error: provide --dataset or --local-dataset (or via --config)", err = True)
         raise typer.Exit(code = 2)
 
-    # Check if the model path is a LoRA adapter (has adapter_config.json)
+    # A LoRA adapter dir has adapter_config.json
     model_path = Path(cfg.model) if cfg.model else None
     model_is_lora = (
         model_path and model_path.is_dir() and (model_path / "adapter_config.json").exists()
diff --git a/unsloth_cli/config.py b/unsloth_cli/config.py
index 3cfa87ec6d..8192f7d749 100644
--- a/unsloth_cli/config.py
+++ b/unsloth_cli/config.py
@@ -78,9 +78,8 @@ class Config(BaseModel):
 
     def model_kwargs(self, use_lora: bool, is_vision: bool) -> dict:
         """Return kwargs for trainer.prepare_model_for_training()."""
-        # Determine target modules based on model type
         if use_lora and is_vision:
-            # Vision models expect a string (e.g., "all-linear"); fall back to None to use trainer defaults
+            # Vision models expect a string (e.g. "all-linear"); None uses trainer defaults
             target_modules = "all-linear" if self.lora.vision_all_linear else None
         else:
             parsed = [
diff --git a/unsloth_cli/options.py b/unsloth_cli/options.py
index 4a2470ac00..03c7540faa 100644
--- a/unsloth_cli/options.py
+++ b/unsloth_cli/options.py
@@ -49,7 +49,7 @@ def _get_python_type(annotation: Any) -> type:
 
 def _collect_config_fields(config_class: type[BaseModel]) -> list[tuple[str, Any]]:
     """
-    Collect all fields from a config class, flattening nested models. Returns list of
+    Flatten config class fields (recursing into nested models) into a list of
     (name, field_info) tuples. Raises ValueError on duplicate field names.
     """
     fields = []
@@ -57,7 +57,7 @@ def _collect_config_fields(config_class: type[BaseModel]) -> list[tuple[str, Any
 
     for name, field_info in config_class.model_fields.items():
         annotation = field_info.annotation
-        # Skip nested models - recurse into them
+        # Recurse into nested models
         if isinstance(annotation, type) and issubclass(annotation, BaseModel):
             for nested_name, nested_field in annotation.model_fields.items():
                 if nested_name in seen_names:
diff --git a/unsloth_cli/tests/test_studio_run_short_alias_clashes.py b/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
index 2fb94c37c7..4234eb75f4 100644
--- a/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
+++ b/unsloth_cli/tests/test_studio_run_short_alias_clashes.py
@@ -162,8 +162,7 @@ def test_previously_broken_short_flag_now_passes_through(monkeypatch, flag, valu
 
 
 def test_dash_hf_documented_alias_still_works(monkeypatch):
-    """`-hf` is documented and must keep working (multi-char shorts
-    don't cluster in Click)."""
+    """`-hf` must keep working: multi-char shorts don't cluster in Click."""
     captured = _invoke(
         monkeypatch,
         ["-hf", "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL"],
@@ -206,8 +205,7 @@ def test_legacy_frontend_alias_still_promotes_to_frontend(monkeypatch):
     captured = _invoke(monkeypatch, ["--model", "X", "-f", "/tmp/dist"])
     assert len(captured) == 1
     argv = captured[0]
-    # Compare via Path so Windows's str(Path("/tmp/dist")) = "\tmp\dist"
-    # doesn't trip the assertion on the same logical path.
+    # Compare via Path: on Windows str(Path("/tmp/dist")) = "\tmp\dist".
     assert Path(argv[argv.index("--frontend") + 1]) == Path("/tmp/dist"), argv
     assert "-f" not in argv, f"-f leaked into child argv: {argv}"
 

From 85314ed1622cbdcbd6621ebf97307606f4baf89d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Mon, 8 Jun 2026 23:10:35 -0700
Subject: [PATCH 117/222] Studio frontend: reduce and tighten code comments
 (#6099)

Trim and tighten code comments across studio/frontend TS/JS. Comment-only: every changed file verified code-identical to main via the TypeScript printer signature comparison.
---
 studio/frontend/src/app/provider.tsx          |  18 +-
 studio/frontend/src/app/routes/__root.tsx     |   4 +-
 studio/frontend/src/app/routes/settings.tsx   |   8 +-
 .../frontend/src/components/app-sidebar.tsx   |  51 ++-
 .../components/assistant-ui/attachment.tsx    |   4 +-
 .../components/assistant-ui/code-plugin.ts    |   4 +-
 .../components/assistant-ui/code-themes.ts    |   9 +-
 .../src/components/assistant-ui/image.tsx     |   5 +-
 .../components/assistant-ui/markdown-text.tsx |  18 +-
 .../assistant-ui/message-timing.tsx           |   7 +-
 .../model-selector/folder-browser.tsx         |  41 +--
 .../assistant-ui/model-selector/pickers.tsx   |  78 ++---
 .../src/components/assistant-ui/reasoning.tsx |   6 +-
 .../src/components/assistant-ui/sources.tsx   |  24 +-
 .../assistant-ui/think-aria-label.ts          |   7 +-
 .../src/components/assistant-ui/thread.tsx    | 216 ++++++------
 .../assistant-ui/tool-call-spinner.tsx        |   6 +-
 .../components/assistant-ui/tool-group.tsx    |   4 +-
 .../assistant-ui/tool-ui-code-execution.tsx   |  14 +-
 .../assistant-ui/tool-ui-image-generation.tsx |  28 +-
 .../assistant-ui/tool-ui-python.tsx           |   2 +-
 .../assistant-ui/tool-ui-render-html.tsx      |   9 +-
 .../assistant-ui/tool-ui-web-search.tsx       |   5 +-
 .../use-intent-aware-autoscroll.tsx           | 276 ++++++---------
 .../src/components/shutdown-dialog.tsx        |   9 +-
 .../src/components/tauri/window-titlebar.tsx  |   2 +-
 studio/frontend/src/config/env.ts             |  10 +-
 studio/frontend/src/features/auth/api.ts      |  12 +-
 .../features/auth/components/auth-form.tsx    |  28 +-
 studio/frontend/src/features/auth/session.ts  |  13 +-
 .../src/features/auth/tauri-auto-auth.ts      |   6 +-
 .../src/features/chat/api-provider-logo.tsx   |   9 +-
 .../src/features/chat/api/chat-adapter.ts     | 327 ++++++++----------
 .../src/features/chat/api/chat-api.ts         |  46 ++-
 .../features/chat/api/openai-containers.ts    |  14 +-
 .../src/features/chat/api/providers-api.ts    |   7 +-
 .../chat/artifacts/artifact-surface.tsx       |   7 +-
 .../features/chat/artifacts/html-frame.tsx    |   5 +-
 .../src/features/chat/artifacts/types.ts      |   4 +-
 .../features/chat/chat-mcp-servers-dialog.tsx |   7 +-
 .../frontend/src/features/chat/chat-page.tsx  | 168 ++++-----
 .../features/chat/chat-providers-dialog.tsx   |  12 +-
 .../src/features/chat/chat-settings-sheet.tsx |  44 +--
 .../chat/components/context-usage-bar.tsx     |   2 +-
 .../chat/components/model-load-status.tsx     |  21 +-
 .../components/openai-code-exec-section.tsx   | 209 +++++------
 studio/frontend/src/features/chat/db.ts       |   5 +-
 .../src/features/chat/external-providers.ts   |  63 ++--
 .../chat/hooks/use-chat-model-runtime.ts      |  65 ++--
 .../chat/hooks/use-chat-search-index.ts       |   7 +-
 .../chat/hooks/use-chat-sidebar-items.ts      |   5 +-
 .../chat/hooks/use-pill-activation-order.ts   |   5 +-
 .../features/chat/hooks/use-transfer-stats.ts |  20 +-
 .../src/features/chat/lib/friendly-names.ts   |  37 +-
 .../src/features/chat/mcp-composer-button.tsx |  15 +-
 .../features/chat/provider-capabilities.ts    | 224 +++++-------
 .../src/features/chat/runtime-provider.tsx    |  45 ++-
 .../src/features/chat/shared-composer.tsx     | 154 ++++-----
 .../chat/stores/chat-runtime-store.ts         | 132 ++++---
 .../frontend/src/features/chat/tour/steps.tsx |   4 +-
 studio/frontend/src/features/chat/types.ts    |  31 +-
 .../frontend/src/features/chat/types/api.ts   |  75 ++--
 .../src/features/chat/types/runtime.ts        |   4 +-
 .../chat/utils/chat-history-storage.ts        |  62 ++--
 .../chat/utils/chat-thread-tombstones.ts      |  10 +-
 .../chat/utils/delete-thread-message.ts       |  17 +-
 .../features/chat/utils/format-transfer.ts    |  20 +-
 .../chat/utils/image-input-support.ts         |  13 +-
 .../chat/utils/parse-assistant-content.ts     |   8 +-
 .../src/features/chat/utils/transfer-stats.ts |  35 +-
 .../src/features/export/api/export-api.ts     |   6 +-
 .../export/components/export-dialog.tsx       |  84 ++---
 .../src/features/export/export-page.tsx       |  13 +-
 .../components/steps/hyperparameters-step.tsx |   8 +-
 .../components/steps/model-selection-step.tsx |   2 +-
 .../components/steps/model-type-step.tsx      |   2 +-
 .../src/features/profile/utils/jwt-subject.ts |   4 +-
 .../profile/utils/resize-image-file.ts        |   4 +-
 .../components/executions/executions-view.tsx |   8 +-
 .../components/inline/inline-model.tsx        |   6 +-
 .../models/local-recipe-model-selector.tsx    |   4 +-
 .../dialogs/models/model-config-dialog.tsx    |   6 +-
 .../hooks/use-recipe-executions.ts            |  21 +-
 .../recipe-studio/recipe-studio-page.tsx      |  44 ++-
 .../recipe-studio/stores/recipe-studio.ts     |   7 +-
 .../recipe-studio/utils/graph/fit-view.ts     |  15 +-
 .../utils/graph/recipe-graph-connection.ts    |   8 +-
 .../features/recipe-studio/utils/layout.ts    |  24 +-
 .../utils/payload/builders-model.ts           |   9 +-
 .../utils/payload/builders-sampler.ts         |   2 +-
 .../settings/components/create-key-form.tsx   |   5 +-
 .../src/features/settings/settings-dialog.tsx |  15 +-
 .../settings/stores/settings-dialog-store.ts  |   8 +-
 .../features/settings/stores/theme-store.ts   |  16 +-
 .../features/settings/tabs/api-keys-tab.tsx   |   5 +-
 .../features/settings/tabs/general-tab.tsx    |  19 +-
 .../studio/historical-training-view.tsx       |   4 +-
 .../src/features/studio/history-card-grid.tsx |  14 +-
 .../dataset-preview-dialog-mapping.tsx        |   4 +-
 .../sections/dataset-preview-dialog.tsx       |  14 +-
 .../studio/sections/model-section.tsx         |   8 +-
 .../studio/sections/progress-section.tsx      |   2 +-
 .../studio/sections/training-section.tsx      |  11 +-
 .../src/features/studio/studio-page.tsx       |   6 +-
 .../studio/training-start-overlay.tsx         |  28 +-
 .../features/tour/lib/confetti-fireworks.ts   |   7 +-
 .../src/features/training/api/models-api.ts   |  10 +-
 .../training/hooks/use-training-actions.ts    |   4 +-
 .../hooks/use-training-history-sidebar.ts     |  12 +-
 .../hooks/use-training-unload-guard.ts        |   7 +-
 .../src/features/training/lib/yaml-config.ts  |   8 +-
 .../training/stores/training-config-store.ts  |  44 +--
 .../src/hooks/use-collapse-scroll-lock.ts     |  10 +-
 studio/frontend/src/hooks/use-gpu-info.ts     |   6 +-
 .../frontend/src/hooks/use-gpu-utilization.ts |   6 +-
 .../frontend/src/hooks/use-hardware-info.ts   |   8 +-
 .../src/hooks/use-hf-dataset-search.ts        |   4 +-
 .../src/hooks/use-hf-dataset-splits.ts        |   5 +-
 .../frontend/src/hooks/use-hf-model-search.ts |  51 ++-
 .../src/hooks/use-hf-token-validation.ts      |   5 +-
 .../src/hooks/use-recommended-model-vram.ts   |   4 +-
 .../frontend/src/hooks/use-tauri-backend.ts   |  29 +-
 studio/frontend/src/lib/copy-to-clipboard.ts  |   8 +-
 .../frontend/src/lib/format-fastapi-error.ts  |  15 +-
 studio/frontend/src/lib/hf-cache.ts           |  11 +-
 studio/frontend/src/lib/latex.ts              |  65 ++--
 studio/frontend/src/lib/open-link.ts          |  11 +-
 studio/frontend/src/lib/vram.ts               |  61 +---
 studio/frontend/src/main.tsx                  |   4 +-
 studio/frontend/src/utils/index.ts            |   1 -
 130 files changed, 1553 insertions(+), 2141 deletions(-)

diff --git a/studio/frontend/src/app/provider.tsx b/studio/frontend/src/app/provider.tsx
index 6f3c7618be..4bd348effc 100644
--- a/studio/frontend/src/app/provider.tsx
+++ b/studio/frontend/src/app/provider.tsx
@@ -48,11 +48,10 @@ async function applyAppWindowLayout(isCurrent: WindowLayoutGuard): Promise<void>
 
   const win = getCurrentWindow();
   // Decide first-launch vs restore from the on-disk state file BEFORE touching the
-  // window. Probing the window itself after restoreStateCurrent is unreliable:
-  // on GTK, set_size against a hidden window is deferred until show(), so
-  // innerSize() reads a stale value and any baseline fallback would overwrite the
-  // queued restore. On macOS the same probe works, hence the inconsistency
-  // between previous iterations of this code.
+  // window. Probing the window after restoreStateCurrent is unreliable: on GTK,
+  // set_size on a hidden window is deferred until show(), so innerSize() reads a
+  // stale value and a baseline fallback would overwrite the queued restore. On
+  // macOS the same probe works, hence the inconsistency between prior iterations.
   const hasSavedState = await invoke<boolean>("has_saved_window_state");
   if (!isCurrent()) return;
 
@@ -60,9 +59,8 @@ async function applyAppWindowLayout(isCurrent: WindowLayoutGuard): Promise<void>
   if (!isCurrent()) return;
 
   if (hasSavedState) {
-    // Subsequent launch: the plugin handles size, position, and maximized,
-    // with built-in off-screen protection (monitor-intersection check) for
-    // positions saved on a now-disconnected display.
+    // Subsequent launch: plugin restores size/position/maximized, with built-in
+    // off-screen protection for positions saved on a now-disconnected display.
     await restoreStateCurrent(
       StateFlags.SIZE | StateFlags.POSITION | StateFlags.MAXIMIZED,
     );
@@ -87,8 +85,8 @@ async function applyAppWindowLayout(isCurrent: WindowLayoutGuard): Promise<void>
   if (!isCurrent()) return;
   await win.show();
   if (!isCurrent()) return;
-  // Apply constraints after restore/show. Setting constraints before plugin restore
-  // can emit a Resized event and overwrite the plugin's cached saved size.
+  // Apply constraints after restore/show: doing so before plugin restore can emit
+  // a Resized event and overwrite the plugin's cached saved size.
   await win.setSizeConstraints({ minWidth: MIN_WINDOW_WIDTH, minHeight: MIN_WINDOW_HEIGHT });
 }
 
diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index da74a9e8a7..200200d190 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -55,8 +55,8 @@ function isChatOnlyAllowed(pathname: string): boolean {
 
 export const Route = createRootRoute({
   beforeLoad: async ({ location }) => {
-    // Ensure platform info is fetched before checking chat-only guard.
-    // fetchDeviceType caches after first call, so subsequent navigations are instant.
+    // Fetch platform info before the chat-only guard. fetchDeviceType caches,
+    // so later navigations are instant.
     await fetchDeviceType();
     const chatOnly = usePlatformStore.getState().isChatOnly();
     if (chatOnly && !isChatOnlyAllowed(location.pathname)) {
diff --git a/studio/frontend/src/app/routes/settings.tsx b/studio/frontend/src/app/routes/settings.tsx
index fa97a450f7..84650bdb8b 100644
--- a/studio/frontend/src/app/routes/settings.tsx
+++ b/studio/frontend/src/app/routes/settings.tsx
@@ -7,10 +7,10 @@ import { useSettingsDialogStore } from "@/features/settings";
 import { requireAuth } from "../auth-guards";
 import { Route as rootRoute } from "./__root";
 
-// /settings is a deep link to the modal. Open it, then redirect home.
-// Tab title is driven by useSettingsDialogStore in __root.tsx since the
-// redirect means /settings never stays matched; staticData is just a
-// safety net if beforeLoad ever stops throwing.
+// /settings deep-links the modal: open it, then redirect home. Tab title is
+// driven by useSettingsDialogStore in __root.tsx since the redirect means
+// /settings never stays matched; staticData is a safety net if beforeLoad
+// ever stops throwing.
 export const Route = createRoute({
   getParentRoute: () => rootRoute,
   path: "/settings",
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 941c2e8a74..8d56d90f98 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -138,11 +138,8 @@ function getTourId(pathname: string): string | null {
   return null;
 }
 
-// Hugeicons' TestTube01Icon ships with two interior bubbles (paths #4
-// and #5 of the 5-path definition). Slicing to the first three paths
-// keeps the test-tube outline + horizontal cap + liquid line, dropping
-// the bubbles. The original export stays untouched, and HugeiconsIcon
-// renders this trimmed array exactly the same way.
+// TestTube01Icon's last 2 paths are interior bubbles; slice to the first
+// 3 (outline + cap + liquid line) to drop them. Original export untouched.
 const TestTubeOutlineIcon = TestTube01Icon.slice(
   0,
   3,
@@ -261,11 +258,11 @@ export function AppSidebar() {
 
   const scrollRef = useRef<HTMLDivElement | null>(null);
   const [scrolled, setScrolled] = useState(false);
-  // Bottom fade hides at the very bottom (and for short, non-scrolling lists)
-  // so the last row isn't washed out - Gemini-style.
+  // Bottom fade hides at the very bottom / for short lists so the last row
+  // isn't washed out (Gemini-style).
   const [canScrollDown, setCanScrollDown] = useState(false);
-  // Driven only from onScroll + a content-change effect below. Deliberately NO
-  // ResizeObserver: its callback-driven setState created a render loop (React
+  // Driven only from onScroll + a content-change effect below. No
+  // ResizeObserver: its callback-driven setState caused a render loop (React
   // #185). Both setters bail out when unchanged, so neither path can loop.
   const syncScrollState = (el: HTMLDivElement) => {
     const nextScrolled = el.scrollTop > 0;
@@ -311,10 +308,9 @@ export function AppSidebar() {
   const selectedHistoryRunId = useTrainingRuntimeStore((s) => s.selectedHistoryRunId);
   const setSelectedHistoryRunId = useTrainingRuntimeStore((s) => s.setSelectedHistoryRunId);
 
-  // Recompute the bottom-fade state on mount and whenever the list height can
-  // change (items load, sections collapse/expand, route switches the visible
-  // list) - onScroll never fires for short, non-scrolling lists. Guarded
-  // setState below means this can't loop even if a dep is a fresh reference.
+  // Recompute bottom-fade on mount and whenever list height can change
+  // (items load, sections toggle, route switch) - onScroll never fires for
+  // short, non-scrolling lists. Guarded setState below can't loop.
   useEffect(() => {
     const el = scrollRef.current;
     if (!el) return;
@@ -761,9 +757,8 @@ export function AppSidebar() {
               label={t("shell.navigation.search")}
               active={false}
               onClick={() => {
-                // Search is read-only over chat history and never runs
-                // inference, so it stays available while training (unlike
-                // New chat, which is gated on `chatDisabled`).
+                // Search is read-only and never runs inference, so it stays
+                // available while training (unlike New chat, gated on chatDisabled).
                 useChatSearchStore.getState().open();
                 closeMobileIfOpen();
               }}
@@ -796,8 +791,7 @@ export function AppSidebar() {
                   closeMobileIfOpen();
                 }}
               />
-              {/* Train has its own labelled section when expanded; surface it as
-                  a plain icon here only while the sidebar is collapsed. */}
+              {/* Train has a labelled section when expanded; plain icon here only when collapsed. */}
               <NavItem
                 icon={TestTubeOutlineIcon}
                 label={t("shell.navigation.train")}
@@ -899,12 +893,10 @@ export function AppSidebar() {
               <SidebarGroupContent className="px-2">
                 <SidebarMenu>
                   {runItems.map((run) => {
-                    // An explicit sidebar selection wins. Otherwise highlight
-                    // the active job only while the "Current Run" tab is the
-                    // view - that covers a live run (it auto-switches there) and
-                    // a just-finished/errored run you're still viewing, while
-                    // keeping the Configure tab unhighlighted even though
-                    // `activeJobId` stays pinned to the last job.
+                    // Explicit selection wins. Otherwise highlight the active
+                    // job only while the "Current Run" tab is the view, keeping
+                    // the Configure tab unhighlighted even though activeJobId
+                    // stays pinned to the last job.
                     const isActiveRun =
                       selectedHistoryRunId != null
                         ? run.id === selectedHistoryRunId
@@ -988,10 +980,9 @@ export function AppSidebar() {
       </SidebarContent>
 
       <SidebarFooter className="relative group-data-[collapsible=icon]:px-0">
-        {/* Fade above the profile box, shown only while there's more list below
-            the fold; at the very bottom (or for short lists) it fades out so the
-            last row shows fully (Gemini-style). `right-2` keeps it clear of the
-            8px scrollbar gutter so the scrollbar isn't faded out. */}
+        {/* Fade above the profile box, shown only when there's more list below
+            the fold; at the bottom (or short lists) it fades so the last row
+            shows fully (Gemini-style). right-2 keeps it clear of the 8px scrollbar gutter. */}
         <div
           aria-hidden="true"
           className={cn(
@@ -1082,8 +1073,8 @@ export function AppSidebar() {
                 </DropdownMenuItem>
                 <DropdownMenuItem
                   onSelect={async () => {
-                    // Best-effort server-side revocation; ignore network errors
-                    // so the local clear path still runs and the user lands on /login.
+                    // Best-effort server revocation; ignore network errors so
+                    // the local clear still runs and the user lands on /login.
                     try {
                       await logout();
                     } catch {
diff --git a/studio/frontend/src/components/assistant-ui/attachment.tsx b/studio/frontend/src/components/assistant-ui/attachment.tsx
index a96dd7a4e1..0a59d75964 100644
--- a/studio/frontend/src/components/assistant-ui/attachment.tsx
+++ b/studio/frontend/src/components/assistant-ui/attachment.tsx
@@ -164,8 +164,8 @@ const AttachmentUI: FC = () => {
         throw new Error(`Unknown attachment type: ${type as string}`);
     }
   });
-  // Include filename in accessible name so screen readers distinguish
-  // same-typed attachments. Sighted users get it via the tooltip.
+  // Filename in accessible name lets screen readers distinguish same-typed
+  // attachments. Sighted users get it via the tooltip.
   const accessibleName = name
     ? `${typeLabel} attachment: ${name}`
     : `${typeLabel} attachment`;
diff --git a/studio/frontend/src/components/assistant-ui/code-plugin.ts b/studio/frontend/src/components/assistant-ui/code-plugin.ts
index 5df7ac4f95..1e70871c06 100644
--- a/studio/frontend/src/components/assistant-ui/code-plugin.ts
+++ b/studio/frontend/src/components/assistant-ui/code-plugin.ts
@@ -10,8 +10,8 @@ import {
 } from "@streamdown/code";
 import type { BundledLanguage } from "shiki";
 
-// Fence tags LLMs/users commonly write that shiki doesn't expose as aliases.
-// Keys are lower-cased input; values are canonical shiki language ids.
+// Common fence tags shiki doesn't expose as aliases.
+// Keys: lower-cased input; values: canonical shiki language ids.
 const LANGUAGE_ALIAS_OVERRIDES: Record<string, BundledLanguage> = {
   objectivec: "objective-c",
   "obj-c": "objective-c",
diff --git a/studio/frontend/src/components/assistant-ui/code-themes.ts b/studio/frontend/src/components/assistant-ui/code-themes.ts
index 2557b45ef0..67db02b9b4 100644
--- a/studio/frontend/src/components/assistant-ui/code-themes.ts
+++ b/studio/frontend/src/components/assistant-ui/code-themes.ts
@@ -5,11 +5,10 @@ import oneDarkPro from "@shikijs/themes/one-dark-pro";
 import oneLight from "@shikijs/themes/one-light";
 import type { ThemeRegistrationAny } from "shiki";
 
-// Canonical Atom One Dark / One Light themes, shipped by `@shikijs/themes`.
-// We only override the background so the code block blends into the app's
-// `--code-block` surface instead of painting its own. Every token color and
-// scope mapping is left intact — that's what gives consistent multi-language
-// highlighting (including Objective-C, Go, Rust, etc.) out of the box.
+// Canonical Atom One Dark / One Light themes from `@shikijs/themes`. Only the
+// background is overridden so the code block blends into the app's `--code-block`
+// surface; all token colors/scopes are kept intact for consistent multi-language
+// highlighting out of the box.
 const withTransparentBg = (theme: ThemeRegistrationAny): ThemeRegistrationAny => ({
   ...theme,
   bg: "transparent",
diff --git a/studio/frontend/src/components/assistant-ui/image.tsx b/studio/frontend/src/components/assistant-ui/image.tsx
index 3cd7ecaaf5..0850a8230a 100644
--- a/studio/frontend/src/components/assistant-ui/image.tsx
+++ b/studio/frontend/src/components/assistant-ui/image.tsx
@@ -378,10 +378,7 @@ function ImageContentFilterError({
 
 export type ImageActionsProps = {
   part: ImageMessagePart;
-  /**
-   * Wire to your own generation call to show a regenerate button. The button
-   * renders only when this is set and the part carries a `prompt`.
-   */
+  /** Shows a regenerate button (only when set and the part has a `prompt`). */
   onRegenerate?: () => void | Promise<void>;
   className?: string;
 };
diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index 107672d938..fc547da0b1 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -157,8 +157,7 @@ const UNSAFE_SVG_RE =
 
 function sanitizeSvg(source: string): string | null {
   if (UNSAFE_SVG_RE.test(source)) return null;
-  // Strip XML declaration (<?xml ...?>) -- not needed for data URI
-  // rendering and can cause issues with some renderers.
+  // Strip XML declaration: unneeded for data URIs and breaks some renderers.
   return source.replace(/^\s*<\?xml[^?]*\?>\s*/i, "");
 }
 
@@ -381,11 +380,10 @@ function StreamdownBlock(props: BlockProps) {
 }
 const AUDIO_PLAYER_RE = /<audio-player\s+src="([^"]+)"\s*\/>/;
 
-// Coalesce markdown re-parses to one per animation frame while streaming: the
-// runtime notifies on every token (hundreds/sec) and the monitor can't paint
-// that fast. When not streaming we return live text rather than the throttled
-// state, so the final text never lags and a reused instance (parts are keyed by
-// index) shows a completed message's text immediately instead of a stale frame.
+// Coalesce markdown re-parses to one per frame while streaming: tokens arrive
+// hundreds/sec, faster than the monitor can paint. When not streaming we return
+// live text (not the throttled state) so final text never lags and a reused
+// instance (parts keyed by index) shows completed text instead of a stale frame.
 function useRafCoalescedText(text: string, isStreaming: boolean): string {
   const [displayed, setDisplayed] = useState(text);
   const pendingRef = useRef(text);
@@ -408,9 +406,9 @@ function useRafCoalescedText(text: string, isStreaming: boolean): string {
     }
   }, [text, isStreaming]);
 
-  // Unmount cleanup. Cancel the in-flight rAF and null the handle so a
-  // StrictMode remount isn't gated out by a stale id. Kept separate from the
-  // scheduling effect so it doesn't cancel mid-stream and defeat the throttle.
+  // Unmount cleanup: cancel the in-flight rAF and null the handle so a
+  // StrictMode remount isn't gated by a stale id. Separate from the scheduling
+  // effect so it doesn't cancel mid-stream and defeat the throttle.
   useEffect(() => {
     return () => {
       if (rafRef.current !== null) {
diff --git a/studio/frontend/src/components/assistant-ui/message-timing.tsx b/studio/frontend/src/components/assistant-ui/message-timing.tsx
index 31f742bc5e..447fd763e3 100644
--- a/studio/frontend/src/components/assistant-ui/message-timing.tsx
+++ b/studio/frontend/src/components/assistant-ui/message-timing.tsx
@@ -52,10 +52,9 @@ export const MessageTiming: FC<{
   // Anthropic-only cache-write count.
   const cacheWrites = custom?.contextUsage?.cacheWriteTokens ?? 0;
 
-  // Guard unphysical tok/s: llama.cpp emits predicted_ms=0 on no-op
-  // turns, blowing the rate up to Infinity. Require >=1 token AND a
-  // non-zero decode window AND a finite rate. Fast cached single-token
-  // responses (sub-10ms) are legitimate and must stay visible.
+  // Guard unphysical tok/s: llama.cpp emits predicted_ms=0 on no-op turns,
+  // blowing the rate up to Infinity. Require >=1 token, a non-zero decode
+  // window, and a finite rate. Fast cached sub-10ms responses are legit.
   const hasPredicted =
     (st?.predicted_n ?? 0) >= 1 && (st?.predicted_ms ?? 0) > 0;
   const predictedRate =
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/folder-browser.tsx b/studio/frontend/src/components/assistant-ui/model-selector/folder-browser.tsx
index 42bd1716a1..3cb80ca2e1 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/folder-browser.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/folder-browser.tsx
@@ -32,12 +32,9 @@ export interface FolderBrowserProps {
 
 function splitBreadcrumb(path: string): { label: string; value: string }[] {
   if (!path) return [];
-  // Distinguish path styles BEFORE normalizing separators. On POSIX
-  // backslashes are valid filename characters, so we cannot blindly
-  // rewrite ``\`` -> ``/`` -- doing so would mangle directory names
-  // like ``my\backup`` into ``my/backup`` and produce breadcrumb
-  // values that 404 on the server. Only Windows-style absolute paths
-  // (drive letter, or UNC ``\\server\share``) get the conversion.
+  // Detect path style BEFORE normalizing: on POSIX, `\` is a valid filename
+  // char, so blindly rewriting `\` -> `/` mangles names like `my\backup` into
+  // 404ing breadcrumbs. Only Windows-style paths (drive letter, or UNC) convert.
   const isWindowsDrive = /^[A-Za-z]:[\\/]/.test(path) || /^[A-Za-z]:$/.test(path);
   const isUnc = /^\\\\/.test(path);
   const isWindows = isWindowsDrive || isUnc;
@@ -57,11 +54,9 @@ function splitBreadcrumb(path: string): { label: string; value: string }[] {
     return parts;
   }
 
-  // Windows-ish drive path (C:, D:): first segment is the drive. Use
-  // ``C:/`` (drive-absolute) as the crumb value so clicking the drive
-  // root navigates to the root of the drive rather than the
-  // drive-relative current working directory on that drive (``C:``
-  // alone resolves to ``CWD-on-C``, not ``C:\``).
+  // Windows drive path (C:, D:): first segment is the drive. Use `C:/` as the
+  // crumb value so clicking the drive root navigates to the drive root, not the
+  // drive-relative CWD (`C:` alone resolves to CWD-on-C, not `C:\`).
   if (/^[A-Za-z]:$/.test(segments[0])) {
     const driveRoot = `${segments[0]}/`;
     let cur = driveRoot;
@@ -102,8 +97,8 @@ export function FolderBrowser({
       abortRef.current = ctrl;
       setLoading(true);
       setError(null);
-      // Forward the signal so cancelled navigation actually cancels the
-      // backend enumeration instead of just discarding the response.
+      // Forward the signal so cancelled navigation aborts the backend
+      // enumeration, not just the response.
       browseFolders(target, hidden, ctrl.signal)
         .then((res) => {
           if (ctrl.signal.aborted) return;
@@ -112,17 +107,13 @@ export function FolderBrowser({
         })
         .catch((err) => {
           if (ctrl.signal.aborted) return;
-          // Surface the error, but if the very first request (typically
-          // a typo'd or denylisted ``initialPath``) fails AND the
-          // browser is empty (no ``data`` to render against), fall
-          // back to the user's HOME so the modal is navigable instead
-          // of an irrecoverable dead end.
+          // Surface the error; if the first request (e.g. a bad initialPath)
+          // fails, fall back to HOME so the modal stays navigable.
           const message = err instanceof Error ? err.message : String(err);
           setError(message);
           if (opts?.fallbackOnError && target !== undefined) {
             // Re-issue without a target -> backend defaults to HOME.
-            // Don't recurse if HOME itself fails (paranoia: shouldn't
-            // happen since the sandbox allowlist always includes HOME).
+            // Don't recurse if HOME itself fails (allowlist always has HOME).
             queueMicrotask(() => navigate(undefined, hidden));
           }
         })
@@ -133,15 +124,13 @@ export function FolderBrowser({
     [],
   );
 
-  // Fetch when the dialog opens.  Only re-run when the dialog transitions
-  // closed -> open; subsequent navigation is driven by `navigate()` so we
-  // don't want `path` in the dependency list here.
+  // Fetch only on closed -> open; later navigation is driven by `navigate()`,
+  // so `path` is deliberately kept out of the dependency list.
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => {
     if (!open) return;
-    // ``fallbackOnError``: if the user-supplied ``initialPath`` is bad
-    // (typo, denylisted, deleted) we recover into HOME instead of
-    // showing an empty modal with no breadcrumbs/entries.
+    // fallbackOnError: recover into HOME if initialPath is bad, rather than
+    // showing an empty modal.
     navigate(initialPath, showHidden, { fallbackOnError: true });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open]);
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
index 2d715bf8de..516aa409fc 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
@@ -62,7 +62,7 @@ function dedupe(values: string[]): string[] {
   return [...new Set(values.filter(Boolean))];
 }
 
-/** Normalize a string for fuzzy search: lowercase, strip separators. */
+/** Lowercase and strip separators for fuzzy search. */
 function normalizeForSearch(s: string): string {
   return s.toLowerCase().replace(/[\s\-_\.]/g, "");
 }
@@ -296,14 +296,14 @@ function GgufVariantExpander({
     [gpuGb, gpuBudgetGb, totalBudgetGb],
   );
 
-  // If the backend-recommended variant is OOM, pick the largest fitting
-  // variant instead; if all are OOM, recommend the smallest one.
+  // If the recommended variant is OOM, pick the largest fitting one;
+  // if all are OOM, recommend the smallest.
   const effectiveRecommended = useMemo(() => {
     if (!variants || !gpuGb || gpuGb <= 0) return defaultVariant;
     const defaultV = variants.find((v) => v.quant === defaultVariant);
     if (defaultV && getGgufFit(defaultV.size_bytes) !== "oom")
       return defaultVariant;
-    // Default is OOM -- pick largest non-OOM variant (best quality that fits)
+    // Largest non-OOM variant (best quality that fits)
     const fitting = variants.filter((v) => getGgufFit(v.size_bytes) !== "oom");
     if (fitting.length > 0) {
       fitting.sort((a, b) => b.size_bytes - a.size_bytes);
@@ -460,8 +460,8 @@ function isGgufRepo(id: string, hintedIsGguf?: boolean): boolean {
 
 /** Extract param count label from model name (e.g. "Qwen3-0.6B" -> "0.6B"). */
 function extractParamLabel(id: string): string | undefined {
-  // Match patterns like "0.6B", "1B", "4B", "3.5B", "70B", "1.5B" etc.
   const name = id.split("/").pop() ?? id;
+  // Match patterns like "0.6B", "1B", "4B", "3.5B", "70B", "1.5B" etc.
   const match = name.match(/(?:^|[-_])(\d+(?:\.\d+)?)[Bb](?:[-_]|$)/);
   return match ? `${match[1]}B` : undefined;
 }
@@ -504,11 +504,10 @@ export function HubModelPicker({
   const { results, isLoading, isLoadingMore, fetchMore } =
     useHfModelSearch(debouncedQuery);
 
-  // Sets of lowercased repo ids that the store or HF search have
-  // confirmed are GGUF. Absence means "no hint" and lets hasGgufSuffix
-  // take over as fallback, rather than conflating unknown with known-
-  // not-GGUF. Keys are lowercased so that store IDs and HF search IDs
-  // that differ only by casing still match the same hint.
+  // Lowercased repo ids confirmed GGUF by the store or HF search.
+  // Absence means "no hint" -> hasGgufSuffix is the fallback (don't
+  // conflate unknown with known-not-GGUF). Lowercased so store and HF
+  // IDs differing only by casing match the same hint.
   const modelGgufIds = useMemo(() => {
     const ids = new Set<string>();
     for (const model of models) {
@@ -538,8 +537,8 @@ export function HubModelPicker({
   const [customFoldersCollapsed, setCustomFoldersCollapsed] = useState(false);
   const [recommendedCollapsed, setRecommendedCollapsed] = useState(false);
 
-  // Cached (already downloaded) repos -- use module-level cache so
-  // re-mounting the popover does not flash an empty "Downloaded" section.
+  // Cached (downloaded) repos -- module-level cache avoids flashing an
+  // empty "Downloaded" section when the popover re-mounts.
   const [cachedGguf, setCachedGguf] =
     useState<CachedGgufRepo[]>(_cachedGgufCache);
   const [cachedModels, setCachedModels] =
@@ -548,8 +547,7 @@ export function HubModelPicker({
     _cachedGgufCache.length > 0 || _cachedModelsCache.length > 0;
   const [cachedReady, setCachedReady] = useState(alreadyCached);
 
-  // LM Studio local models -- module-level cache so re-mounting the
-  // popover does not flash an empty section (same pattern as GGUF/models).
+  // LM Studio local models -- module-level cache, same pattern as above.
   const [lmStudioModels, setLmStudioModels] =
     useState<LocalModelInfo[]>(_lmStudioCache);
   const [customFolderModels, setCustomFolderModels] =
@@ -589,24 +587,20 @@ export function HubModelPicker({
   }, []);
 
   const handleAddFolder = useCallback(async (overridePath?: string) => {
-    // Accept an explicit path so the folder browser can submit the
-    // chosen path in the same tick it calls `setFolderInput`; reading
-    // `folderInput` alone would race the state update.
+    // Explicit path lets the folder browser submit in the same tick it
+    // calls `setFolderInput`; reading `folderInput` would race the update.
     const raw = overridePath !== undefined ? overridePath : folderInput;
     const trimmed = raw.trim();
     if (!trimmed || folderLoading) return;
     setFolderError(null);
     setFolderLoading(true);
-    // True when the request originated from the folder browser's
-    // ``onSelect`` (one-click "Use this folder"). In that flow the
-    // typed-input panel is closed, so the inline ``folderError``
-    // paragraph is invisible. Surface failures via toast instead so
-    // the action doesn't appear to silently no-op when the backend
-    // rejects (denylisted path, sandbox 403, etc.).
+    // From the folder browser's one-click "Use this folder": the typed-
+    // input panel is closed, so the inline folderError is invisible.
+    // Surface failures (denylisted path, sandbox 403, etc.) via toast.
     const fromBrowser = overridePath !== undefined;
     try {
       const created = await addScanFolder(trimmed);
-      // Backend returns existing row for duplicates, so deduplicate
+      // Backend returns the existing row for duplicates, so dedupe.
       const next = _scanFoldersCache.some((f) => f.id === created.id || f.path === created.path)
         ? _scanFoldersCache
         : [..._scanFoldersCache, created];
@@ -632,7 +626,7 @@ export function HubModelPicker({
   const handleRemoveFolder = useCallback(async (id: number) => {
     try {
       await removeScanFolder(id);
-      // Optimistic update so the folder disappears immediately
+      // Optimistic: drop it immediately.
       const next = _scanFoldersCache.filter((f) => f.id !== id);
       _scanFoldersCache = next;
       setScanFolders(next);
@@ -662,18 +656,17 @@ export function HubModelPicker({
   }, [refreshLocalModelsList]);
 
   useEffect(() => {
-    // Always refresh LM Studio + custom folder models (not gated by alreadyCached)
+    // Always refresh LM Studio + custom folder models (not gated by alreadyCached).
     refreshLocalModelsList();
     refreshScanFolders();
     listRecommendedFolders()
       .then(setRecommendedFolders)
       .catch(() => {});
 
-    // Always refetch cached GGUF/model lists. The module-level caches give
-    // an instant render with stale data (no spinner flash), but newly
-    // downloaded repos won't appear unless we re-hit the backend on every
-    // mount.  Initial state already has cachedReady=alreadyCached, so the
-    // background refresh is invisible when we already had data.
+    // Always refetch cached GGUF/model lists. The module-level caches render
+    // instantly with stale data (no spinner flash), but newly downloaded
+    // repos need a fresh backend hit. cachedReady=alreadyCached initially,
+    // so the background refresh is invisible when we already had data.
     let done = 0;
     const check = () => {
       if (++done >= 2) setCachedReady(true);
@@ -694,8 +687,8 @@ export function HubModelPicker({
       .finally(check);
   }, [refreshLocalModelsList, refreshScanFolders]);
 
-  // Deduplicate: don't show downloaded models in the recommended list.
-  // Compare case-insensitively since HF cache lowercases repo IDs.
+  // Hide downloaded models from the recommended list. Case-insensitive
+  // since the HF cache lowercases repo IDs.
   const downloadedSet = useMemo(() => {
     const s = new Set<string>();
     for (const c of cachedGguf) s.add(c.repo_id.toLowerCase());
@@ -756,10 +749,9 @@ export function HubModelPicker({
     return recommendedIds.filter((id) => normalizeForSearch(id).includes(q));
   }, [showHfSection, debouncedQuery, recommendedIds]);
 
-  // Fetch VRAM info for visible models, plus any models surfaced by a search
-  // query so that filtered recommended models also show VRAM badges.
-  // Skip GGUF repos: they have no safetensors metadata and the render layer
-  // already shows a static "GGUF" badge instead of VRAM data.
+  // VRAM info for visible models plus any surfaced by a search query, so
+  // filtered recommended models also show VRAM badges. Skip GGUF repos:
+  // no safetensors metadata, and the render layer shows a "GGUF" badge.
   const idsForVram = useMemo(() => {
     const ids = showHfSection
       ? [...new Set([...visibleRecommendedIds, ...filteredRecommendedIds])]
@@ -851,9 +843,8 @@ export function HubModelPicker({
   );
 
   // Sentinel + IntersectionObserver for recommended infinite scroll.
-  // We disconnect after each fire so the observer doesn't loop while
-  // React re-renders; the effect re-creates it on the next page.
-  // Uses a callback ref for the sentinel so we detect mount/unmount reliably.
+  // Disconnect after each fire so it doesn't loop during re-render; the
+  // effect re-creates it next page. Callback ref detects mount/unmount.
   const [recommendedSentinel, setRecommendedSentinel] =
     useState<HTMLDivElement | null>(null);
   const recommendedSentinelRef = useCallback((node: HTMLDivElement | null) => {
@@ -872,7 +863,7 @@ export function HubModelPicker({
       },
       { threshold: 0, root },
     );
-    // Small delay so the browser finishes layout after the previous page render
+    // Small delay so layout settles after the previous page render.
     const timer = setTimeout(() => obs.observe(recommendedSentinel), 100);
     return () => {
       clearTimeout(timer);
@@ -1184,9 +1175,8 @@ export function HubModelPicker({
                 onSelect={(picked) => {
                   setFolderInput(picked);
                   setFolderError(null);
-                  // One-click UX: the "Use this folder" button submits
-                  // the scan folder directly. Pass the path explicitly
-                  // because `folderInput` state hasn't flushed yet.
+                  // Pass the path explicitly: `folderInput` state hasn't
+                  // flushed yet when "Use this folder" submits.
                   void handleAddFolder(picked);
                 }}
               />
diff --git a/studio/frontend/src/components/assistant-ui/reasoning.tsx b/studio/frontend/src/components/assistant-ui/reasoning.tsx
index 633c3bc3e9..3eaa21a19e 100644
--- a/studio/frontend/src/components/assistant-ui/reasoning.tsx
+++ b/studio/frontend/src/components/assistant-ui/reasoning.tsx
@@ -358,18 +358,18 @@ const ReasoningGroupImpl: ReasoningGroupComponent = ({
     }
   }, [isReasoningStreaming]);
 
-  // Reset dismissed flag when a new stream starts
+  // Reset dismissed flag on new stream.
   useEffect(() => {
     if (isReasoningStreaming) {
       setDismissedWhileStreaming(false);
     }
   }, [isReasoningStreaming]);
 
-  // Derived: open during streaming (unless dismissed), or if user manually opened after
+  // Open while streaming (unless dismissed), or once manually opened.
   const isOpen = (isReasoningStreaming && !dismissedWhileStreaming) || manualOpen;
   const variant = isOpen ? "outline" : "ghost";
 
-  // Allow closing during streaming (matches ChatGPT)
+  // Allow closing during streaming (matches ChatGPT).
   const handleOpenChange = useCallback(
     (open: boolean) => {
       if (isReasoningStreaming) {
diff --git a/studio/frontend/src/components/assistant-ui/sources.tsx b/studio/frontend/src/components/assistant-ui/sources.tsx
index 5593369bf9..7e5b52f7d0 100644
--- a/studio/frontend/src/components/assistant-ui/sources.tsx
+++ b/studio/frontend/src/components/assistant-ui/sources.tsx
@@ -128,9 +128,8 @@ function Source({
 
 interface SourceData {
   /**
-   * Stable per-citation key. Two Anthropic document citations into
-   * different spans of the same source share a ``url``, so React keys
-   * on ``id`` to keep each footnote distinct.
+   * Stable per-citation key. Two Anthropic citations into different spans of
+   * the same source share a `url`, so React keys on `id` to keep them distinct.
    */
   id: string;
   url: string;
@@ -185,7 +184,6 @@ const SourcesGroup: FC = () => {
   const [visibleCount, setVisibleCount] = useState<number | null>(null);
   const [expanded, setExpanded] = useState(false);
 
-  // Extract source parts from the message
   const sources: SourceData[] = [];
   if (message.content) {
     for (const part of message.content) {
@@ -220,7 +218,6 @@ const SourcesGroup: FC = () => {
     const children = Array.from(container.children) as HTMLElement[];
     if (children.length === 0) return;
 
-    // Find the top of the first child as baseline
     const firstTop = children[0].offsetTop;
     let rowCount = 1;
     let prevTop = firstTop;
@@ -263,17 +260,12 @@ const SourcesGroup: FC = () => {
 
   return (
     <div className="relative mt-2 mb-3">
-      {/* Hidden measurement container. Renders all badges off-screen so we
-          can read each child's offsetTop and decide how many fit in two
-          rows. Wrapped in an absolute, h-0, overflow-hidden box so the
-          measurement pills do NOT contribute to the viewport's scrollable
-          overflow region. Without this clip, every hidden source row
-          adds ~30px to scrollHeight, producing a phantom empty scroll
-          area below the message: visible to users as unbounded blank
-          space below the assistant action bar. The inner div still
-          flex-wraps its children for measurement; offsetTop reads
-          correctly because the wrapper is positioned (absolute) and the
-          children's offsetTop is measured relative to it. */}
+      {/* Hidden measurement container: renders all badges off-screen to read
+          each child's offsetTop and decide how many fit in two rows. The
+          absolute/h-0/overflow-hidden wrapper clips the pills so they don't add
+          to scrollHeight (~30px per row) and create a phantom empty scroll area
+          below the message. offsetTop reads correctly because the wrapper is
+          positioned (absolute) and the flex-wrapped children measure against it. */}
       <div
         aria-hidden
         className="absolute pointer-events-none overflow-hidden h-0 w-full left-0 top-0"
diff --git a/studio/frontend/src/components/assistant-ui/think-aria-label.ts b/studio/frontend/src/components/assistant-ui/think-aria-label.ts
index 9a7eb31a86..193a5a5ad1 100644
--- a/studio/frontend/src/components/assistant-ui/think-aria-label.ts
+++ b/studio/frontend/src/components/assistant-ui/think-aria-label.ts
@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-// Shared aria-labels for the Think pill (toggle + effort dropdown) so both
-// controls use the same pre-load / unsupported-model wording.
+// Shared aria-labels for the Think pill toggle + effort dropdown, so both
+// use the same pre-load / unsupported-model wording.
 
 export interface ThinkToggleState {
   reasoningLockedOn: boolean;
@@ -27,8 +27,7 @@ export interface ThinkEffortState {
   reasoningEffort: string;
 }
 
-// Locked-on isn't special-cased: the effort dropdown stays interactive
-// (users can still pick an effort level).
+// Locked-on isn't special-cased: the effort dropdown stays interactive.
 export function thinkEffortAriaLabel(state: ThinkEffortState): string {
   if (!state.modelLoaded) return "Thinking (model not loaded)";
   if (state.reasoningDisabled)
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 6b94bfff6c..302c107e26 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -124,20 +124,18 @@ import {
   useState,
 } from "react";
 
-// True while a file is dragged anywhere over the chat page (not just the
-// composer), so the composer can show its "Drop files here" affordance.
+// True while a file is dragged anywhere over the chat page, so the composer
+// can show its "Drop files here" affordance.
 const PageDragContext = createContext(false);
 
-// Gap (px) between the last message and the floating composer. The bottom
-// spacer tracks composer height plus this gap so the chat can always be
-// scrolled fully above the composer.
+// Gap (px) between last message and floating composer; bottom spacer tracks
+// composer height plus this gap so chat can scroll fully above the composer.
 const COMPOSER_SCROLL_GAP_PX = 24;
 // The scroll-to-bottom footer sits 10px below the spacer top.
 const FOOTER_GAP_BELOW_SPACER_PX = 10;
-// Composer shrinks this soon after a run start (send clears the chips)
-// apply immediately: the run-start pin owns the bottom, so the clamp is
-// the intended glide. Covers instant responses where isRunning is
-// already false by the time the dock resize is observed.
+// Window after a run start during which composer shrinks apply immediately:
+// the run-start pin owns the bottom, so the clamp is the intended glide.
+// Covers instant responses where isRunning is already false by resize time.
 const RUN_SHRINK_WINDOW_MS = 1000;
 
 export const Thread: FC<{
@@ -145,10 +143,9 @@ export const Thread: FC<{
   hideWelcome?: boolean;
   targetThreadId?: string;
 }> = ({ hideComposer, hideWelcome, targetThreadId }) => {
-  // Intent-aware autoscroll: replaces assistant-ui's built-in autoscroll
-  // to prevent the streaming-mutation race that makes the viewport snap
-  // back to the bottom while the user is scrolling up (see the hook for
-  // the full explanation).
+  // Intent-aware autoscroll replaces assistant-ui's built-in autoscroll to
+  // prevent the streaming-mutation race that snaps the viewport back to the
+  // bottom while the user scrolls up (see the hook for the full explanation).
   const { ref: viewportRef, context: autoScrollContext } =
     useIntentAwareAutoScroll();
 
@@ -167,10 +164,9 @@ export const Thread: FC<{
       ? null
       : composerHeight + COMPOSER_SCROLL_GAP_PX - FOOTER_GAP_BELOW_SPACER_PX;
 
-  // The viewport element is owned by the autoscroll hook; mirror it
-  // locally for the spacer clamp math below. State, not a ref: the keyed
-  // provider below remounts the viewport on thread switches, and the
-  // scroll listener effect must re-attach to the new element.
+  // Viewport element is owned by the autoscroll hook; mirror it locally for
+  // the spacer clamp math. State, not a ref: the keyed provider remounts the
+  // viewport on thread switches and the scroll listener must re-attach.
   const [viewportEl, setViewportEl] = useState<HTMLElement | null>(null);
   const composedViewportRef = useCallback(
     (node: HTMLElement | null) => {
@@ -180,13 +176,13 @@ export const Thread: FC<{
     [viewportRef],
   );
 
-  // Bottom spacer sizing. Invariant: the chat never moves on its own when
-  // the composer resizes.
-  // - Grow (attachment added, multiline input): grow the spacer at once.
-  //   Growth below the scroll position is invisible and only adds room.
+  // Bottom spacer sizing. Invariant: chat never moves on its own on composer
+  // resize.
+  // - Grow (attachment added, multiline): grow at once; growth below the
+  //   scroll position is invisible and only adds room.
   // - Shrink (attachment removed): shrinking scrollHeight near the bottom
-  //   would clamp scrollTop and yank the chat down. Defer the shrink until
-  //   it is invisible (user scrolled up) or a bottom-pinning moment.
+  //   clamps scrollTop and yanks the chat down. Defer until invisible (user
+  //   scrolled up) or a bottom-pinning moment.
   // Applied imperatively so a remounted spacer can be sized from refs even
   // when composerHeight did not change (e.g. thread switch).
   const spacerElRef = useRef<HTMLDivElement | null>(null);
@@ -214,8 +210,8 @@ export const Thread: FC<{
   const spacerRef = useCallback(
     (node: HTMLDivElement | null) => {
       spacerElRef.current = node;
-      // Fresh mounts (thread switch, first message) start at the desired
-      // size; deferral state from a previous mount is moot.
+      // Fresh mounts (thread switch, first message) start at desired size;
+      // deferral state from a previous mount is moot.
       const desired = desiredSpacerPxRef.current;
       if (node && desired != null) {
         applySpacerPx(desired);
@@ -249,7 +245,7 @@ export const Thread: FC<{
         aui.thread().getState().isRunning ||
         performance.now() - runStartAtRef.current < RUN_SHRINK_WINDOW_MS;
       // At the bottom the shrink only drops blank spacer, so apply it now
-      // instead of stranding dead space until the next pin.
+      // rather than strand dead space until the next pin.
       if (
         runOwnsBottom ||
         distance >= applied - desired ||
@@ -260,20 +256,20 @@ export const Thread: FC<{
       // else: deferred; released on scroll or a bottom-pinning event.
     }
     if (prev != null && composerHeight > prev) {
-      // The chat is now above the new bottom. Detach as if the user had
-      // scrolled up so no later signal re-pins and shoves the chat up.
-      // Scrolling back down re-attaches; explicit pins still work.
-      // Mid-run growth comes from tool-status rows, not the user, and
-      // detaching then would break streaming autoscroll, so skip it.
+      // Chat is now above the new bottom. Detach as if the user scrolled up
+      // so no later signal re-pins and shoves the chat up (scrolling back
+      // down re-attaches; explicit pins still work). Skip mid-run: that
+      // growth is tool-status rows, not the user, and detaching would break
+      // streaming autoscroll.
       if (!aui.thread().getState().isRunning) {
         autoScrollContext.detachFromBottom();
       }
     }
   }, [composerHeight, hideComposer, autoScrollContext, aui, applySpacerPx, viewportEl]);
 
-  // Drop deferred spacer excess as soon as the user has scrolled far
-  // enough above the bottom that the shrink cannot clamp scrollTop.
-  // Keyed on viewportEl so the listener follows viewport remounts.
+  // Drop deferred spacer excess once the user has scrolled far enough above
+  // the bottom that the shrink cannot clamp scrollTop. Keyed on viewportEl
+  // so the listener follows viewport remounts.
   useEffect(() => {
     const el = viewportEl;
     if (!el) {
@@ -303,10 +299,10 @@ export const Thread: FC<{
   useAuiEvent("thread.initialize", releaseSpacerExcess);
   useAuiEvent("threadListItem.switchedTo", releaseSpacerExcess);
 
-  // Page-wide drag-and-drop: dropping a file anywhere on the chat page (not
-  // just on the composer) attaches it and shows the composer drop affordance.
-  // The composer's own dropzone still handles drops on the box itself; its
-  // handler calls preventDefault, so the page handler skips them (no double-add).
+  // Page-wide drag-and-drop: dropping a file anywhere on the chat page
+  // attaches it and shows the composer drop affordance. The composer's own
+  // dropzone handles drops on the box and calls preventDefault, so the page
+  // handler skips them (no double-add).
   const [pageDragging, setPageDragging] = useState(false);
   const dragDepth = useRef(0);
   const hasFiles = (e: ReactDragEvent) =>
@@ -332,8 +328,8 @@ export const Thread: FC<{
     // Compare panes hide this composer and use the shared composer's own
     // dropzone, so don't capture drops into a hidden composer here.
     if (hideComposer) return;
-    // Drops on the composer box are handled by its own dropzone, which calls
-    // preventDefault; skip those here so the file isn't added twice.
+    // Drops on the composer box are handled by its dropzone (preventDefault);
+    // skip those here so the file isn't added twice.
     if (e.defaultPrevented) return;
     const files = Array.from(e.dataTransfer.files);
     if (files.length === 0) return;
@@ -391,10 +387,9 @@ export const Thread: FC<{
               }}
             />
 
-            {/* Bottom slack so the last message has breathing room above the
-            sticky scroll-to-bottom button (and the floating composer in
-            single mode). Without this, content would butt against the
-            sticky footer and feel cramped. */}
+            {/* Bottom slack so the last message has room above the sticky
+            scroll-to-bottom button (and floating composer in single mode),
+            instead of butting against the footer. */}
             <AuiIf condition={({ thread }) => hideWelcome || !thread.isEmpty}>
               <div
                 ref={spacerRef}
@@ -562,8 +557,8 @@ const ThreadComposerDock: FC<{
 }> = ({ disabled, threadId, onHeightChange }) => {
   const { overlay } = useGeneratedImageOverlay();
 
-  // Report the dock's rendered height so the viewport can reserve matching
-  // scroll space when attachments or multiline input grow the composer.
+  // Report dock height so the viewport reserves matching scroll space when
+  // attachments or multiline input grow the composer.
   const dockRef = useRef<HTMLDivElement | null>(null);
   useEffect(() => {
     const el = dockRef.current;
@@ -608,12 +603,12 @@ const ThreadComposerDock: FC<{
 };
 
 const ThreadScrollToBottom: FC = () => {
-  // State and action both come from our IntentAwareScrollProvider (scoped
-  // per Thread, so compare panes are independent). We deliberately
-  // avoid `ThreadPrimitive.ScrollToBottom` + `useThreadViewport` to
-  // stay off assistant-ui's internal autoscroll path — see the hook
-  // for why. The button stays mounted and toggles via CSS; unmounting
-  // would trip the hook's MutationObserver as a content change.
+  // State and action both come from our IntentAwareScrollProvider (per-Thread
+  // scope, so compare panes are independent). We avoid
+  // `ThreadPrimitive.ScrollToBottom` + `useThreadViewport` to stay off
+  // assistant-ui's internal autoscroll path (see the hook). The button stays
+  // mounted and toggles via CSS; unmounting would trip the hook's
+  // MutationObserver as a content change.
   const isAtBottom = useIsThreadAtBottom();
   const scrollToBottom = useScrollThreadToBottom();
   return (
@@ -634,9 +629,9 @@ const ThreadScrollToBottom: FC = () => {
 const pickRandom = <T,>(arr: T[]): T =>
   arr[Math.floor(Math.random() * arr.length)];
 
-// Each greeting carries the sloth picture that best fits it, so a given line
-// always shows the same mascot. Greeting varies by local time; name-bearing
-// lines drop the name when none is set.
+// Each greeting carries its matching sloth picture so a line always shows the
+// same mascot. Greeting varies by local time; name-bearing lines drop the
+// name when none is set.
 type Welcome = { text: string; sloth: string };
 const DEFAULT_WELCOME: Welcome = {
   text: "What’s on your mind today?",
@@ -645,9 +640,8 @@ const DEFAULT_WELCOME: Welcome = {
 
 function buildWelcome(hour: number, name: string): Welcome {
   const g = (text: string, sloth: string): Welcome => ({ text, sloth });
-  // Use the name on roughly a third of the lines per time of day: only the
-  // direct salutations where it reads most naturally. Everything else stays
-  // name-free so the greeting doesn't feel repetitive.
+  // Use the name on ~a third of lines (only direct salutations where it reads
+  // naturally); the rest stay name-free so greetings don't feel repetitive.
   const base: Welcome[] = [
     g(name ? `Good to see you, ${name}.` : "Good to see you.", "large sloth wave.png"),
     g("Ready when you are.", "large sloth thumbs.png"),
@@ -696,7 +690,7 @@ const ThreadWelcome: FC<{
     <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col">
       <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[28vh]">
         <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-9 px-4">
-          {/* Center the whole greeting (sloth + title) over the composer. */}
+          {/* Center the greeting (sloth + title) over the composer. */}
           <div className="flex flex-row items-center justify-center gap-[15px]">
             <img
               src={currentEmojiSrc}
@@ -784,8 +778,8 @@ const Composer: FC<{
   );
   const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
   const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
-  // With more than 4 pills showing, collapse them to icons only to cut clutter.
-  // Search and Code always show; Images, Canvas and MCP are conditional.
+  // More than 4 pills: collapse to icons only. Search and Code always show;
+  // Images, Canvas and MCP are conditional.
   const pillsCompact =
     2 +
       (supportsBuiltinImageGeneration ? 1 : 0) +
@@ -802,7 +796,7 @@ const Composer: FC<{
   // Expand only once the input wraps to a second line, not on first keystroke.
   // Latch until cleared so it can't flip-flop at the wrap boundary.
   const inputRef = useRef<HTMLTextAreaElement>(null);
-  // Cache line metrics so getComputedStyle runs once, not on every keystroke.
+  // Cache line metrics so getComputedStyle runs once, not per keystroke.
   const lineMetricsRef = useRef<{ lineHeight: number; padding: number } | null>(
     null,
   );
@@ -844,8 +838,8 @@ const Composer: FC<{
   const referenceThreadId = threadId ?? activeThreadId ?? null;
   const hasSendableContent =
     composerText.trim().length > 0 || hasAttachments || hasPendingAudio;
-  // Two-row layout shows once the input wraps or a tool is on. Tools pre-select
-  // before a model loads, so an active toggle expands the composer either way.
+  // Two-row layout shows once the input wraps or a tool is on. Tools can
+  // pre-select before a model loads, so an active toggle expands it either way.
   const composerExpanded =
     isMultiline ||
     hasAttachments ||
@@ -857,7 +851,7 @@ const Composer: FC<{
     mcpEnabledForChat;
   // react-textarea-autosize re-measures only on value change or window resize,
   // not on the width swap from expanding, so it keeps the taller height and
-  // leaves a stray blank row. Nudge a resize whenever the input width changes.
+  // leaves a stray blank row. Nudge a resize whenever input width changes.
   useEffect(() => {
     const el = inputRef.current;
     if (!el || typeof ResizeObserver === "undefined") {
@@ -872,8 +866,8 @@ const Composer: FC<{
         return;
       }
       lastWidth = width;
-      // Re-measure after layout settles. An immediate dispatch races autosize's
-      // own measurement (stale pre-expand width); 0ms + 64ms wins it, no flash.
+      // Re-measure after layout settles. An immediate dispatch races
+      // autosize's own measurement (stale pre-expand width); 0ms + 64ms wins.
       while (pending.length) {
         clearTimeout(pending.pop());
       }
@@ -893,8 +887,8 @@ const Composer: FC<{
       observer.disconnect();
     };
   }, []);
-  // Docked composer opens upward; the centered welcome composer opens downward
-  // by default and only flips up via collision detection when it would not fit.
+  // Docked composer opens upward; the welcome composer opens downward by
+  // default and only flips up via collision detection when it won't fit.
   const effectiveMenuSide = menuSide ?? "bottom";
   const shouldBlockSend = useCallback(
     () =>
@@ -1027,17 +1021,17 @@ const Composer: FC<{
       onSubmit={handleSubmit}
     >
       {isTauri ? (
-        // Phase 1 native model drops own Tauri local-path drops. Restore browser
-        // attachment drops in Tauri when Phase 1d adds attachment-token bridging.
+        // Phase 1 native model owns Tauri local-path drops. Restore browser
+        // attachment drops in Tauri once Phase 1d adds token bridging.
         <div className="aui-composer-attachment-dropzone unsloth-composer-surface">
           {composerContent}
         </div>
       ) : (
         <ComposerPrimitive.AttachmentDropzone className="group/dropzone aui-composer-attachment-dropzone unsloth-composer-surface relative">
           {composerContent}
-          {/* Gemini-style drop affordance: shown only while a file is dragged
-              over the composer. Absolutely positioned + pointer-events-none so
-              the dashed outline adds no layout shift and the drop still lands. */}
+          {/* Gemini-style drop affordance, shown while a file is dragged over
+              the composer. Absolute + pointer-events-none so the outline adds
+              no layout shift and the drop still lands. */}
           <div
             className={cn(
               "aui-composer-drop-overlay pointer-events-none absolute inset-0 z-20 flex flex-col items-center justify-center gap-1 overflow-hidden rounded-[32px] bg-background/90 opacity-0 backdrop-blur-sm transition-opacity duration-150 group-data-[dragging=true]/dropzone:opacity-100 dark:bg-card/90",
@@ -1063,13 +1057,12 @@ function isNativeComposing(event: Event) {
   return "isComposing" in event && (event as InputEvent).isComposing === true;
 }
 
-// Fallback timeout for stuck IME composition. When Chrome on Windows talks
-// to a WSL-hosted Studio (issue #5546), `compositionend` never fires after
-// the candidate is committed, so `composingRef` stays true and Send stays
-// disabled. Every compositionupdate / non-composing input resets the timer;
-// only a true gap-after-commit lets it fire. 2500ms is well above a normal
-// candidate-window pause but short enough to recover before the user
-// notices the Send button is stuck.
+// Fallback timeout for stuck IME composition. With Chrome on Windows against
+// a WSL-hosted Studio (issue #5546), `compositionend` never fires after the
+// candidate commits, so `composingRef` stays true and Send stays disabled.
+// Every compositionupdate / non-composing input resets the timer; only a true
+// gap-after-commit lets it fire. 2500ms is above a normal candidate-window
+// pause but short enough to recover before the user notices Send is stuck.
 const IME_STUCK_TIMEOUT_MS = 2500;
 
 function useImeComposerInputHandlers() {
@@ -1153,13 +1146,12 @@ function useImeComposerInputHandlers() {
   );
 
   // If the watchdog cleared the composing flags during a long candidate-window
-  // pause, a subsequent IME keypress (browser-side isComposing=true / IME
-  // keyCode 229) would otherwise reach handleSubmit with composingRef=false
-  // and submit the preedit text. Re-arm composingRef synchronously from the
-  // native event so the form-submit gate keeps blocking until compositionend.
-  // Re-arm the watchdog at the same time — otherwise the WSL+Chrome path
-  // this PR targets (no compositionend, no follow-up input event) would
-  // leave composingRef pinned true indefinitely and Send blocked again.
+  // pause, a later IME keypress (isComposing=true / keyCode 229) would reach
+  // handleSubmit with composingRef=false and submit the preedit text. Re-arm
+  // composingRef synchronously from the native event so the submit gate keeps
+  // blocking until compositionend. Re-arm the watchdog too, or the WSL+Chrome
+  // path (no compositionend, no follow-up input) would pin composingRef true
+  // forever and block Send again.
   const onKeyDown = useCallback(
     (e: KeyboardEvent<HTMLTextAreaElement>) => {
       if (e.nativeEvent.isComposing || e.keyCode === 229) {
@@ -1207,8 +1199,8 @@ const ComposerAudioMenuItem: FC = () => {
   );
 
   // Build the input on document.body, not in the menu: selecting the item
-  // closes the dropdown, which would unmount a menu-rendered input before the
-  // OS picker returns and drop the file.
+  // closes the dropdown, unmounting a menu-rendered input before the OS picker
+  // returns and dropping the file.
   const pickAudio = useCallback(() => {
     const input = document.createElement("input");
     input.type = "file";
@@ -1573,9 +1565,8 @@ const WebSearchToggle: FC = () => {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
   // External providers (OpenAI today) expose a server-side web_search tool
-  // even when the local tool runtime is unavailable — gate the Search pill
-  // on either source so it lights up on external models too. Mirror of
-  // shared-composer's searchDisabled.
+  // even without the local tool runtime; gate the pill on either source so it
+  // lights up on external models too. Mirror of shared-composer's searchDisabled.
   const supportsBuiltinWebSearch = useChatRuntimeStore(
     (s) => s.supportsBuiltinWebSearch,
   );
@@ -1594,7 +1585,7 @@ const WebSearchToggle: FC = () => {
       : undefined;
   const isKimiExternal = selectedExternalProvider?.providerType === "kimi";
   // Disable only when a loaded model lacks the capability; with no model the
-  // tool can still be pre-selected and reflected, matching the + menu.
+  // tool can still be pre-selected, matching the + menu.
   const disabled = modelLoaded && !(supportsTools || supportsBuiltinWebSearch);
 
   return (
@@ -1605,9 +1596,8 @@ const WebSearchToggle: FC = () => {
         const next = !toolsEnabled;
         setToolsEnabled(next);
         // Kimi's $web_search builtin requires thinking=disabled (see
-        // https://platform.kimi.ai/docs/guide/use-web-search). Keep
-        // the two pills mutually exclusive so the visible state always
-        // matches what the backend ends up sending.
+        // https://platform.kimi.ai/docs/guide/use-web-search). Keep the two
+        // pills mutually exclusive so visible state matches what's sent.
         if (isKimiExternal) {
           setReasoningEnabled(!next, { persist: false });
           applyQwenThinkingParams(!next);
@@ -1630,18 +1620,17 @@ const CodeToolsToggle: FC = () => {
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
   const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
-  // External providers have no local tool runtime, but Anthropic's
-  // Claude 4.x dispatches code_execution_20250825 server-side. The
-  // chat-page resolver stashes that capability in the runtime store
-  // (next to supportsBuiltinWebSearch). Mirror of shared-composer's
-  // codeDisabled so this pill lights up in active threads too.
+  // External providers have no local tool runtime, but Anthropic's Claude 4.x
+  // dispatches code_execution_20250825 server-side; the chat-page resolver
+  // stashes that capability in the runtime store (next to
+  // supportsBuiltinWebSearch). Mirror of shared-composer's codeDisabled.
   const supportsBuiltinCodeExecution = useChatRuntimeStore(
     (s) => s.supportsBuiltinCodeExecution,
   );
   const codeToolsEnabled = useChatRuntimeStore((s) => s.codeToolsEnabled);
   const setCodeToolsEnabled = useChatRuntimeStore((s) => s.setCodeToolsEnabled);
   // Disable only when a loaded model lacks the capability; with no model the
-  // tool can still be pre-selected and reflected, matching the + menu.
+  // tool can still be pre-selected, matching the + menu.
   const disabled = modelLoaded && !(supportsTools || supportsBuiltinCodeExecution);
 
   return (
@@ -1672,9 +1661,8 @@ const ImagesToggle: FC = () => {
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
   // OpenAI cloud Responses-API models advertise image_generation as a
-  // server-side tool; no local runtime fallback exists. Mirror of
-  // shared-composer's imageDisabled / showImagePill so the in-thread
-  // composer surfaces the same control as the empty-state composer.
+  // server-side tool; no local runtime fallback. Mirror of shared-composer's
+  // imageDisabled / showImagePill so this composer matches the empty state.
   const supportsBuiltinImageGeneration = useChatRuntimeStore(
     (s) => s.supportsBuiltinImageGeneration,
   );
@@ -1755,10 +1743,9 @@ const ToolStatusDisplay: FC = () => {
 
     setElapsed(0);
 
-    // Debounce badge visibility by 300ms when the badge is not
-    // already on screen. Once visible from a prior tool, consecutive
-    // tools show immediately so the badge does not flicker. Fast
-    // tool calls that all complete under 300ms never show the badge.
+    // Debounce visibility by 300ms when the badge isn't already on screen.
+    // Once visible from a prior tool, later tools show immediately so it
+    // doesn't flicker; tool calls under 300ms never show the badge.
     let showTimer: ReturnType<typeof setTimeout> | undefined;
     if (!visibleRef.current) {
       showTimer = setTimeout(() => setVisible(true), 300);
@@ -1790,8 +1777,8 @@ const ToolStatusDisplay: FC = () => {
     </div>
   );
 };
-// Plus menu: attachment and workflow actions. Opens downward in the centered
-// welcome composer; the docked composer passes side="top" to open upward.
+// Plus menu: attachment and workflow actions. Opens downward in the welcome
+// composer; the docked composer passes side="top" to open upward.
 const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   side = "bottom",
 }) => {
@@ -1806,7 +1793,7 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const setMcpEnabledForChat = useChatRuntimeStore(
     (s) => s.setMcpEnabledForChat,
   );
-  // Capability gating, mirroring the visible pills so menu and pills agree on
+  // Capability gating mirrors the visible pills so menu and pills agree on
   // what a loaded model supports (a tool the backend drops must not look on).
   const modelLoaded = useChatRuntimeStore(
     (s) => !!s.params.checkpoint && !s.modelLoading,
@@ -1889,8 +1876,7 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
         sideOffset={2}
         avoidCollisions={true}
         className="unsloth-plus-menu w-[212px]"
-        // Don't refocus the + on close; the restored focus showed a stray
-        // focus-visible ring.
+        // Don't refocus the + on close; restored focus showed a stray ring.
         onCloseAutoFocus={(event) => event.preventDefault()}
       >
         <ComposerPrimitive.AddAttachment asChild={true}>
diff --git a/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx b/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx
index bc91408789..79789692cb 100644
--- a/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-call-spinner.tsx
@@ -6,11 +6,7 @@
 import { Loader2Icon } from "lucide-react";
 import { cn } from "@/lib/utils";
 
-/**
- * Spinner shown while a tool call is running: a clean circular arc with a
- * rounded cap (lucide Loader2 / LoaderCircle), animated. Inherits the current
- * text color so it matches the surrounding font.
- */
+/** Spinner shown while a tool call runs. Inherits text color to match its surroundings. */
 export function ToolCallSpinner({ className }: { className?: string }) {
   return (
     <Loader2Icon
diff --git a/studio/frontend/src/components/assistant-ui/tool-group.tsx b/studio/frontend/src/components/assistant-ui/tool-group.tsx
index d30c0a8ee1..569e673da3 100644
--- a/studio/frontend/src/components/assistant-ui/tool-group.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-group.tsx
@@ -217,8 +217,8 @@ const ToolGroupImpl: FC<
       ),
   );
 
-  // Single tool calls and artifacts render directly so cards never hide inside
-  // a collapsed tool group.
+  // Render single tool calls and artifacts directly so cards never hide in a
+  // collapsed group.
   if (toolCount <= 1 || containsArtifactTool) {
     return <>{children}</>;
   }
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
index 2573509c34..e27441183e 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-code-execution.tsx
@@ -23,12 +23,9 @@ import {
 } from "./tool-fallback";
 
 /**
- * Renders the synthetic `_toolEvent` chunks emitted by
- * `_stream_anthropic` when Anthropic's `code_execution_20250825` tool
- * fires. The backend collapses Anthropic's two sub-tools
- * (`bash_code_execution`, `text_editor_code_execution`) into a single
- * `tool_name: "code_execution"`, with `arguments.kind` ("bash" or
- * "text_editor") and a per-kind argument shape:
+ * Renders synthetic `_toolEvent` chunks from `_stream_anthropic` for the
+ * `code_execution_20250825` tool. The backend collapses Anthropic's two
+ * sub-tools into `tool_name: "code_execution"` with `arguments.kind`:
  *
  *   kind=bash:        { command: "<shell command>" }
  *   kind=text_editor: { command: "view"|"create"|"str_replace", path, ... }
@@ -141,9 +138,8 @@ const CodeExecutionToolUIImpl: ToolCallMessagePartComponent = ({
     completedLabel = commandLabel ? `Ran \`${commandLabel}\`` : "Ran command";
   }
 
-  // Collapse the card once the model has resumed streaming prose after
-  // the tool call. Mirrors WebSearchToolUI's behavior so the tool-card
-  // doesn't crowd the final answer once the run is done.
+  // Collapse the card once the model resumes streaming prose after the tool
+  // call (mirrors WebSearchToolUI) so it doesn't crowd the final answer.
   const hasText = useAuiState(({ message }) =>
     message.content.some(
       (p) =>
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
index c0ced3b844..edce6200d5 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-image-generation.tsx
@@ -21,26 +21,14 @@ import {
 
 /**
  * Renders the synthetic `_toolEvent` chunks emitted by
- * `_stream_openai_responses` when OpenAI's Responses-API
- * `image_generation` tool fires. The backend stashes the base64
- * PNG/WebP/JPEG (the gpt-image backbone output) on an `image_b64`
- * field of the tool_end event so the JSON result stays small, and the
- * adapter repackages it into a structured `result` shape:
- *
- *   {
- *     image_b64: string,
- *     image_mime: string,        // e.g. "image/png"
- *     size?: string,             // "1024x1024" etc
- *     quality?: string,
- *     background?: string,
- *   }
- *
- * The corresponding `tool_start` carries the prompt as
- * `args.prompt` (after gpt-image's revision pass) plus `args.kind:
- * "image"`. Without this component the generic ToolFallback would
- * print the prompt as JSON args text with an empty Result block --
- * which is exactly the "no image" symptom users hit before this UI
- * landed.
+ * `_stream_openai_responses` when OpenAI's Responses-API `image_generation`
+ * tool fires. The backend stashes the base64 image on `image_b64` of the
+ * tool_end event (keeping the JSON small); the adapter repackages it into a
+ * structured `result` (image_b64, image_mime e.g. "image/png", size? e.g.
+ * "1024x1024", quality?, background?).
+ * The `tool_start` carries the revised prompt as `args.prompt` plus
+ * `args.kind: "image"`. Without this, ToolFallback would print the prompt as
+ * JSON with an empty Result block (the "no image" symptom).
  */
 interface ImageGenerationArgs {
   prompt?: string;
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
index 642340bb5f..1231ca4a7f 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-python.tsx
@@ -72,7 +72,7 @@ function CopyBtn({ text }: { text: string }) {
   );
 }
 
-/** Render code with syntax highlighting via Streamdown + shiki. No extra borders — inherits parent container. */
+/** Syntax-highlighted code via Streamdown + shiki; inherits parent container. */
 function HighlightedCode({ code: source, language }: { code: string; language: string }) {
   const markdown = useMemo(
     () => `\`\`\`${language}\n${truncate(source)}\n\`\`\``,
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
index d5b72e06ea..7b9d555946 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-render-html.tsx
@@ -17,8 +17,8 @@ import { BrowserIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { memo, useEffect } from "react";
 
-// Context7 assistant-ui docs: tool UIs can read streaming args via
-// useToolArgsStatus, so render_html does not need to wait for tool completion.
+// Per Context7 assistant-ui docs: tool UIs read streaming args via
+// useToolArgsStatus, so render_html need not wait for tool completion.
 type RenderHtmlArgs = Record<string, unknown> & {
   code?: string;
   title?: string;
@@ -41,9 +41,8 @@ const RenderHtmlToolUIImpl: ToolCallMessagePartComponent = ({
   const isRunning = status?.type === "running";
   const codeIsStreaming = propStatus.code === "streaming";
 
-  // Surface the backend error when the tool call completed with invalid
-  // args.  Backend success results start with "Rendered HTML artifact";
-  // error results start with "Error:".
+  // Surface the backend error when the tool call completed with invalid args.
+  // Success results start with "Rendered HTML artifact"; errors with "Error:".
   const errorText =
     status?.type === "complete" &&
     typeof result === "string" &&
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
index ef8cb4a89b..062d0b1370 100644
--- a/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-web-search.tsx
@@ -25,9 +25,8 @@ const RE_URL = /URL:\s*(.+)/;
 const RE_SNIPPET = /Snippet:\s*(.+)/s;
 
 /**
- * Reject anything that is not a real http(s) URL. Web-search / web-fetch
- * output is provider-controlled, so hostile ``javascript:`` / ``data:``
- * lines must not reach the Source badge's <a href>.
+ * Reject non-http(s) URLs. Web-search/fetch output is provider-controlled,
+ * so hostile `javascript:` / `data:` lines must not reach a Source <a href>.
  */
 function isSafeHttpUrl(raw: string): boolean {
   const value = raw.trim();
diff --git a/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx b/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
index e4c17a5021..9488ca1db9 100644
--- a/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
+++ b/studio/frontend/src/components/assistant-ui/use-intent-aware-autoscroll.tsx
@@ -18,57 +18,42 @@ import {
 /**
  * Intent-aware autoscroll for a Thread viewport.
  *
- * Why we don't reuse assistant-ui's built-in autoscroll:
- *   `useThreadViewportAutoScroll` runs unconditionally whenever
- *   `ThreadPrimitive.Viewport` is mounted. Even with every
- *   `scrollToBottomOn*` prop disabled, it still installs observers
- *   that write `isAtBottom` to the shared viewport store on every
- *   layout change. On sidebar toggles, browser resizes, or
- *   mobile↔desktop breakpoint crossings, that write races our scroll
- *   correction — whoever writes last wins, and the scroll-to-bottom
- *   button flickers or sticks depending on observer ordering.
+ * Why not assistant-ui's built-in: `useThreadViewportAutoScroll` always
+ * installs observers that write `isAtBottom` to the shared store on every
+ * layout change, even with `scrollToBottomOn*` disabled. On resizes /
+ * breakpoint crossings that write races our correction and the
+ * scroll-to-bottom button flickers depending on observer ordering.
  *
  * Strategy:
- *   - Own `isAtBottom` as local state (exposed via
- *     `useIsThreadAtBottom`). Upstream can still write to its own
- *     store; nobody reads from it.
- *   - Drive the viewport with a single rAF loop governed by a follow
- *     deadline (`followUntilRef`). Any signal that can invalidate
- *     bottom alignment (resize, mutation, AUI event, programmatic
- *     scroll) extends the deadline; the loop pins to the bottom and
- *     reports `isAtBottom=true` until it expires, then settles on
- *     pure DOM observation.
- *   - Detect user intent (wheel up, touch swipe up, scroll direction)
- *     to detach. While detached, resize/mutation signals don't extend
- *     the deadline, so the button appears and stays. Re-attach when
- *     the user scrolls *down* within 24px of the bottom.
+ *   - Own `isAtBottom` as local state (via `useIsThreadAtBottom`); nobody
+ *     reads upstream's store.
+ *   - Drive the viewport via a single rAF loop with a follow deadline
+ *     (`followUntilRef`). Any signal that can invalidate bottom alignment
+ *     extends the deadline; the loop pins and reports `isAtBottom=true`
+ *     until it expires, then settles on DOM observation.
+ *   - Detect user intent (wheel up, swipe up, scroll direction) to detach.
+ *     While detached, resize/mutation don't extend the deadline. Re-attach
+ *     when the user scrolls down within 24px of the bottom.
  */
 
-// 2px, not 1: subpixel rounding on HiDPI displays can leave a fractional
-// gap at the "true" bottom that a 1px threshold reports as not-at-bottom.
+// 2px, not 1: HiDPI subpixel rounding can leave a fractional gap that a
+// 1px threshold reports as not-at-bottom.
 const AT_BOTTOM_THRESHOLD_PX = 2;
 const RE_ATTACH_THRESHOLD_PX = 24;
 const TOUCH_MOVE_THRESHOLD_PX = 4;
-// Cumulative upward movement (summed across scroll events) that
-// counts as a deliberate detach. Summed rather than per-event so that
-// slow 1-px-per-event sources — middle-click autoscroll, scrollbar
-// drags, some trackpads — accumulate instead of slipping under a
-// per-event threshold forever.
+// Cumulative upward movement counting as a deliberate detach. Summed (not
+// per-event) so slow 1px-per-event sources (middle-click autoscroll,
+// scrollbar drags, some trackpads) accumulate instead of slipping under.
 const UPWARD_DETACH_THRESHOLD_PX = 2;
-// Window during which the viewport pins to the bottom through
-// layout/content races. Extends on every resize/mutation, so streaming
-// keeps the viewport pinned as long as content keeps arriving; settles
-// this long after the last change.
+// Window the viewport stays pinned through layout/content races. Extends
+// on every resize/mutation, so streaming keeps it pinned; settles this
+// long after the last change.
 const FOLLOW_SETTLE_MS = 600;
-// Maximum stabilizer compensation. The stabilizer is meant to absorb
-// sub-frame transients (~5-15px shiki re-renders, ~8px action-bar
-// reservation drift). Anything larger is almost certainly an intentional
-// content removal — message delete, regenerate's old-content clear,
-// reasoning-panel collapse — and should *not* be silently padded over,
-// which would leave persistent empty space below the last message.
-// Above this threshold we release the stabilizer immediately and let
-// the autoscroll re-pin to the new content height, which is the natural
-// behavior the user expects for those actions.
+// Max stabilizer compensation. Absorbs sub-frame transients (~5-15px shiki
+// re-renders, ~8px action-bar drift). Larger shrinks are intentional
+// content removals (delete, regenerate clear, reasoning collapse); padding
+// those over leaves empty space, so above this we release and let
+// autoscroll re-pin to the new height.
 const STABILIZER_MAX_PX = 64;
 
 export type ScrollToBottom = (behavior?: ScrollBehavior) => void;
@@ -78,11 +63,10 @@ type AutoScrollContextValue = {
   getIsAtBottom: () => boolean;
   subscribe: (listener: () => void) => () => void;
   /**
-   * Mark the user as detached from the bottom, as if they had scrolled
-   * up. Called when the composer grows and the bottom spacer grows with
-   * it: the chat is then above the new bottom, and observer-driven pins
-   * must not shove it up. Scrolling back to the bottom re-attaches;
-   * explicit pins (run start, scroll-to-bottom button) still work.
+   * Mark the user as detached, as if they scrolled up. Called when the
+   * composer (and bottom spacer) grow: the chat is then above the new
+   * bottom and observer-driven pins must not shove it up. Scrolling back
+   * re-attaches; explicit pins (run start, button) still work.
    */
   detachFromBottom: () => void;
 };
@@ -191,24 +175,18 @@ export function useIntentAwareAutoScroll(): {
       const atBottomStrict = (): boolean =>
         distanceFromBottom() <= AT_BOTTOM_THRESHOLD_PX;
 
-      // True only when there is room to scroll upward. Guards the
-      // wheel/touch detach paths: a wheel-up or swipe-down gesture on
-      // a viewport with nothing above (short thread, or already at
-      // the top) can't express intent to leave the bottom and must
-      // not flip userDetachedRef — otherwise later streaming updates
-      // skip extendFollow and auto-follow stays dead for the session.
+      // Room to scroll upward. Guards wheel/touch detach: a gesture on a
+      // viewport with nothing above can't express intent to leave the
+      // bottom and must not flip userDetachedRef, else later streaming
+      // skips extendFollow and auto-follow stays dead for the session.
       const canScrollUp = (): boolean => el.scrollTop > 0;
 
-      // True when a nested scrollable ancestor of the event target
-      // (e.g. the reasoning panel's own overflow-y-auto region, or
-      // any tool output with internal scroll) has room above and
-      // will therefore consume the upward delta before it reaches
-      // the viewport. Walking stops at the viewport element itself,
-      // so only intermediate inner scrollers count.
-      //
-      // Wheel and touchmove events bubble, so without this check a
-      // user reading back through a long reasoning pane mid-stream
-      // would falsely detach the outer viewport.
+      // True when a nested scrollable ancestor of the target (reasoning
+      // panel, tool output) has room above and will consume the upward
+      // delta before it reaches the viewport. Walk stops at the viewport,
+      // so only intermediate inner scrollers count. Without this, wheel/
+      // touchmove bubbling would falsely detach while reading a long
+      // reasoning pane mid-stream.
       const innerScrollWillConsumeUpward = (
         target: EventTarget | null,
       ): boolean => {
@@ -230,10 +208,8 @@ export function useIntentAwareAutoScroll(): {
         return false;
       };
 
-      // Stabilizer state — see `stabilize` below for the full
-      // explanation. Lives in this closure so it resets naturally
-      // whenever the viewport remounts (Compare-pane swap, thread
-      // switch with remount, etc.).
+      // Stabilizer state (see `stabilize`). In this closure so it resets
+      // when the viewport remounts (Compare-pane swap, thread switch).
       let stabilizerPx = 0;
       let maxContentHeight = 0;
 
@@ -255,11 +231,10 @@ export function useIntentAwareAutoScroll(): {
       const detach = (): void => {
         userDetachedRef.current = true;
         followUntilRef.current = 0;
-        // The stabilizer is only meaningful while we're actively
-        // pinning to the bottom. Once the user scrolls up, drop any
-        // residual padding so the bottom stays flush whenever they
-        // come back. Safe here because the user is mid-content —
-        // shrinking scrollHeight cannot cap their scrollTop.
+        // The stabilizer only matters while pinning. Once the user
+        // scrolls up, drop residual padding so the bottom stays flush on
+        // return. Safe mid-content: shrinking scrollHeight can't cap their
+        // scrollTop.
         releaseStabilizer();
         maxContentHeight = el.scrollHeight;
       };
@@ -270,12 +245,10 @@ export function useIntentAwareAutoScroll(): {
         }
       };
 
-      // Single rAF loop. While within the follow window and not
-      // detached, pin the viewport to the bottom and report
-      // isAtBottom=true every frame. Otherwise settle on whatever the
-      // DOM says. Scheduling is edge-triggered: scroll/resize/mutation
-      // events call requestTick(), and the loop self-perpetuates only
-      // as long as pinning is still active.
+      // Single rAF loop. Within the follow window and not detached, pin to
+      // bottom and report isAtBottom=true each frame; otherwise settle on
+      // the DOM. Edge-triggered: scroll/resize/mutation call requestTick(),
+      // and the loop self-perpetuates only while pinning is active.
       const tick = (): void => {
         rafId = null;
         const following =
@@ -304,8 +277,8 @@ export function useIntentAwareAutoScroll(): {
         requestTick();
       };
 
-      // Programmatic detach (see detachFromBottom). Same effect as the
-      // user scrolling up; the tick refresh updates isAtBottom.
+      // Programmatic detach (see detachFromBottom). Same as scrolling up;
+      // the tick refresh updates isAtBottom.
       detachImplRef.current = () => {
         detach();
         requestTick();
@@ -363,17 +336,12 @@ export function useIntentAwareAutoScroll(): {
             extendFollow();
           }
         } else if (delta < 0 && !userDetachedRef.current) {
-          // Upward: sum across events. Middle-click autoscroll and
-          // some trackpads deliver 1px-per-event scrolls that each
-          // slip under a per-event threshold; summing catches them.
-          //
-          // Count distance-from-bottom growth, not raw scrollTop
-          // delta. When content above collapses (reasoning panels
-          // auto-closing after streaming, tool outputs auto-hiding),
-          // browsers scroll-anchor to keep visible content stable:
-          // scrollTop decreases but scrollHeight decreases by the
-          // same amount, so distance is unchanged. Those layout-
-          // induced deltas must not flip user intent.
+          // Upward: sum across events to catch 1px-per-event sources
+          // (middle-click autoscroll, some trackpads) that slip under a
+          // per-event threshold. Count distance-from-bottom growth, not
+          // raw scrollTop delta: when content above collapses, browsers
+          // scroll-anchor so scrollTop and scrollHeight drop together and
+          // distance is unchanged. Those layout deltas must not flip intent.
           const distanceDelta = distanceNow - lastDistanceFromBottom;
           if (distanceDelta > 0) {
             upwardAccumulator += distanceDelta;
@@ -393,37 +361,25 @@ export function useIntentAwareAutoScroll(): {
 
       // Scroll stabilizer.
       //
-      // Problem: when a trailing code block finalizes at stream end
-      // (Streamdown flips `isAnimating` → false, shiki re-renders the
-      // <pre> with highlight spans), the block's rendered height
-      // briefly dips and then recovers a frame later. That dip shrinks
-      // `scrollHeight`, which the browser handles by *synchronously*
-      // capping `scrollTop` to the new (smaller) `scrollHeight −
-      // clientHeight`. The cap is visible as a one-frame upward jump;
-      // the recovery a frame or two later is the "snap back" the user
-      // perceives as a flicker. No amount of programmatic re-scrolling
-      // can prevent this — once `scrollHeight` drops, the cap has
-      // already happened and `scrollTop` cannot be pushed past the new
-      // max.
+      // Problem: when a trailing code block finalizes (shiki re-renders the
+      // <pre> with highlight spans), its height briefly dips then recovers.
+      // The dip shrinks `scrollHeight`, so the browser synchronously caps
+      // `scrollTop` to the new max — a one-frame upward jump, then a
+      // "snap back". Re-scrolling can't help: once scrollHeight drops the
+      // cap has happened and scrollTop can't exceed the new max.
       //
-      // Fix: keep `scrollHeight` monotonic across the follow window.
-      // We track the maximum *content* height (scrollHeight minus our
-      // own padding contribution) seen during follow, and compensate
-      // for any shortfall by writing the deficit into a CSS custom
-      // property `--aui-scroll-stabilizer`, which the viewport's
-      // `padding-bottom` reads. A 5px content shrink instantly grows
-      // the padding by 5px, so the browser sees no scrollHeight change
-      // and never caps scrollTop. As content naturally grows past its
-      // prior high-water mark (e.g. the next message streams in), the
-      // padding shrinks back toward zero.
+      // Fix: keep `scrollHeight` monotonic across the follow window. Track
+      // max content height (scrollHeight minus our padding) and write any
+      // shortfall into CSS var `--aui-scroll-stabilizer`, read by the
+      // viewport's padding-bottom. A 5px shrink grows padding 5px so the
+      // browser sees no scrollHeight change. Padding shrinks back to zero
+      // as content grows past its prior high-water mark.
       //
-      // Self-contained: lives entirely on the viewport element via a
-      // CSS variable. Doesn't touch the composer, the action bar, the
-      // message footer, the spacer, or any other UI.
+      // Self-contained: lives on the viewport element via a CSS variable,
+      // touching no other UI.
       //
-      // Returns the post-adjustment scrollHeight so a single layout
-      // read per observer callback can feed both stabilization and
-      // pinning, avoiding a redundant flush.
+      // Returns the post-adjustment scrollHeight so one layout read per
+      // observer callback feeds both stabilization and pinning.
       const stabilize = (): number => {
         const sh = el.scrollHeight;
         const currentContent = sh - stabilizerPx;
@@ -431,9 +387,8 @@ export function useIntentAwareAutoScroll(): {
           !userDetachedRef.current &&
           performance.now() < followUntilRef.current;
         if (!followActive) {
-          // Outside the follow window we stop adjusting, but we keep
-          // `maxContentHeight` aligned with reality so the next follow
-          // session starts from the current content size, not stale.
+          // Outside the follow window: stop adjusting but keep
+          // maxContentHeight current so the next session isn't stale.
           maxContentHeight = currentContent;
           return sh;
         }
@@ -441,14 +396,11 @@ export function useIntentAwareAutoScroll(): {
           maxContentHeight = currentContent;
         }
         const shrink = maxContentHeight - currentContent;
-        // Large shrinks (over STABILIZER_MAX_PX) are intentional content
-        // removals — message delete, regenerate clearing the old
-        // assistant turn, reasoning-panel collapse. Compensating for
-        // those would leave persistent empty space at the bottom of the
-        // viewport, which the user reads as "weird empty gap." Release
-        // the stabilizer instead and rebase the high-water mark; the
-        // pinIfFollowing call right after will smoothly re-anchor to
-        // the new (smaller) bottom.
+        // Large shrinks (over STABILIZER_MAX_PX) are intentional removals
+        // (delete, regenerate clear, reasoning collapse). Compensating
+        // would leave an empty gap, so release the stabilizer and rebase
+        // the high-water mark; the pinIfFollowing call below re-anchors to
+        // the new bottom.
         if (shrink > STABILIZER_MAX_PX) {
           maxContentHeight = currentContent;
           if (stabilizerPx !== 0) {
@@ -468,10 +420,9 @@ export function useIntentAwareAutoScroll(): {
         return currentContent + stabilizerPx;
       };
 
-      // Synchronous pin-to-bottom. Observer callbacks run in the event-
-      // loop's "update the rendering" step (after layout, before paint),
-      // so the scrollTo here is composited in the same frame as the
-      // mutation that triggered the observer.
+      // Synchronous pin-to-bottom. Observer callbacks run after layout,
+      // before paint, so this scrollTo composites in the same frame as the
+      // triggering mutation.
       const pinIfFollowing = (scrollHeight: number): void => {
         if (userDetachedRef.current) {
           return;
@@ -485,10 +436,8 @@ export function useIntentAwareAutoScroll(): {
         el.scrollTo({ top: scrollHeight, behavior: "instant" });
       };
 
-      // All three layout-change signals fan in here so there's a
-      // single place to understand "what runs when the viewport's
-      // content shape changes". Order matters: extend first so the
-      // stabilizer sees the follow window as active; stabilize before
+      // All three layout-change signals fan in here. Order matters: extend
+      // first so the stabilizer sees follow as active; stabilize before
       // pinning so we scroll to the post-adjustment scrollHeight.
       const onLayoutChange = (): void => {
         extendFollow();
@@ -501,18 +450,17 @@ export function useIntentAwareAutoScroll(): {
       const mutationObserver = new MutationObserver(onLayoutChange);
       const onViewportResize = onLayoutChange;
 
-      // Fresh attach (a new viewport element) always starts pinned.
-      // Rebinds to the SAME element must not pin or reset detach state:
-      // the Viewport composes refs with an identity that changes on
-      // re-render, so React re-runs the ref (null, then same element)
-      // on unrelated renders such as composer resizes. Pinning here
-      // would yank the chat to the bottom on every such render. The
-      // observers below are re-installed either way.
+      // Fresh attach always starts pinned. Rebinds to the SAME element must
+      // not pin or reset detach state: the Viewport's composed ref identity
+      // changes on re-render, so React re-runs the ref (null, then same
+      // element) on unrelated renders (composer resizes); pinning would
+      // yank the chat to bottom each time. Observers are re-installed either
+      // way.
       if (!isRebind) {
         userDetachedRef.current = false;
 
-        // Pin to bottom when the ref first attaches. Covers the case
-        // where `thread.initialize` fires before the ref is bound.
+        // Pin on first attach, covering thread.initialize firing before the
+        // ref is bound.
         extendFollow();
         if (el.scrollHeight > el.clientHeight) {
           el.scrollTo({ top: el.scrollHeight, behavior: "instant" });
@@ -521,23 +469,19 @@ export function useIntentAwareAutoScroll(): {
       }
       requestTick();
 
-      // Observe the border box, not the content box. The stabilizer
-      // writes `padding-bottom`, which shrinks the content box; if we
-      // observed that, every stabilizer adjustment would echo back as
-      // a resize and re-enter onLayoutChange. Border-box stays put
-      // through padding changes but still tracks parent-driven
-      // resizes (window, sidebar toggle) — which is all we need.
+      // Observe the border box, not content box. The stabilizer writes
+      // padding-bottom (shrinks the content box); observing that would echo
+      // every adjustment back as a resize into onLayoutChange. Border-box is
+      // stable through padding changes but still tracks parent resizes.
       resizeObserver.observe(el, { box: "border-box" });
       mutationObserver.observe(el, {
         childList: true,
         subtree: true,
         characterData: true,
-        // Layout-affecting attributes only. Excludes `style`, which
-        // elements may mutate in response to viewport state (feedback
-        // loop). `class` catches Tailwind show/hide; `hidden` /
-        // `aria-hidden` / `aria-expanded` / `data-state` catch Radix
-        // and native collapsible toggles that change scrollHeight
-        // without triggering the viewport ResizeObserver.
+        // Layout-affecting attributes only. Excludes `style` (elements may
+        // mutate it in response to viewport state → feedback loop). `class`
+        // catches Tailwind show/hide; the rest catch Radix/native
+        // collapsibles that change scrollHeight without a viewport resize.
         attributes: true,
         attributeFilter: [
           "class",
@@ -551,10 +495,9 @@ export function useIntentAwareAutoScroll(): {
       el.addEventListener("touchstart", onTouchStart, { passive: true });
       el.addEventListener("touchmove", onTouchMove, { passive: true });
       el.addEventListener("scroll", onScroll, { passive: true });
-      // ResizeObserver above covers browser-window resizes (they resize
-      // the viewport element). visualViewport.resize is the only signal
-      // for iOS software-keyboard changes, where the visual viewport
-      // shrinks without the viewport element's clientHeight changing.
+      // ResizeObserver covers window resizes. visualViewport.resize is the
+      // only signal for iOS software-keyboard changes, where the visual
+      // viewport shrinks without the element's clientHeight changing.
       window.visualViewport?.addEventListener("resize", onViewportResize);
 
       return () => {
@@ -580,10 +523,9 @@ export function useIntentAwareAutoScroll(): {
     [setIsAtBottom],
   );
 
-  // Thread lifecycle moments that always pin to the bottom, regardless
-  // of prior detach state. "auto" respects CSS smooth scrolling for
-  // runStart so new turns glide in; "instant" snaps for load/switch
-  // where any animation would just be wasted motion.
+  // Thread lifecycle moments that always pin, regardless of detach state.
+  // "auto" respects CSS smooth scroll for runStart (new turns glide in);
+  // "instant" snaps for load/switch where animation is wasted.
   const pinToBottom = useCallback((behavior: ScrollBehavior) => {
     userDetachedRef.current = false;
     scrollImplRef.current(behavior);
diff --git a/studio/frontend/src/components/shutdown-dialog.tsx b/studio/frontend/src/components/shutdown-dialog.tsx
index dfeafb33eb..e3e6ca9920 100644
--- a/studio/frontend/src/components/shutdown-dialog.tsx
+++ b/studio/frontend/src/components/shutdown-dialog.tsx
@@ -18,10 +18,9 @@ import {
 interface ShutdownDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  /** Called after the shutdown API returns success, right before we replace
-   *  document.body with the "Server stopped" page. Callers use this to remove
-   *  their beforeunload listener — otherwise the browser would prompt
-   *  "Leave site?" when the user tries to close the final tab. */
+  /** Called after shutdown succeeds, before we replace document.body. Lets
+   *  callers remove their beforeunload listener so the browser doesn't prompt
+   *  "Leave site?" when closing the final tab. */
   onAfterShutdown?: () => void;
 }
 
@@ -44,7 +43,7 @@ export function ShutdownDialog({
         return;
       }
     } catch {
-      // Network error — shutdown request never reached the server
+      // Network error: request never reached the server
       toastError("Could not reach server");
       setStopping(false);
       return;
diff --git a/studio/frontend/src/components/tauri/window-titlebar.tsx b/studio/frontend/src/components/tauri/window-titlebar.tsx
index b3180e6663..2ef3258902 100644
--- a/studio/frontend/src/components/tauri/window-titlebar.tsx
+++ b/studio/frontend/src/components/tauri/window-titlebar.tsx
@@ -137,7 +137,7 @@ export function WindowTitlebar({
       const appWindow = await getAppWindow();
       setMaximized(await appWindow.isMaximized());
     } catch {
-      // If a window permission is not ready yet, keep the previous visual state.
+      // Window permission not ready yet: keep previous visual state.
     }
   }, [enabled]);
 
diff --git a/studio/frontend/src/config/env.ts b/studio/frontend/src/config/env.ts
index 3839706d25..92dad2ae27 100644
--- a/studio/frontend/src/config/env.ts
+++ b/studio/frontend/src/config/env.ts
@@ -11,7 +11,7 @@ export const env = {
   BASE_URL: import.meta.env.BASE_URL,
 } as const;
 
-// ── Platform / device type ──────────────────────────────────
+// Platform / device type
 
 export type DeviceType = "mac" | "windows" | "linux" | string;
 
@@ -22,7 +22,7 @@ interface PlatformState {
   isChatOnly: () => boolean;
 }
 
-// Client-side platform detection as fallback when backend isn't ready yet.
+// Client-side fallback when backend isn't ready yet.
 function detectLocalPlatform(): DeviceType {
   if (typeof navigator === "undefined") return "linux";
   const platform = navigator.platform.toLowerCase();
@@ -55,9 +55,9 @@ export async function fetchDeviceType(): Promise<DeviceType> {
       return deviceType;
     }
   } catch {
-    // Backend not ready — use client-side detection so chat-only guard
-    // still works on initial load (important for macOS). Keep fetched=false
-    // so a later call retries against the backend.
+    // Backend not ready: use client-side detection so chat-only guard works
+    // on initial load (important for macOS). Keep fetched=false so a later
+    // call retries against the backend.
     const deviceType = detectLocalPlatform();
     const chatOnly = deviceType === "mac";
     usePlatformStore.setState({ deviceType, chatOnly, fetched: false });
diff --git a/studio/frontend/src/features/auth/api.ts b/studio/frontend/src/features/auth/api.ts
index 95296d3ab9..6356f89378 100644
--- a/studio/frontend/src/features/auth/api.ts
+++ b/studio/frontend/src/features/auth/api.ts
@@ -168,9 +168,8 @@ export async function authFetch(
     });
   } catch (err) {
     if (err instanceof TypeError) {
-      // fetch TypeError = offline | backend down | CORS/DNS. In Tauri
-      // it's always backend-down; in the web build distinguish offline
-      // so the user gets the right recovery path.
+      // fetch TypeError = offline | backend down | CORS/DNS. Tauri is always
+      // backend-down; the web build distinguishes offline for the right message.
       if (!isTauri && typeof navigator !== "undefined" && navigator.onLine === false) {
         throw new Error(
           "You appear to be offline. Check your network connection and try again.",
@@ -227,10 +226,9 @@ async function postLogout(accessToken: string | null): Promise<Response | null>
 }
 
 export async function logout(): Promise<void> {
-  // Server-side revoke. If the access token is expired the 401 fires
-  // BEFORE revoke runs; rotate via the refresh token and retry so the
-  // refresh family is actually revoked. Generation bump in finally
-  // invalidates any in-flight refresh from before this call.
+  // Server-side revoke. If the access token is expired, the 401 fires before
+  // revoke runs; rotate via the refresh token and retry so the refresh family
+  // is revoked. The finally generation bump invalidates in-flight refreshes.
   try {
     let response = await postLogout(getAuthToken());
     if (response && response.status === 401 && getRefreshToken()) {
diff --git a/studio/frontend/src/features/auth/components/auth-form.tsx b/studio/frontend/src/features/auth/components/auth-form.tsx
index c1606c7020..f2017ff0b6 100644
--- a/studio/frontend/src/features/auth/components/auth-form.tsx
+++ b/studio/frontend/src/features/auth/components/auth-form.tsx
@@ -12,8 +12,8 @@ import type { ReactElement } from "react";
 import type { SyntheticEvent } from "react";
 import { refreshSession } from "../api";
 
-// Bootstrap credentials injected into index.html by the backend
-// (only present while default admin must_change_password is true)
+// Bootstrap credentials injected into index.html by the backend (only present
+// while default admin must_change_password is true)
 declare global {
   interface Window {
     __UNSLOTH_BOOTSTRAP__?: { username: string; password: string };
@@ -93,9 +93,9 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
     let canceled = false;
 
     async function initializeAuthForm(): Promise<void> {
-      // Always check the server first — localStorage flags can be stale
-      // (e.g. tokens from a previous install attempt).  The server's
-      // /api/auth/status is the source of truth for requires_password_change.
+      // Always check the server first; localStorage flags can be stale (e.g.
+      // tokens from a previous install). /api/auth/status is the source of
+      // truth for requires_password_change.
       try {
         const response = await fetch(apiUrl("/api/auth/status"));
         if (!response.ok) throw new Error("Failed to load auth status.");
@@ -109,7 +109,7 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
             setMustChangePassword(result.requires_password_change);
           }
 
-          // Redirect between login ↔ change-password based on server state
+          // Redirect between login / change-password per server state
           if (mode === "login" && result.requires_password_change) {
             navigate({ to: "/change-password" });
             return;
@@ -119,8 +119,8 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
             return;
           }
 
-          // On login page, if user already has a valid session and no
-          // password change is required, skip straight to the app.
+          // On login, skip to the app if a valid session exists and no
+          // password change is required.
           if (isLoginMode && !result.requires_password_change) {
             if (hasRefreshToken()) {
               const refreshed = await refreshSession();
@@ -293,12 +293,12 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
       storeAuthTokens(token.access_token, token.refresh_token);
       navigate({ to: getPostAuthRoute() });
     } catch (err: unknown) {
-      // The backend already returns the correct, PATH-based command
-      // ("unsloth studio reset-password"), which the installer puts on PATH on
-      // every platform. Do NOT rewrite it to a relative Windows path like
-      // ".\unsloth_studio\Scripts\unsloth.exe ..." -- that only resolves when the
-      // terminal happens to be inside the Studio home dir, so it fails with
-      // CommandNotFoundException everywhere else. Show the backend message as-is.
+      // The backend returns the correct PATH-based command ("unsloth studio
+      // reset-password"), which the installer puts on PATH on every platform.
+      // Do NOT rewrite it to a relative Windows path like
+      // ".\unsloth_studio\Scripts\unsloth.exe ..." -- that only resolves inside
+      // the Studio home dir and fails with CommandNotFoundException elsewhere.
+      // Show the backend message as-is.
       const msg = err instanceof Error ? err.message : "Auth failed.";
       setError(msg);
     } finally {
diff --git a/studio/frontend/src/features/auth/session.ts b/studio/frontend/src/features/auth/session.ts
index 1e3234590a..e398ee0608 100644
--- a/studio/frontend/src/features/auth/session.ts
+++ b/studio/frontend/src/features/auth/session.ts
@@ -39,9 +39,9 @@ export function storeAuthTokens(
   accessToken: string,
   refreshToken: string,
 ): void {
-  // Callers set must_change_password via setMustChangePassword(). Routing it
-  // through here would let CodeQL trace the boolean to localStorage and flag
-  // the (deliberate) JWT writes as sensitive-info storage.
+  // must_change_password is set via setMustChangePassword(), not here: routing
+  // it through would let CodeQL trace the boolean into localStorage and flag the
+  // deliberate JWT writes as sensitive-info storage.
   if (!canUseStorage()) return;
   localStorage.setItem(AUTH_TOKEN_KEY, accessToken);
   localStorage.setItem(AUTH_REFRESH_TOKEN_KEY, refreshToken);
@@ -54,10 +54,9 @@ export function clearAuthTokens(): void {
   localStorage.removeItem(AUTH_MUST_CHANGE_PASSWORD_KEY);
 }
 
-// Encode the flag as key presence (literal "1" or absence) so localStorage
-// receives a constant, not a derived boolean. Breaks the CodeQL data flow
-// from TokenResponse.must_change_password into localStorage.setItem; the
-// stored value is a route hint (/change-password vs /chat), not a secret.
+// Flag stored as key presence (constant "1" or absence), not a derived boolean,
+// so CodeQL doesn't flow must_change_password into localStorage.setItem. The
+// value is a route hint (/change-password vs /chat), not a secret.
 export function mustChangePassword(): boolean {
   if (!canUseStorage()) return false;
   return localStorage.getItem(AUTH_MUST_CHANGE_PASSWORD_KEY) !== null;
diff --git a/studio/frontend/src/features/auth/tauri-auto-auth.ts b/studio/frontend/src/features/auth/tauri-auto-auth.ts
index 44884796d3..760af26395 100644
--- a/studio/frontend/src/features/auth/tauri-auto-auth.ts
+++ b/studio/frontend/src/features/auth/tauri-auto-auth.ts
@@ -20,8 +20,8 @@ type TauriAutoAuthOptions = {
   force?: boolean;
 };
 
-// Concurrency guard: multiple route guards can call tauriAutoAuth simultaneously.
-// Without this, the first-launch password-change could race with itself.
+// Concurrency guard: multiple route guards can call tauriAutoAuth at once;
+// without this the first-launch password-change could race with itself.
 let pending: { promise: Promise<boolean>; force: boolean } | null = null;
 let lastTauriAuthFailure: string | null = null;
 
@@ -61,7 +61,7 @@ async function doTauriAutoAuth(options: TauriAutoAuthOptions): Promise<boolean>
     return true;
   }
 
-  // Try refreshing existing session
+  // Try refreshing an existing session.
   if (!options.force && hasRefreshToken()) {
     const refreshed = await refreshSession();
     if (refreshed && hasAuthToken() && !mustChangePassword()) {
diff --git a/studio/frontend/src/features/chat/api-provider-logo.tsx b/studio/frontend/src/features/chat/api-provider-logo.tsx
index 09794e3acf..f9d574b8fa 100644
--- a/studio/frontend/src/features/chat/api-provider-logo.tsx
+++ b/studio/frontend/src/features/chat/api-provider-logo.tsx
@@ -7,8 +7,8 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { isCustomProviderType } from "./external-providers";
 
 /**
- * Registry logos live at `public/provider-logos/{provider_type}.{ext}` where `provider_type`
- * matches `PROVIDER_REGISTRY` keys exactly (lowercase). Extension varies by asset (svg preferred).
+ * Registry logos at `public/provider-logos/{provider_type}.{ext}`; key matches
+ * `PROVIDER_REGISTRY` (lowercase). Extension varies per asset (svg preferred).
  */
 const PROVIDER_LOGO_EXT: Record<string, "svg" | "png" | "jpg"> = {
   openai: "svg",
@@ -41,9 +41,8 @@ interface ApiProviderLogoProps {
 }
 
 /**
- * Renders the logo for a registry provider type when `provider_type.{ext}` exists under
- * `public/provider-logos/`.
- * OpenAI's asset is black-on-transparent; it is inverted in dark mode for contrast.
+ * Renders a registry provider's logo when its asset exists under
+ * `public/provider-logos/`. OpenAI's is inverted in dark mode for contrast.
  */
 export function ApiProviderLogo({ providerType, className, title }: ApiProviderLogoProps) {
   const src = apiProviderLogoSrc(providerType);
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 44b8507906..31f73c37bd 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -80,7 +80,7 @@ interface ServerUsage {
   completion_tokens: number;
   total_tokens: number;
   // External prompt-cache fields (see _build_usage_chunk in
-  // external_provider.py). cache_creation is Anthropic-only.
+  // external_provider.py); cache_creation is Anthropic-only.
   prompt_tokens_details?: {
     cached_tokens?: number;
   };
@@ -107,9 +107,9 @@ type RunMessage = RunMessages[number];
 /** Tracks which user messages were sent with an audio file (messageId → filename). */
 export const sentAudioNames = new Map<string, string>();
 
-// Synthetic provider-side tool names; backend stamps args._server_tool
-// so user functions with the same name aren't dropped. Mirror of
-// _SERVER_SIDE_BUILTIN_TOOL_NAMES on the backend.
+// Synthetic provider-side tool names; backend stamps args._server_tool so
+// user functions with the same name aren't dropped. Mirror of backend
+// _SERVER_SIDE_BUILTIN_TOOL_NAMES.
 const SERVER_SIDE_BUILTIN_TOOL_NAMES = new Set<string>([
   "web_search",
   "web_fetch",
@@ -118,10 +118,10 @@ const SERVER_SIDE_BUILTIN_TOOL_NAMES = new Set<string>([
 ]);
 
 /**
- * Whether a persisted tool-call part is provider-side synthetic and
- * should be stripped from outbound history. Match on the
- * args._server_tool marker or a Gemini native_part payload — no shape
- * heuristic, because user functions can legitimately share a name.
+ * Whether a persisted tool-call part is provider-side synthetic and should
+ * be stripped from outbound history. Matches on the args._server_tool marker
+ * or a Gemini native_part payload (no shape heuristic, since user functions
+ * can legitimately share a name).
  */
 function isServerSideBuiltinToolPart(
   toolNameLower: string,
@@ -176,23 +176,19 @@ export function useThreadAutosaveHandle(): ThreadAutosaveHandle {
 }
 
 /**
- * Match error messages that indicate the request filled or would fill
- * the KV cache, so the UI can show a dedicated toast pointing at the
- * ``Context Length`` setting.
+ * Match error messages indicating the request filled (or would fill) the KV
+ * cache, so the UI can toast a pointer at the ``Context Length`` setting.
  *
  * Two wordings reach the client and both must hit:
- *
- *   1. The raw llama-server text when ``--no-context-shift`` trips --
+ *   1. Raw llama-server text when ``--no-context-shift`` trips:
  *      "the request exceeds the available context size (N tokens)".
- *   2. The rewritten friendly text emitted by
- *      ``backend/routes/inference.py::_friendly_error`` -- "Message too
- *      long: X tokens exceeds the Y-token context window. Try
- *      increasing the Context Length ..." This is the one most users
- *      see on the streaming GGUF path.
+ *   2. The friendly rewrite from
+ *      ``backend/routes/inference.py::_friendly_error``: "Message too long:
+ *      ... context window. Try increasing the Context Length ..." (the one
+ *      most users see on the streaming GGUF path).
  *
- * We match on substrings rather than full regexes because both layers
- * have drifted across versions (llama.cpp master has tweaked the
- * phrasing; ``_friendly_error`` has gone through several copy edits).
+ * Match substrings, not full regexes: both layers have drifted across
+ * versions (llama.cpp phrasing and _friendly_error copy edits).
  */
 export function isContextLimitError(message: string): boolean {
   if (!message) return false;
@@ -224,10 +220,10 @@ async function updateStoredChatThreadEventually(
 }
 
 /**
- * Return ``raw`` when it is a safe-to-navigate http(s) URL, or "" otherwise.
+ * Return ``raw`` when it is a safe-to-navigate http(s) URL, else "".
  * Rejects non-string input, CR/LF (header injection), and non-http(s)
- * schemes (``javascript:`` / ``data:`` / ``vbscript:``) so provider /
- * tool-controlled strings cannot land in an <a href>.
+ * schemes (``javascript:`` / ``data:`` / ``vbscript:``) so provider/tool-
+ * controlled strings cannot land in an <a href>.
  */
 function isSafeNavigableSourceUrl(raw: unknown): string {
   if (typeof raw !== "string") return "";
@@ -264,10 +260,9 @@ function documentCitationToSource(
     "";
   const docIndex =
     typeof cit.document_index === "number" ? cit.document_index : undefined;
-  // Only treat ``source`` as a navigable URL when it is real http(s);
+  // Only treat ``source`` as navigable when it is real http(s);
   // search_result_location can carry a free-form id (e.g. ``kb-doc-42``)
-  // or a hostile ``javascript:`` / ``data:`` / ``vbscript:`` string.
-  // Fall back to a stable doc anchor otherwise.
+  // or a hostile scheme. Fall back to a stable doc anchor otherwise.
   const url =
     isSafeNavigableSourceUrl(source) || `#anthropic-doc-${docIndex ?? fallbackIdx}`;
   const title = docTitle || source || `Document ${fallbackIdx + 1}`;
@@ -277,9 +272,8 @@ function documentCitationToSource(
   const description =
     cited.length > 240 ? `${cited.slice(0, 240)}...` : cited;
   // Anthropic numbers inline [N] per citation, not per source URL.
-  // Fold citation type + position-bearing fields into the id so two
-  // distinct citations on the same source (or two search_result_locations
-  // with different search_result_index) keep separate Sources entries.
+  // Fold citation type + position-bearing fields into the id so distinct
+  // citations on the same source keep separate Sources entries.
   const citationType =
     typeof cit.type === "string" ? String(cit.type) : "";
   const positionParts = [
@@ -333,8 +327,8 @@ function parseSourcesFromResult(raw: string): {
     const snippetMatch = block.match(/Snippet:\s*(.+)/);
     if (titleMatch && urlMatch) {
       // Drop blocks whose ``URL:`` is not safe http(s); provider/tool
-      // output is attacker-controllable so a hostile ``javascript:`` /
-      // ``data:`` line must not reach the Sources panel <a href>.
+      // output is attacker-controllable, so a hostile scheme must not
+      // reach the Sources panel <a href>.
       const url = isSafeNavigableSourceUrl(urlMatch[1]);
       if (!url) continue;
       const snippet = snippetMatch?.[1]?.trim();
@@ -363,21 +357,18 @@ function estimateTokenCount(text: string): number | undefined {
  * Normalize a streamed `delta.content` to a plain text string.
  *
  * OpenAI Chat Completions originally typed `delta.content` as a string, but
- * a number of providers now emit it as an array of structured content parts.
- * Concatenating that with `cumulativeText += delta` would stringify each
- * part as `[object Object]` — this function is the guard against that.
+ * some providers now emit an array of structured content parts; concatenating
+ * those directly would stringify each as `[object Object]`. This guards that.
  *
  * Handled part shapes:
  *   { type: "text" | "output_text", text | content: "..." }   → text body
  *   { type: "thinking" | "reasoning", thinking | text: "..." } → wrapped as
- *       inline `<think>...</think>` so the downstream parser
- *       (`parseAssistantContent`) lifts it into a reasoning part the same way
- *       it does for providers that emit thinking inline. Without this wrap,
- *       Mistral magistral and similar reasoning-part providers would lose
- *       their thinking panel.
+ *       inline `<think>...</think>` so `parseAssistantContent` lifts it into
+ *       a reasoning part (else Mistral magistral and similar reasoning-part
+ *       providers lose their thinking panel).
  *
- * Unknown part types are skipped — better to drop a stray field than to
- * stringify an object and pollute the rendered chat with `[object Object]`.
+ * Unknown part types are skipped — better to drop a stray field than
+ * stringify an object into the rendered chat.
  */
 function extractDeltaText(delta: unknown): string {
   const extractReasoningText = (payload: unknown): string => {
@@ -564,8 +555,8 @@ function toOpenAIImageEditReferenceMessage(
 
 // Refusal flag stamped on assistant metadata when the backend emits the
 // `anthropic_refusal` _toolEvent. We drop the refused pair from the next
-// request body (Anthropic guidance: leaving refusals in context keeps
-// refusing). Metadata (not text) prevents content from spoofing a reset.
+// request body (Anthropic: leaving refusals in context keeps refusing).
+// Using metadata, not text, prevents content from spoofing a reset.
 function isAnthropicRefusalMessage(message: RunMessage): boolean {
   if (message.role !== "assistant") return false;
   const metadata = (message as { metadata?: unknown }).metadata as
@@ -618,8 +609,8 @@ function collectAssistantToolCalls(
       hasNativePart,
     );
     if (isServerSideBuiltin) {
-      // Gemini code_execution / image_generation still need to round-
-      // trip the native_part payload for native replay; drop the rest.
+      // Gemini code_execution / image_generation must round-trip the
+      // native_part payload for native replay; drop the rest.
       if (!hasNativePart) continue;
     }
     const argumentsStr =
@@ -640,8 +631,8 @@ function collectAssistantToolCalls(
       },
     };
     // Promote args.google to extra_content.google so the backend
-    // native_part replay branch can find it. The backend only inspects
-    // extra_content, not function.arguments.
+    // native_part replay branch finds it (it only inspects
+    // extra_content, not function.arguments).
     if (tc.extra_content !== undefined) {
       entry.extra_content = tc.extra_content;
     } else if (argsGoogle) {
@@ -670,7 +661,7 @@ function collectToolResultMessages(
     if (part.type !== "tool-call") continue;
     const tc = part as ToolCallMessagePart;
     const result = (tc as { result?: unknown }).result;
-    // Skip provider-side builtins; see isServerSideBuiltinToolPart.
+    // Skip provider-side builtins; see isServerSideBuiltinToolPart().
     const argsObj =
       tc.args && typeof tc.args === "object"
         ? (tc.args as Record<string, unknown>)
@@ -702,8 +693,8 @@ function collectToolResultMessages(
     let content: string;
     if (typeof result === "string") {
       // Backend ChatMessage validator rejects role="tool" with empty
-      // content; serialise a sentinel JSON so legitimately empty tool
-      // outputs still round-trip the follow-up turn to the provider.
+      // content; serialise sentinel JSON so legitimately empty tool
+      // outputs still round-trip to the provider.
       content = result.length > 0 ? result : JSON.stringify({ result: "" });
     } else {
       try {
@@ -774,8 +765,8 @@ function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
       "[audio]",
     );
     if (isAnthropicRefusalMessage(message)) {
-      // Prune refused assistant turn from outbound history; the
-      // rendered transcript still shows the user-visible notice.
+      // Prune refused assistant turn from outbound history; the rendered
+      // transcript still shows the user-visible notice.
       return [];
     }
   }
@@ -795,9 +786,9 @@ function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
   };
   if (toolCalls.length > 0) {
     base.tool_calls = toolCalls;
-    // OpenAI requires content === null on assistant turns whose
-    // payload is entirely tool_calls (matches the wire shape Gemini
-    // expects for the next functionCall replay).
+    // OpenAI requires content === null on assistant turns that are
+    // entirely tool_calls (matches the wire shape Gemini expects for
+    // the next functionCall replay).
     if (!textContent && imageParts.length === 0) {
       base.content = null;
     }
@@ -830,7 +821,7 @@ function findLatestUserImageBase64(messages: RunMessages): string | undefined {
       continue;
     }
 
-    // Image in message.content (e.g. compare view appends content with image parts)
+    // Image in message.content (e.g. compare view).
     for (const part of message.content ?? []) {
       if (part.type === "image" && "image" in part) {
         const encoded = extractImageBase64(part.image);
@@ -838,7 +829,7 @@ function findLatestUserImageBase64(messages: RunMessages): string | undefined {
       }
     }
 
-    // Image in message.attachments (e.g. chat composer)
+    // Image in message.attachments (e.g. chat composer).
     if ("attachments" in message && (message.attachments?.length ?? 0) > 0) {
       for (const attachment of message.attachments ?? []) {
         for (const part of attachment.content ?? []) {
@@ -858,7 +849,7 @@ function findLatestUserImageBase64(messages: RunMessages): string | undefined {
 }
 
 function findLatestUserAudioBase64(messages: RunMessages): string | undefined {
-  // Check message content parts (from compare view's CompareMessagePart with type: "audio")
+  // Message content parts (compare view CompareMessagePart type: "audio").
   for (let i = messages.length - 1; i >= 0; i -= 1) {
     const message = messages[i];
     if (!message || message.role !== "user") continue;
@@ -877,7 +868,7 @@ function findLatestUserAudioBase64(messages: RunMessages): string | undefined {
     }
   }
 
-  // Check the runtime store (from main composer's audio upload)
+  // Runtime store (main composer's audio upload).
   const pendingAudio = useChatRuntimeStore.getState().pendingAudioBase64;
   return pendingAudio ?? undefined;
 }
@@ -893,8 +884,8 @@ async function resolveUseAdapter(
     if (!thread?.pairId) {
       return undefined;
     }
-    // model1/model2 threads don't use the adapter toggle — each side
-    // loads its own model via /api/inference/load before generation.
+    // model1/model2 threads skip the adapter toggle — each side loads
+    // its own model via /api/inference/load before generation.
     if (thread.modelType === "model1" || thread.modelType === "model2") {
       return undefined;
     }
@@ -962,9 +953,9 @@ function waitForModelReady(abortSignal?: AbortSignal): Promise<void> {
 }
 
 /**
- * Auto-load the smallest downloaded model when the user tries to chat
- * without selecting one. Prefers GGUF (picks smallest cached variant),
- * falls back to smallest cached safetensors model.
+ * Auto-load the smallest downloaded model when the user chats without
+ * selecting one. Prefers GGUF (smallest cached variant), then smallest
+ * cached safetensors model.
  */
 // Cap cascade so broken cached repos can't spam /api/inference/load.
 const MAX_AUTO_LOAD_ATTEMPTS = 3;
@@ -1009,8 +1000,7 @@ async function autoLoadSmallestModel(): Promise<{
       listCachedModels().catch(() => []),
     ]);
 
-    // Try GGUF first: pick the repo with the smallest total size,
-    // then pick its smallest downloaded variant.
+    // GGUF first: smallest-total-size repo, then its smallest variant.
     if (ggufRepos.length > 0) {
       const sorted = [...ggufRepos].sort((a, b) => a.size_bytes - b.size_bytes);
       for (const repo of sorted) {
@@ -1053,7 +1043,7 @@ async function autoLoadSmallestModel(): Promise<{
               ...store.params,
               maxTokens: loadResp.context_length ?? 131072,
             });
-            // Add model to store so the selector shows the name
+            // Add to store so the selector shows the name.
             const autoModel: ChatModelSummary = {
               id: repo.repo_id,
               name: loadResp.display_name ?? repo.repo_id,
@@ -1101,7 +1091,7 @@ async function autoLoadSmallestModel(): Promise<{
       }
     }
 
-    // Fall back to safetensors models
+    // Fall back to safetensors models.
     if (modelRepos.length > 0) {
       const sorted = [...modelRepos].sort(
         (a, b) => a.size_bytes - b.size_bytes,
@@ -1171,7 +1161,7 @@ async function autoLoadSmallestModel(): Promise<{
       }
     }
 
-    // Cap also gates the default download so the total /api/inference/load
+    // Cap also gates the default download, so total /api/inference/load
     // budget across cached + fallback is MAX_AUTO_LOAD_ATTEMPTS, not +1.
     if (loadAttempts >= MAX_AUTO_LOAD_ATTEMPTS) {
       toast.dismiss(toastId);
@@ -1182,7 +1172,7 @@ async function autoLoadSmallestModel(): Promise<{
       };
     }
 
-    // No cached models found — try downloading a small default GGUF
+    // No cached models — try downloading a small default GGUF.
     toast("Downloading a small model…", {
       id: toastId,
       description:
@@ -1275,8 +1265,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
     async *run({ messages, abortSignal, unstable_threadId }) {
       await useChatRuntimeStore.getState().hydratePersistedSettings();
       let runtime = useChatRuntimeStore.getState();
-      // Capture the thread ID once at the start so it stays stable even if
-      // the user switches chats while waiting for model load / auto-load.
+      // Capture the thread ID once so it stays stable even if the user
+      // switches chats while waiting for model load / auto-load.
       const resolvedThreadId =
         (unstable_threadId ?? runtime.activeThreadId) || undefined;
       const sandboxSessionId = await resolveSandboxSessionId(resolvedThreadId);
@@ -1305,7 +1295,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         }
       };
 
-      // Wait for in-progress model load to finish before inferring
+      // Wait for in-progress model load before inferring.
       if (runtime.modelLoading) {
         toast.info("Waiting for model to finish loading…");
         try {
@@ -1317,7 +1307,6 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       }
 
       if (!useChatRuntimeStore.getState().params.checkpoint) {
-        // Auto-load the smallest downloaded model
         let loaded: boolean;
         let blockedByTrustRemoteCode: boolean;
         try {
@@ -1342,7 +1331,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         }
       }
 
-      // Re-read store after potential auto-load / model ready wait
+      // Re-read store after auto-load / model-ready wait.
       runtime = useChatRuntimeStore.getState();
       const { params } = runtime;
       const {
@@ -1405,8 +1394,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         throw new Error("Missing connection API key.");
       }
 
-      // Image-generation flag (OpenAI cloud + Responses-capable model).
-      // Computed first so Gemini image mode can suppress Search/Code.
+      // Image-generation flag (OpenAI cloud + Responses-capable model);
+      // computed first so Gemini image mode can suppress Search/Code.
       const imageGenerationEnabledForThisTurn = Boolean(
         externalProvider &&
           externalSelection &&
@@ -1444,9 +1433,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
           ),
       );
       // Fetch pill is independent of Search (Anthropic bills web_fetch
-      // separately from web_search). Sourced from `webFetchToolsEnabled`;
-      // on providers without web_fetch the toggle is forced off in
-      // chat-page's runtime setState.
+      // separately). Sourced from `webFetchToolsEnabled`; on providers
+      // without web_fetch the toggle is forced off in chat-page setState.
       const webFetchEnabledForThisTurn = Boolean(
         externalProvider &&
           webFetchToolsEnabled &&
@@ -1482,7 +1470,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
 
       // toOpenAIMessages emits assistant tool_calls + role="tool"
       // follow-ups; the backend Gemini translator rebuilds the
-      // functionCall/functionResponse parts (with thoughtSignature).
+      // functionCall / functionResponse parts (with thoughtSignature).
       const outboundMessages = survivingMessages
         .flatMap(toOpenAIMessages)
         .filter((message): message is NonNullable<typeof message> =>
@@ -1508,9 +1496,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
           }
         }
         // OpenAIChatMessage is a structural superset of SerializedMessage
-        // for the role/content axis the outbound pipeline consumes; cast
-        // through unknown since referenceMessage carries no tool_calls
-        // (the image_edit reference is a plain assistant turn).
+        // on the role/content axis; cast through unknown since
+        // referenceMessage carries no tool_calls (plain assistant turn).
         outboundMessages.splice(
           insertAt,
           0,
@@ -1545,10 +1532,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         const webLabel = providerShipsWebFetch
           ? "web search or web fetch"
           : "web search";
-        // Treat search and fetch as a single "any web tool" axis so
-        // the guard only warns when neither pill is on; checking
-        // webSearchEnabledForThisTurn alone mis-fired when only Fetch
-        // was on and suppressed live web_fetch calls.
+        // Treat search and fetch as one "any web tool" axis so the guard
+        // only warns when neither pill is on; checking webSearch alone
+        // mis-fired when only Fetch was on and suppressed web_fetch.
         const anyWebEnabledForThisTurn =
           webSearchEnabledForThisTurn || webFetchEnabledForThisTurn;
         if (
@@ -1625,15 +1611,14 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       }
 
       // Scan post-prune history so a refused user turn's image/audio
-      // doesn't gate or mis-attribute the next non-refused turn.
+      // doesn't gate or mis-attribute the next turn.
       const imageBase64 = findLatestUserImageBase64(survivingMessages);
       const audioBase64 = findLatestUserAudioBase64(survivingMessages);
       const hasOutboundImage = Boolean(imageBase64);
 
       // Keep render_html local-only and mirror the backend image-turn gate.
-      // Artifacts are independent of Search/Code: if a local tool-capable
-      // model has Artifacts enabled, expose render_html even when no other
-      // tool pills are active.
+      // Artifacts are independent of Search/Code: a local tool-capable model
+      // with Artifacts on exposes render_html even with no other pills active.
       const renderHtmlToolEnabledForThisTurn = Boolean(
         !isExternalRequest &&
           supportsTools &&
@@ -1652,10 +1637,10 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       addSystemInstruction(outboundMessages, effectiveDisabledToolGuard);
       addSystemInstruction(outboundMessages, artifactInstruction);
 
-      // Block when ANY image is in the outbound payload (current or
-      // prior turns) and the loaded model can't process images. Keeps
-      // the gate simple: once a chat contains an image, a non-vision
-      // model can't respond — user starts a new chat to switch models.
+      // Block when ANY image is in the outbound payload (current or prior
+      // turns) and the loaded model can't process images. Once a chat
+      // contains an image, a non-vision model can't respond — the user
+      // starts a new chat to switch models.
       if (imageBase64) {
         const activeModel = runtime.models.find(
           (m) => m.id === params.checkpoint,
@@ -1672,10 +1657,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         });
         if (imageGateReason) {
           toast.error(imageGateReason);
-          // Flip the per-thread running flag on→off so the compare-mode
-          // waitForRunEnd resolves instead of hanging. This gate fires
-          // before the streaming path's setThreadRunning(true), so the
-          // wait promise would otherwise never settle.
+          // Flip the per-thread running flag on→off so compare-mode
+          // waitForRunEnd resolves instead of hanging: this gate fires
+          // before the streaming path's setThreadRunning(true).
           const gatedThreadKey = resolvedThreadId || "__default";
           runtime.setThreadRunning(gatedThreadKey, true);
           runtime.setThreadRunning(gatedThreadKey, false);
@@ -1683,7 +1667,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
           throw new Error(imageGateReason);
         }
       }
-      // Clear pending audio from store after extracting (consumed on send)
+      // Clear pending audio from store after extracting (consumed on send).
       if (audioBase64) {
         const audioName = runtime.pendingAudioName;
         if (audioName) {
@@ -1785,8 +1769,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       let reasoningStartAt: number | null = null;
       let reasoningDuration = 0;
       // True while wrapping a `delta.reasoning_content` stream in
-      // <think>...</think> for parseAssistantContent. Lives outside
-      // the SSE loop because the close tag fires when content arrives.
+      // <think>...</think> for parseAssistantContent. Lives outside the
+      // SSE loop because the close tag fires when content arrives.
       let reasoningContentOpen = false;
       // Tool call parts, cumulative; result lands on tool_end.
       const toolCallParts: ToolCallMessagePart[] = [];
@@ -1819,9 +1803,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         );
         return [...otherToolParts, ...textParts, ...imageToolParts];
       };
-      // Anthropic document_citations tool_event payload, converted to
-      // Sources-panel source parts at end-of-stream so the inline [N]
-      // markers have matching entries.
+      // Anthropic document_citations payload, converted to Sources-panel
+      // parts at end-of-stream so inline [N] markers have matching entries.
       const documentCitationParts: Array<{
         type: "source";
         sourceType: "url";
@@ -1830,16 +1813,16 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         title: string;
         metadata?: { description: string };
       }> = [];
-      // Latched on the `anthropic_refusal` tool event; stamped onto the
-      // final assistant metadata as `custom.anthropicRefusal` to drive
-      // the history-prune above.
+      // Latched on the `anthropic_refusal` tool event; stamped onto final
+      // assistant metadata as `custom.anthropicRefusal` to drive the
+      // history-prune above.
       let anthropicRefusalSeen = false;
       let serverMetadata: {
         usage?: ServerUsage;
         timings?: ServerTimings;
       } | null = null;
 
-      // Per-run cancellation token so a delayed stop POST cannot match
+      // Per-run cancellation token so a delayed stop POST can't match
       // the next run on the same thread.
       const cancelId =
         typeof crypto !== "undefined" && "randomUUID" in crypto
@@ -1854,10 +1837,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         // Plain fetch, not authFetch: authFetch redirects to login on
         // 401, which would kick the user out mid-stop.
         const token = getAuthToken();
-        // Use apiUrl so the cancel POST reaches the right origin in
-        // Tauri production builds (where the webview origin is not the
-        // backend at 127.0.0.1:<port>). Browser/dev builds get the empty
-        // base, so the path is unchanged there.
+        // Use apiUrl so the cancel POST reaches the right origin in Tauri
+        // production builds (webview origin != backend at 127.0.0.1:<port>).
+        // Browser/dev builds get the empty base, so the path is unchanged.
         void fetch(apiUrl("/api/inference/cancel"), {
           method: "POST",
           headers: {
@@ -1948,8 +1930,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 anthropicCodeExecContainerId = null;
               }
               // Pre-send container validation (OpenAI). Stale ids drop
-              // silently and fall through to lazy-create. On list-call
-              // failure, skip and rely on the backend's retry path.
+              // silently and fall through to lazy-create; on list-call
+              // failure, rely on the backend's retry path.
               let activeContainerIds: Set<string> | null = null;
               if (externalProvider.providerType === "openai") {
                 try {
@@ -1972,8 +1954,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   openaiCodeExecContainerId = null;
                 }
               }
-              // Cross-thread inheritance: reuse the most recently used
-              // container from any other thread; opt-out via the picker.
+              // Cross-thread inheritance: reuse the most recent container
+              // from any other thread; opt-out via the picker.
               if (
                 !openaiCodeExecContainerId &&
                 externalProvider.providerType === "openai"
@@ -1985,7 +1967,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   for (const t of others) {
                     if (t.id === resolvedThreadId) continue;
                     if (!t.openaiCodeExecContainerId) continue;
-                    // Skip ids not in active set; null on source thread so
+                    // Skip ids not in active set; null the source thread so
                     // the next pass doesn't re-pick a dead id.
                     if (
                       activeContainerIds &&
@@ -2006,9 +1988,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   /* fall through to lazy-create below */
                 }
               }
-              // Pre-create our own container (vs container_auto) so it
-              // shows up in the picker with a friendly name and the
-              // configured TTL. Falls back to container_auto on failure.
+              // Pre-create our own container (vs container_auto) so it shows
+              // in the picker with a friendly name and the configured TTL.
+              // Falls back to container_auto on failure.
               if (
                 !openaiCodeExecContainerId &&
                 externalProvider.providerType === "openai"
@@ -2022,10 +2004,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       baseUrl: externalProvider.baseUrl || null,
                     },
                     {
-                      // Friendly English-word name so the container
-                      // is human-readable in the picker list (e.g.
-                      // "kestrel-3f9c") instead of a thread-id slug
-                      // or OpenAI's default blank name.
+                      // Friendly English-word name so the container is
+                      // human-readable in the picker (e.g. "kestrel-3f9c")
+                      // instead of a thread-id slug or blank default.
                       name: pickFriendlyContainerName(),
                       ttlMinutes: ttlToUse,
                     },
@@ -2035,10 +2016,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     openaiCodeExecContainerId: created.id,
                   }).catch(() => {});
                 } catch {
-                  // Fall back to backend's container_auto path on
-                  // failure — keeps the chat moving; the next turn
-                  // can retry. The auto-created container will be
-                  // unnamed, but the chat doesn't break.
+                  // Fall back to the backend's container_auto path on
+                  // failure — keeps the chat moving (the auto-created
+                  // container is unnamed); the next turn can retry.
                   openaiCodeExecContainerId = null;
                 }
               }
@@ -2047,8 +2027,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               model: externalSelection.modelId,
               messages: outboundMessages,
               stream: true,
-              // Reasoning-class models (OpenAI gpt-5.x / o3) reject temperature
-              // and top_p; only forward when the active provider supports them.
+              // Reasoning-class models (OpenAI gpt-5.x / o3) reject
+              // temperature and top_p; forward only when supported.
               ...(externalCapabilities?.temperature !== false
                 ? { temperature: params.temperature }
                 : {}),
@@ -2072,8 +2052,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               ...(externalCapabilities?.presencePenalty
                 ? { presence_penalty: params.presencePenalty }
                 : {}),
-              // Compose the enabled_tools list from the active pills;
-              // backend maps each name to the provider's tool schema.
+              // enabled_tools from active pills; backend maps each name
+              // to the provider's tool schema.
               ...(webSearchEnabledForThisTurn ||
               webFetchEnabledForThisTurn ||
               codeExecEnabledForThisTurn ||
@@ -2128,8 +2108,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 ? { prompt_cache_ttl: externalProvider.promptCacheTtl }
                 : {}),
               // Anthropic fast mode (Opus 4.6 / 4.7 only); backend
-              // silently drops on unsupported models as a second
-              // line of defence.
+              // silently drops on unsupported models as a backstop.
               ...(params.fastMode &&
               providerSupportsFastMode(
                 externalProvider.providerType,
@@ -2230,8 +2209,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               }
 
               // Emit tool-call content parts for assistant-ui.
-              // On tool_start: add a new tool-call part (renders in "running" state).
-              // On tool_end: set result on the existing part (transitions to "complete").
+              // tool_start: add a part (renders "running").
+              // tool_end: set result on the part (transitions to "complete").
               const toolEvent = (
                 chunk as unknown as { _toolEvent?: Record<string, unknown> }
               )._toolEvent;
@@ -2253,8 +2232,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   continue;
                 }
                 if (toolEvent.type === "document_citations") {
-                  // Convert Anthropic citations_delta footnotes into
-                  // Sources-panel entries matching the inline [N] markers.
+                  // Convert citations_delta footnotes into Sources-panel
+                  // entries matching the inline [N] markers.
                   const cits = toolEvent.citations;
                   if (Array.isArray(cits)) {
                     cits.forEach((entry, idx) => {
@@ -2286,8 +2265,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   continue;
                 }
                 if (toolEvent.type === "anthropic_refusal") {
-                  // Latch the backend refusal signal so the final
-                  // message metadata can drive the prune.
+                  // Latch the backend refusal signal so final message
+                  // metadata can drive the prune.
                   anthropicRefusalSeen = true;
                   continue;
                 }
@@ -2346,7 +2325,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       imageB64
                     ) {
                       // Backend keeps base64 on separate image_b64 /
-                      // image_mime fields so logs stay small; repackage.
+                      // image_mime fields so logs stay small; repackage here.
                       parsedResult = {
                         image_b64: imageB64,
                         image_mime:
@@ -2359,8 +2338,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       };
                     } else if (imgIdx !== -1) {
                       const text = rawResult.slice(0, imgIdx);
-                      // Fall back to "_default" to match the backend sandbox directory
-                      // used when no session_id is provided (see tools.py _get_workdir).
+                      // Fall back to "_default" to match the backend sandbox
+                      // dir used when no session_id (see tools.py _get_workdir).
                       const sessionId = sandboxSessionId || "_default";
                       try {
                         const images = JSON.parse(
@@ -2386,7 +2365,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     // Merge tool_end native_part into args.google so the
                     // outbound translator replays both start (executableCode)
                     // and end (result / inlineData) on the same turn.
-                    // Concatenate parts so each keeps its own thoughtSignature.
+                    // Concatenate so each part keeps its own thoughtSignature.
                     const endGoogle = (
                       toolEvent as { google?: { native_part?: unknown } }
                     ).google;
@@ -2410,9 +2389,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                         string,
                         unknown
                       >;
-                      // Extract part entries from either parts:[...] or
-                      // legacy single-object native_part. Legacy
-                      // thoughtSignature always belongs on executableCode.
+                      // Extract part entries from parts:[...] or legacy
+                      // single-object native_part. Legacy thoughtSignature
+                      // always belongs on executableCode.
                       const collectParts = (
                         native: Record<string, unknown>,
                       ): Record<string, unknown>[] => {
@@ -2466,8 +2445,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     };
                   }
                 }
-                // Cumulative yield. orderAssistantContent puts search/
-                // code before text and generated images after.
+                // Cumulative yield; orderAssistantContent puts search/code
+                // before text and generated images after.
                 const textParts = pinTextThoughtSignature(
                   parseAssistantContent(cumulativeText),
                 );
@@ -2485,7 +2464,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 continue;
               }
 
-              // OpenAI-standard usage chunk: choices=[], usage populated
+              // OpenAI-standard usage chunk: choices=[], usage populated.
               if (chunk.choices?.length === 0 && chunk.usage) {
                 serverMetadata = {
                   usage: chunk.usage,
@@ -2497,8 +2476,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
               }
 
               totalChunks += 1;
-              // Latch the chunk's `model` field so the openrouter/free
-              // chip can show the chosen underlying model.
+              // Latch the chunk's `model` field so the openrouter/free chip
+              // shows the chosen underlying model.
               if (
                 isExternalRequest &&
                 externalProvider?.providerType === "openrouter" &&
@@ -2517,7 +2496,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 }
               }
               const rawDelta = chunk.choices?.[0]?.delta?.content;
-              // Normalize structured delta.content (mistral magistral) to text.
+              // Normalize structured delta.content (mistral magistral).
               const delta = extractDeltaText(rawDelta);
               // Latest Gemini text-part thoughtSignature for next-turn replay.
               const deltaExtraContent = (
@@ -2539,15 +2518,15 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   }
                 }
               }
-              // Kimi / DeepSeek stream thinking via delta.reasoning_content.
-              // Wrap inline as <think>...</think> for parseAssistantContent.
+              // Kimi / DeepSeek stream thinking via delta.reasoning_content;
+              // wrap inline as <think>...</think> for parseAssistantContent.
               const rawReasoning = (
                 chunk.choices?.[0]?.delta as
                   | { reasoning_content?: unknown }
                   | undefined
               )?.reasoning_content;
               // OpenRouter ships reasoning as delta.reasoning_details[]
-              // regardless of underlying provider; merge into the same wrap path.
+              // regardless of provider; merge into the same wrap path.
               const rawReasoningDetails = (
                 chunk.choices?.[0]?.delta as
                   | { reasoning_details?: unknown }
@@ -2567,7 +2546,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 reasoningFromDetails;
               // OpenAI delta.tool_calls: streams fragments by index;
               // accumulate into one part. extra_content carries Gemini 3
-              // thoughtSignature for next-turn replay.
+              // thoughtSignature for replay.
               const rawDeltaToolCalls = (
                 chunk.choices?.[0]?.delta as
                   | { tool_calls?: unknown }
@@ -2588,9 +2567,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   const idx =
                     typeof call.index === "number" ? call.index : undefined;
                   const stableId = call.id;
-                  // Match an existing fragment by id first (canonical),
-                  // then by index slot. Fall back to a freshly-minted
-                  // tool_call_<n> id for streams that send neither.
+                  // Match an existing fragment by id first (canonical), then
+                  // by index slot; fall back to a minted tool_call_<n> id
+                  // for streams that send neither.
                   let existing = stableId
                     ? toolCallParts.find((p) => p.toolCallId === stableId)
                     : undefined;
@@ -2777,9 +2756,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             throw streamError;
           }
         }
-        // If the stream ended while we were still inside a
-        // delta.reasoning_content block (Kimi / DeepSeek path), close
-        // the open <think> tag so the reasoning panel parses cleanly.
+        // If the stream ended inside a delta.reasoning_content block
+        // (Kimi / DeepSeek), close the open <think> tag so the reasoning
+        // panel parses cleanly.
         if (reasoningContentOpen) {
           cumulativeText += "</think>";
           reasoningContentOpen = false;
@@ -2787,9 +2766,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         settleFirstTokenOk();
 
         // Extract source parts from completed web_search and web_fetch
-        // tool calls. Both emit the same `Title:` / `URL:` / `Snippet:`
-        // block shape from the Anthropic backend, so the parser does
-        // not need to branch on tool name.
+        // calls. Both emit the same `Title:` / `URL:` / `Snippet:` block
+        // shape, so the parser need not branch on tool name.
         const sourceParts = toolCallParts.flatMap((tc) => {
           if (
             (tc.toolName !== "web_search" && tc.toolName !== "web_fetch") ||
@@ -2818,8 +2796,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         const cacheWriteTokens = meta?.usage?.cache_creation_input_tokens ?? 0;
 
         // Gate on the captured checkpoint still being active so a late
-        // completion from provider A doesn't populate the bar after the
-        // user switched to provider B mid-stream.
+        // completion from provider A doesn't populate the bar after a
+        // mid-stream switch to provider B.
         if (
           meta?.usage &&
           typeof meta.usage.prompt_tokens === "number" &&
@@ -2882,10 +2860,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         if (!abortSignal.aborted) {
           const msg = err instanceof Error ? err.message : String(err);
           if (isContextLimitError(msg)) {
-            // llama-server was launched with --no-context-shift, so it
-            // returns a hard error instead of silently dropping old
-            // turns from the KV cache. Point the user at the exact
-            // control that raises the ceiling.
+            // llama-server runs with --no-context-shift, returning a hard
+            // error instead of silently dropping old KV-cache turns. Point
+            // the user at the control that raises the ceiling.
             toast.error("Context limit reached", {
               description:
                 "The conversation has filled the model's context window. " +
diff --git a/studio/frontend/src/features/chat/api/chat-api.ts b/studio/frontend/src/features/chat/api/chat-api.ts
index 7a71850d66..9d0939c37d 100644
--- a/studio/frontend/src/features/chat/api/chat-api.ts
+++ b/studio/frontend/src/features/chat/api/chat-api.ts
@@ -141,9 +141,8 @@ export interface DownloadProgressResponse {
   expected_bytes: number;
   progress: number;
   /**
-   * Resolved on-disk path of the snapshot dir (or cache repo root if no
-   * snapshot exists yet). Null when nothing has been written to the
-   * cache for this repo.
+   * On-disk path of the snapshot dir (or cache repo root if no snapshot yet).
+   * Null when nothing has been written to the cache for this repo.
    */
   cache_path: string | null;
 }
@@ -168,9 +167,8 @@ export type ModelLoadPhase = "mmap" | "ready" | null;
 
 export interface LoadProgressResponse {
   /**
-   * Load phase: ``"mmap"`` while the llama-server subprocess is paging
-   * weight shards into RAM, ``"ready"`` once it has reported healthy,
-   * or ``null`` when no load is in flight.
+   * Load phase: "mmap" while llama-server pages weight shards into RAM,
+   * "ready" once healthy, or null when no load is in flight.
    */
   phase: ModelLoadPhase;
   bytes_loaded: number;
@@ -179,10 +177,9 @@ export interface LoadProgressResponse {
 }
 
 /**
- * Fetch the active GGUF load's mmap/upload progress. Complements
- * ``getDownloadProgress`` / ``getGgufDownloadProgress`` for the window
- * between "download complete" and "chat ready", which for large MoE
- * models can be several minutes of otherwise-opaque spinning.
+ * Fetch the active GGUF load's mmap/upload progress. Complements the download
+ * progress endpoints for the "download complete" -> "chat ready" window, which
+ * for large MoE models can be several minutes of otherwise-opaque spinning.
  */
 export async function getLoadProgress(): Promise<LoadProgressResponse> {
   const response = await authFetch(`/api/inference/load-progress`);
@@ -551,16 +548,14 @@ export async function buildBackendChatExport(): Promise<{
   return parseJsonOrThrow(response);
 }
 
-// Legacy-Dexie import ledger. The server-side source of truth that
-// replaces the boolean localStorage sentinel
-// (`unsloth_chat_legacy_imported_to_studio_db`) so a studio.db wipe
-// makes the import recoverable.
+// Legacy-Dexie import ledger: server-side source of truth replacing the
+// boolean localStorage sentinel, so a studio.db wipe keeps the import
+// recoverable.
 export async function listChatImportLedger(): Promise<Set<string>> {
   const response = await authFetch("/api/chat/import-ledger");
-  // Backend deployments that don't have this endpoint yet behave the
-  // same as an empty ledger -- caller treats every legacy thread as
-  // un-imported and tries to import. The UPSERT semantics in
-  // syncChatMessages prevent duplicates, so this fallback is safe.
+  // Backends without this endpoint behave like an empty ledger -- caller
+  // re-imports every legacy thread. syncChatMessages UPSERTs prevent
+  // duplicates, so this fallback is safe.
   if (response.status === 404 || response.status === 405) return new Set();
   const data = await parseJsonOrThrow<{ threadIds: string[] }>(response);
   return new Set(data.threadIds);
@@ -569,9 +564,9 @@ export async function listChatImportLedger(): Promise<Set<string>> {
 export interface RecordChatImportLedgerResult {
   accepted: number;
   inserted: number;
-  // false when the backend predates /api/chat/import-ledger (404/405/501)
-  // so the caller can avoid poisoning the localStorage perf hint -- the
-  // next launch will retry the (idempotent) import.
+  // false when the backend predates /api/chat/import-ledger (404/405/501) so
+  // the caller avoids poisoning the localStorage perf hint; next launch
+  // retries the (idempotent) import.
   supported: boolean;
 }
 
@@ -633,11 +628,10 @@ export async function browseFolders(
   if (path !== undefined && path !== null) params.set("path", path);
   if (showHidden) params.set("show_hidden", "true");
   const qs = params.toString();
-  // Forward the AbortSignal through authFetch -> fetch so that a
-  // navigation cancelled in the FolderBrowser (rapid breadcrumb / row /
-  // hidden-toggle clicks) actually cancels the in-flight HTTP request
-  // server-side, instead of merely dropping the response client-side
-  // while the backend keeps walking large directory trees.
+  // Forward the AbortSignal through authFetch -> fetch so a cancelled
+  // FolderBrowser navigation actually cancels the in-flight request
+  // server-side, instead of just dropping the response while the backend
+  // keeps walking large directory trees.
   const response = await authFetch(
     `/api/models/browse-folders${qs ? `?${qs}` : ""}`,
     signal ? { signal } : undefined,
diff --git a/studio/frontend/src/features/chat/api/openai-containers.ts b/studio/frontend/src/features/chat/api/openai-containers.ts
index 6463b5dc7b..f95b5a6349 100644
--- a/studio/frontend/src/features/chat/api/openai-containers.ts
+++ b/studio/frontend/src/features/chat/api/openai-containers.ts
@@ -2,11 +2,10 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Wrappers for the three OpenAI shell-tool container management
- * endpoints exposed by the backend (studio/backend/routes/inference.py).
- * Each one proxies to OpenAI's /v1/containers REST surface using the
- * user's encrypted API key. Backend rejects any base URL that isn't
- * api.openai.com — the shell tool only exists on the managed cloud.
+ * Wrappers for the backend's three OpenAI shell-tool container endpoints
+ * (studio/backend/routes/inference.py). Each proxies to OpenAI's
+ * /v1/containers using the user's encrypted API key. Backend rejects any
+ * base URL but api.openai.com (the shell tool is managed-cloud only).
  */
 
 import { authFetch } from "@/features/auth";
@@ -110,9 +109,8 @@ export async function deleteOpenAIContainer(
       }),
     },
   );
-  // 404 = container already gone (deleted elsewhere, or expired-then-purged).
-  // Treat as idempotent success so a stale list entry doesn't surface as a
-  // confusing error — the caller will refresh and the entry will disappear.
+  // 404 = container already gone; treat as idempotent success so a stale
+  // list entry doesn't surface as a confusing error.
   if (!response.ok && response.status !== 204 && response.status !== 404) {
     throw new Error(await parseError(response));
   }
diff --git a/studio/frontend/src/features/chat/api/providers-api.ts b/studio/frontend/src/features/chat/api/providers-api.ts
index 9625c4c217..d52e5e855e 100644
--- a/studio/frontend/src/features/chat/api/providers-api.ts
+++ b/studio/frontend/src/features/chat/api/providers-api.ts
@@ -140,10 +140,9 @@ export async function deleteProviderConfig(providerId: string): Promise<void> {
   const response = await authFetch(`/api/providers/${providerId}`, {
     method: "DELETE",
   });
-  // Treat 404 as success: another browser (or tab) already deleted this
-  // provider on the backend, so locally pruning the stale cache is the
-  // correct follow-up. Without this, the caller would throw and the user
-  // would be stuck with an entry they cannot remove from the UI.
+  // Treat 404 as success: another tab already deleted this provider, so pruning
+  // the stale cache is correct. Otherwise the caller throws and the user is stuck
+  // with an entry they cannot remove from the UI.
   if (response.status === 404) {
     return;
   }
diff --git a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
index b4ddf38aaa..a685515253 100644
--- a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
+++ b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
@@ -46,10 +46,9 @@ function buildHtmlFence(source: string): string {
   const fence = "`".repeat(longestBacktickRun + 1);
   return `${fence}html\n${source}\n${fence}`;
 }
-// Sandboxed artifact iframes are intentionally excluded from the overlay focus
-// trap. Granting same-origin sandbox privileges would weaken isolation, so
-// keyboard users can reach Studio controls here while fully interactive artifact
-// content remains a known sandbox limitation.
+// Sandboxed artifact iframes are deliberately outside the overlay focus trap:
+// granting same-origin sandbox privileges would weaken isolation, so reaching
+// interactive artifact content via keyboard is a known sandbox limitation.
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
diff --git a/studio/frontend/src/features/chat/artifacts/html-frame.tsx b/studio/frontend/src/features/chat/artifacts/html-frame.tsx
index dc8c14c0ed..041dc4dc56 100644
--- a/studio/frontend/src/features/chat/artifacts/html-frame.tsx
+++ b/studio/frontend/src/features/chat/artifacts/html-frame.tsx
@@ -60,9 +60,8 @@ export function ArtifactHtmlFrame({
     return apiUrl(`/api/inference/artifact-preview-frame?${query.toString()}`);
   }, [allowNetworkAccess, code]);
   const postArtifactHtml = useCallback(() => {
-    // The sandboxed frame intentionally has an opaque origin ("null").
-    // A wildcard target is required here;
-    // the payload is sent only to this iframe's contentWindow.
+    // Sandboxed frame has an opaque origin ("null"), so a wildcard target is
+    // required; the payload only reaches this iframe's contentWindow.
     iframeRef.current?.contentWindow?.postMessage(
       { type: "unsloth:artifact-html", html: artifactHtml },
       "*",
diff --git a/studio/frontend/src/features/chat/artifacts/types.ts b/studio/frontend/src/features/chat/artifacts/types.ts
index 86d42fd733..5ce22cc68a 100644
--- a/studio/frontend/src/features/chat/artifacts/types.ts
+++ b/studio/frontend/src/features/chat/artifacts/types.ts
@@ -44,8 +44,8 @@ export function hashArtifactCode(code: string): string {
 export function createArtifactId(input: ChatArtifactInput): string {
   const threadSegment = input.threadId || "no-thread";
   const messageSegment = input.sourceMessageId || "transient";
-  // Backend tool call IDs (call_0, call_1, …) reset per request, so
-  // the message ID is needed to scope them to a specific turn.
+  // Backend tool call IDs (call_0, call_1, …) reset per request, so the
+  // message ID is needed to scope them to a specific turn.
   const parts = [input.source, threadSegment, messageSegment];
 
   if (input.source === "tool" && input.sourceToolCallId) {
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index c706d971ac..f78784b436 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -84,10 +84,9 @@ function isValidAddress(value: string): boolean {
       return false;
     }
   }
-  // Anything else is treated as a local command (stdio); the backend gates
-  // whether stdio servers are allowed on this host. Reject other URL schemes
-  // only when the command itself is a URL; "://" is fine inside an argument
-  // (e.g. a database connection string passed to the server).
+  // Otherwise it's a local command (stdio); the backend gates whether those
+  // are allowed. Reject only when the command itself is a URL; "://" is fine
+  // inside an argument (e.g. a DB connection string passed to the server).
   return !trimmed.split(/\s+/)[0].includes("://");
 }
 
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 834d0baf34..50650416a4 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -367,9 +367,8 @@ function modelMatchesDeleted(
 }
 
 /**
- * Detect if this is a LoRA base-vs-fine-tuned compare.
- * Returns true when the loaded checkpoint is a LoRA — in that case
- * we use the fast simultaneous base/lora adapter-toggle path.
+ * True when the loaded checkpoint is a LoRA, meaning a base-vs-fine-tuned
+ * compare that uses the fast simultaneous adapter-toggle path.
  */
 function useIsLoraCompare(): boolean {
   return useChatRuntimeStore((s) => {
@@ -424,15 +423,12 @@ const CompareContent = memo(function CompareContent({
 });
 
 /**
- * A single column in the compare layout. Hosts one ChatRuntimeProvider
- * and one Thread rendered with hideComposer — the composer is shared
- * across both panes and rendered outside the pane flex.
+ * A single column in the compare layout: one ChatRuntimeProvider and one
+ * Thread with hideComposer (the composer is shared across panes).
  *
- * Each pane is a flex item with `flex-1 basis-0 min-h-0 min-w-0` so on
- * mobile (flex-col) they share height equally, and on desktop (flex-row)
- * they share width equally. The `min-*` constraints are required for
- * the inner viewport to scroll internally instead of spilling into the
- * page.
+ * Each pane is `flex-1 basis-0 min-h-0 min-w-0` so panes share height
+ * (mobile flex-col) or width (desktop flex-row) equally. The `min-*`
+ * constraints let the inner viewport scroll instead of spilling.
  */
 function ComparePane({
   modelType,
@@ -476,16 +472,13 @@ function ComparePane({
 }
 
 /**
- * Shared shell for both compare variants. A vertical flex column with
- * the two panes as siblings and the shared composer docked at the
- * bottom. On mobile the panes stack (flex-col); on desktop they sit
- * side by side (md:flex-row).
+ * Shared shell for both compare variants: a flex column with the two panes
+ * as siblings and the shared composer docked at the bottom. Panes stack on
+ * mobile (flex-col), sit side by side on desktop (md:flex-row).
  *
- * Flex is used rather than CSS grid for the pane container so that
- * viewport sizing stays stable across viewport-size transitions. Grid
- * rows with 1fr were triggering resize thrash in assistant-ui's
- * autoscroll hook on breakpoint crossings, leaving it stuck in a
- * scroll-to-bottom loop.
+ * Flex, not grid, for the pane container: grid rows with 1fr triggered
+ * resize thrash in assistant-ui's autoscroll on breakpoint crossings,
+ * leaving it stuck in a scroll-to-bottom loop.
  */
 function CompareShell({
   handlesRef,
@@ -594,10 +587,9 @@ const LoraCompareContent = memo(function LoraCompareContent({
 });
 
 /**
- * Per-pane header rendered inside GeneralCompareContent. Contains the
- * model selector aligned with the global topbar height. The left pane
- * reserves room for the mobile sidebar trigger; the right pane reserves
- * room for the global settings button.
+ * Per-pane header (inside GeneralCompareContent) with the model selector,
+ * aligned to the global topbar height. Left pane reserves room for the
+ * mobile sidebar trigger; right pane for the global settings button.
  */
 function GeneralCompareHeader({
   models,
@@ -1087,9 +1079,8 @@ export function ChatPage(): ReactElement {
   const [modelSelectorOpen, setModelSelectorOpen] = useState(false);
   const [modelSelectorLocked, setModelSelectorLocked] = useState(false);
   const viewBeforeCompareRef = useRef<ChatSearch | null>(null);
-  // Tracks the latest non-compare view so exiting compare can restore it even
-  // when compare was opened from a path that does not set viewBeforeCompareRef
-  // (e.g. the composer + menu).
+  // Latest non-compare view, so exiting compare can restore it even when
+  // compare was opened from a path that doesn't set viewBeforeCompareRef.
   const lastNonCompareViewRef = useRef<ChatSearch | null>(null);
   useEffect(() => {
     if (!search.compare) {
@@ -1249,15 +1240,11 @@ export function ChatPage(): ReactElement {
       preferredEffort,
       effortLevels,
     );
-    // Per-provider default effort. Anthropic gets the highest available
-    // level (xhigh on 4.6/4.7, high on 4.5) since Claude's adaptive
-    // thinking adjusts cost per turn — sitting at the top of the dial
-    // gives users the strongest answers and the model can still skip
-    // thinking when the turn is trivial. OpenAI gets "high" by default
-    // — the gpt-5.x reasoning models accept high across the board and
-    // it's the right cost/quality sweet spot for Responses-API tools
-    // (web search included). Everyone else gets "medium" as a balanced
-    // default. Users can pick another level via the Think dropdown.
+    // Per-provider default effort. Anthropic gets the highest level since
+    // Claude's adaptive thinking adjusts cost per turn (top of dial =
+    // strongest answers, still skips thinking when trivial). OpenAI gets
+    // "high" (gpt-5.x accept it across the board; good cost/quality for
+    // Responses-API tools). Everyone else "medium". Overridable via Think.
     const isAnthropic = provider?.providerType === "anthropic";
     const isOpenAI = provider?.providerType === "openai";
     const anthropicTopEffort = effortLevels.includes("xhigh")
@@ -1298,19 +1285,15 @@ export function ChatPage(): ReactElement {
     const supportsBuiltinWebFetch = providerSupportsBuiltinWebFetch(
       provider?.providerType,
     );
-    // Kimi's k2.6/k2.5 default to thinking enabled on the server side
-    // (per https://platform.kimi.ai/docs/models). Mirror that default
-    // in the UI so the Think pill comes up clicked when the user picks
-    // a Kimi model. The Search pill stays off by default; the mutual-
-    // exclusion handlers in the composer flip the two when needed.
+    // Kimi's k2.6/k2.5 default to thinking enabled server-side (per
+    // https://platform.kimi.ai/docs/models). Mirror that so the Think pill
+    // comes up clicked for Kimi models. Search stays off; the composer's
+    // mutual-exclusion handlers flip the two when needed.
     const isKimi = provider?.providerType === "kimi";
-    // Web search is on by default for the two providers we trust most
-    // for it: Anthropic (web_search_20250305 server tool, structured
-    // citations) and OpenAI (/v1/responses web_search, structured
-    // citations). Other providers stay off-by-default — OpenRouter's
-    // plugins shape and Kimi's $web_search builtin still work when the
-    // user opts in via the pill, but they're a notch less reliable so
-    // we don't pre-enable them.
+    // Web search on by default only for the two providers we trust most:
+    // Anthropic and OpenAI (both with structured citations). Others stay
+    // off-by-default; OpenRouter and Kimi work on opt-in but are less
+    // reliable, so we don't pre-enable them.
     const searchOnByDefault =
       supportsBuiltinWebSearch &&
       (provider?.providerType === "anthropic" ||
@@ -1345,15 +1328,11 @@ export function ChatPage(): ReactElement {
           : true
         : state.reasoningEnabled,
       supportsPreserveThinking: false,
-      // External models never give us a local tool runtime (no
-      // python sandbox), so `supportsTools` must be false. The three
-      // `supportsBuiltin*` flags pick up the slack for providers that
-      // run the tool server-side: `supportsBuiltinWebSearch` lights
-      // up the Search pill (OpenAI / Anthropic / OpenRouter / Kimi),
-      // `supportsBuiltinCodeExecution` lights up the Code pill
-      // (Anthropic Claude 4.x and OpenAI gpt-5.5), and
-      // `supportsBuiltinImageGeneration` lights up the Images pill
-      // (OpenAI cloud Responses-API models only).
+      // External models have no local tool runtime, so `supportsTools` is
+      // false. The `supportsBuiltin*` flags cover providers that run tools
+      // server-side: WebSearch lights the Search pill (OpenAI/Anthropic/
+      // OpenRouter/Kimi), CodeExecution the Code pill (Claude 4.x, gpt-5.5),
+      // ImageGeneration the Images pill (OpenAI cloud Responses-API only).
       supportsTools: false,
       supportsBuiltinWebSearch,
       supportsBuiltinCodeExecution,
@@ -1485,9 +1464,9 @@ export function ChatPage(): ReactElement {
   useEffect(() => {
     if (view.mode !== "single") return;
     if (view.threadId || view.newThreadNonce || !selectedArtifact) return;
-    // view intentionally excludes __LOCALID_ threads (they fall through to
-    // { mode: "single" } with no threadId/nonce).  Don't close an artifact
-    // whose thread is the currently active local thread.
+    // view excludes __LOCALID_ threads (they fall through to mode:"single"
+    // with no threadId/nonce). Don't close an artifact whose thread is the
+    // active local thread.
     if (
       selectedArtifact.threadId &&
       selectedArtifact.threadId === activeThreadId
@@ -1593,9 +1572,8 @@ export function ChatPage(): ReactElement {
           preferredEffort,
           effortLevels,
         );
-        // Same per-provider default policy as the useEffect path above:
-        // Anthropic picks the highest available level, OpenAI picks
-        // "high", everyone else picks "medium".
+        // Same per-provider default policy as the useEffect above:
+        // Anthropic highest level, OpenAI "high", everyone else "medium".
         const isAnthropic = selectedProvider?.providerType === "anthropic";
         const isOpenAI = selectedProvider?.providerType === "openai";
         const anthropicTopEffort = effortLevels.includes("xhigh")
@@ -1617,9 +1595,8 @@ export function ChatPage(): ReactElement {
                 ? "medium"
                 : clampedEffort
           : store.reasoningEffort;
-        // Clear any cached router-picked openrouter/free model unless the
-        // user is staying on openrouter/free — otherwise the chip would
-        // keep showing a stale ":<chosen>" suffix from a previous model.
+        // Clear any cached router-picked openrouter/free model unless staying
+        // on openrouter/free, else the chip keeps a stale ":<chosen>" suffix.
         const stillOnOpenRouterFree =
           selectedProvider?.providerType === "openrouter" &&
           selectedExternal?.modelId === "openrouter/free";
@@ -1644,13 +1621,12 @@ export function ChatPage(): ReactElement {
         const supportsBuiltinWebFetch = providerSupportsBuiltinWebFetch(
           selectedProvider?.providerType,
         );
-        // See sibling useEffect above: Kimi's k2.x default to thinking
-        // enabled, so the Think pill comes up clicked. Search pill stays
-        // off by default; mutual exclusion flips them via the composer.
+        // See sibling useEffect: Kimi's k2.x default to thinking enabled
+        // (Think pill clicked). Search stays off; the composer's mutual
+        // exclusion flips them.
         const isKimi = selectedProvider?.providerType === "kimi";
-        // Mirror of sibling useEffect: Anthropic and OpenAI get Search
-        // on-by-default since their server tools emit structured
-        // citations end-to-end. OpenRouter and Kimi stay off-by-default.
+        // Mirror of sibling useEffect: Anthropic/OpenAI get Search on by
+        // default (structured citations end-to-end); others stay off.
         const searchOnByDefault =
           supportsBuiltinWebSearch &&
           (selectedProvider?.providerType === "anthropic" ||
@@ -1676,9 +1652,8 @@ export function ChatPage(): ReactElement {
           ggufMaxContextLength: null,
           ggufNativeContextLength: null,
           activeNativePathToken: null,
-          // Clear previous-model counters; the relaxed external-provider
-          // render gate would otherwise show stale stats until the next
-          // completion overwrites them.
+          // Clear previous-model counters, else the relaxed external-provider
+          // render gate shows stale stats until the next completion.
           contextUsage: null,
           supportsReasoning: reasoningCaps.supportsReasoning,
           reasoningAlwaysOn: reasoningCaps.reasoningAlwaysOn,
@@ -1694,14 +1669,10 @@ export function ChatPage(): ReactElement {
               : true
             : store.reasoningEnabled,
           supportsPreserveThinking: false,
-          // External models have no local tool runtime → supportsTools
-          // stays false. The three supportsBuiltin* flags carry the
-          // server-side capability info for each pill:
-          //   - Search → providerSupportsBuiltinWebSearch
-          //   - Code   → providerSupportsBuiltinCodeExecution
-          //              (Anthropic Claude 4.x + OpenAI gpt-5.5)
-          //   - Images → providerSupportsBuiltinImageGeneration
-          //              (OpenAI cloud Responses-API models)
+          // External models have no local tool runtime → supportsTools false.
+          // The supportsBuiltin* flags carry server-side capability per pill:
+          // Search, Code (Claude 4.x + gpt-5.5), Images (OpenAI cloud
+          // Responses-API).
           supportsTools: false,
           supportsBuiltinWebSearch,
           supportsBuiltinCodeExecution,
@@ -1813,8 +1784,8 @@ export function ChatPage(): ReactElement {
   }, [currentProjectId, navigate, search]);
 
   const exitCompare = useCallback(() => {
-    // Prefer the explicit save; fall back to the last non-compare view so the
-    // composer + menu path also returns to where the user started.
+    // Prefer the explicit save; fall back to the last non-compare view so
+    // the composer + menu path also returns where the user started.
     const saved = viewBeforeCompareRef.current ?? lastNonCompareViewRef.current;
     // No saved view (compare opened by direct URL); fall back to a fresh chat.
     if (!saved) {
@@ -1823,9 +1794,8 @@ export function ChatPage(): ReactElement {
     }
     viewBeforeCompareRef.current = null;
     navigate({ to: "/chat", search: saved });
-    // Restore usage from the last assistant message, but only if it
-    // matches the currently active checkpoint. Without this guard the
-    // relaxed render gate would show stale stats from another model.
+    // Restore usage from the last assistant message, only if it matches the
+    // active checkpoint, else the relaxed render gate shows stale stats.
     const threadId =
       saved.thread ?? useChatRuntimeStore.getState().activeThreadId;
     if (threadId) {
@@ -1845,7 +1815,7 @@ export function ChatPage(): ReactElement {
           const usageModelId =
             (usage as { modelId?: unknown }).modelId;
           // Scope by modelId when present; reject if no active checkpoint
-          // (model-scoped usage cannot be attributed to "nothing").
+          // (model-scoped usage can't be attributed to "nothing").
           if (typeof usageModelId === "string" && usageModelId) {
             if (!activeCheckpoint || usageModelId !== activeCheckpoint) {
               return;
@@ -1895,15 +1865,13 @@ export function ChatPage(): ReactElement {
         .flatMap((provider) =>
           provider.models.map((model) => {
             // For OpenRouter's free router we know which underlying free
-            // model the gateway actually picked once a stream completes
-            // (chat-adapter latches `chunk.model` into the runtime store).
-            // Render the chip as `openrouter:<short-chosen>` — drop the
-            // redundant `/free` from the router id and the org prefix
-            // from the chosen id (e.g.
-            //   openrouter/free + inclusionai/ring-2.6-1t-20260508:free
-            //     -> openrouter:ring-2.6-1t-20260508:free
-            // ). The `:free` suffix on the chosen id already conveys
-            // 'free model', so the leading `/free` is noise.
+            // model the gateway picked once a stream completes (chat-adapter
+            // latches `chunk.model`). Render the chip as
+            // `openrouter:<short-chosen>`, dropping the redundant `/free`
+            // and the chosen id's org prefix (e.g. openrouter/free +
+            // inclusionai/ring-2.6-1t-20260508:free ->
+            // openrouter:ring-2.6-1t-20260508:free). The `:free` suffix
+            // already conveys "free model".
             let displayName = model;
             if (
               provider.providerType === "openrouter" &&
@@ -2117,8 +2085,8 @@ export function ChatPage(): ReactElement {
       <GuidedTour {...tour.tourProps} />
       <div className="relative flex min-h-0 min-w-0 flex-1 basis-0 flex-col overflow-hidden">
         <NativeModelDropOverlay state={nativeModelDropState} />
-        {/* Bottom fade under the top bar so messages dissolve as they scroll
-            beneath it (Gemini / unsloth-sidebar style), instead of a hard cut. */}
+        {/* Fade under the top bar so messages dissolve as they scroll
+            beneath it, instead of a hard cut. */}
         {view.mode !== "compare" && (
           <div
             aria-hidden
diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
index c2e4eaab79..42f8e56ac5 100644
--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
@@ -326,9 +326,8 @@ export function ChatProvidersSettings({
       return;
     }
     // Seed default_models only for curated providers (catalog too large to
-    // enumerate — defaults are the suggestion shortlist). Remote-mode cloud
-    // providers and local OpenAI-compat presets stay empty until the user
-    // clicks "Load available models".
+    // enumerate). Remote cloud providers and local OpenAI-compat presets stay
+    // empty until the user clicks "Load available models".
     const seedDefaults = entry.model_list_mode === "curated";
     setAvailableModels(seedDefaults ? [...entry.default_models] : []);
     setSelectedModelIds([]);
@@ -425,10 +424,9 @@ export function ChatProvidersSettings({
               updatedAt,
             };
           });
-        // Trust the backend response when it succeeds. An empty array means
-        // every connection was removed (often from another browser/tab) and
-        // the local cache should mirror that, otherwise the stale entries
-        // become un-removable in this browser until localStorage is cleared.
+        // Trust the backend response. An empty array means every connection was
+        // removed (often from another tab); mirror that locally, else stale
+        // entries become un-removable here until localStorage is cleared.
         onProvidersChange(syncedProviders);
       } catch (error) {
         // Only surface a toast for real failures, not for the silent
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index bddcb02c69..3b192927d6 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -127,19 +127,11 @@ export function InfoHint({ children }: { children: ReactNode }) {
 }
 
 /**
- * Editable numeric value display.
- *
- * Renders as a single <input> that *looks* like text by default —
- * transparent background, no border, no ring — and only shows a faint
- * surface tint on hover/focus to signal editability. When unfocused,
- * the input shows the formatted display string (`displayValue ?? value`,
- * so labels like "Off" / "Max" still render); on focus, it switches to
- * the raw numeric value, selects it, and accepts free text input.
- * Commit happens on blur or Enter; Escape reverts. The clamp-to-range
- * happens on commit so users can type intermediate values without the
- * input fighting them mid-keystroke. Single component shared by every
- * slider value and the Context Length input so the click-to-edit
- * affordance is consistent across the panel.
+ * Editable numeric value display, shared by every slider value and the Context
+ * Length input. An <input> that looks like text (shows `displayValue ?? value`,
+ * so "Off"/"Max" labels render) until focus, when it swaps to the raw number,
+ * selects it, and accepts free text. Commits on blur/Enter, reverts on Escape.
+ * Clamping happens on commit so typing intermediate values isn't fought.
  */
 function snapToStep(
   value: number,
@@ -205,7 +197,7 @@ function NumericValueInput({
         cancelBlurCommitRef.current = false;
         setDraft(String(value));
         setFocused(true);
-        // Defer the select() so it runs after the value swap above.
+        // Defer select() so it runs after the value swap above.
         const target = e.currentTarget;
         requestAnimationFrame(() => target.select());
       }}
@@ -331,10 +323,9 @@ function CollapsibleSection({
 }: {
   label: string;
   /**
-   * When set, the label text becomes an external link (e.g. to the feature's
-   * GitHub PR) instead of part of the collapse toggle. The chevron still
-   * toggles open/close, so we render the two as siblings rather than nesting
-   * an <a> inside the <button> (invalid HTML).
+   * When set, the label becomes an external link (e.g. the feature's GitHub PR)
+   * instead of part of the toggle. The chevron still toggles, so link and button
+   * are siblings rather than an <a> nested in a <button> (invalid HTML).
    */
   labelHref?: string;
   children?: ReactNode;
@@ -412,17 +403,16 @@ interface ChatSettingsPanelProps {
   onParamsChange: (params: InferenceParams) => void;
   isExternalModel?: boolean;
   /**
-   * Sampling-param capability set for the active external provider, or `null`
-   * for local models (in which case every knob is rendered). Drives the
-   * per-param visibility in the sampling section.
+   * Sampling-param capabilities for the active external provider, or `null` for
+   * local models (every knob rendered). Drives per-param sampling visibility.
    */
   providerCapabilities?: ProviderCapabilities | null;
   activeExternalProvider?: ExternalProviderConfig | null;
   onExternalProviderChange?: (provider: ExternalProviderConfig) => void;
   /**
    * Backend provider type for the active external model (e.g. "kimi",
-   * "anthropic", "openai"), or `null` for local models. Drives the
-   * per-provider Max Tokens floor in the slider.
+   * "anthropic", "openai"), or `null` for local models. Drives the per-provider
+   * Max Tokens floor in the slider.
    */
   externalProviderType?: string | null;
   onReloadModel?: () => void;
@@ -440,9 +430,8 @@ export function ChatSettingsPanel({
   externalProviderType = null,
   onReloadModel,
 }: ChatSettingsPanelProps) {
-  // For non-external (local) models we show every knob — providerCapabilities
-  // is only consulted when `isExternalModel` is true. An external model with an
-  // unknown provider falls back to the OpenAI-compat shape via
+  // Local models show every knob; providerCapabilities is only consulted when
+  // isExternalModel. Unknown providers fall back to the OpenAI-compat shape via
   // getProviderCapabilities, so these flags never undercount support.
   const showTemperature =
     !isExternalModel || Boolean(providerCapabilities?.temperature);
@@ -724,8 +713,7 @@ export function ChatSettingsPanel({
   const settingsContent = (
     <>
       <div className="flex h-full min-h-0 flex-col">
-      {/* Header sits outside the scroll area so the scrollbar never shifts the
-          close button. */}
+      {/* Header is outside the scroll area so the scrollbar never shifts the close button. */}
       <div className="flex h-[48px] shrink-0 items-start gap-2 bg-panel-surface pl-[18px] pr-[16px] pt-[11px]">
         {isMobile ? (
           <span className="flex h-[34px] flex-1 items-center text-[16px] font-semibold tracking-[0em] dark:tracking-[0.015em] text-nav-fg">
diff --git a/studio/frontend/src/features/chat/components/context-usage-bar.tsx b/studio/frontend/src/features/chat/components/context-usage-bar.tsx
index e15a3e0b4f..16dee2a624 100644
--- a/studio/frontend/src/features/chat/components/context-usage-bar.tsx
+++ b/studio/frontend/src/features/chat/components/context-usage-bar.tsx
@@ -28,7 +28,7 @@ function getSeverityColor(percent: number): {
 
 export const ContextUsageBar: FC<{
   used: number;
-  // null on external providers (no known window); bar then hides the ratio.
+  // null on external providers (unknown window); bar hides the ratio.
   total?: number | null;
   cached?: number;
   // Anthropic-only (billed at the write premium).
diff --git a/studio/frontend/src/features/chat/components/model-load-status.tsx b/studio/frontend/src/features/chat/components/model-load-status.tsx
index 75d92f4581..fd78866ece 100644
--- a/studio/frontend/src/features/chat/components/model-load-status.tsx
+++ b/studio/frontend/src/features/chat/components/model-load-status.tsx
@@ -17,15 +17,10 @@ function clampProgress(value: number): number {
 }
 
 /**
- * Split a composed progress label like
- *   "22.8 of 122.3 GB • 330.1 MB/s • 5m 9s left"
- * into a primary chunk ("22.8 of 122.3 GB") that can sit next to the
- * percent, and a secondary chunk ("330.1 MB/s • 5m 9s left") that can
- * live on its own row. This keeps either line from overflowing into a
- * ragged wrap when the rate/ETA part shows up mid-download.
- *
- * Labels without " • " (e.g. "22.8 GB downloaded") are returned
- * primary-only, so the secondary row simply doesn't render.
+ * Split a composed progress label like "22.8 of 122.3 GB • 330.1 MB/s • 5m 9s
+ * left" into a primary chunk (next to the percent) and a secondary chunk (its
+ * own row), so neither line wraps raggedly once rate/ETA appears mid-download.
+ * Labels without " • " return primary-only, so the secondary row doesn't render.
  */
 function splitProgressLabel(
   label: string | null | undefined,
@@ -46,8 +41,7 @@ export function ModelLoadDescription({
   progressLabel,
 }: ModelLoadDescriptionProps) {
   const hasProgress = typeof progressPercent === "number";
-  // Split once at the top of the render so the JSX below stays flat --
-  // no IIFE required. splitProgressLabel is a trivial string op.
+  // Split once at the top so the JSX below stays flat (no IIFE).
   const { primary: labelPrimary, secondary: labelSecondary } =
     splitProgressLabel(progressLabel);
 
@@ -116,9 +110,8 @@ export function ModelLoadInlineStatus({
             className="flex shrink-0 items-center gap-1 text-[10px] font-medium tracking-[0.08em] text-muted-foreground/80"
             title={progressLabel ?? undefined}
           >
-            {/* Inline layout is horizontal and tight -- show only the
-                primary (bytes) chunk; the full label (with rate/ETA)
-                stays available via the tooltip. */}
+            {/* Tight inline layout: show only the primary (bytes) chunk;
+                full label (rate/ETA) stays in the tooltip. */}
             <span>{splitProgressLabel(progressLabel).primary}</span>
             <span className="tabular-nums">
               {Math.round(clampProgress(progressPercent))}%
diff --git a/studio/frontend/src/features/chat/components/openai-code-exec-section.tsx b/studio/frontend/src/features/chat/components/openai-code-exec-section.tsx
index 29e5260de2..7dfa03672d 100644
--- a/studio/frontend/src/features/chat/components/openai-code-exec-section.tsx
+++ b/studio/frontend/src/features/chat/components/openai-code-exec-section.tsx
@@ -2,29 +2,21 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Settings-sheet section for OpenAI shell-tool container management.
- * Renders only when:
- *   - active provider is OpenAI cloud (api.openai.com base URL), AND
- *   - the active model is gpt-5.5 or gpt-5.5-pro (the only families
- *     where the shell tool is wired through today).
+ * Settings-sheet section for OpenAI shell-tool container management. Renders
+ * only when the active provider is OpenAI cloud (api.openai.com) and the model
+ * is gpt-5.5 / gpt-5.5-pro (the only families wired to the shell tool today).
  *
- * Surfaces three controls:
- *   1. Default container idle-timeout (minutes). Persists on the
- *      provider record; pre-fills the create dialog and is used by
- *      the chat-adapter's lazy-create path on the first turn of a
- *      thread.
- *   2. Container picker for the *active thread* — pick any of the
- *      user's existing OpenAI containers, or "Auto-create per thread"
- *      (default; lets the auto-create path manage it).
- *   3. Create-new-container inline form. Refresh + delete actions
- *      per row.
+ * Controls:
+ *   1. Default container idle-timeout (minutes). Persisted on the provider
+ *      record; pre-fills the create dialog and feeds the chat-adapter's
+ *      lazy-create path on a thread's first turn.
+ *   2. Container picker for the active thread (an existing OpenAI container or
+ *      auto-create per thread).
+ *   3. Create-new-container inline form, with per-row refresh + delete.
  *
- * State persistence:
- *   - TTL → ExternalProviderConfig.openaiContainerTtlMinutes
- *   - Active container for this thread → ThreadRecord.openaiCodeExecContainerId
- *
- * No new global stores — list is fetched on open / refresh and held
- * in component state.
+ * Persistence: TTL -> ExternalProviderConfig.openaiContainerTtlMinutes;
+ * active container -> ThreadRecord.openaiCodeExecContainerId. No global stores;
+ * the list is fetched on open / refresh and held in component state.
  */
 
 "use client";
@@ -63,10 +55,9 @@ import {
 const DEFAULT_TTL_MINUTES = 20;
 const TTL_MIN = 1;
 const TTL_MAX = 20; // OpenAI hard cap on expires_after.minutes
-// Cadence for re-fetching the container list while the section is
-// mounted. OpenAI's container TTL flips at minute granularity, so 30s
-// is fast enough that an expired container loses its ACTIVE pill within
-// half a minute without hammering /v1/containers.
+// Re-fetch cadence while the section is mounted. OpenAI's TTL flips at minute
+// granularity, so 30s drops an expired container's ACTIVE pill within half a
+// minute without hammering /v1/containers.
 const REFRESH_POLL_MS = 30_000;
 
 function ageLabel(epochSeconds: number | null | undefined): string {
@@ -89,10 +80,9 @@ function shortContainerId(id: string): string {
 }
 
 function isContainerRunning(c: OpenAIContainerSummary): boolean {
-  // OpenAI's containers API reports `status: "running"` while idle TTL is
-  // valid and `status: "expired"` once the idle window has passed. Treat
-  // a missing status as running so we don't false-positive on any older
-  // payloads that didn't include the field.
+  // OpenAI reports `status: "running"` while idle TTL is valid and "expired"
+  // afterward. Treat a missing status as running so older payloads without the
+  // field don't false-positive.
   return c.status == null || c.status === "running";
 }
 
@@ -114,32 +104,27 @@ export function OpenAICodeExecSection({
   const [creating, setCreating] = useState(false);
   const [createOpen, setCreateOpen] = useState(false);
   const [createName, setCreateName] = useState("");
-  // Ids that have been deleted in this session. Once tombstoned, an id
-  // stays hidden from the picker for the lifetime of the page — OpenAI's
-  // /containers list can keep returning a freshly-deleted id for an
-  // undocumented and variable amount of time, and an automatic re-show
-  // creates more confusion than it solves. Refreshing the page resets
-  // the tombstone naturally.
+  // Ids deleted this session. A tombstoned id stays hidden for the page's
+  // lifetime: OpenAI's /containers list can keep returning a freshly-deleted
+  // id for an undocumented, variable time, and auto-reshowing it confuses more
+  // than it helps. A page refresh resets the tombstone.
   const [tombstones, setTombstones] = useState<Set<string>>(() => new Set());
-  // Ids optimistically inserted after a successful create but not yet
-  // confirmed by a /v1/containers list response. OpenAI's list endpoint
-  // is eventually consistent — a freshly-created container can be absent
-  // for several seconds. We render the row immediately with a "Creating"
-  // pill, then drop it from this set once a refresh sees the id.
+  // Ids optimistically inserted after a create but not yet confirmed by a
+  // /v1/containers list. That endpoint is eventually consistent (a new
+  // container can be absent for several seconds), so we render the row at once
+  // with a "Creating" pill and drop it once a refresh sees the id.
   const [pendingIds, setPendingIds] = useState<Set<string>>(() => new Set());
-  // Ref mirror so `refresh()` can read the current pending set without
-  // re-binding when it changes (the callback is in a useEffect dep).
+  // Ref mirror so `refresh()` reads the current pending set without re-binding
+  // when it changes (the callback is a useEffect dep).
   const pendingIdsRef = useRef<Set<string>>(pendingIds);
   useEffect(() => {
     pendingIdsRef.current = pendingIds;
   }, [pendingIds]);
-  // One-shot follow-up refresh scheduled after a create, to catch the
-  // common case where the server list lags the create response by a few
-  // seconds. Tracked so we can clear it on unmount.
+  // One-shot follow-up refresh after a create, for when the server list lags
+  // the create response by a few seconds. Tracked so we clear it on unmount.
   const pendingRetryRef = useRef<number | null>(null);
-  // Target row for the destructive confirmation dialog. Held in state
-  // (rather than blocking with window.confirm) so the dialog sits inside
-  // the settings sheet instead of a native browser alert.
+  // Target row for the delete-confirmation dialog. Held in state (not
+  // window.confirm) so the dialog sits inside the settings sheet.
   const [pendingDelete, setPendingDelete] =
     useState<OpenAIContainerSummary | null>(null);
   const [deleting, setDeleting] = useState(false);
@@ -174,15 +159,15 @@ export function OpenAICodeExecSection({
   }, [activeThreadId]);
 
   // Hide just-deleted containers even if OpenAI's list still returns them.
-  // This is the single chokepoint — every downstream view (sorted picker,
-  // auto-bind candidate, all-containers list) derives from visibleContainers.
+  // Single chokepoint: every downstream view (sorted picker, auto-bind
+  // candidate, all-containers list) derives from visibleContainers.
   const visibleContainers = useMemo(() => {
     if (tombstones.size === 0) return containers;
     return containers.filter((c) => !tombstones.has(c.id));
   }, [containers, tombstones]);
 
-  // Containers sorted newest-first by lastActiveAt so the dropdown's
-  // default (auto-bind target) shows up first.
+  // Newest-first by lastActiveAt so the dropdown default (auto-bind target)
+  // shows up first.
   const sortedContainers = useMemo(
     () =>
       [...visibleContainers].sort(
@@ -191,19 +176,18 @@ export function OpenAICodeExecSection({
     [visibleContainers],
   );
 
-  // First running container by lastActiveAt — the auto-bind target and
-  // also what we surface visually before Dexie catches up.
+  // First running container by lastActiveAt: the auto-bind target and what we
+  // surface visually before Dexie catches up.
   const firstRunningContainer = useMemo(
     () => sortedContainers.find(isContainerRunning) ?? null,
     [sortedContainers],
   );
 
-  // What the picker should treat as "active" right now. We decouple
-  // this from `activeContainerId` (Dexie state) so the user immediately
-  // sees the most-recent running container while the auto-bind effect's
-  // async write propagates. If the Dexie-bound container has since
-  // expired, fall back to the first running candidate — the stale-bind
-  // sweeper below will clear Dexie shortly after.
+  // What the picker treats as "active" now. Decoupled from `activeContainerId`
+  // (Dexie state) so the user sees the most-recent running container while the
+  // auto-bind effect's async write propagates. If the Dexie-bound container
+  // expired, fall back to the first running candidate; the stale-bind sweeper
+  // clears Dexie shortly after.
   const boundContainer = useMemo(
     () => sortedContainers.find((c) => c.id === activeContainerId) ?? null,
     [sortedContainers, activeContainerId],
@@ -223,8 +207,8 @@ export function OpenAICodeExecSection({
       });
       const serverIds = new Set(list.map((c) => c.id));
       setContainers((prev) => {
-        // Preserve optimistic inserts the server hasn't acknowledged
-        // yet so they don't disappear on the reconciling refresh.
+        // Preserve optimistic inserts the server hasn't acknowledged yet so
+        // they don't disappear on the reconciling refresh.
         const orphans = prev.filter(
           (c) => !serverIds.has(c.id) && pendingIdsRef.current.has(c.id),
         );
@@ -248,11 +232,9 @@ export function OpenAICodeExecSection({
     }
   }, [apiKey, provider.baseUrl]);
 
-  // Fetch once when the section mounts (or provider changes), then
-  // poll on a low cadence so an expired container's ACTIVE pill clears
-  // without the user clicking the refresh button. Also re-fetch when
-  // the tab regains visibility — covers the common case of leaving the
-  // sheet open across a long idle period.
+  // Fetch on mount (or provider change), then poll on a low cadence so an
+  // expired container's ACTIVE pill clears without a manual refresh. Also
+  // re-fetch when the tab regains visibility (sheet left open while idle).
   useEffect(() => {
     void refresh();
     const interval = window.setInterval(() => {
@@ -276,21 +258,17 @@ export function OpenAICodeExecSection({
     };
   }, [refresh]);
 
-  // Auto-bind the active thread to the most-recently-active container
-  // whenever the thread has none set and at least one container exists
-  // on the user's OpenAI account. Sorting by `lastActiveAt` matches
-  // what feels "most recent" from the user's perspective.
+  // Auto-bind the active thread to the most-recently-active container when the
+  // thread has none and at least one container exists on the account. Sorting
+  // by `lastActiveAt` matches what feels "most recent" to the user.
   //
-  // We eagerly materialize the thread row via `ensureThreadRecord` so
-  // the bind lands before the user has sent a first
-  // message. This does NOT create anything at OpenAI — only a local
-  // ThreadRecord — so it does not bypass the user's expectation that
-  // a fresh OpenAI container is not created until first send.
+  // `ensureThreadRecord` eagerly materializes the thread row so the bind lands
+  // before the first message. This creates nothing at OpenAI (only a local
+  // ThreadRecord), so a fresh OpenAI container is still not created until first
+  // send.
   //
-  // If `containers` is empty (no OpenAI containers exist yet), this
-  // effect short-circuits: the picker renders an empty-state hint and
-  // the chat-adapter's lazy-create path will mint the first container
-  // on first send.
+  // If no containers exist yet, this short-circuits: the picker shows an
+  // empty-state hint and the chat-adapter mints the first container on send.
   useEffect(() => {
     if (
       !activeThreadId ||
@@ -330,14 +308,12 @@ export function OpenAICodeExecSection({
 
   const onPick = async (value: string) => {
     if (!activeThreadId || !value) return;
-    // value is always a container id now — the "Auto-create per thread"
-    // option has been removed in favour of always defaulting to the
-    // most-recently-active container. The chat-adapter still handles
-    // the no-containers-exist case (lazy-create on first send).
+    // value is always a container id now; "Auto-create per thread" was removed
+    // in favour of defaulting to the most-recently-active container. The
+    // chat-adapter still handles the no-containers case (lazy-create on send).
     //
-    // ensureThreadRecord materializes the thread row eagerly (modelType
-    // "base" — settings sheet is single-thread-mode only) so the update
-    // actually lands when the user hasn't sent a message yet.
+    // ensureThreadRecord eagerly materializes the thread row (modelType "base":
+    // settings sheet is single-thread only) so the update lands before send.
     try {
       await ensureThreadRecord({ threadId: activeThreadId, modelType: "base" });
       const updated = await updateStoredChatThread(activeThreadId, {
@@ -360,9 +336,9 @@ export function OpenAICodeExecSection({
       toast.error("Container name is required");
       return;
     }
-    // TTL inherits from the section-level "Idle timeout" control —
-    // there is no per-container override on the form. Read it at
-    // submit time so a last-second change to the TTL row applies.
+    // TTL inherits from the section-level "Idle timeout" control (no
+    // per-container override). Read at submit time so a last-second TTL change
+    // applies.
     const ttlMinutes =
       provider.openaiContainerTtlMinutes ?? DEFAULT_TTL_MINUTES;
     setCreating(true);
@@ -374,10 +350,9 @@ export function OpenAICodeExecSection({
       toast.success(`Created container ${name}`);
       setCreateName("");
       setCreateOpen(false);
-      // Optimistic insert + "Creating" pill. OpenAI's /v1/containers
-      // list endpoint is eventually consistent and can omit the new
-      // container for several seconds — without this, the row only
-      // shows up on the next 30s poll or a manual refresh.
+      // Optimistic insert + "Creating" pill. The /v1/containers list is
+      // eventually consistent and can omit the new container for seconds;
+      // without this the row only appears on the next poll or manual refresh.
       setContainers((prev) =>
         prev.some((c) => c.id === created.id) ? prev : [created, ...prev],
       );
@@ -387,9 +362,8 @@ export function OpenAICodeExecSection({
         next.add(created.id);
         return next;
       });
-      // Follow-up refresh ~5s later to reconcile the optimistic row
-      // with the server's view once /v1/containers catches up. One
-      // shot; the regular poll covers any longer tail.
+      // Follow-up refresh ~5s later to reconcile the optimistic row once
+      // /v1/containers catches up. One shot; the poll covers a longer tail.
       if (pendingRetryRef.current != null) {
         window.clearTimeout(pendingRetryRef.current);
       }
@@ -397,9 +371,8 @@ export function OpenAICodeExecSection({
         pendingRetryRef.current = null;
         void refresh();
       }, 5000);
-      // Auto-bind the just-created container to the active thread.
-      // ensureThreadRecord first so the bind lands even when the user
-      // creates a container before sending the first message.
+      // Auto-bind the new container to the active thread. ensureThreadRecord
+      // first so the bind lands even if no message has been sent yet.
       if (activeThreadId) {
         try {
           await ensureThreadRecord({
@@ -420,8 +393,7 @@ export function OpenAICodeExecSection({
     } finally {
       setCreating(false);
       // Refresh even on failure: the request may have partially succeeded
-      // server-side (created container, lost response), and a re-fetch
-      // keeps the picker in sync with OpenAI's actual state.
+      // (container created, response lost); a re-fetch keeps the picker in sync.
       await refresh();
     }
   };
@@ -435,8 +407,8 @@ export function OpenAICodeExecSection({
         { apiKey, baseUrl: provider.baseUrl || null },
         id,
       );
-      // Tombstone the id so the picker hides it immediately even if
-      // OpenAI's list keeps returning it for a while.
+      // Tombstone the id so the picker hides it at once even if OpenAI's list
+      // keeps returning it for a while.
       setTombstones((prev) => {
         if (prev.has(id)) return prev;
         const next = new Set(prev);
@@ -460,9 +432,8 @@ export function OpenAICodeExecSection({
     } finally {
       setDeleting(false);
       setPendingDelete(null);
-      // Always refresh so a stale list entry (e.g. container deleted
-      // elsewhere, or already expired) is purged from the UI even when
-      // the delete call itself errored.
+      // Always refresh so a stale list entry (deleted elsewhere or expired) is
+      // purged even when the delete call errored.
       await refresh();
     }
   };
@@ -496,9 +467,8 @@ export function OpenAICodeExecSection({
         />
       </div>
 
-      {/* Single container list. Clicking a row binds it to the active
-          thread and the ACTIVE pill marks which one — no separate
-          picker needed. */}
+      {/* Container list. Clicking a row binds it to the active thread; the
+          ACTIVE pill marks which one (no separate picker). */}
       <div className="flex flex-col gap-1.5">
         <div className="flex items-center justify-between gap-2">
           <span className="text-[11px] uppercase tracking-wider text-muted-foreground">
@@ -518,10 +488,9 @@ export function OpenAICodeExecSection({
           </Button>
         </div>
         {sortedContainers.length === 0 ? (
-          // Quiet placeholder with the same muted border as row cards
-          // so an empty section doesn't masquerade as an active control.
-          // The first container is minted by the chat-adapter on first
-          // send (lazy-create) and appears here after the next refresh.
+          // Quiet placeholder with the same muted border as row cards so an
+          // empty section doesn't look like an active control. The first
+          // container is lazy-created on first send and appears after refresh.
           <div className="flex h-9 w-full items-center rounded-md border border-dashed border-border/60 bg-muted/20 px-2 text-xs text-muted-foreground">
             None yet - one will be created on first send.
           </div>
@@ -566,9 +535,8 @@ export function OpenAICodeExecSection({
                         : undefined
                   }
                 >
-                  {/* min-w-0 + truncate keeps long OpenAI container ids
-                      from spilling under the trash button on narrow
-                      settings sheets. */}
+                  {/* min-w-0 + truncate keeps long container ids from
+                      spilling under the trash button on narrow sheets. */}
                   <div className="flex min-w-0 flex-1 flex-col gap-0.5">
                     <div className="flex min-w-0 items-center gap-1.5">
                       <span className="min-w-0 truncate font-medium">
@@ -619,10 +587,9 @@ export function OpenAICodeExecSection({
         )}
       </div>
 
-      {/* Create new — inline single-row edit that visually echoes a
-          container card. TTL is inherited from the section's top
-          "Idle timeout" control (no per-container override), which
-          keeps the form light and avoids a duplicated input. */}
+      {/* Create new: inline single-row edit echoing a container card. TTL is
+          inherited from the top "Idle timeout" control (no per-container
+          override), keeping the form light. */}
       {createOpen ? (
         <div className="flex items-center gap-1 rounded-md border border-border/60 bg-muted/20 px-1.5 py-1">
           <Input
diff --git a/studio/frontend/src/features/chat/db.ts b/studio/frontend/src/features/chat/db.ts
index 2aa19ecd9f..928d1722e0 100644
--- a/studio/frontend/src/features/chat/db.ts
+++ b/studio/frontend/src/features/chat/db.ts
@@ -45,9 +45,8 @@ export { db };
 /**
  * Wraps Dexie liveQuery for React state updates.
  *
- * Important: include every semantic query input in `deps` (filters, sort keys,
- * IDs, etc). `querier` identity is intentionally ignored to avoid re-subscribing
- * on every render when callers pass inline functions.
+ * Include every semantic query input in `deps` (filters, sort keys, IDs). `querier`
+ * identity is ignored to avoid re-subscribing every render on inline functions.
  */
 export function useLiveQuery<T>(
   querier: () => Promise<T>,
diff --git a/studio/frontend/src/features/chat/external-providers.ts b/studio/frontend/src/features/chat/external-providers.ts
index b10253c280..300d384cdf 100644
--- a/studio/frontend/src/features/chat/external-providers.ts
+++ b/studio/frontend/src/features/chat/external-providers.ts
@@ -17,33 +17,29 @@ export interface ExternalProviderConfig {
   /** Whether to ask supported hosted providers to use prompt caching. */
   enablePromptCaching?: boolean;
   /**
-   * Anthropic prompt-cache TTL bucket. Only meaningful when
-   * `enablePromptCaching` is true and the provider supports the choice
-   * (Anthropic today). Maps to `prompt_cache_ttl` on the backend, which
-   * attaches `cache_control.ttl` to the cache marker. Omitted = inherit
-   * Anthropic's default 5-minute pool, same as before this knob existed.
+   * Anthropic prompt-cache TTL bucket. Only meaningful when `enablePromptCaching`
+   * is true and the provider supports the choice (Anthropic today). Maps to
+   * backend `prompt_cache_ttl`, which sets `cache_control.ttl` on the cache
+   * marker. Omitted = inherit Anthropic's default 5-minute pool.
    */
   promptCacheTtl?: "5m" | "1h";
   /** User-pinned: the loaded vLLM model supports `enable_thinking`. */
   isReasoningModel?: boolean;
   /**
-   * Default idle-timeout (in minutes) for newly created OpenAI shell
-   * containers. Pre-fills the "Create container" dialog and is the
-   * TTL the auto-create-per-thread path POSTs to /v1/containers with.
-   * OpenAI's hard default is 20. Only meaningful for OpenAI cloud.
+   * Default idle-timeout (minutes) for new OpenAI shell containers. Pre-fills the
+   * "Create container" dialog and is the TTL the auto-create-per-thread path POSTs
+   * to /v1/containers. OpenAI's hard default is 20. Only for OpenAI cloud.
    */
   openaiContainerTtlMinutes?: number;
   createdAt: number;
   updatedAt: number;
 }
 
-// Gemini supports prompt caching, but the wire flow requires a
-// separate POST to /v1beta/cachedContents to create the cache before
-// the generateContent call can reference it; the boolean Studio
-// currently emits on enable_prompt_caching is not enough on its own.
-// Until that two-step orchestration ships we keep the picker off so
-// the toggle does not silently no-op for Gemini users. See
-// https://ai.google.dev/gemini-api/docs/caching.
+// Gemini supports prompt caching, but the wire flow needs a separate POST to
+// /v1beta/cachedContents before generateContent can reference the cache; the
+// enable_prompt_caching boolean alone isn't enough. Until that two-step flow
+// ships, keep the picker off so the toggle doesn't silently no-op for Gemini.
+// See https://ai.google.dev/gemini-api/docs/caching.
 const PROMPT_CACHING_PROVIDER_TYPES = new Set(["openai", "anthropic"]);
 
 export function supportsProviderPromptCaching(
@@ -53,10 +49,9 @@ export function supportsProviderPromptCaching(
 }
 
 /**
- * Whether the provider lets the user choose between a short and a long
- * prompt-cache pool. Anthropic exposes both a 5m and a 1h ephemeral
- * pool via `cache_control.ttl`; OpenAI's automatic prompt cache has no
- * equivalent user-selectable knob, so it stays off the picker.
+ * Whether the provider lets the user choose between a short and long prompt-cache
+ * pool. Anthropic exposes 5m and 1h ephemeral pools via `cache_control.ttl`;
+ * OpenAI's automatic cache has no equivalent knob, so it stays off the picker.
  */
 const PROMPT_CACHE_TTL_PROVIDER_TYPES = new Set(["anthropic"]);
 
@@ -74,8 +69,8 @@ export function isPromptCacheTtl(value: unknown): value is "5m" | "1h" {
   return typeof value === "string" && PROMPT_CACHE_TTL_VALUES.has(value as "5m" | "1h");
 }
 
-// Provider types that expose the connection-level "reasoning model"
-// toggle. vLLM's OpenAI-compat endpoint doesn't advertise this per model.
+// Provider types exposing the connection-level "reasoning model" toggle.
+// vLLM's OpenAI-compat endpoint doesn't advertise this per model.
 const REASONING_TOGGLE_PROVIDER_TYPES = new Set(["vllm"]);
 
 export function supportsProviderReasoningToggle(
@@ -245,10 +240,9 @@ export function toExternalBackendProviderType(
   providerType: string | null | undefined,
 ): string | undefined {
   if (!providerType) return undefined;
-  // vLLM's /v1/responses applies the loaded model's chat template, which
-  // 400s on strict-alternation templates (e.g. Gemma 3). Pass the actual
-  // type through so the backend routes vLLM to /v1/chat/completions instead
-  // of the OpenAI Responses path used for gpt-5.x.
+  // vLLM's /v1/responses applies the loaded model's chat template, which 400s on
+  // strict-alternation templates (e.g. Gemma 3). Pass the type through so the
+  // backend routes vLLM to /v1/chat/completions instead of the Responses path.
   if (providerType === "vllm") return "vllm";
   if (providerType === "ollama") return "ollama";
   if (providerType === "llama_cpp") return "llama_cpp";
@@ -419,10 +413,8 @@ export function loadExternalProviders(): ExternalProviderConfig[] {
   }
 }
 
-/**
- * Load the raw (encrypted or legacy plaintext) key map from localStorage.
- * Values are opaque strings — either AES-GCM ciphertext or legacy plaintext.
- */
+/** Load the raw key map from localStorage. Values are opaque strings: either
+ * AES-GCM ciphertext or legacy plaintext. */
 function loadRawKeyMap(): Record<string, string> {
   if (!canUseStorage()) return {};
   try {
@@ -457,7 +449,7 @@ export function saveExternalProviders(
   if (!canUseStorage()) return;
   try {
     localStorage.setItem(EXTERNAL_PROVIDERS_KEY, JSON.stringify(providers));
-    // Prune keys for removed providers — works on raw ciphertext, no decryption needed
+    // Prune keys for removed providers (works on raw ciphertext, no decryption)
     const allowedIds = new Set(providers.map((provider) => provider.id));
     const keys = loadRawKeyMap();
     const pruned: Record<string, string> = {};
@@ -472,10 +464,7 @@ export function saveExternalProviders(
   }
 }
 
-/**
- * Retrieve a provider API key from localStorage.
- * Returns "" if no key is stored.
- */
+/** Retrieve a provider API key from localStorage; "" if none stored. */
 export function getExternalProviderApiKey(
   providerId: string,
 ): string {
@@ -483,9 +472,7 @@ export function getExternalProviderApiKey(
   return keys[providerId] ?? "";
 }
 
-/**
- * Store a provider API key in localStorage.
- */
+/** Store a provider API key in localStorage. */
 export function setExternalProviderApiKey(
   providerId: string,
   apiKey: string,
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index d1dab924cb..a152cbb358 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -167,11 +167,9 @@ function getTrustRemoteCodeRequiredMessage(modelName: string): string {
   return `${modelName} needs custom code enabled to load. Turn on "Enable custom code" in Chat Settings, then try again.`;
 }
 
-// Canonicalises any value the backend reports (or persisted state holds)
-// onto the five UI-facing modes the Speculative Decoding dropdown
-// understands: "auto" / "mtp" / "ngram" / "mtp+ngram" / "off" / null.
-// Mirrors backend _canonicalize_spec_mode so old persisted "default" /
-// "draft-mtp" / "ngram-mod" / chain values round-trip cleanly.
+// Canonicalises any backend/persisted value onto the Speculative Decoding
+// dropdown's modes ("auto"/"mtp"/"ngram"/"mtp+ngram"/"off"/null). Mirrors
+// backend _canonicalize_spec_mode so legacy persisted values round-trip.
 function normalizeSpeculativeType(v: string | null | undefined): string | null {
   if (v == null) return null;
   const s = String(v).trim().toLowerCase();
@@ -276,9 +274,8 @@ export function useChatModelRuntime() {
         listLoras(),
       ]);
 
-      // Cancellation can land while the requests above are in flight (e.g. the
-      // user cancels a load during this refresh). Bail before writing any
-      // backend state back into the store -- cancelLoading already cleared it.
+      // Cancellation can land while the requests above are in flight. Bail
+      // before writing backend state back -- cancelLoading already cleared it.
       if (signal?.aborted) return;
 
       setModels(listRes.models.map(toChatModelSummary));
@@ -331,12 +328,10 @@ export function useChatModelRuntime() {
         const currentSpecType = normalizeSpeculativeType(
           statusRes.speculative_type,
         );
-        // Refresh runs both on F5 (fresh store needs hydration) AND right
-        // after a fresh load (store was already set by the load path). For
-        // the user-configurable model params we only hydrate when the shadow
-        // `loaded*` field is still null -- that signals "not yet hydrated".
-        // Otherwise we'd clobber the values the load path just applied and
-        // the UI would appear to revert the user's changes.
+        // Refresh runs on F5 (needs hydration) and right after a load (store
+        // already set). For user-configurable params, only hydrate when the
+        // shadow `loaded*` field is null ("not yet hydrated"); otherwise we'd
+        // clobber what the load path just applied and revert the user.
         const prevState = useChatRuntimeStore.getState();
         const clampedReasoningEffort = clampLocalReasoningEffort(
           prevState.reasoningEffort,
@@ -355,15 +350,12 @@ export function useChatModelRuntime() {
           supportsPreserveThinking,
           supportsTools,
           // Reset per-turn reasoning flag so:
-          //   1. models that do not support reasoning do not inherit a stale
-          //      off state from a prior model, and
-          //   2. local reasoning-effort models (where the composer hides
-          //      the Off option via supportsReasoningOff=false) cannot end
-          //      up with reasoningEnabled=false carried over from an
-          //      external model where Off was selected — the composer would
-          //      keep showing "Think: <level>" via effectiveReasoningEnabled,
-          //      but the chat-adapter would omit the kwarg and the Harmony
-          //      template would fall back to its own default effort.
+          //   1. non-reasoning models don't inherit a stale off state, and
+          //   2. local reasoning-effort models (Off hidden via
+          //      supportsReasoningOff=false) don't carry reasoningEnabled=false
+          //      from an external model where Off was selected -- the composer
+          //      would still show "Think: <level>" but the adapter would omit
+          //      the kwarg, so Harmony falls back to its default effort.
           reasoningEnabled: supportsReasoning
             ? reasoningStyle === "reasoning_effort"
               ? true
@@ -600,15 +592,12 @@ export function useChatModelRuntime() {
             }
             if (abortCtrl.signal.aborted) throw new Error("Cancelled");
 
-            // Reset Speculative Decoding to Auto whenever the user
-            // switches to a different model. Spec strategy is a
-            // per-model decision: a sub-3B non-MTP GGUF that ran with
-            // "Off" should not carry that choice into a 27B MTP GGUF
-            // where Auto would auto-promote to draft-mtp. The user can
-            // still pick a forced mode on the new model; this just
-            // clears the stale prior-model choice so the backend's
-            // platform-aware path runs by default. Same applies to
-            // spec_draft_n_max which is MTP-only.
+            // Reset Speculative Decoding to Auto on model switch: spec
+            // strategy is per-model, so a sub-3B non-MTP GGUF's "Off" must
+            // not carry into a 27B MTP GGUF where Auto auto-promotes to
+            // draft-mtp. Clears the stale prior choice so the backend's
+            // platform-aware path runs by default; same for spec_draft_n_max
+            // (MTP-only). The user can still force a mode on the new model.
             if (currentCheckpoint && currentCheckpoint !== modelId) {
               useChatRuntimeStore.setState({
                 speculativeType: null,
@@ -852,17 +841,15 @@ export function useChatModelRuntime() {
         );
         loadToastIdRef.current = toastId;
 
-        // Poll download progress for non-cached models (GGUF and non-GGUF).
-        // Then, once the download wraps (or for already-cached models),
-        // poll the llama-server mmap phase so "Starting model..." no
-        // longer looks frozen for several minutes on large MoE models.
+        // Poll download progress for non-cached models, then (after download
+        // or for cached models) poll the llama-server mmap phase so "Starting
+        // model..." doesn't look frozen for minutes on large MoE models.
         let progressInterval: ReturnType<typeof setInterval> | null = null;
         const expectedBytes =
           typeof selection !== "string" ? selection.expectedBytes ?? 0 : 0;
 
-        // Rolling window of byte samples for rate / ETA estimation.
-        // Shared across download + mmap phases so the estimator doesn't
-        // reset when the phase flips.
+        // Rolling window of byte samples for rate/ETA estimation, shared
+        // across download + mmap phases so it survives phase flips.
         type Sample = { t: number; b: number };
         const MIN_SAMPLES = 3;
         const MIN_WINDOW = 3_000; // ms
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts b/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
index f8e1535e04..dc9226fb8e 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-search-index.ts
@@ -95,8 +95,8 @@ async function buildIndex(): Promise<ChatSearchItem[]> {
   );
 
   // Legacy-only chats can exist before server-side history import finishes.
-  // Fill just the missing ids from the legacy-aware path instead of issuing
-  // one request per thread up front.
+  // Fill only the missing ids via the legacy path instead of one request per
+  // thread up front.
   const missingThreadIds = allThreadIds.filter(
     (threadId) => !messagesByThread.has(threadId),
   );
@@ -163,8 +163,7 @@ export function useChatSearchIndex(enabled: boolean): {
       setLoading(true);
       buildIndex()
         .then((result) => {
-          // Drop out-of-order responses so a slower rebuild can't clobber
-          // a fresher one.
+          // Drop out-of-order responses so a slower rebuild can't clobber a fresher one.
           if (cancelled || seq !== requestSeqRef.current) return;
           setItems(result);
         })
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
index 54aa5d82dc..c2607d6b7b 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-sidebar-items.ts
@@ -61,9 +61,8 @@ export function groupThreads(threads: ThreadRecord[]): SidebarItem[] {
   return items.sort((a, b) => b.createdAt - a.createdAt);
 }
 
-// Streaming fires CHAT_HISTORY_UPDATED_EVENT per chunk. Debounce so
-// each quiet window produces at most one O(N) fetch; requestSeq
-// discards stale responses.
+// Streaming fires CHAT_HISTORY_UPDATED_EVENT per chunk. Debounce so each quiet
+// window produces at most one O(N) fetch; requestSeq discards stale responses.
 const SIDEBAR_REFRESH_DEBOUNCE_MS = 300;
 
 export function useChatSidebarItems(options?: {
diff --git a/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts b/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts
index e159101a7f..76987a86d3 100644
--- a/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts
+++ b/studio/frontend/src/features/chat/hooks/use-pill-activation-order.ts
@@ -3,9 +3,8 @@
 
 import { useEffect, useState } from "react";
 
-// Tracks which of the given keys are active and the order in which each became
-// active, so opt-in composer pills (Canvas, MCP) render in the order they were
-// toggled on rather than a fixed order.
+// Tracks which keys are active and their activation order, so opt-in
+// composer pills (Canvas, MCP) render in toggle-on order, not a fixed one.
 export function usePillActivationOrder(states: Record<string, boolean>): string[] {
   const [order, setOrder] = useState<string[]>(() =>
     Object.keys(states).filter((key) => states[key]),
diff --git a/studio/frontend/src/features/chat/hooks/use-transfer-stats.ts b/studio/frontend/src/features/chat/hooks/use-transfer-stats.ts
index 5681680842..b1f03354e3 100644
--- a/studio/frontend/src/features/chat/hooks/use-transfer-stats.ts
+++ b/studio/frontend/src/features/chat/hooks/use-transfer-stats.ts
@@ -2,19 +2,17 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Compute rate (bytes/sec) and ETA (seconds) from a time-series of
- * cumulative ``bytes`` values, using a rolling window of recent samples.
+ * Compute rate (bytes/sec) and ETA (seconds) from a time-series of cumulative
+ * ``bytes`` values, using a rolling window of recent samples.
  *
- * Shared between the chat-flow download toast, the training-start
- * overlay, and the model-load phase UI. All three have the same shape:
- * a counter that rises monotonically from 0 toward ``totalBytes``, polled
- * on an interval. The derived stats are identical regardless of whether
- * the bytes came from an HTTP download or an mmap page-in.
+ * Shared by the chat-flow download toast, training-start overlay, and
+ * model-load phase UI: all three are a counter rising monotonically from 0
+ * toward ``totalBytes``, polled on an interval, regardless of HTTP download or
+ * mmap page-in.
  *
- * Stability rule: ``stable`` stays ``false`` until we've observed at
- * least 3 samples spanning ≥3 seconds. That keeps the UI from flashing
- * wildly varying rates during the first tick or two when the denominator
- * is effectively zero.
+ * Stability: ``stable`` stays ``false`` until at least 3 samples spanning >=3s,
+ * so the UI doesn't flash wild rates during the first tick or two when the
+ * denominator is ~0.
  */
 
 import { useEffect, useRef, useState } from "react";
diff --git a/studio/frontend/src/features/chat/lib/friendly-names.ts b/studio/frontend/src/features/chat/lib/friendly-names.ts
index 503008f761..79744b3181 100644
--- a/studio/frontend/src/features/chat/lib/friendly-names.ts
+++ b/studio/frontend/src/features/chat/lib/friendly-names.ts
@@ -2,25 +2,17 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Friendly default names for auto-created OpenAI shell containers.
- * Used by the chat-adapter when the lazy-create path fires (Code pill
- * on, no thread container yet, user has set a non-default TTL). The
- * goal is a human-memorable label like "otter" or "harbor" instead of
- * "chat-abc12345" — the user can still rename via the Studio-side
- * alias map.
+ * Friendly default names for auto-created OpenAI shell containers, used by the
+ * chat-adapter's lazy-create path (Code pill on, no thread container, non-default
+ * TTL). Goal: a memorable label like "otter" instead of "chat-abc12345"; users
+ * can still rename via the Studio alias map.
  *
- * The list is curated to:
- *   - Be unambiguous, non-offensive nouns from natural categories
- *     (animals, plants, geography, materials, weather).
- *   - Avoid technical / political / brand words that might read as
- *     odd in a chat UI.
- *   - Stay reasonably small so the bundle cost is negligible (~200
- *     entries × ~7 bytes ≈ 1.5 KB).
+ * The list is curated to be unambiguous, non-offensive nouns from natural
+ * categories (animals, plants, geography, materials, weather), avoid
+ * technical/political/brand words, and stay small (~1.5 KB).
  *
- * Collisions are tolerated — the container's real unique key is its
- * ``cntr_*`` id, not its name. A short random hex suffix is appended
- * to make accidental same-name collisions visually distinct in the
- * picker list.
+ * Collisions are tolerated: the real unique key is the ``cntr_*`` id, not the
+ * name. A short random hex suffix keeps same-name picks visually distinct.
  */
 
 const WORDS = [
@@ -223,20 +215,15 @@ function randomHexSuffix(): string {
   ) {
     return crypto.randomUUID().replace(/-/g, "").slice(0, 4);
   }
-  // Older browser fallback. Math.random is fine here — this is a
-  // display suffix, not a security token.
+  // Older-browser fallback. Math.random is fine: display suffix, not a token.
   return Math.floor(Math.random() * 0xffff)
     .toString(16)
     .padStart(4, "0");
 }
 
 /**
- * Returns a single English-word name with a short random hex suffix.
- *
- * Example output: "kestrel-3f9c", "harbor-a012".
- *
- * The suffix keeps containers visually distinguishable in the picker
- * when the same word recurs across creations.
+ * Returns an English-word name with a short random hex suffix (e.g.
+ * "kestrel-3f9c"), so repeated words stay distinguishable in the picker.
  */
 export function pickFriendlyContainerName(): string {
   const word = WORDS[Math.floor(Math.random() * WORDS.length)] ?? "container";
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index 1e59960d07..8ff9385484 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -80,8 +80,8 @@ const MCP_PRESETS: readonly McpPreset[] = [
   },
 ] as const;
 
-// mcp_servers has no UNIQUE(url); dedupe by normalized URL so a preset
-// toggle reuses its row instead of creating duplicates.
+// mcp_servers has no UNIQUE(url); dedupe by normalized URL so a preset toggle
+// reuses its row instead of duplicating.
 function normalizeMcpUrl(url: string): string {
   return (url || "").trim().toLowerCase().replace(/\/+$/, "");
 }
@@ -110,8 +110,8 @@ export function McpComposerButton({
   const [pendingUrl, setPendingUrl] = useState<string | null>(null);
   const [hintKey, setHintKey] = useState<string | null>(null);
 
-  // Grey out only when a loaded model lacks tool support; with no model yet MCP
-  // can still be pre-selected, matching the other composer tools.
+  // Grey out only when a loaded model lacks tool support; with no model yet,
+  // MCP can still be pre-selected, like the other composer tools.
   const usable = !modelLoaded || supportsTools;
 
   const refresh = useCallback(async () => {
@@ -178,10 +178,9 @@ export function McpComposerButton({
     }
   }
 
-  // One dropdown row. Enabled rows get a green underlay and a tick that
-  // becomes an X on hover so a click removes them. A hint shows as a tooltip
-  // driven by row hover; the tooltip anchor is pointer-events-none so the whole
-  // row stays clickable (a Radix TooltipTrigger would swallow the select).
+  // One dropdown row. Enabled rows get a green underlay and a tick that becomes
+  // an X on hover (click removes). The hint tooltip anchor is pointer-events-none
+  // so the row stays clickable (a Radix TooltipTrigger would swallow the select).
   const renderRow = (opts: {
     key: string;
     label: string;
diff --git a/studio/frontend/src/features/chat/provider-capabilities.ts b/studio/frontend/src/features/chat/provider-capabilities.ts
index f550279826..07c953fecc 100644
--- a/studio/frontend/src/features/chat/provider-capabilities.ts
+++ b/studio/frontend/src/features/chat/provider-capabilities.ts
@@ -4,13 +4,10 @@
 /**
  * Per-provider sampling parameter capability matrix.
  *
- * Values are derived from each provider's published chat-completion docs as of
- * 2026-05. They describe which of our UI knobs map cleanly onto the provider's
- * request body; the panel hides params a provider does not accept so users
- * cannot dial a value that gets silently dropped or rejected.
- *
- * "Local" models (anything that is not an external provider) are represented by
- * a null capability — every knob renders for them.
+ * Derived from each provider's published chat-completion docs (2026-05). The
+ * panel hides params a provider does not accept so users cannot dial a value
+ * that gets silently dropped or rejected. "Local" models (non-external) use a
+ * null capability — every knob renders for them.
  */
 
 export interface ProviderCapabilities {
@@ -48,9 +45,8 @@ export type ExternalReasoningCapabilities = {
 };
 
 /**
- * Prefer a stored reasoning effort level that exists in ``effortLevels``,
- * mapping legacy "xhigh" to "max" when the model only exposes the latter
- * (Claude 4.6 adaptive thinking).
+ * Pick a stored reasoning effort level that exists in `effortLevels`, mapping
+ * legacy "xhigh" to "max" when only the latter is exposed (Claude 4.6).
  */
 export function clampReasoningEffortToLevels(
   preferred: ExternalReasoningCapabilities["reasoningEffortLevels"][number],
@@ -122,8 +118,8 @@ const EXTERNAL_MAX_OUTPUT_TOKENS_BY_MODEL: Array<{
 
 /**
  * Documented per-model output cap; unknown ids fall back to
- * `EXTERNAL_MAX_OUTPUT_TOKENS` (32k). OpenRouter ids are
- * `provider/model`; the prefix is stripped before matching.
+ * `EXTERNAL_MAX_OUTPUT_TOKENS` (32k). OpenRouter `provider/model` ids have the
+ * prefix stripped before matching.
  */
 export function getExternalMaxOutputTokens(
   providerType: string | null | undefined,
@@ -192,16 +188,14 @@ export function providerSupportsBuiltinWebSearch(
   modelId?: string | null | undefined,
   baseUrl?: string | null | undefined,
 ): boolean {
-  // Gemini ships grounded search via `tools: [{googleSearch: {}}]` on
-  // every chat-capable model. Most image-tier ids (`-image`,
-  // `nano-banana`) reject text-tool wiring because the
-  // responseModalities path is mutually exclusive with text tools, but
-  // Google explicitly documents Search grounding on the Gemini 3 image
-  // family (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview,
-  // nano-banana-pro). Allow Search on those; hide on older image ids.
-  // Custom Gemini OpenAI-compat proxies (non-Google bases) skip the
-  // native translator on the backend, so native tool envelopes never
-  // reach them -- hide the pill there.
+  // Gemini ships grounded search via `tools: [{googleSearch: {}}]` on every
+  // chat-capable model. Most image-tier ids reject text-tool wiring (the
+  // responseModalities path excludes text tools), but Google documents Search
+  // grounding on the Gemini 3 image family (gemini-3-pro-image-preview,
+  // gemini-3.1-flash-image-preview, nano-banana-pro), so allow it there and
+  // hide on older
+  // image ids. Custom Gemini OpenAI-compat proxies skip the backend's native
+  // translator, so native tool envelopes never reach them -- hide the pill.
   if (providerType === "gemini") {
     if (isGeminiCustomOpenAICompatBase(baseUrl)) return false;
     const normalized = modelId?.trim().toLowerCase() ?? "";
@@ -247,8 +241,8 @@ export function providerSupportsFastMode(
 ): boolean {
   if (providerType !== "anthropic") return false;
   if (!modelId) return false;
-  // Family boundary ("" or "-") required so IDs like "claude-opus-4-70"
-  // / "claude-opus-4-7b" do not match.
+  // Family boundary ("" or "-") required so IDs like "claude-opus-4-70" or
+  // "claude-opus-4-7b" do not match.
   return ANTHROPIC_FAST_MODE_MODEL_PREFIXES.some(
     (prefix) => modelId === prefix || modelId.startsWith(`${prefix}-`),
   );
@@ -269,15 +263,13 @@ export function providerSupportsFastMode(
  *     thread's stored `openaiCodeExecContainerId`. Documented at
  *       https://developers.openai.com/api/docs/guides/tools-shell
  *
- * Returns false for every other provider. The backend additionally
- * gates the OpenAI shell tool on `is_openai_cloud` so custom
- * OpenAI-compat servers (ollama / llama.cpp / vLLM) that also report
- * `provider_type="openai"` never receive the tool — but in practice
- * none of those catalogs surface the `gpt-5.5` ids anyway, so the
- * frontend prefix match is enough.
+ * Returns false for every other provider. The backend also gates the OpenAI
+ * shell tool on `is_openai_cloud` so custom OpenAI-compat servers reporting
+ * `provider_type="openai"` never receive it; in practice those catalogs don't
+ * surface the `gpt-5.5` ids, so the frontend prefix match suffices.
  *
- * v1 wires the tools themselves; file uploads (Anthropic
- * `container_upload` / OpenAI `input_file`) are a deliberate follow-up.
+ * v1 wires the tools only; file uploads (Anthropic `container_upload` / OpenAI
+ * `input_file`) are a deliberate follow-up.
  */
 const ANTHROPIC_CODE_EXECUTION_MODEL_PREFIXES = [
   "claude-opus-4-7",
@@ -286,29 +278,26 @@ const ANTHROPIC_CODE_EXECUTION_MODEL_PREFIXES = [
   "claude-opus-4-5",
   "claude-sonnet-4-5",
   "claude-haiku-4-5",
-  // Deprecated upstream but the registry still exposes the ids, so the
-  // pill should remain functional for users on those snapshots.
+  // Deprecated upstream but the registry still exposes these ids; keep the
+  // pill working for users on those snapshots.
   "claude-opus-4-1",
   "claude-opus-4",
   "claude-sonnet-4",
 ] as const;
 
-// OpenAI cloud shell-tool gating. Docs only explicitly demonstrate
-// gpt-5.5; gpt-5.5-pro is included because the family share the same
-// /v1/responses contract. `gpt-5.5-pro` is checked first so the prefix
-// match doesn't collide with a hypothetical `gpt-5.5-turbo` etc.
+// OpenAI cloud shell-tool gating. Docs only show gpt-5.5; gpt-5.5-pro shares
+// the same /v1/responses contract. `gpt-5.5-pro` is checked first so the prefix
+// match doesn't collide with e.g. a hypothetical `gpt-5.5-turbo`.
 const OPENAI_CODE_EXECUTION_MODEL_PREFIXES = [
   "gpt-5.5-pro",
   "gpt-5.5",
 ] as const;
 
 /**
- * Strict check that a provider configuration points at OpenAI's
- * managed cloud (api.openai.com) or Azure OpenAI Foundry
- * (*.openai.azure.com), as opposed to a custom OpenAI-compat backend
- * (ollama / llama.cpp / vLLM / generic "custom" preset). The shell and
- * image-generation tools only exist on cloud backends; sending them to
- * anything else 400s the request. Mirror of the backend's
+ * Strict check that a provider config points at OpenAI managed cloud
+ * (api.openai.com) or Azure OpenAI Foundry (*.openai.azure.com), not a custom
+ * OpenAI-compat backend. The shell and image-generation tools exist only on
+ * cloud backends; sending them elsewhere 400s. Mirrors the backend's
  * `_is_openai_family_cloud` host check.
  */
 function isOpenAICloudBaseUrl(baseUrl: string | null | undefined): boolean {
@@ -357,16 +346,13 @@ export function providerSupportsBuiltinCodeExecution(
 }
 
 /**
- * Whether the selected external provider/model exposes OpenAI's
- * Responses-API server-side image_generation tool. Lit on for OpenAI
- * cloud (`api.openai.com`) when the picked model is a Responses-API
- * family id (gpt-5.x today). The backend additionally gates on
- * `is_openai_cloud`; mirror that here so the pill is hidden on custom
- * OpenAI-compat backends (ollama / llama.cpp / vLLM) that report
- * `provider_type="openai"` but would 400 on a `{type:"image_generation"}`
- * tool. See backend/core/inference/external_provider.py near line 2770
- * for the dispatch and backend/tests/test_openai_image_generation.py
- * for the round-trip coverage.
+ * Whether the selected provider/model exposes OpenAI's Responses-API
+ * image_generation tool. On for OpenAI cloud (`api.openai.com`) with a
+ * Responses-API family id (gpt-5.x). Mirrors the backend's `is_openai_cloud`
+ * gate so the pill hides on custom OpenAI-compat backends reporting
+ * `provider_type="openai"` that would 400 on a `{type:"image_generation"}` tool.
+ * See backend/core/inference/external_provider.py (~line 2770) for dispatch and
+ * backend/tests/test_openai_image_generation.py for round-trip coverage.
  */
 const OPENAI_IMAGE_GENERATION_MODEL_PREFIXES = [
   "gpt-5.5-pro",
@@ -394,14 +380,11 @@ export function providerSupportsBuiltinImageGeneration(
     );
   }
   if (providerType === "gemini") {
-    // Gemini's Nano Banana image-output ids carry either `-image` (e.g.
-    // `gemini-2.5-flash-image`, `gemini-3.1-flash-image-preview`) or the
-    // `nano-banana` alias (`nano-banana-pro-preview`). The backend flips
-    // generationConfig.responseModalities to ["TEXT", "IMAGE"] when one
-    // is picked, and translates inlineData parts into the same image_b64
-    // tool_end envelope the OpenAI path emits so the chat UI renders the
-    // picture inline. Custom Gemini OpenAI-compat proxies skip the
-    // native translator on the backend, so hide the image pill there.
+    // Gemini Nano Banana image-output ids carry `-image` or the `nano-banana`
+    // alias. The backend flips responseModalities to ["TEXT", "IMAGE"] and maps
+    // inlineData parts into the same image_b64 tool_end envelope as the OpenAI
+    // path so the UI renders inline. Custom Gemini OpenAI-compat proxies skip
+    // the native translator, so hide the image pill there.
     // See https://ai.google.dev/gemini-api/docs/image-generation.
     if (isGeminiCustomOpenAICompatBase(baseUrl)) return false;
     return normalized.includes("-image") || normalized.includes("nano-banana");
@@ -420,13 +403,11 @@ function isGeminiImageModel(modelId: string): boolean {
 }
 
 /**
- * Whether the saved Gemini connection points at a custom
- * OpenAI-compatible gateway (any non-Google host). The backend
- * `_is_openai_compatible` mirrors this to route those connections
- * through `/chat/completions` instead of the native translator, so
- * native Gemini tool envelopes (googleSearch, codeExecution,
- * responseModalities) never reach them. Hide the corresponding
- * Studio pills here so the request, builder, and UI agree.
+ * Whether the saved Gemini connection points at a custom OpenAI-compat gateway
+ * (any non-Google host). The backend `_is_openai_compatible` routes these
+ * through `/chat/completions` instead of the native translator, so native Gemini
+ * tool envelopes never reach them. Hide the matching Studio pills here so the
+ * request, builder, and UI agree.
  */
 export function isGeminiCustomOpenAICompatBase(
   baseUrl: string | null | undefined,
@@ -458,17 +439,13 @@ function geminiImageModelAllowsGoogleSearch(modelId: string): boolean {
 }
 
 /**
- * Per-provider minimum on the outbound max_tokens. Kimi's docs require
- * `max_tokens >= 16000` whenever a thinking model is in use so the
- * reasoning_content and final answer both fit in the budget — anything
- * lower truncates the response mid-stream. Other providers don't have a
- * documented floor, so they fall through to the generic min of 64 in
- * the slider.
+ * Per-provider minimum on the outbound max_tokens. Kimi requires
+ * `max_tokens >= 16000` for thinking models so reasoning_content and the answer
+ * both fit; lower truncates mid-stream. Others fall through to the generic 64.
  *
- * The chat-adapter resolves the effective floor on send and bumps the
- * outbound max_tokens up to this value if the user's stored maxTokens
- * sits below it. The settings panel reflects the same floor as the
- * slider min so the displayed value never drifts from what's sent.
+ * The chat-adapter resolves the floor on send and bumps maxTokens up to it if
+ * the stored value is below; the settings slider min reflects the same floor so
+ * the displayed value never drifts from what's sent.
  */
 const EXTERNAL_MIN_OUTPUT_TOKENS_BY_PROVIDER: Record<string, number> = {
   kimi: 16000,
@@ -528,11 +505,11 @@ const PROVIDER_CAPABILITIES: Record<string, ProviderCapabilities> = {
     presencePenalty: false,
   },
   mistral: OPENAI_COMPAT_BASE,
-  // Gemini's native generationConfig accepts temperature, topP, topK and
-  // presencePenalty (plus a separate frequencyPenalty we do not surface
-  // today). minP and repetitionPenalty are not part of the contract --
-  // see https://ai.google.dev/api/rest/v1beta/GenerationConfig. Backend
-  // request shaping lives in _stream_gemini in
+  // Gemini's generationConfig accepts temperature, topP, topK and
+  // presencePenalty (plus a frequencyPenalty we don't surface). minP and
+  // repetitionPenalty aren't part of the contract --
+  // see https://ai.google.dev/api/rest/v1beta/GenerationConfig. Backend shaping
+  // lives in _stream_gemini in
   // studio/backend/core/inference/external_provider.py.
   gemini: {
     temperature: true,
@@ -542,11 +519,9 @@ const PROVIDER_CAPABILITIES: Record<string, ProviderCapabilities> = {
     repetitionPenalty: false,
     presencePenalty: true,
   },
-  // Kimi k2.5/k2.6 are reasoning-class — the API locks temperature and
-  // top_p to fixed defaults and 400s on any other value:
-  //   "invalid temperature: only 1 is allowed for this model".
-  // Hide both sliders so the user is not offered knobs the model
-  // silently overrides. Backend additionally strips these fields via
+  // Kimi k2.5/k2.6 are reasoning-class — the API locks temperature and top_p to
+  // fixed defaults and 400s on any other value ("invalid temperature: only 1 is
+  // allowed for this model"). Hide both sliders. Backend also strips these via
   // PROVIDER_REGISTRY['kimi']['body_omit'].
   kimi: {
     temperature: false,
@@ -570,9 +545,9 @@ const PROVIDER_CAPABILITIES: Record<string, ProviderCapabilities> = {
   // OpenRouter silently drops params the target model does not support, so we
   // surface every knob and let the gateway handle the per-model fan-out.
   openrouter: ALL_SUPPORTED,
-  // Local OpenAI-compatible connections are proxied through the OpenAI backend
-  // path, but vLLM/Ollama/llama.cpp users often want top_k / min_p /
-  // repetition controls, so be permissive.
+  // Local OpenAI-compat connections go through the OpenAI backend path, but
+  // vLLM/Ollama/llama.cpp users often want top_k/min_p/repetition controls, so
+  // be permissive.
   custom: ALL_SUPPORTED,
   vllm: ALL_SUPPORTED,
   ollama: ALL_SUPPORTED,
@@ -733,11 +708,11 @@ function withReasoningEffortStyle(caps: ReasoningCaps): ExternalReasoningCapabil
 }
 
 function resolveKimiReasoningCapabilities(modelId: string): ExternalReasoningCapabilities {
-  // Kimi exposes a boolean thinking toggle rather than an effort scale.
-  //   - kimi-k2.6:        thinking enabled by default, toggleable
-  //                       via extra_body: {thinking: {type: enabled|disabled}}
-  //   - kimi-k2-thinking: thinking always on, no off switch
-  //   - kimi-k2.5 (and anything else): no thinking
+  // Kimi exposes a boolean thinking toggle, not an effort scale.
+  //   - kimi-k2.6:        on by default, toggleable via
+  //                       extra_body: {thinking: {type: enabled|disabled}}
+  //   - kimi-k2-thinking: always on, no off switch
+  //   - kimi-k2.5 (and others): no thinking
   if (modelId === "kimi-k2-thinking") {
     return withEnableThinkingStyle({
       supportsReasoning: true,
@@ -754,16 +729,13 @@ function resolveKimiReasoningCapabilities(modelId: string): ExternalReasoningCap
 }
 
 // Gemini's thinking ladder.
-//   - Gemini 3.x (3 / 3.1 / 3.5, Pro + Flash + Flash-Lite) and the
-//     gemini-pro-latest / gemini-flash-latest aliases use the new
-//     `thinkingConfig.thinkingLevel` string field (LOW/MEDIUM/HIGH/
-//     MINIMAL). Pro tier rejects MINIMAL.
-//   - Gemini 2.5 Flash + 2.5 Pro stay on the integer
-//     `thinkingConfig.thinkingBudget` (0=off on Flash, -1=dynamic,
-//     N>0=cap; Pro rejects 0).
-//   - 2.5 Flash-Lite: no native thinking surfaced; leave it off.
-//   - Image-tier ids (`*-image*`, `nano-banana-pro-preview`): image
-//     generation path -- no reasoning controls.
+//   - Gemini 3.x (Pro + Flash + Flash-Lite) and the gemini-pro-latest /
+//     gemini-flash-latest aliases use the string `thinkingConfig.thinkingLevel`
+//     (LOW/MEDIUM/HIGH/MINIMAL); Pro tier rejects MINIMAL.
+//   - Gemini 2.5 Flash + 2.5 Pro use the integer `thinkingConfig.thinkingBudget`
+//     (0=off on Flash, -1=dynamic, N>0=cap; Pro rejects 0).
+//   - 2.5 Flash-Lite: no native thinking surfaced; leave off.
+//   - Image-tier ids: image generation path -- no reasoning controls.
 const GEMINI3_PRO_PREFIXES = [
   "gemini-3.5-pro",
   "gemini-3.1-pro",
@@ -795,9 +767,8 @@ function resolveGeminiReasoningCapabilities(
     // Image generation; no thinking knob.
     return withEnableThinkingStyle();
   }
-  // Gemini 2.5 Flash-Lite supports `thinkingBudget` with `0` = off and
-  // a positive range starting at 512 (the backend maps "minimal" to
-  // that floor at external_provider._stream_gemini). Check this branch
+  // Gemini 2.5 Flash-Lite: `thinkingBudget` 0 = off, positive range from 512
+  // (backend maps "minimal" to that floor in _stream_gemini). Check this branch
   // BEFORE the broader `gemini-2.5-flash` prefix.
   // https://ai.google.dev/gemini-api/docs/thinking
   if (m.startsWith("gemini-2.5-flash-lite")) {
@@ -815,10 +786,10 @@ function resolveGeminiReasoningCapabilities(
     });
   }
   if (GEMINI3_PRO_PREFIXES.some((p) => m.startsWith(p))) {
-    // Gemini 3.x Pro: thinkingLevel supports low/medium/high per
+    // Gemini 3.x Pro: thinkingLevel low/medium/high; cannot fully disable, and
+    // "minimal" is rejected on Pro. Refs:
     // https://ai.google.dev/gemini-api/docs/thinking and
     // https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-pro.
-    // Cannot fully disable thinking; "minimal" is rejected on Pro.
     return withReasoningEffortStyle({
       supportsReasoning: true,
       supportsReasoningOff: false,
@@ -826,8 +797,8 @@ function resolveGeminiReasoningCapabilities(
     });
   }
   if (GEMINI3_FLASH_PREFIXES.some((p) => m.startsWith(p))) {
-    // Gemini 3 Flash: thinkingLevel minimal/low/medium/high. Minimal
-    // is the closest to "off" Google offers on Gemini 3.
+    // Gemini 3 Flash: thinkingLevel minimal/low/medium/high. Minimal is the
+    // closest to "off" Google offers on Gemini 3.
     return withReasoningEffortStyle({
       supportsReasoning: true,
       supportsReasoningOff: false,
@@ -840,9 +811,9 @@ function resolveGeminiReasoningCapabilities(
     });
   }
   if (GEMINI25_PRO_PREFIXES.some((p) => m.startsWith(p))) {
-    // Gemini 2.5 Pro: thinkingBudget cannot be 0 (API rejects with
-    // "only works in thinking mode"); backend coerces to a small
-    // positive budget. The picker still hides the off switch.
+    // Gemini 2.5 Pro: thinkingBudget cannot be 0 (API rejects "only works in
+    // thinking mode"); backend coerces to a small positive budget. Hide the off
+    // switch in the picker.
     return withReasoningEffortStyle({
       supportsReasoning: true,
       supportsReasoningOff: false,
@@ -907,9 +878,8 @@ function resolveConnectionLevelReasoning(
 }
 
 /**
- * resolve external-model thinking capabilities.
- * provider-specific matching lives in the OpenAI/Anthropic resolvers.
- * other providers default to no reasoning controls.
+ * Resolve external-model thinking capabilities. Provider-specific matching lives
+ * in the per-provider resolvers; others default to no reasoning controls.
  */
 export function getExternalReasoningCapabilities(
   providerType: string | null | undefined,
@@ -951,10 +921,9 @@ export function getExternalReasoningCapabilities(
   const isMistralProvider = normalizedProvider === "mistral";
   const isOpenRouterProvider = normalizedProvider === "openrouter";
   if (isOpenRouterProvider) {
-    // OpenRouter's unified `reasoning` parameter is accepted on every
-    // chat-completion request; the gateway silently no-ops for models
-    // that don't reason. Mandatory-reasoning ids are handled by the
-    // early guard above; everything else exposes a toggleable control.
+    // OpenRouter's unified `reasoning` param is accepted on every request; the
+    // gateway no-ops for non-reasoning models. Mandatory-reasoning ids are
+    // handled by the early guard; everything else gets a toggleable control.
     return {
       supportsReasoning: true,
       reasoningStyle: "enable_thinking",
@@ -966,10 +935,9 @@ export function getExternalReasoningCapabilities(
   if (isKimiProvider) return resolveKimiReasoningCapabilities(modelForMatching);
   if (isMistralProvider) return resolveMistralReasoningCapabilities(modelForMatching);
   if (normalizedProvider === "gemini") {
-    // Custom Gemini OAI-compat gateways (LiteLLM, proxies) route
-    // through /chat/completions which drops the Gemini-native
-    // thinkingConfig payload. Hide the native thinking ladder so the
-    // UI does not advertise a control the backend cannot honor.
+    // Custom Gemini OAI-compat gateways route through /chat/completions, which
+    // drops the native thinkingConfig payload. Hide the native thinking ladder
+    // so the UI doesn't advertise a control the backend can't honor.
     if (isGeminiCustomOpenAICompatBase(options?.baseUrl)) {
       return withEnableThinkingStyle();
     }
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 5e5780ec2a..8d9e5a10e3 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -194,9 +194,8 @@ class PDFAttachmentAdapter implements AttachmentAdapter {
 
 class TextAttachmentAdapter implements AttachmentAdapter {
   // MIME is unreliable for source files, so also match by extension
-  // (assistant-ui's fileMatchesAccept supports ".ext" entries). Covers
-  // svg, code, config and other plain-text formats; html keeps its own
-  // adapter below.
+  // (assistant-ui's fileMatchesAccept supports ".ext" entries). Covers svg, code,
+  // config and other plain-text formats; html keeps its own adapter below.
   accept = [
     "text/plain,text/markdown,text/csv,text/xml,text/json,text/css",
     "application/json,application/xml,image/svg+xml",
@@ -258,9 +257,7 @@ class HtmlAttachmentAdapter implements AttachmentAdapter {
 
   async send(attachment: PendingAttachment): Promise<CompleteAttachment> {
     const html = await attachment.file.text();
-    // Strip HTML tags to extract readable text
     const doc = new DOMParser().parseFromString(html, "text/html");
-    // Remove script and style elements
     for (const el of doc.querySelectorAll("script, style")) el.remove();
     const text = (doc.body.textContent ?? "").replace(/\s+/g, " ").trim();
     return {
@@ -584,9 +581,9 @@ export async function ensureThreadRecord({
   try {
     await saveStoredChatThread(record);
   } catch (error) {
-    // assistant-ui can issue overlapping first-message persistence calls.
-    // If another call created the same thread while this one was waiting,
-    // treat initialization as successful and let the message write continue.
+    // assistant-ui can issue overlapping first-message persistence calls. If
+    // another call created the same thread while this one waited, treat init as
+    // successful and let the message write continue.
     const existingAfterRace = await listStoredChatThreads({
       includeArchived: true,
     }).catch(() => []);
@@ -866,7 +863,7 @@ function useStudioRuntimeAdapters(
           return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
         });
 
-        // Restore context usage from last assistant message if model matches
+        // Restore context usage from last assistant message if model matches.
         const lastAssistant = [...msgs]
           .reverse()
           .find((m) => m.role === "assistant");
@@ -882,14 +879,14 @@ function useStudioRuntimeAdapters(
             }
           | undefined;
         const store = useChatRuntimeStore.getState();
-        // Window check applies only when a local GGUF window is known;
-        // external providers have ggufContextLength === null.
+        // Window check applies only when a local GGUF window is known; external
+        // providers have ggufContextLength === null.
         const withinLocalLimit =
           !store.ggufContextLength ||
           (savedUsage?.totalTokens ?? 0) <= store.ggufContextLength;
-        // Legacy unscoped usage (no modelId) is only trusted when a
-        // known local window bounds the totals, so we can't misattribute
-        // an old local turn to a newly-selected external provider.
+        // Legacy unscoped usage (no modelId) is trusted only when a known local
+        // window bounds the totals, so an old local turn can't be misattributed
+        // to a newly-selected external provider.
         const modelMatches = savedUsage?.modelId
           ? savedUsage.modelId === store.params.checkpoint
           : typeof store.ggufContextLength === "number" &&
@@ -898,12 +895,10 @@ function useStudioRuntimeAdapters(
           store.setContextUsage(savedUsage);
         }
 
-        // If any message has a stored parentId, reconstruct the tree
-        // so retries/regenerations load as branches instead of being
-        // unrolled into a flat list.  For mixed legacy/new threads
-        // (old messages without parentId + new messages with), infer
-        // sequential parents for old messages to preserve the chain.
-        // Fall back to fromArray for fully legacy threads.
+        // If any message has a stored parentId, reconstruct the tree so
+        // retries/regenerations load as branches rather than a flat list. For
+        // mixed legacy/new threads, infer sequential parents for old messages to
+        // preserve the chain. Fall back to fromArray for fully legacy threads.
         const hasParentIds = msgs.some((m) => m.parentId != null);
         if (hasParentIds) {
           let previousId: string | null = null;
@@ -931,7 +926,7 @@ function useStudioRuntimeAdapters(
             return;
           }
           // Keep single-chat runtime state in sync once a new chat is first
-          // persisted. Compare panes intentionally do not write global activeThreadId.
+          // persisted. Compare panes intentionally don't write global activeThreadId.
           if (modelType === "base" && !pairId) {
             const store = useChatRuntimeStore.getState();
             if (store.activeThreadId !== remoteId) {
@@ -1071,8 +1066,8 @@ function ThreadNewChatSwitch({
     if (isLoading) {
       return;
     }
-    // Switch to a fresh local thread without persisting it yet.
-    // Persistence still happens on first message append.
+    // Switch to a fresh local thread without persisting it yet; persistence
+    // still happens on first message append.
     void aui.threads().switchToNewThread();
     useChatRuntimeStore.getState().setActiveThreadId(null);
   }, [aui, isLoading, nonce]);
@@ -1099,8 +1094,8 @@ function ActiveThreadSync({
 }
 
 // Exposes the current thread's cancelRun() via the shared store so external
-// surfaces (e.g. the sidebar trash button) can stop an in-flight stream
-// before deleting the thread — mirroring the Stop → Trash sequence.
+// surfaces (e.g. the sidebar trash button) can stop an in-flight stream before
+// deleting the thread, mirroring the Stop -> Trash sequence.
 function CancelRegistrar(): ReactElement | null {
   const aui = useAui();
   const mainThreadId = useAuiState(({ threads }) => threads.mainThreadId);
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 1717152ba0..e54111862c 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -102,7 +102,7 @@ export interface CompareHandle {
 const IMAGE_ACCEPT = "image/jpeg,image/png,image/webp,image/gif";
 const MAX_IMAGE_SIZE = 20 * 1024 * 1024;
 
-// Inlined to avoid a new icon dependency. Kept in sync with the main composer.
+// Inlined to avoid a new icon dep. Kept in sync with the main composer.
 const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
   <svg
     className={className}
@@ -149,9 +149,9 @@ function isNativeComposing(event: Event) {
   return "isComposing" in event && (event as InputEvent).isComposing === true;
 }
 
-// Mirrors the threshold in thread.tsx — see the comment there. Chrome on
-// Windows-over-WSL (issue #5546) never fires `compositionend` after the
-// IME commit, so the compose flag would otherwise stay true forever.
+// Mirrors the threshold in thread.tsx. Chrome on Windows-over-WSL (#5546)
+// never fires `compositionend` after IME commit, so the compose flag would
+// otherwise stay true forever.
 const IME_STUCK_TIMEOUT_MS = 2500;
 
 function fileToBase64DataURL(file: File): Promise<string> {
@@ -187,8 +187,8 @@ function formatReasoningDisabledLabel(
   modelId?: string,
 ): string {
   const normalized = modelId?.trim().toLowerCase() ?? "";
-  // Magistral keeps the "none" wire value, but UX should present this floor
-  // as "Medium" rather than a disabled state label.
+  // Magistral keeps the "none" wire value, but UX presents this floor as
+  // "Medium" rather than a disabled-state label.
   if (normalized.includes("magistral-medium-latest")) return "Medium";
   return supportsReasoningOff && isExternalOpenAIReasoning ? "None" : "Off";
 }
@@ -374,7 +374,7 @@ type CompareModelSelection = {
   ggufVariant?: string;
 };
 
-// Tool icon plus an X overlay the CSS reveals on hover when the pill is active.
+// Tool icon plus an X overlay CSS reveals on hover when the pill is active.
 function PillGlyph({ children }: { children: ReactNode }) {
   return (
     <span className="composer-pill-glyph">
@@ -396,8 +396,7 @@ export function SharedComposer({
   onExitCompare?: () => void;
 }): ReactElement {
   const navigate = useNavigate();
-  // Exit compare. Uses the parent's restore handler, or a fresh chat when
-  // compare was opened by direct URL.
+  // Exit compare: parent's restore handler, or fresh chat if opened by URL.
   const handleExitCompare = useCallback(() => {
     if (onExitCompare) {
       onExitCompare();
@@ -472,7 +471,7 @@ export function SharedComposer({
   const setMcpEnabledForChat = useChatRuntimeStore(
     (s) => s.setMcpEnabledForChat,
   );
-  // Three most recently updated projects for the quick-access submenu.
+  // Three most recently updated projects for the quick-access submenu
   const { projects } = useChatProjects();
   const recentProjects = [...projects]
     .sort((a, b) => b.updatedAt - a.updatedAt)
@@ -507,11 +506,10 @@ export function SharedComposer({
     modelLoaded,
   });
   const isCompareMode = Boolean(model1?.id || model2?.id);
-  // Attach-time gate. Compare mode defers to send: the catalog can lag
-  // behind a model's real capabilities (e.g., a GGUF whose mmproj
-  // arrives after the catalog snapshot), and we only sync the models[]
-  // entry after ensureModelLoaded runs at send time. Single mode uses
-  // the loaded model's runtime capability.
+  // Attach-time gate. Compare mode defers to send: the catalog can lag a
+  // model's real capabilities (e.g. a GGUF whose mmproj arrives after the
+  // snapshot), and models[] only syncs after ensureModelLoaded at send time.
+  // Single mode uses the loaded model's runtime capability.
   const attachUnavailableReason = isCompareMode ? null : imageUnavailableReason;
   const effectiveExternalModelId =
     selectedExternalProvider?.providerType === "openrouter" &&
@@ -547,11 +545,10 @@ export function SharedComposer({
   const reasoningLockedOn =
     effectiveSupportsReasoning &&
     (effectiveReasoningAlwaysOn || !effectiveSupportsReasoningOff);
-  // Kimi's $web_search builtin mandates thinking=disabled per the docs at
-  // https://platform.kimi.ai/docs/guide/use-web-search. Both pills stay
-  // clickable for Kimi, but turning one on flips the other off — the
-  // click handlers below enforce this mutual exclusion so the visible
-  // state always matches what the backend actually sends.
+  // Kimi's $web_search builtin mandates thinking=disabled
+  // (https://platform.kimi.ai/docs/guide/use-web-search). Both pills stay
+  // clickable, but turning one on flips the other off; the click handlers
+  // below enforce this so the visible state matches what the backend sends.
   const isKimiExternal = selectedExternalProvider?.providerType === "kimi";
   const effectiveReasoningEnabled = reasoningLockedOn ? true : reasoningEnabled;
   const effectiveReasoningVisualEnabled =
@@ -563,15 +560,13 @@ export function SharedComposer({
   const thinkingActiveLook = isEffort
     ? reasoningLockedOn || (effectiveReasoningVisualEnabled && !reasoningDisabled)
     : reasoningLockedOn || (effectiveReasoningEnabled && !reasoningDisabled);
-  // Two-pill gating: Search pill lights up when the runtime has either
-  // a local tool runtime (supportsTools, gives us our Code/python + local
-  // web_search) OR a server-side web_search the provider runs for us
-  // (supportsBuiltinWebSearch, currently OpenAI / Anthropic / OpenRouter
-  // / Kimi). Code pill lights up on the local runtime OR when Anthropic
-  // is selected with a model that accepts the server-side
-  // code_execution_20250825 tool — see
-  // providerSupportsBuiltinCodeExecution. Anthropic is the only external
-  // provider that ships a code-execution tool today.
+  // Two-pill gating: Search lights up on a local tool runtime (supportsTools:
+  // Code/python + local web_search) OR a provider-run server-side web_search
+  // (supportsBuiltinWebSearch: OpenAI/Anthropic/OpenRouter/Kimi). Code lights
+  // up on the local runtime OR Anthropic with a model accepting the
+  // server-side code_execution_20250825 tool (see
+  // providerSupportsBuiltinCodeExecution). Anthropic is the only external
+  // provider shipping a code-execution tool today.
   const supportsBuiltinCodeExecution = providerSupportsBuiltinCodeExecution(
     selectedExternalProvider?.providerType,
     effectiveExternalModelId,
@@ -586,24 +581,22 @@ export function SharedComposer({
     selectedExternalProvider?.providerType,
   );
   // Gemini rejects codeExecution alongside image modalities. Search is
-  // blocked on older Gemini image ids but allowed on Gemini 3 image
-  // models -- supportsBuiltinWebSearch already encodes the per-model
-  // allowance, so we only disable Code unconditionally in Gemini
-  // image mode.
+  // blocked on older Gemini image ids but allowed on Gemini 3 image models
+  // (supportsBuiltinWebSearch encodes the per-model allowance), so we only
+  // disable Code unconditionally in Gemini image mode.
   const isExternalGemini = selectedExternalProvider?.providerType === "gemini";
   const imageDisabled = !modelLoaded || !supportsBuiltinImageGeneration;
   const imageModeDisablesCode =
     isExternalGemini && imageToolsEnabled && !imageDisabled;
   // Image-tier Gemini models always reject codeExecution and reject
-  // web_search on older ids (Gemini 3.x Pro/Flash allow it -- encoded
-  // in supportsBuiltinWebSearch). Don't let the local `supportsTools`
-  // runtime flag re-enable a pill the Gemini backend will silently
-  // drop. Detect "external provider is Gemini AND model is image-tier"
-  // and gate strictly on the provider builtin support.
+  // web_search on older ids (Gemini 3.x Pro/Flash allow it, encoded in
+  // supportsBuiltinWebSearch). Don't let local `supportsTools` re-enable a
+  // pill the Gemini backend silently drops: detect image-tier Gemini and
+  // gate strictly on provider builtin support.
   const isGeminiImageTier =
     isExternalGemini && supportsBuiltinImageGeneration;
   // Disable only when a loaded model lacks the capability; with no model the
-  // tool can still be pre-selected and reflected, matching the + menu.
+  // tool can still be pre-selected, matching the + menu.
   const searchDisabled =
     modelLoaded &&
     (isGeminiImageTier
@@ -615,14 +608,14 @@ export function SharedComposer({
         ? true
         : !(supportsTools || supportsBuiltinCodeExecution))) ||
     imageModeDisablesCode;
-  // Images pill is only ever lit on OpenAI cloud's Responses-API models
-  // and Gemini Nano Banana family. No local tool runtime fallback.
+  // Images pill lights only on OpenAI cloud Responses-API models and the
+  // Gemini Nano Banana family. No local tool runtime fallback.
   const showImagePill = supportsBuiltinImageGeneration;
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
   const showWebFetchPill = supportsBuiltinWebFetch;
-  // With more than 4 pills showing, collapse them to icons only to cut clutter.
-  // Compare, Search and Code always show; the rest are conditional.
+  // Above 4 pills, collapse to icons only to cut clutter. Compare, Search and
+  // Code always show; the rest are conditional.
   const pillsCompact =
     3 +
       (showImagePill ? 1 : 0) +
@@ -630,8 +623,8 @@ export function SharedComposer({
       (artifactsEnabled ? 1 : 0) +
       (mcpEnabledForChat ? 1 : 0) >
     4;
-  // Backwards-compatible alias for any other call site that may still
-  // reference `toolsDisabled` (rare; both pills used it before).
+  // Backwards-compatible alias for call sites still referencing
+  // `toolsDisabled` (rare; both pills used it before).
   const toolsDisabled = codeDisabled;
   const setPendingAudioStore = useChatRuntimeStore((s) => s.setPendingAudio);
   const clearPendingAudioStore = useChatRuntimeStore(
@@ -753,11 +746,11 @@ export function SharedComposer({
     const isGeneralizedCompare =
       hasCompareHandles && Boolean(model1?.id && model2?.id);
 
-    // Generalized compare requires both panes to have a model. A
-    // half-selected send either races to an empty bubble with bogus
-    // tok/s (#5569) or leaves the empty pane with a dangling prompt.
-    // hasCompareHandles is true only in GeneralCompareContent, so
-    // LoraCompare and single-pane chats are unaffected.
+    // Generalized compare requires both panes to have a model. A half-
+    // selected send either races to an empty bubble with bogus tok/s (#5569)
+    // or leaves the empty pane with a dangling prompt. hasCompareHandles is
+    // true only in GeneralCompareContent, so LoraCompare and single-pane
+    // chats are unaffected.
     if (hasCompareHandles && !isGeneralizedCompare) {
       toast.error("Pick a model in each pane to compare", {
         description:
@@ -771,10 +764,10 @@ export function SharedComposer({
       !isGeneralizedCompare &&
       imageUnavailableReason
     ) {
-      // Single mode: the loaded model's runtime capability is known
-      // here. Compare mode defers — each ensureModelLoaded below sets
-      // loadedIsMultimodal for its side, and the chat-adapter's
-      // pre-stream gate runs per-side against that fresh state.
+      // Single mode: the loaded model's runtime capability is known here.
+      // Compare mode defers: each ensureModelLoaded sets loadedIsMultimodal
+      // for its side, and the chat-adapter's pre-stream gate runs per-side
+      // against that fresh state.
       toast.error(imageUnavailableReason);
       return;
     }
@@ -869,10 +862,9 @@ export function SharedComposer({
           supportsTools: resp.supports_tools ?? false,
           loadedIsMultimodal: isMultimodalResponse(resp),
         });
-        // Sync the models[] entry with the load response so the
-        // attach/send gates read fresh capabilities. /api/models/list
-        // can lag behind a model's actual state (e.g., a GGUF whose
-        // mmproj was downloaded after the catalog snapshot).
+        // Sync the models[] entry with the load response so attach/send gates
+        // read fresh capabilities. /api/models/list can lag a model's actual
+        // state (e.g. a GGUF whose mmproj arrived after the snapshot).
         const currentModels = useChatRuntimeStore.getState().models;
         const idx = currentModels.findIndex((m) => m.id === sel.id);
         const synced = {
@@ -982,13 +974,12 @@ export function SharedComposer({
   const busy = running || comparing;
 
   function onKeyDown(e: KeyboardEvent) {
-    // IME composition (Japanese/Chinese/Korean): Enter commits the candidate.
-    // Don't hijack it. See issue #5318. Re-pin composingRef in case the stuck
-    // watchdog (#5546) cleared it during a long candidate-window pause; this
-    // keeps a follow-up click-Send from submitting preedit text. Re-arm the
-    // watchdog on the same path — without it the WSL+Chrome no-compositionend
-    // case would leave composingRef pinned forever after an IME keypress and
-    // re-lock Send.
+    // IME composition (JP/CN/KR): Enter commits the candidate, don't hijack it
+    // (#5318). Re-pin composingRef in case the stuck watchdog (#5546) cleared
+    // it during a long candidate-window pause, so a follow-up click-Send won't
+    // submit preedit text. Re-arm the watchdog on the same path; without it the
+    // WSL+Chrome no-compositionend case pins composingRef forever after an IME
+    // keypress and re-locks Send.
     if (e.nativeEvent.isComposing || e.keyCode === 229) {
       composingRef.current = true;
       refreshStuckImeTimer();
@@ -1019,8 +1010,8 @@ export function SharedComposer({
       }}
       onDragLeave={() => setDragging(false)}
       onDrop={(e) => {
-        // Phase 1 native model drops own Tauri local-path drops. Restore browser
-        // attachment drops in Tauri when Phase 1d adds attachment-token bridging.
+        // Phase 1 native model drops own Tauri local-path drops. Restore
+        // browser attachment drops in Tauri once Phase 1d adds token bridging.
         if (isTauri) return;
         e.preventDefault();
         setDragging(false);
@@ -1071,11 +1062,11 @@ export function SharedComposer({
         value={text}
         onChange={(e) => {
           // ALWAYS mirror the DOM value into React state, even during IME
-          // composition. The controlled `value` prop must match the DOM at
-          // all times, otherwise any unrelated parent re-render reconciles
-          // the textarea back to the stored value mid-composition — wiping
-          // the IME preedit AND prior committed text (e.g. Tab cycling
-          // candidates erases earlier words). Issue #5318.
+          // composition: the controlled `value` must match the DOM at all
+          // times, else an unrelated parent re-render reconciles the textarea
+          // back to the stored value mid-composition, wiping the IME preedit
+          // AND prior committed text (e.g. Tab-cycling candidates erases
+          // earlier words). #5318.
           setCompositionState(isNativeComposing(e.nativeEvent));
           setText(e.target.value);
         }}
@@ -1093,8 +1084,8 @@ export function SharedComposer({
         placeholder="Send to both models..."
         className="composer-input"
         rows={1}
-        // dir="auto" auto-detects RTL (Arabic / Hebrew / Persian / Urdu)
-        // from the first strong character; no effect on LTR scripts.
+        // dir="auto" detects RTL (Arabic/Hebrew/Persian/Urdu) from the first
+        // strong character; no effect on LTR scripts.
         dir="auto"
       />
       <div className="composer-action-wrapper">
@@ -1127,8 +1118,8 @@ export function SharedComposer({
             open={newProjectOpen}
             onOpenChange={setNewProjectOpen}
           />
-          {/* Same + side menu as the single-chat composer (ComposerToolsMenu),
-              wired to the compare composer's own file/audio inputs and tools. */}
+          {/* Same + menu as single-chat (ComposerToolsMenu), wired to the
+              compare composer's own file/audio inputs and tools. */}
           <DropdownMenu>
             <DropdownMenuTrigger asChild={true}>
               <button
@@ -1241,8 +1232,8 @@ export function SharedComposer({
                 {mcpEnabledForChat ? <CheckIcon className="ml-auto" /> : null}
               </DropdownMenuItem>
               {/* RAG hidden temporarily */}
-              {/* Always active: this menu only renders in compare mode.
-                  Ticked like Web search/Code; click toggles it off. */}
+              {/* Always active: this menu only renders in compare mode. Ticked
+                  like Web search/Code; click toggles it off. */}
               <DropdownMenuItem
                 className="text-primary font-medium"
                 onSelect={handleExitCompare}
@@ -1303,7 +1294,7 @@ export function SharedComposer({
               const next = !toolsEnabled;
               setToolsEnabled(next);
               // Kimi's $web_search builtin requires thinking=disabled
-              // (https://platform.kimi.ai/docs/guide/use-web-search). Toggle
+              // (https://platform.kimi.ai/docs/guide/use-web-search): toggle
               // the Think pill off when Search is on, mirroring the backend.
               if (isKimiExternal) {
                 setReasoningEnabled(!next, { persist: false });
@@ -1564,9 +1555,8 @@ export function SharedComposer({
                   const next = !reasoningEnabled;
                   setReasoningEnabled(next);
                   applyQwenThinkingParams(next);
-                  // Mutual exclusion: Kimi's $web_search builtin
-                  // requires thinking off, so turning thinking on flips
-                  // the Search pill off (and vice versa).
+                  // Mutual exclusion: Kimi's $web_search builtin requires
+                  // thinking off, so turning thinking on flips Search off.
                   if (isKimiExternal && next && toolsEnabled) {
                     setToolsEnabled(false, { persist: false });
                   }
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index ebcd1892d1..320cf4c962 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -37,12 +37,11 @@ export const CHAT_WEB_FETCH_TOOLS_ENABLED_KEY =
   "unsloth_chat_web_fetch_tools_enabled";
 
 // External provider selection is encoded into `params.checkpoint` as
-// `external::<providerId>::<modelId>`. PersistedChatSettings deliberately
-// Omits `checkpoint` because the local-model side is mirrored by the
-// backend's `/api/inference/status.active_model` response. External
-// selections have no such backend mirror, so without explicit
-// localStorage persistence here the user's external pick is silently
-// reset to the default on every page refresh.
+// `external::<providerId>::<modelId>`. PersistedChatSettings omits `checkpoint`
+// because the local-model side is mirrored by the backend's
+// /api/inference/status.active_model. External selections have no such mirror,
+// so without explicit localStorage persistence here the user's external pick
+// is reset to the default on every refresh.
 const LAST_EXTERNAL_CHECKPOINT_KEY = "unsloth_chat_last_external_checkpoint";
 
 function loadLastExternalCheckpoint(): string | null {
@@ -61,13 +60,13 @@ function saveLastExternalCheckpoint(value: string | null): void {
     if (value && isExternalModelId(value)) {
       window.localStorage.setItem(LAST_EXTERNAL_CHECKPOINT_KEY, value);
     } else {
-      // Clearing on a switch to a local / empty checkpoint means the
-      // next refresh won't override the now-active local selection.
+      // Clear on switch to a local/empty checkpoint so the next refresh
+      // won't override the now-active local selection.
       window.localStorage.removeItem(LAST_EXTERNAL_CHECKPOINT_KEY);
     }
   } catch {
-    // Storage quota / private-mode failures are non-fatal -- the
-    // selection just won't survive the refresh.
+    // Storage quota / private-mode failures are non-fatal; selection just
+    // won't survive the refresh.
   }
 }
 
@@ -103,10 +102,9 @@ function warnSettingsPersistenceFailure(): void {
   });
 }
 
-// Coalesce setting writes into one pendingPatch (deep merge for nested
-// keys), flush on a trailing-edge debounce, flush on beforeunload so a
-// pending patch survives tab close. Slider drag ticks now produce one
-// HTTP write per quiet window instead of one per tick.
+// Coalesce setting writes into one pendingPatch (deep merge for nested keys),
+// flush on a trailing-edge debounce and on beforeunload so a pending patch
+// survives tab close. Slider drags produce one HTTP write per quiet window.
 type SettingsPatch = Parameters<typeof savePersistedChatSettingsPatch>[0];
 
 const SETTINGS_DEBOUNCE_MS = 400;
@@ -156,9 +154,9 @@ function saveSettingsPatch(patch: SettingsPatch): void {
   }, SETTINGS_DEBOUNCE_MS);
 }
 
-// Best-effort flush of any pending patch when the tab closes. keepalive
-// lets the PUT outlive the unload; without it the browser cancels the
-// fetch and the user's last slider drag is dropped.
+// Best-effort flush of any pending patch on tab close. keepalive lets the PUT
+// outlive the unload; without it the browser cancels the fetch and the user's
+// last slider drag is dropped.
 if (typeof window !== "undefined") {
   window.addEventListener("beforeunload", () => {
     if (pendingTimer !== null) clearTimeout(pendingTimer);
@@ -191,9 +189,9 @@ export function loadOptionalBool(key: string): boolean | null {
 
 /**
  * Resolve the web-search / code-execution pill state to apply when a model
- * loads. Honors the user's persisted preference so loading a tool-capable
- * model never silently re-enables a pill the user turned off; falls back to
- * the model's capability only when no preference has been expressed.
+ * loads. Honors the user's persisted preference so a tool-capable model never
+ * re-enables a pill the user turned off; falls back to the model's capability
+ * only when no preference has been expressed.
  */
 export function resolveToolsEnabledOnLoad(supportsTools: boolean): {
   toolsEnabled: boolean;
@@ -255,12 +253,10 @@ type ChatRuntimeStore = {
   reasoningAlwaysOn: boolean;
   reasoningEnabled: boolean;
   /**
-   * The model id the OpenRouter router actually picked for the most recent
-   * stream when the active checkpoint is the openrouter/free meta-model.
-   * Updated each time a chunk arrives carrying a non-empty `model` field
-   * that differs from the requested id. Cleared when a non-OpenRouter
-   * model is selected. Used purely for UI display — appended after
-   * `openrouter/free:` in the active model chip.
+   * The model id the OpenRouter router picked for the most recent stream when
+   * the active checkpoint is the openrouter/free meta-model. Updated when a
+   * chunk's `model` field differs from the requested id; cleared on a
+   * non-OpenRouter model. UI display only (appended after `openrouter/free:`).
    */
   lastOpenRouterChosenModel: string | null;
   reasoningStyle: ReasoningStyle;
@@ -271,35 +267,29 @@ type ChatRuntimeStore = {
   preserveThinking: boolean;
   supportsTools: boolean;
   /**
-   * Whether the active external provider exposes a server-side
-   * web_search tool (OpenAI's /v1/responses today). Distinct from
-   * `supportsTools` — that flag governs the local tool runtime (Code,
-   * python sandbox, our DuckDuckGo web_search). This one only enables
-   * the chat composer's Search pill for external models. Local models
-   * keep `supportsTools` only.
+   * Whether the active external provider exposes a server-side web_search tool
+   * (OpenAI's /v1/responses today). Distinct from `supportsTools` (the local
+   * tool runtime): this only enables the composer's Search pill for external
+   * models. Local models keep `supportsTools` only.
    */
   supportsBuiltinWebSearch: boolean;
   /**
-   * Whether the active external provider exposes a server-side
-   * code-execution tool (Anthropic's `code_execution_20250825` on the
-   * Claude 4.x family). Distinct from `supportsTools` for the same
-   * reason as `supportsBuiltinWebSearch`: external providers don't
-   * give us a local tool runtime, but Anthropic dispatches code
-   * execution server-side. Read by both composers' Code pill gate.
+   * Whether the active external provider exposes a server-side code-execution
+   * tool (Anthropic's `code_execution_20250825` on Claude 4.x). Distinct from
+   * `supportsTools` like supportsBuiltinWebSearch: Anthropic dispatches it
+   * server-side. Read by both composers' Code pill gate.
    */
   supportsBuiltinCodeExecution: boolean;
   /**
-   * Whether the active external provider exposes a server-side
-   * image-generation tool (OpenAI's Responses-API `image_generation`
-   * today). Gates the chat composer's Images pill. Local models never
-   * receive the tool because their runtime cannot dispatch it.
+   * Whether the active external provider exposes a server-side image-generation
+   * tool (OpenAI's Responses-API `image_generation`). Gates the composer's
+   * Images pill. Local models never receive it (their runtime can't dispatch it).
    */
   supportsBuiltinImageGeneration: boolean;
   /**
-   * Whether the active external provider exposes a server-side
-   * web_fetch tool (Anthropic's `web_fetch_20250910` /
-   * `web_fetch_20260209`). Gates the composer's Fetch pill,
-   * independent of Search.
+   * Whether the active external provider exposes a server-side web_fetch tool
+   * (Anthropic's `web_fetch_20250910` / `web_fetch_20260209`). Gates the
+   * composer's Fetch pill, independent of Search.
    */
   supportsBuiltinWebFetch: boolean;
   toolsEnabled: boolean;
@@ -596,10 +586,9 @@ function setScalarSettingVersion<K extends ScalarSettingKey>(
 
 export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   settingsHydrated: false,
-  // Hydrate the last external checkpoint into params.checkpoint so the
-  // external picker selection survives a page refresh. Local model
-  // checkpoints are re-derived from the backend in useChatModelRuntime
-  // and intentionally NOT persisted here.
+  // Hydrate the last external checkpoint so the external picker survives a
+  // refresh. Local checkpoints are re-derived from the backend in
+  // useChatModelRuntime and intentionally NOT persisted here.
   params: (() => {
     const persistedExternal = loadLastExternalCheckpoint();
     return persistedExternal
@@ -699,9 +688,8 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
           return nextState;
         });
       } catch {
-        // Hydrate failed: treat as hydrated-with-defaults so future
-        // setParams calls reach saveSettingsPatch (which surfaces its
-        // own toast on real network failure).
+        // Hydrate failed: treat as hydrated-with-defaults so future setParams
+        // calls reach saveSettingsPatch (which toasts on real network failure).
         warnSettingsPersistenceFailure();
         set({ settingsHydrated: true });
       } finally {
@@ -715,16 +703,15 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
     set({ modelRequiresTrustRemoteCode }),
   setParams: (params) =>
     set((state) => {
-      // Bump version unconditionally so a late hydration response
-      // won't clobber a pre-hydrate user edit; only the HTTP write
-      // is gated on settingsHydrated.
+      // Bump version unconditionally so a late hydration response won't clobber
+      // a pre-hydrate user edit; only the HTTP write is gated on settingsHydrated.
       const changedParams = getChangedInferenceParams(params, state.params);
       if (state.settingsHydrated && hasKeys(changedParams)) {
         saveSettingsPatch({ inferenceParams: changedParams });
       }
-      // Mirror setCheckpoint: the local model load path can mutate
-      // params.checkpoint via setParams() before setCheckpoint runs,
-      // leaving stale per-turn counters under the new checkpoint.
+      // Mirror setCheckpoint: the local load path can mutate params.checkpoint
+      // via setParams() before setCheckpoint runs, leaving stale per-turn
+      // counters under the new checkpoint.
       const checkpointChanged = state.params.checkpoint !== params.checkpoint;
       return {
         params,
@@ -787,19 +774,17 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   setModelsError: (modelsError) => set({ modelsError }),
   setCheckpoint: (modelId, ggufVariant) =>
     set((state) => {
-      // Persist external selections so they survive a page refresh.
-      // Local model ids are NOT persisted here -- they get re-derived
-      // from the backend's `/api/inference/status.active_model` on
-      // mount, and a stale persisted local id would race against the
-      // freshly-loaded model. See LAST_EXTERNAL_CHECKPOINT_KEY notes.
+      // Persist external selections so they survive a refresh. Local ids are
+      // NOT persisted -- they're re-derived from the backend on mount, and a
+      // stale persisted local id would race the freshly-loaded model. See
+      // LAST_EXTERNAL_CHECKPOINT_KEY notes.
       saveLastExternalCheckpoint(isExternalModelId(modelId) ? modelId : null);
-      // Clear stale per-turn usage when the model changes; the relaxed
-      // external-provider render gate would otherwise show old counters
-      // until the next completion overwrites them.
+      // Clear stale per-turn usage on model change; the relaxed external-provider
+      // render gate would otherwise show old counters until the next completion.
       const checkpointChanged = state.params.checkpoint !== modelId;
-      // Clamp maxTokens to the new model's cap on switch into an
-      // external model so a value carried over from a prior local
-      // session does not render above the slider's max.
+      // Clamp maxTokens to the new model's cap when switching into an external
+      // model so a value carried over from a local session doesn't exceed the
+      // slider's max.
       let nextMaxTokens = state.params.maxTokens;
       if (checkpointChanged && isExternalModelId(modelId)) {
         const parsed = parseExternalModelId(modelId);
@@ -831,10 +816,9 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   setActiveProjectId: (activeProjectId) => set({ activeProjectId }),
   setSettingsPanelOpen: (settingsPanelOpen) => set({ settingsPanelOpen }),
   clearCheckpoint: () => {
-    // Mirror setCheckpoint's persistence behavior: dropping the
-    // checkpoint must also clear any stored external selection so
-    // the next refresh doesn't snap back to a model the user
-    // intentionally cleared.
+    // Mirror setCheckpoint's persistence: dropping the checkpoint must also
+    // clear any stored external selection so the next refresh doesn't snap
+    // back to a model the user intentionally cleared.
     saveLastExternalCheckpoint(null);
     return set((state) => ({
       params: {
diff --git a/studio/frontend/src/features/chat/tour/steps.tsx b/studio/frontend/src/features/chat/tour/steps.tsx
index e4f37685cc..de27e93c88 100644
--- a/studio/frontend/src/features/chat/tour/steps.tsx
+++ b/studio/frontend/src/features/chat/tour/steps.tsx
@@ -62,8 +62,8 @@ export function buildChatTourSteps({
   ];
 
   if (canCompare) {
-    // Compare now lives in the + menu, so there is no sidebar button to anchor
-    // to; the view step enters compare on its own and explains it.
+    // Compare lives in the + menu (no sidebar button to anchor to); this step
+    // enters compare on its own and explains it.
     steps.push({
       id: "compare-view",
       target: "chat-compare-view",
diff --git a/studio/frontend/src/features/chat/types.ts b/studio/frontend/src/features/chat/types.ts
index a2bd395065..ef4dd7dbcb 100644
--- a/studio/frontend/src/features/chat/types.ts
+++ b/studio/frontend/src/features/chat/types.ts
@@ -37,29 +37,24 @@ export interface ThreadRecord {
   archived: boolean;
   createdAt: number;
   /**
-   * OpenAI shell tool container id captured from a prior response on
-   * this thread. When set, the next turn reuses it via
-   * `environment.type="container_reference"` so the model can read
-   * files it wrote earlier in the conversation. When null/undefined,
-   * the next turn auto-creates a fresh container.
+   * OpenAI shell tool container id from a prior response. When set, the
+   * next turn reuses it via `environment.type="container_reference"` so
+   * the model can read files it wrote earlier; else auto-creates one.
    *
-   * OpenAI containers expire after ~20 min of inactivity by default;
-   * if a stale id is sent, the backend surfaces an
-   * `_toolEvent.type="container_invalidated"` and the chat-adapter
-   * clears this field so the following turn falls back to auto-create.
+   * Containers expire after ~20 min idle; on a stale id the backend
+   * emits `_toolEvent.type="container_invalidated"` and the chat-adapter
+   * clears this field so the next turn falls back to auto-create.
    */
   openaiCodeExecContainerId?: string | null;
   /**
-   * Anthropic code_execution container id captured from a prior
-   * response on this thread. When set, the next turn sends a
-   * top-level `container` field on /v1/messages so filesystem state
-   * (files, packages, variables) persists across turns. When
-   * null/undefined, Anthropic auto-creates a fresh container.
+   * Anthropic code_execution container id from a prior response. When
+   * set, the next turn sends a top-level `container` on /v1/messages so
+   * filesystem state (files, packages, variables) persists; else auto-
+   * creates one.
    *
-   * Anthropic containers expire after ~1 hour by default; on a stale
-   * id the backend surfaces `_toolEvent.type="container_invalidated"`
-   * and the chat-adapter clears this field so the following turn
-   * falls back to auto-create.
+   * Containers expire after ~1 hour; on a stale id the backend emits
+   * `_toolEvent.type="container_invalidated"` and the chat-adapter
+   * clears this field so the next turn falls back to auto-create.
    */
   anthropicCodeExecContainerId?: string | null;
 }
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 92ea1500bd..48efdbba2e 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -44,18 +44,16 @@ export interface LoadModelRequest {
   chat_template_override?: string | null;
   cache_type_kv?: string | null;
   /**
-   * Speculative decoding mode for GGUF models. Canonical values:
-   * "auto" (platform-aware: MTP on MTP GGUFs, ngram-mod fallback for
-   * sub-3B), "mtp" (force draft-mtp only on both GPU and CPU), "ngram"
-   * (force ngram-mod only), "mtp+ngram" (force ngram-mod + draft-mtp
-   * chain on both platforms), or "off". Legacy values "default" /
-   * "draft-mtp" / "ngram-mod" / "ngram-simple" are still accepted by
-   * the backend.
+   * Speculative decoding mode for GGUF models. Canonical values: "auto"
+   * (platform-aware: MTP on MTP GGUFs, ngram-mod fallback for sub-3B), "mtp"
+   * (force draft-mtp), "ngram" (force ngram-mod), "mtp+ngram" (ngram-mod +
+   * draft-mtp chain), "off". Legacy "default"/"draft-mtp"/"ngram-mod"/
+   * "ngram-simple" are still accepted by the backend.
    */
   speculative_type?: string | null;
   /**
-   * Override --spec-draft-n-max for MTP speculative decoding. Only
-   * applied when speculative_type resolves to "mtp" or "mtp+ngram".
+   * Override --spec-draft-n-max for MTP speculative decoding. Applied only
+   * when speculative_type resolves to "mtp" or "mtp+ngram".
    */
   spec_draft_n_max?: number | null;
 }
@@ -221,13 +219,11 @@ export type OpenAIMessageContentPart =
 export type OpenAIMessageContent = string | OpenAIMessageContentPart[];
 
 /**
- * OpenAI Chat Completions tool_call shape. Assistant turns echo back
- * function/tool calls as `tool_calls`; the matching tool result rides
- * on a separate `role="tool"` message keyed by `tool_call_id`.
- * `extra_content.google.thought_signature` is the Gemini-specific
- * round-trip field the backend translator both emits (on `delta.
- * tool_calls`) and consumes (when rebuilding the native functionCall
- * part on the next turn).
+ * OpenAI Chat Completions tool_call shape. Assistant turns echo function calls
+ * as `tool_calls`; the matching result rides on a separate `role="tool"`
+ * message keyed by `tool_call_id`. `extra_content.google.thought_signature` is
+ * the Gemini round-trip field the backend translator emits (on `delta.
+ * tool_calls`) and consumes (when rebuilding the functionCall part next turn).
  */
 export interface OpenAIToolCallPart {
   id?: string;
@@ -289,36 +285,28 @@ export interface OpenAIChatCompletionsRequest {
   encrypted_api_key?: string;
   provider_base_url?: string | null;
   /**
-   * Boolean toggle for OpenAI/Anthropic ephemeral cache_control. For
-   * Gemini the backend also accepts the cached-content resource name
-   * (`cachedContents/...`) as a string, which is forwarded as
-   * `generationConfig.cachedContent` on the native streamGenerateContent
-   * request.
+   * Boolean toggle for OpenAI/Anthropic ephemeral cache_control. For Gemini the
+   * backend also accepts a cached-content resource name (`cachedContents/...`)
+   * string, forwarded as `generationConfig.cachedContent`.
    */
   enable_prompt_caching?: boolean | string | null;
   /**
-   * OpenAI shell-tool container id captured from the prior response in
-   * this chat thread. When set and the Code pill is on, the backend
-   * routes the next /v1/responses call with
-   * `environment.type="container_reference"` so filesystem state
-   * persists across turns. Unset → backend uses
-   * `environment.type="container_auto"` and OpenAI creates a fresh
-   * container. Only meaningful for OpenAI cloud + gpt-5.5 family.
+   * OpenAI shell-tool container id from the prior response in this thread. When
+   * set and the Code pill is on, the backend routes the next /v1/responses with
+   * `environment.type="container_reference"` so filesystem state persists; unset
+   * → `container_auto` (fresh container). OpenAI cloud + gpt-5.5 family only.
    */
   openai_code_exec_container_id?: string | null;
   /**
-   * Anthropic code_execution container id captured from the prior
-   * response in this chat thread. When set and the Code pill is on,
-   * the backend forwards a top-level `container` field on
-   * /v1/messages so filesystem state persists across turns. Unset →
-   * Anthropic auto-creates a fresh container. Only meaningful for
-   * the Anthropic provider with `code_execution` in `enabled_tools`.
+   * Anthropic code_execution container id from the prior response in this
+   * thread. When set and the Code pill is on, the backend forwards a top-level
+   * `container` on /v1/messages so filesystem state persists; unset →
+   * auto-created. Anthropic provider with `code_execution` in `enabled_tools`.
    */
   anthropic_code_exec_container_id?: string | null;
   /**
-   * Anthropic fast-mode toggle. Opus 4.6 / 4.7 only; backend drops
-   * silently on every other model + provider. See
-   * https://platform.claude.com/docs/en/build-with-claude/fast-mode
+   * Anthropic fast-mode toggle. Opus 4.6 / 4.7 only; dropped silently elsewhere.
+   * See https://platform.claude.com/docs/en/build-with-claude/fast-mode
    */
   fast_mode?: boolean | null;
 }
@@ -327,16 +315,15 @@ export interface OpenAIChatDelta {
   role?: string;
   content?: string | null;
   /**
-   * Streamed assistant tool calls. The Gemini and OpenAI Responses
-   * translators emit incremental `tool_calls` deltas (function name +
-   * arguments fragments) so the chat-adapter can render tool cards as
-   * they arrive.
+   * Streamed assistant tool calls. The Gemini and OpenAI Responses translators
+   * emit incremental deltas (function name + arguments fragments) so the
+   * chat-adapter can render tool cards as they arrive.
    */
   tool_calls?: OpenAIToolCallPart[];
   /**
-   * Provider-specific passthrough. Gemini ships `thoughtSignature`,
-   * citations, `native_part`, etc., here so the round-trip can replay
-   * them on follow-up turns without bleeding into other providers.
+   * Provider-specific passthrough. Gemini ships `thoughtSignature`, citations,
+   * `native_part`, etc., here so the round-trip can replay them on follow-up
+   * turns without bleeding into other providers.
    */
   extra_content?: Record<string, unknown>;
 }
diff --git a/studio/frontend/src/features/chat/types/runtime.ts b/studio/frontend/src/features/chat/types/runtime.ts
index 24286c94fb..f521fd192f 100644
--- a/studio/frontend/src/features/chat/types/runtime.ts
+++ b/studio/frontend/src/features/chat/types/runtime.ts
@@ -15,8 +15,8 @@ export interface InferenceParams {
   /** Allow loading models with custom code (e.g. NVIDIA Nemotron). Only enable for repos you trust. */
   trustRemoteCode?: boolean;
   /**
-   * Anthropic fast-mode toggle. Opus 4.6 / 4.7 only; higher OTPS at
-   * 6x standard Opus pricing. Default false.
+   * Anthropic fast-mode toggle. Opus 4.6 / 4.7 only; higher OTPS at 6x Opus
+   * pricing. Default false.
    * https://platform.claude.com/docs/en/build-with-claude/fast-mode
    */
   fastMode?: boolean;
diff --git a/studio/frontend/src/features/chat/utils/chat-history-storage.ts b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
index 6dc53cf48e..0e9b30a5cc 100644
--- a/studio/frontend/src/features/chat/utils/chat-history-storage.ts
+++ b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
@@ -43,11 +43,10 @@ type ThreadListArgs = {
 };
 
 // localStorage perf-hint that the Dexie -> studio.db import already
-// finished in a previous session. NOT consulted by the import gate
-// itself -- the server-side ledger (chat_legacy_imports) is the source
-// of truth so a studio.db wipe stays recoverable. The hint only short-
-// circuits the listing paths' "should I also surface Dexie threads?"
-// branches once the ledger has covered everything.
+// finished. NOT the import gate -- the server-side ledger
+// (chat_legacy_imports) is the source of truth so a studio.db wipe stays
+// recoverable. The hint only short-circuits the listing paths' "also
+// surface Dexie threads?" branches once the ledger has covered everything.
 const LEGACY_CHAT_IMPORT_KEY = "unsloth_chat_legacy_imported_to_studio_db";
 
 let legacyChatImportPromise: Promise<void> | null = null;
@@ -265,9 +264,9 @@ async function backfillLegacyThreadFields(
   }
 }
 
-// Fast-path: ask IndexedDB whether the "unsloth-chat" database exists
-// without opening it. Modern Chromium / Firefox / Safari support this;
-// older browsers return undefined and we fall through to the next probe.
+// Fast-path: check whether the "unsloth-chat" DB exists without opening
+// it. Supported on modern Chromium/Firefox/Safari; older browsers return
+// undefined and we fall through to the next probe.
 async function dexieDbAbsent(): Promise<boolean> {
   if (typeof indexedDB === "undefined") return true;
   const dbs = (indexedDB as IDBFactory).databases;
@@ -291,24 +290,22 @@ async function dexieIsEmpty(): Promise<boolean> {
     ]);
     return threadCount === 0 && messageCount === 0;
   } catch {
-    // Dexie threw (corrupted DB / version mismatch / quota). Returning
-    // false forces the slow path, which uses the same Dexie under the
-    // hood; that path will throw too and the import promise gets reset
-    // so the next caller can retry rather than silently doing nothing.
+    // Dexie threw (corrupt DB / version mismatch / quota). Returning
+    // false forces the slow path (same Dexie underneath); it'll throw
+    // too and reset the import promise so the next caller can retry.
     return false;
   }
 }
 
 async function importLegacyChatsIfNeeded(): Promise<void> {
-  // Session-level cache: same tab, repeated sidebar mounts share one
-  // import. localStorage is NOT consulted here -- the server-side ledger
-  // is the source of truth so a studio.db wipe still re-triggers the
-  // import even if the browser kept its old hint.
+  // Session-level cache: repeated sidebar mounts in the same tab share
+  // one import. localStorage is NOT consulted -- the server-side ledger
+  // is the source of truth, so a studio.db wipe re-triggers the import
+  // even if the browser kept its old hint.
   if (legacyChatImportPromise) return legacyChatImportPromise;
 
   legacyChatImportPromise = (async () => {
-    // Fast-path: no Dexie database at all. New user, never had the
-    // browser-only Studio. ~0.1 ms, zero network.
+    // Fast-path: no Dexie DB -- new user, never had browser-only Studio.
     if (await dexieDbAbsent()) {
       markLegacyChatImportDone();
       return;
@@ -336,10 +333,9 @@ async function importLegacyChatsIfNeeded(): Promise<void> {
     const unimportedIds: string[] = [];
     const unimportedThreads: ThreadRecord[] = [];
 
-    // "Unimported" = missing from the ledger. We also include threads
-    // already present in the backend (without a ledger row) so the ledger
-    // gets backfilled for old-FE-then-new-FE users -- otherwise the next
-    // launch would redo the diff for the same threads forever.
+    // "Unimported" = missing from the ledger. Include threads already in
+    // the backend (without a ledger row) so the ledger gets backfilled
+    // for old-FE-then-new-FE users; else the next launch re-diffs forever.
     for (const thread of legacyThreads) {
       if (isChatThreadDeleted(thread.id)) continue;
       if (importedThreadIds.has(thread.id)) continue;
@@ -406,14 +402,12 @@ async function importLegacyChatsIfNeeded(): Promise<void> {
       result = await recordChatImportLedger(newlyImportedIds);
     } catch {
       // Network error: leave the perf hint alone so the next launch
-      // retries. The import itself is idempotent via UPSERT, no
-      // duplicates.
+      // retries. Import is idempotent via UPSERT, so no duplicates.
       return;
     }
-    // Only flip the localStorage hint when the backend actually has the
-    // ledger. On older deployments (404/405/501) the hint would lie:
-    // "import done" while the ledger stays empty, defeating recovery
-    // when studio.db gets wiped later.
+    // Only flip the hint when the backend actually has the ledger. On
+    // older deployments (404/405/501) it would lie ("import done" with an
+    // empty ledger), defeating recovery after a studio.db wipe.
     if (result.supported) {
       markLegacyChatImportDone();
     }
@@ -576,8 +570,8 @@ export async function listStoredChatThreadsWithMessages(
 ): Promise<ThreadRecord[]> {
   const threads = await listStoredChatThreads(args);
   if (threads.length === 0) return [];
-  // One batched HTTP call instead of N. Per-thread legacy Dexie
-  // fallback only fires when the batch result is empty.
+  // One batched HTTP call instead of N. Per-thread legacy Dexie fallback
+  // only fires when the batch result is empty.
   const threadIds = threads.map((t) => t.id);
   let backendByThread: Map<string, MessageRecord[]>;
   try {
@@ -728,8 +722,8 @@ export interface ClearStoredChatsResult {
 }
 
 export async function clearStoredChats(): Promise<ClearStoredChatsResult> {
-  // Clear both sides independently and report each outcome so the
-  // toast can distinguish full vs partial success.
+  // Clear both sides independently and report each outcome so the toast
+  // can distinguish full vs partial success.
   const [backendThreadsResult, legacyThreads] = await Promise.all([
     listChatThreads()
       .then((threads) => ({ ok: true as const, threads }))
@@ -752,8 +746,8 @@ export async function clearStoredChats(): Promise<ClearStoredChatsResult> {
     failedThreadIds: [],
   };
   try {
-    // Defer the history refresh until Dexie clear and tombstone state are
-    // finalized, so listeners never observe the composite clear mid-flight.
+    // Defer the history refresh until Dexie clear and tombstones finalize,
+    // so listeners never observe the composite clear mid-flight.
     await clearBackendChats({ notify: false });
     result.backend = "cleared";
   } catch (error) {
diff --git a/studio/frontend/src/features/chat/utils/chat-thread-tombstones.ts b/studio/frontend/src/features/chat/utils/chat-thread-tombstones.ts
index d9a6f2d501..4d2a0da653 100644
--- a/studio/frontend/src/features/chat/utils/chat-thread-tombstones.ts
+++ b/studio/frontend/src/features/chat/utils/chat-thread-tombstones.ts
@@ -2,10 +2,9 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Tombstones mask deleted threads in the Dexie read fallback. Each
- * carries a `deletedAt` timestamp so old entries can be GC'd, keeping
- * localStorage bounded. Reads accept both the legacy plain-string
- * format and the new {id, deletedAt} tuple form.
+ * Tombstones mask deleted threads in the Dexie read fallback. Each carries a
+ * `deletedAt` so old entries can be GC'd, keeping localStorage bounded. Reads
+ * accept both the legacy plain-string format and the {id, deletedAt} tuple.
  */
 
 interface Tombstone {
@@ -62,8 +61,7 @@ function gc(): void {
   for (const [id, t] of deletedThreads) {
     if (t.deletedAt < cutoff) deletedThreads.delete(id);
   }
-  // Cap absolute size: drop oldest if we somehow exceed the limit
-  // (e.g. a script clearing thousands of threads at once).
+  // Cap size: drop oldest if we exceed the limit (e.g. a bulk thread clear).
   if (deletedThreads.size > TOMBSTONE_MAX_COUNT) {
     const sorted = Array.from(deletedThreads.entries()).sort(
       (a, b) => a[1].deletedAt - b[1].deletedAt,
diff --git a/studio/frontend/src/features/chat/utils/delete-thread-message.ts b/studio/frontend/src/features/chat/utils/delete-thread-message.ts
index 37d4732d93..3b439eb779 100644
--- a/studio/frontend/src/features/chat/utils/delete-thread-message.ts
+++ b/studio/frontend/src/features/chat/utils/delete-thread-message.ts
@@ -2,16 +2,15 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * assistant-ui does not expose a public `deleteMessage` on `ThreadRuntime` / `MessageRuntime`
- * in our version, but it already implements branch-safe deletion inside `MessageRepository`.
- * We import that helper from `@assistant-ui/core/internal`, the package's exported internal
- * surface. Avoid importing the deeper `runtime/utils/message-repository` path directly: newer
- * `@assistant-ui/core` releases no longer export arbitrary deep paths.
+ * assistant-ui exposes no public `deleteMessage` in our version, but
+ * `MessageRepository` already does branch-safe deletion. We import it from
+ * `@assistant-ui/core/internal` (the exported internal surface); avoid the
+ * deeper `runtime/utils/message-repository` path since newer releases no
+ * longer export arbitrary deep paths.
  *
- * **Maintainability:** treat this file as the only place that imports `MessageRepository` from
- * `@assistant-ui/core`. When bumping `@assistant-ui/react` / `@assistant-ui/core`, re-run chat
- * delete + reload smoke tests; the path or API may change without a semver signal on “public”
- * surface area.
+ * Keep this file the only importer of `MessageRepository`. When bumping
+ * `@assistant-ui/react` / `core`, re-run chat delete + reload smoke tests;
+ * the path or API may change without a semver signal.
  */
 import { MessageRepository } from "@assistant-ui/core/internal";
 import type {
diff --git a/studio/frontend/src/features/chat/utils/format-transfer.ts b/studio/frontend/src/features/chat/utils/format-transfer.ts
index 737f26c8cb..b6e23519c7 100644
--- a/studio/frontend/src/features/chat/utils/format-transfer.ts
+++ b/studio/frontend/src/features/chat/utils/format-transfer.ts
@@ -2,14 +2,9 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Format a byte-per-second rate as a human-readable string.
- *
- *   512            → "512 B/s"
- *   1_234_567      → "1.2 MB/s"
- *   1_234_567_890  → "1.15 GB/s"
- *
- * Returns `"--"` for non-finite or non-positive inputs so callers can
- * render the label safely before the first stable sample arrives.
+ * Format a byte-per-second rate (e.g. 1_234_567 → "1.2 MB/s"). Returns `"--"`
+ * for non-finite or non-positive inputs so the label renders safely before the
+ * first stable sample.
  */
 export function formatRate(bytesPerSecond: number): string {
   if (!Number.isFinite(bytesPerSecond) || bytesPerSecond <= 0) return "--";
@@ -21,13 +16,8 @@ export function formatRate(bytesPerSecond: number): string {
 }
 
 /**
- * Format an ETA (in seconds) as a short human-readable string.
- *
- *   47       → "47s"
- *   125      → "2m 5s"
- *   3725     → "1h 2m"
- *
- * Returns `"--"` for non-finite or non-positive inputs.
+ * Format an ETA in seconds as a short string (e.g. 125 → "2m 5s", 3725 →
+ * "1h 2m"). Returns `"--"` for non-finite or non-positive inputs.
  */
 export function formatEta(seconds: number): string {
   if (!Number.isFinite(seconds) || seconds <= 0) return "--";
diff --git a/studio/frontend/src/features/chat/utils/image-input-support.ts b/studio/frontend/src/features/chat/utils/image-input-support.ts
index fb39303e29..d1ea31fc76 100644
--- a/studio/frontend/src/features/chat/utils/image-input-support.ts
+++ b/studio/frontend/src/features/chat/utils/image-input-support.ts
@@ -14,8 +14,8 @@ export function getImageInputUnavailableReason({
   activeModel?: ChatModelSummary;
   isExternalModel: boolean;
   // true/false = caller knows; null/undefined = unknown (default-allow).
-  // External selections aren't in runtime.models[], so callers should
-  // resolve provider-type capability and pass it here.
+  // External selections aren't in runtime.models[], so callers resolve
+  // provider-type capability and pass it here.
   externalSupportsVision?: boolean | null;
   // Fallback toast label when activeModel is missing.
   externalModelLabel?: string | null;
@@ -40,11 +40,10 @@ export function getImageInputUnavailableReason({
     return null;
   }
   if (!modelLoaded) return "Load a model before adding images.";
-  // loadedIsMultimodal is true for vision OR audio. Can't tell them apart
-  // from that one flag, so only block when activeModel confirms
-  // audio-only: audio capability set AND isVision === false. Otherwise
-  // trust the load response. The models-list entry might be stale, or
-  // not even there yet (gets auto-injected after load).
+  // loadedIsMultimodal is true for vision OR audio; that one flag can't tell
+  // them apart, so only block when activeModel confirms audio-only (audio
+  // capability set AND isVision === false). Otherwise trust the load
+  // response: the models-list entry may be stale or not yet injected.
   if (loadedIsMultimodal) {
     const isAudioOnly =
       Boolean(activeModel?.isAudio || activeModel?.hasAudioInput) &&
diff --git a/studio/frontend/src/features/chat/utils/parse-assistant-content.ts b/studio/frontend/src/features/chat/utils/parse-assistant-content.ts
index 36655ca81e..515fb0e1dd 100644
--- a/studio/frontend/src/features/chat/utils/parse-assistant-content.ts
+++ b/studio/frontend/src/features/chat/utils/parse-assistant-content.ts
@@ -8,11 +8,9 @@ type ContentPart = NonNullable<ChatModelRunResult["content"]>[number];
 const THINK_OPEN_TAG = "<think>";
 const THINK_CLOSE_TAG = "</think>";
 
-// ContentPart from @assistant-ui/react has readonly fields, so we cannot
-// do `last.text += text` to coalesce adjacent same-type parts — tsc fails
-// with TS2540 "Cannot assign to 'text' because it is a read-only property".
-// Instead, replace the last element with a fresh merged object: same
-// allocation cost as the mutation path but type-safe.
+// ContentPart from @assistant-ui/react has readonly fields, so coalescing via
+// `last.text += text` fails (TS2540). Instead replace the last element with a
+// fresh merged object: same allocation cost as mutation but type-safe.
 
 function appendTextPart(parts: ContentPart[], text: string): void {
   if (!text) return;
diff --git a/studio/frontend/src/features/chat/utils/transfer-stats.ts b/studio/frontend/src/features/chat/utils/transfer-stats.ts
index 7aecf29eb0..ca6c082a1a 100644
--- a/studio/frontend/src/features/chat/utils/transfer-stats.ts
+++ b/studio/frontend/src/features/chat/utils/transfer-stats.ts
@@ -4,13 +4,9 @@
 /**
  * Pure, framework-free math behind {@link useTransferStats}.
  *
- * Split out so it can be unit-tested without a DOM/React renderer, and
- * so the training-start overlay, the chat download toast, and the
- * model-load phase UI all share the exact same rate/ETA semantics.
- *
- * No React, no `useRef`/`useState`, no timers -- the caller owns the
- * sample buffer and clock. This is the "what is the rate right now
- * given these samples" question, nothing more.
+ * Split out for unit-testing without React, and so the training-start overlay,
+ * chat download toast, and model-load UI share identical rate/ETA semantics.
+ * No React/timers -- the caller owns the sample buffer and clock.
  */
 
 export type TransferSample = { t: number; b: number };
@@ -19,10 +15,9 @@ export type TransferStats = {
   rateBytesPerSecond: number;
   etaSeconds: number;
   /**
-   * False until the window has at least {@link MIN_SAMPLES} samples
-   * spanning ≥ {@link MIN_WINDOW_SECONDS} with strictly forward progress.
-   * Consumers should hide rate/ETA while this is false so the UI doesn't
-   * flicker "123 GB/s" during the first tick.
+   * False until the window has ≥ {@link MIN_SAMPLES} samples spanning ≥
+   * {@link MIN_WINDOW_SECONDS} with forward progress. Hide rate/ETA while false
+   * so the UI doesn't flicker "123 GB/s" during the first tick.
    */
   stable: boolean;
 };
@@ -32,11 +27,9 @@ export const MIN_WINDOW_SECONDS = 3;
 export const MAX_WINDOW_SECONDS = 15;
 
 /**
- * Mutate ``samples`` in place: append the new sample, drop any that
- * fell out of the rolling window, and clear the buffer if the counter
- * went backwards (user cancelled + restarted a download, etc.).
- *
- * Returns the same array for chain-ability.
+ * Mutate ``samples`` in place: append the sample, drop any out of the rolling
+ * window, and clear the buffer if the counter went backwards (cancel + restart).
+ * Returns the same array for chaining.
  */
 export function appendSample(
   samples: TransferSample[],
@@ -56,13 +49,11 @@ export function appendSample(
 }
 
 /**
- * Derive {@link TransferStats} from a window of cumulative-byte samples
- * plus the known total.
- *
+ * Derive {@link TransferStats} from a window of cumulative-byte samples plus the
+ * known total.
  *   * Needs ≥ {@link MIN_SAMPLES} samples spanning ≥ {@link MIN_WINDOW_SECONDS}
- *     seconds before it will report ``stable: true``.
- *   * ETA is clamped to 0 when: no progress, no total known, or the
- *     counter already hit the total.
+ *     seconds before reporting ``stable: true``.
+ *   * ETA clamps to 0 when there's no progress, no total, or total is hit.
  */
 export function computeTransferStats(
   samples: readonly TransferSample[],
diff --git a/studio/frontend/src/features/export/api/export-api.ts b/studio/frontend/src/features/export/api/export-api.ts
index 56f8c8129b..58df511366 100644
--- a/studio/frontend/src/features/export/api/export-api.ts
+++ b/studio/frontend/src/features/export/api/export-api.ts
@@ -37,10 +37,8 @@ export interface ExportOperationResponse {
   success: boolean;
   message: string;
   /**
-   * Optional extras returned by the backend. The export endpoints set
-   * `details.output_path` to the resolved on-disk directory of the
-   * saved model when a local save was requested. Hub-only pushes leave
-   * `details` undefined.
+   * Optional backend extras. Local saves set `details.output_path` to the
+   * saved model's on-disk directory; hub-only pushes leave it undefined.
    */
   details?: { output_path?: string | null } & Record<string, unknown>;
 }
diff --git a/studio/frontend/src/features/export/components/export-dialog.tsx b/studio/frontend/src/features/export/components/export-dialog.tsx
index 176b10a52f..c529cadab6 100644
--- a/studio/frontend/src/features/export/components/export-dialog.tsx
+++ b/studio/frontend/src/features/export/components/export-dialog.tsx
@@ -26,9 +26,8 @@ import { streamExportLogs, type ExportLogEntry } from "../api/export-api";
 import { collapseAnim } from "../anim";
 import { EXPORT_METHODS, type ExportMethod } from "../constants";
 
-// Max log lines kept in the dialog's local state. Matches the backend
-// ring buffer's maxlen so the UI shows the full scrollback captured
-// server side.
+// Max log lines kept in local state. Matches the backend ring buffer's maxlen
+// so the UI shows the full server-side scrollback.
 const MAX_LOG_LINES = 4000;
 
 interface UseExportLogsResult {
@@ -38,14 +37,10 @@ interface UseExportLogsResult {
 }
 
 /**
- * Subscribe to the live export log SSE stream while `exporting` is
- * true, and accumulate lines in local state. Lines from a previous
- * action are cleared:
- *
- *   - when a new export starts (`exporting` flips to true), and
- *   - when the user switches export method, dialog opens fresh, or
- *     the dialog closes — so re-opening into a different action's
- *     screen doesn't show the prior screen's saved output.
+ * Subscribe to the live export log SSE stream while `exporting` is true and
+ * accumulate lines. Prior-action lines are cleared when a new export starts and
+ * when the user switches method / reopens / closes the dialog, so reopening
+ * into a different action doesn't show stale output.
  */
 function useExportLogs(
   exporting: boolean,
@@ -56,10 +51,9 @@ function useExportLogs(
   const [connected, setConnected] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  // Reset log state whenever the user moves to a different screen --
-  // either by switching export method or by reopening the dialog -- so
-  // each (open × method) tuple shows only its own run history. The
-  // streaming effect below additionally clears on new export start.
+  // Reset log state on screen change (method switch or dialog reopen) so each
+  // (open × method) shows only its own run history. The streaming effect below
+  // additionally clears on new export start.
   useEffect(() => {
     setLines([]);
     setError(null);
@@ -74,17 +68,15 @@ function useExportLogs(
 
     const abortCtrl = new AbortController();
     let cancelled = false;
-    // Track the highest seq we've observed on a `log` event so we can
-    // resume the stream via `since=` / `Last-Event-ID` after a drop.
-    // The backend's SSE `id:` field carries this as ExportLogEvent.id.
+    // Highest seq seen on a `log` event, to resume via `since=` / Last-Event-ID
+    // after a drop. The backend's SSE `id:` field carries this as ExportLogEvent.id.
     let lastSeq: number | null = null;
-    // Exponential backoff with jitter, capped. Reset on every
-    // successful connection so flaky networks don't accumulate delay.
+    // Capped exponential backoff with jitter; reset on each successful connect
+    // so flaky networks don't accumulate delay.
     let backoffMs = 500;
     const MAX_BACKOFF_MS = 5000;
-    // Flipped by a terminal event (explicit `complete` from the
-    // backend or a non-transient error we choose not to retry). Stops
-    // the outer reconnect loop even if `exporting` is still true.
+    // Set by a terminal event (backend `complete` or a non-retryable error) to
+    // stop the reconnect loop even while `exporting` is still true.
     let terminated = false;
 
     const run = async () => {
@@ -115,9 +107,8 @@ function useExportLogs(
                   return next;
                 });
               } else if (event.event === "complete") {
-                // Backend signalled the run is fully drained -- stop
-                // trying to reconnect even though `exporting` may not
-                // have flipped false yet on this tick.
+                // Run fully drained -- stop reconnecting even if `exporting`
+                // hasn't flipped false yet on this tick.
                 terminated = true;
               } else if (event.event === "error" && event.error) {
                 setError(event.error);
@@ -128,17 +119,15 @@ function useExportLogs(
           if (cancelled) return;
           if (err instanceof DOMException && err.name === "AbortError") return;
           setError(err instanceof Error ? err.message : String(err));
-          // Fall through to the backoff path below; a fetch-level
-          // failure is retryable the same way a clean EOF is.
+          // Fall through to backoff; a fetch-level failure retries like a clean EOF.
         }
 
         setConnected(false);
         if (cancelled || terminated) return;
 
-        // Exponential backoff with jitter before reconnecting. The
-        // backend's ring buffer plus Last-Event-ID resume means we
-        // don't lose lines across the retry as long as the reconnect
-        // happens within the buffer's lifetime (~4000 lines).
+        // Exponential backoff with jitter before reconnecting. Ring buffer +
+        // Last-Event-ID resume means no lines lost across the retry as long as
+        // the reconnect lands within the buffer's lifetime (~4000 lines).
         const delay = backoffMs + Math.floor(Math.random() * 250);
         backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
         try {
@@ -163,9 +152,8 @@ function useExportLogs(
       }
     };
 
-    // run()'s own try/catch handles every failure path we care about;
-    // swallow anything that somehow escapes so React's dev overlay
-    // doesn't flag an unhandled rejection on dialog close.
+    // run() handles every failure path; swallow stragglers so React's dev
+    // overlay doesn't flag an unhandled rejection on dialog close.
     void run().catch(() => {});
 
     return () => {
@@ -179,10 +167,9 @@ function useExportLogs(
 }
 
 /**
- * Tick every second while `exporting` is true and report elapsed
- * seconds. Powers the "Working… 27s" badge in the log header so the
- * panel doesn't look frozen during long single-step phases (cache
- * file copy, GGUF conversion) when no new lines are arriving.
+ * Tick every second while `exporting` is true and report elapsed seconds.
+ * Powers the "Working… 27s" badge so the panel doesn't look frozen during long
+ * single-step phases (cache copy, GGUF conversion) with no new lines.
  */
 function useElapsedSeconds(exporting: boolean): number {
   const [elapsed, setElapsed] = useState(0);
@@ -209,8 +196,7 @@ function formatElapsed(seconds: number): string {
 }
 
 function formatLogLine(entry: ExportLogEntry): string {
-  // Strip trailing carriage returns that tqdm-style progress leaves
-  // in the stream so the scrollback doesn't render funky boxes.
+  // Strip trailing CRs from tqdm-style progress so scrollback doesn't render boxes.
   return entry.line.replace(/\r+$/g, "");
 }
 
@@ -240,9 +226,8 @@ interface ExportDialogProps {
   exportError: string | null;
   exportSuccess: boolean;
   /**
-   * Resolved on-disk realpath of the most recent successful export.
-   * Surfaced on the Export Complete screen so users can find their
-   * model. Null when the export only pushed to the Hub.
+   * Resolved on-disk realpath of the latest successful export, shown on the
+   * Export Complete screen. Null when the export only pushed to the Hub.
    */
   exportOutputPath: string | null;
 }
@@ -272,8 +257,7 @@ export function ExportDialog({
   exportSuccess,
   exportOutputPath,
 }: ExportDialogProps) {
-  // Live log capture is useful for any export path executed by the
-  // backend worker, including LoRA adapter-only export.
+  // Live log capture applies to any backend-worker export path, incl. LoRA-only.
   const showLogPanel =
     exportMethod === "merged" ||
     exportMethod === "gguf" ||
@@ -285,8 +269,7 @@ export function ExportDialog({
   const elapsedSeconds = useElapsedSeconds(exporting && showLogPanel);
 
   const logScrollRef = useRef<HTMLDivElement | null>(null);
-  // Auto-scroll to bottom whenever a new line arrives, unless the
-  // user has scrolled up to read earlier output.
+  // Auto-scroll to bottom on each new line, unless the user scrolled up.
   const [followTail, setFollowTail] = useState(true);
 
   useEffect(() => {
@@ -461,9 +444,8 @@ export function ExportDialog({
               )}
             </AnimatePresence>
 
-            {/* Success banner for log-driven exports.
-                Keep users on the log screen after completion so they can
-                inspect conversion output before closing. */}
+            {/* Success banner: keep users on the log screen after completion so
+                they can inspect conversion output before closing. */}
             {exportSuccess && showLogPanel && (
               <div className="flex items-start gap-2 rounded-lg bg-emerald-500/10 p-3 text-sm text-emerald-700 dark:text-emerald-300">
                 <HugeiconsIcon icon={CheckmarkCircle02Icon} className="mt-0.5 size-4 shrink-0" />
diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsx
index 233164b59a..b1a379b582 100644
--- a/studio/frontend/src/features/export/export-page.tsx
+++ b/studio/frontend/src/features/export/export-page.tsx
@@ -121,9 +121,8 @@ export function ExportPage() {
   const [exporting, setExporting] = useState(false);
   const [exportError, setExportError] = useState<string | null>(null);
   const [exportSuccess, setExportSuccess] = useState(false);
-  // Resolved on-disk path of the most recent successful export, surfaced
-  // on the Export Complete screen so the user can find their model
-  // without digging through the server log. Null for Hub-only pushes.
+  // On-disk path of the last successful export, shown on the Export Complete
+  // screen so the user can find their model. Null for Hub-only pushes.
   const [exportOutputPath, setExportOutputPath] = useState<string | null>(null);
 
   const hfComboboxAnchorRef = useRef<HTMLDivElement>(null);
@@ -438,11 +437,9 @@ export function ExportPage() {
         });
       }
 
-      // 2. Run export based on method. Capture the resolved output_path
-      // (when the backend wrote a local copy) so the success screen can
-      // show the user the realpath of their saved model. For multi-quant
-      // GGUF runs, the directory is the same for every quant so we just
-      // keep the last response.
+      // 2. Run export. Capture the resolved output_path (when the backend
+      // wrote a local copy) for the success screen. Multi-quant GGUF runs
+      // share one directory, so we just keep the last response.
       let lastOutputPath: string | null = null;
       if (exportMethod === "merged") {
         if (isAdapter) {
diff --git a/studio/frontend/src/features/onboarding/components/steps/hyperparameters-step.tsx b/studio/frontend/src/features/onboarding/components/steps/hyperparameters-step.tsx
index 337023ad33..a1174186af 100644
--- a/studio/frontend/src/features/onboarding/components/steps/hyperparameters-step.tsx
+++ b/studio/frontend/src/features/onboarding/components/steps/hyperparameters-step.tsx
@@ -39,10 +39,7 @@ function formatLR(value: number): string {
   return `${rounded}e${exp}`;
 }
 
-/**
- * Step learning rate up in a scientific-notation-friendly sequence:
- * 1e-4 -> 2e-4 -> 3e-4 -> ... -> 9e-4 -> 1e-3 -> 2e-3 -> ...
- */
+/** Step the LR in a scientific sequence: 1e-4 -> 2e-4 -> ... -> 9e-4 -> 1e-3 -> ... */
 function stepLR(value: number, direction: 1 | -1): number {
   if (value <= 0) return 1e-5;
   const exp = Math.floor(Math.log10(value) + 1e-9);
@@ -116,8 +113,7 @@ export function HyperparametersStep() {
   const maxStepsSliderMax = Math.max(500, maxSteps, 30);
   const epochsSliderMax = Math.max(10, epochs, 1);
 
-  // Use model's max_position_embeddings to cap context length options.
-  // Fall back to 65536 (64K) if not available.
+  // Cap context length by model's max_position_embeddings; fall back to 64K.
   const maxCtx = maxPositionEmbeddings ?? 65536;
   const contextLengthOptions = useMemo(
     () => CONTEXT_LENGTHS.filter((len) => len <= maxCtx),
diff --git a/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx b/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
index 52f61700e2..8e15fc6195 100644
--- a/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
+++ b/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
@@ -115,7 +115,7 @@ export function ModelSelectionStep() {
     return applyPriorityOrdering(ids);
   }, [hfResults]);
 
-  // Match Studio behavior: only show exception signals (OOM/TIGHT) in training flows.
+  // Match Studio: only show exception signals (OOM/TIGHT) in training flows.
   const vramMap = useMemo(() => {
     const fitMap = buildModelVramMap(
       hfResults,
diff --git a/studio/frontend/src/features/onboarding/components/steps/model-type-step.tsx b/studio/frontend/src/features/onboarding/components/steps/model-type-step.tsx
index 4ab9fedf10..2a286a8c80 100644
--- a/studio/frontend/src/features/onboarding/components/steps/model-type-step.tsx
+++ b/studio/frontend/src/features/onboarding/components/steps/model-type-step.tsx
@@ -192,7 +192,7 @@ export function ModelTypeStep(): ReactElement {
             )}
           >
             <CardContent className="flex items-center gap-4 py-4">
-              {/* Invisible spacer matching RadioGroupItem (size-4 flex) in other cards */}
+              {/* Invisible spacer matching RadioGroupItem (size-4) in other cards */}
               <div className="size-4 shrink-0" aria-hidden="true" />
               <div
                 className={cn(
diff --git a/studio/frontend/src/features/profile/utils/jwt-subject.ts b/studio/frontend/src/features/profile/utils/jwt-subject.ts
index 9c7596966a..a6b71811f6 100644
--- a/studio/frontend/src/features/profile/utils/jwt-subject.ts
+++ b/studio/frontend/src/features/profile/utils/jwt-subject.ts
@@ -1,9 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-/**
- * Read the JWT `sub` claim for display purposes only (not verified).
- */
+/** Read the JWT `sub` claim for display only (not verified). */
 export function decodeJwtSubject(token: string | null): string | null {
   if (!token) return null;
   try {
diff --git a/studio/frontend/src/features/profile/utils/resize-image-file.ts b/studio/frontend/src/features/profile/utils/resize-image-file.ts
index c420497395..7df5f45972 100644
--- a/studio/frontend/src/features/profile/utils/resize-image-file.ts
+++ b/studio/frontend/src/features/profile/utils/resize-image-file.ts
@@ -50,9 +50,7 @@ function encodeCanvasWithinLimit(
   return dataUrl.length <= MAX_DATA_URL_LENGTH ? dataUrl : null;
 }
 
-/**
- * Downscale the image and keep transparency when present while staying localStorage-friendly.
- */
+/** Downscale the image, preserving transparency, to stay localStorage-friendly. */
 export async function resizeImageFileToDataUrl(file: File): Promise<string> {
   const img = await loadImage(file);
   const w = img.naturalWidth;
diff --git a/studio/frontend/src/features/recipe-studio/components/executions/executions-view.tsx b/studio/frontend/src/features/recipe-studio/components/executions/executions-view.tsx
index cfc0e61338..3488ac0595 100644
--- a/studio/frontend/src/features/recipe-studio/components/executions/executions-view.tsx
+++ b/studio/frontend/src/features/recipe-studio/components/executions/executions-view.tsx
@@ -108,11 +108,9 @@ export function ExecutionsView({
     [datasetColumnNames, hiddenDatasetColumns],
   );
 
-  // Columns where at least one row has text long enough that it would wrap at
-  // the default narrow width. We give those columns a wider min-width so the
-  // text is readable without clicking anything. The table's wrapper already
-  // scrolls horizontally, so a few wide columns just add a horizontal
-  // scrollbar instead of squeezing everything into the viewport.
+  // Columns with at least one long-text row get a wider min-width so the text
+  // is readable without clicking. The wrapper scrolls horizontally, so wide
+  // columns just add a scrollbar instead of squeezing the viewport.
   const wideColumns = useMemo(() => {
     const result = new Set<string>();
     if (!selectedExecution) {
diff --git a/studio/frontend/src/features/recipe-studio/components/inline/inline-model.tsx b/studio/frontend/src/features/recipe-studio/components/inline/inline-model.tsx
index 1d98d18b56..b7354c1805 100644
--- a/studio/frontend/src/features/recipe-studio/components/inline/inline-model.tsx
+++ b/studio/frontend/src/features/recipe-studio/components/inline/inline-model.tsx
@@ -55,9 +55,9 @@ export function InlineModel(props: InlineModelProps): ReactElement {
     );
   }
 
-  // model_config branch - mirror the local-aware provider sync from the
-  // dialog path so inline edits clear stale local-only metadata without
-  // synthesizing the legacy "local" placeholder.
+  // model_config branch: mirror the dialog path's local-aware provider sync so
+  // inline edits clear stale local-only metadata without synthesizing the
+  // legacy "local" placeholder.
   const localNames = props.localProviderNames ?? new Set<string>();
   const modelConfig = props.config;
   const isLinkedToLocal = localNames.has(modelConfig.provider);
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
index 00b9fa1b46..9b91bfe334 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
@@ -556,8 +556,8 @@ export function LocalRecipeModelSelector({
             return;
           }
         } catch {
-          // Non-GGUF local models commonly have no variant endpoint. Fall
-          // through to regular selection so users can still choose them.
+          // Non-GGUF local models commonly have no variant endpoint;
+          // fall through to regular selection so they stay choosable.
         } finally {
           setProbingVariantModelId(null);
         }
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/models/model-config-dialog.tsx b/studio/frontend/src/features/recipe-studio/dialogs/models/model-config-dialog.tsx
index 68f912bc57..64f203fe4f 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/models/model-config-dialog.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/models/model-config-dialog.tsx
@@ -49,10 +49,8 @@ export function ModelConfigDialog({
   const skipHealthCheckId = `${config.id}-skip-health-check`;
   const providerAnchorRef = useRef<HTMLDivElement>(null);
   const providerInputRef = useRef(config.provider);
-  // Sync providerInputRef with the current provider value. Updating a ref in
-  // an effect (vs reading/writing it during render) satisfies the
-  // react-hooks/refs rule and keeps the combobox blur path stable across
-  // re-renders.
+  // Sync providerInputRef in an effect (not during render) to satisfy the
+  // react-hooks/refs rule and keep the combobox blur path stable.
   useEffect(() => {
     providerInputRef.current = config.provider;
   }, [config.provider]);
diff --git a/studio/frontend/src/features/recipe-studio/hooks/use-recipe-executions.ts b/studio/frontend/src/features/recipe-studio/hooks/use-recipe-executions.ts
index 19a6a3004d..f11fed6e13 100644
--- a/studio/frontend/src/features/recipe-studio/hooks/use-recipe-executions.ts
+++ b/studio/frontend/src/features/recipe-studio/hooks/use-recipe-executions.ts
@@ -563,10 +563,9 @@ export function useRecipeExecutions({
 
     resetForRecipe();
 
-    // Seed previewRows from the recipe's original run.rows (read from the
-    // loaded JSON, not the rebuilt payload (the builder hardcodes 5).
-    // Templates ship their own suggested preview size (e.g. GitHub Support
-    // Bot: 10); we honor it so users don't see a surprise 5.
+    // Seed previewRows from the recipe's original run.rows (the loaded JSON, not
+    // the rebuilt payload, which hardcodes 5). Templates ship a suggested preview
+    // size (e.g. GitHub Support Bot: 10); honor it so users don't see a surprise 5.
     if (
       typeof initialRunRows === "number" &&
       Number.isFinite(initialRunRows) &&
@@ -794,8 +793,8 @@ export function useRecipeExecutions({
       }
 
       // Flip to the Runs pane before validation starts. Validation can re-crawl
-      // the seed (multiple seconds for the github_repo reader), and runExecution()
-      // later no-ops this callback if the view has already been flipped.
+      // the seed (seconds for the github_repo reader); runExecution() later no-ops
+      // this callback if the view has already been flipped.
       onExecutionStart?.();
 
       const normalizedRows = sanitizeExecutionRows(rows, kind);
@@ -811,11 +810,11 @@ export function useRecipeExecutions({
         return false;
       }
 
-      // Recipe and Chat share one singleton local inference backend. This
-      // direct load is a point-in-time handoff to job creation, not a lease:
-      // if Chat swaps models after this succeeds, the backend will reject or
-      // run against the active backend state. A future generation token should
-      // be validated across this load and the `/jobs` loaded-model gate.
+      // Recipe and Chat share one singleton local inference backend. This direct
+      // load is a point-in-time handoff to job creation, not a lease: if Chat
+      // swaps models after this succeeds, the backend runs against current state.
+      // A future generation token should be validated across this load and the
+      // `/jobs` loaded-model gate.
       const restorePrevious = await prepareLocalModelForExecution(payload);
       if (restorePrevious === false) {
         return false;
diff --git a/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx b/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx
index c1001c0322..ec9358ee0f 100644
--- a/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx
+++ b/studio/frontend/src/features/recipe-studio/recipe-studio-page.tsx
@@ -78,16 +78,15 @@ const EDGE_TYPES: EdgeTypes = {
 const COMPLETE_ISLAND_VISIBLE_MS = 7_000;
 const TAB_SWITCH_FIT_DELAY_MS = 110;
 /**
- * Maximum RAF iterations to wait for React Flow's ResizeObserver to populate
- * `node.measured` dimensions before calling fitView. ~20 frames ≈ 333 ms at
- * 60 fps — more than enough for the render → layout → ResizeObserver cycle.
+ * Max RAF iterations to wait for React Flow's ResizeObserver to populate
+ * `node.measured` before calling fitView. ~20 frames ≈ 333 ms at 60 fps,
+ * ample for the render → layout → ResizeObserver cycle.
  */
 const MAX_FIT_VIEW_RETRIES = 20;
 /**
- * After all target nodes appear measured, wait this many extra stable frames
- * before firing fitView. This absorbs `updateNodeInternals` calls from
- * InternalsSync and individual node mount effects that can transiently reset
- * measurements.
+ * Extra stable frames to wait after target nodes appear measured before
+ * firing fitView, absorbing `updateNodeInternals` calls from InternalsSync
+ * and node mount effects that can transiently reset measurements.
  */
 const FIT_VIEW_STABLE_FRAMES = 3;
 
@@ -227,10 +226,10 @@ export function RecipeStudioPage({
     },
     [viewModeStorageKey],
   );
-  // Easy mode has no canvas overlay/progress island, so once a run starts the
-  // user sees the Run button stuck on "Running..." with nothing else changing.
-  // Flip to the Runs pane so they land where progress is actually rendered.
-  // Advanced (editor) keeps its island and stays put.
+  // Easy mode has no canvas overlay/progress island, so a started run would
+  // leave the Run button stuck on "Running..." with nothing else changing.
+  // Flip to the Runs pane where progress is rendered. Advanced (editor) keeps
+  // its island and stays put.
   const handleExecutionStart = useCallback(() => {
     setActiveView((currentView) =>
       currentView === "easy" ? "executions" : currentView,
@@ -396,10 +395,9 @@ export function RecipeStudioPage({
   const runBusy = previewLoading || fullLoading || executionLocked;
   const islandExecution = activeExecution ?? recentCompletedExecution;
 
-  // Easy mode runs a full run (artifact persisted, tracked in Runs pane)
-  // using runFull. runFull requires a non-empty fullRunName but the Easy form
-  // has no run-name input, so seed a default here as soon as Easy is active.
-  // User can still rename it from Advanced/Runs dialogs before clicking Run.
+  // Easy mode uses runFull (artifact persisted, tracked in Runs pane), which
+  // requires a non-empty fullRunName. The Easy form has no run-name input, so
+  // seed a default once Easy is active; user can rename from Advanced/Runs.
   useEffect(() => {
     if (!supportsEasyMode) return;
     if (activeView !== "easy") return;
@@ -527,22 +525,21 @@ export function RecipeStudioPage({
           return;
         }
         if (retries >= MAX_FIT_VIEW_RETRIES) {
-          // Timed out waiting — fit with whatever we have (graceful fallback).
+          // Timed out: fit with whatever we have (graceful fallback).
           doFit();
           return;
         }
         const targets = getFitViewTargetNodes(reactFlowInstance.getNodes());
         if (allTargetsMeasured(targets)) {
           stableCount++;
-          // Wait a few extra frames after measurements appear to let
-          // updateNodeInternals (InternalsSync, node mount effects) settle.
+          // Extra frames after measurements appear let updateNodeInternals
+          // (InternalsSync, node mount effects) settle.
           if (stableCount >= FIT_VIEW_STABLE_FRAMES) {
             doFit();
             return;
           }
         } else {
-          // Measurements were reset (e.g. by updateNodeInternals) — restart
-          // the stability counter.
+          // Measurements reset (e.g. by updateNodeInternals): restart counter.
           stableCount = 0;
         }
         retries++;
@@ -808,10 +805,9 @@ export function RecipeStudioPage({
                 updateConfig={updateConfig}
                 onRun={() => {
                   // Easy mode is a full run (artifact persisted, tracked in
-                  // the Runs pane) capped at the user's row count. runFull
-                  // requires a non-empty fullRunName; the effect below
-                  // populates one on mount so the closure in runFull is
-                  // already up to date by the time the user clicks Run.
+                  // Runs) capped at the user's row count. runFull requires a
+                  // non-empty fullRunName; the effect above populates one on
+                  // mount so runFull's closure is current by click time.
                   void runFull();
                 }}
                 runLoading={fullLoading || executionLocked}
diff --git a/studio/frontend/src/features/recipe-studio/stores/recipe-studio.ts b/studio/frontend/src/features/recipe-studio/stores/recipe-studio.ts
index 52ce1329bf..8659cad4fb 100644
--- a/studio/frontend/src/features/recipe-studio/stores/recipe-studio.ts
+++ b/studio/frontend/src/features/recipe-studio/stores/recipe-studio.ts
@@ -756,10 +756,9 @@ export const useRecipeStudioStore = create<RecipeStudioState>((set, get) => ({
         configs = applyRenameToConfigs(configs, oldName, newName);
       }
 
-      // When a provider toggles between local and external, keep already
-      // linked model_config nodes in sync. applyRenameToConfigs above has
-      // already propagated any name change, so providerName here is the
-      // post-rename value.
+      // When a provider toggles local/external, keep linked model_config nodes
+      // in sync. applyRenameToConfigs above already propagated any name change,
+      // so providerName here is the post-rename value.
       if (current.kind === "model_provider" && next.kind === "model_provider") {
         const prevIsLocal = current.is_local === true;
         const nextIsLocal = next.is_local === true;
diff --git a/studio/frontend/src/features/recipe-studio/utils/graph/fit-view.ts b/studio/frontend/src/features/recipe-studio/utils/graph/fit-view.ts
index a9da180db4..0ee541e02d 100644
--- a/studio/frontend/src/features/recipe-studio/utils/graph/fit-view.ts
+++ b/studio/frontend/src/features/recipe-studio/utils/graph/fit-view.ts
@@ -27,12 +27,9 @@ function isAuxNode(node: Node): boolean {
 /**
  * Returns the primary workflow nodes that fitView should target.
  *
- * Excludes markdown notes and aux (LLM input overlay) nodes so the viewport
- * is framed around the primary workflow blocks. Falls back to all nodes if
- * filtering would leave an empty set.
- *
- * The returned array contains full {@link Node} objects so callers can inspect
- * `node.measured` without a second lookup pass.
+ * Excludes markdown notes and aux (LLM input overlay) nodes; falls back to
+ * all nodes if filtering would leave an empty set. Returns full {@link Node}
+ * objects so callers can inspect `node.measured` without a second lookup.
  */
 export function getFitViewTargetNodes(nodes: Node[]): Node[] {
   const primary = nodes.filter(
@@ -42,9 +39,9 @@ export function getFitViewTargetNodes(nodes: Node[]): Node[] {
 }
 
 /**
- * Builds a standard {@link FitViewOptions} object targeting the primary
- * workflow nodes. Every call site that invokes `fitView` should go through
- * this helper so zoom, padding, and node filtering stay consistent.
+ * Builds a standard {@link FitViewOptions} targeting the primary workflow
+ * nodes. All `fitView` call sites go through this so zoom, padding, and
+ * node filtering stay consistent.
  */
 export function buildFitViewOptions(
   nodes: Node[],
diff --git a/studio/frontend/src/features/recipe-studio/utils/graph/recipe-graph-connection.ts b/studio/frontend/src/features/recipe-studio/utils/graph/recipe-graph-connection.ts
index 059ddf186f..25e4d848c2 100644
--- a/studio/frontend/src/features/recipe-studio/utils/graph/recipe-graph-connection.ts
+++ b/studio/frontend/src/features/recipe-studio/utils/graph/recipe-graph-connection.ts
@@ -387,10 +387,10 @@ export function applyRecipeConnection(
     nextBaseEdges,
   );
   if (source.kind === "model_provider" && target.kind === "model_config") {
-    // Keep model_config.provider in sync when a graph drag changes the link.
-    // Local providers now require an explicit selected load id; do not synthesize
-    // the legacy "local" placeholder. External relinks clear local-only GGUF
-    // metadata, while legacy placeholders are normalized back to empty.
+    // Keep model_config.provider in sync when a drag changes the link.
+    // Local providers need an explicit load id; don't synthesize the legacy
+    // "local" placeholder. External relinks clear local-only GGUF metadata;
+    // legacy placeholders normalize back to empty.
     const isSourceLocal = source.is_local === true;
     const isLegacyLocalPlaceholder =
       target.model.trim().toLowerCase() === "local";
diff --git a/studio/frontend/src/features/recipe-studio/utils/layout.ts b/studio/frontend/src/features/recipe-studio/utils/layout.ts
index 6b357c9028..3b76900e73 100644
--- a/studio/frontend/src/features/recipe-studio/utils/layout.ts
+++ b/studio/frontend/src/features/recipe-studio/utils/layout.ts
@@ -17,10 +17,7 @@ type LayoutOptions = {
   configs?: Record<string, NodeConfig>;
 };
 
-/**
- * Pipeline rank order used to enforce a logical flow even for disconnected nodes.
- * Lower rank = earlier in the pipeline.
- */
+/** Pipeline rank for logical flow; lower = earlier. */
 function getPipelineRank(config: NodeConfig | undefined): number {
   if (!config) {
     return 2;
@@ -65,17 +62,15 @@ function getEdgeWeight(edgeType: string | undefined): number {
 
 /**
  * Build phantom edges between disconnected data-pipeline nodes so dagre
- * respects the pipeline rank order even when blocks aren't wired together.
- *
- * Groups nodes by rank, then inserts invisible edges from the last node of
- * rank N to the first node of rank N+1 when no real edge already connects them.
+ * respects pipeline rank order even when blocks aren't wired together.
+ * Groups by rank, then inserts invisible edges from the last node of rank N
+ * to the first of rank N+1 when no real edge already connects them.
  */
 function buildPhantomEdges(
   nodes: Node[],
   edges: Edge[],
   configs: Record<string, NodeConfig>,
 ): Edge[] {
-  // Group nodes by rank
   const byRank = new Map<number, string[]>();
   for (const node of nodes) {
     const rank = getPipelineRank(configs[node.id]);
@@ -94,7 +89,6 @@ function buildPhantomEdges(
       continue;
     }
 
-    // Check if any real edge already connects these rank groups
     const hasRealEdge = edges.some(
       (e) => currentIds.includes(e.source) && nextIds.includes(e.target),
     );
@@ -102,7 +96,7 @@ function buildPhantomEdges(
       continue;
     }
 
-    // Insert one phantom edge from last node in current rank to first in next
+    // One phantom edge: last node in current rank to first in next.
     phantoms.push({
       id: `phantom-${ranks[i]}-${ranks[i + 1]}`,
       source: currentIds[currentIds.length - 1],
@@ -129,7 +123,7 @@ export function getLayoutedElements<TNode extends Node>(
     configs,
   } = options;
 
-  // When configs are provided, filter out infra and aux nodes from dagre
+  // With configs, filter infra and aux nodes out of dagre.
   const hasConfigs = configs && Object.keys(configs).length > 0;
   const dataNodes = hasConfigs
     ? nodes.filter((n) => !(isInfraNode(n.id, configs) || isAuxNode(n.id)))
@@ -146,7 +140,7 @@ export function getLayoutedElements<TNode extends Node>(
       )
     : edges;
 
-  // Build phantom edges to enforce pipeline rank ordering for disconnected nodes
+  // Phantom edges enforce rank ordering for disconnected nodes.
   const phantomEdges = hasConfigs
     ? buildPhantomEdges(dataNodes, dataEdges, configs)
     : [];
@@ -175,7 +169,7 @@ export function getLayoutedElements<TNode extends Node>(
 
   dagre.layout(graph);
 
-  // Build position map from dagre results (data nodes only)
+  // Position map from dagre results (data nodes only).
   const layoutedPositions = new Map<string, { x: number; y: number }>();
   for (const node of dataNodes) {
     const pos = graph.node(node.id);
@@ -187,7 +181,7 @@ export function getLayoutedElements<TNode extends Node>(
     });
   }
 
-  // Apply positions: data nodes get dagre positions, infra/aux keep original
+  // Data nodes get dagre positions; infra/aux keep original.
   const layoutedNodes = nodes.map((node) => {
     const position = layoutedPositions.get(node.id);
     if (!position) {
diff --git a/studio/frontend/src/features/recipe-studio/utils/payload/builders-model.ts b/studio/frontend/src/features/recipe-studio/utils/payload/builders-model.ts
index 1575919705..0a85ef618f 100644
--- a/studio/frontend/src/features/recipe-studio/utils/payload/builders-model.ts
+++ b/studio/frontend/src/features/recipe-studio/utils/payload/builders-model.ts
@@ -8,11 +8,10 @@ export function buildModelProvider(
   config: ModelProviderConfig,
   errors: string[],
 ): Record<string, unknown> {
-  // Local providers do not use any of the advanced request overrides -
-  // the backend overrides endpoint/api_key/provider_type and strips the
-  // extra fields in _inject_local_providers. Skip parsing the hidden
-  // JSON inputs here so imported or hydrated recipes with stale extra
-  // headers/body cannot block the client-side validation step.
+  // Local providers ignore advanced request overrides: the backend overrides
+  // endpoint/api_key/provider_type and strips extras in _inject_local_providers.
+  // Skip parsing hidden JSON inputs so stale headers/body in imported recipes
+  // can't block client-side validation.
   if (config.is_local === true) {
     return {
       name: config.name,
diff --git a/studio/frontend/src/features/recipe-studio/utils/payload/builders-sampler.ts b/studio/frontend/src/features/recipe-studio/utils/payload/builders-sampler.ts
index 596450d1e1..70e345f3b3 100644
--- a/studio/frontend/src/features/recipe-studio/utils/payload/builders-sampler.ts
+++ b/studio/frontend/src/features/recipe-studio/utils/payload/builders-sampler.ts
@@ -134,7 +134,7 @@ function buildSamplerParams(
     if (!raw) {
       return {};
     }
-    // UI historically used "uuid4" as a "format". data_designer uuid sampler is always uuid4.
+    // UI historically used "uuid4" as a format; data_designer uuid is always uuid4.
     if (raw.toLowerCase() === "uuid4") {
       return {};
     }
diff --git a/studio/frontend/src/features/settings/components/create-key-form.tsx b/studio/frontend/src/features/settings/components/create-key-form.tsx
index 93802bfad8..c375bc280c 100644
--- a/studio/frontend/src/features/settings/components/create-key-form.tsx
+++ b/studio/frontend/src/features/settings/components/create-key-form.tsx
@@ -36,9 +36,8 @@ export function CreateKeyForm({
       onCreated(result.key);
       setName("");
     } catch {
-      // API helpers in ../api/api-keys.ts throw generic English Error
-      // messages; always use the translated message so zh-CN users do not
-      // see English text bleed through from internal exceptions.
+      // api-keys.ts throws English Error messages; use the translated one so
+      // zh-CN users don't see English bleed through from internal exceptions.
       onError(t("settings.apiKeys.createError"));
     } finally {
       setLoading(false);
diff --git a/studio/frontend/src/features/settings/settings-dialog.tsx b/studio/frontend/src/features/settings/settings-dialog.tsx
index a1048b202e..26efcde7ea 100644
--- a/studio/frontend/src/features/settings/settings-dialog.tsx
+++ b/studio/frontend/src/features/settings/settings-dialog.tsx
@@ -116,21 +116,20 @@ export function SettingsDialog() {
         showCloseButton={false}
         overlayClassName="bg-background/40"
         onCloseAutoFocus={(e) => {
-          // Restore focus to the element that triggered openDialog().
-          // Radix's FocusScope races our rAF-scheduled tab-button focus
-          // and loses the previous-focus reference, so we restore by hand.
+          // Restore focus to the element that triggered openDialog(). Radix's
+          // FocusScope races our rAF-scheduled tab focus and loses the
+          // previous-focus reference, so restore it by hand.
           if (opener && opener.isConnected) {
             e.preventDefault();
             opener.focus({ preventScroll: true });
           }
         }}
         className={cn(
-          // Cap at 820px but shrink to the viewport so we don't clip
-          // on iPad-portrait widths (640-820px) where the fixed
-          // `w-[820px]` overflows by 26px on each side.
+          // Cap at 820px but shrink to the viewport so it doesn't clip on
+          // iPad-portrait widths (640-820px) where fixed `w-[820px]` overflows.
           "settings-surface !max-w-[min(820px,calc(100vw-2rem))] h-[560px] w-[min(820px,calc(100vw-2rem))] p-0 overflow-hidden",
-          // Soft shadow only, no outline ring. Pin --radius to the light value
-          // so the corner rounding is the same in dark mode.
+          // Soft shadow, no outline ring. Pin --radius to the light value so
+          // corner rounding matches in dark mode.
           "shadow-border rounded-xl ring-0 [--radius:1.1rem]",
           "max-sm:h-dvh max-sm:w-dvw max-sm:!max-w-none max-sm:rounded-none",
         )}
diff --git a/studio/frontend/src/features/settings/stores/settings-dialog-store.ts b/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
index 7ac5422ff1..1f4ac9c372 100644
--- a/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
+++ b/studio/frontend/src/features/settings/stores/settings-dialog-store.ts
@@ -15,10 +15,10 @@ export type SettingsTab =
 interface SettingsDialogState {
   open: boolean;
   activeTab: SettingsTab;
-  // Element focused at the moment openDialog() ran. Radix's FocusScope
-  // would normally track this, but the rAF-scheduled focus() in
-  // settings-dialog.tsx races its previous-focus capture, leaving focus
-  // on <body> after close. We restore explicitly via onCloseAutoFocus.
+  // Element focused when openDialog() ran. Radix's FocusScope normally tracks
+  // this, but the rAF-scheduled focus() in settings-dialog.tsx races its
+  // previous-focus capture, leaving focus on <body> after close. We restore
+  // explicitly via onCloseAutoFocus.
   opener: HTMLElement | null;
   openDialog: (tab?: SettingsTab) => void;
   closeDialog: () => void;
diff --git a/studio/frontend/src/features/settings/stores/theme-store.ts b/studio/frontend/src/features/settings/stores/theme-store.ts
index f73fc51e1c..9d05582c77 100644
--- a/studio/frontend/src/features/settings/stores/theme-store.ts
+++ b/studio/frontend/src/features/settings/stores/theme-store.ts
@@ -32,9 +32,8 @@ function resolveTheme(theme: Theme): ResolvedTheme {
 
 function applyToDocument(resolved: ResolvedTheme) {
   if (typeof document === "undefined") return;
-  // Keep "dark"/"light" mutually exclusive. next-themes (via Sonner)
-  // adds "light" on first mount; without the explicit toggle we'd end
-  // up with `class="light dark"` after a switch.
+  // Keep "dark"/"light" mutually exclusive: next-themes (via Sonner) adds
+  // "light" on first mount, so without this toggle we'd get "light dark".
   const cl = document.documentElement.classList;
   cl.toggle("dark", resolved === "dark");
   cl.toggle("light", resolved === "light");
@@ -72,15 +71,14 @@ function getServerSnapshot(): Theme {
 }
 
 /**
- * Single source of truth for setting the theme. All writers (the Settings
- * dialog's segmented control AND the sidebar dropdown's animated toggler)
- * must route through this so the DOM class, localStorage, and React
- * subscribers stay in sync.
+ * Single source of truth for setting the theme. All writers (Settings dialog
+ * control, sidebar dropdown toggler) route through this so the DOM class,
+ * localStorage, and React subscribers stay in sync.
  */
 export function setTheme(next: Theme): void {
   if (typeof window === "undefined") return;
-  // Persist "system" explicitly so next-themes (mounted with
-  // defaultTheme="light") doesn't clobber the choice on reload.
+  // Persist "system" explicitly so next-themes (defaultTheme="light")
+  // doesn't clobber the choice on reload.
   try {
     window.localStorage.setItem(STORAGE_KEY, next);
   } catch {
diff --git a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
index d562b585b1..601a81b799 100644
--- a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
@@ -32,9 +32,8 @@ export function ApiKeysTab() {
     ? { duration: 0 }
     : { duration: 0.18, ease: [0.165, 0.84, 0.44, 1] as const };
 
-  // API helpers in ../api/api-keys.ts throw generic English Error messages
-  // ("Failed to load API access", etc.). Always use the translated message
-  // so zh-CN users do not see those English strings bleed through.
+  // ../api/api-keys.ts throws generic English errors; use the translated
+  // message so zh-CN users don't see English strings bleed through.
   const load = useCallback(async () => {
     setLoading(true);
     setError(null);
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index aaaf0a7115..57a52b83d1 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -30,15 +30,10 @@ import { SettingsRow } from "../components/settings-row";
 import { SettingsSection } from "../components/settings-section";
 
 // Keys cleared by "Reset all local preferences".
-//
-// NEVER include auth / session keys here — resetting them would log the user
-// out, which is not what users expect from a "reset preferences" button.
-//
-// Explicitly EXCLUDED:
-//   - "unsloth_auth_token"                 (auth: access token)
-//   - "unsloth_auth_refresh_token"         (auth: refresh token)
-//   - "unsloth_auth_must_change_password"  (auth: forced password change flag)
-//   - "unsloth_onboarding_done"            (session: would force re-onboarding)
+// NEVER include auth/session keys here — clearing them would log the user out
+// or force re-onboarding. Explicitly excluded: unsloth_auth_token,
+// unsloth_auth_refresh_token, unsloth_auth_must_change_password,
+// unsloth_onboarding_done.
 const PREFS_KEYS: string[] = [
   // Appearance
   "theme",
@@ -70,10 +65,8 @@ const PREFS_KEYS: string[] = [
   "tour:studio:v1",
 ];
 
-// Set to true from resetAllPrefs so the unmount-commit effect skips writing
-// back the in-memory draft — otherwise the cleanup would re-persist the old
-// HF token into localStorage after it was just cleared, and the subsequent
-// reload would read the re-written value.
+// Set by resetAllPrefs so the unmount-commit effect skips writing back the
+// in-memory draft, else cleanup would re-persist the just-cleared HF token.
 let resetInProgress = false;
 
 function resetAllPrefs() {
diff --git a/studio/frontend/src/features/studio/historical-training-view.tsx b/studio/frontend/src/features/studio/historical-training-view.tsx
index 504e251bc5..e958f2ba0d 100644
--- a/studio/frontend/src/features/studio/historical-training-view.tsx
+++ b/studio/frontend/src/features/studio/historical-training-view.tsx
@@ -95,7 +95,7 @@ export function HistoricalTrainingView({
   const [detail, setDetail] = useState<TrainingRunDetailResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
 
-  // Derive loading from detail/error -- no separate state needed
+  // Derive loading from detail/error; no separate state.
   const loading = detail === null && error === null;
 
   useEffect(() => {
@@ -114,7 +114,7 @@ export function HistoricalTrainingView({
       });
     return () => {
       controller.abort();
-      // Reset on runId change so loading derives correctly for the next fetch
+      // Reset on runId change so loading derives correctly for the next fetch.
       setDetail(null);
       setError(null);
     };
diff --git a/studio/frontend/src/features/studio/history-card-grid.tsx b/studio/frontend/src/features/studio/history-card-grid.tsx
index 75ec43f20d..dbe7fff01b 100644
--- a/studio/frontend/src/features/studio/history-card-grid.tsx
+++ b/studio/frontend/src/features/studio/history-card-grid.tsx
@@ -125,7 +125,7 @@ function Sparkline({
   const w = 120;
   const gradientId = `sparkFill-${id}`;
 
-  // Build points with vertical padding so the stroke isn't clipped
+  // Vertical padding so the stroke isn't clipped.
   const pts = values.map((v, i) => ({
     x: (i / (values.length - 1)) * w,
     y: pad + (1 - (v - min) / range) * (h - pad * 2),
@@ -206,7 +206,7 @@ export function HistoryCardGrid({
   }, [runs.length]);
 
   const fetchRuns = useCallback(async (offset = 0, append = false, limit = PAGE_SIZE) => {
-    // Cancel any in-flight poll so its stale response can't clobber this fresher fetch
+    // Cancel any in-flight poll so its stale response can't clobber this fetch.
     pollControllerRef.current?.abort();
     userControllerRef.current?.abort();
     const controller = new AbortController();
@@ -261,7 +261,7 @@ export function HistoryCardGrid({
     };
   }, [fetchRuns]);
 
-  // Poll while any run is still "running" so the card shows live progress
+  // Poll while any run is "running" so cards show live progress.
   const hasRunningRun = runs.some((r) => r.status === "running");
   const visibleCount = runs.length;
   useEffect(() => {
@@ -275,11 +275,11 @@ export function HistoryCardGrid({
       try {
         const limit = Math.max(PAGE_SIZE, visibleCount);
         const result = await listTrainingRuns(limit, 0, controller.signal);
-        if (pollIdRef.current !== pid) return; // stale poll — discard
+        if (pollIdRef.current !== pid) return; // stale poll
         setRuns(result.runs);
         setTotal(result.total);
       } catch {
-        // silently handle — poll will retry
+        // ignore; poll will retry
       }
     }, RUNNING_POLL_INTERVAL_MS);
     return () => {
@@ -294,11 +294,11 @@ export function HistoryCardGrid({
     try {
       await deleteTrainingRun(deleteTarget);
       emitTrainingRunDeleted(deleteTarget);
-      // Re-fetch preserving visible count so offsets stay consistent for "Load more"
+      // Re-fetch preserving visible count so "Load more" offsets stay consistent.
       const currentCount = runs.length - 1;
       const limit = Math.max(PAGE_SIZE, currentCount);
       fetchRuns(0, false, limit).catch(() => {
-        // Refresh failed — card is already removed, no stale display
+        // Refresh failed; card is already removed, no stale display.
       });
     } catch {
       setDeleteError(translate("studio.history.deleteError"));
diff --git a/studio/frontend/src/features/studio/sections/dataset-preview-dialog-mapping.tsx b/studio/frontend/src/features/studio/sections/dataset-preview-dialog-mapping.tsx
index 4a99c4f702..4f9ea2c98f 100644
--- a/studio/frontend/src/features/studio/sections/dataset-preview-dialog-mapping.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-preview-dialog-mapping.tsx
@@ -303,8 +303,8 @@ const FROM_CANONICAL: Record<string, Record<string, string>> = {
 };
 
 /**
- * Remap a column→role mapping between formats.
- * Normalises every role to canonical chatml first, then maps to the target format.
+ * Remap a column→role mapping between formats: normalise to canonical chatml,
+ * then map to the target format.
  */
 export function remapRolesForFormat(
   mapping: Record<string, string>,
diff --git a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
index d05a8cf242..6710099400 100644
--- a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
@@ -86,8 +86,7 @@ export function DatasetPreviewDialog({
   );
   const { isStarting, startError, startTrainingRun } = useTrainingActions();
 
-  // If the backend reports image data, treat as VLM even if the prop
-  // hasn't caught up yet (isDatasetImage may still be null in the store).
+  // Treat backend-reported image data as VLM even if the prop hasn't caught up.
   const effectiveIsAudio = !!data?.is_audio;
   const effectiveIsVlm = isVlm || !!data?.is_image;
 
@@ -119,7 +118,7 @@ export function DatasetPreviewDialog({
       });
 
       if (result.success && result.suggested_mapping) {
-        // Remap from chatml roles (user/assistant/system) to format-specific roles
+        // Remap chatml roles to format-specific roles
         const table = ROLE_REMAP[datasetFormat];
         const mapped: Record<string, string> = {};
         for (const [col, role] of Object.entries(result.suggested_mapping)) {
@@ -155,14 +154,12 @@ export function DatasetPreviewDialog({
     setManualMapping(remapRolesForFormat(manualMapping, datasetFormat));
   }, [datasetFormat]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Handle role change for a column
   const handleRoleChange = useCallback(
     (colName: string, role: string | undefined) => {
       const next = { ...manualMapping };
-      // Remove this column's previous role
       delete next[colName];
       if (role) {
-        // Remove any other column that had this role (each role can only be assigned once)
+        // Each role maps to one column, so drop any other column holding it
         for (const [col, r] of Object.entries(next)) {
           if (r === role) delete next[col];
         }
@@ -230,7 +227,6 @@ export function DatasetPreviewDialog({
   const rows = data?.preview_samples ?? [];
   const columns = data?.columns ?? [];
 
-  // Determine source label
   const sourceLabel = useMemo(() => {
     if (!datasetName) return "";
     if (datasetSource === "huggingface") {
@@ -243,7 +239,6 @@ export function DatasetPreviewDialog({
     return `Local Files (${datasetName})`;
   }, [datasetName, datasetSource, datasetSubset, datasetSplit]);
 
-  // Build TanStack Table columns from the column names
   const tableColumns = useMemo<ColumnDef<Record<string, unknown>>[]>(() => {
     if (!columns.length) return [];
 
@@ -507,10 +502,7 @@ export function DatasetPreviewDialog({
   );
 }
 
-// ---------------------------------------------------------------------------
 // Metadata row
-// ---------------------------------------------------------------------------
-
 function MetaRow({
   label,
   value,
diff --git a/studio/frontend/src/features/studio/sections/model-section.tsx b/studio/frontend/src/features/studio/sections/model-section.tsx
index 055437a1f5..cc5717692a 100644
--- a/studio/frontend/src/features/studio/sections/model-section.tsx
+++ b/studio/frontend/src/features/studio/sections/model-section.tsx
@@ -233,12 +233,8 @@ export function ModelSection() {
     });
   }, [localMetaById, localModelInput, localResultIds]);
 
-  // Pre-compute VRAM fit status for every model in the current result set.
-  // Keyed by model id so the render callback is a simple O(1) lookup.
-  //
-  // Pre-compute VRAM fit status for every model in the current result set.
-  // Keyed by model id so the render callback is a simple O(1) lookup.
-  // Re-computes when the training method changes (QLoRA=4-bit vs LoRA/Full=fp16).
+  // VRAM fit status per model, keyed by id for O(1) render lookups.
+  // Recomputes on training-method change (QLoRA=4-bit vs LoRA/Full=fp16).
   const vramMap = useMemo(() => {
     const fitMap = buildModelVramMap(
       hfResults,
diff --git a/studio/frontend/src/features/studio/sections/progress-section.tsx b/studio/frontend/src/features/studio/sections/progress-section.tsx
index f52f3bcb99..67800df27b 100644
--- a/studio/frontend/src/features/studio/sections/progress-section.tsx
+++ b/studio/frontend/src/features/studio/sections/progress-section.tsx
@@ -122,7 +122,7 @@ export function ProgressSection({
   const [stopDialogOpen, setStopDialogOpen] = useState(false);
   const [stopRequestedLocal, setStopRequestedLocal] = useState(false);
 
-  // Auto-reset when training stops -- no useEffect needed
+  // Auto-resets when training stops; no useEffect needed
   const stopRequested = data.isTrainingRunning && stopRequestedLocal;
 
   const pct =
diff --git a/studio/frontend/src/features/studio/sections/training-section.tsx b/studio/frontend/src/features/studio/sections/training-section.tsx
index adeb1a7b14..d1ef132efb 100644
--- a/studio/frontend/src/features/studio/sections/training-section.tsx
+++ b/studio/frontend/src/features/studio/sections/training-section.tsx
@@ -81,15 +81,14 @@ export function TrainingSection() {
   };
 
   const handleSaveConfig = () => {
-    // isDatasetImage is null in three windows: before a dataset check
-    // completes, after dataset edits, and on import. Treat all three as
-    // "save it" so the user's choice is never silently dropped while we
-    // wait to confirm the dataset type. Only a confirmed text-only dataset
+    // isDatasetImage is null before a dataset check completes, after edits, and
+    // on import. Treat all three as "save it" so the user's choice isn't dropped
+    // while the type is unconfirmed. Only a confirmed text-only dataset
     // (=== false) suppresses the vision fields.
     const includeVisionFields =
       store.isVisionModel && store.isDatasetImage !== false;
-    // DeepSeek OCR ignores vision_image_size; don't emit it to YAML either,
-    // or a later import on a non-DeepSeek model would activate the stale value.
+    // DeepSeek OCR ignores vision_image_size; don't emit it, or a later import
+    // on a non-DeepSeek model would activate the stale value.
     const selectedModelLower = (store.selectedModel ?? "").toLowerCase();
     const isDeepseekOcr =
       selectedModelLower.includes("deepseek") &&
diff --git a/studio/frontend/src/features/studio/studio-page.tsx b/studio/frontend/src/features/studio/studio-page.tsx
index d5368fba58..4635a6ce0e 100644
--- a/studio/frontend/src/features/studio/studio-page.tsx
+++ b/studio/frontend/src/features/studio/studio-page.tsx
@@ -61,9 +61,9 @@ export function StudioPage(): ReactElement {
     return () => setSelectedHistoryRunId(null);
   }, [setSelectedHistoryRunId]);
 
-  // Derive activeTab: auto-switch to "current-run" only while training is
-  // genuinely running.  Once training ends, honour whatever tab the user clicks.
-  // If requestedTab is "current-run" but there's nothing to show, fall back to "configure".
+  // Auto-switch to "current-run" only while training runs; afterward honour
+  // the user's clicked tab. If "current-run" has nothing to show, use
+  // "configure".
   const activeTab =
     isTrainingRunning && requestedTab !== "history"
       ? "current-run"
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index 0205394a53..ba80432896 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -38,9 +38,8 @@ import { useT } from "@/i18n";
 const HF_REPO_REGEX = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 
 // Tracks which jobs have already played the terminal intro animation. The
-// overlay unmounts when you navigate away from the training page, so without
-// this its typing/fade-in would replay on every return even though the run
-// itself is still going. Module-level so it survives remounts.
+// overlay unmounts on navigation away, so without this its typing/fade-in would
+// replay on every return mid-run. Module-level so it survives remounts.
 const animatedJobs = new Set<string>();
 
 function formatBytes(n: number): string {
@@ -90,12 +89,9 @@ function coerceCachedStateReady(state: DownloadState): DownloadState {
 type Fetcher = (repoId: string) => Promise<DownloadProgressResponse>;
 
 /**
- * Polls a HF repo's download progress on a 1.5s tick. Used for both
- * model weights (`/api/models/download-progress`) and dataset blobs
- * (`/api/datasets/download-progress`) by swapping the fetcher.
- *
- * Stops polling once `progress >= 1.0` -- the bar freezes at the final
- * value rather than disappearing, mirroring the existing chat flow.
+ * Polls a HF repo's download progress on a 1.5s tick. Serves both model weights
+ * and dataset blobs by swapping the fetcher. Stops once `progress >= 1.0`; the
+ * bar freezes at the final value rather than disappearing, matching chat flow.
  */
 function useHfDownloadProgress(
   repoId: string | null,
@@ -179,9 +175,8 @@ type DownloadRowProps = {
 
 function DownloadRow({ label, state }: DownloadRowProps): ReactElement | null {
   const t = useT();
-  // Compute a rolling-window rate + ETA from the same cumulative-byte
-  // series the poll hook already produces, so we can show
-  // "5.2 / 20.7 GB • 85.3 MB/s • 3m 12s left" instead of just the pair.
+  // Rolling-window rate + ETA from the cumulative-byte series the poll hook
+  // produces, so we show "5.2 / 20.7 GB • 85.3 MB/s • 3m 12s left", not just the pair.
   const stats = useTransferStats(state.downloadedBytes, state.totalBytes);
 
   if (state.downloadedBytes <= 0 && !state.cachePath) return null;
@@ -267,8 +262,8 @@ export function TrainingStartOverlay({
   const configuredModel = useTrainingConfigStore((s) => s.selectedModel);
   const datasetSource = useTrainingConfigStore((s) => s.datasetSource);
   const dataset = useTrainingConfigStore((s) => s.dataset);
-  // Only HF datasets have a download phase to track. Uploaded files are
-  // already on disk by the time the overlay shows up.
+  // Only HF datasets have a download phase to track; uploaded files are already
+  // on disk by the time the overlay shows up.
   const hfDatasetName = datasetSource === "huggingface" ? dataset : null;
   const hasStartResources = startModelName !== null;
   const useConfiguredResources = !isStarting && !hasStartResources;
@@ -305,9 +300,8 @@ export function TrainingStartOverlay({
     }
   }, [isStarting]);
 
-  // Play the intro animation only the first time we mount for a given job.
-  // On later remounts (e.g. leaving the training page and coming back) the
-  // terminal renders its final state instantly so the logs don't restart.
+  // Play the intro animation only on the first mount per job. On later remounts
+  // the terminal renders its final state instantly so the logs don't restart.
   const alreadyAnimated = jobId != null && animatedJobs.has(jobId);
   useEffect(() => {
     if (jobId != null) {
diff --git a/studio/frontend/src/features/tour/lib/confetti-fireworks.ts b/studio/frontend/src/features/tour/lib/confetti-fireworks.ts
index 1904436c69..6eaf8e031e 100644
--- a/studio/frontend/src/features/tour/lib/confetti-fireworks.ts
+++ b/studio/frontend/src/features/tour/lib/confetti-fireworks.ts
@@ -11,10 +11,9 @@ type FireworksOpts = {
   zIndex?: number;
 };
 
-// CSP blocks canvas-confetti's default blob: worker, so reuse a single
-// overlay canvas via `confetti.create(..., { useWorker: false })`.
-// Caller-provided canvases ignore the per-fire `zIndex`; stacking is
-// driven by `_sharedCanvas.style.zIndex` instead (set in fireConfettiFireworks).
+// CSP blocks canvas-confetti's default blob: worker, so reuse a single overlay
+// canvas via `confetti.create(..., { useWorker: false })`. Caller canvases
+// ignore per-fire `zIndex`; stacking is driven by `_sharedCanvas.style.zIndex`.
 const DEFAULT_FIREWORKS_Z_INDEX = 99999;
 let _sharedCanvas: HTMLCanvasElement | null = null;
 let _sharedFire: ConfettiInstance | null = null;
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index 8fecfaf7b8..1e9a135fd3 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -92,10 +92,7 @@ interface LocalModelListResponse {
   models: LocalModelInfo[];
 }
 
-/**
- * Check whether a model is a vision model by asking the backend.
- * Calls GET /api/models/check-vision/{model_name}.
- */
+/** Ask the backend whether a model is a vision model (GET /api/models/check-vision/{model_name}). */
 export async function checkVisionModel(modelName: string): Promise<boolean> {
   const encoded = encodeURIComponent(modelName);
   const response = await authFetch(`/api/models/check-vision/${encoded}`);
@@ -107,10 +104,7 @@ export async function checkVisionModel(modelName: string): Promise<boolean> {
   return data.is_vision;
 }
 
-/**
- * Check whether a model is an embedding model by asking the backend.
- * Calls GET /api/models/check-embedding/{model_name}.
- */
+/** Ask the backend whether a model is an embedding model (GET /api/models/check-embedding/{model_name}). */
 export async function checkEmbeddingModel(
   modelName: string,
 ): Promise<boolean> {
diff --git a/studio/frontend/src/features/training/hooks/use-training-actions.ts b/studio/frontend/src/features/training/hooks/use-training-actions.ts
index 3d2cb64022..8069ff9bbf 100644
--- a/studio/frontend/src/features/training/hooks/use-training-actions.ts
+++ b/studio/frontend/src/features/training/hooks/use-training-actions.ts
@@ -75,8 +75,8 @@ export function useTrainingActions() {
           isVlm,
         });
 
-        // Backend auto-detects image/audio from dataset content.
-        // Sync these flags into the store so buildTrainingStartPayload picks them up.
+        // Backend auto-detects image/audio from dataset content; sync the flags
+        // into the store so buildTrainingStartPayload picks them up.
         const isAudio = !!check.is_audio;
         const isImage = !!check.is_image;
 
diff --git a/studio/frontend/src/features/training/hooks/use-training-history-sidebar.ts b/studio/frontend/src/features/training/hooks/use-training-history-sidebar.ts
index 92ffd68466..6569214c40 100644
--- a/studio/frontend/src/features/training/hooks/use-training-history-sidebar.ts
+++ b/studio/frontend/src/features/training/hooks/use-training-history-sidebar.ts
@@ -60,9 +60,8 @@ export function useTrainingHistorySidebarItems(enabled: boolean) {
     }
   }, [fetchRuns]);
 
-  // Initial load: bounded retry-with-backoff, then surface a toast on
-  // final failure with a Retry action so the user isn't stuck staring
-  // at an empty sidebar after F5 if the backend was slow to come up.
+  // Initial load: bounded retry-with-backoff, then a toast with Retry on final
+  // failure so the user isn't stuck on an empty sidebar if the backend is slow.
   useEffect(() => {
     if (!enabled) {
       return;
@@ -124,10 +123,9 @@ export function useTrainingHistorySidebarItems(enabled: boolean) {
     };
   }, [enabled, fetchRuns]);
 
-  // Poll while there's a running run, but only when the tab is visible.
-  // Browsers throttle background timers but don't pause them — gating on
-  // visibility avoids hammering the API for tabs left open in the
-  // background, which is common during long training runs.
+  // Poll while a run is active, but only when the tab is visible. Browsers
+  // throttle background timers but don't pause them, so gating on visibility
+  // avoids hammering the API for tabs left open during long training runs.
   const hasRunning = items.some((r) => r.status === "running");
   useEffect(() => {
     if (!enabled || !hasRunning) {
diff --git a/studio/frontend/src/features/training/hooks/use-training-unload-guard.ts b/studio/frontend/src/features/training/hooks/use-training-unload-guard.ts
index 1808cf5888..879200ade3 100644
--- a/studio/frontend/src/features/training/hooks/use-training-unload-guard.ts
+++ b/studio/frontend/src/features/training/hooks/use-training-unload-guard.ts
@@ -31,10 +31,9 @@ export function useTrainingUnloadGuard() {
 }
 
 /**
- * Removes the active beforeunload guard (if any).
- * Call this before intentionally ending the session (e.g. shutting down
- * the Studio server) so the "Server stopped" page can render without
- * the browser prompting the user to confirm leaving.
+ * Removes the active beforeunload guard (if any). Call before intentionally
+ * ending the session (e.g. shutting down the server) so the "Server stopped"
+ * page renders without the browser prompting to confirm leaving.
  */
 export function removeTrainingUnloadGuard() {
   if (currentHandler) {
diff --git a/studio/frontend/src/features/training/lib/yaml-config.ts b/studio/frontend/src/features/training/lib/yaml-config.ts
index 1deabf3547..d25f5a56f8 100644
--- a/studio/frontend/src/features/training/lib/yaml-config.ts
+++ b/studio/frontend/src/features/training/lib/yaml-config.ts
@@ -27,10 +27,10 @@ export function parseYamlConfig(text: string): BackendModelConfig {
     console.warn("Ignored unknown YAML keys:", unknownKeys.join(", "));
   }
 
-  // File import is authoritative: forge vision_image_size = null when the
-  // training section is missing, malformed, or missing the key, so a stale
-  // store value cannot survive an import. (Same-model defaults reloads
-  // preserve user choice via Object.hasOwn in model-defaults.ts.)
+  // File import is authoritative: force vision_image_size = null when the
+  // training section is missing/malformed/lacks the key, so a stale store
+  // value can't survive an import. (Same-model defaults reloads preserve
+  // user choice via Object.hasOwn in model-defaults.ts.)
   const rawTraining = raw.training;
   const isPlainTrainingObject =
     rawTraining != null &&
diff --git a/studio/frontend/src/features/training/stores/training-config-store.ts b/studio/frontend/src/features/training/stores/training-config-store.ts
index 137669f8b8..7de78096f9 100644
--- a/studio/frontend/src/features/training/stores/training-config-store.ts
+++ b/studio/frontend/src/features/training/stores/training-config-store.ts
@@ -19,11 +19,8 @@ const MIN_STEP: StepNumber = 1;
 const MAX_STEP: StepNumber = STEPS.length as StepNumber;
 
 /**
- * Auto-select LoRA (16-bit) vs QLoRA (4-bit) based on model size and GPU memory.
- *
- * Rule: if model_size_gb * 1.5 * context_scale fits in free VRAM, use "lora" (16-bit).
- * Otherwise use "qlora" (4-bit).
- *
+ * Auto-select LoRA (16-bit) vs QLoRA (4-bit) by model size and GPU memory.
+ * Use "lora" if model_size_gb * 1.5 * context_scale fits in free VRAM, else "qlora".
  * Context scale: <=8192 = 1.0, >8192 = 1.7, >=16384 = 2.0, >=32768 = 4.0
  */
 async function autoSelectTrainingMethod(
@@ -97,17 +94,16 @@ let _datasetCheckController: AbortController | null = null;
 // AbortController for in-flight model default loads.
 let _modelConfigController: AbortController | null = null;
 
-// Track whether the user has manually toggled trainOnCompletions
-// since the last auto-set (model load or dataset change).
+// Has the user manually toggled trainOnCompletions since the last auto-set
+// (model load or dataset change)?
 let _trainOnCompletionsManuallySet = false;
 
-// Track whether the user has manually edited the learning rate
-// since the last model load. When false, switching training method
-// auto-sets LR to 2e-4 (LoRA/QLoRA) or 2e-5 (full fine-tune).
+// Has the user manually edited the LR since the last model load? When false,
+// switching method auto-sets LR to 2e-4 (LoRA/QLoRA) or 2e-5 (full fine-tune).
 let _learningRateManuallySet = false;
 
-// Stash the model-config-provided (YAML) learning rate so that
-// setTrainingMethod can restore it when switching back from full to adapter.
+// Stash the YAML learning rate so setTrainingMethod can restore it when
+// switching back from full to adapter.
 let _yamlLearningRate: number | undefined = undefined;
 
 // Track whether entering CPT auto-forced datasetFormat="raw" so that
@@ -303,20 +299,18 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
             _yamlLearningRate = undefined;
             const patch = mapBackendModelConfigToTrainingPatch(modelDetails.config);
 
-            // If the model config provides a specific learning rate, treat
-            // it as authoritative so the async auto-select does not overwrite it.
+            // Treat a model-config LR as authoritative so async auto-select
+            // won't overwrite it.
             const modelConfigHasLR = patch.learningRate !== undefined;
             _yamlLearningRate = patch.learningRate;
 
-            // YAML learning rates are tuned for adapter methods (LoRA/QLoRA).
-            // If the user is currently on full fine-tune, override with the
-            // full-finetune default instead of applying the YAML adapter LR.
+            // YAML LRs are tuned for adapters (LoRA/QLoRA); on full fine-tune,
+            // use the full-finetune default instead of the YAML adapter LR.
             if (modelConfigHasLR && !isAdapterMethod(get().trainingMethod)) {
               patch.learningRate = LR_DEFAULT_FULL;
             }
 
-            // If vision model + image dataset already known, override
-            // trainOnCompletions to false regardless of backend default.
+            // Vision model + known image dataset: force trainOnCompletions off.
             if (modelDetails.is_vision && get().isDatasetImage === true) {
               patch.trainOnCompletions = false;
             }
@@ -331,17 +325,13 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
               patch.trainOnCompletions = false;
             }
 
-            // Use backend-provided model_type when available, otherwise
-            // infer from capability flags.
+            // Use backend model_type when available, else infer from flags.
             const isEmbedding = !!modelDetails.is_embedding;
             const inferredModelType: ModelType = modelDetails.model_type
               ?? (isEmbedding ? "embeddings" : modelDetails.is_vision ? "vision" : modelDetails.is_audio ? "audio" : "text");
 
-            // Auto-select training method based on model size vs GPU memory.
-            // If model_size * 1.5 * context_scale fits in free VRAM, use LoRA 16-bit.
-            // Otherwise use QLoRA 4-bit.
-            // Auto-select LoRA vs QLoRA based on GPU memory.
-            // Skip if user has manually chosen CPT -- don't override it.
+            // Auto-select LoRA vs QLoRA by model size vs GPU memory (see
+            // autoSelectTrainingMethod). Skip if the user chose CPT.
             const modelSizeBytes = modelDetails.model_size_bytes;
             if (modelSizeBytes && modelSizeBytes > 0 && get().trainingMethod !== "cpt") {
               void autoSelectTrainingMethod(modelSizeBytes, patch.contextLength ?? get().contextLength)
@@ -358,7 +348,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
             }
 
             // Preserve CPT hyperparams: YAML adapter defaults (r/alpha/targets/LR)
-            // are tuned for standard LoRA and would otherwise clobber CPT settings.
+            // are tuned for standard LoRA and would clobber CPT settings.
             const cptOverrides =
               get().trainingMethod === "cpt"
                 ? getCptModelDefaultsPatch()
diff --git a/studio/frontend/src/hooks/use-collapse-scroll-lock.ts b/studio/frontend/src/hooks/use-collapse-scroll-lock.ts
index fb7baa062c..5ad8853839 100644
--- a/studio/frontend/src/hooks/use-collapse-scroll-lock.ts
+++ b/studio/frontend/src/hooks/use-collapse-scroll-lock.ts
@@ -4,12 +4,12 @@
 import { type RefObject, useCallback, useEffect, useRef } from "react";
 
 /**
- * Locks the nearest scrollable ancestor's scrollTop for the duration of a
- * collapsible animation so the page doesn't jump when content height changes.
+ * Locks the nearest scrollable ancestor's scrollTop during a collapsible
+ * animation so the page doesn't jump when content height changes.
  *
- * Unlike @assistant-ui/react's `useScrollLock`, this hook does NOT toggle
- * `scrollbar-width: none` on the container. Hiding the scrollbar mid-animation
- * caused a visible disappear/reappear flicker on tool-call collapsibles.
+ * Unlike @assistant-ui/react's `useScrollLock`, this does NOT toggle
+ * `scrollbar-width: none` on the container; hiding the scrollbar mid-animation
+ * caused a visible flicker on tool-call collapsibles.
  */
 export function useCollapseScrollLock(
   animatedElementRef: RefObject<HTMLElement | null>,
diff --git a/studio/frontend/src/hooks/use-gpu-info.ts b/studio/frontend/src/hooks/use-gpu-info.ts
index a7ee416112..c7a2852067 100644
--- a/studio/frontend/src/hooks/use-gpu-info.ts
+++ b/studio/frontend/src/hooks/use-gpu-info.ts
@@ -54,10 +54,8 @@ async function fetchGpuOnce(): Promise<GpuInfo> {
 }
 
 /**
- * Fetch GPU info from the backend /api/system endpoint.
- *
- * The result is cached at module level -- only one network request is made
- * regardless of how many components call this hook.
+ * Fetch GPU info from /api/system. Cached at module level, so only one request
+ * is made no matter how many components call this hook.
  */
 export function useGpuInfo(): GpuInfo {
   const [gpu, setGpu] = useState<GpuInfo>(cachedGpu ?? DEFAULT_GPU);
diff --git a/studio/frontend/src/hooks/use-gpu-utilization.ts b/studio/frontend/src/hooks/use-gpu-utilization.ts
index 1262dcbc2f..1a9f6102dd 100644
--- a/studio/frontend/src/hooks/use-gpu-utilization.ts
+++ b/studio/frontend/src/hooks/use-gpu-utilization.ts
@@ -31,10 +31,8 @@ const DEFAULT: GpuUtilization = {
 };
 
 /**
- * Poll `GET /api/train/hardware` for live GPU utilization stats.
- *
- * Only polls while `enabled` is true (i.e. training is running).
- * Polling interval defaults to 10 000 ms.
+ * Poll `GET /api/train/hardware` for live GPU utilization stats while
+ * `enabled` (training running). Interval defaults to 10 000 ms.
  */
 export function useGpuUtilization(
     enabled: boolean,
diff --git a/studio/frontend/src/hooks/use-hardware-info.ts b/studio/frontend/src/hooks/use-hardware-info.ts
index 1e9210be5a..e988830d70 100644
--- a/studio/frontend/src/hooks/use-hardware-info.ts
+++ b/studio/frontend/src/hooks/use-hardware-info.ts
@@ -49,7 +49,7 @@ async function fetchOnce(): Promise<HardwareInfo> {
             cached = info;
             return info;
         } catch {
-            // Reset promise so subsequent calls retry (e.g. backend wasn't ready)
+            // Reset so subsequent calls retry (e.g. backend wasn't ready).
             fetchPromise = null;
             return DEFAULT;
         }
@@ -59,10 +59,8 @@ async function fetchOnce(): Promise<HardwareInfo> {
 }
 
 /**
- * Fetch hardware info from `GET /api/system/hardware`.
- *
- * The result is cached at module level — only one network request is made
- * regardless of how many components call this hook.
+ * Fetch hardware info from `GET /api/system/hardware`. Cached at module level,
+ * so only one request is made regardless of how many components call this hook.
  */
 export function useHardwareInfo(): HardwareInfo {
     const [info, setInfo] = useState<HardwareInfo>(cached ?? DEFAULT);
diff --git a/studio/frontend/src/hooks/use-hf-dataset-search.ts b/studio/frontend/src/hooks/use-hf-dataset-search.ts
index 78fe2d68d1..f8863f328f 100644
--- a/studio/frontend/src/hooks/use-hf-dataset-search.ts
+++ b/studio/frontend/src/hooks/use-hf-dataset-search.ts
@@ -332,8 +332,8 @@ function isOcrOrVisionTextDataset(dataset: HfDatasetResult): boolean {
 }
 
 function toCuratedDatasetResult(id: string): HfDatasetResult {
-  // Curated defaults are id-only. This adapter satisfies the shared result shape
-  // used by downstream combobox/ranking code without making extra HF requests.
+  // Curated defaults are id-only. Adapts them to the shared result shape used
+  // by downstream combobox/ranking code without extra HF requests.
   return {
     id,
     downloads: 0,
diff --git a/studio/frontend/src/hooks/use-hf-dataset-splits.ts b/studio/frontend/src/hooks/use-hf-dataset-splits.ts
index 2be5cad309..44c76779e4 100644
--- a/studio/frontend/src/hooks/use-hf-dataset-splits.ts
+++ b/studio/frontend/src/hooks/use-hf-dataset-splits.ts
@@ -169,9 +169,8 @@ export function useHfDatasetSplits(
   // Derive unique subsets
   const subsets = Array.from(new Set(entries.map((e) => e.config)));
 
-  // Derive splits for the active subset.
-  // If dataset has >1 subset and none is selected yet, return no splits so UI
-  // doesn't auto-pick/show a split before subset is chosen.
+  // Splits for the active subset. With >1 subset and none selected, return no
+  // splits so the UI doesn't auto-pick before a subset is chosen.
   const activeSubset =
     selectedSubset ?? (subsets.length === 1 ? subsets[0] : null);
   const filteredEntries = activeSubset
diff --git a/studio/frontend/src/hooks/use-hf-model-search.ts b/studio/frontend/src/hooks/use-hf-model-search.ts
index efe4d726be..ba52b654b8 100644
--- a/studio/frontend/src/hooks/use-hf-model-search.ts
+++ b/studio/frontend/src/hooks/use-hf-model-search.ts
@@ -42,8 +42,8 @@ const EXCLUDED_TAGS_MLX = new Set([
   "ctranslate2",
 ]);
 
-// Embedding / sentence-transformer models ship with onnx/openvino as additional
-// export formats — they should not be excluded by the tag check above.
+// Embedding / sentence-transformer models ship onnx/openvino as extra
+// export formats, so the tag check above must not exclude them.
 const EMBEDDING_TAGS = new Set([
   "sentence-transformers",
   "feature-extraction",
@@ -123,17 +123,16 @@ function makeMapModel(excludeGguf: boolean, excludedTags: Set<string>) {
 
 /** Number of unsloth results to pull up-front before yielding general results. */
 const UNSLOTH_PREFETCH = 20;
-/** When the user searched for a specific publisher, show fewer unsloth results
- *  before the pinned (original publisher) model. */
+/** Fewer unsloth results before the pinned model when a publisher is searched. */
 const UNSLOTH_PINNED_PREFETCH = 4;
 /** Matches a valid "owner/repo" identifier (exactly two non-empty segments). */
 const PUBLISHER_RE = /^([^/\s]+)\/([^/\s]+)$/;
 
 /**
- * Prime the hf-cache from a listModels result. For public (non-gated,
- * non-private) models, also prime the anonymous slot so the VRAM hook
- * gets cache hits without re-fetching. Gated/private models are only
- * cached under the caller's token to avoid auth leakage.
+ * Prime the hf-cache from a listModels result. For public models, also
+ * prime the anonymous slot so the VRAM hook gets cache hits without
+ * re-fetching. Gated/private models are cached only under the caller's
+ * token to avoid auth leakage.
  */
 function primeFromListing(
   name: string,
@@ -173,8 +172,8 @@ async function* mergedModelIterator(
     ...common,
   });
 
-  // Start pinned model lookup immediately so it can run in parallel with
-  // the Phase 1 unsloth iteration instead of blocking Phase 2.
+  // Start the pinned lookup now so it runs in parallel with Phase 1
+  // instead of blocking Phase 2.
   const pinnedPromise = pinnedId
     ? cachedModelInfo({
         name: pinnedId,
@@ -203,9 +202,8 @@ async function* mergedModelIterator(
   if (pinnedId && !seen.has(pinnedId) && pinnedPromise) {
     const pinned = await pinnedPromise;
     if (pinned) {
-      // Record both the raw input and the canonical name returned by HF
-      // so phase 2 deduplication works even when casing differs
-      // (e.g. user typed "OpenAI/gpt-oss-20b", HF returns "openai/gpt-oss-20b").
+      // Record both the raw input and HF's canonical name so phase 2 dedupe
+      // works across casing (e.g. "OpenAI/..." vs HF's "openai/...").
       seen.add(pinnedId);
       const canonicalName = (pinned as { name?: string }).name;
       if (canonicalName && canonicalName !== pinnedId) {
@@ -255,7 +253,7 @@ async function* priorityThenListingIterator(
   for (const result of settled) {
     if (result.status === "fulfilled") {
       const m = result.value as { name?: string; pipeline_tag?: string };
-      // Skip models that don't match the selected task filter
+      // Skip models that don't match the task filter.
       if (task && m.pipeline_tag && m.pipeline_tag !== task) continue;
       if (m.name) seen.add(m.name);
       yield result.value;
@@ -288,8 +286,8 @@ export function useHfModelSearch(
 ) {
   const { task, accessToken, excludeGguf = false, priorityIds } = options ?? {};
 
-  // Parse publisher detection once and share between the iterator factory
-  // and the secondary sort gate (avoids duplicating the regex + logic).
+  // Detect the publisher once, shared by the iterator factory and the
+  // secondary sort gate (avoids duplicating the regex + logic).
   const { isPublisherQuery, searchQuery, pinnedId, trimmed } = useMemo(() => {
     const t = query.trim();
     const m = PUBLISHER_RE.exec(t);
@@ -305,7 +303,7 @@ export function useHfModelSearch(
   const createIter = useCallback(
     () => {
       if (!trimmed) {
-        // No query: show priority models first (with full metadata), then general unsloth listing
+        // No query: priority models first (full metadata), then general unsloth.
         if (priorityIds && priorityIds.length > 0) {
           return priorityThenListingIterator(priorityIds, task, accessToken) as AsyncGenerator<unknown>;
         }
@@ -316,13 +314,11 @@ export function useHfModelSearch(
           ...(accessToken ? { credentials: { accessToken } } : {}),
         }) as AsyncGenerator<unknown>;
       }
-      // Typed query: disable task filter so explicitly searched models still
-      // appear even if HF task metadata is wrong/missing.
-      // If the query is a valid "owner/repo" identifier (exactly two non-empty,
-      // slash-free, space-free segments), strip the org prefix so unsloth
-      // variants surface, then pin the original publisher model after a small
-      // batch of unsloth results.  Queries for unsloth-owned models are left
-      // as-is so they get the full 20-result prefetch and secondary sort.
+      // Typed query: disable the task filter so explicitly searched models
+      // appear even with wrong/missing HF task metadata. For a valid
+      // "owner/repo" query, strip the org prefix so unsloth variants
+      // surface, then pin the original publisher model after a small batch.
+      // unsloth-owned queries are left as-is for the full prefetch + sort.
       return mergedModelIterator(searchQuery, undefined, accessToken, pinnedId) as AsyncGenerator<unknown>;
     },
     [trimmed, searchQuery, pinnedId, task, accessToken, priorityIds],
@@ -333,10 +329,9 @@ export function useHfModelSearch(
   const mapModel = useMemo(() => makeMapModel(excludeGguf, excludedTags), [excludeGguf, excludedTags]);
   const search = useHfPaginatedSearch(createIter, mapModel);
 
-  // Secondary sort guarantee: unsloth models always float to the top.
-  // Skip when the user searched for a specific non-unsloth publisher
-  // (e.g. "openai/gpt-oss-20b") -- the iterator already handles the
-  // pinned ordering in that case.
+  // Secondary sort: unsloth models always float to the top. Skip for a
+  // specific non-unsloth publisher query (e.g. "openai/gpt-oss-20b") --
+  // the iterator already handles pinned ordering there.
   const results = useMemo(
     () =>
       isPublisherQuery
diff --git a/studio/frontend/src/hooks/use-hf-token-validation.ts b/studio/frontend/src/hooks/use-hf-token-validation.ts
index f13be6b10a..11f56a2151 100644
--- a/studio/frontend/src/hooks/use-hf-token-validation.ts
+++ b/studio/frontend/src/hooks/use-hf-token-validation.ts
@@ -18,9 +18,8 @@ const INITIAL: HfTokenValidationState = {
 };
 
 /**
- * Validates the Hugging Face token by calling the whoami-v2 API.
- * Debounces the token to avoid excessive requests while typing.
- * Returns validation state: isValid (null = not checked), error message, and isChecking.
+ * Validates the HF token via the whoami-v2 API, debounced to avoid excessive
+ * requests while typing. isValid is null until checked.
  */
 export function useHfTokenValidation(token: string): HfTokenValidationState {
   const debouncedToken = useDebouncedValue(
diff --git a/studio/frontend/src/hooks/use-recommended-model-vram.ts b/studio/frontend/src/hooks/use-recommended-model-vram.ts
index 8826b38da9..39d58fe600 100644
--- a/studio/frontend/src/hooks/use-recommended-model-vram.ts
+++ b/studio/frontend/src/hooks/use-recommended-model-vram.ts
@@ -48,8 +48,8 @@ export function useRecommendedModelVram(ids: string[]) {
         }),
       );
       if (!canceled) {
-        // Merge with previous state so that VRAM badges for already-visible
-        // models are preserved while newly-visible models are still loading.
+        // Merge with previous state so VRAM badges for already-visible models
+        // persist while newly-visible models are still loading.
         setParamCountById((prev) => new Map([...prev, ...next]));
         setIsLoading(false);
       }
diff --git a/studio/frontend/src/hooks/use-tauri-backend.ts b/studio/frontend/src/hooks/use-tauri-backend.ts
index c7628c0fd0..b376cb3a37 100644
--- a/studio/frontend/src/hooks/use-tauri-backend.ts
+++ b/studio/frontend/src/hooks/use-tauri-backend.ts
@@ -277,12 +277,11 @@ export function useTauriBackend() {
 
     try {
       const { invoke } = await import("@tauri-apps/api/core");
-      // backend/run.py keeps the existing 8888-8908 fallback via
-      // server-port/TAURI_PORT.
+      // backend/run.py keeps the 8888-8908 fallback via server-port/TAURI_PORT.
       await invoke("start_managed_server", { port: 8888 });
 
-      // Wait for the owned backend's server-port event. Do not attach to an
-      // external backend if the managed start does not report a port.
+      // Wait for the owned backend's server-port event. Don't attach to an
+      // external backend if the managed start doesn't report a port.
       const startupResult = await waitForManagedServerReady(
         invoke,
         () => portRef.current,
@@ -348,8 +347,7 @@ export function useTauriBackend() {
 
   async function stopServer() {
     if (isExternalServer) {
-      // We attached to a server we didn't spawn — can't kill it,
-      // just disconnect the UI.
+      // We attached to a server we didn't spawn: can't kill it, just disconnect the UI.
       startingRef.current = false;
       setIsExternalServer(false);
       stopExternalServerPoll();
@@ -373,19 +371,18 @@ export function useTauriBackend() {
     const { invoke } = await import("@tauri-apps/api/core");
     try {
       await invoke("start_install");
-      // Install completed — start the managed backend we just installed.
-      // Do not run the general preflight here: it can attach to an unrelated
-      // already-running CLI/backend server before launching our managed one.
-      // The install-complete event listener does NOT call startServer() to
-      // avoid a double-start race condition.
+      // Install done: start the managed backend we just installed. Don't run the
+      // general preflight here, it can attach to an unrelated running CLI/backend
+      // before launching ours. The install-complete listener does NOT call
+      // startServer() to avoid a double-start race.
       setBackendStatus("starting");
       elevationResumeRef.current = null;
       await startServer();
     } catch (e) {
       const msg = String(e);
-      // NEEDS_ELEVATION is not a real error — the Rust side also emits
-      // install-needs-elevation which sets needs-elevation status.
-      // Don't race with it by setting install-error here.
+      // NEEDS_ELEVATION is not a real error: the Rust side also emits
+      // install-needs-elevation (sets needs-elevation status). Don't race with it
+      // by setting install-error here.
       if (msg.includes("NEEDS_ELEVATION")) return;
       setBackendError(msg, "install-error");
     }
@@ -511,8 +508,8 @@ export function useTauriBackend() {
         setLogs((prev) => [...prev.slice(-499), e.payload]);
       });
 
-      // install-complete is informational only — does NOT trigger startServer.
-      // The invoke("start_install") success path handles that to avoid races.
+      // install-complete is informational only; does NOT trigger startServer. The
+      // invoke("start_install") success path handles that to avoid races.
       register<void>("install-complete", () => {
         setCurrentStepIndex(999); // all steps done
       });
diff --git a/studio/frontend/src/lib/copy-to-clipboard.ts b/studio/frontend/src/lib/copy-to-clipboard.ts
index cce9ea7783..2cbecbbdab 100644
--- a/studio/frontend/src/lib/copy-to-clipboard.ts
+++ b/studio/frontend/src/lib/copy-to-clipboard.ts
@@ -2,9 +2,8 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 /**
- * Copy text to clipboard in a way that works on Mac/Safari.
- * Uses a synchronous textarea + execCommand fallback so the copy runs in the
- * same user gesture as the click (required by Safari's clipboard security).
+ * Synchronous textarea + execCommand copy so it runs in the same user gesture
+ * as the click (required by Safari's clipboard security).
  */
 function copyWithExecCommand(text: string): boolean {
   if (typeof document === "undefined" || !document.body) return false;
@@ -44,8 +43,7 @@ export async function copyToClipboard(text: string): Promise<boolean> {
       return true;
     } catch (error) {
       console.warn("Async clipboard API failed, falling back to execCommand", error);
-      // Clipboard API rejected (NotAllowedError, insecure context, etc.)
-      // Fall through to execCommand fallback.
+      // Rejected (NotAllowedError, insecure context, etc.); fall through.
     }
   }
 
diff --git a/studio/frontend/src/lib/format-fastapi-error.ts b/studio/frontend/src/lib/format-fastapi-error.ts
index ed4a5ece7d..79d53f469d 100644
--- a/studio/frontend/src/lib/format-fastapi-error.ts
+++ b/studio/frontend/src/lib/format-fastapi-error.ts
@@ -5,11 +5,9 @@
  * Render a FastAPI error response body into a human-readable string.
  *
  * FastAPI emits 422s as `{detail: Array<{loc, msg, type, input?}>}`. The
- * naive `body.detail || body.message` pattern truthy-coerces the array
- * and stringifies it as `[object Object]`, which is unhelpful and was
- * exactly the regression #5409 fixed inside `train-api.ts`. Lift the
- * helper here so chat, export, history, datasets, and recipe-studio
- * can all share it.
+ * naive `body.detail || body.message` stringifies the array as
+ * `[object Object]` (the #5409 regression). Shared here across chat,
+ * export, history, datasets, and recipe-studio.
  *
  * Falls back through: array detail -> string detail -> message -> null.
  */
@@ -38,10 +36,9 @@ export function formatFastApiDetail(detail: unknown): string | null {
 }
 
 /**
- * Convert a Response (likely a non-ok response from a fetch) into the
- * best human-readable error message available. Used by *-api.ts wrappers
- * so toast text reads as `field: msg` instead of `[object Object]` or
- * `Request failed (422)`.
+ * Convert a (likely non-ok) Response into the best human-readable error
+ * message. Used by *-api.ts wrappers so toasts read `field: msg` instead
+ * of `[object Object]` or `Request failed (422)`.
  */
 export async function readFastApiError(
   response: Response,
diff --git a/studio/frontend/src/lib/hf-cache.ts b/studio/frontend/src/lib/hf-cache.ts
index d87345eb61..eebb3ce4b2 100644
--- a/studio/frontend/src/lib/hf-cache.ts
+++ b/studio/frontend/src/lib/hf-cache.ts
@@ -19,8 +19,8 @@ const MAX_CONCURRENT = 3;
 
 // ── Cache & in-flight maps ──────────────────────────────────────
 
-// Extend ModelEntry with the additional fields we always request so callers
-// do not need unsafe casts to access safetensors/tags.
+// Extend ModelEntry with the fields we always request, so callers avoid
+// unsafe casts to access safetensors/tags.
 export type CachedResult = ModelEntry & {
   safetensors?: { total?: number; parameters?: Record<string, number> };
   tags?: string[];
@@ -140,10 +140,9 @@ export async function cachedModelInfo(
       });
       const entry = { data: result as CachedResult, ts: Date.now() };
       cache.set(key, entry);
-      // For public (non-gated, non-private) models, also prime the anonymous
-      // cache slot so the VRAM hook (which reads without credentials) gets a
-      // cache hit. We skip gated/private models to avoid leaking auth-scoped
-      // metadata into the anonymous slot.
+      // For public models, also prime the anonymous cache slot so the VRAM
+      // hook (which reads without credentials) hits cache. Skip gated/private
+      // models to avoid leaking auth-scoped metadata into the anonymous slot.
       const r = result as CachedResult & { gated?: false | "auto" | "manual"; private?: boolean };
       if (token && !r.private && !r.gated) {
         const anonKey = cacheKey(params.name, undefined);
diff --git a/studio/frontend/src/lib/latex.ts b/studio/frontend/src/lib/latex.ts
index 0092d51be0..1a4ebdace8 100644
--- a/studio/frontend/src/lib/latex.ts
+++ b/studio/frontend/src/lib/latex.ts
@@ -15,8 +15,8 @@ const CURRENCY_REGEX =
   /(?<![\\$])\$(?!\$)(?=\d+(?:,\d{3})*(?:\.\d+)?[KMBkmb]?(?:\s|$|[^a-zA-Z\d]))/g;
 
 /**
- * Find regions inside code blocks (``` ... ``` and ` ... `) so we can skip them.
- * Returns sorted array of [start, end] index pairs.
+ * Find code-block regions (``` ... ``` and ` ... `) to skip.
+ * Returns a sorted array of [start, end] index pairs.
  */
 function findCodeBlockRegions(content: string): Array<[number, number]> {
   const regions: Array<[number, number]> = [];
@@ -28,12 +28,11 @@ function findCodeBlockRegions(content: string): Array<[number, number]> {
     regions.push([match.index, match.index + match[0].length]);
   }
 
-  // Inline code: `...` (but not inside fenced blocks -- we filter below)
+  // Inline code: `...` (skip spans inside fenced blocks, filtered below)
   const inlineRe = /`[^`\n]+`/g;
   while ((match = inlineRe.exec(content)) !== null) {
     const start = match.index;
     const end = start + match[0].length;
-    // Skip if this backtick span falls inside a fenced block
     let inside = false;
     for (const [rs, re] of regions) {
       if (start >= rs && end <= re) {
@@ -46,7 +45,7 @@ function findCodeBlockRegions(content: string): Array<[number, number]> {
     }
   }
 
-  // Sort by start position for binary search
+  // Sort by start position for binary search.
   regions.sort((a, b) => a[0] - b[0]);
   return regions;
 }
@@ -74,51 +73,42 @@ function isInCodeBlock(
   return false;
 }
 
-/**
- * A token (no whitespace) that looks purely like currency, e.g. `5`,
- * `1,000`, `5.99`, `100K`, `3.5M`.
- */
+/** A whitespace-free token that looks purely like currency, e.g. `5`, `1,000`, `5.99`, `100K`, `3.5M`. */
 const CURRENCY_BODY_RE = /^\d+(?:,\d{3})*(?:\.\d+)?[KMBkmb]?$/;
 
 /** Body characters that almost always indicate real LaTeX. */
 const LATEX_CHAR_RE = /[\\^_{}]/;
 
 /**
- * Operators that strongly suggest a math expression. We deliberately
- * leave out `^` and `_` because `LATEX_CHAR_RE` already short-circuits
- * on those before we ever consult this regex.
+ * Operators that strongly suggest math. Omits `^` and `_` since
+ * `LATEX_CHAR_RE` short-circuits on those before this regex runs.
  */
 const MATH_OP_RE = /[=+\-<>/*]/;
 
 /**
- * Trailing chars stripped before the currency check. Includes prose
- * punctuation plus the connectors `-` and `/` that appear in compact
- * currency ranges like `$5-$10` or `$5/$10`; without them the body
- * `5-` or `5/` would slip through the single-token math shortcut.
+ * Trailing chars stripped before the currency check: prose punctuation
+ * plus `-` and `/` from compact ranges like `$5-$10`; without them the
+ * body `5-` or `5/` would slip through the single-token math shortcut.
  */
 const TRAIL_PUNCT_RE = /[.,;:!?\-/]+$/;
 
 /**
- * A standalone single letter (variable name) inside the body. We require
- * that the letter is not part of a longer word so that prose like
- * "5 to attend" doesn't get misread as a math expression with the
- * variable `t`.
+ * A standalone single-letter variable, not part of a longer word, so
+ * prose like "5 to attend" isn't misread as math with variable `t`.
  */
 const LONE_LETTER_RE = /(?<![a-zA-Z])[a-zA-Z](?![a-zA-Z])/;
 
 /**
- * Numeric or single-letter operands joined by math operators, with
- * optional whitespace. Matches `2 + 2`, `100 < 200`, `1,000 - 500`,
- * `2.5 * 3`, `x + y`. Lets us recognise numeric-only expressions like
- * `$2 + 2$` as math without forcing a lone variable token.
+ * Numeric or single-letter operands joined by math operators (optional
+ * whitespace): `2 + 2`, `100 < 200`, `1,000 - 500`, `x + y`. Recognises
+ * numeric-only expressions like `$2 + 2$` without a lone variable token.
  */
 const SIMPLE_MATH_RE =
   /^(?:\d+(?:,\d{3})*(?:\.\d+)?|[a-zA-Z])(?:\s*[=+\-<>/*]\s*(?:\d+(?:,\d{3})*(?:\.\d+)?|[a-zA-Z]))+$/;
 
 /**
- * Return true if the substring between two `$` delimiters looks like a
- * LaTeX expression rather than a span of prose between two currency
- * tokens.
+ * True if the substring between two `$` delimiters looks like LaTeX
+ * rather than prose between two currency tokens.
  *
  * Rule of thumb:
  *   - `$30^\circ$`  -> math (LaTeX chars)
@@ -142,14 +132,12 @@ function looksLikeMathBody(body: string): boolean {
 }
 
 /**
- * Return true if the `$` at `offset` opens a balanced inline math span
- * (`$...$`) on the same line. The closer must be unescaped, must not be
- * part of `$$`, and must lie inside a 200-character window. The body
- * must look like LaTeX so we don't pair two currency tokens that share
- * a line (e.g. "$5 to $10"). Bold-wrapped spans (`**$X$**` and the
- * underscore equivalent `__$X$__`) are always treated as math because
- * LLMs reach for that pattern when they want "bold math" and the
- * heuristic would otherwise reject prose-shaped bodies like "90 - x".
+ * True if the `$` at `offset` opens a balanced inline math span (`$...$`)
+ * on the same line. The closer must be unescaped, not part of `$$`, and
+ * within 200 chars. The body must look like LaTeX so we don't pair two
+ * currency tokens on a line (e.g. "$5 to $10"). Bold-wrapped spans
+ * (`**$X$**`, `__$X$__`) are always math: LLMs use that for "bold math"
+ * and the heuristic would otherwise reject prose-shaped bodies like "90 - x".
  */
 function hasInlineMathCloser(content: string, offset: number): boolean {
   const MAX_SPAN = 200;
@@ -163,10 +151,9 @@ function hasInlineMathCloser(content: string, offset: number): boolean {
       i++;
       continue;
     }
-    // A `$` immediately followed by a digit is far more likely the start
-    // of another currency token than the closer for the current span. Keep
-    // scanning so prose like `Starts at $5 + a $10 add-on` doesn't pair
-    // the two currency markers as a math span.
+    // A `$` followed by a digit is more likely another currency token than
+    // the closer. Keep scanning so prose like `$5 + a $10 add-on` doesn't
+    // pair the two currency markers as a math span.
     if (/\d/.test(content[i + 1] ?? "")) {
       continue;
     }
diff --git a/studio/frontend/src/lib/open-link.ts b/studio/frontend/src/lib/open-link.ts
index b7e6a0fa6e..46c9a8dd59 100644
--- a/studio/frontend/src/lib/open-link.ts
+++ b/studio/frontend/src/lib/open-link.ts
@@ -1,21 +1,20 @@
 import { isTauri } from "@/lib/api-base";
 
 /**
- * Open a URL in the system browser (Tauri) or new tab (web).
- * Handles anchor links and mailto: natively without the opener plugin.
- * Returns true when the caller should preventDefault; false when the
- * browser's native navigation should proceed (relative URLs, empty, etc.).
+ * Open a URL in the system browser (Tauri) or new tab (web). Handles anchor
+ * and mailto: links natively. Returns true when the caller should
+ * preventDefault; false to let native navigation proceed (relative, empty).
  */
 export function openLink(url: string): boolean {
   if (!url) return false;
 
-  // Anchor links — scroll within the page, don't open externally
+  // Anchor links scroll within the page, don't open externally
   if (url.startsWith("#")) {
     window.location.hash = url;
     return true;
   }
 
-  // Relative URLs — let the browser / router handle them natively
+  // Relative URLs: let the browser / router handle them natively
   if (!url.includes("://") && !url.startsWith("mailto:")) {
     return false;
   }
diff --git a/studio/frontend/src/lib/vram.ts b/studio/frontend/src/lib/vram.ts
index fad2c438bd..1c443134d9 100644
--- a/studio/frontend/src/lib/vram.ts
+++ b/studio/frontend/src/lib/vram.ts
@@ -4,56 +4,42 @@
 /**
  * VRAM estimation for model loading (4-bit quantization via bitsandbytes).
  *
- * Estimates the total driver-level VRAM (what nvidia-smi reports) needed to
- * load a model in 4-bit with Unsloth / bitsandbytes.  This determines
- * whether a model will fit on the user's GPU before any training begins.
+ * Estimates the total driver-level VRAM (what nvidia-smi reports) to load a
+ * model in 4-bit with Unsloth / bitsandbytes, to check it fits the GPU before
+ * training.
  *
- * Formula:  totalParams * 0.90  +  1.4 GB
+ * Formula: totalParams * 0.90 + 1.4 GB
  *
- * Calibrated against isolated Unsloth model loads on RTX 5070 Ti (2026.2):
+ * Calibrated against isolated Unsloth loads on RTX 5070 Ti (2026.2):
  *   Qwen2.5-0.5B  (0.49B) : est 1.8 vs actual 1.86 GB  (-3%)
  *   Llama-3.2-1B  (1.24B) : est 2.5 vs actual 2.54 GB   (-1%)
  *   Llama-3.2-3B  (3.21B) : est 4.3 vs actual 4.40 GB   (-2%)
  *   Llama-3.1-8B  (8.03B) : est 8.6 vs actual 8.14 GB   (+6%)
  *
- * Accuracy: within 3% for 0.5B-3B models, within 6% for 8B.
+ * Accuracy: within 3% for 0.5B-3B, within 6% for 8B.
  */
 
-// ---------------------------------------------------------------------------
 // Constants (exported for testing)
-// ---------------------------------------------------------------------------
 
 /**
- * Effective bytes per parameter for 4-bit model weights at driver level.
- *
- * Raw bnb 4-bit is ~0.5 bytes/param, but embedding and lm_head layers remain
- * in fp16 and bnb adds per-block quantization metadata, bringing the
- * effective rate to ~0.84-0.93 across tested architectures.  0.9 is the
- * calibrated middle ground.
+ * Effective bytes per parameter for 4-bit weights at driver level. Raw bnb
+ * 4-bit is ~0.5, but embedding/lm_head stay fp16 and bnb adds per-block
+ * metadata, giving ~0.84-0.93 across architectures; 0.9 is the calibrated mid.
  */
 export const BNB_4BIT_LOADING_BYTES = 0.9;
 
 /**
- * Fixed overhead (GB) for the CUDA driver context and PyTorch runtime.
- *
- * This is independent of model size -- it is the baseline GPU memory consumed
- * before any model weights are loaded.  Measured at 1.34-1.46 GB across
- * tested models; we use 1.4 as the default.
+ * Fixed overhead (GB) for the CUDA driver context and PyTorch runtime,
+ * independent of model size. Measured at 1.34-1.46 GB; we use 1.4.
  */
 export const LOADING_OVERHEAD_GB = 1.4;
 
-// ---------------------------------------------------------------------------
-// Estimation
-// ---------------------------------------------------------------------------
-
 export type VramFitStatus = "fits" | "tight" | "exceeds";
 
 /**
- * Bytes per parameter when loading a model at fp16/bf16 (LoRA, full FT).
- *
- * This is the theoretical value (2 bytes = 16 bits).  Not yet calibrated
- * against actual measurements -- the real driver-level usage may be slightly
- * higher due to buffers and metadata, similar to how 4-bit is 0.9 vs 0.5.
+ * Bytes per parameter at fp16/bf16 (LoRA, full FT). Theoretical (2 bytes = 16
+ * bits); not yet calibrated, so real usage may run slightly higher (as 4-bit
+ * is 0.9 vs 0.5).
  */
 export const FP16_LOADING_BYTES = 2.0;
 
@@ -65,15 +51,9 @@ function usesQuantizedLoading(method: TrainingMethod, modelId?: string): boolean
 }
 
 /**
- * Estimate VRAM (GB) needed to load a model with Unsloth.
- *
- * The bytes-per-param rate depends on the training method:
- *   - QLoRA  : 4-bit quantized via bnb  -> 0.90 bytes/param (calibrated)
- *   - LoRA   : fp16                      -> 2.0  bytes/param (theoretical)
- *   - Full   : fp16                      -> 2.0  bytes/param (theoretical)
- *   - CPT    : fp16 LoRA (16-bit base)   -> 2.0  bytes/param (theoretical)
- *
- * Formula:  totalParams * bytesPerParam + 1.4 GB overhead
+ * Estimate VRAM (GB) to load a model with Unsloth. Bytes/param by method:
+ *   QLoRA: 4-bit bnb -> 0.90 (calibrated); LoRA/Full/CPT: fp16 -> 2.0
+ *   (theoretical). Formula: totalParams * bytesPerParam + 1.4 GB overhead.
  */
 export function estimateLoadingVram(
   totalParams: number,
@@ -88,11 +68,8 @@ export function estimateLoadingVram(
 }
 
 /**
- * Check whether a model fits in the available GPU VRAM.
- *
- *   fits     -  uses <= 75% of available
- *   tight    -  uses 75-100% of available
- *   exceeds  -  uses > 100% of available
+ * Check whether a model fits in available GPU VRAM.
+ *   fits: <= 75%; tight: 75-100%; exceeds: > 100%.
  */
 export function checkVramFit(
   requiredGb: number,
diff --git a/studio/frontend/src/main.tsx b/studio/frontend/src/main.tsx
index a924c1652e..0922e764bb 100644
--- a/studio/frontend/src/main.tsx
+++ b/studio/frontend/src/main.tsx
@@ -12,8 +12,8 @@ import { initializeLocale } from "./i18n";
 const globalCrypto = globalThis.crypto as Crypto | undefined;
 
 if (globalCrypto && typeof globalCrypto.randomUUID !== "function") {
-  // Some envs ship `crypto` but no `randomUUID()` (or a non-function stub).
-  // Provide a best-effort v4 UUID using `getRandomValues` when available.
+  // Some envs ship `crypto` without `randomUUID()`. Provide a best-effort v4
+  // UUID using `getRandomValues` when available.
   const cryptoRef = globalCrypto;
 
   function getRandomByte(): number {
diff --git a/studio/frontend/src/utils/index.ts b/studio/frontend/src/utils/index.ts
index fef4e946d9..e8eccd2e29 100644
--- a/studio/frontend/src/utils/index.ts
+++ b/studio/frontend/src/utils/index.ts
@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-// Utility functions
 export { normalizeNonEmptyName } from "./strings";

From aec41d17edf23f5efe0b8e7d7bcb854687680235 Mon Sep 17 00:00:00 2001
From: Eyera <hauzin@hotmail.com>
Date: Tue, 9 Jun 2026 13:11:24 +0200
Subject: [PATCH 118/222] feat(studio): Hub + Download Manager (#5916)

Adds the Studio Hub and download manager: browse Hugging Face models and datasets, download GGUF and safetensors with live progress and cancellation, and manage on-device inventory. The Hub does not require a GPU, so it is available on chat-only hosts.

CI: all substantive checks pass, including the three Core jobs after unsloth-zoo#736. The two red checks are non-code flakes, a transient npm-registry DNS resolution failure in the package scan and one quantized vision-model output assertion whose sibling shards passed.
---
 studio/backend/hub/__init__.py                |    8 +
 studio/backend/hub/dependencies.py            |   24 +
 studio/backend/hub/routes/__init__.py         |   12 +
 studio/backend/hub/routes/datasets.py         |  138 +
 studio/backend/hub/routes/inventory.py        |  222 ++
 studio/backend/hub/schemas/__init__.py        |    2 +
 studio/backend/hub/schemas/datasets.py        |  108 +
 studio/backend/hub/schemas/downloads.py       |  161 +
 studio/backend/hub/schemas/inventory.py       |  286 ++
 studio/backend/hub/services/__init__.py       |   29 +
 .../backend/hub/services/datasets/__init__.py |    4 +
 .../hub/services/datasets/cache_inventory.py  |  474 +++
 .../hub/services/datasets/downloads.py        |  268 ++
 .../hub/services/datasets/formatting.py       |  527 +++
 studio/backend/hub/services/datasets/local.py |  330 ++
 .../hub/services/download_lifecycle.py        |  449 +++
 .../backend/hub/services/models/__init__.py   |    4 +
 .../hub/services/models/cache_inventory.py    |  461 +++
 studio/backend/hub/services/models/common.py  |  610 ++++
 .../backend/hub/services/models/deletion.py   |  455 +++
 .../backend/hub/services/models/downloads.py  |  411 +++
 .../hub/services/models/folder_browser.py     |  518 +++
 .../hub/services/models/gguf_variants.py      |  643 ++++
 .../hub/services/models/local_inventory.py    |  679 ++++
 studio/backend/hub/services/models/ollama.py  |  394 +++
 .../backend/hub/services/snapshot_progress.py |  260 ++
 studio/backend/hub/storage/__init__.py        |    2 +
 studio/backend/hub/storage/scan_folders.py    |  194 ++
 studio/backend/hub/tests/conftest.py          |  106 +
 .../hub/tests/test_dataset_services.py        |  356 ++
 .../backend/hub/tests/test_model_services.py  | 2962 +++++++++++++++++
 studio/backend/hub/utils/__init__.py          |    2 +
 studio/backend/hub/utils/dataset_cache.py     |  145 +
 studio/backend/hub/utils/dataset_format.py    |  749 +++++
 studio/backend/hub/utils/download_manifest.py |  487 +++
 studio/backend/hub/utils/download_registry.py | 1263 +++++++
 studio/backend/hub/utils/gguf.py              |  406 +++
 studio/backend/hub/utils/gguf_plan.py         |  158 +
 studio/backend/hub/utils/hf_cache_state.py    |  293 ++
 studio/backend/hub/utils/hf_errors.py         |   28 +
 studio/backend/hub/utils/inventory_scan.py    |  533 +++
 studio/backend/hub/utils/llm_assist.py        |  440 +++
 studio/backend/hub/utils/paths.py             |  522 +++
 studio/backend/hub/utils/snapshot_filters.py  |  110 +
 studio/backend/hub/utils/state_dir.py         |  154 +
 studio/backend/hub/workers/__init__.py        |    2 +
 studio/backend/hub/workers/hf_download.py     |  753 +++++
 studio/backend/main.py                        |   37 +-
 studio/backend/tests/test_middleware.py       |   33 +-
 studio/frontend/package-lock.json             |   28 +
 studio/frontend/package.json                  |    1 +
 .../public/hub/profile/logo/anthropic.svg     |    6 +
 .../public/hub/profile/logo/cohere.png        |  Bin 0 -> 5122 bytes
 .../public/hub/profile/logo/deepseek.svg      |   14 +
 .../public/hub/profile/logo/google.png        |  Bin 0 -> 19507 bytes
 .../frontend/public/hub/profile/logo/hf.svg   |    8 +
 .../frontend/public/hub/profile/logo/ibm.png  |  Bin 0 -> 17084 bytes
 .../frontend/public/hub/profile/logo/meta.svg |   19 +
 .../public/hub/profile/logo/microsoft.svg     |    1 +
 .../public/hub/profile/logo/minimax-color.png |  Bin 0 -> 8665 bytes
 .../public/hub/profile/logo/mistral.svg       |   19 +
 .../public/hub/profile/logo/moonshot.jpg      |  Bin 0 -> 15554 bytes
 .../public/hub/profile/logo/nvidia.svg        |    1 +
 .../public/hub/profile/logo/openai.svg        |    5 +
 .../frontend/public/hub/profile/logo/qwen.png |  Bin 0 -> 117172 bytes
 .../frontend/public/hub/profile/logo/xai.svg  |    1 +
 .../frontend/public/hub/profile/logo/zai.svg  |  215 ++
 studio/frontend/src/app/provider.tsx          |   28 +-
 studio/frontend/src/app/router.tsx            |    2 +
 studio/frontend/src/app/routes/__root.tsx     |    1 +
 studio/frontend/src/app/routes/hub.tsx        |   29 +
 .../frontend/src/components/app-sidebar.tsx   |   10 +
 studio/frontend/src/components/ui/tooltip.tsx |   18 +-
 .../chat/stores/chat-runtime-store.ts         |   20 +-
 .../features/hub/catalog/catalog-states.tsx   |  300 ++
 .../hub/catalog/dataset-download-section.tsx  |  193 ++
 .../src/features/hub/catalog/dot-tag.tsx      |   46 +
 .../hub/catalog/download-cancel-indicator.tsx |   25 +
 .../features/hub/catalog/download-card.tsx    |  217 ++
 .../features/hub/catalog/download-section.tsx |   82 +
 .../catalog/external-link-confirm-dialog.tsx  |   79 +
 .../hub/catalog/gguf-download-card.tsx        |  857 +++++
 .../hub/catalog/gguf-live-variant-states.ts   |   87 +
 .../hub/catalog/gguf-status-cards.tsx         |  110 +
 .../features/hub/catalog/hub-option-menu.tsx  |  239 ++
 .../hub/catalog/local-dataset-card.tsx        |   64 +
 .../hub/catalog/local-on-device-card.tsx      |  545 +++
 .../features/hub/catalog/model-inspector.tsx  |  732 ++++
 .../src/features/hub/catalog/model-readme.tsx |  582 ++++
 .../hub/catalog/models-catalog-lists.tsx      |  287 ++
 .../hub/catalog/models-catalog-rows.tsx       |  768 +++++
 .../features/hub/catalog/models-catalog.tsx   |  396 +++
 .../features/hub/catalog/models-header.tsx    |  139 +
 .../features/hub/catalog/models-toolbar.tsx   |  405 +++
 .../hub/catalog/on-device-folders-dialog.tsx  |  370 ++
 .../src/features/hub/catalog/owner-avatar.tsx |  221 ++
 .../features/hub/catalog/path-info-button.tsx |  111 +
 .../hub/catalog/safetensors-download-card.tsx |  327 ++
 .../src/features/hub/catalog/shared.tsx       |   56 +
 .../hub/catalog/transport-conflict-dialog.tsx |   95 +
 .../features/hub/catalog/transport-toggle.tsx |   84 +
 .../features/hub/catalog/use-card-delete.ts   |   31 +
 .../hub/catalog/use-delete-confirm-action.ts  |   66 +
 .../hub/catalog/use-download-card-state.ts    |   95 +
 .../catalog/use-gguf-variant-fetch-state.ts   |  175 +
 .../hub/components/hf-token-indicator.tsx     |  108 +
 .../features/hub/components/page-heading.tsx  |   27 +
 .../src/features/hub/components/train-icon.ts |    8 +
 .../src/features/hub/download-manager/api.ts  |  455 +++
 .../hub/download-manager/constants.ts         |   36 +
 .../download-manager/download-api-adapter.ts  |  244 ++
 .../download-manager-config.ts                |   37 +
 .../download-manager-controller.ts            |   72 +
 .../download-manager-panel.tsx                |  255 ++
 .../download-manager-state.ts                 |  526 +++
 .../download-manager-types.ts                 |   81 +
 .../download-progress-bar.tsx                 |   56 +
 .../hub/download-manager/hydration.ts         |  281 ++
 .../features/hub/download-manager/index.ts    |   47 +
 .../hub/download-manager/poll-loop.ts         |  955 ++++++
 .../hub/download-manager/runtime-registry.ts  |   83 +
 .../download-manager/transport-conflict.ts    |  201 ++
 .../download-manager/transport-preference.ts  |  110 +
 .../features/hub/download-manager/types.ts    |   10 +
 .../hub/download-manager/use-repo-download.ts |  190 ++
 .../features/hub/hooks/use-copy-feedback.ts   |   30 +
 .../features/hub/hooks/use-dataset-size.ts    |   40 +
 .../features/hub/hooks/use-discover-search.ts |  212 ++
 .../hub/hooks/use-hub-dataset-search.ts       |  432 +++
 .../hub/hooks/use-hub-infinite-scroll.ts      |  245 ++
 .../hub/hooks/use-hub-model-search.ts         |  623 ++++
 .../features/hub/hooks/use-hub-model-vram.ts  |   50 +
 .../hub/hooks/use-hub-paginated-search.ts     |  355 ++
 .../features/hub/hooks/use-is-hub-desktop.ts  |   22 +
 .../src/features/hub/hooks/use-latest-ref.ts  |   10 +
 .../hub/hooks/use-models-selection.ts         |  283 ++
 .../features/hub/hooks/use-online-status.ts   |   53 +
 .../hub/hooks/use-selected-model-metadata.ts  |   74 +
 .../hub/hooks/use-selected-model-view.ts      |  391 +++
 studio/frontend/src/features/hub/hub-page.tsx |  770 +++++
 studio/frontend/src/features/hub/hub.css      |  756 +++++
 .../src/features/hub/inventory/api.ts         |  455 +++
 .../src/features/hub/inventory/constants.ts   |   32 +
 .../inventory/gguf-variants-cache-events.ts   |   51 +
 .../src/features/hub/inventory/index.ts       |   80 +
 .../hub/inventory/inventory-dedupe.ts         |  185 +
 .../hub/inventory/inventory-hint-store.ts     |  221 ++
 .../features/hub/inventory/inventory-hints.ts |  273 ++
 .../hub/inventory/resource-resolver.ts        |  125 +
 .../src/features/hub/inventory/types.ts       |   88 +
 .../hub/inventory/use-device-inventory.ts     |  359 ++
 .../use-gguf-variants-cache-version.ts        |   18 +
 .../hub/inventory/use-hub-inventory.ts        |  610 ++++
 .../src/features/hub/inventory/view-models.ts |  304 ++
 .../src/features/hub/lib/abort-signals.ts     |   96 +
 .../frontend/src/features/hub/lib/channels.ts |   66 +
 .../src/features/hub/lib/dataset-size.ts      |  356 ++
 .../src/features/hub/lib/format-filters.ts    |   26 +
 .../frontend/src/features/hub/lib/format.ts   |   72 +
 .../frontend/src/features/hub/lib/gguf-fit.ts |   51 +
 .../src/features/hub/lib/gguf-variant-sort.ts |   89 +
 .../frontend/src/features/hub/lib/hf-cache.ts |  114 +
 .../src/features/hub/lib/hf-model-meta.ts     |   46 +
 .../src/features/hub/lib/hf-owner-avatar.ts   |  208 ++
 .../src/features/hub/lib/hf-readme.ts         |  194 ++
 .../src/features/hub/lib/hub-feature-flags.ts |    8 +
 .../src/features/hub/lib/hub-token-header.ts  |   12 +
 .../src/features/hub/lib/inventory-search.ts  |   62 +
 .../src/features/hub/lib/local-path.ts        |   20 +
 .../frontend/src/features/hub/lib/lru-map.ts  |   72 +
 .../features/hub/lib/model-capabilities.ts    |  162 +
 .../src/features/hub/lib/model-identifiers.ts |   24 +
 .../src/features/hub/lib/model-identity.ts    |   65 +
 .../frontend/src/features/hub/lib/network.ts  |  186 ++
 .../src/features/hub/lib/provider-logos.ts    |  278 ++
 .../src/features/hub/lib/search-text.ts       |   23 +
 .../features/hub/lib/selection-resolution.ts  |  145 +
 .../src/features/hub/lib/token-fingerprint.ts |   17 +
 .../src/features/hub/lib/unsloth-support.ts   |  232 ++
 .../src/features/hub/lib/view-models.ts       |  189 ++
 .../hub/stores/external-link-confirm.ts       |   31 +
 .../src/features/hub/stores/hf-token-store.ts |  118 +
 .../features/hub/stores/inventory-events.ts   |  143 +
 studio/frontend/src/features/hub/types.ts     |   98 +
 studio/frontend/src/i18n/locales/en.ts        |    1 +
 studio/frontend/src/i18n/locales/zh-CN.ts     |    1 +
 studio/frontend/src/index.css                 |    1 +
 studio/src-tauri/tauri.conf.json              |    2 +-
 188 files changed, 39508 insertions(+), 51 deletions(-)
 create mode 100644 studio/backend/hub/__init__.py
 create mode 100644 studio/backend/hub/dependencies.py
 create mode 100644 studio/backend/hub/routes/__init__.py
 create mode 100644 studio/backend/hub/routes/datasets.py
 create mode 100644 studio/backend/hub/routes/inventory.py
 create mode 100644 studio/backend/hub/schemas/__init__.py
 create mode 100644 studio/backend/hub/schemas/datasets.py
 create mode 100644 studio/backend/hub/schemas/downloads.py
 create mode 100644 studio/backend/hub/schemas/inventory.py
 create mode 100644 studio/backend/hub/services/__init__.py
 create mode 100644 studio/backend/hub/services/datasets/__init__.py
 create mode 100644 studio/backend/hub/services/datasets/cache_inventory.py
 create mode 100644 studio/backend/hub/services/datasets/downloads.py
 create mode 100644 studio/backend/hub/services/datasets/formatting.py
 create mode 100644 studio/backend/hub/services/datasets/local.py
 create mode 100644 studio/backend/hub/services/download_lifecycle.py
 create mode 100644 studio/backend/hub/services/models/__init__.py
 create mode 100644 studio/backend/hub/services/models/cache_inventory.py
 create mode 100644 studio/backend/hub/services/models/common.py
 create mode 100644 studio/backend/hub/services/models/deletion.py
 create mode 100644 studio/backend/hub/services/models/downloads.py
 create mode 100644 studio/backend/hub/services/models/folder_browser.py
 create mode 100644 studio/backend/hub/services/models/gguf_variants.py
 create mode 100644 studio/backend/hub/services/models/local_inventory.py
 create mode 100644 studio/backend/hub/services/models/ollama.py
 create mode 100644 studio/backend/hub/services/snapshot_progress.py
 create mode 100644 studio/backend/hub/storage/__init__.py
 create mode 100644 studio/backend/hub/storage/scan_folders.py
 create mode 100644 studio/backend/hub/tests/conftest.py
 create mode 100644 studio/backend/hub/tests/test_dataset_services.py
 create mode 100644 studio/backend/hub/tests/test_model_services.py
 create mode 100644 studio/backend/hub/utils/__init__.py
 create mode 100644 studio/backend/hub/utils/dataset_cache.py
 create mode 100644 studio/backend/hub/utils/dataset_format.py
 create mode 100644 studio/backend/hub/utils/download_manifest.py
 create mode 100644 studio/backend/hub/utils/download_registry.py
 create mode 100644 studio/backend/hub/utils/gguf.py
 create mode 100644 studio/backend/hub/utils/gguf_plan.py
 create mode 100644 studio/backend/hub/utils/hf_cache_state.py
 create mode 100644 studio/backend/hub/utils/hf_errors.py
 create mode 100644 studio/backend/hub/utils/inventory_scan.py
 create mode 100644 studio/backend/hub/utils/llm_assist.py
 create mode 100644 studio/backend/hub/utils/paths.py
 create mode 100644 studio/backend/hub/utils/snapshot_filters.py
 create mode 100644 studio/backend/hub/utils/state_dir.py
 create mode 100644 studio/backend/hub/workers/__init__.py
 create mode 100644 studio/backend/hub/workers/hf_download.py
 create mode 100644 studio/frontend/public/hub/profile/logo/anthropic.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/cohere.png
 create mode 100644 studio/frontend/public/hub/profile/logo/deepseek.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/google.png
 create mode 100644 studio/frontend/public/hub/profile/logo/hf.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/ibm.png
 create mode 100644 studio/frontend/public/hub/profile/logo/meta.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/microsoft.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/minimax-color.png
 create mode 100644 studio/frontend/public/hub/profile/logo/mistral.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/moonshot.jpg
 create mode 100644 studio/frontend/public/hub/profile/logo/nvidia.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/openai.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/qwen.png
 create mode 100644 studio/frontend/public/hub/profile/logo/xai.svg
 create mode 100644 studio/frontend/public/hub/profile/logo/zai.svg
 create mode 100644 studio/frontend/src/app/routes/hub.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/catalog-states.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/dataset-download-section.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/dot-tag.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/download-cancel-indicator.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/download-card.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/download-section.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/external-link-confirm-dialog.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/gguf-live-variant-states.ts
 create mode 100644 studio/frontend/src/features/hub/catalog/gguf-status-cards.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/local-dataset-card.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/model-inspector.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/model-readme.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/models-catalog-lists.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/models-catalog.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/models-header.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/models-toolbar.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/owner-avatar.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/path-info-button.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/shared.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/transport-conflict-dialog.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/transport-toggle.tsx
 create mode 100644 studio/frontend/src/features/hub/catalog/use-card-delete.ts
 create mode 100644 studio/frontend/src/features/hub/catalog/use-delete-confirm-action.ts
 create mode 100644 studio/frontend/src/features/hub/catalog/use-download-card-state.ts
 create mode 100644 studio/frontend/src/features/hub/catalog/use-gguf-variant-fetch-state.ts
 create mode 100644 studio/frontend/src/features/hub/components/hf-token-indicator.tsx
 create mode 100644 studio/frontend/src/features/hub/components/page-heading.tsx
 create mode 100644 studio/frontend/src/features/hub/components/train-icon.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/api.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/constants.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-manager-config.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-manager-state.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-manager-types.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
 create mode 100644 studio/frontend/src/features/hub/download-manager/hydration.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/index.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/poll-loop.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/runtime-registry.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/transport-conflict.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/transport-preference.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/types.ts
 create mode 100644 studio/frontend/src/features/hub/download-manager/use-repo-download.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-copy-feedback.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-dataset-size.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-discover-search.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-hub-dataset-search.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-hub-infinite-scroll.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-hub-model-search.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-hub-model-vram.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-hub-paginated-search.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-is-hub-desktop.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-latest-ref.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-models-selection.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-online-status.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-selected-model-metadata.ts
 create mode 100644 studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
 create mode 100644 studio/frontend/src/features/hub/hub-page.tsx
 create mode 100644 studio/frontend/src/features/hub/hub.css
 create mode 100644 studio/frontend/src/features/hub/inventory/api.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/constants.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/gguf-variants-cache-events.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/index.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/inventory-dedupe.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/inventory-hint-store.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/inventory-hints.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/resource-resolver.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/types.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/use-device-inventory.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/use-gguf-variants-cache-version.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
 create mode 100644 studio/frontend/src/features/hub/inventory/view-models.ts
 create mode 100644 studio/frontend/src/features/hub/lib/abort-signals.ts
 create mode 100644 studio/frontend/src/features/hub/lib/channels.ts
 create mode 100644 studio/frontend/src/features/hub/lib/dataset-size.ts
 create mode 100644 studio/frontend/src/features/hub/lib/format-filters.ts
 create mode 100644 studio/frontend/src/features/hub/lib/format.ts
 create mode 100644 studio/frontend/src/features/hub/lib/gguf-fit.ts
 create mode 100644 studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hf-cache.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hf-model-meta.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hf-owner-avatar.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hf-readme.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hub-feature-flags.ts
 create mode 100644 studio/frontend/src/features/hub/lib/hub-token-header.ts
 create mode 100644 studio/frontend/src/features/hub/lib/inventory-search.ts
 create mode 100644 studio/frontend/src/features/hub/lib/local-path.ts
 create mode 100644 studio/frontend/src/features/hub/lib/lru-map.ts
 create mode 100644 studio/frontend/src/features/hub/lib/model-capabilities.ts
 create mode 100644 studio/frontend/src/features/hub/lib/model-identifiers.ts
 create mode 100644 studio/frontend/src/features/hub/lib/model-identity.ts
 create mode 100644 studio/frontend/src/features/hub/lib/network.ts
 create mode 100644 studio/frontend/src/features/hub/lib/provider-logos.ts
 create mode 100644 studio/frontend/src/features/hub/lib/search-text.ts
 create mode 100644 studio/frontend/src/features/hub/lib/selection-resolution.ts
 create mode 100644 studio/frontend/src/features/hub/lib/token-fingerprint.ts
 create mode 100644 studio/frontend/src/features/hub/lib/unsloth-support.ts
 create mode 100644 studio/frontend/src/features/hub/lib/view-models.ts
 create mode 100644 studio/frontend/src/features/hub/stores/external-link-confirm.ts
 create mode 100644 studio/frontend/src/features/hub/stores/hf-token-store.ts
 create mode 100644 studio/frontend/src/features/hub/stores/inventory-events.ts
 create mode 100644 studio/frontend/src/features/hub/types.ts

diff --git a/studio/backend/hub/__init__.py b/studio/backend/hub/__init__.py
new file mode 100644
index 0000000000..706dae9224
--- /dev/null
+++ b/studio/backend/hub/__init__.py
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hub + Download Manager feature module.
+
+Self-contained routes, schemas, utilities, workers, and storage for the model
+inventory layer and the HuggingFace download manager. Wired into the FastAPI
+app via two routers plus startup/shutdown hooks in main.py."""
diff --git a/studio/backend/hub/dependencies.py b/studio/backend/hub/dependencies.py
new file mode 100644
index 0000000000..ff78dce8f6
--- /dev/null
+++ b/studio/backend/hub/dependencies.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared FastAPI dependencies for Hub routes."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import Header
+
+HUB_HF_TOKEN_HEADER = "X-Unsloth-HF-Token"
+HUB_HF_TOKEN_MAX_LENGTH = 512
+
+
+def get_hf_token(
+    hf_token: Optional[str] = Header(
+        None,
+        alias = HUB_HF_TOKEN_HEADER,
+        max_length = HUB_HF_TOKEN_MAX_LENGTH,
+    ),
+) -> Optional[str]:
+    token = (hf_token or "").strip()
+    return token or None
diff --git a/studio/backend/hub/routes/__init__.py b/studio/backend/hub/routes/__init__.py
new file mode 100644
index 0000000000..e9579635b0
--- /dev/null
+++ b/studio/backend/hub/routes/__init__.py
@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hub routers exposed at /api/hub/* and /api/hub/datasets/*."""
+
+from hub.routes.inventory import router as inventory_router
+from hub.routes.datasets import router as datasets_router
+
+__all__ = [
+    "inventory_router",
+    "datasets_router",
+]
diff --git a/studio/backend/hub/routes/datasets.py b/studio/backend/hub/routes/datasets.py
new file mode 100644
index 0000000000..edf4f36ac0
--- /dev/null
+++ b/studio/backend/hub/routes/datasets.py
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Endpoints mounted at /api/hub/datasets/*."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Body, Depends, Query, UploadFile
+
+from auth.authentication import get_current_subject
+from hub.dependencies import get_hf_token
+from hub.schemas.datasets import (
+    AiAssistMappingRequest,
+    AiAssistMappingResponse,
+    CachedDatasetsResponse,
+    CheckFormatRequest,
+    CheckFormatResponse,
+    DeleteCachedDatasetResponse,
+    LocalDatasetsResponse,
+    UploadDatasetResponse,
+)
+from hub.schemas.downloads import (
+    ActiveDownloadsResponse,
+    CancelDatasetDownloadRequest,
+    CancelDatasetDownloadResponse,
+    DatasetDownloadJobStatus,
+    DatasetDownloadStartResponse,
+    DownloadProgressResponse,
+    DownloadDatasetRequest,
+    TransportStatusResponse,
+)
+from hub.services.datasets import cache_inventory, downloads, formatting, local
+
+router = APIRouter()
+
+
+@router.post("/upload", response_model = UploadDatasetResponse)
+async def upload_dataset(
+    file: UploadFile, current_subject: str = Depends(get_current_subject)
+) -> UploadDatasetResponse:
+    return await local.upload_dataset_response(file)
+
+
+@router.get("/local", response_model = LocalDatasetsResponse)
+def list_local_datasets(
+    current_subject: str = Depends(get_current_subject),
+) -> LocalDatasetsResponse:
+    return local.list_local_datasets_response()
+
+
+@router.get(
+    "/cached",
+    response_model = CachedDatasetsResponse,
+    response_model_exclude_unset = True,
+)
+async def list_cached_datasets(current_subject: str = Depends(get_current_subject)):
+    return await cache_inventory.list_cached_datasets_response()
+
+
+@router.delete("/cached", response_model = DeleteCachedDatasetResponse)
+async def delete_cached_dataset(
+    repo_id: str = Body(..., embed = True), current_subject: str = Depends(get_current_subject)
+):
+    return await cache_inventory.delete_cached_dataset_response(repo_id)
+
+
+@router.get("/download-progress", response_model = DownloadProgressResponse)
+async def get_dataset_download_progress(
+    repo_id: str = Query(..., description = "HuggingFace dataset repo ID, e.g. 'unsloth/LaTeX_OCR'"),
+    expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_dataset_download_progress_response(
+        repo_id,
+        expected_bytes = expected_bytes,
+        hf_token = hf_token,
+    )
+
+
+@router.post("/download", response_model = DatasetDownloadStartResponse, status_code = 202)
+async def download_dataset(
+    body: DownloadDatasetRequest,
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.download_dataset_response(body, hf_token)
+
+
+@router.post("/download/cancel", response_model = CancelDatasetDownloadResponse, status_code = 202)
+async def cancel_dataset_download(
+    body: CancelDatasetDownloadRequest, current_subject: str = Depends(get_current_subject)
+):
+    return await downloads.cancel_dataset_download_response(body)
+
+
+@router.get("/download-status", response_model = DatasetDownloadJobStatus)
+async def get_dataset_download_status(
+    repo_id: str = Query(..., description = "HuggingFace dataset repo ID"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_dataset_download_status_response(repo_id)
+
+
+@router.get("/active-downloads", response_model = ActiveDownloadsResponse)
+async def get_active_dataset_downloads(
+    repo_id: str = Query("", description = "HuggingFace dataset repo ID"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_active_dataset_downloads_response(repo_id)
+
+
+@router.get("/transport-status", response_model = TransportStatusResponse)
+async def get_dataset_transport_status(
+    repo_id: str = Query(..., description = "HuggingFace dataset repo ID"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_dataset_transport_status_response(repo_id)
+
+
+@router.post("/check-format", response_model = CheckFormatResponse)
+def check_format(
+    request: CheckFormatRequest,
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return formatting.check_format_response(request, hf_token)
+
+
+@router.post("/ai-assist-mapping", response_model = AiAssistMappingResponse)
+def ai_assist_mapping(
+    request: AiAssistMappingRequest,
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return formatting.ai_assist_mapping_response(request, hf_token)
diff --git a/studio/backend/hub/routes/inventory.py b/studio/backend/hub/routes/inventory.py
new file mode 100644
index 0000000000..fcfdd0ad14
--- /dev/null
+++ b/studio/backend/hub/routes/inventory.py
@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Endpoints mounted at /api/hub/* for the model inventory."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Body, Depends, Query
+
+from auth.authentication import get_current_subject
+from hub.dependencies import get_hf_token
+from hub.schemas.downloads import (
+    ActiveDownloadsResponse,
+    CancelDownloadResponse,
+    CancelDownloadRequest,
+    DownloadProgressResponse,
+    DownloadJobStatus,
+    DownloadModelRequest,
+    DownloadStartResponse,
+    TransportStatusResponse,
+)
+from hub.schemas.inventory import (
+    AddScanFolderRequest,
+    BrowseFoldersResponse,
+    CachedGgufResponse,
+    CachedModelsResponse,
+    DeleteCachedModelResponse,
+    GgufVariantsResponse,
+    LocalModelListResponse,
+    RecommendedFoldersResponse,
+    RemoveScanFolderResponse,
+    ScanFolderInfo,
+    ScanFoldersResponse,
+)
+from hub.services.models import (
+    cache_inventory,
+    deletion,
+    downloads,
+    folder_browser,
+    gguf_variants,
+    local_inventory,
+)
+
+router = APIRouter()
+
+
+@router.get("/local", response_model = LocalModelListResponse)
+async def list_local_models(
+    models_dir: str = Query(
+        default = "./models", description = "Directory to scan for local model folders"
+    ),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await local_inventory.list_local_models_response(models_dir)
+
+
+# Plain `def` (not async): synchronous SQLite + filesystem work runs in
+# FastAPI's thread-pool instead of blocking the event loop.
+@router.get("/scan-folders", response_model = ScanFoldersResponse)
+def get_scan_folders(current_subject: str = Depends(get_current_subject)):
+    return local_inventory.get_scan_folders_response()
+
+
+@router.post("/scan-folders", response_model = ScanFolderInfo, status_code = 201)
+def add_scan_folder_endpoint(
+    body: AddScanFolderRequest, current_subject: str = Depends(get_current_subject)
+):
+    return local_inventory.add_scan_folder_response(body.path)
+
+
+@router.delete("/scan-folders/{folder_id}", response_model = RemoveScanFolderResponse)
+def remove_scan_folder_endpoint(
+    folder_id: int, current_subject: str = Depends(get_current_subject)
+):
+    return local_inventory.remove_scan_folder_response(folder_id)
+
+
+@router.get("/recommended-folders", response_model = RecommendedFoldersResponse)
+def get_recommended_folders(current_subject: str = Depends(get_current_subject)):
+    return folder_browser.get_recommended_folders_response()
+
+
+@router.get("/browse-folders", response_model = BrowseFoldersResponse)
+def browse_folders(
+    path: Optional[str] = Query(None),
+    show_hidden: bool = Query(False),
+    current_subject: str = Depends(get_current_subject),
+):
+    return folder_browser.browse_folders_response(path, show_hidden)
+
+
+@router.get("/gguf-variants", response_model = GgufVariantsResponse)
+async def get_gguf_variants(
+    repo_id: str = Query(
+        ..., description = "HuggingFace repo ID (e.g. 'unsloth/gemma-3-4b-it-GGUF')"
+    ),
+    prefer_local_cache: bool = Query(False),
+    offline: bool = Query(False),
+    local_path: Optional[str] = Query(None),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await gguf_variants.get_gguf_variants_response(
+        repo_id,
+        prefer_local_cache = prefer_local_cache,
+        offline = offline,
+        local_path = local_path,
+        hf_token = hf_token,
+    )
+
+
+@router.post("/download", response_model = DownloadStartResponse, status_code = 202)
+async def download_model(
+    body: DownloadModelRequest,
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.download_model_response(body, hf_token)
+
+
+@router.post("/download/cancel", response_model = CancelDownloadResponse, status_code = 202)
+async def cancel_download_model(
+    body: CancelDownloadRequest, current_subject: str = Depends(get_current_subject)
+):
+    return await downloads.cancel_download_model_response(body)
+
+
+@router.get("/download-status", response_model = DownloadJobStatus)
+async def get_download_status(
+    repo_id: str = Query(..., description = "HuggingFace repo ID"),
+    gguf_variant: str = Query("", description = "Quantization variant (empty for safetensors)"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_download_status_response(repo_id, gguf_variant)
+
+
+@router.get("/active-downloads", response_model = ActiveDownloadsResponse)
+async def get_active_downloads(
+    repo_id: str = Query("", description = "HuggingFace repo ID"),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_active_downloads_response(repo_id)
+
+
+@router.get("/transport-status", response_model = TransportStatusResponse)
+async def get_model_transport_status(
+    repo_id: str = Query(..., description = "HuggingFace repo ID"),
+    gguf_variant: str = Query("", description = "Quantization variant (empty for safetensors)"),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_model_transport_status_response(
+        repo_id,
+        gguf_variant,
+        hf_token,
+    )
+
+
+@router.get(
+    "/gguf-download-progress",
+    response_model = DownloadProgressResponse,
+    response_model_exclude_none = True,
+)
+async def get_gguf_download_progress(
+    repo_id: str = Query(..., description = "HuggingFace repo ID"),
+    variant: str = Query("", description = "Quantization variant (e.g. UD-TQ1_0)"),
+    expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_gguf_download_progress_response(
+        repo_id,
+        variant = variant,
+        expected_bytes = expected_bytes,
+        hf_token = hf_token,
+    )
+
+
+@router.get("/download-progress", response_model = DownloadProgressResponse)
+async def get_download_progress(
+    repo_id: str = Query(..., description = "HuggingFace repo ID"),
+    expected_bytes: int = Query(0, description = "Expected total download size in bytes"),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await downloads.get_download_progress_response(
+        repo_id,
+        expected_bytes = expected_bytes,
+        hf_token = hf_token,
+    )
+
+
+@router.get("/cached-gguf", response_model = CachedGgufResponse)
+async def list_cached_gguf(
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await cache_inventory.list_cached_gguf_response(hf_token)
+
+
+@router.get("/cached-models", response_model = CachedModelsResponse)
+async def list_cached_models(
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await cache_inventory.list_cached_models_response(hf_token)
+
+
+@router.delete(
+    "/delete-cached",
+    response_model = DeleteCachedModelResponse,
+    response_model_exclude_none = True,
+)
+async def delete_cached_model(
+    repo_id: str = Body(...),
+    variant: Optional[str] = Body(None),
+    hf_token: Optional[str] = Depends(get_hf_token),
+    current_subject: str = Depends(get_current_subject),
+):
+    return await deletion.delete_cached_model_response(repo_id, variant, hf_token)
diff --git a/studio/backend/hub/schemas/__init__.py b/studio/backend/hub/schemas/__init__.py
new file mode 100644
index 0000000000..32014236c6
--- /dev/null
+++ b/studio/backend/hub/schemas/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
diff --git a/studio/backend/hub/schemas/datasets.py b/studio/backend/hub/schemas/datasets.py
new file mode 100644
index 0000000000..02365b1992
--- /dev/null
+++ b/studio/backend/hub/schemas/datasets.py
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class CheckFormatRequest(BaseModel):
+    dataset_name: str
+    is_vlm: bool = False
+    subset: Optional[str] = None
+    train_split: Optional[str] = "train"
+    prefer_local_cache: bool = False
+    local_path: Optional[str] = None
+
+    @model_validator(mode = "before")
+    @classmethod
+    def _compat_split(cls, values: Any) -> Any:
+        if isinstance(values, dict) and "split" in values:
+            merged = {**values}
+            merged.setdefault("train_split", merged.pop("split"))
+            return merged
+        return values
+
+
+class CheckFormatResponse(BaseModel):
+    requires_manual_mapping: bool
+    detected_format: str
+    columns: List[str]
+    is_image: bool = False
+    is_audio: bool = False
+    multimodal_columns: Optional[List[str]] = None
+    suggested_mapping: Optional[Dict[str, str]] = None
+    detected_image_column: Optional[str] = None
+    detected_audio_column: Optional[str] = None
+    detected_text_column: Optional[str] = None
+    detected_speaker_column: Optional[str] = None
+    preview_samples: Optional[List[Dict]] = None
+    total_rows: Optional[int] = None
+    warning: Optional[str] = None
+
+
+class AiAssistMappingRequest(BaseModel):
+    columns: List[str]
+    samples: List[Dict[str, Any]]
+    dataset_name: Optional[str] = None
+    model_name: Optional[str] = None
+    model_type: Optional[str] = None
+
+
+class AiAssistMappingResponse(BaseModel):
+    success: bool
+    suggested_mapping: Optional[Dict[str, str]] = None
+    warning: Optional[str] = None
+    system_prompt: Optional[str] = None
+    user_template: Optional[str] = None
+    assistant_template: Optional[str] = None
+    label_mapping: Optional[Dict[str, Dict[str, str]]] = None
+    dataset_type: Optional[str] = None
+    is_conversational: Optional[bool] = None
+    user_notification: Optional[str] = None
+
+
+class UploadDatasetResponse(BaseModel):
+    filename: str = Field(..., description = "Original filename")
+    stored_path: str = Field(..., description = "Absolute path stored on backend")
+
+
+class LocalDatasetItem(BaseModel):
+    class Metadata(BaseModel):
+        actual_num_records: Optional[int] = None
+        target_num_records: Optional[int] = None
+        total_num_batches: Optional[int] = None
+        num_completed_batches: Optional[int] = None
+        columns: Optional[List[str]] = None
+
+    id: str
+    label: str
+    path: str
+    source: Literal["recipe", "upload"]
+    rows: Optional[int] = None
+    updated_at: Optional[float] = None
+    metadata: Optional[Metadata] = None
+
+
+class LocalDatasetsResponse(BaseModel):
+    datasets: List[LocalDatasetItem] = Field(default_factory = list)
+
+
+class CachedDatasetItem(BaseModel):
+    repo_id: str
+    size_bytes: int = 0
+    cache_path: Optional[str] = None
+    processed_cache: bool = False
+    partial: bool = False
+    partial_transport: Optional[str] = None
+
+
+class CachedDatasetsResponse(BaseModel):
+    cached: List[CachedDatasetItem] = Field(default_factory = list)
+
+
+class DeleteCachedDatasetResponse(BaseModel):
+    status: str
+    repo_id: str
diff --git a/studio/backend/hub/schemas/downloads.py b/studio/backend/hub/schemas/downloads.py
new file mode 100644
index 0000000000..dccd0c6733
--- /dev/null
+++ b/studio/backend/hub/schemas/downloads.py
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Pydantic schemas for the Hub download manager (/api/hub/downloads/*)."""
+
+from pydantic import BaseModel, Field
+from typing import List, Literal, Optional
+
+
+DownloadJobState = Literal["idle", "running", "cancelling", "cancelled", "complete", "error"]
+
+
+class DownloadModelRequest(BaseModel):
+    """Body for POST /api/hub/download.
+
+    The HuggingFace token travels in the internal Hub token header.
+    """
+
+    repo_id: str = Field(
+        ...,
+        description = "HuggingFace repo ID, e.g. 'unsloth/Qwen3-4B-GGUF'",
+    )
+    gguf_variant: Optional[str] = Field(
+        None,
+        description = "Quantization label (e.g. 'Q4_K_M'). Required for GGUF repos.",
+    )
+    use_xet: bool = Field(
+        False,
+        description = "Enable Xet parallel chunked transport. Default False uses HTTP Range-resume.",
+    )
+
+
+class CancelDownloadRequest(BaseModel):
+    repo_id: str = Field(..., description = "HuggingFace repo ID")
+    gguf_variant: Optional[str] = Field(
+        None,
+        description = "GGUF variant label; omit for safetensors snapshots",
+    )
+    generation: Optional[int] = Field(
+        None,
+        description = "Download generation tag from a prior start; passing it scopes the cancel to that exact run.",
+    )
+
+
+class DownloadJobStatus(BaseModel):
+    """Live state of a background download job."""
+
+    state: DownloadJobState = Field(
+        ...,
+        description = "Current download job state.",
+    )
+    error: Optional[str] = Field(None, description = "Error message if state == 'error'")
+    generation: int = Field(
+        0,
+        description = "Current run generation; an adopting client stores it so a later cancel is scoped to this exact run.",
+    )
+
+
+class DownloadStartResponse(BaseModel):
+    job_key: str
+    state: str
+    accepted: bool
+    generation: int
+
+
+class CancelDownloadResponse(BaseModel):
+    job_key: str
+    state: str
+
+
+class ActiveDownload(BaseModel):
+    """One in-flight download for a repo. ``variant`` is null for safetensors."""
+
+    repo_id: Optional[str] = None
+    variant: Optional[str] = None
+    transport: Optional[str] = None
+    state: str
+    generation: int = Field(
+        0,
+        description = "Current run generation; an adopting client stores it so a later cancel is scoped to this exact run.",
+    )
+
+
+class ActiveDownloadsResponse(BaseModel):
+    downloads: List[ActiveDownload]
+
+
+class TransportCapability(BaseModel):
+    available: bool
+    reason: Optional[str] = None
+
+
+class TransportCapabilities(BaseModel):
+    http: TransportCapability
+    xet: TransportCapability
+
+
+class TransportStatusResponse(BaseModel):
+    has_partial: bool
+    last_transport: Optional[str] = None
+    resumable: bool
+
+
+class DownloadProgressResponse(BaseModel):
+    downloaded_bytes: int
+    # Finalized-blob bytes only (no ``.incomplete``). Registry-loss completion
+    # fallbacks key off this so a partial isn't mistaken for a finished download.
+    completed_bytes: int = 0
+    complete_on_disk: bool = Field(
+        False,
+        description = (
+            "True only when the backend verified a usable completed snapshot/variant on disk."
+        ),
+    )
+    expected_bytes: int
+    progress: float
+    cache_path: Optional[str] = None
+
+
+class DownloadDatasetRequest(BaseModel):
+    """Body for POST /api/hub/datasets/download.
+
+    The HuggingFace token travels in the internal Hub token header.
+    """
+
+    repo_id: str = Field(..., description = "HuggingFace dataset repo ID")
+    use_xet: bool = Field(
+        False,
+        description = "Enable Xet parallel chunked transport. Default False uses HTTP Range-resume.",
+    )
+
+
+class CancelDatasetDownloadRequest(BaseModel):
+    repo_id: str = Field(..., description = "HuggingFace dataset repo ID")
+    generation: Optional[int] = Field(None, description = "Download generation")
+
+
+class DatasetDownloadJobStatus(BaseModel):
+    """Live state of a background dataset download job."""
+
+    state: DownloadJobState = Field(
+        ...,
+        description = "Current dataset download job state.",
+    )
+    error: Optional[str] = Field(None, description = "Error message if state == 'error'")
+    generation: int = Field(
+        0,
+        description = "Current run generation; an adopting client stores it so a later cancel is scoped to this exact run.",
+    )
+
+
+class DatasetDownloadStartResponse(BaseModel):
+    repo_id: str
+    state: str
+    accepted: bool
+    generation: int
+
+
+class CancelDatasetDownloadResponse(BaseModel):
+    repo_id: str
+    state: str
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
new file mode 100644
index 0000000000..c333c7ca89
--- /dev/null
+++ b/studio/backend/hub/schemas/inventory.py
@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Pydantic schemas for the Hub inventory layer (/api/hub/*).
+
+Kept independent from upstream models/models.py so the Hub module can ship
+without modifying any upstream schema."""
+
+from pydantic import BaseModel, Field
+from typing import List, Literal, Optional
+
+
+ModelFormat = Literal["gguf", "safetensors", "adapter", "checkpoint", "unknown"]
+ModelRuntime = Literal["llama_cpp", "transformers", "adapter", "unknown"]
+
+
+class GgufVariantDetail(BaseModel):
+    """A single GGUF quantization variant in a HuggingFace repo."""
+
+    filename: str = Field(..., description = "GGUF filename (e.g., 'gemma-3-4b-it-Q4_K_M.gguf')")
+    quant: str = Field(..., description = "Quantization label or internal GGUF variant key")
+    display_label: Optional[str] = Field(
+        None, description = "Optional user-facing label when quant is an internal key"
+    )
+    size_bytes: int = Field(0, description = "File size in bytes")
+    download_size_bytes: int = Field(0, description = "Total bytes needed to download this variant")
+    downloaded: bool = Field(
+        False, description = "Whether this variant is already in the local HF cache"
+    )
+    partial: bool = Field(
+        False,
+        description = "Whether this variant has an in-progress (.incomplete) blob in cache",
+    )
+    partial_transport: Optional[str] = Field(
+        None,
+        description = (
+            'Transport recorded for the partial state ("http" or '
+            '"xet"), or null if not partial / unknown. Frontend uses '
+            "this to pick Resume (http) vs Redownload (xet) labels."
+        ),
+    )
+
+
+class GgufVariantsResponse(BaseModel):
+    """Response for listing GGUF quantization variants in a HuggingFace repo."""
+
+    repo_id: str = Field(..., description = "HuggingFace repo ID")
+    variants: List[GgufVariantDetail] = Field(
+        default_factory = list, description = "Available GGUF variants"
+    )
+    has_vision: bool = Field(
+        False, description = "Whether the model has vision support (mmproj files)"
+    )
+    default_variant: Optional[str] = Field(
+        None, description = "Recommended default quantization variant"
+    )
+
+
+class LocalModelCapabilities(BaseModel):
+    can_train: bool = False
+    can_chat: bool = False
+    can_delete: bool = False
+    can_download: bool = False
+    requires_variant: bool = False
+    supports_lora: bool = False
+    supports_vision: bool = False
+
+
+class LocalModelInfo(BaseModel):
+    """Discovered local model candidate."""
+
+    id: str = Field(..., description = "Identifier to use for loading/training")
+    inventory_id: Optional[str] = Field(
+        None, description = "Stable semantic inventory row identifier"
+    )
+    load_id: Optional[str] = Field(
+        None, description = "Identifier/path to pass to load or train APIs"
+    )
+    display_name: str = Field(..., description = "Display label")
+    path: str = Field(..., description = "Local path where model data was discovered")
+    size_bytes: int = Field(0, description = "Observed model artifact size in bytes")
+    model_format: ModelFormat = Field("unknown", description = "Model file format")
+    runtime: ModelRuntime = Field("unknown", description = "Expected runtime backend")
+    format_variant: Optional[str] = Field(
+        None, description = "Format variant label, for example a GGUF quant"
+    )
+    capabilities: LocalModelCapabilities = Field(
+        default_factory = LocalModelCapabilities,
+        description = "Declared capabilities for this inventory row",
+    )
+    source: Literal["models_dir", "hf_cache", "lmstudio", "ollama", "custom"] = Field(
+        ...,
+        description = "Discovery source",
+    )
+    model_id: Optional[str] = Field(
+        None,
+        description = "HF repo id for cached models, e.g. org/model",
+    )
+    base_model: Optional[str] = Field(
+        None,
+        description = "Base model from adapter_config.json when this is an adapter",
+    )
+    base_model_source: Optional[Literal["huggingface", "local", "unknown"]] = Field(
+        None,
+        description = "Whether the adapter base model is a HF repo id or local path",
+    )
+    adapter_type: Optional[str] = Field(
+        None,
+        description = "Adapter type from adapter_config.json, e.g. LORA",
+    )
+    training_method: Optional[str] = Field(
+        None,
+        description = "Training method hint from adapter_config.json",
+    )
+    updated_at: Optional[float] = Field(
+        None,
+        description = "Unix timestamp of latest observed update",
+    )
+    partial: bool = Field(
+        False,
+        description = "True when this hf_cache entry has incomplete blobs",
+    )
+    partial_transport: Optional[str] = Field(
+        None,
+        description = (
+            'Transport recorded for the partial state ("http" or '
+            '"xet"), or null if not partial / unknown.'
+        ),
+    )
+
+
+class LocalModelListResponse(BaseModel):
+    """Response schema for listing local/cached models."""
+
+    models_dir: str = Field(..., description = "Directory scanned for custom local models")
+    hf_cache_dir: Optional[str] = Field(
+        None,
+        description = "HF cache root that was scanned",
+    )
+    lmstudio_dirs: List[str] = Field(
+        default_factory = list,
+        description = "LM Studio model directories that were scanned",
+    )
+    ollama_dirs: List[str] = Field(
+        default_factory = list,
+        description = "Ollama model directories that were scanned",
+    )
+    models: List[LocalModelInfo] = Field(
+        default_factory = list,
+        description = "Discovered local/cached models",
+    )
+
+
+class CachedRepoBase(BaseModel):
+    """Shared shape for a cached HF repo row surfaced under On Device."""
+
+    repo_id: str
+    size_bytes: int = 0
+    cache_path: Optional[str] = None
+    partial: bool = False
+    partial_transport: Optional[str] = None
+    inventory_id: Optional[str] = None
+    load_id: Optional[str] = None
+    model_format: ModelFormat = "unknown"
+    runtime: ModelRuntime = "unknown"
+    format_variant: Optional[str] = None
+    capabilities: LocalModelCapabilities = Field(default_factory = LocalModelCapabilities)
+
+
+class CachedGgufRepo(CachedRepoBase):
+    model_format: ModelFormat = "gguf"
+
+
+class CachedGgufResponse(BaseModel):
+    cached: List[CachedGgufRepo] = Field(default_factory = list)
+
+
+class CachedModelRepo(CachedRepoBase):
+    quant_method: Optional[str] = None
+    pipeline_tag: Optional[str] = None
+    library_name: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+class CachedModelsResponse(BaseModel):
+    cached: List[CachedModelRepo] = Field(default_factory = list)
+
+
+class AddScanFolderRequest(BaseModel):
+    """Request body for adding a custom scan folder."""
+
+    path: str = Field(
+        ...,
+        description = "Absolute or relative folder path, or a model weight file path",
+    )
+
+
+class ScanFolderInfo(BaseModel):
+    """A registered custom model scan folder."""
+
+    id: int = Field(..., description = "Database row ID")
+    path: str = Field(..., description = "Normalized absolute path")
+    created_at: str = Field(..., description = "ISO 8601 creation timestamp")
+
+
+class ScanFoldersResponse(BaseModel):
+    folders: List[ScanFolderInfo] = Field(default_factory = list)
+
+
+class RemoveScanFolderResponse(BaseModel):
+    ok: bool
+
+
+class RecommendedFoldersResponse(BaseModel):
+    folders: List[str] = Field(default_factory = list)
+
+
+class DeleteCachedModelResponse(BaseModel):
+    status: str
+    repo_id: str
+    variant: Optional[str] = None
+
+
+class BrowseEntry(BaseModel):
+    """A directory entry surfaced by the folder browser."""
+
+    name: str = Field(..., description = "Entry name (basename, not full path)")
+    has_models: bool = Field(
+        False,
+        description = (
+            "Hint that the directory likely contains models "
+            "(*.gguf, *.safetensors, config.json, or HF-style "
+            "`models--*` subfolders). Used by the UI to highlight "
+            "promising candidates; the scanner itself is authoritative."
+        ),
+    )
+    hidden: bool = Field(
+        False,
+        description = "Name starts with a dot (e.g. `.cache`)",
+    )
+
+
+class BrowseFoldersResponse(BaseModel):
+    """Response schema for the folder browser endpoint."""
+
+    current: str = Field(..., description = "Absolute path of the directory just listed")
+    parent: Optional[str] = Field(
+        None,
+        description = (
+            "Parent directory of `current`, or null if `current` is the "
+            "filesystem root. The frontend uses this to render an `Up` row."
+        ),
+    )
+    entries: List[BrowseEntry] = Field(
+        default_factory = list,
+        description = (
+            "Subdirectories of `current`. Sorted with model-bearing "
+            "directories first, then alphabetically case-insensitive; "
+            "hidden entries come last within each group."
+        ),
+    )
+    suggestions: List[str] = Field(
+        default_factory = list,
+        description = (
+            "Handy starting points (home, HF cache, already-registered "
+            "scan folders). Rendered as quick-pick chips above the list."
+        ),
+    )
+    truncated: bool = Field(
+        False,
+        description = (
+            "True when the listing was capped because the directory had "
+            "more subfolders than the server is willing to enumerate in "
+            "one request. The UI should show a hint telling the user to "
+            "narrow their path."
+        ),
+    )
+    model_files_here: int = Field(
+        0,
+        description = (
+            "Count of GGUF/safetensors files immediately inside "
+            "``current``. Used by the UI to surface a hint on leaf "
+            "model directories (which otherwise look `empty` because "
+            "they contain only files, no subdirectories)."
+        ),
+    )
diff --git a/studio/backend/hub/services/__init__.py b/studio/backend/hub/services/__init__.py
new file mode 100644
index 0000000000..e86fcb6f46
--- /dev/null
+++ b/studio/backend/hub/services/__init__.py
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared helpers for the Hub service layer."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from fastapi import HTTPException
+
+from hub.utils.hf_cache_state import resolve_destructive_case_matches
+
+
+def resolve_destructive_repo_ids(repo_id: str, candidates: Iterable[str], *, noun: str) -> set[str]:
+    """Cache-dir repo ids a destructive op on *repo_id* may target.
+
+    Refuses with 409 on ambiguous case-only matches so a delete never removes
+    the wrong casing. *noun* is the plural shown to the user."""
+    resolved = resolve_destructive_case_matches(repo_id, candidates)
+    if resolved is None:
+        raise HTTPException(
+            status_code = 409,
+            detail = (
+                f"Multiple cached {noun} differ only by case. "
+                "Delete the exact repo casing from On Device."
+            ),
+        )
+    return resolved
diff --git a/studio/backend/hub/services/datasets/__init__.py b/studio/backend/hub/services/datasets/__init__.py
new file mode 100644
index 0000000000..c917f7bc02
--- /dev/null
+++ b/studio/backend/hub/services/datasets/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Dataset services for Hub routes."""
diff --git a/studio/backend/hub/services/datasets/cache_inventory.py b/studio/backend/hub/services/datasets/cache_inventory.py
new file mode 100644
index 0000000000..a180c9df58
--- /dev/null
+++ b/studio/backend/hub/services/datasets/cache_inventory.py
@@ -0,0 +1,474 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Cached dataset inventory and deletion services."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.services import resolve_destructive_repo_ids
+from hub.services.datasets import downloads
+from hub.utils import download_manifest
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.hf_cache_state import (
+    purge_partial_repo,
+    purge_repo_cache_dirs,
+    resolve_destructive_case_matches,
+)
+from hub.utils.paths import (
+    hf_default_cache_dir,
+    is_valid_repo_id as _is_valid_repo_id,
+    legacy_hf_cache_dir,
+    resolve_cached_repo_id_case,
+)
+
+logger = get_logger(__name__)
+
+
+def _collect_hf_cache_scans() -> tuple[list, set[str]]:
+    scans = hf_cache_scan.all_hf_cache_scans()
+    seen_roots = {
+        str(cache_dir)
+        for cache_dir in (getattr(scan, "cache_dir", None) for scan in scans)
+        if cache_dir is not None
+    }
+    return scans, seen_roots
+
+
+def _hf_hub_cache_roots() -> list[Path]:
+    roots: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(path: Optional[Path]) -> None:
+        if path is None or not path.is_dir():
+            return
+        try:
+            resolved = str(path.resolve())
+        except OSError:
+            return
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        roots.append(path)
+
+    try:
+        from huggingface_hub.constants import HF_HUB_CACHE
+        _add(Path(HF_HUB_CACHE))
+    except Exception:
+        pass
+
+    hf_hub_cache = os.environ.get("HF_HUB_CACHE")
+    if hf_hub_cache:
+        _add(Path(hf_hub_cache).expanduser())
+
+    hf_home = os.environ.get("HF_HOME")
+    if hf_home:
+        _add(Path(hf_home).expanduser() / "hub")
+
+    _add(legacy_hf_cache_dir())
+    _add(hf_default_cache_dir())
+    return roots
+
+
+def _repo_id_from_hub_dataset_dir(name: str) -> str | None:
+    if not name.startswith("datasets--"):
+        return None
+    encoded = name.removeprefix("datasets--")
+    owner, sep, repo = encoded.partition("--")
+    if not sep or not owner or not repo:
+        return None
+    repo_id = f"{owner}/{repo}"
+    return repo_id if _is_valid_repo_id(repo_id) else None
+
+
+def _directory_size(path: Path) -> int:
+    total = 0
+    try:
+        for entry in path.rglob("*"):
+            try:
+                if entry.is_file() and not entry.is_symlink():
+                    total += entry.stat().st_size
+            except OSError:
+                continue
+    except OSError:
+        return 0
+    return total
+
+
+def _prefer_dataset_cache_row(candidate: dict, existing: Optional[dict]) -> bool:
+    if existing is None:
+        return True
+    candidate_partial = bool(candidate.get("partial"))
+    existing_partial = bool(existing.get("partial"))
+    if candidate_partial != existing_partial:
+        return not candidate_partial
+    return int(candidate.get("size_bytes") or 0) > int(existing.get("size_bytes") or 0)
+
+
+def _hub_dataset_snapshot_count(path: Path) -> int:
+    snapshots = path / "snapshots"
+    try:
+        return sum(1 for entry in snapshots.iterdir() if entry.is_dir())
+    except OSError:
+        return 0
+
+
+def _scan_hub_dataset_cache_dirs() -> list[dict]:
+    """Fallback scanner: ``scan_cache_dir()`` skips repos when one cache entry is partially corrupt, so this keeps On Device matching disk."""
+    seen_lower: dict[str, dict] = {}
+    for root in _hf_hub_cache_roots():
+        try:
+            entries = [entry for entry in root.iterdir() if entry.is_dir()]
+        except OSError:
+            continue
+        for entry in entries:
+            repo_id = _repo_id_from_hub_dataset_dir(entry.name)
+            if repo_id is None:
+                continue
+            size_bytes = _directory_size(entry / "blobs")
+            if size_bytes <= 0:
+                size_bytes = _directory_size(entry)
+            if size_bytes <= 0:
+                continue
+            key = repo_id.lower()
+            existing = seen_lower.get(key)
+            snapshot_partial = _hub_dataset_snapshot_count(
+                entry
+            ) == 0 or hf_cache_scan.is_snapshot_partial("dataset", repo_id, entry)
+            row = {
+                "repo_id": repo_id,
+                "size_bytes": size_bytes,
+                "cache_path": str(entry.resolve()),
+                # snapshot_count == 0 catches blobs-but-no-snapshot;
+                # is_snapshot_partial adds active-row state checks.
+                "partial": snapshot_partial,
+                "partial_transport": (
+                    hf_cache_scan.partial_transport_for(
+                        "dataset",
+                        repo_id,
+                        repo_cache_dir = entry,
+                    )
+                    if snapshot_partial
+                    else None
+                ),
+            }
+            if _prefer_dataset_cache_row(row, existing):
+                seen_lower[key] = row
+    return sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+
+
+def _hf_datasets_cache_roots() -> list[Path]:
+    roots: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(path: Optional[Path]) -> None:
+        if path is None or not path.is_dir():
+            return
+        try:
+            resolved = str(path.resolve())
+        except OSError:
+            return
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        roots.append(path)
+
+    env_cache = os.environ.get("HF_DATASETS_CACHE")
+    if env_cache:
+        _add(Path(env_cache).expanduser())
+
+    try:
+        from datasets import config as datasets_config
+        _add(Path(datasets_config.HF_DATASETS_CACHE))
+    except Exception:
+        pass
+
+    hf_home = os.environ.get("HF_HOME")
+    if hf_home:
+        _add(Path(hf_home).expanduser() / "datasets")
+
+    xdg_cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")).expanduser()
+    _add(xdg_cache / "huggingface" / "datasets")
+    return roots
+
+
+def _repo_id_from_datasets_cache_dir(name: str) -> str | None:
+    if "___" not in name:
+        return None
+    owner, repo = name.split("___", 1)
+    repo_id = f"{owner}/{repo}"
+    return repo_id if _is_valid_repo_id(repo_id) else None
+
+
+def _processed_dataset_cache_size(path: Path) -> int:
+    total = 0
+    try:
+        for entry in path.rglob("*"):
+            try:
+                if entry.is_file():
+                    total += entry.stat().st_size
+            except OSError:
+                continue
+    except OSError:
+        return 0
+    return total
+
+
+def _looks_like_processed_dataset_cache(path: Path) -> bool:
+    try:
+        for entry in path.rglob("*"):
+            if not entry.is_file():
+                continue
+            if entry.name in {"dataset_info.json", "state.json"}:
+                return True
+            if entry.suffix == ".arrow":
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _scan_processed_dataset_caches() -> list[dict]:
+    """`load_dataset()` stores processed Arrow caches separately from the Hub snapshot cache, so they're usable on-device but invisible to `scan_cache_dir()`."""
+    seen_lower: dict[str, dict] = {}
+    for root in _hf_datasets_cache_roots():
+        try:
+            entries = [entry for entry in root.iterdir() if entry.is_dir()]
+        except OSError:
+            continue
+        for entry in entries:
+            repo_id = _repo_id_from_datasets_cache_dir(entry.name)
+            if repo_id is None:
+                continue
+            if not _looks_like_processed_dataset_cache(entry):
+                continue
+            size_bytes = _processed_dataset_cache_size(entry)
+            if size_bytes <= 0:
+                continue
+            key = repo_id.lower()
+            existing = seen_lower.get(key)
+            if existing is None or size_bytes > existing["size_bytes"]:
+                seen_lower[key] = {
+                    "repo_id": repo_id,
+                    "size_bytes": size_bytes,
+                    "cache_path": str(entry.resolve()),
+                    "processed_cache": True,
+                    "partial": False,
+                }
+    return sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+
+
+def _scan_hf_dataset_caches() -> list[dict]:
+    scans, seen_roots = _collect_hf_cache_scans()
+
+    seen_lower: dict[str, dict] = {}
+    inspected = 0
+    for hf_cache in scans:
+        for repo_info in hf_cache.repos:
+            inspected += 1
+            try:
+                # str(...) guards against the library switching repo_type to an Enum.
+                if str(repo_info.repo_type) != "dataset":
+                    continue
+                total_size = int(getattr(repo_info, "size_on_disk", 0) or 0)
+                if total_size == 0:
+                    unique_blobs: dict[str, int] = {}
+                    for rev in repo_info.revisions:
+                        rev_id = getattr(rev, "commit_hash", None) or str(id(rev))
+                        for f in rev.files:
+                            blob_path = getattr(f, "blob_path", None)
+                            key = str(blob_path) if blob_path else f"{rev_id}:{f.file_name}"
+                            unique_blobs[key] = int(f.size_on_disk or 0)
+                    total_size = sum(unique_blobs.values())
+                key = repo_info.repo_id.lower()
+                existing = seen_lower.get(key)
+                cache_dir = Path(repo_info.repo_path)
+                snapshot_partial = hf_cache_scan.is_snapshot_partial(
+                    "dataset",
+                    repo_info.repo_id,
+                    cache_dir,
+                )
+                row = {
+                    "repo_id": repo_info.repo_id,
+                    "size_bytes": total_size,
+                    "cache_path": str(repo_info.repo_path),
+                    "partial": snapshot_partial,
+                    "partial_transport": (
+                        hf_cache_scan.partial_transport_for(
+                            "dataset",
+                            repo_info.repo_id,
+                            repo_cache_dir = cache_dir,
+                        )
+                        if snapshot_partial
+                        else None
+                    ),
+                }
+                if _prefer_dataset_cache_row(row, existing):
+                    seen_lower[key] = row
+            except Exception as exc:
+                label = getattr(repo_info, "repo_id", "<unknown>")
+                logger.warning("Skipping cached dataset repo %s: %s", label, exc)
+    for row in _scan_hub_dataset_cache_dirs():
+        key = row["repo_id"].lower()
+        existing = seen_lower.get(key)
+        if _prefer_dataset_cache_row(row, existing):
+            seen_lower[key] = row
+        elif existing is not None and bool(existing.get("partial")) == bool(row.get("partial")):
+            existing["size_bytes"] = max(existing["size_bytes"], row["size_bytes"])
+            existing["cache_path"] = existing.get("cache_path") or row.get("cache_path")
+            if (
+                existing.get("partial")
+                and not existing.get("partial_transport")
+                and row.get("partial_transport")
+            ):
+                existing["partial_transport"] = row["partial_transport"]
+    for row in _scan_processed_dataset_caches():
+        key = row["repo_id"].lower()
+        existing = seen_lower.get(key)
+        if existing is None or (bool(existing.get("partial")) and not bool(row.get("partial"))):
+            seen_lower[key] = row
+        else:
+            existing["size_bytes"] = max(existing["size_bytes"], row["size_bytes"])
+            # Keep the processed-cache marker when a repo is both snapshot and
+            # processed Arrow cache; merging by size alone dropped it.
+            if row.get("processed_cache"):
+                existing["processed_cache"] = True
+    logger.info(
+        "Cached dataset scan: roots=%d inspected=%d returned=%d",
+        len(seen_roots) or len(scans),
+        inspected,
+        len(seen_lower),
+    )
+    return sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+
+
+async def list_cached_datasets_response() -> dict:
+    """List dataset repos already downloaded into the HF cache."""
+    try:
+        return {"cached": await asyncio.to_thread(_scan_hf_dataset_caches)}
+    except Exception as exc:
+        logger.error("Error listing cached datasets: %s", exc, exc_info = True)
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to read the local dataset cache.",
+        ) from exc
+
+
+async def delete_cached_dataset_response(repo_id: str) -> dict:
+    """Remove a cached dataset repo from the HF cache."""
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
+
+    repo_key = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
+    if not downloads.registry.begin_delete(repo_key):
+        raise HTTPException(
+            status_code = 400,
+            detail = "Cancel the active download before deleting.",
+        )
+    try:
+        return await asyncio.to_thread(_delete_cached_dataset_blocking, repo_key)
+    finally:
+        downloads.registry.end_delete(repo_key)
+        hf_cache_scan.invalidate_hf_cache_scans()
+
+
+def _delete_cached_dataset_blocking(repo_id: str) -> dict:
+    scans, _seen_roots = _collect_hf_cache_scans()
+
+    candidate_entries = []
+    for hf_cache in scans:
+        for repo_info in hf_cache.repos:
+            if str(repo_info.repo_type) != "dataset":
+                continue
+            if repo_info.repo_id.lower() == repo_id.lower():
+                candidate_entries.append((hf_cache, repo_info))
+    matched_repo_ids = resolve_destructive_repo_ids(
+        repo_id,
+        [str(repo_info.repo_id) for _hf_cache, repo_info in candidate_entries],
+        noun = "datasets",
+    )
+
+    deleted = False
+    failures: list[str] = []
+    for hf_cache, repo_info in candidate_entries:
+        if str(repo_info.repo_id) not in matched_repo_ids:
+            continue
+        try:
+            strategy = hf_cache.delete_revisions(*(rev.commit_hash for rev in repo_info.revisions))
+            strategy.execute()
+            deleted = True
+        except Exception as exc:
+            failures.append(str(exc))
+            logger.error(
+                "Failed deleting cached dataset %s from %s: %s",
+                repo_id,
+                getattr(hf_cache, "cache_dir", "<unknown>"),
+                exc,
+                exc_info = True,
+            )
+
+    processed_deleted, processed_failures = _delete_processed_dataset_cache(repo_id)
+    failures.extend(processed_failures)
+    if failures:
+        raise HTTPException(
+            status_code = 500,
+            detail = (
+                f"Failed to delete dataset from {len(failures)} cache "
+                "location(s). Some files may remain."
+            ),
+        )
+
+    # ``scan_cache_dir()`` skips blob-only/corrupt repos the revision delete
+    # can't touch, yet the fallback scanner shows them; purge the whole dir.
+    cache_purged = purge_repo_cache_dirs("dataset", repo_id)
+    partial_purged = purge_partial_repo("dataset", repo_id)
+    state_purged = download_manifest.purge_all_state_for_repo("dataset", repo_id) > 0
+    if not (deleted or processed_deleted or cache_purged or partial_purged or state_purged):
+        raise HTTPException(status_code = 404, detail = "Dataset not found in cache")
+    return {"status": "deleted", "repo_id": repo_id}
+
+
+def _delete_processed_dataset_cache(repo_id: str) -> tuple[bool, list[str]]:
+    import shutil
+
+    target = repo_id.replace("/", "___")
+    folded_target = target.lower()
+    deleted = False
+    failures: list[str] = []
+    for root in _hf_datasets_cache_roots():
+        try:
+            entries = [
+                entry
+                for entry in root.iterdir()
+                if entry.is_dir() and entry.name.lower() == folded_target
+            ]
+        except OSError:
+            continue
+        matched_names = resolve_destructive_case_matches(
+            target,
+            (entry.name for entry in entries),
+        )
+        if not matched_names:
+            continue
+        for entry in entries:
+            if entry.name not in matched_names:
+                continue
+            try:
+                shutil.rmtree(entry)
+                deleted = True
+            except Exception as exc:
+                failures.append(str(exc))
+                logger.error(
+                    "Failed deleting processed dataset cache %s: %s",
+                    repo_id,
+                    exc,
+                    exc_info = True,
+                )
+    return deleted, failures
diff --git a/studio/backend/hub/services/datasets/downloads.py b/studio/backend/hub/services/datasets/downloads.py
new file mode 100644
index 0000000000..ac90be8c6f
--- /dev/null
+++ b/studio/backend/hub/services/datasets/downloads.py
@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Start, cancel, and report progress for dataset downloads."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from collections import OrderedDict
+from typing import Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.downloads import (
+    ActiveDownloadsResponse,
+    CancelDatasetDownloadRequest,
+    DatasetDownloadJobStatus,
+    DownloadDatasetRequest,
+)
+from hub.services import snapshot_progress
+from hub.services import download_lifecycle
+from hub.utils import download_manifest
+from hub.utils import download_registry
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.hf_cache_state import has_active_incomplete_blobs
+from hub.utils.paths import (
+    is_valid_repo_id as _is_valid_repo_id,
+    resolve_cached_repo_id_case,
+)
+from hub.utils.snapshot_filters import (
+    blob_hashes_for_siblings,
+    total_size_for_siblings,
+)
+
+logger = get_logger(__name__)
+
+_dataset_size_cache: "OrderedDict[str, tuple[int, frozenset[str], bool, str, float]]" = (
+    OrderedDict()
+)
+_dataset_size_neg_cache: "OrderedDict[tuple[str, str], float]" = OrderedDict()
+_DATASET_SIZE_CACHE_MAX = 256
+_DATASET_SIZE_POS_TTL = 60.0
+_DATASET_SIZE_NEG_TTL = 60.0
+_DATASET_SIZE_TIMEOUT_SECONDS = 5.0
+_dataset_size_cache_lock = threading.Lock()
+
+_registry = download_registry.get_datasets_registry()
+
+
+def _download_job_key(repo_id: str) -> str:
+    return download_registry.normalize_repo_key(repo_id)
+
+
+def get_dataset_snapshot_metadata_cached(
+    repo_id: str, hf_token: Optional[str] = None
+) -> tuple[int, frozenset[str]]:
+    """Raw snapshot size + expected blob hashes for a dataset repo.
+
+    The dataset worker downloads every sibling, so the denominator is the full
+    sibling-size sum and the hashes cover every file. Consumed by the shared
+    ``snapshot_progress`` accounting."""
+    token_fp = hf_cache_scan.token_fingerprint(hf_token)
+    cache_key = (repo_id, token_fp)
+    with _dataset_size_cache_lock:
+        cached = _dataset_size_cache.get(repo_id)
+        if cached is not None:
+            size, hashes, restricted, cached_fp, ts = cached
+            if (time.monotonic() - ts) >= _DATASET_SIZE_POS_TTL:
+                del _dataset_size_cache[repo_id]
+            # A gated/private repo's metadata is only served back to the token
+            # that fetched it; another token may have no access at all.
+            elif not restricted or cached_fp == token_fp:
+                _dataset_size_cache.move_to_end(repo_id)
+                return size, hashes
+        neg_ts = _dataset_size_neg_cache.get(cache_key)
+        if neg_ts is not None and (time.monotonic() - neg_ts) < _DATASET_SIZE_NEG_TTL:
+            return 0, frozenset()
+    try:
+        from huggingface_hub import HfApi
+
+        info = HfApi(token = hf_token).dataset_info(
+            repo_id,
+            files_metadata = True,
+            timeout = _DATASET_SIZE_TIMEOUT_SECONDS,
+        )
+        total = total_size_for_siblings(info.siblings)
+        hashes = blob_hashes_for_siblings(info.siblings)
+        restricted = bool(getattr(info, "private", False) or getattr(info, "gated", False))
+    except Exception:
+        with _dataset_size_cache_lock:
+            _dataset_size_neg_cache[cache_key] = time.monotonic()
+            _dataset_size_neg_cache.move_to_end(cache_key)
+            while len(_dataset_size_neg_cache) > _DATASET_SIZE_CACHE_MAX:
+                _dataset_size_neg_cache.popitem(last = False)
+        return 0, frozenset()
+    with _dataset_size_cache_lock:
+        _dataset_size_cache[repo_id] = (
+            total,
+            hashes,
+            restricted,
+            token_fp,
+            time.monotonic(),
+        )
+        _dataset_size_cache.move_to_end(repo_id)
+        _dataset_size_neg_cache.pop(cache_key, None)
+        while len(_dataset_size_cache) > _DATASET_SIZE_CACHE_MAX:
+            _dataset_size_cache.popitem(last = False)
+    return total, hashes
+
+
+async def get_dataset_download_progress_response(
+    repo_id: str,
+    expected_bytes: int = 0,
+    hf_token: Optional[str] = None,
+) -> dict:
+    """Return download progress for a HuggingFace dataset repo.
+
+    Scans the ``datasets--owner--name`` cache dir and shares the blob accounting
+    with the model path via ``snapshot_progress``. Returns ``cache_path`` for the
+    UI."""
+    return await snapshot_progress.snapshot_progress_response(
+        repo_type = "dataset",
+        repo_id = repo_id,
+        job_key = _download_job_key(repo_id),
+        expected_bytes = expected_bytes,
+        hf_token = hf_token,
+        registry = _registry,
+        metadata_resolver = get_dataset_snapshot_metadata_cached,
+    )
+
+
+def _dataset_status(key: str, *, repo_id: Optional[str] = None) -> DatasetDownloadJobStatus:
+    state, error, generation = download_lifecycle.idle_status(
+        _registry,
+        key,
+        repo_type = "dataset",
+        repo_id = repo_id,
+        variant = None,
+    )
+    return DatasetDownloadJobStatus(state = state, error = error, generation = generation)
+
+
+async def download_dataset_response(
+    body: DownloadDatasetRequest, hf_token: Optional[str] = None
+) -> dict:
+    """Start a background download for a HuggingFace dataset."""
+    repo_id = body.repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid repo_id: {repo_id!r}",
+        )
+    # Canonicalize so two different-cased paste-ins share one job + cache dir.
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
+    key = _download_job_key(repo_id)
+
+    transport = download_lifecycle.resolve_transport(body.use_xet)
+
+    claimed, claim_state = _registry.claim(
+        key,
+        transport,
+        repo_type = "dataset",
+        repo_id = repo_id,
+    )
+    generation = _registry.current_generation(key)
+    if not claimed:
+        # Pollable when rejected by this repo's own in-flight job; an
+        # in-progress delete leaves no job, so flag it via ``adoptable``.
+        return {
+            "repo_id": repo_id,
+            "state": claim_state,
+            "accepted": _registry.adoptable(key),
+            "generation": generation,
+        }
+    download_manifest.clear_cancel_marker("dataset", repo_id, None)
+
+    state = download_lifecycle.launch_worker(
+        _registry,
+        key,
+        spawn = lambda: download_lifecycle.spawn_worker(
+            ["--repo-id", repo_id, "--dataset"],
+            hf_token,
+            use_xet = body.use_xet,
+        ),
+        hf_token = hf_token,
+        label = repo_id,
+        log_prefix = "Dataset download",
+        logger = logger,
+        repo_type = "dataset",
+        repo_id = repo_id,
+        transport = transport,
+        watch_name = f"hf-dataset-download-watch-{repo_id}",
+    )
+
+    return {
+        "repo_id": repo_id,
+        "state": state,
+        "accepted": True,
+        "generation": generation,
+    }
+
+
+async def cancel_dataset_download_response(body: CancelDatasetDownloadRequest) -> dict:
+    """Cancel an in-flight dataset download (SIGKILL; HF cache resumes on next download)."""
+    repo_id = body.repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid repo_id: {repo_id!r}",
+        )
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
+    key = _download_job_key(repo_id)
+
+    state = download_lifecycle.cancel_worker(
+        _registry,
+        key,
+        generation = body.generation,
+        label = f"dataset {repo_id}",
+        logger = logger,
+    )
+    return {"repo_id": repo_id, "state": state}
+
+
+async def get_dataset_download_status_response(repo_id: str) -> DatasetDownloadJobStatus:
+    """Return the latest state of a background dataset download job."""
+    repo_id = repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        return DatasetDownloadJobStatus(state = "idle")
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
+    return _dataset_status(_download_job_key(repo_id), repo_id = repo_id)
+
+
+async def get_active_dataset_downloads_response(repo_id: str = "") -> ActiveDownloadsResponse:
+    repo_id = repo_id.strip()
+    if repo_id and not _is_valid_repo_id(repo_id):
+        return ActiveDownloadsResponse(downloads = [])
+    canonical_repo_id = (
+        await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
+        if repo_id
+        else None
+    )
+    return ActiveDownloadsResponse(
+        downloads = download_lifecycle.active_download_refs(
+            _registry,
+            canonical_repo_id,
+            with_variant = False,
+        )
+    )
+
+
+async def get_dataset_transport_status_response(repo_id: str) -> dict:
+    """Last transport used, whether partial blobs exist, and whether they
+    support byte-level resume. XET partials show via ``has_partial`` but are not
+    byte-level resumable (see ``models.get_model_transport_status``)."""
+    repo_id = repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        return {"has_partial": False, "last_transport": None, "resumable": False}
+    return {
+        "has_partial": has_active_incomplete_blobs("dataset", repo_id),
+        "last_transport": download_registry.read_active_transport_marker("dataset", repo_id),
+        "resumable": download_registry.is_resumable_partial("dataset", repo_id),
+    }
+
+
+registry = _registry
diff --git a/studio/backend/hub/services/datasets/formatting.py b/studio/backend/hub/services/datasets/formatting.py
new file mode 100644
index 0000000000..8b0ff39f63
--- /dev/null
+++ b/studio/backend/hub/services/datasets/formatting.py
@@ -0,0 +1,527 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Dataset preview, format-check, and mapping-assist services."""
+
+from __future__ import annotations
+
+import base64
+import errno
+import io
+import re
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.datasets import (
+    AiAssistMappingRequest,
+    AiAssistMappingResponse,
+    CheckFormatRequest,
+    CheckFormatResponse,
+)
+from hub.services.datasets.local import (
+    DATA_EXTS,
+    _TABULAR_EXTS,
+    _load_local_preview_slice,
+    _stream_file_preview_slice,
+)
+from hub.utils.dataset_cache import (
+    cached_dataset_candidates as _shared_cached_dataset_candidates,
+    latest_cached_dataset_snapshot as _shared_latest_cached_dataset_snapshot,
+    split_label_matches as _split_label_matches,
+)
+from hub.utils import download_registry
+from hub.utils.dataset_format import check_dataset_format, format_dataset_preview
+from hub.utils.hf_errors import hf_error_status
+from hub.utils.paths import (
+    is_valid_repo_id as _is_valid_repo_id,
+    resolve_dataset_path,
+)
+
+logger = get_logger(__name__)
+
+_BINARY_IMAGE_PREVIEW_MAX_BYTES = 10 * 1024 * 1024
+_IMAGE_PREVIEW_MAX_PIXELS = 16_000_000
+_IMAGE_PREVIEW_THUMBNAIL_SIZE = (512, 512)
+
+
+def _image_pixel_count(image) -> int:
+    width = max(int(getattr(image, "width", 0) or 0), 0)
+    height = max(int(getattr(image, "height", 0) or 0), 0)
+    return width * height
+
+
+def _pil_image_has_transparency(image) -> bool:
+    if "A" in image.getbands():
+        extrema = image.getchannel("A").getextrema()
+        return bool(extrema and extrema[0] < 255)
+    if image.mode == "P":
+        transparency = image.info.get("transparency")
+        if transparency is None:
+            return False
+        if isinstance(transparency, bytes):
+            return any(alpha < 255 for alpha in transparency)
+        return True
+    return False
+
+
+def _serialize_pil_image(image):
+    pixel_count = _image_pixel_count(image)
+    if pixel_count > _IMAGE_PREVIEW_MAX_PIXELS:
+        return (
+            f"<image preview omitted, {image.width}x{image.height} pixels "
+            f"exceeds {_IMAGE_PREVIEW_MAX_PIXELS:,} pixel limit>"
+        )
+
+    preview = image.copy()
+    preview.thumbnail(_IMAGE_PREVIEW_THUMBNAIL_SIZE)
+    buffer = io.BytesIO()
+    if _pil_image_has_transparency(preview):
+        preview.save(buffer, format = "PNG")
+        mime = "image/png"
+    else:
+        preview.convert("RGB").save(buffer, format = "JPEG", quality = 85)
+        mime = "image/jpeg"
+    return {
+        "type": "image",
+        "mime": mime,
+        "width": preview.width,
+        "height": preview.height,
+        "data": base64.b64encode(buffer.getvalue()).decode("ascii"),
+    }
+
+
+def _serialize_binary_value(data):
+    if len(data) > _BINARY_IMAGE_PREVIEW_MAX_BYTES:
+        return (
+            f"<binary data omitted, {len(data)} bytes exceeds "
+            f"{_BINARY_IMAGE_PREVIEW_MAX_BYTES:,} byte preview limit>"
+        )
+
+    try:
+        from PIL import Image as PILImageModule
+        with PILImageModule.open(io.BytesIO(data)) as image:
+            return _serialize_pil_image(image)
+    except Exception:
+        return f"<binary data, {len(data)} bytes>"
+
+
+def _serialize_preview_value(value):
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return _serialize_binary_value(value)
+
+    try:
+        from PIL.Image import Image as PILImage
+        if isinstance(value, PILImage):
+            return _serialize_pil_image(value)
+    except Exception:
+        pass
+
+    if isinstance(value, dict):
+        # Undecoded HF Image/Audio cells are {"bytes": b"...", "path": ...}.
+        raw = value.get("bytes")
+        if isinstance(raw, (bytes, bytearray, memoryview)) and not (
+            value.keys() - {"bytes", "path"}
+        ):
+            return _serialize_binary_value(raw)
+        return {str(key): _serialize_preview_value(item) for key, item in value.items()}
+
+    if isinstance(value, (list, tuple)):
+        return [_serialize_preview_value(item) for item in value]
+
+    return str(value)
+
+
+def _serialize_preview_rows(rows):
+    return [
+        {str(key): _serialize_preview_value(value) for key, value in dict(row).items()}
+        for row in rows
+    ]
+
+
+def _latest_cached_dataset_snapshot(
+    repo_id: str, local_path: Optional[str] = None
+) -> Optional[Path]:
+    return _shared_latest_cached_dataset_snapshot(repo_id, local_path)
+
+
+def _cached_dataset_candidates(
+    snapshot: Path, *, subset: Optional[str], train_split: str
+) -> list[Path]:
+    return _shared_cached_dataset_candidates(
+        snapshot,
+        subset = subset,
+        train_split = train_split,
+        extensions = DATA_EXTS,
+        preferred_extensions = _TABULAR_EXTS,
+    )
+
+
+def _repo_file_label_tokens(path: str) -> set[str]:
+    return {token for token in re.split(r"[^a-z0-9]+", path.lower()) if token}
+
+
+def _repo_file_matches_label(path: str, label: str) -> bool:
+    return label.strip().lower() in _repo_file_label_tokens(path)
+
+
+def _repo_file_matches_split(path: str, split: str) -> bool:
+    return _split_label_matches(path, split)
+
+
+def _select_tier1_repo_file(
+    files: list[str], *, subset: Optional[str], train_split: str
+) -> Optional[str]:
+    data_files = sorted(f for f in files if any(f.lower().endswith(ext) for ext in DATA_EXTS))
+    if not data_files:
+        return None
+    tabular_files = [f for f in data_files if any(f.lower().endswith(ext) for ext in _TABULAR_EXTS)]
+    candidates = tabular_files or data_files
+    if subset:
+        candidates = [f for f in candidates if _repo_file_matches_label(f, subset)]
+        if not candidates:
+            return None
+    candidates = [f for f in candidates if _repo_file_matches_split(f, train_split)]
+    return candidates[0] if candidates else None
+
+
+def _load_cached_hf_preview_slice(request: CheckFormatRequest, preview_size: int):
+    if not _is_valid_repo_id(request.dataset_name):
+        return None
+    snapshot = _latest_cached_dataset_snapshot(
+        request.dataset_name,
+        request.local_path,
+    )
+    if snapshot is None:
+        return None
+    train_split = request.train_split or "train"
+    for candidate in _cached_dataset_candidates(
+        snapshot,
+        subset = request.subset,
+        train_split = train_split,
+    ):
+        try:
+            preview = _stream_file_preview_slice(candidate, preview_size)
+        except Exception as exc:
+            logger.debug("Cached dataset preview failed for %s: %s", candidate, exc)
+            continue
+        if preview is not None:
+            return preview
+    return None
+
+
+def _load_processed_hf_preview_slice(
+    request: CheckFormatRequest,
+    preview_size: int,
+    hf_token: Optional[str] = None,
+):
+    if not _is_valid_repo_id(request.dataset_name):
+        return None
+    try:
+        from datasets import DownloadConfig, load_dataset
+    except Exception:
+        return None
+
+    load_kwargs = {
+        "path": request.dataset_name,
+        "split": request.train_split or "train",
+        "download_config": DownloadConfig(local_files_only = True),
+    }
+    if request.subset:
+        load_kwargs["name"] = request.subset
+    if hf_token:
+        load_kwargs["token"] = hf_token
+
+    dataset = load_dataset(**load_kwargs)
+    total_rows = len(dataset)
+    preview_slice = dataset.select(range(min(preview_size, total_rows)))
+    return preview_slice, total_rows
+
+
+def _load_any_cached_hf_preview_slice(
+    request: CheckFormatRequest,
+    preview_size: int,
+    hf_token: Optional[str] = None,
+):
+    cached_preview = _load_cached_hf_preview_slice(request, preview_size)
+    if cached_preview is not None:
+        return cached_preview
+    try:
+        return _load_processed_hf_preview_slice(request, preview_size, hf_token)
+    except Exception as exc:
+        logger.debug(
+            "Processed dataset cache preview failed for %s: %s",
+            request.dataset_name,
+            exc,
+        )
+        return None
+
+
+def check_format_response(
+    request: CheckFormatRequest, hf_token: Optional[str] = None
+) -> CheckFormatResponse:
+    """
+    Check if a dataset requires manual column mapping.
+
+    HF datasets: tier 1 loads a single requested split/subset file (avoids
+    resolving thousands of files); tier 2 falls back to full streaming. Local
+    files load directly. Plain `def` so FastAPI runs the blocking IO in a
+    thread-pool.
+    """
+    try:
+        from itertools import islice
+
+        PREVIEW_SIZE = 10
+
+        logger.info(f"Checking format for dataset: {request.dataset_name}")
+
+        try:
+            dataset_path = resolve_dataset_path(request.dataset_name)
+        except ValueError as e:
+            # Malformed path (null bytes, '..', outside roots) is a client error:
+            # surface 400 rather than the generic 500 below.
+            raise HTTPException(status_code = 400, detail = str(e)) from e
+        total_rows = None
+
+        if dataset_path.exists():
+            train_split = request.train_split or "train"
+            preview_slice, total_rows = _load_local_preview_slice(
+                dataset_path = dataset_path,
+                train_split = train_split,
+                preview_size = PREVIEW_SIZE,
+            )
+        else:
+            from datasets import Dataset, load_dataset
+
+            # Tier 1: list_repo_files → load only the first data file
+            cached_preview = (
+                _load_any_cached_hf_preview_slice(request, PREVIEW_SIZE, hf_token)
+                if request.prefer_local_cache
+                else None
+            )
+            if cached_preview is not None:
+                preview_slice, total_rows = cached_preview
+            elif request.prefer_local_cache:
+                raise HTTPException(
+                    status_code = 404,
+                    detail = "Dataset is not available in the local cache.",
+                )
+            else:
+                preview_slice = None
+
+                try:
+                    from huggingface_hub import HfApi
+
+                    api = HfApi()
+                    repo_files = api.list_repo_files(
+                        request.dataset_name,
+                        repo_type = "dataset",
+                        token = hf_token or None,
+                    )
+                    train_split = request.train_split or "train"
+                    first_file = _select_tier1_repo_file(
+                        repo_files,
+                        subset = request.subset,
+                        train_split = train_split,
+                    )
+                    if first_file:
+                        logger.info(f"Tier 1: loading single file {first_file}")
+                        load_kwargs = {
+                            "path": request.dataset_name,
+                            "data_files": {train_split: [first_file]},
+                            "split": train_split,
+                            "streaming": True,
+                        }
+                        if hf_token:
+                            load_kwargs["token"] = hf_token
+
+                        streamed_ds = load_dataset(**load_kwargs)
+                        rows = list(islice(streamed_ds, PREVIEW_SIZE))
+                        if rows:
+                            preview_slice = Dataset.from_list(rows)
+                except Exception as e:
+                    logger.warning(
+                        "Tier 1 (single-file) failed: %s",
+                        download_registry.scrub_secrets(str(e), hf_token = hf_token),
+                    )
+
+            if preview_slice is None:
+                # Tier 2: full streaming (resolves all files — slow for large repos)
+                logger.info("Tier 2: falling back to full streaming load_dataset")
+                try:
+                    load_kwargs = {
+                        "path": request.dataset_name,
+                        "split": request.train_split or "train",
+                        "streaming": True,
+                    }
+                    if request.subset:
+                        load_kwargs["name"] = request.subset
+                    if hf_token:
+                        load_kwargs["token"] = hf_token
+
+                    streamed_ds = load_dataset(**load_kwargs)
+
+                    rows = list(islice(streamed_ds, PREVIEW_SIZE))
+                    if not rows:
+                        raise HTTPException(
+                            status_code = 400,
+                            detail = "Dataset appears to be empty or could not be streamed",
+                        )
+
+                    preview_slice = Dataset.from_list(rows)
+                    total_rows = None
+                except Exception:
+                    cached_preview = _load_any_cached_hf_preview_slice(
+                        request,
+                        PREVIEW_SIZE,
+                        hf_token,
+                    )
+                    if cached_preview is None:
+                        raise
+                    preview_slice, total_rows = cached_preview
+
+        result = check_dataset_format(preview_slice, is_vlm = request.is_vlm)
+
+        logger.info(
+            f"Format check result: requires_mapping={result['requires_manual_mapping']}, format={result['detected_format']}, is_image={result.get('is_image', False)}"
+        )
+
+        preview_samples = None
+        if not result["requires_manual_mapping"]:
+            if result.get("suggested_mapping"):
+                # Heuristic-detected: show raw data so columns match the response;
+                # column stripping happens at training time, not preview.
+                preview_samples = _serialize_preview_rows(preview_slice)
+            else:
+                try:
+                    processed = format_dataset_preview(preview_slice)
+                    preview_samples = _serialize_preview_rows(processed)
+                except Exception as e:
+                    logger.warning(f"Processed preview generation failed (non-fatal): {e}")
+                    preview_samples = _serialize_preview_rows(preview_slice)
+        else:
+            preview_samples = _serialize_preview_rows(preview_slice)
+
+        # Collect warnings: from check_dataset_format + URL-based image detection
+        warning = result.get("warning")
+        image_col = result.get("detected_image_column")
+        if image_col and image_col in (result.get("columns") or []):
+            try:
+                sample_val = preview_slice[0][image_col]
+                if isinstance(sample_val, str) and sample_val.startswith(("http://", "https://")):
+                    url_warning = (
+                        "This dataset contains image URLs instead of embedded images. "
+                        "Images will be downloaded during training, which may be slow for large datasets."
+                    )
+                    logger.info(f"URL-based image column detected: {image_col}")
+                    warning = f"{warning} {url_warning}" if warning else url_warning
+            except Exception:
+                pass
+
+        return CheckFormatResponse(
+            requires_manual_mapping = result["requires_manual_mapping"],
+            detected_format = result["detected_format"],
+            columns = result["columns"],
+            is_image = result.get("is_image", False),
+            is_audio = result.get("is_audio", False),
+            multimodal_columns = result.get("multimodal_columns"),
+            suggested_mapping = result.get("suggested_mapping"),
+            detected_image_column = result.get("detected_image_column"),
+            detected_audio_column = result.get("detected_audio_column"),
+            detected_text_column = result.get("detected_text_column"),
+            detected_speaker_column = result.get("detected_speaker_column"),
+            preview_samples = preview_samples,
+            total_rows = total_rows,
+            warning = warning,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        scrubbed = download_registry.scrub_secrets(str(e), hf_token = hf_token)
+        # Missing/gated/bad-token and malformed names are client errors, not 500s.
+        status = hf_error_status(e)
+        if (
+            status is None
+            and isinstance(e, OSError)
+            and getattr(e, "errno", None) == errno.ENAMETOOLONG
+        ):
+            status, scrubbed = 400, "Invalid dataset name"
+        elif status is None and isinstance(e, FileNotFoundError):
+            # datasets raises DatasetNotFoundError (FileNotFoundError) for missing/gated.
+            status = 404
+        elif status is None and isinstance(e, ValueError):
+            status = 400
+        if status is not None:
+            raise HTTPException(status_code = status, detail = scrubbed)
+        logger.error("Error checking dataset format: %s", scrubbed)
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to check dataset format: " + scrubbed,
+        )
+
+
+def ai_assist_mapping_response(
+    request: AiAssistMappingRequest, hf_token: Optional[str] = None
+) -> AiAssistMappingResponse:
+    """
+    Run the LLM-assisted dataset conversion advisor (user-triggered).
+
+    Multi-pass analysis with a 7B helper model: classify dataset type, generate
+    a conversion strategy, then validate it. Falls back to simple column
+    classification if the advisor fails.
+    """
+    try:
+        from hub.utils.llm_assist import llm_conversion_advisor
+
+        truncated = [
+            {col: str(s.get(col, ""))[:200] for col in request.columns} for s in request.samples[:5]
+        ]
+
+        result = llm_conversion_advisor(
+            column_names = request.columns,
+            samples = truncated,
+            dataset_name = request.dataset_name,
+            hf_token = hf_token,
+            model_name = request.model_name,
+            model_type = request.model_type,
+        )
+
+        if result and result.get("success"):
+            return AiAssistMappingResponse(
+                success = True,
+                suggested_mapping = result.get("suggested_mapping"),
+                system_prompt = result.get("system_prompt"),
+                user_template = result.get("user_template"),
+                assistant_template = result.get("assistant_template"),
+                label_mapping = result.get("label_mapping"),
+                dataset_type = result.get("dataset_type"),
+                is_conversational = result.get("is_conversational"),
+                user_notification = result.get("user_notification"),
+                warning = result.get("warning"),
+            )
+
+        return AiAssistMappingResponse(
+            success = False,
+            warning = "AI could not determine column roles. Please assign them manually.",
+        )
+
+    except Exception as e:
+        scrubbed = download_registry.scrub_secrets(str(e), hf_token = hf_token)
+        status = hf_error_status(e)
+        if status is None and isinstance(e, FileNotFoundError):
+            status = 404
+        elif status is None and isinstance(e, ValueError):
+            status = 400
+        if status is not None:
+            raise HTTPException(status_code = status, detail = scrubbed)
+        logger.error("AI assist mapping failed: %s", scrubbed)
+        raise HTTPException(
+            status_code = 500,
+            detail = "AI assist failed: " + scrubbed,
+        )
diff --git a/studio/backend/hub/services/datasets/local.py b/studio/backend/hub/services/datasets/local.py
new file mode 100644
index 0000000000..2d2c7c3a0d
--- /dev/null
+++ b/studio/backend/hub/services/datasets/local.py
@@ -0,0 +1,330 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Local dataset upload and listing services."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from pathlib import Path
+
+from fastapi import HTTPException, UploadFile
+
+from hub.schemas.datasets import (
+    LocalDatasetItem,
+    LocalDatasetsResponse,
+    UploadDatasetResponse,
+)
+from hub.utils.paths import dataset_uploads_root, ensure_dir, recipe_datasets_root
+
+# Tabular formats are preferred over archives for Tier 1 preview: archives
+# (e.g. images.zip) load as ImageFolder with synthetic columns that don't
+# match the real schema.
+_TABULAR_EXTS = (".parquet", ".json", ".jsonl", ".csv", ".tsv", ".arrow")
+_ARCHIVE_EXTS = (".tar", ".tar.gz", ".tgz", ".gz", ".zst", ".zip", ".txt")
+DATA_EXTS = _TABULAR_EXTS + _ARCHIVE_EXTS
+LOCAL_FILE_EXTS = (".json", ".jsonl", ".csv", ".parquet")
+LOCAL_UPLOAD_EXTS = {".csv", ".json", ".jsonl", ".parquet"}
+LOCAL_UPLOAD_CHUNK_BYTES = 1024 * 1024
+LOCAL_UPLOAD_MAX_BYTES = 500 * 1024 * 1024
+LOCAL_DATASETS_ROOT = recipe_datasets_root()
+DATASET_UPLOAD_DIR = dataset_uploads_root()
+
+
+def _safe_read_metadata(path: Path) -> dict | None:
+    try:
+        payload = json.loads(path.read_text(encoding = "utf-8"))
+    except (OSError, ValueError, TypeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    return payload
+
+
+def _safe_read_rows_from_metadata(payload: dict | None) -> int | None:
+    if not payload:
+        return None
+    for key in ("actual_num_records", "target_num_records"):
+        value = payload.get(key)
+        if isinstance(value, int):
+            return value
+    return None
+
+
+def _safe_read_metadata_summary(payload: dict | None) -> dict | None:
+    if not payload:
+        return None
+
+    actual_num_records = (
+        payload.get("actual_num_records")
+        if isinstance(payload.get("actual_num_records"), int)
+        else None
+    )
+    target_num_records = (
+        payload.get("target_num_records")
+        if isinstance(payload.get("target_num_records"), int)
+        else actual_num_records
+    )
+
+    columns: list[str] | None = None
+    schema = payload.get("schema")
+    if isinstance(schema, dict):
+        columns = [str(key) for key in schema.keys()]
+    if not columns:
+        stats = payload.get("column_statistics")
+        if isinstance(stats, list):
+            derived = [
+                str(item.get("column_name"))
+                for item in stats
+                if isinstance(item, dict) and item.get("column_name")
+            ]
+            columns = derived or None
+
+    parquet_files_count = None
+    file_paths = payload.get("file_paths")
+    if isinstance(file_paths, dict):
+        parquet_files = file_paths.get("parquet-files")
+        if isinstance(parquet_files, list):
+            parquet_files_count = len(parquet_files)
+
+    total_num_batches = (
+        payload.get("total_num_batches")
+        if isinstance(payload.get("total_num_batches"), int)
+        else parquet_files_count
+    )
+    num_completed_batches = (
+        payload.get("num_completed_batches")
+        if isinstance(payload.get("num_completed_batches"), int)
+        else total_num_batches
+    )
+
+    return {
+        "actual_num_records": actual_num_records,
+        "target_num_records": target_num_records,
+        "total_num_batches": total_num_batches,
+        "num_completed_batches": num_completed_batches,
+        "columns": columns,
+    }
+
+
+def _safe_mtime(path: Path) -> float | None:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return None
+
+
+def _display_uploaded_dataset_name(path: Path) -> str:
+    stem = path.stem
+    prefix, sep, rest = stem.partition("_")
+    if sep and len(prefix) == 32 and all(c in "0123456789abcdef" for c in prefix):
+        return f"{rest}{path.suffix}"
+    return path.name
+
+
+def _build_recipe_dataset_items() -> list[LocalDatasetItem]:
+    if not LOCAL_DATASETS_ROOT.exists():
+        return []
+
+    items: list[LocalDatasetItem] = []
+    for entry in LOCAL_DATASETS_ROOT.iterdir():
+        if not entry.is_dir() or not entry.name.startswith("recipe_"):
+            continue
+        parquet_dir = entry / "parquet-files"
+        if not parquet_dir.exists() or not any(parquet_dir.glob("*.parquet")):
+            continue
+
+        rows = None
+        metadata_summary = None
+        metadata_path = entry / "metadata.json"
+        if metadata_path.exists():
+            metadata_payload = _safe_read_metadata(metadata_path)
+            rows = _safe_read_rows_from_metadata(metadata_payload)
+            metadata_summary = _safe_read_metadata_summary(metadata_payload)
+
+        items.append(
+            LocalDatasetItem(
+                id = entry.name,
+                label = entry.name,
+                path = str(parquet_dir.resolve()),
+                source = "recipe",
+                rows = rows,
+                updated_at = _safe_mtime(entry),
+                metadata = metadata_summary,
+            )
+        )
+
+    return items
+
+
+def _build_uploaded_dataset_items() -> list[LocalDatasetItem]:
+    if not DATASET_UPLOAD_DIR.exists():
+        return []
+
+    items: list[LocalDatasetItem] = []
+    for path in DATASET_UPLOAD_DIR.iterdir():
+        if not path.is_file() or path.suffix.lower() not in LOCAL_UPLOAD_EXTS:
+            continue
+        try:
+            if path.stat().st_size == 0:
+                continue
+        except OSError:
+            continue
+        label = _display_uploaded_dataset_name(path)
+        items.append(
+            LocalDatasetItem(
+                id = path.name,
+                label = label,
+                path = str(path.resolve()),
+                source = "upload",
+                updated_at = _safe_mtime(path),
+            )
+        )
+    return items
+
+
+def _build_local_dataset_items() -> list[LocalDatasetItem]:
+    items = _build_recipe_dataset_items() + _build_uploaded_dataset_items()
+    items.sort(key = lambda item: item.updated_at or 0, reverse = True)
+    return items
+
+
+def _stream_file_preview_slice(path: Path, preview_size: int):
+    """Stream the first ``preview_size`` rows so a large file is never fully parsed into Arrow; returns ``(Dataset, None)`` or ``None`` if empty/unsupported."""
+    from itertools import islice
+
+    from datasets import Dataset, load_dataset
+
+    name = path.name.lower()
+    if name.endswith((".json", ".jsonl")):
+        loader = "json"
+    elif name.endswith((".csv", ".tsv")):
+        loader = "csv"
+    elif name.endswith(".parquet"):
+        loader = "parquet"
+    elif name.endswith(".arrow"):
+        loader = "arrow"
+    elif name.endswith(".txt"):
+        loader = "text"
+    else:
+        return None
+
+    streamed = load_dataset(
+        loader,
+        data_files = str(path),
+        split = "train",
+        streaming = True,
+    )
+    rows = list(islice(streamed, preview_size))
+    if not rows:
+        return None
+    return Dataset.from_list(rows), None
+
+
+def _load_local_preview_slice(*, dataset_path: Path, train_split: str, preview_size: int):
+    from datasets import load_dataset
+
+    if dataset_path.is_dir():
+        parquet_dir = (
+            dataset_path / "parquet-files"
+            if (dataset_path / "parquet-files").exists()
+            else dataset_path
+        )
+        parquet_files = sorted(parquet_dir.glob("*.parquet"))
+        if parquet_files:
+            dataset = load_dataset(
+                "parquet",
+                data_files = [str(path) for path in parquet_files],
+                split = train_split,
+            )
+            total_rows = len(dataset)
+            preview_slice = dataset.select(range(min(preview_size, total_rows)))
+            return preview_slice, total_rows
+
+        candidate_files: list[Path] = []
+        for ext in LOCAL_FILE_EXTS:
+            candidate_files.extend(sorted(dataset_path.glob(f"*{ext}")))
+        if not candidate_files:
+            raise HTTPException(
+                status_code = 400,
+                detail = "Unsupported local dataset directory (expected parquet/json/jsonl/csv files)",
+            )
+        dataset_path = candidate_files[0]
+
+    suffix = dataset_path.suffix.lower()
+    # Parquet/Arrow give a cheap exact total_rows via len()+select; JSON/CSV
+    # carry no such metadata, so stream them and report total_rows=None.
+    if suffix == ".parquet":
+        dataset = load_dataset("parquet", data_files = str(dataset_path), split = train_split)
+        total_rows = len(dataset)
+        preview_slice = dataset.select(range(min(preview_size, total_rows)))
+        return preview_slice, total_rows
+
+    if suffix in (".json", ".jsonl", ".csv"):
+        preview = _stream_file_preview_slice(dataset_path, preview_size)
+        if preview is None:
+            raise HTTPException(
+                status_code = 400,
+                detail = "Dataset appears to be empty or could not be read",
+            )
+        return preview
+
+    raise HTTPException(status_code = 400, detail = f"Unsupported file format: {dataset_path.suffix}")
+
+
+def _sanitize_filename(filename: str) -> str:
+    name = Path(filename).name.strip().replace("\x00", "")
+    if not name:
+        return "dataset_upload"
+    return name
+
+
+def _upload_too_large(size_bytes: int) -> HTTPException:
+    return HTTPException(
+        status_code = 413,
+        detail = (f"Upload is too large " f"({size_bytes:,} bytes; max {LOCAL_UPLOAD_MAX_BYTES:,})."),
+    )
+
+
+async def upload_dataset_response(file: UploadFile) -> UploadDatasetResponse:
+    filename = _sanitize_filename(file.filename or "dataset_upload")
+    ext = Path(filename).suffix.lower()
+    if ext not in LOCAL_UPLOAD_EXTS:
+        allowed = ", ".join(sorted(LOCAL_UPLOAD_EXTS))
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Unsupported file type: {ext}. Allowed: {allowed}",
+        )
+
+    declared_size = getattr(file, "size", None)
+    if isinstance(declared_size, int) and declared_size > LOCAL_UPLOAD_MAX_BYTES:
+        raise _upload_too_large(declared_size)
+
+    ensure_dir(DATASET_UPLOAD_DIR)
+    stem = Path(filename).stem
+    stored_name = f"{uuid.uuid4().hex}_{stem}{ext}"
+    stored_path = DATASET_UPLOAD_DIR / stored_name
+
+    written = 0
+    try:
+        with open(stored_path, "wb") as f:
+            while chunk := await file.read(LOCAL_UPLOAD_CHUNK_BYTES):
+                written += len(chunk)
+                if written > LOCAL_UPLOAD_MAX_BYTES:
+                    raise _upload_too_large(written)
+                await asyncio.to_thread(f.write, chunk)
+    except Exception:
+        stored_path.unlink(missing_ok = True)
+        raise
+
+    if written == 0:
+        stored_path.unlink(missing_ok = True)
+        raise HTTPException(status_code = 400, detail = "Empty upload payload")
+
+    return UploadDatasetResponse(filename = filename, stored_path = str(stored_path))
+
+
+def list_local_datasets_response() -> LocalDatasetsResponse:
+    return LocalDatasetsResponse(datasets = _build_local_dataset_items())
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
new file mode 100644
index 0000000000..8256b00252
--- /dev/null
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -0,0 +1,449 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from fastapi import HTTPException
+
+from hub.schemas.downloads import ActiveDownload, DownloadJobState
+from hub.utils import download_manifest
+from hub.utils import download_registry
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.hf_cache_state import EXIT_CANCELLED
+from hub.utils.state_dir import RepoType
+
+
+def backend_dir() -> Path:
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def resolve_transport(use_xet: bool) -> str:
+    transport = download_registry.TRANSPORT_XET if use_xet else download_registry.TRANSPORT_HTTP
+    unavailable_reason = download_registry.download_transport_unavailable_reason(transport)
+    if unavailable_reason is not None:
+        raise HTTPException(status_code = 400, detail = unavailable_reason)
+    return transport
+
+
+def spawn_worker(
+    args: list[str],
+    hf_token: Optional[str],
+    *,
+    use_xet: bool,
+    protected_blob_hashes: Optional[frozenset[str]] = None,
+) -> subprocess.Popen:
+    """Spawn the download worker.
+
+    XET and ``hf_transfer`` write chunks out of order, so their partials can't
+    resume under a sequential writer; the HTTP path stays sequential so
+    SIGKILL -> resume is byte-identical. ``protected_blob_hashes`` are blobs a
+    concurrent same-repo peer is writing, excluded from the cache-prep purge so a
+    shared ``.incomplete`` (e.g. bundled mmproj) is never deleted.
+    """
+    cwd = backend_dir()
+    mode = download_registry.TRANSPORT_XET if use_xet else download_registry.TRANSPORT_HTTP
+    env = os.environ.copy()
+    if protected_blob_hashes:
+        env["UNSLOTH_PROTECTED_BLOB_HASHES"] = ",".join(sorted(protected_blob_hashes))
+    else:
+        env.pop("UNSLOTH_PROTECTED_BLOB_HASHES", None)
+    env["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+    env["HF_HUB_DISABLE_TELEMETRY"] = "1"
+    env["HF_HUB_DISABLE_XET"] = "0" if use_xet else "1"
+    env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0" if hf_token else "1"
+    # hf_transfer's parallel Range chunks can leave sparse partials even in
+    # "http" mode; disable so the worker's writer is always sequential.
+    env["HF_HUB_ENABLE_HF_TRANSFER"] = "0"
+    for token_key in (
+        "HF_TOKEN",
+        "HF_HUB_TOKEN",
+        "HUGGING_FACE_HUB_TOKEN",
+        "HUGGINGFACE_HUB_TOKEN",
+        "HUGGINGFACEHUB_API_TOKEN",
+    ):
+        env.pop(token_key, None)
+    if hf_token:
+        env["HF_TOKEN"] = hf_token
+    existing_path = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = f"{cwd}{os.pathsep}{existing_path}" if existing_path else str(cwd)
+    return subprocess.Popen(
+        [
+            sys.executable,
+            "-m",
+            "hub.workers.hf_download",
+            *args,
+            "--parent-pid",
+            str(os.getpid()),
+            "--transport",
+            mode,
+        ],
+        env = env,
+        cwd = str(cwd),
+        stdout = subprocess.DEVNULL,
+        stderr = subprocess.PIPE,
+        start_new_session = sys.platform != "win32",
+    )
+
+
+def drain_stderr_excerpt(stream, edge_bytes: int = 500) -> bytes:
+    """Drain a worker's stderr to EOF, retaining the first and last bytes.
+
+    Incremental reads keep the pipe from filling while bounding memory; long
+    messages keep both ends since stderr prefixes often name the failing repo."""
+    if stream is None:
+        return b""
+    edge_bytes = max(1, edge_bytes)
+    max_bytes = edge_bytes * 2
+    full = bytearray()
+    head = bytearray()
+    tail = bytearray()
+    truncated = False
+    for chunk in iter(lambda: stream.read(4096), b""):
+        if not truncated:
+            full.extend(chunk)
+            if len(full) <= max_bytes:
+                continue
+            truncated = True
+            head.extend(full[:edge_bytes])
+            tail.extend(full[-edge_bytes:])
+            full.clear()
+            continue
+        tail.extend(chunk)
+        if len(tail) > edge_bytes:
+            del tail[:-edge_bytes]
+    if not truncated:
+        return bytes(full)
+    return bytes(head + b"\n...[stderr truncated]...\n" + tail)
+
+
+def _cancellation_return_codes() -> frozenset[int]:
+    """Returncodes for intentional cancellation only (SIGKILL/SIGTERM/SIGINT); crash signals stay errors, and ``getattr`` tolerates Windows where these signals are absent."""
+    codes: set[int] = set()
+    for name in ("SIGKILL", "SIGTERM", "SIGINT"):
+        sig = getattr(signal, name, None)
+        if sig is not None:
+            codes.add(-int(sig))
+    return frozenset(codes)
+
+
+_CANCELLATION_RETURN_CODES = _cancellation_return_codes()
+
+
+def _sigpipe_return_codes() -> frozenset[int]:
+    sig = getattr(signal, "SIGPIPE", None)
+    if sig is None:
+        return frozenset()
+    value = int(sig)
+    return frozenset({-value, 128 + value})
+
+
+_SIGPIPE_RETURN_CODES = _sigpipe_return_codes()
+
+
+def classify_exit(rc: int, *, cancel_requested: bool = False) -> str:
+    """Map a worker process exit code to a job state.
+
+    - rc == 0: clean completion.
+    - rc == EXIT_CANCELLED (130): the worker trapped a stop signal and exited
+      cleanly with a resumable partial. In-app cancel uses untrappable SIGKILL
+      and the OOM killer never produces 130, so 130 is always a resumable cancel.
+    - rc killed by SIGKILL/SIGTERM/SIGINT: a cancel only when *we* asked for it.
+      The OOM killer also sends SIGKILL, so an unrequested kill surfaces as error.
+    - rc killed by SIGPIPE (or 128+SIGPIPE): parent pipe is gone; treated as
+      cancelled.
+    - any other non-zero rc (incl. crash signals): worker errored out.
+
+    Windows has no POSIX signal exit encoding, so a user cancel can't be told from
+    an error by code alone; there ``cancel_requested`` decides.
+    """
+    if rc == 0:
+        return "complete"
+    if rc == EXIT_CANCELLED:
+        return "cancelled"
+    if rc in _SIGPIPE_RETURN_CODES:
+        return "cancelled"
+    if rc in _CANCELLATION_RETURN_CODES:
+        return "cancelled" if cancel_requested else "error"
+    if cancel_requested and sys.platform == "win32":
+        return "cancelled"
+    return "error"
+
+
+def finalize_worker_exit(
+    registry: download_registry.DownloadRegistry,
+    key: str,
+    proc: subprocess.Popen,
+    *,
+    hf_token: Optional[str],
+    label: str,
+    log_prefix: str,
+    logger,
+    repo_type: Optional[RepoType] = None,
+    repo_id: Optional[str] = None,
+    transport: Optional[str] = None,
+) -> None:
+    """Block until *proc* exits, then record the job's terminal state in
+    *registry*. Drains and scrubs stderr first, then classifies the exit code.
+    A no-op when the process was already dropped (e.g. superseded).
+
+    No stall watchdog: huggingface_hub already times out chunk reads and raises
+    a resumable error on a dead connection, so the worker's exit code is the
+    single source of truth."""
+    stderr_data = drain_stderr_excerpt(proc.stderr)
+    rc = proc.wait()
+    cancel_requested = registry.cancel_requested(key)
+    if not registry.drop_process(key, proc):
+        return
+    stderr_text = download_registry.scrub_secrets(
+        (stderr_data or b"").decode("utf-8", "replace").strip(),
+        hf_token = hf_token,
+    )
+    state = classify_exit(rc, cancel_requested = cancel_requested)
+    if state == "complete":
+        registry.set_job(key, "complete")
+        if stderr_text:
+            if download_manifest.MANIFEST_DEGRADED_MARKER in stderr_text:
+                logger.warning(
+                    f"{log_prefix} complete with degraded diagnostics for "
+                    f"{label}: {stderr_text}"
+                )
+            else:
+                logger.info(f"{log_prefix} worker diagnostics for {label}: {stderr_text}")
+        logger.info(f"{log_prefix} complete: {label}")
+        # Defensive cleanup: the canonical clear is at download-start; this
+        # catches the rare case where that failed but the download succeeded.
+        if repo_type and repo_id:
+            try:
+                download_manifest.clear_cancel_marker(
+                    repo_type,
+                    repo_id,
+                    download_registry.variant_from_key(key),
+                )
+            except Exception as exc:
+                logger.debug(f"clear_cancel_marker failed for {repo_id} (rc=0): {exc}")
+    elif state == "cancelled":
+        # Read metadata before the terminal set_job so a concurrent eviction
+        # can't drop it; the job key is the fallback variant label.
+        metadata = registry.get_job_metadata(key)
+        registry.set_job(key, "cancelled")
+        logger.info(f"{log_prefix} cancelled: {label} (rc={rc})")
+        download_registry.persist_cancel_marker(
+            repo_type,
+            repo_id,
+            metadata.variant
+            if metadata is not None and metadata.variant
+            else download_registry.variant_from_key(key),
+            transport,
+            logger = logger,
+        )
+    else:
+        registry.set_job(
+            key,
+            "error",
+            stderr_text or f"worker exited with code {rc}",
+        )
+        logger.error(
+            f"{log_prefix} failed for {label} (rc={rc}): {stderr_text}",
+        )
+
+
+def kill_and_reap_process(
+    proc: subprocess.Popen,
+    *,
+    label: str,
+    logger,
+    timeout: float = 10.0,
+) -> None:
+    try:
+        proc.kill()
+    except ProcessLookupError:
+        pass
+    except Exception as exc:
+        logger.warning(f"Cancel SIGKILL for {label} failed: {exc}")
+    try:
+        proc.wait(timeout = timeout)
+    except subprocess.TimeoutExpired:
+        logger.warning(f"Cancelled worker for {label} did not exit after SIGKILL")
+    except Exception:
+        pass
+
+
+def register_worker(
+    registry: download_registry.DownloadRegistry,
+    key: str,
+    proc: subprocess.Popen,
+    *,
+    hf_token: Optional[str],
+    label: str,
+    log_prefix: str,
+    logger,
+    repo_type: RepoType,
+    repo_id: str,
+    transport: str,
+    watch_name: str,
+) -> bool:
+    if not registry.register_process(key, proc):
+        kill_and_reap_process(proc, label = label, logger = logger)
+        return False
+
+    worker_token = hf_token
+
+    def _watch() -> None:
+        finalize_worker_exit(
+            registry,
+            key,
+            proc,
+            hf_token = worker_token,
+            label = label,
+            log_prefix = log_prefix,
+            logger = logger,
+            repo_type = repo_type,
+            repo_id = repo_id,
+            transport = transport,
+        )
+        if registry.get_job(key).state in ("error", "cancelled"):
+            download_registry.purge_empty_marker_dir(
+                repo_type,
+                repo_id,
+                download_registry.variant_from_key(key),
+            )
+        hf_cache_scan.invalidate_hf_cache_scans()
+
+    threading.Thread(target = _watch, name = watch_name, daemon = True).start()
+    return True
+
+
+def launch_worker(
+    registry: download_registry.DownloadRegistry,
+    key: str,
+    *,
+    spawn: Callable[[], subprocess.Popen],
+    hf_token: Optional[str],
+    label: str,
+    log_prefix: str,
+    logger,
+    repo_type: RepoType,
+    repo_id: str,
+    transport: str,
+    watch_name: str,
+) -> str:
+    try:
+        proc = spawn()
+    except Exception as e:
+        scrubbed = download_registry.scrub_secrets(str(e), hf_token = hf_token)
+        logger.error(
+            f"Failed to spawn {log_prefix.lower()} worker for {label}: {scrubbed}",
+            exc_info = True,
+        )
+        registry.set_job(key, "error", scrubbed)
+        raise HTTPException(
+            status_code = 500,
+            detail = f"Failed to start {log_prefix.lower()}: {scrubbed}",
+        ) from e
+    register_worker(
+        registry,
+        key,
+        proc,
+        hf_token = hf_token,
+        label = label,
+        log_prefix = log_prefix,
+        logger = logger,
+        repo_type = repo_type,
+        repo_id = repo_id,
+        transport = transport,
+        watch_name = watch_name,
+    )
+    return registry.get_job(key).state
+
+
+def cancel_worker(
+    registry: download_registry.DownloadRegistry,
+    key: str,
+    *,
+    generation: Optional[int],
+    label: str,
+    logger,
+) -> str:
+    proc = registry.get_process(key)
+    # No worker process yet: arm a pending cancel so register_process kills it on
+    # arrival during the claim-to-register window.
+    if proc is None:
+        if registry.mark_pending_cancel(key, generation):
+            return "cancelling"
+        return registry.get_job(key).state
+    # Worker already exited; let its watcher classify the real return code.
+    # Arming a pending cancel here could mislabel a genuine failure as a cancel.
+    if proc.poll() is not None:
+        return registry.get_job(key).state
+
+    if not registry.request_cancel(key, proc, generation):
+        return registry.get_job(key).state
+    # No eager marker: finalize_worker_exit writes it on a "cancelled" exit.
+    # Persisting before the kill races a clean completion and strands a stale marker.
+    try:
+        proc.kill()
+    except ProcessLookupError:
+        pass
+    except Exception as e:
+        logger.warning(f"Cancel SIGKILL for {label} failed: {e}")
+
+    return "cancelling"
+
+
+def idle_status(
+    registry: download_registry.DownloadRegistry,
+    key: str,
+    *,
+    repo_type: RepoType,
+    repo_id: Optional[str],
+    variant: Optional[str],
+) -> tuple[DownloadJobState, Optional[str], int]:
+    state = registry.get_job(key)
+    generation = registry.current_generation(key)
+    if (
+        state.state == "idle"
+        and repo_id
+        and download_manifest.has_cancel_marker(
+            repo_type,
+            repo_id,
+            variant,
+        )
+    ):
+        return ("cancelled", None, generation)
+    return (state.state, state.error, generation)
+
+
+def active_download_refs(
+    registry: download_registry.DownloadRegistry, repo_id: Optional[str], *, with_variant: bool
+) -> list[ActiveDownload]:
+    downloads: list[ActiveDownload] = []
+    for ref in registry.active_job_refs(repo_id):
+        metadata = ref.metadata
+        if with_variant:
+            ref_repo_id = metadata.repo_id if metadata is not None else ref.key.split("::", 1)[0]
+            if metadata is not None:
+                variant = metadata.variant
+            else:
+                _repo, sep, raw_variant = ref.key.partition("::")
+                variant = raw_variant if sep and raw_variant else None
+        else:
+            ref_repo_id = metadata.repo_id if metadata is not None else ref.key
+            variant = None
+        downloads.append(
+            ActiveDownload(
+                repo_id = ref_repo_id,
+                variant = variant,
+                transport = metadata.transport if metadata is not None else None,
+                state = ref.state,
+                generation = ref.generation,
+            )
+        )
+    return downloads
diff --git a/studio/backend/hub/services/models/__init__.py b/studio/backend/hub/services/models/__init__.py
new file mode 100644
index 0000000000..707a7c633a
--- /dev/null
+++ b/studio/backend/hub/services/models/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Model service layer."""
diff --git a/studio/backend/hub/services/models/cache_inventory.py b/studio/backend/hub/services/models/cache_inventory.py
new file mode 100644
index 0000000000..a961a6ae9d
--- /dev/null
+++ b/studio/backend/hub/services/models/cache_inventory.py
@@ -0,0 +1,461 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Cached model inventory."""
+
+from __future__ import annotations
+
+import json
+import asyncio
+import threading
+import time
+from collections import OrderedDict
+from pathlib import Path
+from typing import NamedTuple, Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.inventory import ModelFormat
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils import download_registry
+from hub.utils.snapshot_filters import (
+    snapshot_download_blob_hashes,
+    snapshot_download_size,
+)
+from hub.services.models.common import (
+    _capabilities_for_format,
+    _classify_non_gguf_model_format,
+    _gguf_variant_state_summary,
+    _is_adapter_weight_name,
+    _is_checkpoint_weight_name,
+    _is_gguf_filename,
+    _is_main_gguf_filename,
+    _is_transformers_safetensors_weight_name,
+    _local_inventory_id,
+    _prefer_complete_larger,
+    _runtime_for_format,
+)
+
+logger = get_logger(__name__)
+
+_repo_size_cache: "OrderedDict[tuple[str, str], tuple[int, frozenset[str], float]]" = OrderedDict()
+_repo_size_neg_cache: "OrderedDict[tuple[str, str], float]" = OrderedDict()
+_REPO_SIZE_CACHE_MAX = 256
+_REPO_SIZE_POS_TTL = 60.0
+_REPO_SIZE_NEG_TTL = 60.0
+_MODEL_METADATA_TIMEOUT_SECONDS = 5.0
+_repo_size_cache_lock = threading.Lock()
+
+
+def get_repo_snapshot_metadata_cached(
+    repo_id: str, hf_token: Optional[str] = None
+) -> tuple[int, frozenset[str]]:
+    token_fp = hf_cache_scan.token_fingerprint(hf_token)
+    cache_key = (repo_id, token_fp)
+    with _repo_size_cache_lock:
+        cached = _repo_size_cache.get(cache_key)
+        if cached is not None:
+            total, blob_hashes, ts = cached
+            if (time.monotonic() - ts) < _REPO_SIZE_POS_TTL:
+                _repo_size_cache.move_to_end(cache_key)
+                return total, blob_hashes
+            del _repo_size_cache[cache_key]
+        neg_ts = _repo_size_neg_cache.get(cache_key)
+        if neg_ts is not None and (time.monotonic() - neg_ts) < _REPO_SIZE_NEG_TTL:
+            return 0, frozenset()
+    try:
+        from huggingface_hub import HfApi
+
+        info = HfApi(token = hf_token).model_info(
+            repo_id,
+            files_metadata = True,
+            timeout = _MODEL_METADATA_TIMEOUT_SECONDS,
+        )
+        total = snapshot_download_size(info.siblings)
+        blob_hashes = snapshot_download_blob_hashes(info.siblings)
+    except Exception as e:
+        logger.warning(
+            "Failed to get repo size for %s: %s",
+            repo_id,
+            download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
+        with _repo_size_cache_lock:
+            _repo_size_neg_cache[cache_key] = time.monotonic()
+            _repo_size_neg_cache.move_to_end(cache_key)
+            while len(_repo_size_neg_cache) > _REPO_SIZE_CACHE_MAX:
+                _repo_size_neg_cache.popitem(last = False)
+        return 0, frozenset()
+    with _repo_size_cache_lock:
+        _repo_size_cache[cache_key] = (total, blob_hashes, time.monotonic())
+        _repo_size_cache.move_to_end(cache_key)
+        _repo_size_neg_cache.pop(cache_key, None)
+        while len(_repo_size_cache) > _REPO_SIZE_CACHE_MAX:
+            _repo_size_cache.popitem(last = False)
+    return total, blob_hashes
+
+
+def all_hf_cache_scans():
+    return hf_cache_scan.all_hf_cache_scans()
+
+
+def _repo_gguf_size_bytes(repo_info) -> int:
+    """Sum primary GGUF blob sizes across revisions, deduped by blob path (HF hardlinks shared blobs); mmproj is excluded so a vision-adapter-only repo isn't classed as GGUF."""
+    unique_blobs: dict[str, int] = {}
+    for revision in repo_info.revisions:
+        rev_id = getattr(revision, "commit_hash", None) or str(id(revision))
+        for f in revision.files:
+            if _is_main_gguf_filename(f.file_name):
+                blob_path = getattr(f, "blob_path", None)
+                size = f.size_on_disk or 0
+                if blob_path:
+                    unique_blobs[str(blob_path)] = size
+                else:
+                    unique_blobs[f"{rev_id}:{f.file_name}"] = size
+    return sum(unique_blobs.values())
+
+
+def _repo_has_gguf_files(repo_info) -> bool:
+    return _repo_gguf_size_bytes(repo_info) > 0
+
+
+def _prefer_cache_row(candidate: dict, existing: Optional[dict]) -> bool:
+    if existing is None:
+        return True
+    return _prefer_complete_larger(
+        bool(candidate.get("partial")),
+        int(candidate.get("size_bytes") or 0),
+        bool(existing.get("partial")),
+        int(existing.get("size_bytes") or 0),
+    )
+
+
+def _cache_inventory_fields(
+    repo_id: str,
+    model_format: ModelFormat,
+    *,
+    partial: bool = False,
+    requires_variant: bool = False,
+) -> dict:
+    return {
+        "inventory_id": _local_inventory_id("cache", model_format, repo_id),
+        "load_id": repo_id,
+        "model_format": model_format,
+        "runtime": _runtime_for_format(model_format),
+        "format_variant": None,
+        "capabilities": _capabilities_for_format(
+            model_format,
+            "hf_cache",
+            partial = partial,
+            requires_variant = requires_variant,
+        ).model_dump(),
+    }
+
+
+def invalidate_hf_cache_scans() -> None:
+    hf_cache_scan.invalidate_hf_cache_scans()
+
+
+def _scan_cached_gguf() -> list[dict]:
+    """Synchronous HF-cache disk walk for GGUF repos; runs in a worker thread."""
+    cache_scans = all_hf_cache_scans()
+
+    seen_lower: dict[str, dict] = {}
+    for hf_cache in cache_scans:
+        for repo_info in hf_cache.repos:
+            try:
+                if str(repo_info.repo_type) != "model":
+                    continue
+                repo_id = repo_info.repo_id
+                total_size = _repo_gguf_size_bytes(repo_info)
+                has_variant_state, variant_state_size = _gguf_variant_state_summary(repo_id)
+                if total_size == 0 and not has_variant_state:
+                    continue
+                partial = hf_cache_scan.is_gguf_repo_partial(
+                    repo_id,
+                    Path(repo_info.repo_path),
+                )
+                if total_size == 0 and not partial:
+                    continue
+                key = repo_id.lower()
+                existing = seen_lower.get(key)
+                row = {
+                    "repo_id": repo_id,
+                    "size_bytes": max(total_size, variant_state_size),
+                    "cache_path": str(repo_info.repo_path),
+                    "partial": partial,
+                    # GGUF row-level transport is ambiguous (variants may differ);
+                    # per-variant detail lives on GgufVariantDetail.
+                    "partial_transport": None,
+                }
+                row.update(
+                    _cache_inventory_fields(
+                        repo_id,
+                        "gguf",
+                        partial = bool(row["partial"]),
+                        requires_variant = True,
+                    )
+                )
+                if _prefer_cache_row(row, existing):
+                    seen_lower[key] = row
+            except Exception as e:
+                repo_label = getattr(repo_info, "repo_id", "<unknown>")
+                logger.warning(f"Skipping cached GGUF repo {repo_label}: {e}")
+                continue
+    return sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+
+
+async def list_cached_gguf_response(hf_token: Optional[str] = None):
+    """List GGUF repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
+    try:
+        cached = await asyncio.to_thread(_scan_cached_gguf)
+        return {"cached": cached}
+    except Exception as e:
+        logger.error(
+            "Error listing cached GGUF repos: %s",
+            download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to read the local model cache.",
+        ) from e
+
+
+class _CachedNonGgufPayload(NamedTuple):
+    size_bytes: int
+    has_runnable_weights: bool
+    model_format: ModelFormat
+
+
+def _repo_non_gguf_model_payload(repo_info) -> _CachedNonGgufPayload:
+    all_weight_blobs: dict[str, int] = {}
+    adapter_blobs: dict[str, int] = {}
+    safetensors_blobs: dict[str, int] = {}
+    checkpoint_blobs: dict[str, int] = {}
+    has_config = False
+    has_adapter_config = False
+    has_adapter_weights = False
+    has_safetensors = False
+    has_transformers_safetensors = False
+    has_checkpoint = False
+
+    def _record_blob(target: dict[str, int], file_obj, rev_id: str, file_name: str) -> None:
+        blob_path = getattr(file_obj, "blob_path", None)
+        size = int(file_obj.size_on_disk or 0)
+        key = str(blob_path) if blob_path else f"{rev_id}:{file_name}"
+        target[key] = size
+        all_weight_blobs[key] = size
+
+    for revision in repo_info.revisions:
+        rev_id = getattr(revision, "commit_hash", None) or str(id(revision))
+        for f in revision.files:
+            file_name = str(f.file_name)
+            lower = file_name.lower()
+            name = lower.replace("\\", "/").rsplit("/", 1)[-1]
+            if _is_gguf_filename(lower):
+                continue
+            if name == "config.json":
+                has_config = True
+                continue
+            if name == "adapter_config.json":
+                has_adapter_config = True
+                continue
+            is_adapter = _is_adapter_weight_name(name)
+            is_safetensors = name.endswith(".safetensors") and not is_adapter
+            is_checkpoint = _is_checkpoint_weight_name(name)
+            if is_adapter:
+                has_adapter_weights = True
+                _record_blob(adapter_blobs, f, rev_id, file_name)
+            if is_safetensors:
+                has_safetensors = True
+                if _is_transformers_safetensors_weight_name(name):
+                    has_transformers_safetensors = True
+                _record_blob(safetensors_blobs, f, rev_id, file_name)
+            if is_checkpoint:
+                has_checkpoint = True
+                _record_blob(checkpoint_blobs, f, rev_id, file_name)
+
+    model_format = (
+        _classify_non_gguf_model_format(
+            has_config = has_config,
+            has_adapter_config = has_adapter_config,
+            has_adapter_weights = has_adapter_weights,
+            has_safetensors = has_safetensors,
+            has_transformers_safetensors = has_transformers_safetensors,
+            has_checkpoint_weights = has_checkpoint,
+            trusted_hf_cache_repo = True,
+        )
+        or "unknown"
+    )
+    if model_format == "adapter":
+        size_bytes = sum(adapter_blobs.values())
+    elif model_format == "safetensors":
+        size_bytes = sum(safetensors_blobs.values())
+    elif model_format == "checkpoint":
+        size_bytes = sum(checkpoint_blobs.values())
+    else:
+        size_bytes = sum(all_weight_blobs.values())
+
+    return _CachedNonGgufPayload(
+        size_bytes = size_bytes,
+        has_runnable_weights = model_format != "unknown",
+        model_format = model_format,
+    )
+
+
+def _cached_model_snapshot_path(repo_path: Path) -> Optional[Path]:
+    resolved = hf_cache_scan.resolve_hf_cache_realpath(repo_path)
+    if not resolved:
+        return None
+    path = Path(resolved)
+    return path if path.is_dir() else None
+
+
+def _read_json_object(path: Path) -> dict:
+    try:
+        with open(path, "r", encoding = "utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _read_model_card_frontmatter(path: Path) -> dict:
+    try:
+        text = path.read_text(encoding = "utf-8")
+    except Exception:
+        return {}
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    body: list[str] = []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        body.append(line)
+    if not body:
+        return {}
+    try:
+        import yaml
+        data = yaml.safe_load("\n".join(body)) or {}
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _cached_model_local_metadata(repo_path: Path) -> dict:
+    snapshot = _cached_model_snapshot_path(repo_path)
+    if snapshot is None:
+        return {}
+
+    result: dict = {}
+    config = _read_json_object(snapshot / "config.json")
+    quant_method = (
+        config.get("quantization_config", {}).get("quant_method")
+        if isinstance(config.get("quantization_config"), dict)
+        else None
+    )
+    if isinstance(quant_method, str) and quant_method.strip():
+        result["quant_method"] = quant_method.strip()
+
+    card = _read_model_card_frontmatter(snapshot / "README.md")
+    pipeline_tag = card.get("pipeline_tag")
+    if isinstance(pipeline_tag, str) and pipeline_tag.strip():
+        result["pipeline_tag"] = pipeline_tag.strip()
+    library_name = card.get("library_name")
+    if isinstance(library_name, str) and library_name.strip():
+        result["library_name"] = library_name.strip()
+    tags = card.get("tags")
+    if isinstance(tags, list):
+        clean_tags = [tag.strip() for tag in tags if isinstance(tag, str) and tag.strip()]
+        if clean_tags:
+            result["tags"] = clean_tags
+    return result
+
+
+def _scan_cached_models() -> list[dict]:
+    """Synchronous HF-cache disk walk for non-GGUF model repos; runs in a worker thread."""
+    cache_scans = all_hf_cache_scans()
+
+    seen_lower: dict[str, dict] = {}
+    inspected = 0
+    skipped_gguf = 0
+    skipped_no_weights = 0
+    for hf_cache in cache_scans:
+        for repo_info in hf_cache.repos:
+            inspected += 1
+            try:
+                if str(repo_info.repo_type) != "model":
+                    continue
+                repo_id = repo_info.repo_id
+                has_main_gguf = _repo_has_gguf_files(repo_info)
+                payload = _repo_non_gguf_model_payload(repo_info)
+                if payload.size_bytes == 0:
+                    if has_main_gguf:
+                        skipped_gguf += 1
+                    continue
+                if not payload.has_runnable_weights:
+                    skipped_no_weights += 1
+                    continue
+                key = repo_id.lower()
+                existing = seen_lower.get(key)
+                repo_path = Path(repo_info.repo_path)
+                snapshot_partial = hf_cache_scan.is_snapshot_partial(
+                    "model",
+                    repo_id,
+                    repo_path,
+                )
+                row = {
+                    "repo_id": repo_id,
+                    "size_bytes": payload.size_bytes,
+                    "cache_path": str(repo_info.repo_path),
+                    "partial": snapshot_partial,
+                    "partial_transport": (
+                        hf_cache_scan.partial_transport_for(
+                            "model",
+                            repo_id,
+                            repo_cache_dir = repo_path,
+                        )
+                        if snapshot_partial
+                        else None
+                    ),
+                    **_cached_model_local_metadata(repo_path),
+                }
+                row.update(
+                    _cache_inventory_fields(
+                        repo_id,
+                        payload.model_format,
+                        partial = bool(row["partial"]),
+                    )
+                )
+                if _prefer_cache_row(row, existing):
+                    seen_lower[key] = row
+            except Exception as e:
+                repo_label = getattr(repo_info, "repo_id", "<unknown>")
+                logger.warning(f"Skipping cached model repo {repo_label}: {e}")
+                continue
+    cached = sorted(seen_lower.values(), key = lambda c: c["repo_id"])
+    logger.info(
+        "Cached model scan: inspected=%d skipped_gguf=%d skipped_no_weights=%d returned=%d",
+        inspected,
+        skipped_gguf,
+        skipped_no_weights,
+        len(cached),
+    )
+    return cached
+
+
+async def list_cached_models_response(hf_token: Optional[str] = None):
+    """List non-GGUF model repos downloaded to HF cache, legacy Unsloth cache, and HF default cache."""
+    try:
+        cached = await asyncio.to_thread(_scan_cached_models)
+        return {"cached": cached}
+    except Exception as e:
+        logger.error(
+            "Error listing cached models: %s",
+            download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to read the local model cache.",
+        ) from e
diff --git a/studio/backend/hub/services/models/common.py b/studio/backend/hub/services/models/common.py
new file mode 100644
index 0000000000..688d324a60
--- /dev/null
+++ b/studio/backend/hub/services/models/common.py
@@ -0,0 +1,610 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared model inventory helpers for the Hub service layer."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import List, Literal, Optional
+from urllib.parse import quote
+
+from hub.schemas.inventory import (
+    LocalModelCapabilities,
+    LocalModelInfo,
+    ModelFormat,
+    ModelRuntime,
+)
+from hub.utils.gguf import (
+    extract_quant_label,
+    is_gguf_filename as _is_gguf_filename,
+    is_mmproj_filename as _is_mmproj_filename,
+)
+from hub.utils.paths import is_valid_repo_id as _is_valid_repo_id
+
+ModelType = Literal["text", "vision", "audio", "embeddings"]
+LocalModelSource = Literal["models_dir", "hf_cache", "lmstudio", "ollama", "custom"]
+
+
+def _safe_is_dir(path) -> bool:
+    # Py >= 3.12 propagates PermissionError (EACCES) from is_dir(); folder scans
+    # probe root-owned system dirs, so treat un-stat-able paths as not-a-dir.
+    try:
+        return Path(path).is_dir()
+    except OSError:
+        return False
+
+
+_LOCAL_CHECKPOINT_EXTENSIONS = (
+    ".bin",
+    ".pt",
+    ".pth",
+    ".ckpt",
+    ".h5",
+    ".msgpack",
+    ".npz",
+)
+
+_LOCAL_BASE_MODEL_PREFIXES = {
+    "checkpoint",
+    "checkpoints",
+    "export",
+    "exports",
+    "model",
+    "models",
+    "output",
+    "outputs",
+    "run",
+    "runs",
+    "train",
+}
+_HF_CACHE_MODEL_FILE_PROBE_LIMIT = 2000
+
+
+def _is_model_directory(d: Path) -> bool:
+    """True when *d* has a config plus real weights; excludes mmproj GGUFs and non-weight ``.bin`` files (``tokenizer.bin``) to avoid false positives."""
+
+    def _is_weight_file(f: Path) -> bool:
+        suffix = f.suffix.lower()
+        if suffix == ".safetensors":
+            return True
+        if suffix == ".gguf":
+            return "mmproj" not in f.name.lower()
+        if suffix == ".bin":
+            name = f.name.lower()
+            return (
+                name.startswith("pytorch_model")
+                or name.startswith("model")
+                or name.startswith("adapter_model")
+                or name.startswith("consolidated")
+            )
+        return False
+
+    try:
+        has_config = (d / "config.json").exists() or (d / "adapter_config.json").exists()
+        if not has_config:
+            return False
+        return any(_is_weight_file(f) for f in d.iterdir() if f.is_file())
+    except OSError:
+        return False
+
+
+def _local_inventory_id(
+    source: str,
+    model_format: ModelFormat,
+    semantic_id: str,
+    variant: Optional[str] = None,
+) -> str:
+    parts = [
+        source,
+        model_format,
+        quote(semantic_id, safe = ""),
+    ]
+    if variant:
+        parts.append(quote(variant, safe = ""))
+    return ":".join(parts)
+
+
+def _runtime_for_format(model_format: ModelFormat) -> ModelRuntime:
+    if model_format == "gguf":
+        return "llama_cpp"
+    if model_format == "adapter":
+        return "adapter"
+    if model_format in {"safetensors", "checkpoint"}:
+        return "transformers"
+    return "unknown"
+
+
+def _capabilities_for_format(
+    model_format: ModelFormat,
+    source: str,
+    *,
+    partial: bool = False,
+    requires_variant: bool = False,
+) -> LocalModelCapabilities:
+    is_complete = not partial
+    can_chat = model_format in {"gguf", "safetensors", "adapter", "checkpoint"}
+    can_train = model_format in {"safetensors", "checkpoint"} and is_complete
+    return LocalModelCapabilities(
+        can_train = can_train,
+        can_chat = can_chat and is_complete,
+        can_delete = source == "hf_cache",
+        can_download = False,
+        requires_variant = requires_variant,
+        supports_lora = model_format in {"safetensors", "checkpoint"} and is_complete,
+        supports_vision = False,
+    )
+
+
+def _prefer_complete_larger(
+    candidate_partial: bool,
+    candidate_size_bytes: int,
+    existing_partial: bool,
+    existing_size_bytes: int,
+) -> bool:
+    if candidate_partial != existing_partial:
+        return not candidate_partial
+    return candidate_size_bytes > existing_size_bytes
+
+
+def _gguf_variant_state_summary(repo_id: str) -> tuple[bool, int]:
+    """Whether GGUF variant-scoped state exists and its expected size; a cancelled/in-progress variant may have only manifests/markers/`.incomplete` blobs, which inventory needs to avoid a generic fallback row."""
+    from hub.utils import download_manifest
+
+    variant_keys: set[str] = set()
+    size_by_variant: dict[str, int] = {}
+    for variant, _path in download_manifest.iter_variant_manifests(
+        "model",
+        repo_id,
+    ):
+        key = variant.lower()
+        variant_keys.add(key)
+        manifest = download_manifest.read_manifest("model", repo_id, variant)
+        if manifest is None:
+            continue
+        size_by_variant[key] = max(
+            size_by_variant.get(key, 0),
+            sum(max(0, int(file.size or 0)) for file in manifest.expected_files),
+        )
+    for variant, _path in download_manifest.iter_variant_markers(
+        "model",
+        repo_id,
+    ):
+        variant_keys.add(variant.lower())
+    return bool(variant_keys), sum(size_by_variant.values())
+
+
+def _apply_format_aware_partial(
+    rows: List[LocalModelInfo],
+    *,
+    snapshot_partial: bool,
+    gguf_partial: bool,
+    snapshot_partial_transport: Optional[str] = None,
+) -> List[LocalModelInfo]:
+    """Rewrite each row's partial flag with format-aware predicates so a hybrid (gguf + safetensors) repo's broken format doesn't taint the clean one; capabilities are recomputed from the new flag."""
+    rewritten: List[LocalModelInfo] = []
+    for row in rows:
+        target = gguf_partial if row.model_format == "gguf" else snapshot_partial
+        if not target:
+            rewritten.append(row)
+            continue
+        # GGUF row-level transport is ambiguous (variants may differ); per-variant
+        # detail lives on GgufVariantDetail.partial_transport via the variants endpoint.
+        partial_transport = None if row.model_format == "gguf" else snapshot_partial_transport
+        rewritten.append(
+            row.model_copy(
+                update = {
+                    "partial": True,
+                    "partial_transport": partial_transport,
+                    "capabilities": _capabilities_for_format(
+                        row.model_format,
+                        row.source,
+                        partial = True,
+                        requires_variant = row.capabilities.requires_variant,
+                    ),
+                }
+            )
+        )
+    return rewritten
+
+
+def _weight_basename(name: str) -> str:
+    return name.replace("\\", "/").rsplit("/", 1)[-1].lower()
+
+
+def _is_adapter_weight_name(name: str) -> bool:
+    lower = _weight_basename(name)
+    return lower.startswith("adapter_model") and lower.endswith((".safetensors", ".bin"))
+
+
+def _is_transformers_safetensors_weight_name(name: str) -> bool:
+    lower = _weight_basename(name)
+    return lower.endswith(".safetensors") and lower.startswith(
+        ("model", "pytorch_model", "consolidated")
+    )
+
+
+def _is_transformers_bin_weight_name(name: str) -> bool:
+    lower = _weight_basename(name)
+    if not lower.endswith(".bin"):
+        return False
+    return lower.startswith(("pytorch_model", "model", "consolidated", "adapter_model"))
+
+
+def _is_checkpoint_weight_name(name: str) -> bool:
+    lower = _weight_basename(name)
+    if lower.endswith(".bin"):
+        return _is_transformers_bin_weight_name(lower)
+    return lower.endswith(_LOCAL_CHECKPOINT_EXTENSIONS)
+
+
+def _is_adapter_weight_file(path: Path) -> bool:
+    return _is_adapter_weight_name(path.name)
+
+
+def _is_transformers_safetensors_weight_file(path: Path) -> bool:
+    return _is_transformers_safetensors_weight_name(path.name)
+
+
+def _is_transformers_bin_weight_file(path: Path) -> bool:
+    return _is_transformers_bin_weight_name(path.name)
+
+
+def _is_checkpoint_weight_file(path: Path) -> bool:
+    return _is_checkpoint_weight_name(path.name)
+
+
+def _classify_non_gguf_model_format(
+    *,
+    has_config: bool,
+    has_adapter_config: bool,
+    has_adapter_weights: bool,
+    has_safetensors: bool,
+    has_transformers_safetensors: bool,
+    has_checkpoint_weights: bool,
+    trusted_hf_cache_repo: bool = False,
+) -> Optional[ModelFormat]:
+    if has_safetensors and (has_config or (trusted_hf_cache_repo and has_transformers_safetensors)):
+        return "safetensors"
+    if has_adapter_config and has_adapter_weights:
+        return "adapter"
+    if has_config and has_checkpoint_weights:
+        return "checkpoint"
+    return None
+
+
+def _is_main_gguf_filename(name: str) -> bool:
+    return _is_gguf_filename(name) and not _is_mmproj_filename(name)
+
+
+def _iter_gguf_paths(root: Path):
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = list(current.iterdir())
+        except OSError:
+            continue
+        for path in entries:
+            try:
+                if path.is_dir() and not path.is_symlink():
+                    stack.append(path)
+                elif path.is_file() and _is_gguf_filename(path.name):
+                    yield path
+            except OSError:
+                continue
+
+
+def _iter_immediate_files(path: Path, *, include_symlinks: bool = False) -> list[Path]:
+    if path.is_file():
+        return [path]
+    if not path.is_dir():
+        return []
+    try:
+        return [
+            entry
+            for entry in path.iterdir()
+            if entry.is_file() or (include_symlinks and entry.is_symlink())
+        ]
+    except OSError:
+        return []
+
+
+def _iter_hf_cache_model_files(path: Path) -> list[Path]:
+    files = _iter_immediate_files(path, include_symlinks = True)
+    if not path.is_dir():
+        return files
+    if any(
+        _is_main_gguf_filename(entry.name)
+        or _is_transformers_safetensors_weight_file(entry)
+        or _is_checkpoint_weight_file(entry)
+        for entry in files
+    ):
+        return files
+    try:
+        bounded: list[Path] = []
+        for index, entry in enumerate(path.rglob("*"), start = 1):
+            if index > _HF_CACHE_MODEL_FILE_PROBE_LIMIT:
+                break
+            if entry.is_file() or entry.is_symlink():
+                bounded.append(entry)
+        return bounded
+    except OSError:
+        return []
+
+
+def _file_size_bytes(path: Path) -> int:
+    try:
+        if path.is_file() or path.is_symlink():
+            return path.stat().st_size
+    except OSError:
+        return 0
+    return 0
+
+
+def _sum_file_sizes(paths) -> int:
+    return sum(_file_size_bytes(path) for path in paths)
+
+
+def _main_gguf_files(path: Path, *, include_symlinks: bool = False) -> list[Path]:
+    return [
+        entry
+        for entry in _iter_immediate_files(path, include_symlinks = include_symlinks)
+        if _is_main_gguf_filename(entry.name)
+    ]
+
+
+def _format_label(model_format: ModelFormat) -> str:
+    if model_format == "gguf":
+        return "GGUF"
+    if model_format == "safetensors":
+        return "Safetensors"
+    if model_format == "adapter":
+        return "Adapter"
+    if model_format == "checkpoint":
+        return "Checkpoint"
+    return "Unknown"
+
+
+def _read_adapter_config(path: Path) -> dict:
+    if not path.is_dir():
+        return {}
+    try:
+        with (path / "adapter_config.json").open("r", encoding = "utf-8") as f:
+            data = json.load(f)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _clean_optional_string(value: object) -> Optional[str]:
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def _base_model_looks_local(value: str) -> bool:
+    raw = value.strip()
+    normalized = raw.replace("\\", "/")
+    if raw.startswith(("/", "./", "../", "~", "\\\\")) or (
+        len(raw) >= 3 and raw[1] == ":" and raw[0].isalpha()
+    ):
+        return True
+    first = normalized.split("/", 1)[0].lower()
+    return "/" in normalized and first in _LOCAL_BASE_MODEL_PREFIXES
+
+
+def _base_model_source(value: Optional[str], adapter_dir: Path) -> Optional[str]:
+    if not value:
+        return None
+    candidates = [value, value.replace("\\", "/")]
+    for candidate in candidates:
+        try:
+            expanded = Path(os.path.expanduser(candidate))
+            if expanded.exists() or (adapter_dir / candidate).exists():
+                return "local"
+        except (OSError, ValueError):
+            return "unknown"
+    if _base_model_looks_local(value):
+        return "local"
+    if _is_valid_repo_id(value):
+        return "huggingface"
+    return "unknown"
+
+
+def _local_model_info(
+    *,
+    scan_path: Path,
+    load_path: Path,
+    source: LocalModelSource,
+    model_format: ModelFormat,
+    display_name: Optional[str] = None,
+    model_id: Optional[str] = None,
+    updated_at: Optional[float] = None,
+    partial: bool = False,
+    requires_variant: bool = False,
+    format_variant: Optional[str] = None,
+    size_bytes: int = 0,
+    base_model: Optional[str] = None,
+    base_model_source: Optional[str] = None,
+    adapter_type: Optional[str] = None,
+    training_method: Optional[str] = None,
+) -> LocalModelInfo:
+    load_id = model_id if source == "hf_cache" and model_id else str(load_path)
+    semantic_id = model_id or str(load_path)
+    return LocalModelInfo(
+        id = load_id,
+        inventory_id = _local_inventory_id(
+            source,
+            model_format,
+            semantic_id,
+            format_variant,
+        ),
+        load_id = load_id,
+        model_id = model_id,
+        display_name = display_name or (scan_path.stem if scan_path.is_file() else scan_path.name),
+        path = str(load_path),
+        size_bytes = max(0, int(size_bytes or 0)),
+        source = source,
+        base_model = base_model,
+        base_model_source = base_model_source,
+        adapter_type = adapter_type,
+        training_method = training_method,
+        updated_at = updated_at,
+        partial = partial,
+        model_format = model_format,
+        runtime = _runtime_for_format(model_format),
+        format_variant = format_variant,
+        capabilities = _capabilities_for_format(
+            model_format,
+            source,
+            partial = partial,
+            requires_variant = requires_variant,
+        ),
+    )
+
+
+def _classify_local_path(
+    scan_path: Path,
+    source: LocalModelSource,
+    *,
+    load_path: Optional[Path] = None,
+    display_name: Optional[str] = None,
+    model_id: Optional[str] = None,
+    updated_at: Optional[float] = None,
+    partial: bool = False,
+) -> list[LocalModelInfo]:
+    load_path = load_path or scan_path
+    files = (
+        _iter_hf_cache_model_files(scan_path)
+        if source == "hf_cache"
+        else _iter_immediate_files(scan_path)
+    )
+    if not files:
+        return []
+
+    rows: list[LocalModelInfo] = []
+    include_broken_snapshot_symlinks = source == "hf_cache"
+    gguf_files = _main_gguf_files(
+        scan_path,
+        include_symlinks = include_broken_snapshot_symlinks,
+    )
+    if gguf_files:
+        gguf_size_bytes = _sum_file_sizes(gguf_files)
+        variant = (
+            extract_quant_label(gguf_files[0].name)
+            if scan_path.is_file() and len(gguf_files) == 1
+            else None
+        )
+        rows.append(
+            _local_model_info(
+                scan_path = scan_path,
+                load_path = load_path,
+                source = source,
+                model_format = "gguf",
+                display_name = display_name,
+                model_id = model_id,
+                updated_at = updated_at,
+                partial = partial,
+                requires_variant = scan_path.is_dir(),
+                format_variant = variant,
+                size_bytes = gguf_size_bytes,
+            )
+        )
+
+    has_config = (scan_path / "config.json").is_file() if scan_path.is_dir() else False
+    has_adapter_config = (
+        (scan_path / "adapter_config.json").is_file() if scan_path.is_dir() else False
+    )
+    adapter_config = _read_adapter_config(scan_path) if has_adapter_config else {}
+    adapter_base_model = _clean_optional_string(adapter_config.get("base_model_name_or_path"))
+    adapter_type = _clean_optional_string(adapter_config.get("peft_type"))
+    training_method = _clean_optional_string(adapter_config.get("unsloth_training_method"))
+    has_adapter_weights = any(_is_adapter_weight_file(f) for f in files)
+    has_safetensors = any(
+        f.suffix.lower() == ".safetensors" and not _is_adapter_weight_file(f) for f in files
+    )
+    has_transformers_safetensors = any(
+        _is_transformers_safetensors_weight_file(f) and not _is_adapter_weight_file(f)
+        for f in files
+    )
+    has_checkpoint_weights = any(_is_checkpoint_weight_file(f) for f in files)
+    trusted_hf_cache_repo = source == "hf_cache" and bool(model_id)
+
+    model_format = _classify_non_gguf_model_format(
+        has_config = has_config,
+        has_adapter_config = has_adapter_config,
+        has_adapter_weights = has_adapter_weights,
+        has_safetensors = has_safetensors,
+        has_transformers_safetensors = has_transformers_safetensors,
+        has_checkpoint_weights = has_checkpoint_weights,
+        trusted_hf_cache_repo = trusted_hf_cache_repo,
+    )
+
+    if model_format is not None:
+        if model_format == "adapter":
+            size_bytes = _sum_file_sizes(f for f in files if _is_adapter_weight_file(f))
+        elif model_format == "safetensors":
+            size_bytes = _sum_file_sizes(
+                f
+                for f in files
+                if f.suffix.lower() == ".safetensors" and not _is_adapter_weight_file(f)
+            )
+        else:
+            size_bytes = _sum_file_sizes(f for f in files if _is_checkpoint_weight_file(f))
+        rows.append(
+            _local_model_info(
+                scan_path = scan_path,
+                load_path = load_path,
+                source = source,
+                model_format = model_format,
+                display_name = display_name,
+                model_id = model_id,
+                updated_at = updated_at,
+                partial = partial,
+                size_bytes = size_bytes,
+                base_model = adapter_base_model if model_format == "adapter" else None,
+                base_model_source = (
+                    _base_model_source(adapter_base_model, scan_path)
+                    if model_format == "adapter"
+                    else None
+                ),
+                adapter_type = adapter_type if model_format == "adapter" else None,
+                training_method = training_method if model_format == "adapter" else None,
+            )
+        )
+    elif not rows:
+        fallback_format: ModelFormat = (
+            "safetensors" if trusted_hf_cache_repo and has_config else "unknown"
+        )
+        size_bytes = _sum_file_sizes(files)
+        rows.append(
+            _local_model_info(
+                scan_path = scan_path,
+                load_path = load_path,
+                source = source,
+                model_format = fallback_format,
+                display_name = display_name,
+                model_id = model_id,
+                updated_at = updated_at,
+                partial = partial or trusted_hf_cache_repo,
+                size_bytes = size_bytes,
+            )
+        )
+
+    if len(rows) > 1:
+        rows = [
+            row.model_copy(
+                update = {
+                    "display_name": f"{row.display_name} ({_format_label(row.model_format)})",
+                    "inventory_id": _local_inventory_id(
+                        row.source,
+                        row.model_format,
+                        row.model_id or row.path,
+                        row.format_variant,
+                    ),
+                }
+            )
+            for row in rows
+        ]
+    return rows
diff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.py
new file mode 100644
index 0000000000..d4aed0d59f
--- /dev/null
+++ b/studio/backend/hub/services/models/deletion.py
@@ -0,0 +1,455 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Cached model deletion."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.utils import download_manifest
+from hub.utils import download_registry
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.gguf import extract_quant_label
+from hub.utils.hf_cache_state import (
+    INCOMPLETE_SUFFIX,
+    purge_partial_repo,
+    purge_repo_cache_dirs,
+)
+from hub.utils.paths import (
+    is_valid_gguf_variant as _is_valid_gguf_variant,
+    is_valid_repo_id as _is_valid_repo_id,
+    resolve_cached_repo_id_case,
+)
+from hub.services import resolve_destructive_repo_ids
+from hub.services.models import cache_inventory, downloads, gguf_variants
+from hub.services.models.common import (
+    _is_gguf_filename,
+    _is_main_gguf_filename,
+    _is_mmproj_filename,
+)
+
+logger = get_logger(__name__)
+
+
+def _snapshot_blob_reference_counts(repo_dir: Optional[Path]) -> dict[Path, int]:
+    """Map each blob's realpath to its live snapshot symlink count, so per-variant deletion never unlinks a blob another revision still references (call after the target variant's own symlinks are removed)."""
+    counts: dict[Path, int] = {}
+    if repo_dir is None:
+        return counts
+    snapshots = repo_dir / "snapshots"
+    if not snapshots.is_dir():
+        return counts
+    try:
+        entries = list(snapshots.rglob("*"))
+    except OSError:
+        return counts
+    for link in entries:
+        try:
+            if not link.is_symlink():
+                continue
+            target = link.resolve()
+        except OSError:
+            continue
+        counts[target] = counts.get(target, 0) + 1
+    return counts
+
+
+def _blob_hash_from_path(blob: Path) -> Optional[str]:
+    name = blob.name
+    if not name or name.endswith(INCOMPLETE_SUFFIX):
+        return None
+    return name
+
+
+def _path_exists_or_symlink(path: Path) -> bool:
+    try:
+        return path.is_symlink() or path.exists()
+    except OSError:
+        return False
+
+
+def _repo_file_matches(target_repo, predicate) -> list[tuple[Path, Optional[Path], str]]:
+    matches: list[tuple[Path, Optional[Path], str]] = []
+    for rev in getattr(target_repo, "revisions", ()):
+        for f in getattr(rev, "files", ()):
+            name = str(getattr(f, "file_name", ""))
+            if not predicate(name):
+                continue
+            file_path = getattr(f, "file_path", None)
+            if not file_path:
+                continue
+            blob_path = getattr(f, "blob_path", None)
+            matches.append(
+                (
+                    Path(file_path),
+                    Path(blob_path) if blob_path else None,
+                    name,
+                )
+            )
+    return matches
+
+
+def _has_remaining_main_gguf(target_repo) -> bool:
+    return any(
+        _path_exists_or_symlink(snap)
+        for snap, _blob, _name in _repo_file_matches(
+            target_repo,
+            _is_main_gguf_filename,
+        )
+    )
+
+
+def _delete_gguf_variant_from_repos(
+    repo_id: str,
+    variant: str,
+    target_repos: list,
+    hf_token: Optional[str],
+    *,
+    sibling_active: bool = False,
+) -> dict:
+    failures: list[str] = []
+    removed_snapshots = 0
+    deleted_bytes = 0
+    deleted_blobs = 0
+    completed_hashes: set[str] = set()
+
+    for target_repo in target_repos:
+        repo_dir = Path(target_repo.repo_path) if getattr(target_repo, "repo_path", None) else None
+        matched = _repo_file_matches(
+            target_repo,
+            lambda name: _is_main_gguf_filename(name)
+            and extract_quant_label(name).lower() == variant.lower(),
+        )
+
+        for snap, _blob, name in matched:
+            try:
+                if _path_exists_or_symlink(snap):
+                    snap.unlink()
+                    removed_snapshots += 1
+            except OSError as e:
+                failures.append(f"{name}: {e}")
+
+        companion_matches: list[tuple[Path, Optional[Path], str]] = []
+        if matched and not sibling_active and not _has_remaining_main_gguf(target_repo):
+            companion_matches = _repo_file_matches(
+                target_repo,
+                lambda name: _is_gguf_filename(name) and _is_mmproj_filename(name),
+            )
+            for snap, _blob, name in companion_matches:
+                try:
+                    if _path_exists_or_symlink(snap):
+                        snap.unlink()
+                        removed_snapshots += 1
+                except OSError as e:
+                    failures.append(f"{name}: {e}")
+
+        ref_counts = _snapshot_blob_reference_counts(repo_dir)
+        seen_blobs: set[Path] = set()
+        for _snap, blob, name in [*matched, *companion_matches]:
+            if blob is None:
+                continue
+            blob_hash = _blob_hash_from_path(blob)
+            if blob_hash:
+                completed_hashes.add(blob_hash)
+            try:
+                blob_key = blob.resolve()
+            except OSError:
+                blob_key = blob
+            if blob_key in seen_blobs:
+                continue
+            seen_blobs.add(blob_key)
+            if ref_counts.get(blob_key, 0) > 0:
+                continue
+            try:
+                if blob.exists():
+                    deleted_bytes += blob.stat().st_size
+                    blob.unlink()
+                    deleted_blobs += 1
+            except OSError as e:
+                failures.append(f"{name}: {e}")
+
+    if failures:
+        raise HTTPException(
+            status_code = 409,
+            detail = (
+                f"Couldn't fully delete {variant} for {repo_id}: "
+                f"{len(failures)} file(s) are in use. "
+                "Unload the model and try again."
+            ),
+        )
+
+    incomplete_result = gguf_variants.delete_variant_incomplete_blobs_result(
+        repo_id,
+        variant,
+        hf_token,
+        extra_hashes = frozenset(completed_hashes),
+        companions = not sibling_active,
+    )
+    if incomplete_result.unresolved:
+        raise HTTPException(
+            status_code = 409,
+            detail = (
+                f"Couldn't fully delete {variant} for {repo_id}: partial "
+                "download bytes exist but this variant's blob hashes are unavailable. "
+                "Reconnect or provide access to the repo, then try again."
+            ),
+        )
+
+    state_purged = download_manifest.purge_state("model", repo_id, variant)
+    if (
+        removed_snapshots == 0
+        and deleted_blobs == 0
+        and incomplete_result.deleted == 0
+        and not state_purged
+    ):
+        raise HTTPException(
+            status_code = 404,
+            detail = f"Variant {variant} not found in cache for {repo_id}",
+        )
+
+    freed_mb = deleted_bytes / (1024 * 1024)
+    logger.info(
+        f"Deleted {removed_snapshots} file(s) for {repo_id} variant {variant}: "
+        f"{freed_mb:.1f} MB freed"
+    )
+    return {"status": "deleted", "repo_id": repo_id, "variant": variant}
+
+
+def _loaded_id_matches_repo(loaded_id: str, repo_id: str) -> bool:
+    """True when *loaded_id* is *repo_id* or a file within it; ``/``-boundary aware so ``org/model`` doesn't match sibling ``org/model-v2``."""
+    rid = repo_id.lower()
+    lid = loaded_id.lower()
+    return lid == rid or lid.startswith(f"{rid}/")
+
+
+def _loaded_repo_variant_blocks_delete(
+    loaded_id: str, repo_id: str, delete_variant: Optional[str], loaded_variant: Optional[str]
+) -> bool:
+    if not _loaded_id_matches_repo(loaded_id, repo_id):
+        return False
+    if not delete_variant:
+        return True
+    if not loaded_variant:
+        return True
+    return loaded_variant.lower() == delete_variant.lower()
+
+
+_LOAD_STATE_UNVERIFIABLE_DETAIL = (
+    "Couldn't verify whether this model is still loaded for inference. "
+    "Unload it if it is active, then try deleting again."
+)
+
+
+def _llama_cpp_blocks_delete(repo_id: str, variant: Optional[str]) -> bool:
+    """Whether the llama.cpp backend holds *repo_id* (/variant). Acquiring fails open (import error means nothing loaded); reading load state is unguarded so a raise propagates and the caller fails closed rather than delete a live model."""
+    try:
+        from routes.inference import get_llama_cpp_backend
+        backend = get_llama_cpp_backend()
+    except Exception as e:
+        logger.debug(f"llama.cpp backend unavailable during delete guard for {repo_id}: {e}")
+        return False
+    loaded_id = backend.model_identifier
+    loaded_variant = getattr(backend, "hf_variant", None)
+    if backend.is_active and not backend.is_loaded and loaded_id:
+        return _loaded_repo_variant_blocks_delete(
+            loaded_id,
+            repo_id,
+            variant,
+            loaded_variant,
+        )
+    if backend.is_loaded and loaded_id:
+        return _loaded_repo_variant_blocks_delete(
+            loaded_id,
+            repo_id,
+            variant,
+            loaded_variant,
+        )
+    return False
+
+
+def _inference_backend_blocks_delete(repo_id: str) -> bool:
+    """Whether the subprocess inference backend holds *repo_id*; same fail-open-on-acquire / surface-on-query contract as :func:`_llama_cpp_blocks_delete`."""
+    try:
+        from core.inference import get_inference_backend
+        backend = get_inference_backend()
+    except Exception as e:
+        logger.debug(f"Inference backend unavailable during delete guard for {repo_id}: {e}")
+        return False
+    active_name = backend.active_model_name
+    return bool(active_name) and _loaded_id_matches_repo(active_name, repo_id)
+
+
+async def delete_cached_model_response(
+    repo_id: str,
+    variant: Optional[str] = None,
+    hf_token: Optional[str] = None,
+):
+    """Delete a cached model repo (or a specific GGUF variant) from the HF cache.
+
+    When *variant* is provided, only the GGUF files matching that quant label
+    are removed (e.g. ``UD-Q4_K_XL``).  Otherwise the entire repo is deleted.
+    Refuses if the model is currently loaded for inference.
+    """
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(status_code = 400, detail = "Invalid repo_id format")
+    variant = (variant or "").strip() or None
+    if variant is not None and not _is_valid_gguf_variant(variant):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid gguf_variant: {variant!r}",
+        )
+
+    # Guard fails closed: if a live backend's load state can't be read, abort
+    # with 503 rather than risk unlinking weights under a running process.
+    try:
+        blocks_delete = _llama_cpp_blocks_delete(repo_id, variant) or (
+            _inference_backend_blocks_delete(repo_id)
+        )
+    except Exception as e:
+        logger.warning(f"Load-state verification failed for {repo_id}; refusing delete: {e}")
+        raise HTTPException(
+            status_code = 503,
+            detail = _LOAD_STATE_UNVERIFIABLE_DETAIL,
+        )
+    if blocks_delete:
+        raise HTTPException(
+            status_code = 400,
+            detail = "Unload the model before deleting",
+        )
+
+    repo_key = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")
+    if not downloads.registry.begin_delete(repo_key, variant):
+        detail = (
+            f"Cancel the {variant} download before deleting it."
+            if variant is not None
+            else "Cancel the active downloads before deleting."
+        )
+        raise HTTPException(status_code = 400, detail = detail)
+    try:
+        return await asyncio.to_thread(_delete_cached_model_blocking, repo_id, variant, hf_token)
+    finally:
+        downloads.registry.end_delete(repo_key, variant)
+        cache_inventory.invalidate_hf_cache_scans()
+
+
+def _delete_cached_model_blocking(
+    repo_id: str, variant: Optional[str], hf_token: Optional[str]
+) -> dict:
+    try:
+        # If a sibling quant is downloading concurrently, restrict this delete to
+        # the variant's own files and leave the shared mmproj companion for it.
+        sibling_active = bool(
+            variant and downloads.registry.has_active_peer_variant(repo_id, variant)
+        )
+
+        cache_scans = cache_inventory.all_hf_cache_scans()
+
+        candidate_entries = []
+        for hf_cache in cache_scans:
+            for repo_info in hf_cache.repos:
+                if str(repo_info.repo_type) != "model":
+                    continue
+                if repo_info.repo_id.lower() == repo_id.lower():
+                    candidate_entries.append((hf_cache, repo_info))
+
+        matched_repo_ids = resolve_destructive_repo_ids(
+            repo_id,
+            [str(repo_info.repo_id) for _hf_cache, repo_info in candidate_entries],
+            noun = "models",
+        )
+        target_entries = [
+            (hf_cache, repo_info)
+            for hf_cache, repo_info in candidate_entries
+            if str(repo_info.repo_id) in matched_repo_ids
+        ]
+
+        if not target_entries:
+            if variant is None:
+                cache_purged = purge_repo_cache_dirs("model", repo_id) or purge_partial_repo(
+                    "model", repo_id
+                )
+                state_purged = download_manifest.purge_all_state_for_repo("model", repo_id) > 0
+                if cache_purged or state_purged:
+                    return {"status": "deleted", "repo_id": repo_id}
+            if variant:
+                incomplete_result = gguf_variants.delete_variant_incomplete_blobs_result(
+                    repo_id,
+                    variant,
+                    hf_token,
+                    companions = not sibling_active,
+                )
+                if incomplete_result.unresolved:
+                    raise HTTPException(
+                        status_code = 409,
+                        detail = (
+                            f"Couldn't fully delete {variant} for {repo_id}: partial "
+                            "download bytes exist but this variant's blob hashes are unavailable. "
+                            "Reconnect or provide access to the repo, then try again."
+                        ),
+                    )
+                state_purged = download_manifest.purge_state(
+                    "model",
+                    repo_id,
+                    variant,
+                )
+                if incomplete_result.deleted > 0 or state_purged:
+                    return {
+                        "status": "deleted",
+                        "repo_id": repo_id,
+                        "variant": variant,
+                    }
+            raise HTTPException(status_code = 404, detail = "Model not found in cache")
+
+        if variant:
+            return _delete_gguf_variant_from_repos(
+                repo_id,
+                variant,
+                [repo for _cache, repo in target_entries],
+                hf_token,
+                sibling_active = sibling_active,
+            )
+
+        deleted_revisions = False
+        for hf_cache, repo_info in target_entries:
+            revision_hashes = [
+                rev.commit_hash for rev in repo_info.revisions if getattr(rev, "commit_hash", None)
+            ]
+            if not revision_hashes:
+                continue
+            delete_strategy = hf_cache.delete_revisions(*revision_hashes)
+            logger.info(
+                f"Deleting cached model {repo_id} from "
+                f"{getattr(hf_cache, 'cache_dir', '<unknown>')}: "
+                f"{delete_strategy.expected_freed_size_str} will be freed"
+            )
+            delete_strategy.execute()
+            deleted_revisions = True
+
+        cache_purged = purge_repo_cache_dirs("model", repo_id)
+        partial_purged = purge_partial_repo("model", repo_id)
+        state_purged = download_manifest.purge_all_state_for_repo("model", repo_id) > 0
+
+        if not (deleted_revisions or cache_purged or partial_purged or state_purged):
+            raise HTTPException(status_code = 404, detail = "No revisions found for model")
+
+        return {"status": "deleted", "repo_id": repo_id}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error deleting cached model %s: %s",
+            repo_id,
+            download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to delete cached model: "
+            + download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
diff --git a/studio/backend/hub/services/models/downloads.py b/studio/backend/hub/services/models/downloads.py
new file mode 100644
index 0000000000..db95b82c95
--- /dev/null
+++ b/studio/backend/hub/services/models/downloads.py
@@ -0,0 +1,411 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Download orchestration."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional, TYPE_CHECKING
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.downloads import (
+    ActiveDownloadsResponse,
+    CancelDownloadRequest,
+    DownloadJobStatus,
+    DownloadModelRequest,
+)
+from hub.utils import download_registry
+from hub.utils import download_manifest
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.hf_cache_state import has_active_incomplete_blobs
+from hub.utils.paths import (
+    is_valid_gguf_variant as _is_valid_gguf_variant,
+    is_valid_repo_id as _is_valid_repo_id,
+    resolve_cached_repo_id_case,
+)
+from hub.services import snapshot_progress
+from hub.services import download_lifecycle
+from hub.services.models import cache_inventory, gguf_variants
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    import subprocess
+
+_registry = download_registry.get_models_registry()
+
+
+def _download_job_key(repo_id: str, variant: Optional[str]) -> str:
+    return download_registry.normalize_job_key(
+        f"{download_registry.normalize_repo_key(repo_id)}::{variant or ''}"
+    )
+
+
+def _job_status(
+    key: str,
+    *,
+    repo_id: Optional[str] = None,
+    variant: Optional[str] = None,
+) -> DownloadJobStatus:
+    state, error, generation = download_lifecycle.idle_status(
+        _registry,
+        key,
+        repo_type = "model",
+        repo_id = repo_id,
+        variant = variant,
+    )
+    return DownloadJobStatus(state = state, error = error, generation = generation)
+
+
+def _spawn_download_worker(
+    repo_id: str,
+    variant: Optional[str],
+    hf_token: Optional[str],
+    use_xet: bool = False,
+    protected_blob_hashes: Optional[frozenset[str]] = None,
+) -> subprocess.Popen:
+    args = ["--repo-id", repo_id]
+    if variant:
+        args.extend(["--variant", variant])
+    return download_lifecycle.spawn_worker(
+        args,
+        hf_token,
+        use_xet = use_xet,
+        protected_blob_hashes = protected_blob_hashes,
+    )
+
+
+async def download_model_response(body: DownloadModelRequest, hf_token: Optional[str] = None):
+    """Start a background download for a HuggingFace model."""
+    repo_id = body.repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid repo_id: {repo_id!r}",
+        )
+    # Canonicalize so two different-cased paste-ins share one job + cache dir.
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")
+
+    variant = (body.gguf_variant or "").strip() or None
+    if variant is not None and not _is_valid_gguf_variant(variant):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid gguf_variant: {variant!r}",
+        )
+    key = _download_job_key(repo_id, variant)
+    transport = download_lifecycle.resolve_transport(body.use_xet)
+    variant_blob_hashes = frozenset()
+    variant_progress_blob_hashes = frozenset()
+    completed_baseline_bytes = 0
+    if variant is not None:
+        try:
+            variant_blob_hashes = await asyncio.to_thread(
+                gguf_variants.gguf_variant_blob_hashes,
+                repo_id,
+                variant,
+                hf_token,
+                include_companions = False,
+            )
+            variant_progress_blob_hashes = await asyncio.to_thread(
+                gguf_variants.gguf_variant_blob_hashes,
+                repo_id,
+                variant,
+                hf_token,
+                include_companions = True,
+            )
+        except Exception as e:
+            logger.warning(
+                "GGUF hash pre-resolution failed for %s [%s]; continuing without "
+                "a completed-bytes baseline or peer-protection hashes (the worker "
+                "re-resolves its own blobs before purging): %s",
+                repo_id,
+                variant,
+                download_registry.scrub_secrets(str(e), hf_token = hf_token),
+            )
+        has_variant_resume_state = (
+            download_manifest.has_cancel_marker("model", repo_id, variant)
+            or download_manifest.read_manifest("model", repo_id, variant) is not None
+        )
+        if variant_progress_blob_hashes and not has_variant_resume_state:
+            completed_baseline_bytes = await asyncio.to_thread(
+                download_registry.completed_blob_bytes,
+                "model",
+                repo_id,
+                variant_progress_blob_hashes,
+            )
+
+    claimed, claim_state = _registry.claim(
+        key,
+        transport,
+        repo_type = "model",
+        repo_id = repo_id,
+        variant = variant,
+        blob_hashes = variant_blob_hashes,
+        progress_blob_hashes = variant_progress_blob_hashes,
+        completed_baseline_bytes = completed_baseline_bytes,
+    )
+    generation = _registry.current_generation(key)
+    if not claimed:
+        # claim_state is the blocking job's state. The client can attach only
+        # when the blocker is this key's own in-flight job (adoptable); a
+        # cross-variant conflict or in-progress delete is not accepted.
+        return {
+            "job_key": key,
+            "state": claim_state,
+            "accepted": _registry.adoptable(key),
+            "generation": generation,
+        }
+    download_manifest.clear_cancel_marker("model", repo_id, variant)
+    # Blobs a concurrent same-repo variant is already writing (e.g. a shared
+    # mmproj). The worker must not purge these during cache preparation.
+    protected_blob_hashes = _registry.peer_blob_hashes(key) if variant else frozenset()
+
+    label = f"{repo_id}{f' [{variant}]' if variant else ''}"
+    state = download_lifecycle.launch_worker(
+        _registry,
+        key,
+        spawn = lambda: _spawn_download_worker(
+            repo_id,
+            variant,
+            hf_token,
+            use_xet = body.use_xet,
+            protected_blob_hashes = protected_blob_hashes,
+        ),
+        hf_token = hf_token,
+        label = label,
+        log_prefix = "Download",
+        logger = logger,
+        repo_type = "model",
+        repo_id = repo_id,
+        transport = transport,
+        watch_name = f"hf-download-watch-{repo_id}",
+    )
+
+    return {
+        "job_key": key,
+        "state": state,
+        "accepted": True,
+        "generation": generation,
+    }
+
+
+async def cancel_download_model_response(body: CancelDownloadRequest):
+    """Cancel an in-flight model download (SIGKILL; HF cache resumes on next download)."""
+    repo_id = body.repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid repo_id: {repo_id!r}",
+        )
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")
+    variant = (body.gguf_variant or "").strip() or None
+    if variant is not None and not _is_valid_gguf_variant(variant):
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Invalid gguf_variant: {variant!r}",
+        )
+    key = _download_job_key(repo_id, variant)
+
+    state = download_lifecycle.cancel_worker(
+        _registry,
+        key,
+        generation = body.generation,
+        label = repo_id,
+        logger = logger,
+    )
+    return {"job_key": key, "state": state}
+
+
+async def get_download_status_response(repo_id: str, gguf_variant: str = "") -> DownloadJobStatus:
+    """Return the latest state of a background download job."""
+    repo_id = repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        return DownloadJobStatus(state = "idle")
+    repo_id = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")
+    variant = (gguf_variant or "").strip() or None
+    key = _download_job_key(repo_id, variant)
+    return _job_status(key, repo_id = repo_id, variant = variant)
+
+
+async def get_active_downloads_response(repo_id: str = "") -> ActiveDownloadsResponse:
+    """Return every in-flight download for a repo in a single call."""
+    repo_id = repo_id.strip()
+    if repo_id and not _is_valid_repo_id(repo_id):
+        return ActiveDownloadsResponse(downloads = [])
+    canonical_repo_id = (
+        await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "model")
+        if repo_id
+        else None
+    )
+    return ActiveDownloadsResponse(
+        downloads = download_lifecycle.active_download_refs(
+            _registry,
+            canonical_repo_id,
+            with_variant = True,
+        )
+    )
+
+
+def _variant_transport_status(repo_id: str, variant: str, hf_token: Optional[str]) -> dict:
+    incomplete_hashes = download_registry.incomplete_blob_hashes(
+        "model",
+        repo_id,
+        active_only = True,
+    )
+    variant_hashes = gguf_variants.gguf_variant_blob_hashes(
+        repo_id,
+        variant,
+        hf_token,
+        allow_remote = False,
+    )
+    has_partial = hf_cache_scan.is_variant_partial(
+        repo_id,
+        variant,
+        incomplete_blob_hashes = incomplete_hashes,
+        variant_blob_hashes = variant_hashes,
+    )
+    last_transport = hf_cache_scan.partial_transport_for("model", repo_id, variant)
+    if (
+        last_transport is None
+        and has_partial
+        and incomplete_hashes
+        and variant_hashes
+        and incomplete_hashes.intersection(variant_hashes)
+    ):
+        last_transport = download_registry.read_active_transport_marker(
+            "model",
+            repo_id,
+            variant,
+        )
+    has_matching_incomplete = bool(
+        incomplete_hashes and variant_hashes and incomplete_hashes.intersection(variant_hashes)
+    )
+    return {
+        "has_partial": has_partial,
+        "last_transport": last_transport,
+        "resumable": (
+            has_matching_incomplete and last_transport == download_registry.TRANSPORT_HTTP
+        ),
+    }
+
+
+async def get_model_transport_status_response(
+    repo_id: str,
+    gguf_variant: str = "",
+    hf_token: Optional[str] = None,
+) -> dict:
+    """Return last transport used for this repo + whether any partial blobs
+    exist + whether that partial supports byte-level resume.
+
+    ``resumable`` is True only when an HTTP partial exists. XET partials
+    are reported via ``has_partial`` but always have ``resumable=False``
+    because ``hf_xet`` rewrites the destination from scratch on every
+    call (network resume happens transparently via its chunk cache).
+    """
+    repo_id = repo_id.strip()
+    if not _is_valid_repo_id(repo_id):
+        return {"has_partial": False, "last_transport": None, "resumable": False}
+    variant = (gguf_variant or "").strip()
+    if variant:
+        if not _is_valid_gguf_variant(variant):
+            return {"has_partial": False, "last_transport": None, "resumable": False}
+        return _variant_transport_status(repo_id, variant, hf_token)
+    return {
+        "has_partial": has_active_incomplete_blobs("model", repo_id),
+        "last_transport": download_registry.read_active_transport_marker("model", repo_id),
+        "resumable": download_registry.is_resumable_partial("model", repo_id),
+    }
+
+
+async def get_gguf_download_progress_response(
+    repo_id: str,
+    variant: str = "",
+    expected_bytes: int = 0,
+    hf_token: Optional[str] = None,
+) -> dict:
+    """Return download progress for a specific GGUF variant."""
+    expected_total = max(expected_bytes, 0)
+    progress_variant = variant.strip() or None
+    if progress_variant is not None and not _is_valid_gguf_variant(progress_variant):
+        return {
+            "downloaded_bytes": 0,
+            "completed_bytes": 0,
+            "complete_on_disk": False,
+            "expected_bytes": expected_total,
+            "progress": 0,
+            "cache_path": None,
+        }
+
+    def _metadata_resolver(
+        resolved_repo_id: str, token: Optional[str]
+    ) -> tuple[int, frozenset[str]]:
+        if progress_variant is None:
+            return expected_total, frozenset()
+        requirement = gguf_variants.gguf_variant_requirements(
+            resolved_repo_id,
+            progress_variant,
+            token,
+        )
+        if requirement is not None:
+            return requirement.download_size_bytes, requirement.required_hashes
+        manifest = download_manifest.read_manifest(
+            "model",
+            resolved_repo_id,
+            progress_variant,
+        )
+        if manifest is not None:
+            return (
+                sum(max(0, int(file.size or 0)) for file in manifest.expected_files),
+                frozenset(file.sha256 for file in manifest.expected_files if file.sha256),
+            )
+        return (
+            expected_total,
+            gguf_variants.gguf_variant_blob_hashes(
+                resolved_repo_id,
+                progress_variant,
+                token,
+                allow_remote = False,
+            ),
+        )
+
+    return await snapshot_progress.snapshot_progress_response(
+        repo_type = "model",
+        repo_id = repo_id,
+        job_key = _download_job_key(repo_id, progress_variant),
+        expected_bytes = expected_total,
+        hf_token = hf_token,
+        registry = _registry,
+        metadata_resolver = _metadata_resolver,
+        variant = progress_variant,
+    )
+
+
+async def get_download_progress_response(
+    repo_id: str,
+    expected_bytes: int = 0,
+    hf_token: Optional[str] = None,
+) -> dict:
+    """Return download progress for any HuggingFace model repo.
+
+    Checks the local HF cache for completed blobs and in-progress
+    (.incomplete) downloads. Uses the caller-supplied expected total
+    when available; otherwise queries HF metadata and caches it.
+    Also returns ``cache_path``: the realpath of the snapshot directory
+    (or the cache repo root if no snapshot exists yet) so the UI can
+    show users where the weights actually live on disk.
+    """
+    return await snapshot_progress.snapshot_progress_response(
+        repo_type = "model",
+        repo_id = repo_id,
+        job_key = _download_job_key(repo_id, None),
+        expected_bytes = expected_bytes,
+        hf_token = hf_token,
+        registry = _registry,
+        metadata_resolver = cache_inventory.get_repo_snapshot_metadata_cached,
+    )
+
+
+registry = _registry
diff --git a/studio/backend/hub/services/models/folder_browser.py b/studio/backend/hub/services/models/folder_browser.py
new file mode 100644
index 0000000000..9b0b46509b
--- /dev/null
+++ b/studio/backend/hub/services/models/folder_browser.py
@@ -0,0 +1,518 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Model folder recommendation and browsing services."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.inventory import BrowseEntry, BrowseFoldersResponse
+from hub.storage.scan_folders import (
+    contains_sensitive_path_component,
+    list_scan_folders,
+)
+from hub.utils.paths import (
+    exports_root,
+    hf_default_cache_dir,
+    legacy_hf_cache_dir,
+    lmstudio_model_dirs,
+    normalize_path,
+    outputs_root,
+    studio_root,
+    well_known_model_dirs,
+)
+from hub.services.models.common import _safe_is_dir
+from hub.services.models.local_inventory import _resolve_hf_cache_dir
+
+logger = get_logger(__name__)
+
+
+def get_recommended_folders_response() -> dict:
+    """Return well-known model directories that exist on this machine."""
+    folders: list[str] = []
+    seen: set[str] = set()
+
+    def _add(p: Optional[Path]) -> None:
+        if p is None:
+            return
+        try:
+            resolved = str(p.resolve())
+        except OSError:
+            return
+        if resolved in seen:
+            return
+        if _safe_is_dir(resolved) and os.access(resolved, os.R_OK | os.X_OK):
+            seen.add(resolved)
+            folders.append(resolved)
+
+    try:
+        for p in lmstudio_model_dirs():
+            _add(p)
+    except Exception as e:
+        logger.warning("Failed to scan for LM Studio model directories: %s", e)
+
+    ollama_env = os.environ.get("OLLAMA_MODELS")
+    if ollama_env:
+        _add(Path(normalize_path(ollama_env)).expanduser())
+    for candidate in (
+        Path.home() / ".ollama" / "models",
+        Path("/usr/share/ollama/.ollama/models"),
+        Path("/var/lib/ollama/.ollama/models"),
+    ):
+        _add(candidate)
+
+    return {"folders": folders}
+
+
+# Ceiling on children to stat when guessing if a directory holds models.
+_BROWSE_MODEL_HINT_PROBE = 64
+# Hard cap on returned subdirectory entries so pointing at ``/usr/lib`` or
+# ``/proc`` can't stat-storm the process or flood the client.
+_BROWSE_ENTRY_CAP = 2000
+
+
+def _count_model_files(directory: Path, cap: int = 200) -> int:
+    """Count GGUF/safetensors files immediately inside *directory*, bounded by visited entries (not matches) so the hint never costs more than ``cap`` stats."""
+    n = 0
+    visited = 0
+    try:
+        for f in directory.iterdir():
+            visited += 1
+            if visited > cap:
+                break
+            try:
+                if f.is_file():
+                    low = f.name.lower()
+                    if low.endswith((".gguf", ".safetensors")):
+                        n += 1
+            except OSError:
+                continue
+    except PermissionError as e:
+        logger.debug("browse-folders: permission denied counting %s: %s", directory, e)
+        return 0
+    except OSError as e:
+        logger.debug("browse-folders: OS error counting %s: %s", directory, e)
+        return 0
+    return n
+
+
+def _has_direct_model_signal(directory: Path) -> bool:
+    """True if an immediate child signals a model (GGUF/safetensors/config file or ``models--*`` HF-cache subdir); bounded by the hint probe."""
+    try:
+        it = directory.iterdir()
+    except OSError:
+        return False
+    try:
+        for i, child in enumerate(it):
+            if i >= _BROWSE_MODEL_HINT_PROBE:
+                break
+            try:
+                name = child.name
+                if child.is_file():
+                    low = name.lower()
+                    if low.endswith((".gguf", ".safetensors")):
+                        return True
+                    if low in ("config.json", "adapter_config.json"):
+                        return True
+                elif child.is_dir() and name.startswith("models--"):
+                    return True
+            except OSError:
+                continue
+    except OSError:
+        return False
+    return False
+
+
+def _looks_like_model_dir(directory: Path) -> bool:
+    """Bounded heuristic flagging dirs worth exploring (false negatives are fine; the scanner is authoritative). Three signals, cheapest first: a ``models--*`` name, a direct child signal, or a grandchild signal (LM Studio / Ollama ``publisher/model/weights.gguf`` layout)."""
+    if directory.name.startswith("models--"):
+        return True
+    if _has_direct_model_signal(directory):
+        return True
+    try:
+        it = directory.iterdir()
+    except OSError:
+        return False
+    try:
+        for i, child in enumerate(it):
+            if i >= _BROWSE_MODEL_HINT_PROBE:
+                break
+            try:
+                if not child.is_dir():
+                    continue
+            except OSError:
+                continue
+            if child.name.startswith("models--"):
+                return True
+            if _has_direct_model_signal(child):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _build_browse_allowlist() -> list[Path]:
+    """Root directories the browser may walk (also seeds the suggestion chips): HOME, resolved HF cache dirs, Studio outputs/exports/root, registered scan folders, and well-known local-LLM dirs. Each is added only if it resolves to a real directory so the sandbox has no dead boundary."""
+    from hub.storage.scan_folders import list_scan_folders
+
+    candidates: list[Path] = []
+
+    def _add(p: Optional[Path | str]) -> None:
+        if p is None:
+            return
+        try:
+            p = Path(normalize_path(str(p))).expanduser()
+            resolved = p.resolve()
+        except (OSError, RuntimeError, ValueError):
+            return
+        if _safe_is_dir(resolved):
+            candidates.append(resolved)
+
+    _add(Path.home())
+    _add(_resolve_hf_cache_dir())
+    try:
+        _add(hf_default_cache_dir())
+    except Exception:  # noqa: BLE001 -- best-effort
+        pass
+    try:
+        _add(legacy_hf_cache_dir())
+    except Exception:  # noqa: BLE001 -- best-effort
+        pass
+    try:
+        _add(studio_root())
+        _add(outputs_root())
+        _add(exports_root())
+    except Exception as exc:  # noqa: BLE001 -- best-effort
+        logger.debug("browse-folders: studio roots unavailable: %s", exc)
+    try:
+        for folder in list_scan_folders():
+            p = folder.get("path")
+            if p:
+                _add(p)
+    except Exception as exc:  # noqa: BLE001 -- best-effort
+        logger.debug("browse-folders: could not load scan folders: %s", exc)
+    try:
+        for p in well_known_model_dirs():
+            _add(p)
+    except Exception as exc:  # noqa: BLE001 -- best-effort
+        logger.debug("browse-folders: well-known dirs unavailable: %s", exc)
+
+    seen: set[str] = set()
+    deduped: list[Path] = []
+    for p in candidates:
+        key = os.path.normcase(os.path.realpath(str(p)))
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(p)
+    return deduped
+
+
+def _is_path_inside_allowlist(target: Path, allowed_roots: list[Path]) -> bool:
+    """True if *target* equals or descends from any allowed root; uses ``os.path.realpath`` so symlinks cannot escape the sandbox."""
+    try:
+        target_real = os.path.normcase(os.path.realpath(str(target)))
+    except OSError:
+        return False
+    for root in allowed_roots:
+        try:
+            root_real = os.path.normcase(os.path.realpath(str(root)))
+        except OSError:
+            continue
+        try:
+            if os.path.commonpath([target_real, root_real]) == root_real:
+                return True
+        except ValueError:
+            continue
+        if target_real == root_real:
+            return True
+    return False
+
+
+def _normalize_browse_request_path(path: Optional[str], *, relative_root: Path) -> str:
+    """Normalize the browse request path lexically, without touching the FS."""
+    if path is None or not path.strip():
+        return os.path.normpath(str(Path.home()))
+
+    expanded = os.path.expanduser(normalize_path(path.strip()))
+    if not os.path.isabs(expanded):
+        expanded = os.path.join(str(relative_root), expanded)
+    return os.path.normpath(expanded)
+
+
+def _browse_relative_parts(requested_path: str, root: Path) -> Optional[list[str]]:
+    if "\x00" in requested_path:
+        raise HTTPException(
+            status_code = 400,
+            detail = "Path cannot contain null bytes",
+        )
+    root_text = os.path.normcase(os.path.normpath(str(root)))
+    requested_text = os.path.normcase(os.path.normpath(requested_path))
+    try:
+        rel_text = os.path.relpath(requested_text, root_text)
+    except ValueError:
+        return None
+
+    if rel_text == ".":
+        return []
+    if rel_text == ".." or rel_text.startswith(f"..{os.sep}"):
+        return None
+
+    parts = [part for part in rel_text.split(os.sep) if part not in ("", ".")]
+    altsep = os.altsep
+    for part in parts:
+        if part == ".." or "\x00" in part or os.sep in part or (altsep and altsep in part):
+            return None
+    return parts
+
+
+def _match_browse_child(current: Path, name: str) -> Optional[Path]:
+    """Immediate child named ``name`` under ``current``, or None. ``name`` is pre-validated as a safe single component, so the join is O(1); case resolution follows OS filesystem semantics."""
+    child = current / name
+    try:
+        child.stat()
+    except (FileNotFoundError, NotADirectoryError):
+        return None
+    except PermissionError:
+        raise HTTPException(
+            status_code = 403,
+            detail = f"Permission denied reading {current}",
+        ) from None
+    except OSError as exc:
+        raise HTTPException(
+            status_code = 500,
+            detail = f"Could not read {current}: {exc}",
+        ) from exc
+    return child
+
+
+def _resolve_browse_target(path: Optional[str], allowed_roots: list[Path]) -> Path:
+    """Resolve a requested browse path by walking from trusted allowlist roots."""
+    requested_path = _normalize_browse_request_path(path, relative_root = Path.home())
+    resolved_roots: list[Path] = []
+    seen_roots: set[str] = set()
+    for root in sorted(allowed_roots, key = lambda p: len(str(p)), reverse = True):
+        try:
+            resolved = root.resolve()
+        except OSError:
+            continue
+        key = os.path.normcase(os.path.realpath(str(resolved)))
+        if key in seen_roots:
+            continue
+        seen_roots.add(key)
+        resolved_roots.append(resolved)
+
+    for root in resolved_roots:
+        parts = _browse_relative_parts(requested_path, root)
+        if parts is None:
+            continue
+
+        current = root
+        for part in parts:
+            child = _match_browse_child(current, part)
+            if child is None:
+                raise HTTPException(
+                    status_code = 404,
+                    detail = f"Path does not exist: {requested_path}",
+                )
+            try:
+                resolved_child = child.resolve()
+            except OSError as exc:
+                raise HTTPException(
+                    status_code = 400,
+                    detail = f"Invalid path: {exc}",
+                ) from exc
+            if not _is_path_inside_allowlist(resolved_child, resolved_roots):
+                raise HTTPException(
+                    status_code = 403,
+                    detail = (
+                        "Path is not in the browseable allowlist. Register it via "
+                        "POST /api/hub/scan-folders first, or pick a directory "
+                        "under your home folder."
+                    ),
+                )
+            # HOME is in the allowlist, so without this denylist (same one
+            # registration enforces) a user could browse into ~/.ssh, ~/.aws, etc.
+            if contains_sensitive_path_component(str(resolved_child)):
+                raise HTTPException(
+                    status_code = 403,
+                    detail = "Credential or configuration directories are not browseable.",
+                )
+            current = resolved_child
+
+        if not current.is_dir():
+            raise HTTPException(
+                status_code = 400,
+                detail = f"Not a directory: {current}",
+            )
+        return current
+
+    raise HTTPException(
+        status_code = 403,
+        detail = (
+            "Path is not in the browseable allowlist. Register it via "
+            "POST /api/hub/scan-folders first, or pick a directory "
+            "under your home folder."
+        ),
+    )
+
+
+def browse_folders_response(
+    path: Optional[str] = None, show_hidden: bool = False
+) -> BrowseFoldersResponse:
+    """List immediate subdirectories of *path* for the Custom Folders picker.
+
+    Requests are bounded to the :func:`_build_browse_allowlist` roots; paths
+    outside it return 403 (symlinks resolved via realpath first, so traversal
+    can't escape). Sorting: model-bearing dirs first, then plain, then hidden.
+    """
+    from hub.storage.scan_folders import list_scan_folders
+
+    # Build the allowlist once -- the sandbox check and suggestion chips share
+    # it so chips are always navigable.
+    allowed_roots = _build_browse_allowlist()
+
+    try:
+        target = _resolve_browse_target(path, allowed_roots)
+    except HTTPException:
+        requested_path = _normalize_browse_request_path(
+            path,
+            relative_root = Path.home(),
+        )
+        if path is not None and path.strip():
+            logger.warning(
+                "browse-folders: rejected path %r (normalized=%s)",
+                path,
+                requested_path,
+            )
+        raise
+
+    # Enumerate immediate subdirectories with a bounded cap so a stray
+    # query against ``/usr/lib`` or ``/proc`` can't stat-storm the process.
+    entries: list[BrowseEntry] = []
+    truncated = False
+    visited = 0
+    try:
+        it = target.iterdir()
+    except PermissionError:
+        raise HTTPException(
+            status_code = 403,
+            detail = f"Permission denied reading {target}",
+        )
+    except OSError as exc:
+        raise HTTPException(
+            status_code = 500,
+            detail = f"Could not read {target}: {exc}",
+        )
+
+    try:
+        for child in it:
+            # Bound by visited entries, not appended ones, so a directory full
+            # of files still caps work at ``_BROWSE_ENTRY_CAP`` stats.
+            visited += 1
+            if visited > _BROWSE_ENTRY_CAP:
+                truncated = True
+                break
+            try:
+                if not child.is_dir():
+                    continue
+            except OSError:
+                continue
+            name = child.name
+            is_hidden = name.startswith(".")
+            if is_hidden and not show_hidden:
+                continue
+            # Don't surface credential/config dirs even with show_hidden:
+            # descending into them is refused and registration rejects them.
+            if contains_sensitive_path_component(name):
+                continue
+            entries.append(
+                BrowseEntry(
+                    name = name,
+                    has_models = _looks_like_model_dir(child),
+                    hidden = is_hidden,
+                )
+            )
+    except PermissionError as exc:
+        logger.debug(
+            "browse-folders: permission denied during enumeration of %s: %s",
+            target,
+            exc,
+        )
+    except OSError as exc:
+        # Rare: iterdir succeeded but reading a specific entry failed.
+        logger.warning("browse-folders: partial enumeration of %s: %s", target, exc)
+
+    # Model-bearing dirs first, then plain, then hidden; case-insensitive
+    # alphabetical within each bucket.
+    def _sort_key(e: BrowseEntry) -> tuple[int, str]:
+        bucket = 0 if e.has_models else (2 if e.hidden else 1)
+        return (bucket, e.name.lower())
+
+    entries.sort(key = _sort_key)
+
+    # Parent is None at the FS root and when it would step outside the sandbox,
+    # so the up-row never 403s on click.
+    parent: Optional[str]
+    if target.parent == target or not _is_path_inside_allowlist(target.parent, allowed_roots):
+        parent = None
+    else:
+        parent = str(target.parent)
+
+    # Handy starting points for the quick-pick chips.
+    suggestions: list[str] = []
+    seen_sug: set[str] = set()
+
+    def _add_sug(p: Optional[Path | str]) -> None:
+        if p is None:
+            return
+        try:
+            p = Path(normalize_path(str(p))).expanduser()
+            resolved = str(p.resolve())
+        except (OSError, RuntimeError, ValueError):
+            return
+        if resolved in seen_sug:
+            return
+        if _safe_is_dir(resolved):
+            seen_sug.add(resolved)
+            suggestions.append(resolved)
+
+    # Home first as the safe fallback.
+    _add_sug(Path.home())
+    # The HF cache root in use (honors HF_HOME / HF_HUB_CACHE), then the default.
+    try:
+        _add_sug(_resolve_hf_cache_dir())
+    except Exception:
+        pass
+    try:
+        _add_sug(hf_default_cache_dir())
+    except Exception:
+        pass
+    # Already-registered scan folders (what the user has curated).
+    try:
+        for folder in list_scan_folders():
+            _add_sug(folder.get("path", ""))
+    except Exception as exc:
+        logger.debug("browse-folders: could not load scan folders: %s", exc)
+    # Well-known third-party dirs (LM Studio, Ollama, ~/models). Each helper
+    # only returns existing paths so we never show dead chips.
+    try:
+        for p in well_known_model_dirs():
+            _add_sug(p)
+    except Exception as exc:
+        logger.debug("browse-folders: could not load well-known dirs: %s", exc)
+
+    return BrowseFoldersResponse(
+        current = str(target),
+        parent = parent,
+        entries = entries,
+        suggestions = suggestions,
+        truncated = truncated,
+        model_files_here = _count_model_files(target),
+    )
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
new file mode 100644
index 0000000000..efe6bdf6c4
--- /dev/null
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -0,0 +1,643 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF variant resolution."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from collections import OrderedDict
+from typing import NamedTuple, Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.inventory import GgufVariantDetail, GgufVariantsResponse
+from hub.utils import download_manifest
+from hub.utils import download_registry
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.hf_errors import hf_error_status
+from hub.utils.hf_cache_state import (
+    INCOMPLETE_SUFFIX,
+    iter_destructive_repo_cache_dirs,
+)
+from hub.utils.gguf import (
+    extract_quant_label,
+    iter_hf_cache_snapshots,
+    list_gguf_variants,
+    list_gguf_variants_from_hf_cache,
+    list_local_gguf_variants,
+    list_partial_gguf_variants_from_state,
+    pick_best_gguf,
+)
+from hub.utils.paths import (
+    is_local_path,
+    is_valid_repo_id as _is_valid_repo_id,
+)
+from hub.services.models.common import (
+    _is_mmproj_filename,
+    _iter_gguf_paths,
+)
+from hub.utils.gguf_plan import (
+    GgufVariantPlan as _GgufVariantRequirement,
+    build_gguf_variant_plans,
+    is_main_gguf_variant_path,
+)
+
+logger = get_logger(__name__)
+
+_VARIANT_HASH_CACHE: "OrderedDict[tuple[str, str, str, bool], tuple[frozenset[str], float]]" = (
+    OrderedDict()
+)
+_VARIANT_REQUIREMENT_CACHE: "OrderedDict[tuple[str, str, str], tuple[_GgufVariantRequirement, float]]" = OrderedDict()
+_VARIANT_REQUIREMENT_NEG_CACHE: "OrderedDict[tuple[str, str], float]" = OrderedDict()
+_VARIANT_HASH_MAX = 512
+# Blob hashes are derived from the same mutable remote revision metadata as
+# variant requirements, so they must not outlive that freshness window.
+_VARIANT_HASH_POS_TTL = 60.0
+# Refresh resolved variant requirements so a moved repo revision is picked up
+# within the session instead of being pinned for the backend's lifetime.
+_VARIANT_REQUIREMENT_POS_TTL = 60.0
+# Suppress retries on a metadata-fetch failure so a slow/flaky link doesn't
+# re-hammer the API on every page refresh.
+_VARIANT_REQUIREMENT_NEG_TTL = 60.0
+# Fail fast on a slow link so the variant render isn't blocked for seconds.
+_GGUF_METADATA_TIMEOUT_SECONDS = 5.0
+_VARIANT_HASH_LOCK = threading.Lock()
+
+
+class VariantIncompleteDeleteResult(NamedTuple):
+    deleted: int
+    unresolved: bool
+
+
+def _variant_hash_cache_key(
+    repo_id: str, variant: str, hf_token: Optional[str]
+) -> tuple[str, str, str]:
+    return (
+        repo_id.lower(),
+        variant.lower(),
+        hf_cache_scan.token_fingerprint(hf_token),
+    )
+
+
+def _variant_blob_hash_cache_key(
+    repo_id: str, variant: str, hf_token: Optional[str], include_companions: bool
+) -> tuple[str, str, str, bool]:
+    base = _variant_hash_cache_key(repo_id, variant, hf_token)
+    return (*base, include_companions)
+
+
+def _variant_repo_cache_key(repo_id: str, hf_token: Optional[str]) -> tuple[str, str]:
+    return (repo_id.lower(), hf_cache_scan.token_fingerprint(hf_token))
+
+
+def _variant_requirement_neg_cache_active(key: tuple[str, str]) -> bool:
+    with _VARIANT_HASH_LOCK:
+        cached_at = _VARIANT_REQUIREMENT_NEG_CACHE.get(key)
+        if cached_at is None:
+            return False
+        if (time.monotonic() - cached_at) < _VARIANT_REQUIREMENT_NEG_TTL:
+            _VARIANT_REQUIREMENT_NEG_CACHE.move_to_end(key)
+            return True
+        _VARIANT_REQUIREMENT_NEG_CACHE.pop(key, None)
+        return False
+
+
+def _variant_requirement_neg_cache_set(key: tuple[str, str]) -> None:
+    with _VARIANT_HASH_LOCK:
+        _VARIANT_REQUIREMENT_NEG_CACHE[key] = time.monotonic()
+        _VARIANT_REQUIREMENT_NEG_CACHE.move_to_end(key)
+        while len(_VARIANT_REQUIREMENT_NEG_CACHE) > _VARIANT_HASH_MAX:
+            _VARIANT_REQUIREMENT_NEG_CACHE.popitem(last = False)
+
+
+def _variant_requirement_neg_cache_clear(key: tuple[str, str]) -> None:
+    with _VARIANT_HASH_LOCK:
+        _VARIANT_REQUIREMENT_NEG_CACHE.pop(key, None)
+
+
+def _variant_hash_cache_get(key: tuple[str, str, str, bool]) -> Optional[frozenset[str]]:
+    with _VARIANT_HASH_LOCK:
+        cached = _VARIANT_HASH_CACHE.get(key)
+        if cached is None:
+            return None
+        hashes, ts = cached
+        if (time.monotonic() - ts) >= _VARIANT_HASH_POS_TTL:
+            _VARIANT_HASH_CACHE.pop(key, None)
+            return None
+        _VARIANT_HASH_CACHE.move_to_end(key)
+        return hashes
+
+
+def _variant_hash_cache_set(key: tuple[str, str, str, bool], hashes: frozenset[str]) -> None:
+    with _VARIANT_HASH_LOCK:
+        _VARIANT_HASH_CACHE[key] = (hashes, time.monotonic())
+        _VARIANT_HASH_CACHE.move_to_end(key)
+        while len(_VARIANT_HASH_CACHE) > _VARIANT_HASH_MAX:
+            _VARIANT_HASH_CACHE.popitem(last = False)
+
+
+def _variant_requirement_cache_get(key: tuple[str, str, str]) -> Optional[_GgufVariantRequirement]:
+    with _VARIANT_HASH_LOCK:
+        cached = _VARIANT_REQUIREMENT_CACHE.get(key)
+        if cached is None:
+            return None
+        requirement, ts = cached
+        if (time.monotonic() - ts) >= _VARIANT_REQUIREMENT_POS_TTL:
+            _VARIANT_REQUIREMENT_CACHE.pop(key, None)
+            return None
+        _VARIANT_REQUIREMENT_CACHE.move_to_end(key)
+        return requirement
+
+
+def _variant_requirement_cache_set_many(
+    repo_id: str, hf_token: Optional[str], requirements: dict[str, _GgufVariantRequirement]
+) -> None:
+    with _VARIANT_HASH_LOCK:
+        now = time.monotonic()
+        for quant, requirement in requirements.items():
+            key = _variant_hash_cache_key(repo_id, quant, hf_token)
+            _VARIANT_REQUIREMENT_CACHE[key] = (requirement, now)
+            _VARIANT_REQUIREMENT_CACHE.move_to_end(key)
+        while len(_VARIANT_REQUIREMENT_CACHE) > _VARIANT_HASH_MAX:
+            _VARIANT_REQUIREMENT_CACHE.popitem(last = False)
+
+
+def _build_gguf_variant_requirements(siblings: list) -> dict[str, _GgufVariantRequirement]:
+    return build_gguf_variant_plans(siblings)
+
+
+def gguf_variant_requirements(
+    repo_id: str,
+    variant: str,
+    hf_token: Optional[str] = None,
+) -> Optional[_GgufVariantRequirement]:
+    key = _variant_hash_cache_key(repo_id, variant, hf_token)
+    cached = _variant_requirement_cache_get(key)
+    if cached is not None:
+        return cached
+    requirements = _fetch_gguf_variant_requirements(repo_id, hf_token)
+    return requirements.get(variant.lower())
+
+
+def _fetch_gguf_variant_requirements(
+    repo_id: str,
+    hf_token: Optional[str] = None,
+    *,
+    siblings: Optional[list] = None,
+) -> dict[str, _GgufVariantRequirement]:
+    repo_key = _variant_repo_cache_key(repo_id, hf_token)
+    if siblings is None:
+        if _variant_requirement_neg_cache_active(repo_key):
+            return {}
+        try:
+            from huggingface_hub import HfApi
+            info = HfApi(token = hf_token).model_info(
+                repo_id,
+                files_metadata = True,
+                timeout = _GGUF_METADATA_TIMEOUT_SECONDS,
+            )
+        except Exception as e:
+            logger.warning(
+                "model_info failed resolving GGUF files for %s: %s",
+                repo_id,
+                download_registry.scrub_secrets(str(e), hf_token = hf_token),
+            )
+            _variant_requirement_neg_cache_set(repo_key)
+            return {}
+        siblings = list(info.siblings)
+    requirements = _build_gguf_variant_requirements(siblings)
+    if requirements:
+        _variant_requirement_cache_set_many(repo_id, hf_token, requirements)
+    _variant_requirement_neg_cache_clear(repo_key)
+    return requirements
+
+
+def _gguf_all_variant_requirements(
+    repo_id: str,
+    hf_token: Optional[str] = None,
+    *,
+    siblings: Optional[list] = None,
+) -> dict[str, _GgufVariantRequirement]:
+    return _fetch_gguf_variant_requirements(repo_id, hf_token, siblings = siblings)
+
+
+def _manifest_variant_blob_hashes(
+    repo_id: str,
+    variant: str,
+    *,
+    include_companions: bool = True,
+) -> frozenset[str]:
+    manifest = download_manifest.read_manifest("model", repo_id, variant)
+    if manifest is None:
+        return frozenset()
+    variant_key = variant.lower()
+    hashes: set[str] = set()
+    for expected in manifest.expected_files:
+        if not expected.sha256:
+            continue
+        if include_companions:
+            hashes.add(expected.sha256)
+            continue
+        if is_main_gguf_variant_path(expected.path, variant_key):
+            hashes.add(expected.sha256)
+    return frozenset(hashes)
+
+
+def gguf_variant_blob_hashes(
+    repo_id: str,
+    variant: str,
+    hf_token: Optional[str] = None,
+    *,
+    include_companions: bool = True,
+    allow_remote: bool = True,
+) -> frozenset[str]:
+    key = _variant_blob_hash_cache_key(
+        repo_id,
+        variant,
+        hf_token,
+        include_companions,
+    )
+    cached = _variant_hash_cache_get(key)
+    if cached is not None:
+        return cached
+    hashes = _manifest_variant_blob_hashes(
+        repo_id,
+        variant,
+        include_companions = include_companions,
+    )
+    if hashes:
+        _variant_hash_cache_set(key, hashes)
+        return hashes
+    requirement_key = _variant_hash_cache_key(repo_id, variant, hf_token)
+    requirement = _variant_requirement_cache_get(requirement_key)
+    if requirement is None and allow_remote:
+        requirement = gguf_variant_requirements(repo_id, variant, hf_token)
+    if requirement is not None:
+        hashes = requirement.required_hashes if include_companions else requirement.main_hashes
+        if hashes:
+            _variant_hash_cache_set(key, hashes)
+        return hashes
+    return frozenset()
+
+
+def _partial_transport_for_variant(repo_id: str, variant: str) -> Optional[str]:
+    return hf_cache_scan.partial_transport_for("model", repo_id, variant)
+
+
+def delete_variant_incomplete_blobs_result(
+    repo_id: str,
+    variant: str,
+    hf_token: Optional[str],
+    *,
+    extra_hashes: frozenset[str] = frozenset(),
+    companions: bool = True,
+) -> VariantIncompleteDeleteResult:
+    # With a sibling still downloading, ``companions=False`` keeps a shared mmproj
+    # from being unlinked out from under it; the repo's last delete reclaims it.
+    target_hashes = (
+        gguf_variant_blob_hashes(repo_id, variant, hf_token, include_companions = companions)
+        | extra_hashes
+    )
+    if not target_hashes:
+        has_variant_partial_state = hf_cache_scan.is_variant_partial(
+            repo_id,
+            variant,
+            incomplete_blob_hashes = set(),
+            variant_blob_hashes = frozenset(),
+        )
+        has_repo_partials = bool(download_registry.incomplete_blob_hashes("model", repo_id))
+        return VariantIncompleteDeleteResult(
+            deleted = 0,
+            unresolved = has_variant_partial_state and has_repo_partials,
+        )
+    deleted = 0
+    # Destructive iterator: only the exact-case match (or abort if ambiguous),
+    # so a case-variant sibling repo's partials are never unlinked.
+    for entry in iter_destructive_repo_cache_dirs("model", repo_id):
+        blobs_dir = entry / "blobs"
+        if not blobs_dir.is_dir():
+            continue
+        for h in target_hashes:
+            incomplete = blobs_dir / f"{h}{INCOMPLETE_SUFFIX}"
+            if incomplete.exists():
+                try:
+                    incomplete.unlink()
+                    deleted += 1
+                except OSError as e:
+                    logger.warning(f"Failed to unlink {incomplete}: {e}")
+    return VariantIncompleteDeleteResult(deleted = deleted, unresolved = False)
+
+
+async def get_gguf_variants_response(
+    repo_id: str,
+    prefer_local_cache: bool = False,
+    offline: bool = False,
+    local_path: Optional[str] = None,
+    hf_token: Optional[str] = None,
+):
+    """
+    List available GGUF quantization variants for a HuggingFace repo
+    or a local directory (e.g. LM Studio model folder).
+
+    Returns all available quantization variants (Q4_K_M, Q8_0, BF16, etc.)
+    with file sizes, whether the model supports vision, and the recommended
+    default variant.
+    """
+
+    def _compute() -> GgufVariantsResponse:
+        def _local_response(
+            response_repo_id: str, variants, has_vision: bool
+        ) -> GgufVariantsResponse:
+            filenames = [v.filename for v in variants]
+            best = pick_best_gguf(filenames)
+            default_variant = extract_quant_label(best) if best else None
+            return GgufVariantsResponse(
+                repo_id = response_repo_id,
+                variants = [
+                    GgufVariantDetail(
+                        filename = v.filename,
+                        quant = v.quant,
+                        display_label = v.display_label,
+                        size_bytes = v.size_bytes,
+                        download_size_bytes = v.size_bytes,
+                        downloaded = True,
+                    )
+                    for v in variants
+                ],
+                has_vision = has_vision,
+                default_variant = default_variant,
+            )
+
+        def _partial_local_response(
+            response_repo_id: str, variants, has_vision: bool
+        ) -> GgufVariantsResponse:
+            filenames = [v.filename for v in variants]
+            best = pick_best_gguf(filenames)
+            default_variant = extract_quant_label(best) if best else None
+            return GgufVariantsResponse(
+                repo_id = response_repo_id,
+                variants = [
+                    GgufVariantDetail(
+                        filename = v.filename,
+                        quant = v.quant,
+                        display_label = v.display_label,
+                        size_bytes = v.size_bytes,
+                        download_size_bytes = v.download_size_bytes or v.size_bytes,
+                        downloaded = False,
+                        partial = True,
+                        partial_transport = _partial_transport_for_variant(
+                            response_repo_id,
+                            v.quant,
+                        ),
+                    )
+                    for v in variants
+                ],
+                has_vision = has_vision,
+                default_variant = default_variant,
+            )
+
+        # Local directory path (e.g. LM Studio models) — scan filesystem
+        if is_local_path(repo_id):
+            variants, has_vision = list_local_gguf_variants(repo_id)
+
+            return _local_response(repo_id, variants, has_vision)
+
+        # Reject invalid remote repo_ids up front (like download/delete) so a
+        # malformed id returns 400 instead of a 500 from the HF client.
+        if not _is_valid_repo_id(repo_id):
+            raise HTTPException(status_code = 400, detail = f"Invalid repo_id: {repo_id!r}")
+
+        local_only = prefer_local_cache or offline
+        if local_only:
+            cached = list_gguf_variants_from_hf_cache(repo_id)
+            if cached is not None:
+                variants, has_vision = cached
+                return _local_response(repo_id, variants, has_vision)
+            if local_path and is_local_path(local_path):
+                variants, has_vision = list_local_gguf_variants(local_path)
+                if variants or has_vision:
+                    return _local_response(repo_id, variants, has_vision)
+            partial = list_partial_gguf_variants_from_state(repo_id)
+            if partial is not None:
+                variants, has_vision = partial
+                return _partial_local_response(repo_id, variants, has_vision)
+            if local_path and offline:
+                return GgufVariantsResponse(
+                    repo_id = repo_id,
+                    variants = [],
+                    has_vision = False,
+                    default_variant = None,
+                )
+            if offline:
+                raise HTTPException(
+                    status_code = 404,
+                    detail = "No cached GGUF variants available while offline.",
+                )
+
+        try:
+            variants, has_vision, siblings = list_gguf_variants(repo_id, hf_token = hf_token)
+        except Exception:
+            cached = list_gguf_variants_from_hf_cache(repo_id)
+            if cached is not None:
+                variants, has_vision = cached
+                return _local_response(repo_id, variants, has_vision)
+            partial = list_partial_gguf_variants_from_state(repo_id)
+            if partial is not None:
+                variants, has_vision = partial
+                return _partial_local_response(repo_id, variants, has_vision)
+            raise
+
+        filenames = [v.filename for v in variants]
+        best = pick_best_gguf(filenames)
+        default_variant = extract_quant_label(best) if best else None
+
+        # Per-snapshot accounting: a variant counts as present only when one
+        # snapshot holds all its files (split GGUFs need every shard together),
+        # sizes are max across snapshots so shared blobs aren't double-counted,
+        # and keys are lowercased since cache dir casing can differ from repo_id.
+        cached_filenames_by_snapshot: list[dict[str, int]] = []
+        cached_quant_bytes_by_snapshot: list[dict[str, int]] = []
+        if _is_valid_repo_id(repo_id):
+            for snap in iter_hf_cache_snapshots(repo_id):
+                try:
+                    gguf_paths = list(_iter_gguf_paths(snap))
+                except (OSError, RuntimeError, ValueError) as e:
+                    logger.debug("Skipping GGUF cache snapshot %s: %s", snap, e)
+                    continue
+                by_filename: dict[str, int] = {}
+                by_quant: dict[str, int] = {}
+                for f in gguf_paths:
+                    try:
+                        rel = f.relative_to(snap).as_posix()
+                        size = f.stat().st_size
+                    except (OSError, RuntimeError, ValueError) as e:
+                        logger.debug("Skipping GGUF cache file %s: %s", f, e)
+                        continue
+                    key = rel.lower()
+                    by_filename[key] = max(by_filename.get(key, 0), size)
+                    if _is_mmproj_filename(f.name):
+                        continue
+                    q = extract_quant_label(rel).lower()
+                    by_quant[q] = by_quant.get(q, 0) + size
+                if by_filename:
+                    cached_filenames_by_snapshot.append(by_filename)
+                if by_quant:
+                    cached_quant_bytes_by_snapshot.append(by_quant)
+
+        requirements_by_quant = {
+            v.quant.lower(): _variant_requirement_cache_get(
+                _variant_hash_cache_key(repo_id, v.quant, hf_token)
+            )
+            for v in variants
+        }
+        if any(req is None for req in requirements_by_quant.values()):
+            fetched_requirements = _gguf_all_variant_requirements(
+                repo_id, hf_token, siblings = siblings
+            )
+            for v in variants:
+                key = v.quant.lower()
+                if requirements_by_quant.get(key) is None:
+                    requirements_by_quant[key] = fetched_requirements.get(key)
+
+        def _filenames_cached(filenames: frozenset[str], expected_size: int) -> bool:
+            if not filenames:
+                return False
+            wanted = [name.lower() for name in filenames]
+            # All files must live in a single snapshot, not spread across several.
+            for by_filename in cached_filenames_by_snapshot:
+                cached = 0
+                for name in wanted:
+                    size = by_filename.get(name)
+                    if size is None:
+                        break
+                    cached += size
+                else:
+                    return expected_size <= 0 or cached >= expected_size * 0.99
+            return False
+
+        def _any_mmproj_cached(filenames: frozenset[str]) -> bool:
+            return any(
+                by_filename.get(name.lower()) is not None
+                for by_filename in cached_filenames_by_snapshot
+                for name in filenames
+            )
+
+        def _is_fully_downloaded(variant) -> bool:
+            requirement = requirements_by_quant.get(variant.quant.lower())
+            if requirement is None:
+                if variant.size_bytes == 0:
+                    return False
+                quant = variant.quant.lower()
+                # Allow small rounding tolerance (symlinks vs real sizes).
+                return any(
+                    by_quant.get(quant, 0) >= variant.size_bytes * 0.99
+                    for by_quant in cached_quant_bytes_by_snapshot
+                )
+            if not _filenames_cached(
+                requirement.main_filenames,
+                requirement.main_size_bytes,
+            ):
+                return False
+            # Vision repos ship an mmproj adapter per variant. Any mmproj
+            # precision on disk suffices (the loader picks whichever is present);
+            # requiring the API-preferred one would falsely demote variants.
+            if requirement.mmproj_filenames and not _any_mmproj_cached(
+                requirement.mmproj_filenames,
+            ):
+                return False
+            return True
+
+        partial_quants: set[str] = set()
+        partial_quant_transports: dict[str, Optional[str]] = {}
+        try:
+            incomplete_hashes = download_registry.incomplete_blob_hashes("model", repo_id)
+        except Exception as e:
+            logger.warning(f"Failed to compute partial GGUF variants for {repo_id}: {e}")
+            incomplete_hashes = set()
+        scan_snapshot_dir = hf_cache_scan.resolve_snapshot_dir_for_scan("model", repo_id)
+        # Manifest + marker + main incomplete-blob check: catches variants whose
+        # download was cancelled or whose expected shards are missing/undersized.
+        for variant in variants:
+            try:
+                requirement = requirements_by_quant.get(variant.quant.lower())
+                variant_hashes = requirement.main_hashes if requirement is not None else None
+                if variant_hashes is None and incomplete_hashes:
+                    variant_hashes = gguf_variant_blob_hashes(
+                        repo_id,
+                        variant.quant,
+                        hf_token,
+                        include_companions = False,
+                    )
+                if hf_cache_scan.is_variant_partial(
+                    repo_id,
+                    variant.quant,
+                    scan_snapshot_dir,
+                    incomplete_blob_hashes = incomplete_hashes,
+                    variant_blob_hashes = variant_hashes,
+                ):
+                    partial_quants.add(variant.quant)
+                    partial_quant_transports[variant.quant] = _partial_transport_for_variant(
+                        repo_id,
+                        variant.quant,
+                    )
+            except Exception as e:
+                logger.warning(
+                    f"Manifest-based partial check failed for " f"{repo_id}/{variant.quant}: {e}"
+                )
+        if incomplete_hashes:
+            for variant in variants:
+                requirement = requirements_by_quant.get(variant.quant.lower())
+                if requirement is None:
+                    continue
+                if requirement.mmproj_hashes & incomplete_hashes and _filenames_cached(
+                    requirement.main_filenames,
+                    requirement.main_size_bytes,
+                ):
+                    partial_quants.add(variant.quant)
+                    partial_quant_transports.setdefault(
+                        variant.quant,
+                        _partial_transport_for_variant(repo_id, variant.quant),
+                    )
+
+        def _variant_detail(v) -> GgufVariantDetail:
+            is_partial = v.quant in partial_quants
+            requirement = requirements_by_quant.get(v.quant.lower())
+            return GgufVariantDetail(
+                filename = v.filename,
+                quant = v.quant,
+                display_label = v.display_label,
+                size_bytes = v.size_bytes,
+                download_size_bytes = (
+                    requirement.download_size_bytes if requirement is not None else v.size_bytes
+                ),
+                downloaded = _is_fully_downloaded(v) and not is_partial,
+                partial = is_partial,
+                partial_transport = (partial_quant_transports.get(v.quant) if is_partial else None),
+            )
+
+        return GgufVariantsResponse(
+            repo_id = repo_id,
+            variants = [_variant_detail(v) for v in variants],
+            has_vision = has_vision,
+            default_variant = default_variant,
+        )
+
+    try:
+        return await asyncio.to_thread(_compute)
+    except HTTPException:
+        raise
+    except Exception as e:
+        scrubbed = download_registry.scrub_secrets(str(e), hf_token = hf_token)
+        # Client-side HF error (missing repo, gated, bad token): pass the status through.
+        status = hf_error_status(e)
+        if status is not None:
+            raise HTTPException(status_code = status, detail = scrubbed)
+        logger.error("Error listing GGUF variants for %s: %s", repo_id, scrubbed)
+        raise HTTPException(
+            status_code = 500,
+            detail = "Failed to list GGUF variants: " + scrubbed,
+        )
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
new file mode 100644
index 0000000000..6e6a28b919
--- /dev/null
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -0,0 +1,679 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Local model, HF cache, LM Studio, and Ollama inventory services.
+
+Ollama logic lives in :mod:`hub.services.models.ollama`; this module
+orchestrates all on-device sources and exposes the route handlers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import List, Optional
+
+from fastapi import HTTPException
+from loggers import get_logger
+
+from hub.schemas.inventory import LocalModelInfo, LocalModelListResponse, ModelFormat
+from hub.storage.scan_folders import (
+    add_scan_folder,
+    list_scan_folders,
+    remove_scan_folder,
+)
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.paths import (
+    hf_default_cache_dir,
+    legacy_hf_cache_dir,
+    lmstudio_model_dirs,
+    normalize_path,
+    ollama_model_dirs,
+    outputs_root,
+    path_is_same_or_child,
+    studio_root,
+)
+from hub.services.models import common as model_common
+from hub.services.models.ollama import scan_ollama_dir
+
+logger = get_logger(__name__)
+_MAX_MODELS_PER_CUSTOM_FOLDER = 200
+_MAX_CUSTOM_FOLDER_ENTRIES = 2000
+_MODEL_SIGNAL_PROBE_LIMIT = 200
+
+# Local aliases keep the extracted code close to the original implementation.
+_is_model_directory = model_common._is_model_directory
+_local_inventory_id = model_common._local_inventory_id
+_local_model_info = model_common._local_model_info
+_capabilities_for_format = model_common._capabilities_for_format
+_apply_format_aware_partial = model_common._apply_format_aware_partial
+_classify_local_path = model_common._classify_local_path
+_is_main_gguf_filename = model_common._is_main_gguf_filename
+_is_transformers_bin_weight_file = model_common._is_transformers_bin_weight_file
+_prefer_complete_larger = model_common._prefer_complete_larger
+_gguf_variant_state_summary = model_common._gguf_variant_state_summary
+
+
+def _is_immediate_model_weight_file(path: Path) -> bool:
+    suffix = path.suffix.lower()
+    if suffix == ".safetensors":
+        return True
+    if suffix == ".gguf":
+        return _is_main_gguf_filename(path.name)
+    if suffix == ".bin":
+        return _is_transformers_bin_weight_file(path)
+    return False
+
+
+def _has_immediate_model_weight(
+    path: Path, *, probe_limit: int = _MODEL_SIGNAL_PROBE_LIMIT
+) -> bool:
+    try:
+        for index, entry in enumerate(path.iterdir(), start = 1):
+            if index > probe_limit:
+                break
+            try:
+                if entry.is_file() and _is_immediate_model_weight_file(entry):
+                    return True
+            except OSError:
+                continue
+    except OSError:
+        return False
+    return False
+
+
+def _has_immediate_model_signal(
+    path: Path, *, probe_limit: int = _MODEL_SIGNAL_PROBE_LIMIT
+) -> bool:
+    try:
+        if (path / "config.json").exists() or (path / "adapter_config.json").exists():
+            return True
+    except OSError:
+        return False
+    return _has_immediate_model_weight(path, probe_limit = probe_limit)
+
+
+def _is_model_directory_for_scan(path: Path, *, entry_limit: int | None) -> bool:
+    if entry_limit is None:
+        return _is_model_directory(path)
+    try:
+        has_config = (path / "config.json").exists() or (path / "adapter_config.json").exists()
+    except OSError:
+        return False
+    return has_config and _has_immediate_model_weight(path)
+
+
+def _resolve_hf_cache_dir() -> Path:
+    try:
+        from huggingface_hub.constants import HF_HUB_CACHE
+        return Path(HF_HUB_CACHE)
+    except Exception:
+        return Path.home() / ".cache" / "huggingface" / "hub"
+
+
+def _scan_models_dir(
+    models_dir: Path,
+    *,
+    limit: int | None = None,
+    entry_limit: int | None = None,
+) -> List[LocalModelInfo]:
+    if not models_dir.exists() or not models_dir.is_dir():
+        return []
+
+    _is_self_model = _is_model_directory_for_scan(
+        models_dir,
+        entry_limit = entry_limit,
+    )
+
+    if _is_self_model:
+        try:
+            updated_at = models_dir.stat().st_mtime
+        except OSError:
+            updated_at = None
+        return _classify_local_path(
+            models_dir,
+            "models_dir",
+            updated_at = updated_at,
+        )
+
+    found: List[LocalModelInfo] = []
+    visited = 0
+    try:
+        children = models_dir.iterdir()
+    except OSError:
+        return found
+    for child in children:
+        if limit is not None and len(found) >= limit:
+            break
+        visited += 1
+        if entry_limit is not None and visited > entry_limit:
+            break
+        try:
+            is_dir = child.is_dir()
+            is_gguf_file = not is_dir and child.suffix.lower() == ".gguf" and child.is_file()
+            if not is_dir and not is_gguf_file:
+                continue
+            has_model_files = is_gguf_file or _has_immediate_model_signal(child)
+        except OSError:
+            # Skip individual children that are unreadable (permissions, broken
+            # symlinks, etc.) rather than failing the entire scan.
+            continue
+        if not has_model_files:
+            continue
+        try:
+            updated_at = child.stat().st_mtime
+        except OSError:
+            updated_at = None
+        rows = _classify_local_path(
+            child,
+            "models_dir",
+            updated_at = updated_at,
+        )
+        if limit is not None:
+            rows = rows[: max(0, limit - len(found))]
+        found.extend(rows)
+
+    return found
+
+
+def _hf_repo_dir_has_content(repo_dir: Path) -> bool:
+    blobs_dir = repo_dir / "blobs"
+    if not blobs_dir.is_dir():
+        return False
+    try:
+        for entry in blobs_dir.iterdir():
+            if entry.is_file() or entry.is_symlink():
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _scan_hf_cache(cache_dir: Path, *, entry_limit: int | None = None) -> List[LocalModelInfo]:
+    if not cache_dir.exists() or not cache_dir.is_dir():
+        return []
+
+    discovered: List[tuple[Path, str, Optional[float]]] = []
+    visited = 0
+    try:
+        entries = cache_dir.iterdir()
+    except OSError:
+        return []
+    for repo_dir in entries:
+        visited += 1
+        if entry_limit is not None and visited > entry_limit:
+            break
+        if not repo_dir.name.startswith("models--"):
+            continue
+        if not repo_dir.is_dir():
+            continue
+        if not _hf_repo_dir_has_content(repo_dir):
+            continue
+        repo_name = repo_dir.name[len("models--") :]
+        if not repo_name:
+            continue
+        model_id = repo_name.replace("--", "/")
+        try:
+            updated_at = repo_dir.stat().st_mtime
+        except OSError:
+            updated_at = None
+        discovered.append((repo_dir, model_id, updated_at))
+
+    found: list[LocalModelInfo] = []
+    for repo_dir, model_id, updated_at in discovered:
+        snapshot_partial = hf_cache_scan.is_snapshot_partial(
+            "model",
+            model_id,
+            repo_dir,
+        )
+        gguf_partial = hf_cache_scan.is_gguf_repo_partial(model_id, repo_dir)
+        has_gguf_variant_state, gguf_variant_state_size = _gguf_variant_state_summary(model_id)
+        snapshot_partial_transport = (
+            hf_cache_scan.partial_transport_for(
+                "model",
+                model_id,
+                repo_cache_dir = repo_dir,
+            )
+            if snapshot_partial
+            else None
+        )
+        resolved = hf_cache_scan.resolve_hf_cache_realpath(repo_dir)
+        scan_path = Path(resolved) if resolved else repo_dir
+        # partial=False here; _apply_format_aware_partial below rewrites per-row
+        # so a hybrid repo's gguf row doesn't taint its safetensors row.
+        rows = _classify_local_path(
+            scan_path,
+            "hf_cache",
+            load_path = repo_dir,
+            display_name = model_id.split("/")[-1],
+            model_id = model_id,
+            updated_at = updated_at,
+            partial = False,
+        )
+        if not rows:
+            if has_gguf_variant_state and gguf_partial:
+                rows = [
+                    _local_model_info(
+                        scan_path = repo_dir,
+                        load_path = repo_dir,
+                        source = "hf_cache",
+                        model_format = "gguf",
+                        display_name = model_id.split("/")[-1],
+                        model_id = model_id,
+                        updated_at = updated_at,
+                        partial = True,
+                        requires_variant = True,
+                        size_bytes = gguf_variant_state_size,
+                    )
+                ]
+            else:
+                # Fallback row's model_format is "unknown"; either signal
+                # applies because we can't dispatch to a specific predicate.
+                rows = [
+                    _local_model_info(
+                        scan_path = repo_dir,
+                        load_path = repo_dir,
+                        source = "hf_cache",
+                        model_format = "unknown",
+                        display_name = model_id.split("/")[-1],
+                        model_id = model_id,
+                        updated_at = updated_at,
+                        partial = snapshot_partial or gguf_partial,
+                    )
+                ]
+        elif (
+            has_gguf_variant_state
+            and gguf_partial
+            and not any(row.model_format == "gguf" for row in rows)
+        ):
+            rows.append(
+                _local_model_info(
+                    scan_path = repo_dir,
+                    load_path = repo_dir,
+                    source = "hf_cache",
+                    model_format = "gguf",
+                    display_name = model_id.split("/")[-1],
+                    model_id = model_id,
+                    updated_at = updated_at,
+                    partial = True,
+                    requires_variant = True,
+                    size_bytes = gguf_variant_state_size,
+                )
+            )
+        rows = _apply_format_aware_partial(
+            rows,
+            snapshot_partial = snapshot_partial,
+            gguf_partial = gguf_partial,
+            snapshot_partial_transport = snapshot_partial_transport,
+        )
+        found.extend(rows)
+    return found
+
+
+def _scan_lmstudio_dir(lm_dir: Path, *, entry_limit: int | None = None) -> List[LocalModelInfo]:
+    """Scan an LM Studio models dir (``publisher/model-name`` folders of GGUFs, or top-level standalone GGUFs)."""
+    if not lm_dir.exists() or not lm_dir.is_dir():
+        return []
+
+    # If the dir is itself a model dir (config + weights), it's not an LM Studio
+    # publisher structure -- return it as a single entry rather than descend.
+    if _is_model_directory(lm_dir):
+        try:
+            updated_at = lm_dir.stat().st_mtime
+        except OSError:
+            updated_at = None
+        return _classify_local_path(
+            lm_dir,
+            "lmstudio",
+            updated_at = updated_at,
+        )
+
+    found: List[LocalModelInfo] = []
+    visited = 0
+    exhausted = False
+
+    def _consume_visit() -> bool:
+        nonlocal visited
+        visited += 1
+        return entry_limit is not None and visited > entry_limit
+
+    try:
+        children = lm_dir.iterdir()
+    except OSError:
+        return found
+    for child in children:
+        if _consume_visit():
+            break
+        try:
+            if not child.is_dir():
+                if child.suffix == ".gguf" and child.is_file():
+                    try:
+                        updated_at = child.stat().st_mtime
+                    except OSError:
+                        updated_at = None
+                    found.extend(
+                        _classify_local_path(
+                            child,
+                            "lmstudio",
+                            updated_at = updated_at,
+                        )
+                    )
+                continue
+
+            # Child is itself a model dir: surface it directly, not as a publisher.
+            if _is_model_directory(child):
+                try:
+                    updated_at = child.stat().st_mtime
+                except OSError:
+                    updated_at = None
+                found.extend(
+                    _classify_local_path(
+                        child,
+                        "lmstudio",
+                        updated_at = updated_at,
+                    )
+                )
+                continue
+
+            # child is a publisher directory -- scan its sub-directories
+            for model_dir in child.iterdir():
+                if _consume_visit():
+                    exhausted = True
+                    break
+                try:
+                    if model_dir.is_dir():
+                        has_model = _has_immediate_model_signal(model_dir)
+                        if not has_model:
+                            continue
+                        model_id = f"{child.name}/{model_dir.name}"
+                        try:
+                            updated_at = model_dir.stat().st_mtime
+                        except OSError:
+                            updated_at = None
+                        found.extend(
+                            _classify_local_path(
+                                model_dir,
+                                "lmstudio",
+                                display_name = model_dir.name,
+                                model_id = model_id,
+                                updated_at = updated_at,
+                            )
+                        )
+                    elif model_dir.suffix == ".gguf" and model_dir.is_file():
+                        try:
+                            updated_at = model_dir.stat().st_mtime
+                        except OSError:
+                            updated_at = None
+                        found.extend(
+                            _classify_local_path(
+                                model_dir,
+                                "lmstudio",
+                                model_id = f"{child.name}/{model_dir.stem}",
+                                updated_at = updated_at,
+                            )
+                        )
+                except OSError:
+                    continue
+            if exhausted:
+                break
+        except OSError:
+            continue
+    return found
+
+
+def _resolve_allowed_models_dir(models_dir: str, allowed_roots: list[Path]) -> Path:
+    """Resolve a requested model scan directory without widening subpaths."""
+    if not models_dir or not models_dir.strip():
+        raise ValueError("Directory not allowed")
+
+    requested = Path(os.path.realpath(os.path.expanduser(normalize_path(models_dir.strip()))))
+    if any(path_is_same_or_child(requested, root) for root in allowed_roots):
+        return requested
+
+    raise ValueError("Directory not allowed")
+
+
+def _coerce_scan_folder_path(raw_path: str) -> str:
+    """Normalize a scan registration target; the registry stores directories, so a pasted weight-file path is reduced to its parent folder."""
+    if not raw_path or not raw_path.strip():
+        raise ValueError("Path cannot be empty")
+    raw = raw_path.strip()
+    if "\x00" in raw:
+        raise ValueError("Path cannot contain null bytes")
+
+    def normalize(value: str) -> Path:
+        return Path(os.path.realpath(os.path.expanduser(normalize_path(value))))
+
+    try:
+        normalized = normalize(raw)
+    except (OSError, ValueError) as e:
+        raise ValueError(f"Path is not readable: {e}") from e
+    try:
+        exists = normalized.exists()
+        is_dir = normalized.is_dir()
+        is_file = normalized.is_file()
+    except (OSError, ValueError) as e:
+        raise ValueError(f"Path is not readable: {e}") from e
+
+    if not exists and "\\" in raw:
+        try:
+            slash_normalized = normalize(raw.replace("\\", "/"))
+            slash_exists = slash_normalized.exists()
+        except (OSError, ValueError) as e:
+            raise ValueError(f"Path is not readable: {e}") from e
+        if slash_exists:
+            normalized = slash_normalized
+            try:
+                is_dir = normalized.is_dir()
+                is_file = normalized.is_file()
+            except (OSError, ValueError) as e:
+                raise ValueError(f"Path is not readable: {e}") from e
+            exists = True
+
+    if not exists:
+        return str(normalized)
+    if is_dir:
+        return str(normalized)
+    if is_file:
+        suffix = normalized.suffix.lower()
+        if suffix not in {".gguf", ".safetensors", ".bin"}:
+            raise ValueError("Path must be a folder or model weight file")
+        return str(normalized.parent)
+    return str(normalized)
+
+
+async def _scan_source(label: str, scanner, path: Path) -> List[LocalModelInfo]:
+    try:
+        return await asyncio.to_thread(scanner, path)
+    except Exception as e:
+        logger.warning("Skipping %s scan for %s: %s", label, path, e)
+        return []
+
+
+async def _collect_models_from_default_sources(
+    models_root: Path,
+    hf_cache_dir: Path,
+    legacy_hf: Path,
+    hf_default: Path,
+    lm_dirs: list[Path],
+    ollama_dirs: list[Path],
+) -> List[LocalModelInfo]:
+    local_models = await _scan_source("models directory", _scan_models_dir, models_root)
+    local_models += await _scan_source("HF cache", _scan_hf_cache, hf_cache_dir)
+
+    if legacy_hf.is_dir() and legacy_hf.resolve() != hf_cache_dir.resolve():
+        local_models += await _scan_source("legacy HF cache", _scan_hf_cache, legacy_hf)
+
+    if (
+        hf_default.is_dir()
+        and hf_default.resolve() != hf_cache_dir.resolve()
+        and hf_default.resolve() != legacy_hf.resolve()
+    ):
+        local_models += await _scan_source("default HF cache", _scan_hf_cache, hf_default)
+
+    for lm_dir in lm_dirs:
+        local_models += await _scan_source("LM Studio", _scan_lmstudio_dir, lm_dir)
+
+    for ollama_dir in ollama_dirs:
+        local_models += await _scan_source("Ollama", scan_ollama_dir, ollama_dir)
+
+    return local_models
+
+
+def _scan_custom_folder(folder_path: Path) -> List[LocalModelInfo]:
+    supported_formats: set[ModelFormat] = {"gguf", "safetensors", "adapter"}
+    generic = [
+        m
+        for m in (
+            _scan_models_dir(
+                folder_path,
+                limit = _MAX_MODELS_PER_CUSTOM_FOLDER,
+                entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
+            )
+            + _scan_hf_cache(folder_path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES)
+            + _scan_lmstudio_dir(folder_path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES)
+        )
+        if m.model_format in supported_formats
+        if not any(p in (".studio_links", "ollama_links") for p in Path(m.path).parts)
+    ]
+    return generic[:_MAX_MODELS_PER_CUSTOM_FOLDER]
+
+
+def _promote_to_custom_source(model: LocalModelInfo) -> LocalModelInfo:
+    if model.source == "hf_cache":
+        return model
+    return model.model_copy(
+        update = {
+            "source": "custom",
+            "model_id": None,
+            "inventory_id": _local_inventory_id(
+                "custom",
+                model.model_format,
+                model.path,
+                model.format_variant,
+            ),
+            "capabilities": _capabilities_for_format(
+                model.model_format,
+                "custom",
+                partial = model.partial,
+                requires_variant = model.capabilities.requires_variant,
+            ),
+        }
+    )
+
+
+async def _collect_models_from_custom_folders() -> List[LocalModelInfo]:
+    try:
+        custom_folders = await asyncio.to_thread(list_scan_folders)
+    except Exception as e:
+        logger.warning("Could not load custom scan folders: %s", e)
+        return []
+
+    local_models: List[LocalModelInfo] = []
+    for folder in custom_folders:
+        folder_path = Path(normalize_path(folder["path"])).expanduser()
+        try:
+            custom_models = await asyncio.to_thread(_scan_custom_folder, folder_path)
+        except Exception as e:
+            logger.warning("Skipping unreadable scan folder %s: %s", folder_path, e)
+            continue
+        local_models.extend(_promote_to_custom_source(m) for m in custom_models)
+    return local_models
+
+
+def _dedupe_local_models(local_models: List[LocalModelInfo]) -> list[LocalModelInfo]:
+    deduped: dict[str, LocalModelInfo] = {}
+    for model in local_models:
+        if model.source == "hf_cache" and model.model_id:
+            key = "\x00".join(
+                (
+                    "hf_cache",
+                    model.model_id.strip().lower(),
+                    model.model_format,
+                    model.format_variant or "",
+                )
+            )
+        else:
+            row_key = model.inventory_id or model.id
+            key = f"{row_key}\x00custom" if model.source == "custom" else row_key
+        existing = deduped.get(key)
+        if existing is None or _prefer_complete_larger(
+            model.partial,
+            model.size_bytes,
+            existing.partial,
+            existing.size_bytes,
+        ):
+            deduped[key] = model
+    return sorted(
+        deduped.values(),
+        key = lambda item: (item.updated_at or 0),
+        reverse = True,
+    )
+
+
+async def list_local_models_response(models_dir: str = "./models") -> LocalModelListResponse:
+    """List local model candidates from every supported on-device source."""
+    hf_cache_dir = _resolve_hf_cache_dir()
+    legacy_hf = legacy_hf_cache_dir()
+    hf_default = hf_default_cache_dir()
+    lm_dirs = lmstudio_model_dirs()
+    ollama_dirs = ollama_model_dirs()
+
+    allowed_roots: list[Path] = [Path("./models").resolve(), hf_cache_dir]
+    if legacy_hf.is_dir():
+        allowed_roots.append(legacy_hf)
+    if hf_default.is_dir():
+        allowed_roots.append(hf_default)
+    allowed_roots.extend([studio_root(), outputs_root()])
+
+    try:
+        models_root = _resolve_allowed_models_dir(models_dir, allowed_roots)
+    except ValueError:
+        raise HTTPException(status_code = 403, detail = "Directory not allowed")
+
+    try:
+        local_models = await _collect_models_from_default_sources(
+            models_root,
+            hf_cache_dir,
+            legacy_hf,
+            hf_default,
+            lm_dirs,
+            ollama_dirs,
+        )
+        local_models += await _collect_models_from_custom_folders()
+        models = _dedupe_local_models(local_models)
+
+        return LocalModelListResponse(
+            models_dir = str(models_root),
+            hf_cache_dir = str(hf_cache_dir),
+            lmstudio_dirs = [str(d) for d in lm_dirs],
+            ollama_dirs = [str(d) for d in ollama_dirs],
+            models = models,
+        )
+    except Exception as e:
+        logger.error(f"Error listing local models: {e}", exc_info = True)
+        raise HTTPException(
+            status_code = 500,
+            detail = f"Failed to list local models: {str(e)}",
+        )
+
+
+def get_scan_folders_response() -> dict:
+    return {"folders": list_scan_folders()}
+
+
+def add_scan_folder_response(path: str) -> dict:
+    try:
+        folder = add_scan_folder(_coerce_scan_folder_path(path))
+    except ValueError as e:
+        logger.warning("Scan folder rejected: %s (path=%s)", e, path)
+        raise HTTPException(status_code = 400, detail = str(e))
+    logger.info("Scan folder added: %s", folder.get("path"))
+    return folder
+
+
+def remove_scan_folder_response(folder_id: int) -> dict:
+    remove_scan_folder(folder_id)
+    logger.info("Scan folder removed: id=%s", folder_id)
+    return {"ok": True}
diff --git a/studio/backend/hub/services/models/ollama.py b/studio/backend/hub/services/models/ollama.py
new file mode 100644
index 0000000000..96a4114620
--- /dev/null
+++ b/studio/backend/hub/services/models/ollama.py
@@ -0,0 +1,394 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Ollama model inventory: manifest parsing and writable-symlink materialization.
+
+Ollama stores models content-addressed under ``<root>/manifests/`` and
+``<root>/blobs/``. Inventory scans read the manifests directly (no writes),
+returning rows whose ``id`` is an opaque ``ollama-manifest:`` reference. The
+load path then calls :func:`materialize_ollama_model_ref`, which creates a
+``.gguf``-named symlink (or hardlink) so that downstream loaders see a path
+with the GGUF suffix without copying multi-GB blobs inside an API request.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import uuid
+from pathlib import Path
+from typing import List, Optional
+from urllib.parse import quote, unquote
+
+from loggers import get_logger
+
+from hub.schemas.inventory import LocalModelInfo
+from hub.services.models.common import (
+    _capabilities_for_format,
+    _local_inventory_id,
+)
+from hub.utils.paths import (
+    cache_root,
+    ollama_model_dirs,
+    path_is_same_or_child,
+    tmp_root,
+)
+
+logger = get_logger(__name__)
+
+_OLLAMA_MANIFEST_REF_PREFIX = "ollama-manifest:"
+_OLLAMA_BLOB_NAME_CHARS = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._+-"
+)
+
+
+def _ollama_manifest_ref(tag_file: Path) -> str:
+    return f"{_OLLAMA_MANIFEST_REF_PREFIX}{quote(str(tag_file), safe = '')}"
+
+
+def _safe_is_file(path: Path) -> bool:
+    try:
+        return path.is_file()
+    except OSError:
+        return False
+
+
+def _ollama_blob_path(blobs_dir: Path, digest: object) -> Optional[Path]:
+    if not isinstance(digest, str):
+        return None
+    algorithm, separator, value = digest.partition(":")
+    if separator != ":" or not algorithm or not value:
+        return None
+    name = f"{algorithm}-{value}"
+    if (
+        not name
+        or name in (".", "..")
+        or any(char not in _OLLAMA_BLOB_NAME_CHARS for char in name)
+        or not name.isprintable()
+    ):
+        return None
+    return blobs_dir / name
+
+
+def _contained_link_path(link_dir: Path, link_name: str) -> Optional[Path]:
+    """Resolve *link_name* to a direct child of *link_dir*, or ``None``. ``link_name`` derives from manifest fields, so requiring a direct child keeps a crafted value with separators, ``..``, or a drive prefix from escaping the links dir."""
+    if not link_name or link_name in (".", ".."):
+        return None
+    link_path = link_dir / link_name
+    try:
+        if link_path.parent.resolve() != link_dir.resolve():
+            return None
+    except OSError:
+        return None
+    return link_path
+
+
+def _ollama_links_dir(ollama_dir: Path) -> Optional[Path]:
+    """Writable directory for Ollama ``.gguf`` symlinks. Prefers ``<ollama_dir>/.studio_links/`` next to the blobs; falls back to Studio's cache (read-only system installs), then the temp dir (sandboxed installs)."""
+
+    def _ensure_writable_dir(path: Path) -> Optional[Path]:
+        try:
+            path.mkdir(parents = True, exist_ok = True)
+            probe = path / f".write-test-{uuid.uuid4().hex[:8]}"
+            probe.mkdir()
+            probe.rmdir()
+            return path
+        except OSError as e:
+            logger.debug("Ollama link dir %s is not writable: %s", path, e)
+            return None
+
+    primary = ollama_dir / ".studio_links"
+    if _ensure_writable_dir(primary) is not None:
+        return primary
+
+    # Namespace by a hash of the ollama_dir so two different Ollama roots
+    # don't collide. This is a cache path, not a security boundary.
+    try:
+        digest = hashlib.sha256(str(ollama_dir.resolve()).encode()).hexdigest()[:12]
+    except (OSError, RuntimeError):
+        digest = "default"
+
+    fallback = cache_root() / "ollama_links" / digest
+    if _ensure_writable_dir(fallback) is not None:
+        return fallback
+
+    tmp_fallback = tmp_root() / "ollama_links" / digest
+    if _ensure_writable_dir(tmp_fallback) is not None:
+        return tmp_fallback
+
+    logger.warning(
+        "Could not create a writable Ollama link directory for %s",
+        ollama_dir,
+    )
+    return None
+
+
+def _make_ollama_blob_link(link_dir: Path, link_name: str, target: Path) -> Optional[str]:
+    """Create a .gguf-named link to an Ollama blob: tries symlink then hardlink, skips the model if neither works (a full multi-GB copy would block the API). Idempotent."""
+    try:
+        link_dir.mkdir(parents = True, exist_ok = True)
+    except OSError as e:
+        logger.warning(
+            "Could not create Ollama link directory %s: %s",
+            link_dir,
+            e,
+        )
+        return None
+    link_path = _contained_link_path(link_dir, link_name)
+    if link_path is None:
+        logger.warning("Refusing unsafe Ollama link name %r under %s", link_name, link_dir)
+        return None
+    try:
+        resolved = target.resolve()
+    except OSError as e:
+        logger.debug("Could not resolve Ollama blob %s: %s", target, e)
+        return None
+
+    # Skip if the link already points at the same blob. Use samefile, not size:
+    # `ollama pull` can swap a tag to a same-sized blob, leaving a stale link.
+    try:
+        if link_path.exists() and os.path.samefile(str(link_path), str(resolved)):
+            return str(link_path)
+    except OSError as e:
+        logger.debug("Error checking existing link %s: %s", link_path, e)
+
+    tmp_path = link_dir / f".{link_name}.tmp-{uuid.uuid4().hex[:8]}"
+    try:
+        if tmp_path.is_symlink() or tmp_path.exists():
+            tmp_path.unlink()
+        try:
+            tmp_path.symlink_to(resolved)
+        except OSError:
+            try:
+                os.link(str(resolved), str(tmp_path))
+            except OSError:
+                logger.warning(
+                    "Could not create link for Ollama blob %s "
+                    "(symlinks and hardlinks both failed). "
+                    "Skipping model to avoid blocking the API.",
+                    target,
+                )
+                return None
+        os.replace(str(tmp_path), str(link_path))
+        return str(link_path)
+    except OSError as e:
+        logger.debug("Could not create Ollama link %s: %s", link_path, e)
+        try:
+            if tmp_path.is_symlink() or tmp_path.exists():
+                tmp_path.unlink()
+        except OSError as cleanup_err:
+            logger.debug("Could not clean up tmp path %s: %s", tmp_path, cleanup_err)
+        return None
+
+
+def _ollama_model_info_from_manifest(
+    ollama_dir: Path,
+    tag_file: Path,
+    *,
+    materialize_links: bool = False,
+    links_root: Optional[Path] = None,
+) -> Optional[LocalModelInfo]:
+    manifests_root = ollama_dir / "manifests"
+    blobs_dir = ollama_dir / "blobs"
+
+    try:
+        rel = tag_file.relative_to(manifests_root)
+    except ValueError:
+        return None
+    parts = rel.parts
+    if len(parts) < 3:
+        return None
+
+    host = parts[0]
+    repo_parts = list(parts[1:-1])
+    tag = parts[-1]
+
+    if host == "registry.ollama.ai" and repo_parts and repo_parts[0] == "library":
+        repo_name = "/".join(repo_parts[1:])
+    elif host == "registry.ollama.ai":
+        repo_name = "/".join(repo_parts)
+    else:
+        repo_name = "/".join([host] + repo_parts)
+
+    if not repo_name:
+        return None
+
+    try:
+        manifest = json.loads(tag_file.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        logger.debug("Skipping unreadable/invalid Ollama manifest %s: %s", tag_file, e)
+        return None
+
+    config = manifest.get("config", {})
+    config_digest = config.get("digest", "") if isinstance(config, dict) else ""
+    model_type = ""
+    file_type = ""
+    if config_digest and blobs_dir.is_dir():
+        config_blob = _ollama_blob_path(blobs_dir, config_digest)
+        if config_blob is not None and _safe_is_file(config_blob):
+            try:
+                cfg = json.loads(config_blob.read_text())
+                model_type = cfg.get("model_type", "")
+                file_type = cfg.get("file_type", "")
+            except (json.JSONDecodeError, OSError) as e:
+                logger.debug("Could not parse Ollama config blob %s: %s", config_blob, e)
+
+    layers = manifest.get("layers") or []
+    if not isinstance(layers, list):
+        return None
+
+    model_blob: Optional[Path] = None
+    gguf_link_path: Optional[str] = None
+    stem_hash = hashlib.sha256(rel.as_posix().encode()).hexdigest()[:10]
+    model_link_dir = links_root / stem_hash if links_root is not None else None
+    safe_name = repo_name.replace("/", "-")
+    quant = f"-{file_type}" if file_type else ""
+
+    for layer in layers:
+        if not isinstance(layer, dict):
+            continue
+        media = layer.get("mediaType", "")
+        digest = layer.get("digest", "")
+        if not digest:
+            continue
+
+        if media == "application/vnd.ollama.image.model":
+            candidate = _ollama_blob_path(blobs_dir, digest)
+            if candidate is None or not _safe_is_file(candidate):
+                continue
+            model_blob = candidate
+            if materialize_links and model_link_dir is not None:
+                link_name = f"{safe_name}-{tag}{quant}.gguf"
+                gguf_link_path = _make_ollama_blob_link(model_link_dir, link_name, candidate)
+
+        elif materialize_links and media == "application/vnd.ollama.image.projector":
+            candidate = _ollama_blob_path(blobs_dir, digest)
+            if candidate is not None and _safe_is_file(candidate) and model_link_dir is not None:
+                mmproj_name = f"{safe_name}-{tag}-mmproj.gguf"
+                _make_ollama_blob_link(model_link_dir, mmproj_name, candidate)
+
+    if model_blob is None:
+        return None
+    if materialize_links and not gguf_link_path:
+        return None
+
+    suffix = ""
+    if model_type:
+        suffix += f" ({model_type}"
+        if file_type:
+            suffix += f" {file_type}"
+        suffix += ")"
+
+    try:
+        updated_at = tag_file.stat().st_mtime
+    except OSError:
+        updated_at = None
+
+    display = f"{repo_name}:{tag}"
+    model_id = f"ollama/{repo_name}:{tag}"
+    path = gguf_link_path if materialize_links and gguf_link_path else str(model_blob)
+    load_id = path if materialize_links else _ollama_manifest_ref(tag_file)
+    return LocalModelInfo(
+        id = load_id,
+        inventory_id = _local_inventory_id("ollama", "gguf", model_id),
+        load_id = load_id,
+        model_id = model_id,
+        display_name = display + suffix,
+        path = path,
+        source = "ollama",
+        updated_at = updated_at,
+        model_format = "gguf",
+        runtime = "llama_cpp",
+        capabilities = _capabilities_for_format("gguf", "ollama"),
+    )
+
+
+def scan_ollama_dir(
+    ollama_dir: Path,
+    *,
+    limit: Optional[int] = None,
+    materialize_links: bool = False,
+) -> List[LocalModelInfo]:
+    """Scan an Ollama models directory for downloaded models.
+
+    Ollama uses a content-addressable layout
+    (``manifests/<host>/<namespace>/<model>/<tag>`` + ``blobs/sha256-...``),
+    iterated via ``rglob`` to find every depth. Each manifest's ``model`` layer
+    holds the GGUF weights (vision models add a projector layer).
+
+    Scans are read-only by default and return an opaque manifest reference;
+    the load route later calls :func:`materialize_ollama_model_ref` to create a
+    ``.gguf`` symlink/hardlink, keeping GET /local free of filesystem writes.
+    """
+    manifests_root = ollama_dir / "manifests"
+    if not manifests_root.is_dir():
+        return []
+
+    found: List[LocalModelInfo] = []
+    links_root = _ollama_links_dir(ollama_dir) if materialize_links else None
+    if materialize_links and links_root is None:
+        logger.warning(
+            "Skipping Ollama scan for %s: no writable location for .gguf links",
+            ollama_dir,
+        )
+        return []
+
+    try:
+        for tag_file in manifests_root.rglob("*"):
+            if not _safe_is_file(tag_file):
+                continue
+
+            info = _ollama_model_info_from_manifest(
+                ollama_dir,
+                tag_file,
+                materialize_links = materialize_links,
+                links_root = links_root,
+            )
+            if info is None:
+                continue
+            found.append(info)
+            if limit is not None and len(found) >= limit:
+                return found
+    except OSError as e:
+        logger.warning("Error scanning Ollama directory %s: %s", ollama_dir, e)
+    return found
+
+
+def _ollama_dir_for_manifest(tag_file: Path) -> Optional[Path]:
+    """Discovered Ollama root whose ``manifests/`` contains *tag_file*, or ``None``. Validating against known roots keeps a crafted reference from driving materialization to an arbitrary path."""
+    for ollama_dir in ollama_model_dirs():
+        if path_is_same_or_child(tag_file, ollama_dir / "manifests"):
+            return ollama_dir
+    return None
+
+
+def materialize_ollama_model_ref(ref: str) -> str:
+    """Resolve an ``ollama-manifest:`` reference to a loadable ``.gguf`` path,
+    creating the writable symlink/hardlink on demand.
+
+    Raises ``ValueError`` if the reference is malformed, points outside a
+    discovered Ollama models directory, or cannot be materialized.
+    """
+    if not ref.startswith(_OLLAMA_MANIFEST_REF_PREFIX):
+        raise ValueError("Not an Ollama manifest reference")
+
+    tag_file = Path(unquote(ref[len(_OLLAMA_MANIFEST_REF_PREFIX) :]))
+
+    ollama_dir = _ollama_dir_for_manifest(tag_file)
+    if ollama_dir is None:
+        raise ValueError("Reference is outside any known Ollama models directory")
+
+    links_root = _ollama_links_dir(ollama_dir)
+    if links_root is None:
+        raise ValueError("No writable location for Ollama .gguf links")
+
+    info = _ollama_model_info_from_manifest(
+        ollama_dir,
+        tag_file,
+        materialize_links = True,
+        links_root = links_root,
+    )
+    if info is None or not info.path:
+        raise ValueError("Could not materialize Ollama model from manifest")
+    return info.path
diff --git a/studio/backend/hub/services/snapshot_progress.py b/studio/backend/hub/services/snapshot_progress.py
new file mode 100644
index 0000000000..9c8bc9a891
--- /dev/null
+++ b/studio/backend/hub/services/snapshot_progress.py
@@ -0,0 +1,260 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared snapshot download-progress computation for models and datasets.
+
+Both scan the cache's ``blobs/`` dir, split finalized vs ``.incomplete`` bytes,
+filter to the target revision's expected hashes, and divide by its total size;
+only the ``metadata_resolver`` differs. One copy keeps the two from drifting (a
+prior hash-filter fix once landed only on the model copy, leaving datasets
+summing stale blobs against the wrong total)."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Callable, Optional
+
+from loggers import get_logger
+
+from hub.utils import download_manifest
+from hub.utils import download_registry
+from hub.utils import inventory_scan as hf_cache_scan
+from hub.utils.state_dir import RepoType
+from hub.utils.hf_cache_state import (
+    INCOMPLETE_SUFFIX,
+    blob_bytes_present,
+    latest_snapshot_dir,
+    preferred_repo_cache_dirs,
+)
+from hub.utils.paths import is_valid_repo_id as _is_valid_repo_id
+
+logger = get_logger(__name__)
+
+# (repo_id, hf_token) -> (expected_total_bytes, expected_blob_hashes)
+SnapshotMetadataResolver = Callable[[str, Optional[str]], "tuple[int, frozenset[str]]"]
+
+
+def _empty_progress(expected_bytes: int) -> dict:
+    return {
+        "downloaded_bytes": 0,
+        "completed_bytes": 0,
+        "complete_on_disk": False,
+        "expected_bytes": max(expected_bytes, 0),
+        "progress": 0,
+        "cache_path": None,
+    }
+
+
+def _snapshot_complete_on_disk(
+    *,
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str],
+    entry: Path,
+    expected_total: int,
+    completed_bytes: int,
+    in_progress_bytes: int,
+) -> bool:
+    if expected_total <= 0 or completed_bytes < expected_total or in_progress_bytes > 0:
+        return False
+    snapshot_dir = latest_snapshot_dir(entry)
+    if snapshot_dir is None:
+        return False
+    if variant is None and hf_cache_scan.repo_cache_dir_has_incomplete_blobs(entry):
+        return False
+    if download_manifest.has_cancel_marker(repo_type, repo_id, variant):
+        return False
+    manifest = download_manifest.read_manifest(repo_type, repo_id, variant)
+    if manifest is None:
+        return False
+    return download_manifest.verify_against_disk(manifest, snapshot_dir).ok
+
+
+def compute_snapshot_progress(
+    *,
+    repo_type: RepoType,
+    repo_id: str,
+    job_key: str,
+    expected_bytes: int,
+    hf_token: Optional[str],
+    registry,
+    metadata_resolver: SnapshotMetadataResolver,
+    variant: Optional[str] = None,
+) -> dict:
+    """Synchronous progress reading. Safe to run under ``asyncio.to_thread``."""
+    empty = _empty_progress(expected_bytes)
+    if not _is_valid_repo_id(repo_id):
+        return empty
+
+    job_state = registry.get_job(job_key).state
+    force_active = job_state in {"running", "cancelling"}
+    get_job_metadata = getattr(registry, "get_job_metadata", None)
+    metadata = get_job_metadata(job_key) if callable(get_job_metadata) else None
+    completed_baseline_bytes = max(
+        0,
+        int(getattr(metadata, "completed_baseline_bytes", 0) or 0),
+    )
+
+    expected_total = max(expected_bytes, 0)
+    # Always resolve the revision's blob hashes so stale blobs from a superseded
+    # revision can't inflate the count; hashes degrade to empty (count-all) only
+    # when metadata is unavailable (e.g. offline). Take the larger total so a low
+    # caller hint can't cap the bar below the revision's real size.
+    meta_total, expected_hashes = metadata_resolver(repo_id, hf_token)
+    expected_total = max(expected_total, meta_total)
+
+    # Without resolved hashes, a variant must not count unscoped blobs: sibling
+    # quants share one blobs/ dir, so a sibling's bytes (or .incomplete) would be
+    # misattributed and make the bar jump backward. A no-variant snapshot owns
+    # the whole dir, so it counts unscoped.
+    count_finalized_unscoped = variant is None
+
+    readings: list[tuple[int, int, Optional[str], bool]] = []
+    for entry in preferred_repo_cache_dirs(
+        repo_type,
+        repo_id,
+        force_active = force_active,
+    ):
+        completed_bytes = 0
+        in_progress_bytes = 0
+        cache_path = hf_cache_scan.resolve_hf_cache_realpath(entry)
+        blobs_dir = entry / "blobs"
+        if blobs_dir.is_dir():
+            try:
+                blob_entries = list(blobs_dir.iterdir())
+            except OSError:
+                blob_entries = []
+            for f in blob_entries:
+                # Skip a blob that vanished mid-poll rather than zeroing the reading.
+                try:
+                    if not f.is_file():
+                        continue
+                    if f.name.endswith(INCOMPLETE_SUFFIX):
+                        blob_hash = f.name[: -len(INCOMPLETE_SUFFIX)]
+                        if expected_hashes:
+                            if blob_hash not in expected_hashes:
+                                continue
+                        elif not count_finalized_unscoped:
+                            continue
+                        in_progress_bytes += blob_bytes_present(f)
+                    else:
+                        if expected_hashes:
+                            if f.name not in expected_hashes:
+                                continue
+                        elif not count_finalized_unscoped:
+                            continue
+                        completed_bytes += f.stat().st_size
+                except OSError:
+                    continue
+        readings.append(
+            (
+                completed_bytes,
+                in_progress_bytes,
+                cache_path,
+                _snapshot_complete_on_disk(
+                    repo_type = repo_type,
+                    repo_id = repo_id,
+                    variant = variant,
+                    entry = entry,
+                    expected_total = expected_total,
+                    completed_bytes = completed_bytes,
+                    in_progress_bytes = in_progress_bytes,
+                ),
+            )
+        )
+
+    selected = max(
+        readings,
+        key = lambda item: (item[0] + item[1], item[0]),
+        default = None,
+    )
+    if selected is None:
+        return empty
+
+    completed_bytes, in_progress_bytes, cache_path, complete_on_disk = selected
+    downloaded_bytes = completed_bytes + in_progress_bytes
+    # Subtract the companion baseline only while still counted in completed_bytes
+    # and the variant is not yet verified complete, else genuine progress reads as
+    # 0-byte.
+    effective_baseline_bytes = (
+        completed_baseline_bytes
+        if not complete_on_disk and completed_baseline_bytes <= completed_bytes
+        else 0
+    )
+    display_completed_bytes = max(0, completed_bytes - effective_baseline_bytes)
+    display_downloaded_bytes = max(0, downloaded_bytes - effective_baseline_bytes)
+
+    if expected_total <= 0:
+        # Cannot determine total; report bytes only, no percentage.
+        return {
+            "downloaded_bytes": display_downloaded_bytes,
+            "completed_bytes": display_completed_bytes,
+            "complete_on_disk": False,
+            "expected_bytes": 0,
+            "progress": 0,
+            "cache_path": cache_path,
+        }
+
+    display_expected_total = max(0, expected_total - effective_baseline_bytes)
+    if downloaded_bytes == 0:
+        return {
+            **empty,
+            "expected_bytes": display_expected_total,
+            "cache_path": cache_path,
+        }
+
+    # Cap at 0.99 until the manifest-backed disk check verifies completion: on
+    # resume, completed bytes can sit above the threshold while files still download.
+    progress = (
+        1.0
+        if complete_on_disk
+        else (
+            min(display_downloaded_bytes / display_expected_total, 0.99)
+            if display_expected_total > 0
+            else 0
+        )
+    )
+    return {
+        "downloaded_bytes": display_downloaded_bytes,
+        "completed_bytes": display_completed_bytes,
+        "complete_on_disk": complete_on_disk,
+        "expected_bytes": display_expected_total,
+        "progress": round(progress, 3),
+        "cache_path": cache_path,
+    }
+
+
+async def snapshot_progress_response(
+    *,
+    repo_type: RepoType,
+    repo_id: str,
+    job_key: str,
+    expected_bytes: int,
+    hf_token: Optional[str],
+    registry,
+    metadata_resolver: SnapshotMetadataResolver,
+    variant: Optional[str] = None,
+) -> dict:
+    """Async wrapper: offloads the blocking cache walk and never raises."""
+    try:
+        return await asyncio.to_thread(
+            compute_snapshot_progress,
+            repo_type = repo_type,
+            repo_id = repo_id,
+            job_key = job_key,
+            expected_bytes = expected_bytes,
+            hf_token = hf_token,
+            registry = registry,
+            metadata_resolver = metadata_resolver,
+            variant = variant,
+        )
+    except Exception as e:
+        logger.warning(
+            "Error checking %s download progress for %s: %s: %s",
+            repo_type,
+            repo_id,
+            type(e).__name__,
+            download_registry.scrub_secrets(str(e), hf_token = hf_token),
+        )
+        return _empty_progress(expected_bytes)
diff --git a/studio/backend/hub/storage/__init__.py b/studio/backend/hub/storage/__init__.py
new file mode 100644
index 0000000000..32014236c6
--- /dev/null
+++ b/studio/backend/hub/storage/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
diff --git a/studio/backend/hub/storage/scan_folders.py b/studio/backend/hub/storage/scan_folders.py
new file mode 100644
index 0000000000..85f515da00
--- /dev/null
+++ b/studio/backend/hub/storage/scan_folders.py
@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Persistence for user-registered custom model scan folders.
+
+Self-bootstrapping table inside the existing studio SQLite so the Hub module
+doesn't have to modify upstream studio_db.py's schema init."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sqlite3
+import threading
+from datetime import datetime, timezone
+
+from storage.studio_db import get_connection
+from hub.utils.paths import normalize_path
+
+
+_schema_lock = threading.Lock()
+_schema_ready = False
+_SENSITIVE_PATH_COMPONENTS = {
+    ".aws",
+    ".azure",
+    ".config",
+    ".docker",
+    ".gcloud",
+    ".gnupg",
+    ".huggingface",
+    ".kaggle",
+    ".kube",
+    ".modelscope",
+    ".ngc",
+    ".local",
+    ".mozilla",
+    ".pki",
+    ".thunderbird",
+    ".ssh",
+    ".1password",
+    ".bitwarden",
+    ".password-store",
+    "1password",
+    "bitwarden",
+    "keychains",
+    "keyrings",
+    "mozilla",
+    "thunderbird",
+}
+
+
+def _denied_path_prefixes() -> list[str]:
+    system = platform.system()
+    if system == "Linux":
+        return ["/proc", "/sys", "/dev", "/etc", "/boot", "/run"]
+    if system == "Darwin":
+        # realpath() resolves /etc -> /private/etc, /tmp -> /private/tmp on macOS,
+        # so include the /private variants to avoid bypasses.
+        return [
+            "/System",
+            "/Library",
+            "/dev",
+            "/etc",
+            "/private/etc",
+            "/tmp",
+            "/private/tmp",
+            "/var",
+            "/private/var",
+        ]
+    if system == "Windows":
+        win = os.environ.get("SystemRoot", r"C:\Windows")
+        pf = os.environ.get("ProgramFiles", r"C:\Program Files")
+        pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+        return [os.path.normcase(p) for p in [win, pf, pf86]]
+    return []
+
+
+def _contains_sensitive_path_component(path: str) -> bool:
+    parts = os.path.normpath(path).split(os.sep)
+    return any(part.lower() in _SENSITIVE_PATH_COMPONENTS for part in parts)
+
+
+def contains_sensitive_path_component(path: str) -> bool:
+    """Public predicate for the credential/config denylist (.ssh, .aws, ...).
+
+    Shared with the folder browser so browse and register enforce one policy."""
+    return _contains_sensitive_path_component(path)
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    global _schema_ready
+    if _schema_ready:
+        return
+    with _schema_lock:
+        if _schema_ready:
+            return
+        collation = "COLLATE NOCASE" if platform.system() == "Windows" else ""
+        conn.execute(
+            f"""
+            CREATE TABLE IF NOT EXISTS scan_folders (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                path TEXT NOT NULL UNIQUE {collation},
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+        conn.commit()
+        _schema_ready = True
+
+
+def list_scan_folders() -> list[dict]:
+    conn = get_connection()
+    try:
+        _ensure_schema(conn)
+        rows = conn.execute(
+            "SELECT id, path, created_at FROM scan_folders ORDER BY created_at"
+        ).fetchall()
+        return [dict(row) for row in rows]
+    finally:
+        conn.close()
+
+
+def add_scan_folder(path: str) -> dict:
+    """Add a readable directory for the local OS user; not a multi-user sandbox."""
+    if not path or not path.strip():
+        raise ValueError("Path cannot be empty")
+    normalized = os.path.realpath(os.path.expanduser(normalize_path(path.strip())))
+
+    if not os.path.exists(normalized):
+        raise ValueError("Path does not exist")
+    if not os.path.isdir(normalized):
+        raise ValueError("Path must be a directory, not a file")
+    if not os.access(normalized, os.R_OK | os.X_OK):
+        raise ValueError("Path is not readable")
+    if os.path.dirname(normalized) == normalized:
+        # Registering a filesystem root would expose denied system dirs via browse.
+        raise ValueError("The filesystem root cannot be registered")
+    if _contains_sensitive_path_component(normalized):
+        raise ValueError("Credential or configuration directories are not allowed")
+
+    is_win = platform.system() == "Windows"
+    check = os.path.normcase(normalized) if is_win else normalized
+    for prefix in _denied_path_prefixes():
+        if check == prefix or check.startswith(prefix + os.sep):
+            raise ValueError(f"Path under {prefix} is not allowed")
+
+    conn = get_connection()
+    try:
+        _ensure_schema(conn)
+        now = datetime.now(timezone.utc).isoformat()
+        if is_win:
+            existing = conn.execute(
+                "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE",
+                (normalized,),
+            ).fetchone()
+        else:
+            existing = conn.execute(
+                "SELECT id, path, created_at FROM scan_folders WHERE path = ?",
+                (normalized,),
+            ).fetchone()
+        if existing is not None:
+            return dict(existing)
+        try:
+            conn.execute(
+                "INSERT INTO scan_folders (path, created_at) VALUES (?, ?)",
+                (normalized, now),
+            )
+            conn.commit()
+        except sqlite3.IntegrityError:
+            pass
+        fallback_sql = (
+            "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE"
+            if is_win
+            else "SELECT id, path, created_at FROM scan_folders WHERE path = ?"
+        )
+        row = conn.execute(fallback_sql, (normalized,)).fetchone()
+        if row is None:
+            raise ValueError("Folder was concurrently removed")
+        return dict(row)
+    finally:
+        conn.close()
+
+
+def remove_scan_folder(id: int) -> None:
+    # sqlite INTEGER is signed 64-bit; ids outside that range cannot exist.
+    if not -(2**63) <= id < 2**63:
+        return
+    conn = get_connection()
+    try:
+        _ensure_schema(conn)
+        conn.execute("DELETE FROM scan_folders WHERE id = ?", (id,))
+        conn.commit()
+    finally:
+        conn.close()
diff --git a/studio/backend/hub/tests/conftest.py b/studio/backend/hub/tests/conftest.py
new file mode 100644
index 0000000000..38b6bed938
--- /dev/null
+++ b/studio/backend/hub/tests/conftest.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import sys
+import types
+
+
+class _BaseModel:
+    def __init__(self, **kwargs):
+        for name, value in self.__class__.__dict__.items():
+            if name.startswith("_") or callable(value):
+                continue
+            if name not in kwargs:
+                setattr(self, name, value)
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    def model_dump(self):
+        return dict(self.__dict__)
+
+    def model_copy(self, update = None):
+        data = self.model_dump()
+        if update:
+            data.update(update)
+        return self.__class__(**data)
+
+
+def _field(default = ..., **kwargs):
+    if "default_factory" in kwargs:
+        return kwargs["default_factory"]()
+    return None if default is ... else default
+
+
+def _model_validator(*args, **kwargs):
+    def decorator(fn):
+        return fn
+
+    return decorator
+
+
+class _HTTPException(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        detail = None,
+    ):
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class _APIRouter:
+    def get(self, *args, **kwargs):
+        return lambda fn: fn
+
+    def post(self, *args, **kwargs):
+        return lambda fn: fn
+
+    def delete(self, *args, **kwargs):
+        return lambda fn: fn
+
+
+def _fastapi_marker(
+    default = None,
+    *args,
+    **kwargs,
+):
+    return default
+
+
+class _DummyLogger:
+    def __getattr__(self, _name):
+        return lambda *args, **kwargs: None
+
+
+sys.modules.setdefault(
+    "pydantic",
+    types.SimpleNamespace(
+        BaseModel = _BaseModel,
+        Field = _field,
+        model_validator = _model_validator,
+    ),
+)
+sys.modules.setdefault(
+    "fastapi",
+    types.SimpleNamespace(
+        APIRouter = _APIRouter,
+        Body = _fastapi_marker,
+        Depends = _fastapi_marker,
+        Header = _fastapi_marker,
+        HTTPException = _HTTPException,
+        Query = _fastapi_marker,
+        UploadFile = object,
+    ),
+)
+sys.modules.setdefault(
+    "loggers",
+    types.SimpleNamespace(get_logger = lambda *args, **kwargs: _DummyLogger()),
+)
+sys.modules.setdefault(
+    "structlog",
+    types.SimpleNamespace(
+        BoundLogger = _DummyLogger,
+        get_logger = lambda *args, **kwargs: _DummyLogger(),
+    ),
+)
diff --git a/studio/backend/hub/tests/test_dataset_services.py b/studio/backend/hub/tests/test_dataset_services.py
new file mode 100644
index 0000000000..4890714cd0
--- /dev/null
+++ b/studio/backend/hub/tests/test_dataset_services.py
@@ -0,0 +1,356 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi import HTTPException
+
+from hub.schemas.datasets import CheckFormatRequest, LocalDatasetItem
+from hub.services.datasets import cache_inventory, downloads, formatting, local
+from hub.utils import download_manifest, download_registry, state_dir
+
+
+class _Upload:
+    def __init__(self, filename: str, payload: bytes):
+        self.filename = filename
+        self._payload = payload
+        self._offset = 0
+
+    async def read(self, size: int) -> bytes:
+        if self._offset >= len(self._payload):
+            return b""
+        chunk = self._payload[self._offset : self._offset + size]
+        self._offset += len(chunk)
+        return chunk
+
+
+def test_dataset_cache_scan_merges_raw_and_processed_rows(monkeypatch):
+    raw_repo = SimpleNamespace(
+        repo_id = "Org/Data",
+        repo_type = "dataset",
+        repo_path = "/cache/datasets--Org--Data",
+        size_on_disk = 100,
+        revisions = [SimpleNamespace(files = [], commit_hash = "abc")],
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_collect_hf_cache_scans",
+        lambda: ([SimpleNamespace(repos = [raw_repo])], {"/cache"}),
+    )
+    monkeypatch.setattr(
+        cache_inventory.hf_cache_scan,
+        "is_snapshot_partial",
+        lambda _repo_type, _repo_id, _cache_dir: False,
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_scan_hub_dataset_cache_dirs",
+        lambda: [],
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_scan_processed_dataset_caches",
+        lambda: [
+            {
+                "repo_id": "org/data",
+                "size_bytes": 250,
+                "cache_path": "/processed/org___data",
+                "processed_cache": True,
+                "partial": False,
+            }
+        ],
+    )
+
+    rows = cache_inventory._scan_hf_dataset_caches()
+
+    assert len(rows) == 1
+    assert rows[0]["repo_id"] == "Org/Data"
+    assert rows[0]["size_bytes"] == 250
+    assert rows[0]["partial"] is False
+
+
+def test_delete_cached_dataset_attempts_all_roots_before_raising(monkeypatch):
+    calls = []
+    purged_state = []
+
+    class _DeleteStrategy:
+        def __init__(self, label: str, fail: bool):
+            self.label = label
+            self.fail = fail
+
+        def execute(self):
+            calls.append(self.label)
+            if self.fail:
+                raise RuntimeError(f"{self.label} failed")
+
+    class _Cache:
+        def __init__(self, label: str, fail: bool):
+            self.cache_dir = label
+            self.repos = [
+                SimpleNamespace(
+                    repo_type = "dataset",
+                    repo_id = "Org/Data",
+                    revisions = [SimpleNamespace(commit_hash = f"{label}-rev")],
+                )
+            ]
+            self.fail = fail
+
+        def delete_revisions(self, *_revisions):
+            return _DeleteStrategy(self.cache_dir, self.fail)
+
+    monkeypatch.setattr(
+        cache_inventory,
+        "_collect_hf_cache_scans",
+        lambda: ([_Cache("first", True), _Cache("second", False)], set()),
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_delete_processed_dataset_cache",
+        lambda _repo_id: (True, []),
+    )
+    monkeypatch.setattr(
+        cache_inventory.download_manifest,
+        "purge_all_state_for_repo",
+        lambda *_args: purged_state.append(True) or 1,
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        cache_inventory._delete_cached_dataset_blocking("Org/Data")
+
+    assert exc_info.value.status_code == 500
+    assert calls == ["first", "second"]
+    assert purged_state == []
+
+
+def test_delete_cached_dataset_purges_blob_only_repo_dir(monkeypatch):
+    """A blob-only ``datasets--owner--repo`` dir (no usable snapshot/refs) is
+    fully removable: purge_partial_repo alone clears only ``.incomplete`` files
+    and would leave the complete blobs and the row."""
+    purged_dirs: list[str] = []
+
+    monkeypatch.setattr(
+        cache_inventory,
+        "_collect_hf_cache_scans",
+        lambda: ([], set()),
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_delete_processed_dataset_cache",
+        lambda _repo_id: (False, []),
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "purge_repo_cache_dirs",
+        lambda _repo_type, repo_id: purged_dirs.append(repo_id) or True,
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "purge_partial_repo",
+        lambda *_args: False,
+    )
+    monkeypatch.setattr(
+        cache_inventory.download_manifest,
+        "purge_all_state_for_repo",
+        lambda *_args: 0,
+    )
+
+    result = cache_inventory._delete_cached_dataset_blocking("Org/Data")
+
+    assert result == {"status": "deleted", "repo_id": "Org/Data"}
+    assert purged_dirs == ["Org/Data"]
+
+
+def test_delete_cached_dataset_absent_everywhere_raises_404(monkeypatch):
+    monkeypatch.setattr(
+        cache_inventory,
+        "_collect_hf_cache_scans",
+        lambda: ([], set()),
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "_delete_processed_dataset_cache",
+        lambda _repo_id: (False, []),
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "purge_repo_cache_dirs",
+        lambda *_args: False,
+    )
+    monkeypatch.setattr(
+        cache_inventory,
+        "purge_partial_repo",
+        lambda *_args: False,
+    )
+    monkeypatch.setattr(
+        cache_inventory.download_manifest,
+        "purge_all_state_for_repo",
+        lambda *_args: 0,
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        cache_inventory._delete_cached_dataset_blocking("Org/Missing")
+
+    assert exc_info.value.status_code == 404
+
+
+def test_check_format_rejects_invalid_path_as_400():
+    with pytest.raises(HTTPException) as exc_info:
+        formatting.check_format_response(CheckFormatRequest(dataset_name = "../../etc/passwd"))
+
+    assert exc_info.value.status_code == 400
+
+
+def test_dataset_download_status_preserves_idle_shape():
+    status = downloads._dataset_status("Org/Data")
+
+    assert status.state == "idle"
+    assert status.error is None
+
+
+def test_dataset_download_registry_key_is_case_insensitive():
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Data",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "Org/Data",
+    )
+    duplicate_claimed, duplicate_state = registry.claim(
+        "org/data",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "org/data",
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert duplicate_claimed is False
+    assert duplicate_state == "running"
+    assert registry.active_jobs("ORG/DATA") == {"org/data": "running"}
+
+
+def test_dataset_idle_status_uses_cancel_marker_after_restart(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path)
+    monkeypatch.setattr(downloads, "_registry", download_registry.DownloadRegistry())
+    assert download_manifest.write_cancel_marker("dataset", "Owner/Data", None, "http")
+
+    status = asyncio.run(downloads.get_dataset_download_status_response("owner/data"))
+
+    assert status.state == "cancelled"
+    assert status.error is None
+
+
+def test_dataset_claim_register_cancel_uses_registry_marker_owner(monkeypatch):
+    killed = []
+
+    class _Registry:
+        def claim(self, *_args, **_kwargs):
+            return True, "running"
+
+        def current_generation(self, _key):
+            return 1
+
+        def register_process(self, _key, _proc):
+            return False
+
+        def persist_cancel_for_key(self, *_args, **_kwargs):
+            raise AssertionError("register_process owns pending-cancel markers")
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "cancelled", error = None)
+
+    monkeypatch.setattr(downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "download_transport_unavailable_reason",
+        lambda _transport: None,
+    )
+    monkeypatch.setattr(
+        downloads.download_lifecycle,
+        "spawn_worker",
+        lambda *_args, **_kwargs: object(),
+    )
+    monkeypatch.setattr(
+        downloads.download_lifecycle,
+        "kill_and_reap_process",
+        lambda proc, **_kwargs: killed.append(proc),
+    )
+
+    result = asyncio.run(
+        downloads.download_dataset_response(SimpleNamespace(repo_id = "Org/Data", use_xet = False))
+    )
+
+    assert result["state"] == "cancelled"
+    assert killed
+
+
+def test_dataset_cancel_pending_spawn_arms_pending_cancel(monkeypatch):
+    events = []
+
+    class _Registry:
+        def get_process(self, _key):
+            return None
+
+        def mark_pending_cancel(self, key, generation):
+            events.append(("pending", key, generation))
+            return True
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running")
+
+    monkeypatch.setattr(downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+
+    result = asyncio.run(
+        downloads.cancel_dataset_download_response(
+            SimpleNamespace(repo_id = "Org/Data", generation = 5)
+        )
+    )
+
+    assert result == {"repo_id": "Org/Data", "state": "cancelling"}
+    assert events == [("pending", "org/data", 5)]
+
+
+def test_upload_dataset_response_writes_non_empty_file(monkeypatch, tmp_path):
+    payload = b'{"text":"hello"}\n'
+    monkeypatch.setattr(local, "DATASET_UPLOAD_DIR", tmp_path)
+
+    response = asyncio.run(local.upload_dataset_response(_Upload("../train.jsonl", payload)))
+
+    stored_path = Path(response.stored_path)
+    assert response.filename == "train.jsonl"
+    assert stored_path.parent == tmp_path
+    assert stored_path.name.endswith("_train.jsonl")
+    assert stored_path.read_bytes() == payload
+
+
+def test_local_dataset_items_expose_recipe_and_upload_source(monkeypatch, tmp_path):
+    recipe_root = tmp_path / "recipes"
+    upload_root = tmp_path / "uploads"
+    parquet_dir = recipe_root / "recipe_alpha" / "parquet-files"
+    parquet_dir.mkdir(parents = True)
+    (parquet_dir / "part.parquet").write_bytes(b"parquet")
+    upload_root.mkdir()
+    (upload_root / "manual.jsonl").write_text('{"text":"hello"}\n', encoding = "utf-8")
+    monkeypatch.setattr(local, "LOCAL_DATASETS_ROOT", recipe_root)
+    monkeypatch.setattr(local, "DATASET_UPLOAD_DIR", upload_root)
+
+    response = local.list_local_datasets_response()
+
+    assert "source" in LocalDatasetItem.__annotations__
+    by_id = {item.id: item for item in response.datasets}
+    assert by_id["recipe_alpha"].source == "recipe"
+    assert by_id["manual.jsonl"].source == "upload"
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
new file mode 100644
index 0000000000..44ab4b80d0
--- /dev/null
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -0,0 +1,2962 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi import HTTPException
+
+from hub.dependencies import get_hf_token
+from hub.storage import scan_folders
+from hub.services import download_lifecycle
+from hub.services import snapshot_progress
+from hub.services.datasets import downloads as dataset_downloads
+from hub.services.models import (
+    cache_inventory,
+    common as model_common,
+    deletion,
+    downloads,
+    folder_browser,
+    gguf_variants,
+    local_inventory,
+    ollama,
+)
+from hub.utils import (
+    download_manifest,
+    download_registry,
+    gguf,
+    hf_cache_state,
+    inventory_scan,
+    paths,
+    state_dir,
+)
+from hub.workers import hf_download
+
+
+def _repo(repo_id: str, files: list[SimpleNamespace], repo_path: Path):
+    return SimpleNamespace(
+        repo_id = repo_id,
+        repo_type = "model",
+        repo_path = repo_path,
+        revisions = [SimpleNamespace(files = files)],
+    )
+
+
+def _file(
+    name: str,
+    size: int,
+    blob_path: str | None = None,
+):
+    return SimpleNamespace(file_name = name, size_on_disk = size, blob_path = blob_path)
+
+
+def _sibling(name: str, size: int, sha: str):
+    return SimpleNamespace(rfilename = name, size = size, lfs = {"sha256": sha})
+
+
+class TestExtractQuantToken:
+    def test_trailing_precision_is_kept(self):
+        assert gguf.extract_quant_token("model-it-F16.gguf") == "F16"
+        assert gguf.extract_quant_token("model-BF16.gguf") == "BF16"
+
+    def test_real_quant_wins_over_infix_precision(self):
+        assert gguf.extract_quant_token("Foo-BF16-Q4_K_M.gguf") == "Q4_K_M"
+        assert gguf.extract_quant_token("Foo-F16-Q8_0.gguf") == "Q8_0"
+        assert gguf.extract_quant_token("Foo-F32-IQ4_XS.gguf") == "IQ4_XS"
+
+    def test_ud_prefix_preserved(self):
+        assert gguf.extract_quant_token("Foo-BF16-UD-Q4_K_XL.gguf") == "UD-Q4_K_XL"
+
+    def test_precision_infix_variants_do_not_collapse(self):
+        labels = {
+            gguf.extract_quant_label("Foo-BF16-Q4_K_M.gguf"),
+            gguf.extract_quant_label("Foo-BF16-Q8_0.gguf"),
+        }
+        assert labels == {"Q4_K_M", "Q8_0"}
+
+
+@pytest.mark.parametrize("repo_id", ["bert-base-uncased", "owner/repo"])
+def test_repo_id_validation_accepts_hf_repo_id_contract(repo_id):
+    assert paths.is_valid_repo_id(repo_id)
+
+
+@pytest.mark.parametrize(
+    "repo_id",
+    [
+        "datasets/foo/bar",
+        ".repo",
+        "repo.git",
+        "foo..bar",
+        "foo--bar",
+        "../repo",
+        "owner/../repo",
+    ],
+)
+def test_repo_id_validation_rejects_unsafe_or_invalid_ids(repo_id):
+    assert not paths.is_valid_repo_id(repo_id)
+
+
+class _RecordingLogger:
+    def __init__(self):
+        self.warnings = []
+
+    def warning(self, *args, **kwargs):
+        self.warnings.append((args, kwargs))
+
+
+def test_resolve_browse_target_preserves_allowlist_and_symlink_safety(tmp_path):
+    home = tmp_path / "home"
+    scan = tmp_path / "scan"
+    target = scan / "nested"
+    home.mkdir()
+    target.mkdir(parents = True)
+    (home / "scan-link").symlink_to(scan, target_is_directory = True)
+
+    resolved = folder_browser._resolve_browse_target(
+        str(home / "scan-link" / "nested"),
+        [home, scan],
+    )
+
+    assert resolved == target.resolve()
+
+
+def test_resolve_browse_target_rejects_outside_allowlist(tmp_path):
+    allowed = tmp_path / "allowed"
+    outside = tmp_path / "outside"
+    allowed.mkdir()
+    outside.mkdir()
+
+    with pytest.raises(HTTPException) as exc_info:
+        folder_browser._resolve_browse_target(str(outside), [allowed])
+
+    assert exc_info.value.status_code == 403
+
+
+def test_resolve_browse_target_rejects_sensitive_dir(tmp_path):
+    home = tmp_path / "home"
+    ssh = home / ".ssh"
+    ssh.mkdir(parents = True)
+
+    with pytest.raises(HTTPException) as exc_info:
+        folder_browser._resolve_browse_target(str(ssh), [home])
+
+    assert exc_info.value.status_code == 403
+
+
+def test_browse_folders_hides_sensitive_dirs(monkeypatch, tmp_path):
+    home = tmp_path / "home"
+    (home / ".ssh").mkdir(parents = True)
+    (home / "models").mkdir()
+    monkeypatch.setattr(folder_browser, "_build_browse_allowlist", lambda: [home])
+
+    response = folder_browser.browse_folders_response(str(home), show_hidden = True)
+
+    names = {entry.name for entry in response.entries}
+    assert "models" in names
+    assert ".ssh" not in names
+
+
+def test_contained_link_path_confines_to_link_dir(tmp_path):
+    link_dir = tmp_path / "ollama" / ".studio_links" / "abc123"
+
+    legit = ollama._contained_link_path(link_dir, "llama3-latest-Q4_K_M.gguf")
+    assert legit == link_dir / "llama3-latest-Q4_K_M.gguf"
+
+    for unsafe in (
+        "",
+        ".",
+        "..",
+        "a/b.gguf",
+        "../evil.gguf",
+        "/etc/passwd",
+        "model-tag-../../../pwned.gguf",
+    ):
+        assert ollama._contained_link_path(link_dir, unsafe) is None
+
+
+def test_make_ollama_blob_link_refuses_escaping_name(tmp_path):
+    root = tmp_path / "ollama"
+    link_dir = root / ".studio_links" / "abc123"
+    blob = root / "blobs" / "sha256-deadbeef"
+    blob.parent.mkdir(parents = True)
+    blob.write_bytes(b"weights")
+
+    escaped = ollama._make_ollama_blob_link(link_dir, "model-tag-../../../pwned.gguf", blob)
+    assert escaped is None
+    assert not list(tmp_path.rglob("pwned.gguf"))
+
+    safe = ollama._make_ollama_blob_link(link_dir, "model-tag.gguf", blob)
+    assert safe == str(link_dir / "model-tag.gguf")
+    assert (link_dir / "model-tag.gguf").exists()
+
+
+def test_cached_gguf_scan_dedupes_and_excludes_mmproj_only(monkeypatch, tmp_path):
+    smaller = _repo("Org/Dupe", [_file("Q4_K_M.gguf", 100)], tmp_path / "small")
+    larger = _repo(
+        "org/dupe",
+        [_file("Q4_K_M.gguf", 300), _file("Q8_0.gguf", 200)],
+        tmp_path / "large",
+    )
+    mmproj_only = _repo("Org/VisionAdapter", [_file("mmproj-F16.gguf", 900)], tmp_path / "mmproj")
+    monkeypatch.setattr(
+        cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [smaller, larger, mmproj_only])],
+    )
+    monkeypatch.setattr(
+        cache_inventory.hf_cache_scan,
+        "is_gguf_repo_partial",
+        lambda _repo_id, _path: False,
+    )
+
+    result = {"cached": cache_inventory._scan_cached_gguf()}
+
+    assert [row["repo_id"] for row in result["cached"]] == ["org/dupe"]
+    assert result["cached"][0]["size_bytes"] == 500
+    assert result["cached"][0]["model_format"] == "gguf"
+    assert result["cached"][0]["capabilities"]["requires_variant"] is True
+
+
+def test_cached_gguf_scan_preserves_partial_flag(monkeypatch, tmp_path):
+    partial = _repo("Org/Partial", [_file("Q4_K_M.gguf", 100)], tmp_path / "partial")
+    monkeypatch.setattr(
+        cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [partial])],
+    )
+    monkeypatch.setattr(
+        cache_inventory.hf_cache_scan,
+        "is_gguf_repo_partial",
+        lambda _repo_id, _path: True,
+    )
+
+    result = {"cached": cache_inventory._scan_cached_gguf()}
+    row = result["cached"][0]
+
+    assert row["partial"] is True
+    assert row["partial_transport"] is None
+    assert row["capabilities"]["can_chat"] is False
+
+
+def test_cached_gguf_scan_includes_variant_state_without_completed_gguf(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    repo_path = tmp_path / "hub" / "models--Org--PartialGguf"
+    repo_path.mkdir(parents = True)
+    partial = _repo(
+        "Org/PartialGguf",
+        [_file("config.json", 12)],
+        repo_path,
+    )
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/PartialGguf",
+        "Q4_K_M",
+        [download_manifest.ExpectedFile(path = "model-Q4_K_M.gguf", size = 4096)],
+        "http",
+    )
+    assert download_manifest.write_cancel_marker("model", "Org/PartialGguf", "Q4_K_M", "http")
+    monkeypatch.setattr(
+        cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [partial])],
+    )
+    monkeypatch.setattr(
+        cache_inventory.hf_cache_scan,
+        "is_gguf_repo_partial",
+        lambda _repo_id, _path: True,
+    )
+
+    result = {"cached": cache_inventory._scan_cached_gguf()}
+    row = result["cached"][0]
+
+    assert row["repo_id"] == "Org/PartialGguf"
+    assert row["model_format"] == "gguf"
+    assert row["size_bytes"] == 4096
+    assert row["partial"] is True
+    assert row["capabilities"]["requires_variant"] is True
+
+
+def test_gguf_variant_requirements_include_split_files_and_preferred_mmproj():
+    requirements = gguf_variants._build_gguf_variant_requirements(
+        [
+            _sibling("model-Q4_K_M-00001-of-00002.gguf", 10, "main-a"),
+            _sibling("model-Q4_K_M-00002-of-00002.gguf", 20, "main-b"),
+            _sibling("mmproj-BF16.gguf", 7, "mm-bf16"),
+            _sibling("mmproj-F16.gguf", 5, "mm-f16"),
+        ]
+    )
+
+    req = requirements["q4_k_m"]
+
+    assert req.main_size_bytes == 30
+    assert req.download_size_bytes == 35
+    assert req.main_hashes == frozenset({"main-a", "main-b"})
+    assert req.required_hashes == frozenset({"main-a", "main-b", "mm-f16"})
+    assert req.companion_hashes == frozenset({"mm-f16"})
+    assert req.mmproj_hashes == frozenset({"mm-bf16", "mm-f16"})
+    assert req.target_filenames == (
+        "model-Q4_K_M-00001-of-00002.gguf",
+        "model-Q4_K_M-00002-of-00002.gguf",
+        "mmproj-F16.gguf",
+    )
+
+
+def test_worker_gguf_variant_plan_matches_service_requirement(monkeypatch):
+    siblings = [
+        _sibling("model-Q4_K_M-00001-of-00002.gguf", 10, "main-a"),
+        _sibling("model-Q4_K_M-00002-of-00002.gguf", 20, "main-b"),
+        _sibling("mmproj-BF16.gguf", 7, "mm-bf16"),
+        _sibling("mmproj-F16.gguf", 5, "mm-f16"),
+    ]
+    monkeypatch.setattr(
+        hf_download,
+        "_model_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(siblings = siblings),
+    )
+
+    service_req = gguf_variants._build_gguf_variant_requirements(siblings)["q4_k_m"]
+    worker_plan = hf_download._gguf_variant_target_plan("Org/Vision", "Q4_K_M", None)
+
+    assert worker_plan == service_req
+
+
+def test_gguf_variant_blob_hashes_accept_dict_lfs_fallback(monkeypatch):
+    with gguf_variants._VARIANT_HASH_LOCK:
+        gguf_variants._VARIANT_HASH_CACHE.clear()
+        gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(
+            HfApi = lambda *_args, **_kwargs: SimpleNamespace(
+                model_info = lambda *_a, **_k: SimpleNamespace(
+                    siblings = [
+                        _sibling("model-Q4_K_M.gguf", 10, "main-dict"),
+                        _sibling("model-Q8_0.gguf", 20, "other"),
+                        _sibling("mmproj-F16.gguf", 5, "mmproj"),
+                    ]
+                )
+            )
+        ),
+    )
+
+    result = gguf_variants.gguf_variant_blob_hashes("Org/DictLfs", "Q4_K_M", None)
+    main_only = gguf_variants.gguf_variant_blob_hashes(
+        "Org/DictLfs",
+        "Q4_K_M",
+        None,
+        include_companions = False,
+    )
+
+    assert result == frozenset({"main-dict", "mmproj"})
+    assert main_only == frozenset({"main-dict"})
+
+
+def test_gguf_variant_blob_hashes_skip_missing_rfilename(monkeypatch):
+    with gguf_variants._VARIANT_HASH_LOCK:
+        gguf_variants._VARIANT_HASH_CACHE.clear()
+        gguf_variants._VARIANT_REQUIREMENT_CACHE.clear()
+    siblings = [
+        SimpleNamespace(rfilename = None, size = 1, lfs = {"sha256": "bad"}),
+        _sibling("model-Q4_K_M.gguf", 10, "main"),
+    ]
+    monkeypatch.setattr(
+        gguf_variants,
+        "_fetch_gguf_variant_requirements",
+        lambda _repo_id, _hf_token = None: gguf_variants._build_gguf_variant_requirements(siblings),
+    )
+
+    result = gguf_variants.gguf_variant_blob_hashes("Org/Malformed", "Q4_K_M", None)
+
+    assert result == frozenset({"main"})
+
+
+def test_worker_gguf_variant_targets_skip_missing_rfilename(monkeypatch):
+    monkeypatch.setattr(
+        hf_download,
+        "_model_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            siblings = [
+                SimpleNamespace(rfilename = None, size = 1),
+                _sibling("model-Q4_K_M.gguf", 10, "main"),
+                _sibling("mmproj-F16.gguf", 5, "mm"),
+            ]
+        ),
+    )
+
+    result = hf_download._gguf_variant_target_plan("Org/Malformed", "Q4_K_M", None)
+
+    assert list(result.target_filenames) == ["model-Q4_K_M.gguf", "mmproj-F16.gguf"]
+
+
+def test_download_gguf_variant_purges_only_main_quant_hashes(monkeypatch, tmp_path):
+    prepare_calls = []
+    snapshot_calls = []
+    written = []
+    verified = []
+
+    monkeypatch.setattr(
+        hf_download,
+        "_model_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            siblings = [
+                _sibling("model-Q4_K_M.gguf", 10, "q4-main"),
+                _sibling("model-Q8_0.gguf", 20, "q8-main"),
+                _sibling("mmproj-F16.gguf", 5, "shared-mmproj"),
+            ]
+        ),
+    )
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry,
+        "prepare_cache_for_transport",
+        lambda *args, **kwargs: prepare_calls.append((args, kwargs)) or 0,
+    )
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(
+            snapshot_download = lambda **kwargs: snapshot_calls.append(kwargs) or str(tmp_path)
+        ),
+    )
+
+    hf_download._download_gguf_variant("Org/Vision", "Q4_K_M", None, "http")
+
+    assert prepare_calls == [
+        (
+            ("model", "Org/Vision", "http", "Q4_K_M"),
+            {
+                "only_blob_hashes": frozenset({"q4-main"}),
+                "companion_blob_hashes": frozenset({"shared-mmproj"}),
+                "protected_blob_hashes": frozenset(),
+            },
+        )
+    ]
+    assert [file.path for file in written[0][3]] == ["model-Q4_K_M.gguf", "mmproj-F16.gguf"]
+    assert snapshot_calls[0]["allow_patterns"] == ["model-Q4_K_M.gguf", "mmproj-F16.gguf"]
+    assert verified == [("model", "Org/Vision", "Q4_K_M", str(tmp_path))]
+
+
+def test_download_gguf_variant_manifest_resume_purges_only_main_quant_hashes(monkeypatch, tmp_path):
+    prepare_calls = []
+    snapshot_calls = []
+
+    def _metadata_unavailable(*_args, **_kwargs):
+        raise RuntimeError("metadata down")
+
+    manifest = download_manifest.Manifest(
+        repo_type = "model",
+        repo_id = "Org/Vision",
+        variant = "Q4_K_M",
+        started_at = "",
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 10,
+                sha256 = "q4-main",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 5,
+                sha256 = "shared-mmproj",
+            ),
+        ),
+        transport = "http",
+    )
+    monkeypatch.setattr(
+        hf_download,
+        "_gguf_variant_target_plan",
+        _metadata_unavailable,
+    )
+    monkeypatch.setattr(download_manifest, "read_manifest", lambda *_args: manifest)
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(
+        download_registry,
+        "prepare_cache_for_transport",
+        lambda *args, **kwargs: prepare_calls.append((args, kwargs)) or 0,
+    )
+    monkeypatch.setattr(hf_download, "_verify_completed_download", lambda *_args, **_kwargs: None)
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(
+            snapshot_download = lambda **kwargs: snapshot_calls.append(kwargs) or str(tmp_path)
+        ),
+    )
+
+    hf_download._download_gguf_variant("Org/Vision", "Q4_K_M", None, "http")
+
+    assert prepare_calls == [
+        (
+            ("model", "Org/Vision", "http", "Q4_K_M"),
+            {
+                "only_blob_hashes": frozenset({"q4-main"}),
+                "companion_blob_hashes": frozenset({"shared-mmproj"}),
+                "protected_blob_hashes": frozenset(),
+            },
+        )
+    ]
+    assert snapshot_calls[0]["allow_patterns"] == ["model-Q4_K_M.gguf", "mmproj-F16.gguf"]
+
+
+def test_download_snapshot_recovers_manifest_after_metadata_fallback(monkeypatch, tmp_path):
+    metadata_calls = []
+    written = []
+    cleared = []
+    verified = []
+
+    def _metadata(*_args, **_kwargs):
+        metadata_calls.append(True)
+        if len(metadata_calls) == 1:
+            raise RuntimeError("metadata down")
+        return SimpleNamespace(siblings = [SimpleNamespace(rfilename = "config.json", size = 12)])
+
+    monkeypatch.setattr(hf_download, "_model_info_with_retry", _metadata)
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(
+        download_manifest, "clear_cancel_marker", lambda *args: cleared.append(args)
+    )
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(snapshot_download = lambda **_kwargs: str(tmp_path)),
+    )
+
+    hf_download._download_snapshot("Org/Model", None, "http")
+
+    assert len(metadata_calls) == 2
+    assert cleared == [("model", "Org/Model", None)]
+    assert written[0][0:3] == ("model", "Org/Model", None)
+    assert written[0][3][0].path == "config.json"
+    assert verified == [("model", "Org/Model", None, str(tmp_path))]
+
+
+def test_download_dataset_continues_without_metadata_manifest(monkeypatch, tmp_path):
+    metadata_calls = []
+    snapshot_calls = []
+    written = []
+    cleared = []
+    verified = []
+
+    def _metadata(*_args, **_kwargs):
+        metadata_calls.append(True)
+        raise RuntimeError("metadata down")
+
+    monkeypatch.setattr(hf_download, "_dataset_info_with_retry", _metadata)
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(
+        download_manifest, "clear_cancel_marker", lambda *args: cleared.append(args)
+    )
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setattr(
+        hf_cache_state, "has_active_incomplete_blobs", lambda *_args, **_kwargs: False
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(
+            snapshot_download = lambda **kwargs: snapshot_calls.append(kwargs) or str(tmp_path)
+        ),
+    )
+
+    hf_download._download_dataset("Org/Data", None, "http")
+
+    assert len(metadata_calls) == 2
+    assert cleared == [("dataset", "Org/Data", None)]
+    assert written == []
+    assert snapshot_calls == [
+        {
+            "repo_id": "Org/Data",
+            "token": False,
+            "repo_type": "dataset",
+            "max_workers": 1,
+        }
+    ]
+    assert verified == [("dataset", "Org/Data", None, str(tmp_path))]
+
+
+def test_download_snapshot_fails_when_metadata_unavailable_and_partial_remains(
+    monkeypatch, tmp_path
+):
+    """No prior manifest + metadata unavailable + leftover .incomplete blobs means
+    a cached partial was returned without downloading: the worker must exit 1, not
+    derive a self-certifying manifest from the finalized subset."""
+    written = []
+    verified = []
+
+    def _metadata(*_args, **_kwargs):
+        raise RuntimeError("metadata down")
+
+    monkeypatch.setattr(hf_download, "_model_info_with_retry", _metadata)
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(download_manifest, "read_manifest", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setattr(
+        hf_cache_state, "has_active_incomplete_blobs", lambda *_args, **_kwargs: True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(snapshot_download = lambda **_kwargs: str(tmp_path)),
+    )
+
+    with pytest.raises(SystemExit) as excinfo:
+        hf_download._download_snapshot("Org/Model", None, "http")
+
+    assert excinfo.value.code == 1
+    assert written == []
+    assert verified == []
+
+
+def test_purge_repo_cache_dirs_skips_top_level_symlink(monkeypatch, tmp_path):
+    root = tmp_path / "hub"
+    target = tmp_path / "target"
+    root.mkdir()
+    target.mkdir()
+    link = root / "models--Org--Repo"
+    link.symlink_to(target, target_is_directory = True)
+    monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda: [root])
+
+    removed = hf_cache_state.purge_repo_cache_dirs("model", "Org/Repo")
+
+    assert removed is False
+    assert link.is_symlink()
+    assert target.is_dir()
+
+
+def test_gguf_download_progress_fallback_logs_warning(monkeypatch):
+    token = "hf_12345678901234567890"
+    logger = _RecordingLogger()
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    def _raise_permission_error(*_args, **_kwargs):
+        raise PermissionError(f"denied {token}")
+
+    monkeypatch.setattr(snapshot_progress, "logger", logger)
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda *_args, **_kwargs: frozenset(),
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        _raise_permission_error,
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(get_job = lambda _key: SimpleNamespace(state = "running")),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model",
+            variant = "Q4_K_M",
+            expected_bytes = -1,
+            hf_token = token,
+        )
+    )
+
+    assert result == {
+        "downloaded_bytes": 0,
+        "completed_bytes": 0,
+        "complete_on_disk": False,
+        "expected_bytes": 0,
+        "progress": 0,
+        "cache_path": None,
+    }
+    assert logger.warnings
+    args, kwargs = logger.warnings[0]
+    assert args[:4] == (
+        "Error checking %s download progress for %s: %s: %s",
+        "model",
+        "Org/Model",
+        "PermissionError",
+    )
+    assert token not in args[4]
+    assert "***" in args[4]
+    assert kwargs == {}
+
+
+def test_gguf_progress_counts_completed_mmproj_with_expected_bytes(monkeypatch, tmp_path):
+    """A finished mmproj companion keeps counting toward progress once the caller
+    supplies expected bytes; resolving the variant requirement credits it."""
+    entry = tmp_path / "models--Org--Model-GGUF"
+    snap = entry / "snapshots" / "rev0"
+    blobs = entry / "blobs"
+    snap.mkdir(parents = True)
+    blobs.mkdir(parents = True)
+    (snap / "model-Q4_K_M.gguf").write_bytes(b"x" * 100)
+    (snap / "mmproj-F16.gguf").write_bytes(b"y" * 30)
+    (blobs / "mainhash").write_bytes(b"x" * 100)
+    (blobs / "mmprojhash").write_bytes(b"y" * 30)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/Model-GGUF",
+        "Q4_K_M",
+        [
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ],
+        "http",
+    )
+
+    requirement = gguf_variants._GgufVariantRequirement(
+        main_filenames = frozenset({"model-Q4_K_M.gguf"}),
+        target_filenames = ("model-Q4_K_M.gguf", "mmproj-F16.gguf"),
+        main_hashes = frozenset({"mainhash"}),
+        required_hashes = frozenset({"mainhash", "mmprojhash"}),
+        companion_hashes = frozenset({"mmprojhash"}),
+        mmproj_filenames = frozenset({"mmproj-F16.gguf"}),
+        mmproj_hashes = frozenset({"mmprojhash"}),
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ),
+        main_size_bytes = 100,
+        download_size_bytes = 130,
+    )
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: requirement,
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(get_job = lambda _key: SimpleNamespace(state = "idle")),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 130,
+        )
+    )
+
+    assert result["completed_bytes"] == 130
+    assert result["downloaded_bytes"] == 130
+    assert result["complete_on_disk"] is True
+    assert result["progress"] == 1.0
+
+
+def test_gguf_progress_subtracts_new_job_completed_baseline(monkeypatch, tmp_path):
+    entry = tmp_path / "models--Org--Model-GGUF"
+    snap = entry / "snapshots" / "rev0"
+    blobs = entry / "blobs"
+    snap.mkdir(parents = True)
+    blobs.mkdir(parents = True)
+    (snap / "mmproj-F16.gguf").write_bytes(b"y" * 30)
+    (blobs / "mmprojhash").write_bytes(b"y" * 30)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/Model-GGUF",
+        "Q4_K_M",
+        [
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ],
+        "http",
+    )
+
+    requirement = gguf_variants._GgufVariantRequirement(
+        main_filenames = frozenset({"model-Q4_K_M.gguf"}),
+        target_filenames = ("model-Q4_K_M.gguf", "mmproj-F16.gguf"),
+        main_hashes = frozenset({"mainhash"}),
+        required_hashes = frozenset({"mainhash", "mmprojhash"}),
+        companion_hashes = frozenset({"mmprojhash"}),
+        mmproj_filenames = frozenset({"mmproj-F16.gguf"}),
+        mmproj_hashes = frozenset({"mmprojhash"}),
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ),
+        main_size_bytes = 100,
+        download_size_bytes = 130,
+    )
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: requirement,
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "running"),
+            get_job_metadata = lambda _key: SimpleNamespace(
+                completed_baseline_bytes = 30,
+            ),
+        ),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 130,
+        )
+    )
+
+    assert result["completed_bytes"] == 0
+    assert result["downloaded_bytes"] == 0
+    assert result["expected_bytes"] == 100
+    assert result["complete_on_disk"] is False
+    assert result["progress"] == 0
+
+
+def test_gguf_progress_shows_main_when_companion_left_the_count(monkeypatch, tmp_path):
+    # The mmproj companion that seeded the baseline is gone, so completed_bytes
+    # is main-only and below the baseline; it must not be subtracted to 0.
+    entry = tmp_path / "models--Org--Model-GGUF"
+    blobs = entry / "blobs"
+    blobs.mkdir(parents = True)
+    (blobs / "mainhash").write_bytes(b"x" * 20)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+
+    requirement = gguf_variants._GgufVariantRequirement(
+        main_filenames = frozenset({"model-Q4_K_M.gguf"}),
+        target_filenames = ("model-Q4_K_M.gguf", "mmproj-F16.gguf"),
+        main_hashes = frozenset({"mainhash"}),
+        required_hashes = frozenset({"mainhash", "mmprojhash"}),
+        companion_hashes = frozenset({"mmprojhash"}),
+        mmproj_filenames = frozenset({"mmproj-F16.gguf"}),
+        mmproj_hashes = frozenset({"mmprojhash"}),
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ),
+        main_size_bytes = 100,
+        download_size_bytes = 130,
+    )
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: requirement,
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "running"),
+            get_job_metadata = lambda _key: SimpleNamespace(
+                completed_baseline_bytes = 30,
+            ),
+        ),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 130,
+        )
+    )
+
+    assert result["completed_bytes"] == 20
+    assert result["downloaded_bytes"] == 20
+    assert result["expected_bytes"] == 130
+    assert result["complete_on_disk"] is False
+
+
+def test_gguf_progress_complete_on_disk_ignores_full_baseline(monkeypatch, tmp_path):
+    # A variant already complete on disk carries a baseline equal to its full
+    # size; subtracting it would report 0/0 for a finished variant (frontend
+    # evicts it as gone). Once complete_on_disk is verified, the full figures
+    # must survive.
+    entry = tmp_path / "models--Org--Model-GGUF"
+    snap = entry / "snapshots" / "rev0"
+    blobs = entry / "blobs"
+    snap.mkdir(parents = True)
+    blobs.mkdir(parents = True)
+    (snap / "model-Q4_K_M.gguf").write_bytes(b"x" * 100)
+    (snap / "mmproj-F16.gguf").write_bytes(b"y" * 30)
+    (blobs / "mainhash").write_bytes(b"x" * 100)
+    (blobs / "mmprojhash").write_bytes(b"y" * 30)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/Model-GGUF",
+        "Q4_K_M",
+        [
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ],
+        "http",
+    )
+
+    requirement = gguf_variants._GgufVariantRequirement(
+        main_filenames = frozenset({"model-Q4_K_M.gguf"}),
+        target_filenames = ("model-Q4_K_M.gguf", "mmproj-F16.gguf"),
+        main_hashes = frozenset({"mainhash"}),
+        required_hashes = frozenset({"mainhash", "mmprojhash"}),
+        companion_hashes = frozenset({"mmprojhash"}),
+        mmproj_filenames = frozenset({"mmproj-F16.gguf"}),
+        mmproj_hashes = frozenset({"mmprojhash"}),
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+            download_manifest.ExpectedFile(
+                path = "mmproj-F16.gguf",
+                size = 30,
+                sha256 = "mmprojhash",
+            ),
+        ),
+        main_size_bytes = 100,
+        download_size_bytes = 130,
+    )
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: requirement,
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "running"),
+            get_job_metadata = lambda _key: SimpleNamespace(
+                completed_baseline_bytes = 130,
+            ),
+        ),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 130,
+        )
+    )
+
+    assert result["complete_on_disk"] is True
+    assert result["completed_bytes"] == 130
+    assert result["downloaded_bytes"] == 130
+    assert result["expected_bytes"] == 130
+    assert result["progress"] == 1.0
+
+
+def test_gguf_progress_scoped_hashes_exclude_sibling_quant(monkeypatch, tmp_path):
+    # The "instant ~900 MB" bug: a sibling quant is fully cached when a different
+    # variant starts. With this variant's hashes resolved, progress counts ONLY
+    # its in-progress blob, never the sibling's finalized bytes in the shared
+    # blobs/ dir.
+    entry = tmp_path / "models--Org--Model-GGUF"
+    blobs = entry / "blobs"
+    blobs.mkdir(parents = True)
+    (blobs / "siblinghash").write_bytes(b"z" * 900)  # other quant, complete
+    (blobs / "mainhash.incomplete").write_bytes(b"x" * 5)  # this variant, started
+
+    requirement = gguf_variants._GgufVariantRequirement(
+        main_filenames = frozenset({"model-Q4_K_M.gguf"}),
+        target_filenames = ("model-Q4_K_M.gguf",),
+        main_hashes = frozenset({"mainhash"}),
+        required_hashes = frozenset({"mainhash"}),
+        companion_hashes = frozenset(),
+        mmproj_filenames = frozenset(),
+        mmproj_hashes = frozenset(),
+        expected_files = (
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            ),
+        ),
+        main_size_bytes = 100,
+        download_size_bytes = 100,
+    )
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: requirement,
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "running"),
+            get_job_metadata = lambda _key: SimpleNamespace(
+                completed_baseline_bytes = 0,
+            ),
+        ),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 100,
+        )
+    )
+
+    assert result["completed_bytes"] == 0
+    assert result["downloaded_bytes"] == 5
+
+
+def test_gguf_progress_unknown_hashes_does_not_count_foreign_blobs(monkeypatch, tmp_path):
+    # With a variant's hashes unresolved (metadata flaked, no manifest), the
+    # shared blobs/ dir's FINALIZED blobs must NOT be counted wholesale: a cached
+    # sibling quant (``siblinghash``) alongside is the "instant ~900 MB" bug.
+    # With no .incomplete present, downloaded must be 0.
+    entry = tmp_path / "models--Org--Model-GGUF"
+    snap = entry / "snapshots" / "rev0"
+    blobs = entry / "blobs"
+    snap.mkdir(parents = True)
+    blobs.mkdir(parents = True)
+    (blobs / "mainhash").write_bytes(b"x" * 100)
+    (blobs / "mmprojhash").write_bytes(b"y" * 30)
+    (blobs / "siblinghash").write_bytes(b"z" * 900)
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda *_args, **_kwargs: frozenset(),
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(get_job = lambda _key: SimpleNamespace(state = "running")),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 130,
+        )
+    )
+
+    assert result["completed_bytes"] == 0
+    assert result["downloaded_bytes"] == 0
+    assert result["complete_on_disk"] is False
+
+
+def test_gguf_progress_unknown_hashes_drops_unscoped_incomplete_blob(monkeypatch, tmp_path):
+    # With hashes unresolved, an .incomplete in the shared blobs/ dir can't be
+    # attributed to this variant (it may be a concurrent sibling's active write),
+    # so it is dropped, mirroring the finalized-blob guard. In production the
+    # worker writes the manifest before any .incomplete exists, so hashes resolve
+    # via the manifest backstop and this window never suppresses real progress.
+    entry = tmp_path / "models--Org--Model-GGUF"
+    blobs = entry / "blobs"
+    blobs.mkdir(parents = True)
+    (blobs / "activehash.incomplete").write_bytes(b"x" * 50)  # unattributable
+    (blobs / "siblinghash").write_bytes(b"z" * 900)  # finalized sibling
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda *_args, **_kwargs: frozenset(),
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(get_job = lambda _key: SimpleNamespace(state = "running")),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "Org/Model-GGUF",
+            variant = "Q4_K_M",
+            expected_bytes = 1000,
+        )
+    )
+
+    assert result["downloaded_bytes"] == 0  # unscoped .incomplete not leaked
+    assert result["completed_bytes"] == 0  # finalized sibling still ignored
+
+
+def test_gguf_progress_unknown_hashes_no_backward_dip_when_variant_finalizes(monkeypatch, tmp_path):
+    # Regression for the two-variant dip: with hashes unresolved, the first quant
+    # finalizes while the sibling still writes its .incomplete. The sibling's
+    # bytes used to leak into this numerator, dipping the bar ~99% -> ~78% for
+    # one poll. The unscoped .incomplete must be dropped so the reading stays 0.
+    entry = tmp_path / "models--unsloth--SmolLM2-360M-Instruct-GGUF"
+    blobs = entry / "blobs"
+    snap = entry / "snapshots" / "rev0"
+    blobs.mkdir(parents = True)
+    snap.mkdir(parents = True)
+    own_total = 218_673_760  # Q2_K finished blob size (denominator)
+    sibling_total = 234_686_560  # Q3_K_M total
+
+    def _sparse_file(path: Path, size: int) -> None:
+        with path.open("wb") as handle:
+            handle.truncate(size)
+
+    own_finalized = blobs / "q2hash"
+    _sparse_file(own_finalized, own_total)
+    # ~72.7% of the sibling => sibling_partial / own_total == 0.78 pre-fix.
+    sibling_incomplete = blobs / "q3hash.incomplete"
+    _sparse_file(sibling_incomplete, int(sibling_total * 0.727))
+
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_requirements",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda *_args, **_kwargs: frozenset(),
+    )
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda *_args, **_kwargs: [entry],
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        SimpleNamespace(get_job = lambda _key: SimpleNamespace(state = "running")),
+    )
+
+    result = asyncio.run(
+        downloads.get_gguf_download_progress_response(
+            "unsloth/SmolLM2-360M-Instruct-GGUF",
+            variant = "Q2_K",
+            expected_bytes = own_total,
+        )
+    )
+
+    assert result["downloaded_bytes"] == 0  # sibling .incomplete did not leak
+    assert result["progress"] == 0  # no ~0.78 backward dip
+
+
+def test_hf_cache_model_file_probe_is_bounded(monkeypatch, tmp_path):
+    snapshot = tmp_path / "snapshot"
+    snapshot.mkdir()
+    first = tmp_path / "README.md"
+    second = tmp_path / "notes.txt"
+    model = tmp_path / "model.safetensors"
+    first.write_text("readme", encoding = "utf-8")
+    second.write_text("notes", encoding = "utf-8")
+    model.write_bytes(b"weights")
+    entries = [first, second, model]
+
+    monkeypatch.setattr(model_common.Path, "rglob", lambda _self, _pattern: iter(entries))
+    monkeypatch.setattr(model_common, "_HF_CACHE_MODEL_FILE_PROBE_LIMIT", 2)
+
+    bounded = model_common._iter_hf_cache_model_files(snapshot)
+
+    assert bounded == [first, second]
+
+    monkeypatch.setattr(model_common, "_HF_CACHE_MODEL_FILE_PROBE_LIMIT", 3)
+
+    unbounded = model_common._iter_hf_cache_model_files(snapshot)
+
+    assert unbounded == [first, second, model]
+
+
+def test_download_state_lookup_is_repo_case_insensitive(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path)
+
+    assert download_manifest.write_manifest(
+        "model",
+        "Owner/Repo",
+        None,
+        [download_manifest.ExpectedFile(path = "config.json", size = 12)],
+    )
+    assert download_manifest.write_cancel_marker("model", "Owner/Repo", "Q4_K_M", "http")
+
+    manifest = download_manifest.read_manifest("model", "owner/repo", None)
+
+    assert manifest is not None
+    assert manifest.repo_id == "Owner/Repo"
+    assert manifest.expected_files[0].path == "config.json"
+    assert download_manifest.has_cancel_marker("model", "owner/repo", "Q4_K_M")
+    assert (
+        download_manifest.read_cancel_marker_transport(
+            "model",
+            "owner/repo",
+            "Q4_K_M",
+        )
+        == "http"
+    )
+    assert [
+        variant
+        for variant, _path in download_manifest.iter_variant_markers(
+            "model",
+            "owner/repo",
+        )
+    ] == ["Q4_K_M"]
+    assert download_manifest.purge_all_state_for_repo("model", "owner/repo") == 2
+    assert download_manifest.read_manifest("model", "owner/repo", None) is None
+
+
+def test_hf_cache_scan_fallback_row_uses_local_model_info_alias(monkeypatch, tmp_path):
+    cache_dir = tmp_path / "hub"
+    repo_dir = cache_dir / "models--Org--Broken"
+    blobs_dir = repo_dir / "blobs"
+    blobs_dir.mkdir(parents = True)
+    (blobs_dir / "blob").write_bytes(b"content")
+    monkeypatch.setattr(local_inventory, "_classify_local_path", lambda *_args, **_kwargs: [])
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "is_snapshot_partial",
+        lambda *_args, **_kwargs: False,
+    )
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "is_gguf_repo_partial",
+        lambda *_args, **_kwargs: False,
+    )
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "resolve_hf_cache_realpath",
+        lambda *_args, **_kwargs: None,
+    )
+
+    rows = local_inventory._scan_hf_cache(cache_dir)
+
+    assert len(rows) == 1
+    assert rows[0].model_id == "Org/Broken"
+    assert rows[0].source == "hf_cache"
+    assert rows[0].model_format == "unknown"
+
+
+def test_hf_cache_scan_uses_gguf_partial_row_for_variant_state(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    cache_dir = tmp_path / "hub"
+    repo_dir = cache_dir / "models--Org--PartialGguf"
+    blobs_dir = repo_dir / "blobs"
+    blobs_dir.mkdir(parents = True)
+    (blobs_dir / "partial").write_bytes(b"content")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/PartialGguf",
+        "Q4_K_M",
+        [download_manifest.ExpectedFile(path = "model-Q4_K_M.gguf", size = 8192)],
+        "http",
+    )
+    assert download_manifest.write_cancel_marker("model", "Org/PartialGguf", "Q4_K_M", "http")
+    monkeypatch.setattr(local_inventory, "_classify_local_path", lambda *_args, **_kwargs: [])
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "is_snapshot_partial",
+        lambda *_args, **_kwargs: False,
+    )
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "is_gguf_repo_partial",
+        lambda *_args, **_kwargs: True,
+    )
+    monkeypatch.setattr(
+        local_inventory.hf_cache_scan,
+        "resolve_hf_cache_realpath",
+        lambda *_args, **_kwargs: None,
+    )
+
+    rows = local_inventory._scan_hf_cache(cache_dir)
+
+    assert len(rows) == 1
+    assert rows[0].model_id == "Org/PartialGguf"
+    assert rows[0].source == "hf_cache"
+    assert rows[0].model_format == "gguf"
+    assert rows[0].partial is True
+    assert rows[0].size_bytes == 8192
+    assert rows[0].capabilities.requires_variant is True
+
+
+def test_model_download_job_helpers_preserve_idle_shape():
+    key = downloads._download_job_key("Org/Model", None)
+    status = downloads._job_status(key)
+
+    assert key == "org/model::"
+    assert status.state == "idle"
+    assert status.error is None
+
+
+def test_gguf_repo_partial_treats_completed_disk_variant_as_clean(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    snapshot = tmp_path / "cache" / "models--Org--Repo" / "snapshots" / "abc"
+    snapshot.mkdir(parents = True)
+    (snapshot / "model-Q8_0.gguf").write_bytes(b"complete")
+    assert download_manifest.write_cancel_marker("model", "Org/Repo", "Q4_K_M", "xet")
+    monkeypatch.setattr(
+        inventory_scan,
+        "resolve_snapshot_dir_for_scan",
+        lambda *_args: snapshot,
+    )
+
+    assert inventory_scan.is_gguf_repo_partial("Org/Repo", snapshot.parents[1]) is False
+
+
+def test_gguf_repo_partial_flags_vision_variant_missing_mmproj(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    snapshot = tmp_path / "cache" / "models--Org--Vision" / "snapshots" / "abc"
+    snapshot.mkdir(parents = True)
+    (snapshot / "model-Q4_K_M.gguf").write_bytes(b"complete-weight")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/Vision",
+        "Q4_K_M",
+        [
+            download_manifest.ExpectedFile(path = "model-Q4_K_M.gguf", size = 15),
+            download_manifest.ExpectedFile(path = "mmproj-F16.gguf", size = 8),
+        ],
+        "http",
+    )
+    monkeypatch.setattr(
+        inventory_scan,
+        "resolve_snapshot_dir_for_scan",
+        lambda *_args: snapshot,
+    )
+
+    assert inventory_scan.is_gguf_repo_partial("Org/Vision") is True
+
+
+def test_cancel_worker_leaves_exited_process_to_watcher():
+    calls: list = []
+
+    class _Registry:
+        def get_process(self, _key):
+            return SimpleNamespace(poll = lambda: 1)
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running")
+
+        def mark_pending_cancel(self, key, generation):
+            calls.append(("pending", key, generation))
+            return True
+
+        def request_cancel(self, key, proc, generation):
+            calls.append(("request", key, generation))
+            return True
+
+        def cancel_requested(self, _key):
+            return False
+
+    state = download_lifecycle.cancel_worker(
+        _Registry(),
+        "org/model::",
+        generation = 3,
+        label = "Org/Model",
+        logger = SimpleNamespace(warning = lambda *_a, **_k: None),
+    )
+
+    assert state == "running"
+    assert calls == []
+
+
+def test_completed_gguf_split_variant_requires_all_shards(tmp_path):
+    snapshot = tmp_path / "snapshot"
+    snapshot.mkdir()
+    first = snapshot / "model-Q8_0-00001-of-00002.gguf"
+    second = snapshot / "model-Q8_0-00002-of-00002.gguf"
+    first.write_bytes(b"first")
+
+    assert "Q8_0" not in inventory_scan._completed_gguf_variants(snapshot)
+
+    second.write_bytes(b"second")
+    assert "Q8_0" in inventory_scan._completed_gguf_variants(snapshot)
+
+
+def test_variant_partial_accepts_variant_filtered_legacy_hashes(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path)
+
+    assert inventory_scan.is_variant_partial(
+        "Org/Repo",
+        "Q4_K_M",
+        incomplete_blob_hashes = {"main-q4", "main-q8"},
+        variant_blob_hashes = frozenset({"main-q4"}),
+    )
+    assert not inventory_scan.is_variant_partial(
+        "Org/Repo",
+        "Q5_K_M",
+        incomplete_blob_hashes = {"main-q4"},
+        variant_blob_hashes = frozenset({"main-q5"}),
+    )
+
+
+def test_gguf_variants_partial_marker_overrides_size_only_downloaded(monkeypatch, tmp_path):
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    monkeypatch.setattr(gguf_variants.asyncio, "to_thread", _run_inline)
+    assert download_manifest.write_cancel_marker("model", "Org/PartialRepo", "Q4_K_M", "http")
+    snapshot = tmp_path / "cache" / "models--Org--PartialRepo" / "snapshots" / "rev0"
+    snapshot.mkdir(parents = True)
+    (snapshot / "model-Q4_K_M.gguf").write_bytes(b"x" * 100)
+
+    monkeypatch.setattr(
+        gguf_variants,
+        "list_gguf_variants",
+        lambda *_args, **_kwargs: (
+            [
+                SimpleNamespace(
+                    filename = "model-Q4_K_M.gguf",
+                    quant = "Q4_K_M",
+                    display_label = None,
+                    size_bytes = 100,
+                )
+            ],
+            False,
+            None,
+        ),
+    )
+    monkeypatch.setattr(
+        gguf_variants,
+        "iter_hf_cache_snapshots",
+        lambda _repo_id: [snapshot],
+    )
+    monkeypatch.setattr(
+        gguf_variants,
+        "_gguf_all_variant_requirements",
+        lambda *_args, **_kwargs: {},
+    )
+    monkeypatch.setattr(
+        gguf_variants.download_registry,
+        "incomplete_blob_hashes",
+        lambda *_args, **_kwargs: set(),
+    )
+
+    result = asyncio.run(gguf_variants.get_gguf_variants_response("Org/PartialRepo"))
+
+    assert result.variants[0].downloaded is False
+    assert result.variants[0].partial is True
+
+
+def test_download_registry_repo_keys_are_case_insensitive():
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+    )
+    # The same variant under a different-cased repo id resolves to the same
+    # job, so the second claim attaches to the running one instead of starting
+    # a duplicate.
+    duplicate_claimed, duplicate_state = registry.claim(
+        "org/repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "org/repo",
+        variant = "Q8_0",
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert duplicate_claimed is False
+    assert duplicate_state == "running"
+    assert registry.active_jobs("ORG/REPO") == {"org/repo::Q8_0": "running"}
+
+
+def test_download_registry_allows_disjoint_gguf_variant_downloads():
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+        blob_hashes = frozenset({"q8-main"}),
+        progress_blob_hashes = frozenset({"q8-main", "shared-mmproj"}),
+    )
+    second_claimed, second_state = registry.claim(
+        "Org/Repo::Q4_K_M",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+        blob_hashes = frozenset({"q4-main"}),
+        progress_blob_hashes = frozenset({"q4-main", "shared-mmproj"}),
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert second_claimed is True
+    assert second_state == "running"
+    assert registry.active_jobs("org/repo") == {
+        "org/repo::Q8_0": "running",
+        "org/repo::Q4_K_M": "running",
+    }
+
+
+def test_download_registry_allows_overlapping_same_transport_variant_downloads():
+    # Two variants sharing one mmproj blob still download together on one
+    # transport: huggingface_hub's per-blob lock serializes the shared write and
+    # prepare_cache_for_transport never purges a blob a peer is writing.
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+        blob_hashes = frozenset({"q8-main"}),
+        progress_blob_hashes = frozenset({"q8-main", "shared-mmproj"}),
+    )
+    second_claimed, second_state = registry.claim(
+        "Org/Repo::Q4_K_M",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+        blob_hashes = frozenset({"q4-main"}),
+        progress_blob_hashes = frozenset({"q4-main", "shared-mmproj"}),
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert second_claimed is True
+    assert second_state == "running"
+
+
+def test_download_registry_variant_delete_does_not_block_sibling_download():
+    # Deleting one quant's partial must be allowed while a different quant of the
+    # same repo is downloading, and must protect every blob the live sibling is
+    # writing (including a shared mmproj companion).
+    registry = download_registry.DownloadRegistry()
+    registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+        blob_hashes = frozenset({"q8-main"}),
+        progress_blob_hashes = frozenset({"q8-main", "shared-mmproj"}),
+    )
+
+    # A sibling variant delete is allowed; deleting the in-flight variant is not.
+    assert registry.begin_delete("Org/Repo", "Q4_K_M") is True
+    assert registry.begin_delete("Org/Repo", "Q8_0") is False
+    # A whole-repo delete still waits for every active download.
+    assert registry.begin_delete("Org/Repo") is False
+
+    # The live sibling is detected so the delete keeps the shared companion.
+    assert registry.has_active_peer_variant("Org/Repo", "Q4_K_M") is True
+    assert registry.has_active_peer_variant("Org/Repo", "Q8_0") is False
+
+    # While Q4_K_M is being deleted, re-downloading it is blocked but an
+    # untouched third variant may still start.
+    blocked, blocked_state = registry.claim(
+        "Org/Repo::Q4_K_M",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+    )
+    assert blocked is False
+    assert blocked_state == "deleting"
+    started, started_state = registry.claim(
+        "Org/Repo::Q5_K_M",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q5_K_M",
+    )
+    assert started is True
+    assert started_state == "running"
+
+    registry.end_delete("Org/Repo", "Q4_K_M")
+    assert registry.begin_delete("Org/Repo", "Q4_K_M") is True
+
+
+def test_partial_gguf_reconstruction_dedupes_variant_casing(monkeypatch):
+    # The manifest keeps original casing while the marker is lowercased; offline
+    # reconstruction must collapse them to ONE entry (manifest's casing), not two.
+    monkeypatch.setattr(
+        download_manifest,
+        "iter_variant_manifests",
+        lambda _repo_type, _repo_id: iter([("Q4_K_M", Path("manifest.json"))]),
+    )
+    monkeypatch.setattr(
+        download_manifest,
+        "iter_variant_markers",
+        lambda _repo_type, _repo_id: iter([("q4_k_m", Path("marker.json"))]),
+    )
+    monkeypatch.setattr(download_manifest, "read_manifest", lambda *_a, **_k: None)
+
+    result = gguf.list_partial_gguf_variants_from_state("Org/Repo")
+
+    assert result is not None
+    variants, _has_vision = result
+    assert [variant.quant for variant in variants] == ["Q4_K_M"]
+
+
+def test_download_registry_serializes_cross_transport_variant_downloads():
+    # An HTTP append-resume and an XET rewrite of the same shared blob would
+    # corrupt each other, so different-transport variants are serialized.
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+        blob_hashes = frozenset({"q8-main"}),
+        progress_blob_hashes = frozenset({"q8-main", "shared-mmproj"}),
+    )
+    second_claimed, second_state = registry.claim(
+        "Org/Repo::Q4_K_M",
+        download_registry.TRANSPORT_XET,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+        blob_hashes = frozenset({"q4-main"}),
+        progress_blob_hashes = frozenset({"q4-main", "shared-mmproj"}),
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert second_claimed is False
+    assert second_state == "running"
+
+
+def test_download_registry_allows_unknown_hash_gguf_variant_downloads():
+    # Resolved blob hashes are NOT required to run two same-transport variants
+    # concurrently: on-disk safety comes from each worker purging only its own
+    # main-quant blobs plus huggingface_hub's per-etag lock. Requiring them here
+    # used to reject the second variant whenever a metadata fetch flaked.
+    registry = download_registry.DownloadRegistry()
+
+    claimed, state = registry.claim(
+        "Org/Repo::Q8_0",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q8_0",
+    )
+    second_claimed, second_state = registry.claim(
+        "Org/Repo::Q4_K_M",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+        blob_hashes = frozenset({"q4-main"}),
+        progress_blob_hashes = frozenset({"q4-main", "shared-mmproj"}),
+    )
+
+    assert claimed is True
+    assert state == "running"
+    assert second_claimed is True
+    assert second_state == "running"
+    assert registry.active_jobs("org/repo") == {
+        "org/repo::Q8_0": "running",
+        "org/repo::Q4_K_M": "running",
+    }
+
+
+def test_finalize_worker_exit_never_kills_a_healthy_worker(monkeypatch, tmp_path):
+    # finalize_worker_exit relies solely on the worker's exit code and never kills
+    # a live process: huggingface_hub already bounds reads with timeouts, so a
+    # liveness kill could only false-cancel a healthy download.
+    import inspect
+    import io
+    import logging
+
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+
+    class _Proc:
+        pid = 4242
+
+        def __init__(self):
+            self.killed = False
+            self.stderr = io.BytesIO(b"")
+
+        def poll(self):
+            return 0
+
+        def wait(self, timeout = None):
+            return 0
+
+        def kill(self):
+            self.killed = True
+
+    registry = download_registry.DownloadRegistry()
+    proc = _Proc()
+    key = "Org/Repo::Q4_K_M"
+    registry.claim(
+        key,
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        variant = "Q4_K_M",
+    )
+    registry.register_process(key, proc)
+
+    download_lifecycle.finalize_worker_exit(
+        registry,
+        key,
+        proc,
+        hf_token = None,
+        label = "Org/Repo [Q4_K_M]",
+        log_prefix = "Download",
+        logger = logging.getLogger("test"),
+        repo_type = "model",
+        repo_id = "Org/Repo",
+        transport = "http",
+    )
+
+    assert proc.killed is False
+    assert registry.get_job(key).state == "complete"
+    # The stall-watchdog knob is gone entirely; no caller may re-enable it.
+    assert (
+        "enable_stall_watchdog"
+        not in inspect.signature(download_lifecycle.finalize_worker_exit).parameters
+    )
+
+
+def test_prepare_cache_for_transport_purges_only_requested_hashes(monkeypatch, tmp_path):
+    root = tmp_path / "hub"
+    blobs = root / "models--Org--Repo" / "blobs"
+    blobs.mkdir(parents = True)
+    (blobs / "variant-main.incomplete").write_bytes(b"x")
+    (blobs / "shared-mmproj.incomplete").write_bytes(b"y")
+    monkeypatch.setattr(download_registry, "hf_cache_root", lambda create = False: root)
+
+    purged = download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Repo",
+        download_registry.TRANSPORT_XET,
+        "Q4_K_M",
+        frozenset({"variant-main"}),
+    )
+
+    assert purged == 1
+    assert not (blobs / "variant-main.incomplete").exists()
+    assert (blobs / "shared-mmproj.incomplete").exists()
+
+
+def _vision_cache_root(monkeypatch, tmp_path):
+    root = tmp_path / "hub"
+    blobs = root / "models--Org--Vision" / "blobs"
+    blobs.mkdir(parents = True)
+    monkeypatch.setattr(download_registry, "hf_cache_root", lambda create = False: root)
+    return blobs
+
+
+def test_prepare_cache_for_transport_purges_cross_transport_companion(monkeypatch, tmp_path):
+    blobs = _vision_cache_root(monkeypatch, tmp_path)
+    companion = frozenset({"shared-mmproj"})
+
+    # An interrupted XET download stamps the companion marker "xet" and leaves a
+    # sparse partial. A later HTTP download of a different variant must purge it,
+    # else the HTTP resumer appends to the sparse bytes and corrupts the blob.
+    download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_XET,
+        "Q4_K_M",
+        only_blob_hashes = frozenset({"q4-main"}),
+        companion_blob_hashes = companion,
+    )
+    (blobs / "shared-mmproj.incomplete").write_bytes(b"sparse")
+
+    purged = download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_HTTP,
+        "Q8_0",
+        only_blob_hashes = frozenset({"q8-main"}),
+        companion_blob_hashes = companion,
+    )
+
+    assert purged == 1
+    assert not (blobs / "shared-mmproj.incomplete").exists()
+
+
+def test_prepare_cache_for_transport_preserves_same_transport_companion(monkeypatch, tmp_path):
+    blobs = _vision_cache_root(monkeypatch, tmp_path)
+    companion = frozenset({"shared-mmproj"})
+
+    download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_HTTP,
+        "Q4_K_M",
+        only_blob_hashes = frozenset({"q4-main"}),
+        companion_blob_hashes = companion,
+    )
+    (blobs / "shared-mmproj.incomplete").write_bytes(b"resumable")
+
+    purged = download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_HTTP,
+        "Q4_K_M",
+        only_blob_hashes = frozenset({"q4-main"}),
+        companion_blob_hashes = companion,
+    )
+
+    assert purged == 0
+    assert (blobs / "shared-mmproj.incomplete").exists()
+
+
+def test_prepare_cache_for_transport_protects_peer_companion(monkeypatch, tmp_path):
+    blobs = _vision_cache_root(monkeypatch, tmp_path)
+    companion = frozenset({"shared-mmproj"})
+
+    download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_XET,
+        "Q4_K_M",
+        only_blob_hashes = frozenset({"q4-main"}),
+        companion_blob_hashes = companion,
+    )
+    (blobs / "shared-mmproj.incomplete").write_bytes(b"sparse")
+
+    purged = download_registry.prepare_cache_for_transport(
+        "model",
+        "Org/Vision",
+        download_registry.TRANSPORT_HTTP,
+        "Q8_0",
+        only_blob_hashes = frozenset({"q8-main"}),
+        companion_blob_hashes = companion,
+        protected_blob_hashes = companion,
+    )
+
+    assert purged == 0
+    assert (blobs / "shared-mmproj.incomplete").exists()
+
+
+def test_model_download_records_completed_baseline_for_new_gguf_variant(monkeypatch, tmp_path):
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, repo_type = "model": repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda _repo, _variant, _token = None, include_companions = True, **_kwargs: (
+            frozenset({"mainhash", "mmprojhash"}) if include_companions else frozenset({"mainhash"})
+        ),
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "completed_blob_bytes",
+        lambda *_args, **_kwargs: 30,
+    )
+
+    class _Registry:
+        claim_kwargs = None
+
+        def claim(self, _key, _transport, **kwargs):
+            self.claim_kwargs = kwargs
+            return True, "running"
+
+        def current_generation(self, _key):
+            return 1
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running")
+
+        def register_process(self, _key, _proc):
+            return False
+
+        def peer_blob_hashes(self, _key):
+            return frozenset()
+
+    class _Proc:
+        pid = 123
+        stderr = None
+
+        def poll(self):
+            return None
+
+        def kill(self):
+            return None
+
+        def wait(self, timeout = None):
+            return 0
+
+    registry = _Registry()
+    monkeypatch.setattr(downloads, "_registry", registry)
+    monkeypatch.setattr(downloads, "_spawn_download_worker", lambda *_args, **_kwargs: _Proc())
+
+    asyncio.run(
+        downloads.download_model_response(
+            SimpleNamespace(repo_id = "Org/Model", gguf_variant = "Q4_K_M", use_xet = False)
+        )
+    )
+
+    assert registry.claim_kwargs["blob_hashes"] == frozenset({"mainhash"})
+    assert registry.claim_kwargs["progress_blob_hashes"] == frozenset({"mainhash", "mmprojhash"})
+    assert registry.claim_kwargs["completed_baseline_bytes"] == 30
+
+
+def test_gguf_model_download_skips_completed_baseline_for_variant_resume_state(
+    monkeypatch, tmp_path
+):
+    async def _run_inline(fn, *args, **kwargs):
+        return fn(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _run_inline)
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    assert download_manifest.write_manifest(
+        "model",
+        "Org/Model",
+        "Q4_K_M",
+        [
+            download_manifest.ExpectedFile(
+                path = "model-Q4_K_M.gguf",
+                size = 100,
+                sha256 = "mainhash",
+            )
+        ],
+        "http",
+    )
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, repo_type = "model": repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda _repo, _variant, _token = None, include_companions = True, **_kwargs: (
+            frozenset({"mainhash", "mmprojhash"}) if include_companions else frozenset({"mainhash"})
+        ),
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "completed_blob_bytes",
+        lambda *_args, **_kwargs: 30,
+    )
+
+    class _Registry:
+        claim_kwargs = None
+
+        def claim(self, _key, _transport, **kwargs):
+            self.claim_kwargs = kwargs
+            return True, "running"
+
+        def current_generation(self, _key):
+            return 1
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running")
+
+        def register_process(self, _key, _proc):
+            return False
+
+        def peer_blob_hashes(self, _key):
+            return frozenset()
+
+    class _Proc:
+        pid = 123
+        stderr = None
+
+        def poll(self):
+            return None
+
+        def kill(self):
+            return None
+
+        def wait(self, timeout = None):
+            return 0
+
+    registry = _Registry()
+    monkeypatch.setattr(downloads, "_registry", registry)
+    monkeypatch.setattr(downloads, "_spawn_download_worker", lambda *_args, **_kwargs: _Proc())
+
+    asyncio.run(
+        downloads.download_model_response(
+            SimpleNamespace(repo_id = "Org/Model", gguf_variant = "Q4_K_M", use_xet = False)
+        )
+    )
+
+    assert registry.claim_kwargs["completed_baseline_bytes"] == 0
+
+
+def test_model_idle_status_uses_cancel_marker_after_restart(monkeypatch, tmp_path):
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path)
+    monkeypatch.setattr(downloads, "_registry", download_registry.DownloadRegistry())
+    assert download_manifest.write_cancel_marker("model", "Owner/Repo", "Q4_K_M", "http")
+
+    status = asyncio.run(downloads.get_download_status_response("owner/repo", "Q4_K_M"))
+
+    assert status.state == "cancelled"
+    assert status.error is None
+
+
+def test_shutdown_kills_all_workers_before_shared_deadline_reap(monkeypatch):
+    events = []
+    now = [100.0]
+
+    class _Proc:
+        def __init__(self, name):
+            self.name = name
+
+        def poll(self):
+            return None
+
+        def kill(self):
+            events.append(("kill", self.name))
+
+        def wait(self, timeout):
+            events.append(("wait", self.name, timeout))
+            now[0] += 7.0
+
+    registry = download_registry.DownloadRegistry()
+    proc_a = _Proc("a")
+    proc_b = _Proc("b")
+    registry.claim(
+        "Org/A",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "Org/A",
+    )
+    registry.claim(
+        "Org/B",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "Org/B",
+    )
+    assert registry.register_process("org/a", proc_a)
+    assert registry.register_process("org/b", proc_b)
+    monkeypatch.setattr(
+        download_registry,
+        "persist_cancel_marker",
+        lambda *args, **kwargs: events.append(("marker", args[1])),
+    )
+    monkeypatch.setattr(download_registry.time, "monotonic", lambda: now[0])
+
+    registry.terminate_all("dataset download")
+
+    assert events == [
+        ("kill", "a"),
+        ("kill", "b"),
+        ("wait", "a", 10.0),
+        ("marker", "Org/A"),
+        ("wait", "b", 3.0),
+        ("marker", "Org/B"),
+    ]
+
+
+def test_shutdown_skips_marker_for_worker_that_exits_cleanly(monkeypatch):
+    markers = []
+
+    class _Proc:
+        def __init__(self, final_rc):
+            self._final_rc = final_rc
+            self._exited = False
+
+        def poll(self):
+            return self._final_rc if self._exited else None
+
+        def kill(self):
+            pass
+
+        def wait(self, timeout):
+            self._exited = True
+
+    registry = download_registry.DownloadRegistry()
+    clean = _Proc(0)
+    interrupted = _Proc(-9)
+    registry.claim(
+        "Org/Clean",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "Org/Clean",
+    )
+    registry.claim(
+        "Org/Cut",
+        download_registry.TRANSPORT_HTTP,
+        repo_type = "dataset",
+        repo_id = "Org/Cut",
+    )
+    assert registry.register_process("org/clean", clean)
+    assert registry.register_process("org/cut", interrupted)
+    monkeypatch.setattr(
+        download_registry,
+        "persist_cancel_marker",
+        lambda *args, **kwargs: markers.append(args[1]),
+    )
+
+    registry.terminate_all("dataset download")
+
+    assert markers == ["Org/Cut"]
+
+
+def test_model_claim_register_cancel_uses_registry_marker_owner(monkeypatch):
+    killed = []
+
+    class _Registry:
+        def claim(self, *_args, **_kwargs):
+            return True, "running"
+
+        def current_generation(self, _key):
+            return 1
+
+        def register_process(self, _key, _proc):
+            return False
+
+        def persist_cancel_for_key(self, *_args, **_kwargs):
+            raise AssertionError("register_process owns pending-cancel markers")
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "cancelled", error = None)
+
+    monkeypatch.setattr(downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "download_transport_unavailable_reason",
+        lambda _transport: None,
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_spawn_download_worker",
+        lambda *_args, **_kwargs: object(),
+    )
+    monkeypatch.setattr(
+        downloads.download_lifecycle,
+        "kill_and_reap_process",
+        lambda proc, **_kwargs: killed.append(proc),
+    )
+
+    result = asyncio.run(
+        downloads.download_model_response(
+            SimpleNamespace(repo_id = "Org/Model", gguf_variant = None, use_xet = False)
+        )
+    )
+
+    assert result["state"] == "cancelled"
+    assert killed
+
+
+def test_model_cancel_registered_worker_requests_and_kills(monkeypatch):
+    events = []
+
+    class _Proc:
+        def poll(self):
+            return None
+
+        def kill(self):
+            events.append(("kill",))
+
+    class _Registry:
+        def get_process(self, _key):
+            return _Proc()
+
+        def request_cancel(self, key, _proc, generation):
+            events.append(("request", key, generation))
+            return True
+
+        def persist_cancel_for_key(self, *_args, **_kwargs):
+            raise AssertionError(
+                "cancel_worker must leave marker persistence to the exit watcher; "
+                "an eager persist races a clean completion and strands a stale marker"
+            )
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running")
+
+    monkeypatch.setattr(downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+
+    result = asyncio.run(
+        downloads.cancel_download_model_response(
+            SimpleNamespace(repo_id = "Org/Model", gguf_variant = "Q4_K_M", generation = 7)
+        )
+    )
+
+    assert result == {
+        "job_key": downloads._download_job_key("Org/Model", "Q4_K_M"),
+        "state": "cancelling",
+    }
+    assert events == [
+        ("request", downloads._download_job_key("Org/Model", "Q4_K_M"), 7),
+        ("kill",),
+    ]
+
+
+def test_model_download_watcher_invalidates_hf_cache_scan(monkeypatch):
+    invalidated = []
+
+    class _Registry:
+        def claim(self, *_args, **_kwargs):
+            return True, "running"
+
+        def current_generation(self, _key):
+            return 1
+
+        def register_process(self, _key, _proc):
+            return True
+
+        def get_job(self, _key):
+            return SimpleNamespace(state = "complete", error = None)
+
+    class _ImmediateThread:
+        def __init__(self, *, target, **_kwargs):
+            self._target = target
+
+        def start(self):
+            self._target()
+
+    monkeypatch.setattr(downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "download_transport_unavailable_reason",
+        lambda _transport: None,
+    )
+    monkeypatch.setattr(
+        downloads.download_lifecycle,
+        "finalize_worker_exit",
+        lambda *_args, **_kwargs: None,
+    )
+    monkeypatch.setattr(
+        downloads,
+        "_spawn_download_worker",
+        lambda *_args, **_kwargs: object(),
+    )
+    monkeypatch.setattr(downloads.download_lifecycle.threading, "Thread", _ImmediateThread)
+    monkeypatch.setattr(
+        downloads.hf_cache_scan,
+        "invalidate_hf_cache_scans",
+        lambda: invalidated.append(True),
+    )
+
+    async def _inline_to_thread(func, *args, **kwargs):
+        return func(*args, **kwargs)
+
+    monkeypatch.setattr(downloads.asyncio, "to_thread", _inline_to_thread)
+
+    result = asyncio.run(
+        downloads.download_model_response(
+            SimpleNamespace(repo_id = "Org/Model", gguf_variant = None, use_xet = False)
+        )
+    )
+
+    assert result["accepted"] is True
+    assert invalidated == [True]
+
+
+def test_two_concurrent_same_repo_variants_both_complete(monkeypatch, tmp_path):
+    # End-to-end proof that two GGUF variants of ONE repo download concurrently
+    # without cancelling each other, with real registry/finalize/subprocess/watch
+    # threads exercising the claim gate, register, finalize funnel, and
+    # classify_exit under true concurrency.
+    import subprocess
+    import time
+
+    monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "state")
+    monkeypatch.setattr(
+        downloads,
+        "_registry",
+        download_registry.DownloadRegistry(),
+    )
+    monkeypatch.setattr(
+        downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_k: repo_id,
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "download_transport_unavailable_reason",
+        lambda _transport: None,
+    )
+    # Per-variant blob hashes (distinct main shard, shared mmproj companion).
+    monkeypatch.setattr(
+        downloads.gguf_variants,
+        "gguf_variant_blob_hashes",
+        lambda _repo, variant, _token = None, include_companions = True, **_k: (
+            frozenset({f"{variant.lower()}-main", "shared-mmproj"})
+            if include_companions
+            else frozenset({f"{variant.lower()}-main"})
+        ),
+    )
+    monkeypatch.setattr(
+        downloads.download_registry,
+        "completed_blob_bytes",
+        lambda *_a, **_k: 0,
+    )
+    monkeypatch.setattr(
+        downloads.hf_cache_scan,
+        "invalidate_hf_cache_scans",
+        lambda: None,
+    )
+    # Real subprocess that exits 0 immediately, with a stderr pipe to drain.
+    spawned: list[subprocess.Popen] = []
+
+    def _fake_spawn(*_args, **_kwargs):
+        proc = subprocess.Popen(
+            [sys.executable, "-c", "import sys; sys.exit(0)"],
+            stderr = subprocess.PIPE,
+        )
+        spawned.append(proc)
+        return proc
+
+    monkeypatch.setattr(downloads, "_spawn_download_worker", _fake_spawn)
+
+    async def _run_both():
+        return await asyncio.gather(
+            downloads.download_model_response(
+                SimpleNamespace(
+                    repo_id = "Org/Model",
+                    gguf_variant = "Q4_K_M",
+                    use_xet = False,
+                )
+            ),
+            downloads.download_model_response(
+                SimpleNamespace(
+                    repo_id = "Org/Model",
+                    gguf_variant = "Q8_0",
+                    use_xet = False,
+                )
+            ),
+        )
+
+    results = asyncio.run(_run_both())
+    assert all(r["accepted"] is True for r in results), results
+
+    registry = downloads._registry
+    key_q4 = downloads._download_job_key("Org/Model", "Q4_K_M")
+    key_q8 = downloads._download_job_key("Org/Model", "Q8_0")
+    deadline = time.monotonic() + 10.0
+    while time.monotonic() < deadline:
+        s4 = registry.get_job(key_q4).state
+        s8 = registry.get_job(key_q8).state
+        if s4 in download_registry.TERMINAL_STATES and s8 in download_registry.TERMINAL_STATES:
+            break
+        time.sleep(0.02)
+
+    for p in spawned:
+        try:
+            p.wait(timeout = 5)
+        except Exception:
+            pass
+
+    assert registry.get_job(key_q4).state == "complete"
+    assert registry.get_job(key_q8).state == "complete"
+
+
+def test_download_registry_factories_reuse_service_singletons():
+    registry_module = downloads.download_registry
+    before_count = len(registry_module._REGISTRIES)
+
+    assert registry_module.get_models_registry() is downloads.registry
+    assert registry_module.get_models_registry() is downloads.registry
+    assert registry_module.get_datasets_registry() is dataset_downloads.registry
+    assert registry_module.get_datasets_registry() is dataset_downloads.registry
+    assert len(registry_module._REGISTRIES) == before_count
+
+
+def test_hub_hf_token_header_uses_namespaced_header_only():
+    assert get_hf_token("new-token") == "new-token"
+    assert get_hf_token(None) is None
+
+
+def test_scan_folder_rejects_credential_directories(tmp_path):
+    sensitive_dir = tmp_path / ".ssh" / "models"
+    sensitive_dir.mkdir(parents = True)
+
+    with pytest.raises(ValueError, match = "Credential or configuration"):
+        scan_folders.add_scan_folder(str(sensitive_dir))
+
+
+def _build_variant_cache_repo(repo_dir, blob_specs, snapshot_links):
+    """Build a HF cache repo dir with blobs + snapshot symlinks for the
+    per-variant deletion path. blob_specs: {blob_name: bytes_payload};
+    snapshot_links: list of (revision, filename, blob_name)."""
+    blobs_dir = repo_dir / "blobs"
+    blobs_dir.mkdir(parents = True)
+    for blob_name, payload in blob_specs.items():
+        (blobs_dir / blob_name).write_bytes(payload)
+
+    files = []
+    for revision, filename, blob_name in snapshot_links:
+        snap_dir = repo_dir / "snapshots" / revision
+        snap_dir.mkdir(parents = True, exist_ok = True)
+        blob = blobs_dir / blob_name
+        link = snap_dir / filename
+        link.symlink_to(blob)
+        files.append(
+            SimpleNamespace(
+                file_name = filename,
+                file_path = str(link),
+                blob_path = str(blob),
+                size_on_disk = blob.stat().st_size,
+            )
+        )
+    repo = SimpleNamespace(
+        repo_id = "Org/Repo-GGUF",
+        repo_type = "model",
+        repo_path = repo_dir,
+        revisions = [SimpleNamespace(commit_hash = "rev1", files = files)],
+    )
+    return repo
+
+
+def _patch_variant_delete_side_effects(monkeypatch):
+    monkeypatch.setattr(
+        deletion.download_manifest,
+        "purge_state",
+        lambda *_args, **_kwargs: False,
+    )
+
+
+def test_snapshot_progress_filters_stale_blobs(monkeypatch, tmp_path):
+    """Exclude superseded-revision blobs; count an in-progress blob only when its
+    hash belongs to the target."""
+    entry = tmp_path / "datasets--Org--Data"
+    blobs = entry / "blobs"
+    blobs.mkdir(parents = True)
+    (blobs / "keep1").write_bytes(b"a" * 100)
+    (blobs / "stale").write_bytes(b"b" * 500)
+    (blobs / "keep2.incomplete").write_bytes(b"c" * 40)
+
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda _repo_type, _repo_id, force_active = False: [entry],
+    )
+
+    result = snapshot_progress.compute_snapshot_progress(
+        repo_type = "dataset",
+        repo_id = "Org/Data",
+        job_key = "org/data",
+        expected_bytes = 0,
+        hf_token = None,
+        registry = SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "running"),
+        ),
+        metadata_resolver = lambda _repo_id, _hf_token: (
+            140,
+            frozenset({"keep1", "keep2"}),
+        ),
+    )
+
+    assert result["completed_bytes"] == 100
+    assert result["downloaded_bytes"] == 140
+    assert result["complete_on_disk"] is False
+    assert result["expected_bytes"] == 140
+
+
+def test_snapshot_progress_confirms_complete_only_with_verified_snapshot(monkeypatch, tmp_path):
+    entry = tmp_path / "models--Org--Model"
+    blobs = entry / "blobs"
+    snap = entry / "snapshots" / "rev0"
+    blobs.mkdir(parents = True)
+    snap.mkdir(parents = True)
+    (blobs / "keep1").write_bytes(b"a" * 100)
+    (snap / "model.safetensors").write_bytes(b"a" * 100)
+
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda _repo_type, _repo_id, force_active = False: [entry],
+    )
+    monkeypatch.setattr(
+        snapshot_progress.download_manifest,
+        "has_cancel_marker",
+        lambda *_args, **_kwargs: False,
+    )
+    monkeypatch.setattr(
+        snapshot_progress.download_manifest,
+        "read_manifest",
+        lambda *_args, **_kwargs: SimpleNamespace(),
+    )
+    monkeypatch.setattr(
+        snapshot_progress.download_manifest,
+        "verify_against_disk",
+        lambda *_args, **_kwargs: SimpleNamespace(ok = True),
+    )
+
+    result = snapshot_progress.compute_snapshot_progress(
+        repo_type = "model",
+        repo_id = "Org/Model",
+        job_key = "org/model::",
+        expected_bytes = 100,
+        hf_token = None,
+        registry = SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "idle"),
+        ),
+        metadata_resolver = lambda _repo_id, _hf_token: (
+            100,
+            frozenset({"keep1"}),
+        ),
+    )
+
+    assert result["completed_bytes"] == 100
+    assert result["complete_on_disk"] is True
+
+
+def test_expected_files_from_snapshot_dir_records_relative_paths_and_sizes(tmp_path):
+    snap = tmp_path / "snapshots" / "rev0"
+    (snap / "nested").mkdir(parents = True)
+    (snap / "model.safetensors").write_bytes(b"a" * 12)
+    (snap / "nested" / "config.json").write_bytes(b"b" * 3)
+
+    files = download_manifest.expected_files_from_snapshot_dir(snap)
+
+    by_path = {f.path: f for f in files}
+    assert by_path["model.safetensors"].size == 12
+    assert by_path["nested/config.json"].size == 3
+    assert all(f.sha256 is None for f in files)
+
+
+def test_snapshot_progress_complete_with_manifest_synthesized_from_disk(monkeypatch, tmp_path):
+    """A finished snapshot whose only manifest was synthesized from on-disk files
+    still verifies as complete, so a refresh finalizes it instead of capping at
+    99% and evicting it as gone."""
+    entry = tmp_path / "models--Org--Model"
+    blobs = entry / "blobs"
+    snap = entry / "snapshots" / "rev0"
+    blobs.mkdir(parents = True)
+    snap.mkdir(parents = True)
+    (blobs / "keep1").write_bytes(b"a" * 100)
+    (snap / "model.safetensors").write_bytes(b"a" * 100)
+
+    synthesized = download_manifest.expected_files_from_snapshot_dir(snap)
+    manifest = download_manifest.Manifest(
+        repo_type = "model",
+        repo_id = "Org/Model",
+        variant = None,
+        started_at = "",
+        expected_files = tuple(synthesized),
+    )
+
+    monkeypatch.setattr(
+        snapshot_progress,
+        "preferred_repo_cache_dirs",
+        lambda _repo_type, _repo_id, force_active = False: [entry],
+    )
+    monkeypatch.setattr(
+        snapshot_progress.download_manifest,
+        "has_cancel_marker",
+        lambda *_args, **_kwargs: False,
+    )
+    monkeypatch.setattr(
+        snapshot_progress.download_manifest,
+        "read_manifest",
+        lambda *_args, **_kwargs: manifest,
+    )
+
+    result = snapshot_progress.compute_snapshot_progress(
+        repo_type = "model",
+        repo_id = "Org/Model",
+        job_key = "org/model::",
+        expected_bytes = 100,
+        hf_token = None,
+        registry = SimpleNamespace(
+            get_job = lambda _key: SimpleNamespace(state = "idle"),
+        ),
+        metadata_resolver = lambda _repo_id, _hf_token: (
+            100,
+            frozenset({"keep1"}),
+        ),
+    )
+
+    assert result["complete_on_disk"] is True
+    assert result["progress"] == 1.0
+
+
+def test_delete_variant_keeps_blob_shared_with_other_snapshot(monkeypatch, tmp_path):
+    """A blob still referenced by a non-target snapshot symlink survives so that
+    symlink doesn't dangle (which the scanner reports as partial)."""
+    repo_dir = tmp_path / "models--Org--Repo-GGUF"
+    repo = _build_variant_cache_repo(
+        repo_dir,
+        blob_specs = {"sharedblob": b"x" * 200, "q8blob": b"y" * 300},
+        snapshot_links = [
+            ("rev1", "model-Q4_K_M.gguf", "sharedblob"),
+            ("rev1", "model-Q8_0.gguf", "q8blob"),
+            # An unrelated file that happens to share Q4's blob content.
+            ("rev1", "extra-copy.gguf", "sharedblob"),
+        ],
+    )
+    monkeypatch.setattr(
+        deletion.cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [repo])],
+    )
+    _patch_variant_delete_side_effects(monkeypatch)
+
+    result = deletion._delete_cached_model_blocking("Org/Repo-GGUF", "Q4_K_M", None)
+
+    assert result["status"] == "deleted"
+    # Q4 snapshot link gone, but its blob survives (extra-copy still links it).
+    assert not (repo_dir / "snapshots" / "rev1" / "model-Q4_K_M.gguf").exists()
+    assert (repo_dir / "blobs" / "sharedblob").exists()
+    extra = repo_dir / "snapshots" / "rev1" / "extra-copy.gguf"
+    assert extra.is_symlink() and extra.exists()  # not dangling
+
+
+def test_delete_variant_unlinks_unshared_blob(monkeypatch, tmp_path):
+    repo_dir = tmp_path / "models--Org--Repo-GGUF"
+    repo = _build_variant_cache_repo(
+        repo_dir,
+        blob_specs = {"q4blob": b"x" * 200, "q8blob": b"y" * 300},
+        snapshot_links = [
+            ("rev1", "model-Q4_K_M.gguf", "q4blob"),
+            ("rev1", "model-Q8_0.gguf", "q8blob"),
+        ],
+    )
+    monkeypatch.setattr(
+        deletion.cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [repo])],
+    )
+    _patch_variant_delete_side_effects(monkeypatch)
+
+    result = deletion._delete_cached_model_blocking("Org/Repo-GGUF", "Q4_K_M", None)
+
+    assert result["status"] == "deleted"
+    assert not (repo_dir / "blobs" / "q4blob").exists()
+    # Untouched sibling variant remains fully intact.
+    assert (repo_dir / "blobs" / "q8blob").exists()
+    q8 = repo_dir / "snapshots" / "rev1" / "model-Q8_0.gguf"
+    assert q8.is_symlink() and q8.exists()
+
+
+def test_delete_variant_surfaces_locked_file_as_conflict(monkeypatch, tmp_path):
+    """A blob unlink that fails (e.g. a Windows file lock on a loaded model)
+    must raise a clear 409, not report a misleading success."""
+    repo_dir = tmp_path / "models--Org--Repo-GGUF"
+    repo = _build_variant_cache_repo(
+        repo_dir,
+        blob_specs = {"lockedblob": b"x" * 200},
+        snapshot_links = [("rev1", "model-Q4_K_M.gguf", "lockedblob")],
+    )
+    monkeypatch.setattr(
+        deletion.cache_inventory,
+        "all_hf_cache_scans",
+        lambda: [SimpleNamespace(repos = [repo])],
+    )
+    _patch_variant_delete_side_effects(monkeypatch)
+
+    real_unlink = Path.unlink
+
+    def fake_unlink(self, *args, **kwargs):
+        if self.name == "lockedblob":
+            raise PermissionError("file in use")
+        return real_unlink(self, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "unlink", fake_unlink)
+
+    with pytest.raises(HTTPException) as exc_info:
+        deletion._delete_cached_model_blocking("Org/Repo-GGUF", "Q4_K_M", None)
+
+    assert exc_info.value.status_code == 409
+
+
+def test_download_snapshot_writes_manifest_for_xet(monkeypatch, tmp_path):
+    written = []
+    verified = []
+
+    monkeypatch.setattr(
+        hf_download,
+        "_model_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            siblings = [SimpleNamespace(rfilename = "config.json", size = 12)]
+        ),
+    )
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(snapshot_download = lambda **_kwargs: str(tmp_path)),
+    )
+
+    hf_download._download_snapshot("Org/Model", None, "xet")
+
+    assert written, "XET snapshot download must still record a manifest"
+    assert written[0][0:3] == ("model", "Org/Model", None)
+    assert written[0][3][0].path == "config.json"
+    assert verified == [("model", "Org/Model", None, str(tmp_path))]
+
+
+def test_download_gguf_variant_writes_manifest_for_xet(monkeypatch, tmp_path):
+    written = []
+    verified = []
+
+    monkeypatch.setattr(
+        hf_download,
+        "_model_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            siblings = [_sibling("model-Q4_K_M.gguf", 10, "main")]
+        ),
+    )
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(snapshot_download = lambda **_kwargs: str(tmp_path)),
+    )
+
+    hf_download._download_gguf_variant("Org/Model", "Q4_K_M", None, "xet")
+
+    assert written, "XET GGUF variant download must still record a manifest"
+    assert written[0][0:3] == ("model", "Org/Model", "Q4_K_M")
+    assert written[0][3][0].path == "model-Q4_K_M.gguf"
+    assert verified == [("model", "Org/Model", "Q4_K_M", str(tmp_path))]
+
+
+def test_download_dataset_writes_manifest_for_xet(monkeypatch, tmp_path):
+    written = []
+    verified = []
+
+    monkeypatch.setattr(
+        hf_download,
+        "_dataset_info_with_retry",
+        lambda *_args, **_kwargs: SimpleNamespace(
+            siblings = [SimpleNamespace(rfilename = "data.parquet", size = 30)]
+        ),
+    )
+    monkeypatch.setattr(
+        hf_download, "_verify_completed_download", lambda *args, **kwargs: verified.append(args)
+    )
+    monkeypatch.setattr(
+        download_registry, "prepare_cache_for_transport", lambda *_args, **_kwargs: 0
+    )
+    monkeypatch.setattr(download_manifest, "clear_cancel_marker", lambda *_args: None)
+    monkeypatch.setattr(
+        download_manifest, "write_manifest", lambda *args: written.append(args) or True
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "huggingface_hub",
+        SimpleNamespace(snapshot_download = lambda **_kwargs: str(tmp_path)),
+    )
+
+    hf_download._download_dataset("Org/Data", None, "xet")
+
+    assert written, "XET dataset download must still record a manifest"
+    assert written[0][0:3] == ("dataset", "Org/Data", None)
+    assert written[0][3][0].path == "data.parquet"
+    assert verified == [("dataset", "Org/Data", None, str(tmp_path))]
+
+
+def test_dataset_status_includes_generation(monkeypatch):
+    class _Registry:
+        def get_job(self, _key):
+            return SimpleNamespace(state = "running", error = None)
+
+        def current_generation(self, _key):
+            return 4
+
+    monkeypatch.setattr(dataset_downloads, "_registry", _Registry())
+    monkeypatch.setattr(
+        dataset_downloads,
+        "resolve_cached_repo_id_case",
+        lambda repo_id, **_kwargs: repo_id,
+    )
+
+    result = asyncio.run(dataset_downloads.get_dataset_download_status_response("Org/Data"))
+
+    assert result.state == "running"
+    assert result.generation == 4
diff --git a/studio/backend/hub/utils/__init__.py b/studio/backend/hub/utils/__init__.py
new file mode 100644
index 0000000000..32014236c6
--- /dev/null
+++ b/studio/backend/hub/utils/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
diff --git a/studio/backend/hub/utils/dataset_cache.py b/studio/backend/hub/utils/dataset_cache.py
new file mode 100644
index 0000000000..1a7a90d8a5
--- /dev/null
+++ b/studio/backend/hub/utils/dataset_cache.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from hub.utils.hf_cache_state import iter_repo_cache_dirs
+
+
+TRAINING_DATA_EXTS = (".parquet", ".json", ".jsonl", ".csv")
+
+
+def _rel_lower(snapshot: Path, path: Path) -> str:
+    return path.relative_to(snapshot).as_posix().lower()
+
+
+_SPLIT_ALIASES = {
+    "validation": frozenset({"validation", "valid", "val"}),
+    "valid": frozenset({"validation", "valid", "val"}),
+    "val": frozenset({"validation", "valid", "val"}),
+    "eval": frozenset({"eval", "validation", "valid", "val"}),
+}
+
+
+def _label_tokens(text: str) -> set[str]:
+    return {token for token in re.split(r"[^a-z0-9]+", text.lower()) if token}
+
+
+def split_label_matches(text: str, split: str) -> bool:
+    """Match a split name against a file path's tokens, expanding split aliases
+    (validation/valid/val, eval) so cached and remote selection agree."""
+    normalized = split.strip().lower()
+    if not normalized:
+        return False
+    labels = _SPLIT_ALIASES.get(normalized, frozenset({normalized}))
+    return bool(labels.intersection(_label_tokens(text)))
+
+
+def _matches_label(snapshot: Path, path: Path, label: str) -> bool:
+    label = label.strip().lower()
+    if not label:
+        return False
+    rel = _rel_lower(snapshot, path)
+    tokens = [token for token in re.split(r"[^a-z0-9]+", rel) if token]
+    if label in tokens:
+        return True
+    if label in {"train", "test", "validation", "valid", "val", "eval"}:
+        return False
+    return label in rel
+
+
+def dataset_snapshot_from_cache_path(local_path: Optional[str], repo_id: str) -> Optional[Path]:
+    if not local_path or not repo_id:
+        return None
+    try:
+        root = Path(local_path).expanduser()
+        if not root.exists():
+            return None
+        expected_repo_dir = f"datasets--{repo_id.replace('/', '--')}".lower()
+        if expected_repo_dir not in {part.lower() for part in root.parts}:
+            return None
+        if root.is_dir() and root.parent.name == "snapshots":
+            return root.resolve()
+        snapshots = root / "snapshots" if root.is_dir() else None
+        if snapshots is None or not snapshots.is_dir():
+            return None
+        candidates = [p for p in snapshots.iterdir() if p.is_dir()]
+        if not candidates:
+            return None
+        candidates.sort(
+            key = lambda path: path.stat().st_mtime if path.exists() else 0,
+            reverse = True,
+        )
+        return candidates[0].resolve()
+    except Exception:
+        return None
+
+
+def latest_cached_dataset_snapshot(
+    repo_id: str, local_path: Optional[str] = None
+) -> Optional[Path]:
+    local_snapshot = dataset_snapshot_from_cache_path(local_path, repo_id)
+    if local_snapshot is not None:
+        return local_snapshot
+
+    newest: Optional[Path] = None
+    newest_mtime = -1.0
+    for entry in iter_repo_cache_dirs("dataset", repo_id):
+        snapshots = entry / "snapshots"
+        if not snapshots.is_dir():
+            continue
+        try:
+            candidates = [s for s in snapshots.iterdir() if s.is_dir()]
+        except OSError:
+            continue
+        for snap in candidates:
+            try:
+                mtime = snap.stat().st_mtime
+            except OSError:
+                continue
+            if mtime > newest_mtime:
+                newest = snap
+                newest_mtime = mtime
+    return newest
+
+
+def cached_dataset_candidates(
+    snapshot: Path,
+    *,
+    subset: Optional[str],
+    train_split: str,
+    extensions: tuple[str, ...],
+    preferred_extensions: tuple[str, ...] = TRAINING_DATA_EXTS,
+) -> list[Path]:
+    try:
+        files = [
+            p for p in snapshot.rglob("*") if p.is_file() and p.name.lower().endswith(extensions)
+        ]
+    except OSError:
+        return []
+    if not files:
+        return []
+
+    subset_lower = subset.lower() if subset else ""
+    split_lower = train_split.lower()
+
+    def score(path: Path) -> tuple[int, int, str]:
+        rel = _rel_lower(snapshot, path)
+        subset_match = bool(subset_lower and _matches_label(snapshot, path, subset_lower))
+        split_match = bool(split_lower and split_label_matches(rel, split_lower))
+        location_rank = 3
+        if split_match and (not subset_lower or subset_match):
+            location_rank = 0
+        elif split_match:
+            location_rank = 1
+        elif subset_match:
+            location_rank = 2
+        return (
+            0 if path.name.lower().endswith(preferred_extensions) else 1,
+            location_rank,
+            rel,
+        )
+
+    return sorted(files, key = score)
diff --git a/studio/backend/hub/utils/dataset_format.py b/studio/backend/hub/utils/dataset_format.py
new file mode 100644
index 0000000000..df02035365
--- /dev/null
+++ b/studio/backend/hub/utils/dataset_format.py
@@ -0,0 +1,749 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+
+def _first_row(dataset) -> Optional[dict]:
+    try:
+        row = next(iter(dataset))
+    except StopIteration:
+        return None
+    return row if isinstance(row, dict) else None
+
+
+def _column_names(dataset, sample: Optional[dict] = None) -> list[str]:
+    names = getattr(dataset, "column_names", None)
+    if names is not None:
+        return list(names)
+    return list((sample or {}).keys())
+
+
+def _keyword_in_column(keyword: str, col_name: str) -> bool:
+    return re.search(r"\b" + re.escape(keyword) + r"\b", col_name, re.IGNORECASE) is not None
+
+
+def _unknown_dataset_format(
+    chat_column: Optional[str] = None, sample_keys: Optional[list[str]] = None
+) -> dict:
+    return {
+        "format": "unknown",
+        "chat_column": chat_column,
+        "needs_standardization": None,
+        "sample_keys": sample_keys or [],
+    }
+
+
+def detect_dataset_format(dataset) -> dict:
+    sample = _first_row(dataset)
+    if sample is None:
+        return _unknown_dataset_format()
+    column_names = set(sample.keys())
+    if {"instruction", "output"}.issubset(column_names):
+        return {
+            "format": "alpaca",
+            "chat_column": None,
+            "needs_standardization": False,
+            "sample_keys": [],
+        }
+
+    chat_column = None
+    if "messages" in column_names:
+        chat_column = "messages"
+    elif "conversations" in column_names:
+        chat_column = "conversations"
+    elif "texts" in column_names:
+        chat_column = "texts"
+
+    if not chat_column:
+        return _unknown_dataset_format()
+
+    chat_data = sample.get(chat_column)
+    if not isinstance(chat_data, (list, tuple)) or not chat_data:
+        return _unknown_dataset_format(chat_column)
+    first_msg = chat_data[0]
+    if not isinstance(first_msg, dict):
+        return _unknown_dataset_format(chat_column)
+    msg_keys = set(first_msg.keys())
+    sample_keys = [str(key) for key in msg_keys]
+    if "from" in msg_keys or "value" in msg_keys:
+        return {
+            "format": "sharegpt",
+            "chat_column": chat_column,
+            "needs_standardization": True,
+            "sample_keys": sample_keys,
+        }
+    if "role" in msg_keys and "content" in msg_keys:
+        return {
+            "format": "chatml",
+            "chat_column": chat_column,
+            "needs_standardization": False,
+            "sample_keys": sample_keys,
+        }
+    return _unknown_dataset_format(chat_column, sample_keys)
+
+
+def detect_custom_format_heuristic(dataset):
+    sample = _first_row(dataset)
+    if sample is None:
+        return None
+    all_columns = list(sample.keys())
+    mapping = {}
+    assistant_words = [
+        "output",
+        "answer",
+        "response",
+        "assistant",
+        "completion",
+        "expected",
+        "recommendation",
+        "reply",
+        "result",
+        "target",
+        "solution",
+        "explanation",
+        "solve",
+    ]
+    user_words_high_priority = [
+        "input",
+        "question",
+        "query",
+        "prompt",
+        "instruction",
+        "request",
+        "snippet",
+        "user",
+        "text",
+        "problem",
+        "exercise",
+    ]
+    user_words_low_priority = ["task"]
+    user_words = user_words_high_priority + user_words_low_priority
+    system_words = [
+        "system",
+        "context",
+        "description",
+        "persona",
+        "role",
+        "template",
+        "task",
+    ]
+    metadata_exact_match = {
+        "id",
+        "idx",
+        "index",
+        "key",
+        "timestamp",
+        "date",
+        "metadata",
+        "source",
+        "kind",
+        "type",
+        "category",
+        "score",
+        "label",
+        "tag",
+        "inference_mode",
+    }
+    metadata_prefix_patterns = [
+        "problem_type",
+        "problem_source",
+        "generation_model",
+        "pass_rate",
+    ]
+    priority_patterns = {
+        "generated": 100,
+        "gen_": 90,
+        "model_": 80,
+        "predicted": 70,
+        "completion": 60,
+    }
+
+    def has_keyword(col_name, keywords):
+        col_lower = col_name.lower()
+        col_normalized = col_lower.replace("_", "").replace("-", "").replace(" ", "")
+        return any(keyword in col_lower or keyword in col_normalized for keyword in keywords)
+
+    def is_metadata(col_name):
+        col_lower = col_name.lower()
+        if col_lower in metadata_exact_match or col_lower in metadata_prefix_patterns:
+            return True
+        for pattern in metadata_prefix_patterns:
+            if col_lower.startswith(pattern.split("_")[0] + "_") and col_lower != pattern:
+                if "_" in col_lower:
+                    prefix = col_lower.split("_")[0]
+                    if prefix in ["generation", "pass", "inference"]:
+                        return True
+        return len(col_lower) <= 2 and col_lower not in ["qa", "q", "a"]
+
+    def get_priority_score(col_name):
+        col_lower = col_name.lower()
+        return sum(score for pattern, score in priority_patterns.items() if pattern in col_lower)
+
+    def get_content_length(col_name):
+        try:
+            return len(str(sample[col_name])) if sample.get(col_name) else 0
+        except Exception:
+            return 0
+
+    def score_column(col_name, keywords, role_type, num_candidates):
+        if not has_keyword(col_name, keywords):
+            return 0
+        score = 10
+        if role_type == "user":
+            col_lower = col_name.lower()
+            if "task" in col_lower and not any(kw in col_lower for kw in user_words_high_priority):
+                score -= 15
+        score += get_priority_score(col_name)
+        if role_type in ["assistant", "user"]:
+            avg_length = get_content_length(col_name)
+            if num_candidates > 1:
+                if avg_length > 1000:
+                    score += 50
+                elif avg_length > 200:
+                    score += 30
+                elif avg_length > 50:
+                    score += 10
+                elif avg_length < 50:
+                    score -= 20
+            else:
+                if avg_length > 1000:
+                    score += 50
+                elif avg_length > 200:
+                    score += 30
+                elif avg_length > 50:
+                    score += 10
+        return score
+
+    content_columns = [col for col in all_columns if not is_metadata(col)]
+    assistant_potential = [col for col in content_columns if has_keyword(col, assistant_words)]
+    user_potential = [col for col in content_columns if has_keyword(col, user_words)]
+    assistant_candidates = [
+        (col, score)
+        for col in assistant_potential
+        if (score := score_column(col, assistant_words, "assistant", len(assistant_potential))) > 0
+    ]
+    if assistant_candidates:
+        assistant_candidates.sort(key = lambda item: item[1], reverse = True)
+        assistant_col = assistant_candidates[0][0]
+        mapping[assistant_col] = "assistant"
+    else:
+        assistant_col = None
+
+    user_candidates = []
+    for col in user_potential:
+        if col == assistant_col:
+            continue
+        score = score_column(col, user_words, "user", len(user_potential))
+        if score > 0:
+            user_candidates.append((col, score))
+    if user_candidates:
+        user_candidates.sort(key = lambda item: item[1], reverse = True)
+        user_col = user_candidates[0][0]
+        mapping[user_col] = "user"
+    else:
+        user_col = None
+
+    remaining_columns = [col for col in content_columns if col not in mapping]
+    system_col = None
+    for col in remaining_columns:
+        if has_keyword(col, system_words):
+            mapping[col] = "system"
+            system_col = col
+            break
+    if system_col:
+        remaining_columns = [col for col in remaining_columns if col != system_col]
+    if remaining_columns:
+        remaining_col = remaining_columns[0]
+        if not has_keyword(remaining_col, user_words + assistant_words):
+            mapping[remaining_col] = "system"
+        elif user_col is None:
+            mapping[remaining_col] = "user"
+        else:
+            mapping[remaining_col] = "system"
+
+    has_user = any(role == "user" for role in mapping.values())
+    has_assistant = any(role == "assistant" for role in mapping.values())
+    if not has_user:
+        for col in remaining_columns:
+            if col not in mapping:
+                mapping[col] = "user"
+                has_user = True
+                break
+    return mapping if has_user and has_assistant else None
+
+
+_AUDIO_EXTENSIONS = (
+    ".wav",
+    ".mp3",
+    ".flac",
+    ".ogg",
+    ".opus",
+    ".m4a",
+    ".aac",
+    ".wma",
+    ".webm",
+)
+
+
+def _is_audio_value(value) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, dict):
+        if "array" in value and "sampling_rate" in value:
+            return True
+        if "bytes" in value or "path" in value:
+            path = value.get("path") or ""
+            return isinstance(path, str) and any(
+                path.lower().endswith(ext) for ext in _AUDIO_EXTENSIONS
+            )
+    return False
+
+
+def _has_image_header(data: bytes) -> bool:
+    if len(data) < 4:
+        return False
+    return (
+        data[:2] == b"\xff\xd8"
+        or data[:4] == b"\x89PNG"
+        or data[:3] == b"GIF"
+        or (data[:4] == b"RIFF" and len(data) >= 12 and data[8:12] == b"WEBP")
+        or data[:2] == b"BM"
+    )
+
+
+def _is_image_value(value) -> bool:
+    if value is None:
+        return False
+    try:
+        from PIL.Image import Image as PILImage
+        if isinstance(value, PILImage):
+            return True
+    except ImportError:
+        pass
+    if isinstance(value, dict):
+        if "array" in value and "sampling_rate" in value:
+            return False
+        if "bytes" in value and "path" in value:
+            path = value.get("path") or ""
+            if isinstance(path, str) and any(
+                path.lower().endswith(ext) for ext in _AUDIO_EXTENSIONS
+            ):
+                return False
+            return True
+    if isinstance(value, (bytes, bytearray)):
+        return _has_image_header(value)
+    image_exts = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff", ".svg")
+    if isinstance(value, str) and len(value) < 1000:
+        lower = value.strip().lower()
+        if lower.startswith(("http://", "https://")):
+            return any(lower.split("?")[0].endswith(ext) for ext in image_exts)
+        return any(lower.endswith(ext) for ext in image_exts)
+    return False
+
+
+def detect_multimodal_dataset(dataset):
+    sample = _first_row(dataset)
+    if sample is None:
+        return {
+            "is_image": False,
+            "multimodal_columns": [],
+            "modality_types": [],
+            "is_audio": False,
+            "audio_columns": [],
+            "detected_audio_column": None,
+            "detected_text_column": None,
+            "detected_speaker_column": None,
+        }
+    column_names = list(sample.keys())
+    image_keywords = [
+        "image",
+        "img",
+        "pixel",
+        "jpg",
+        "jpeg",
+        "png",
+        "webp",
+        "bmp",
+        "gif",
+        "tiff",
+        "svg",
+        "photo",
+        "pic",
+        "picture",
+        "visual",
+        "file_name",
+        "filename",
+    ]
+    audio_keywords = ["audio", "speech", "wav", "waveform", "sound"]
+    multimodal_columns = []
+    audio_columns = []
+    modality_types = set()
+    for col_name in column_names:
+        if any(_keyword_in_column(keyword, col_name) for keyword in image_keywords):
+            multimodal_columns.append(col_name)
+            modality_types.add("image")
+    for col_name in column_names:
+        if col_name not in multimodal_columns and _is_image_value(sample[col_name]):
+            multimodal_columns.append(col_name)
+            modality_types.add("image")
+    for col_name in column_names:
+        if any(_keyword_in_column(keyword, col_name) for keyword in audio_keywords):
+            audio_columns.append(col_name)
+            modality_types.add("audio")
+    for col_name in column_names:
+        if col_name not in audio_columns and _is_audio_value(sample[col_name]):
+            audio_columns.append(col_name)
+            modality_types.add("audio")
+    if audio_columns:
+        multimodal_columns = [col for col in multimodal_columns if col not in set(audio_columns)]
+
+    detected_text_col = None
+    if audio_columns:
+        for col_name in column_names:
+            if col_name.lower() in [
+                "text",
+                "sentence",
+                "transcript",
+                "transcription",
+                "label",
+            ]:
+                detected_text_col = col_name
+                break
+    detected_speaker_col = None
+    if audio_columns:
+        for col_name in column_names:
+            if col_name.lower() in ["source", "speaker", "speaker_id"]:
+                detected_speaker_col = col_name
+                break
+    return {
+        "is_image": len(multimodal_columns) > 0,
+        "multimodal_columns": multimodal_columns,
+        "modality_types": list(modality_types),
+        "is_audio": len(audio_columns) > 0,
+        "audio_columns": audio_columns,
+        "detected_audio_column": audio_columns[0] if audio_columns else None,
+        "detected_text_column": detected_text_col,
+        "detected_speaker_column": detected_speaker_col,
+    }
+
+
+def detect_vlm_dataset_structure(dataset):
+    sample = _first_row(dataset)
+    if sample is None:
+        return {
+            "format": "unknown",
+            "needs_conversion": None,
+            "image_column": None,
+            "text_column": None,
+            "messages_column": None,
+        }
+    column_names = set(sample.keys())
+    if "messages" in column_names:
+        messages = sample["messages"]
+        if messages and len(messages) > 0:
+            first_msg = messages[0]
+            if "content" in first_msg:
+                content = first_msg["content"]
+                if (
+                    isinstance(content, list)
+                    and content
+                    and isinstance(content[0], dict)
+                    and "type" in content[0]
+                ):
+                    has_index = any("index" in item for item in content if isinstance(item, dict))
+                    if has_index and "images" in column_names:
+                        return {
+                            "format": "vlm_messages_llava",
+                            "needs_conversion": True,
+                            "messages_column": "messages",
+                            "image_column": "images",
+                            "text_column": None,
+                        }
+                    has_image = any("image" in item for item in content if isinstance(item, dict))
+                    if has_image:
+                        return {
+                            "format": "vlm_messages",
+                            "needs_conversion": False,
+                            "messages_column": "messages",
+                            "image_column": None,
+                            "text_column": None,
+                        }
+
+    for chat_col in ("conversations", "messages"):
+        if chat_col not in column_names:
+            continue
+        chat_data = sample[chat_col]
+        if not isinstance(chat_data, list) or not chat_data:
+            continue
+        has_image_placeholder = any(
+            "<image>" in str(message.get("value", "") or message.get("content", ""))
+            for message in chat_data
+            if isinstance(message, dict)
+        )
+        if not has_image_placeholder:
+            continue
+        image_col = next(
+            (
+                col
+                for col in column_names
+                if col != chat_col
+                and (_keyword_in_column("image", col) or _keyword_in_column("img", col))
+            ),
+            None,
+        )
+        if image_col:
+            return {
+                "format": "sharegpt_with_images",
+                "needs_conversion": True,
+                "image_column": image_col,
+                "text_column": None,
+                "messages_column": chat_col,
+            }
+
+    metadata_suffixes = (
+        "_id",
+        "_url",
+        "_name",
+        "_filename",
+        "_uri",
+        "_link",
+        "_key",
+        "_index",
+    )
+    metadata_prefixes = (
+        "id_",
+        "url_",
+        "name_",
+        "filename_",
+        "uri_",
+        "link_",
+        "key_",
+        "index_",
+    )
+    image_keywords = [
+        "image",
+        "img",
+        "photo",
+        "picture",
+        "pic",
+        "visual",
+        "scan",
+        "file_name",
+        "filename",
+    ]
+    text_keywords = [
+        "text",
+        "caption",
+        "captions",
+        "description",
+        "answer",
+        "output",
+        "response",
+        "label",
+    ]
+
+    def is_metadata_column(col_name):
+        lower = col_name.lower()
+        return any(lower.endswith(suffix) for suffix in metadata_suffixes) or any(
+            lower.startswith(prefix) for prefix in metadata_prefixes
+        )
+
+    image_candidates = []
+    for col in column_names:
+        value = sample[col]
+        if any(_keyword_in_column(keyword, col) for keyword in image_keywords) or _is_image_value(
+            value
+        ):
+            if hasattr(value, "size") and hasattr(value, "mode"):
+                score = 100
+            elif isinstance(value, dict) and ("bytes" in value or "path" in value):
+                score = 75
+            elif isinstance(value, str):
+                score = (
+                    55
+                    if is_metadata_column(col)
+                    else 70
+                    if value.startswith(("http://", "https://"))
+                    else 50
+                )
+            else:
+                score = 0
+            if score > 0:
+                image_candidates.append((col, score))
+    image_candidates.sort(key = lambda item: item[1], reverse = True)
+
+    text_candidates = []
+    for col in column_names:
+        if is_metadata_column(col) or not any(
+            _keyword_in_column(keyword, col) for keyword in text_keywords
+        ):
+            continue
+        value = sample[col]
+        if isinstance(value, str) and value:
+            text_candidates.append((col, min(len(value), 1000)))
+        elif isinstance(value, list) and value and isinstance(value[0], str):
+            text_candidates.append((col, min(len(value[0]), 1000) // 2))
+    text_candidates.sort(key = lambda item: item[1], reverse = True)
+
+    found_image = image_candidates[0][0] if image_candidates else None
+    found_text = text_candidates[0][0] if text_candidates else None
+    if found_image and found_text:
+        return {
+            "format": "simple_image_text",
+            "needs_conversion": True,
+            "image_column": found_image,
+            "text_column": found_text,
+            "messages_column": None,
+        }
+    return {
+        "format": "unknown",
+        "needs_conversion": None,
+        "image_column": found_image,
+        "text_column": found_text,
+        "messages_column": None,
+    }
+
+
+def check_dataset_format(dataset, is_vlm: bool = False) -> dict:
+    sample = _first_row(dataset)
+    columns = _column_names(dataset, sample)
+    multimodal_info = detect_multimodal_dataset(dataset)
+    is_audio = multimodal_info.get("is_audio", False)
+    audio_fields = {
+        "is_audio": is_audio,
+        "detected_audio_column": multimodal_info.get("detected_audio_column"),
+        "detected_speaker_column": multimodal_info.get("detected_speaker_column"),
+    }
+
+    if is_vlm:
+        vlm_structure = detect_vlm_dataset_structure(dataset)
+        requires_mapping = vlm_structure["format"] == "unknown"
+        warning = None
+        if requires_mapping:
+            missing = []
+            if not vlm_structure.get("image_column"):
+                missing.append("image")
+            if not vlm_structure.get("text_column"):
+                missing.append("text")
+            if missing:
+                warning = (
+                    f"Could not auto-detect {' or '.join(missing)} column. "
+                    "Please assign image and text columns manually."
+                )
+        return {
+            "requires_manual_mapping": requires_mapping,
+            "detected_format": vlm_structure["format"],
+            "columns": columns,
+            "suggested_mapping": None,
+            "detected_image_column": vlm_structure.get("image_column"),
+            "detected_text_column": vlm_structure.get("text_column"),
+            "is_image": multimodal_info["is_image"],
+            "multimodal_columns": multimodal_info.get("multimodal_columns"),
+            "warning": warning,
+            **audio_fields,
+        }
+
+    if is_audio:
+        detected_audio = multimodal_info.get("detected_audio_column")
+        detected_text = multimodal_info.get("detected_text_column")
+        return {
+            "requires_manual_mapping": not detected_audio or not detected_text,
+            "detected_format": "audio",
+            "columns": columns,
+            "suggested_mapping": None,
+            "detected_image_column": None,
+            "detected_text_column": detected_text,
+            "is_image": False,
+            "multimodal_columns": multimodal_info.get("audio_columns"),
+            **audio_fields,
+        }
+
+    detected = detect_dataset_format(dataset)
+    if detected["format"] == "unknown":
+        heuristic_mapping = detect_custom_format_heuristic(dataset)
+        if heuristic_mapping:
+            return {
+                "requires_manual_mapping": False,
+                "detected_format": "custom_heuristic",
+                "columns": columns,
+                "suggested_mapping": heuristic_mapping,
+                "detected_image_column": None,
+                "detected_text_column": None,
+                "is_image": multimodal_info["is_image"],
+                "multimodal_columns": multimodal_info.get("multimodal_columns"),
+                **audio_fields,
+            }
+        return {
+            "requires_manual_mapping": True,
+            "detected_format": "unknown",
+            "columns": columns,
+            "suggested_mapping": None,
+            "detected_image_column": None,
+            "detected_text_column": None,
+            "is_image": multimodal_info["is_image"],
+            "multimodal_columns": multimodal_info.get("multimodal_columns"),
+            "warning": (
+                f"Could not auto-detect column roles for columns: {columns}. "
+                "Please assign roles manually, or use AI Assist."
+            ),
+            **audio_fields,
+        }
+
+    return {
+        "requires_manual_mapping": False,
+        "detected_format": detected["format"],
+        "columns": columns,
+        "suggested_mapping": None,
+        "detected_image_column": None,
+        "detected_text_column": None,
+        "is_image": multimodal_info["is_image"],
+        "multimodal_columns": multimodal_info.get("multimodal_columns"),
+        **audio_fields,
+    }
+
+
+_ROLE_MAP = {
+    "human": "user",
+    "user": "user",
+    "input": "user",
+    "gpt": "assistant",
+    "assistant": "assistant",
+    "output": "assistant",
+    "system": "system",
+}
+
+
+def _standardize_sharegpt_row(row: dict[str, Any], chat_column: str) -> dict[str, Any]:
+    chat_data = row.get(chat_column)
+    if not isinstance(chat_data, list):
+        return row
+    messages = []
+    for message in chat_data:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role") or message.get("from")
+        content = message.get("content") if "content" in message else message.get("value")
+        messages.append(
+            {
+                "role": _ROLE_MAP.get(str(role), str(role or "user")),
+                "content": "" if content is None else content,
+            }
+        )
+    return {chat_column: messages}
+
+
+def format_dataset_preview(dataset):
+    detected = detect_dataset_format(dataset)
+    if detected.get("format") != "sharegpt":
+        return dataset
+    chat_column = detected.get("chat_column")
+    if not isinstance(chat_column, str):
+        return dataset
+
+    if hasattr(dataset, "map"):
+        return dataset.map(lambda row: _standardize_sharegpt_row(row, chat_column))
+    return dataset
diff --git a/studio/backend/hub/utils/download_manifest.py b/studio/backend/hub/utils/download_manifest.py
new file mode 100644
index 0000000000..5366689296
--- /dev/null
+++ b/studio/backend/hub/utils/download_manifest.py
@@ -0,0 +1,487 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hub download manifest + cancel-marker primitives.
+
+Manifests record what a download was supposed to fetch (path + declared
+size per expected file). Consumed by:
+  - the worker post-download, to verify on-disk sizes match what HF
+    declared, so a resume that no-ops doesn't get classified as success;
+  - the inventory scanner, to mark a row partial when expected files
+    are absent or undersized, so a half-finished GGUF/dataset doesn't
+    masquerade as a complete on-device row.
+
+Cancel markers record that a user-initiated cancel landed for a
+(repo_type, repo_id, variant) triple. *Existence* is the signal the
+scanner reads; the body carries debuggability metadata. Markers are
+cleared at the start of a new download attempt (supersedes prior cancel)
+and on successful completion (defensive, in case the start clear failed).
+
+I/O contracts:
+  - Writes are atomic via ``tmp + os.replace``: a SIGKILL mid-write
+    cannot leave a half-written file readable to the next reader.
+  - Manifest reads fail *open*: missing/corrupt/schema-mismatched
+    manifests return ``None`` and the scanner falls through to the
+    legacy on-disk-only check (matches HF-cache imports and pre-fix
+    downloads that never wrote a manifest).
+  - Cancel-marker reads fail *closed*: file existence is the signal
+    regardless of body parseability, so a corrupt marker still
+    suppresses the "on device" classification.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+from loggers import get_logger
+
+from hub.utils.state_dir import (
+    RepoType,
+    cancelled_dir,
+    manifest_path,
+    manifests_dir,
+    marker_path,
+    variant_filename_prefix,
+)
+
+logger = get_logger(__name__)
+
+
+_MANIFEST_VERSION = 1
+_MARKER_VERSION = 2
+_LEGACY_MARKER_VERSION = 1
+
+# Verbatim phrase the worker emits on a degraded completion and the download
+# lifecycle escalates to a warning log. Shared so the emit and match stay coupled.
+MANIFEST_DEGRADED_MARKER = "completed without a manifest so partial detection is degraded"
+
+
+@dataclass(frozen = True)
+class ExpectedFile:
+    path: str
+    size: int
+    sha256: Optional[str] = None
+
+
+@dataclass(frozen = True)
+class Manifest:
+    repo_type: RepoType
+    repo_id: str
+    variant: Optional[str]
+    started_at: str
+    expected_files: tuple[ExpectedFile, ...]
+    transport: Optional[str] = None
+
+
+@dataclass(frozen = True)
+class VerifyResult:
+    ok: bool
+    missing: tuple[str, ...]
+    size_mismatched: tuple[str, ...]
+
+
+def _atomic_write_json(path: Path, payload: dict) -> bool:
+    # Per-write uuid suffix so a concurrent caller or a stale tmp from a
+    # previous crash cannot collide with the in-flight write.
+    tmp = path.with_name(f".{path.name}.tmp-{uuid.uuid4().hex[:8]}")
+    try:
+        with tmp.open("w", encoding = "utf-8") as handle:
+            handle.write(json.dumps(payload, indent = 2))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, path)
+    except OSError as exc:
+        logger.debug("Atomic write failed for %s: %s", path, exc)
+        try:
+            tmp.unlink(missing_ok = True)
+        except OSError:
+            pass
+        return False
+    if os.name != "nt":
+        try:
+            flags = os.O_RDONLY
+            if hasattr(os, "O_DIRECTORY"):
+                flags |= os.O_DIRECTORY
+            parent_fd = os.open(path.parent, flags)
+            try:
+                os.fsync(parent_fd)
+            finally:
+                os.close(parent_fd)
+        except OSError as exc:
+            logger.debug("Parent dir fsync failed for %s: %s", path, exc)
+    return True
+
+
+def write_manifest(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str],
+    expected_files: Sequence[ExpectedFile],
+    transport: Optional[str] = None,
+) -> bool:
+    """Write/overwrite the manifest for this triple. Best-effort.
+
+    ``False`` on write failure must not be treated as fatal: the
+    worst-case fallback is the pre-fix scanner behavior (one missed
+    partial detection), which is no regression.
+    """
+    path = manifest_path(repo_type, repo_id, variant)
+    if path is None:
+        return False
+    payload = {
+        "version": _MANIFEST_VERSION,
+        "repo_type": repo_type,
+        "repo_id": repo_id,
+        "variant": variant,
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "expected_files": [
+            {
+                "path": f.path,
+                "size": int(f.size),
+                **({"sha256": f.sha256} if f.sha256 else {}),
+            }
+            for f in expected_files
+        ],
+        "transport": transport,
+    }
+    return _atomic_write_json(path, payload)
+
+
+def read_manifest(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> Optional[Manifest]:
+    """Return the manifest if present and parseable; ``None`` otherwise.
+
+    Treats missing-file, parse-error, and any schema mismatch all as
+    ``None`` (fail-open). Scanner callers fall through to on-disk-only
+    behavior on ``None`` so this never regresses legacy/imported repos
+    that have no manifest.
+
+    Forward-compat: accepts only ``version == 1``; an unknown version is
+    treated as no manifest. A future v2 schema MUST either keep v1's
+    ``expected_files`` shape on the same filename (bump
+    ``_MANIFEST_VERSION`` and widen this check) or live under a different
+    filename, so an incompatible payload can never mis-classify rows.
+    """
+    path = manifest_path(repo_type, repo_id, variant)
+    if path is None or not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding = "utf-8"))
+    except (OSError, ValueError) as exc:
+        logger.debug("Could not read manifest %s: %s", path, exc)
+        return None
+    if not isinstance(data, dict):
+        return None
+    if data.get("version") != _MANIFEST_VERSION:
+        logger.debug(
+            "Manifest %s has unknown version %r; ignoring.",
+            path,
+            data.get("version"),
+        )
+        return None
+    raw_files = data.get("expected_files")
+    if not isinstance(raw_files, list):
+        return None
+    expected: list[ExpectedFile] = []
+    for item in raw_files:
+        if not isinstance(item, dict):
+            return None
+        file_path = item.get("path")
+        size = item.get("size")
+        if not isinstance(file_path, str) or not isinstance(size, int):
+            return None
+        sha256 = item.get("sha256")
+        expected.append(
+            ExpectedFile(
+                path = file_path,
+                size = size,
+                sha256 = sha256 if isinstance(sha256, str) and sha256 else None,
+            )
+        )
+    raw_variant = data.get("variant")
+    transport = data.get("transport")
+    return Manifest(
+        repo_type = repo_type,
+        repo_id = str(data.get("repo_id", repo_id)),
+        variant = raw_variant if raw_variant else None,
+        started_at = str(data.get("started_at", "")),
+        expected_files = tuple(expected),
+        transport = transport if transport in ("http", "xet") else None,
+    )
+
+
+def verify_against_disk(manifest: Manifest, snapshot_dir: Path) -> VerifyResult:
+    """Check every expected file is present in *snapshot_dir* at its declared size.
+
+    Presence + size only, not content integrity: it converts a
+    no-op-on-cached ``snapshot_download`` into a clear error when shards are
+    missing or truncated, and marks a scanner row partial when expected bytes
+    aren't on disk. Byte-level integrity is already covered upstream by
+    ``huggingface_hub`` (size check on HTTP, content-addressed chunk hashes on
+    XET), so re-hashing finalized multi-GB weights here would only duplicate
+    that at a large cost. ``Path.stat()`` follows symlinks, so HF's symlink and
+    Windows copy cache layouts both verify correctly.
+    """
+    missing: list[str] = []
+    mismatched: list[str] = []
+    for expected in manifest.expected_files:
+        target = snapshot_dir / expected.path
+        try:
+            actual_size = target.stat().st_size
+        except OSError:
+            missing.append(expected.path)
+            continue
+        # expected.size == 0 means HF metadata had no declared size: verify
+        # existence only rather than flagging every such file as mismatched.
+        if expected.size > 0 and actual_size != expected.size:
+            mismatched.append(expected.path)
+    return VerifyResult(
+        ok = not missing and not mismatched,
+        missing = tuple(missing),
+        size_mismatched = tuple(mismatched),
+    )
+
+
+def expected_files_from_snapshot_dir(snapshot_dir: Path) -> list[ExpectedFile]:
+    """Derive expected-file entries from a completed snapshot directory.
+
+    Last-resort manifest source for when HF metadata was unreachable for the
+    whole download. ``snapshot_download`` has already exited cleanly, so every
+    regular file is a finished, correctly-sized blob; recording them keeps the
+    scanner's completion check in agreement with the worker's exit-0 success
+    instead of leaving a finished repo perpetually partial. ``stat()`` follows
+    HF's symlink layout and Windows copies, so the recorded sizes match what
+    ``verify_against_disk`` later reads.
+    """
+    out: list[ExpectedFile] = []
+    try:
+        entries = sorted(snapshot_dir.rglob("*"))
+    except OSError:
+        return out
+    for path in entries:
+        try:
+            if not path.is_file():
+                continue
+            relative = path.relative_to(snapshot_dir).as_posix()
+            out.append(
+                ExpectedFile(
+                    path = relative,
+                    size = path.stat().st_size,
+                    sha256 = None,
+                )
+            )
+        except OSError:
+            continue
+    return out
+
+
+def write_cancel_marker(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+    transport: Optional[str] = None,
+) -> bool:
+    """Record that this triple was cancelled. Idempotent across repeated cancels.
+
+    ``transport`` ("http"/"xet") is surfaced via partial_transport on
+    inventory rows so the UI labels HTTP retries as continuable and XET
+    retries as full redownloads. None is accepted for forward-compat.
+    """
+    path = marker_path(repo_type, repo_id, variant)
+    if path is None:
+        return False
+    payload = {
+        "version": _MARKER_VERSION,
+        "repo_type": repo_type,
+        "repo_id": repo_id,
+        "variant": variant,
+        "transport": transport,
+        "cancelled_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return _atomic_write_json(path, payload)
+
+
+def read_cancel_marker_transport(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> Optional[str]:
+    """Return the transport recorded in the cancel marker, or ``None`` if no
+    marker exists or it is unreadable.
+
+    Cases:
+
+    * No marker on disk → ``None``.
+    * Legacy v1 marker → ``"http"``: v1 markers were only written by the
+      HTTP path, so the transport is unambiguous despite the absent field.
+    * v2 marker with a valid ``"http"`` / ``"xet"`` transport → that value.
+    * Corrupt, non-dict, or v2-with-missing-transport marker → ``None``.
+      Defaulting these to ``"http"`` misled the UI into showing a
+      byte-resume "Continue" label for what may have been an XET cancel;
+      ``None`` keeps the neutral "Retry" label.
+    * Unknown future versions → ``None`` (unknown layout, unknown transport).
+    """
+    path = marker_path(repo_type, repo_id, variant)
+    if path is None or not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding = "utf-8"))
+    except (OSError, ValueError) as exc:
+        logger.debug("Could not read cancel marker %s: %s", path, exc)
+        return None
+    if not isinstance(data, dict):
+        return None
+    version = data.get("version")
+    if version == _LEGACY_MARKER_VERSION:
+        return "http"
+    if version != _MARKER_VERSION:
+        return None
+    transport = data.get("transport")
+    if isinstance(transport, str) and transport in ("http", "xet"):
+        return transport
+    return None
+
+
+def clear_cancel_marker(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> None:
+    """Remove the cancel marker for this triple if present.
+
+    Idempotent: a missing marker is not an error. Called at
+    download-start (a fresh attempt supersedes prior cancel state) and
+    again at successful completion (cleans up if the start clear failed).
+    """
+    path = marker_path(repo_type, repo_id, variant)
+    if path is None:
+        return
+    try:
+        path.unlink(missing_ok = True)
+    except OSError as exc:
+        logger.debug("Could not clear cancel marker %s: %s", path, exc)
+
+
+def has_cancel_marker(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> bool:
+    """File-existence check only. Body is never read.
+
+    Fail-closed: a corrupt marker still returns ``True`` because the
+    file's existence is the signal (the user once cancelled this
+    triple, even if the body is unreadable).
+    """
+    path = marker_path(repo_type, repo_id, variant)
+    if path is None:
+        return False
+    try:
+        return path.is_file()
+    except OSError:
+        return False
+
+
+def delete_manifest(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> bool:
+    path = manifest_path(repo_type, repo_id, variant)
+    if path is None:
+        return False
+    try:
+        if not path.is_file():
+            return False
+        path.unlink()
+        return True
+    except OSError as exc:
+        logger.debug("Could not delete manifest %s: %s", path, exc)
+        return False
+
+
+def purge_state(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> bool:
+    """Remove manifest + cancel marker for this triple. Returns ``True``
+    when anything was present on disk before the call. Idempotent."""
+    marker_existed = has_cancel_marker(repo_type, repo_id, variant)
+    manifest_removed = delete_manifest(repo_type, repo_id, variant)
+    clear_cancel_marker(repo_type, repo_id, variant)
+    return marker_existed or manifest_removed
+
+
+def purge_all_state_for_repo(repo_type: RepoType, repo_id: str) -> int:
+    """Remove the snapshot-level manifest + marker AND every variant-keyed
+    manifest + marker for this repo. Used by the route delete handlers so
+    scanner state never outlives the cache it described. Returns the count
+    of (repo, variant) triples that had any state on disk."""
+    removed = 0
+    if purge_state(repo_type, repo_id, None):
+        removed += 1
+    variants: set[str] = set()
+    for variant, _ in iter_variant_manifests(repo_type, repo_id):
+        variants.add(variant)
+    for variant, _ in iter_variant_markers(repo_type, repo_id):
+        variants.add(variant)
+    for variant in variants:
+        if purge_state(repo_type, repo_id, variant):
+            removed += 1
+    return removed
+
+
+def _variant_from_state_file(path: Path, fallback: str) -> str:
+    try:
+        data = json.loads(path.read_text(encoding = "utf-8"))
+    except (OSError, ValueError):
+        return fallback
+    if not isinstance(data, dict):
+        return fallback
+    variant = data.get("variant")
+    return variant if isinstance(variant, str) and variant else fallback
+
+
+def _iter_variant_state_files(
+    parent: Optional[Path], repo_type: RepoType, repo_id: str
+) -> Iterator[tuple[str, Path]]:
+    if parent is None:
+        return
+    prefix = variant_filename_prefix(repo_type, repo_id)
+    try:
+        entries = list(parent.iterdir())
+    except OSError:
+        return
+    for entry in entries:
+        if not entry.is_file() or not entry.name.endswith(".json"):
+            continue
+        stem = entry.name[: -len(".json")]
+        if not stem.lower().startswith(prefix):
+            continue
+        variant = stem[len(prefix) :]
+        if variant:
+            yield _variant_from_state_file(entry, variant), entry
+
+
+def iter_variant_manifests(repo_type: RepoType, repo_id: str) -> Iterator[tuple[str, Path]]:
+    """Yield (variant, manifest_path) for every variant-keyed manifest
+    written for this repo. Used by is_gguf_repo_partial to enumerate all
+    variants present on disk so the all-variants-broken gate can run."""
+    yield from _iter_variant_state_files(manifests_dir(), repo_type, repo_id)
+
+
+def iter_variant_markers(repo_type: RepoType, repo_id: str) -> Iterator[tuple[str, Path]]:
+    """Yield (variant, marker_path) for every variant-keyed cancel marker.
+    Companion to iter_variant_manifests: catches variants cancelled
+    before download-start ever wrote a manifest (very early failures)."""
+    yield from _iter_variant_state_files(cancelled_dir(), repo_type, repo_id)
diff --git a/studio/backend/hub/utils/download_registry.py b/studio/backend/hub/utils/download_registry.py
new file mode 100644
index 0000000000..777d63e1b5
--- /dev/null
+++ b/studio/backend/hub/utils/download_registry.py
@@ -0,0 +1,1263 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""HF cache inspection, download registry state, and orphan-worker reaping.
+
+Worker spawning and exit handling live in
+:mod:`hub.services.download_lifecycle`; this module owns the registry state
+machine plus the cache/marker inspection those workers depend on.
+
+Resume model
+------------
+Only the HTTP transport supports true partial-file resume:
+huggingface_hub's HTTP resumer opens ``<etag>.incomplete`` in append mode
+and sends ``Range: bytes={resume_size}-`` to continue from disk.
+
+The XET transport CANNOT resume from a ``.incomplete`` partial:
+``hf_xet.download_files`` rewrites the destination from scratch.
+Network-level dedup still happens, but through the separate chunk cache at
+``~/.cache/huggingface/xet/chunk-cache``, which these helpers never touch.
+
+Cross-transport corruption: a partial written by XET (or ``hf_transfer``'s
+parallel-Range writer) can be sparse — high reported size, zero-filled
+gaps below. Feeding it to the HTTP resumer would produce a correct-sized
+blob whose internal bytes are silently wrong. To prevent that, we keep
+transport markers at the download's scope (repo for snapshots/datasets,
+variant for GGUF) and refuse to inherit an HTTP partial unless the marker
+proves the previous writer was the same single-stream sequential writer.
+
+Marker writes go through tmp+rename in :func:`prepare_cache_for_transport`
+before the worker hands off to ``snapshot_download``, so the next process
+always sees a consistent provenance signal.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import shlex
+import signal
+import subprocess
+import sys
+import threading
+import time
+import weakref
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, Literal, Optional
+
+from loggers import get_logger
+
+from hub.utils import state_dir
+from hub.utils.state_dir import RepoType
+
+logger = get_logger(__name__)
+
+from hub.utils.hf_cache_state import (
+    INCOMPLETE_SUFFIX,
+    TRANSPORT_HTTP,
+    TRANSPORT_XET,
+    TRANSPORT_MARKER_NAME,
+    VALID_TRANSPORTS,
+    has_active_incomplete_blobs,
+    iter_repo_cache_dirs,
+    iter_active_repo_cache_dirs,
+    repo_cache_dir_name,
+    target_dir_name,
+    hf_cache_root,
+)
+
+
+@dataclass(frozen = True)
+class DownloadTransportCapability:
+    available: bool
+    reason: Optional[str] = None
+
+
+@dataclass(frozen = True)
+class DownloadTransportCapabilities:
+    http: DownloadTransportCapability
+    xet: DownloadTransportCapability
+
+
+def get_download_transport_capabilities() -> DownloadTransportCapabilities:
+    xet_available = importlib.util.find_spec("hf_xet") is not None
+    return DownloadTransportCapabilities(
+        http = DownloadTransportCapability(available = True),
+        xet = DownloadTransportCapability(
+            available = xet_available,
+            reason = None
+            if xet_available
+            else "Xet transport is unavailable because hf_xet is not installed.",
+        ),
+    )
+
+
+def download_transport_unavailable_reason(transport: str) -> Optional[str]:
+    if transport == TRANSPORT_HTTP:
+        return None
+    if transport == TRANSPORT_XET:
+        caps = get_download_transport_capabilities().xet
+        return None if caps.available else caps.reason
+    return f"Unsupported download transport: {transport}"
+
+
+def _worker_breadcrumb_path(key: str) -> Optional[Path]:
+    parent = state_dir.workers_dir()
+    if parent is None:
+        return None
+    safe = hashlib.sha256(key.encode("utf-8")).hexdigest()[:32]
+    return parent / f"{safe}.json"
+
+
+def write_worker_breadcrumb(key: str, pid: int, metadata: Optional["DownloadMetadata"]) -> None:
+    """Record a live worker's PID so a restarted backend can reap it. Best
+    effort: a write failure only forfeits boot-time reaping for this worker,
+    still covered by the worker's own parent-death watchdog."""
+    path = _worker_breadcrumb_path(key)
+    if path is None:
+        return
+    payload = {
+        "pid": int(pid),
+        "repo_type": metadata.repo_type if metadata is not None else None,
+        "repo_id": metadata.repo_id if metadata is not None else None,
+        "variant": metadata.variant if metadata is not None else None,
+        "transport": metadata.transport if metadata is not None else None,
+    }
+    tmp = path.with_name(f".{path.name}.tmp-{pid}")
+    try:
+        tmp.write_text(json.dumps(payload), encoding = "utf-8")
+        os.replace(tmp, path)
+    except OSError as exc:
+        logger.debug("Could not write worker breadcrumb %s: %s", path, exc)
+        try:
+            tmp.unlink(missing_ok = True)
+        except OSError:
+            pass
+
+
+def remove_worker_breadcrumb(key: str) -> None:
+    path = _worker_breadcrumb_path(key)
+    if path is None:
+        return
+    _safe_unlink(path)
+
+
+def _safe_unlink(path: Path) -> None:
+    try:
+        path.unlink(missing_ok = True)
+    except OSError as exc:
+        logger.debug("Could not remove %s: %s", path, exc)
+
+
+def _process_alive(pid: int) -> bool:
+    if sys.platform == "win32":
+        import ctypes
+        from ctypes import wintypes
+
+        SYNCHRONIZE = 0x00100000
+        ERROR_INVALID_PARAMETER = 87
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error = True)
+        kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+        kernel32.OpenProcess.restype = wintypes.HANDLE
+        kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+        kernel32.CloseHandle.restype = wintypes.BOOL
+        ctypes.set_last_error(0)
+        handle = kernel32.OpenProcess(SYNCHRONIZE, False, pid)
+        if not handle:
+            return ctypes.get_last_error() != ERROR_INVALID_PARAMETER
+        kernel32.CloseHandle(handle)
+        return True
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True
+
+
+def _read_process_cmdline(pid: int) -> Optional[str]:
+    proc_cmdline = Path(f"/proc/{pid}/cmdline")
+    try:
+        if proc_cmdline.exists():
+            raw = proc_cmdline.read_bytes()
+            return raw.replace(b"\x00", b" ").decode("utf-8", "replace")
+    except OSError:
+        pass
+    try:
+        import psutil
+        return " ".join(psutil.Process(pid).cmdline())
+    except Exception:
+        return None
+
+
+def _cmdline_repo_id(cmdline: str) -> Optional[str]:
+    try:
+        args = shlex.split(cmdline)
+    except ValueError:
+        args = cmdline.split()
+    for i, arg in enumerate(args):
+        if arg == "--repo-id" and i + 1 < len(args):
+            return args[i + 1]
+        if arg.startswith("--repo-id="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+def _is_our_worker(pid: int, repo_id: Optional[str]) -> bool:
+    cmdline = _read_process_cmdline(pid)
+    if cmdline is None:
+        return False
+    if "hub.workers.hf_download" not in cmdline:
+        return False
+    # Exact --repo-id match: a substring match would let a stale breadcrumb for
+    # Org/Model reap a live worker for Org/Model-v2.
+    if isinstance(repo_id, str) and repo_id:
+        return _cmdline_repo_id(cmdline) == repo_id
+    return True
+
+
+def _kill_orphan(pid: int) -> None:
+    try:
+        os.kill(pid, signal.SIGTERM if sys.platform == "win32" else signal.SIGKILL)
+    except OSError:
+        pass
+
+
+def _settle_orphaned_download(
+    repo_type: Optional[str],
+    repo_id: Optional[str],
+    variant: Optional[str],
+    transport: Optional[str],
+) -> None:
+    """Persist a cancel marker for a reaped orphan still mid-download so the next
+    launch settles it to a resumable "cancelled" state instead of a phantom-running
+    row.
+
+    Gated on surviving partial state and on the recorded manifest not already
+    verifying against an active snapshot, so a download that finished before its
+    breadcrumb was cleaned up is never mislabeled cancelled. For a GGUF variant
+    manifest with blob hashes, the partial-state check is scoped to those hashes so
+    a sibling variant cannot contaminate this orphan's state. The recorded
+    transport is preserved so the resume affordance stays accurate."""
+    if repo_type not in ("model", "dataset") or not repo_id:
+        return
+    from hub.utils import download_manifest
+
+    manifest = download_manifest.read_manifest(repo_type, repo_id, variant)
+    if repo_type == "model" and variant and manifest is None:
+        return
+    if manifest is None:
+        if not has_active_incomplete_blobs(repo_type, repo_id):
+            return
+    else:
+        if _manifest_verifies_against_active_cache(repo_type, repo_id, manifest):
+            return
+        if not _manifest_has_active_incomplete_blobs(repo_type, repo_id, manifest):
+            return
+    persist_cancel_marker(repo_type, repo_id, variant, transport, logger = logger)
+
+
+def reap_orphan_workers() -> None:
+    """Kill download workers left running by a previous backend instance.
+
+    Verifies each breadcrumb's PID is alive AND its command line is one of our
+    workers before terminating, so a recycled PID can't take down an unrelated
+    process. Partial blobs are never touched, so a reaped download stays
+    resumable; an interrupted one with bytes on disk is settled to a cancelled
+    marker (see :func:`_settle_orphaned_download`) so its resume affordance
+    survives a hard crash like a graceful shutdown's does. Runs once at startup
+    and never raises."""
+    parent = state_dir.workers_dir()
+    if parent is None:
+        return
+    try:
+        entries = list(parent.iterdir())
+    except OSError:
+        return
+    for entry in entries:
+        if not entry.is_file() or not entry.name.endswith(".json"):
+            continue
+        try:
+            data = json.loads(entry.read_text(encoding = "utf-8"))
+        except (OSError, ValueError):
+            _safe_unlink(entry)
+            continue
+        pid = data.get("pid") if isinstance(data, dict) else None
+        repo_id = data.get("repo_id") if isinstance(data, dict) else None
+        if not isinstance(pid, int) or pid <= 0:
+            _safe_unlink(entry)
+            continue
+        try:
+            if _process_alive(pid) and _is_our_worker(pid, repo_id):
+                _kill_orphan(pid)
+                logger.warning(
+                    "Reaped orphaned download worker pid=%s repo=%s from a "
+                    "previous backend instance.",
+                    pid,
+                    repo_id,
+                )
+            _settle_orphaned_download(
+                data.get("repo_type"),
+                repo_id,
+                data.get("variant"),
+                data.get("transport"),
+            )
+        except Exception as exc:
+            logger.debug("Reaper failed for breadcrumb %s: %s", entry, exc)
+        _safe_unlink(entry)
+
+
+def _purge_incomplete_blobs(
+    entry: Path,
+    only_hashes: Optional[frozenset[str]] = None,
+    protected_hashes: Optional[frozenset[str]] = None,
+) -> int:
+    """Delete matching ``*.incomplete`` blobs beneath *entry*; return the count
+    removed. Per-file failures are swallowed.
+
+    ``only_hashes`` whitelists which partials may be purged; ``None`` means
+    every partial (full-repo snapshot/dataset). ``protected_hashes`` is honoured
+    unconditionally, even when ``only_hashes`` is ``None``, so a blob a
+    concurrent same-repo peer is writing is never purged from under it."""
+    blobs_dir = entry / "blobs"
+    if not blobs_dir.is_dir():
+        return 0
+    removed = 0
+    try:
+        candidates = list(blobs_dir.iterdir())
+    except OSError:
+        return 0
+    for blob in candidates:
+        try:
+            if not blob.is_file():
+                continue
+            if not blob.name.endswith(INCOMPLETE_SUFFIX):
+                continue
+            blob_hash = blob.name[: -len(INCOMPLETE_SUFFIX)]
+            if protected_hashes and blob_hash in protected_hashes:
+                continue
+            if only_hashes is not None and blob_hash not in only_hashes:
+                continue
+            blob.unlink()
+            removed += 1
+        except OSError:
+            # Swallow; downstream snapshot_download surfaces a precise error if
+            # it actually can't proceed.
+            continue
+    return removed
+
+
+def _iter_active_snapshot_dirs(repo_type: str, repo_id: str) -> Iterator[Path]:
+    for entry in iter_active_repo_cache_dirs(repo_type, repo_id):
+        snapshots_dir = entry / "snapshots"
+        if not snapshots_dir.is_dir():
+            continue
+        try:
+            snapshots = list(snapshots_dir.iterdir())
+        except OSError:
+            continue
+        for snapshot in snapshots:
+            if snapshot.is_dir():
+                yield snapshot
+
+
+def _manifest_verifies_against_active_cache(repo_type: str, repo_id: str, manifest) -> bool:
+    from hub.utils import download_manifest
+    for snapshot_dir in _iter_active_snapshot_dirs(repo_type, repo_id):
+        if download_manifest.verify_against_disk(manifest, snapshot_dir).ok:
+            return True
+    return False
+
+
+def _manifest_has_active_incomplete_blobs(repo_type: str, repo_id: str, manifest) -> bool:
+    if not getattr(manifest, "variant", None):
+        return has_active_incomplete_blobs(repo_type, repo_id)
+    expected_hashes = frozenset(
+        expected.sha256 for expected in manifest.expected_files if expected.sha256
+    )
+    if not expected_hashes:
+        return has_active_incomplete_blobs(repo_type, repo_id)
+    return bool(
+        incomplete_blob_hashes(repo_type, repo_id, active_only = True).intersection(expected_hashes)
+    )
+
+
+def _marker_path(entry: Path, variant: Optional[str] = None) -> Path:
+    if not variant:
+        return entry / TRANSPORT_MARKER_NAME
+    digest = hashlib.sha256(variant.strip().lower().encode("utf-8")).hexdigest()[:24]
+    return entry / f"{TRANSPORT_MARKER_NAME}.gguf-{digest}"
+
+
+def _is_transport_marker_file(path: Path) -> bool:
+    # Matches ".transport", its tmps, and variant-scoped ".transport.gguf-*".
+    # Real HF cache entries (blobs/refs/snapshots/.no_exist) never start with
+    # ".transport.".
+    return path.name == TRANSPORT_MARKER_NAME or path.name.startswith(f"{TRANSPORT_MARKER_NAME}.")
+
+
+def _companion_marker_path(entry: Path) -> Path:
+    return entry / f"{TRANSPORT_MARKER_NAME}.companion"
+
+
+def _read_marker_value(marker: Path) -> Optional[str]:
+    try:
+        if not marker.exists():
+            return None
+        value = marker.read_text().strip()
+    except OSError:
+        return None
+    return value if value in VALID_TRANSPORTS else None
+
+
+def _write_marker_value(marker: Path, mode: str) -> None:
+    try:
+        # tmp + rename so a SIGKILL mid-write can't leave a half-written marker.
+        # The tmp name is per-process so concurrent writers don't clobber tmps.
+        tmp = marker.with_name(f"{marker.name}.tmp-{os.getpid()}")
+        tmp.write_text(mode)
+        os.replace(tmp, marker)
+    except OSError:
+        # Best-effort: a missing marker next run purges the partial defensively,
+        # the safe failure mode.
+        pass
+
+
+def _read_marker(entry: Path, variant: Optional[str] = None) -> Optional[str]:
+    return _read_marker_value(_marker_path(entry, variant))
+
+
+def _write_marker(
+    entry: Path,
+    mode: str,
+    variant: Optional[str] = None,
+) -> None:
+    _write_marker_value(_marker_path(entry, variant), mode)
+
+
+def _read_companion_marker(entry: Path) -> Optional[str]:
+    return _read_marker_value(_companion_marker_path(entry))
+
+
+def _write_companion_marker(entry: Path, mode: str) -> None:
+    _write_marker_value(_companion_marker_path(entry), mode)
+
+
+def prepare_cache_for_transport(
+    repo_type: str,
+    repo_id: str,
+    mode: str,
+    variant: Optional[str] = None,
+    only_blob_hashes: Optional[frozenset[str]] = None,
+    companion_blob_hashes: Optional[frozenset[str]] = None,
+    protected_blob_hashes: Optional[frozenset[str]] = None,
+) -> int:
+    """Guarantee any pre-existing ``.incomplete`` blobs are SAFE to resume under
+    *mode*. Returns the number of partial blobs purged for untrusted provenance.
+
+    Two marker scopes govern GGUF downloads. ``only_blob_hashes`` are the
+    variant's own (main quant) blobs, judged by the ``variant``-scoped marker;
+    ``None`` widens the scope to every partial for full-repo snapshots/datasets.
+    ``companion_blob_hashes`` are blobs shared across sibling variants (a vision
+    mmproj), judged by a separate repo-scoped companion marker — so a companion
+    partial is trusted against the transport that wrote it, not against
+    whichever sibling variant resumes next.
+
+    The contract:
+    - HTTP mode: a partial is trusted ONLY when its governing marker equals
+      ``"http"``. Any other case (missing/unreadable/mismatched marker) purges,
+      since the HTTP resumer would otherwise append to a sparse
+      XET/parallel-Range partial and silently produce a corrupt blob.
+    - XET mode: incomplete blobs are purged (``hf_xet.download_files`` rewrites
+      from scratch, so this only fixes UI accounting — bytes already in CAS are
+      reused via the chunk-cache). Scoped to ``only_blob_hashes``: companion
+      blobs fall outside that set and survive (shared, and XET overwrites them).
+
+    ``protected_blob_hashes`` are blobs a concurrent same-repo peer is writing;
+    they are excluded from every purge so a shared companion is never deleted
+    mid-write.
+
+    Scope: only the active ``HF_HUB_CACHE`` root is inspected. That suffices for
+    resume safety because ``snapshot_download`` runs without a ``cache_dir``
+    override and so can only read or resume a ``.incomplete`` under this same
+    active root. Markers are written for the new mode before returning.
+    """
+    if mode not in VALID_TRANSPORTS:
+        raise ValueError(f"Invalid transport mode: {mode!r}")
+    root = hf_cache_root(create = True)
+    if root is None:
+        return 0
+    target = target_dir_name(repo_type, repo_id)
+    try:
+        entries = [e for e in root.iterdir() if e.name.lower() == target]
+    except OSError:
+        return 0
+    if not entries:
+        # First download: pre-create the repo dir so the marker lands before the
+        # worker writes any bytes. Otherwise a SIGKILL mid-download leaves a
+        # partial with no marker that the resume then purges.
+        canonical = repo_cache_dir_name(repo_type, repo_id)
+        new_entry = root / canonical
+        try:
+            new_entry.mkdir(exist_ok = True)
+        except OSError:
+            return 0
+        entries = [new_entry]
+    protected = protected_blob_hashes or frozenset()
+    has_companion = bool(companion_blob_hashes)
+    total_purged = 0
+    for entry in entries:
+        if mode == TRANSPORT_XET:
+            total_purged += _purge_incomplete_blobs(entry, only_blob_hashes, protected)
+        else:
+            if _read_marker(entry, variant) != mode:
+                total_purged += _purge_incomplete_blobs(entry, only_blob_hashes, protected)
+            if companion_blob_hashes and _read_companion_marker(entry) != mode:
+                total_purged += _purge_incomplete_blobs(entry, companion_blob_hashes, protected)
+        _write_marker(entry, mode, variant)
+        if has_companion:
+            _write_companion_marker(entry, mode)
+    return total_purged
+
+
+_HF_TOKEN_RE = re.compile(r"hf_[A-Za-z0-9]{20,}")
+_BEARER_RE = re.compile(r"(?i)bearer\s+[A-Za-z0-9._\-]+")
+
+
+def scrub_secrets(text: str, *, hf_token: Optional[str] = None) -> str:
+    if not text:
+        return text
+    cleaned = text
+    if hf_token:
+        cleaned = cleaned.replace(hf_token, "***")
+    cleaned = _BEARER_RE.sub("Bearer ***", cleaned)
+    cleaned = _HF_TOKEN_RE.sub("hf_***", cleaned)
+    return cleaned
+
+
+def purge_empty_marker_dir(
+    repo_type: str,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> bool:
+    """Remove the failed download's own transport marker from a marker-only dir.
+
+    ``prepare_cache_for_transport`` pre-creates the dir + marker before any
+    download; a failure during validation/auth/network setup leaves the dir as
+    marker-only litter. Only the failed download's OWN marker is removed (the
+    repo-scope ``.transport`` or the variant-scoped ``.transport.gguf-*`` plus
+    its ``.tmp-*`` siblings); a sibling variant's marker and the shared
+    ``.transport.companion`` are left intact, so cancelling one quant never
+    strips a peer's provenance. A dir holding ``blobs/``/``snapshots/``/``refs/``
+    won't match and is left untouched, so a resumable partial isn't blown away.
+    """
+    cleaned = False
+    for entry in iter_repo_cache_dirs(repo_type, repo_id):
+        try:
+            contents = list(entry.iterdir())
+        except OSError:
+            continue
+        if not contents or not all(_is_transport_marker_file(item) for item in contents):
+            continue
+        own_name = _marker_path(entry, variant).name
+        own_markers = [
+            item
+            for item in contents
+            if item.name == own_name or item.name.startswith(f"{own_name}.tmp")
+        ]
+        if not own_markers:
+            continue
+        try:
+            for marker in own_markers:
+                marker.unlink()
+        except OSError:
+            continue
+        cleaned = True
+        try:
+            entry.rmdir()
+        except OSError:
+            continue
+    return cleaned
+
+
+def read_active_transport_marker(
+    repo_type: str,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> Optional[str]:
+    for entry in iter_active_repo_cache_dirs(repo_type, repo_id):
+        value = _read_marker(entry, variant)
+        if value is not None:
+            return value
+    return None
+
+
+def is_resumable_partial(
+    repo_type: str,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> bool:
+    """True only when a partial exists AND was produced by a byte-resumable
+    writer (the HTTP transport). XET partials exist on disk but are discarded on
+    the next download attempt."""
+    if not has_active_incomplete_blobs(repo_type, repo_id):
+        return False
+    return read_active_transport_marker(repo_type, repo_id, variant) == TRANSPORT_HTTP
+
+
+def incomplete_blob_hashes(
+    repo_type: str,
+    repo_id: str,
+    *,
+    active_only: bool = False,
+) -> set[str]:
+    out: set[str] = set()
+    entries = (
+        iter_active_repo_cache_dirs(repo_type, repo_id)
+        if active_only
+        else iter_repo_cache_dirs(repo_type, repo_id)
+    )
+    for entry in entries:
+        blobs_dir = entry / "blobs"
+        if not blobs_dir.is_dir():
+            continue
+        try:
+            for blob in blobs_dir.iterdir():
+                if blob.is_file() and blob.name.endswith(INCOMPLETE_SUFFIX):
+                    out.add(blob.name[: -len(INCOMPLETE_SUFFIX)])
+        except OSError:
+            continue
+    return out
+
+
+def completed_blob_bytes(repo_type: str, repo_id: str, blob_hashes: frozenset[str]) -> int:
+    """Sum finalized blob bytes for *blob_hashes* in the active HF cache root.
+
+    A worker only writes to the active ``HF_HUB_CACHE`` root, so a baseline must
+    ignore legacy/default roots that ``snapshot_download`` won't reuse this run.
+    """
+    if not blob_hashes:
+        return 0
+    total = 0
+    for entry in iter_active_repo_cache_dirs(repo_type, repo_id):
+        blobs_dir = entry / "blobs"
+        if not blobs_dir.is_dir():
+            continue
+        for blob_hash in blob_hashes:
+            blob = blobs_dir / blob_hash
+            try:
+                if blob.is_file():
+                    total += max(0, int(blob.stat().st_size))
+            except OSError:
+                continue
+    return total
+
+
+def existing_blob_bytes(repo_type: str, repo_id: str, blob_hashes: frozenset[str]) -> int:
+    """Bytes already on disk (finalized + ``.incomplete``) for *blob_hashes* in
+    the active HF cache root. A blob is in exactly one state, so summing both
+    candidate names never double-counts. Used to size what a (possibly resumed)
+    download still needs to write before the run starts."""
+    if not blob_hashes:
+        return 0
+    total = 0
+    for entry in iter_active_repo_cache_dirs(repo_type, repo_id):
+        blobs_dir = entry / "blobs"
+        if not blobs_dir.is_dir():
+            continue
+        for blob_hash in blob_hashes:
+            for name in (blob_hash, f"{blob_hash}{INCOMPLETE_SUFFIX}"):
+                blob = blobs_dir / name
+                try:
+                    if blob.is_file():
+                        total += max(0, int(blob.stat().st_size))
+                except OSError:
+                    continue
+    return total
+
+
+JobState = Literal["idle", "running", "cancelling", "cancelled", "complete", "error"]
+
+TERMINAL_STATES = frozenset({"complete", "cancelled", "error"})
+_ACTIVE_STATES = frozenset({"running", "cancelling"})
+
+
+@dataclass(frozen = True)
+class DownloadState:
+    state: JobState
+    error: Optional[str] = None
+
+
+@dataclass(frozen = True)
+class DownloadMetadata:
+    repo_type: RepoType
+    repo_id: str
+    variant: Optional[str]
+    transport: Optional[str]
+    # GGUF variant main/writable hashes, identifying the variant-specific shards
+    # for concurrency decisions.
+    blob_hashes: frozenset[str] = field(default_factory = frozenset)
+    # Full required hash set for progress/completion (includes the shared mmproj
+    # companion for vision GGUF repos).
+    progress_blob_hashes: frozenset[str] = field(default_factory = frozenset)
+    # Bytes already complete before this job started; not counted as this run's
+    # progress.
+    completed_baseline_bytes: int = 0
+
+
+@dataclass(frozen = True)
+class ActiveDownloadRef:
+    key: str
+    state: str
+    metadata: Optional[DownloadMetadata]
+    generation: int
+
+
+def normalize_repo_key(repo_id: str) -> str:
+    return repo_id.strip().lower()
+
+
+def normalize_job_key(key: str) -> str:
+    repo, sep, variant = key.partition("::")
+    repo_key = normalize_repo_key(repo)
+    return f"{repo_key}{sep}{variant.strip().lower()}" if sep else repo_key
+
+
+def _repo_of_key(key: str) -> str:
+    return normalize_repo_key(key.split("::", 1)[0])
+
+
+def variant_from_key(key: str) -> Optional[str]:
+    """Parse the variant suffix from a 'repo_id::variant' key. Empty
+    variant returns None — matches the manifest/marker calling
+    convention for full-snapshot models and datasets."""
+    if "::" not in key:
+        return None
+    _, _, variant = key.partition("::")
+    return variant or None
+
+
+def persist_cancel_marker(
+    repo_type: Optional[RepoType],
+    repo_id: Optional[str],
+    variant: Optional[str],
+    transport: Optional[str],
+    *,
+    logger = logger,
+) -> None:
+    if not repo_type or not repo_id:
+        return
+    try:
+        from hub.utils.download_manifest import write_cancel_marker
+        if not write_cancel_marker(
+            repo_type,
+            repo_id,
+            variant,
+            transport = transport,
+        ):
+            logger.debug("write_cancel_marker returned False for %s", repo_id)
+    except Exception as exc:
+        logger.debug("write_cancel_marker failed for %s: %s", repo_id, exc)
+
+
+_REGISTRIES: "weakref.WeakSet[DownloadRegistry]" = weakref.WeakSet()
+_NAMED_REGISTRIES: dict[str, "DownloadRegistry"] = {}
+_NAMED_REGISTRIES_LOCK = threading.Lock()
+
+
+def terminate_active_downloads() -> None:
+    """Best-effort shutdown hook called from the FastAPI lifespan.
+
+    Walks every live DownloadRegistry instance and SIGKILLs any in-flight
+    workers so the parent exit path doesn't leak zombies. The WeakSet drops
+    ad-hoc registries (e.g. test fixtures) automatically once their last
+    strong reference is gone; the long-lived named registries stay reachable
+    via ``_NAMED_REGISTRIES``. Quiet on its own failures: shutdown must not
+    raise.
+    """
+    for registry in list(_REGISTRIES):
+        try:
+            registry.terminate_all("download")
+        except Exception as exc:
+            logger.warning("terminate_active_downloads: %s", exc)
+
+
+class DownloadRegistry:
+    """Thread-safe state machine for background HF download jobs.
+
+    One instance backs model downloads (keys ``repo_id::variant``) and another
+    backs dataset downloads (keys ``repo_id``). Repo-scoped tracking serializes
+    full snapshots, datasets, cross-transport work, and deletes; same-transport
+    GGUF variants may run concurrently.
+    """
+
+    def __init__(self, max_terminal: int = 64) -> None:
+        self._jobs: dict[str, DownloadState] = {}
+        self._processes: dict[str, subprocess.Popen] = {}
+        self._repo_active: dict[str, set[str]] = {}
+        self._metadata: dict[str, DownloadMetadata] = {}
+        self._pending_cancel: dict[str, Optional[int]] = {}
+        self._generations: dict[str, int] = {}
+        # Monotonic across keys so an evicted then re-claimed key never reuses a
+        # prior generation (which would let a stale cancel match a new run).
+        self._generation_seq = 0
+        self._deleting: dict[str, set[Optional[str]]] = {}
+        self._lock = threading.Lock()
+        _REGISTRIES.add(self)
+        self._max_terminal = max_terminal
+
+    def _put_terminal_job_locked(
+        self,
+        key: str,
+        state: JobState,
+        error: Optional[str] = None,
+    ) -> None:
+        self._jobs.pop(key, None)
+        self._jobs[key] = DownloadState(state, error)
+        if len(self._jobs) > self._max_terminal:
+            for stale_key, stale in list(self._jobs.items()):
+                if stale.state in TERMINAL_STATES and stale_key != key:
+                    self._jobs.pop(stale_key, None)
+                    self._metadata.pop(stale_key, None)
+                    self._generations.pop(stale_key, None)
+                    if len(self._jobs) <= self._max_terminal:
+                        break
+
+    def set_job(
+        self,
+        key: str,
+        state: JobState,
+        error: Optional[str] = None,
+    ) -> None:
+        key = normalize_job_key(key)
+        with self._lock:
+            if state in TERMINAL_STATES:
+                self._put_terminal_job_locked(key, state, error)
+                self._pending_cancel.pop(key, None)
+                repo = _repo_of_key(key)
+                active = self._repo_active.get(repo)
+                if active is not None:
+                    active.discard(key)
+                    if not active:
+                        self._repo_active.pop(repo, None)
+            else:
+                self._jobs[key] = DownloadState(state, error)
+
+    def get_job(self, key: str) -> DownloadState:
+        key = normalize_job_key(key)
+        with self._lock:
+            return self._jobs.get(key, DownloadState("idle"))
+
+    def current_generation(self, key: str) -> int:
+        key = normalize_job_key(key)
+        with self._lock:
+            return self._generations.get(key, 0)
+
+    def get_job_metadata(self, key: str) -> Optional[DownloadMetadata]:
+        key = normalize_job_key(key)
+        with self._lock:
+            return self._metadata.get(key)
+
+    def _generation_matches_locked(self, key: str, generation: Optional[int]) -> bool:
+        key = normalize_job_key(key)
+        return generation is None or self._generations.get(key, 0) == generation
+
+    def register_process(self, key: str, proc: subprocess.Popen) -> bool:
+        """Register *proc* for *key*. Returns ``False`` when a cancel was
+        requested during the claim→register window (the caller must kill
+        *proc* immediately); ``True`` otherwise."""
+        key = normalize_job_key(key)
+        metadata_to_persist: Optional[DownloadMetadata] = None
+        registered = False
+        breadcrumb_metadata: Optional[DownloadMetadata] = None
+        with self._lock:
+            has_pending_cancel = key in self._pending_cancel
+            pending_generation = self._pending_cancel.pop(key, None)
+            if has_pending_cancel and self._generation_matches_locked(
+                key,
+                pending_generation,
+            ):
+                self._put_terminal_job_locked(key, "cancelled")
+                metadata_to_persist = self._metadata.pop(key, None)
+                repo = _repo_of_key(key)
+                active = self._repo_active.get(repo)
+                if active is not None:
+                    active.discard(key)
+                    if not active:
+                        self._repo_active.pop(repo, None)
+            else:
+                self._processes[key] = proc
+                breadcrumb_metadata = self._metadata.get(key)
+                registered = True
+        if registered:
+            try:
+                write_worker_breadcrumb(key, proc.pid, breadcrumb_metadata)
+            except Exception as exc:
+                logger.debug("Could not record worker breadcrumb: %s", exc)
+            return True
+        if metadata_to_persist is not None:
+            persist_cancel_marker(
+                metadata_to_persist.repo_type,
+                metadata_to_persist.repo_id,
+                metadata_to_persist.variant,
+                metadata_to_persist.transport,
+            )
+        return False
+
+    def mark_pending_cancel(
+        self,
+        key: str,
+        generation: Optional[int] = None,
+    ) -> bool:
+        """Record a cancel for an active job whose worker process hasn't
+        registered yet. Returns ``True`` when the pending cancel was armed,
+        so :func:`register_process` will kill the process on arrival."""
+        key = normalize_job_key(key)
+        with self._lock:
+            if self._jobs.get(key, DownloadState("idle")).state not in _ACTIVE_STATES:
+                return False
+            if not self._generation_matches_locked(key, generation):
+                return False
+            self._pending_cancel[key] = generation
+            self._jobs[key] = DownloadState("cancelling")
+            return True
+
+    def cancel_requested(self, key: str) -> bool:
+        """True when *we* initiated a stop for *key* (a pending cancel armed
+        before the worker registered, or the job already moved to
+        ``cancelling``). Lets exit classification tell an intentional kill
+        apart from an OOM/external SIGKILL."""
+        key = normalize_job_key(key)
+        with self._lock:
+            if key in self._pending_cancel:
+                return True
+            return self._jobs.get(key, DownloadState("idle")).state == "cancelling"
+
+    def get_process(self, key: str) -> Optional[subprocess.Popen]:
+        key = normalize_job_key(key)
+        with self._lock:
+            return self._processes.get(key)
+
+    def drop_process(self, key: str, proc: subprocess.Popen) -> bool:
+        key = normalize_job_key(key)
+        with self._lock:
+            if self._processes.get(key) is not proc:
+                return False
+            self._processes.pop(key, None)
+        remove_worker_breadcrumb(key)
+        return True
+
+    def claim(
+        self,
+        key: str,
+        transport: str,
+        *,
+        repo_type: Optional[RepoType] = None,
+        repo_id: Optional[str] = None,
+        variant: Optional[str] = None,
+        blob_hashes: Optional[frozenset[str]] = None,
+        progress_blob_hashes: Optional[frozenset[str]] = None,
+        completed_baseline_bytes: int = 0,
+    ) -> tuple[bool, str]:
+        key = normalize_job_key(key)
+        repo = _repo_of_key(key)
+        requested_hashes = blob_hashes or frozenset()
+        requested_progress_hashes = progress_blob_hashes or frozenset()
+        with self._lock:
+            deleting_scopes = self._deleting.get(repo)
+            if deleting_scopes is not None and (
+                None in deleting_scopes or variant_from_key(key) in deleting_scopes
+            ):
+                return False, "deleting"
+            active = self._repo_active.get(repo, set())
+            stale_keys: list[str] = []
+            conflict_state: Optional[str] = None
+            for other_key in active:
+                if other_key == key:
+                    continue
+                other_status = self._jobs.get(other_key)
+                if other_status is None or other_status.state not in _ACTIVE_STATES:
+                    stale_keys.append(other_key)
+                    continue
+                other_metadata = self._metadata.get(other_key)
+                # Same-transport variants of one model run concurrently: each
+                # worker purges only its own re-resolved main blobs and the
+                # shared companion is guarded by its marker. Cross-transport
+                # stays serialized so an HTTP resume and an XET rewrite never
+                # write one shared blob at once.
+                concurrent_gguf_variants = (
+                    repo_type == "model"
+                    and bool(variant)
+                    and other_metadata is not None
+                    and other_metadata.repo_type == "model"
+                    and bool(other_metadata.variant)
+                    and other_metadata.transport == transport
+                )
+                if concurrent_gguf_variants:
+                    continue
+                conflict_state = other_status.state
+                break
+            for stale_key in stale_keys:
+                active.discard(stale_key)
+            if conflict_state is not None:
+                return False, conflict_state
+            current = self._jobs.get(key, DownloadState("idle")).state
+            if current in _ACTIVE_STATES:
+                return False, current
+            self._generation_seq += 1
+            self._generations[key] = self._generation_seq
+            self._jobs[key] = DownloadState("running")
+            self._repo_active.setdefault(repo, active).add(key)
+            if repo_type and repo_id:
+                self._metadata[key] = DownloadMetadata(
+                    repo_type = repo_type,
+                    repo_id = repo_id,
+                    variant = variant,
+                    transport = transport,
+                    blob_hashes = requested_hashes,
+                    progress_blob_hashes = requested_progress_hashes,
+                    completed_baseline_bytes = max(
+                        0,
+                        int(completed_baseline_bytes or 0),
+                    ),
+                )
+            else:
+                self._metadata.pop(key, None)
+            return True, "running"
+
+    def adoptable(self, key: str) -> bool:
+        """True when *key* itself has a live job a client can attach to.
+
+        Lets a rejected claim distinguish a collision with this key's own
+        in-flight job (pollable) from one blocked by a different repo job
+        or an in-progress delete, where no job exists for this key."""
+        key = normalize_job_key(key)
+        with self._lock:
+            return self._jobs.get(key, DownloadState("idle")).state in _ACTIVE_STATES
+
+    def _active_job_variant_locked(self, key: str) -> Optional[str]:
+        metadata = self._metadata.get(key)
+        if metadata is not None:
+            return (metadata.variant or "").strip().lower() or None
+        return variant_from_key(key)
+
+    def _delete_blocked_by_active_locked(self, repo_id: str, variant: Optional[str]) -> bool:
+        """Whether an active download conflicts with deleting *repo_id*/*variant*.
+
+        A whole-repo delete (``variant is None``) conflicts with any active
+        download. A variant delete conflicts only with that same variant or a
+        whole-repo download writing the shared snapshot; other quantizations
+        download concurrently and never block it."""
+        for key in self._repo_active.get(repo_id, set()):
+            job = self._jobs.get(key)
+            if job is None or job.state not in _ACTIVE_STATES:
+                continue
+            if variant is None:
+                return True
+            other_variant = self._active_job_variant_locked(key)
+            if other_variant is None or other_variant == variant:
+                return True
+        return False
+
+    def peer_blob_hashes(self, key: str) -> frozenset[str]:
+        """Union of the writable blob hashes of every OTHER active download for
+        this key's repo. A worker excludes these from its purge so it never
+        deletes an ``.incomplete`` a concurrent same-repo variant is writing
+        (e.g. a shared mmproj bundled with two GGUF quants)."""
+        key = normalize_job_key(key)
+        repo = _repo_of_key(key)
+        out: set[str] = set()
+        with self._lock:
+            for other_key in self._repo_active.get(repo, set()):
+                if other_key == key:
+                    continue
+                job = self._jobs.get(other_key)
+                if job is None or job.state not in _ACTIVE_STATES:
+                    continue
+                metadata = self._metadata.get(other_key)
+                if metadata is not None:
+                    out |= set(metadata.progress_blob_hashes or metadata.blob_hashes)
+        return frozenset(out)
+
+    def active_jobs(self, repo_id: str) -> dict[str, str]:
+        """Map of every active job key for *repo_id* to its state."""
+        repo_id = normalize_repo_key(repo_id)
+        with self._lock:
+            result: dict[str, str] = {}
+            for key in self._repo_active.get(repo_id, set()):
+                job = self._jobs.get(key)
+                if job is not None and job.state in _ACTIVE_STATES:
+                    metadata = self._metadata.get(key)
+                    display_key = (
+                        f"{_repo_of_key(key)}::{metadata.variant}"
+                        if metadata is not None and metadata.variant
+                        else key
+                    )
+                    result[display_key] = job.state
+            return result
+
+    def active_job_refs(self, repo_id: Optional[str] = None) -> list[ActiveDownloadRef]:
+        repo_key = normalize_repo_key(repo_id) if repo_id else None
+        with self._lock:
+            if repo_key:
+                candidate_keys = list(self._repo_active.get(repo_key, set()))
+            else:
+                candidate_keys = [key for active in self._repo_active.values() for key in active]
+            refs: list[ActiveDownloadRef] = []
+            for key in candidate_keys:
+                job = self._jobs.get(key)
+                if job is None or job.state not in _ACTIVE_STATES:
+                    continue
+                refs.append(
+                    ActiveDownloadRef(
+                        key = key,
+                        state = job.state,
+                        metadata = self._metadata.get(key),
+                        generation = self._generations.get(key, 0),
+                    )
+                )
+            return refs
+
+    def begin_delete(
+        self,
+        repo_id: str,
+        variant: Optional[str] = None,
+    ) -> bool:
+        """Reserve *repo_id* (or one GGUF *variant* of it) for deletion. Returns
+        ``False`` when a conflicting download is active (a whole-repo delete vs
+        any download, a variant delete vs that same variant or a whole-repo
+        download), so sibling quantizations keep downloading. On success the
+        scope is marked so :func:`claim` rejects overlapping downloads until
+        :func:`end_delete` runs, closing the check-then-delete race against a
+        concurrently spawned worker."""
+        repo_id = normalize_repo_key(repo_id)
+        variant_key = (variant or "").strip().lower() or None
+        with self._lock:
+            if self._delete_blocked_by_active_locked(repo_id, variant_key):
+                return False
+            self._deleting.setdefault(repo_id, set()).add(variant_key)
+            return True
+
+    def end_delete(
+        self,
+        repo_id: str,
+        variant: Optional[str] = None,
+    ) -> None:
+        repo_id = normalize_repo_key(repo_id)
+        variant_key = (variant or "").strip().lower() or None
+        with self._lock:
+            scopes = self._deleting.get(repo_id)
+            if scopes is None:
+                return
+            scopes.discard(variant_key)
+            if not scopes:
+                self._deleting.pop(repo_id, None)
+
+    def has_active_peer_variant(self, repo_id: str, variant: Optional[str]) -> bool:
+        """Whether a DIFFERENT quantization of *repo_id* is downloading while
+        *variant* is being deleted. When one is, the delete reclaims only this
+        variant's files and leaves the shared companion (mmproj) for the live
+        sibling. Point-in-time (a sibling may claim just after it returns), but
+        safe: the finalized companion is held by deletion's reference-count
+        walk and a sibling starting mid-delete re-fetches it, so protection
+        never depends on the sibling having resolved its blob hashes."""
+        repo_id = normalize_repo_key(repo_id)
+        target = (variant or "").strip().lower() or None
+        with self._lock:
+            for key in self._repo_active.get(repo_id, set()):
+                job = self._jobs.get(key)
+                if job is None or job.state not in _ACTIVE_STATES:
+                    continue
+                if self._active_job_variant_locked(key) != target:
+                    return True
+        return False
+
+    def request_cancel(
+        self,
+        key: str,
+        proc: subprocess.Popen,
+        generation: Optional[int] = None,
+    ) -> bool:
+        """Authorize a SIGKILL for the registered *proc*. Idempotent across an
+        active job's lifetime: a repeated cancel while already ``cancelling``
+        still returns ``True`` so a kill that raced and lost can be re-sent."""
+        key = normalize_job_key(key)
+        with self._lock:
+            if self._processes.get(key) is not proc:
+                return False
+            if not self._generation_matches_locked(key, generation):
+                return False
+            if self._jobs.get(key, DownloadState("idle")).state not in _ACTIVE_STATES:
+                return False
+            self._jobs[key] = DownloadState("cancelling")
+            return True
+
+    def terminate_all(self, kind: str = "download") -> None:
+        with self._lock:
+            live = [
+                (key, proc, self._metadata.get(key))
+                for key, proc in self._processes.items()
+                if proc.poll() is None
+            ]
+            # Flag as an intentional stop so the watcher's exit classification
+            # reports them cancelled rather than an OOM/crash once SIGKILL lands.
+            for key, _proc, _metadata in live:
+                if self._jobs.get(key, DownloadState("idle")).state == "running":
+                    self._jobs[key] = DownloadState("cancelling")
+        reaped: list[tuple[str, subprocess.Popen, Optional[DownloadMetadata]]] = []
+        for key, proc, metadata in live:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+            except Exception as e:
+                logger.warning(f"shutdown: failed to kill {kind} worker for {key}: {e}")
+                if metadata is not None:
+                    persist_cancel_marker(
+                        metadata.repo_type,
+                        metadata.repo_id,
+                        metadata.variant,
+                        metadata.transport,
+                    )
+                continue
+            reaped.append((key, proc, metadata))
+        deadline = time.monotonic() + 10.0
+        for key, proc, metadata in reaped:
+            try:
+                proc.wait(timeout = max(0.0, deadline - time.monotonic()))
+            except subprocess.TimeoutExpired:
+                logger.warning(f"shutdown: {kind} worker for {key} did not exit after kill")
+            except Exception:
+                pass
+            # Mark only genuinely interrupted workers (rc != 0, or None on wait
+            # timeout); persisting before the exit is known would strand a stale
+            # marker on a worker that completed cleanly during shutdown.
+            if metadata is not None and proc.poll() != 0:
+                persist_cancel_marker(
+                    metadata.repo_type,
+                    metadata.repo_id,
+                    metadata.variant,
+                    metadata.transport,
+                )
+
+
+def _named_registry(name: str) -> DownloadRegistry:
+    with _NAMED_REGISTRIES_LOCK:
+        registry = _NAMED_REGISTRIES.get(name)
+        if registry is None:
+            registry = DownloadRegistry()
+            _NAMED_REGISTRIES[name] = registry
+        return registry
+
+
+def get_models_registry() -> DownloadRegistry:
+    return _named_registry("models")
+
+
+def get_datasets_registry() -> DownloadRegistry:
+    return _named_registry("datasets")
diff --git a/studio/backend/hub/utils/gguf.py b/studio/backend/hub/utils/gguf.py
new file mode 100644
index 0000000000..4bd1961c33
--- /dev/null
+++ b/studio/backend/hub/utils/gguf.py
@@ -0,0 +1,406 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF filename helpers. Quantization variants are derived from filenames, not parsed from binary GGUF headers."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+_GGUF_MODEL_INFO_TIMEOUT_SECONDS = 5.0
+
+
+@dataclass
+class GgufVariantInfo:
+    filename: str
+    quant: str
+    size_bytes: int
+    display_label: Optional[str] = None
+    download_size_bytes: int = 0
+
+
+GGUF_QUANT_PREFERENCE = [
+    "UD-Q4_K_XL",
+    "UD-Q4_K_L",
+    "UD-Q5_K_XL",
+    "UD-Q3_K_XL",
+    "UD-Q6_K_XL",
+    "UD-Q6_K_S",
+    "UD-Q8_K_XL",
+    "UD-Q2_K_XL",
+    "UD-IQ4_NL",
+    "UD-IQ4_XS",
+    "UD-IQ3_S",
+    "UD-IQ3_XXS",
+    "UD-IQ2_M",
+    "UD-IQ2_XXS",
+    "UD-IQ1_M",
+    "UD-IQ1_S",
+    "Q4_K_M",
+    "Q4_K_S",
+    "Q5_K_M",
+    "Q5_K_S",
+    "Q6_K",
+    "Q8_0",
+    "Q3_K_M",
+    "Q3_K_L",
+    "Q3_K_S",
+    "Q2_K",
+    "Q2_K_L",
+    "IQ4_NL",
+    "IQ4_XS",
+    "IQ3_M",
+    "IQ3_XXS",
+    "IQ2_M",
+    "IQ1_M",
+    "F16",
+    "BF16",
+    "F32",
+]
+
+_GGUF_SPLIT_SUFFIX_RE = re.compile(r"-\d{3,}-of-\d{3,}", re.IGNORECASE)
+_GGUF_QUANT_RE = re.compile(
+    r"(UD-)?"
+    r"(MXFP[0-9]+(?:_[A-Z0-9]+)*"
+    r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
+    r"|TQ[0-9]+_[0-9]+"
+    r"|Q[0-9]+_K_[A-Z]+"
+    r"|Q[0-9]+_[0-9]+"
+    r"|Q[0-9]+_K"
+    r"|BF16|F16|F32)",
+    re.IGNORECASE,
+)
+
+
+def is_mmproj_filename(filename: str) -> bool:
+    return "mmproj" in filename.lower()
+
+
+def is_gguf_filename(filename: str) -> bool:
+    return filename.lower().endswith(".gguf")
+
+
+# Cap recursive walks so a huge or system path cannot run unbounded.
+_MAX_LOCAL_SCAN_ENTRIES = 100_000
+
+
+def iter_gguf_files(directory: Path, recursive: bool = False):
+    if not directory.is_dir():
+        return
+    if recursive:
+        seen = 0
+        # os.walk skips unreadable subdirs instead of raising (e.g. /proc).
+        for dirpath, dirnames, filenames in os.walk(directory, onerror = lambda _e: None):
+            for name in filenames:
+                if is_gguf_filename(name):
+                    yield Path(dirpath) / name
+            seen += len(dirnames) + len(filenames)
+            if seen > _MAX_LOCAL_SCAN_ENTRIES:
+                return
+        return
+    try:
+        entries = list(directory.iterdir())
+    except OSError:
+        return
+    for file in entries:
+        try:
+            if file.is_file() and is_gguf_filename(file.name):
+                yield file
+        except OSError:
+            continue
+
+
+def pick_best_gguf(filenames: list[str]) -> Optional[str]:
+    gguf_files = [
+        name for name in filenames if is_gguf_filename(name) and not is_mmproj_filename(name)
+    ]
+    if not gguf_files:
+        return None
+    by_quant: dict[str, str] = {}
+    for name in gguf_files:
+        by_quant.setdefault(extract_quant_label(name).upper(), name)
+    for quant in GGUF_QUANT_PREFERENCE:
+        filename = by_quant.get(quant.upper())
+        if filename is not None:
+            return filename
+    return gguf_files[0]
+
+
+def _gguf_stem(filename: str) -> str:
+    basename = filename.rsplit("/", 1)[-1]
+    return _GGUF_SPLIT_SUFFIX_RE.sub("", basename.rsplit(".", 1)[0]).strip()
+
+
+_FLOAT_PRECISION_QUANTS = frozenset({"BF16", "F16", "F32"})
+
+
+def _select_quant_match(text: str) -> Optional[re.Match]:
+    fallback: Optional[re.Match] = None
+    for match in _GGUF_QUANT_RE.finditer(text):
+        if match.group(2).upper() in _FLOAT_PRECISION_QUANTS:
+            if fallback is None:
+                fallback = match
+            continue
+        return match
+    return fallback
+
+
+def extract_quant_token(filename: str) -> Optional[str]:
+    stem = _gguf_stem(filename)
+    match = _select_quant_match(stem)
+    if not match and "/" in filename:
+        parents = filename.rsplit("/", 1)[0]
+        for segment in reversed(parents.split("/")):
+            parent_match = _select_quant_match(segment)
+            if parent_match:
+                match = parent_match
+                break
+    if match:
+        prefix = match.group(1) or ""
+        return f"{prefix}{match.group(2)}"
+    return None
+
+
+def _unknown_gguf_variant_key(filename: str) -> str:
+    stem = _gguf_stem(filename)
+    if "/" not in filename:
+        return stem or "gguf"
+    parents = filename.rsplit("/", 1)[0].strip("/")
+    return f"{parents}/{stem}" if parents and stem else stem or "gguf"
+
+
+def extract_quant_label(filename: str) -> str:
+    return extract_quant_token(filename) or _unknown_gguf_variant_key(filename)
+
+
+def _apply_gguf_display_labels(variants: list[GgufVariantInfo]) -> None:
+    unknown_variants = [
+        variant for variant in variants if extract_quant_token(variant.filename) is None
+    ]
+    if not unknown_variants:
+        return
+    ambiguous = len(unknown_variants) > 1
+    for variant in unknown_variants:
+        variant.display_label = f"GGUF · {variant.filename}" if ambiguous else "GGUF"
+
+
+def _env_offline() -> bool:
+    return os.environ.get("HF_HUB_OFFLINE", "").lower() in (
+        "1",
+        "true",
+        "yes",
+    ) or os.environ.get("TRANSFORMERS_OFFLINE", "").lower() in ("1", "true", "yes")
+
+
+def iter_hf_cache_snapshots(repo_id: str):
+    from hub.utils.hf_cache_state import iter_repo_cache_dirs
+
+    snapshots: list[Path] = []
+    for repo_dir in iter_repo_cache_dirs("model", repo_id):
+        snapshots_dir = repo_dir / "snapshots"
+        if not snapshots_dir.is_dir():
+            continue
+        try:
+            snapshots.extend(snap for snap in snapshots_dir.iterdir() if snap.is_dir())
+        except OSError:
+            continue
+
+    def _mtime(path: Path) -> float:
+        try:
+            return path.stat().st_mtime
+        except OSError:
+            return 0.0
+
+    snapshots.sort(key = _mtime, reverse = True)
+    yield from snapshots
+
+
+def list_gguf_variants_from_hf_cache(repo_id: str) -> Optional[tuple[list[GgufVariantInfo], bool]]:
+    for snapshot in iter_hf_cache_snapshots(repo_id):
+        variants, has_vision = list_local_gguf_variants(str(snapshot))
+        if variants or has_vision:
+            return variants, has_vision
+    return None
+
+
+def list_partial_gguf_variants_from_state(
+    repo_id: str,
+) -> Optional[tuple[list[GgufVariantInfo], bool]]:
+    """Reconstruct GGUF variants from download manifests/markers alone.
+
+    Used when no completed snapshot exists (download cancelled or interrupted)
+    and the HF API is unreachable (offline/gated/private). Each variant's
+    ``quant`` is the stored variant key so a resume passes the matching
+    ``--variant`` back to the worker.
+    """
+    from hub.utils import download_manifest
+
+    # Variant identity on disk is case-insensitive (_entry_key lowercases it), so
+    # dedupe on the lowercased key. Manifests are read first to keep their
+    # original-casing label over a lowercased cancel marker for the same variant.
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for source in (
+        download_manifest.iter_variant_manifests("model", repo_id),
+        download_manifest.iter_variant_markers("model", repo_id),
+    ):
+        for variant, _path in source:
+            key = variant.lower()
+            if key not in seen:
+                seen.add(key)
+                ordered.append(variant)
+    if not ordered:
+        return None
+
+    variants: list[GgufVariantInfo] = []
+    has_vision = False
+    for variant in ordered:
+        manifest = download_manifest.read_manifest("model", repo_id, variant)
+        main_filename: Optional[str] = None
+        size_bytes = 0
+        companion_bytes = 0
+        if manifest is not None:
+            for expected in manifest.expected_files:
+                if not is_gguf_filename(expected.path):
+                    continue
+                if is_mmproj_filename(expected.path):
+                    has_vision = True
+                    companion_bytes += max(0, int(expected.size or 0))
+                    continue
+                if main_filename is None:
+                    main_filename = expected.path
+                size_bytes += max(0, int(expected.size or 0))
+        if main_filename is None:
+            main_filename = f"{variant}.gguf"
+        variants.append(
+            GgufVariantInfo(
+                filename = main_filename,
+                quant = variant,
+                size_bytes = size_bytes,
+                download_size_bytes = size_bytes + companion_bytes,
+            )
+        )
+
+    variants.sort(key = lambda variant: -variant.size_bytes)
+    _apply_gguf_display_labels(variants)
+    return variants, has_vision
+
+
+def list_gguf_variants(
+    repo_id: str, hf_token: Optional[str] = None
+) -> tuple[list[GgufVariantInfo], bool, Optional[list]]:
+    from huggingface_hub import HfApi
+
+    if _env_offline():
+        cached = list_gguf_variants_from_hf_cache(repo_id)
+        if cached is not None:
+            return (*cached, None)
+
+    try:
+        info = HfApi(token = hf_token).model_info(
+            repo_id,
+            files_metadata = True,
+            timeout = _GGUF_MODEL_INFO_TIMEOUT_SECONDS,
+        )
+    except Exception as exc:
+        if type(exc).__name__ in (
+            "RepositoryNotFoundError",
+            "GatedRepoError",
+            "RevisionNotFoundError",
+            "EntryNotFoundError",
+        ):
+            raise
+        cached = list_gguf_variants_from_hf_cache(repo_id)
+        if cached is not None:
+            logger.warning(
+                "HF API unreachable for %s (%s); using local cache snapshot.",
+                repo_id,
+                exc.__class__.__name__,
+            )
+            return (*cached, None)
+        raise
+
+    variants: list[GgufVariantInfo] = []
+    has_vision = False
+    quant_totals: dict[str, int] = {}
+    quant_first_file: dict[str, str] = {}
+
+    for sibling in info.siblings:
+        filename = getattr(sibling, "rfilename", None)
+        if not isinstance(filename, str) or not is_gguf_filename(filename):
+            continue
+        if is_mmproj_filename(filename):
+            has_vision = True
+            continue
+        quant = extract_quant_label(filename)
+        quant_totals[quant] = quant_totals.get(quant, 0) + int(getattr(sibling, "size", 0) or 0)
+        quant_first_file.setdefault(quant, filename)
+
+    for quant, total_size in quant_totals.items():
+        variants.append(
+            GgufVariantInfo(
+                filename = quant_first_file[quant],
+                quant = quant,
+                size_bytes = total_size,
+            )
+        )
+
+    variants.sort(key = lambda variant: -variant.size_bytes)
+    _apply_gguf_display_labels(variants)
+    return variants, has_vision, list(info.siblings)
+
+
+def _resolve_gguf_dir(path: Path) -> Optional[Path]:
+    if path.is_dir():
+        return path
+    if path.is_file() and path.suffix.lower() == ".gguf":
+        parent = path.parent
+        if (
+            (parent / "config.json").exists()
+            or (parent / "adapter_config.json").exists()
+            or (parent / "export_metadata.json").exists()
+        ):
+            return parent
+    return None
+
+
+def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], bool]:
+    root = _resolve_gguf_dir(Path(directory))
+    if root is None:
+        return [], False
+
+    quant_totals: dict[str, int] = {}
+    quant_first_file: dict[str, str] = {}
+    has_vision = False
+
+    for file in sorted(iter_gguf_files(root, recursive = True)):
+        if is_mmproj_filename(file.name):
+            has_vision = True
+            continue
+        try:
+            size = file.stat().st_size
+        except OSError:
+            size = 0
+        rel = file.relative_to(root).as_posix()
+        quant = extract_quant_label(rel)
+        quant_totals[quant] = quant_totals.get(quant, 0) + size
+        quant_first_file.setdefault(quant, rel)
+
+    variants = [
+        GgufVariantInfo(
+            filename = quant_first_file[quant],
+            quant = quant,
+            size_bytes = size,
+        )
+        for quant, size in quant_totals.items()
+    ]
+    variants.sort(key = lambda variant: -variant.size_bytes)
+    _apply_gguf_display_labels(variants)
+    return variants, has_vision
diff --git a/studio/backend/hub/utils/gguf_plan.py b/studio/backend/hub/utils/gguf_plan.py
new file mode 100644
index 0000000000..03ec847f4c
--- /dev/null
+++ b/studio/backend/hub/utils/gguf_plan.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from hub.utils.download_manifest import ExpectedFile
+from hub.utils.gguf import extract_quant_label, is_gguf_filename, is_mmproj_filename
+
+
+@dataclass(frozen = True)
+class GgufVariantPlan:
+    main_filenames: frozenset[str]
+    target_filenames: tuple[str, ...]
+    main_hashes: frozenset[str]
+    required_hashes: frozenset[str]
+    companion_hashes: frozenset[str]
+    mmproj_filenames: frozenset[str]
+    mmproj_hashes: frozenset[str]
+    expected_files: tuple[ExpectedFile, ...]
+    main_size_bytes: int
+    download_size_bytes: int
+
+
+def sibling_sha256(sibling) -> Optional[str]:
+    lfs = getattr(sibling, "lfs", None)
+    if isinstance(lfs, dict):
+        value = lfs.get("sha256")
+    else:
+        value = getattr(lfs, "sha256", None)
+    return value if isinstance(value, str) and value else None
+
+
+def sibling_size(sibling) -> int:
+    size = getattr(sibling, "size", 0) or 0
+    try:
+        return int(size)
+    except (TypeError, ValueError):
+        return 0
+
+
+def expected_file_from_sibling(sibling) -> Optional[ExpectedFile]:
+    name = getattr(sibling, "rfilename", None)
+    if not isinstance(name, str):
+        return None
+    return ExpectedFile(
+        path = name,
+        size = sibling_size(sibling),
+        sha256 = sibling_sha256(sibling),
+    )
+
+
+def is_companion_gguf_path(path: str) -> bool:
+    return is_gguf_filename(path) and is_mmproj_filename(path)
+
+
+def is_main_gguf_variant_path(path: str, variant: str) -> bool:
+    return (
+        is_gguf_filename(path)
+        and not is_mmproj_filename(path)
+        and extract_quant_label(path).lower() == variant.lower()
+    )
+
+
+def mmproj_siblings(siblings: Sequence) -> list:
+    return [
+        s
+        for s in siblings
+        if isinstance(getattr(s, "rfilename", None), str)
+        and is_companion_gguf_path(getattr(s, "rfilename"))
+    ]
+
+
+def preferred_mmproj_sibling(siblings: Sequence) -> Optional[object]:
+    candidates = mmproj_siblings(siblings)
+    if not candidates:
+        return None
+    return next(
+        (s for s in candidates if extract_quant_label(getattr(s, "rfilename")).upper() == "F16"),
+        candidates[0],
+    )
+
+
+def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
+    main: dict[str, list] = {}
+    all_mmproj = mmproj_siblings(siblings)
+    all_mmproj_filenames = frozenset(
+        getattr(s, "rfilename")
+        for s in all_mmproj
+        if isinstance(getattr(s, "rfilename", None), str)
+    )
+    all_mmproj_hashes = frozenset(h for h in (sibling_sha256(s) for s in all_mmproj) if h)
+    companion = preferred_mmproj_sibling(siblings)
+    companion_expected = expected_file_from_sibling(companion) if companion is not None else None
+
+    for sibling in siblings:
+        name = getattr(sibling, "rfilename", None)
+        if not isinstance(name, str) or not is_gguf_filename(name):
+            continue
+        if is_mmproj_filename(name):
+            continue
+        quant = extract_quant_label(name).lower()
+        main.setdefault(quant, []).append(sibling)
+
+    plans: dict[str, GgufVariantPlan] = {}
+    for quant, target_main_siblings in main.items():
+        main_expected = tuple(
+            file
+            for sibling in target_main_siblings
+            if (file := expected_file_from_sibling(sibling)) is not None
+        )
+        expected_files = (
+            (*main_expected, companion_expected)
+            if companion_expected is not None
+            else main_expected
+        )
+        plans[quant] = plan_from_expected_files(
+            quant,
+            expected_files,
+            all_mmproj_filenames = all_mmproj_filenames,
+            all_mmproj_hashes = all_mmproj_hashes,
+        )
+    return plans
+
+
+def plan_from_expected_files(
+    variant: str,
+    expected_files: Sequence[ExpectedFile],
+    *,
+    all_mmproj_filenames: frozenset[str] | None = None,
+    all_mmproj_hashes: frozenset[str] | None = None,
+) -> GgufVariantPlan:
+    expected = tuple(expected_files)
+    main_files = tuple(file for file in expected if is_main_gguf_variant_path(file.path, variant))
+    companion_files = tuple(file for file in expected if is_companion_gguf_path(file.path))
+    main_hashes = frozenset(file.sha256 for file in main_files if file.sha256)
+    companion_hashes = frozenset(file.sha256 for file in companion_files if file.sha256)
+    required_hashes = frozenset(file.sha256 for file in expected if file.sha256)
+    main_size = sum(max(0, int(file.size or 0)) for file in main_files)
+    download_size = sum(max(0, int(file.size or 0)) for file in expected)
+    return GgufVariantPlan(
+        main_filenames = frozenset(file.path for file in main_files),
+        target_filenames = tuple(file.path for file in expected),
+        main_hashes = main_hashes,
+        required_hashes = required_hashes,
+        companion_hashes = companion_hashes,
+        mmproj_filenames = (
+            all_mmproj_filenames
+            if all_mmproj_filenames is not None
+            else frozenset(file.path for file in companion_files)
+        ),
+        mmproj_hashes = (all_mmproj_hashes if all_mmproj_hashes is not None else companion_hashes),
+        expected_files = expected,
+        main_size_bytes = main_size,
+        download_size_bytes = download_size,
+    )
diff --git a/studio/backend/hub/utils/hf_cache_state.py b/studio/backend/hub/utils/hf_cache_state.py
new file mode 100644
index 0000000000..a1ac372abb
--- /dev/null
+++ b/studio/backend/hub/utils/hf_cache_state.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import errno
+import shutil
+import sys
+from pathlib import Path
+from typing import Iterable, Iterator, Optional
+
+
+EXIT_CANCELLED = 130
+
+TRANSPORT_HTTP = "http"
+TRANSPORT_XET = "xet"
+VALID_TRANSPORTS = frozenset({TRANSPORT_HTTP, TRANSPORT_XET})
+TRANSPORT_MARKER_NAME = ".transport"
+INCOMPLETE_SUFFIX = ".incomplete"
+
+
+def hf_cache_root(*, create: bool = False) -> Optional[Path]:
+    try:
+        from huggingface_hub import constants as hf_constants
+    except ImportError:
+        return None
+    root = Path(hf_constants.HF_HUB_CACHE)
+    if create:
+        try:
+            root.mkdir(parents = True, exist_ok = True)
+        except OSError:
+            return None
+        return root
+    return root if root.is_dir() else None
+
+
+def hf_cache_roots() -> list[Path]:
+    from hub.utils.paths import hf_default_cache_dir, legacy_hf_cache_dir
+
+    roots: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(path: Optional[Path]) -> None:
+        if path is None or not path.is_dir():
+            return
+        try:
+            key = str(path.resolve())
+        except OSError:
+            return
+        if key in seen:
+            return
+        seen.add(key)
+        roots.append(path)
+
+    _add(hf_cache_root())
+    _add(legacy_hf_cache_dir())
+    _add(hf_default_cache_dir())
+    return roots
+
+
+def target_dir_name(repo_type: str, repo_id: str) -> str:
+    return repo_cache_dir_name(repo_type, repo_id).lower()
+
+
+def repo_cache_dir_name(repo_type: str, repo_id: str) -> str:
+    return f"{repo_type}s--{repo_id.replace('/', '--')}"
+
+
+def resolve_destructive_case_matches(target: str, candidates: Iterable[str]) -> Optional[set[str]]:
+    values = list(candidates)
+    exact = {candidate for candidate in values if candidate == target}
+    if exact:
+        return exact
+    folded = {candidate for candidate in values if candidate.lower() == target.lower()}
+    if len(folded) <= 1:
+        return folded
+    return None
+
+
+def _blob_dir_is_partial(blobs_dir: Path) -> bool:
+    try:
+        for blob in blobs_dir.iterdir():
+            if blob.is_file() and blob.name.endswith(INCOMPLETE_SUFFIX):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def blob_bytes_present(path: Path) -> int:
+    """Sparse-aware on-disk size: XET/``hf_transfer`` ``.incomplete`` partials
+    report a full ``st_size`` while only some blocks are allocated, so prefer
+    ``st_blocks``, falling back to ``st_size`` where it is unreported (Windows,
+    some network filesystems)."""
+    st = path.stat()
+    blocks = getattr(st, "st_blocks", 0)
+    if blocks > 0:
+        return min(blocks * 512, st.st_size)
+    if sys.platform == "win32":
+        allocated = _windows_allocated_size(path)
+        if allocated is not None:
+            return min(allocated, st.st_size)
+    return st.st_size
+
+
+def _windows_allocated_size(path: Path) -> Optional[int]:
+    """Best-effort allocated-byte count for sparse files on Windows."""
+    if sys.platform != "win32":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error = True)
+        get_compressed_file_size = kernel32.GetCompressedFileSizeW
+        get_compressed_file_size.argtypes = [
+            wintypes.LPCWSTR,
+            ctypes.POINTER(wintypes.DWORD),
+        ]
+        get_compressed_file_size.restype = wintypes.DWORD
+
+        high = wintypes.DWORD(0)
+        ctypes.set_last_error(0)
+        low = get_compressed_file_size(str(path), ctypes.byref(high))
+        if low == 0xFFFFFFFF and ctypes.get_last_error() != 0:
+            return None
+        return (int(high.value) << 32) + int(low)
+    except Exception:
+        return None
+
+
+def latest_snapshot_dir(repo_dir: Path) -> Optional[Path]:
+    """Newest immediate child of ``repo_dir/snapshots`` by mtime, or None.
+
+    mtime is the signal huggingface_hub's from_pretrained resolves to, so this
+    points at whatever snapshot most recently landed on disk.
+    """
+    snapshots_dir = repo_dir / "snapshots"
+    try:
+        if not snapshots_dir.is_dir():
+            return None
+        snapshots = [entry for entry in snapshots_dir.iterdir() if entry.is_dir()]
+        if not snapshots:
+            return None
+        return max(snapshots, key = lambda entry: entry.stat().st_mtime)
+    except OSError:
+        return None
+
+
+def _repo_dir_has_broken_snapshot_symlinks(repo_dir: Path) -> bool:
+    latest = latest_snapshot_dir(repo_dir)
+    if latest is None:
+        return False
+    try:
+        for entry in latest.rglob("*"):
+            if entry.is_symlink() and not entry.exists():
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def iter_repo_cache_dirs(repo_type: str, repo_id: str) -> Iterator[Path]:
+    target = target_dir_name(repo_type, repo_id)
+    for root in hf_cache_roots():
+        try:
+            for entry in root.iterdir():
+                if entry.name.lower() == target:
+                    yield entry
+        except OSError:
+            continue
+
+
+def iter_destructive_repo_cache_dirs(repo_type: str, repo_id: str) -> Iterator[Path]:
+    target = repo_cache_dir_name(repo_type, repo_id)
+    folded_target = target.lower()
+    for root in hf_cache_roots():
+        try:
+            entries = [entry for entry in root.iterdir() if entry.name.lower() == folded_target]
+        except OSError:
+            continue
+        matched_names = resolve_destructive_case_matches(
+            target,
+            (entry.name for entry in entries),
+        )
+        if not matched_names:
+            continue
+        for entry in entries:
+            if entry.name in matched_names:
+                yield entry
+
+
+def iter_active_repo_cache_dirs(repo_type: str, repo_id: str) -> Iterator[Path]:
+    root = hf_cache_root()
+    if root is None:
+        return
+    target = target_dir_name(repo_type, repo_id)
+    try:
+        for entry in root.iterdir():
+            if entry.name.lower() == target:
+                yield entry
+    except OSError:
+        return
+
+
+def preferred_repo_cache_dirs(
+    repo_type: str,
+    repo_id: str,
+    *,
+    force_active: bool = False,
+) -> list[Path]:
+    active_entries = list(iter_active_repo_cache_dirs(repo_type, repo_id))
+    if active_entries:
+        return active_entries
+    if force_active:
+        root = hf_cache_root()
+        if root is not None:
+            canonical = repo_cache_dir_name(repo_type, repo_id)
+            return [root / canonical]
+    return list(iter_repo_cache_dirs(repo_type, repo_id))
+
+
+def has_incomplete_blobs(repo_type: str, repo_id: str) -> bool:
+    for entry in iter_repo_cache_dirs(repo_type, repo_id):
+        if repo_cache_dir_has_incomplete_blobs(entry):
+            return True
+    return False
+
+
+def has_active_incomplete_blobs(repo_type: str, repo_id: str) -> bool:
+    for entry in iter_active_repo_cache_dirs(repo_type, repo_id):
+        if repo_cache_dir_has_incomplete_blobs(entry):
+            return True
+    return False
+
+
+def repo_cache_dir_has_incomplete_blobs(repo_dir: Path) -> bool:
+    blobs_dir = repo_dir / "blobs"
+    return (blobs_dir.is_dir() and _blob_dir_is_partial(blobs_dir)) or (
+        _repo_dir_has_broken_snapshot_symlinks(repo_dir)
+    )
+
+
+def _prune_empty_dirs(root: Path) -> bool:
+    removed = False
+    try:
+        dirs = sorted(
+            (path for path in root.rglob("*") if path.is_dir()),
+            key = lambda path: len(path.parts),
+            reverse = True,
+        )
+    except OSError:
+        dirs = []
+    for directory in [*dirs, root]:
+        try:
+            directory.rmdir()
+            removed = True
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            if exc.errno not in (errno.ENOTEMPTY, errno.EEXIST):
+                raise
+    return removed
+
+
+def purge_partial_repo(repo_type: str, repo_id: str) -> bool:
+    removed = False
+    for entry in iter_destructive_repo_cache_dirs(repo_type, repo_id):
+        blobs_dir = entry / "blobs"
+        if blobs_dir.is_dir():
+            for blob in blobs_dir.iterdir():
+                if blob.is_file() and blob.name.endswith(INCOMPLETE_SUFFIX):
+                    try:
+                        blob.unlink()
+                        removed = True
+                    except FileNotFoundError:
+                        continue
+        if _prune_empty_dirs(entry):
+            removed = True
+    return removed
+
+
+def purge_repo_cache_dirs(repo_type: str, repo_id: str) -> bool:
+    removed = False
+    for entry in iter_destructive_repo_cache_dirs(repo_type, repo_id):
+        try:
+            if entry.is_symlink() or not entry.is_dir():
+                continue
+            shutil.rmtree(entry)
+            removed = True
+        except FileNotFoundError:
+            continue
+    return removed
diff --git a/studio/backend/hub/utils/hf_errors.py b/studio/backend/hub/utils/hf_errors.py
new file mode 100644
index 0000000000..b2569758c6
--- /dev/null
+++ b/studio/backend/hub/utils/hf_errors.py
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Map Hugging Face Hub client-side errors to HTTP status codes."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def hf_error_status(exc: Exception) -> Optional[int]:
+    # Client-side HF errors should surface as 4xx, not a generic 500.
+    name = type(exc).__name__
+    if name in (
+        "RepositoryNotFoundError",
+        "RevisionNotFoundError",
+        "EntryNotFoundError",
+    ):
+        return 404
+    if name == "GatedRepoError":
+        return 403
+    if name == "HFValidationError":
+        return 400
+    # HfHubHTTPError subclasses carry the upstream response status.
+    code = getattr(getattr(exc, "response", None), "status_code", None)
+    if isinstance(code, int) and 400 <= code < 500:
+        return code
+    return None
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
new file mode 100644
index 0000000000..a7281ad8b3
--- /dev/null
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -0,0 +1,533 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""HF cache inventory scanner.
+
+Read-only walks of the HuggingFace hub cache plus legacy/default
+cache locations. Builds the foundation that Hub inventory endpoints
+and the DownloadRegistry both consume.
+
+The worker spawn / transport-marker preparation / DownloadRegistry
+layers built on top of these primitives live in download_registry.py.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+from hub.utils.gguf import extract_quant_label, is_gguf_filename, is_mmproj_filename
+from hub.utils.state_dir import RepoType
+
+from hub.utils.hf_cache_state import (
+    INCOMPLETE_SUFFIX,
+    has_incomplete_blobs,
+    hf_cache_root,
+    iter_repo_cache_dirs,
+    latest_snapshot_dir,
+    repo_cache_dir_has_incomplete_blobs,
+)
+
+# Inventory is invalidated explicitly on every app-driven cache mutation, so
+# this TTL only bounds staleness from out-of-band edits while skipping re-walks
+# on rapid UI navigation.
+_HF_CACHE_SCANS_TTL_SECONDS = 15.0
+_GGUF_SPLIT_RE = re.compile(r"-(\d{3,})-of-(\d{3,})(?=\.gguf$)", re.IGNORECASE)
+_hf_cache_scans_lock = threading.Lock()
+
+
+@dataclass
+class _HfCacheScanFlight:
+    event: threading.Event
+    epoch: int
+    result: Optional[list] = None
+    error: Optional[BaseException] = None
+
+
+_hf_cache_scans_flight: Optional[_HfCacheScanFlight] = None
+_hf_cache_scans_result: Optional[list] = None
+_hf_cache_scans_cached_at: float = 0.0
+# Bumped on every invalidation. A scan tags itself with the epoch it began
+# under; an invalidation mid-scan changes the epoch so the in-flight result is
+# neither cached nor served to callers that arrived after the mutation.
+_hf_cache_scans_epoch: int = 0
+
+
+def invalidate_hf_cache_scans() -> None:
+    global _hf_cache_scans_result, _hf_cache_scans_cached_at, _hf_cache_scans_epoch
+    with _hf_cache_scans_lock:
+        _hf_cache_scans_result = None
+        _hf_cache_scans_cached_at = 0.0
+        _hf_cache_scans_epoch += 1
+
+
+def all_hf_cache_scans() -> list:
+    global _hf_cache_scans_flight, _hf_cache_scans_result, _hf_cache_scans_cached_at
+
+    now = time.monotonic()
+    with _hf_cache_scans_lock:
+        if (
+            _hf_cache_scans_result is not None
+            and (now - _hf_cache_scans_cached_at) < _HF_CACHE_SCANS_TTL_SECONDS
+        ):
+            return list(_hf_cache_scans_result)
+        start_epoch = _hf_cache_scans_epoch
+        flight = _hf_cache_scans_flight
+        # Only coalesce onto an in-flight scan from the current epoch; one that
+        # began before an intervening invalidation is superseded so
+        # post-mutation callers never receive pre-mutation data.
+        if flight is None or flight.epoch != start_epoch:
+            flight = _HfCacheScanFlight(event = threading.Event(), epoch = start_epoch)
+            _hf_cache_scans_flight = flight
+            owner = True
+        else:
+            owner = False
+
+    if not owner:
+        flight.event.wait()
+        if flight.error is not None:
+            raise flight.error
+        return list(flight.result or [])
+
+    try:
+        scans = _compute_all_hf_cache_scans()
+        with _hf_cache_scans_lock:
+            flight.result = scans
+            if _hf_cache_scans_epoch == flight.epoch:
+                _hf_cache_scans_result = scans
+                _hf_cache_scans_cached_at = time.monotonic()
+        return scans
+    except Exception as exc:
+        with _hf_cache_scans_lock:
+            if _hf_cache_scans_epoch == flight.epoch:
+                _hf_cache_scans_result = None
+                _hf_cache_scans_cached_at = 0.0
+            flight.error = exc
+        raise
+    finally:
+        with _hf_cache_scans_lock:
+            if _hf_cache_scans_flight is flight:
+                _hf_cache_scans_flight = None
+            flight.event.set()
+
+
+def _compute_all_hf_cache_scans() -> list:
+    from huggingface_hub import scan_cache_dir
+    from hub.utils.paths import legacy_hf_cache_dir, hf_default_cache_dir
+
+    scans: list = []
+    seen: set[str] = set()
+    try:
+        from huggingface_hub.constants import HF_HUB_CACHE
+
+        active = Path(HF_HUB_CACHE).resolve()
+        seen.add(str(active))
+        if active.is_dir():
+            scans.append(scan_cache_dir())
+    except Exception as exc:
+        logger.warning("Could not scan active HF cache: %s", exc)
+
+    for extra_fn in (legacy_hf_cache_dir, hf_default_cache_dir):
+        extra = extra_fn()
+        if extra.is_dir() and str(extra.resolve()) not in seen:
+            seen.add(str(extra.resolve()))
+            try:
+                scans.append(scan_cache_dir(cache_dir = str(extra)))
+            except Exception as exc:
+                logger.warning("Could not scan HF cache %s: %s", extra, exc)
+    return scans
+
+
+def token_fingerprint(hf_token: Optional[str]) -> str:
+    """16-char SHA256 prefix used as a cache-key qualifier for gated repos.
+
+    Lets per-token size/snapshot caches refuse to serve a previously
+    fetched value back to a different token (a private/gated repo's
+    metadata is only valid for the credential that fetched it).
+    """
+    if not hf_token:
+        return ""
+    return hashlib.sha256(hf_token.encode()).hexdigest()[:16]
+
+
+def resolve_hf_cache_realpath(repo_dir: Path) -> Optional[str]:
+    """Pick the most useful on-disk path for a HF cache repo dir.
+
+    Prefers the most-recent snapshot dir (what ``from_pretrained``
+    actually points at). Falls back to the cache repo root. Returns the
+    resolved realpath so symlinks under ``snapshots/`` are followed back
+    to ``blobs/``.
+    """
+    try:
+        latest = latest_snapshot_dir(repo_dir)
+        if latest is not None:
+            return str(latest.resolve())
+        return str(repo_dir.resolve())
+    except Exception:
+        return None
+
+
+def resolve_snapshot_dir_for_scan(
+    repo_type: str,
+    repo_id: str,
+    repo_cache_dir: Optional[Path] = None,
+) -> Optional[Path]:
+    """Latest snapshot dir for a cache row, or the first populated HF cache root.
+
+    Scanner-side counterpart to snapshot_download()'s return value (which the
+    scanner cannot access). With a *repo_cache_dir*, returns its newest
+    snapshot. Otherwise scans roots in priority order (active, legacy, default)
+    and returns the newest snapshot in the first root that holds one; active is
+    where snapshot_download writes, so it is authoritative. Within a root,
+    picks by mtime (what from_pretrained resolves to) rather than refs/main,
+    since the user may have downloaded a non-main commit.
+    """
+    if repo_cache_dir is not None:
+        latest = latest_snapshot_dir(repo_cache_dir)
+        if latest is None:
+            return None
+        try:
+            return latest.resolve()
+        except OSError:
+            return None
+    for repo_dir in iter_repo_cache_dirs(repo_type, repo_id):
+        latest = latest_snapshot_dir(repo_dir)
+        if latest is None:
+            continue
+        try:
+            return latest.resolve()
+        except OSError:
+            continue
+    return None
+
+
+def _compose_partial(*signals: Callable[[], bool]) -> bool:
+    return any(signal() for signal in signals)
+
+
+def _state_applies_to_repo_cache_dir(repo_cache_dir: Optional[Path]) -> bool:
+    if repo_cache_dir is None:
+        return True
+    root = hf_cache_root()
+    if root is None:
+        return False
+    try:
+        return repo_cache_dir.resolve().parent == root.resolve()
+    except OSError:
+        return False
+
+
+def _legacy_partial(
+    repo_type: str,
+    repo_id: str,
+    repo_cache_dir: Optional[Path] = None,
+) -> bool:
+    if repo_cache_dir is not None:
+        return repo_cache_dir_has_incomplete_blobs(repo_cache_dir)
+    return has_incomplete_blobs(repo_type, repo_id)
+
+
+def _repo_cache_dir_incomplete_hashes(repo_cache_dir: Path) -> set[str]:
+    blobs_dir = repo_cache_dir / "blobs"
+    if not blobs_dir.is_dir():
+        return set()
+    hashes: set[str] = set()
+    try:
+        entries = list(blobs_dir.iterdir())
+    except OSError:
+        return hashes
+    for blob in entries:
+        try:
+            if blob.is_file() and blob.name.endswith(INCOMPLETE_SUFFIX):
+                hashes.add(blob.name[: -len(INCOMPLETE_SUFFIX)])
+        except OSError:
+            continue
+    return hashes
+
+
+def _repo_cache_dir_has_non_gguf_broken_snapshot_symlinks(repo_cache_dir: Path) -> bool:
+    latest = latest_snapshot_dir(repo_cache_dir)
+    if latest is None:
+        return False
+    try:
+        entries = list(latest.rglob("*"))
+    except OSError:
+        return False
+    for entry in entries:
+        try:
+            if not entry.is_symlink() or entry.exists():
+                continue
+            rel = entry.relative_to(latest).as_posix()
+            if is_gguf_filename(rel):
+                continue
+            return True
+        except OSError:
+            continue
+    return False
+
+
+def _gguf_variant_manifest_blob_hashes(repo_id: str) -> frozenset[str]:
+    from hub.utils import download_manifest
+
+    hashes: set[str] = set()
+    for variant, _path in download_manifest.iter_variant_manifests("model", repo_id):
+        manifest = download_manifest.read_manifest("model", repo_id, variant)
+        if manifest is None:
+            continue
+        for expected in manifest.expected_files:
+            if expected.sha256 and is_gguf_filename(expected.path):
+                hashes.add(expected.sha256)
+    return frozenset(hashes)
+
+
+def _repo_cache_dir_has_snapshot_legacy_partial(
+    repo_cache_dir: Path, *, ignored_blob_hashes: frozenset[str]
+) -> bool:
+    incomplete_hashes = _repo_cache_dir_incomplete_hashes(repo_cache_dir)
+    if any(blob_hash not in ignored_blob_hashes for blob_hash in incomplete_hashes):
+        return True
+    return _repo_cache_dir_has_non_gguf_broken_snapshot_symlinks(repo_cache_dir)
+
+
+def _snapshot_legacy_partial(
+    repo_type: str,
+    repo_id: str,
+    repo_cache_dir: Optional[Path] = None,
+) -> bool:
+    if repo_type != "model":
+        return _legacy_partial(repo_type, repo_id, repo_cache_dir)
+    ignored_hashes = _gguf_variant_manifest_blob_hashes(repo_id)
+    if repo_cache_dir is not None:
+        return _repo_cache_dir_has_snapshot_legacy_partial(
+            repo_cache_dir,
+            ignored_blob_hashes = ignored_hashes,
+        )
+    return any(
+        _repo_cache_dir_has_snapshot_legacy_partial(
+            entry,
+            ignored_blob_hashes = ignored_hashes,
+        )
+        for entry in iter_repo_cache_dirs(repo_type, repo_id)
+    )
+
+
+def _completed_gguf_variants(snapshot_dir: Optional[Path]) -> set[str]:
+    if snapshot_dir is None:
+        return set()
+    complete: set[str] = set()
+    split_groups: dict[str, dict[int, set[int]]] = {}
+    try:
+        paths = list(snapshot_dir.rglob("*"))
+    except OSError:
+        return set()
+    for path in paths:
+        try:
+            if not path.is_file() or path.stat().st_size <= 0:
+                continue
+        except OSError:
+            continue
+        rel = path.relative_to(snapshot_dir).as_posix()
+        if not is_gguf_filename(rel) or is_mmproj_filename(rel):
+            continue
+        quant = extract_quant_label(rel)
+        split = _GGUF_SPLIT_RE.search(path.name)
+        if split is None:
+            complete.add(quant)
+            continue
+        index = int(split.group(1))
+        total = int(split.group(2))
+        if index <= 0 or total <= 0 or index > total:
+            continue
+        split_groups.setdefault(quant, {}).setdefault(total, set()).add(index)
+    for quant, groups in split_groups.items():
+        for total, indices in groups.items():
+            if indices == set(range(1, total + 1)):
+                complete.add(quant)
+                break
+    return complete
+
+
+def _manifest_partial(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+    snapshot_dir: Optional[Path] = None,
+    repo_cache_dir: Optional[Path] = None,
+) -> bool:
+    from hub.utils import download_manifest
+
+    if not _state_applies_to_repo_cache_dir(repo_cache_dir):
+        return False
+    manifest = download_manifest.read_manifest(repo_type, repo_id, variant)
+    if manifest is None:
+        return False
+    resolved = (
+        snapshot_dir
+        if snapshot_dir is not None
+        else resolve_snapshot_dir_for_scan(repo_type, repo_id, repo_cache_dir)
+    )
+    if resolved is None:
+        return True
+    return not download_manifest.verify_against_disk(manifest, resolved).ok
+
+
+def is_snapshot_partial(
+    repo_type: RepoType,
+    repo_id: str,
+    repo_cache_dir: Optional[Path] = None,
+) -> bool:
+    """Repo-row partial flag for snapshot-style downloads (full-snapshot
+    models — safetensors/adapter/checkpoint — and all datasets).
+
+    Composes three signals, cheapest first:
+      1. Cancel marker (single stat).
+      2. Snapshot-attributed legacy .incomplete blob / broken-symlink check.
+      3. Manifest walk (stat per expected file under the latest snapshot).
+
+    A manifest without a resolvable snapshot is partial: the worker got
+    far enough to record expectations but did not leave a usable snapshot."""
+    from hub.utils import download_manifest
+
+    state_applies = _state_applies_to_repo_cache_dir(repo_cache_dir)
+    return _compose_partial(
+        lambda: state_applies and download_manifest.has_cancel_marker(repo_type, repo_id, None),
+        lambda: _snapshot_legacy_partial(repo_type, repo_id, repo_cache_dir),
+        lambda: _manifest_partial(
+            repo_type,
+            repo_id,
+            None,
+            None,
+            repo_cache_dir,
+        ),
+    )
+
+
+def is_variant_partial(
+    repo_id: str,
+    variant: str,
+    snapshot_dir: Optional[Path] = None,
+    *,
+    incomplete_blob_hashes: Optional[set[str]] = None,
+    variant_blob_hashes: Optional[frozenset[str]] = None,
+    repo_cache_dir: Optional[Path] = None,
+) -> bool:
+    """Per-variant partial detection. Owns its manifest, owns its marker.
+    Used by the GGUF variants endpoint to flag a specific quant as broken
+    without contaminating other quants in the same repo.
+
+    snapshot_dir is an optional hint to avoid re-walking the cache when a
+    caller is checking many variants of the same repo (see
+    is_gguf_repo_partial for that usage)."""
+    from hub.utils import download_manifest
+
+    state_applies = _state_applies_to_repo_cache_dir(repo_cache_dir)
+    return _compose_partial(
+        lambda: state_applies and download_manifest.has_cancel_marker("model", repo_id, variant),
+        lambda: bool(
+            incomplete_blob_hashes
+            and variant_blob_hashes
+            and incomplete_blob_hashes.intersection(variant_blob_hashes)
+        ),
+        lambda: _manifest_partial(
+            "model",
+            repo_id,
+            variant,
+            snapshot_dir,
+            repo_cache_dir,
+        ),
+    )
+
+
+def is_gguf_repo_partial(repo_id: str, repo_cache_dir: Optional[Path] = None) -> bool:
+    """Repo-row partial flag for a GGUF repo. The inventory shows ONE row per
+    GGUF repo (requires_variant=True); per-variant detail lives in
+    GET /api/models/gguf-variants and uses is_variant_partial.
+
+    *** DO NOT simplify this to "any variant partial -> repo partial" ***
+
+    Tripwire scenario: user downloads Q8_0 fully, then starts Q4_K_M and
+    cancels. Both variants share ONE inventory row. If row.partial flips True,
+    _capabilities_for_format flips can_chat=False, so the user can no longer
+    chat with the perfectly-good Q8_0 because of an unrelated cancelled Q4_K_M.
+
+    Correct semantics: partial=True only when at least one variant is broken
+    AND no other variant is clean. "Simplifying" to the obvious "any broken"
+    form re-introduces this Q8+Q4 mixed-state regression.
+
+    Composes signals:
+      1. Cheap legacy fast-path (.incomplete blobs / broken symlinks).
+      2. Per-variant manifest + marker enumeration, gated on "all broken".
+    """
+    from hub.utils import download_manifest
+
+    has_legacy_partial = _legacy_partial("model", repo_id, repo_cache_dir)
+    state_applies = _state_applies_to_repo_cache_dir(repo_cache_dir)
+    snapshot_dir = resolve_snapshot_dir_for_scan(
+        "model",
+        repo_id,
+        repo_cache_dir,
+    )
+    variants: set[str] = set(_completed_gguf_variants(snapshot_dir))
+    if state_applies:
+        for variant, _path in download_manifest.iter_variant_manifests(
+            "model",
+            repo_id,
+        ):
+            variants.add(variant)
+        for variant, _path in download_manifest.iter_variant_markers(
+            "model",
+            repo_id,
+        ):
+            variants.add(variant)
+    if not variants:
+        return has_legacy_partial
+    has_clean = False
+    has_broken = has_legacy_partial
+    for variant in variants:
+        if is_variant_partial(
+            repo_id,
+            variant,
+            snapshot_dir,
+            repo_cache_dir = repo_cache_dir,
+        ):
+            has_broken = True
+        else:
+            has_clean = True
+    return has_broken and not has_clean
+
+
+def partial_transport_for(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+    repo_cache_dir: Optional[Path] = None,
+) -> Optional[str]:
+    """Transport to surface on a partial row's resume affordance.
+
+    Prefers the cancel marker's transport, then the manifest's. The fallback
+    matters for rows partial without a marker (an errored/interrupted download
+    leaves the manifest but no marker) so the UI can still show HTTP-resume vs
+    XET-redownload instead of the neutral retry label. ``None`` when neither is
+    available."""
+    from hub.utils import download_manifest
+
+    if not _state_applies_to_repo_cache_dir(repo_cache_dir):
+        return None
+    marker_transport = download_manifest.read_cancel_marker_transport(
+        repo_type,
+        repo_id,
+        variant,
+    )
+    if marker_transport is not None:
+        return marker_transport
+    manifest = download_manifest.read_manifest(repo_type, repo_id, variant)
+    return manifest.transport if manifest is not None else None
diff --git a/studio/backend/hub/utils/llm_assist.py b/studio/backend/hub/utils/llm_assist.py
new file mode 100644
index 0000000000..00edb204c5
--- /dev/null
+++ b/studio/backend/hub/utils/llm_assist.py
@@ -0,0 +1,440 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import textwrap
+import time
+from typing import Any, Optional
+
+from loggers import get_logger
+
+from hub.utils import download_registry
+
+logger = get_logger(__name__)
+
+DEFAULT_HELPER_MODEL_REPO = "unsloth/gemma-4-E2B-it-GGUF"
+DEFAULT_HELPER_MODEL_VARIANT = "UD-Q4_K_XL"
+README_MAX_CHARS = 1500
+
+
+def _helper_disabled() -> bool:
+    return os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip().lower() in {
+        "1",
+        "true",
+    }
+
+
+def _strip_think_tags(text: str) -> str:
+    if "<think>" not in text:
+        return text
+    stripped = re.sub(r"<think>.*?</think>\s*", "", text, flags = re.DOTALL).strip()
+    if stripped:
+        return stripped
+    matches = re.findall(r"<think>(.*?)</think>", text, flags = re.DOTALL)
+    return matches[-1].strip() if matches else text
+
+
+def _parse_json_response(text: str) -> Optional[dict[str, Any]]:
+    cleaned = (text or "").strip()
+    if not cleaned:
+        return None
+    if cleaned.startswith("```"):
+        lines = cleaned.splitlines()
+        end = -1 if lines and lines[-1].strip().startswith("```") else len(lines)
+        cleaned = "\n".join(lines[1:end]).strip()
+    try:
+        parsed = json.loads(cleaned)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r"\{.*\}", cleaned, re.DOTALL)
+    if not match:
+        return None
+    try:
+        parsed = json.loads(match.group())
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _generate_with_backend(backend, messages: list[dict[str, str]], max_tokens: int) -> str:
+    cumulative = ""
+    for chunk in backend.generate_chat_completion(
+        messages = messages,
+        temperature = 0.1,
+        top_p = 0.9,
+        top_k = 20,
+        max_tokens = max_tokens,
+        repetition_penalty = 1.0,
+        enable_thinking = False,
+    ):
+        if isinstance(chunk, dict):
+            continue
+        cumulative = chunk
+    return _strip_think_tags(cumulative.strip())
+
+
+def _fetch_hf_dataset_card(
+    dataset_name: str, hf_token: Optional[str]
+) -> tuple[Optional[str], Optional[dict[str, Any]]]:
+    try:
+        from huggingface_hub import DatasetCard
+
+        card = DatasetCard.load(dataset_name, token = hf_token)
+        readme = card.text or ""
+        if len(readme) > README_MAX_CHARS:
+            cut = readme[:README_MAX_CHARS].rfind(".")
+            if cut > README_MAX_CHARS // 2:
+                readme = readme[: cut + 1] + "\n[...truncated]"
+            else:
+                readme = readme[:README_MAX_CHARS] + "\n[...truncated]"
+        metadata: dict[str, Any] = {}
+        if card.data:
+            for key in (
+                "task_categories",
+                "task_ids",
+                "language",
+                "size_categories",
+                "tags",
+                "license",
+                "pretty_name",
+            ):
+                value = getattr(card.data, key, None)
+                if value is not None:
+                    metadata[key] = value
+        return readme, metadata
+    except Exception as exc:
+        logger.warning(
+            "Could not fetch dataset card for %s: %s",
+            dataset_name,
+            download_registry.scrub_secrets(str(exc), hf_token = hf_token),
+        )
+        return None, None
+
+
+def _is_gemma_3n(model_name: Optional[str]) -> bool:
+    normalized = (model_name or "").lower().replace("_", "-")
+    return "gemma-3n" in normalized or "gemma3n" in normalized
+
+
+def _sample_text(columns: list[str], samples: list[dict[str, Any]]) -> str:
+    rows: list[str] = []
+    for index, row in enumerate(samples[:5], 1):
+        parts = [f"  {col}: {str(row.get(col, ''))[:200]}" for col in columns]
+        rows.append(f"Row {index}:\n" + "\n".join(parts))
+    return "\n".join(rows)
+
+
+def _target_hints(model_name: Optional[str], model_type: Optional[str]) -> str:
+    if model_type == "audio" and not _is_gemma_3n(model_name):
+        return (
+            "\n\nHINT: The user is training an AUDIO model. The dataset must contain "
+            "a column with audio files or paths and one such column should be selected "
+            "as part of the input."
+        )
+    if model_type == "embeddings":
+        return (
+            "\n\nHINT: The user is training an EMBEDDING model. Prefer dataset formats "
+            "such as text pairs for STS, premise/hypothesis/label for NLI, or query "
+            "and document columns for retrieval."
+        )
+    return ""
+
+
+def _run_multi_pass_advisor(
+    *,
+    columns: list[str],
+    samples: list[dict[str, Any]],
+    dataset_name: Optional[str],
+    dataset_card: Optional[str],
+    dataset_metadata: Optional[dict[str, Any]],
+    model_name: Optional[str],
+    model_type: Optional[str],
+) -> Optional[dict[str, Any]]:
+    if _helper_disabled():
+        return None
+
+    repo = os.environ.get("UNSLOTH_HELPER_MODEL_REPO", DEFAULT_HELPER_MODEL_REPO)
+    variant = os.environ.get("UNSLOTH_HELPER_MODEL_VARIANT", DEFAULT_HELPER_MODEL_VARIANT)
+    backend = None
+    try:
+        from core.inference.llama_cpp import LlamaCppBackend
+
+        backend = LlamaCppBackend()
+        started = time.monotonic()
+        if not backend.load_model(
+            hf_repo = repo,
+            hf_variant = variant,
+            model_identifier = f"hub-advisor:{repo}:{variant}",
+            is_vision = False,
+            n_ctx = 2048,
+            n_gpu_layers = -1,
+        ):
+            return None
+        logger.info("Hub advisor model loaded in %.1fs", time.monotonic() - started)
+
+        samples_text = _sample_text(columns, samples)
+        metadata_text = (
+            json.dumps(dataset_metadata, indent = 2, default = str)[:500] if dataset_metadata else "N/A"
+        )
+        card_excerpt = (dataset_card or "")[:1200] or "N/A"
+        hints = _target_hints(model_name, model_type)
+
+        pass1_raw = _generate_with_backend(
+            backend,
+            [
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a dataset analyst. Classify the dataset and respond "
+                        "with only a valid JSON object."
+                        f"{hints}"
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": textwrap.dedent(f"""\
+                        Dataset: {dataset_name or "unknown"}
+
+                        DATASET CARD:
+                        {card_excerpt}
+
+                        METADATA:
+                        {metadata_text}
+
+                        COLUMNS: {columns}
+
+                        SAMPLE DATA:
+                        {samples_text}
+
+                        Return this JSON shape:
+                        {{
+                          "dataset_type": "<summarization|question_answering|translation|classification|natural_language_inference|instruction_following|conversational|code_generation|other>",
+                          "is_conversational": <boolean>,
+                          "needs_conversion": <boolean>,
+                          "description": "<one sentence>",
+                          "task_description": "<one sentence>"
+                        }}"""),
+                },
+            ],
+            256,
+        )
+        pass1 = _parse_json_response(pass1_raw)
+        if not pass1:
+            return None
+
+        if pass1.get("is_conversational") and not pass1.get("needs_conversion"):
+            return {
+                "success": True,
+                "dataset_type": pass1.get("dataset_type"),
+                "is_conversational": True,
+                "user_notification": (
+                    "This dataset is already in conversational format. No conversion is needed."
+                ),
+            }
+
+        pass2_raw = _generate_with_backend(
+            backend,
+            [
+                {
+                    "role": "system",
+                    "content": (
+                        "Assign each dataset column to user, assistant, or skip for "
+                        "LLM fine-tuning. The target/output/answer/label column must be "
+                        "assistant. Return only valid JSON."
+                        f"{hints}"
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": textwrap.dedent(f"""\
+                        CLASSIFICATION:
+                        {json.dumps(pass1, indent = 2)}
+
+                        COLUMNS: {columns}
+
+                        SAMPLE DATA:
+                        {samples_text}
+
+                        Return this JSON shape:
+                        {{
+                          "column_roles": {{"<column_name>": "<user|assistant|skip>"}},
+                          "label_mapping": null,
+                          "notes": "<short reason>"
+                        }}"""),
+                },
+            ],
+            512,
+        )
+        pass2 = _parse_json_response(pass2_raw)
+        if not pass2:
+            return None
+        column_roles = pass2.get("column_roles")
+        if not isinstance(column_roles, dict):
+            return None
+        roles_present = set(column_roles.values())
+        if "user" not in roles_present or "assistant" not in roles_present:
+            return None
+
+        label_mapping = pass2.get("label_mapping") or None
+        system_prompt = ""
+        if not pass1.get("is_conversational"):
+            user_cols = [col for col, role in column_roles.items() if role == "user"]
+            assistant_cols = [col for col, role in column_roles.items() if role == "assistant"]
+            prompt_raw = _generate_with_backend(
+                backend,
+                [
+                    {
+                        "role": "user",
+                        "content": textwrap.dedent(f"""\
+                            Write a concise system prompt for fine-tuning.
+
+                            Dataset type: {pass1.get("dataset_type", "other")}
+                            Task: {pass1.get("task_description") or pass1.get("description") or ""}
+                            User input columns: {user_cols}
+                            Assistant output columns: {assistant_cols}
+
+                            Write only the system prompt text."""),
+                    },
+                ],
+                256,
+            )
+            cleaned = prompt_raw.strip().strip('"').strip("'").strip()
+            if 20 <= len(cleaned) <= 800 and cleaned.lower() not in {"null", "none"}:
+                system_prompt = cleaned
+
+        suggested_mapping = {
+            col: role
+            for col, role in column_roles.items()
+            if col in columns and role in {"user", "assistant", "system"}
+        }
+        if (
+            "user" not in suggested_mapping.values()
+            or "assistant" not in suggested_mapping.values()
+        ):
+            return None
+
+        dtype = str(pass1.get("dataset_type") or "other")
+        notification_parts = [f"This is a {dtype} dataset."]
+        description = pass1.get("task_description") or pass1.get("description")
+        if description:
+            notification_parts.append(str(description))
+        notification_parts.append("Columns were mapped to conversation roles.")
+
+        return {
+            "success": True,
+            "suggested_mapping": suggested_mapping,
+            "system_prompt": system_prompt,
+            "label_mapping": label_mapping if isinstance(label_mapping, dict) else None,
+            "dataset_type": dtype,
+            "is_conversational": bool(pass1.get("is_conversational")),
+            "user_notification": " ".join(notification_parts),
+        }
+    except Exception as exc:
+        logger.warning("Hub advisor failed: %s", exc)
+        return None
+    finally:
+        if backend is not None:
+            try:
+                backend.unload_model()
+            except Exception:
+                pass
+
+
+def _heuristic_mapping(columns: list[str]) -> Optional[dict[str, str]]:
+    if not columns:
+        return None
+    lowered = {col: col.lower().replace("-", "_") for col in columns}
+    metadata_terms = ("id", "uuid", "url", "source", "date", "time", "score", "index")
+    assistant_terms = (
+        "assistant",
+        "answer",
+        "response",
+        "output",
+        "completion",
+        "target",
+        "label",
+        "summary",
+        "translation",
+    )
+    user_terms = (
+        "user",
+        "human",
+        "prompt",
+        "instruction",
+        "input",
+        "question",
+        "query",
+        "context",
+        "document",
+        "article",
+        "problem",
+        "text",
+    )
+    mapping: dict[str, str] = {}
+    for col, name in lowered.items():
+        if any(term == name or name.endswith(f"_{term}") for term in metadata_terms):
+            continue
+        if any(term in name for term in assistant_terms):
+            mapping[col] = "assistant"
+        elif any(term in name for term in user_terms):
+            mapping[col] = "user"
+
+    if "assistant" not in mapping.values():
+        candidates = [col for col in columns if col not in mapping]
+        if candidates:
+            mapping[candidates[-1]] = "assistant"
+        elif columns:
+            mapping[columns[-1]] = "assistant"
+    if "user" not in mapping.values():
+        for col in columns:
+            if mapping.get(col) != "assistant":
+                mapping[col] = "user"
+                break
+    if "user" not in mapping.values() or "assistant" not in mapping.values():
+        return None
+    return mapping
+
+
+def llm_conversion_advisor(
+    column_names: list[str],
+    samples: list[dict[str, Any]],
+    dataset_name: Optional[str] = None,
+    hf_token: Optional[str] = None,
+    model_name: Optional[str] = None,
+    model_type: Optional[str] = None,
+) -> Optional[dict[str, Any]]:
+    dataset_card = None
+    dataset_metadata = None
+    if dataset_name and "/" in dataset_name:
+        dataset_card, dataset_metadata = _fetch_hf_dataset_card(dataset_name, hf_token)
+
+    result = _run_multi_pass_advisor(
+        columns = column_names,
+        samples = samples,
+        dataset_name = dataset_name,
+        dataset_card = dataset_card,
+        dataset_metadata = dataset_metadata,
+        model_name = model_name,
+        model_type = model_type,
+    )
+    if result and result.get("success"):
+        return result
+
+    mapping = _heuristic_mapping(column_names)
+    if mapping:
+        return {
+            "success": True,
+            "suggested_mapping": mapping,
+            "dataset_type": None,
+            "is_conversational": None,
+            "warning": (
+                "The helper model was unavailable, so Hub used column-name heuristics. "
+                "Review the suggested mapping before training."
+            ),
+        }
+    return None
diff --git a/studio/backend/hub/utils/paths.py b/studio/backend/hub/utils/paths.py
new file mode 100644
index 0000000000..afcb0b41dc
--- /dev/null
+++ b/studio/backend/hub/utils/paths.py
@@ -0,0 +1,522 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Path validators and storage roots for the Hub layer."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tempfile
+import threading
+from collections import OrderedDict
+from pathlib import Path
+from typing import Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+
+def _infer_studio_home_from_venv() -> Optional[Path]:
+    try:
+        prefix = Path(sys.prefix).resolve()
+    except (OSError, ValueError):
+        return None
+    if prefix.name != "unsloth_studio":
+        return None
+    candidate = prefix.parent
+    shim_name = "unsloth.exe" if os.name == "nt" else "unsloth"
+    try:
+        if (candidate / "share" / "studio.conf").is_file() or (
+            candidate / "bin" / shim_name
+        ).is_file():
+            return candidate
+    except OSError:
+        return None
+    return None
+
+
+def studio_root() -> Path:
+    override = (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip()
+    if not override:
+        override = (os.environ.get("STUDIO_HOME") or "").strip()
+    if override:
+        try:
+            return Path(override).expanduser().resolve()
+        except (OSError, ValueError):
+            return Path(override).expanduser()
+    inferred = _infer_studio_home_from_venv()
+    if inferred is not None:
+        return inferred
+    return Path.home() / ".unsloth" / "studio"
+
+
+def cache_root() -> Path:
+    return studio_root() / "cache"
+
+
+def assets_root() -> Path:
+    return studio_root() / "assets"
+
+
+def datasets_root() -> Path:
+    return assets_root() / "datasets"
+
+
+def dataset_uploads_root() -> Path:
+    return datasets_root() / "uploads"
+
+
+def recipe_datasets_root() -> Path:
+    return datasets_root() / "recipes"
+
+
+def outputs_root() -> Path:
+    return studio_root() / "outputs"
+
+
+def exports_root() -> Path:
+    return studio_root() / "exports"
+
+
+def tmp_root() -> Path:
+    return Path(tempfile.gettempdir()) / "unsloth-studio"
+
+
+def ensure_dir(path: Path) -> Path:
+    path.mkdir(parents = True, exist_ok = True)
+    return path
+
+
+def legacy_hf_cache_dir() -> Path:
+    return cache_root() / "huggingface" / "hub"
+
+
+def hf_default_cache_dir() -> Path:
+    return Path.home() / ".cache" / "huggingface" / "hub"
+
+
+def _is_wsl() -> bool:
+    if sys.platform == "win32":
+        return False
+    try:
+        return "microsoft" in Path("/proc/version").read_text().lower()
+    except Exception:
+        return False
+
+
+_IS_WSL = _is_wsl()
+
+
+def _wsl_automount_root() -> str:
+    """DrvFs root under which WSL maps Windows drives, with a trailing slash.
+
+    Defaults to ``/mnt/`` but is user-configurable via ``/etc/wsl.conf``
+    (``[automount] root``), so hard-coding ``/mnt/`` mistranslates Windows paths
+    on a host with a custom root (e.g. ``root = /`` → ``C:`` at ``/c/``)."""
+    default = "/mnt/"
+    if not _IS_WSL:
+        return default
+    try:
+        import configparser
+
+        parser = configparser.ConfigParser(inline_comment_prefixes = ("#", ";"))
+        parser.read("/etc/wsl.conf")
+        root = parser.get("automount", "root", fallback = "").strip().strip("\"'")
+    except Exception:
+        return default
+    if not root:
+        return default
+    return root if root.endswith("/") else f"{root}/"
+
+
+_WSL_AUTOMOUNT_ROOT = _wsl_automount_root()
+
+
+def normalize_path(path: str) -> str:
+    if not path:
+        return path
+    if len(path) >= 3 and path[1] == ":" and path[2] in ("\\", "/"):
+        if _IS_WSL:
+            drive = path[0].lower()
+            rest = path[3:].replace("\\", "/")
+            return f"{_WSL_AUTOMOUNT_ROOT}{drive}/{rest}"
+        return path.replace("\\", "/")
+    return path.replace("\\", "/")
+
+
+def _host_path(path: str | Path) -> Path:
+    return Path(normalize_path(str(path))).expanduser()
+
+
+def is_local_path(path: str) -> bool:
+    if not path:
+        return False
+    normalized = normalize_path(path)
+    has_local_syntax = (
+        path.startswith(("/", ".", "~"))
+        or ":" in path
+        or "\\" in path
+        or os.path.isabs(path)
+        or os.path.isabs(normalized)
+    )
+    if path.count("/") == 1 and not has_local_syntax:
+        return False
+    try:
+        if has_local_syntax and Path(normalized).expanduser().exists():
+            return True
+    except Exception:
+        pass
+    return has_local_syntax
+
+
+_VALID_REPO_ID_SEGMENT = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$")
+_MAX_REPO_ID_LENGTH = 96
+
+
+def is_valid_repo_id(repo_id: str) -> bool:
+    """Validate Hugging Face ``repo_name`` or ``namespace/repo_name`` IDs."""
+    if not repo_id or repo_id != repo_id.strip():
+        return False
+    if len(repo_id) > _MAX_REPO_ID_LENGTH or repo_id.endswith(".git"):
+        return False
+    if "--" in repo_id or ".." in repo_id:
+        return False
+    segments = repo_id.split("/")
+    if len(segments) not in (1, 2):
+        return False
+    return all(
+        segment not in ("", ".", "..") and _VALID_REPO_ID_SEGMENT.fullmatch(segment) is not None
+        for segment in segments
+    )
+
+
+_GGUF_VARIANT_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
+_MAX_GGUF_VARIANT_LENGTH = 512
+
+
+def is_valid_gguf_variant(variant: str) -> bool:
+    """Validate Hub GGUF variant keys.
+
+    Known quant labels are short tokens (``Q4_K_M``), but unknown GGUF layouts
+    use a snapshot-relative key derived from the filename and may contain
+    slashes or spaces.
+    """
+    if not variant or variant != variant.strip():
+        return False
+    if len(variant) > _MAX_GGUF_VARIANT_LENGTH:
+        return False
+    if _GGUF_VARIANT_CONTROL_CHARS.search(variant) or not variant.isprintable():
+        return False
+    normalized = variant.replace("\\", "/")
+    return all(segment not in ("", ".", "..") for segment in normalized.split("/"))
+
+
+def ollama_model_dirs() -> list[Path]:
+    """Return Ollama model directories that exist on disk."""
+    dirs: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(p: Path | str) -> None:
+        try:
+            expanded = _host_path(p)
+            resolved = expanded.resolve()
+            is_dir = expanded.is_dir()
+        except (OSError, RuntimeError, ValueError):
+            return
+        key = str(resolved)
+        if key in seen or not is_dir:
+            return
+        seen.add(key)
+        dirs.append(expanded)
+
+    ollama_env = os.environ.get("OLLAMA_MODELS")
+    if ollama_env:
+        _add(ollama_env)
+    _add(Path.home() / ".ollama" / "models")
+    _add(Path("/usr/share/ollama/.ollama/models"))
+    _add(Path("/var/lib/ollama/.ollama/models"))
+    return dirs
+
+
+# Per-process memo for resolve_cached_repo_id_case. Bounded LRU so a long-lived
+# process touching many repo ids can't grow it without limit; evicted cold
+# entries simply recompute on next use.
+_CACHE_CASE_RESOLUTION_MEMO_MAX = 512
+_CACHE_CASE_RESOLUTION_MEMO: "OrderedDict[tuple[str, str], str]" = OrderedDict()
+_CACHE_CASE_RESOLUTION_LOCK = threading.Lock()
+
+
+def _memo_get(memo_key: tuple[str, str]) -> Optional[str]:
+    with _CACHE_CASE_RESOLUTION_LOCK:
+        value = _CACHE_CASE_RESOLUTION_MEMO.get(memo_key)
+        if value is not None:
+            _CACHE_CASE_RESOLUTION_MEMO.move_to_end(memo_key)
+        return value
+
+
+def _memo_set(memo_key: tuple[str, str], value: str) -> None:
+    with _CACHE_CASE_RESOLUTION_LOCK:
+        _CACHE_CASE_RESOLUTION_MEMO[memo_key] = value
+        _CACHE_CASE_RESOLUTION_MEMO.move_to_end(memo_key)
+        while len(_CACHE_CASE_RESOLUTION_MEMO) > _CACHE_CASE_RESOLUTION_MEMO_MAX:
+            _CACHE_CASE_RESOLUTION_MEMO.popitem(last = False)
+
+
+def _memo_drop(memo_key: tuple[str, str]) -> None:
+    with _CACHE_CASE_RESOLUTION_LOCK:
+        _CACHE_CASE_RESOLUTION_MEMO.pop(memo_key, None)
+
+
+def _hf_hub_cache_dir() -> Path:
+    try:
+        from huggingface_hub.constants import HF_HUB_CACHE
+        return Path(HF_HUB_CACHE)
+    except Exception as exc:
+        logger.debug("Could not read huggingface_hub HF_HUB_CACHE, using default: %s", exc)
+        return Path.home() / ".cache" / "huggingface" / "hub"
+
+
+def _hf_hub_cache_dirs() -> list[Path]:
+    roots: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(path: Path) -> None:
+        try:
+            resolved = path.resolve()
+        except OSError:
+            return
+        key = str(resolved)
+        if key in seen or not resolved.is_dir():
+            return
+        seen.add(key)
+        roots.append(resolved)
+
+    _add(_hf_hub_cache_dir())
+    try:
+        _add(legacy_hf_cache_dir())
+        _add(hf_default_cache_dir())
+    except Exception as exc:
+        logger.debug("Could not enumerate secondary HF cache roots: %s", exc)
+    return roots
+
+
+def lmstudio_model_dirs() -> list[Path]:
+    dirs: list[Path] = []
+    seen: set[str] = set()
+
+    def _add(path: Path | str) -> None:
+        try:
+            expanded = _host_path(path)
+            resolved = expanded.resolve()
+        except (OSError, RuntimeError, ValueError):
+            return
+        key = str(resolved)
+        if key in seen or not expanded.is_dir():
+            return
+        seen.add(key)
+        dirs.append(expanded)
+
+    settings_path = Path.home() / ".lmstudio" / "settings.json"
+    if settings_path.is_file():
+        try:
+            settings = json.loads(settings_path.read_text(encoding = "utf-8"))
+            downloads = settings.get("downloadsFolder", "")
+            if downloads:
+                _add(downloads)
+        except Exception:
+            pass
+    _add(Path.home() / ".lmstudio" / "models")
+    _add(Path.home() / ".cache" / "lm-studio" / "models")
+    return dirs
+
+
+def well_known_model_dirs() -> list[Path]:
+    candidates: list[Path] = []
+    candidates.extend(lmstudio_model_dirs())
+    candidates.extend(ollama_model_dirs())
+    candidates.append(Path.home() / ".cache" / "huggingface" / "hub")
+    candidates.append(Path.home() / "models")
+    candidates.append(Path.home() / "Models")
+
+    out: list[Path] = []
+    seen: set[str] = set()
+    for path in candidates:
+        try:
+            resolved = path.resolve()
+        except OSError:
+            continue
+        key = str(resolved)
+        if key in seen or not resolved.is_dir():
+            continue
+        seen.add(key)
+        out.append(resolved)
+    return out
+
+
+def _assert_contained(resolved: Path, root: Path) -> None:
+    try:
+        resolved_real = Path(os.path.realpath(resolved))
+        root_real = Path(os.path.realpath(root))
+    except OSError as exc:
+        raise ValueError(f"path resolution failed: {exc}") from exc
+    try:
+        resolved_real.relative_to(root_real)
+    except ValueError as exc:
+        raise ValueError(f"path escapes root: {resolved!s}") from exc
+
+
+def path_is_same_or_child(path: Path, root: Path) -> bool:
+    """True when *path* is *root* or lives beneath it.
+
+    Compares real (symlink-resolved, case-normalized) paths so the check holds
+    through symlinks and on case-insensitive filesystems, where a plain
+    ``Path.is_relative_to`` would miss a casing-only match. Returns False on any
+    resolution error rather than raising.
+    """
+    try:
+        path_real = os.path.normcase(os.path.realpath(str(path)))
+        root_real = os.path.normcase(os.path.realpath(str(root)))
+        return os.path.commonpath([path_real, root_real]) == root_real
+    except (OSError, ValueError):
+        return False
+
+
+def resolve_dataset_path(path_value: str) -> Path:
+    raw = str(path_value or "").strip()
+    if "\x00" in raw:
+        raise ValueError("dataset path may not contain null bytes")
+    # Normalize first so Windows/UNC and backslash paths resolve like the rest
+    # of the Hub path layer (e.g. C:\data -> /mnt/c/data on WSL) and a
+    # backslashed '..' is caught by the traversal guard below.
+    normalized = normalize_path(raw)
+    path = Path(normalized).expanduser()
+    if ".." in path.parts:
+        raise ValueError(f"dataset path may not contain '..' segments: {raw!r}")
+    if path.is_absolute():
+        for root in (datasets_root(), dataset_uploads_root(), recipe_datasets_root()):
+            try:
+                _assert_contained(path, root)
+                return path
+            except ValueError:
+                continue
+        raise ValueError(f"dataset path must be relative or under a dataset root: {raw!r}")
+
+    parts = [part for part in Path(normalized).parts if part not in ("", ".")]
+    if parts[:2] == ["assets", "datasets"]:
+        parts = parts[2:]
+    if parts and parts[0] == "uploads":
+        cleaned = Path(*parts[1:]) if len(parts) > 1 else Path()
+        return dataset_uploads_root() / cleaned
+    if parts and parts[0] == "recipes":
+        cleaned = Path(*parts[1:]) if len(parts) > 1 else Path()
+        return recipe_datasets_root() / cleaned
+
+    cleaned = Path(*parts) if parts else Path()
+    candidates = [
+        dataset_uploads_root() / cleaned,
+        recipe_datasets_root() / cleaned,
+        datasets_root() / cleaned,
+        dataset_uploads_root() / cleaned.name,
+        recipe_datasets_root() / cleaned.name,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]
+
+
+def resolve_cached_repo_id_case(
+    model_name: str,
+    use_memo: bool = True,
+    repo_type: str = "model",
+) -> str:
+    """Resolve repo_id to the exact casing already present in local HF cache.
+
+    Prefers the requested casing, but if a case-variant already exists in
+    local HF cache, reuses that exact cached spelling so we don't trigger
+    a duplicate download.
+    """
+    if not model_name or "/" not in model_name:
+        return model_name
+
+    cache_dirs = _hf_hub_cache_dirs()
+    if not cache_dirs:
+        return model_name
+
+    prefix = f"{repo_type}s--"
+    expected_dir = f"{prefix}{model_name.replace('/', '--')}"
+    memo_key = (repo_type, model_name)
+
+    for cache_dir in cache_dirs:
+        exact_path = cache_dir / expected_dir
+        if exact_path.is_dir():
+            if use_memo:
+                _memo_set(memo_key, model_name)
+            return model_name
+
+    if use_memo:
+        cached = _memo_get(memo_key)
+        if cached is not None:
+            if any(
+                (cache_dir / f"{prefix}{cached.replace('/', '--')}").is_dir()
+                for cache_dir in cache_dirs
+            ):
+                return cached
+            _memo_drop(memo_key)
+
+    expected_lower = expected_dir.lower()
+    try:
+        candidates: set[str] = set()
+        for cache_dir in cache_dirs:
+            for entry in cache_dir.iterdir():
+                if not entry.is_dir():
+                    continue
+                if entry.name.lower() != expected_lower:
+                    continue
+                # The lowercased full-name match already proves the prefix
+                # matches; a case-sensitive startswith would reject a mixed-case
+                # imported dir such as Models--Org--Repo.
+                repo_part = entry.name[len(prefix) :]
+                if not repo_part:
+                    continue
+                candidates.add(repo_part.replace("--", "/"))
+
+        if candidates:
+            resolved = sorted(candidates)[0]
+            if use_memo:
+                _memo_set(memo_key, resolved)
+            return resolved
+    except Exception as exc:
+        logger.debug(f"resolve_cached_repo_id_case failed for {model_name!r}: {exc}")
+
+    return model_name
+
+
+__all__ = [
+    "assets_root",
+    "cache_root",
+    "dataset_uploads_root",
+    "datasets_root",
+    "ensure_dir",
+    "exports_root",
+    "hf_default_cache_dir",
+    "is_local_path",
+    "is_valid_gguf_variant",
+    "is_valid_repo_id",
+    "legacy_hf_cache_dir",
+    "lmstudio_model_dirs",
+    "normalize_path",
+    "ollama_model_dirs",
+    "outputs_root",
+    "path_is_same_or_child",
+    "recipe_datasets_root",
+    "resolve_cached_repo_id_case",
+    "resolve_dataset_path",
+    "studio_root",
+    "tmp_root",
+    "well_known_model_dirs",
+]
diff --git a/studio/backend/hub/utils/snapshot_filters.py b/studio/backend/hub/utils/snapshot_filters.py
new file mode 100644
index 0000000000..20674db4f0
--- /dev/null
+++ b/studio/backend/hub/utils/snapshot_filters.py
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+from typing import Iterable
+
+
+SNAPSHOT_IGNORE_PATTERNS: tuple[str, ...] = (
+    "*.gguf",
+    "*.onnx",
+    "onnx/*",
+    "openvino/*",
+    "mlx/*",
+    "*.bin.index.json.bak",
+)
+CONSOLIDATED_PATTERN = "consolidated*"
+SNAPSHOT_WEIGHT_EXTENSIONS = (
+    ".safetensors",
+    ".bin",
+    ".pt",
+    ".pth",
+    ".ckpt",
+    ".h5",
+    ".msgpack",
+    ".npz",
+)
+SNAPSHOT_NON_BIN_WEIGHT_EXTENSIONS = tuple(
+    ext for ext in SNAPSHOT_WEIGHT_EXTENSIONS if ext != ".bin"
+)
+SNAPSHOT_BIN_WEIGHT_PREFIXES = ("model", "pytorch_model", "adapter_model")
+
+
+def _filename(sibling) -> str:
+    value = getattr(sibling, "rfilename", "")
+    return value if isinstance(value, str) else ""
+
+
+def _size(sibling) -> int:
+    value = getattr(sibling, "size", None)
+    return int(value) if isinstance(value, int) and value > 0 else 0
+
+
+def repo_ships_transformers_weights(filenames: Iterable[str]) -> bool:
+    for name in filenames:
+        base = name.rsplit("/", 1)[-1].lower()
+        if base.startswith("consolidated"):
+            continue
+        if base.endswith(SNAPSHOT_NON_BIN_WEIGHT_EXTENSIONS):
+            return True
+        if base.endswith(".bin") and base.startswith(SNAPSHOT_BIN_WEIGHT_PREFIXES):
+            return True
+    return False
+
+
+def resolve_snapshot_ignore_patterns_for_files(filenames: Iterable[str]) -> list[str]:
+    names = list(filenames)
+    ignore = list(SNAPSHOT_IGNORE_PATTERNS)
+    if repo_ships_transformers_weights(names):
+        ignore.append(CONSOLIDATED_PATTERN)
+    return ignore
+
+
+def sibling_matches_ignore(filename: str, ignore_patterns: Iterable[str]) -> bool:
+    return any(fnmatchcase(filename, pattern) for pattern in ignore_patterns)
+
+
+def snapshot_download_siblings(siblings: Iterable) -> list:
+    items = list(siblings)
+    ignore_patterns = resolve_snapshot_ignore_patterns_for_files(
+        _filename(sibling) for sibling in items
+    )
+    return [
+        sibling
+        for sibling in items
+        if not sibling_matches_ignore(_filename(sibling), ignore_patterns)
+    ]
+
+
+def snapshot_download_size(siblings: Iterable) -> int:
+    return sum(_size(sibling) for sibling in snapshot_download_siblings(siblings))
+
+
+def total_size_for_siblings(siblings: Iterable) -> int:
+    """Sum of declared sizes across siblings verbatim (no ignore filter).
+
+    Use for repo types that download every file (datasets); models go
+    through ``snapshot_download_size`` so the ignore patterns apply."""
+    return sum(_size(sibling) for sibling in siblings)
+
+
+def blob_hashes_for_siblings(siblings: Iterable) -> frozenset[str]:
+    # Blob filename == file etag (LFS sha256, else git blob id). Collecting both
+    # lets progress count exactly this revision's files without summing stale
+    # blobs from other revisions.
+    hashes: set[str] = set()
+    for sibling in siblings:
+        sha = getattr(getattr(sibling, "lfs", None), "sha256", None)
+        if isinstance(sha, str) and sha:
+            hashes.add(sha)
+            continue
+        blob_id = getattr(sibling, "blob_id", None)
+        if isinstance(blob_id, str) and blob_id:
+            hashes.add(blob_id)
+    return frozenset(hashes)
+
+
+def snapshot_download_blob_hashes(siblings: Iterable) -> frozenset[str]:
+    return blob_hashes_for_siblings(snapshot_download_siblings(siblings))
diff --git a/studio/backend/hub/utils/state_dir.py b/studio/backend/hub/utils/state_dir.py
new file mode 100644
index 0000000000..a304477a3d
--- /dev/null
+++ b/studio/backend/hub/utils/state_dir.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Filesystem layout for Hub download state.
+
+State directory sits beside HF's cache (under Studio's own cache root)
+so it survives ``huggingface-cli delete-cache`` and any other HF-side
+cache lifecycle. Two subdirectories:
+
+    <studio cache>/hub-state/
+        manifests/   <key>.json   per-download expected-files manifest
+        cancelled/   <key>.json   per-download cancel marker
+
+The ``<key>`` mirrors HF's cache dir naming so a state file can be
+eyeballed next to the on-disk repo it describes:
+
+    models--<owner>--<name>                       full snapshot
+    models--<owner>--<name>--variant--<variant>   GGUF variant
+    datasets--<owner>--<name>                     dataset snapshot
+
+All path accessors return ``Optional[Path]`` and yield ``None`` when
+the directory can't be created (read-only FS, permission error).
+Callers must treat ``None`` as "no state available" and fall through
+to existing on-disk-only behavior; this module never raises on a
+configuration failure.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Literal, Optional, get_args
+
+from loggers import get_logger
+
+from hub.utils.paths import cache_root
+
+logger = get_logger(__name__)
+
+
+RepoType = Literal["model", "dataset"]
+
+_VALID_REPO_TYPES: tuple[RepoType, ...] = get_args(RepoType)
+
+
+_HUB_STATE_DIRNAME = "hub-state"
+_MANIFESTS_SUBDIR = "manifests"
+_CANCELLED_SUBDIR = "cancelled"
+_WORKERS_SUBDIR = "workers"
+_SAFE_VARIANT_FRAGMENT = re.compile(r"^[a-z0-9._-]{1,64}$")
+
+
+def state_root() -> Optional[Path]:
+    """Return the Hub state root, creating it if needed. ``None`` on failure."""
+    root = cache_root() / _HUB_STATE_DIRNAME
+    try:
+        root.mkdir(parents = True, exist_ok = True)
+    except OSError as exc:
+        logger.debug("Could not create hub state root %s: %s", root, exc)
+        return None
+    return root
+
+
+def _subdir(name: str) -> Optional[Path]:
+    root = state_root()
+    if root is None:
+        return None
+    path = root / name
+    try:
+        path.mkdir(parents = True, exist_ok = True)
+    except OSError as exc:
+        logger.debug("Could not create hub state subdir %s: %s", path, exc)
+        return None
+    return path
+
+
+def repo_cache_basename(repo_type: RepoType, repo_id: str) -> str:
+    # Reject a bad repo_type at runtime: a wrong value would silently produce a
+    # wrong filename and a misclassified scanner row (the Literal only guards
+    # statically; dynamic/JSON-sourced values slip past it).
+    if repo_type not in _VALID_REPO_TYPES:
+        raise ValueError(f"repo_type must be one of {_VALID_REPO_TYPES}, got {repo_type!r}")
+    return f"{repo_type}s--{repo_id.replace('/', '--')}".lower()
+
+
+def variant_filename_prefix(repo_type: RepoType, repo_id: str) -> str:
+    """Lowercased prefix every variant-keyed state file for this repo shares.
+
+    The single source the download_manifest enumerators match against, so the
+    scheme in :func:`_entry_key` cannot drift from them silently."""
+    return f"{repo_cache_basename(repo_type, repo_id)}--variant--"
+
+
+def _entry_key(repo_type: RepoType, repo_id: str, variant: Optional[str]) -> str:
+    base = repo_cache_basename(repo_type, repo_id)
+    if not variant:
+        return base
+    normalized_variant = variant.strip().lower()
+    if _SAFE_VARIANT_FRAGMENT.fullmatch(normalized_variant):
+        variant_fragment = normalized_variant
+    else:
+        digest = hashlib.sha256(normalized_variant.encode("utf-8")).hexdigest()[:32]
+        variant_fragment = f"sha256-{digest}"
+    return f"{variant_filename_prefix(repo_type, repo_id)}{variant_fragment}"
+
+
+def manifest_path(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> Optional[Path]:
+    """Path to the manifest file for this triple. May or may not exist."""
+    parent = _subdir(_MANIFESTS_SUBDIR)
+    if parent is None:
+        return None
+    return parent / f"{_entry_key(repo_type, repo_id, variant)}.json"
+
+
+def marker_path(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: Optional[str] = None,
+) -> Optional[Path]:
+    """Path to the cancel-marker file for this triple. May or may not exist."""
+    parent = _subdir(_CANCELLED_SUBDIR)
+    if parent is None:
+        return None
+    return parent / f"{_entry_key(repo_type, repo_id, variant)}.json"
+
+
+def manifests_dir() -> Optional[Path]:
+    """Manifests subdirectory, created on demand. ``None`` on failure.
+
+    Exposed for iter_variant_manifests, which enumerates the directory to find
+    every variant-keyed manifest for a repo (the path helpers above answer
+    "where would key X go" but not "what keys exist")."""
+    return _subdir(_MANIFESTS_SUBDIR)
+
+
+def cancelled_dir() -> Optional[Path]:
+    """Cancel-marker subdirectory, created on demand. ``None`` on failure.
+
+    See manifests_dir for why this iteration entry point is needed."""
+    return _subdir(_CANCELLED_SUBDIR)
+
+
+def workers_dir() -> Optional[Path]:
+    """Worker PID-breadcrumb subdirectory, created on demand. ``None`` on failure.
+
+    Each live download worker drops one breadcrumb here so a backend that
+    restarts after a hard crash can reap workers it can no longer reach through
+    its in-memory registry."""
+    return _subdir(_WORKERS_SUBDIR)
diff --git a/studio/backend/hub/workers/__init__.py b/studio/backend/hub/workers/__init__.py
new file mode 100644
index 0000000000..32014236c6
--- /dev/null
+++ b/studio/backend/hub/workers/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
diff --git a/studio/backend/hub/workers/hf_download.py b/studio/backend/hub/workers/hf_download.py
new file mode 100644
index 0000000000..42a8ca52b3
--- /dev/null
+++ b/studio/backend/hub/workers/hf_download.py
@@ -0,0 +1,753 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""HuggingFace Hub download worker, spawned as a subprocess so SIGKILL stops all chunk threads.
+
+Resume safety
+-------------
+Downloads here MUST be single-stream sequential writers so the parent's
+SIGKILL → restart loop can rely on ``os.path.getsize(.incomplete)`` to
+compute the correct resume offset.
+
+Enforced by:
+- Setting ``HF_HUB_DISABLE_XET=1`` and ``HF_HUB_ENABLE_HF_TRANSFER=0`` on
+  the spawning side (see :mod:`hub.utils.download_registry`) for transport=http.
+- Passing ``max_workers=1`` to ``snapshot_download`` so files download
+  serially, making the at-most-one-active-`.incomplete` invariant hold
+  globally and simplifying reasoning about partial state during a SIGKILL.
+- Letting ``prepare_cache_for_transport`` purge any pre-existing
+  ``.incomplete`` blobs not provably from the same sequential writer.
+
+If the final byte count doesn't match what HF declared, huggingface_hub
+raises ``EnvironmentError`` ("Consistency check failed: …"); we surface
+that on stderr so the watcher can show the exact message to the user.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import sys
+import threading
+import time
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_BACKEND = _HERE.parent.parent
+if str(_BACKEND) not in sys.path:
+    sys.path.insert(0, str(_BACKEND))
+
+from hub.utils.snapshot_filters import (
+    SNAPSHOT_IGNORE_PATTERNS,
+)
+from hub.utils.gguf_plan import (
+    GgufVariantPlan,
+    build_gguf_variant_plans,
+    plan_from_expected_files,
+    sibling_sha256,
+)
+from hub.utils.state_dir import RepoType
+
+HfTokenArg = str | bool | None
+
+
+# Bound the metadata fetch so a stalled connection fails the worker (exit 1)
+# instead of hanging at 0%. The file download itself is governed separately by
+# huggingface_hub's own timeout.
+_METADATA_REQUEST_TIMEOUT = 10.0
+_METADATA_RETRY_TIMEOUT = 30.0
+_METADATA_RETRY_DELAY = 1.0
+
+
+def _on_signal(signum, frame):
+    # 130 is what `classify_exit` maps to the "cancelled" job state.
+    sys.exit(130)
+
+
+def _install_signal_handlers() -> None:
+    signal.signal(signal.SIGTERM, _on_signal)
+    signal.signal(signal.SIGINT, _on_signal)
+    sigpipe = getattr(signal, "SIGPIPE", None)
+    if sigpipe is not None:
+        signal.signal(sigpipe, _on_signal)
+
+
+def _parent_poll_seconds() -> float:
+    raw = os.environ.get("UNSLOTH_HF_WORKER_PARENT_POLL_SECONDS")
+    if raw:
+        try:
+            value = float(raw)
+            if value > 0:
+                return value
+        except ValueError:
+            pass
+    return 2.0
+
+
+def _protected_blob_hashes() -> frozenset[str]:
+    """Blob hashes a concurrent same-repo peer is writing (passed by the backend
+    as a plain env list). Excluded from this worker's purge so a shared
+    ``.incomplete`` (e.g. a bundled mmproj) is never deleted under the peer."""
+    raw = os.environ.get("UNSLOTH_PROTECTED_BLOB_HASHES", "")
+    return frozenset(h for h in raw.split(",") if h)
+
+
+def _parent_is_alive(parent_pid: int) -> bool:
+    """Whether the recorded parent (the backend) is still running.
+
+    Liveness ONLY: ``os.kill(pid, 0)`` on POSIX, an ``OpenProcess`` handle on
+    Windows, against the *recorded* PID (never os.getppid(), so POSIX
+    reparenting to init after the backend dies still resolves as dead). Probe
+    ambiguity is treated as alive so a transient error never kills a healthy
+    download.
+
+    We deliberately do NOT compare psutil ``create_time()`` for PID-reuse
+    detection: it isn't stable across reads on some platforms, so an exact match
+    can spuriously kill a live download. PID-reuse after parent death is covered
+    by the boot-time orphan reaper.
+    """
+    if sys.platform == "win32":
+        import ctypes
+        from ctypes import wintypes
+
+        SYNCHRONIZE = 0x00100000
+        WAIT_OBJECT_0 = 0x0
+        ERROR_INVALID_PARAMETER = 87
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error = True)
+        kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+        kernel32.OpenProcess.restype = wintypes.HANDLE
+        kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+        kernel32.WaitForSingleObject.restype = wintypes.DWORD
+        kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+        kernel32.CloseHandle.restype = wintypes.BOOL
+        ctypes.set_last_error(0)
+        handle = kernel32.OpenProcess(SYNCHRONIZE, False, parent_pid)
+        if not handle:
+            return ctypes.get_last_error() != ERROR_INVALID_PARAMETER
+        try:
+            return kernel32.WaitForSingleObject(handle, 0) != WAIT_OBJECT_0
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(parent_pid, 0)
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True
+    return True
+
+
+def _terminate_orphaned_self() -> None:
+    # Hard exit from the watchdog thread: a self-SIGTERM would be deferred while
+    # the main thread is GIL-blocked in a C socket read. The partial .incomplete
+    # resumes byte-exact and marker/manifest writes are atomic, so cancelled code
+    # 130 is safe. The diagnostic is best-effort: a dead parent's closed stderr
+    # pipe can raise BrokenPipeError, which must never preempt the exit.
+    try:
+        print(
+            "Parent process exited; stopping orphaned download worker.",
+            file = sys.stderr,
+        )
+        sys.stderr.flush()
+    except Exception:
+        pass
+    os._exit(130)
+
+
+def _install_parent_death_watchdog(parent_pid: int | None) -> None:
+    if not parent_pid or parent_pid <= 0:
+        return
+    interval = _parent_poll_seconds()
+
+    def _watch() -> None:
+        while True:
+            try:
+                alive = _parent_is_alive(parent_pid)
+            except Exception:
+                alive = True
+            if not alive:
+                _terminate_orphaned_self()
+                return
+            time.sleep(interval)
+
+    threading.Thread(
+        target = _watch,
+        name = "parent-death-watchdog",
+        daemon = True,
+    ).start()
+
+
+def _hf_token_arg(hf_token: str | None) -> HfTokenArg:
+    return hf_token if hf_token else False
+
+
+def _retry_metadata_fetch(repo_id: str, fetch, *, label: str):
+    for attempt, timeout in enumerate((_METADATA_REQUEST_TIMEOUT, _METADATA_RETRY_TIMEOUT)):
+        try:
+            return fetch(timeout)
+        except Exception as e:
+            if attempt == 1:
+                raise
+            print(
+                f"{label} request failed for {repo_id} " f"({type(e).__name__}: {e}); retrying.",
+                file = sys.stderr,
+            )
+            time.sleep(_METADATA_RETRY_DELAY)
+    raise RuntimeError(f"{label} unavailable for {repo_id}")
+
+
+def _model_info_with_retry(repo_id: str, hf_token: str | None):
+    from huggingface_hub import model_info as hf_model_info
+    return _retry_metadata_fetch(
+        repo_id,
+        lambda timeout: hf_model_info(
+            repo_id,
+            token = _hf_token_arg(hf_token),
+            timeout = timeout,
+            files_metadata = True,
+        ),
+        label = "Metadata",
+    )
+
+
+def _dataset_info_with_retry(repo_id: str, hf_token: str | None):
+    from huggingface_hub import HfApi
+    api = HfApi(token = _hf_token_arg(hf_token))
+    return _retry_metadata_fetch(
+        repo_id,
+        lambda timeout: api.dataset_info(
+            repo_id,
+            timeout = timeout,
+            files_metadata = True,
+        ),
+        label = "Dataset metadata",
+    )
+
+
+# Tied to drain_stderr_excerpt's 500-byte head/tail window in the parent (see
+# hub/utils/download_registry.py): listing every expected file would blow past
+# it and lose the diagnostic. Cap the preview so the summary line survives.
+_VERIFY_PATH_LIST_CAP = 10
+
+
+def _format_path_list(paths: tuple[str, ...], cap: int = _VERIFY_PATH_LIST_CAP) -> str:
+    if len(paths) <= cap:
+        return ", ".join(paths)
+    head = ", ".join(paths[:cap])
+    return f"{head}, ... and {len(paths) - cap} more"
+
+
+def _verify_completed_download(
+    repo_type: RepoType,
+    repo_id: str,
+    variant: str | None,
+    snapshot_path: str,
+    *,
+    metadata_unavailable: bool = False,
+) -> None:
+    """Verify every manifest file is on disk at its declared size; exit nonzero
+    with a diagnostic if not.
+
+    No-op when no manifest exists: the manifest write is best-effort, so absence
+    means "verification unavailable, trust snapshot_download's exit code".
+    """
+    from hub.utils import download_manifest
+
+    manifest = download_manifest.read_manifest(repo_type, repo_id, variant)
+    if manifest is None:
+        return
+    result = download_manifest.verify_against_disk(
+        manifest,
+        Path(snapshot_path),
+    )
+    if result.ok:
+        return
+    label = f"{repo_id}{f' [{variant}]' if variant else ''}"
+    if metadata_unavailable:
+        print(
+            f"Could not reach Hugging Face for {label} and the copy on disk is "
+            f"incomplete ({len(result.missing)} file(s) missing, "
+            f"{len(result.size_mismatched)} the wrong size). Access to a private "
+            "or restricted repo may have been lost (HF token removed or "
+            "changed), the connection dropped, or Hugging Face is temporarily "
+            "unavailable. Set a valid HF token or reconnect, then resume the "
+            "download.",
+            file = sys.stderr,
+        )
+    else:
+        print(
+            f"Verification failed for {label}: snapshot_download completed but "
+            f"{len(result.missing)} expected file(s) are missing and "
+            f"{len(result.size_mismatched)} have incorrect size on disk.",
+            file = sys.stderr,
+        )
+    if result.missing:
+        print(
+            f"Missing: {_format_path_list(result.missing)}",
+            file = sys.stderr,
+        )
+    if result.size_mismatched:
+        print(
+            f"Size mismatched: {_format_path_list(result.size_mismatched)}",
+            file = sys.stderr,
+        )
+    sys.exit(1)
+
+
+def _preflight_disk_space(repo_type: str, repo_id: str, expected_files: list) -> None:
+    """Fail fast when the active HF cache filesystem can't hold what's left to
+    download. Fail-open: any inability to size the work or read free space skips
+    the check, so a real download is never blocked by an estimation gap."""
+    import shutil
+
+    from hub.utils.download_registry import existing_blob_bytes
+    from hub.utils.hf_cache_state import hf_cache_root
+
+    try:
+        size_by_hash: dict[str, int] = {}
+        unhashed_bytes = 0
+        for expected in expected_files:
+            size = int(getattr(expected, "size", 0) or 0)
+            if size <= 0:
+                continue
+            blob_hash = getattr(expected, "sha256", None)
+            if blob_hash:
+                # Dedup by content hash: a blob listed under two filenames is
+                # written once, so it must be counted once.
+                size_by_hash[blob_hash] = size
+            else:
+                unhashed_bytes += size
+        total_expected = sum(size_by_hash.values()) + unhashed_bytes
+        if total_expected <= 0:
+            return
+        already_have = existing_blob_bytes(
+            repo_type,
+            repo_id,
+            frozenset(size_by_hash),
+        )
+        remaining = max(0, total_expected - already_have)
+        if remaining <= 0:
+            return
+        root = hf_cache_root(create = True)
+        if root is None:
+            return
+        free = shutil.disk_usage(root).free
+    except Exception:
+        return
+
+    if free < remaining:
+        print(
+            f"Not enough disk space to download {repo_id}: need about "
+            f"{remaining / (1024 ** 3):.1f} GB free in {root}, but only "
+            f"{free / (1024 ** 3):.1f} GB is available. Free up space and "
+            "try again.",
+            file = sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _snapshot_download_plan(info) -> tuple[list[str], list]:
+    from hub.utils.download_manifest import ExpectedFile
+    from hub.utils.snapshot_filters import (
+        resolve_snapshot_ignore_patterns_for_files,
+        snapshot_download_siblings,
+    )
+
+    filenames = [s.rfilename for s in info.siblings if isinstance(s.rfilename, str)]
+    filtered = snapshot_download_siblings(info.siblings)
+    expected_files = [
+        ExpectedFile(
+            path = s.rfilename,
+            size = int(getattr(s, "size", 0) or 0),
+            sha256 = sibling_sha256(s),
+        )
+        for s in filtered
+        if isinstance(s.rfilename, str)
+    ]
+    return resolve_snapshot_ignore_patterns_for_files(filenames), expected_files
+
+
+def _dataset_expected_files(info) -> list:
+    from hub.utils.download_manifest import ExpectedFile
+    return [
+        ExpectedFile(
+            path = s.rfilename,
+            size = int(getattr(s, "size", 0) or 0),
+            sha256 = sibling_sha256(s),
+        )
+        for s in info.siblings
+        if isinstance(s.rfilename, str)
+    ]
+
+
+def _recover_manifest_after_download(
+    repo_type: RepoType,
+    repo_id: str,
+    snapshot_path: str,
+    mode: str,
+    *,
+    fetch_info,
+    expected_files_from_info,
+    label: str = "",
+) -> None:
+    """Best-effort manifest write for a download whose metadata was unavailable
+    at start: re-fetch and record the expected files, else fall back to the
+    on-disk file list. Shared by the model and dataset workers.
+
+    A pre-existing manifest is authoritative and is preserved untouched. This is
+    load-bearing: when access is lost on resume (token revoked/changed on a
+    gated/private repo), snapshot_download returns the cached partial snapshot
+    WITHOUT downloading, so rebuilding the manifest from on-disk files would record
+    the partial set as expected and let _verify_completed_download certify a
+    half-finished download as complete.
+
+    The same hazard exists with NO prior manifest. When metadata is still
+    unavailable here, leftover ``.incomplete`` blobs prove a cached partial was
+    returned without downloading, so we fail (exit 1) instead of deriving a
+    self-certifying manifest, leaving the partial intact for a later resume. That
+    signal misses a file that never started (no ``.incomplete``), so a kill
+    between files is accepted optimistically from the on-disk subset; a later
+    metadata-bearing attempt writes the true manifest and catches any shortfall."""
+    from hub.utils import download_manifest
+    from hub.utils.hf_cache_state import has_active_incomplete_blobs
+
+    if download_manifest.read_manifest(repo_type, repo_id, None) is not None:
+        return
+
+    try:
+        if download_manifest.write_manifest(
+            repo_type,
+            repo_id,
+            None,
+            expected_files_from_info(fetch_info()),
+            mode,
+        ):
+            return
+        reason = "manifest write failed"
+    except Exception as e:
+        reason = f"{type(e).__name__}: {e}"
+
+    if has_active_incomplete_blobs(repo_type, repo_id):
+        print(
+            f"{label}could not reach Hugging Face for {repo_id} and the copy on "
+            "disk is still incomplete. Access to a private or restricted repo may "
+            "have been lost (HF token removed or changed), the connection dropped, "
+            "or Hugging Face is temporarily unavailable. Set a valid HF token or "
+            "reconnect, then resume the download.",
+            file = sys.stderr,
+        )
+        sys.exit(1)
+
+    fallback_files = download_manifest.expected_files_from_snapshot_dir(Path(snapshot_path))
+    if fallback_files and download_manifest.write_manifest(
+        repo_type,
+        repo_id,
+        None,
+        fallback_files,
+        mode,
+    ):
+        print(
+            f"{label}could not record the metadata manifest for {repo_id}, "
+            "recorded one from the downloaded files so completion "
+            f"is tracked ({reason})",
+            file = sys.stderr,
+        )
+    else:
+        print(
+            f"{label}could not record the metadata manifest for {repo_id}, "
+            f"{download_manifest.MANIFEST_DEGRADED_MARKER} ({reason})",
+            file = sys.stderr,
+        )
+
+
+def _download_snapshot(repo_id: str, hf_token: str | None, mode: str) -> None:
+    from huggingface_hub import snapshot_download
+    from hub.utils.download_registry import prepare_cache_for_transport
+    from hub.utils import download_manifest
+
+    # One metadata fetch powers both the ignore-pattern decision (drop
+    # consolidated.* when transformers weights exist) and the manifest's
+    # expected_files. A failure is non-fatal: fall back to the legacy
+    # ignore-pattern set (keeping consolidated) and skip the manifest, so
+    # download proceeds without the verification + partial detection it enables.
+    try:
+        info = _model_info_with_retry(repo_id, hf_token)
+    except Exception as e:
+        print(
+            f"metadata unavailable, downloading full snapshot for {repo_id} "
+            f"({type(e).__name__}: {e})",
+            file = sys.stderr,
+        )
+        info = None
+
+    download_manifest.clear_cancel_marker("model", repo_id, None)
+    if info is not None:
+        ignore_patterns, expected_files = _snapshot_download_plan(info)
+        # Written for every transport. The manifest verifies the finalized
+        # files under snapshots/, which both transports produce identically
+        # (XET also renames a full, correctly-sized blob into place). XET's
+        # block-level dedup lives only in the chunk-cache the manifest never
+        # inspects, so per-file size verification is valid regardless of transport.
+        download_manifest.write_manifest("model", repo_id, None, expected_files, mode)
+    else:
+        ignore_patterns = list(SNAPSHOT_IGNORE_PATTERNS)
+        expected_files = []
+
+    purged = prepare_cache_for_transport("model", repo_id, mode)
+    if purged:
+        print(
+            f"Purged {purged} untrusted partial blob(s) for {repo_id} "
+            f"before starting {mode} download.",
+            file = sys.stderr,
+        )
+    _preflight_disk_space("model", repo_id, expected_files)
+    snapshot_path = snapshot_download(
+        repo_id = repo_id,
+        token = _hf_token_arg(hf_token),
+        ignore_patterns = ignore_patterns,
+        max_workers = 1,
+    )
+    if info is None:
+        _recover_manifest_after_download(
+            "model",
+            repo_id,
+            snapshot_path,
+            mode,
+            fetch_info = lambda: _model_info_with_retry(repo_id, hf_token),
+            expected_files_from_info = lambda recovered: _snapshot_download_plan(recovered)[1],
+        )
+    _verify_completed_download(
+        "model",
+        repo_id,
+        None,
+        snapshot_path,
+        metadata_unavailable = info is None,
+    )
+
+
+def _gguf_variant_target_plan(
+    repo_id: str, variant: str, hf_token: str | None
+) -> GgufVariantPlan | None:
+    try:
+        info = _model_info_with_retry(repo_id, hf_token)
+    except Exception as e:
+        print(
+            f"metadata unavailable, cannot resolve GGUF variant '{variant}' "
+            f"for {repo_id} ({type(e).__name__}: {e})",
+            file = sys.stderr,
+        )
+        raise RuntimeError(
+            f"Metadata unavailable while resolving GGUF variant '{variant}' " f"for {repo_id}"
+        ) from e
+    return build_gguf_variant_plans(list(info.siblings)).get(variant.lower())
+
+
+def _download_gguf_variant(repo_id: str, variant: str, hf_token: str | None, mode: str) -> None:
+    from huggingface_hub import snapshot_download
+    from hub.utils.download_registry import prepare_cache_for_transport
+    from hub.utils.hf_cache_state import has_active_incomplete_blobs
+    from hub.utils import download_manifest
+
+    metadata_unavailable = False
+    try:
+        plan = _gguf_variant_target_plan(repo_id, variant, hf_token)
+    except RuntimeError:
+        plan = None
+        metadata_unavailable = True
+
+    if not metadata_unavailable:
+        if plan is None:
+            print(
+                f"No GGUF shards matching variant '{variant}' in {repo_id}",
+                file = sys.stderr,
+            )
+            sys.exit(1)
+        targets = list(plan.target_filenames)
+        expected_files = list(plan.expected_files)
+        main_blob_hashes = plan.main_hashes
+        companion_blob_hashes = plan.companion_hashes
+        download_manifest.write_manifest(
+            "model",
+            repo_id,
+            variant,
+            expected_files,
+            mode,
+        )
+    else:
+        # Metadata unreachable (offline / gated / private). Resume the exact
+        # shards the original attempt recorded so snapshot_download can range
+        # over the surviving .incomplete blobs without a model_info call.
+        manifest = download_manifest.read_manifest("model", repo_id, variant)
+        if manifest is None or not manifest.expected_files:
+            print(
+                f"Metadata unavailable and no manifest to resume GGUF "
+                f"variant '{variant}' for {repo_id}",
+                file = sys.stderr,
+            )
+            sys.exit(1)
+        plan = plan_from_expected_files(variant, manifest.expected_files)
+        targets = list(plan.target_filenames)
+        expected_files = list(plan.expected_files)
+        download_manifest.write_manifest(
+            "model",
+            repo_id,
+            variant,
+            expected_files,
+            mode,
+        )
+        main_blob_hashes = plan.main_hashes
+        companion_blob_hashes = plan.companion_hashes
+        print(
+            f"Metadata unavailable; resuming GGUF variant '{variant}' for "
+            f"{repo_id} from the existing manifest.",
+            file = sys.stderr,
+        )
+
+    download_manifest.clear_cancel_marker("model", repo_id, variant)
+    purge_blob_hashes = main_blob_hashes
+    if not main_blob_hashes:
+        if has_active_incomplete_blobs("model", repo_id):
+            print(
+                f"GGUF variant '{variant}' for {repo_id} has partial cache state "
+                "but no resolvable blob hashes; delete the partial download or "
+                "retry when metadata is available.",
+                file = sys.stderr,
+            )
+            sys.exit(1)
+        purge_blob_hashes = frozenset()
+        print(
+            f"GGUF variant '{variant}' for {repo_id} has no resolvable blob "
+            "hashes; starting without partial cache reuse.",
+            file = sys.stderr,
+        )
+    # Main quant blobs are owned by this variant (variant-scoped marker). The
+    # shared vision companion (mmproj) is judged by a separate companion marker
+    # and never purged while a concurrent peer is writing it.
+    purged = prepare_cache_for_transport(
+        "model",
+        repo_id,
+        mode,
+        variant,
+        only_blob_hashes = purge_blob_hashes,
+        companion_blob_hashes = companion_blob_hashes,
+        protected_blob_hashes = _protected_blob_hashes(),
+    )
+    if purged:
+        print(
+            f"Purged {purged} untrusted partial blob(s) for {repo_id} "
+            f"before starting {mode} download.",
+            file = sys.stderr,
+        )
+    _preflight_disk_space("model", repo_id, expected_files)
+    snapshot_path = snapshot_download(
+        repo_id = repo_id,
+        token = _hf_token_arg(hf_token),
+        allow_patterns = targets,
+        max_workers = 1,
+    )
+    _verify_completed_download(
+        "model",
+        repo_id,
+        variant,
+        snapshot_path,
+        metadata_unavailable = metadata_unavailable,
+    )
+
+
+def _download_dataset(repo_id: str, hf_token: str | None, mode: str) -> None:
+    from huggingface_hub import snapshot_download
+    from hub.utils.download_registry import prepare_cache_for_transport
+    from hub.utils import download_manifest
+
+    try:
+        info = _dataset_info_with_retry(repo_id, hf_token)
+    except Exception as e:
+        print(
+            f"dataset metadata unavailable, downloading full dataset for {repo_id} "
+            f"({type(e).__name__}: {e})",
+            file = sys.stderr,
+        )
+        info = None
+    # Cancel-marker clear and manifest write run on every transport. See
+    # _download_snapshot for why per-file size verification is valid under XET.
+    download_manifest.clear_cancel_marker("dataset", repo_id, None)
+    if info is not None:
+        expected_files = _dataset_expected_files(info)
+        download_manifest.write_manifest(
+            "dataset",
+            repo_id,
+            None,
+            expected_files,
+            mode,
+        )
+    else:
+        expected_files = []
+    purged = prepare_cache_for_transport("dataset", repo_id, mode)
+    if purged:
+        print(
+            f"Purged {purged} untrusted partial blob(s) for {repo_id} "
+            f"before starting {mode} download.",
+            file = sys.stderr,
+        )
+    _preflight_disk_space("dataset", repo_id, expected_files)
+    snapshot_path = snapshot_download(
+        repo_id = repo_id,
+        token = _hf_token_arg(hf_token),
+        repo_type = "dataset",
+        max_workers = 1,
+    )
+    if info is None:
+        _recover_manifest_after_download(
+            "dataset",
+            repo_id,
+            snapshot_path,
+            mode,
+            fetch_info = lambda: _dataset_info_with_retry(repo_id, hf_token),
+            expected_files_from_info = _dataset_expected_files,
+            label = "dataset ",
+        )
+    _verify_completed_download(
+        "dataset",
+        repo_id,
+        None,
+        snapshot_path,
+        metadata_unavailable = info is None,
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description = "HuggingFace Hub download worker")
+    parser.add_argument("--repo-id", required = True)
+    parser.add_argument("--variant", default = None)
+    parser.add_argument("--dataset", action = "store_true")
+    parser.add_argument("--transport", choices = ("http", "xet"), default = "http")
+    parser.add_argument("--parent-pid", type = int, default = None)
+    args = parser.parse_args()
+
+    _install_signal_handlers()
+    _install_parent_death_watchdog(args.parent_pid)
+
+    hf_token = os.environ.get("HF_TOKEN") or None
+
+    try:
+        if args.dataset:
+            _download_dataset(args.repo_id, hf_token, args.transport)
+        elif args.variant:
+            _download_gguf_variant(args.repo_id, args.variant, hf_token, args.transport)
+        else:
+            _download_snapshot(args.repo_id, hf_token, args.transport)
+        sys.exit(0)
+    except SystemExit:
+        raise
+    except Exception as e:
+        # Surface a precise message so the UI doesn't show a generic "worker
+        # exited with code 1". huggingface_hub's consistency check recommends
+        # force_download=True to recover, which our "Restart" UI maps to a fresh
+        # start by purging the partial via prepare_cache_for_transport.
+        print(f"{type(e).__name__}: {e}", file = sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 104d557eea..a9f7004df7 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -8,6 +8,8 @@ Main FastAPI application for Unsloth UI Backend
 import os
 import sys
 from pathlib import Path as _Path
+import asyncio
+from dataclasses import asdict
 
 # Suppress C-level dependency warnings globally
 os.environ["PYTHONWARNINGS"] = "ignore"
@@ -217,6 +219,16 @@ from routes import (
     training_history_router,
     training_router,
 )
+from hub.routes import (
+    inventory_router as hub_inventory_router,
+    datasets_router as hub_datasets_router,
+)
+from hub.schemas.downloads import TransportCapabilities
+from hub.utils.download_registry import (
+    get_download_transport_capabilities,
+    reap_orphan_workers as reap_hub_orphan_workers,
+    terminate_active_downloads as terminate_hub_downloads,
+)
 from routes.settings import router as settings_router
 from auth import storage
 from auth.authentication import get_current_subject
@@ -293,6 +305,9 @@ async def lifespan(app: FastAPI):
     # Detect hardware first — sets the DEVICE global used everywhere.
     detect_hardware()
 
+    # Reap download workers orphaned by a previous crash before new downloads start.
+    reap_hub_orphan_workers()
+
     # llama.cpp probes: capability (MTP support) + freshness (release age).
     # Both cached; freshness has a 24h disk TTL.
     try:
@@ -367,6 +382,7 @@ async def lifespan(app: FastAPI):
     else:
         app.state.bootstrap_password = storage.get_bootstrap_password()
     yield
+    await asyncio.to_thread(terminate_hub_downloads)
     _hw_module.DEVICE = None
     clear_unsloth_compiled_cache()
 
@@ -389,8 +405,8 @@ logger = LogConfig.setup_logging(
 app.add_middleware(LoggingMiddleware)
 
 
-# Citation favicons load from www.google.com/s2/favicons; *.gstatic.com is
-# kept for legacy web-search faviconV2 paths. All else is same-origin.
+# img/media-src allow any https origin so HF model-card assets render (mirrors
+# tauri.conf.json); scripts/frames/connect-src stay same-origin + HF.
 from starlette.middleware.base import BaseHTTPMiddleware  # noqa: E402
 from starlette.requests import Request as _StarletteRequest  # noqa: E402
 
@@ -435,9 +451,8 @@ def _build_csp(script_nonce: "str | None" = None) -> str:
 
     return (
         "default-src 'self'; "
-        "img-src 'self' data: blob: https://t0.gstatic.com "
-        "https://t1.gstatic.com https://t2.gstatic.com "
-        "https://t3.gstatic.com https://www.google.com; "
+        "img-src 'self' data: blob: https:; "
+        "media-src 'self' data: blob: https:; "
         f"connect-src {connect_src}; "
         "style-src 'self' 'unsafe-inline'; "
         f"{script_src}; "
@@ -491,6 +506,7 @@ _BODY_PROTECTED_PREFIXES = (
     "/api/inference",
     "/api/data-recipe",
     "/api/datasets",
+    "/api/hub",
     "/api/chat",
     "/api/settings",
     "/api/train",
@@ -714,6 +730,8 @@ app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
 app.include_router(export_router, prefix = "/api/export", tags = ["export"])
 app.include_router(training_history_router, prefix = "/api/train", tags = ["training-history"])
+app.include_router(hub_inventory_router, prefix = "/api/hub", tags = ["hub"])
+app.include_router(hub_datasets_router, prefix = "/api/hub/datasets", tags = ["hub"])
 
 
 # ============ Health and System Endpoints ============
@@ -781,6 +799,14 @@ def studio_update_status(_current_subject: str = Depends(get_current_subject)):
     return get_studio_update_status(UNSLOTH_VERSION)
 
 
+@app.get(
+    "/api/studio/download-transport-capabilities",
+    response_model = TransportCapabilities,
+)
+def studio_download_transport_capabilities(_current_subject: str = Depends(get_current_subject)):
+    return asdict(get_download_transport_capabilities())
+
+
 @app.post("/api/shutdown")
 async def shutdown_server(request: Request, current_subject: str = Depends(get_current_subject)):
     """Gracefully shut down the Unsloth Studio server.
@@ -788,7 +814,6 @@ async def shutdown_server(request: Request, current_subject: str = Depends(get_c
     Called by the frontend quit dialog so users can stop the server from the UI
     without the CLI or killing the process manually.
     """
-    import asyncio
 
     async def _delayed_shutdown():
         await asyncio.sleep(0.2)  # Let the HTTP response return first
diff --git a/studio/backend/tests/test_middleware.py b/studio/backend/tests/test_middleware.py
index 16a7bbc46d..1005431926 100644
--- a/studio/backend/tests/test_middleware.py
+++ b/studio/backend/tests/test_middleware.py
@@ -276,25 +276,22 @@ class TestSecurityHeadersMiddleware:
         nonced = main_module._build_csp("XYZ")
         assert "script-src 'self' 'nonce-XYZ';" in nonced
 
-    def test_img_src_allows_google_favicons(self, main_module):
-        # sources.tsx fetches https://www.google.com/s2/favicons?... ; without
-        # this allowlist entry, citation favicons fall back to gray initials.
+    def test_img_and_media_allow_https_sources(self, main_module):
+        # Model-card READMEs and citation favicons pull images/media from many
+        # https origins (HF LFS/XET CDNs, shields/badge hosts, GitHub-hosted
+        # assets, audio/video samples). img-src/media-src allow any https source
+        # so they render; this mirrors the desktop CSP in tauri.conf.json.
         csp = main_module._build_csp()
-        img_directive = next(
-            chunk.strip() for chunk in csp.split(";") if chunk.strip().startswith("img-src ")
-        )
-        # Tokenise and compare with `==` so CodeQL's URL-substring rule
-        # doesn't read directive-string `in` membership as URL sanitisation.
-        img_sources = img_directive.split()
-        assert any(src == "https://www.google.com" for src in img_sources)
-        # Pre-existing favicon CDNs stay allowed.
-        for host in (
-            "https://t0.gstatic.com",
-            "https://t1.gstatic.com",
-            "https://t2.gstatic.com",
-            "https://t3.gstatic.com",
-        ):
-            assert any(src == host for src in img_sources)
+        directives = {
+            chunk.strip().split()[0]: chunk.strip().split()
+            for chunk in csp.split(";")
+            if chunk.strip()
+        }
+        for name in ("img-src", "media-src"):
+            assert name in directives, f"missing {name} directive"
+            # Tokenise and compare with `==` so CodeQL's URL-substring rule does
+            # not read directive-string `in` membership as URL sanitisation.
+            assert any(src == "https:" for src in directives[name])
 
 
 # /api/health auth gate
diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index f36f2d8e79..7d1283e94d 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -31,6 +31,7 @@
         "@tailwindcss/vite": "^4.2.2",
         "@tanstack/react-router": "1.169.2",
         "@tanstack/react-table": "^8.21.3",
+        "@tanstack/react-virtual": "3.13.25",
         "@tauri-apps/api": "^2.10.1",
         "@tauri-apps/plugin-clipboard-manager": "^2.3.2",
         "@tauri-apps/plugin-notification": "^2.3.3",
@@ -6112,6 +6113,23 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/@tanstack/react-virtual": {
+      "version": "3.13.25",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-virtual/-/react-virtual-3.13.25.tgz",
+      "integrity": "sha512-bmNoqMu6gcAW9JGrKVB0Q1tN1i5RONZF8r1fW0bbE4Oyf3DwEGnzzQJ2OW+Ozg1P4s8PyugkHg2ULZoFQN+cqw==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/virtual-core": "3.15.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/@tanstack/router-core": {
       "version": "1.169.2",
       "resolved": "https://registry.npmjs.org/@tanstack/router-core/-/router-core-1.169.2.tgz",
@@ -6154,6 +6172,16 @@
         "url": "https://github.com/sponsors/tannerlinsley"
       }
     },
+    "node_modules/@tanstack/virtual-core": {
+      "version": "3.15.0",
+      "resolved": "https://registry.npmjs.org/@tanstack/virtual-core/-/virtual-core-3.15.0.tgz",
+      "integrity": "sha512-0AwPGx0I8QxPYjAxShT/+z+ZOe9u8mW5rsXvivCTjRfRmz9a43+3mRyi4wwlyoUqOC56q/jatKa0Bh9M99BEHQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
     "node_modules/@tauri-apps/api": {
       "version": "2.11.0",
       "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.11.0.tgz",
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 5ba0db143f..8537b0c076 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -40,6 +40,7 @@
     "@tailwindcss/vite": "^4.2.2",
     "@tanstack/react-router": "1.169.2",
     "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "3.13.25",
     "@tauri-apps/api": "^2.10.1",
     "@tauri-apps/plugin-clipboard-manager": "^2.3.2",
     "@tauri-apps/plugin-notification": "^2.3.3",
diff --git a/studio/frontend/public/hub/profile/logo/anthropic.svg b/studio/frontend/public/hub/profile/logo/anthropic.svg
new file mode 100644
index 0000000000..7545cc8f3e
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/anthropic.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="900" viewBox="0 0 900 900">
+<g>
+<path d="M 222.16 664.50 L 212.35 691.50 L 206.42 691.53 C163.39,691.75 102.00,690.80 102.00,689.92 C102.00,689.34 103.32,685.63 104.94,681.68 C106.56,677.73 124.74,632.20 145.34,580.50 C165.94,528.80 205.07,430.70 232.29,362.50 C259.51,294.30 284.65,231.20 288.14,222.28 L 294.50 206.05 L 404.68 206.00 L 405.94 208.75 C407.23,211.56 413.90,227.98 437.50,286.50 C444.82,304.65 453.36,325.80 456.49,333.50 C459.61,341.20 475.70,381.02 492.24,422.00 C508.78,462.98 528.13,510.90 535.25,528.50 C542.36,546.10 553.72,574.22 560.48,591.00 C567.25,607.78 575.81,628.92 579.50,638.00 C585.05,651.65 598.92,686.11 600.73,690.76 C601.12,691.76 590.44,691.97 547.95,691.76 L 494.69 691.50 L 489.31 678.00 C486.35,670.58 481.94,659.33 479.52,653.00 C477.10,646.67 471.91,633.17 468.00,623.00 C464.08,612.83 459.67,601.24 458.19,597.25 L 455.51 590.00 L 249.31 590.00 L 245.56 600.25 C237.09,623.44 231.46,638.87 222.16,664.50 ZM 798.00 691.05 C798.00,691.64 777.31,692.00 743.50,692.00 C703.78,692.00 689.00,691.69 689.00,690.87 C689.00,690.26 685.87,681.82 682.04,672.12 C678.21,662.43 670.76,643.47 665.49,630.00 C660.21,616.53 652.36,596.50 648.03,585.50 C638.84,562.16 624.19,524.76 620.02,514.00 C615.63,502.69 600.65,464.57 593.49,446.50 C590.00,437.70 582.57,418.80 576.98,404.50 C562.77,368.16 549.76,334.97 543.27,318.50 C540.24,310.80 536.29,300.67 534.50,296.00 C532.71,291.33 526.45,275.35 520.59,260.50 C514.73,245.65 507.70,227.83 504.97,220.91 C502.23,213.98 500.00,207.85 500.00,207.29 C500.00,204.88 522.83,204.39 576.12,205.66 L 603.75 206.32 L 624.52 257.91 C635.94,286.28 646.96,313.77 649.01,319.00 C651.05,324.23 663.76,355.95 677.26,389.50 C699.90,445.80 737.77,540.07 780.62,646.80 C790.18,670.61 798.00,690.53 798.00,691.05 ZM 285.33 500.42 C285.62,501.18 305.07,501.42 351.82,501.24 L 417.90 500.97 L 415.37 494.24 C413.98,490.53 410.81,482.33 408.32,476.00 C405.83,469.67 403.42,463.38 402.98,462.00 C402.53,460.62 398.95,451.17 395.03,441.00 C391.11,430.83 384.57,413.73 380.50,403.00 C376.42,392.27 369.89,375.17 365.97,365.00 C362.05,354.83 357.46,342.77 355.77,338.20 C354.08,333.64 352.38,330.26 352.00,330.70 C351.61,331.14 347.21,341.85 342.21,354.50 C333.07,377.64 317.55,416.89 296.36,470.42 C290.06,486.32 285.10,499.82 285.33,500.42 Z" fill="rgb(37,37,36)"/>
+<path d="M 0.00 450.00 L 0.00 0.00 L 450.00 0.00 L 900.00 0.00 L 900.00 450.00 L 900.00 900.00 L 450.00 900.00 L 0.00 900.00 L 0.00 450.00 ZM 222.16 664.50 C231.46,638.87 237.09,623.44 245.56,600.25 L 249.31 590.00 L 352.41 590.00 L 455.51 590.00 L 458.19 597.25 C459.67,601.24 464.08,612.83 468.00,623.00 C471.91,633.17 477.10,646.67 479.52,653.00 C481.94,659.33 486.35,670.58 489.31,678.00 L 494.69 691.50 L 547.95 691.76 C590.44,691.97 601.12,691.76 600.73,690.76 C598.92,686.11 585.05,651.65 579.50,638.00 C575.81,628.92 567.25,607.78 560.48,591.00 C553.72,574.22 542.36,546.10 535.25,528.50 C528.13,510.90 508.78,462.98 492.24,422.00 C475.70,381.02 459.61,341.20 456.49,333.50 C453.36,325.80 444.82,304.65 437.50,286.50 C413.90,227.98 407.23,211.56 405.94,208.75 L 404.68 206.00 L 349.59 206.03 L 294.50 206.05 L 288.14 222.28 C284.65,231.20 259.51,294.30 232.29,362.50 C205.07,430.70 165.94,528.80 145.34,580.50 C124.74,632.20 106.56,677.73 104.94,681.68 C103.32,685.63 102.00,689.34 102.00,689.92 C102.00,690.80 163.39,691.75 206.42,691.53 L 212.35 691.50 L 222.16 664.50 ZM 798.00 691.05 C798.00,690.53 790.18,670.61 780.62,646.80 C737.77,540.07 699.90,445.80 677.26,389.50 C663.76,355.95 651.05,324.23 649.01,319.00 C646.96,313.77 635.94,286.28 624.52,257.91 L 603.75 206.32 L 576.12 205.66 C522.83,204.39 500.00,204.88 500.00,207.29 C500.00,207.85 502.23,213.98 504.97,220.91 C507.70,227.83 514.73,245.65 520.59,260.50 C526.45,275.35 532.71,291.33 534.50,296.00 C536.29,300.67 540.24,310.80 543.27,318.50 C549.76,334.97 562.77,368.16 576.98,404.50 C582.57,418.80 590.00,437.70 593.49,446.50 C600.65,464.57 615.63,502.69 620.02,514.00 C624.19,524.76 638.84,562.16 648.03,585.50 C652.36,596.50 660.21,616.53 665.49,630.00 C670.76,643.47 678.21,662.43 682.04,672.12 C685.87,681.82 689.00,690.26 689.00,690.87 C689.00,691.69 703.78,692.00 743.50,692.00 C777.31,692.00 798.00,691.64 798.00,691.05 ZM 285.33 500.42 C285.10,499.82 290.06,486.32 296.36,470.42 C317.55,416.89 333.07,377.64 342.21,354.50 C347.21,341.85 351.61,331.14 352.00,330.70 C352.38,330.26 354.08,333.64 355.77,338.20 C357.46,342.77 362.05,354.83 365.97,365.00 C369.89,375.17 376.42,392.27 380.50,403.00 C384.57,413.73 391.11,430.83 395.03,441.00 C398.95,451.17 402.53,460.62 402.98,462.00 C403.42,463.38 405.83,469.67 408.32,476.00 C410.81,482.33 413.98,490.53 415.37,494.24 L 417.90 500.97 L 351.82 501.24 C305.07,501.42 285.62,501.18 285.33,500.42 Z" fill="rgb(209,155,118)"/>
+</g>
+</svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/cohere.png b/studio/frontend/public/hub/profile/logo/cohere.png
new file mode 100644
index 0000000000000000000000000000000000000000..99eabbb54f1a8c77ace998d22a98bd28fb2e5ddd
GIT binary patch
literal 5122
zcmaJ_c{r5)*PjhDwz*M^ee6qNM3zcs#x{0?Y*D7gQnK_|E3-0)GEY)M5h95QQOHtB
z(Ly5G*C_kGjPXwI`+NWW-PbvvvwhCF&h@>%f86(-<m6x_#4p7U0)d3A3Fgiq5QO?y
z;ZSbosF<+`*SI>_xmwr-h8cO-{ibDc(a6)T>*g32jXmvy&YkCGI&Y43-Wc19^8D-k
zzwAYN{70fZ_Wn;IJw}+d+%7JMOO7F1g1Pf0!<`*mK%ZrQW30%oK=CgftJI4hN@hM+
z`%!M@<bR$=MQ}-oP=e<_AdrCAUj>6Qvr!<Bn2xnM&Ncey-2F>wSpzpM0)u}3Xw|8|
zcO+qN&-B?*M>WIZaM82STQ_^2WM*b=VO$C}(yMA<pAT{8{ny8X`Fwy}&S+d-3UST5
z)8|?<*wDDJ5fYLG68ll#FgLt#!Th@8fd#YZw)qH^p@>=w2bW~Ik6CwXHe{<8MP6(?
zN$|e&BtCI*A$}p&aqy&9+``e@>k*Uri$wUlS>E)J^XuI>o1Ac+R;m2sB>&m^{rSf~
z=8g;`Y~QwHXsgr?uH1F+PSPM#VH)HzmFY(!3+iNo6DHJ>oH<9hw>|y-mDyGGv?}%{
z^jktPd87iVWNI55oxr9l8l7FFv(@SJ3cY3l3#am(=W9*EdTiPk1G|mGL(G}i=zgYc
zy-wnbQLRa&c^{F3y&d&Y-q%8%qW)FT+lR#bz-cOmM6s)#(DTr1n&kz%dDst2$c<!3
zSmTJ^4HDaomO=rtgC|jYPUv<+xI@TULJo9;_T#jN8IAu9YW7))5wHukgzb{d6LY{y
zbPfvYNul=Y0=v4rd8VORyodI9gwKAJH@eg^ovNC`X}Tyj#c47*IsXi8bR)lpy~6O7
z`Lt_7*ajd0tb?>^q<JhHEJ(1_g<;U15QH!G&~**nCbS1c7mfDf0swn<1_i=(!7FLd
zP7M|qP_{)Q(ARJuK=9^f%M2JmpCAe%1PQ9T`o3^FNnZ$Mo`#ab5Pkwu81_5nSE|A#
zX*`sPt`#Ej3EncvP{IOp&9hY8bG~sbwu%dAxL>Cc0Kes_FASrP9M6!2!<s8yW#Eat
zy5<<P<Xa~YE*xF}qE7$>FsxI71%cx*2yQ&hjpNX@!rEKz@mx~~q8A8|ATXi?o|}Ft
z@Q@n|O$qWAHp`;p!taF1;28nJZ?e$ndvAcht{E>h&sb0#rp%MbLqki#&fu`lR1fYR
ze4c-?1USgu;{;qBMxW4(6Bf*a6hIjTpqVDLCiVy>k)I_jh+C9l{-+QiQ24jn2W314
z#YhXA^R%gmb2%HG3UE0kpoRJvgdkyEsc{$phIB@d(1ZsQVl7zKHH{<@?)hD9E}(M9
zI%DDVVWt8Pj0ipi!LyF>or7^*Q8P2ZI}R{2V|mAo;LwDrud`firDpg7_M}BL`U1U=
zfd!7Wy@xR#BU%~MzW`E2{eVFe>-X95LvhRTfHR6E1GXliLxqKct*~dXfGjt{uHG<$
z!EwtgU*A#z<wn~$kOG0@iZRxQGcj-=j`BF&0#1k=Nudx}vrR!`*ea+J7JgYnzr+{L
zwo%=zM#BMREjahU1?V7LH$7CCJInux2)a!i3xntJ0ARW=F9U?D1u0@#*`WW;U&aDj
zR5(EI7KMTFzyL%E8_l#&0x4uPLMIfZCS<wOKERnZW7r<r;wcQQSOs(1k~$+CoeWZt
z<?HCJz;=VV*C!=+3$F=R<1T3~h7yM0qCw{*1(C~c+RE6-Fti``$2;0%utE|OeFrNB
zqnCp%spw~>bS%K{3y0un94@$0CNPWcyXnaSEE!(qwFDtv;x37S3+BAxH3L5Gl{e?&
zDfRadq`6%k0~Dv(&t!KLKVmra;?E3H0;0GiVAYA1YQ(_kRlB|tkdkX4UJ1yN_ojIP
z@Iy0tM16RXjvy^JclQ>I-n7h62HbWwd9BgMoH#>z*6=eK9CH%<+_qS}0&7`K04LZd
zZ-N@QhrEIrbVtB+!%x#u9w*3kb|S03Ow%hEBN@(gv)p9Or*0h5l6<an#ElEeI$fa|
zj>~i*@U!LdNu%JhL`bv!e2Nf`yq$*)f`5{bhG>___XAJ3x~OG(3pHUS3T?KUwG(Bq
z)oE0&(ijJ9&}dT|^m0Co9<@b;2rUeJJcv-IwWW%}Pfc1Ol-Ie1vs+>N7)z7tyfW>n
z-vYAvLK3KFw?@rE<;-<QLRa4;WK1^*Pb45ot701p`lR&y95HUy^(MKlLu}RzwF`$f
z_f1=gsjlTC7&YBUHM<3sn@pW6&n|9>Sc%nPctz_rnFpCew&IM1^MY~vV|A9#3Qi1A
z^?_l5oItc?T!*9*e&Jmr=(WWE*%~)>)==_(Uh!ac*4NZ=Y*RGA=gf9Oht4EG`l55O
z=m;FGK>KMtc$@~Y_L*+kXL?<pe?k`d;_|>N5Wn(e2RzN&U&PpdfZHW=fOR1Dx;zcN
zW6&EW=oS|%?U&Iec>uD{lozMU)$8(KnHuCO(slU}rq7R|LtolOck6tT3Hut^9@&n)
z?USKKZ*z>iwR^wKc<(bl6*pFsvOM2X$5wo08tOjQmm}P;zxhP+@Dgrj*ID%0ue<`d
zGy9apaKw{!GI8`@MZ(h6J7eKVI{!#K%p%ucRa(h%jMZ^{J>1&jGO8jr;KZK7$o!K0
zzR>`Puad40o9)H@vh|K*q#ntb-ch``zi~`TVj}cNS3*StC9ol(R$qeee7T)1{bH<p
ze(l>6M%kD7L<=_U50Z<_ypeo2m4ytS_e34ObDy0ZIX3rT;X>QbAqrtJ1r}4yetq$%
zg@&-O^5*A~NzIgm(+IEdw-@cnf25E#mAQuzWp3;;B98=L-)gYq(n-_HWE9`akyz9K
zYby{VcghL}Js(<q)RZ(n`T|*^%?P;|`(Z2kh<SSUb3viPvg3za-~35$@juqEw6*{0
ziPkq^BK3TFN42E9pRE_`$&uBX7aBa+p%IN^CF#Fx^_z{`j|GP6cx<~}EA=j2+WhU*
z-g{tf(jgZJUN0e=)z_Na%3SY|EV&+9d3xh+Ww$i)%c%)>5$y%rq4m0S(}}2h%Vh8S
z<j{+_{X+u7zfA{;4|F=!9}FzIYhLT`@Y)zsAse*bTJi<hHcTD&H#NIHSMc&*w6r^o
zehJPW86d;Myl?|S$1e;yELMIJzrp7=aoT2JK2rWn{Ys?&3hoE{{Vs*GIowETbKo$l
z-yJS&-rpz5Mt<B9O&e|LExJMKkG}S>DZ8;);kvEejW_?AmWV9B<zB(66YMfwq7%9m
z%0pi|>as6!sr)In9`iSpAIB+PYL1r4Q_^O?)0LZzSI}FdOV{XHOCe7;+}*)mdTsdX
z(a4uC(^hEvwG{z3)D|gz@W?Q9`%Pl`QaV%DsbJ?6aVScu#o^|BJ8JsCm4`c0GSK$=
z-@#`6`Vl^<QS*DH!9PcPqS7ncAL!kxJj{FNgrWYh`G(c+^&ZK8Ne)|;w|S=qOC{wW
zy`0fu@_fs=r<xsQX5uiZjsLW*bmc`?T*+(6oJZe(-VBqs%naqww~q@vv=r(h+v|@$
zzj`7zC!)M%cllP=YR}P>O5#T5M|2$$8W#RNWhJjr@YZYdwfDv6Pp7VYd(0a7cge91
z>1j!}QBLGk?XaGov>{6=d*o_Q9zRFiO0orZq$3&&jqBDnuPYRBDv(=U^1|bq-6m_P
z>Xx}X{2QdzqF1n~xmr~->%B)XjyI<@z4*YY6=I(zWiQN(a=XcK<z%X;zVVix%Hros
z`_5DwWapbUs5lkumJKjpnnu%)&8+W?6I6e3KCT@pkcuz<2ZDVsZ!>KfCN2-tZ6eMQ
zJ1`e=-+-)gqG)qQh0m~p1lKE4J{LNN^ZYV4DAlUE=k;#R9AJT+E{f*cP?9xRFs~9J
zVqs(0tR%>%j}<8+tImQs{lR<WaPBO&SnVqamp+t|&&Sh6Jw3!cnBPe5wzhyqitt3*
ztQoGHLh(JV;&adU@-rb$@>=>MKVNKs$edK1o`?<AyHNO^ru@JHnIEhvL+J7hFY>1R
zBl)i=U*2W;?9|_ZMs(|1KErJuqjpq=QugB|)jtMaxp^Q}skg4GtA;%)JeW`D!U~0^
z-c+atRWqT9T!ps)+l9hAK20y2P_qNO8p8}CVVjv^+9EevmCN-C8hghA?x2aI)^46B
zMMsS47at$Q<+Y?eC0AK+8!yOaOMe>{I3A~mx}klpT(zml79FA(7_KnIKeD32612=0
zsBj16Xwy7^_&R{Wv)Cuvrt;cSI;aA4+!GSB-}<4DfhQ>E0PQL5@XwJfd+>1=2m*XJ
zH@q4aGoxaUZ+g6-TrORD>l@9bjU-hGnVo4uOkmPIcW)e)Gos1(l^<yOU;rzf7V{1C
zptxLuYlL@4r4M_GkC;oh$a#=N2Q$Tet>9;mC4IL46XJzbjq~KMk&X63`oUal`2%kV
zl%IvA+;Mca9pBFCW=Mk95arLcn<^$^M*^ZHk7Y>szJmvNQmbRYLmn_`ao^xm6tU0F
zo-nJ3Uzq!`;Nx;{M{uj$FC#2<|6O<_kB1t%Njjt;Yrii<X=L0Ct?H2jD%l4!Iz#`&
zU+##f8Ydf-K!VZ$-vq>qOsIi1e6iJvl)_(bho__tDWSz8Aa-vU$2NmydLI)958Ek1
zWRk%7pBUZ8MZi;Ushtzn94!&B+h5Pt`jR4K7Vy>I^72bd1YLy%xKJY$A@vpTB-O?g
zRw74kr%xG%s*aT|w6maUK~ls`zuYNOY+^Fl0ZZZv=`!0DC*Y8CVhJG6I5gHN%}h<H
zNd%mk0v16hwo+fi2!i?ZN?ULsT1^;iStIZN2S5|Z3P0U>CZsF}4VOjG<{xs3msGG0
z%UcFn+_zc{>p{M}*b~@O?XDXK4!?%AseSyu>y)hnUJewFFcqJ@$U8A^PVARhzJCH+
zCQ`NQ^iU7{oWFDZWb<bjL9{do79J^LFIqb1KUR-mp)r~}6{`bxK_5u2TJ*sNi4-9>
z@s{YFLl6TGPx$y;Kjw$;CD|W+y%n_yojtVsvGRaKUKw;}8?UKt?!&jfb|Zj^jgU3E
z_fJN)d{FgWeBI7{fPB#UyPVM@<ySGAG)c(!S(*z!q(33&t^!8$<y#xggc*7ADQ45-
zvDglI!7@9Hb?y@YBP)H3BubKf+D0!p!}x<hb`XE3@RVQkp+3?<;*oAuJl5~yS6$>X
z<esWAtj|ljpI`M&leE*+KKD}{kL;=7b?}$yvb%cbN_in9qXqckc-8lLfISZ;UZFg5
z^X)Z7OBZle4y?x|CnJ{22-s_2kuI+%2@zdEbI%wh9~@JJI$c4Z_;kN*;C=wIwyXu&
z;`Q$|W83>Af$T5p*m0BED`QE0O!FnZ4A*O+yWL7@ZwbR-)p15b(Sr<S)sJ%cqBINl
zFD8eq?QUO{(0ddcx-y~U0*NrkOf`P(G}&phquIzLUXpe;joo)s#O)hZtDn`sl4^%=
z{YDiEF+0^}ra@ai3as?AM$`TMWEIy`2i#X596}kie3UBxu3Q*9chC4bag-{Q(D^<2
zAHKjUe!iec{-D#beq8~bN~jf=kw1G<n?Rpz`P{+K4ASx=M7tWsud>PbC)nQOJt$yF
zXq0@%-%md8EU2nRr0iGBl+yp^=M5S&XYK{Ij3GuG^<w7K=*@_dL+GAs1e4)ocp2H=
zSfoi(dv|cF|I|TC8rYyGuHREWQ`cz-)PJF6tz%Cvg|_!~SodUVvnP~ez<Z0=h7V)9
zt1E>(YSe`--PQxF3<U-z&X{*kJMN-9bPfS$|GGOU53QB2*;egZSUVq;Ra+B%HxKLG
zZ})j$w3{5}@6I!QXIY>jaqU72N^9Gtr0Ghh`2!;-48?#H|0muMukLh%6aG5iRcrUF
z`eM-z<5=3{lp{qQQ%0toC(yo2A$`W;$FFP@6+&h%JSwuJIWJYtOL>&8ch8!~%_Z2V
zIhSsB`_Cpw-7e6LsQ&FDkwQ@q{lre)Y0CK-^6yOEtziMfKQ(b|{LXj$P{CCSbw6>C
z+<2heeuZ-#w^*|r)e+uRS0UdhNFVySSlm&iXaG0JQ~Hp!{OcM}k1&l4^W7LVN)-ue
zH03aUozso_q_^gJQKA|5jxhER{-m9wA1%T&`Q?Lhw2{A?hb~KUpYijmxkZgHf}N#j
z6S8c2&ldG3JbT|EKFP1<6;ZVC(y{G}z5M)%sfSyLt>Ued2V*o%9?M#brsaBW#U`Kg
zidx>8vb<%@gM9Jyy}PJ)E`LwMHYJ^Xn=bn@yAsy6bH(ou(JOj(Imn0Jt7sc9d34FC
zFJ^Y^!pqHcPn(Gv<Bz`IB(n&Yv(7Ju9`TzYHau=FG&Dv^^b|Jhf8X$7e38?vY9JZ9
zc_Sl_guME_6J+Cav>GrlJ5QF=aFBpLdZw-?F)_I4tMat}^+%VO-<4zdXyf}U9TG9$
zYd+;9lLiH60v7g=rRAb>Wx<-m?tz}CB77*)%omrkb|^w`N*7*f&g|*SC8yo=imvT#
z$Ui-2tfuq1=+D|^qo+D`?Q7vjB#bH0%~?ncnXUBBdtfhQa8I7N_+S5Maf=T|DVq0x
Uf{v*+9R5qSws0^n!~4?z2MkW@KmY&$

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/deepseek.svg b/studio/frontend/public/hub/profile/logo/deepseek.svg
new file mode 100644
index 0000000000..d1ba06b942
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/deepseek.svg
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_2" data-name="Layer 2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 377.1 277.86">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #4d6bfe;
+        stroke-width: 0px;
+      }
+    </style>
+  </defs>
+  <g id="Layer_1-2" data-name="Layer 1">
+    <path id="path" class="cls-1" d="M373.15,23.32c-4-1.95-5.72,1.77-8.06,3.66-.79.62-1.47,1.43-2.14,2.14-5.85,6.26-12.67,10.36-21.57,9.86-13.04-.71-24.16,3.38-33.99,13.37-2.09-12.31-9.04-19.66-19.6-24.38-5.54-2.45-11.13-4.9-14.99-10.23-2.71-3.78-3.44-8-4.81-12.16-.85-2.51-1.72-5.09-4.6-5.52-3.13-.5-4.36,2.14-5.58,4.34-4.93,8.99-6.82,18.92-6.65,28.97.43,22.58,9.97,40.56,28.89,53.37,2.16,1.46,2.71,2.95,2.03,5.09-1.29,4.4-2.82,8.68-4.19,13.09-.85,2.82-2.14,3.44-5.15,2.2-10.39-4.34-19.37-10.76-27.29-18.55-13.46-13.02-25.63-27.41-40.81-38.67-3.57-2.64-7.12-5.09-10.81-7.41-15.49-15.07,2.03-27.45,6.08-28.9,4.25-1.52,1.47-6.79-12.23-6.73-13.69.06-26.24,4.65-42.21,10.76-2.34.93-4.79,1.61-7.32,2.14-14.5-2.73-29.55-3.35-45.29-1.58-29.62,3.32-53.28,17.34-70.68,41.28C1.29,88.2-3.63,120.88,2.39,155c6.33,35.91,24.64,65.68,52.8,88.94,29.18,24.1,62.8,35.91,101.15,33.65,23.29-1.33,49.23-4.46,78.48-29.24,7.38,3.66,15.12,5.12,27.97,6.23,9.89.93,19.41-.5,26.79-2.02,11.55-2.45,10.75-13.15,6.58-15.13-33.87-15.78-26.44-9.36-33.2-14.54,17.21-20.41,43.15-41.59,53.3-110.19.79-5.46.11-8.87,0-13.3-.06-2.67.54-3.72,3.61-4.03,8.48-.96,16.72-3.29,24.28-7.47,21.94-12,30.78-31.69,32.87-55.33.31-3.6-.06-7.35-3.86-9.24ZM181.96,235.97c-32.83-25.83-48.74-34.33-55.31-33.96-6.14.34-5.04,7.38-3.69,11.97,1.41,4.53,3.26,7.66,5.85,11.63,1.78,2.64,3.01,6.57-1.78,9.49-10.57,6.58-28.95-2.2-29.82-2.64-21.38-12.59-39.26-29.24-51.87-52.01-12.16-21.92-19.23-45.43-20.39-70.52-.31-6.08,1.47-8.22,7.49-9.3,7.92-1.46,16.11-1.77,24.03-.62,33.49,4.9,62.01,19.91,85.9,43.63,13.65,13.55,23.97,29.71,34.61,45.49,11.3,16.78,23.48,32.75,38.97,45.84,5.46,4.59,9.83,8.09,14,10.67-12.59,1.4-33.62,1.71-47.99-9.68ZM197.69,134.65c0-2.7,2.15-4.84,4.87-4.84.6,0,1.16.12,1.66.31.67.25,1.29.62,1.77,1.18.87.84,1.36,2.08,1.36,3.35,0,2.7-2.15,4.84-4.85,4.84s-4.81-2.14-4.81-4.84ZM246.55,159.77c-3.13,1.27-6.26,2.39-9.27,2.51-4.67.22-9.77-1.68-12.55-4-4.3-3.6-7.36-5.61-8.67-11.94-.54-2.7-.23-6.85.25-9.24,1.12-5.15-.12-8.44-3.74-11.44-2.96-2.45-6.7-3.1-10.82-3.1-1.54,0-2.95-.68-4-1.24-1.72-.87-3.13-3.01-1.78-5.64.43-.84,2.53-2.92,3.02-3.29,5.58-3.19,12.03-2.14,18,.25,5.54,2.26,9.71,6.42,15.72,12.28,6.16,7.1,7.26,9.09,10.76,14.39,2.76,4.19,5.29,8.47,7.01,13.37,1.04,3.04-.31,5.55-3.94,7.1Z"/>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/google.png b/studio/frontend/public/hub/profile/logo/google.png
new file mode 100644
index 0000000000000000000000000000000000000000..01bb81206ed4e13aa9ba72392504a58f0d4f8ddd
GIT binary patch
literal 19507
zcmV)7K*zs{P)<h;3K|Lk000e1NJLTq007AV006`Y1^@s6HCP4P002w+Nkl<Zc-rl~
zd7NceS?~RQ*4|asb9zWZ<~d9;fEgr+0YsE5ctJtNs~@k3;&2tm>wT~HRe04a=tXg4
z=9McBC@7$CMG+7|0TTv=Fl6Y=Lnqyx?yerH&R*-ee>~4xd!18No$jPNU0uCbQlG9m
z!#?|*vwr*c{GL%%RT<W>hPC7h!$&ZzVGSS|*02VU3~N{eNQO160VKm3)&P=W4Ql|&
zu!c2&WLU!*Kr*ah4Ql|&u!c2&WLU#G@~a&_f`@61MsVN&?B5Uj_Sw(;0hpTy5r2@t
z%rvZ84Qp1z>ecr9s#VYqU)2DT<9($ByLZ9Xo8Y=H!&k0Dw{C^I?u7gAhyDAJs33y2
z0h$IvfY6jfh=6txQbdx1CR7z9z?#*_rY&&VY3PL)Adh@BJod40_BpU=Qw6kP9qA=Q
z7Vv{yyY5G?y$1RC$Ixr8fm?5b`8im<2G*`MMhH#WypkLsi|l1_gygRx{|%b|Hvp;M
zmm(aPhrN4^oo1%dbIyUwuSBlC8Xo@ybjub7*bE?fc-Nji@X1f0fAc>0^rvChF4(vU
z)~`2KIOvC*fUqb)3=e{80;B>6j*1FA68hURnCcZ1?A`;jyU=wfAy2##zT-LYq^n@V
zNyB$IfaEBwJ8nn+;?LoI?}a;VhfSMd!v+Xqm-j>ckZu1j2@<L;FBOAifEaLs{ce9O
z1c~@LNpO6rJ!<zJ*nK~G`q{{HpMyT{JCQTbnta(|4Ip`dl|KRz^uBxHkKTd4>yHV$
zcEf3>qti2o1&W0%BIqKT!Qn7rc4e{<lB&5MC1e5_!&MDB=O9!C3I4k%qK!SbRoFj*
zyYGT6o6(p2CwS2dkS$wSc<^BjAgRG2f_5Ez@cr<6zm42-E1YpA%*^!QQF%}pQB8y;
z%&Zy^3jk7I<O_qy68sbFxBT27pw1?e5Sj{A!O2G8z#QCl7kcqU@RP4Zp8m~apUJRJ
zbdY3l?A!sr`C8=9{{&7x71nQ9(k4<p{Ec%kGfOJ1fjBU<2TQNkS#;BCVGjXOEaX+g
zt8yzZIJi6H1VkES`wnz=7J1o!Mt|t#$hvg{SWZ}wB!wX8^<PC^_49D;HE`~Q=8E-?
zK{YIDrXMayMAgkK4r*o<&sK81QQTOQ0I_FjZCXtV{eUCVf85mb1D9hYkrG8#wPU0p
z$lM5SzYU)G4CEL7A2{{Y0W2pBNHTML<%{q$KZe|P3!HtP-L9eRCn140ONwjNLr+kU
zRIHwZn^_WoR0;KZPs&1dogb4VpSn8|Dxi$fSAKpr!JK&f!6_)Bf{5CMAm4w}R`lwt
z;a7hNIrUVF1BEbvWaTl3eX)A;jmRrs2Djb{XPsk=Lgk@KjqmEbufjtzxx`hq%0l;%
zQ~)V|Cq<fodMri8z+sy=vy3W;8bkFu#mp@w*lQQFD*vS7^(qWi&QuW^(=RHhG|o}}
zu&p=4GrtA-)mOusH76vqgcS=8K=;nV4?G{9`xN`e&pNxZ&Fh^SmkjicZ}3CBo}_%N
z34kEu012TI+j&c86!qRJ>ad9er2poGK5?Qp;woo@gyLaSH3(>SBTM6P7a99pGz0AX
z3*aj^pig)*`a6GM0P)Xv0Lk%bSDD=u0=({*kZ-&Iw%>!CcYy`#CNJ#8+_x*gh}-Xy
zCN|ypmH*%@f-}gXygh!Ll>B(XapBi*k={@$U<>wpu=5lRl^NwqMXF;UMc8Y_K#Oo*
zG5fS=m*D5>k8fM#kryNH`#<Oto(!M;{Mf~4Ft?5y_J|M~^t1nryyAKAh%;e&6~w#=
z6O#3YR{Ou+IN8XL*$>++0u(8+zNK)mv{<i$hJH>tU?^b`HmF}G^!f#v0LUbu{Jn&V
z5o$K`4?t+`F{;(|vUe*;_LyaGOCSY-JMMyuE+D+)jW9iZXjhMcNsh57SA`hSS3Dbe
z<qOgCFS0lX>hCc6l`{4_S;q8iza7<u@Dfa7S9)ENMGi_aW7{x|Ik2>N*A_XFC2aLN
zB|ES3`AHv%w}&)n@Brol@(BLZRI)5ozA`}w2!Z6xY77%d*+Y27>9BV{>2Xg+|Mu@!
zya{%EGf8HTPkk8q@$ZBSF0qZ0{M%2`Z=9q+Q<)up$<MnqIRH}Qba410UUVTj*+sUB
zi7d(@QljjrLK7hA!VR2(Anp`MVeB>RwL<}t=(sM)dS?tg<^3g+G&Ci(#azV&(DcX6
zE;1#+z1!iOGYNn8Haqtf=m9%^L6TjPKl^<6+`qsh&Nd*Z*yd4s5CFuAHuCMY*+q3*
zHe+-tlWTFHENN;j$na$%wRd4mL{Z<Xp<;*xIfA|*f2{GKy3lLz@k{}c#txUpg_#B+
zq=1Ur>&m$B4+=?wxyWTaI%;@PxbbG>U2lg=AG_i_V8<Wq-MrFmcfhx7g1fiEX=hQn
zhumA`0y=+Jjk?JKN?a)1%f_uVfe7TsK7hAN4kGk*!snYsx+X;%@t9wAguKb41v#yz
zBr{<!osn6Rrq2s2@j@8`ut?+j1iOHQRD`{V5E69dv-9JNn_UtrMhPVMu4&}~QyO^W
zh3NPG5c;~`UvcKw@x>%L?(v~Ng4etPIsXz%508z1YuYo02MX00MJ5<!%-f^AxlfdF
z(O&Ym!jhN;IV4jnn^`ri#<Swbp=ODS!6WCbF^TxO6z1uLc@hXx1H{C+hUh}xSr!Ft
zh>g-#?<+Z=0|A1f$-yB~m$wviY|J4b#(rtfEY13L$ou}dWH<~Uc^LJFh6Z`n^Wh8s
zjBY-|D*dwd&`@cS+I*^RM~b&AN6@9-vniV`sRD-fw=ZUPX_X$L4+N4)4KiVwgy7oA
zUb}=yvT0R<h+*7ZlF(lSLT0K4G!}NStGhieHD+E#IwZ8cJaHx!nlUR>lBKN#!~v2f
z&c9ESDRHQqZzFv4y|D45<6ftP<Ap&K;CnBGTfPLRoQ9B$_JeOOQ8Z|8L|5ilNoPVU
zvrBp$jAegJCa;U<4#p+DR&o%Z@Z#5?KI|@abUXtjh(*AI2M#k@n#r%MKlw~9ea@u0
zm6cE~6r$<?QA<Y&P0=2r4kQPlQ28%%7C`xYJf`I4m}XWij|p)8`J^X53%>M~nsNt_
z932gk(7ik1yVfJ?)}b>qrW2&UK&nIwvIRv$s@|EptJMKCp-)Ux=!E4E`%AlYW9E#}
z&cZKSMVHVcvM8gdDzxL#_Zm!Em{I!_6%{joWDK2s08m{=NT@trzM1{vk(%HD3FUo>
zTG~shT)^sw(+~&}dVhyopPHmjTyd|No3;cqi&fz<k0HJ2N6-&`cws)yU~U}|bl7)r
z`*rA#U5cFlIOw98PT53?jeE0l7@;=1w3uP4ie$m7d9UZ=^!N8}-^yI8^@wWa{hBz}
z)NimuHMM$sDp}su0*{dAR1vBepA-fuf_*_cy&bEtP`NFDMhgfM2qL7U1PMgc{#GG)
zMwhsox38}cAa<^`4ja>AT01?w&&BQcpf7kf@^k-XV3H&2!2<p2KfzBu0lDZBU_=QH
zHaX)p*^UpD<>BJCj|F%<LXw#vN^go)6rx!amw?B3BH(y1L>IHUIP@gpG#*&N)AM!G
z)Jq0#adycuknAP%_cP|)l2CbR`}CA7uVM&@G^C^s*2YgodXJs7NWi>SrDnywXxdoT
za5h7OebzxkCahwfNl=uAG&hf2_PFDgNy4%OhzNY{ui@3-3Ku-u-LS4F#HqmJ0rt(L
z`T`3Qk!)U-h`V3uLqdb^m<G`PzA-##>b1H=#_BRAfTGI6T3o0+Sqq70+&fm|$IPk{
zdH0~91aleZ1E?l~+6L9y0iA0|#>5ttx67JNw4p_loukKDOYl-j?jh4EvR{=r*Io+$
zDv~5p2<8az3zX8r4O@{ny%wH+HOFf~eOR6V`Ahhn7b53f06KE^z{PnoU<B<!(b(Ub
zwMX#HmE#|cdt@Z`CPV(d+RQffcJiyFRxV752QgaRGOxfh2E0ij-!^qw{Q_`FNQeVj
z2}p=&tV?*a$R2;PxJc6+D^gec&K9Octk5NEw~*6LG<)#;&@}Ev6VG|eF%d5&%lbqb
zps@<a`U=npa^qHb%Woi0yu1qj3?O-E8bk!X@Lu%yUyPo8zI~w~Gl$v-FX}-;yUhf-
z^!ZDIZ2(a>1^OVOnO(7XVKgun3z49G0J0YIT2p{5FuP<Tc(|B=@1>t0NylnIG}nr_
zXHIF&VIjd-)S0CAxQU2+y0v_EISt;@QF0zubcdgTE@&{*G77X(1>Xa~9TS=YNGuFh
zJ5eON3dI^um~M$<rld3tTz?Dt=3hs?;j)an!Mk-tbo$pm0&jc)a@M&B^UexxQf0l-
z)R_^<&GepKq$DpYgwzYzMvK{{5)rBNNh^J91ey3`Qk9LKsw;REidkSYEs+2zvZ#yM
z-bxP~DWKM|v>1CGV@S=9&#qg|W~b|~v4CSLV6f8NhUD*GJkB9tqFp?YNcOJvjVwY4
zuIsdVFGlmKCiZDs(pR^lZ+<P|iC3@^dKN7YkZ6KCKL@XW2Apx8Z*W1HSOF#VU}>_s
zCD{p7K#?txBBCWasHD;-*=ePH^tiQJ6uUB}2~$e@ve@Dlb{jtfM<;4U#;&gQ<AcX_
zr25J2P6b>ml(<R0ziiA<T)UFAB4KgwRppIqgl;_5xd6h#Aq{=ffxC%wL>`aOyWld=
zRXVR!ei{21s|57=n~}FTKx9Q=WEr@CHKMck!2dWCIsJU-aMx{i?JAlYB)fi7pTMZm
z9w*VoN%ZKr21vo`)>9v?E-5Q1p(%Lbk~c%hxag#B<FmjmT)CNR)ve>T9TxQth<1kH
zQU>BFCbEbNd9n`OJxRqWp+b^ielS&Q+%TC|p94qUJ}3&bv|}cfI18zJ!AeUA5i})2
z2&7`tf#%wpT-Ga%<&#xHJ|Lt<;QE{4O|K<fb;Saw;J_pg0U)R%|KC~2+2@;W+r&zs
z<3YlTQ8Hr)?!ih`gkAc_;2NcN4+qaZ@#?-3c+4)+u`9n;k@^V}N@DLuRvGgmspmh5
z)Frrj5ce_T0n1#@Tl7k*He)iDlaM17)wu=J3!1?t6MHn3%`FlPPkwIMWDLRLB?YYc
zT%^sar372W^SQ(sD_nmwvH}5eY(b)(`QBf12ApvgFz*p_ppA&63MlkIX<VaZ)2aat
zvGRK56pmyfJZKT|y;sX4?wH7zk~paD?TX|1QFU2t-uyCN0A(f=^eG!UfjJ$Esf^#Y
z0H0$XD^)T)TvKV42Jct*{2p`sD4TZ0>@yIF_JK)p5aiS8lBckc%+yP@b2+<y-RmY|
zu5<~c>u)B#>9xoT1jw-iiS^w?|L7^m>gZ`Dz3|osXmwGb^zPr9Q7Yhw1F57TxyOp=
zpz@-l#z131v1I8PjZo)ziKOv*b*VRa<&m2ROfF_fExdJs-*@rNrG2$}pi0!NP^DS0
zPn0Bw<U&1Lg-!MGYaod_0L{c|Ln?0H&@@P65&6Z=SJY!JH`OMVuE^fP$7Vi>2z=((
zVB58@YCRHDZ_@`KQ=q|s(rMpcs-)`H_29|3PbD4_9+h|dKjkF8WQl$`4Lo3}_Bl{k
zf`SgB*r$LC6Gcv;F4F3AyRyzHPKBJt($vq>Di{|%r9AcB>HR#C<h1prUD0F2lVgu#
z?gAZ;lX~o@c3z9W5v^<HA4sY;VG#|oGV9zQe&MbW-SI`_%};<Wr<pYnlZ)|CiFQGw
z`TXhV)7q2Ym&X4lg<jZ47uV{k@hS9<fS5f;O`r3XT)by@t4F*AflkdVtZP!V(jv8x
zubVVvb87zxW_Q~hk?Co4{RTMsROIB%=!T83W(_js*Qx{a=)QfhYd7rJ4%>GkyZ4Y%
zhpb+UuG@gjOnGX2zw>h@uJ!P;3d4kWZAq0{@2!r4yTz?LYGVnB5=ic05DAEv51Wvu
zbaioGFx+?x`li<qo_P6+2FSw?675iF;dO#+KFtyq^F~I@vy?)=@wEa<)baZg6Mv5b
zMUx=8j5o@dSF8Xr(pUJ!th%eBtfZDiN$*zGoY<GUKW4z>l=r=Rt?ql{dU*WhaMd@#
z<(I)Z=h|?e<}k^->tNUYaQmI;wbvq_`V4&G-waGAp8{*GVVuyE+L4rV-*R47od}up
zibGYRoFnTc1*Mw4<xTdo8Ab?j!_Dx<*CJ0^nHuC6g2ct&pI?UTzopvHp|_f%EChlE
zzuiF+d#33bWx_pNGfE1*i?;?!IZl|Ujn|%qiaWV#NL>oLD!1+ZyI|)Ic*5oI{1>B7
ze+IH~)6xAn@3{v)_Hoj?{}R6ZRb-3JPEk*PCkd&s_aSvkNXf}+U6X}E1YHU=r45l=
zpfQx7EFtG&{W@HAe5aZ$Pmrj>jeiIq`C(YIw%^P#r?oe}=`jX~b*y9@7)0sWA+t@a
zSfU0(4CBWsrr07t$#oolKBf0U-Hai}L`EaH<rcW)Quv{tM6Z4tGBfjVdqC{G_V0%e
z{{#BQx5BM=7;CveNd*MGpDJiTL#{w{O_#I%k)Ab5OvlsgZ`z8!@wJ2}U3o$c|9N;o
zq7jXIkvE?Nn>R!B^3MVW#!GM$wz<pIzh()4d~C+eCY=CJ0ZKN@La#|Q*zu`=QUIeR
z7+K7y)c3Pu&tBMeH~QiqKz{V6VZ%no1{)p|Z(;9g(>v}!e)IQ8|L5<Jv(F(-o7R(@
zictI>6YLT~iQMa0UscyFH{Oc8`PYy8WW{9)5;wEnb1@R{>rE@qE0lbtk2PyJ7#8Rd
zsen;~MtW9?GQkivgER($C{^=_NdV?%5-#rDq)Pkt67IPNe)5;##V>=lIkvz!sC!*t
zc9!(I-$wuRFX6%qJbm35GX<eRybFrD<>+lx>!Cm1Zb+`b8Q$_b!c~`_kYgB*ew;)T
z-1<)Bz%9^r?&{Q%V`aa4?MBYYYW%0QcnOU^r<r_QvY#ACYZPrg5333|mSg5%V<Y3w
zD|uhq=Xi;~wnVt;I>Ph65B~Lb_)kCRjSXaZZkT*dYu6Hf=@)3O`A6ieGi>fikg?Wd
zQdM4x7qqKK<r6{*g5Izdd8-5D1Rbz=beTk>nJDiRSbvfMX3TAyg|Vk{q|lpL#q`oj
zi-d)YlEm}9`chtv*_5k2V4>F|6WT_#(jNKtwuP-Xz>}T{zx)=Mo;f}{6y`Qe*WZAC
z?<+`a*AmvO9jl5&)$+om3N*F>zP6R{w%7I9yeH@^pQCSXeexNw<C7llt#v}yBE6ZT
z2_(9S)4AR3W|-zg##n0-D&bBaYl-wO;G$Q;gsZr60Y~xUyC|QZhi&(uZ~aH){702`
zs>k*69$4vr{Vw{4?}Q64v{;C@5K5|q;5F|}3pd<^y!E$`6C5B%86=9%UXOh6QLt`J
z)u=(nn>R!k#L+bfGI8af&?RG<qjm*jn>^NxQUe8uZKY9y1I#mpqYbc;+qR<L{6gfv
zy<ug5V=-2_;YQ+jeh=aNb1g0+jR)d=Ov4Q~5#IWG!c|wE@BlgbO!D^^fNm?va+apf
zLZGB7Mp0kwbHuxtSE0Z9PXed7kH=X<lQTrDqT`(`1PU$O@Fn#1A3?tE8&~%DGk<U0
zb6$kZ9zfTxHgh!ydecobZ+Si8i3326vT%>+&X2)?t%d^WOKf|gtczy#ma>YvmVHd%
z3$#>OzZ9V_IW4{jb+7JgK*yR$_&GFo4ABnVc@O-}4&;)njCNM?e83POCffJE3!ZcZ
zY}*b^K(D{C0tf>@jvkY^>+tV3AX5>#+`YqHwD}<=qCMflRWDgBk#Ks!J(h<x;r6ZF
zz4@oB-OJ7@U3MXxrqS8m$jKL?zxFX?rI}X`cr8oN1kxY<8S$t72h9iml<*BJJ6Um=
zfFz;!{uO-og~-eleZ^o^TB^1AW%pU<o_?}y+4NPkTvI6ZPWkt7K|gMO8HlQ&W9QH7
zT&VBZj$Za3ksp0K#P0C(s#e1CxJtVHPQsa|4*+@CG|5NS!*n#;H&sJ)H1zJ)B>i`k
z+{Vhnz0TFrN_dw%E-F^3gm|2EExQLRHe(TYO$~D2HuPJ56nWvVp3vi$hxNeg2wyrA
zy5mE@ETS_WkoI~I5s02p7ra%uHkN4{d?2V#c*<qFL^YG3r8mE_l9CLhY&?5Ih8T*?
zUEZQ(v#+(t@{YUF|L_yYcl~ldh;&%PdbpTGKXDoocA5Ls<06_nZY0k@EqPP)CRZ7Y
z(6fL>FJki8h-LG-dpEh6RWgY~@Aj=VO7vvK1kwd`_x;FKFN5d3Zi%K0!y496V-khE
zpG8LZz|3?>n6vA=HD}AUNrLA`1#7b@In*1(X9?yxffais@!*$uQxNx7CGkeu#y(||
zL5!3--k_#K(jMe7-#h?hSjUb@^z&bj9JsD3PYuO;m76=~#8T4@jhRKlSi+$u?fX2X
zre~TQg-=z=N{)L(`pn|7z+;sxDVyPE{%z$235Rt&Fo{C91G)e6ux8rFh~?rQZ$TP;
zUPkF=4jMWO;zflfn&*jJJD03vw{&C%ZM|BM)U$*p>%bTqe+})~MEw3Rjqcipyy|vH
zofQuaYgiArxuti!8d=>IVC1I%B^|v{Z_e(GrPX27#L}))$PF6u{aMsoGX%*~X{p-t
z<g)V6S##-n;!GaKdDkuQ^LIO727nCfn1Dp!jyJ%xbsQ}1H*=?v9H+?9^L)imRSTbJ
zUM5ks+3YEr=@hcq$Fzla57C$zLkiPKj^uaMvG;6;@A-3N^{IpZe^|!~Bno>!?JYfX
zHw}sw5w-M_5(`mJA?d8mPN`3CauaB87F|kAb2VMADbFp0@W#;~DLDwm=8ZJo6hTMm
zS(hOfzknr&8V+k%4~KBquUw7n{Y>AxN~@M^sREOGsrtv{zOs4zhfl;+?W5;f1sv;2
zLJfU8pk&X{82V9f+M@SugP+h7FWqEVM|2$-AL!0c_{1f~TY^#r2J;Y@GJz_1$3=JB
zw%GiUCZWL}*Hm5N8=Fs3MvygmW(i2^rds1wi4CxSCp`ay){t%h$gqwjNOaGKOF!Ad
z7g7(oPh-Q%#YeLBqt(1Lx0(f*#~CD%Qrat}udjH<ueU>Oa+Yu`nZE=<H(i9B`R#)a
z8P+n;BzOG^OiyR|?u|nn5JCDrPuXoNUZyMV;w=N5Ql(j}PgWkEOzu0I)EZ=aAFb>K
zD`s3C2yp*)c**C7fZ?!~2}th$xYvL8jxHIK^>+1_RCgfohlXguLa9V~zzeR*9A^Va
z)6X=Qu~{M2SOXD+5&D?tBCF3DzTIIRdvi<o|C_sPS+YP!B+mlzP9|gH#zQ|75wXIb
zY=Q+T&+m(;d}c^BCQeJCmH+JBhkV1IST~4a4eMAliEMu>Oiz`x_pyODx)3a?rYn*_
z$i+{RM~}Jdm*5kfTyJDc%}1`4JTD)4AW{1vQ#yi2y%d@?!#6vuBeour3t0c{TqNDQ
z)V)g%b<$+P#86i%+GI;gN0r=VGgZR{at@ceYdCrHYHxb2yY|3yb|UQtmg9)}VVz*+
zmg*d`|JH-yZ{c7`k9`P%pbbf^LtsA=I*gfaB9KBo!KoS#E#~3so7E*a`<sw<;{cFh
zEfY<$@AHT7Y#9ej?v&_#PJ{QRP4(v2RAMbEecM{Cfs%n$je67ldy&V!i6OE+tmUIg
zcD>v5NFL9u4+Iv97t0)6KKwIyib;0unvG=%kG<vPW83_1uRSR#`4V8wsj&93!#6st
z<-;Vh>u*7(db=ppy>Z7U(oQnVczmz-9g8Tbk+A_Yk|X&3@8sW>+&G6^^wR^23~QMQ
z_iJZhY6&7zsTd|L6!bWC<c{W4t!e!+N;O-3OxX81T$-P^cON`$JG7fP9-BoeLyM~w
zXKrbC9}?$bYI<Vh`|qL^ad_TTu6ZvjQjc>kQTl3R8Nm}C=~M3)8gYWIJ0EE`AGcq^
z?7oiIf2?8S>H#W;f0>6pbMT*^m^fo&SUw<O?kiPp7EF#zE(1vF+j5ejV3mk@pk;o9
zSPF^;dImv!OtgE&WFhHk9Kks+Kd!&$y$2${@wW|UZW;Fcg9XW{YvAQqFDKzX`$-#3
z@PJZB7a9~w@12q`hNUvH%)wBzib}G|!*VEp%xE4?dFgTgO;63h>ZxJRKbSQg;Ip?a
zGjof5|8j_Bu(Gt}ozq!z{YU*QFH+YkPpdb}ytFqLvQJIJ%z493Ie}LQaNXTUPu)E@
zBksU;Hvagq($HmT#TpiWtaz-X$B=0l3D#5sNwDGThg~vQT->(v=;^r!1rnLxhCF1%
z%J@%CP@Hh%_6d^peZj{kcj%VyS{dK;;JtoGYu5o`zSCs_67A4#j}Lqm^Ijd1!ln$C
z#b;uO2O;f@z0N&#aMHI8_!t&RVb7c_6Og3YKK4<nbOYX2@yLKhWHNBln_s2QD%zaI
znTuA2y)dkYw59^wyJxvDN!;P-STZiS^AxGWVwQuvDXH2CEoOcR(9A%yelWF$#dHhz
z>|QQR(%p-As``>&_#uDkhw!FCShT21L}2E$6{0)`DtV}D)fC*ZYq>DV=w7cImj^iP
z5sZE&UF78=vg(`_0+NAB9<sUB!mZm`CLrmy^{FNYwI9+EJj<}aE>TUe`r;Mx70Vz?
zj=)CVy<CL5ru!ejN;(=Rs-^2mA2&%bb<T?Uk_Rq%XsZoy_wHrFB$8$iVnZu1dSDij
z!v&L|$(q*HFQrqDSTPV8nB<|a`R*tI@UWi|_bvgB$ijNvB}gWXWicLn`_!5IRa(7j
zg65=QXAG-stsQ$y9r!T@N$FJ5P2^lXz=>r$Nzx$!WXUoYRpTjDL{_h$uXtDw^&_0`
zj?QO!_#lyFJ*~7|+T_w^{OqkA;~`nz4^#uT5^Z;7&?HCVGBX!-nSi96(j*urfOMGb
zq=&GPP@T{z`-f}ruquIlbaumoV3Kuy>1%rX?{GnZ%@N7NM|Dw1<To5qUBtg2f~5P0
zoiVJVz78KG%{pwXR62YEs4#(zO3<WBfFo7F=mC;nvB8J;j_w_pWLOLK$1(uPrU|p>
zP(aaN{c~qVCIBM-*o3l_XFB-39RZOB=5HQ$#<0p(o0*!lLXH(k+EW$*iT3AKb(b&k
zlw7%+bj*!ADaO;H=2n)qf#l%HRrDOVap=`JtYTiwG%OS0UO<xD`}EDL`$kz4E9wH-
zKMt`}8EpjuB!qyX&LN_ZR4o&jK-z!P3i8bi>mew1G{WY!%f#H$_7QFxRSkQ=JD<ow
zHHu8!m#Bw@+5qb0^}IqN5Qr!w^>K{i?Yz{R$lte8jD=yNKa}f>&(&<3#L?&jeb^w8
zc8dkqQ(XLP4+4}7fiz~5^?>V{L%nmVA|x9N2PAbMdZvDg2hcQ&gmuGaIT688j2GJ}
zr=N6mjPJugYFJbC+*+)iY0d!df3*B$L#j_-(abSwvlXL4QgIW@o2jT;6(ZuTh3vl+
zKo5Lv1@OpVZXGf(>c%0y?Np#sIBC@~sV7mHs)pn^2o#dWvA@TD#$aTB<&BRjs+RXv
zk3UQ##K9$^BvF!2#8OqFH_h&L|J`72od}Fk{Vr)DM>YxbBRFUCGD(#efSE^_@szZ9
zas?@%7=uHhMMaV>e2nBK4^sF>#u!M<NK<hzYVQSW8s>MrchK!Cl`$ssWgQ$^4HU?G
zXfDE;CoPxCL_k+R8cosb%_rVW<=YK_Bop3cAk`v!BZ=t^d#W)^LP#-#!%VEqRmI#w
z==OYJ<y|pPG-A=k83Qo=TR(J>L^lzbAHiuyDJlHHDV?=X>N}?7llHUMq-9elY(Anc
z)|XD4D>RYvb6v2f5*o2%M8rQU2S*vDD0JNcbacmYzO!U}$WidmY^5{Iq{gTvZVsu1
zrP;PvDhWmjHm_M$Ah{a4H0HJH%_tdb`@57(P3i#BEX<*gHD;#BLcao#Gf4DfFeU8Y
z{*L2(M^!04RYQIz{Ua;MjGBCZHAB=fXkDCLb;4&90!OVY|AXt`xaM(a>;-sD6)Kvg
zd1V-B`8z2@XQ7<C)qg%cFe2{7Qh#<*1D2Y0iK;}D)U@om^Y@SY-6O6>Me@jQ_3%;M
zQCttc>6WXWSmbIcLhk_0nMm2}iU&74wYo1~Oio$_ZF6+q(t}HtZ#F?YV*pu%HFOcj
zO@>Lz1A06lC>1#H`*T}_<WqX{wBGC%E-d4p*4*AZ(YOm~HXN6iTvcWNTx8#To-wIb
zz3CYYS`R|<X5l(v$jd}F_2INW)1@TR0~|vFtZ65*lom^!Y8ao!5vu3p*_WNvaplEj
zOHS~ZICoJvXY<h;h4kQOCa%2z=5L%}f?8dT116QvPbO|xNJ0u0Xe0#(Qr2zusU(lb
zTMVUt%>>Adu;<=4vEj6zJ1%)-<Lbbx|0A5VdP2a}?aflC*d#yhAR9vtZOa@iSM`B_
zwtb)SwoeG_XZmwpw6;#i!8a+sB}p-#Y7l6Z?Np9GfkgpgQoimewqSekAUWxo=smv!
zp;`2U?u{*3iZCH5G4wM+bCkW`7ujVTDve@8M^hI5fHn>H-ufCgoc3RjOOULaY5Cc2
zIaJrzVU$cC<@Kl6NdMi}X?ub3y!C2-q=^o;liH%Bnba1F9Q@tx>x9eBJ$jCt2R~SJ
z<MYu`S^$tf-kt&Cnj%yhB`KXMoj)O}P2N?pnIuvCCt378l8BfFQG`zH_s-4N5s3qH
zJDH!mevuiC!#Y~)eP2kdn^^=5X`#DcSzKq-%%fG@qrP7z*rjG!71(_Mt~i%v2$D6I
zEmGxDi*y*{g=G8J1a~d+djLh$14UZQvm8>iM+73dH;WcGv#JnQwcLK=50?I1!#euw
z6E_M$bj)_hLLrQ8_8tj>ng(HMVL#R{T_zk~&N5QjUI#{S-WFMYAR(-Q)u$9FB&y9n
znU<2=8<jm@;sHa+R~)6oyjM}hJz&rkRtnA<#vYxTm#oV_n8$3}wtpnWJsiCnwPEFT
z>rQ2M&c92K@u>eG?w-%^@KTB-fF#tfbego+A~j}I7noZze#u3vlJQMzVExQ8G`9d`
z%kxPZi>FD|HhTWxa&A`53dPG6K$AcUjB;F3109hhp*(g(asaA>!vNV~ZSY12BcKyu
zYIVcbt*?Ng6zk}E<A8U67Ea$}LPXpriKh^$B!Z~1Mm?pBzV=9~NgdJi^EA7_RTfmP
zCh9b&@#@vf&OW+BzQaTLsO01yBF-gm1Ejsv#ZePos3qx5Fcph+ki>O{MVKSWA16e+
zm587!bSBq}HtC?;rXD-#6ru<>-~Okhv~OUOqqqck<0m7lTMO$ZvF}bq3GTvA0#S0-
zMIt(AVs>%ktfOisTcHjmh29G=X1b4g>=G#Kn}=sS`slvj@K8Rgu;vK}O#z2`a42Do
z8dNGhp@}33O@ZW_U4wb6ViF=fd#DCFkFIBNZbCm428k+k>MY_p!;!?)s)jFJ|2+en
z97Pt{x<k2Vk9{wZe9<@cm?WVR`wZ@2ED^+v@<1%nKv6*@+IJUfHETLms#^plX#W=k
z5M}#5_|`}3as`Q>?3O2+SE2$(5_Kafi|~ZfkWwffszf5CL`Nu(O)8937)f%SVIVRO
zmxD&dn1jFwWrWbV$u&|Tig5iMf5oWVJ|2V{))8Zo*L*l~)@ExssIJo0Gazs`est5x
za`|iz6t}(WlP<(kaT<sqv3SL@m(%o0nlQC`RUc6<JVll>NR;-ppC^u@iE@t=W$P=s
z022*F?IZ5duPM2)LsB7Xre`y=iVi_cz^f1)ERk%g*@xLBWu%GDZ(Fl&nvZ_|DntT9
zt;P{#5sz@c<Jvhw8|fq(14x9%e6^`bMBmJ+5L+!>IrHo%4d&|X1MJbl0NFzE-H|V{
zIhY{Ig!dG_?ldKcEN>=hH+-vA@@C;)W&eT@)l4J}I5>nPW=<)>NRydUl4B>96|5+o
zm{9LDF<$_q%!B=|Fj5$anQI-wyegv<xp(#k?z;a214xcAjr`Wf5AcW$iKr3iKsr<s
z(SNeJ6@wC+gmg-36*Q837*k5FC#C-he!D5phU9$?L~Mqpu~6+fP8=8|p7;2p|F$2x
z;Vx4&o1W|pkipTQ8pdlsR0}(3GAP9qQ3-VUs$-U_14c;6yjSDQV%L~1nMr1VQ8T?%
zT(bmbR<GiH*M5gtv)T<C{2{J9Z0r|4xR*7nloS#v7$B0^rAwu=3uWj)JF6pVtt`81
zAvBSw*3?7Vh-x&GIGHIXO>k}7*?nWB;Pl$pOEd1=tvvU*013*>+5eL`pF9~45?x`G
z=rNEEkE*L}>L`IugwAc*=pc&<U9{N8yyt0ku02L>T6L;)L5g`bQemX|ad<2xv1auQ
zfA#rqM5G-U<)LmAfmeTImQ9-yT^PB?DiS3c`!^6nLc_@PX-H`3NOWk35M5cc<_+_L
zZL=(z;N5oeNDUdUDJf21kI4yW5LQpY1zU~_kO=Mir;v2of`RTU&%wpg*g<hXn7EFv
zAu@%I)I3%rlqA7fsTbxki3b>!c{jD9|C<AiBR9!L&M-;fru#q54fp*yI)LOsuc)wp
zq`c}QJ6SX1EYgffA(|cuk(A7}5=nHy4C~wqS5=|u%tTZ3dIl1)323m(Xmpb-14V<n
z4L06JL_Dn6Mddp#m50TPd4yg;nLhLTU3{r+;Hrp9ee-Gv#xcIZGdM=tn^RUVk{A(~
z$ARIZejcUsTKLY{!%Qq?B<Arl;0Rr^$FE(rns<EmMa*}*yy3*K4%g+|2z={1@8+CS
zgcLedN2o+pI%ktaYTWGdWUCa+H6MfNl!QW~Xo!d^F_?`Y?miZT*ch|qwErAK%lTUt
zn~sPm_sj}E{7nxNiyo;1tv&01GPlpWn3Pry=HZGWs0;J#nMxTPY7CHt_ehK>q9~f&
zq*9poPL8HIj4dJto{nI^P?&ed>ckjmP7_-;tml_Meg+~9Y0xK!twsKR>s~&4=PVi$
zopf};%q*3JHVF->WNB*?NgnQ16cvw(c`}x&0ZOBnK7`)PvaJ(Itpy31<eIh=aP@)3
zE+(!xCmc^85kk9}nT?l_Xk1(PMh)2urKRLHU;VQ-NeCm7nPHf#w~OZS8oB2yW=&FD
z!O6j55qUeN3wM#iL>+<olvp(rc+ICCOOV#v9}VkJ%q&Iuw*P$-CvSo%o=qo~`_M@w
zseh9pqKzky1iN@?WAPE|RbZ^5$z8fKU+PcH!<9;*SI+B;Rf44E6c>e<;5#mT81>kZ
z<K@Ij7ru@81JQJeh$k%i6(*ZtNUvSo%<9~$HA?mY<h1yC4@z|iQI(N~;s_X(q(_K^
zK3&BbB)ZwxCA&RIV8`56-ulJo5u_P3${_%x5qQ)azQk##PB9{)p<^VSxqF*r85Po}
zoftE?*%dq<@3F5E<7jfCqs_I^5POkcB`r!2XcEaI?*%Fi+_f8i?&;w;1c?Nu*F6zt
zHaa8p-m2s*5>wU{p3y7DHlyUx^6ae=tLC(vEZgj(yz#R@cdar~VNQ)v=3V2MYuH#R
zN9LmjrrK5f>%AY~-8cM{r`rucIhYQ4@dt0>-q@kiA;B0zLISbNkc1Azb0M5jl6D?c
zHu0@QW0_zn8QJCARU%wN7Wv7560}Sp5P=w^N|jgIpgiu(;}InO@t$(=+nAe+MRz1@
z!;gS2cpD(UEhb@<Qi-v2z`R(x{Ky%h^Vmn{p0CcCqjQEStl@#nsA7zxW^#?hQth*j
zSvRwR_ul;byl3k#4nSD~AOigE7w+OOzkC-ntIVAnr6bb0YZsFEcN`L3aFa^ZD-S(o
zMN^-*7b4npR!h<-DngX(vodg4+DWn)NvTTpJPl`+10DR>Qy<>Eyd(Z<Yd1ZQ#2SyZ
zn|CUuoa$_WLRFzlo`#~rD5wi@*B+XPi4q6ta)2@CY2`W+$=aqd@HiOzOkpe3n%CeW
zUl=82<Eo9k^TyZmXE*)7-g$D+D77qp&yDx;%D?{#C!I9yU22l|YL4T7mmCVO70Q{u
zA(g);M+HX74B_dlQfK$3zI2~xj3TL+V<K?#{fYl_b#usbq?RE_>>Zx*s5db;?}0=y
z2I;Z@kKzSZo|G8OB+Fp1WX8-8Fqh3T|9j-%GnUCg#$>S(H_PS;?hdwqWPbd7l9ENd
zdDY4M$xXk>Z(a9tL>l4=?)A!h?!7nP%Xh!`8n$d%MJJ|12nlUW4`|alD_E+LijqQv
zl9Hm{)V#C5QD{8UQGqDOOYF8pC)xug<n!^kiTFiKm8&m=&1(dC7|Z)b^+;pV2>aSk
zuA`aWPb`!xeH<h(mWq<dqCQw%3Bg%LU6gxLV}j&*r^}$CcL67aP6JVJMiQbnBw!R8
zVhZjhYaFD3`{Q2DUHf?c;L48?HPT3P!T}_yB?-R$Yq#?QfAcvuZ9d7fBN`f}e6I>Z
zi)cWS1@RghOLtcrswCQA;gBY~sr>d}`XdF)#Yzx@<(NnczTpF+f_PntkZ<d+=XdQ;
zKK2u<c--mD!`cGlC>VE^+j;RNf5E;3sT4$YIYCjpR5#%@BUSV~w=|VntXs3lky>Y!
zZVVtcKe1;b^PFUWc=ZBZ@QA&~STx63R9M$;<ko#R@U)MdjXNq&D1dYhkRSV(f9K_Y
zcMTg)UPDLc6UCCnJVMUj?uxMXA_gy%OT{&er>j`RT|AA%``Y;P2z|0*3jItQ73tZi
zHot%%iOp-3$3M&fIZ7b0!*1C4?KIP;6jyH!B9`1L&+0UjiPG=4LrY90X8j??64`T=
zK{6@;%;uHXn5ZRNcPhjn#MJn)?e<X;A}uO`QG}*h&4%f<JnDn1`1f6(^RH*+*P=vK
zS`ohfJs;vNU%a068&{jxNi6-{gm)xKgeI3jS?(3tb49dG?`D>Xht!)|Zeo=hqdYf3
zD-GiprbOpjM<;-y+`U_Q(~DM-j)9-$sJRJLBaeIhC)u?(F%pVrD)|+BlyZ$aB~Umj
zf?F6RDQWOy_3T>zTYI>&7p(Dr-Ibggf1GQXB<}Gtw{aBngw3mP@rJMCyZ-s<{I@T?
zlHkQ)E7iPG;O4!v%)IFxd~M%;rq{H@Wcni!J(3;^yGA;TYh=9<%!8Fv<4epWL~jZa
zNx@Q9vVd2~DJu4SW1?tf6yml)kiJ!}|0|+Qhr}~3Zu|LBD*+@T4XamO%qgc{ZLZnE
z9G>VX6t+m!ScM#M&-Z8DlJD<)Q};o{P#&9skdr7?D?Ou)bz+geHBr>YbG@u&cwQst
zuDgH_-}52P|Ik_7Fngn4anp)ok08QNUh`=#ddE9iebPFl@$xlEXo~&SpWZENf?CU!
z-Q2o)Bt|lCRoUFB8jhjF?BS|oA<j6~w$=J1WJiFj<>LLiXEyPs7p*xaEOL~D`#77Z
zcKp@HR<Ul4CpXq$ASXY%dpId6xW*7;oLsS}7$aD!z4YENyx=N1D>$Pljb#=)kUDL=
zj=nJl(b@!?cCa=k{AnOe@#S4N@Z7Ur!2kdFKd8D09-r;q6G}k1cIP&p`u=w_->hP4
zY89l`%4f9!S`*hAP;C$mKx^U}LA0@+2G!qS;#+BG^KIS-D3~4Q&oi+fv={VfV>4_#
zIV%f%MQFSlD~PgtR=D#QH*s`(q8tMz$!rqBG~aN^8`wLqy-7r$yVX_NBTD`k4<f4P
zZRMyreN|#+k;>faOM8O@q;Ym>3iEX3F}e9f>siZzQ8{LyOUn7{9?8G%{5&%sID_B0
z>Fp)>csvCl^AOi<2ljF42j0OIfAtPnvx;WAakp$7A9NvEH+Y<bXfso?X_S)|i(t=9
z8?48TnO;>rdUgp*ZWNI_p=dF`w6IY0f0K95iQK&_@viS%SBkz?9Fx>8;rD&&bX4vm
zYDYg^(ek)VnA=88sur2o-o2Z&7WSDvykb#Zpi3z1W2~V>T7SM2z*v%H>p*LWxEV(4
z>=K;KT00*a5)Jov``9zTo7X({7x|I%UgGaemnF00@`QkJ+rB-#_+Q@3Ki_&2t2dm2
zYU?|=#RDIRwx|Xg4Mc5d2%xP8LX1&FjV*%zjs|B2`&Ux%+{T7LKs6u)nv_S5Ly8SS
zgrI^-FlUzvL7Z_sO+LGRn-FNDaNSRDIi{cI!vGRc?dakxZ~y2fHmwidKdT?alO%Wt
zl-vly;vt=4An-4~^Q(W%<-MMMlB*mowZ3N;V+oI+(0W6O#$UUoqah_BN<$}slv)F%
zw5UwcB}mee{7X;LuycMNyXJTD;}^Z0|9;`i*gUmia`wzI1xG%IzrE)Me)yXAbIbPo
zSiSyaphc5ydhkdfZ2^NMyImawwP{5*m$WUw7zc^~4yF{W0Y?JCo)<hin2(D$2MNW@
z$}LhFLI#QkZo4<}<)1y73pcmN^s{|fK$5SzU%UHv_@}S_6f@JgGm59JNGRFD84x3H
zOxK%H#yruRNEkZ=a|#6U?BP(78WT;Q&xHZOS{enS1V-B0F;i=7BB2M6w$=g(A<C3F
zC@W1P1ooxK-TUt137ek4FF*1XJnNJv5+ocmyBXk%d+z2}zV?s2_lD0fl4)jEZ6s-c
z6igrJl%*9W+w5i+P1_l#2EhQM8VIy_oh*`pGyxPcSPG+H$JQJ)G+mMdib1t7Q|_H*
zAj%Bl`bD6Nfve7%<}Y5b>6kO~!v>Oko%_?zT*QHRv)Q9rgnL)Z>>jrAUKjITkYzo+
zLe(qS*dvz<cNsJe5~Xon(>e<|pxo?AZf13~21aS=G<acGLvr&%rS<y!raT84l31@o
z)xiDpyV*C|$CW2v#*dxzoqYQ#S8~eqNk{z?-Q6AFBllg;A8h>uAHVZU%*Vvc>XT`t
zMYJtF${MxqBOw|1H3b4wp8wQ<P8n!YQ&>Z_ArvNYpcG+V0Ye)znY3{>ZIL7n1ZR&7
zlw{yA@oqp;4aPUQ-w;A8ft&B?NWXFpF+mef7?9xU)bJbsFvaF|Q*;`Ohs%KBCR7&m
zYR#5y(_2t6MjO$PUBTv74yCfuioQJB?qXa;=u$%zA!*}UB%tah7!93+AOp<KrS&e8
zt%Jne#;U>QvJhNX*=wi@v!lK2o8QBx>5W{m<q16d)GN4p(<Pk0>QpvPt$k1$W-fK?
z9PQ;Rvv>3Ho!9gC+rG>fw%^2_`8_o4I@+m|Y(tM->4h!@ga-9<ZndGKrSV{@UDZvW
zWDr=vN9zr-T7rA7q_9TgplN)=n|{gcP)skMC@aobL9-bqhzKDGBEeEx)J-^#yzkfr
zfAQi|c;<zxk4aqQn1aOkB(Z(=v;4uQu4MDt#=RI8JY+2LUd1!Kh%3fE29g=XvW<;F
z%*T@5xKd0mi@rO16z^5zIb!DSv|}_5ke+Fh*lqUHI}30&QlCMOnu9^b?#o4Hb8()z
zI7^Bnrkd4kp5DZkRhu|<dNW(5H?S_OVr@H3Lf9AQ*c0d2IoijL1G~9*Za2H;ce8&q
zhpG~qRkY1Irkd$u=42hA*oK2Z(m<2^{E|P;K@ij&6j{8hwloeRGq*5i@vD6n_Sw`D
ze~khZ71JJWM)mI7P@N-)n|x-<xq~=~jmn6Egi!Lp&REs(uRnO^F*RL}DM<4A<SjqT
z$8Y{kR?TFMk<BZ5okCxKLh@{0=>bujSjhnrJsm}Js*1L#7~6Ed*}D|zLg)eEW>?<y
z(OJbpVU4p7AX6^l4ZvV*h8Pgl?d<;F%%EA;=k6ZKK^v`kc(F$Nm_iWSK;o~LH=8EA
zQme-m?6r*5H03L^F@idPOswaB1x-`^-)=q$4U$@t1T&pd<B5w++3@yzuPL&&kqio|
z`<x-h^oMH{d#nSci28;$z^!+8#8+QLQlVWY?VOL%X(XO}?*C%r+Dn;B!Sk=A#7%O2
zb5}rP8M|Gm0KzyxI<n}_^Gt%*&*zv+C}KRfShd!vp>zyXXPJ~j0bP#4s3%e;Hvz%i
zm^nCFkF(DsD00!ZU<{K)Jh#BaX)9Aqht__Ymgz7>+qh3Cx1Q2|e6@}ZCDc*_F5XwU
zR0-C#93Fq5wD|GXJXNZQ<h(11h+35)p>mn{@lvigmDES*OWKKgx0D>c_xnR`0$~yR
z<R!j!6ZMGAufJ>i93Or8nJCK#Ajc3S0o9Hlx#A1#nVa&>t0ncl&*C*!$>}7qxN|d$
z(8o;5hIin2m-|?oQCKyk)!!S)@Z;f$m^P2mfGD2AGR6dASMyGVnAAtuWwRobezso0
z>XmgC53)@mWn_dBt2y@Sg-z;ZuYQ!$C8VzZP7Yh&blBK~dK$9$^F);peC~&b79~V`
zo!lWU-zR+nqV>L_+-D%m0mcjvZ*pCwn$(GorC=%piT=Lm?T2!IuD$ae&wc!Qo_5X}
znq?MxI%aqkX;F>5`l<JE%j`TV(;g!UrG_LqK&)G%l$!Z0*iBQ|X4f2$B#USl=Q(Hz
z#1u%O@to680A}-5#bYzU+i9APA^A)hZ%3fX09Yn3X>ToA&Xdo6EMsQPeQhmm-9++c
z(UMz6d%xT9!Ghw-tpBQ{wB_mB^Vm5=e}_G<mAPXfyGFddXa-y8Ocdv+y60TwysaE%
zFB^Ld9PX(1QQ6{&j(7o;X26kC;WKOXIaz{tc?6n9m`Rbpc+Q!`WthxxOi4|op^<4`
z`;?p5x@SKcrag_sOMF#KJ80G?!QHn~7(?Avo6}6Ri1|A8#Pvl8-WRMjEukjvag$7a
z_a}0+S$yi2#}(YPgFaExyj#vR4luullY*4S&`W;?6LO_IHu??Pvq?3bSh2AM4O-P)
z)Wf@R^UMA%Oj2)tb+e1um)VM?!b>ip6=xl1jm$<#>dhZLA+ky}QDcZa#K&AVosWj=
znMaz$UH8m#>nk5af@Q}d#~dUXC?~Btk6*g#pSWrFK9EpSO)@|_Hw<$0JlCuD>G2ks
zPk8J^O~4vBT5poq3;GPM&P}8aMWxpzIl7PJ>#ld}(BKRq#a(H9VCghARoL#=)DO>;
zMc?-#w`PmZhoh#HylGqKtdYiASJc1fbafFagLCR;ZaI$%js4X;vy6a9EZ_+ejR7*|
zo6Jsbeo5|IlR;>vo=EhGSKcW_lilV(34-eun|38lV%xU8T>Hb1rVX-e$1W|4^Adz}
zH$0jDdilG#ZO?x1q`_FH`RE(Cm{}PxntKmtTVHxtZRr+iDJ9|oN%dq(@qS&<5|f)*
z&JG~OyOTRVMfb?4Ynluwo55mcR`5Q@>Ta#vnK0{)<QgEQRDQ;FiH~X3dXTV;&vGt8
zK2^78&_=iNGDuU!Og*4-JvkBy($6>6tSi)KRfa^;s`4<m^bq=_L=-|E&*Xi3C6YqE
zAY}G&#*q#YVdu^{-v0da`TA4WEK3GiRv^hhdHj~=^W%?u8@JBx2Wg4`FX<;}pLU{^
zt2W0)v`<4xRiMv6rNwN@o-PyRmcNBi>|wi)ava-rjWdgk4P5rJynfiY_JUg{24Ie5
zc!dB#+-zCg471iel}3?DVfld0P>J-coW!R?6%#8r(<Pc~S)C2U!K21(*=z!JHgZ6C
zyC5l9y;?xi3v#SsgqwlJPF-mmM3q4dFneG>KX}EdeE(xkX1T9r#&F7$PJ0<Yap{}6
zZFUxwrlg^$_PJShRcfkyF4rj1Q~)txX_2%!SIa<vI|s<3Tr9%e`9~5<wAeO4th`oP
ze`vMmRjkcTs>Umifnw1#9V`QOLF&EsNYUPHzTh!cT6-1wf->!1Cyr-2L4vmx)!tPc
za|`n(7Dj^TUNd`*F7&sZocTW!jvvQe>4QEgxpG^koXK5nqf(AJiWtJ&R?~b@&dr>Y
zq?r5I93N-7DXnEij^@~6F`8L9zvj&Oapmi8`2P0(175$pUys-G$uzYj<@MblAnzJ@
zK7OW>BLsV{Yhpropih35rR+}l6!2k-;=8oF?XDi4+$HrMDL)7ZPk49Yucn#1NhjuP
z<!Acmq<|ION$;u#9E4k%ji7fQV+v<>oBStJ#zIvR^vKVF=EVIUDY`A_lvgkf`Ibv$
zO^azS>gZJ$i4<3C($cO~l8v<zw43LApd_k^mV)oH(cVBj>^p32##z>9qK7N)l3r{W
zw+%RX^HA&Ev1#`7dY$JfP@{&aTby0#pqm}X0Ey%!&gQe#X{PoOvYta`JOYQ9+P!eG
zA5{<oJ+d{B?RKzjWhzrQ$lrN!G8;41q{qs7E%w~#^B4b4jd25~-ru`jF_l>HxdhtW
zC+%sr@0{$rwOXruxLE}mEjfW}H_Sh?QsHa3S5l<!AC{k2WlecYQ*C+{l`*N8L%;Fy
zTi+Nk=d_xIx(%S!VEzl*Xet9K138?!c#L7)3<lNuaql*Yt~P7Y=j!bC#Nm@I@<NPR
zbt1x|l>Sd&fePM5b?5i`Oqcj;clOu_#B=#5sSMkkpA>N|$^1`++2U_~v7;feb?tL`
zGbNe;Xd_OOH;-#*bM959&^ZkejGDn5xNuY6qPeH>Y@~-{wabg^35YNWm_Jd44p{RH
zc*s}kbEC&XvmqB8T_EPpeLquv9&!YR$(VNjb`Wf@O(uwRb}u&k3@VP1g|je5YK0y;
zb0g26J>=VCg+LtOjkA#txS_V*LH;$OmQGUa9z$v<0mQYHIMHzMfvf)XW6h7@1>;og
z%m-scc>rI=-Eoihm9G;L_KMc``<uDr<&D;1M$Rg3H{tOQKKjaJq!R>pAy}>OReVAo
zKI(A#H(rT2wEV*YsB2<G&$M-?8(iKKyauN5G%wx2PhTpmvYThn<$^hgE;p{#TB9#F
zs;takwNz>=!qtkFGk8;eVX(F<tG7B-vTmGtkBdkY-)a6pDQ#ZQd_nzv<^85+8C2&s
zn&;bhC5Ev12vR`3xG*PbbJ7>uE+x$WS6RE^(132lQRd9Ook>SG@5{;(KfjyyFnkkf
z0@zso=<W4ka{|r0IJ7(1&s!d*bVW2>Xda8+!xX*UZko7`H32+U8+fgW5Cz!BC%jGW
zuScz{Yjt$WT|rFLHb*6wlN>x924#bKH082Sc&*>wOi~aF(8lCyZ!bz0&LGeh(@ohr
z{@TCXt)k|>%@FGcglS@cQQUVkw8@UnoLrsNVjgKkqFqJ7ERcVR)0D~tFWXQ4ZiQO*
zDkp3f?_aUX#_DK1GQXgOMfWf6uEO^oDv(xg-cbo(#dWF!3)>FZA9DLmZv_Jjg>uX+
zu9PTe<yj6_#+rf=`TQvnnZo}C2TsdU{4@S@Mj88z`KHsgv`-4ThfUR4FSn^%ceAod
zZinOBMAk#;*~#jpIe~_Y)TdWGnl9zIHq=;QnWHS58F37fZ|GZN5bF@VUO}I-tU_HA
z(0jr|J^Qj;CGoRO3;fqZMJ#B(7R=&;tYn0V&+SjjcAryX4TJcEoCvUw4?G@LbN$Hn
zhMp%!?+J*iM{!*HrgQmHqO9lcnwE{=;KC|@ept;KSC0*V(SVNBy5@w^g*bcxpMt~<
zpM*rgwB17-#ZsUnC@7V2fmvM5to;j9M@A&5BDUp!uB>8t7k~5&`x;YV#w&N1tI(4_
zQb}7bp&;)Omx<t?sC2{L=WLPD&B{FESo|kHDlCFNxPDq8hrqhuVaiFrMnqIcdSGl#
zBEM>eRI9>Z-Y<5yDFO8axQL_cbK5*LCahsjC9cG9$mxv>z#eES7<Cv2HZ<R;2+@MZ
z?qbN1Q<Z-&?U&{@`o9L&^2EyJTI-@>#;X%W*&9ssP5`mrXVj#=oXmn5&$9Xo0M7R(
zcvX5%4QX(_I|sCu!G7_>kqfU!Ve4|T%JZRGC-AO~{kO>ej;c~bAiITnGZShyfON|<
zi_(K44TImMkE&SGB1S3t(((<(Z2~mPWP3&qDLQ<ummVW|8NBMY;YqcM?G@&+{Jo1P
zW1Qt|U*_~ZZGq1YjLZ)KPgJ5M9gxfM-@O4f`q5u+J8G3YAqvz?dI5JU9YWfZ#U*QQ
zg_{d1iF$@eltjF5+{2u@<RQb#PJ^IAY6={_xMn)FMPIk~`7|L8D5)VB-(iJAOTAjd
zO{y9^=()u^>{_I&#tnbJx<<fc;@HTNkKG^R)ei^mZlCs}=Il}b<!q+q0HeRelLHGO
zg7&Ifj<R5QO2xm<8Ua;u1vO8cAKW<|XW80FEhFkJ>|6CYn>M~iZ5o^Z`VvS>T6(zx
z#Vt#}9iQ8U%jB~tX`I8#s*rsVcxOSS``JC8?s$Pq=Ux*(%&HB<^q!_HXH|uMSz=lZ
zTBx5If=R1)w=JIUByK_BHr3f0MpDjN#P?+JR5=RLd+1ZIhrSli_lV@FrOs+v#}>}-
zJ;HGnHU7`|Q>0W9#jWjClC-f*+|Y_Vn!UHRbQlL)zaRw~uG*?Mi>Or!MaDTP51o0x
z|G6EsQ=s@0O0J*YG?-^(<4&&(_K}=ccAJ$-MWTYjeQrCYB~w3E)s606)ZK1)neQQ5
zsYWZOR-E&9#9~?+wC~TsIN9zXNAr(|8Xkz8_Iq=Uh<=VM$U7TJ;x>yR@;Gg;o(`{z
z9{q|Yc{9|^MkM}zDRKO@y%7*Xd+p>#b{LrS5l*g5XBh<SFLmR@n+jeIcXfasSnBDl
zeb0uJ^1p?2Cs*E92uxIx6SR25TRg2CLyWi_cM7koT}scR$)69^6WMxKO<b@z-m|Xo
z45E7<P!>+0IgziFUCGyMv)-27urCC}uPy8!rR93;GbTvblNTExg_lywovbUwtXd&K
zViKTqe>DxhSx&dJ@5FL+mZsM-Tra`v3a{c>*C0b%3D5h3?(!Au5m$|iY`RY3XmrJr
zt2$H6hA4<h<j}0oIP&7~HDyy>p&VowCO;SR#}OUOWEw}Zuj*Sz{t&hp(EdpTS`o-b
z=?tJtqSbv9XURy<^vwxfRLIB+Z-WbIv!0HDx{^sdlRQ`ZT@22Yd!fRlke#PK1$S@!
zo3U~E@}v2#gkGV)@Rp5%>~JZQt!&OTrVaD#=^HyQM>6et<)&-bK3=mEkQ!H>zjjSt
zEnU+uBqgDI_!xq{=eU?Bed}crvvxR3#ikT^$1f)A`g{;2)(F1M22E#)*hT!O=$lf$
z0JJK@XkstMV`JoKkg(s@gkql`_$pq2-is|Xn38yzTIjOX1F?4xl;VBv?|>9Cq{f+?
ze45Ee$Sa(P$7!#PtdGs@tojywhF<<x(j%1Ga@<ucH|MwM#`@;R0pVAI#=<XtYT5!H
zP_-02gNl5%UOVKUUIu9D-m5U~0hoJ7+ejkPS}c!pUu+30(C7Pj+Ag7$&SdIhf5xbE
zGH4(1Ffe!At$p`^SDN2KVd4X7+bL#0=hH86_yIplbji~{>H=d~W;OL`t4p~cQL!xy
z%;cj)kb1_=8oeyo2fQCh;M#nTUWVN#d@<?gd5|CDwm^m-gM{Is3Ok3>R%Z@bkS~gp
zf9^rr4pRqu53TKjj@zMI=?fPI00svI75S=dro$6YMw;>S<ijrhmVs8}`zQVXL{jrP
zUq$T5_!g(fpeY@NV?Pv-S$CZ03#=o;4vLIJhPm|;_E&E>m?N0q-o1I)nH8Rlt!4$6
zIZZww+(~=F1~pxet&FVn#W6++RL4TaFQImaQAEnDm~HXZhyRudrfU{U7zFoDoUSiy
zC)lyE{Kf3hbMWK)@yQiG`hljqOk_B|M^<0|+1TbqEgOdsGUSfM5NkaG<D2JQN${H9
zyhHQA$h>mLs^&g^AKPzO)cen9QAcIX+tCQrvFPe0toO4UcZ|Ip5Cr;Mk1}at$81+z
z-3|*~LE)TaoRZW=^%=EDrzVQ~;9i&k^2;eb8>q(Mn%8NiV_8-X=l?fnEgtc;xBOZQ
U*3H#EmVxnD-nKQXzv&tOKaA1?!T<mO

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/hf.svg b/studio/frontend/public/hub/profile/logo/hf.svg
new file mode 100644
index 0000000000..ab959d165f
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/hf.svg
@@ -0,0 +1,8 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M230.721 172.7C230.183 170.673 229.313 168.75 228.146 167.008C228.396 166.091 228.587 165.159 228.714 164.217C229.543 158.241 227.471 152.77 223.567 148.537C221.452 146.225 219.185 144.698 216.784 143.761C218.36 137.018 219.157 130.117 219.161 123.193C219.161 120.03 218.982 116.932 218.682 113.88C218.526 112.356 218.337 110.836 218.115 109.32C217.428 104.847 216.408 100.431 215.064 96.11C214.183 93.2707 213.164 90.476 212.01 87.736C210.281 83.6782 208.262 79.75 205.969 75.982C204.465 73.475 202.827 71.0508 201.062 68.72C200.197 67.543 199.296 66.3938 198.358 65.274C195.58 61.898 192.561 58.7277 189.325 55.788C188.25 54.7997 187.145 53.8453 186.01 52.926C184.893 51.9943 183.751 51.0927 182.586 50.222C180.241 48.4766 177.818 46.8392 175.324 45.315C161.543 36.945 145.382 32.145 128.109 32.145C77.817 32.145 37.057 72.907 37.057 123.196C37.055 130.208 37.867 137.196 39.477 144.02C37.317 144.958 35.247 146.42 33.327 148.535C29.424 152.766 27.351 158.217 28.18 164.193C28.306 165.142 28.495 166.082 28.747 167.006C27.5811 168.749 26.7117 170.673 26.174 172.7C24.974 177.261 25.369 181.374 26.894 184.978C25.236 189.688 25.65 194.704 27.809 199.065C29.379 202.25 31.626 204.714 34.396 206.916C37.689 209.534 41.811 211.758 46.783 213.892C52.715 216.422 59.956 218.799 63.249 219.671C71.755 221.873 79.911 223.269 88.177 223.337C99.954 223.446 110.096 220.677 117.357 213.59C120.924 214.027 124.515 214.246 128.109 214.244C131.906 214.236 135.699 213.997 139.467 213.529C146.711 220.661 156.892 223.455 168.712 223.343C176.977 223.277 185.133 221.881 193.617 219.676C196.932 218.804 204.17 216.427 210.105 213.897C215.077 211.76 219.199 209.536 222.514 206.922C225.263 204.719 227.508 202.256 229.079 199.071C231.26 194.709 231.652 189.693 230.017 184.983C231.527 181.379 231.92 177.257 230.721 172.7ZM222.281 184.673C223.952 187.844 224.059 191.427 222.585 194.764C220.349 199.821 214.795 203.805 204.008 208.082C197.3 210.742 191.158 212.443 191.104 212.458C182.232 214.759 174.208 215.928 167.262 215.928C155.76 215.928 147.201 212.754 141.773 206.486C132.594 208.05 123.222 208.103 114.026 206.644C108.591 212.808 100.081 215.928 88.676 215.928C81.729 215.928 73.706 214.759 64.833 212.458C64.779 212.443 58.639 210.742 51.929 208.082C41.143 203.805 35.587 199.824 33.352 194.764C31.878 191.427 31.985 187.844 33.656 184.673C33.81 184.378 33.976 184.091 34.153 183.813C33.1516 182.309 32.4799 180.61 32.182 178.827C31.8842 177.045 31.967 175.22 32.425 173.472C33.089 170.949 34.46 168.851 36.322 167.344C35.425 165.87 34.8365 164.23 34.592 162.522C34.056 158.808 35.289 155.1 38.062 152.076C40.222 149.723 43.275 148.428 46.655 148.428H46.745C44.1965 140.259 42.9044 131.75 42.913 123.193C42.913 76.522 80.749 38.683 127.427 38.683C174.104 38.683 211.94 76.518 211.94 123.193C211.947 131.773 210.646 140.304 208.081 148.492C208.489 148.452 208.889 148.432 209.282 148.431C212.662 148.431 215.716 149.726 217.874 152.079C220.647 155.1 221.881 158.811 221.344 162.525C221.1 164.233 220.511 165.873 219.615 167.347C221.477 168.854 222.849 170.952 223.512 173.475C223.97 175.223 224.053 177.048 223.755 178.831C223.458 180.613 222.786 182.312 221.784 183.816C221.961 184.091 222.129 184.378 222.281 184.673Z" fill="white"/>
+<path d="M221.784 183.816C222.786 182.312 223.458 180.613 223.756 178.831C224.053 177.048 223.97 175.223 223.512 173.475C222.848 170.952 221.476 168.854 219.615 167.347C220.512 165.873 221.1 164.233 221.344 162.525C221.881 158.811 220.648 155.103 217.874 152.079C215.716 149.726 212.662 148.431 209.282 148.431C208.889 148.431 208.489 148.452 208.081 148.492C210.643 140.304 211.942 131.774 211.933 123.195C211.933 76.5231 174.097 38.6851 127.424 38.6851C80.75 38.6851 42.9099 76.5191 42.9099 123.195C42.9015 131.752 44.1936 140.261 46.742 148.43H46.6519C43.2719 148.43 40.219 149.724 38.06 152.077C35.287 155.098 34.0529 158.81 34.5899 162.523C34.8346 164.231 35.4231 165.872 36.3199 167.346C34.4579 168.852 33.086 170.95 32.422 173.473C31.9642 175.222 31.8817 177.047 32.1799 178.83C32.4781 180.612 33.1501 182.312 34.1519 183.816C33.9739 184.094 33.8099 184.381 33.6549 184.676C31.9849 187.847 31.877 191.43 33.352 194.767C35.588 199.824 41.1419 203.808 51.9289 208.085C58.6359 210.745 64.779 212.446 64.833 212.461C73.705 214.762 81.729 215.931 88.675 215.931C100.081 215.931 108.591 212.811 114.026 206.647C123.222 208.106 132.594 208.052 141.773 206.489C147.201 212.757 155.76 215.931 167.262 215.931C174.208 215.931 182.232 214.762 191.103 212.461C191.158 212.446 197.298 210.745 204.008 208.085C214.795 203.808 220.35 199.824 222.585 194.767C224.059 191.43 223.952 187.847 222.281 184.676C222.129 184.379 221.961 184.091 221.784 183.816ZM110.137 196.997C109.669 197.815 109.168 198.614 108.635 199.391C107.23 201.448 105.382 203.02 103.237 204.188C99.1369 206.424 93.947 207.205 88.675 207.205C80.346 207.205 71.808 205.256 67.023 204.015C66.787 203.954 37.689 195.735 41.373 188.739C41.993 187.562 43.0129 187.092 44.2979 187.092C49.4849 187.092 58.9299 194.816 62.9889 194.816C63.8959 194.816 64.5359 194.43 64.7969 193.488C66.5269 187.284 38.5039 184.676 40.8639 175.692C41.2799 174.102 42.41 173.456 43.998 173.456C50.856 173.455 66.248 185.516 69.467 185.516C69.714 185.516 69.8909 185.443 69.9869 185.291C70.0009 185.268 70.015 185.246 70.028 185.222C71.539 182.727 70.6719 180.913 60.3209 174.573L59.3269 173.968C47.9359 167.074 39.9409 162.925 44.4879 157.975C45.0109 157.404 45.7529 157.151 46.6539 157.151C47.7219 157.151 49.0149 157.508 50.4389 158.108C56.4549 160.645 64.793 167.564 68.276 170.581C68.8239 171.057 69.3683 171.538 69.9089 172.022C69.9089 172.022 74.319 176.608 76.985 176.608C77.599 176.608 78.1199 176.366 78.4729 175.768C80.364 172.58 60.9099 157.838 59.8129 151.755C59.0689 147.634 60.3349 145.546 62.6749 145.546C63.7879 145.546 65.1459 146.02 66.6449 146.971C71.2949 149.922 80.2729 165.35 83.5599 171.352C84.6619 173.363 86.5429 174.213 88.2379 174.213C91.6009 174.213 94.2299 170.87 88.5459 166.622C80.0029 160.23 83.001 149.782 87.078 149.139C87.252 149.111 87.4279 149.097 87.6029 149.097C91.3109 149.097 92.9459 155.486 92.9459 155.486C92.9459 155.486 97.7399 167.524 105.975 175.753C113.447 183.222 114.491 189.351 110.137 196.997ZM136.766 198.407L136.339 198.458L135.611 198.541C135.228 198.581 134.844 198.619 134.459 198.654L134.084 198.688L133.741 198.717L133.255 198.756L132.718 198.795L132.182 198.83L132.063 198.838C131.923 198.846 131.783 198.855 131.641 198.862L131.462 198.872C131.296 198.881 131.13 198.889 130.962 198.896L130.381 198.921L129.854 198.939L129.502 198.949H129.323C129.213 198.949 129.104 198.955 128.994 198.956H128.82C128.71 198.956 128.601 198.956 128.491 198.961L128.043 198.967H127.418C126.927 198.967 126.437 198.962 125.949 198.952L125.553 198.943C125.44 198.943 125.327 198.938 125.216 198.934L124.796 198.922L124.275 198.902L123.805 198.881L123.684 198.876L123.237 198.853C123.112 198.846 122.989 198.84 122.865 198.831L122.576 198.814C122.213 198.791 121.85 198.766 121.487 198.738L121.107 198.707C120.947 198.695 120.787 198.68 120.628 198.666C120.441 198.65 120.254 198.632 120.067 198.614C119.754 198.585 119.441 198.553 119.128 198.519H119.113C123.683 188.324 121.372 178.802 112.137 169.575C106.08 163.526 102.051 154.594 101.215 152.633C99.5229 146.828 95.045 140.375 87.608 140.375C86.979 140.375 86.351 140.425 85.73 140.523C82.472 141.036 79.624 142.911 77.592 145.733C75.396 143.002 73.262 140.831 71.332 139.605C68.422 137.76 65.5179 136.824 62.6889 136.824C59.1579 136.824 56.0019 138.274 53.8019 140.904L53.7459 140.971C53.7039 140.798 53.6639 140.625 53.6229 140.451L53.6179 140.428C53.1992 138.638 52.8477 136.833 52.5639 135.016C52.5639 135.004 52.5639 134.992 52.5579 134.98C52.5359 134.843 52.5159 134.705 52.4949 134.568C52.4334 134.162 52.3757 133.755 52.3219 133.348C52.2979 133.163 52.2719 132.978 52.2489 132.793L52.1809 132.238C52.1589 132.053 52.1409 131.885 52.1209 131.709L52.115 131.665C52.0351 130.945 51.9651 130.225 51.9049 129.503L51.8829 129.226L51.8479 128.754C51.8379 128.625 51.8279 128.495 51.8209 128.365C51.8209 128.334 51.8159 128.304 51.8149 128.275C51.7895 127.913 51.7678 127.55 51.7499 127.187C51.7399 126.998 51.7299 126.81 51.7219 126.62L51.7019 126.124L51.6969 125.974L51.6809 125.517L51.6709 125.128C51.6709 124.973 51.6629 124.818 51.6609 124.663C51.6579 124.508 51.6539 124.338 51.6529 124.174C51.6509 124.01 51.6529 123.848 51.6479 123.685C51.6439 123.521 51.6479 123.358 51.6479 123.195C51.6479 81.3421 85.5789 47.4111 127.436 47.4111C169.292 47.4111 203.222 81.3411 203.222 123.195V124.174C203.222 124.337 203.217 124.501 203.214 124.663C203.214 124.798 203.208 124.931 203.204 125.068C203.204 125.188 203.199 125.309 203.195 125.425C203.195 125.578 203.186 125.731 203.181 125.884V125.896L203.16 126.427C203.153 126.582 203.147 126.738 203.139 126.893L203.134 127.003L203.107 127.499C203.048 128.562 202.967 129.623 202.866 130.683V130.696C202.849 130.87 202.832 131.044 202.813 131.218L202.768 131.629L202.679 132.433L202.628 132.84L202.565 133.319C202.542 133.493 202.519 133.668 202.493 133.841C202.467 134.036 202.438 134.23 202.409 134.424L202.34 134.883L202.258 135.403C202.23 135.576 202.2 135.748 202.168 135.92C202.135 136.093 202.109 136.265 202.079 136.437C202.019 136.781 201.956 137.125 201.89 137.468C201.789 137.981 201.686 138.493 201.58 139.005L201.47 139.512C201.434 139.681 201.395 139.851 201.357 140.02C199.224 137.947 196.399 136.818 193.284 136.818C190.457 136.818 187.55 137.753 184.641 139.598C182.711 140.824 180.578 142.996 178.381 145.726C176.346 142.904 173.498 141.029 170.242 140.516C169.621 140.418 168.993 140.368 168.364 140.368C160.925 140.368 156.45 146.821 154.757 152.626C153.917 154.587 149.887 163.519 143.825 169.577C134.596 178.775 132.268 188.254 136.766 198.407ZM215.007 177.998L214.977 178.087C214.901 178.288 214.813 178.484 214.714 178.674C214.639 178.814 214.558 178.95 214.47 179.082C214.303 179.331 214.12 179.569 213.921 179.793C213.875 179.845 213.831 179.897 213.779 179.948C213.707 180.025 213.634 180.101 213.559 180.175C212.213 181.509 210.161 182.679 207.841 183.752C207.578 183.871 207.311 183.99 207.042 184.11L206.774 184.229C206.595 184.308 206.416 184.386 206.228 184.463C206.049 184.541 205.863 184.619 205.677 184.695L205.119 184.925C203.814 185.462 202.477 185.974 201.173 186.479L200.615 186.696L200.064 186.912C199.697 187.055 199.335 187.198 198.979 187.341L198.448 187.555L197.926 187.768L197.67 187.876C197.499 187.947 197.332 188.018 197.165 188.089C193.328 189.736 190.567 191.411 191.147 193.489C191.163 193.548 191.181 193.604 191.201 193.659C191.253 193.813 191.324 193.958 191.413 194.095C191.465 194.176 191.525 194.253 191.592 194.323C192.274 195.032 193.515 194.92 195.08 194.357C195.3 194.276 195.519 194.192 195.736 194.104L195.872 194.048C196.23 193.896 196.609 193.726 196.996 193.542C197.093 193.496 197.191 193.452 197.289 193.401C199.203 192.465 201.372 191.205 203.524 190.058C204.385 189.593 205.258 189.152 206.142 188.733C208.18 187.774 210.096 187.094 211.636 187.094C212.359 187.094 212.997 187.242 213.529 187.582L213.618 187.641C213.952 187.876 214.232 188.178 214.441 188.528C214.482 188.595 214.522 188.666 214.561 188.739C215.322 190.184 214.685 191.68 213.194 193.147C211.763 194.556 209.537 195.937 207.007 197.215C206.819 197.31 206.631 197.405 206.44 197.498C198.91 201.196 189.049 203.981 188.912 204.016C186.284 204.697 182.526 205.591 178.292 206.26L177.666 206.358L177.563 206.373C177.089 206.445 176.614 206.512 176.138 206.574C175.655 206.639 175.167 206.698 174.676 206.753L174.586 206.763C172.806 206.968 171.019 207.104 169.228 207.169H169.202C168.554 207.192 167.907 207.204 167.259 207.204H166.512C165.524 207.191 164.538 207.146 163.553 207.07C163.53 207.07 163.505 207.07 163.482 207.064C163.129 207.037 162.777 207.004 162.425 206.965C162.06 206.926 161.696 206.882 161.333 206.833C161.094 206.801 160.856 206.765 160.618 206.726C160.376 206.687 160.134 206.647 159.893 206.605L159.564 206.543L159.539 206.538C159.192 206.472 158.847 206.399 158.503 206.319C158.303 206.274 158.104 206.23 157.907 206.176L157.788 206.146C157.69 206.122 157.595 206.096 157.498 206.07L157.445 206.056L157.137 205.966C157.025 205.935 156.913 205.901 156.801 205.868L156.762 205.857L156.471 205.768C156.361 205.734 156.251 205.698 156.142 205.662L155.874 205.573L155.677 205.504C155.487 205.437 155.298 205.368 155.111 205.296L154.933 205.226L154.786 205.168C154.502 205.054 154.22 204.935 153.941 204.81L153.756 204.72L153.725 204.706C153.659 204.675 153.594 204.644 153.528 204.617C153.399 204.555 153.271 204.491 153.144 204.426L153.105 204.407L152.921 204.31C152.594 204.139 152.274 203.957 151.96 203.764L151.788 203.658C151.702 203.605 151.616 203.55 151.532 203.494L151.308 203.346L151.067 203.18L150.923 203.077C150.771 202.969 150.622 202.857 150.476 202.742L150.243 202.563C150.15 202.488 150.058 202.412 149.967 202.335C149.89 202.272 149.815 202.206 149.74 202.14L149.734 202.135C149.653 202.064 149.574 201.993 149.495 201.92C149.417 201.849 149.339 201.777 149.263 201.704L149.254 201.695C149.174 201.619 149.096 201.542 149.019 201.463C148.942 201.385 148.863 201.307 148.788 201.227C148.713 201.148 148.636 201.067 148.562 200.984C148.488 200.902 148.42 200.827 148.35 200.746L148.327 200.719C148.259 200.641 148.192 200.562 148.126 200.481C147.983 200.31 147.844 200.135 147.71 199.956C147.575 199.776 147.443 199.592 147.314 199.405L147.191 199.221C147.027 198.981 146.867 198.739 146.712 198.493C146.596 198.316 146.483 198.138 146.373 197.957C146.302 197.844 146.234 197.73 146.166 197.618L146.138 197.572C146.073 197.462 146.009 197.354 145.947 197.245C145.911 197.186 145.877 197.127 145.845 197.066C145.812 197.004 145.774 196.941 145.739 196.878L145.682 196.779L145.647 196.715C145.58 196.595 145.514 196.474 145.45 196.352C145.42 196.298 145.391 196.244 145.36 196.192L145.271 196.019L145.181 195.848C144.956 195.398 144.743 194.942 144.543 194.48L144.472 194.311C144.426 194.198 144.383 194.086 144.337 193.975C144.315 193.921 144.293 193.868 144.274 193.814C144.167 193.537 144.067 193.257 143.975 192.975C143.942 192.874 143.91 192.775 143.88 192.675C143.808 192.448 143.743 192.219 143.685 191.988C143.614 191.719 143.551 191.448 143.498 191.175C143.487 191.12 143.476 191.065 143.467 191.012C143.415 190.745 143.373 190.476 143.34 190.206C143.332 190.153 143.326 190.1 143.32 190.047L143.303 189.885C143.281 189.673 143.264 189.46 143.254 189.247C143.254 189.193 143.249 189.139 143.247 189.087C143.242 188.981 143.24 188.875 143.239 188.769C143.183 184.496 145.345 180.388 149.968 175.767C158.203 167.54 162.997 155.501 162.997 155.501C162.997 155.501 163.126 154.996 163.394 154.269C163.431 154.168 163.47 154.064 163.514 153.955C163.67 153.548 163.846 153.148 164.041 152.758L164.08 152.683C164.246 152.351 164.428 152.027 164.624 151.712C164.67 151.639 164.714 151.567 164.765 151.494C164.912 151.277 165.067 151.065 165.23 150.86C165.319 150.749 165.416 150.639 165.513 150.532C165.552 150.49 165.59 150.448 165.631 150.408C166.108 149.915 166.653 149.513 167.27 149.299L167.348 149.273C167.4 149.256 167.452 149.24 167.505 149.225C167.566 149.209 167.627 149.195 167.69 149.182L167.719 149.176C167.849 149.15 167.981 149.133 168.114 149.124H168.125C168.194 149.124 168.264 149.117 168.335 149.117C168.424 149.117 168.507 149.117 168.594 149.126C168.684 149.134 168.773 149.144 168.863 149.158C169.605 149.276 170.311 149.718 170.919 150.4C171.15 150.66 171.358 150.94 171.54 151.236C171.66 151.428 171.773 151.631 171.88 151.845C171.923 151.934 171.964 152.016 172.004 152.104C172.108 152.33 172.202 152.56 172.284 152.795C172.479 153.345 172.626 153.911 172.723 154.487C172.807 154.992 172.857 155.502 172.873 156.013C172.881 156.286 172.881 156.563 172.873 156.842C172.819 158.14 172.553 159.421 172.086 160.634C172.044 160.745 171.997 160.857 171.952 160.969C171.86 161.195 171.759 161.417 171.65 161.634C171.569 161.799 171.484 161.965 171.392 162.13C171.332 162.24 171.269 162.35 171.206 162.46C171.045 162.734 170.871 163.006 170.684 163.277L170.571 163.439C170.129 164.055 169.637 164.633 169.099 165.167C168.569 165.698 168.001 166.189 167.4 166.637C166.798 167.083 166.233 167.577 165.711 168.114C164.208 169.691 163.858 171.083 164.196 172.138C164.25 172.304 164.321 172.465 164.407 172.617C164.508 172.791 164.628 172.951 164.764 173.097L164.817 173.152L164.871 173.206C164.925 173.258 164.982 173.309 165.043 173.359L165.103 173.407C165.248 173.519 165.402 173.619 165.563 173.707C165.61 173.732 165.652 173.757 165.705 173.781C165.879 173.866 166.058 173.939 166.242 173.998C166.293 174.015 166.344 174.03 166.396 174.046L166.461 174.063L166.551 174.087L166.628 174.106L166.712 174.124L166.795 174.141L166.874 174.154C166.932 174.164 166.992 174.174 167.052 174.181L167.109 174.19L167.213 174.2L167.277 174.207L167.382 174.214H167.444L167.554 174.22H167.9L167.999 174.214L168.113 174.207L168.252 174.194L168.382 174.179C168.412 174.179 168.442 174.171 168.472 174.165C168.872 174.107 169.264 174.001 169.639 173.849L169.798 173.782C169.887 173.743 169.977 173.702 170.059 173.658C170.235 173.57 170.406 173.47 170.57 173.361C170.799 173.211 171.015 173.043 171.217 172.858C171.265 172.815 171.312 172.769 171.358 172.725C171.381 172.703 171.403 172.682 171.425 172.658C171.469 172.613 171.514 172.569 171.558 172.52C171.878 172.168 172.155 171.78 172.383 171.363C174.34 167.804 176.391 164.298 178.534 160.849L178.828 160.378L179.125 159.907C179.273 159.668 179.423 159.433 179.572 159.199L179.722 158.965C180.22 158.185 180.726 157.41 181.241 156.641L181.546 156.185C182.158 155.278 182.768 154.396 183.373 153.558L183.674 153.143C184.332 152.236 185.017 151.348 185.728 150.482L186.01 150.144C186.057 150.088 186.1 150.032 186.151 149.978C186.244 149.868 186.337 149.761 186.428 149.657C186.474 149.604 186.517 149.552 186.566 149.5L186.834 149.198L186.968 149.051C187.103 148.906 187.235 148.767 187.365 148.634C187.455 148.544 187.538 148.455 187.624 148.371C188.131 147.853 188.69 147.388 189.293 146.985L189.433 146.895C189.567 146.805 189.706 146.721 189.848 146.645C192.212 145.303 194.169 145.204 195.296 146.331C195.978 147.013 196.356 148.144 196.335 149.718C196.335 149.787 196.335 149.857 196.33 149.929V150.006C196.33 150.078 196.324 150.15 196.318 150.223C196.318 150.313 196.308 150.402 196.299 150.492C196.29 150.581 196.285 150.649 196.276 150.729C196.276 150.751 196.272 150.774 196.268 150.798C196.262 150.867 196.253 150.938 196.243 151.009C196.243 151.03 196.243 151.052 196.235 151.074C196.224 151.169 196.21 151.263 196.194 151.357C196.183 151.447 196.168 151.531 196.152 151.619L196.126 151.768C196.1 151.91 196.067 152.05 196.026 152.188C195.948 152.447 195.854 152.7 195.743 152.946C195.588 153.284 195.417 153.613 195.229 153.933C195.125 154.111 195.018 154.286 194.907 154.459C194.793 154.638 194.673 154.819 194.549 155.002C194.233 155.454 193.905 155.897 193.564 156.33L193.408 156.527C192.852 157.22 192.278 157.899 191.686 158.562L191.499 158.772C191.247 159.053 190.991 159.336 190.729 159.62L190.532 159.834C190.401 159.977 190.264 160.12 190.132 160.264C190.001 160.407 189.864 160.552 189.726 160.697L189.315 161.13L188.898 161.566L188.478 162.002C188.196 162.294 187.913 162.586 187.628 162.878C183.573 167.037 179.301 171.182 177.855 173.766C177.758 173.934 177.671 174.108 177.593 174.285C177.387 174.755 177.301 175.157 177.36 175.482C177.379 175.589 177.416 175.691 177.471 175.785C177.552 175.926 177.651 176.056 177.766 176.172C177.819 176.224 177.875 176.272 177.934 176.316C178.232 176.528 178.591 176.637 178.957 176.627H179.071L179.188 176.618L179.305 176.605L179.402 176.591C179.415 176.589 179.429 176.587 179.442 176.583L179.531 176.566L179.554 176.561L179.653 176.54L179.688 176.531C179.723 176.522 179.757 176.513 179.792 176.503C179.827 176.493 179.875 176.48 179.917 176.466C180.093 176.413 180.265 176.35 180.434 176.278C180.523 176.242 180.61 176.203 180.696 176.161C180.741 176.141 180.786 176.12 180.828 176.098L180.962 176.032C181.282 175.866 181.594 175.685 181.898 175.491L182.031 175.401C182.076 175.373 182.121 175.344 182.164 175.312L182.297 175.223L182.368 175.174L182.56 175.039C182.739 174.916 182.906 174.789 183.075 174.66L183.09 174.648L183.359 174.44C183.726 174.15 184.074 173.858 184.39 173.583L184.6 173.399L184.619 173.381L184.729 173.284C184.987 173.052 185.217 172.836 185.408 172.658L185.487 172.581C185.556 172.516 185.619 172.455 185.676 172.403L185.788 172.292L185.828 172.253L185.839 172.242L185.956 172.125L186.03 172.048L186.039 172.041L186.074 172.009L186.118 171.969L186.132 171.956L186.169 171.922L186.373 171.743L186.487 171.641C186.548 171.588 186.607 171.534 186.666 171.479L186.802 171.358C186.827 171.338 186.851 171.316 186.876 171.294L187.019 171.169L187.229 170.984L187.341 170.887C187.776 170.509 188.305 170.052 188.913 169.537L189.162 169.326L189.573 168.981L189.994 168.63C190.544 168.173 191.136 167.688 191.762 167.185L192.173 166.855C192.523 166.576 192.882 166.292 193.246 166.006C193.393 165.891 193.542 165.776 193.694 165.662C194.066 165.373 194.44 165.086 194.817 164.803C195.675 164.155 196.56 163.506 197.456 162.874L197.84 162.606C198.109 162.421 198.377 162.235 198.645 162.054L198.888 161.89C199.367 161.565 199.853 161.248 200.343 160.939L200.586 160.786L200.827 160.636C201.069 160.486 201.309 160.339 201.548 160.196L201.787 160.053L202.265 159.775L202.734 159.506L202.829 159.454L203.2 159.25C203.355 159.166 203.509 159.085 203.663 159.006L203.892 158.888L204.115 158.776C204.193 158.739 204.27 158.7 204.346 158.663C204.848 158.415 205.36 158.187 205.88 157.979C206.021 157.919 206.161 157.865 206.3 157.818L206.71 157.674C206.833 157.633 206.953 157.594 207.068 157.559L207.108 157.547C207.17 157.527 207.232 157.509 207.293 157.493L207.311 157.488C207.439 157.451 207.566 157.419 207.691 157.389H207.7C208.054 157.304 208.414 157.243 208.777 157.206C208.944 157.189 209.111 157.18 209.279 157.181H209.363C209.475 157.181 209.583 157.188 209.69 157.199C209.739 157.199 209.788 157.209 209.836 157.215H209.856C209.904 157.221 209.952 157.228 210 157.239C210.047 157.248 210.095 157.256 210.141 157.267H210.156C210.203 157.277 210.245 157.289 210.294 157.303C210.548 157.374 210.79 157.484 211.012 157.628C211.121 157.699 211.223 157.779 211.317 157.868L211.344 157.894C211.362 157.91 211.379 157.927 211.395 157.944L211.444 157.997C211.846 158.418 212.178 158.901 212.428 159.427L212.466 159.517C212.551 159.717 212.618 159.924 212.666 160.135C212.808 160.781 212.753 161.455 212.508 162.07C212.415 162.318 212.302 162.557 212.169 162.785C211.858 163.309 211.489 163.796 211.07 164.237L210.981 164.332C210.848 164.472 210.71 164.612 210.565 164.752C210.501 164.815 210.434 164.877 210.367 164.94L210.162 165.129L210.055 165.224C209.797 165.454 209.532 165.677 209.263 165.893C209.1 166.025 208.936 166.154 208.77 166.281C208.184 166.729 207.587 167.161 206.979 167.578C206.612 167.83 206.242 168.077 205.869 168.321C204.95 168.924 204.021 169.512 203.083 170.084C201.115 171.294 198.934 172.588 196.609 173.995L196.007 174.36C195.348 174.762 194.726 175.146 194.14 175.512L193.845 175.697L193.287 176.055C192.917 176.292 192.548 176.531 192.179 176.77L191.882 176.966C191.737 177.06 191.593 177.156 191.449 177.252L191.308 177.342L190.876 177.633L190.647 177.79L190.379 177.976L190.13 178.149C189.713 178.444 189.325 178.725 188.968 178.992L188.834 179.094C188.624 179.253 188.416 179.415 188.211 179.58C187.902 179.829 187.62 180.067 187.367 180.296L187.243 180.409C187.172 180.474 187.102 180.539 187.035 180.603C186.989 180.648 186.946 180.693 186.898 180.736L186.834 180.8C186.691 180.944 186.551 181.091 186.416 181.242L186.35 181.318C186.203 181.488 186.075 181.651 185.963 181.81L185.913 181.881C185.825 182.009 185.744 182.141 185.671 182.277C185.652 182.311 185.635 182.345 185.618 182.379L185.569 182.481L185.536 182.555L185.515 182.605L185.498 182.65L185.475 182.711C185.413 182.88 185.37 183.056 185.345 183.234L185.337 183.296L185.331 183.354V183.669C185.331 183.695 185.331 183.721 185.338 183.749L185.343 183.797C185.343 183.823 185.349 183.848 185.353 183.876C185.357 183.902 185.364 183.949 185.372 183.986V183.991C185.379 184.026 185.386 184.06 185.395 184.095C185.404 184.13 185.413 184.17 185.424 184.206C185.443 184.277 185.467 184.347 185.492 184.417C185.508 184.459 185.523 184.5 185.54 184.541C185.54 184.549 185.546 184.558 185.55 184.566L185.586 184.647L185.636 184.758C185.69 184.873 185.749 184.985 185.813 185.094L185.879 185.208L185.947 185.322C185.959 185.341 185.973 185.359 185.988 185.376L186.01 185.399L186.035 185.422L186.061 185.442C186.099 185.469 186.14 185.49 186.183 185.505C186.206 185.513 186.23 185.519 186.254 185.525C186.831 185.655 188.017 185.178 189.593 184.346C189.682 184.298 189.78 184.248 189.875 184.196L190.355 183.934L190.589 183.804C190.756 183.715 190.926 183.614 191.1 183.515L191.417 183.336C193.5 182.137 195.988 180.597 198.56 179.093C198.801 178.952 199.043 178.811 199.285 178.672L199.771 178.361C200.335 178.038 200.902 177.719 201.471 177.404C202.188 177.01 202.91 176.626 203.639 176.254L204.115 176.013C204.431 175.857 204.744 175.705 205.053 175.557C205.651 175.273 206.256 175.003 206.868 174.748L207.203 174.612L207.243 174.596C209.018 173.893 210.627 173.459 211.929 173.459C212.21 173.456 212.492 173.48 212.769 173.528H212.778C212.867 173.544 212.948 173.562 213.031 173.582H213.046C213.259 173.636 213.466 173.713 213.662 173.812C213.937 173.954 214.184 174.143 214.393 174.371C214.489 174.477 214.574 174.592 214.649 174.714C214.789 174.929 214.899 175.162 214.978 175.406C215.01 175.501 215.038 175.594 215.067 175.693C215.278 176.45 215.257 177.253 215.007 177.998Z" fill="#FF9D00"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M203.21 123.685V123.194C203.21 81.34 169.292 47.411 127.435 47.411C85.5791 47.411 51.648 81.342 51.648 123.194V123.358C51.646 123.467 51.645 123.576 51.648 123.685C51.6529 123.848 51.6546 124.011 51.653 124.174L51.6581 124.534L51.661 124.663C51.661 124.723 51.6631 124.782 51.6651 124.842C51.6681 124.937 51.67 125.033 51.67 125.128L51.681 125.517L51.697 125.974L51.702 126.124L51.722 126.597V126.62C51.73 126.805 51.7401 126.989 51.7491 127.173L51.75 127.187C51.76 127.375 51.7701 127.564 51.7821 127.753C51.7921 127.927 51.802 128.101 51.815 128.275L51.8171 128.306C51.8258 128.455 51.8358 128.605 51.847 128.754L51.85 128.794L51.883 129.226L51.8861 129.254C51.8921 129.338 51.898 129.422 51.906 129.503C51.9658 130.224 52.0355 130.945 52.1151 131.664L52.12 131.709L52.181 132.238L52.2491 132.793L52.299 133.17L52.322 133.347C52.3753 133.755 52.433 134.162 52.495 134.568L52.4991 134.595L52.558 134.979C52.8435 136.808 53.1971 138.626 53.618 140.429L53.6231 140.451L53.655 140.586L53.746 140.971L53.802 140.904C56.002 138.274 59.158 136.824 62.689 136.824C65.519 136.824 68.4221 137.76 71.3321 139.605C73.2621 140.831 75.3961 143.002 77.5921 145.733C79.6241 142.911 82.4721 141.035 85.7301 140.523C86.3513 140.425 86.9792 140.376 87.6081 140.375C95.0441 140.375 99.523 146.828 101.215 152.633C102.051 154.594 106.08 163.526 112.156 169.568C121.392 178.795 123.703 188.316 119.132 198.511H119.148C119.459 198.546 119.772 198.578 120.087 198.607C120.274 198.625 120.46 198.643 120.648 198.659L120.714 198.665L121.127 198.7L121.507 198.73C121.869 198.758 122.232 198.784 122.596 198.807L122.885 198.824L123.114 198.838L123.256 198.846L123.703 198.869L123.825 198.874L124.294 198.895L124.816 198.915L125.235 198.927L125.305 198.929C125.394 198.933 125.483 198.936 125.572 198.936L125.668 198.939C126.258 198.953 126.847 198.96 127.437 198.959H128.063L128.51 198.954C128.62 198.949 128.729 198.949 128.84 198.949H129.014L129.165 198.945C129.224 198.943 129.283 198.941 129.343 198.941H129.522L129.873 198.932L130.401 198.914L130.982 198.888C131.15 198.882 131.316 198.873 131.482 198.865L131.661 198.854L131.927 198.84L132.083 198.831L132.201 198.823L132.738 198.788L133.274 198.749L133.761 198.71L134.103 198.681L134.479 198.647C135.107 198.591 135.733 198.525 136.359 198.45L136.786 198.399C132.287 188.247 134.616 178.767 143.813 169.577C149.876 163.519 153.905 154.587 154.745 152.625C156.438 146.821 160.914 140.368 168.352 140.368C168.981 140.368 169.61 140.418 170.231 140.516C173.486 141.028 176.334 142.904 178.369 145.726C180.566 142.996 182.699 140.823 184.63 139.597C187.539 137.753 190.445 136.817 193.272 136.817C196.388 136.817 199.212 137.947 201.345 140.02C201.384 139.851 201.422 139.682 201.459 139.512L201.568 139.006C201.607 138.821 201.646 138.636 201.683 138.451C201.749 138.124 201.815 137.797 201.878 137.467C201.944 137.125 202.007 136.781 202.067 136.437L202.098 136.251C202.117 136.141 202.135 136.031 202.156 135.92C202.19 135.748 202.218 135.576 202.246 135.402L202.257 135.336L202.328 134.883L202.398 134.424V134.42C202.449 134.081 202.497 133.742 202.542 133.403L202.553 133.319L202.616 132.841L202.667 132.433L202.757 131.629L202.792 131.306L202.801 131.218C202.82 131.044 202.838 130.87 202.854 130.696V130.682C202.867 130.544 202.881 130.405 202.893 130.266C202.964 129.478 203.024 128.686 203.072 127.891C203.081 127.761 203.088 127.63 203.096 127.499V127.493L203.122 127.002L203.128 126.892C203.144 126.56 203.158 126.228 203.169 125.896V125.884L203.174 125.754C203.179 125.645 203.183 125.535 203.183 125.425L203.185 125.381C203.189 125.278 203.193 125.172 203.193 125.067L203.196 124.977C203.199 124.872 203.202 124.768 203.202 124.663L203.204 124.574C203.207 124.441 203.21 124.307 203.21 124.174V123.685ZM108.638 199.391C114.64 190.59 114.214 183.984 105.98 175.754C97.7441 167.523 92.951 155.487 92.951 155.487C92.951 155.487 91.1621 148.496 87.0821 149.138C83.0021 149.78 80.0091 160.227 88.5521 166.622C97.0941 173.017 86.8521 177.353 83.5641 171.352C80.2761 165.35 71.299 149.923 66.645 146.972C61.991 144.021 58.718 145.675 59.815 151.757C60.36 154.776 65.4281 159.929 70.1631 164.743C74.9671 169.627 79.428 174.163 78.474 175.768C76.581 178.955 69.9141 172.023 69.9141 172.023C69.9141 172.023 49.038 153.025 44.494 157.976C40.304 162.539 46.765 166.418 56.7211 172.397C57.5671 172.905 58.4391 173.429 59.3321 173.969C70.7231 180.865 71.609 182.684 69.992 185.293C69.395 186.257 65.582 183.968 60.892 181.153C52.897 176.352 42.3551 170.023 40.8661 175.688C39.5781 180.591 47.334 183.595 54.368 186.32C60.228 188.59 65.5881 190.666 64.7991 193.484C63.9821 196.406 59.5531 193.969 54.7121 191.305C49.2771 188.314 43.3221 185.038 41.3731 188.735C37.6901 195.725 66.7831 203.954 67.0231 204.015C76.4231 206.453 100.295 211.619 108.638 199.391ZM147.303 199.391C141.301 190.59 141.727 183.984 149.962 175.754C158.197 167.523 162.99 155.487 162.99 155.487C162.99 155.487 164.779 148.496 168.859 149.138C172.939 149.78 175.932 160.227 167.39 166.622C158.847 173.017 169.089 177.353 172.377 171.352C175.666 165.35 184.637 149.923 189.291 146.972C193.945 144.021 197.22 145.675 196.122 151.757C195.578 154.776 190.509 159.929 185.774 164.744C180.97 169.628 176.509 174.163 177.462 175.768C179.355 178.955 186.027 172.019 186.027 172.019C186.027 172.019 206.902 153.022 211.448 157.973C215.637 162.535 209.176 166.415 199.219 172.394C198.348 172.917 197.478 173.441 196.609 173.966C185.218 180.862 184.332 182.681 185.948 185.289C186.546 186.254 190.359 183.964 195.048 181.149C203.044 176.349 213.586 170.019 215.075 175.685C216.364 180.588 208.607 183.592 201.573 186.317C195.713 188.587 190.353 190.663 191.141 193.481C191.957 196.402 196.385 193.965 201.225 191.301C206.66 188.31 212.616 185.032 214.564 188.732C218.248 195.726 189.15 203.947 188.915 204.007C179.515 206.453 155.643 211.619 147.303 199.391Z" fill="#FFD21E"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M152.047 102.567C153.229 102.985 154.108 104.257 154.944 105.468C156.074 107.104 157.126 108.627 158.74 107.769C160.644 106.756 162.205 105.202 163.225 103.302C164.246 101.402 164.681 99.2427 164.475 97.096C164.321 95.4908 163.813 93.9398 162.987 92.5548C162.161 91.1697 161.038 89.985 159.7 89.0862C158.361 88.1874 156.839 87.5968 155.245 87.3569C153.65 87.117 152.022 87.2339 150.478 87.699C148.934 88.1639 147.513 88.9653 146.316 90.0455C145.119 91.1257 144.176 92.4578 143.556 93.946C142.936 95.4342 142.653 97.0415 142.728 98.652C142.804 100.263 143.235 101.836 143.992 103.26C144.74 104.667 146.4 104.003 148.152 103.302C149.525 102.753 150.956 102.181 152.047 102.567ZM100.672 102.567C99.49 102.985 98.611 104.258 97.775 105.468C96.645 107.105 95.592 108.627 93.979 107.769C91.5845 106.501 89.7482 104.386 88.8278 101.838C87.9075 99.2895 87.9692 96.4896 89.0008 93.9841C90.0324 91.4786 91.9601 89.4471 94.408 88.2855C96.856 87.1239 99.6488 86.9156 102.242 87.701C104.307 88.3228 106.141 89.5427 107.513 91.2065C108.885 92.8704 109.732 94.9035 109.949 97.049C110.165 99.1945 109.74 101.356 108.728 103.26C107.979 104.667 106.319 104.003 104.567 103.303C103.193 102.753 101.764 102.181 100.672 102.567ZM144.099 149.318C152.242 142.903 155.233 132.429 155.233 125.977C155.233 120.877 151.802 122.482 146.309 125.202L145.999 125.355C140.957 127.852 134.245 131.177 126.877 131.177C119.508 131.177 112.796 127.852 107.755 125.354C102.084 122.545 98.527 120.783 98.527 125.978C98.527 132.634 101.709 143.563 110.443 149.912C111.596 147.573 113.219 145.497 115.211 143.813C117.202 142.129 119.52 140.874 122.018 140.126C122.89 139.866 123.788 141.367 124.707 142.904C125.594 144.386 126.501 145.902 127.423 145.902C128.406 145.902 129.371 144.408 130.314 142.95C131.299 141.425 132.26 139.94 133.189 140.237C137.864 141.738 141.775 144.993 144.099 149.318Z" fill="#32343D"/>
+<path d="M144.097 149.317C139.856 152.659 134.219 154.9 126.878 154.9C119.981 154.9 114.587 152.922 110.443 149.911C111.596 147.572 113.219 145.495 115.211 143.812C117.202 142.128 119.52 140.873 122.018 140.125C123.73 139.614 125.545 145.901 127.423 145.901C129.433 145.901 131.37 139.655 133.189 140.236C137.863 141.738 141.773 144.993 144.097 149.317Z" fill="#FF323D"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M81.2 111.64C80.2312 112.288 79.1173 112.687 77.9572 112.801C76.7971 112.916 75.6267 112.742 74.55 112.295C73.6893 111.94 72.9072 111.418 72.2488 110.759C71.5903 110.101 71.0684 109.319 70.713 108.458C70.267 107.381 70.0935 106.211 70.2082 105.051C70.3228 103.891 70.7219 102.777 71.37 101.808C72.1488 100.642 73.2558 99.7333 74.5512 99.1967C75.8466 98.6601 77.272 98.5197 78.6471 98.7935C80.0223 99.0672 81.2853 99.7427 82.2764 100.734C83.2675 101.726 83.9422 102.99 84.215 104.365C84.4883 105.74 84.3477 107.165 83.8113 108.46C83.2748 109.755 82.3654 110.861 81.2 111.64ZM182.613 111.64C181.644 112.288 180.53 112.687 179.37 112.801C178.209 112.916 177.039 112.742 175.962 112.295C175.101 111.939 174.319 111.418 173.661 110.759C173.003 110.101 172.481 109.319 172.125 108.458C171.68 107.381 171.507 106.211 171.621 105.051C171.736 103.891 172.135 102.777 172.782 101.808C173.364 100.936 174.133 100.205 175.032 99.6658C175.931 99.1269 176.938 98.7942 177.981 98.6917C179.025 98.5891 180.078 98.7193 181.064 99.0728C182.051 99.4264 182.947 99.9944 183.688 100.736C184.68 101.727 185.355 102.99 185.628 104.365C185.902 105.74 185.761 107.165 185.224 108.46C184.687 109.755 183.779 110.861 182.613 111.64Z" fill="#FFAD03"/>
+</svg>
diff --git a/studio/frontend/public/hub/profile/logo/ibm.png b/studio/frontend/public/hub/profile/logo/ibm.png
new file mode 100644
index 0000000000000000000000000000000000000000..31c965f0b3e6f400a47b01de00657624ab1d628f
GIT binary patch
literal 17084
zcmeEtQ+Fj?)9v1|ZQEAIwzFf~=olT_wv&!++uBJw>DW%k?4YCXdH=!r0q3G>U92%`
z)R;GGR?WGhRh4Cs5eN_f006R_tR(2abMk)y2k~E~;OCnH01)JCB_vecKr-TFa#9jJ
z?0h^t%p5H20Dx?CzPguA>NAe;?z1JTmiXFjQ>H^OfP%6XZW2xRCt3=?Gz<+xbSyjy
zK?@5TJx^A1G-Me;Hb3g1h_2IGEG9}XR?~p@nslq8&Hu;E)z#bTTkmP!>HD0|JZca+
z22JwGPdfk~C|r<#jWkh3c66#Q2m)Jn4~h)!WM<eJdJF)#h4k?baBmcO2R3{MKmeSV
zS*S23_P;{ARcW*VWXXU%3XD@kU=j#0$)Yid1(?JGG^)2)AOO+;00$pGaSA{+GT`!2
zP8b@nR+YMi3t0O}R0Ri!2LiI`WT+rSdjKYy!5}7x!C^pAttbTx)L=a@NVlCs1|p~r
z8sM3rlY}a20tm_$X95Grcp(51B$%_1WQveQY>NYXRmRTYow7i{;7s~#rotj8R%iMz
z0<Zhqy#w-tVTUGhQ(Ss9EBGUdyv$rmOxaUN#W^GZfZ%mu=#y6@>Gb4i|HSIl;pTDd
z=coPccM4(hyWP*;I0z^Jn)3Y3hVk+73Z(M{u+d|{zDggkp#`wneKq9VgfG%V`1Rv8
z)`$09l%$|obyAR+2mulCirTEWkL@s4_=|J@`(A9o(|@<0n?G&=E;*vvb%Q0LA1<a&
zp7o%F(-|mncBki4%Fl`Lz>fs_g#)f8119X4JDuoGRSKmEpDs|cB>7bO0mfM%#~o?L
z2Yjj*GN3j>Wl*^twr$2?FyI;p5sRX;=m`)FcwmkrKuiXpS#xptJOco!1Fwmqj6lF_
zX6YdS(EA6^pfU|taU2c+kSq#jXcU7*8p5g_M9CW>?j6L1Fols6MWPxML=%TO3L-)%
z#>)`H*BInqgKBGpBq&19*+**~V&_FZ-NP^lzHr8cF~KVs#_NrMhZ38F!!#x5k3u&~
zSfiMO!_7{BqA-=^N(m|@JBz|nqZpfXErqBOw@WsZrMzc$#o~)M5dD|5IZ4J5^B&VH
z!=4u0tOmIR;UU^pNlFkiUgWmm&V_0il=0JkfuNN{D5(8s#e%{g4|jlnOoDmP0y~OT
z+`6ejT%?pqv<?By1djQ!4!2e!w>h!SH&1NB!2;78I4X$PAk0fRqcF5#hmfQs868C(
ziAw5A%2teSIBodQF!o_uiquM#R_Y%ZucO{({7p$Z(zP_#<Rs(;)JC)@n8vBHR47v^
zN6HA~)JYt2h;sI_o3hNM>ZQVqXtsHZG#5#ZQ#(g+%|W$fnaLeVs7Wd*Z&M>j9a#Kh
zQ3s0fKdC^aX&Ca{mLkVcWrZB#*+tcAvsDF4aMe-#g?e(1MV_jx>XB8LTpl^pv$;4D
zGo{QW%fE7Lt!<xeSkK(M;kQFcq%wbHF53TrJv%)Mee^;?jzA8bkTs*jx5xLzufXfT
zXU$eDhyI<JJ*mOA%0ZZIorRk9T~mkQiNOy$c^V^~KV2(5ApNvjL(@%DWZ9=0QKLo^
zwZ=%xzg$|gMfI=>ehH^$xr$h`r;4Y34&((&RGn8dF6lS^2>EA@+#C@uT@)c(qG8@K
zjvr5sGtOaorz5`Nss(w$WS^yErr-Q}sptv)M(D}vtEevFR&7;lm28!N;xY?F8E@LV
z<y+5_pCg|`p7UjfWENp=TCuCMstc(5w((=5f5Ys`^$O?eV&lfcIbSrNDgQ6OBmc7p
zd^b<GT6cK&rpNrb@Ne@ApELNs(|=LUwijgnIzE>C#XY}Sxmh6n#>NH5lZ5ZU&TD=P
zPBQ;vpJm&*a2vK?i9Tb~ojht&vLIJN+evdBX?@7;jVo+b`<=+FmTSjy%U;mb%$8%b
zbhLErsGoi|%|6Gfd!hBWI~Y94v{k!SJ9U}Bx148RVA{XlyZIg;UM7_{CLhZaJCU)G
z;Wq=Fp_K7lo24bJ<)igiYqeHx#o&VJ!f{30L6uND7b%xNcc#6vF1K#fGuLq!>i{c}
zev$sKy3+>x<@+VVWzHqc72lKT6ZMnh(>yVl2!nV<z+J%4)!hT^>EPUZQM%7HQZ-sN
za;9xfXkF}<|G<q~u8=f?k?EO<tL|74Q{hzjV<!EW;JSOU?f2i3+@9R6x^>5;ZLrXo
zf6bc`OD^G*;fT<U*yHW9&VdW~Fux+VV)!BHl-0=7NZ07Ck3^*<kEURS&2e&bRDZ8;
z#@B>jSjh6<+!>_sxG+TFkHX0Q@_ve4p?=DMm4NI3*!O}rfqyd}i7x~DKKD3x%Frgj
zA>c8vFPI>>1=1dp6e=6443--@9=ZpH6-gLd90?v-m((@&`ylQ;;j204mNiq(0`@dq
zKDHj=KQ=IpBFPGRLc~1WE?U6%@>j((a64Soo{U3OC#fxdHtwrG7Ci$;HOskLtGc_3
z`!mx@?UC-Abzj0=VpUw1z@}ZhtEY9Xodd|h{4%#QsI$5=*gNt?>Mj$*9g_<FD*9-2
zZB!`w&<*0$A%`>XC`Tj1-Ms#I>t`44$=TdYftR2zw{DUjZ+I3)X0ym~D4Dn_E1t@6
zg_9C7=6zUhxQbN&&-kBeO&y)`f+;8YTIo-`+XDU)|7;>uq&>zt;Z;D4KFRngU6c<>
zT9PX}we#yP>&$#<d1-kiAY|K&R>oDf4!RB%D@Mjt<RhOG$7#aU$m!=J%2&6CO>Bp7
z#f6eqP`xS&jv{L%qqjbuzIUf=pRC>z=dRV~`70%22##N0Qln~TW6N5nx9;5@#eh@~
z4rQ!5t``ftA*kEJ+xB+Rf5v8}Ipah1KnJ9GZ|Adhp8yJ7EGv^>4AJIFuS%PmajJjR
z>oUhSO}EgzvCCZ6*9v67O*gJ}uC1(pX_W3fInY)%UiSOz<G8W0Bi}K7bs>9Edf`<2
ztUJ&k-)ASb{43%XxsLEI{+Q6%QGUn0_=nx!gxS{F=~+l_Q|>E$aC`0MeKAkT(~tZ>
z!x^oQx|)vub()Qpfo(6}2b54^Y=NDdw9DQ$MsIEVJ}LjdPK(ze+ld5bgxv!t0o$E2
zUMgb+iN0mNuuoDq7k2L79kv<<2Abg=K|Jv!vi#1+xk2AIa<6i{+MM+mP=>{hhiG@p
z{d^Bq{}j)SY>mwBW(Risg}adTVO-=N@Tg@jaV!!l?z{ODSCUU`L@d+a@fC2xerWD7
z!JVjGP?S$6boY7`l6qKSQBjbuEF!d&z2)<)_?~TVsAkw_Eiqppg6n>**kSxU^{{iA
zXn5P}{7CU^wn^QgP$yI`BopBLu`k=8|NX-9dFD!6u-^Sq=|W)P=6B#fyTN6*)t6Nk
z!$P0FoAFD+4kwyzqE71Wzb~FoSGZmX*NR()KN7tg-upK`&SC$do(HymHdzij?!A}{
zn#_;rqTZmuM;3ghef^HyUz7pMEK^ET#wX^Jk`f{l^xa#`rS4ZWS76Rh2WWlyT)5So
z?tUD+Da`A<uiYZP#?BAa`&2!+-qchz@J~=qkoL~`2;G&x*UfGE-*nz|?@siQX4Ack
zeyTn!{4<}Z_@(kJeCqf4&iWko@Ww2|JO3ZIgm;$JbprqpG5;4pKu#VW0KkhcCn=`k
zop;se+vu>aOZxQI|Gloy%d61s`fV;BKi-OqvKUr2rT{H8EZM=q0op;L5+Y>A#lSL3
zVhqcY0R=mC)I~Gu3W1#kl-@~%nMtZ4t7<U_$0jR_#zX})<1%~9dIslbzxAI!n%}go
zJRc{v{jYfU&6dD9OMK-=O}+2@SqrIs!-xLvzm;db)@N;Op&t$e@99pWi6RAmqL<AX
z|9|>_!r-NvJR_OlOuHM~*rzerQDIff#9Zi-$AcW8Fgxu>4H(>TV$*w9WUXmgg9}=`
z_wxEte4J`5O?gkrNhn$k7>sP_LW%XY{Q2i9uk~Jh>1l`9$ololAz;)gP6r8E1Gg@{
z{nX|vltl!&fj<UmqQGFY1MVD!m%_ug%Q_wjuzt=%MEK9~A{}5O9PQwf#AM9(RRYk-
zMhfBpj(6tcN-b?~pQsd<Zl|9<8`?ScGaP5Q1t?O|(L<U!V&XdzCP+k|tbTt>2hiPX
zn8alY3@4hKkAlFvh^H0$b_d1dbGsZ~Blc&|nD{0S&o*xTEMBc3UwM*Ri^wq2O|zw)
zpSeza#eeGN9Sd!3!Fa?cB-{NjGpz%CC7JxDuk5IX%09Ea{Ey5Y#NK#>>hV0HwPoWj
zv_GO|0VZWyY1BMH;W`&{9Zn=u%`s_cKuZ7}*36cji~*xcM!k6}*)013$?!W<$t(22
zHp^FW-}{|*)|AO80OSh+Sv11o!OS!>c3q#AodtVj=Tosq&9}<EHE6=|Cl9N&d&q{+
zPY28hgpl=mA7AR2J=b}d+L;7^h)8f|8Ul~EI^1=>L6YD|=@hHgoek@MZ0uOS;<kG#
z>+;+FrSismFuz=L4#a1*-BItl(3(u-3(hFLH-i~y%dy<P%pQA>xrr{y-Cu!;O3#&5
zE;=V3>%KE!3sy3LYh4;rK<)jZvG{HbQN%zIz(a^DB_?UbMkz0?>-Lk{(lok4vipxa
z9YFtY#F~R}3)~)2cuq?8b4m((N2qX}O<A!&{*tme%#B<qyZWL}t`UUKB5nl!WO03o
z8%g$js}n_g88w8ND(e9v*eW>;x6W`NfCmD}j15wPyP++7mTst*w{5mkmoQbwlwdl9
zNl~G~Or0l+pBhj@{Wd+$=ruu*i=Ujl*jQRA){Cm-4klk238^w9WXwWE{RLeknh#N5
zqX~N*H3oxNMaGGKBCf7DZNiSz?5QOZ@x&8n!IN49d1@ZxD$@|YMuDm3U^P-5w{WHa
zC(G@G?Z|O2&Xm)NUSFmUg=gAUIfEGMNusgK(4YoSCNowEZy~qJ?0$`vOO8W`+_zfp
z$<f}r8wP1@HwBbUTjBoOIm(kD3IKSAu=(KSqCc>$=^hOCtPvR~%kB^~!C)OO{8jf|
z?rol_(|@S<nR9|BVniQ1vW_pTO4>yy02ZiW?6Y<7GbatohD4VT{`z1m@F~`xy_+y~
zh{gm96kNNpcam0uHXBQhvb;({*5P1`ofQx9SOgReYRAkzFV6KB4tzPH=!?Kg6f~DB
z9-1#bU<17tnoe~GMYC+N+|Zksr-#6&kJCe}ouo*uAM`WRY8!2_S6aW_sZs3SM+yV3
z?@noNEoNs2{u*yRb3d1GG=>C8vW1YO#<;b&&44v^=!S_s#<}ZNZbyH6KgO<-e3q~h
zDdu5$QLnRWOxe_9ox)SwGlb86J`CJfH~7NMLMab=b=FgeW2#;4xg{Rbem%!>=25#@
zwMx6PBjr^|z?rt|D}A1zZhuv`IHTW#q!V6aZR%>FEU5q_q;FIKC&nTdG6M8{X6{S?
zc{Es)uVOdr9Zy`(?u+`sia`T-!(|%aBpST=9zR=3je~DEk_?y68{u6>3m(Af3<0qO
zJWa^VZALtEnh7cjK$QMmQlBsUH>)xi@bs<!agvi2<WabgG{sKWrXXwv8K;oj`{C4k
zv7=>re^KZ~j8Qa5$hsFg@JHlrNyo<GXvnj)Dt{|qACn1OKd|36GVrK%33Mea51~wS
z3W9*of>^y46Y8-o@r}P81i2#q2Rb);1OYuVxiWbWhRw(MjTR1#D8}R<l*<|{7f(W7
z(4j-EQV&)htK+EX`yx*`pO*5hWZf2r#FXf0sI|*;VNL&?ivQL8C&K60*TZ7~W~X5C
z21zdKToe*flR_4C<IcKbl*1+)oCMbQz>9SezxM+h?`AnhT;y0<4hVgBp0|vK0ad!Z
zli=+GPcY*jaIhqrXwZ-{_8**!2!Ro+C`${p94X0U$fBe0U{x*RUFNry5JO)bWH8p8
zp{$-3h(R;{=NXgLLq`^Cr_<z4!fLsp>0%0lc_nfMgWpZZA>qJ&f8oo-Y>CRZU?Mt(
zU~D!k32|<#-Xb(uuhURNASEvuM*pkOOIKj-&v2*#qd*&M88Nq;uD<WygkfqA!}Ak5
z+Z{6h1doA=swN0vy!d7|cZn02jkg-YTTFbhvD*Ge53e%VxvnK5@I-48@dG)8jP!D|
zW`2vl#MGWDG_xJw-R<G3(>SMxEVZHU#cH0=@l(DMIK`tz_IF!s_Th+E+Yo<`09X+@
zh<DzZ-7akONV;N9#CJ;g8C+UktabrOZmCvvIlkIYKnweOIJca}*1!?R2$DJ+WV+0R
zJpOq}sbVCOg*>TgJBv7%Kn&f>ZC(BEZvz3=-9ckqOKG&zaVp;;syrA*4X;Uax#ipI
zzO`SGx_CQ!bQ`-FeyVEH34dfX2Egi&axO#Sn~^O988?Vp(@YB|YPk53TPJ2aZAo36
zGues;C)A!lc5c|N5u>BTylqrZXE1Ft4o_>42!q~$A%ZFeWFc)2@oip~zXzr!pR(*}
z40F33<-0?<xG<H{Q77IYvV`m~qt0-|8W+V}EFj9I+|<AsQla}-pHrm1o3R*_$${$S
z92?p^!QJ#?6QHs>{79F76)IFTa`*UP9d8Drwq+=(DL4#>!RicH&Y@ru;0G-(aS0sY
zp#gPFSrB{M9`^Q)Qrh@e@^tb(nn&R$<<U5)i=u6j+#F0;u#EQOieOw4m}ufJ4H#`#
z*7~)$=fMDFyW%}Pb=68$_L~w)ytFa^J+)Gsm(pT{93asNBT!C@8HEfw4?Qd<ZIZ7*
zS*<s2d4j<qMMsNN(0ykvL6L1%ojg0_;GR7)e0m|9ov^SuwJ@Ik4xFb|G4OKvNhK@W
zsz1xJB~xK>$*#5NIh?=Ax5{<-M1^B+im0hdl>jhFAI_G7lnI~O`%yP<*vD7=J4PHU
zomkNMb3A;zls$@U=M~Dt3QVMK@-td%o)~N1ux{*%z;eE-ZAi@L9gmB;?XKpU;d&bp
z%LxuWNHVe(zNXM+y=*0CyVzNL#GdotrCah=LEq0bFAfc8l=|J5*uZ~7Hy=FSqWp}a
z0c)Fg-TPUmtUbF0^>-bgP9Kx0<~P+`UGF7<Z^++$xns;T1u%eKVWJm`gb!{lfi|Y2
z<Zx{jI@ajUgBog_0Y^8&cW1P;+=+lYp4Wzey-zO@C|Ig+m!6`Ye3|xZV_?b<Cc&Py
zNJQa_@qh_Olt$yRPUaS-WJIOjYvs4Xx8NK9k&eE;d*00NX<By8tl{tOVt2_ZhcW^8
z`1H?4V*SHNh<I}Rl)TVs2ozL$wdzy@z2?OPOKMY<{-kC>ZFdkbP$msQ+}i2{*!}KU
zPlC$mFp;Dp#^d^gF(qM=kzC>FtXY|#Iob_M*73BV-vCiddWTqW=)Q3lFQ3mMx3D6A
z&&+P}Fp^MUkUc4Nh8CNh17`IH%&!#vNn~L-74dIg`QKx=&mKHVc&H#DqXD8AYoZAg
zu&lkuB>ua(&Ks(WW<s4P3PS{{;`|Oz>Jkv%NDH}_=ok7%7wt_=FS%)45ox50c<qly
z`VvH9_|sP@{cTxp6QT97@p_3`0YXal{=^!gF{9`RoEDIlJlADTjSS=*1Y#Cc;t&Um
zv~~ZOKIONq&vIp>mJEpis=U0?VlNS12gB=}F8tgIYRO1D!GdH_+jp;+-(TfsMA*W_
z2CFc=Cj|PPqM2bt;m1{Bh%hd%Zv0YNHx^z}Mst2^SAF<=DqY`7vWamhR<tNdr8>=t
z+7-DzPeBUu3|R!CZ@9?1&410&2C+QS2mYRJ*-~HM!xyDy;qFXURz7E|G%zozs5c?I
z4NI~`NMbg0BOz_NeBj4WadoH)cUYJLwIJ%Hyq>L`AJ78<=-y$zq@7<)Duz`Ia?NjR
zKxG4|YEzi%Zfm|?i>U_tvae|*@Gm$`Dp60Dd(AC0dNG_>05SxRXc<9)@H4+4&)6a7
zB=gF4WMG?RY<DoS74vcgc0n$=iAF|xgmwxsqV8hp2Rci9Ob&?3K3=F@t55f{fRiuH
zB+XGBtg3>*V87nOPV-cuNxl+iV0f-6j+xy9*Aw1jj&9Q<9;w;7#ZOhC-vjLMtlhE-
z0r{#K`8Cie=XHM2O9?X`R}mhnzLqcIditrOt$NfkIT~OQH|s($t|BAYXzi%W1K<iu
zv&M%c=Lr(K(TJgoh=3<Y#NQ+Wv;XP=mC0ejOc36gto^-IIUQlhs^*p1QV@eX*oQiX
zD%J)bphL!~gm6JJIt(Q|wX{tc4tp7q7BpMjv?iT_N=gcxn4GxfC6GO)m71jzfR;C$
z@*c33R@_J+YNE`>L(M~}v-tD2bgS#G?f0GN5m#9nNH@bGYt||!g_pM1`#9RvPVp#z
z6>k=aNfL?<J=gXGr=^l6XgQ`bO1X&BI(0a%4WJ`81Vh7N^;BA2>S36fZcMG0hBg~l
zrHIZZBbh)g<){h@Mgxe_-T6WNunlQm2~7brjpl?c)R!do8IJfZ=XEJtwCGA$gg>mz
z(mD`SMd2}oHQ}2%E+s%~Apv>Wg5%+!C^S&Au6BE0&FH6P<sC5~Agief+4lI$qvRue
zry+F`I>Z7d6X;;blA%I$yPO3D8YN_h7KNW!`C@ZOW6Zu;=#GB#xSdleFC)!Ibzdw!
z{vLrIGUQ{!xpEg^SD#89g2q`iYPEr`AgL}-GbkHDD;sMw%4IjW2LWRilx(65NxX%|
z)#A;D*ZEIcf^oDxWNC>=lRjq{9evGABei-<U?KnyL?{OgT9B>fBeFsI+iBWPBklI8
zGR<iA$WfCO|KAqgGlY+2p6VDM*y!Y{foENF&B&5%#^SI}HVrrq!bdJTYxC-Df6wp|
z))=MB!WSEomLC`91DuQBmRQ#x?!J$!AG$NBE+5OI#f{x#wZrLV3)qaAv}|ayZ3f=-
z%=drn{D#ae&KJNc?b6RD1egD{(eQtY{`d7!hdZ_{!RO?*<KEIt=2(9<6@T-x0(-qK
zbn0=g7{+vm5Y64P@AmChfz<!nY9m^Zj5{b@2_9t}M%`oozN7zRRG|N9tJW52c90Ym
z@xs+LP2P=O?+VKyp-Wjf>+RdXC-~Hu==UvA&?uT^;#6qG#O@QVv69CjAOD?4+$~_K
zs-E4LJ#L-%XRVO%XZA^lNDu1>X3lC>HV93B>>n#^Zkmp+AkjyPsmnj^=Yp3R(m@h~
z;QTJjs9!MIl318~$&4?P6Xh+Pxfximl#SGNSx63gKhSfPX;*i?kgW$E9M`1U^5|FE
zfl-wV|B+YqfIlT~8dO$t^mD%*@N#mF&>4DOgTIgG-bjawnbsxZ=rAp`@N>clyP*%f
z*u#or<5N>Y(o*3O32@M*x!)If?K~LXNHh<t?XT7jVv`j?g-|%#GuHs2t=@18Uc#-@
z(Kb!XcTheL-fq6Gze~wM>#Je>Y~#FSRwR5Shh&2(FMgR-5lOrs^;5kwpmLxaW&LkF
z*PHv8M4y7ffTZVAMC>_xELFM97b)CaCkF7EY7Em`r8XsJGpBf++}p~Dv7coGSm2nW
z#Y)I?g;RMuYUl8gbuW`c5$qv2hn=<h=609fRC}FhQdh;&VTFqW*m=WGq6nOPCee5H
zPw-mOVy18AA!bDJMWK>Ll;TUH$=`?!Afy_N&CzI+hT+N`JA>i4elpzdcy$K8ni6}}
zf?_Pb?LMRAQHDX0qnQA=pp$BQ``s@rDcSZyQSzZ7+2f*WXXmGg$!pBtjZxZD%6<<4
z%z{~A#H7u|&o(_Lu7S<-Aw*UHc_dHeZ9!+=%b{740x5&*`$E8t0*56_8XDB059^HC
z`Z`{%D8LMu3Iqt?L>bRRaAsd}g$+8A(Ls_F&1tL<1P~F7m#B~x-y85Ii`J3HBUk&}
z$;!$9#e*Eh(}266j*++jC2mhE#^9`e7xC@Dqakp1AdpLS2r%Aq=DYLvWC0(FOkRLV
z{0^gBcGbfhtc{~A9WFDO@GISEOUWd3RPQZFBmecI;zQ&E+u06z3-K<MStp2{<>v5*
zA$4~s4ZaxhH(Qgj?8Fapqh1Jds9<0{WdnK^P+Zab9bZy-^A6vwn_(@z%&d_#1~mZd
z>yrvl2>?hniXkfog`zVJ69qh^%KDj=6NO{t@Jq<W$irB1biCco9~>xE7BdyKwEb{t
zH!rI##nefnK!`kI;|`)IQT3=DLwd<Z4Yj(WmyA-tuvfYn;a6aVEDXTX%QHA@*R?(J
zU0=)UG9?C2B8t296&QM@WX`V7;b9{&0(tDA>Y1ctroAUne)py8IR1E9Siyj24_ka0
zKNcrcjjM-Q%D!l3%G$rkGMU4bC<DC*Wox!6kj=1=xgsS5A9Bq-Va{?it!2p;Wn@Oi
zSS;v79RFz@;+`T?hKH{+9g}jEu0OKkaq;BjHmBB97k*TYe85%G&!5lA${I6M=M}ME
z+EQ-wqVa^M2%%AGu*(5DA4JiI4R)B|(4)n3qcdieSmR@d{)RC+#c173nCawhmt~@~
zF_O#vk*P??gFT(hE}Ig44A63fIsUb@9G}hH>@D!Nqi2SmjG?iNsE!oQkSwKErbqyj
zmF{MO0KlXDCHUtYt;xjU9Gm5oP#<i{DNh!WlhWj6X$SfxN<}7DL}Z%00f0h_R*92@
zmn85+z=$2k0OJgeN2bQ)xheg|k|IAi?<S`(mBRs`89+%LwFh%!87ZdIZ#pbTBa%15
z0hFSpz#1qIicAc)W}4!_4v_+vrjm?4nVOxAh^RJG;tRN}s3<6<XnT^wkPx~_0}85G
zX@J38w$nH`6miH;+~ti#(aaMfOE(9ZI?h>wP2m@uf}ItNn*~{!79xdNN*9V(mJa>J
z912URg`GH5r7M(v$WUH~SpKx#>2+?4P3&3TdJ2T1cs@2JS!sE*ZFCO!+)6&+Rf^>`
zJXEt9L&u(RP;pdL16ouOp8hAnZ>N~Qzv_|ctA5Y`i|pp8M(Mh;VAbrF_!b%kpER(@
zl!zelTi0Aha%L(aT0FKk;M!$teO_$*ozLd|exH%P7xch#@<IoV$}V-^PMW}L?YGPy
z2L9WvH`rK>+IQR$=T-&XXpAi1d?gzHJ>B&*Ghvf%UYP~QIKWRP@1<#j9%N_A65=P<
zJ<+7=*g|KLp||*LfKkO&x10kBfuF?}C3aA5d6@QfCPg09^m1Z$N&ilsKf8Q|Z;eJF
z8$)836VWK6$U=TZ453MyNXt$>vW@lc!G7&f`qD-O-hA)9y9R0q2rZL^;B9)0yT_z8
zc6f1NI$bZr$C15g4>)|CvI=SD^%@_JFIA<l)sIq8QXuu_Z)W#BJ^tZRb)Tu}x`_$G
zLldNd8D&&Fb=e#ZX@WZsB~<>t<Aw6Qo3Ll1H)Y9xqmx>{)M{S4aJ?q;Bb~_+(d~!s
zxgKFKf%l7#-(^QZh8Y)YT4QBB=KxbMQhBPc@?qO48}F*{Ul+RDY>^ES54-1KzO=Zd
zV{j?UISue_aPtPmdVcy_Ka2z<eN+*YI<Huii5LXQfDM48SM*A9O*iml)D8~W`NoLJ
z(opb&rm3kh+k;FxY9W|72?7ME@N0?YyJa*r6686|F9HY87YRwprQ`YAebkg`o0~Ao
z%&`<31vs9@5bU&29rFURp^XTrIn=#8;WFoq067GC(U5XQI7$gX!PZ3LS4o9&r=8;Z
z&8XoN9`*07;mbgca9sz=7DBQie4-3t7;C`oDB}HsiXdu;-J7frl7$a_1o24V(=4jr
z^X9w;5K<h!F3#Bwf^3MoGtA=UHBs=rtVU8aS!5}IXb2s_u7s73E2F)~VCFycAxzLm
zmzR{UAkWo2&AohnsDwoiF+jyV&gG2KL(v<Gy8JSU<4KZUnET;Kcp`>om^FRhaK)Z4
zSBTGd#Ar=0-rGnm=z%Qq@43+Xh(7h+Pk#7P>!J%vJ;;P33kVzZfOk4rU>^A`f>7{1
zT}Aly^s5B1dar&K!Mjz99dGCFUs?c|h(J^jom}-IL>7rgF(@(6>EB+Di;vufwY5p^
z9THU$kEDpa##*=F`>g532}}^0QvnHggYRECd#96s5M3uSp62vJXd2aW1VS!%MJw`6
z;-tF71SYcNI3#f=I}aldnv_|kL|!H1Hhg8okXe6T8m`*9S;P5;z<P33)#XRA=dTKH
z^TyUMeKx|`wfaI;*$*i}OIv=kd|MtHN)vA-VwUtoEuyZHE|%h~2K|o_Z*#~9$g@Ze
zCvvHL4`$(Z06Z-~<?k?bT~VsZa=r322t?XWRzd&QqbW?Ue2h$St<Q{e2X@!@6vBRI
zN?{k|TM31lD?4N8lZd!!bwybha8%<U42b8qV4}q<7CR?M8!10+%Hr5rPljpg+LTAa
zwc3il31UMlr^(Z@K!r^2&ffRqTER*!OV4PTGcI~E&cpyIf}R0=)x)G?<3}1-3~L;k
zI$agKX}QTwUwA|!gI=v@%CI6IokVmTQMLrg8#BTN6r`yxe~uuRbHCBPY>LM&WvVr7
z!<(a6AwC5%b92z$s74>@R2p@bk|+huiW6ZSYelzhSN#H?Z$!<4Q)nXQu&riR0C)g&
z8d^IXaf9dKmE!sfF->j)aGGY1I|HY__uE;e|9)lH{$wVUvps{UdJKI|%CjXLIqTop
z;nTSNLwDS%t#G#7oCgvrrQeMt$mCi!3D#Kj@1k50-T0IQ!QAA-Q5c|hfvg7$xp4R*
zgQe-E9J$JB@;F9gE_HJ^E0dp>(UufwRqTU&3W8&mV6;gEor`Zl%nb<9d1#A|1)Pt2
zeHC^1Uh2gng4j8)Lji_<PYRjHA)4y@{2C+qSk}-JZ!DKv+)?7Gqfl@gCL=53oZnG1
zV2(MO9A-5pnUu_>)C{|L{EzMw1O?3nZGLuX(pMoWFqydg+Y`D5li;0O7B%rvkjEvd
z8j|47_c@PD3Ox?mbR<EjyVk->ic4lt6oI9w$|b4zi0IIl;_5hd{Lh<({$8dJPuX9K
zc<ghXe-I8Us*(f4_F9A%qSC8R>%k=crr?0nC*PN2)6HptWuUNu?@jK_Yw|z{y0j&(
zf1}`%kTa(D3&-aSDXDRGI-^IerU~UzF+SG#-}tY`O|P%T)i<EB4sM6&MA{?ePUA5T
zct9|vQ(6=fYtSwA;O0H;vqwcpJ>Tb7%j&Q65y^@vbWsaAf1dkD#@#RLo3Fudrio&r
z!RIfKalv12&$qi@N1XD<Jv;9kq_1<XsMNqF{l_`X09R*3FQfC?I7H{|+ue7}?w9w`
zv-pAkSlZ{PeUk)j2EB+1io&4A-Mom#$GnJ_RHQFK;y3HmwSU#Bf^?Fk#zY72M&f0T
z-Le<slmJ=uDN|9=?zy#|kJwZ(NunXMD~O1g{MX0QSfto4XP;<IQzsBhqp1l5Iuaax
z)wGbr``Ruq_nYx;ZlN#An2*c@hkPXZkY#(!a@he>C?vvQ9X}5o3{ttpj{kudY5Mm-
ze@heV9K}IN)z}~m_~fj1#APC{G$f<jVPWA1*u=(5Em?uM)G)j244Oe4qc4C45-x3d
z3-Xy-$FQe%zO)Sn1z0oGhed;fN&*r}%G?G?i3bKDZF@t}Qvc3WLTY$uat%8wZZHap
zI%%+ZYH|dMCa4u(gJC-|Q}}@uK6-<wc?HA(feK;N7W(xMRz=9$iyjLOnQl(o=;0o$
zxvuFV4<ijZIO5^Rdk=Jl*c!yeE$FTsc=G`xEJ=?mk~p*7fN`B6fPUKiibZi`ohW{f
z&$sU$sxGdJSjZ-#ldo<_Ge*i0uDR1V!Bo&$u5=$-O&-z52sYIP{p5k(=%L-S5ZtZs
z9gYW?Bj9~EZD+J<fmU-dAa<sz|DCSid9-JLv5(R2{V%E@RJp2j3<W&+eDtkB1j-|C
z51A<JosW7%75|qL!8|`BZ6TTG95Li_lfe6`8Sf*C9Cn0=L+tPv+OUbj;6>#qYUdLP
zQqr3Of--glNP)&Scxyg!nhB7#OIa9<EXu&s)J3v#BX&RUhm4Bp{0KK4)Sqcm^$>{U
zBsiy_2^R9=dy@95sDAD>S9eG{sx;_4BL+tbJps+2sWsng3~DYL!(4@HFclV4=w?z$
zcPBJ?xYdLk^+K7wA}2LB=iC_AtmR>6b}*L148q&}yx}7dk&}s<(+pye0KjD-eQS^~
zK{evmqROV}me2fc1g`qXHH9oxiLvj<ovFxRQ#K>5Td`JF%DsZ7?Zq{cOV7K>IlfF4
zTNw*UNe;+{iJq-H_x7z3BL#o$X5QpjR~CO{X}$9&VJ&hlBw1HwG#`M$D$F9qf%e}+
zF=BzCTKaX(V8U1|08gTENkeLm)S(4#y=YW^qm;gfW1IqpH&CGEAw(w_i5};_Cdos%
zHk+VQ)YX?J74?4vL)wsJvC(Fz&0#|`3c%<)X0$TzB)OU(0cc!~;1Jy8W;{6{;}qdD
zGV>O);E^C;YRlW24vFYoUh*wb({oU#!m4cD*^cD$r$M6UAPV*6w9RZx{!+|Sc{cS>
zl_^mOAYxH8Z#I4nC8RDSC`&!0ojR1Sii<nd`xG}9p2%)lJD6A@J~%A|7qXmv%ONKR
z9bbMt@Ap`IdfF(Lcl>hEhC-xQkxuB`i3I};?PaU&_*)3f5}u5x`gM^5-qCQH8I{Od
z=q1`44b)8@^K4qqUU(Lgsl#7Qom2ys$2xJzXjhPtBmDS*jADh70_8rFO63EbTJ8o;
zIjjS0Ip?WOxmcU9QPON}%DK~|Eb;*_xb-N@YBlFfvsf~!+L1{wL#F_d0;Dt!<^be_
zY9^_9imGT~S7(4@-4P5D(IbK?Q(4GhgQR%*4a<8uM<ba1MxpPVYZOfzOCG0a^#jN8
z6+6%Iv}1cGwzx3v(Wg{V5vTS0r-5f1RCmPdO$er9jaFZfyRQ58q#>|LwB^Ua*0TQ%
z>d6zgLy3k;$F^qHy_Xpa%}gLp7Q+Xj!2PA|l2m1ML&8l;QGpt`6mj6+m$uz;+Q6?x
zXZMvf6l{WP3=Fu#?;j_K-+d{~AoqC$|G^RLwWu86240n82}tGvR?eRNC)OWm=lMg5
z;)BWUJeaK5O!Y!xz3(YL8;m<0xX7}~#@Aoo`XBn=ZXk|3bLOtH?3a%w4LRR;tZ$Qd
zyFf_QXW9*2<ny884yIp!PpiL<ghujNb{QXRofyqbVEj%H0*<x6&!s4Mi8JX~Am%u|
zM|T*!BzT!G$+aANB;w}~^k4_<97+uQ;7+fg-h9SQ)<w!1u@GJT1P6MbJ6f|FOoyjX
z`+|7Ll!BoA&iDOYD$EYMBh@U+B+o@Diaxyh_v>$bzUOYYEiUz;`rV@5&XD$N*c5AI
zn^(~`Yzn*@24XBP`k$WEypQny^n9rpKpNt`m!rgq4Y3dWw~gDs55(ft>ss%=#D*Tm
ze%Et@9^oVeKk7x#Ix?=tZye*C9x?xx<)>$3!t|?fIrT2TWKD=!48@9z*!;o#`uLjW
z_2~I<?m<qMswc1LENbi6^>EDJLO+DxD-OXl=gQ5rTo(Nc&8nEHQK=4ymA7|#?x?Rr
z3?b=g&nM!{IxQ|C1ml^hO^C=3Iw*qfob0P*EEslUi6Wg82hoPxqgV|*d<lK#-}obQ
z5(S@F%EH+>$5}y~Hs0JWB!2Wy<3q2>Msb0eenNCcFebH32l2eb1p|^oJE$;vEW|gA
z8h6V*%XJ*g#~jy*xepA4gAJvQ*C7X|%>DpO#K{4why;T~pxl#{jB3qRZXJ9{K0jgD
z6tpzF*LXq&b{h*WO7MLI4ut!<27XfwFirmDCxRjGG^hb%1algV+6Rm`N+;m^ErSA6
zN>5;X2OyCWtrrq983mry(2+wX^JbBOgmE@;4olI7t82&Bpg9GFtY}^5y=_nQKW5|J
zW%#PLDe%K>V6_5D(P;+13&l*ZWU4)xP{5bYInYtt4W?JR<&lLVZ_w;X1pAK#NAsad
zb4(L&js>^ALS5La?BeqXV_O|Y|5OSwiJj)~eu+H{yl;>RSB7hmWLXu)3ROXBjOGfs
zeFxgbVRRjfjb;epdpf|E02qUHa*`~Z|7nXPoc4!JKRuY{xG4&ZV$C$amsHSbU8V$M
z@oE$m0x9bEls{)s53W<`7E3|q5*9R3<k{4sx&Rvq-+9tTlhWwzL2mZr<^)HoRv@}$
z$?nV58R9$&O8M{oAoTOH4FI#1`}uyXi5JC;6EH1e^>97#z2Uq=crct;2P&5mj-49H
zb*)g@#(N*Lux8>;F$KbLu;1+yJpTb9>_LJtQ4RxYA^=oE=rGZ^auR+FWulN##=Fql
zN3AQK{b^4$rs1)1n!L-0H-zQ~SkUFEBJgjr@|Lk_E{@g${?mZdfc4x%>2xp}$P$Zr
zdZ{X~Rm>|vb<Itcg>uffP0^bB!<YPv$W4>ulkhjOcAQY6VHL<ReLc$zn%oMJj(W<n
z`C(Hp4ED1*{4MGzxl^Ndebfjtt%vVM7{>M-sCX^y8I)*gOKQJ9Y6@EAem6fVWf9$Q
zNbE;Gi!;EP#U0xAapHyijPO@pg+os^oy&@vTGBythpCQxHt5QYxAu9*8lFA+G1az$
zNd+|FfL^KuZ2ZGDVmOYeQAf*OK@83hjdu6>*2Y?hOh}=HV#AdP*|Y|)*;ZOggBFG9
zI!;6%xi=TvNI$sOTwgJsycSo-jBd_QEuA+h)hP)bhmRJ!L$gQI#IV*QR%tGl2W~!&
zUN$wog_31Hb7r&28D~2FR%&G>hk~vE;)2V~#$@L_AD(ys4Nz<8zfOklMGIz?&vsT)
zi1{<|>hgG6*c!^Nb0rHUC)x4q;Vhdl*kMP1i@^VxgU%j|7dA+MmX2(~Nh1$2!8g#9
z9SuiFYd*XAgD+{t<9LZZiRu&=zpAPASw5NDrx=f75CNv6_`7(yb38IeTa~4;FgcIL
z77r_+ZoT*dl5bL(i=7%TESnlPL}gMS*!C$50Qd%=!=YPiqAs<_7C~D!-A}m>d#+E2
zo=NqP+;^Y<MrrWC3-?nV%~(2ynm3zTM*g-MkTN%8QE4He4t+s{pH0UX(%N>+HfF<T
zB`xZs-s4#Uz)*+O$y@SJ8bud?z4kMoOOqdpsz-I;M+3@upbMfFsCk@7w$9e^RrgD3
zs0(<sc*cog4$eVlM9E4-e;8Ipwu{`ZlxDNz$I5w7zJ#H_scpw20^vcH9=c%Zu`I{)
zUZ5-zwQ5hrPXv4>8(FDnqV#GLHu|QlLeuAi{^U&^-r0zD!KvWo7Q)?U!{?81k#Mv<
z*FE_a<+2*44M(ADucK*tT>w)Jjn9(jg&&N8I9IRE;m!NVX<@IcswQRT)7KN~?#H-W
zMQonLxHC$Vv>2NdxVk<Vd8VEEC(qzex3@26mZwK@l@QHXJMw7INp*mzQQ}b>c8P5f
z{54j<d&S+I%1!2&Q}{ob!2k5)UJ|DWyuo9PKsePX(N*3Pg1yx*z}H^I0Gr^Qo#w2*
zU^0!E+x6pI;M+*WO~Z9Ny}`msEA$X<!~VeATjuk3lEEvqQf6|esj17zuYX+~g6_&W
zV{Z7tC)5%6sx~1db5U6%E=WDTFCC;qUoZ0o&!PEf#-<rwoNJfkH4&$zm8uCF*0}?y
zMTTti7i_b?)fzRZZ2DF0jU~gpyczbEO#ankNyc|DdR=XO?AapKEgun~MbZI&XSBUe
z{|M9B{(D-dDL^F#C%f?^j9Elx$4t4@R&jYh$g<-76n*OF!?I*b1=}F(@~@4uXt<zA
zw>k8rYKhqBCyP0fUjQt2c@*b~SVy^<Sg-rtYpBA1o+GO~!Q_$61pw^ecaac6*u$Yc
z2UWF0&mqyu3&!UHk>_7>mutfbZEMygZ=+Cl%cJe#Fi;~xJw=@je)}1$uPBXGjreXP
zbH@viO)PvhzD0cTm58P#WxlM0We;6YaH_migT6@-SRp~-8%JdZX^{(7+~`SHI`xRm
zx^ry@JZl#8E^%br_1X_A{UK-upNt;6?q0Utzv5KhSy=kKl}0nmXqCnJx=)fc+x-=N
ztBh!(+$1$JVlO3lv|-=JC&c4oO`6}oCIT<WDmgn#A3}j-cD3eSc)^WpD+=8xy1kjl
zI6wW3PAz76PFZ39v(woHJ+m(H(m7Kyc@DMCv5EVP=gqs%uv5KS>sG_&o|1+8^s1I*
z7;;S5R`NC#-U_N7RbQ_ttFXwV{|YIV5jRT+dpW*3w3uohjl&ySB-vVd`|qp4MszwJ
zLLBAiI;;PbCT@;N5DiwQ_1eujRM*l@O&zhdbA5aOUjn|Vh$#+i!GFRT84_C!Dp~cM
z|2bl&u-9vWGcG8Eer?}v{vdhc`@aK?$z?}C8xix*^J@PwC6m0pTEa!cLhD>MHQy=&
zIN~6>B059^yQHJ`hp_LEgqx-GHh7aS{R<BBvj}oFHI`J6Ev><)7lNmT*wQ?liv|Xo
zK%4DKQsuI4Z))x{7FvmBLTlyq#;s=_Om#K5o^rXXE=f0;@AV1-1E0w@UYwkqx@I_-
zV`&YkQIkn}ZQ6(w?3^5x3~vi<w%y*El=-L{^tREtUN_2~F_2XRJZ)Je_j;8c({Bt=
zmj;Cey*w_dbm*nEY;$}(pe$}&QeJjpA^D)1+|l9HiqC`DzKEx8SO+m1P`BrN*S$NR
z+udMr5S$$#>&JDB0GgV7bX03R5QyJ`GrHU+clXj3oZ;K0_(06LhsPsP3#Cw-a5xBI
zZ}StvM7;$s+f8}W5yQUU88e(#dzCw}S})%6s8qJNeMz=H9|<~bom&aZRMXrjDLN`M
zs!So;7)f*%44xXMmy=|dM(2nfWs4mxPm+WdGmy8KENjSnMrv^ONu`m%u#d8uvZ9fm
zBHf^#U*fB<Pf5f#s<mLTl8;`d0+=wbnWW@NIyvbfEXb>ynI=;dvmKb<!67KIuQ0*b
z`{}dm>H8`Nh+0v|v$sRieCKq6CZr7NboKT99i)VAFTp}gLET(hoIU=7ssDkyhP`UL
zV075jjGCHiLKH!)6pKE^c2Smqik|$WlTm^zUK%MsQU_v^z*mN;t+v?{c`rjZ4aHK<
zo@1H@o>PI1(~O$(r4oX%QxF{@Z|3-xpA&krwTaiIOsowanOWdF7@(WETz|9<WpLy$
zRJLQ9Mg7<LH0s>jxvx?>S!NtUlmEn>3KEP!tJHF%<73;C?SqC#kIu=2F)3@xz6*U0
ziZXCUh(!1d$X;8cQBvM_d^&lHS<NF&UJkQ?vKb-68CF1JoRG6J1FjQW)JDh4yz#vE
z%^UU$*W{%cq3*nvyLqLzO-S<L1!w2NFtG_~n5ASsGGBQv<+EZd>0en-{ZnKY&%(|C
zncz?$MvE?05?<x`|AT(t&!kBzW;nrKlv4W>-w>E8phi%J-!$~n_`{k)=NmT9n!jh@
z=`*Q+a*R+0Mda~mttdAFJKVYu?c>F+CrjAv+x#C+?a);0w|;ht#rUs1C0rx_jfuOl
z;V`ANqSiHq&Rm4(s5CnE;1sHm=wDN`EMxP6ZqXmvB?4*#1`dio&*5C!^?rN)4R6=a
zBj%F%SEAj%Tf?b4(a9qLreyd8!<u8LA6Z-8{Edu4=L7GCpSeaCjF;efJ0!(eG9vfg
z`C>QU<3-}xy$oeCGS4pK2S&*~G8rYI;KCP~Z<&k!zch2%Bd3ht>b3j+4)vvwiMEzp
zMEIN?AL2ohzGIOD)T${<s#-Q1=#fwvblJH&JI}x7lfIEFT3t7Mp$0oKiOgciDy+V@
z-3$p_vqnCN?o{{1j~a8~Z*kA_L&}rr{th$#Fnr%p@gG8-3#X~;{LKGPbdCWU=@32?
zf%fa_=E)JJq!%cMycGUe4SP08!xRD}R7VkD(N_$p`)8Q=qbY|(n`-KSN%%@(&e}As
zBh8Qe{S4q&6sNPZXf(_)(|ozqpsKwo_|L?`30RT$HLA;(^Va6$KFvOYIQVl%EwD3%
z!cf?O^PhD5(K_xV>0r#D2|G%ib>;|lVYO7O<GE8(|Ib%kR)d}hnSmFdZJ#I<)=Ex1
zcJ5W%r}N)Xq{SiaPk3Z*^I9DYd7G#Ac52AsBfo;pWZO(NDXwP*%cG=lilfz3A&Y82
zCZZ|SZX*Qr_W4yp+7QzxN<2sk2B5|uLu_?*B&L-lAVkSE%b3kKj23F&qD9jt_HRj^
z##Z*{%}be1sBD&%!|=ji)bBki1|NGj2JZ*hq}x8#($QHbchTc@fmr`-;)1FVo~m#=
z=DzBEbk{=-7_lvr(|{bHd>L%?EN6cazsJ;07szo+nxSdt#CT$XJ2tY{6%qk2TeVd+
zz!Eda=z$c&8L))Vh{ztZi$u+XlgNFGXZ|?Z@-k`O2(yJ;D{%ZJ$i_U73PrTEhDr;z
zZ7t&XH;U{0%8xL!S$*V|V047@LtH;{8^^5HA1WwFceKpj`_k5L|L#LZ<ZHAOXQ$8P
zIB63i!!auhI6avQzta46H{rZo1WYh(7yk*+slrylEBwG%n&S#KjUEL)5M!eMY<6k#
zTAlyoKku&hyw2sK8J?ik3RmcU?y5jXQbKkGw9SUr!LdQ<NtmxZ)TDYJNp<eyhm;~a
zQvUbgLlUCZGNo*^rPU9WJM0;JrLHOk)tEYBU)Ij`{0dT)?^2%`B+{NcpW;R^7dvE1
zsUpsK(2{gLftd@mqr?WE@W7D`Kw5grAA7@K^&CakZ$Y}nwWnZ7XUt=OYr6=nRwH+C
zl|gnZmu3wU1E_d3f#2SZK$ZuU5p&HsC7jLh3{sR78I~2V<WW-a=0i-Qxd#}X*|6%(
z_tOi^=KxJ749Xl@FY)(v-B~I^y?IB6=Z4a7ydDd^)OLJFi=spQ$*q6<?N|(zN2N%~
zvTIqnSWx2@;^XBP?gyUzxvT2DaR&crCT78PVn}J@R+9CqC6(o)(<oQt6;_d#(meC9
zQ(O1S=A4W(&9+uMZ)J{KMi2<N8m^PD$ECb2a~1=CcxY=8>3e<(;7^kyP~TAN64$vY
zZ)`<-U@5zWX~#ja^mSIF5Mci9wtYis;-lrN;uArxy6q|6z6=F6E)s{+u+Z*ehcBT=
z|5}P~j83(HL5J8iQwV=j(bX66{1C)G!T6>y3Oeny#h~Cvw0kx{{CY9P=QV~6x`6U5
zaZxp?h;~fA-Sjt#m)g%#TfO^rZVq4P`-lU%q_a+lt@P_B-Cxx(ao<@=0UDWUdwouE
zIC&Z}(@5>5fbbZp9(+-~UR4jz%^4*974F1OW)<YR|16)mrhZvESA_}v8_F)ax#BWS
zJt(XSv7XrCyj+EPguu<^{Q1SEZ8`hx!#Z^Hj^9F&N5^$27oXlQKWmh2DOskvKlC{A
z`i7qv^J1yX>gCM|rIkALOEMe9=UVlo5{z_77G;*J^c_qG;yift@Mam`8~8j-MLDKd
z;)&=t=6EBtERCpXSKF=Cc`1_kCsr0lPNdRK&ln~?e;|e)5}QztP8W|ONYn?U&rl5}
zxk0VKy=+42?ku_nl+@quzyGYG`bC}GWp?6U738F*+Z~1P(fvf8Z+=JNTJ^&z6cH+e
zQ@<so)9KupJkLo*u=i2S-6B|VQu<fkvC9!KE{T#5$Ct!9`(57ctQN|nWu6!*sOyJ?
z!T<@0cC6(2dk52Df+ul8pOk>-AcwchlAc~|5XJ-fiK8*sHVcx%@5h795gZ)%V5&Oy
zaHqQIZ6FVBV%ucd6uUbj=K`^NJ28RFRl^Am{!D~&v2MVpfSynNifx9~{G9d@^2xHc
zEv42&U7eC;VaKOsfBvD_UtYchuL|Y>-qJYsgmavW`o!gepRADj$vTD|0eo8`)49my
zz1!o&z$1s2w&${v)=jYJS96o%r~vge0{nAx)8AqH+~IPbq5j{#bptmv6VLhow}e*B
zhoT+pL*9S+k=(als`Kk{@%1q)KR;bCJ;HWd(>yp4cl=k^<7=nyM)&`D{5<d5kLmq!
kNndYpRgDrzVeqfssXa}Af6F2b;Lbq?Pgg&ebxsLQ0D1g(ivR!s

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/meta.svg b/studio/frontend/public/hub/profile/logo/meta.svg
new file mode 100644
index 0000000000..9fa656bd6b
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/meta.svg
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:cc="http://creativecommons.org/ns#" width="287.56" height="191">
+<desc>Logo of Meta Platforms -- Graphic created by Detmar Owen</desc>
+<defs>
+<linearGradient id="Grad_Logo1" x1="61" y1="117" x2="259" y2="127" gradientUnits="userSpaceOnUse">
+<stop style="stop-color:#0064e1" offset="0"/>
+<stop style="stop-color:#0064e1" offset="0.4"/>
+<stop style="stop-color:#0073ee" offset="0.83"/>
+<stop style="stop-color:#0082fb" offset="1"/>
+</linearGradient>
+<linearGradient id="Grad_Logo2" x1="45" y1="139" x2="45" y2="66" gradientUnits="userSpaceOnUse">
+<stop style="stop-color:#0082fb" offset="0"/>
+<stop style="stop-color:#0064e0" offset="1"/>
+</linearGradient>
+</defs>
+<path id="Logo0" style="fill:#0081fb" d="m31.06,125.96c0,10.98 2.41,19.41 5.56,24.51 4.13,6.68 10.29,9.51 16.57,9.51 8.1,0 15.51-2.01 29.79-21.76 11.44-15.83 24.92-38.05 33.99-51.98l15.36-23.6c10.67-16.39 23.02-34.61 37.18-46.96 11.56-10.08 24.03-15.68 36.58-15.68 21.07,0 41.14,12.21 56.5,35.11 16.81,25.08 24.97,56.67 24.97,89.27 0,19.38-3.82,33.62-10.32,44.87-6.28,10.88-18.52,21.75-39.11,21.75l0-31.02c17.63,0 22.03-16.2 22.03-34.74 0-26.42-6.16-55.74-19.73-76.69-9.63-14.86-22.11-23.94-35.84-23.94-14.85,0-26.8,11.2-40.23,31.17-7.14,10.61-14.47,23.54-22.7,38.13l-9.06,16.05c-18.2,32.27-22.81,39.62-31.91,51.75-15.95,21.24-29.57,29.29-47.5,29.29-21.27,0-34.72-9.21-43.05-23.09-6.8-11.31-10.14-26.15-10.14-43.06z"/>
+<path id="Logo1" style="fill:url(#Grad_Logo1)" d="m24.49,37.3c14.24-21.95 34.79-37.3 58.36-37.3 13.65,0 27.22,4.04 41.39,15.61 15.5,12.65 32.02,33.48 52.63,67.81l7.39,12.32c17.84,29.72 27.99,45.01 33.93,52.22 7.64,9.26 12.99,12.02 19.94,12.02 17.63,0 22.03-16.2 22.03-34.74l27.4-.86c0,19.38-3.82,33.62-10.32,44.87-6.28,10.88-18.52,21.75-39.11,21.75-12.8,0-24.14-2.78-36.68-14.61-9.64-9.08-20.91-25.21-29.58-39.71l-25.79-43.08c-12.94-21.62-24.81-37.74-31.68-45.04-7.39-7.85-16.89-17.33-32.05-17.33-12.27,0-22.69,8.61-31.41,21.78z"/>
+<path id="Logo2" style="fill:url(#Grad_Logo2)" d="m82.35,31.23c-12.27,0-22.69,8.61-31.41,21.78-12.33,18.61-19.88,46.33-19.88,72.95 0,10.98 2.41,19.41 5.56,24.51l-26.48,17.44c-6.8-11.31-10.14-26.15-10.14-43.06 0-30.75 8.44-62.8 24.49-87.55 14.24-21.95 34.79-37.3 58.36-37.3z"/>
+</svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/microsoft.svg b/studio/frontend/public/hub/profile/logo/microsoft.svg
new file mode 100644
index 0000000000..5334aa7ca6
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/microsoft.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 23 23"><path fill="#f3f3f3" d="M0 0h23v23H0z"/><path fill="#f35325" d="M1 1h10v10H1z"/><path fill="#81bc06" d="M12 1h10v10H12z"/><path fill="#05a6f0" d="M1 12h10v10H1z"/><path fill="#ffba08" d="M12 12h10v10H12z"/></svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/minimax-color.png b/studio/frontend/public/hub/profile/logo/minimax-color.png
new file mode 100644
index 0000000000000000000000000000000000000000..e9472c676dc3af879f12d31ac0c66c0c0f211640
GIT binary patch
literal 8665
zcmb_?XIK;6x9^?|2`vGnhR}iqP^5Q3jfx726h(T8B3&dD1*rqRil`JDq9Vjbk?IS7
zL1}|1pmZrBAOs5_HFSi4ckrBV_rtx<x%bH=nOS?UwSTM3T5C@dZ)tv*#7E%+0FX>g
zjE@6=LpI(#Fh(&HG1!EC#aNnIA2jn07}uarYP$VWJU6$`W_G{r>>m4x-OfwL%-FkJ
zR*xU%IM7D61kCJl_$haON|!#eIdIwX$h@)j+<u!$%`@y>&J!9Qi$~3WDV-bJ;k$I~
z*t*N^5&7U5Bd1jx<7IQRHK)BRCl7rmNBll<c-p{qO51IAx5H1FkkPGy3no_Ms@^YG
zw_9LfgoBTpp8#SNg%!bf_`j(+G&=6@7`pL{IukO9jq)-~?1KQ{7uk42;6WN004gvw
z-e(=!JNan*^pghhL;JXlUwfHl8P+*<?s=&={RiQmcH;B7MBQ4TrWNVYk~EcG7S=UT
ze(kL~kNiJE`~Saw{CHT;AJKO~x-lU0)g-rvMU<n5`oP*N53Tx_lL7uwj?Ze!YJ!E<
zrjx5jjN$slH)~r?wO;x2Q}e->n8vup+pN_=gJ?llUcUT9>ionIr}`Ul5^0@M+*xjZ
z$3yLk+TkIzYT=D%Z*83Zd(K*-R-n-y)L*6}as8fY3lhhnEb9f&hFS~?pmCbuyV=?9
zZ`0Q^=CbJ)?r5z;#M9Q^{~T6a`A95VU8!7cf2{mF(|7v&AJOgVtY#r?!R58mS_?WF
z>5=ztus@1>PG&u;4GHJ!bGceS7Z<dZU{rTXe%)o}=^wFYO-R7@W#6_;zlx#P^L^hH
zwOIvnl5>xvo_2+>m+cx{a-it<-p#th6Y^q}&~37SeO&d?iLArhkj-#ieDCk<OIEnb
z7leL1Z&cElTDPk>Er7H<E>xbdS9~rm&X-u`dnlW0HG>+~1lu(uemiT2)e~G~;JUli
zM#gk`Qhoh?a9M|SO7h%=<>3U`*_^Ye{@K>ZOS6R#ydLIPBGfc%`xz09-Q7ArW5rAF
zqA;e>;WHvla<UXn*0<8;`u;w<Bs{RuW2x@ruO0CvmD%l--ZPqBcX20o(GgM)H3q+)
z>y7H`7cGtZYZ1<RP{~arf(aDHOQyht`=1#*BK;Ai=&?)B!`6qotXT7BNpttI>g!14
zrMI73;O6#<i?C{xmf(bA1u;6I6VZq%R*rV9y~s~++Ic8#(}Zom380_HkVaM(d<z+#
z(<PSK5q~$Wc7eTjadxGI8xZHGvkr2<)Q#paR3(O3_(`%KXtq6U?bBqPuE}(YK7D92
z81F;^(#HAF6k-`UKs!_KWx9hleeK|K87MtN6CWDb8u|$eJxC&FdDKiN4*OA(?ah*Q
zv1~|or6L!GCn?G1J)@1AcFH3<zUYI<t9luwzUX_yNRuS4o=nJhJ44sM51AI(v$oDt
z^qx|bf@{9GN-&OzG@0+Lf_#<Q?w9(bAurIVCT4Co68%SfpB)$79j}1zNr$ZH(OgQp
zbnUAmlafttc3iCSWj^SYC%PmF$j%wDIXLFe@DbmD$?RB2xfS>H8X@i7(p+8Xynr%=
zQInIJsC5@6|30_4p67ZRxHiA2XC5T<i|7XmOU#BXVmyOi1b#L0<-wL0r|){lLnY%a
z^k9PYu+0)(Ntb#%wW@@=3#gQiZpO<aR?oluaPmU`be6i{MRG9CB&}V0uTVjo+Up~S
z2&`P&5prw`a=Elp|IeDZWU@|~nlfWM;@-g*LWSE3`d|qu_TwKT#P!>f$yW5eVXWhz
zG0WW)cN9o>PsZ?*mep0OTfUdRL--T%l&}7^ci~arklWipRd?EcWvHLuQp?eLmpV7K
zcr^VE@*a#?XopvC1!3opqBz(m+SP3n(%;#hBwQp!`%wGy6&J1i9B;NRlWv+}3ZC&y
zs1Dx-wD!uSn}C)zTTFE)q=nzg>cxXZ7CO4PGs*z@_xB?;U|H~>-Kh`1_bNk{A4GWS
zwT#w~-w4r$uJ7Hv8?pK-YwV8xIn#543w*jv{_4*q0V|~)?+F9%`)XnUZAe4h5m5ES
z7M}2`g0@=@M*-cknAZkU;=DG4kdm55?o4h=&RD*QAX6<${t|YRj;MFS4fjzOvr~LP
zRB&2)H}d_#iPVdeV*1qtn6-psTXBNEgn`LnAlfPl??#BYa3Yf<bazl1(b|oCYw5z+
zZ=x-;&+rUt#`ZBN*r(;O82DJaPy$p_jYGsrO+n>DoRXYuQVD^J2L2vcwc<g52@nF1
z5a0zkDt17B$F^<^@E}|p15h$n1+X#U{|VFol<)s;u^xb^{=Y!O(PjBtOS5dqR~n-m
zm+ND67GM!j{Y6VYQ}31M?GIihVd0Jm3b#Kr2~@1tdaiV^Gd4%B|I>lu(P@aOm!2>n
z{9FI0-#6_)+jZ|zxd$`8+Y(u-mvVTKNN#m#@bJobYP{d#r^pNDk<sSFsVIGgv$G)<
zq#kV~U2E6NkY#1lLHyfwjZtNZ0XUKyPT$0Fy9j!Y!f(ERxL?H|>kX&x)}O0_qb|a-
zDc=CRC_wvc-W@6Dzhime7STL*fK|$|O*SU=5Ms$i8sPSF<kp!+mD+f-75Y9kCsj9a
z?;wGbrOt|y*VUj$1ENB1SD#}YV#@78Tuyn$=svIFWqz-5HzGzNk2Dg{bl}xulgow3
zNeD)r=^nZRmR=hEY;{#l0;;*4NLFHx8}Ag1Ec)EVu}gRqe;b~s`g_Au-9uAbN6qhf
z0zAQ*KI(?HK*655L_{uLo*5{d`k}0G%)%FqeoyE>8LJ8|@H6!s@&gG*w6c#X)&6|&
z)Q)|njX#$ta9v{&FXD{z^0%=Ed(DH;q?4z4TNw8|imtose{gN4FftlobPAN%=AIlt
zxY;(Z@ntk5;E<kNLr<go7Q&74Appv8j915@<(ZVPyauIm?_bYYhrMy)BiXsY>ldps
z#UL~n1b1;{x<WS512?H2XEpjc-XuobO0s{q77HTIK;J3fnro_bpUo<t`hPen6!y=b
zDFRKiA;(B%2iOJx?Su6lbMT>`1|7o$@-<j0yz}=O38XTZZ2^!{LYsZQ&3m4LSws14
z&TLuqo?xN!dO<cM2=;s)zYG=aK`ux}Nx%v{9g^&y?!mXcZ<IReo<m1Q+VH3&j+|$M
z`KpY}e#){8h7h&eQfAM-GVDJfPblh%ctnq@P1>Dxg3LI7_Q0)PWntDP^q&1HaA>q4
zE<0t35zsflJaFYiCvr{lMjfK2_PtMlDU}O_%mB6x*k!;Ou*rF<o|`n6GdeGwnayVe
z^<3EUP30a|{0z8IDTsX5#+@sZm~AMS3bEZkt>Y^Eo)d1k!K`B-SaAo(=C$f_AX#1`
zUKM2%>E+jps?W9~t*r`R07ol#LPk{e=j@LEy3&A01&hB5ggUk(vy`GRMIv$@XzM*Z
z4i~8E&{veqzIgO+s!A~&`t`3fZ1eRNjP3$0y1l~c?&!`dM}%F4z5R~1IH~4J740W2
zbBqAm4bAJ?gTciEsS%{quU8EB-m|xaqoj#FE^?YDb*aZFMNe>05dkSq@ZjAeefdMi
zRn@Qjuk+A=3UPdo56SLi46u_y9|1i~gOTFw+z#`rV>h3@eUzM}743I2<~{Cg3(_UZ
zgLFY@es_*CeDE&Yk`81|Dcq7QlEJ@ed_myYenq+{r$8Q&`TC2OFZ$gob<U&TF;Jw;
zOLT7bCWEfbH(z>}NOtJRsVv`q{$d&PxEFe)n6|-C*)F9%b7n=Uirn?;(HCRAxQnI>
zHFADw*IvGICp5KrhW`pz{$oP2^ETuH%CLU#oo?hq)~x}B?~PfbgyQzsq$uSVP@mCl
z`nmUnCRZ>T7ro9yBID@S0YNGT5`6ADg`<TS?XY1r)*n3{t73LK)A2D>ORJ1m)TZA(
zpaJZ}&@YGl(20ONy`Rm#1<oAH{-czd;l5-`FVwrHv|F09Ns@h$51EAYg(*eZLbD3*
zE#5yD^(rmGT_@TF<^}K2WZCi{`Ov7J?kx)2&uMn&%fKzF<y?BzgjGXO+WRQ^lUwtN
zc44Q-f&}y$=#`3xY@gTm+;2b<mTFQOkOyuHDLgbe(1&B#@z8IfFNd{<>JQ(9_Vyay
z6gooG?~)z41@!S~3JBH{hI@OtA6z4*-sspFJzztptv$V)&V}*-N1S>Oj}I+!LEMC>
z?_I^!NwK7V%>k&V1n7g>#L0|pWM<R64y*C-_Y<^yXj@;|xviiLMlXOgF$!Cg`_9?#
z4^~vmewi}2sWV4yOYmR?^avm#m5}Wd$#-V{=#}zhOMluIPK)RUmJ2}omoM#$fw+Y$
ztZQ`5WsIc6!K>^>#K9{Z^L4wFW#~2flgZeJyKnuckGoycvTS%Y3~+-UKE#C=QN&#?
z2Z;lSAF%VF{StVP#jVbT+5qA_;f{a>E|R409YM77L7#_y?S#n?O9e9PMvnX4$KY83
zxDtB*=s-4}EeRYUMxGwCET~P2(TPLcb(mxn0*n0U4{6JYTNj@h2$HjA5|RVqYkwx}
z!oV?b7N$A+(=?FVvm)&(5Vkbn6aWRR^8{00Y7t=9iqsz@!#H{zaB-*k&_IO%I_`@$
zktr~aMIwbh5yZx1z{Am44JtT}(bg!*s$@_ICmT?~1p=$<s5*fQHNQv4SSNar;2O{)
zgET=9dl$Hm%`SC`&4HjIH~14Crf2C;vDSjfgLEQfA@C~}VoTu~q=kS6mGBIEanat;
ziB}<vjY@cjkdrAJb2O+yv|$8Xg*2!-*b88CsDv{DJR1@=NPh|cJq5y8FlJ|UpvnDi
zgXe!Iu+4pGdZ`XWVU+^;IdK@wI_Dw-XGP&&RZNS%X6UPE)ao)O+TWd~<}~7Vf8+Ex
zyyEM=AF~6C^oE67{}zf79W&st%bffJBA9g=3EH)%!Dn$yLW(b%L#dn`@|VNtxz3Ca
zxC+;QoH334TA-}U6Mo8xFs5wYIa+CFw8kZQj6>X)7M*`R9<x!UYN&%My2FnLQ_n6^
zfSh8B1Y}}M^=Z-VT%dExH*lD~^aYBgBktS*OyuPG8ecyW`7{lj^%p4X?%J?OxhCsE
z!e6yPbfAP8i3fSq0&O^;^sjw4+}o%c8qVRz;2jRyaD_}ORO-9oyF5aF`g$D#db*_9
zY-=72n!qrYy1B5K5`=zim5DHcvJlLHsQDY#35i%tXsyBDOJZm*Uk%3i%Vi@J1V%Q1
z7(ReyKf7Y`vGeJF3H?~)(Cb_AZkQM!fzUm~OAxf-Dl8!0ZNyBdMbJj<{V>)B13{!R
zL!o9ZdC=o5aRXbWZ)24Ws7sC;QMBRSfk|mbAG?`n4>*mgVoG)*pY*mp8bN%2sp-8(
z$VGt?(gjlCj*p+~(E%2W?u339%Bh@J`zxW{;2q)(JNQmcs=qB23v;Z5j)7+cPWIv(
zn;B}`z!=F3P@UP=CoXsOHSQ&d*|3hoS3rZbx*JN1-p8D{oL^((PvZv~^g1MSJ!N*G
zH}_NQ9WsLtgCGfy4RlcRaclV~vIh%GPoiBn!F9*JN!bF)b9ll$NH(B%Bd>-pq(+Km
zPaep_rp?N7f$4fAef^e8q@?~amhD+gb`BIo(AGYYIyqy_R2(Yo|0`^SXlKWjennl8
zhu`+p=OaVdOcCq`8zzkwE~w=X_{WP9ttx{4Jl3FJ7RD^zfD}}Lep$ITYm+u>)#@WW
zewdcloyeF@=tDhvTAM|*Ma3`8eHnF#0)|wXXjdY2F9!<wL-F+cJutL-n$W>`Xr2Qp
z&!Zspa1i=c^#K+hvOCK}PNn_SJ?#1#ip1=A1Wu9p(3`1T({bD>Sr}gDcivb;s!hca
znIkw!wA=ciJ5+eUzzGSb7pULATorGTKPjr%y=mP7g{&Ey%0<ku+9MAVQ=}L^fJ)e@
zNxzBfaAq$WC2V)O%ulpCiGWaB9p;gkF#~!$Xe8O?<G9e(vDoX2-!%>8eUIVoPNQuA
z%MO==XbU?T54Bh;N;GFuD%Ne0i!fc?VqQN=ZrtVc0XYF<9<wK<P9Lz=VZAX!wh@TO
zFa@4F7X@w_D45e>+1S7?uK~<@)C^s}67%Iza;MUvv*;K<7HUr+tw(I#1-Ck6oR3gK
z#8mA3j9d$tzmTs>e@-bn1o0ptJ$R|Hr#VO9f?RT&77&8RMv(gY>;GEdUHwoL(1=Pp
z%%LmKgV4D{MJUoYmSqXCTYS+qF{!ar^S^0y9k~0aAees1Z@#Ilvf`yqv}k5Sj6K{v
zj1d_EsfDmeNNuMkosJnP&kJqRRtS=12dle&!pEgUSm25IqWm$A@6Anq-RInZ#+&~D
zc2zlR&QIzh?9qBAhh|1*j8U*`sN4dn<zKxUW3e~ZR7zc)h*{t~DfA1u#Yn7F)%A)6
zp~P&%PLmY%Z8g>sJ2hCE^Q6B7)#W=>v&upRZ}hE*{mkdPU2<UHx3v0y1md<4oRmrW
zI)A5$5RBwgHCb<h1$u;{fC(wo{%Zc*t_bmr2h~Ly9FVN4|C@KkCUEaFx>P8IOd^2k
zaDi0c_()~5PGmf7mGWE=XfVgZqhr;Z({)HrPiFvChv{%RecB@F<r=Exz=uU@2nB59
z{{K$x04kEevcYMz1*;H$Qw^5tg#IRpAR49}mV5qBgd!3+wj0sKN(<c=P^wEnq6XEO
z5e@`OKp2^Q=l%r&eQ2Y5*#)-1aQZhdEZLld=7Yg50>Q{VFCX#)c|5Erk}BL*i`+{&
z)`#cDIxAYWH2V0II=6L*{51ns13+JZDN#Ed)02*V)6w^(Nr7B=bZrOJra|;Uh4Gob
zsGtZ&BI~`q3<O9ptRQmdLd}{Oy%5q)+YGjJpvbnTXp=PKG@z>hk|T+}ZGEa1xnj6o
zn-#~6=s?;LVo0&i($;}Eh!kXP2`@gVu7bTnFYQFEx=Nq+$3bp5#T?b;cZ1oVISaCA
zS%oa;7$ASSTNqy%XTTbQQ@5wE;=KXuB$!fdxp2kG?38xVILEt60-jngGS?(XCtwaP
z#Iry4o03A)Of1a(*ey}7e6d~sKnt?EaC)LiA;80}W0?S<8SbdR1mJjYJVN-d5{wm4
zBkupYGQq4DLSp%E6fa1>6Su6&`QQ--6ENR(L84Q(7V}t^6avKqpI{{?eZ4TOK!9$*
zP*{nNO&Gv36^^cuD2v`4^$gNoF<|l|Aa&At0etLc-5fx+zyMM&4;+J>Ol0><`C~mF
z5hF;QprcF7TR@Cp1V%BuJ__wVVBsXQaud)e&_E{<*9EG^`+xdv1sf<H=-NT7{ey93
zBD{#Q1b{3%E{l@ckyajRA!Y4QnF#A0pn;}8w%3Tud-&dQ#3b7`gowr93H|S+6ZzHD
zdq$!D?dsU1&V(m(K;hMoJA-92URz*>JGS_XU3QrL?5@nUUgkDf6T|7lG+^!VM2mI0
z*!7<fo?R|uHv`0?4*o^bt5epAa1%Ti_1UrX3A2Hal1hF^S`x$9`?YK*a@~zoX0W*V
zVUS~BLwOG(0C3DI!4^rzO|O6SJbCo8)LvtiZbA$x@O}^psVi|YUfQxeUK*SzGguGZ
zYH=2Q3?Y?JTX9_bdep}T-hNq-YRNp!TSYwGLNH?6en7B}5>Jaxt$3mr*fa$Z`GAvj
zm9FB7?yr+&v5+DGEdEFwRSGeE{nY@uXL`ejH?dkbe)r8S5nV(wpzj4u6}iL9DU@Pg
zP=5qSaIXw>%s-;$eZmhWfp7ul33j?rp&MvDNpC^If!;lZG8fV)L~k9u^W!{`nWfE|
zQ8u{#r85VTfkF6sL0QA3INEXH>I+_j*M%1(i~^w|K|qKOUw+jz7d?^PgYdgc>@0-p
zF;sx2w<FS((WZjbTbU71IP%`U;C$6k4?vd#CE>s8=9@OBY0(3Poc#s#HL>IY4*dil
z#d?I1Rdc)7T>j!1lrYk$B<SG=-}#E9X<5FY*~*?2>QQ)_<Rt}q_<@WJV)YqJeWbaQ
zQhRu?hu`-hWDPKwFuQA<f~KNR3|QWx&MyfOQg1+y2#EHEq(cPg72C4B_8-sb##>A!
zRuAC3*1K?CA%e_P%EVB8K|4<YeGL+r;6>79X<6K$t`^(R+ASHecF%Gnwm7dFVmfpm
z!j=MP`qo}hA&wqZ4D25Cu&PJ2J_Fh|<kPv1PS|UW21x#QRB+=Hc*D9#k6!5wVIzt-
zuhiNJbCaKytmYnoZU&J<7C*<Kv~?4Zl;02lxm4H=@~4L`eatvD4&6Df)dhR~u>=Y9
zJ4S-3M#3uDkX~YVDMzwO94)kb6B1AlC<Swd#Ug2wvHZTMDZM`cR|#GAW4z(Eg2@~^
z@O^NGz4i(3KX5z2<UVxxRlsKrJos33@D-p<bHiojD{5=>mDTbpLfZYhM~4A(qTdwT
zjV-r>Iv(=@!4atS@TQjQ>_hIfk*OK28<v91Y(euS)CWAx5THAKB5K(#WS&zvGNku!
zjfGCU4NwXtG$(KYhrM!WS@uiC7l%8F326zZEOy6P0j1P;W*J<dcL}hj^rp=QI!d`R
zN%{{GoEr=yi?;$Fi6NFLj?Pd7Q-$BpD_noZ)5<^Hw8&Jwucm^ywz|5e5A(_MA{KRP
zAaps2=d7oG+KmhM&92P2SIW9)yyCIuWskp}*CgVjcL44s0#(Cj;<8ch+{ub40^hnd
z=mjS82bq-W<=m@stK+5wCO2YyGX}F_Z4xZDZ-Dj7lt6!e{S;uI`^?%8M@2^3+jH$6
zS6&>v$AcAzc)DR(4^sY5ynL)@T=}1)Ug%*F5YH4;)nds%b~i{AOJ83wwSgT7K)B{+
zULd?<vo_Y|z7vu*X_HdtXEq==A;kF8m69{q?mFHiW|FL~36igh_9S9m+g45dtJ7!$
zpl$9;@_mop=fVdTkuWJjUeq)f7_e{3J_sLD0K(pKpJJg%7{tr>C;JW{DVRVhy|W*X
zo4kne0I%LT)S;CHSYK0Oj!6{_d{qRYrNyaNNOp6>7NDZ<&@=lDaJP<d>H45C{K&H-
z%0^zD$bWvrX!*7_pEhLSH%#NH7(lwkGL*qUfLebtR2Vjg2b84<H%FKd@n&ku4OEPT
zws#S36jZFpfbCp`8qD*PI%h!W$V~NYV^KfyxjGDh>D`$p`w$zrR2@g<ed|EDLAf|1
z2yT_hB<_$>_ZfY^7nm$Qr`ut;zjhwxMSfgm(fC=sH8F$zYW&EL+2OmEbkwVNw2ylp
zMCtNS<pNv3ALD)w1Tv3RufFY+VkmKPHme|8_6)7plQJ)v#JFmw5>)c&1+uhX=jDO`
z#~}CRh=oieh4{9HTBUG)taRzyT~`O->fRq72I3<A-CD{RgYJ-|>w!rx)Ry!4(hn$Y
zW>Vn`wlP0=kZJfC_L{@4upb2u`WC5xWZR`%P7x3i+q)6gv+LGR(v5wAsFI~TY9J+V
ztk2U4kze2SRObVdu<$_w4!C;Wb)@4F?Hc1vhjA>=i|}~UHt^|^&_UcLr0|0KdLVcZ
zQ5^q-hqDc07cX1hFzjnz%)uuMCyR>32!p+GK9?>Y*cN#a$W(Q`v$VjS2T@a1d$t_h
zG$K2qmJtTvs;*~rl6WU#$X&<t=Dt=*yX>BL$UY|CszfFaV#E!`psk<3ESF>qCB$WL
zFGU{lq3On&o|4<?7;AAc;Y#f((Lc44d*h*BF{W0VD<Kh%v*zB2cw&P+?Krvo0i@O+
z`H^J8zyC<$zb2&RUD1y+lsIOavNfo<tzx3tnyiRc)|A}Hhr-iP%O+}04mu$kw)EMz
z7m<W~h*yEB7+(AaB*>Ls*0DehYLQQVz-N62DfC=loDCPttKmr|FL=bfKgNzCRrOeO
z|I=h}-6A-E58{|j{UbeABNI~?2>;8wzeHn8vv7n{grJ|vr<h&}<6SY;Sgv~XLf-e!
zkNNj7Qgv9lv&O_N<l{k`R7F`MFL_&<p`*kGoY|R2?4ma0FjOZhn_Ke?rxQezJ-GR9
zBkiP!=3sG1HguaUcJ801?ZEWC{f$gQza*o6h@&Nse*TSrZ-i`7P=EIE7w0X7J$D9E
zt0<VLl?BNkT2Of%!5caeD=1R)`yw^pK#(W;nRpCdDj>^%<-20kG|pR1{6{e86=JG_
zJE_AOaTn14Qz07Te%ot#OP5v)lxof5ENJs}W*nlgZPN)KN&^-_qd}zQoP6k4biCEl
z?%v<qmUYS{(kSo_F8v?d^^faK?Hs(cbtyJ!m6}l>U-A*r8gBjZ!e*;2oK8%Y!S5iM
ztnPc@aOFhSsTLjjls-$bQO)~c>^;A-v!vx0x-6cxn+m6QxsO1u_372~0D#Vo{{pB9
zW@V8^E!S>l5;PCEla}xI@|j98>e!dH?fG^UVtwdxaD!2Z&fA!M>@Ce($dxbBc|S-o
zezb)PJx$Of8~!$+FFt<u`$mG^C)rDGibwX4)Ak7IC#7jT;`T1zE^An;6ttJ#G|(nl
zJbUY5PMcKUtMB^7%l>_`;a8LXKmVWLAEDXixoDFinZ<otcMLH7fayVV<AVM4*#89=
C2tB$0

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/mistral.svg b/studio/frontend/public/hub/profile/logo/mistral.svg
new file mode 100644
index 0000000000..40c2591b31
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/mistral.svg
@@ -0,0 +1,19 @@
+<svg width="191" height="135" viewBox="0 0 191 135" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_134_208)">
+<path d="M54.3221 0H27.1531V27.0892H54.3221V0Z" fill="#FFD800"/>
+<path d="M162.984 0H135.815V27.0892H162.984V0Z" fill="#FFD800"/>
+<path d="M81.4823 27.0913H27.1531V54.1805H81.4823V27.0913Z" fill="#FFAF00"/>
+<path d="M162.99 27.0913H108.661V54.1805H162.99V27.0913Z" fill="#FFAF00"/>
+<path d="M162.972 54.168H27.1531V81.2572H162.972V54.168Z" fill="#FF8205"/>
+<path d="M54.3221 81.2593H27.1531V108.349H54.3221V81.2593Z" fill="#FA500F"/>
+<path d="M108.661 81.2593H81.4917V108.349H108.661V81.2593Z" fill="#FA500F"/>
+<path d="M162.984 81.2593H135.815V108.349H162.984V81.2593Z" fill="#FA500F"/>
+<path d="M81.4879 108.339H-0.00146484V135.429H81.4879V108.339Z" fill="#E10500"/>
+<path d="M190.159 108.339H108.661V135.429H190.159V108.339Z" fill="#E10500"/>
+</g>
+<defs>
+<clipPath id="clip0_134_208">
+<rect width="190.141" height="135" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/studio/frontend/public/hub/profile/logo/moonshot.jpg b/studio/frontend/public/hub/profile/logo/moonshot.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..956a5b58b102ea01c21cd7a9e8697f42c3af73a1
GIT binary patch
literal 15554
zcmV;zJUzowNk&GxJOBV!MM6+kP&gp2JOBXj{{Wo<Dv$w?0RR91C8fAK1l*Dlz<+n!
z2<%B>{Vfk&`QV>4dk5JA*BDt}SJ*}t8{t2}zvF-X|MTpF;$O>utpCyaOZt)T-<gjs
z|Ht|}`lbGdpSQpN_vrWXKe%5d{^9yr``P^i>yJo&;rNsKXY>pBKk$F#AB7*SKkB;_
zfDhrH#Xpt*Nc}VZpZ<URzh538AIN`}f1>{d`)BYM`2YKUWgmC{MeG6mclu}hfA62S
zAM(HUeXf63{+Io4?7#H?a37ifW&bb!6ZUiaXaBFjAK|~of2{v={^9-K`$zwOtp8^p
zx?aX#t3U5Pzthcx<{9~haS;prFp_Y5Rrhlz$yj6P3F3W&_RO7Xy03=u7Xa&|@#YF$
ze=zGJ9Z*Z|4Y*nDlhiSPiM@e<{d|7(Uvy5Sm}ELQm7U-Rh;ZH*y=#gzT>6SNh5H`{
zSLIGs^6vBk12TRG5-wS1c>(tT47`|Z(Vv_8J{G)8>q$E&FRZh4maVZPK+XXHuntM&
z(a6?8>kmtPRa7iqJp7YN#UT_-x{~X_l-sX%B2<r#;h-lmY3y_X4;4~C(4;3j*$33&
zxd=Eyo)=+fh~rbsKJu!_*q<qzzsO~o<;E~*4HB84v()0~n&_i)HtfT)uS!7T$i2Vl
z%C~A0eoHQIV1@mUstx036Ye}%$B-8zckIE|_k@bTga6qnDE9Z&0V4DU*M^#P|607F
zRu>C*ATh}|c3CfJcshHplr<sKh4CF|#nX=K7X6S9a^3qWl~6FW>P$@y|DCejr(;R$
z8{dOjZ|e$CTg<-^tYI*pwC@`vecyvc;W*8~T(1@f*#<qkGx_5s;3xXbh~V|}!cBRw
z!K0v8F>*r!lVcI!fR0svIuPBn$_D<Y81&Cs94Mba=)yT)O15Bu>67Cfr%Db=Tdp21
z%7$In*8E|e+@0q-BwGh%@<k;?UHp_YoljvuyY~|Z&THfO{j-YIx8S_FIBxu~Fd_N|
zyj5OhJ13udDD9vd>}X!RiP^W&;NR2_Yo?3;NAPbN`UF`$H|WDBmd%MkdTpS2%H52l
zAsgh7C@UJbH9^}ve@QyQV>wV>#{9gkw18vPSVxd2w<yX6obj@Ivph@B%U+vNLVqn7
zp}<1V-Nf#S7B)=?$QT<A6Le_?r(4)fEItXU%TvMoIb>}`81(Ui@CyaYwbHxo2lf}R
z0hI_&iWzXPQfduUJukcw`^u1}(H;r(Lo@=xA^Td@)d1j+i#}3-u2EL!Y6eM@CN|R4
z#R2D~{e{)ey5juC)FYB~<#eMXGJ9rF5bkHwQgT|E8lN0!TRqztxMlFugojmFBmS6g
z<RHv}!10qV8Wc7r&M?OtBQqYfIhVkx^@jz=NL5nHJP!aE^?-F{!)kABqMd9G>cryg
zp$&WlStW3oVhX4PG~s>+RH%NuBsw95-a$<po-?gW#e&D#uQ;=`dnA+rk3Gn<go*!f
zNW5C;Wk#<X04VUwnOET8J7@`E0w2mRP1QUs=Gh2#%@UO$ag%1f%<`y}fssN8zD?qS
z9w7#_z^cbk;ucCV{EMR;VG^I0GXgN<^Vh{BkFgSt?~1PFTNeADEimju8dkHPJvH3C
z3L@=ru<l@+c1Wb;KThO@=k-j8XUf614M}g~94;`ikT*Dj&3Fkuytp~&57XVzx)UMb
zZ-Yc^jA8P?GqyO(mq_=^zUM{2adHd-?L%h2c<J(lK0io86o9q}HSY(O<-7)t>Tcqh
zK9kX>f@{A45Jrvuq%i}ftzoZ{ML%x+!L%Y+Ge>S`bw<S;70$%N^4f%WS_AE*rKErJ
zYc=v~eUH`iCLiEaDgeNc_MxWBLs&U9&J0(9`o~&60N<Z_zx*Q@=6LZgHui>K+|Y}n
zRY-pw^9gn-|A}7Wyxm7-I-_#4sWH=(jTt!8akaqQzzEyrOBp|K6_v-Fw4}S1-Ecj1
zp}8MG?K&>X8`-}vCz&SoQ#xtU>pf|_-KgeAFSfeMy9Mq}ghaeHbdoJ^I5W-STm8VN
zGW|EB+-BsD{s8nj0piO7!CBivo7Iil*L(#6?!dITO?{(rwB;X>+zr1iXWweu(YS%d
zIdVFD6p$a}gV~`p9y0(C=fNUbG;`s?33gd^z2*>wtk$BUun2#b=K<OP7pV3uP=U$1
zd8OB~K?;K6MfL&*&)q_Dm)e3~rZ69zs1dY)aVT>Ztn#1dqlEX|KvKLa-Y7sNH=t7{
zq!9HJFy*175&`4Xc#u;?gI2$2!$S!k_jtbeK!6V4O0fQR5Y){e4bi;7N`im6R?erZ
z7{pF_uB?<t$?LPC#823=%?RQQVBA2r68r#Bu4(O)Fyz*y(QDq?nevKb+yOI4)#i2}
z+RBHe*ueShE;CVCU_ZQvAWx3kFywY`43a3F$-lOq`qA+8ilj=@QgAogkDYmUskO&A
zL-aZ1@v?4!l#}$Bj<#yMruk9IX+R{hjM>-k0E142U)}_n&mU6!)v8qXDm)nbGq%UW
z^5){De@H_kSIbxG21?L))-njfm7Wqk9qa_1VlQmI7?em|_{2_CZxmv_HD(d5dc+_Y
za+c&-b3XO$5K#akBuClqf*Nm5GMZN&(sik3Rk$9r4>{vmP}0qF$2x*TBS_s)baR$x
z#@29|MQ6W{7@d<sRJlajlpf3$3gzGydN@po=2d~23o^M?><)eTUMpebpPwAZ#8_K!
zr+5GW{`;f#Kj&{c{CvNE_aBRXB?lGn0qq&eWnUbK@070=^G!fLt2z%`a=oS*>mSLs
z%h=flwfemD>3Vto?Ybt;SO&_`eh$r^h}>@&h6UPZcr?NW<^1KEQ<DrCPiG`YzcXl1
ztwX`BdgmcZeX-fMSYLf$*<7w^8b{6IN^0(b25pjaMcByiQ&f4pn%sTP?@A8IUwr2(
z0<wDSt8kd3M?Didkn=pBW%(oegm>6Ag%%Cpi<Pe5|A;q~OS%6iBm$ZuEpGDN8b?2e
z`n)K`X)Q&6*HAdphil6#wv$SY)YG>dDvfY$6%Tyi_A!DE<0d`=jYvWdxw|HQ!mfZ%
zg1vr&_2hy|<Ra^4%5Li^3MXu|&=Z2Fsg0C-C3~Gd38Y3mVSXE1gRzk`goSR#C*ZHd
z7fK~X$LctET;4Od7N9{U!rpgmZlzfCET<ST;hE8^ijPdg)DpHqZ><7K3RAwpay~S(
zt+A}J3Yp}9%(<JBhSBD@d-ehdU6kMCK7hV^{<6V_xF~Q3uKCDQ2ZF<*%IlBddt}SQ
zms|S&Teup-sc2tJG<=dNR^XTXb{I}hpbup;p&6xuxwB%t6jR%{jWzKCMwUTsd{`0G
z;H<!qW#p?=>H%%(b7-amq@U|>DFh>_PjLb?|BWDko!f?V=1Sj_f?5h}NJ&@uMlM~I
zpY?AdD$!0Sp(P*R1te0^+K&<`VDYD#)s_;Me%=u4tS+(77;S69q;BQVNOFTNO;jC-
z#Ahi=fjJn7SB_#pz#fK<XbXjB_4r5ge+2r%X?npLB1U1Oxbm2wgB|2JyiOC8Lqpdo
zrZ;htZET!BXE(RqgzBPQMcYpG<Ut9v)UG5=$7g_s{StL0*JV<vNL#I_b>g$wR?fuu
zXzg)wYH>Td?Swa#LlwV8%Y++`Do${43zjRI`e}+?3N(INziE?3`;ff+=p~|xB3Gyk
zyZiYw9@#<I5>9S5v0L*+e(sdg#Bs`YMj<r@QC~DdG;D2?(J`2$`!qbBo~nG*M9y5%
zFa^|dqFBw*m9~AE&w86-T)lUmN^Q^Rq#%eWU8)e7`rg_G0)kf|UemVLudci2EC>GW
zpTO^_$Mr`M{>xbazAlgzxhMG><tTQd+igh1TVSG(uA|xsZb{KxI5mKbByfxP7;ZVS
zFD1x>-6+??<h)SYNfo5y8kEaSvnGhR@@r~qJ#Y8cv3%nG%c29NZ}1-25>~KEL-rX>
zk}~AT@}DAOm5~4|+&1SVzu$R%^UZKBXfkn?$9?qm4ZyKElw+YgUUq_)6X!v;7ag%M
zs~N3jas()Ski-1-wy%p%>fa<~U}H~N9za{%3`2(iW&8t9;2uW%J_$-z={EjFHCcUQ
zk(u~KdYG7of%C#LA=Gs}eUc`Bw?}SMBxQ#;L&`LFbX0BWp;Ho)1!0tF+-K?fPrH^$
zx^*&3lVL!yK@r2(cG^QfQf?eIMZlrf=wkLyTvo^<gXgj)ahptuA-yx4`&1{*brVEx
ze%sRnY7Z*mtY>aQY~egsj?-vR>3n75f&i-0Q)?L|B3bKp(eh7%p)jBpH4aUO`?hGP
z)^RVvaR;MaKMs!?Ugpl`Y4;mb*CqrC843100}>W<NfF|CsK6WmFD<6&D)3Zo8$KQ>
z7fvDvuuL<;8L%?xw+HilX+p3j+&sl7FhT?<FbL@K9PuaiOt~93+X>{g`ksbbHSS|i
z1pn-)-DrRRjB(}$svyld=rv&Y;hQ!)0!{$0ee+KMX15s*`iSA4DeQ5=EQ`F)+Bj2j
zdFm%;+OXTE+bJhN+~}HkD|a8{?~fykFaVH!YBcXw%1Q?6^n^zp#SGnDp2X!ct*P@_
z8H`yw$U*#<|1v_%A_4&_xv49%IfH44S|$#gK_b+?;{DuT^(p<42ka~#cwrP2(ac4m
zxAsvr+t1s*^`~HV`t)t`#|G6Qu96}@gUe7>In)pku*CxcT*==m41-?la^DNqe4k5}
zC$2>c>SwFQM?b)rBXTomWsTuQ)c|pd(sgN4T_zL+-T2G~;v{HofW-i#65ONbROld+
z<{2fm?chGzT!;qQ{71vNy1mM38el2f*Bb!FVzdV)W-!L?&e@=xhTHf+{&((68rIKa
z(tnKA*<bV+4a?}LN^QDm%yCBTMy@I%H|8%_L6f(wU5eWHKRtc$cgy$Vnb|kGc-jS9
zq)2hbV}{58d^y2T-JTS1Cf5SV2=8qdAE{ag*b0Pe0X)y0elUxiy)GGZ2)F8S-G3$A
z%`VGNX?p@4&FJC|Qyjq_HVC0ResQN4Ho(Zckjxp+@q%HG20pSVt}-fHCj}Bwo5J7n
z367TOXcifUoXc$EoVSr>(Ac-E3ba5^o=i>!(vEF1K~8T-j&V2DjuHJQ9G8Q-GBlqf
zM?j+TLh*E0;N2?fAN?52<J7uiGC@43iJ?m)ckos)4o8{N&BF1A!bXYdoE*mL{z%g2
z64owZ9Fp~m&Cb=~!QT!IJq<J_TWCNhkqMX_ZNd0Aw0>42Jb)*+M1;dP@z#KWEy4N@
znjVv`aE{B4(PRAS5E^M44#&+!!oSujK>{SePRjI4Na`gBac<tU$3qLcB+m3%sh=`}
ze^g_R>~>)hq*~2sBWRnGSSLJRJrlnJ=|+(VvuJ~EG=Uc7%t{N`e}SXo8o`|hlq|Nt
zzCTAVsyCwqvw$!u+LHjW*V_qRcVS>z?Zc$NAz9RTA-(R1DIjbzdJ&#@O^US3K+VCz
zyMacCkWaaMunDP_u=L5vfF1FH_9;Lor=luj6G4b+l^3caWCQcxN88<YLgXIcDt=MP
zcu%R2_H!?}&+AaZ$%Ip#6}}bAzU<k7Ya5P2H!AY~Z=tB|2Q+4iVBxxe;1kOMQn|xi
zhsHTP21<!=usG_|3)TU3Q>2W{B+;ob+C*Qo8uEc=)nUZ2_`us;Ejb#RntTEw+(*cC
zIj#nbvZ=AWm(3S>m`AX>c7`T^ZmCR9MnG0f$pZVX>3%!YwF9dm(^A)5Dnwbi=7@nX
znHpZpnfog4%|IB?n)e6g)R{xirfg~{H5Q6|XYkjs$<3;O8tFY0WaGf<n%s+^7P~sg
z&5`3t1F#cXD&x;+&j{?pptpyi+;`GopGS;ptnP;T#J~8FSr6V}Z71F6aMn_zreQLR
zHCOi2Hg$q-?ir@JcJSV+nzw2kmSFUnmy^1DBS`Ad+hNl>PQDtG7pyX8sOm=HIJ`YK
zOm~Cn1w!8O7&b)JcB*?g*KeU*jLCrfs-`;~fd=C)eImRT52ph-31{5sN-uyvySy1v
z>*pY6IFI*bvglET++Nffa_*dyG;X|t1=fISv5lF4tmNu?zwhec0tZYMXTbIhXgIN8
z-dO5rFa%hPE}v+~GNZ(Tcl+o6ZAwajW0MN#w3%B(&1tGg+KE1aOVMN1u-e+4y^jUx
zF_gxs0w=G!f#zJ|>o0D#DKQ`p0#O**$8Z2Tne!zP{folc9eMb%j<SsgZAI##Di2x!
zA_Khk#Cf8B05sG$wKt<J2rv0yU!av~!2k(^3q6H3^|Ij!>WSrxTM~|%c1}sI8C}8M
zDGI)hK<8linh1RFeHHMw_Z3LymBBChPqD~vn^ggpTp&*WKJ`e8(SZ~{5C-4(!<Z`&
z4hP=!@8U;fR8Do3k6DE5DQ29<-~I5)t@r7ql{ltgE(c3waEFWwz&l!Ar&bh}s_7NO
z*L_SG5}byV(bvslNlh<-7`qg*4Z2KL4B})23g4YoHg4O`=yFRfHb^rbRhwDwP~>dK
zS+MQw&TEgZKW)-^a|Ul;8+U=Bo94L%#*s76UCmG1$~=1p@aBiB1}_eBMf^aYf*4#^
zYU;VnsN=u|LzUVFVVbTlrSx-XRTf`#Nr*LG=JJ7_Uq~#5J^%msAiBV@&fb*5kWGJ?
zC7yhi!oedTTV#_O8m~f+0`DTT_o2lyj&$H1NM|wMn<ydnUNkFb$eww{mna;DK*TKr
zcU=80d_Bl1w*8lPUCaX42i=+(SnJ+YGN$9L@D7z<<CYCjKn5Zbjj0#9sZjDRKbQ1_
z=fT*WpLc0=;SwUBO|A5-BwA2OZrbD74{NR(?0YN%UD3ge@~qowehl@+q-pe*qJYYi
z4E~gfyn>iW2j$-)EP7cIiCq-zxB3o9d#2f)r8zvaHrskt9RC!-ZQJO%Zjque>)93V
z*JtTAmPbY{n%oPLDbd$3vO5QxW(8hYVZ0$>9IAMF_bLzh1KRVqSORgDJvB@a>{+8X
zH6e!fMQl{)Q*1@0s4zv+b7y#;WMtihoTntS%|D~9ygs4cBS0L&s0ag*FN|E1g?Z|p
z8`Hix&?o=?)qZ(kAoB9%I;WR~)_MfYVCQLJ6pmv@P9^^r9$x$1z}NV4=PuI9q<5+}
z8hyAs&;^$b0_OHDzrVn036tHw4)gyf`_nS(FV5~_>V6(mAK6p#cZjv5m;eC;b4na%
zm(2{`0xJ~-Wnes@Zwah5fsUy&Gk_)l6<OYu`4f4ZJ5iKg$na*|w<KfMmAvIq&Bbv0
zZyor~9WVHf#63-j7Uy!#God`ysnxPwZE64iSsf|q(agJx+*(|ng!Gxg&M9vdpQBT7
z^tjYkRsR^sO#D0datIeTGUiOqaS5yh%S2%(eHrP#DXVFbtMBt4xo;kD{D*jM;Z}S3
zT-WG_)k7vs7MR`#AZ!7$tuXNguERREaPL7C_zCEQrAGY@F3~~6edr!d?wn=WWXg+2
zR-r_G0SX_N`HcgsvHv?m+Owa_z9k&dMEt*vbsH8FG=M=`{;gRw#UzeODSPM&qoS;<
zY5gBnt;2r4eV))x73rArkIC*~`>t%2;nxxgWu<FTj_4hx-3`67z9~qGCVgmdpkAH7
zu74DBJ)P>%0l2I|R^!FTukxHZ9u-FUAD_WRj#cbeqcgi1gsI)Olzt<>&qyss<cXP%
z1$Bjd{HJ5&a$SJNijV!>k%1-(NoyjA%vTtc_v9MQI0LfkC1H|(M=RJLKHD!rrsQiu
z{o$Vcqdl6~oLn~?I)mLOw|!^I0Jus;K5Z%qXQue(gRn{Jqo=|aRFoP>d8=#8`O>g#
z^7a#EZ*RweiHh;{;pFn?qnG9rHynf2*C>Uz@VM$cu=38yg`@o&fQV+AWO-eCmqN(q
zh;K7O3ga23en)spA&-`sY`#}#y%4MWcDuHjmkm;W!yqM3e@4Cgc=NC!MEq1jDV#Wi
zBFi0<<ev`ti@$HyJn+rkzP1(@<@2f-Uz6+3@Yy8}VMWfDQ#E2rgfY{g5EGWFl))B^
zv7NKp@VOq5R<0`I>af3NN$j<i4l%zeM!5k{>;pDb+1MKSHSRZUC!yWN9T?~~En@ke
z!IL28z?)`8_<4y!LUxotzR6u6MRt-Gi<CCF2O~D$HrY)LA1*JbY{TP=(&r=Aj%Z|@
zM-9}V33lV^&m}tdVls)sa~aAX581P|RO8QJtr_FiS$X@MvHK6pkGRI#*F$tF01O2T
zLIZGy`A-h2V?o#iYMBbL1!sVtmGYZeB@H0-t(C+O>^V(aQaSHobm6X=ciTyc(3r1^
z$L&9YjBjcT<HN4kKD&U#rYc1KW~f0wUgrarS&<eYl-LcC{`<AW5Vdl7DTX)E<)mN(
zXhxRtM?m$0W3t@aX=MX6=F%gRGB#wO4X@Ry|Gonh>9u8JK_Yx=u1D-DiyfCUd{pS|
z9}TH5>NjC(byO0hZ<P<u5u|xY&F5prLr~H(!UEbyT-S!bHl%D4<LhJ!Dp{JXM^0<Z
z!}x1#aS|Ur^8fxb`P)RrK)S!c8bkHe8;R2jo*}9CIq&YU@Omv-e&CV?@vTXwv1ARZ
zj7uq1E6vbo&xwPGrf7K_7td%#Q^MG(yP#rMFk#-T#s?@eyvr9MI)ZazgKfOV2-_=F
z$`1T}*8rp~nx#ozN|8-u@N**`K*9Y+j-}|5O86%gzl)oqQEofqdok}Q8rT;^>I_E{
z%-FVqzZYy)i}IXEr~Jds9CuN6h-d<vj3mu+QbKp!D?<FM4NNJW@R{@u4)h0+1#E7K
z;rdG|)dy@k{!KE#b_*TJ68U%evJ(Y9lHB^3(SuIVeQ(|ddivsHCZ-|#$&h~6^EB#}
z-t7$Uasnvs<k%xP&^hJC!R#pD{)j9P2X^ngaYGi88<UG6mi?@7+`nmkxVq3>jJPhf
zqBGiB5E<fU*9Pl?x2gHePq@uYh@6xo&U9K1UjfPPWQL(|V(pDXVD^#+cn{rkec0`e
zM18$G+PnYUD>;oXT1br<<f@ltFkWK_)ROiz<WwK(cFVx_xc^Li6qkYr)C4#pW?|U7
zf9DiD3S=0{i0TOFgJH6e+slDNHDmG7`3Y+h<Tr6iHEGiz_6bJVR{om%3TUB`8ORgi
zDN1GV;-~S6&V<zzq%+Z%F%UpWP}~9{cI}Ggmh>gY>B~=?JO~vZYB<`zv;}lAuVCOh
zk*!?%!gIii>I29bE`{yFBX6<UYVAnD0J(Ing)J$n30yy!fn}oZ>-5^%jh|rxQOJ;t
z6V(kBwXabBWniXi-0>?h_y^8x<Y<0j5E^okp%9n*p$zq$wbzD%MAHTf^QM^AwQPg~
z`Ce~Kuk5>&&z4tc6z4L3&!@7u7<}D{IR`TitUz)x`3c2?>r!_#7T3=G(GlEsf@J|n
zfuQ#_z-w&X@*rlnkuuVWfgOXU8teLF%LAjm>&3BDWWHA{|7%IH((I01l{|i18T|cm
z7=X*`GE7G+8Cca>E^qI0mh=ZC*(S_zbAY;X_N)?X9Ed70&AXNvp&x{jw=bBJhJY>D
zgKc|D9ZH^4DKS@P%hV#Bs|EX8j6w(Fanj#tG$D#g8tN1KBXJ!PRj$6QAPw<~NjV>q
z{$x+o+Ul*2zd8UTLeLp5qdoUkC`p&pz&ZJmDMj1`uL*~KH>2*;oIX#|Ck^kXQ0FHC
zQ+J7s`WZTEf7kp%fB5JSHa^q4(H_0v?&p(o506B!>W0kuwhgjh+k#s;hgssArJELt
zU=Y3D(&E4qo@wC^_Db4NcF7K@M!UvwwyCB1TlXE8{!=Gp%yPqm%^g0<0X}qN0Yzz0
z0(j+ZY|u8Eq{9>CRNXt~o#Al=RD6L(Hk*3hOp^=p-fJsR1~z`3<)*Wc;yMh(UFsV*
z>Id>eN3oen_SS+(afO~tKRE~mje*B;!D=VjO2?&j^xj={7TWqRs8x*Fh_x1XjPPqn
zVyQd7R2E^M=p*D3q!2_bOe)$@%F}M@kT?xIsiwvM^j0YdzEi)*=SAJ(-{VVKPiL$4
zO1<B<i=a~vACb?nIo+C3|K3vI`C^mD2Cv-f9B5V3j*N*QuRxe8UP$Op8sRrd1NU4s
zqM1j%KJ?$`+|{uBNB3=kAsu{j-|$w4?+!QxU*lm1AOHXjJcv&fu}OW(EX0mj<!m<p
z<kw9j>q-K=ATSiFs-0g(=V%?X!$SMk@ypCSjbN2{&bnC~onuKTPIEZRg;76;;>_`O
z=^CzRwFZ!{bLHo?_)Xw56v_N4;HUt4zb>#)Feb2id-D(Xx6F|kC`d#iR{7gbN2PM=
zB}Ic2-u3tVd29Ihx!njmnAxh?aSb?KFG&@cmNycCN|`}=OyaW_j_U>y=&xWJ1uUE#
zu#C|l!|0;cEYbv@U%etD*e-z`@04X+r{23*4EX2%pc(P7bCQpyisJpPlA5r>T$5J*
z?BSUW6@OLU;af|JnKQlSt9!am+9WOYND-|^nBV@Twvkq1AJDVrb2Y1L{^w*@kuZ6N
z-3Z|`fjZKv3{T&NK~)sWh}Thfo~pOTMh%;?3`{uyk&&ty!H*GjZ|Bx-{Pw&sXMX6h
z5K%-5ZK^y?vW8j7CdtSZ4eWx-ZG3O_KB_8}!(1vuh@spwZ4oGn+|oV(3nG6N{eNR7
z$<K9Z-)TpbFm@7cd%shAgDlL|$Y8>JsL`m~ZUF*hR5O-(x!WKOY{ysN#+N2<QjgB4
zFWNJg;94)?sK~bH)$$~*1u2-(E7$H8Ymmk}H&hA#{~*ZzoR*S#V7Kpa){u#GWUr*o
zn#pD^`Zd5gTPFEdM}gZ6w*M8o6Fb!M)pfV0_|PzDCBmpZ*sq=Vm_V%#yfcfB>wN@M
zsK0O5S=BSn$K2#xcEKefZGB~)1zlB%3i|nutSw<<!i07=ZL{#508|xqvP~9AmVe~8
z4E*;J%4Sp`7KdHcySIZYEfN&zP%V85V91PND7BY6&ic@(E}K7XynYM@ZnwIKDe~X~
zKYhW`i+k~T6o$@YGKej6LmTxz&M`nrCIDr>VhDO!d)h63@OM%A5~mUa9As~DK!C`-
z3fB|q&U{RN0*onG07o9CL(NC7qTj>cPqU=DS^hp(K5jbY#PJh38-&P%X!UB1zj-)d
zgiU9>_<Fc4Rjby#pGhW2C(xvg9EQm}^}sN+72zwd@1gS^DdDrVF+=i!>pKsPRlymx
zy`Gd8?(x(4BS1IwJQ$dq>G5+Fe!1yWajIh1iW+G6@|_dTuD?L5k)9KIx5CT=ABzGv
z0{tB;<bA`5|NK;ecP-l{jIxiI<=*q1IhxJ6_1>z*WAjHUTZsD&EmY#3F4;%i?Rvcl
z`e#`VGht0qxx@;fmIp&LTPcTE+A*U#5q;qH1kvxeVKi8-Ju~2w+lC%|VX*sxhm@iy
z9SW-u^GG}PZNc}p+Kwb(j7@~7AE{3Zp)#acdM#NG&59$8ewG~VWa=PBEZrQJn^D*2
z;1-V6t0t#z(!3w_-4$<lMC`bPsu^1x_3`!@eT~`oel{4lkaxkUyP1*<emy=Z<h#=o
zNYY|lH8QPwL>wW5!1O1>uFTtH#<}c)nw&Q7yeJo_26P{b#L8d<-e26gv@~UeL=w|L
zSZ+|hgxEv>5z@hs{zpZ~nyg!+S9hLP4$)#qxl@FV-ZPP+Ja1xZE-ZJRnst4GNw#kc
zl~-u~L-y=8(AkBUtnIQRwB`l(0k&};$z>A1`MMw?hw1G1k?^z_9R-GMdMV|(0yH{K
z)u}TbDX@T)6U;gAZK^-%WUDi@y+Yz?^~)-xjY~5FNj68<OHZwdO}D$zVdq3Pjk{F=
z)lFQ!crQ^u`_HnV3^(LTPGJAf#+F4Y<#pnff3<@Egk8~nXO9$luLPi^koY#)74ETq
z6k`~n^*ka#rHpz^tJ$VoI-GMY+IRlym-D5n*)o23sS-m-UKBHtozOl8O$b~T$fEH)
zWL+@c&(NZzdh{ZbMWw6Ey&v;0C)J%sO<#Bbk~lBGUM%1Ae<Fa^ij63Tm~Lyvj|7E}
z&FaY$2X7?L4utY0aOfvkN_IGgCl;La&lqxH1KJ7dA(<3#&XSV`*VUYFB1<JA@PoqU
zF8nlxY9+>Qclz(e;|(RLo250i77>0@>Gz~5xZLXrqXMzSX;s)Q5cPJ;rU78=YPrZp
z?xq*qQf@ICX1vCh-wRC0)-yA@G$*8G^d&<{moi>fmNRnS9BXW)y<NyzkZ{YrNx2&Y
zo*lk8-rT(agGXYxRcAOHKS%2Fd8{h1qV4WFuuSk;VYOtqNu0DUQ6w&Lx?(JEE30ld
zPv-X|Lp7A8dtYy$s45t&WxRFAL0p4X+c=+PJvlSA*q=#gnt8GiJLbr3rNiX7iq%PH
zFeAhtjjg;;gab${wNvx>Rdvz=bAnsfgmXB8Kcj2AHtHOta=f&JU)_FHw!n~deZ2LY
z-d-1ucW53n*1K);e^tJwe$6cO?p(*!B^u?y6S{cF!=K-jZew$5u$Ihp48RQYT~YVn
z2ln}OhLVzHw)+8re31Xj7l2d$HMfw`Ll$6R(_)9d5sStVc>?Y&2AcVH5+5QiE+~U}
z8YiWN>QVD3sGRxDKtg~|aJVWOmelB9rkZY$L*pS@Z~dU}0M3&5W1RHErD2jyI5gl@
z+P(|i(SZbPv+QN~TE>!r=1!!1haf~%xte|C*<v_myeBs1m{9Y9GYGH^;`giv7wyxr
zF{(AA!w(|S(Xq)#n_ut{M+3$suTUX}NB}v(-T5}u@p)shyhojnp@J>{IzWW~;Y@FU
zwd|q`TWm4f0r6<ay^A>*LCxkI$>D1ZX*}C1@Y&jB39zrO;Soa7eFI8Gk9Bu9btGt*
zq-Iq5w0_EK9yYt)JEMSn(6;ds^DCY-E=)f_j1tq_DTyiI8&kNh3&TW-z&B?IrhX%w
zrf4y1I`8q5V*>P02*G_7PWLoXsb-X(Pn{=luaK>gy>mBHPB~mD^Z5gMCn5<&+@L0U
zl+L8$w}>O6C_4q5`IJ}7v%_fg(TV8(y-Iz|LR*Go#STVr`oZz`kvC6~JPjLbEm;ik
z-qrSI#>^dpr>1~t0yP5W$uCJvI&8;gG40M!KR``5aKW7!YAa-@Mfz1ZJUpjt^l!#>
z@Ywtv`?)3`VTwwZnlE}{|AIYm7)iO5h4<g#Gb7u^P-at`cpU+kc=*Pdwi+5qbnswq
zR6+5Wd#bcAEE#N;Xx4v7h?>ckcq#=sCO=6IVd-yDg4|hiL2RfLJu7zxE9~{0^i9wh
zVvIS7I8-lLC?bhWd?<tblw<uI<%w{u4m4bSY6g2Sl+6B3TH8_wx@jF8q<#UA$fZ~U
zo`O2=;fH@fVad;}nd&tA(3Nx>Fh=1@`4F`_dcL6_u;$K*W)&lRDQ3zGoT>H8p@>+p
zda@|GAZ|$GvisIqjeS`DV#3Y9legm#%W+oqLBCcT_bBsg+*oW+BdRNu@QCgn`yZ++
zH~`lrdEq+of}OkxIr|KR7BuaW<*t%ZoyYef%4#k&3e^v$C$?E-9M>)3v`PTe2k{9v
z(M^Ee3d>b*qbk)wL}O~K<6`N+3#j+ND4Ad`zvwyDv8~%LwGYZg7L33~M6)6nU)+9Y
z%J^F4aLD~CEOHc9(`*OXJXi73JiFF;boZ!wZRxvvGSq_^2ma&zE2T?>F$mu5zyw)Z
z85Pl+OdBESyDOcc^^kuTC{|<>U+2nK6nVf{NIYPbyizhrho}v@?pWbp+EaX{&M`r|
zu|f_zD8Ia~NEqTrMEJQm{}oST7cEIkMP&knD2lL~rM1dIEGMLQ9s8RU^{TvS+|q_m
z9||Q(>w-#I@tmh@wYM2|&?-m#f?ii4)OfVX?f3I5y&VtE4G7j*w#M2VnD*=I?Ur6g
z{Sg67x$H@~q(vMyU*Q>_Vt>ix6J|kp$+KDldQ;uRAEtA_8u9p3u32Iyl~ApF=vcjM
zz><xEd{N=jS%2fEU*ypV&<9e0HJUv){1PP-f7Y9le)|`^-K*0fj*1+?Z|3cSo*Rb;
zW<R|RM<5ErUGzO;@A>a&+7p|M_`$l?Qi|CbXeM7Rywn~ezg{~BBVd5vgaj0=-Amg-
zDzboRxTE{}(^udh)oTBr4x_epkj|X8&|+1m{m&yhW2cS$Zb;t>B>xWoIW@yLT(~pt
z?7$q&m&^=3im}0W`T%T7rbdJR|4d0i#OrP8HKLhd0KV1{Sp)Dg5qCo@ayF$sG|*dE
zD|6)^Ud09<f6-mMQJcmrKZItehw$<7CHnrf6mVeH{{KVwf4L16fl#>b&y02W>V8^b
z)?lhs0Ee?oLRh+huwqH<vy&{V6-S`J4wQ|*dA4vCT<=y1*R^il^>n|kT1qIQPFC$r
zGu1ahatLG{eWhzm=A{|^X+B51Gv*i?MLhmTQ8;85qw4i@X&Fc@gj*VW-27h6%{b=?
z`qPL)o#tkuXC+@{$%U_aA_g|^5d$s3<1mQ+tRjfuMw{0g)Q7tX+zr1rOdyMPm<Jln
zf|@&1!H&mOj5$<six>Q~C)c*#+~kcqkJ|_f2r64lOmtqz>JZ>Fp6d9Yn2tQ~b<=tN
zG;uBTKYrTt@*~t5nw1oQ0eL>R?58^t{-`vzQu~%>WKJT%P-l7wdgPbN`>cgAlgnTy
zI&t_kh1alFasMq6-UD|NO=gnE3$kiXjcOMGyqWKnd~xG-FK&?Gb;yulh%}6qi@&Rc
zQ}&0OBJ2DJuSz;X=hXsBCTTZ0qPhaBD%Ln&L=6FRk>(QV9+JLv`+pmcgzhvxN$yO1
zu>_MFG9dxVoiiuY@boF4{5DTgKQjxy^VF|sp2sK(5+pqoxDhl9{{C=_%L=0N9ZH`y
zJCY(Ox5&nA)xe;ZEekDC#W7l(-9Jrjue>ERY>~A_fI<v)the!+{3pB5&Z04(MreWI
z-AnnG{`9xQUsm8gt}b8XQ(z@2h%O|?D1Z7DLkNm$Nhr~}GTTTo{KdbvxTS4@+m}WA
zJ^oSUt>+4qaBeYF)w$?pjrB3qJI4?!zk4&;H4I&nqY3uqjSuwc%4Y)Bljb;VO0yvo
z+sk)-Td|VK(8O?78b_J4xU%ixK(G8f3rIj=HqzKq_LZ;m8erDq$}OusLNosCcuf?g
zu8-;Rq#>ya6JmsMoOIr8;U~yN)b1xlAW*3qGMr+-#6vzVR;%vMaWYjg=0^Q6u(mtx
zVKR@-%%P4rN(|+eDhYVds>&u*=APw;K)cub-1zMA?5^Q)lNuhT{5*H^;Uh|Il93@Z
zy2x-172tK~-A0{=JRLDm1mES?S0o~jwBW>e%Lk=<!<SpJ)FF6c4rbbZDJykYW|J;5
zaL^_t>i%NxUN5pIFvj;L@m(5V2Dm<h)px!58L~^|AbqSGn<k1cQ0crFg@(S28_8Gw
z0s033x~Pf-6p`F)8E0K7Q1Xb98q1~bA#4T;1*t!vbm%<rA8dPp_Qe6NNikbJ|34Om
zk~Tp#+1U=fL}KTN|EyDB-Z$aaxsn;f?kt#t)~A4(Z@t4dzxN#VH7UNjnC*z-b;5VA
z;4dYYHLsNLDjcoI1KEd7i=xZP*?B&NaIHa+>ouFzJkxo!4rj=^=HGJJ6MVh2s`0*(
z=JXGbohpn@P^%Pv=gs8P3$G<LKc*fGtCmx-VcD_wqcooO#fXfb?q?LLK+BWTp=CE5
zY7@-*kbn$)e|3)w%kfYE&J&RLW4-WI%tD61?kmDoS$88EW%x@|VlS<H!kVf}{3_;B
z=I%Nmb|FD$Zm5^opUwL?71}gRL7%A2G>2urP;Jy9g=wVRG-TS5FYxQ)2{*J3EM<8o
zsfP=LcGK4p<kaTYc!18&o_m41^IHEEJC)syF_sGz49C6w$3LM3gYvzyzz3Mk3G?H~
z_f8XHW7uPyxbXUZ{5VDhY7+@mtEGtj`vB)oaus(+xVgj(lT#Tf#&Wyp{u}y<X`&7O
zjW@J_XO!rac;@fE08SS{D>D{21#vbGxGbf$C!bK}uo+`%`n{JOtAMGWTdI@DY(Tzr
zKy5dIBpm%`VO|*|iKAC)lX1U^*m2vo`L>DBKPmFw=qG6Nc7$G{v8{8J`K*fg_ZW+C
zP_LVQi@e!!MLi_GcIePamxHH-h}bGuGXzbC|4F-<K7(r(FfcM0Jc8rd%(YIPR03DA
z$?3zgMxN;dUPc=ik*q?H43Oj%qpA@VsLrX|!alwvG`L&`Nrw*i4}rzoA?TgwV=Q>$
zvA~@ac1q#ffz?q`pKSlOaY^C}k_4v5>ZOxf?{1GMayW)>2)Z%}!9m15N<LdBL-g+?
z^PrYu`}QAW`l+FK3FCgf*fm^Igiuklc#Hdt5Fi7EM#|JtVUM^ZLR$VdDb|yeFI!d3
z9t)VOP1s}-NI4VeKM4EHON5jh1jKKXP0O-2Bl;?@vej!$0n*M-Xn=XPiF7CgEnv?6
z{~&YhgT1E(7!1JQDXHYoE!-h9yDQO6q{J$;!CN~InyL*EzsVAkw(LSEIAm$*r=h1=
zZ;F2EGb9VEJIzm+1-@Iu0uy4qR{(06A$l*qDUx;MGeX&=pa#&X;?SdL3ixrBzvj!f
z)2kJUJc2%EnsX`XG{M^h1HSRetMkry#-%KhZBBpZDg(s1$GapX4}J-atLE=>9}5Kq
z87@<huEKq*S~koN&`a{i)2H;mkJS~(D*exB^Zh#EGa_{XO6{AZFSDx%x<{;UFdog@
zx0E)UB?1Zf<^wo;ry%t$RzS^8G(Tar^-}6I8<<erhWim!_@6lMK9;ei<MSz5Q^|C^
z_|z7qYXEn9>(wao3DQ4i#aa_H1vCtw6EV=MkKAc5vSbu(MwwJ)UqslXb+O?=66#@k
zDy^Ub4$N=eS`jWp1k_Y{bUhYl3JO%ah?__v*46a`pU;T=YkiY;{%N>Mt;UuZcyWlE
zsx~6GXNYLAVvJ;(*!pL=$-gb2tZyL^4}Nh)L!-J~h?T8(I25?sIb!nA?qssftb!lt
zx?duO6VN93rju=g!(a`r0|fleBvM$JW)>c3pMXR@6a!J9br@Ulm98SlqIMA-3Z-9$
zhNQ|KE?JXT+8FrPRY(bds5bdtDgJV_4I<r@cwXmlcQ7ql!Zy6(URp)ui}yEsREiX+
zR?fUnN1t!E3@3rx$>vC4bPP*gB-r!1VZ5*|>HwMJ^*1-&j5S~`))|hi{OYbw#`sBv
zBzgvVGi%Z`KD9tBvqNLNZA55gjwUw%w4lW-xsNTV-PksM#QmJz5W?C%=)i!_ckvbi
z6c`4S=-`RoQ+Er=-gfD)rIN)H7F{4fA7X&(7Fd=D)Npe%ec=PS3rGSKyP~DktfF5V
zg=4r_XV>fh_HK!cT&)v$98vFr<GHBfOWi&Ui%o(P4g=HlbmBOSM=C~WUeg8hiGMM&
z)b@aRI#~!^tk5)#LzkVHP)=FeUPo0-bVon=`oXHs9Cic|yH!2nwic)ctH%3DBAm@j
zUdnomj&CyL(N$O^Sz7=g+U*S>b4*a0(79o%hN<8=8vFJ`{@AqoF@x1^Ryn5Uy?Wub
z`iFz5V>*m96d94C0cIL!-Ez;tKK?s65YhLFcsgE~LI#EM76s!q5^IU@Y7f{pTO~Gq
z>P<kagO^Z{G0=Tf9AOkqp12F>Xf=%(*$@J!1$qHaPof4eLl_r~n_aA~?@3UUrp8WV
zWDoVu#YZVU`Eu|$b(<8y1tNFoqpN>_wjpBEya4^3g5K_u-ETVqI&2}&IFTVS_&Q7M
zup1Yz6L>klKQdNW*~s5qkj%2(_q&XO&%*;hzm#h5EE7!^Xiw#5PnkJ&dj9Te9&_x|
z=+1AW*^|Y8k}v4#aK`h=bo&Y!lK|2lFIz&j8b!@MWSS|j&~|6i3OWDollFa<=4K+d
z)-jMqJBAd=(1aYJep0VXTeIV%DclsId2VM&LMebtFWHJ_*5iDuvG8%+fsSdG@2mq-
zhX#C8YHP5%_tq}cT581!`=pfV6XDX#Jy};zJ37<Ul6gZ)VFSG=kA`xsC;?mSo&$+l
z3i{9kZ$QYGNGk74e&X%4!#p0-NlHwUe9@!BRk#{Bz4U)Zk2W=f?FJN0<(4HV7$j2=
zh5TcTD^$Xic@C^wl9S%M@XDpu!WHan1U$72+5n&s(vmAamXwdE;RWecpR=!MJfrqJ
z%R4gUPp?kM>Uls+7s^|lLe)TN9w)=_KkV}1!2%TMhhY>kx^Qo#_<K*-f^P7XsIEmc
zcV+08m~wl`)k|I3CuXin0#M1}*5jT^KOx$!a%~k`ODpAphr7Ltw7)eno0F}2?H*1R
zD>KrGl|sxlUAY?iWLmp7ldhb+Fi_1KRTuu`TF}N?(Ayyf`kj&SffthTLE!G$w`R<A
zA4dkn(%d<=o%WOM$p``e3hJlJXw&LE(Dr`q<(t>JV1WEk{8U{ZaRMA1A>?MfV~h7}
zfUAzv@$r7@*XeWZ0g~d(jvYNx>ceW1YtZc^6oMtoCQ|ZO@{q*z*wV$*h42MFwa-KL
zh?vAUWq70yqQL?-;k4`amH#_~_tHwD!_bU=NIVsN31;2VP&bSdOLRzRSurV^sf1(G
zJXJf(=Z3!^APT-~aOB(#bR1N@eOlA2kS#%y!~{xq5F=%;tx*r)k$$K~hiE~R)r#z-
zh}`fVDmV{EI^Ty@Qjh0GN6hvbVoGP2<VjricMhT(|Nomx5K2gLC$<HMcVJfEd?%{4
z*Z&IYAefw>zU91_%-eU^b3D<%+!&K8<oJrj3R*pV_!E-<8gSsnF&Ax90TskMJz~;e
zh{<rJ?{CO-=eJV3u`-r89K8V~a&c6<Pmwl3{)eM=s!iav`W(>IWCeF2!ri7xVq;wW
z0&piGTzc?p3yer6%ber5_9R|hp1d`MH0OXm6zmF%E~Sj%B(<!J)sIX<MNA6Lr7K~P
zoOSwfi-lhF$Vh8x7Cp1PW2SE-^G(sp5q)L@s(jdDgW?iLKyFc~;$udiLT1VtToyVt
z+1lkF-Wtp$?9L6nFko=`(&+V=l-@yQ6@tg^%Yp<?yrB58%+VzBR4epL!^yqOD(ur?
zL%c~c-{n#~{tJ!Q@@`+<L*xnt52SW+G!@l8non5jl3k>BJ)xJJDP%YayXlB~{KLZ}
zIt-2WJJ~QR_~Leg>M|*ofD)+`+WmXjQXhg{3Ehc(3$q>b^2|-xHPR;g$<AF{lBUec
zg11?!<a<cDG+!<UE%M|wi?@M@6zG*122x`J8?+5yVxt`EpIJF+mr&)KM7NI?Otr+3
z;N^#5imckjhUJSTd&0~wcog%|4Fi$h1%NQcm7i5_V%)<u918_aV)tuyfD90gtKFjC
zz=uXwJ`qKVYJ~P*_TDPbC|Kd@2C}?}-~<8!;=^VC8vg4?3+N7JTJg&(o;jr8uKt>a
zT$&xJu+_6f6H4W{son${<F{(?6Pb^;5Uuu;pRUKPg7gAX-PD|2N&=mVKOahpPa%li
zr%knX#nCgD^Cd<d5M?QHI+2LAaBQAgJS!|WcSPUXt}DzQi7mGhT$TbbbKdkABxvLf
zS*PYo$5P|g+W@tWAL*gFMwqC*NvO1uSweFpzod7gm<8rE3B7abtF<39Fvo#j^B4x3
z{Sps4u4oT}rxOV41j+l!^Y9KnF&WBuN)GU)>I`Jul$+=na8z6%cPP*3sQ{B({q2Uq
z_(B(X;IS0GOLi}0W|8UW$V$rJo{Kn@6f`+g2UORhCIZ1%CPXk9)KC#DFnh}ILW5x1
zt8`H{5ua16rE`$efbOc)JX$Q%L<Sh^r21+KC)b?w8td%V2uZ!Pdo$U-C0v5vg%yj1
zZi%y1)+O6lZbhari`(hli)(bVCJ%VkoF>ahsA@*;Ml%{3k-G<*<YZzB|NT1}boLHP
zGgvModIT!wB}8Ghs7`d*lOP<i84t5xC}w1)>dvB%u65Q(RT}0mX;;I+i0C<o$+_UL
zFd!yul?Q|w-P9PVL?=<~8&UtL@^DEy0|(_LBt?dM@d$B!l!)wbUx@nS+nqgE%<KN0
zl>{FItFw!%&fb<odh(<wuPp$kcX~48mh~Z7;;MR9J0?r14B0fcO)Ts0A^cVotp^Na
z^*323uY)z1!s-VxejYdy!Gol;0+|NK^)AezK&qPLRM=K^!-oX|=r9x2wMWE$>1p%Q
zDj@UzRB~y&Gr7{st)Ku*Pb?<G*+;FN5U^Me<apQ+W(`%b;G=U!7*y8XLf``g_F-D)
zdQ?|0-vBupK;?Yy{yH3uH(j)rU*V_u!3dY+m@iAgC{>Wid`7P%J1x1jUCrCjb7~lK
z)xeE7R+krgerfP-$7Jv)AaX(QjzW2HQD8%wpnoax7#W!~q<-3SNxNancq}&n#w)^C
zm=leGh&3KUh&MV@Icp5HxQDCD@ll=6Cy^A<H;cYPq<%kX4_Sn`(L60mE4a2sBShB1
z96IHobPnqW^658%E7=su`2N{E;8fE||3z@ph4nm<o<<fAX)9G}2H)*=Xby}t$e_50
zQQ^h#c0<YTbU60-b3}Z#4i{z>ZN^LhND9qZj;r!THp}14Vy}NCv$VGtWWq$Mp|ZT@
QpM_5wk7l)q000000FI(=XaE2J

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/nvidia.svg b/studio/frontend/public/hub/profile/logo/nvidia.svg
new file mode 100644
index 0000000000..ae65b09a2b
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/nvidia.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 271.7 179.7" xmlns="http://www.w3.org/2000/svg" width="2500" height="1653"><path d="M101.3 53.6V37.4c1.6-.1 3.2-.2 4.8-.2 44.4-1.4 73.5 38.2 73.5 38.2S148.2 119 114.5 119c-4.5 0-8.9-.7-13.1-2.1V67.7c17.3 2.1 20.8 9.7 31.1 27l23.1-19.4s-16.9-22.1-45.3-22.1c-3-.1-6 .1-9 .4m0-53.6v24.2l4.8-.3c61.7-2.1 102 50.6 102 50.6s-46.2 56.2-94.3 56.2c-4.2 0-8.3-.4-12.4-1.1v15c3.4.4 6.9.7 10.3.7 44.8 0 77.2-22.9 108.6-49.9 5.2 4.2 26.5 14.3 30.9 18.7-29.8 25-99.3 45.1-138.7 45.1-3.8 0-7.4-.2-11-.6v21.1h170.2V0H101.3zm0 116.9v12.8c-41.4-7.4-52.9-50.5-52.9-50.5s19.9-22 52.9-25.6v14h-.1c-17.3-2.1-30.9 14.1-30.9 14.1s7.7 27.3 31 35.2M27.8 77.4s24.5-36.2 73.6-40V24.2C47 28.6 0 74.6 0 74.6s26.6 77 101.3 84v-14c-54.8-6.8-73.5-67.2-73.5-67.2z" fill="#76b900"/></svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/openai.svg b/studio/frontend/public/hub/profile/logo/openai.svg
new file mode 100644
index 0000000000..74d9b1b44b
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/openai.svg
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 158.7128 157.296">
+  <!-- Generator: Adobe Illustrator 29.2.1, SVG Export Plug-In . SVG Version: 2.1.0 Build 116)  -->
+  <path d="M60.8734,57.2556v-14.9432c0-1.2586.4722-2.2029,1.5728-2.8314l30.0443-17.3023c4.0899-2.3593,8.9662-3.4599,13.9988-3.4599,18.8759,0,30.8307,14.6289,30.8307,30.2006,0,1.1007,0,2.3593-.158,3.6178l-31.1446-18.2467c-1.8872-1.1006-3.7754-1.1006-5.6629,0l-39.4812,22.9651ZM131.0276,115.4561v-35.7074c0-2.2028-.9446-3.7756-2.8318-4.8763l-39.481-22.9651,12.8982-7.3934c1.1007-.6285,2.0453-.6285,3.1458,0l30.0441,17.3024c8.6523,5.0341,14.4708,15.7296,14.4708,26.1107,0,11.9539-7.0769,22.965-18.2461,27.527v.0021ZM51.593,83.9964l-12.8982-7.5497c-1.1007-.6285-1.5728-1.5728-1.5728-2.8314v-34.6048c0-16.8303,12.8982-29.5722,30.3585-29.5722,6.607,0,12.7403,2.2029,17.9324,6.1349l-30.987,17.9324c-1.8871,1.1007-2.8314,2.6735-2.8314,4.8764v45.6159l-.0014-.0015ZM79.3562,100.0403l-18.4829-10.3811v-22.0209l18.4829-10.3811,18.4812,10.3811v22.0209l-18.4812,10.3811ZM91.2319,147.8591c-6.607,0-12.7403-2.2031-17.9324-6.1344l30.9866-17.9333c1.8872-1.1005,2.8318-2.6728,2.8318-4.8759v-45.616l13.0564,7.5498c1.1005.6285,1.5723,1.5728,1.5723,2.8314v34.6051c0,16.8297-13.0564,29.5723-30.5147,29.5723v.001ZM53.9522,112.7822l-30.0443-17.3024c-8.652-5.0343-14.471-15.7296-14.471-26.1107,0-12.1119,7.2356-22.9652,18.403-27.5272v35.8634c0,2.2028.9443,3.7756,2.8314,4.8763l39.3248,22.8068-12.8982,7.3938c-1.1007.6287-2.045.6287-3.1456,0ZM52.2229,138.5791c-17.7745,0-30.8306-13.3713-30.8306-29.8871,0-1.2585.1578-2.5169.3143-3.7754l30.987,17.9323c1.8871,1.1005,3.7757,1.1005,5.6628,0l39.4811-22.807v14.9435c0,1.2585-.4721,2.2021-1.5728,2.8308l-30.0443,17.3025c-4.0898,2.359-8.9662,3.4605-13.9989,3.4605h.0014ZM91.2319,157.296c19.0327,0,34.9188-13.5272,38.5383-31.4594,17.6164-4.562,28.9425-21.0779,28.9425-37.908,0-11.0112-4.719-21.7066-13.2133-29.4143.7867-3.3035,1.2595-6.607,1.2595-9.909,0-22.4929-18.2471-39.3247-39.3251-39.3247-4.2461,0-8.3363.6285-12.4262,2.045-7.0792-6.9213-16.8318-11.3254-27.5271-11.3254-19.0331,0-34.9191,13.5268-38.5384,31.4591C11.3255,36.0212,0,52.5373,0,69.3675c0,11.0112,4.7184,21.7065,13.2125,29.4142-.7865,3.3035-1.2586,6.6067-1.2586,9.9092,0,22.4923,18.2466,39.3241,39.3248,39.3241,4.2462,0,8.3362-.6277,12.426-2.0441,7.0776,6.921,16.8302,11.3251,27.5271,11.3251Z"/>
+</svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/qwen.png b/studio/frontend/public/hub/profile/logo/qwen.png
new file mode 100644
index 0000000000000000000000000000000000000000..67d2258f407d7b06323959c35f7c42a50c641136
GIT binary patch
literal 117172
zcmV)FK)=6INk&Gj$pHXYMM6+kP&iDV$pHW_N`uf48HjBgNs>^y|D^mA?w;Da3?lkJ
z0rRL;@B59Ff1*;w`i45T-FRL3q=lW{I<%}b&6|1P%=hn+S#uhwIP=}<d8ikep;9Z;
zOyFSfRUT!AUAkak<wj;!IK%rB6FtcccNG}#DCor#2F-2Y!&fLg6>m4OlvaSH)`#Mm
z^$On06YyF-w!yLjj&@7`XY7yqkI8AXfgIbmX=}XqzPXye`SOqI+qQL3Cj_^#ZL7-q
z%EiAGa6>}+FNw%qMs6fYjwJcvqu%N<PAmOoc`#%>ZV~$NQfvL605lI*-dDkEkYp`5
zVJtC30$Up5?0pj`BO8FufVBe<fM7>K0uTV1o^uF59yb98bbZThhYbOUH?3O;FK7^k
zcP5zYXsiH1lD6crd;!4q3_ywKiUI`);2u>9(?0;$5CAsO1vCKAXc7RoHO^54fUb40
zyMtb$4S?wzi-Qn=h!C_{0C`>k@ZI9TZJY=I3t+KW#l}5^0f;96r)2>k1ZCieek6cU
zq5wirXBAv>#AX;K5Q5w6-JRR)-F;QW^<w}y698b?3<Kf_gaCv9z+qs4LCIz@E6*VS
z2q8d4Tnk{>1?T_(gn;k@AOLV1z%aZjD24z!gwt(z&jOoO0T_nSg08vc0m=x&+`_ue
zjskF~zyXE<KvAR;Vlyn(%Ck}40uWThtAf*9hrkBgQ=tYB8n{&;yaMoD0>>+8OCaid
zK!>8f7q3t<8_z-S;R<*H{s063zE{^28$&q*h|ORuUjabwK>%1_k7Ba{tk9tz28|?z
znLF@rx(`J{L`*;~k@sFF7V@@j%$xL5$myF~#Qgwk?|LBZXa5L7==zf{J4x1hLz31x
zr}IVJAn26Al#ryINKVk!kT%y)T9ia^kyZ)fa!_=1nM3VWPWd9}p8WmTYtbK(w)S4F
zLN1MahYr`BQ}sG2<ni!0fBjDXuUeOEIb+Os=Yei9Gcz+YOSc&hgk&*U%q&|jGcz+Y
zGfNgXb04bO?;OS&W6rhKyVl<Cd99CF<+e+fm{}^ZQtjPzm-r2Nnlh>3b(_gVt0K-d
z%dP92h#~W)r@ZD6>!y3nUxOtEOVN;RN|qwsS>o+3H{0ud%vWIY7BfqB-Du|S6Y_F9
zH?$*UEvqBWHD^R)M##qOILB;Hp)^%)nVs%?EXB4u?r}@3?VdkC*kFk<k65pn?%ZyP
zR~#>|DTWbILYFzkl3QtJiH}>;O>xR>G({=&7)q?up0-=p+#%~Ot3$hFG29ZX$r5Xe
znVH^@ypoyXpQq^MZr8W9ZO1m*wsoG@^F>r!ZOyjb+LCRoX8tuI(QLQ2G28&#wr$(3
zWoBf&*M(b>ZB>#a*<R<|>kybx*@->O%sg-NHXqK+%*Evy;Nfxo`t@_xwt#Kh@}}8I
zDGb+NaCexyySpQkOmKVW*s*-Ur%9&mtPOJwfw}U{y=1>@$lS{}mzGX|H~9b8?RG5X
z_xt~^>%Nz5OR^)Kw7Yw{le9}Zo$e%^WXHQtpO)i>yB-^#X_?b*vDSFfX^H!8No&%U
zPNzH8v8~JQ`@XLK@Au%o?(1IJ`~I)BYCU>G=E;6UaSTb-xX+|&g6H5HhmEuFyBfc6
z9l3GH_~5R)3WwmNkyQPWkq(|N9$h#robmb2Ob-&AuFBMuEu0L#a4wu1=N_LOe0LT0
z$K4iAH}dR^&-9V%Avi(1`bN5H;oJ}D;5Y8hk>Z}&jf_i*@i_};KY|X<nhJK|y>R+G
zV)pplxE-l#+{S0t`1Hm%&b6^Ff-laqg}Yu=qdmCvK|(E@@zmM)jgtqX7fx4Y9t7uP
zaED{q!b4SXa*#vi$w;4?vV~{i?D3i43uohQ>(JxV{fv{5uDJ#tv9T1X8vEjK<1Flf
z_JOxe+mfW;7<27??u(aMwryK&+y2xU8BvU={zv+gZQHhO+ui95WW4w8*=r2`+O{c@
zBguR0GjnqYj*N^1rKA#6RabR&LGv)rzsqz8dj`x$um`~SV`hfJDOO3P5>qNAB}N8#
zI2c&KwtxN7>PDyFF~I`lkF6~2TH4*+;!M)NT^sx`G5J%r0-J7fR=V!Vsdaacbq`Lh
zaRNBO|F_(dBj<VF_nZq!rK%D)mee5Dh(_3qqV6em30pM6W{rlKnMcqhhEl0ZrLJlc
zL#w+Q#7x~%m$208!pyvU&ig!zbMDQmd(V4sEx(SzGBaH>vt8j8GrPjOT%OI)S()jW
znVB&MmbEl1;x#mBXZ7+myUWb*m~Cx4qRdV+Q<{CuPP5Opv@El)_Z^gm!KIn2Hys|z
zg|<qABCgrT?BSU=VpdvDOl@w2+H9|wYdbt@FVpNaOJ=4tGcz;iBF(Pr-8K7^*~4?q
z&JOQ7T+#4G48zu_h+LVuR(5*HbiBf@h1u?bm6@5Hj$q~r?`TzHtcvie+DuKeqOIA!
z16wn@BW`$EX3P8-%5cq2vpw+tZQ5@Af3Gp-!ruEZPHp#7yS=EHrvCKWHb1uQPuq(c
zu~{RyO`2QVZJg#N2OA4>49wQHCz2%T)h`)321f=%VOA#>HgnI8w{r<|L$hXPE@sH$
zWX_-jj|dM(GdD9yF#&q^|64BEQttbH)>>87)!n<dowJX-yPxr+<L>V6lfla%@>k%H
zjk_H8?fbazv!$(Ut@YghpnIP)vMc}L6z(?i4sh)W8;M+2#PwV_H}3M_P{<q5XhJmX
zgFj@P!WYhsLxnipNaQYA4-R3c3ug^krG2tl6F#`xxaGL?#@*5?ywbwm9-NVkYofy8
z4NN$lcGx@ZgRihhqC>dmBB~ULCdGAcoX%*Rs&t17r#GR?O6MYSXOnReah)CRw6Do_
z;cUFpA#@pwa8D=gbowIN2VZIJ5QoY}(i7rNx-X)hv~W)N5YCf!>RXZ|OOhnpVq#G>
zbC0OYYybcM-8(ZP+|5MTq9n<RBuVZbkuS5Vc^Gb)j+q%g{C<F$?-phjnxP;o^Sy|e
z0Im7|>5^nQ5vNw~?{7%{dnOa!U+M(N%<7kEJ^Lj4LbVOol3v(UMGp)dE(E?V$cmx0
z@K6=Zg@KO?;mODa(Oh_F(V|I@3o1`qE?im#i#8poplyZxXxea#=7k5&(o55mbzz4V
z9GXQN9@=X|db4yd6fJs_4ooT=+6GxM^j<h(3fc_?RaA0etr)nXMK27hpiL#VjU-8u
z6t(yGZ|`=>w<JlHBuTbK#9|5c|9@I<eMwj5m;eJ&%x!%epK*VoufGTc(ii{sI3fcV
z!4mPe$6((U@NK;toA7M`?}lRXZGpw!4c36)20)>_8?RN~4Gmx|-fah<C};o|1FU#A
z-a>mfYyhjh8*h;gzac~c23|ApJoA>nolpLFP43toW+lB0Bq${hhKEa(N&_gsyMcFu
zU3fQMLwYxKfDr*Z0XnK00&vKrjS0V*Y}f=~9o7*r9>7((NY9y=k2;b(of&oL-#f3^
zJNSfupJ>|KAI)$~eob0<_h=~)78nGc$bkVClu89Gz<(Y88h;yb1gfrq#Hd*SobWsj
ztOH%(@xY-Q%Hc$YhkcbYUZPscPG~S`nobkO59-)9y?uvf*5y6}C+7)!yPy0&@5rz5
zI@2QB%knZjK>$pHJqT>T092ts7qEnY83IipReA`x;aLNA;&CQm5lDdt14rxxtYaOJ
zSP4AA%BX=UT9)k|sk7cUj0###{rArE^?0B0|0H<je=~HtI9ovysKv7~yaWg^z)sg8
zz@<Q47kF%iaT*E?oo95Ib)*SPC=IVOI2oK<d2~{wtkN_*ZD8FzUT@=bz8YoeR65({
zK?Omyeu@+Zb}}<EO@O-Y<{FrIffXy$Aaa)NM$a+Ocb=}t`K-@JS<>?c6CG?=3wFgI
zM(HoqSwTT6n8IU%*+fbi74d?_Q33+9RiBXR=x03-*JFS7&Cv$V86?_7Q$<BcivlHP
zQ_7~Ak*A3|Wqpj@(a(CGt;hY$4-=e=Q#K}=hS-2%5r&-r!$3d20ma*a>nu^=1|UES
zD6p<|2pq8n%)%IQz|Ob=C=HiAicsRfL`qiTR;aaC_bvLkEHVu&o>$8tCoDc;S4ah6
zHc&7zj2(!8PC0aH`{Tj)2JW9X>+O8vf4(5t&DfUvIeb$G+8CqSuYeSz1*AgnaluSe
zgp}6`aIDsbUHgX(q|KX^Uz2=;p(Y7YCB}z~=)4XBaK~wPZL_CYlDp>NKl8j;kNxRi
zZO^Z1Vt`^TemSC+7SgHCI)(u!5FpSZGD^Y)9@`YS0SM3n$CWMthjf4u908wJDFF&(
zqURyXCB9^;2wKE27>Rf7m0IH_&GvhKmw_+ly?PtJVw8|y!}V54bXdn)eBl0ml~jmp
zM?`0f(#1L$ULTIpzEdH21GCgY16lK4dF*j78*ODcX95Mmc6L<?dI|b>er~9A2yCZd
zRtJPB+5Px4124>L^)`Rl^ft&i5EMxfBn8k;Qb<52CR)cY3i%Qf%n?K<kcg&U*{uc^
z%xh)btz3}Vtu#QG9XT0*03|^CLFFd$!|E4EDHu7XqnIIMDQ5z92p9nv3(qA1%_F7;
ztOFfj5szkwGIAZj8h|4LZV1!><3Oz<qrmT6-s2SO@@fO8=B;|{AI|1`Y!`Ib5>i0v
z+^?hk{b_#+kP_EQBB@g$a(9n`jq_F+rNu(Af&j`0LDzP*)WphQ=Xz3WvnM()Fn9*t
z%2MYWSUNA&<NgXtJhp`=Q3s?@K`-%YB^Xt30w9!j2D4EV5cNtIdNq$5_;TK<$9+9b
zh_bQNC*^iR0!7qGy9f}l-YqMGl4;PP)=jJoJVCglB_+Uv0)hfgcv>J6ISf1uNF}Wx
zW6}!QGYnMF0^Si|(SRXg-L0&HV0(T-1F!U?frax<<(O7F(r6L9L_fu^3{g5VbNFb1
z6EC|m&IP1CJPcwb3e0KS=tCc96o!Qy)qY9yN<HrD$tVNY^|NcepThl+l5&S^olUQW
z$FDKX;>p}-JEi~;Lx3uRpz{gQrc-vefvNLKxhBO+LFuwzp+6N3+KR4M9=ap<u)Unb
zy<oi9N;nt9Nu<zEKb^40Pk=?h2sS(hq)O|q2#A^{A*<DhKgYaLkN5g4?6F;0#<HbW
z24JlL{V>|*Xp$4{UCU`MvyVI)$b!sPPGsfV{qZ~8x~jvutNJ=uzhOyL+!Emq2}Cjw
z*#f74BLwUuuqFeFB>)?$y8+k$0;p#g@B#uPybj>)02U3nBY24*31`p77aCYKPt@bQ
zc9z)DQBG8AS)HQSqBB&RL~7FpnJgV$*G<`=#n^HOkHRHqQ)QdgF-0Bpl#c-^U<Tl6
zPUsj-o^{M>p_HUHmK$jj>_z!JQ5{^`lV>y5Hi1wt2Ku*Dhf6KLPaUSw!&bCbF<Y34
zTB01Ijc@12UokPIKc=tIZvdh_z#dK$_$Hk?oa{tLCwm^K6Ta5znP)KFV`4Ie!KqVt
zU+8xz8c6d-M^`4+vpID%uGqAZiL%mF<bhq{1hefab09jV^6Cn!4X6E5l%Tav0c)jo
zM5k@I8|(1Z^h++_B@!U@QVe+mLwNb0KJSx3A_ih;c#A+vCt-Nqu$AE@7NPxF2U(Wx
z5#^z^w$jKkjt*+EaK;0*cK2;Ozm-kbRd&4FxrqddTBkrlPy|rGTA)B?)XW491C9Ww
zfSsU#&;SwW0tqk^V2uLV6MzB=q`)u%f!v%A4cri5iLGKCWH^=O{<e9Z9`m(kzCmuF
zpU!oF;o)Jfj+OWUWoShE#G~t~J-LzIs9k79gi#*LSG>#a3-CO_0$*V*gf23{Q=nn5
zI{=jFdL6^8qe!&~4VVdeQElLXd7UCgH+zg-4MM2{C<=-&qJPc@_O1ur4PIYH4B7`I
z+S)x`-h=ry&pT^5cfDfW7s~sI<XYtt$+KlIo&bx$8dyj19?*F{u(H4p$P0m%OqQaC
z%6XiQ|HFfA5k)sa>9)Go?4EfP<w^&t^u2zxu;*2Iq=}w_+9iza3|SlWgfHBwGwn*?
zz$M5x`>#<}I8W0_Ui%@@r@P)N#w5zV><f4zzz@tQf>o3>C)YcXf9~!BhB1j`*ld(<
z<WLSTJfOEdM<4PyzFrlExjN&dfD~|6fR%U)#!-g5)dp@LfW>eo;EoGm9q53aC655=
zIR!cdxCPuKbLzQ70yU{N#<OqVdev=r-^&{~{UDR0yXRjT$U~H3B}JNHSMD*n2NQBZ
zP_zoh!X$tYVB#(9xbU#xuubi-3Nz$br}jySbu(<rCdkG?$@auT?`q(^gG-O~`mLT`
z`TVz1kfIn#1H7^9KJiGJn0Vo%S!4p^2-blzrD$7tRA2Cny~k2X7=AOp<XJEb45K@f
z$AJ_uOMpF6<FrBtY`E2(#6sH%9gO462KG9*lxKQ!qzNEeOq%3d$z<hTo4GHLFIo#+
z8&<+v0Eqe^3?4Liz;3#rjyPJ@Ige*z1Sl}fcsGjAv5x4Zraf=mRh0{FcFUnXi`}OT
zG#*rXtk-YN^O)YKP$x+PBEXLTg{J;HTUdI`^}0<j<cxt{Gr|UR9w7i%o3e3ahMq?E
zv{9O*0f)07kODyk!(1I02RuO+)dJ(ZHE(J}88H};Nfoq$038vKN(y8)fL3xMTZGNu
z)6Txnw;I=18~D>fB}bO;F+e4uNKtL>wQ0R0`kF%&WE%A|-jGhfhdA)Qi~C^g!m~Er
zN|XA*EW=tMt|h-MnoH~guIoP<SZiR>!KAnG`nN@%EGemjR-{l3@Dn5kC(K;yb?QV;
zO?-}gyo>`<5eh0s%DVFLwBeoR6Vs20EF$krDk^{?v6BF0ljGgHXO4PN!8G7sc@XKb
zUcZ%)V|$q+gP_SCDg`_dKuF}f5N76Be#h0wNHL18N$~;LeB;>urDxQ)I=T?70gx0?
z01sj&oDp%<jwNHxz!?XTI=XW--$Be<DOC1=A#4P$5s)U;h>Fe3mWdt|*bP_wu&ycH
zD4PopiFUYVE_I|#on&}?e-Z?S$A>|?SYIGOnMH<#0E!_19bg9pP}UVPpd{c;z{?1r
zbil^b0u2fjNo2^Tqup&!cRTH3;QfO~$A9frkBI&Rj~1$ufG7gg1*eF8H19@!zq0B5
z*yFDEOxg&F@->C7wLliQ!Ex8yo~U04T5>ZWBp?98%fLG7B37fpB%7|4yI5yn(!nE-
zRH`Ks02xAR``e1I4&wkNgV>bRL+Yw~*tpu#T_NoX1qO_Qz<7WQ_s_QHpF+^eEr*R9
zOcSY~#BB;hK*Ufd-p7~c8YmnzI`M1Y%rnqEQSAiO00sgHPgM14WZKGP;Y8YHHkSS|
zg%q?40eoP#v!?yPV|vfG`Q!efpiB7~T62dKQj(a+w?ZH~0s{GN$>og(dK@&07#7pC
zG?Fg71Fl`S69pE=@Oa+vw5(>1<ZHGFFuOK3GE$>!p|csq*l7hz9%FK+mD8~<h+ObE
z;_Qq%N2~{H1+*LMDHPlQXoU_)9^pEWfEy?vw7|0!gf8$VZUKTZ0Gg}Z5-3{$<``ON
z#?g6RcXy2S24)^CI_?jh+~VlOqLzSS6D!5k^8<&ocQ%#Z*s<M_7i_$c3c@VBX|mbI
z!|=l9d+D<0C63mF4KI<9kPzpQT(b3A-lYucZ{V|oL?`^A?-C3$V*}lMEfVMGOU}rf
z(8jTJ-DW{}Aso$MFbmi1VhF~ThFf_I4L#);n`6wRF{({s{e-uJRjjq+u6GRvjyg!>
z$!`0v2vQtGD6W;&lNwCO$`Om~g=J<(BP!hkK_}BXO7|TByzClsvIJCO%83!L;#eQK
z%dpGu`ryzBf9SiBzQy2*so-@86fx9=Q)EUPaoY)``Bp-m`!?U+cc3fEPRib53XB9`
zj6x+St8iPH+9-1*-rhR$PO~SshDQA;ej>C{pwY$3F3JWVA%NmcfB;><R)AZ;Ap$5j
zfMXy9)_{6U1&CNu;D`Ze$dK%5fDNK|=m)DFF)-rbP@YNAwdx{D(fj@ooW&%iW?qjx
zU?%SI8S+9I5YvF7%M=tgvEa}tJv51POhQs(Ule`O;Nd&lU1H$6gF;*V(2G1r(Y+#4
zPqZkwMq8Jrq;)(^<&2;xtz(u7K)%`!xb+c_#1mV%afO+3q$J)>5H@;d(v%h@<CO+_
z9uV5<2OlSTY?cTlN|A4lPn4`SoIBd_o-GT1M;15%yp(<;akXxBj)Y(WN}IR#zzxps
zT;3b<%4CEZ)lTcWZ~_pZ^hlz0L;=Aepx7k?J?y3j3`{;46j0_{npmyl+eoYgb%H8|
zzB)UKlebq!3-{W-BN|HsR_yAq11ta&7;Cd61VC$pt#r>j?T(9|yYg$y<8dGi!@&q8
zl+Nn`ivSLwfRHL^h3tuda0n=HBhUgy@hBj4fC?BBiKD<{_zR)mxT?9}mM7bO>i>Nm
z1Um5#e%RAsW&lZ|DoLHfF5brM1a8kwSPPH5rltgChvVdhXk})-7l3dpM^oYylWSi)
z90_3<CsY~6N~5zU0;~kFDmh}PO4c1qwvQOt_aIQNdj(O)F-8en(M${h2SSj*NF$++
zNVMVW{mAbBD<{7E>;<eXP(YDc0$wP$TsWeix$k-}I0dhfn}C-PcG7mi)657VBiS)>
z4Ienqn|*BSIR@4p{MqUUpU#aK4)$aY)_{gm&^Kb=IxGmRnNf0&OOqcONByyz{!gtJ
z$T*cIs8DcV7L<U`@)(@@2%BnKSKtX4CeB3>996l>_0n$dqTkcOAJ^`l*Vqu$YpyEf
z8dw>=ft5hmS6d!5pOpvr>Wl8{OW^|$Kwx<%yilMF3^4$dgQA2pmfq|A+{5g~na+zc
z$3@K@XiS-b`qdSNsRDu)xC5*aK<R)7JZ1%8>?&m-j_FlkO$H)EAklD0^0>hxxEbye
z<ncdo0W6opEna0{=|P_p{J;;n29s1Lq3fmlE@KaNYx=!(h>ur}@zchlJF-Q;V5D%x
zEfYz}20?KY;gDIeT?k@qrqnQ+cnRXYC%awDbEE(Fb+G4nKX5xCqQ7Y@Or;(uGKDQ{
zMW?zTbt^-3^=f||IquJT)0Urzi3h69QNc?<az(&N`G#@e@XY-lpVLOWC+rM#C>m>m
zLF{yF#WTzZMFEBQoHcq_R@WPta<C`IG~Z)m&}M)_=XwGl0-2?CJU?-S&#WEg+fbv)
zPH;(y_1TR_=c&W*nU|Pt(ToLSB?*uw!+@27=oM?+qLUJ>BRWzs-}x3w##5|MI~!;^
z$aDN3__n7(7S=)10@Se*zQMTac%oCDDv$Ha-j~^!^aP~if){|4@~i_w6eeE5aU`BV
z*35I8p?2N<$E%~7Lc-Na*avVVp!EoAp!3)z;Il9$pa&8PWKR@0L_IeE0T$R8@Qu>~
zw*)>w>uCU2;D5;@lpA2E9d~)%Xkf>KJRW;o=&o7`ZJO3*zWvg}e8;wX{d|~2?ax}R
zr!me>vCKG8#QpWq11osG>1dw`?~XK0fnnCOfSAsZOV&G_&-QEscOTq2;SYQ^$5HfE
zLGX<Vyg8z<l#lI4HsyBW(SLHsrZ1uG8C-%}_4V!)fZlK#hQ!fY`-t$S-ma06apFEI
zXQhRKtN$Dack)b1c2|Th1q4LfpD%6lF!!+Eb=BQ}7NQ_~VB*tMFFREobKASSEFBSX
zmUENJ)g|sQY0xtR{dTfjX<*qwo#TJT{~Ym6<6b}57?qST08)vTKrPWAgBEYINwwVf
z9d{|g7Ar%;)VY<RI2uV6QiWwTxV)lXxT$*O@UtJ&7$OLQ05AsdXWIfF021H^AbPF>
zKMW56OQ1sl^(=sd0Lo$Dh-2W93btSXoS?0AO+aZ7%D`AGv~76w`mFX({{iRCIq@g|
zs|15A@26<5L;{HH+I}5++uF3rMyARxyQpdKr(jCW{T}34gH!QZ%l*R2E>7qB2CaU{
z$}uqw9mQ?~Yv;}JGKYiKjsBR<1uv`9dLTfI?(=G4D=MRJVrkuHqKC=S#|Wq%%9ObM
z2KuyW$L&3PF4n=I)vqUrubC6_>Yabtyf`QP)c<UFG{Z?oiBTEtR5<O|e(ORG>=owR
zV`(h7w3!tX4G>{!T?5T--eSF(n7h<mu}tATHG}A+a;#HNiV^LEsj!8!=1KV4JHFa^
zaoTT}i#yH>mM|(Q;4Oe?l>Pg69bP|thY49YVtWoPhaVd-+K=XdDOgSfF0jYs#)<PJ
zHaDE{)02aYS<EhKtrNfq&sC490m&mC73fevNPq%|o?{*dG*?*yHbK3ZMBv)g@Ctqq
z-Z|H-v(?EU1E=S`d5rI$WJWVg84c^Gpme>fLI=*2v|6rLj)ylf$N+W$FRlDRrq%&d
zqm1>z4X>w(taw&Dqi1Gm<;7u)m}DgeGUvT9NM3(GC`IZW6q$tOGjp77+w6`zI^#M3
zUP_)GgpTD-PYzDQmp7QkGQuDX5$>YQCD9;G>aoqO%3TIB=C#@C`zbd_9Nq0#S7dB_
z<e%auyY%Rdf-1}R*^}}D=+d+}0AyOrpr&zM?hchsWFs}(Bn(2d@>;%yX}07~Y2fR5
zYmWDQ%LGSv)&{g2X^XpdWF<stNv*B>PB44+ouOcYj6DGh7I2O5aw3l70^s<6?VkL?
zDfCKwR)5s1R4SDqAVn`r%$YN%spS;F7J+r33nX9xtPw!z0x9rd;0Q>-3RqcG9Y}y0
z7%9OhQFXMFJ^j_rTa#z=w4)odf$n~g9jRG~;apelt$096Ou`su0ce>ib`7`{mx&+^
zuYq>h^s($}===c#glO%>z_lT>#s(glm*)82H=FC|4|Npk^lJe@J7uM0u$HuSA&d9;
zzG(7Y@j|{qMh0aNcCxMuz#x3w#qat?>)lC-)ZChZ0TX(j2ZW)_D=`Uv8Wl%T^0%3n
zCSs7Y0Z@wHV@a-S6I(eF+wQTA)<>bYU*{3*9K-z{P!5kVaXQ{$bG;6;9~%pTG^Ye=
z-p=3B62=>d%sX@J@9X47jJr4Y8ZprTDIh4|a7^a1_vcQ+imlisXk(=z;f-0*0cirR
zF(V_4nN5u~PMWCcYd))e)-eTq1PJavI-m*kftLdvkbs3pSOW@lffP6dZUm%2QbfG~
zh$eVUU?7-h<~ZM%#^>114yfW3rJJH2XOjev$_1P5=sI8;?a$8AU}=oRl);Vp8=r{J
zhSOjGzjA=@zn)ZMJ_?;xJT$l0!65_l=9MwH{E%gw!y2&?*a)ORN<Y@(%|`DKbZxV&
z9Y^>;yRZh?d7z(RdoQnVT)o<%6Q3xSib|!O0{H#?iq0Vggbf<t<mpcf&-_CJugn{>
z)%P_$Ja(4KhIJI%SSF3UqSjsV_ven!wuzTQnFZ`@+g7F2C=|nM(c6i+{@s+ofC1q9
zCicTHVbMC-Vs%98h)x422&lnEM|AfY$euSQV&jCPAM@55@Qv^T+(eXsMeJ_|8;6}5
z6SVLUX+30DIwU^w7Fm?B6|*EwC=3@Y=<3P{7!PU($9EjZ54bnaV@R5NQ)#GcXsBrT
z61hh5*h>K0fD?exq>kn~QL1!6lsdj%fjW=?<G3nZ8x+O~5>OwrT3wgnFnOMs<9uH_
zJEGrrgP;^Ik+i6lzf;HkxySWo*{$#iv9lhrO82Q_gX`j{$f_<G0tTVyHNrd=6oqmf
zj}7LD$urse+L|O3)<RsjKgg*^_9a^+$`NE`>^r<OF$TsMxGp9In<cN-Uuc{&mZ`VB
z9pQfa2{MmB6q5Q#M8RXbL^;_u56m%N9pyTT(C(H7T@M!sfXCUj73ZFI@YoH4DlZRK
zVtD5P7-I~x04z@g*C<TPEc=?W2?4BI_t~QJ39tlp>au&pILqZ#{5&sPy*f)U$R>&%
zE)ADZhD{yY6|+wqsRO?oXY31<b}qYYCBN=rCU3!Cte=fFtA`2O1J5fdjtdf?6}k#v
z*0TWYQsCuU3m^k)VukF990p890p&K-3nUB!WuVTY#3rcwrY-W_+BeUOqr1yvVo>dh
zVF#=Y`V~v7C5?Ly9#Mil=>Z*9)e5Y^u@gs}zOFY`<|2~@e9U{54US^|%zM#u9+%_1
z8hYf}Ox>VOx_<||UwTZ9Y?feWM?e8U$lMZ*y2iEh*2L^AWyP33C0&X(I?w7PfI&{p
z<C5dTSw~krp_{(YK*3m;l?Q6qy`=Sl7`75SFRf?6etUl1<0_7%qqugI3Nz6EfSt{=
z!UlSE?0W7zEysRU=0x;Uv`Mk0;Xnc$PL{xSZAxnIa5`G<!VA8Ul^BN7&S<u-0n;SF
zgc~=vUis@hBWd<4{v(tGK)8g#JQjGq1n|Yi^j6@g)`AQ~))g`kJ;McrS4V-{bWsNq
z6e|rM9Ec;^H&08%pkzZ+Q0WR%kr3k!pZ7zv;{yd%<|{p-LCDnbGOtN**Uf4je1kIg
z#bXoO+7!*ha;#U20!KH_(g1{_N3|X2uxW(%M~<snSS2hh-V&7_p}!w^nKvqK(6?OE
z09tubk_0w*vgP?ckDq7dIIo6;h|$VsKxu>2Ns7{4ClKtI7v4!;v)OYcvZC~mE|c{e
z$YJW{&HL-0=yxYDbZMR;4A%u4%_NETq{rr2F@)0@PGXuHB1Rk;0hKPS#FBs@Xl+84
z4j1nswZxvJSQ$M6;JP#v!OJ|(#1U`tIgh2aX!<aaN3?=l0F24=B|NqQbROj`fU^J&
z1D7kPX8~kjO$4$h>0%fGULEB&UDUA!b=iFbV@;oYg5M8&%%gIgSDO)@Y^W;T*8gCb
zg>awv*3Cuc5?_2qLg+c!FduqzZlzv}U7yaJv!vz^0Vu-Uu9w*$Bx6Jj{yL9J#IPvO
zh^RO$L6J@h$gV-xKJQ1=p1W`Be{ABF@Iuc4f*h&d!(Vx|xj!MbPUYhiZE=Dp(K#dx
zCy-F5*|fCX%>H4{JSoS1)nqz4DX&onK`Bzag#J0hoH@FJ1M}5d2q@9BF1Cj^>Q^2=
zuIW70lMU@Lb5yjeBI_G=cXT+qhvrF%805VMh^Uf)7D78nb9{ON-q@=Vi_F#pxeOv<
zvQ5cN^~%dQ*Wxc*)-JCM>49hwDd13mYXcqy*aB_|Ws5;5mw?X!QlJ5BF_sgaU`_OV
z`!yctUoNiZc^Rceu>yI*b?ptgWYf#-e{cA151t(B)yL(IB5wCF08J>YF-+iOX)Eu@
zgQHb)yKNmHvr3q3GohsnM39Eai}}Z^mtLCj24~A4=&Xfe*{paX%abMJ>G$#N%LcwU
zXtLF-|Nm8vZ05B#1XL_eeT=T92j7fwQ*Gm8$g9D&qy`xz3>MKBHk4f9Ri2bD>=n(}
zE5D^CC^4Ul)=sa@Wut+~2TdZz1s>ao1QLq1#U#CQ#4U_j@2<UdH-;+=q{*lTv@#lc
zjBfGWeDT%Ds}Xp}kFar2Uk?GSm02b_^Kgjm`XHB9YvB2VCC7U8>FgXkLw8S9>yV%b
z0$3uFvP$GLUN(-Or!Gu>7jrg;-b|7u^|nHhaJ=IU@3j9ntHvM$gB~y3k&|MjrLcGw
zlnWj;NJ2dVbb&VkMguN;p76xLf+svytJMYUQeX`f1i;vJMS0FLAND;yUnIQ_*+4`$
zTCGR`w%7u=9{8f5Yqr4Fa}%_Ocs*be1YAI)u#F>Ipk+(XP0tD#C=?(A8Mvv%0re%M
z5wQc*#7G`AI`W`G%T}+mg$O1AFfkgGt;eSDY$;4^i8Ns78d|mpK^2@mF)=*Uv=2Yz
z8ZH>Zb_3OO*K%y<zILJtP)8^jSSX(?5?+cpI<U9zyhB1UWY{d^$wHpH3y#b+7d$PW
zwM-&acJTzBs0!n=V2-MOC%fEoY?a8VDv+b7#7ZYUyv)#p69L-<F7gOo9ch7~rE3Cq
z0fwH##K5R263{GQp!GaHK;LvNV;xW_PK-GlrQk;9YC>@jt@xBfi9jbx(<0BJkm2zq
ztT-eMjP?u9nvNsT!-%0c)TTug?+9B>7dcdmmPpG<haYSSH*ahG$4qxiKApK}kN)Z`
z$Kp~{DJ*p$0T;)?{T@l5>_-<?V68q-3wm=4pIOpo$;0N4cnn?gPUp5P6(5ZNB~n0|
zGHcZ%Gokkk<I=aJyF&N4QhV!hOGa1)SEC<b9RTgWaU!rzBOTB?LB&l+-;g@|sR8;m
zK<8O6fOR^71<(O#Dzt+YkYWV^O9DDzjlco~qu@OO(L`3y2M#?8jxIqyiXGe%7HCQt
zMXzzyYm_Ie?%b+XW{1ku?eC`(4E$qm+0kBU<2`oOSVFy%AOc!XKvKmhsw_K#FD_S-
z6g!zroFxx%*x;CY%QNU6L!WhqC98zE&#AMOXfT8mP?Nxd4~%H?(DXn9w1I)1HKS&h
zAp*#nstvtv=%lf=l!2iKIyL}G1GKR2yXBlRfQp85&ByFj1)t{G@5j8D-=9I9K?P{&
zVSsXpmfXUZEoOk+(3^KoN1WDXU~^K4lN)O;9o=A!DPVwv5&?ia4$s)y&;FasP_s5I
z4s{IfYj^Xffx&ahEH2--iEAQ8h5!h4645$|i+8PemsNJ31~&dR@Bsq`&>1Gn+DvdH
zaBnSK*ykp!9RY@w;e@otIN<TRa710a&lBm8i3p$*>49M~k_Aj=dcqwxkX!>U1t%k^
z1C*XGOUnQp1-=L_!ZTzPi=gBY$^%FtdnHR44o`TQ&kzS_XldwiH*hkNSi_qDdx2BL
z3mFhS3Q7sCVaXqn5u{qO7nC;(XgFdC^b9nt+0qdgkuTE0z+019U`s<wlU8u@zH-La
z72Ef7bhN-JJj*H89>b(0R>BjQY8Fk_XOgm$@R%E>*PYuDdVcJ4!;bmh+gF)3i!6=`
zg;f$j6n)v2500akY6_I_1`U1>88@4UU7(}UAz$D)y5Pg(3sFlM^<-?lVI-LCCB(Ym
zkf=c91o8&gz~_wQ$mq~hbpZOIXS_MV0Q3*rbzHfPx3L3FD|944p^U^H@6ZD*0fjiy
zt2vnu4Dd0pOPFUt68!1?Ad0tXfm48imC@`(S@6F6R*ssMrbQFr2Dy2<Jw0J_1T+r;
zwu-`+48v9;bRan?2mK0iXss2KMzz>PJbh6y`eUC97STO1MrQ?qu_kpv)Y6c4d<a=T
zcnK1OX#QpVbOsPehG;b-aK9T5qDwC5bNM#H>2uN?0kb%I@=RzwPK+(=VuT+bp#v;n
zG4z1}`hkAvhkiT^&^NS0-?WT2&<^xXi+_N=0oFi2z?$(5uKLJm1<XILn>hz>pdDD?
zZ<njaPJoVQp&jU(mbwkJ17IU~PaMeC1#q1~UuD;InQAR=8{J*=m$vEg=#PD_*Q34s
zc(%v(OAw*3CJH`L{q}E_dvRu|I5~M(tjqYtche{_#-}GG<4Pw085COXcnqdK0={<H
z$%Nka&rStTG)w0HDbVpCr))jbpCeQIzUF~_f>-W`92ui1(=NceWL;iL2dN3F8cj<2
zq=7+my$oS58^%dU>Ij;siq!Y@Y585s=-lC1A64<mG<#JeCdcNw2Q*+Z4bD+eh5W*A
z?I;~PyBD@UHdU>(!DwNLCx9RV(4xwP3ULCBN4N}VEjRJ3foDA@9;FMkz#7<$ZB%ee
zY<ZP6VCVodu;w8KVC|7W4`|?!2D^d<#x5U`=unodNGw=;7Qh-fn(&nLew+hVfKqC&
z(N{Lub{UR<1gIyY@+>V2jyWXJam3)UGoZx{Y=A?+Pb3HOp}7v74>S!*SG)b|-6nhH
z33=6}2ByyCI>yU4avWJ`gDj>_9igCLt+*XT*GkB#!+olDBANROn#9&(a)e~=JxgAm
zY;wnmd)ecD;{Pq%lBH&pfhE;(mS82Ay*y=f%PCtf4t<p`nb1b$bn?{9zyE-9wT}Ms
zetce+H+yW1>RLPr8BY|X4)TG)?Zy`Gt~~0Ge@BTO-hk9-H!^mJ7s`oRQaR!A)*pBp
zeed7o-3MvP&a?xzKnZ|?Fmv|0n_(5+N&}n%TgoL83)ZzVaE`;UBy-9k>fnYYnI&+_
zW#IFGj>~}sYcg9-i9ko<5NJ59(2+d7Kp(KKQ(E={2Ei8<;G;bHl!3)_wen04MRa45
zCV)siQ9y(QpPJuuclT+=BmSs_ZDbcgn8_%?Smh`i_nF*<-HO)K8c)P5ZQ4owo*!Xu
z4*gyjcaC))Z_$xy_7Vxj3#GD)k)<{9&|Rjd9A}_#F4kkb_sgpS)l)>)S&5tLQeWp4
zNpu|cHA?K;w6y+kTYhTh@!#{VO%6y!K)$k@5`q9zq6Fv+Ls-U=P+n>I3Ao~2_-lb%
z9Zjs+U#s{5Zh``ClrH*aM1f3OYY9B_dxkC00pB_Bb|3;rfB*^zP6N!u6FmZ`Cj$#2
zYZL*D;yIzvC<l+V03xqqZUJ+pp$9Th5O|hS;~A_KuVPd1I0_`70ZavGX}C&{iLvF&
zvBh1+5|fISl8y&46HY0XGMobD1mHgaOFaJt#UZ|O%xf}bAfJ>#0sM?y!ztzzz?TDx
z3FQoHGRP@g9>qm?hSJ1?tT?4uV4%ScycMeeZixk_6bn4g?*dRS0SPb+_;C=d0IbW_
zFqqv2HqXU!WM`AQ!Lc$xl6pcx0amwo?kL}W)e$}eGcVLc44NRokimrzID&f!9#j`S
z_bhC$RO?LiS}DwZd~bm=YZEU)TAnnvQ7%=Hfn{^8j`7|*v-3<Z^@tJ*kf<O6+{HEE
zy|wzKWBeqsU+V&SZK3hNK%#ssCceFV>5z17GfD;}ut0Yn9k2yT0&wjD!!5Dplr3<I
z8Mw*go)lOB1CW6wkU8g=C7C6eC7C6oUBHq8N5Fy)u;p=06&Bp&tsDUhU=4IY8SsjL
zYJrr5gmjIQ5!ft=SU&!-&#lU_SNhr%sX}L~=&ej!A#)G^J+ImH36|{PIA~hcnT&7v
z@OK<dKXxV`uwBZi!xN2ryjdkWnaK*Eh|V_A@qs8)?g0`96~YQ&C~gDfh+n!0$OsCM
zBV!Z=7)Ep*!$1k^z>`JgB&Q54o=f#;?|oioadCAvlHiR_D2hQGyzni)#Y2B$>#={y
zMc**%l+Z(3jYcS$tjsaUOv<S#G-gi0xX}3XcQ1RQfFgiStOK3^3<*%+at4S34|vSP
z69Mt4r^612XYJ7%8CWoQKEu-i_pl`3A^aWCR){PZcn-KFzS|7+fmZ?%P#y3c;3ovY
zx)G%$AOo#0b-?{sMsDXLj7ATTVa@1}7QpQcb^&OCXMq$*1g_0E!G<^@*7GHQXuDCe
zDB)_^$dDP=@oxtHIalgYUp`E56tn5(+60dwK90|l-G`3-Gd>W4P{I0PZoE~Rj9(6e
zf7MC!b5E!bMduYF^t?Ha%zRO1?E9LBnj_;D9U(_1Tct#R!Z6o)Ei(b-pvWv(o4*>E
zIakV2oc_)$Bt@(ZBvk5&Pb+#n_F!LQJ>qv`KP%w?!B%*q8UzpZ0{54`7kU`*G6Et^
zldft79tHB)dcd79vB+qibu)TC#)&GmGZ7F#nfhcwe~6V`ox~kjPd89B7wXYoemLAC
zL+R#X#${iZR(7>Edm23UFMH37k73iNpp19+&QvS2tP`(yeOo@|5n(Ri63{4Q!3xKC
zGX&ObDHjwjal|2Tgnt37JzL(Pa0uK0T5d92loh%n$y)@7RvR7e?f)~+g)&h57G@Mc
z0WSdvN-)AFTIhEr>$QjY*6aRQ69rdLA!vh8ht6a|)>d}o^1^kkgeHk6>Qv)aMMW}4
z2oF?ffu7F-QY8VlfQ~@{sg!}}Iq?V`>S;ZK5vXVD8GzpNDzHWXr2{T`gd?<41|ltR
zQprRDw*yB35fcU=Gb%4M2#cSffs9)s$`(a9;x=Xyh`<6UBb*XtixPen_>zmLb8VD8
zIS9&b1x&PQkRzNmFm0~Wv0whbG6JfUfF(Z(*&q~YrTKc%7N%aPR%S{eCyxJfH~jv`
zTn+kl^EPCBFO*J}Pgx~28DoxrIR=h^4oFm805>_M11@pIVc>|W*1##FhrkiAj+<i?
zb+L|O9Z?=@idQ;XOo`gQXyDViOk2JDU&UL(wjXcEjGx@@*V=#-P-Wi@`7HuD8P_JA
zOUL-hKeffX!Qwy|w(`{IwirNXtgrFCKl77d>M?TNJB%edUhQIjfoB03TMvBZ#MC1f
zPzRl(6j%W3z-(RR?bvO#+C{lhcm00nGDVDcNA%-1P^{`&42fl~TJGM;&eFtn>XCnJ
zs#O>^w00*ZtK(F?mG}O#PjI?^spH(^q<K833f&at0$+3z8RDaO*g1meh-fJL;z*7l
zKFtt2rAaY$u1z1TOKNVs339A#pB=L5WZ;guN{{{?u4?D%?0;#(w@-wUSI`OeW497+
zm+U@rl3)0{4)-n${}cmj)DA)@UI2{G5Pm_YQEB@r9O``Aj#}Bf>ZAx=uOtQROh79M
zpq|0g*XjTXC~(6QIT}Ou#0ui+JW7jrKCi;y=>ao%gf-B46iY%pM;-;TCrXtLh=2ru
z>n-qpLN#Ha29(F2016n3N@kYfmOzKfBCzpw3*c5JoDQMu18k!dZdG8Ib(HC4-LREr
z<yab~nw5x-!4U&1=PKoyL?VVU8{T5<1{AA8GrDT6t9CzMI(C%rK)%S(3dWEcF*y!=
zb1(iB7tmv^$Bu0&U9ZZV_mxod<P@c5jvz{Rhw%bsSO-a@$Y5+*;$|Glnm_PHNXLB7
zYPLa!2;J6QarZNmZfhs}`EQym4A&19fE+>QQ^6V24m@=po4NX0ROnFT@kmKY=B#G$
ztH9dl?FIUP>j1X`)-g<pvLdM`$kb_3kR#b(VDCmqo-`Lt*jR*;xH$Ysd>V)PB;~=s
zanC(|4!GvH5S#J|waA!hTu68+FZtt=8Pw8@lvLR1KN0J^zn!)mr!B_|ogA4;6&281
zOia_j$3L{u(N}!et~~E{T(c-0l#N{|>InP}Lcu23WGhpyGh1okzsgs{Dp4s;W*1o-
z(L{ggr|Cz2wvj9+C6EAEh9x2etOW-aZ~>697>B5*SOvU;hAl0pKzs?BfC+#i!GRG4
z6anl6P%;*vo|52Mv0>%0v14Bsc*G+#sOKbL41rCq^Lmfap`PRsj!>FfMFHeWCf!Je
zOSR0v55StD<`G~OFiC;`0FgDq04VS#;0QPYKA0f}GQ?Bh25<zlfN~Q!<zY3gVrh4}
zbCZvM-Ur{^^*H%!n@jW+-?e_{xm)a5LlcU3iWW>#N4{%Q_Y-edzi@;*%pGg{dMTJH
z%<z&$+4Gr?we2PsO^1^aI@RB4u5(VxxP>n1`_A1PYg*iW)IiEyqVsvb#^t7y3f&yB
zN(7A@UPl-1TU#D1sAPaaGeo_D(DN(0*h|@E<ql_bdfkv;8?KTvm-rM|0Bc{xL*NEb
z7<iR68Hn<7<U{UDE4KTD{VK~q@m!&w+LLd0D7i?<{d7}OYb!`&T2K7zkHsbbuS!VJ
zE5xMsvS(zp51t|qwHz1ic=WBIYcJ7XT#grd*=o~}<Mibi5}=D!MsuX907^wsDyN-;
zj8d*yu7Or_h0Iyqi5d$w7RQJNcoVX6A6Imgcd&eZudbDtpbsMBg%9OIM=<ReGD<mt
z;o)HfLA^wwK?HavL-dG8D>Sq~1EevD$E^bd<vQX~PvRYHXaL(V0r6Z5w1Jl^Er9H~
z#2WEj3navInCslCB>>lbM}dU0;0K_s5IxrcOX1P{5U|FdIyeL_0Rqs$0=NZafaE&_
zt_!p%Ycjnq%g5nY;Af*{`-H;=(&hqvfd`jU9NLX>Hrw{G&8{Qg+T)i9it<`OB?eS|
zo$6mBH%iXRnK?6k^;vi1z-S;aCx7L(XAg@~Q<R!Hdd68SZ5^=F5gc1L8YjtL+uR?=
zcs16FH=+hnXc<byHV9G)S~?^+s@}K7g>qR10hJz35yqP1x9M2X*`!@auei14b{=oB
zmDp_-C?Hd{0+tsr2`6f;fCLQ8>&R)j6o9OZtcr%wj7}IBIoIb4+--7>aS)ZoOVEVo
z>d$n_UV7|wg+Yn5OwV5`1A?&#Y?UrQ%5&<T*4Y$I-wf6=PFPvP%q4vsxEy#W(2zWb
zfg=t%0v3Ta9m!)2xEbIGBo@G$?m;4gpdwIrn4kV215eN8`AY82{Yo}793x7MT@t7O
zmHDEzwGp0AX-ZqU`%`acex_tW8A_B{-m{fT&JcqG21_>tRi4Y@5-XZ8TdLQ#L~11p
zq{AqJ;tTpoi^!~rp2L7408Uic0Eq@T@d!3RJzI|eN?&0B8rnVaR^Vt1nTNRKSqHkn
z2Z1A6pkWPkz?uZCFcF{wigsK9l*7Qo2oNcQz?uw1zC5r6oQ9B4ngC=HN)AM>aEOuv
z5uqajZVA`|nS_#g3O9k3=9LJX)bq|O4J6Oy+2y*fWYhVsfGAxm&?0MQUh(_Xz0!4m
zL1lSnV|kf)6ksG8TxQ`cJQA*{ybLl*4ELwfX)fpqU<SY$NQ4(aLn3?#9C64|U;(V@
zNWd1i#368l#DXsF?+KP<i?A`2-=`S{O6Tf)MR(fqJhvy7Y!pcV(nVquK&4$y;&S30
zte^Smm&<u05SEwAJzlv?!Q}zUsW`B$M4OEXBz9$;_NUUlejra(0-6h$L{qB`3{y3G
zm1bBk+rUca8)!OLXP4^-zmvQ95|tBZY(Xw}J#l2-bhsk3!PQ+64$72zJPM`Dzsz&$
zuHfN)S$A1lPU40_k)mDAp5{xF60IW|@{3m4>p4#9%I!L$Bch>9Qt5mJ<cZu$Ou;tE
zW`4*(`dpl^>~25Tps{7bP=Z}jVZl2%xQjtnCEN9hL+ypfIWGH#p}eTFju=!7LSW{g
z<G|DPTXyYmvaAGLz2C|x)bAzemqKZQSRs4j1f1}s3gUT71z`YeEpP}7fPGv5>xoF9
z3tY-@7_dkM1+u3V-#Tzj;Da~-G!zSf3N$FNVE}p{qkxbC3vTl=nG|>k1u|<O0s<`1
zyse-t$gF_~WZ;l^W#l&S3a}tb14Qv10yhL1hb2L48F@ij5#~H(;Ip|myKGn7<q|d5
zE*{ap@5A+Vo87T&{jTeXQ+ME8#wG3j+WI~t?Z0VCDxK!C3otATM5DH{&gvQR69z`j
zwfTzg+<2b5-fy_1T4S-K&BF$dmA=eIB=ifciv<Dlt+^wWUwEc|&dr9%)~^4-RD@KR
z%jjyr!@z@MI{_RCD3n^S0&7plCBQ1R9tTq3HX7Hx$(x8u;0`~Nk?o@geVDm4U(sFd
z_gdbc`ER|8QqxMSHp9$4s@^p}C_+#jCr1C*%TE)`Tm$*(ShKf+AfTNF4~(1RN9r6u
za-lFguiUOP#sn|r)oz%#Wt0nMaQ-Jdm*#xl-dE<f(~FEY6&jMZNQ*Le1Y3_7k-1R6
z{yt6$40q};w4GgEpp-W*b>QsW<Yy?i5@|nHnm9*n>_@Ex4NL<Hm(T*IwcJwRFd&`|
zLtx|4z)9fP69J_K%o$Yb0Y`TXW>P60!{ti<+lgGSAXo$i8ct|xoB|GD0-)tOP(*;l
zG4KK{P?~@q0hBIaNnD}fHZ4#N9swdw01oj)tO3C`0OcCsWrT#X0Ng1&5fD1Sthq9B
zn<Fv{h&G{ybjZ~(vD9qrzlA!j-Ti6CM>bdHr}5y`VI`Y`@7}LUO<nXUeztGhmxaOW
zvQJ9ketP;6lm?!mcTIDm-3hxAya@rIvocpaC#{A6$cU8)f|+=mx_`hx%v_n0s~azU
ze}bUZc)yz`dZ=FXODd<tXc@flf(u(ToK;j*@889zfT263bLj4H=#Y@^4nZWO+Zm+0
zk(6$b?if(Ik&=>>l2B;`Uw;3!-gPd{b8{}vIZy8IXYc94s~w_Z$Wtl&VZy~rFu{-5
zipf?I^Nn*J=!p?uUhEeJ;wFtSaTU5Z_gKXj`%(v9nPy}EL8CP*dlB(=zSaO7eRL@p
z=py%nR#(1%NJ1^m7M$T0lpVqrXtr=_RuI-!P9h#Rq2z_Kr?;$PlBf)-OmL)`b;|Ne
zP#05vZP7s^2e6OZ5v<k_Z+$gUkJYnfmicKH_&|Lee%&XVhF<Om@ria!9&|U)@yiQP
z=&LLpLEMhB8-eeT{j}<65}Hyy_%6OaEg$6@u@$k_(?Jr+I8yqBf8Mat3!#{F1+#&Z
z-ak_igy}-=G(fIUhwt*hYRnpGo&q%LJd`~NfefHIAF6_e@dUh}<WW>;9^qj>lA+LZ
zR+3k66;dHygee>yFWOLvWCX=1D}PagQ8n=?P7<S|=Ey~0JrdVUX30KtwFU3;@$dba
zj<f>Tx`K3q)ltaiBhLwiTJ1>r;v7jsrJAeto)7l^FWc4pPjA%@%$uPU=%F!;+r3~O
z&)ICImdu{$+MAiOtHy-YAw96~wEe9b-31NK$%IzteT3-RWO@~M;~3bqVu!+i^@}9y
z_pPV^m-Kc%u`0XJHDs!%-7347QvmsopWJ|K@wtF(LO09F7m_35%3h9S34iVO8`Ek$
z(7oj>gMK}BWuyh$#!)!EYds0vCD=W!4aR3!V};#KT-7hy$OQ)X|IQS1cU`wn7++jN
z%WKL>bRGTrHk!Bw^$x;i1U8L8ULvS3&}tf^Yd;55P(XiF1u1IPv7LDYo|_LE3u}Ng
zVZ@t{=N!?V*35dZJ>oSir~@(b+D*_ELh&K(xW^QbyFh`&C1;gg8t#vGh}69o$&#*=
z@pCig8u1`@_6#T|P;6!p-bMyw1H6ZD865Jt3$aE5-hv|2Cm?)SR+xxWq=%Aq|0o3+
zvKlF$5AOAJg)G{^RY@T)B{qr9DL`vO6d)Rqf(JcgH|8KELVi;K1ak$gK^R-*BBS53
zxaSN5iuv8K;%sr$H_?SvH-tRhvc})o)E)V|etKXkrhZXYRHU1h<+JW>$0NQw#F<tM
zVpEJBl^NB`xr6X>b$>`yY!ih{DMW0@F7ccSiQem5#s4E&-h2)sLp|c`09pb1!RzO9
zv;DC@7{InaivG@j49XLkN1|`3o-(?RGC9}dh6=3&xQ?3)8yeoz=!#f{d^5lq3?;rA
zefndwCfp`s-hHj#I*+hY$G!?I4jFu%&J6<Pe(={frLscfqBQ4z+DL5t#YUl`5UEJ?
z{4D3+y1~CO{+TrzrwP*Q#WSZZ)ZVWZ|H^i^O&!3PVB^Vz5GiH-+s@NkPmlGpo_m}A
zmLrYdajqWXB|X7sVAEO%LA7Kh*BT7do7gYLXsV@U+q`D208+4Y$KK^{V1f-Ngx?;$
zE|(zmkwvI15AEZTpIFd7Q|?Q82W&G%;_wcVF9WAGUn>d+P@gdSS?}fX`fvMRnEhz2
zemFQ!{mryN#QQ!X`P!5RU;$!lX!67Kd#y&j9Zf8WP7726Fr(-Z21kft@NvT$)QGvD
zV+`b{h61_*Sq2zpK#9eO8NDckpTuSo)NHE|MOB+Dt-S&1#xYawi1Q=yixxhQssW;f
z5sR#4JVQaxo6180m!kZ%(Th`iw+pI*?tVO@<n60J4`#$OlMw$>TA=oO#*%uvj{)|a
zmis)-=*C~ru>uRt)bVRe{B4Jjf_#E5I#bgArs!ab(qn6s+D|TrKi()tv$S{S7BRjI
z*>9~1PRvrwdFU8Zk-}JZ?Io^cNnaQ58zNT%Ppe11|62E*t4X`elPX|a0u|XhH}=24
z+TRJJ873=EbJp{4Nry?PYaP8t7NdNQ>cC|EmY{;Di5}uaaQ+Lp?s4;?$jd3jI7-A_
zO&QeM5`naifW~N!;zr8bJp1n5fUN0YeBRR4rmJRP%VQsk&Hz61*Iudku*iBUI6PZc
zniJ~CM6{^gzV_amy)mSVO-$O?Tb-v|AuKdB>8jZ5t>Q8DbAif3@>)UvS&5=1*R`U}
zBr$=9BJa*syFBmKd2xKon>VgertjyjCt<2UYtn)KKQ0Y36TNb=9}k>E7Kghbmizs4
zn428cFT#=Q%ob%B7U(9Ztk>on@}LUTNF4DrcX!3~o?ZM6#~(Mn4s9&g^c56<7_*%f
zl{=6s#^A3eQAsT5$kGL|qeqje&TulU){~NU4oK|EEKviIjKCtkw2j#pK#<PJ=`ZiZ
z&z0WCHN(%?Pe4oHaGhhk`k_+5n@K@Hq!b2;AT5aMiBwL5ym?Zs%gq3^Ojv7Eyx?c_
zg}F)6id%#tFno|Jh&h+$8G1h0g7=)76_>3Y5`%`y2IyLWGEgy#j@ZXDl~UE+$gF$%
z#H-uq3OGdANvv?J`j>CQm!ld!otGr`oCe#w{bjc_bU!W8LY+#YdFr&ZeX?aBD8tiS
zJ-hifFYwHP!oPb4Qw2yW^Y(3n?J|Yf%0<Vm=e2ag<u|&v%Q1tWEtc6OB?v$aW3lKx
zM#zQfBgzn?H#892clT!K$H>=)ESEUzku=x8KTZ6cxZi|yyOc3iW(RO20eH7wBcufc
z*9gRLjO>pj=+Wvd33Bz05CbodAqOg?B1mE@pcIW5=9|~%7zv1HsP_n0t?{OwY1Djh
z;@@oQ`%x-kr7&hR2)rP`T`-gQdDXpdh~D+*C8@NPIs(!k#Z@x_Ta0G|-@LU#0#=?Z
z0|Lxf$|^bzf;0f4K=bCOC0d!VytWLnm|X%RCc!la;-$wFp^et!@oI_B!PjMm8)WwX
zQM&H3K8|J2&I)HIB^9B4AtY?xt`m$@JJ$`F)Ve#un_8c9Rv4e@0&hM{oy+FiB1x$|
zNK~2>?RJM|H}#zNe!nWaT%O_Im|Q1fD5?^=a<&@$Z?|j`&!$h1xabaj%Yi;kUL(YT
z2*{_<B|mu0Wh9t{EMoPhX0^ghzaTXtKz<i=F2ImrJdgK;HY3d8z(OF23N11L>VD8M
zAdhmf(zsHfH>8i}0+ci4L+!NEl6Al)o3MD8s7hm0A8t-nSPMGYiKp20i(ElQ#^UTb
zapZjA&mG6*DH?$drX%h?&0pR)`&xc3zgiv2w-b<z6OYNWbANcG4C%(|xW$Xi1swIV
zXigAc!rvt9j*#q+%*zl~cFTJxOl!6Gn%wrBIa8lt=fCpK&Fn01b)0`)>{yfpV_saj
zu^>L4?9TW5u<eZ3>*F56XYAQv6aRWT)zFm8EYC%N3fCcDEZ8kuWK12cP)JC7=38Q?
z<vGZ1aTODGL{y)?wDz;t=XrOK$h|G?!@d%j?(EfWf|G@i`KX+EWmHKt2&+4?zP9gc
z!`~bMMFtD-V!UED)MMF_CCE#xSZ!*AH@D7{_lNH3miI|DlQv0O#~)XU@&9DxapHZR
zps8WGd%CHI>+8q9YyN~g7UedIu4Q_>C>}Ey#!O3{kFglYTsbe{Ck>t8ve3u%=FHxo
zo~*Ko>~+n-d8C%j0K7L;bF*9=+B|J}A3{Da9#g*46gLgU5m4E}TaGKV?ss6sP2#|$
zNyf<qB;zPdTW?kjp+b8Ho@_}|wx0m)sZvW|7HH7E?I;eHW3=wuZGW^VE|9Ysq`n1f
zi62Vf4|AuEA{DUW;{ht87@yiLWJudhAnIE(KP#gz=$zU)AMGvr?f0V9BAv2&*DLAi
z;N$&MQ|ikX7R{Feg4r<uOk9#V1$yJWRbJ_os}I<+4bHYqAR8=V+aH`IGd`O_=3Tpf
zA7w45oCeJPdH{&d3C{gVH#MXt$O^XvCdCb>IQK>BMBV3l!!xDtEwzpM>Br<y&q|mn
za@7qJMilY!{(63B?u|>LN+OM}hCgSHFfOr`7>IkyF)*`s=a8B8Fe4Vvl;dbpY&~SO
zPvJhp_=)AZqti2`u5R#7Bv|U()9@Oc?b}>5;}tZ5)j;#YFE|_7U0U;$Z6f>5W5?A3
zC#m?sVxQk1@zo5dFY%|j$GzM8`XgFnQTVIjv_1(sOw6durh5z&i0yeQr|qRvlsZB%
z%p{Rwn|I{e@37n0yMY?KC+S#aUgAE6<L(^NE2^11xP=GSdQa2vubv(zY@R+0)D+#f
z{s>bQ2z&Cga6rv=pb17o#~Jb#KM0n8OAwuB^kAs56HK+8%gLlY=ef;EuxP==6)EC_
zVvej)frZ*Rfz>E-JTFw4&Xqy|6L6KCO3Kn5Bv6)$5=lZHI7yXlN7rzABgat;?z{e_
z1EJ70Tigp;G=WGsi4kNGj$WjE03cOCMgnXxcHyBsAR;43wouV+Au9Xe5EM@Ial;ta
zbo94D9sik_tL1iu<!_Gju}<WS24$kj{h(%u)E}5vGrDN%FY~Wgj;YJk>8y2vUlqgl
z{*Ar*Sswb0Z&qHAD=hDz8kO@6BZEg^iaM)?sR29{JFxxP({p~w=jOQlr@YkNe(>TV
zLE~_poz2S{#!5c4;**f!;sci~Y{Ssw5I!1<cOSk)RMF&od*45kyf^(NYdrBLXR6@h
z8>Lf#Vu0|u!;eGE`VOP5lJ|N}f}mVT4Z}=>7492K?j<jgt<QRapX>Wk4fh1-SH{`P
z3rxKkB!!qi1w%?(gB{0V%0)ZF%@W2;u&wG~0BtWsIZ{v&XC>6J{#VC?+3JO&X1JOd
zJLdWuoxIW5scg1heO4}${b=Q@70$OC>c_-{3YDEbSD2p@Z|XlUwG0!YFP=%hxjg)5
zoX8iV#Of^Cp$ZpTIVZz5#-u=dy<1X6x4H{U)sZ;8>ln2f($AtUKPsNDvv`-OUnk(6
zm(wFT=hCUsChpHE6*K@=ekMUgbIx~8Hhqa;QBNmF^!|>^Jg>VLxS9%c=8_PwX?^uJ
zl!k9)03?c`15U<SqxxKpdW#~3gM3ceka)W1LbzBIld0meFAM1X(iE=JAk#6^#n&Ig
zOzt4eo6Pl<3tN4JFaNR-wWC3?6a?xo?dSt6s^)?C-Jr@8)BRDn9dPXeT0jaxoBu<U
z1STZdG<n+k`)vLJEg>)<&2yONv=aHOTj~fW09ku#{_^jN3pfS^n01EtdfV9~X!+#G
z0Niv<liOAP$SF%TsgRmhcgaJ0b{8V*vpl^vUAo5h;XC6CCFSo5Or9S8LhVt%2J)SA
za=n$LwBMx&Ajr<+5yBzz18#|WE7R{7^ZKX0UEH_(bs|acafTn_{y8LMo^TgnnpZcj
zZuF+pZ7@V>Hivw9(~NOqd=pr@G4%WTVA5F`)jEd(L;Yk&8^mMFN0R%Pg}?KM>U9+L
z@w$80dBHm!#eto0kO)%piRnP^L@mB&)GE237_770cwoQBz7_sPH#wuRSVO6yIwx1~
zkUG;k{vvXv{om<b?ZO(Vh8}~P{1`Q%_--_eBOp(1OTyH_joHm=dTwYRjr@u~(9Fig
zzlg)r(lZx*Ry8i>t|~^36-ZUVt(7}S?prjqw|!TBO-g%dPu%>xI|Ej!!jV+Nm6r78
zqoIiExu;}Vga>)XDGeHOuw8gewbxOI#Qlw`2TW}^gJ-4z-Gu(6qdS)?x}H&Vc?&b&
zsW-#&Sy{q|O~>vS&*p!RaGipc!BmC(GI_*y$<vr(Jr_dMsw=XBc+M|~C4bcbGx=Da
zNCaYF+om>IdM;Xn5_vn$8i1!5eg(5aDobT=iC_}Yf=P@pJP^Cbh<oHP=p)9HihazX
z0KAziIE5xjY3Zq)f61K9JN{-YU_oc!>MU};Xcnd%oOMH;s^MefCHJeUpzm+JGk!H)
zmqv%#3z{*F$Z;uZ|D<vFa0E9^4vK5iN^iAHgrV~JAxoym_)JFTtlg74G9UBD0cAC8
z=P__l&{WscbRoml^^tp8F=|=NA<41R+}OyN;v}8P>t_f`d1@w<zG6NUcTF`?uDujY
zbZYe@%#p^`PPO|0ce>i}_i(~-t3mXTs-o(?*F4i72iCspNOwxdwFbdj$y1LN&(nUU
zp6-Ru$(l2+(QzWF8A7zP<o3Kb5FcB=5zH4Ar{*bdVu%FG1Kf~ltkXYRH=T1D)Au(6
zGjm4TUw}EGj1uLZTftcEQ1&O*;EnVMabx31n}z!98rar1(i@kvw&IpgW@S;$Q*DV>
zZ1wb!FbCsD!>l#6kOhCS-zH|2;iUWDjjj5<C^EJiDYzf`6yT}QzyxyA+NzQIu4}eg
z<9B`HlUac)5o?3<7Yd)1v$3W23{`xI5=O%VUyT@LpfG3ROQ{i2n}8Sy<F%2Mb3O(*
zgRgb>EoRMaXg<#jnvlEnCYjU#`sEvGHO5qMvLQl@5IFDoWd6`&04IM&WI_H%nA5nk
zpI;#wn7|D>=tZx_4~XFqiB_)~fG1W%YM<dF6L|vl?7yU!d~KTtpY%MrdpYHNuQAh>
z^@3fb{~Y^KxZDrAcs?hd$zH3QEs#@}N^G0H18FN{{Tk2IBFIlU^RD5ZG7vb0y3RNm
zRMmg{4s^im<F7BZjs4e@_-H{^Gi7f_Vdt7*KW7F~F85kmmsV<n7X6(QxF%Mf($~dm
zBh(!J!VTIaE=Z@6%3MQUy(i2ccGRZIXi~t%_21hQ#LqRKVo6ZDY9F!!NL2F(EIbv4
zcgQvdw+LS|;Xf<Q+<mn(vxY40$t9PZBhx8gJ?awS#=z^#i!>OM9(GW4uBFr~Gc$Qd
zFZ-F8Av0G|O7l}6Ii10a!kL!@6|2pGICn-N`?`P7&X6?gH(&anT~yRz`u#y0-5`Hb
zxyP8^dK7(4-HCEMz@)F_{X5~`@VZEp?TtX{qbE4w*O*hc=(x`{MFpcdED-Lgq)BbF
zL|f|S)WN4p@wniisyM(yi?)w4uA~ckm@zUYDjL?#hEPioDN}nuyxt%b!O`*wV!OXB
zlG=FESI9L*;!oUiS~H0?wS2sV3V=9dDp*f*G!@Y%!RDe~TrbuKFv{SyJtMs%F0r2h
z@i7Q{4O5p5cAfyo_=2*n*vE`okU;4GmbBsRINcUc=@d`PKdqan2Zb1B5bb|P$pcU%
z9I`RxQeX?VqxTm|RKV=dX~$rOOD}?6iM4&{EXd7zwyDA)O~ifi^~4UVJ@RVJHu?L_
z;2!1>+0Qwzm~)uE-7|b#MPl+AW9skQ2M2p2ae0SoLs<_z*11h>>e8&N6L14GQ8mbc
z^*A~4%Qbv6L|;ntSU!pUP^``$%)eIxDw*7ajpBW_-5yc`Hts!+eV`aGLV^><yJGPa
zo(gryyGsC?)@HN<y*CWW=<K(?s-_Df69FcuqJ(P%<Rw@|K3|;;s0I(WzJ@Fg=-<?}
zR<cM>KGr@3m!?WBzT6>cSH?OZjwbTEzM8n*`;hV1Or(Isl0o5@*kkYcrkSrwy(I>+
z2A{a5*gZRqpVssZnHLic3#{#9`^bP|c}iCAOH79<>r%qZ<H)iT!ISi|N%{b52bk-7
z7$u`F%}2mp&zqk=oL};nKLy#{PlwxE#*?8V%BgO)-Uwk6Fn#rG;>UQ>F;=19Evt-M
z5o+C>E}6Sjc!rZZ*umpmGH6X|c!wFEKE~=Sr_`U|5z^&>8IR`1`diUTS3v6@eB_>6
z+ku(Xm4P9&eZODHAWbE&>&*7<^yxvYKMs-mj!5*Ed?QW~z-41l0%wOYiUaNh^1(z1
zznp*(`9-`!1j3!FF17=9DV*WbwaTh?)0e1AII{b58?Kb@u_?|PB!GU~7aIjw_Cfjr
zKor0)YNngqP*Z`j^(a*59LAFluwRRkM+(>H5j{;KCe_RU7J87HI0csLD%6UAMC>XJ
z8(ved=q^mFqzbdLK?!ILR15m1`ih?51o12X?~{bEWX?WIQ~wgy8)@9*%F)s=@zW&l
z=I=^IJel=$Pgk<7J%c(FfdHQ~(*~>}T7%HR%m9hMDBi<QAA@L?HoM6m7wxr)u)?GF
zM`YRy5uEBBHUw3VuWt{bX&-MZCuYTuTF?X7;X|KmXbaT%Mvdtf@$rCD<U(M3W(I|%
zIdU7v0s(>_#&|1K${~+2b%Vr78%UXIbX*7nQE%CH=J~64hifms->g_t2Sp*5I&_hm
zj{pAFBA5#Ek5R2dmHQe9!6d+YE0&an-m$>({99b0@&k_4bBt@W)5jn-W$F00DJv4z
zxoeg(;|N5aKcM75Xx1#VL^ukBm(lCx7G}sx3E&<h1y)M6FC@|_y~LHJQ2THjdz+e<
z_$@xsxgm9yl4Xmc=rnQH=t(V9_R<m89DB*fAwe|7ulJmZ?nL>Rs5=10-S;ODhk3F;
zZ+{Z^odG${LXaP;nPKs=p7KQd4Sjl$QO6f$^91nM{`B-Z_;l>;YU(SK?7FgI)+Bc9
zYazsYhbcC=2=-@4A^ctpamEN)2O9>&THZc?cS<}}yRL8Q85(64Z+LlR1euZcaI*<b
z;3h6t0IU;>6Cl5uP}Vo0IwRa^+S9i9&I#OK6jYOxj(Nk8!_os(GiGd{C3e+(XTb2e
zlftHm2$70;I)xuGCCstWTkhzv=x;cx(|nx&yN%Tn^{Uq4sgud5&p*M}_q21yTG4dl
zpYjA9y;wB5V;05;X1HMB-tw^axU6X|nH-Kubojq^JiGi{5oX3w)aTmMAoC@qLt*EB
z$6aFVM9ON%aQ?;XEVn0l{N+@6(*k@)yfsw3QOI$EmW~$izMs&eI%mzXQ`B2V-XUYW
zLnuLZ0Zjxd$AOztDCm~x%<8-7Ev%*D0wtl}BAR~Nk%=eMFRG@TDD#@&mWUPiKv4xB
zN4Fd?(NdY%d5oSd{4oLc?A@=`{Cl2Br67I$e|Kpq$CP!)4G9ggwm*+6PFz5ytuw^r
z_2}pV^$O;?uzO8#c?-{y7@8($PoDB+Fn=u8rSy@L%?V9g{#t)eKK1Monnk*kJ<30h
zgV4+_)x2)5>zk%oo93URLBL&_mT=7oW_LuK&F(b%E(<fwlHVt-cl*QK-Y0D~6))c-
zKxTah?P8iTDt#iqN`eA^zlrlKUHA1C*{b&cp>@@WC%$x|`DwlSWNoqCmIF13?igLO
zO+Q0mRy?BOPPlA9g&=d}paz-9M$vm*)5bu?00I<TjoTs5w;V(MY{yehT-#Q>-y}7v
zM;DJ&C+>U!W>EVrr{<FRdFr_#?Yvj_p^20q>NOQ=c1Fg5LFI4mU-$vU!1%YFoFqZv
zsq1^TT80eeT^Hz)%5Zsa4mJ28Ef;-*svgUItZgJ?`U40PCa25{E{8LNXLW6ma+qcq
z3CID08B{fLJRc3eaR8Ez=S%~nTn=C?7|Hh|H8MN`V81rUm!dT??8Gy>hGhbQ)Jl-F
zHV`lPsV<>~!3=pxf4nXebwCTD_*mr@5^d}L2`STrW_c_4Pjq=Mztujp<z{2ORlOR&
z6%BZRfrzRtoL+mc%q$^mA<dyy1ZI|VaKp}0(J0OcI|~TCXBwNT_#o$`9m_mASLJH2
z@pQ$Xbu1u0&x9Khu;?G<fBap!h_LV0G2u#{b_hwT{Sma}9Os@a>|0Y}o-QimDqHDy
zq*A{}tfdINrAGuM1!x5Q-pFtWMczArdt+Yp1)!SqUEMXDxkJur?35Mq!J7BUq!$tw
zDEJF`d@trID*l8rj0kp$N$(;?ot^~Da>-sl4AE`<kM7cAYPKQa;z9h{zZL}t&}24K
z1Hd1pm_PdII7GkE6DxEm_17ZeVmT`5fN8{}p!j28sEpVN()wHuwB1l;#1t_a94-^J
ztPmJdh+&lS`Q5MO`!Tx5>&=vFE%JQU+}Y=AGK?1hX+D7T#r22Zt=4LS-Yi*7^pUFZ
z-)|j{^J3SNlwR2JIx;z#Oxicje4JJx&+_o$CZF}nb#s1q@WDKs+GC`kndb0lI?gTS
zhgs^;mw7|8Lw%lywT-)VaYaTAaUDA>MYiOfc1?eL#euahKeCi1Z<K=HoDY)h{@(<D
z+X8-N($<k%neFv;NYY~6;ThEz6DbjoRP8<183++g(gEurl@Y)|&m9}(6waCZTcQ_d
zSRn$X52Pn*w)}mJ@4V_t-!Fa7NsY~}vkm9L21XVb_>(>3L5bk$`nG7jl<Q~DmbYc!
zbO9&Ni=#FjD-bHo1Wt~0q_J<d9OC&{?bGc=sj7F&L^(ke5Q2KLtFRQvpj_z=oJ2@Z
z>FC1FvJUO~h77n$Fawu`N>LmD7(g^nOh~9^GUQ9Sen$Snmo=U64M9L&xjnE3dAW=S
z#z$L3@+7^!5F@Tfr~TcW&kHoWu4%_JL!*u!hrgv1MdH-VHc0I^fH%SKQyV5meji0O
zHwk$3t@{cuw%$EbjJ>+n0Iz>EZoXJ)O_Uxg5qyeLY<v}~4SQ8%FBbYSI63w`2|=so
zT<&zn*8UY&C8_m%KMUh;W8I2V$3FFsuS+k#^?(l3wU?9piB=dFidY9e|BY~VSyFWx
zN>S)Uw|B#L7Q8w72r?}*eOa|H*1Ge$g=IL&(o5%&TGq?%&a<QpCafs`NL|T3ww%c1
zPK~*5RNfj@{8ena`3ow|C|2k}nSMPjGnSN2%K0qDj+F}r%0`Om%6*6eW}EADG2PrM
zFB?QXb3&;TnhbnKvn;}?k0Ojxca$S0^Tb38wJ{)=m08eo)}KH6t&_09;WCQPPC%Ch
zWSk+&R+|z(TMYAIOv#4xT{C&mh@qbvV>?QNpstwhltdpFDT@IEVrZ8twT9qf1%Y$=
z0%(DM3H`hTdWjCY4e1CIw>W{l85O}(Zlul`310*p$Btfq&Wr`fp)Y}|C05B#AgfoU
zT;p<wET=*eq@{;RA)D=HfL<H|LbxYPe^wJSDTsjY%Uk1<>-+1WW!vsfb0?crPI?zk
z-%~uj#kYW>2~=Umz>Q+IlO^Y$Lce*&p!_g?1N}b){cwN2l#8G`B^!NN8^}~zwZ9G(
zz|#6{vfG<I#o|jPmVB)?g+xjR6HmK|;GRRefbTbvtqGXw{b~DRb)7{?wmrXi4ChH|
z1vpIX_0qD7=1J^-4payn;->&$%vBLHs0HfBnw{gD@6YK-#GYzx$LW3fIZKKj=#04M
z;-qQ5fFDPj8%$50!daZ<YHS?DEQfsoh6#l_PzaTB{lw{0?Y_<5Gmb`efy^mchkHF*
zBd;F*c^7UbuC$|EisdQJ$`VQB=<V@;bjUm4c_@CiHnAWSKp0*;S7mAn`%^x?)iDX7
z2TPOT8qvFlGZAQGsfd*Ir6&swA>cFb+~OR6P)WAWtPD?*iFheBNX7pxtO(Ub2wT<h
z%%HcTKqCa&-!tpxKPMr{{32hy5TAM4JV5qnfU??f1dt%j{Apd_!ePpqrvC%otb;&f
zFbQ%2u6$KLu^5L@ct!*IR-(WIWZObxDqOXobc^-J5p`p&c8XLo6A4fRaUONiZbXZq
z^-Cg^#&ttCDUcmifcUKv`H(-sTQGGUd$gZin7JUZJLOFQTwZHBMF8-){$#EQFriYz
z5kn(uzJO;zsKKR3Wj{PW!HNzX_a|5`Ulc^cEe+;HY|dISan=(-<WdwS?~L-e_}v9s
z<0M|a^E61Pd})43DO3bYC)J|}b|5I@a~OC)L6{1lF#+2H)&NzFoZHz1T&171{xCJl
zc3g;5@#aYjZ>C<a5!#$>jh3J8ALjY<lUb4;n%&$#LzCWJmFIyJjQ_-bN9Po&e?s>u
z3YeseK)y6{xs>N%vdMj;T%qr-2^c6Yn2#oCV&fuoFGz7D<vRC<V|l@AQgHJMqpDyq
zwF?08KqK}y{~vUb=5F(hFBGfa$0jE;{~$I26Oe>r0*T2=uj0qCms*Nedl~HHV0wcE
z+_!~j+f1`mjL+$q3}g-7CA@gkSvSzgGGtJ@_HP`n3iyiWj$!-Oiv*(iEx?05VGxIu
z1QS-k6a#~OsYz!%7|8*#fSM5+01`@hh)pTfksc)B9aDf%FEQJeeR_nE63y;N6Nz?=
zWxDwvHQJg+fu_R*dIAfU#O-4liHT<r5#`ov0yW{r%=Q8Gqwo-Q#T7}4=GT6u&hqHm
zW!f(Vj5ePI`1vq6hR@<)K4n^t=yPBRyP&=9j=SH)JL@yw`K3tc-S8}>nfaN!SR!VM
z(LizoChr)Z6?B5T&|mPG9Qq!!jUCoC$1T;yyK<cQvs9tV!X<ZueXx{=3yB;v)G;nM
zaJ05+=#8#^;;YJ9fjO<J##fOWqNl4ASa4Z1w5Sdu*w;Fh(iP2@ZOF3Ayv1d7`jjkJ
z#dZR711m}c8>UUBI0?ppL-drLL$ObZoVaz?Du+yMW3^)-aS(`zLWwcg;XpYT(F!KQ
z>Fq@h0xIP&n7e}uz;$}5)M$k85gFnD!VwnZZ*rPF{H63~6}&@|E}^zA+WcRzbnyDO
zpo)m-DoBEeaZHLy(oP3~!~4E7Y6^_JKMoBb?1n&*A)P`(3DzR7xbTl8^mY#Jvn^(B
zk<7MtlP;}2UlMQ9SZTL57B*~c;P_laMBq}LN}7UCrC$j5MAph)Lm2H0!N9br1QO*S
zBBbyP!~jKg5KM@MM#7u`Q$WoE7XdgIwB@%H2Xug?guq{{!7T3#qO+jJvLxE|sjmW`
zWErA*qwBO6ABf#wAimUu-Z2}DVMQV%5j#fZDx}u&ln0JEMF1aMs@FOBx)YeQvsMW+
zU*{~>Il7Il3({XSgGnH#?9@)A%GM1WAP9&+(OT5Uzv;W@Hp#6Gb7pm6)MPKZMO5+d
zO<}y9vdBY%iaEuk0z@%Lz=K>9iI?GE1i*CLf2IL9WY{`6XZx$eJ-!}63}K<-xP(pW
zq1k=F*>L{%?e1T>g`2vf&)GIbB)ZaEn0kul$mhnejLpCgEzBwoiRe2AQ{lqgWSiqa
zc<fw|rZGEC41@QC?a_5OUX5wvSW)$HVwREZPzp-@vnUM5Ffs8HD0$Wvg-3g7M@OJM
z(hC`Lj94sZ3fU7$mSSX*W0iBzLt`n@Gq7$XR3z-?KnT?Gcd=5@qqWkee;`GEkVPY%
z8D5+>tHB(uDS|fRR_N&zI!t)mu&#+9)S_B}jHH2RB%eShPf@OFqyo$mS`ahf4Z<D~
z)SRDIO_;pAWdFgzN|l;&7Z3YVJ<eG_WZYYpKuDfsl$Np%<-$nG2dq)KkyO#|R5-!Y
zDZt)+%?M3F`WZ$uK?$iojy@=zO{I4^FUqO~$NG#|Tgrd}tgsZ6<n&DZ5%5#$h-}_<
z!XuYmlqUy|UtIhs##UHN`VZPV$!%L>Q$nS$Tvbk=mHxRT^c(-etDB=s3}Qz<S{%HP
zJ#q@pW4o0oI0OQJVM4KBYeO~!46zvb^Ib81FQZ@$I*TUk1kx}pELao>27^+b&N4x%
z{L=DOF6>;4uV>H}X=ka?!p*Fb(sy2E#O^EurE#R?pC=t4$g;1K_4W9uxB#<iMM)re
z?C<S&0Td?m%0_$_FABh?u<?9r;Z3*nElNjO2DwjW!H`o06ZAC6?1=s5Pzn}#`HKRW
zqJa*8xQ;a<@!mvWUGL6tjMZRpx!`p|mY4_cjwP68h9fFe;UH+7G%C~)PQollu7WgT
zuP$<gkT4cANP)lKIBnZJ9H#Be?xLdVWY7Z<BI`(3Ml~`Wsx6O^w9Sn!227hNEs}2I
zQX<c3kSgCv)P)XaGxU=|++RPd-^ku616qd#(O<n^LH(kVRPdc&`fw(-Fk2E5w=gIk
zfoA>`Mo9=jph8O)NaDIPS%3w?QhP~BI+<QHe*_xNhe0iXke5hbxR%{Ziv!YdB&{Dw
zM1BF*1-M23X*kgTusGv(P5yNaet<8u$|{~f$Of<xYAmE2t+*98h!DU?l99BUkrD32
zi-CdY84zd~;l9ryJxnWGdYri}3F^t;Y={b-Ddjf52RO^t8dQEuAyHQPX6+2NXsOwV
z!RAQXapgWLezT{=F3zFm1WMV|53m6EFv{q1A@`pwEd}t<uS1hozzdWuP!s_GBm9)Y
zJt%D8XU^N+LSO%UJN>$|RD5?BqFTX35mne1A?Gj#5fuo=DuJC}YG4j3U;B%C4jc4D
z%h$26XPc2|Wh3+ungSt1J@m=G)ZSSyH0!CEz=g!y^1$u$g1%nX#`rQ5<}2L#oz1vJ
z|1h`2C2r+_&33-}V24<ybk%YZ<Vh>sXjYC(!@jHWu$gW&--w|L;QW-#pdnv~A{{}I
zx+*I|U*SW2F*yhrlu?+Ql29%rEex8U63QLo>HWsd#6FhEJaF9GPta|(JGoXIna_=g
z^`kgIk{tlq_(IRwzXQt=@Fls>KPL#4x!-^%b?$)D(dp^N2W|}oP+P0u78sSPEW5Vl
zL)M@{#wcl#znTDFgz!wm&j1+=$t_mg8Nr#k84xSc7VFPC!Kb6{YL1b8a4I)^`rwr(
zzR{MJI|b>|#b))C=7j3+cEC0q*oU?$x=A{K{XFnl_Lmt<%j(vw6$1<w>~RuG22rK^
z`-g|Ayj`h4a&&gx_3$XXOrW*_Q@sO_na+7AI8Tn9Q8bpsbinmIH#aR)+9wpidlQ<1
zn~D#xc2pmGW0N0&7a!KOKLx@sWM>qFVBY)idTN6hGMYE9R^Mtqua2y1HRw#~X5TVP
zauawFG6)(;iw{H<P-G43uocBb!UqOF(wXmnR_3lT&R5LQ)((YpWI(m)da+i%g7!d5
zMa6;b%%l)cJJUMPlJSQ9c0<4K<C3E6I&0KO^^$;AxHEJ^eb5L8E0htjIgNlMoDZ@6
zDu+jY$G|rLwkCY>ZXYxFr}KtxT~5*i=L2x@6C7I_{_e>!L-BdU=ichAUDrCOJE$D_
z3Y7w|7$L#6N3_vUoILy6gNay}`5i!znZWrG$Vc5f%$>I_4Z;IsJ4V7+H_ZV`vS(6b
zJN7Qu0-~N8&0y$qQGZ_tmMPZ2_MK0xJ|YKP%)P<=K(&a(<Ka%btUl&^VE^RI-EYVI
zO-1&w8;7MrK(E^Rd#~gM>Y-sL)uoxaCf>oS5PtEi=sZ8A3BQL|ve$hHduJ3QSs>jm
z4n2((o@WJ?b{{}LKmZSh9msE_Gg^Kh-Sv{?!qFXHpQBgh!{*)_lLr)Xou*GT7oV2h
zJVHoM7$&SKWCE~LHdUa@iXS_(e>Lh3bOa>6pQ>!%<i~p#6G6qc_4E2c-dmtTBR}Yr
z{X&mR8+BDx&>Dq};@(s-`)(mh=JseM?&;;GNGRzzEm?Dbw}h=#RGr)jF{n%lUhq|k
z0oWZyOr#`g6kwO2oUESlouIgbD~|_5-T%s<*A=(31PgLvf$E2z&orS{Eu;Ou3xPxz
zlaw|fn-J=FsLjE|7sGeKAm#9(W8?Qc(ER-0i@I9M3lQ^XR=7{8WW;lwwt=T4`>y(L
zW4O5}T%f%!h#WIZ(vd4xQ|joi)l15E1h`xvCAcQ2`^(Bp?=$XjCvCE>XC#$zXsW;p
z?HTy9?JMTzeis$PA~l(uB(?Obp2|LS(;*~op2x$Nr>4(~L<dN@4jmC&5ci0TvR94_
zvs*L)D6Y5@dmo}!k;Y)la9_xyG=QcZk<H>~ay?AGrxx(9CjgqoJj#L@@#ojT?;Z{9
zvnq;EJpl}SfL%lkPgUKE->ma<FU;3fl?=gN^D@W<b6lBQh{1D_zZb4y#KE^(#{rD8
zw%BMMq(0yYV6n8c)MNziIz}h%m6a|Icn0rb^t9geZ`o;$wAB;KvW4WZ?NO@#Q$mo(
zMgz>MQbwMef^*<Y`Cj%fLqnQ2q$X!(^K$8*If_byABF1+u9+LB13f%`kBzE|$MM1Y
zB8HU#uN<up5F3JFD`YoArsRi-rrBgTAe@KMSx=8`)pRN&$(Wb;n2rbqSFQm`+WYbE
z;>g7&Jae$f`DMNsAgAv5K+Rolu)I(!j2xBIPbDTW@?)3xc4h0cWvJ!O*{1W|(vRcE
zkL1{0LY?Az4RhN+Za#(YcKbw9+PnI(I2Z2O{B^s<eK>h{Ga8H&QsSm?%eaW228ekk
zqQwSLL0~`SMIdP@=)F-MZ;GR<%<0$Sz4YsT{rWk&_Rg&$rR*j^I&67S&sHi{aG#Ft
zyz8GB=^)Z#X6ZA;>LrmJPbv|PaVRtP)LFERmvX4yN0YQvSm((z6o-qn)giSX6K2}W
z0uloXl4c!tN>BJfSO@Atq^GJXZIfOZn*jnOkOK=b>lE35g)pg9xY$E6@?9x>m4{1?
zRbe;O%m~GOQ*;C5`PW`AjCb$*kU}$`L5niz0Y(=%Nty`OFA-lN&Z)#Oh2Z02A5q`8
z&WKPBe+C@Dx#tvYq+}=wlD`_VnFzdPOa$?fkIWhRK}FzzEvb^_JrsT~6kBe2&nRMf
z|88gL5BaMrJvt9w3f(6;$%+NmFJQ^C5)*4<&oiWv(4)+FcR40s<z@J`>ExF4L9X}V
z-2+$OQDo4;cs&PQ|Ln<H%pTDuHFRDJPPNLQtnO1%tQPE^{l{6$_R&eu$V(=bz$1s`
z{;T7&-;NGATssUXQbe?z&fOm@`HU#>R3o`OphP6mtJi>P@rt+9^~TJ!m(^I{P{4aW
z3^_D02ch4U2w4Cy1BNBUJQT8v{H%I78wJ>&{hZ`?LEyDJ!YK0si+Vu-Q%2bEH#F2Q
z4*df~8Gwv5qXvP7x(hLCouT$eeK@DPHF)9&P|Ze+ao*A?*&!W9O-9=qVN3Jh^*jJ>
zM~JX@V6T=sw4qgC<s2P}(I-4QlMRg1K+2Gg=f8KA|Fyn)o@;1%Yu#frUQ@X0=1{=p
zpn2XohBL$7^?hb#^LSfnFiJ)0Uwhz*cWY`>-fD~GDqYaw(&O+=Lm#mZo(0TxFktk6
z!QJQ>`fqFbuQDlK^~i{0RU`N{Z?4ZbN~x3GZ$lV3^C`ZzI<2u2-_WJRa2)Y?rfmbB
zQ|M15n*s+(*CfoeaS>$pfDgDd+#h^~T;qm_0@qvYK*_`WP!L(VP;e?Gr0yw)x+$iL
zGvC&@^w|q6uT;i(Jz<hCNv%#`rt*L&sB&>GvI9_K%vS}#s#ttE-xN^_ixnm|0~JB-
zhSq?UU9EON=OHS(U5_VQ=R8&l0z)=|zQ`Ry9a^GR%094%B7Ay-_bBbnsLkTC(UP0T
z*vu`_^R}C#$IJf2GwJU)=lAQUEim%k_i*}t0V`vm)^ACEXB$upG*Pw<&F7Sq?k<J2
zt;xLZXZJ;|<&5v&rjO&I|KiF|yAsie&6+axLFqf6S?abN=q!WO&c5@}Nt1sEAPAl<
zo`O6*a|0Z~8!we2ds$f`>BHyh7sBSUJ*^YoHgMH;cq@6Kz3hCwkAs$>afFA)HS*<W
zL-uT|KXs4>=Ec)t>X>#6+zZ9#;I--rt)7YVBc9P<)<3G6Ka+dp>5oq)`S3TOUrbSH
z5rWq52GT1ie!)J2mg1&|<_*Q{6iTql%<#i^HUkxQGLn*5>k%Vhp@zv=R9PNq5IrBd
zEsO`!2eZ4%kiW`ZiFjkqDaCBETdW&$=OVd-LFG606G6LQ_Y8)YuS3SET2-I7MCb~g
zQd=wWr;gBtXT6#pbl8)6{}V+L9uRnccXt=2`fP(29T~*g$rNX-lYhw|G`7Utq)NZF
zm?T_0xn+L)v*w#oliIqkV7aq;rhd#<>VNBTW`)(&)oN<Pwa{#zSJDz>x0)oCDS91I
zgLkzPpH}{C8{`INp7R<eG~RW4Sm_r#av7BV(V4}c2b8M&O&*;6NkEP&0&A+#h#!Rn
zva7;Ag;$lUmPmX6AC;L@KP8!hYLpjIpklx$as&(KVk}F&jn^nv2B<q>_AFO^-j*E!
zp*EnLRJR@gmhtIG2P!cwc!rOBxjxji<Yf$|;CfF+v5Li;w)(SSPx%dt6mWX`wN#w$
z6qY1)@y_4;!4`atK-b=<kMud|Pq)m!x+*?REj^9(F>!JM=dXghwwfbAUbveZFTYcc
zV1v<4l$Wls$Nj0W7iQNu_}uRCgpGyl-LS;-)2p1<`jJ_hOY3{fM&iK};Yz$3vgd}w
ztmH|i#BSS@)*{&Ndw=k2A@-XppbMmhodyI$)&FZS>KP`221>$z@l<9bcMF-ke@?Pz
z{jyK8fEY>H;Y%$%Dvig5J2S?l(wl$z82|fDYc3L7bIsf2x#iULWL`pb!pG)0Uj|zM
zH8S(pQk&oviT?p<kGlr(zO7)h5KmI2w&vlty1)mSPmlOF|F*S~Grs5qd{T7P($qHR
z{!nx;e4E6MPyI=0p^CN$H&a}|F$a6zz;!N_-tLRNi_JvBEPk7a`-t!@VGqR)rSvV1
znF^2b!iS(DkL>{qKtSYOw|lP@hVOa{4PjCD-ZSkwTNGEn`F>22Oz`lxhm1W=u-kO{
zr@Q{@U}}loM_=vc4#~POyy&y@+l%=<vRvd_p_%HHp8g3v4cJb0YN>5*^<m93^Bkle
zIPo;I^lzo*!W-s=?dm=*-4LPg7(>G}b~MV@BFCFGLOm?k8K2_2I8|DWQ));AooW_j
ze&uYkSTmJX1Z>;PFdIqjhW)v${4_Yr#4}a_>&J;!c6s)qE4Jf~VO9E^VReB*RL$UY
z<KOpyuB1|nIdx`Hb3x0_?NNUYQ6oOa*uzJ9IToh=4ojpx+vVHwdHg36PUmg?>d8N5
zb|zzolZ@8YRj3M^_Gb=djw*v{jj7q>((Cz~aK0gi+_zZiJm@UT<=8bs*ztLY1q&c|
zebIwq+5|OFrkacfGvg@_8B~oDsK?<NPT|E0xZhL~C)(On&vnkpcMOOy-VYme3xgSM
zUVZ!ayyQM0zp42Qw<epD?qOGG8fB%w0j?Sl)0bzd!6pRr@^g}tuaMu>RT{qE*w_|m
z+3A#+6>D6~oL|&bQ(S$Nf{YOPV1Fzl^L1j^AI~=g03%iO%$R=}P$UyAt2V9rdHPlj
zHTYIL@H5x&>T`-eaO(j$huyMi5Ik=QKe;hSK(ybpWP*98vYed13TQd6i2y^lNiC>1
zLJa(jrp$tIpVzn2cT!<25+)+;?5JO2Rs~_#RkE#Ej^LQRUAHI(=mpxMyn#Y1iLEar
zm_)y8hz10h{hT!HW8&dp(`s=TCf4VX*Q<T%ej@U8m;65Dv+_Q#ofCR={eGSbXD~Tr
zkm3=xk)bsk30Y~!iPtj`xhH0UJY-W52||jTR+K8_VA}|y2pM8-y)kMr;(LjCQuapU
zu9lXq)vuX6z3~O-IU(U%jH~LVI8p+Jy^U<|it2V-ovo8J_}_EIH7S*Xc7Wk0WjhlE
zE(iq2Tc@rCbytb5A71RSv)qlGQExIMTBID@8Ya0GIudc`Qn8Cecf=F01j*Xy>!{^Q
zzv+Kjl4O}|Fon1jw>DdsHPkp}65<+(jPg?<#3iY99Vq*MB692ByE~Z(E`Ct_b2-2C
zOUy#)E0GaeA15CxwSK=qr2n0^+d`5j*Vp*!>@G>ji%ed7S&~ZrcaMKps`RU0w@gn3
z9L@I>4u1F-!GxG|79#lyO~)w<YaZU(Ood8WmyY%*^Sp4KdwcuNx^x5&>3H+ywm(QO
zzRH%8<_}H0KuBiG2G{&}k+V-0&5%Ri*Ct#%+_|sc8vBv>Vp20jVKI?8tTz}hpOTd-
z8Cps*=5<OU=2J{`Uc6=}QlTZ*yO~EsL!QX%${+))J;DrfV5zqJ^o%fu8r!k?iJ*{f
z^dgq&ek4p^H}QfS8rl47#>sGvgK3&#S;X+?kR*0f#4H!oHqWv$$z$e%pV8$e>I(e5
z^41L&1)~t6v;_0E_(*GVQZ)zm;`3Ikie{y$AzAdOzD?S-0FyKRM1gepi14U~{Ywpq
zPN`2dvn4N-M)E$kh{L))<<d8O6AteYlzYV;1r0k#?nfTXLFvJ{LRE21gJ&zj^yCwL
zC+@kUQV&rWOZU0^SA1PIk<4QXg9dtUz>~s_U%iv3)XmRP5LPV43fY_q3|uGb+xA`~
z9_K?{AE0MY3Y)yzd9%{cP%~tFI4Y~pi$^fBT3h%xB~9r!;l)+t2ZwlON|vrS7&*~I
z*iQeRvx#wW6roE|#iDabd-}8wt2sNtIoRpbNs=1=zoCXTvP|NKXQUZl348$ul>suy
z15}llR<_?9A(4W6bu<q2g2CTlHI2mD-LaRApL>xVovUXq?yH?8yaG<80<z&|#I71a
z3W=hM?+cMjXUFp8+yw`~nW~OAsS>KH17w1meilYQHOp2l)-xMWNhJ2hlChfrw`X1T
zzO?U_mbtbKImt=ey9S*sa3W^Nu&aPMi_RZE#I%Y1qB-ExT$k^sTAeUmA@a+WM0yd;
zf1Zm!!!eUFlsW2m=q<i_5b;k$@nPyG;Y4Ker>?OWxC0s55Dl<Gj+wUi1W*J4RDeV%
zJaW|GKL04~V}5kPIM(dz)hwG29E*N_&?OO)WfY-2e~KNUoqt=BnReK#+Ln0pC@1mx
zN&0vJ$wPYqNmZm^vtr?&0#q&1V-A!LI2~nbu{(O|lPQ&gK&zNoW<|h~(q^3tes_rp
z4bi`E5AUgfwQm^)Rgut8;+5WwquYsvlm%}_;}11etR)LurV<gFo)4SrUL<LRQo5Wk
z#4=hw2eT80jJj9<^cre>HTvrHj|ijW2=o`mNl2a8OotZRSLsI1&m@<JUS+@Wy~%56
zLSpT?=lJ+wFIzd+J1V*Sbtf`&*UET!3`5ZvhD=F|evV+qpp(+f6fctNpwGDFMbG{*
zrYy~cpK0dxG7OVVRabFQfJ$QtZ(Jg{M{yQC$`Acf<0Ow*_ZyDEWyxbqT*5cZF2+pk
zXi2K>y4t-{Co?jYe(+X3(M||??bqvDjwaOBmpFIFWY$k6#NG~7JezyQMBQQTg=@tA
z9P)`G&MM@)epMar=keshGMWB&$@rr37G3z|9}<K!f0wEjCKbI_@w4}#I8nd1)x~&j
z&pX3rJYAnRs&lC_l}8P}rfxbp-IYkw|IkgQpo}iWe|EgLDc#;~Y{lJaA7bNT+axl3
z>MrNCN34f~YQq%3#NJiy%Pdy`-6C}vxmx+BHcaDmlR@PpJHm#TCE+95UwO>=rBP<<
zlj}`W)!DwJ;4(i!dYCKv0fmk%y~@k1=h=mvM$crnAJP+mdGVUW4&8WPFfN@MX@wRv
zJFz^yz3K3L$tyZMl*{tsM)MU$oX}`v;Bm~ipXy>jf8;!3kEDhK16yKuDO~!w!-gnW
z{)~b#MesgGRV>5b+JZ^ITN$EQ+MA&{Gk^!M3+Kp0auyRU@jQ{0F{i)Gu}!g%m+q_f
zqKopLBzH{iT_F-i=u4^OoDnr9MXU~Q)_(51Z?~eEt&Vj;yPp>h%e;RE(hifTOOd`L
z;t+Qxq~V=fQ|#v(;qkNAYmxK5@D?`r<#N=ypVE{G^;%JEY|&G1q#E$$B8oLn>1kZ4
z!mNIi_YYcR$CYAK-BjANsK-eygr%UBEnp(>qJ(eoYGB6o<I!HMr@N^Im{`bzl#aWq
zplfz!S!0RMkf!CdPoFQai!a=Q5v{%%#ICCYEj#;kE%eZz_)$z>je*;x=ChD-B%1>N
zh;2J|wXS<Wr-q*GXz8CvG~IU@JKJ9lsY|1=8x#+Jrhn@IMYm47k~1Y#c96rCHr8;&
zo|je{`Q{y_rIIONs_0==(4Q9tWs^;OeAez%7xd+Q<DARtzPNo%Z5Z1T!EZG`{O-6H
z<Ye85%xwmMPGfQJqAn@FBCoOz!iB!NG@Wrf&FE(|r`b9w;TMnC%bYy>*xE3oY)R*D
z*1$au)f5o*f;&O{_Un4;LiOy_awU5dO8_0Ou~{0EPrQa`D67m~7XuoAl+^E4|G53c
z!qV?kkMUOd21E^<116A>&S_Zprk(Kf(!+GTiBlG(M0oFvPtgg2JdSdXfxu3x$FD&+
zD*5dm|5WRa8S4SX`ihsmF}>?=n}Jx?LG?lANv?IRKoTBB<1aWiDm%e~cK05c>x-`$
z^(3q3O{(7?u|3fD4>_GXN}-hI)&COhYcav-0j@{y6S87f)j9JcODh|HfBmKW?s>1Q
zQLV}6{{zWDHorPT@F*x}cb~+vFgd<zV9Q+jDxZA&yxV05yV3uo7))Wn6z>Z7W_EDT
zNwqNH!p6RD4-d6n<2P#6T4w*5Cn=(sz~d+aAx@V{rlYCa>*6*t8Nqqu8(?v|<D+ft
zfSpB+a>DDd)~Q%jx0c|jb~e<o1d55O7^cpONnq+2GQok185iyWvo7!vnI?kWNUC(H
zB$@oIwf$Ojxr}-GQE$~g1;fF`3cK_;Q=F*Uwvtsh`R|-p_g&-(f+Fg(&=Ot)5P1Mo
z!wX1nTYTb-J8HpvxFR-2oqZ4jC9;y`PRdD&?&rRbBx)CP93te~0>zdGS445QcwNYl
z?aeOk^1bePr1PnfGK5}@A<oPLb_O~W5NwAEfI$EXDUmaSA7!q(t{V*0yyY%ay<d`4
zFtM^T5@_OS@3;Il#{^t6jv~woRdet{$H97ybg`-K-5bl;q*1CeMcJqE0ji<FX|YID
z6Ot8{@6N19w1vf~RpJx`i{HGo=!Ladt61E~ddr!jj=uI`F(I>QM<6asc#)?-o#&fL
z{6|X9p=f&&9X7Jc*oto`NI+-b2>6l#45F4(QZOx_D<Acw7L;tp{NNM@+hB@IfL4$(
z7-8kgm7V-xP`v}yW%5VKleuV5ymWD(LwN-#uY?+m_R)ly4GxK}wt9{?jyqQ~t{2Js
zdP19(x~{<E|Kd^qlcjFw*?ya*a=EBHF~9yvlw^?Rr#}_r76ny_titt794gf*?o@dx
zZpv0?qAT_`6@P3&*3IA*56O`!ufOcB#D_)2oDx`GMWvnsfB?9u%_`-ZM#gnIoZ5Eb
zx${UnIom{~S^*n?QxG85t>oqejWEaySe6@@tGm2PyKV`4F;ege<tvOfJkk9lFXiuk
zG%5#MD4_8`*Nv3J363Q$Y{pT8Mhi+!ipk8s=r`k{kV3Hvzv-;CXh4cBh*!d`G(sei
zOMbd&gc>jAu3J$9UO~-6zWNYwOoO%0T*w*0feYlshcwCsGF-h1g`I-xIv@<_S{MFn
zVBK8#h`YOb!={hP$`4+wc$ZF<h=@0`O0>x6Aeb=QrmJi9wH*0k_}Fb%8c$@RaRIaV
zaPMtu7D*+=SQcywo9@xOS98rV)fu|0!7U*F?Bnq7ofH@IPO@AexcS~i5_ff%Z9#U~
zeQj8H5|cd&XdeL9tfxWqO#>6K=%Nefp94la-ar?E6zJNBg~fB3r(gAh?++=tI?pkB
z4wNZxP`aik$U4(DscEZl!N+dBw7-AOff*Z@gyIRax~@%a**xw!?%cP+-GdntocwA=
zODH9E22*T>{ONBi$JW^jtCT@2%PIEM(9&9KKN4CSBuU@?u|<)(V#uoHYgoqFprDWm
zQ{kcctlDGfrf1$qIvC1&L)xUfDSs@R<z)lE%$4uZQ9Hc-J@5L$j8n!kI5;>6gM&0Y
z0cJ;|xoBC&uD7Fl8UMTge80OaB*r@ng+hy3d@P=9?84l?p>!s$dC8KwV%q#d+Wijd
z{yzUJkALPn6b~^^Uf!KW9ivuqW|>7=b`2O8e4zxFU{i0PzRuU%{5FfjK^as;DqfH&
zffr;niz&?z7{mx2!iz3kbXNY;P6?b8YJgLKh>k;mNZ+hkxcs`q<2lUJkABF$mh&O1
zs;G=%;-1JU@;ey4iIV0ep1FIy?cDKnb`LxQKq8$)f9=H7i?ORg8^~k0bUJhA7A0<b
zm{IZf_DOH|8&iL50i@tjP7-ewicMQB6)TFhZ&4sg+PLMt1`xq5(p=|jtDv=!@k(DX
z4IY}$w880nQ-*<-DddS%5Ky{KntR!u9%ioE@ZdRTWiObmz2`A&!JZtqR*Vy_M@voG
zJmWoAUg*z$5Mt0?(P5jyx~g5+xbDZYovyJ_AXsI@zH6mrufFn+`_JE+e}Vl*o!!5_
z&pUUh?Xj}ME^?LauHdrJ#n(|s4!mI@cucFO7SCU22I3R?SVIX$lN6GD07Y;Lns%>+
znb#PYKUaR5Pqzi8>w)ii>!07Qa8&G3rEmRFcg^?ntG~-#9t6tO9(bkODFj_QRIPWM
zs~Yd~TJWOhd2l60w13dQe`WvtHD9x>7TThPNXaB;q98l;Y-hDSF%4P!G~yGZXMO!3
zFCM6QF@>2wG=FH~!nt$Hj7bH~P{k@rZ30M1D4bX~tji4M>MnO{&U4GMmTY7g67WF4
z2@+rjk2^)B1+06ZqxZbIJBxwv*Jzt9?;@YbFSHL_6zNnhm&*(l+arY`y%HJ=uD_cH
z`m?W8vh8|>Kv0T~lHFd*%&90oX3IouVYg^oE?OE+AQh!A5fp>fj^mV-10p1;x$vLQ
zQlZAZExfYI#gU}`x1aoCv!sy00P+p>1rSd@P&CBC2lANZ>Omd~Y(J5rL>Vv#%%zxH
z^kgqynSS&HYm=9ie4uft1LG-4!mHpWijK$~yl3FHSo!EL{rmb|uDiI73aV&_%+#7;
zP4!41V~ulPG-GF=^iwX)+zXvLn}8lZ#U!mz8o$iDvhzQ_XQgdPh)`$fbJW#Tx4mas
zOKJR@rEF9J)}pd(1^Oxqk}S3b!Lqi1k>Q+5F%-`!?%X)RvonK3i}NR7IqjnbG!_j6
z=D==DWE$%qg<ZJVJ#|r+qV>9)@FfQ^=+YpR&MTXN<}-=YlYHMY`F!6^cV4#B9n&MN
znIOQ;X{c)rFf!^ToD0v!4NFTCS5H?xe@Fn$#tp}Let-J;y1iAGX{FAl5Lz%~nUFfp
zFjY21b51n-c*L;6=O{1*DSETr1+B{r6~?%%RM6vk5tn%2Gtf+x6@8u8>WDZ!huS^i
zY<+cuXcr!!SC4EZ!(838y4S#~v65$ecgbZt$LKd&oK7-(S>%<sUzv|&p81@K*XC-V
zh-=c|9ILXkF4+5J-}bPjW26N`($3wJd!gf0Y}qF<kmSQlAQf5)#T+uKGwT3Ort=_|
zL>D&C?Q94OJ4*x5gXDr_f?P`_&`$6v0CRRkR1l{uqL5q4*5t0B!ZhdpD8tJb?xM4}
zB@%BK!Y|g<a^mzcUp>6WME9YkqSPA3)>l%+E8}Ow3;M*igXPO(!T=gUp<T?(ll=Tj
zU0nUEED>8XrVQ~IPiM1e$v~r6(vCAk&IMJ6B}v3sB`7YFMDL1afdsuPic%?)#ZyTJ
z1)5VSK_fwxS`O4fR!)*t?G?0|4TqFTruB*OOCn3+RE0L22~GWza#qfwr?#DmN!s#i
zj5Ex57k&ha8>4C695e7uthg5UnIu-K?JBT0RdrQ+jc?{7$PLTA5GTeEC6Ehl<U#Mg
zI=<bO#8sI!PdW52Wb8hgi56>O?QF=>NHe9PR2p-@LlI+$i_EFV3LF&13RS&m+$Vf+
zgqnkIT2_n1ba;YNZ4r$#2s<h_u_N0nYL$`f4-8|a6#xWF^M!#`#OaA&S!6qnV>j%G
zPbv&6(jL+v&ie@xFu`4|Y}#%%Y<*zaP~n~q3_ujR;J^#~x0{dhLS-cjP6~ZP?*5g=
z8E2%%#QpV3p{&AjbU}n7()x37sW8S7mlgC1F%S(g`jrA|CT|>R%t6<{cA8Vp$7`$h
z#k4KuLM()9gS=^wi0%r6%+?dD`RwdBN*dT&t$vOHi9M}asrkw6IH^<ad-4m*iAjUe
z5ut=e=P@?(BLDSDT`}XLhWdsUl}E~abgA%}3Gw6SexB>PTq^AEx&#j*049yW?KCcl
zehM>FqnIpR&8F1~IDVk<K22j3p*)mPV#*TBPjQuU?#U^WOQS`wit2@i3-|*31jgY7
z1GmS@@m}dX5z%Wfzh-STA%VwW-NKMO!xZ$Oh$II`aa@dT9i4KY*lndTIt>)vGhtE)
z>nmH6>X&-^)778pv{+MmG!*6B(JMLAwN0d?5tqo4Wp>ebiFA34V{HMCMB83_i7`IL
z$HnNtF~YbE1rDF^Y2(tyCB6lb1A24Ltxs%#mUpxslpQkw7Kqc166GO=OaVTMS-8-V
zy7W=VITHz464r`y)bIt?3d1Y_8o+x>EN%&LdV*IZ*{3(;A7`SW)La1V;F(qtz%@vH
z3m5Rdi=S8--Mvn6Xix~y5_2oW>s6fWdv7<fn)KFCghhi^@VK$b8D1O9@el*1dlA}L
ztPFx~XV!s>3Rw%6xws&Uup5`Y{3iHX;WEj=G<iNIfjB80qnvKn^7Q;stOUNG%i&I%
z460RCVc@k`G07hfkf?7VkYkI&pf#pnR;^l<Rw|X7Z0C+s?n8v5b-K}whK71N2!Vh`
zSb5pWLoC~Cu~W)b#9ON}e=RmmFi)>-+@(C+<K`B*T*hNjp`f)caH*gRRqa&&x58rM
z$2FVUCm!4bYhXK#DR)BOmucpQ@SK-%1sd78z{<c&BwZCuj2lfi@=M6+M&k6uudHU6
zCS7aIN<Xu(2K?iq8M&Ze`1;IXIViE1BJmRS_Wqmu{gdl!?n)(T(#*Rl@dQ&N<|Q?h
z6q-?8ohpSR`9(g%vMvEQPG{CtE>?#@+3RnILcR@>r??k)X;ZjmE(1p|iPcuCE<q+T
z*{7*WXJcjHI;Mip?tDD6!`iiNOA}jAQYr2|SsDRL)~lR%8!J)sqw4~BrU`l1pL0vO
z2V`IkNTp_4u+kPRFiK=+L+iTe6uN~0Ckz;ip-vhH5&|0%aGAGw;eY#~NS2!GI+vAL
z<!gtuk;@EwOO+{}k{Ap3pyWq=`wNi?iF84bAtotjb*BU*9v2=_T~4at!pwcMjNisw
zMxj19i^V5ERo>IG0bY0m=>@O@ED)y{3P|5IuVb*BakA^&boE8<%BnAIQlyE(0O-e?
z*+=jEjfv9}yw~qCEn=bn0}HcKW~wpM+Qlb2^#UvDQdN6Ag6xb><z@W;okxCV@GEl{
zCS%l<?Y2GTKIx8EXSw^|k7G>^8nei8GNE!16dVa3K9GvB0*%DCU%v}c@g$cv=SIc7
zWEN&SMI}){%V_2SJ&9?lV1j5n0g0EttnuP5wVfAObp<kZ6)6H}3?{3smjQ8lqE}|^
zJ$Aj7^{PTYH+4pMyhC6upSHTrs2g$zcKd{<W##p>3+>@Tuz>J}W1RHIpETO0?aux5
zi&#XMte)0jQMT{tki8k?X?x_Dk}I`#GLC~nA&+tG6w0e8H=qH<95#bGZc*rFD7OHl
zM|q}V0@vh8Q&Rzya1!|<Z=7mB)Uig4`>c%;q)De`z%cs_`VmV^*H0Lzj1}KbnQeZ_
zU&6+C9Z-c~ChR?<EA7<m8kshQQ?+*IR^cB)!A{z<r3UblZtq-dV}Il!Y{&iH2T>kH
z1fnxcv9M#c!Ig}wwRX8wV5k6S$LWv|!mAnU)7kfY7-$j`H#LAyu&J5K%6zkt3of*9
zF*ok|$ES0eP%s5mjKVM0&1&NGMDHoD@f{BKN(CeY8af~}fTIfxmC{s*hyXYoYb|ib
zPtTe4mCFs<2Y?{}P<nckHRxt1iB1Y9{lQ1^DydykF1Gh%EvSrn<{2Ai`wMm?>y<ef
zm_@q7fo4&GAeR*up}Y{CwN>Eg-T(T|w~M|oS(T(NSIba1u)s29Upf!3H%Gu7@*6i8
z5BflzCvk#$ti`^c7D@q(5e}ZC5ACpWtr~ehi&>!*v=Y4D>sc9E9dsz3c)NkuW5v-c
zbL3H$Ojw1UbwMbDHEq*#@;nm^ydcD+*+o!s`xbN@<~`gRc5-`v=D|arS<Lk5YpohQ
z9dBkCQ!uOzT<LJBFor5}?pQWNX4w^hS5N~Rw+yvZ0BaMlshRE$+~&uB0hTV~)`Xex
zQS^;aiWD!AfPo(k+(?|hjhA0#8}hD(uD-C|>(+acDm1y}`E|z&fikEf24iGIq-P^*
z&>yn{tX0uKB$P!#yx`x>2qCxPGLXsXy{d1B@JlSxD7cunx>zVUi^dBY%kY)qbL?yY
zGMpmw)+%ggLeXRoYkrBUNHdig`z2rYz_a<D%-Y}*?Lx6tU=Lnx(8Eo{YSdw{q3`u=
z1wG~<KuVHM@Wh1K@ih5A{7#+WFpLeHfQ*O`gA)Eh8@1E1JSVel$*w+%_3C4c5J;(}
znB!tgW@}1~T9!#%BEgr)Ex89&BydRi@RAIIjSDWRKnuSY!X)~ycG9G9ezk-i$$f7D
zsZ4FlCPp+kw=2^<5@=wY?khp7w+tMPl@q)t9?vt0wM~7Xl42ve<$^siI5<e7k?xZ0
zJ-)z9;WL=JdY)I<Ek8g4K+kW;=Rtz6aJR4N*zxvS(aKC(uVJ=_C^1RIA7UrB=31tu
zie35eWJ+g8(Us^i&`qK&aY;z!f33u+Tqr;Y%$#xG3+{EX`-Pk}cnFf~Yfue^Eo=bC
zibKkza9H$1kxyhOw;RKkHeQHR`88&P{lggDQA<OOov_DQ#Od*0aqS~*F9{&(f0Znt
zM@<sI1vBHd&ZZqE@wEA0Ecb&544`qa3w?PB!wV&8eDXvyUVPRK+WwM<AiS`MqsNf4
zcrB(0Q+kr4v~vyu7L*X6!XycYT^G_*(JxjwzJFhD&V}7PH_N<);AZSDU09G|wMa}~
z%VdR_#_96HGz=4~$t*MuteeLSJQ*vVQJED{-xXUCpe^IT?zO<MM^M#;8I({~N0HG)
z;4M!u2WAdlKA)C$*^{wIkRgZ#frR0Ok}!Uuwj-G*bt&;#5Q}b}7Q$url!t*-yNv2+
z+{sFQZoY_^#AO8`IGikqK!XZxGY9+%q7p`v$0t01AD8eX{M17c7`k%%;DUpTTQf1<
zPe_0#kn!T=Rf1MOTbc#L>2Y4&y2fLNylzknIFO!HNfN~tPTFh!p<l>HrVpkInMnvr
zkDt<~P-Zytb0_Spi_fKv{UOSZR0+Ce1}(d!P1S8pDZXb~Vpuu9h)XEA`Cb=`ls;dI
z<#WI%pV&x>S2ZtJEeaeny3c=>m!GQxG23yYJ~8DK1?0eWdrShS+mBp9U9Ig18YwVb
zK!K4I66>nez&EjC%^iUPt*541KSd@W0nOBXW`#z>qV4nNM@_^xpIal5C*IZlp2;95
zm|&G4BGRLoESfyoytI_nICd5di3gW6(nQ~)`3FA_UOW4o?5EOa-unnk%v;p?_SqO8
zR^4tfcze7loI<a7@Ae*)ms)ydbHC<Kmy*BIZ@K$783w@o?C@<YQ?kseO4RT1EV=iA
z7gz=~7T9<?AblbMBFIo_AiHpeE=*-@++)>(mYPNhF{5<SX5t5<FSn*t4m1D3z<T2J
zc(1T32nj*O{)^r<J+esytAtZ(2S=Cm+H)NkEP)V%S@J+G_jsH1crk{$ah^%WAA(Eh
zT4}r42h&@&yFDdz77%1Oix(=+(vXMfd~u8TqBhB$JX6q0vst=(Hlk-fD5ISYI7D~#
zHZEhCZ6-*Pn3j5>jG6?i0>F00v*jz{x^8lNI!K75;6VXTkPMnSrVVc)dxbqtBUWAe
z`)v(WwO?md3k-XtvT$Lj;N7hVl$tiFlj)X0XAq~k$9p_=RN_K86Y6*!T;ADNI5avN
zjRx^GNnsxmis`t@6}g1!BE4Tw0LrG$Vv~j?ndR(iQ=AG0rz{9U;(-&eKq0WAonqjH
zA+tS$^Qz`beBYlVaO*Xmu3SAEhjc{v>UcS5f{bNyY_)MCX!)jrJ7VQ{uW)y0F8Sbh
zc(WjZ$1qI*^y@6x<94^22M3eNu1%L2<5Y$-L?R(R9OUpr5`BE-hJa0V%0k$`hwP2Y
zw`DWbQLXU7uE?YPwKEPbxrN~L#g$L{x4D91r|2SbDoU}vFNV4$e5moDAHXLLxN5=b
z=|rh4w=t6%X)9h9Y~9CNeZj^y8VQo737ut4Q=6-UE?HN?%x4p)kNMs^?OSv_+0coy
z&6%bgmZi1fzvdDB^wSeI8jS`>LD0lTM9$dRamIWvKWJZY;LXjBZZtF$3)v9JCEhr!
z<_maLqb^2vt+1M9vIZ;<c6Ch^6V!Yzty)-Sl~l2sloc?Egj|-z&-sc%-^OqpoVwoK
z{~yU~9OzTJ<YvlA62Xqyv>p@y4qye&K1k=eyzfVe5fkrUKH&kU%5Cqny+%lsiB?4z
zOW~`7ckM^4wq9zcUK!`?4g+t*iX*$n)<hjh9ngMyY8QA}Z~TOP<&QPZc==nY5|6Iy
z=5qC!C;35(CYyO#p-^^z9+xb6GMp}_Fp<FOud5yH7Aho^+<kfKy`Rj=TX_Cs(N={i
zgIe=`ZVz2>%)GG7l#>L#nlos|S|ZcVvKKHF#wl~hxrECo^3CA4M`uwArlT_I++|(<
zY~-?t)8oIVz9!GbUV&3Sxm|W;_xc8U+G=5Fu3mHDwRZUvtpjw7&I&U70K0JXx!iHq
z5m#YGL884Va7buQ?kLvSVu~jeonj&+H79T|R=_9JF$A~F%bZn{=EEHc!1qW-aLkS+
zN!B8wcie)x&Px;&vLsG12nsKh`1H=C8)mM)yO^%k1QZ2?&T`BA%7vV6ez&pWnBH#)
zEpG6au+r|(?=gfPTa#ooS{t5VpPIhVE{uqDib>lomo6TH{RS$RaiWtTcp6KUp>1bX
zYP8Q<?A9LEWat#YC1jN}H9o;okr!e)x-ORTs<2SJ0xe7U4m4+%j!L<O-q0ev`pZOX
z$xJs@%G@;C2#r(k1MM2HYarM`(?*O6s&tt!>Mh)|pBTs|PCx4I^VQbNUjH%*!vn<%
zcnr)D6&hquIZ$E}0Szi$RD3-<9wtIU6)wUH=h@LCSBV6JMQI3z;^B?zx))B?IH{iU
zxn|wWUQ1cVk0F;VhJnrJUl+_}rMO$MXfGZhD_I#Ya?2*x!{c!euh~1u5~XsP_8oiU
zsvh_d@IACg3lK2yb?$7SmtN`$<|$nPp_fW2mjo&_y9t|0r-AMMoa)%B<#^-b#)Uoi
z1NBL)wn6pvQWC5L;1vJ|Hax;N$f#XMtU7NllRw~l8{jdB%1m_3%5*yxI%J)NTRz-3
z-*MaFb!9+A;s83<h~KzDo=)mJnUy`w0Fnd@Q7)kK^uiORm6){{k%HqP0D}+!p$vz;
zW*mNo04%h)-HQODJSHBqU>d4R-`u*e-Y%S8r*?F~lDo2x5)jSTB&FyP>-EzHzKoTR
zeDL*4yS%E^zL@j~k=eUvp>!0I7Fl26wyWo4T6vr87*-V_KCQtKZ=7mgojfg;N~&Z3
z=}&RRx=>cR@Sc7)b7!GaiIOXdFg|pMAd4YDCO8@z6C!M|-<}8@WkTP>-LqnuI|`Uy
zG+DRu{KfP4i1Ds$txSNEav;`PQb<r#Jo0nMBAYn<sHeXiy1NetTGk4M1v6d%!YNE&
zUFX$9moe`Cj%yl6CJHesf{lOSrg_Z!Gn&hN@TdM1b{m%N>(<jV^8Qz~c9ErF07anq
zFLary5!4RDS;C(y#SY&CB0ocb0t-Nh5{148boEHro+W7#H1q@@64<rV2#k$j71(}o
z_I*!wO&N{kuSQD{DiPt4QuH#6!mY$=*_-DLZijaf(6KnNCu~tv3aA9r^T|HLzVF-K
z>;C)(%~&x;jA*-ZqyOPn^rM=-w(boE27vxQHN(2ps@tvck_*=1ROsoEVw+TGI8mpW
z>kBD}g0Wr~YRMQ6hY&am8Bj%%4s;_aN!t}9Kzu5}3Xuo_Lv(P*C83cGcsa27!~%ms
zZg9cDrI$5bjVWx|e;-o>)gT2{0u}HL%)p25Y$=MBuj*-?S@vp_onUJ%vpz`$^?2O!
zBCGa13*VsGff)lR#f8H)HJmu@3&*;bR<@#R&H%ot^|HoCcjJGwY&;uL>cQ+K=q{Vk
zU()Uwl?^!pQ)9AmAOMS%2}Btp3*#lNP6`5WXXj0#P*fnqNFZ{@CDX`}kx%uqgR|`e
z!7-Ij<aQ%S<P=pXUI*?JP#+*x?bdacOQwi+wqY^jG+CpG-i)@j>1ny;2|w~<*@8HA
zMS3xaHLgcrn0)8DFeF5{=}Bp|B5^)HL!CDPzC=k<4sp0@l?RlEG3ywF2!IA$dLfz>
zNkFH&sEjCZ++0!-Ck5f4b1E*FMh>CKDx8rK&e4U-YUQsw;mVOz=u#2tmZ%XVFmkUO
zcraEz;=%6rg6L%|%!QUYnUGE$?J|R{jU#P@#!$(E*ih0LQ(A+Q433qPSl?OqNL>d9
zL8`ohSF-9Z%+)1VOImytRvZT4vjoRL3Z)^*a%Tuqnt-DhQXt5oCNRe#EW1VtaV&3h
zNf$!nL8hC!M``^_FT4=XMYT5W;}m%!n*gk}0-gJpzxi%Kn}9g|h$sGN=<ZcgJ4xno
zaF3IYsRO#1Fi=1tHHb7EBYTWIx&L2J`S$N=xnsR40>Of~;EHwM`r%`PTdyba`{UGH
zP$o9fORB>?(#>XNExVibLFz<<+Y%H_DQx44h>v?521YH3><W&BCL}4$c1K3JRVUkn
z*_KpDL3%R%1j|b#0Gjd#paqNoj)2WR-Vm^ds<~iph>TO+pSprPJ60gUz6=VEh#Qdb
zIzXdV4ca_p;OAIzyKO97)jnHXD4QI`m}ahei6oUk#!M?S*QS%V_O>5W2YhxvVB(UA
zTnr(C$rr9YUzs!+o4SrCLJxM$%t2PuF6S(WZRv6<t?vPX2!T<dMr0rf?Qn##0>NmG
zVQLi)d`&=zW4g^;?;=ys`9nk3Tsi&1OD<fbM>^J6wmGAeQ{?f2DoIKZ1xVQw^$u#D
z$d><m`*h;;qo4Sr{dUgnf%l!YFUKjAsb-#_iKIek&8RSa^_^1>T=D^jz9UnZ-O|`F
z28%!0_4{PX)LP}o^Tbr1I=tSO%bOJ2<z>>~CEwugaTIzOWe#B+>~h}^1v$V=9O^NZ
zm=BmMAXqqE?)cMZ=vhtzDFuaLj2#=%f3SyJh}GSF)?mG9x8sUwde13yF##Euef|M0
zGckR2JZT^JHgL@r7us7QJ`J=r*r0J^{t~;-MaGX8dN5>{)qkt0t8G&)bwC#E1qq8B
z3){Qbx*il)K7<GOo?A7PV5G}1mVjGXlVt#rYPU9XEzCVw!91pAnknWX#reUsNknvf
zcKfW@hn4dIsmi!4JHW;;3XBz#>N^8DvGUbE@ogygag^Dm-4>gZ0hvrQBRW^b#7F~-
zFY%(n%M2dyIa-g7_%IN`Vy4O)r+wo%_g?zCN{F?xv>N2<z9N;&bJ2X37dveuWk|s`
z(uGA#T7vbC>+q;lRnQ@!C6#dmkFll=dDm4s1Rc0u*@6og3v;F4VM$oPAPH~{cne?*
zz!9*Shyy^XpdP899;ws;X#(nz3hI$5Qjb(nk4&TkQU&!$1@%a!4%kdUJyJnEGDYf<
zV))noqt3{e^2Y^#jWsK(*imXLEgH3|R2>0k@cs5q_y{X6GwUtH>TbTj+FZSJxskiT
ze07ROMsC@<E_%}3_Cz0fOKTvp0l={tW8D_tg5Rjkl*)$E>Z-rIk>#>VoF!vXdpx_l
z+@==Z+;9&CV$%1ypd8nk7jRSo*0e2Y*BnY!hA)xIHe@3b%R0ZfwMv|bU1Yo$lqse?
z@GO09#^f%iwaH95DZ3<eS#^r`=KEd0&C6Tb*FJ$*`Dz|=hgF@=-3G;yRZg0@VsX}_
zYuXe|wQ_cxhsAJ40aewW&6yRP5)-V(F@NKf{sO5bvxQXi`}a=S(s-(dKXEC6fCRmk
zC`&|w4=WrZGzbCsY=X==0+R^c<p{GHg@eS(#NZGNOJs^!y5zzOc;=0#c*I&s5;|9@
z0>ZFG8D1H-$s$g_%7@oO&9>(kYwe!dFskvDIiX2&jm}UdH-%I2r6+#-SC$os#SjoG
zB35&u<-m=3Z^L`n)VDKwwF;z3&S+;GYEg^rlP!Jz4z9eOJ6VS@$^%R<9%H;y&ntsr
zQVAiBE#yWP$`Mkj%I;eF&JJC*i;QXu7ax+<;M2poVM+USx{Ann$~-dZxN1AqqQFWE
zoS?f6ixQ-|jaaoTjh5C<H<$!_#1tn$42h?!)B??(8tS43@E(I*AtRAjVd`zqN6fLA
z3k(fGZ*N~;&*r+0>o@>v-#GjWr|J6}MD;!<953O6#c~&)F^;9}=c$WxxV=b*C=nSa
zh$M;_vEB>zcQ^{{q83>1;NFV~TH<SFWd4A_9qxMqZX4zi)T3_f)^FEB{9xDM{{&bA
z8E6CC@SOmcfX@R=0AwHqOaUk$l@yS`66k;gD6j&gmI4x30*WAkRV58br6r&U5?BF>
zAY)Nr31lDzR)7LhNf9Kl1UjGqfC4K(YAGOrC7^%=R+Tg$m6m`a6^7ty?bn&sbAt<B
zxVRia?$}~#Woku=d?HVTiGa#DgH?}*Q$#3?**5>T)LUZZqn`P0zn%G@g3u6|w+UD&
zKZp+ZTv#XC2S5IS0b-MYg0BC<&FWzyE6SRydf^hGCMwA>kf?i`>%}{0T&Npc2iE~$
z7MG#41CD@pu5<`_3s){&pO3&}zoS?_(oI!JpP6dTr}bfjzoTt%O1>3M&zcoUiOv-Y
zrn27+e*po@2(jvVz46R4xKl*5Ihiw^$M?@E@y_?>+<~ti5TUQ9GsYMI8X~wYf4BC&
z<hk3ASp0?o0O`!Kc<x-3V}&GrH@YPdq6x9fq*O2=0C+xt<qaJUno0?^G=1)K8CS(%
zIdwqHg@Mzv@*P=|B$}k1pxTMi{XTfe{96NsvGUbC>)^cTWh2eNT&{wj+$ERtLW7S9
zdNC+{#H1$h>rVX($DCr#?OfkR5*s50xyJU80_W4&G^3uNC{C8jeSj*l$SXq$5lTa`
zNsiVBLU0zYG)^TeaWNQ2R7_)!7vw&(WWdm3C=l1g&H1;Sy5&WOCwi>`b45l<1a>%a
zHvJ%2SFAzlrt~pp-L4>3?YQPi#|paY!6Y2dgGv`ShHAPmd0B4lczW*h2SEFXN3DUt
z8Z5qL-mRZWYGRp4O_~OXzR`!=wpLRZHl||nSb+^-LPznaj4`g{QW;Qr7fN>&07n`X
zR{$l%2&{H}omt+JnQRc?aB3U?QUw(Sq=Je9QmL!4tg%GJ!~g+05}=}h1eUc{fhEw9
z02KwKf{FqXSdOIwQUw(Sq=Je9QmLDeiULwWMFE*2MF0hb+spth3s2Xl+NZBWiC1MG
zbqb`0C!hj&1DpfrXo)5M-M|mA@=?!zb%!mrkFDAmnaBH9Su=AommT9w1sH<fn3$CV
zEI!f~u1;@#m~~N9A~i}g{q`Czz?JR8W7gDkIX9NT2XqLhQUyQ&8pxIbWQR4#cP<7~
zKo3-MDk@D+pED&TVgV%-2KKNDHC3o;LC54(sHwt~t58#gDOaJU3RA8^O%<R^u=K4w
z%L*&cGE~t@3=9oST6p2X3(Z{1Z1C!F1!*D_-LzB!l}yzNVs&?KraA^1bp`#3b{q-l
zW)|Z}>kR!>POcBld;$!P#t1a@4d-OieL1O_o|#ARJn6h2xrT<N3-zam<;etM%|8c~
z_NM}Yt`NFpcoLUsX(c(5lPB<k1q&9yBCue=0$9L$1+WAMMphG;vuPX?PSY^PjszXy
zr6<_I)1J<ks`L&Gn2m4wOgfi6E;AMFUCOF!4@ql4rHjGUHw!Z>C04(xXU8*3E;<*F
zt$(H<;3$~WY5EmTI$rl=J-6IoNpE~;jm4XN<EHYHY1jX2gb?9wJ@%$trD5g$Zkcv+
zL)^4+BCqt~xRMDlkYr)}ONI+W6RziK3jv0lg<xQ<-h2hzR=~U(v^0?Xn6CC0(9v=P
zIFTw{^4$QnhCs~K6qHdRC<uagu^w3gOE4A2EeKL6lg1=t%cL4IHUWfj3W8LUTGJ>s
zGO^19lc$S-1R{_}(nv&9PyqpEvNmyY-@_L+UdnSbW@1Vcp|ts=30*hzs)<o0VE(_b
zr+M+R^CF9i#}E;u$42hp2Dmqt1SFuF88<F8Zml^-47di?R@-!Jt!G~Jz~Tk%RAM7!
zGct`LA%fuAUv}KSZ{4eP;erJVdhEj!$4NuR3*YBcd~Zsc1t=VP95&Xo3}h5h0W-@`
zT$)$*wOZtl`zu`B!+ja{prkV?1GVrFRYD0Z&L9X|beElic=B{PJOHr3pEv|Z@&QQ$
zM07+=0W1I+5vmGR7XT|@39ts1KvxMILKjGM6o5<uR)Dzy=ztCq-o&!&8Gz*JxQ2LE
zz>-m^u&lHMR=_f_3V={oDy)EI;JL90)jOa>=mM!Df>J+@c!i*pN@f0s<PJQ&zO>`o
z6C!erf+nP<wL&S4rgdX4GmV=Cn&%q$E?(>yYX^Gf^gshp$=k}$z$y5~)EmmJ%Ebp$
zWm7|4{|#$!gS<QOefRT?4{|V~xL&w4QMb(9k?LrZZfQ|;5&`|wbT;S!GqYd9z%j@x
ztvD#@X#Zz>pTB=ug~;K`8Jyq#L05mOh>ULMz=AFT>kbmok*J)vA;1)%01H^NMi9on
zUa(?xwS+YTB<gmIvjY+}yX1i`QM1FJm~_Xy?10qyAmYuWYIGzYAi$@>Af@u|%b!(^
z86Nn@4Mhpk6+oJF0)&PdH6I!{K)f30Y?TubUZHP~fgZS5sRf*vRWJ@o^ZH)aB_=wr
zG4llR8HTGgYG1he-#F16J>4gK!c}5|G}BCy%4~cO+x4oR{f$&>r+xbUyV;ob0fXfR
zfLqRDohfIby4J%?+haFuobfPJ>fO9EuL(HK#k$1;Gzk_!$LJA<QUPPAuv9#2fF%Ng
zzZ*lpUMx)kOJEH{N9sr#$Ri25Iz6MyK=RQA5|An-R-WZ})FUGax{(!VK&C)pRcjGg
z0}EhXVex_0GI0$$QXmOnsGy^6qVsilpC*-;4wWWITx77d9{L+j%!Udz5~!F8NJvr{
zy~z!&D+XChyne)6hcmGX^SjajZ6<5lj*(9(ztFxAAEw_R>CNI;<EHcGMt3~4=-^oR
zfkYwAO!kBpA8k8wqWi-nQ^SK9k@cYoz%wB({q8N}z415$|L%hMma(6gKL8wYl&-@O
z-ozvYU4H;wjtG#M;F6UtSc5F_b`%&&=TRWzPgRzy5tJn$K$ifbM+hq<$b{7+6_n}%
zq!F}&0#ZReQb8H>M9ggcsh9{WSY88^Q2{zqt;!t<x*lbIT6)$#v3-RnV`@+%p=cTP
zvYfN~44jXdkNLktf2-_R6bmd^!51$JUV%6_{0M*wjbw1}3-U8DV-1};OLlPEm<Z9|
z4<u5Unl(7w3s;xV)y|DzE&@z7Znd|RJ?%@(Dm}K@LF(Z?3GOGxxEV#C-X_u-WzrKi
zB@mB>nX><dEVIcMqDy;bb*}{1i7XZZr8pHx{~lpMRQ|&LvCm9fDm`wA)6*lo+pSfM
z!3>*?36AQmmLv7kB*4VDeR$)voN*6$h1<lW1P~wtS1R;$ES8pzhQcH-1E@gi0L>#w
zg{4OYI#Lvto=+8zN<alvJSw2VsG^v4Z)#6ZN4NvzK$I<88kK+wsEi}L1Xk1)7^KIm
z_=Sv6-3A!Jy28_}7&Q^xrS{yx3wOzA%f#J>O@J**Nujh882Fz-HWIToasmrh%<n<c
zbf(20;yHBFwhLZ}37A<7Q?83Ou6N32@9p1|s_+(2g`n8U_0zq(B-6wkZ?-49oP`WW
zwiHPu=;E?oGAM*n%Wdr4xTqx-mZhnV%2?O9yAXgo!e4xUei6%29{ier22mPs8Gl6Z
zgc4lq=%{>+lv1MWI`Jerpra$0#*#=RIt1t#O~ADdZ^szdK;jh=H%N3;HAouiNcc05
z=t%f&gt`Lc<mvEt2@-IJ6TB^S1aqRM0Kz2Kz@nD7_0{aEEl7A5BMX)bSOP{G=e!@9
zp461tW~&TQA)!bS#L|=*csp)hrWw8%^E^$FjI>W-`WiT?j=h`6pf?VT={EqOfdM_`
z!VT-ovALU|4n9+O(%xfD)YiczSGx<=+iQ2A0IW#rWQ8l0MHw_3X&aBd8!1Z3yc?;I
zBp0J*sZ?PT`<tS^ZBP=*a!E(e5C5>g`)^^c#?6li;jaD)Xn;e&8pyZ_Cl=YA;ebG2
z!5*QUxhB(e%67Z83PeB|6~YR{T4sp7@<uXSWB@^X<ueFpK!6PNp3w!$4KDFAOF)1n
zpxsE1sRSMc26~<gygncS1)l9Z76>4KnGjJnKw<Da21r1=BaXOC4n#o5l6)Pb3Aze)
zAOq6-6o@FGAk~gIq8Uj*-_oxk<40)FMj+!gTiaoFl%#Y!9St*ok+^M2k~8TUc7yp<
zsUghl+Siy}Q!mixUdC{S7uLqX>@}dLeBm?~4u6+)p9#&L2P$YulXCLFG$d9(Q(Jo}
zKAm)}Na6s^tQehz{5e6;X^F4Hl9Zr}A%XJl{{4OXtdrv5U-EzJYcjG^FFE^px#hku
z9i0Q(28;rn5IH;*x6UeMll*UKhY?c%Ca?y!!1k0=dO(2|AoE_&fC9EwhxdXOgsnNj
zS~QFbN*h^)1it`Ic+7xzNq?-Yd!WOg@Hc@Le-l^)s&DXj00KRrywN6Xt+Msl3PAQm
zVGVRd@n{CphyqfjRS!5pi$GJM2NtzZPi;%Um`0i&I=m?lCQV1nI%ts=C0O8>*1e=@
z2-&fN>W<Bhi=xfzpM$cXG!6c0O|1kpd+O^2P5^TmPy)ac-RVwu%2e@DTvHwDdD838
zWP-8@ZZtGB)bkaKMF@hRJ6Ut0&pmI~Pi^u&A~4MUn1`C9v71el3Ioa=AP`(v^e`uB
zwz{E#0qGWsn+$M%0Pf-K?X3c2fK!4U6?Y#4I_xa~32s6Q&`_}jxCskr@mdXT0?KIe
z*oX&O1q93qKo1Zx!$`4$urgW@JkSH;0(u1odfv>!V<`gGK#z$5RtZ4wX#qnAhGJU@
z6eoxopjZ(63O!&WfDJ~(qo5?*1=0cu1(opxNDB!ObOXE@ij)4Z@DkM{ta@7C7H=fD
ztu(r2v?Z8H2v>^Thn$o<kzlL=-YDc9s9HCii(X+)R~smZ8EYw?xSHxEJA0A2o>hVk
zuX%~3o%uv07#l*22Fbc`go7Q<p-!5!<G@EDe&kndQ9V6+2|1%MJ`my4=7E|6BUJ4e
zr(R1a=*S~Y1sws_3;eg3s8BaU3y4PvM<C-LV0eZ-dYf^^44@!@Qd>P$lLAF1D3ZWS
z_?4$vjV$dEUU~{%BGHgAF+lsC1^(!p!p8S(1%y$pF$>ky$a{NZ$mx}zcf1&=8r*it
zDuyb5{=e-0Ii?DFm6^w;)944&7M203anVv%iOT&^)o}k`etvArnH!Hh;pS|%BZh^*
zY|^xSu&?7CS^1V}ED72c(g<yZG_oL^NEOmZJJN=NedvOJ11m;X3072I(Zhl%cY<((
zf_~5~5fLn*tygxlf$Vspw0u#fDp%d*k}~IIO?GYh(VUWfGY&YzfdM>GTvTOdbTi&2
z*v9~eJZZ_Xu5E=hClDR^1|JL<K>HB2<t9vewHynyK*F0UOuS_}2U|>P@C^Nh2do&~
zuvk-h1<*5tRa4Z2tf2E01MkGk$3CYg&UfW+aKhauh2?TOnwg@&iWRk*GCCSa{0`2&
zj$P)!ZoX@X#6&4OJu4x6z%MQBeV|*NW<SbEG|Y_wgJE-EHkr^MjCP(x)t72?bTyhO
zXaI&01tKfpo@d1nzyu?!0oI;Hg`w6!4>V(IF%w!q#?sdsngun6sF4B*5ZDmxSTmY{
zgujP%XbALyA<)+v0<|s{Q6mA|2tYuu#H)~8DQJ1vz>s+Pu-k6MZclA@^IgZNWR#ir
z5nhLt=-Bd1Jwxc+od(v$gt?9IYFliG!SO!zb5TAS)1tmtlN!>+TykN$Vf;M<vr;KK
z8AFBC%MK1Rn-DMG(C(w%|Lv{#>?iLEb6izOnwn8AQpW{!-wQwB-;lHNMr+3a?fF2M
z=r9-!cYCVZ-{EahK5mM0uGAs&9IJ7wf=-=IZ1(D&sZgN;Y=8xjY9x+H9_VLA;RI3z
zNUk*cU%zX9P2`SC2jhj^>mjuq%E<BYJnO6;FGNgq#}DF5dRO_vv;z&lqp>kXiN``f
z6`bHxXDsV{(zZ{gXxh8%y^GUCX*S0|3MfAmx_pVzrxFVCX5h^<B$|;c+-6j(6p@h(
zeZZVB5}^-l14E!zU?Jn9CdP<wlnQ2|gd_z<#$b<6+_w;E+-2(Z8>{2Rz^iUAn_cV}
zOt73p2Xr${RmaD1D0ccTw-V<wGDgnEb%;lyayt?9$fmt;u>Cm9DccuYm#gHI8(PxE
zC&DrXR8S5=G_yAZ@sWu@BnMvN7NAIlV{Y<Dg_i=ifLophXe)I<nyTno0uAt(r?0eR
zpx;vh=$KA`w$gZ^q=jgDXYO_n9lIxTuXHdYi~}{SK&24Sv7uu_N7ao&Csb4-8L*KN
zdSJy8H~|`3lxGmYDu4@sL!zg14bqSCGOE0U&Ukl)PRJ`KtE*52C*`_|+{s>^;?v!}
z<KrK<iWPSH#YqL{wqbaId9UgkRM*(G<rMu~?!ax=2#EB2X$uLgau%Q9Q=2dRZ~JTh
zuBmD#lA0|};(Rvp)ppiGITI4x54kN03zpyotN_@8b<_$x4KyT5Kx(M`0MGzkAmQHt
zou{P<4D=*gM%O?CB&t?`pU(X$v$aZ>S1WI0O|?pwDS*~ek7?}EKM*h9P~r1k_l&k4
zhGCd%B+6*yj@*nq<$f%);H99wfOhWb!jY{UVexYP+}kG?&bgrToyS8Y>xtzaa-O0d
z-6L`C#DKGyltIWujC)Gv&_xIshVn2lL=ZrQGMzhs255i;G$az64qyNVdcq^n0xOn4
zSpZ8`iNFTBCEgUOL1~gOO}M`n&Zigtvd!;pwW&hV6(sM+kuBWz`Cm_o6%1Tx^v}av
zng5B(kA3<W=hFkf#%N%$93U<O8x=!h@CqB8<u4m9JDA&X6ccBD1ErE<BVA7vBKCJ}
zv`U-U=)TxABc&Eu29aWM5()%Ws6hfK4ImvzCAC5sl?G&>SJWe05TJ$C5};gyHSh>Z
z56Bko0g4hs)EEuM`k}TM_vQ^3@`+pSf2VP}sk(cf>6v)pHIJ4h_r0VVnr0fBnWjL1
za+S8}d!l}){Q!{-=tVmBbYVz9jWD5-<KDdW(r)V~ivI1CE5nkE@)A}98d{*M^iqwc
zR!0IFpq;7=G_=4_YoG_#fEgxcD7ZZqL4hZLI59^M+F(&G=kAG3lP`o+B(*Z=)hd2K
zjUWm*MTsW@1sXtrO!yW`#3_IP$0$l91Mdffo)xh4vE~t!XAr<z0QXRoNVo>0&Ikry
z=shp1)sA;hyMnL@A5=S~1r!DG*xr|a{x>JYi-Fw7{Qu);#l6v%X2g;vGwTy=k;pia
zpPm=dsTUJ|w=4VB5}VoWY<SLlIPK(sN2iy3(K>m<m0(b7Oa{3KuWGI<Th=-Pxd~uq
z&t+^_88>7+Ihcbv80!f3u7VO&0j+@Y6g>43D2Rd*A!djf6eR)!5P=4i2r8f;3QDB9
zE-A76KD6hB^n`VnT}Ey<f@+<Lu8X5M7B3XMoN-TH2XKk`EvTgtw32BMPR}R%boovz
zDCOl5qefu&(r`_1qR&<L_v1g0_iyMZLOMQ{sEuSq@p$7=8;-`L1`nuRt?{O*vY7^E
zvU2^^qluRg1VKR3lw?EzUV?QM;Ux=rN$?6PWI!MbfRF(JGOz|A_aGpEphB*af<TFT
zk+NBh?I+hJZ#0FZ3qcUn(T%_K^M9HbFMt2nJYv%>fx&4;vn18|)mcZqJA$?863aRD
zAP_QWi(^D1!GSxTQY?SP(s`fAnq=1ZrTB=AY!mkOv_9MWXUmpFwvkJ4yFemIukWM<
zC{_yNjI$2*uR28-X-@%f1`Gl;72XU)>?!cyM1e>K9%j@Uumvyxg#j4Y0=9+#TVRU<
z(c=_RSfv~kEALx-o?l0{wKp+^00Yu43fFuyx$Lfe>1Y4CRjlxu)|9igl$@D0uUExZ
z?%b)<RZ2iJQ!D}`Ns`oRwVF?Kw>$kuof45#cXcxmuBo&28<$(iEzlPaK|p@SjNaZ_
z;m8-;F^&GjxRfAmF6GtR!GOe*LphTqwH~jKE8Ox(g<HU@K)C=s2&@AO;8manZibTY
zCZK?;1#AQm;F*9m1inR2%a-2bmMZj~A}MeRlqR590M>vb0VM%=%o71cfIe^;L+ANG
zB>@}&zHz`RfI9;8z`Y8BpMXI-5hk_Gio>@sWy2)+A$Yv~96^Xk_e+%(fKkN!gM$IZ
zIzdgf0DlX|fC32B7pwsn;MJar0_Xq;aJNE9Q;|@a!xdYg{PuS>4um1;Y7i&*DzD>`
zh?+Ofw|5|3z9GX?;fFRZOqxd<gn6EhN;>)@*kNhU(EGxoM0{$(ff(G$lwyUMn-6~f
zuE<U$DjRFWcy;2!ULj#!|E=#s+YV7I^E5`mN+Aghd?Nw)lBr=v6xG$iia-wxjJH=4
z01adSJ5=#D_%jk+SQ-{bN24~bcYm6Au0FRd!PlT7blaANmwfimu8tM{U3Q19pKoZ?
zk|gImzfz!?1hW3i7w{{;y*L4%-rjq=;CQ(M{57`DZjN%N5vn}tLO;@E^uLy&vAI(B
zOztNg5-eFl;DjfDgoG4Olq4+%cxpTf#83{zkuwHB;Y`Mt2`dQWzp%rDL#gB9%&qpa
zQbARU5dF=5*#?T@g>!xv{m_uP#C$(^ztGxs!!?#UE_s^X5)Dd}Ob{2wU<Onz$C$bD
zAb0oI?aU4ju~BSPd_6Jo+F3ay#sjhCC!HZ`s>*mEt*Q`MVTpj1AOM4!6w`rL(?EoQ
za11D*Isim~3|dP^B2+pls-%)7kp)wY!!fXBJ1*@d;~qN&w?wT;@rj9W?f1FFJO6rN
zy!^HcrvJ(to^+avnb@QACQZ|{h^oVh+DeUbGme4Z%Xv=RnKCgcj0Mvm7?b$Jp42<o
z@zF(ple@{B>#4w{5#q315w#+O4b22Ip$l|C2c#()Y7KiR6Fr7v$|7jT!Rqne`=P4+
zktf~Z<9K^^l)Ysf6kt$lbRLvqs5P4K5A?q5TWSvq13_Wjf?t({RikDw)5r$*fO2^E
zTu_gM4vd18gM*18UCHhdeSfJAuI`B!3XbO)Tic^$#6^yo`*(3tZW7JVv+$+16Kw}D
zjtpKrfF@*%9q!`_^&<cAV7=}d8@)P<s62s3QPav{n!3k!g@I4-Md1j><zQeO7+|Qt
zK-!I`>a7AxRzC3!aRqTIav)LQAn`&7DjDIhSesXiX2T96A_ajAim$BN-K8(;B>p9y
z-HpV{-@o7(Te?T@-p#c(KsPs3Rc(S5!FJYcufEglR$$}}gEQ6}6T(yl6mH<4(<k?I
zZu6lZiEWqJmCjzAE0HIVCn7?6>wnWd(|1p?TH=NARF)5MZH0Y-L6QQ4NjJ2fjRgjx
zFZ-fKP|%Q$Ed~@+zyf_gL2*d%AiC}xx+|E83<{8>+7%pl&_Q<Fr5AhW%T}?1frA~V
z7FV2<CL?Oi+a%Eh6KjW+I=#NI<H9#QLVN~6(kn}X@m+WF8^aU*@xNYo*OVf5MO*H3
zoxAz#EFuWLt>zXOcaL$%!eynURvV4c<rUUhi6w+ma0*z-`~n;4?o+iEfi(+{;CBL>
z#OOLS_Dsb@<r*o8RdmxVIJ9t|?7FDtI=b>(1(LKFSmlw%CfV_L!R&O+sU=xDH@iFz
zD}W8q%`A~lNn(Rw2P;;9tO-5vGyO<je5QS&?-qTrP%MUkEkS;nX3zpByt(-@ZW}bj
z=_EC5_nRU;)DeRl+H%h|KvSs=2p|EOP{Tl9Dee&k6eN1COj&#a(9L-oZ6&&QZQBz3
zr2|@v!j<@sE&yu<P{7xtb440mG$dfds8-5=5^kjl017Sjj{yY+dY~05tE7SkqeW^N
zB_<2^rmpkpxxJb&NJ0vzs#fO1K@r`_Fa7qH<KxA^l3inKN%NM0xu2$K&LUFoMSbR?
zMl|RnCIbj!2<&{Q6Z-qzue{<rt=il)6%(ZnO;_At;@PA3QMJ&Rg7(0+T7q0E>t207
zTd@mbrGSnAy+A_00~u)rY7C}@maKp@@)VVumw1YbJwpyefPM@^CQ_k?Tp@uJs=CkK
z&dS|^d+gAQPi5w0UZ3u2f=MRIB#0NBb*76PQ#%38+(-~P$VSvc#N>7a>M+LzPt_ZC
zxFH(EMXNUKaH7w&p3h(AP3?)56ctIT2o<&yr+a5lItw6z@ER9~s&+*0c<-$j0*iG7
zihQE$OL{OQbk<IaCWRWF0-hStYWfsfMbQ}05gmg@bVN}=Ay!aGU~m1p(l$jCtK1zO
zTavnzD-o7}O43zg8!TM*))D<aFY(d+?07NokmcOuBF)e=)#hxPrjqXO6y@8BWVo4l
zsqsFM{6gF$3U$zfvcsIxT>ZC|orMVxv?XdpIi0uptCWgf`;g8K*TOx6*L9$}zaG4|
zL8N<ASm{~|DGKOFU8SxD#;?@X3V;F}yd)&D#$g8csIK$(p}V@KzAgr9(iI8ViXVid
zyZIs?e%dNl*x~79M{T>;ls61bGfzZB3Z-c(B7=*(TBa>G(HHcs+GEF)=Z5Jgq5<^w
z_QnR|a>57r+VFw?;4juGPIb%5esHcJqXLECW6)H9ej*K!W<morw4M$~9-Y|W>GzO$
zWDn6<<?r{${E;xY=jNsqZo|jX@r;zc-&1O1Pyz-E)CzU!1c}KG^uFLgKd#_F?;ERi
zlr`*NQ{nK&;bdKET7g^6mN3|rLLF=!n-K3~x5mpibRXZWFE|+(N)vNG^)hamTO-eq
z#?|%!B|f*ZQG08+d;Y}q8RztChSsZ_aiT^<*a+1s-@faS-LoGHx9&x-8$t2zn}M`9
z-}md{AiO}CL99UU&gyhe37t#6_~Sk3>^XC9%Zw5=6Db0u5K4k36@!Fd{DZf<#|j2c
z**W_bu_RLiRCWF&Nut_GXs*_o*3Qc<FLfX=P-1jW61F(eb(8%Z;MN+SRdw~xB@8DB
z(MBVYC*(dx_hEnNpWv`*;J4RQ2tkT`Q7OP6KoV0a1^d=d4(<`$n|8g-)biA<t$p{G
zv<p;~4fRSy|4_WJ!~W9U9zD$|%A8J65Hx8fMyZbJIBCB^slFJEjc~vPj&sA(1K<8=
zo$<Pp&Dd!~S9|E|H0`ti`kGD3e&eU$&--t;7Wu3JDM_lDq$DKi60j0BK{viIU)Upn
zRuVvg4I7UDZVjNQM*yuPfC7qo1kfTRAq5gEg^b0t!Gn3=w0$g~mUkwMkn8S}bde+p
zpdLH)`QLvuE?&M9K4&$7Jdd{k4m|L{LXAeFQCzK7tMx2eM9Lx-r78+K_;P<r(~b-I
z+>73D-;a2m(7+RETm->u*!dpL<Sq^l#x=`Zn`l8At<#mJS|+Gu2cT>kTagfWEKmqw
z4Lspl@OFA!0#MwNC-LQg4Pa03D6UPwB7yQCP+SO{1PY|qdjdry@Bxo0cz}h+0Z)kl
z>L~~VWGqIhp$PCI<E^j{H54$Tbn$XX({<@^?zq3vS}v4y#R+iC9eO~qDcDW825>b(
z&sD5}jxGMjj{#0%g=2S&>y%4zi@(iA0L86PIAyfY01_)?7Xu_h&j9pU0g^6KKmhdw
zp_BlG#b(7lGxXw}nLbvwxdppOn*8h)1e<^wFPE6nepsOv2jhio&&Ru6qKb$}q1a7Q
z6%yFj5#(&-j%`oaFMPOf{M;sY&_|5^g#+W@{=af5(R*Z*`@8Gi3qBix3N&rbJq){A
zg3W@DfAQpl@HPPyg|p*$d>v5WCIefxRo;f6Z=~uVTYV!H-sps&HwpJ}gdv^g3egOL
z-pqt8i6ag@5k(4}wd&gPcwUxM;-NM44EwI_#@c_>V1QC&0{EfZ3x4jm+5ebWG4Rja
zKEIG!2_;R5<CM+{kd<)33<sI>k{!=YXK&>=JHwq0R*i>jc003O_kN~ww3)xI4pv1U
zZH}2t6h#|lBq<B_N%ylf?xREZQ)Dg#g%$)jmL0)@2(W$h*pUDf6eXg>fLQ=VwUVkv
zB?cD6OpFyGWMW5E3px_jZ(vDUjCLANumabgROE~!=?&-BBh%MJUPd5An~4?ytZ|Ix
zj@_L>k2)IoK2GpjrP@&!>72$<m&QOOujoHIQC(l#v@uSj&pqXvzvKNFDJZd+HG;}u
z26~TueY(t$|La7ZTkiUmc_KFI6yZ%<2qvfTaN6+-Esfe(dfOJZ+@x1U;BBQTzHJ1w
zWkA^p0A$2AFj|62Yv2bZ+%r%+Qa6%oL^9n;tQ5vGQpN+6YqS>kVca7FFSs1gL@D0X
zaAQT&Z<1e=y}ztj`Pc*dlg_~i#=)XRv#QZ(G<vXs0yG$9MK#!sFsYfxjwjdB+i%x^
zLBs^0Z{KIOs8;U#`tynLhcWBhQld4!?{_3Yr@|$Sq1$6Jv2`u+<S80N0YL$DH`7u!
zbN9#8;e(06t$$*rBLQIn6qhktCLM2mk*dcd{;tyKw!*kmr3J94Ffi(gis_s<MFc3p
zz)D%N@G6@G_cvpw<v><WBt^X)Y=v}63nAhqi(BqbyBT;dPB5^{QvW>YEr{j80g4r;
zsF_~I-UYO8+rgH1q$6>m`(`B3zt7@Vc=zY9|07#9+7<P9zJ=C48*QfG2sR<nzF!IV
zi6bfV>1NxCsD&0KgAxI*^l<xwAh45)V72fu@p3gm3#D2n*2qLhs)V4HPyxt9r=UCR
z2YZ(^ab0ud{(JY=sTcFo=Nu|ULN~Q$Yd9BY4D^c?g1y-635GYuQo$iGMulXEMA>{c
zP2MXX$#v7W=Z$wngHefv{EQiS30g(%Vl7w(R=Dco=)9-m*hw^CjM*r|AdmpBEoW@b
z97FHga-%iaJ4B3A0BZnQL2MP-;ttsQbS#2)wYJp+ts&^;YQXhsiLTl$AmP;y&Pcr1
z9S09D<Ei^lww_1|L&YSk8I3&dYs)wT55&rM!lS;5CWr{u$I{RML%`4gLnI)9Qf(HO
za^+d6Y;;E6sK!Csoqr7xt%?QrdbVC}zc|iF#oSL}BT4~5oT4P4mCK3y$-w=B*G)XF
zg9DVeIV)>009u6}_~6y+lL2Y~H72hJ)fJf~RgY(_+#rZ@tBJ+!9)ioxI)^esjvy3-
zqBV%)Elk8+bI0y+1BtOhUd(Xli_38e8jY^J&}Gjx*abrr90JnBkMJmbcGFho0(zih
zAwL)%*O=(-?RCV(q{xOR|LPl~8@a0bwpduQq*AH0KdB&O;zZWKqEZ8-N&@IqWx$dq
zvgG~rV^APgkcl*CP(dISbQgo+@m7DWpWK7$g3XKed-PY@dw<zwAdG5@|93zz`m9px
zdaY(+ht+_iYJex075f@%EHtAyMT=UB`>nPmiESq5(+XudlnPiWtl;HHsF9iq@wFV?
z1VhL%uq{@8<A&7**T}i0#BdE5q{}p+DtEn@S5C86TJKni!~|d?|FU4x(sg$}jeGs%
znc8&lvWc|TY$Tb|Ig*#DXR_dO;=VibKtev)HQ67E6i1E(O6&upaipeJ@M{IXRuGR?
z5RX<6k5(wG1*8z;j7xxmDc<XYGjV1;G{HtY8r`nprTG@?GyAZkf$!slpeKv1+duAL
z>=*|z)VbEhAh6a*`<r?XoRu41`Uye+c%c*%wwl}b)#Ng;{FSwRPRJL&6TM(Td83FF
zP+;E>$LyKI#CUXF(SBhIFbT`zIYkJEpE{yGN0I{IFwi>6Xyh1B&uHWrP|s+@A%J>D
zBN<SS0Fex+M}SBMv_R)1)k6EHEC7-p@PiBYg!R9+6Va$p>tc{a&BfOUwr4{V-|Xnm
zFjhYHum|NK=falmu&5DBMW@J3-Z(h6ow^5hIIy8qA~v;hWh*u;+s`qsdp+*GTTgwH
zI@&0rOH<Fc@x2W)^DutPA&dW{FZNCsRHY!GfD%*{lzE+`g}T(G*^Nimo~O<aR;vJr
zLYmN7n`$sqGy8aufv4kyFC^3bpF%HLuiQZ!-Dxx$jh<}~s1=b~DaM8;8jV)rGHzXf
zM?Pq75E)R82`$i@5A??2@Tao>!|T<d_qJ@*YkiXo${SuDo1jx+M6HGdbbu8enY!$;
zO%r&(r{6;ji~>MlJkv&|D@UMk-%b3iLJ-v(_YwpWfFs3YBI@J%@q<(sK#88W0oQ<I
zB48CyVFEJI^Tt3Xdfo^e0htJ7B5(*~B9Mu|5+Ef3N_0*^Qfin%kYGtbW5L~T+&@z<
zICFW8TqPwX5n+)Zp-5^guyva1TofAUA1egR0>gq;%h*{&?5E<DFzWhbpFCg73SKCe
ziOW3n#$Zg!kuF}Z@`JxFp6JbQ%0`zufhg?CBlrW8g8hP4GKw79l3wM;@!Qz4MTs0=
z-(Ft=Qt23oC=fXYIzUiB5nu}l3Pf^1P#}`=Cpth8{D}^TWS|NN3Mc{ykWv8+CNSH}
zch1eoqtDnA=dSJ62rK8)%>=x%etu-Wfzz?_kMVBbS6_I7CBwrp7oZ$medW*KGAsA&
z2TG`FOaNi%z&)PKb3duA>Z3)4Ej7k$)Sw`cUf*@;o;vbi*1|hhEBmjrc&0T<*W{G9
zfx?#UwuqeGq(G?LFq!~va|I|#gd@kmlJIS=1pK$T0yq+&2$1LiOJG!h>s$t$0=iB}
zDJW1wlNHsL$%T`dYCPP$;f#7|um+%oG*QyT)bKJ)%-$bstYG3sc+|yIXb|(7?BA-6
za0b4a)ASqBV7V9~G&TZ)1l;eJURb8TNVFd>^oI=@(FCh`vs}$G5S*f@&W*yhCS~oY
zzTkDkjlHdu@c^Jr&OX~FAt(?zW(`)rrpg$1lnRF&0h<crwg}-HB)|dB=oLmoL=nC8
z6#{C#Xeh-gkR{~@28VI#5*7!^q7@VrMS(Qg!ypMk%L4}1#>&U;&==OEgLsR0s1@ZV
z0;CI*Xnej;wEw7gZhI%5K`S@LG$2NM2gbtQGw$~6&DyjpV*l2b7YpZ?RrEy@P&SQ0
z0tzfE4V6j~-y#vXw)A}fa1_AKtk$amdjik^uLj;6xE`=bz=41z1WHn^jQ{Hm>|lYD
zu?SESJa)#GXAr>60#+G|AVl`OTV9nGmF`zl_huXrB=Qatqrlr+m;_4jwznAyR>1uL
zjcwPs6Tk{4x~VX&n+ivao>cI!E24NaNGgnnXepZ(cRrd%o@9T|dPBxt?`_2!Y&1I>
zbSNwY`URYneS8%sz1(Qk?VFDi3=H)nzi%87V!m1>B5(~xUh`aj?D8ja3vKe^gy2W$
zKIS#^%k8Ti?+Yv0l8qiEt&V>=ZqH0i>EX1gbt4E|YKgV5#%_s%>IaXm0nNzG=H`YA
z!-Rs1xapR{19{6uY0V@NR)8(&Qa}_jHBC(HE(6nJ1y9_!k3)>6ud{Eg0g1uWHQP_-
zWIgAN-;YR)5JSabZ#hT5=H=0iLYP&Aigb#`ANCg*tzN(RsT`HJ9PUE2@uRy@)k@hr
z4WyA^EadAwJS4c`LNNjGBY;Lw9CG7m-SA|+r3ELdwWdO6p`g}kCJ-+>Ez=icf90`a
zV5_D6>Cc~Ijs3^t4)C&qwdq{C<3$J2V0jg))i}szAsg&)gcI4{Ax($=t_q_gHhLWQ
zt!<y@9yo;~3b*OFmUe@2_V!Uo!C*V$Xc3}F7()b(=T1VAM)*q~Qg|4>;Vk<O?=3V6
zbgjtfXf(ax-x(_eoJ=ro+~J?AUWk*yZlwie^i#?lyPlw*u!B;ygGP>4m3Yi%EyO6w
zZBF=^O}BUu(>x}!rPh&5#6<v$T}0gT*kVFS({yE%T{}`QJ5&&Ed>+1y@o@nd2ez~o
zV5l|ED?meiTG@@GkT|>&FJmR6sp~o^`=l!i2+H7~%9{L|^ov$E(?ChA{KjWy@zR9b
zK$Myi`vxstY@M*~*>(!&8H9mTl#!8DB9O3B;vkPP3M?dWV1LuN&r41>jU9+M@zDa~
zVsR1|;o98GT&M1zT@Q_x-^ivFO510A0bM^$A97&RJ$(UD18!=Gth_9(7AGEFZ+c2T
zGG$)(HOy=PkR}wF`gY}Kdw1C54hDXR6TIvcgSjXYYY8bSRz_ek5fM5y;e6dw^10<1
zG#o*dSj-C?go?m|DtLg;E-%|(G`0_ID+*D>MB~)O8aneX%^X2>_18Kf3y-E96N=mC
z8dxQ~L?Gk!Q1%0gh2z&lL-I5{S|))rTqq3E*)Hota$myzF!j=dj;`cw`Dmz+CMamF
zrq~KM!XQne8E*M6#EOAWr|(zym`Q9DP(|XYU|MwzW_0P7{8zSX>dEG|j)j4N@pu3N
z!XSnl1NU{+rDgjw+wuVizZvhD#KpD>&07aOcXa>4-Gh$c(`A${trhyHLc*UIy~M*8
z28HEU`4iq;IOe?WN%ki$cN8Y;qELxc*l3G10fn?_A_glpPqxOn+ttAPal+3q55K!=
z^}4>rTgV3K(FVJvMI<B%w94=}8N>{W^Ut}<-{6c6ff5=A8hU#J=~Zz28Ns-8r#hVs
zPaHj5cz$4<CKkvO%YdWsSPW34g3i24Q+Lc3JDZRq%73e4A2>|BBce?X%pIP<TKJ-Z
z5=3EN!f1?MrD|c|LUVA)9*B(lC>}^d&ofbW6t_Jq%`IybZ>(&9aC5ympm@n410!Mu
zoBeg6)-Ve8Q&frf@wIEF9}_3#R5W<`5~>;p8pztBvEhEc_}hlP4^=g)%}lZ^?QPJE
z<Dz`6CBRG2PA%J|$@L!DKlKX?f)8jKEu-)_u))lzz5&vOM2SHY7-MF=NA+7i0)6Yf
z&yeSqk&>VkloT*>5(C3SPRIVrW91(c`uK}Q$}7L?)d8ikSXv9LUAuNIux94!IG-MQ
zzJ+W+S&74Z9>{AF<>WA@szaW*V%5D^VuXaW(2Oktd8)LA&ODthC`sC)L`${J5**V;
zbYaPGUm)=2ycT;`8o*6psMN7{4?RbFsJB30cUVWM)-u|mjfeHSPNQ2g$7}p_G*>8v
zRRk1$KPL8|fs|OmYCY>+dmHb114%;MzloimiEGbE`?V`PK?w&8LSi7js;#tYbQbM!
z%5QGhB!|MsRax-bYr#HZ)3ouY-fI2Y%#BGK6}qf2TU>^6xw`BqOW9oBY8=YoV66};
zXp%I8mV#8>GyC`^13O~Hz&}0u$;heQVS~dGD%5JVTD%xEU~yrrj2#_qbBvtd05^sZ
zmsv|ZVX&Ve?&H#pMEB`$)H6(=i~xP50qCbl#^5G1MyAdwEPw&%Ypn$YR{NZ||Bih>
z-(zL1^sS?py)mPxufqNewKf+TK-oA79Yu(5>9N;)p15~pj!U8_zLAqw(_~*1NKjq0
z+PV~UCEPDJhM9MW6|x*Hw#19hnzxV*BS3{X&nw8O)#9FQt(>%<E6+HQ35d<S5d8!S
z0#=y0x{pczKmL+;x2NN~xK80p6Rr~{&?O6VaV9px%b>6_yWFe01x6^`yKtZCxs;8W
zPUXo2)dWC50qN{zn>c5C;^k|zoFBiki{`5RC0<8}`3xf4sEyJt!5aApo*ei}Iu1k*
zRAT}i60~6VnQ`2kU$4!2ANRs5yI$%60rcW-@d#?E9aq1$W$@{m4UbnH2d+(pUIHt?
zW`<aj=f)oDFW{wgD+Kgw?I#vV$t|2nyS`oT{=ZE*-j|gTB?5&MNED0%=R%|jKf#qc
zj%!OU@c;kkuCaoF6&C*Aa1sqP?#6ZReR4{@=#(ygV9C`1RO0}Gpb9PFKF(oZgZZ!b
zpKjRMPUO#KZ$-mCVA{M{n3)GtVzZ4*k*ntj#*>uUY)#ORR^EwU;IZ^`&+a4b9t$au
zKxz;`n!u=xripPQ&(`U9!D_zw{rCnXOHCXtSgX})Jx?2G0#d0`sZ;=uvnaDf%gS|}
zscl!+$vQLh24h^ExLjJ0Qc3shpYvz>@HbWK$hOKTELy7|Z*o>Tseb$Ix0k3^MfAJw
zy6Z?6a966e0m=brQNU`R5(I1lN(*#=nE>S#YPqIB4wMD30U96yuLkT1wcg|T#&|Op
z^E?-LAyA51L6k14fC51kU=VN<ba8N@o4@atu9@yT{`$GY6sC~94<0v&y-gG>5w~Jr
zoFm``pqWTl!xHGYT%#O3DX`@+9<0&TxJ<|88YS?gz!sq(RCA_vSZQiTNmd7Lyy`=!
z=a3bbb>U5I6KRmZS}}+eNB~l!gkYQV?e%}I_x+D!;^iM>UA?!_DDV!H*cZI4_DQ{%
zkDX5l17`>ds@mg?iX;6tew=TI!=AJu%R>hnQ&VOZU4Fg(%pAMNZ9I|?6y>OqlM*6G
z_hEMWa*2Y?usDM7;B(1Y`$(H7Zf@g%CMjJeqZL!JyUXxIykN6f>>KNRorT1`L36f7
zN!r?YjWcn>_AjASQbbVIH~_b_1CDmd^gbt+Zp<`*@w<2iFY1ELiIeyz4)HNeUnqGg
zk|vA?LV+6l&k`$YU9NSlR$-{1fXYrnt;@Bp)hY-T6j0d_btqA`5|&7>>xr_)G~pN(
zhfnZQGn7i2C`lKIts}5Uo=M{Q-}nFTj~4^~G71+oiM0lhj*P+-_vDm#SvzNJCBLv-
z6tr_J&>dhu?)BUk;tbwB3iFLmmp(vXTA9$s5xL|6f;*RC0iYBfq$gJPx>COk$Uc$K
zh7%Yq;F!GbiFHrdT9hbLZQK)4WWtc($mG~wasK!J-z{SWgIjFO?=-vsl}e=&FE0UZ
z#Eoy9-u&jNyy~kOY2%I{<3etYoK9c4+=(4du(%Vkcp07@SmBCzOk-G+6&6*G@j)nQ
z+orYFTB!jnn1G|GB?zFkN(8Vm(o7JK0!vnVtD5W<;pDn-n7#IRo(MO5q9srcP_)WA
z3=v=^!dvNLQ|aky3EV=hO_gTEReULcO{#Vo-cf5)r5Sn2mjXOh4_L+xZcq#B1;PCW
z_t$|JQ7cC-aEBYi6KPTbhJXP&TSAkF{*ibw@M*xj?1yC(G)lz%Vo0OubF=B0b1qz<
zuS$Gw*`!*y?`vPT>qE=k?wYRsIF8`gcU=A0;om{t*ww@;S-?&^F=4yV5KfHuG82Bh
zA)J`>0xK=tk;nU?EIO{H-ud;p;Jj?Q5}`Xt=w`)4_;#nC^Mm&W#0np)b@`(TB~Vo3
z<Q9-5NumnPq_%1;Ub#1ZZl1chz)Us9$B=kP1%YdfQSSX*?&^Sa_=niCw80o-Otmx<
zp1Pn=U@>dQt%M`^&)$dkJn+VFCJ2(i0>w69VcOe;C7LCv(x?Jb=@2;b@i>q?qly5R
zD~&23l@5U;ACCjcGpY!1c`W^~Zg9cE>;0{cKJR!oJ@pfhnsHK4P!dvxfZKb-YrnRS
zEsPgJW-E=>9G+9)8vsgNt7^I!Qs+#YGf%yLF#Q1&u>cW~7#M9XC&6BvV_tbWX2;L;
zXIL&9OqW=I1WRLLmL95I|2@B>j1`mwAW6HJ-QE}phb<n#xy=<^T2^LlGBK25Ykq{X
z>>yhi@M0hSM|0!lrw}rKH=xo?e4T|gpwZ}goT#ONu7Yu}DA>+hCe&&*8_m1pVw!n=
z5Dh>O;<7rA9B`e(AIlL=m>(SurDwIxTF<QXDW=udtO#@y5I`sJRN$ow4UlF)14NGr
za0c2b5Fjm(0Ez$t?C180`@SnjyO6o#rnd=-+m9<&0vPO~Z<cIoZ7UrCsn*jTL#nW;
zwXJjnq*|ZjIjpc5%l<57&;5JN4)VewjU#f^v--Ag@jHEB+5iRt;pQ}w)vMKG_r3T>
z|5nRb!LS<XwXXBjoLWW!4MB+MwQE@mr0qh>Or5MB`%PdlKw|^qS~_t5UtEaAM^-%?
zKic)_qNgc~b)v+?RF2P^au+6VsKeu6WwzeZA{PX<9$}^KwF56XYt|FDJctApx>U6d
zYNjU9rMD?wzP5nsDeH!jqeg*<5U00+wOxX(XN!uhw$N=SaH8FbE3DKRSh_O;sxeWb
z&w;(C9R12yt7Q0v&oA4q`X|j8W2Djs==Ri87aR%*l6?CgT$eq_Mic}aHEK1wYlwDo
zhhsUMs>87yPDO7Y(5p)(pqbJBlaIEpc#8cMLrwe`E6^mBE;@_Hu6W6h{@t#z!jH?S
z`n}N*FO)>$WQ=Q*39?$1`%oQg=q&o)#Rte@RpPRg@8#H+gm*U0B)U)Dvk|)Hi8`Wd
zuWr3gJ+4P)g2_9$8#QL*d&?!jCvemP7d8X;2JYP(o|j|U^G#O{)Ot%VuV$=K^g*uu
zrg=7Y#tQ-ETKO`ZjfQt{zyWb`1sEJ09PCQf<K(FDzN4e>vWIc1d2WZNDD_?Qnx3c{
z55*$<n6+@MnLnteW5=<L8o?58K!_U<!r%tiO-QDs^K3lL9&2WUtCLq0DiK&rsPoX>
zHQ~aP7w`>`LCgqX92oDS0kpL?wJf1ls<o}Psdc$ls<o}P8Ou1GgBYGhfKX%cLwKC?
zvTyghZtz}<T*(qGV$e4d=Ll=9i-is=pQ&80&Umqp{PWTAVxZW_{U{p*CEoRbyc_A7
zmSf8W=7pDCnEHVB1tCstFLQ@Jo<p6mtb8b9SpbZoi){(+Hc>g(iqFy!VmwZ_O?ZJe
zMH5h>M9luDBk47LU<X0)Q1hm<dnTN~wG>FJEu;81xK@;*e5XOY5Kv8Myh(&`2+=qb
z5!B)|y{!Ck!AI1)CT<KnCq^X}4iB@Ct4V_x?0nx>zc{X0DbM#1qBW_;_<k2iL6k%>
z7-Oy1bI0ffb!SXK$r<aH%>K!%uEXLTxLI)wrM_Js_f$*P+-`_(3Q3Df5*)>V7yRg_
z>G5LVUjgL{h87@kM#Ec(kgkc`aZxRu<p#e{N}5g8o)1ixfOoJ|!hsIr5XUWBbyw7d
ztnIG&K3!>1NTzab@?N<A3_VzJHI_5GpU}Bv0sVLUTWz&2d6NCDfWm7pd*vVs#V3jQ
z7Wpsu;jdc83ZagtSuN^T>(VZ*M3=Ln4LA{yK!VOj+qiM#;>8;`dX#;fl|TQV-;MHe
zZW-yQQDT?8J$sHkweRS-AuN7arfZ*+Y3)sWzN5q2+y)37*!cm!I6pe?#S-hf710hz
z_qPD8dwSa9YCty@dj#kLE@3Qg07?K934lWaW&qq3YPqIL3KS<)G6?W$tv7o*-ovJn
zDfnW6BA6CY3XYkpG;voRyKmX_8S(>$dHH~7RRJ>q)^!mSz-D4;A}vseO5Iq}L|Wil
zrKVO2>`mvp0d8sh<b%Nxi~CCM!YWOe%l;xewzNqL3U>lltXQ!E{m92G4MS*Z2pi+&
zYs={1?!Zeb9z%%LMA3c#hzOdK=vWg^D==yleHBK^E<GQjNmb%{N5QdXyzbDiN|gbP
zrc3N45&<M#eWgv)I4W<uhoD0U4Oqt<V+ih;2glJHKB9iXwHDaeRAW9Bicf+DE7TzC
zU-&~GcZn4Y%m{k&KhxHRkG52bl`*ENVx@#i<nYdwZ*B7wmQ)TcmotXUXbhk=<j}p(
zdaO^FrTbl+eAw4o0$t=3npjzH#LW)9YsV3;cD=|LE|;&58pP~g|AJ0-flP3}!b9r1
z^ZVR;2!&mm#dS6n5yR4WA<%NOvEzsws8fou1i&Z=WMrMm9EEmgKK$Oa{R6V@vM!WL
z=<G`y_%?2bo$v2+FS_Nv?UMyt-b5f>BoW3KALnLaW{$0QY<9=h)&tk~c*5+zC0amd
zkJBdO1R8p0x$oku$7`Ua3ecz&Rl_$M`TQTaKPp~+Zw~*tchDGUP>KsT3Djy`G#dNu
zx8Hu45x*ZN%^U+SGu}lOraizMIcJng%>H5#0t;sh+|9up{=}&XqfaDqV-c+|J9+Zt
zbUJOd21qlf0n#4n*i7t|@rif|gq7o0%I<Ub8tX`)0??mS)1Uo<**?Gsm;{a>y<VH}
z2wd{?>#;vai*rCwg~CY!g2lmMPsR%wj%QgGtSXKcs&P?!uz?mFP9v0??6^9fv|nl|
zG8<SxI{VTGN~(n90VlornLC-1#HCbmLYF#{7s~pif}A*(-?z!e()Cbgj#A1k8%G`M
z5L7Nd1HlaWT7xtyg*q!>kaib*|AQ^@a;@yVdOYx4Gf5KFc(7WX&PkFa00zUZkxRO9
zhNBV<D3?leLTih_Mq)Vbvc<if_iS7`R-9Pq4^x>b{~22QzQ2K_nUp4?vr9DrFXK($
z^kxsi6-V4yT81*D$busJyX6SAE>(JXsuIvuNS=qMDgjM}G=_c}eQrdBa@P2AAK&kK
zf_^2p_Bi)}h)vLy+6Kw0x;nB=7yQuIEn|g{(<LFZy1+}u72`%TA)YG~nRZA_T)R%q
zpSk=Klprq9gAO{5uZ6E~g)7p%4P>ew{OT6Q5<{w?tzGD%@;x{y87V8@L#7qGPd&P>
zn7{M~^n-wYMcBEv4^N=2H{SN)3AFX5)i@XmMtleF4cx;HE_RNM$u1N>Uuw3(V46l5
z?v9tQEi-4wGCK2PT&-HG)q0Yqmev|943%Yjc!@NnR@1~z)Uk}2Ytu*CM=~4brNi@r
ztT6(+%`(b;U2<`$mW_);I0Y6gAXO`sB}<lcKtlpHbbHQ-3JW07)Dl2E3MewM4sZ!T
z&k|Twa1>LZo+zTxA`8=&-$#z=U%S^J2uvHEmZ>9FiURas5iU)Hb^;YU5}-(hRDpH^
z6&n(uNQG2m0sVj?R9L!h+$NZB7AAocub=z&`XepJTQUqxvs0~Afq{WeD^p~Z*+#Hg
zcER_3)+JUjkQPw=kjMrhwgnJP5&{`l=~#Uio>Lck3fc~2g1JF<m#^hD#Nf#11p63P
zqjP6l0h8$p2S$sm5XI5*U6_=W<67J<x>h#XN}{UloRvvRV6w_2B{1Fn=%9&btPR`;
zIGTUz%zngqQ=mQ+Wq{67hq{dTW?cKX#tQ}sBDx%1p3H`g@nGo2frx-AqeiJUc^6K{
zfvHas3Cv4_*7}`4>&_?r)LFOp#PQrVR}P`)hv?CmN!tM3Oi2^d876@e_|`(4LsUDF
zex>EYFK!Z<AT=Y6S*YETT3TuPEdV-?dZs@CjYpAMN|%d_wSi+yZer$w^_J}<T4SIL
zctoiLAVR{1h@m{wfm?sz&g^(GP~v3YaTXg>kyx0ljDB{n`8<B^g2weq^8&QS7i8NU
z>TvGnv@KB{en-+vWlF_Tcol}4u5H!f-KsrvheA7iv_}NB%tjytO6aVZ6I^7hWj9VZ
zzjg}UVZ0-{G`vBbqU*c=xg*B=;{^jt0-Czj)Nku8;^4|e;4k5)W5((`ZST8U+d>Jt
zuA2t}(V&rHci#C}Ga7d?%~tENEq2bFt$KPSXsuHWG7}ooo{%YeKm7z!ASr5Pr*v60
zLlkr=e}CYFx*~hwl?bZrQUyV069mwiFbKZ*OCK2=etVaig456sF&TnNrBv#ICXTG#
zIX?V+PrO_!VE*J@3U!Hr$ttoY@X$-U^enffi5EKNrq+EnAr34z%-x*2mMHc|HIP<~
zFlVmTbZrlA@6x7?9-gc2edB7co2J*Sjx$GU>{)5w(s9?@o?w3{@O7kgGcg3ZA)=pl
z_BYSsVuf$kcKzFX^R#>eVqTj~(!7Q7z-jo><=%x6)!AnZ=s#Xchz-3*y=ZE={UT{2
zbRSBc5I4|ONr5EM=KG!4)^T;g7BAooXHmjS*_%{*IF%|2$b5hhJZSL%8M^Q)434al
z;z+<_ntHOs@j{@}J%7+<Deh23TGf$v${ZIwZD0C&J0e0i>j2#Y1Oxl-V}(m!{|=p`
z*kltS&Np<_htpo`Hg%e`*9L3dNCDDNnv1u3aw^B<J%@XN_Gz@#DuE@Uhu2Fgjsg_v
zG9b#_G;th8TX7P<<0Igqpp{$x{ah5O7e#`Yn3?B%^F{x7F_057|K8Y1)*rB6Csoy*
zUmq9(QmX}8U;x~LPgUL`>~7`jeD2Dx{1?CQG6!ZHm^uxV<)u;&r?mzGf}s1}&o&1>
zcBwj@*bHwyyd!3C(4+$8G`UIGwiSD%R(S<R6R@EJijzE-ft9C7sMXY>8_9rrTu~0b
ztAQAJbKv{;v~1};yM$V%9>u2w(NHon0vR)0+hngC`kMP#O0BU7iV_>62r|pYKE#JG
zipG~LvGTs6@g+H7Ni=ZA0s$6uPb$f*P<)i2Vu!(*?45%bX0D#732OzYRG?C+RN%%p
zZjd@>h4F$_m8QhK2<UFRyI=CZ`lS6veqqyX3Go^58fvL_IOcULwc+F~`i8En0)bP_
z&1=lOfA9Ey*MIVApu)^o1yChtEI*f@n|4D95LrM>*5*5u%Pzc2Zkjq1MjH}}PXN5^
zz;k~6leBm-aHl7{GaPpaRs;Bw7n#=9gWQ4qKy>NSay$?OHrj#19K>Nynvbhf7+vnF
zBqWgLz|C5(eMjj94{>2BR1a2=*`{JBTx+D$NVd4_iKp{7PU|(6_QL{VaRJmS%Oc_5
z|CIesxL%`HTBA`6Numi}+1B%Z-Dh#JLcq}|qw_l3(tGoG{na=NzQG;aPT3oNxg7&%
zfx#Kmm>@8XHfc2O?<?zj9g-)u+!eYioi&-kxygH_<$B>b?8zAuE-ZIo2|d3-j2Nt2
z2pF_m+_wFOlkwQJbIVzDM>HsTDGRVfu|aMA9)9pndEm0s<5jccg+g`DVjvmA%e3<?
zHpa`>7V`W~s}q0F)rnTCA|gGPLja>qs$?{C6}CTnPBpa&8~H&xHbx8vsR(?n%2LX*
z%H5u}K1v2vxSBMw9E_Q?3Q%rGou~1nu?!QFsT-!`<&rTb*mHg5p?k?a2d{(!EHQ{N
zKxSH(eIp$UFSzgmK9gBHws+!5c%rdn_~5T-$&w{Y#)}-083ZM2^WDbaZ{Q=%H!>`I
z@V%WPHxUeVk)||Pt8<Zd-mm+tbF5%smSypqspA}t4-@|qIq}A4=7!6C92zB5V<3H=
z?P75J8`9;biztQ@_VnnwrUY%Y_tccVbX;Gt$ulhPHB~5;QDNrmn8V2{TK;Zw3#a71
z_BCRsXUp}v3;N7OZuprv!4Rktlcn1He2_PS15c0_GFtladaYf5?*r&MNl0oH=d5X@
z@y>X`Qmv6SDM-&2#}a|#DmsN!M%E6i>&bhpw0=ZTjfK(z-6sfomlBS9-RWww5707K
z$P{S;R-1WoJgJS~z+g8vd$DrD{+2^*5OfVsW&wp|rm0EeE#GqK2VOROwySZemO>5X
zDt5%#(S6UD6CL2=lNcFV$4ukOmoPTlwSXh8Co-yJ>Ll7p3#X%_Z(wR?o%gH19u+SJ
zO1=4hjffEc(^<($`5!#Do_MK&8$@F)P*sfs$mi+Z;%-l5|A$T2gh}DmNmnR$8Q}ud
z<LS+gkm%93h=Mm76QvA-2(!P%u*N^?w0tF86K&Qq&V6>d$y|h2UPxG;j))eLu4G0r
zWQ_HH+Q0Pj`_YK+A)|$V?o}1ilrBX^*O*wo#ld*N!^Aa42`eo%(M*)r?+J!lT5AA?
zN-=N@`9~i~b4nQZeI)wC)yjebrBbP<D;8n9U4k8+*EiOxty9y8eq!xLYkc2NsdRt_
zNR?K#o}Cf}G@yV?pkbh|6vs3Kzmr|>5_QFO=56x}uP||At*IqgA^;(*$jljnRkygs
zErg&rZLq`I(N4j{FdH4acD)?IY4fpnQ#xqX5R^&)A|g~&WX1qjUbOu2=aMa~OhhD3
z$}SGYS%HSPkb-dFfzFn5_p<YT<?R*mV&G}-@Z5m2V75@43zrz2;a#|~B_R|p^>C@i
zBqI~L>~9M9cHs+6?I+46vBXq2Qac1u6s2@2#{-nro5Xvt?zz_@8(eAaKQ2W<n1doR
zW8<QOt@T89?O0=_<Y{S^gi-2}T6^Xmiw1*02|(%T6=AJGyYW`XA8FIlSL}(zj}W2g
z^bKAk@^IhzzT(@sSRtUCVQ_T`gFV}Az**FK1aOfmw^Vga+Zy`bf2bRef^>?*J{=2G
z1)3_3d3CyvNtGibV@V(_m@;L`k77F7Y63d*bUc!w<1=l0eBkYI!Rub_O;zdK9R+0O
zm<Ct7+WhFmY4gkuLN1Q26Yk0{EeT1z#^2|;^Tf*zq5)beQAU}C3djrrdJUD4%*KNn
z_r$ho%pEZ3QT$3QkhB;P6U!uPnxE;0c=_6_%cFx0270uy4^&TB)4Fy|U4@hBp|*um
zWFb|`<#IU&bl%it)TZpUpL;w1`BB-4tcP{&5n9vb)V7}6d@r1c-?GJp6>o}2fjBf4
zGP3c-!1?uzbs>;Qw7D=)A}`CY4VPcWv$M9*7{*2kP>}A;;I)PZT=@j&by1JGR$M(#
zKzAkeGJLxm&+#?qonr+9=??SXx>LkJPj+Q21JIBv48GjWUnM#UJD$07`I*a{DCY&)
zg%~s@OJ3)9*{%vsa=F^u(7^WILSqaSQ-%tZTd4rMW7<VS0+zsPOvigbCp38aNnL45
zYW6yC)TCPOn2*6AmAEj%uo>*Q@bq(^z3uw!NCl1JSW<uPXvUsL2QDT|H!vHwu{$!m
zWfI(IsNiz8^}a89|B3gx@o?D_x)Raycoye?1CpX3O-;<L@j|Bin~YY5>vhl`YbrCO
z5+T}c<=50R@Kian(I&4SRC~JCjSbx=`1C6^X@9AHY>Hu9t?<G?r9u~Sb?$oX?elA!
zY%G0Kyewk0R63V%NjJ<4?c;DpMg>Q(;402t9aDI^JkYYRqksj5fSBxEOK&L*9z&OH
z83bN4YG_r`Zh(P7=lRM<Bjd$DX_%Lv-hP?XRh7C(JY__L_m;8MevF;RPdxui_<&YQ
z1_2^Hoz{6EKSL0)#l0NGp-)_py+^kmev8605dtc74V6)B0=U_IB=rczgcs;1^-@Y@
zOVqO|Acfx3B@UdHFPQ1u#pCJdno$8przyCoj-0)<$%FDAQ$ZvSaP}lWqLiz%d2lqn
zY0@?GZ!!)<AWcEFt0bEK$#}tbJv)+;0+vXLR|#Y?qaH6*Fp=EPHaK>jlrPbW=p!bx
zS%6@N6Mc5Q$~(#4;lf{i>#Z%(bRC7}>d*AV`arnR(dgHgk&qHG+CDgSXRa_t<di6+
zk^&~eHIY;9nfm{08#qHc6N{zNlBF6L4<&3#%evC<CjdxP>0IfASC(|PZ(MJRmk(p7
zcog5Dzl0^)x%Gh|AhlYc1qR?45RQQbS)f*1v0`thVC1eZvv7*z#GNUqJzv`3bBw`0
z8yxeR*Q#~w1c#NFz9?M<(13^@kmA#rG_Dq~M*^-XU{3%V;2ZNO#R;hAvd0t@2}DoX
z;8_64Q`}OmH+!sxs}T|4YT(s?H3VJ_6om1~flMMdqeogFPd&gj^ne@L3$0Ro1JeXI
zVt^7QAbE5KslWi5@*)e*HBW8v@VYg=ks0l0KVA)@+zo}i5UIznYfcaR!uvMTb}<$M
zg-1FP@SJBkV^}|by&WqH+=XNNXIcp&x0=SzK$<KJ;=CWTy*v3tce~r3dpbvV@kG%m
z`#Z%g=lZ(u;$np`hf712zkYB9v|n}Sv}Z*CG(n?!PKtA;eFo0KJ)Z?A@fpTZjD>qX
zw|S@2qbeEx%UWSDm6XoEq-k;mj%>DT6Zfgd^>tSZ3Id5CdVWzs0ddBR6VJ*M?W=2h
zIbt12iYmZ@R(G||hH0yCHg0*DLA$Y@I1PldPvc0!y{pe=rkSS3py(7y4K(#icg2f=
z&w{)>Wm2-V*ihFySiJri3MW;nUPg8{Og*|z%S$sK0MHv3Z_q}lf_)EgpBJC4@ncnI
zwnRw}5jrtlf>cuU%Q2ZdChs}a#!_NZP}Q+pEWh#d2+zj>@4in}lT=gz(W;YXom+DS
zx6Y!4X$z6CC_efrmp5HjwDFj13$EvM&6-qobaXWBBq9Pt(_eA!um8MXtnevY*WcaY
z4n|IYKQXT!PueXyrso333m@I`v`$QBjbTwR2JYoNeJ7KZQ;lR*{Ci483t@6sfYdc;
ziCEp5$`)xn8UrmsIW9m@T^tQ=d<wo29y_cvEwTWTgn~P=lviMturqLWe((oaFY$pT
z!Z<QlW$9rzjy~_QDk)O+jU0+Y6X~STxa#U#C(gaXc)_^Ivu;_}tk;YxB`0Gv?TH)$
z7_D048?ZwKg>eEYdynUqkvn>3tg)xi3saw<yu7!!x3|a3=OJs@H3;^pocwdIS@p3j
z`gUvKre^XWFu6?;eut1+#}jBsV>zBWsnM#`j?Dc!TT;tk`yN}ru-PNR0AQe78jx91
zqAc|GEq|sue~@T~oDwwlH}PIwRSQgRhYO+_#sf1waLRqp0P}~2X2Eg>DOS<JOU8}G
z4?454l?EpFTnj6~1bG~Xhrt*{JE7h|bM?(W(=ca(E(V?NYyS6{@$!**g|{|{x2OyC
zo~ZWFP*YW?xL{5D^t_m7USu%!32xe_N<0elyH4J9b~D`dAsq4i3sus0e4Nm@yyN6S
zI{&W0)Xp4iQpxw!12gqt;Ob$#Pm|az$w(ALgG(=*OLydFAn(jB4#yEVMTQ_r5`aV#
zBH<r5VWwVMD`%ro2Zp*gixpM4g^^~LlifI;-qN1O%r5<*ti(P}N|l01k|<z{gS@f>
zzpGfmV@Bsau8Zh-?GfnjiDI3Ktq(M$Ng|^i&YhGWgvQ3)M24tSZ*Ol8m)BbB$>q57
z>#Q)Ny-Z&|zM5{)mQquu;sXk4gWnm;N^FwMTekH~>s2~Iu4%brw@;I}v|zmzyfE@{
zx1V^1zA$5TMb3?y?b!q-;z0e#RY4%p1c@Y~={h~%xWWQ)sj8GpMq+&^JYsRLJNh#n
zoTdpy%IH<Tf!whrzqaJ&LXu1Wbi5e&EX>j44$sw!gk{8HYJB6CTV8sCXIUs`qloko
zi&|^=Z5`O>M3%qe)w3`9-0`7E8Z9QeOy}Jpqnbb}8(uxf!lYe064yN7GvpRB8^op)
z)~{RQjHNFrJP!{|I^GjGQB5GNpcGam4P<rLy28qxm1sE(#RHv7tZXxmx8Ai0trmHR
zHnl4bT;rR$rBj#FkZ<uH1N&kH1Ea#8{@T0i0ekGRa^=ovsHL?AU;s#v040s&kd-oS
zMwxG<jnDr8#v9I*&t2ib^cxJC0DWMHdV99KP|-q^NR$YO;9Ypu!=0h;bXsu3(WJg^
z$*Q!~*oj~?eq;axXiU2kGPf!%8ED7Q0F9>sQl$*snyL)M5m}?F6Glxeayb+3BZqiA
z@%B8{aUv{m_JS&a0Hva27U2P9wmI<B*GF1B71auosEzNvAV3igtU;QlX?1+>@w}q!
zjQC^M|NSyXDOWHwG{g#)$+MhMA~0~%<pUFn2Q2QrUAY`u>6T$>?3FMuFffp&z)&r?
z!(PH(#zB_wfPo)l1*6p-)4)?RZCtgV7`~N(L;-{pX?J4!Dx9JZWQ5XU;&KprL-sp~
z6=uBrz<0bW%RyZc*Ywp&<qF_Obi!3hbkrcya#q@A6-U?mCO<=||Bck539;yjuC~Mh
z%IC7T?dof<HG`I_0vH5crhu%ut639I)^81D7t8`M1gw^xSuH}j3@}4D$+2m(HrzBC
zen7F6ic&EZ9;0b#PQ{CXTx0iLK+S4x*8>g!M0%FnfU_7&@?^M`NdQ$rNQfkUb?4Sy
z7hZ5iser2X_HcuM?v2C1y`Rp3kDR&4#-7NQ3tC~Q7}{t$QF<1%qACbFVS8I_Y^9DB
zk#U_p5)@IuOZ0FD@8%?K$4f0dtMAz69I?#>Mj$Vswa^p`=clXEv=Bl9-0~$CwqA&Y
zA$r%YH3Sf59Z)JUx!CN&qxc;`7Mfm$A0zD|O;aih!6>jUSy%ru@K~&n<sdEaIZJCl
zk;Y2mT|M5<y~P7|Z8>Q_cjJvv>O>3%fsKn%ZPEb8z2VF$|NQMyS!J2qQXxgOX+x)4
zEe#m;jb1&uS&%a)_8Y!n%1C-JsL<o9vSfX3@EqN@!{qEt`0e;Aubu$Z=vpXv6}K*U
zI&Rw?bZqR3FdvimMhK2<92UiD&M5FQ2D<2azh)BX<d%3ba960)XN{futI-2rnHmu=
z4i*g#?wwm&?i_fjqjvrWwBNA2R4Vm}^mxT01i|nR{Z$`qf9~nbXD_;`(<t*04dm$X
z*>kJH;7JvliDj$+8X!$ch6s>it*oAwg+o`l&t#4i4EvUha$X965Qk$UWQ9wg*jmSS
zJhuc@j1sA}W~>D$)oOKoysOTttoddxKdEOI1^`u+3LTJU75lCIdmV1$=v>meXPS|t
zbf7y@cNX5^bLaGqSRrIN!>avr5hd!<(@e9fD&iDHcvp#L<Z1i0a;a2?#Ugz@TzX*$
ztNv#PPX2|}<9+9UZOeRoI_EhGNFc+?h^QQ@TFZ6h`0NQc!XjyoYC=qk<iP*r8TP5R
zH5535l_DZuf>}D6ox<<#OnmLq3j+e68k+4Ru=HWTJ#CTKxpBHH8%m1?B6Uw2_%T-A
z(9+&%>Ug!5xe5`9D^0YSh$O1cnYLr<=}ydef~93jrM^C5v9HfbHOn@*ud7~Pan=5A
z!%D^YoicJvkw{o>X=L`Xqw<Cadj>GJoT4T%sDQ{w`tlbR&d(j;d5uHyZH=PLV$Bzy
z`OG!&Oggr{Z$wlDI!LoF9TCc{#Yxs1vaRH)B!Fs?bfFkI|A?zPnSW=!e<D^eFx#m4
zb=O^YRlp<SWL*IgB?U&Wav3|%-mi5S(V#?ZYQ3eX$R$gTdu?l<ll`^!rpb^<32C?8
zrp{o8`R4CX#b)KO3AR#Z`e1Urpkky7+Vg=5h%-74oRk~FHPvAyONt~#XA#Y>%gxYv
z_`ypW1G`-Jz0Ao(wRga8+&efTdp4zI+}Oq18WoC_W<UdvmErK820n}xEdAp9zrW9a
zZ%Jb??8L0t3w>Y+NUa1Upb2Cj4UaN1B1LVi-1l$2b$@^VZ@ZO5yF^K%c$P}im-?Sy
zKX!K*1RjAP+?T3SdLQUJFRA)oQ*|s7n4F@_-$85XDy?qyvPU`Omgn!%_}o&UNN7e{
z+?7ZkdrN^=Ypj8V=T%SQ%>h>g>=B>?HUWDIK!6opSSeljK~Xh8h$A;3t4URo9sbOX
z+Jqh6x$;m8(U^@>G!SGgQ7Dy}2A<`Hskh7C*cB<2Ai<p!C#5S-1dIbUNTuemvfA{F
zz3JPbcLafnm_L6$lzYB12IqafueI<v>dD?8$!Eq&vy;eKq^g>9p-{(T$7FalB3=yK
z;`CRKe$v0{^Obq-6GcNq$=W4iaK+b8uJIuf@Kj3~>^;!F9OC%daedfWLnnS%Sa+%Z
z;uu#oc35Oa1fq>LDH&db;ji)I`yFh}GuxgMMwvf9fHI2{xcMzF;?i>)4;t7j5)fih
zP(I|)gyIqPCcDr0R+daqB1BMp9es@)I|cEAnNM)T>kDS@v?S2^q_qanFm@n${YhCn
z!`=7mDqxqaSFDAq904!%d*@W=(5kYjowS6Z5pF%U(Z9d1oo}vLD!~XeppDLaB?L-0
zK9gS9Mx`8%C&-d;cviyWF+PhF=)Xz(F?9-V`gZe<Edw$21Spq#JQ*=qw-6VsY%z}G
zk$Y?=$f=Gl1;F8mNZM6hL>!rXwl8<|m&c2NH;wJ-yMhxKjCrnMq`4?v50c)v=KF&y
zzeaax@XTCD?_OXZaG&SD?DURpE0EE-wf*lqVQC`G#e!Ps&_C#LGY2_>Z7_K0l1agf
z-te5dEq7d&Z!1#`E5Q}F8p)VBUE56JtUYnUZV(^MjG#&!_AOrA7YP1B?uD1#IJ(|8
zai8nhho<%f;zy(uSr<%=KX;VzzG$+zSiy3fQL<@0-;Ld@@$7m%OEU26RA`+JP_AD6
z5Aiffk~7@@bt7~O0<SOumau7W40<J;^v1NNd@Rf1e_!tB4seTGbewKtYs?Tx0Vja8
z#|$D86td_&cKqpaZrI!=4%?x1D>}oKC{bGa%z7zvT=B+Nxf`=y0Z|$KnxeH~Yd!Ol
z12f2vHGdc_+>@yqA^>YII}s0K+zXcDgk#Csi$>YSqlm4Lf~68b#XvKUSr;z`J^&6u
z@xI#0r@FzhR;FP7>&RDxYwmOpdRHfyH`gOZgTOrNSm&gl`K@ia8|_F{7XH(8zP&^s
zqbl__z4bo2b%LAUSZ*3S?~>ITk1Ru}{lNK*Pbpke?Fz6~_MLSFC0&qF?kbmZ<=OiL
z&S(!D-odK${9|uqh?sw?_oW@dv5p_vlxQ<Dh)9JZO<)7niiz3mY&ypZ2IlSX@?GiR
z$ueQK#EGR^Ce=5QlE!6U*t`A+n}i;rQY@Csno+{Ne@qT=*qZH1)-E2*ARvUn%%yB*
zj3|KZ_QSrj>1O#WQU`)L8V@ZmpD{QMH+(YF9c55pf8S`9NhgH2s)lRq!aDS+X9w#-
zDF7lOJ(;MX@@b3#jJ@}JHXix>rRhFL>Sd&9F;ENQ=!Pg874brmY4QCfjT>gmo*lYT
zeJ?%Ltv5b;32fyF7!2SE-O8)djY&EFP19qOqhzn!&>n;D8#>Vj0W=duFRsJmfBI*m
zQ+gFH0PPiJN~N=bZ6-C-+Gv`v6EtZ>f}OD)j>0qbu9aV(u`oo45Qn`h#n>2dcoT$2
zH4a7VAAu$mpET7}IJ(!&%rAz=%Rkxpyv1^6NsmAN_~X+z)Y4iF&{VQoz#)MsN-=(l
z&(M^rywPIq%e~<*wuu;!giu15K9d;)L$SD<C0?YeI&gP~aquHYwW04;h2^4^I-wOE
zv;o?QXpIJF#v*_OWD06Pu$^F6s*>!E_X!Vs3ZnoEl{Y${l1Jb(ok|Cd+*nsQa85rq
zV-1<r5e#4@`vdy|m2N2@=)umBL+e-rZEMqo=FD>%90)>>FNVUkMi_X-_ie@sPK_yd
z9Jg=sIW@EA@|jz`cbcY+Mx!Aj0*yp=kLZ@g3-|He6uV<<NwZ}BYu(T-<9SQz!o#jU
zd8~qYc?pDgp};}WPGrOe?(YjPS94qwCX0+fhC0ez77$&1vqbOU1fM;#m%!qIJQy<r
zZ*(;5SU>S+<E2Zh=G+n37-y&Xb>*G#Ghk-Z8Ti5sBX2AgVqo!NfWG`7M-&Nvu!pj-
z>8@<rU^5D@Sf$&h!lRSU`u5?5c=_BNUY?^_E|;_8HsB~GRw|WBt@*z1lluQViN5aU
z!;3yelheBh!Z7n`O=@q8Pxdp+v9JH>#~ZWZRAr&EcqoG@3doEQKrt~^uMYRz-JbdE
z0S;#I&LJ4QQf`+mUf=;|<BpE=l2F0*Nv>!LSS$3V6V|33ZJf5R+!pCo)gBJ$>jN@D
z&ZS&S4oocG=6c`6>(q9fX}9LaSh;d#R~}KX*GYm#KH1iDzIit`Rxp`o82pPi4a3aX
zyYFz~*r25>nk#djN3K5B9&n?CAs#wTqJd*ym5$3gpNnnIs+Fi!A%o3aO;VD~HJ8~(
zj&;L|at5-Y1c7KzsKPjzv2q8Vrr*dNQ+9HDTbvYN<@_r~L2V{&itMrJ+5LkZ2hJ$<
zsS=aDlbZ5s<=x=^H}198p<39R?g}(bO|z(zl6W!jkx9F=)HXB>Ip;hJ48@+PR4SER
zyb)HU#%t}3ALbz|!49T73`6g5@xd5)LErm5+3wUP+K#SVp4@Soi5UbL%Q29~q!Up{
z;OmO0nCsYa^-Fsj;L9W1i$JxK&umo3A!nR_aA}E113w6#2yP%yTY1Gw($%=)lgXdg
zJ&9i0cp!_3$x^SunMf`ae!^2W9*b+*_cNZQtG*nFn2J3*CDdvrVn}ghbI<+8tv<1W
zfq9nmm)2@v{!4Q>sugC`!0LscxPJL}_yF+Kz=0hOb_9n#Wus~DZrrOFn$B{fDF4|%
z>7m+qc=~E{2BvFZMm9~RABWP83#aBg`RTdksIpT{VE??Wjy3d>TDh?CdtTPpry2_&
z1k(Ebjt(h2>b$F^3#*esicBC$5Q*p&#tW9itkOcrd2Wr2jHCd1-96(k@yz#M{njKv
z;2k$%pbCzC^)pN7y_l4;ww6)$eFV}8($$z`B#RbYODECqx`&UU+k!l)c`q1;YR93R
zu}fDNBd5f^ULt{g0H^4RmeSebe5jN5J5!4G!GVTg43Z=U(vcCtP81Z6CLEHrKqWr`
zgODTzNK{$1s^;ilbB;ImXT*zvqFMW^zF;)wWFA9Xqs=F@-I_bp>dzs8grmI!%LyGg
z<YC<HnX7RhxkYBV!x#`qCt|QRi-f37maf$u*UY`r^~le)+kR_!YkriD!MXK=9jvst
zBbeMT*-Ma6bfYq>I;W}RZCq;MbT>5YU_?+Q4pYG>aILl6&{7<Ow}m-#vu3qgrR#*w
z|Dt@h55x<__Q#mbt*>{p6E|^}m<umI?wyW4Fa)Gl0us;!vX2r0gi<UPeLqD%%gvO^
zk|mpOzWL@iyO|}*7FBTxCU)b8Tyjss;$)3xdJuSnB~Wl+o1<N}T`kAs`s~(#ZxBcn
zP0A^q=YzG1NZ@9me4GNsEd(C-n1U~a)jYY<0{ATi?gZ=+k5aY^1QmYJsYaDbftv&S
z(@31PyrQPbna!`6x9cs@;BQXaQX6yzE0z6j*kvt$s=Rdh5!tnA)HU!ZsFO0(#UM~?
z6jLqgP9Q%B6Qj1KZ4I26I|jbSz8}OY&~mw_E0@cR8!3S_K92`C?!{d#doG}M@WFp9
zutfz{tunz-tp;ESp|gMFcxSwP-`3N!nM(-DT-Q*Q#kXAJgZ`?^C*8Fvz0*w=Zww%i
zaKHmN>SbqTd9Y9*8slqCXLo$mSj)SWyB|B|{i^%?C_X*g+Nfq^G)CirDy8Ke1op_h
z_zlnJL)o>%D-#KMdBRRvgwaU39hPx&UU}~&FoB2?i^jq%!))v}89b6N@jYbS$V$-7
z1gM$V%yWL^Y3EqMz%h>T7nFHDGBT2)kSL0DWNY;1&b8>1b;oIl#J~tDJTaR!o9;$$
z?=fe_cRV$Ji$f8<iH7hyIlE+?$+eWfpSfp-PQ*m}iR%R${d*WR9;mA2(l>d%C*6N$
z=5*Y0w5b5qF2=7|X)2o7F=je(c0Kh{H<VQoK~-Y_S-EbvBZCL(wl6qQ(zIR&DNwup
zs#SPQvxxq-c;P-it^IFF7EEj|rLRB*h=kS>K6B=KABzB5dqUP2ARuWhm2kqFf9P=X
z7SV>z@Phx=#B1rHxbCpe;J|)M@JfR)7+NM=+L>2rhh^>HsP(u&*oh~KP0*4=%M5+g
zPtQvmWw`^T5~{?aj+Hx#$2%^YBBzZLrXC4h8iW8zl8DF7J=Ys|hsTS7Ou^xcl7VCN
zL%2v@diPcaj5c+ZN`>vWzp)jRfho=2e3VTOueXgRnA?~40w7BeV2i7Pdpw1M9oMQ(
zkK(~8^Z34jT-sDYJi3SSo@;bt$9-nfK6lt_?J=K=Xpkw&CP7N6m0~6XClL_M5b_Hr
z_m`scl3xr8N{zvy2C2<5NyeHAQ52`X7v{wC8My_lgcnd1i3N<D8@k~4bY!lYl(m2E
z0h&OivanLAzySvwaKPADGh!IT3q_`rtY`nK`<eH~7Vk5pq@M8Bsc*TwMYlxZm07?M
zWl_fAgr9jP&OyWY(^wj477hD!a+^~S!FBGj{A(M70+T>Bp6P@(Y7>-sSLd0T$H)vB
zcC6|+J87laB=vZB8L#;)+~N+j8!t~uh)s2>bO^_q!l9*Dt$2I;DN+YeRUje3$6j-`
zH)hM?<#Ts<e*GK=-{Xri3*y8IZ7k(-nW<BaF?;wVD%(<-HFs7Q+(@?svL28Zh}Ho4
zzTUf@$~~O3xYUq;A3vhp@Ioanm-!Z+G=a@TD(@%Shwi_d9`0?F%E%rdgp8+BAP}-E
z^CBnC#~tm?T$jDkE@}({HDK_Hk|08JFS*?GodN9j#Shg?#6c1Z0|Um!Z6_)7_xf2K
zUDr)Y%e2zpSXly9P-?Z>D%nuOz|H4+^HyxEu(MB-ZJ%51PH>St1NLkg48FfT)p_#O
zH(TRe3%_10fxHK_F&~VD`~B35qryq!_+z2f5}(fPzWZY-O?>gv<M%Q$8|51Ds0Kla
z@=|A<O1Dj49hn&jlnP`-3aae16IBtEHQN}c=a!j+tWY90MP#593iof^*K7${ab8RI
z2S}0x1rd?Dm`KPpT^BFkcftIi(@O07Z@kkn)Y4iF&{VQoAlE7s3I)=Z%N0Nbr9$+N
zulW&Yo-=9z2qk2`d>*m@y)jr8R=Dcr(ao;%F+&2;l}aV00W3fO-BU{%QYAA?%qoCZ
z8U$*90E&<IMP`(mc-4;AAGxPT{LP&)f7lZB2~j{X(}5RC<+TRwc^+`#1Lm0Ullg*R
z?_GdFYF!K#7zApwL{cP8YX|)xd^4dtrdxTkKGm^sQ_vd?4GqNrDCMPFfFsc}xh1cf
zUB(9%BkZ={Zo8Ed;DAP>;caZ#5YgXq?l-^g6e}2*=B8h`#GH?$N)P?Y)h++=M_6-x
z-7#jiL>m%jyf$XtIDFP)o*(UfD0gfu-4oGiRT8Ykrs|5awE1p4%-%KW8JHjJh`3ZK
zv-k(_3_LPp4H*?=U#eAh+9H6+=xD~7%nV&nFTAMXg_{zmgDYL};DZPCo?GX<)@U>U
zlte)R+2B)%x>*!2lo>8szHn&<+y-8mhytZjsnoVYp+LE;wbtNAQ{LR#d*y8RKf(z*
zgwPA}DG1f|ZlCpq{qPsH!S0GDrirDoD2eLGXfyM8;F$YuhZ3Se7z{f_0ZI%gh%%;Y
zHlER?i@O#~-<45FyQ(y5I|b4d(iHLuOgoJCoSs87i}~|Sg~Z1amVU!0@W5t`+B;_)
z1WOz+U`F#6B9Lg3s4B9-QH(qHn_mx)7Xx)g4i%e|7d+jb+Oq}H7eT6##7Svh<f$uH
zf1mCUq*o@J`O;=%BBMpe;oy@v$YHZp)yda-hYC>1aC=shG1u0#ymbH18%Mw6Z@zEE
zN~sc$iYGdl(zF}S;)kY>HC2^K6i}tuN@FL{bs!_0j;SMFtVdo%V5PAjE``p&r-$=f
z4&~IxYsZVOMgytW>o5QyP~YI&DTo(#{BElC=sO=q>AG(3T$z}RizrG%rNX-{l6r#H
z%ew9Tc@uj`2rSWL{Cqx5-bM-R77jfBudl{?cii5|vrws2s8lL#1%r5W4>g`tp_$lc
z*BUHD<^8m_mfdF_i+3$8@4atAw?iPvG=c&n?F#HEo`ge}Uxi=|eB23|IHCknDnNs-
z2N=2{c%o{x3W!lEk}**ozq+U3BU4YTT-lXs&n5sXO`T<rapKSlJZD0!U1OZO$i|Hu
zx$SK?e&Y3dGoWD;II=6w^TyXp<K=S;<|i*TTo6__>wB5Je)V@I7g)ny8W7qjo$*?a
z<_0_Oy~)uoJv+8x9d&eGg=TvWJpw;+KOlRdJRTy5Nl{(!HMSz2{{a{DOVf|3P}bh+
ziP#xe^El#Mn0AajyYQbPR@ErT8fN2o>jHm&C0w<MPp!Zr3IOVKsqmf3vvuIyZ+sgY
zD_G7m4YbO9>+kOehKE(mU6WB0o<HZJuex_`c4kVL3)!p(<ohBRBOL3xwQ>EfCUe8&
zIw_+%y4NPx%yBg``8hHh&LA#J0Lwd0oRO#6oeP!95SXqRghRPDq&pMc%hKQ~|J2j<
zYrg|m6i`)A?a5SCjU!{lpy4*|FL;n|xX9g4G+ls*P*62Vq(1T*F8yYCcDBchfsYI3
zTP)qo>&BK#N$U^)Q`EI5jYY8Ds5#@p!#b!I93a3mg}H3+-ugK4O=s=iL)&uDTDONT
z)mfTi#@PsxX3&*m`xox+!qRA>a%=z+2@`|odI>K&b9VY()hSBSgq>icGK)wO+%kT3
z(^lpg`-ESJ1_J{F^bv!qCeiENW?-Ta1SkH5yIRksnJ;GYX#`6Ef=2+TDpKF@)-L^w
zv%N9v6e}3Wwq1U6`{7|vFdcnh2uQ62B%ldo9}Tdql!3>A!85p~SK;!;b{fahKuY_<
zYr5ClP3U@wgfR311EwTgq{{~y-v8gecZtpIL~H#SXRGMT2H_SEPMbCcEKwN1Pjd~w
zMFPk8cTWiHV1bhwYhdBoHFzRh)N?1WrL9#4q@&FF3&-`jrTVM8Kf6(@ps+T&K-mB$
zsFY?_PT29p$@875V@1vwC&Zx$dtxiP@FS@4o`BQ9mH`25t*O&!G#Z10gM&A}`OPJ>
zGMQs!>*LVY2litKdQlMR*@Pvsq7ajUhtM^d*6!F3Y3)GLTCG;=zmwVCe%1cFR3oJo
z@j{k^V0Eg@dvy)cbl=b|#}}=$&Kk9VEdk&|HuD)nsjs=P@htfGue5~|{Q3Wj;R~^}
z+0?6KUDD~)Hb&swDzoV)dXJBF{iS_R#(}^_K^c!MQ@ZhaRJr(++;P!$eU-&R%FcWy
zr3o|gA2|chkvH0KeiaCU5QD~`CXHkCl^<t@rqBvq@oK#%w*)Cd=b8d2Ugp}ff9=y@
z@nYae!18q=(Yf_1Rs$qU!sn6_{=~o2WnR4Z$S?4@1#fYo0kXzqIza10<!@D;t5f{%
zokw|n;>x0HS}{Rt9EoWC$(;!_wv@8!-u0o;y`O^(5Lu|Xcw||}qOo3fa7Nt_&dBYO
zesKbxz)I}Q$Pr|w@1=F_oDawk0t?d?hzLEqc!0QSQt@bhTV~H#))GWUkxn9=YE+^b
zl*J1H)pA4lGvNYI>!G!Fb%i$1a{uKjp&O4(!>t@;-ZjR#zn{Nz-Q82wLrbyL_DBu2
zPv_DMe<RBd+vD7L`llbQ1PZpAj5n(8Gj6b=!87Wa9acv$eXYusJdP(aXzc7KC^ube
z9WwIMbIN|_3WF94V*@V`mrL{q+#Wncu}KzgrXi?SNh!Lfo-A~hZ&>Vzmk(g%9)V$i
zrr9eQFxo`iWNd<ZN(CrRGgLRzmO7{}rcQHT*8xE+2=c~|*E++cH#(f?ti0mnH22<A
zeH$v#Dp4wNh)M~U!8DUMfT+W*J&OubtEn}uq%C*YjB3N^aHnn_@DQH08$tk``Bba0
z@pFFhS<A19n^+l%EWt{!Pf>$AgM3>V<*wq~wY@VJ02o_dATF2k<Pn<`TW&nQe&*+u
zYb8*0RX2_s&(y1mh;*vepoW*pI_KBkjExnt9ImibKQrHNK{m$1`NFL0!TO!(QJ&em
z#z)LdqO>u2GJXgIWX%k&H_9ph=E@qo<Caj9Ss+qRr?QCoasRqyC$Pe`3j+zaG0|aw
zSL(qd{9AuGGbR^ISJZ}6gd+5SMv0ra={a3Lx6O&15g)*z!o3Uk;h`yVeo7vP?jLAN
zGvA^(UJQI5u-xq>UUI`;ve?854Jb*I&_{qD#WFW6ZQ@e7PQsFP+tF&PyC40$yfJvi
zE~YP^gw>wprQG&*qPd*NrhYqth-k~51s~9xIhH&0k8<(3We2E%@I%~`$yj)d_5xl1
z=RViMB}cnTM4)?DQ_(A)j-^tmRBE+atq`N8R*R;dbU!rnz_QxVjZ|YoRryPwM7#3$
zd%o5d3o9WhX^IxA%(oQ~&0yZyzy5yjSi!({SMzmdjtdI-#y9;g`WwH{6L+uqArj~l
zh=*w5`m<~byzu|L@rW-Bn$tx$tEmuJq6az)V1$VyV!O8)#{Brur?6BYbR9o?6Q*PE
zKv`_Ctnm4sq91EJcjaX)LFpki$q{Ym;KDO=Q4oSi7%+{9M^zLrl<sch*!)bMV;x;E
z3Lq7V))l+wy;B%3II=WX!Oe6u#z_pdv{nN&m2L$bQtK9Q3-TjC;xU?A09uHNY4C5v
zg0Vv4rfVxL>`C~(XZ%=DDrLCzS;Gvy_-Z@3-#`9exAFX1V{Y`&tm{=JrOY6c+awUc
zWRy%MP9#UJ05;0Oy1gea>W_YJ-xGn&3I!;mGhPXBN^E>L&!xz%p+7-RS{k$_R!TKp
z+&w8mfk>{^RvH>wp?|C}US_xcTUWnI`wTrppV;=mN*@?0H@Z=89DoAlU%?};j%?;8
zI%s+a`!y)CvGM>A1J|DAn@*<1i-B`y^9OgBzqc~M3{ezqZfkI}id55FMOS<C=%O33
zK?0tc1?GlL@DlIbS?!SrRm0CWTU<`l8H{Xq<)?D%Qh0XA6E^mHFfq`*1w67`V%p&I
z4TBGTs(fgN+nz7ux}GRa=m~3}nvrIm%TLEk>D;+g3xzhpSQtk)A}*C7rUZ|5{Eiv>
zIqOmr6bzyenk3XJzFEO@e&Z@ORyfCZ$Ns=V#8KVNc`w`s9K}QwSOLpA6%$aHJ$ts+
z(9oMS*5PU^?o4nb?6OPNBOtp-Ab)5AuDYA&_t)=DuxBQgb&+^Fhnhl!Srpgtac<gP
zDglQ|mu}(_lnFu3*!}@0?Ni&W%uQO9h$JEcD?>ej0gHD6aV)hi!AqnfBCEn0VN<`l
z=h!z~df|?!#)GN?goB3_?!|pU7pxnDG@GNNQV3PRme7A8UJQJEj<28o9?3Yt{MMwe
zX~wQckGUs!$Q4NVLoq^~chL9G?{v21{gsyQuU}57+$fclO4;kcjJT#^QZ$Y49P#7Z
zcX<$jFej|)69`_ZW8c!iMU5BsiI%lv+9cZL1t^FtX6HIcVNX=8R-K}8fIvn-#|}r~
zj5=o)@)v{{b%PuEjrk|?8z!+5^xQAax#iVLkhF`!2C~laHFrD33I>kb$?j*9=H3^N
z#%8(P3s)v46FUZSseqFjktFp+ebuF3UvG@{I?T`%Q;abt({0Avo*UM~^Zfaj*Vtj)
z{y8_qDTPXT1JD^KPsH|0y0b-4gf+Ro)2WjaeyS-;Fu?E9icm6~>WDMGr6<YPX0EYl
zh5}`lj0Y&l0(2*kYc&9ao$*9ep;q&W?sk`I)jOA;k>}G(mm0hqlf+0oh={PxHz@hy
zK7|MDrVQskDNoC^F@~3dbma$wV4ztvqr7;bV1Lo`$_1eo61lX_G54v}ggl-p%$J0!
zBH?+S<wgGc|Gq^!iH<7eKGDr;^17-9N1O5TGK16x(0v+@R272aIZj+*rEckEgt9;d
zl%09CAPI`xa(ipf*vEnc(O_|39EdzQBIUA`wr*(vjygM9_uT)lwIWoMXg}Tc%I06{
zeR^2D7^t^9d~Vj112X^2@bHvJ-uU>MTj`$I>*tME2%|)?$jnpx)8~)+L0TzeJWgYX
zT=PHh-lsI`N4rb+=l6Dz8559zP|1QY<qdrp#P|IQPw>p#<7NY^M@JB)r%ZHAwdy6>
ztvxSKT*%m1qBjN*1n^QQFFjmwtm8N3a$>cWLZaQmmLOg@$Nfpq<05$`b<+h#VJ3EK
z4}SaokA7^Unb(9K0Z79Q#DvRk<K%zyp=0A4Y2R`{m}t+^pp9>fOc=|?wwx+<9`Ku|
zt;kRR14BNGNA`_4<M;oJJ@nK19%b4}5*0v^9-&|$!%EA#Z{l&$)8!k#gpKsY0hH)$
z@s_rNBO&gMiI&!ys9J(<ROTDx+ROd_*^+oM@RoIX^|Q-KY0B9}yyNKuLqKXJAOTGv
z`)B|Y)XKmBG=KsoJ(kG=Jw-|F(ce6}?2GIv0i8x5I<u8XeFxI81AE@ndCy*CQ@5^|
zs%cKO^iC|RhP5P|+?M_g#9;x8RO*2e0INzxQ0W=K8h{q~-vYVPsYlsd;vxq8A6F6V
zWx|qM>>TiLbHKy+t_LhoZY|e9(HkH#Ui8HI^+Zmo5hszXuX+g**0Pus2oiKL4ro!Q
zlnb7rQXi;R-9&?o*J`lKF11=vg#!<2BeRXg)<v%H0SpZd&A!er|MF%cJHa=+MR8;<
znX#W~La>AJB7-P*8y~;h-NwC&gWG)INo=fOXj2?&!63|k9qB|gRjtLd-1qUs0tq?@
zj6on|_;f{h?2~_b;bedGMYT@W-tlDIK;%OKZx&Lc=)EzGoldfQaEfodK3X6!c%~!B
zD_Wl)yyB_Z*Kur`sTPY<)+Q-EsE9+U;G{WsMH)IYcl{FbLUi{IBn~a0pe}RZ$j1F?
zQ{<W%jqckD6XCJVB1UWC<x|{r|6PN~+>7uTJJ|lyud}r{`>b6F3jA9yG6KOX!+HCL
zV_*651K<7a*jzpn;nEZJ3{LhWa)ci-MSs#x+&%i$XYXPP3H(4-xzb*t%F4#s@t)tO
z+NNipy#i?f2^h4VLei8youbjJIQLzClxOVBufSPj_?mZ7opps5FMdz^1s9IzYbKyr
zX`ou1ARBy&o3{PHy-u-$fpZEETVEVx-uW2*|GJKI@|8#3wBOyml`#;8p+|JbVEOaZ
zK8DI0jx>{+s1POHyjEMhB??c@Km=f0woG6DSl89Nt56cF6$+2kvE4E#OE150Dn2)9
zUF4i=RZ5q1+F3Wcg9yOrE!*93e(t#Fz%Hx@l=*0gdUgHg#(jeO?go>Yuq{VxpM5-0
zwTRk$un`*^{la+R+&;g;a3p^y*#iy%j5ZNBnb-hS(qfD$-$I&m(llX>b=$QU{qMJT
zmgqbh?+n@D1%L0A7y1vMG>4`7m_|JjZOu{WATkw$#}<Kz9|6PjYqbCTfB4I>iUR_x
zZvw?Og+Q83D9n7oc^9@jw@p>U(h8*sJ87vk05m!ms?};W5JA$>n@pd=DY<Wlh1-_A
z6y~I=_6C5T@Y~VAg!?|9Q#n_n1-A@8V(@4Gvv;H1pi>P?z$+;cgYlR9;PKFSF>sru
z{g1gnJPd{#xiqi-?&wk9fP_1NA%wsqV26Vp$o>vYF8;b}$(CY?7HWi5GFENzR^t!h
ze<*QA2RNd2ki*#`l*mo+PB9pK7SE~!ZL4ohlF&nI!Xyn$TvN}dBNrM(#`=<oDxj*f
zO@Lmk@x42m-!g@@u(caH2cBRFMc0=d^qq=2jl>HErm1QKVvN%iCst^{<%zUFIsKnu
zTk*uqHp6C0lef=s*S9-aQX9fUh0)Tks`|_hC;!6vQ~cdGmiX5ov@(<Z2yKY)y+!?K
zXzEuT^IlDOy26a*EyA!6041Q<N|2GXv)m#YIOEy6u#IXn<ar6z>yIujCb^>N^w9LQ
z^3($5TF%#;k!N-o<c-n-Ms;+iF)Gpr!N#%Ox9P4;Q0dkI!9W8k=D-cR?{1JQFZ;py
z+Iaacci2B(FgXJv^L$I7C^f9_hL8T?=wj>XPC6151c6sPVO45G#D=@vm&2dAap8@f
zi7|2|iV^7uO&^-b_Y}bQhaDLm=<wQeJA!}$z;vKUhF69BVB>S&a6ulkE=*9tpo!8$
ztNJ$bw2V?6?zrp{FKm3s_3MsC7}1$V+6Mze@9FsG``kYA1zQ?Pb(mtEMSVjZkIlLK
zho8sB3g`HC_73}>pI1inIEGqUs{xuyRtw~@wLk)zD$$fFJwmk*XQ?O+g@(=1SYh_;
zb3S>jF<fUZQ1XaUQMfZPxWCW0kNd;7*R4;rFehExsD<S86!sX-<sb(X+L4USQ2+wu
zF}MKefq^~B3oWmj#=H9%IyuF+&&9z3Uzkt?ia<yJlqhB>P#U>~)AV~+us0gY04b1?
z00xi6-I5{{h~%je(LlmV%Uki2n?Bal_bZnid`M#)s(`98<I80LC(m4X;K99k!1mm&
zt(9GzqnmnyB{#T%C#r%s8g%}tyY#lji-C{N@ooL{#0Z&r9Yq2G=}wAE;$vy7lKPsv
z^*I)FcN|C>Zsk>78IKUrEuu6q4o?1sU%vSN|Inc<Yi;}?@bOx$E$4|xH}d<u;?<>_
zOm&2tFG8qjgT@0*JxAaS3(hTE%qw;V#N&~Qbn21ELy7A6XV<ZM&dO4o@x==YBFsgH
z^PbE?SiJ4?$F`7@q2%k0(9MLpso^LxFZaP&r&z(jMFsO`0{JdeeH(aXA_fCiz;bK}
zD710v)WW8YySQK{UV0$I$|avWTw^=k2rZR5q0V?h>HQK?Y0YT3=aV_uQKv5T^4QK+
zlq4F4h349JkMAv6n9-Bp`5jH3EPpvX_06|5LMYuF3=p+a0+usJz)0IW5-xw>^!-N8
zeYYfGahfhJYAs-^T~Xo`iKNvgGi^N=_gw@GH~}C}KKZ1`><eU=(dfA2up1A}HCg7C
zSf|Fdb0MQ(KSg%;Ekqrc#|t)dq&P&F^95t68j)gDsI5K1xtDh)MjXWnp{;^9mfo*o
zkzmhScz`c%pW+WciN&F-EhSb24?ealyjI(Yh`Hna<*&S88#@3@#v?^OyJ^OmICE*&
z?s}7SEi7J4&z&T4%k3=A(3|pu^j9bWV2~$8n1e%nePQrOGqFV-uccrDKY<>g6uoN0
z?vCQROMf668ZQQJbDTC0E;76@T~{V16KiUXjBKvV_t~o6b1O|Q{@mbludx{A>P<@2
zR$&;1GtUTN5F2)wx&O)B%h}tjKDy%!tbd5>jSluQu?@zcsZj1fuK;l(ji;^9QkAu-
zs!az6IHGZHA2(Y_u-t<{@J5An#zNbH^XVbGCL*Vtw0)}V#Ph@ki&RxjbcOh4I_P+@
zo_QXj48GoSLUj#>G#~*DNI(M;(0~NA%iiAJUgM~Dzk$OD58=yNSopsFP!}Z)7<^BQ
z7A;!TXf)tJ6QdST2Jymud_B`Lw{QVikyxS160e9F>h>A#z2E)TZmRJ_VHlt+DeBs`
zb|5*<)${lNXCK@3u}qswO=!JV5tI)YjhFUI4>s#Yc57v4`71Yidxe7*?(jwhS^iT#
z1^ccrqJ1)JgdSdD=r=uarv59>yub9-gVzRY4C(N&!i-lVueW@xwP8vse}`X~88HYb
z#T&wP+kN16$9OUDcG3M)uI36?nP<i*w_9&5+!{-;MW)zk>jpcEm6wekJItl{zUnM1
zf$1}XN~p5kR|g-fx$`L;`NGpHKXkoO7M(;V5d5it$$Ua4qHbwRrf#fTn`HNR?&_hA
zqc=pM(8dc?RVgk1@1NHPejIOTCA252R_}6`YJb0sb~qIrQ!g{MU%~&`Ys3TSi!a{3
zeK>7ht*%x#9&{1y!Q1f%Chvv*5hF`H0Yz(5eF`r9HSvOh6Ab*sZ0)8EPy+ZqOD1;4
zzu}7WKTQhV0+k0a%yeM@S{q@d2voOHQKKr3dt>{Kr>d)L4pnPKWMM>Z$$UIhDBH+;
zKlu8V9kM65d2NdT%6Oup7_@Zx)P<AxF}rsBr9!71UZS(8QRxXfD-hM&j-|*QEo;{=
z?|=TmZ{UIn?g*;POZ6ANrTZ@)Qm+ZR79<L)&|PJB$Kd*yp<G#A$Vy5K8^Km;^#K<I
zq?QFh0-8Yf(E!V_G(Z<<0M#xw4kkdV7RM-)y}jcje*4_F+XL-`i5H?l8H3W7&u6kx
zp>n(8?Pf5oHswn@`i$59V_Qq*rO;|eP%2B7w5?3=C|jcETEHs60JsU@L?s)mv;>9#
zBNR0sP|7$PB(-X$O4W63_l2+gBtP^={K#I0bD#uRv0=T&Ab<eLvz$2!s?x{b<^tfN
zUdbKXvPvzeDy#)cL#+a7e3t`jj{xfF0#>Qf0m<W<0CNIhC*ayy7eD;BzjXeE(e8Ea
zYx?)_EBnRSPwVs7?gL+1gs{|luF?{C2jB$oc;Kag8v+v81df3SI1>pB>F7(_q_=*t
zpEx({<45;#w!5mNDU@f;z)Bzj0=#gZ+Z_yi5Hki=Sx%oi)&rR9gA@+Ib!Qxf3tk5<
zbi@7LF@0h31|WE#*4gd0%MKj=bajMNx2)>WCii{3G?h%X7AO3*G(AUt%x|~#)qLh!
z30}+M93v9*(hz_%wqJM_K6TeMIXoo}-&LH>Aa0|wTOa<)w|<#F@)v&2-|+i>9Pfm3
z5J8T7lfMC&1tVbFc{T($C!P)A6VC?V7;nN*nHt8h*(rXk!&k;H`Gx1NeV9Ms{LVh?
zTyjf~Q1d(an*Ql@NX)RahuN>;L+JsXXG;KM0ayv=puM#n?VSAWo8IMrc*o!C&(|6Y
z$mcVj)>>m0)xchrV_&mc<A+Yn=a*Qrq*Cz+5o5*Fh*)cFZL??}^|?RmD?IpZ+{XYw
z=YXKd$n?Qq`1C5Zt%;kUI<C@#xhqj#VMGA=TK@g$Ltg&YFZjFv*3bRhe#yBDU)m&b
z#59@$XaNSoi_jQ1p3#JV1+sw6Ge1@Eqki0dP3JTA48CuQHi{w$D9~e|SKJubV9Cu^
zcH#nX+>Aox;KzUAYwm1=hZ4SMdg;RhwbuG}z(Ee=KF)t3UJdQ&Vj}%+ba-T%fK?)}
z*d{M*9&zv9^;3Lb{7y@7J%Tb1t6B|YIO8XNi4$AvsU22o4S+!qi>e>?@+;@Bt*`E1
zt6%*0q_5&rLNOEvbYpWxB_N%Q08aQQf<PB|A<*DA7XT6rn1RvsaYfU7y<hRYU-t{$
z7tT?1Rsj>NsBB=TxWS|yXE%I2RT(haMBHRzP5`yy8l4)>QDrbAZPT?adtZ3!H$U-I
z|K~U47gp$EJW>n7zOV|$!6`nqymW43wY70mZFiQra+&f5b38+YQX)!!DD6tq_1sC;
zpDMwJ2u7DH3^Mbo>@&*Jf9sR*oo$w4j-F9&pdeTYz|E#eJUW4{R_g@%r{O-U-D~4x
zo_p<A{wvRZzTegSh+bE9jC%vT;Oo*z8w%TiL`SOdG>MKx7g&t|MlkvT_>VNrYlg4)
z&$m@aQ^xdlK(8R4`D^f{mXxPy=K4W{F0Dkcj1?V6$0doL`JJV=oi4Pu&m(~8pI40X
z72d}M7wqm6+3nY6;T<%T@kATpjgLH+CF9!B^@nD>g!Fw}$psA}!t5V+1WwT_<OXdE
zFJ-*APMPz%FFs?7__Uhh7&)q6-`{t?+@JnG?<5B-RwEaRf=%#Q06fQMyeE_ZL2pu7
z(3?~i^g6^5uQ>s0c-S~_ZfwotXP>~?AMTvh>&kV^`<?SV(5iV%b(~nC0gq24)hV(;
zMP`83+m2Je^M$AWzrXJYZ(&RqdqW<KL0I6xacAm%_Z=>kSIHvRQVm4HrBEmoGMQ3N
zgJ{u;l4c97L$vS+w<#~|4h1QJG8c7#tAE3jFFajt%B(G~I*C-?V$U>*iCd~fo5G&0
zzo2FDHo{s>wh?Tk+9PkRmbo=dgI0K&>({T#(zs#Ig~IAQO))8kN1z86R4}kLZXBEY
z464mjHG3<KLVzF9a&)xD%bnYv=B<~$?X%60>BB1xMq@*baf+|~)-Df4J)95a!tM)7
zB{KdO-9cloAalpM{RwBZ-*6ut9dlAu<x`y)oa%;4Of6cQhV$~Agh)yf2Z>SFB(Lq-
z*<VWGF<A2mpd*4J&COmZ5<HoR(DIhnm-)^q5fb(!5*>+5Bx45bEz#1@A}9hlI=nhE
zP#ADA-nOf~HpPeM*2meDSh28$o~mUe8fc1{4?F+8$9e7!$Tl(-7u3>P4bW7&706?=
z0N4OsV6Y1+MG(r!Ez2ES&i}aYB~RQv$S2tJ5?+DPz~^@Oli1JxNwtoIXFm!+q2SMN
zn;_^+@kV9cRr76R>SU=LH531U2`})6A$21rU^UYe6e*d7ZQqSE_!DjhZs}!sf<~jU
zG1&+kdz@6m33yB~8mf1G@RCt{1X;ylYd1h{dLlqWoAKYmPyzR_XN^QdLh%cJ#s7Xr
zTa-ix{1<?$yb*Y0P`G+6>dq>Y>aX#8zrLlYa1{_hA-A2SZHbxJ@B_tNu1EoN9P_!F
zdS!CAu_u1(3-A2D|J=_CFD<fl3{LUQ3s%)}eE7uW2m?{nw%IEgL|)Fc&P<HvSowCY
zzhU`}Ezyx+fe5o-K}xxWZ14=7YhMF*y$P`@2r(-ltjNzj2suYUa|9j(#G~12Kn6q*
zL`4As#G|5s05T#f3J4%vh4Lmn@i+?HamS*HU=<ujO(%>fm_Ibo8ZSHNINi7!@PA@w
z4byxZcx56Atbpa%Hb7&RX;ar+q?N7jctj8%+5p3GSZ)f-UwX01dX|j}mJ0^0DU~u;
zC8f<Ro5p5zWm~x~y=K}Iur%*rTPTSfW!9;xig;oD3!OMeZ<>DYiKgo+O-18lR3o%X
zPYYYf@6{1Tauova%Zj494wykZ65TBVw_fT<IPKQzR-$_e9zBME_R(HjRl-V9LFs`3
zXrPsyeA-03mTdA|Kx%?1yi#s$d%AbN@Z|sV=du?hctc(wXmE{0EL+^Z!sA>&wU0p?
ztA}nccPqcO5-agrp~>voD9fYkT&rr2bNe~S%bO63(VS*oXG4PJgQw@Fw&|MYXyV!?
zG>BUTrKiOk6;L8TgsdPaw@~C3aBBf5iXsY+=`9}P7K$PY-0FCYTiin777(F4LPSwU
zBZ9w`fr=)$w$pk2d^w-%!g+2xKT@nir|QbYWMW;dMlq;xlO0!T8|9widFk;~NP;(j
z*7>k#C1Oj-vdVF;d3|gciE^S!S4L>HqZB`~@y1aUMX`eHp+RchNrnc4DpsYV^RAgs
zuzYEN!f0Z2Im<*$m61O3gRM`z;91HYUBSwH$wp3tLEz<pa074(5NAdQq*|G912n(@
zMDC#oup%t@*T5POM%O^cs4&_A9iu|s!E;Rb9s=mdz%v$qXyCoMa-Lz(Yk4zuhpbgg
zH)XS4h@8uxL(lro4Nvlae+>!Vkk97{9B>F@$UqG4;VkwwRMn=gDi{&{9VAv!3UN6y
zdh(HHg~^DAoo%I3DMS>Qi(bMxYM-Dr;#yDN@60&*KAX)n;H3Swl{xNa-SenjYh<n(
zw6Wk=Ygsc0$_3+kmZg)YBh$*ZlY6qa_H|2q=m`*pU?I<l1BDZR{zow#x5Q#eWq6Yv
z$=relQQUaV&3E+3>lbnd+74&JWt50V6;-QfiL=NrJe$2sxD*__e#7luvbH2GV#yql
z3V;|~wakyrm0iXY9d##5r%xIhW~u{w3mUYy)@m)YHf{a**rRPhq9iE1H>3(g2R2B!
zyJI=<F>^IZ?<2LvD#~HyzLM)8ofVT~zDZ;zx_yw+mbM<KnYIT^eqm6KgA!#rhgcIY
zT<qO=4t+0N6CGAsuy#>RyhK;C`(2s_y?RFtf^ueAGR)Oou5NYRFdewU)$~$<kjKym
zhJe&cKmwXT_R#>#u{1yzumv<~g$65tNdO4L41iH!97T@Y%D8jtW!`#u-r~R$!j%60
zIdl9yU(gR1tm^itwEy}ncW&i?T<YaOL8#@hfIU*{8)Gy98#=&D00dF+1E2;BLJfAw
z?r5eLCZ+cH^IJMjl!?O*Kom*KH-6@xd)ZOKW6a86@7EJAVT7)%6hLdaS-?gDrB<r|
zfiBQgYJtv^fR+Ym1Lg$!fNSz-pf~||6u5^Xz~z8VKsgCm4G@%L;8nn^qr4KwJkq%d
z;4t9N0t(M?H6TEFjGn6~L#E}w<#Kx2!2jmTc~;9xF8Z4mf?i@SS14Sg+Zkz$zUH;I
z>4$ub7RZNQ5Cj1*7yNDZ5;)oCf6+LyFRMJJx~5Tc5Hj}Q3L6nx%exj_D-Son_7ed^
z1bsbTP^EO^3m$kr9hkf>nK4chDHsP#VT3N`B$e^!2t0p|$G}|O<z`9A%6s(^kmu1X
z_C$C*guxHiP&Zdua=E@F3?ZBG=<o0E$HEtaKa^$Qi023Unv&Yl?QXeNuF4ro%Q~7E
z8U9*1ymCig8<x}C2fcl>E&-)-uWG6Nz!`MQw3XSxQD&4TkWyq7_?(M`@rx*i1}S)1
z$6R%58%s8w9aXk;ig1BB$Y{;L;)G6mru%N}8E%!mP3CL$Hn?8RTSi&_(wD1s=$51U
zv9WN-)GCVKOaH{9&hKcyVR>&KK=09vQxH&`jncUtT+C}f+v|>q>?6!s3pwI~qE1Yf
zE9Z*cVNXLn>dqa^3MSsy%7D=(^3qf^t_TAR0*$@OrMdbu{YT$|18&UoN|aZWN1Ry3
z%=$67kBiJ*?(0AC(T(U1v$akUKr3DK^i$D!8U-pv2<#QKGzIOUJ@6AL6O#(icZ=nh
ze85xcf7N#GabsmBF>a+Tps}(iYk;;wQ)`%*)RJ0K>$sLXQtK*UFp1fv`m>lUdFE=#
zMZKfe!U-3i4Jy!7N`l1|=N}+7Y_6+*uVB9IIHHBiz*yykH@#6!|3k6ek)fqjvkHtF
z{(j`KkH6#}P$EXl^e%5daXxwZHDx?h4GEN#Iqxi5uv87)HCH}#|2nhuvmNbL)Y4hy
z()7iN6&mpPo=RXmrjDjEe59xEUHnaAqBplyQnFbO(0W0k@Cpxi9EUw=UGxrZE1<Gu
z3Fw}y6liqCL4#zjrTguc|7A2FHU+#;e#2>l9iQNgeCZo-&gg0oq+98t=gBS=Je|i}
zeJyX(WiQ=DFL7b&1QXBGZ@Fe*<qY>+cA+XLQjPHdA}x%<;>Lmp`pWv=28Xv+;@)!=
z3!e;}mKWMqtQ(JY{E-<?FvGzlL|h0;xm5n%ovhDIo!o0)WlTkw^B!6ZEjF-iu9VkB
z-t4+RS|H>p(pnABRJs+&V@rS)Ko=P7)&W2j5ZGntM-rl6(G}iwD?dngV>KiUA>+-R
z`!r8uiR@+zo7$1R=Ip(XBb~qQa$;pTiItXZy=(u!Y=jDC7{gVdpNJDcs#F68fg1ME
z!qg_>-EXh?2N0fu_!KDJ`S}(uz+L&{HBPDPuGSk!3M4=cn9s@{tOL?aThoy$381xx
zk*gFeiq0wK>1((hRI-_V_kJ#1l_MQ3iAB1!>hkZ`?(xP60J0gb)p9&AalF{(*w?M!
z#ewzOkXbR`v}}eAvo@L0g)g+_UV3{^K5*kVdczoj((>|C^#7EbE<2f&G!f>wuL{pw
z<~(!NbyH`c^JiFb30~(pnX22sD-%&*1uXZBLSp<#5svO(SZ6Fe$HLCf!FB;?Jg`!!
zyo0~7wiU|A<1c^d^P}}dR7Ff8Gc2^)<Oi3<9vcG63>KIV$t1KH`^0hApStsMgF(zZ
z>xpfSkv3=A6`+!)KvLBFIi9Oh-l|w|NOpM2&K1|#(~`#)TfD(4lDSYd2BlJ8lukB#
zo`-L*J%$7%7J+yIuv<JOro3yP+fmQp&W5X4HU5*P8e?F+*jq(AMU}g`2G*Y2OZT8n
z5BUN=k)W_BLkz@(BJ15C8k}68iH^%!XTm522y@nYrjPQD=Pl<9bJb4w?(FCdzf<Rh
zEcpR+>I}uiWX}nzz7gWg8)}Y$n=GB`mU|Q6$C4=W`Mfv4tz?bm{5tplxij(dsA;6*
zxb=OmO24jl)zeRf6C_{&7-A5pc_KoDYmnRLwit1|<2T)T`<pkZ8Zcyt2I%YgR4Kh;
zX5(pmBsw>B9DN?AY6(&yZaa@1W=dP5^RyMjqoMfx^ER{Re;WmdvVj-p$~ivGELo3)
zOI*nMX224wR1(&_`g{E=zR5(e5WG_w;6z#q?rL9-a^aaV$?#<hmq@_uR3w9Dt<0b@
zL8&axz3jf$V)^eq8hB9dH;RN<RGIF^<XRVf7cQXZ^6qgmJS~sM9QfJu|4ftFe`=?X
zfw{WN-CF03lEIT1OUjncDi<UI_`^1ZE%x1Rp?UhdzHmUo_vRg`ai>-|=8WmR^^HFi
zf%N?l!>mvs5?q6cO|`o*VSA6i-tqmt^Zc+dpubmCVn7d(e*;hL=e9e0MonuVb6}$e
zN(MH~mBPGdm#bcuk)uM;OU&SI78Ep#5E4l0YwnblR^?#~6M9K7J#Or4h@)J5!C`1o
zSc$lz?hIG^nE*)|ptQS@Y1Dd^9(nz?juQqf&jic8prS(0e`2<<5yPki!C>nrxS$RM
z=QWW8;|3w<9F`m(zoWd3)`k1PJe{N)NiH{&4HpC`NHh|0k*Sed2}nQ_aEOlvFu_<F
zpsSQBb$|fkaTB5lK;K9u^Q$epb;FL-y9zRrBL%DhxCA%@U<EvWW*w})>W{tiEBW;&
zU;A^j*FKVx$`Y-aHER|qrIJoWm3HpjxpSW;t#a3jCDKZND<eP!h=8{ZzR$42I3Y}S
zyUVurk8u@Y_ke_8Qz6PgDdU9_E2$vZJ@WJP-uYZ|u6)r_!60C36juj)AW#6-p0c6R
z0w`_?NPw#a?2%g8vjLLlg{g5(0h>^(1c7U{I-ooqu=Vu7f_0@XupLvMS#tN23l16P
zYQ*4d*~|8yd<GFPm_fK;)jDFRsfy}*^)o+kI4B__jeqNkBDnTdf9x;&#r(jZIiHRH
z;p8oQ$c&NCdp0UJwRw5W>s}d~GhpKg1Y+>Sz!B|e*cVQ8ei3}n*N_Xv+1gdy37}kb
zI|haX1|^oIVXkCyFu+k<^M)rMJ_8UgT%$;%gu$fg1dWTX>0asGD1@vr#(04{uniCI
zif6C=RNoc9ffsK4>i*#0d<Cz3!*->~j0)*9wpGKH4fj1gI@+bRXYCCHU_g68n9r}X
zcRY5uR@dcMCW?FSnX~e!vw#SCaV0p4Bek@^T#Xo=+dXq39BF@BCyC<uw9J;zaL?l>
z3CRj~#^8xpkM2D1?AIlJCZF(AesMqX4_-5Q+4IX~nAP#Xt!+%z!enpn{=c&Q3brtK
zW=QyBEj?VDch31IU){NM?%oGB11`!Hp<sy(ROU()wKB(c{O)IBXLe{1k4{|%j5d*%
z_S{Q>oDye7a!HAjOkeXuck$<vCy^jgAQ0^d>u%kqbKpn)TKojx=lA>~fA~+u>&&T(
zsgvg$W_7fjh1<h5`<%6*dxSG)4toe-G*AMa;S3N)VIy2?C#!FGu=A34cJE!wJj)a1
zDcV@Y1gxf{x!_m;>nRzM;q1LPcGySE)f_tqgT_Wg3IZ3x#*nO)lsKvFl^5ThH=$B3
zk>3T4XQmGo%}?P&N57iiIdbAKM)79=N?m1Ehw-D7LZK=PW1?!(U`$?|@aE01S5Ro6
zgf|*yhN~_)PI`0qT-(jYSp-C$c&5Tdv8E3gRbZ}mWb1)X(OR(qKnt|c^ivlnR%pQE
zd&<TDKkc+>(}Y&$MvwlUoPD0uq*MjbCY0a_$s8=Maf_Y%_-TCP@2al*G0VPcjE|wC
z`o@n00tk~QuSvDrdwkSO&g^%XBslmM_f-;5BJ&#{^8K)><`U2Gs2gr3bhV@c+9%8^
z(I|RRB_FU;Vo-LjOuybua%7{Dn&e2hZKiIn8Us^WZ0ccG-g&H!G(!tYqJtpwb-*T-
zz?n+J=6~^1{2<(EUmUZ(qfVN`Adn7&F`(RI88o)@agBWGM)z1VsE;fakhr)+J|3wp
z&@;mBRhN7vLbI{!&Yf#+a5LU7!bNj_Qllb#pjcsY%rRH3;)AxKJ|2Vb<NC;oCD2Zd
z)@p#JlGOrvYzf!^U7)F@fC3VzRE$4>o+5NA8D?I_|J++V<HwQ^qBE5<013KH$3`~A
zU@yq>Lxbi-C!crfqvo>f`+z`tIts>rW*faV^OqW|w~Ssr$>(3MfgRXNVds=UXS@g>
z!uO`G$I8q5*W2Nfb^N=WJR*7`ZbmWm@R@)KJWD>4ege&focu%N`FPw(u~3HUeSIj-
zmFSYmzjczN&V{joD7Qq3aT+zDt;@dLyZq~M40^j4FAg$QxHC&|6K?h=*9vjS3G8>c
zF(&w$pbcm`^et4>JX6!y{-IA=xw|u@3jYQLR$DH6;EBF*y^?MQce}wZ9%0?B`d&O{
zaIwDYuXUYT3ynloE|x`!oz2m?J_P1!p2?9)Amu&o{S}cTD_{jIfgTv9<~H!kL=;#7
z%RQrjNrgyjkj6Jw-C8}@qP_J@Ee>zJh>UL&a7zF~vGlxUh39?lYcU@s%i&aJZ`spP
zqCVzNo$_3>=iAlJF|M9l26j<Y-+N)ME_wos9C6Yr5zJ#h?CSjq?KqatG#0A4bPwNW
z@d%F~Y?X`SvorZW-F;q{=XxI-Xr3$6?{DVVO55g;G=&Rgts_RP5Lh8?^64wQHhPpz
z=}tSx(J_<>Gu@~g4xM4+Oct~2o@yUC$3FhG=I)NHOHpZIVws!YQ5X_9SWx(?W7fO(
zPi!CLKoE@kn2UE-CuZhV-sBR`KYh9>(sgaKR+2gZMY&i$)4RgGXKbdxJay0Oq-<Yp
z4xGkZHz2{->MXK{48_D`&q+XQ9f8@gUrP8f$n4Zg3m??g>idoa3c`%GX*zDY3pRLo
z@v0-)%8P|x?MMf*cTQB9OOJM)YFW9(R$FxlJ!BZ6xjS5XK#gq;k2!N?8%4fVq?yEG
zChH69YR>$?z4gaar_o;00IWb$zf<`JA6Hxgu-r2ZkjB(ppgb3U8+>wdp}<`An4_WE
zn70ZPQAcA|**kN0_H5;HQ&;M1?n+jiFWocd;`<rR-*I?k7MfPYVw+Ks6P^6)YD&k-
zA6S^BBmWtNaV;&oyGOd<`8%J8MX`&8)(SN#nY>RTkA30C^J{G$j~ZBRC<|pC866kj
z4mmsi1KJ*w`}j6JS4``H(Oe#7rR!T;LLwUk;lg(I?Af!GyKT4i0nEaMdSW@f>dKuP
z?A6T07?ZKO5i2-(8dz<dm5N%q1!I(ZI5;`b#OWHc7}Zqist0;{I)d?GGZ_c_JwUB+
zbs8w_kiZB8&y2$E2^}7K#V3gvPHdM?fuVYLQ6!4oILAZ8T+M6im{+HMXw(TBC?ix|
z&YW&Gv}%kG#`w{VYWi1Bb<3TZ-4cn&$PXuKA19H~*SCABBo?`kqgF<1=UeKw)%&#5
zTwxN-uw`z3AufeoAKmv2XO_vx8iAQH*(*ZV*);6F(39o*<F%$TaFK}4V3+0%qH4*i
zf#O_oiYo)ED>FhRK-pLCM!ldwSpsDfumpywkXi{yKoiJ58eln=2IwlKS^`L5$&w{Y
zv}Sfm8QX3v#Y<7H=#68+OA9Xls$A^lB$(OV7lrBfP8TR5KnZ-Q12#Z{!;*0L@KHLv
z(hD<Vv(^*Vz;mC%A*a_yH-hSBLs+@cr&6g@M$&Gz6_nC$oW>x<;is|O<kD5r_+{TW
z3#-ELt`BP*<|KHFHjeZHfnr7rfn0OsDb^Zgr3IH;SgUHbhblg-06{4Mk(+=)JS*-5
zid(3(2C~O$K=eq!9tpUn3RZYFwT4=4SLfBh&44=y>>dPmu28G<lmO^G_JmrOYb+=X
zYLGL_F~wXp%JZ+GRvNS0KKS(X)V7S!&}wd+>4C%bUG;v5u3J1(8XGB0b&RE)V;u9G
zh=)y8mmi`>YkFw^2EDMQbN_jLb8DM7=tr%1VHk(nKr=kpudgJTeL5iWxfmDA6dP!p
zD|ru#BW*ReXxGpr>7*Atv(qXU4Zct6S7D`d*L=Ua;1glDBU)PJXDmko7BD>MS$*dV
z7cTr!5|!I)!jTSmVXXCk2q|@`p;7^QdV1QE59nxU;SoRi+;Y>{CY%dd3y(r&K4Tc7
z`>`+c3RiinkffwW^p#Eko8qEINm)e-4k_koq;4qc#k2rbUz?}`2^ZW=wNF%P!gw)u
zaQ-a!fAg4oObp^7i82;&bVz02Hus~*GIMI~b^mamp?W5e?&fGsdyjCV`*6O+n4KK+
z`h`)jSWt9ZC_K`jumUY%-kI*Z*-*{iC`}hUf`dGB)wO@r;OYk`)Hr~he+HhN$V+?f
zrCL!WkfGoAZP(;9R#j3~S6gkyyOKZ{hMB0t8aO??2kDTb!=s}O^gN?&Qsbt!WZ8<7
z9DByDJGN%hCK3-q-8A2Ct(bPhS%5$y2k*!vPVXdNe06UFIFO{+1LmM7Da=TMP>|Cb
zUgSxxwavzxTZyV{<ug4IaHn83WsS!o6L7#I9-RxHIR!!&F*vcb>|DvO(LhHrhS_;5
zF<-RMO4s%3554m4S|fUKNZMf5jIlhT)cg=X#P=Svpe8c5<bVSlV(PqON6Gr+bJ|=5
zF^2Z7qd%i6Gx55!kKxHZoy!gj_plI!i}1*AZ|)##wRx!JSEWofmF8^?r@Q!m-ew8R
zRiEOv-B-v8v{u6w-C0dtoLHd&k5ApEl8ueUA0F;eA+740Kh<q}<D-(05(Lch9-1W|
zQBO}#<V0%Rk1<v_dL?H2du;|S_2{+r7~ixTfna>febJvZVb8-;|NXC)6?X1+F!^W9
zrz-))R)P#-(r8Tok2UC`>MG8?xIey={z%P5HmV_X(a%g;*+A1=u~KQK(((3ma~ZlI
z_6=Ggb{f@}$>m-vF8M;ztpMP*x1D8v30i-MG7|nM+w8B8dq3dCWO*dKRAQ%LXs-g%
zh6R?%kQK%Ds=0G`cjvrxkVB{f33Kv!+FB$N8xRN>V~Ovhq2l^GIM0J$CBxRJzIsE)
z4tLG;PxE527MQCB4!*?-EE=Y$V1ov*1e~A+TAHcRS`E-tvRWXIEdd*#3pBNE0j>$i
zfv8m>48mq3LLw0&5wuKeZrECB{*xzJTwmrsz-qPE90@q8@Frj&(Kmug!Wq(ag2CD0
zJ8+dmVr0!;IvjKV#nI+RrGd@(Bb}zx4GvZ+8%{;%v`^B)>JT-K_p5bK?SqqjZgGHj
zZn8j$B2WZE0-!`OlVC79gb<pYbIiLfvIP-pjh%^5T`_HQ7C>YPxCEeO39Kg4O`QNb
z)0V($Vm|=!`FC2D5_7eM2e*Z-Vt%}<Ml6Yh+4v~h>eb88y7qR?KCidu*etP-l$q|7
z1Sm-B21Rwn(vc${eBLP!KOIAR&QTuMA5Gjl8k1H_W!ceZT-?tvF>uKpoW>J%1R+ha
zvVytv^IYxi{LKw<2fE-wSI`(2mL<%UN%=Np6K4K+-~Y9Cx8x3@o=_VaV8s$URO*3Y
zY78CVC?=x73Rq560-Au1MVNkOs8CU%cA+($I#cUK)s4w)J<tHfS+k@9;oo@FLuFs-
z*r_Yw;XCQk?Z;r6x><FY*uDK_THWO@Ck`L(m{9GKHD&=&0*Y-aWfHA*1o%UCFzbx7
z;+(IW>*f^S_@;}cAOHq3%+)-TN=Lu`K~Pztrh?ggSL6C}_QCI%JVgk`=q!>$Pelt4
z{rxu_JFZn?1;;r2)p*f&%3@bNtGyWGgIf&a-mBK9_xshKj>}m*CLk#$+aksoJ()o=
zxz;det09Rrlw54>aP7UOp-hFU{;f4#bIVdKI27kfc)b|d(JO;?4~@!(dQgo7Xc%MX
zcBNKVOZJ@9ilQh=Q_20r6U*i!Y&g8;)}YQ+h%xA_DG8**V@QW^=#CsN2tx@o!hU*3
zwd%^t+NwJIWWB#;9Pf2s_Nc6Z3ba;9TiBqmsEBautTxT>bYF8Xrx6Sbs>uS;V9b_e
za!m+?NhF4n&?20D-Y0H)uG!+M#QGJ1^aGZtNqC~d`)O-5q_Jc+Km(+SWY49!u$+ic
zrqZGdjAEH0=4!;~e8kZ1897a1_P_FJN=;k5b?RT-uM!qVLWOzRJBO)uUBpXHeB6ui
z;!(_twa1^(UVQ`9W~#Y!bo|f!Y~Btr3T=yMZSX*!yn~vzc$2fuK1s6JSZGW1(+(?F
zjL^l-QBXsR4OHfe-BoT--DYi2g<{8N-=L)|n@hR=N9F<>YV**yn;qAI1vX)9piu9`
zuESW#z5@4g$g|3NwRr+cq^GB6^5hK-AAC#gVb3~u*yFGv&>D<J>x{=D1VPySsIT$x
z>-L&$e#jQfP=v;GsWf%G;q3p)Ts6rzZ9tJCW>=d)H?~SjRU?cy>rGYTT#Fv8-;tT2
zHo+`#hJ^R%5FSqOaH=A${18flTlHARXgK1*OJm}s#>(;!0ifBCE2LWFZtwmHKhvK1
z&yfOJli9-nU``<6T#IhDSUa9i?e;4v_XvcpwrK34WhpRM?XDhj8pK#MO@b;(10hAt
zDELMVmK8crGZiv1H<?%ibd~x_18@wS0s|1W$p<Pxjwt6O!A+CYuD^4#()@$_`P`C(
z0f7ir?d^K4GjISIm=Rnci-_SOmyj>q|J+1|fod?sq<ijFe8qfu`KA|6_5JNT=zq8T
zeVi_*3J(ZPcp3F`i!@3qz!ISX_&@Ut{N68?8)gj5I|oEio)cJCNS@^k2?-?xQAD3!
z{kL4<)sD!v5>+v6nn2hL4D<urT5j-|f+7HxKnXm;O<K=M1tkIYgn+9B?2%e;@g#0y
zCmyFw&8q>6)RI7fjP13$xOPzuV8vT_x!RDjAXb8X8j7+p!na^BRH-vZ*e^v5J>4U3
zd~mJp+~ssc1e0xN)7?1BY)P;c0tvtbD&XJP7fw4kOW!uFK7BZe1c3F(T}G2!p7OHo
z*x%nFt;3zhmlg(ZG6)F5tPcPky?ZUrYD=$<8d$9_5}&k&E_Ge>E%wSVj}WWQ7ap?H
zt?!fBFiz3q<G6+kG~Wn;iqvr3PU|f9AH3)vFF64+<~1Oc_yCgwTa{au)VI4|Y{?W$
zsSj?TzV+1mZ)p#bj_m010Sw-Ql!uhZj`d^Z!3r}rmWFw+VGk=-CIDd$`cWjII%VbM
zy){0}WU|%=7`omYlCh9^wSlr&i5R9w3@_iKUSrNtASmLbPhIkby-U8rVU8u#`3&($
z1F6O^OCmJ`pD8y;nW=2*^+{@fM!HM(WqJ+LMk^{@@^c~XVdu}c>+${$tsUlgHkm1`
zh^Y}kn1j+Q95E8Qulo@fc=FcMO^N7|8wA?4s=~x-AeFnp)Ce0{M^GuPA}Qc4c5*JL
zl>wto<RxIar}6}pIyT<e60JgDTjXT(E6)D<)PHrMdxnAz<P3CN(o+FjU=9ccZ4Efk
z9|!1zR$N3FEs$U^+r(6>m{^Ns<L3LFCwu)memvwyU!>BD6AeiYUS_&Y<*Bmlsos-Q
ze*NsS(7j1al)yg8idA4a%al8%x?95H)BgJYb#^9p+LqXgK+@&f)x)H*2(Q#?Ce+Lb
z@#wSxMxn~UPq7lnml$ZXthSJaLZ!qUVb2mP8fn@}o0olQ_uLOnx<fLrHIC87F{-rh
zffPPZnldMW%f$z$tS{aj|NIW=Y772F&tUE{o5XiMN=8S$==@zwX66oo5F^Z)E6JL9
z=sRj$q{)aYmwuV6zH?%wv$hCbbZr_rR!x{VZPlZYZ+GcI2fx+9HCL@c4;pJ(QR}Ha
z7spbDN+Gv9Fm#8cmyJa}YGCOc^WJ={F5O|~Ip7)tGca3UBaArK|A#WXajkxQCww9$
z>1wFpiyN7qyQhlLDgW2ft-*1w4IS7bV1X87#u=Tmh!_+n80TJc-Sx;8u|(;PkuK;|
zfadCes*qT99Uu3x(F<2p#z|_89%OEpD}@{i@%0Dlq$**qMbf&m@$hSGw}i~1)Qt;*
z!E7)E5CCu-Wc{)SCixJ9mH+12_`*}3Kh)O40a-c7iX|Yr`^b^Y6_`IY=KUjn;<-ET
zCkQCzHM8DeG+;EFJnAN{_U=H+>`3GqdZZ&<(5tARO^d6wR0XjT^mt&De0cI#vQ6zl
z10X3NJE5VL)=EGEnt;&)GPVS4fG#l9Qb5Nd9AJ>t0zT*g5ki^FB*Xj}?)jhV?qwzt
zG&j#?+tb5iyJ&)o1gPeb^W}XxT`)lJymH2`I`B1-^LfZ%-IW$Rmax-k^L;72S2K+j
zC3asx5rB<KBM`s<xk^qbm9m{6%0d={eN6BtxHhFAqTN_H+{7rr(xb=>GN6qHhU%Rr
z=bZDux0AUR3nX5md*%SSHoYI{$F>SAS<z0UnSzdvG*bj;!6Q?lia?@9RY0t|jLsVJ
z`W7vyQeh5LidXJM66$1V%XHzavmSPTV<8#R8^>hDLZovTSH+4llvdiHqkCU(QMM&@
zqv=n#zj{~w=SFJMN#ctu103S+a|tkhPp?+<ap~}6pFO{cLs>AwohH*8G)4nMpIuB?
zWx?Yc?9A<a-E|j5LIT^Jp=&LwAeN^3#~CZR>q5F?qrH_DO4RD2G>ijCdyLzFqo|Z>
z=}ho}s7=Cw!7@||z>?^l+^8wmAAa4<E4<BaVPJ&%d?t8^Yvbs_rO9Lm0{=YijF05t
z$i|d;zBT_%r!-esXD6M5xO>$K!~DY1gSEuy!-E_aANF{9fk7b-q>=(MTfm^xxNz;?
z@ldP3kjYEUg^gv3A%USot}fsNRHYtLrV^_W!+eWt8VUzdVGeQfAe1YlR+ju-ZkRd4
zJ)b?c1e7a*kk2??GrB@TZbB#x00pi@E@LlRv5Dc#z;2voJv~RinC>Q*aaj-Ue#^pS
zhV7+YyX5%s(#_(5zIsMf^cG4Quau6W`iQz0Kltt6#2YJ0YEG7X?3QRvu0veN*DV2v
zv11de3|x$rY4_hOwQ)@YD}F22AV5L7QQz5JsnyhS3h?SIYNJq98mQP=B+}^{>}@^R
zeVr`==_*f$Rg5D(dT^|@MWddes3covF?BCKik>t*!!+D(0VN6KAOV4>_;oFL3e-%-
z%};d{Uf-Jcf53m}?756IFgvnbm#rEn7PUG&$^~ckJCS}Hi$+gU2GXq2!kjR`5~bj=
zuktomdSjT7#RQ>LGaOYkN=R2}2TRWi5Oj(fAdRV;5#rIQNiYtizQV|*5~nk->mi?P
zWguTKsKOknKa3Uh6OHc#t8cu2tu`|UOC1OBJgDcOT?Pu8AcO#n<um1Ikkr_aImOru
zIY}LFnVTl<QimJdJ(oqSY_Dt|k86yMc};VR=4w=(gm|LHXw9IF4kVoBmtQAk)}`eV
zyw)KwbhQ<l|07~GP&{s>>V-1KeWN*%eo$`RSV*&5jvx0cFYW9(sGMDP=?I-~@}fY+
zGJ%M9m2gnqV#xuKTy!GL8Z0KG7tZ|LRdixt2`A>gyValgDzcmvi{T)XSTISxpcFp&
zP-50U*0n!cCWY!W-L~urXk7wk?!4M6))`HcUUNnId98Xgy5N>ZKvf&CEQ=MF{=lGd
zRDi<1%!bR@23rHOwYh`BJl**oxpU2(bSH%wx+9F$GP#rNRqYeAk`kGrg{vKb43rLG
z)bx8jY4%PGl04kXFXi&#h{W<BCN=Vfm%=lLzQge`E;Ktg)zl>J7I>ymwoDlD!1c#i
zWyxo%@!W(?rSXR_m`+cZW=f-;*aQKUfMu9i^<?+%A5<B?TY{!Qsi@lnWz$sjfgvEZ
z8lVYufCSRm8lbDxS84zO1b7aR;wNbk7-<8RC`XkYw57Gz(<G~>y<@Kq9A$BSgSuX8
z3zPupJRKRis20QgI+yICK*gl-6bC`NTwTz$KMnE}N_mK6-i>+ynII>+nav591Ywj1
zvBB)Us{20GetMVn0bh$2%`dPhMIN9;u`N-Ld5caM#Y5-C{>5*5x3pp@OoUssQbqs;
z@d;@Lm1gh8ZlQ#8FMiNeh3oFgoji>s4nx1`Hv&nsD^LMkQOi+yA|>D%UIFYWDp<{P
zt<oAO8$60V0rj|=#{%pTHl8l<>e$Mqz|BD0)#(Bj3Alqm8L)fA^A&Y#pbMv{latsz
z`6~sKuNrtcR!rLrL)selO_VuQJII&3<S8d~gKK^`Ui}sJ)MP+GIJi~f8pqfuS9V;Z
zga}}mA(hLG#)WjZjj$u|>KXWV%|79)w>2&4GfblPYjPEn!C_BZIluuB#L}RssnDv5
zXEqmiLq)7WP2eh9c({kZiw&HQHB#vU#>ZgjN|!{y(u9dsM{&Sl1l5`gl{r!69`uwU
zl)BnxeXYIrjQ4&1*rd-I)1DltqnOkZE(t_b+>UUxd)<8=0mTTjm89knJ@>1J?^{^|
zfzpkuXMf9F?Y#9_5@iUrPX&RrVd_-3=#Og_C;sf_vr5>_R<@iw9ZxL5$Irxyv(3Jn
zlr`5Ax2~3q?1AzMO9X**sX80Nd15v6=~=57{Z`HS%(3b|T_N5Gs~Xd5?X91AY1s{g
zWR0N%Hg4R+K1ApwPl+T=`}8Q2g2_Uq;XH(wDLZc4!EKUMyn~rSuoW>ZHkf$f7<uDd
z{D0aS6YF4{N}+(Z-hvo%ix0)Adq@1_#r<Ri5^M*U>kTC9(vrYQsV}(Vt32Y<cjAMm
zlV<3UuUz1%CSCysVQFeD<i<+&d>*od86iu)mPzKbsY6mgdXx+pt&#(^+++?!d_+<V
zLTQPmlh+b5yV|m^Uqe#`(wqdn-F671y`4hDR6CqJQd9Sc7o<W*dzQfV()8}QghG@P
zj%!I6&gd61@5Qlc+(5g>#np(79_iG3vDJ*pihm+^2~p7oPy$fEGJ0S3vVDxpvg2Nr
z^g2{7#u8?iE6hzJv&}4uB~eqQ=T+xC=-r>z4lN4}B+62q8v&sLR4BJn+0cH^yb=&}
zDx_97Ch_Q8c#G9Wm3Q9^DD#NbJd-;dS-tryR0U;@)Q><%ek4hgv>)t_y%q;s1&kpB
zo=c;oMH|_1yZX)&NwP>vjwwwFA9;dW@x(}{#~}a=#wHqXUE6y7ZuHmYRo-P88f{1)
z7h|JjHLlit;;uWV{MOI5*<@H?Z8V-~bkdZBm6tQITfgNW+P{ay8@l2eP*w-bBe7zi
zRMVmi2bfr<hK+awgILi>dZJisQ_IHoT%4FNV7~3H5MhRg72zXoIJoAA&{UNHTI&q(
zD1Fa_*hMR1H;xjtNEhDYV_`VL*I-hFi;Bvw%WCf*^vIbbp2Zee1h%W`({DbVxf#v?
z8v3dm{Fdi`^sDtddJ5)Sn@vOkD7T^9j&w>k7aHQQlHI=Sh<;$8CQiOmm*HVY-zr<N
zszQ=5XX*nQf7pD>s<C{!S-WdhSZN@ENFa1{WmF}CMqo8GEz-NplH}4NR2hVi-0;C1
zE*>JN5zP{sIN0emp59+MOaH!Ko_(8gPkKMXb?f#DODDD;EkEN2HIOtU=n)J8A@gem
zp|&)XkQ5$z<^45xj8wMVQyD-y0->udyO#((t1?hdoI1kc+}>#Y8sn8(y3jiiO32P;
zsHL?Mkbowj0U28YHb55`YAK+AjIGp$h*sSYPLSj>?{_co3}H94gAxE8&;h5w4s_$t
zz_C*vwe%n{S+TCqagr=252Z7!U4MRA=?GY{l1X8S6<^(?88&|72>obt{iEUR(nl{%
zS8l=fK&6s<3OlQ;WO$gfH}ByDf-3cMc!P{gf(B%U7_^oU+7LE4Jo-CaZ0+^W;SKQt
z-wG(CsiY|b1#%mLqW~fixCOkzt%;clkMUHchK4i|g8(|yhG3%@i~|CeVdB(4u0ei%
zjd}$@m~-_FpcTeywA_4Vl~vzeyCRejg&W>P1wlg(Xp4vey7t&rLv3?ir2&^9=C5Y>
z!BH`ii6O@^!yNJ8Tj~?f<Gar9C+>$&WU21~&_q;hD{As$RG!`U@2@|}(%?|&8DKP-
zKZI{?aI~<~L$7#bH<qoe;bckDagAtOP1oBC7^pDtN~{D4RkqPW#!;Zoem&4_;FVe%
zpbO|s@PTLpD*&a^{P`t~Zs?TB7>sYH54mjE3=)8_13hHlW3mn%!uJ3sA>>#wv=ssp
zbTkuuUVylQk7^1htMA`=|HV&A^fYW=P>9Y=@xSV4ipQg4U-$YQw-^n>i~8OmXf{{{
zWJYKV^jcCn1PyS>r+Gi6%s0ir^+2MeIjy$@%P0etHWk{<ttm;K=7M1(O^?)CLYO$s
zlLaPHx5_xsgf6A$xxloOw7wTV;`-ay{0IpWu@D7>9ZL}1=MvhAPtMfZk|{EYXk3J!
z3)gELNRUe*R6u0jK+PS+Jh%6#EO%D7qb`2A@19ggf=aT=s?^5faBqX7qke*x$R;)w
z-Wd=>v38dWuKr%ibW@C^n&#S#kW&bh=}H@8C_w|45d$@GV&G{fc~@4|bO<Q15}^(x
zJ&K{2Gk%($Nh%hL#U&BStx>KLmaaP*uCnA{&z+)30Z=NHgt?oyhllC7q{nLLH0{OP
ztf=I2|E2?%@Ff3YaFmb(Aq<ozEUy5XSepk(^mxdvoR^na4LG4+xx4(+&0Bs1eq?M{
zHp-6GpM8Iy`N`6-g@mC%;U&sOc|eFj0>UI_-40iImi--V6C_{4h&1&@j~F({+=lkb
z)II5WszT#wYq^Q%){HAr8Bh#V8wiNg42PvokQ5Q-jBT~j{FFav^^H51e2Y;q4+!a~
z9W9_(?yJG44rKfE#n1?u(+kC;wFh%72m~R~5`bYI;Ct`~pM)wyJDh|Lxlzx1S9$*_
zY28>k$mmoO?cKwixOTYXd4<jJFFTH{P{0%Yz90-;W7UQ4-^-1^pYYI<K&kUb=yKO9
zBvz%255mN$fzr^+?-#LZ0iAV@Ct`Tmf69s7^o;j>zmo$Je83n3#<ZUvG!{hOl6%c;
z0OPa;GLk6x84ie6Xe$a4q>PHltag3OFZ*71H3X&dDnIfq0vLfzDZAa_Qq62!I6B6R
z<t>_E2T*SDMnANnFKmIc-+SYTpM7=W=wVgg99``?P3p2iN&(9%1LtDJ5CTi9AD@Uh
z!KfYN0H1f;&S$T^ZFJrZRUL#;NV{zUUCRNx7P{IeZ)y%|K#GWxs~LW91QTMmd*m0h
z@t&xqFf~YWS=Y&``lhr2%*#%UKfc@3Rt|C?-8PUgZ@F`na*ED)Kp0-(Wm?K72S4eV
zaf3n9f-Y7aQ2>E}GL=|$^f%UZe`{^AD3JAfT~K{su~;lFUAlB>Z}b5d1Z1Y1R<a7<
zW`Q>FI^dXy0s@=@5;z7TKnWDT=&iRGLCv={s&3An{?30n+yDOwVBzx!#|RPhB=kTB
zT#gt*RDpvEu&p#oFQ`#3mAF0SMRD5hbARZ?J#G1vj#hSbkVm@Gw_J>t7rK}8*Z~V!
z?11IVmoKDY_iC2tW`q?>n*88d)pjUWH>b1`gpk`*NM%us%k?rXj(@|J12G8soc`)t
z2vG<V(idBinG*ujEkwbdD=oO2U_D7JUCap-NhB-+43rvRBOVt3t;c~t3Uq-4*mXb&
z0$boQpcKHWQXxERI?PbxG+-mO9G&MeZgS#zA#fUSL8TsOfCQWdZr1u1Yoz=D%4cL_
zN3kW(Ts6xldu)h=IcEc=BE>fpwlOx&^uWCr@TsjNNPHC@fxKTD&4y?k57QfGL2%zQ
z(VKd%7E^QRM;tBd1mIUdB2)xGkAQ<RdPeR`mR(%DSWVXRK)UjMgXU$+-odeEzIrDU
z5N>0lkq$Oun2aZyiB&l^4KDbkyVmBs#g|;9pNnhhB8ckQnPpB2mh5~9>^HsDHO7+_
zg|fUD@~IfZ@Q9-*!p3U)LTesgZG<}+VjDpzh|mau_FO`ZB}lw&BwHQ!xkt&ITWegk
zbs3agl?~jg6Txu<IHkZ>*`TwdK&2kG6?^cUbHTRT$`5PE7^0!KxSxHCV_d<O)uOxk
zfc=dr4W<)HW;46Q(%^bsR$cm;OQe-+F0wVz8RRbS{PgE{m?Gw@B@9-S*+SJylJcza
z4G3}3{0fZN<`y|g>}2zG#nfqTyZ=Idyt%K0reac)H|fY-U$7Ft5GHjsbh7=*`6^U4
z42pi>lqx7WB~+X&BtoZ!+XdQAkG#-cG#{nOv)G=)_?ovE<M{r*`np?EB^L0F(Ric8
z{9O*LyzuclBZ2hbwGxS5RH1^PM9We&P@FRcT6+UvwOXxaR|b-9HGoQSdKN3?yE2Zx
zRuA+Hv^4Y#v>p{5huT&wqJo}cne-bGt%&81Dom6#lq_8J-RxRhcy0$Fsc%^>YzSdo
z#Q+rppwWUOAT3aWbl37ldVQW7YUrHOh2kmOf$?$ALBMb+laOQg%&;*o6;K98sCL9;
zX;YqPdgx3#{ej$epz+~XP*zmw$w7~49^!DGHA}$n@|zfgKs-PJ66UV4lZ&mpm-N=Z
zKt-riGEPunV;Ma5N;70Vb;C?DNSE}*w3`hKq?oe?T0y18+}ATrT_qV$^?smd+$!UU
z3l{=YZfQj$-4DOTTMvKKKloEN^yIX+e0%zTJXf7d2-ywpp>|F)+Bpqg(WlS4=Uypa
zFbLF7okL-^BNG6A!9^vTg<oQkt16D9@<|(sGcRmSKPdNNj4Op!6lv&;s>0Z@-BWyP
z+X2BuU}g}Y@xm~KP{P^g-f1XmO?4Rg!x0zXFD8RHDoZOdcWX7M*@eevSp?EqCTOR`
zcJ`f@h($sJWZNoN7+RpM)ByCfBmK~mmo05mVZ4t#@vVWUT<}g_>s$O#Y=(cK@|xup
zwW+@L`wt#+)zf2NHZL8r#<Zu0?KPt#VAxo}7<WXwRUoRmzR}%-Z7;-{YN^|4_ve}m
zdGz;V^20t#rM49(yLawu#!Gw87!a5l*Z?eOLy2OhO6|VPJ3R8Uot8K~RNT=Fzn^?j
zrBQ{uVwu9+8G_mnb6ZMCqD@_0uy`@z&Cm}NG={~Q?+|)`)1k`fDSp=kWCoA{Xd);A
zoMt!;ytScNV@qLM2`D0$`jmc)$=7ph|GA!hew@LmWVq_Qzdh5fe^wh{koMbywhD;&
zgpJo96$SKJ^3~QIw_V*;0>@M;a43+dD8&FE=mx5jMZH(DE$b}lgPUu+bAj)^4cg!I
zS%j6cKDyH>`q&rE4%napgDx)6tz`1v?(W5>zvou%z~;oZm!cz#=3+Z4ck{Qw{H;{z
zDTi8G%MZG!6@#QwGWQk7+T<E-o%xx3$shWOe$duAM(2@h2}q2lb3yWb0Dq!x3UmZJ
zNK{Qg7w9^=Py!GHK^PJe^b!UGPe{c!KPZqkHGl;i5P%8>G*}?h)BrwpEpKm1AV15{
z)t!URm2A$D>-v=<7P<r~Olt4!bo(-YzoLqJq|2uNZI}9^zhJFx53H8t!bLbCTyL~H
zZel}dZpZ!my!gysVVf+F%?mVHp+ZJ4K`{&&n0NLiC)e6KPO$hy{W-`rG(fXQoJFNq
zW=sR5*#wAz<U5>0aW9ay*0EO%OZTchKe9LDU;oG1848i014yKlpaTwp1YGW_q)H_K
z(g<~`pTe%8JIz4voVi-l+Z*UGhzEk{hIZLFz*E~085P8|U7Pz{!a`ZMi3aPAWf9i#
zJCUtaI+PQr04_2a1uDH8b(Qod&+hZa(xf{1RV*$VDeA<rkrRw-E?M>uaB%IYAJ?I*
zayyL#ki`fDP38}o7p_zC2pe{vZVFn{C6`<<1?KPXDF$u>i)Wbv9VjhQ+&=M+&p-6n
z`1s<78?3vp7ZT6`B>)os4j@&jo(Lu;n|d7p2m*Qs!Z7G%0H90;9RribxYQYN<W`Z-
zV|?5NbB<7%y$gBZr3<U>#8~IOWP-=DLQKfU^wnIin#Zzgs^i~y@mXW=?L!tcZ8WXO
z%$WuX1{R-f*74eV!oOSz1<)y0BVSBq$rhIlG|eFcKLP_i+=P=-c{BCoS$Tk7x5HC>
zH^s32*SCLv=zs)WN8JQ;V+kiF-1deky#(3m`4FaKbb*fOQ`e4B463apiN*m(Hz-%3
zROxg(D<t?Oz{zF~RPu29H2XyTY3J@MvG)dIl)z{T-AJ-G9-T~%aPsCo970oMz-T<u
zn7(ef>NYO6{!T*Hh5${MTXNKb$qxI#95(O~rAA|8)6B9fz}jwA3YE$vV^eizOAT#x
zzG?dt=kB4%!Z2DC0!ReAI-_YUDKPnT0X7PPkbtxzs0}U<xn>6%#IaBh3^i87;7Q%{
zGiA>Qke<OMzAO|<s0OEaN&^X)v~ca(tm<U3l95oYS~zcCqEfZQgYuaT4{jmNu%+oA
z+*UAD=`1-(XnP*--MQaS&2*0r2)DxQ?X&>$8P1?V&md&a)7|y0l`b^Z##W)NCJ4wL
zi?lPQnWBa?7OQ!3wfv--9i8L8z&tjXM^dETU~Wq(Y5L3@WqzgohWvuA^_(Kia7zk$
zQ_=@?(9R_eShCh@AEI$aMIqI#k))HN6%vqA3M7C;RUvX&3CIxb-fTBk&W_yq=+Dn4
zy_R2-u(rHr(u(?#?x-X`&Q-50*G~+bNckq3jBiN&`114)T>53M@cL1F;B-V+T`f)u
zrtDlYkP|hj+gMu3{7%cITW?9~sH>1)aK?*<iVMg<JXoJgxEvX)s8#NKFfL!t*v<!N
zTnwpkIdB-xQ3UOB5pEgf5l-d@*B#s>z2dX$cIM%<mhY08Lu>mAD;@evH?reiKli1{
zNI{_i1d`2QhE{)<AJY!(e4SBNnt!9FZ>_PLHS`$U-<0mVWbwu1P>%U*3Gad$1<ScL
z{-({nj=g@*^e4EnYwd?9tk4UGNA8n{<daW~h6qp$00Na#G#iX?jK|>ZEmyf<Vwz!B
zdD_ypdbREPu*@x%X-qaa@#kLqb;2Ld+$tr*8#Ex)>D*!ot8W-z<*g%;ttPQm3DPPd
zy6YA7?8Q$iQPrU0oC;Vj@ohOp0L$e_p)8k6t29lsH~PR3Fi5Rh7lTDLTM$tf4$s7W
z1z;`8;>IDHN-1!8CRoE*`X@;kpaL|Ixdv`ZR$vKh3u4@>qkw>Vk`<2*eF=(v={PTl
zS_S!{d?~)CL?ZS|)t_d+UzycKMxVj(a8~gV5BK6y@b{b3YHCqe3+~=t-FEl(>9-^;
z$O_EKE2W!N*_;cDn?s#Ab5Ez@K(Z=dm2fP)2nsN|O*-SGDlis>!c^jL-7(I!=wm0H
zN}8GWZ%S9nmBgnx1<ciXN`j{_)%qfVE|3CcLg1Pw^1lsS1D2J_AyA0GNv$tisRe8#
za2hxU+JFM5fh}+^(9!_ObLvr)?6F4x8PT)n&(2=_!I;w@#;AF_?hR#LC;3*UbLtRe
z9{>EcXs~vzQL3=ulnYMJc*}TiTA*{rfzlS3|KHX)mRERFtIlP9w&X<F4i-2r*sxFF
z4QeTgl`haRm5kF(s6jfa)yPt*ktQjd-k%)n+U+>(@G4!bgWk~+MTXaCh(Z$%C7oYm
zmBoi&%<Hx_lwxi1TGPdrv%f&<qJh{z^SmNtxx`EAKrgAzCCx~gT;=|I!PKX4hKO=O
zdCkqp<Pt7J92whJ2wCaoG6Js$i#;w-F?00#Mj(#3HNqt@sUth$!i`9f$ru=T#@mmb
zH+L;1?q(69a$l?Ca@2!$vG#j?Y~4HbzBqs-MuqSV+9)!A6omMCiiF*+{5ls|d#kRP
zn=&*sVvCCKyG{xQLEov4t&-{oV{U&KOL#n4<TMvBkM|8MOj~<RXmH%~bvvH;Dfjhp
zA$%Uu*lGZBh-WS-Qv*t55%!f+^th8G1tn)*5GwQVSp&eXXx3C){rlQ7>*>Y1z5ipA
zYm&~gCpwZ>h)MRkyskg?n&FLhhZahc@k0m+wwf_7Y;?}K;L7-RoYdyeP_ZN+f~f1{
zm%F)O$uP%F>!qgkZ$A`gSEkvGm7r;6RR)q-vR!Ak@KCM2a}!f}gyVP3IPmh!mYzY|
zIG|bA<)7$tiaU-If<rl+aa>AOjHlOe=ZwRYWlxMGC9ftS)B8fCt0V)aWKo;zk5&9D
z*Q|l9+};Nl_bhjxT%rYT&?1?fW+`gz_IrC`9v}G~+c@~}4d!hSNXCOOz~sZltiF+}
zy*p_3whA?6zEYu#VS^PwFSrI;psBGz5#SLZgYt&I<C6x*240$H20pV|=C6LBVPLK*
zvhUw}M=#`XGIj2Ofd`QBw=uM?PTy<@&^Qj>ckU3Gcg7t%<9PaeauIB0oT=gv7T=#y
zE`Y--bh%Q}E?Ag(@MMV}dCtD($9{V2%`uBgWVLaUWwLt5?$xzCRsTk>&7@Dco{JX-
z%yHeh*k7f4{T?eV_@+f>Y6s>M9{qA3yAfdMazA<3u$1p(mu9a2eXOeQE@c$-U9%|y
zX?L_tDX>94PFBWdSdZX0d?@<X3bWO75$XY~2Z9(JbW9tLc%-4qu3ic-XItHF+s$-|
zH8w8roy?>%W}|Y##vUg5bAIjT)6MP{zp==eJv1Rfh6{kHjC4!5=z6ZTwW=Q6NSO5R
zDAa-932AY`SlU@(5IO_p``9gH&Ig{SeZD0*0gu}T=4!P~UO;Q}8i$~851?bfKE3N^
zGpvTjJ&5l?n{x(ONo%F2=+h%<Lb5119{|-;yMh@BBrJANAVnz@BUcOpidd_hT1r2<
z&ADk_o+|EE_8DeFA>?Dd-8gY7V&>&MiltVd@knDvY%#$m*Wb;mORmJ5^DT8eu{{~p
zjEup%brKWTap(jLaw}KKp9DGYFcr?RYhd0RxXb4F50mDSRRC0-_Q2j5YH6*(E^5HR
zNZP87_Rh5Jd*1%-kK_(y3v4x3nt<ip3ll2P9$Wwi7fPrv?0OTmG$^fMj*|HW^czvd
zyWZp$gtNBNr}dX^w2xv7-4bhb`fXX>ijA}Jx{%I1^P^7tV~;<E_$nO#c_I>0P$xCN
z@7R5HedohOFl9o((rtxGza^R=<CTn{Dn=3<=sxT0{qfx(;i+`(q)K9iTcCn4$taEj
zh*P1e9)kc{sRag)Aprv|kZ1r6#VVOdr1}7~mFPfF&)ujo{|^j`z9;6t&FM(XdE3*d
zl7)FGG`)n!J2ZXwrKxS6AQ~_<Fu-iCHx5cbGAbcZ4G3bskdt1yf>1K2EtL>$jnfW6
z_!Vg`@1$k2G%srn(`K{P<YDW*NqsD?%*!4g-C`_0CDmiy%tz4vv7B``#E=@p73B&~
zGzKJal`UL+(|xP?%#_z!l^P#`;N3z+sZ{ldx-z2pvkx*kRvV*G-7>k4UBNP^xe)xm
z3)}OEYL+Y_v*$LjxI2<6K^qy6rE&DRCcgl~cED`*Jh&VB{Z%5>4F_ciCgQQ~0v>+s
zF;=8pQ)Lq$?OfMY^Ag{ku!bXeSEBAFc1gX?uJ^gW$yZjTQox(xjnjluWVi+M(Z8hs
z{#+(Au0=T^&Nn?w_Pt7Q4B{ED2)si5M1y}r=Se^wi9iM<1d=CI@kyTlh8(qVhsQ=P
z5Dgq@IR0AFl%fR7f%$0=>}B?;qa8ohaROM!Y_X-!-4EVW(&|bsbmjMx`}3Xj%KM4w
zbO=t3_SKu}21O8VrV{X$skAYB?N<801!`#8eR`4ER1l$Cq*||dV^>?R9H!<(Lqbbn
zONeMaLEucjPr4HlcAxtZ))}o!>MhYTtzuv>@;&O62(QHWe8E$>;J6j_Z9E;}4+0$<
zpkwsG5m2fMpjH8$in|VNHn6#%Z8Ffth2u^hFZpfA-S#a;b7B@<0oE2+%i=CP-emRd
zNa^2n&x!8UxmU>zvH_T2VD`hPpb&z#28Sh_n7la3;hEeS2gafMAFF=S@5LWE-Bj_V
zWDOU;Ec>0cRous5VNeQGr)w{M$w|*Rqpqf(CQD=jC|}`W>R+?{`}{_gi5mwo#K<d&
zAnfh|A>?Pc9#+=van@Ovo5PwbS_EYUZv_ib9*i>3D^n3ULtZ&M$G24jJ8_Zz8#6n7
zRSs`=3aYbcoLY?#JM_e1+?TC$jQORh55O%jJKEqFwZ;K7j?obPq82eU5=-``s};2p
zw@$xun6{x_mv0Lge29vZtz<GEpB0!%JK34r$fh4o$KWd<0+o1n{P+2F>{li_YHsLg
zY(zvfo@f>|RlX{X9{W5G7fEePQY9rK_<oJI3y$LK(|34CanW9II-zl?<XB|(r6gK5
z(gJ5TCo|)E;vU&BY2XZk!U+MG4SB#mEN-oG6d06c0cdM_M)zs28yBK(oPcVmZeXay
zu`w6Ew}#Wk?2Q?#ob|p;o^CyQ=^WM&qi({V`(b|OYe}P~CG5|mgAS6a09)_^9ZRDL
z72_*bS$esVmEk>dTWdVtF)$d<7rev<HeI|Kc(dU6){Bstk6QK;xh@^5cw4vkY;&UJ
zKzVs4V7AyYxsw#dI>|QCyz$8=CVRt8L{-4mJSmlLF1}(*kUAE%dq3qoXiS$Wu%?O3
zjdO9MpZ8u5yGdbHm*I&am?%gpr}^a*R~Ds&JLUi*kPW9vbw2Y8&KiWXbL>)F#Ghk#
z`VRYTW(zkvdHdVnZdQESr+wPq=mSGQYSmcGT3`?uYi)2}Y@7N7lMQFD9#(+?U;wa$
zIdMH;72tZH1VAAp0d?FgaZ0#iM`Q{5Zh=)Fk@C1|Hy9E5q{#bT1cJJA>FV$yyvmxT
zg&qu+KZuY^Qiu|w*Qe56!~TR`%3->2!6PsDI8A+6Ln@7Nb=<}=F{EMYzN`KD<d!~v
zy1~MG5JvT~mlZ<q><fWVA_5tzGj*vKxYTp|qP5u)9Rh=8hP0LoOh-Au5U_^8DgJHX
z&T~F{BoG7kgurRQD!?V6BvmpMptvQ#6hOHYxG7lXJQwrd_c_0O*ybS0U18QIX<BB?
z?}fb{=k`-=2fW}F7%9EN>|}5}T3<T=j3hM_7e_n*Fi<+g?2V6Er)Blu>?iIvf43h+
zZh_0pD)692R(DUEUE9+YYHoCh%H7a<PS+BOXSnCR1g)e+N`*)u+N4-6cz5g^H7QuK
z7j+nze2)9?O`7~9Gd%5-kfiBom{OQCk8}R9wi_aQy@o_Dv%ep1QRq<d^A$s+gvz@B
z3x+Uj1f3}ZfYL<ru*@Mq3K-*?^>xqvh688y?)<g8O1MsRtQz30J>+{6`?<dPkDnj%
zfB1MEBY<iJLcqc<LSnjCUFFwr&oq0|SQOO_pQ96~(V)OZzV)#9Y<VNku!3n)9dD@?
zQSsF7MN^v#%Z(Z%g3Qh=gVQV{U=fX>Vuapo+2@He+)TM6&twS7UPl3nN94w1Wu+B`
zk}MV@6y@@!2O1wZv)^xeEYrK&o76}%59F0s6?cvQTpySFr~iRML8Da+LM*&lG<5rU
z=UDKWY`hRpTa_)Jdis#}VOh%mwu`;rSV^yzq*83%FgjZ@kN`=6lxqZP1z9s~yp7|x
zd_n8gNH9CO1S%NNV7W#r5mrdlY+BUq=Gu>nSYnihl4%(6SaL+*z6U_*!Qrtv>pi7&
zgM+La;3u6w^~~qhC63A;hv}nhBej+MYIIGpo3Zz%_I-Y<AMgHy_?=uSLO?;OH0yxS
z%#g(MPIbpYg89ZWd6$G&%$8DW%LLGADs9Nb`5||AxDQ<P@8o{6&BVHhL&NM|OJ8|3
zlwsve?@UYA?!%X@%q^@mHFUP(VV=4$=N9mx5Y=)K=D;t(2s3BBjvN5~3U57}0u*##
zmx2x@QC#Y?&a}cpHHR*7;tc$+?&H2V`@Lnc=*_q8#;!Sa-<+bJ9RC}!3tEI4t!LC|
zSzM<cV<(UJoBev(a$RpLv2$imkBr9K)#4Ht{|4SX$L^W$@r<advn2v)r?q=hLV6p&
zzE9^Joqw$3fHz83DP~jGW41i*uP4_hZp7@=vHMJL*ZC~|`8@6V>|so?27JuqtdHym
zH~smpU8uWY4K)C*wVn%8s&wl6KFi$h+MRZfB4c_qjp=~)A^|04`1jf^>3skSAE(<K
ze*L5~X1SJA^+eNpZn6?bo8LF%24_$zQJzh3hCpy*SUIpv-n1i|IZ(N>Kc6hFrV4)E
z_kbc(!VRET2L;7}GY2*yC*;5e)%0PhC$?DY3$C$c4K0p|?C1Ih{3xz@!o51p@yhXj
zq5cOVK<g>p=VE9HHtM3!aG95%B&3l9C8Z^Xib4Pcf=7$yr2j3$l4C#6z()m#JAU8K
zs}aP99@+~-EggrHl4Pu<%4Y6*lr<C$=-rdfy<Hs59Y+F6;G+YU;0CG+yLGSvoSxmn
z=K0yB%o1}YkR*i?k!ILmdkBw1xNwVMM*)>JaI$5k`82moh?1p$PD49LZteUx?&f^a
za_lF)usE1;Z^clAtc+H_Q{ScL=1_BSQ$UL}-HOZ>stB)dthDG#Lri1MWQGVzslyUu
zQc{%&P#|hUCKJb?fCdyW$i(tw08=SwEK_xdskkqIfq6Fbm(RLLUT0>rLA!PWnASem
zt&U%rdP8n7K~O0$TkO#mN#=3C2mu(SRgTO#L<o7vg0i3Qga^k(27jN1#g3%GPCE;m
zrstkqg%5JM91JGfV{>z}fBZ-<4#5U}eXWG+PN;hP#SZErmvZeLra7ACs;q5B06J>L
zixm;RjdR>b>=XXqa(1cmT4a{o1{QaMv`l)l`)uE4;LagH=u#0t0l7e!v&6AI$iaQB
zw9)`f=)=RMX$T*X8}fjBpmAfX`;$hsr~6I*%N~0SvVrJH-WMnEqto1|eFIEgUmte$
z4Vn-fVUZwQeATU-=aK9GWz9gnrms;qKI$m|8m+xaNm+PtheK?jvR`1}78m_(t>lK;
zycmyjQ{S~Pl@lGmmS0#7eO)2F%#JS6s@!kjxmE1EX>Bh=P;yvza)s;XhBZ{4W1)oe
z%Yf1_2fARvur_4TLHktm1DkU_!zn2H?Gs{LsQnkKHxqs?Zu$9otWk3Ta9*#otJi86
zwg4A+ve!^2@n$<w`G#(0iOfa=XgoT0DT8H+*f%tAp=D`({@xcCCuYeN;C-<eQt>#q
zGFfR!<pI{)+HY81qFCwe0}kg~b3!p#5||I@il34wO0dp?^@>Rfl&u|gxrsTTvMW(R
zX#oBlf=djPhVnqA42E@|`eydSratN=o;Z{KJKZT=iqcsuN`*xvbtSH|YvGM!y)fwu
zi_yn4{}SxVn^wZeBI>^UX3qEc!)BlQQG{q^0vb)*a|{9tK+q}Cy+rJ6flDp0fB3lt
z`{$llX7Sp^AXeh~GkR##VyojPZcK5rgAHT!rxL0mIJlI_08+6DnE40gmtLWJBmk-z
za)_|RosujlcZpH+8BiLbojQ#<xnO<z8TE1Maa?ztaNB@+2PU1}$4qFw8MxW=*~D+8
z0d*A(fDz%YT&mH8zC^}HWe0VJd-iGvHr5>(zRFiQ+u-#%^4*`~KE02CfusNbh7-4D
z7O{4*q)A5Jq((>NvO7nE<z>pV6+zXcE)i@*W0@h`%E9IN0BEGaE_Q0nwlprG5JP~J
z1cc~AhhUCpzcPJbD~;P8tCn*=y(AM%E<L<gSxyzC)s*D5pI<x5FIe9h>ln;r(9aC!
z+_f`cB6`CyL9M!`y84?3DqD4e`hfoo9cgciS;*(O&#|w#!~Gh|<V+>coP@yWpwS}B
z)tQk~hjiZw`v#U%D$N!=Tx;bRyQw{zgKuh2Y8k98C=Dhm4Fy+^OHzovZl=sJgxsVg
zOla6zOnCM)4%}t`o%S)E%bn{cwWr~(t_2Af`+d9V_stDsN@Vxu-W)<>40iQ(J}*Hh
zFyZ&T;_Nq-M6P=gl!{nR4<7H32$oj;4)+%fWQy&-G;K~!P9B@SJ}?9fQUh&9ZM4YB
zD6+JUef+VG6Kx4L*^zoBO6yb#^r7?tGV>g%mNVe*0CRyA0TG2P<JPj;J}dh6KcuR*
z_qfj2_LB1fAJ&Dke{ZM^bZc43u|dd!(o$H>LXi}rRAY!q<vmxhV(<QA<A@%4=7X1d
z;GB-s`7nvnN7Vhbke@T{x(}-j^OQ`Dzjrr3-#Em-aXGfi$k@uVF-+;~x|LWUR3zx`
z#d^<kuP7U1y{=m-cQ->Iuhnvyt<!7^L|Aw%5x@WfJc}7P#a+Qum;$E(dxGZ{u0})v
zdnDkR0!^SK1q!6n06YhnfW9l*oY~BQea3=mmZ2dtga5G;m1^tK^d5N#z3mrv<B1lg
z4UsalvpzTu>VreCB$Ap#pa7$IVzp6P3855`5=3xG=?pVH6H3x>Xokf`<AJl@|M`V4
zF28^uBnMT5`%Jo~W9Z<t-haT*pjFfc=-yL7u*NP{TlT3NW|taXY>t6+u_TPN#@j{D
zEOY!l?Kc=GTKrcxoD9oZ<0VEV5OSS4Ogpw(SIk&wGrXM4WGI8ohAiWfK#jHWI+xdc
z9m6?72rjs?RW4SZWl1870DO(vl7gesIN<*^Q!OrO>$J<dY92V_b(wTFY70IX9K<Ng
zAg)M#{q0Hp@ukOhP%d{p{KFe#%&r?6f;fE4GuMMN-*sp05g9YIAw#{PTZ$ld65#cc
z)2HvS59~V@c|4}@v9)mTd;Ii&)r&eq7DKO*=2~h^?SAJv$l-;PqH2lgqez);c(|U#
zYfEO~+Ho!mks&irPy+<=ietS(kWkNA&2d#^X_3HLF$EHZ^MbAOB3{FP7aj9?gSV(#
zD6Sg+xxK0VgCqWek_w;;t)(xKJ?C9xGuL>p8*eT&*0F1nbnT=;1k=5Z91YI1|7hT&
zbN<&uJN}=7Z&)4}UKmeGyV8{NEXY8Dm*9sIwqf?6ceFl$qtPM@tQ52tkOD$HcR&ZY
zC7|OJ%b;zb#<F}V9K1u@FYX9PNSVyFoOZv!2VoQAu3gjtblDwuz%UQKR$eg^q5PL-
zEZmu1+MoL$ZU}?o)=2NinEakM{@UJJ9(}w(j2+Yk09{?Xc13`Y#Q=anf4`@`<#Jt-
zy3$Gz{MD8S$^cs-N)rLoThSZXKtGn_J%z!Ef$Tm62Bw~K_sb3k1+(XGF+)?5B#>gV
zu+{uAXAq$DF}r-0eA={Z5I1EdNpyxLWCLaqKwfDm4Zwt$mBcVYDG96-+g`Zj+S%vw
zquGx6e1hK^tZ^T|=j7M>H@LnNzY%+5&_rl86@+08oO{(^{Z3>zW*f_N=mVaP_n*Df
zute-jTIP$-0P<{zkcH-Flx;MT=#kmL)dMGj0#7uKfX>FO0W}!!^)GI_KP*#IC6}N)
z$7R7-rVPMAXUIng%W7#P$t9gsu#E=e0{+-uOS?K*1ai4md&=A%bGjQm+`5nfL9~(v
zP~gIvu*$N_<LjlbQ;AqAxtt{eL>?B&pT5Im_4lzqVc^!1@yowO$=VwX6*DthDL4iH
z!Ca2K{qxVs4~)D3%?mhT3A2F@PX^eu6R@yW0}Pb*L)|lo*-H}h6jSEhp~#X3d+s@Y
z;4Hm99CrB#*kh25e@pr6W}{!zt(@PjeL)P+n(Cx8*nPHHy$QWW(vl%d1kaBh@zc+-
zPq9yVKDQ^nCU5-5O1AFG@aQxRwX_Ov<?FRk*@DD<wCDTRZiLpBz>>b$dl<hHz{9}6
zRhDS%v$>@bMOwqA^(ZQHU|tDz`(hQ3!j*n}OzDMJa6>U|cw|s%hbCMh;>ujf!ZIL~
zJ_whE9R}0ZCr99U_<_bbj3P!Snv?&tJJrt{r@WAOK?Fd))yRjrnUA)G^F8{#2=g~m
zrmP^+nPqmLB!vKa0~vt9GXQ<14BXl)aAs%<me@ese#PfH#y8&ZWM*b=^Ee)7lUh6E
zg|~hFsb~-eSO12YjrM8N%BB1WN5Y_4C=I1u1!$!)ZwOKW4zgv%h0re=3F{8r)x0>m
zA8(YS@;VqpIIJGyU!UFTe)92RNwl8E=%n$g!n4f!CMj)KQzs3Fl)Krx;qB5TwU}j2
zv2R&0ooQ&T8X?bu+i)5v<*5X%Ji_r?$kCcGiK~~&UCC^U4>fZt)CiL3O>4{JekqGv
zUHf~>P|%WeVW2c-KUgL!90aH!E19_!5OsFkylM9uz<|AnM_ypf^$mP{ZIgire(msZ
zK5QKnV4{RG9v=BcuKI5Fx;2|BXSeCzCY^w#W!S&`zKcw^(g4E@0B&bwWC%8k^GIvp
zXT3=igrLN1u-9ONW9*l>;DjG8aNN)hO=biNa6NDc0E4?3j-^TauqI<m|NnUPrP>bO
zGmJ5uE)=<q_32IiaUyU0JvIOcqE!sZOH_;d+Q2&SV7GrdzSoc%FUk4S@pw&i1#_~)
zW5YfM2Ijjcxp%xa8pG&b5fs5ta9aaf-}6WE2c{j!+~9-&P@YZbfQ}QO100F#fWJ=J
zFH`hsQ%T>Z5Y$mZaph?&CVXgGm3>EH*=iuOz83)8Ksm^xP!=JQyON82a;v)DWDX89
z_vv1VskDq?9BUIcn%lbm?AHGJmDQ-rM4F`n0AZ~`I47T11W8f#u*%Z$I-_xQYqg<t
z($qARIxI6xLzr$CLxqOcGt|gzfCjK&nl8Oazr#MTuernjFZv!|08nP&S(I~!Q0Aev
zjmV(N_-w-DrE&X*I>cyE=vGdIl0$$Xvyz~$jE8QvjLcdgf|3{_<mFg`3eDNoJ(f)i
z=braZP+zbhy?5hGGVs>feQ^wz>u4kfuO})33aw!<hsC{L+BL^{xQ9MVc)hXEN-U9u
z(*}>%GXv#++x~`ux}AMnakIzXjz-Nn=e;0+c&-%8CZ+aR=O3H4@C&2VM|pO{k+@#v
zZPoy%ho?@OPy>9pg)nzlx(GN)P*)hpq3po9Ul7RUSmio_YU^<OV4FQ2s~)CuTYqc)
zpaHn1^mSQx-`>K<S2z7PtbttpqjqX0Kq<BB7ZN%!Zz8O+c(1uiZq-s`R$@d@uQEbI
z)XHp6LJO9_KBr}#YM>QBV`NXCvU_zq$6ouwg9rCj(ZCtKdzP3ze7M%=v1Ah_tDBGv
zKDbjCSFP8O!i`J_&&TXd=xbH<d}*T-zxBL7|2zKr@`Q`YtPN~{eXQQp=H~Rr7mxox
zv>d>!8m(XmN$m6(=1H#j1`oITn^^xdR+`$G7HR;6OlJ~>a$Ap(jHSDj5mT{gEK7m?
z&JW;{Kf0``iH>O!r=r%yATZuVRoJB(3b#H?#R}&v3<P-srhCsxpfErQ<6I!(iOa(P
znkI+byW;dQ3c|0TFPAL8-IRDV`-4XD#G+jB*~oEw5hO7M9+MDA$#%ZEfHivA;GdVW
z!H7it?dH(~+q7joZTitQ{sVV(ZW<p$GT^8$_#j)?<hp*eQyqp&H?#Zs{PeFA+F;>@
zdSI>xKxm;~#YAUd)#baYvDN4^LK0hp!HTATZe*Y&0pB>#G8!pOC<46Cvj)uIaZLex
z0#11D1nd!@12zGB3P1pJbpdM#T=r$dNPnZ+J1Q}nt*Z@K7R>b^?BR0T<u8F6O@%}i
znSxoYf+v_<W4r6Fhv7%=c-RGm)9Jig9`Nkwc>b|gUXtY-tg-X0=#ixmFiDd4OTjXV
zY^B6T5ZLgZ3y*=9*Y@J5Q|?|oY>PGQczSxdz^TEi3psK^P(RkM%~dS+p2wvxEdz@k
zz-SE96)MPhfrK!yF-c+d=ehjry`)ShJnkQ?;N@x%H1X2f;v&rbH1K(*&rkejn~039
zen(c>3kg6{iYVP<jAO`vkWOoeib<VNw%9*y(S5ULz$c%&nulm$0Pqp0AS<o%CPkur
z=Ve>no0&6nx|qxNU>!cHvUo4UGtDD=d!G;;|MK?I&<qj+3}B{{@l8P30^KXkyEVR@
zRQJ#JD}hNr1q#BvID4Lwt-H@hgM34taL-&2J{uqRjl)~U&RsKY`0L0C{1cmP*bvhB
z^)wPmuqs(y7@vUT>+S#s27qs{%ONBFT=MLiKCpGw^XDq@`7osb_=G`oXKYnHt9S2|
z-~3@MOpKFwh#Vlj$$ZeexDHlc{PZz4XX7TV*7qjZqBelJ8dXWE&l?;uS2Q9CyoFb^
z=bnolT1II1K#G+Hx6WqnKHGDYAbTM<(zyskmIH!~v`X<{9I=E;6w3(o5}&pj6t6&W
z4EwY9(l{leDvzon5dtX%2Lz;S4?5c`eXM~VM#v+R8?}GUJ8e6Y&*SUxy)rtf>_y1q
z$;!PihdpujV29B=Iz(IU)@zAQ<ADNcsf+3)oOy%YobT}iJDaKN7JF<@yI->y%Q2Al
zLQZF&{^C)wg>{Y%ROXHtIAU78?&N^fg*_<<%3g;^<HWk?HUxBLEn|&a4#L!gqfZ6P
z`|-yX;0U#IAu5%Xp}mM82!c{jX-6Q*WfJ6uSye_fFQz}^Oi|OLmuq+jVLw;S&5c$u
zv5Lb7`0}~9<3KPC?`-I0wT)ykXPbA}5N8`IrNr5y@cPUr+2YtZyN_L9E@{Z=Sd06U
z4Rv8p3X+nH-R!<oxR;<cn4Z$;zN8cL(qTXhMoVa)w)9f-X%v2<Ux!P)a*Q7x#VC(P
zeHQwdwFjeNF0=|4rJS3yhDT=~h466h+}#GPt2*WAd0hJHT}~lU5kMJ=9x<ws)J3O)
zT=`udWy8IeWX)Ew#V+Xp%4RHS&tRxZs=J24xjq!wFMX8^r;ivn3_{qeDf>AZH~UnM
z=RMhtK$xfuo!+3a)evEIzBdWsP|;U)HLUXYb~cz6Iv|jUg7&4qDhL7u%Yx$Hi$?oX
zi)ZOir){xgxmOQ*n5*p;8**>QrjL$2BMO#Ekw6(QG(=$#`lEt0z&RG&aGHz%LM%^4
zTvUJio3#e%p5#AoY3Y3v42-i>zcjp^&*RQi40cNe9FEUim{X6TUpRDd4T2Hg*8}zd
zM_2~k*fnq>Xj6j?NR$JxC0$UJ@LR#&3xbhgoCZE@RclM_0E_X+_xX4`X64hp*9jE+
zqc-8&%6F>HK9_8Db`cmRX1-gKllk@qe*bs-=%WTCzA#rgeEc3DDD-nlfF{p`)E@dt
zuJ*2}E6fttg37R;E?0^`tYDBzTEhY$0ZlCdBp?$S;7*Q)mSZ0^pxI5*RAdTfY4Y8k
zkcA^`<+vay7^3KTkN!M@HEj+@HytkMyn6OYwvW!tw@#b6+@-Mq?SX_81!F+~Nd|#k
z&2~;@7yn$+wzK!y%<ALx!^|;?AmPHR&eUoX)kB}a*u*P${n`?R7aD_v5Nf1$!<ut0
z{BG^B$jNFS^Tr0xSA&RQseXt1DF(I~!q?5_nPh=HT>%P_kQkgPXcMw@JpI@;%FN!b
z$6PS>(n!oGmT7F=)vum&Kpu^nQ8T)X#{o!^f&c>2ZmCt0C(f#R2|@mObnlcMALsT*
z$IQ-28WUfqPx|xCFKyd?=)bua(5H|fuqa%@@B17Jj~{c7*jY=dXyf|^G!TJ2C5i%4
zDea+1Uj}#2@fg@w&GaD6w6g5c=h%xLCs4w6Et7@&V8g>c!hxWmG+Q%PkOY*_O5Kk)
zA5*VwQ$Sfah4YdMPUy4TH!{DrsR5J5Dl}PXm(C!N<gy?Dm9cGgAKgVyzw7>N+8=vY
z0cEnZ2*b<O#p!!>jeY-=|Ex%}mI&Tx7$WeIaP1LRUHM&ec+M5c330vw1cG<R4#DF1
zd)i<5uvV*oI%&n4Y`20FfS}W3rBq#=@2%f6AN99>UA25SAIz2nG**vM?&J(DFOV{;
z`_+Bt(1exroh7fV>%bWq+ukj&puI9CoxzYKDO&Xy?L%@a@zKvXbOw#$alhenX_v{+
znlg;Mn9AO(3E%76JMXIiEK%AMbQsd&xh26o3;ojn??xglD`HDz5MvCQ2#6EOH3SJb
z0W_qEsYk}cGYrW=ihWkoX11^Vsb|qqk(utQQ*@0_%H_oUFqRFz-&xSlg4vJ*do*Kv
zZ3;qH9T!-lLwDb=4kbyIaDr2C-_=s71U@Op4v@um5~bPB8i7o(()t;vE_ilZ*RB1$
zzgN)CY-atp+@t=zz3$`fBmWz*=0|9WjNp+$5IQ1BlbEW@ZQ-i#4q9}5iN7hGz^KLM
zJo~M$VsK~Aah?WbWU3Mf@O)<Og`symSB1e<F{79S00!MD=m8PPd9VXt3(17oXYk1<
zpSqd@8_YIftzZ$i%V*qOK5X39;IIx~Iq+ybqyD$w;Jv=7bF$5r)Oe~#@W_y$H%?fi
z>eqM~|M$V0i-c5`<Pl2YwF26cA{mG;7Hf(1IlJ$If%*6G{F9@0{&dIauBc3npsB}m
zQbN4{>e2NhnT^RC-|rBpS|U1yjbp6U&^YMaL7Eo2A8dv`+s2{9Ne{rOdFsXpZx-}m
z7yw6#MhD2nt?-K+*|2n9fZ_4fn&U(3o~*gKl|SE|@&nOgU2RttuK;0C*Q>^~%tJrw
zum4f-#`SB!f7`TUC(>RU`Z`|atl%YLA9jcRMXuYr{G{tz$=Y49DKt)?*2N$qh~iSY
z_2%1qa4=y5hOc?eTVVjxiuQz)z)7G32atgo!3DCzUX+j(y;#WG2G<5bTH&X^1HzGb
zu8oKj8FXS>o0By|bx|Tm#>cW@^q>deRu;5|OD#WRZkis)wa+6#zhG~Us<L;7V%hS2
zc0Bi|zcw`&<6+J2Z)>?OdPEpZ#!1Y&H7m`(+-!><i}Ff{L#ZftJ>>9F0`M(X`ZVA)
za1&^NSIec56<>&3bbxpklvfDs91FN2V2^l|?=w&!E*R-?OSFKJiNO7qrEK7({TKuF
zhW5FEe)8$>{Ny(vIgYPL5fITFb1hwYy!CUFf}k)7LI6ezv$b9;b&S2V<dV&W<h6Q)
z5?*g<*X4_Qxm8x?mI4G3by*PwiQ1*3B29{3-rFNJDv1ZTWOMOV?T`Bwjy68x(O~V(
znXj{&uhU!jJdQONJ4WM`0fQ21GG59ZyAwJ|W1UoGdQ*t-Zi6U9^w3dQT3}z+z)1$)
z)Ia+t?{bUjO-Yg|iSC)c2MDqkhQ>zZHZnVL4eW>qdcZ!TsLh0HH6^o#=hhy-P(vb>
z5sozi*iga)K1jQCzPwdEwp;w%-~P07aLL!g!Z`|n!MXKqlV0;Rtdrw>R}s1{ytH_`
zN882)pL(!vTympTf?g7#LAk@A0jtaz1jTR`j|?iYKWpGE15Y^C$DWByi>g#%^`tDk
zJzrMN6<Hi*Ho0^9tR{b13(4>!_JmQdq{S!bYJzqYr4;xuU1V^a9bL;4ck6ZIb0JpG
z5r9C6j{mdqb#Y6NlgYnX08lJ>g&%d#d$9ZOw`8Yk2B#;qtu_&ww3-gQUhEkVh35+n
zVV?#QX1$gV6$7;^Lp3}=bYgO~D*KpG#{c|=r3Yv1Fu@*qJJ&JQu6fP)%fJyJ0@wm`
zKqv@i4GycrVkm)P>;lDwk`<_!auRnzgp;H18(BXcIc3_9E^trdGYP&y5C9zUWi7|B
z?eeYnHu+r2@&J%Zsj$Xt#n|imde<9A{7+g#0_x#mL(v;b#iUiPhIPhe-{g|7cba9b
zvGh)&L6b|P(d{gI8jl5QSWI05C@r6C37=nZ$gp4gDLXvga-P=<KKU=Dk*OS)Y9R4X
zY}d>o+j@IkwqkgKjM`m<*;Z>DqaH5#5#}dy8d-#G7Q5FW7kXB2YGIz;C5-E6mBZby
z1dz%0z)&GT&p&AVz#Zqq84qK-e~i2@l~Td6G;QkZ?4&=t8(LVgHqkv=)3-m*RbJ+=
z-fT&l$u!)3Duzy=!AZf~uy2Ebg^scLHGJrG_Y9SZi6WztSxVG}@cziLdCPDlyl&12
zb`%0;k4w08FN>vQ^FiC(t0qM*eHH|gPs-FBm>CF12lqm%xUGk2=Rwo9<eEjgWri;a
z{11w<jWgWj@y3Q<s(aCPa<Nqi!2*OqNvaQ4d8oX>SnUU}v{<m9pmS|78(KS-w8sSa
zOQ~fE?Bm)#E&2q0yw0tA%juR0C!_%H$<*0lKX-q7<&lFZn7ENQ_6wvi8|aXL)#JPd
zrEXkLAX<Yf>HODyB}6v`mP}pcJKHuA4A{D>J9jw0wPQ#r(O57l==MrF*jXC3&XP+y
z51K!cEilKZ&*Qc3cfQUymX5!NYq{2R3p~oh-}UQ&5GD^=sOuJ-bMZ$qnRO-ph&CHm
z7&dGd^i^iDJkqFGj<JEte$M~B*i+d!>?lKNvWCedtNDUb#MoKnR62yk<IHbqxud0E
zm_dRaA%OOz8-PRbTc80JKtphmU>wBr=u^{Lq#@x+&?~o)-agwCB@VoCpc!3NV?_f#
z9{BAvvOT00x6r)93j5DvwyM2q$dMsOgT}hF)c4<R`9lOOgNA4gyAhgtjB1b=x1yz6
zloeMTtTXPa8tsNE(7#ND9B2$+(38{v3?sGxdWH&18d9aj#01bv1N5|@X7Zv81xv)f
z?zw$FbJy3emTYT{D>g-8(ut^|2*$x`v*#XMSKZ$oGu3F7wSGTld(R_)_E9xCd*igy
z0u`%n=%p#ag~+ia#{!)`-PTH6rbq#kNC+f3DwQpg_$&<v&!E$nCY^;*R_qzfPf}_A
zdjER%v%_5tnmL!Z2L7*@-}tF7vz-g9xi@NfHBpOjgT}*$9_U{X3>4Vk{Vvb(-P5n-
z<8g9#$1_02Cu@{sO?uVU@A(*X1;xKCXlr!A?9arKQV?kr?WJ~g51Bp_h&;??)}YAG
zK7Hc$XH1?)$&I<zJA35A`S_@~qxt7%(>rc!9r3quahOM<1Qd4tEJ$fCGDl1-3mRdi
z`MXWFn6PBxcwXCTlp=vqD!}fo2;7F&kHrjoCm0<{%#_{dq2Mt4HT>AWk$eW=f__XX
z38bw4QXiUY4pT&ek*7+$-<T4gx>j%nl)yeSt&&!Hec3BS8la5B09r{aNK)#w@@i3%
z+9)6iK#(q4=VIDn=NMjiNAq)GZ&C$Dmm3lP_Vw4z4IFQ7_<wb1w2r9*{Hj!08Yd#F
z|CUQX|G2ri+0ZFI3K8vyj_~f@h-M`3@RDP{_fuSaTj^&Do2G#V2I$9-q%sN<WNn`#
zhv?ejckp&R)_TVcdmD{g8I<{PR@p5uup|N+uxKo%_J#$idw!;@zbxUh7hX-jDb%=<
z<*M3eds8{)w*vJ{kT({ud@G3t?HrfNioGm#V#mX_*tattW*>!C#3s45oLw=w4rbi7
z_QE0Gm$&$H`^szI?f>(LqgH_g##kCI9$)cb_kQr{yB^o%b)PaQ1*l+|YZpT;CrH2=
zSWJm{3>N4IfI)0k-C<YU_rX9gZa#Hh^^Z(k+i7Lna(U&L`jN~=Wqd@Sm)Tiw9H2~l
z2B;=y|FrJu3g%f97)uD33y0OG=~LZNS3|}o11144j@2;3cG0r!kNMH~)^1;NK#bXo
zJ6(6NtEFD2xBUD{;--qVRnR)FFrf8>f>l-**WDf7s0?L1U85ShsL|lSKJX6v+2^@i
zZ!G}HV@p!Nwbt6!17*{Zz}1#6z6k}rl$g3Pkp!NJU28FtfMVTqkspn?HyjtF&%KR(
z#wVY;x~mz@!04E);CRi#<~5w(+lF1zYb0+4y&2$lH&xpWZ4-XZPpQ4rUmI(fF0vLF
zY#mVH4k0EA)@gIjrQbB#JT}8Vg#j>VuZn+TOH*+6;`5dzHqg8uWS~?qZ8olUx{EN$
zgv4|yo25tfYwX6-{u?ZyOfPZlz{upaB}rnKY!%J)#^p<C`V90L;Ck!O7U?CxygZgp
zI)#j{zVV4|_Uin#iJb>cwat^TZ0_@z;Dx-`HP`8F|9SY_?E<^f8s9y;ysK3ZE!-nv
zf^)_PuGG~Hr#16E+UBH&MEGQ0r=+O?G-}Z~urFL>f4uRf#cc8VFYm7K<?FS86TmR=
z{JA{&@xAXyKaO|7hk%8)01v^yW-hp)N*d{aL`UKfc)dX!$LMh$PeRv<<H+CEE8Q%k
zIu?5<`n{J^^nx(CC-=;*dYbEU%Z|~Ke%#~IzPKt;6HyIE!bzA1yu=6aT>oib+bVQy
z<pY=)tJJC#cxmFznS44&|8YOD=}WkB&?sYJ9RWj~XCCjM*kZ~}xZ(%(M|`PjNH(|s
z<15c>napAqVVdo+MA$vewLnwjDy50uQ=Aky1ug>x0WhLc*)WVmKs|SA9eR3Rxa-((
z2)a`j*dP8B%lRo6QDy8I^4aqre(%9g=ZRYd_}J(06}~h@Dq1iXx+>w+k?0PO0Mv89
z<QbdrK=Pn&CA3<S0R>T8q*JU!Cw#V%dR?vs>ET#nXyuXtgAlyYUTsG4T>tus?8j}0
zmKBXL&K|<*=zeUor)wwr1)H{92*EmI#RSA;u|J1QND8N4)@uxlEuw33(_A`)I6PiT
zDvRWTIVpHd?-OC*gtEiWC-1$4EAEU35tV}3SMo`}<cI%KoCAL}<x++Dc&XA2Ab|q_
zhlh+x!i@>w>oCSc!b4dLQ(kj^@u|is)yfoXRVja^4mn?cC;iBb&5G9}JtJe>EVzMr
z$#{wX<z3=`9|{h`ONcJypldPZSUBO&dEa3{*%Dz4Gm4QC6Z|eosbT~%)GF)cYFm}t
zSewu-)*I`OYNkCsOb0Yzya~yMs$idE-}pXut1KruXJNcT5!rqG;#|&l_~fVfF&iKM
z9KOPrp%B}b&vHoTLiI}mhZ(O5ASgbJkpPKNfBpqRR9hw41@}ViKG&~m{BaBZS?QC0
zhovj9WYYb(R;Knz<u^@&2E~>|LS#e-+856HcfU3H6Q-glf-Qn7`|kZpVM_P<xtU{r
z4?f`xk%AelTp15xn8YSDu2)XC<fiPulpw5b#y`a@JYJJSBpX~c(6E1GVAT$XPs<Fx
zg?o%wGXLA}@k8?9XY%y#_>sICZ?Ogx;(SS!=zuhm5k`+V$BhX9PD3aR=MF?DaXSj#
zzb8$BJWUQ|NS@?X<6d|_<m+LlXef*`mry!f;f0@j?!?yr+Ur<DGw#~V=Z=+f@PY+l
z6mwNta?U*4_YPkEiR(=O>Jfclj4o##)Q~hNXINElPPdy7875W|hPDN>ER!}Yp^#=4
zV2cS{ojUR8xLBl8DQcFMVjsC+I{EWI|9%}0#MeHWeAxZPkL(STALqN^G3%L_B~XGg
zqE%!>tH_A@q=EucNdcLJRuLl7DF}&9;0SI=<bdl>2|(QjP)z0k_~`k9iVJZ#{5KUB
z$7WW-tFjiO`QhJwExE4+sXN6}bwMK<T;hYc;J>?X>Z6i<7&*+RUa)ZCDj&t&TkhFR
z?qknA%(q{2-=Bu-1;8QthKbKGDO|78tF3vIY;3wgiPR~z!gTSrc)QT;v@w}u18w_B
z2Hrl$)63`B`yTHfkDi_Va9%aoeYEql`<mbO!+!<fe~VI4M`qxN`c{>e0Z;@5L<Ka(
z40K{ijv&w-r8H)ZV*_jw_29n=F313k&+DFV{L2%n<iDw$smu2*gIEeI$B&MqG+;_7
zSwZAh9*zdj`>*bse)lpDUDKa=+kLd8i9xLT99vwQ;4^RYm%izG88F;Oj0O^#g_kwA
zV`VcUNfT0-MIW%4K0S@`s%)svEVFamr`T8C*~2umV~bhCc%wf53C}<Jalhve`4PPi
zsM{b`Gsw$RBw9ff(Ml+S|2aU%5LUc7W|h<(B|1`vB&@J(*R0vHbsm-op_(gki3*4E
zn^&B?O9M%iA$`&PpkB<SVy}17O23yUlu}ta-OoLL;>Uf-53YF^Tr}A?u?a|ilfhnj
zoL}@O?(P$i0p&6=T0+8=_e7U@n+avmY)T;77{jdHQ@lH4X?gaSKgG=Vy`fyd731LS
zonPTgo1fuR?>K-w%owGX)G85=w**}W9R>js9m&%HEgKeGv%%B$fH6LSMF1h}43NNq
z^fIFxLa6pXC=c<m{c8Jj_C^&66w8l(;pBqAu-sK2DmCN}v%;9uL1hRl#R@9RRjrHf
z_h;lAi8k!-R$TrI{$8>F|7PCsvX6N7zjaf43f>)GSD@CHZ4>C~e{SYfw)ptOaem6s
zrr?fchAGEG387F7Pc_F*v~@dcS|-nIro*hV3Qhyh48_@KG_x{F2I7R`|G=T_J`)Dc
zEyqucS5-ga3x6CR{|Fy`!wVgBl@ic+n&tyt=WzpYHLwI$6`sEKK)Ob-OLUNYUoSv<
z8hF~*`MM22N7d9Npd$gK4p_PvLyVlDj`HKbzgz~0zahUJ;|UaT5=)quar!$S!a$ry
zQ+T38Ww^A`53Fl&hVbY8Gb2O~xbz#|^ed6OQU}$7G=6D{w=i<1JZ-(LSAOnLLRgdo
zf+giLacD3C;cKWbIQOIDtGw@<8!L9I(OQYn=GzwW;MnbS3hX=o-Nyt)(ogh5@Y?55
z+{bS4uRnjG&IVX`u3g&^*LHyCDv$yV@HEhQfYgyZUFxXX0NsX;5>UNk106sLb%_oV
z;Wbx;pZ^fI40!RF^UgW;k9Ys^-8-|bwy}6zZr20DJPcPwn9De9or(YW;ef4kRU{t9
z?cOib?l{L^|5nGN5jwTvm-b~_8Wn@#u=KvZr0>XIkE!7EC~J8MacG29MyTl{o>HH%
z^2)DNsK?Y;E|uE~)6)$GOgazl8Cs*u2AcMt4BTF@{0A878AQ%s)ld7WfAAH))Xu;7
z>|D~|mLON!0*9Wi#JZC7SsuFtR|&3xH$k=l1iG?T&UTkNh$G}Q(g4b+usC%Mr{$8H
zc^Y5|41jF{v<tzT5@g^_K;lhu#35?tOwZm^l48cahnGR&<Wej@KS}yND<in#`ODw_
zM&{RF3w<_MKly)A`LxyH<=^!76t7%;l*F4n5Kn31Twb33kKEUht{-APQPNaR7#W%H
zkSTwVs4&5h5)X?o3LZN={k-1z*tD{AmQnz;awwq5QM|1eLHnON*ZaUebdjgChGESx
z3^ll0vSrR25nQBfiuy<dCjz5BtinyaSD_zh8GsfTAPQ)PSDV6ciffloN1_B2zqD|V
zat54o85n>y&;U<TH=_8rTI>VLuh*sH1;41@K~g&ktl795iR3TL^)<YaYTi8E*8kG+
z8<{_e__LDtFZ?Mc!0eH4ZlsY8#J931gS6vg!mSRs5{*V<V`FSg-}*d%?}3;2-^dJn
zBE&=t#R3?*d#^smd7ijhHTdHAQdLL|Eg>AFf)o!$P$Eok!&RW4x`B2q*%NCC3UIFX
zCHAAgSxetQrhblhzmvOn<=(r_UMyzRna&PKjC1HKK_kN{P|i4QfF<Mxl7LE;4j_sG
zN>GMbBar!4Fu+pzP!Hnfwrev7(gkz=2S`iD7eiMU=a#zf5+7=~G4L~aWwBDI@4maB
zBQsv4-qmlo<$9S>*n@anu%!@(gq=?Hs~h7BJ+byOQN`P)5QZ9oV2R+-kJvRfbJ&-{
z?l{MwmU4xwxB@O+x^$@mJecLKpf8@OWT|#k>u@Xy=*BYYTa#gUM+4wyoDM)EFl5HR
zKqUeLu$;pjDu5HV!ST{n6?0_)g^3&HOib_%fQJs4gN>*GBiDNE-33~o4qfbj&Yk)%
zSK12)m_HwSdwY9(IQmSVe&pA<`13ol;cY90&f%G5&agji;FE&+#`~$;02yM|7%@ne
zysp&L8cj5$N*$1DbwC2d(;y5qf&#;kVGWQGR6uiu1Za+e3LRj82x|lL0Mr|5Mk|;D
zc)0iiD&Qh{SdV~u0sioUu~Of#p)Ltl33H5{{EvL<a?juZarwIlLKm5LnqPic)xXjl
z&3in{GSiwsOvh-_UTa$V<6?7lhkbFM3Ii7xOrQQX23MF`neb(DHV3c1`l@RJ2FeKN
z^P*S^5Z(xI3N%0pI1IQ7eE*EDS+HOoh>+E@Mc6U`W*xA?Uy>LdX!NZ*0QQzLygKq3
zkWnCd24D*anRS9=p!_W$o~*Y3g#hL6kAVcz{Q4Nm24qi9h8y6zK)T=c<NgqM3vArD
zaU)5yxe{o5(c1o*xV$cT(m%M?FoV1KjiDjco=?=3$fCt(UN9Knt2b9^LK77tN0bDx
zMVNJm5QFU+r~m^%$ZgZSEpRQ+)G8YoZGnUnKyi}iGO*$naI?~5zyS0W2EH8R#|o#2
zed`b5o9O#9$R)<8ya*ud(U?6GSLGIP?-nRvkqE3AcV^tR0!AI<yTrwsvBSLMp(hE@
znDX&G6F+`zYC6vL5AL|^+h~7|j%RR+h{cwwv>Wvsj&b2Ncblrj^~egLCAwfN5j@^$
zc2d-gjtx}yufB(3FHLSxy;N@wwu7mWoM>TK0g0d)Dy(f$sRI+VfSF(>%o%ThIq<ts
zoWr>40$4wkMuUQ(MawOfS;ls6)IP#rdsFrS(I7mOfq_-4=<DHx$_KmT^!IljbB{`x
zR_c7S8(y!XTChayV;9V`3~n(og<<ck7kh*jNI*;F9vFO!btPc6WY$i9r*!R>!wPSG
z7y54tXZ;s2C%$+L5q*91?EOkqOW;cHae=j0tiEUKVs&E-oxy^sz<%~OYfpcYWwT}&
z8K!Oxi>ve%R={#>O&w?;Gt~{u$81?oFw8#_jYgvZnbF!`)bfw5?300QudXNi1E0I{
z^bH5pSiuB6oNLYvI#_ANZ85M^XMsurE0G+nTOt_VBw(3rAXn+9%n8yI8HE4A4v*P=
zE$-vfoPxtoFOr$RL&KCWPg-WLlhLtyUg~{~lmDfaNdpJ;_2|+2Em7Rqfrr@0MW5Y~
z*>=2@wA4AB!MwA{x!vd3-!|~ceeA+J4e|y-WUusG-5V8KpaldNCNYB>jfS_FxrKW&
zcFI5YvC9F*)C2=PRtYRu$!KFi+bV19<_xpnwg=YgyDAa0k*Bo?Fig)tX$o{i$niO&
zoZGJY9qx1SJ?!vYvU_1Rb2V4oxg&dI;zK{S)c9%-{n*-O)&ObCOI?w=zQU*dy{Eo-
zL(XiC9=-TVTMSpZ*wgzr*rk-tG<Gv93EYZ^v=W$(C6ZC5H^<&;3zIpp@BKSFw{PCx
z*%O<yd&(VG(Mm&L0Gt?04_6n!ngy^PLj$a#AAkkW28IC1=M=yoz~JlGfkj{d60B&U
zg6$d@0P`e}-?CRvUOUe8SMGYD|BAMam1d!*Dq%EXRc3a&-d@f)>vC<rn&@IntfGl@
z85JBb9S8wSWRi-&RnJwRpMnIefF&zW22v%hq}U1c`hcay2AcQ3FtF==`}}>gi5pJb
zjOp*MG7FOvc-z4<`Sq43so&8XcnT3i&-^Fu8r*lrTj;4U#w?N00*lY^z$1}wNz(5<
z=NbYbeF#`0c(0y4^V{gpOqRfY_}_Ae!zLY_I`4w@m|DOIpa<502519qASXxwt!J3n
z6Sbs?jiWbt?tk^tS^go~z@&Gh$AW2uT>c#{yzZK8J|oo_GoRGyWZ>0Qh@L(FPCc`<
z0{i0z4*n3nSyE(bxrFGRn1L%;0VYV$K;NwA2P{m~$;usDp5pg@YWw2K4)jz)B}>@7
z=Y!qznapPs9=_Y8pN=;h1oW)?B>f*4T6&)h18eSMH_W8HSBhOjVW)M5sagOn3@ac3
z!`M=#3?!h1VFk+`2FBh1^Cv*9R;zVYsVI$~$<%w{Qg2w#{AXLA@bGX~T{laLp+sTB
zo)5R4t9|I|dg`^20}DrbOQaP&3B@*CrT1K&kP}mqJp&ZQi>ah~pNk{*&A&kdyL~AC
zx5tO@%}b@X`<1La)Y+5$z#eS}SS^|LUw-~_d_AR`>BbIaIy`WOzk0*P?{J{p)vRsy
z$`LbfytCqh%L%4N4NprC2Jv=-C@y&WWAfKCP~1NQ1Me6(g!8_;;LrG-8t7x7>mIAv
z!_e0m(n#wW5|Bn(NYJz}w6GXvTK+NcSK!i81yof#*$7A{Jk8l#;R=tbC;BZ9{O{<Q
zLxfZk_FQFo{tea+uDf-qLS+06LVJj&v%9;jz2WW-hZOtl2JYk{*W8ag`unQZr<Ksn
zMq~Q3QobU%O>F&7pLmh~4H@q3X$%ozSVcVV20d0;_H9+)ViKwA3~T#Zmd1F!@}xl=
zH8#+;-`3?d@JX;=MS`yR9qkXgc(Jc?bKhv+efMoN(3U3&Ypwkq#cRt)^eaF1#eeah
zV0d_V2!bF}5QbqWfqFRYFFS6s+)(ln#nPz1zaRDhPAc63PAV)s#Vr6|9<V2H>~Xb#
zJrX$elqRf!-gCvH6bY!Oyh7kXU=1vQfnEWF{QEd)8eWehHtTBHP*;k-<IjHNH*vB5
zpE%v$L?}$#jp1R8L8deihP{ylz2{}#<Z>@PuJ=>juOXhL2n3H86w8$1z^Q>6bFIRr
z)*Fbb7IDWrmcc0#&88>*wg0E>iis=d!0<Z4Ff$l~Kq7iUf(<Y8|K9wI5;3qtDUcz+
zYyc<o1d;#zIqn+{o?zgd2~|?ZD4@F=wtolPd@OaUKYgwPTp9LM_&FKD7=sByKMWV2
zZc%qaub%MOR%3})ltXB=nY1}7;;>jS*<l|zh#IB|2OF|di`##HGm2eG>(ibIAGho2
ze(#rF>;t%Rj#^tAi!Ibv838aRu%S0#r;BZPP#0S=jZ{G5-?rv$<Fm(xw8ji$X@E4Q
z!P8GnM)*@kyV*JJ%m20mDF$8%nN<X>BvKsEaB|#{%dH(x`kU{YB!o)6S|E^WGC^t|
zd!G8vr`O-*lA*2=EyXU;fR9J3j68zTicW!psT1=soXu(N!VS_L_2Wd2T0U;-1^@k#
z3;Z8AkdYt=z!;MO1fqpOvG*z;a*;JR8)Q*v<Zsrmjqy!KNqY_j^z6L`l{ldK3AgYv
za_e%rJEf2E18nzZBX~0Pgum)jJAf9!0Ud@ILq`{g)}}OhkeO$lbz3IWQd4PxP&fRv
zfWf0RF;aBl;>6DBgDQOf8J5+-4z%12`4l20f-^PaF>&$#*KyXriT_=`l>kCA;sT9?
zpZ@~ux!kKy){hHL-^`L>^M2!#+5>!_6IlbDX9Faf8K8_l6CW+M<T$t*rb<l~YIj67
zzV`HM=&63|r`kc_Ob9_{K;tS+!itMNYu2f;6Bg<#`VBrFE(%c}`CZ$!;sF)|7lMSU
zFpZ!MEvlpo7gjdBcCG_Y@T+h8;w2D(Kr(@5mJ4T`n_q7vP0~<me#z##7%>LWm=2I;
zfPg-uCQw^N9As_X2dUW}%XIG63yXn;3+G!zV5|L}JL_M)<3;`}Bxn@8Nr7OD=}^X$
z^y13Q^E`E}&Zq1wZ72#QmWoe$-Tr3hBX%t|P&v@@8BNHe!fcLZvUH_|tXfs5TuyEu
z1QlCxEjK%!^f!EF<~$Tui9}j!-J!U-R*oyggctSyx7IC^WY)06|Mph!cR(RR6$N?#
z4LAdkW|VjoSYnER!jqD9hkeAs)?gn8LFTnq4h@Q}lou}aZQVTbz(xLB>Ef?4b0-_I
zQFMH*t-x*<d4r3;a*|BzGBDpxWDnb2gtv>{{S3RMzyVhSHMVWA;g!=;ql-!f?r7Dp
zQ}ML&&gIvJ)7|yOHcd6%VGxELCj<hmHG4kr-8UxMq8rRdTCfZYy?{!=!-P(-w4`88
zA9TS$#2~M}Yl>`8Ms>g2=9TDh&ttaZ)2(t&!kjRKu%mSN07a?P8Rz{?wZ^uwJ>mJr
zYDg3T<w`~y`pE$OU)gNQaq!h3VQDn(c*lJmUguYTb)V>N`#LF+G>7(v|Nr{N!b&SI
zuQ^6D5Qb1n-<~=kf-z9v8IEqX_FS{%LFc^PjB6<dQ-;dsGwH9Of!nl_YLy^xGw`Zs
z!55;ulBc+(fU5<p61W_=K8*By|2%>dz!w5mEGd^*0R|yGZ#P%J!vip1Wl(p1;X?He
zyaEa~8kCTY8{JrSRX9G@&phWI5+DrdsK!KCsL`!yc$mkFi9Q|6(_}RfX>);J!1E1a
znVe%6I0zfG4F9l_g%sJ4v{WjQsN4s6(Wm#WupJlZm<bSFq=%3c&9393*DN^q;*Zwu
zHJq&duRhhw_AwQ2Q@OjtKK`B##2EM_bCr3oP^px=D%=o3Ie9zTTt35`-Fe+%hwy6+
z0v!{*(@XsCt4%gFW@s%@TQ~9>SgPm@T9y<CV_P2Qkzh-;MN}xV(HUFiiRx)y;<cx%
ztj%|F0ECjhy{*h82%%R(_fD7F$~Cq{Dp^QW;U+RxKeZ8v?nuk2JN7)_X)73<=YXt%
znhDo_5T;Zvrm*k2`-c)~bLACZeDpi@(qT)809EK1ysTTUt=|b<Po(QNxjlMF8~hG4
z6XTifk`&C@gEAN>Z`p@cw$8$G=OXkyTe$EiUZ*#;@@hLTX;A7IOLLj<LW^J|bg#OW
zH8vkQt>=^}3<zY3Hp7wcEv={Voqc-26mf7ilQJmV3K2ne-(3pf&*!=7yYWhkKD=QE
zTcM+_wMN1XE6y?Ri|W>?`l7J2h7SUXFg~9B%%jglhgn+HK=A<0S7|O=@dhTws#Vl|
z3g4-B-6){*3nGTXV=Kf~+IR{7|H*pL44VK7K!Oh2)yg2RjVEY~ysTS})*6|rkGg80
zl{AY1e<2-ZO~+=c2B5FBf=B-%-}&<&`+qM!_J5ZY2WeZ`4}w;;6|4dgx~>$;mdS!d
z>04rQ#kYo6+DaAlxsY_a13KW~?V61%y}=_tbHBN<C4;n-cG`}9gc$~OhnR`|z;lIj
zi37Et(YMfiC0$hsRQkStQH3Ph@;$So8{O9y+ETjuptoOL2f|QNI(UK4W^L#V+SQV<
z`{!6?<*kNFYfHi*ON&ZGdV}_qm1oI&e}Mm!rTXN8eK=Ud=WiRT%N6vC`l7TDT08D-
z@y)$55yPZUJ;n$5Bm9;p8K{y#P%T<y4DGxNAN%reap_l&s|Kc;WBG2!68&*}?C5l!
zE&M|a%5c!uV8R<Vd{JLiy}oRjw<x%~Wo*5*!b{T$i<`ZDnqR#&@3F}nV@jp=)s<jE
z$*7Fe{Q63h%r}{lR7PUyDIgF);5typ255jZB?CRM1XjQg@Lsi$n5p5w&4)Fus~YGX
zDO|5(fJ%?6>3W^?^oz$c>C?ir*0l3(Y{nTMEZ5jkx%qO!ZN*9a^eo>0ZQ4zNgSR%X
z!Zbt|7P{jd0nD(aV<ArEv*(!q!6z>PLGZmlGwph{WEZRpE6)2!CC!PQNp+tYV2Kdz
zd3RhIODh{_I)L*98mPcK&^s0agFrOH!<BezR;6<<{r|ptl5Qjv+g0~yiO9eHO!p0%
z<J2vy@<bq144_lA@hXZfcD4^3#I<e1!Sc1%&h@T0<SSOKTD7WNZZsMVK;GJ(o1W)i
zoqC@CiV)nc!A`d%6%cp{PjZ#__@(^tU-^Xd!QFGGaGaSGM!SbWj>$kVlfB}Gz)L_0
zD%o}cs{~4tr)5je01N>GHMr`h%{;jVYC@L*36v>p5I|jCXU6l|uPc9U`v`y4XD+$X
z4pySNQy~bct4~HJGrg;<cy!)dU-I}Ag!x`;keE_yTNTWk!>1Ees!OJTa@jigJV2-;
z;%wMum{Dflz1DYKu<f(Lv;U3OCk)1sv8Ou`69f`QB{L0h;pe#cvpeT+mv+zSRI@>x
z$THVD8$yJ6bz9a!YUriweICG@(K&&Q5^WI`Ee{>-71MX-8UDoQF8=~o9`5aBr@6J|
zcDvh$5}xEt_kNrR?OnIN_ya5rBEo!6#)3B0LCbsQ+4(B7$6?jGzuux!DsR>aJwSJB
zd<y2YoGRw9rgOow{8@ZM4&1_E)Q5+MuXv@hF*g2B`c76}K3HQ%kxW<q-e2m4n48$=
zKnCKR80dik7-B4JCG0$4-rbDOQv)^L{TPK+0mjGoJz(RGkEv7rsn2Zl7OpIHcA9q(
zs)TugER}L?<81Rk96Nb^LYe#?j+>@o-pec5R#gT*o`=W4C+#1e<wcK`yCg~pU15V7
zk_xL=%d5=~9y*@rH-Bp?xSa#TN%@LrrrqW_MKIx0oZ-HKo3E`iHjcHXiW_z>L`GX8
z8HjVp1jb?yQzvj4W?tTokGzWb$5pMr*FKLjsH)OAY3iyyvest46Fl!ff98V!9=E&l
zmDwp8nmc9nK&_$Tim!8?N4{)nJ)<(E#9X!~xGTkxxxV76VVer(=`~Q}ALn6zZzz<Z
z(P*FxRadO21ef?jO+5NcMxN$(e&T;OJrIL1MCB_&2m~0z7t~TvopRb=zA2KHGL?*>
zQZc7+S0KY<M0$!EFwBXDH9Z4hiiPE|FlDWAlRIw@KQQyyyt)MaJhViYNu^ftSFj;C
zMlSk4O3(BsS0)?7^md+At?NXOCwRCuTz6-1ON}lYnDcR1_|1l#Mwr*v#)T`kB2h1~
za^=cW2`ZI6pwx)a^3!J?ww(IUf9<8;L7Bd>u`%tPML`;^Zx?TH-4RZ6`v-2i`ikH7
zXR`1O+1I1}0QA5xPgqzoF+$C&-^)BdUuEd({2e9TuSA_9OP_e2)NgBMN1pMI&+Q1>
zK_9BBy|boOX-G)GY7aeHw}>Z}fzuaa=7T|W1bXIlZBdXWm3e=|bs9DbwYP{coPrxR
zM3#w&K%=qIjrgzUoSWH>Gyk=3T=f6rS9?3I=yl_HO*2`q!}WTcW$_ou#!I6owHwM_
zPNIiQMf5~H^LH5ONj#zIQ=JFsGx}K=qdw@2v_aR6M&so^@n|wX*(d(ZpCbY?>kI~z
zD}^4@pN7>f&NTNyOLL_zN(;V+p-5<%>)9d<l`N;J%nNKK5ksg}Ut>eVfa1seI2~=}
zox0SAmDBwlIM6q8kU>b_EWsE`eYVh2VI^Gt_3EM<ZZ<bgHx(-B%GDV721MtZymiRD
zka>a))P$Y~fgSd!7pMD?xn(AO;<oAcj+6a?|HtK?A%`$%BFthf2+eOY`N`kM2II7M
z{MRQ@Jvd!II(FUl8RMhOSZA_?IzvAu5ng<62EK`avS8jIeqf=hstk=+s!6?GuY(AH
zVwITsw$q-T9iDYP$KSw}J(&Jh%|z)N9-bBXyo5-IDLuJpaGrHM+V-~8W>aV21h1rA
zz@I_v2Qu#k?s<l(E3v@S0XN`(I`E~35#^BRv8#Of52?Q&#ZGXTl?#|xc*5~C2vrFX
zuP{`h=tdN5c<W!`DgWr7xybu)<;fqPX)wz}igtr1d62t5uDAIw0E`dx%xkqk_1pZ%
z_l2!&;Hi0rzRC<`h1r=sDip7($y?9d15ft{&b*Zj56_xBHiQ*D?^Ji}G+WKi8v-c+
z80Plb^ZEwM**ib~%&-LJ9S&86ZK=IYtyZg1@2a+<!YjLD!&(2{Z7=*^(GDD7mIvMQ
zuC{~oK5?Ty*%TTq0D<7;QT6bOMnfwx53zxoP)#J*f!*RKeBglxQZH0NN*mo6IcIX`
zh7af0e&j12o^?O}Z#na&{rYZwx}Ma;P=?3{1>&5@p6JVo=eswE#o-_k27=6<RcH26
zn9{93avSINNg<XY^^G}+@ZA$vxc8mvui$pGEMfeX-}gmd<;w5(n>j^=NJFFzb33<Y
zFp;~4CBwnu%>8~ib3GGYuY{TV%{IqYsCE*Bw3K;JKHqJh^_={V{eLd=Cd%b9^!Dc4
zkj<yWm4B)cPCx6Dq(&mB-Ek9JDMOjU{A&M{hCxYXsL2iw4F`-qZ2m>4a#!%WD_-gL
zs&pxkPbECGO+RT@2P4n<cVB7)w;LWB8luhFJkagHimUVM?kHcqP-g(5GQwew_n*Df
zqrzR_pz)5+$Kj3)<<nu6Kohi+vT$LA-?xd^_OXQ=g{SzV-+1wNkO2-b)K^?;_dm5Z
zthV~|s^(Ht&BEa&TiLEgY}B*Nw?#2{2B4p51_88Ei__ZY&asOPR1O?{f$pNvH?s#t
zDo|0korTxRzjV!0|DmO~dUw#PI^RkbvUw!v)6Ke5U)Gw+aFh9!NFaJkEJH^=^ID5G
z%jb$M5eJWho(2Y~RRyE~s;ZTW?4H|w=lOg0obNxP^?)-5i~}WY7RV#8XbD%`!3Cdq
zm|#`9UNB;b-kbtu$|jmyXP>`vsRa%of5I)<558=J*nM}Qn;ZW3evLixZ~nv=f4c#Z
zbgk-q_v!Aut-{)<fm8MEOcQBMnKB;U|COy%@`D^i;?v3GwA#md?bqH=DkLJZV8Qsf
z+0nFT+V*?uN&a*T`W#|TntYlWtT)aDH`%Mboi(K^b#1GMd>DyF5J6#p259Gk1YV#A
z<=h@~98Au1p4y~QqT6;^Q}3Cx{=FYuVq-_})mLfrqJ){Zf9hNRqrU&#jfPVU9xe)Q
zR<?QV3&*P2v3Nk~tITkE{>Qji(v5m_d4J50FS2r}4^>Y3$Ie`N0&vu9q7;G86B1-4
z$`#JN0=x12bG_^w0%L|1VtlW9D~M7S@e^Ly2M#J{`!XCb_hs8U-5?zJGy-|AGvl5(
z>)(CsLLbCba9vXK5J(_zp|AftR$TDucwd!$(XbLB@*^LQcT29P_<K6AWZ;ub=M_<l
z+)unxsu={JK%D@`NC}qWcH}nfIWX-V<z&D2fp_@JuOWnhv=Uf+n%lpU{Y$Dj?S_2Q
zVkKhO^b16arwl%%K(ohAYn=wHA#e(0;M=2D;W^tSaBw+D6*1Vw2AbDtQ0#ax!tEfs
z2NNE8ekL#RAD?>B_oW{C+qJO}1OQ<WN{GW1wsEO92K9ARUrwr9s#pOKh$hu%4(r*S
zAHb|~b%6uSpRnB$coA7d@xGB&V%#clm(#HktiEUZW1oAJpYl`7H3<L&-oh(<AmN72
zscyg7q|4uSO}|KN1$+d8H^<yy+MN|`hJUn~l9EgxWa0;w-LqZ}+hf$(Knm0okov1<
zt&}`Uds3JBf29}v7p(`nHrOO(kx5`J(t5biy8O{T7}fbw0@qySuhI#Em&Z)gVuq7q
zQ^djM);<oq_9IS~ul244>X3-msg)1FC;CBz=frvb)<bLjj(razs$z6A41--3nJ|3N
zdp?+8tFJ%l!p(ApR(ymy?;(;u`&$A01OxlK^Y1rMJmB<IX7;i=Qn6@btpPNsAqoh-
zt>3a)g_rriN6xWe@04F!scMD+7;RH)K%IGcv0l+khP3DN#uAU$4?no0`dy#%>l6o_
z&31u1x~om3`Ir43H`1t30!Zo`4!+Ar9$5*d=X{Ucy4)+=-S4q@0Db!e>bgB1V&OaW
zvhhPq8?M-{Jdgb3Id<{4b>QhU3R0c(w&6N7D)TYIe1LjcliO-UDn7V=#yQts*590V
zBBKK~PT&65cxktOp&AQ+Yr>SN;Q2!z4NbwE;^1?J<A}pf@f7V}d2Ek`1|UWOLOmHS
z536`vjg7|THXmPT6Zd#35*oW%ZL{VYSK7>_-w2c1Ohk7x|IdgFN*uGjt6BFvZ!_mP
z0R0J1*!z*TV-k2WwS^c2N*y4nmm#uf31KpudXT%`Is1SAV*Qd>R-5c7FXex3wJ_&m
z|Jdq00Uytof+;!IUG^XpKd_K_$GrMCEWG_2XbH-lU|3k$*dEK6tkZ6-yowWEMm(_R
znHQGpj+OC7IAOFucA);g00nPr7x|=MA2=AD*=0CCS)^Q7sel#|O0}vG#Ik0rZ{uup
zJ~`)YZ|pT?t#KY=)#V$MwU)9N)k>4K9Z~M_`c<18lnpc;kop2MclT;EvS?$8;_Vf2
zGa<UZ2wRf57yqB%z388vJ>7g?AEvAFR{2e8M!anWR`84+frHW$9uLB~ndIdsYi<!*
zpi!XKpkJE9mGmm_4p&{nqr9|hHD>C2<@R&}TQmDhnJgs^On<_eJulDCIJ{g?MfOk<
zC}9KNw{)z;ekEs~dt1_IF3EKU+Qr#7_0Kyv#piD#i!GsjV}&fLdx`mycmOLa2VjP6
z6_vCm_99yYZHXss<XuYCsJ6~<kUD%M)w?b?bv|+G#$pd)*aB6I6{(;?fQhA1Prr@A
zprN2MUP-Fd0u8W$$Qj?jH}$dq|5E+Bo?nUws=mtXK8`Y&8-_pePoDZfUFcGyVT4X#
z%wm}%4pvXN9;bTQ@=x5=@XGiai%f(8QWt2DzJTXvqb!iJm$8A$0jtj_$m+a7ui6N8
zETT^LwWrBH<OAQpJJ0Pg;-Ixb2OhQB5}L0@>bFg70Mv@oXfL~K80EA3_H}^+*PpN@
zM0{<qp9dt&ZZ_-we^7KzAH2dq#2`cdtmV}Q1PO*glG%u}7cs3l4q^u>!_GzIT{mk0
zNqsgT3uh|O+ARvF>UVe`>#Gb^*G5ezvETeM)Byu%FO&aMd|p#Vi`lvD0td6-pT`y&
zXkIDR8q6NXPCuhbcYB9R-_`-GPuOk=8@X~iH)aR^%K!ZMhQ;%|!J(?1(j3(Ou$f)G
z8Y#=IG$=7Us8Rn?_xk+TENtg;aQpKQF4NH~EK&yMHwxtnlq*04_+BIYrA%he{GrTh
zVyGu_klR3N_~Ini*c6!2HoUSFB3Hn(O(ACm3uEJ`iFG-VgWaD_%e8;rSk5_R%^h8z
ze4~&jw}S`xjoLXj_*@Qpf0eC$mTGpAmv?{Bhgw)4qF5n%Di7khGDxi8j<F?nOE6I3
zAov8HcIePF@CuU+rn$YWjn08H<c`Ay?id?&umR-;b|YyRq&k9fiz{PZ@kw)|g^8JL
z9R^2q2X`=T{~7|?DP9+r<Tsni>8pXN3#L;3n`2(`ukx$>*eB_1FbEne38>;RpL|Bl
GZ3O@>GoEMw

literal 0
HcmV?d00001

diff --git a/studio/frontend/public/hub/profile/logo/xai.svg b/studio/frontend/public/hub/profile/logo/xai.svg
new file mode 100644
index 0000000000..0c83eb3d9b
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/xai.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 466.04 516.93"><polygon points="0.12 182.71 234.14 516.92 338.15 516.92 104.13 182.71 0.12 182.71"/><polygon points="0 516.92 104.08 516.92 156.08 442.67 104.04 368.34 0 516.92"/><polygon points="466.04 0 361.96 0 182.1 256.86 234.15 331.18 466.04 0"/><polygon points="380.78 516.92 466.04 516.92 466.04 37.16 380.78 158.92 380.78 516.92"/></svg>
\ No newline at end of file
diff --git a/studio/frontend/public/hub/profile/logo/zai.svg b/studio/frontend/public/hub/profile/logo/zai.svg
new file mode 100644
index 0000000000..28ca7280a1
--- /dev/null
+++ b/studio/frontend/public/hub/profile/logo/zai.svg
@@ -0,0 +1,215 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" x="0px" y="0px" viewBox="0.0 0.0 30.0 30.0" style="enable-background:new 0 0 30 30;" xml:space="preserve" width="316.22776601683796" height="316.22776601683796">
+<style type="text/css">
+	.st0{opacity:0.3;fill:#E2E4E7;}
+	.st1{opacity:0.8;fill:#E2E4E7;stroke:#FFFFFF;stroke-width:5;stroke-miterlimit:10;}
+	.st2{fill:url(#SVGID_1_);}
+	.st3{fill:none;stroke:#E0E4E9;stroke-width:0.25;stroke-miterlimit:10;}
+	.st4{fill:none;}
+	.st5{fill:#9DA1A5;}
+	.st6{fill-rule:evenodd;clip-rule:evenodd;fill:none;}
+	.st7{fill-rule:evenodd;clip-rule:evenodd;fill:#DFE2E7;}
+	.st8{fill-rule:evenodd;clip-rule:evenodd;fill:#CDD4DA;}
+	.st9{fill-rule:evenodd;clip-rule:evenodd;fill:#B3BCC7;}
+	.st10{fill-rule:evenodd;clip-rule:evenodd;fill:#9DAAB7;}
+	.st11{fill-rule:evenodd;clip-rule:evenodd;fill:#8698A8;}
+	.st12{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_2_);}
+	.st13{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_3_);}
+	.st14{fill:#1F63EC;}
+	.st15{fill:#2D2D2D;}
+	.st16{fill:none;stroke:#E0E4E9;stroke-width:0.5;stroke-miterlimit:10;}
+	.st17{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_4_);}
+	.st18{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_5_);}
+	.st19{fill:none;stroke:#677380;stroke-width:0.5;stroke-miterlimit:10;}
+	.st20{fill:none;stroke:url(#SVGID_6_);stroke-width:2;stroke-miterlimit:10;}
+	.st21{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_7_);}
+	.st22{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_8_);}
+	.st23{fill:#FFFFFF;}
+	.st24{fill-rule:evenodd;clip-rule:evenodd;fill:#2D2D2D;}
+	.st25{clip-path:url(#SVGID_10_);}
+	.st26{clip-path:url(#SVGID_12_);}
+	.st27{fill:url(#SVGID_13_);}
+	.st28{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_14_);}
+	.st29{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_15_);}
+	.st30{clip-path:url(#SVGID_17_);}
+	.st31{clip-path:url(#SVGID_19_);}
+	.st32{fill:url(#SVGID_20_);}
+	.st33{fill:none;stroke:url(#SVGID_21_);stroke-width:2;stroke-miterlimit:10;}
+	.st34{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_22_);}
+	.st35{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_23_);}
+	.st36{clip-path:url(#SVGID_25_);}
+	.st37{clip-path:url(#SVGID_27_);}
+	.st38{fill:url(#SVGID_28_);}
+	.st39{clip-path:url(#SVGID_30_);}
+	.st40{clip-path:url(#SVGID_32_);}
+	.st41{fill:url(#SVGID_33_);}
+	.st42{fill-rule:evenodd;clip-rule:evenodd;fill:#126EF6;}
+	.st43{fill-rule:evenodd;clip-rule:evenodd;fill:#FFFFFF;}
+	.st44{clip-path:url(#SVGID_35_);}
+	.st45{clip-path:url(#SVGID_37_);}
+	.st46{fill:url(#SVGID_38_);}
+	.st47{fill-rule:evenodd;clip-rule:evenodd;fill:#9DA1A5;}
+	.st48{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_39_);}
+	.st49{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_40_);}
+	.st50{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_41_);}
+	.st51{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_42_);}
+	.st52{fill:none;stroke:url(#SVGID_43_);stroke-width:2;stroke-miterlimit:10;}
+	.st53{fill-rule:evenodd;clip-rule:evenodd;fill:none;stroke:#E0E4E9;stroke-width:0.5;stroke-miterlimit:10;}
+	.st54{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_44_);}
+	.st55{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_45_);}
+	.st56{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_46_);}
+	.st57{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_47_);}
+	.st58{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_48_);}
+	.st59{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_49_);}
+	.st60{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_50_);}
+	.st61{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_51_);}
+	.st62{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_52_);}
+	.st63{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_53_);}
+	.st64{clip-path:url(#SVGID_55_);}
+	.st65{clip-path:url(#SVGID_57_);}
+	.st66{fill:url(#SVGID_58_);}
+	.st67{clip-path:url(#SVGID_60_);}
+	.st68{clip-path:url(#SVGID_62_);}
+	.st69{fill:url(#SVGID_63_);}
+	.st70{fill:none;stroke:url(#SVGID_64_);stroke-width:2;stroke-miterlimit:10;}
+	.st71{clip-path:url(#SVGID_66_);}
+	.st72{clip-path:url(#SVGID_68_);}
+	.st73{fill:url(#SVGID_69_);}
+	.st74{clip-path:url(#SVGID_71_);}
+	.st75{clip-path:url(#SVGID_73_);}
+	.st76{fill:url(#SVGID_74_);}
+	.st77{clip-path:url(#SVGID_76_);}
+	.st78{clip-path:url(#SVGID_78_);}
+	.st79{fill:url(#SVGID_79_);}
+	.st80{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_80_);}
+	.st81{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_81_);}
+	.st82{clip-path:url(#SVGID_83_);}
+	.st83{clip-path:url(#SVGID_85_);}
+	.st84{fill:url(#SVGID_86_);}
+	.st85{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_87_);}
+	.st86{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_88_);}
+	.st87{clip-path:url(#SVGID_90_);}
+	.st88{clip-path:url(#SVGID_92_);}
+	.st89{fill:url(#SVGID_93_);}
+	.st90{fill:none;stroke:url(#SVGID_94_);stroke-width:2;stroke-miterlimit:10;}
+	.st91{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_95_);}
+	.st92{fill-rule:evenodd;clip-rule:evenodd;fill:url(#SVGID_96_);}
+	.st93{clip-path:url(#SVGID_98_);}
+	.st94{clip-path:url(#SVGID_100_);}
+	.st95{fill:url(#SVGID_101_);}
+	.st96{clip-path:url(#SVGID_103_);}
+	.st97{clip-path:url(#SVGID_105_);}
+	.st98{fill:url(#SVGID_106_);}
+	.st99{clip-path:url(#SVGID_108_);}
+	.st100{clip-path:url(#SVGID_110_);}
+	.st101{fill:url(#SVGID_111_);}
+	.st102{fill:#FFFFFF;stroke:#B3BCC7;stroke-width:0.275;stroke-miterlimit:10;}
+	.st103{clip-path:url(#SVGID_113_);}
+	.st104{fill:#FDD138;}
+	.st105{fill:#FCA62F;}
+	.st106{fill:#FB7927;}
+	.st107{fill:#F44B22;}
+	.st108{fill:#D81915;}
+	.st109{fill:#2D2D2D;stroke:#FFFFFF;stroke-width:0.3354;stroke-miterlimit:10;}
+	.st110{fill:none;stroke:#65727F;stroke-width:2;stroke-miterlimit:10;}
+	.st111{fill:none;stroke:#65727F;stroke-width:0.75;stroke-miterlimit:10;}
+	.st112{fill:url(#SVGID_114_);}
+	.st113{fill:#D06C50;}
+	.st114{fill:#2D2D2D;stroke:#B3BCC7;stroke-width:0.275;stroke-miterlimit:10;}
+	.st115{opacity:0.2;}
+	.st116{fill:none;stroke:#677380;stroke-width:0.3564;stroke-miterlimit:10;}
+	.st117{fill:none;stroke:#677380;stroke-width:0.3564;stroke-miterlimit:10;stroke-dasharray:1.0212,1.0212;}
+	.st118{fill:none;stroke:#677380;stroke-width:0.3564;stroke-miterlimit:10;stroke-dasharray:1.0205,1.0205;}
+	.st119{opacity:0.2;fill:none;}
+	.st120{fill:none;stroke:#677380;stroke-width:0.3689;stroke-miterlimit:10;}
+	.st121{fill:none;stroke:#677380;stroke-width:0.3689;stroke-miterlimit:10;stroke-dasharray:1.0509,1.0509;}
+	.st122{opacity:0.3;fill:#1F63EC;}
+	.st123{fill:#2D2D2D;stroke:#FFFFFF;stroke-width:0.3162;stroke-miterlimit:10;}
+	.st124{fill:#FFFFFF;stroke:#B3BCC7;stroke-width:0.3162;stroke-miterlimit:10;}
+	.st125{clip-path:url(#SVGID_118_);}
+	.st126{fill:url(#SVGID_119_);}
+	.st127{fill:none;stroke:#DFE2E7;stroke-width:0.75;stroke-miterlimit:10;}
+	.st128{fill:#9DA1A5;stroke:#FFFFFF;stroke-miterlimit:10;}
+	.st129{fill:url(#SVGID_120_);}
+	.st130{fill:none;stroke:#677380;stroke-width:0.75;stroke-miterlimit:10;}
+	.st131{opacity:0.4;}
+	.st132{clip-path:url(#SVGID_122_);}
+	.st133{clip-path:url(#SVGID_124_);}
+	.st134{fill:url(#SVGID_125_);}
+	.st135{fill:none;stroke:#8392A3;stroke-width:0.35;stroke-miterlimit:10;}
+	.st136{fill:none;stroke:#8392A3;stroke-width:0.35;stroke-miterlimit:10;stroke-dasharray:0.9951,0.9951;}
+	.st137{fill:none;stroke:#8392A3;stroke-width:0.35;stroke-miterlimit:10;stroke-dasharray:1.004,1.004;}
+	.st138{fill:none;stroke:url(#SVGID_126_);stroke-width:1.5;stroke-miterlimit:10;}
+	.st139{fill:url(#SVGID_127_);}
+	.st140{fill:none;stroke:#DDE0E4;stroke-width:0.35;stroke-miterlimit:10;}
+	.st141{fill:#2D2D2D;stroke:#A9B3BE;stroke-width:0.275;stroke-miterlimit:10;}
+	.st142{fill-rule:evenodd;clip-rule:evenodd;fill:#126EF4;}
+	.st143{fill:#FFFFFF;stroke:#B1BAC4;stroke-width:0.275;stroke-miterlimit:10;}
+	.st144{fill:#CE6C50;}
+	.st145{fill:#5B5B5B;}
+	.st146{fill:#8392A3;}
+	.st147{fill:none;stroke:url(#SVGID_128_);stroke-width:1.5;stroke-miterlimit:10;}
+	.st148{fill:url(#SVGID_129_);}
+	.st149{fill:none;stroke:#B5BDC4;stroke-width:0.7;stroke-miterlimit:10;}
+	.st150{opacity:0.6;fill:none;stroke:#78838E;stroke-width:0.35;stroke-miterlimit:10;}
+	.st151{opacity:0.2;fill:none;stroke:#8392A3;stroke-width:0.35;stroke-miterlimit:10;stroke-dasharray:1,1;}
+	.st152{fill:none;stroke:#DDE0E4;stroke-width:0.75;stroke-miterlimit:10;}
+	.st153{fill:none;stroke:#8392A3;stroke-width:0.5;stroke-miterlimit:10;}
+	.st154{opacity:0.2;fill:none;stroke:#677380;stroke-width:0.3564;stroke-miterlimit:10;stroke-dasharray:1.0182,1.0182;}
+	.st155{fill:none;stroke:#DDE0E4;stroke-width:0.765;stroke-miterlimit:10;}
+	.st156{fill:url(#SVGID_130_);}
+	.st157{fill:url(#SVGID_131_);}
+	.st158{fill:#B1BAC4;}
+	.st159{fill:#CBD1D8;}
+	.st160{fill:#0B1B2B;}
+	.st161{fill:#91D119;}
+	.st162{opacity:0.7;}
+	.st163{fill:#FFFFFF;stroke:#000000;stroke-width:0.4418;stroke-miterlimit:10;}
+	.st164{fill:none;stroke:#939CAA;stroke-width:0.2209;stroke-miterlimit:10;}
+	.st165{fill:none;stroke:#FFFFFF;stroke-width:3.0924;stroke-miterlimit:10;}
+	.st166{fill:url(#SVGID_132_);}
+	.st167{fill:none;stroke:url(#SVGID_133_);stroke-width:1.714;stroke-miterlimit:10;}
+	.st168{fill:url(#SVGID_134_);}
+	.st169{fill:url(#SVGID_135_);}
+	.st170{fill:url(#SVGID_136_);}
+	.st171{fill:url(#SVGID_137_);}
+	.st172{fill:url(#SVGID_138_);}
+	.st173{fill:url(#SVGID_139_);}
+	.st174{fill:url(#SVGID_140_);}
+	.st175{fill:url(#SVGID_141_);}
+	.st176{fill:url(#SVGID_142_);}
+	.st177{fill:url(#SVGID_143_);}
+	.st178{fill:url(#SVGID_144_);}
+	.st179{fill:none;stroke:#1F63EC;stroke-width:4;stroke-miterlimit:10;}
+	.st180{fill:none;stroke:#0B1B2B;stroke-width:4;stroke-miterlimit:10;}
+	.st181{fill:none;stroke:#677380;stroke-width:0.3989;stroke-miterlimit:10;}
+	.st182{fill:none;stroke:#677380;stroke-width:0.3989;stroke-miterlimit:10;stroke-dasharray:1.14,1.14;}
+	.st183{fill:#257AF1;}
+	.st184{opacity:0.3;fill:#FFFFFF;}
+	.st185{fill:none;stroke:#98A5B2;stroke-width:4;stroke-miterlimit:10;}
+	.st186{fill:none;stroke:#65727F;stroke-width:0.3989;stroke-miterlimit:10;}
+	.st187{fill:none;stroke:#65727F;stroke-width:0.3989;stroke-miterlimit:10;stroke-dasharray:1.14,1.14;}
+	.st188{fill:none;stroke:#DDDFE4;stroke-width:0.75;stroke-miterlimit:10;}
+	.st189{fill:#9A9EA2;}
+	.st190{fill-rule:evenodd;clip-rule:evenodd;fill:#3267AC;}
+	.st191{fill:#FFFFFF;stroke:#AFB8C3;stroke-width:0.275;stroke-miterlimit:10;}
+	.st192{fill:#C5694E;}
+	.st193{fill:#8192A2;}
+	.st194{fill:#2D2D2D;stroke:#FFFFFF;stroke-width:0.6317;stroke-miterlimit:10;}
+</style>
+<g id="图层_2">
+</g>
+<g id="图层_1">
+	<path class="st194" d="M24.51,28.51H5.49c-2.21,0-4-1.79-4-4V5.49c0-2.21,1.79-4,4-4h19.03c2.21,0,4,1.79,4,4v19.03   C28.51,26.72,26.72,28.51,24.51,28.51z"/>
+	<g>
+		<g>
+			<g>
+				<g>
+					<path class="st23" d="M15.47,7.1l-1.3,1.85c-0.2,0.29-0.54,0.47-0.9,0.47h-7.1V7.09C6.16,7.1,15.47,7.1,15.47,7.1z"/>
+					<polygon class="st23" points="24.3,7.1 13.14,22.91 5.7,22.91 16.86,7.1      "/>
+					<path class="st23" d="M14.53,22.91l1.31-1.86c0.2-0.29,0.54-0.47,0.9-0.47h7.09v2.33H14.53z"/>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+</svg>
\ No newline at end of file
diff --git a/studio/frontend/src/app/provider.tsx b/studio/frontend/src/app/provider.tsx
index 4bd348effc..25dbfdc780 100644
--- a/studio/frontend/src/app/provider.tsx
+++ b/studio/frontend/src/app/provider.tsx
@@ -9,7 +9,9 @@ import {
   shouldUseCustomWindowTitlebar,
 } from "@/components/tauri/window-titlebar";
 import { Toaster } from "@/components/ui/sonner";
+import { TooltipProvider } from "@/components/ui/tooltip";
 import { WebUpdateBanner } from "@/components/web/update-banner";
+import { DownloadManagerPanel } from "@/features/hub/download-manager";
 import { getTauriAuthFailure, tauriAutoAuth } from "@/features/auth";
 import { NativeIntentDrain } from "@/features/native-intents/native-intent-drain";
 import { useTauriBackend, type BackendStatus } from "@/hooks/use-tauri-backend";
@@ -255,6 +257,7 @@ function TauriWrapper({ children }: { children: ReactNode }) {
     return (
       <>
         {children}
+        <DownloadManagerPanel />
         <WebUpdateBanner enabled={!WEB_UPDATE_HIDDEN_ROUTES.has(pathname)} />
       </>
     );
@@ -272,6 +275,7 @@ function TauriWrapper({ children }: { children: ReactNode }) {
       <TauriUpdateLayer isExternalServer={isExternalServer} />
       <NativeIntentDrain />
       {children}
+      <DownloadManagerPanel />
     </>
   ) : (
     <StartupScreen
@@ -308,17 +312,19 @@ function TauriWrapper({ children }: { children: ReactNode }) {
 export function AppProvider({ children }: AppProviderProps) {
   return (
     <ThemeProvider attribute="class" defaultTheme="light">
-      <TauriWrapper>
-        {children}
-      </TauriWrapper>
-      <Toaster
-        position="top-right"
-        visibleToasts={2}
-        expand={true}
-        closeButton={true}
-        // Clear the chat header buttons on the right.
-        offset={{ top: 12, right: 64 }}
-      />
+      <TooltipProvider>
+        <TauriWrapper>
+          {children}
+        </TauriWrapper>
+        <Toaster
+          position="top-right"
+          visibleToasts={2}
+          expand={true}
+          closeButton={true}
+          // Clear the chat header buttons on the right.
+          offset={{ top: 12, right: 64 }}
+        />
+      </TooltipProvider>
     </ThemeProvider>
   );
 }
diff --git a/studio/frontend/src/app/router.tsx b/studio/frontend/src/app/router.tsx
index a0ca1e8cdb..dbb74ee1a1 100644
--- a/studio/frontend/src/app/router.tsx
+++ b/studio/frontend/src/app/router.tsx
@@ -12,6 +12,7 @@ import { Route as exportRoute } from "./routes/export";
 import { Route as gridTestRoute } from "./routes/grid-test";
 import { Route as indexRoute } from "./routes/index";
 import { Route as loginRoute } from "./routes/login";
+import { Route as hubRoute } from "./routes/hub";
 import { Route as onboardingRoute } from "./routes/onboarding";
 import { Route as projectsRoute } from "./routes/projects";
 import { Route as changePasswordRoute } from "./routes/change-password";
@@ -24,6 +25,7 @@ const routeTree = rootRoute.addChildren([
   loginRoute,
   changePasswordRoute,
   gridTestRoute,
+  hubRoute,
   settingsRoute,
   studioRoute,
   chatRoute,
diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index 200200d190..c8e47902b9 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -42,6 +42,7 @@ const CHAT_ONLY_ALLOWED = new Set([
   "/",
   "/chat",
   "/projects",
+  "/hub",
   "/login",
   "/signup",
   "/change-password",
diff --git a/studio/frontend/src/app/routes/hub.tsx b/studio/frontend/src/app/routes/hub.tsx
new file mode 100644
index 0000000000..dcd6617ec8
--- /dev/null
+++ b/studio/frontend/src/app/routes/hub.tsx
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { createRoute } from "@tanstack/react-router";
+import { lazy } from "react";
+import { requireAuth } from "../auth-guards";
+import { Route as rootRoute } from "./__root";
+
+const ModelsPage = lazy(() =>
+  import("@/features/hub/hub-page").then((m) => ({
+    default: m.ModelsPage,
+  })),
+);
+
+export interface ModelsSearch {
+  tab?: "discover" | "downloaded";
+}
+
+export const Route = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/hub",
+  beforeLoad: () => requireAuth(),
+  component: ModelsPage,
+  validateSearch: (search: Record<string, unknown>): ModelsSearch => {
+    const raw = search.tab;
+    if (raw === "discover" || raw === "downloaded") return { tab: raw };
+    return {};
+  },
+});
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 8d56d90f98..2abc4d190b 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -47,6 +47,7 @@ import { cn } from "@/lib/utils";
 import {
   ChefHatIcon,
   CursorInfo02Icon,
+  DashboardCircleIcon,
   Delete02Icon,
   DownloadSquare01Icon,
   Edit03Icon,
@@ -791,6 +792,15 @@ export function AppSidebar() {
                   closeMobileIfOpen();
                 }}
               />
+              <NavItem
+                icon={DashboardCircleIcon}
+                label={t("shell.navigation.hub")}
+                active={pathname === "/hub" || pathname.startsWith("/hub/")}
+                onClick={() => {
+                  navigate({ to: "/hub" });
+                  closeMobileIfOpen();
+                }}
+              />
               {/* Train has a labelled section when expanded; plain icon here only when collapsed. */}
               <NavItem
                 icon={TestTubeOutlineIcon}
diff --git a/studio/frontend/src/components/ui/tooltip.tsx b/studio/frontend/src/components/ui/tooltip.tsx
index b01dbccde1..954b1871f3 100644
--- a/studio/frontend/src/components/ui/tooltip.tsx
+++ b/studio/frontend/src/components/ui/tooltip.tsx
@@ -48,16 +48,14 @@ function Tooltip({
   }, []);
 
   return (
-    <TooltipProvider>
-      <TooltipToggleCtx.Provider value={toggle}>
-        <TooltipPrimitive.Root
-          data-slot="tooltip"
-          open={isControlled ? controlledOpen : clickOpen || undefined}
-          onOpenChange={onOpenChange}
-          {...props}
-        />
-      </TooltipToggleCtx.Provider>
-    </TooltipProvider>
+    <TooltipToggleCtx.Provider value={toggle}>
+      <TooltipPrimitive.Root
+        data-slot="tooltip"
+        open={isControlled ? controlledOpen : clickOpen || undefined}
+        onOpenChange={onOpenChange}
+        {...props}
+      />
+    </TooltipToggleCtx.Provider>
   );
 }
 
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 320cf4c962..ebaa756501 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -23,6 +23,7 @@ import {
 } from "../utils/chat-settings-storage";
 
 const HF_TOKEN_KEY = "unsloth_hf_token";
+const HF_TOKEN_CHANGED_EVENT = "unsloth:hf-token-changed";
 export const CHAT_REASONING_ENABLED_KEY = "unsloth_chat_reasoning_enabled";
 export const CHAT_TOOLS_ENABLED_KEY = "unsloth_chat_tools_enabled";
 export const CHAT_CODE_TOOLS_ENABLED_KEY = "unsloth_chat_code_tools_enabled";
@@ -231,6 +232,15 @@ function saveString(key: string, value: string): void {
   }
 }
 
+function notifyHfTokenChanged(value: string): void {
+  if (!canUseStorage()) return;
+  try {
+    window.dispatchEvent(new CustomEvent(HF_TOKEN_CHANGED_EVENT, { detail: value }));
+  } catch {
+    // ignore
+  }
+}
+
 type ChatRuntimeStore = {
   settingsHydrated: boolean;
   params: InferenceParams;
@@ -766,11 +776,11 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       setScalarSettingVersion("autoTitle", autoTitle, state.autoTitle);
       return { autoTitle };
     }),
-  setHfToken: (hfToken) =>
-    set(() => {
-      saveString(HF_TOKEN_KEY, hfToken);
-      return { hfToken };
-    }),
+  setHfToken: (hfToken) => {
+    saveString(HF_TOKEN_KEY, hfToken);
+    set({ hfToken });
+    notifyHfTokenChanged(hfToken);
+  },
   setModelsError: (modelsError) => set({ modelsError }),
   setCheckpoint: (modelId, ggufVariant) =>
     set((state) => {
diff --git a/studio/frontend/src/features/hub/catalog/catalog-states.tsx b/studio/frontend/src/features/hub/catalog/catalog-states.tsx
new file mode 100644
index 0000000000..e4c8554773
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/catalog-states.tsx
@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  CloudOffIcon,
+  CubeIcon,
+  FilterIcon,
+  RefreshIcon,
+  WifiDisconnected02Icon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useLayoutEffect, useRef, useState } from "react";
+
+export function NetworkErrorState({
+  online,
+  message,
+  onRetry,
+  onSwitchDevice,
+  resourceLabel = "models",
+}: {
+  online: boolean;
+  message: string;
+  onRetry: () => void;
+  onSwitchDevice?: () => void;
+  resourceLabel?: "models" | "datasets";
+}) {
+  const title = online ? "Couldn't reach Hugging Face" : "You're offline";
+  const body = online
+    ? "The discovery feed couldn't load. Check your connection or try again."
+    : `Reconnect to the internet to browse ${resourceLabel} from Hugging Face.`;
+  const icon = online ? CloudOffIcon : WifiDisconnected02Icon;
+
+  return (
+    <div className="flex min-h-[260px] flex-col items-center justify-center gap-3 px-6 text-center">
+      <div className="inline-flex size-11 items-center justify-center rounded-[12px] bg-amber-500/10 text-amber-700 dark:text-amber-300">
+        <HugeiconsIcon icon={icon} strokeWidth={1.6} className="size-5" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-[14px] font-semibold tracking-tight text-foreground">
+          {title}
+        </p>
+        <p className="max-w-md text-[12.5px] leading-5 text-muted-foreground">
+          {body}
+        </p>
+        <p className="text-[11px] text-muted-foreground/70">{message}</p>
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        {onSwitchDevice ? (
+          <button
+            type="button"
+            onClick={onSwitchDevice}
+            className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-foreground/[0.06] px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.1] dark:bg-white/[0.06] dark:hover:bg-white/[0.1]"
+          >
+            On Device
+          </button>
+        ) : null}
+        <button
+          type="button"
+          onClick={onRetry}
+          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.05]"
+        >
+          <HugeiconsIcon
+            icon={RefreshIcon}
+            strokeWidth={1.75}
+            className="size-3.5"
+          />
+          Try again
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function DiscoverFetchMoreState({
+  scannedCount,
+  hasActiveFilters,
+  isLoadingMore,
+  onFetchMore,
+  onClearFilters,
+}: {
+  scannedCount: number;
+  hasActiveFilters: boolean;
+  isLoadingMore: boolean;
+  onFetchMore: () => void;
+  onClearFilters: () => void;
+}) {
+  return (
+    <div className="flex min-h-[260px] flex-col items-center justify-center gap-3 px-6 text-center">
+      <div className="inline-flex size-11 items-center justify-center rounded-[12px] bg-muted text-muted-foreground">
+        <HugeiconsIcon icon={FilterIcon} strokeWidth={1.5} className="size-5" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-[14px] font-semibold tracking-tight text-foreground">
+          No matches yet
+        </p>
+        <p className="max-w-md text-[12.5px] leading-5 text-muted-foreground">
+          Scanned {scannedCount.toLocaleString()} results. Load another page to
+          keep searching Hugging Face.
+        </p>
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-2 pt-1">
+        {hasActiveFilters && (
+          <button
+            type="button"
+            onClick={onClearFilters}
+            className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-foreground/[0.06] px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.1] dark:bg-white/[0.06] dark:hover:bg-white/[0.1]"
+          >
+            Clear filters
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={onFetchMore}
+          disabled={isLoadingMore}
+          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] disabled:cursor-not-allowed disabled:opacity-50 dark:hover:bg-white/[0.05]"
+        >
+          <HugeiconsIcon
+            icon={RefreshIcon}
+            strokeWidth={1.75}
+            className="size-3.5"
+          />
+          {isLoadingMore ? "Loading..." : "Load more"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function DiscoverFetchMoreFooter({
+  scannedCount,
+  manualFetchAvailable,
+  hasActiveFilters,
+  isLoadingMore,
+  onFetchMore,
+}: {
+  scannedCount: number;
+  manualFetchAvailable: boolean;
+  hasActiveFilters: boolean;
+  isLoadingMore: boolean;
+  onFetchMore: () => void;
+}) {
+  return (
+    <div className="relative z-10 flex flex-col items-center gap-2 bg-card px-4 py-4 text-center">
+      <p className="text-[11.5px] leading-4 text-muted-foreground">
+        {hasActiveFilters
+          ? "Some results may be hidden by your filters."
+          : manualFetchAvailable
+            ? `Scanned ${scannedCount.toLocaleString()} results. Load more to continue.`
+            : "More results are available."}
+      </p>
+      <button
+        type="button"
+        onClick={onFetchMore}
+        disabled={isLoadingMore}
+        className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-foreground/[0.06] px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.1] disabled:cursor-not-allowed disabled:opacity-50 dark:bg-white/[0.06] dark:hover:bg-white/[0.1]"
+      >
+        <HugeiconsIcon
+          icon={RefreshIcon}
+          strokeWidth={1.75}
+          className="size-3.5"
+        />
+        {isLoadingMore ? "Loading..." : "Load more"}
+      </button>
+    </div>
+  );
+}
+
+export function InventoryErrorState({
+  isDataset,
+  onRetry,
+}: {
+  isDataset: boolean;
+  onRetry: () => void;
+}) {
+  return (
+    <div className="flex min-h-[260px] flex-col items-center justify-center gap-3 px-6 text-center">
+      <div className="inline-flex size-11 items-center justify-center rounded-[12px] bg-amber-500/10 text-amber-700 dark:text-amber-300">
+        <HugeiconsIcon icon={CloudOffIcon} strokeWidth={1.6} className="size-5" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-[14px] font-semibold tracking-tight text-foreground">
+          Couldn't load your library
+        </p>
+        <p className="max-w-md text-[12.5px] leading-5 text-muted-foreground">
+          Something went wrong reading your downloaded{" "}
+          {isDataset ? "datasets" : "models"}. Check that the backend is running
+          and try again.
+        </p>
+      </div>
+      <button
+        type="button"
+        onClick={onRetry}
+        className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.05]"
+      >
+        <HugeiconsIcon icon={RefreshIcon} strokeWidth={1.75} className="size-3.5" />
+        Try again
+      </button>
+    </div>
+  );
+}
+
+export function EmptyState({
+  title,
+  body,
+  icon = CubeIcon,
+}: {
+  title: string;
+  body: string;
+  icon?: IconSvgElement;
+}) {
+  return (
+    <div className="flex min-h-[220px] flex-col items-center justify-center gap-3 px-6 text-center">
+      <div className="inline-flex size-11 items-center justify-center rounded-[12px] bg-muted text-muted-foreground">
+        <HugeiconsIcon icon={icon} strokeWidth={1.5} className="size-5" />
+      </div>
+      <div className="space-y-1">
+        <p className="text-[14px] font-semibold tracking-tight text-foreground">
+          {title}
+        </p>
+        <p className="max-w-md text-[12.5px] leading-5 text-muted-foreground">
+          {body}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function SkeletonRow() {
+  return (
+    <div className="flex items-center gap-3 px-3 py-2.5">
+      <div className="size-8 shrink-0 animate-pulse rounded-[9px] bg-muted" />
+      <div className="min-w-0 flex-1 space-y-1.5">
+        <div className="h-[13px] w-1/2 animate-pulse rounded-full bg-muted" />
+        <div className="h-[11px] w-3/4 animate-pulse rounded-full bg-muted/70" />
+      </div>
+    </div>
+  );
+}
+
+const SKELETON_ROW_ESTIMATE_PX = 56;
+const MIN_SKELETON_ROWS = 4;
+const MAX_SKELETON_ROWS = 24;
+const DEFAULT_SKELETON_ROWS = 6;
+
+function clampSkeletonCount(height: number): number {
+  if (!Number.isFinite(height) || height <= 0) return DEFAULT_SKELETON_ROWS;
+  return Math.max(
+    MIN_SKELETON_ROWS,
+    Math.min(MAX_SKELETON_ROWS, Math.ceil(height / SKELETON_ROW_ESTIMATE_PX)),
+  );
+}
+
+export function SkeletonList({ count }: { count?: number }) {
+  const ref = useRef<HTMLUListElement>(null);
+  const [autoCount, setAutoCount] = useState(count ?? DEFAULT_SKELETON_ROWS);
+  const rowCount = count ?? autoCount;
+
+  useLayoutEffect(() => {
+    if (count != null) return;
+    const container = ref.current?.parentElement;
+    if (!container || typeof window === "undefined") return;
+
+    let frame: number | null = null;
+    const update = () => {
+      frame = null;
+      setAutoCount(clampSkeletonCount(container.clientHeight));
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = window.requestAnimationFrame(update);
+    };
+    schedule();
+
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", schedule);
+      return () => {
+        if (frame !== null) window.cancelAnimationFrame(frame);
+        window.removeEventListener("resize", schedule);
+      };
+    }
+
+    const observer = new ResizeObserver(schedule);
+    observer.observe(container);
+    return () => {
+      if (frame !== null) window.cancelAnimationFrame(frame);
+      observer.disconnect();
+    };
+  }, [count]);
+
+  return (
+    <ul ref={ref} className="divide-y divide-border" aria-hidden="true">
+      {Array.from({ length: rowCount }).map((_, i) => (
+        <li key={i}>
+          <SkeletonRow />
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/dataset-download-section.tsx b/studio/frontend/src/features/hub/catalog/dataset-download-section.tsx
new file mode 100644
index 0000000000..253d818116
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/dataset-download-section.tsx
@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useRepoDownload } from "../download-manager";
+import { deleteCachedDataset } from "../inventory";
+import { cn } from "@/lib/utils";
+import { TrainIcon } from "../components/train-icon";
+import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import { DotTag } from "./dot-tag";
+import { PathInfoButton } from "./path-info-button";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useState } from "react";
+import { useHfTokenStore } from "../stores/hf-token-store";
+import { formatBytes } from "../lib/format";
+import { useDatasetSize } from "../hooks/use-dataset-size";
+import {
+  CardDivider,
+  CardDeleteButton,
+  DeleteConfirmDialog,
+  DownloadActionButton,
+  DownloadCard,
+} from "./download-card";
+import { useCardDelete } from "./use-card-delete";
+import { useDownloadCardState } from "./use-download-card-state";
+
+export function DatasetDownloadSection({
+  repoId,
+  isDownloaded,
+  isPartial = false,
+  partialTransport = null,
+  cachePath,
+  knownBytes,
+  onTrain,
+  onChange,
+}: {
+  repoId: string;
+  isDownloaded: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+  cachePath?: string | null;
+  knownBytes?: number | null;
+  onTrain?: () => void;
+  onChange?: () => void;
+}) {
+  const hfToken = useHfTokenStore((s) => s.token);
+  const [deleteOpen, setDeleteOpen] = useState(false);
+  const { deleting, runDelete } = useCardDelete({
+    action: () => deleteCachedDataset(repoId),
+    resourceName: "dataset",
+    successMessage: () => `Deleted ${repoId}`,
+    onSuccess: () => {
+      setDeleteOpen(false);
+      onChange?.();
+    },
+  });
+
+  const job = useRepoDownload({
+    kind: "dataset",
+    repoId,
+    autoAdopt: true,
+  });
+
+  const progress = job.progress;
+  const cancelling = job.cancelling;
+  const upstreamSize = useDatasetSize(repoId, {
+    enabled:
+      progress === null && !isDownloaded && !(knownBytes && knownBytes > 0),
+    token: hfToken || undefined,
+  });
+  const upstreamBytes =
+    upstreamSize?.numBytesParquet ?? upstreamSize?.numBytesOriginal ?? null;
+  const progressBytes =
+    progress && progress.expectedBytes > 0 ? progress.expectedBytes : null;
+  const totalBytes =
+    progressBytes && progressBytes > 0
+      ? progressBytes
+      : knownBytes && knownBytes > 0
+        ? knownBytes
+        : upstreamBytes;
+
+  const downloading = progress !== null;
+  const canDelete =
+    (isDownloaded || isPartial) && !downloading && !cancelling && !deleting;
+  const downloadAction = useDownloadCardState({
+    job,
+    variant: null,
+    // The datasets-server size above is a parquet/original estimate, not the raw
+    // repo bytes snapshot_download fetches; 0 lets the backend resolve the true total.
+    expectedBytes: 0,
+    downloading,
+    disabled: cancelling || deleting,
+    isPartial,
+    partialTransport,
+  });
+
+  return (
+    <DownloadCard
+      job={job}
+      progress={downloading ? progress : null}
+      dialogs={
+        <DeleteConfirmDialog
+          open={deleteOpen}
+          onOpenChange={(o) => {
+            if (!o && !deleting) setDeleteOpen(false);
+          }}
+          title="Delete cached dataset?"
+          deleting={deleting}
+          onConfirm={() => void runDelete()}
+          description={
+            <>
+              This will remove{" "}
+              <span className="font-medium text-foreground">{repoId}</span> and
+              its downloaded files
+              {totalBytes && totalBytes > 0
+                ? ` (${formatBytes(totalBytes)})`
+                : ""}{" "}
+              from disk. You can re-download it later.
+            </>
+          }
+        />
+      }
+    >
+      <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+        <span className="flex items-center gap-1.5 text-[12px] text-muted-foreground">
+          {isDownloaded && <DotTag tone="success" label="On device" />}
+          {!isDownloaded && isPartial && !downloading && (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span className="inline-flex">
+                  <DotTag tone="warning" label="Partial" />
+                </span>
+              </TooltipTrigger>
+              <TooltipContent side="top" sideOffset={4}>
+                Partial download. Click to continue.
+              </TooltipContent>
+            </Tooltip>
+          )}
+          {totalBytes && totalBytes > 0 && (
+            <span className="tabular-nums">{formatBytes(totalBytes)}</span>
+          )}
+        </span>
+        <div className="ml-auto flex items-center gap-0.5">
+          {canDelete && (
+            <CardDeleteButton
+              label={`Delete ${repoId}`}
+              onClick={() => setDeleteOpen(true)}
+            />
+          )}
+          {isDownloaded && cachePath && (
+            <PathInfoButton
+              path={cachePath}
+              title="On-device location"
+              description={`Where ${repoId} lives on disk.`}
+            />
+          )}
+        </div>
+      </div>
+      {/* Train CTA hidden until Hub->train picker ships; divider pairs with it. */}
+      {(!isDownloaded || downloading || HUB_POST_DOWNLOAD_ACTIONS_VISIBLE) && (
+        <CardDivider />
+      )}
+      {isDownloaded && !downloading ? (
+        <button
+          type="button"
+          onClick={() => onTrain?.()}
+          className={cn(
+            "hub-action-btn w-28",
+            !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && "hidden",
+          )}
+        >
+          <HugeiconsIcon icon={TrainIcon} strokeWidth={1.75} />
+          Train
+        </button>
+      ) : (
+        <DownloadActionButton
+          downloading={downloadAction.downloading}
+          cancelling={downloadAction.cancelling}
+          loading={downloadAction.starting}
+          isPartial={downloadAction.isPartial}
+          partialTransport={downloadAction.partialTransport}
+          progressPercent={downloadAction.progressPercent}
+          disabled={downloadAction.disabled}
+          onClick={downloadAction.onClick}
+        />
+      )}
+    </DownloadCard>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/dot-tag.tsx b/studio/frontend/src/features/hub/catalog/dot-tag.tsx
new file mode 100644
index 0000000000..77b0a73d7b
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/dot-tag.tsx
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { cn } from "@/lib/utils";
+
+type DotTagTone =
+  | "success"
+  | "warning"
+  | "danger"
+  | "gguf"
+  | "checkpoint"
+  | "adapter";
+
+const TONE_CLASS: Record<DotTagTone, string> = {
+  success: "bg-status-success",
+  warning: "bg-status-warning",
+  danger: "bg-status-danger",
+  gguf: "bg-format-gguf",
+  checkpoint: "bg-format-checkpoint",
+  adapter: "bg-format-adapter",
+};
+
+export function DotTag({
+  tone,
+  label,
+  className,
+}: {
+  tone: DotTagTone;
+  label: string;
+  className?: string;
+}) {
+  return (
+    <span
+      className={cn(
+        "inline-flex h-5 shrink-0 items-center gap-1.5 whitespace-nowrap rounded-[7px] border border-border/60 bg-transparent px-1.5 text-[11px] font-medium leading-none text-muted-foreground",
+        className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className={cn("inline-block size-1.5 shrink-0 rounded-full", TONE_CLASS[tone])}
+      />
+      {label}
+    </span>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/download-cancel-indicator.tsx b/studio/frontend/src/features/hub/catalog/download-cancel-indicator.tsx
new file mode 100644
index 0000000000..d1b8671bfe
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/download-cancel-indicator.tsx
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Spinner } from "@/components/ui/spinner";
+import { Cancel01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+
+/**
+ * Inspector action-button affordance during a download: spinner that cross-fades
+ * to a cancel glyph on `.hub-action-btn` hover, in the same 16x16 slot so the
+ * percentage label never shifts. The swap is pure CSS; the component only carries
+ * the marker classes.
+ */
+export function DownloadCancelIndicator() {
+  return (
+    <span className="hub-cta-indicator">
+      <Spinner className="hub-cta-indicator-spinner" />
+      <HugeiconsIcon
+        icon={Cancel01Icon}
+        strokeWidth={1.75}
+        className="hub-cta-indicator-cancel"
+      />
+    </span>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/download-card.tsx b/studio/frontend/src/features/hub/catalog/download-card.tsx
new file mode 100644
index 0000000000..e5253526ab
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/download-card.tsx
@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { ReactNode } from "react";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import { Delete02Icon, Download01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import {
+  DownloadProgressBar,
+  type DownloadJob,
+  type DownloadJobProgress,
+} from "../download-manager";
+import { DownloadCancelIndicator } from "./download-cancel-indicator";
+import { TransportConflictDialog } from "./transport-conflict-dialog";
+import {
+  downloadActionAriaLabel,
+  downloadActionLabel,
+} from "./use-download-card-state";
+
+/**
+ * Shared shell for every download surface (safetensors, GGUF, dataset): card frame,
+ * progress bar, transport-conflict dialog, plus card-specific `dialogs` and children.
+ */
+export function DownloadCard({
+  job,
+  progress,
+  children,
+  dialogs,
+}: {
+  job: DownloadJob;
+  progress: DownloadJobProgress | null;
+  children: ReactNode;
+  dialogs?: ReactNode;
+}) {
+  return (
+    <>
+      <div className="hub-download-card">
+        <div className="group/dl flex items-center">{children}</div>
+        {progress && (
+          <DownloadProgressBar progress={progress} bytesPerSec={job.bytesPerSec} />
+        )}
+      </div>
+      <TransportConflictDialog
+        conflict={job.transportConflict}
+        onCancel={job.cancelConflict}
+        onKeepTransport={job.resumeConflict}
+        onSwitchTransport={job.restartConflict}
+      />
+      {dialogs}
+    </>
+  );
+}
+
+/** Vertical hairline that fades out on row hover, separating info from actions. */
+export function CardDivider() {
+  return (
+    <div
+      aria-hidden="true"
+      className="ml-1 mr-0 h-5 w-px shrink-0 bg-foreground/[0.06] opacity-100 transition-opacity duration-150 group-hover/dl:opacity-0 dark:bg-white/[0.04]"
+    />
+  );
+}
+
+export function CardDeleteButton({
+  label,
+  onClick,
+}: {
+  label: string;
+  onClick: () => void;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={label}
+          onClick={(e) => {
+            e.stopPropagation();
+            onClick();
+          }}
+          className="inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-[8px] text-muted-foreground opacity-0 transition-[opacity,background-color,color] duration-150 hover:bg-rose-500/10 hover:text-rose-600 focus-visible:opacity-100 group-hover/dl:opacity-100 dark:hover:bg-rose-500/15 dark:hover:text-rose-400"
+        >
+          <HugeiconsIcon
+            icon={Delete02Icon}
+            strokeWidth={1.75}
+            className="size-4"
+          />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="top" sideOffset={4}>
+        Delete from device
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+/**
+ * Download / Cancel / Resume button for the safetensors and dataset cards
+ * (the GGUF card folds Run/Chat into its own bespoke CTA).
+ */
+export function DownloadActionButton({
+  downloading,
+  cancelling,
+  loading = false,
+  isPartial = false,
+  partialTransport = null,
+  progressPercent = null,
+  disabled,
+  onClick,
+  className,
+}: {
+  downloading: boolean;
+  cancelling: boolean;
+  loading?: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+  progressPercent?: number | null;
+  disabled: boolean;
+  onClick: () => void;
+  className?: string;
+}) {
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={onClick}
+      aria-label={downloadActionAriaLabel(downloading, cancelling)}
+      className={cn(
+        "hub-action-btn w-28",
+        (loading || cancelling) && "opacity-70",
+        downloading &&
+          !cancelling &&
+          "hover:bg-rose-500/10 hover:text-rose-600 dark:hover:text-rose-400",
+        className,
+      )}
+    >
+      {cancelling ? (
+        <span className="inline-flex items-center gap-2 text-muted-foreground">
+          <Spinner />
+          Cancelling…
+        </span>
+      ) : downloading ? (
+        <>
+          <DownloadCancelIndicator />
+          {progressPercent != null ? `${progressPercent}%` : null}
+        </>
+      ) : loading ? (
+        <>
+          <Spinner />
+          Loading…
+        </>
+      ) : (
+        <>
+          <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} />
+          {downloadActionLabel(isPartial, partialTransport)}
+        </>
+      )}
+    </button>
+  );
+}
+
+/** Confirmation dialog shared by the model, quantization, and dataset delete flows. */
+export function DeleteConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  deleting,
+  onConfirm,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string;
+  description: ReactNode;
+  deleting: boolean;
+  onConfirm: () => void;
+}) {
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent size="sm">
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={deleting}>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            variant="destructive"
+            disabled={deleting}
+            onClick={(e) => {
+              e.preventDefault();
+              onConfirm();
+            }}
+          >
+            {deleting ? "Deleting…" : "Delete"}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/download-section.tsx b/studio/frontend/src/features/hub/catalog/download-section.tsx
new file mode 100644
index 0000000000..fb2921649b
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/download-section.tsx
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { GgufDownloadCard } from "./gguf-download-card";
+import { SafetensorsDownloadCard } from "./safetensors-download-card";
+import type { ModelInventoryFormat } from "../inventory";
+
+export function DownloadSection({
+  repoId,
+  isGguf,
+  isDownloaded,
+  isPartial = false,
+  partialTransport = null,
+  modelFormat,
+  canRun = true,
+  isActive,
+  activeQuant,
+  isLoadingThisModel,
+  gpuGb,
+  systemRamGb,
+  cachePath,
+  knownBytes,
+  onLoad,
+  onUseInChat,
+  onTrain,
+  onChange,
+}: {
+  repoId: string;
+  isGguf: boolean;
+  isDownloaded: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+  modelFormat?: ModelInventoryFormat | null;
+  canRun?: boolean;
+  isActive: boolean;
+  activeQuant: string | null;
+  isLoadingThisModel: boolean;
+  gpuGb?: number;
+  systemRamGb?: number;
+  cachePath?: string | null;
+  knownBytes?: number | null;
+  onLoad: (opts: { ggufVariant?: string; expectedBytes?: number }) => void;
+  onUseInChat?: () => void;
+  onTrain?: () => void;
+  onChange?: () => void;
+}) {
+  if (isGguf) {
+    return (
+      <GgufDownloadCard
+        repoId={repoId}
+        isActive={isActive}
+        activeQuant={activeQuant}
+        isLoadingThisModel={isLoadingThisModel}
+        gpuGb={gpuGb}
+        systemRamGb={systemRamGb}
+        cachePath={cachePath}
+        isPartial={isPartial}
+        onLoad={onLoad}
+        onUseInChat={onUseInChat}
+        onChange={onChange}
+      />
+    );
+  }
+  return (
+    <SafetensorsDownloadCard
+      repoId={repoId}
+      isDownloaded={isDownloaded}
+      isPartial={isPartial}
+      partialTransport={partialTransport}
+      modelFormat={modelFormat}
+      canRun={canRun}
+      isActive={isActive}
+      isLoadingThisModel={isLoadingThisModel}
+      cachePath={cachePath}
+      knownBytes={knownBytes}
+      onLoad={onLoad}
+      onUseInChat={onUseInChat}
+      onTrain={onTrain}
+      onChange={onChange}
+    />
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/external-link-confirm-dialog.tsx b/studio/frontend/src/features/hub/catalog/external-link-confirm-dialog.tsx
new file mode 100644
index 0000000000..5a661467fc
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/external-link-confirm-dialog.tsx
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { openLink } from "@/lib/open-link";
+import { LinkSquare02Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useExternalLinkConfirm } from "../stores/external-link-confirm";
+
+function hostOf(url: string): string {
+  try {
+    return new URL(url, "https://_").host;
+  } catch {
+    return url;
+  }
+}
+
+export function ExternalLinkConfirmDialog() {
+  const pendingUrl = useExternalLinkConfirm((s) => s.pendingUrl);
+  const dismiss = useExternalLinkConfirm((s) => s.dismiss);
+  const open = pendingUrl !== null;
+
+  return (
+    <AlertDialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) dismiss();
+      }}
+    >
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogMedia>
+            <HugeiconsIcon
+              icon={LinkSquare02Icon}
+              strokeWidth={1.75}
+              className="text-muted-foreground"
+            />
+          </AlertDialogMedia>
+          <AlertDialogTitle>Open external link</AlertDialogTitle>
+          <AlertDialogDescription>
+            You are about to leave Unsloth and open this page in your browser.
+            Only continue if you trust the destination.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        {pendingUrl && (
+          <div className="min-w-0 rounded-[12px] bg-muted/50 px-3 py-2.5 text-left">
+            <p className="truncate text-[13px] font-medium text-foreground">
+              {hostOf(pendingUrl)}
+            </p>
+            <p className="mt-0.5 break-all text-[11.5px] leading-[16px] text-muted-foreground">
+              {pendingUrl}
+            </p>
+          </div>
+        )}
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            onClick={() => {
+              if (pendingUrl) openLink(pendingUrl);
+              dismiss();
+            }}
+          >
+            Open link
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
new file mode 100644
index 0000000000..c9be7b549b
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
@@ -0,0 +1,857 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import {
+  downloadManager,
+  useDownloadManagerStore,
+  useRepoDownload,
+} from "../download-manager";
+import { type GgufVariantDetail, deleteCachedModel } from "../inventory";
+import { formatBytes } from "../lib/format";
+import { type GgufFitClass, classifyGgufFit } from "../lib/gguf-fit";
+import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import {
+  ggufVariantsMatch,
+  normalizeGgufVariantIdentity,
+} from "../lib/model-identity";
+import { cn } from "@/lib/utils";
+import { useHfTokenStore } from "../stores/hf-token-store";
+import {
+  ArrowDown01Icon,
+  Delete02Icon,
+  Download01Icon,
+  InformationCircleIcon,
+  PencilEdit02Icon,
+  PlayIcon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  type KeyboardEventHandler,
+  type MouseEventHandler,
+} from "react";
+import {
+  ggufVariantDisplayLabel,
+  ggufVariantDownloadSizeBytes,
+  sortDownloadableGgufVariants,
+} from "../lib/gguf-variant-sort";
+import { DotTag } from "./dot-tag";
+import { DownloadCancelIndicator } from "./download-cancel-indicator";
+import {
+  CardDivider,
+  DeleteConfirmDialog,
+  DownloadCard,
+} from "./download-card";
+import {
+  activeDownloadState,
+  applyLiveGgufVariantStates,
+  createLiveGgufVariantStatesSelector,
+} from "./gguf-live-variant-states";
+import {
+  GgufDownloadStatusCard,
+  GgufDownloadingFallbackCard,
+} from "./gguf-status-cards";
+import { PathInfoButton } from "./path-info-button";
+import { useDeleteConfirmAction } from "./use-delete-confirm-action";
+import { useDownloadCardState } from "./use-download-card-state";
+import { useGgufVariantFetchState } from "./use-gguf-variant-fetch-state";
+
+interface FitBadgeMeta {
+  label: string;
+  tooltip: string;
+  iconClassName: string;
+}
+
+const FIT_BADGE: Record<GgufFitClass, FitBadgeMeta> = {
+  fits: {
+    label: "Full GPU offload",
+    tooltip: "Full offload likely possible on your system.",
+    iconClassName: "text-emerald-600 dark:text-emerald-400",
+  },
+  marginal: {
+    label: "Might fit",
+    tooltip:
+      "Might fit. Within the last GB of VRAM headroom, so loading can fail if other apps are using GPU memory.",
+    iconClassName: "text-amber-600 dark:text-amber-400",
+  },
+  partial: {
+    label: "Partial offload",
+    tooltip:
+      "Partial offload possible. Exceeds VRAM but fits with system RAM offload. Inference will be slower.",
+    iconClassName: "text-sky-600 dark:text-sky-400",
+  },
+  ram: {
+    label: "RAM fallback",
+    tooltip:
+      "No GPU VRAM detected. This GGUF may run with system RAM and CPU offload. Inference will be slower.",
+    iconClassName: "text-sky-600 dark:text-sky-400",
+  },
+  oom: {
+    label: "Won't fit",
+    tooltip: "Exceeds combined VRAM and system RAM budget.",
+    iconClassName: "text-rose-600 dark:text-rose-400",
+  },
+};
+
+/** Chip styling matching the on-device list's StatChip, no icon. */
+const CHIP_BASE =
+  "inline-flex h-5 shrink-0 items-center justify-center whitespace-nowrap rounded-[7px] border px-1.5 text-[11.5px] font-medium tabular-nums leading-3 shadow-[inset_0_1px_0_rgba(255,255,255,0.04)]";
+const CHIP_DEFAULT =
+  "border-foreground/15 bg-muted text-foreground/85 dark:border-border/60 dark:bg-white/[0.04] dark:text-foreground/85";
+const CHIP_ACTIVE =
+  "border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300";
+
+function QuantBadge({
+  quant,
+  fit,
+  showFit = true,
+  active = false,
+  variant = "trigger",
+  tooltipMode = "eager",
+}: {
+  quant: string;
+  fit: GgufFitClass;
+  showFit?: boolean;
+  active?: boolean;
+  variant?: "trigger" | "menu";
+  tooltipMode?: "eager" | "lazy" | "none";
+}) {
+  const meta = FIT_BADGE[fit];
+  const [tooltipArmed, setTooltipArmed] = useState(false);
+  const [tooltipOpen, setTooltipOpen] = useState(false);
+  const armTooltip = useCallback(() => {
+    setTooltipArmed((armed) => (armed ? armed : true));
+    if (tooltipMode === "lazy") setTooltipOpen(true);
+  }, [tooltipMode]);
+  const tooltipActive = tooltipMode === "eager" || tooltipArmed;
+  const inner =
+    variant === "menu" ? (
+      <span
+        className={cn(
+          CHIP_BASE,
+          "gap-1.5 cursor-help",
+          active ? CHIP_ACTIVE : CHIP_DEFAULT,
+        )}
+      >
+        {showFit && (
+          <HugeiconsIcon
+            icon={InformationCircleIcon}
+            strokeWidth={2.25}
+            className={cn("size-3.5 shrink-0", meta.iconClassName)}
+          />
+        )}
+        <span>{quant}</span>
+      </span>
+    ) : (
+      <span
+        className={cn(
+          "inline-flex cursor-help items-center gap-1.5 text-[12.5px] font-medium tracking-tight tabular-nums",
+          active ? "text-emerald-600 dark:text-emerald-400" : "text-foreground",
+        )}
+      >
+        {showFit && (
+          <HugeiconsIcon
+            icon={InformationCircleIcon}
+            strokeWidth={2.25}
+            className={cn("size-3.5 shrink-0", meta.iconClassName)}
+          />
+        )}
+        <span>{quant}</span>
+      </span>
+    );
+  if (!showFit || tooltipMode === "none") return inner;
+  if (!tooltipActive) {
+    return (
+      <span
+        className="inline-flex min-w-0"
+        onPointerEnter={armTooltip}
+        onFocusCapture={armTooltip}
+      >
+        {inner}
+      </span>
+    );
+  }
+  return (
+    <Tooltip
+      open={tooltipMode === "lazy" ? tooltipOpen : undefined}
+      onOpenChange={tooltipMode === "lazy" ? setTooltipOpen : undefined}
+    >
+      <TooltipTrigger
+        asChild
+        onFocusCapture={tooltipMode === "lazy" ? armTooltip : undefined}
+        onPointerEnter={tooltipMode === "lazy" ? armTooltip : undefined}
+      >
+        {inner}
+      </TooltipTrigger>
+      <TooltipContent side="top" sideOffset={4}>
+        {meta.tooltip}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+interface GgufVariantMenuItem {
+  filename: string;
+  key: string;
+  quant: string;
+  label: string;
+  fit: GgufFitClass;
+  downloaded: boolean;
+  partial: boolean;
+  downloadSizeLabel: string;
+}
+
+function createGgufVariantMenuItems(
+  variants: readonly GgufVariantDetail[] | null,
+  resources: { gpuGb?: number; systemRamGb?: number },
+): GgufVariantMenuItem[] {
+  if (!variants) return [];
+  return variants.map((variant) => ({
+    filename: variant.filename,
+    key: normalizeGgufVariantIdentity(variant.quant),
+    quant: variant.quant,
+    label: ggufVariantDisplayLabel(variant),
+    fit: classifyGgufFit(variant.size_bytes, resources),
+    downloaded: Boolean(variant.downloaded),
+    partial: Boolean(variant.partial),
+    downloadSizeLabel: formatBytes(ggufVariantDownloadSizeBytes(variant)),
+  }));
+}
+
+const GgufVariantMenuRow = memo(function GgufVariantMenuRow({
+  item,
+  selected,
+  loaded,
+  liveActive,
+  showFitInfo,
+  onSelect,
+  onDelete,
+}: {
+  item: GgufVariantMenuItem;
+  selected: boolean;
+  loaded: boolean;
+  liveActive: boolean;
+  showFitInfo: boolean;
+  onSelect: (quant: string) => void;
+  onDelete: (quant: string) => void;
+}) {
+  const selectVariant = useCallback(() => {
+    onSelect(item.quant);
+  }, [item.quant, onSelect]);
+  const handleKeyDown = useCallback<KeyboardEventHandler<HTMLDivElement>>(
+    (e) => {
+      if (e.target !== e.currentTarget) return;
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        selectVariant();
+      }
+    },
+    [selectVariant],
+  );
+  const handleDelete = useCallback<MouseEventHandler<HTMLButtonElement>>(
+    (e) => {
+      e.stopPropagation();
+      onDelete(item.quant);
+    },
+    [item.quant, onDelete],
+  );
+  const canDelete = (item.downloaded || item.partial) && !loaded && !liveActive;
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-pressed={selected}
+      onClick={selectVariant}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        "group relative mx-2 flex cursor-pointer items-center gap-2 rounded-[12px] px-2.5 py-2 text-left transition-colors",
+        selected
+          ? "bg-foreground/[0.07] dark:bg-foreground/[0.12]"
+          : "hover:bg-foreground/[0.05] dark:hover:bg-foreground/[0.06]",
+      )}
+    >
+      <span className="flex min-w-0 flex-1 items-center gap-2">
+        <QuantBadge
+          quant={item.label}
+          fit={item.fit}
+          showFit={showFitInfo}
+          active={loaded}
+          variant="menu"
+          tooltipMode="lazy"
+        />
+      </span>
+      <span className="ml-auto flex shrink-0 items-center gap-1.5">
+        {item.downloaded && (
+          <DotTag tone="success" label={loaded ? "Loaded" : "On device"} />
+        )}
+        {!item.downloaded && item.partial && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <span className="inline-flex">
+                <DotTag
+                  tone="warning"
+                  label={liveActive ? "Downloading" : "Partial"}
+                />
+              </span>
+            </TooltipTrigger>
+            <TooltipContent side="top" sideOffset={4}>
+              {liveActive
+                ? "Download is running. Select it to view progress."
+                : "Partial download. Select it to continue."}
+            </TooltipContent>
+          </Tooltip>
+        )}
+        <DotTag tone="gguf" label="GGUF" />
+        <span className="relative">
+          <span className={cn(CHIP_BASE, CHIP_DEFAULT)}>
+            {item.downloadSizeLabel}
+          </span>
+          {canDelete && (
+            <button
+              type="button"
+              onClick={handleDelete}
+              aria-label={`Delete ${item.label}${item.partial && !item.downloaded ? " (partial)" : ""}`}
+              className={cn(
+                "absolute inset-0 inline-flex cursor-pointer items-center justify-center rounded-[7px]",
+                "bg-popover text-foreground/70 ring-1 ring-border transition-colors",
+                "opacity-0 group-hover:opacity-100 focus-visible:opacity-100",
+                "hover:text-destructive hover:ring-destructive/40",
+              )}
+            >
+              <HugeiconsIcon
+                icon={Delete02Icon}
+                strokeWidth={1.75}
+                className="size-3"
+              />
+            </button>
+          )}
+        </span>
+      </span>
+    </div>
+  );
+});
+
+export function GgufDownloadCard({
+  repoId,
+  isActive,
+  activeQuant,
+  isLoadingThisModel,
+  gpuGb,
+  systemRamGb,
+  cachePath,
+  preferLocalCache = false,
+  isPartial = false,
+  onLoad,
+  onUseInChat,
+  onChange,
+}: {
+  repoId: string;
+  isActive: boolean;
+  activeQuant: string | null;
+  isLoadingThisModel: boolean;
+  gpuGb?: number;
+  systemRamGb?: number;
+  cachePath?: string | null;
+  preferLocalCache?: boolean;
+  isPartial?: boolean;
+  onLoad: (opts: { ggufVariant?: string; expectedBytes?: number }) => void;
+  onUseInChat?: () => void;
+  onChange?: () => void;
+}) {
+  const hfToken = useHfTokenStore((s) => s.token);
+  const localVariantPath = cachePath?.trim() || null;
+  const { variants, loading, error, refreshError, refresh } =
+    useGgufVariantFetchState({
+      repoId,
+      hfToken,
+      preferLocalCache,
+      localPath: localVariantPath,
+    });
+  const [selectedQuantState, setSelectedQuantState] = useState<{
+    repoId: string;
+    quant: string | null;
+    userPicked?: boolean;
+  }>(() => ({ repoId, quant: null }));
+  const selectedQuantOverride =
+    selectedQuantState.repoId === repoId ? selectedQuantState.quant : null;
+  const [open, setOpen] = useState(false);
+  const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
+  const [completedVariantKeys, setCompletedVariantKeys] = useState<
+    ReadonlySet<string>
+  >(() => new Set<string>());
+
+  const rawSortedVariants = useMemo(() => {
+    if (!variants) return null;
+    return sortDownloadableGgufVariants(variants, { gpuGb, systemRamGb });
+  }, [variants, gpuGb, systemRamGb]);
+  const selectLiveGgufVariantStates = useMemo(
+    () => createLiveGgufVariantStatesSelector(repoId),
+    [repoId],
+  );
+  const liveVariantStates = useDownloadManagerStore(selectLiveGgufVariantStates);
+  const sortedVariants = useMemo(() => {
+    if (!rawSortedVariants) return null;
+    const withLive = applyLiveGgufVariantStates(
+      rawSortedVariants,
+      liveVariantStates,
+    );
+    if (completedVariantKeys.size === 0) return withLive;
+    return withLive.map((v) =>
+      completedVariantKeys.has(normalizeGgufVariantIdentity(v.quant))
+        ? { ...v, downloaded: true, partial: false }
+        : v,
+    );
+  }, [completedVariantKeys, liveVariantStates, rawSortedVariants]);
+  const variantMenuItems = useMemo(
+    () => createGgufVariantMenuItems(sortedVariants, { gpuGb, systemRamGb }),
+    [gpuGb, sortedVariants, systemRamGb],
+  );
+
+  const selectedQuant =
+    (selectedQuantOverride
+      ? sortedVariants?.find((v) =>
+          ggufVariantsMatch(v.quant, selectedQuantOverride),
+        )?.quant
+      : null) ??
+    sortedVariants?.[0]?.quant ??
+    null;
+
+  const job = useRepoDownload({
+    kind: "model",
+    repoId,
+    activeVariant: selectedQuant ?? undefined,
+    onComplete: (variant) => {
+      if (!variant) return;
+      const key = normalizeGgufVariantIdentity(variant);
+      setCompletedVariantKeys((prev) =>
+        prev.has(key) ? prev : new Set(prev).add(key),
+      );
+    },
+  });
+  const progress = job.progress;
+  const cancelling = job.cancelling;
+
+  const setExpectedBytes = job.setExpectedBytes;
+  useEffect(() => {
+    const controller = new AbortController();
+    void downloadManager.probeAndAdopt("model", repoId, controller.signal, {
+      includeVariants: true,
+      fresh: true,
+      onModelAdopt: (active) => {
+        if (controller.signal.aborted) return;
+        if (active.variant) {
+          setSelectedQuantState((prev) =>
+            prev.repoId === repoId && prev.userPicked
+              ? prev
+              : { repoId, quant: active.variant },
+          );
+        }
+      },
+    });
+    return () => {
+      controller.abort();
+    };
+  }, [repoId]);
+
+  useEffect(() => {
+    if (!variants || !progress?.variant) return;
+    const knownVariant = variants.find((variant) =>
+      ggufVariantsMatch(variant.quant, progress.variant),
+    );
+    if (!knownVariant) return;
+    const expectedBytes =
+      knownVariant.download_size_bytes ?? knownVariant.size_bytes ?? 0;
+    if (expectedBytes > progress.expectedBytes) {
+      setExpectedBytes(expectedBytes, progress.variant);
+    }
+  }, [
+    variants,
+    progress?.variant,
+    progress?.expectedBytes,
+    setExpectedBytes,
+  ]);
+
+  useEffect(() => {
+    setCompletedVariantKeys(new Set<string>());
+  }, [repoId]);
+
+  useEffect(() => {
+    if (loading || error || refreshError || !variants) return;
+    setCompletedVariantKeys((prev) =>
+      prev.size === 0 ? prev : new Set<string>(),
+    );
+  }, [loading, error, refreshError, variants]);
+
+  const selected =
+    sortedVariants?.find((v) => ggufVariantsMatch(v.quant, selectedQuant)) ??
+    null;
+  const selectedLiveState = selectedQuant
+    ? liveVariantStates.get(normalizeGgufVariantIdentity(selectedQuant))
+    : undefined;
+  const selectedLiveActive = activeDownloadState(selectedLiveState?.state);
+  const downloadingThisVariant =
+    progress !== null && ggufVariantsMatch(progress.variant, selectedQuant);
+  const ctaDisabled = isLoadingThisModel || !selected;
+  const selectedIsActive =
+    isActive && activeQuant && ggufVariantsMatch(selected?.quant, activeQuant);
+  const isGgufRunCta =
+    !!selected?.downloaded &&
+    !cancelling &&
+    !downloadingThisVariant &&
+    !isLoadingThisModel &&
+    !selectedIsActive;
+  const showFitInfo = Boolean(gpuGb) || Boolean(systemRamGb);
+  const selectedFit = useMemo(
+    () =>
+      selected
+        ? classifyGgufFit(selected.size_bytes, { gpuGb, systemRamGb })
+        : null,
+    [gpuGb, selected?.size_bytes, systemRamGb],
+  );
+  const selectedDownloadSizeLabel = selected
+    ? formatBytes(ggufVariantDownloadSizeBytes(selected))
+    : null;
+  const selectedVariantKey = selectedQuant
+    ? normalizeGgufVariantIdentity(selectedQuant)
+    : null;
+  const activeVariantKey = activeQuant
+    ? normalizeGgufVariantIdentity(activeQuant)
+    : null;
+  const handleSelectVariant = useCallback(
+    (quant: string) => {
+      setSelectedQuantState({
+        repoId,
+        quant,
+        userPicked: true,
+      });
+      setOpen(false);
+    },
+    [repoId],
+  );
+  const handleDeleteVariant = useCallback((quant: string) => {
+    setDeleteTarget(quant);
+  }, []);
+  const downloadAction = useDownloadCardState({
+    job,
+    variant: selectedQuant,
+    expectedBytes: selected?.download_size_bytes ?? selected?.size_bytes ?? 0,
+    downloading: downloadingThisVariant,
+    cancelling,
+    disabled: cancelling
+      ? true
+      : downloadingThisVariant
+        ? false
+        : ctaDisabled && !selectedIsActive,
+    isPartial: Boolean(selected?.partial),
+    partialTransport: selected?.partial_transport ?? null,
+  });
+  const selectedLabel = selected ? ggufVariantDisplayLabel(selected) : null;
+  const deleteTargetVariant =
+    deleteTarget && sortedVariants
+      ? sortedVariants.find((v) => ggufVariantsMatch(v.quant, deleteTarget))
+      : null;
+  const deleteTargetLabel = deleteTargetVariant
+    ? ggufVariantDisplayLabel(deleteTargetVariant)
+    : deleteTarget;
+  const { deleting, runDelete } = useDeleteConfirmAction({
+    action: async () => {
+      if (!deleteTarget) return;
+      await deleteCachedModel(repoId, deleteTarget, hfToken || undefined);
+    },
+    successMessage: () => `Deleted ${repoId} ${deleteTargetLabel ?? deleteTarget}`,
+    errorToast: (err) => ({
+      title: err instanceof Error ? err.message : "Failed to delete",
+    }),
+    onSuccess: () => {
+      onChange?.();
+    },
+    onSettled: () => {
+      setDeleteTarget(null);
+    },
+  });
+  const variantListUnavailable = !sortedVariants || sortedVariants.length === 0;
+  const showVariantLoadingState = loading && variantListUnavailable;
+
+  // Keep showing download progress even when the variant list is unavailable, so a
+  // remount never hides an in-flight download behind the variant status card.
+  if (progress && variantListUnavailable) {
+    return (
+      <GgufDownloadingFallbackCard
+        job={job}
+        progress={progress}
+        cancelling={cancelling}
+      />
+    );
+  }
+
+  if (showVariantLoadingState) {
+    return (
+      <GgufDownloadStatusCard
+        job={job}
+        loading
+        message="Loading available quantizations…"
+      />
+    );
+  }
+
+  if (variantListUnavailable) {
+    if (isPartial) {
+      return (
+        <GgufDownloadStatusCard
+          job={job}
+          tone="muted"
+          partial
+          message="Partial download present. Couldn't load quantizations."
+          actionLabel="Reload"
+          onAction={() => void refresh()}
+        />
+      );
+    }
+    return (
+      <GgufDownloadStatusCard
+        job={job}
+        tone="danger"
+        message={error ?? "No GGUF quantizations found in this repository."}
+      />
+    );
+  }
+
+  return (
+    <div className="flex w-full flex-col gap-2">
+      <DownloadCard
+        job={job}
+        progress={downloadingThisVariant ? progress : null}
+        dialogs={
+          <DeleteConfirmDialog
+            open={deleteTarget !== null}
+            onOpenChange={(o) => {
+              if (!o && !deleting) setDeleteTarget(null);
+            }}
+            title="Delete quantization?"
+            deleting={deleting}
+            onConfirm={() => void runDelete()}
+            description={
+              <>
+                This will remove{" "}
+                <span className="font-medium text-foreground">
+                  {repoId} ({deleteTargetLabel})
+                </span>{" "}
+                from disk. You can re-download it later.
+              </>
+            }
+          />
+        }
+      >
+        <Popover open={open} onOpenChange={setOpen}>
+          <PopoverTrigger asChild>
+            <button
+              type="button"
+              onClick={(e) => {
+                e.preventDefault();
+                setOpen((o) => !o);
+              }}
+              className="hub-menu-trigger flex h-9 min-w-0 flex-1 cursor-pointer items-center gap-2.5 rounded-[12px] px-3 text-left transition-colors hover:bg-foreground/[0.04] data-[state=open]:bg-foreground/[0.06] dark:hover:bg-white/[0.04] dark:data-[state=open]:bg-white/[0.06]"
+            >
+              {selected ? (
+                <QuantBadge
+                  quant={selectedLabel ?? selected.quant}
+                  fit={selectedFit ?? "oom"}
+                  showFit={showFitInfo}
+                  active={Boolean(selectedIsActive)}
+                />
+              ) : (
+                <span className="text-[12.5px] text-muted-foreground">
+                  Select quantization
+                </span>
+              )}
+              <span className="ml-auto flex items-center gap-1.5 text-[12px] text-muted-foreground">
+                {selected?.downloaded && (
+                  <DotTag
+                    tone="success"
+                    label={selectedIsActive ? "Loaded" : "On device"}
+                  />
+                )}
+                {selected && !selected.downloaded && selected.partial && (
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <span className="inline-flex">
+                        <DotTag
+                          tone="warning"
+                          label={selectedLiveActive ? "Downloading" : "Partial"}
+                        />
+                      </span>
+                    </TooltipTrigger>
+                    <TooltipContent side="top" sideOffset={4}>
+                      {selectedLiveActive
+                        ? "Download is running. Click to cancel."
+                        : "Partial download. Click to continue."}
+                    </TooltipContent>
+                  </Tooltip>
+                )}
+                <DotTag tone="gguf" label="GGUF" />
+                {selected &&
+                  selectedDownloadSizeLabel &&
+                  !selected.downloaded && (
+                    <span className="tabular-nums">
+                      {selectedDownloadSizeLabel}
+                    </span>
+                  )}
+                <HugeiconsIcon
+                  icon={ArrowDown01Icon}
+                  strokeWidth={1.25}
+                  className="ml-0.5 size-3.5 shrink-0"
+                />
+              </span>
+            </button>
+          </PopoverTrigger>
+          <PopoverContent
+            align="start"
+            side="bottom"
+            sideOffset={8}
+            avoidCollisions={false}
+            className="hub-menu-instant menu-soft-surface w-[var(--radix-popover-trigger-width)] min-w-[200px] gap-0 overflow-hidden p-0 py-2 ring-0"
+          >
+            <div className="max-h-[344px] overflow-y-auto [scrollbar-width:thin]">
+              {variantMenuItems.map((item) => {
+                const liveState = liveVariantStates.get(item.key);
+                const liveActive = activeDownloadState(liveState?.state);
+                return (
+                  <GgufVariantMenuRow
+                    key={item.filename}
+                    item={item}
+                    selected={item.key === selectedVariantKey}
+                    loaded={isActive && item.key === activeVariantKey}
+                    liveActive={liveActive}
+                    showFitInfo={showFitInfo}
+                    onSelect={handleSelectVariant}
+                    onDelete={handleDeleteVariant}
+                  />
+                );
+              })}
+            </div>
+          </PopoverContent>
+        </Popover>
+
+        {selected?.downloaded && cachePath && (
+          <PathInfoButton
+            path={cachePath}
+            title="On-device location"
+            description={`Where ${repoId} (${selectedLabel}) lives on disk.`}
+            className="ml-0.5"
+          />
+        )}
+
+        {!isGgufRunCta && <CardDivider />}
+
+        <button
+          type="button"
+          disabled={downloadAction.disabled}
+          onClick={() => {
+            if (downloadingThisVariant) {
+              downloadAction.onClick();
+              return;
+            }
+            if (selectedIsActive) {
+              onUseInChat?.();
+              return;
+            }
+            if (!selected) return;
+            if (selected.downloaded) {
+              onLoad({
+                ggufVariant: selected.quant,
+                expectedBytes: selected.size_bytes,
+              });
+            } else {
+              downloadAction.onClick();
+            }
+          }}
+          aria-label={downloadAction.ariaLabel}
+          className={cn(
+            isGgufRunCta ? "hub-run-action-btn w-28" : "hub-action-btn w-28",
+            isGgufRunCta && "ml-2",
+            ctaDisabled &&
+              !selectedIsActive &&
+              !downloadingThisVariant &&
+              !cancelling &&
+              "opacity-70",
+            (cancelling || downloadAction.starting) && "opacity-70",
+            downloadingThisVariant &&
+              !cancelling &&
+              "hover:bg-rose-500/10 hover:text-rose-600 dark:hover:text-rose-400",
+            // Hide post-download CTAs (Run / New Chat) for this PR.
+            !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE &&
+              !downloadingThisVariant &&
+              !cancelling &&
+              !isLoadingThisModel &&
+              (selectedIsActive || selected?.downloaded) &&
+              "hidden",
+          )}
+        >
+          {cancelling ? (
+            <span className="inline-flex items-center gap-2 text-muted-foreground">
+              <Spinner />
+              Cancelling…
+            </span>
+          ) : downloadingThisVariant ? (
+            <span className="inline-flex items-center gap-2">
+              <DownloadCancelIndicator />
+              {downloadAction.progressPercent != null
+                ? `${downloadAction.progressPercent}%`
+                : null}
+            </span>
+          ) : downloadAction.starting ? (
+            <span className="inline-flex items-center gap-2">
+              <Spinner />
+              Starting…
+            </span>
+          ) : isLoadingThisModel ? (
+            <span className="inline-flex items-center gap-2">
+              <Spinner />
+              Loading…
+            </span>
+          ) : selectedIsActive ? (
+            <>
+              <HugeiconsIcon icon={PencilEdit02Icon} strokeWidth={1.75} />
+              New Chat
+            </>
+          ) : selected?.downloaded ? (
+            <>
+              <HugeiconsIcon icon={PlayIcon} strokeWidth={1.75} />
+              Run
+            </>
+          ) : (
+            <>
+              <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} />
+              {downloadAction.downloadLabel}
+            </>
+          )}
+        </button>
+      </DownloadCard>
+      {refreshError && (
+        <button
+          type="button"
+          onClick={() => void refresh()}
+          className="self-start px-1 text-[11px] text-status-warning underline-offset-2 transition-colors hover:underline"
+        >
+          Couldn't refresh quantizations. Retry
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/gguf-live-variant-states.ts b/studio/frontend/src/features/hub/catalog/gguf-live-variant-states.ts
new file mode 100644
index 0000000000..ca18a00bce
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/gguf-live-variant-states.ts
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { ManagedDownload } from "../download-manager";
+import type { GgufVariantDetail } from "../inventory";
+import { normalizeGgufVariantIdentity } from "../lib/model-identity";
+
+export type LiveGgufVariantState = {
+  state: ManagedDownload["state"];
+  expectedBytes: number;
+  startedAt: number;
+};
+
+export function activeDownloadState(state: ManagedDownload["state"] | undefined): boolean {
+  return state === "running" || state === "cancelling";
+}
+
+function terminalPartialState(state: ManagedDownload["state"] | undefined): boolean {
+  return state === "cancelled" || state === "error";
+}
+
+function completedDownloadState(
+  state: ManagedDownload["state"] | undefined,
+): boolean {
+  return state === "complete";
+}
+
+export function createLiveGgufVariantStatesSelector(repoId: string): (state: {
+  jobs: Record<string, ManagedDownload>;
+}) => Map<string, LiveGgufVariantState> {
+  const repoKey = repoId.trim().toLowerCase();
+  let cache: { signature: string; states: Map<string, LiveGgufVariantState> } = {
+    signature: "",
+    states: new Map(),
+  };
+  return (state) => {
+    const entries: Array<[string, LiveGgufVariantState]> = [];
+    for (const job of Object.values(state.jobs)) {
+      if (job.kind !== "model" || !job.variant) continue;
+      if (job.repoId.trim().toLowerCase() !== repoKey) continue;
+      const live =
+        activeDownloadState(job.state) ||
+        completedDownloadState(job.state) ||
+        (terminalPartialState(job.state) &&
+          Math.max(job.downloadedBytes, job.completedBytes) > 0);
+      if (!live) continue;
+      entries.push([
+        normalizeGgufVariantIdentity(job.variant),
+        {
+          state: job.state,
+          expectedBytes: job.expectedBytes,
+          startedAt: job.startedAt,
+        },
+      ]);
+    }
+    entries.sort(([left], [right]) => left.localeCompare(right));
+    const signature = JSON.stringify(entries);
+    if (signature === cache.signature) return cache.states;
+    cache = { signature, states: new Map(entries) };
+    return cache.states;
+  };
+}
+
+export function applyLiveGgufVariantStates(
+  variants: readonly GgufVariantDetail[],
+  liveStates: ReadonlyMap<string, LiveGgufVariantState>,
+): GgufVariantDetail[] {
+  return variants.map((variant) => {
+    const live = liveStates.get(normalizeGgufVariantIdentity(variant.quant));
+    if (!live) return variant;
+    const liveComplete = completedDownloadState(live.state);
+    const livePartial =
+      activeDownloadState(live.state) || terminalPartialState(live.state);
+    const expectedBytes = Math.max(
+      live.expectedBytes,
+      variant.download_size_bytes ?? 0,
+      variant.size_bytes,
+    );
+    return {
+      ...variant,
+      downloaded: liveComplete ? true : livePartial ? false : variant.downloaded,
+      partial: liveComplete ? false : livePartial || variant.partial,
+      download_size_bytes:
+        expectedBytes > 0 ? expectedBytes : variant.download_size_bytes,
+    };
+  });
+}
diff --git a/studio/frontend/src/features/hub/catalog/gguf-status-cards.tsx b/studio/frontend/src/features/hub/catalog/gguf-status-cards.tsx
new file mode 100644
index 0000000000..6cc764b876
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/gguf-status-cards.tsx
@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import type { DownloadJob, DownloadJobProgress } from "../download-manager";
+import { DotTag } from "./dot-tag";
+import {
+  CardDivider,
+  DownloadActionButton,
+  DownloadCard,
+} from "./download-card";
+
+export function GgufDownloadStatusCard({
+  job,
+  message,
+  tone = "muted",
+  loading = false,
+  partial = false,
+  actionLabel,
+  onAction,
+}: {
+  job: DownloadJob;
+  message: string;
+  tone?: "muted" | "danger";
+  loading?: boolean;
+  partial?: boolean;
+  actionLabel?: string;
+  onAction?: () => void;
+}) {
+  return (
+    <div className="flex w-full flex-col gap-2">
+      <DownloadCard job={job} progress={null}>
+        <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+          <span
+            className={cn(
+              "flex min-w-0 items-center gap-2 text-[12.5px]",
+              tone === "danger" ? "text-destructive" : "text-muted-foreground",
+            )}
+          >
+            {loading && <Spinner className="size-3.5 shrink-0" />}
+            {partial && <DotTag tone="warning" label="Partial" />}
+            <span className="truncate">{message}</span>
+          </span>
+        </div>
+        <CardDivider />
+        {actionLabel && onAction ? (
+          <button
+            type="button"
+            onClick={onAction}
+            className="hub-action-btn w-28"
+          >
+            {actionLabel}
+          </button>
+        ) : (
+          <button
+            type="button"
+            disabled
+            className="hub-action-btn w-28 opacity-70"
+          >
+            {loading ? (
+              <>
+                <Spinner />
+                Loading
+              </>
+            ) : (
+              "Unavailable"
+            )}
+          </button>
+        )}
+      </DownloadCard>
+    </div>
+  );
+}
+
+/**
+ * Shown when a download is in flight but the variant list isn't loaded. Keeps the
+ * live job as source of truth so progress + cancel survive a remount instead of
+ * being replaced by the variant-status card.
+ */
+export function GgufDownloadingFallbackCard({
+  job,
+  progress,
+  cancelling,
+}: {
+  job: DownloadJob;
+  progress: DownloadJobProgress;
+  cancelling: boolean;
+}) {
+  return (
+    <div className="flex w-full flex-col gap-2">
+      <DownloadCard job={job} progress={progress}>
+        <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+          <span className="flex min-w-0 items-center gap-2 text-[12.5px] text-muted-foreground">
+            {progress.variant && <DotTag tone="gguf" label={progress.variant} />}
+            <span className="truncate">Downloading…</span>
+          </span>
+        </div>
+        <CardDivider />
+        <DownloadActionButton
+          downloading
+          cancelling={cancelling}
+          progressPercent={Math.round(Math.min(progress.fraction, 1) * 100)}
+          disabled={cancelling}
+          onClick={() => void job.cancelDownload(progress.variant)}
+        />
+      </DownloadCard>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx b/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
new file mode 100644
index 0000000000..76539d43de
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { cn } from "@/lib/utils";
+import { ArrowDown01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import {
+  type KeyboardEvent,
+  type ReactNode,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+export interface HubOption<T extends string> {
+  value: T;
+  label: ReactNode;
+  triggerLabel?: ReactNode;
+  checkClassName?: string;
+}
+
+export function HubOptionMenu<T extends string>({
+  value,
+  options,
+  onValueChange,
+  className,
+  contentClassName,
+  ariaLabel,
+  align = "start",
+  showChevron = true,
+  title,
+  triggerContent,
+}: {
+  value: T;
+  options: readonly HubOption<T>[];
+  onValueChange: (value: T) => void;
+  className?: string;
+  contentClassName?: string;
+  ariaLabel: string;
+  align?: "start" | "center" | "end";
+  showChevron?: boolean;
+  title?: string;
+  triggerContent?: ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const listboxRef = useRef<HTMLDivElement | null>(null);
+  const idBase = useId();
+  const listboxId = `${idBase}-listbox`;
+
+  const selectedIndex = useMemo(() => {
+    const index = options.findIndex((option) => option.value === value);
+    return index >= 0 ? index : 0;
+  }, [options, value]);
+  const selected = options[selectedIndex];
+  const resolvedActiveIndex =
+    options.length === 0
+      ? -1
+      : Math.min(Math.max(activeIndex, 0), options.length - 1);
+  const activeOptionId =
+    resolvedActiveIndex >= 0 ? `${idBase}-option-${resolvedActiveIndex}` : undefined;
+
+  const activateIndex = useCallback((index: number) => {
+    setActiveIndex((current) => (current === index ? current : index));
+  }, []);
+
+  const closeAndRestoreFocus = useCallback(() => {
+    setOpen(false);
+    requestAnimationFrame(() => triggerRef.current?.focus());
+  }, []);
+
+  const selectIndex = useCallback(
+    (index: number) => {
+      const option = options[index];
+      if (!option) return;
+      onValueChange(option.value);
+      closeAndRestoreFocus();
+    },
+    [closeAndRestoreFocus, onValueChange, options],
+  );
+
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      setOpen(nextOpen);
+      if (nextOpen) {
+        activateIndex(selectedIndex);
+        requestAnimationFrame(() => listboxRef.current?.focus());
+      }
+    },
+    [activateIndex, selectedIndex],
+  );
+
+  const handleContentKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (options.length === 0) return;
+      const currentIndex =
+        resolvedActiveIndex >= 0 ? resolvedActiveIndex : selectedIndex;
+
+      if (event.key === "Escape") {
+        event.preventDefault();
+        closeAndRestoreFocus();
+        return;
+      }
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setActiveIndex((currentIndex + 1) % options.length);
+        return;
+      }
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setActiveIndex((currentIndex - 1 + options.length) % options.length);
+        return;
+      }
+      if (event.key === "Home") {
+        event.preventDefault();
+        setActiveIndex(0);
+        return;
+      }
+      if (event.key === "End") {
+        event.preventDefault();
+        setActiveIndex(options.length - 1);
+        return;
+      }
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        selectIndex(currentIndex);
+      }
+    },
+    [
+      closeAndRestoreFocus,
+      options,
+      resolvedActiveIndex,
+      selectIndex,
+      selectedIndex,
+    ],
+  );
+
+  return (
+    <Popover open={open} onOpenChange={handleOpenChange}>
+      <PopoverTrigger asChild>
+        <button
+          ref={triggerRef}
+          type="button"
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-controls={open ? listboxId : undefined}
+          aria-label={ariaLabel}
+          title={title}
+          className={cn(
+            "field-trigger hub-menu-trigger field-soft field-filter inline-flex h-9 shrink-0 cursor-pointer items-center justify-between gap-2 rounded-full px-3 text-[12.5px] transition-colors",
+            "focus-visible:border-border focus-visible:ring-0 focus-visible:ring-offset-0",
+            className,
+          )}
+          onKeyDown={(event) => {
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+              event.preventDefault();
+              handleOpenChange(true);
+            }
+          }}
+        >
+          <span className="flex min-w-0 items-center gap-2 truncate">
+            {triggerContent ?? selected?.triggerLabel ?? selected?.label ?? value}
+          </span>
+          {showChevron && (
+            <HugeiconsIcon
+              icon={ArrowDown01Icon}
+              strokeWidth={1.5}
+              className="size-3.5 shrink-0 text-muted-foreground"
+            />
+          )}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        align={align}
+        side="bottom"
+        sideOffset={8}
+        collisionPadding={12}
+        onCloseAutoFocus={(event) => event.preventDefault()}
+        className={cn(
+          "hub-menu-instant menu-soft-surface w-max min-w-[var(--radix-popover-trigger-width)] max-w-[min(var(--radix-popover-content-available-width),calc(100vw-1rem))] rounded-[14px] p-1 ring-0",
+          contentClassName,
+        )}
+      >
+        <div
+          ref={listboxRef}
+          id={listboxId}
+          role="listbox"
+          aria-label={ariaLabel}
+          aria-activedescendant={activeOptionId}
+          tabIndex={0}
+          onKeyDown={handleContentKeyDown}
+          className="outline-none"
+        >
+          {options.map((option, index) => {
+            const selectedOption = option.value === value;
+            const activeOption = index === resolvedActiveIndex;
+            return (
+              <div
+                key={option.value}
+                id={`${idBase}-option-${index}`}
+                role="option"
+                aria-selected={selectedOption}
+                data-highlighted={activeOption || undefined}
+                onClick={() => {
+                  selectIndex(index);
+                }}
+                onPointerEnter={() => activateIndex(index)}
+                className={cn(
+                  "relative flex w-full min-w-0 cursor-pointer select-none items-center rounded-xl corner-squircle py-2 pr-8 pl-3 text-left text-sm leading-snug outline-none transition-colors",
+                )}
+              >
+                <span className="flex min-w-0 flex-1 items-center gap-2.5 overflow-hidden whitespace-normal break-words">
+                  {option.label}
+                </span>
+                {selectedOption && (
+                  <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center">
+                    <HugeiconsIcon
+                      icon={Tick02Icon}
+                      strokeWidth={2}
+                      className={cn("size-4", option.checkClassName)}
+                    />
+                  </span>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/local-dataset-card.tsx b/studio/frontend/src/features/hub/catalog/local-dataset-card.tsx
new file mode 100644
index 0000000000..5b9ca6b1de
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/local-dataset-card.tsx
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { TrainIcon } from "@/features/hub/components/train-icon";
+import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "@/features/hub/lib/hub-feature-flags";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { LocalSource } from "../types";
+import { DotTag } from "./dot-tag";
+import { PathInfoButton } from "./path-info-button";
+
+interface LocalDatasetCardProps {
+  sourceLabel: string;
+  source: LocalSource;
+  path: string;
+  onTrain?: () => void;
+}
+
+export function LocalDatasetCard({
+  sourceLabel,
+  source,
+  path,
+  onTrain,
+}: LocalDatasetCardProps) {
+  return (
+    <div className="hub-download-card">
+      <div className="group/dl flex items-center">
+        <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+          <span className="flex min-w-0 items-center gap-1.5 text-[12px] text-muted-foreground">
+            <DotTag tone="success" label="On device" />
+            {source !== "hf_cache" && (
+              <span className="truncate text-muted-foreground/85">
+                {sourceLabel}
+              </span>
+            )}
+          </span>
+          <div className="ml-auto flex items-center gap-0.5">
+            <PathInfoButton
+              path={path}
+              title={sourceLabel}
+              description="Where this dataset lives on disk."
+            />
+          </div>
+        </div>
+        {HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && (
+          <div
+            aria-hidden="true"
+            className="ml-1 mr-0 h-5 w-px shrink-0 bg-foreground/[0.06] opacity-100 transition-opacity duration-150 group-hover/dl:opacity-0 dark:bg-white/[0.04]"
+          />
+        )}
+        {/* Train CTA hidden until Hub->train picker ships. */}
+        {onTrain && HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && (
+          <button
+            type="button"
+            onClick={() => onTrain()}
+            className="hub-action-btn w-28"
+          >
+            <HugeiconsIcon icon={TrainIcon} strokeWidth={1.75} />
+            Train
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
new file mode 100644
index 0000000000..c5e754d982
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
@@ -0,0 +1,545 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { TrainIcon } from "../components/train-icon";
+import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import {
+  type BaseModelSource,
+  type LocalModelInfo,
+  type ModelInventoryFormat,
+  deleteCachedModel,
+} from "../inventory";
+import { formatBytes } from "../lib/format";
+import { ggufVariantsMatch } from "../lib/model-identity";
+import { cn } from "@/lib/utils";
+import { confirmExternalLink } from "../stores/external-link-confirm";
+import { useHfTokenStore } from "../stores/hf-token-store";
+import {
+  Alert02Icon,
+  ArrowDown01Icon,
+  CubeIcon,
+  PencilEdit02Icon,
+  PlayIcon,
+  Share05Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useMemo, useState } from "react";
+import {
+  ggufVariantDisplayLabel,
+  sortLocalGgufVariants,
+} from "../lib/gguf-variant-sort";
+import { DotTag } from "./dot-tag";
+import { CardDeleteButton, DeleteConfirmDialog } from "./download-card";
+import { PathInfoButton } from "./path-info-button";
+import { useCardDelete } from "./use-card-delete";
+import { useGgufVariantFetchState } from "./use-gguf-variant-fetch-state";
+
+type LocalLoadOptions = {
+  ggufVariant?: string;
+  expectedBytes?: number;
+};
+
+interface LocalOnDeviceCardProps {
+  modelId: string;
+  repoId: string | null;
+  sourceLabel: string;
+  source: LocalModelInfo["source"];
+  path: string;
+  isGguf: boolean;
+  requiresVariant?: boolean;
+  modelFormat: ModelInventoryFormat | null;
+  baseModel?: string | null;
+  baseModelSource?: BaseModelSource | null;
+  baseModelHubId?: string | null;
+  baseModelSummary?: string | null;
+  adapterType?: string | null;
+  trainingMethod?: string | null;
+  canRun?: boolean;
+  isActive: boolean;
+  activeGgufVariant?: string | null;
+  isLoading: boolean;
+  loadingPhase?: "downloading" | "starting";
+  gpuGb?: number;
+  systemRamGb?: number;
+  unsupportedReason?: string | null;
+  onLoad: (opts?: LocalLoadOptions) => void;
+  onUseInChat: () => void;
+  onTrain?: () => void;
+  onChange?: () => void;
+}
+
+function formatAdapterLabel(
+  adapterType?: string | null,
+  trainingMethod?: string | null,
+): string {
+  const method = trainingMethod?.trim().toLowerCase();
+  if (method === "qlora") return "QLoRA adapter";
+  if (method === "lora") return "LoRA adapter";
+  const type = adapterType?.trim();
+  return type ? `${type.toUpperCase()} adapter` : "Adapter";
+}
+
+function baseModelSourceLabel(source?: BaseModelSource | null): string {
+  if (source === "huggingface") return "Hugging Face base model";
+  if (source === "local") return "Local base model";
+  return "Base model";
+}
+
+function BaseModelReference({
+  baseModel,
+  baseModelSource,
+  baseModelHubId,
+  baseModelSummary,
+}: {
+  baseModel: string;
+  baseModelSource?: BaseModelSource | null;
+  baseModelHubId?: string | null;
+  baseModelSummary?: string | null;
+}) {
+  const canOpenHub = baseModelSource === "huggingface" && !!baseModelHubId;
+  return (
+    <div className="flex min-w-0 items-center gap-2 rounded-[10px] border border-border/55 bg-muted/35 px-3 py-2">
+      <div className="flex size-7 shrink-0 items-center justify-center rounded-[8px] bg-background/70 text-muted-foreground">
+        <HugeiconsIcon
+          icon={CubeIcon}
+          strokeWidth={1.75}
+          className="size-3.5"
+        />
+      </div>
+      <div className="min-w-0 flex-1">
+        <div className="flex min-w-0 items-center gap-1.5">
+          <span className="shrink-0 text-[11px] font-medium text-muted-foreground">
+            {baseModelSourceLabel(baseModelSource)}
+          </span>
+          <span className="truncate text-[12px] font-medium text-foreground">
+            {baseModel}
+          </span>
+        </div>
+        {baseModelSummary && (
+          <p className="mt-0.5 truncate text-[11px] text-muted-foreground">
+            {baseModelSummary}
+          </p>
+        )}
+      </div>
+      {canOpenHub && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <a
+              href={`https://huggingface.co/${baseModelHubId}`}
+              target="_blank"
+              rel="noopener noreferrer"
+              aria-label={`Open ${baseModelHubId} on Hugging Face`}
+              className="inline-flex size-7 shrink-0 items-center justify-center rounded-[8px] text-muted-foreground transition-colors hover:bg-background hover:text-foreground"
+              onClick={(event) => {
+                event.stopPropagation();
+                if (confirmExternalLink(`https://huggingface.co/${baseModelHubId}`)) {
+                  event.preventDefault();
+                }
+              }}
+            >
+              <HugeiconsIcon
+                icon={Share05Icon}
+                strokeWidth={1.75}
+                className="size-3.5"
+              />
+            </a>
+          </TooltipTrigger>
+          <TooltipContent side="top" sideOffset={4}>
+            Open base model
+          </TooltipContent>
+        </Tooltip>
+      )}
+    </div>
+  );
+}
+
+export function LocalOnDeviceCard({
+  modelId,
+  repoId,
+  sourceLabel,
+  source,
+  path,
+  isGguf,
+  requiresVariant = false,
+  modelFormat,
+  baseModel,
+  baseModelSource,
+  baseModelHubId,
+  baseModelSummary,
+  adapterType,
+  trainingMethod,
+  canRun = true,
+  isActive,
+  activeGgufVariant = null,
+  isLoading,
+  loadingPhase,
+  gpuGb,
+  systemRamGb,
+  unsupportedReason,
+  onLoad,
+  onUseInChat,
+  onTrain,
+  onChange,
+}: LocalOnDeviceCardProps) {
+  const [deleteOpen, setDeleteOpen] = useState(false);
+  const [variantOpen, setVariantOpen] = useState(false);
+  const hfToken = useHfTokenStore((s) => s.token);
+  const { deleting, runDelete } = useCardDelete({
+    action: async () => {
+      if (!repoId) return;
+      await deleteCachedModel(repoId, undefined, hfToken || undefined);
+    },
+    resourceName: "model",
+    successMessage: () => `Deleted ${repoId}`,
+    onSuccess: () => {
+      setDeleteOpen(false);
+      onChange?.();
+    },
+  });
+  const localGgufPath = path.trim();
+  const needsVariantSelection =
+    isGguf && requiresVariant && !localGgufPath.toLowerCase().endsWith(".gguf");
+  const currentVariantState = useGgufVariantFetchState({
+    repoId: modelId,
+    hfToken,
+    preferLocalCache: true,
+    localPath: localGgufPath,
+    enabled: needsVariantSelection,
+    errorFallback: "Failed to load quantizations",
+  });
+  const variantKey = currentVariantState.key;
+  const [selectedVariantState, setSelectedVariantState] = useState<{
+    key: string;
+    quant: string | null;
+  }>(() => ({
+    key: variantKey,
+    quant: null,
+  }));
+
+  const canDelete =
+    source === "hf_cache" && !!repoId && !isActive && !isLoading;
+  const variants = currentVariantState.variants;
+  const sortedVariants = useMemo(
+    () =>
+      variants
+        ? sortLocalGgufVariants(variants, {
+            defaultVariant: currentVariantState.defaultVariant,
+            activeGgufVariant: isActive ? activeGgufVariant : null,
+            gpuGb,
+            systemRamGb,
+          })
+        : null,
+    [
+      variants,
+      currentVariantState.defaultVariant,
+      isActive,
+      activeGgufVariant,
+      gpuGb,
+      systemRamGb,
+    ],
+  );
+  const selectedVariantOverride =
+    selectedVariantState.key === variantKey ? selectedVariantState.quant : null;
+  const selectedQuant =
+    selectedVariantOverride &&
+    sortedVariants?.some((variant) =>
+      ggufVariantsMatch(variant.quant, selectedVariantOverride),
+    )
+      ? selectedVariantOverride
+      : (sortedVariants?.find(
+          (variant) =>
+            isActive && ggufVariantsMatch(variant.quant, activeGgufVariant),
+        )?.quant ??
+        sortedVariants?.find((variant) =>
+          ggufVariantsMatch(variant.quant, currentVariantState.defaultVariant),
+        )?.quant ??
+        sortedVariants?.[0]?.quant ??
+        null);
+  const selectedVariant =
+    sortedVariants?.find((variant) =>
+      ggufVariantsMatch(variant.quant, selectedQuant),
+    ) ?? null;
+  const selectedVariantIsActive =
+    needsVariantSelection && selectedQuant
+      ? isActive && ggufVariantsMatch(activeGgufVariant, selectedQuant)
+      : isActive;
+  const variantUnavailable =
+    needsVariantSelection &&
+    (currentVariantState.loading ||
+      currentVariantState.error !== null ||
+      selectedVariant === null);
+  const variantActionPending =
+    needsVariantSelection && currentVariantState.loading;
+
+  const formatLabel =
+    modelFormat === "gguf"
+      ? "GGUF"
+      : modelFormat === "adapter"
+        ? formatAdapterLabel(adapterType, trainingMethod)
+        : modelFormat === "checkpoint"
+          ? "Checkpoint"
+          : modelFormat === "safetensors"
+            ? "Safetensors"
+            : "Model";
+  const formatTone =
+    modelFormat === "adapter" ? "adapter" : isGguf ? "gguf" : "checkpoint";
+  const showOldCacheHint = source === "hf_cache" && !!unsupportedReason;
+
+  return (
+    <div className="flex w-full flex-col gap-2">
+      {showOldCacheHint && (
+        <div className="flex items-start gap-2 rounded-[12px] border border-amber-500/20 bg-amber-500/8 px-3 py-2 text-[12px] leading-5 text-amber-700 dark:text-amber-300">
+          <HugeiconsIcon
+            icon={Alert02Icon}
+            strokeWidth={1.75}
+            className="mt-[1px] size-3.5 shrink-0"
+          />
+          <span>
+            This looks like an older Hub cache. It may use a format that Unsloth
+            no longer loads (missing config or unsupported quantization). You
+            can still keep it on disk, or delete it to free space.
+          </span>
+        </div>
+      )}<div className="hub-download-card">
+        <div className="group/dl flex items-center">
+          <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+            <span className="flex min-w-0 items-center gap-1.5 text-[12px] text-muted-foreground">
+              <DotTag
+                tone="success"
+                label={selectedVariantIsActive ? "Loaded" : "On device"}
+              />
+              <DotTag tone={formatTone} label={formatLabel} />
+              {needsVariantSelection && (
+                <Popover open={variantOpen} onOpenChange={setVariantOpen}>
+                  <PopoverTrigger asChild={true}>
+                    <button
+                      type="button"
+                      disabled={currentVariantState.loading}
+                      className="inline-flex h-6 max-w-[170px] shrink-0 cursor-pointer items-center gap-1.5 rounded-[8px] border border-format-gguf/35 px-2 font-mono text-[10.5px] leading-none text-format-gguf transition-colors hover:bg-format-gguf/8 disabled:cursor-not-allowed disabled:opacity-60"
+                    >
+                      <span className="truncate">
+                        {currentVariantState.loading
+                          ? "Loading"
+                          : currentVariantState.error
+                            ? "Unavailable"
+                            : selectedVariant
+                              ? ggufVariantDisplayLabel(selectedVariant)
+                              : "Select"}
+                      </span>
+                      {selectedVariant && (
+                        <span className="shrink-0 font-sans text-[10px] text-muted-foreground tabular-nums">
+                          {formatBytes(selectedVariant.size_bytes)}
+                        </span>
+                      )}
+                      <HugeiconsIcon
+                        icon={ArrowDown01Icon}
+                        strokeWidth={1.5}
+                        className="size-3 shrink-0"
+                      />
+                    </button>
+                  </PopoverTrigger>
+                  <PopoverContent
+                    align="start"
+                    side="bottom"
+                    sideOffset={8}
+                    avoidCollisions={false}
+                    className="hub-menu-instant menu-soft-surface w-[var(--radix-popover-trigger-width)] min-w-[220px] gap-0 overflow-hidden p-0 py-2 ring-0"
+                  >
+                    <div className="max-h-[280px] overflow-y-auto [scrollbar-width:thin]">
+                      {sortedVariants?.map((variant) => {
+                        const label = ggufVariantDisplayLabel(variant);
+                        const isSelected = ggufVariantsMatch(
+                          variant.quant,
+                          selectedQuant,
+                        );
+                        const isLoaded =
+                          ggufVariantsMatch(variant.quant, activeGgufVariant) &&
+                          isActive;
+                        return (
+                          <button
+                            key={variant.filename}
+                            type="button"
+                            onClick={() => {
+                              setSelectedVariantState({
+                                key: variantKey,
+                                quant: variant.quant,
+                              });
+                              setVariantOpen(false);
+                            }}
+                            className={cn(
+                              "mx-2 flex w-[calc(100%-1rem)] min-w-0 cursor-pointer items-center gap-2 rounded-[10px] px-2.5 py-2 text-left transition-colors",
+                              isSelected
+                                ? "bg-foreground/[0.07] dark:bg-foreground/[0.12]"
+                                : "hover:bg-foreground/[0.05] dark:hover:bg-foreground/[0.06]",
+                            )}
+                          >
+                            <span className="min-w-0 flex-1 truncate font-mono text-[12px] text-format-gguf">
+                              {label}
+                            </span>
+                            <span className="flex shrink-0 items-center gap-1.5">
+                              {isLoaded && (
+                                <DotTag tone="success" label="Loaded" />
+                              )}
+                              <span className="text-[10px] text-muted-foreground tabular-nums">
+                                {formatBytes(variant.size_bytes)}
+                              </span>
+                            </span>
+                          </button>
+                        );
+                      })}
+                      {!currentVariantState.loading &&
+                        !currentVariantState.error &&
+                        sortedVariants?.length === 0 && (
+                          <div className="px-4 py-2 text-xs text-muted-foreground">
+                            No quantizations found.
+                          </div>
+                        )}
+                      {currentVariantState.error && (
+                        <div className="px-4 py-2 text-xs text-destructive">
+                          {currentVariantState.error}
+                        </div>
+                      )}
+                    </div>
+                  </PopoverContent>
+                </Popover>
+              )}
+              {source !== "hf_cache" && (
+                <span className="truncate text-muted-foreground/85">
+                  {sourceLabel}
+                </span>
+              )}
+            </span>
+            <div className="ml-auto flex items-center gap-0.5">
+              {canDelete && (
+                <CardDeleteButton
+                  label={`Delete ${repoId}`}
+                  onClick={() => setDeleteOpen(true)}
+                />
+              )}
+              <PathInfoButton
+                path={path}
+                title={sourceLabel}
+                description="Where this model lives on disk."
+              />
+            </div>
+          </div>
+          {onTrain && HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && (
+            <div
+              aria-hidden="true"
+              className="ml-1 mr-0 h-5 w-px shrink-0 bg-foreground/[0.06] opacity-100 transition-opacity duration-150 group-hover/dl:opacity-0 dark:bg-white/[0.04]"
+            />
+          )}
+          {/* Run + Train pair hidden until Hub->chat/train pickers ship. */}
+          <div
+            className={cn(
+              "group/pair flex h-9 shrink-0 items-stretch gap-1.5",
+              !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && "hidden",
+            )}
+          >
+            {onTrain && (
+              <button
+                type="button"
+                onClick={() => onTrain()}
+                className="hub-action-btn w-24"
+              >
+                <HugeiconsIcon icon={TrainIcon} strokeWidth={1.75} />
+                Train
+              </button>
+            )}
+            <button
+              type="button"
+              disabled={isLoading || variantUnavailable || !canRun}
+              onClick={() => {
+                if (!canRun) return;
+                if (selectedVariantIsActive) {
+                  onUseInChat();
+                  return;
+                }
+                if (needsVariantSelection) {
+                  if (!selectedVariant) return;
+                  onLoad({
+                    ggufVariant: selectedVariant.quant,
+                    expectedBytes: selectedVariant.size_bytes,
+                  });
+                  return;
+                }
+                onLoad();
+              }}
+              className={cn(
+                isLoading ||
+                  selectedVariantIsActive ||
+                  variantUnavailable ||
+                  !canRun
+                  ? "hub-action-btn w-24"
+                  : "hub-run-action-btn w-24",
+                (isLoading || variantUnavailable || !canRun) && "opacity-70",
+              )}
+            >
+              {isLoading ? (
+                <>
+                  <Spinner />
+                  {loadingPhase === "downloading" ? "Preparing…" : "Loading…"}
+                </>
+              ) : selectedVariantIsActive ? (
+                <>
+                  <HugeiconsIcon icon={PencilEdit02Icon} strokeWidth={1.75} />
+                  Chat
+                </>
+              ) : variantActionPending ? (
+                <>
+                  <Spinner />
+                  Loading…
+                </>
+              ) : !canRun ? (
+                <>
+                  <HugeiconsIcon icon={Alert02Icon} strokeWidth={1.75} />
+                  No run
+                </>
+              ) : (
+                <>
+                  <HugeiconsIcon icon={PlayIcon} strokeWidth={1.75} />
+                  Run
+                </>
+              )}
+            </button>
+          </div>
+        </div>
+      </div>
+      {baseModel && (
+        <BaseModelReference
+          baseModel={baseModel}
+          baseModelSource={baseModelSource}
+          baseModelHubId={baseModelHubId}
+          baseModelSummary={baseModelSummary}
+        />
+      )}
+      <DeleteConfirmDialog
+        open={deleteOpen}
+        onOpenChange={(o) => {
+          if (!o && !deleting) setDeleteOpen(false);
+        }}
+        title="Delete cached model?"
+        deleting={deleting}
+        onConfirm={() => void runDelete()}
+        description={
+          <>
+            This will remove{" "}
+            <span className="font-medium text-foreground">{repoId}</span> and
+            its downloaded files from disk. You can re-download it later.
+          </>
+        }
+      />
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/model-inspector.tsx b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
new file mode 100644
index 0000000000..54165aa5e6
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
@@ -0,0 +1,732 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { usePlatformStore } from "@/config/env";
+import {
+  type UnslothSupport,
+  classifyUnslothSupport,
+} from "@/features/hub/hooks/use-hub-model-search";
+import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
+import { formatBytes, formatRelativeShort } from "@/features/hub/lib/format";
+import { cn, formatCompact } from "@/lib/utils";
+import { confirmExternalLink } from "../stores/external-link-confirm";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import {
+  Calendar03Icon,
+  Copy01Icon,
+  CpuIcon,
+  CubeIcon,
+  Database02Icon,
+  Download01Icon,
+  FavouriteIcon,
+  Globe02Icon,
+  LayersLogoIcon,
+  LicenseIcon,
+  PackageIcon,
+  RamMemoryIcon,
+  Share05Icon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import {
+  memo,
+  useDeferredValue,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useCopyFeedback } from "../hooks/use-copy-feedback";
+import { useDatasetSize } from "../hooks/use-dataset-size";
+import {
+  formatLocalUpdated,
+  formatPipelineTag,
+  parseLanguageTags,
+} from "../lib/view-models";
+import type { SelectedModelView } from "../types";
+import {
+  selectActiveJob,
+  useDownloadManagerStore,
+} from "../download-manager";
+import { DatasetDownloadSection } from "./dataset-download-section";
+import { DownloadSection } from "./download-section";
+import { LocalDatasetCard } from "./local-dataset-card";
+import { LocalOnDeviceCard } from "./local-on-device-card";
+import { ModelReadme } from "./model-readme";
+import { OwnerAvatar } from "./owner-avatar";
+import { CapabilityPill } from "./shared";
+
+function ViewRepositoryButton({
+  repoId,
+  isDataset,
+}: {
+  repoId: string;
+  isDataset: boolean;
+}) {
+  const online = useOnlineStatus();
+  const url = `https://huggingface.co/${isDataset ? "datasets/" : ""}${repoId}`;
+  const baseClass =
+    "inline-flex size-7 shrink-0 items-center justify-center rounded-[8px] text-muted-foreground transition-colors";
+  const icon = (
+    <HugeiconsIcon icon={Share05Icon} strokeWidth={1.75} className="size-4" />
+  );
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild={true}>
+        {online ? (
+          <a
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            aria-label="View repository"
+            className={cn(baseClass, "hover:bg-muted hover:text-foreground")}
+            onClick={(event) => {
+              event.stopPropagation();
+              if (confirmExternalLink(url)) {
+                event.preventDefault();
+              }
+            }}
+          >
+            {icon}
+          </a>
+        ) : (
+          <span
+            aria-label="View repository unavailable offline"
+            aria-disabled="true"
+            className={cn(baseClass, "cursor-not-allowed opacity-45")}
+          >
+            {icon}
+          </span>
+        )}
+      </TooltipTrigger>
+      <TooltipContent side="bottom" className="tooltip-compact">
+        {online ? "Open on Hugging Face" : "Unavailable offline"}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function CopyRepoButton({ repoId }: { repoId: string }) {
+  const { copied, copy } = useCopyFeedback();
+
+  const handleCopy = async (event: React.MouseEvent<HTMLButtonElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
+    await copy(repoId);
+  };
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild={true}>
+        <button
+          type="button"
+          aria-label="Copy repository ID"
+          onClick={handleCopy}
+          className="inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-[8px] text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        >
+          <HugeiconsIcon
+            icon={copied ? Tick02Icon : Copy01Icon}
+            strokeWidth={1.75}
+            className="size-4"
+          />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" className="tooltip-compact">
+        {repoId}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function StatRow({
+  label,
+  value,
+  icon,
+}: {
+  label: string;
+  value: string;
+  icon: IconSvgElement;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild={true}>
+        <span className="hub-tag-meta inline-flex cursor-default items-center gap-1.5 px-2.5 py-1 text-[11.5px] text-muted-foreground transition-colors hover:text-foreground/80">
+          <HugeiconsIcon
+            icon={icon}
+            strokeWidth={1.75}
+            className="size-3.5 shrink-0"
+          />
+          <span className="font-medium tabular-nums">{value}</span>
+        </span>
+      </TooltipTrigger>
+      <TooltipContent className="tooltip-compact">{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+function StatGrid({ children }: { children: React.ReactNode }) {
+  return <div className="flex flex-wrap items-center gap-1.5">{children}</div>;
+}
+
+function InspectorDownloadSlot({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="shrink-0 pl-6 pr-10 pt-3 sm:pr-14 lg:pr-[4.5rem] xl:pr-[5.5rem]">
+      {children}
+    </div>
+  );
+}
+
+function StatusChip({
+  tone,
+  label,
+  className,
+}: {
+  tone: "success" | "warning" | "danger";
+  label: string;
+  className?: string;
+}) {
+  const toneClass =
+    tone === "danger"
+      ? "border-red-500/35 text-red-700 dark:border-red-400/40 dark:text-red-300"
+      : tone === "warning"
+        ? "border-amber-500/40 text-amber-700 dark:border-amber-400/45 dark:text-amber-300"
+        : "border-emerald-500/40 text-emerald-700 dark:border-emerald-400/45 dark:text-emerald-300";
+  return (
+    <span
+      className={cn(
+        "inline-flex h-5 shrink-0 items-center whitespace-nowrap rounded-[7px] border bg-transparent px-1.5 text-[11px] font-medium leading-none",
+        toneClass,
+        className,
+      )}
+    >
+      {label}
+    </span>
+  );
+}
+
+type VramInfo = { est: number; status: "fits" | "tight" | "exceeds" } | null;
+
+function ModelStatusChips({
+  isDataset,
+  isGguf,
+  unslothSupport,
+  vramInfo,
+}: {
+  isDataset: boolean;
+  isGguf: boolean;
+  unslothSupport: UnslothSupport;
+  vramInfo: VramInfo;
+}) {
+  const showUnsupported = !isDataset && unslothSupport.status === "unsupported";
+  const showVram = !isDataset && vramInfo && !isGguf;
+  if (!showUnsupported && !showVram) return null;
+
+  const vramTone = vramInfo
+    ? vramInfo.status === "exceeds"
+      ? "danger"
+      : vramInfo.status === "tight"
+        ? "warning"
+        : "success"
+    : "success";
+  const vramLabel = vramInfo
+    ? vramInfo.status === "exceeds"
+      ? `Over VRAM budget · ~${vramInfo.est} GB`
+      : vramInfo.status === "tight"
+        ? `Tight fit · ~${vramInfo.est} GB`
+        : `Likely fits · ~${vramInfo.est} GB`
+    : "";
+  const vramDetail = vramInfo
+    ? vramInfo.status === "exceeds"
+      ? "A 4-bit load is likely to exceed the current GPU budget. Higher-precision loads need even more."
+      : vramInfo.status === "tight"
+        ? "A 4-bit load should fit, with limited headroom for context and activations."
+        : "A 4-bit load should fit comfortably on the current GPU."
+    : "";
+
+  return (
+    <div className="mt-3 flex flex-wrap items-center gap-1.5">
+      {showUnsupported && (
+        <Tooltip>
+          <TooltipTrigger asChild={true}>
+            <span tabIndex={0} className="inline-flex outline-none">
+              <StatusChip tone="danger" label="May not be supported" />
+            </span>
+          </TooltipTrigger>
+          <TooltipContent
+            side="bottom"
+            sideOffset={6}
+            className="tooltip-compact max-w-xs"
+          >
+            This model may not be supported yet.
+            {unslothSupport.reason && (
+              <span className="mt-1 block text-[10.5px] font-normal text-white/75">
+                {unslothSupport.reason}
+              </span>
+            )}
+            <span className="mt-1 block text-[10.5px] font-normal text-white/75">
+              Still downloadable to your Hugging Face cache, shared with every
+              framework that reads it.
+            </span>
+          </TooltipContent>
+        </Tooltip>
+      )}
+      {showVram && vramInfo && (
+        <Tooltip>
+          <TooltipTrigger asChild={true}>
+            <span tabIndex={0} className="inline-flex outline-none">
+              <StatusChip tone={vramTone} label={vramLabel} />
+            </span>
+          </TooltipTrigger>
+          <TooltipContent
+            side="bottom"
+            sideOffset={6}
+            className="tooltip-compact max-w-xs"
+          >
+            Estimated 4-bit memory load is around {vramInfo.est} GB.
+            <span className="mt-1 block text-[10.5px] font-normal text-white/75">
+              {vramDetail}
+            </span>
+          </TooltipContent>
+        </Tooltip>
+      )}
+    </div>
+  );
+}
+
+export type ModelInspectorRuntime = {
+  isActive: boolean;
+  activeGgufVariant: string | null;
+  isLoadingThisModel: boolean;
+  loadingPhase?: "downloading" | "starting";
+  minMemory: string | null;
+  vramInfo: {
+    est: number;
+    status: "fits" | "tight" | "exceeds";
+  } | null;
+  gpuGb?: number;
+  systemRamGb?: number;
+};
+
+export type ModelInspectorActions = {
+  onLoad: (opts: { ggufVariant?: string; expectedBytes?: number }) => void;
+  onLoadLocal: (opts?: {
+    ggufVariant?: string;
+    expectedBytes?: number;
+  }) => void;
+  onUseInChat: () => void;
+  onTrain?: () => void;
+  onInventoryChange?: () => void;
+};
+
+export const ModelInspector = memo(function ModelInspector({
+  model,
+  runtime,
+  actions,
+  isDataset = false,
+  metadataUnavailable = false,
+  selectionHiddenByFilters = false,
+}: {
+  model: SelectedModelView | null;
+  isDataset?: boolean;
+  metadataUnavailable?: boolean;
+  selectionHiddenByFilters?: boolean;
+  runtime: ModelInspectorRuntime;
+  actions: ModelInspectorActions;
+}) {
+  const {
+    isActive,
+    activeGgufVariant,
+    isLoadingThisModel,
+    loadingPhase,
+    minMemory,
+    vramInfo,
+    gpuGb,
+    systemRamGb,
+  } = runtime;
+  const { onLoad, onLoadLocal, onUseInChat, onTrain, onInventoryChange } =
+    actions;
+  const deviceType = usePlatformStore((s) => s.deviceType);
+  const hfToken = useHfTokenStore((s) => s.token);
+  const datasetRepoId = isDataset && model?.hubRepoId ? model.hubRepoId : null;
+  const datasetSize = useDatasetSize(datasetRepoId, {
+    token: hfToken || undefined,
+  });
+  // Inventory rows are snapshots; the download manager is the live source of truth.
+  // When a download is in flight, route through the download-aware section so
+  // progress/cancel stays visible across refreshes.
+  const activeDownloadRepoId = model?.hubRepoId ?? null;
+  const hasActiveHubDownload = useDownloadManagerStore((state) =>
+    activeDownloadRepoId
+      ? selectActiveJob(
+          state,
+          isDataset ? "dataset" : "model",
+          activeDownloadRepoId,
+        ) !== null
+      : false,
+  );
+  const readmeRepoId =
+    model?.hubRepoId ?? (isDataset ? null : (model?.baseModelHubId ?? null));
+  const readmeSubject = isDataset
+    ? "dataset"
+    : model?.hubRepoId
+      ? "model"
+      : "baseModel";
+  const supportModelId =
+    model?.hubRepoId ??
+    model?.baseModelHubId ??
+    (model?.baseModelSource === "huggingface" ? model.baseModel : null);
+  const supportPipelineTag = model?.pipelineTag;
+  const supportTagsKey = model?.tags?.join("\0") ?? "";
+  const supportLibraryName = model?.libraryName;
+  const supportQuantMethod = model?.quantMethod;
+  const unslothSupport = useMemo<UnslothSupport>(() => {
+    return classifyUnslothSupport({
+      modelId: supportModelId,
+      pipelineTag: supportPipelineTag,
+      tags: supportTagsKey ? supportTagsKey.split("\0") : undefined,
+      libraryName: supportLibraryName,
+      deviceType,
+      quantMethod: supportQuantMethod,
+    });
+  }, [
+    deviceType,
+    supportLibraryName,
+    supportModelId,
+    supportPipelineTag,
+    supportQuantMethod,
+    supportTagsKey,
+  ]);
+
+  const descScrollRef = useRef<HTMLDivElement | null>(null);
+  const descScrollKey = `${model?.id ?? ""}\0${readmeRepoId ?? ""}`;
+  const deferredReadmeRepoId = useDeferredValue(readmeRepoId);
+  const readmeReady = deferredReadmeRepoId === readmeRepoId;
+  const [descScrollState, setDescScrollState] = useState({
+    key: descScrollKey,
+    scrolled: false,
+  });
+  const descScrolled =
+    descScrollState.key === descScrollKey && descScrollState.scrolled;
+  useEffect(() => {
+    const el = descScrollRef.current;
+    if (!el) return;
+    el.scrollTop = 0;
+    const onScroll = () => {
+      const scrolled = el.scrollTop > 0;
+      setDescScrollState((current) =>
+        current.key === descScrollKey && current.scrolled === scrolled
+          ? current
+          : { key: descScrollKey, scrolled },
+      );
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [descScrollKey]);
+
+  if (!model) {
+    return (
+      <div className="flex h-full min-h-0 flex-1 flex-col items-center justify-center gap-3 px-6 py-10 text-center">
+        <div className="inline-flex size-12 items-center justify-center rounded-[14px] bg-muted text-muted-foreground">
+          <HugeiconsIcon icon={CubeIcon} strokeWidth={1.5} className="size-5" />
+        </div>
+        <div className="space-y-1">
+          <p className="text-[15px] font-semibold tracking-tight text-foreground">
+            Select a {isDataset ? "dataset" : "model"}
+          </p>
+          <p className="max-w-sm text-[12.5px] leading-5 text-muted-foreground">
+            {isDataset
+              ? "Choose a dataset from the catalog to inspect its download state and details."
+              : "Choose an item from the catalog to inspect its runtime fit, download state, and model card."}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const updatedRaw = model.updatedAt
+    ? formatRelativeShort(model.updatedAt)
+    : formatLocalUpdated(model.localUpdatedAt);
+  const updatedLabel = updatedRaw === "Unknown update" ? "N/A" : updatedRaw;
+  const taskLabel = formatPipelineTag(model.pipelineTag) ?? "General";
+  const licenseLabel = model.license ?? "N/A";
+  const paramsLabel = model.totalParams
+    ? formatCompact(model.totalParams)
+    : "N/A";
+  const trainingSupported = unslothSupport.status !== "unsupported";
+  const canRunModel =
+    !isDataset && (model.runtimeCapabilities?.canChat ?? true);
+  const canTrainModel =
+    !isDataset &&
+    (model.runtimeCapabilities?.canTrain ?? false) &&
+    model.modelFormat !== "gguf" &&
+    model.modelFormat !== "adapter" &&
+    trainingSupported;
+
+  const languages = parseLanguageTags(model.tags);
+  const datasetSizeBytes =
+    datasetSize?.numBytesParquet ?? datasetSize?.numBytesOriginal ?? null;
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col">
+      <div className="shrink-0 px-6 pb-2 pt-0">
+        <div className="flex items-center gap-3.5">
+          <OwnerAvatar
+            owner={model.owner}
+            repoName={model.title}
+            className="size-[52px] rounded-[14px] text-[16px]"
+          />
+          <div className="min-w-0 flex-1">
+            <div className="flex min-w-0 items-center gap-1.5">
+              <h2 className="truncate text-[22px] font-semibold leading-[28px] tracking-[-0.025em] text-foreground">
+                {model.title}
+              </h2>
+              {model.hubRepoId && (
+                <div className="flex shrink-0 items-center gap-0.5">
+                  <CopyRepoButton repoId={model.hubRepoId} />
+                  <ViewRepositoryButton
+                    repoId={model.hubRepoId}
+                    isDataset={isDataset}
+                  />
+                </div>
+              )}
+            </div>
+            <div className="mt-0.5 flex min-w-0 items-center gap-1 text-[14px] leading-[22px] text-muted-foreground">
+              <span className="truncate">{model.owner}</span>
+              {model.owner.toLowerCase() === "unsloth" && (
+                <span
+                  aria-label="Verified Unsloth"
+                  className="hub-verified-badge size-4 shrink-0 text-primary"
+                />
+              )}
+            </div>
+          </div>
+        </div>
+
+        <div className="mt-4 flex flex-wrap items-center gap-1.5">
+          {isDataset && (
+            <span className="inline-flex shrink-0 items-center rounded-full border border-violet-500/40 bg-transparent px-2 py-0.5 text-[11.5px] font-medium text-violet-600 dark:text-violet-400">
+              Dataset
+            </span>
+          )}
+          {!isDataset && (
+            <span className="inline-flex h-6 items-center gap-1.5 rounded-full bg-muted px-2.5 text-[11.5px] font-medium text-foreground dark:bg-[rgba(255,255,255,0.04)]">
+              <HugeiconsIcon
+                icon={CubeIcon}
+                strokeWidth={1.75}
+                className="size-3 text-muted-foreground"
+              />
+              {taskLabel}
+            </span>
+          )}
+          {model.capabilities.map((capability) => (
+            <CapabilityPill key={capability.key} capability={capability} />
+          ))}
+        </div>
+      </div>
+
+      {isDataset &&
+        model.hubRepoId &&
+        (!model.isLocal || hasActiveHubDownload) && (
+          <InspectorDownloadSlot>
+            <DatasetDownloadSection
+              repoId={model.hubRepoId}
+              isDownloaded={model.isDownloaded}
+              isPartial={model.isPartial ?? false}
+              partialTransport={model.partialTransport ?? null}
+              cachePath={model.path}
+              knownBytes={model.cachedBytes}
+              onTrain={onTrain}
+              onChange={onInventoryChange}
+            />
+          </InspectorDownloadSlot>
+        )}
+      {isDataset && model.isLocal && !hasActiveHubDownload && model.path && (
+        <InspectorDownloadSlot>
+          <LocalDatasetCard
+            sourceLabel={model.sourceLabel}
+            source={model.localSource ?? "custom"}
+            path={model.path}
+            onTrain={onTrain}
+          />
+        </InspectorDownloadSlot>
+      )}
+      {!isDataset && (
+        <InspectorDownloadSlot>
+          {model.isLocal && !hasActiveHubDownload ? (
+            <LocalOnDeviceCard
+              modelId={model.id}
+              repoId={model.hubRepoId}
+              sourceLabel={model.sourceLabel}
+              source={model.localSource ?? "custom"}
+              path={model.path ?? model.displayId}
+              isGguf={model.isGguf}
+              requiresVariant={model.requiresVariant}
+              modelFormat={model.modelFormat}
+              baseModel={model.baseModel}
+              baseModelSource={model.baseModelSource}
+              baseModelHubId={model.baseModelHubId}
+              baseModelSummary={model.baseModelSummary}
+              adapterType={model.adapterType}
+              trainingMethod={model.trainingMethod}
+              canRun={canRunModel}
+              isActive={isActive}
+              activeGgufVariant={activeGgufVariant}
+              isLoading={isLoadingThisModel}
+              loadingPhase={loadingPhase}
+              gpuGb={gpuGb}
+              systemRamGb={systemRamGb}
+              unsupportedReason={
+                unslothSupport.status === "unsupported"
+                  ? (unslothSupport.reason ?? "Unsupported format")
+                  : null
+              }
+              onLoad={onLoadLocal}
+              onUseInChat={onUseInChat}
+              onTrain={
+                model.isDownloaded && canTrainModel ? onTrain : undefined
+              }
+              onChange={onInventoryChange}
+            />
+          ) : (
+            <DownloadSection
+              repoId={model.isLocal ? (model.hubRepoId ?? model.id) : model.id}
+              isGguf={model.isGguf}
+              isDownloaded={model.isDownloaded}
+              isPartial={model.isPartial ?? false}
+              partialTransport={model.partialTransport ?? null}
+              modelFormat={model.modelFormat}
+              canRun={canRunModel}
+              isActive={isActive}
+              activeQuant={isActive ? (activeGgufVariant ?? null) : null}
+              isLoadingThisModel={isLoadingThisModel}
+              gpuGb={gpuGb}
+              systemRamGb={systemRamGb}
+              cachePath={model.path}
+              knownBytes={model.cachedBytes}
+              onLoad={model.isLocal ? onLoadLocal : onLoad}
+              onUseInChat={onUseInChat}
+              onTrain={
+                model.isDownloaded && canTrainModel ? onTrain : undefined
+              }
+              onChange={onInventoryChange}
+            />
+          )}
+        </InspectorDownloadSlot>
+      )}
+
+      <div className="shrink-0 px-6 pb-5 pt-5">
+        {selectionHiddenByFilters && (
+          <p className="mb-3 rounded-[8px] border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-[11.5px] leading-snug text-muted-foreground">
+            Current selection is hidden by the active filters or search.
+          </p>
+        )}
+        {metadataUnavailable && (
+          <p className="mb-3 text-[11.5px] leading-snug text-muted-foreground">
+            Couldn't load full details from Hugging Face. Some fields may be
+            incomplete.
+          </p>
+        )}
+        <StatGrid>
+          <StatRow label="Updated" value={updatedLabel} icon={Calendar03Icon} />
+          <StatRow
+            label="Downloads"
+            value={
+              model.downloads !== undefined
+                ? formatCompact(model.downloads)
+                : "N/A"
+            }
+            icon={Download01Icon}
+          />
+          <StatRow
+            label="Likes"
+            value={
+              model.likes !== undefined ? formatCompact(model.likes) : "N/A"
+            }
+            icon={FavouriteIcon}
+          />
+          {!isDataset && (
+            <StatRow label="Parameters" value={paramsLabel} icon={CpuIcon} />
+          )}
+          {!isDataset && (
+            <StatRow
+              label="Memory"
+              value={minMemory ?? "N/A"}
+              icon={RamMemoryIcon}
+            />
+          )}
+          {isDataset && datasetSize?.numRows != null && (
+            <StatRow
+              label="Rows"
+              value={formatCompact(datasetSize.numRows)}
+              icon={Database02Icon}
+            />
+          )}
+          {isDataset && datasetSizeBytes != null && (
+            <StatRow
+              label="Size"
+              value={formatBytes(datasetSizeBytes)}
+              icon={PackageIcon}
+            />
+          )}
+          {isDataset &&
+            datasetSize?.numSplits != null &&
+            datasetSize.numSplits > 0 && (
+              <StatRow
+                label="Splits"
+                value={String(datasetSize.numSplits)}
+                icon={LayersLogoIcon}
+              />
+            )}
+          {isDataset && languages.length > 0 && (
+            <StatRow
+              label="Languages"
+              value={
+                languages.length > 3
+                  ? `${languages.slice(0, 3).join(", ")} +${languages.length - 3}`
+                  : languages.join(", ")
+              }
+              icon={Globe02Icon}
+            />
+          )}
+          <StatRow label="License" value={licenseLabel} icon={LicenseIcon} />
+        </StatGrid>
+        <ModelStatusChips
+          isDataset={isDataset}
+          isGguf={model.isGguf}
+          unslothSupport={unslothSupport}
+          vramInfo={vramInfo}
+        />
+      </div>
+
+      <div
+        aria-hidden="true"
+        className={cn(
+          "mx-6 shrink-0 border-t transition-colors",
+          descScrolled ? "border-border" : "border-transparent",
+        )}
+      />
+
+      <div
+        ref={descScrollRef}
+        data-hub-scroll="true"
+        className="min-h-0 flex-1 space-y-4 overflow-y-auto pl-6 pr-4 pt-5 pb-0 [scrollbar-gutter:stable] [scrollbar-width:thin]"
+      >
+        {readmeReady && readmeRepoId && (
+          <ModelReadme
+            repoId={readmeRepoId}
+            kind={isDataset ? "dataset" : "model"}
+            subject={readmeSubject}
+          />
+        )}
+      </div>
+
+      <div aria-hidden="true" className="h-3 shrink-0" />
+    </div>
+  );
+});
diff --git a/studio/frontend/src/features/hub/catalog/model-readme.tsx b/studio/frontend/src/features/hub/catalog/model-readme.tsx
new file mode 100644
index 0000000000..3d215473e2
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/model-readme.tsx
@@ -0,0 +1,582 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Spinner } from "@/components/ui/spinner";
+import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
+import { LruMap } from "@/features/hub/lib/lru-map";
+import { isHuggingFaceOffline } from "@/features/hub/lib/network";
+import { fingerprintToken } from "@/features/hub/lib/token-fingerprint";
+import { cn } from "@/lib/utils";
+import { confirmExternalLink } from "../stores/external-link-confirm";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import { code as streamdownCode } from "@streamdown/code";
+import { math as streamdownMath } from "@streamdown/math";
+import { mermaid as streamdownMermaid } from "@streamdown/mermaid";
+import {
+  createContext,
+  startTransition,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import type { ComponentProps } from "react";
+import { Streamdown, type Components } from "streamdown";
+import {
+  createReadmeUrlTransform,
+  fetchReadme,
+  readmeBaseUrl,
+  stripChromeHeadings,
+  stripFrontmatter,
+} from "../lib/hf-readme";
+
+type ReadmePlugins = NonNullable<ComponentProps<typeof Streamdown>["plugins"]>;
+
+interface ReadmeState {
+  key: string;
+  body: string | null;
+  baseUrl: string | null;
+  loading: boolean;
+  error: string | null;
+  plugins: ReadmePlugins | null;
+}
+
+type ReadmeCacheEntry = Pick<ReadmeState, "body" | "baseUrl" | "error">;
+type ReadmeSubject = "model" | "dataset" | "baseModel";
+
+const README_ALLOWED_TAGS: NonNullable<
+  ComponentProps<typeof Streamdown>["allowedTags"]
+> = {
+  audio: ["src", "controls", "preload", "loop", "muted"],
+  video: [
+    "src",
+    "controls",
+    "preload",
+    "loop",
+    "muted",
+    "poster",
+    "width",
+    "height",
+    "playsinline",
+  ],
+  source: ["src", "type", "media"],
+  track: ["src", "kind", "srclang", "label", "default"],
+};
+
+const READMEX_NEEDS_MATH = /\$\$|\\\(|\\\[/;
+const READMEX_NEEDS_MERMAID = /```mermaid\b/;
+const README_RENDER_CHAR_LIMIT = 120_000;
+const README_CACHE_TTL_MS = 60_000;
+const README_TRUNCATED_NOTICE =
+  "\n\n---\n\nCard truncated for performance. Open the repository on Hugging Face to read the full README.";
+const ReadmeOnlineContext = createContext(true);
+
+interface ResolvedReadmeCacheEntry {
+  entry: ReadmeCacheEntry;
+  expiresAt: number;
+}
+
+type ReadmeCacheValue =
+  | ResolvedReadmeCacheEntry
+  | Promise<ReadmeCacheEntry>;
+
+const readmeCache = new LruMap<string, ReadmeCacheValue>(64);
+
+function isReadmeCachePromise(
+  entry: ReadmeCacheValue,
+): entry is Promise<ReadmeCacheEntry> {
+  return typeof (entry as Promise<ReadmeCacheEntry>).then === "function";
+}
+
+function readResolvedReadmeCache(cacheKey: string): ReadmeCacheEntry | null {
+  const cached = readmeCache.get(cacheKey);
+  if (!cached || isReadmeCachePromise(cached)) {
+    return null;
+  }
+  if (cached.expiresAt <= Date.now()) {
+    readmeCache.delete(cacheKey);
+    return null;
+  }
+  return cached.entry;
+}
+
+function readmeStateFromEntry(
+  key: string,
+  entry: ReadmeCacheEntry,
+): ReadmeState {
+  return {
+    key,
+    body: entry.body,
+    baseUrl: entry.baseUrl,
+    loading: false,
+    error: entry.error,
+    plugins: null,
+  };
+}
+
+function hasReadmeContent(state: Pick<ReadmeState, "body" | "error">): boolean {
+  return state.error == null && state.body != null;
+}
+
+function prepareReadmeBody(markdown: string): string {
+  const { body } = stripFrontmatter(markdown);
+  const cleaned = stripChromeHeadings(body).trim();
+  if (cleaned.length <= README_RENDER_CHAR_LIMIT) return cleaned;
+  return `${cleaned.slice(0, README_RENDER_CHAR_LIMIT).trimEnd()}${README_TRUNCATED_NOTICE}`;
+}
+
+const PROSE = cn(
+  "max-w-none text-[13.5px] leading-[1.7] text-foreground/85",
+  "[&_h1]:text-[18px] [&_h1]:font-semibold [&_h1]:tracking-tight [&_h1]:mt-2 [&_h1]:mb-3",
+  "[&_h2]:text-[15.5px] [&_h2]:font-semibold [&_h2]:tracking-tight [&_h2]:mt-5 [&_h2]:mb-2",
+  "[&_h3]:text-[14px] [&_h3]:font-semibold [&_h3]:mt-4 [&_h3]:mb-1.5",
+  "[&_p]:my-2.5 [&_ul]:my-2 [&_ol]:my-2 [&_li]:my-0.5",
+  "[&_a]:text-primary [&_a:hover]:underline",
+  "[&_code]:rounded-md [&_code]:bg-muted/60 [&_code]:px-1 [&_code]:py-0.5 [&_code]:text-[12px] [&_code]:font-mono",
+  "[&_pre]:rounded-[12px] [&_pre]:border [&_pre]:border-border/60 [&_pre]:bg-muted/40 [&_pre]:p-3 [&_pre]:text-[12px] [&_pre]:overflow-x-auto",
+  "[&_pre_code]:bg-transparent [&_pre_code]:p-0",
+  "[&_blockquote]:border-l-2 [&_blockquote]:border-border/60 [&_blockquote]:pl-3 [&_blockquote]:text-muted-foreground",
+  "[&_table]:my-3 [&_table]:text-[12.5px]",
+  "[&_th]:px-2 [&_th]:py-1.5 [&_th]:text-left [&_th]:font-semibold [&_th]:border-b [&_th]:border-border/60",
+  "[&_td]:px-2 [&_td]:py-1.5 [&_td]:border-b [&_td]:border-border/40",
+  "[&_img]:rounded-[10px] [&_img]:my-2 [&_img]:max-w-full",
+  "[&_audio]:my-1 [&_audio]:max-w-full [&_audio]:h-9 [&_audio]:align-middle",
+  "[&_video]:my-2 [&_video]:max-w-full [&_video]:rounded-[10px]",
+  "[&_hr]:my-4 [&_hr]:border-border/40",
+);
+
+function ReadmeLink({
+  node,
+  href,
+  target,
+  rel,
+  className,
+  title,
+  children,
+  ...props
+}: ComponentProps<"a"> & { node?: unknown }) {
+  void node;
+  const online = useContext(ReadmeOnlineContext);
+  const rawHref = typeof href === "string" ? href.trim() : "";
+  const disabledExternal =
+    !online &&
+    rawHref.length > 0 &&
+    !rawHref.startsWith("#") &&
+    (/^(https?:)?\/\//i.test(rawHref) || rawHref.startsWith("/"));
+  if (disabledExternal) {
+    return (
+      <span
+        aria-disabled="true"
+        title={title ?? "Unavailable offline"}
+        className={cn(className, "cursor-not-allowed opacity-60")}
+      >
+        {children}
+      </span>
+    );
+  }
+  return (
+    <a
+      {...props}
+      href={href}
+      rel={rel ?? "noreferrer noopener"}
+      target={target ?? "_blank"}
+      className={className}
+      title={title}
+      onClick={(event) => {
+        if (confirmExternalLink(rawHref)) {
+          event.preventDefault();
+        }
+      }}
+    >
+      {children}
+    </a>
+  );
+}
+
+function ReadmeImage({
+  node,
+  alt,
+  loading,
+  decoding,
+  ...props
+}: ComponentProps<"img"> & { node?: unknown }) {
+  void node;
+  return (
+    <img
+      {...props}
+      alt={alt ?? ""}
+      decoding={decoding ?? "async"}
+      loading={loading ?? "lazy"}
+    />
+  );
+}
+
+const README_COMPONENTS: Components = {
+  a: ReadmeLink,
+  img: ReadmeImage,
+};
+
+function readmeLoadingMessage(subject: ReadmeSubject): string {
+  if (subject === "dataset") return "Loading dataset card...";
+  if (subject === "baseModel") return "Loading base model card...";
+  return "Loading model card...";
+}
+
+function readmePreparingMessage(subject: ReadmeSubject): string {
+  if (subject === "dataset") return "Preparing dataset card...";
+  if (subject === "baseModel") return "Preparing base model card...";
+  return "Preparing model card...";
+}
+
+function readmeOfflineMessage(subject: ReadmeSubject): string {
+  if (subject === "dataset") return "Dataset card unavailable offline.";
+  if (subject === "baseModel") return "Base model card unavailable offline.";
+  return "Model card unavailable offline.";
+}
+
+function readmeMissingMessage(subject: ReadmeSubject): string {
+  if (subject === "dataset") return "This dataset has no README.";
+  if (subject === "baseModel") return "This base model has no README.";
+  return "This repository has no README.";
+}
+
+function readmeUnavailableMessage(subject: ReadmeSubject): string {
+  if (subject === "dataset") {
+    return "Dataset card unavailable. It may be private, gated, or temporarily unreachable.";
+  }
+  if (subject === "baseModel") {
+    return "Base model card unavailable. It may be private, gated, or temporarily unreachable.";
+  }
+  return "Model card unavailable. It may be private, gated, or temporarily unreachable.";
+}
+
+function isMissingReadmeError(error: string): boolean {
+  return /^No (dataset|model) card available\.$/.test(error);
+}
+
+function scheduleIdleTask(callback: () => void, timeout = 250): () => void {
+  let canceled = false;
+  const run = () => {
+    if (!canceled) callback();
+  };
+
+  if (typeof window === "undefined") {
+    run();
+    return () => {
+      canceled = true;
+    };
+  }
+
+  const idleWindow = window as Window & {
+    requestIdleCallback?: Window["requestIdleCallback"];
+    cancelIdleCallback?: Window["cancelIdleCallback"];
+  };
+
+  if (idleWindow.requestIdleCallback && idleWindow.cancelIdleCallback) {
+    const handle = idleWindow.requestIdleCallback(run, { timeout });
+    return () => {
+      canceled = true;
+      idleWindow.cancelIdleCallback?.(handle);
+    };
+  }
+
+  const handle = globalThis.setTimeout(run, Math.min(timeout, 120));
+  return () => {
+    canceled = true;
+    globalThis.clearTimeout(handle);
+  };
+}
+
+function ReadmePlaceholder({
+  kind,
+  message,
+}: {
+  kind: "model" | "dataset";
+  message?: string;
+}) {
+  return (
+    <div
+      className="min-h-[108px] space-y-3 py-0.5"
+      aria-busy="true"
+      aria-live="polite"
+    >
+      <div className="flex items-center gap-2 text-[12.5px] text-muted-foreground">
+        <Spinner className="size-3.5" />
+        {message ?? `Loading ${kind === "dataset" ? "dataset" : "model"} card…`}
+      </div>
+      <div className="space-y-2" aria-hidden="true">
+        <div className="h-2.5 w-11/12 rounded-full bg-muted/60" />
+        <div className="h-2.5 w-4/5 rounded-full bg-muted/50" />
+        <div className="h-2.5 w-2/3 rounded-full bg-muted/40" />
+      </div>
+    </div>
+  );
+}
+
+async function loadReadmeFromCache({
+  cacheKey,
+  repoId,
+  kind,
+  hfToken,
+}: {
+  cacheKey: string;
+  repoId: string;
+  kind: "model" | "dataset";
+  hfToken: string | undefined;
+}): Promise<ReadmeCacheEntry> {
+  const cached = readmeCache.get(cacheKey);
+  if (cached) {
+    if (isReadmeCachePromise(cached)) return cached;
+    if (cached.expiresAt > Date.now()) return cached.entry;
+    readmeCache.delete(cacheKey);
+  }
+
+  const promise = fetchReadme(repoId, kind, hfToken || null).then((fetched) => {
+    if (fetched == null) {
+      return {
+        body: null,
+        baseUrl: null,
+        error: `No ${kind === "dataset" ? "dataset" : "model"} card available.`,
+      };
+    }
+    return {
+      body: prepareReadmeBody(fetched.markdown),
+      baseUrl: readmeBaseUrl(repoId, kind, fetched.branch),
+      error: null,
+    };
+  });
+
+  readmeCache.set(cacheKey, promise);
+  try {
+    const entry = await promise;
+    if (entry.error == null) {
+      readmeCache.set(cacheKey, {
+        entry,
+        expiresAt: Date.now() + README_CACHE_TTL_MS,
+      });
+    } else if (readmeCache.get(cacheKey) === promise) {
+      readmeCache.delete(cacheKey);
+    }
+    return entry;
+  } catch (err) {
+    if (readmeCache.get(cacheKey) === promise) {
+      readmeCache.delete(cacheKey);
+    }
+    throw err;
+  }
+}
+
+function loadPlugins(needs: {
+  math: boolean;
+  mermaid: boolean;
+}): ReadmePlugins {
+  const plugins: ReadmePlugins = { code: streamdownCode };
+  if (needs.math) plugins.math = streamdownMath;
+  if (needs.mermaid) plugins.mermaid = streamdownMermaid;
+  return plugins;
+}
+
+export function ModelReadme({
+  repoId,
+  kind = "model",
+  subject = kind,
+}: {
+  repoId: string;
+  kind?: "model" | "dataset";
+  subject?: ReadmeSubject;
+}) {
+  const hfToken = useHfTokenStore((s) => s.token);
+  const online = useOnlineStatus();
+  const tokenFingerprint = useMemo(() => fingerprintToken(hfToken), [hfToken]);
+  const stateKey = useMemo(
+    () => `${kind}::${repoId}::${tokenFingerprint}`,
+    [kind, repoId, tokenFingerprint],
+  );
+  const [state, setState] = useState<ReadmeState>(() => {
+    const cached = readResolvedReadmeCache(stateKey);
+    if (cached) return readmeStateFromEntry(stateKey, cached);
+    return {
+      key: stateKey,
+      body: null,
+      baseUrl: null,
+      loading: !isHuggingFaceOffline(),
+      error: null,
+      plugins: null,
+    };
+  });
+  const matchingState = state.key === stateKey ? state : null;
+  const cachedEntry = readResolvedReadmeCache(stateKey);
+  const cachedState = cachedEntry
+    ? readmeStateFromEntry(stateKey, cachedEntry)
+    : null;
+  const current = matchingState && hasReadmeContent(matchingState)
+    ? matchingState
+    : cachedState && hasReadmeContent(cachedState)
+      ? cachedState
+      : !online
+        ? {
+            key: stateKey,
+            body: null,
+            baseUrl: null,
+            loading: false,
+            error: readmeOfflineMessage(subject),
+            plugins: null,
+          }
+        : matchingState ?? {
+            key: stateKey,
+            body: null,
+            baseUrl: null,
+            loading: true,
+            error: null,
+            plugins: null,
+          };
+
+  const urlTransform = useMemo(
+    () =>
+      current.baseUrl ? createReadmeUrlTransform(current.baseUrl) : undefined,
+    [current.baseUrl],
+  );
+
+  useEffect(() => {
+    let canceled = false;
+    if (!online) return;
+    void loadReadmeFromCache({
+      cacheKey: stateKey,
+      repoId,
+      kind,
+      hfToken,
+    })
+      .then((entry) => {
+        if (canceled) return;
+        startTransition(() => {
+          setState({
+            key: stateKey,
+            body: entry.body,
+            baseUrl: entry.baseUrl,
+            loading: false,
+            error: entry.error,
+            plugins: null,
+          });
+        });
+      })
+      .catch((err) => {
+        if (canceled) return;
+        startTransition(() => {
+          setState({
+            key: stateKey,
+            body: null,
+            baseUrl: null,
+            loading: false,
+            error:
+              err instanceof Error ? err.message : "Failed to load model card",
+            plugins: null,
+          });
+        });
+      });
+    return () => {
+      canceled = true;
+    };
+  }, [repoId, kind, hfToken, stateKey, online]);
+
+  useEffect(() => {
+    // Plugin assembly is synchronous, so it runs regardless of connectivity: a
+    // body served from the README cache while offline still clears the preparing gate.
+    if (!current.body || current.loading || current.error || current.plugins) {
+      return;
+    }
+    let canceled = false;
+    const key = current.key;
+    const body = current.body;
+    const baseUrl = current.baseUrl;
+    const applyPlugins = (next: ReadmePlugins) => {
+      if (canceled) return;
+      startTransition(() => {
+        setState((prev) => {
+          if (prev.key === key) {
+            return prev.plugins ? prev : { ...prev, plugins: next };
+          }
+          return {
+            key,
+            body,
+            baseUrl,
+            loading: false,
+            error: null,
+            plugins: next,
+          };
+        });
+      });
+    };
+    const cancelIdle = scheduleIdleTask(() => {
+      applyPlugins(
+        loadPlugins({
+          math: READMEX_NEEDS_MATH.test(body),
+          mermaid: READMEX_NEEDS_MERMAID.test(body),
+        }),
+      );
+    }, 400);
+    return () => {
+      canceled = true;
+      cancelIdle();
+    };
+  }, [
+    current.body,
+    current.loading,
+    current.error,
+    current.plugins,
+    current.key,
+    current.baseUrl,
+  ]);
+
+  if (current.loading) {
+    return (
+      <ReadmePlaceholder kind={kind} message={readmeLoadingMessage(subject)} />
+    );
+  }
+
+  if (current.error) {
+    const errorMessage = isMissingReadmeError(current.error)
+      ? readmeMissingMessage(subject)
+      : current.error.toLowerCase().includes("offline")
+        ? current.error
+        : readmeUnavailableMessage(subject);
+    return (
+      <p className="min-h-[44px] text-[12.5px] text-muted-foreground">
+        {errorMessage}
+      </p>
+    );
+  }
+
+  if (!current.body) {
+    return (
+      <p className="min-h-[44px] text-[12.5px] text-muted-foreground">
+        {readmeMissingMessage(subject)}
+      </p>
+    );
+  }
+
+  if (!current.plugins) {
+    return (
+      <ReadmePlaceholder
+        kind={kind}
+        message={readmePreparingMessage(subject)}
+      />
+    );
+  }
+
+  return (
+    <div className={cn("hub-readme-prose", PROSE)}>
+      <ReadmeOnlineContext.Provider value={online}>
+        <Streamdown
+          mode="static"
+          plugins={current.plugins}
+          controls={false}
+          components={README_COMPONENTS}
+          allowedTags={README_ALLOWED_TAGS}
+          urlTransform={urlTransform}
+        >
+          {current.body}
+        </Streamdown>
+      </ReadmeOnlineContext.Provider>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/models-catalog-lists.tsx b/studio/frontend/src/features/hub/catalog/models-catalog-lists.tsx
new file mode 100644
index 0000000000..b506f6a02d
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/models-catalog-lists.tsx
@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Spinner } from "@/components/ui/spinner";
+import { modelIdsMatch } from "@/features/hub/lib/model-identity";
+import {
+  CubeIcon,
+  DownloadCircle02Icon,
+  FolderSearchIcon,
+} from "@hugeicons/core-free-icons";
+import type { RefObject } from "react";
+import { useMemo } from "react";
+import { inventoryRowMatches, scoreInventoryRow } from "../lib/inventory-search";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+} from "../types";
+import {
+  DiscoverFetchMoreFooter,
+  DiscoverFetchMoreState,
+  EmptyState,
+  InventoryErrorState,
+  NetworkErrorState,
+  SkeletonList,
+} from "./catalog-states";
+import {
+  DiscoverModelRow,
+  InventoryRow,
+  VirtualRows,
+} from "./models-catalog-rows";
+
+type InventoryItem =
+  | { variant: "cached"; row: CachedInventoryRow }
+  | { variant: "local"; row: LocalInventoryRow };
+
+export function InventoryWarningRow({
+  isDataset,
+  onRetry,
+}: {
+  isDataset: boolean;
+  onRetry: () => void;
+}) {
+  return (
+    <div className="mx-5 mt-2 rounded-[8px] border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-[12.5px] text-muted-foreground">
+      <div className="flex items-center justify-between gap-3">
+        <span>
+          Some on-device sources couldn't be scanned. Showing available{" "}
+          {isDataset ? "datasets" : "models"}.
+        </span>
+        <button
+          type="button"
+          className="shrink-0 text-[12px] font-medium text-foreground transition-colors hover:text-primary"
+          onClick={onRetry}
+        >
+          Retry
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function DiscoverList({
+  discoverRows,
+  selectedId,
+  onSelect,
+  isLoading,
+  query,
+  scrollElement,
+  sentinelRef,
+  activeCheckpoint,
+  searchError,
+  online,
+  isDataset,
+  deviceType,
+  scannedCount,
+  isLoadingMore,
+  hasMore,
+  manualFetchAvailable,
+  hasActiveFilters,
+  onFetchMore,
+  onClearFilters,
+  onRetry,
+  onSwitchDevice,
+}: {
+  discoverRows: DiscoverRow[];
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+  isLoading: boolean;
+  query: string;
+  scrollElement: HTMLDivElement | null;
+  sentinelRef: RefObject<HTMLDivElement | null>;
+  activeCheckpoint: string | null;
+  searchError: string | null;
+  online: boolean;
+  isDataset: boolean;
+  deviceType: string | null;
+  scannedCount: number;
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  manualFetchAvailable: boolean;
+  hasActiveFilters: boolean;
+  onFetchMore: () => void;
+  onClearFilters: () => void;
+  onRetry: () => void;
+  onSwitchDevice?: () => void;
+}) {
+  return (
+    <>
+      {online ? (
+        searchError && discoverRows.length === 0 ? (
+          <NetworkErrorState
+            online={online}
+            message={searchError}
+            onRetry={onRetry}
+            resourceLabel={isDataset ? "datasets" : "models"}
+          />
+        ) : hasMore && discoverRows.length === 0 ? (
+          <DiscoverFetchMoreState
+            scannedCount={scannedCount}
+            hasActiveFilters={hasActiveFilters}
+            isLoadingMore={isLoadingMore}
+            onFetchMore={onFetchMore}
+            onClearFilters={onClearFilters}
+          />
+        ) : discoverRows.length === 0 && isLoading ? (
+          <SkeletonList />
+        ) : discoverRows.length === 0 ? (
+          <EmptyState
+            icon={query.trim() ? FolderSearchIcon : CubeIcon}
+            title={
+              query.trim()
+                ? `No matching ${isDataset ? "datasets" : "models"}`
+                : `No ${isDataset ? "datasets" : "models"} available`
+            }
+            body={
+              query.trim()
+                ? "Try a broader search or remove some filters."
+                : "The current filters are excluding every result."
+            }
+          />
+        ) : (
+          <>
+            <VirtualRows
+              items={discoverRows}
+              scrollElement={scrollElement}
+              getKey={(row) => row.id}
+              renderRow={(row) => (
+                <DiscoverModelRow
+                  row={row}
+                  selected={selectedId === row.id}
+                  active={modelIdsMatch(activeCheckpoint, row.id)}
+                  deviceType={deviceType}
+                  isDataset={isDataset}
+                  onSelect={onSelect}
+                />
+              )}
+            />
+            {hasMore && (
+              <DiscoverFetchMoreFooter
+                scannedCount={scannedCount}
+                manualFetchAvailable={manualFetchAvailable}
+                hasActiveFilters={hasActiveFilters}
+                isLoadingMore={isLoadingMore}
+                onFetchMore={onFetchMore}
+              />
+            )}
+          </>
+        )
+      ) : (
+        <NetworkErrorState
+          online={online}
+          message="Discovery is unavailable while offline."
+          onRetry={onRetry}
+          onSwitchDevice={onSwitchDevice}
+          resourceLabel={isDataset ? "datasets" : "models"}
+        />
+      )}
+
+      <div ref={sentinelRef} className="h-px" />
+    </>
+  );
+}
+
+export function DownloadedList({
+  cachedRows,
+  localRows,
+  selectedId,
+  onSelect,
+  downloadedReady,
+  inventoryError,
+  query,
+  scrollElement,
+  activeCheckpoint,
+  activeGgufVariant,
+  isDataset,
+  inventoryTokens,
+  deviceType,
+  onInventoryChange,
+}: {
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+  downloadedReady: boolean;
+  inventoryError: boolean;
+  query: string;
+  scrollElement: HTMLDivElement | null;
+  activeCheckpoint: string | null;
+  activeGgufVariant: string | null;
+  isDataset: boolean;
+  inventoryTokens: readonly string[];
+  deviceType: string | null;
+  onInventoryChange?: () => void;
+}) {
+  const inventoryItems = useMemo<InventoryItem[]>(() => {
+    const merged: InventoryItem[] = [
+      ...cachedRows.map((row) => ({ variant: "cached" as const, row })),
+      ...localRows.map((row) => ({ variant: "local" as const, row })),
+    ];
+    if (inventoryTokens.length === 0) return merged;
+    return merged
+      .map((item, index) => ({
+        item,
+        index,
+        score: scoreInventoryRow(item.row, inventoryTokens),
+      }))
+      .sort((a, b) => b.score - a.score || a.index - b.index)
+      .map((entry) => entry.item);
+  }, [cachedRows, localRows, inventoryTokens]);
+  const hasInventoryRows = cachedRows.length > 0 || localRows.length > 0;
+
+  if (!downloadedReady && !hasInventoryRows) {
+    return (
+      <div className="flex min-h-[240px] items-center justify-center gap-3 text-[13px] text-muted-foreground">
+        <Spinner className="size-4" />
+        Loading local inventory...
+      </div>
+    );
+  }
+
+  if (inventoryError && cachedRows.length === 0 && localRows.length === 0) {
+    return (
+      <InventoryErrorState
+        isDataset={isDataset}
+        onRetry={() => onInventoryChange?.()}
+      />
+    );
+  }
+
+  if (cachedRows.length === 0 && localRows.length === 0) {
+    return (
+      <EmptyState
+        icon={query.trim() ? FolderSearchIcon : DownloadCircle02Icon}
+        title={query.trim() ? "No matches on device" : "Nothing on device yet"}
+        body={
+          query.trim()
+            ? `Clear the search or try a different query. No cached or local ${isDataset ? "dataset" : "model"} matches it.`
+            : isDataset
+              ? "Downloaded datasets, recipe outputs, and uploaded files will appear here."
+              : "Downloaded repositories and indexed local folders will appear here."
+        }
+      />
+    );
+  }
+
+  return (
+    <VirtualRows
+      items={inventoryItems}
+      scrollElement={scrollElement}
+      getKey={(item) => `${item.variant}-${item.row.id}`}
+      renderRow={(item) => (
+        <InventoryRow
+          row={item.row}
+          selected={selectedId === item.row.id}
+          activeCheckpoint={activeCheckpoint}
+          activeGgufVariant={activeGgufVariant}
+          isDataset={isDataset}
+          dimmed={!inventoryRowMatches(item.row, inventoryTokens)}
+          deviceType={deviceType}
+          onSelect={onSelect}
+          onChange={onInventoryChange}
+        />
+      )}
+    />
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx b/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
new file mode 100644
index 0000000000..cc87fc23ce
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/models-catalog-rows.tsx
@@ -0,0 +1,768 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { ModelDeleteAction } from "@/components/assistant-ui/model-selector/model-delete-action";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import {
+  type GgufVariantDetail,
+  deleteCachedModel,
+  deleteCachedDataset,
+  formatLocalUpdated,
+  listGgufVariants,
+  useGgufVariantsCacheVersion,
+} from "@/features/hub/inventory";
+import { classifyUnslothSupport } from "@/features/hub/hooks/use-hub-model-search";
+import { formatBytes, formatRelativeShort } from "@/features/hub/lib/format";
+import { ggufVariantDisplayLabel } from "@/features/hub/lib/gguf-variant-sort";
+import { modelIdsMatch } from "@/features/hub/lib/model-identity";
+import { cn, formatCompact } from "@/lib/utils";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import {
+  Download01Icon,
+  FavouriteIcon,
+  PackageIcon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import {
+  type ReactNode,
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+} from "../types";
+import { OwnerAvatar } from "./owner-avatar";
+
+const COARSE_POINTER =
+  typeof window !== "undefined" &&
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(pointer: coarse)").matches;
+
+// Defer the cached-size chip (a Radix Tooltip + two store subscriptions) until the
+// row is hovered/focused so flicking the list doesn't pay that cost per row. The
+// placeholder renders an identical StatChip, so the swap shifts nothing. Coarse
+// pointers have no hover, so arm immediately; default true so out-of-row usage works.
+const CatalogRowInteractiveContext = createContext(true);
+
+function CachedSizeChip(props: {
+  repoId: string;
+  totalBytes: number;
+  isGguf: boolean;
+  isDataset?: boolean;
+  cachePath?: string | null;
+}) {
+  const interactive = useContext(CatalogRowInteractiveContext);
+  if (!interactive) {
+    return <StatChip icon={PackageIcon} value={formatBytes(props.totalBytes)} />;
+  }
+  return <CachedSizeChipLive {...props} />;
+}
+
+function CachedSizeChipLive({
+  repoId,
+  totalBytes,
+  isGguf,
+  isDataset = false,
+  cachePath,
+}: {
+  repoId: string;
+  totalBytes: number;
+  isGguf: boolean;
+  isDataset?: boolean;
+  cachePath?: string | null;
+}) {
+  const hfToken = useHfTokenStore((s) => s.token) || undefined;
+  const variantsVersion = useGgufVariantsCacheVersion(repoId);
+  const fetchKey = `${repoId}::${cachePath ?? ""}::${variantsVersion}`;
+  const [variantState, setVariantState] = useState<{
+    key: string;
+    status: "idle" | "loading" | "loaded" | "error";
+    variants: GgufVariantDetail[];
+  }>(() => ({
+    key: fetchKey,
+    status: "idle",
+    variants: [],
+  }));
+  const fetchedForRef = useRef<string | null>(null);
+  const needsVariantFetch = isGguf && !isDataset;
+  const currentVariantState =
+    variantState.key === fetchKey
+      ? variantState
+      : { key: fetchKey, status: "idle" as const, variants: [] };
+
+  const ensureVariantsLoaded = useCallback(() => {
+    if (!needsVariantFetch) return;
+    if (fetchedForRef.current === fetchKey) return;
+    fetchedForRef.current = fetchKey;
+    setVariantState({ key: fetchKey, status: "loading", variants: [] });
+    listGgufVariants(repoId, hfToken, {
+      preferLocalCache: true,
+      localPath: cachePath ?? null,
+    })
+      .then((res) => {
+        if (fetchedForRef.current !== fetchKey) return;
+        setVariantState({
+          key: fetchKey,
+          status: "loaded",
+          variants: res.variants.filter((v) => v.downloaded),
+        });
+      })
+      .catch(() => {
+        if (fetchedForRef.current !== fetchKey) return;
+        fetchedForRef.current = null;
+        setVariantState({ key: fetchKey, status: "error", variants: [] });
+      });
+  }, [needsVariantFetch, fetchKey, repoId, hfToken, cachePath]);
+
+  const trigger = (
+    <span
+      className="pointer-events-auto hub-modal-pe-guard"
+      onClick={(e) => e.stopPropagation()}
+    >
+      <StatChip icon={PackageIcon} value={formatBytes(totalBytes)} />
+    </span>
+  );
+
+  const rows: Array<{ label: string; size_bytes: number }> | null =
+    !needsVariantFetch
+      ? [{ label: repoId, size_bytes: totalBytes }]
+      : currentVariantState.status === "loaded" &&
+          currentVariantState.variants.length > 0
+        ? currentVariantState.variants.map((variant) => ({
+            label: ggufVariantDisplayLabel(variant),
+            size_bytes: variant.size_bytes,
+          }))
+        : null;
+  const variantMessage =
+    currentVariantState.status === "loading"
+      ? "Loading downloaded variants..."
+      : currentVariantState.status === "error"
+        ? "Couldn't load downloaded variants. Open again to retry."
+        : currentVariantState.status === "loaded"
+          ? "No downloaded GGUF variants found."
+          : "Open to load downloaded variants.";
+
+  return (
+    <Tooltip
+      onOpenChange={(open) => {
+        if (open) ensureVariantsLoaded();
+      }}
+    >
+      <TooltipTrigger asChild={true}>{trigger}</TooltipTrigger>
+      <TooltipContent variant="default" side="top" sideOffset={4}>
+        {rows ? (
+          <ul className="flex flex-col gap-1">
+            {rows.map((row) => (
+              <li
+                key={row.label}
+                className="flex items-center gap-3 tabular-nums"
+              >
+                <span className="min-w-0 truncate">{row.label}</span>
+                <span className="ml-auto">
+                  <StatChip
+                    icon={PackageIcon}
+                    value={formatBytes(row.size_bytes)}
+                  />
+                </span>
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <span className="block max-w-52 text-[11px] leading-4 text-muted-foreground">
+            {variantMessage}
+          </span>
+        )}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+export function StatChip({
+  icon,
+  value,
+}: {
+  icon: IconSvgElement;
+  value: string;
+}) {
+  return (
+    <span className="inline-flex shrink-0 items-center gap-1 whitespace-nowrap text-[10px] font-medium leading-none tabular-nums text-muted-foreground/75">
+      <HugeiconsIcon
+        icon={icon}
+        strokeWidth={1.75}
+        className="size-2.5 shrink-0"
+      />
+      {value}
+    </span>
+  );
+}
+
+function CatalogRow({
+  selected,
+  active,
+  onClick,
+  tooltip,
+  label,
+  children,
+}: {
+  selected: boolean;
+  active?: boolean;
+  tooltip?: ReactNode;
+  onClick: () => void;
+  label: string;
+  children: ReactNode;
+}) {
+  const [interactive, setInteractive] = useState(COARSE_POINTER);
+  const arm = useCallback(() => setInteractive(true), []);
+  const button = (
+    <div
+      data-selected={selected || undefined}
+      data-active={active || undefined}
+      onPointerEnter={arm}
+      onFocusCapture={arm}
+      className="catalog-row group/row relative block w-full select-none overflow-hidden rounded-[14px] pl-3 pr-2.5 py-2.5 text-left"
+    >
+      <button
+        type="button"
+        aria-label={label}
+        onClick={onClick}
+        className="absolute inset-0 cursor-pointer rounded-[14px] outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+      />
+      <CatalogRowInteractiveContext.Provider value={interactive}>
+        <div className="pointer-events-none relative">{children}</div>
+      </CatalogRowInteractiveContext.Provider>
+    </div>
+  );
+  if (!tooltip || !interactive) return button;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild={true}>{button}</TooltipTrigger>
+      <TooltipContent
+        side="right"
+        align="center"
+        sideOffset={8}
+        className="tooltip-compact max-w-xs"
+      >
+        {tooltip}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function StatusDot({
+  tone,
+  label,
+}: {
+  tone: "warning" | "danger" | "success";
+  label: string;
+}) {
+  const toneClass =
+    tone === "warning"
+      ? "bg-status-warning"
+      : tone === "danger"
+        ? "bg-status-danger"
+        : "bg-status-success";
+  return (
+    <span
+      role="img"
+      aria-label={label}
+      className={cn("inline-block size-[5px] shrink-0 rounded-full", toneClass)}
+    />
+  );
+}
+
+function TooltipLegendRow({
+  toneClass,
+  children,
+}: {
+  toneClass: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className="flex items-start gap-1.5 leading-snug">
+      <span
+        aria-hidden="true"
+        className={cn(
+          "mt-1 inline-block size-1.5 shrink-0 rounded-full",
+          toneClass,
+        )}
+      />
+      <span className="min-w-0">{children}</span>
+    </div>
+  );
+}
+
+function buildRowStatusTooltip({
+  isGguf,
+  isAdapter,
+  isAvailableOnDevice,
+  partialRepoId,
+  unsupported,
+  unsupportedReason,
+  resourceLabel = "model",
+}: {
+  isGguf?: boolean;
+  isAdapter?: boolean;
+  isAvailableOnDevice?: boolean;
+  partialRepoId?: string;
+  unsupported?: boolean;
+  unsupportedReason?: string | null;
+  resourceLabel?: "model" | "dataset";
+}): ReactNode {
+  const lines: ReactNode[] = [];
+
+  if (isGguf) {
+    lines.push(
+      <TooltipLegendRow key="gguf" toneClass="bg-format-gguf">
+        GGUF format.
+      </TooltipLegendRow>,
+    );
+  }
+  if (isAdapter) {
+    lines.push(
+      <TooltipLegendRow key="adapter" toneClass="bg-format-adapter">
+        Adapter format.
+      </TooltipLegendRow>,
+    );
+  }
+
+  if (partialRepoId) {
+    lines.push(
+      <TooltipLegendRow key="partial" toneClass="bg-status-warning">
+        Partial download of <span className="font-medium">{partialRepoId}</span>
+        . Click Resume to continue.
+      </TooltipLegendRow>,
+    );
+  } else if (isAvailableOnDevice) {
+    lines.push(
+      <TooltipLegendRow key="success" toneClass="bg-status-success">
+        On device. Ready to use locally.
+      </TooltipLegendRow>,
+    );
+  }
+
+  if (unsupported) {
+    lines.push(
+      <TooltipLegendRow key="danger" toneClass="bg-status-danger">
+        <span className="block">
+          This {resourceLabel} may not be supported yet.
+        </span>
+        {unsupportedReason && (
+          <span className="mt-0.5 block text-white/75">
+            {unsupportedReason}
+          </span>
+        )}
+        <span className="mt-0.5 block text-white/75">
+          Still downloadable to your Hugging Face cache, shared with every
+          framework that reads it.
+        </span>
+      </TooltipLegendRow>,
+    );
+  }
+
+  if (lines.length === 0) return null;
+  return <div className="space-y-1.5">{lines}</div>;
+}
+
+export const DiscoverModelRow = memo(function DiscoverModelRow({
+  row,
+  selected,
+  active,
+  deviceType,
+  isDataset,
+  onSelect,
+}: {
+  row: DiscoverRow;
+  selected: boolean;
+  active: boolean;
+  deviceType: string | null;
+  isDataset: boolean;
+  onSelect: (id: string) => void;
+}) {
+  const support = useMemo(
+    () =>
+      isDataset
+        ? null
+        : classifyUnslothSupport({
+            modelId: row.id,
+            pipelineTag: row.result.pipelineTag,
+            tags: row.result.tags,
+            libraryName: row.result.libraryName,
+            deviceType,
+            quantMethod: row.result.quantMethod,
+          }),
+    [isDataset, row.id, row.result, deviceType],
+  );
+  const unsupported = support?.status === "unsupported";
+  const handleClick = useCallback(() => onSelect(row.id), [onSelect, row.id]);
+  const partialRepoId =
+    row.isAvailableOnDevice && row.isPartialOnDevice
+      ? row.result.id
+      : undefined;
+  const tooltip = buildRowStatusTooltip({
+    isGguf: row.result.isGguf,
+    isAdapter: false,
+    isAvailableOnDevice: row.isAvailableOnDevice,
+    partialRepoId,
+    unsupported,
+    unsupportedReason: support?.reason ?? null,
+    resourceLabel: isDataset ? "dataset" : "model",
+  });
+  return (
+    <CatalogRow
+      selected={selected}
+      active={active}
+      tooltip={tooltip}
+      label={row.repo}
+      onClick={handleClick}
+    >
+      <div className="flex items-center gap-3">
+        <OwnerAvatar
+          owner={row.owner}
+          repoName={row.repo}
+          className="size-8 rounded-[9px]"
+        />
+        <div className="flex min-w-0 flex-1 flex-col gap-[3px]">
+          <div className="flex h-[18px] min-w-0 items-center justify-between gap-2">
+            <div className="flex min-w-0 items-center gap-1.5 pr-2">
+              <p className="truncate text-[12px] font-medium leading-[18px] tracking-[-0.005em] text-foreground">
+                {row.repo}
+              </p>
+              {row.result.isGguf && (
+                <span
+                  role="img"
+                  aria-label="GGUF"
+                  className="inline-block size-[5px] shrink-0 rounded-full bg-format-gguf"
+                />
+              )}
+              {unsupported && (
+                <StatusDot tone="danger" label="May not be supported yet" />
+              )}
+              {row.isAvailableOnDevice && row.isPartialOnDevice && (
+                <StatusDot tone="warning" label="Partial download" />
+              )}
+              {row.isAvailableOnDevice && !row.isPartialOnDevice && (
+                <StatusDot tone="success" label="On device" />
+              )}
+            </div>
+            <div className="flex shrink-0 items-center gap-2.5">
+              <StatChip
+                icon={FavouriteIcon}
+                value={formatCompact(row.result.likes)}
+              />
+              <StatChip
+                icon={Download01Icon}
+                value={formatCompact(row.result.downloads)}
+              />
+            </div>
+          </div>
+          <div className="flex h-[16px] min-w-0 items-center justify-between gap-2 text-[11.5px] leading-[16px] text-muted-foreground/85">
+            <span className="flex min-w-0 items-center gap-1">
+              <span className="truncate">{row.owner}</span>
+              {row.owner.toLowerCase() === "unsloth" && (
+                <span
+                  aria-label="Verified Unsloth"
+                  className="hub-verified-badge size-3.5 shrink-0 text-primary"
+                />
+              )}
+            </span>
+            <span className="shrink-0 text-[10.5px] tabular-nums">
+              {formatRelativeShort(row.result.updatedAt)}
+            </span>
+          </div>
+        </div>
+      </div>
+    </CatalogRow>
+  );
+});
+
+function cachedRowActive(
+  row: CachedInventoryRow,
+  activeCheckpoint: string | null,
+  activeGgufVariant: string | null,
+): boolean {
+  if (!modelIdsMatch(activeCheckpoint, row.loadId)) return false;
+  if (row.modelFormat === "gguf") {
+    return row.capabilities.requiresVariant ? activeGgufVariant !== null : true;
+  }
+  return activeGgufVariant === null;
+}
+
+function localRowActive(
+  row: LocalInventoryRow,
+  activeCheckpoint: string | null,
+  activeGgufVariant: string | null,
+): boolean {
+  if (!modelIdsMatch(activeCheckpoint, row.loadId)) return false;
+  if (row.modelFormat === "gguf") {
+    return row.capabilities.requiresVariant ? activeGgufVariant !== null : true;
+  }
+  return activeGgufVariant === null;
+}
+
+export const InventoryRow = memo(function InventoryRow({
+  row,
+  selected,
+  activeCheckpoint,
+  activeGgufVariant,
+  isDataset,
+  dimmed,
+  deviceType,
+  onSelect,
+  onChange,
+}: {
+  row: CachedInventoryRow | LocalInventoryRow;
+  selected: boolean;
+  activeCheckpoint: string | null;
+  activeGgufVariant: string | null;
+  isDataset: boolean;
+  dimmed: boolean;
+  deviceType: string | null;
+  onSelect: (id: string) => void;
+  onChange?: () => void;
+}) {
+  const rowModelId =
+    row.kind === "cache"
+      ? row.repoId
+      : (row.repoId ?? row.baseModelHubId ?? row.baseModel ?? row.loadId);
+  const rowTagsSignature = row.tags?.join("\u0001") ?? "";
+  const unsupported = useMemo(() => {
+    if (isDataset) return false;
+    return (
+      classifyUnslothSupport({
+        modelId: rowModelId,
+        pipelineTag: row.pipelineTag,
+        tags: rowTagsSignature ? rowTagsSignature.split("\u0001") : undefined,
+        libraryName: row.libraryName,
+        quantMethod: row.quantMethod,
+        deviceType,
+      }).status === "unsupported"
+    );
+  }, [
+    isDataset,
+    rowModelId,
+    row.pipelineTag,
+    rowTagsSignature,
+    row.libraryName,
+    row.quantMethod,
+    deviceType,
+  ]);
+  const handleClick = useCallback(() => onSelect(row.id), [onSelect, row.id]);
+  const active =
+    row.kind === "cache"
+      ? cachedRowActive(row, activeCheckpoint, activeGgufVariant)
+      : localRowActive(row, activeCheckpoint, activeGgufVariant);
+  const title = row.kind === "cache" ? row.repo : row.title;
+
+  const subLabel = row.owner;
+  const trailing =
+    row.kind === "local" && row.updatedAt
+      ? formatLocalUpdated(row.updatedAt)
+      : null;
+  const cacheDeletableRepoId =
+    row.kind === "cache"
+      ? row.repoId
+      : row.source === "hf_cache" && row.repoId
+        ? row.repoId
+        : null;
+  const canDelete = cacheDeletableRepoId !== null;
+  const partialRepoId = row.partial
+    ? row.kind === "cache"
+      ? row.repoId
+      : (row.repoId ?? row.loadId)
+    : undefined;
+  const tooltip = buildRowStatusTooltip({
+    isGguf: row.isGguf,
+    isAdapter: row.modelFormat === "adapter",
+    isAvailableOnDevice: !partialRepoId,
+    partialRepoId,
+    unsupported,
+    resourceLabel: isDataset ? "dataset" : "model",
+  });
+
+  return (
+    <CatalogRow
+      selected={selected}
+      active={active}
+      tooltip={tooltip}
+      label={title}
+      onClick={handleClick}
+    >
+      <div
+        className={cn(
+          "flex items-center gap-3 transition-opacity",
+          dimmed && "opacity-25 group-hover/row:opacity-60",
+        )}
+      >
+        <OwnerAvatar
+          owner={row.owner}
+          repoName={title}
+          className="size-8 rounded-[9px]"
+        />
+        <div className="flex min-w-0 flex-1 flex-col gap-[3px]">
+          <div className="flex h-[18px] min-w-0 items-center justify-between gap-2">
+            <div className="flex min-w-0 items-center gap-1.5 pr-2">
+              <p className="truncate text-[12px] font-medium leading-[18px] tracking-[-0.005em] text-foreground">
+                {title}
+              </p>
+              {row.isGguf && (
+                <span
+                  role="img"
+                  aria-label="GGUF"
+                  className="inline-block size-[5px] shrink-0 rounded-full bg-format-gguf"
+                />
+              )}
+              {row.modelFormat === "adapter" && (
+                <span
+                  role="img"
+                  aria-label="Adapter"
+                  className="inline-block size-[5px] shrink-0 rounded-full bg-format-adapter"
+                />
+              )}
+              {partialRepoId ? (
+                <StatusDot tone="warning" label="Partial download" />
+              ) : (
+                <StatusDot tone="success" label="On device" />
+              )}
+              {unsupported && (
+                <StatusDot tone="danger" label="May not be supported yet" />
+              )}
+            </div>
+            <div className="flex shrink-0 items-center gap-1">
+              {canDelete && cacheDeletableRepoId && (
+                <ModelDeleteAction
+                  ariaLabel={`Delete ${cacheDeletableRepoId}`}
+                  title={
+                    isDataset
+                      ? "Delete cached dataset?"
+                      : "Delete cached model?"
+                  }
+                  description={
+                    <>
+                      This will remove{" "}
+                      <span className="font-medium text-foreground">
+                        {cacheDeletableRepoId}
+                      </span>{" "}
+                      {isDataset
+                        ? "and its downloaded files"
+                        : row.isGguf
+                          ? "and all of its downloaded quantizations"
+                          : "and all of its downloaded files"}
+                      {row.kind === "cache"
+                        ? ` (${formatBytes(row.bytes)})`
+                        : ""}{" "}
+                      from disk. You can re-download it later.
+                    </>
+                  }
+                  successMessage={`Deleted ${cacheDeletableRepoId}`}
+                  buttonClassName="pointer-events-auto hub-modal-pe-guard opacity-0 transition-opacity group-hover/row:opacity-100 focus-visible:opacity-100 data-[state=open]:opacity-100 [@media(pointer:coarse)]:opacity-100"
+                  iconClassName="size-3.5"
+                  onConfirm={async () => {
+                    if (isDataset) {
+                      await deleteCachedDataset(cacheDeletableRepoId);
+                    } else {
+                      await deleteCachedModel(cacheDeletableRepoId);
+                    }
+                  }}
+                  onDeleted={onChange}
+                />
+              )}
+              {row.kind === "cache" && (
+                <CachedSizeChip
+                  repoId={row.repoId}
+                  totalBytes={row.bytes}
+                  isGguf={row.isGguf}
+                  isDataset={isDataset}
+                  cachePath={row.cachePath}
+                />
+              )}
+            </div>
+          </div>
+          <div className="flex h-[16px] min-w-0 items-center justify-between gap-2 text-[11.5px] leading-[16px] text-muted-foreground/85">
+            <span className="flex min-w-0 items-center gap-1">
+              <span className="truncate">{subLabel}</span>
+              {subLabel.toLowerCase() === "unsloth" && (
+                <span
+                  aria-label="Verified Unsloth"
+                  className="hub-verified-badge size-3.5 shrink-0 text-primary"
+                />
+              )}
+            </span>
+            {trailing && (
+              <span className="shrink-0 text-[10.5px] tabular-nums">
+                {trailing}
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+    </CatalogRow>
+  );
+});
+
+export const CATALOG_ROW_HEIGHT_PX = 57;
+
+export function VirtualRows<T>({
+  items,
+  scrollElement,
+  getKey,
+  renderRow,
+}: {
+  items: readonly T[];
+  scrollElement: HTMLDivElement | null;
+  getKey: (item: T, index: number) => string;
+  renderRow: (item: T) => ReactNode;
+}) {
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => scrollElement,
+    estimateSize: () => CATALOG_ROW_HEIGHT_PX,
+    overscan: 10,
+    getItemKey: (index) => getKey(items[index], index),
+  });
+
+  return (
+    <ul
+      style={{
+        height: virtualizer.getTotalSize(),
+        position: "relative",
+        width: "100%",
+        overflowAnchor: "none",
+      }}
+    >
+      {virtualizer.getVirtualItems().map((virtualRow) => (
+        <li
+          key={virtualRow.key}
+          data-index={virtualRow.index}
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: "100%",
+            transform: `translateY(${virtualRow.start}px)`,
+            // Lock rows to estimateSize with no measureElement ref: per-mount
+            // measurement churns the virtualizer (re-renders + offset recompute)
+            // that reads as a jump. A fixed matching height keeps appends stable.
+            height: `${CATALOG_ROW_HEIGHT_PX}px`,
+            contain: "layout paint",
+          }}
+        >
+          {renderRow(items[virtualRow.index])}
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/models-catalog.tsx b/studio/frontend/src/features/hub/catalog/models-catalog.tsx
new file mode 100644
index 0000000000..872baf61d0
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/models-catalog.tsx
@@ -0,0 +1,396 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { usePlatformStore } from "@/config/env";
+import { cn } from "@/lib/utils";
+import {
+  type RefObject,
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+  ModelsTab,
+} from "../types";
+import {
+  DiscoverList,
+  DownloadedList,
+  InventoryWarningRow,
+} from "./models-catalog-lists";
+import { CATALOG_ROW_HEIGHT_PX } from "./models-catalog-rows";
+
+export interface ModelsCatalogState {
+  tab: ModelsTab;
+  discoverRows: DiscoverRow[];
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+  selectedId: string | null;
+  isLoading: boolean;
+  downloadedReady: boolean;
+  inventoryError: boolean;
+  inventoryWarning: boolean;
+  query: string;
+  activeCheckpoint: string | null;
+  activeGgufVariant: string | null;
+  searchError: string | null;
+  online: boolean;
+  isDataset: boolean;
+  inventoryTokens: readonly string[];
+  scannedCount: number;
+  loadingIntentCount: number;
+  hasMore: boolean;
+  manualFetchAvailable: boolean;
+  hasActiveFilters: boolean;
+}
+
+export interface ModelsCatalogPagination {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  sentinelRef: RefObject<HTMLDivElement | null>;
+  isLoadingMore: boolean;
+}
+
+export interface ModelsCatalogHandlers {
+  onSelect: (id: string) => void;
+  onFetchMore: () => void;
+  onClearFilters: () => void;
+  onRetry: () => void;
+  onInventoryChange?: () => void;
+  onSwitchDevice?: () => void;
+}
+
+function assignRef<T>(ref: RefObject<T | null>, value: T | null) {
+  (ref as { current: T | null }).current = value;
+}
+
+export const ModelsCatalog = memo(function ModelsCatalog({
+  state,
+  pagination,
+  handlers,
+}: {
+  state: ModelsCatalogState;
+  pagination: ModelsCatalogPagination;
+  handlers: ModelsCatalogHandlers;
+}) {
+  const {
+    tab,
+    discoverRows,
+    cachedRows,
+    localRows,
+    selectedId,
+    isLoading,
+    downloadedReady,
+    inventoryError,
+    inventoryWarning,
+    query,
+    activeCheckpoint,
+    activeGgufVariant,
+    searchError,
+    online,
+    isDataset,
+    inventoryTokens,
+    scannedCount,
+    loadingIntentCount,
+    hasMore,
+    manualFetchAvailable,
+    hasActiveFilters,
+  } = state;
+  const { scrollRef, sentinelRef, isLoadingMore } = pagination;
+  const {
+    onSelect,
+    onFetchMore,
+    onClearFilters,
+    onRetry,
+    onInventoryChange,
+    onSwitchDevice,
+  } = handlers;
+  const [scrolled, setScrolled] = useState(false);
+  const [streamingActive, setStreamingActive] = useState(false);
+  const previousScannedCountRef = useRef(scannedCount);
+  const previousLoadingIntentRef = useRef(loadingIntentCount);
+  const discoverScrollRef = useRef<HTMLDivElement>(null);
+  const downloadedScrollRef = useRef<HTMLDivElement>(null);
+  const [discoverScrollEl, setDiscoverScrollEl] = useState<HTMLDivElement | null>(
+    null,
+  );
+  const [downloadedScrollEl, setDownloadedScrollEl] =
+    useState<HTMLDivElement | null>(null);
+  const activeTabRef = useRef(tab);
+  // Per-tab scroll positions. Some browsers drop the hidden pane's scrollTop, so
+  // mirror it live via the scroll listener and restore on tab entry.
+  const savedScrollTopsRef = useRef<Record<ModelsTab, number>>({
+    discover: 0,
+    downloaded: 0,
+  });
+  const savedScrollHeightsRef = useRef<Record<ModelsTab, number>>({
+    discover: 0,
+    downloaded: 0,
+  });
+  const deviceType = usePlatformStore((s) => s.deviceType);
+
+  const setDiscoverScrollNode = useCallback((node: HTMLDivElement | null) => {
+    discoverScrollRef.current = node;
+    setDiscoverScrollEl(node);
+  }, []);
+
+  const setDownloadedScrollNode = useCallback((node: HTMLDivElement | null) => {
+    downloadedScrollRef.current = node;
+    setDownloadedScrollEl(node);
+  }, []);
+
+  // Restore the incoming pane's scrollTop and rebind scrollRef. Don't read scrollTop
+  // off the outgoing pane: overflow toggling can clamp it to 0 before this runs, so
+  // trust the live listener mirror instead and avoid that race.
+  useLayoutEffect(() => {
+    let restoreFrame: number | null = null;
+    const previousTab = activeTabRef.current;
+    if (previousTab !== tab) {
+      const previousEl =
+        previousTab === "discover"
+          ? discoverScrollRef.current
+          : downloadedScrollRef.current;
+      if (previousEl) {
+        savedScrollTopsRef.current[previousTab] = previousEl.scrollTop;
+        savedScrollHeightsRef.current[previousTab] = previousEl.scrollHeight;
+      }
+    }
+    const nextEl =
+      tab === "discover"
+        ? discoverScrollRef.current
+        : downloadedScrollRef.current;
+    if (nextEl) {
+      const saved = savedScrollTopsRef.current[tab];
+      if (nextEl.scrollTop !== saved) {
+        nextEl.scrollTop = saved;
+      }
+      savedScrollHeightsRef.current[tab] = nextEl.scrollHeight;
+      restoreFrame = window.requestAnimationFrame(() => {
+        if (activeTabRef.current === tab && nextEl.scrollTop !== saved) {
+          nextEl.scrollTop = saved;
+        }
+      });
+    }
+    activeTabRef.current = tab;
+    assignRef(scrollRef, nextEl);
+    const nextScrolled = (nextEl?.scrollTop ?? 0) > 0;
+    setScrolled((current) => (current === nextScrolled ? current : nextScrolled));
+    return () => {
+      if (restoreFrame !== null) {
+        window.cancelAnimationFrame(restoreFrame);
+      }
+    };
+  }, [scrollRef, tab]);
+
+  useEffect(() => {
+    const discoverEl = discoverScrollRef.current;
+    const downloadedEl = downloadedScrollRef.current;
+    // Mirror scrollTop ONLY from the active pane; the inactive pane can fire
+    // spurious scroll events that would overwrite the saved position with 0.
+    const onDiscoverScroll = () => {
+      if (!discoverEl || activeTabRef.current !== "discover") {
+        return;
+      }
+      savedScrollTopsRef.current.discover = discoverEl.scrollTop;
+      savedScrollHeightsRef.current.discover = discoverEl.scrollHeight;
+      const nextScrolled = discoverEl.scrollTop > 0;
+      setScrolled((current) =>
+        current === nextScrolled ? current : nextScrolled,
+      );
+    };
+    const onDownloadedScroll = () => {
+      if (!downloadedEl || activeTabRef.current !== "downloaded") {
+        return;
+      }
+      savedScrollTopsRef.current.downloaded = downloadedEl.scrollTop;
+      savedScrollHeightsRef.current.downloaded = downloadedEl.scrollHeight;
+      const nextScrolled = downloadedEl.scrollTop > 0;
+      setScrolled((current) =>
+        current === nextScrolled ? current : nextScrolled,
+      );
+    };
+    discoverEl?.addEventListener("scroll", onDiscoverScroll, { passive: true });
+    downloadedEl?.addEventListener("scroll", onDownloadedScroll, {
+      passive: true,
+    });
+    return () => {
+      discoverEl?.removeEventListener("scroll", onDiscoverScroll);
+      downloadedEl?.removeEventListener("scroll", onDownloadedScroll);
+    };
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (
+        scrollRef.current === discoverScrollRef.current ||
+        scrollRef.current === downloadedScrollRef.current
+      ) {
+        assignRef(scrollRef, null);
+      }
+    },
+    [scrollRef],
+  );
+
+  useEffect(() => {
+    // Only the Discover tab drives the streaming loading bar.
+    if (tab !== "discover") {
+      previousScannedCountRef.current = scannedCount;
+      previousLoadingIntentRef.current = loadingIntentCount;
+      setStreamingActive((current) => (current ? false : current));
+      return;
+    }
+    const previousCount = previousScannedCountRef.current;
+    const previousLoadingIntent = previousLoadingIntentRef.current;
+    previousScannedCountRef.current = scannedCount;
+    previousLoadingIntentRef.current = loadingIntentCount;
+    const rowsScanned = scannedCount > previousCount;
+    const fetchRequested = loadingIntentCount > previousLoadingIntent;
+    let nextActive = false;
+    let linger = false;
+    if (isLoading || isLoadingMore) {
+      nextActive = true;
+    } else if (rowsScanned || fetchRequested) {
+      nextActive = true;
+      linger = true;
+    }
+    setStreamingActive((current) => (current === nextActive ? current : nextActive));
+    const timer = linger
+      ? window.setTimeout(() => setStreamingActive(false), 1400)
+      : null;
+    return () => {
+      if (timer !== null) {
+        window.clearTimeout(timer);
+      }
+    };
+  }, [tab, isLoading, isLoadingMore, scannedCount, loadingIntentCount]);
+
+  const showDiscoverLoading = tab === "discover" && streamingActive;
+  // overflow-y stays `auto` on BOTH panes: toggling to `hidden` would clamp the
+  // inactive pane's scrollTop to 0 and corrupt our mirror. Visibility +
+  // pointer-events-none hides it while preserving native scroll state.
+  const scrollPaneClassName =
+    "absolute inset-0 min-h-0 overflow-y-auto pb-6 pl-5 pr-3 pt-0 [overflow-anchor:none] [scrollbar-gutter:stable] [scrollbar-width:thin]";
+  const discoverActive = tab === "discover";
+  const downloadedActive = tab === "downloaded";
+  const discoverInactiveHeight = Math.max(
+    savedScrollHeightsRef.current.discover,
+    discoverRows.length * CATALOG_ROW_HEIGHT_PX,
+  );
+  const downloadedInactiveHeight = Math.max(
+    savedScrollHeightsRef.current.downloaded,
+    (cachedRows.length + localRows.length) * CATALOG_ROW_HEIGHT_PX,
+  );
+
+  return (
+    <div className="relative flex h-full min-h-0 flex-1 flex-col overflow-hidden">
+      <div
+        aria-hidden="true"
+        className={cn(
+          "mx-5 shrink-0 border-t transition-colors",
+          scrolled ? "border-border" : "border-transparent",
+        )}
+      />
+      {/* Banner sits outside the scroll container so toggling it never shifts virtualized rows. */}
+      {downloadedActive && inventoryWarning && (
+        <InventoryWarningRow
+          isDataset={isDataset}
+          onRetry={() => onInventoryChange?.()}
+        />
+      )}
+      <div className="relative min-h-0 flex-1">
+        <div
+          ref={setDiscoverScrollNode}
+          data-hub-scroll="true"
+          aria-hidden={!discoverActive}
+          tabIndex={discoverActive ? undefined : -1}
+          className={cn(
+            scrollPaneClassName,
+            discoverActive ? "visible" : "pointer-events-none invisible",
+          )}
+        >
+          {discoverActive ? (
+            <DiscoverList
+              discoverRows={discoverRows}
+              selectedId={selectedId}
+              onSelect={onSelect}
+              isLoading={isLoading}
+              query={query}
+              scrollElement={discoverScrollEl}
+              sentinelRef={sentinelRef}
+              activeCheckpoint={activeCheckpoint}
+              searchError={searchError}
+              online={online}
+              isDataset={isDataset}
+              deviceType={deviceType}
+              scannedCount={scannedCount}
+              isLoadingMore={isLoadingMore}
+              hasMore={hasMore}
+              manualFetchAvailable={manualFetchAvailable}
+              hasActiveFilters={hasActiveFilters}
+              onFetchMore={onFetchMore}
+              onClearFilters={onClearFilters}
+              onRetry={onRetry}
+              onSwitchDevice={onSwitchDevice}
+            />
+          ) : (
+            <div
+              aria-hidden="true"
+              style={{ height: discoverInactiveHeight }}
+            />
+          )}
+        </div>
+        <div
+          ref={setDownloadedScrollNode}
+          data-hub-scroll="true"
+          aria-hidden={!downloadedActive}
+          tabIndex={downloadedActive ? undefined : -1}
+          className={cn(
+            scrollPaneClassName,
+            downloadedActive ? "visible" : "pointer-events-none invisible",
+          )}
+        >
+          {downloadedActive ? (
+            <DownloadedList
+              cachedRows={cachedRows}
+              localRows={localRows}
+              selectedId={selectedId}
+              onSelect={onSelect}
+              downloadedReady={downloadedReady}
+              inventoryError={inventoryError}
+              query={query}
+              scrollElement={downloadedScrollEl}
+              activeCheckpoint={activeCheckpoint}
+              activeGgufVariant={activeGgufVariant}
+              isDataset={isDataset}
+              inventoryTokens={inventoryTokens}
+              deviceType={deviceType}
+              onInventoryChange={onInventoryChange}
+            />
+          ) : (
+            <div
+              aria-hidden="true"
+              style={{ height: downloadedInactiveHeight }}
+            />
+          )}
+        </div>
+      </div>
+      <output
+        aria-live="polite"
+        aria-label={showDiscoverLoading ? "Loading models" : undefined}
+        className={cn(
+          "pointer-events-none absolute inset-x-0 bottom-0 z-10 h-[3px] transition-opacity duration-150",
+          showDiscoverLoading ? "opacity-100" : "opacity-0",
+        )}
+      >
+        <div
+          className="hub-loading-bar"
+          data-active={showDiscoverLoading || undefined}
+        />
+      </output>
+    </div>
+  );
+});
diff --git a/studio/frontend/src/features/hub/catalog/models-header.tsx b/studio/frontend/src/features/hub/catalog/models-header.tsx
new file mode 100644
index 0000000000..d1b3acced9
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/models-header.tsx
@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { HfTokenIndicator } from "@/features/hub/components/hf-token-indicator";
+import { PageHeading } from "@/features/hub/components/page-heading";
+import { TransportToggle } from "./transport-toggle";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import {
+  ChipIcon,
+  Database02Icon,
+  Logout01Icon,
+  PackageIcon,
+  RamMemoryIcon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import { HugeiconsIcon } from "@hugeicons/react";
+
+function StatPill({
+  icon,
+  label,
+  value,
+  tone = "default",
+}: {
+  icon: IconSvgElement;
+  label: string;
+  value: string;
+  tone?: "default" | "active";
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div
+          className={cn(
+            "inline-flex cursor-default items-center gap-1.5 px-2.5 py-1 text-[11.5px] transition-colors duration-150",
+            tone === "active"
+              ? "rounded-[11px] bg-emerald-500/10 text-emerald-700 ring-1 ring-inset ring-emerald-500/20 dark:text-emerald-300"
+              : "hub-tag-soft text-muted-foreground hover:text-foreground/80",
+          )}
+        >
+          <HugeiconsIcon icon={icon} strokeWidth={1.75} className="size-3.5" />
+          <span className="font-medium tabular-nums">{value}</span>
+        </div>
+      </TooltipTrigger>
+      <TooltipContent className="tooltip-compact">{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+export function ModelsHeader({
+  cachedCount,
+  localCount,
+  isDataset,
+  gpuLabel,
+  ramLabel,
+  activeCheckpoint,
+  activeGgufVariant,
+  onEject,
+}: {
+  cachedCount: number;
+  localCount: number;
+  isDataset: boolean;
+  gpuLabel: string;
+  ramLabel: string;
+  activeCheckpoint: string | null;
+  activeGgufVariant: string | null;
+  onEject: () => void;
+}) {
+  return (
+    <header className="font-heading flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between">
+      <PageHeading
+        title="Hub"
+        subtitle={
+          isDataset
+            ? "Discover, download, and train on datasets locally."
+            : "Discover, download, and run inference models locally."
+        }
+      />
+
+      <div className="flex flex-wrap items-center gap-1.5">
+        <HfTokenIndicator />
+        <TransportToggle />
+        <StatPill
+          icon={PackageIcon}
+          label="Cache"
+          value={String(cachedCount)}
+        />
+        <StatPill
+          icon={Database02Icon}
+          label="Local"
+          value={String(localCount)}
+        />
+        <StatPill icon={ChipIcon} label="VRAM" value={gpuLabel} />
+        <StatPill icon={RamMemoryIcon} label="CPU RAM" value={ramLabel} />
+
+        {activeCheckpoint && (
+          <div className="hub-tag-soft ml-1 inline-flex items-center gap-1.5 px-2 py-1 text-[11.5px]">
+            <span
+              className="size-1.5 rounded-full bg-emerald-500"
+              aria-hidden="true"
+            />
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span className="max-w-[120px] cursor-default truncate font-medium text-primary">
+                  {activeCheckpoint}
+                  {activeGgufVariant ? ` · ${activeGgufVariant}` : ""}
+                </span>
+              </TooltipTrigger>
+              <TooltipContent
+                side="bottom"
+                sideOffset={6}
+                className="tooltip-compact"
+              >
+                {activeCheckpoint}
+                {activeGgufVariant ? ` · ${activeGgufVariant}` : ""}
+              </TooltipContent>
+            </Tooltip>
+            <button
+              type="button"
+              onClick={onEject}
+              className="-mr-0.5 ml-0.5 inline-flex cursor-pointer items-center gap-1 rounded-md px-1.5 text-[11px] text-muted-foreground transition-colors hover:text-foreground"
+            >
+              <HugeiconsIcon
+                icon={Logout01Icon}
+                strokeWidth={1.75}
+                className="size-3"
+              />
+              Eject
+            </button>
+          </div>
+        )}
+      </div>
+    </header>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/models-toolbar.tsx b/studio/frontend/src/features/hub/catalog/models-toolbar.tsx
new file mode 100644
index 0000000000..82033642bd
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/models-toolbar.tsx
@@ -0,0 +1,405 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Input } from "@/components/ui/input";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import {
+  AiChipIcon,
+  Database02Icon,
+  FolderSearchIcon,
+  Refresh01Icon,
+  Search01Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { HfSortKey } from "@/features/hub/hooks/use-hub-model-search";
+import type {
+  CapabilityFilter,
+  ModelFormatFilter,
+  ModelsTab,
+  ResourceTypeFilter,
+} from "../types";
+import {
+  CHANNEL_PRESETS,
+  type ChannelId,
+  findChannel,
+} from "../lib/channels";
+import {
+  CAPABILITY_FILTER_OPTIONS,
+  FORMAT_FILTER_OPTIONS,
+} from "../lib/view-models";
+import { HubOptionMenu, type HubOption } from "./hub-option-menu";
+import { memo, useMemo } from "react";
+
+const SORT_OPTIONS: ReadonlyArray<{
+  value: HfSortKey;
+  label: string;
+}> = [
+  { value: "trendingScore", label: "Trending" },
+  { value: "likes", label: "Most likes" },
+  { value: "downloads", label: "Most downloads" },
+  { value: "lastModified", label: "Recently updated" },
+  { value: "createdAt", label: "Newest" },
+];
+
+type ChannelOptionValue = "all" | ChannelId;
+
+export const ModelsToolbar = memo(function ModelsToolbar({
+  tab,
+  onTabChange,
+  query,
+  onQueryChange,
+  isLoading,
+  sortBy,
+  onSortChange,
+  resourceType,
+  onResourceTypeChange,
+  formatFilter,
+  onFormatFilterChange,
+  capabilityFilter,
+  onCapabilityFilterChange,
+  activeChannelId,
+  onChannelSelect,
+  onRefresh,
+  onManageLocalFolders,
+}: {
+  tab: ModelsTab;
+  onTabChange: (tab: ModelsTab) => void;
+  query: string;
+  onQueryChange: (value: string) => void;
+  isLoading: boolean;
+  onRefresh: () => void;
+  sortBy: HfSortKey;
+  onSortChange: (value: HfSortKey) => void;
+  resourceType: ResourceTypeFilter;
+  onResourceTypeChange: (value: ResourceTypeFilter) => void;
+  formatFilter: ModelFormatFilter;
+  onFormatFilterChange: (value: ModelFormatFilter) => void;
+  capabilityFilter: CapabilityFilter;
+  onCapabilityFilterChange: (value: CapabilityFilter) => void;
+  activeChannelId: ChannelId | null;
+  onChannelSelect: (id: ChannelId | null) => void;
+  onManageLocalFolders: () => void;
+}) {
+  const activeChannel = findChannel(activeChannelId);
+  const isDataset = resourceType === "datasets";
+  const channelValue: ChannelOptionValue = activeChannelId ?? "all";
+  const formatOptions = useMemo<HubOption<ModelFormatFilter>[]>(
+    () =>
+      FORMAT_FILTER_OPTIONS.map((option) => ({
+        value: option.value,
+        triggerLabel: option.label,
+        label: (
+          <>
+            {option.value === "gguf" && (
+              <span className="inline-block size-1.5 shrink-0 rounded-full bg-format-gguf" />
+            )}
+            {option.value === "checkpoint" && (
+              <span className="inline-block size-1.5 shrink-0 rounded-full bg-format-checkpoint" />
+            )}
+            {option.label}
+          </>
+        ),
+      })),
+    [],
+  );
+  const capabilityOptions = useMemo<HubOption<CapabilityFilter>[]>(
+    () =>
+      CAPABILITY_FILTER_OPTIONS.map((option) => ({
+        value: option.value,
+        label: option.label,
+      })),
+    [],
+  );
+  const sortOptions = useMemo<HubOption<HfSortKey>[]>(
+    () =>
+      SORT_OPTIONS.map((option) => ({
+        value: option.value,
+        label: option.label,
+      })),
+    [],
+  );
+  const channelOptions = useMemo<HubOption<ChannelOptionValue>[]>(
+    () => [
+      { value: "all", label: "All models" },
+      ...CHANNEL_PRESETS.map((preset) => ({
+        value: preset.id,
+        checkClassName: "text-primary",
+        label: (
+          <span className="flex w-full min-w-0 items-start gap-2">
+            <HugeiconsIcon
+              icon={preset.icon}
+              strokeWidth={1.75}
+              className="mt-0.5 size-4 shrink-0 text-muted-foreground"
+            />
+            <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+              <span className="min-w-0 truncate">{preset.label}</span>
+              <span className="min-w-0 whitespace-normal break-words text-[11px] leading-snug text-muted-foreground">
+                {preset.hint}
+              </span>
+            </span>
+          </span>
+        ),
+      })),
+    ],
+    [],
+  );
+  const triggerBase = cn(
+    "field-trigger hub-menu-trigger field-soft transition-colors",
+    "focus-visible:ring-0 focus-visible:ring-offset-0 focus-visible:border-border",
+  );
+  return (
+    <div className="flex min-w-0 flex-col gap-2 lg:flex-row lg:flex-wrap lg:items-center">
+      <div
+        className={cn(
+          "hub-menu-trigger hub-tab-toggle relative inline-flex h-9 w-full shrink-0 items-center rounded-full lg:w-[240px]",
+        )}
+        role="radiogroup"
+        aria-label="View"
+      >
+        <span
+          aria-hidden="true"
+          className={cn(
+            "hub-tab-toggle-pill",
+            "pointer-events-none absolute inset-y-0 left-0 w-1/2 rounded-full transition-transform duration-200 ease-out",
+            tab === "downloaded" ? "translate-x-full" : "translate-x-0",
+          )}
+        />
+        <button
+          type="button"
+          role="radio"
+          aria-checked={tab === "discover"}
+          onClick={() => onTabChange("discover")}
+          className={cn(
+            "relative z-10 inline-flex h-9 flex-1 items-center justify-center rounded-full px-3 text-[12.5px] transition-colors",
+            tab === "discover"
+              ? "text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          Discover
+        </button>
+        <button
+          type="button"
+          role="radio"
+          aria-checked={tab === "downloaded"}
+          onClick={() => onTabChange("downloaded")}
+          className={cn(
+            "relative z-10 inline-flex h-9 flex-1 items-center justify-center rounded-full px-3 text-[12.5px] transition-colors",
+            tab === "downloaded"
+              ? "text-foreground"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          On Device
+        </button>
+      </div>
+
+      <div className="flex min-w-0 items-center gap-2 lg:flex-[1_1_280px]">
+        <div
+          className="hub-menu-trigger hub-tab-toggle relative inline-flex h-9 shrink-0 items-center rounded-full"
+          role="radiogroup"
+          aria-label="Resource type"
+        >
+          <span
+            aria-hidden="true"
+            className={cn(
+              "hub-tab-toggle-pill",
+              "pointer-events-none absolute inset-y-0 left-0 w-1/2 rounded-full transition-transform duration-200 ease-out",
+              resourceType === "datasets" ? "translate-x-full" : "translate-x-0",
+            )}
+          />
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                role="radio"
+                aria-checked={resourceType === "models"}
+                aria-label="Models"
+                onClick={() => onResourceTypeChange("models")}
+                className={cn(
+                  "relative z-10 inline-flex h-9 w-9 items-center justify-center rounded-full transition-colors",
+                  resourceType === "models"
+                    ? "text-foreground"
+                    : "text-muted-foreground hover:text-foreground",
+                )}
+              >
+                <HugeiconsIcon
+                  icon={AiChipIcon}
+                  strokeWidth={1.75}
+                  className="size-4"
+                />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={6}>
+              Models
+            </TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                role="radio"
+                aria-checked={resourceType === "datasets"}
+                aria-label="Datasets"
+                onClick={() => onResourceTypeChange("datasets")}
+                className={cn(
+                  "relative z-10 inline-flex h-9 w-9 items-center justify-center rounded-full transition-colors",
+                  resourceType === "datasets"
+                    ? "text-foreground"
+                    : "text-muted-foreground hover:text-foreground",
+                )}
+              >
+                <HugeiconsIcon
+                  icon={Database02Icon}
+                  strokeWidth={1.75}
+                  className="size-4"
+                />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={6}>
+              Datasets
+            </TooltipContent>
+          </Tooltip>
+        </div>
+
+        <div className="relative min-w-0 flex-1">
+          <HugeiconsIcon
+            icon={Search01Icon}
+            strokeWidth={1.8}
+            className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+          />
+          <Input
+            value={query}
+            onChange={(event) => onQueryChange(event.target.value)}
+            placeholder={
+              tab === "downloaded"
+                ? `Search on-device ${isDataset ? "datasets" : "models"}`
+                : "Search Hugging Face"
+            }
+            className="field-soft h-9 rounded-full pl-10 pr-10 text-[12.5px] placeholder:text-muted-foreground/80"
+          />
+          {tab === "discover" && isLoading && (
+            <Spinner className="pointer-events-none absolute right-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+          )}
+        </div>
+      </div>
+
+      <div className="flex min-w-0 flex-wrap items-center gap-2 lg:flex-[0_1_auto] lg:justify-end">
+        {tab === "downloaded" && !isDataset && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={onManageLocalFolders}
+                className={cn(
+                  triggerBase,
+                  "field-filter inline-flex h-9 shrink-0 items-center gap-1.5 rounded-full px-3 text-[12.5px]",
+                )}
+              >
+                <HugeiconsIcon
+                  icon={FolderSearchIcon}
+                  strokeWidth={1.75}
+                  className="size-3.5"
+                />
+                Add folder
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={6}>
+              Manage local model folders
+            </TooltipContent>
+          </Tooltip>
+        )}
+
+        {!isDataset && (
+          <HubOptionMenu
+            value={formatFilter}
+            options={formatOptions}
+            onValueChange={onFormatFilterChange}
+            ariaLabel="Format filter"
+            className={cn(triggerBase, "min-w-[124px]")}
+          />
+        )}
+
+        {tab === "discover" && !isDataset && (
+          <HubOptionMenu
+            value={capabilityFilter}
+            options={capabilityOptions}
+            onValueChange={onCapabilityFilterChange}
+            ariaLabel="Capability filter"
+            className={cn(triggerBase, "min-w-[136px]")}
+          />
+        )}
+
+        {tab === "discover" && (
+          <HubOptionMenu
+            value={sortBy}
+            options={sortOptions}
+            onValueChange={onSortChange}
+            ariaLabel="Sort models"
+            className={cn(triggerBase, "min-w-[140px]")}
+          />
+        )}
+
+        {tab === "discover" && !isDataset && (
+          <HubOptionMenu
+            value={channelValue}
+            options={channelOptions}
+            onValueChange={(next) =>
+              onChannelSelect(next === "all" ? null : next)
+            }
+            ariaLabel="Curated channels"
+            title={activeChannel ? activeChannel.label : "Curated channels"}
+            align="end"
+            showChevron={false}
+            triggerContent={
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "hub-verified-badge size-4",
+                  activeChannel ? "text-primary" : "text-muted-foreground",
+                )}
+              />
+            }
+            className={cn(
+              triggerBase,
+              "field-filter inline-flex size-9 shrink-0 items-center justify-center rounded-full p-0",
+            )}
+            contentClassName="w-[calc(100vw-1.5rem)] sm:w-[320px]"
+          />
+        )}
+
+        {tab === "discover" && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                aria-label="Refresh from Hugging Face"
+                onClick={onRefresh}
+                className={cn(
+                  triggerBase,
+                  "field-filter inline-flex size-9 shrink-0 items-center justify-center rounded-full p-0",
+                )}
+              >
+                <HugeiconsIcon
+                  icon={Refresh01Icon}
+                  strokeWidth={1.75}
+                  className={cn("size-4", isLoading && "animate-spin")}
+                />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" sideOffset={6}>
+              Refresh from Hugging Face
+            </TooltipContent>
+          </Tooltip>
+        )}
+
+      </div>
+    </div>
+  );
+});
diff --git a/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx b/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
new file mode 100644
index 0000000000..94726b9295
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/on-device-folders-dialog.tsx
@@ -0,0 +1,370 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { FolderBrowser } from "@/components/assistant-ui/model-selector/folder-browser";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import {
+  type ScanFolderInfo,
+  addScanFolder,
+  listScanFolders,
+  removeScanFolder,
+} from "@/features/hub/inventory";
+import { cn } from "@/lib/utils";
+import {
+  Delete02Icon,
+  FileSearchIcon,
+  FolderAddIcon,
+  FolderOpenIcon,
+  FolderSearchIcon,
+  PlusSignIcon,
+  RefreshIcon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { toast } from "@/lib/toast";
+
+function pathTail(path: string): string {
+  const parts = path.split(/[\\/]/).filter(Boolean);
+  return parts.at(-1) ?? path;
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function OnDeviceFoldersDialog({
+  open,
+  onOpenChange,
+  onInventoryChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onInventoryChange?: () => void;
+}) {
+  const [folders, setFolders] = useState<ScanFolderInfo[]>([]);
+  const [path, setPath] = useState("");
+  const [browserOpen, setBrowserOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState<"add" | `remove:${number}` | null>(
+    null,
+  );
+  const refreshIdRef = useRef(0);
+  const mutationVersionRef = useRef(0);
+
+  const sortedFolders = useMemo(
+    () => [...folders].sort((a, b) => a.path.localeCompare(b.path)),
+    [folders],
+  );
+
+  const refreshFolders = useCallback(() => {
+    const refreshId = refreshIdRef.current + 1;
+    const mutationVersion = mutationVersionRef.current;
+    refreshIdRef.current = refreshId;
+    setLoading(true);
+    setError(null);
+    listScanFolders()
+      .then((nextFolders) => {
+        if (refreshIdRef.current !== refreshId) {
+          return;
+        }
+        if (mutationVersionRef.current !== mutationVersion) {
+          return;
+        }
+        setFolders(nextFolders);
+      })
+      .catch((err) => {
+        if (refreshIdRef.current === refreshId) {
+          setError(formatError(err));
+        }
+      })
+      .finally(() => {
+        if (refreshIdRef.current === refreshId) {
+          setLoading(false);
+        }
+      });
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+    const timer = window.setTimeout(refreshFolders, 0);
+    return () => window.clearTimeout(timer);
+  }, [open, refreshFolders]);
+
+  const handleInventoryChanged = useCallback(() => {
+    onInventoryChange?.();
+  }, [onInventoryChange]);
+
+  const handleAdd = useCallback(
+    async (rawPath: string) => {
+      const nextPath = rawPath.trim();
+      if (!nextPath || pending) return;
+      setPending("add");
+      setError(null);
+      try {
+        const folder = await addScanFolder(nextPath);
+        setPath("");
+        mutationVersionRef.current += 1;
+        setFolders((current) => {
+          const withoutDuplicate = current.filter((row) => row.id !== folder.id);
+          return [...withoutDuplicate, folder];
+        });
+        toast.success("Location added", {
+          description: pathTail(folder.path),
+        });
+        handleInventoryChanged();
+      } catch (err) {
+        const message = formatError(err);
+        setError(message);
+        toast.error("Couldn't add location", { description: message });
+      } finally {
+        setPending(null);
+      }
+    },
+    [handleInventoryChanged, pending],
+  );
+
+  const handleRemove = useCallback(
+    async (folder: ScanFolderInfo) => {
+      const key = `remove:${folder.id}` as const;
+      if (pending) return;
+      setPending(key);
+      setError(null);
+      try {
+        await removeScanFolder(folder.id);
+        mutationVersionRef.current += 1;
+        setFolders((current) => current.filter((row) => row.id !== folder.id));
+        toast.success("Location removed", {
+          description: pathTail(folder.path),
+        });
+        handleInventoryChanged();
+      } catch (err) {
+        const message = formatError(err);
+        setError(message);
+        toast.error("Couldn't remove location", { description: message });
+      } finally {
+        setPending(null);
+      }
+    },
+    [handleInventoryChanged, pending],
+  );
+
+  return (
+    <>
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent
+          className="max-w-[600px] gap-0 overflow-hidden p-0"
+          overlayClassName="bg-black/20 backdrop-blur-none"
+        >
+          <DialogHeader className="border-b border-border/60 px-5 py-4">
+            <DialogTitle className="text-[15px]">On-device locations</DialogTitle>
+            <DialogDescription className="sr-only">
+              Hugging Face model folders, GGUF files, and adapters are indexed here.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-4 px-5 py-4">
+            <div className="rounded-[14px] border border-border/70 bg-muted/20 p-3">
+              <div className="mb-2 flex items-center gap-2 text-[12px] font-medium text-foreground">
+                <HugeiconsIcon
+                  icon={FolderAddIcon}
+                  strokeWidth={1.75}
+                  className="size-3.5 text-muted-foreground"
+                />
+                Add location
+              </div>
+
+              <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+                <div className="relative min-w-0 flex-1">
+                  <HugeiconsIcon
+                    icon={FileSearchIcon}
+                    strokeWidth={1.75}
+                    className="pointer-events-none absolute left-3 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground"
+                  />
+                  <Input
+                    value={path}
+                    onChange={(event) => setPath(event.target.value)}
+                    onKeyDown={(event) => {
+                      if (event.key !== "Enter") return;
+                      event.preventDefault();
+                      void handleAdd(path);
+                    }}
+                    placeholder="Paste model folder or file path"
+                    className="field-soft h-9 rounded-full pl-9 pr-3 font-mono text-[12px] placeholder:font-sans"
+                  />
+                </div>
+                <div className="flex shrink-0 items-center gap-2">
+                  <Tooltip>
+                    <TooltipTrigger asChild={true}>
+                      <Button
+                        type="button"
+                        variant="outline"
+                        size="icon-sm"
+                        onClick={() => setBrowserOpen(true)}
+                        aria-label="Browse locations"
+                        className="size-9 rounded-full"
+                      >
+                        <HugeiconsIcon
+                          icon={FolderSearchIcon}
+                          strokeWidth={1.75}
+                          className="size-4"
+                        />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" className="tooltip-compact">
+                      Browse
+                    </TooltipContent>
+                  </Tooltip>
+                  <Button
+                    type="button"
+                    size="sm"
+                    onClick={() => void handleAdd(path)}
+                    disabled={!path.trim() || pending !== null}
+                    className="h-9 rounded-full px-3 text-[12.5px]"
+                  >
+                    {pending === "add" ? (
+                      <Spinner className="size-3.5" />
+                    ) : (
+                      <HugeiconsIcon
+                        icon={PlusSignIcon}
+                        strokeWidth={1.75}
+                        data-icon="inline-start"
+                        className="size-3.5"
+                      />
+                    )}
+                    Add
+                  </Button>
+                </div>
+              </div>
+            </div>
+
+            {error ? (
+              <div className="rounded-[10px] border border-destructive/20 bg-destructive/5 px-3 py-2 text-[12px] text-destructive">
+                {error}
+              </div>
+            ) : null}
+
+            <div className="overflow-hidden rounded-[14px] border border-border/70">
+              <div className="flex h-10 items-center justify-between border-b border-border/60 px-3">
+                <span className="text-[12px] font-medium text-foreground">
+                  Indexed locations
+                </span>
+                <Tooltip>
+                  <TooltipTrigger asChild={true}>
+                    <button
+                      type="button"
+                      aria-label="Refresh locations"
+                      onClick={refreshFolders}
+                      disabled={loading}
+                      className="inline-flex size-7 items-center justify-center rounded-[8px] text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-50"
+                    >
+                      <HugeiconsIcon
+                        icon={RefreshIcon}
+                        strokeWidth={1.75}
+                        className={cn("size-3.5", loading && "animate-spin")}
+                      />
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom" className="tooltip-compact">
+                    Refresh
+                  </TooltipContent>
+                </Tooltip>
+              </div>
+
+              <div className="max-h-64 overflow-y-auto">
+                {loading ? (
+                  <div className="flex h-24 items-center justify-center gap-2 text-[12px] text-muted-foreground">
+                    <Spinner className="size-3.5" />
+                    Loading locations...
+                  </div>
+                ) : sortedFolders.length === 0 ? (
+                  <div className="flex h-28 flex-col items-center justify-center gap-2 px-4 text-center text-[12px] text-muted-foreground">
+                    <HugeiconsIcon
+                      icon={FolderOpenIcon}
+                      strokeWidth={1.75}
+                      className="size-5 text-muted-foreground/60"
+                    />
+                    No custom locations
+                  </div>
+                ) : (
+                  sortedFolders.map((folder) => {
+                    const removing = pending === `remove:${folder.id}`;
+                    return (
+                      <div
+                        key={folder.id}
+                        className="flex min-h-12 items-center gap-3 border-b border-border/50 px-3 py-2 last:border-b-0"
+                      >
+                        <div className="flex size-8 shrink-0 items-center justify-center rounded-[9px] bg-muted text-muted-foreground">
+                          <HugeiconsIcon
+                            icon={FolderOpenIcon}
+                            strokeWidth={1.75}
+                            className="size-4"
+                          />
+                        </div>
+                        <div className="min-w-0 flex-1">
+                          <p className="truncate text-[12.5px] font-medium text-foreground">
+                            {pathTail(folder.path)}
+                          </p>
+                          <p
+                            title={folder.path}
+                            className="truncate font-mono text-[10.5px] text-muted-foreground"
+                          >
+                            {folder.path}
+                          </p>
+                        </div>
+                        <Tooltip>
+                          <TooltipTrigger asChild={true}>
+                            <button
+                              type="button"
+                              aria-label={`Remove ${folder.path}`}
+                              onClick={() => void handleRemove(folder)}
+                              disabled={pending !== null}
+                              className="inline-flex size-8 shrink-0 items-center justify-center rounded-[9px] text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-50"
+                            >
+                              {removing ? (
+                                <Spinner className="size-3.5" />
+                              ) : (
+                                <HugeiconsIcon
+                                  icon={Delete02Icon}
+                                  strokeWidth={1.75}
+                                  className="size-4"
+                                />
+                              )}
+                            </button>
+                          </TooltipTrigger>
+                          <TooltipContent side="left" className="tooltip-compact">
+                            Remove from list
+                          </TooltipContent>
+                        </Tooltip>
+                      </div>
+                    );
+                  })
+                )}
+              </div>
+            </div>
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      <FolderBrowser
+        open={browserOpen}
+        onOpenChange={setBrowserOpen}
+        onSelect={(selectedPath) => void handleAdd(selectedPath)}
+      />
+    </>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/owner-avatar.tsx b/studio/frontend/src/features/hub/catalog/owner-avatar.tsx
new file mode 100644
index 0000000000..cb2adc0b05
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/owner-avatar.tsx
@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { cn } from "@/lib/utils";
+import { useEffect, useState } from "react";
+import { useHfOwnerAvatar } from "../lib/hf-owner-avatar";
+import {
+  type ProviderLogo,
+  resolveOwnerProviderLogo,
+} from "../lib/provider-logos";
+
+const PALETTE = [
+  "hsl(214 42% 42%)",
+  "hsl(172 32% 36%)",
+  "hsl(30 42% 42%)",
+  "hsl(348 36% 44%)",
+  "hsl(198 38% 40%)",
+  "hsl(140 26% 38%)",
+  "hsl(222 24% 46%)",
+  "hsl(16 34% 44%)",
+  "hsl(260 22% 48%)",
+  "hsl(44 44% 40%)",
+];
+
+function hashOwner(owner: string): number {
+  let h = 0;
+  for (let i = 0; i < owner.length; i++) {
+    h = (h * 31 + owner.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+type AvatarSize = "xs" | "sm" | "md" | "lg";
+
+const SIZES: Record<AvatarSize, string> = {
+  xs: "size-5 rounded-[6px] text-[9px]",
+  sm: "size-7 rounded-[8px] text-[11px]",
+  md: "size-9 rounded-[10px] text-[13px]",
+  lg: "size-12 rounded-[13px] text-[16px]",
+};
+
+const AVATAR_IMAGE_RETRY_BASE_MS = 60_000;
+const AVATAR_IMAGE_RETRY_MAX_MS = 30 * 60_000;
+
+interface FailedAvatarImage {
+  url: string;
+  failures: number;
+  retryReady: boolean;
+}
+
+function avatarImageRetryDelay(failures: number): number {
+  return Math.min(
+    AVATAR_IMAGE_RETRY_BASE_MS * 2 ** Math.max(failures - 1, 0),
+    AVATAR_IMAGE_RETRY_MAX_MS,
+  );
+}
+
+export function OwnerAvatar({
+  owner,
+  repoName,
+  size = "md",
+  className,
+}: {
+  owner: string;
+  // For an eligible owner (currently "unsloth"), match a known upstream provider
+  // and render its logo (e.g. an Unsloth Qwen2.5 re-upload shows the Qwen logo).
+  repoName?: string;
+  size?: AvatarSize;
+  className?: string;
+}) {
+  const providerLogo = resolveOwnerProviderLogo(owner, repoName);
+  if (providerLogo) {
+    return (
+      <ProviderLogoTile
+        provider={providerLogo}
+        size={size}
+        className={className}
+      />
+    );
+  }
+  return <DefaultAvatar owner={owner} size={size} className={className} />;
+}
+
+function ProviderLogoTile({
+  provider,
+  size,
+  className,
+}: {
+  provider: ProviderLogo;
+  size: AvatarSize;
+  className?: string;
+}) {
+  const altLabel = `${provider.name} logo`;
+  const bgClass =
+    provider.background === "white" ? "bg-white" : "bg-transparent";
+
+  if (provider.treatment === "original") {
+    const fit = provider.fit ?? "contain";
+    return (
+      <span
+        role="img"
+        aria-label={altLabel}
+        className={cn(
+          "hub-avatar-tile inline-flex shrink-0 items-center justify-center overflow-hidden",
+          bgClass,
+          SIZES[size],
+          className,
+        )}
+      >
+        <img
+          src={provider.logoPath}
+          alt=""
+          loading="lazy"
+          className={cn(
+            fit === "cover" ? "size-full object-cover" : "size-3/4 object-contain",
+          )}
+        />
+      </span>
+    );
+  }
+
+  // mono treatments paint a silhouette via CSS mask; host text color drives its color.
+  const colorClass =
+    provider.treatment === "mono-black" ? "text-black" : "text-foreground";
+  return (
+    <span
+      role="img"
+      aria-label={altLabel}
+      className={cn(
+        "hub-avatar-tile inline-flex shrink-0 items-center justify-center overflow-hidden",
+        bgClass,
+        colorClass,
+        SIZES[size],
+        className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className="size-3/4 bg-current"
+        style={{
+          mask: `url(${provider.logoPath}) center / contain no-repeat`,
+          WebkitMask: `url(${provider.logoPath}) center / contain no-repeat`,
+        }}
+      />
+    </span>
+  );
+}
+
+function DefaultAvatar({
+  owner,
+  size,
+  className,
+}: {
+  owner: string;
+  size: AvatarSize;
+  className?: string;
+}) {
+  const owned = owner.trim() || "?";
+  const initial = owned[0]?.toUpperCase() ?? "?";
+  const color = PALETTE[hashOwner(owned) % PALETTE.length];
+  const remoteUrl = useHfOwnerAvatar(owned);
+  const [failedImage, setFailedImage] = useState<FailedAvatarImage | null>(
+    null,
+  );
+  const imageBlocked =
+    Boolean(remoteUrl) &&
+    failedImage?.url === remoteUrl &&
+    !failedImage.retryReady;
+  const showImage = Boolean(remoteUrl) && !imageBlocked;
+
+  useEffect(() => {
+    const activeFailure =
+      remoteUrl && failedImage?.url === remoteUrl ? failedImage : null;
+    if (!activeFailure || activeFailure.retryReady) {
+      return;
+    }
+
+    const timer = globalThis.setTimeout(() => {
+      setFailedImage((current) =>
+        current?.url === remoteUrl && !current.retryReady
+          ? { ...current, retryReady: true }
+          : current,
+      );
+    }, avatarImageRetryDelay(activeFailure.failures));
+    return () => globalThis.clearTimeout(timer);
+  }, [remoteUrl, failedImage]);
+
+  return (
+    <span
+      style={showImage ? undefined : { backgroundColor: color }}
+      className={cn(
+        "hub-avatar-tile inline-flex shrink-0 items-center justify-center overflow-hidden font-semibold text-white",
+        SIZES[size],
+        className,
+      )}
+      aria-hidden="true"
+    >
+      {showImage ? (
+        <img
+          src={remoteUrl ?? ""}
+          alt=""
+          loading="lazy"
+          className="size-full object-cover"
+          onLoad={() => setFailedImage(null)}
+          onError={() => {
+            if (!remoteUrl) {
+              return;
+            }
+            setFailedImage((current) => ({
+              url: remoteUrl,
+              failures: current?.url === remoteUrl ? current.failures + 1 : 1,
+              retryReady: false,
+            }));
+          }}
+        />
+      ) : (
+        initial
+      )}
+    </span>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/path-info-button.tsx b/studio/frontend/src/features/hub/catalog/path-info-button.tsx
new file mode 100644
index 0000000000..c2c897412c
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/path-info-button.tsx
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import {
+  Copy01Icon,
+  FolderSearchIcon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { MouseEvent } from "react";
+import { useState } from "react";
+import { useCopyFeedback } from "../hooks/use-copy-feedback";
+
+export function PathInfoButton({
+  path,
+  title = "On-device location",
+  description = "Where this model lives on disk.",
+  className,
+}: {
+  path: string;
+  title?: string;
+  description?: string;
+  className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const { copied, copy } = useCopyFeedback();
+
+  const handleCopy = async (event: MouseEvent<HTMLButtonElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
+    await copy(path);
+  };
+
+  return (
+    <>
+      <Tooltip>
+        <TooltipTrigger asChild={true}>
+          <button
+            type="button"
+            aria-label="Show on-device path"
+            onClick={(e) => {
+              e.stopPropagation();
+              setOpen(true);
+            }}
+            className={cn(
+              "inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-[8px] text-muted-foreground opacity-0 transition-[opacity,background-color,color] duration-150 hover:bg-muted hover:text-foreground focus-visible:opacity-100 group-hover/dl:opacity-100",
+              className,
+            )}
+          >
+            <HugeiconsIcon
+              icon={FolderSearchIcon}
+              strokeWidth={1.75}
+              className="size-4"
+            />
+          </button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" className="tooltip-compact">
+          Show path
+        </TooltipContent>
+      </Tooltip>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent
+          className="sm:max-w-[520px]"
+          onClick={(e) => e.stopPropagation()}
+        >
+          <DialogHeader>
+            <DialogTitle>{title}</DialogTitle>
+            <DialogDescription>{description}</DialogDescription>
+          </DialogHeader>
+          <div className="flex items-stretch gap-2">
+            <div className="flex-1 select-text rounded-[10px] border border-border bg-muted/30 px-3 py-2.5 text-[12px] leading-5 text-foreground/85 break-all">
+              {path}
+            </div>
+            <Tooltip>
+              <TooltipTrigger asChild={true}>
+                <button
+                  type="button"
+                  aria-label="Copy path"
+                  onClick={handleCopy}
+                  className="inline-flex shrink-0 cursor-pointer items-center justify-center rounded-[10px] border border-border bg-muted/30 px-3 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                >
+                  <HugeiconsIcon
+                    icon={copied ? Tick02Icon : Copy01Icon}
+                    strokeWidth={1.75}
+                    className="size-4"
+                  />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="bottom" className="tooltip-compact">
+                {copied ? "Copied" : "Copy path"}
+              </TooltipContent>
+            </Tooltip>
+          </div>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx b/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
new file mode 100644
index 0000000000..5c5d390116
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/safetensors-download-card.tsx
@@ -0,0 +1,327 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Spinner } from "@/components/ui/spinner";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useRepoDownload } from "../download-manager";
+import { deleteCachedModel } from "../inventory";
+import { cn } from "@/lib/utils";
+import {
+  Alert02Icon,
+  PencilEdit02Icon,
+  PlayIcon,
+} from "@hugeicons/core-free-icons";
+import { TrainIcon } from "../components/train-icon";
+import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useEffect, useState } from "react";
+import { useHfTokenStore } from "../stores/hf-token-store";
+import { fetchModelSize } from "../lib/dataset-size";
+import { formatBytes } from "../lib/format";
+import { fingerprintToken } from "../lib/token-fingerprint";
+import { useOnlineStatus } from "../hooks/use-online-status";
+import {
+  CardDivider,
+  CardDeleteButton,
+  DeleteConfirmDialog,
+  DownloadActionButton,
+  DownloadCard,
+} from "./download-card";
+import { DotTag } from "./dot-tag";
+import { PathInfoButton } from "./path-info-button";
+import { useCardDelete } from "./use-card-delete";
+import type { ModelInventoryFormat } from "../inventory";
+import { useDownloadCardState } from "./use-download-card-state";
+
+function formatModelLabel(modelFormat?: ModelInventoryFormat | null): string {
+  if (modelFormat === "adapter") return "Adapter";
+  if (modelFormat === "checkpoint") return "Checkpoint";
+  if (!modelFormat || modelFormat === "safetensors") return "Safetensors";
+  return "Model";
+}
+
+function formatModelTone(
+  modelFormat?: ModelInventoryFormat | null,
+): "checkpoint" | "adapter" {
+  return modelFormat === "adapter" ? "adapter" : "checkpoint";
+}
+
+export function SafetensorsDownloadCard({
+  repoId,
+  isDownloaded,
+  isPartial = false,
+  partialTransport = null,
+  modelFormat,
+  canRun = true,
+  isActive,
+  isLoadingThisModel,
+  cachePath,
+  knownBytes,
+  onLoad,
+  onUseInChat,
+  onTrain,
+  onChange,
+}: {
+  repoId: string;
+  isDownloaded: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+  modelFormat?: ModelInventoryFormat | null;
+  canRun?: boolean;
+  isActive: boolean;
+  isLoadingThisModel: boolean;
+  cachePath?: string | null;
+  knownBytes?: number | null;
+  onLoad: (opts: { ggufVariant?: string; expectedBytes?: number }) => void;
+  onUseInChat?: () => void;
+  onTrain?: () => void;
+  onChange?: () => void;
+}) {
+  const hfToken = useHfTokenStore((s) => s.token);
+  const online = useOnlineStatus();
+  const sizeKey = `${repoId}::${fingerprintToken(hfToken)}`;
+  const [modelSize, setModelSize] = useState<{
+    key: string;
+    bytes: number | null;
+  }>(() => ({ key: sizeKey, bytes: null }));
+  const modelTotalBytes =
+    knownBytes && knownBytes > 0
+      ? knownBytes
+      : modelSize.key === sizeKey
+      ? modelSize.bytes
+      : null;
+  const [deleteRepoOpen, setDeleteRepoOpen] = useState(false);
+  const { deleting, runDelete } = useCardDelete({
+    action: () => deleteCachedModel(repoId, undefined, hfToken || undefined),
+    resourceName: "model",
+    successMessage: () => `Deleted ${repoId}`,
+    onSuccess: () => {
+      setDeleteRepoOpen(false);
+      onChange?.();
+    },
+  });
+
+  const job = useRepoDownload({
+    kind: "model",
+    repoId,
+    activeVariant: null,
+    autoAdopt: true,
+  });
+
+  const progress = job.progress;
+  const cancelling = job.cancelling;
+  const repoPeerActive = job.repoPeerActive;
+  const setJobExpectedBytes = job.setExpectedBytes;
+
+  useEffect(() => {
+    if (knownBytes && knownBytes > 0) {
+      setJobExpectedBytes(knownBytes);
+      return;
+    }
+    if (!online) return;
+    if (!repoId) return;
+    const controller = new AbortController();
+    const { signal } = controller;
+    void fetchModelSize(repoId, hfToken || undefined, signal)
+      .then((info) => {
+        if (signal.aborted || !info) return;
+        const upstream = info.weightsBytes ?? info.totalBytes;
+        if (upstream && upstream > 0) {
+          setModelSize({ key: sizeKey, bytes: upstream });
+          setJobExpectedBytes(upstream);
+        }
+      })
+      .catch((err) => {
+        if (!signal.aborted && import.meta.env.DEV) {
+          console.debug("Model size lookup failed", err);
+        }
+      });
+    return () => {
+      controller.abort();
+    };
+  }, [repoId, hfToken, sizeKey, setJobExpectedBytes, knownBytes, online]);
+
+  const downloading = progress !== null && progress.variant === null;
+  const downloadAction = useDownloadCardState({
+    job,
+    variant: null,
+    expectedBytes: modelTotalBytes ?? 0,
+    downloading,
+    disabled: isLoadingThisModel || cancelling || repoPeerActive,
+    isPartial,
+    partialTransport,
+  });
+  const showActionPair = isDownloaded && !downloading && (canRun || !!onTrain);
+  const showUnavailableAction =
+    isDownloaded && !downloading && !canRun && !onTrain;
+  const canDelete =
+    (isDownloaded || isPartial) &&
+    !downloading &&
+    !repoPeerActive &&
+    !isActive &&
+    !isLoadingThisModel;
+
+  return (
+    <div className="flex w-full flex-col gap-2"><DownloadCard
+        job={job}
+        progress={downloading ? progress : null}
+        dialogs={
+          <DeleteConfirmDialog
+            open={deleteRepoOpen}
+            onOpenChange={(o) => {
+              if (!o && !deleting) setDeleteRepoOpen(false);
+            }}
+            title="Delete cached model?"
+            deleting={deleting}
+            onConfirm={() => void runDelete()}
+            description={
+              <>
+                This will remove{" "}
+                <span className="font-medium text-foreground">{repoId}</span>{" "}
+                and its downloaded files
+                {modelTotalBytes && modelTotalBytes > 0
+                  ? ` (${formatBytes(modelTotalBytes)})`
+                  : ""}{" "}
+                from disk. You can re-download it later.
+              </>
+            }
+          />
+        }
+      >
+        <div className="relative flex h-9 min-w-0 flex-1 items-center pl-3 pr-2">
+          <span className="flex items-center gap-1.5 text-[12px] text-muted-foreground">
+            {(isActive || isDownloaded) && (
+              <DotTag
+                tone="success"
+                label={isActive ? "Loaded" : "On device"}
+              />
+            )}
+            {!isDownloaded && !isActive && isPartial && !downloading && (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <span className="inline-flex">
+                    <DotTag tone="warning" label="Partial" />
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="top" sideOffset={4}>
+                  Partial download. Click to continue.
+                </TooltipContent>
+              </Tooltip>
+            )}
+            <DotTag
+              tone={formatModelTone(modelFormat)}
+              label={formatModelLabel(modelFormat)}
+            />
+            {modelTotalBytes && modelTotalBytes > 0 && (
+              <span className="tabular-nums">
+                {formatBytes(modelTotalBytes)}
+              </span>
+            )}
+          </span>
+          <div className="ml-auto flex items-center gap-0.5">
+            {canDelete && (
+              <CardDeleteButton
+                label={`Delete ${repoId}`}
+                onClick={() => setDeleteRepoOpen(true)}
+              />
+            )}
+            {isDownloaded && cachePath && (
+              <PathInfoButton
+                path={cachePath}
+                title="On-device location"
+                description={`Where ${repoId} lives on disk.`}
+              />
+            )}
+          </div>
+        </div>
+        {/* Divider sits above the Download CTA; in the action-pair state it hides with the pair. */}
+        {(!showActionPair || HUB_POST_DOWNLOAD_ACTIONS_VISIBLE) && <CardDivider />}
+        {showActionPair ? (
+          <div
+            className={cn(
+              "group/pair flex h-9 shrink-0 items-stretch gap-1.5",
+              // Run + Train pair hidden until Hub->chat/train pickers ship.
+              !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && "hidden",
+            )}
+          >
+            {onTrain && (
+              <button
+                type="button"
+                onClick={onTrain}
+                className="hub-action-btn w-24"
+              >
+                <HugeiconsIcon icon={TrainIcon} strokeWidth={1.75} />
+                Train
+              </button>
+            )}
+            <button
+              type="button"
+              disabled={isLoadingThisModel || !canRun}
+              onClick={() => {
+                if (!canRun) return;
+                if (isActive) {
+                  onUseInChat?.();
+                  return;
+                }
+                onLoad({});
+              }}
+              className={cn(
+                isLoadingThisModel || isActive || !canRun
+                  ? "hub-action-btn w-24"
+                  : "hub-run-action-btn w-24",
+                (isLoadingThisModel || !canRun) && "opacity-70",
+              )}
+            >
+              {isLoadingThisModel ? (
+                <>
+                  <Spinner />
+                  Loading…
+                </>
+              ) : isActive ? (
+                <>
+                  <HugeiconsIcon icon={PencilEdit02Icon} strokeWidth={1.75} />
+                  Chat
+                </>
+              ) : !canRun ? (
+                <>
+                  <HugeiconsIcon icon={Alert02Icon} strokeWidth={1.75} />
+                  No run
+                </>
+              ) : (
+                <>
+                  <HugeiconsIcon icon={PlayIcon} strokeWidth={1.75} />
+                  Run
+                </>
+              )}
+            </button>
+          </div>
+        ) : showUnavailableAction ? (
+          <button
+            type="button"
+            disabled
+            className="hub-action-btn w-28 opacity-70"
+          >
+            <HugeiconsIcon icon={Alert02Icon} strokeWidth={1.75} />
+            Unavailable
+          </button>
+        ) : (
+          <DownloadActionButton
+            downloading={downloadAction.downloading}
+            cancelling={downloadAction.cancelling}
+            loading={isLoadingThisModel || downloadAction.starting}
+            isPartial={downloadAction.isPartial}
+            partialTransport={downloadAction.partialTransport}
+            progressPercent={downloadAction.progressPercent}
+            disabled={downloadAction.disabled}
+            onClick={downloadAction.onClick}
+            className={repoPeerActive ? "opacity-70" : undefined}
+          />
+        )}
+      </DownloadCard>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/shared.tsx b/studio/frontend/src/features/hub/catalog/shared.tsx
new file mode 100644
index 0000000000..d8e53fdb14
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/shared.tsx
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  BrainIcon,
+  CodeIcon,
+  GlobeIcon,
+  HeadphonesIcon,
+  SparklesIcon,
+  ViewIcon,
+  Wrench01Icon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import type { Capability, CapabilityKey } from "../lib/model-capabilities";
+
+const CAPABILITY_ICON: Record<CapabilityKey, IconSvgElement> = {
+  vision: ViewIcon,
+  audio: HeadphonesIcon,
+  tools: Wrench01Icon,
+  reasoning: BrainIcon,
+  code: CodeIcon,
+  embedding: SparklesIcon,
+  multilingual: GlobeIcon,
+};
+
+const CAPABILITY_TONE: Record<CapabilityKey, string> = {
+  vision:
+    "bg-indigo-500/10 text-indigo-700 dark:bg-indigo-400/20 dark:text-indigo-300",
+  audio:
+    "bg-rose-500/10 text-rose-700 dark:bg-rose-400/20 dark:text-rose-300",
+  tools:
+    "bg-amber-500/10 text-amber-800 dark:bg-amber-400/20 dark:text-amber-300",
+  reasoning:
+    "bg-violet-500/10 text-violet-700 dark:bg-violet-400/20 dark:text-violet-300",
+  code: "bg-cyan-500/10 text-cyan-800 dark:bg-cyan-400/20 dark:text-cyan-300",
+  embedding:
+    "bg-emerald-500/10 text-emerald-700 dark:bg-emerald-400/20 dark:text-emerald-300",
+  multilingual:
+    "bg-sky-500/10 text-sky-700 dark:bg-sky-400/20 dark:text-sky-300",
+};
+
+export function CapabilityPill({ capability }: { capability: Capability }) {
+  return (
+    <span
+      className={`inline-flex h-6 items-center gap-1.5 rounded-full px-2.5 text-[11.5px] font-medium ${CAPABILITY_TONE[capability.key]}`}
+    >
+      <HugeiconsIcon
+        icon={CAPABILITY_ICON[capability.key]}
+        strokeWidth={1.75}
+        className="size-3"
+      />
+      {capability.label}
+    </span>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/transport-conflict-dialog.tsx b/studio/frontend/src/features/hub/catalog/transport-conflict-dialog.tsx
new file mode 100644
index 0000000000..7fe2126888
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/transport-conflict-dialog.tsx
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import type { TransportConflictInfo } from "@/features/hub/download-manager";
+
+export type { TransportConflictInfo } from "@/features/hub/download-manager";
+
+export function TransportConflictDialog({
+  conflict,
+  onCancel,
+  onKeepTransport,
+  onSwitchTransport,
+}: {
+  conflict: TransportConflictInfo | null;
+  onCancel: () => void;
+  // Continue on the partial download's existing transport (resumes if possible);
+  // distinct from switching transport, which always restarts from scratch.
+  onKeepTransport: () => void;
+  onSwitchTransport: () => void;
+}) {
+  const previousLabel = conflict?.previous.toUpperCase() ?? "";
+  const nextLabel = conflict?.next.toUpperCase() ?? "";
+  const description = conflict?.resumable ? (
+    <>
+      You started this download with{" "}
+      <span className="font-medium text-foreground">{previousLabel}</span>, but
+      your current setting is{" "}
+      <span className="font-medium text-foreground">{nextLabel}</span>. Resume
+      with {previousLabel} to keep the progress you already have, or restart
+      with {nextLabel} to begin from scratch.
+    </>
+  ) : (
+    <>
+      Your previous download used{" "}
+      <span className="font-medium text-foreground">{previousLabel}</span>,
+      which can't resume its partial files, so the existing partial will be
+      discarded and this download will start from the beginning either way.
+      Restart with {previousLabel} to keep it usually faster, or restart with{" "}
+      {nextLabel} so future cancels can resume.
+    </>
+  );
+  const primaryLabel = conflict?.resumable
+    ? `Resume with ${previousLabel}`
+    : `Restart with ${previousLabel}`;
+  const secondaryLabel = `Restart with ${nextLabel}`;
+  return (
+    <AlertDialog
+      open={conflict !== null}
+      onOpenChange={(o) => {
+        if (!o) onCancel();
+      }}
+    >
+      <AlertDialogContent className="sm:!max-w-[22rem]">
+        <AlertDialogHeader>
+          <AlertDialogTitle>Different transport mode</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter className="!flex !flex-col gap-2 sm:!flex-col sm:!justify-stretch">
+          <AlertDialogAction
+            className="w-full"
+            onClick={(e) => {
+              e.preventDefault();
+              onKeepTransport();
+            }}
+          >
+            {primaryLabel}
+          </AlertDialogAction>
+          <AlertDialogAction
+            variant="outline"
+            className="w-full !bg-transparent hover:!bg-transparent"
+            onClick={(e) => {
+              e.preventDefault();
+              onSwitchTransport();
+            }}
+          >
+            {secondaryLabel}
+          </AlertDialogAction>
+          <AlertDialogCancel className="w-full !bg-transparent hover:!bg-transparent">
+            Cancel
+          </AlertDialogCancel>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/transport-toggle.tsx b/studio/frontend/src/features/hub/catalog/transport-toggle.tsx
new file mode 100644
index 0000000000..d3fc68fbf3
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/transport-toggle.tsx
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import {
+  useDownloadTransportCapabilities,
+  useTransportMode,
+} from "@/features/hub/download-manager";
+import { cn } from "@/lib/utils";
+import { useEffect } from "react";
+
+const OPTIONS: { value: "http" | "xet"; label: string; hint: string }[] = [
+  {
+    value: "http",
+    label: "HTTP",
+    hint: "Resumes from where it stopped if you cancel.",
+  },
+  {
+    value: "xet",
+    label: "Xet",
+    hint: "Usually faster on a fresh download, but starts over if you cancel.",
+  },
+];
+
+export function TransportToggle() {
+  const [mode, setMode] = useTransportMode();
+  const { capabilities } = useDownloadTransportCapabilities();
+  const xetUnavailable = capabilities?.xet.available === false;
+
+  useEffect(() => {
+    if (mode === "xet" && xetUnavailable) {
+      setMode("http");
+    }
+  }, [mode, setMode, xetUnavailable]);
+
+  return (
+    <fieldset
+      aria-label="Download transport"
+      className="hub-tag-soft m-0 inline-flex h-[26px] min-w-0 items-center gap-0.5 rounded-[11px] border-0 p-0.5 text-[11px]"
+    >
+      {OPTIONS.map((opt) => {
+        const active = mode === opt.value;
+        const disabled = opt.value === "xet" && xetUnavailable;
+        const hint =
+          disabled && capabilities?.xet.reason
+            ? capabilities.xet.reason
+            : opt.hint;
+        return (
+          <Tooltip key={opt.value}>
+            <TooltipTrigger asChild={true}>
+              <button
+                type="button"
+                disabled={disabled}
+                onClick={() => setMode(opt.value)}
+                aria-pressed={active}
+                className={cn(
+                  "inline-flex h-[22px] cursor-pointer items-center justify-center rounded-[8px] px-2 font-medium tracking-tight transition-colors",
+                  active
+                    ? "hub-tab-toggle-pill text-foreground"
+                    : disabled
+                      ? "cursor-not-allowed text-muted-foreground/45"
+                      : "text-muted-foreground hover:text-foreground/80",
+                )}
+              >
+                {opt.label}
+              </button>
+            </TooltipTrigger>
+            <TooltipContent
+              side="bottom"
+              sideOffset={6}
+              className="tooltip-compact"
+            >
+              {hint}
+            </TooltipContent>
+          </Tooltip>
+        );
+      })}
+    </fieldset>
+  );
+}
diff --git a/studio/frontend/src/features/hub/catalog/use-card-delete.ts b/studio/frontend/src/features/hub/catalog/use-card-delete.ts
new file mode 100644
index 0000000000..6f853a962d
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/use-card-delete.ts
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useDeleteConfirmAction } from "./use-delete-confirm-action";
+
+type DeleteSuccessMessage = string | (() => string);
+
+export function useCardDelete({
+  action,
+  resourceName,
+  successMessage,
+  onSuccess,
+  onSettled,
+}: {
+  action: () => Promise<void>;
+  resourceName: string;
+  successMessage: DeleteSuccessMessage;
+  onSuccess?: () => void;
+  onSettled?: () => void;
+}) {
+  return useDeleteConfirmAction({
+    action,
+    successMessage,
+    errorToast: (err) => ({
+      title: `Failed to delete ${resourceName}`,
+      description: err instanceof Error ? err.message : undefined,
+    }),
+    onSuccess,
+    onSettled,
+  });
+}
diff --git a/studio/frontend/src/features/hub/catalog/use-delete-confirm-action.ts b/studio/frontend/src/features/hub/catalog/use-delete-confirm-action.ts
new file mode 100644
index 0000000000..26e1c8c21a
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/use-delete-confirm-action.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "@/lib/toast";
+
+type DeleteSuccessMessage = string | (() => string);
+type DeleteErrorToast =
+  | { title: string; description?: string }
+  | ((error: unknown) => { title: string; description?: string });
+
+function resolveSuccessMessage(message: DeleteSuccessMessage): string {
+  return typeof message === "function" ? message() : message;
+}
+
+function resolveErrorToast(
+  errorToast: DeleteErrorToast,
+  error: unknown,
+): { title: string; description?: string } {
+  return typeof errorToast === "function" ? errorToast(error) : errorToast;
+}
+
+export function useDeleteConfirmAction({
+  action,
+  successMessage,
+  errorToast,
+  onSuccess,
+  onSettled,
+}: {
+  action: () => Promise<void>;
+  successMessage: DeleteSuccessMessage;
+  errorToast: DeleteErrorToast;
+  onSuccess?: () => void;
+  onSettled?: () => void;
+}) {
+  const [deleting, setDeleting] = useState(false);
+  const inFlightRef = useRef(false);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const runDelete = useCallback(async () => {
+    if (inFlightRef.current) return;
+    inFlightRef.current = true;
+    setDeleting(true);
+    try {
+      await action();
+      toast.success(resolveSuccessMessage(successMessage));
+      onSuccess?.();
+    } catch (error) {
+      const resolved = resolveErrorToast(errorToast, error);
+      toast.error(resolved.title, { description: resolved.description });
+    } finally {
+      inFlightRef.current = false;
+      if (mountedRef.current) setDeleting(false);
+      onSettled?.();
+    }
+  }, [action, errorToast, onSettled, onSuccess, successMessage]);
+
+  return { deleting, runDelete };
+}
diff --git a/studio/frontend/src/features/hub/catalog/use-download-card-state.ts b/studio/frontend/src/features/hub/catalog/use-download-card-state.ts
new file mode 100644
index 0000000000..67613d9abe
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/use-download-card-state.ts
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { DownloadJob } from "../download-manager";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export function partialResumeLabel(transport: string | null | undefined): string {
+  if (transport === "xet") return "Redownload";
+  if (transport === "http") return "Continue";
+  return "Retry";
+}
+
+export function downloadActionAriaLabel(
+  downloading: boolean,
+  cancelling: boolean,
+): string | undefined {
+  return cancelling ? "Cancelling…" : downloading ? "Cancel download" : undefined;
+}
+
+export function downloadActionLabel(
+  isPartial: boolean,
+  partialTransport: string | null | undefined,
+): string {
+  return isPartial ? partialResumeLabel(partialTransport) : "Download";
+}
+
+export function useDownloadCardState({
+  job,
+  variant,
+  expectedBytes,
+  downloading,
+  cancelling = job.cancelling,
+  disabled,
+  isPartial = false,
+  partialTransport = null,
+}: {
+  job: DownloadJob;
+  variant: string | null;
+  expectedBytes: number;
+  downloading: boolean;
+  cancelling?: boolean;
+  disabled: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+}) {
+  const [starting, setStarting] = useState(false);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  useEffect(() => {
+    if (downloading || cancelling || disabled) {
+      setStarting(false);
+    }
+  }, [cancelling, disabled, downloading]);
+  const progressPercent =
+    job.progress != null
+      ? Math.round(Math.min(job.progress.fraction, 1) * 100)
+      : null;
+  const effectiveDisabled = disabled || starting;
+  const onClick = useCallback(() => {
+    if (disabled || cancelling || starting) return;
+    if (downloading) {
+      void job.cancelDownload(variant);
+      return;
+    }
+    setStarting(true);
+    void job.requestStartDownload(variant, expectedBytes).finally(() => {
+      if (mountedRef.current) setStarting(false);
+    });
+  }, [
+    cancelling,
+    disabled,
+    downloading,
+    expectedBytes,
+    job,
+    starting,
+    variant,
+  ]);
+  return {
+    downloading,
+    cancelling,
+    starting,
+    isPartial,
+    partialTransport,
+    progressPercent,
+    disabled: effectiveDisabled,
+    ariaLabel: downloadActionAriaLabel(downloading, cancelling),
+    downloadLabel: downloadActionLabel(isPartial, partialTransport),
+    onClick,
+  };
+}
diff --git a/studio/frontend/src/features/hub/catalog/use-gguf-variant-fetch-state.ts b/studio/frontend/src/features/hub/catalog/use-gguf-variant-fetch-state.ts
new file mode 100644
index 0000000000..aeba45383d
--- /dev/null
+++ b/studio/frontend/src/features/hub/catalog/use-gguf-variant-fetch-state.ts
@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  type GgufVariantDetail,
+  listGgufVariants,
+  useGgufVariantsCacheVersion,
+} from "../inventory";
+import { fingerprintToken } from "../lib/token-fingerprint";
+
+interface GgufVariantFetchState {
+  key: string;
+  scopeKey: string;
+  variants: GgufVariantDetail[] | null;
+  defaultVariant: string | null;
+  loading: boolean;
+  error: string | null;
+  refreshError: string | null;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+export function useGgufVariantFetchState({
+  repoId,
+  hfToken,
+  preferLocalCache = false,
+  localPath = null,
+  enabled = true,
+  errorFallback = "Failed to load variants",
+}: {
+  repoId: string;
+  hfToken?: string | null;
+  preferLocalCache?: boolean;
+  localPath?: string | null;
+  enabled?: boolean;
+  errorFallback?: string;
+}) {
+  const variantsVersion = useGgufVariantsCacheVersion(repoId);
+  const localVariantPath = localPath?.trim() || null;
+  const variantScopeKey = useMemo(
+    () =>
+      `${repoId}::${fingerprintToken(hfToken)}::${
+        preferLocalCache ? "local" : "remote"
+      }::${localVariantPath ?? ""}`,
+    [hfToken, localVariantPath, preferLocalCache, repoId],
+  );
+  const variantKey = useMemo(
+    () => `${variantScopeKey}::${variantsVersion}`,
+    [variantScopeKey, variantsVersion],
+  );
+  const [state, setState] = useState<GgufVariantFetchState>(() => ({
+    key: variantKey,
+    scopeKey: variantScopeKey,
+    variants: null,
+    defaultVariant: null,
+    loading: enabled,
+    error: null,
+    refreshError: null,
+  }));
+  const abortRef = useRef<AbortController | null>(null);
+
+  const refresh = useCallback(async (): Promise<void> => {
+    abortRef.current?.abort();
+    if (!enabled) {
+      setState({
+        key: variantKey,
+        scopeKey: variantScopeKey,
+        variants: null,
+        defaultVariant: null,
+        loading: false,
+        error: null,
+        refreshError: null,
+      });
+      return;
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setState((prev) => {
+      const sameScope = prev.scopeKey === variantScopeKey;
+      return {
+        key: variantKey,
+        scopeKey: variantScopeKey,
+        variants: sameScope ? prev.variants : null,
+        defaultVariant: sameScope ? prev.defaultVariant : null,
+        loading: true,
+        error: null,
+        refreshError: null,
+      };
+    });
+    try {
+      const response = await listGgufVariants(repoId, hfToken || undefined, {
+        preferLocalCache,
+        localPath: localVariantPath,
+        signal: controller.signal,
+      });
+      if (controller.signal.aborted) return;
+      setState({
+        key: variantKey,
+        scopeKey: variantScopeKey,
+        variants: response.variants,
+        defaultVariant: response.default_variant,
+        loading: false,
+        error: null,
+        refreshError: null,
+      });
+    } catch (error) {
+      if (controller.signal.aborted || isAbortError(error)) return;
+      setState((prev) => {
+        const sameScope = prev.scopeKey === variantScopeKey;
+        const variants = sameScope ? prev.variants : null;
+        const hasUsableVariants = !!variants && variants.length > 0;
+        const message = error instanceof Error ? error.message : errorFallback;
+        return {
+          key: variantKey,
+          scopeKey: variantScopeKey,
+          variants,
+          defaultVariant: sameScope ? prev.defaultVariant : null,
+          loading: false,
+          error: hasUsableVariants ? null : message,
+          refreshError: hasUsableVariants ? message : null,
+        };
+      });
+    } finally {
+      if (abortRef.current === controller) {
+        abortRef.current = null;
+      }
+    }
+  }, [
+    enabled,
+    errorFallback,
+    hfToken,
+    localVariantPath,
+    preferLocalCache,
+    repoId,
+    variantScopeKey,
+    variantKey,
+  ]);
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => void refresh(), 0);
+    return () => {
+      window.clearTimeout(timer);
+      abortRef.current?.abort();
+      abortRef.current = null;
+    };
+  }, [refresh]);
+
+  if (state.key === variantKey) {
+    return { ...state, refresh };
+  }
+  if (state.scopeKey === variantScopeKey) {
+    return {
+      ...state,
+      key: variantKey,
+      loading: true,
+      error: null,
+      refreshError: null,
+      refresh,
+    };
+  }
+  return {
+    key: variantKey,
+    scopeKey: variantScopeKey,
+    variants: null,
+    defaultVariant: null,
+    loading: enabled,
+    error: null,
+    refreshError: null,
+    refresh,
+  };
+}
diff --git a/studio/frontend/src/features/hub/components/hf-token-indicator.tsx b/studio/frontend/src/features/hub/components/hf-token-indicator.tsx
new file mode 100644
index 0000000000..35020de5b1
--- /dev/null
+++ b/studio/frontend/src/features/hub/components/hf-token-indicator.tsx
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useSettingsDialogStore } from "@/features/settings";
+import { cn } from "@/lib/utils";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import { AiSecurity03Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+
+interface HfTokenIndicatorProps {
+  // true: chip with label (Train wizard); false: icon-only pill (Hub header).
+  showLabel?: boolean;
+}
+
+// Compact "set / not set" indicator for the app-wide Hugging Face token; click
+// opens Settings -> General. Shared by the Hub header and Train wizard.
+export function HfTokenIndicator({ showLabel = false }: HfTokenIndicatorProps = {}) {
+  const hfToken = useHfTokenStore((s) => s.token);
+  const openDialog = useSettingsDialogStore((s) => s.openDialog);
+  const hasToken = Boolean(hfToken && hfToken.trim());
+
+  const ariaLabel = hasToken
+    ? "Hugging Face token configured"
+    : "Set Hugging Face token";
+  const tipText = hasToken
+    ? "Token set. Allows access to private and gated repos."
+    : "Set a token to access private and gated repos.";
+
+  if (showLabel) {
+    return (
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            onClick={() => openDialog("general")}
+            aria-label={ariaLabel}
+            className={cn(
+              "hub-menu-trigger field-soft inline-flex h-9 w-full items-center justify-between gap-2 rounded-[12px] py-0 pl-1.5 pr-3 text-[12.5px] font-medium text-foreground transition-colors",
+              "focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
+            )}
+          >
+            <span className="flex min-w-0 items-center gap-2">
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "inline-flex size-6 items-center justify-center rounded-full transition-colors",
+                  hasToken
+                    ? "bg-primary/15 text-primary"
+                    : "bg-foreground/[0.07] text-muted-foreground dark:bg-white/[0.07]",
+                )}
+              >
+                <HugeiconsIcon
+                  icon={AiSecurity03Icon}
+                  strokeWidth={1.75}
+                  className="size-3.5"
+                />
+              </span>
+              <span className="truncate">HF Token</span>
+            </span>
+            <span
+              className={cn(
+                "shrink-0 text-[11px] font-normal tabular-nums",
+                hasToken ? "text-primary" : "text-muted-foreground/70",
+              )}
+            >
+              {hasToken ? "Set" : "Add"}
+            </span>
+          </button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" sideOffset={6} className="tooltip-compact">
+          {tipText}
+        </TooltipContent>
+      </Tooltip>
+    );
+  }
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          onClick={() => openDialog("general")}
+          aria-label={ariaLabel}
+          className={cn(
+            "inline-flex items-center justify-center px-2.5 py-1 text-[11.5px] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            hasToken
+              ? "hub-tag-soft text-muted-foreground hover:text-foreground/80"
+              : "rounded-[11px] bg-destructive text-destructive-foreground hover:bg-destructive/90",
+          )}
+        >
+          <HugeiconsIcon
+            icon={AiSecurity03Icon}
+            strokeWidth={1.75}
+            className="size-4"
+          />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom" sideOffset={6} className="tooltip-compact">
+        {tipText}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
diff --git a/studio/frontend/src/features/hub/components/page-heading.tsx b/studio/frontend/src/features/hub/components/page-heading.tsx
new file mode 100644
index 0000000000..0b9c3d2728
--- /dev/null
+++ b/studio/frontend/src/features/hub/components/page-heading.tsx
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { ReactNode } from "react";
+
+import { cn } from "@/lib/utils";
+
+type PageHeadingProps = {
+  title: ReactNode;
+  subtitle?: ReactNode;
+  className?: string;
+};
+
+export function PageHeading({ title, subtitle, className }: PageHeadingProps) {
+  return (
+    <div className={cn("page-title-halo min-w-0", className)}>
+      <h1 className="text-[30px] font-semibold leading-[1.04] tracking-[-0.028em] text-foreground sm:text-[34px]">
+        {title}
+      </h1>
+      {subtitle ? (
+        <p className="mt-2 text-[13px] leading-[19px] text-muted-foreground">
+          {subtitle}
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/components/train-icon.ts b/studio/frontend/src/features/hub/components/train-icon.ts
new file mode 100644
index 0000000000..1b59bc4835
--- /dev/null
+++ b/studio/frontend/src/features/hub/components/train-icon.ts
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { TestTube01Icon } from "@hugeicons/core-free-icons";
+
+// Slice to the first three paths to drop TestTube01Icon's two interior bubbles,
+// keeping the outline + cap + liquid line. Shared so the Train icon stays identical app-wide.
+export const TrainIcon = TestTube01Icon.slice(0, 3) as typeof TestTube01Icon;
diff --git a/studio/frontend/src/features/hub/download-manager/api.ts b/studio/frontend/src/features/hub/download-manager/api.ts
new file mode 100644
index 0000000000..ca987f1643
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/api.ts
@@ -0,0 +1,455 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { formatFastApiDetail } from "@/lib/format-fastapi-error";
+import { hubTokenHeader } from "../lib/hub-token-header";
+import { abortError, withAbort } from "../lib/abort-signals";
+import type { TransportMode } from "./constants";
+
+function parseErrorText(status: number, body: unknown): string {
+  if (body && typeof body === "object") {
+    const detail = (body as { detail?: unknown }).detail;
+    const formatted = formatFastApiDetail(detail);
+    if (status === 405) {
+      return `${formatted || "Method Not Allowed"} - the Studio backend did not accept this API method. Restart Studio so the frontend and backend are on the same build.`;
+    }
+    if (formatted) return formatted;
+    const message = (body as { message?: unknown }).message;
+    if (typeof message === "string" && message) return message;
+  }
+  if (status === 405) {
+    return "Method Not Allowed - the Studio backend did not accept this API method. Restart Studio so the frontend and backend are on the same build.";
+  }
+  return `Request failed (${status})`;
+}
+
+async function parseJsonOrThrow<T>(response: Response): Promise<T> {
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new Error(parseErrorText(response.status, body));
+  }
+  return body as T;
+}
+
+export type DownloadJobState =
+  | "idle"
+  | "running"
+  | "complete"
+  | "error"
+  | "cancelled"
+  | "cancelling";
+
+export interface DownloadJobStatus {
+  state: DownloadJobState;
+  error?: string | null;
+  generation?: number;
+}
+
+export type DownloadStartState = DownloadJobState | "deleting";
+
+export interface DownloadStartResult {
+  state: DownloadStartState;
+  accepted: boolean;
+  generation?: number;
+}
+
+export interface ActiveModelDownload {
+  repo_id?: string;
+  variant: string | null;
+  transport?: TransportMode | null;
+  state: DownloadJobState;
+  generation?: number;
+}
+
+export interface ActiveDatasetDownload {
+  repo_id: string;
+  variant: null;
+  transport?: TransportMode | null;
+  state: DownloadJobState;
+  generation?: number;
+}
+
+type ActiveModelDownloadsOptions = {
+  fresh?: boolean;
+};
+
+const ACTIVE_MODEL_DOWNLOADS_DEDUPE_MS = 750;
+const ACTIVE_MODEL_DOWNLOADS_CACHE_MAX = 200;
+const activeModelDownloadsInFlight = new Map<
+  string,
+  Promise<readonly ActiveModelDownload[]>
+>();
+const activeModelDownloadsCache = new Map<
+  string,
+  { expiresAt: number; downloads: readonly ActiveModelDownload[] }
+>();
+
+function pruneActiveModelDownloadsCache(now = Date.now()): void {
+  for (const [key, entry] of activeModelDownloadsCache) {
+    if (entry.expiresAt <= now) activeModelDownloadsCache.delete(key);
+  }
+  while (activeModelDownloadsCache.size > ACTIVE_MODEL_DOWNLOADS_CACHE_MAX) {
+    const oldest = activeModelDownloadsCache.keys().next().value;
+    if (oldest === undefined) break;
+    activeModelDownloadsCache.delete(oldest);
+  }
+}
+
+export type TransportMarker = TransportMode | null;
+
+export interface TransportStatus {
+  has_partial: boolean;
+  last_transport: TransportMarker;
+  resumable: boolean;
+}
+
+export interface DownloadTransportCapability {
+  available: boolean | null;
+  reason: string | null;
+}
+
+export interface DownloadTransportCapabilities {
+  http: DownloadTransportCapability;
+  xet: DownloadTransportCapability;
+}
+
+export interface DownloadProgressResponse {
+  downloaded_bytes: number;
+  completed_bytes: number;
+  complete_on_disk: boolean;
+  expected_bytes: number;
+  progress: number;
+  cache_path: string | null;
+}
+
+export type DownloadProgressOptions = {
+  signal?: AbortSignal;
+  hfToken?: string | null;
+  expectedBytes?: number;
+};
+
+export type GgufDownloadProgressOptions = DownloadProgressOptions & {
+  variant: string;
+};
+
+const DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK: DownloadTransportCapabilities = {
+  http: { available: true, reason: null },
+  xet: {
+    available: null,
+    reason: "Couldn't verify Xet support with the Studio backend.",
+  },
+};
+let downloadTransportCapabilitiesCache: DownloadTransportCapabilities | null =
+  null;
+let downloadTransportCapabilitiesInFlight: Promise<DownloadTransportCapabilities> | null =
+  null;
+
+function normalizeDownloadTransportCapability(
+  value: unknown,
+  fallback: DownloadTransportCapability,
+): DownloadTransportCapability {
+  if (!value || typeof value !== "object") {
+    return fallback;
+  }
+  const candidate = value as { available?: unknown; reason?: unknown };
+  return {
+    available:
+      typeof candidate.available === "boolean"
+        ? candidate.available
+        : fallback.available,
+    reason:
+      typeof candidate.reason === "string"
+        ? candidate.reason
+        : candidate.reason === null
+          ? null
+          : fallback.reason,
+  };
+}
+
+function normalizeDownloadTransportCapabilities(
+  value: unknown,
+): DownloadTransportCapabilities {
+  if (!value || typeof value !== "object") {
+    return DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK;
+  }
+  const candidate = value as { http?: unknown; xet?: unknown };
+  return {
+    http: normalizeDownloadTransportCapability(candidate.http, {
+      available: true,
+      reason: null,
+    }),
+    xet: normalizeDownloadTransportCapability(
+      candidate.xet,
+      DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK.xet,
+    ),
+  };
+}
+
+export async function getDownloadTransportCapabilities(options: {
+  force?: boolean;
+} = {}): Promise<DownloadTransportCapabilities> {
+  if (!options.force && downloadTransportCapabilitiesCache) {
+    return downloadTransportCapabilitiesCache;
+  }
+  if (!options.force && downloadTransportCapabilitiesInFlight) {
+    return downloadTransportCapabilitiesInFlight;
+  }
+  const request = authFetch("/api/studio/download-transport-capabilities")
+    .then(parseJsonOrThrow<unknown>)
+    .then(normalizeDownloadTransportCapabilities)
+    .then((capabilities) => {
+      downloadTransportCapabilitiesCache = capabilities;
+      return capabilities;
+    })
+    .catch(() => DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK)
+    .finally(() => {
+      if (downloadTransportCapabilitiesInFlight === request) {
+        downloadTransportCapabilitiesInFlight = null;
+      }
+    });
+  downloadTransportCapabilitiesInFlight = request;
+  return request;
+}
+
+export function __resetDownloadTransportCapabilitiesForTests(): void {
+  downloadTransportCapabilitiesCache = null;
+  downloadTransportCapabilitiesInFlight = null;
+}
+
+export async function startModelDownload(payload: {
+  repo_id: string;
+  gguf_variant?: string | null;
+  hf_token?: string | null;
+  use_xet?: boolean;
+}): Promise<DownloadStartResult & { job_key: string }> {
+  const { hf_token, ...body } = payload;
+  const headers = {
+    "Content-Type": "application/json",
+    ...hubTokenHeader(hf_token),
+  };
+  const response = await authFetch("/api/hub/download", {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function cancelModelDownload(payload: {
+  repo_id: string;
+  gguf_variant?: string | null;
+  generation?: number | null;
+  signal?: AbortSignal;
+}): Promise<{ job_key: string; state: DownloadJobState }> {
+  const { signal, ...body } = payload;
+  const response = await authFetch("/api/hub/download/cancel", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function getModelDownloadStatus(
+  repoId: string,
+  ggufVariant?: string | null,
+  signal?: AbortSignal,
+): Promise<DownloadJobStatus> {
+  const params = new URLSearchParams({ repo_id: repoId });
+  if (ggufVariant) params.set("gguf_variant", ggufVariant);
+  const response = await authFetch(`/api/hub/download-status?${params}`, {
+    signal,
+  });
+  return parseJsonOrThrow<DownloadJobStatus>(response);
+}
+
+export async function getActiveModelDownloads(
+  repoId: string,
+  signal?: AbortSignal,
+  options: ActiveModelDownloadsOptions = {},
+): Promise<readonly ActiveModelDownload[]> {
+  return getActiveModelDownloadsForKey(repoId, signal, options);
+}
+
+export async function getAllActiveModelDownloads(
+  signal?: AbortSignal,
+  options: ActiveModelDownloadsOptions = {},
+): Promise<readonly ActiveModelDownload[]> {
+  return getActiveModelDownloadsForKey(null, signal, options);
+}
+
+async function getActiveModelDownloadsForKey(
+  repoId: string | null,
+  signal?: AbortSignal,
+  options: ActiveModelDownloadsOptions = {},
+): Promise<readonly ActiveModelDownload[]> {
+  const trimmedRepoId = repoId?.trim() ?? "";
+  const key = trimmedRepoId ? trimmedRepoId.toLowerCase() : "*";
+  if (signal?.aborted) return Promise.reject(abortError(signal));
+  const useCachedResult = !options.fresh;
+  const cached = useCachedResult ? activeModelDownloadsCache.get(key) : undefined;
+  const now = Date.now();
+  if (cached && cached.expiresAt > now) {
+    return withAbort(Promise.resolve(cached.downloads), signal);
+  }
+
+  let request = useCachedResult ? activeModelDownloadsInFlight.get(key) : undefined;
+  if (!request) {
+    const fetchRequest = (async () => {
+      const params = new URLSearchParams();
+      if (trimmedRepoId) params.set("repo_id", trimmedRepoId);
+      const query = params.toString();
+      const response = await authFetch(
+        `/api/hub/active-downloads${query ? `?${query}` : ""}`,
+        options.fresh && signal ? { signal } : undefined,
+      );
+      const data = await parseJsonOrThrow<{
+        downloads: ActiveModelDownload[];
+      }>(response);
+      activeModelDownloadsCache.set(key, {
+        expiresAt: Date.now() + ACTIVE_MODEL_DOWNLOADS_DEDUPE_MS,
+        downloads: data.downloads,
+      });
+      pruneActiveModelDownloadsCache();
+      return data.downloads;
+    })();
+    request = useCachedResult
+      ? fetchRequest.finally(() => {
+          activeModelDownloadsInFlight.delete(key);
+        })
+      : fetchRequest;
+    if (useCachedResult) {
+      activeModelDownloadsInFlight.set(key, request);
+    }
+  }
+  return withAbort(request, signal);
+}
+
+export async function getActiveDatasetDownloads(
+  signal?: AbortSignal,
+): Promise<ActiveDatasetDownload[]> {
+  const response = await authFetch("/api/hub/datasets/active-downloads", {
+    signal,
+  });
+  const data = await parseJsonOrThrow<{
+    downloads: ActiveDatasetDownload[];
+  }>(response);
+  return data.downloads;
+}
+
+export async function startDatasetDownload(payload: {
+  repo_id: string;
+  hf_token?: string | null;
+  use_xet?: boolean;
+}): Promise<DownloadStartResult & { repo_id: string }> {
+  const { hf_token, ...body } = payload;
+  const headers = {
+    "Content-Type": "application/json",
+    ...hubTokenHeader(hf_token),
+  };
+  const response = await authFetch("/api/hub/datasets/download", {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function cancelDatasetDownload(payload: {
+  repo_id: string;
+  generation?: number | null;
+  signal?: AbortSignal;
+}): Promise<{ repo_id: string; state: DownloadJobState }> {
+  const { signal, ...body } = payload;
+  const response = await authFetch("/api/hub/datasets/download/cancel", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function getDatasetDownloadStatus(
+  repoId: string,
+  signal?: AbortSignal,
+): Promise<DownloadJobStatus> {
+  const params = new URLSearchParams({ repo_id: repoId });
+  const response = await authFetch(`/api/hub/datasets/download-status?${params}`, {
+    signal,
+  });
+  return parseJsonOrThrow<DownloadJobStatus>(response);
+}
+
+export async function getModelTransportStatus(
+  repoId: string,
+  ggufVariant?: string | null,
+  hfToken?: string | null,
+  signal?: AbortSignal,
+): Promise<TransportStatus> {
+  const params = new URLSearchParams({ repo_id: repoId });
+  if (ggufVariant) params.set("gguf_variant", ggufVariant);
+  const response = await authFetch(`/api/hub/transport-status?${params}`, {
+    headers: hubTokenHeader(hfToken),
+    signal,
+  });
+  return parseJsonOrThrow<TransportStatus>(response);
+}
+
+export async function getDatasetTransportStatus(
+  repoId: string,
+  signal?: AbortSignal,
+): Promise<TransportStatus> {
+  const params = new URLSearchParams({ repo_id: repoId });
+  const response = await authFetch(`/api/hub/datasets/transport-status?${params}`, {
+    signal,
+  });
+  return parseJsonOrThrow<TransportStatus>(response);
+}
+
+export async function getGgufDownloadProgress(
+  repoId: string,
+  options: GgufDownloadProgressOptions,
+): Promise<DownloadProgressResponse> {
+  const { expectedBytes = 0, hfToken, signal, variant } = options;
+  const params = new URLSearchParams({
+    repo_id: repoId,
+    variant,
+    expected_bytes: String(expectedBytes),
+  });
+  const response = await authFetch(`/api/hub/gguf-download-progress?${params}`, {
+    headers: hubTokenHeader(hfToken),
+    signal,
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function getDownloadProgress(
+  repoId: string,
+  options: DownloadProgressOptions,
+): Promise<DownloadProgressResponse> {
+  const { expectedBytes = 0, hfToken, signal } = options;
+  const params = new URLSearchParams({ repo_id: repoId });
+  if (expectedBytes > 0) params.set("expected_bytes", String(expectedBytes));
+  const response = await authFetch(`/api/hub/download-progress?${params}`, {
+    headers: hubTokenHeader(hfToken),
+    signal,
+  });
+  return parseJsonOrThrow(response);
+}
+
+export async function getDatasetDownloadProgress(
+  repoId: string,
+  options: DownloadProgressOptions,
+): Promise<DownloadProgressResponse> {
+  const { expectedBytes = 0, hfToken, signal } = options;
+  const params = new URLSearchParams({ repo_id: repoId });
+  if (expectedBytes > 0) params.set("expected_bytes", String(expectedBytes));
+  const response = await authFetch(`/api/hub/datasets/download-progress?${params}`, {
+    headers: hubTokenHeader(hfToken),
+    signal,
+  });
+  return parseJsonOrThrow(response);
+}
diff --git a/studio/frontend/src/features/hub/download-manager/constants.ts b/studio/frontend/src/features/hub/download-manager/constants.ts
new file mode 100644
index 0000000000..3f772cb196
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/constants.ts
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export const TRANSPORT = {
+  HTTP: "http",
+  XET: "xet",
+} as const;
+
+export const TRANSPORT_MODES = [TRANSPORT.HTTP, TRANSPORT.XET] as const;
+export type TransportMode = (typeof TRANSPORT_MODES)[number];
+export const DEFAULT_TRANSPORT_MODE: TransportMode = TRANSPORT.HTTP;
+
+export function isTransportMode(value: unknown): value is TransportMode {
+  return (
+    typeof value === "string" &&
+    (TRANSPORT_MODES as readonly string[]).includes(value)
+  );
+}
+
+export const DOWNLOAD_KIND = {
+  MODEL: "model",
+  DATASET: "dataset",
+} as const;
+
+export const DOWNLOAD_KINDS = [
+  DOWNLOAD_KIND.MODEL,
+  DOWNLOAD_KIND.DATASET,
+] as const;
+export type DownloadKind = (typeof DOWNLOAD_KINDS)[number];
+
+export function isDownloadKind(value: unknown): value is DownloadKind {
+  return (
+    typeof value === "string" &&
+    (DOWNLOAD_KINDS as readonly string[]).includes(value)
+  );
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts b/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
new file mode 100644
index 0000000000..6942dfbbb9
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { getHfToken } from "../stores/hf-token-store";
+import { toast } from "@/lib/toast";
+import {
+  type DownloadStartResult,
+  type DownloadStartState,
+  cancelDatasetDownload,
+  cancelModelDownload,
+  getDatasetDownloadProgress,
+  getDatasetDownloadStatus,
+  getDatasetTransportStatus,
+  getDownloadProgress,
+  getDownloadTransportCapabilities,
+  getGgufDownloadProgress,
+  getModelDownloadStatus,
+  getModelTransportStatus,
+  startDatasetDownload,
+  startModelDownload,
+} from "./api";
+import {
+  POLL_REQUEST_TIMEOUT_MS,
+  TRANSPORT_STATUS_RETRY_DELAY_MS,
+  TRANSPORT_STATUS_TIMEOUT_MS,
+} from "./download-manager-config";
+import { DOWNLOAD_KIND, TRANSPORT, type TransportMode } from "./constants";
+import type {
+  DownloadRequest,
+  ManagedDownload,
+  ProgressLike,
+} from "./download-manager-types";
+import {
+  type PollSignal,
+  disposableTimeoutSignal,
+  pollSignal,
+} from "../lib/abort-signals";
+
+let lastXetUnavailableWarningReason: string | null = null;
+
+export async function withPollRequestTimeout<T>(
+  parent: AbortController | null,
+  request: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const poll: PollSignal = parent
+    ? pollSignal(parent.signal, POLL_REQUEST_TIMEOUT_MS)
+    : disposableTimeoutSignal(POLL_REQUEST_TIMEOUT_MS);
+  try {
+    return await request(poll.signal);
+  } finally {
+    poll.dispose();
+  }
+}
+
+export function apiGetStatus(job: ManagedDownload, signal: AbortSignal) {
+  return job.kind === DOWNLOAD_KIND.DATASET
+    ? getDatasetDownloadStatus(job.repoId, signal)
+    : getModelDownloadStatus(job.repoId, job.variant, signal);
+}
+
+export function apiGetProgress(
+  job: ManagedDownload,
+  signal: AbortSignal,
+): Promise<ProgressLike> {
+  const token = getHfToken() || null;
+  if (job.kind === DOWNLOAD_KIND.DATASET) {
+    return getDatasetDownloadProgress(job.repoId, {
+      signal,
+      hfToken: token,
+      expectedBytes: job.expectedBytes,
+    });
+  }
+  if (job.variant) {
+    return getGgufDownloadProgress(job.repoId, {
+      variant: job.variant,
+      expectedBytes: job.expectedBytes,
+      hfToken: token,
+      signal,
+    });
+  }
+  return getDownloadProgress(job.repoId, {
+    signal,
+    hfToken: token,
+    expectedBytes: job.expectedBytes,
+  });
+}
+
+export function apiStart(
+  req: DownloadRequest,
+  useXet: boolean,
+  hfToken: string | null,
+): Promise<DownloadStartResult> {
+  return req.kind === DOWNLOAD_KIND.DATASET
+    ? startDatasetDownload({
+        repo_id: req.repoId,
+        hf_token: hfToken,
+        use_xet: useXet,
+      })
+    : startModelDownload({
+        repo_id: req.repoId,
+        gguf_variant: req.variant,
+        hf_token: hfToken,
+        use_xet: useXet,
+      });
+}
+
+export function apiCancel(job: ManagedDownload, signal?: AbortSignal) {
+  const generation = Number.isSafeInteger(job.serverGeneration)
+    ? job.serverGeneration
+    : undefined;
+  return job.kind === DOWNLOAD_KIND.DATASET
+    ? cancelDatasetDownload({ repo_id: job.repoId, generation, signal })
+    : cancelModelDownload({
+        repo_id: job.repoId,
+        gguf_variant: job.variant,
+        generation,
+        signal,
+      });
+}
+
+export function apiCancelRequest(
+  req: DownloadRequest,
+  generation: number | undefined,
+  signal?: AbortSignal,
+) {
+  if (!Number.isSafeInteger(generation)) return Promise.resolve();
+  return req.kind === DOWNLOAD_KIND.DATASET
+    ? cancelDatasetDownload({ repo_id: req.repoId, generation, signal })
+    : cancelModelDownload({
+        repo_id: req.repoId,
+        gguf_variant: req.variant,
+        generation,
+        signal,
+      });
+}
+
+function apiTransportStatus(
+  req: DownloadRequest,
+  signal?: AbortSignal,
+) {
+  const token = getHfToken() || null;
+  return req.kind === DOWNLOAD_KIND.DATASET
+    ? getDatasetTransportStatus(req.repoId, signal)
+    : getModelTransportStatus(req.repoId, req.variant, token, signal);
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    globalThis.setTimeout(resolve, ms);
+  });
+}
+
+export async function apiTransportStatusWithRetry(
+  req: DownloadRequest,
+): Promise<Awaited<ReturnType<typeof apiTransportStatus>>> {
+  const request = async () => {
+    const timeout = disposableTimeoutSignal(TRANSPORT_STATUS_TIMEOUT_MS);
+    try {
+      return await apiTransportStatus(req, timeout.signal);
+    } finally {
+      timeout.dispose();
+    }
+  };
+  try {
+    return await request();
+  } catch {
+    await wait(TRANSPORT_STATUS_RETRY_DELAY_MS);
+    return request();
+  }
+}
+
+export async function effectiveTransportMode(
+  preferred: TransportMode,
+): Promise<TransportMode> {
+  if (preferred !== TRANSPORT.XET) {
+    return preferred;
+  }
+  const capabilities = await getDownloadTransportCapabilities();
+  if (capabilities.xet.available === true) {
+    lastXetUnavailableWarningReason = null;
+    return preferred;
+  }
+  if (capabilities.xet.available === null) {
+    return preferred;
+  }
+  const reason =
+    capabilities.xet.reason ?? "Studio will use HTTP downloads instead.";
+  if (lastXetUnavailableWarningReason !== reason) {
+    lastXetUnavailableWarningReason = reason;
+    toast.warning("Xet download transport unavailable", {
+      description: reason,
+    });
+  }
+  return TRANSPORT.HTTP;
+}
+
+export function describeUnacceptedStart(state: DownloadStartState): string {
+  switch (state) {
+    case "deleting":
+      return "This repository is being removed. Try again once it finishes.";
+    case "running":
+    case "cancelling":
+      return "Another download for this repository is already in progress. Wait for it to finish or cancel it first.";
+    default:
+      return "The download could not be started. Try again in a moment.";
+  }
+}
+
+export function accessErrorMessage(raw: string): string | null {
+  const lower = raw.toLowerCase();
+  const hasAccessSignal =
+    lower.includes("unauthorized") ||
+    lower.includes("forbidden") ||
+    lower.includes("gated") ||
+    lower.includes("repository not found");
+  if (!hasAccessSignal) return null;
+  return "Couldn't access this Hugging Face repo with the token used for this download. Update the HF token and restart the download, or delete the partial download if you no longer need it.";
+}
+
+export const pollAccessErrorMessage = accessErrorMessage;
+
+export function normalizeDownloadError(
+  error: unknown,
+  fallback = "Failed to start download",
+): string {
+  const raw =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : fallback;
+  return accessErrorMessage(raw) ?? raw;
+}
+
+export function isRequestTimeout(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.name === "AbortError" || error.name === "TimeoutError")
+  );
+}
+
+export function resetDownloadApiAdapterState(): void {
+  lastXetUnavailableWarningReason = null;
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-config.ts b/studio/frontend/src/features/hub/download-manager/download-manager-config.ts
new file mode 100644
index 0000000000..dce0c6cf30
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-config.ts
@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { DownloadJobState } from "./api";
+
+export const POLL_INTERVAL_MS = 500;
+export const POLL_BACKOFF_AFTER_MS = 60_000;
+export const POLL_BACKOFF_INTERVAL_MS = 1_500;
+export const HIDDEN_POLL_INTERVAL_MS = 10_000;
+export const POLL_JITTER_MS = 50;
+export const PROGRESS_POLL_INTERVAL_MS = 1_000;
+export const PROGRESS_POLL_BACKOFF_INTERVAL_MS = 2_000;
+export const POLL_REQUEST_TIMEOUT_MS = 15_000;
+export const POLL_DEGRADED_AFTER_MS = 30_000;
+export const POLL_DEGRADED_MESSAGE =
+  "Couldn't update download status. The download may still be running.";
+export const TRANSPORT_STATUS_TIMEOUT_MS = 3_000;
+export const SPEED_EMA_WEIGHT = 0.7;
+export const MAX_PROGRESS_FRACTION = 0.99;
+export const CANCEL_WATCHDOG_MS = 20_000;
+export const IDLE_EVICT_GRACE_MS = 60_000;
+export const COMPLETE_LINGER_MS = 6_000;
+export const CANCELLED_LINGER_MS = 6_000;
+export const ERROR_LINGER_MS = 12_000;
+export const INVENTORY_BUMP_DEBOUNCE_MS = 250;
+export const TRANSPORT_STATUS_RETRY_DELAY_MS = 300;
+
+export const ACTIVE_STATES: ReadonlySet<DownloadJobState> = new Set([
+  "running",
+  "cancelling",
+]);
+
+export const TERMINAL_DISPLAY_STATES: ReadonlySet<DownloadJobState> = new Set([
+  "complete",
+  "error",
+  "cancelled",
+]);
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts b/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
new file mode 100644
index 0000000000..abfeaf3c0d
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  createDownloadManagerInitialState,
+  removeJob,
+  setState,
+} from "./download-manager-state";
+import { resetDownloadApiAdapterState } from "./download-api-adapter";
+import {
+  hydrateDownloadManager,
+  resetHydrationState,
+} from "./hydration";
+import { cancelJob, probeAndAdopt, setExpected } from "./poll-loop";
+import { runtimeRegistry } from "./runtime-registry";
+import {
+  cancelConflict,
+  requestStart,
+  restartConflict,
+  resumeConflict,
+} from "./transport-conflict";
+
+export type { DownloadKind } from "./constants";
+export {
+  clearCompletedInventoryHint,
+  jobKeyOf,
+  repoKeyOf,
+  selectActiveJob,
+  subscribeJobListeners,
+  useDownloadManagerStore,
+} from "./download-manager-state";
+export type {
+  DownloadRequest,
+  JobListeners,
+  ManagedDownload,
+} from "./download-manager-types";
+export { hydrateDownloadManager };
+
+export function __resetDownloadManagerForTests(): void {
+  runtimeRegistry.reset();
+  resetDownloadApiAdapterState();
+  resetHydrationState();
+  setState(createDownloadManagerInitialState());
+}
+
+export interface DownloadManagerController {
+  requestStart: typeof requestStart;
+  cancel: typeof cancelJob;
+  probeAndAdopt: typeof probeAndAdopt;
+  setExpected: typeof setExpected;
+  resumeConflict: typeof resumeConflict;
+  restartConflict: typeof restartConflict;
+  cancelConflict: typeof cancelConflict;
+  dismiss: typeof removeJob;
+}
+
+export const downloadManager: DownloadManagerController = {
+  requestStart,
+  cancel: cancelJob,
+  probeAndAdopt,
+  setExpected,
+  resumeConflict,
+  restartConflict,
+  cancelConflict,
+  dismiss: removeJob,
+};
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    __resetDownloadManagerForTests();
+  });
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
new file mode 100644
index 0000000000..e01cd6b5cc
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { hasAuthToken, mustChangePassword } from "@/features/auth/session";
+import { isTauri } from "@/lib/api-base";
+import { cn } from "@/lib/utils";
+import {
+  Alert02Icon,
+  ArrowDown01Icon,
+  Cancel01Icon,
+  CheckmarkCircle02Icon,
+  Download01Icon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useRouterState } from "@tanstack/react-router";
+import { useEffect, useMemo, useState } from "react";
+import { DownloadProgressBar } from "./download-progress-bar";
+import {
+  type ManagedDownload,
+  downloadManager,
+  hydrateDownloadManager,
+  useDownloadManagerStore,
+} from "./download-manager-controller";
+
+function createOrderedJobKeysSelector(): (state: {
+  jobs: Record<string, ManagedDownload>;
+}) => string[] {
+  let cache: { signature: string; keys: string[] } = {
+    signature: "",
+    keys: [],
+  };
+  return (state) => {
+    const ordered = Object.values(state.jobs)
+      .map((job) => ({ key: job.key, startedAt: job.startedAt }))
+      .sort((a, b) => a.startedAt - b.startedAt);
+    const signature = ordered
+      .map((job) => `${job.key}\u0001${job.startedAt}`)
+      .join("\u0002");
+    if (signature === cache.signature) {
+      return cache.keys;
+    }
+    const keys = ordered.map((job) => job.key);
+    cache = { signature, keys };
+    return keys;
+  };
+}
+
+function selectActiveJobCount(state: {
+  jobs: Record<string, ManagedDownload>;
+}): number {
+  let count = 0;
+  for (const job of Object.values(state.jobs)) {
+    if (job.state === "running" || job.state === "cancelling") count += 1;
+  }
+  return count;
+}
+
+function canUseDownloadManager(pathname: string): boolean {
+  if (isTauri) return true;
+  if (
+    pathname === "/login" ||
+    pathname === "/change-password" ||
+    pathname === "/signup"
+  ) {
+    return false;
+  }
+  return hasAuthToken() && !mustChangePassword();
+}
+
+function variantSuffix(job: ManagedDownload): string {
+  return job.variant ? ` · ${job.variant}` : "";
+}
+
+function StatusLine({ job }: { job: ManagedDownload }) {
+  if (job.state === "complete") {
+    return <span className="text-status-success">Downloaded</span>;
+  }
+  if (job.state === "cancelled") {
+    return <span>Cancelled. Partial files kept.</span>;
+  }
+  if (job.state === "error") {
+    return (
+      <span className="text-destructive">{job.error ?? "Download failed"}</span>
+    );
+  }
+  if (job.state === "cancelling") {
+    return <span>Cancelling…</span>;
+  }
+  if (job.error) {
+    return <span className="text-status-warning">{job.error}</span>;
+  }
+  return null;
+}
+
+function DownloadRow({ jobKey }: { jobKey: string }) {
+  const job = useDownloadManagerStore((state) => state.jobs[jobKey]);
+  if (!job) return null;
+  const active = job.state === "running" || job.state === "cancelling";
+  const terminal =
+    job.state === "complete" ||
+    job.state === "cancelled" ||
+    job.state === "error";
+  return (
+    <li className="flex flex-col gap-1.5 px-3 py-2.5">
+      <div className="flex items-center gap-2">
+        <span className="min-w-0 flex-1 truncate text-[12.5px] font-medium text-foreground">
+          {job.repoId}
+          <span className="text-muted-foreground">{variantSuffix(job)}</span>
+        </span>
+        {job.state === "complete" && (
+          <HugeiconsIcon
+            icon={CheckmarkCircle02Icon}
+            strokeWidth={2}
+            className="size-4 shrink-0 text-status-success"
+          />
+        )}
+        {job.state === "error" && (
+          <HugeiconsIcon
+            icon={Alert02Icon}
+            strokeWidth={2}
+            className="size-4 shrink-0 text-destructive"
+          />
+        )}
+        <Tooltip>
+          <TooltipTrigger asChild={true}>
+            <button
+              type="button"
+              aria-label={active ? "Cancel download" : "Dismiss"}
+              disabled={job.state === "cancelling"}
+              onClick={() =>
+                active
+                  ? void downloadManager.cancel(job.key)
+                  : downloadManager.dismiss(job.key)
+              }
+              className={cn(
+                "inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-[7px] text-muted-foreground transition-colors",
+                "hover:bg-foreground/[0.06] hover:text-foreground disabled:cursor-default disabled:opacity-50 dark:hover:bg-white/[0.06]",
+              )}
+            >
+              <HugeiconsIcon
+                icon={Cancel01Icon}
+                strokeWidth={1.75}
+                className="size-3.5"
+              />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="top" sideOffset={4}>
+            {active ? "Cancel download" : "Dismiss"}
+          </TooltipContent>
+        </Tooltip>
+      </div>
+      {active ? (
+        <DownloadProgressBar
+          progress={{
+            expectedBytes: job.expectedBytes,
+            downloadedBytes: job.downloadedBytes,
+            fraction: job.fraction,
+          }}
+          bytesPerSec={job.bytesPerSec}
+        />
+      ) : null}
+      {terminal || job.state === "cancelling" || job.error ? (
+        <div className="px-0 text-[11px] text-muted-foreground tabular-nums">
+          <StatusLine job={job} />
+        </div>
+      ) : null}
+    </li>
+  );
+}
+
+export function DownloadManagerPanel() {
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+  const enabled = canUseDownloadManager(pathname);
+  const [collapsed, setCollapsed] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) return;
+    hydrateDownloadManager();
+  }, [enabled]);
+
+  const selectOrderedJobKeys = useMemo(createOrderedJobKeysSelector, []);
+  const jobKeys = useDownloadManagerStore(selectOrderedJobKeys);
+  const activeCount = useDownloadManagerStore(selectActiveJobCount);
+
+  if (!enabled || jobKeys.length === 0) return null;
+
+  const headerLabel =
+    activeCount > 0
+      ? `Downloading ${activeCount} ${activeCount === 1 ? "item" : "items"}`
+      : "Downloads";
+
+  return (
+    <div className="pointer-events-none fixed bottom-4 right-4 z-50">
+      {collapsed ? (
+        <Tooltip>
+          <TooltipTrigger asChild={true}>
+            <button
+              type="button"
+              aria-label={headerLabel}
+              onClick={() => setCollapsed(false)}
+              className="hub-download-fab pointer-events-auto"
+            >
+              <HugeiconsIcon
+                icon={Download01Icon}
+                strokeWidth={1.75}
+                className="size-[18px]"
+              />
+              {activeCount > 0 && (
+                <span className="hub-download-fab-badge">{activeCount}</span>
+              )}
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left" sideOffset={6}>
+            {headerLabel}
+          </TooltipContent>
+        </Tooltip>
+      ) : (
+        <div className="hub-download-panel pointer-events-auto w-[min(360px,calc(100vw-2rem))] overflow-hidden">
+          <div className="flex items-center gap-2 border-b border-foreground/[0.07] px-3 py-2">
+            <HugeiconsIcon
+              icon={Download01Icon}
+              strokeWidth={1.75}
+              className="size-4 shrink-0 text-muted-foreground"
+            />
+            <span className="min-w-0 flex-1 truncate text-[12.5px] font-semibold text-foreground">
+              {headerLabel}
+            </span>
+            <button
+              type="button"
+              aria-label="Collapse downloads"
+              onClick={() => setCollapsed(true)}
+              className="inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-[7px] text-muted-foreground transition-colors hover:bg-foreground/[0.06] hover:text-foreground dark:hover:bg-white/[0.06]"
+            >
+              <HugeiconsIcon
+                icon={ArrowDown01Icon}
+                strokeWidth={1.75}
+                className="size-3.5"
+              />
+            </button>
+          </div>
+          <ul className="max-h-[60vh] divide-y divide-foreground/[0.06] overflow-y-auto [scrollbar-width:thin]">
+            {jobKeys.map((jobKey) => (
+              <DownloadRow key={jobKey} jobKey={jobKey} />
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-state.ts b/studio/frontend/src/features/hub/download-manager/download-manager-state.ts
new file mode 100644
index 0000000000..5699fd62fb
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-state.ts
@@ -0,0 +1,526 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { INVENTORY_HINT_KIND } from "../inventory/constants";
+import { inventoryHintKey } from "../inventory/inventory-hints";
+import type { InventoryHint } from "../inventory/types";
+import { create } from "zustand";
+import {
+  type StateStorage,
+  createJSONStorage,
+  persist,
+} from "zustand/middleware";
+import type { DownloadJobState } from "./api";
+import {
+  ACTIVE_STATES,
+  MAX_PROGRESS_FRACTION,
+} from "./download-manager-config";
+import {
+  DOWNLOAD_KIND,
+  type DownloadKind,
+  isDownloadKind,
+} from "./constants";
+import {
+  type DownloadManagerState,
+  type JobListeners,
+  type ManagedDownload,
+} from "./download-manager-types";
+import {
+  clearRuntimeTimer,
+  pruneSuppressedCompletedInventoryHints as pruneRuntimeSuppressedHints,
+  runtimeRegistry,
+  teardownRuntime,
+} from "./runtime-registry";
+
+const PERSIST_KEY = "unsloth.studio.downloads";
+const PERSIST_VERSION = 1;
+const PERSIST_THROTTLE_MS = 1_000;
+
+const noopStorage: StateStorage = {
+  getItem: () => null,
+  setItem: () => undefined,
+  removeItem: () => undefined,
+};
+
+function createThrottledStorage(
+  base: StateStorage,
+  delayMs: number,
+): StateStorage {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pending: { name: string; value: string } | null = null;
+  const flush = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (pending) {
+      base.setItem(pending.name, pending.value);
+      pending = null;
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("pagehide", flush);
+  }
+  return {
+    getItem: (name) => base.getItem(name),
+    setItem: (name, value) => {
+      pending = { name, value };
+      if (timer === null) timer = setTimeout(flush, delayMs);
+    },
+    removeItem: (name) => {
+      pending = null;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      base.removeItem(name);
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function nonNegativeNumber(value: unknown, fallback = 0): number {
+  return Math.max(0, finiteNumber(value, fallback));
+}
+
+function sanitizePersistedJob(value: unknown): ManagedDownload | null {
+  if (!isRecord(value)) return null;
+  const kind = isDownloadKind(value.kind) ? value.kind : null;
+  const repoId = typeof value.repoId === "string" ? value.repoId : null;
+  const state = value.state as DownloadJobState;
+  if (!kind || !repoId || !ACTIVE_STATES.has(state)) return null;
+
+  const variant = typeof value.variant === "string" ? value.variant : null;
+  const key = jobKeyOf(kind, repoId, variant);
+  return {
+    key,
+    kind,
+    repoId,
+    variant,
+    state,
+    downloadedBytes: nonNegativeNumber(value.downloadedBytes),
+    completedBytes: nonNegativeNumber(value.completedBytes),
+    completeOnDisk: false,
+    expectedBytes: nonNegativeNumber(value.expectedBytes),
+    fraction: Math.min(Math.max(finiteNumber(value.fraction, 0), 0), 1),
+    bytesPerSec: 0,
+    error: typeof value.error === "string" ? value.error : null,
+    startedAt: nonNegativeNumber(value.startedAt, Date.now()),
+    ...(Number.isSafeInteger(value.serverGeneration)
+      ? { serverGeneration: Number(value.serverGeneration) }
+      : {}),
+  };
+}
+
+function sanitizePersistedState(
+  persisted: unknown,
+): Partial<DownloadManagerState> {
+  if (!isRecord(persisted) || !isRecord(persisted.jobs)) {
+    return { jobs: {}, conflicts: {} };
+  }
+  const jobs: Record<string, ManagedDownload> = {};
+  for (const value of Object.values(persisted.jobs)) {
+    const job = sanitizePersistedJob(value);
+    if (job) jobs[job.key] = job;
+  }
+  return {
+    jobs,
+    conflicts: {},
+  };
+}
+
+function toPersistedJob(
+  job: ManagedDownload,
+): Omit<ManagedDownload, "bytesPerSec" | "completeOnDisk"> {
+  return {
+    key: job.key,
+    kind: job.kind,
+    repoId: job.repoId,
+    variant: job.variant,
+    state: job.state,
+    downloadedBytes: job.downloadedBytes,
+    completedBytes: job.completedBytes,
+    expectedBytes: job.expectedBytes,
+    fraction: job.fraction,
+    error: job.error,
+    startedAt: job.startedAt,
+    ...(job.serverGeneration !== undefined
+      ? { serverGeneration: job.serverGeneration }
+      : {}),
+  };
+}
+
+// Mirrors the backend's normalize_repo_key (strip().lower()) so two casings of
+// one repo share a key (else duplicate jobs / mismatched listeners). Keys only —
+// `repoId` keeps original casing for display and API calls.
+function normalizeRepoIdentity(repoId: string): string {
+  return repoId.trim().toLowerCase();
+}
+
+function normalizeVariantIdentity(variant: string | null | undefined): string {
+  return variant?.trim().toLowerCase() ?? "";
+}
+
+export function repoKeyOf(kind: DownloadKind, repoId: string): string {
+  return `${kind}:${normalizeRepoIdentity(repoId)}`;
+}
+
+export function jobKeyOf(
+  kind: DownloadKind,
+  repoId: string,
+  variant: string | null,
+): string {
+  const base = repoKeyOf(kind, repoId);
+  const variantKey = normalizeVariantIdentity(variant);
+  return variantKey ? `${base}#${variantKey}` : base;
+}
+
+function completedInventoryHintKind(
+  kind: DownloadKind,
+  variant: string | null,
+): InventoryHint["kind"] {
+  return kind === DOWNLOAD_KIND.DATASET
+    ? INVENTORY_HINT_KIND.DATASET
+    : variant
+      ? INVENTORY_HINT_KIND.GGUF
+      : INVENTORY_HINT_KIND.MODEL;
+}
+
+function liveCompletedInventoryHintKeys(): Set<string> {
+  const keys = new Set<string>();
+  for (const job of Object.values(getState().jobs)) {
+    if (job.state !== "complete") continue;
+    keys.add(
+      inventoryHintKey(
+        completedInventoryHintKind(job.kind, job.variant),
+        job.repoId,
+      ),
+    );
+  }
+  return keys;
+}
+
+function collectCompletedInventoryHints(
+  jobs: Record<string, ManagedDownload>,
+): InventoryHint[] {
+  return Object.values(jobs).flatMap((job) => {
+    if (job.state !== "complete") return [];
+    const kind = completedInventoryHintKind(job.kind, job.variant);
+    if (
+      runtimeRegistry.suppressedCompletedInventoryHints.has(
+        inventoryHintKey(kind, job.repoId),
+      )
+    ) {
+      return [];
+    }
+    const bytes = Math.max(job.downloadedBytes, job.expectedBytes, 0);
+    return [
+      {
+        kind,
+        repoId: job.repoId,
+        ...(bytes > 0 ? { bytes } : {}),
+      },
+    ];
+  });
+}
+
+function buildCompletedHintSignature(hints: readonly InventoryHint[]): string {
+  return hints
+    .map((hint) => `${hint.kind}:${hint.repoId}:${hint.bytes ?? ""}`)
+    .sort()
+    .join("|");
+}
+
+export function createDownloadManagerInitialState(): DownloadManagerState {
+  return {
+    jobs: {},
+    conflicts: {},
+    completedHintSignature: "",
+    completedInventoryHints: [],
+  };
+}
+
+export const useDownloadManagerStore = create<DownloadManagerState>()(
+  persist(createDownloadManagerInitialState, {
+    name: PERSIST_KEY,
+    version: PERSIST_VERSION,
+    storage: createJSONStorage(() =>
+      typeof window === "undefined"
+        ? noopStorage
+        : createThrottledStorage(window.localStorage, PERSIST_THROTTLE_MS),
+    ),
+    migrate: (persisted) => sanitizePersistedState(persisted),
+    merge: (persisted, current) => ({
+      ...current,
+      ...sanitizePersistedState(persisted),
+    }),
+    partialize: (state) => ({
+      jobs: Object.fromEntries(
+        Object.entries(state.jobs)
+          .filter(([, job]) => ACTIVE_STATES.has(job.state))
+          .map(([key, job]) => [key, toPersistedJob(job)] as const),
+      ),
+      conflicts: {},
+    }),
+  }),
+);
+
+export const setState = useDownloadManagerStore.setState;
+export const getState = useDownloadManagerStore.getState;
+
+function withCompletedHintSignature(
+  state: DownloadManagerState,
+): DownloadManagerState {
+  const completedInventoryHints = collectCompletedInventoryHints(state.jobs);
+  const completedHintSignature = buildCompletedHintSignature(
+    completedInventoryHints,
+  );
+  if (state.completedHintSignature === completedHintSignature) return state;
+  return { ...state, completedHintSignature, completedInventoryHints };
+}
+
+function isPreferredRepoActiveJob(
+  candidate: ManagedDownload,
+  current: ManagedDownload | null | undefined,
+): boolean {
+  if (!current || !ACTIVE_STATES.has(current.state)) return true;
+  if (candidate.startedAt !== current.startedAt) {
+    return candidate.startedAt > current.startedAt;
+  }
+  return candidate.key < current.key;
+}
+
+export function findActiveJobForRepo(
+  jobs: Record<string, ManagedDownload>,
+  kind: DownloadKind,
+  repoId: string,
+): ManagedDownload | null {
+  let selected: ManagedDownload | null = null;
+  const repoIdentity = normalizeRepoIdentity(repoId);
+  for (const job of Object.values(jobs)) {
+    if (job.kind !== kind || normalizeRepoIdentity(job.repoId) !== repoIdentity)
+      continue;
+    if (!ACTIVE_STATES.has(job.state)) continue;
+    if (isPreferredRepoActiveJob(job, selected)) {
+      selected = job;
+    }
+  }
+  return selected;
+}
+
+function hasRuntimePeerForRepo(
+  kind: DownloadKind,
+  repoId: string,
+  key: string,
+): boolean {
+  const repoIdentity = normalizeRepoIdentity(repoId);
+  for (const [runtimeKey, runtime] of runtimeRegistry.runtimes) {
+    if (runtimeKey === key) continue;
+    if (runtime.kind === kind && normalizeRepoIdentity(runtime.repoId) === repoIdentity)
+      return true;
+  }
+  return false;
+}
+
+// Shared rule for what blocks a fresh GGUF variant start. Peer guard passes
+// includeOwnRuntime:false (runs after this start made its own runtime); requestStart
+// passes both true (runs before any runtime or job exists).
+export function hasVariantRepoActivity(
+  kind: DownloadKind,
+  repoId: string,
+  key: string,
+  opts: { includeOwnRuntime: boolean; includePending: boolean },
+): boolean {
+  const state = getState();
+  const own = state.jobs[key];
+  if (own && ACTIVE_STATES.has(own.state)) return true;
+  if (selectActiveJob(state, kind, repoId, null)) return true;
+  const snapshotKey = jobKeyOf(kind, repoId, null);
+  if (runtimeRegistry.runtimes.has(snapshotKey)) return true;
+  if (opts.includeOwnRuntime && runtimeRegistry.runtimes.has(key)) return true;
+  if (opts.includePending) {
+    if (runtimeRegistry.pendingStartRepoKeys.has(key)) return true;
+    if (runtimeRegistry.pendingStartRepoKeys.has(snapshotKey)) return true;
+  }
+  return false;
+}
+
+export function hasActiveRepoPeer(
+  kind: DownloadKind,
+  repoId: string,
+  key: string,
+  variant?: string | null,
+): boolean {
+  if (kind === DOWNLOAD_KIND.MODEL && variant) {
+    return hasVariantRepoActivity(kind, repoId, key, {
+      includeOwnRuntime: false,
+      includePending: false,
+    });
+  }
+  const active = findActiveJobForRepo(getState().jobs, kind, repoId);
+  if (active && active.key !== key) return true;
+  return hasRuntimePeerForRepo(kind, repoId, key);
+}
+
+function refreshCompletedHintSignature(): void {
+  setState((state) => withCompletedHintSignature(state));
+}
+
+export function patchJob(key: string, patch: Partial<ManagedDownload>): void {
+  setState((state) => {
+    const job = state.jobs[key];
+    if (!job) return state;
+    const nextJob = { ...job, ...patch };
+    const nextState = {
+      ...state,
+      jobs: { ...state.jobs, [key]: nextJob },
+    };
+    if (job.state !== "complete" && nextJob.state !== "complete") {
+      return nextState;
+    }
+    return withCompletedHintSignature(nextState);
+  });
+}
+
+export function putJob(job: ManagedDownload): void {
+  runtimeRegistry.clearRemovalTimer(job.key);
+  const suppressionChanged =
+    runtimeRegistry.suppressedCompletedInventoryHints.delete(
+      inventoryHintKey(
+        completedInventoryHintKind(job.kind, job.variant),
+        job.repoId,
+      ),
+    );
+  setState((state) => {
+    const existing = state.jobs[job.key];
+    const nextState = {
+      ...state,
+      jobs: { ...state.jobs, [job.key]: job },
+    };
+    if (
+      !suppressionChanged &&
+      existing?.state !== "complete" &&
+      job.state !== "complete"
+    ) {
+      return nextState;
+    }
+    return withCompletedHintSignature(nextState);
+  });
+}
+
+export function removeJob(key: string): void {
+  const job = getState().jobs[key];
+  teardownRuntime(key);
+  let suppressionChanged = false;
+  if (job) {
+    suppressionChanged =
+      runtimeRegistry.suppressedCompletedInventoryHints.delete(
+        inventoryHintKey(
+          completedInventoryHintKind(job.kind, job.variant),
+          job.repoId,
+        ),
+      );
+  }
+  runtimeRegistry.clearRemovalTimer(key);
+  setState((state) => {
+    if (!(key in state.jobs)) return state;
+    const next = { ...state.jobs };
+    delete next[key];
+    const nextState = { ...state, jobs: next };
+    if (!suppressionChanged && job?.state !== "complete") return nextState;
+    return withCompletedHintSignature(nextState);
+  });
+}
+
+export function setConflict(
+  key: string,
+  entry: DownloadManagerState["conflicts"][string] | null,
+): void {
+  setState((state) => {
+    const next = { ...state.conflicts };
+    if (entry) next[key] = entry;
+    else delete next[key];
+    return { ...state, conflicts: next };
+  });
+}
+
+export function isCurrent(key: string, epoch: number): boolean {
+  const rt = runtimeRegistry.runtimes.get(key);
+  return rt != null && rt.epoch === epoch && key in getState().jobs;
+}
+
+export function scheduleRemoval(key: string, delayMs: number): void {
+  const existing = runtimeRegistry.removalTimers.get(key);
+  if (existing != null) clearRuntimeTimer(existing);
+  const startedAt = getState().jobs[key]?.startedAt;
+  const timer = window.setTimeout(() => {
+    runtimeRegistry.removalTimers.delete(key);
+    if (getState().jobs[key]?.startedAt === startedAt) removeJob(key);
+  }, delayMs);
+  runtimeRegistry.removalTimers.set(key, timer);
+}
+
+export function selectActiveJob(
+  state: DownloadManagerState,
+  kind: DownloadKind,
+  repoId: string,
+  variant?: string | null,
+): ManagedDownload | null {
+  if (variant !== undefined) {
+    const job = state.jobs[jobKeyOf(kind, repoId, variant)];
+    return job && ACTIVE_STATES.has(job.state) ? job : null;
+  }
+  return findActiveJobForRepo(state.jobs, kind, repoId);
+}
+
+export function clearCompletedInventoryHint(hint: InventoryHint): void {
+  const key = inventoryHintKey(hint.kind, hint.repoId);
+  runtimeRegistry.suppressedCompletedInventoryHints.delete(key);
+  runtimeRegistry.suppressedCompletedInventoryHints.add(key);
+  pruneRuntimeSuppressedHints(liveCompletedInventoryHintKeys());
+  refreshCompletedHintSignature();
+}
+
+export function subscribeJobListeners(
+  kind: DownloadKind,
+  repoId: string,
+  handlers: JobListeners,
+): () => void {
+  const key = repoKeyOf(kind, repoId);
+  let set = runtimeRegistry.listeners.get(key);
+  if (!set) {
+    set = new Set();
+    runtimeRegistry.listeners.set(key, set);
+  }
+  set.add(handlers);
+  return () => {
+    const current = runtimeRegistry.listeners.get(key);
+    if (!current) return;
+    current.delete(handlers);
+    if (current.size === 0) runtimeRegistry.listeners.delete(key);
+  };
+}
+
+export function setExpectedBytesForJob(
+  kind: DownloadKind,
+  repoId: string,
+  variant: string | null,
+  bytes: number,
+): void {
+  const job = selectActiveJob(getState(), kind, repoId, variant);
+  if (!job || job.state !== "running" || bytes <= job.expectedBytes) return;
+  patchJob(job.key, {
+    expectedBytes: bytes,
+    fraction:
+      job.fraction > 0
+        ? job.fraction
+        : Math.min(job.downloadedBytes / bytes, MAX_PROGRESS_FRACTION),
+  });
+}
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-types.ts b/studio/frontend/src/features/hub/download-manager/download-manager-types.ts
new file mode 100644
index 0000000000..27b8161eab
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-types.ts
@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { InventoryHint } from "../inventory/types";
+import type { DownloadJobState } from "./api";
+import type { DownloadKind } from "./constants";
+import type { TransportConflictInfo } from "./types";
+
+export interface ManagedDownload {
+  key: string;
+  kind: DownloadKind;
+  repoId: string;
+  variant: string | null;
+  state: DownloadJobState;
+  downloadedBytes: number;
+  // Finalized bytes on disk (excludes the in-progress `.incomplete` portion in
+  // `downloadedBytes`). The idle/registry-loss completion fallback keys off this
+  // so a partial can't be marked complete.
+  completedBytes: number;
+  // Server-verified completion; not trusted across reloads (hydration re-probes).
+  completeOnDisk: boolean;
+  expectedBytes: number;
+  fraction: number;
+  bytesPerSec: number;
+  error: string | null;
+  startedAt: number;
+  serverGeneration?: number;
+}
+
+export interface DownloadRequest {
+  kind: DownloadKind;
+  repoId: string;
+  variant: string | null;
+  expectedBytes: number;
+}
+
+export interface JobListeners {
+  onComplete?: (variant: string | null, bytes: number) => unknown;
+  onCancelled?: (variant: string | null) => unknown;
+  onError?: (variant: string | null) => unknown;
+}
+
+export interface ConflictEntry {
+  info: TransportConflictInfo;
+  pending: DownloadRequest;
+}
+
+export interface DownloadManagerState {
+  jobs: Record<string, ManagedDownload>;
+  conflicts: Record<string, ConflictEntry>;
+  completedHintSignature: string;
+  completedInventoryHints: InventoryHint[];
+}
+
+export interface JobRuntime {
+  kind: DownloadKind;
+  repoId: string;
+  epoch: number;
+  pollTimer: number | null;
+  pollStartedAt: number;
+  pollingStarted: boolean;
+  abort: AbortController | null;
+  inFlight: boolean;
+  cancelRequested: boolean;
+  watchdog: number | null;
+  speedSample: { bytes: number; tMs: number } | null;
+  idleSinceMs: number | null;
+  lastProgressPollAt: number | null;
+  pollFailureStartedAt: number | null;
+  visibilityListener: (() => void) | null;
+}
+
+export interface ProgressLike {
+  downloaded_bytes: number;
+  completed_bytes?: number;
+  complete_on_disk?: boolean;
+  expected_bytes: number;
+  progress: number;
+}
+
+export type Terminal = "complete" | "cancelled" | "error" | "gone";
diff --git a/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx b/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
new file mode 100644
index 0000000000..6629305609
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/download-progress-bar.tsx
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { formatBytes, formatEta, formatRate } from "@/features/hub/lib/format";
+
+export interface DownloadProgress {
+  expectedBytes: number;
+  downloadedBytes: number;
+  fraction: number;
+}
+
+export function DownloadProgressBar({
+  progress,
+  bytesPerSec,
+}: {
+  progress: DownloadProgress;
+  bytesPerSec: number;
+}) {
+  const exactPercent = Math.min(Math.max(progress.fraction, 0), 1) * 100;
+  const totalLabel =
+    progress.expectedBytes > 0 ? formatBytes(progress.expectedBytes) : null;
+  const rateLabel = formatRate(bytesPerSec);
+  const remainingBytes = Math.max(
+    progress.expectedBytes - progress.downloadedBytes,
+    0,
+  );
+  const etaLabel =
+    bytesPerSec > 0 && remainingBytes > 0
+      ? formatEta(remainingBytes / bytesPerSec)
+      : "";
+  return (
+    <div className="flex flex-col gap-1.5 px-3 pb-1">
+      <div className="relative h-[3px] overflow-hidden rounded-full bg-foreground/[0.06] dark:bg-white/[0.06]">
+        <div
+          className="h-full rounded-full bg-status-warning/80 transition-[width] duration-500 ease-linear"
+          style={{ width: `${exactPercent}%` }}
+        />
+        <span
+          aria-hidden="true"
+          className="pointer-events-none absolute top-1/2 size-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-status-warning ring-2 ring-status-warning/30 transition-[left] duration-500 ease-linear"
+          style={{ left: `${exactPercent}%` }}
+        />
+      </div>
+      <div className="flex items-center justify-between gap-2 text-[10.5px] text-muted-foreground tabular-nums">
+        <span>
+          {formatBytes(progress.downloadedBytes)}
+          {totalLabel && ` / ${totalLabel}`}
+        </span>
+        <span className="flex items-center gap-2">
+          {rateLabel && <span>{rateLabel}</span>}
+          {etaLabel && <span>{etaLabel}</span>}
+        </span>
+      </div>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/download-manager/hydration.ts b/studio/frontend/src/features/hub/download-manager/hydration.ts
new file mode 100644
index 0000000000..a222fc4574
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/hydration.ts
@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { disposableTimeoutSignal } from "../lib/abort-signals";
+import {
+  getActiveDatasetDownloads,
+  getAllActiveModelDownloads,
+  type DownloadJobState,
+} from "./api";
+import { DOWNLOAD_KIND } from "./constants";
+import { ACTIVE_STATES, POLL_REQUEST_TIMEOUT_MS } from "./download-manager-config";
+import {
+  apiGetProgress,
+  apiGetStatus,
+  isRequestTimeout,
+} from "./download-api-adapter";
+import type {
+  DownloadRequest,
+  ManagedDownload,
+} from "./download-manager-types";
+import {
+  getState,
+  jobKeyOf,
+  removeJob,
+  repoKeyOf,
+} from "./download-manager-state";
+import {
+  adoptJob,
+  applyProgressUpdate,
+  finalize,
+  hasObservedExpectedBytes,
+} from "./poll-loop";
+import { runtimeRegistry } from "./runtime-registry";
+
+const HYDRATE_STATUS_TIMEOUT_RETRIES = 4;
+const HYDRATE_STATUS_RETRY_MS = 2_500;
+const HYDRATE_ADOPTION_RETRY_MS = 2_500;
+const HYDRATE_ADOPTION_MAX_RETRIES = 12;
+
+let hydrated = false;
+
+type HydratedIdleProbeResult = "active" | "gone" | "settled";
+
+function safeGeneration(value: number | undefined): number | undefined {
+  return Number.isSafeInteger(value) ? value : undefined;
+}
+
+async function withHydrationTimeout<T>(
+  request: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const timeout = disposableTimeoutSignal(POLL_REQUEST_TIMEOUT_MS);
+  try {
+    return await request(timeout.signal);
+  } finally {
+    timeout.dispose();
+  }
+}
+
+function removeLocalActivePeers(
+  kind: DownloadRequest["kind"],
+  repoId: string,
+  variant: string | null,
+): void {
+  const activeRepoKey = repoKeyOf(kind, repoId);
+  const activeJobKey = jobKeyOf(kind, repoId, variant);
+  const snapshotJobKey = jobKeyOf(kind, repoId, null);
+  for (const job of Object.values(getState().jobs)) {
+    if (!ACTIVE_STATES.has(job.state)) continue;
+    if (repoKeyOf(job.kind, job.repoId) !== activeRepoKey) continue;
+    if (variant !== null && kind === DOWNLOAD_KIND.MODEL) {
+      if (job.key === activeJobKey) continue;
+      if (job.key === snapshotJobKey) removeJob(job.key);
+      continue;
+    }
+    if (job.key !== activeJobKey) removeJob(job.key);
+  }
+}
+
+async function adoptActiveModelDownloads(): Promise<void> {
+  const downloads = await withHydrationTimeout((signal) =>
+    getAllActiveModelDownloads(signal),
+  );
+  for (const download of downloads) {
+    const repoId = download.repo_id?.trim();
+    if (!repoId || !ACTIVE_STATES.has(download.state)) continue;
+    removeLocalActivePeers(
+      DOWNLOAD_KIND.MODEL,
+      repoId,
+      download.variant ?? null,
+    );
+    adoptJob(
+      {
+        kind: DOWNLOAD_KIND.MODEL,
+        repoId,
+        variant: download.variant ?? null,
+        expectedBytes: 0,
+      },
+      safeGeneration(download.generation),
+      download.state,
+    );
+  }
+}
+
+async function adoptActiveDatasetDownloads(): Promise<void> {
+  const downloads = await withHydrationTimeout((signal) =>
+    getActiveDatasetDownloads(signal),
+  );
+  for (const download of downloads) {
+    const repoId = download.repo_id?.trim();
+    if (!repoId || !ACTIVE_STATES.has(download.state)) continue;
+    removeLocalActivePeers(DOWNLOAD_KIND.DATASET, repoId, null);
+    adoptJob(
+      {
+        kind: DOWNLOAD_KIND.DATASET,
+        repoId,
+        variant: null,
+        expectedBytes: 0,
+      },
+      safeGeneration(download.generation),
+      download.state,
+    );
+  }
+}
+
+type BackendAdoptionSide = "model" | "dataset";
+
+const BACKEND_ADOPTERS: Record<BackendAdoptionSide, () => Promise<void>> = {
+  model: adoptActiveModelDownloads,
+  dataset: adoptActiveDatasetDownloads,
+};
+
+// Adopt backend-running downloads this client doesn't know about. Retry only the
+// failed side(s) so transient backend readiness settles without duplicating jobs.
+async function hydrateBackendActiveDownloads(
+  attempt = 0,
+  sides: readonly BackendAdoptionSide[] = ["model", "dataset"],
+): Promise<void> {
+  const results = await Promise.allSettled(
+    sides.map((side) => BACKEND_ADOPTERS[side]()),
+  );
+  const pending = sides.filter(
+    (_, index) => results[index].status === "rejected",
+  );
+  if (pending.length === 0 || attempt >= HYDRATE_ADOPTION_MAX_RETRIES) return;
+  scheduleBackendAdoptionRetry(attempt + 1, pending);
+}
+
+function scheduleBackendAdoptionRetry(
+  attempt: number,
+  sides: readonly BackendAdoptionSide[],
+): void {
+  const timer = window.setTimeout(() => {
+    runtimeRegistry.hydrationRetryTimers.delete(timer);
+    void hydrateBackendActiveDownloads(attempt, sides);
+  }, HYDRATE_ADOPTION_RETRY_MS);
+  runtimeRegistry.hydrationRetryTimers.add(timer);
+}
+
+async function probeHydratedIdleProgress(
+  key: string,
+  job: ManagedDownload,
+): Promise<HydratedIdleProbeResult> {
+  try {
+    const progressResp = await withHydrationTimeout((signal) =>
+      apiGetProgress(job, signal),
+    );
+    const current = getState().jobs[key];
+    if (!current || !ACTIVE_STATES.has(current.state)) return "settled";
+    const { downloadedBytes } = applyProgressUpdate(key, current, progressResp);
+    const updated = getState().jobs[key];
+    if (!updated || !ACTIVE_STATES.has(updated.state)) return "settled";
+    if (hasObservedExpectedBytes(updated)) {
+      finalize(key, "complete", { bytes: updated.downloadedBytes });
+      return "settled";
+    }
+    return downloadedBytes > 0 ? "active" : "gone";
+  } catch {
+    return "active";
+  }
+}
+
+async function settleHydratedJob(
+  key: string,
+  req: DownloadRequest,
+  status: {
+    state: DownloadJobState;
+    error?: string | null;
+    generation?: number;
+  },
+): Promise<void> {
+  if (status.state === "running" || status.state === "cancelling") {
+    adoptJob(req, safeGeneration(status.generation), status.state);
+  } else if (status.state === "complete") {
+    finalize(key, "complete");
+  } else if (status.state === "cancelled") {
+    finalize(key, "cancelled");
+  } else if (status.state === "error") {
+    finalize(key, "error", { error: status.error ?? null });
+  } else {
+    const job = getState().jobs[key];
+    if (job && hasObservedExpectedBytes(job)) {
+      finalize(key, "complete", { bytes: job.downloadedBytes });
+    } else if (job?.state === "running" || job?.state === "cancelling") {
+      const probeResult = await probeHydratedIdleProgress(key, job);
+      if (probeResult === "settled") return;
+      if (probeResult === "active" && job.state === "running") {
+        adoptJob(req);
+        return;
+      }
+      const latest = getState().jobs[key];
+      if (latest && hasObservedExpectedBytes(latest)) {
+        finalize(key, "complete", { bytes: latest.downloadedBytes });
+      } else {
+        finalize(key, job.state === "cancelling" ? "cancelled" : "gone");
+      }
+    } else {
+      finalize(key, "gone");
+    }
+  }
+}
+
+function scheduleHydrationProbeRetry(
+  key: string,
+  req: DownloadRequest,
+  attempt: number,
+): void {
+  const timer = window.setTimeout(() => {
+    runtimeRegistry.hydrationRetryTimers.delete(timer);
+    const job = getState().jobs[key];
+    if (!job || !ACTIVE_STATES.has(job.state)) return;
+    void probeHydratedJob(key, req, attempt);
+  }, HYDRATE_STATUS_RETRY_MS);
+  runtimeRegistry.hydrationRetryTimers.add(timer);
+}
+
+async function probeHydratedJob(
+  key: string,
+  req: DownloadRequest,
+  attempt: number,
+): Promise<void> {
+  const job = getState().jobs[key];
+  if (!job || !ACTIVE_STATES.has(job.state)) return;
+  try {
+    const status = await withHydrationTimeout((signal) =>
+      apiGetStatus(job, signal),
+    );
+    const current = getState().jobs[key];
+    if (!current || !ACTIVE_STATES.has(current.state)) return;
+    await settleHydratedJob(key, req, status);
+  } catch (error) {
+    if (isRequestTimeout(error) && attempt < HYDRATE_STATUS_TIMEOUT_RETRIES) {
+      scheduleHydrationProbeRetry(key, req, attempt + 1);
+      return;
+    }
+    adoptJob(req);
+  }
+}
+
+export function hydrateDownloadManager(): void {
+  if (hydrated) return;
+  hydrated = true;
+  void hydrateBackendActiveDownloads();
+  const jobs = Object.values(getState().jobs);
+  for (const job of jobs) {
+    if (!ACTIVE_STATES.has(job.state)) {
+      removeJob(job.key);
+      continue;
+    }
+    const req: DownloadRequest = {
+      kind: job.kind,
+      repoId: job.repoId,
+      variant: job.variant,
+      expectedBytes: job.expectedBytes,
+    };
+    void probeHydratedJob(job.key, req, 0);
+  }
+}
+
+export function resetHydrationState(): void {
+  hydrated = false;
+}
diff --git a/studio/frontend/src/features/hub/download-manager/index.ts b/studio/frontend/src/features/hub/download-manager/index.ts
new file mode 100644
index 0000000000..60ef3851f8
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/index.ts
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export * from "./api";
+export { DownloadManagerPanel } from "./download-manager-panel";
+export {
+  DownloadProgressBar,
+  type DownloadProgress,
+} from "./download-progress-bar";
+export {
+  DEFAULT_TRANSPORT_MODE,
+  DOWNLOAD_KIND,
+  DOWNLOAD_KINDS,
+  TRANSPORT,
+  TRANSPORT_MODES,
+  isDownloadKind,
+  isTransportMode,
+  type DownloadKind,
+  type TransportMode,
+} from "./constants";
+export {
+  __resetDownloadManagerForTests,
+  clearCompletedInventoryHint,
+  downloadManager,
+  hydrateDownloadManager,
+  jobKeyOf,
+  repoKeyOf,
+  selectActiveJob,
+  subscribeJobListeners,
+  useDownloadManagerStore,
+  type DownloadManagerController,
+  type DownloadRequest,
+  type JobListeners,
+  type ManagedDownload,
+} from "./download-manager-controller";
+export {
+  useRepoDownload,
+  type DownloadJob,
+  type DownloadJobProgress,
+  type RepoDownloadConfig,
+} from "./use-repo-download";
+export {
+  getTransportMode,
+  useDownloadTransportCapabilities,
+  useTransportMode,
+} from "./transport-preference";
+export type { TransportConflictInfo } from "./types";
diff --git a/studio/frontend/src/features/hub/download-manager/poll-loop.ts b/studio/frontend/src/features/hub/download-manager/poll-loop.ts
new file mode 100644
index 0000000000..95df4afd31
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/poll-loop.ts
@@ -0,0 +1,955 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { invalidateGgufVariantsCache } from "../inventory/api";
+import { getHfToken } from "../stores/hf-token-store";
+import { bumpInventoryVersion } from "../stores/inventory-events";
+import { toast } from "@/lib/toast";
+import {
+  getActiveModelDownloads,
+  getDatasetDownloadStatus,
+  type ActiveModelDownload,
+  type DownloadJobState,
+} from "./api";
+import {
+  CANCELLED_LINGER_MS,
+  CANCEL_WATCHDOG_MS,
+  COMPLETE_LINGER_MS,
+  ERROR_LINGER_MS,
+  HIDDEN_POLL_INTERVAL_MS,
+  IDLE_EVICT_GRACE_MS,
+  INVENTORY_BUMP_DEBOUNCE_MS,
+  MAX_PROGRESS_FRACTION,
+  POLL_BACKOFF_AFTER_MS,
+  POLL_BACKOFF_INTERVAL_MS,
+  POLL_DEGRADED_AFTER_MS,
+  POLL_DEGRADED_MESSAGE,
+  POLL_INTERVAL_MS,
+  POLL_JITTER_MS,
+  PROGRESS_POLL_BACKOFF_INTERVAL_MS,
+  PROGRESS_POLL_INTERVAL_MS,
+  SPEED_EMA_WEIGHT,
+  ACTIVE_STATES,
+  TERMINAL_DISPLAY_STATES,
+} from "./download-manager-config";
+import {
+  DOWNLOAD_KIND,
+  TRANSPORT,
+  type DownloadKind,
+  type TransportMode,
+} from "./constants";
+import {
+  apiCancel,
+  apiCancelRequest,
+  apiGetProgress,
+  apiGetStatus,
+  apiStart,
+  describeUnacceptedStart,
+  effectiveTransportMode,
+  normalizeDownloadError,
+  pollAccessErrorMessage,
+  withPollRequestTimeout,
+} from "./download-api-adapter";
+import type {
+  DownloadRequest,
+  JobListeners,
+  JobRuntime,
+  ManagedDownload,
+  ProgressLike,
+  Terminal,
+} from "./download-manager-types";
+import {
+  getState,
+  hasActiveRepoPeer,
+  isCurrent,
+  jobKeyOf,
+  patchJob,
+  putJob,
+  removeJob,
+  repoKeyOf,
+  scheduleRemoval,
+  setExpectedBytesForJob,
+} from "./download-manager-state";
+import {
+  clearWatchdog,
+  runtimeRegistry,
+  teardownRuntime,
+} from "./runtime-registry";
+import { getTransportMode } from "./transport-preference";
+
+function notify(
+  job: ManagedDownload,
+  event: keyof JobListeners,
+  bytes: number,
+): void {
+  const set = runtimeRegistry.listeners.get(repoKeyOf(job.kind, job.repoId));
+  if (!set) return;
+  for (const handlers of [...set]) {
+    try {
+      if (event === "onComplete")
+        void handlers.onComplete?.(job.variant, bytes);
+      else if (event === "onCancelled")
+        void handlers.onCancelled?.(job.variant);
+      else void handlers.onError?.(job.variant);
+    } catch (error) {
+      console.warn("Download job listener failed", {
+        kind: job.kind,
+        repoId: job.repoId,
+        variant: job.variant,
+        event,
+        error,
+      });
+    }
+  }
+}
+
+function scheduleInventoryBump(): void {
+  if (typeof window === "undefined") {
+    bumpInventoryVersion();
+    return;
+  }
+  if (runtimeRegistry.inventoryBumpTimer !== null) {
+    window.clearTimeout(runtimeRegistry.inventoryBumpTimer);
+  }
+  runtimeRegistry.inventoryBumpTimer = window.setTimeout(() => {
+    runtimeRegistry.inventoryBumpTimer = null;
+    bumpInventoryVersion();
+  }, INVENTORY_BUMP_DEBOUNCE_MS);
+}
+
+function withDownloadTimeout<T>(
+  request: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  return withPollRequestTimeout(null, request);
+}
+
+export function hasObservedExpectedBytes(job: ManagedDownload): boolean {
+  // Finalized bytes only: a partial whose `.incomplete` blob merely reached the
+  // expected size must not count as finished; the backend must also verify it on disk.
+  return (
+    job.expectedBytes > 0 &&
+    job.completedBytes >= job.expectedBytes &&
+    job.completeOnDisk
+  );
+}
+
+export function resolveProgressUpdate(
+  job: ManagedDownload,
+  progressResp: ProgressLike,
+  opts: { resetMonotonic?: boolean } = {},
+): {
+  expected: number;
+  downloadedBytes: number;
+  completedBytes: number;
+  completeOnDisk: boolean;
+  fraction: number;
+  madeProgress: boolean;
+} {
+  const reported = progressResp.expected_bytes;
+  const isGgufVariantJob =
+    job.kind === DOWNLOAD_KIND.MODEL && job.variant !== null;
+  const backendOwnsGgufProgress = isGgufVariantJob && reported > 0;
+  // GGUF totals are backend-owned (non-monotonic). Snapshots keep the displayed
+  // total monotonic to absorb jitter, but a fresh attempt (generation changed:
+  // XET redownload, restart, re-adoption) drops the stale high-water mark.
+  const trustBackend = backendOwnsGgufProgress || opts.resetMonotonic === true;
+  const expected = trustBackend
+    ? reported > 0
+      ? reported
+      : job.expectedBytes
+    : Math.max(reported > 0 ? reported : job.expectedBytes, job.expectedBytes);
+  const previousDownloadedBytes = job.downloadedBytes;
+  const downloadedBytes = trustBackend
+    ? Math.max(0, progressResp.downloaded_bytes)
+    : Math.max(previousDownloadedBytes, progressResp.downloaded_bytes);
+  const completedBytes = trustBackend
+    ? Math.max(0, progressResp.completed_bytes ?? 0)
+    : Math.max(job.completedBytes, progressResp.completed_bytes ?? 0);
+  const completeOnDisk = progressResp.complete_on_disk === true;
+  const madeProgress =
+    opts.resetMonotonic === true ||
+    downloadedBytes > previousDownloadedBytes ||
+    expected !== job.expectedBytes;
+  const rawFraction =
+    progressResp.progress > 0
+      ? progressResp.progress
+      : expected > 0
+        ? downloadedBytes / expected
+        : 0;
+  const cappedFraction = Math.min(rawFraction, MAX_PROGRESS_FRACTION);
+  // Keep the GGUF variant bar monotonic: its backend progress is recomputed from
+  // the shared per-repo blobs/ dir each poll, so a sibling quant or generation
+  // bump can make one reading dip. A fresh download resets via startJob's seed.
+  const fraction = isGgufVariantJob
+    ? Math.max(cappedFraction, job.fraction)
+    : cappedFraction;
+  return {
+    expected,
+    downloadedBytes,
+    completedBytes,
+    completeOnDisk,
+    fraction,
+    madeProgress,
+  };
+}
+
+export function applyProgressUpdate(
+  key: string,
+  job: ManagedDownload,
+  progressResp: ProgressLike,
+): ReturnType<typeof resolveProgressUpdate> {
+  const resolved = resolveProgressUpdate(job, progressResp);
+  patchJob(key, {
+    expectedBytes: resolved.expected,
+    downloadedBytes: resolved.downloadedBytes,
+    completedBytes: resolved.completedBytes,
+    completeOnDisk: resolved.completeOnDisk,
+    fraction: resolved.fraction,
+  });
+  return resolved;
+}
+
+function progressPollDelayMs(rt: JobRuntime): number {
+  return Date.now() - rt.pollStartedAt >= POLL_BACKOFF_AFTER_MS
+    ? PROGRESS_POLL_BACKOFF_INTERVAL_MS
+    : PROGRESS_POLL_INTERVAL_MS;
+}
+
+function shouldPollProgress(rt: JobRuntime, force: boolean): boolean {
+  if (force || rt.lastProgressPollAt === null) {
+    return true;
+  }
+  return Date.now() - rt.lastProgressPollAt >= progressPollDelayMs(rt);
+}
+
+function markPollSuccess(key: string, rt: JobRuntime): void {
+  rt.pollFailureStartedAt = null;
+  const job = getState().jobs[key];
+  if (job?.error === POLL_DEGRADED_MESSAGE && ACTIVE_STATES.has(job.state)) {
+    patchJob(key, { error: null });
+  }
+}
+
+function markPollFailure(key: string, rt: JobRuntime): void {
+  const now = Date.now();
+  rt.pollFailureStartedAt ??= now;
+  if (now - rt.pollFailureStartedAt < POLL_DEGRADED_AFTER_MS) return;
+  rt.speedSample = null;
+  patchJob(key, {
+    error: POLL_DEGRADED_MESSAGE,
+    bytesPerSec: 0,
+  });
+}
+
+export function finalize(
+  key: string,
+  outcome: Terminal,
+  opts: { bytes?: number; error?: string | null } = {},
+): void {
+  const job = getState().jobs[key];
+  teardownRuntime(key);
+  if (!job) return;
+  if (TERMINAL_DISPLAY_STATES.has(job.state)) return;
+  if (job.kind === DOWNLOAD_KIND.MODEL) {
+    invalidateGgufVariantsCache(job.repoId);
+  }
+  if (outcome === "gone") {
+    notify(job, "onCancelled", 0);
+    removeJob(key);
+  } else if (outcome === "complete") {
+    // Reconcile to the largest known figure so a terminal status arriving before
+    // the final progress poll doesn't leave a stale sub-total: downloaded ==
+    // completed >= expected, fraction 1, and report that figure to listeners.
+    const bytes = Math.max(
+      opts.bytes ?? 0,
+      job.downloadedBytes,
+      job.completedBytes,
+      job.expectedBytes,
+    );
+    patchJob(key, {
+      state: "complete",
+      fraction: 1,
+      downloadedBytes: bytes,
+      completedBytes: bytes,
+      completeOnDisk: true,
+      bytesPerSec: 0,
+      error: null,
+    });
+    notify(job, "onComplete", bytes);
+    scheduleRemoval(key, COMPLETE_LINGER_MS);
+  } else if (outcome === "cancelled") {
+    patchJob(key, { state: "cancelled", bytesPerSec: 0, error: null });
+    notify(job, "onCancelled", 0);
+    scheduleRemoval(key, CANCELLED_LINGER_MS);
+  } else {
+    const rawError =
+      typeof opts.error === "string" && opts.error
+        ? opts.error
+        : "Download failed";
+    patchJob(key, {
+      state: "error",
+      error:
+        opts.error === null ? null : (pollAccessErrorMessage(rawError) ?? rawError),
+      bytesPerSec: 0,
+    });
+    notify(job, "onError", 0);
+    scheduleRemoval(key, ERROR_LINGER_MS);
+  }
+  scheduleInventoryBump();
+}
+
+type PollStatus = Awaited<ReturnType<typeof apiGetStatus>>;
+
+function terminalKindFromState(state: DownloadJobState): Terminal | null {
+  return state === "complete"
+    ? "complete"
+    : state === "error"
+      ? "error"
+      : state === "cancelled"
+        ? "cancelled"
+        : null;
+}
+
+function syncServerGeneration(
+  key: string,
+  job: ManagedDownload,
+  status: PollStatus,
+): boolean {
+  const statusGeneration = status.generation;
+  const previousGeneration = job.serverGeneration;
+  const generationChanged =
+    typeof statusGeneration === "number" &&
+    Number.isSafeInteger(statusGeneration) &&
+    typeof previousGeneration === "number" &&
+    Number.isSafeInteger(previousGeneration) &&
+    statusGeneration !== previousGeneration;
+  if (
+    typeof statusGeneration === "number" &&
+    Number.isSafeInteger(statusGeneration)
+  ) {
+    patchJob(key, { serverGeneration: statusGeneration });
+  }
+  return generationChanged;
+}
+
+async function finalizeTerminalStatus(
+  key: string,
+  terminalKind: Terminal,
+  status: PollStatus,
+  abort: AbortController | null,
+  epoch: number,
+): Promise<void> {
+  const current = getState().jobs[key];
+  if (!current) return;
+  if (terminalKind === "complete") {
+    let finalBytes = current.downloadedBytes;
+    try {
+      const progressResp = await withPollRequestTimeout(abort, (signal) =>
+        apiGetProgress(current, signal),
+      );
+      if (!isCurrent(key, epoch)) return;
+      const latest = getState().jobs[key];
+      if (latest) {
+        const { downloadedBytes } = applyProgressUpdate(key, latest, progressResp);
+        finalBytes = downloadedBytes;
+      }
+    } catch {
+      // Terminal status is authoritative; progress reconciliation is best-effort.
+    }
+    finalize(key, "complete", { bytes: finalBytes });
+  } else if (terminalKind === "error") {
+    finalize(key, "error", { error: status.error ?? null });
+  } else {
+    finalize(key, "cancelled");
+  }
+}
+
+function applySpeedSample(
+  rt: JobRuntime,
+  current: ManagedDownload,
+  downloadedBytes: number,
+  nowMs: number,
+): number {
+  const last = rt.speedSample;
+  let bytesPerSec = last ? current.bytesPerSec : 0;
+  if (last) {
+    const dt = (nowMs - last.tMs) / 1000;
+    const db = Math.max(0, downloadedBytes - last.bytes);
+    if (dt > 0) {
+      const sample = db / dt;
+      bytesPerSec =
+        bytesPerSec > 0
+          ? bytesPerSec * SPEED_EMA_WEIGHT + sample * (1 - SPEED_EMA_WEIGHT)
+          : sample;
+    }
+  }
+  rt.speedSample = { bytes: downloadedBytes, tMs: nowMs };
+  return bytesPerSec;
+}
+
+function reconcileProgressAndSpeed(
+  rt: JobRuntime,
+  key: string,
+  current: ManagedDownload,
+  progressResp: ProgressLike,
+  generationChanged: boolean,
+): { madeProgress: boolean } {
+  const { expected, downloadedBytes, completedBytes, completeOnDisk, fraction, madeProgress } =
+    resolveProgressUpdate(current, progressResp, {
+      resetMonotonic: generationChanged,
+    });
+  const bytesPerSec = applySpeedSample(rt, current, downloadedBytes, Date.now());
+  patchJob(key, {
+    expectedBytes: expected,
+    downloadedBytes,
+    completedBytes,
+    completeOnDisk,
+    fraction,
+    bytesPerSec,
+  });
+  markPollSuccess(key, rt);
+  return { madeProgress };
+}
+
+function handleIdleAfterProgress(
+  rt: JobRuntime,
+  key: string,
+  madeProgress: boolean,
+): void {
+  const updatedJob = getState().jobs[key];
+  if (updatedJob && hasObservedExpectedBytes(updatedJob)) {
+    finalize(key, "complete", { bytes: updatedJob.downloadedBytes });
+  } else if (rt.cancelRequested) {
+    finalize(key, "cancelled");
+  } else if (madeProgress) {
+    rt.idleSinceMs = null;
+  } else {
+    rt.idleSinceMs ??= Date.now();
+    if (Date.now() - rt.idleSinceMs >= IDLE_EVICT_GRACE_MS) {
+      finalize(key, "gone");
+    }
+  }
+}
+
+function handleTickError(
+  key: string,
+  rt: JobRuntime,
+  epoch: number,
+  error: unknown,
+): void {
+  if (!isCurrent(key, epoch)) return;
+  const accessMessage = pollAccessErrorMessage(
+    error instanceof Error ? error.message : String(error ?? ""),
+  );
+  if (accessMessage) {
+    finalize(key, "error", { error: accessMessage });
+    return;
+  }
+  markPollFailure(key, rt);
+}
+
+async function tick(key: string): Promise<void> {
+  const rt = runtimeRegistry.runtimes.get(key);
+  if (!rt) return;
+  const job = getState().jobs[key];
+  if (!job) {
+    teardownRuntime(key);
+    return;
+  }
+  if (typeof document !== "undefined" && document.hidden) {
+    rt.speedSample = null;
+    return;
+  }
+  if (rt.inFlight) return;
+  rt.inFlight = true;
+  const epoch = rt.epoch;
+  const abort = rt.abort;
+  try {
+    const status = await withPollRequestTimeout(abort, (signal) =>
+      apiGetStatus(job, signal),
+    );
+    if (!isCurrent(key, epoch)) return;
+
+    const generationChanged = syncServerGeneration(key, job, status);
+
+    const terminalKind = terminalKindFromState(status.state);
+    if (terminalKind !== null) {
+      await finalizeTerminalStatus(key, terminalKind, status, abort, epoch);
+      return;
+    }
+
+    if (status.state === "idle") {
+      const observedJob = getState().jobs[key];
+      if (observedJob && hasObservedExpectedBytes(observedJob)) {
+        finalize(key, "complete", { bytes: observedJob.downloadedBytes });
+        return;
+      }
+    }
+
+    const forceProgress = status.state === "idle";
+    if (!shouldPollProgress(rt, forceProgress)) {
+      rt.idleSinceMs = null;
+      markPollSuccess(key, rt);
+      return;
+    }
+    rt.lastProgressPollAt = Date.now();
+    const jobForProgress = getState().jobs[key] ?? job;
+    const progressResp = await withPollRequestTimeout(abort, (signal) =>
+      apiGetProgress(jobForProgress, signal),
+    );
+    if (!isCurrent(key, epoch)) return;
+    const current = getState().jobs[key];
+    if (!current) return;
+
+    const { madeProgress } = reconcileProgressAndSpeed(
+      rt,
+      key,
+      current,
+      progressResp,
+      generationChanged,
+    );
+
+    if (status.state === "idle") {
+      handleIdleAfterProgress(rt, key, madeProgress);
+    } else {
+      rt.idleSinceMs = null;
+    }
+  } catch (error) {
+    handleTickError(key, rt, epoch, error);
+  } finally {
+    rt.inFlight = false;
+  }
+}
+
+function pollDelayMs(rt: JobRuntime): number {
+  if (typeof document !== "undefined" && document.hidden) {
+    return HIDDEN_POLL_INTERVAL_MS;
+  }
+  const elapsedMs = Date.now() - rt.pollStartedAt;
+  const base =
+    elapsedMs >= POLL_BACKOFF_AFTER_MS
+      ? POLL_BACKOFF_INTERVAL_MS
+      : POLL_INTERVAL_MS;
+  const jitter = Math.round((Math.random() * 2 - 1) * POLL_JITTER_MS);
+  return Math.max(100, base + jitter);
+}
+
+async function runPollTick(key: string): Promise<void> {
+  const startedRuntime = runtimeRegistry.runtimes.get(key);
+  const epoch = startedRuntime?.epoch;
+  try {
+    await tick(key);
+  } finally {
+    const rt = runtimeRegistry.runtimes.get(key);
+    if (
+      startedRuntime !== undefined &&
+      epoch !== undefined &&
+      rt === startedRuntime &&
+      isCurrent(key, epoch)
+    ) {
+      rt.pollTimer = window.setTimeout(
+        () => void runPollTick(key),
+        pollDelayMs(rt),
+      );
+    }
+  }
+}
+
+function beginPolling(key: string, rt: JobRuntime): void {
+  rt.pollingStarted = true;
+  if (typeof document !== "undefined") {
+    const epoch = rt.epoch;
+    rt.visibilityListener = () => {
+      if (document.hidden || !isCurrent(key, epoch)) return;
+      const live = runtimeRegistry.runtimes.get(key);
+      if (live !== rt) return;
+      if (live.inFlight) return;
+      if (live.pollTimer != null) {
+        window.clearTimeout(live.pollTimer);
+        live.pollTimer = null;
+      }
+      void runPollTick(key);
+    };
+    document.addEventListener("visibilitychange", rt.visibilityListener);
+  }
+  void runPollTick(key);
+}
+
+function reissueDroppedStartCancel(
+  req: DownloadRequest,
+  generation: number | undefined,
+): void {
+  if (!Number.isSafeInteger(generation)) {
+    return;
+  }
+  void withDownloadTimeout(async (signal) => {
+    await apiCancelRequest(req, generation, signal);
+  }).catch(() => {});
+}
+
+export async function startJob(
+  req: DownloadRequest,
+  opts: {
+    adopt?: boolean;
+    useXet?: boolean;
+    generation?: number;
+    state?: DownloadJobState;
+  } = {},
+): Promise<void> {
+  const key = jobKeyOf(req.kind, req.repoId, req.variant);
+  // Peer guard stops a FRESH start from double-starting a variant already
+  // downloading (or colliding with a no-variant snapshot). Skipped when ADOPTING:
+  // the restored own entry would look like a peer and freeze the bar; adoptJob's
+  // `pollingStarted` guard already prevents double-polling the same key.
+  if (!opts.adopt && hasActiveRepoPeer(req.kind, req.repoId, key, req.variant)) {
+    return;
+  }
+  const nextEpoch = (runtimeRegistry.runtimes.get(key)?.epoch ?? 0) + 1;
+  teardownRuntime(key);
+  const existing = getState().jobs[key];
+  const adoptingCancel =
+    opts.adopt === true &&
+    (opts.state === "cancelling" ||
+      (opts.state === undefined && existing?.state === "cancelling"));
+  const rt: JobRuntime = {
+    kind: req.kind,
+    repoId: req.repoId,
+    epoch: nextEpoch,
+    pollTimer: null,
+    pollStartedAt: Date.now(),
+    pollingStarted: false,
+    abort: new AbortController(),
+    inFlight: false,
+    cancelRequested: adoptingCancel,
+    watchdog: null,
+    speedSample: null,
+    idleSinceMs: null,
+    lastProgressPollAt: null,
+    pollFailureStartedAt: null,
+    visibilityListener: null,
+  };
+  runtimeRegistry.runtimes.set(key, rt);
+  const epoch = rt.epoch;
+
+  const expected = Math.max(existing?.expectedBytes ?? 0, req.expectedBytes);
+  const hfToken = getHfToken() || null;
+  const requestedUseXet = opts.useXet ?? (getTransportMode() === TRANSPORT.XET);
+  const requestedMode: TransportMode = requestedUseXet
+    ? TRANSPORT.XET
+    : TRANSPORT.HTTP;
+  let mode: TransportMode;
+  try {
+    mode = opts.adopt
+      ? TRANSPORT.HTTP
+      : await effectiveTransportMode(requestedMode);
+  } catch (error) {
+    teardownRuntime(key);
+    throw error;
+  }
+  const seedDownloaded = opts.adopt ? (existing?.downloadedBytes ?? 0) : 0;
+  const seedCompleted = opts.adopt ? (existing?.completedBytes ?? 0) : 0;
+  const seedFraction = opts.adopt ? (existing?.fraction ?? 0) : 0;
+  // An adopted job never called apiStart, so it learns the run's generation from
+  // the probe (or persisted value) to scope a later cancel to this exact run.
+  const seedGeneration = opts.adopt
+    ? Number.isSafeInteger(opts.generation)
+      ? opts.generation
+      : existing?.serverGeneration
+    : undefined;
+  if (!opts.adopt && hasActiveRepoPeer(req.kind, req.repoId, key, req.variant)) {
+    teardownRuntime(key);
+    return;
+  }
+  putJob({
+    key,
+    kind: req.kind,
+    repoId: req.repoId,
+    variant: req.variant,
+    state: adoptingCancel ? "cancelling" : "running",
+    downloadedBytes: seedDownloaded,
+    completedBytes: seedCompleted,
+    completeOnDisk: false,
+    expectedBytes: expected,
+    fraction: seedFraction,
+    bytesPerSec: 0,
+    error: null,
+    startedAt: opts.adopt ? (existing?.startedAt ?? Date.now()) : Date.now(),
+    ...(Number.isSafeInteger(seedGeneration)
+      ? { serverGeneration: seedGeneration }
+      : {}),
+  });
+
+  if (!opts.adopt) {
+    let result;
+    try {
+      result = await apiStart(req, mode === TRANSPORT.XET, hfToken);
+    } catch (err) {
+      if (!isCurrent(key, epoch)) return;
+      finalize(key, "error", {
+        error: normalizeDownloadError(err),
+      });
+      return;
+    }
+    // A cancel pressed during this apiStart round-trip can land before the job is
+    // claimable; re-issue against the accepted generation.
+    if (rt.cancelRequested && result.accepted) {
+      reissueDroppedStartCancel(req, result.generation);
+    }
+    if (!isCurrent(key, epoch)) return;
+    if (!result.accepted) {
+      finalize(key, "error", { error: describeUnacceptedStart(result.state) });
+      return;
+    }
+    if (Number.isSafeInteger(result.generation)) {
+      patchJob(key, { serverGeneration: result.generation });
+    }
+  }
+
+  beginPolling(key, rt);
+}
+
+function armCancelWatchdog(
+  key: string,
+  rt: JobRuntime,
+  cancelEpoch: number,
+): void {
+  rt.watchdog = window.setTimeout(() => {
+    void resolveCancelWatchdog(key, cancelEpoch);
+  }, CANCEL_WATCHDOG_MS);
+}
+
+async function resolveCancelWatchdog(
+  key: string,
+  cancelEpoch: number,
+): Promise<void> {
+  const rt = runtimeRegistry.runtimes.get(key);
+  if (!rt || rt.epoch !== cancelEpoch || !rt.cancelRequested) return;
+  const job = getState().jobs[key];
+  if (!job) return;
+  const probe = await probeCancelOutcome(key, job, rt, cancelEpoch);
+  if (probe === "stale") return;
+  const live = runtimeRegistry.runtimes.get(key);
+  if (!live || live.epoch !== cancelEpoch || !live.cancelRequested) return;
+  if (probe.terminal === "complete") {
+    finalize(key, "complete", { bytes: getState().jobs[key]?.downloadedBytes ?? 0 });
+  } else if (probe.terminal === "error") {
+    finalize(key, "error", { error: probe.error });
+  } else {
+    finalize(key, "cancelled");
+  }
+}
+
+function applyCancelResult(
+  key: string,
+  cancelEpoch: number,
+  result: { state: DownloadJobState },
+): void {
+  const live = runtimeRegistry.runtimes.get(key);
+  if (live && live.epoch !== cancelEpoch) return;
+  if (result.state === "cancelling" || result.state === "cancelled") {
+    if (!live || !live.pollingStarted) finalize(key, "cancelled");
+    return;
+  }
+  if (live) {
+    if (result.state !== "idle") {
+      live.cancelRequested = false;
+    }
+    clearWatchdog(live);
+  }
+  if (result.state === "complete") {
+    finalize(key, "complete", {
+      bytes: getState().jobs[key]?.downloadedBytes ?? 0,
+    });
+  } else if (result.state === "error") {
+    finalize(key, "error");
+  } else if (result.state === "idle") {
+    const current = getState().jobs[key];
+    finalize(
+      key,
+      current && hasObservedExpectedBytes(current) ? "complete" : "cancelled",
+    );
+  } else if (live?.pollingStarted) {
+    patchJob(key, { state: "running" });
+    toast.error("Couldn't cancel the download. It's still running.");
+  } else {
+    finalize(key, "cancelled");
+  }
+}
+
+type CancelProbeResult = { terminal: Terminal | null; error: string | null };
+
+async function probeCancelOutcome(
+  key: string,
+  job: ManagedDownload,
+  rt: JobRuntime | undefined,
+  cancelEpoch: number,
+): Promise<CancelProbeResult | "stale"> {
+  try {
+    const probe = await withDownloadTimeout((signal) => apiGetStatus(job, signal));
+    if (probe.state === "complete") {
+      return { terminal: "complete", error: null };
+    }
+    if (probe.state === "error") {
+      return { terminal: "error", error: probe.error ?? null };
+    }
+    if (probe.state === "cancelled") {
+      return { terminal: "cancelled", error: null };
+    }
+    if (probe.state === "idle") {
+      const current = getState().jobs[key];
+      if (current && hasObservedExpectedBytes(current)) {
+        return { terminal: "complete", error: null };
+      }
+      if (current) {
+        try {
+          const progressResp = await withDownloadTimeout((signal) =>
+            apiGetProgress(current, signal),
+          );
+          const liveAfterProgress = runtimeRegistry.runtimes.get(key);
+          if (rt && liveAfterProgress && liveAfterProgress.epoch !== cancelEpoch) {
+            return "stale";
+          }
+          const latest = getState().jobs[key];
+          if (latest) {
+            applyProgressUpdate(key, latest, progressResp);
+            const updated = getState().jobs[key];
+            return {
+              terminal:
+                updated && hasObservedExpectedBytes(updated)
+                  ? "complete"
+                  : "cancelled",
+              error: null,
+            };
+          }
+          return { terminal: "cancelled", error: null };
+        } catch {
+          return { terminal: "cancelled", error: null };
+        }
+      }
+      return { terminal: "cancelled", error: null };
+    }
+    return { terminal: null, error: null };
+  } catch {
+    return { terminal: null, error: null };
+  }
+}
+
+export async function cancelJob(key: string): Promise<void> {
+  const job = getState().jobs[key];
+  if (!job) return;
+  const rt = runtimeRegistry.runtimes.get(key);
+  const cancelEpoch = rt?.epoch ?? 0;
+  if (rt) rt.cancelRequested = true;
+  patchJob(key, { state: "cancelling" });
+  clearWatchdog(rt);
+  if (rt) armCancelWatchdog(key, rt, cancelEpoch);
+  try {
+    const result = await withDownloadTimeout<{ state: DownloadJobState }>(
+      (signal) => apiCancel(job, signal),
+    );
+    applyCancelResult(key, cancelEpoch, result);
+  } catch (err) {
+    const liveAtError = runtimeRegistry.runtimes.get(key);
+    if (rt && liveAtError && liveAtError.epoch !== cancelEpoch) return;
+    // apiCancel failed; the probe below is authoritative. Disarm the watchdog so
+    // it can't finalize "cancelled" mid-probe and tear down a still-running worker.
+    clearWatchdog(liveAtError);
+
+    const probe = await probeCancelOutcome(key, job, rt, cancelEpoch);
+    if (probe === "stale") return;
+
+    const live = runtimeRegistry.runtimes.get(key);
+    if (rt && (!live || live.epoch !== cancelEpoch)) return;
+
+    if (probe.terminal !== null) {
+      if (probe.terminal === "complete") {
+        const current = getState().jobs[key];
+        finalize(key, "complete", { bytes: current?.downloadedBytes ?? 0 });
+      } else if (probe.terminal === "error") {
+        finalize(key, "error", { error: probe.error });
+      } else {
+        finalize(key, "cancelled");
+      }
+      return;
+    }
+
+    if (live) {
+      live.cancelRequested = false;
+    }
+    patchJob(key, { state: "running" });
+    toast.error("Couldn't cancel the download. It's still running.");
+    console.warn("Failed to cancel download", err);
+  }
+}
+
+export function adoptJob(
+  req: DownloadRequest,
+  generation?: number,
+  state?: DownloadJobState,
+): void {
+  const key = jobKeyOf(req.kind, req.repoId, req.variant);
+  if (runtimeRegistry.runtimes.get(key)?.pollingStarted) return;
+  void startJob(req, { adopt: true, generation, state });
+}
+
+type ProbeAndAdoptOptions = {
+  includeVariants?: boolean;
+  fresh?: boolean;
+  onModelAdopt?: (download: ActiveModelDownload) => void;
+};
+
+export async function probeAndAdopt(
+  kind: DownloadKind,
+  repoId: string,
+  signal: AbortSignal,
+  options: ProbeAndAdoptOptions = {},
+): Promise<void> {
+  try {
+    if (kind === DOWNLOAD_KIND.MODEL) {
+      const downloads = await getActiveModelDownloads(repoId, signal, {
+        fresh: options.fresh,
+      });
+      if (signal.aborted) return;
+      const activeDownloads = downloads.filter(
+        (download) =>
+          (options.includeVariants || download.variant === null) &&
+          (download.state === "running" || download.state === "cancelling"),
+      );
+      for (const active of activeDownloads) {
+        options.onModelAdopt?.(active);
+        adoptJob(
+          { kind, repoId, variant: active.variant, expectedBytes: 0 },
+          active.generation,
+          active.state,
+        );
+      }
+      return;
+    }
+
+    const status = await getDatasetDownloadStatus(repoId, signal);
+    if (signal.aborted) return;
+    if (status.state === "running" || status.state === "cancelling") {
+      adoptJob(
+        { kind, repoId, variant: null, expectedBytes: 0 },
+        status.generation,
+        status.state,
+      );
+    }
+  } catch (error) {
+    if (signal.aborted) {
+      return;
+    }
+    if (import.meta.env.DEV) {
+      console.debug("Download adoption probe failed", { kind, repoId, error });
+    }
+  }
+}
+
+export function setExpected(
+  kind: DownloadKind,
+  repoId: string,
+  variant: string | null,
+  bytes: number,
+): void {
+  setExpectedBytesForJob(kind, repoId, variant, bytes);
+}
diff --git a/studio/frontend/src/features/hub/download-manager/runtime-registry.ts b/studio/frontend/src/features/hub/download-manager/runtime-registry.ts
new file mode 100644
index 0000000000..0f203070b7
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/runtime-registry.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { JobListeners, JobRuntime } from "./download-manager-types";
+import { evictOldestUnprotected } from "../lib/lru-map";
+
+const MAX_SUPPRESSED_COMPLETED_INVENTORY_HINTS = 64;
+
+class DownloadManagerRuntimeRegistry {
+  readonly runtimes = new Map<string, JobRuntime>();
+  readonly listeners = new Map<string, Set<JobListeners>>();
+  readonly removalTimers = new Map<string, number>();
+  readonly hydrationRetryTimers = new Set<number>();
+  readonly suppressedCompletedInventoryHints = new Set<string>();
+  readonly pendingStartRepoKeys = new Set<string>();
+  inventoryBumpTimer: number | null = null;
+
+  clearRemovalTimer(key: string): void {
+    const timer = this.removalTimers.get(key);
+    if (timer === undefined) return;
+    clearRuntimeTimer(timer);
+    this.removalTimers.delete(key);
+  }
+
+  reset(): void {
+    for (const key of Array.from(this.runtimes.keys())) {
+      teardownRuntime(key);
+    }
+    for (const timer of this.removalTimers.values()) {
+      clearRuntimeTimer(timer);
+    }
+    for (const timer of this.hydrationRetryTimers) {
+      clearRuntimeTimer(timer);
+    }
+    clearRuntimeTimer(this.inventoryBumpTimer);
+    this.runtimes.clear();
+    this.listeners.clear();
+    this.removalTimers.clear();
+    this.hydrationRetryTimers.clear();
+    this.suppressedCompletedInventoryHints.clear();
+    this.pendingStartRepoKeys.clear();
+    this.inventoryBumpTimer = null;
+  }
+}
+
+export const runtimeRegistry = new DownloadManagerRuntimeRegistry();
+
+export function clearRuntimeTimer(timer: number | null): void {
+  if (timer === null) return;
+  if (typeof window !== "undefined") {
+    window.clearTimeout(timer);
+  } else {
+    globalThis.clearTimeout(timer);
+  }
+}
+
+export function clearWatchdog(rt: JobRuntime | undefined): void {
+  if (rt?.watchdog == null) return;
+  clearRuntimeTimer(rt.watchdog);
+  rt.watchdog = null;
+}
+
+export function teardownRuntime(key: string): void {
+  const rt = runtimeRegistry.runtimes.get(key);
+  if (!rt) return;
+  clearRuntimeTimer(rt.pollTimer);
+  if (rt.visibilityListener != null && typeof document !== "undefined") {
+    document.removeEventListener("visibilitychange", rt.visibilityListener);
+  }
+  rt.abort?.abort();
+  clearWatchdog(rt);
+  runtimeRegistry.runtimes.delete(key);
+}
+
+export function pruneSuppressedCompletedInventoryHints(
+  liveCompletedKeys: Set<string>,
+): void {
+  evictOldestUnprotected(
+    runtimeRegistry.suppressedCompletedInventoryHints,
+    MAX_SUPPRESSED_COMPLETED_INVENTORY_HINTS,
+    (key) => liveCompletedKeys.has(key),
+  );
+}
diff --git a/studio/frontend/src/features/hub/download-manager/transport-conflict.ts b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
new file mode 100644
index 0000000000..684ef544a2
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { toast } from "@/lib/toast";
+import { disposableTimeoutSignal } from "../lib/abort-signals";
+import { getActiveModelDownloads } from "./api";
+import { TRANSPORT, type TransportMode } from "./constants";
+import {
+  apiTransportStatusWithRetry,
+  effectiveTransportMode,
+} from "./download-api-adapter";
+import type { DownloadRequest } from "./download-manager-types";
+import {
+  findActiveJobForRepo,
+  getState,
+  hasVariantRepoActivity,
+  jobKeyOf,
+  repoKeyOf,
+  setConflict,
+} from "./download-manager-state";
+import { startJob } from "./poll-loop";
+import { runtimeRegistry } from "./runtime-registry";
+import { getTransportMode } from "./transport-preference";
+import { ACTIVE_STATES, TRANSPORT_STATUS_TIMEOUT_MS } from "./download-manager-config";
+
+function reportConflictStartError(error: unknown): void {
+  const description =
+    error instanceof Error ? error.message : String(error || "Unknown error");
+  toast.error("Couldn't start download", { description });
+}
+
+function pendingStartKey(req: DownloadRequest): string {
+  return jobKeyOf(req.kind, req.repoId, req.variant);
+}
+
+function hasPendingStartForRepo(repoKey: string): boolean {
+  for (const key of runtimeRegistry.pendingStartRepoKeys) {
+    if (key === repoKey || key.startsWith(`${repoKey}#`)) return true;
+  }
+  return false;
+}
+
+function hasActiveOrPendingStart(req: DownloadRequest): boolean {
+  const key = pendingStartKey(req);
+  if (req.kind === "model" && req.variant) {
+    return hasVariantRepoActivity(req.kind, req.repoId, key, {
+      includeOwnRuntime: true,
+      includePending: true,
+    });
+  }
+  if (runtimeRegistry.pendingStartRepoKeys.has(key)) return true;
+  const repoKey = repoKeyOf(req.kind, req.repoId);
+  if (hasPendingStartForRepo(repoKey)) return true;
+  return (
+    Boolean(findActiveJobForRepo(getState().jobs, req.kind, req.repoId)) ||
+    Boolean(runtimeRegistry.runtimes.get(repoKey))
+  );
+}
+
+function asTransportMode(value: unknown): TransportMode | null {
+  return value === TRANSPORT.HTTP || value === TRANSPORT.XET ? value : null;
+}
+
+async function activeSiblingTransport(
+  req: DownloadRequest,
+): Promise<TransportMode | null> {
+  if (req.kind !== "model" || !req.variant) return null;
+  const timeout = disposableTimeoutSignal(TRANSPORT_STATUS_TIMEOUT_MS);
+  const downloads = await getActiveModelDownloads(req.repoId, timeout.signal, {
+    fresh: true,
+  }).finally(() => timeout.dispose());
+  const variant = req.variant.trim().toLowerCase();
+  for (const download of downloads) {
+    const siblingVariant = download.variant?.trim().toLowerCase();
+    if (!siblingVariant || siblingVariant === variant) continue;
+    if (!ACTIVE_STATES.has(download.state)) continue;
+    const transport = asTransportMode(download.transport);
+    if (transport) return transport;
+  }
+  return null;
+}
+
+async function runWithPendingStartGuard(
+  req: DownloadRequest,
+  action: () => Promise<void>,
+): Promise<void> {
+  const startKey = pendingStartKey(req);
+  if (hasActiveOrPendingStart(req)) return;
+  runtimeRegistry.pendingStartRepoKeys.add(startKey);
+  try {
+    await action();
+  } catch (error) {
+    reportConflictStartError(error);
+  } finally {
+    runtimeRegistry.pendingStartRepoKeys.delete(startKey);
+  }
+}
+
+export async function requestStart(req: DownloadRequest): Promise<void> {
+  await runWithPendingStartGuard(req, async () => {
+    let mode: TransportMode = getTransportMode();
+    try {
+      mode = await effectiveTransportMode(mode);
+    } catch (err) {
+      console.warn(
+        "Transport capability check failed; using the selected transport.",
+        err,
+      );
+    }
+    let siblingTransport: TransportMode | null = null;
+    let siblingProbed = false;
+    try {
+      siblingTransport = await activeSiblingTransport(req);
+      siblingProbed = true;
+      if (siblingTransport && siblingTransport !== mode) {
+        toast.info("Another variant is already downloading", {
+          description:
+            siblingTransport === TRANSPORT.XET
+              ? "This repository is currently downloading with Xet. Switch to Xet or wait for it to finish."
+              : "This repository is currently downloading with HTTP. Switch to HTTP or wait for it to finish.",
+        });
+        return;
+      }
+    } catch (err) {
+      console.warn("Active download transport check failed.", err);
+    }
+    try {
+      const status = await apiTransportStatusWithRetry(req);
+      if (
+        status.has_partial &&
+        status.last_transport &&
+        status.last_transport !== mode
+      ) {
+        setConflict(jobKeyOf(req.kind, req.repoId, req.variant), {
+          info: {
+            previous: status.last_transport,
+            next: mode,
+            resumable: status.resumable,
+          },
+          pending: req,
+        });
+        return;
+      }
+      if (status.has_partial && !status.last_transport) {
+        toast.info("Restarting this download", {
+          description:
+            "An earlier partial download can't be resumed, so it will start again from the beginning.",
+        });
+      }
+    } catch (err) {
+      console.warn(
+        "Transport status check failed; starting without partial-conflict preflight.",
+        err,
+      );
+      // Fail safe: Xet purges any partial unconditionally, so when we couldn't
+      // verify the partial we downgrade this one start to HTTP (resumes an HTTP
+      // partial, harmless for a fresh download); the Xet preference is kept for
+      // next time. Only downgrade once we confirmed no sibling variant is
+      // downloading, since a live sibling may be mid-transfer on Xet.
+      if (mode === TRANSPORT.XET && siblingProbed && !siblingTransport) {
+        toast.warning("Couldn't verify existing partial download", {
+          description:
+            "Starting with HTTP so an existing partial is not discarded. Switch transport to retry with Xet.",
+        });
+        await startJob(req, { useXet: false });
+        return;
+      }
+      toast.warning("Couldn't verify existing partial download", {
+        description:
+          "Starting with the selected transport. If a partial from another transport exists, it may be restarted from the beginning.",
+      });
+    }
+    await startJob(req, { useXet: mode === TRANSPORT.XET });
+  });
+}
+
+export function resumeConflict(conflictKey: string): void {
+  const entry = getState().conflicts[conflictKey];
+  if (!entry) return;
+  setConflict(conflictKey, null);
+  void runWithPendingStartGuard(entry.pending, () =>
+    startJob(entry.pending, {
+      useXet: entry.info.previous === TRANSPORT.XET,
+    }),
+  );
+}
+
+export function restartConflict(conflictKey: string): void {
+  const entry = getState().conflicts[conflictKey];
+  if (!entry) return;
+  setConflict(conflictKey, null);
+  void runWithPendingStartGuard(entry.pending, () =>
+    startJob(entry.pending, {
+      useXet: entry.info.next === TRANSPORT.XET,
+    }),
+  );
+}
+
+export function cancelConflict(conflictKey: string): void {
+  setConflict(conflictKey, null);
+}
diff --git a/studio/frontend/src/features/hub/download-manager/transport-preference.ts b/studio/frontend/src/features/hub/download-manager/transport-preference.ts
new file mode 100644
index 0000000000..a1af2a2470
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/transport-preference.ts
@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "@/lib/toast";
+import {
+  type DownloadTransportCapabilities,
+  getDownloadTransportCapabilities,
+} from "./api";
+import {
+  DEFAULT_TRANSPORT_MODE,
+  type TransportMode,
+  isTransportMode,
+} from "./constants";
+export type { TransportMode } from "./constants";
+
+const STORAGE_KEY = "unsloth.studio.transportMode";
+const CHANGE_EVENT = "unsloth:transport-preference-change";
+
+type TransportCapabilitiesState = {
+  capabilities: DownloadTransportCapabilities | null;
+  isLoading: boolean;
+};
+
+function readStored(): TransportMode {
+  if (typeof window === "undefined") {
+    return DEFAULT_TRANSPORT_MODE;
+  }
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    return isTransportMode(raw) ? raw : DEFAULT_TRANSPORT_MODE;
+  } catch {
+    return DEFAULT_TRANSPORT_MODE;
+  }
+}
+
+export function getTransportMode(): TransportMode {
+  return readStored();
+}
+
+export function useTransportMode(): [
+  TransportMode,
+  (next: TransportMode) => void,
+] {
+  const [mode, setMode] = useState<TransportMode>(readStored);
+
+  useEffect(() => {
+    const handleLocal = () => setMode(readStored());
+    const handleStorage = (event: StorageEvent) => {
+      if (event.storageArea !== window.localStorage) {
+        return;
+      }
+      if (event.key !== null && event.key !== STORAGE_KEY) {
+        return;
+      }
+      setMode(readStored());
+    };
+    window.addEventListener(CHANGE_EVENT, handleLocal);
+    window.addEventListener("storage", handleStorage);
+    return () => {
+      window.removeEventListener(CHANGE_EVENT, handleLocal);
+      window.removeEventListener("storage", handleStorage);
+    };
+  }, []);
+
+  const set = useCallback((next: TransportMode) => {
+    // Persist first, reflect after: the engine reads getTransportMode() fresh from
+    // localStorage at download time, so an optimistic setMode() before a failed
+    // write would show the new transport while downloads still used the old one.
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      toast.error("Couldn't save the download transport preference.");
+      return;
+    }
+    setMode(next);
+    window.dispatchEvent(new Event(CHANGE_EVENT));
+  }, []);
+
+  return [mode, set];
+}
+
+export function useDownloadTransportCapabilities(): TransportCapabilitiesState {
+  const [state, setState] = useState<TransportCapabilitiesState>({
+    capabilities: null,
+    isLoading: true,
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    getDownloadTransportCapabilities()
+      .then((capabilities) => {
+        if (cancelled) {
+          return;
+        }
+        setState({ capabilities, isLoading: false });
+      })
+      .catch(() => {
+        if (cancelled) {
+          return;
+        }
+        setState({ capabilities: null, isLoading: false });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return state;
+}
diff --git a/studio/frontend/src/features/hub/download-manager/types.ts b/studio/frontend/src/features/hub/download-manager/types.ts
new file mode 100644
index 0000000000..b2bf9d6a96
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/types.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { TransportMode } from "./constants";
+
+export interface TransportConflictInfo {
+  previous: TransportMode;
+  next: TransportMode;
+  resumable: boolean;
+}
diff --git a/studio/frontend/src/features/hub/download-manager/use-repo-download.ts b/studio/frontend/src/features/hub/download-manager/use-repo-download.ts
new file mode 100644
index 0000000000..374e6b1f44
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/use-repo-download.ts
@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useMemo } from "react";
+import { useShallow } from "zustand/react/shallow";
+import { useLatestRef } from "../hooks/use-latest-ref";
+import type { TransportConflictInfo } from "./types";
+import {
+  type DownloadKind,
+  type JobListeners,
+  downloadManager,
+  jobKeyOf,
+  selectActiveJob,
+  subscribeJobListeners,
+  useDownloadManagerStore,
+} from "./download-manager-controller";
+
+export interface DownloadJobProgress {
+  variant: string | null;
+  expectedBytes: number;
+  downloadedBytes: number;
+  fraction: number;
+}
+
+export interface DownloadJob {
+  progress: DownloadJobProgress | null;
+  bytesPerSec: number;
+  cancelling: boolean;
+  repoPeerActive: boolean;
+  transportConflict: TransportConflictInfo | null;
+  requestStartDownload: (
+    variant: string | null,
+    expectedBytes: number,
+  ) => Promise<void>;
+  cancelDownload: (variant: string | null) => void;
+  setExpectedBytes: (bytes: number, variant?: string | null) => void;
+  resumeConflict: () => void;
+  restartConflict: () => void;
+  cancelConflict: () => void;
+}
+
+export interface RepoDownloadConfig {
+  kind: DownloadKind;
+  repoId: string;
+  activeVariant?: string | null;
+  onComplete?: JobListeners["onComplete"];
+  onCancelled?: JobListeners["onCancelled"];
+  onError?: JobListeners["onError"];
+  // Attach to a no-variant backend download already running (GGUF surfaces adopt their own variant).
+  autoAdopt?: boolean;
+}
+
+/**
+ * Binds a single download surface (one repo, optionally per GGUF variant) to the
+ * global download manager. Job state and polling live in the store, so a download
+ * keeps running and stays visible after the card unmounts.
+ */
+export function useRepoDownload(config: RepoDownloadConfig): DownloadJob {
+  const {
+    kind,
+    repoId,
+    activeVariant,
+    onComplete,
+    onCancelled,
+    onError,
+    autoAdopt,
+  } = config;
+
+  const handlersRef = useLatestRef<JobListeners>({
+    onComplete,
+    onCancelled,
+    onError,
+  });
+  useEffect(() => {
+    return subscribeJobListeners(kind, repoId, {
+      onComplete: (variant, bytes) =>
+        handlersRef.current.onComplete?.(variant, bytes),
+      onCancelled: (variant) => handlersRef.current.onCancelled?.(variant),
+      onError: (variant) => handlersRef.current.onError?.(variant),
+    });
+  }, [handlersRef, kind, repoId]);
+
+  useEffect(() => {
+    if (!autoAdopt) return;
+    const controller = new AbortController();
+    void downloadManager.probeAndAdopt(kind, repoId, controller.signal);
+    return () => controller.abort();
+  }, [autoAdopt, kind, repoId]);
+
+  const activeState = useDownloadManagerStore(
+    useShallow((state) => {
+      if (activeVariant === undefined) {
+        return {
+          active: selectActiveJob(state, kind, repoId),
+          repoPeerActive: false,
+        };
+      }
+      const active = selectActiveJob(state, kind, repoId, activeVariant);
+      const repoActive = selectActiveJob(state, kind, repoId);
+      return {
+        active,
+        repoPeerActive: Boolean(repoActive && repoActive.key !== active?.key),
+      };
+    }),
+  );
+  const active = activeState.active;
+  const conflictKey = useMemo(
+    () => jobKeyOf(kind, repoId, activeVariant ?? null),
+    [activeVariant, kind, repoId],
+  );
+  const transportConflict = useDownloadManagerStore(
+    (state) => state.conflicts[conflictKey]?.info ?? null,
+  );
+
+  useEffect(
+    () => () => {
+      downloadManager.cancelConflict(conflictKey);
+    },
+    [conflictKey],
+  );
+
+  const requestStartDownload = useCallback(
+    (variant: string | null, expectedBytes: number) => {
+      return downloadManager.requestStart({
+        kind,
+        repoId,
+        variant,
+        expectedBytes,
+      });
+    },
+    [kind, repoId],
+  );
+
+  const cancelDownload = useCallback(
+    (variant: string | null) => {
+      const state = useDownloadManagerStore.getState();
+      const activeJob = selectActiveJob(state, kind, repoId, variant);
+      void downloadManager.cancel(
+        activeJob?.key ?? jobKeyOf(kind, repoId, variant),
+      );
+    },
+    [kind, repoId],
+  );
+
+  const setExpectedBytes = useCallback(
+    (bytes: number, variant: string | null = null) =>
+      downloadManager.setExpected(kind, repoId, variant, bytes),
+    [kind, repoId],
+  );
+
+  const resumeConflict = useCallback(
+    () => downloadManager.resumeConflict(conflictKey),
+    [conflictKey],
+  );
+  const restartConflict = useCallback(
+    () => downloadManager.restartConflict(conflictKey),
+    [conflictKey],
+  );
+  const cancelConflict = useCallback(
+    () => downloadManager.cancelConflict(conflictKey),
+    [conflictKey],
+  );
+
+  const progress = useMemo<DownloadJobProgress | null>(
+    () =>
+      active
+        ? {
+            variant: active.variant,
+            expectedBytes: active.expectedBytes,
+            downloadedBytes: active.downloadedBytes,
+            fraction: active.fraction,
+          }
+        : null,
+    [active],
+  );
+
+  return {
+    progress,
+    bytesPerSec: active?.bytesPerSec ?? 0,
+    cancelling: active?.state === "cancelling",
+    repoPeerActive: activeState.repoPeerActive,
+    transportConflict,
+    requestStartDownload,
+    cancelDownload,
+    setExpectedBytes,
+    resumeConflict,
+    restartConflict,
+    cancelConflict,
+  };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-copy-feedback.ts b/studio/frontend/src/features/hub/hooks/use-copy-feedback.ts
new file mode 100644
index 0000000000..58686850ff
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-copy-feedback.ts
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { copyToClipboard } from "@/lib/copy-to-clipboard";
+
+export function useCopyFeedback(resetMs = 1500) {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    async (value: string) => {
+      const ok = await copyToClipboard(value);
+      if (!ok) return;
+      setCopied(true);
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => setCopied(false), resetMs);
+    },
+    [resetMs],
+  );
+
+  return { copied, copy };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-dataset-size.ts b/studio/frontend/src/features/hub/hooks/use-dataset-size.ts
new file mode 100644
index 0000000000..db4623da47
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-dataset-size.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
+import { fingerprintToken } from "@/features/hub/lib/token-fingerprint";
+import { useEffect, useState } from "react";
+import {
+  type DatasetSizeInfo,
+  fetchDatasetSize,
+} from "../lib/dataset-size";
+
+export function useDatasetSize(
+  repoId: string | null | undefined,
+  options: { enabled?: boolean; token?: string | null } = {},
+): DatasetSizeInfo | null {
+  const online = useOnlineStatus();
+  const enabled = options.enabled ?? true;
+  const token = options.token || undefined;
+  const repoKey = repoId ?? "";
+  const key = repoKey ? `${repoKey}::${fingerprintToken(token)}` : "";
+  const [state, setState] = useState<{
+    key: string;
+    value: DatasetSizeInfo | null;
+  }>(() => ({ key, value: null }));
+
+  useEffect(() => {
+    if (!repoKey || !enabled || !online) return;
+    const controller = new AbortController();
+    void fetchDatasetSize(repoKey, token, controller.signal).then((value) => {
+      if (!controller.signal.aborted) {
+        setState({ key, value });
+      }
+    });
+    return () => {
+      controller.abort();
+    };
+  }, [enabled, key, online, repoKey, token]);
+
+  return state.key === key ? state.value : null;
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-discover-search.ts b/studio/frontend/src/features/hub/hooks/use-discover-search.ts
new file mode 100644
index 0000000000..6c11ca8dc4
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-discover-search.ts
@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { toast } from "@/lib/toast";
+import {
+  type HfModelResult,
+  type HfSortDirection,
+  type HfSortKey,
+  useHubModelSearch,
+} from "./use-hub-model-search";
+import {
+  type HfDatasetResult,
+  useHubDatasetSearch,
+} from "./use-hub-dataset-search";
+import type { ChannelPreset } from "../lib/channels";
+
+export interface DiscoverSearch {
+  results: HfModelResult[];
+  datasetResults: HfDatasetResult[];
+  scannedCount: number;
+  isLoading: boolean;
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  fetchMore: () => boolean;
+  searchError: string | null;
+  handleRetrySearch: () => void;
+}
+
+type DiscoverErrorKind = "offline" | "auth" | "rate-limited" | "server" | "unknown";
+
+const RECONNECT_RETRY_COOLDOWN_MS = 90_000;
+
+function classifyDiscoverError(
+  message: string,
+  online: boolean,
+): DiscoverErrorKind {
+  if (!online) return "offline";
+  const lower = message.toLowerCase();
+  if (
+    lower.includes("429") ||
+    lower.includes("rate limit") ||
+    lower.includes("too many requests")
+  ) {
+    return "rate-limited";
+  }
+  if (
+    lower.includes("401") ||
+    lower.includes("403") ||
+    lower.includes("unauthorized") ||
+    lower.includes("forbidden") ||
+    (lower.includes("token") && !lower.includes("unexpected token")) ||
+    lower.includes("authentication")
+  ) {
+    return "auth";
+  }
+  if (
+    lower.includes("500") ||
+    lower.includes("502") ||
+    lower.includes("503") ||
+    lower.includes("504") ||
+    lower.includes("server")
+  ) {
+    return "server";
+  }
+  return "unknown";
+}
+
+function discoverErrorTitle(kind: DiscoverErrorKind): string {
+  switch (kind) {
+    case "offline":
+      return "You're offline";
+    case "auth":
+      return "Hugging Face auth failed";
+    case "rate-limited":
+      return "Hugging Face rate limit";
+    default:
+      return "Couldn't reach Hugging Face";
+  }
+}
+
+export function useDiscoverSearch({
+  debouncedQuery,
+  accessToken,
+  isDiscoverTab,
+  isDatasetMode,
+  sortBy,
+  direction,
+  activeChannel,
+  online,
+}: {
+  debouncedQuery: string;
+  accessToken: string | undefined;
+  isDiscoverTab: boolean;
+  isDatasetMode: boolean;
+  sortBy: HfSortKey;
+  direction: HfSortDirection;
+  activeChannel: ChannelPreset | null;
+  online: boolean;
+}): DiscoverSearch {
+  const channelOption = useMemo(
+    () =>
+      activeChannel
+        ? {
+            owner: activeChannel.owner,
+            tags: activeChannel.tags,
+            query: activeChannel.query,
+            idSuffix: activeChannel.idSuffix,
+          }
+        : null,
+    [activeChannel],
+  );
+
+  const modelSearch = useHubModelSearch(debouncedQuery, {
+    accessToken,
+    sortBy,
+    sortDirection: direction,
+    pinUnslothFirst:
+      sortBy === "trendingScore" && direction === "desc" && !activeChannel,
+    enabled: online && isDiscoverTab && !isDatasetMode,
+    keepUnsupportedTags: true,
+    channel: channelOption,
+  });
+  const datasetSearch = useHubDatasetSearch(debouncedQuery, {
+    accessToken,
+    enabled: online && isDiscoverTab && isDatasetMode,
+    sortBy,
+    sortDirection: direction,
+  });
+
+  const results = isDatasetMode ? [] : modelSearch.results;
+  const isLoading = isDatasetMode ? datasetSearch.isLoading : modelSearch.isLoading;
+  const isLoadingMore = isDatasetMode
+    ? datasetSearch.isLoadingMore
+    : modelSearch.isLoadingMore;
+  const hasMore = isDatasetMode ? datasetSearch.hasMore : modelSearch.hasMore;
+  const scannedCount = isDatasetMode
+    ? datasetSearch.scannedCount
+    : modelSearch.scannedCount;
+  const rawFetchMore = isDatasetMode
+    ? datasetSearch.fetchMore
+    : modelSearch.fetchMore;
+  const rawSearchError = isDatasetMode ? datasetSearch.error : modelSearch.error;
+  const retrySearch = isDatasetMode ? datasetSearch.retry : modelSearch.retry;
+  const searchError = isDiscoverTab && online ? rawSearchError : null;
+  const fetchMore = useCallback(() => {
+    if (!online || !hasMore) return false;
+    return rawFetchMore();
+  }, [online, hasMore, rawFetchMore]);
+
+  const handleRetrySearch = useCallback(() => {
+    if (!online) {
+      toast.error("You're offline", {
+        description: "Reconnect to the internet to browse Hugging Face.",
+      });
+      return;
+    }
+    retrySearch();
+    toast.message("Retrying…", {
+      description: "Reaching Hugging Face for the latest models.",
+    });
+  }, [online, retrySearch]);
+
+  const lastErrorRef = useRef<DiscoverErrorKind | null>(null);
+  useEffect(() => {
+    if (!isDiscoverTab) {
+      lastErrorRef.current = null;
+      return;
+    }
+    if (!searchError) {
+      lastErrorRef.current = null;
+      return;
+    }
+    const errorKind = classifyDiscoverError(searchError, online);
+    if (lastErrorRef.current === errorKind) return;
+    lastErrorRef.current = errorKind;
+    toast.error(discoverErrorTitle(errorKind), {
+      description: online
+        ? searchError
+        : "Reconnect to the internet to browse models.",
+      action: { label: "Retry", onClick: handleRetrySearch },
+    });
+  }, [isDiscoverTab, searchError, online, handleRetrySearch]);
+
+  const wasOfflineRef = useRef(!online);
+  const lastReconnectAtRef = useRef(0);
+  useEffect(() => {
+    if (online && wasOfflineRef.current && isDiscoverTab) {
+      const now = Date.now();
+      if (now - lastReconnectAtRef.current > RECONNECT_RETRY_COOLDOWN_MS) {
+        lastReconnectAtRef.current = now;
+        toast.success("Back online", {
+          description: "Refreshing the discovery feed.",
+        });
+        retrySearch();
+      }
+    }
+    wasOfflineRef.current = !online;
+  }, [online, retrySearch, isDiscoverTab]);
+
+  return {
+    results,
+    datasetResults: datasetSearch.results,
+    scannedCount,
+    isLoading,
+    isLoadingMore,
+    hasMore,
+    fetchMore,
+    searchError,
+    handleRetrySearch,
+  };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-hub-dataset-search.ts b/studio/frontend/src/features/hub/hooks/use-hub-dataset-search.ts
new file mode 100644
index 0000000000..a232c0730a
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-hub-dataset-search.ts
@@ -0,0 +1,432 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { fetchWithTimeout } from "../lib/network";
+import type { HubModelType } from "../types";
+import { listDatasets } from "@huggingface/hub";
+import { useCallback, useMemo } from "react";
+import { useHubPaginatedSearch } from "./use-hub-paginated-search";
+
+interface DatasetInfoSplit {
+  name: string;
+  // biome-ignore lint/style/useNamingConvention: external schema
+  num_bytes: number;
+  // biome-ignore lint/style/useNamingConvention: external schema
+  num_examples: number;
+}
+
+interface CardDataWithInfo {
+  size_categories?: string[];
+  pretty_name?: string;
+  dataset_info?:
+    | {
+        splits?: DatasetInfoSplit[];
+        download_size?: number;
+        dataset_size?: number;
+      }
+    | Array<{ splits?: DatasetInfoSplit[] }>;
+}
+
+function extractTotalExamples(
+  cardData: CardDataWithInfo | undefined,
+): number | undefined {
+  if (!cardData?.dataset_info) {
+    return undefined;
+  }
+
+  const infos = Array.isArray(cardData.dataset_info)
+    ? cardData.dataset_info
+    : [cardData.dataset_info];
+
+  const examples = infos
+    .flatMap((info) => info.splits ?? [])
+    .filter((s) => typeof s.num_examples === "number")
+    .map((s) => s.num_examples);
+
+  return examples.length > 0 ? examples.reduce((a, b) => a + b, 0) : undefined;
+}
+
+export interface HfDatasetResult {
+  id: string;
+  downloads: number;
+  likes: number;
+  totalExamples?: number;
+  sizeCategory?: string;
+  taskCategories: string[];
+  plainTags: string[];
+}
+
+function mapDataset(raw: unknown): HfDatasetResult {
+  const ds = raw as {
+    name: string;
+    downloads?: number;
+    likes?: number;
+    tags?: string[];
+    cardData?: unknown;
+  };
+  const card = ds.cardData as CardDataWithInfo | undefined;
+  const tags = ds.tags ?? [];
+  const taskCategories = tags
+    .filter((t) => t.startsWith("task_categories:"))
+    .map((t) => t.slice("task_categories:".length));
+  const plainTags = tags.filter((t) => !t.includes(":"));
+  return {
+    id: ds.name,
+    downloads: ds.downloads ?? 0,
+    likes: ds.likes ?? 0,
+    totalExamples: extractTotalExamples(card),
+    sizeCategory: card?.size_categories?.[0],
+    taskCategories,
+    plainTags,
+  };
+}
+
+type DatasetSortKey =
+  | "trendingScore"
+  | "downloads"
+  | "likes"
+  | "lastModified"
+  | "createdAt";
+type DatasetSortDirection = "desc" | "asc";
+
+const DESC_ONLY_DATASET_SORTS = new Set<DatasetSortKey>(["trendingScore"]);
+const HF_DATASET_SEARCH_TIMEOUT_MS = 15_000;
+
+function makeDatasetSortFetch(
+  sortBy: DatasetSortKey,
+  direction: DatasetSortDirection,
+  signal?: AbortSignal,
+): typeof fetch {
+  return (input, init) => {
+    const rawUrl =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    const url = new URL(rawUrl);
+
+    if (!url.searchParams.has("sort")) {
+      url.searchParams.set("sort", sortBy);
+    }
+    const effectiveSort = (url.searchParams.get("sort") ?? sortBy) as
+      | DatasetSortKey
+      | undefined;
+    const effectiveDir =
+      effectiveSort && DESC_ONLY_DATASET_SORTS.has(effectiveSort)
+        ? "desc"
+        : direction;
+    url.searchParams.set("direction", effectiveDir === "asc" ? "1" : "-1");
+
+    return fetchWithTimeout(
+      url,
+      signal ? { ...init, signal } : init,
+      HF_DATASET_SEARCH_TIMEOUT_MS,
+    );
+  };
+}
+
+type DatasetRelevance = "incompatible" | "neutral" | "boosted";
+
+const BOOSTED_TASK_CATEGORIES: Record<HubModelType, Set<string>> = {
+  text: new Set([
+    "text-generation",
+    "text2text-generation",
+    "question-answering",
+    "summarization",
+    "conversational",
+  ]),
+  vision: new Set([
+    "image-text-to-text",
+    "visual-question-answering",
+    "image-to-text",
+    "image-captioning",
+  ]),
+  audio: new Set([
+    "text-to-speech",
+    "text-to-audio",
+    "automatic-speech-recognition",
+  ]),
+  embeddings: new Set([
+    "feature-extraction",
+    "sentence-similarity",
+    "text-retrieval",
+  ]),
+};
+
+const INCOMPATIBLE_TASKS_ALL_MODELS = new Set([
+  "text-to-3d",
+  "image-to-3d",
+  "robotics",
+  "reinforcement-learning",
+  "tabular-classification",
+  "tabular-regression",
+  "time-series-forecasting",
+]);
+
+const PRETRAINING_PLAIN_TAGS = new Set(["pretraining", "pre-training"]);
+const OCR_PLAIN_TAGS = new Set(["ocr", "document-ocr"]);
+
+const PRETRAINING_SIZE_CATEGORIES = new Set([
+  "5M<n<10M",
+  "10M<n<100M",
+  "100M<n<1B",
+  "1B<n<10B",
+  "10B<n<100B",
+  "100B<n<1T",
+  "n>1T",
+]);
+
+const OCR_OR_VISION_TEXT_TASKS = new Set([
+  "image-to-text",
+  "image-captioning",
+  "visual-question-answering",
+  "document-question-answering",
+]);
+
+const CURATED_EMPTY_QUERY_DATASET_IDS: Partial<Record<HubModelType, string[]>> = {
+  text: [
+    "unsloth/alpaca-cleaned",
+    "unsloth/OpenMathReasoning-mini",
+    "mlabonne/FineTome-100k",
+    "openai/gsm8k",
+    "philschmid/guanaco-sharegpt-style",
+    "open-r1/DAPO-Math-17k-Processed",
+    "HuggingFaceH4/Multilingual-Thinking",
+    "HuggingFaceH4/ultrafeedback_binarized",
+    "reciperesearch/dolphin-sft-v0.1-preference",
+    "roneneldan/TinyStories",
+    "FreedomIntelligence/alpaca-gpt4-korean",
+    "Goedel-LM/SFT_dataset_v2",
+    "allenai/tulu-3-sft-mixture",
+    "HuggingFaceH4/no_robots",
+    "Magpie-Align/Magpie-Air-300K-Filtered",
+    "teknium/OpenHermes-2.5",
+    "databricks/databricks-dolly-15k",
+    "tatsu-lab/alpaca",
+    "garage-bAInd/Open-Platypus",
+    "microsoft/orca-math-word-problems-200k",
+    "Open-Orca/OpenOrca",
+    "openbmb/UltraInteract_sft",
+  ],
+  vision: [
+    "unsloth/LaTeX_OCR",
+    "unsloth/llava-instruct-mix-vsft-mini",
+    "unsloth/Radiology_mini",
+    "AI4Math/MathVista",
+    "AI4Math/MathVerse",
+    "ChongyanChen/VQAonline",
+    "lmms-lab/VQAv2",
+    "hezarai/parsynth-ocr-200k",
+  ],
+  audio: [
+    "MrDragonFox/Elise",
+    "keithito/lj_speech",
+    "parler-tts/mls_eng_10k",
+    "parler-tts/libritts-r-filtered-speaker-descriptions",
+    "openslr/librispeech_asr",
+    "MikhailT/hifi-tts",
+    "mozilla-foundation/common_voice_17_0",
+    "facebook/voxpopuli",
+    "speechcolab/gigaspeech",
+    "kth-tmh/vctk",
+    "Wenetspeech4TTS/WenetSpeech4TTS",
+  ],
+  embeddings: [
+    "electroglyph/technical",
+  ],
+};
+
+const INCOMPATIBLE_TASKS_BY_MODEL: Record<HubModelType, Set<string>> = {
+  text: new Set([
+    "text-to-image",
+    "image-to-image",
+    "image-to-video",
+    "text-to-video",
+    "image-classification",
+    "image-feature-extraction",
+    "image-text-to-image",
+    "zero-shot-image-classification",
+    "keypoint-detection",
+    "object-detection",
+    "image-segmentation",
+    "depth-estimation",
+    "text-to-speech",
+    "text-to-audio",
+    "audio-classification",
+    "audio-to-audio",
+    "automatic-speech-recognition",
+    "video-classification",
+    "visual-document-retrieval",
+  ]),
+  vision: new Set([
+    "text-to-speech",
+    "text-to-audio",
+    "audio-classification",
+    "audio-to-audio",
+    "automatic-speech-recognition",
+  ]),
+  audio: new Set([
+    "text-to-image",
+    "image-to-image",
+    "image-to-video",
+    "text-to-video",
+    "image-classification",
+    "image-feature-extraction",
+    "image-text-to-image",
+    "zero-shot-image-classification",
+    "keypoint-detection",
+    "object-detection",
+    "image-segmentation",
+    "depth-estimation",
+    "video-classification",
+    "visual-document-retrieval",
+  ]),
+  embeddings: new Set([
+    "text-to-image",
+    "image-to-image",
+    "image-to-video",
+    "text-to-video",
+    "image-classification",
+    "image-feature-extraction",
+    "image-text-to-image",
+    "zero-shot-image-classification",
+    "keypoint-detection",
+    "object-detection",
+    "image-segmentation",
+    "depth-estimation",
+    "text-to-speech",
+    "text-to-audio",
+    "audio-classification",
+    "audio-to-audio",
+    "automatic-speech-recognition",
+    "video-classification",
+    "visual-document-retrieval",
+  ]),
+};
+
+function isPretrainingDataset(dataset: HfDatasetResult): boolean {
+  if (dataset.plainTags.some((t) => PRETRAINING_PLAIN_TAGS.has(t.toLowerCase())))
+    return true;
+  if (
+    dataset.sizeCategory &&
+    PRETRAINING_SIZE_CATEGORIES.has(dataset.sizeCategory)
+  )
+    return true;
+  return false;
+}
+
+function rankDatasetRelevance(
+  dataset: HfDatasetResult,
+  modelType: HubModelType,
+): DatasetRelevance {
+  if (isPretrainingDataset(dataset)) return "incompatible";
+
+  // Keep OCR / vision-text corpora out of non-vision defaults.
+  if (modelType !== "vision") {
+    if (
+      dataset.plainTags.some((t) => OCR_PLAIN_TAGS.has(t.toLowerCase())) ||
+      dataset.taskCategories.some((t) => OCR_OR_VISION_TEXT_TASKS.has(t))
+    ) {
+      return "incompatible";
+    }
+  }
+
+  const { taskCategories } = dataset;
+  if (taskCategories.length === 0) return "neutral";
+
+  const boosted = BOOSTED_TASK_CATEGORIES[modelType];
+  const modelIncompat = INCOMPATIBLE_TASKS_BY_MODEL[modelType];
+
+  if (taskCategories.some((t) => boosted.has(t))) return "boosted";
+  if (
+    taskCategories.every(
+      (t) => INCOMPATIBLE_TASKS_ALL_MODELS.has(t) || modelIncompat.has(t),
+    )
+  )
+    return "incompatible";
+  return "neutral";
+}
+
+function isOcrOrVisionTextDataset(dataset: HfDatasetResult): boolean {
+  return (
+    dataset.plainTags.some((t) => OCR_PLAIN_TAGS.has(t.toLowerCase())) ||
+    dataset.taskCategories.some((t) => OCR_OR_VISION_TEXT_TASKS.has(t))
+  );
+}
+
+function toCuratedDatasetResult(id: string): HfDatasetResult {
+  // Curated defaults are id-only; this fills the shared result shape without extra HF requests.
+  return {
+    id,
+    downloads: 0,
+    likes: 0,
+    taskCategories: [],
+    plainTags: [],
+  };
+}
+
+export function useHubDatasetSearch(
+  query: string,
+  options?: {
+    modelType?: HubModelType | null;
+    accessToken?: string;
+    enabled?: boolean;
+    sortBy?: DatasetSortKey;
+    sortDirection?: DatasetSortDirection;
+  },
+) {
+  const {
+    modelType,
+    accessToken,
+    enabled = true,
+    sortBy = "trendingScore",
+    sortDirection = "desc",
+  } = options ?? {};
+  const hasQuery = query.trim().length > 0;
+  const useCuratedOnly = !hasQuery && !!modelType;
+  const createIter = useCallback(
+    (signal: AbortSignal) => {
+      if (useCuratedOnly) {
+        return (async function* empty() {})() as AsyncGenerator<unknown>;
+      }
+      return listDatasets({
+        search: hasQuery ? { query } : {},
+        additionalFields: ["cardData", "tags"],
+        fetch: makeDatasetSortFetch(sortBy, sortDirection, signal),
+        ...(accessToken ? { credentials: { accessToken } } : {}),
+      }) as AsyncGenerator<unknown>;
+    },
+    [useCuratedOnly, hasQuery, query, accessToken, sortBy, sortDirection],
+  );
+
+  const search = useHubPaginatedSearch(createIter, mapDataset, { enabled });
+
+  const results = useMemo(() => {
+    if (!enabled) return [];
+    const hideOcr = modelType !== "vision";
+    const baseResults = hideOcr
+      ? search.results.filter((ds) => !isOcrOrVisionTextDataset(ds))
+      : search.results;
+
+    if (!hasQuery && modelType) {
+      const curatedIds = CURATED_EMPTY_QUERY_DATASET_IDS[modelType] ?? [];
+      return curatedIds.map(toCuratedDatasetResult);
+    }
+
+    if (!modelType) return baseResults;
+
+    const boosted: HfDatasetResult[] = [];
+    const neutral: HfDatasetResult[] = [];
+
+    for (const ds of baseResults) {
+      const relevance = rankDatasetRelevance(ds, modelType);
+      if (relevance === "boosted") boosted.push(ds);
+      else if (relevance !== "incompatible") neutral.push(ds);
+    }
+
+    return [...boosted, ...neutral];
+  }, [enabled, search.results, modelType, query]);
+
+  return { ...search, results };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-hub-infinite-scroll.ts b/studio/frontend/src/features/hub/hooks/use-hub-infinite-scroll.ts
new file mode 100644
index 0000000000..2f37e2e713
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-hub-infinite-scroll.ts
@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * IntersectionObserver sentinel for infinite scroll, plus a ResizeObserver
+ * fallback that auto-fetches while the scroll container doesn't yet overflow.
+ * `signal` (typically results.length) is a dep so the fit check re-runs after a
+ * fetch even when the page filter rejected every new row and the DOM didn't change.
+ */
+// Hard backstop on no-overflow auto-fetches, capping a runaway sweep of the full listing.
+const DEFAULT_MAX_AUTO_FILL_FETCHES = 40;
+
+export interface InfiniteScrollOptions {
+  enabled?: boolean;
+  onFetchIntent?: () => void;
+  resultCount?: number;
+  resetKey?: string | number | boolean | null;
+  maxAutoFillFetches?: number;
+  manualFetchAfterAutoFill?: boolean;
+  isFetching?: boolean;
+}
+
+function hasScrollableOverflow(root: HTMLElement): boolean {
+  return root.scrollHeight > root.clientHeight + 4;
+}
+
+export function useHubInfiniteScroll(
+  fetchMore: () => boolean | void,
+  signal: number,
+  options: InfiniteScrollOptions = {},
+) {
+  const enabled = options.enabled ?? true;
+  const onFetchIntent = options.onFetchIntent;
+  const resultCount = options.resultCount ?? signal;
+  const resetKey = options.resetKey ?? null;
+  const maxAutoFillFetches =
+    options.maxAutoFillFetches ?? DEFAULT_MAX_AUTO_FILL_FETCHES;
+  const manualFetchAfterAutoFill = options.manualFetchAfterAutoFill ?? false;
+  const isFetching = options.isFetching ?? false;
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const sentinelRef = useRef<HTMLDivElement>(null);
+
+  const fetchMoreRef = useRef(fetchMore);
+  const onFetchIntentRef = useRef(onFetchIntent);
+  const enabledRef = useRef(enabled);
+  const isFetchingRef = useRef(isFetching);
+  useEffect(() => {
+    fetchMoreRef.current = fetchMore;
+  }, [fetchMore]);
+  useEffect(() => {
+    onFetchIntentRef.current = onFetchIntent;
+  }, [onFetchIntent]);
+  useEffect(() => {
+    enabledRef.current = enabled;
+  }, [enabled]);
+  useEffect(() => {
+    isFetchingRef.current = isFetching;
+  }, [isFetching]);
+
+  const autoFireCountRef = useRef(0);
+  const prevSignalRef = useRef(signal);
+  const prevResultCountRef = useRef(resultCount);
+  const resetKeyRef = useRef(resetKey);
+  const wasEnabledRef = useRef(false);
+  const manualFetchAvailableRef = useRef(false);
+  const manualStateTimerRef = useRef<ReturnType<
+    typeof globalThis.setTimeout
+  > | null>(null);
+  const [manualFetchAvailable, setManualFetchAvailableState] = useState(false);
+
+  const setManualFetchAvailable = useCallback((next: boolean) => {
+    manualFetchAvailableRef.current = next;
+    if (manualStateTimerRef.current !== null) {
+      globalThis.clearTimeout(manualStateTimerRef.current);
+    }
+    manualStateTimerRef.current = globalThis.setTimeout(() => {
+      manualStateTimerRef.current = null;
+      setManualFetchAvailableState((current) =>
+        current === next ? current : next,
+      );
+    }, 0);
+  }, []);
+
+  const requestFetchMore = useCallback(() => {
+    const accepted = fetchMoreRef.current() !== false;
+    if (accepted) {
+      onFetchIntentRef.current?.();
+    }
+    return accepted;
+  }, []);
+
+  const fetchMoreManually = useCallback(() => {
+    if (!enabledRef.current || isFetchingRef.current) return;
+    if (requestFetchMore()) {
+      setManualFetchAvailable(false);
+    }
+  }, [requestFetchMore, setManualFetchAvailable]);
+
+  useEffect(
+    () => () => {
+      if (manualStateTimerRef.current !== null) {
+        globalThis.clearTimeout(manualStateTimerRef.current);
+      }
+    },
+    [],
+  );
+
+  // Fires when the stable sentinel scrolls into view. Omits `signal` on purpose:
+  // rebuilding per batch could drop an intersection. Refills fall to the auto-fire effect.
+  useEffect(() => {
+    if (!enabled) return;
+    const sentinel = sentinelRef.current;
+    if (!sentinel) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            const root = scrollRef.current;
+            if (
+              !root ||
+              isFetchingRef.current ||
+              manualFetchAvailableRef.current ||
+              !hasScrollableOverflow(root)
+            ) {
+              continue;
+            }
+            if (autoFireCountRef.current >= maxAutoFillFetches) {
+              setManualFetchAvailable(manualFetchAfterAutoFill);
+              continue;
+            }
+            if (requestFetchMore()) {
+              autoFireCountRef.current += 1;
+            }
+          }
+        }
+      },
+      {
+        threshold: 0,
+        root: scrollRef.current,
+        rootMargin: "200px 0px",
+      },
+    );
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [
+    enabled,
+    manualFetchAfterAutoFill,
+    maxAutoFillFetches,
+    requestFetchMore,
+    setManualFetchAvailable,
+  ]);
+
+  // Auto-fire fallback: keep requesting batches while the container doesn't yet
+  // overflow (initial empty state or aggressive filters). Driven only off
+  // `enabled`/`signal` and a ResizeObserver on the scroll root, so it wakes on
+  // listing-shape changes rather than thrashing the main thread every frame
+  // (the prior childList/subtree observer was the dominant Hub lag source).
+  useEffect(() => {
+    if (!enabled) {
+      wasEnabledRef.current = false;
+      setManualFetchAvailable(false);
+      return;
+    }
+    // Fresh enable or a shrinking list clears the backstop so loading can refill the viewport.
+    if (
+      !wasEnabledRef.current ||
+      signal < prevSignalRef.current ||
+      resultCount < prevResultCountRef.current ||
+      resetKey !== resetKeyRef.current
+    ) {
+      autoFireCountRef.current = 0;
+      setManualFetchAvailable(false);
+    } else if (resultCount > prevResultCountRef.current) {
+      autoFireCountRef.current = 0;
+      setManualFetchAvailable(false);
+    }
+    wasEnabledRef.current = true;
+    prevSignalRef.current = signal;
+    prevResultCountRef.current = resultCount;
+    resetKeyRef.current = resetKey;
+
+    const root = scrollRef.current;
+    if (!root) return;
+
+    const tryFire = () => {
+      const sentinel = sentinelRef.current;
+      if (!sentinel?.isConnected) return;
+      if (manualFetchAvailableRef.current) return;
+      // Once content overflows, the IntersectionObserver takes over — stop polling.
+      if (hasScrollableOverflow(root)) {
+        setManualFetchAvailable(false);
+        return;
+      }
+      if (isFetchingRef.current) return;
+      if (autoFireCountRef.current >= maxAutoFillFetches) {
+        setManualFetchAvailable(manualFetchAfterAutoFill);
+        return;
+      }
+      if (requestFetchMore()) {
+        setManualFetchAvailable(false);
+        autoFireCountRef.current += 1;
+      }
+    };
+
+    let frame: number | null = null;
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        tryFire();
+      });
+    };
+
+    schedule();
+
+    const ro = new ResizeObserver(schedule);
+    ro.observe(root);
+
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      ro.disconnect();
+    };
+  }, [
+    enabled,
+    isFetching,
+    manualFetchAfterAutoFill,
+    maxAutoFillFetches,
+    resetKey,
+    requestFetchMore,
+    resultCount,
+    setManualFetchAvailable,
+    signal,
+  ]);
+
+  return {
+    scrollRef,
+    sentinelRef,
+    manualFetchAvailable,
+    fetchMoreManually,
+  };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-hub-model-search.ts b/studio/frontend/src/features/hub/hooks/use-hub-model-search.ts
new file mode 100644
index 0000000000..ebce58e9d8
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-hub-model-search.ts
@@ -0,0 +1,623 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { PipelineType } from "@huggingface/hub";
+import { listModels } from "@huggingface/hub";
+import {
+  type CachedResult,
+  cachedModelInfo,
+  primeCacheFromListing,
+} from "../lib/hf-cache";
+import { fetchWithTimeout } from "../lib/network";
+import {
+  startTransition,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { useHubPaginatedSearch } from "./use-hub-paginated-search";
+import { usePlatformStore } from "@/config/env";
+import {
+  EMBEDDING_TAGS,
+  estimateSizeFromDtypes,
+} from "../lib/hf-model-meta";
+import { isGgufLike } from "../lib/model-identifiers";
+import {
+  classifyUnslothSupport,
+  excludedFormatTagsForDevice,
+  type UnslothSupport,
+  type UnslothSupportStatus,
+} from "../lib/unsloth-support";
+
+const ALL_FIELDS: ("safetensors" | "tags")[] = ["safetensors", "tags"];
+
+export { classifyUnslothSupport };
+export type { UnslothSupport, UnslothSupportStatus };
+
+export type HfSortKey =
+  | "trendingScore"
+  | "downloads"
+  | "likes"
+  | "lastModified"
+  | "createdAt";
+
+export type HfSortDirection = "desc" | "asc";
+export type HfTaskFilter = PipelineType | readonly PipelineType[] | undefined;
+
+function normalizeTaskFilter(task: HfTaskFilter): readonly PipelineType[] {
+  if (!task) return [];
+  return typeof task === "string" ? [task] : task;
+}
+
+function taskMatches(
+  pipelineTag: string | undefined,
+  tasks: readonly PipelineType[],
+): boolean {
+  return (
+    tasks.length === 0 ||
+    !pipelineTag ||
+    tasks.includes(pipelineTag as PipelineType)
+  );
+}
+
+async function* mergeTaskIterators(
+  tasks: readonly PipelineType[],
+  createIter: (task?: PipelineType) => AsyncGenerator<unknown>,
+): AsyncGenerator<unknown> {
+  const seen = new Set<string>();
+  const taskList = tasks.length > 0 ? tasks : [undefined];
+  for (const task of taskList) {
+    for await (const model of createIter(task)) {
+      const name = (model as { name?: string }).name;
+      if (name) {
+        const key = name.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+      }
+      yield model;
+    }
+  }
+}
+
+export interface HfModelResult {
+  id: string;
+  downloads: number;
+  likes: number;
+  totalParams?: number;
+  estimatedSizeBytes?: number;
+  isGguf: boolean;
+  tags?: string[];
+  pipelineTag?: string;
+  updatedAt?: string;
+  libraryName?: string;
+  quantMethod?: string;
+}
+
+// HF rejects direction=1 (asc) for trendingScore — only descending is supported.
+const DESC_ONLY_SORTS = new Set<HfSortKey>(["trendingScore"]);
+const HF_SEARCH_TIMEOUT_MS = 15_000;
+
+function makeHfFetch(signal?: AbortSignal): typeof fetch {
+  return (input, init) =>
+    fetchWithTimeout(
+      input,
+      signal ? { ...init, signal } : init,
+      HF_SEARCH_TIMEOUT_MS,
+    );
+}
+
+function makeSortFetch(
+  sortBy: HfSortKey | undefined,
+  direction: HfSortDirection,
+  signal?: AbortSignal,
+): typeof fetch {
+  return (input, init) => {
+    const rawUrl =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    const url = new URL(rawUrl);
+
+    if (sortBy && !url.searchParams.has("sort")) {
+      url.searchParams.set("sort", sortBy);
+    }
+    const effectiveSort = (url.searchParams.get("sort") ?? sortBy) as
+      | HfSortKey
+      | undefined;
+    const effectiveDir =
+      effectiveSort && DESC_ONLY_SORTS.has(effectiveSort) ? "desc" : direction;
+    url.searchParams.set("direction", effectiveDir === "asc" ? "1" : "-1");
+
+    return fetchWithTimeout(
+      url,
+      signal ? { ...init, signal } : init,
+      HF_SEARCH_TIMEOUT_MS,
+    );
+  };
+}
+
+function makeMapModel(
+  excludeGguf: boolean,
+  excludedTags: ReadonlySet<string>,
+  keepUnsupportedTags: boolean,
+  idSuffix: string,
+  deviceType: string | null,
+) {
+  const suffixLower = idSuffix.toLowerCase();
+  return (raw: unknown): HfModelResult | null => {
+    const m = raw as {
+      name: string;
+      downloads?: number;
+      likes?: number;
+      task?: string;
+      pipeline_tag?: string;
+      library_name?: string;
+      updatedAt?: Date | string;
+      safetensors?: { total: number; parameters?: Record<string, number> };
+      gguf?: { total?: number; architecture?: string };
+      tags?: string[];
+      config?: { quantization_config?: { quant_method?: string } };
+    };
+    if (suffixLower && !m.name?.toLowerCase().endsWith(suffixLower)) {
+      return null;
+    }
+    const isEmbedding = m.tags?.some((t) => EMBEDDING_TAGS.has(t));
+    if (
+      !keepUnsupportedTags &&
+      !isEmbedding &&
+      m.tags?.some((t) => excludedTags.has(t))
+    ) {
+      return null;
+    }
+    const isGguf =
+      Boolean(m.tags?.some((tag) => tag.toLowerCase() === "gguf")) ||
+      isGgufLike(m.name);
+    if (excludeGguf && isGguf) {
+      return null;
+    }
+    const pipelineTag = m.task ?? m.pipeline_tag;
+    const quantMethod = m.config?.quantization_config?.quant_method;
+    // Drops runtime-unloadable models before they reach the row list. Discover
+    // opts out via keepUnsupportedTags to render them with a "may not be supported"
+    // dot. Embeddings skip the gate: their pipeline tag is unsupported for chat but trainable.
+    if (!keepUnsupportedTags && !isEmbedding) {
+      const support = classifyUnslothSupport({
+        modelId: m.name,
+        pipelineTag,
+        tags: m.tags,
+        libraryName: m.library_name,
+        deviceType,
+        quantMethod,
+      });
+      if (support.status === "unsupported") return null;
+    }
+    const updatedAtIso =
+      m.updatedAt instanceof Date
+        ? m.updatedAt.toISOString()
+        : typeof m.updatedAt === "string"
+          ? m.updatedAt
+          : undefined;
+    return {
+      id: m.name,
+      downloads: m.downloads ?? 0,
+      likes: m.likes ?? 0,
+      totalParams: m.safetensors?.total ?? m.gguf?.total,
+      estimatedSizeBytes: estimateSizeFromDtypes(m.safetensors?.parameters),
+      isGguf,
+      tags: m.tags,
+      pipelineTag,
+      updatedAt: updatedAtIso,
+      libraryName: m.library_name,
+      quantMethod,
+    };
+  };
+}
+
+/** Unsloth results pulled up-front before yielding general results. */
+const UNSLOTH_PREFETCH = 20;
+/** With a typed query, float only a few unsloth results before the general listing. */
+const UNSLOTH_QUERY_PREFETCH = 3;
+/** With a publisher query, fewer unsloth results before the pinned publisher model. */
+const UNSLOTH_PINNED_PREFETCH = 4;
+const PUBLISHER_RE = /^([^/\s]+)\/([^/\s]+)$/;
+
+/**
+ * Prime the hf-cache from a listModels result. For public models also prime the
+ * anonymous slot so the VRAM hook gets cache hits; gated/private models are cached
+ * only under the caller's token to avoid auth leakage.
+ */
+function primeFromListing(
+  name: string,
+  accessToken: string | undefined,
+  model: unknown,
+): void {
+  const data = model as CachedResult;
+  primeCacheFromListing(name, accessToken, data);
+  if (accessToken && !data.private && !data.gated) {
+    primeCacheFromListing(name, undefined, data);
+  }
+}
+
+/** Merged generator yielding unsloth-owned models first, then deduped general results. */
+async function* mergedModelIterator(
+  query: string,
+  task?: HfTaskFilter,
+  accessToken?: string,
+  pinnedId?: string,
+  sortBy: HfSortKey = "downloads",
+  direction: HfSortDirection = "desc",
+  signal?: AbortSignal,
+): AsyncGenerator<unknown> {
+  const sortFetch = makeSortFetch(sortBy, direction, signal);
+  const tasks = normalizeTaskFilter(task);
+  const common = {
+    additionalFields: ALL_FIELDS,
+    fetch: sortFetch,
+    ...(accessToken ? { credentials: { accessToken } } : {}),
+  };
+
+  const unslothIter = mergeTaskIterators(tasks, (task) =>
+    listModels({
+      search: { query, owner: "unsloth", ...(task ? { task } : {}) },
+      ...common,
+    }) as AsyncGenerator<unknown>,
+  );
+  const generalIter = mergeTaskIterators(tasks, (task) =>
+    listModels({
+      search: { query, ...(task ? { task } : {}) },
+      ...common,
+    }) as AsyncGenerator<unknown>,
+  );
+
+  // Start the pinned lookup now so it runs in parallel with Phase 1 instead of blocking Phase 2.
+  const pinnedPromise = pinnedId
+    ? cachedModelInfo({
+        name: pinnedId,
+        additionalFields: ALL_FIELDS,
+        fetch: makeHfFetch(signal),
+        ...(accessToken ? { credentials: { accessToken } } : {}),
+      }).catch(() => null)
+    : null;
+
+  const limit = pinnedId
+    ? UNSLOTH_PINNED_PREFETCH
+    : query.trim()
+      ? UNSLOTH_QUERY_PREFETCH
+      : UNSLOTH_PREFETCH;
+
+  // Phase 1: unsloth models first
+  const seen = new Set<string>();
+  let count = 0;
+  for await (const model of unslothIter) {
+    const m = model as { name?: string };
+    if (m.name) {
+      seen.add(m.name);
+      primeFromListing(m.name, accessToken, model);
+    }
+    yield model;
+    count++;
+    if (count >= limit) break;
+  }
+
+  // Phase 1b: pinned publisher model before general results
+  if (pinnedId && !seen.has(pinnedId) && pinnedPromise) {
+    const pinned = await pinnedPromise;
+    if (pinned) {
+      // Record raw input and HF's canonical name so Phase 2 dedup survives casing differences.
+      seen.add(pinnedId);
+      const canonicalName = (pinned as { name?: string }).name;
+      if (canonicalName && canonicalName !== pinnedId) {
+        seen.add(canonicalName);
+      }
+      yield pinned;
+    }
+  }
+
+  // Phase 2: general results, skipping already-seen models
+  for await (const model of generalIter) {
+    const m = model as { name?: string };
+    if (m.name && seen.has(m.name)) continue;
+    if (m.name) {
+      primeFromListing(m.name, accessToken, model);
+    }
+    yield model;
+  }
+}
+
+/** Yields priority models (fetched individually for full metadata), then the unsloth listing. */
+async function* priorityThenListingIterator(
+  priorityIds: readonly string[],
+  task?: HfTaskFilter,
+  accessToken?: string,
+  sortBy: HfSortKey = "downloads",
+  direction: HfSortDirection = "desc",
+  signal?: AbortSignal,
+): AsyncGenerator<unknown> {
+  const tasks = normalizeTaskFilter(task);
+  const common = {
+    additionalFields: ALL_FIELDS,
+    fetch: makeSortFetch(sortBy, direction, signal),
+    ...(accessToken ? { credentials: { accessToken } } : {}),
+  };
+
+  // Phase 1: priority models in parallel via modelInfo
+  const seen = new Set<string>();
+  const settled = await Promise.allSettled(
+    priorityIds.map((id) =>
+      cachedModelInfo({
+        name: id,
+        additionalFields: ALL_FIELDS,
+        fetch: makeHfFetch(signal),
+        ...(accessToken ? { credentials: { accessToken } } : {}),
+      }),
+    ),
+  );
+  for (const result of settled) {
+    if (result.status === "fulfilled") {
+      const m = result.value as { name?: string; pipeline_tag?: string };
+      if (!taskMatches(m.pipeline_tag, tasks)) continue;
+      if (m.name) seen.add(m.name);
+      yield result.value;
+    }
+  }
+
+  const generalIter = mergeTaskIterators(tasks, (task) =>
+    listModels({
+      search: { owner: "unsloth", ...(task ? { task } : {}) },
+      ...common,
+    }) as AsyncGenerator<unknown>,
+  );
+  for await (const model of generalIter) {
+    const m = model as { name?: string };
+    if (m.name && seen.has(m.name)) continue;
+    if (m.name) {
+      primeFromListing(m.name, accessToken, model);
+    }
+    yield model;
+  }
+}
+
+export interface HfModelSearchChannel {
+  owner?: string;
+  tags?: readonly string[];
+  /** Free-text query injected into the HF listModels search.query field. */
+  query?: string;
+  /** Strict client-side filter: drop results whose id doesn't end with this. */
+  idSuffix?: string;
+}
+
+export function useHubModelSearch(
+  query: string,
+  options?: {
+    task?: HfTaskFilter;
+    accessToken?: string;
+    excludeGguf?: boolean;
+    priorityIds?: readonly string[];
+    sortBy?: HfSortKey;
+    sortDirection?: HfSortDirection;
+    pinUnslothFirst?: boolean;
+    enabled?: boolean;
+    keepUnsupportedTags?: boolean;
+    channel?: HfModelSearchChannel | null;
+  },
+) {
+  const {
+    task,
+    accessToken,
+    excludeGguf = false,
+    priorityIds,
+    sortBy = "downloads",
+    sortDirection = "desc",
+    pinUnslothFirst = true,
+    enabled = true,
+    keepUnsupportedTags = false,
+    channel = null,
+  } = options ?? {};
+
+  const channelOwner = channel?.owner ?? null;
+  const channelTagsKey = channel?.tags ? channel.tags.join("|") : "";
+  const channelQuery = channel?.query ?? "";
+  const channelIdSuffix = channel?.idSuffix ?? "";
+  const priorityIdsKey = priorityIds?.join("|") ?? "";
+  const stablePriorityIds = useMemo(
+    () => (priorityIdsKey ? priorityIdsKey.split("|") : undefined),
+    [priorityIdsKey],
+  );
+
+  // Parse publisher detection once, shared between the iterator factory and the secondary sort gate.
+  const { isPublisherQuery, searchQuery, pinnedId, trimmed } = useMemo(() => {
+    const t = query.trim();
+    const m = PUBLISHER_RE.exec(t);
+    const is = !!m && m[1].toLowerCase() !== "unsloth";
+    return {
+      isPublisherQuery: is,
+      searchQuery: is ? m![2] : t,
+      pinnedId: is ? t : undefined,
+      trimmed: t,
+    };
+  }, [query]);
+
+  const createIter = useCallback(
+    (signal: AbortSignal) => {
+      // Channel scoping bypasses the unsloth-merge iterator: a hard owner/tag
+      // filter shows just that curated slice, with the user's text query forwarded into it.
+      if (channelOwner || channelTagsKey || channelQuery) {
+        const channelTags = channelTagsKey ? channelTagsKey.split("|") : undefined;
+        // User text query takes precedence over channel.query; without it, the
+        // channel's own query (e.g. "bnb-4bit") narrows the listing server-side.
+        const queryString = trimmed || channelQuery || undefined;
+        return listModels({
+          search: {
+            ...(queryString ? { query: queryString } : {}),
+            ...(channelOwner ? { owner: channelOwner } : {}),
+            ...(channelTags ? { tags: channelTags } : {}),
+          },
+          additionalFields: ALL_FIELDS,
+          fetch: makeSortFetch(sortBy, sortDirection, signal),
+          sort: sortBy,
+          ...(accessToken ? { credentials: { accessToken } } : {}),
+        }) as AsyncGenerator<unknown>;
+      }
+      if (!trimmed) {
+        // No query: priority models first (full metadata), then the general unsloth listing.
+        if (stablePriorityIds && stablePriorityIds.length > 0) {
+          return priorityThenListingIterator(
+            stablePriorityIds,
+            task,
+            accessToken,
+            sortBy,
+            sortDirection,
+            signal,
+          ) as AsyncGenerator<unknown>;
+        }
+        return mergeTaskIterators(normalizeTaskFilter(task), (task) =>
+          listModels({
+            search: { ...(task ? { task } : {}) },
+            additionalFields: ALL_FIELDS,
+            fetch: makeSortFetch(sortBy, sortDirection, signal),
+            sort: sortBy,
+            ...(accessToken ? { credentials: { accessToken } } : {}),
+          }) as AsyncGenerator<unknown>,
+        );
+      }
+      // Typed query: drop the task filter so searched models appear despite
+      // wrong/missing HF task metadata. For an "owner/repo" query, strip the org
+      // prefix so unsloth variants surface, then pin the original publisher model.
+      // Unsloth-owned queries are left as-is for the full prefetch + secondary sort.
+      return mergedModelIterator(
+        searchQuery,
+        undefined,
+        accessToken,
+        pinnedId,
+        sortBy,
+        sortDirection,
+        signal,
+      ) as AsyncGenerator<unknown>;
+    },
+    [
+      trimmed,
+      searchQuery,
+      pinnedId,
+      task,
+      accessToken,
+      stablePriorityIds,
+      sortBy,
+      sortDirection,
+      channelOwner,
+      channelTagsKey,
+      channelQuery,
+    ],
+  );
+
+  const deviceType = usePlatformStore((s) => s.deviceType);
+  const excludedTags = excludedFormatTagsForDevice(deviceType);
+  const mapModel = useMemo(
+    () =>
+      makeMapModel(
+        excludeGguf,
+        excludedTags,
+        keepUnsupportedTags,
+        channelIdSuffix,
+        deviceType,
+      ),
+    [excludeGguf, excludedTags, keepUnsupportedTags, channelIdSuffix, deviceType],
+  );
+  const search = useHubPaginatedSearch(createIter, mapModel, { enabled });
+
+  // Secondary sort only with no user query (merged iterator already floats
+  // unsloth results; re-sorting would bury matches) and outside channel scoping.
+  //
+  // STABLE-APPEND CONTRACT: when a later page lands, keep the sorted prefix
+  // verbatim and append only the new tail. Re-sorting the whole array would let
+  // a late unsloth/* repo jump to an earlier index and bump the viewport during
+  // infinite scroll, so we only sort when the listing resets (length shrinks or
+  // zeros), where re-ordering is safe.
+  const channelActive = Boolean(channelOwner || channelTagsKey);
+  const [stableCache, setStableCache] = useState<{
+    source: HfModelResult[] | null;
+    length: number;
+    results: HfModelResult[];
+    sorted: boolean;
+  }>({ source: null, length: 0, results: [], sorted: false });
+
+  const incoming = search.results;
+  const sortingDisabled =
+    !pinUnslothFirst || isPublisherQuery || trimmed || channelActive;
+  const { results, nextCache } = useMemo(() => {
+    let results: HfModelResult[];
+    let nextCache = stableCache;
+
+    if (sortingDisabled) {
+      results = incoming;
+      if (stableCache.results !== incoming || stableCache.sorted) {
+        nextCache = {
+          source: incoming,
+          length: incoming.length,
+          results: incoming,
+          sorted: false,
+        };
+      }
+    } else if (incoming.length === 0) {
+      results = incoming;
+      if (
+        stableCache.length !== 0 ||
+        stableCache.results !== incoming ||
+        !stableCache.sorted
+      ) {
+        nextCache = {
+          source: incoming,
+          length: 0,
+          results: incoming,
+          sorted: true,
+        };
+      }
+    } else if (
+      !stableCache.sorted ||
+      stableCache.length === 0 ||
+      incoming.length < stableCache.length ||
+      (incoming.length === stableCache.length && stableCache.source !== incoming)
+    ) {
+      const sorted = [...incoming].sort((a, b) => {
+        const aFirst = a.id.startsWith("unsloth/") ? 0 : 1;
+        const bFirst = b.id.startsWith("unsloth/") ? 0 : 1;
+        return aFirst - bFirst;
+      });
+      results = sorted;
+      nextCache = {
+        source: incoming,
+        length: incoming.length,
+        results: sorted,
+        sorted: true,
+      };
+    } else if (incoming.length === stableCache.length) {
+      results = stableCache.results;
+    } else {
+      const newTail = incoming.slice(stableCache.length);
+      const merged = stableCache.results.concat(newTail);
+      results = merged;
+      nextCache = {
+        source: incoming,
+        length: incoming.length,
+        results: merged,
+        sorted: true,
+      };
+    }
+
+    return { results, nextCache };
+  }, [incoming, sortingDisabled, stableCache]);
+
+  const cacheNeedsUpdate = nextCache !== stableCache;
+  useEffect(() => {
+    if (!cacheNeedsUpdate) return;
+    startTransition(() => {
+      setStableCache((current) =>
+        current === stableCache ? nextCache : current,
+      );
+    });
+  }, [cacheNeedsUpdate, nextCache, stableCache]);
+
+  return { ...search, results };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-hub-model-vram.ts b/studio/frontend/src/features/hub/hooks/use-hub-model-vram.ts
new file mode 100644
index 0000000000..db20d09a15
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-hub-model-vram.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useMemo } from "react";
+import type { GpuInfo } from "@/hooks/use-gpu-info";
+import {
+  type VramFitStatus,
+  checkVramFit,
+  estimateLoadingVram,
+} from "@/lib/vram";
+import { formatBytes } from "@/features/hub/lib/format";
+import type { SelectedModelView } from "../types";
+
+export interface ModelVramInfo {
+  est: number;
+  status: VramFitStatus;
+}
+
+export function useHubModelVram(
+  selectedModel: SelectedModelView | null,
+  gpu: GpuInfo,
+): { vramInfo: ModelVramInfo | null; minMemory: string | null } {
+  const vramInfo = useMemo<ModelVramInfo | null>(() => {
+    if (!selectedModel || selectedModel.isGguf || !selectedModel.totalParams) {
+      return null;
+    }
+    const est = estimateLoadingVram(selectedModel.totalParams, "qlora");
+    const status = checkVramFit(est, gpu.available ? gpu.memoryTotalGb : 0);
+    return status ? { est, status } : null;
+  }, [gpu, selectedModel]);
+
+  const minMemory = useMemo(() => {
+    if (!selectedModel) return null;
+    if (selectedModel.isGguf) {
+      if (selectedModel.cachedBytes)
+        return formatBytes(selectedModel.cachedBytes);
+      if (selectedModel.estimatedSizeBytes)
+        return formatBytes(selectedModel.estimatedSizeBytes);
+      return null;
+    }
+    if (selectedModel.estimatedSizeBytes)
+      return formatBytes(selectedModel.estimatedSizeBytes);
+    if (vramInfo) return `~${vramInfo.est} GB`;
+    if (selectedModel.cachedBytes)
+      return formatBytes(selectedModel.cachedBytes);
+    return null;
+  }, [selectedModel, vramInfo]);
+
+  return { vramInfo, minMemory };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-hub-paginated-search.ts b/studio/frontend/src/features/hub/hooks/use-hub-paginated-search.ts
new file mode 100644
index 0000000000..2d6214d442
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-hub-paginated-search.ts
@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+interface HfPaginatedState<T> {
+  results: T[];
+  scannedCount: number;
+  isLoading: boolean;
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  error: string | null;
+}
+
+const INITIAL: HfPaginatedState<never> = {
+  results: [],
+  scannedCount: 0,
+  isLoading: false,
+  isLoadingMore: false,
+  hasMore: false,
+  error: null,
+};
+const BATCH = 20;
+const MAX_RAW_ITEMS_PER_BATCH = BATCH * 4;
+type BusyKind = "initial" | "more";
+
+/**
+ * Min gap between fetchMore() calls. Two observers can fire in one tick and React
+ * commits the in-flight flag asynchronously, so this caps the worst case at one
+ * request per window. Pairs with a trailing-edge schedule: a blocked call queues
+ * one fire at the window end so filters that starve the visible list keep paginating.
+ */
+const MIN_FETCH_INTERVAL_MS = 1000;
+
+// Preserved results older than this are refetched on re-enable so the feed can't
+// lag the Hub. Reset by every successful pull (idle time only). Mirrors hf-cache TTL.
+const STALE_AFTER_MS = 5 * 60 * 1000;
+
+async function pullBatch<T>(
+  iter: AsyncGenerator<unknown>,
+  mapItem: (raw: unknown) => T | null,
+  size: number,
+) {
+  const items: T[] = [];
+  let scanned = 0;
+  while (items.length < size && scanned < MAX_RAW_ITEMS_PER_BATCH) {
+    const result = await iter.next();
+    if (result.done) {
+      return { items, done: true, scanned };
+    }
+    scanned += 1;
+    const mapped = mapItem(result.value);
+    if (mapped !== null) {
+      items.push(mapped);
+    }
+  }
+  return { items, done: false, scanned };
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+
+function isDocumentHidden(): boolean {
+  return typeof document !== "undefined" && document.hidden;
+}
+
+export function useHubPaginatedSearch<T>(
+  createIter: (signal: AbortSignal) => AsyncGenerator<unknown>,
+  mapItem: (raw: unknown) => T | null,
+  options?: { enabled?: boolean },
+): HfPaginatedState<T> & { fetchMore: () => boolean; retry: () => void } {
+  const enabled = options?.enabled ?? true;
+  const [state, setState] = useState<HfPaginatedState<T>>(
+    INITIAL as HfPaginatedState<T>,
+  );
+  const [retryNonce, setRetryNonce] = useState(0);
+  const stateRef = useRef(state);
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  const iterRef = useRef<AsyncGenerator<unknown> | null>(null);
+  const versionRef = useRef(0);
+  // Aborts the live iterator's in-flight fetches; replaced when a new query
+  // supersedes the feed so the abandoned listing stops fetching/priming.
+  const abortRef = useRef<AbortController | null>(null);
+
+  // Identity of the last-fetched query. A fetch (re)starts only when one of these
+  // changes, never just on `enabled` toggling — keeps tab switches instant.
+  const loadedFactoryRef = useRef<typeof createIter | null>(null);
+  const loadedMapItemRef = useRef<typeof mapItem | null>(null);
+  const loadedNonceRef = useRef(-1);
+  const loadedAtRef = useRef(0);
+
+  // Synchronous in-flight guard, set before any setState so back-to-back
+  // fetchMore() calls can't both pass the gate while React batches the commit.
+  const busyRef = useRef(false);
+  const busyKindRef = useRef<BusyKind | null>(null);
+  const busyTokenRef = useRef(0);
+  // Timestamp of the last accepted request; with the trailing-edge timer below,
+  // enforces at most one accepted request per MIN_FETCH_INTERVAL_MS.
+  const lastFireAtRef = useRef(0);
+  // Pending trailing-edge fire (idempotent) so a time-gated request isn't lost
+  // when no later DOM event would re-trigger us.
+  const trailingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // One follow-up request queued behind an in-flight "load more" pull; scroll
+  // observers fire repeatedly at the bottom but only one should wait.
+  const queuedAfterBusyRef = useRef(false);
+  const queuedWhileHiddenRef = useRef(false);
+
+  const cancelTrailing = useCallback(() => {
+    if (trailingTimerRef.current !== null) {
+      clearTimeout(trailingTimerRef.current);
+      trailingTimerRef.current = null;
+    }
+  }, []);
+
+  const clearDeferredFetch = useCallback(() => {
+    cancelTrailing();
+    queuedAfterBusyRef.current = false;
+    queuedWhileHiddenRef.current = false;
+  }, [cancelTrailing]);
+
+  useEffect(
+    () => () => {
+      abortRef.current?.abort();
+      clearDeferredFetch();
+    },
+    [clearDeferredFetch],
+  );
+
+  useEffect(() => {
+    if (!enabled) {
+      clearDeferredFetch();
+      if (busyRef.current) {
+        versionRef.current += 1;
+        busyTokenRef.current += 1;
+        abortRef.current?.abort();
+        abortRef.current = null;
+        iterRef.current = null;
+        loadedAtRef.current = 0;
+        busyRef.current = false;
+        busyKindRef.current = null;
+      }
+      setState((prev) =>
+        prev.isLoading || prev.isLoadingMore || prev.error
+          ? {
+              ...prev,
+              isLoading: false,
+              isLoadingMore: false,
+              error: null,
+            }
+          : prev,
+      );
+      return;
+    }
+
+    // Same query, still fresh: reuse what we have. Stale results refetch.
+    const sameQuery =
+      loadedFactoryRef.current === createIter &&
+      loadedMapItemRef.current === mapItem &&
+      loadedNonceRef.current === retryNonce;
+    const fresh = Date.now() - loadedAtRef.current < STALE_AFTER_MS;
+    if (sameQuery && fresh && iterRef.current !== null) {
+      return;
+    }
+    loadedFactoryRef.current = createIter;
+    loadedMapItemRef.current = mapItem;
+    loadedNonceRef.current = retryNonce;
+
+    const v = ++versionRef.current;
+    iterRef.current = null;
+    const busyToken = ++busyTokenRef.current;
+    busyRef.current = true;
+    busyKindRef.current = "initial";
+    clearDeferredFetch();
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    lastFireAtRef.current = Date.now();
+    setState({
+      ...(INITIAL as HfPaginatedState<T>),
+      isLoading: true,
+    });
+
+    const iter = createIter(controller.signal);
+    iterRef.current = iter;
+
+    pullBatch(iter, mapItem, BATCH)
+      .then(({ items, done, scanned }) => {
+        if (versionRef.current !== v) return;
+        loadedAtRef.current = Date.now();
+        setState({
+          results: items,
+          scannedCount: scanned,
+          isLoading: false,
+          isLoadingMore: false,
+          hasMore: !done,
+          error: null,
+        });
+      })
+      .catch((err) => {
+        if (versionRef.current !== v || isAbortError(err)) return;
+        setState({
+          results: [],
+          scannedCount: 0,
+          isLoading: false,
+          isLoadingMore: false,
+          hasMore: false,
+          error: err instanceof Error ? err.message : "Search failed",
+        });
+      })
+      .finally(() => {
+        if (busyTokenRef.current === busyToken) {
+          busyRef.current = false;
+          busyKindRef.current = null;
+        }
+      });
+
+    return () => {
+      clearDeferredFetch();
+    };
+  }, [createIter, mapItem, enabled, retryNonce, clearDeferredFetch]);
+
+  const retry = useCallback(() => {
+    setRetryNonce((n) => n + 1);
+  }, []);
+
+  const fetchMore = useCallback(function fetchMoreInner(): boolean {
+    if (!enabled) {
+      queuedAfterBusyRef.current = false;
+      queuedWhileHiddenRef.current = false;
+      return false;
+    }
+    // Synchronous in-flight gate before any setState, so concurrent fires from
+    // sibling observers all see the same truth and only one proceeds.
+    if (busyRef.current) {
+      if (busyKindRef.current === "more" && stateRef.current.isLoadingMore) {
+        if (queuedAfterBusyRef.current) return false;
+        queuedAfterBusyRef.current = true;
+        return true;
+      }
+      return false;
+    }
+
+    const iter = iterRef.current;
+    const { hasMore } = stateRef.current;
+    if (!iter || !hasMore) {
+      queuedAfterBusyRef.current = false;
+      queuedWhileHiddenRef.current = false;
+      return false;
+    }
+
+    if (isDocumentHidden()) {
+      queuedAfterBusyRef.current = false;
+      if (queuedWhileHiddenRef.current) return false;
+      queuedWhileHiddenRef.current = true;
+      return true;
+    }
+
+    const now = Date.now();
+    const elapsed = now - lastFireAtRef.current;
+
+    if (elapsed < MIN_FETCH_INTERVAL_MS) {
+      // Trailing-edge schedule: calls during the window collapse to one timer.
+      if (trailingTimerRef.current === null) {
+        trailingTimerRef.current = setTimeout(
+          () => {
+            trailingTimerRef.current = null;
+            fetchMoreInner();
+          },
+          MIN_FETCH_INTERVAL_MS - elapsed,
+        );
+        return true;
+      }
+      return false;
+    }
+
+    cancelTrailing();
+    queuedAfterBusyRef.current = false;
+    queuedWhileHiddenRef.current = false;
+    const busyToken = ++busyTokenRef.current;
+    busyRef.current = true;
+    busyKindRef.current = "more";
+    lastFireAtRef.current = now;
+
+    const v = versionRef.current;
+    let shouldScheduleFollowUp = false;
+    setState((prev) => ({ ...prev, isLoadingMore: true }));
+
+    pullBatch(iter, mapItem, BATCH)
+      .then(({ items, done, scanned }) => {
+        if (versionRef.current !== v) return;
+        shouldScheduleFollowUp = !done && queuedAfterBusyRef.current;
+        loadedAtRef.current = Date.now();
+        setState((prev) => ({
+          ...prev,
+          results: [...prev.results, ...items],
+          scannedCount: prev.scannedCount + scanned,
+          isLoadingMore: false,
+          hasMore: !done,
+          // Clear any error left by a prior failed page.
+          error: null,
+        }));
+      })
+      .catch((err) => {
+        if (versionRef.current !== v || isAbortError(err)) return;
+        shouldScheduleFollowUp = false;
+        setState((prev) => ({
+          ...prev,
+          isLoadingMore: false,
+          // Keep results and hasMore=true: the iterator is still valid, so the next
+          // fetchMore() resumes the failed page without discarding the list (retry() restarts from page 1).
+          error: err instanceof Error ? err.message : "Failed to load more",
+        }));
+      })
+      .finally(() => {
+        if (busyTokenRef.current === busyToken) {
+          busyRef.current = false;
+          busyKindRef.current = null;
+          if (
+            shouldScheduleFollowUp &&
+            trailingTimerRef.current === null
+          ) {
+            queuedAfterBusyRef.current = false;
+            const elapsed = Date.now() - lastFireAtRef.current;
+            trailingTimerRef.current = setTimeout(
+              () => {
+                trailingTimerRef.current = null;
+                fetchMoreInner();
+              },
+              Math.max(0, MIN_FETCH_INTERVAL_MS - elapsed),
+            );
+          }
+        }
+      });
+    return true;
+  }, [enabled, mapItem, cancelTrailing]);
+
+  useEffect(() => {
+    if (!enabled || typeof document === "undefined") return;
+    const handleVisibilityChange = () => {
+      if (document.hidden || !queuedWhileHiddenRef.current) return;
+      queuedWhileHiddenRef.current = false;
+      fetchMore();
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [enabled, fetchMore]);
+
+  return { ...state, fetchMore, retry };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-is-hub-desktop.ts b/studio/frontend/src/features/hub/hooks/use-is-hub-desktop.ts
new file mode 100644
index 0000000000..cfbf7c1e4e
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-is-hub-desktop.ts
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useSyncExternalStore } from "react";
+
+const HUB_DESKTOP_QUERY = "(min-width: 1024px)";
+
+function getSnapshot(): boolean {
+  if (typeof window === "undefined") return true;
+  return window.matchMedia(HUB_DESKTOP_QUERY).matches;
+}
+
+function subscribe(callback: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  const mql = window.matchMedia(HUB_DESKTOP_QUERY);
+  mql.addEventListener("change", callback);
+  return () => mql.removeEventListener("change", callback);
+}
+
+export function useIsHubDesktop(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, () => true);
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-latest-ref.ts b/studio/frontend/src/features/hub/hooks/use-latest-ref.ts
new file mode 100644
index 0000000000..d760dfb299
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-latest-ref.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useRef, type MutableRefObject } from "react";
+
+export function useLatestRef<T>(value: T): MutableRefObject<T> {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-models-selection.ts b/studio/frontend/src/features/hub/hooks/use-models-selection.ts
new file mode 100644
index 0000000000..ad86e454e0
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-models-selection.ts
@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  type InventoryResourceFormatHint,
+  findCompleteHfCacheLocalRow,
+  resolveInventoryResource,
+} from "@/features/hub/inventory";
+import type { HfModelResult } from "@/features/hub/hooks/use-hub-model-search";
+import {
+  useCallback,
+  useDeferredValue,
+  useMemo,
+  useState,
+} from "react";
+import {
+  resolveDiscoverSelection,
+  resolveDownloadedSelection,
+} from "../lib/selection-resolution";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+  SelectedModelView,
+} from "../types";
+import { useSelectedModelMetadata } from "./use-selected-model-metadata";
+import { useSelectedModelView } from "./use-selected-model-view";
+
+export interface ModelsSelection {
+  selectedId: string | null;
+  setSelected: (id: string) => void;
+  selectedModel: SelectedModelView | null;
+  metadataUnavailable: boolean;
+  selectionHiddenByFilters: boolean;
+}
+
+function preferredLocalRow(
+  rows: readonly LocalInventoryRow[],
+): LocalInventoryRow | null {
+  return (
+    rows.find((row) => !row.partial && row.source !== "hf_cache") ??
+    rows.find((row) => !row.partial) ??
+    rows[0] ??
+    null
+  );
+}
+
+export function useModelsSelection({
+  isDiscoverTab,
+  isDatasetMode,
+  discoverRows,
+  cachedRows,
+  localRows,
+  filteredDiscoverRows,
+  filteredCachedRows,
+  filteredLocalRows,
+  results,
+  accessToken,
+  online,
+}: {
+  isDiscoverTab: boolean;
+  isDatasetMode: boolean;
+  discoverRows: DiscoverRow[];
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+  filteredDiscoverRows: DiscoverRow[];
+  filteredCachedRows: CachedInventoryRow[];
+  filteredLocalRows: LocalInventoryRow[];
+  results: HfModelResult[];
+  accessToken: string | undefined;
+  online: boolean;
+}): ModelsSelection {
+  // Per-tab selection so switching keeps each list's highlighted row.
+  const [discoverSelectedId, setDiscoverSelectedId] = useState<string | null>(
+    null,
+  );
+  const [downloadedSelectedId, setDownloadedSelectedId] = useState<
+    string | null
+  >(null);
+  const [discoverSelectedSnapshot, setDiscoverSelectedSnapshot] =
+    useState<DiscoverRow | null>(null);
+
+  const [prevDatasetMode, setPrevDatasetMode] = useState(isDatasetMode);
+  if (prevDatasetMode !== isDatasetMode) {
+    setPrevDatasetMode(isDatasetMode);
+    setDiscoverSelectedId(null);
+    setDiscoverSelectedSnapshot(null);
+  }
+
+  const discoverRowById = useMemo(
+    () => new Map(discoverRows.map((row) => [row.id, row])),
+    [discoverRows],
+  );
+  const cachedRowById = useMemo(
+    () => new Map(cachedRows.map((row) => [row.id, row])),
+    [cachedRows],
+  );
+  const localRowById = useMemo(
+    () => new Map(localRows.map((row) => [row.id, row])),
+    [localRows],
+  );
+  const localRowsByRepo = useMemo(() => {
+    const map = new Map<string, LocalInventoryRow[]>();
+    for (const row of localRows) {
+      if (!row.repoId) {
+        continue;
+      }
+      const key = row.repoId.toLowerCase();
+      const rows = map.get(key);
+      if (rows) {
+        rows.push(row);
+      } else {
+        map.set(key, [row]);
+      }
+    }
+    return map;
+  }, [localRows]);
+  const resultByRepo = useMemo(
+    () => new Map(results.map((row) => [row.id.toLowerCase(), row])),
+    [results],
+  );
+
+  const discoverResolution = useMemo(
+    () =>
+      resolveDiscoverSelection({
+        selectedId: discoverSelectedId,
+        discoverRows,
+        filteredDiscoverRows,
+        selectedSnapshotId: discoverSelectedSnapshot?.id ?? null,
+      }),
+    [
+      discoverRows,
+      discoverSelectedId,
+      discoverSelectedSnapshot,
+      filteredDiscoverRows,
+    ],
+  );
+  const downloadedResolution = useMemo(
+    () =>
+      resolveDownloadedSelection({
+        selectedId: downloadedSelectedId,
+        cachedRows,
+        localRows,
+        filteredCachedRows,
+        filteredLocalRows,
+      }),
+    [
+      cachedRows,
+      downloadedSelectedId,
+      filteredCachedRows,
+      filteredLocalRows,
+      localRows,
+    ],
+  );
+  const selectedId = isDiscoverTab
+    ? discoverResolution.selectedId
+    : downloadedResolution.selectedId;
+  const selectionHiddenByFilters = isDiscoverTab
+    ? discoverResolution.hiddenByFilters
+    : downloadedResolution.hiddenByFilters;
+  const detailSelectedId = useDeferredValue(selectedId);
+  const setSelected = useCallback(
+    (id: string) => {
+      if (isDiscoverTab) {
+        setDiscoverSelectedId(id);
+        setDiscoverSelectedSnapshot(discoverRowById.get(id) ?? null);
+      } else {
+        setDownloadedSelectedId(id);
+      }
+    },
+    [discoverRowById, isDiscoverTab],
+  );
+
+  const selectedDiscoverRow = useMemo(
+    () =>
+      isDiscoverTab && detailSelectedId
+        ? (discoverRowById.get(detailSelectedId) ??
+          (discoverSelectedSnapshot?.id === detailSelectedId
+            ? discoverSelectedSnapshot
+            : null))
+        : null,
+    [
+      detailSelectedId,
+      discoverRowById,
+      discoverSelectedSnapshot,
+      isDiscoverTab,
+    ],
+  );
+
+  const selectedDiscoverResource = useMemo(() => {
+    if (!selectedDiscoverRow) return null;
+    const formatHint: InventoryResourceFormatHint = isDatasetMode
+      ? null
+      : selectedDiscoverRow.result.isGguf
+        ? "gguf"
+        : "non-gguf";
+    return resolveInventoryResource({
+      repoId: selectedDiscoverRow.result.id,
+      cachedRows,
+      localRows,
+      formatHint,
+    });
+  }, [cachedRows, isDatasetMode, localRows, selectedDiscoverRow]);
+
+  const selectedCachedRow = useMemo(() => {
+    if (selectedDiscoverResource) return selectedDiscoverResource.cachedRow;
+    if (!detailSelectedId) return null;
+    const cached = cachedRowById.get(detailSelectedId) ?? null;
+    if (!cached?.partial) return cached;
+    const completeLocal = findCompleteHfCacheLocalRow(cached, localRows);
+    return completeLocal ? null : cached;
+  }, [cachedRowById, detailSelectedId, localRows, selectedDiscoverResource]);
+
+  const selectedLocalRow = useMemo(() => {
+    if (selectedDiscoverResource) return selectedDiscoverResource.localRow;
+    if (!detailSelectedId) return null;
+    const direct = localRowById.get(detailSelectedId);
+    if (direct) return direct;
+    const cached = cachedRowById.get(detailSelectedId);
+    if (cached?.partial) {
+      return findCompleteHfCacheLocalRow(cached, localRows);
+    }
+    const repoKey = isDiscoverTab
+      ? selectedDiscoverRow?.result.id.toLowerCase()
+      : detailSelectedId.toLowerCase();
+    return repoKey ? preferredLocalRow(localRowsByRepo.get(repoKey) ?? []) : null;
+  }, [
+    detailSelectedId,
+    cachedRowById,
+    isDiscoverTab,
+    localRowById,
+    localRows,
+    localRowsByRepo,
+    selectedDiscoverResource,
+    selectedDiscoverRow,
+  ]);
+
+  const selectedHubRepoId =
+    selectedDiscoverRow?.result.id ??
+    selectedCachedRow?.repoId ??
+    (selectedLocalRow?.source === "hf_cache"
+      ? selectedLocalRow.repoId
+      : null) ??
+    null;
+  const selectedMetadataRepoId =
+    selectedHubRepoId ?? selectedLocalRow?.baseModelHubId ?? null;
+
+  const selectedResultFromFeed = useMemo(
+    () =>
+      selectedMetadataRepoId
+        ? (resultByRepo.get(selectedMetadataRepoId.toLowerCase()) ?? null)
+        : null,
+    [resultByRepo, selectedMetadataRepoId],
+  );
+
+  const selectedRepoMetadata = useSelectedModelMetadata(selectedMetadataRepoId, {
+    accessToken,
+    enabled: !isDatasetMode && !selectedResultFromFeed,
+    online,
+  });
+  const selectedHfResult = selectedResultFromFeed ?? selectedRepoMetadata.result;
+  const metadataUnavailable =
+    !isDatasetMode &&
+    !selectedResultFromFeed &&
+    !!selectedHubRepoId &&
+    selectedRepoMetadata.error;
+
+  const selectedModel = useSelectedModelView({
+    selectedDiscoverRow,
+    selectedCachedRow,
+    selectedLocalRow,
+    selectedHfResult,
+    isDatasetMode,
+  });
+
+  return {
+    selectedId,
+    setSelected,
+    selectedModel,
+    metadataUnavailable,
+    selectionHiddenByFilters,
+  };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-online-status.ts b/studio/frontend/src/features/hub/hooks/use-online-status.ts
new file mode 100644
index 0000000000..cf73a74fc8
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-online-status.ts
@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  getBrowserOfflineRetryDelayMs,
+  isHuggingFaceOffline,
+  subscribeNetworkStatus,
+} from "@/features/hub/lib/network";
+import { useSyncExternalStore } from "react";
+
+function getOnlineSnapshot(): boolean {
+  return !isHuggingFaceOffline();
+}
+
+function getServerOnlineSnapshot(): boolean {
+  return true;
+}
+
+function subscribeOnlineStatus(onStoreChange: () => void): () => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const clearRetryTimer = () => {
+    if (timer === null) {
+      return;
+    }
+    clearTimeout(timer);
+    timer = null;
+  };
+  const scheduleRetry = () => {
+    clearRetryTimer();
+    const retryDelay = getBrowserOfflineRetryDelayMs();
+    if (retryDelay > 0) {
+      timer = setTimeout(handleChange, retryDelay + 50);
+    }
+  };
+  const handleChange = () => {
+    onStoreChange();
+    scheduleRetry();
+  };
+  const unsubscribe = subscribeNetworkStatus(handleChange);
+  scheduleRetry();
+  return () => {
+    clearRetryTimer();
+    unsubscribe();
+  };
+}
+
+export function useOnlineStatus(): boolean {
+  return useSyncExternalStore(
+    subscribeOnlineStatus,
+    getOnlineSnapshot,
+    getServerOnlineSnapshot,
+  );
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-selected-model-metadata.ts b/studio/frontend/src/features/hub/hooks/use-selected-model-metadata.ts
new file mode 100644
index 0000000000..2072f37d55
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-selected-model-metadata.ts
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { HfModelResult } from "@/features/hub/hooks/use-hub-model-search";
+import { cachedModelInfo } from "../lib/hf-cache";
+import { useEffect, useState } from "react";
+import { toHfModelResult } from "../lib/view-models";
+
+type SelectedModelMetadataResult = ReturnType<typeof toHfModelResult>;
+
+export function useSelectedModelMetadata(
+  repoId: string | null,
+  {
+    accessToken,
+    enabled,
+    online,
+  }: {
+    accessToken: string | undefined;
+    enabled: boolean;
+    online: boolean;
+  },
+): { result: SelectedModelMetadataResult; error: boolean } {
+  const [state, setState] = useState<{
+    repoId: string;
+    result: HfModelResult | null;
+    error: boolean;
+  }>(() => ({ repoId: "", result: null, error: false }));
+
+  useEffect(() => {
+    if (!(repoId && enabled && online)) {
+      return;
+    }
+
+    // No AbortController: cachedModelInfo shares one in-flight request per repo
+    // across callers (hf-cache.ts), so aborting would cancel it for everyone.
+    // The `cancelled` flag plus the state.repoId guard prevent stale writes.
+    let cancelled = false;
+
+    cachedModelInfo({
+      name: repoId,
+      ...(accessToken ? { accessToken } : {}),
+    })
+      .then((result) => {
+        if (cancelled) {
+          return;
+        }
+        setState({
+          repoId,
+          result: toHfModelResult(result),
+          error: false,
+        });
+      })
+      .catch(() => {
+        if (cancelled) {
+          return;
+        }
+        setState({
+          repoId,
+          result: null,
+          error: true,
+        });
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [repoId, accessToken, enabled, online]);
+
+  if (state.repoId !== repoId) {
+    return { result: null, error: false };
+  }
+
+  return { result: state.result, error: state.error };
+}
diff --git a/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts b/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
new file mode 100644
index 0000000000..4616aba4bd
--- /dev/null
+++ b/studio/frontend/src/features/hub/hooks/use-selected-model-view.ts
@@ -0,0 +1,391 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useMemo } from "react";
+import { detectCapabilities, detectLicense } from "../lib/model-capabilities";
+import { buildSummary, localSourceLabel, toHfModelResult } from "../lib/view-models";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+  SelectedResourceRef,
+  SelectedModelView,
+} from "../types";
+
+type HfResult = ReturnType<typeof toHfModelResult>;
+
+function detectViewCapabilities(
+  tags: string[] | undefined,
+  pipelineTag: string | undefined,
+  ...identifiers: Array<string | null | undefined>
+) {
+  const modelId = identifiers.filter(Boolean).join(" ");
+  return detectCapabilities(tags, pipelineTag, modelId);
+}
+
+function cachedResource(row: CachedInventoryRow): SelectedResourceRef {
+  return {
+    repoId: row.repoId,
+    localPath: row.cachePath ?? null,
+    source: "hub_cache",
+    cacheState: row.partial ? "partial" : "cached",
+    runId: row.loadId,
+    trainId: row.loadId,
+  };
+}
+
+function localResource(
+  row: LocalInventoryRow,
+  repoId: string | null = row.repoId,
+): SelectedResourceRef {
+  const cacheState = row.partial
+    ? "partial"
+    : row.source === "hf_cache"
+      ? "cached"
+      : "local";
+  const id =
+    row.source === "hf_cache" && repoId && !row.partial ? repoId : row.loadId;
+  return {
+    repoId,
+    localPath: row.path,
+    source: row.source,
+    cacheState,
+    runId: id,
+    trainId: id,
+  };
+}
+
+function remoteResource(row: DiscoverRow): SelectedResourceRef {
+  return {
+    repoId: row.result.id,
+    localPath: null,
+    source: "huggingface",
+    cacheState: row.isPartialOnDevice ? "partial" : "remote",
+    runId: row.result.id,
+    trainId: row.result.id,
+  };
+}
+
+function localFormatLabel(row: LocalInventoryRow): string {
+  if (row.modelFormat === "gguf") return "local GGUF";
+  if (row.modelFormat === "adapter") return "local adapter";
+  if (row.modelFormat === "safetensors") return "local safetensors model";
+  if (row.modelFormat === "checkpoint") return "local checkpoint";
+  return "local model";
+}
+
+export function useSelectedModelView({
+  selectedDiscoverRow,
+  selectedCachedRow,
+  selectedLocalRow,
+  selectedHfResult,
+  isDatasetMode,
+}: {
+  selectedDiscoverRow: DiscoverRow | null;
+  selectedCachedRow: CachedInventoryRow | null;
+  selectedLocalRow: LocalInventoryRow | null;
+  selectedHfResult: HfResult;
+  isDatasetMode: boolean;
+}): SelectedModelView | null {
+  return useMemo<SelectedModelView | null>(() => {
+    if (selectedDiscoverRow) {
+      if (
+        !selectedCachedRow &&
+        selectedLocalRow &&
+        selectedLocalRow.source !== "hf_cache"
+      ) {
+        const resource = localResource(
+          selectedLocalRow,
+          selectedDiscoverRow.result.id,
+        );
+        return {
+          id: resource.runId,
+          kind: "local",
+          resource,
+          displayId: selectedDiscoverRow.id,
+          hubRepoId: selectedDiscoverRow.result.id,
+          owner: selectedDiscoverRow.owner,
+          title: selectedDiscoverRow.repo,
+          summary: selectedHfResult
+            ? buildSummary(selectedHfResult)
+            : selectedDiscoverRow.summary,
+          sourceLabel: selectedLocalRow.sourceLabel,
+          path: selectedLocalRow.path,
+          localSource: selectedLocalRow.source,
+          isLocal: true,
+          isGguf: selectedLocalRow.isGguf || selectedDiscoverRow.result.isGguf,
+          requiresVariant: selectedLocalRow.capabilities.requiresVariant,
+          modelFormat:
+            selectedLocalRow.modelFormat !== "unknown"
+              ? selectedLocalRow.modelFormat
+              : selectedDiscoverRow.result.isGguf
+                ? "gguf"
+                : null,
+          isDownloaded: !selectedLocalRow.partial,
+          isPartial: selectedLocalRow.partial ?? false,
+          partialTransport: selectedLocalRow.partialTransport ?? null,
+          runtimeCapabilities: selectedLocalRow.capabilities,
+          capabilities: selectedDiscoverRow.capabilities,
+          license: detectLicense(selectedDiscoverRow.result.tags),
+          pipelineTag: selectedDiscoverRow.result.pipelineTag,
+          libraryName: selectedDiscoverRow.result.libraryName,
+          downloads: selectedDiscoverRow.result.downloads,
+          likes: selectedDiscoverRow.result.likes,
+          totalParams: selectedDiscoverRow.result.totalParams,
+          estimatedSizeBytes: selectedDiscoverRow.result.estimatedSizeBytes,
+          updatedAt: selectedDiscoverRow.result.updatedAt,
+          localUpdatedAt: selectedLocalRow.updatedAt,
+          tags: selectedDiscoverRow.result.tags,
+          quantMethod: selectedDiscoverRow.result.quantMethod,
+        };
+      }
+
+      const onDevicePath =
+        selectedCachedRow?.cachePath ?? selectedLocalRow?.path ?? null;
+      const resource = selectedCachedRow
+        ? cachedResource(selectedCachedRow)
+        : selectedLocalRow?.source === "hf_cache"
+          ? localResource(selectedLocalRow, selectedDiscoverRow.result.id)
+        : remoteResource(selectedDiscoverRow);
+      const isResolvedPartial = resource.cacheState === "partial";
+      const isResolvedOnDevice =
+        resource.cacheState === "cached" || resource.cacheState === "local";
+      const resolvedModelFormat =
+        selectedCachedRow?.modelFormat ??
+        (selectedLocalRow?.modelFormat && selectedLocalRow.modelFormat !== "unknown"
+          ? selectedLocalRow.modelFormat
+          : selectedDiscoverRow.result.isGguf
+            ? "gguf"
+            : null);
+      return {
+        id: selectedDiscoverRow.id,
+        kind: "discover",
+        resource,
+        displayId: selectedDiscoverRow.id,
+        hubRepoId: selectedDiscoverRow.result.id,
+        owner: selectedDiscoverRow.owner,
+        title: selectedDiscoverRow.repo,
+        summary: selectedDiscoverRow.summary,
+        sourceLabel: isResolvedOnDevice
+          ? "On device"
+          : isResolvedPartial
+            ? "Partial on device"
+            : "Hugging Face",
+        path: onDevicePath,
+        isLocal: false,
+        isGguf:
+          selectedCachedRow?.isGguf ??
+          selectedLocalRow?.isGguf ??
+          selectedDiscoverRow.result.isGguf,
+        requiresVariant:
+          selectedCachedRow?.capabilities.requiresVariant ??
+          selectedLocalRow?.capabilities.requiresVariant ??
+          selectedDiscoverRow.result.isGguf,
+        modelFormat: resolvedModelFormat,
+        isDownloaded: isResolvedOnDevice,
+        isPartial: isResolvedPartial,
+        partialTransport:
+          selectedCachedRow?.partialTransport ??
+          selectedLocalRow?.partialTransport ??
+          null,
+        runtimeCapabilities:
+          selectedCachedRow?.capabilities ?? selectedLocalRow?.capabilities,
+        capabilities: selectedDiscoverRow.capabilities,
+        license: detectLicense(selectedDiscoverRow.result.tags),
+        pipelineTag: selectedDiscoverRow.result.pipelineTag,
+        libraryName: selectedDiscoverRow.result.libraryName,
+        downloads: selectedDiscoverRow.result.downloads,
+        likes: selectedDiscoverRow.result.likes,
+        totalParams: selectedDiscoverRow.result.totalParams,
+        estimatedSizeBytes: selectedDiscoverRow.result.estimatedSizeBytes,
+        cachedBytes: selectedCachedRow?.bytes,
+        updatedAt: selectedDiscoverRow.result.updatedAt,
+        tags: selectedDiscoverRow.result.tags,
+        quantMethod: selectedDiscoverRow.result.quantMethod,
+      };
+    }
+
+    if (selectedCachedRow) {
+      const resource = cachedResource(selectedCachedRow);
+      const cachedSummary = isDatasetMode
+        ? "Cached dataset, ready to use."
+        : selectedCachedRow.isGguf
+          ? "Cached GGUF repository ready for local inference."
+          : "Cached checkpoint repository ready for local inference.";
+      const mergedTags = selectedHfResult?.tags ?? selectedCachedRow.tags;
+      const mergedPipelineTag =
+        selectedHfResult?.pipelineTag ?? selectedCachedRow.pipelineTag ?? undefined;
+      const mergedLibraryName =
+        selectedHfResult?.libraryName ?? selectedCachedRow.libraryName ?? undefined;
+      const mergedQuantMethod =
+        selectedHfResult?.quantMethod ?? selectedCachedRow.quantMethod ?? undefined;
+      return {
+        id: selectedCachedRow.repoId,
+        kind: "cache",
+        resource,
+        displayId: selectedCachedRow.repoId,
+        hubRepoId: selectedCachedRow.repoId,
+        owner: selectedCachedRow.owner,
+        title: selectedCachedRow.repo,
+        summary: selectedHfResult
+          ? buildSummary(selectedHfResult)
+          : cachedSummary,
+        sourceLabel: "Hub cache",
+        path: selectedCachedRow.cachePath ?? null,
+        isLocal: false,
+        isGguf: selectedCachedRow.isGguf,
+        requiresVariant: selectedCachedRow.capabilities.requiresVariant,
+        modelFormat: selectedCachedRow.modelFormat,
+        isDownloaded: !selectedCachedRow.partial,
+        isPartial: selectedCachedRow.partial ?? false,
+        partialTransport: selectedCachedRow.partialTransport ?? null,
+        runtimeCapabilities: selectedCachedRow.capabilities,
+        capabilities: detectViewCapabilities(
+          mergedTags,
+          mergedPipelineTag,
+          selectedCachedRow.repoId,
+          selectedCachedRow.loadId,
+          selectedCachedRow.repo,
+        ),
+        license: detectLicense(mergedTags),
+        pipelineTag: mergedPipelineTag,
+        libraryName: mergedLibraryName,
+        downloads: selectedHfResult?.downloads,
+        likes: selectedHfResult?.likes,
+        totalParams: selectedHfResult?.totalParams,
+        estimatedSizeBytes: selectedHfResult?.estimatedSizeBytes,
+        cachedBytes: selectedCachedRow.bytes,
+        updatedAt: selectedHfResult?.updatedAt,
+        tags: mergedTags,
+        quantMethod: mergedQuantMethod,
+      };
+    }
+
+    if (selectedLocalRow) {
+      const localHubRepoId =
+        selectedLocalRow.source === "hf_cache" ? selectedLocalRow.repoId : null;
+      const resource = localResource(selectedLocalRow, localHubRepoId);
+      const localDisplayId = selectedLocalRow.repoId ?? selectedLocalRow.loadId;
+      const isPartialHubCache =
+        selectedLocalRow.source === "hf_cache" &&
+        !!selectedLocalRow.partial &&
+        !!selectedLocalRow.repoId;
+      const mergedTags = selectedHfResult?.tags ?? selectedLocalRow.tags;
+      const mergedPipelineTag =
+        selectedHfResult?.pipelineTag ??
+        selectedLocalRow.pipelineTag ??
+        undefined;
+      const mergedLibraryName =
+        selectedHfResult?.libraryName ??
+        selectedLocalRow.libraryName ??
+        undefined;
+      const mergedQuantMethod =
+        selectedHfResult?.quantMethod ??
+        selectedLocalRow.quantMethod ??
+        undefined;
+      const baseModelSummary = selectedLocalRow.baseModel && selectedHfResult
+        ? buildSummary(selectedHfResult)
+        : null;
+      const localHubMetadata = localHubRepoId ? selectedHfResult : null;
+
+      if (isPartialHubCache && selectedLocalRow.repoId) {
+        return {
+          id: selectedLocalRow.repoId,
+          kind: "cache",
+          resource,
+          displayId: selectedLocalRow.repoId,
+          hubRepoId: selectedLocalRow.repoId,
+          owner: selectedLocalRow.owner,
+          title: selectedLocalRow.title,
+          summary: selectedHfResult
+            ? buildSummary(selectedHfResult)
+            : "Partial download. Resume to finish or delete to free space.",
+          sourceLabel: "Hub cache",
+          path: selectedLocalRow.path,
+          isLocal: false,
+          isGguf: selectedLocalRow.isGguf,
+          requiresVariant: selectedLocalRow.capabilities.requiresVariant,
+          modelFormat: selectedLocalRow.modelFormat,
+          isDownloaded: false,
+          isPartial: true,
+          partialTransport: selectedLocalRow.partialTransport ?? null,
+          runtimeCapabilities: selectedLocalRow.capabilities,
+          capabilities: detectViewCapabilities(
+            mergedTags,
+            mergedPipelineTag,
+            selectedLocalRow.repoId,
+            selectedLocalRow.loadId,
+            selectedLocalRow.title,
+            selectedLocalRow.path,
+          ),
+          license: detectLicense(mergedTags),
+          pipelineTag: mergedPipelineTag,
+          libraryName: mergedLibraryName,
+          downloads: selectedHfResult?.downloads,
+          likes: selectedHfResult?.likes,
+          totalParams: selectedHfResult?.totalParams,
+          estimatedSizeBytes: selectedHfResult?.estimatedSizeBytes,
+          updatedAt: selectedHfResult?.updatedAt,
+          localUpdatedAt: selectedLocalRow.updatedAt,
+          tags: mergedTags,
+          quantMethod: mergedQuantMethod,
+        };
+      }
+
+      return {
+        id: selectedLocalRow.loadId,
+        kind: "local",
+        resource,
+        displayId: localDisplayId,
+        hubRepoId: localHubRepoId,
+        owner: selectedLocalRow.owner,
+        title: selectedLocalRow.title,
+        summary: `${localSourceLabel(selectedLocalRow.source)} · ${localFormatLabel(
+          selectedLocalRow,
+        )}`,
+        sourceLabel: selectedLocalRow.sourceLabel,
+        path: selectedLocalRow.path,
+        localSource: selectedLocalRow.source,
+        isLocal: true,
+        isGguf: selectedLocalRow.isGguf,
+        requiresVariant: selectedLocalRow.capabilities.requiresVariant,
+        modelFormat: selectedLocalRow.modelFormat,
+        baseModel: selectedLocalRow.baseModel ?? null,
+        baseModelSource: selectedLocalRow.baseModelSource ?? null,
+        baseModelHubId: selectedLocalRow.baseModelHubId ?? null,
+        baseModelSummary,
+        adapterType: selectedLocalRow.adapterType ?? null,
+        trainingMethod: selectedLocalRow.trainingMethod ?? null,
+        isDownloaded: true,
+        runtimeCapabilities: selectedLocalRow.capabilities,
+        capabilities: detectViewCapabilities(
+          mergedTags,
+          mergedPipelineTag,
+          selectedLocalRow.repoId ?? selectedLocalRow.title,
+          selectedLocalRow.baseModel,
+          selectedLocalRow.loadId,
+          selectedLocalRow.path,
+        ),
+        license: detectLicense(mergedTags),
+        pipelineTag: mergedPipelineTag,
+        libraryName: mergedLibraryName,
+        downloads: localHubMetadata?.downloads,
+        likes: localHubMetadata?.likes,
+        totalParams: localHubMetadata?.totalParams,
+        estimatedSizeBytes: localHubMetadata?.estimatedSizeBytes,
+        updatedAt: localHubMetadata?.updatedAt,
+        localUpdatedAt: selectedLocalRow.updatedAt,
+        tags: mergedTags,
+        quantMethod: mergedQuantMethod,
+      };
+    }
+
+    return null;
+  }, [
+    isDatasetMode,
+    selectedCachedRow,
+    selectedDiscoverRow,
+    selectedHfResult,
+    selectedLocalRow,
+  ]);
+}
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
new file mode 100644
index 0000000000..f606a9941a
--- /dev/null
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -0,0 +1,770 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Hub page: browse + download surface only. Train CTA hidden until Hub->train picker ships.
+import { useHubInventory } from "@/features/hub/inventory";
+import { useDebouncedValue } from "@/hooks/use-debounced-value";
+import { useGpuInfo } from "@/hooks/use-gpu-info";
+import {
+  type HfSortDirection,
+  type HfSortKey,
+} from "@/features/hub/hooks/use-hub-model-search";
+import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
+import { useIsHubDesktop } from "@/features/hub/hooks/use-is-hub-desktop";
+import { useHubInfiniteScroll } from "@/features/hub/hooks/use-hub-infinite-scroll";
+import { modelIdsMatch } from "@/features/hub/lib/model-identity";
+import { cn } from "@/lib/utils";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import { ArrowLeft01Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import {
+  useCallback,
+  useDeferredValue,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { ModelInspector } from "./catalog/model-inspector";
+import {
+  ModelsCatalog,
+  type ModelsCatalogHandlers,
+  type ModelsCatalogPagination,
+  type ModelsCatalogState,
+} from "./catalog/models-catalog";
+import { ModelsHeader } from "./catalog/models-header";
+import { ModelsToolbar } from "./catalog/models-toolbar";
+import { ExternalLinkConfirmDialog } from "./catalog/external-link-confirm-dialog";
+import { OnDeviceFoldersDialog } from "./catalog/on-device-folders-dialog";
+import { useDiscoverSearch } from "./hooks/use-discover-search";
+import { useHubModelVram } from "./hooks/use-hub-model-vram";
+import { useModelsSelection } from "./hooks/use-models-selection";
+import {
+  type ChannelId,
+  type ChannelPreset,
+  findChannel,
+} from "./lib/channels";
+import { inventoryRowMatches, tokenizeQuery } from "./lib/inventory-search";
+import {
+  buildDiscoverRows,
+  matchesCapability,
+  matchesFormat,
+} from "./lib/view-models";
+import type {
+  CachedInventoryRow,
+  CapabilityFilter,
+  DiscoverRow,
+  LocalInventoryRow,
+  ModelFormatFilter,
+  ModelsTab,
+  ResourceTypeFilter,
+  SelectedModelView,
+} from "./types";
+
+const MODELS_TAB_STORAGE_KEY = "unsloth.hub.modelsTab";
+
+const DEFAULT_DISCOVER_CHANNEL: ChannelId = "unsloth-trending";
+
+type ModelLoadOptions = { ggufVariant?: string; expectedBytes?: number };
+
+function discoveryInventorySignature(
+  cachedRows: readonly CachedInventoryRow[],
+  localRows: readonly LocalInventoryRow[],
+): string {
+  const parts: string[] = [];
+  for (const row of cachedRows) {
+    parts.push(
+      `c:${row.repoId.toLowerCase()}:${row.modelFormat}:${row.partial ? "p" : "c"}`,
+    );
+  }
+  for (const row of localRows) {
+    parts.push(
+      `l:${(row.repoId ?? row.id).toLowerCase()}:${row.modelFormat}:${row.partial ? "p" : "c"}`,
+    );
+  }
+  return parts.sort().join("|");
+}
+
+function readModelsTabPreference(): ModelsTab | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    const value = window.localStorage.getItem(MODELS_TAB_STORAGE_KEY);
+    return value === "discover" || value === "downloaded" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeModelsTabPreference(tab: ModelsTab): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  try {
+    window.localStorage.setItem(MODELS_TAB_STORAGE_KEY, tab);
+  } catch {
+    return;
+  }
+}
+
+function useModelsTabState(): {
+  tab: ModelsTab;
+  setTab: (tab: ModelsTab) => void;
+} {
+  const navigate = useNavigate();
+  const search = useSearch({ from: "/hub" });
+  const urlTab: ModelsTab | null = search.tab ?? null;
+  const [fallbackTab, setFallbackTab] = useState<ModelsTab>(
+    () => readModelsTabPreference() ?? "downloaded",
+  );
+  const tab = urlTab ?? fallbackTab;
+
+  useEffect(() => {
+    if (urlTab !== null) return;
+    void navigate({
+      to: "/hub",
+      search: (prev) => ({ ...prev, tab: fallbackTab }),
+      replace: true,
+    });
+  }, [urlTab, fallbackTab, navigate]);
+
+  const setTab = useCallback(
+    (next: ModelsTab) => {
+      setFallbackTab(next);
+      writeModelsTabPreference(next);
+      void navigate({
+        to: "/hub",
+        search: (prev) => ({ ...prev, tab: next }),
+        replace: true,
+      });
+    },
+    [navigate],
+  );
+
+  return { tab, setTab };
+}
+
+function partitionByMatch<T extends CachedInventoryRow | LocalInventoryRow>(
+  rows: T[],
+  tokens: readonly string[],
+): T[] {
+  if (tokens.length === 0) return rows;
+  const matches: T[] = [];
+  const rest: T[] = [];
+  for (const row of rows) {
+    if (inventoryRowMatches(row, tokens)) matches.push(row);
+    else rest.push(row);
+  }
+  return [...matches, ...rest];
+}
+
+function selectedRepoMatchesRuntime(
+  selectedModel: SelectedModelView | null,
+  runtimeId: string | null,
+  ggufVariant: string | null,
+): boolean {
+  if (!selectedModel || !runtimeId) return false;
+  if (!modelIdsMatch(runtimeId, selectedModel.resource.runId)) return false;
+  if (selectedModel.modelFormat === "gguf") {
+    const localPath =
+      selectedModel.resource.localPath ?? selectedModel.path ?? "";
+    return ggufVariant !== null || localPath.toLowerCase().endsWith(".gguf");
+  }
+  return ggufVariant === null;
+}
+
+export function ModelsPage() {
+  const navigate = useNavigate();
+  const gpu = useGpuInfo();
+  const online = useOnlineStatus();
+
+  // "Use in chat" just navigates to /chat; checkpoint/variant handoff lands with the Hub-aware picker.
+  const activeCheckpoint: string | null = null;
+  const activeGgufVariant: string | null = null;
+  // Stubs so the inspector + load-status memo still typecheck; cast keeps the shape from narrowing to `never`.
+  const loadingModel = null as { id: string } | null;
+  const loadProgress = null as {
+    phase?: "downloading" | "starting";
+  } | null;
+
+  const { tab, setTab: setModelsTab } = useModelsTabState();
+  const [query, setQuery] = useState("");
+  const [sortBy, setSortBy] = useState<HfSortKey>(
+    () => findChannel(DEFAULT_DISCOVER_CHANNEL)?.sort ?? "trendingScore",
+  );
+  const [direction, setDirection] = useState<HfSortDirection>("desc");
+  const [resourceType, setResourceType] =
+    useState<ResourceTypeFilter>("models");
+  const [activeChannelId, setActiveChannelId] = useState<ChannelId | null>(
+    DEFAULT_DISCOVER_CHANNEL,
+  );
+  const activeChannel: ChannelPreset | null = useMemo(
+    () => findChannel(activeChannelId),
+    [activeChannelId],
+  );
+  const [discoverFormat, setDiscoverFormat] = useState<ModelFormatFilter>(
+    () => findChannel(DEFAULT_DISCOVER_CHANNEL)?.format ?? "gguf",
+  );
+  const [downloadedFormat, setDownloadedFormat] =
+    useState<ModelFormatFilter>("all");
+  const isDiscoverTab = tab === "discover";
+  const isDatasetMode = resourceType === "datasets";
+  const formatFilter = isDiscoverTab ? discoverFormat : downloadedFormat;
+  const setFormatFilter = useCallback(
+    (next: ModelFormatFilter) => {
+      if (isDiscoverTab) {
+        setDiscoverFormat(next);
+      } else {
+        setDownloadedFormat(next);
+      }
+    },
+    [isDiscoverTab],
+  );
+  const [capabilityFilter, setCapabilityFilter] =
+    useState<CapabilityFilter>("all");
+  const [mobileInspectorOpen, setMobileInspectorOpen] = useState(false);
+  const isHubDesktop = useIsHubDesktop();
+  const [foldersDialogOpen, setFoldersDialogOpen] = useState(false);
+  const [discoverFetchIntent, setDiscoverFetchIntent] = useState(0);
+
+  const handleTabChange = useCallback(
+    (next: ModelsTab) => {
+      setMobileInspectorOpen(false);
+      setModelsTab(next);
+    },
+    [setModelsTab],
+  );
+
+  const handleResourceTypeChange = useCallback(
+    (next: ResourceTypeFilter) => {
+      if (next === resourceType) return;
+      setResourceType(next);
+      setDownloadedFormat("all");
+      setCapabilityFilter("all");
+      if (next === "models") {
+        const preset = findChannel(DEFAULT_DISCOVER_CHANNEL);
+        setActiveChannelId(DEFAULT_DISCOVER_CHANNEL);
+        setDiscoverFormat(preset?.format ?? "gguf");
+        setSortBy(preset?.sort ?? "trendingScore");
+        setDirection("desc");
+      } else {
+        setActiveChannelId(null);
+      }
+    },
+    [resourceType],
+  );
+
+  const handleChannelSelect = useCallback((next: ChannelId | null) => {
+    setActiveChannelId(next);
+    setCapabilityFilter("all");
+    setQuery("");
+    const preset = findChannel(next);
+    if (preset) {
+      setDiscoverFormat(preset.format);
+      setSortBy(preset.sort);
+      setDirection("desc");
+    }
+  }, []);
+
+  const handleSortChange = useCallback((next: HfSortKey) => {
+    setSortBy(next);
+    if (next === "trendingScore") setDirection("desc");
+  }, []);
+
+  const debouncedQuery = useDebouncedValue(query);
+  const deferredDebouncedQuery = useDeferredValue(debouncedQuery);
+  const hfToken = useHfTokenStore((s) => s.token);
+  const debouncedHfToken = useDebouncedValue(hfToken, 500);
+  const effectiveSort: HfSortKey = sortBy;
+  const deferredFormatFilter = useDeferredValue(formatFilter);
+  const deferredCapabilityFilter = useDeferredValue(capabilityFilter);
+
+  const {
+    results,
+    datasetResults,
+    scannedCount,
+    isLoading,
+    isLoadingMore,
+    hasMore,
+    fetchMore,
+    searchError,
+    handleRetrySearch,
+  } = useDiscoverSearch({
+    debouncedQuery,
+    accessToken: debouncedHfToken || undefined,
+    isDiscoverTab,
+    isDatasetMode,
+    sortBy: effectiveSort,
+    direction,
+    activeChannel,
+    online,
+  });
+
+  const {
+    cachedRows: effectiveCachedRows,
+    localRows: effectiveLocalRows,
+    availableSet,
+    partialSet,
+    downloadedReady,
+    inventoryError,
+    inventoryWarning,
+    refreshInventory,
+  } = useHubInventory({ kind: isDatasetMode ? "datasets" : "models" });
+
+  const modelDiscoveryInventorySignature = useMemo(
+    () =>
+      discoveryInventorySignature(effectiveCachedRows, effectiveLocalRows),
+    [effectiveCachedRows, effectiveLocalRows],
+  );
+  const modelDiscoverRows = useMemo<DiscoverRow[]>(
+    () => buildDiscoverRows(results, effectiveCachedRows, effectiveLocalRows),
+    [results, modelDiscoveryInventorySignature],
+  );
+
+  const datasetDiscoverRows = useMemo<DiscoverRow[]>(() => {
+    if (!isDatasetMode) return [];
+    return datasetResults.map((ds) => {
+      const owner = ds.id.includes("/") ? ds.id.split("/")[0] : "Hub";
+      const repo = ds.id.includes("/")
+        ? ds.id.split("/").slice(1).join("/")
+        : ds.id;
+      const summaryParts: string[] = [];
+      if (ds.taskCategories.length > 0)
+        summaryParts.push(ds.taskCategories.slice(0, 2).join(", "));
+      if (ds.totalExamples)
+        summaryParts.push(`${ds.totalExamples.toLocaleString()} rows`);
+      else if (ds.sizeCategory) summaryParts.push(ds.sizeCategory);
+      const lower = ds.id.toLowerCase();
+      return {
+        id: ds.id,
+        owner,
+        repo,
+        result: {
+          id: ds.id,
+          downloads: ds.downloads,
+          likes: ds.likes,
+          isGguf: false,
+          tags: ds.plainTags,
+        },
+        isAvailableOnDevice: availableSet.has(lower),
+        isPartialOnDevice: partialSet.has(lower),
+        summary: summaryParts.join(" · ") || "Dataset",
+        capabilities: [],
+      };
+    });
+  }, [isDatasetMode, datasetResults, availableSet, partialSet]);
+
+  const discoverRows = isDatasetMode ? datasetDiscoverRows : modelDiscoverRows;
+
+  const filteredDiscoverRows = useMemo(
+    () =>
+      discoverRows.filter((row) => {
+        if (isDatasetMode) return true;
+        return (
+          matchesFormat(row.result.isGguf, deferredFormatFilter) &&
+          matchesCapability(row.capabilities, deferredCapabilityFilter)
+        );
+      }),
+    [
+      discoverRows,
+      isDatasetMode,
+      deferredFormatFilter,
+      deferredCapabilityFilter,
+    ],
+  );
+
+  const inventoryTokens = useMemo(
+    () => (isDiscoverTab ? [] : tokenizeQuery(deferredDebouncedQuery)),
+    [isDiscoverTab, deferredDebouncedQuery],
+  );
+  // Format filter hard-filters; the text query drives dim-not-filter on the On Device
+  // tab so selection survives typing, with matching rows partitioned to the top.
+  const filteredCachedRows = useMemo(
+    () =>
+      partitionByMatch(
+        effectiveCachedRows.filter(
+          (row) =>
+            isDatasetMode ||
+            matchesFormat(row.modelFormat, deferredFormatFilter),
+        ),
+        inventoryTokens,
+      ),
+    [effectiveCachedRows, isDatasetMode, deferredFormatFilter, inventoryTokens],
+  );
+
+  const filteredLocalRows = useMemo(
+    () =>
+      partitionByMatch(
+        effectiveLocalRows.filter(
+          (row) =>
+            isDatasetMode ||
+            matchesFormat(row.modelFormat, deferredFormatFilter),
+        ),
+        inventoryTokens,
+      ),
+    [effectiveLocalRows, isDatasetMode, deferredFormatFilter, inventoryTokens],
+  );
+
+  const filterResetSignature = useMemo(
+    () =>
+      JSON.stringify([
+        deferredDebouncedQuery,
+        resourceType,
+        deferredFormatFilter,
+        deferredCapabilityFilter,
+        effectiveSort,
+        direction,
+        activeChannelId,
+      ]),
+    [
+      deferredDebouncedQuery,
+      resourceType,
+      deferredFormatFilter,
+      deferredCapabilityFilter,
+      effectiveSort,
+      direction,
+      activeChannelId,
+    ],
+  );
+  const handleClearFilters = useCallback(() => {
+    if (isDiscoverTab) {
+      setActiveChannelId(null);
+      setDiscoverFormat("all");
+    } else {
+      setDownloadedFormat("all");
+    }
+    setCapabilityFilter("all");
+  }, [isDiscoverTab]);
+  const handleDiscoverFetchIntent = useCallback(() => {
+    setDiscoverFetchIntent((value) => value + 1);
+  }, []);
+
+  const {
+    scrollRef,
+    sentinelRef,
+    manualFetchAvailable: discoverManualFetchAvailable,
+    fetchMoreManually: fetchMoreDiscoverManually,
+  } = useHubInfiniteScroll(
+    fetchMore,
+    // Re-evaluate off the raw fetched count, not the filtered one: page-level filters
+    // can reject every incoming row, stalling filteredDiscoverRows while results grow.
+    scannedCount,
+    {
+      enabled: online && isDiscoverTab && hasMore,
+      isFetching: isLoading || isLoadingMore,
+      resultCount: filteredDiscoverRows.length,
+      maxAutoFillFetches: 5,
+      manualFetchAfterAutoFill: true,
+      onFetchIntent: handleDiscoverFetchIntent,
+      resetKey: filterResetSignature,
+    },
+  );
+
+  const {
+    selectedId,
+    setSelected,
+    selectedModel,
+    metadataUnavailable,
+    selectionHiddenByFilters,
+  } = useModelsSelection({
+    isDiscoverTab,
+    isDatasetMode,
+    discoverRows,
+    cachedRows: effectiveCachedRows,
+    localRows: effectiveLocalRows,
+    filteredDiscoverRows,
+    filteredCachedRows,
+    filteredLocalRows,
+    results,
+    accessToken: debouncedHfToken || undefined,
+    online,
+  });
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      setSelected(id);
+      // Only flip the mobile drawer in single-pane layout; on lg+ both panes are
+      // visible and setting state here just churns the catalog's virtualizer.
+      if (
+        typeof window !== "undefined" &&
+        window.matchMedia("(max-width: 1023.98px)").matches
+      ) {
+        setMobileInspectorOpen(true);
+      }
+    },
+    [setSelected],
+  );
+  const handleQueryChange = useCallback(
+    (next: string) => {
+      if (activeChannelId) setActiveChannelId(null);
+      setQuery(next);
+    },
+    [activeChannelId],
+  );
+  const handleManageLocalFolders = useCallback(
+    () => setFoldersDialogOpen(true),
+    [],
+  );
+  const handleSwitchDevice = useCallback(
+    () => handleTabChange("downloaded"),
+    [handleTabChange],
+  );
+
+  const isActive = useMemo(
+    () =>
+      selectedRepoMatchesRuntime(
+        selectedModel,
+        activeCheckpoint,
+        activeGgufVariant,
+      ),
+    [activeCheckpoint, activeGgufVariant, selectedModel],
+  );
+
+  const isLoadingThisModel = useMemo(() => {
+    if (!loadingModel) return false;
+    return selectedRepoMatchesRuntime(selectedModel, loadingModel.id, null);
+  }, [loadingModel, selectedModel]);
+
+  const { vramInfo, minMemory } = useHubModelVram(selectedModel, gpu);
+
+  const gpuLabel = gpu.available
+    ? `${Math.floor(gpu.memoryTotalGb)} GB`
+    : "Unavailable";
+  const ramLabel =
+    gpu.systemRamAvailableGb > 0
+      ? `${Math.floor(gpu.systemRamAvailableGb)} GB`
+      : "Unavailable";
+
+  // Load / use-in-chat / train handlers are stubs; they wire in once the
+  // Hub-aware chat and train pickers ship.
+  const handleLoad = useCallback(
+    (_opts: ModelLoadOptions) => undefined,
+    [],
+  );
+  const handleLoadLocal = useCallback(
+    (_opts: ModelLoadOptions = {}) => undefined,
+    [],
+  );
+  const handleUseInChat = useCallback(() => {
+    void navigate({ to: "/chat" });
+  }, [navigate]);
+  const handleTrain = useCallback(() => {
+    // Train CTA hidden until Hub->train picker ships.
+  }, []);
+
+  const inspectorRuntime = useMemo(
+    () => ({
+      isActive,
+      activeGgufVariant,
+      isLoadingThisModel,
+      loadingPhase: loadProgress?.phase,
+      minMemory,
+      vramInfo,
+      gpuGb: gpu.available ? gpu.memoryTotalGb : undefined,
+      systemRamGb:
+        gpu.systemRamAvailableGb > 0 ? gpu.systemRamAvailableGb : undefined,
+    }),
+    [
+      isActive,
+      activeGgufVariant,
+      isLoadingThisModel,
+      loadProgress?.phase,
+      minMemory,
+      vramInfo,
+      gpu.available,
+      gpu.memoryTotalGb,
+      gpu.systemRamAvailableGb,
+    ],
+  );
+
+  const inspectorActions = useMemo(
+    () => ({
+      onLoad: handleLoad,
+      onLoadLocal: handleLoadLocal,
+      onUseInChat: handleUseInChat,
+      onTrain: handleTrain,
+      onInventoryChange: refreshInventory,
+    }),
+    [
+      handleLoad,
+      handleLoadLocal,
+      handleUseInChat,
+      handleTrain,
+      refreshInventory,
+    ],
+  );
+
+  const catalogState = useMemo<ModelsCatalogState>(
+    () => ({
+      tab,
+      discoverRows: filteredDiscoverRows,
+      cachedRows: filteredCachedRows,
+      localRows: filteredLocalRows,
+      selectedId,
+      isLoading,
+      downloadedReady,
+      inventoryError,
+      inventoryWarning,
+      query,
+      activeCheckpoint,
+      activeGgufVariant,
+      searchError,
+      online,
+      isDataset: isDatasetMode,
+      inventoryTokens,
+      scannedCount,
+      loadingIntentCount: discoverFetchIntent,
+      hasMore,
+      manualFetchAvailable: discoverManualFetchAvailable,
+      hasActiveFilters:
+        deferredFormatFilter !== "all" || deferredCapabilityFilter !== "all",
+    }),
+    [
+      tab,
+      filteredDiscoverRows,
+      filteredCachedRows,
+      filteredLocalRows,
+      selectedId,
+      isLoading,
+      downloadedReady,
+      inventoryError,
+      inventoryWarning,
+      query,
+      activeCheckpoint,
+      activeGgufVariant,
+      searchError,
+      online,
+      isDatasetMode,
+      inventoryTokens,
+      scannedCount,
+      discoverFetchIntent,
+      hasMore,
+      discoverManualFetchAvailable,
+      deferredFormatFilter,
+      deferredCapabilityFilter,
+    ],
+  );
+
+  const catalogPagination = useMemo<ModelsCatalogPagination>(
+    () => ({
+      scrollRef,
+      sentinelRef,
+      isLoadingMore,
+    }),
+    [scrollRef, sentinelRef, isLoadingMore],
+  );
+
+  const catalogHandlers = useMemo<ModelsCatalogHandlers>(
+    () => ({
+      onSelect: handleSelect,
+      onFetchMore: fetchMoreDiscoverManually,
+      onClearFilters: handleClearFilters,
+      onRetry: handleRetrySearch,
+      onInventoryChange: refreshInventory,
+      onSwitchDevice: handleSwitchDevice,
+    }),
+    [
+      handleSelect,
+      fetchMoreDiscoverManually,
+      handleClearFilters,
+      handleRetrySearch,
+      refreshInventory,
+      handleSwitchDevice,
+    ],
+  );
+
+  return (
+    <div className="hub-page flex h-full min-h-0 flex-col bg-background">
+      <div className="mx-auto flex w-full max-w-[1180px] flex-1 min-h-0 flex-col gap-6 px-5 pt-8 pb-16 sm:px-9 sm:pt-10 sm:pb-24">
+        <ModelsHeader
+          cachedCount={effectiveCachedRows.length}
+          localCount={effectiveLocalRows.length}
+          isDataset={isDatasetMode}
+          gpuLabel={gpuLabel}
+          ramLabel={ramLabel}
+          activeCheckpoint={activeCheckpoint}
+          activeGgufVariant={activeGgufVariant}
+          onEject={() => undefined}
+        />
+
+        <section className="elevated-card flex min-h-0 flex-1 flex-col overflow-hidden bg-card">
+          <div className="hub-side-surface shrink-0 px-4 pt-4 pb-6">
+            <ModelsToolbar
+              tab={tab}
+              onTabChange={handleTabChange}
+              query={query}
+              onQueryChange={handleQueryChange}
+              isLoading={isLoading}
+              sortBy={effectiveSort}
+              onSortChange={handleSortChange}
+              resourceType={resourceType}
+              onResourceTypeChange={handleResourceTypeChange}
+              formatFilter={formatFilter}
+              onFormatFilterChange={setFormatFilter}
+              capabilityFilter={capabilityFilter}
+              onCapabilityFilterChange={setCapabilityFilter}
+              activeChannelId={activeChannelId}
+              onChannelSelect={handleChannelSelect}
+              onRefresh={handleRetrySearch}
+              onManageLocalFolders={handleManageLocalFolders}
+            />
+          </div>
+
+          <div className="flex min-h-0 flex-1 flex-col lg:grid lg:grid-cols-[360px_minmax(0,1fr)] xl:grid-cols-[400px_minmax(0,1fr)] 2xl:grid-cols-[440px_minmax(0,1fr)]">
+            <div
+              className={cn(
+                "hub-side-surface flex min-h-0 min-w-0 flex-1 flex-col border-b border-border lg:flex-initial lg:border-b-0 lg:border-r",
+                mobileInspectorOpen && "hidden lg:flex",
+              )}
+            >
+              <ModelsCatalog
+                state={catalogState}
+                pagination={catalogPagination}
+                handlers={catalogHandlers}
+              />
+            </div>
+
+            <div
+              className={cn(
+                "hub-side-surface flex min-h-0 min-w-0 flex-1 flex-col lg:flex-initial",
+                !mobileInspectorOpen && "hidden lg:flex",
+              )}
+            >
+              <button
+                type="button"
+                onClick={() => setMobileInspectorOpen(false)}
+                className="relative z-10 flex h-10 shrink-0 cursor-pointer select-none items-center gap-1.5 border-b border-border bg-transparent px-4 text-[12.5px] font-medium text-muted-foreground transition-colors hover:text-foreground lg:hidden"
+              >
+                <HugeiconsIcon
+                  icon={ArrowLeft01Icon}
+                  strokeWidth={1.75}
+                  className="size-3.5"
+                />
+                Back to list
+              </button>
+              <div className="flex min-h-0 flex-1 flex-col">
+                {(isHubDesktop || mobileInspectorOpen) && (
+                  <ModelInspector
+                    model={selectedModel}
+                    isDataset={isDatasetMode}
+                    metadataUnavailable={metadataUnavailable}
+                    selectionHiddenByFilters={selectionHiddenByFilters}
+                    runtime={inspectorRuntime}
+                    actions={inspectorActions}
+                  />
+                )}
+              </div>
+            </div>
+          </div>
+        </section>
+        <OnDeviceFoldersDialog
+          open={foldersDialogOpen}
+          onOpenChange={setFoldersDialogOpen}
+          onInventoryChange={refreshInventory}
+        />
+        <ExternalLinkConfirmDialog />
+      </div>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/hub/hub.css b/studio/frontend/src/features/hub/hub.css
new file mode 100644
index 0000000000..66e732c7b6
--- /dev/null
+++ b/studio/frontend/src/features/hub/hub.css
@@ -0,0 +1,756 @@
+/* SPDX-License-Identifier: AGPL-3.0-only */
+/* Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0 */
+
+/* Hub feature CSS.
+
+   Lives with the Hub feature module so the styling stays bundled with the
+   Hub. Wired into the build via a single @import in studio/frontend/src/index.css.
+
+   Format/status color tokens are defined at :root and :root.dark so Tailwind
+   utilities like `bg-format-gguf` or `text-status-success` resolve everywhere
+   the Hub UI is rendered. Rule bodies are scoped to .hub-page or hub-prefixed
+   classes so they do not bleed into chat, train or settings surfaces. */
+
+:root {
+	--format-gguf: #60a5fa;
+	--format-checkpoint: #f472b6;
+	--format-adapter: #8b5cf6;
+	--status-warning: #eab308;
+	--status-danger: #ef4444;
+	--status-success: #11b686;
+}
+
+.dark {
+	--format-gguf: #60a5fa;
+	--format-checkpoint: #f472b6;
+	--format-adapter: #a78bfa;
+	--status-warning: #fbbf24;
+	--status-danger: #ef4444;
+	--status-success: #11b686;
+}
+
+@theme inline {
+	--color-format-gguf: var(--format-gguf);
+	--color-format-checkpoint: var(--format-checkpoint);
+	--color-format-adapter: var(--format-adapter);
+	--color-status-warning: var(--status-warning);
+	--color-status-danger: var(--status-danger);
+	--color-status-success: var(--status-success);
+}
+
+@layer base {
+	/* Filled-control surface — Hub search, Hub filter triggers, Train
+	   number/text inputs, Train Selects, picker search bars. The same
+	   visual identity the Hub search has always had:
+	     - Resting: subtle 3% bg + 5% border
+	     - Hover / open: 5% bg + 8% border
+	     - Focus: 4% bg + 15% border (no solid colour swap)
+	     - box-shadow: none on focus to neutralise shadcn's
+	       focus-visible green ring (--ring is the brand primary).
+	   `!important` is used on focus box-shadow only — Tailwind's
+	   `focus-visible:ring-…` utility composes via `--tw-ring-shadow`
+	   into the final box-shadow at the same specificity as ours, and
+	   without bumping ours we'd lose the cascade tie inconsistently
+	   depending on which utility was applied last to the element. */
+	.field-soft {
+		background-color: color-mix(in srgb, var(--foreground) 3%, transparent);
+		border: 1px solid color-mix(in srgb, var(--foreground) 5%, transparent);
+		box-shadow: none;
+		transition:
+			background-color 160ms ease,
+			border-color 160ms ease;
+	}
+
+	.field-soft:hover,
+	.field-soft[data-state="open"] {
+		background-color: color-mix(in srgb, var(--foreground) 5%, transparent);
+		border-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+	}
+
+	.field-soft:focus,
+	.field-soft:focus-visible,
+	.field-soft:focus-within {
+		background-color: color-mix(in srgb, var(--foreground) 4%, transparent);
+		border-color: color-mix(in srgb, var(--foreground) 15%, transparent) !important;
+		box-shadow: none !important;
+		outline: none;
+	}
+
+	.dark .field-soft {
+		background-color: color-mix(in srgb, var(--foreground) 4%, transparent);
+		border-color: color-mix(in srgb, var(--foreground) 6%, transparent);
+	}
+
+	.dark .field-soft:hover,
+	.dark .field-soft[data-state="open"] {
+		background-color: color-mix(in srgb, var(--foreground) 5%, transparent);
+		border-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+	}
+
+	.dark .field-soft:focus,
+	.dark .field-soft:focus-visible,
+	.dark .field-soft:focus-within {
+		background-color: color-mix(in srgb, var(--foreground) 7%, transparent);
+		border-color: color-mix(in srgb, var(--foreground) 15%, transparent) !important;
+	}
+
+	.hub-page .elevated-card {
+		border: 1px solid color-mix(in srgb, var(--foreground) 5%, transparent);
+		border-radius: 20px;
+		box-shadow:
+			0 12px 48px -8px color-mix(in srgb, var(--foreground) 8%, transparent),
+			0 0 100px 20px color-mix(in srgb, var(--foreground) 3%, transparent);
+	}
+
+	@media (min-width: 640px) {
+		.hub-page .elevated-card {
+			border-radius: 28px;
+		}
+	}
+
+	@media (min-width: 1024px) {
+		.hub-page .elevated-card {
+			border-radius: 32px;
+		}
+	}
+
+	html.dark .hub-page .elevated-card {
+		border-color: transparent;
+		box-shadow: none;
+	}
+
+	.hub-page .page-title-halo {
+		text-shadow:
+			0 0 24px #e4e3df,
+			0 0 56px #ebeae6,
+			0 0 96px #efeeea;
+	}
+
+	html.dark .hub-page .page-title-halo {
+		text-shadow: none;
+	}
+
+	html:not(.dark) .hub-page {
+		background-color: var(--background);
+	}
+
+	html:not(.dark) .hub-page > div > section .border-b,
+	html:not(.dark) .hub-page > div > section .border-r,
+	html:not(.dark) .hub-page > div > section .border-t.border-border {
+		border-color: color-mix(in srgb, var(--foreground) 6%, transparent);
+	}
+
+	html:not(.dark) .hub-page .hub-side-surface {
+		background-color: var(--background);
+	}
+
+	html:not(.dark) .hub-page .hub-tag-soft,
+	html:not(.dark) .hub-page .hub-tag-meta {
+		background-color: transparent;
+		transition:
+			background-color 160ms ease,
+			border-color 160ms ease;
+	}
+
+	html:not(.dark) .hub-page .hub-tag-soft:hover,
+	html:not(.dark) .hub-page .hub-tag-meta:hover {
+		background-color: color-mix(in srgb, var(--foreground) 4%, transparent);
+	}
+
+	html.dark .hub-page {
+		background-color: var(--background);
+	}
+
+	html.dark .hub-page > div > section [class*="bg-card"],
+	html.dark .hub-page > div > section [class*="bg-background"] {
+		background-color: var(--popover);
+	}
+
+	html.dark .hub-page > div > section .border-b,
+	html.dark .hub-page > div > section .border-r,
+	html.dark .hub-page > div > section .border-t.border-border {
+		border-color: color-mix(in srgb, var(--foreground) 5%, transparent);
+	}
+
+	html.dark .hub-page .hub-side-surface {
+		background-color: transparent;
+	}
+
+	html.dark .hub-page .hub-tag-soft,
+	html.dark .hub-page .hub-tag-meta {
+		background-color: transparent;
+		transition:
+			background-color 160ms ease,
+			border-color 160ms ease;
+	}
+
+	html.dark .hub-page .hub-tag-soft {
+		color: var(--muted-foreground);
+	}
+
+	html.dark .hub-page .hub-tag-meta {
+		color: var(--muted-foreground);
+	}
+
+	html.dark .hub-page .hub-tag-soft:hover,
+	html.dark .hub-page .hub-tag-meta:hover {
+		background-color: color-mix(in srgb, var(--foreground) 4%, transparent);
+	}
+
+	.hub-menu-instant {
+		animation: none !important;
+		transition: none !important;
+		transform: none !important;
+		--tw-translate-x: 0px !important;
+		--tw-translate-y: 0px !important;
+		--tw-scale-x: 1 !important;
+		--tw-scale-y: 1 !important;
+		translate: 0 0 !important;
+		user-select: none;
+		-webkit-user-select: none;
+		will-change: auto !important;
+	}
+
+	.hub-menu-instant.menu-soft-surface {
+		--menu-soft-blur: 18px;
+		--menu-soft-spread: -8px;
+	}
+
+	.hub-menu-instant [data-slot="select-item"]:focus,
+	.hub-menu-instant [data-slot="select-item"][data-highlighted],
+	.hub-menu-instant [role="option"][data-highlighted] {
+		background-color: color-mix(in srgb, var(--foreground) 6%, transparent);
+		color: var(--foreground);
+	}
+
+	html.dark .hub-menu-instant [data-slot="select-item"]:focus,
+	html.dark .hub-menu-instant [data-slot="select-item"][data-highlighted],
+	html.dark .hub-menu-instant [role="option"][data-highlighted] {
+		background-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+		color: var(--foreground);
+	}
+
+	html.dark .hub-menu-instant {
+		background-color: #2e2f31 !important;
+	}
+
+	.hub-menu-instant *,
+	.hub-menu-instant *::before,
+	.hub-menu-instant *::after,
+	.hub-menu-trigger,
+	.hub-menu-trigger * {
+		animation: none !important;
+		transition: none !important;
+		user-select: none;
+		-webkit-user-select: none;
+	}
+
+	html:not(.dark) .hub-page .hub-tab-toggle {
+		background-color: color-mix(in srgb, var(--foreground) 5%, transparent);
+		border: 0;
+		box-shadow: none;
+	}
+
+	html.dark .hub-page .hub-tab-toggle {
+		background-color: color-mix(in srgb, var(--foreground) 4.5%, transparent);
+		border: 0;
+		box-shadow: none;
+	}
+
+	html:not(.dark) .hub-page .hub-tab-toggle-pill {
+		background-color: var(--background);
+		border: 0;
+		box-shadow:
+			0 1px 2px color-mix(in srgb, var(--foreground) 8%, transparent),
+			0 4px 10px -3px color-mix(in srgb, var(--foreground) 6%, transparent);
+	}
+
+	html.dark .hub-page .hub-tab-toggle-pill {
+		background-color: color-mix(in srgb, var(--foreground) 10%, transparent);
+		border: 0;
+		box-shadow:
+			0 1px 2px rgba(0, 0, 0, 0.14),
+			0 4px 10px -3px rgba(0, 0, 0, 0.1);
+	}
+
+	html:not(.dark) .hub-page .catalog-row {
+		background-color: transparent;
+		border-color: transparent;
+		box-shadow: none;
+		transition: background-color 160ms ease;
+	}
+
+	html:not(.dark) .hub-page .catalog-row:hover {
+		background-color: color-mix(in srgb, var(--foreground) 3.5%, transparent);
+	}
+
+	html:not(.dark) .hub-page .catalog-row[data-selected="true"] {
+		background-color: color-mix(in srgb, var(--foreground) 6%, transparent);
+	}
+
+	/* Currently-loaded checkpoint: a brand-green left stripe plus a faint
+	   green wash, orthogonal to the neutral selected tint so a row that is
+	   both loaded and selected still reads as loaded. */
+	html:not(.dark) .hub-page .catalog-row[data-active="true"] {
+		background-color: color-mix(in srgb, var(--status-success) 7%, transparent);
+		box-shadow: inset 2px 0 0 0 var(--primary);
+	}
+
+	html.dark .hub-page .catalog-row {
+		background-color: transparent;
+		border-color: transparent;
+		box-shadow: none;
+		transition: background-color 160ms ease;
+	}
+
+	html.dark .hub-page .catalog-row:hover {
+		background-color: color-mix(in srgb, var(--foreground) 3.5%, transparent);
+	}
+
+	html.dark .hub-page .catalog-row[data-selected="true"] {
+		background-color: color-mix(in srgb, var(--foreground) 7%, transparent);
+	}
+
+	html.dark .hub-page .catalog-row[data-active="true"] {
+		background-color: color-mix(in srgb, var(--status-success) 12%, transparent);
+		box-shadow: inset 2px 0 0 0 var(--primary);
+	}
+
+}
+
+@layer utilities {
+	.hub-tag-soft,
+	.hub-tag-meta {
+		@apply min-h-[26px] rounded-[11px] bg-muted/70 ring-1 ring-inset;
+		--tw-ring-color: color-mix(in srgb, var(--foreground) 3.5%, transparent);
+	}
+
+	.dark .hub-tag-soft,
+	.dark .hub-tag-meta {
+		@apply bg-white/[0.05] ring-white/[0.035];
+	}
+	.hub-download-card {
+		@apply flex w-full flex-col gap-2 rounded-[22px] p-2;
+		background-color: color-mix(in srgb, var(--foreground) 3%, transparent);
+		border: 1px solid color-mix(in srgb, var(--foreground) 5.5%, transparent);
+		box-shadow: none;
+	}
+
+	.dark .hub-download-card {
+		background-color: color-mix(in srgb, var(--foreground) 3.5%, transparent);
+		border: 1px solid color-mix(in srgb, var(--foreground) 5.5%, transparent);
+		box-shadow: none;
+	}
+
+	.hub-download-panel {
+		border-radius: 20px;
+		background-color: var(--popover);
+		border: 1px solid color-mix(in srgb, var(--foreground) 6%, transparent);
+		box-shadow:
+			0 1px 2px color-mix(in srgb, var(--foreground) 7%, transparent),
+			0 18px 48px -12px color-mix(in srgb, var(--foreground) 22%, transparent);
+	}
+
+	.dark .hub-download-panel {
+		border-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+		box-shadow:
+			0 1px 2px rgba(0, 0, 0, 0.4),
+			0 20px 56px -12px rgba(0, 0, 0, 0.6);
+	}
+
+	.hub-download-fab {
+		position: relative;
+		display: inline-flex;
+		width: 2.75rem;
+		height: 2.75rem;
+		cursor: pointer;
+		align-items: center;
+		justify-content: center;
+		border-radius: 9999px;
+		color: var(--muted-foreground);
+		background-color: var(--popover);
+		border: 1px solid color-mix(in srgb, var(--foreground) 6%, transparent);
+		box-shadow:
+			0 1px 2px color-mix(in srgb, var(--foreground) 7%, transparent),
+			0 12px 32px -10px color-mix(in srgb, var(--foreground) 22%, transparent);
+		transition:
+			color 150ms ease,
+			background-color 150ms ease,
+			box-shadow 150ms ease,
+			transform 150ms ease;
+	}
+
+	.hub-download-fab:hover {
+		color: var(--foreground);
+		transform: translateY(-1px);
+		box-shadow:
+			0 2px 4px color-mix(in srgb, var(--foreground) 8%, transparent),
+			0 16px 40px -10px color-mix(in srgb, var(--foreground) 26%, transparent);
+	}
+
+	.dark .hub-download-fab {
+		border-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+		box-shadow:
+			0 1px 2px rgba(0, 0, 0, 0.4),
+			0 14px 36px -10px rgba(0, 0, 0, 0.6);
+	}
+
+	.dark .hub-download-fab:hover {
+		box-shadow:
+			0 2px 4px rgba(0, 0, 0, 0.45),
+			0 18px 44px -10px rgba(0, 0, 0, 0.65);
+	}
+
+	.hub-download-fab-badge {
+		position: absolute;
+		top: -3px;
+		right: -3px;
+		display: inline-flex;
+		min-width: 1.125rem;
+		height: 1.125rem;
+		align-items: center;
+		justify-content: center;
+		border-radius: 9999px;
+		padding-inline: 0.3125rem;
+		background-color: var(--status-success);
+		color: var(--primary-foreground);
+		font-size: 10.5px;
+		font-weight: 600;
+		line-height: 1;
+		font-variant-numeric: tabular-nums;
+		border: 2px solid var(--popover);
+	}
+}
+
+@layer base {
+	.hub-avatar-tile {
+		box-shadow: 0 0 0 0.5px color-mix(in srgb, var(--foreground) 6%, transparent);
+	}
+
+	.dark .hub-avatar-tile {
+		box-shadow: 0 0 0 0.5px color-mix(in srgb, var(--foreground) 8%, transparent);
+	}
+
+	/* Verified badge: solid badge shape with a check-shaped hole punched
+	   through, so whatever sits behind shows through the check. The badge
+	   fill follows currentColor (so `text-primary` makes it Unsloth green;
+	   any text-* utility recolors it). Use as: `<span class="hub-verified-badge
+	   size-4 text-primary" />`. */
+	.hub-verified-badge {
+		display: inline-block;
+		background-color: currentColor;
+		mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><defs><mask id='c'><rect width='24' height='24' fill='white'/><path d='m8.75 12.5 2.5 2.5 4.25-5.25' stroke='black' stroke-width='1.85' stroke-linecap='round' stroke-linejoin='round' fill='none'/></mask></defs><path d='M8.603 3.799A4.49 4.49 0 0 1 12 2.25c1.357 0 2.573.6 3.397 1.549a4.49 4.49 0 0 1 3.498 1.307 4.491 4.491 0 0 1 1.307 3.497A4.49 4.49 0 0 1 21.75 12a4.49 4.49 0 0 1-1.549 3.397 4.491 4.491 0 0 1-1.307 3.497 4.491 4.491 0 0 1-3.497 1.307A4.49 4.49 0 0 1 12 21.75a4.49 4.49 0 0 1-3.397-1.549 4.49 4.49 0 0 1-3.498-1.306 4.491 4.491 0 0 1-1.307-3.498A4.49 4.49 0 0 1 2.25 12c0-1.357.6-2.573 1.549-3.397a4.49 4.49 0 0 1 1.307-3.497 4.49 4.49 0 0 1 3.497-1.307Z' fill='white' mask='url(%23c)'/></svg>") center / contain no-repeat;
+		-webkit-mask: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><defs><mask id='c'><rect width='24' height='24' fill='white'/><path d='m8.75 12.5 2.5 2.5 4.25-5.25' stroke='black' stroke-width='1.85' stroke-linecap='round' stroke-linejoin='round' fill='none'/></mask></defs><path d='M8.603 3.799A4.49 4.49 0 0 1 12 2.25c1.357 0 2.573.6 3.397 1.549a4.49 4.49 0 0 1 3.498 1.307 4.491 4.491 0 0 1 1.307 3.497A4.49 4.49 0 0 1 21.75 12a4.49 4.49 0 0 1-1.549 3.397 4.491 4.491 0 0 1-1.307 3.497 4.491 4.491 0 0 1-3.497 1.307A4.49 4.49 0 0 1 12 21.75a4.49 4.49 0 0 1-3.397-1.549 4.49 4.49 0 0 1-3.498-1.306 4.491 4.491 0 0 1-1.307-3.498A4.49 4.49 0 0 1 2.25 12c0-1.357.6-2.573 1.549-3.397a4.49 4.49 0 0 1 1.307-3.497 4.49 4.49 0 0 1 3.497-1.307Z' fill='white' mask='url(%23c)'/></svg>") center / contain no-repeat;
+	}
+
+
+	@keyframes hub-loading-sweep {
+		0% {
+			opacity: 0;
+			transform: translate3d(-120%, 0, 0);
+		}
+
+		16% {
+			opacity: 0.92;
+		}
+
+		78% {
+			opacity: 0.92;
+		}
+
+		100% {
+			opacity: 0;
+			transform: translate3d(520%, 0, 0);
+		}
+	}
+
+	.hub-loading-bar {
+		pointer-events: none;
+		position: relative;
+		overflow: hidden;
+		width: 100%;
+		height: 3px;
+	}
+
+	.hub-loading-bar::after {
+		content: "";
+		display: none;
+		position: absolute;
+		inset-block: 0;
+		left: 0;
+		width: 36%;
+		background: linear-gradient(90deg,
+				transparent,
+				color-mix(in srgb, var(--foreground) 20%, transparent),
+				color-mix(in srgb, var(--foreground) 58%, transparent),
+				color-mix(in srgb, var(--foreground) 20%, transparent),
+				transparent);
+		will-change: opacity, transform;
+	}
+
+	html.dark .hub-loading-bar::after {
+		background: linear-gradient(90deg,
+				transparent,
+				color-mix(in srgb, var(--foreground) 22%, transparent),
+				color-mix(in srgb, var(--foreground) 60%, transparent),
+				color-mix(in srgb, var(--foreground) 22%, transparent),
+				transparent);
+	}
+
+	.hub-loading-bar[data-active="true"]::after {
+		display: block;
+		animation: hub-loading-sweep 3s cubic-bezier(0.22, 0.72, 0.18, 1) infinite;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hub-loading-bar[data-active="true"]::after {
+			animation-duration: 3s !important;
+			animation-iteration-count: infinite !important;
+		}
+	}
+
+	/* README markdown can be thousands of nodes. Keep its paint/layout work
+	   scoped so unrelated overlays, like the sidebar account menu, do less
+	   route-wide recalculation while the Hub is open. */
+	.hub-readme-prose {
+		content-visibility: auto;
+		contain-intrinsic-size: auto 640px;
+	}
+
+	.hub-readme-prose > * {
+		content-visibility: auto;
+		contain-intrinsic-size: auto 140px;
+	}
+
+	.hub-readme-prose :is(p, div):has(> a:nth-of-type(2) > img) {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 0.5rem;
+	}
+
+	.hub-readme-prose :is(p, div):has(> a:nth-of-type(2) > img) > br {
+		display: none;
+	}
+
+	.hub-readme-prose :is(p, div):has(> a:nth-of-type(2) > img) > a {
+		display: inline-flex;
+		align-items: center;
+	}
+
+	.hub-readme-prose :is(p, div):has(> a:nth-of-type(2) > img) img {
+		margin-block: 0;
+	}
+
+	/* Inspector action pills (Download / Run / Train / Cancel) for the hub
+	   inspector card. Centralized so all three sections (GGUF, safetensors,
+	   datasets) stay in lock-step on type scale, padding, hover surface, and
+	   the 16px icon size — mirrors the pattern used for `.sidebar-nav-btn`.
+	   Width and disabled tint are layered inline by callers (some buttons
+	   are w-24 in a pair, some are w-28 standalone). Raw CSS rather than
+	   @apply so the cascade is explicit and predictable. */
+	.hub-action-btn {
+		display: inline-flex;
+		height: 2.25rem;
+		cursor: pointer;
+		align-items: center;
+		justify-content: center;
+		gap: 0.5rem;
+		white-space: nowrap;
+		border-radius: 9999px;
+		background-color: transparent;
+		padding-left: 0.75rem;
+		padding-right: 0.75rem;
+		font-size: 13px;
+		font-weight: 500;
+		line-height: 18px;
+		letter-spacing: -0.025em;
+		color: var(--foreground);
+		transition: color 150ms, background-color 150ms;
+	}
+
+	.hub-action-btn:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--foreground) 4%, transparent);
+	}
+
+	.dark .hub-action-btn:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--foreground) 5%, transparent);
+	}
+
+	.hub-action-btn:disabled {
+		cursor: not-allowed;
+	}
+
+	/* Every glyph inside a hub action button — explicit icon, spinner, or
+	   embedded SVG — locks to 16px so swapping icons or replacing the
+	   spinner can't drift the layout. */
+	.hub-action-btn svg {
+		width: 1rem;
+		height: 1rem;
+		flex-shrink: 0;
+	}
+
+	/* Primary "Run" action — confirms loading/running a model. Pill shape
+	   (rounded-full) so it reads as the unmistakable CTA in a row of
+	   ghost actions and matches the live-model status-success token used
+	   elsewhere in the app. Same h-9 geometry, 13px
+	   medium type, tracking-tight, and 16px icon slot as .hub-action-btn
+	   so the height aligns with adjacent ghost buttons. */
+	.hub-run-action-btn {
+		display: inline-flex;
+		height: 2.25rem;
+		cursor: pointer;
+		align-items: center;
+		justify-content: center;
+		gap: 0.4rem;
+		white-space: nowrap;
+		border-radius: 9999px;
+		background-color: var(--status-success);
+		padding-left: 1rem;
+		padding-right: 1rem;
+		font-size: 13px;
+		font-weight: 600;
+		line-height: 18px;
+		letter-spacing: -0.025em;
+		color: var(--primary-foreground);
+		transition: background-color 150ms, transform 150ms;
+		box-shadow:
+			inset 0 1px 0 color-mix(in srgb, var(--primary-foreground) 18%, transparent),
+			0 1px 2px color-mix(in srgb, var(--status-success) 22%, transparent);
+	}
+
+	.hub-run-action-btn:hover:not(:disabled) {
+		background-color: color-mix(in srgb, var(--status-success) 88%, black);
+	}
+
+	.hub-run-action-btn:active:not(:disabled) {
+		transform: scale(0.98);
+	}
+
+	.hub-run-action-btn:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+
+	.hub-run-action-btn svg {
+		width: 0.9rem;
+		height: 0.9rem;
+		flex-shrink: 0;
+	}
+
+	/* Spinner-default / cancel-on-hover swap inside `.hub-action-btn`.
+	   Two glyphs occupy the same 16×16 slot; the button's :hover toggles
+	   their opacities so the percentage label beside them never shifts. */
+	.hub-cta-indicator {
+		position: relative;
+		display: inline-flex;
+		width: 1rem;
+		height: 1rem;
+		flex-shrink: 0;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.hub-cta-indicator-spinner,
+	.hub-cta-indicator-cancel {
+		transition: opacity 150ms;
+	}
+
+	.hub-cta-indicator-cancel {
+		position: absolute;
+		opacity: 0;
+	}
+
+	.hub-action-btn:hover .hub-cta-indicator-spinner {
+		opacity: 0;
+	}
+
+	.hub-action-btn:hover .hub-cta-indicator-cancel {
+		opacity: 1;
+	}
+
+	/* Hover-revealed inline action overlay (used for the row-end trash on
+	   downloaded models and datasets in the inspector). Wrapper 28×28 with a
+	   16px glyph — same icon size as `.hub-action-btn` so the destructive
+	   affordance reads consistently with the primary actions. Relies on a
+	   `.group/dl` ancestor for the hover scope (the Hub download row). */
+	.hub-row-action {
+		position: absolute;
+		right: 0.25rem;
+		top: 50%;
+		display: inline-flex;
+		width: 1.75rem;
+		height: 1.75rem;
+		transform: translateY(-50%);
+		align-items: center;
+		justify-content: center;
+		border-radius: 8px;
+		color: var(--muted-foreground);
+		opacity: 0;
+		cursor: pointer;
+		transition: opacity 150ms, color 150ms;
+	}
+
+	.group\/dl:hover .hub-row-action,
+	.hub-row-action:focus-visible {
+		opacity: 1;
+	}
+
+	.hub-row-action:hover {
+		color: rgb(225 29 72);
+	}
+
+	.dark .hub-row-action:hover {
+		color: rgb(251 113 133);
+	}
+
+	.hub-row-action svg {
+		width: 1rem;
+		height: 1rem;
+		flex-shrink: 0;
+	}
+}
+
+@layer base {
+	.hub-page .field-trigger.field-filter {
+		color: var(--muted-foreground);
+		font-weight: 400;
+		padding-top: 0.25rem;
+		padding-bottom: 0.25rem;
+		line-height: 1.25rem;
+	}
+
+	.hub-page .field-trigger.field-filter:hover {
+		color: var(--foreground);
+	}
+}
+
+html:not(.dark) .hub-page [data-hub-scroll="true"] {
+	scrollbar-color: oklch(0.5 0 0 / 0.22) transparent;
+}
+
+html.dark .hub-page [data-hub-scroll="true"] {
+	scrollbar-color: oklch(0.55 0 0 / 0.16) transparent;
+}
+
+html:not(.dark) .hub-page [data-hub-scroll="true"]::-webkit-scrollbar-thumb {
+	background: oklch(0.5 0 0 / 0.22);
+}
+
+html.dark .hub-page [data-hub-scroll="true"]::-webkit-scrollbar-thumb {
+	background: oklch(0.55 0 0 / 0.16);
+}
+
+/* While a modal dialog is open (delete confirmation, transport-mode swap, the
+   folder manager) Radix locks the background: it sets body[data-scroll-locked]
+   and body { pointer-events: none }. A few Hub affordances (the cached-size
+   chip, the row delete button) opt back into pointer events with
+   `pointer-events-auto` so they can sit above the row's full-bleed click
+   overlay. That opt-in must NOT survive an open modal, or hovering the
+   background fires their tooltips behind the dialog. Re-disable only those
+   opt-ins while the scroll lock is active; everything else is already blocked
+   by the body-level rule, and the dialog's own portaled content never carries
+   this class. */
+body[data-scroll-locked] .hub-modal-pe-guard {
+	pointer-events: none !important;
+}
diff --git a/studio/frontend/src/features/hub/inventory/api.ts b/studio/frontend/src/features/hub/inventory/api.ts
new file mode 100644
index 0000000000..8ae3f7d3cd
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/api.ts
@@ -0,0 +1,455 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import {
+  disposableTimeoutSignal,
+  withAbort,
+} from "@/features/hub/lib/abort-signals";
+import { hubTokenHeader } from "@/features/hub/lib/hub-token-header";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+import { localPathCacheKey } from "@/features/hub/lib/local-path";
+import { isHuggingFaceOffline } from "@/features/hub/lib/network";
+import { fingerprintToken } from "@/features/hub/lib/token-fingerprint";
+import { bumpInventoryVersion } from "@/features/hub/stores/inventory-events";
+import type { LocalSource } from "./constants";
+import { bumpGgufVariantsCacheVersion } from "./gguf-variants-cache-events";
+
+export type ModelInventoryFormat =
+  | "gguf"
+  | "safetensors"
+  | "adapter"
+  | "checkpoint"
+  | "unknown";
+export type ModelInventoryRuntime =
+  | "llama_cpp"
+  | "transformers"
+  | "adapter"
+  | "unknown";
+export type BaseModelSource = "huggingface" | "local" | "unknown";
+
+export interface BackendModelCapabilities {
+  can_train?: boolean;
+  can_chat?: boolean;
+  can_delete?: boolean;
+  can_download?: boolean;
+  requires_variant?: boolean;
+  supports_lora?: boolean;
+  supports_vision?: boolean;
+}
+
+export interface CachedGgufRepo {
+  repo_id: string;
+  inventory_id?: string | null;
+  load_id?: string | null;
+  model_format?: ModelInventoryFormat | null;
+  runtime?: ModelInventoryRuntime | null;
+  format_variant?: string | null;
+  capabilities?: BackendModelCapabilities | null;
+  size_bytes: number;
+  cache_path?: string;
+  partial?: boolean;
+  partial_transport?: string | null;
+  pipeline_tag?: string | null;
+  tags?: string[];
+  library_name?: string | null;
+}
+
+export interface CachedModelRepo {
+  repo_id: string;
+  inventory_id?: string | null;
+  load_id?: string | null;
+  model_format?: ModelInventoryFormat | null;
+  runtime?: ModelInventoryRuntime | null;
+  format_variant?: string | null;
+  capabilities?: BackendModelCapabilities | null;
+  size_bytes: number;
+  cache_path?: string;
+  partial?: boolean;
+  partial_transport?: string | null;
+  pipeline_tag?: string | null;
+  tags?: string[];
+  library_name?: string | null;
+  quant_method?: string | null;
+}
+
+export interface LocalModelInfo {
+  id: string;
+  inventory_id?: string | null;
+  load_id?: string | null;
+  display_name: string;
+  path: string;
+  size_bytes?: number;
+  model_format?: ModelInventoryFormat | null;
+  runtime?: ModelInventoryRuntime | null;
+  format_variant?: string | null;
+  capabilities?: BackendModelCapabilities | null;
+  source: LocalSource;
+  model_id?: string | null;
+  base_model?: string | null;
+  base_model_source?: BaseModelSource | null;
+  adapter_type?: string | null;
+  training_method?: string | null;
+  updated_at?: number | null;
+  partial?: boolean;
+  partial_transport?: string | null;
+  pipeline_tag?: string | null;
+  tags?: string[];
+  library_name?: string | null;
+  quant_method?: string | null;
+}
+
+export interface LocalModelListResponse {
+  models_dir: string;
+  hf_cache_dir?: string | null;
+  lmstudio_dirs: string[];
+  ollama_dirs?: string[];
+  models: LocalModelInfo[];
+}
+
+export interface CachedDatasetRepo {
+  repo_id: string;
+  size_bytes: number;
+  cache_path?: string;
+  partial?: boolean;
+  partial_transport?: string | null;
+}
+
+export type LocalDatasetInfo = {
+  metadata?: {
+    actual_num_records?: number | null;
+    target_num_records?: number | null;
+    total_num_batches?: number | null;
+    num_completed_batches?: number | null;
+    columns?: string[] | null;
+  } | null;
+  id: string;
+  label: string;
+  path: string;
+  source: "recipe" | "upload";
+  rows?: number | null;
+  updated_at?: number | null;
+};
+
+export type LocalDatasetsResponse = {
+  datasets: LocalDatasetInfo[];
+};
+
+export interface ScanFolderInfo {
+  id: number;
+  path: string;
+  created_at: string;
+}
+
+export interface BrowseEntry {
+  name: string;
+  has_models: boolean;
+  hidden: boolean;
+}
+
+export interface BrowseFoldersResponse {
+  current: string;
+  parent: string | null;
+  entries: BrowseEntry[];
+  suggestions: string[];
+  truncated?: boolean;
+  model_files_here?: number;
+}
+
+export interface GgufVariantDetail {
+  filename: string;
+  quant: string;
+  display_label?: string | null;
+  size_bytes: number;
+  download_size_bytes?: number;
+  downloaded?: boolean;
+  partial?: boolean;
+  partial_transport?: string | null;
+}
+
+export interface GgufVariantsResponse {
+  repo_id: string;
+  variants: GgufVariantDetail[];
+  has_vision: boolean;
+  default_variant: string | null;
+}
+
+async function parseJsonOrThrow<T>(
+  response: Response,
+  fallback?: string,
+): Promise<T> {
+  if (!response.ok) {
+    throw new Error(await readFastApiError(response, fallback));
+  }
+  return response.json();
+}
+
+async function throwIfNotOk(
+  response: Response,
+  fallback?: string,
+): Promise<void> {
+  if (!response.ok) {
+    throw new Error(await readFastApiError(response, fallback));
+  }
+}
+
+const INVENTORY_TIMEOUT_MS = 30_000;
+
+async function withHubTimeout<T>(
+  ms: number,
+  request: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const timeout = disposableTimeoutSignal(ms);
+  try {
+    return await request(timeout.signal);
+  } finally {
+    timeout.dispose();
+  }
+}
+
+export async function listLocalModels(): Promise<LocalModelListResponse> {
+  const response = await withHubTimeout(INVENTORY_TIMEOUT_MS, (signal) =>
+    authFetch("/api/hub/local", { signal }),
+  );
+  return parseJsonOrThrow<LocalModelListResponse>(response);
+}
+
+export async function listCachedGguf(
+  hfToken?: string | null,
+): Promise<CachedGgufRepo[]> {
+  const response = await withHubTimeout(INVENTORY_TIMEOUT_MS, (signal) =>
+    authFetch("/api/hub/cached-gguf", {
+      headers: hubTokenHeader(hfToken),
+      signal,
+    }),
+  );
+  const data = await parseJsonOrThrow<{ cached: CachedGgufRepo[] }>(response);
+  return data.cached;
+}
+
+export async function listCachedModels(
+  hfToken?: string | null,
+): Promise<CachedModelRepo[]> {
+  const response = await withHubTimeout(INVENTORY_TIMEOUT_MS, (signal) =>
+    authFetch("/api/hub/cached-models", {
+      headers: hubTokenHeader(hfToken),
+      signal,
+    }),
+  );
+  const data = await parseJsonOrThrow<{ cached: CachedModelRepo[] }>(response);
+  return data.cached;
+}
+
+export async function listLocalDatasets(): Promise<LocalDatasetsResponse> {
+  const response = await withHubTimeout(INVENTORY_TIMEOUT_MS, (signal) =>
+    authFetch("/api/hub/datasets/local", { signal }),
+  );
+  return parseJsonOrThrow<LocalDatasetsResponse>(response);
+}
+
+export async function listCachedDatasets(): Promise<CachedDatasetRepo[]> {
+  const response = await withHubTimeout(INVENTORY_TIMEOUT_MS, (signal) =>
+    authFetch("/api/hub/datasets/cached", { signal }),
+  );
+  const data = await parseJsonOrThrow<{ cached: CachedDatasetRepo[] }>(response);
+  return data.cached;
+}
+
+export async function deleteCachedDataset(repoId: string): Promise<void> {
+  const response = await authFetch("/api/hub/datasets/cached", {
+    method: "DELETE",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ repo_id: repoId }),
+  });
+  await throwIfNotOk(response, `Failed to delete dataset (${response.status})`);
+  bumpInventoryVersion();
+}
+
+export async function deleteCachedModel(
+  repoId: string,
+  variant?: string,
+  hfToken?: string | null,
+): Promise<void> {
+  const payload: Record<string, string> = { repo_id: repoId };
+  if (variant) {
+    payload.variant = variant;
+  }
+  const response = await authFetch("/api/hub/delete-cached", {
+    method: "DELETE",
+    headers: { "Content-Type": "application/json", ...hubTokenHeader(hfToken) },
+    body: JSON.stringify(payload),
+  });
+  try {
+    await throwIfNotOk(response);
+    bumpInventoryVersion();
+  } finally {
+    invalidateGgufVariantsCache(repoId);
+  }
+}
+
+export async function listScanFolders(): Promise<ScanFolderInfo[]> {
+  const response = await authFetch("/api/hub/scan-folders");
+  const data = await parseJsonOrThrow<{ folders: ScanFolderInfo[] }>(response);
+  return data.folders;
+}
+
+export async function addScanFolder(path: string): Promise<ScanFolderInfo> {
+  const response = await authFetch("/api/hub/scan-folders", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ path }),
+  });
+  const folder = await parseJsonOrThrow<ScanFolderInfo>(response);
+  bumpInventoryVersion();
+  return folder;
+}
+
+export async function removeScanFolder(id: number): Promise<void> {
+  const response = await authFetch(`/api/hub/scan-folders/${id}`, {
+    method: "DELETE",
+  });
+  await throwIfNotOk(response);
+  bumpInventoryVersion();
+}
+
+export async function browseFolders(
+  path?: string,
+  showHidden = false,
+  signal?: AbortSignal,
+): Promise<BrowseFoldersResponse> {
+  const params = new URLSearchParams();
+  if (path !== undefined && path !== null) {
+    params.set("path", path);
+  }
+  if (showHidden) {
+    params.set("show_hidden", "true");
+  }
+  const qs = params.toString();
+  const response = await authFetch(
+    `/api/hub/browse-folders${qs ? `?${qs}` : ""}`,
+    signal ? { signal } : undefined,
+  );
+  return parseJsonOrThrow<BrowseFoldersResponse>(response);
+}
+
+const GGUF_VARIANTS_TTL_MS = 30 * 1000;
+const GGUF_VARIANTS_LOCAL_TTL_MS = 10 * 60 * 1000;
+const GGUF_VARIANTS_TIMEOUT_MS = 30_000;
+const GGUF_VARIANTS_CACHE_MAX_ENTRIES = 64;
+
+interface GgufVariantsCacheEntry {
+  expiresAt: number;
+  promise: Promise<GgufVariantsResponse>;
+}
+
+const ggufVariantsCache = new Map<string, GgufVariantsCacheEntry>();
+
+function pruneGgufVariantsCache(now = Date.now()): void {
+  for (const [key, entry] of ggufVariantsCache) {
+    if (entry.expiresAt <= now) {
+      ggufVariantsCache.delete(key);
+    }
+  }
+  while (ggufVariantsCache.size > GGUF_VARIANTS_CACHE_MAX_ENTRIES) {
+    const oldest = ggufVariantsCache.keys().next().value;
+    if (!oldest) {
+      break;
+    }
+    ggufVariantsCache.delete(oldest);
+  }
+}
+
+function ggufVariantsTtlMs(
+  response: GgufVariantsResponse,
+  preferLocalCache: boolean,
+): number {
+  if (
+    preferLocalCache &&
+    response.variants.some((variant) => variant.downloaded)
+  ) {
+    return GGUF_VARIANTS_LOCAL_TTL_MS;
+  }
+  return GGUF_VARIANTS_TTL_MS;
+}
+
+export async function listGgufVariants(
+  repoId: string,
+  hfToken?: string,
+  options?: {
+    preferLocalCache?: boolean;
+    localPath?: string | null;
+    signal?: AbortSignal;
+  },
+): Promise<GgufVariantsResponse> {
+  const offline = isHuggingFaceOffline();
+  const localPath = options?.localPath?.trim() || null;
+  const preferLocalCache = !!options?.preferLocalCache || offline;
+  const signal = options?.signal;
+  const key = `${repoId}::${fingerprintToken(hfToken)}::${
+    preferLocalCache ? "local" : "remote"
+  }::${localPathCacheKey(localPath)}`;
+  const now = Date.now();
+  const hit = ggufVariantsCache.get(key);
+  if (hit && now < hit.expiresAt) {
+    ggufVariantsCache.delete(key);
+    ggufVariantsCache.set(key, hit);
+    return withAbort(hit.promise, signal);
+  }
+  if (hit) {
+    ggufVariantsCache.delete(key);
+  }
+  const params = new URLSearchParams({ repo_id: repoId });
+  if (preferLocalCache) {
+    params.set("prefer_local_cache", "true");
+  }
+  if (localPath) {
+    params.set("local_path", localPath);
+  }
+  if (offline) {
+    params.set("offline", "true");
+  }
+  const requestPromise = withHubTimeout(
+    GGUF_VARIANTS_TIMEOUT_MS,
+    async (signal) => {
+      const response = await authFetch(`/api/hub/gguf-variants?${params}`, {
+        headers: hubTokenHeader(hfToken),
+        signal,
+      });
+      return parseJsonOrThrow<GgufVariantsResponse>(response);
+    },
+  );
+  const promise = requestPromise.then((result) => {
+    const current = ggufVariantsCache.get(key);
+    if (current?.promise === promise) {
+      current.expiresAt =
+        Date.now() + ggufVariantsTtlMs(result, preferLocalCache);
+    }
+    return result;
+  });
+  ggufVariantsCache.set(key, {
+    expiresAt: now + GGUF_VARIANTS_TTL_MS,
+    promise,
+  });
+  pruneGgufVariantsCache(now);
+  promise.catch(() => {
+    if (ggufVariantsCache.get(key)?.promise === promise) {
+      ggufVariantsCache.delete(key);
+    }
+  });
+  return withAbort(promise, signal);
+}
+
+export function invalidateGgufVariantsCache(repoId?: string): void {
+  if (!repoId) {
+    ggufVariantsCache.clear();
+    bumpGgufVariantsCacheVersion();
+    return;
+  }
+  const repoPrefix = `${repoId}::`.toLowerCase();
+  for (const key of ggufVariantsCache.keys()) {
+    if (key.toLowerCase().startsWith(repoPrefix)) {
+      ggufVariantsCache.delete(key);
+    }
+  }
+  bumpGgufVariantsCacheVersion(repoId);
+}
diff --git a/studio/frontend/src/features/hub/inventory/constants.ts b/studio/frontend/src/features/hub/inventory/constants.ts
new file mode 100644
index 0000000000..6482f5f602
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/constants.ts
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export const LOCAL_MODEL_SOURCE = {
+  MODELS_DIR: "models_dir",
+  HF_CACHE: "hf_cache",
+  LMSTUDIO: "lmstudio",
+  OLLAMA: "ollama",
+  CUSTOM: "custom",
+} as const;
+
+export const LOCAL_MODEL_SOURCES = [
+  LOCAL_MODEL_SOURCE.MODELS_DIR,
+  LOCAL_MODEL_SOURCE.HF_CACHE,
+  LOCAL_MODEL_SOURCE.LMSTUDIO,
+  LOCAL_MODEL_SOURCE.OLLAMA,
+  LOCAL_MODEL_SOURCE.CUSTOM,
+] as const;
+export type LocalSource = (typeof LOCAL_MODEL_SOURCES)[number];
+
+export const INVENTORY_HINT_KIND = {
+  MODEL: "model",
+  GGUF: "gguf",
+  DATASET: "dataset",
+} as const;
+
+export const INVENTORY_HINT_KINDS = [
+  INVENTORY_HINT_KIND.MODEL,
+  INVENTORY_HINT_KIND.GGUF,
+  INVENTORY_HINT_KIND.DATASET,
+] as const;
+export type InventoryHintKind = (typeof INVENTORY_HINT_KINDS)[number];
diff --git a/studio/frontend/src/features/hub/inventory/gguf-variants-cache-events.ts b/studio/frontend/src/features/hub/inventory/gguf-variants-cache-events.ts
new file mode 100644
index 0000000000..d5d8299ffe
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/gguf-variants-cache-events.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+type Listener = () => void;
+
+const listeners = new Set<Listener>();
+const repoVersions = new Map<string, number>();
+const REPO_VERSION_LIMIT = 256;
+let globalVersion = 0;
+let versionSequence = 0;
+
+function repoKey(repoId: string): string {
+  return repoId.trim().toLowerCase();
+}
+
+function emit(): void {
+  for (const listener of [...listeners]) listener();
+}
+
+function nextVersion(): number {
+  versionSequence += 1;
+  return versionSequence;
+}
+
+export function bumpGgufVariantsCacheVersion(repoId?: string): void {
+  const key = repoId ? repoKey(repoId) : "";
+  if (key) {
+    repoVersions.delete(key);
+    repoVersions.set(key, nextVersion());
+    while (repoVersions.size > REPO_VERSION_LIMIT) {
+      const oldest = repoVersions.keys().next().value;
+      if (!oldest) break;
+      repoVersions.delete(oldest);
+    }
+  } else {
+    globalVersion = nextVersion();
+  }
+  emit();
+}
+
+export function getGgufVariantsCacheVersion(repoId?: string | null): string {
+  const key = repoId ? repoKey(repoId) : "";
+  return `${globalVersion}:${key ? (repoVersions.get(key) ?? 0) : 0}`;
+}
+
+export function subscribeGgufVariantsCache(
+  listener: Listener,
+): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
diff --git a/studio/frontend/src/features/hub/inventory/index.ts b/studio/frontend/src/features/hub/inventory/index.ts
new file mode 100644
index 0000000000..dd8e161708
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/index.ts
@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export {
+  INVENTORY_HINT_KIND,
+  INVENTORY_HINT_KINDS,
+  LOCAL_MODEL_SOURCE,
+  LOCAL_MODEL_SOURCES,
+  type InventoryHintKind,
+  type LocalSource,
+} from "./constants";
+export {
+  addScanFolder,
+  browseFolders,
+  listCachedDatasets,
+  listCachedGguf,
+  listCachedModels,
+  deleteCachedDataset,
+  deleteCachedModel,
+  invalidateGgufVariantsCache,
+  listGgufVariants,
+  listLocalDatasets,
+  listLocalModels,
+  listScanFolders,
+  removeScanFolder,
+  type BrowseFoldersResponse,
+  type CachedDatasetRepo,
+  type CachedGgufRepo,
+  type CachedModelRepo,
+  type BaseModelSource,
+  type GgufVariantDetail,
+  type GgufVariantsResponse,
+  type LocalDatasetInfo,
+  type LocalModelInfo,
+  type LocalModelListResponse,
+  type ModelInventoryFormat,
+  type ModelInventoryRuntime,
+  type ScanFolderInfo,
+} from "./api";
+export {
+  buildLocalInventoryRows,
+  buildCachedInventoryRow,
+  defaultCapabilities,
+  formatLocalUpdated,
+  localSourceLabel,
+  normalizeCapabilities,
+  normalizeModelFormat,
+  normalizeRuntime,
+  normalizeTimestamp,
+} from "./view-models";
+export {
+  resolveInventoryResource,
+  type InventoryResourceFormatHint,
+  type ResolvedInventoryResource,
+} from "./resource-resolver";
+export {
+  dedupeSameSourceHubCacheRows,
+  findCompleteHfCacheLocalRow,
+} from "./inventory-dedupe";
+export {
+  fetchInventorySource,
+  useDeviceInventorySources,
+  useDeviceInventoryStore,
+  type DeviceInventoryRows,
+  type DeviceInventorySource,
+  type DeviceInventorySourceState,
+} from "./use-device-inventory";
+export {
+  useHubInventory,
+  type HubInventoryKind,
+  type HubInventory,
+} from "./use-hub-inventory";
+export { useGgufVariantsCacheVersion } from "./use-gguf-variants-cache-version";
+export type {
+  CachedInventoryRow,
+  InventoryHint,
+  InventoryRow,
+  LocalInventoryRow,
+  ModelInventoryCapabilities,
+} from "./types";
diff --git a/studio/frontend/src/features/hub/inventory/inventory-dedupe.ts b/studio/frontend/src/features/hub/inventory/inventory-dedupe.ts
new file mode 100644
index 0000000000..138f83fadb
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/inventory-dedupe.ts
@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { CachedInventoryRow, LocalInventoryRow } from "./types";
+
+function repoFormatKey(
+  repoId: string | null | undefined,
+  modelFormat: string | null | undefined,
+): string | null {
+  const normalizedRepo = repoId?.trim().toLowerCase();
+  if (!normalizedRepo) {
+    return null;
+  }
+  return `${normalizedRepo}\0${modelFormat ?? "unknown"}`;
+}
+
+function repoKey(repoId: string | null | undefined): string | null {
+  return repoId?.trim().toLowerCase() || null;
+}
+
+export function findCompleteHfCacheLocalRow(
+  cachedRow: CachedInventoryRow,
+  localRows: readonly LocalInventoryRow[],
+): LocalInventoryRow | null {
+  const key = repoFormatKey(cachedRow.repoId, cachedRow.modelFormat);
+  if (!key) {
+    return null;
+  }
+  return (
+    localRows.find(
+      (row) =>
+        row.source === "hf_cache" &&
+        !row.partial &&
+        repoFormatKey(row.repoId, row.modelFormat) === key,
+    ) ?? null
+  );
+}
+
+export function partialSetFromRows<T extends { partial?: boolean }>(
+  rows: readonly T[],
+  getRepoId: (row: T) => string | null | undefined,
+): Set<string> {
+  const complete = new Set<string>();
+  for (const row of rows) {
+    const repoId = getRepoId(row);
+    if (repoId && !row.partial) complete.add(repoId.toLowerCase());
+  }
+  const partial = new Set<string>();
+  for (const row of rows) {
+    const repoId = getRepoId(row);
+    if (!repoId) continue;
+    const key = repoId.toLowerCase();
+    if (row.partial && !complete.has(key)) partial.add(key);
+  }
+  return partial;
+}
+
+function preferCachedRow(
+  candidate: CachedInventoryRow,
+  existing: CachedInventoryRow | null | undefined,
+): boolean {
+  if (!existing) {
+    return true;
+  }
+  if (Boolean(candidate.partial) !== Boolean(existing.partial)) {
+    return !candidate.partial;
+  }
+  if (Boolean(candidate.liveDownload) !== Boolean(existing.liveDownload)) {
+    return Boolean(candidate.liveDownload);
+  }
+  return candidate.bytes > existing.bytes;
+}
+
+function dedupeCachedRows(
+  rows: readonly CachedInventoryRow[],
+): CachedInventoryRow[] {
+  const selected = new Map<string, CachedInventoryRow>();
+  const passthrough: CachedInventoryRow[] = [];
+  for (const row of rows) {
+    const key = repoFormatKey(row.repoId, row.modelFormat);
+    if (!key) {
+      passthrough.push(row);
+      continue;
+    }
+    const existing = selected.get(key);
+    if (preferCachedRow(row, existing)) {
+      selected.set(key, row);
+    }
+  }
+  return [...selected.values(), ...passthrough];
+}
+
+export function dedupeSameSourceHubCacheRows({
+  cachedRows,
+  localRows,
+}: {
+  cachedRows: readonly CachedInventoryRow[];
+  localRows: readonly LocalInventoryRow[];
+}): {
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+} {
+  const uniqueCachedRows = dedupeCachedRows(cachedRows);
+  const completeCachedRepos = new Set<string>();
+  const partialGgufRepos = new Set<string>();
+  for (const row of uniqueCachedRows) {
+    if (row.partial && row.modelFormat === "gguf") {
+      const repo = repoKey(row.repoId);
+      if (repo) partialGgufRepos.add(repo);
+    }
+    if (row.partial) {
+      continue;
+    }
+    const repo = repoKey(row.repoId);
+    if (repo) {
+      completeCachedRepos.add(repo);
+    }
+  }
+
+  const completeHfCacheLocalKeys = new Set<string>();
+  for (const row of localRows) {
+    if (row.partial && row.modelFormat === "gguf") {
+      const repo = repoKey(row.repoId);
+      if (repo) partialGgufRepos.add(repo);
+    }
+    if (row.source !== "hf_cache" || row.partial) {
+      continue;
+    }
+    const key = repoFormatKey(row.repoId, row.modelFormat);
+    if (key) {
+      completeHfCacheLocalKeys.add(key);
+    }
+  }
+
+  const filteredCachedRows = uniqueCachedRows.filter((row) => {
+    const repo = repoKey(row.repoId);
+    if (
+      row.partial &&
+      !row.liveDownload &&
+      row.modelFormat === "unknown" &&
+      repo &&
+      partialGgufRepos.has(repo)
+    ) {
+      return false;
+    }
+    const key = repoFormatKey(row.repoId, row.modelFormat);
+    return !(row.partial && key && completeHfCacheLocalKeys.has(key));
+  });
+  const retainedCachedKeys = new Set(
+    filteredCachedRows.flatMap((row) => {
+      const key = repoFormatKey(row.repoId, row.modelFormat);
+      return key ? [key] : [];
+    }),
+  );
+
+  return {
+    cachedRows: filteredCachedRows,
+    localRows: localRows.filter((row) => {
+      if (row.source !== "hf_cache") {
+        return true;
+      }
+      const key = repoFormatKey(row.repoId, row.modelFormat);
+      if (key && retainedCachedKeys.has(key)) {
+        return false;
+      }
+      const repo = repoKey(row.repoId);
+      if (
+        row.partial &&
+        row.modelFormat === "unknown" &&
+        repo &&
+        partialGgufRepos.has(repo)
+      ) {
+        return false;
+      }
+      if (
+        row.modelFormat === "unknown" &&
+        repo &&
+        completeCachedRepos.has(repo)
+      ) {
+        return false;
+      }
+      return true;
+    }),
+  };
+}
diff --git a/studio/frontend/src/features/hub/inventory/inventory-hint-store.ts b/studio/frontend/src/features/hub/inventory/inventory-hint-store.ts
new file mode 100644
index 0000000000..b56e488519
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/inventory-hint-store.ts
@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+import { INVENTORY_HINT_KINDS } from "./constants.ts";
+import {
+  type InventoryHintReconciliation,
+  type PendingInventoryHints,
+  clonePendingInventoryHints,
+  commitInventoryHintReconciliation,
+  createPendingInventoryHints,
+  pruneExpiredInventoryHints,
+  reconcileInventoryHints,
+  rememberInventoryHint,
+  repoKey,
+} from "./inventory-hints.ts";
+import type { InventoryHint } from "./types.ts";
+import { evictOldestUnprotected } from "../lib/lru-map.ts";
+
+export const MAX_OBSERVED_INVENTORY_KEYS_PER_KIND = 1024;
+
+type ObservedInventoryKeys = Record<InventoryHint["kind"], Set<string>>;
+
+export type PendingHintReconciliationCommit = {
+  kind: InventoryHint["kind"];
+  reconciliation: Pick<
+    InventoryHintReconciliation,
+    "pending" | "staleCompletedHints" | "observedKeys"
+  >;
+};
+
+type InventoryHintState = {
+  pending: PendingInventoryHints;
+  observedKeys: ObservedInventoryKeys;
+  pruneExpiredHints: () => void;
+  commitReconciliations: (
+    completedHints: readonly InventoryHint[],
+    baseline: PendingInventoryHints,
+    reconciliations: readonly PendingHintReconciliationCommit[],
+  ) => InventoryHint[];
+};
+
+const INVENTORY_HINT_EQUALITY_FIELDS = {
+  kind: true,
+  repoId: true,
+  bytes: true,
+  createdAt: true,
+} satisfies Record<keyof InventoryHint, true>;
+
+const INVENTORY_HINT_EQUALITY_KEYS = Object.keys(
+  INVENTORY_HINT_EQUALITY_FIELDS,
+) as (keyof InventoryHint)[];
+
+function createObservedInventoryKeys(): ObservedInventoryKeys {
+  return {
+    model: new Set(),
+    gguf: new Set(),
+    dataset: new Set(),
+  };
+}
+
+function setEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) {
+    return false;
+  }
+  for (const value of a) {
+    if (!b.has(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function inventoryHintEqual(
+  a: InventoryHint | undefined,
+  b: InventoryHint,
+): boolean {
+  if (a === undefined) {
+    return false;
+  }
+  return INVENTORY_HINT_EQUALITY_KEYS.every((key) => {
+    const left =
+      key === "bytes" || key === "createdAt" ? (a[key] ?? 0) : a[key];
+    const right =
+      key === "bytes" || key === "createdAt" ? (b[key] ?? 0) : b[key];
+    return left === right;
+  });
+}
+
+export function pendingInventoryHintsEqual(
+  a: PendingInventoryHints,
+  b: PendingInventoryHints,
+): boolean {
+  for (const kind of INVENTORY_HINT_KINDS) {
+    if (a[kind].size !== b[kind].size) {
+      return false;
+    }
+    for (const [key, hint] of a[kind]) {
+      if (!inventoryHintEqual(b[kind].get(key), hint)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+export function pendingHintReconciliationNeedsCommit(
+  baseline: PendingInventoryHints,
+  observedKeys: Record<InventoryHint["kind"], ReadonlySet<string>>,
+  commit: PendingHintReconciliationCommit,
+): boolean {
+  if (!pendingInventoryHintsEqual(baseline, commit.reconciliation.pending)) {
+    return true;
+  }
+  if (commit.reconciliation.staleCompletedHints.length > 0) {
+    return true;
+  }
+  return !setEqual(
+    observedKeys[commit.kind],
+    commit.reconciliation.observedKeys,
+  );
+}
+
+function observedInventoryKeysEqual(
+  a: ObservedInventoryKeys,
+  b: ObservedInventoryKeys,
+): boolean {
+  return INVENTORY_HINT_KINDS.every((kind) => setEqual(a[kind], b[kind]));
+}
+
+function pendingHasHint(
+  pending: PendingInventoryHints,
+  hint: InventoryHint,
+): boolean {
+  const existing = pending[hint.kind].get(repoKey(hint.repoId));
+  if (!existing) {
+    return false;
+  }
+  return (existing.bytes ?? 0) >= (hint.bytes ?? 0);
+}
+
+export function pendingWithInventoryHints(
+  pending: PendingInventoryHints,
+  hints: readonly InventoryHint[],
+): PendingInventoryHints {
+  let next = pruneExpiredInventoryHints(pending);
+  for (const hint of hints) {
+    if (!pendingHasHint(next, hint)) {
+      next = rememberInventoryHint(next, hint);
+    }
+  }
+  return next;
+}
+
+function rememberObservedInventoryKeys(
+  current: ObservedInventoryKeys,
+  kind: InventoryHint["kind"],
+  keys: ReadonlySet<string>,
+  pending: PendingInventoryHints,
+): ObservedInventoryKeys {
+  const observed = new Set(current[kind]);
+  for (const key of keys) {
+    observed.delete(key);
+    observed.add(key);
+  }
+  evictOldestUnprotected(
+    observed,
+    MAX_OBSERVED_INVENTORY_KEYS_PER_KIND,
+    (key) => pending[kind].has(key),
+  );
+  if (setEqual(current[kind], observed)) {
+    return current;
+  }
+  return { ...current, [kind]: observed };
+}
+
+export const useInventoryHintStore = create<InventoryHintState>()(
+  (set, get) => ({
+    pending: createPendingInventoryHints(),
+    observedKeys: createObservedInventoryKeys(),
+    pruneExpiredHints: () => {
+      const current = get().pending;
+      const next = pruneExpiredInventoryHints(current);
+      if (!pendingInventoryHintsEqual(current, next)) {
+        set({ pending: clonePendingInventoryHints(next) });
+      }
+    },
+    commitReconciliations: (completedHints, baseline, reconciliations) => {
+      const state = get();
+      let next = pendingWithInventoryHints(state.pending, completedHints);
+      let observedKeys = state.observedKeys;
+      const completedHintsToSuppress: InventoryHint[] = [];
+      for (const { kind, reconciliation } of reconciliations) {
+        const committed = commitInventoryHintReconciliation({
+          current: next,
+          kind,
+          baseline,
+          next: reconciliation.pending,
+          staleCompletedHints: reconciliation.staleCompletedHints,
+        });
+        next = committed.pending;
+        observedKeys = rememberObservedInventoryKeys(
+          observedKeys,
+          kind,
+          reconciliation.observedKeys,
+          next,
+        );
+        completedHintsToSuppress.push(...committed.completedHintsToSuppress);
+      }
+      const unchanged =
+        pendingInventoryHintsEqual(state.pending, next) &&
+        observedInventoryKeysEqual(state.observedKeys, observedKeys);
+      if (!unchanged) {
+        set({ pending: clonePendingInventoryHints(next), observedKeys });
+      }
+      return completedHintsToSuppress;
+    },
+  }),
+);
+
+export { reconcileInventoryHints };
diff --git a/studio/frontend/src/features/hub/inventory/inventory-hints.ts b/studio/frontend/src/features/hub/inventory/inventory-hints.ts
new file mode 100644
index 0000000000..af9f254ab3
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/inventory-hints.ts
@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { InventoryHint } from "./types";
+
+export type PendingInventoryHints = Record<
+  InventoryHint["kind"],
+  Map<string, InventoryHint>
+>;
+
+export type InventoryHintRow = {
+  repo_id: string;
+  size_bytes: number;
+  partial?: boolean;
+};
+
+export type InventoryHintReconciliation = {
+  rows: InventoryHintRow[];
+  pending: PendingInventoryHints;
+  staleCompletedHints: InventoryHint[];
+  observedKeys: Set<string>;
+};
+
+type InventoryHintCommit = {
+  pending: PendingInventoryHints;
+  completedHintsToSuppress: InventoryHint[];
+};
+
+export const INVENTORY_HINT_TTL_MS = 5 * 60_000;
+
+function rowRepoId(row: InventoryHintRow): string {
+  return row.repo_id;
+}
+
+function rowSizeBytes(row: InventoryHintRow): number {
+  return row.size_bytes;
+}
+
+function optimisticRow(hint: InventoryHint): InventoryHintRow {
+  return {
+    repo_id: hint.repoId,
+    size_bytes: hint.bytes ?? 0,
+    partial: false,
+  };
+}
+
+function suppressibleInventoryHint(hint: InventoryHint): InventoryHint {
+  return {
+    kind: hint.kind,
+    repoId: hint.repoId,
+    ...(hint.bytes ? { bytes: hint.bytes } : {}),
+  };
+}
+
+export function createPendingInventoryHints(): PendingInventoryHints {
+  return {
+    model: new Map(),
+    gguf: new Map(),
+    dataset: new Map(),
+  };
+}
+
+export function clonePendingInventoryHints(
+  source: PendingInventoryHints,
+): PendingInventoryHints {
+  return {
+    model: new Map(source.model),
+    gguf: new Map(source.gguf),
+    dataset: new Map(source.dataset),
+  };
+}
+
+function clonePendingInventoryHintsForKind(
+  source: PendingInventoryHints,
+  kind: InventoryHint["kind"],
+): PendingInventoryHints {
+  return {
+    ...source,
+    [kind]: new Map(source[kind]),
+  };
+}
+
+export function repoKey(repoId: string): string {
+  return repoId.trim().toLowerCase();
+}
+
+export function inventoryHintKey(
+  kind: InventoryHint["kind"],
+  repoId: string,
+): string {
+  return `${kind}:${repoKey(repoId)}`;
+}
+
+function mergeInventoryHint(
+  rows: InventoryHintRow[],
+  hint: InventoryHint,
+): InventoryHintRow[] {
+  const lower = repoKey(hint.repoId);
+  const seed = optimisticRow(hint);
+  const idx = rows.findIndex((row) => repoKey(rowRepoId(row)) === lower);
+  if (idx === -1) {
+    return [...rows, seed];
+  }
+  const merged = {
+    ...rows[idx],
+    ...seed,
+    size_bytes: Math.max(rowSizeBytes(rows[idx]), rowSizeBytes(seed)),
+  };
+  return [...rows.slice(0, idx), merged, ...rows.slice(idx + 1)];
+}
+
+export function rememberInventoryHint(
+  pending: PendingInventoryHints,
+  hint: InventoryHint,
+): PendingInventoryHints {
+  const next = clonePendingInventoryHints(pending);
+  const key = repoKey(hint.repoId);
+  const existing = next[hint.kind].get(key);
+  const bytes = Math.max(existing?.bytes ?? 0, hint.bytes ?? 0);
+  const createdAt = existing?.createdAt ?? hint.createdAt ?? Date.now();
+  next[hint.kind].set(key, {
+    kind: hint.kind,
+    repoId: hint.repoId,
+    ...(bytes > 0 ? { bytes } : {}),
+    createdAt,
+  });
+  return next;
+}
+
+function inventoryHintExpired(hint: InventoryHint, now: number): boolean {
+  return (hint.createdAt ?? now) + INVENTORY_HINT_TTL_MS <= now;
+}
+
+export function nextInventoryHintExpiryDelay(
+  pending: PendingInventoryHints,
+  now = Date.now(),
+): number | null {
+  let nextExpiry = Number.POSITIVE_INFINITY;
+  for (const hints of Object.values(pending)) {
+    for (const hint of hints.values()) {
+      if (typeof hint.createdAt !== "number") {
+        continue;
+      }
+      nextExpiry = Math.min(nextExpiry, hint.createdAt + INVENTORY_HINT_TTL_MS);
+    }
+  }
+  return Number.isFinite(nextExpiry) ? Math.max(0, nextExpiry - now) : null;
+}
+
+export function pruneExpiredInventoryHints(
+  pending: PendingInventoryHints,
+  now = Date.now(),
+): PendingInventoryHints {
+  let next = pending;
+  for (const kind of Object.keys(pending) as InventoryHint["kind"][]) {
+    for (const [key, hint] of next[kind]) {
+      if (!inventoryHintExpired(hint, now)) {
+        continue;
+      }
+      if (next === pending) {
+        next = clonePendingInventoryHints(pending);
+      }
+      next[kind].delete(key);
+    }
+  }
+  return next;
+}
+
+function serverRowSatisfiesHint(
+  row: InventoryHintRow,
+  hint: InventoryHint,
+): boolean {
+  if (row.partial) {
+    return false;
+  }
+  return !hint.bytes || rowSizeBytes(row) >= hint.bytes;
+}
+
+export function reconcileInventoryHints<T extends InventoryHintRow>({
+  pending,
+  kind,
+  rows,
+  previouslyObserved,
+}: {
+  pending: PendingInventoryHints;
+  kind: InventoryHint["kind"];
+  rows: T[];
+  previouslyObserved: ReadonlySet<string>;
+}): InventoryHintReconciliation {
+  const pruned = pruneExpiredInventoryHints(pending);
+  const serverRows = new Map(rows.map((row) => [repoKey(rowRepoId(row)), row]));
+  const observedKeys = new Set(serverRows.keys());
+  if (pruned[kind].size === 0) {
+    return {
+      rows,
+      pending: pruned,
+      staleCompletedHints: [],
+      observedKeys,
+    };
+  }
+
+  const nextPending = clonePendingInventoryHintsForKind(pruned, kind);
+  const hints = nextPending[kind];
+  const staleCompletedHints: InventoryHint[] = [];
+
+  for (const [key, hint] of hints) {
+    const serverRow = serverRows.get(key);
+    if (serverRow && serverRowSatisfiesHint(serverRow, hint)) {
+      hints.delete(key);
+    } else if (!serverRow && previouslyObserved.has(key)) {
+      hints.delete(key);
+      staleCompletedHints.push(hint);
+    }
+  }
+
+  let mergedRows: InventoryHintRow[] = rows;
+  for (const hint of hints.values()) {
+    mergedRows = mergeInventoryHint(mergedRows, hint);
+  }
+
+  return {
+    rows: mergedRows,
+    pending: nextPending,
+    staleCompletedHints,
+    observedKeys,
+  };
+}
+
+export function commitInventoryHintReconciliation({
+  current,
+  kind,
+  baseline,
+  next,
+  staleCompletedHints,
+}: {
+  current: PendingInventoryHints;
+  kind: InventoryHint["kind"];
+  baseline: PendingInventoryHints;
+  next: PendingInventoryHints;
+  staleCompletedHints: InventoryHint[];
+}): InventoryHintCommit {
+  const committed = clonePendingInventoryHints(
+    pruneExpiredInventoryHints(current),
+  );
+  const sharedHints = committed[kind];
+  const staleKeys = new Set(
+    staleCompletedHints.map((hint) => repoKey(hint.repoId)),
+  );
+  const completedHintsToSuppress: InventoryHint[] = [];
+
+  for (const [key, baselineHint] of baseline[kind]) {
+    const nextHint = next[kind].get(key);
+    const currentHint = sharedHints.get(key);
+    const currentIsNewer =
+      currentHint && (currentHint.bytes ?? 0) > (baselineHint.bytes ?? 0);
+
+    if (nextHint) {
+      if (!currentIsNewer) {
+        sharedHints.set(key, nextHint);
+      }
+      continue;
+    }
+    if (currentIsNewer) {
+      continue;
+    }
+    sharedHints.delete(key);
+    if (staleKeys.has(key)) {
+      completedHintsToSuppress.push(suppressibleInventoryHint(baselineHint));
+    }
+  }
+
+  return { pending: committed, completedHintsToSuppress };
+}
diff --git a/studio/frontend/src/features/hub/inventory/resource-resolver.ts b/studio/frontend/src/features/hub/inventory/resource-resolver.ts
new file mode 100644
index 0000000000..343c59e758
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/resource-resolver.ts
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type {
+  CachedInventoryRow,
+  LocalInventoryRow,
+  ModelInventoryFormat,
+} from "./types";
+
+export type InventoryResourceFormatHint =
+  | ModelInventoryFormat
+  | "non-gguf"
+  | null
+  | undefined;
+
+export type ResolvedInventoryResource = {
+  cachedRow: CachedInventoryRow | null;
+  localRow: LocalInventoryRow | null;
+};
+
+function repoKey(value: string | null | undefined): string {
+  return value?.trim().toLowerCase() ?? "";
+}
+
+function cachedRowMatchesFormat(
+  row: CachedInventoryRow,
+  formatHint: InventoryResourceFormatHint,
+): boolean {
+  if (!formatHint || formatHint === "unknown") return true;
+  if (formatHint === "non-gguf") return row.modelFormat !== "gguf";
+  return row.modelFormat === formatHint;
+}
+
+function localRowMatchesFormat(
+  row: LocalInventoryRow,
+  formatHint: InventoryResourceFormatHint,
+): boolean {
+  if (!formatHint || formatHint === "unknown") return true;
+  if (formatHint === "non-gguf") return row.modelFormat !== "gguf";
+  return row.modelFormat === formatHint;
+}
+
+function hasExplicitFormatHint(
+  formatHint: InventoryResourceFormatHint,
+): boolean {
+  return Boolean(formatHint && formatHint !== "unknown");
+}
+
+function bestCompleteCached(
+  rows: CachedInventoryRow[],
+): CachedInventoryRow | null {
+  return (
+    rows.find((row) => !row.partial && row.modelFormat === "safetensors") ??
+    rows.find((row) => !row.partial && row.modelFormat === "checkpoint") ??
+    rows.find((row) => !row.partial && row.modelFormat === "gguf") ??
+    rows.find((row) => !row.partial && row.modelFormat === "adapter") ??
+    rows.find((row) => !row.partial) ??
+    null
+  );
+}
+
+function bestCompleteLocal(rows: LocalInventoryRow[]): LocalInventoryRow | null {
+  return (
+    rows.find((row) => !row.partial && row.source !== "hf_cache") ??
+    rows.find((row) => !row.partial) ??
+    null
+  );
+}
+
+export function resolveInventoryResource({
+  repoId,
+  cachedRows,
+  localRows,
+  formatHint,
+}: {
+  repoId: string | null | undefined;
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+  formatHint?: InventoryResourceFormatHint;
+}): ResolvedInventoryResource {
+  const key = repoKey(repoId);
+  if (!key) return { cachedRow: null, localRow: null };
+
+  const repoCachedRows = cachedRows.filter((row) => repoKey(row.repoId) === key);
+  const repoLocalRows = localRows.filter((row) => repoKey(row.repoId) === key);
+  const compatibleCachedRows = repoCachedRows.filter((row) =>
+    cachedRowMatchesFormat(row, formatHint),
+  );
+  const compatibleLocalRows = repoLocalRows.filter((row) =>
+    localRowMatchesFormat(row, formatHint),
+  );
+
+  const completeCached = bestCompleteCached(compatibleCachedRows);
+  if (completeCached) return { cachedRow: completeCached, localRow: null };
+
+  const completeLocal = bestCompleteLocal(compatibleLocalRows);
+  if (completeLocal) return { cachedRow: null, localRow: completeLocal };
+
+  const partialCached =
+    compatibleCachedRows.find((row) => row.partial) ?? null;
+  if (partialCached) return { cachedRow: partialCached, localRow: null };
+
+  const compatibleLocal = compatibleLocalRows[0] ?? null;
+  if (compatibleLocal) return { cachedRow: null, localRow: compatibleLocal };
+
+  if (hasExplicitFormatHint(formatHint)) {
+    return { cachedRow: null, localRow: null };
+  }
+
+  const fallbackCached = bestCompleteCached(repoCachedRows);
+  if (fallbackCached) return { cachedRow: fallbackCached, localRow: null };
+
+  const fallbackLocal = bestCompleteLocal(repoLocalRows);
+  if (fallbackLocal) return { cachedRow: null, localRow: fallbackLocal };
+
+  const fallbackPartialCached = repoCachedRows.find((row) => row.partial) ?? null;
+  if (fallbackPartialCached) {
+    return { cachedRow: fallbackPartialCached, localRow: null };
+  }
+
+  return {
+    cachedRow: null,
+    localRow: repoLocalRows[0] ?? null,
+  };
+}
diff --git a/studio/frontend/src/features/hub/inventory/types.ts b/studio/frontend/src/features/hub/inventory/types.ts
new file mode 100644
index 0000000000..c86ffb1d86
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/types.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { BaseModelSource } from "./api";
+import type { InventoryHintKind, LocalSource } from "./constants";
+
+export type ModelInventoryFormat =
+  | "gguf"
+  | "safetensors"
+  | "adapter"
+  | "checkpoint"
+  | "unknown";
+export type ModelInventoryRuntime =
+  | "llama_cpp"
+  | "transformers"
+  | "adapter"
+  | "unknown";
+
+export interface ModelInventoryCapabilities {
+  canTrain: boolean;
+  canChat: boolean;
+  canDelete: boolean;
+  canDownload: boolean;
+  requiresVariant: boolean;
+  supportsLora: boolean;
+  supportsVision: boolean;
+}
+
+export interface InventoryHint {
+  kind: InventoryHintKind;
+  repoId: string;
+  bytes?: number;
+  createdAt?: number;
+}
+
+export interface CachedInventoryRow {
+  kind: "cache";
+  id: string;
+  loadId: string;
+  repoId: string;
+  owner: string;
+  repo: string;
+  isGguf: boolean;
+  modelFormat: ModelInventoryFormat;
+  runtime: ModelInventoryRuntime;
+  formatVariant?: string | null;
+  capabilities: ModelInventoryCapabilities;
+  bytes: number;
+  cachePath?: string | null;
+  partial?: boolean;
+  partialTransport?: string | null;
+  pipelineTag?: string | null;
+  tags?: string[];
+  libraryName?: string | null;
+  quantMethod?: string | null;
+  liveDownload?: boolean;
+}
+
+export interface LocalInventoryRow {
+  kind: "local";
+  id: string;
+  loadId: string;
+  repoId: string | null;
+  owner: string;
+  title: string;
+  source: LocalSource;
+  sourceLabel: string;
+  path: string;
+  isGguf: boolean;
+  modelFormat: ModelInventoryFormat;
+  runtime: ModelInventoryRuntime;
+  formatVariant?: string | null;
+  capabilities: ModelInventoryCapabilities;
+  baseModel?: string | null;
+  baseModelSource?: BaseModelSource | null;
+  baseModelHubId?: string | null;
+  adapterType?: string | null;
+  trainingMethod?: string | null;
+  updatedAt: number | null;
+  partial?: boolean;
+  partialTransport?: string | null;
+  pipelineTag?: string | null;
+  tags?: string[];
+  libraryName?: string | null;
+  quantMethod?: string | null;
+}
+
+export type InventoryRow = CachedInventoryRow | LocalInventoryRow;
diff --git a/studio/frontend/src/features/hub/inventory/use-device-inventory.ts b/studio/frontend/src/features/hub/inventory/use-device-inventory.ts
new file mode 100644
index 0000000000..c662a58228
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/use-device-inventory.ts
@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  type CachedDatasetRepo,
+  type CachedGgufRepo,
+  type CachedModelRepo,
+  type LocalDatasetInfo,
+  type LocalModelInfo,
+  listCachedDatasets,
+  listCachedGguf,
+  listCachedModels,
+  listLocalDatasets,
+  listLocalModels,
+} from "./api";
+import { useDebouncedValue } from "@/hooks/use-debounced-value";
+import { fingerprintToken } from "@/features/hub/lib/token-fingerprint";
+import { useInventoryVersion } from "@/features/hub/stores/inventory-events";
+import { useCallback, useEffect, useMemo } from "react";
+import { create } from "zustand";
+import { useShallow } from "zustand/react/shallow";
+
+export type DeviceInventorySource =
+  | "cachedGguf"
+  | "cachedModels"
+  | "cachedDatasets"
+  | "localModels"
+  | "localDatasets";
+
+export type DeviceInventoryRows = {
+  cachedGguf: CachedGgufRepo[];
+  cachedModels: CachedModelRepo[];
+  cachedDatasets: CachedDatasetRepo[];
+  localModels: LocalModelInfo[];
+  localDatasets: LocalDatasetInfo[];
+};
+
+export type DeviceInventorySourceState<Rows extends readonly unknown[]> = {
+  rows: Rows;
+  loading: boolean;
+  ready: boolean;
+  error: string | null;
+  key: string | null;
+};
+
+type DeviceInventoryState = {
+  [K in DeviceInventorySource]: DeviceInventorySourceState<
+    DeviceInventoryRows[K]
+  >;
+};
+
+type FetchInventorySourceOptions = {
+  hfToken?: string | null;
+  tokenFingerprint?: string;
+  inventoryVersion: number;
+  force?: boolean;
+};
+
+type UseDeviceInventoryOptions = {
+  hfToken?: string | null;
+  enabled?: boolean;
+};
+
+type UseDeviceInventoryResult<
+  Sources extends readonly DeviceInventorySource[],
+> = Pick<DeviceInventoryState, Sources[number]> & {
+  refresh: () => Promise<void>;
+};
+
+const TOKEN_SCOPED_SOURCES = new Set<DeviceInventorySource>([
+  "cachedGguf",
+  "cachedModels",
+]);
+const TOKEN_SCOPED_INVENTORY_DEBOUNCE_MS = 500;
+
+const inFlight = new Map<string, Promise<unknown>>();
+const forceQueue = new Map<string, Promise<unknown>>();
+
+function emptySource<
+  Rows extends readonly unknown[],
+>(): DeviceInventorySourceState<Rows> {
+  return {
+    rows: [] as unknown as Rows,
+    loading: false,
+    ready: false,
+    error: null,
+    key: null,
+  };
+}
+
+export const useDeviceInventoryStore = create<DeviceInventoryState>(() => ({
+  cachedGguf: emptySource<CachedGgufRepo[]>(),
+  cachedModels: emptySource<CachedModelRepo[]>(),
+  cachedDatasets: emptySource<CachedDatasetRepo[]>(),
+  localModels: emptySource<LocalModelInfo[]>(),
+  localDatasets: emptySource<LocalDatasetInfo[]>(),
+}));
+
+function sourceRequestKey(
+  source: DeviceInventorySource,
+  inventoryVersion: number,
+  tokenFingerprint: string,
+): string {
+  const tokenPart = TOKEN_SCOPED_SOURCES.has(source)
+    ? tokenFingerprint
+    : "local";
+  return `${source}:${inventoryVersion}:${tokenPart}`;
+}
+
+function fetchErrorMessage(
+  source: DeviceInventorySource,
+  error: unknown,
+): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  switch (source) {
+    case "cachedGguf":
+      return "Couldn't scan cached GGUF models";
+    case "cachedModels":
+      return "Couldn't scan cached Hugging Face models";
+    case "cachedDatasets":
+      return "Couldn't scan cached datasets";
+    case "localModels":
+      return "Couldn't scan local models";
+    case "localDatasets":
+      return "Couldn't scan local datasets";
+    default:
+      return "Couldn't scan inventory";
+  }
+}
+
+function logInventorySourceFailure(
+  source: DeviceInventorySource,
+  error: unknown,
+): void {
+  if (!import.meta.env?.DEV) {
+    return;
+  }
+  console.warn(`Inventory source "${source}" failed to refresh:`, error);
+}
+
+async function runSourceFetch<K extends DeviceInventorySource>(
+  source: K,
+  hfToken?: string | null,
+): Promise<DeviceInventoryRows[K]> {
+  switch (source) {
+    case "cachedGguf":
+      return (await listCachedGguf(hfToken)) as DeviceInventoryRows[K];
+    case "cachedModels":
+      return (await listCachedModels(hfToken)) as DeviceInventoryRows[K];
+    case "cachedDatasets":
+      return (await listCachedDatasets()) as DeviceInventoryRows[K];
+    case "localModels":
+      return (await listLocalModels()).models as DeviceInventoryRows[K];
+    case "localDatasets":
+      return (await listLocalDatasets()).datasets as DeviceInventoryRows[K];
+    default:
+      throw new Error("Unsupported inventory source");
+  }
+}
+
+function updateSourceState<K extends DeviceInventorySource>(
+  source: K,
+  patch: Partial<DeviceInventorySourceState<DeviceInventoryRows[K]>>,
+): void {
+  useDeviceInventoryStore.setState((state) => ({
+    [source]: {
+      ...state[source],
+      ...patch,
+    },
+  }));
+}
+
+export function fetchInventorySource<K extends DeviceInventorySource>(
+  source: K,
+  options: FetchInventorySourceOptions,
+): Promise<DeviceInventoryRows[K]> {
+  const tokenFingerprint =
+    options.tokenFingerprint ?? fingerprintToken(options.hfToken);
+  const key = sourceRequestKey(
+    source,
+    options.inventoryVersion,
+    tokenFingerprint,
+  );
+  const current = useDeviceInventoryStore.getState()[
+    source
+  ] as DeviceInventorySourceState<DeviceInventoryRows[K]>;
+  const pending = inFlight.get(key) as
+    | Promise<DeviceInventoryRows[K]>
+    | undefined;
+  if (pending) {
+    if (!options.force) {
+      return pending;
+    }
+    const queued = forceQueue.get(key) as
+      | Promise<DeviceInventoryRows[K]>
+      | undefined;
+    if (queued) {
+      return queued;
+    }
+    const refetch = pending
+      .catch(() => undefined)
+      .then(() => fetchInventorySource(source, options))
+      .finally(() => {
+        if (forceQueue.get(key) === refetch) {
+          forceQueue.delete(key);
+        }
+      });
+    forceQueue.set(key, refetch);
+    return refetch;
+  }
+  if (!options.force && current.ready && current.key === key) {
+    return Promise.resolve(current.rows);
+  }
+
+  // Carry `ready` across refetches so a stale-but-known state doesn't flip to
+  // "loading" on a bump and flash a spinner in every consumer; show prior rows
+  // until the success path lands fresh data.
+  updateSourceState(source, {
+    loading: true,
+    ready: current.ready,
+    error: null,
+    key,
+  });
+
+  const request = runSourceFetch(source, options.hfToken)
+    .then((rows) => {
+      if (useDeviceInventoryStore.getState()[source].key === key) {
+        updateSourceState(source, {
+          rows,
+          loading: false,
+          ready: true,
+          error: null,
+          key,
+        });
+      }
+      return rows;
+    })
+    .catch((error) => {
+      if (useDeviceInventoryStore.getState()[source].key === key) {
+        // Preserve prior `ready` on failure so a transient background-refetch
+        // error doesn't blank consumers that already hold good rows.
+        updateSourceState(source, {
+          loading: false,
+          ready: current.ready,
+          error: fetchErrorMessage(source, error),
+          key,
+        });
+      }
+      throw error;
+    })
+    .finally(() => {
+      if (inFlight.get(key) === request) {
+        inFlight.delete(key);
+      }
+    });
+
+  inFlight.set(key, request);
+  return request;
+}
+
+export function inventoryEmptyRevalidationSignature(
+  sources: readonly Pick<
+    DeviceInventorySourceState<readonly unknown[]>,
+    "error" | "key" | "ready"
+  >[],
+): string {
+  return sources
+    .map((source) =>
+      [
+        source.key ?? "pending",
+        source.ready ? "ready" : "pending",
+        source.error ?? "",
+      ].join("\u0001"),
+    )
+    .join("\u0002");
+}
+
+export function useDeviceInventorySources<
+  const Sources extends readonly DeviceInventorySource[],
+>(
+  sources: Sources,
+  options: UseDeviceInventoryOptions = {},
+): UseDeviceInventoryResult<Sources> {
+  const rawInventoryVersion = useInventoryVersion();
+  const rawHfToken = options.hfToken ?? undefined;
+  const debouncedInventoryVersion = useDebouncedValue(
+    rawInventoryVersion,
+    TOKEN_SCOPED_INVENTORY_DEBOUNCE_MS,
+  );
+  const debouncedHfToken = useDebouncedValue(
+    rawHfToken,
+    TOKEN_SCOPED_INVENTORY_DEBOUNCE_MS,
+  );
+  const enabled = options.enabled ?? true;
+  const sourceKey = sources.join("|");
+  const sourceList = useMemo(
+    () => sourceKey.split("|").filter(Boolean) as DeviceInventorySource[],
+    [sourceKey],
+  );
+  const hasTokenScopedSources = useMemo(
+    () => sourceList.some((source) => TOKEN_SCOPED_SOURCES.has(source)),
+    [sourceList],
+  );
+  const inventoryVersion = hasTokenScopedSources
+    ? debouncedInventoryVersion
+    : rawInventoryVersion;
+  const hfToken = hasTokenScopedSources ? debouncedHfToken : rawHfToken;
+  const tokenFingerprint = useMemo(() => fingerprintToken(hfToken), [hfToken]);
+  const state = useDeviceInventoryStore(
+    useShallow((s) => {
+      const selected = {} as Pick<DeviceInventoryState, Sources[number]>;
+      for (const source of sourceList) {
+        (selected as Partial<DeviceInventoryState>)[source] = s[
+          source
+        ] as never;
+      }
+      return selected;
+    }),
+  );
+
+  const refresh = useCallback(async () => {
+    const results = await Promise.allSettled(
+      sourceList.map((source) =>
+        fetchInventorySource(source, {
+          hfToken,
+          tokenFingerprint,
+          inventoryVersion,
+          force: true,
+        }),
+      ),
+    );
+    for (const [index, result] of results.entries()) {
+      const source = sourceList[index];
+      if (source && result.status === "rejected") {
+        logInventorySourceFailure(source, result.reason);
+      }
+    }
+  }, [sourceList, hfToken, tokenFingerprint, inventoryVersion]);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    for (const source of sourceList) {
+      fetchInventorySource(source, {
+        hfToken,
+        tokenFingerprint,
+        inventoryVersion,
+      }).catch((error) => logInventorySourceFailure(source, error));
+    }
+  }, [enabled, sourceList, hfToken, tokenFingerprint, inventoryVersion]);
+
+  return {
+    ...state,
+    refresh,
+  } as UseDeviceInventoryResult<Sources>;
+}
diff --git a/studio/frontend/src/features/hub/inventory/use-gguf-variants-cache-version.ts b/studio/frontend/src/features/hub/inventory/use-gguf-variants-cache-version.ts
new file mode 100644
index 0000000000..ad8bfc9fba
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/use-gguf-variants-cache-version.ts
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useSyncExternalStore } from "react";
+import {
+  getGgufVariantsCacheVersion,
+  subscribeGgufVariantsCache,
+} from "./gguf-variants-cache-events";
+
+export function useGgufVariantsCacheVersion(
+  repoId?: string | null,
+): string {
+  return useSyncExternalStore(
+    subscribeGgufVariantsCache,
+    () => getGgufVariantsCacheVersion(repoId),
+    () => getGgufVariantsCacheVersion(repoId),
+  );
+}
diff --git a/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
new file mode 100644
index 0000000000..a7dc7ae3f3
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/use-hub-inventory.ts
@@ -0,0 +1,610 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  clearCompletedInventoryHint,
+  useDownloadManagerStore,
+  type ManagedDownload,
+} from "@/features/hub/download-manager";
+import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { LocalDatasetInfo } from "./api";
+import {
+  dedupeSameSourceHubCacheRows,
+  partialSetFromRows,
+} from "./inventory-dedupe";
+import {
+  type PendingHintReconciliationCommit,
+  pendingHintReconciliationNeedsCommit,
+  pendingInventoryHintsEqual,
+  pendingWithInventoryHints,
+  reconcileInventoryHints,
+  useInventoryHintStore,
+} from "./inventory-hint-store";
+import {
+  type PendingInventoryHints,
+  nextInventoryHintExpiryDelay,
+} from "./inventory-hints";
+import type { CachedInventoryRow, LocalInventoryRow } from "./types";
+import {
+  type DeviceInventorySource,
+  inventoryEmptyRevalidationSignature,
+  useDeviceInventorySources,
+} from "./use-device-inventory";
+import {
+  buildCachedInventoryRow,
+  buildLocalInventoryRows,
+  defaultCapabilities,
+  normalizeTimestamp,
+} from "./view-models";
+
+export interface HubInventory {
+  cachedRows: CachedInventoryRow[];
+  localRows: LocalInventoryRow[];
+  availableSet: Set<string>;
+  partialSet: Set<string>;
+  downloadedReady: boolean;
+  inventoryError: boolean;
+  inventoryWarning: boolean;
+  refreshInventory: () => Promise<void>;
+}
+
+export type HubInventoryKind = "models" | "datasets";
+
+type HubInventoryOptions = {
+  kind?: HubInventoryKind;
+  enabled?: boolean;
+  includeLocal?: boolean;
+};
+
+const MODEL_HUB_CACHE_SOURCES = [
+  "cachedGguf",
+  "cachedModels",
+] as const satisfies readonly DeviceInventorySource[];
+
+const DATASET_HUB_CACHE_SOURCES = [
+  "cachedDatasets",
+] as const satisfies readonly DeviceInventorySource[];
+
+const LOCAL_MODEL_INVENTORY_SOURCE = [
+  "localModels",
+] as const satisfies readonly DeviceInventorySource[];
+
+const LOCAL_DATASET_INVENTORY_SOURCE = [
+  "localDatasets",
+] as const satisfies readonly DeviceInventorySource[];
+
+type LiveInventoryJob = Pick<
+  ManagedDownload,
+  "kind" | "repoId" | "variant" | "state" | "startedAt"
+> & {
+  displayBytes: number;
+};
+
+function compareCachedRows(
+  a: CachedInventoryRow,
+  b: CachedInventoryRow,
+): number {
+  if (Boolean(a.partial) !== Boolean(b.partial)) return a.partial ? 1 : -1;
+  return a.repoId.localeCompare(b.repoId);
+}
+
+function localDatasetSourceLabel(source?: string | null): string {
+  switch (source) {
+    case "recipe":
+      return "Recipe dataset";
+    case "upload":
+      return "Uploaded dataset";
+    default:
+      return "Local dataset";
+  }
+}
+
+function isReadyForDisplay(source: {
+  error: string | null;
+  loading: boolean;
+  ready: boolean;
+  rows: readonly unknown[];
+}): boolean {
+  if (source.error !== null) return true;
+  if (!source.ready) return false;
+  return !(source.loading && source.rows.length === 0);
+}
+
+function liveInventoryRank(job: ManagedDownload): number {
+  if (job.state === "running" || job.state === "cancelling") return 2;
+  if (job.state === "cancelled" || job.state === "error") return 1;
+  return 0;
+}
+
+function shouldSurfaceLiveJob(
+  job: ManagedDownload,
+  isDatasetMode: boolean,
+): boolean {
+  if (isDatasetMode !== (job.kind === "dataset")) return false;
+  if (job.state === "running" || job.state === "cancelling") return true;
+  if (job.state !== "cancelled" && job.state !== "error") return false;
+  return Math.max(job.downloadedBytes, job.completedBytes) > 0;
+}
+
+function liveJobDisplayBytes(job: ManagedDownload): number {
+  if (job.expectedBytes > 0) return job.expectedBytes;
+  if (job.state === "running" || job.state === "cancelling") return 0;
+  return Math.max(job.downloadedBytes, job.completedBytes, 0);
+}
+
+function createLiveInventoryJobsSelector(isDatasetMode: boolean): (state: {
+  jobs: Record<string, ManagedDownload>;
+}) => LiveInventoryJob[] {
+  let cache: { signature: string; jobs: LiveInventoryJob[] } = {
+    signature: "",
+    jobs: [],
+  };
+  return (state) => {
+    const selectedByRepo = new Map<string, ManagedDownload>();
+    for (const job of Object.values(state.jobs)) {
+      if (!shouldSurfaceLiveJob(job, isDatasetMode)) continue;
+      const repoKey = job.repoId.trim().toLowerCase();
+      if (!repoKey) continue;
+      const current = selectedByRepo.get(repoKey);
+      if (
+        !current ||
+        liveInventoryRank(job) > liveInventoryRank(current) ||
+        (liveInventoryRank(job) === liveInventoryRank(current) &&
+          job.startedAt > current.startedAt)
+      ) {
+        selectedByRepo.set(repoKey, job);
+      }
+    }
+    const jobs = [...selectedByRepo.values()]
+      .map((job) => ({
+        kind: job.kind,
+        repoId: job.repoId,
+        variant: job.variant,
+        state: job.state,
+        startedAt: job.startedAt,
+        displayBytes: liveJobDisplayBytes(job),
+      }))
+      .sort((a, b) => a.repoId.localeCompare(b.repoId));
+    const signature = jobs
+      .map(
+        (job) =>
+          `${job.kind}\u0001${job.repoId.toLowerCase()}\u0001${job.variant ?? ""}\u0001${job.state}\u0001${job.startedAt}\u0001${job.displayBytes}`,
+      )
+      .join("\u0002");
+    if (signature === cache.signature) return cache.jobs;
+    cache = { signature, jobs };
+    return jobs;
+  };
+}
+
+function liveDownloadInventoryRows(
+  jobs: readonly LiveInventoryJob[],
+  isDatasetMode: boolean,
+): CachedInventoryRow[] {
+  return jobs.map((job) => {
+    const modelFormat = isDatasetMode
+      ? "unknown"
+      : job.variant
+        ? "gguf"
+        : "safetensors";
+    return {
+      ...buildCachedInventoryRow(
+        {
+          repo_id: job.repoId,
+          inventory_id: `cache:${modelFormat}:${job.repoId}`,
+          load_id: job.repoId,
+          model_format: modelFormat,
+          runtime:
+            modelFormat === "gguf"
+              ? "llama_cpp"
+              : modelFormat === "safetensors"
+                ? "transformers"
+                : "unknown",
+          size_bytes: job.displayBytes,
+          partial: true,
+          partial_transport: null,
+        },
+        modelFormat,
+      ),
+      liveDownload: true,
+    };
+  });
+}
+
+export function useHubInventory(
+  options: HubInventoryOptions = {},
+): HubInventory {
+  const hfToken = useHfTokenStore((state) => state.token) || undefined;
+  const isDatasetMode = (options.kind ?? "models") === "datasets";
+  const enabled = options.enabled ?? true;
+  const includeLocal = options.includeLocal ?? true;
+  const modelInventory = useDeviceInventorySources(MODEL_HUB_CACHE_SOURCES, {
+    hfToken,
+    enabled: enabled && !isDatasetMode,
+  });
+  const datasetInventory = useDeviceInventorySources(
+    DATASET_HUB_CACHE_SOURCES,
+    {
+      hfToken,
+      enabled: enabled && isDatasetMode,
+    },
+  );
+  const localModelInventory = useDeviceInventorySources(
+    LOCAL_MODEL_INVENTORY_SOURCE,
+    {
+      hfToken,
+      enabled: enabled && !isDatasetMode && includeLocal,
+    },
+  );
+  const localDatasetInventory = useDeviceInventorySources(
+    LOCAL_DATASET_INVENTORY_SOURCE,
+    {
+      hfToken,
+      enabled: enabled && isDatasetMode && includeLocal,
+    },
+  );
+  const cachedGgufSource = modelInventory.cachedGguf;
+  const cachedModelsSource = modelInventory.cachedModels;
+  const cachedDatasetsSource = datasetInventory.cachedDatasets;
+  const localModelsSource = localModelInventory.localModels;
+  const localDatasetsSource = localDatasetInventory.localDatasets;
+  const refreshModelInventory = modelInventory.refresh;
+  const refreshDatasetInventory = datasetInventory.refresh;
+  const refreshLocalModelInventory = localModelInventory.refresh;
+  const refreshLocalDatasetInventory = localDatasetInventory.refresh;
+  const pendingHints = useInventoryHintStore((state) => state.pending);
+  const observedInventoryKeys = useInventoryHintStore(
+    (state) => state.observedKeys,
+  );
+  const pruneExpiredPendingHints = useInventoryHintStore(
+    (state) => state.pruneExpiredHints,
+  );
+  const commitPendingHintReconciliations = useInventoryHintStore(
+    (state) => state.commitReconciliations,
+  );
+  const completedHints = useDownloadManagerStore(
+    (state) => state.completedInventoryHints,
+  );
+  const selectLiveInventoryJobs = useMemo(
+    () => createLiveInventoryJobsSelector(isDatasetMode),
+    [isDatasetMode],
+  );
+  const liveInventoryJobs = useDownloadManagerStore(selectLiveInventoryJobs);
+  const emptyRevalidationSignatureRef = useRef<string | null>(null);
+  const pendingForRenderRef = useRef<PendingInventoryHints | null>(null);
+
+  const pendingForRenderNext = useMemo(
+    () => pendingWithInventoryHints(pendingHints, completedHints),
+    [completedHints, pendingHints],
+  );
+  const pendingForRender = useMemo(() => {
+    const current = pendingForRenderRef.current;
+    if (current && pendingInventoryHintsEqual(current, pendingForRenderNext)) {
+      return current;
+    }
+    return pendingForRenderNext;
+  }, [pendingForRenderNext]);
+
+  useEffect(() => {
+    const current = pendingForRenderRef.current;
+    if (!current || !pendingInventoryHintsEqual(current, pendingForRender)) {
+      pendingForRenderRef.current = pendingForRender;
+    }
+  }, [pendingForRender]);
+
+  useEffect(() => {
+    const delay = nextInventoryHintExpiryDelay(pendingHints);
+    if (delay === null) {
+      return;
+    }
+    if (typeof window === "undefined") {
+      pruneExpiredPendingHints();
+      return;
+    }
+    const timer = window.setTimeout(pruneExpiredPendingHints, delay + 1);
+    return () => window.clearTimeout(timer);
+  }, [pendingHints, pruneExpiredPendingHints]);
+
+  const cachedGgufReconciliation = useMemo(
+    () =>
+      reconcileInventoryHints({
+        pending: pendingForRender,
+        kind: "gguf",
+        rows: cachedGgufSource.rows,
+        previouslyObserved: observedInventoryKeys.gguf,
+      }),
+    [cachedGgufSource.rows, observedInventoryKeys.gguf, pendingForRender],
+  );
+  const cachedModelsReconciliation = useMemo(
+    () =>
+      reconcileInventoryHints({
+        pending: pendingForRender,
+        kind: "model",
+        rows: cachedModelsSource.rows,
+        previouslyObserved: observedInventoryKeys.model,
+      }),
+    [cachedModelsSource.rows, observedInventoryKeys.model, pendingForRender],
+  );
+  const cachedDatasetsReconciliation = useMemo(
+    () =>
+      reconcileInventoryHints({
+        pending: pendingForRender,
+        kind: "dataset",
+        rows: cachedDatasetsSource.rows,
+        previouslyObserved: observedInventoryKeys.dataset,
+      }),
+    [
+      cachedDatasetsSource.rows,
+      observedInventoryKeys.dataset,
+      pendingForRender,
+    ],
+  );
+
+  useEffect(() => {
+    const reconciliations: PendingHintReconciliationCommit[] = [];
+    if (!isDatasetMode) {
+      reconciliations.push(
+        {
+          kind: "gguf",
+          reconciliation: cachedGgufReconciliation,
+        },
+        {
+          kind: "model",
+          reconciliation: cachedModelsReconciliation,
+        },
+      );
+    }
+    if (isDatasetMode) {
+      reconciliations.push({
+        kind: "dataset",
+        reconciliation: cachedDatasetsReconciliation,
+      });
+    }
+    if (
+      completedHints.length === 0 &&
+      !reconciliations.some((commit) =>
+        pendingHintReconciliationNeedsCommit(
+          pendingForRender,
+          observedInventoryKeys,
+          commit,
+        ),
+      )
+    ) {
+      return;
+    }
+    const completedHintsToSuppress = commitPendingHintReconciliations(
+      completedHints,
+      pendingForRender,
+      reconciliations,
+    );
+    for (const hint of completedHintsToSuppress) {
+      clearCompletedInventoryHint(hint);
+    }
+  }, [
+    completedHints,
+    commitPendingHintReconciliations,
+    pendingForRender,
+    observedInventoryKeys,
+    isDatasetMode,
+    cachedGgufReconciliation,
+    cachedModelsReconciliation,
+    cachedDatasetsReconciliation,
+  ]);
+
+  const cachedGguf = cachedGgufReconciliation.rows;
+  const cachedModels = cachedModelsReconciliation.rows;
+  const cachedDatasets = cachedDatasetsReconciliation.rows;
+  const liveDownloadRows = useMemo(
+    () => liveDownloadInventoryRows(liveInventoryJobs, isDatasetMode),
+    [isDatasetMode, liveInventoryJobs],
+  );
+
+  const cachedModelRows = useMemo<CachedInventoryRow[]>(
+    () =>
+      [
+        ...(isDatasetMode ? [] : liveDownloadRows),
+        ...cachedGguf.map((row) => buildCachedInventoryRow(row, "gguf")),
+        ...cachedModels.map((row) =>
+          buildCachedInventoryRow(row, "safetensors"),
+        ),
+      ].sort(compareCachedRows),
+    [cachedGguf, cachedModels, isDatasetMode, liveDownloadRows],
+  );
+
+  const cachedDatasetRows = useMemo<CachedInventoryRow[]>(
+    () =>
+      [
+        ...(isDatasetMode ? liveDownloadRows : []),
+        ...cachedDatasets.map((row) => buildCachedInventoryRow(row, "unknown")),
+      ]
+        .sort(compareCachedRows),
+    [cachedDatasets, isDatasetMode, liveDownloadRows],
+  );
+
+  const localRows = useMemo(
+    () => buildLocalInventoryRows(localModelsSource.rows),
+    [localModelsSource.rows],
+  );
+
+  const localDatasetRows = useMemo<LocalInventoryRow[]>(() => {
+    return localDatasetsSource.rows
+      .map((ds: LocalDatasetInfo) => {
+        const repoId = ds.id.includes("/") ? ds.id : null;
+        const owner = repoId ? ds.id.split("/")[0] : "Local";
+        return {
+          kind: "local" as const,
+          id: ds.id,
+          repoId,
+          owner,
+          title: ds.label || ds.id,
+          source: "custom" as const,
+          sourceLabel: localDatasetSourceLabel(ds.source),
+          path: ds.path,
+          isGguf: false,
+          loadId: ds.id,
+          modelFormat: "unknown" as const,
+          runtime: "unknown" as const,
+          formatVariant: null,
+          capabilities: defaultCapabilities("unknown"),
+          updatedAt: normalizeTimestamp(ds.updated_at),
+        };
+      })
+      .sort((a, b) => a.title.localeCompare(b.title));
+  }, [localDatasetsSource.rows]);
+
+  const dedupedModelInventory = useMemo(
+    () =>
+      dedupeSameSourceHubCacheRows({
+        cachedRows: cachedModelRows,
+        localRows,
+      }),
+    [cachedModelRows, localRows],
+  );
+
+  const dedupedDatasetInventory = useMemo(
+    () =>
+      dedupeSameSourceHubCacheRows({
+        cachedRows: cachedDatasetRows,
+        localRows: localDatasetRows,
+      }),
+    [cachedDatasetRows, localDatasetRows],
+  );
+
+  const cachedRows = isDatasetMode
+    ? dedupedDatasetInventory.cachedRows
+    : dedupedModelInventory.cachedRows;
+  const effectiveLocalRows = isDatasetMode
+    ? dedupedDatasetInventory.localRows
+    : dedupedModelInventory.localRows;
+
+  const availableSet = useMemo(() => {
+    const set = new Set<string>();
+    for (const row of cachedRows) set.add(row.repoId.toLowerCase());
+    for (const row of effectiveLocalRows) {
+      if (row.repoId) set.add(row.repoId.toLowerCase());
+    }
+    return set;
+  }, [cachedRows, effectiveLocalRows]);
+
+  const partialSet = useMemo(() => {
+    return partialSetFromRows(
+      [...cachedRows, ...effectiveLocalRows],
+      (row) => row.repoId,
+    );
+  }, [cachedRows, effectiveLocalRows]);
+
+  const modelReady =
+    isReadyForDisplay(cachedGgufSource) &&
+    isReadyForDisplay(cachedModelsSource) &&
+    (!includeLocal || isReadyForDisplay(localModelsSource));
+  const datasetReady =
+    isReadyForDisplay(cachedDatasetsSource) &&
+    (!includeLocal || isReadyForDisplay(localDatasetsSource));
+  const inventoryFailed = isDatasetMode
+    ? Boolean(
+        cachedDatasetsSource.error ||
+          (includeLocal && localDatasetsSource.error),
+      )
+    : Boolean(
+        cachedGgufSource.error ||
+          cachedModelsSource.error ||
+          (includeLocal && localModelsSource.error),
+      );
+  const inventoryWarning =
+    inventoryFailed && (cachedRows.length > 0 || effectiveLocalRows.length > 0);
+
+  const refreshDeviceInventory = useCallback(async () => {
+    if (isDatasetMode) {
+      await Promise.all([
+        refreshDatasetInventory(),
+        ...(includeLocal ? [refreshLocalDatasetInventory()] : []),
+      ]);
+      return;
+    }
+    await Promise.all([
+      refreshModelInventory(),
+      ...(includeLocal ? [refreshLocalModelInventory()] : []),
+    ]);
+  }, [
+    includeLocal,
+    isDatasetMode,
+    refreshDatasetInventory,
+    refreshLocalDatasetInventory,
+    refreshLocalModelInventory,
+    refreshModelInventory,
+  ]);
+  const refreshInventory = useCallback(async () => {
+    await refreshDeviceInventory();
+  }, [refreshDeviceInventory]);
+  const downloadedReady = isDatasetMode ? datasetReady : modelReady;
+  const hasInventoryRows =
+    cachedRows.length > 0 || effectiveLocalRows.length > 0;
+  const hasActiveEmptyRefresh = isDatasetMode
+    ? cachedDatasetsSource.loading ||
+      (includeLocal && localDatasetsSource.loading)
+    : cachedGgufSource.loading ||
+      cachedModelsSource.loading ||
+      (includeLocal && localModelsSource.loading);
+  const emptyRevalidationSignature = useMemo(
+    () =>
+      isDatasetMode
+        ? inventoryEmptyRevalidationSignature([
+            cachedDatasetsSource,
+            ...(includeLocal ? [localDatasetsSource] : []),
+          ])
+        : inventoryEmptyRevalidationSignature([
+            cachedGgufSource,
+            cachedModelsSource,
+            ...(includeLocal ? [localModelsSource] : []),
+          ]),
+    [
+      cachedDatasetsSource,
+      cachedGgufSource,
+      cachedModelsSource,
+      includeLocal,
+      isDatasetMode,
+      localDatasetsSource,
+      localModelsSource,
+    ],
+  );
+
+  useEffect(() => {
+    if (
+      !enabled ||
+      !downloadedReady ||
+      inventoryFailed ||
+      hasInventoryRows ||
+      hasActiveEmptyRefresh
+    ) {
+      return;
+    }
+    if (emptyRevalidationSignatureRef.current === emptyRevalidationSignature) {
+      return;
+    }
+    const timer = window.setTimeout(() => {
+      emptyRevalidationSignatureRef.current = emptyRevalidationSignature;
+      void refreshDeviceInventory();
+    }, 500);
+    return () => window.clearTimeout(timer);
+  }, [
+    downloadedReady,
+    emptyRevalidationSignature,
+    enabled,
+    hasActiveEmptyRefresh,
+    hasInventoryRows,
+    inventoryFailed,
+    refreshDeviceInventory,
+  ]);
+
+  return {
+    cachedRows,
+    localRows: effectiveLocalRows,
+    availableSet,
+    partialSet,
+    downloadedReady,
+    inventoryError: inventoryFailed,
+    inventoryWarning,
+    refreshInventory,
+  };
+}
diff --git a/studio/frontend/src/features/hub/inventory/view-models.ts b/studio/frontend/src/features/hub/inventory/view-models.ts
new file mode 100644
index 0000000000..63d70418be
--- /dev/null
+++ b/studio/frontend/src/features/hub/inventory/view-models.ts
@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { ownerOf, repoOf } from "../lib/format";
+import { looksLikeLocalPath } from "../lib/local-path";
+import { isGgufLike } from "../lib/model-identifiers";
+import type {
+  BackendModelCapabilities,
+  LocalModelInfo,
+  ModelInventoryFormat,
+  ModelInventoryRuntime,
+} from "./api";
+import type {
+  ModelInventoryCapabilities,
+  CachedInventoryRow,
+  LocalInventoryRow,
+} from "./types";
+
+export function localSourceLabel(source: LocalModelInfo["source"]): string {
+  switch (source) {
+    case "lmstudio":
+      return "LM Studio";
+    case "ollama":
+      return "Ollama";
+    case "custom":
+      return "Custom folder";
+    case "models_dir":
+      return "Models folder";
+    case "hf_cache":
+      return "HF Cache";
+    default:
+      return "Local model";
+  }
+}
+
+export function normalizeTimestamp(value?: number | null): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return null;
+  }
+  return value < 10_000_000_000 ? value * 1000 : value;
+}
+
+export function formatLocalUpdated(value?: number | null): string {
+  const normalized = normalizeTimestamp(value);
+  if (!normalized) return "Unknown update";
+  const formatter = new Intl.DateTimeFormat("en", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+  return formatter.format(new Date(normalized));
+}
+
+function getLocalHubId(model: LocalModelInfo): string | null {
+  if (model.source !== "hf_cache") return null;
+  const candidate = model.model_id?.trim();
+  if (candidate?.toLowerCase().startsWith("ollama/")) {
+    return null;
+  }
+  if (candidate && candidate.includes("/") && !looksLikeLocalPath(candidate)) {
+    return candidate;
+  }
+  return null;
+}
+
+function getBaseModelHubId(model: LocalModelInfo): string | null {
+  const baseModel = model.base_model?.trim();
+  return model.base_model_source === "huggingface" && baseModel
+    ? baseModel
+    : null;
+}
+
+function isOllamaInventoryModel(model: LocalModelInfo): boolean {
+  return (
+    model.source === "ollama" ||
+    model.id.toLowerCase().startsWith("ollama-manifest:") ||
+    (model.model_id?.toLowerCase().startsWith("ollama/") ?? false)
+  );
+}
+
+export function normalizeModelFormat(
+  value: string | null | undefined,
+  fallback: ModelInventoryFormat = "unknown",
+): ModelInventoryFormat {
+  if (
+    value === "gguf" ||
+    value === "safetensors" ||
+    value === "adapter" ||
+    value === "checkpoint" ||
+    value === "unknown"
+  ) {
+    return value;
+  }
+  return fallback;
+}
+
+export function normalizeRuntime(
+  value: string | null | undefined,
+  modelFormat: ModelInventoryFormat,
+): ModelInventoryRuntime {
+  if (
+    value === "llama_cpp" ||
+    value === "transformers" ||
+    value === "adapter" ||
+    value === "unknown"
+  ) {
+    return value;
+  }
+  if (modelFormat === "gguf") return "llama_cpp";
+  if (modelFormat === "adapter") return "adapter";
+  if (modelFormat === "safetensors" || modelFormat === "checkpoint") {
+    return "transformers";
+  }
+  return "unknown";
+}
+
+export function defaultCapabilities(
+  modelFormat: ModelInventoryFormat,
+  partial = false,
+  requiresVariant = false,
+): ModelInventoryCapabilities {
+  const complete = !partial;
+  const canChat =
+    complete &&
+    (modelFormat === "gguf" ||
+      modelFormat === "safetensors" ||
+      modelFormat === "adapter" ||
+      modelFormat === "checkpoint");
+  return {
+    canTrain:
+      complete &&
+      (modelFormat === "safetensors" || modelFormat === "checkpoint"),
+    canChat,
+    canDelete: false,
+    canDownload: false,
+    requiresVariant,
+    supportsLora:
+      complete &&
+      (modelFormat === "safetensors" || modelFormat === "checkpoint"),
+    supportsVision: false,
+  };
+}
+
+export function normalizeCapabilities(
+  value: BackendModelCapabilities | null | undefined,
+  modelFormat: ModelInventoryFormat,
+  partial = false,
+  requiresVariant = false,
+): ModelInventoryCapabilities {
+  const fallback = defaultCapabilities(modelFormat, partial, requiresVariant);
+  return {
+    canTrain: value?.can_train ?? fallback.canTrain,
+    canChat: value?.can_chat ?? fallback.canChat,
+    canDelete: value?.can_delete ?? fallback.canDelete,
+    canDownload: value?.can_download ?? fallback.canDownload,
+    requiresVariant: value?.requires_variant ?? fallback.requiresVariant,
+    supportsLora: value?.supports_lora ?? fallback.supportsLora,
+    supportsVision: value?.supports_vision ?? fallback.supportsVision,
+  };
+}
+
+export function buildCachedInventoryRow(
+  row: {
+    repo_id: string;
+    size_bytes: number;
+    cache_path?: string;
+    partial?: boolean;
+    partial_transport?: string | null;
+    pipeline_tag?: string | null;
+    tags?: string[];
+    library_name?: string | null;
+    quant_method?: string | null;
+    inventory_id?: string | null;
+    load_id?: string | null;
+    model_format?: ModelInventoryFormat | null;
+    runtime?: string | null;
+    format_variant?: string | null;
+    capabilities?: BackendModelCapabilities | null;
+  },
+  fallbackFormat: ModelInventoryFormat,
+): CachedInventoryRow {
+  const rawModelFormat = normalizeModelFormat(row.model_format, "unknown");
+  const modelFormat =
+    rawModelFormat === "unknown" ? fallbackFormat : rawModelFormat;
+  const inferredFromEndpoint =
+    rawModelFormat === "unknown" && modelFormat !== "unknown";
+  const requiresVariant = modelFormat === "gguf";
+  return {
+    kind: "cache",
+    id:
+      !inferredFromEndpoint && row.inventory_id
+        ? row.inventory_id
+        : `cache:${modelFormat}:${row.repo_id}`,
+    loadId: row.load_id ?? row.repo_id,
+    repoId: row.repo_id,
+    owner: row.repo_id.includes("/") ? ownerOf(row.repo_id) : "Hub",
+    repo: row.repo_id.includes("/") ? repoOf(row.repo_id) : row.repo_id,
+    isGguf: modelFormat === "gguf",
+    modelFormat,
+    runtime: normalizeRuntime(
+      inferredFromEndpoint ? null : row.runtime,
+      modelFormat,
+    ),
+    formatVariant: row.format_variant ?? null,
+    capabilities: normalizeCapabilities(
+      inferredFromEndpoint ? null : row.capabilities,
+      modelFormat,
+      row.partial ?? false,
+      requiresVariant,
+    ),
+    bytes: row.size_bytes,
+    cachePath: row.cache_path ?? null,
+    partial: row.partial ?? false,
+    partialTransport: row.partial_transport ?? null,
+    pipelineTag: row.pipeline_tag ?? null,
+    tags: row.tags,
+    libraryName: row.library_name ?? null,
+    quantMethod: row.quant_method ?? null,
+  };
+}
+
+function sourceSortWeight(source: LocalModelInfo["source"]): number {
+  switch (source) {
+    case "models_dir":
+      return 0;
+    case "custom":
+      return 1;
+    case "lmstudio":
+      return 2;
+    case "ollama":
+      return 3;
+    case "hf_cache":
+      return 4;
+    default:
+      return 5;
+  }
+}
+
+export function buildLocalInventoryRows(
+  models: LocalModelInfo[],
+): LocalInventoryRow[] {
+  return models
+    .map((model) => {
+      const repoId = getLocalHubId(model);
+      const baseModel = model.base_model?.trim() || null;
+      const owner = repoId ? ownerOf(repoId) : localSourceLabel(model.source);
+      const title = repoId ? repoOf(repoId) : model.display_name;
+      const fallbackIsGguf =
+        isOllamaInventoryModel(model) ||
+        isGgufLike(model.path) ||
+        isGgufLike(model.id) ||
+        isGgufLike(model.model_id) ||
+        isGgufLike(model.display_name);
+      const modelFormat = normalizeModelFormat(
+        model.model_format,
+        fallbackIsGguf ? "gguf" : "unknown",
+      );
+      const fallbackRequiresVariant =
+        modelFormat === "gguf" && !model.path.toLowerCase().endsWith(".gguf");
+      const capabilities = normalizeCapabilities(
+        model.capabilities,
+        modelFormat,
+        model.partial ?? false,
+        fallbackRequiresVariant,
+      );
+      return {
+        kind: "local" as const,
+        id: model.inventory_id ?? model.id,
+        loadId: model.load_id ?? model.id,
+        repoId,
+        owner,
+        title,
+        source: model.source,
+        sourceLabel: localSourceLabel(model.source),
+        path: model.path,
+        isGguf: modelFormat === "gguf",
+        modelFormat,
+        runtime: normalizeRuntime(model.runtime, modelFormat),
+        formatVariant: model.format_variant ?? null,
+        capabilities,
+        baseModel,
+        baseModelSource: model.base_model_source ?? null,
+        baseModelHubId: getBaseModelHubId(model),
+        adapterType: model.adapter_type ?? null,
+        trainingMethod: model.training_method ?? null,
+        updatedAt: normalizeTimestamp(model.updated_at),
+        partial: model.partial ?? false,
+        partialTransport: model.partial_transport ?? null,
+        pipelineTag: model.pipeline_tag ?? null,
+        tags: model.tags,
+        libraryName: model.library_name ?? null,
+        quantMethod: model.quant_method ?? null,
+      };
+    })
+    .sort((a, b) => {
+      if (Boolean(a.partial) !== Boolean(b.partial)) return a.partial ? 1 : -1;
+      const sourceWeight = sourceSortWeight(a.source) - sourceSortWeight(b.source);
+      if (sourceWeight !== 0) return sourceWeight;
+      if (a.updatedAt && b.updatedAt && a.updatedAt !== b.updatedAt) {
+        return b.updatedAt - a.updatedAt;
+      }
+      return a.title.localeCompare(b.title);
+    });
+}
diff --git a/studio/frontend/src/features/hub/lib/abort-signals.ts b/studio/frontend/src/features/hub/lib/abort-signals.ts
new file mode 100644
index 0000000000..fbd00990a7
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/abort-signals.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// WebView-compatibility shims. AbortSignal.timeout (WebKitGTK < 2.38) and
+// AbortSignal.any (WebKitGTK < 2.44) are missing on older engines Tauri embeds
+// and throw synchronously if called. These ponyfills delegate to the native
+// impl when present, else fall back to an AbortController.
+
+export interface PollSignal {
+  signal: AbortSignal;
+  dispose: () => void;
+}
+
+// Timeout signal paired with a disposer. On the ponyfill path the setTimeout
+// pins the controller until it fires, so callers settling early MUST dispose.
+export function disposableTimeoutSignal(ms: number): PollSignal {
+  if (typeof AbortSignal.timeout === "function") {
+    return { signal: AbortSignal.timeout(ms), dispose: () => {} };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () =>
+      controller.abort(
+        new DOMException("The operation timed out.", "TimeoutError"),
+      ),
+    ms,
+  );
+  return { signal: controller.signal, dispose: () => clearTimeout(timer) };
+}
+
+export function timeoutSignal(ms: number): AbortSignal {
+  return disposableTimeoutSignal(ms).signal;
+}
+
+// Callers MUST dispose() once the request settles so abort listeners don't pile up.
+export function combineAbortSignals(signals: AbortSignal[]): PollSignal {
+  if (typeof AbortSignal.any === "function") {
+    return { signal: AbortSignal.any(signals), dispose: () => {} };
+  }
+  const controller = new AbortController();
+  const detachers: Array<() => void> = [];
+  const dispose = () => {
+    while (detachers.length > 0) {
+      detachers.pop()?.();
+    }
+  };
+  const abort = (reason: unknown) => {
+    if (!controller.signal.aborted) controller.abort(reason);
+    dispose();
+  };
+  for (const input of signals) {
+    if (input.aborted) {
+      abort(input.reason);
+      break;
+    }
+    const handler = () => abort(input.reason);
+    input.addEventListener("abort", handler, { once: true });
+    detachers.push(() => input.removeEventListener("abort", handler));
+  }
+  return { signal: controller.signal, dispose };
+}
+
+export function pollSignal(parent: AbortSignal, timeoutMs: number): PollSignal {
+  const timeout = disposableTimeoutSignal(timeoutMs);
+  const combined = combineAbortSignals([parent, timeout.signal]);
+  return {
+    signal: combined.signal,
+    dispose: () => {
+      combined.dispose();
+      timeout.dispose();
+    },
+  };
+}
+
+export function abortError(signal: AbortSignal): DOMException {
+  return signal.reason instanceof DOMException
+    ? signal.reason
+    : new DOMException("The operation was aborted.", "AbortError");
+}
+
+// Rejects the returned promise on abort but never aborts the wrapped promise,
+// so a request shared across callers keeps running when one caller's signal fires.
+export function withAbort<T>(
+  promise: Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener("abort", onAbort);
+    });
+  });
+}
diff --git a/studio/frontend/src/features/hub/lib/channels.ts b/studio/frontend/src/features/hub/lib/channels.ts
new file mode 100644
index 0000000000..25f8b660ea
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/channels.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  NewReleasesIcon,
+  SlidersHorizontalIcon,
+  SparklesIcon,
+} from "@hugeicons/core-free-icons";
+import type { IconSvgElement } from "@hugeicons/react";
+import type { HfSortKey } from "@/features/hub/hooks/use-hub-model-search";
+import type { ModelFormatFilter } from "../types";
+
+export type ChannelId =
+  | "unsloth-trending"
+  | "unsloth-latest"
+  | "unsloth-safetensors";
+
+export interface ChannelPreset {
+  id: ChannelId;
+  label: string;
+  icon: IconSvgElement;
+  hint: string;
+  owner?: string;
+  tags?: readonly string[];
+  query?: string;
+  idSuffix?: string;
+  format: ModelFormatFilter;
+  sort: HfSortKey;
+}
+
+export const CHANNEL_PRESETS: readonly ChannelPreset[] = [
+  {
+    id: "unsloth-trending",
+    label: "Unsloth Trending",
+    icon: SparklesIcon,
+    hint: "Most trending models published by Unsloth.",
+    owner: "unsloth",
+    format: "gguf",
+    sort: "trendingScore",
+  },
+  {
+    id: "unsloth-latest",
+    label: "Latest Unsloth",
+    icon: NewReleasesIcon,
+    hint: "Freshly released models from the Unsloth channel.",
+    owner: "unsloth",
+    format: "all",
+    sort: "lastModified",
+  },
+  {
+    id: "unsloth-safetensors",
+    label: "Fine-tune ready",
+    icon: SlidersHorizontalIcon,
+    hint: "Latest Unsloth bnb-4bit checkpoints ready to fine-tune.",
+    owner: "unsloth",
+    query: "bnb-4bit",
+    idSuffix: "-bnb-4bit",
+    format: "checkpoint",
+    sort: "lastModified",
+  },
+];
+
+export function findChannel(id: ChannelId | null): ChannelPreset | null {
+  if (!id) return null;
+  return CHANNEL_PRESETS.find((preset) => preset.id === id) ?? null;
+}
diff --git a/studio/frontend/src/features/hub/lib/dataset-size.ts b/studio/frontend/src/features/hub/lib/dataset-size.ts
new file mode 100644
index 0000000000..76ac12d2d6
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/dataset-size.ts
@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { LruMap } from "./lru-map";
+import { fetchWithTimeout } from "./network";
+import { fingerprintToken } from "./token-fingerprint";
+
+export interface DatasetSizeInfo {
+  numBytesOriginal: number | null;
+  numBytesParquet: number | null;
+  numRows: number | null;
+  numSplits: number | null;
+}
+
+interface DatasetSizeApiResponse {
+  size?: {
+    dataset?: {
+      num_bytes_original_files?: number;
+      num_bytes_parquet_files?: number;
+      num_rows?: number;
+    };
+    splits?: unknown[];
+  };
+}
+
+// Transient (429/5xx/network) misses cache briefly so a rate-limited burst
+// doesn't pin the size to "unknown" until reload. "longlived" covers stable-ish
+// answers like datasets-server 404 ("not processed yet"); "permanent" is a
+// genuinely missing repo (HF models API 404).
+const TRANSIENT_MISS_TTL_MS = 60_000;
+const LONGLIVED_MISS_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+
+type SizeCacheEntry<T> =
+  | { kind: "value"; value: T }
+  | { kind: "miss-permanent" }
+  | { kind: "miss-transient"; until: number };
+
+type LoadResult<T> =
+  | { value: T }
+  | { miss: "permanent" | "transient" | "longlived" };
+
+type InflightSizeEntry<T> = {
+  promise: Promise<T | null>;
+  controller: AbortController;
+  consumers: number;
+  settled: boolean;
+  cancelledByConsumers: boolean;
+};
+
+function readSizeCache<T>(
+  cache: LruMap<string, SizeCacheEntry<T>>,
+  key: string,
+): SizeCacheEntry<T> | null {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (entry.kind === "miss-transient" && Date.now() >= entry.until) {
+    cache.delete(key);
+    return null;
+  }
+  return entry;
+}
+
+function fetchCachedSize<T>(
+  cacheKey: string,
+  cache: LruMap<string, SizeCacheEntry<T>>,
+  inflight: Map<string, InflightSizeEntry<T>>,
+  load: (signal: AbortSignal) => Promise<LoadResult<T>>,
+  debugContext: { label: string; id: string },
+  signal?: AbortSignal,
+): Promise<T | null> {
+  if (signal?.aborted) {
+    return Promise.resolve(null);
+  }
+  const entry = readSizeCache(cache, cacheKey);
+  if (entry) {
+    return Promise.resolve(entry.kind === "value" ? entry.value : null);
+  }
+  const existing = inflight.get(cacheKey);
+  if (existing) return attachInflight(existing, signal);
+
+  let timedOut = false;
+  const controller = new AbortController();
+  const inflightEntry: InflightSizeEntry<T> = {
+    promise: Promise.resolve(null),
+    controller,
+    consumers: 0,
+    settled: false,
+    cancelledByConsumers: false,
+  };
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, FETCH_TIMEOUT_MS);
+
+  inflightEntry.promise = (async (): Promise<T | null> => {
+    try {
+      const result = await load(controller.signal);
+      if ("value" in result) {
+        cache.set(cacheKey, { kind: "value", value: result.value });
+        return result.value;
+      }
+      if (result.miss === "permanent") {
+        cache.set(cacheKey, { kind: "miss-permanent" });
+      } else {
+        const ttl =
+          result.miss === "longlived"
+            ? LONGLIVED_MISS_TTL_MS
+            : TRANSIENT_MISS_TTL_MS;
+        cache.set(cacheKey, {
+          kind: "miss-transient",
+          until: Date.now() + ttl,
+        });
+      }
+      return null;
+    } catch (err) {
+      if (
+        import.meta.env.DEV &&
+        (!inflightEntry.cancelledByConsumers || timedOut)
+      ) {
+        console.debug(`${debugContext.label} size lookup failed`, {
+          id: debugContext.id,
+          error: err,
+        });
+      }
+      if (!inflightEntry.cancelledByConsumers || timedOut) {
+        cache.set(cacheKey, {
+          kind: "miss-transient",
+          until: Date.now() + TRANSIENT_MISS_TTL_MS,
+        });
+      }
+      return null;
+    } finally {
+      clearTimeout(timeout);
+      inflightEntry.settled = true;
+      inflight.delete(cacheKey);
+    }
+  })();
+
+  inflight.set(cacheKey, inflightEntry);
+  return attachInflight(inflightEntry, signal);
+}
+
+function attachInflight<T>(
+  entry: InflightSizeEntry<T>,
+  signal?: AbortSignal,
+): Promise<T | null> {
+  entry.consumers += 1;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    entry.consumers = Math.max(0, entry.consumers - 1);
+    if (entry.consumers === 0 && !entry.settled) {
+      entry.cancelledByConsumers = true;
+      entry.controller.abort();
+    }
+  };
+
+  if (!signal) {
+    return entry.promise.finally(release);
+  }
+
+  if (signal.aborted) {
+    release();
+    return Promise.resolve(null);
+  }
+
+  const activeSignal = signal;
+  return new Promise((resolve) => {
+    function cleanup() {
+      activeSignal.removeEventListener("abort", onAbort);
+    }
+    function onAbort() {
+      cleanup();
+      release();
+      resolve(null);
+    }
+    activeSignal.addEventListener("abort", onAbort, { once: true });
+    entry.promise.then(
+      (value) => {
+        cleanup();
+        release();
+        resolve(value);
+      },
+      () => {
+        cleanup();
+        release();
+        resolve(null);
+      },
+    );
+  });
+}
+
+const datasetCache = new LruMap<string, SizeCacheEntry<DatasetSizeInfo>>(128);
+const datasetInflight = new Map<string, InflightSizeEntry<DatasetSizeInfo>>();
+
+export function fetchDatasetSize(
+  repoId: string,
+  signal?: AbortSignal,
+): Promise<DatasetSizeInfo | null>;
+export function fetchDatasetSize(
+  repoId: string,
+  token?: string,
+  signal?: AbortSignal,
+): Promise<DatasetSizeInfo | null>;
+export function fetchDatasetSize(
+  repoId: string,
+  tokenOrSignal?: string | AbortSignal,
+  signal?: AbortSignal,
+): Promise<DatasetSizeInfo | null> {
+  const resolvedToken =
+    typeof tokenOrSignal === "string" ? tokenOrSignal : undefined;
+  const resolvedSignal =
+    signal ?? (typeof tokenOrSignal === "string" ? undefined : tokenOrSignal);
+  const cacheKey = `${repoId}::${fingerprintToken(resolvedToken)}`;
+  return fetchCachedSize<DatasetSizeInfo>(
+    cacheKey,
+    datasetCache,
+    datasetInflight,
+    async (signal) => {
+      const res = await fetchWithTimeout(
+        `https://datasets-server.huggingface.co/size?dataset=${encodeURIComponent(repoId)}`,
+        {
+          signal,
+          headers: resolvedToken
+            ? { Authorization: `Bearer ${resolvedToken}` }
+            : undefined,
+        },
+        FETCH_TIMEOUT_MS,
+      );
+      if (!res.ok) {
+        // datasets-server 404 often means "not processed yet", not "never".
+        return { miss: res.status === 404 ? "longlived" : "transient" };
+      }
+      const data = (await res.json()) as DatasetSizeApiResponse;
+      const ds = data.size?.dataset;
+      if (!ds) return { miss: "longlived" };
+      return {
+        value: {
+          numBytesOriginal: ds.num_bytes_original_files ?? null,
+          numBytesParquet: ds.num_bytes_parquet_files ?? null,
+          numRows: ds.num_rows ?? null,
+          numSplits: Array.isArray(data.size?.splits)
+            ? (data.size?.splits.length ?? null)
+            : null,
+        },
+      };
+    },
+    { label: "Dataset", id: repoId },
+    resolvedSignal,
+  );
+}
+
+export interface ModelSizeInfo {
+  totalBytes: number | null;
+  weightsBytes: number | null;
+}
+
+interface ModelInfoApiResponse {
+  siblings?: Array<{
+    rfilename?: string;
+    size?: number;
+  }>;
+}
+
+type ModelSibling = NonNullable<ModelInfoApiResponse["siblings"]>[number];
+
+const SNAPSHOT_WEIGHT_FILE_RE =
+  /\.(safetensors|bin|pt|pth|ckpt|h5|msgpack|npz)$/i;
+const SNAPSHOT_NON_BIN_WEIGHT_FILE_RE =
+  /\.(safetensors|pt|pth|ckpt|h5|msgpack|npz)$/i;
+const SNAPSHOT_BIN_WEIGHT_PREFIX_RE = /^(model|pytorch_model|adapter_model).*\.bin$/i;
+
+function basename(path: string): string {
+  return path.split("/").pop() ?? path;
+}
+
+function shipsTransformersWeights(siblings: ModelSibling[]): boolean {
+  return siblings.some((s) => {
+    const base = basename(s.rfilename ?? "").toLowerCase();
+    if (base.startsWith("consolidated")) return false;
+    return (
+      SNAPSHOT_NON_BIN_WEIGHT_FILE_RE.test(base) ||
+      SNAPSHOT_BIN_WEIGHT_PREFIX_RE.test(base)
+    );
+  });
+}
+
+function isSnapshotIgnored(
+  filename: string,
+  skipConsolidated: boolean,
+): boolean {
+  const lower = filename.toLowerCase();
+  return (
+    lower.endsWith(".gguf") ||
+    lower.endsWith(".onnx") ||
+    lower.startsWith("onnx/") ||
+    lower.startsWith("openvino/") ||
+    lower.startsWith("mlx/") ||
+    lower.endsWith(".bin.index.json.bak") ||
+    (skipConsolidated && lower.startsWith("consolidated"))
+  );
+}
+
+const modelCache = new LruMap<string, SizeCacheEntry<ModelSizeInfo>>(128);
+const modelInflight = new Map<string, InflightSizeEntry<ModelSizeInfo>>();
+
+export function fetchModelSize(
+  repoId: string,
+  token?: string,
+  signal?: AbortSignal,
+): Promise<ModelSizeInfo | null> {
+  const cacheKey = `${repoId}::${fingerprintToken(token)}`;
+  return fetchCachedSize<ModelSizeInfo>(
+    cacheKey,
+    modelCache,
+    modelInflight,
+    async (signal) => {
+      const path = repoId.split("/").map(encodeURIComponent).join("/");
+      const res = await fetchWithTimeout(
+        `https://huggingface.co/api/models/${path}?blobs=true`,
+        {
+          signal,
+          headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+        },
+        FETCH_TIMEOUT_MS,
+      );
+      if (!res.ok) {
+        return { miss: res.status === 404 ? "permanent" : "transient" };
+      }
+      const data = (await res.json()) as ModelInfoApiResponse;
+      const siblings = data.siblings ?? [];
+      const skipConsolidated = shipsTransformersWeights(siblings);
+      let total = 0;
+      let weights = 0;
+      for (const s of siblings) {
+        if (typeof s.size !== "number") continue;
+        const filename = s.rfilename ?? "";
+        if (filename && isSnapshotIgnored(filename, skipConsolidated)) continue;
+        total += s.size;
+        if (filename && SNAPSHOT_WEIGHT_FILE_RE.test(filename)) {
+          weights += s.size;
+        }
+      }
+      return {
+        value: {
+          totalBytes: total > 0 ? total : null,
+          weightsBytes: weights > 0 ? weights : null,
+        },
+      };
+    },
+    { label: "Model", id: repoId },
+    signal,
+  );
+}
diff --git a/studio/frontend/src/features/hub/lib/format-filters.ts b/studio/frontend/src/features/hub/lib/format-filters.ts
new file mode 100644
index 0000000000..0fb0d6e0bc
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/format-filters.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export type FormatFilterModelFormat =
+  | "gguf"
+  | "safetensors"
+  | "adapter"
+  | "checkpoint"
+  | "unknown";
+
+export type FormatFilterValue = "all" | "gguf" | "checkpoint";
+
+export function matchesFormat(
+  modelFormat: boolean | FormatFilterModelFormat | null | undefined,
+  formatFilter: FormatFilterValue,
+): boolean {
+  if (formatFilter === "all") return true;
+  const normalized =
+    typeof modelFormat === "boolean"
+      ? modelFormat
+        ? "gguf"
+        : "safetensors"
+      : modelFormat;
+  if (formatFilter === "gguf") return normalized === "gguf";
+  return normalized === "safetensors" || normalized === "checkpoint";
+}
diff --git a/studio/frontend/src/features/hub/lib/format.ts b/studio/frontend/src/features/hub/lib/format.ts
new file mode 100644
index 0000000000..862597ff95
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/format.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "N/A";
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = Math.min(
+    Math.max(Math.floor(Math.log(bytes) / Math.log(1000)), 0),
+    units.length - 1,
+  );
+  let value = bytes / 1000 ** i;
+  let decimals = i > 0 && Number(value.toFixed(1)) < 10 ? 1 : 0;
+  while (i < units.length - 1 && Number(value.toFixed(decimals)) >= 1000) {
+    i += 1;
+    value = bytes / 1000 ** i;
+    decimals = Number(value.toFixed(1)) < 10 ? 1 : 0;
+  }
+  return `${value.toFixed(decimals)} ${units[i]}`;
+}
+
+export function formatRate(bytesPerSec: number): string {
+  if (!Number.isFinite(bytesPerSec) || bytesPerSec <= 0) return "";
+  return `${formatBytes(bytesPerSec)}/s`;
+}
+
+export function formatEta(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds <= 0) return "";
+  const s = Math.round(seconds);
+  if (s < 60) return `${s}s left`;
+  if (s < 3600) {
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return rem ? `${m}m ${rem}s left` : `${m}m left`;
+  }
+  if (s < 86400) {
+    const h = Math.floor(s / 3600);
+    const rem = Math.floor((s % 3600) / 60);
+    return rem ? `${h}h ${rem}m left` : `${h}h left`;
+  }
+  const d = Math.floor(s / 86400);
+  const rem = Math.floor((s % 86400) / 3600);
+  return rem ? `${d}d ${rem}h left` : `${d}d left`;
+}
+
+export function ownerOf(id: string): string {
+  return id.includes("/") ? id.split("/")[0] : "";
+}
+
+export function repoOf(id: string): string {
+  return id.includes("/") ? id.split("/").slice(1).join("/") : id;
+}
+
+export function formatRelativeShort(iso?: string): string {
+  if (!iso) return "N/A";
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "N/A";
+  const diffMs = Math.max(0, Date.now() - then);
+  const minutes = Math.floor(diffMs / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  if (days < 365) {
+    const months = Math.floor(days / 30);
+    return `${months}mo ago`;
+  }
+  const years = Math.floor(days / 365);
+  return `${years}y ago`;
+}
diff --git a/studio/frontend/src/features/hub/lib/gguf-fit.ts b/studio/frontend/src/features/hub/lib/gguf-fit.ts
new file mode 100644
index 0000000000..8f89b806b1
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/gguf-fit.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/**
+ * Single source of truth for "will this GGUF fit on the user's GPU?". Mirrors the
+ * backend's GPU selection (llama_cpp.py `_select_gpus`): 90% of GPU memory for
+ * weights + KV cache, else `--fit` CPU offload. One formula so the Hub card and
+ * chat picker can't disagree.
+ */
+
+export type GgufFitClass = "fits" | "marginal" | "partial" | "ram" | "oom";
+
+export interface GgufFitInput {
+  gpuGb?: number;
+  systemRamGb?: number;
+}
+
+/** Fraction of GPU VRAM treated as usable, matching the backend's 0.90 budget. */
+const VRAM_HEADROOM_RATIO = 0.9;
+/** GGUF weights are file size; runtime activations add roughly this fraction. */
+const ACTIVATIONS_RATIO = 0.15;
+/** Flat KV/context allowance at a typical 4K window. */
+const CONTEXT_OVERHEAD_GB = 1.0;
+/** Conservative share of system RAM usable for CPU offload. */
+const RAM_OFFLOAD_USABLE_RATIO = 0.5;
+
+export function requiredGgufMemoryGb(
+  sizeBytes: number,
+  contextOverheadGb = CONTEXT_OVERHEAD_GB,
+): number {
+  const sizeGb = sizeBytes / 1024 ** 3;
+  return sizeGb * (1 + ACTIVATIONS_RATIO) + contextOverheadGb;
+}
+
+export function classifyGgufFit(
+  sizeBytes: number,
+  { gpuGb, systemRamGb }: GgufFitInput,
+): GgufFitClass {
+  const required = requiredGgufMemoryGb(sizeBytes);
+  if (!gpuGb || gpuGb <= 0) {
+    const ramBudget = (systemRamGb ?? 0) * RAM_OFFLOAD_USABLE_RATIO;
+    return required <= ramBudget ? "ram" : "oom";
+  }
+  const budget = gpuGb * VRAM_HEADROOM_RATIO;
+  if (required <= budget) return "fits";
+  if (required <= gpuGb) return "marginal";
+  const combined = gpuGb + (systemRamGb ?? 0) * RAM_OFFLOAD_USABLE_RATIO;
+  if (required <= combined) return "partial";
+  return "oom";
+}
+
diff --git a/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts b/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
new file mode 100644
index 0000000000..3fe9e040d9
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/gguf-variant-sort.ts
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { GgufVariantDetail } from "@/features/hub/inventory";
+import { classifyGgufFit } from "@/features/hub/lib/gguf-fit";
+import { ggufVariantsMatch } from "@/features/hub/lib/model-identity";
+
+type GgufVariantResources = {
+  gpuGb?: number;
+  systemRamGb?: number;
+};
+
+export function ggufVariantDisplayLabel(
+  variant: Pick<GgufVariantDetail, "display_label" | "quant">,
+): string {
+  return variant.display_label?.trim() || variant.quant;
+}
+
+export function ggufVariantDownloadSizeBytes(
+  variant: Pick<GgufVariantDetail, "download_size_bytes" | "size_bytes">,
+): number {
+  return variant.download_size_bytes ?? variant.size_bytes;
+}
+
+export function ggufVariantFitRank(
+  variant: GgufVariantDetail,
+  resources: GgufVariantResources,
+): number {
+  switch (classifyGgufFit(variant.size_bytes, resources)) {
+    case "fits":
+      return 0;
+    case "marginal":
+      return 1;
+    case "partial":
+    case "ram":
+      return 2;
+    default:
+      return 3;
+  }
+}
+
+export function compareGgufVariantFitAndSize(
+  a: GgufVariantDetail,
+  b: GgufVariantDetail,
+  resources: GgufVariantResources,
+): number {
+  const aFit = ggufVariantFitRank(a, resources);
+  const bFit = ggufVariantFitRank(b, resources);
+  if (aFit !== bFit) return aFit - bFit;
+  return aFit === 3 ? a.size_bytes - b.size_bytes : b.size_bytes - a.size_bytes;
+}
+
+export function ggufVariantDownloadStatusRank(
+  variant: GgufVariantDetail,
+): number {
+  if (variant.downloaded) return 0;
+  if (variant.partial) return 1;
+  return 2;
+}
+
+export function sortDownloadableGgufVariants(
+  variants: readonly GgufVariantDetail[],
+  resources: GgufVariantResources,
+): GgufVariantDetail[] {
+  return [...variants].sort((a, b) => {
+    const statusDelta =
+      ggufVariantDownloadStatusRank(a) - ggufVariantDownloadStatusRank(b);
+    if (statusDelta !== 0) return statusDelta;
+    return compareGgufVariantFitAndSize(a, b, resources);
+  });
+}
+
+export function sortLocalGgufVariants(
+  variants: readonly GgufVariantDetail[],
+  options: GgufVariantResources & {
+    activeGgufVariant?: string | null;
+    defaultVariant?: string | null;
+  },
+): GgufVariantDetail[] {
+  return [...variants].sort((a, b) => {
+    const aActive = ggufVariantsMatch(a.quant, options.activeGgufVariant);
+    const bActive = ggufVariantsMatch(b.quant, options.activeGgufVariant);
+    if (aActive !== bActive) return aActive ? -1 : 1;
+    const aDefault = ggufVariantsMatch(a.quant, options.defaultVariant);
+    const bDefault = ggufVariantsMatch(b.quant, options.defaultVariant);
+    if (aDefault !== bDefault) return aDefault ? -1 : 1;
+    return compareGgufVariantFitAndSize(a, b, options);
+  });
+}
diff --git a/studio/frontend/src/features/hub/lib/hf-cache.ts b/studio/frontend/src/features/hub/lib/hf-cache.ts
new file mode 100644
index 0000000000..f2cab8b2ca
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hf-cache.ts
@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { type ModelEntry, modelInfo } from "@huggingface/hub";
+
+import { LruMap } from "./lru-map";
+import { fingerprintToken } from "./token-fingerprint";
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const CACHE_MAX_ENTRIES = 256;
+const MAX_CONCURRENT = 3;
+const ALL_FIELDS: ("safetensors" | "tags")[] = ["safetensors", "tags"];
+
+export type CachedResult = ModelEntry & {
+  safetensors?: { total?: number; parameters?: Record<string, number> };
+  tags?: string[];
+};
+
+interface CacheEntry {
+  data: CachedResult;
+  ts: number;
+}
+
+const cache = new LruMap<string, CacheEntry>(CACHE_MAX_ENTRIES);
+const inflight = new Map<string, Promise<CachedResult>>();
+let active = 0;
+const waiting: Array<() => void> = [];
+
+function acquire(): Promise<void> {
+  if (active < MAX_CONCURRENT) {
+    active++;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) =>
+    waiting.push(() => {
+      active++;
+      resolve();
+    }),
+  );
+}
+
+function release() {
+  active--;
+  const next = waiting.shift();
+  if (next) next();
+}
+
+function isStale(key: string): boolean {
+  const hit = cache.get(key);
+  return !hit || Date.now() - hit.ts >= CACHE_TTL_MS;
+}
+
+function cacheKey(name: string, token: string | undefined): string {
+  return `${name}::${fingerprintToken(token)}`;
+}
+
+function extractToken(
+  params: Parameters<typeof modelInfo>[0],
+): string | undefined {
+  if (params.accessToken) return params.accessToken;
+  if (params.credentials && "accessToken" in params.credentials) {
+    return params.credentials.accessToken;
+  }
+  return undefined;
+}
+
+export function primeCacheFromListing(
+  name: string,
+  token: string | undefined,
+  data: CachedResult,
+): void {
+  if (!name) return;
+  const key = cacheKey(name, token);
+  if (!isStale(key)) return;
+  cache.set(key, { data, ts: Date.now() });
+}
+
+export async function cachedModelInfo(
+  params: Parameters<typeof modelInfo>[0],
+): Promise<CachedResult> {
+  const token = extractToken(params);
+  const key = cacheKey(params.name, token);
+  if (!isStale(key)) return cache.get(key)!.data;
+
+  const flying = inflight.get(key);
+  if (flying) return flying;
+
+  const promise = (async () => {
+    await acquire();
+    try {
+      const result = await modelInfo({
+        ...params,
+        additionalFields: ALL_FIELDS,
+      });
+      const entry = { data: result as CachedResult, ts: Date.now() };
+      cache.set(key, entry);
+      const typed = result as CachedResult & {
+        gated?: false | "auto" | "manual";
+        private?: boolean;
+      };
+      if (token && !typed.private && !typed.gated) {
+        const anonKey = cacheKey(params.name, undefined);
+        if (isStale(anonKey)) cache.set(anonKey, entry);
+      }
+      return result as CachedResult;
+    } finally {
+      release();
+      inflight.delete(key);
+    }
+  })();
+
+  inflight.set(key, promise);
+  return promise;
+}
diff --git a/studio/frontend/src/features/hub/lib/hf-model-meta.ts b/studio/frontend/src/features/hub/lib/hf-model-meta.ts
new file mode 100644
index 0000000000..a390516fbf
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hf-model-meta.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export const EMBEDDING_TAGS: ReadonlySet<string> = new Set([
+  "feature-extraction",
+  "sentence-transformers",
+  "sentence-similarity",
+  "text-embeddings-inference",
+  "embeddings",
+]);
+
+export const DTYPE_BYTES: Readonly<Record<string, number>> = {
+  F64: 8,
+  F32: 4,
+  F16: 2,
+  BF16: 2,
+  F8_E4M3: 1,
+  F8_E5M2: 1,
+  I64: 8,
+  U64: 8,
+  I32: 4,
+  U32: 4,
+  I16: 2,
+  U16: 2,
+  I8: 1,
+  U8: 1,
+  BOOL: 1,
+  NF4: 0.5,
+  FP4: 0.5,
+  INT4: 0.5,
+  GPTQ: 0.5,
+};
+
+export function estimateSizeFromDtypes(
+  params: Record<string, number> | undefined,
+): number | undefined {
+  if (!params) return undefined;
+  let total = 0;
+  for (const [dtype, count] of Object.entries(params)) {
+    const bytesPerParam = DTYPE_BYTES[dtype.toUpperCase()] ?? 2;
+    total += count * bytesPerParam;
+  }
+  return total > 0 ? total : undefined;
+}
+
+export { isGgufLike } from "@/features/hub/lib/model-identifiers";
diff --git a/studio/frontend/src/features/hub/lib/hf-owner-avatar.ts b/studio/frontend/src/features/hub/lib/hf-owner-avatar.ts
new file mode 100644
index 0000000000..e3871f4011
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hf-owner-avatar.ts
@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useEffect, useState } from "react";
+import { LruMap } from "@/features/hub/lib/lru-map";
+import { fetchWithTimeout } from "@/features/hub/lib/network";
+import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
+
+type AvatarCacheEntry =
+  | { kind: "url"; url: string; expiresAt: number }
+  | { kind: "miss-permanent" }
+  | { kind: "miss-transient"; until: number; failures: number };
+
+// Avatars rarely change; after this the cached URL is shown immediately, then
+// refreshed in the background and swapped if changed (stale-while-revalidate).
+const URL_TTL_MS = 24 * 60 * 60 * 1000;
+
+// Transient (429/5xx) avatar failures are negative-cached so they auto-recover.
+// Each consecutive failure doubles the retry delay up to a cap (a success
+// resets it); the backoff lives in the cache entry to survive virtualized-list churn.
+const TRANSIENT_MISS_BASE_TTL_MS = 60_000;
+const TRANSIENT_MISS_MAX_TTL_MS = 30 * 60_000;
+
+// Bound each fetch so a stalled connection can't hold a concurrency permit open
+// forever (which would hang every queued lookup); timeout is treated as transient.
+const AVATAR_FETCH_TIMEOUT_MS = 10_000;
+
+const cache = new LruMap<string, AvatarCacheEntry>(256);
+const inflight = new Map<string, Promise<string | null>>();
+
+// Cap concurrent avatar lookups so a fast scroll doesn't burst past the rate limit.
+const MAX_AVATAR_CONCURRENT = 6;
+let activeFetches = 0;
+const waiting: Array<() => void> = [];
+
+function acquire(): Promise<void> {
+  if (activeFetches < MAX_AVATAR_CONCURRENT) {
+    activeFetches++;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) =>
+    waiting.push(() => {
+      activeFetches++;
+      resolve();
+    }),
+  );
+}
+
+function release(): void {
+  activeFetches--;
+  waiting.shift()?.();
+}
+
+// Expired transient misses report "no entry" so the caller refetches, but the
+// entry is kept so its failure count can escalate the next backoff.
+function readCache(name: string): AvatarCacheEntry | null {
+  const entry = cache.get(name);
+  if (!entry) return null;
+  if (entry.kind === "miss-transient" && Date.now() >= entry.until) {
+    return null;
+  }
+  return entry;
+}
+
+function readCachedUrl(name: string): string | null {
+  if (!name) return null;
+  const entry = readCache(name);
+  return entry?.kind === "url" ? entry.url : null;
+}
+
+function transientMiss(name: string): AvatarCacheEntry {
+  const prev = cache.get(name);
+  const failures = prev?.kind === "miss-transient" ? prev.failures + 1 : 1;
+  const ttl = Math.min(
+    TRANSIENT_MISS_BASE_TTL_MS * 2 ** (failures - 1),
+    TRANSIENT_MISS_MAX_TTL_MS,
+  );
+  return { kind: "miss-transient", until: Date.now() + ttl, failures };
+}
+
+async function fetchAvatarUrl(
+  name: string,
+): Promise<{ url: string | null; transient: boolean }> {
+  const candidates = [
+    `https://huggingface.co/api/organizations/${encodeURIComponent(name)}/overview`,
+    `https://huggingface.co/api/users/${encodeURIComponent(name)}/overview`,
+  ];
+
+  let sawTransient = false;
+  for (const url of candidates) {
+    try {
+      const res = await fetchWithTimeout(
+        url,
+        {
+          credentials: "omit",
+        },
+        AVATAR_FETCH_TIMEOUT_MS,
+      );
+      if (res.ok) {
+        const data = (await res.json()) as { avatarUrl?: string };
+        if (data.avatarUrl) {
+          const resolved = data.avatarUrl.startsWith("http")
+            ? data.avatarUrl
+            : `https://huggingface.co${data.avatarUrl}`;
+          return { url: resolved, transient: false };
+        }
+        continue;
+      }
+      if (res.status === 404) {
+        continue;
+      }
+      sawTransient = true;
+    } catch {
+      sawTransient = true;
+    }
+  }
+  return { url: null, transient: sawTransient };
+}
+
+function loadAvatar(name: string): Promise<string | null> {
+  const existing = inflight.get(name);
+  if (existing) return existing;
+  const promise = acquire()
+    .then(() => fetchAvatarUrl(name))
+    .finally(release)
+    .then(
+      ({ url, transient }) => {
+        if (url) {
+          cache.set(name, { kind: "url", url, expiresAt: Date.now() + URL_TTL_MS });
+        } else if (transient) {
+          cache.set(name, transientMiss(name));
+        } else {
+          cache.set(name, { kind: "miss-permanent" });
+        }
+        inflight.delete(name);
+        return url;
+      },
+      () => {
+        cache.set(name, transientMiss(name));
+        inflight.delete(name);
+        return null;
+      },
+    );
+  inflight.set(name, promise);
+  return promise;
+}
+
+export function useHfOwnerAvatar(owner: string | null | undefined): string | null {
+  const key = owner?.trim() ?? "";
+  const online = useOnlineStatus();
+  const [state, setState] = useState<{ key: string; url: string | null }>(() => {
+    return { key, url: readCachedUrl(key) };
+  });
+  const url = state.key === key ? state.url : readCachedUrl(key);
+
+  useEffect(() => {
+    if (!key || !online) return;
+    let cancelled = false;
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const scheduleRetry = (until: number) => {
+      const wait = Math.max(until - Date.now(), 0) + 100;
+      retryTimer = setTimeout(() => {
+        if (!cancelled) void attempt();
+      }, wait);
+    };
+
+    const attempt = async () => {
+      const cached = readCache(key);
+      if (cached?.kind === "url") {
+        if (!cancelled) setState({ key, url: cached.url });
+        if (cached.expiresAt <= Date.now()) {
+          void loadAvatar(key).then((next) => {
+            if (!cancelled && next) setState({ key, url: next });
+          });
+        }
+        return;
+      }
+      if (cached?.kind === "miss-permanent") {
+        if (!cancelled) setState({ key, url: null });
+        return;
+      }
+      if (cached?.kind === "miss-transient") {
+        if (!cancelled) setState({ key, url: null });
+        scheduleRetry(cached.until);
+        return;
+      }
+      const next = await loadAvatar(key);
+      if (cancelled) return;
+      setState({ key, url: next });
+      if (next == null) {
+        const post = readCache(key);
+        if (post?.kind === "miss-transient") {
+          scheduleRetry(post.until);
+        }
+      }
+    };
+
+    void attempt();
+
+    return () => {
+      cancelled = true;
+      if (retryTimer != null) clearTimeout(retryTimer);
+    };
+  }, [key, online]);
+
+  return url;
+}
diff --git a/studio/frontend/src/features/hub/lib/hf-readme.ts b/studio/frontend/src/features/hub/lib/hf-readme.ts
new file mode 100644
index 0000000000..89cb5590dc
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hf-readme.ts
@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { LruMap } from "@/features/hub/lib/lru-map";
+import { fetchWithTimeout } from "@/features/hub/lib/network";
+import { fingerprintToken } from "@/features/hub/lib/token-fingerprint";
+import { defaultUrlTransform, type UrlTransform } from "streamdown";
+
+export type ReadmeKind = "model" | "dataset";
+
+export interface FetchedReadme {
+  markdown: string;
+  branch: "main" | "master";
+}
+
+interface ReadmeCacheEntry {
+  promise: Promise<FetchedReadme | null>;
+  // Epoch ms after which the result is refetched. 404s and transient failures
+  // are cached briefly (transient shorter) so absence/outage can recover;
+  // positive results and pending requests never expire within the session.
+  staleAt: number;
+}
+
+const cache = new LruMap<string, ReadmeCacheEntry>(64);
+
+// Bound each request so a stalled HF connection aborts and surfaces as a transient failure.
+const README_FETCH_TIMEOUT_MS = 10_000;
+const README_NEGATIVE_TTL_MS = 5 * 60_000;
+const README_TRANSIENT_TTL_MS = 30_000;
+
+function readmePrefix(kind: ReadmeKind): string {
+  return kind === "dataset" ? "datasets/" : "";
+}
+
+export function readmeBaseUrl(
+  repoId: string,
+  kind: ReadmeKind,
+  branch: "main" | "master" = "main",
+): string {
+  return `https://huggingface.co/${readmePrefix(kind)}${repoId}/resolve/${branch}/`;
+}
+
+async function fetchReadmeOnce(
+  repoId: string,
+  kind: ReadmeKind,
+  token: string | null,
+): Promise<FetchedReadme | null> {
+  const prefix = readmePrefix(kind);
+  const headers: HeadersInit = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  let transient = false;
+  for (const branch of ["main", "master"] as const) {
+    try {
+      const url = `https://huggingface.co/${prefix}${repoId}/raw/${branch}/README.md`;
+      const res = await fetchWithTimeout(
+        url,
+        {
+          mode: "cors",
+          headers,
+        },
+        README_FETCH_TIMEOUT_MS,
+      );
+      if (res.ok) {
+        return { markdown: await res.text(), branch };
+      }
+      if (res.status !== 404) transient = true;
+    } catch {
+      transient = true;
+    }
+  }
+  if (transient) {
+    throw new Error(`Failed to fetch README for ${repoId}`);
+  }
+  return null;
+}
+
+export function fetchReadme(
+  repoId: string,
+  kind: ReadmeKind = "model",
+  token: string | null = null,
+): Promise<FetchedReadme | null> {
+  const key = `${kind}::${repoId}::${fingerprintToken(token)}`;
+  const cached = cache.get(key);
+  if (cached && Date.now() < cached.staleAt) return cached.promise;
+
+  const entry: ReadmeCacheEntry = {
+    promise: Promise.resolve(null),
+    staleAt: Number.POSITIVE_INFINITY,
+  };
+  entry.promise = fetchReadmeOnce(repoId, kind, token)
+    .then((result) => {
+      if (result === null) entry.staleAt = Date.now() + README_NEGATIVE_TTL_MS;
+      return result;
+    })
+    .catch((err) => {
+      entry.staleAt = Date.now() + README_TRANSIENT_TTL_MS;
+      throw err;
+    });
+  cache.set(key, entry);
+  return entry.promise;
+}
+
+const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#|data:|mailto:|tel:)/i;
+const BLOCKED_README_PROTOCOLS = new Set(["javascript:", "vbscript:"]);
+
+function resolveAgainstBase(src: string, baseUrl: string): string {
+  if (!src) return src;
+  if (ABSOLUTE_URL_RE.test(src)) return src;
+  try {
+    return new URL(src, baseUrl).toString();
+  } catch {
+    return src;
+  }
+}
+
+function readmeUrlProtocol(src: string): string | null {
+  try {
+    return new URL(src, "https://huggingface.co").protocol.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function isBlockedReadmeUrl(
+  src: string,
+  node: Readonly<{ tagName?: unknown }>,
+): boolean {
+  const protocol = readmeUrlProtocol(src.trim());
+  if (!protocol) return false;
+  if (BLOCKED_README_PROTOCOLS.has(protocol)) return true;
+  if (protocol !== "data:") return false;
+  return String(node.tagName ?? "").toLowerCase() !== "img";
+}
+
+// Resolves relative asset URLs against the repo base, then delegates to
+// defaultUrlTransform so unsafe schemes (javascript:, etc.) stay stripped.
+export function createReadmeUrlTransform(baseUrl: string): UrlTransform {
+  return (url, key, node) => {
+    const resolved = resolveAgainstBase(url, baseUrl);
+    if (isBlockedReadmeUrl(resolved, node)) {
+      return undefined;
+    }
+    return defaultUrlTransform(resolved, key, node);
+  };
+}
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
+
+export function stripFrontmatter(markdown: string): {
+  body: string;
+  frontmatter: string | null;
+} {
+  const match = FRONTMATTER_RE.exec(markdown);
+  if (match) {
+    return {
+      body: markdown.slice(match[0].length),
+      frontmatter: match[1],
+    };
+  }
+  return { body: markdown, frontmatter: null };
+}
+
+/**
+ * Drop heading lines that duplicate the inspector's chrome (`# Model Card …`,
+ * standalone `Details` / `Model Card` / `Dataset Card`, etc.), since the page
+ * header already shows the repo name and section context.
+ */
+export function stripChromeHeadings(markdown: string): string {
+  const RE_HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+  const isChromeTitle = (text: string): boolean => {
+    const t = text
+      .toLowerCase()
+      .replace(/[*_`]/g, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    return (
+      t === "details" ||
+      t === "model card" ||
+      t === "dataset card" ||
+      t.startsWith("model card for") ||
+      t.startsWith("dataset card for") ||
+      t.startsWith("card for")
+    );
+  };
+
+  const lines = markdown.split(/\r?\n/);
+  const out: string[] = [];
+  for (const line of lines) {
+    const m = RE_HEADING.exec(line);
+    if (m && isChromeTitle(m[2])) continue;
+    out.push(line);
+  }
+  return out.join("\n");
+}
diff --git a/studio/frontend/src/features/hub/lib/hub-feature-flags.ts b/studio/frontend/src/features/hub/lib/hub-feature-flags.ts
new file mode 100644
index 0000000000..cf28403725
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hub-feature-flags.ts
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Hub feature flags for staged rollout. Each gates a CTA whose integration ships
+// in a later PR; JSX/wiring stay in place so flipping here is the only re-enable edit.
+
+// Post-download Run / chat / Train CTAs, hidden until the Hub-aware chat and train pickers ship.
+export const HUB_POST_DOWNLOAD_ACTIONS_VISIBLE = false;
diff --git a/studio/frontend/src/features/hub/lib/hub-token-header.ts b/studio/frontend/src/features/hub/lib/hub-token-header.ts
new file mode 100644
index 0000000000..27b5693eee
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/hub-token-header.ts
@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Internal Unsloth API header; direct Hugging Face calls use Authorization.
+
+export const HUB_HF_TOKEN_HEADER = "X-Unsloth-HF-Token";
+
+export function hubTokenHeader(
+  token?: string | null,
+): Record<string, string> {
+  return token ? { [HUB_HF_TOKEN_HEADER]: token } : {};
+}
diff --git a/studio/frontend/src/features/hub/lib/inventory-search.ts b/studio/frontend/src/features/hub/lib/inventory-search.ts
new file mode 100644
index 0000000000..dd9e12ae5f
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/inventory-search.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  matchTokens,
+  normalizeForSearch,
+  tokenizeQuery,
+} from "@/features/hub/lib/search-text";
+import type { CachedInventoryRow, LocalInventoryRow } from "../types";
+
+export { tokenizeQuery };
+
+function inventoryRowName(row: CachedInventoryRow | LocalInventoryRow): string {
+  return row.kind === "cache" ? row.repoId : row.title;
+}
+
+function inventoryRowHaystack(
+  row: CachedInventoryRow | LocalInventoryRow,
+): string {
+  if (row.kind === "cache")
+    return [
+      row.repoId,
+      row.modelFormat,
+      row.pipelineTag ?? "",
+      row.libraryName ?? "",
+      ...(row.tags ?? []),
+    ].join(" ");
+  return [
+    row.title,
+    row.owner,
+    row.sourceLabel,
+    row.path,
+    row.loadId,
+    row.modelFormat,
+    row.repoId ?? "",
+  ].join(" ");
+}
+
+export function inventoryRowMatches(
+  row: CachedInventoryRow | LocalInventoryRow,
+  tokens: readonly string[],
+): boolean {
+  if (tokens.length === 0) return true;
+  return matchTokens(inventoryRowHaystack(row), tokens);
+}
+
+export function scoreInventoryRow(
+  row: CachedInventoryRow | LocalInventoryRow,
+  tokens: readonly string[],
+): number {
+  if (tokens.length === 0) return 0;
+  const name = normalizeForSearch(inventoryRowName(row));
+  const haystack = normalizeForSearch(inventoryRowHaystack(row));
+  let score = 0;
+  for (const token of tokens) {
+    if (name.startsWith(token)) score += 3;
+    else if (name.includes(token)) score += 2;
+    else if (haystack.includes(token)) score += 1;
+    else return 0;
+  }
+  return score;
+}
diff --git a/studio/frontend/src/features/hub/lib/local-path.ts b/studio/frontend/src/features/hub/lib/local-path.ts
new file mode 100644
index 0000000000..aeb6a9a437
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/local-path.ts
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+const LOCAL_PATH_PREFIX_RE =
+  /^(?:\/|\.{1,2}(?:$|[\\/])|~(?:$|[\\/])|~[^\\/]+[\\/]|[A-Za-z]:[\\/]|\\\\)/;
+const WINDOWS_PATH_SEPARATOR_RE = /\\/g;
+const TRAILING_PATH_SEPARATOR_RE = /\/+$/;
+
+export function looksLikeLocalPath(input: string): boolean {
+  const value = input.trim();
+  return value.length > 0 && LOCAL_PATH_PREFIX_RE.test(value);
+}
+
+export function localPathCacheKey(path: string | null | undefined): string {
+  return (
+    path
+      ?.replace(WINDOWS_PATH_SEPARATOR_RE, "/")
+      .replace(TRAILING_PATH_SEPARATOR_RE, "") ?? ""
+  );
+}
diff --git a/studio/frontend/src/features/hub/lib/lru-map.ts b/studio/frontend/src/features/hub/lib/lru-map.ts
new file mode 100644
index 0000000000..348a255b50
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/lru-map.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/**
+ * Insertion-ordered map with a maximum size. Reads and writes move a key to
+ * the most-recent position; once over capacity the least-recently-used key is
+ * evicted. Bounds memory for module-level caches that live for the tab's
+ * lifetime (HF READMEs, dataset sizes, owner avatars).
+ */
+export class LruMap<K, V> {
+  private readonly map = new Map<K, V>();
+  private readonly max: number;
+
+  constructor(max: number) {
+    this.max = max;
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  get(key: K): V | undefined {
+    if (!this.map.has(key)) return undefined;
+    const value = this.map.get(key) as V;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > this.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== undefined) this.map.delete(oldest);
+    }
+  }
+
+  delete(key: K): void {
+    this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+/**
+ * Trim an insertion-ordered Set to `max` entries, evicting oldest-first but
+ * never an entry `isProtected` reports as still live. Protected entries are
+ * re-inserted at the back; `protectedScans` caps the walk at one full pass so
+ * a fully-protected set over capacity exits instead of looping forever.
+ */
+export function evictOldestUnprotected(
+  set: Set<string>,
+  max: number,
+  isProtected: (key: string) => boolean,
+): void {
+  let protectedScans = 0;
+  while (set.size > max && protectedScans < set.size) {
+    const oldest = set.values().next().value;
+    if (oldest === undefined) break;
+    if (isProtected(oldest)) {
+      set.delete(oldest);
+      set.add(oldest);
+      protectedScans += 1;
+      continue;
+    }
+    set.delete(oldest);
+    protectedScans = 0;
+  }
+}
diff --git a/studio/frontend/src/features/hub/lib/model-capabilities.ts b/studio/frontend/src/features/hub/lib/model-capabilities.ts
new file mode 100644
index 0000000000..bbfc2174df
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/model-capabilities.ts
@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { EMBEDDING_TAGS } from "./hf-model-meta";
+
+export type CapabilityKey =
+  | "vision"
+  | "audio"
+  | "tools"
+  | "reasoning"
+  | "code"
+  | "embedding"
+  | "multilingual";
+
+export interface Capability {
+  key: CapabilityKey;
+  label: string;
+}
+
+const VISION_TAGS = new Set([
+  "vision",
+  "vision-language",
+  "image-text-to-text",
+  "image-to-text",
+  "visual-question-answering",
+  "image-classification",
+  "image-segmentation",
+  "object-detection",
+  "any-to-any",
+  "multimodal",
+  "vlm",
+  "llava",
+]);
+
+const AUDIO_TAGS = new Set([
+  "audio",
+  "audio-text-to-text",
+  "automatic-speech-recognition",
+  "text-to-speech",
+  "audio-classification",
+  "voice-activity-detection",
+  "asr",
+  "tts",
+]);
+
+const TOOL_TAGS = new Set([
+  "tool-use",
+  "tools",
+  "tool-calling",
+  "function-calling",
+  "function-call",
+  "agent",
+  "agentic",
+]);
+
+const REASONING_TAGS = new Set([
+  "reasoning",
+  "thinking",
+  "chain-of-thought",
+  "math-reasoning",
+  "step-by-step",
+]);
+
+const CODE_TAGS = new Set([
+  "code",
+  "code-generation",
+  "code-completion",
+  "code-llm",
+  "programming",
+]);
+
+const COMMON_LANGUAGE_TAGS = new Set([
+  "en", "fr", "de", "es", "it", "pt", "nl", "ru", "pl", "uk", "tr", "cs",
+  "sv", "no", "da", "fi", "el", "ro", "bg", "hu", "hr", "sr", "sl", "sk",
+  "zh", "ja", "ko", "ar", "he", "fa", "hi", "bn", "ta", "te", "th", "vi",
+  "id", "ms", "tl", "sw", "ur", "ca", "eu", "is", "lv", "lt", "et",
+]);
+
+function lower(values: string[] | undefined): Set<string> {
+  if (!values) return new Set();
+  return new Set(values.map((v) => v.toLowerCase()));
+}
+
+export function detectCapabilities(
+  tags: string[] | undefined,
+  pipelineTag: string | undefined,
+  modelId: string,
+): Capability[] {
+  const tagSet = lower(tags);
+  const pipeline = pipelineTag?.toLowerCase();
+  const lowerId = modelId.toLowerCase();
+  const out: Capability[] = [];
+
+  const hasAny = (set: ReadonlySet<string>) => {
+    for (const t of set) {
+      if (tagSet.has(t)) return true;
+    }
+    return pipeline ? set.has(pipeline) : false;
+  };
+
+  if (
+    hasAny(VISION_TAGS) ||
+    /[-_/]vl[-_]|vision|multimodal|llava|kosmos|qwen2[-_]?vl|cogvlm/.test(
+      lowerId,
+    )
+  ) {
+    out.push({ key: "vision", label: "Vision" });
+  }
+  if (
+    hasAny(AUDIO_TAGS) ||
+    /audio|whisper|speech|tts|stt|asr|parler|sesame|bark|wav2vec|hubert|musicgen|speecht5|vocos|encodec|clap|ultravox|kyutai|moshi/.test(
+      lowerId,
+    )
+  ) {
+    out.push({ key: "audio", label: "Audio" });
+  }
+  if (hasAny(TOOL_TAGS) || /tool[-_]use|function[-_]call/.test(lowerId)) {
+    out.push({ key: "tools", label: "Tool use" });
+  }
+  if (
+    hasAny(REASONING_TAGS) ||
+    /think|reason|qwq|deepseek[-_]?r|gpt[-_]?oss|(?:^|[-_/])o1(?:[-_]|$)|nemotron[-_]reasoning/.test(
+      lowerId,
+    )
+  ) {
+    out.push({ key: "reasoning", label: "Reasoning" });
+  }
+  if (
+    hasAny(CODE_TAGS) ||
+    /(?:^|[-_/])coder(?:[-_/]|$)|(?:^|[-_/])code(?:[-_]|$)|starcoder|codellama|deepseek[-_]coder/.test(
+      lowerId,
+    )
+  ) {
+    out.push({ key: "code", label: "Code" });
+  }
+  if (
+    hasAny(EMBEDDING_TAGS) ||
+    /embed|embedding|retriever|reranker|bge[-_]|e5[-_]|gte[-_]|colbert|sentence[-_]?transformer|sentence[-_]?similarity|jina[-_]?embeddings?|nomic[-_]?embed|arctic[-_]?embed|qwen3[-_]?embedding|qwen3[-_]?reranker|text[-_]?embedding/.test(
+      lowerId,
+    )
+  ) {
+    out.push({ key: "embedding", label: "Embeddings" });
+  }
+  const languageCodes = new Set<string>();
+  for (const tag of tags ?? []) {
+    const lower = tag.toLowerCase();
+    const code = lower.startsWith("language:")
+      ? lower.slice("language:".length)
+      : lower;
+    if (COMMON_LANGUAGE_TAGS.has(code)) languageCodes.add(code);
+  }
+  if (tagSet.has("multilingual") || languageCodes.size >= 3) {
+    out.push({ key: "multilingual", label: "Multilingual" });
+  }
+  return out;
+}
+
+export function detectLicense(tags: string[] | undefined): string | null {
+  if (!tags) return null;
+  const license = tags.find((t) => t.startsWith("license:"));
+  return license ? license.slice("license:".length) : null;
+}
diff --git a/studio/frontend/src/features/hub/lib/model-identifiers.ts b/studio/frontend/src/features/hub/lib/model-identifiers.ts
new file mode 100644
index 0000000000..4c7b2031ec
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/model-identifiers.ts
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+const GGUF_REPO_SUFFIX_PATTERN = /-GGUF$/i;
+
+function normalizedLeaf(value: string): string {
+  const normalized = value.trim().replace(/[\\/]+$/, "");
+  return normalized.split(/[\\/]/).pop() ?? normalized;
+}
+
+export function hasGgufRepoSuffix(value: string | undefined | null): boolean {
+  if (!value) return false;
+  const leaf = normalizedLeaf(value);
+  return leaf.length > 0 && GGUF_REPO_SUFFIX_PATTERN.test(leaf);
+}
+
+export function isGgufFilename(value: string | undefined | null): boolean {
+  if (!value) return false;
+  return normalizedLeaf(value).toLowerCase().endsWith(".gguf");
+}
+
+export function isGgufLike(value: string | undefined | null): boolean {
+  return isGgufFilename(value) || hasGgufRepoSuffix(value);
+}
diff --git a/studio/frontend/src/features/hub/lib/model-identity.ts b/studio/frontend/src/features/hub/lib/model-identity.ts
new file mode 100644
index 0000000000..488502ae28
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/model-identity.ts
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { looksLikeLocalPath } from "./local-path.ts";
+
+const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
+const WSL_DRIVE_PATH_RE = /^\/mnt\/[A-Za-z](?:\/|$)/;
+
+function trimTrailingSeparators(path: string, minLength: number): string {
+  let end = path.length;
+  while (end > minLength && path.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return end === path.length ? path : path.slice(0, end);
+}
+
+function normalizeCaseInsensitivePath(path: string, minLength: number): string {
+  return trimTrailingSeparators(
+    path.replace(/\\/g, "/"),
+    minLength,
+  ).toLowerCase();
+}
+
+export function normalizeModelIdentity(modelId: string): string {
+  const trimmed = modelId.trim();
+  if (!looksLikeLocalPath(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+  const slashPath = trimmed.replace(/\\/g, "/");
+  if (WINDOWS_DRIVE_PATH_RE.test(trimmed)) {
+    return normalizeCaseInsensitivePath(trimmed, 3);
+  }
+  if (slashPath.startsWith("//")) {
+    return normalizeCaseInsensitivePath(trimmed, 2);
+  }
+  if (WSL_DRIVE_PATH_RE.test(slashPath)) {
+    return normalizeCaseInsensitivePath(trimmed, 6);
+  }
+  return trimmed;
+}
+
+export function normalizeGgufVariantIdentity(
+  ggufVariant?: string | null,
+): string {
+  return ggufVariant?.trim().toLowerCase() ?? "";
+}
+
+export function modelIdsMatch(
+  left: string | null | undefined,
+  right: string | null | undefined,
+): boolean {
+  if (!(left && right)) {
+    return false;
+  }
+  return normalizeModelIdentity(left) === normalizeModelIdentity(right);
+}
+
+export function ggufVariantsMatch(
+  left: string | null | undefined,
+  right: string | null | undefined,
+): boolean {
+  return (
+    normalizeGgufVariantIdentity(left) === normalizeGgufVariantIdentity(right)
+  );
+}
diff --git a/studio/frontend/src/features/hub/lib/network.ts b/studio/frontend/src/features/hub/lib/network.ts
new file mode 100644
index 0000000000..549af99fbc
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/network.ts
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export function isBrowserOffline(): boolean {
+  return isNavigatorOffline();
+}
+
+const NETWORK_STATUS_EVENT = "unsloth-network-status";
+const REMOTE_OFFLINE_TTL_MS = 30_000;
+const HUGGING_FACE_REMOTE_ORIGINS = [
+  "https://huggingface.co",
+  "https://datasets-server.huggingface.co",
+] as const;
+const noopUnsubscribe = () => undefined;
+
+type RemoteNetworkScope = string | readonly string[];
+
+const remoteOfflineUntilByOrigin = new Map<string, number>();
+
+function isNavigatorOffline(): boolean {
+  return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+
+function emitNetworkStatusChange(): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  window.dispatchEvent(new Event(NETWORK_STATUS_EVENT));
+}
+
+export function getBrowserOfflineRetryDelayMs(): number {
+  // Keyed off the empirical remote-offline TTL, not navigator.onLine, so recovery
+  // doesn't stall on platforms where navigator.onLine is stuck false.
+  return Math.max(
+    0,
+    getRemoteOfflineUntil(HUGGING_FACE_REMOTE_ORIGINS) - Date.now(),
+  );
+}
+
+function normalizeScope(scope: RemoteNetworkScope): readonly string[] {
+  return typeof scope === "string" ? [scope] : scope;
+}
+
+function getRemoteOfflineUntil(scope: RemoteNetworkScope): number {
+  const now = Date.now();
+  let until = 0;
+  for (const origin of normalizeScope(scope)) {
+    const value = remoteOfflineUntilByOrigin.get(origin) ?? 0;
+    if (value <= now) {
+      remoteOfflineUntilByOrigin.delete(origin);
+      continue;
+    }
+    until = Math.max(until, value);
+  }
+  return until;
+}
+
+export function isRemoteNetworkOffline(
+  scope: RemoteNetworkScope = HUGGING_FACE_REMOTE_ORIGINS,
+): boolean {
+  return getRemoteOfflineUntil(scope) > Date.now();
+}
+
+export function isHuggingFaceOffline(): boolean {
+  // navigator.onLine is advisory only (false-reports offline on WSL2 / some
+  // WebKitGTK/Tauri webviews). The authoritative signal is the empirical
+  // remote-offline TTL, set when a real fetch fails and cleared on next success.
+  return isRemoteNetworkOffline(HUGGING_FACE_REMOTE_ORIGINS);
+}
+
+export function markRemoteNetworkOnline(origin?: string): void {
+  if (origin === undefined) {
+    if (remoteOfflineUntilByOrigin.size === 0) {
+      return;
+    }
+    remoteOfflineUntilByOrigin.clear();
+    emitNetworkStatusChange();
+    return;
+  }
+  if (!remoteOfflineUntilByOrigin.delete(origin)) {
+    return;
+  }
+  emitNetworkStatusChange();
+}
+
+export function markRemoteNetworkOffline(
+  originOrTtl: string | number = HUGGING_FACE_REMOTE_ORIGINS[0],
+  ttlMs = REMOTE_OFFLINE_TTL_MS,
+): void {
+  const origin =
+    typeof originOrTtl === "string"
+      ? originOrTtl
+      : HUGGING_FACE_REMOTE_ORIGINS[0];
+  const ttl = typeof originOrTtl === "number" ? originOrTtl : ttlMs;
+  const nextUntil = Date.now() + ttl;
+  if (nextUntil <= (remoteOfflineUntilByOrigin.get(origin) ?? 0)) {
+    return;
+  }
+  remoteOfflineUntilByOrigin.set(origin, nextUntil);
+  emitNetworkStatusChange();
+}
+
+export function subscribeNetworkStatus(listener: () => void): () => void {
+  if (typeof window === "undefined") {
+    return noopUnsubscribe;
+  }
+  window.addEventListener("online", listener);
+  window.addEventListener("offline", listener);
+  window.addEventListener(NETWORK_STATUS_EVENT, listener);
+  return () => {
+    window.removeEventListener("online", listener);
+    window.removeEventListener("offline", listener);
+    window.removeEventListener(NETWORK_STATUS_EVENT, listener);
+  };
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function isNetworkFetchError(error: unknown): boolean {
+  if (isAbortError(error)) {
+    return false;
+  }
+  return error instanceof TypeError;
+}
+
+function originFromFetchInput(
+  input: Parameters<typeof fetch>[0],
+): string | null {
+  try {
+    const raw =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+    const base =
+      typeof window !== "undefined" ? window.location.href : "http://localhost";
+    return new URL(raw, base).origin;
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchWithTimeout(
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1] = {},
+  timeoutMs = 15_000,
+): Promise<Response> {
+  const parentSignal = init.signal;
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  const abortFromParent = () => controller.abort();
+
+  if (parentSignal?.aborted) {
+    abortFromParent();
+  } else {
+    parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+  }
+
+  const origin = originFromFetchInput(input);
+
+  try {
+    const response = await fetch(input, { ...init, signal: controller.signal });
+    if (origin) {
+      markRemoteNetworkOnline(origin);
+    }
+    return response;
+  } catch (error) {
+    if (timedOut) {
+      throw new Error("Request timed out");
+    }
+    if (origin && isNetworkFetchError(error)) {
+      markRemoteNetworkOffline(origin);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    parentSignal?.removeEventListener("abort", abortFromParent);
+  }
+}
diff --git a/studio/frontend/src/features/hub/lib/provider-logos.ts b/studio/frontend/src/features/hub/lib/provider-logos.ts
new file mode 100644
index 0000000000..d271351df3
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/provider-logos.ts
@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/**
+ * Provider-logo registry for Unsloth re-uploads. Unsloth re-uploads upstream
+ * models (e.g. unsloth/Qwen2.5-7B is Alibaba's Qwen); we render the upstream
+ * provider's logo in place of the Unsloth profile picture.
+ *
+ * Providers are evaluated in declaration order; a provider matches if any of its
+ * `prefixes` is a prefix of the repo name (the part after "owner/"). Repo names
+ * are case-sensitive — match the publisher's exact casing.
+ */
+
+/**
+ * Logo coloring. "original" = file as-is; "mono-theme" = CSS mask in current
+ * text color (follows theme); "mono-black" = mask always pure black.
+ */
+export type LogoTreatment = "original" | "mono-theme" | "mono-black";
+
+/** Tile background. "white" keeps colored marks readable; "transparent" shows the surface. */
+export type LogoBackground = "white" | "transparent";
+
+/**
+ * Logo sizing (only for "original"; mono always pads). "contain" pads at ~75%;
+ * "cover" is full-bleed.
+ */
+export type LogoFit = "contain" | "cover";
+
+export interface ProviderLogo {
+	id: string;
+	name: string;
+	logoPath: string;
+	treatment: LogoTreatment;
+	background: LogoBackground;
+	fit?: LogoFit;
+	/**
+	 * Repo-name prefixes (after `owner/`) mapping to this provider. A prefix
+	 * match suffices — variants (-Instruct, -bnb-4bit, -GGUF) ride along. Match
+	 * on the family stem so future minor versions are picked up automatically.
+	 */
+	prefixes: readonly string[];
+}
+
+export const PROVIDER_LOGOS: readonly ProviderLogo[] = [
+	// First so Llama-3.x-Nemotron/Minitron and Mistral-NeMo beat meta-llama / mistralai.
+	{
+		id: "nvidia",
+		name: "NVIDIA",
+		logoPath: "/hub/profile/logo/nvidia.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: [
+			"Llama-3.1-Nemotron-",
+			"Llama-3.3-Nemotron-",
+			"Llama-3.1-Minitron-",
+			"NVIDIA-Nemotron-",
+			"Nemotron-3-",
+			"Nemotron-4-",
+			"Nemotron-H-",
+			"Minitron-",
+			"Mistral-NeMo-",
+			"OpenReasoning-Nemotron-",
+			"OpenCodeReasoning",
+			"Cosmos-"
+		],
+	},
+
+	// `DeepSeek-R1-Distill-*` must beat Qwen/meta-llama on the suffix family.
+	{
+		id: "deepseek-ai",
+		name: "DeepSeek",
+		logoPath: "/hub/profile/logo/deepseek.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: [
+			"DeepSeek-R1-Distill-",
+			"DeepSeek-",
+			"deepseek-",
+			"deepseek-llm-",
+			"deepseek-coder-",
+		],
+	},
+
+	{
+		id: "microsoft",
+		name: "Microsoft",
+		logoPath: "/hub/profile/logo/microsoft.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: [
+			"MAI-DS-R1",
+			"NextCoder-",
+			"Phi-3-",
+			"Phi-3.5-",
+			"Phi-4",
+			"phi-1",
+			"phi-2",
+			"phi-",
+		],
+	},
+
+	// The broad `Qwen` prefix catches Qwen1.5/2/2.5/3/future versions without explicit entries.
+	{
+		id: "qwen",
+		name: "Qwen",
+		logoPath: "/hub/profile/logo/qwen.png",
+		treatment: "original",
+		background: "white",
+		prefixes: ["Qwen", "QwQ-", "QVQ-"],
+	},
+
+	{
+		id: "moonshotai",
+		name: "Moonshot AI",
+		logoPath: "/hub/profile/logo/moonshot.jpg",
+		treatment: "original",
+		background: "transparent",
+		fit: "cover",
+		prefixes: ["Kimi-", "Moonlight-"],
+	},
+
+	// Z.ai (THUDM successor).
+	{
+		id: "zai-org",
+		name: "Z.ai",
+		logoPath: "/hub/profile/logo/zai.svg",
+		treatment: "original",
+		background: "transparent",
+		fit: "cover",
+		prefixes: ["GLM-", "glm-", "chatglm", "codegeex"],
+	},
+
+	{
+		id: "xai-org",
+		name: "xAI",
+		logoPath: "/hub/profile/logo/xai.svg",
+		treatment: "mono-black",
+		background: "white",
+		prefixes: ["grok-"],
+	},
+
+	{
+		id: "minimax",
+		name: "MiniMax AI",
+		logoPath: "/hub/profile/logo/minimax-color.png",
+		treatment: "original",
+		background: "white",
+		prefixes: ["MiniMax-"],
+	},
+
+	// SmolLM family lives under HuggingFaceTB.
+	{
+		id: "huggingface",
+		name: "Hugging Face",
+		logoPath: "/hub/profile/logo/hf.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: ["SmolLM"],
+	},
+
+	{
+		id: "ibm",
+		name: "IBM",
+		logoPath: "/hub/profile/logo/ibm.png",
+		treatment: "original",
+		background: "transparent",
+		fit: "cover",
+		prefixes: ["granite-", "granitelib-"],
+	},
+
+	{
+		id: "cohere",
+		name: "Cohere Labs",
+		logoPath: "/hub/profile/logo/cohere.png",
+		treatment: "original",
+		background: "white",
+		prefixes: ["c4ai-command", "aya-"],
+	},
+
+	{
+		id: "openai",
+		name: "OpenAI",
+		logoPath: "/hub/profile/logo/openai.svg",
+		treatment: "mono-theme",
+		background: "transparent",
+		prefixes: ["gpt-oss-"],
+	},
+
+	{
+		id: "google",
+		name: "Google",
+		logoPath: "/hub/profile/logo/google.png",
+		treatment: "original",
+		background: "white",
+		prefixes: [
+			"gemma-",
+			"codegemma-",
+			"recurrentgemma-",
+			"shieldgemma-",
+			"medgemma-",
+			"functiongemma-",
+			"translategemma-",
+			"alphagenome-",
+			"t5gemma-",
+			"tipsv2-",
+			"embeddinggemma-",
+			"videoprism-",
+			"txgemma-",
+			"paligemma-",
+			"metricx-",
+			"bert-",
+		],
+	},
+
+	// After NVIDIA so `Mistral-NeMo-` wins; generic Mistral-/Mixtral- fall through here.
+	{
+		id: "mistralai",
+		name: "Mistral AI",
+		logoPath: "/hub/profile/logo/mistral.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: ["Mistral-", "Mixtral-", "Codestral-", "Pixtral-", "Devstral-", "Ministral-", "Voxtral-", "Magistral-"],
+	},
+
+	// Last among Llama-prefix providers so NVIDIA's Llama-3.x-Nemotron/Minitron match first.
+	{
+		id: "meta-llama",
+		name: "Meta",
+		logoPath: "/hub/profile/logo/meta.svg",
+		treatment: "original",
+		background: "white",
+		prefixes: [
+			"Meta-Llama-",
+			"Llama-Guard-",
+			"LlamaGuard-",
+			"CodeLlama-",
+			"Llama-",
+			"llama-",
+			"meta-"
+		],
+	},
+];
+
+/**
+ * Resolve a repo name (after `owner/`) to its upstream provider, or null.
+ * Iterates PROVIDER_LOGOS in declaration order; first prefix match wins.
+ */
+export function matchProviderLogo(repoName: string): ProviderLogo | null {
+	if (!repoName) return null;
+	for (const provider of PROVIDER_LOGOS) {
+		if (provider.prefixes.some((prefix) => repoName.startsWith(prefix))) {
+			return provider;
+		}
+	}
+	return null;
+}
+
+// Owners whose avatars get swapped for the matched provider's logo.
+const RELABELED_OWNERS: ReadonlySet<string> = new Set(["unsloth"]);
+
+export function isProviderRelabeledOwner(
+	owner: string | null | undefined,
+): boolean {
+	if (!owner) return false;
+	return RELABELED_OWNERS.has(owner.toLowerCase());
+}
+
+/**
+ * Provider logo to render in place of the owner's profile picture, or null.
+ * Only owners in RELABELED_OWNERS are eligible.
+ */
+export function resolveOwnerProviderLogo(
+	owner: string | null | undefined,
+	repoName: string | null | undefined,
+): ProviderLogo | null {
+	if (!isProviderRelabeledOwner(owner) || !repoName) return null;
+	return matchProviderLogo(repoName);
+}
diff --git a/studio/frontend/src/features/hub/lib/search-text.ts b/studio/frontend/src/features/hub/lib/search-text.ts
new file mode 100644
index 0000000000..b6653ee1f8
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/search-text.ts
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+/** Lowercase and strip whitespace and separators so "Llama-3.1" matches "llama 3 1". */
+export function normalizeForSearch(value: string): string {
+  return value.toLowerCase().replace(/[\s_.-]/g, "");
+}
+
+export function tokenizeQuery(query: string): string[] {
+  return query
+    .split(/\s+/)
+    .map((token) => normalizeForSearch(token))
+    .filter((token) => token.length > 0);
+}
+
+export function matchTokens(haystack: string, tokens: readonly string[]): boolean {
+  if (tokens.length === 0) return true;
+  const normalized = normalizeForSearch(haystack);
+  for (const token of tokens) {
+    if (!normalized.includes(token)) return false;
+  }
+  return true;
+}
diff --git a/studio/frontend/src/features/hub/lib/selection-resolution.ts b/studio/frontend/src/features/hub/lib/selection-resolution.ts
new file mode 100644
index 0000000000..f3c4543448
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/selection-resolution.ts
@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { findCompleteHfCacheLocalRow } from "../inventory/inventory-dedupe";
+import type {
+  CachedInventoryRow,
+  DiscoverRow,
+  LocalInventoryRow,
+} from "../types";
+
+export type SelectionResolution = {
+  selectedId: string | null;
+  hiddenByFilters: boolean;
+};
+
+function idSet(rows: readonly { id: string }[]): Set<string> {
+  return new Set(rows.map((row) => row.id));
+}
+
+function idMap<T extends { id: string }>(rows: readonly T[]): Map<string, T> {
+  return new Map(rows.map((row) => [row.id, row]));
+}
+
+function resolveCachedSelection(
+  cached: CachedInventoryRow,
+  filteredCachedIds: ReadonlySet<string>,
+  filteredLocalIds: ReadonlySet<string>,
+  localRows: readonly LocalInventoryRow[],
+): SelectionResolution {
+  if (cached.partial) {
+    const completeLocal = findCompleteHfCacheLocalRow(cached, localRows);
+    if (completeLocal) {
+      return {
+        selectedId: completeLocal.id,
+        hiddenByFilters: !filteredLocalIds.has(completeLocal.id),
+      };
+    }
+  }
+  return {
+    selectedId: cached.id,
+    hiddenByFilters: !filteredCachedIds.has(cached.id),
+  };
+}
+
+function resolveDownloadedId(
+  id: string | null,
+  cachedById: ReadonlyMap<string, CachedInventoryRow>,
+  localById: ReadonlyMap<string, LocalInventoryRow>,
+  filteredCachedIds: ReadonlySet<string>,
+  filteredLocalIds: ReadonlySet<string>,
+  localRows: readonly LocalInventoryRow[],
+): SelectionResolution | null {
+  if (!id) {
+    return null;
+  }
+  const cached = cachedById.get(id);
+  if (cached) {
+    return resolveCachedSelection(
+      cached,
+      filteredCachedIds,
+      filteredLocalIds,
+      localRows,
+    );
+  }
+  if (localById.has(id)) {
+    return {
+      selectedId: id,
+      hiddenByFilters: !filteredLocalIds.has(id),
+    };
+  }
+  return null;
+}
+
+export function resolveDiscoverSelection({
+  selectedId,
+  discoverRows,
+  filteredDiscoverRows,
+  selectedSnapshotId,
+}: {
+  selectedId: string | null;
+  discoverRows: readonly DiscoverRow[];
+  filteredDiscoverRows: readonly DiscoverRow[];
+  selectedSnapshotId?: string | null;
+}): SelectionResolution {
+  const filteredIds = idSet(filteredDiscoverRows);
+  if (
+    selectedId &&
+    (discoverRows.some((row) => row.id === selectedId) ||
+      selectedSnapshotId === selectedId)
+  ) {
+    return {
+      selectedId,
+      hiddenByFilters: !filteredIds.has(selectedId),
+    };
+  }
+  return {
+    selectedId: filteredDiscoverRows[0]?.id ?? null,
+    hiddenByFilters: false,
+  };
+}
+
+export function resolveDownloadedSelection({
+  selectedId,
+  cachedRows,
+  localRows,
+  filteredCachedRows,
+  filteredLocalRows,
+}: {
+  selectedId: string | null;
+  cachedRows: readonly CachedInventoryRow[];
+  localRows: readonly LocalInventoryRow[];
+  filteredCachedRows: readonly CachedInventoryRow[];
+  filteredLocalRows: readonly LocalInventoryRow[];
+}): SelectionResolution {
+  const cachedById = idMap(cachedRows);
+  const localById = idMap(localRows);
+  const filteredCachedIds = idSet(filteredCachedRows);
+  const filteredLocalIds = idSet(filteredLocalRows);
+  return (
+    resolveDownloadedId(
+      selectedId,
+      cachedById,
+      localById,
+      filteredCachedIds,
+      filteredLocalIds,
+      localRows,
+    ) ??
+    resolveDownloadedId(
+      filteredCachedRows[0]?.id ?? null,
+      cachedById,
+      localById,
+      filteredCachedIds,
+      filteredLocalIds,
+      localRows,
+    ) ??
+    resolveDownloadedId(
+      filteredLocalRows[0]?.id ?? null,
+      cachedById,
+      localById,
+      filteredCachedIds,
+      filteredLocalIds,
+      localRows,
+    ) ?? { selectedId: null, hiddenByFilters: false }
+  );
+}
diff --git a/studio/frontend/src/features/hub/lib/token-fingerprint.ts b/studio/frontend/src/features/hub/lib/token-fingerprint.ts
new file mode 100644
index 0000000000..316ac6ea24
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/token-fingerprint.ts
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export function fingerprintToken(token?: string | null): string {
+  if (!token) return "anon";
+  let h1 = 0x811c9dc5;
+  let h2 = 0;
+  for (let i = 0; i < token.length; i++) {
+    const c = token.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = (Math.imul(h2, 33) + c) | 0;
+  }
+  return (
+    (h1 >>> 0).toString(16).padStart(8, "0") +
+    (h2 >>> 0).toString(16).padStart(8, "0")
+  );
+}
diff --git a/studio/frontend/src/features/hub/lib/unsloth-support.ts b/studio/frontend/src/features/hub/lib/unsloth-support.ts
new file mode 100644
index 0000000000..45e913b2b9
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/unsloth-support.ts
@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+const EXCLUDED_TAGS_GPU = new Set([
+  "gptq",
+  "awq",
+  "exl2",
+  "mlx",
+  "onnx",
+  "openvino",
+  "coreml",
+  "tflite",
+  "ctranslate2",
+]);
+
+const EXCLUDED_TAGS_MLX = new Set([
+  "gptq",
+  "awq",
+  "exl2",
+  "onnx",
+  "openvino",
+  "coreml",
+  "tflite",
+  "ctranslate2",
+]);
+
+const UNSUPPORTED_PIPELINE_TAGS: ReadonlySet<string> = new Set([
+  "text-to-image",
+  "image-to-image",
+  "image-text-to-image",
+  "text-to-video",
+  "video-to-video",
+  "image-to-video",
+  "video-text-to-text",
+  "video-classification",
+  "unconditional-image-generation",
+  "text-to-3d",
+  "image-to-3d",
+  "image-segmentation",
+  "object-detection",
+  "depth-estimation",
+  "mask-generation",
+  "zero-shot-image-classification",
+  "zero-shot-object-detection",
+  "image-classification",
+  "keypoint-detection",
+  "image-feature-extraction",
+  "robotics",
+  "reinforcement-learning",
+  "graph-ml",
+  "tabular-classification",
+  "tabular-regression",
+  "time-series-forecasting",
+]);
+
+const UNSUPPORTED_LIBRARY_TAGS: ReadonlySet<string> = new Set([
+  "diffusers",
+  "stable-diffusion",
+  "stable-diffusion-xl",
+  "flux",
+  "controlnet",
+  "lora-diffusers",
+]);
+
+const FORMAT_TAG_LABEL: Record<string, string> = {
+  gptq: "GPTQ quantization",
+  awq: "AWQ quantization",
+  exl2: "EXL2 quantization",
+  mlx: "MLX-format weights",
+  onnx: "ONNX-format weights",
+  openvino: "OpenVINO-format weights",
+  coreml: "Core ML-format weights",
+  tflite: "TensorFlow Lite-format weights",
+  ctranslate2: "CTranslate2-format weights",
+};
+
+const FORMAT_ALIAS_TAGS: Record<string, string> = {
+  "auto-gptq": "gptq",
+};
+
+const FORMAT_NAME_PATTERNS: ReadonlyArray<{ key: string; pattern: RegExp }> = [
+  { key: "awq", pattern: /(?:^|[-_./])awq(?:\d+(?:bit)?)?(?:$|[-_./])/i },
+  { key: "gptq", pattern: /(?:^|[-_./])gptq(?:\d+(?:bit)?)?(?:$|[-_./])/i },
+  { key: "exl2", pattern: /(?:^|[-_./])exl2(?:$|[-_./])/i },
+  { key: "mlx", pattern: /(?:^|[-_./])mlx(?:$|[-_./])/i },
+  { key: "onnx", pattern: /(?:^|[-_./])onnx(?:$|[-_./])/i },
+  { key: "openvino", pattern: /(?:^|[-_./])openvino(?:$|[-_./])/i },
+  { key: "coreml", pattern: /(?:^|[-_./])coreml(?:$|[-_./])/i },
+  { key: "tflite", pattern: /(?:^|[-_./])tflite(?:$|[-_./])/i },
+  { key: "ctranslate2", pattern: /(?:^|[-_./])ctranslate2(?:$|[-_./])/i },
+];
+
+const SUPPORTED_QUANT_METHODS: ReadonlySet<string> = new Set([
+  "bitsandbytes",
+  "bnb",
+  "bnb_4bit",
+  "bnb_8bit",
+]);
+
+const UNSUPPORTED_QUANT_METHODS: Record<string, string> = {
+  awq: "AWQ quantization",
+  gptq: "GPTQ quantization",
+  exl2: "EXL2 quantization",
+  "compressed-tensors": "compressed-tensors quantization",
+  aqlm: "AQLM quantization",
+  eetq: "EETQ quantization",
+  hqq: "HQQ quantization",
+  fbgemm_fp8: "FBGEMM FP8 quantization",
+  finegrained_fp8: "fine-grained FP8 quantization",
+  quark: "Quark quantization",
+  vptq: "VPTQ quantization",
+  spqr: "SpQR quantization",
+  higgs: "HIGGS quantization",
+  sinq: "SINQ quantization",
+  torchao: "torchao quantization",
+  quanto: "optimum-quanto quantization",
+  auto_round: "AutoRound quantization",
+  autoround: "AutoRound quantization",
+  metal: "Metal-kernel quantization",
+  fouroversix: "Four Over Six quantization",
+  fp_quant: "FP-Quant quantization",
+};
+
+export type UnslothSupportStatus = "supported" | "unsupported";
+
+export interface UnslothSupport {
+  status: UnslothSupportStatus;
+  reason: string | null;
+}
+
+export function excludedFormatTagsForDevice(
+  deviceType?: string | null,
+): ReadonlySet<string> {
+  return deviceType?.toLowerCase() === "mac"
+    ? EXCLUDED_TAGS_MLX
+    : EXCLUDED_TAGS_GPU;
+}
+
+function normalizeQuantMethod(value: string | null | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.toLowerCase().trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function repoLeaf(modelId: string): string {
+  const parts = modelId.trim().split("/").filter(Boolean);
+  return parts.at(-1) ?? modelId;
+}
+
+function detectFormatKey(
+  modelId: string | null | undefined,
+  lowerTags: ReadonlySet<string>,
+): string | null {
+  for (const tag of lowerTags) {
+    if (FORMAT_TAG_LABEL[tag]) return tag;
+    const alias = FORMAT_ALIAS_TAGS[tag];
+    if (alias) return alias;
+  }
+  if (modelId) {
+    const name = repoLeaf(modelId);
+    for (const { key, pattern } of FORMAT_NAME_PATTERNS) {
+      if (pattern.test(name)) return key;
+    }
+  }
+  return null;
+}
+
+export function classifyUnslothSupport({
+  modelId,
+  pipelineTag,
+  tags,
+  libraryName,
+  deviceType,
+  quantMethod,
+}: {
+  modelId?: string | null;
+  pipelineTag?: string | null;
+  tags?: readonly string[] | null;
+  libraryName?: string | null;
+  deviceType?: string | null;
+  quantMethod?: string | null;
+}): UnslothSupport {
+  const pipeline = pipelineTag?.toLowerCase().trim() || null;
+  const lowerTags = new Set(
+    (tags ?? []).map((tag) => tag.toLowerCase().trim()).filter(Boolean),
+  );
+  const library = libraryName?.toLowerCase().trim() || null;
+  const formatTags = excludedFormatTagsForDevice(deviceType);
+  const normalizedQuant = normalizeQuantMethod(quantMethod);
+
+  if (normalizedQuant) {
+    if (SUPPORTED_QUANT_METHODS.has(normalizedQuant)) {
+      return { status: "supported", reason: null };
+    }
+    if (Object.hasOwn(UNSUPPORTED_QUANT_METHODS, normalizedQuant)) {
+      return {
+        status: "unsupported",
+        reason: `Detected ${UNSUPPORTED_QUANT_METHODS[normalizedQuant]}.`,
+      };
+    }
+  }
+
+  if (pipeline && UNSUPPORTED_PIPELINE_TAGS.has(pipeline)) {
+    return {
+      status: "unsupported",
+      reason: `Pipeline task: ${pipeline}.`,
+    };
+  }
+  for (const tag of lowerTags) {
+    if (UNSUPPORTED_LIBRARY_TAGS.has(tag)) {
+      return {
+        status: "unsupported",
+        reason: `Library: ${tag}.`,
+      };
+    }
+  }
+  if (library && UNSUPPORTED_LIBRARY_TAGS.has(library)) {
+    return {
+      status: "unsupported",
+      reason: `Library: ${library}.`,
+    };
+  }
+  const formatKey = detectFormatKey(modelId, lowerTags);
+  if (formatKey && formatTags.has(formatKey)) {
+    const label = FORMAT_TAG_LABEL[formatKey] ?? `${formatKey.toUpperCase()} weights`;
+    return {
+      status: "unsupported",
+      reason: `Detected ${label}.`,
+    };
+  }
+  return { status: "supported", reason: null };
+}
diff --git a/studio/frontend/src/features/hub/lib/view-models.ts b/studio/frontend/src/features/hub/lib/view-models.ts
new file mode 100644
index 0000000000..6fc06a6e97
--- /dev/null
+++ b/studio/frontend/src/features/hub/lib/view-models.ts
@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { HfModelResult } from "@/features/hub/hooks/use-hub-model-search";
+import { resolveInventoryResource } from "@/features/hub/inventory/resource-resolver";
+import type {
+  CachedInventoryRow,
+  LocalInventoryRow,
+} from "@/features/hub/inventory/types";
+import type {
+  CapabilityFilter,
+  DiscoverRow,
+  ModelFormatFilter,
+} from "../types";
+import {
+  detectCapabilities,
+  type CapabilityKey,
+} from "./model-capabilities";
+import { ownerOf, repoOf } from "@/features/hub/lib/format";
+import { estimateSizeFromDtypes, isGgufLike } from "./hf-model-meta";
+export { matchesFormat } from "./format-filters";
+export {
+  formatLocalUpdated,
+  localSourceLabel,
+} from "@/features/hub/inventory";
+export { isGgufLike } from "./hf-model-meta";
+
+export const CAPABILITY_FILTER_OPTIONS: ReadonlyArray<{
+  value: CapabilityFilter;
+  label: string;
+}> = [
+  { value: "all", label: "All capabilities" },
+  { value: "reasoning", label: "Reasoning" },
+  { value: "code", label: "Code" },
+  { value: "vision", label: "Vision" },
+  { value: "audio", label: "Audio" },
+  { value: "tools", label: "Tools" },
+  { value: "embedding", label: "Embeddings" },
+  { value: "multilingual", label: "Multilingual" },
+];
+
+export const FORMAT_FILTER_OPTIONS: ReadonlyArray<{
+  value: ModelFormatFilter;
+  label: string;
+}> = [
+  { value: "all", label: "All formats" },
+  { value: "gguf", label: "GGUF" },
+  { value: "checkpoint", label: "Checkpoints" },
+];
+
+export function formatPipelineTag(tag: string | undefined): string | null {
+  if (!tag) return null;
+  return tag
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function formatLibrary(name: string | undefined): string | null {
+  if (!name) return null;
+  if (name === "transformers") return "Transformers";
+  return name;
+}
+
+export function buildSummary(result: HfModelResult): string {
+  const parts: string[] = [];
+  const pipeline = formatPipelineTag(result.pipelineTag);
+  if (pipeline) parts.push(pipeline);
+  if (result.totalParams) parts.push(`${compactNumber(result.totalParams)} params`);
+  if (result.isGguf) {
+    parts.push("GGUF");
+  } else {
+    const library = formatLibrary(result.libraryName);
+    if (library) parts.push(library);
+  }
+  return parts.join(" · ") || "Hugging Face model";
+}
+
+function compactNumber(value: number): string {
+  return new Intl.NumberFormat("en", {
+    notation: "compact",
+    maximumFractionDigits: value < 10 ? 1 : 0,
+  }).format(value);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function toHfModelResult(raw: unknown): HfModelResult | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+
+  const model = raw as {
+    name?: string;
+    downloads?: number;
+    likes?: number;
+    task?: string;
+    pipeline_tag?: string;
+    library_name?: string;
+    updatedAt?: Date | string;
+    safetensors?: { total?: number; parameters?: Record<string, number> };
+    gguf?: { total?: number; architecture?: string };
+    tags?: string[];
+    config?: { quantization_config?: { quant_method?: string } };
+  };
+
+  if (!model.name) return null;
+
+  const isGguf =
+    Boolean(model.tags?.some((tag) => tag.toLowerCase() === "gguf")) ||
+    isGgufLike(model.name);
+  const updatedAt =
+    model.updatedAt instanceof Date
+      ? model.updatedAt.toISOString()
+      : typeof model.updatedAt === "string"
+        ? model.updatedAt
+        : undefined;
+
+  return {
+    id: model.name,
+    downloads: finiteNumber(model.downloads) ?? 0,
+    likes: finiteNumber(model.likes) ?? 0,
+    totalParams:
+      finiteNumber(model.safetensors?.total) ?? finiteNumber(model.gguf?.total),
+    estimatedSizeBytes: estimateSizeFromDtypes(model.safetensors?.parameters),
+    isGguf,
+    tags: model.tags,
+    pipelineTag: model.task ?? model.pipeline_tag,
+    updatedAt,
+    libraryName: model.library_name,
+    quantMethod: model.config?.quantization_config?.quant_method,
+  };
+}
+
+export function buildDiscoverRows(
+  results: HfModelResult[],
+  cachedRows: CachedInventoryRow[],
+  localRows: LocalInventoryRow[],
+): DiscoverRow[] {
+  return results.map((result) => {
+    const resource = resolveInventoryResource({
+      repoId: result.id,
+      cachedRows,
+      localRows,
+      formatHint: result.isGguf ? "gguf" : "non-gguf",
+    });
+    const partial = Boolean(
+      resource.cachedRow?.partial ?? resource.localRow?.partial ?? false,
+    );
+    return {
+      id: result.id,
+      owner: ownerOf(result.id),
+      repo: repoOf(result.id),
+      result,
+      isAvailableOnDevice: Boolean(resource.cachedRow || resource.localRow),
+      isPartialOnDevice: partial,
+      summary: buildSummary(result),
+      capabilities: detectCapabilities(
+        result.tags,
+        result.pipelineTag,
+        result.id,
+      ),
+    };
+  });
+}
+
+export function matchesCapability(
+  capabilities: Array<{ key: CapabilityKey }>,
+  capabilityFilter: CapabilityFilter,
+): boolean {
+  if (capabilityFilter === "all") return true;
+  return capabilities.some((capability) => capability.key === capabilityFilter);
+}
+
+const LANGUAGE_TAG_PREFIX = "language:";
+
+export function parseLanguageTags(
+  tags: readonly string[] | null | undefined,
+): string[] {
+  const langs: string[] = [];
+  for (const tag of tags ?? []) {
+    if (!tag.startsWith(LANGUAGE_TAG_PREFIX)) continue;
+    const code = tag.slice(LANGUAGE_TAG_PREFIX.length);
+    if (code && !langs.includes(code)) langs.push(code);
+  }
+  return langs;
+}
diff --git a/studio/frontend/src/features/hub/stores/external-link-confirm.ts b/studio/frontend/src/features/hub/stores/external-link-confirm.ts
new file mode 100644
index 0000000000..bcd3980362
--- /dev/null
+++ b/studio/frontend/src/features/hub/stores/external-link-confirm.ts
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+
+interface ExternalLinkConfirmStore {
+  pendingUrl: string | null;
+  request: (url: string) => void;
+  dismiss: () => void;
+}
+
+export const useExternalLinkConfirm = create<ExternalLinkConfirmStore>((set) => ({
+  pendingUrl: null,
+  request: (url) => set({ pendingUrl: url }),
+  dismiss: () => set({ pendingUrl: null }),
+}));
+
+export function confirmExternalLink(url: string): boolean {
+  const trimmed = url?.trim() ?? "";
+  if (!trimmed || trimmed.startsWith("#")) return false;
+  const lower = trimmed.toLowerCase();
+  if (
+    !lower.includes("://") &&
+    !lower.startsWith("//") &&
+    !lower.startsWith("mailto:")
+  ) {
+    return false;
+  }
+  useExternalLinkConfirm.getState().request(trimmed);
+  return true;
+}
diff --git a/studio/frontend/src/features/hub/stores/hf-token-store.ts b/studio/frontend/src/features/hub/stores/hf-token-store.ts
new file mode 100644
index 0000000000..c63aa82ad4
--- /dev/null
+++ b/studio/frontend/src/features/hub/stores/hf-token-store.ts
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+import { bumpInventoryVersion } from "./inventory-events";
+
+const HF_TOKEN_KEY = "unsloth_hf_token";
+const HF_TOKEN_CHANGED_EVENT = "unsloth:hf-token-changed";
+const LEGACY_TRAINING_KEY = "unsloth_training_config_v1";
+let storageSyncStarted = false;
+let storageSyncListener: ((event: StorageEvent) => void) | null = null;
+let tokenChangedListener: ((event: Event) => void) | null = null;
+
+function canUseStorage(): boolean {
+  return typeof window !== "undefined";
+}
+
+function loadInitial(): string {
+  if (!canUseStorage()) return "";
+  try {
+    const direct = window.localStorage.getItem(HF_TOKEN_KEY);
+    if (direct !== null) {
+      const normalized = normalize(direct);
+      if (normalized !== direct) persist(normalized);
+      return normalized;
+    }
+    const legacy = window.localStorage.getItem(LEGACY_TRAINING_KEY);
+    if (legacy) {
+      const parsed = JSON.parse(legacy) as {
+        state?: Record<string, unknown>;
+        [key: string]: unknown;
+      };
+      const fromTraining = parsed?.state?.hfToken;
+      if (typeof fromTraining === "string" && fromTraining.length > 0) {
+        const normalized = normalize(fromTraining);
+        // Copy only: training-config-store still reads its own hfToken, so deleting it would drop that token.
+        persist(normalized);
+        return normalized;
+      }
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
+function persist(value: string): void {
+  if (!canUseStorage()) return;
+  try {
+    window.localStorage.setItem(HF_TOKEN_KEY, value);
+  } catch {
+    void 0;
+  }
+}
+
+function normalize(raw: string): string {
+  return raw.replace(/^[\s"']+|[\s"']+$/g, "");
+}
+
+function stopStorageSync(): void {
+  if (!canUseStorage()) return;
+  if (storageSyncListener !== null) {
+    window.removeEventListener("storage", storageSyncListener);
+    storageSyncListener = null;
+  }
+  if (tokenChangedListener !== null) {
+    window.removeEventListener(HF_TOKEN_CHANGED_EVENT, tokenChangedListener);
+    tokenChangedListener = null;
+  }
+  storageSyncStarted = false;
+}
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(stopStorageSync);
+}
+
+interface HfTokenStore {
+  token: string;
+  setToken: (value: string) => void;
+  clearToken: () => void;
+}
+
+export const useHfTokenStore = create<HfTokenStore>((set) => {
+  const applyToken = (value: string, shouldPersist: boolean) => {
+    const next = normalize(value);
+    if (shouldPersist || next !== value) persist(next);
+    let changed = false;
+    set((state) => {
+      if (state.token === next) return state;
+      changed = true;
+      return { token: next };
+    });
+    if (changed) bumpInventoryVersion();
+  };
+
+  if (!storageSyncStarted && canUseStorage()) {
+    storageSyncStarted = true;
+    storageSyncListener = (event) => {
+      if (event.key !== HF_TOKEN_KEY) return;
+      applyToken(event.newValue ?? "", false);
+    };
+    window.addEventListener("storage", storageSyncListener);
+    tokenChangedListener = (event) => {
+      applyToken((event as CustomEvent<string>).detail ?? "", false);
+    };
+    window.addEventListener(HF_TOKEN_CHANGED_EVENT, tokenChangedListener);
+  }
+
+  return {
+    token: loadInitial(),
+    setToken: (value) => applyToken(value, true),
+    clearToken: () => applyToken("", true),
+  };
+});
+
+export function getHfToken(): string {
+  return useHfTokenStore.getState().token;
+}
diff --git a/studio/frontend/src/features/hub/stores/inventory-events.ts b/studio/frontend/src/features/hub/stores/inventory-events.ts
new file mode 100644
index 0000000000..c47c0407ca
--- /dev/null
+++ b/studio/frontend/src/features/hub/stores/inventory-events.ts
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useSyncExternalStore } from "react";
+
+type Listener = () => void;
+
+const CHANNEL_NAME = "unsloth.inventory";
+const STORAGE_KEY = "unsloth.inventory.bump";
+const OUTBOUND_CHANNEL_CLOSE_DELAY_MS = 250;
+
+let _version = 0;
+const listeners = new Set<Listener>();
+const seenBumps = new Set<string>();
+const seenBumpOrder: string[] = [];
+let crossTabReady = false;
+let channel: BroadcastChannel | null = null;
+let outboundChannel: BroadcastChannel | null = null;
+let outboundCloseTimer: ReturnType<typeof setTimeout> | null = null;
+let storageHandler: ((event: StorageEvent) => void) | null = null;
+
+function emitInventoryChange(): void {
+  for (const fn of [...listeners]) fn();
+}
+
+function rememberBump(id: string): boolean {
+  if (seenBumps.has(id)) return false;
+  seenBumps.add(id);
+  seenBumpOrder.push(id);
+  while (seenBumpOrder.length > 32) {
+    const oldest = seenBumpOrder.shift();
+    if (oldest) seenBumps.delete(oldest);
+  }
+  return true;
+}
+
+function applyInventoryBump(): void {
+  _version += 1;
+  emitInventoryChange();
+}
+
+function ensureCrossTabSync(): void {
+  if (crossTabReady || typeof window === "undefined") return;
+  crossTabReady = true;
+  if (typeof BroadcastChannel !== "undefined") {
+    channel = new BroadcastChannel(CHANNEL_NAME);
+    channel.onmessage = (event) => {
+      if (typeof event.data !== "string") return;
+      if (!rememberBump(event.data)) return;
+      applyInventoryBump();
+    };
+  }
+  storageHandler = (event) => {
+    if (event.key !== STORAGE_KEY || typeof event.newValue !== "string") return;
+    if (!rememberBump(event.newValue)) return;
+    applyInventoryBump();
+  };
+  window.addEventListener("storage", storageHandler);
+  try {
+    const current = window.localStorage.getItem(STORAGE_KEY);
+    if (typeof current === "string") rememberBump(current);
+  } catch {
+    void 0;
+  }
+}
+
+function stopCrossTabSync(): void {
+  if (!crossTabReady) return;
+  channel?.close();
+  channel = null;
+  if (storageHandler && typeof window !== "undefined") {
+    window.removeEventListener("storage", storageHandler);
+  }
+  storageHandler = null;
+  crossTabReady = false;
+}
+
+function closeOutboundChannel(): void {
+  outboundCloseTimer = null;
+  outboundChannel?.close();
+  outboundChannel = null;
+}
+
+function getOutboundChannel(): BroadcastChannel | null {
+  if (typeof BroadcastChannel === "undefined") {
+    return null;
+  }
+  if (!outboundChannel) {
+    outboundChannel = new BroadcastChannel(CHANNEL_NAME);
+  }
+  if (outboundCloseTimer !== null) {
+    clearTimeout(outboundCloseTimer);
+  }
+  outboundCloseTimer = setTimeout(
+    closeOutboundChannel,
+    OUTBOUND_CHANNEL_CLOSE_DELAY_MS,
+  );
+  return outboundChannel;
+}
+
+function postInventoryBump(id: string): void {
+  const target = channel ?? getOutboundChannel();
+  target?.postMessage(id);
+  try {
+    window.localStorage.setItem(STORAGE_KEY, id);
+  } catch {
+    void 0;
+  }
+}
+
+export function getInventoryVersion(): number {
+  return _version;
+}
+
+export function bumpInventoryVersion(): void {
+  const id =
+    typeof window === "undefined"
+      ? null
+      : `${Date.now()}:${Math.random().toString(36).slice(2)}`;
+  if (id) rememberBump(id);
+  applyInventoryBump();
+  if (!id) return;
+  postInventoryBump(id);
+}
+
+export function subscribeInventory(listener: Listener): () => void {
+  listeners.add(listener);
+  ensureCrossTabSync();
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      stopCrossTabSync();
+    }
+  };
+}
+
+export function useInventoryVersion(): number {
+  return useSyncExternalStore(
+    subscribeInventory,
+    getInventoryVersion,
+    getInventoryVersion,
+  );
+}
diff --git a/studio/frontend/src/features/hub/types.ts b/studio/frontend/src/features/hub/types.ts
new file mode 100644
index 0000000000..f2aa412f64
--- /dev/null
+++ b/studio/frontend/src/features/hub/types.ts
@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type {
+  BaseModelSource,
+  LocalSource,
+  ModelInventoryCapabilities,
+  ModelInventoryFormat,
+} from "@/features/hub/inventory";
+import type { HfModelResult } from "@/features/hub/hooks/use-hub-model-search";
+import type { Capability, CapabilityKey } from "./lib/model-capabilities";
+
+export type {
+  CachedInventoryRow,
+  InventoryHint,
+  InventoryRow,
+  LocalInventoryRow,
+  LocalSource,
+} from "@/features/hub/inventory";
+
+export type ModelsTab = "discover" | "downloaded";
+
+export type ResourceTypeFilter = "models" | "datasets";
+
+export type HubModelType = "text" | "vision" | "audio" | "embeddings";
+
+export type ModelFormatFilter = "all" | "gguf" | "checkpoint";
+
+export type CapabilityFilter = "all" | CapabilityKey;
+
+export interface DiscoverRow {
+  id: string;
+  owner: string;
+  repo: string;
+  result: HfModelResult;
+  isAvailableOnDevice: boolean;
+  isPartialOnDevice: boolean;
+  summary: string;
+  capabilities: Capability[];
+}
+
+export type SelectedResourceSource = "huggingface" | "hub_cache" | LocalSource;
+
+export type SelectedResourceCacheState =
+  | "remote"
+  | "cached"
+  | "local"
+  | "partial";
+
+export interface SelectedResourceRef {
+  repoId: string | null;
+  localPath: string | null;
+  source: SelectedResourceSource;
+  cacheState: SelectedResourceCacheState;
+  runId: string;
+  trainId: string;
+}
+
+export interface SelectedModelView {
+  id: string;
+  kind: "discover" | "cache" | "local";
+  resource: SelectedResourceRef;
+  displayId: string;
+  hubRepoId: string | null;
+  owner: string;
+  title: string;
+  summary: string;
+  sourceLabel: string;
+  path: string | null;
+  localSource?: LocalSource;
+  isLocal: boolean;
+  isGguf: boolean;
+  requiresVariant?: boolean;
+  modelFormat: ModelInventoryFormat | null;
+  baseModel?: string | null;
+  baseModelSource?: BaseModelSource | null;
+  baseModelHubId?: string | null;
+  baseModelSummary?: string | null;
+  adapterType?: string | null;
+  trainingMethod?: string | null;
+  isDownloaded: boolean;
+  isPartial?: boolean;
+  partialTransport?: string | null;
+  runtimeCapabilities?: ModelInventoryCapabilities;
+  capabilities: Capability[];
+  license: string | null;
+  pipelineTag?: string;
+  libraryName?: string;
+  downloads?: number;
+  likes?: number;
+  totalParams?: number;
+  estimatedSizeBytes?: number;
+  cachedBytes?: number;
+  updatedAt?: string;
+  localUpdatedAt?: number | null;
+  tags?: string[];
+  quantMethod?: string;
+}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 83a04b60c1..45c1fabe72 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -34,6 +34,7 @@ export const en = {
       newChat: "New Chat",
       compare: "Compare",
       search: "Search",
+      hub: "Hub",
       train: "Train",
       recipes: "Recipes",
       export: "Export",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index f7075eb887..3cfea1ae7a 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -34,6 +34,7 @@ export const zhCN = {
       newChat: "新聊天",
       compare: "对比",
       search: "搜索",
+      hub: "Hub",
       train: "训练",
       recipes: "配方",
       export: "导出",
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 68993d4a65..521fe28190 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -5,6 +5,7 @@
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
 @import "streamdown/styles.css";
+@import "./features/hub/hub.css";
 @import "@fontsource-variable/figtree";
 @import "@fontsource-variable/space-grotesk";
 @import "@fontsource-variable/inter";
diff --git a/studio/src-tauri/tauri.conf.json b/studio/src-tauri/tauri.conf.json
index d4d706cc14..44fccaa447 100644
--- a/studio/src-tauri/tauri.conf.json
+++ b/studio/src-tauri/tauri.conf.json
@@ -16,7 +16,7 @@
   "app": {
     "withGlobalTauri": true,
     "security": {
-      "csp": "default-src 'self'; connect-src 'self' http://localhost:* ws://localhost:* ws://127.0.0.1:* http://127.0.0.1:* https://huggingface.co https://*.huggingface.co https://datasets-server.huggingface.co; img-src 'self' data: https:; style-src 'self' 'unsafe-inline'; font-src 'self' data:"
+      "csp": "default-src 'self'; connect-src 'self' http://localhost:* ws://localhost:* ws://127.0.0.1:* http://127.0.0.1:* https://huggingface.co https://*.huggingface.co https://datasets-server.huggingface.co; img-src 'self' data: blob: https:; media-src 'self' data: blob: https:; style-src 'self' 'unsafe-inline'; font-src 'self' data:"
     },
     "windows": [
       {

From 33f4397b78f82f5851c888fdff1a896f02263abe Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Tue, 9 Jun 2026 14:02:00 +0200
Subject: [PATCH 119/222] Studio fix recipe dataset preview (#6031)

* Studio: fix recipe dataset preview

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/models/datasets.py             |   1 +
 studio/backend/routes/datasets.py             | 210 +++++++++++++++---
 .../backend/utils/datasets/dataset_utils.py   | 160 ++++++++-----
 .../utils/datasets/format_conversion.py       |  87 +++++---
 .../utils/datasets/format_detection.py        | 184 ++++++++++-----
 .../sections/dataset-preview-dialog.tsx       |  26 ++-
 .../src/features/training/types/datasets.ts   |   1 +
 7 files changed, 505 insertions(+), 164 deletions(-)

diff --git a/studio/backend/models/datasets.py b/studio/backend/models/datasets.py
index 9a2d8e91cb..b40a8416ec 100644
--- a/studio/backend/models/datasets.py
+++ b/studio/backend/models/datasets.py
@@ -40,6 +40,7 @@ class CheckFormatResponse(BaseModel):
     detected_audio_column: Optional[str] = None
     detected_text_column: Optional[str] = None
     detected_speaker_column: Optional[str] = None
+    chat_column: Optional[str] = None
     preview_samples: Optional[List[Dict]] = None
     total_rows: Optional[int] = None
     warning: Optional[str] = None
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index b755bf9d4a..859f2958f9 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -122,12 +122,12 @@ def _serialize_preview_rows(rows):
     ]
 
 
-# Data-file extensions for the single-file fallback. Tier 1 preview prefers
-# tabular over archives: archives (e.g. images.zip) load as ImageFolder with
-# synthetic image/label columns that don't match the real schema.
-_TABULAR_EXTS = (".parquet", ".json", ".jsonl", ".csv", ".tsv", ".arrow")
-_ARCHIVE_EXTS = (".tar", ".tar.gz", ".tgz", ".gz", ".zst", ".zip", ".txt")
-DATA_EXTS = _TABULAR_EXTS + _ARCHIVE_EXTS
+# Data-file extensions for single-file preview. Tier 1 only uses tabular
+# files; archives/text/config fall through to full load_dataset.
+_COLUMNAR_EXTS = (".parquet", ".arrow")
+_RECORD_EXTS = (".jsonl", ".csv", ".tsv")
+_JSON_EXTS = (".json",)
+_TABULAR_EXTS = _COLUMNAR_EXTS + _RECORD_EXTS + _JSON_EXTS
 LOCAL_FILE_EXTS = (".json", ".jsonl", ".csv", ".parquet")
 LOCAL_UPLOAD_EXTS = {".csv", ".json", ".jsonl", ".parquet"}
 # sync: training dataset upload limits are exposed by /api/settings/upload-limit
@@ -145,6 +145,166 @@ def _safe_read_metadata(path: Path) -> dict | None:
     return payload
 
 
+_HF_PREVIEW_EXT_PRIORITY = {
+    ".parquet": 0,
+    ".arrow": 0,
+    ".jsonl": 1,
+    ".csv": 2,
+    ".tsv": 3,
+    ".json": 4,
+}
+_HF_NON_DATA_EXACT_FILENAMES = {
+    ".gitattributes",
+    "builder_config.json",
+    "config.json",
+    "dataset_info.json",
+    "dataset_infos.json",
+    "metadata.json",
+}
+_HF_NON_DATA_CARD_FILENAMES = {"card.json", "dataset_card.json"}
+
+
+def _normalize_hf_repo_path(path: str) -> str:
+    return path.strip().replace("\\", "/").lstrip("./")
+
+
+def _hf_preview_extension(path: str) -> str | None:
+    lower = path.lower()
+    for ext in _HF_PREVIEW_EXT_PRIORITY:
+        if lower.endswith(ext):
+            return ext
+    return None
+
+
+def _is_known_hf_non_data_file(path: str) -> bool:
+    name = Path(path).name.lower()
+    if name in _HF_NON_DATA_EXACT_FILENAMES:
+        return True
+    if name in _HF_NON_DATA_CARD_FILENAMES:
+        return True
+    if name == "readme" or name.startswith("readme."):
+        return True
+    if name.endswith("_config.json") or name.endswith("-config.json"):
+        return True
+    if name.endswith("_card.json") or name.endswith("-card.json"):
+        return True
+    return False
+
+
+def _is_hf_preview_data_file(path: str) -> bool:
+    normalized = _normalize_hf_repo_path(path)
+    if not normalized or _is_known_hf_non_data_file(normalized):
+        return False
+    return _hf_preview_extension(normalized) is not None
+
+
+def _extract_hf_metadata_data_paths(metadata: dict | None) -> list[str]:
+    if not metadata:
+        return []
+    file_paths = metadata.get("file_paths")
+    if not isinstance(file_paths, dict):
+        return []
+    raw_data_paths = file_paths.get("data")
+    if isinstance(raw_data_paths, str):
+        values = [raw_data_paths]
+    elif isinstance(raw_data_paths, list):
+        values = raw_data_paths
+    else:
+        return []
+
+    paths: list[str] = []
+    for value in values:
+        if not isinstance(value, str):
+            continue
+        normalized = _normalize_hf_repo_path(value)
+        if normalized:
+            paths.append(normalized)
+    return paths
+
+
+def _select_best_hf_preview_candidate(
+    candidates: list[str], *, subset: str | None, split: str | None
+) -> str | None:
+    if not candidates:
+        return None
+    subset_lower = subset.lower() if subset else None
+    split_lower = split.lower() if split else None
+
+    def score(path: str) -> tuple[int, int, int, int, str]:
+        ext = _hf_preview_extension(path)
+        ext_priority = _HF_PREVIEW_EXT_PRIORITY[ext] if ext else 99
+        stem = Path(path).stem.lower()
+        path_lower = path.lower()
+
+        subset_miss = 0
+        if subset_lower:
+            subset_miss = 0 if subset_lower in stem or subset_lower in path_lower else 1
+
+        split_miss = 0
+        if split_lower:
+            split_hit = (
+                stem == split_lower
+                or stem.startswith(f"{split_lower}_")
+                or stem.startswith(f"{split_lower}-")
+                or f"/{split_lower}/" in path_lower
+                or f"_{split_lower}." in path_lower
+                or f"-{split_lower}." in path_lower
+                or f"/{split_lower}." in path_lower
+                or f"/{split_lower}_" in path_lower
+                or f"/{split_lower}-" in path_lower
+            )
+            split_miss = 0 if split_hit else 1
+
+        return (subset_miss, split_miss, ext_priority, len(path), path)
+
+    return sorted(candidates, key = score)[0]
+
+
+def _select_hf_preview_file(
+    repo_files: list[str], *, metadata: dict | None, subset: str | None, split: str | None
+) -> str | None:
+    normalized_repo_files = [_normalize_hf_repo_path(path) for path in repo_files]
+    repo_file_set = set(normalized_repo_files)
+
+    metadata_candidates = [
+        path
+        for path in _extract_hf_metadata_data_paths(metadata)
+        if path in repo_file_set and _is_hf_preview_data_file(path)
+    ]
+    if metadata_candidates:
+        return _select_best_hf_preview_candidate(metadata_candidates, subset = subset, split = split)
+
+    data_candidates = [path for path in normalized_repo_files if _is_hf_preview_data_file(path)]
+    return _select_best_hf_preview_candidate(data_candidates, subset = subset, split = split)
+
+
+def _download_hf_metadata(*, repo_id: str, repo_files: list[str], token: str | None) -> dict | None:
+    metadata_file = next(
+        (
+            path
+            for path in repo_files
+            if Path(_normalize_hf_repo_path(path)).name.lower() == "metadata.json"
+        ),
+        None,
+    )
+    if not metadata_file:
+        return None
+
+    try:
+        from huggingface_hub import hf_hub_download
+        local_path = hf_hub_download(
+            repo_id = repo_id,
+            filename = metadata_file,
+            repo_type = "dataset",
+            token = token,
+        )
+    except Exception as exc:
+        logger.warning(f"Could not read HF dataset metadata for {repo_id}: {exc}")
+        return None
+
+    return _safe_read_metadata(Path(local_path))
+
+
 def _safe_read_rows_from_metadata(payload: dict | None) -> int | None:
     if not payload:
         return None
@@ -442,7 +602,8 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
     """Check if a dataset requires manual column mapping.
 
     HuggingFace strategy:
-      1. list_repo_files -> first data file -> load_dataset (avoids resolving thousands of files; ~2-4 s).
+      1. list_repo_files -> select one tabular data file -> load_dataset
+         (avoids resolving thousands of files; ~2-4 s).
       2. Full streaming load_dataset as a last-resort fallback.
 
     Local files load directly. Plain `def` (not async) so FastAPI runs it in a
@@ -470,7 +631,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
             )
         else:
             # ── HuggingFace dataset ─────────────────────────────────
-            # Tier 1: load only the first data file from list_repo_files
+            # Tier 1: list_repo_files -> load one selected tabular data file
             preview_slice = None
 
             try:
@@ -482,27 +643,23 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
                     repo_type = "dataset",
                     token = request.hf_token or None,
                 )
-                data_files = [f for f in repo_files if any(f.endswith(ext) for ext in DATA_EXTS)]
+                metadata = _download_hf_metadata(
+                    repo_id = request.dataset_name,
+                    repo_files = repo_files,
+                    token = request.hf_token or None,
+                )
+                selected_file = _select_hf_preview_file(
+                    repo_files,
+                    metadata = metadata,
+                    subset = request.subset,
+                    split = request.train_split or "train",
+                )
 
-                # Prefer tabular over archives (e.g. images.zip -> ImageFolder
-                # with synthetic columns not in the real schema).
-                tabular_files = [
-                    f for f in data_files if any(f.endswith(ext) for ext in _TABULAR_EXTS)
-                ]
-                candidates = tabular_files or data_files
-
-                # With a subset, narrow to files whose name matches it.
-                if request.subset and candidates:
-                    subset_matches = [f for f in candidates if request.subset in Path(f).stem]
-                    if subset_matches:
-                        candidates = subset_matches
-
-                if candidates:
-                    first_file = candidates[0]
-                    logger.info(f"Tier 1: loading single file {first_file}")
+                if selected_file:
+                    logger.info(f"Tier 1: loading single file {selected_file}")
                     load_kwargs = {
                         "path": request.dataset_name,
-                        "data_files": [first_file],
+                        "data_files": [selected_file],
                         "split": "train",
                         "streaming": True,
                     }
@@ -596,6 +753,7 @@ def check_format(request: CheckFormatRequest, current_subject: str = Depends(get
             detected_audio_column = result.get("detected_audio_column"),
             detected_text_column = result.get("detected_text_column"),
             detected_speaker_column = result.get("detected_speaker_column"),
+            chat_column = result.get("chat_column"),
             preview_samples = preview_samples,
             total_rows = total_rows,
             warning = warning,
diff --git a/studio/backend/utils/datasets/dataset_utils.py b/studio/backend/utils/datasets/dataset_utils.py
index 2d65b6ecbc..faa3deac70 100644
--- a/studio/backend/utils/datasets/dataset_utils.py
+++ b/studio/backend/utils/datasets/dataset_utils.py
@@ -180,6 +180,7 @@ def check_dataset_format(dataset, is_vlm: bool = False) -> dict:
         "suggested_mapping": None,
         "detected_image_column": None,
         "detected_text_column": None,
+        "chat_column": detected.get("chat_column"),
         "is_image": multimodal_info["is_image"],
         "multimodal_columns": multimodal_info.get("multimodal_columns"),
         **audio_fields,
@@ -199,6 +200,17 @@ _TO_CHATML = {
 }
 _CHATML_ROLE_ORDER = ("system", "user", "assistant")
 _CHATML_TO_ALPACA = {"user": "instruction", "system": "input", "assistant": "output"}
+_KNOWN_CHAT_COLUMNS = {"messages", "conversations", "texts"}
+
+
+def _chatml_final_format(chat_column: str | None) -> str:
+    return "chatml_messages" if chat_column == "messages" else "chatml_conversations"
+
+
+def _chatml_detected_format_label(chat_column: str | None) -> str:
+    if chat_column in _KNOWN_CHAT_COLUMNS:
+        return f"chatml_{chat_column}"
+    return "chatml_conversations"
 
 
 def _apply_user_mapping(
@@ -522,7 +534,7 @@ def format_dataset(
             }
 
         # ShareGPT - needs standardization
-        elif detected["format"] == "sharegpt":
+        elif detected["format"] == "sharegpt" and detected.get("chat_column"):
             try:
                 standardized = standardize_chat_format(
                     dataset,
@@ -532,11 +544,12 @@ def format_dataset(
                     aliases_for_assistant,
                     batch_size,
                     num_proc,
+                    chat_column = detected["chat_column"],
                 )
                 return {
                     "dataset": standardized,
                     "detected_format": "sharegpt",
-                    "final_format": f"chatml_{detected['chat_column']}",
+                    "final_format": _chatml_final_format(detected["chat_column"]),
                     "chat_column": detected["chat_column"],
                     "is_standardized": True,
                     "requires_manual_mapping": False,
@@ -558,15 +571,11 @@ def format_dataset(
                     "warnings": warnings,
                 }
 
-        elif detected["format"] == "chatml" and detected["chat_column"] in [
-            "conversations",
-            "messages",
-            "texts",
-        ]:
+        elif detected["format"] == "chatml" and detected.get("chat_column"):
             return {
                 "dataset": dataset,
-                "detected_format": f"chatml_{detected['chat_column']}",
-                "final_format": f"chatml_{detected['chat_column']}",
+                "detected_format": _chatml_detected_format_label(detected["chat_column"]),
+                "final_format": _chatml_final_format(detected["chat_column"]),
                 "chat_column": detected["chat_column"],
                 "is_standardized": True,
                 "requires_manual_mapping": False,
@@ -637,12 +646,13 @@ def format_dataset(
                         aliases_for_assistant,
                         batch_size,
                         num_proc,
+                        chat_column = detected["chat_column"],
                     )
                     warnings.append("Successfully standardized unknown format")
                     return {
                         "dataset": standardized,
                         "detected_format": "unknown",
-                        "final_format": f"chatml_{detected['chat_column']}",
+                        "final_format": _chatml_final_format(detected["chat_column"]),
                         "chat_column": detected["chat_column"],
                         "is_standardized": True,
                         "requires_manual_mapping": False,
@@ -681,32 +691,52 @@ def format_dataset(
                 "warnings": [],
             }
 
-        elif detected["format"] in ["sharegpt", "chatml"]:
-            # First standardize if ShareGPT
-            if detected["format"] == "sharegpt":
-                dataset = standardize_chat_format(
+        elif detected["format"] in ["sharegpt", "chatml"] and detected.get("chat_column"):
+            try:
+                # First standardize if ShareGPT
+                if detected["format"] == "sharegpt":
+                    dataset = standardize_chat_format(
+                        dataset,
+                        tokenizer,
+                        aliases_for_system,
+                        aliases_for_user,
+                        aliases_for_assistant,
+                        batch_size,
+                        num_proc,
+                        chat_column = detected["chat_column"],
+                    )
+
+                # Then convert to Alpaca
+                converted = convert_chatml_to_alpaca(
                     dataset,
-                    tokenizer,
-                    aliases_for_system,
-                    aliases_for_user,
-                    aliases_for_assistant,
                     batch_size,
                     num_proc,
+                    chat_column = detected["chat_column"],
                 )
-
-            # Then convert to Alpaca
-            converted = convert_chatml_to_alpaca(dataset, batch_size, num_proc)
-            return {
-                "dataset": converted,
-                "detected_format": detected["format"],
-                "final_format": "alpaca",
-                "chat_column": None,
-                "is_standardized": True,
-                "requires_manual_mapping": False,
-                "is_image": multimodal_info["is_image"],
-                "multimodal_info": multimodal_info,
-                "warnings": [],
-            }
+                return {
+                    "dataset": converted,
+                    "detected_format": detected["format"],
+                    "final_format": "alpaca",
+                    "chat_column": None,
+                    "is_standardized": True,
+                    "requires_manual_mapping": False,
+                    "is_image": multimodal_info["is_image"],
+                    "multimodal_info": multimodal_info,
+                    "warnings": [],
+                }
+            except Exception as e:
+                warnings.append(f"Failed to convert chat dataset to Alpaca: {e}")
+                return {
+                    "dataset": dataset,
+                    "detected_format": detected["format"],
+                    "final_format": "unknown",
+                    "chat_column": detected["chat_column"],
+                    "is_standardized": False,
+                    "requires_manual_mapping": True,
+                    "is_image": multimodal_info["is_image"],
+                    "multimodal_info": multimodal_info,
+                    "warnings": warnings,
+                }
 
         else:
             warnings.append(f"Cannot convert unknown format to Alpaca")
@@ -738,33 +768,48 @@ def format_dataset(
                 "warnings": [],
             }
 
-        elif detected["format"] == "sharegpt":
-            standardized = standardize_chat_format(
-                dataset,
-                tokenizer,
-                aliases_for_system,
-                aliases_for_user,
-                aliases_for_assistant,
-                batch_size,
-                num_proc,
-            )
-            return {
-                "dataset": standardized,
-                "detected_format": "sharegpt",
-                "final_format": f"chatml_{detected['chat_column']}",
-                "chat_column": detected["chat_column"],
-                "is_standardized": True,
-                "requires_manual_mapping": False,
-                "is_image": multimodal_info["is_image"],
-                "multimodal_info": multimodal_info,
-                "warnings": [],
-            }
+        elif detected["format"] == "sharegpt" and detected.get("chat_column"):
+            try:
+                standardized = standardize_chat_format(
+                    dataset,
+                    tokenizer,
+                    aliases_for_system,
+                    aliases_for_user,
+                    aliases_for_assistant,
+                    batch_size,
+                    num_proc,
+                    chat_column = detected["chat_column"],
+                )
+                return {
+                    "dataset": standardized,
+                    "detected_format": "sharegpt",
+                    "final_format": _chatml_final_format(detected["chat_column"]),
+                    "chat_column": detected["chat_column"],
+                    "is_standardized": True,
+                    "requires_manual_mapping": False,
+                    "is_image": multimodal_info["is_image"],
+                    "multimodal_info": multimodal_info,
+                    "warnings": [],
+                }
+            except Exception as e:
+                warnings.append(f"Failed to standardize ShareGPT format: {e}")
+                return {
+                    "dataset": dataset,
+                    "detected_format": "sharegpt",
+                    "final_format": "sharegpt",
+                    "chat_column": detected["chat_column"],
+                    "is_standardized": False,
+                    "requires_manual_mapping": True,
+                    "is_image": multimodal_info["is_image"],
+                    "multimodal_info": multimodal_info,
+                    "warnings": warnings,
+                }
 
-        elif detected["format"] == "chatml":
+        elif detected["format"] == "chatml" and detected.get("chat_column"):
             return {
                 "dataset": dataset,
-                "detected_format": f"chatml_{detected['chat_column']}",
-                "final_format": f"chatml_{detected['chat_column']}",
+                "detected_format": _chatml_detected_format_label(detected["chat_column"]),
+                "final_format": _chatml_final_format(detected["chat_column"]),
                 "chat_column": detected["chat_column"],
                 "is_standardized": True,
                 "requires_manual_mapping": False,
@@ -785,11 +830,12 @@ def format_dataset(
                         aliases_for_assistant,
                         batch_size,
                         num_proc,
+                        chat_column = detected["chat_column"],
                     )
                     return {
                         "dataset": standardized,
                         "detected_format": "unknown",
-                        "final_format": f"chatml_{detected['chat_column']}",
+                        "final_format": _chatml_final_format(detected["chat_column"]),
                         "chat_column": detected["chat_column"],
                         "is_standardized": True,
                         "requires_manual_mapping": False,
diff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.py
index 7a556a9745..cb24bd96ba 100644
--- a/studio/backend/utils/datasets/format_conversion.py
+++ b/studio/backend/utils/datasets/format_conversion.py
@@ -29,6 +29,7 @@ def standardize_chat_format(
     ],
     batch_size = 1000,
     num_proc = None,
+    chat_column: str | None = None,
 ):
     """
     Standardize BOTH messages and conversations: map non-standard role
@@ -46,9 +47,10 @@ def standardize_chat_format(
 
     column_names = set(next(iter(dataset)).keys())
 
-    # Find the chat column
-    chat_column = None
-    if "conversations" in column_names:
+    if chat_column:
+        if chat_column not in column_names:
+            return dataset
+    elif "conversations" in column_names:
         chat_column = "conversations"
     elif "messages" in column_names:
         chat_column = "messages"
@@ -57,30 +59,48 @@ def standardize_chat_format(
     else:
         return dataset  # No chat column found
 
-    # Inspect structure
-    examples = itertools.islice(dataset, 10)
+    def _iter_probe_rows():
+        try:
+            total = min(len(dataset), 100)
+            for index in range(total):
+                yield dataset[index]
+            return
+        except Exception:
+            pass
+        for example in itertools.islice(dataset, 100):
+            yield example
+
     uniques = collections.defaultdict(list)
-    for example in examples:
-        for message in example[chat_column]:
+    for example in _iter_probe_rows():
+        chat_data = example.get(chat_column)
+        if not isinstance(chat_data, list) or len(chat_data) == 0:
+            continue
+        for message in chat_data:
+            if not isinstance(message, dict):
+                continue
             for key, value in message.items():
                 if type(value) is not str:
                     continue  # Skip non-strings
                 uniques[key].append(value)
 
-    if len(uniques.keys()) != 2:
-        return dataset  # Unexpected structure
-
-    keys = list(uniques.keys())
-    length_first = len(set(uniques[keys[0]]))
-    length_second = len(set(uniques[keys[1]]))
-
-    # Fewer unique values => role; the other => content
-    if length_first < length_second:
-        role_key = keys[0]
-        content_key = keys[1]
+    if "from" in uniques and "value" in uniques:
+        role_key = "from"
+        content_key = "value"
+    elif "role" in uniques and "content" in uniques:
+        role_key = "role"
+        content_key = "content"
+    elif len(uniques.keys()) == 2:
+        keys = list(uniques.keys())
+        length_first = len(set(uniques[keys[0]]))
+        length_second = len(set(uniques[keys[1]]))
+        if length_first < length_second:
+            role_key = keys[0]
+            content_key = keys[1]
+        else:
+            role_key = keys[1]
+            content_key = keys[0]
     else:
-        role_key = keys[1]
-        content_key = keys[0]
+        raise ValueError(f"Could not infer role/content keys for chat column '{chat_column}'")
 
     # Mapping for aliases
     aliases_mapping = {}
@@ -95,10 +115,23 @@ def standardize_chat_format(
         convos = examples[chat_column]
         all_convos = []
         for convo in convos:
+            if not isinstance(convo, list):
+                all_convos.append([])
+                continue
+
             new_convo = []
             for message in convo:
-                original_role = message.get(role_key, "")
-                original_content = message.get(content_key, "")
+                if not isinstance(message, dict):
+                    continue
+
+                # Use the inferred keys first; fall back per-message so mixed
+                # ShareGPT/ChatML rows keep valid turns.
+                original_role = message.get(role_key)
+                original_content = message.get(content_key)
+                if original_role is None:
+                    original_role = message.get("role") or message.get("from") or ""
+                if original_content is None:
+                    original_content = message.get("content") or message.get("value") or ""
 
                 standard_role = aliases_mapping.get(original_role, original_role)
 
@@ -136,6 +169,7 @@ def convert_chatml_to_alpaca(
     dataset,
     batch_size = 1000,
     num_proc = None,
+    chat_column: str | None = None,
 ):
     """
     Convert ChatML (messages OR conversations) to Alpaca format.
@@ -151,10 +185,11 @@ def convert_chatml_to_alpaca(
         _is_torch_iterable = False
 
     def _convert(examples):
-        # Auto-detect the column name
-        chatml_data = (
-            examples.get("messages") or examples.get("conversations") or examples.get("texts")
-        )
+        chatml_data = examples.get(chat_column) if chat_column else None
+        if chatml_data is None:
+            chatml_data = (
+                examples.get("messages") or examples.get("conversations") or examples.get("texts")
+            )
 
         if chatml_data is None:
             raise ValueError("No 'messages' or 'conversations' or 'texts' column found.")
diff --git a/studio/backend/utils/datasets/format_detection.py b/studio/backend/utils/datasets/format_detection.py
index b3a4e3d6d5..f5ea5ca138 100644
--- a/studio/backend/utils/datasets/format_detection.py
+++ b/studio/backend/utils/datasets/format_detection.py
@@ -11,22 +11,146 @@ def _keyword_in_column(keyword: str, col_name: str) -> bool:
     return re.search(r"\b" + re.escape(keyword) + r"\b", col_name, re.IGNORECASE) is not None
 
 
+CONVERSATION_COLUMNS = ("messages", "conversations", "texts")
+_CHATML_KEYS = frozenset({"role", "content"})
+_SHAREGPT_KEYS = frozenset({"from", "value"})
+_TRACE_SUFFIXES = ("__trace", "_trace")
+
+
+def _sample_dataset_rows(dataset, limit: int = 100) -> list[dict]:
+    try:
+        total = min(len(dataset), limit)
+        return [dataset[index] for index in range(total)]
+    except Exception:
+        rows = []
+        try:
+            for index, row in enumerate(dataset):
+                if index >= limit:
+                    break
+                rows.append(row)
+        except Exception:
+            return []
+        return rows
+
+
+def _get_dataset_column_names(dataset, sample: dict) -> list[str]:
+    column_names = getattr(dataset, "column_names", None)
+    if isinstance(column_names, list):
+        return [str(column) for column in column_names]
+    return [str(column) for column in sample.keys()]
+
+
+def _is_trace_conversation_name(column_name: str) -> bool:
+    return column_name.lower().endswith(_TRACE_SUFFIXES)
+
+
+def _inspect_conversation_column(rows: list[dict], column_name: str) -> dict | None:
+    turn_keys: set[str] = set()
+    has_chatml = False
+    has_sharegpt = False
+
+    for row in rows:
+        if not isinstance(row, dict) or column_name not in row:
+            continue
+        chat_data = row[column_name]
+        if not isinstance(chat_data, list) or len(chat_data) == 0:
+            continue
+        for turn in chat_data:
+            if not isinstance(turn, dict):
+                continue
+            keys = {str(key) for key in turn.keys()}
+            turn_keys.update(keys)
+            if _SHAREGPT_KEYS.issubset(keys):
+                has_sharegpt = True
+            if _CHATML_KEYS.issubset(keys):
+                has_chatml = True
+
+    if has_sharegpt:
+        return {
+            "format": "sharegpt",
+            "chat_column": column_name,
+            "needs_standardization": True,
+            "sample_keys": sorted(turn_keys),
+        }
+    if has_chatml:
+        return {
+            "format": "chatml",
+            "chat_column": column_name,
+            "needs_standardization": False,
+            "sample_keys": sorted(turn_keys),
+        }
+    if turn_keys:
+        return {
+            "format": "unknown",
+            "chat_column": column_name,
+            "needs_standardization": None,
+            "sample_keys": sorted(turn_keys),
+        }
+    return None
+
+
+def _detect_conversation_column(rows: list[dict], column_names: list[str]) -> dict | None:
+    column_name_set = set(column_names)
+    unknown_exact = None
+    for column_name in CONVERSATION_COLUMNS:
+        if column_name not in column_name_set:
+            continue
+        inspected = _inspect_conversation_column(rows, column_name)
+        if inspected and inspected["format"] in {"sharegpt", "chatml"}:
+            return inspected
+        if inspected and unknown_exact is None:
+            unknown_exact = inspected
+
+    structural_candidates = []
+    for column_name in column_names:
+        if column_name in CONVERSATION_COLUMNS:
+            continue
+        inspected = _inspect_conversation_column(rows, column_name)
+        if inspected and inspected["format"] in {"sharegpt", "chatml"}:
+            structural_candidates.append(inspected)
+
+    trace_candidates = [
+        candidate
+        for candidate in structural_candidates
+        if _is_trace_conversation_name(candidate["chat_column"])
+    ]
+    if len(trace_candidates) == 1:
+        return trace_candidates[0]
+    if len(trace_candidates) > 1:
+        return unknown_exact
+    if len(structural_candidates) == 1:
+        return structural_candidates[0]
+    if unknown_exact is not None:
+        return unknown_exact
+    return None
+
+
 def detect_dataset_format(dataset):
     """Detect dataset format by inspecting structure.
 
     Returns:
         dict: {
             "format": "alpaca" | "sharegpt" | "chatml" | "unknown",
-            "chat_column": "messages" | "conversations" | None,
+            "chat_column": str | None,
             "needs_standardization": bool,
             "sample_keys": list of keys found in messages (for debugging)
         }
     """
-    column_names = set(next(iter(dataset)).keys())
+    sample_rows = _sample_dataset_rows(dataset)
+    if not sample_rows:
+        return {
+            "format": "unknown",
+            "chat_column": None,
+            "needs_standardization": None,
+            "sample_keys": [],
+        }
+
+    column_names = _get_dataset_column_names(dataset, sample_rows[0])
+    column_name_set = set(column_names)
 
     # Alpaca
     alpaca_columns = {"instruction", "output"}
-    if alpaca_columns.issubset(column_names):
+    if alpaca_columns.issubset(column_name_set):
         return {
             "format": "alpaca",
             "chat_column": None,
@@ -34,57 +158,9 @@ def detect_dataset_format(dataset):
             "sample_keys": [],
         }
 
-    # Chat-based formats (messages or conversations)
-    chat_column = None
-    if "messages" in column_names:
-        chat_column = "messages"
-    elif "conversations" in column_names:
-        chat_column = "conversations"
-    elif "texts" in column_names:
-        chat_column = "texts"
-
-    if chat_column:
-        try:
-            sample = next(iter(dataset))
-            chat_data = sample[chat_column]
-
-            if chat_data and len(chat_data) > 0:
-                first_msg = chat_data[0]
-                msg_keys = set(first_msg.keys())
-
-                # ShareGPT: "from"/"value"
-                if "from" in msg_keys or "value" in msg_keys:
-                    return {
-                        "format": "sharegpt",
-                        "chat_column": chat_column,
-                        "needs_standardization": True,
-                        "sample_keys": list(msg_keys),
-                    }
-
-                # ChatML: "role"/"content"
-                elif "role" in msg_keys and "content" in msg_keys:
-                    return {
-                        "format": "chatml",
-                        "chat_column": chat_column,
-                        "needs_standardization": False,
-                        "sample_keys": list(msg_keys),
-                    }
-
-                else:
-                    return {
-                        "format": "unknown",
-                        "chat_column": chat_column,
-                        "needs_standardization": None,
-                        "sample_keys": list(msg_keys),
-                    }
-        except Exception as e:
-            return {
-                "format": "unknown",
-                "chat_column": chat_column,
-                "needs_standardization": None,
-                "sample_keys": [],
-                "error": str(e),
-            }
+    conversation = _detect_conversation_column(sample_rows, column_names)
+    if conversation:
+        return conversation
 
     return {
         "format": "unknown",
diff --git a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
index 6710099400..f337d51004 100644
--- a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
@@ -17,7 +17,11 @@ import { useTrainingActions, useTrainingConfigStore } from "@/features/training"
 import { checkDatasetFormat } from "@/features/training/api/datasets-api";
 import { isRawTextDatasetFormat } from "@/features/training/lib/training-methods";
 import type { CheckFormatResponse } from "@/features/training/types/datasets";
-import { Database02Icon, AlertCircleIcon } from "@hugeicons/core-free-icons";
+import {
+  AlertCircleIcon,
+  CheckmarkCircle02Icon,
+  Database02Icon,
+} from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useShallow } from "zustand/react/shallow";
 import { collectPreviewImages, formatCell } from "./dataset-preview-dialog-utils";
@@ -97,6 +101,16 @@ export function DatasetPreviewDialog({
   const mappingOk = isRawFormat || isMappingComplete(manualMapping, effectiveIsVlm, datasetFormat, effectiveIsAudio);
   const availableRoles = getAvailableRoles(effectiveIsVlm, datasetFormat, effectiveIsAudio);
   const isHfDataset = datasetSource === "huggingface";
+  const readyForTraining =
+    !(isRawFormat || mappingEnabled) &&
+    !data?.requires_manual_mapping &&
+    !!data?.detected_format &&
+    data.detected_format !== "unknown";
+  const readyDetail = data?.chat_column && data.detected_format === "chatml"
+    ? `Detected ChatML conversation column: ${data.chat_column}`
+    : data?.detected_format
+      ? `Detected ${data.detected_format} format. No manual column mapping needed.`
+      : null;
 
   // ── AI Assist ──────────────────────────────────────────────────────
   const [isAiLoading, setIsAiLoading] = useState(false);
@@ -438,6 +452,16 @@ export function DatasetPreviewDialog({
                 />
               </div>
 
+              {readyForTraining && (
+                <div className="mb-4 flex items-start gap-2.5 rounded-lg border border-emerald-200 bg-emerald-50 px-4 py-3 text-xs text-emerald-800 dark:border-emerald-800 dark:bg-emerald-950/70 dark:text-emerald-300">
+                  <HugeiconsIcon icon={CheckmarkCircle02Icon} className="mt-0.5 size-4 shrink-0" />
+                  <div className="space-y-0.5">
+                    <p className="font-medium">Ready for training</p>
+                    {readyDetail && <p>{readyDetail}</p>}
+                  </div>
+                </div>
+              )}
+
               {data.warning && !isRawFormat && (
                 <div className="rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-xs text-amber-700 dark:border-amber-800 dark:bg-amber-950 dark:text-amber-400 mb-4 flex items-start gap-2.5">
                   <HugeiconsIcon icon={AlertCircleIcon} className="size-4 shrink-0 mt-0.5" />
diff --git a/studio/frontend/src/features/training/types/datasets.ts b/studio/frontend/src/features/training/types/datasets.ts
index b3aa080d1e..f63bab7aca 100644
--- a/studio/frontend/src/features/training/types/datasets.ts
+++ b/studio/frontend/src/features/training/types/datasets.ts
@@ -10,6 +10,7 @@ export type CheckFormatResponse = {
   detected_audio_column?: string | null;
   detected_text_column?: string | null;
   detected_speaker_column?: string | null;
+  chat_column?: string | null;
   preview_samples?: Record<string, unknown>[] | null;
   total_rows?: number | null;
   is_image?: boolean;

From 0d6d7dd4b3aeeb94a01fabe90affa42db1da23bc Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Tue, 9 Jun 2026 15:28:34 +0200
Subject: [PATCH 120/222] Studio: make Helper LLM startup pre-cache opt in
 (#6113)

* Studio: make Helper LLM startup pre-cache opt in

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/main.py                        |  34 +++--
 studio/backend/routes/settings.py             |  47 +++++++
 .../tests/test_llm_assist_startup_opt_in.py   | 127 ++++++++++++++++++
 .../backend/utils/helper_precache_settings.py |  65 +++++++++
 .../features/settings/api/helper-precache.ts  |  88 ++++++++++++
 .../features/settings/tabs/general-tab.tsx    |  79 +++++++++++
 studio/frontend/src/i18n/locales/en.ts        |  10 ++
 7 files changed, 438 insertions(+), 12 deletions(-)
 create mode 100644 studio/backend/tests/test_llm_assist_startup_opt_in.py
 create mode 100644 studio/backend/utils/helper_precache_settings.py
 create mode 100644 studio/frontend/src/features/settings/api/helper-precache.ts

diff --git a/studio/backend/main.py b/studio/backend/main.py
index a9f7004df7..321995885c 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -292,6 +292,27 @@ def _desktop_owner() -> dict[str, str] | None:
     return _DESKTOP_OWNER
 
 
+def _start_helper_precache_if_enabled() -> None:
+    """Start optional Helper LLM GGUF pre-cache only after explicit opt-in."""
+    try:
+        from utils.helper_precache_settings import should_preload_helper_on_startup
+        if not should_preload_helper_on_startup():
+            return
+    except Exception:
+        return
+
+    import threading
+
+    def _precache():
+        try:
+            from utils.datasets.llm_assist import precache_helper_gguf
+            precache_helper_gguf()
+        except Exception:
+            pass  # non-critical
+
+    threading.Thread(target = _precache, daemon = True, name = "helper-gguf-precache").start()
+
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Startup: detect hardware, seed default admin if needed. Shutdown: clean up compiled cache."""
@@ -350,18 +371,7 @@ async def lifespan(app: FastAPI):
         import structlog
         structlog.get_logger(__name__).warning("cleanup_orphaned_runs failed at startup: %s", exc)
 
-    # Pre-cache the helper GGUF model for LLM-assisted dataset detection,
-    # in a background thread so it doesn't block server startup.
-    import threading
-
-    def _precache():
-        try:
-            from utils.datasets.llm_assist import precache_helper_gguf
-            precache_helper_gguf()
-        except Exception:
-            pass  # non-critical
-
-    threading.Thread(target = _precache, daemon = True).start()
+    _start_helper_precache_if_enabled()
 
     # Initialize RSA key pair for API key encryption (external providers)
     from core.inference.key_exchange import init_key_pair
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 94ea4c7b6c..516502c1e5 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -16,6 +16,12 @@ from utils.upload_limits import (
     upload_limit_bytes,
     upload_limit_label,
 )
+from utils.helper_precache_settings import (
+    DEFAULT_HELPER_PRECACHE_ENABLED,
+    get_helper_precache_enabled,
+    helper_model_disabled_by_env,
+    set_helper_precache_enabled,
+)
 
 router = APIRouter()
 
@@ -35,6 +41,16 @@ class UploadLimitResponse(BaseModel):
     max_allowed_upload_size_mb: int = MAX_UPLOAD_LIMIT_MB
 
 
+class HelperPrecachePayload(BaseModel):
+    enabled: bool
+
+
+class HelperPrecacheResponse(BaseModel):
+    enabled: bool
+    default_enabled: bool = DEFAULT_HELPER_PRECACHE_ENABLED
+    disabled_by_env: bool
+
+
 def _upload_limit_response(limit_mb: int) -> UploadLimitResponse:
     return UploadLimitResponse(
         max_upload_size_mb = limit_mb,
@@ -44,6 +60,13 @@ def _upload_limit_response(limit_mb: int) -> UploadLimitResponse:
     )
 
 
+def _helper_precache_response(enabled: bool | None = None) -> HelperPrecacheResponse:
+    return HelperPrecacheResponse(
+        enabled = get_helper_precache_enabled() if enabled is None else enabled,
+        disabled_by_env = helper_model_disabled_by_env(),
+    )
+
+
 @router.get("/upload-limit", response_model = UploadLimitResponse)
 def get_upload_limit(current_subject: str = Depends(get_current_subject)) -> UploadLimitResponse:
     return _upload_limit_response(get_upload_limit_mb())
@@ -64,3 +87,27 @@ def update_upload_limit(
             log = logger,
         ) from exc
     return _upload_limit_response(limit_mb)
+
+
+@router.get("/helper-precache", response_model = HelperPrecacheResponse)
+def get_helper_precache(
+    current_subject: str = Depends(get_current_subject),
+) -> HelperPrecacheResponse:
+    return _helper_precache_response()
+
+
+@router.put("/helper-precache", response_model = HelperPrecacheResponse)
+def update_helper_precache(
+    payload: HelperPrecachePayload, current_subject: str = Depends(get_current_subject)
+) -> HelperPrecacheResponse:
+    try:
+        enabled = set_helper_precache_enabled(payload.enabled)
+    except ValueError as exc:
+        raise log_and_http_error(
+            exc,
+            400,
+            safe_error_detail(exc, fallback = "Invalid Helper LLM pre-cache setting."),
+            event = "settings.update_helper_precache_failed",
+            log = logger,
+        ) from exc
+    return _helper_precache_response(enabled)
diff --git a/studio/backend/tests/test_llm_assist_startup_opt_in.py b/studio/backend/tests/test_llm_assist_startup_opt_in.py
new file mode 100644
index 0000000000..e81b1d3775
--- /dev/null
+++ b/studio/backend/tests/test_llm_assist_startup_opt_in.py
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Regression tests for Helper LLM startup pre-cache opt-in behavior."""
+
+from __future__ import annotations
+
+import sys
+import types
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from models.datasets import AiAssistMappingRequest
+from routes import datasets as datasets_route
+from routes import settings as settings_route
+from utils import helper_precache_settings
+
+
+def _install_fake_studio_db(monkeypatch, *, stored = None):
+    storage_pkg = types.ModuleType("storage")
+    studio_db = types.ModuleType("storage.studio_db")
+    values: dict[str, object] = {}
+    if stored is not None:
+        values[helper_precache_settings.HELPER_PRECACHE_SETTING_KEY] = stored
+
+    def get_app_setting(key, fallback = None):
+        return values.get(key, fallback)
+
+    def upsert_app_settings(settings):
+        values.update(settings)
+        return dict(values)
+
+    studio_db.get_app_setting = get_app_setting
+    studio_db.upsert_app_settings = upsert_app_settings
+    monkeypatch.setitem(sys.modules, "storage", storage_pkg)
+    monkeypatch.setitem(sys.modules, "storage.studio_db", studio_db)
+    return values
+
+
+def test_helper_precache_defaults_off_when_setting_missing(monkeypatch):
+    monkeypatch.delenv("UNSLOTH_HELPER_MODEL_DISABLE", raising = False)
+    _install_fake_studio_db(monkeypatch)
+
+    assert helper_precache_settings.get_helper_precache_enabled() is False
+    assert helper_precache_settings.should_preload_helper_on_startup() is False
+
+
+def test_helper_precache_opt_in_is_blocked_by_existing_disable_env(monkeypatch):
+    _install_fake_studio_db(monkeypatch, stored = True)
+    monkeypatch.setenv("UNSLOTH_HELPER_MODEL_DISABLE", "true")
+
+    assert helper_precache_settings.get_helper_precache_enabled() is True
+    assert helper_precache_settings.should_preload_helper_on_startup() is False
+
+
+def test_settings_route_persists_helper_precache_toggle(monkeypatch):
+    values = _install_fake_studio_db(monkeypatch)
+    monkeypatch.delenv("UNSLOTH_HELPER_MODEL_DISABLE", raising = False)
+
+    response = settings_route.update_helper_precache(
+        settings_route.HelperPrecachePayload(enabled = True),
+        current_subject = "test-user",
+    )
+
+    assert response.enabled is True
+    assert response.default_enabled is False
+    assert response.disabled_by_env is False
+    assert values[helper_precache_settings.HELPER_PRECACHE_SETTING_KEY] is True
+
+
+def test_main_startup_uses_helper_precache_gate_instead_of_unconditional_precache():
+    source = (Path(__file__).resolve().parent.parent / "main.py").read_text(encoding = "utf-8")
+    startup_section = source[
+        source.index("cleanup_orphaned_runs") : source.index("# Initialize RSA key pair")
+    ]
+
+    assert "_start_helper_precache_if_enabled()" in startup_section
+    assert "precache_helper_gguf" not in startup_section
+    assert "threading.Thread(target = _precache" not in startup_section
+
+
+def test_ai_assist_route_still_calls_on_demand_advisor(monkeypatch):
+    calls: list[dict] = []
+    llm_assist = types.ModuleType("utils.datasets.llm_assist")
+
+    def fake_llm_conversion_advisor(**kwargs):
+        calls.append(kwargs)
+        return {
+            "success": True,
+            "suggested_mapping": {"prompt": "user", "answer": "assistant"},
+            "system_prompt": "Answer carefully.",
+            "dataset_type": "question_answering",
+            "is_conversational": False,
+            "user_notification": "Columns mapped by AI Assist.",
+        }
+
+    llm_assist.llm_conversion_advisor = fake_llm_conversion_advisor
+    monkeypatch.setitem(sys.modules, "utils.datasets.llm_assist", llm_assist)
+
+    response = datasets_route.ai_assist_mapping(
+        AiAssistMappingRequest(
+            columns = ["prompt", "answer"],
+            samples = [{"prompt": "x" * 250, "answer": "ok", "extra": "ignored"}],
+            dataset_name = "owner/dataset",
+            hf_token = "hf_test",
+            model_name = "unsloth/test",
+            model_type = "text",
+        ),
+        current_subject = "test-user",
+    )
+
+    assert response.success is True
+    assert response.suggested_mapping == {"prompt": "user", "answer": "assistant"}
+    assert response.system_prompt == "Answer carefully."
+    assert calls == [
+        {
+            "column_names": ["prompt", "answer"],
+            "samples": [{"prompt": "x" * 200, "answer": "ok"}],
+            "dataset_name": "owner/dataset",
+            "hf_token": "hf_test",
+            "model_name": "unsloth/test",
+            "model_type": "text",
+        }
+    ]
diff --git a/studio/backend/utils/helper_precache_settings.py b/studio/backend/utils/helper_precache_settings.py
new file mode 100644
index 0000000000..db19a2d028
--- /dev/null
+++ b/studio/backend/utils/helper_precache_settings.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Persisted opt-in controls for Helper LLM startup pre-cache."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+HELPER_PRECACHE_SETTING_KEY = "helper_model_preload_on_startup"
+DEFAULT_HELPER_PRECACHE_ENABLED = False
+
+
+def _coerce_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off", ""}:
+            return False
+    return None
+
+
+def helper_model_disabled_by_env() -> bool:
+    """Return True when existing broad helper-disable env var is active."""
+    return os.environ.get("UNSLOTH_HELPER_MODEL_DISABLE", "").strip() in {"1", "true"}
+
+
+def get_helper_precache_enabled() -> bool:
+    """Read the persisted startup pre-cache preference.
+
+    Missing or unreadable settings default to False so Studio startup never
+    performs optional network work unless the user explicitly opted in.
+    """
+    try:
+        from storage.studio_db import get_app_setting
+        stored = get_app_setting(HELPER_PRECACHE_SETTING_KEY, None)
+    except Exception:
+        stored = None
+    parsed = _coerce_bool(stored)
+    return parsed if parsed is not None else DEFAULT_HELPER_PRECACHE_ENABLED
+
+
+def set_helper_precache_enabled(value: Any) -> bool:
+    """Persist whether Studio should pre-cache the Helper LLM at startup."""
+    parsed = _coerce_bool(value)
+    if parsed is None:
+        raise ValueError("Helper LLM startup pre-cache must be true or false.")
+
+    from storage.studio_db import upsert_app_settings
+
+    upsert_app_settings({HELPER_PRECACHE_SETTING_KEY: parsed})
+    return parsed
+
+
+def should_preload_helper_on_startup() -> bool:
+    """Gate the startup pre-cache thread.
+
+    The persisted setting is opt-in and the existing broad disable env var wins.
+    Explicit AI Assist calls do not use this gate; they remain user-triggered.
+    """
+    return get_helper_precache_enabled() and not helper_model_disabled_by_env()
diff --git a/studio/frontend/src/features/settings/api/helper-precache.ts b/studio/frontend/src/features/settings/api/helper-precache.ts
new file mode 100644
index 0000000000..434a6c7d03
--- /dev/null
+++ b/studio/frontend/src/features/settings/api/helper-precache.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+
+const HELPER_PRECACHE_EVENT = "unsloth-helper-precache-change";
+
+export type HelperPrecacheSettings = {
+  enabled: boolean;
+  defaultEnabled: boolean;
+  disabledByEnv: boolean;
+};
+
+type ApiHelperPrecacheSettings = {
+  enabled: boolean;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  default_enabled: boolean;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  disabled_by_env: boolean;
+};
+
+let cachedHelperPrecache: HelperPrecacheSettings | null = null;
+let inFlightHelperPrecache: Promise<HelperPrecacheSettings> | null = null;
+
+export function subscribeHelperPrecacheSettings(
+  listener: (settings: HelperPrecacheSettings) => void,
+) {
+  const handleChange = (event: Event) => {
+    listener((event as CustomEvent<HelperPrecacheSettings>).detail);
+  };
+  window.addEventListener(HELPER_PRECACHE_EVENT, handleChange);
+  return () => window.removeEventListener(HELPER_PRECACHE_EVENT, handleChange);
+}
+
+function fromApi(settings: ApiHelperPrecacheSettings): HelperPrecacheSettings {
+  return {
+    enabled: settings.enabled,
+    defaultEnabled: settings.default_enabled,
+    disabledByEnv: settings.disabled_by_env,
+  };
+}
+
+function cacheHelperPrecache(settings: HelperPrecacheSettings) {
+  cachedHelperPrecache = settings;
+  window.dispatchEvent(
+    new CustomEvent(HELPER_PRECACHE_EVENT, { detail: settings }),
+  );
+  return settings;
+}
+
+async function fetchHelperPrecacheSettings(): Promise<HelperPrecacheSettings> {
+  const res = await authFetch("/api/settings/helper-precache");
+  if (!res.ok) {
+    throw new Error(
+      await readFastApiError(res, "Failed to load Helper LLM settings"),
+    );
+  }
+  return fromApi(await res.json());
+}
+
+export async function loadHelperPrecacheSettings() {
+  if (cachedHelperPrecache) {
+    return cachedHelperPrecache;
+  }
+  inFlightHelperPrecache ??= fetchHelperPrecacheSettings()
+    .then(cacheHelperPrecache)
+    .finally(() => {
+      inFlightHelperPrecache = null;
+    });
+  return inFlightHelperPrecache;
+}
+
+export async function updateHelperPrecacheSettings(
+  enabled: boolean,
+): Promise<HelperPrecacheSettings> {
+  const res = await authFetch("/api/settings/helper-precache", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ enabled }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      await readFastApiError(res, "Failed to update Helper LLM settings"),
+    );
+  }
+  return cacheHelperPrecache(fromApi(await res.json()));
+}
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index 57a52b83d1..8a15eb4985 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -15,6 +15,11 @@ import { Switch } from "@/components/ui/switch";
 import { usePlatformStore } from "@/config/env";
 import { resetOnboardingDone } from "@/features/auth";
 import { useChatRuntimeStore } from "@/features/chat";
+import {
+  loadHelperPrecacheSettings,
+  updateHelperPrecacheSettings,
+  type HelperPrecacheSettings,
+} from "../api/helper-precache";
 import {
   DEFAULT_UPLOAD_LIMIT_MB,
   loadUploadLimitSettings,
@@ -114,6 +119,12 @@ export function GeneralTab() {
   );
   const [uploadLimitError, setUploadLimitError] = useState<string | null>(null);
   const [isSavingUploadLimit, setIsSavingUploadLimit] = useState(false);
+  const [helperPrecache, setHelperPrecache] =
+    useState<HelperPrecacheSettings | null>(null);
+  const [helperPrecacheError, setHelperPrecacheError] = useState<string | null>(
+    null,
+  );
+  const [isSavingHelperPrecache, setIsSavingHelperPrecache] = useState(false);
 
   const draftRef = useRef(draftToken);
   useEffect(() => {
@@ -158,6 +169,44 @@ export function GeneralTab() {
     };
   }, []);
 
+  useEffect(() => {
+    let cancelled = false;
+    void loadHelperPrecacheSettings()
+      .then((settings) => {
+        if (cancelled) return;
+        setHelperPrecache(settings);
+        setHelperPrecacheError(null);
+      })
+      .catch((error) => {
+        if (cancelled) return;
+        setHelperPrecacheError(
+          error instanceof Error
+            ? error.message
+            : t("settings.general.helperLlm.loadError"),
+        );
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [t]);
+
+  const saveHelperPrecache = async (enabled: boolean) => {
+    setIsSavingHelperPrecache(true);
+    setHelperPrecacheError(null);
+    try {
+      const settings = await updateHelperPrecacheSettings(enabled);
+      setHelperPrecache(settings);
+    } catch (error) {
+      setHelperPrecacheError(
+        error instanceof Error
+          ? error.message
+          : t("settings.general.helperLlm.saveError"),
+      );
+    } finally {
+      setIsSavingHelperPrecache(false);
+    }
+  };
+
   const saveUploadLimit = async () => {
     const parsed = Number(draftUploadLimit);
     if (!Number.isInteger(parsed)) {
@@ -236,6 +285,36 @@ export function GeneralTab() {
         </SettingsRow>
       </SettingsSection>
 
+      <SettingsSection title={t("settings.general.helperLlm.sectionTitle")}>
+        <SettingsRow
+          label={t("settings.general.helperLlm.preloadOnStartup")}
+          description={t(
+            "settings.general.helperLlm.preloadOnStartupDescription",
+          )}
+        >
+          <div className="flex flex-col items-end gap-1">
+            <Switch
+              checked={helperPrecache?.enabled ?? false}
+              disabled={
+                !helperPrecache ||
+                isSavingHelperPrecache ||
+                helperPrecache.disabledByEnv
+              }
+              onCheckedChange={(enabled) => void saveHelperPrecache(enabled)}
+            />
+            {helperPrecache?.disabledByEnv ? (
+              <span className="max-w-[260px] text-right text-xs text-muted-foreground">
+                {t("settings.general.helperLlm.disabledByEnv")}
+              </span>
+            ) : helperPrecacheError ? (
+              <span className="max-w-[260px] text-right text-xs text-destructive">
+                {helperPrecacheError}
+              </span>
+            ) : null}
+          </div>
+        </SettingsRow>
+      </SettingsSection>
+
       <SettingsSection title={t("settings.general.uploads.sectionTitle")}>
         <SettingsRow
           label={t("settings.general.uploads.maxUploadSize")}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 45c1fabe72..1492c7bb2b 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -108,6 +108,16 @@ export const en = {
       autoTitleNewChats: "Auto-title new chats",
       autoTitleNewChatsDescription:
         "Generate a short title from the first message.",
+      helperLlm: {
+        sectionTitle: "Helper LLM",
+        preloadOnStartup: "Pre-cache Helper LLM on startup",
+        preloadOnStartupDescription:
+          "Download and cache the AI Assist helper model in the background when Studio starts. Off by default; AI Assist can still download it on demand when clicked.",
+        disabledByEnv:
+          "Disabled by UNSLOTH_HELPER_MODEL_DISABLE in the backend environment.",
+        loadError: "Failed to load Helper LLM settings.",
+        saveError: "Failed to save Helper LLM settings.",
+      },
       gettingStarted: "Getting started",
       startOnboarding: "Start onboarding",
       startOnboardingDescription:

From ccb471f5bf2c86c1453b7dfd3fa8a28343800683 Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Tue, 9 Jun 2026 16:28:44 +0200
Subject: [PATCH 121/222] Improve local chat tool call flow (#5962)

Unify the Studio local tool-call loop (GGUF + safetensors) behind a shared ToolLoopController: ordered preface-then-tool-card rendering, duplicate-call de-looping with a forced final answer, XML-leak containment, and a parser fix that accepts closed <function=...> calls followed by trailing prose. Includes backend tests for the controller, strict parser, and GGUF route cursor reset.
---
 studio/backend/core/inference/inference.py    |    7 +-
 studio/backend/core/inference/llama_cpp.py    |  489 +++----
 studio/backend/core/inference/orchestrator.py |    9 +-
 .../core/inference/safetensors_agentic.py     |  385 +++---
 .../core/inference/tool_call_parser.py        |   86 +-
 .../core/inference/tool_loop_controller.py    |  410 ++++++
 studio/backend/routes/inference.py            |  274 ++--
 .../backend/tests/test_anthropic_messages.py  |   46 +
 .../tests/test_gguf_route_cursor_reset.py     |  224 ++++
 .../backend/tests/test_llama_cpp_tool_loop.py | 1151 +++++++++++++++++
 .../tests/test_safetensors_tool_loop.py       |  398 +++++-
 .../tests/test_tool_call_parser_strict.py     |  114 ++
 .../tests/test_tool_loop_controller.py        |  212 +++
 studio/backend/tests/test_tool_xml_strip.py   |   14 +
 .../src/features/chat/api/chat-adapter.ts     |  736 +++++++----
 15 files changed, 3651 insertions(+), 904 deletions(-)
 create mode 100644 studio/backend/core/inference/tool_loop_controller.py
 create mode 100644 studio/backend/tests/test_gguf_route_cursor_reset.py
 create mode 100644 studio/backend/tests/test_llama_cpp_tool_loop.py
 create mode 100644 studio/backend/tests/test_tool_call_parser_strict.py
 create mode 100644 studio/backend/tests/test_tool_loop_controller.py

diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index c44db7485d..8e202d161a 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -772,8 +772,11 @@ class InferenceBackend:
         from core.inference.safetensors_agentic import run_safetensors_tool_loop
         from core.inference.tools import execute_tool
 
-        def _single_turn(conv: list):
+        def _single_turn(conv: list, *, active_tools: Optional[list[dict]] = None):
             # conv already has the system message -- avoid double-prepend.
+            # `active_tools` is supplied by run_safetensors_tool_loop so one-shot
+            # tools such as render_html can be removed from later same-response prompts.
+            turn_tools = active_tools if active_tools is not None else tools
             yield from self._generate_chat_response_inner(
                 messages = conv,
                 system_prompt = "",
@@ -784,7 +787,7 @@ class InferenceBackend:
                 max_new_tokens = max_new_tokens,
                 repetition_penalty = repetition_penalty,
                 cancel_event = cancel_event,
-                tools = tools,
+                tools = turn_tools,
                 enable_thinking = enable_thinking,
                 reasoning_effort = reasoning_effort,
                 preserve_thinking = preserve_thinking,
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 4d4ae57afe..d12eb6e29e 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -24,7 +24,6 @@ import threading
 import time
 from pathlib import Path
 from typing import Generator, Iterable, List, Optional
-from urllib.parse import urlparse
 
 import httpx
 
@@ -51,9 +50,13 @@ from utils.subprocess_compat import (
     windows_hidden_subprocess_kwargs as _windows_hidden_subprocess_kwargs,
 )
 from core.inference.tool_call_parser import (
-    RENDER_HTML_REPEAT_NUDGE,
+    TOOL_XML_SIGNALS,
     parse_tool_calls_from_text as _shared_parse_tool_calls_from_text,
 )
+from core.inference.tool_loop_controller import (
+    ToolLoopController,
+    tool_event_provenance,
+)
 
 logger = get_logger(__name__)
 
@@ -76,7 +79,7 @@ _INTENT_SIGNAL = re.compile(
     r"\b(?:now i|next i)\b"
     r")"
 )
-_MAX_REPROMPTS = 3
+_MAX_REPROMPTS = 1
 
 # Without max_tokens, llama-server defaults n_predict = n_ctx (up to 262144 for
 # Qwen3.5), causing many-minute zombie decodes when cancel fails.
@@ -88,6 +91,30 @@ _MAX_REPROMPTS = 3
 _DEFAULT_MAX_TOKENS_FLOOR = 32768
 _DEFAULT_T_MAX_PREDICT_MS = 600_000  # 10 min
 _REPROMPT_MAX_CHARS = 2000
+_FORCED_REPEAT_PLAN_SIGNAL = re.compile(
+    r"\b(?:i\s+will|i'll|let\s+me|going\s+to|need\s+to|call|use|run|search|fetch|render)\b",
+    re.I,
+)
+_FINAL_ANSWER_SIGNAL = re.compile(
+    r"\b(?:final\s+answer|answer\s*:|here\s+is|here's|in\s+summary|result\s*:)\b",
+    re.I,
+)
+
+
+def _is_short_intent_without_action(text: str) -> bool:
+    stripped = text.strip()
+    return 0 < len(stripped) < _REPROMPT_MAX_CHARS and _INTENT_SIGNAL.search(stripped) is not None
+
+
+def _should_suppress_forced_no_tool_output(text: str) -> bool:
+    """Suppress only repeated forced-turn planning text, not final answers."""
+    stripped = text.strip()
+    if not stripped or len(stripped) >= _REPROMPT_MAX_CHARS:
+        return False
+    if _FINAL_ANSWER_SIGNAL.search(stripped):
+        return False
+    return _FORCED_REPEAT_PLAN_SIGNAL.search(stripped) is not None
+
 
 # ── Pre-compiled patterns for GGUF shard detection ───────────
 _SHARD_FULL_RE = re.compile(r"^(.*)-(\d{5})-of-(\d{5})\.gguf$")
@@ -3933,10 +3960,13 @@ class LlamaCppBackend:
     # ── Message building (OpenAI format) ──────────────────────────
 
     @staticmethod
-    def _parse_tool_calls_from_text(content: str) -> list[dict]:
-        """Thin wrapper around the shared tool_call_parser so safetensors
-        and llama_cpp pick up the same fixes."""
-        return _shared_parse_tool_calls_from_text(content)
+    def _parse_tool_calls_from_text(content: str, *, allow_incomplete: bool = True) -> list[dict]:
+        """Thin wrapper around the shared parser in tool_call_parser
+        so safetensors and llama_cpp pick up the same fixes."""
+        return _shared_parse_tool_calls_from_text(
+            content,
+            allow_incomplete = allow_incomplete,
+        )
 
     @staticmethod
     def _build_openai_messages(messages: list[dict], image_b64: Optional[str] = None) -> list[dict]:
@@ -4282,24 +4312,37 @@ class LlamaCppBackend:
         _accumulated_predicted_ms = 0.0
         _accumulated_predicted_n = 0
 
-        def _strip_tool_markup(text: str, *, final: bool = False) -> str:
-            if not auto_heal_tool_calls:
+        def _strip_tool_markup(
+            text: str,
+            *,
+            final: bool = False,
+            force: bool = False,
+        ) -> str:
+            if not (auto_heal_tool_calls or force):
                 return text
             return strip_tool_call_markup(text, final = final)
 
-        # XML prefixes that signal a tool call in content. Empty when
-        # auto_heal is disabled so the buffer never speculatively holds
-        # content for XML detection.
-        _TOOL_XML_SIGNALS = ("<tool_call>", "<function=") if auto_heal_tool_calls else ()
-        _MAX_BUFFER_CHARS = 32
+        def _strip_tool_markup_streaming(text: str, *, force: bool = False) -> str:
+            if not (auto_heal_tool_calls or force):
+                return text
+            for pat in _TOOL_ALL_PATS:
+                text = pat.sub("", text)
+            return text
 
-        # ── Duplicate tool-call detection ────────────────────────
-        # Track recent (tool_name, arguments) hashes to detect loops where
-        # the model repeats the exact same call. Retries after a transient
-        # failure are allowed (only block when the prior identical call
-        # succeeded).
-        _tool_call_history: list[tuple[str, bool]] = []  # (key, failed)
-        _render_html_succeeded = False
+        tool_controller = ToolLoopController(
+            tools = tools,
+            auto_heal_tool_calls = auto_heal_tool_calls,
+        )
+
+        def _tool_succeeded(tool_name: str) -> bool:
+            key_prefix = f"{tool_name}:"
+            return any(
+                record.executed and not record.is_error and record.key.startswith(key_prefix)
+                for record in tool_controller.history
+            )
+
+        _MAX_BUFFER_CHARS = 32
+        _append_budget_exhausted_nudge = True
 
         # ── Re-prompt on plan-without-action ─────────────────
         # When the model describes what it intends to do (forward-looking
@@ -4308,6 +4351,7 @@ class LlamaCppBackend:
         # "Hello!" won't match. Pattern compiled at module level
         # (_INTENT_SIGNAL).
         _reprompt_count = 0
+        _forced_tool_call_pending = False
 
         # Reserve extra iterations for re-prompts so they don't consume the
         # caller's tool-call budget; only when tool iterations are allowed.
@@ -4316,8 +4360,14 @@ class LlamaCppBackend:
             if cancel_event is not None and cancel_event.is_set():
                 return
 
-            # stream: True so we detect tool signals in the first 1-2 chunks
-            # without a non-streaming penalty.
+            active_tools = tool_controller.active_tools()
+            if not active_tools:
+                _append_budget_exhausted_nudge = False
+                break
+            _tool_xml_signals = TOOL_XML_SIGNALS if active_tools else ()
+
+            # Build payload -- stream: True so we detect tool signals
+            # in the first 1-2 chunks without a non-streaming penalty.
             payload = {
                 "messages": conversation,
                 "stream": True,
@@ -4328,7 +4378,7 @@ class LlamaCppBackend:
                 "min_p": min_p,
                 "repeat_penalty": repetition_penalty,
                 "presence_penalty": presence_penalty,
-                "tools": tools,
+                "tools": active_tools,
                 "tool_choice": "auto",
             }
             _reasoning_kw = self._request_reasoning_kwargs(
@@ -4372,6 +4422,7 @@ class LlamaCppBackend:
                 _stream_done = False
                 _last_emitted = ""
                 provisional_render_html_tool_call_ids = set()
+                _suppress_visible_output = _forced_tool_call_pending
 
                 stream_timeout = httpx.Timeout(
                     connect = 10,
@@ -4413,19 +4464,21 @@ class LlamaCppBackend:
                                     if detect_state == _S_STREAMING and in_thinking:
                                         if has_content_tokens:
                                             cumulative_display += "</think>"
-                                            yield {
-                                                "type": "content",
-                                                "text": _strip_tool_markup(
-                                                    cumulative_display,
-                                                    final = True,
-                                                ),
-                                            }
+                                            if not _suppress_visible_output:
+                                                yield {
+                                                    "type": "content",
+                                                    "text": _strip_tool_markup(
+                                                        cumulative_display,
+                                                        final = True,
+                                                    ),
+                                                }
                                         else:
                                             cumulative_display = reasoning_accum
-                                            yield {
-                                                "type": "content",
-                                                "text": cumulative_display,
-                                            }
+                                            if not _suppress_visible_output:
+                                                yield {
+                                                    "type": "content",
+                                                    "text": cumulative_display,
+                                                }
                                     _stream_done = True
                                     break  # exit inner while
                                 if not line.startswith("data: "):
@@ -4449,11 +4502,11 @@ class LlamaCppBackend:
                                     # ── Structured tool_calls ──
                                     tc_deltas = delta.get("tool_calls")
                                     if tc_deltas:
-                                        # Once visible content has been
-                                        # emitted, don't reclassify this turn
-                                        # as a tool call.
-                                        if _last_emitted:
-                                            continue
+                                        # llama-server can emit visible assistant
+                                        # preface content before native structured
+                                        # tool_calls. Preserve content_accum as
+                                        # the assistant pre-tool text and still
+                                        # drain/execute the structured call.
                                         has_structured_tc = True
                                         detect_state = _S_DRAINING
                                         for tc_d in tc_deltas:
@@ -4491,8 +4544,16 @@ class LlamaCppBackend:
                                             has_real_id = current_id != fallback_id
                                             if (
                                                 current_name == "render_html"
-                                                and not _render_html_succeeded
+                                                and not _tool_succeeded("render_html")
+                                                and any(
+                                                    (
+                                                        (tool.get("function") or {}).get("name")
+                                                        == "render_html"
+                                                    )
+                                                    for tool in active_tools
+                                                )
                                                 and not already_started
+                                                and not provisional_render_html_tool_call_ids
                                                 and has_real_id
                                             ):
                                                 provisional_render_html_tool_call_ids.add(
@@ -4503,6 +4564,9 @@ class LlamaCppBackend:
                                                     "tool_name": "render_html",
                                                     "tool_call_id": current_id,
                                                     "arguments": {},
+                                                    "provenance": tool_event_provenance(
+                                                        provisional = True,
+                                                    ),
                                                 }
                                         continue
 
@@ -4520,10 +4584,11 @@ class LlamaCppBackend:
                                                 cumulative_display += "<think>"
                                                 in_thinking = True
                                             cumulative_display += reasoning
-                                            yield {
-                                                "type": "content",
-                                                "text": cumulative_display,
-                                            }
+                                            if not _suppress_visible_output:
+                                                yield {
+                                                    "type": "content",
+                                                    "text": cumulative_display,
+                                                }
 
                                     # ── Content tokens ──
                                     token = delta.get("content", "")
@@ -4539,15 +4604,16 @@ class LlamaCppBackend:
                                                 cumulative_display += "</think>"
                                                 in_thinking = False
                                             cumulative_display += token
-                                            cleaned = _strip_tool_markup(
-                                                cumulative_display,
+                                            cleaned = _strip_tool_markup_streaming(
+                                                cumulative_display
                                             )
                                             if len(cleaned) > len(_last_emitted):
                                                 _last_emitted = cleaned
-                                                yield {
-                                                    "type": "content",
-                                                    "text": cleaned,
-                                                }
+                                                if not _suppress_visible_output:
+                                                    yield {
+                                                        "type": "content",
+                                                        "text": cleaned,
+                                                    }
 
                                         elif detect_state == _S_BUFFERING:
                                             content_buffer += token
@@ -4558,7 +4624,7 @@ class LlamaCppBackend:
                                             # Check tool signal prefixes.
                                             is_prefix = False
                                             is_match = False
-                                            for sig in _TOOL_XML_SIGNALS:
+                                            for sig in _tool_xml_signals:
                                                 if stripped_buf.startswith(sig):
                                                     is_match = True
                                                     break
@@ -4567,6 +4633,25 @@ class LlamaCppBackend:
                                                     break
 
                                             if is_match:
+                                                # Tool signal -- flush any visible
+                                                # prefix before DRAINING so the
+                                                # route sends it before tool_start.
+                                                if reasoning_accum:
+                                                    cumulative_display += "<think>"
+                                                    cumulative_display += reasoning_accum
+                                                    cumulative_display += "</think>"
+                                                cumulative_display += content_buffer
+                                                cleaned = _strip_tool_markup_streaming(
+                                                    cumulative_display,
+                                                    force = True,
+                                                )
+                                                if len(cleaned) > len(_last_emitted):
+                                                    _last_emitted = cleaned
+                                                    if not _suppress_visible_output:
+                                                        yield {
+                                                            "type": "content",
+                                                            "text": cleaned,
+                                                        }
                                                 detect_state = _S_DRAINING
                                             elif (
                                                 is_prefix and len(stripped_buf) < _MAX_BUFFER_CHARS
@@ -4587,10 +4672,11 @@ class LlamaCppBackend:
                                                 )
                                                 if len(cleaned) > len(_last_emitted):
                                                     _last_emitted = cleaned
-                                                    yield {
-                                                        "type": "content",
-                                                        "text": cleaned,
-                                                    }
+                                                    if not _suppress_visible_output:
+                                                        yield {
+                                                            "type": "content",
+                                                            "text": cleaned,
+                                                        }
 
                                 except json.JSONDecodeError:
                                     logger.debug(f"Skipping malformed SSE line: {line[:100]}")
@@ -4600,11 +4686,7 @@ class LlamaCppBackend:
                 # ── Resolve BUFFERING at stream end ──
                 if detect_state == _S_BUFFERING:
                     stripped_buf = content_buffer.lstrip()
-                    if (
-                        stripped_buf
-                        and auto_heal_tool_calls
-                        and any(s in stripped_buf for s in _TOOL_XML_SIGNALS)
-                    ):
+                    if stripped_buf and any(s in stripped_buf for s in _tool_xml_signals):
                         detect_state = _S_DRAINING
                     elif content_accum or reasoning_accum:
                         detect_state = _S_STREAMING
@@ -4615,22 +4697,24 @@ class LlamaCppBackend:
                                 cumulative_display += reasoning_accum
                                 cumulative_display += "</think>"
                             cumulative_display += content_buffer
-                            yield {
-                                "type": "content",
-                                "text": _strip_tool_markup(
-                                    cumulative_display,
-                                    final = True,
-                                ),
-                            }
+                            if not _suppress_visible_output:
+                                yield {
+                                    "type": "content",
+                                    "text": _strip_tool_markup(
+                                        cumulative_display,
+                                        final = True,
+                                    ),
+                                }
                         elif reasoning_accum and not has_content_tokens:
                             # Reasoning-only response: show reasoning as plain
                             # text, matching the final streaming pass for
                             # models that put everything in reasoning.
                             cumulative_display = reasoning_accum
-                            yield {
-                                "type": "content",
-                                "text": cumulative_display,
-                            }
+                            if not _suppress_visible_output:
+                                yield {
+                                    "type": "content",
+                                    "text": cumulative_display,
+                                }
                     else:
                         return
 
@@ -4641,9 +4725,10 @@ class LlamaCppBackend:
                     # synthesis streams correctly even if content was emitted
                     # before the tool XML.
                     _safety_tc = None
-                    if auto_heal_tool_calls and any(s in content_accum for s in _TOOL_XML_SIGNALS):
+                    if any(s in content_accum for s in _tool_xml_signals):
                         _safety_tc = self._parse_tool_calls_from_text(
                             content_accum,
+                            allow_incomplete = auto_heal_tool_calls,
                         )
                     if not _safety_tc:
                         # ── Re-prompt on plan-without-action ──
@@ -4656,11 +4741,18 @@ class LlamaCppBackend:
                         _stripped = content_accum.strip()
                         if not _stripped:
                             _stripped = reasoning_accum.strip()
+                        _render_html_already_done_intent = _tool_succeeded(
+                            "render_html"
+                        ) and re.search(
+                            r"(?i)\brender[_\s-]?html\b",
+                            _stripped,
+                        )
                         if (
-                            tools
+                            auto_heal_tool_calls
+                            and active_tools
+                            and not _render_html_already_done_intent
                             and _reprompt_count < _MAX_REPROMPTS
-                            and 0 < len(_stripped) < _REPROMPT_MAX_CHARS
-                            and _INTENT_SIGNAL.search(_stripped)
+                            and _is_short_intent_without_action(_stripped)
                         ):
                             _reprompt_count += 1
                             logger.info(
@@ -4675,19 +4767,21 @@ class LlamaCppBackend:
                                 }
                             )
                             available_tool_names = [
-                                tool.get("function", {}).get("name")
-                                for tool in tools
+                                (tool.get("function") or {}).get("name")
+                                for tool in active_tools
                                 if isinstance(tool, dict) and isinstance(tool.get("function"), dict)
                             ]
                             available_tool_names = [name for name in available_tool_names if name]
                             tool_hint = " or ".join(available_tool_names) or "an available tool"
+                            _forced_tool_call_pending = True
                             conversation.append(
                                 {
                                     "role": "user",
                                     "content": (
-                                        "STOP. Do NOT write code or explain. "
-                                        "You MUST call a tool NOW. "
-                                        f"Call {tool_hint} immediately."
+                                        "You have access to enabled tools. If a tool is needed to satisfy "
+                                        "the user's request or complete the action you described, call "
+                                        f"{tool_hint} now. If no tool is needed, provide the final answer "
+                                        "and follow the user's requested format."
                                     ),
                                 }
                             )
@@ -4700,7 +4794,28 @@ class LlamaCppBackend:
                             yield {"type": "status", "text": ""}
                             continue
 
-                        # Content already streamed; yield metadata.
+                        if _forced_tool_call_pending:
+                            _forced_tool_call_pending = False
+                            if not _should_suppress_forced_no_tool_output(_stripped):
+                                if cumulative_display:
+                                    forced_visible_text = _strip_tool_markup(
+                                        cumulative_display,
+                                        final = True,
+                                    )
+                                elif content_accum:
+                                    forced_visible_text = _strip_tool_markup(
+                                        content_accum,
+                                        final = True,
+                                    )
+                                else:
+                                    forced_visible_text = reasoning_accum
+                                if forced_visible_text:
+                                    yield {
+                                        "type": "content",
+                                        "text": forced_visible_text,
+                                    }
+
+                        # Content was already streamed.  Yield metadata.
                         yield {"type": "status", "text": ""}
                         _fu = _backfill_usage_from_timings(_iter_usage, _iter_timings) or {}
                         _fc = _fu.get("completion_tokens", 0)
@@ -4733,6 +4848,7 @@ class LlamaCppBackend:
                     content_text = _strip_tool_markup(
                         content_accum,
                         final = True,
+                        force = True,
                     )
                     logger.info(
                         f"Safety net: parsed {len(tool_calls)} tool call(s) "
@@ -4750,18 +4866,16 @@ class LlamaCppBackend:
                             for i in sorted(tool_calls_acc)
                             if (tool_calls_acc[i].get("function", {}).get("name", "").strip())
                         ] or None
-                    if (
-                        not tool_calls
-                        and auto_heal_tool_calls
-                        and any(s in content_accum for s in _TOOL_XML_SIGNALS)
-                    ):
+                    if not tool_calls and any(s in content_accum for s in _tool_xml_signals):
                         tool_calls = self._parse_tool_calls_from_text(
                             content_accum,
+                            allow_incomplete = auto_heal_tool_calls,
                         )
                     if tool_calls and not has_structured_tc:
                         content_text = _strip_tool_markup(
                             content_text,
                             final = True,
+                            force = True,
                         )
                     if tool_calls:
                         logger.info(
@@ -4812,163 +4926,68 @@ class LlamaCppBackend:
                 _accumulated_predicted_ms += _it.get("predicted_ms", 0)
                 _accumulated_predicted_n += _it.get("predicted_n", 0)
 
-                assistant_msg = {"role": "assistant", "content": content_text}
-                if tool_calls:
-                    assistant_msg["tool_calls"] = tool_calls
-                conversation.append(assistant_msg)
+                assistant_msg: dict = {"role": "assistant", "content": content_text}
+                assistant_appended = False
 
                 for tc in tool_calls or []:
                     func = tc.get("function", {})
                     tool_name = func.get("name", "")
-                    raw_args = func.get("arguments", {})
-
-                    if isinstance(raw_args, str):
-                        try:
-                            arguments = json.loads(raw_args)
-                        except (json.JSONDecodeError, ValueError):
-                            if auto_heal_tool_calls:
-                                heal_key = {
-                                    "python": "code",
-                                    "terminal": "command",
-                                    "render_html": "code",
-                                }.get(tool_name, "query")
-                                arguments = {heal_key: raw_args}
-                            else:
-                                arguments = {"raw": raw_args}
-                    else:
-                        arguments = raw_args
-
-                    if tool_name == "web_search":
-                        _ws_url = (arguments.get("url") or "").strip()
-                        if _ws_url:
-                            _parsed = urlparse(_ws_url)
-                            if _parsed.scheme in ("http", "https") and _parsed.hostname:
-                                _ws_host = _parsed.hostname
-                                if _ws_host.startswith("www."):
-                                    _ws_host = _ws_host[4:]
-                                status_text = f"Reading: {_ws_host}"
-                            else:
-                                status_text = "Reading page..."
-                        else:
-                            status_text = f"Searching: {arguments.get('query', '')}"
-                    elif tool_name == "python":
-                        preview = (arguments.get("code") or "").strip().split("\n")[0][:60]
-                        status_text = (
-                            f"Running Python: {preview}" if preview else "Running Python..."
-                        )
-                    elif tool_name == "terminal":
-                        cmd_preview = (arguments.get("command") or "")[:60]
-                        status_text = (
-                            f"Running: {cmd_preview}" if cmd_preview else "Running command..."
-                        )
-                    else:
-                        status_text = f"Calling: {tool_name}"
-                    _repeat_render_html = tool_name == "render_html" and _render_html_succeeded
-                    if not _repeat_render_html:
-                        yield {"type": "status", "text": status_text}
-
-                        yield {
-                            "type": "tool_start",
-                            "tool_name": tool_name,
-                            "tool_call_id": tc.get("id", ""),
-                            "arguments": arguments,
-                        }
-
-                    # ── Duplicate call detection ──────────────
-                    # str(dict) is stable here: arguments always come from
-                    # json.loads on the same model output within one request,
-                    # so insertion order is deterministic (Python 3.7+).
-                    _tc_key = tool_name + str(arguments)
-                    _prev = _tool_call_history[-1] if _tool_call_history else None
-                    if _repeat_render_html:
-                        result = RENDER_HTML_REPEAT_NUDGE
-                    elif _prev and _prev[0] == _tc_key and not _prev[1]:
-                        result = (
-                            "You already made this exact call. "
-                            "Do not repeat the same tool call. "
-                            "Try a different approach: fetch a URL "
-                            "from previous results, use Python to "
-                            "process data you already have, or "
-                            "provide your final answer now."
-                        )
-                    else:
-                        _effective_timeout = (
-                            None if tool_call_timeout >= 9999 else tool_call_timeout
-                        )
-                        # Guard against a tool not in the per-request
-                        # advertised set: filtered MCP names, an opted-out
-                        # built-in, or a stale name from a prior turn. Mirrors
-                        # the safetensors loop's allowed_tool_names check.
-                        _allowed = {
-                            (t.get("function") or {}).get("name")
-                            for t in (tools or [])
-                            if (t.get("function") or {}).get("name")
-                        }
-                        if _allowed and tool_name not in _allowed:
-                            result = (
-                                f"Error: tool '{tool_name}' is not enabled "
-                                "for this request. Use one of the enabled "
-                                "tools or provide a final answer."
-                            )
-                        else:
-                            result = execute_tool(
-                                tool_name,
-                                arguments,
-                                cancel_event = cancel_event,
-                                timeout = _effective_timeout,
-                                session_id = session_id,
-                            )
-
-                    if not _repeat_render_html:
-                        yield {
-                            "type": "tool_end",
-                            "tool_name": tool_name,
-                            "tool_call_id": tc.get("id", ""),
-                            "result": result,
-                        }
-
-                    # Nudge the model toward a different approach on errors.
-                    _error_prefixes = (
-                        "Error",
-                        "Search failed",
-                        "Execution error",
-                        "Blocked:",
-                        "Exit code",
-                        "Failed to fetch",
-                        "Failed to resolve",
-                        "No query provided",
+                    provisional_render_html_match = (
+                        tool_name == "render_html"
+                        and tc.get("id") in provisional_render_html_tool_call_ids
                     )
-                    _is_error = isinstance(result, str) and result.lstrip().startswith(
-                        _error_prefixes
+                    decision = tool_controller.prepare_call(
+                        tc,
+                        forced = _forced_tool_call_pending,
+                        provisional = provisional_render_html_match,
                     )
-                    if tool_name == "render_html" and not _is_error:
-                        _render_html_succeeded = True
-                    _tool_call_history.append((_tc_key, _is_error))
-                    # Strip image sentinel before feeding the result to the
-                    # LLM (the full result with sentinel is still yielded via
-                    # tool_end so the frontend can extract image paths).
-                    _result_content = result
-                    if "\n__IMAGES__:" in _result_content:
-                        _result_content = _result_content.rsplit("\n__IMAGES__:", 1)[0]
-                    if _is_error:
-                        _result_content = (
-                            _result_content + "\n\nThe tool call encountered an issue. "
-                            "Please try a different approach or rephrase your request."
+
+                    if not decision.should_execute:
+                        if content_text and not assistant_appended:
+                            conversation.append(assistant_msg)
+                            assistant_appended = True
+                        completion = tool_controller.record_noop(decision)
+                        conversation.append(completion.model_message())
+                        if _forced_tool_call_pending:
+                            _forced_tool_call_pending = False
+                        logger.info(
+                            "Suppressed local GGUF tool call as internal no-op: "
+                            f"action={decision.action} tool={decision.tool_name}"
+                        )
+                        break
+
+                    if not assistant_appended:
+                        assistant_msg["tool_calls"] = [decision.as_assistant_tool_call()]
+                        conversation.append(assistant_msg)
+                        assistant_appended = True
+                    else:
+                        assistant_msg.setdefault("tool_calls", []).append(
+                            decision.as_assistant_tool_call()
                         )
 
-                    tool_msg = {
-                        "role": "tool",
-                        "name": tool_name,
-                        "content": _result_content,
-                    }
-                    tool_call_id = tc.get("id")
-                    if tool_call_id:
-                        tool_msg["tool_call_id"] = tool_call_id
-                    conversation.append(tool_msg)
+                    yield {"type": "status", "text": decision.status_text}
+                    yield decision.tool_start_event()
 
-                # Clear tool status badge before the next generation.
+                    _effective_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
+                    result = execute_tool(
+                        decision.tool_name,
+                        decision.arguments,
+                        cancel_event = cancel_event,
+                        timeout = _effective_timeout,
+                        session_id = session_id,
+                    )
+                    completion = tool_controller.record_result(decision, result)
+                    yield completion.tool_end_event()
+                    conversation.append(completion.tool_message())
+
+                    if _forced_tool_call_pending:
+                        _forced_tool_call_pending = False
+
+                # Clear tool status badge before next generation/final pass.
                 yield {"type": "status", "text": ""}
-                # Continue so the model responds with tool context.
+                if tool_controller.force_final_answer or not tool_controller.active_tools():
+                    _append_budget_exhausted_nudge = False
+                    break
                 continue
 
             except httpx.ConnectError:
@@ -4982,7 +5001,7 @@ class LlamaCppBackend:
         # The model used all iterations without a final text response. Nudge
         # the final streaming pass to produce a useful answer instead of
         # continuing to request tools.
-        if max_tool_iterations > 0:
+        if max_tool_iterations > 0 and _append_budget_exhausted_nudge:
             conversation.append(
                 {
                     "role": "user",
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 0cbdea1337..74a011093a 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -836,8 +836,11 @@ class InferenceOrchestrator:
 
         max_new_tokens = max_tokens if max_tokens and max_tokens > 0 else 2048
 
-        def _single_turn(conv: list):
-            # ``conv`` already carries any system message.
+        def _single_turn(conv: list, *, active_tools: Optional[list[dict]] = None):
+            # ``conv`` already carries any system message. ``active_tools`` lets
+            # run_safetensors_tool_loop drop one-shot tools (e.g. render_html) from
+            # later same-response prompts.
+            turn_tools = active_tools if active_tools is not None else tools
             common_kwargs = dict(
                 messages = conv,
                 system_prompt = "",
@@ -849,7 +852,7 @@ class InferenceOrchestrator:
                 max_new_tokens = max_new_tokens,
                 repetition_penalty = repetition_penalty,
                 cancel_event = cancel_event,
-                tools = tools,
+                tools = turn_tools,
                 enable_thinking = enable_thinking,
                 reasoning_effort = reasoning_effort,
                 preserve_thinking = preserve_thinking,
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index acf6bd9eda..7d498a170d 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -14,25 +14,25 @@ parses tool calls from the cumulative text and dispatches via
 ``core.inference.tools``.
 """
 
-import json
 import re
 import threading
 from typing import Callable, Generator, Optional
-from urllib.parse import urlparse
 
 from loggers import get_logger
 
 from core.inference.tool_call_parser import (
+    _TOOL_ALL_PATS,
     BUDGET_EXHAUSTED_NUDGE,
-    DUPLICATE_CALL_NUDGE,
-    RENDER_HTML_REPEAT_NUDGE,
-    TOOL_ERROR_NUDGE,
-    TOOL_ERROR_PREFIXES,
     TOOL_XML_SIGNALS,
-    has_tool_signal,
     parse_tool_calls_from_text,
     strip_tool_markup,
 )
+from core.inference.tool_loop_controller import (
+    ToolLoopController,
+    coerce_tool_arguments,
+    status_for_tool,
+    tool_event_provenance,
+)
 
 
 logger = get_logger(__name__)
@@ -42,34 +42,34 @@ logger = get_logger(__name__)
 _MAX_BUFFER_CHARS = 32
 
 
+def strip_tool_markup_streaming(
+    text: str,
+    *,
+    auto_heal_tool_calls: bool = True,
+    tool_protocol_active: bool = False,
+) -> str:
+    """Strip open-ended tool XML from display text without trimming whitespace."""
+    if not (auto_heal_tool_calls or tool_protocol_active):
+        return text
+    for pat in _TOOL_ALL_PATS:
+        text = pat.sub("", text)
+    return text
+
+
+def _strip_tool_markup_final(
+    text: str,
+    *,
+    auto_heal_tool_calls: bool,
+    tool_protocol_active: bool = False,
+) -> str:
+    if not (auto_heal_tool_calls or tool_protocol_active):
+        return text
+    return strip_tool_markup(text, final = True)
+
+
 def _status_for_tool(tool_name: str, arguments: dict) -> str:
     """Return a human-readable status line matching the GGUF path."""
-    if tool_name == "web_search":
-        url = (arguments.get("url") or "").strip()
-        if url:
-            parsed = urlparse(url)
-            if parsed.scheme in ("http", "https") and parsed.hostname:
-                host = parsed.hostname
-                if host.startswith("www."):
-                    host = host[4:]
-                return f"Reading: {host}"
-            return "Reading page..."
-        query = arguments.get("query", "")
-        return f"Searching: {query}"
-    if tool_name == "python":
-        preview = (arguments.get("code") or "").strip().split("\n")[0][:60]
-        return f"Running Python: {preview}" if preview else "Running Python..."
-    if tool_name == "terminal":
-        preview = (arguments.get("command") or "")[:60]
-        return f"Running: {preview}" if preview else "Running command..."
-    return f"Calling: {tool_name}"
-
-
-_CANONICAL_HEAL_ARG = {
-    "python": "code",
-    "terminal": "command",
-    "render_html": "code",
-}
+    return status_for_tool(tool_name, arguments)
 
 
 _FUNCTION_SIGNAL_RE = re.compile(r"<function=([\w-]+)>")
@@ -93,34 +93,43 @@ def _detect_render_html_tool_start(content: str) -> bool:
     return False
 
 
+def _coerce_arguments_with_provenance(
+    raw_args,
+    *,
+    heal: bool,
+    tool_name: str = "",
+):
+    """Normalise tool ``arguments`` and report whether healing was applied."""
+    coerced = coerce_tool_arguments(raw_args, heal = heal, tool_name = tool_name)
+    return coerced.arguments, coerced.healed
+
+
 def _coerce_arguments(
     raw_args,
     *,
     heal: bool,
     tool_name: str = "",
 ) -> dict:
-    """Normalise tool ``arguments`` to a dict.
+    arguments, _ = _coerce_arguments_with_provenance(
+        raw_args,
+        heal = heal,
+        tool_name = tool_name,
+    )
+    return arguments
 
-    Some templates emit a JSON string, others a bare query string. With
-    ``heal=True`` a bare string becomes ``{<canonical_key>: ...}`` so a
-    Hermes-style call without proper JSON still runs. Canonical key per
-    tool: ``code`` for python, ``command`` for terminal, ``query`` otherwise
-    (e.g. web_search).
-    """
-    if isinstance(raw_args, dict):
-        return raw_args
-    if isinstance(raw_args, str):
-        try:
-            parsed = json.loads(raw_args)
-            if isinstance(parsed, dict):
-                return parsed
-        except (json.JSONDecodeError, ValueError):
-            pass
-        if heal:
-            key = _CANONICAL_HEAL_ARG.get(tool_name, "query")
-            return {key: raw_args}
-        return {"raw": raw_args}
-    return {}
+
+def _tool_event_provenance(**flags: object) -> dict[str, object]:
+    return tool_event_provenance(**flags)
+
+
+def _call_single_turn(single_turn, conversation: list, active_tools: list[dict]):
+    """Call a single-turn generator with active tool schemas when supported."""
+    try:
+        return single_turn(conversation, active_tools = active_tools)
+    except TypeError as exc:
+        if "active_tools" not in str(exc):
+            raise
+        return single_turn(conversation)
 
 
 def run_safetensors_tool_loop(
@@ -158,16 +167,21 @@ def run_safetensors_tool_loop(
     * ``{"type": "tool_end", "tool_name", "tool_call_id", "result"}``
     """
     conversation = list(messages)
-    tool_call_history: list[tuple[str, bool]] = []
-    render_html_succeeded = False
+    unrestricted_tools = not tools
+    tool_controller = ToolLoopController(
+        tools = None if unrestricted_tools else tools,
+        auto_heal_tool_calls = auto_heal_tool_calls,
+    )
     final_attempt_done = False
-    allowed_tool_names = {
-        (tool.get("function") or {}).get("name")
-        for tool in (tools or [])
-        if (tool.get("function") or {}).get("name")
-    }
     next_call_id = 0
 
+    def _tool_succeeded(tool_name: str) -> bool:
+        key_prefix = f"{tool_name}:"
+        return any(
+            record.executed and not record.is_error and record.key.startswith(key_prefix)
+            for record in tool_controller.history
+        )
+
     if max_tool_iterations <= 0:
         # 0 = disabled (same contract as the GGUF loop).
         yield {"type": "status", "text": ""}
@@ -181,6 +195,17 @@ def run_safetensors_tool_loop(
         if cancel_event is not None and cancel_event.is_set():
             return
 
+        if final_attempt_done:
+            active_tools: list[dict] = []
+        else:
+            active_tools = tool_controller.active_tools()
+            if not active_tools and not unrestricted_tools:
+                final_attempt_done = True
+                active_tools = []
+
+        tool_protocol_active = not final_attempt_done and (unrestricted_tools or bool(active_tools))
+        tool_xml_signals = TOOL_XML_SIGNALS if tool_protocol_active else ()
+
         detect_state = _state_buffering
         content_buffer = ""
         content_accum = ""
@@ -189,7 +214,7 @@ def run_safetensors_tool_loop(
         provisional_render_html_started = False
         provisional_render_html_id = f"call_{next_call_id}"
 
-        gen = single_turn(conversation)
+        gen = _call_single_turn(single_turn, conversation, active_tools)
         prev_cumulative = ""
 
         for cumulative in gen:
@@ -207,7 +232,11 @@ def run_safetensors_tool_loop(
 
             if detect_state == _state_draining:
                 if (
-                    not render_html_succeeded
+                    not _tool_succeeded("render_html")
+                    and any(
+                        ((tool.get("function") or {}).get("name") == "render_html")
+                        for tool in active_tools
+                    )
                     and not provisional_render_html_started
                     and _detect_render_html_tool_start(content_accum)
                 ):
@@ -217,26 +246,35 @@ def run_safetensors_tool_loop(
                         "tool_name": "render_html",
                         "tool_call_id": provisional_render_html_id,
                         "arguments": {},
+                        "provenance": _tool_event_provenance(provisional = True),
                     }
                 continue
 
             if detect_state == _state_streaming:
                 candidate = cumulative_display + delta
                 signal_pos = -1
-                for sig in TOOL_XML_SIGNALS:
+                for sig in tool_xml_signals:
                     p = candidate.find(sig)
                     if p >= 0 and (signal_pos < 0 or p < signal_pos):
                         signal_pos = p
                 if signal_pos >= 0:
                     before_tool = candidate[:signal_pos]
-                    cleaned_before = strip_tool_markup(before_tool)
+                    cleaned_before = strip_tool_markup_streaming(
+                        before_tool,
+                        auto_heal_tool_calls = auto_heal_tool_calls,
+                        tool_protocol_active = tool_protocol_active,
+                    )
                     if len(cleaned_before) > len(last_emitted):
                         last_emitted = cleaned_before
                         yield {"type": "content", "text": cleaned_before}
                     cumulative_display = candidate
                     detect_state = _state_draining
                     if (
-                        not render_html_succeeded
+                        not _tool_succeeded("render_html")
+                        and any(
+                            ((tool.get("function") or {}).get("name") == "render_html")
+                            for tool in active_tools
+                        )
                         and not provisional_render_html_started
                         and _detect_render_html_tool_start(content_accum)
                     ):
@@ -246,10 +284,15 @@ def run_safetensors_tool_loop(
                             "tool_name": "render_html",
                             "tool_call_id": provisional_render_html_id,
                             "arguments": {},
+                            "provenance": _tool_event_provenance(provisional = True),
                         }
                     continue
                 cumulative_display = candidate
-                cleaned = strip_tool_markup(cumulative_display)
+                cleaned = strip_tool_markup_streaming(
+                    cumulative_display,
+                    auto_heal_tool_calls = auto_heal_tool_calls,
+                    tool_protocol_active = tool_protocol_active,
+                )
                 if len(cleaned) > len(last_emitted):
                     last_emitted = cleaned
                     yield {"type": "content", "text": cleaned}
@@ -263,7 +306,7 @@ def run_safetensors_tool_loop(
 
             is_match = False
             is_prefix = False
-            for sig in TOOL_XML_SIGNALS:
+            for sig in tool_xml_signals:
                 if stripped.startswith(sig):
                     is_match = True
                     break
@@ -272,9 +315,24 @@ def run_safetensors_tool_loop(
                     break
 
             if is_match:
+                # Tool signal -- flush any visible prefix before DRAINING
+                # so the route sends it before tool_start.
+                cumulative_display += content_buffer
+                cleaned = strip_tool_markup_streaming(
+                    cumulative_display,
+                    auto_heal_tool_calls = auto_heal_tool_calls,
+                    tool_protocol_active = tool_protocol_active,
+                )
+                if len(cleaned) > len(last_emitted):
+                    last_emitted = cleaned
+                    yield {"type": "content", "text": cleaned}
                 detect_state = _state_draining
                 if (
-                    not render_html_succeeded
+                    not _tool_succeeded("render_html")
+                    and any(
+                        ((tool.get("function") or {}).get("name") == "render_html")
+                        for tool in active_tools
+                    )
                     and not provisional_render_html_started
                     and _detect_render_html_tool_start(content_accum)
                 ):
@@ -284,13 +342,18 @@ def run_safetensors_tool_loop(
                         "tool_name": "render_html",
                         "tool_call_id": provisional_render_html_id,
                         "arguments": {},
+                        "provenance": _tool_event_provenance(provisional = True),
                     }
             elif is_prefix and len(stripped) < _MAX_BUFFER_CHARS:
                 continue
             else:
                 detect_state = _state_streaming
                 cumulative_display += content_buffer
-                cleaned = strip_tool_markup(cumulative_display)
+                cleaned = strip_tool_markup_streaming(
+                    cumulative_display,
+                    auto_heal_tool_calls = auto_heal_tool_calls,
+                    tool_protocol_active = tool_protocol_active,
+                )
                 if len(cleaned) > len(last_emitted):
                     last_emitted = cleaned
                     yield {"type": "content", "text": cleaned}
@@ -302,14 +365,22 @@ def run_safetensors_tool_loop(
         if detect_state == _state_buffering:
             # Buffer never resolved -- tool XML or plain content?
             stripped = content_buffer.lstrip()
-            if stripped and has_tool_signal(stripped):
+            if (
+                stripped
+                and tool_protocol_active
+                and any(sig in stripped for sig in tool_xml_signals)
+            ):
                 detect_state = _state_draining
             else:
                 if content_buffer:
                     cumulative_display += content_buffer
                     yield {
                         "type": "content",
-                        "text": strip_tool_markup(cumulative_display, final = True),
+                        "text": _strip_tool_markup_final(
+                            cumulative_display,
+                            auto_heal_tool_calls = auto_heal_tool_calls,
+                            tool_protocol_active = False,
+                        ),
                     }
                 yield {"type": "status", "text": ""}
                 return
@@ -317,19 +388,30 @@ def run_safetensors_tool_loop(
         if detect_state == _state_streaming:
             # No tool detected mid-stream -- check for late tool XML.
             safety_tc = None
-            if has_tool_signal(content_accum):
+            saw_tool_signal = tool_protocol_active and any(
+                sig in content_accum for sig in tool_xml_signals
+            )
+            if saw_tool_signal:
                 safety_tc = parse_tool_calls_from_text(
                     content_accum,
                     id_offset = next_call_id,
+                    allow_incomplete = auto_heal_tool_calls,
                 )
             if not safety_tc:
-                # Final answer: streaming already emitted content. Skip the
-                # final=True re-strip so literal "<tool_call>" in prose
-                # survives when no real tool call parsed.
+                # Final answer: if a literal tool marker in prose was stripped
+                # during streaming but did not parse as a real call, restore the
+                # raw cumulative text for core callers. Route-level cleanup can
+                # still apply the Auto-Heal display policy.
+                if saw_tool_signal and content_accum:
+                    yield {"type": "content", "text": content_accum}
                 yield {"type": "status", "text": ""}
                 return
             tool_calls = safety_tc
-            content_text = strip_tool_markup(content_accum, final = True)
+            content_text = _strip_tool_markup_final(
+                content_accum,
+                auto_heal_tool_calls = auto_heal_tool_calls,
+                tool_protocol_active = True,
+            )
             logger.info(
                 "Safetensors safety net: parsed %d tool call(s) from streamed content",
                 len(tool_calls),
@@ -339,22 +421,39 @@ def run_safetensors_tool_loop(
             tool_calls = parse_tool_calls_from_text(
                 content_accum,
                 id_offset = next_call_id,
+                allow_incomplete = auto_heal_tool_calls,
             )
-            if not tool_calls and auto_heal_tool_calls:
-                # Parser found nothing -- surface raw content so literal
-                # "<tool_call>" prose is preserved.
+            if not tool_calls:
+                # Parser found nothing. Auto-Heal-enabled display cleanup
+                # strips unparseable tool XML; disabled Auto-Heal preserves
+                # the raw text so literal/malformed markup stays visible.
                 if content_accum:
-                    yield {"type": "content", "text": content_accum}
+                    yield {
+                        "type": "content",
+                        "text": _strip_tool_markup_final(
+                            content_accum,
+                            auto_heal_tool_calls = auto_heal_tool_calls,
+                            tool_protocol_active = False,
+                        ),
+                    }
                 if provisional_render_html_started:
                     yield {
                         "type": "tool_end",
                         "tool_name": "render_html",
                         "tool_call_id": provisional_render_html_id,
                         "result": "Error: render_html tool call could not be parsed.",
+                        "provenance": _tool_event_provenance(provisional = True),
                     }
                 yield {"type": "status", "text": ""}
                 return
-            content_text = strip_tool_markup(content_accum, final = True)
+            content_text = _strip_tool_markup_final(
+                content_accum,
+                auto_heal_tool_calls = auto_heal_tool_calls,
+                tool_protocol_active = True,
+            )
+
+        if tool_calls:
+            next_call_id += len(tool_calls)
 
         if final_attempt_done:
             # Final-answer turn re-called a tool -- stop the loop.
@@ -364,99 +463,69 @@ def run_safetensors_tool_loop(
             return
 
         assistant_msg: dict = {"role": "assistant", "content": content_text}
-        if tool_calls:
-            assistant_msg["tool_calls"] = tool_calls
-            next_call_id += len(tool_calls)
-        conversation.append(assistant_msg)
+        assistant_appended = False
 
         for tc in tool_calls or []:
             func = tc.get("function", {}) or {}
             tool_name = func.get("name", "") or ""
-            arguments = _coerce_arguments(
-                func.get("arguments", {}),
-                heal = auto_heal_tool_calls,
-                tool_name = tool_name,
+            provisional_match = (
+                provisional_render_html_started
+                and tool_name == "render_html"
+                and tc.get("id", "") == provisional_render_html_id
             )
+            decision = tool_controller.prepare_call(tc, provisional = provisional_match)
 
-            repeat_render_html = tool_name == "render_html" and render_html_succeeded
-            if not repeat_render_html:
-                yield {"type": "status", "text": _status_for_tool(tool_name, arguments)}
-                yield {
-                    "type": "tool_start",
-                    "tool_name": tool_name,
-                    "tool_call_id": tc.get("id", ""),
-                    "arguments": arguments,
-                }
-
-            tc_key = tool_name + str(arguments)
-            if repeat_render_html:
-                result = RENDER_HTML_REPEAT_NUDGE
-            elif allowed_tool_names and tool_name not in allowed_tool_names:
-                result = (
-                    f"Error: tool '{tool_name}' is not enabled for this "
-                    "request. Use one of the enabled tools or provide a "
-                    "final answer."
+            if not decision.should_execute:
+                if content_text and not assistant_appended:
+                    conversation.append(assistant_msg)
+                    assistant_appended = True
+                completion = tool_controller.record_noop(decision)
+                conversation.append(completion.model_message())
+                logger.info(
+                    "Suppressed local safetensors tool call as internal no-op: "
+                    f"action={decision.action} tool={decision.tool_name}"
                 )
+                break
+
+            if not assistant_appended:
+                assistant_msg["tool_calls"] = [decision.as_assistant_tool_call()]
+                conversation.append(assistant_msg)
+                assistant_appended = True
             else:
-                already_ran_ok = any(k == tc_key and not err for k, err in tool_call_history)
-                if already_ran_ok:
-                    result = DUPLICATE_CALL_NUDGE
-                else:
-                    eff_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
-                    try:
-                        result = execute_tool(
-                            tool_name,
-                            arguments,
-                            cancel_event = cancel_event,
-                            timeout = eff_timeout,
-                            session_id = session_id,
-                        )
-                    except Exception as exc:
-                        logger.exception("Tool %s raised: %s", tool_name, exc)
-                        result = f"Error: tool raised an exception: {exc}"
+                assistant_msg.setdefault("tool_calls", []).append(decision.as_assistant_tool_call())
 
-            if not repeat_render_html:
-                yield {
-                    "type": "tool_end",
-                    "tool_name": tool_name,
-                    "tool_call_id": tc.get("id", ""),
-                    "result": result,
-                }
+            yield {"type": "status", "text": decision.status_text}
+            yield decision.tool_start_event()
 
-            is_error = isinstance(result, str) and result.lstrip().startswith(TOOL_ERROR_PREFIXES)
-            if tool_name == "render_html" and not is_error:
-                render_html_succeeded = True
-            tool_call_history.append((tc_key, is_error))
+            eff_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
+            try:
+                result = execute_tool(
+                    decision.tool_name,
+                    decision.arguments,
+                    cancel_event = cancel_event,
+                    timeout = eff_timeout,
+                    session_id = session_id,
+                )
+            except Exception as exc:
+                logger.exception("Tool %s raised: %s", decision.tool_name, exc)
+                result = f"Error: tool raised an exception: {exc}"
 
-            # Strip frontend image sentinel from the model's view. Cut at the
-            # first occurrence so leading and consecutive sentinels both go.
-            result_for_model = result
-            if isinstance(result_for_model, str) and "__IMAGES__:" in result_for_model:
-                result_for_model = result_for_model.split("__IMAGES__:", 1)[0].rstrip()
-            if is_error:
-                result_for_model = result_for_model + TOOL_ERROR_NUDGE
-
-            tool_msg: dict = {
-                "role": "tool",
-                "name": tool_name,
-                "content": result_for_model,
-            }
-            tool_call_id = tc.get("id")
-            if tool_call_id:
-                tool_msg["tool_call_id"] = tool_call_id
-            conversation.append(tool_msg)
+            completion = tool_controller.record_result(decision, result)
+            yield completion.tool_end_event()
+            conversation.append(completion.tool_message())
 
         # Clear the status badge before the next turn.
         yield {"type": "status", "text": ""}
 
+        if tool_controller.force_final_answer:
+            final_attempt_done = True
+            continue
+        if not unrestricted_tools and not tool_controller.active_tools():
+            final_attempt_done = True
+            continue
         if iteration + 1 >= max_tool_iterations and not final_attempt_done:
             # Budget exhausted; nudge a final plain answer.
             final_attempt_done = True
-            conversation.append(
-                {
-                    "role": "user",
-                    "content": BUDGET_EXHAUSTED_NUDGE,
-                }
-            )
+            conversation.append({"role": "user", "content": BUDGET_EXHAUSTED_NUDGE})
 
     yield {"type": "status", "text": ""}
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index 601cd9f92b..ccb777db1c 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -102,7 +102,12 @@ def strip_tool_markup(text: str, *, final: bool = False) -> str:
     return text.strip() if final else text
 
 
-def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict]:
+def parse_tool_calls_from_text(
+    content: str,
+    *,
+    id_offset: int = 0,
+    allow_incomplete: bool = True,
+) -> list[dict]:
     """Parse OpenAI-format ``tool_calls`` from model text.
 
     Returns a list of ``{"id", "type", "function": {"name", "arguments"}}``
@@ -116,8 +121,10 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
     - XML-style function blocks:
       ``<function=name><parameter=k>v</parameter></function>``
 
-    Closing tags (``</tool_call>``, ``</function>``, ``</parameter>``)
-    are all optional since models frequently omit them.
+    ``allow_incomplete=True`` keeps the historical healing behavior for
+    missing closing tags. ``allow_incomplete=False`` accepts only
+    well-formed wrappers so disabled Auto-Heal can still parse valid
+    local tool protocol without repairing truncated output.
     """
     tool_calls: list[dict] = []
 
@@ -144,23 +151,28 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                 if depth == 0:
                     break
             i += 1
-        if depth == 0:
-            json_str = content[brace_start : i + 1]
-            try:
-                obj = json.loads(json_str)
-                tc = {
-                    "id": f"call_{id_offset + len(tool_calls)}",
-                    "type": "function",
-                    "function": {
-                        "name": obj.get("name", ""),
-                        "arguments": obj.get("arguments", {}),
-                    },
-                }
-                if isinstance(tc["function"]["arguments"], dict):
-                    tc["function"]["arguments"] = json.dumps(tc["function"]["arguments"])
-                tool_calls.append(tc)
-            except (json.JSONDecodeError, ValueError):
-                pass
+        if depth != 0:
+            continue
+        if not allow_incomplete:
+            tail_after_json = content[i + 1 :].lstrip()
+            if _TC_END_TAG_RE.match(tail_after_json) is None:
+                continue
+        json_str = content[brace_start : i + 1]
+        try:
+            obj = json.loads(json_str)
+            tc = {
+                "id": f"call_{id_offset + len(tool_calls)}",
+                "type": "function",
+                "function": {
+                    "name": obj.get("name", ""),
+                    "arguments": obj.get("arguments", {}),
+                },
+            }
+            if isinstance(tc["function"]["arguments"], dict):
+                tc["function"]["arguments"] = json.dumps(tc["function"]["arguments"])
+            tool_calls.append(tc)
+        except (json.JSONDecodeError, ValueError):
+            pass
 
     # Pattern 2: <function=name><parameter=k>v... -- closing tags optional;
     # </function> isn't a body boundary since code values can contain it.
@@ -181,7 +193,19 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                 body_end = len(content)
             body_end = min(body_end, next_func)
             body = content[body_start:body_end]
-            body = _TC_FUNC_CLOSE_RE.sub("", body)
+            if not allow_incomplete:
+                # Bound the body at the closing </function> tag rather than
+                # the end of the response, so a complete call followed by
+                # trailing prose is still accepted (matching the JSON-style
+                # <tool_call> path, which already tolerates trailing text).
+                # rfind picks the last </function>, so a literal </function>
+                # inside a code parameter value stays in the body.
+                close_idx = body.rfind(_FUNC_CLOSE_TAG)
+                if close_idx < 0:
+                    continue
+                body = body[:close_idx]
+            else:
+                body = _TC_FUNC_CLOSE_RE.sub("", body)
 
             arguments: dict = {}
             param_starts = list(_TC_PARAM_START_RE.finditer(body))
@@ -190,9 +214,16 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                 # </parameter> in code strings is preserved.
                 pm = param_starts[0]
                 val = body[pm.end() :]
-                val = _TC_PARAM_CLOSE_RE.sub("", val)
+                if not allow_incomplete:
+                    stripped_val = val.rstrip()
+                    if not stripped_val.endswith(_PARAM_CLOSE_TAG):
+                        continue
+                    val = stripped_val[: -len(_PARAM_CLOSE_TAG)]
+                else:
+                    val = _TC_PARAM_CLOSE_RE.sub("", val)
                 arguments[pm.group(1)] = val.strip()
             else:
+                valid_params = True
                 for pidx, pm in enumerate(param_starts):
                     param_name = pm.group(1)
                     val_start = pm.end()
@@ -202,8 +233,17 @@ def parse_tool_calls_from_text(content: str, *, id_offset: int = 0) -> list[dict
                         else len(body)
                     )
                     val = body[val_start:next_param]
-                    val = _TC_PARAM_CLOSE_RE.sub("", val)
+                    if not allow_incomplete:
+                        stripped_val = val.rstrip()
+                        if not stripped_val.endswith(_PARAM_CLOSE_TAG):
+                            valid_params = False
+                            break
+                        val = stripped_val[: -len(_PARAM_CLOSE_TAG)]
+                    else:
+                        val = _TC_PARAM_CLOSE_RE.sub("", val)
                     arguments[param_name] = val.strip()
+                if not valid_params:
+                    continue
 
             tc = {
                 "id": f"call_{id_offset + len(tool_calls)}",
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
new file mode 100644
index 0000000000..667ec7a33e
--- /dev/null
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Shared controller state for Studio local agentic tool loops.
+
+This module is intentionally dependency-light: it owns only per-response
+ledger state and value objects used by the GGUF and safetensors loops.
+Route/SSE conversion, tool execution, and model streaming stay in the
+backend-specific modules.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping, Sequence
+from urllib.parse import urlparse
+
+from core.inference.tool_call_parser import TOOL_ERROR_NUDGE, TOOL_ERROR_PREFIXES
+
+
+_CANONICAL_HEAL_ARG = {
+    "python": "code",
+    "terminal": "command",
+    "render_html": "code",
+}
+_ONE_SHOT_TOOLS = frozenset({"render_html"})
+
+NoopReason = Literal["duplicate", "disabled", "render_html_repeat"]
+ToolAction = Literal["execute", "duplicate", "disabled", "render_html_repeat"]
+
+
+@dataclass(frozen = True)
+class CoercedArguments:
+    """Normalized tool arguments plus whether healing changed the shape."""
+
+    arguments: dict[str, Any]
+    healed: bool = False
+
+
+@dataclass(frozen = True)
+class ToolCallDecision:
+    """Decision made before any visible tool event is emitted."""
+
+    action: ToolAction
+    tool_name: str
+    arguments: dict[str, Any]
+    tool_call_id: str = ""
+    key: str = ""
+    provenance: dict[str, Any] = field(default_factory = dict)
+    status_text: str = ""
+    noop_result: str = ""
+
+    @property
+    def should_execute(self) -> bool:
+        return self.action == "execute"
+
+    @property
+    def emit_visible_events(self) -> bool:
+        """Only real executions should become frontend-visible tool cards."""
+        return self.should_execute
+
+    @property
+    def noop_reason(self) -> NoopReason | None:
+        if self.action == "execute":
+            return None
+        return self.action
+
+    def tool_start_payload(self) -> dict[str, Any]:
+        """Build the payload fields for a real tool_start event."""
+        return {
+            "tool_name": self.tool_name,
+            "tool_call_id": self.tool_call_id,
+            "arguments": self.arguments,
+            "provenance": self.provenance,
+        }
+
+    def tool_start_event(self) -> dict[str, Any]:
+        """Build the existing backend event shape for a real execution."""
+        return {"type": "tool_start", **self.tool_start_payload()}
+
+    def as_assistant_tool_call(self) -> dict[str, Any]:
+        """Return an OpenAI-style tool_call with normalized arguments."""
+        tool_call: dict[str, Any] = {
+            "type": "function",
+            "function": {
+                "name": self.tool_name,
+                "arguments": json.dumps(
+                    self.arguments,
+                    ensure_ascii = False,
+                    sort_keys = True,
+                    separators = (",", ":"),
+                ),
+            },
+        }
+        if self.tool_call_id:
+            tool_call["id"] = self.tool_call_id
+        return tool_call
+
+
+@dataclass(frozen = True)
+class ToolCallCompletion:
+    """Result/nudge that should be fed back to the next model turn."""
+
+    decision: ToolCallDecision
+    result: str
+    is_error: bool = False
+    executed: bool = False
+
+    def tool_end_payload(self) -> dict[str, Any]:
+        """Build the payload fields for a real tool_end event."""
+        return {
+            "tool_name": self.decision.tool_name,
+            "tool_call_id": self.decision.tool_call_id,
+            "result": self.result,
+            "provenance": self.decision.provenance,
+        }
+
+    def tool_end_event(self) -> dict[str, Any]:
+        """Build the existing backend event shape for a real execution result."""
+        return {"type": "tool_end", **self.tool_end_payload()}
+
+    def tool_message(self) -> dict[str, Any]:
+        """Return the OpenAI-compatible tool message for a real execution."""
+        if not self.executed:
+            raise ValueError("No-op completions are internal nudges, not tool messages")
+        return self.model_message()
+
+    def model_message(self) -> dict[str, Any]:
+        """Return the internal message appended before the next generation.
+
+        Executed calls keep the existing OpenAI-compatible ``role=tool``
+        continuation. No-op controller decisions are not real tool output, so
+        they are fed back as a hidden user nudge rather than a normal tool
+        result.
+        """
+        if not self.executed:
+            return {"role": "user", "content": self.result}
+
+        content = strip_result_for_model(self.result)
+        if self.is_error:
+            content = content + TOOL_ERROR_NUDGE
+        message: dict[str, Any] = {
+            "role": "tool",
+            "name": self.decision.tool_name,
+            "content": content,
+        }
+        if self.decision.tool_call_id:
+            message["tool_call_id"] = self.decision.tool_call_id
+        return message
+
+
+@dataclass(frozen = True)
+class _ToolCallRecord:
+    key: str
+    is_error: bool
+    executed: bool
+    action: ToolAction
+
+
+def _json_default(value: Any) -> str:
+    return str(value)
+
+
+def canonical_tool_call_key(tool_name: str, arguments: Mapping[str, Any]) -> str:
+    """Return a stable key for duplicate detection."""
+    canonical_args = json.dumps(
+        dict(arguments),
+        ensure_ascii = False,
+        sort_keys = True,
+        separators = (",", ":"),
+        default = _json_default,
+    )
+    return f"{tool_name}:{canonical_args}"
+
+
+def coerce_tool_arguments(
+    raw_args: Any,
+    *,
+    heal: bool,
+    tool_name: str = "",
+) -> CoercedArguments:
+    """Normalize model-emitted ``function.arguments`` to a dictionary."""
+    if isinstance(raw_args, Mapping):
+        return CoercedArguments(dict(raw_args), False)
+    if isinstance(raw_args, str):
+        try:
+            parsed = json.loads(raw_args)
+            if isinstance(parsed, Mapping):
+                return CoercedArguments(dict(parsed), False)
+        except (json.JSONDecodeError, ValueError):
+            pass
+        if heal:
+            key = _CANONICAL_HEAL_ARG.get(tool_name, "query")
+            return CoercedArguments({key: raw_args}, True)
+        return CoercedArguments({"raw": raw_args}, False)
+    return CoercedArguments({}, False)
+
+
+def tool_event_provenance(**flags: object) -> dict[str, object]:
+    """Return provenance metadata with falsey flags omitted."""
+    provenance: dict[str, object] = {"source": "local"}
+    for key, value in flags.items():
+        if value is not None and value is not False:
+            provenance[key] = value
+    return provenance
+
+
+def status_for_tool(tool_name: str, arguments: Mapping[str, Any]) -> str:
+    """Return the status text already used by local tool streams."""
+    if tool_name == "web_search":
+        url = str(arguments.get("url") or "").strip()
+        if url:
+            parsed = urlparse(url)
+            if parsed.scheme in ("http", "https") and parsed.hostname:
+                host = parsed.hostname
+                if host.startswith("www."):
+                    host = host[4:]
+                return f"Reading: {host}"
+            return "Reading page..."
+        return f"Searching: {arguments.get('query', '')}"
+    if tool_name == "python":
+        preview = str(arguments.get("code") or "").strip().split("\n")[0][:60]
+        return f"Running Python: {preview}" if preview else "Running Python..."
+    if tool_name == "terminal":
+        preview = str(arguments.get("command") or "")[:60]
+        return f"Running: {preview}" if preview else "Running command..."
+    return f"Calling: {tool_name}"
+
+
+def is_tool_error(result: str) -> bool:
+    return isinstance(result, str) and result.lstrip().startswith(TOOL_ERROR_PREFIXES)
+
+
+def strip_result_for_model(result: str) -> str:
+    """Remove frontend-only image sentinels before feeding the model."""
+    if "__IMAGES__:" in result:
+        return result.split("__IMAGES__:", 1)[0].rstrip()
+    return result
+
+
+def _tool_name_from_schema(tool: Mapping[str, Any]) -> str:
+    function = tool.get("function")
+    if not isinstance(function, Mapping):
+        return ""
+    name = function.get("name")
+    return str(name or "")
+
+
+def _noop_result(reason: NoopReason, tool_name: str) -> str:
+    if reason == "duplicate":
+        return (
+            "The previous tool request was not executed because this exact "
+            "tool call already completed successfully. Do not repeat the same "
+            "tool call. Continue with a different enabled tool if that would "
+            "materially help, or provide the final answer if you have enough "
+            "information."
+        )
+    if reason == "render_html_repeat":
+        return (
+            "render_html completed successfully earlier in this assistant "
+            "response. Do not call render_html again unless the user asks for "
+            "changes. Do not mention this internal instruction. Provide only "
+            "the requested final note or answer."
+        )
+    return (
+        f"The previous tool request was not executed because tool "
+        f"'{tool_name}' is not enabled for this request. Provide the "
+        "final answer now without calling more tools."
+    )
+
+
+class ToolLoopController:
+    """Per-response ledger for local agentic tool loops."""
+
+    def __init__(
+        self,
+        *,
+        tools: Sequence[Mapping[str, Any]] | None,
+        auto_heal_tool_calls: bool = True,
+        one_shot_tools: frozenset[str] = _ONE_SHOT_TOOLS,
+        duplicate_noop_limit: int = 2,
+    ) -> None:
+        self._restrict_to_allowed = tools is not None
+        self._tools = [copy.deepcopy(dict(tool)) for tool in (tools or [])]
+        self._allowed_tool_names = {
+            name for name in (_tool_name_from_schema(tool) for tool in self._tools) if name
+        }
+        self._auto_heal_tool_calls = auto_heal_tool_calls
+        self._one_shot_tools = one_shot_tools
+        self._completed_one_shot_tools: set[str] = set()
+        self._successful_keys: set[str] = set()
+        self._duplicate_noop_counts: dict[str, int] = {}
+        self._duplicate_noop_limit = max(1, duplicate_noop_limit)
+        self._history: list[_ToolCallRecord] = []
+        self._force_final_answer = False
+
+    @property
+    def history(self) -> tuple[_ToolCallRecord, ...]:
+        return tuple(self._history)
+
+    @property
+    def force_final_answer(self) -> bool:
+        """True once a terminal no-op should transition to a no-tools pass."""
+        return self._force_final_answer
+
+    def active_tools(self) -> list[dict[str, Any]]:
+        """Return tools still worth advertising to the next model call."""
+        if self._force_final_answer:
+            return []
+        active: list[dict[str, Any]] = []
+        for tool in self._tools:
+            name = _tool_name_from_schema(tool)
+            if name in self._completed_one_shot_tools:
+                continue
+            active.append(copy.deepcopy(tool))
+        return active
+
+    def prepare_call(
+        self,
+        tool_call: Mapping[str, Any],
+        *,
+        forced: bool = False,
+        provisional: bool = False,
+    ) -> ToolCallDecision:
+        """Classify a parsed tool call before any visible event is yielded."""
+        function = tool_call.get("function")
+        function = function if isinstance(function, Mapping) else {}
+        tool_name = str(function.get("name") or "").strip()
+        coerced = coerce_tool_arguments(
+            function.get("arguments", {}),
+            heal = self._auto_heal_tool_calls,
+            tool_name = tool_name,
+        )
+        key = canonical_tool_call_key(tool_name, coerced.arguments)
+        provenance = tool_event_provenance(
+            healed = coerced.healed,
+            forced = forced,
+            provisional = provisional,
+        )
+        action: ToolAction = "execute"
+        noop = ""
+        if tool_name in self._completed_one_shot_tools:
+            action = "render_html_repeat"
+            noop = _noop_result("render_html_repeat", tool_name)
+        elif self._restrict_to_allowed and tool_name not in self._allowed_tool_names:
+            action = "disabled"
+            noop = _noop_result("disabled", tool_name)
+        elif key in self._successful_keys:
+            action = "duplicate"
+            noop = _noop_result("duplicate", tool_name)
+
+        return ToolCallDecision(
+            action = action,
+            tool_name = tool_name,
+            arguments = coerced.arguments,
+            tool_call_id = str(tool_call.get("id") or ""),
+            key = key,
+            provenance = provenance,
+            status_text = status_for_tool(tool_name, coerced.arguments),
+            noop_result = noop,
+        )
+
+    def record_result(self, decision: ToolCallDecision, result: Any) -> ToolCallCompletion:
+        """Record a real tool execution and return model/frontend payload helpers."""
+        result_text = result if isinstance(result, str) else str(result)
+        failed = is_tool_error(result_text)
+        self._history.append(
+            _ToolCallRecord(
+                key = decision.key,
+                is_error = failed,
+                executed = True,
+                action = decision.action,
+            )
+        )
+        if not failed:
+            self._successful_keys.add(decision.key)
+            if decision.tool_name in self._one_shot_tools:
+                self._completed_one_shot_tools.add(decision.tool_name)
+        return ToolCallCompletion(
+            decision = decision,
+            result = result_text,
+            is_error = failed,
+            executed = True,
+        )
+
+    def record_noop(self, decision: ToolCallDecision) -> ToolCallCompletion:
+        """Record a controller no-op without creating visible tool output."""
+        self._history.append(
+            _ToolCallRecord(
+                key = decision.key,
+                is_error = False,
+                executed = False,
+                action = decision.action,
+            )
+        )
+        if decision.action == "duplicate":
+            duplicate_count = self._duplicate_noop_counts.get(decision.key, 0) + 1
+            self._duplicate_noop_counts[decision.key] = duplicate_count
+            if duplicate_count >= self._duplicate_noop_limit:
+                self._force_final_answer = True
+        elif decision.action in ("disabled", "render_html_repeat"):
+            self._force_final_answer = True
+        return ToolCallCompletion(
+            decision = decision,
+            result = decision.noop_result,
+            is_error = False,
+            executed = False,
+        )
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index cf264d0dc9..28634396f5 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -538,27 +538,63 @@ async def _await_cancel_then_close(cancel_event, resp) -> None:
         return
 
 
-# Appended to tool-use nudge to discourage plan-without-action.
-# Gate render_html guidance to turns where the artifact tool is in the schema;
-# otherwise small local models hallucinate a missing tool call instead of the
-# fenced-HTML fallback prompt.
-_TOOL_ACTION_NUDGE = (
-    " IMPORTANT: Always call tools directly -- never write code yourself."
-    " Never describe what you plan to do -- just call the tool immediately."
-    " For non-artifact code requests, call the python tool when it is available."
-    " For factual questions that require current information, call web_search when it is available."
-    " Do NOT output raw code blocks when an enabled tool can satisfy the request."
+# Centralized local/server tool nudge. Keep render_html guidance gated to turns
+# where the artifact tool is actually present in the tool schema; otherwise
+# small local models can hallucinate a missing tool call instead of following
+# the fenced-HTML fallback prompt.
+_TOOL_BASE_NUDGE = (
+    "Tools are available when they materially improve the answer. Use an enabled "
+    "tool for current facts, calculations, code execution, or artifacts when it "
+    "materially helps; otherwise answer normally and follow the user's requested "
+    "format."
 )
-_ARTIFACT_TOOL_ACTION_NUDGE = (
-    " For HTML, CSS, or JavaScript artifact requests, call render_html once when "
-    "it is available. After render_html succeeds, do not call it again in the "
-    "same response unless the user asks for changes. Future user requests for "
-    "new artifacts may call render_html once."
+_TOOL_WEB_COMPACT_TIP = "When using web_search, do not repeat the same search query."
+_TOOL_WEB_EXPANDED_TIP = (
+    "When using web_search and a result URL is relevant, fetch its full content "
+    "by calling web_search with the url parameter. Do not repeat the same search "
+    "query. If a search returns no useful results, try rephrasing or fetching a "
+    "result URL directly."
+)
+_TOOL_CODE_TIP = (
+    "Use code execution for math, calculations, data processing, or to parse "
+    "and analyze information from tool results."
+)
+_TOOL_ARTIFACT_TIP = (
+    "For HTML, CSS, or JavaScript artifact requests, call render_html once when "
+    "it is available with one complete self-contained HTML document in the code "
+    "argument. After render_html succeeds, do not call it again in the same "
+    "response unless the user asks for changes. Future user requests for new "
+    "artifacts may call render_html once."
 )
 
 
-def _tool_action_nudge(has_artifact: bool) -> str:
-    return _TOOL_ACTION_NUDGE + (_ARTIFACT_TOOL_ACTION_NUDGE if has_artifact else "")
+def _build_tool_action_nudge(*, tools: list[dict], model_name: str) -> str:
+    tool_names = {
+        (tool.get("function") or {}).get("name")
+        for tool in tools
+        if isinstance(tool, dict) and isinstance(tool.get("function"), dict)
+    }
+    has_web = "web_search" in tool_names
+    has_code = "python" in tool_names or "terminal" in tool_names
+    has_artifact = "render_html" in tool_names
+    if not (has_web or has_code or has_artifact):
+        return ""
+
+    model_size_b = _extract_model_size_b(model_name)
+    compact_web_tip = model_size_b is not None and model_size_b < 9
+    tool_tip_parts: list[str] = []
+    if has_web:
+        tool_tip_parts.append(_TOOL_WEB_COMPACT_TIP if compact_web_tip else _TOOL_WEB_EXPANDED_TIP)
+    if has_code:
+        tool_tip_parts.append(_TOOL_CODE_TIP)
+    if has_artifact:
+        tool_tip_parts.append(_TOOL_ARTIFACT_TIP)
+    return (
+        f"The current date is {_date.today().isoformat()}. "
+        + _TOOL_BASE_NUDGE
+        + " "
+        + " ".join(tool_tip_parts)
+    )
 
 
 # Strip tool-call XML the speculative buffer in core/inference/llama_cpp.py
@@ -576,6 +612,15 @@ _TOOL_XML_RE = _re.compile(
     r"|</parameter>\s*\Z",
     _re.DOTALL,
 )
+
+
+def _strip_tool_xml_for_display(text: str, *, auto_heal_tool_calls: bool) -> str:
+    """Apply route-level XML leak cleanup only when Auto-Heal is enabled."""
+    if not auto_heal_tool_calls:
+        return text
+    return _TOOL_XML_RE.sub("", text)
+
+
 logger = get_logger(__name__)
 
 
@@ -2722,69 +2767,30 @@ async def openai_chat_completions(
 
         if use_tools:
             # ── Tool-use system prompt nudge ──────────────────────
-            _tool_names = {t["function"]["name"] for t in tools_to_use}
-            _has_web = "web_search" in _tool_names
-            _has_code = "python" in _tool_names or "terminal" in _tool_names
-            _has_artifact = "render_html" in _tool_names
-
-            _date_line = f"The current date is {_date.today().isoformat()}."
-
-            # Small models (<9B) struggle with multi-step search plans, so
-            # simplify the web tips to avoid plan-then-stall behavior.
-            _model_size_b = _extract_model_size_b(model_name)
-            _is_small_model = _model_size_b is not None and _model_size_b < 9
-
-            if _is_small_model:
-                _web_tips = "Do not repeat the same search query."
-            else:
-                _web_tips = (
-                    "When you search and find a relevant URL in the results, "
-                    "fetch its full content by calling web_search with the url parameter. "
-                    "Do not repeat the same search query. If a search returns "
-                    "no useful results, try rephrasing or fetching a result URL directly."
-                )
-            _code_tips = (
-                "Use code execution for math, calculations, data processing, "
-                "or to parse and analyze information from tool results."
+            _nudge = _build_tool_action_nudge(
+                tools = tools_to_use,
+                model_name = model_name,
             )
-            _artifact_tips = (
-                "Use render_html for HTML, CSS, or JavaScript artifact requests "
-                "with one complete self-contained HTML document in the code argument. "
-                "Call it once, then do not call it again in the same response unless "
-                "the user asks for changes. Future user requests for new artifacts may "
-                "call render_html once."
-            )
-
-            _tool_tip_parts = []
-            if _has_web:
-                _tool_tip_parts.append(_web_tips)
-            if _has_code:
-                _tool_tip_parts.append(_code_tips)
-            if _has_artifact:
-                _tool_tip_parts.append(_artifact_tips)
-
-            if _tool_tip_parts:
-                _nudge = (
-                    _date_line + " "
-                    "You have access to tools. When appropriate, prefer using "
-                    "tools rather than answering from memory. " + " ".join(_tool_tip_parts)
-                )
-            else:
-                _nudge = ""
 
             if _nudge:
-                _nudge += _tool_action_nudge(_has_artifact)
-                # Append nudge to system prompt (preserve the user's prompt)
+                # Append nudge to system prompt (preserve user's prompt)
                 if system_prompt:
                     system_prompt = system_prompt.rstrip() + "\n\n" + _nudge
                 else:
                     system_prompt = _nudge
                 gguf_messages = _set_or_prepend_system_message(gguf_messages, system_prompt)
 
+            _gguf_auto_heal_tool_calls = (
+                payload.auto_heal_tool_calls if payload.auto_heal_tool_calls is not None else True
+            )
+
             # ── Strip stale tool-call XML from conversation history ─
             for _msg in gguf_messages:
                 if _msg.get("role") == "assistant" and isinstance(_msg.get("content"), str):
-                    _msg["content"] = _TOOL_XML_RE.sub("", _msg["content"]).strip()
+                    _msg["content"] = _strip_tool_xml_for_display(
+                        _msg["content"],
+                        auto_heal_tool_calls = _gguf_auto_heal_tool_calls,
+                    ).strip()
 
             def gguf_generate_with_tools():
                 return llama_backend.generate_chat_completion_with_tools(
@@ -2801,9 +2807,7 @@ async def openai_chat_completions(
                     enable_thinking = payload.enable_thinking,
                     reasoning_effort = payload.reasoning_effort,
                     preserve_thinking = payload.preserve_thinking,
-                    auto_heal_tool_calls = payload.auto_heal_tool_calls
-                    if payload.auto_heal_tool_calls is not None
-                    else True,
+                    auto_heal_tool_calls = _gguf_auto_heal_tool_calls,
                     max_tool_iterations = payload.max_tool_calls_per_message
                     if payload.max_tool_calls_per_message is not None
                     else 25,
@@ -2884,7 +2888,10 @@ async def openai_chat_completions(
                         # cumulative then diff against the last sanitized
                         # snapshot so cross-chunk XML tags are handled correctly.
                         raw_cumulative = event.get("text", "")
-                        clean_cumulative = _TOOL_XML_RE.sub("", raw_cumulative)
+                        clean_cumulative = _strip_tool_xml_for_display(
+                            raw_cumulative,
+                            auto_heal_tool_calls = _gguf_auto_heal_tool_calls,
+                        )
                         new_text = clean_cumulative[len(prev_text) :]
                         prev_text = clean_cumulative
                         if not new_text:
@@ -3228,61 +3235,22 @@ async def openai_chat_completions(
             _sf_use_tools = False
 
     if _sf_use_tools:
-        _sf_tool_names = {t["function"]["name"] for t in _sf_tools_to_use}
-        _sf_has_web = "web_search" in _sf_tool_names
-        _sf_has_code = "python" in _sf_tool_names or "terminal" in _sf_tool_names
-        _sf_has_artifact = "render_html" in _sf_tool_names
-
-        _sf_date_line = f"The current date is {_date.today().isoformat()}."
-        _sf_model_size_b = _extract_model_size_b(model_name)
-        _sf_is_small_model = _sf_model_size_b is not None and _sf_model_size_b < 9
-
-        if _sf_is_small_model:
-            _sf_web_tips = "Do not repeat the same search query."
-        else:
-            _sf_web_tips = (
-                "When you search and find a relevant URL in the results, "
-                "fetch its full content by calling web_search with the url parameter. "
-                "Do not repeat the same search query. If a search returns "
-                "no useful results, try rephrasing or fetching a result URL directly."
-            )
-        _sf_code_tips = (
-            "Use code execution for math, calculations, data processing, "
-            "or to parse and analyze information from tool results."
+        _sf_nudge = _build_tool_action_nudge(
+            tools = _sf_tools_to_use,
+            model_name = model_name,
         )
-        _sf_artifact_tips = (
-            "Use render_html for HTML, CSS, or JavaScript artifact requests "
-            "with one complete self-contained HTML document in the code argument. "
-            "Call it once, then do not call it again in the same response unless "
-            "the user asks for changes. Future user requests for new artifacts may "
-            "call render_html once."
-        )
-
-        _sf_tool_tip_parts = []
-        if _sf_has_web:
-            _sf_tool_tip_parts.append(_sf_web_tips)
-        if _sf_has_code:
-            _sf_tool_tip_parts.append(_sf_code_tips)
-        if _sf_has_artifact:
-            _sf_tool_tip_parts.append(_sf_artifact_tips)
-
-        if _sf_tool_tip_parts:
-            _sf_nudge = (
-                _sf_date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "tools rather than answering from memory. " + " ".join(_sf_tool_tip_parts)
-            )
-        else:
-            _sf_nudge = ""
 
         _sf_system_prompt = system_prompt
         if _sf_nudge:
-            _sf_nudge += _tool_action_nudge(_sf_has_artifact)
             if _sf_system_prompt:
                 _sf_system_prompt = _sf_system_prompt.rstrip() + "\n\n" + _sf_nudge
             else:
                 _sf_system_prompt = _sf_nudge
 
+        _sf_auto_heal_tool_calls = (
+            payload.auto_heal_tool_calls if payload.auto_heal_tool_calls is not None else True
+        )
+
         # Strip stale tool-call XML from prior assistant turns.
         _sf_chat_messages = []
         for _msg in chat_messages:
@@ -3290,7 +3258,10 @@ async def openai_chat_completions(
                 _sf_chat_messages.append(
                     {
                         **_msg,
-                        "content": _TOOL_XML_RE.sub("", _msg["content"]).strip(),
+                        "content": _strip_tool_xml_for_display(
+                            _msg["content"],
+                            auto_heal_tool_calls = _sf_auto_heal_tool_calls,
+                        ).strip(),
                     }
                 )
             else:
@@ -3314,9 +3285,7 @@ async def openai_chat_completions(
                 enable_thinking = payload.enable_thinking,
                 reasoning_effort = payload.reasoning_effort,
                 preserve_thinking = payload.preserve_thinking,
-                auto_heal_tool_calls = payload.auto_heal_tool_calls
-                if payload.auto_heal_tool_calls is not None
-                else True,
+                auto_heal_tool_calls = _sf_auto_heal_tool_calls,
                 max_tool_iterations = _sf_tool_budget,
                 tool_call_timeout = payload.tool_call_timeout
                 if payload.tool_call_timeout is not None
@@ -3381,7 +3350,10 @@ async def openai_chat_completions(
 
                     # Diff cumulative cleaned text against last snapshot.
                     raw_cumulative = event.get("text", "")
-                    clean_cumulative = _TOOL_XML_RE.sub("", raw_cumulative)
+                    clean_cumulative = _strip_tool_xml_for_display(
+                        raw_cumulative,
+                        auto_heal_tool_calls = _sf_auto_heal_tool_calls,
+                    )
                     new_text = clean_cumulative[len(prev_text) :]
                     prev_text = clean_cumulative
                     if not new_text:
@@ -3472,7 +3444,10 @@ async def openai_chat_completions(
                     if cancel_event.is_set():
                         break
                     if event.get("type") == "content":
-                        full_text = _TOOL_XML_RE.sub("", event.get("text", ""))
+                        full_text = _strip_tool_xml_for_display(
+                            event.get("text", ""),
+                            auto_heal_tool_calls = _sf_auto_heal_tool_calls,
+                        )
                 return full_text
 
             content_text = await asyncio.to_thread(_drain_to_text)
@@ -4942,56 +4917,13 @@ async def anthropic_messages(
             payload.enabled_tools,
         )
 
-        # Build tool-use system prompt nudge (same as /chat/completions)
-        _tool_names = {t["function"]["name"] for t in openai_tools}
-        _has_web = "web_search" in _tool_names
-        _has_code = "python" in _tool_names or "terminal" in _tool_names
-        _has_artifact = "render_html" in _tool_names
-
-        _date_line = f"The current date is {_date.today().isoformat()}."
-        _model_size_b = _extract_model_size_b(model_name)
-        _is_small_model = _model_size_b is not None and _model_size_b < 9
-
-        if _is_small_model:
-            _web_tips = "Do not repeat the same search query."
-        else:
-            _web_tips = (
-                "When you search and find a relevant URL in the results, "
-                "fetch its full content by calling web_search with the url parameter. "
-                "Do not repeat the same search query. If a search returns "
-                "no useful results, try rephrasing or fetching a result URL directly."
-            )
-        _code_tips = (
-            "Use code execution for math, calculations, data processing, "
-            "or to parse and analyze information from tool results."
+        # Build tool-use system prompt nudge (same logic as /chat/completions)
+        _nudge = _build_tool_action_nudge(
+            tools = openai_tools,
+            model_name = model_name,
         )
-        _artifact_tips = (
-            "Use render_html for HTML, CSS, or JavaScript artifact requests "
-            "with one complete self-contained HTML document in the code argument. "
-            "Call it once, then do not call it again in the same response unless "
-            "the user asks for changes. Future user requests for new artifacts may "
-            "call render_html once."
-        )
-
-        _tool_tip_parts = []
-        if _has_web:
-            _tool_tip_parts.append(_web_tips)
-        if _has_code:
-            _tool_tip_parts.append(_code_tips)
-        if _has_artifact:
-            _tool_tip_parts.append(_artifact_tips)
-
-        if _tool_tip_parts:
-            _nudge = (
-                _date_line + " "
-                "You have access to tools. When appropriate, prefer using "
-                "tools rather than answering from memory. " + " ".join(_tool_tip_parts)
-            )
-        else:
-            _nudge = ""
 
         if _nudge:
-            _nudge += _tool_action_nudge(_has_artifact)
             # Inject into system prompt
             if openai_messages and openai_messages[0].get("role") == "system":
                 openai_messages[0]["content"] = (
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index 77b0b21212..207c4b3805 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -32,6 +32,7 @@ from core.inference.anthropic_compat import (
     AnthropicPassthroughEmitter,
 )
 from routes.inference import (
+    _build_tool_action_nudge,
     _normalize_anthropic_openai_images,
     _select_anthropic_server_tools,
     _anthropic_requested_studio_tools,
@@ -46,6 +47,51 @@ from io import BytesIO as _BytesIO
 from types import SimpleNamespace
 
 
+# =====================================================================
+# Tool nudge tests
+# =====================================================================
+
+
+class TestToolActionNudge:
+    def test_balanced_nudge_uses_expanded_web_and_code_tips(self):
+        nudge = _build_tool_action_nudge(
+            tools = [
+                {"type": "function", "function": {"name": "web_search"}},
+                {"type": "function", "function": {"name": "python"}},
+            ],
+            model_name = "Llama-3.1-70B-Instruct",
+        )
+
+        assert nudge.startswith("The current date is ")
+        assert "Tools are available when they materially improve" in nudge
+        assert "prefer using tools rather than answering from memory" not in nudge
+        assert "fetch its full content by calling web_search with the url parameter" in nudge
+        assert "Use code execution for math" in nudge
+        assert "render_html" not in nudge
+
+    def test_balanced_nudge_preserves_compact_web_tip_and_artifact_gate(self):
+        nudge = _build_tool_action_nudge(
+            tools = [
+                {"type": "function", "function": {"name": "web_search"}},
+                {"type": "function", "function": {"name": "render_html"}},
+            ],
+            model_name = "Llama-3.1-8B-Instruct",
+        )
+
+        assert "When using web_search, do not repeat the same search query." in nudge
+        assert "fetch its full content" not in nudge
+        assert "call render_html once" in nudge
+
+    def test_balanced_nudge_empty_without_known_tool_categories(self):
+        assert (
+            _build_tool_action_nudge(
+                tools = [],
+                model_name = "Llama-3.1-8B-Instruct",
+            )
+            == ""
+        )
+
+
 # =====================================================================
 # Pydantic model tests
 # =====================================================================
diff --git a/studio/backend/tests/test_gguf_route_cursor_reset.py b/studio/backend/tests/test_gguf_route_cursor_reset.py
new file mode 100644
index 0000000000..fdbf31f9de
--- /dev/null
+++ b/studio/backend/tests/test_gguf_route_cursor_reset.py
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF SSE cursor reset across an internal no-op tool decision.
+
+When a GGUF turn streams visible preface text ("I'll render it again...")
+and then hits an internal no-op (duplicate / disabled / repeat render_html),
+no ``tool_start`` event is emitted. The GGUF SSE route diffs each cumulative
+``content`` event against a ``prev_text`` cursor and resets that cursor on
+``tool_start`` *and* on an empty ``status`` event. The generator must emit an
+empty status between the preface turn and the final no-tools pass, otherwise
+the final answer would be diffed against the stale preface and truncated or
+dropped entirely.
+
+This test drives the real generator and replays its events through a faithful
+copy of the route's cursor loop (studio/backend/routes/inference.py), asserting
+the final answer survives in full and the no-op produces no phantom tool card.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import json
+import sys
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from core.inference.llama_cpp import LlamaCppBackend
+
+
+def _sse(delta: dict) -> str:
+    return "data: " + json.dumps({"choices": [{"index": 0, "delta": delta}]}) + "\n"
+
+
+def _done() -> str:
+    return "data: [DONE]\n"
+
+
+def _make_backend(monkeypatch, streams: list[list[str]], payloads: list[dict]):
+    backend = LlamaCppBackend.__new__(LlamaCppBackend)
+    backend._process = object()
+    backend._healthy = True
+    backend._port = 48848
+    backend._api_key = None
+    backend._effective_context_length = 4096
+    backend._supports_reasoning = False
+    backend._reasoning_always_on = False
+    backend._reasoning_style = "enable_thinking"
+    backend._supports_preserve_thinking = False
+
+    @contextlib.contextmanager
+    def fake_stream_with_retry(
+        _client,
+        _url,
+        payload,
+        _cancel_event,
+        headers = None,
+    ):
+        payloads.append(copy.deepcopy(payload))
+        yield type("FakeResponse", (), {"status_code": 200, "chunks": streams.pop(0)})()
+
+    def fake_iter_text_cancellable(response, _cancel_event):
+        yield from response.chunks
+
+    monkeypatch.setattr(backend, "_stream_with_retry", fake_stream_with_retry)
+    monkeypatch.setattr(backend, "_iter_text_cancellable", fake_iter_text_cancellable)
+    return backend
+
+
+def _replay_route_cursor(events: list[dict]) -> dict:
+    """Replicate the GGUF SSE route's cumulative-cursor loop.
+
+    Mirrors studio/backend/routes/inference.py: reset ``prev_text`` on empty
+    status and on ``tool_start``; otherwise diff each cumulative ``content``
+    snapshot against the cursor and stream the delta. The preface/final text
+    here carry no tool XML, so the display strip is the identity -- the cursor
+    reset is the behaviour under test.
+    """
+    prev_text = ""
+    visible_deltas: list[str] = []
+    tool_starts: list[dict] = []
+    statuses: list[str] = []
+    for event in events:
+        etype = event["type"]
+        if etype == "status":
+            if not event["text"]:
+                prev_text = ""
+            statuses.append(event["text"])
+            continue
+        if etype in ("tool_start", "tool_end"):
+            if etype == "tool_start":
+                prev_text = ""
+                tool_starts.append(event)
+            continue
+        if etype == "metadata":
+            continue
+        clean_cumulative = event.get("text", "")
+        new_text = clean_cumulative[len(prev_text) :]
+        prev_text = clean_cumulative
+        if not new_text:
+            continue
+        visible_deltas.append(new_text)
+    return {
+        "visible": "".join(visible_deltas),
+        "tool_starts": tool_starts,
+        "statuses": statuses,
+    }
+
+
+def _replay_route_cursor_without_status_reset(events: list[dict]) -> dict:
+    """Pre-fix control: identical to the route loop but never resets the
+    cursor on an empty status (only on ``tool_start``)."""
+    prev_text = ""
+    visible_deltas: list[str] = []
+    for event in events:
+        etype = event["type"]
+        if etype == "status":
+            continue
+        if etype in ("tool_start", "tool_end"):
+            if etype == "tool_start":
+                prev_text = ""
+            continue
+        if etype == "metadata":
+            continue
+        clean_cumulative = event.get("text", "")
+        new_text = clean_cumulative[len(prev_text) :]
+        prev_text = clean_cumulative
+        if not new_text:
+            continue
+        visible_deltas.append(new_text)
+    return {"visible": "".join(visible_deltas)}
+
+
+def _web_search_tool() -> dict:
+    return {
+        "type": "function",
+        "function": {
+            "name": "web_search",
+            "description": "Search the web.",
+            "parameters": {
+                "type": "object",
+                "properties": {"query": {"type": "string"}},
+                "required": ["query"],
+            },
+        },
+    }
+
+
+def test_final_answer_survives_preface_then_disabled_tool_noop(monkeypatch):
+    """Preface text, then a call to a disabled tool (internal no-op).
+
+    A disabled-tool decision emits no ``tool_start`` and forces the final
+    no-tools pass. The route cursor must be reset before that pass so the
+    short final answer is not diffed away against the longer preface.
+    """
+    preface = "Let me run a quick command to double-check."
+    final = "All set."  # deliberately shorter than the preface -> truncation is visible
+
+    # Single turn: visible preface + a call to `terminal`, which is NOT in the
+    # enabled tool list, so the controller marks it disabled -> internal no-op.
+    turn_stream = [
+        _sse({"content": preface}),
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_disabled",
+                        "type": "function",
+                        "function": {
+                            "name": "terminal",
+                            "arguments": json.dumps({"command": "ls"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": final}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [turn_stream, final_stream], payloads)
+
+    executed: list[str] = []
+    monkeypatch.setattr(
+        "core.inference.tools.execute_tool",
+        lambda name, arguments, **_kw: executed.append(name) or "should-not-run",
+    )
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "answer me"}],
+            tools = [_web_search_tool()],  # terminal intentionally absent
+            temperature = 0.0,
+            max_tool_iterations = 5,
+        )
+    )
+
+    replay = _replay_route_cursor(events)
+
+    # Disabled tool is an internal no-op: never executed, no visible card.
+    assert executed == []
+    assert replay["tool_starts"] == []
+
+    # The generator must emit an empty status that resets the route cursor
+    # before the final pass; otherwise `final` (shorter than `preface`) would
+    # be diffed to nothing and dropped.
+    assert "" in replay["statuses"], "no cursor-resetting empty status emitted"
+
+    # Both the preface and the final answer survive, in order, untruncated.
+    assert preface in replay["visible"], replay["visible"]
+    assert final in replay["visible"], replay["visible"]
+    assert replay["visible"].index(preface) < replay["visible"].index(final)
+    assert replay["visible"].count(preface) == 1
+
+    # Negative control: a route loop that does NOT reset on empty status (the
+    # pre-fix behaviour) would diff `final` against the stale preface cursor
+    # and drop it -- proving the empty status is load-bearing here.
+    no_reset = _replay_route_cursor_without_status_reset(events)
+    assert final not in no_reset["visible"], no_reset["visible"]
diff --git a/studio/backend/tests/test_llama_cpp_tool_loop.py b/studio/backend/tests/test_llama_cpp_tool_loop.py
new file mode 100644
index 0000000000..fa583ef53d
--- /dev/null
+++ b/studio/backend/tests/test_llama_cpp_tool_loop.py
@@ -0,0 +1,1151 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Focused tests for the GGUF llama.cpp agentic tool loop.
+
+These tests drive ``LlamaCppBackend.generate_chat_completion_with_tools``
+with fake llama-server SSE streams. They require no model, subprocess, GPU,
+or network access.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import json
+import sys
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from core.inference.llama_cpp import LlamaCppBackend
+
+
+def _sse(delta: dict) -> str:
+    return "data: " + json.dumps({"choices": [{"index": 0, "delta": delta}]}) + "\n"
+
+
+def _done() -> str:
+    return "data: [DONE]\n"
+
+
+def _make_backend(monkeypatch, streams: list[list[str]], payloads: list[dict]):
+    backend = LlamaCppBackend.__new__(LlamaCppBackend)
+    backend._process = object()
+    backend._healthy = True
+    backend._port = 48847
+    backend._api_key = None
+    backend._effective_context_length = 4096
+    backend._supports_reasoning = False
+    backend._reasoning_always_on = False
+    backend._reasoning_style = "enable_thinking"
+    backend._supports_preserve_thinking = False
+
+    @contextlib.contextmanager
+    def fake_stream_with_retry(
+        _client,
+        _url,
+        payload,
+        _cancel_event,
+        headers = None,
+    ):
+        payloads.append(copy.deepcopy(payload))
+        yield type("FakeResponse", (), {"status_code": 200, "chunks": streams.pop(0)})()
+
+    def fake_iter_text_cancellable(response, _cancel_event):
+        yield from response.chunks
+
+    monkeypatch.setattr(backend, "_stream_with_retry", fake_stream_with_retry)
+    monkeypatch.setattr(backend, "_iter_text_cancellable", fake_iter_text_cancellable)
+    return backend
+
+
+def _tool_names(payload: dict) -> list[str]:
+    return [
+        (tool.get("function") or {}).get("name")
+        for tool in payload.get("tools", [])
+        if (tool.get("function") or {}).get("name")
+    ]
+
+
+def test_structured_tool_call_after_visible_preface_is_executed(monkeypatch):
+    """llama-server may emit content first and then native delta.tool_calls.
+
+    Studio must not drop that tool call after it has streamed the preface.
+    """
+
+    tool_call_id = "call_render_late"
+    first_stream = [
+        _sse({"content": "Here is the artifact.\n\n"}),
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": tool_call_id,
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps(
+                                {
+                                    "code": "<html><body><div>red</div></body></html>",
+                                    "title": "Simple Red Square",
+                                }
+                            ),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    second_stream = [
+        _sse({"content": "Done."}),
+        _done(),
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [first_stream, second_stream], payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "Rendered HTML artifact: Simple Red Square."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        }
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 1,
+        )
+    )
+
+    content_events = [e for e in events if e.get("type") == "content"]
+    assert content_events[0]["text"] == "Here is the artifact.\n\n"
+
+    first_content_index = next(
+        i for i, event in enumerate(events) if event.get("type") == "content"
+    )
+    actual_tool_start_index = next(
+        i
+        for i, event in enumerate(events)
+        if event.get("type") == "tool_start" and event.get("arguments", {}).get("code")
+    )
+    assert first_content_index < actual_tool_start_index
+
+    assert calls == [
+        (
+            "render_html",
+            {
+                "code": "<html><body><div>red</div></body></html>",
+                "title": "Simple Red Square",
+            },
+        )
+    ]
+    assert any(e.get("type") == "tool_end" and e.get("tool_name") == "render_html" for e in events)
+
+    # The second llama-server request should include the assistant preface
+    # plus the structured tool call, preserving OpenAI-compatible ordering.
+    assert len(payloads) == 2
+    assistant_messages = [m for m in payloads[1]["messages"] if m.get("role") == "assistant"]
+    assert assistant_messages[-1]["content"] == "Here is the artifact.\n\n"
+    assert assistant_messages[-1]["tool_calls"][0]["id"] == tool_call_id
+    assert assistant_messages[-1]["tool_calls"][0]["function"]["name"] == "render_html"
+
+
+def test_repeat_render_html_nudge_is_not_user_visible_error(monkeypatch):
+    """A repeated render_html call is an internal no-op, not a visible card."""
+
+    first_stream = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_first",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps(
+                                {
+                                    "code": "<html><body>first</body></html>",
+                                    "title": "First",
+                                }
+                            ),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    repeat_stream = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_repeat",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps(
+                                {
+                                    "code": "<html><body>repeat</body></html>",
+                                    "title": "Repeat",
+                                }
+                            ),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Short note."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [first_stream, repeat_stream, final_stream], payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "Rendered HTML artifact: First."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        },
+        {"type": "function", "function": {"name": "web_search"}},
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 2,
+        )
+    )
+
+    assert calls == [
+        (
+            "render_html",
+            {"code": "<html><body>first</body></html>", "title": "First"},
+        )
+    ]
+    assert _tool_names(payloads[1]) == ["web_search"]
+
+    actual_tool_starts = [
+        event
+        for event in events
+        if event.get("type") == "tool_start" and event.get("arguments", {}).get("code")
+    ]
+    tool_ends = [
+        event
+        for event in events
+        if event.get("type") == "tool_end" and event.get("tool_name") == "render_html"
+    ]
+    assert len(actual_tool_starts) == 1
+    assert len(tool_ends) == 1
+
+    assert len(payloads) == 3
+    render_tool_messages = [
+        message
+        for message in payloads[2]["messages"]
+        if message.get("role") == "tool" and message.get("name") == "render_html"
+    ]
+    assert len(render_tool_messages) == 1
+    internal_nudges = [
+        message
+        for message in payloads[2]["messages"]
+        if message.get("role") == "user"
+        and "Do not call render_html again" in message.get("content", "")
+    ]
+    assert len(internal_nudges) == 1
+
+
+def test_render_html_success_drops_tool_schema_before_final_pass(monkeypatch):
+    first_stream = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_first",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps({"code": "<html>ok</html>"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Done."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [first_stream, final_stream], payloads)
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        return "Rendered HTML artifact: Done."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Render this."}],
+            tools = [{"type": "function", "function": {"name": "render_html"}}],
+            max_tool_iterations = 3,
+        )
+    )
+
+    assert len(payloads) == 2
+    assert "tools" not in payloads[1]
+    assert any(event.get("type") == "content" and event.get("text") == "Done." for event in events)
+    final_user_messages = [
+        m.get("content", "") for m in payloads[1]["messages"] if m.get("role") == "user"
+    ]
+    assert not any("used all available tool calls" in message for message in final_user_messages)
+
+
+def test_non_consecutive_duplicate_web_search_is_internal_noop(monkeypatch):
+    first_search = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_1",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    python_call = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_python",
+                        "type": "function",
+                        "function": {
+                            "name": "python",
+                            "arguments": json.dumps({"code": "print('ok')"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    duplicate_search = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_2",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Final answer from gathered data."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(
+        monkeypatch,
+        [first_search, python_call, duplicate_search, final_stream],
+        payloads,
+    )
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return f"ok:{name}"
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {"type": "function", "function": {"name": "web_search"}},
+        {"type": "function", "function": {"name": "python"}},
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "search gpus in 2026 prices and use python"}],
+            tools = tools,
+            max_tool_iterations = 3,
+        )
+    )
+
+    assert calls == [
+        ("web_search", {"query": "gpu prices 2026"}),
+        ("python", {"code": "print('ok')"}),
+    ]
+    assert [
+        event.get("tool_name")
+        for event in events
+        if event.get("type") == "tool_start" and event.get("tool_name")
+    ] == ["web_search", "python"]
+    assert [
+        event.get("tool_name")
+        for event in events
+        if event.get("type") == "tool_end" and event.get("tool_name")
+    ] == ["web_search", "python"]
+    assert not [
+        event
+        for event in events
+        if event.get("tool_call_id") == "call_search_2"
+        and event.get("type") in {"tool_start", "tool_end"}
+    ]
+    assert len(payloads) == 4
+    assert _tool_names(payloads[3]) == ["web_search", "python"]
+    duplicate_nudges = [
+        message
+        for message in payloads[3]["messages"]
+        if message.get("role") == "user"
+        and "already completed successfully" in message.get("content", "")
+    ]
+    assert len(duplicate_nudges) == 1
+
+
+def test_duplicate_web_search_noop_allows_distinct_followup_tool(monkeypatch):
+    first_search = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_1",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    duplicate_search = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_2",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    python_call = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_python",
+                        "type": "function",
+                        "function": {
+                            "name": "python",
+                            "arguments": json.dumps({"code": "print('ok')"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Final answer from gathered data."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(
+        monkeypatch,
+        [first_search, duplicate_search, python_call, final_stream],
+        payloads,
+    )
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return f"ok:{name}"
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {"type": "function", "function": {"name": "web_search"}},
+        {"type": "function", "function": {"name": "python"}},
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "search gpus in 2026 prices and use python"}],
+            tools = tools,
+            max_tool_iterations = 4,
+        )
+    )
+
+    assert calls == [
+        ("web_search", {"query": "gpu prices 2026"}),
+        ("python", {"code": "print('ok')"}),
+    ]
+    assert [
+        event.get("tool_name")
+        for event in events
+        if event.get("type") == "tool_start" and event.get("tool_name")
+    ] == ["web_search", "python"]
+    assert [
+        event.get("tool_name")
+        for event in events
+        if event.get("type") == "tool_end" and event.get("tool_name")
+    ] == ["web_search", "python"]
+    assert not [
+        event
+        for event in events
+        if event.get("tool_call_id") == "call_search_2"
+        and event.get("type") in {"tool_start", "tool_end"}
+    ]
+    assert len(payloads) == 4
+    assert _tool_names(payloads[2]) == ["web_search", "python"]
+    duplicate_nudges = [
+        message
+        for message in payloads[2]["messages"]
+        if message.get("role") == "user"
+        and "already completed successfully" in message.get("content", "")
+    ]
+    assert len(duplicate_nudges) == 1
+
+
+def test_repeated_duplicate_noop_transitions_to_final_pass(monkeypatch):
+    first_search = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_1",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    duplicate_one = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_2",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    duplicate_two = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_3",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Final answer from first search."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(
+        monkeypatch,
+        [first_search, duplicate_one, duplicate_two, final_stream],
+        payloads,
+    )
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "result"
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "search gpus"}],
+            tools = [{"type": "function", "function": {"name": "web_search"}}],
+            max_tool_iterations = 10,
+        )
+    )
+
+    assert calls == [("web_search", {"query": "gpu prices 2026"})]
+    assert [event.get("tool_call_id") for event in events if event.get("type") == "tool_end"] == [
+        "call_search_1"
+    ]
+    assert len(payloads) == 4
+    assert "tools" not in payloads[-1]
+    assert any(
+        event.get("type") == "content" and event.get("text") == "Final answer from first search."
+        for event in events
+    )
+
+
+def test_same_turn_duplicate_web_search_is_internal_noop(monkeypatch):
+    same_turn_duplicates = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_search_1",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    },
+                    {
+                        "index": 1,
+                        "id": "call_search_2",
+                        "type": "function",
+                        "function": {
+                            "name": "web_search",
+                            "arguments": json.dumps({"query": "gpu prices 2026"}),
+                        },
+                    },
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Final answer."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [same_turn_duplicates, final_stream], payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "search-result"
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "search gpus"}],
+            tools = [{"type": "function", "function": {"name": "web_search"}}],
+            max_tool_iterations = 2,
+        )
+    )
+
+    assert calls == [("web_search", {"query": "gpu prices 2026"})]
+    assert [event.get("tool_call_id") for event in events if event.get("type") == "tool_end"] == [
+        "call_search_1"
+    ]
+    assert not [
+        event
+        for event in events
+        if event.get("tool_call_id") == "call_search_2"
+        and event.get("type") in {"tool_start", "tool_end"}
+    ]
+
+
+def test_same_turn_repeated_render_html_does_not_emit_second_provisional_start(monkeypatch):
+    same_turn_render_calls = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_html_1",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps({"code": "<html>one</html>"}),
+                        },
+                    },
+                    {
+                        "index": 1,
+                        "id": "call_html_2",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps({"code": "<html>two</html>"}),
+                        },
+                    },
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "Final answer."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [same_turn_render_calls, final_stream], payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "Rendered HTML artifact: One."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "render html"}],
+            tools = [{"type": "function", "function": {"name": "render_html"}}],
+            max_tool_iterations = 2,
+        )
+    )
+
+    assert calls == [("render_html", {"code": "<html>one</html>"})]
+    assert [
+        event.get("tool_call_id")
+        for event in events
+        if event.get("type") == "tool_start" and not event.get("arguments")
+    ] == ["call_html_1"]
+    assert not [
+        event
+        for event in events
+        if event.get("tool_call_id") == "call_html_2"
+        and event.get("type") in {"tool_start", "tool_end"}
+    ]
+    assert len(payloads) == 2
+    assert "tools" not in payloads[1]
+    render_nudges = [
+        message
+        for message in payloads[1]["messages"]
+        if message.get("role") == "user"
+        and "Do not call render_html again" in message.get("content", "")
+    ]
+    assert len(render_nudges) == 1
+
+
+def test_disabled_tool_call_is_internal_noop(monkeypatch):
+    disabled_python = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_python_disabled",
+                        "type": "function",
+                        "function": {
+                            "name": "python",
+                            "arguments": json.dumps({"code": "print(1)"}),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    final_stream = [_sse({"content": "I cannot run Python here."}), _done()]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [disabled_python, final_stream], payloads)
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        raise AssertionError(f"unexpected tool execution: {name} {arguments}")
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "run python"}],
+            tools = [{"type": "function", "function": {"name": "web_search"}}],
+            max_tool_iterations = 1,
+        )
+    )
+
+    assert not [event for event in events if event.get("type") in {"tool_start", "tool_end"}]
+    assert len(payloads) == 2
+    disabled_nudges = [
+        message
+        for message in payloads[1]["messages"]
+        if message.get("role") == "user" and "not enabled" in message.get("content", "")
+    ]
+    assert len(disabled_nudges) == 1
+
+
+def test_render_html_success_does_not_reprompt_render_html_intent(monkeypatch):
+    """After render_html succeeds, do not force another render_html call.
+
+    The post-tool model pass can say it will use render_html again without
+    emitting a tool call. That should be accepted as a final model mistake,
+    not turned into repeated internal re-prompts after the artifact already
+    exists.
+    """
+
+    first_stream = [
+        _sse(
+            {
+                "tool_calls": [
+                    {
+                        "index": 0,
+                        "id": "call_first",
+                        "type": "function",
+                        "function": {
+                            "name": "render_html",
+                            "arguments": json.dumps(
+                                {
+                                    "code": "<html><body>first</body></html>",
+                                    "title": "First",
+                                }
+                            ),
+                        },
+                    }
+                ]
+            }
+        ),
+        _done(),
+    ]
+    post_tool_stream = [
+        _sse({"content": "I will now use render_html again."}),
+        _done(),
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, [first_stream, post_tool_stream], payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "Rendered HTML artifact: First."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        }
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 1,
+        )
+    )
+
+    assert len(payloads) == 2
+    assert len(calls) == 1
+    assert any(
+        event.get("type") == "content" and event.get("text") == "I will now use render_html again."
+        for event in events
+    )
+
+
+def test_internal_reprompt_attempts_do_not_duplicate_visible_text(monkeypatch):
+    """No-tool re-prompt attempts should not concatenate into the UI."""
+
+    streams = [
+        [_sse({"content": "I will use render_html now."}), _done()],
+        [_sse({"content": "Understood. I will use render_html now."}), _done()],
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, streams, payloads)
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        raise AssertionError(f"unexpected tool execution: {name} {arguments}")
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        }
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 1,
+        )
+    )
+
+    content_texts = [event.get("text", "") for event in events if event.get("type") == "content"]
+    assert content_texts == ["I will use render_html now."]
+    assert len(payloads) == 2
+
+
+def test_forced_reprompt_plain_final_answer_is_visible(monkeypatch):
+    """A hidden forced re-prompt may fall back to a plain final answer."""
+
+    streams = [
+        [_sse({"content": "I will use render_html now."}), _done()],
+        [
+            _sse({"content": "No tool is needed. Final answer: use a red square."}),
+            _done(),
+        ],
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, streams, payloads)
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        raise AssertionError(f"unexpected tool execution: {name} {arguments}")
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": "render_html",
+                        "description": "Render HTML.",
+                        "parameters": {
+                            "type": "object",
+                            "properties": {"code": {"type": "string"}},
+                            "required": ["code"],
+                        },
+                    },
+                }
+            ],
+            max_tool_iterations = 1,
+        )
+    )
+
+    content_texts = [event.get("text", "") for event in events if event.get("type") == "content"]
+    assert content_texts == [
+        "I will use render_html now.",
+        "No tool is needed. Final answer: use a red square.",
+    ]
+    assert len(payloads) == 2
+
+
+def test_internal_reprompt_disabled_when_auto_heal_disabled(monkeypatch):
+    streams = [[_sse({"content": "I will use render_html now."}), _done()]]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, streams, payloads)
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        raise AssertionError(f"unexpected tool execution: {name} {arguments}")
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        }
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 1,
+            auto_heal_tool_calls = False,
+        )
+    )
+
+    content_texts = [event.get("text", "") for event in events if event.get("type") == "content"]
+    assert content_texts == ["I will use render_html now."]
+    assert len(payloads) == 1
+
+
+def test_auto_heal_disabled_parses_well_formed_xml_when_tools_enabled(monkeypatch):
+    streams = [
+        [
+            _sse(
+                {
+                    "content": '<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'
+                }
+            ),
+            _done(),
+        ],
+        [_sse({"content": "done"}), _done()],
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, streams, payloads)
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "result"
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "search"}],
+            tools = [{"type": "function", "function": {"name": "web_search"}}],
+            auto_heal_tool_calls = False,
+            max_tool_iterations = 1,
+        )
+    )
+
+    assert calls == [("web_search", {"query": "x"})]
+    assert not any(
+        event.get("type") == "content" and "<tool_call>" in event.get("text", "")
+        for event in events
+    )
+
+
+def test_reprompted_tool_call_still_streams_final_answer(monkeypatch):
+    """Suppression ends once a forced re-prompt actually calls a tool."""
+
+    streams = [
+        [_sse({"content": "I will use render_html now."}), _done()],
+        [
+            _sse(
+                {
+                    "tool_calls": [
+                        {
+                            "index": 0,
+                            "id": "call_forced",
+                            "type": "function",
+                            "function": {
+                                "name": "render_html",
+                                "arguments": json.dumps(
+                                    {
+                                        "code": "<html><body>forced</body></html>",
+                                        "title": "Forced",
+                                    }
+                                ),
+                            },
+                        }
+                    ]
+                }
+            ),
+            _done(),
+        ],
+        [_sse({"content": "Final note after tool."}), _done()],
+    ]
+    payloads: list[dict] = []
+    backend = _make_backend(monkeypatch, streams, payloads)
+
+    calls: list[tuple[str, dict]] = []
+
+    def fake_execute_tool(name, arguments, **_kwargs):
+        calls.append((name, arguments))
+        return "Rendered HTML artifact: Forced."
+
+    monkeypatch.setattr("core.inference.tools.execute_tool", fake_execute_tool)
+
+    tools = [
+        {
+            "type": "function",
+            "function": {
+                "name": "render_html",
+                "description": "Render HTML.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"code": {"type": "string"}},
+                    "required": ["code"],
+                },
+            },
+        }
+    ]
+
+    events = list(
+        backend.generate_chat_completion_with_tools(
+            messages = [{"role": "user", "content": "Make a red square."}],
+            tools = tools,
+            max_tool_iterations = 1,
+        )
+    )
+
+    assert len(calls) == 1
+    content_texts = [event.get("text", "") for event in events if event.get("type") == "content"]
+    assert content_texts == ["I will use render_html now.", "Final note after tool."]
+    assert len(payloads) == 3
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index 55d2a48df1..16ed1dc182 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -20,6 +20,7 @@ from core.inference.safetensors_agentic import (
     _coerce_arguments,
     _detect_render_html_tool_start,
     run_safetensors_tool_loop,
+    strip_tool_markup_streaming,
 )
 from core.inference.tool_call_parser import (
     has_tool_signal,
@@ -53,6 +54,11 @@ class TestParser:
         assert len(result) == 1
         assert result[0]["function"]["name"] == "python"
 
+    def test_json_tool_call_unclosed_requires_healing(self):
+        text = '<tool_call>{"name":"python","arguments":{"code":"print(1)"}}'
+        assert parse_tool_calls_from_text(text)[0]["function"]["name"] == "python"
+        assert parse_tool_calls_from_text(text, allow_incomplete = False) == []
+
     def test_xml_function_call(self):
         text = "<function=python><parameter=code>print('hi')</parameter></function>"
         result = parse_tool_calls_from_text(text)
@@ -68,6 +74,11 @@ class TestParser:
         assert result[0]["function"]["name"] == "terminal"
         assert "ls -la" in result[0]["function"]["arguments"]
 
+    def test_xml_unclosed_requires_healing(self):
+        text = "<function=terminal><parameter=command>ls -la"
+        assert parse_tool_calls_from_text(text)[0]["function"]["name"] == "terminal"
+        assert parse_tool_calls_from_text(text, allow_incomplete = False) == []
+
     def test_code_with_embedded_xml(self):
         # A code parameter with a literal </parameter> must not truncate: the
         # parser uses end-of-body as the only boundary for single-param calls.
@@ -134,6 +145,23 @@ class TestParser:
         # Without final=True the unclosed run is preserved.
         assert "partial" in strip_tool_markup(text)
 
+    def test_streaming_strip_respects_disabled_healing(self):
+        raw = 'before <tool_call>{"name":"web_search"'
+        assert strip_tool_markup_streaming(raw, auto_heal_tool_calls = False) == raw
+        assert strip_tool_markup_streaming(raw) == "before "
+
+    def test_streaming_strip_respects_disabled_healing_without_tool_protocol(self):
+        raw = 'before <tool_call>{"name":"web_search"'
+        assert strip_tool_markup_streaming(raw, auto_heal_tool_calls = False) == raw
+        assert (
+            strip_tool_markup_streaming(
+                raw,
+                auto_heal_tool_calls = False,
+                tool_protocol_active = True,
+            )
+            == "before "
+        )
+
 
 # ────────────────────────────────────────────────────────────────────
 # run_safetensors_tool_loop
@@ -230,6 +258,41 @@ def _make_loop(
     ), exec_fn
 
 
+def test_active_tools_are_passed_to_single_turn_after_render_html_success():
+    captured_tool_names: list[list[str]] = []
+    exec_fn = FakeExecuteTool(["Rendered HTML artifact."])
+
+    def fake_single_turn(_messages, *, active_tools = None):
+        captured_tool_names.append(
+            [
+                (tool.get("function") or {}).get("name")
+                for tool in (active_tools or [])
+                if (tool.get("function") or {}).get("name")
+            ]
+        )
+        if len(captured_tool_names) == 1:
+            yield '<tool_call>{"name":"render_html","arguments":{"code":"<html>one</html>"}}</tool_call>'
+        else:
+            yield "Done."
+
+    events = _collect_events(
+        run_safetensors_tool_loop(
+            single_turn = fake_single_turn,
+            messages = [{"role": "user", "content": "make html"}],
+            tools = [
+                {"type": "function", "function": {"name": "render_html"}},
+                {"type": "function", "function": {"name": "web_search"}},
+            ],
+            execute_tool = exec_fn,
+            max_tool_iterations = 3,
+        )
+    )
+
+    assert exec_fn.calls == [("render_html", {"code": "<html>one</html>"})]
+    assert captured_tool_names == [["render_html", "web_search"], ["web_search"]]
+    assert any(event.get("type") == "content" and event.get("text") == "Done." for event in events)
+
+
 class TestLoopBasic:
     def test_plain_answer(self):
         # No tool XML; loop should yield content then status="".
@@ -409,23 +472,158 @@ class TestLoopBasic:
 
 
 class TestLoopBehaviour:
-    def test_duplicate_tool_call_synthetic_result(self):
-        # Two identical calls in a row: the second short-circuits with a "do not
-        # repeat" message; execute_tool runs once.
-        loop, exec_fn = _make_loop(
-            turns = [
+    def test_duplicate_tool_call_internal_noop(self):
+        captured_messages: list[list[dict]] = []
+        turns = iter(
+            [
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
                 ["final"],
-            ],
-            exec_results = ["search-result-1"],
+            ]
+        )
+
+        def fake_single_turn(messages):
+            captured_messages.append([dict(message) for message in messages])
+            chunks = next(turns)
+            acc = ""
+            for chunk in chunks:
+                acc += chunk
+                yield acc
+
+        exec_fn = FakeExecuteTool(["search-result-1"])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "hi"}],
+                tools = [{"type": "function", "function": {"name": "web_search"}}],
+                execute_tool = exec_fn,
+                max_tool_iterations = 3,
+            )
+        )
+
+        assert exec_fn.calls == [("web_search", {"query": "x"})]
+        assert [e["tool_call_id"] for e in events if e["type"] == "tool_end"] == ["call_0"]
+        assert not [
+            e
+            for e in events
+            if e.get("tool_call_id") == "call_1" and e.get("type") in {"tool_start", "tool_end"}
+        ]
+        duplicate_nudges = [
+            message
+            for message in captured_messages[-1]
+            if message.get("role") == "user"
+            and "already completed successfully" in message.get("content", "")
+        ]
+        assert len(duplicate_nudges) == 1
+
+    def test_duplicate_tool_call_internal_noop_allows_distinct_followup_tool(self):
+        captured_messages: list[list[dict]] = []
+        captured_tool_names: list[list[str]] = []
+        turns = iter(
+            [
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"python","arguments":{"code":"print(1)"}}</tool_call>'],
+                ["final"],
+            ]
+        )
+
+        def fake_single_turn(messages, active_tools = None):
+            captured_messages.append([dict(message) for message in messages])
+            captured_tool_names.append(
+                [
+                    tool["function"]["name"]
+                    for tool in (active_tools or [])
+                    if tool.get("function", {}).get("name")
+                ]
+            )
+            chunks = next(turns)
+            acc = ""
+            for chunk in chunks:
+                acc += chunk
+                yield acc
+
+        exec_fn = FakeExecuteTool(["search-result-1", "python-result"])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "hi"}],
+                tools = [
+                    {"type": "function", "function": {"name": "web_search"}},
+                    {"type": "function", "function": {"name": "python"}},
+                ],
+                execute_tool = exec_fn,
+                max_tool_iterations = 4,
+            )
+        )
+
+        assert exec_fn.calls == [
+            ("web_search", {"query": "x"}),
+            ("python", {"code": "print(1)"}),
+        ]
+        assert [e["tool_call_id"] for e in events if e["type"] == "tool_end"] == [
+            "call_0",
+            "call_2",
+        ]
+        assert not [
+            e
+            for e in events
+            if e.get("tool_call_id") == "call_1" and e.get("type") in {"tool_start", "tool_end"}
+        ]
+        duplicate_nudges = [
+            message
+            for message in captured_messages[2]
+            if message.get("role") == "user"
+            and "already completed successfully" in message.get("content", "")
+        ]
+        assert len(duplicate_nudges) == 1
+        assert captured_tool_names[2] == ["web_search", "python"]
+
+    def test_repeated_duplicate_noop_transitions_to_final_attempt(self):
+        captured_tool_names: list[list[str]] = []
+        turns = iter(
+            [
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ["final from first result"],
+            ]
+        )
+
+        def fake_single_turn(messages, active_tools = None):
+            captured_tool_names.append(
+                [
+                    (tool.get("function") or {}).get("name")
+                    for tool in (active_tools or [])
+                    if (tool.get("function") or {}).get("name")
+                ]
+            )
+            chunks = next(turns)
+            acc = ""
+            for chunk in chunks:
+                acc += chunk
+                yield acc
+
+        exec_fn = FakeExecuteTool(["search-result"])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "hi"}],
+                tools = [{"type": "function", "function": {"name": "web_search"}}],
+                execute_tool = exec_fn,
+                max_tool_iterations = 10,
+            )
+        )
+
+        assert exec_fn.calls == [("web_search", {"query": "x"})]
+        assert [
+            event.get("tool_call_id") for event in events if event.get("type") == "tool_end"
+        ] == ["call_0"]
+        assert captured_tool_names[-1] == []
+        assert any(
+            event.get("type") == "content" and "final from first result" in event.get("text", "")
+            for event in events
         )
-        events = _collect_events(loop)
-        # Only one real call.
-        assert len(exec_fn.calls) == 1
-        tool_end_events = [e for e in events if e["type"] == "tool_end"]
-        assert len(tool_end_events) == 2
-        assert "do not repeat" in tool_end_events[1]["result"].lower()
 
     def test_image_sentinel_stripped_from_model_feed(self):
         # The image sentinel is stripped before the next turn, but tool_end still
@@ -695,34 +893,62 @@ class TestChatTemplateHelper:
 
 class TestGuardrails:
     def test_disabled_tool_is_not_executed(self):
-        exec_fn = FakeExecuteTool([])
-        loop = run_safetensors_tool_loop(
-            single_turn = _fake_stream(
-                ['<tool_call>{"name":"terminal","arguments":{"command":"echo bypass"}}</tool_call>']
-            ),
-            messages = [{"role": "user", "content": "hi"}],
-            tools = [{"type": "function", "function": {"name": "web_search"}}],
-            execute_tool = exec_fn,
-            max_tool_iterations = 2,
-        )
-        events = _collect_events(loop)
-        assert exec_fn.calls == []
-        tool_ends = [e for e in events if e["type"] == "tool_end"]
-        assert tool_ends and "not enabled" in tool_ends[0]["result"].lower()
+        captured_messages: list[list[dict]] = []
 
-    def test_empty_tools_list_does_not_enforce_allowlist(self):
-        exec_fn = FakeExecuteTool(["OK"])
-        loop = run_safetensors_tool_loop(
-            single_turn = _fake_stream(
-                ['<tool_call>{"name":"python","arguments":{"code":"print(1)"}}</tool_call>']
-            ),
-            messages = [{"role": "user", "content": "hi"}],
-            tools = [],
-            execute_tool = exec_fn,
-            max_tool_iterations = 2,
+        def fake_single_turn(messages):
+            captured_messages.append([dict(message) for message in messages])
+            if len(captured_messages) == 1:
+                yield '<tool_call>{"name":"terminal","arguments":{"command":"echo bypass"}}</tool_call>'
+            else:
+                yield "final"
+
+        exec_fn = FakeExecuteTool([])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "hi"}],
+                tools = [{"type": "function", "function": {"name": "web_search"}}],
+                execute_tool = exec_fn,
+                max_tool_iterations = 2,
+            )
+        )
+
+        assert exec_fn.calls == []
+        assert not [event for event in events if event.get("type") in {"tool_start", "tool_end"}]
+        disabled_nudges = [
+            message
+            for message in captured_messages[-1]
+            if message.get("role") == "user" and "not enabled" in message.get("content", "")
+        ]
+        assert len(disabled_nudges) == 1
+
+    def test_empty_tools_list_means_allow_all_in_core_loop(self):
+        turns = iter(
+            [
+                ['<tool_call>{"name":"python","arguments":{"code":"print(1)"}}</tool_call>'],
+                ["done"],
+            ]
+        )
+
+        def fake_single_turn(_messages, active_tools = None):
+            assert active_tools == []
+            acc = ""
+            for chunk in next(turns):
+                acc += chunk
+                yield acc
+
+        exec_fn = FakeExecuteTool(["OK"])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "hi"}],
+                tools = [],
+                execute_tool = exec_fn,
+                max_tool_iterations = 2,
+            )
         )
-        _collect_events(loop)
         assert exec_fn.calls == [("python", {"code": "print(1)"})]
+        assert any(event.get("type") == "tool_end" for event in events)
 
     def test_max_iterations_zero_executes_no_tools(self):
         loop, exec_fn = _make_loop(
@@ -767,6 +993,67 @@ class TestGuardrails:
         _collect_events(loop)
         assert exec_fn.calls == [("web_search", {"query": "x"})]
 
+    def test_auto_heal_disabled_preserves_xml_on_final_no_tools_pass(self):
+        turns = iter(
+            [
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}</tool_call>'],
+                ['<tool_call>{"name":"web_search","arguments":{"query":"literal"}}</tool_call>'],
+            ]
+        )
+
+        def fake_single_turn(_messages, active_tools = None):
+            acc = ""
+            for chunk in next(turns):
+                acc += chunk
+                yield acc
+
+        exec_fn = FakeExecuteTool(["OK"])
+        events = _collect_events(
+            run_safetensors_tool_loop(
+                single_turn = fake_single_turn,
+                messages = [{"role": "user", "content": "show literal"}],
+                tools = [{"type": "function", "function": {"name": "web_search"}}],
+                execute_tool = exec_fn,
+                max_tool_iterations = 1,
+                auto_heal_tool_calls = False,
+            )
+        )
+        assert exec_fn.calls == [("web_search", {"query": "x"})]
+        assert any(
+            event.get("type") == "content" and "<tool_call>" in event.get("text", "")
+            for event in events
+        )
+
+    def test_auto_heal_disabled_does_not_repair_unclosed_tool_call(self):
+        loop, exec_fn = _make_loop(
+            turns = [
+                ['<tool_call>{"name":"web_search","arguments":{"query":"x"}}'],
+            ],
+            exec_results = ["OK"],
+            auto_heal_tool_calls = False,
+            max_tool_iterations = 1,
+        )
+        events = _collect_events(loop)
+        assert exec_fn.calls == []
+        assert any(
+            event.get("type") == "content" and "<tool_call>" in event.get("text", "")
+            for event in events
+        )
+
+    def test_auto_heal_enabled_strips_unparseable_xml_tool_call(self):
+        loop, exec_fn = _make_loop(
+            turns = [["<tool_call>{not valid json}</tool_call>"]],
+            exec_results = ["OK"],
+            auto_heal_tool_calls = True,
+            max_tool_iterations = 1,
+        )
+        events = _collect_events(loop)
+        assert exec_fn.calls == []
+        assert not any(
+            event.get("type") == "content" and "<tool_call>" in event.get("text", "")
+            for event in events
+        )
+
     def test_non_consecutive_duplicate_is_short_circuited(self):
         loop, exec_fn = _make_loop(
             turns = [
@@ -780,8 +1067,39 @@ class TestGuardrails:
         )
         events = _collect_events(loop)
         assert exec_fn.calls == [("web_search", {"query": "A"}), ("web_search", {"query": "B"})]
-        tool_ends = [e for e in events if e["type"] == "tool_end"]
-        assert "already made this exact call" in tool_ends[-1]["result"]
+        assert [
+            event.get("tool_call_id") for event in events if event.get("type") == "tool_end"
+        ] == ["call_0", "call_1"]
+        assert not [
+            event
+            for event in events
+            if event.get("tool_call_id") == "call_2"
+            and event.get("type") in {"tool_start", "tool_end"}
+        ]
+
+    def test_same_turn_duplicate_is_short_circuited(self):
+        loop, exec_fn = _make_loop(
+            turns = [
+                [
+                    '<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'
+                    '<tool_call>{"name":"web_search","arguments":{"query":"A"}}</tool_call>'
+                ],
+                ["final"],
+            ],
+            exec_results = ["res-A"],
+            max_tool_iterations = 2,
+        )
+        events = _collect_events(loop)
+        assert exec_fn.calls == [("web_search", {"query": "A"})]
+        assert [
+            event.get("tool_call_id") for event in events if event.get("type") == "tool_end"
+        ] == ["call_0"]
+        assert not [
+            event
+            for event in events
+            if event.get("tool_call_id") == "call_1"
+            and event.get("type") in {"tool_start", "tool_end"}
+        ]
 
     def test_coerce_string_args_python_uses_code_key(self):
         assert _coerce_arguments("print(1)", heal = True, tool_name = "python") == {"code": "print(1)"}
diff --git a/studio/backend/tests/test_tool_call_parser_strict.py b/studio/backend/tests/test_tool_call_parser_strict.py
new file mode 100644
index 0000000000..8ff41342d7
--- /dev/null
+++ b/studio/backend/tests/test_tool_call_parser_strict.py
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Strict-mode (Auto-Heal disabled) tool-call parsing.
+
+With ``allow_incomplete=False`` the parser must accept a well-formed
+``<function=...>...</function>`` call even when the model appends prose
+after the closing tag -- matching the JSON-style ``<tool_call>...`` path,
+which already tolerates trailing text -- while still rejecting genuinely
+truncated calls that never close.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from core.inference.tool_call_parser import parse_tool_calls_from_text
+
+
+def _only(text: str) -> dict:
+    calls = parse_tool_calls_from_text(text, allow_incomplete = False)
+    assert len(calls) == 1, f"expected exactly one call, got {len(calls)}: {calls!r}"
+    fn = calls[0]["function"]
+    return {"name": fn["name"], "arguments": json.loads(fn["arguments"])}
+
+
+class TestFunctionStyleTrailingText:
+    def test_closed_function_with_trailing_prose_is_accepted(self):
+        text = (
+            "<function=web_search><parameter=query>weather london</parameter></function>"
+            " Let me check that for you."
+        )
+        call = _only(text)
+        assert call == {"name": "web_search", "arguments": {"query": "weather london"}}
+
+    def test_closed_function_with_trailing_whitespace_is_accepted(self):
+        text = "<function=web_search><parameter=query>cats</parameter></function>   \n\n"
+        call = _only(text)
+        assert call == {"name": "web_search", "arguments": {"query": "cats"}}
+
+    def test_closed_function_without_trailing_text_still_parses(self):
+        text = "<function=web_search><parameter=query>cats</parameter></function>"
+        call = _only(text)
+        assert call == {"name": "web_search", "arguments": {"query": "cats"}}
+
+    def test_multi_param_with_trailing_prose(self):
+        text = (
+            "<function=terminal><parameter=command>ls -la</parameter>"
+            "<parameter=workdir>home</parameter></function> running it now"
+        )
+        call = _only(text)
+        assert call == {
+            "name": "terminal",
+            "arguments": {"command": "ls -la", "workdir": "home"},
+        }
+
+    def test_code_value_containing_literal_close_tag_is_preserved(self):
+        # The real closing </function> is the last one; the literal inside
+        # the code argument must survive (rfind, not the first match).
+        text = (
+            "<function=python><parameter=code>"
+            'print("</function>")'
+            "</parameter></function> all done"
+        )
+        call = _only(text)
+        assert call == {"name": "python", "arguments": {"code": 'print("</function>")'}}
+
+    def test_incomplete_function_without_close_is_still_rejected(self):
+        text = "<function=web_search><parameter=query>weather london"
+        assert parse_tool_calls_from_text(text, allow_incomplete = False) == []
+
+    def test_param_without_close_tag_is_rejected_in_strict_mode(self):
+        # Closing </function> present, but the single parameter never closes.
+        text = "<function=web_search><parameter=query>weather london</function>"
+        assert parse_tool_calls_from_text(text, allow_incomplete = False) == []
+
+
+class TestParityWithJsonStyle:
+    def test_json_tool_call_with_trailing_prose_is_accepted(self):
+        text = (
+            '<tool_call>{"name":"web_search","arguments":{"query":"weather london"}}</tool_call>'
+            " Let me check that for you."
+        )
+        calls = parse_tool_calls_from_text(text, allow_incomplete = False)
+        assert len(calls) == 1
+        assert calls[0]["function"]["name"] == "web_search"
+
+    def test_function_and_json_styles_agree_on_trailing_text(self):
+        q = "weather london"
+        func = parse_tool_calls_from_text(
+            f"<function=web_search><parameter=query>{q}</parameter></function> trailing",
+            allow_incomplete = False,
+        )
+        js = parse_tool_calls_from_text(
+            f'<tool_call>{{"name":"web_search","arguments":{{"query":"{q}"}}}}</tool_call> trailing',
+            allow_incomplete = False,
+        )
+        assert len(func) == len(js) == 1
+        assert json.loads(func[0]["function"]["arguments"]) == {"query": q}
+        assert json.loads(js[0]["function"]["arguments"]) == {"query": q}
+
+
+class TestHealingPathUnaffected:
+    def test_auto_heal_still_repairs_unclosed_function(self):
+        text = "<function=web_search><parameter=query>cats"
+        calls = parse_tool_calls_from_text(text, allow_incomplete = True)
+        assert len(calls) == 1
+        assert calls[0]["function"]["name"] == "web_search"
diff --git a/studio/backend/tests/test_tool_loop_controller.py b/studio/backend/tests/test_tool_loop_controller.py
new file mode 100644
index 0000000000..dea5de6d6e
--- /dev/null
+++ b/studio/backend/tests/test_tool_loop_controller.py
@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from core.inference.tool_loop_controller import (
+    ToolLoopController,
+    canonical_tool_call_key,
+    coerce_tool_arguments,
+    status_for_tool,
+    strip_result_for_model,
+    tool_event_provenance,
+)
+
+
+def _tool(name: str) -> dict:
+    return {"type": "function", "function": {"name": name}}
+
+
+def _call(
+    name: str,
+    args,
+    call_id: str = "call_0",
+) -> dict:
+    return {
+        "id": call_id,
+        "type": "function",
+        "function": {
+            "name": name,
+            "arguments": json.dumps(args) if isinstance(args, dict) else args,
+        },
+    }
+
+
+def test_canonical_tool_call_key_sorts_arguments():
+    a = canonical_tool_call_key("web_search", {"query": "gpu", "limit": 5})
+    b = canonical_tool_call_key("web_search", {"limit": 5, "query": "gpu"})
+    c = canonical_tool_call_key("python", {"limit": 5, "query": "gpu"})
+
+    assert a == b
+    assert a != c
+    assert a == 'web_search:{"limit":5,"query":"gpu"}'
+
+
+def test_coerce_tool_arguments_parses_json_and_heals_raw_strings():
+    parsed = coerce_tool_arguments('{"query":"gpu prices"}', heal = True)
+    healed = coerce_tool_arguments("print(1)", heal = True, tool_name = "python")
+    raw = coerce_tool_arguments("not-json", heal = False, tool_name = "python")
+
+    assert parsed.arguments == {"query": "gpu prices"}
+    assert not parsed.healed
+    assert healed.arguments == {"code": "print(1)"}
+    assert healed.healed
+    assert raw.arguments == {"raw": "not-json"}
+    assert not raw.healed
+
+
+def test_status_and_provenance_match_local_event_conventions():
+    assert status_for_tool("web_search", {"query": "gpus"}) == "Searching: gpus"
+    assert (
+        status_for_tool("web_search", {"url": "https://www.example.com/a"})
+        == "Reading: example.com"
+    )
+    assert status_for_tool("python", {"code": "print(1)\nprint(2)"}) == "Running Python: print(1)"
+    assert tool_event_provenance(healed = True, forced = False, provisional = None) == {
+        "source": "local",
+        "healed": True,
+    }
+
+
+def test_prepare_execute_builds_visible_events_and_model_tool_message():
+    controller = ToolLoopController(tools = [_tool("web_search")])
+    decision = controller.prepare_call(_call("web_search", {"query": "gpu prices"}))
+
+    assert decision.should_execute
+    assert decision.emit_visible_events
+    assert decision.status_text == "Searching: gpu prices"
+    assert decision.tool_start_payload()["arguments"] == {"query": "gpu prices"}
+    assert decision.tool_start_event()["type"] == "tool_start"
+    assert decision.as_assistant_tool_call()["function"]["arguments"] == '{"query":"gpu prices"}'
+
+    completion = controller.record_result(decision, "Search result\n__IMAGES__:{...}")
+
+    assert completion.tool_end_payload()["result"] == "Search result\n__IMAGES__:{...}"
+    assert completion.tool_end_event()["type"] == "tool_end"
+    assert completion.tool_message() == {
+        "role": "tool",
+        "name": "web_search",
+        "content": "Search result",
+        "tool_call_id": "call_0",
+    }
+
+
+def test_successful_duplicate_is_internal_noop_and_keeps_remaining_tools():
+    controller = ToolLoopController(tools = [_tool("web_search"), _tool("python")])
+    first = controller.prepare_call(_call("web_search", {"query": "gpu prices"}, "call_a"))
+    controller.record_result(first, "ok")
+
+    duplicate = controller.prepare_call(_call("web_search", {"query": "gpu prices"}, "call_b"))
+    completion = controller.record_noop(duplicate)
+
+    assert duplicate.action == "duplicate"
+    assert not duplicate.should_execute
+    assert not duplicate.emit_visible_events
+    duplicate_nudge = completion.model_message()["content"]
+    assert "already completed successfully" in duplicate_nudge
+    assert "different enabled tool" in duplicate_nudge
+    assert completion.model_message()["role"] == "user"
+    assert not controller.force_final_answer
+    assert [tool["function"]["name"] for tool in controller.active_tools()] == [
+        "web_search",
+        "python",
+    ]
+
+
+def test_repeated_successful_duplicate_becomes_terminal_after_one_recovery_nudge():
+    controller = ToolLoopController(tools = [_tool("web_search"), _tool("python")])
+    first = controller.prepare_call(_call("web_search", {"query": "gpu prices"}, "call_a"))
+    controller.record_result(first, "ok")
+
+    duplicate_one = controller.prepare_call(_call("web_search", {"query": "gpu prices"}, "call_b"))
+    completion_one = controller.record_noop(duplicate_one)
+
+    assert duplicate_one.action == "duplicate"
+    assert "already completed successfully" in completion_one.model_message()["content"]
+    assert not controller.force_final_answer
+    assert [tool["function"]["name"] for tool in controller.active_tools()] == [
+        "web_search",
+        "python",
+    ]
+
+    duplicate_two = controller.prepare_call(_call("web_search", {"query": "gpu prices"}, "call_c"))
+    completion_two = controller.record_noop(duplicate_two)
+
+    assert duplicate_two.action == "duplicate"
+    assert "already completed successfully" in completion_two.model_message()["content"]
+    assert controller.force_final_answer
+    assert controller.active_tools() == []
+
+
+def test_failed_call_does_not_block_retry():
+    controller = ToolLoopController(tools = [_tool("web_search")])
+    first = controller.prepare_call(_call("web_search", {"query": "gpu prices"}))
+    controller.record_result(first, "Error: temporary failure")
+
+    retry = controller.prepare_call(_call("web_search", {"query": "gpu prices"}))
+
+    assert retry.should_execute
+    assert retry.action == "execute"
+
+
+def test_empty_enabled_tool_list_blocks_all_tool_calls():
+    controller = ToolLoopController(tools = [])
+    decision = controller.prepare_call(_call("web_search", {"query": "gpu prices"}))
+    completion = controller.record_noop(decision)
+
+    assert decision.action == "disabled"
+    assert not decision.emit_visible_events
+    assert completion.model_message()["role"] == "user"
+    assert "not enabled" in completion.model_message()["content"]
+    assert controller.force_final_answer
+    assert controller.active_tools() == []
+
+
+def test_disabled_tool_is_internal_noop_not_visible_tool_error():
+    controller = ToolLoopController(tools = [_tool("web_search")])
+    decision = controller.prepare_call(_call("python", {"code": "print(1)"}))
+    completion = controller.record_noop(decision)
+
+    assert decision.action == "disabled"
+    assert not decision.emit_visible_events
+    assert completion.model_message()["role"] == "user"
+    assert "not enabled" in completion.model_message()["content"]
+    assert controller.force_final_answer
+    assert controller.active_tools() == []
+
+
+def test_render_html_success_filters_active_tools_and_repeat_is_internal():
+    controller = ToolLoopController(tools = [_tool("render_html"), _tool("web_search")])
+    assert [t["function"]["name"] for t in controller.active_tools()] == [
+        "render_html",
+        "web_search",
+    ]
+
+    first = controller.prepare_call(_call("render_html", {"code": "<html></html>"}, "call_html_1"))
+    controller.record_result(first, "Rendered HTML artifact: Demo")
+
+    assert [t["function"]["name"] for t in controller.active_tools()] == ["web_search"]
+
+    repeat = controller.prepare_call(_call("render_html", {"code": "<html></html>"}, "call_html_2"))
+    completion = controller.record_noop(repeat)
+
+    assert repeat.action == "render_html_repeat"
+    assert not repeat.emit_visible_events
+    assert completion.model_message()["role"] == "user"
+    assert "Do not call render_html again" in completion.model_message()["content"]
+    assert controller.force_final_answer
+    assert controller.active_tools() == []
+
+
+def test_strip_result_for_model_removes_frontend_image_sentinel():
+    assert strip_result_for_model('text\n__IMAGES__:{"paths":[]}') == "text"
+    assert strip_result_for_model("text __IMAGES__:payload") == "text"
+    assert strip_result_for_model("plain text") == "plain text"
diff --git a/studio/backend/tests/test_tool_xml_strip.py b/studio/backend/tests/test_tool_xml_strip.py
index 6cc01f2595..2ba3310fbe 100644
--- a/studio/backend/tests/test_tool_xml_strip.py
+++ b/studio/backend/tests/test_tool_xml_strip.py
@@ -27,11 +27,25 @@ assert _m, "could not extract _TOOL_XML_RE source"
 _ns = {"_re": _re}
 exec(f"_TOOL_XML_RE = _re.compile({_m.group(1)})", _ns)
 _TOOL_XML_RE = _ns["_TOOL_XML_RE"]
+_helper = _re.search(
+    r"def _strip_tool_xml_for_display\(text: str, \*, auto_heal_tool_calls: bool\) -> str:\n"
+    r"(?:    .+\n)+",
+    _src,
+)
+assert _helper, "could not extract _strip_tool_xml_for_display source"
+exec(_helper.group(0), _ns)
+_strip_tool_xml_for_display = _ns["_strip_tool_xml_for_display"]
 
 
 # ── Well-formed pairs ─────────────────────────────────────────────
 
 
+def test_route_display_strip_respects_disabled_auto_heal_contract():
+    text = 'literal <tool_call>{"name":"web_search"}</tool_call> survives'
+    assert _strip_tool_xml_for_display(text, auto_heal_tool_calls = False) == text
+    assert "<tool_call>" not in _strip_tool_xml_for_display(text, auto_heal_tool_calls = True)
+
+
 def test_strips_well_formed_tool_call():
     text = (
         "Let me search.\n"
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 31f73c37bd..34cae518e3 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -252,8 +252,7 @@ function documentCitationToSource(
   title: string;
   metadata?: { description: string };
 } | null {
-  const source =
-    typeof cit.source === "string" && cit.source ? cit.source : "";
+  const source = typeof cit.source === "string" && cit.source ? cit.source : "";
   const docTitle =
     (typeof cit.document_title === "string" && cit.document_title) ||
     (typeof cit.title === "string" && cit.title) ||
@@ -264,13 +263,12 @@ function documentCitationToSource(
   // search_result_location can carry a free-form id (e.g. ``kb-doc-42``)
   // or a hostile scheme. Fall back to a stable doc anchor otherwise.
   const url =
-    isSafeNavigableSourceUrl(source) || `#anthropic-doc-${docIndex ?? fallbackIdx}`;
+    isSafeNavigableSourceUrl(source) ||
+    `#anthropic-doc-${docIndex ?? fallbackIdx}`;
   const title = docTitle || source || `Document ${fallbackIdx + 1}`;
-  const cited =
-    typeof cit.cited_text === "string" ? cit.cited_text.trim() : "";
+  const cited = typeof cit.cited_text === "string" ? cit.cited_text.trim() : "";
   // Trim the cited snippet so the Sources panel stays scannable.
-  const description =
-    cited.length > 240 ? `${cited.slice(0, 240)}...` : cited;
+  const description = cited.length > 240 ? `${cited.slice(0, 240)}...` : cited;
   // Anthropic numbers inline [N] per citation, not per source URL.
   // Fold citation type + position-bearing fields into the id so distinct
   // citations on the same source keep separate Sources entries.
@@ -565,154 +563,6 @@ function isAnthropicRefusalMessage(message: RunMessage): boolean {
   return metadata?.custom?.anthropicRefusal === true;
 }
 
-function collectAssistantToolCalls(
-  message: RunMessage,
-): Array<{
-  id: string;
-  type: "function";
-  function: { name: string; arguments: string };
-  extra_content?: unknown;
-}> {
-  const out: Array<{
-    id: string;
-    type: "function";
-    function: { name: string; arguments: string };
-    extra_content?: unknown;
-  }> = [];
-  for (const part of message.content ?? []) {
-    if (part.type !== "tool-call") continue;
-    const tc = part as ToolCallMessagePart & {
-      argsText?: string;
-      extra_content?: unknown;
-    };
-    const toolNameLower = (tc.toolName ?? "").toLowerCase();
-    const argsObj =
-      tc.args && typeof tc.args === "object"
-        ? (tc.args as Record<string, unknown>)
-        : null;
-    const argsGoogle =
-      argsObj && typeof argsObj.google === "object" && argsObj.google !== null
-        ? (argsObj.google as Record<string, unknown>)
-        : null;
-    const hasNativePart = Boolean(
-      argsGoogle &&
-        typeof argsGoogle.native_part === "object" &&
-        argsGoogle.native_part !== null,
-    );
-    const hasServerToolMarker = Boolean(
-      argsObj && (argsObj as Record<string, unknown>)._server_tool === true,
-    );
-    const isServerSideBuiltin = isServerSideBuiltinToolPart(
-      toolNameLower,
-      argsObj,
-      hasServerToolMarker,
-      hasNativePart,
-    );
-    if (isServerSideBuiltin) {
-      // Gemini code_execution / image_generation must round-trip the
-      // native_part payload for native replay; drop the rest.
-      if (!hasNativePart) continue;
-    }
-    const argumentsStr =
-      typeof tc.argsText === "string" && tc.argsText.length > 0
-        ? tc.argsText
-        : JSON.stringify(tc.args ?? {});
-    const entry: {
-      id: string;
-      type: "function";
-      function: { name: string; arguments: string };
-      extra_content?: unknown;
-    } = {
-      id: tc.toolCallId,
-      type: "function" as const,
-      function: {
-        name: tc.toolName ?? "",
-        arguments: argumentsStr,
-      },
-    };
-    // Promote args.google to extra_content.google so the backend
-    // native_part replay branch finds it (it only inspects
-    // extra_content, not function.arguments).
-    if (tc.extra_content !== undefined) {
-      entry.extra_content = tc.extra_content;
-    } else if (argsGoogle) {
-      entry.extra_content = { google: argsGoogle };
-    }
-    out.push(entry);
-  }
-  return out;
-}
-
-function collectToolResultMessages(
-  message: RunMessage,
-): Array<{
-  role: "tool";
-  content: string;
-  tool_call_id: string;
-  name?: string;
-}> {
-  const out: Array<{
-    role: "tool";
-    content: string;
-    tool_call_id: string;
-    name?: string;
-  }> = [];
-  for (const part of message.content ?? []) {
-    if (part.type !== "tool-call") continue;
-    const tc = part as ToolCallMessagePart;
-    const result = (tc as { result?: unknown }).result;
-    // Skip provider-side builtins; see isServerSideBuiltinToolPart().
-    const argsObj =
-      tc.args && typeof tc.args === "object"
-        ? (tc.args as Record<string, unknown>)
-        : null;
-    const argsGoogle =
-      argsObj && typeof argsObj.google === "object" && argsObj.google !== null
-        ? (argsObj.google as Record<string, unknown>)
-        : null;
-    const toolNameLower = (tc.toolName ?? "").toLowerCase();
-    const hasServerToolMarker = Boolean(
-      argsObj && argsObj._server_tool === true,
-    );
-    const hasNativePart = Boolean(
-      argsGoogle &&
-        typeof argsGoogle.native_part === "object" &&
-        argsGoogle.native_part !== null,
-    );
-    if (
-      isServerSideBuiltinToolPart(
-        toolNameLower,
-        argsObj,
-        hasServerToolMarker,
-        hasNativePart,
-      )
-    ) {
-      continue;
-    }
-    if (result === undefined || result === null) continue;
-    let content: string;
-    if (typeof result === "string") {
-      // Backend ChatMessage validator rejects role="tool" with empty
-      // content; serialise sentinel JSON so legitimately empty tool
-      // outputs still round-trip to the provider.
-      content = result.length > 0 ? result : JSON.stringify({ result: "" });
-    } else {
-      try {
-        content = JSON.stringify(result);
-      } catch {
-        content = String(result);
-      }
-    }
-    out.push({
-      role: "tool",
-      content,
-      tool_call_id: tc.toolCallId,
-      ...(tc.toolName ? { name: tc.toolName } : {}),
-    });
-  }
-  return out;
-}
-
 type SerializedMessage = {
   role: "system" | "user" | "assistant" | "tool";
   content: OpenAIMessageContent | null;
@@ -733,6 +583,185 @@ type SerializedMessage = {
   extra_content?: unknown;
 };
 
+type SerializedToolCall = NonNullable<SerializedMessage["tool_calls"]>[number];
+type SerializedToolResult = {
+  role: "tool";
+  content: string;
+  tool_call_id: string;
+  name?: string;
+};
+
+type ToolPartReplayMetadata = {
+  argsObj: Record<string, unknown> | null;
+  argsGoogle: Record<string, unknown> | null;
+  hasNativePart: boolean;
+  isServerSideBuiltin: boolean;
+};
+
+function getToolPartReplayMetadata(
+  tc: ToolCallMessagePart,
+): ToolPartReplayMetadata {
+  const toolNameLower = (tc.toolName ?? "").toLowerCase();
+  const argsObj =
+    tc.args && typeof tc.args === "object"
+      ? (tc.args as Record<string, unknown>)
+      : null;
+  const argsGoogle =
+    argsObj && typeof argsObj.google === "object" && argsObj.google !== null
+      ? (argsObj.google as Record<string, unknown>)
+      : null;
+  const hasNativePart = Boolean(
+    argsGoogle &&
+      typeof argsGoogle.native_part === "object" &&
+      argsGoogle.native_part !== null,
+  );
+  const hasServerToolMarker = Boolean(
+    argsObj && (argsObj as Record<string, unknown>)._server_tool === true,
+  );
+  return {
+    argsObj,
+    argsGoogle,
+    hasNativePart,
+    isServerSideBuiltin: isServerSideBuiltinToolPart(
+      toolNameLower,
+      argsObj,
+      hasServerToolMarker,
+      hasNativePart,
+    ),
+  };
+}
+
+type ToolReplayProvenance = {
+  source?: string;
+  [key: string]: unknown;
+};
+
+function getToolReplayProvenance(
+  part: ToolCallMessagePart,
+): ToolReplayProvenance | null {
+  const provenance = (part as { provenance?: unknown }).provenance;
+  if (
+    !provenance ||
+    typeof provenance !== "object" ||
+    Array.isArray(provenance)
+  ) {
+    return null;
+  }
+  return provenance as ToolReplayProvenance;
+}
+
+function hasToolReplayResult(part: ToolCallMessagePart): boolean {
+  const result = (part as { result?: unknown }).result;
+  return result !== undefined && result !== null;
+}
+
+function shouldFlushCompletedLocalToolPair(part: ToolCallMessagePart): boolean {
+  const provenance = getToolReplayProvenance(part);
+  if (provenance?.source !== "local") {
+    return false;
+  }
+  if (getToolPartReplayMetadata(part).isServerSideBuiltin) {
+    return false;
+  }
+  return hasToolReplayResult(part);
+}
+
+function serializeAssistantToolCallPart(
+  part: ToolCallMessagePart,
+): SerializedToolCall | null {
+  const tc = part as ToolCallMessagePart & {
+    argsText?: string;
+    extra_content?: unknown;
+  };
+  const { argsGoogle, hasNativePart, isServerSideBuiltin } =
+    getToolPartReplayMetadata(tc);
+
+  if (isServerSideBuiltin && !hasNativePart) {
+    return null;
+  }
+
+  const argumentsStr =
+    typeof tc.argsText === "string" && tc.argsText.length > 0
+      ? tc.argsText
+      : JSON.stringify(tc.args ?? {});
+  const entry: SerializedToolCall = {
+    id: tc.toolCallId,
+    type: "function" as const,
+    function: {
+      name: tc.toolName ?? "",
+      arguments: argumentsStr,
+    },
+  };
+  // Promote args.google to extra_content.google so the backend
+  // native_part replay branch can find it. The backend only inspects
+  // extra_content, not function.arguments.
+  if (tc.extra_content !== undefined) {
+    entry.extra_content = tc.extra_content;
+  } else if (argsGoogle) {
+    entry.extra_content = { google: argsGoogle };
+  }
+  return entry;
+}
+
+function serializeToolResultPart(
+  part: ToolCallMessagePart,
+): SerializedToolResult | null {
+  const tc = part as ToolCallMessagePart;
+  const result = (tc as { result?: unknown }).result;
+  const { isServerSideBuiltin } = getToolPartReplayMetadata(tc);
+
+  // Skip provider-side builtins; see isServerSideBuiltinToolPart.
+  if (isServerSideBuiltin) {
+    return null;
+  }
+  if (result === undefined || result === null) return null;
+
+  let content: string;
+  if (typeof result === "string") {
+    // Backend ChatMessage validator rejects role="tool" with empty
+    // content; serialise a sentinel JSON so legitimately empty tool
+    // outputs still round-trip the follow-up turn to the provider.
+    content = result.length > 0 ? result : JSON.stringify({ result: "" });
+  } else {
+    try {
+      content = JSON.stringify(result);
+    } catch {
+      content = String(result);
+    }
+  }
+
+  return {
+    role: "tool" as const,
+    content,
+    tool_call_id: tc.toolCallId,
+    ...(tc.toolName ? { name: tc.toolName } : {}),
+  };
+}
+
+function canReplayToolCallWithoutRoleTool(part: ToolCallMessagePart): boolean {
+  // Gemini/OpenAI provider-native builtin cards replay through
+  // extra_content/native parts and intentionally do not produce role="tool"
+  // messages. Local/user tool calls must have a concrete tool result before
+  // they are replayed ahead of later assistant text.
+  return getToolPartReplayMetadata(part).isServerSideBuiltin;
+}
+
+function sanitizeAssistantReplayText(text: string): string {
+  return text.replace(
+    /data:audio\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/g,
+    "[audio]",
+  );
+}
+
+function buildReplayContent(
+  textContent: string,
+  imageParts: Array<{ type: "image_url"; image_url: { url: string } }>,
+): OpenAIMessageContent {
+  return imageParts.length > 0
+    ? [{ type: "text", text: textContent }, ...imageParts]
+    : textContent;
+}
+
 function collectAssistantTextThoughtSignature(
   message: RunMessage,
 ): string | undefined {
@@ -749,6 +778,132 @@ function collectAssistantTextThoughtSignature(
   return undefined;
 }
 
+function attachAssistantThoughtSignature(
+  messages: SerializedMessage[],
+  thoughtSignature: string | undefined,
+): void {
+  if (!thoughtSignature) return;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (message.role !== "assistant") continue;
+    const extra =
+      message.extra_content &&
+      typeof message.extra_content === "object" &&
+      !Array.isArray(message.extra_content)
+        ? (message.extra_content as Record<string, unknown>)
+        : {};
+    const google =
+      extra.google &&
+      typeof extra.google === "object" &&
+      !Array.isArray(extra.google)
+        ? (extra.google as Record<string, unknown>)
+        : {};
+    message.extra_content = {
+      ...extra,
+      google: { ...google, thought_signature: thoughtSignature },
+    };
+    return;
+  }
+}
+
+function serializeAssistantReplayMessages(
+  message: RunMessage,
+): SerializedMessage[] {
+  if (isAnthropicRefusalMessage(message)) {
+    // Prune refused assistant turn from outbound history; the
+    // rendered transcript still shows the user-visible notice.
+    return [];
+  }
+
+  const imageParts = collectImageParts(message);
+  const messages: SerializedMessage[] = [];
+  const pendingTextParts: string[] = [];
+  let pendingToolCalls: SerializedToolCall[] = [];
+  let pendingToolResults: SerializedToolResult[] = [];
+  let imagePartsPending = imageParts.length > 0;
+
+  const flushAssistantAndToolResults = (force = false): void => {
+    const textContent = sanitizeAssistantReplayText(
+      pendingTextParts.join("\n"),
+    );
+    const includeImageParts = imagePartsPending ? imageParts : [];
+    const hasContent = textContent.length > 0 || includeImageParts.length > 0;
+    const hasToolCalls = pendingToolCalls.length > 0;
+
+    if (!force && !hasContent && !hasToolCalls) {
+      return;
+    }
+
+    const assistantMessage: SerializedMessage = {
+      role: "assistant",
+      content: hasContent
+        ? buildReplayContent(textContent, includeImageParts)
+        : "",
+    };
+    if (hasToolCalls) {
+      assistantMessage.tool_calls = pendingToolCalls;
+      // OpenAI requires content === null on assistant turns whose
+      // payload is entirely tool_calls (matches the wire shape Gemini
+      // expects for the next functionCall replay).
+      if (!hasContent) {
+        assistantMessage.content = null;
+      }
+    }
+
+    messages.push(assistantMessage);
+    if (pendingToolResults.length > 0) {
+      messages.push(...pendingToolResults);
+    }
+
+    pendingTextParts.length = 0;
+    pendingToolCalls = [];
+    pendingToolResults = [];
+    imagePartsPending = false;
+  };
+
+  for (const part of message.content ?? []) {
+    if (part.type === "text") {
+      if (pendingToolCalls.length > 0) {
+        flushAssistantAndToolResults();
+      }
+      pendingTextParts.push(part.text);
+      continue;
+    }
+
+    if (part.type === "tool-call") {
+      const toolPart = part as ToolCallMessagePart;
+      const toolCall = serializeAssistantToolCallPart(toolPart);
+      if (!toolCall) continue;
+
+      const toolResult = serializeToolResultPart(toolPart);
+      if (!toolResult && !canReplayToolCallWithoutRoleTool(toolPart)) {
+        continue;
+      }
+
+      const flushLocalPair = shouldFlushCompletedLocalToolPair(toolPart);
+      if (flushLocalPair && pendingToolCalls.length > 0) {
+        flushAssistantAndToolResults();
+      }
+
+      pendingToolCalls.push(toolCall);
+      if (toolResult) {
+        pendingToolResults.push(toolResult);
+      }
+
+      if (flushLocalPair) {
+        flushAssistantAndToolResults();
+      }
+    }
+  }
+
+  flushAssistantAndToolResults(messages.length === 0);
+  attachAssistantThoughtSignature(
+    messages,
+    collectAssistantTextThoughtSignature(message),
+  );
+  return messages;
+}
+
 function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
   if (
     message.role !== "system" &&
@@ -758,49 +913,18 @@ function toOpenAIMessages(message: RunMessage): SerializedMessage[] {
     return [];
   }
 
-  let textContent = collectTextParts(message).join("\n");
   if (message.role === "assistant") {
-    textContent = textContent.replace(
-      /data:audio\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/g,
-      "[audio]",
-    );
-    if (isAnthropicRefusalMessage(message)) {
-      // Prune refused assistant turn from outbound history; the rendered
-      // transcript still shows the user-visible notice.
-      return [];
-    }
+    return serializeAssistantReplayMessages(message);
   }
 
+  const textContent = collectTextParts(message).join("\n");
   const imageParts = collectImageParts(message);
-  const toolCalls =
-    message.role === "assistant" ? collectAssistantToolCalls(message) : [];
-  const toolResults =
-    message.role === "assistant" ? collectToolResultMessages(message) : [];
-
-  const base: SerializedMessage = {
-    role: message.role,
-    content:
-      imageParts.length > 0
-        ? [{ type: "text", text: textContent }, ...imageParts]
-        : textContent,
-  };
-  if (toolCalls.length > 0) {
-    base.tool_calls = toolCalls;
-    // OpenAI requires content === null on assistant turns that are
-    // entirely tool_calls (matches the wire shape Gemini expects for
-    // the next functionCall replay).
-    if (!textContent && imageParts.length === 0) {
-      base.content = null;
-    }
-  }
-  if (message.role === "assistant") {
-    const sig = collectAssistantTextThoughtSignature(message);
-    if (sig) {
-      base.extra_content = { google: { thought_signature: sig } };
-    }
-  }
-
-  return toolResults.length > 0 ? [base, ...toolResults] : [base];
+  return [
+    {
+      role: message.role,
+      content: buildReplayContent(textContent, imageParts),
+    },
+  ];
 }
 
 function extractImageBase64(input: string): string | undefined {
@@ -1310,7 +1434,8 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         let loaded: boolean;
         let blockedByTrustRemoteCode: boolean;
         try {
-          ({ loaded, blockedByTrustRemoteCode } = await autoLoadSmallestModel());
+          ({ loaded, blockedByTrustRemoteCode } =
+            await autoLoadSmallestModel());
         } catch (error) {
           clearSelectedImageEditReference();
           throw error;
@@ -1772,8 +1897,23 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
       // <think>...</think> for parseAssistantContent. Lives outside the
       // SSE loop because the close tag fires when content arrives.
       let reasoningContentOpen = false;
+      type ToolCallProvenance = {
+        source?: string;
+        healed?: boolean;
+        forced?: boolean;
+        provisional?: boolean;
+        duplicate?: boolean;
+        reason?: string;
+        [key: string]: unknown;
+      };
+      type PositionedToolCallPart = ToolCallMessagePart & {
+        textCursor?: number;
+        _delta_index?: number;
+        extra_content?: unknown;
+        provenance?: ToolCallProvenance;
+      };
       // Tool call parts, cumulative; result lands on tool_end.
-      const toolCallParts: ToolCallMessagePart[] = [];
+      const toolCallParts: PositionedToolCallPart[] = [];
       // Latest Gemini text-part thoughtSignature; pinned onto the final
       // text MessagePart so next-turn replay carries it.
       let latestTextThoughtSignature: string | undefined;
@@ -1792,16 +1932,81 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         }
         return parts;
       };
-      const orderAssistantContent = (
-        textParts: ReturnType<typeof parseAssistantContent>,
-      ) => {
-        const imageToolParts = toolCallParts.filter(
-          (part) => part.toolName === "image_generation",
-        );
-        const otherToolParts = toolCallParts.filter(
-          (part) => part.toolName !== "image_generation",
-        );
-        return [...otherToolParts, ...textParts, ...imageToolParts];
+      const buildAssistantContent = (rawText: string) => {
+        const positionedTools = toolCallParts
+          .map((part, index) => {
+            const cursor = (part as PositionedToolCallPart).textCursor;
+            return {
+              part,
+              index,
+              cursor:
+                typeof cursor === "number" && Number.isFinite(cursor)
+                  ? Math.min(Math.max(cursor, 0), rawText.length)
+                  : 0,
+            };
+          })
+          .sort((a, b) => a.cursor - b.cursor || a.index - b.index);
+
+        const assembled: Array<
+          ReturnType<typeof parseAssistantContent>[number] | ToolCallMessagePart
+        > = [];
+        let textCursor = 0;
+        let toolIndex = 0;
+
+        const appendTextThrough = (nextCursor: number) => {
+          if (nextCursor <= textCursor) return;
+          assembled.push(
+            ...parseAssistantContent(rawText.slice(textCursor, nextCursor)),
+          );
+          textCursor = nextCursor;
+        };
+
+        while (toolIndex < positionedTools.length) {
+          const cursor = positionedTools[toolIndex].cursor;
+          appendTextThrough(cursor);
+          while (
+            toolIndex < positionedTools.length &&
+            positionedTools[toolIndex].cursor === cursor
+          ) {
+            assembled.push(positionedTools[toolIndex].part);
+            toolIndex += 1;
+          }
+        }
+        appendTextThrough(rawText.length);
+
+        return pinTextThoughtSignature(assembled);
+      };
+      const parseToolProvenance = (
+        value: unknown,
+      ): ToolCallProvenance | undefined => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          return undefined;
+        }
+        return { ...(value as Record<string, unknown>) } as ToolCallProvenance;
+      };
+      const mergeToolProvenance = (
+        existing: ToolCallProvenance | undefined,
+        incoming: ToolCallProvenance | undefined,
+      ): ToolCallProvenance | undefined => {
+        if (!incoming) return existing;
+        if (!existing) return incoming;
+        const merged: ToolCallProvenance = { ...existing, ...incoming };
+        for (const key of [
+          "healed",
+          "forced",
+          "provisional",
+          "duplicate",
+        ] as const) {
+          if (existing[key] === true || incoming[key] === true) {
+            merged[key] = true;
+          }
+        }
+        return merged;
+      };
+      const closeReasoningContent = () => {
+        if (!reasoningContentOpen) return;
+        cumulativeText += "</think>";
+        reasoningContentOpen = false;
       };
       // Anthropic document_citations payload, converted to Sources-panel
       // parts at end-of-stream so inline [N] markers have matching entries.
@@ -2189,7 +2394,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
           try {
             let requestPayload: OpenAIChatCompletionsRequest;
             try {
-              requestPayload = await buildRequestPayload(retriedWithRefreshedKey);
+              requestPayload = await buildRequestPayload(
+                retriedWithRefreshedKey,
+              );
             } catch (error) {
               clearSelectedImageEditReference();
               throw error;
@@ -2270,6 +2477,10 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   anthropicRefusalSeen = true;
                   continue;
                 }
+                closeReasoningContent();
+                const toolProvenance = parseToolProvenance(
+                  toolEvent.provenance,
+                );
                 if (toolEvent.type === "tool_start") {
                   const id =
                     (toolEvent.tool_call_id as string) ||
@@ -2280,11 +2491,18 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     (p) => p.toolCallId === id,
                   );
                   if (idx !== -1) {
+                    const existing = toolCallParts[
+                      idx
+                    ] as PositionedToolCallPart;
                     toolCallParts[idx] = {
-                      ...toolCallParts[idx],
+                      ...existing,
                       toolName: toolEvent.tool_name as string,
                       argsText: JSON.stringify(toolArgs),
                       args: toolArgs,
+                      provenance: mergeToolProvenance(
+                        existing.provenance,
+                        toolProvenance,
+                      ),
                     };
                   } else {
                     toolCallParts.push({
@@ -2293,7 +2511,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       toolName: toolEvent.tool_name as string,
                       argsText: JSON.stringify(toolArgs),
                       args: toolArgs,
-                    });
+                      textCursor: cumulativeText.length,
+                      ...(toolProvenance ? { provenance: toolProvenance } : {}),
+                    } as PositionedToolCallPart);
                   }
                 } else if (toolEvent.type === "tool_end") {
                   const id =
@@ -2437,21 +2657,23 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                         native_part: { parts: mergedParts },
                       };
                     }
+                    const existing = toolCallParts[
+                      idx
+                    ] as PositionedToolCallPart;
                     toolCallParts[idx] = {
-                      ...toolCallParts[idx],
+                      ...existing,
                       args: mergedArgs,
                       argsText: JSON.stringify(mergedArgs ?? {}),
                       result: parsedResult,
+                      provenance: mergeToolProvenance(
+                        existing.provenance,
+                        toolProvenance,
+                      ),
                     };
                   }
                 }
-                // Cumulative yield; orderAssistantContent puts search/code
-                // before text and generated images after.
-                const textParts = pinTextThoughtSignature(
-                  parseAssistantContent(cumulativeText),
-                );
                 yield {
-                  content: orderAssistantContent(textParts),
+                  content: buildAssistantContent(cumulativeText),
                   metadata: {
                     timing: buildTiming(
                       streamStartTime,
@@ -2504,10 +2726,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   | { extra_content?: unknown }
                   | undefined
               )?.extra_content;
-              if (
-                deltaExtraContent &&
-                typeof deltaExtraContent === "object"
-              ) {
+              if (deltaExtraContent && typeof deltaExtraContent === "object") {
                 const eGoogle = (deltaExtraContent as Record<string, unknown>)
                   .google;
                 if (eGoogle && typeof eGoogle === "object") {
@@ -2556,6 +2775,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 Array.isArray(rawDeltaToolCalls) &&
                 rawDeltaToolCalls.length > 0
               ) {
+                closeReasoningContent();
                 for (const tc of rawDeltaToolCalls) {
                   if (!tc || typeof tc !== "object") continue;
                   const call = tc as {
@@ -2575,20 +2795,16 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     : undefined;
                   if (!existing && idx !== undefined) {
                     existing = toolCallParts.find(
-                      (p) =>
-                        (
-                          p as ToolCallMessagePart & { _delta_index?: number }
-                        )._delta_index === idx,
+                      (p) => (p as PositionedToolCallPart)._delta_index === idx,
                     );
                   }
                   const argsFragment = call.function?.arguments ?? "";
                   if (existing) {
                     const prevName = existing.toolName ?? "";
                     const nextName = call.function?.name ?? prevName;
-                    const merged =
-                      (existing.argsText ?? "") + argsFragment;
-                    let parsedArgs:
-                      ToolCallMessagePart["args"] = existing.args ?? {};
+                    const merged = (existing.argsText ?? "") + argsFragment;
+                    let parsedArgs: ToolCallMessagePart["args"] =
+                      existing.args ?? {};
                     if (merged) {
                       try {
                         parsedArgs = JSON.parse(
@@ -2600,24 +2816,18 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                         } as ToolCallMessagePart["args"];
                       }
                     }
-                    const prevExtra = (
-                      existing as ToolCallMessagePart & {
-                        extra_content?: unknown;
-                      }
-                    ).extra_content;
-                    const updated: ToolCallMessagePart & {
-                      _delta_index?: number;
-                      extra_content?: unknown;
-                    } = {
-                      ...(existing as ToolCallMessagePart),
+                    const prevExtra = (existing as PositionedToolCallPart)
+                      .extra_content;
+                    const updated: PositionedToolCallPart = {
+                      ...(existing as PositionedToolCallPart),
                       toolName: nextName,
                       argsText: merged,
                       args: parsedArgs,
                       ...(call.extra_content !== undefined
                         ? { extra_content: call.extra_content }
                         : prevExtra !== undefined
-                        ? { extra_content: prevExtra }
-                        : {}),
+                          ? { extra_content: prevExtra }
+                          : {}),
                       ...(idx !== undefined ? { _delta_index: idx } : {}),
                     };
                     const replaceIdx = toolCallParts.indexOf(existing);
@@ -2626,8 +2836,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                     }
                   } else {
                     const callId =
-                      stableId ||
-                      `tool_call_${idx ?? toolCallParts.length}`;
+                      stableId || `tool_call_${idx ?? toolCallParts.length}`;
                     const argsText = argsFragment;
                     let parsedArgs: ToolCallMessagePart["args"] = {};
                     if (argsText) {
@@ -2641,15 +2850,13 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                         } as ToolCallMessagePart["args"];
                       }
                     }
-                    const fresh: ToolCallMessagePart & {
-                      _delta_index?: number;
-                      extra_content?: unknown;
-                    } = {
+                    const fresh: PositionedToolCallPart = {
                       type: "tool-call" as const,
                       toolCallId: callId,
                       toolName: call.function?.name ?? "",
                       argsText,
                       args: parsedArgs,
+                      textCursor: cumulativeText.length,
                       ...(call.extra_content !== undefined
                         ? { extra_content: call.extra_content }
                         : {}),
@@ -2659,12 +2866,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   }
                 }
                 yield {
-                  content: [
-                    ...toolCallParts,
-                    ...pinTextThoughtSignature(
-                      parseAssistantContent(cumulativeText),
-                    ),
-                  ],
+                  content: buildAssistantContent(cumulativeText),
                   metadata: {
                     timing: buildTiming(
                       streamStartTime,
@@ -2695,10 +2897,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 }
               }
               if (delta) {
-                if (reasoningContentOpen) {
-                  cumulativeText += "</think>";
-                  reasoningContentOpen = false;
-                }
+                closeReasoningContent();
                 cumulativeText += delta;
               }
               // Strip a trailing ${...} template-literal artifact from
@@ -2709,12 +2908,10 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                   "",
                 );
               }
-              const parts = pinTextThoughtSignature(
-                parseAssistantContent(cumulativeText),
-              );
+              const textParts = parseAssistantContent(cumulativeText);
 
               if (
-                parts.some((part) => part.type === "reasoning") &&
+                textParts.some((part) => part.type === "reasoning") &&
                 !reasoningStartAt
               ) {
                 reasoningStartAt = Date.now();
@@ -2729,9 +2926,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                 );
               }
 
-              if (parts.length > 0 || toolCallParts.length > 0) {
+              if (textParts.length > 0 || toolCallParts.length > 0) {
                 yield {
-                  content: orderAssistantContent(parts),
+                  content: buildAssistantContent(cumulativeText),
                   metadata: {
                     timing: buildTiming(
                       streamStartTime,
@@ -2756,13 +2953,10 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             throw streamError;
           }
         }
-        // If the stream ended inside a delta.reasoning_content block
-        // (Kimi / DeepSeek), close the open <think> tag so the reasoning
-        // panel parses cleanly.
-        if (reasoningContentOpen) {
-          cumulativeText += "</think>";
-          reasoningContentOpen = false;
-        }
+        // If the stream ended while we were still inside a
+        // delta.reasoning_content block (Kimi / DeepSeek path), close
+        // the open <think> tag so the reasoning panel parses cleanly.
+        closeReasoningContent();
         settleFirstTokenOk();
 
         // Extract source parts from completed web_search and web_fetch
@@ -2826,9 +3020,7 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
 
         yield {
           content: [
-            ...orderAssistantContent(
-              pinTextThoughtSignature(parseAssistantContent(cumulativeText)),
-            ),
+            ...buildAssistantContent(cumulativeText),
             ...sourceParts,
             ...documentCitationParts,
           ],

From a01960f20f6312f54d8c259c8d82d2c01544f53b Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 9 Jun 2026 07:29:47 -0700
Subject: [PATCH 122/222] [pre-commit.ci] pre-commit autoupdate (#6104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/astral-sh/ruff-pre-commit: v0.15.15 → v0.15.16](https://github.com/astral-sh/ruff-pre-commit/compare/v0.15.15...v0.15.16)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .pre-commit-config.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e018803a5f..56d32c9312 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.15
+    rev: v0.15.16
     hooks:
       - id: ruff
         args:

From 57be5868f9a4826b6be2b63646ce192afae24f50 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Tue, 9 Jun 2026 12:13:25 -0300
Subject: [PATCH 123/222] Studio: improve OpenAI- and Anthropic-compatible API
 spec compliance (#6010)

* Studio: fix OpenAI- and Anthropic-compatible API spec compliance

* Studio: fix API spec-compliance gaps on passthrough and streaming paths

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: carry context_length_exceeded through the OpenAI passthrough error path

* Studio: count tool-schema tokens in the Anthropic server-tool stream, and small stream-handling guards

* Studio: guard message_delta usage against None and normalize developer role before proxying

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: honor max_completion_tokens on the external-provider proxy path

* Studio: forward llama-server cached_tokens into OpenAI prompt_tokens_details

* Studio: sanitize messages in count_tokens to match the /v1/messages prompt

* Studio: report max_tokens for truncated tool calls and guard null usage in metadata events

* Studio: drop the request-id middleware (headers aren't declared in either spec)

* Studio: include the required request_id field in Anthropic error bodies

* Studio: honor max_completion_tokens on the audio (TTS / audio-input) paths

* Studio: add the _effective_max_tokens helper and route all max-token sites through it

* Studio: align API compatibility edge cases

* Studio: clarify multi-choice chat support

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: clarify logprobs chat support

* Studio: opt the local chat UI into the streaming usage chunk so the context bar and tok/s repopulate

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: forward seed to llama-server, and fix Anthropic server-tool stop_reason, tool_result id correlation, and parallel-tool execution cap

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: align OpenAI chat completion spec edge cases

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: align backend API compatibility tests

* Studio: honor tool caps and internal stream usage

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: coerce nullable stream usage counts

* Studio: preserve system prompts with developer messages

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: wasimysaid <wasimysdev@gmail.com>
---
 .../core/inference/anthropic_compat.py        |  112 +-
 studio/backend/core/inference/llama_cpp.py    |  178 ++-
 studio/backend/main.py                        |   12 +-
 studio/backend/models/inference.py            |   56 +-
 studio/backend/routes/data_recipe/jobs.py     |    6 +
 studio/backend/routes/inference.py            | 1143 +++++++++++++----
 .../backend/tests/test_anthropic_messages.py  |  173 ++-
 .../tests/test_gguf_completion_usage.py       |   28 +-
 .../tests/test_openai_tool_passthrough.py     |  348 ++++-
 .../tests/test_responses_tool_passthrough.py  |  149 +++
 studio/backend/utils/api_errors.py            |  252 ++++
 .../src/features/chat/api/chat-adapter.ts     |    3 +
 .../frontend/src/features/chat/types/api.ts   |    7 +
 13 files changed, 2174 insertions(+), 293 deletions(-)
 create mode 100644 studio/backend/utils/api_errors.py

diff --git a/studio/backend/core/inference/anthropic_compat.py b/studio/backend/core/inference/anthropic_compat.py
index c1f1c6b81e..0307336dde 100644
--- a/studio/backend/core/inference/anthropic_compat.py
+++ b/studio/backend/core/inference/anthropic_compat.py
@@ -10,9 +10,37 @@ Pure functions plus stateful stream emitters; no FastAPI, no I/O.
 from __future__ import annotations
 
 import json
+import uuid
 from typing import Any, Optional, Union
 
 
+def openai_finish_to_anthropic_stop(finish_reason, had_tool_calls = False) -> str:
+    """Map an OpenAI finish_reason to an Anthropic stop_reason.
+    'length' -> 'max_tokens' (truncation wins even mid tool call, so a cut-off
+    tool call isn't mislabeled tool_use); tool_calls / had_tool_calls -> 'tool_use';
+    'stop_sequence' -> 'stop_sequence'; 'stop'/None/unknown -> 'end_turn'."""
+    # Truncation takes precedence: a tool call cut off at max_tokens has possibly
+    # incomplete arguments, so report max_tokens rather than telling the client to
+    # run the tool.
+    if finish_reason == "length":
+        return "max_tokens"
+    if finish_reason == "tool_calls" or had_tool_calls:
+        return "tool_use"
+    if finish_reason == "stop_sequence":
+        return "stop_sequence"
+    # "stop", None, and any unknown value collapse to end_turn.
+    return "end_turn"
+
+
+def anthropic_tool_use_id(upstream_id = None) -> str:
+    """Return an Anthropic-style tool_use id (prefix 'toolu_'). Reuses an
+    upstream id only if it already starts with 'toolu_'; otherwise mints a fresh
+    'toolu_<24 hex>'."""
+    if upstream_id and isinstance(upstream_id, str) and upstream_id.startswith("toolu_"):
+        return upstream_id
+    return f"toolu_{uuid.uuid4().hex[:24]}"
+
+
 def _anthropic_image_block_to_openai_part(block: dict) -> Optional[dict]:
     """Translate one Anthropic ``image`` block to an OpenAI ``image_url`` part.
 
@@ -204,6 +232,19 @@ def build_anthropic_sse_event(event_type: str, data: dict) -> str:
     return f"event: {event_type}\ndata: {json.dumps(data)}\n\n"
 
 
+def _message_delta_usage(usage: Optional[dict]) -> dict:
+    """Usage block for a message_delta event (cumulative token counts). Cache
+    fields are always 0 — no prompt caching backend. ``usage`` may be None when a
+    metadata event carried usage=None (e.g. only finish_reason set)."""
+    usage = usage or {}
+    return {
+        "input_tokens": usage.get("prompt_tokens", 0),
+        "cache_creation_input_tokens": 0,
+        "cache_read_input_tokens": 0,
+        "output_tokens": usage.get("completion_tokens", 0),
+    }
+
+
 class AnthropicStreamEmitter:
     """Converts generate_chat_completion_with_tools() events into Anthropic
     Messages SSE strings."""
@@ -212,11 +253,19 @@ class AnthropicStreamEmitter:
         self.block_index: int = 0
         self._text_block_open: bool = False
         self._open_tool_call_id: Optional[str] = None
+        # The mapped Anthropic ``toolu_*`` id published in content_block_start,
+        # reused for the paired tool_result so consumers can correlate them.
+        self._open_tool_use_id: Optional[str] = None
         self._open_tool_args_sent: bool = False
         self._prev_text: str = ""
         self._usage: dict = {}
 
-    def start(self, message_id: str, model: str) -> list[str]:
+    def start(
+        self,
+        message_id: str,
+        model: str,
+        input_tokens: int = 0,
+    ) -> list[str]:
         """Emit message_start and open the first text content block."""
         events = []
         events.append(
@@ -232,7 +281,12 @@ class AnthropicStreamEmitter:
                         "model": model,
                         "stop_reason": None,
                         "stop_sequence": None,
-                        "usage": {"input_tokens": 0, "output_tokens": 0},
+                        "usage": {
+                            "input_tokens": input_tokens,
+                            "output_tokens": 0,
+                            "cache_creation_input_tokens": 0,
+                            "cache_read_input_tokens": 0,
+                        },
                     },
                 },
             )
@@ -255,22 +309,28 @@ class AnthropicStreamEmitter:
         # status events — no Anthropic equivalent
         return []
 
-    def finish(self, stop_reason: str = "end_turn") -> list[str]:
+    def finish(
+        self,
+        stop_reason: str = "end_turn",
+        stop_sequence = None,
+    ) -> list[str]:
         """Close any open block and emit message_delta + message_stop."""
         events = []
         if self._text_block_open or self._open_tool_call_id is not None:
             events.append(self._close_block())
             self._open_tool_call_id = None
+            self._open_tool_use_id = None
             self._open_tool_args_sent = False
         events.append(
             build_anthropic_sse_event(
                 "message_delta",
                 {
                     "type": "message_delta",
-                    "delta": {"stop_reason": stop_reason, "stop_sequence": None},
-                    "usage": {
-                        "output_tokens": self._usage.get("completion_tokens", 0),
+                    "delta": {
+                        "stop_reason": stop_reason,
+                        "stop_sequence": stop_sequence,
                     },
+                    "usage": _message_delta_usage(self._usage),
                 },
             )
         )
@@ -319,11 +379,13 @@ class AnthropicStreamEmitter:
         elif self._open_tool_call_id is not None:
             events.append(self._close_block())
             self._open_tool_call_id = None
+            self._open_tool_use_id = None
             self._open_tool_args_sent = False
 
         # Open a tool_use block.
         self.block_index += 1
         self._open_tool_call_id = tool_call_id
+        self._open_tool_use_id = anthropic_tool_use_id(tool_call_id)
         self._open_tool_args_sent = False
         events.append(
             build_anthropic_sse_event(
@@ -333,7 +395,7 @@ class AnthropicStreamEmitter:
                     "index": self.block_index,
                     "content_block": {
                         "type": "tool_use",
-                        "id": tool_call_id,
+                        "id": self._open_tool_use_id,
                         "name": event.get("tool_name", ""),
                         "input": {},
                     },
@@ -368,7 +430,11 @@ class AnthropicStreamEmitter:
         # Close the tool_use block.
         if self._open_tool_call_id is not None or self._text_block_open:
             events.append(self._close_block())
+        # Reuse the id published in content_block_start; fall back to mapping
+        # the raw id only if no tool_start preceded this end.
+        tool_use_id = self._open_tool_use_id or anthropic_tool_use_id(event.get("tool_call_id", ""))
         self._open_tool_call_id = None
+        self._open_tool_use_id = None
         self._open_tool_args_sent = False
         # Emit custom tool_result event (non-standard, ignored by SDKs)
         events.append(
@@ -376,7 +442,7 @@ class AnthropicStreamEmitter:
                 "tool_result",
                 {
                     "type": "tool_result",
-                    "tool_use_id": event.get("tool_call_id", ""),
+                    "tool_use_id": tool_use_id,
                     "content": event.get("result", ""),
                 },
             )
@@ -427,8 +493,14 @@ class AnthropicPassthroughEmitter:
         self._tool_call_states: dict = {}  # delta index -> {block_index, id, name}
         self._usage: dict = {}
         self._stop_reason: str = "end_turn"
+        self._stop_sequence: Optional[str] = None
 
-    def start(self, message_id: str, model: str) -> list[str]:
+    def start(
+        self,
+        message_id: str,
+        model: str,
+        input_tokens: int = 0,
+    ) -> list[str]:
         return [
             build_anthropic_sse_event(
                 "message_start",
@@ -442,7 +514,12 @@ class AnthropicPassthroughEmitter:
                         "model": model,
                         "stop_reason": None,
                         "stop_sequence": None,
-                        "usage": {"input_tokens": 0, "output_tokens": 0},
+                        "usage": {
+                            "input_tokens": input_tokens,
+                            "output_tokens": 0,
+                            "cache_creation_input_tokens": 0,
+                            "cache_read_input_tokens": 0,
+                        },
                     },
                 },
             )
@@ -492,7 +569,7 @@ class AnthropicPassthroughEmitter:
                 # New tool call — close prior block, open tool_use block
                 if self._current_block_type is not None:
                     events.append(self._close_current_block())
-                tc_id = tc.get("id", "")
+                tc_id = anthropic_tool_use_id(tc.get("id", ""))
                 tc_name = fn.get("name", "")
                 self.block_index += 1
                 self._current_block_type = "tool_use"
@@ -535,12 +612,7 @@ class AnthropicPassthroughEmitter:
 
         # ── Finish reason ──
         if finish_reason:
-            if finish_reason == "tool_calls":
-                self._stop_reason = "tool_use"
-            elif finish_reason == "length":
-                self._stop_reason = "max_tokens"
-            else:
-                self._stop_reason = "end_turn"
+            self._stop_reason = openai_finish_to_anthropic_stop(finish_reason)
 
         return events
 
@@ -555,11 +627,9 @@ class AnthropicPassthroughEmitter:
                     "type": "message_delta",
                     "delta": {
                         "stop_reason": self._stop_reason,
-                        "stop_sequence": None,
-                    },
-                    "usage": {
-                        "output_tokens": self._usage.get("completion_tokens", 0),
+                        "stop_sequence": self._stop_sequence,
                     },
+                    "usage": _message_delta_usage(self._usage),
                 },
             )
         )
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index d12eb6e29e..ec3a216258 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -4116,6 +4116,7 @@ class LlamaCppBackend:
         enable_thinking: Optional[bool] = None,
         reasoning_effort: Optional[str] = None,
         preserve_thinking: Optional[bool] = None,
+        seed: Optional[int] = None,
     ) -> Generator[str | dict, None, None]:
         """
         Send a chat completion to llama-server and stream tokens back.
@@ -4156,6 +4157,8 @@ class LlamaCppBackend:
         payload["t_max_predict_ms"] = _DEFAULT_T_MAX_PREDICT_MS
         if stop:
             payload["stop"] = stop
+        if seed is not None:
+            payload["seed"] = seed
         payload["stream_options"] = {"include_usage": True}
 
         url = f"{self.base_url}/v1/chat/completions"
@@ -4164,6 +4167,7 @@ class LlamaCppBackend:
         _stream_done = False
         _metadata_usage = None
         _metadata_timings = None
+        _metadata_finish_reason = None
 
         try:
             # _stream_with_retry uses a 120 s read timeout so prefill can
@@ -4228,6 +4232,9 @@ class LlamaCppBackend:
                                 choices = data.get("choices", [])
                                 if choices:
                                     delta = choices[0].get("delta", {})
+                                    _fr = choices[0].get("finish_reason")
+                                    if _fr:
+                                        _metadata_finish_reason = _fr
 
                                     # Reasoning/thinking tokens: llama-server
                                     # sends these as "reasoning_content"; wrap
@@ -4253,14 +4260,18 @@ class LlamaCppBackend:
                                 logger.debug(f"Skipping malformed SSE line: {line[:100]}")
                         if _stream_done:
                             break  # exit outer for
-                    if _metadata_usage or _metadata_timings:
+                    if _metadata_usage or _metadata_timings or _metadata_finish_reason:
                         _metadata_usage = _backfill_usage_from_timings(
                             _metadata_usage, _metadata_timings
                         )
                         yield {
                             "type": "metadata",
-                            "usage": _metadata_usage,
+                            # Never None: a finish-only metadata event (no usage,
+                            # no timings) would otherwise crash consumers that do
+                            # usage.get(...) on the non-streaming paths.
+                            "usage": _metadata_usage or {},
                             "timings": _metadata_timings,
+                            "finish_reason": _metadata_finish_reason,
                         }
 
         except httpx.ConnectError:
@@ -4292,6 +4303,8 @@ class LlamaCppBackend:
         auto_heal_tool_calls: bool = True,
         tool_call_timeout: int = 300,
         session_id: Optional[str] = None,
+        seed: Optional[int] = None,
+        disable_parallel_tool_use: bool = False,
     ) -> Generator[dict, None, None]:
         """
         Agentic loop: let the model call tools, execute them, and continue.
@@ -4394,6 +4407,8 @@ class LlamaCppBackend:
             payload["t_max_predict_ms"] = _DEFAULT_T_MAX_PREDICT_MS
             if stop:
                 payload["stop"] = stop
+            if seed is not None:
+                payload["seed"] = seed
 
             try:
                 _auth_headers = (
@@ -4419,6 +4434,7 @@ class LlamaCppBackend:
                 has_structured_tc = False
                 _iter_usage = None
                 _iter_timings = None
+                _iter_finish_reason = None
                 _stream_done = False
                 _last_emitted = ""
                 provisional_render_html_tool_call_ids = set()
@@ -4498,6 +4514,9 @@ class LlamaCppBackend:
                                         continue
 
                                     delta = choices[0].get("delta", {})
+                                    _fr = choices[0].get("finish_reason")
+                                    if _fr:
+                                        _iter_finish_reason = _fr
 
                                     # ── Structured tool_calls ──
                                     tc_deltas = delta.get("tool_calls")
@@ -4840,6 +4859,7 @@ class LlamaCppBackend:
                                     "total_tokens": _fp + _tc,
                                 },
                                 "timings": _mt,
+                                "finish_reason": _iter_finish_reason,
                             }
                         return
 
@@ -4915,6 +4935,7 @@ class LlamaCppBackend:
                                     "total_tokens": _fp + _tc,
                                 },
                                 "timings": _mt,
+                                "finish_reason": _iter_finish_reason,
                             }
                         return
 
@@ -4926,6 +4947,12 @@ class LlamaCppBackend:
                 _accumulated_predicted_ms += _it.get("predicted_ms", 0)
                 _accumulated_predicted_n += _it.get("predicted_n", 0)
 
+                # disable_parallel_tool_use: execute only the first tool call
+                # this turn. Truncate before building assistant_msg so the
+                # conversation stays consistent and extra calls are never executed.
+                if disable_parallel_tool_use and tool_calls and len(tool_calls) > 1:
+                    tool_calls = tool_calls[:1]
+
                 assistant_msg: dict = {"role": "assistant", "content": content_text}
                 assistant_appended = False
 
@@ -5040,6 +5067,8 @@ class LlamaCppBackend:
         stream_payload["t_max_predict_ms"] = _DEFAULT_T_MAX_PREDICT_MS
         if stop:
             stream_payload["stop"] = stop
+        if seed is not None:
+            stream_payload["seed"] = seed
         stream_payload["stream_options"] = {"include_usage": True}
 
         cumulative = ""
@@ -5049,6 +5078,7 @@ class LlamaCppBackend:
         reasoning_text = ""
         _metadata_usage = None
         _metadata_timings = None
+        _metadata_finish_reason = None
         _stream_done = False
 
         try:
@@ -5107,6 +5137,9 @@ class LlamaCppBackend:
                                 choices = chunk_data.get("choices", [])
                                 if choices:
                                     delta = choices[0].get("delta", {})
+                                    _fr = choices[0].get("finish_reason")
+                                    if _fr:
+                                        _metadata_finish_reason = _fr
 
                                     reasoning = delta.get("reasoning_content", "")
                                     if reasoning:
@@ -5137,7 +5170,7 @@ class LlamaCppBackend:
                     _final_completion = _final_usage.get("completion_tokens", 0)
                     _final_prompt = _final_usage.get("prompt_tokens", 0)
                     _total_completion = _final_completion + _accumulated_completion_tokens
-                    if _metadata_usage or _metadata_timings:
+                    if _metadata_usage or _metadata_timings or _metadata_finish_reason:
                         _merged_timings = dict(_metadata_timings) if _metadata_timings else {}
                         if _accumulated_predicted_ms or _accumulated_predicted_n:
                             _merged_timings["predicted_ms"] = (
@@ -5160,6 +5193,7 @@ class LlamaCppBackend:
                                 "total_tokens": _final_prompt + _total_completion,
                             },
                             "timings": _merged_timings,
+                            "finish_reason": _metadata_finish_reason,
                         }
 
         except httpx.ConnectError:
@@ -5169,6 +5203,144 @@ class LlamaCppBackend:
                 return
             raise
 
+    # ── Prompt token counting ──────────────────────────────────
+
+    def count_chat_tokens(
+        self,
+        messages,
+        system = None,
+        tools = None,
+        strict: bool = False,
+    ) -> int:
+        """Count prompt tokens for a chat request via llama-server.
+
+        Non-strict callers keep the historical best-effort behavior and receive
+        0 when a count cannot be determined. Strict callers (public count_tokens
+        endpoints) get an exception instead of a successful-looking zero when
+        tokenizer/template calls fail or a multimodal prompt would fall back to a
+        text-only approximation.
+        """
+        if not self.is_loaded:
+            if strict:
+                raise RuntimeError("llama-server is not loaded")
+            return 0
+
+        def _has_non_text_content(content) -> bool:
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, str):
+                        continue
+                    if not isinstance(block, dict):
+                        return True
+                    if block.get("type") == "text" and isinstance(block.get("text"), str):
+                        continue
+                    if isinstance(block.get("text"), str):
+                        continue
+                    return True
+            return False
+
+        def _has_non_text_prompt_parts() -> bool:
+            if _has_non_text_content(system):
+                return True
+            for msg in messages or []:
+                if isinstance(msg, dict) and _has_non_text_content(msg.get("content", "")):
+                    return True
+            return False
+
+        def _block_text(content) -> str:
+            if isinstance(content, str):
+                return content
+            if isinstance(content, list):
+                parts = []
+                for block in content:
+                    if isinstance(block, dict):
+                        if block.get("type") == "text" and isinstance(block.get("text"), str):
+                            parts.append(block["text"])
+                        elif isinstance(block.get("text"), str):
+                            parts.append(block["text"])
+                    elif isinstance(block, str):
+                        parts.append(block)
+                return "".join(parts)
+            return ""
+
+        # Normalize system into a leading message / plain text.
+        system_text = ""
+        if isinstance(system, str):
+            system_text = system
+        elif isinstance(system, list):
+            system_text = _block_text(system)
+
+        try:
+            _auth_headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else None
+            with httpx.Client(timeout = 10, headers = _auth_headers) as client:
+
+                def _tokenize(text: str) -> int:
+                    r = client.post(
+                        f"{self.base_url}/tokenize",
+                        json = {"content": text, "add_special": True},
+                    )
+                    if r.status_code != 200:
+                        if strict:
+                            raise RuntimeError("llama-server tokenizer failed")
+                        return 0
+                    tokens = r.json().get("tokens", [])
+                    if not isinstance(tokens, list):
+                        if strict:
+                            raise RuntimeError("llama-server tokenizer returned invalid tokens")
+                        return 0
+                    return len(tokens)
+
+                # 1. Try /apply-template to render the real chat prompt.
+                template_messages = list(messages) if messages else []
+                if system_text:
+                    template_messages = [
+                        {"role": "system", "content": system_text}
+                    ] + template_messages
+                apply_template_failed = False
+                try:
+                    # llama-server's /apply-template renders tool declarations
+                    # into the prompt when ``tools`` is supplied, so pass them
+                    # through — otherwise tool-schema tokens go uncounted.
+                    template_body = {"messages": template_messages}
+                    if tools:
+                        template_body["tools"] = tools
+                    resp = client.post(
+                        f"{self.base_url}/apply-template",
+                        json = template_body,
+                    )
+                    if resp.status_code == 200:
+                        prompt = resp.json().get("prompt", "")
+                        if isinstance(prompt, str):
+                            return _tokenize(prompt)
+                    apply_template_failed = True
+                except Exception:
+                    apply_template_failed = True
+
+                if strict and apply_template_failed and _has_non_text_prompt_parts():
+                    raise RuntimeError(
+                        "cannot fall back to text-only token counting for multimodal messages"
+                    )
+
+                # 2. Fallback: concatenate plain text and tokenize. Append a
+                # serialized form of the tools so they still contribute to the
+                # count when /apply-template is unavailable.
+                parts = []
+                if system_text:
+                    parts.append(system_text)
+                for msg in messages or []:
+                    if isinstance(msg, dict):
+                        parts.append(_block_text(msg.get("content", "")))
+                if tools:
+                    try:
+                        parts.append(json.dumps(tools, ensure_ascii = False))
+                    except Exception:
+                        pass
+                return _tokenize("\n".join(p for p in parts if p))
+        except Exception:
+            if strict:
+                raise
+            return 0
+
     # ── TTS support ────────────────────────────────────────────
 
     def detect_audio_type(self) -> Optional[str]:
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 321995885c..1794e0a9af 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -247,6 +247,7 @@ from utils.update_status import (
     get_studio_update_status,
 )
 from utils.studio_version import get_studio_version
+from utils.api_errors import install_api_error_handlers
 
 
 def get_unsloth_version() -> str:
@@ -719,6 +720,7 @@ app.add_middleware(
     allow_headers = ["*"],
 )
 
+
 # ============ Register API Routes ============
 
 # Register routers
@@ -743,6 +745,10 @@ app.include_router(training_history_router, prefix = "/api/train", tags = ["trai
 app.include_router(hub_inventory_router, prefix = "/api/hub", tags = ["hub"])
 app.include_router(hub_datasets_router, prefix = "/api/hub/datasets", tags = ["hub"])
 
+# Re-wrap client-error responses on the /v1/* surface into OpenAI/Anthropic
+# error envelopes; non-/v1 paths keep FastAPI's default {"detail": ...} shape.
+install_api_error_handlers(app)
+
 
 # ============ Health and System Endpoints ============
 
@@ -1055,8 +1061,12 @@ def setup_frontend(app: FastAPI, build_path: Path):
 
     @app.get("/{full_path:path}")
     async def serve_frontend(request: Request, full_path: str):
+        # Unknown API paths: raise a real 404 so the api_errors handlers can
+        # render the correct envelope for /v1/* (and {"detail":...} for /api/*).
+        # This handler only sees paths NOT matched by a real route. The full
+        # request path is "/" + full_path.
         if full_path in {"api", "v1"} or full_path.startswith(("api/", "v1/")):
-            return {"error": "API endpoint not found"}
+            raise HTTPException(status_code = 404, detail = "API endpoint not found")
 
         file_path = (build_path / full_path).resolve()
 
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 9005f087be..3482303eeb 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -495,7 +495,9 @@ class ChatMessage(BaseModel):
     ``role="tool"`` is resolved at the ``ChatCompletionRequest`` layer.
     """
 
-    role: Literal["system", "user", "assistant", "tool"] = Field(..., description = "Message role")
+    role: Literal["system", "user", "assistant", "tool", "developer"] = Field(
+        ..., description = "Message role"
+    )
     content: Optional[Union[str, list[ContentPart]]] = Field(
         None, description = "Message content (string or multimodal parts)"
     )
@@ -590,6 +592,34 @@ class ChatCompletionRequest(BaseModel):
             "{'type': 'function', 'function': {'name': ...}}"
         ),
     )
+    max_completion_tokens: Optional[int] = Field(
+        None,
+        ge = 1,
+        description = "OpenAI upper bound on generated tokens (supersedes the deprecated max_tokens).",
+    )
+    n: Optional[int] = Field(
+        None,
+        ge = 1,
+        le = 128,
+        description = "Number of chat completion choices to generate.",
+    )
+    logprobs: Optional[bool] = Field(
+        None, description = "Whether to return log probabilities of the output tokens."
+    )
+    top_logprobs: Optional[int] = Field(
+        None,
+        ge = 0,
+        le = 20,
+        description = "Number of most likely tokens (0-20) to return per position; requires logprobs=true.",
+    )
+    parallel_tool_calls: Optional[bool] = Field(
+        None, description = "Whether to enable parallel function calling during tool use."
+    )
+    seed: Optional[int] = Field(None, description = "Best-effort deterministic sampling seed.")
+    stream_options: Optional[dict] = Field(
+        None,
+        description = 'Streaming options, e.g. {"include_usage": true} to emit a final usage chunk.',
+    )
 
     # ── Unsloth extensions (ignored by standard OpenAI clients) ──
     top_k: int = Field(20, ge = -1, le = 100, description = "[x-unsloth] Top-k sampling")
@@ -933,12 +963,16 @@ class ChoiceDelta(BaseModel):
     content: Optional[str] = None
 
 
+OpenAIFinishReason = Literal["stop", "length", "tool_calls", "content_filter", "function_call"]
+
+
 class ChunkChoice(BaseModel):
     """A single choice in a streaming chunk."""
 
     index: int = 0
     delta: ChoiceDelta
-    finish_reason: Optional[Literal["stop", "length"]] = None
+    finish_reason: Optional[OpenAIFinishReason] = None
+    logprobs: Optional[dict] = None
 
 
 class ChatCompletionChunk(BaseModel):
@@ -961,6 +995,7 @@ class CompletionMessage(BaseModel):
 
     role: Literal["assistant"] = "assistant"
     content: str
+    refusal: Optional[str] = None
 
 
 class CompletionChoice(BaseModel):
@@ -968,7 +1003,8 @@ class CompletionChoice(BaseModel):
 
     index: int = 0
     message: CompletionMessage
-    finish_reason: Literal["stop", "length"] = "stop"
+    finish_reason: OpenAIFinishReason = "stop"
+    logprobs: Optional[dict] = None
 
 
 class CompletionUsage(BaseModel):
@@ -977,6 +1013,17 @@ class CompletionUsage(BaseModel):
     prompt_tokens: int = 0
     completion_tokens: int = 0
     total_tokens: int = 0
+    prompt_tokens_details: Optional[dict] = Field(
+        default_factory = lambda: {"cached_tokens": 0, "audio_tokens": 0}
+    )
+    completion_tokens_details: Optional[dict] = Field(
+        default_factory = lambda: {
+            "reasoning_tokens": 0,
+            "audio_tokens": 0,
+            "accepted_prediction_tokens": 0,
+            "rejected_prediction_tokens": 0,
+        }
+    )
 
 
 class ChatCompletion(BaseModel):
@@ -988,6 +1035,7 @@ class ChatCompletion(BaseModel):
     model: str = "default"
     choices: list[CompletionChoice]
     usage: CompletionUsage = Field(default_factory = CompletionUsage)
+    system_fingerprint: Optional[str] = None
 
 
 # =====================================================================
@@ -1434,6 +1482,8 @@ class AnthropicMessagesRequest(BaseModel):
 
 class AnthropicUsage(BaseModel):
     input_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
     output_tokens: int = 0
 
 
diff --git a/studio/backend/routes/data_recipe/jobs.py b/studio/backend/routes/data_recipe/jobs.py
index 3874bd587c..59714380da 100644
--- a/studio/backend/routes/data_recipe/jobs.py
+++ b/studio/backend/routes/data_recipe/jobs.py
@@ -243,6 +243,12 @@ def _inject_local_structured_response_format(
             "type": "json_schema",
             "schema": output_format,
         }
+        # The OpenAI chat endpoint now returns raw JSON by default for
+        # response_format requests (spec compliance for public clients). This
+        # internal opt-in flag rides through the OpenAI SDK's extra_body
+        # passthrough alongside response_format and re-enables the ```json
+        # markdown fence that data_designer's structured-output parser expects.
+        extra_body["_unsloth_guided_fence"] = True
         params["extra_body"] = extra_body
         new_configs.append(clone)
         column["model_alias"] = clone_alias
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 28634396f5..a2e0e5a811 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -26,6 +26,8 @@ import re as _re
 # Model size extraction (shared with core/inference/llama_cpp.py)
 from utils.models import extract_model_size_b as _extract_model_size_b
 
+from utils.api_errors import openai_error_body, anthropic_error_body
+
 
 def _install_httpcore_asyncgen_silencer() -> None:
     """Silence benign httpx/httpcore asyncgen GC noise on Python 3.13.
@@ -107,6 +109,273 @@ def _friendly_error(exc: Exception) -> str:
     return "An internal error occurred"
 
 
+def _clamp_finish_reason(value) -> str:
+    """Coerce an upstream finish_reason into OpenAI's known chat values.
+
+    Unknown values (including ``None``) become ``"stop"`` so local upstream
+    quirks do not leak into the public API shape.
+    """
+    return (
+        value
+        if value
+        in (
+            "stop",
+            "length",
+            "tool_calls",
+            "content_filter",
+            "function_call",
+        )
+        else "stop"
+    )
+
+
+def _normalize_stop_sequences(raw):
+    """Coerce an OpenAI/Anthropic ``stop`` value into the list-of-non-empty-strings
+    shape llama-server expects, or ``None`` when absent. A bare string becomes a
+    single-element list; empty strings are dropped (an empty stop sequence would
+    terminate generation immediately at position 0)."""
+    if isinstance(raw, str):
+        return [raw] if raw else None
+    if isinstance(raw, list):
+        return [s for s in raw if isinstance(s, str) and s] or None
+    return None
+
+
+def _effective_max_tokens(payload):
+    """Resolve the generation cap, preferring OpenAI's replacement field.
+
+    ``max_tokens`` is deprecated in favor of ``max_completion_tokens``; honor
+    either for compatibility, but let the replacement field win when both are
+    supplied.
+    """
+    return (
+        payload.max_completion_tokens
+        if payload.max_completion_tokens is not None
+        else payload.max_tokens
+    )
+
+
+def _wants_multiple_choices(payload) -> bool:
+    return (payload.n or 1) > 1
+
+
+def _raise_unsupported_openai_parameter(param: str, message: str) -> None:
+    raise HTTPException(
+        status_code = 400,
+        detail = openai_error_body(
+            message,
+            status = 400,
+            code = "unsupported_parameter",
+            param = param,
+        ),
+    )
+
+
+def _raise_unsupported_n(path_label: str) -> None:
+    _raise_unsupported_openai_parameter("n", f"n > 1 is not supported for {path_label}.")
+
+
+def _openai_stream_error_chunk(exc) -> dict:
+    """Build an in-band OpenAI error chunk for a mid-stream failure. Once the
+    stream's 200 headers are flushed the status can't change, so the error must
+    ride in the SSE body. An upstream context-window overflow is mapped to
+    code=context_length_exceeded so client compaction/trim loops can detect it
+    (a code-less error hides it)."""
+    _cls = _classify_llama_generation_error(exc)
+    if _cls:
+        return openai_error_body(_friendly_error(exc), status = 400, code = "context_length_exceeded")
+    if _cls is False:
+        return openai_error_body(_friendly_error(exc), status = 400)
+    return openai_error_body(_friendly_error(exc), status = 500)
+
+
+def _openai_passthrough_error(status_code, text) -> "HTTPException":
+    """HTTPException for a non-200 upstream response on the OpenAI passthrough
+    (tools / response_format). An over-context upstream error is mapped to a 400
+    with code="context_length_exceeded" so these paths deliver the same signal as
+    the non-passthrough path; any other upstream error keeps llama-server's
+    message verbatim."""
+    if _classify_llama_generation_error(Exception(text)):
+        return HTTPException(
+            status_code = 400,
+            detail = openai_error_body(
+                _friendly_error(Exception(text)),
+                status = 400,
+                code = "context_length_exceeded",
+                param = "messages",
+            ),
+        )
+    return HTTPException(
+        status_code = status_code,
+        detail = f"llama-server error: {text[:500]}",
+    )
+
+
+def _anthropic_stream_error_event(exc):
+    """Anthropic in-band SSE ``error`` event for a mid-stream failure, or ``None``
+    to fall through to a normal message_delta finish. Returns an event only for a
+    classifiable upstream client error (context overflow / 4xx) so a streaming
+    over-context request surfaces a real error instead of a silent empty
+    end_turn message."""
+    if _classify_llama_generation_error(exc) is None:
+        return None
+    return build_anthropic_sse_event(
+        "error",
+        anthropic_error_body(_friendly_error(exc), status = 400),
+    )
+
+
+def _drop_parallel_tool_call_deltas(chunk) -> bool:
+    """In-place: drop tool_call deltas whose index >= 1 from a parsed OpenAI
+    streaming chunk so only the first tool call survives (parallel_tool_calls=false
+    / disable_parallel_tool_use, best-effort). Returns True if anything changed."""
+    if not isinstance(chunk, dict):
+        return False
+    changed = False
+    for ch in chunk.get("choices") or []:
+        delta = ch.get("delta") or {}
+        tcs = delta.get("tool_calls")
+        if isinstance(tcs, list):
+            kept = [tc for tc in tcs if isinstance(tc, dict) and (tc.get("index") or 0) == 0]
+            if len(kept) != len(tcs):
+                delta["tool_calls"] = kept
+                changed = True
+    return changed
+
+
+def _cap_parallel_tool_calls_sse_line(raw_line: str) -> str:
+    """Drop tool_call deltas whose index >= 1 from one streamed OpenAI SSE
+    ``data:`` line so only the first tool call survives (parallel_tool_calls=false,
+    best-effort). Non-tool / unparseable payloads are returned byte-for-byte."""
+    payload = raw_line[len("data: ") :]
+    if payload.strip() in ("", "[DONE]"):
+        return raw_line
+    try:
+        obj = json.loads(payload)
+    except Exception:
+        return raw_line
+    if not _drop_parallel_tool_call_deltas(obj):
+        return raw_line
+    return "data: " + json.dumps(obj, separators = (",", ":"))
+
+
+def _prompt_tokens_details(upstream):
+    """Surface llama-server's real ``cached_tokens`` (KV-cache prompt hits) while
+    keeping the full OpenAI ``prompt_tokens_details`` shape. Defaults to zero when
+    the upstream usage doesn't carry it, so the field is always present."""
+    out = {"cached_tokens": 0, "audio_tokens": 0}
+    if isinstance(upstream, dict):
+        out.update({k: v for k, v in upstream.items() if v is not None})
+    return out
+
+
+def _wants_stream_usage(payload) -> bool:
+    return bool((payload.stream_options or {}).get("include_usage"))
+
+
+def _openai_stream_usage_chunk(
+    payload, completion_id, created, model_name, stream_usage, stream_timings
+):
+    """Build the final OpenAI-standard usage chunk (choices=[], usage populated)
+    for a chat stream. Returns the SSE ``data:`` line, or None when the client
+    did not opt in via ``stream_options.include_usage`` (or no usage exists)."""
+    if not _wants_stream_usage(payload):
+        return None
+    if not (stream_usage or stream_timings):
+        return None
+    _usage = stream_usage or {}
+    _prompt_tokens = _usage.get("prompt_tokens") or 0
+    _completion_tokens = _usage.get("completion_tokens") or 0
+    _total_tokens = _usage.get("total_tokens") or (_prompt_tokens + _completion_tokens)
+    usage_chunk = ChatCompletionChunk(
+        id = completion_id,
+        created = created,
+        model = model_name,
+        choices = [],
+        usage = CompletionUsage(
+            prompt_tokens = _prompt_tokens,
+            completion_tokens = _completion_tokens,
+            total_tokens = _total_tokens,
+            prompt_tokens_details = _prompt_tokens_details(_usage.get("prompt_tokens_details")),
+        ),
+        timings = stream_timings,
+    )
+    return f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
+
+
+def _rewrite_cmpl_id(raw: bytes) -> bytes:
+    """Rewrite llama-server's chat-style ``chatcmpl-`` ids to the ``cmpl-``
+    prefix OpenAI's legacy /v1/completions use. Anchored on the ``"id":`` key
+    (both spacing variants) so the rest of the body stays byte-exact."""
+    return raw.replace(b'"id":"chatcmpl-', b'"id":"cmpl-').replace(
+        b'"id": "chatcmpl-', b'"id": "cmpl-'
+    )
+
+
+def _cmpl_stream_event_out(event: bytes, include_usage: bool) -> Optional[bytes]:
+    """Process one legacy /v1/completions SSE event (text between blank-line
+    separators).
+
+    Always rewrites the ``chatcmpl-`` -> ``cmpl-`` id prefix. When the client
+    did NOT request ``stream_options.include_usage``, also removes the usage
+    statistics so the stream matches OpenAI's contract.
+
+    Shape note: on /v1/completions, llama-server attaches ``usage`` to the
+    FINAL content chunk (the ``finish_reason`` chunk, which has a populated
+    ``choices`` array) -- unlike the chat stream, which emits a standalone
+    ``choices: []`` usage chunk. Both shapes are handled: a standalone
+    usage-only chunk is dropped; an inline ``usage`` field is stripped from a
+    content chunk while keeping ``choices``/``finish_reason`` intact.
+
+    Returns the event bytes to emit, or ``None`` to drop the event. Only a
+    usage-bearing event is re-serialized; every other event keeps exact bytes.
+    """
+    if include_usage:
+        return _rewrite_cmpl_id(event)
+    lines = event.split(b"\n")
+    changed = False
+    for i, ln in enumerate(lines):
+        if not ln.startswith(b"data:"):
+            continue
+        payload = ln[len(b"data:") :].strip()
+        if not payload or payload == b"[DONE]":
+            continue
+        try:
+            obj = json.loads(payload)
+        except Exception:
+            continue
+        if not isinstance(obj, dict) or obj.get("usage") is None:
+            continue
+        # Standalone usage-only chunk (chat-style) -> drop the whole event.
+        if obj.get("choices") == []:
+            return None
+        # Usage on a content/finish chunk (completions-style) -> strip it.
+        obj.pop("usage", None)
+        lines[i] = b"data: " + json.dumps(obj, separators = (",", ":")).encode("utf-8")
+        changed = True
+    return _rewrite_cmpl_id(b"\n".join(lines) if changed else event)
+
+
+def _classify_llama_generation_error(exc: Exception) -> Optional[bool]:
+    """Classify an error raised while consuming the GGUF generator.
+
+    Returns True for a context-window overflow, False for any other upstream
+    4xx (a client error), or None when it should stay a 500. Distinguishes a
+    real client error from a genuine crash by the explicit "llama-server
+    returned 4xx" marker, not a bare "tokens"/"exceed" substring.
+    """
+    msg = str(exc)
+    msg_l = msg.lower()
+    if "n_ctx" in msg_l or (
+        "context" in msg_l and any(t in msg_l for t in ("exceed", "length", "window", "too long"))
+    ):
+        return True
+    if _re.search(r"llama-server returned (4\d\d)", msg):
+        return False
+    return None
+
+
+# Add backend directory to path
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
@@ -214,6 +483,9 @@ from core.inference.anthropic_compat import (
     anthropic_messages_to_openai,
     anthropic_tools_to_openai,
     anthropic_tool_choice_to_openai,
+    openai_finish_to_anthropic_stop,
+    anthropic_tool_use_id,
+    build_anthropic_sse_event,
     AnthropicStreamEmitter,
     AnthropicPassthroughEmitter,
 )
@@ -1672,7 +1944,7 @@ async def generate_audio(
             top_p = payload.top_p,
             top_k = payload.top_k,
             min_p = payload.min_p,
-            max_new_tokens = payload.max_tokens or 2048,
+            max_new_tokens = _effective_max_tokens(payload) or 2048,
             repetition_penalty = payload.repetition_penalty,
         )
     else:
@@ -1689,7 +1961,7 @@ async def generate_audio(
             top_p = payload.top_p,
             top_k = payload.top_k,
             min_p = payload.min_p,
-            max_new_tokens = payload.max_tokens or 2048,
+            max_new_tokens = _effective_max_tokens(payload) or 2048,
             repetition_penalty = payload.repetition_penalty,
             use_adapter = payload.use_adapter,
         )
@@ -1773,7 +2045,7 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
         chat_messages:  Non-system messages with content flattened to strings.
         image_base64:   Base64 of the *first* image found, or ``None``.
     """
-    system_prompt = ""
+    system_parts: list[str] = []
     chat_messages: list[dict] = []
     first_image_b64: Optional[str] = None
 
@@ -1781,10 +2053,10 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
         # ── System messages → extract as system_prompt ────────
         if msg.role == "system":
             if isinstance(msg.content, str):
-                system_prompt = msg.content
+                system_parts.append(msg.content)
             elif isinstance(msg.content, list):
                 # Unlikely but handle: join text parts
-                system_prompt = "\n".join(p.text for p in msg.content if p.type == "text")
+                system_parts.append("\n".join(p.text for p in msg.content if p.type == "text"))
             continue
 
         # ── User / assistant messages ─────────────────────────
@@ -1807,7 +2079,7 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
             combined_text = "\n".join(text_parts) if text_parts else ""
             chat_messages.append({"role": msg.role, "content": combined_text})
 
-    return system_prompt, chat_messages, first_image_b64
+    return "\n\n".join(p for p in system_parts if p), chat_messages, first_image_b64
 
 
 # ── External provider proxy ──────────────────────────────────────
@@ -2227,7 +2499,10 @@ async def _proxy_to_external_provider(
             model = model,
             temperature = payload.temperature,
             top_p = payload.top_p,
-            max_tokens = payload.max_tokens,
+            # Honor max_completion_tokens when max_tokens is absent, so a
+            # provider-routed request capped only by the newer field still gets
+            # a limit instead of falling back to the provider default.
+            max_tokens = _effective_max_tokens(payload),
             presence_penalty = payload.presence_penalty,
             top_k = _top_k_explicit,
             enable_thinking = payload.enable_thinking,
@@ -2469,11 +2744,56 @@ async def openai_chat_completions(
     - GGUF models → llama-server via LlamaCppBackend
     - Other models → Unsloth/transformers via InferenceBackend
     """
+    # OpenAI's newer "developer" role is equivalent to "system". Normalize it
+    # before provider routing so external providers (which may not accept the
+    # "developer" role) get "system" too, matching the local path.
+    for _m in payload.messages:
+        if _m.role == "developer":
+            _m.role = "system"
+
+    if payload.logprobs:
+        _raise_unsupported_openai_parameter(
+            "logprobs", "logprobs is not supported for chat completions."
+        )
+    if payload.top_logprobs is not None:
+        _raise_unsupported_openai_parameter(
+            "top_logprobs", "top_logprobs is not supported for chat completions."
+        )
+
     # ── External provider routing ────────────────────────────────
     # encrypted_api_key is optional -- local providers (llama.cpp / vLLM / Ollama) may run without auth.
     if payload.provider_id or payload.provider_type:
+        if _wants_multiple_choices(payload):
+            _raise_unsupported_n("external provider chat completions")
         return await _proxy_to_external_provider(payload, request)
 
+    # Reject a malformed function tool here: it would otherwise reach
+    # llama-server and surface as an opaque 500 "Failed to parse tools".
+    if payload.tools:
+        for _tool in payload.tools:
+            if not isinstance(_tool, dict):
+                continue
+            # llama-server 500s ("Failed to parse tools: Missing tool type") when
+            # a function tool omits "type". Default it to "function" so a
+            # well-formed tool isn't rejected over a missing discriminator (and a
+            # malformed one still surfaces as a clean 400 below, not a 500).
+            if _tool.get("type") is None and isinstance(_tool.get("function"), dict):
+                _tool["type"] = "function"
+            if _tool.get("type") != "function":
+                continue
+            _fn = _tool.get("function")
+            _name = _fn.get("name") if isinstance(_fn, dict) else None
+            if not isinstance(_name, str) or not _name.strip():
+                raise HTTPException(
+                    status_code = 400,
+                    detail = openai_error_body(
+                        "Invalid 'tools': each tool must have a 'function' with a 'name'.",
+                        status = 400,
+                        code = "invalid_value",
+                        param = "tools",
+                    ),
+                )
+
     llama_backend = get_llama_cpp_backend()
     using_gguf = llama_backend.is_loaded
 
@@ -2492,9 +2812,13 @@ async def openai_chat_completions(
             payload.enable_thinking = bool(_tpl_kw["enable_thinking"])
 
     # ── Determine which backend is active ─────────────────────
+    # Single-model server: any model name serves the loaded model (drop-in
+    # OpenAI compat), so payload.model is only a fallback label here.
     if using_gguf:
         model_name = llama_backend.model_identifier or payload.model
         if getattr(llama_backend, "_is_audio", False):
+            if _wants_multiple_choices(payload):
+                _raise_unsupported_n("GGUF audio chat completions")
             return await generate_audio(payload, request)
     else:
         backend = get_inference_backend()
@@ -2504,6 +2828,8 @@ async def openai_chat_completions(
                 detail = "No model loaded. Call POST /inference/load first.",
             )
         model_name = backend.active_model_name or payload.model
+        if _wants_multiple_choices(payload):
+            _raise_unsupported_n("non-GGUF chat completions")
 
         # ── Audio TTS path: auto-route to audio generation ────
         # (Whisper is ASR not TTS -- handled below in audio input path)
@@ -2540,7 +2866,7 @@ async def openai_chat_completions(
                     top_p = payload.top_p,
                     top_k = payload.top_k,
                     min_p = payload.min_p,
-                    max_new_tokens = payload.max_tokens or 2048,
+                    max_new_tokens = _effective_max_tokens(payload) or 2048,
                     repetition_penalty = payload.repetition_penalty,
                     cancel_event = cancel_event,
                 )
@@ -2634,11 +2960,16 @@ async def openai_chat_completions(
     # ── Standard OpenAI function-calling pass-through (GGUF only) ────
     # When a client (opencode / Claude Code via OpenAI compat / Cursor /
     # Continue / ...) sends standard OpenAI `tools` without Studio's
-    # `enable_tools` shorthand, forward to llama-server verbatim so structured
-    # `tool_calls` flow back. Runs BEFORE `_extract_content_parts` because that
-    # helper is unaware of `role="tool"` messages and assistant messages that
-    # only carry `tool_calls` (content=None) -- both valid in multi-turn
-    # client-side tool loops.
+    # `enable_tools` shorthand, forward the request to llama-server
+    # verbatim so structured `tool_calls` flow back to the client. This
+    # branch runs BEFORE `_extract_content_parts` because that helper is
+    # unaware of `role="tool"` messages and assistant messages that only
+    # carry `tool_calls` (content=None) — both of which are valid in
+    # multi-turn client-side tool loops.
+    effective_max_tokens = _effective_max_tokens(payload)
+
+    normalized_stop = _normalize_stop_sequences(payload.stop)
+
     _has_tool_messages = any(m.role == "tool" or m.tool_calls for m in payload.messages)
     # Route guided-decoding requests through the verbatim passthrough so
     # ``response_format`` (JSON schema) reaches llama-server and the model's
@@ -2656,6 +2987,8 @@ async def openai_chat_completions(
         and not _effective_enable_tools(payload)
         and (_tools_passthrough or _has_response_format)
     ):
+        if _wants_multiple_choices(payload):
+            _raise_unsupported_n("GGUF tool or response_format passthrough")
         if payload.audio_base64:
             raise HTTPException(
                 status_code = 400,
@@ -2766,6 +3099,8 @@ async def openai_chat_completions(
                 use_tools = False
 
         if use_tools:
+            if _wants_multiple_choices(payload):
+                _raise_unsupported_n("GGUF tool chat completions")
             # ── Tool-use system prompt nudge ──────────────────────
             _nudge = _build_tool_action_nudge(
                 tools = tools_to_use,
@@ -2800,10 +3135,12 @@ async def openai_chat_completions(
                     top_p = payload.top_p,
                     top_k = payload.top_k,
                     min_p = payload.min_p,
-                    max_tokens = payload.max_tokens,
+                    max_tokens = effective_max_tokens,
                     repetition_penalty = payload.repetition_penalty,
                     presence_penalty = payload.presence_penalty,
+                    stop = normalized_stop,
                     cancel_event = cancel_event,
+                    seed = payload.seed,
                     enable_thinking = payload.enable_thinking,
                     reasoning_effort = payload.reasoning_effort,
                     preserve_thinking = payload.preserve_thinking,
@@ -2815,6 +3152,7 @@ async def openai_chat_completions(
                     if payload.tool_call_timeout is not None
                     else 300,
                     session_id = payload.session_id,
+                    disable_parallel_tool_use = payload.parallel_tool_calls is False,
                 )
 
             _tool_sentinel = object()
@@ -2844,6 +3182,7 @@ async def openai_chat_completions(
                     prev_text = ""
                     _stream_usage = None
                     _stream_timings = None
+                    _stream_finish = None
                     while True:
                         if cancel_event.is_set():
                             break
@@ -2882,6 +3221,7 @@ async def openai_chat_completions(
                         if event["type"] == "metadata":
                             _stream_usage = event.get("usage")
                             _stream_timings = event.get("timings")
+                            _stream_finish = event.get("finish_reason")
                             continue
 
                         # "content" type -- cumulative text. Sanitize the full
@@ -2916,27 +3256,21 @@ async def openai_chat_completions(
                         choices = [
                             ChunkChoice(
                                 delta = ChoiceDelta(),
-                                finish_reason = "stop",
+                                finish_reason = _clamp_finish_reason(_stream_finish),
                             )
                         ],
                     )
                     yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
-                    # Usage chunk (OpenAI standard: choices=[], usage populated)
-                    if _stream_usage or _stream_timings:
-                        usage_obj = CompletionUsage(
-                            prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
-                            completion_tokens = (_stream_usage or {}).get("completion_tokens", 0),
-                            total_tokens = (_stream_usage or {}).get("total_tokens", 0),
-                        )
-                        usage_chunk = ChatCompletionChunk(
-                            id = completion_id,
-                            created = created,
-                            model = model_name,
-                            choices = [],
-                            usage = usage_obj,
-                            timings = _stream_timings,
-                        )
-                        yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
+                    usage_line = _openai_stream_usage_chunk(
+                        payload,
+                        completion_id,
+                        created,
+                        model_name,
+                        _stream_usage,
+                        _stream_timings,
+                    )
+                    if usage_line is not None:
+                        yield usage_line
                     yield "data: [DONE]\n\n"
 
                 except asyncio.CancelledError:
@@ -2947,12 +3281,7 @@ async def openai_chat_completions(
 
                     tb = traceback.format_exc()
                     logger.error(f"Error during GGUF tool streaming: {e}\n{tb}")
-                    error_chunk = {
-                        "error": {
-                            "message": _friendly_error(e),
-                            "type": "server_error",
-                        },
-                    }
+                    error_chunk = _openai_stream_error_chunk(e)
                     yield f"data: {json.dumps(error_chunk)}\n\n"
                 finally:
                     _tracker.__exit__(None, None, None)
@@ -2969,7 +3298,10 @@ async def openai_chat_completions(
 
         # ── Standard GGUF path (no tools) ─────────────────────
 
-        def gguf_generate():
+        def gguf_generate(choice_index: int = 0):
+            _seed = payload.seed
+            if _seed is not None and _seed >= 0 and choice_index:
+                _seed += choice_index
             return llama_backend.generate_chat_completion(
                 messages = gguf_messages,
                 image_b64 = image_b64,
@@ -2977,18 +3309,22 @@ async def openai_chat_completions(
                 top_p = payload.top_p,
                 top_k = payload.top_k,
                 min_p = payload.min_p,
-                max_tokens = payload.max_tokens,
+                max_tokens = effective_max_tokens,
                 repetition_penalty = payload.repetition_penalty,
                 presence_penalty = payload.presence_penalty,
+                stop = normalized_stop,
                 cancel_event = cancel_event,
                 enable_thinking = payload.enable_thinking,
                 reasoning_effort = payload.reasoning_effort,
                 preserve_thinking = payload.preserve_thinking,
+                seed = _seed,
             )
 
         _gguf_sentinel = object()
 
         if payload.stream:
+            if _wants_multiple_choices(payload):
+                _raise_unsupported_n("streaming GGUF chat completions")
             _cancel_keys = (payload.cancel_id, payload.session_id, completion_id)
             _tracker = _TrackedCancel(cancel_event, *_cancel_keys)
             _tracker.__enter__()
@@ -3015,6 +3351,7 @@ async def openai_chat_completions(
                     prev_text = ""
                     _stream_usage = None
                     _stream_timings = None
+                    _stream_finish = None
                     while True:
                         if cancel_event.is_set():
                             break
@@ -3029,6 +3366,7 @@ async def openai_chat_completions(
                             if cumulative.get("type") == "metadata":
                                 _stream_usage = cumulative.get("usage")
                                 _stream_timings = cumulative.get("timings")
+                                _stream_finish = cumulative.get("finish_reason")
                             else:
                                 logger.warning(
                                     "gguf_stream_chunks: unexpected dict event: %s",
@@ -3060,27 +3398,21 @@ async def openai_chat_completions(
                         choices = [
                             ChunkChoice(
                                 delta = ChoiceDelta(),
-                                finish_reason = "stop",
+                                finish_reason = _clamp_finish_reason(_stream_finish),
                             )
                         ],
                     )
                     yield f"data: {final_chunk.model_dump_json(exclude_none = True)}\n\n"
-                    # Usage chunk (OpenAI standard: choices=[], usage populated)
-                    if _stream_usage or _stream_timings:
-                        usage_obj = CompletionUsage(
-                            prompt_tokens = (_stream_usage or {}).get("prompt_tokens", 0),
-                            completion_tokens = (_stream_usage or {}).get("completion_tokens", 0),
-                            total_tokens = (_stream_usage or {}).get("total_tokens", 0),
-                        )
-                        usage_chunk = ChatCompletionChunk(
-                            id = completion_id,
-                            created = created,
-                            model = model_name,
-                            choices = [],
-                            usage = usage_obj,
-                            timings = _stream_timings,
-                        )
-                        yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
+                    usage_line = _openai_stream_usage_chunk(
+                        payload,
+                        completion_id,
+                        created,
+                        model_name,
+                        _stream_usage,
+                        _stream_timings,
+                    )
+                    if usage_line is not None:
+                        yield usage_line
                     yield "data: [DONE]\n\n"
 
                 except asyncio.CancelledError:
@@ -3088,12 +3420,7 @@ async def openai_chat_completions(
                     raise
                 except Exception as e:
                     logger.error(f"Error during GGUF streaming: {e}", exc_info = True)
-                    error_chunk = {
-                        "error": {
-                            "message": _friendly_error(e),
-                            "type": "server_error",
-                        },
-                    }
+                    error_chunk = _openai_stream_error_chunk(e)
                     yield f"data: {json.dumps(error_chunk)}\n\n"
                 finally:
                     _tracker.__exit__(None, None, None)
@@ -3109,35 +3436,74 @@ async def openai_chat_completions(
             )
         else:
             try:
-                full_text = ""
-                completion_usage = None
-                for token in gguf_generate():
-                    if isinstance(token, dict):
-                        if token.get("type") == "metadata":
-                            completion_usage = token.get("usage")
-                        continue
-                    full_text = token
+                # ``n`` requests several independent completions; the single
+                # decode slot yields one at a time, so loop sequentially.
+                _n = payload.n or 1
+
+                _choices = []
+                _prompt_tokens = 0
+                _sum_completion = 0
+                _prompt_details = None
+                for _idx in range(_n):
+                    # Stop spawning the remaining choices once cancelled.
+                    if cancel_event.is_set():
+                        break
+                    full_text = ""
+                    completion_usage = None
+                    completion_finish = None
+                    for token in gguf_generate(_idx):
+                        if isinstance(token, dict):
+                            if token.get("type") == "metadata":
+                                completion_usage = token.get("usage")
+                                completion_finish = token.get("finish_reason")
+                            continue
+                        full_text = token
+
+                    _choices.append(
+                        CompletionChoice(
+                            index = _idx,
+                            message = CompletionMessage(content = full_text),
+                            finish_reason = _clamp_finish_reason(completion_finish),
+                        )
+                    )
+                    if completion_usage:
+                        # The prompt is shared across all n choices, so count its
+                        # tokens ONCE (OpenAI bills only generated tokens for each
+                        # extra choice). Only completion_tokens accumulates.
+                        _prompt_tokens = completion_usage.get("prompt_tokens") or _prompt_tokens
+                        _sum_completion += completion_usage.get("completion_tokens") or 0
+                        if _prompt_details is None:
+                            _prompt_details = completion_usage.get("prompt_tokens_details")
 
                 response = ChatCompletion(
                     id = completion_id,
                     created = created,
                     model = model_name,
-                    choices = [
-                        CompletionChoice(
-                            message = CompletionMessage(content = full_text),
-                            finish_reason = "stop",
-                        )
-                    ],
+                    choices = _choices,
                     usage = CompletionUsage(
-                        prompt_tokens = (completion_usage or {}).get("prompt_tokens") or 0,
-                        completion_tokens = (completion_usage or {}).get("completion_tokens") or 0,
-                        total_tokens = (completion_usage or {}).get("total_tokens") or 0,
+                        prompt_tokens = _prompt_tokens,
+                        completion_tokens = _sum_completion,
+                        total_tokens = _prompt_tokens + _sum_completion,
+                        prompt_tokens_details = _prompt_tokens_details(_prompt_details),
                     ),
                 )
                 return JSONResponse(content = response.model_dump())
 
             except Exception as e:
                 logger.error(f"Error during GGUF completion: {e}", exc_info = True)
+                # An over-context prompt makes llama-server return 400; map any
+                # upstream 4xx to a 400 client error rather than leaking a 500.
+                _cls = _classify_llama_generation_error(e)
+                if _cls is not None:
+                    raise HTTPException(
+                        status_code = 400,
+                        detail = openai_error_body(
+                            _friendly_error(e),
+                            status = 400,
+                            code = "context_length_exceeded" if _cls else None,
+                            param = "messages",
+                        ),
+                    )
                 raise HTTPException(status_code = 500, detail = safe_error_detail(e))
 
     # ── Standard Unsloth path ─────────────────────────────────
@@ -3279,7 +3645,7 @@ async def openai_chat_completions(
                 top_p = payload.top_p,
                 top_k = payload.top_k,
                 min_p = payload.min_p,
-                max_tokens = payload.max_tokens,
+                max_tokens = effective_max_tokens,
                 repetition_penalty = payload.repetition_penalty,
                 cancel_event = cancel_event,
                 enable_thinking = payload.enable_thinking,
@@ -3388,20 +3754,16 @@ async def openai_chat_completions(
                 # concurrent streams cannot read each other's stats.
                 _stats = _sf_stats_holder.get("stats")
                 if _stats:
-                    _stream_usage = _stats.get("usage") or {}
-                    usage_chunk = ChatCompletionChunk(
-                        id = completion_id,
-                        created = created,
-                        model = model_name,
-                        choices = [],
-                        usage = CompletionUsage(
-                            prompt_tokens = _stream_usage.get("prompt_tokens", 0),
-                            completion_tokens = _stream_usage.get("completion_tokens", 0),
-                            total_tokens = _stream_usage.get("total_tokens", 0),
-                        ),
-                        timings = _stats.get("timings"),
+                    usage_line = _openai_stream_usage_chunk(
+                        payload,
+                        completion_id,
+                        created,
+                        model_name,
+                        _stats.get("usage"),
+                        _stats.get("timings"),
                     )
-                    yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
+                    if usage_line is not None:
+                        yield usage_line
                 yield "data: [DONE]\n\n"
 
             except asyncio.CancelledError:
@@ -3483,7 +3845,7 @@ async def openai_chat_completions(
         top_p = payload.top_p,
         top_k = payload.top_k,
         min_p = payload.min_p,
-        max_new_tokens = payload.max_tokens or 2048,
+        max_new_tokens = effective_max_tokens or 2048,
         repetition_penalty = payload.repetition_penalty,
     )
     # Forward reasoning kwargs; the worker/template wrapper peels off any the
@@ -3596,20 +3958,16 @@ async def openai_chat_completions(
                 # read each other's stats.
                 _stats = stats_holder.get("stats")
                 if _stats:
-                    _stream_usage = _stats.get("usage") or {}
-                    usage_chunk = ChatCompletionChunk(
-                        id = completion_id,
-                        created = created,
-                        model = model_name,
-                        choices = [],
-                        usage = CompletionUsage(
-                            prompt_tokens = _stream_usage.get("prompt_tokens", 0),
-                            completion_tokens = _stream_usage.get("completion_tokens", 0),
-                            total_tokens = _stream_usage.get("total_tokens", 0),
-                        ),
-                        timings = _stats.get("timings"),
+                    usage_line = _openai_stream_usage_chunk(
+                        payload,
+                        completion_id,
+                        created,
+                        model_name,
+                        _stats.get("usage"),
+                        _stats.get("timings"),
                     )
-                    yield f"data: {usage_chunk.model_dump_json(exclude_none = True)}\n\n"
+                    if usage_line is not None:
+                        yield usage_line
                 yield "data: [DONE]\n\n"
 
             except asyncio.CancelledError:
@@ -3757,15 +4115,14 @@ async def serve_sandbox_file(
 # =====================================================================
 
 
-@router.get("/models")
-async def openai_list_models(current_subject: str = Depends(get_current_subject)):
-    """
-    OpenAI-compatible model listing endpoint.
+def _openai_model_objects() -> list[dict]:
+    """The model objects GET /v1/models exposes (one per loaded local backend).
 
-    Returns the currently loaded model in the format expected by
-    OpenAI-compatible clients (``GET /v1/models``).
+    Shared by the LIST and RETRIEVE handlers so both report the same ids and
+    field shape.
     """
-    models = []
+    models: list[dict] = []
+    _created = int(time.time())
 
     # Check GGUF backend
     llama_backend = get_llama_cpp_backend()
@@ -3774,6 +4131,7 @@ async def openai_list_models(current_subject: str = Depends(get_current_subject)
             {
                 "id": llama_backend.model_identifier,
                 "object": "model",
+                "created": _created,
                 "owned_by": "local",
             }
         )
@@ -3785,11 +4143,46 @@ async def openai_list_models(current_subject: str = Depends(get_current_subject)
             {
                 "id": backend.active_model_name,
                 "object": "model",
+                "created": _created,
                 "owned_by": "local",
             }
         )
 
-    return {"object": "list", "data": models}
+    return models
+
+
+@router.get("/models")
+async def openai_list_models(current_subject: str = Depends(get_current_subject)):
+    """
+    OpenAI-compatible model listing endpoint.
+
+    Returns the currently loaded model in the format expected by
+    OpenAI-compatible clients (``GET /v1/models``).
+    """
+    return {"object": "list", "data": _openai_model_objects()}
+
+
+@router.get("/models/{model_id:path}")
+async def openai_retrieve_model(model_id: str, current_subject: str = Depends(get_current_subject)):
+    """
+    OpenAI-compatible single-model retrieval endpoint (``GET /v1/models/{id}``).
+
+    Returns the bare model object when ``model_id`` matches a loaded local
+    model, or 404 model_not_found otherwise. Defined after the LIST route so
+    it does not shadow it; ``{model_id:path}`` keeps ids with slashes intact.
+    """
+    for model in _openai_model_objects():
+        if model["id"] == model_id:
+            return model
+    raise HTTPException(
+        status_code = 404,
+        detail = openai_error_body(
+            f"The model '{model_id}' does not exist",
+            status = 404,
+            code = "model_not_found",
+            param = "id",
+        ),
+    )
 
 
 # =====================================================================
@@ -3819,14 +4212,17 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
     if is_stream:
 
         async def _stream():
-            # Manual httpx client/response lifecycle AND explicit aiter_bytes()
-            # iterator close -- see _anthropic_passthrough_stream for the full
-            # rationale. Saving `bytes_iter = resp.aiter_bytes()` and `await
-            # bytes_iter.aclose()` in finally is what avoids the Python 3.13 +
-            # httpcore 1.0.x "Exception ignored in: <async_generator>" / anyio
-            # cancel-scope trace: an anonymous async for leaves the iterator
-            # unclosed, so the asyncgen GC finalizer runs cleanup later in a
-            # different asyncio task.
+            # Manual httpx client/response lifecycle AND explicit iterator
+            # close — see _anthropic_passthrough_stream for the full rationale.
+            # Saving the iterator and closing it in the finally block avoids the
+            # Python 3.13 + httpcore 1.0.x "Exception ignored in:
+            # <async_generator>" / anyio cancel-scope trace.
+            #
+            # Buffer the relay into whole SSE events (split on the blank-line
+            # separator) so _cmpl_stream_event_out can rewrite the cmpl- id and
+            # honor stream_options.include_usage per event, while keeping SSE
+            # framing and token bytes intact.
+            _include_usage = bool((body.get("stream_options") or {}).get("include_usage"))
             client = httpx.AsyncClient(timeout = 600)
             resp = None
             bytes_iter = None
@@ -3834,8 +4230,21 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
                 req = client.build_request("POST", target_url, json = body)
                 resp = await client.send(req, stream = True)
                 bytes_iter = resp.aiter_bytes()
+                buffer = b""
                 async for chunk in bytes_iter:
-                    yield chunk
+                    buffer += chunk
+                    while b"\n\n" in buffer:
+                        event, buffer = buffer.split(b"\n\n", 1)
+                        out = _cmpl_stream_event_out(event, _include_usage)
+                        if out is not None:
+                            yield out + b"\n\n"
+                if buffer:
+                    out = _cmpl_stream_event_out(buffer, _include_usage)
+                    if out is not None:
+                        # Re-add the SSE separator the split consumed, so a final
+                        # event arriving without a trailing blank line is still
+                        # terminated for the client's parser.
+                        yield out + b"\n\n"
             except Exception as e:
                 logger.error("openai_completions stream error: %s", e)
             finally:
@@ -3858,8 +4267,12 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
     else:
         async with httpx.AsyncClient() as client:
             resp = await client.post(target_url, json = body, timeout = 600)
+
+        if resp.status_code != 200:
+            raise _openai_passthrough_error(resp.status_code, resp.text)
+
         return Response(
-            content = resp.content,
+            content = _rewrite_cmpl_id(resp.content),
             status_code = resp.status_code,
             media_type = "application/json",
         )
@@ -4139,14 +4552,10 @@ def _build_chat_request(
     chat_tool_choice = _translate_responses_tool_choice_to_chat(payload.tool_choice)
     if chat_tool_choice is not None:
         chat_kwargs["tool_choice"] = chat_tool_choice
+    if payload.parallel_tool_calls is not None:
+        chat_kwargs["parallel_tool_calls"] = payload.parallel_tool_calls
 
-    req = ChatCompletionRequest(**chat_kwargs)
-    # `parallel_tool_calls` isn't a first-class field on ChatCompletionRequest,
-    # but the model allows extras and _build_openai_passthrough_body forwards
-    # only known fields. Llama-server doesn't implement parallel_tool_calls
-    # semantics, so accept-and-ignore it on the Responses side to avoid breaking
-    # SDK clients that always send it.
-    return req
+    return ChatCompletionRequest(**chat_kwargs)
 
 
 def _chat_tool_calls_to_responses_output(tool_calls: list[dict]) -> list[dict]:
@@ -4295,6 +4704,7 @@ async def _responses_stream(
         )
 
     body = _build_openai_passthrough_body(chat_req, backend_ctx = llama_backend.context_length)
+    body["stream_options"] = {"include_usage": True}
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
 
     async def event_generator():
@@ -4399,6 +4809,8 @@ async def _responses_stream(
                     chunk_data = json.loads(data_str)
                 except json.JSONDecodeError:
                     continue
+                if payload.parallel_tool_calls is False:
+                    _drop_parallel_tool_call_deltas(chunk_data)
 
                 choices = chunk_data.get("choices", [])
                 if not choices:
@@ -4720,6 +5132,56 @@ def _normalize_anthropic_openai_images(openai_messages: list[dict], is_vision: b
     return has_image
 
 
+@router.post("/messages/count_tokens")
+async def anthropic_count_tokens(
+    payload: AnthropicMessagesRequest,
+    request: Request,
+    current_subject: str = Depends(get_current_subject),
+):
+    """Anthropic-compatible token-counting endpoint (POST /v1/messages/count_tokens).
+
+    Translates the Anthropic request to OpenAI form (the same translation the
+    /messages handler uses), counts prompt tokens with the loaded GGUF model's
+    tokenizer, and returns ``{"input_tokens": int}`` only. Unlike /messages,
+    max_tokens is NOT required here.
+    """
+    llama_backend = get_llama_cpp_backend()
+    if not llama_backend.is_loaded:
+        raise HTTPException(
+            status_code = 503,
+            detail = "No GGUF model loaded. Load a GGUF model first.",
+        )
+
+    # Same Anthropic → OpenAI translation as anthropic_messages: system is
+    # folded into the messages list, so pass system=None to the counter.
+    openai_messages = anthropic_messages_to_openai(
+        [m.model_dump() for m in payload.messages],
+        payload.system,
+    )
+    # Apply the same sanitization /messages does before generation, so the count
+    # matches the prompt the real request would build (otherwise empty-assistant
+    # sentinels / synthetic tool history inflate the count or hit the fallback).
+    openai_messages = _strip_provider_synthetic_tool_history(
+        _drop_empty_assistant_sentinels(openai_messages)
+    )
+    openai_tools = anthropic_tools_to_openai(payload.tools or []) or None
+
+    try:
+        count = await asyncio.to_thread(
+            llama_backend.count_chat_tokens,
+            openai_messages,
+            None,
+            openai_tools,
+            strict = True,
+        )
+    except Exception:
+        raise HTTPException(
+            status_code = 503,
+            detail = "Unable to count tokens with the loaded model tokenizer.",
+        )
+    return JSONResponse(content = {"input_tokens": int(count)})
+
+
 def _set_or_prepend_system_message(
     messages: Optional[list[dict]], system_prompt: str
 ) -> list[dict]:
@@ -4755,6 +5217,18 @@ async def anthropic_messages(
             detail = "No GGUF model loaded. Load a GGUF model first.",
         )
 
+    # max_tokens is a required field on the Anthropic Messages API; real
+    # Anthropic returns a 400 invalid_request_error when it is omitted.
+    if payload.max_tokens is None:
+        raise HTTPException(
+            status_code = 400,
+            detail = anthropic_error_body(
+                "max_tokens: field required",
+                status = 400,
+                err_type = "invalid_request_error",
+            ),
+        )
+
     model_name = getattr(llama_backend, "model_identifier", None) or payload.model
     message_id = f"msg_{uuid.uuid4().hex[:24]}"
 
@@ -4866,6 +5340,14 @@ async def anthropic_messages(
         not server_tools and len(openai_client_tools) > 0 and llama_backend.supports_tools
     )
 
+    # Anthropic tool_choice.disable_parallel_tool_use caps the response to a
+    # single tool_use block. Computed here so BOTH the client-tool passthrough
+    # and the server-tool path honor it.
+    _disable_parallel = bool(
+        isinstance(payload.tool_choice, dict)
+        and payload.tool_choice.get("disable_parallel_tool_use")
+    )
+
     # ── Client-side pass-through path ─────────────────────────
     if client_tools:
         openai_tools = openai_client_tools
@@ -4890,6 +5372,7 @@ async def anthropic_messages(
                 tool_choice = openai_tool_choice,
                 session_id = payload.session_id,
                 cancel_id = payload.cancel_id,
+                disable_parallel_tool_use = _disable_parallel,
             )
         return await _anthropic_passthrough_non_streaming(
             llama_backend,
@@ -4906,6 +5389,7 @@ async def anthropic_messages(
             repetition_penalty = repetition_penalty,
             presence_penalty = presence_penalty,
             tool_choice = openai_tool_choice,
+            disable_parallel_tool_use = _disable_parallel,
         )
 
     if server_tools:
@@ -4954,6 +5438,7 @@ async def anthropic_messages(
                 auto_heal_tool_calls = True,
                 tool_call_timeout = 300,
                 session_id = payload.session_id,
+                disable_parallel_tool_use = _disable_parallel,
             )
 
         if payload.stream:
@@ -4963,11 +5448,16 @@ async def anthropic_messages(
                 _run_tool_gen,
                 message_id,
                 model_name,
+                llama_backend = llama_backend,
+                openai_messages = openai_messages,
+                openai_tools = openai_tools,
+                disable_parallel_tool_use = _disable_parallel,
             )
         return await _anthropic_tool_non_streaming(
             _run_tool_gen,
             message_id,
             model_name,
+            disable_parallel_tool_use = _disable_parallel,
         )
 
     # ── No-tool path ──────────────────────────────────────────
@@ -4992,6 +5482,8 @@ async def anthropic_messages(
             _run_plain_gen,
             message_id,
             model_name,
+            llama_backend = llama_backend,
+            openai_messages = openai_messages,
         )
     return await _anthropic_plain_non_streaming(
         _run_plain_gen,
@@ -5000,15 +5492,44 @@ async def anthropic_messages(
     )
 
 
-async def _anthropic_tool_stream(request, cancel_event, run_gen, message_id, model_name):
+async def _anthropic_tool_stream(
+    request,
+    cancel_event,
+    run_gen,
+    message_id,
+    model_name,
+    llama_backend = None,
+    openai_messages = None,
+    openai_tools = None,
+    disable_parallel_tool_use = False,
+):
     """Streaming response for the tool-calling path."""
     _sentinel = object()
 
+    # Prompt-token count for message_start.usage.input_tokens. count_chat_tokens
+    # makes blocking HTTP calls to llama-server, so run it off the event loop.
+    # Pass the tools so tool-schema tokens are counted (the generator renders
+    # them too), matching the non-stream / count_tokens / passthrough paths.
+    input_tokens = 0
+    if llama_backend is not None and openai_messages is not None:
+        input_tokens = await asyncio.to_thread(
+            llama_backend.count_chat_tokens, openai_messages, None, openai_tools
+        )
+
     async def _stream():
         emitter = AnthropicStreamEmitter()
-        for line in emitter.start(message_id, model_name):
+        for line in emitter.start(message_id, model_name, input_tokens = input_tokens):
             yield line
 
+        captured_finish_reason = None
+        # Whether the response currently ends on a pending tool_use block (the
+        # client must act → stop_reason "tool_use") as opposed to final text.
+        # The server may run a tool and then keep generating, which flips this
+        # back to False — that is an end_turn (or max_tokens) response.
+        ends_on_tool_use = False
+        tool_blocks_emitted = 0
+        drop_until_tool_end = False
+
         gen = run_gen()
         try:
             while True:
@@ -5018,16 +5539,53 @@ async def _anthropic_tool_stream(request, cancel_event, run_gen, message_id, mod
                 event = await asyncio.to_thread(next, gen, _sentinel)
                 if event is _sentinel:
                     break
-                # Strip leaked tool-call XML from content events
-                if event.get("type") == "content":
+                etype = event.get("type")
+                if drop_until_tool_end:
+                    # disable_parallel_tool_use: a later tool call is being
+                    # dropped — skip every event until (and including) its tool_end.
+                    if etype == "tool_end":
+                        drop_until_tool_end = False
+                    continue
+                if etype == "metadata":
+                    _fr = event.get("finish_reason")
+                    if _fr is not None:
+                        captured_finish_reason = _fr
+                # Strip leaked tool-call XML from content events first, so a
+                # content event that was purely tool XML doesn't count as text.
+                if etype == "content":
                     event = dict(event)
                     event["text"] = _TOOL_XML_RE.sub("", event["text"])
+                # disable_parallel_tool_use: keep only the first tool_use block,
+                # dropping every later tool_start and its paired tool_end (robust
+                # to empty tool-call ids — tracked by state, not id matching).
+                if etype == "tool_start":
+                    if disable_parallel_tool_use and tool_blocks_emitted >= 1:
+                        drop_until_tool_end = True
+                        continue
+                    ends_on_tool_use = True
+                elif etype == "tool_end":
+                    tool_blocks_emitted += 1
+                    # A tool_end means Studio executed the tool server-side, so
+                    # the response no longer ends on a pending client action.
+                    # Without this, a server tool that produces no trailing text
+                    # would be mislabeled stop_reason "tool_use", telling the
+                    # client to run a tool Studio already ran.
+                    ends_on_tool_use = False
+                elif etype == "content" and event.get("text"):
+                    ends_on_tool_use = False
                 for line in emitter.feed(event):
                     yield line
         except Exception as e:
             logger.error("anthropic_messages stream error: %s", e)
+            _error_event = _anthropic_stream_error_event(e)
+            if _error_event is not None:
+                yield _error_event
+                return
 
-        for line in emitter.finish("end_turn"):
+        stop_reason = openai_finish_to_anthropic_stop(
+            captured_finish_reason, had_tool_calls = ends_on_tool_use
+        )
+        for line in emitter.finish(stop_reason = stop_reason, stop_sequence = None):
             yield line
 
     return StreamingResponse(
@@ -5041,15 +5599,31 @@ async def _anthropic_tool_stream(request, cancel_event, run_gen, message_id, mod
     )
 
 
-async def _anthropic_plain_stream(request, cancel_event, run_gen, message_id, model_name):
+async def _anthropic_plain_stream(
+    request,
+    cancel_event,
+    run_gen,
+    message_id,
+    model_name,
+    llama_backend = None,
+    openai_messages = None,
+):
     """Streaming response for the no-tool path."""
     _sentinel = object()
 
+    # Prompt-token count for message_start.usage.input_tokens. count_chat_tokens
+    # makes blocking HTTP calls to llama-server, so run it off the event loop.
+    input_tokens = 0
+    if llama_backend is not None and openai_messages is not None:
+        input_tokens = await asyncio.to_thread(llama_backend.count_chat_tokens, openai_messages)
+
     async def _stream():
         emitter = AnthropicStreamEmitter()
-        for line in emitter.start(message_id, model_name):
+        for line in emitter.start(message_id, model_name, input_tokens = input_tokens):
             yield line
 
+        captured_finish_reason = None
+
         gen = run_gen()
         try:
             while True:
@@ -5061,6 +5635,9 @@ async def _anthropic_plain_stream(request, cancel_event, run_gen, message_id, mo
                     break
                 if isinstance(cumulative, dict):
                     if cumulative.get("type") == "metadata":
+                        _fr = cumulative.get("finish_reason")
+                        if _fr is not None:
+                            captured_finish_reason = _fr
                         for line in emitter.feed(cumulative):
                             yield line
                     continue
@@ -5069,8 +5646,13 @@ async def _anthropic_plain_stream(request, cancel_event, run_gen, message_id, mo
                     yield line
         except Exception as e:
             logger.error("anthropic_messages stream error: %s", e)
+            _error_event = _anthropic_stream_error_event(e)
+            if _error_event is not None:
+                yield _error_event
+                return
 
-        for line in emitter.finish("end_turn"):
+        stop_reason = openai_finish_to_anthropic_stop(captured_finish_reason, had_tool_calls = False)
+        for line in emitter.finish(stop_reason = stop_reason, stop_sequence = None):
             yield line
 
     return StreamingResponse(
@@ -5084,7 +5666,38 @@ async def _anthropic_plain_stream(request, cancel_event, run_gen, message_id, mo
     )
 
 
-async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
+def _anthropic_map_generation_error(e: Exception) -> HTTPException:
+    """Map an upstream 4xx / context-overflow generation error to a clean
+    Anthropic 400 invalid_request_error. Genuine 5xx errors stay 500."""
+    if _classify_llama_generation_error(e) is not None:
+        return HTTPException(
+            status_code = 400,
+            detail = anthropic_error_body(
+                _friendly_error(e),
+                status = 400,
+                err_type = "invalid_request_error",
+            ),
+        )
+    return HTTPException(status_code = 500, detail = _friendly_error(e))
+
+
+def _collect_anthropic_events(run_gen) -> list:
+    """Drain the generator into a list, mapping an upstream 4xx / context
+    overflow to a clean Anthropic 400 instead of leaking a 500."""
+    try:
+        return list(run_gen())
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise _anthropic_map_generation_error(e)
+
+
+async def _anthropic_tool_non_streaming(
+    run_gen,
+    message_id,
+    model_name,
+    disable_parallel_tool_use = False,
+):
     """Non-streaming response for the tool-calling path.
 
     Builds ``content_blocks`` in generation order (text → tool_use → text →
@@ -5101,8 +5714,14 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
     tool_blocks_by_id: dict[str, AnthropicResponseToolUseBlock] = {}
     usage = {}
     prev_text = ""
+    captured_finish_reason = None
+    # Pending client tool_use; cleared by tool_end (server execution) or
+    # trailing text. See the stop_reason mapping below.
+    ends_on_tool_use = False
 
-    for event in run_gen():
+    events = _collect_anthropic_events(run_gen)
+
+    for event in events:
         etype = event.get("type", "")
         if etype == "content":
             # Strip leaked tool-call XML
@@ -5110,6 +5729,7 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
             new = clean[len(prev_text) :]
             prev_text = clean
             if new:
+                ends_on_tool_use = False
                 if content_blocks and isinstance(content_blocks[-1], AnthropicResponseTextBlock):
                     content_blocks[-1].text += new
                 else:
@@ -5125,23 +5745,50 @@ async def _anthropic_tool_non_streaming(run_gen, message_id, model_name):
                     existing_tool_block.name = event["tool_name"]
             else:
                 tool_block = AnthropicResponseToolUseBlock(
-                    id = tool_call_id,
+                    id = anthropic_tool_use_id(tool_call_id),
                     name = event["tool_name"],
                     input = arguments,
                 )
                 if tool_call_id:
                     tool_blocks_by_id[tool_call_id] = tool_block
                 content_blocks.append(tool_block)
+            ends_on_tool_use = True
         elif etype == "tool_end":
             prev_text = ""
+            # Server-executed: no longer pending a client action (see above).
+            ends_on_tool_use = False
         elif etype == "metadata":
             usage = event.get("usage", {})
+            _fr = event.get("finish_reason")
+            if _fr is not None:
+                captured_finish_reason = _fr
+
+    # disable_parallel_tool_use: cap the response to at most one tool_use
+    # block. Keep the first tool_use and drop any later ones.
+    if disable_parallel_tool_use:
+        _seen_tool_use = False
+        _capped: list = []
+        for block in content_blocks:
+            if isinstance(block, AnthropicResponseToolUseBlock):
+                if _seen_tool_use:
+                    continue
+                _seen_tool_use = True
+            _capped.append(block)
+        content_blocks = _capped
+
+    # stop_reason "tool_use" only when the response still ends on a pending
+    # tool_use (client must act). `ends_on_tool_use` is tracked through the
+    # event stream above: it is True only if the last tool_start had no
+    # following tool_end (server execution) or trailing text.
+    stop_reason = openai_finish_to_anthropic_stop(
+        captured_finish_reason, had_tool_calls = ends_on_tool_use
+    )
 
     resp = AnthropicMessagesResponse(
         id = message_id,
         model = model_name,
         content = content_blocks,
-        stop_reason = "end_turn",
+        stop_reason = stop_reason,
         usage = AnthropicUsage(
             input_tokens = usage.get("prompt_tokens", 0),
             output_tokens = usage.get("completion_tokens", 0),
@@ -5155,11 +5802,17 @@ async def _anthropic_plain_non_streaming(run_gen, message_id, model_name):
     text_parts = []
     usage = {}
     prev_text = ""
+    captured_finish_reason = None
 
-    for cumulative in run_gen():
+    events = _collect_anthropic_events(run_gen)
+
+    for cumulative in events:
         if isinstance(cumulative, dict):
             if cumulative.get("type") == "metadata":
                 usage = cumulative.get("usage", {})
+                _fr = cumulative.get("finish_reason")
+                if _fr is not None:
+                    captured_finish_reason = _fr
             continue
         new = cumulative[len(prev_text) :]
         prev_text = cumulative
@@ -5171,11 +5824,13 @@ async def _anthropic_plain_non_streaming(run_gen, message_id, model_name):
     if full_text:
         content_blocks.append(AnthropicResponseTextBlock(text = full_text))
 
+    stop_reason = openai_finish_to_anthropic_stop(captured_finish_reason, had_tool_calls = False)
+
     resp = AnthropicMessagesResponse(
         id = message_id,
         model = model_name,
         content = content_blocks,
-        stop_reason = "end_turn",
+        stop_reason = stop_reason,
         usage = AnthropicUsage(
             input_tokens = usage.get("prompt_tokens", 0),
             output_tokens = usage.get("completion_tokens", 0),
@@ -5205,6 +5860,8 @@ def _build_passthrough_payload(
     response_format = None,
     chat_template_kwargs = None,
     backend_ctx = None,
+    seed = None,
+    stream_options = None,
 ):
     body = {
         "messages": openai_messages,
@@ -5215,14 +5872,19 @@ def _build_passthrough_payload(
         "top_k": top_k,
         "stream": stream,
     }
-    if stream:
-        body["stream_options"] = {"include_usage": True}
+    if seed is not None:
+        body["seed"] = seed
+    if stream and stream_options is not None:
+        body["stream_options"] = stream_options
     body["max_tokens"] = (
         max_tokens if max_tokens is not None else (backend_ctx or _DEFAULT_MAX_TOKENS_FLOOR)
     )
     body["t_max_predict_ms"] = _DEFAULT_T_MAX_PREDICT_MS
-    if stop:
-        body["stop"] = stop
+    # Normalize stop the same way the non-passthrough path does (the passthrough
+    # was previously the one path that forwarded an empty stop string verbatim).
+    _stop = _normalize_stop_sequences(stop)
+    if _stop:
+        body["stop"] = _stop
     if min_p is not None:
         body["min_p"] = min_p
     if repetition_penalty is not None:
@@ -5263,6 +5925,7 @@ async def _anthropic_passthrough_stream(
     tool_choice = "auto",
     session_id = None,
     cancel_id = None,
+    disable_parallel_tool_use = False,
 ):
     """Streaming client-side pass-through: forward tools to llama-server and
     translate its stream to Anthropic SSE without executing anything."""
@@ -5281,16 +5944,25 @@ async def _anthropic_passthrough_stream(
         presence_penalty = presence_penalty,
         tool_choice = tool_choice,
         backend_ctx = llama_backend.context_length,
+        stream_options = {"include_usage": True},
     )
 
-    # cancel_id mirrors the OpenAI passthrough so a per-run cancel POST works
-    # without the caller knowing the local message_id.
+    # Prompt-token count for message_start.usage.input_tokens. count_chat_tokens
+    # makes blocking HTTP calls to llama-server, so run it off the event loop.
+    # Pass the tools through so tool-schema tokens are counted (otherwise the
+    # streaming input_tokens undercounts vs the non-stream / count_tokens paths).
+    input_tokens = await asyncio.to_thread(
+        llama_backend.count_chat_tokens, openai_messages, None, openai_tools
+    )
+
+    # cancel_id mirrors the OpenAI passthrough so a per-run cancel POST
+    # works without the caller having to know the local message_id.
     _tracker = _TrackedCancel(cancel_event, cancel_id, session_id, message_id)
     _tracker.__enter__()
 
     async def _stream():
         emitter = AnthropicPassthroughEmitter()
-        for line in emitter.start(message_id, model_name):
+        for line in emitter.start(message_id, model_name, input_tokens = input_tokens):
             yield line
 
         # Manage the httpx client, response, AND the aiter_lines() async
@@ -5327,10 +5999,31 @@ async def _anthropic_passthrough_stream(
             req = client.build_request("POST", target_url, json = body)
             resp = await client.send(req, stream = True)
 
-            # See _openai_passthrough_stream for rationale: aiter_lines() blocks
-            # during llama-server prefill, so the in-loop cancel check is
-            # unreachable until the first SSE chunk arrives. The watcher closes
-            # `resp` on cancel, raising in aiter_lines.
+            # Upstream client error (e.g. over-context 400) arrives before any
+            # SSE. The 200 stream headers are already flushed, so surface it as
+            # an in-band Anthropic ``error`` event instead of silently finishing
+            # with an empty end_turn message.
+            if resp.status_code != 200:
+                _err_bytes = await resp.aread()
+                _err_text = _err_bytes.decode("utf-8", "replace")[:500]
+                logger.error(
+                    "anthropic passthrough upstream error: status=%s body=%s",
+                    resp.status_code,
+                    _err_text,
+                )
+                yield build_anthropic_sse_event(
+                    "error",
+                    anthropic_error_body(
+                        f"llama-server error: {_err_text}",
+                        status = resp.status_code,
+                    ),
+                )
+                return
+
+            # See _openai_passthrough_stream for rationale: aiter_lines()
+            # blocks during llama-server prefill, so the in-loop cancel
+            # check is unreachable until the first SSE chunk arrives.
+            # The watcher closes `resp` on cancel, raising in aiter_lines.
             cancel_watcher = asyncio.create_task(_await_cancel_then_close(cancel_event, resp))
             lines_iter = resp.aiter_lines()
             async for raw_line in lines_iter:
@@ -5348,6 +6041,8 @@ async def _anthropic_passthrough_stream(
                     chunk = json.loads(data_str)
                 except json.JSONDecodeError:
                     continue
+                if disable_parallel_tool_use:
+                    _drop_parallel_tool_call_deltas(chunk)
                 for line in emitter.feed_chunk(chunk):
                     yield line
         except (httpx.RemoteProtocolError, httpx.ReadError, httpx.CloseError):
@@ -5407,6 +6102,7 @@ async def _anthropic_passthrough_non_streaming(
     repetition_penalty = None,
     presence_penalty = None,
     tool_choice = "auto",
+    disable_parallel_tool_use = False,
 ):
     """Non-streaming client-side pass-through."""
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
@@ -5448,6 +6144,9 @@ async def _anthropic_passthrough_non_streaming(
             content_blocks.append(AnthropicResponseTextBlock(text = text))
 
     tool_calls = message.get("tool_calls") or []
+    # disable_parallel_tool_use: keep only the first tool_use block.
+    if disable_parallel_tool_use and len(tool_calls) > 1:
+        tool_calls = tool_calls[:1]
     for tc in tool_calls:
         fn = tc.get("function") or {}
         try:
@@ -5456,18 +6155,13 @@ async def _anthropic_passthrough_non_streaming(
             args = {}
         content_blocks.append(
             AnthropicResponseToolUseBlock(
-                id = tc.get("id", ""),
+                id = anthropic_tool_use_id(tc.get("id")),
                 name = fn.get("name", ""),
                 input = args,
             )
         )
 
-    if tool_calls:
-        stop_reason = "tool_use"
-    elif finish_reason == "length":
-        stop_reason = "max_tokens"
-    else:
-        stop_reason = "end_turn"
+    stop_reason = openai_finish_to_anthropic_stop(finish_reason, had_tool_calls = bool(tool_calls))
 
     usage = data.get("usage") or {}
     resp_obj = AnthropicMessagesResponse(
@@ -5734,7 +6428,8 @@ def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
         payload.temperature,
         payload.top_p,
         payload.top_k,
-        payload.max_tokens,
+        # Honor max_completion_tokens on the tools/response_format passthrough too.
+        _effective_max_tokens(payload),
         payload.stream,
         stop = payload.stop,
         min_p = payload.min_p,
@@ -5744,6 +6439,8 @@ def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
         response_format = _extract_response_format(payload),
         chat_template_kwargs = tpl_kwargs,
         backend_ctx = backend_ctx,
+        seed = payload.seed,
+        stream_options = payload.stream_options,
     )
 
 
@@ -5755,8 +6452,8 @@ async def _openai_passthrough_stream(
     Forwards the client's OpenAI function-calling request to llama-server and
     relays the SSE stream back verbatim, preserving llama-server's native
     response ``id``, ``finish_reason`` (including ``"tool_calls"``),
-    ``delta.tool_calls``, and the trailing ``usage`` chunk so the client sees a
-    standard OpenAI response.
+    ``delta.tool_calls``, and any client-requested trailing ``usage`` chunk so
+    the client sees a standard OpenAI response.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
     body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
@@ -5814,10 +6511,7 @@ async def _openai_passthrough_stream(
                 await client.aclose()
             except Exception:
                 pass
-            raise HTTPException(
-                status_code = upstream_status,
-                detail = f"llama-server error: {err_text[:500]}",
-            )
+            raise _openai_passthrough_error(upstream_status, err_text)
 
         async def _stream():
             # Same httpx lifecycle pattern as _anthropic_passthrough_stream:
@@ -5843,6 +6537,12 @@ async def _openai_passthrough_stream(
                         continue
                     if not raw_line.startswith("data: "):
                         continue
+                    # Honor parallel_tool_calls=false (best-effort): drop tool_call
+                    # deltas with index>=1 so only the first call streams. Only
+                    # lines carrying tool_calls are reparsed; everything else is
+                    # relayed byte-for-byte.
+                    if payload.parallel_tool_calls is False and '"tool_calls"' in raw_line:
+                        raw_line = _cap_parallel_tool_calls_sse_line(raw_line)
                     # Relay verbatim to preserve llama-server's native id,
                     # finish_reason, delta.tool_calls, and usage chunks.
                     yield raw_line + "\n\n"
@@ -5856,12 +6556,7 @@ async def _openai_passthrough_stream(
             except Exception as e:
                 # 200 headers already flushed; errors must go in the SSE body.
                 logger.error("openai passthrough stream error: %s", e)
-                err = {
-                    "error": {
-                        "message": _friendly_error(e),
-                        "type": "server_error",
-                    },
-                }
+                err = _openai_stream_error_chunk(e)
                 yield f"data: {json.dumps(err)}\n\n"
             finally:
                 cancel_watcher.cancel()
@@ -5922,46 +6617,62 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
         )
 
     if resp.status_code != 200:
-        raise HTTPException(
-            status_code = resp.status_code,
-            detail = f"llama-server error: {resp.text[:500]}",
+        raise _openai_passthrough_error(resp.status_code, resp.text)
+
+    # The guided-decoding fence wraps each choice's JSON content in a
+    # ```json ... ``` markdown fence that data_designer's structured parser
+    # requires but which CORRUPTS output for standard OpenAI clients doing
+    # ``json.loads(content)``. It is therefore opt-in: only the internal
+    # data-recipe path sets ``_unsloth_guided_fence``; public response_format
+    # clients get the raw upstream JSON verbatim.
+    _guided_fence = bool((payload.model_extra or {}).get("_unsloth_guided_fence"))
+    _do_fence = _guided_fence and _extract_response_format(payload) is not None
+    _cap_parallel = payload.parallel_tool_calls is False
+
+    try:
+        data = resp.json()
+    except Exception as exc:
+        # Non-JSON / unparseable upstream body: relay verbatim as before.
+        logger.warning(
+            "openai passthrough non-streaming: response not JSON, relaying raw: %s",
+            exc,
         )
+        return Response(content = resp.content, media_type = "application/json")
 
-    # Guided-decoding fence wrap. llama-server returns raw JSON matching the
-    # schema (no markdown) since the GBNF grammar emits only the JSON object.
-    # data_designer's llm-structured parser looks for a ```json ... ``` fence
-    # and discards unfenced output, collapsing a 100%-valid guided-decoding run
-    # to 0/N. Wrap each choice's content in the expected fence when the caller
-    # asked for guided decoding, leaving already-fenced content alone.
-    if _extract_response_format(payload) is not None:
-        try:
-            data = resp.json()
-            changed = False
-            for choice in data.get("choices", []):
-                if not isinstance(choice, dict):
-                    continue
-                msg = choice.get("message")
-                if not isinstance(msg, dict):
-                    continue
-                content = msg.get("content")
-                if not isinstance(content, str):
-                    continue
-                stripped = content.strip()
-                if not stripped or stripped.startswith("```"):
-                    continue
-                msg["content"] = f"```json\n{stripped}\n```"
+    changed = False
+    for choice in data.get("choices", []):
+        if not isinstance(choice, dict):
+            continue
+        msg = choice.get("message")
+        if not isinstance(msg, dict):
+            continue
+
+        # OpenAI requires content=null on a pure tool-call turn; llama-server
+        # emits content="".
+        if msg.get("tool_calls") and msg.get("content") == "":
+            msg["content"] = None
+            changed = True
+
+        # Honor parallel_tool_calls=false (best-effort) by capping to one call.
+        if _cap_parallel:
+            _tcs = msg.get("tool_calls")
+            if isinstance(_tcs, list) and len(_tcs) > 1:
+                msg["tool_calls"] = _tcs[:1]
                 changed = True
-            if changed:
-                return JSONResponse(content = data)
-        except Exception as exc:
-            # Wrap is best-effort; fall through to the verbatim body if the
-            # response isn't JSON-shaped or the structure is unusual.
-            logger.warning(
-                "response_format fence wrap skipped: %s",
-                exc,
-            )
 
-    # Pass the upstream body through as raw bytes -- skips a redundant
-    # parse+re-serialize round-trip and keeps the response truly verbatim
-    # (matches the docstring). Status is guaranteed 200 by the check above.
-    return Response(content = resp.content, media_type = "application/json")
+        # Guided-decoding fence wrap (opt-in via _unsloth_guided_fence).
+        if _do_fence:
+            content = msg.get("content")
+            if not isinstance(content, str):
+                continue
+            stripped = content.strip()
+            if not stripped or stripped.startswith("```"):
+                continue
+            msg["content"] = f"```json\n{stripped}\n```"
+            changed = True
+
+    # Nothing mutated: relay the upstream bytes verbatim, skipping a redundant
+    # parse + re-serialize round-trip.
+    if not changed:
+        return Response(content = resp.content, media_type = "application/json")
+    return JSONResponse(content = data)
diff --git a/studio/backend/tests/test_anthropic_messages.py b/studio/backend/tests/test_anthropic_messages.py
index 207c4b3805..e1230ae113 100644
--- a/studio/backend/tests/test_anthropic_messages.py
+++ b/studio/backend/tests/test_anthropic_messages.py
@@ -6,7 +6,9 @@
 import sys
 import os
 import json
+import threading
 
+import httpx
 import pytest
 
 _backend = os.path.join(os.path.dirname(__file__), "..")
@@ -36,6 +38,7 @@ from routes.inference import (
     _normalize_anthropic_openai_images,
     _select_anthropic_server_tools,
     _anthropic_requested_studio_tools,
+    _anthropic_passthrough_stream,
     _anthropic_tool_non_streaming,
     anthropic_messages,
 )
@@ -671,7 +674,7 @@ class TestAnthropicStreamEmitter:
             and payload["content_block"]["type"] == "tool_use"
         ]
         assert len(tool_starts) == 1
-        assert tool_starts[0]["content_block"]["id"] == "call_0"
+        assert tool_starts[0]["content_block"]["id"].startswith("toolu_")
         assert second_payloads == [
             {
                 "type": "content_block_delta",
@@ -686,7 +689,7 @@ class TestAnthropicStreamEmitter:
     def test_tool_end_closes_tool_opens_new_text_block(self):
         e = AnthropicStreamEmitter()
         e.start("msg_1", "m")
-        e.feed(
+        start_events = e.feed(
             {
                 "type": "tool_start",
                 "tool_name": "t",
@@ -694,6 +697,13 @@ class TestAnthropicStreamEmitter:
                 "arguments": {},
             }
         )
+        start_payload = next(
+            json.loads(event.split("data: ")[1])
+            for event in start_events
+            if "content_block_start" in event
+        )
+        tool_use_id = start_payload["content_block"]["id"]
+        assert tool_use_id.startswith("toolu_")
         events = e.feed(
             {
                 "type": "tool_end",
@@ -708,7 +718,7 @@ class TestAnthropicStreamEmitter:
         assert "tool_result" in events[1]
         parsed = json.loads(events[1].split("data: ")[1])
         assert parsed["content"] == "done"
-        assert parsed["tool_use_id"] == "tc_1"
+        assert parsed["tool_use_id"] == tool_use_id
         assert "content_block_start" in events[2]
         assert '"type": "text"' in events[2]
 
@@ -837,14 +847,11 @@ class TestAnthropicToolNonStreaming:
         body = json.loads(response.body)
         tool_blocks = [block for block in body["content"] if block["type"] == "tool_use"]
 
-        assert tool_blocks == [
-            {
-                "type": "tool_use",
-                "id": "call_0",
-                "name": "render_html",
-                "input": {"code": "<!doctype html><html></html>"},
-            }
-        ]
+        assert len(tool_blocks) == 1
+        assert tool_blocks[0]["type"] == "tool_use"
+        assert tool_blocks[0]["id"].startswith("toolu_")
+        assert tool_blocks[0]["name"] == "render_html"
+        assert tool_blocks[0]["input"] == {"code": "<!doctype html><html></html>"}
 
 
 # =====================================================================
@@ -912,7 +919,7 @@ class TestAnthropicPassthroughEmitter:
         parsed = self._parse(events[0])
         assert parsed["type"] == "content_block_start"
         assert parsed["content_block"]["type"] == "tool_use"
-        assert parsed["content_block"]["id"] == "call_1"
+        assert parsed["content_block"]["id"].startswith("toolu_")
         assert parsed["content_block"]["name"] == "Bash"
 
     def test_tool_call_arguments_streamed_as_input_json_delta(self):
@@ -1117,7 +1124,102 @@ class TestAnthropicPassthroughEmitter:
         assert "content_block_start" in events[1]
         parsed = self._parse(events[1])
         assert parsed["content_block"]["name"] == "Read"
-        assert parsed["content_block"]["id"] == "c2"
+        assert parsed["content_block"]["id"].startswith("toolu_")
+
+
+class TestAnthropicPassthroughStreamAdapter:
+    class _Request:
+        async def is_disconnected(self):
+            return False
+
+    @staticmethod
+    async def _collect(response):
+        chunks = []
+        async for chunk in response.body_iterator:
+            chunks.append(chunk.decode() if isinstance(chunk, bytes) else chunk)
+        return chunks
+
+    @staticmethod
+    def _payloads(lines, event_name):
+        prefix = f"event: {event_name}\n"
+        return [
+            json.loads(line.split("data: ", 1)[1].strip())
+            for line in lines
+            if line.startswith(prefix)
+        ]
+
+    def test_stream_requests_usage_for_final_message_delta(self, monkeypatch):
+        import routes.inference as inf_mod
+
+        captured = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["body"] = json.loads(request.content.decode())
+            chunks = [
+                {"choices": [{"delta": {"content": "hi"}}]},
+                {
+                    "choices": [],
+                    "usage": {
+                        "prompt_tokens": 2,
+                        "completion_tokens": 4,
+                        "total_tokens": 6,
+                    },
+                },
+            ]
+            content = "".join(f"data: {json.dumps(chunk)}\n\n" for chunk in chunks)
+            content += "data: [DONE]\n\n"
+            return httpx.Response(
+                200,
+                content = content.encode(),
+                headers = {"content-type": "text/event-stream"},
+            )
+
+        transport = httpx.MockTransport(handler)
+        real_async_client = httpx.AsyncClient
+
+        def _client(*args, **kwargs):
+            return real_async_client(
+                transport = transport,
+                timeout = kwargs.get("timeout", 600),
+            )
+
+        monkeypatch.setattr(inf_mod.httpx, "AsyncClient", _client)
+        backend = SimpleNamespace(
+            base_url = "http://llama.test",
+            context_length = 4096,
+            count_chat_tokens = lambda *args, **kwargs: 2,
+        )
+
+        async def run():
+            response = await _anthropic_passthrough_stream(
+                self._Request(),
+                threading.Event(),
+                backend,
+                [{"role": "user", "content": "hi"}],
+                [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "lookup",
+                            "parameters": {"type": "object"},
+                        },
+                    }
+                ],
+                0.7,
+                0.95,
+                20,
+                16,
+                "msg_1",
+                "test-model",
+            )
+            return await self._collect(response)
+
+        lines = asyncio.run(run())
+
+        assert captured["body"]["stream_options"] == {"include_usage": True}
+        message_delta = self._payloads(lines, "message_delta")[0]
+        assert message_delta["usage"]["input_tokens"] == 2
+        assert message_delta["usage"]["output_tokens"] == 4
 
 
 # =====================================================================
@@ -1271,27 +1373,23 @@ class TestAnthropicRequestedStudioTools:
 # =====================================================================
 
 
-class _PlainPathCalled(Exception):
-    pass
-
-
-class _ToolPathCalled(Exception):
-    pass
-
-
 def _mock_backend(monkeypatch, **overrides):
     """Install a minimal stub backend on routes.inference.
 
-    Generation methods raise sentinels so the caller can assert which path
-    the route entered.
+    Generation methods record which path the route entered, then yield one
+    content event so the route can complete normally.
     """
     import routes.inference as inf_mod
 
+    calls = []
+
     def _gen_plain(**kwargs):
-        raise _PlainPathCalled()
+        calls.append(("plain", kwargs))
+        yield {"type": "content", "text": "ok"}
 
     def _gen_tools(**kwargs):
-        raise _ToolPathCalled()
+        calls.append(("tools", kwargs))
+        yield {"type": "content", "text": "ok"}
 
     backend = SimpleNamespace(
         is_loaded = True,
@@ -1300,6 +1398,7 @@ def _mock_backend(monkeypatch, **overrides):
         model_identifier = "test-model",
         generate_chat_completion = _gen_plain,
         generate_chat_completion_with_tools = _gen_tools,
+        calls = calls,
     )
     backend.__dict__.update(overrides)
     monkeypatch.setattr(inf_mod, "get_llama_cpp_backend", lambda: backend)
@@ -1414,42 +1513,42 @@ class TestAnthropicMessagesToolRouting:
         assert "input_schema" in exc.value.detail
 
     def test_unrecognized_server_tool_accepted_as_noop(self, monkeypatch):
-        _mock_backend(monkeypatch)
+        backend = _mock_backend(monkeypatch)
         payload = _basic_payload(
             tools = [{"type": "code_execution_20250825", "name": "code_execution"}],
         )
 
-        with pytest.raises(_PlainPathCalled):
-            _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        assert backend.calls[0][0] == "plain"
 
     def test_disable_tools_policy_overrides_server_tool_alias(self, monkeypatch):
         # CLI `unsloth run --disable-tools` sets policy=False. A request with
         # a Studio server-tool alias must NOT enter the agentic loop then.
-        _mock_backend(monkeypatch)
+        backend = _mock_backend(monkeypatch)
         set_tool_policy(False)
         payload = _basic_payload(
             tools = [{"type": "web_search_20250305", "name": "web_search"}],
         )
 
-        with pytest.raises(_PlainPathCalled):
-            _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        assert backend.calls[0][0] == "plain"
 
     def test_server_tool_alias_enters_tool_path_when_policy_unset(self, monkeypatch):
         # Mirror of the previous test for the default (None) policy.
-        _mock_backend(monkeypatch)
+        backend = _mock_backend(monkeypatch)
         payload = _basic_payload(
             tools = [{"type": "web_search_20250305", "name": "web_search"}],
         )
 
-        with pytest.raises(_ToolPathCalled):
-            _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        assert backend.calls[0][0] == "tools"
 
     def test_per_request_enable_tools_false_blocks_server_tool_alias(self, monkeypatch):
-        _mock_backend(monkeypatch)
+        backend = _mock_backend(monkeypatch)
         payload = _basic_payload(
             enable_tools = False,
             tools = [{"type": "web_search_20250305", "name": "web_search"}],
         )
 
-        with pytest.raises(_PlainPathCalled):
-            _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        _drive(anthropic_messages(payload, request = None, current_subject = "t"))
+        assert backend.calls[0][0] == "plain"
diff --git a/studio/backend/tests/test_gguf_completion_usage.py b/studio/backend/tests/test_gguf_completion_usage.py
index 9f9de80a84..d1e05f3e0e 100644
--- a/studio/backend/tests/test_gguf_completion_usage.py
+++ b/studio/backend/tests/test_gguf_completion_usage.py
@@ -53,10 +53,16 @@ def test_non_streaming_gguf_completion_includes_generated_usage(monkeypatch):
     )
 
     assert response.status_code == 200
-    assert response.json()["usage"] == {
-        "prompt_tokens": 23,
-        "completion_tokens": 1283,
-        "total_tokens": 1306,
+    usage = response.json()["usage"]
+    assert usage["prompt_tokens"] == 23
+    assert usage["completion_tokens"] == 1283
+    assert usage["total_tokens"] == 1306
+    assert usage["prompt_tokens_details"] == {"cached_tokens": 0, "audio_tokens": 0}
+    assert usage["completion_tokens_details"] == {
+        "reasoning_tokens": 0,
+        "audio_tokens": 0,
+        "accepted_prediction_tokens": 0,
+        "rejected_prediction_tokens": 0,
     }
 
 
@@ -67,8 +73,14 @@ def test_non_streaming_gguf_completion_defaults_nullable_usage_to_zero(monkeypat
     )
 
     assert response.status_code == 200
-    assert response.json()["usage"] == {
-        "prompt_tokens": 0,
-        "completion_tokens": 1283,
-        "total_tokens": 0,
+    usage = response.json()["usage"]
+    assert usage["prompt_tokens"] == 0
+    assert usage["completion_tokens"] == 1283
+    assert usage["total_tokens"] == 1283
+    assert usage["prompt_tokens_details"] == {"cached_tokens": 0, "audio_tokens": 0}
+    assert usage["completion_tokens_details"] == {
+        "reasoning_tokens": 0,
+        "audio_tokens": 0,
+        "accepted_prediction_tokens": 0,
+        "rejected_prediction_tokens": 0,
     }
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 4437bf2212..495ebc434d 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -12,6 +12,7 @@ mapping. No server or GPU required.
 import os
 import sys
 import asyncio
+import json
 from types import SimpleNamespace
 
 _backend = os.path.join(os.path.dirname(__file__), "..")
@@ -25,13 +26,19 @@ from pydantic import ValidationError
 from models.inference import (
     ChatCompletionRequest,
     ChatMessage,
+    CompletionChoice,
+    CompletionMessage,
 )
 from core.inference.anthropic_compat import (
     anthropic_tool_choice_to_openai,
 )
 from routes.inference import (
     _build_passthrough_payload,
+    _clamp_finish_reason,
+    _effective_max_tokens,
+    _extract_content_parts,
     _friendly_error,
+    _openai_stream_usage_chunk,
     _set_or_prepend_system_message,
     openai_chat_completions,
 )
@@ -271,17 +278,19 @@ class TestChatCompletionRequestToolFields:
         assert req.stop is None
 
     def test_extra_fields_accepted(self):
-        # `frequency_penalty`, `seed`, `response_format` aren't explicitly
-        # declared but must survive Pydantic parsing now that extra="allow".
+        # `frequency_penalty` and `response_format` are not yet explicitly
+        # declared but must survive Pydantic parsing now that extra="allow" is
+        # set. `seed` is declared and should land on the typed field instead.
         req = self._make(
             frequency_penalty = 0.5,
             seed = 42,
             response_format = {"type": "json_object"},
         )
+        assert req.seed == 42
         # Extras land in model_extra
         assert req.model_extra is not None
         assert req.model_extra.get("frequency_penalty") == 0.5
-        assert req.model_extra.get("seed") == 42
+        assert "seed" not in req.model_extra
         assert req.model_extra.get("response_format") == {"type": "json_object"}
 
     def test_unsloth_extensions_still_work(self):
@@ -337,6 +346,153 @@ class TestChatCompletionRequestToolFields:
         assert "text/event-stream" not in resp.headers["content-type"]
         assert captured["stream"] is False
 
+    def _v1_client(
+        self,
+        monkeypatch,
+        llama_backend,
+        inference_backend = None,
+    ):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        import routes.inference as inference_route
+        from auth.authentication import get_current_subject
+        from utils.api_errors import install_api_error_handlers
+
+        monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: llama_backend)
+        if inference_backend is not None:
+            monkeypatch.setattr(inference_route, "get_inference_backend", lambda: inference_backend)
+
+        app = FastAPI()
+        app.include_router(inference_route.router, prefix = "/v1")
+        install_api_error_handlers(app)
+        app.dependency_overrides[get_current_subject] = lambda: "test-user"
+        return TestClient(app)
+
+    def _assert_unsupported_param(self, response, param):
+        assert response.status_code == 400
+        body = response.json()
+        assert body["error"]["param"] == param
+        assert body["error"]["code"] == "unsupported_parameter"
+
+    def _assert_unsupported_n(self, response):
+        self._assert_unsupported_param(response, "n")
+
+    def test_n_allows_openai_chat_completion_range(self):
+        req = self._make(n = 128)
+        assert req.n == 128
+        with pytest.raises(ValidationError):
+            self._make(n = 129)
+
+    def test_n_rejected_for_external_provider_path(self, monkeypatch):
+        class _UnusedBackend:
+            is_loaded = False
+
+        client = self._v1_client(monkeypatch, _UnusedBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "provider_type": "openai",
+                "n": 2,
+            },
+        )
+        self._assert_unsupported_n(resp)
+
+    def test_logprobs_rejected_until_supported(self, monkeypatch):
+        class _UnusedBackend:
+            is_loaded = False
+
+        client = self._v1_client(monkeypatch, _UnusedBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "provider_type": "openai",
+                "logprobs": True,
+            },
+        )
+        self._assert_unsupported_param(resp, "logprobs")
+
+    def test_top_logprobs_rejected_until_supported(self, monkeypatch):
+        class _UnusedBackend:
+            is_loaded = False
+
+        client = self._v1_client(monkeypatch, _UnusedBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "provider_type": "openai",
+                "top_logprobs": 3,
+            },
+        )
+        self._assert_unsupported_param(resp, "top_logprobs")
+
+    def test_n_rejected_for_gguf_streaming_path(self, monkeypatch):
+        class _GGUFBackend:
+            is_loaded = True
+            model_identifier = "test-gguf"
+            supports_tools = False
+            is_vision = False
+            _is_audio = False
+
+        client = self._v1_client(monkeypatch, _GGUFBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "stream": True,
+                "n": 2,
+            },
+        )
+        self._assert_unsupported_n(resp)
+
+    def test_n_rejected_for_gguf_tools_passthrough_path(self, monkeypatch):
+        class _GGUFBackend:
+            is_loaded = True
+            model_identifier = "test-gguf"
+            supports_tools = True
+            is_vision = False
+            _is_audio = False
+
+        client = self._v1_client(monkeypatch, _GGUFBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "tools": [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "lookup",
+                            "parameters": {"type": "object"},
+                        },
+                    }
+                ],
+                "n": 2,
+            },
+        )
+        self._assert_unsupported_n(resp)
+
+    def test_n_rejected_for_non_gguf_path(self, monkeypatch):
+        class _NoGGUFBackend:
+            is_loaded = False
+
+        class _InferenceBackend:
+            active_model_name = "test-model"
+            models = {"test-model": {}}
+
+        client = self._v1_client(monkeypatch, _NoGGUFBackend(), _InferenceBackend())
+        resp = client.post(
+            "/v1/chat/completions",
+            json = {
+                "messages": [{"role": "user", "content": "hi"}],
+                "n": 2,
+            },
+        )
+        self._assert_unsupported_n(resp)
+
     def test_multiturn_tool_loop_messages(self):
         req = ChatCompletionRequest(
             messages = [
@@ -449,18 +605,115 @@ class TestBuildPassthroughPayloadToolChoice:
         body = _build_passthrough_payload(**self._args(), tool_choice = tc)
         assert body["tool_choice"] == tc
 
-    def test_stream_adds_include_usage(self):
+    def test_stream_omits_usage_options_when_client_did_not_request_them(self):
         args = self._args()
         args["stream"] = True
         body = _build_passthrough_payload(**args)
+        assert "stream_options" not in body
+
+    def test_stream_forwards_include_usage_when_client_requests_it(self):
+        args = self._args()
+        args["stream"] = True
+        body = _build_passthrough_payload(
+            **args,
+            stream_options = {"include_usage": True},
+        )
         assert body.get("stream_options") == {"include_usage": True}
 
+    def test_stream_forwards_include_usage_false_when_client_requests_it(self):
+        args = self._args()
+        args["stream"] = True
+        body = _build_passthrough_payload(
+            **args,
+            stream_options = {"include_usage": False},
+        )
+        assert body.get("stream_options") == {"include_usage": False}
+
     def test_repetition_penalty_renamed(self):
         body = _build_passthrough_payload(**self._args(), repetition_penalty = 1.1)
         assert body.get("repeat_penalty") == 1.1
         assert "repetition_penalty" not in body
 
 
+# =====================================================================
+# OpenAI API compatibility helpers — verified spec edge cases
+# =====================================================================
+
+
+class TestOpenAICompatibilityHelpers:
+    def test_max_completion_tokens_wins_over_deprecated_max_tokens(self):
+        payload = SimpleNamespace(max_tokens = 128, max_completion_tokens = 64)
+        assert _effective_max_tokens(payload) == 64
+
+    @pytest.mark.parametrize(
+        "finish_reason",
+        ["stop", "length", "tool_calls", "content_filter", "function_call"],
+    )
+    def test_clamp_finish_reason_preserves_openai_finish_reasons(self, finish_reason):
+        assert _clamp_finish_reason(finish_reason) == finish_reason
+
+    def test_clamp_finish_reason_defaults_unknown_to_stop(self):
+        assert _clamp_finish_reason(None) == "stop"
+        assert _clamp_finish_reason("unexpected") == "stop"
+
+    def test_non_streaming_completion_choice_accepts_tool_calls_finish_reason(self):
+        choice = CompletionChoice(
+            index = 0,
+            message = CompletionMessage(content = ""),
+            finish_reason = "tool_calls",
+        )
+        assert choice.finish_reason == "tool_calls"
+
+    def test_stream_usage_chunk_requires_include_usage(self):
+        usage = {"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5}
+        payload = SimpleNamespace(stream_options = None)
+        assert (
+            _openai_stream_usage_chunk(payload, "chatcmpl-test", 123, "model", usage, None) is None
+        )
+
+        payload.stream_options = {"include_usage": True}
+        line = _openai_stream_usage_chunk(payload, "chatcmpl-test", 123, "model", usage, None)
+        assert line is not None
+        assert '"choices":[]' in line
+        assert '"usage"' in line
+
+    def test_stream_usage_chunk_coerces_nullable_counts(self):
+        payload = SimpleNamespace(stream_options = {"include_usage": True})
+        line = _openai_stream_usage_chunk(
+            payload,
+            "chatcmpl-test",
+            123,
+            "model",
+            {"prompt_tokens": None, "completion_tokens": 7, "total_tokens": None},
+            None,
+        )
+
+        assert line is not None
+        parsed = json.loads(line.removeprefix("data: "))
+        usage = parsed["usage"]
+        assert usage["prompt_tokens"] == 0
+        assert usage["completion_tokens"] == 7
+        assert usage["total_tokens"] == 7
+
+    def test_developer_message_preserves_existing_system_prompt(self):
+        payload = ChatCompletionRequest(
+            messages = [
+                {"role": "system", "content": "original system"},
+                {"role": "developer", "content": "developer rules"},
+                {"role": "user", "content": "hi"},
+            ]
+        )
+        for message in payload.messages:
+            if message.role == "developer":
+                message.role = "system"
+
+        system_prompt, chat_messages, image_b64 = _extract_content_parts(payload.messages)
+
+        assert system_prompt == "original system\n\ndeveloper rules"
+        assert chat_messages == [{"role": "user", "content": "hi"}]
+        assert image_b64 is None
+
+
 # =====================================================================
 # _friendly_error — httpx transport failures
 # =====================================================================
@@ -800,3 +1053,90 @@ class TestGgufVisionToolRouting:
         assert tool_messages[0]["role"] == "system"
         assert tool_messages[1]["role"] == "user"
         assert tool_messages[1]["content"][1]["type"] == "image_url"
+
+    def test_parallel_tool_calls_false_reaches_gguf_tool_loop(self, monkeypatch):
+        import routes.inference as inf_mod
+
+        reset_tool_policy()
+        captured = {}
+
+        def _plain(**kwargs):
+            raise AssertionError("plain GGUF path should not be used")
+
+        def _tools(**kwargs):
+            captured["kwargs"] = kwargs
+            yield {"type": "content", "text": "done"}
+
+        backend = SimpleNamespace(
+            is_loaded = True,
+            is_vision = False,
+            supports_tools = True,
+            model_identifier = "test-gguf",
+            generate_chat_completion = _plain,
+            generate_chat_completion_with_tools = _tools,
+        )
+        monkeypatch.setattr(inf_mod, "get_llama_cpp_backend", lambda: backend)
+
+        payload = ChatCompletionRequest(
+            model = "default",
+            enable_tools = True,
+            enabled_tools = ["web_search"],
+            parallel_tool_calls = False,
+            messages = [{"role": "user", "content": "search once"}],
+        )
+
+        response = self._drive(
+            openai_chat_completions(payload, request = self._Request(), current_subject = "test")
+        )
+        self._consume_response(response)
+
+        assert captured["kwargs"]["disable_parallel_tool_use"] is True
+
+    @pytest.mark.parametrize(
+        ("seed", "expected"),
+        [
+            (41, [41, 42, 43]),
+            (-1, [-1, -1, -1]),
+        ],
+    )
+    def test_gguf_n_choices_vary_explicit_non_negative_seed(self, monkeypatch, seed, expected):
+        import routes.inference as inf_mod
+
+        seen_seeds = []
+
+        def _generate(**kwargs):
+            seen_seeds.append(kwargs.get("seed"))
+            yield f"choice-{len(seen_seeds)}"
+            yield {
+                "type": "metadata",
+                "usage": {
+                    "prompt_tokens": 5,
+                    "completion_tokens": 7,
+                    "total_tokens": 12,
+                },
+                "finish_reason": "stop",
+            }
+
+        backend = SimpleNamespace(
+            is_loaded = True,
+            is_vision = False,
+            supports_tools = False,
+            model_identifier = "test-gguf",
+            generate_chat_completion = _generate,
+        )
+        monkeypatch.setattr(inf_mod, "get_llama_cpp_backend", lambda: backend)
+
+        payload = ChatCompletionRequest(
+            model = "default",
+            messages = [{"role": "user", "content": "hi"}],
+            n = 3,
+            seed = seed,
+        )
+
+        response = self._drive(
+            openai_chat_completions(payload, request = self._Request(), current_subject = "test")
+        )
+        body = json.loads(response.body)
+
+        assert seen_seeds == expected
+        assert [choice["index"] for choice in body["choices"]] == [0, 1, 2]
diff --git a/studio/backend/tests/test_responses_tool_passthrough.py b/studio/backend/tests/test_responses_tool_passthrough.py
index c182e3d6d0..f0f2714214 100644
--- a/studio/backend/tests/test_responses_tool_passthrough.py
+++ b/studio/backend/tests/test_responses_tool_passthrough.py
@@ -26,12 +26,15 @@ No running server or GPU required.
 
 import os
 import sys
+import asyncio
+from types import SimpleNamespace
 
 _backend = os.path.join(os.path.dirname(__file__), "..")
 sys.path.insert(0, _backend)
 
 import json
 
+import httpx
 import pytest
 from pydantic import ValidationError
 
@@ -52,8 +55,10 @@ from models.inference import (
     ResponsesUsage,
 )
 from routes.inference import (
+    _build_chat_request,
     _chat_tool_calls_to_responses_output,
     _normalise_responses_input,
+    _responses_stream,
     _translate_responses_tool_choice_to_chat,
     _translate_responses_tools_to_chat,
 )
@@ -259,6 +264,26 @@ class TestToolChoiceTranslation:
         assert _translate_responses_tool_choice_to_chat(obj) == obj
 
 
+class TestBuildChatRequest:
+    def test_parallel_tool_calls_false_is_preserved_for_passthrough_caps(self):
+        payload = ResponsesRequest(
+            input = "hi",
+            tools = [
+                {
+                    "type": "function",
+                    "name": "lookup",
+                    "parameters": {"type": "object"},
+                }
+            ],
+            parallel_tool_calls = False,
+        )
+        messages = [ChatMessage(role = "user", content = "hi")]
+
+        chat_req = _build_chat_request(payload, messages, stream = True)
+
+        assert chat_req.parallel_tool_calls is False
+
+
 # =====================================================================
 # _normalise_responses_input — multi-turn tool mapping
 # =====================================================================
@@ -424,6 +449,130 @@ class TestChatToolCallsToResponsesOutput:
         assert items[0]["arguments"] == ""
 
 
+# =====================================================================
+# Streaming Responses adapter
+# =====================================================================
+
+
+class TestResponsesStreamAdapter:
+    class _Request:
+        async def is_disconnected(self):
+            return False
+
+    @staticmethod
+    async def _collect(response):
+        chunks = []
+        async for chunk in response.body_iterator:
+            chunks.append(chunk.decode() if isinstance(chunk, bytes) else chunk)
+        return chunks
+
+    @staticmethod
+    def _payloads(lines, event_name):
+        prefix = f"event: {event_name}\n"
+        return [
+            json.loads(line.split("data: ", 1)[1].strip())
+            for line in lines
+            if line.startswith(prefix)
+        ]
+
+    def test_requests_usage_and_caps_parallel_tool_calls(self, monkeypatch):
+        import routes.inference as inf_mod
+
+        captured = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["body"] = json.loads(request.content.decode())
+            chunks = [
+                {
+                    "choices": [
+                        {
+                            "delta": {
+                                "tool_calls": [
+                                    {
+                                        "index": 0,
+                                        "id": "call_0",
+                                        "type": "function",
+                                        "function": {"name": "first", "arguments": "{}"},
+                                    },
+                                    {
+                                        "index": 1,
+                                        "id": "call_1",
+                                        "type": "function",
+                                        "function": {"name": "second", "arguments": "{}"},
+                                    },
+                                ]
+                            }
+                        }
+                    ]
+                },
+                {"choices": [], "usage": {"prompt_tokens": 2, "completion_tokens": 3}},
+            ]
+            content = "".join(f"data: {json.dumps(chunk)}\n\n" for chunk in chunks)
+            content += "data: [DONE]\n\n"
+            return httpx.Response(
+                200,
+                content = content.encode(),
+                headers = {"content-type": "text/event-stream"},
+            )
+
+        transport = httpx.MockTransport(handler)
+        real_async_client = httpx.AsyncClient
+
+        def _client(*args, **kwargs):
+            return real_async_client(
+                transport = transport,
+                timeout = kwargs.get("timeout", 600),
+            )
+
+        monkeypatch.setattr(inf_mod.httpx, "AsyncClient", _client)
+        monkeypatch.setattr(
+            inf_mod,
+            "get_llama_cpp_backend",
+            lambda: SimpleNamespace(
+                is_loaded = True,
+                is_vision = False,
+                context_length = 4096,
+                base_url = "http://llama.test",
+            ),
+        )
+
+        payload = ResponsesRequest(
+            input = "hi",
+            stream = True,
+            parallel_tool_calls = False,
+            tools = [
+                {
+                    "type": "function",
+                    "name": "first",
+                    "parameters": {"type": "object"},
+                },
+                {
+                    "type": "function",
+                    "name": "second",
+                    "parameters": {"type": "object"},
+                },
+            ],
+        )
+        messages = [ChatMessage(role = "user", content = "hi")]
+
+        async def run():
+            response = await _responses_stream(payload, messages, self._Request())
+            return await self._collect(response)
+
+        lines = asyncio.run(run())
+
+        assert captured["body"]["stream_options"] == {"include_usage": True}
+        joined = "".join(lines)
+        assert "call_0" in joined
+        assert "call_1" not in joined
+        completed = self._payloads(lines, "response.completed")[0]
+        assert completed["response"]["usage"] == {
+            "input_tokens": 2,
+            "output_tokens": 3,
+            "total_tokens": 5,
+        }
+
+
 # =====================================================================
 # Response model — ResponsesOutputFunctionCall / mixed output
 # =====================================================================
diff --git a/studio/backend/utils/api_errors.py b/studio/backend/utils/api_errors.py
new file mode 100644
index 0000000000..b1c55b61b9
--- /dev/null
+++ b/studio/backend/utils/api_errors.py
@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Error-envelope helpers for the OpenAI/Anthropic-compatible ``/v1/*`` API surface.
+
+FastAPI's defaults emit ``{"detail": ...}`` bodies (status 422 for validation,
+``exc.status_code`` for ``HTTPException``). Real OpenAI/Anthropic clients expect
+provider-specific error envelopes instead, so this module re-wraps Unsloth's own
+client-error responses on the ``/v1/*`` surface:
+
+- OpenAI surface (``/v1/chat/completions``, ``/v1/completions``, ``/v1/models``,
+  ``/v1/responses``, ``/v1/embeddings``, ...)::
+
+      {"error": {"message": str, "type": str, "param": None|str, "code": None|str}}
+
+- Anthropic surface (any path starting with ``/v1/messages``)::
+
+      {"type": "error", "error": {"type": str, "message": str}}
+
+CRITICAL: the exception handlers installed by :func:`install_api_error_handlers`
+are global, but they ONLY transform responses for paths that start with ``/v1/``.
+For every other path (``/api/...``, frontend routes) they reproduce FastAPI's
+default behavior byte-for-byte, because the Studio frontend depends on the
+``{"detail": ...}`` shape for ``/api/*``.
+
+Public contract (other modules depend on these):
+
+- ``OPENAI_TYPE_BY_STATUS`` / ``ANTHROPIC_TYPE_BY_STATUS``: status -> type maps.
+- ``openai_error_body(message, *, status=400, err_type=None, code=None, param=None)``
+- ``anthropic_error_body(message, *, status=400, err_type=None)``
+- ``is_anthropic_path(path)``
+- ``error_body_for_path(path, message, *, status, err_type=None, code=None, param=None)``
+- ``install_api_error_handlers(app)``
+"""
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.utils import is_body_allowed_for_status_code
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+
+# Status-code -> error ``type`` string for the OpenAI error envelope.
+OPENAI_TYPE_BY_STATUS = {
+    400: "invalid_request_error",
+    401: "authentication_error",
+    403: "permission_error",
+    404: "not_found_error",
+    409: "conflict_error",
+    413: "invalid_request_error",
+    422: "invalid_request_error",
+    429: "rate_limit_error",
+    500: "api_error",
+    502: "api_error",
+    503: "api_error",
+}
+
+# Status-code -> error ``type`` string for the Anthropic error envelope.
+ANTHROPIC_TYPE_BY_STATUS = {
+    400: "invalid_request_error",
+    401: "authentication_error",
+    403: "permission_error",
+    404: "not_found_error",
+    409: "conflict_error",
+    413: "request_too_large",
+    422: "invalid_request_error",
+    429: "rate_limit_error",
+    500: "api_error",
+    502: "api_error",
+    503: "api_error",
+    529: "overloaded_error",
+}
+
+
+def openai_error_body(
+    message,
+    *,
+    status = 400,
+    err_type = None,
+    code = None,
+    param = None,
+) -> dict:
+    """Build an OpenAI-style error envelope.
+
+    Returns ``{"error": {"message", "type", "param", "code"}}``. The ``param``
+    and ``code`` keys are always present (value may be ``None``). ``err_type``
+    defaults to :data:`OPENAI_TYPE_BY_STATUS` for ``status`` (``"api_error"``
+    fallback).
+    """
+    return {
+        "error": {
+            "message": str(message),
+            "type": err_type or OPENAI_TYPE_BY_STATUS.get(status, "api_error"),
+            "param": param,
+            "code": code,
+        }
+    }
+
+
+def anthropic_error_body(
+    message,
+    *,
+    status = 400,
+    err_type = None,
+) -> dict:
+    """Build an Anthropic-style error envelope.
+
+    Returns ``{"type": "error", "request_id": None, "error": {"type", "message"}}``.
+    ``request_id`` is a required (nullable) field on the spec's ErrorResponse;
+    Studio has no request-id system, so it is null. ``err_type`` defaults to
+    :data:`ANTHROPIC_TYPE_BY_STATUS` for ``status`` (``"api_error"`` fallback).
+    """
+    return {
+        "type": "error",
+        "request_id": None,
+        "error": {
+            "type": err_type or ANTHROPIC_TYPE_BY_STATUS.get(status, "api_error"),
+            "message": str(message),
+        },
+    }
+
+
+def is_anthropic_path(path: str) -> bool:
+    """True iff ``path`` belongs to the Anthropic surface (``/v1/messages*``)."""
+    return path.startswith("/v1/messages")
+
+
+def error_body_for_path(
+    path,
+    message,
+    *,
+    status,
+    err_type = None,
+    code = None,
+    param = None,
+) -> dict:
+    """Dispatch to the correct envelope builder based on ``path``.
+
+    Anthropic surface paths use :func:`anthropic_error_body` (``code``/``param``
+    are not part of that envelope and are ignored); all other ``/v1/*`` paths use
+    :func:`openai_error_body`.
+    """
+    if is_anthropic_path(path):
+        return anthropic_error_body(message, status = status, err_type = err_type)
+    return openai_error_body(message, status = status, err_type = err_type, code = code, param = param)
+
+
+def _summarize_validation_errors(errors) -> tuple:
+    """Derive a readable one-line message and (optional) body param from ``exc.errors()``.
+
+    Returns ``(summary, param)``. ``summary`` is a human-readable string like
+    ``"messages: Field required"``. ``param`` is the offending body field name when
+    one can be extracted (used as the OpenAI envelope ``param``), else ``None``.
+
+    Malformed-JSON bodies surface here as ``type == "json_invalid"`` and get a
+    dedicated message.
+    """
+    if not errors:
+        return "Invalid request", None
+
+    first = errors[0]
+    if first.get("type") == "json_invalid":
+        return "Invalid JSON in request body", None
+
+    loc = first.get("loc", ()) or ()
+    msg = first.get("msg", "Invalid request")
+
+    # Extract the body field name (the loc element after a leading "body").
+    param = None
+    loc_parts = [p for p in loc if p not in ("body",)]
+    if loc and loc[0] == "body" and loc_parts:
+        # First non-"body" element that is a field name (string).
+        for part in loc_parts:
+            if isinstance(part, str):
+                param = part
+                break
+
+    label = ".".join(str(p) for p in loc_parts) if loc_parts else ".".join(str(p) for p in loc)
+    summary = f"{label}: {msg}" if label else str(msg)
+    return summary, param
+
+
+def install_api_error_handlers(app) -> None:
+    """Register validation + HTTPException handlers that emit ``/v1/*`` envelopes.
+
+    Both handlers are global but only transform responses for paths starting with
+    ``/v1/``. Non-``/v1/`` paths reproduce FastAPI's default ``{"detail": ...}``
+    behavior exactly so the Studio frontend keeps working.
+    """
+
+    @app.exception_handler(RequestValidationError)
+    async def _handle_validation_error(request, exc):
+        path = request.url.path
+        if path.startswith("/v1/"):
+            summary, param = _summarize_validation_errors(exc.errors())
+            return JSONResponse(
+                status_code = 400,
+                content = error_body_for_path(path, summary, status = 400, param = param),
+            )
+        # Default FastAPI behavior for every other path.
+        return JSONResponse(
+            status_code = 422,
+            content = {"detail": jsonable_encoder(exc.errors())},
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _handle_http_exception(request, exc):
+        path = request.url.path
+        headers = getattr(exc, "headers", None)
+        # Statuses like 204/304/1xx must not carry a body — mirror FastAPI's
+        # default http_exception_handler, which returns a bodiless Response.
+        if not is_body_allowed_for_status_code(exc.status_code):
+            return Response(status_code = exc.status_code, headers = headers)
+        if path.startswith("/v1/"):
+            detail = exc.detail
+            # Already a fully-formed envelope: pass through untouched.
+            if isinstance(detail, dict) and ("error" in detail or detail.get("type") == "error"):
+                return JSONResponse(
+                    status_code = exc.status_code,
+                    content = detail,
+                    headers = headers,
+                )
+            # A dict carrying our individual fields.
+            if isinstance(detail, dict):
+                message = detail.get("message", detail)
+                err_type = detail.get("type")
+                code = detail.get("code")
+                param = detail.get("param")
+            else:
+                # Plain message string (the common HTTPException case).
+                message = detail
+                err_type = None
+                code = None
+                param = None
+            return JSONResponse(
+                status_code = exc.status_code,
+                content = error_body_for_path(
+                    path,
+                    message,
+                    status = exc.status_code,
+                    err_type = err_type,
+                    code = code,
+                    param = param,
+                ),
+                headers = headers,
+            )
+        # Default FastAPI behavior for every other path.
+        return JSONResponse(
+            status_code = exc.status_code,
+            content = {"detail": exc.detail},
+            headers = headers,
+        )
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 34cae518e3..91a9bffa36 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -2339,6 +2339,9 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             model: params.checkpoint,
             messages: outboundMessages,
             stream: true,
+            // Opt into the trailing usage chunk so the context-usage bar
+            // and tok/s readout populate (backend gates it on include_usage).
+            stream_options: { include_usage: true },
             temperature: params.temperature,
             top_p: params.topP,
             max_tokens: params.maxTokens,
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 48efdbba2e..a69c216891 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -309,6 +309,13 @@ export interface OpenAIChatCompletionsRequest {
    * See https://platform.claude.com/docs/en/build-with-claude/fast-mode
    */
   fast_mode?: boolean | null;
+  /**
+   * Opt into the OpenAI-standard trailing usage chunk on streams
+   * (`choices: []` with `usage` + llama-server `timings` populated). The
+   * backend only emits it when `include_usage` is set; the local chat UI
+   * sends it so the context-usage bar and tok/s readout populate.
+   */
+  stream_options?: { include_usage?: boolean } | null;
 }
 
 export interface OpenAIChatDelta {

From 2554636ded46f87430cac6c20a35c828801585c8 Mon Sep 17 00:00:00 2001
From: Wasim Yousef Said <wasimysdev@gmail.com>
Date: Tue, 9 Jun 2026 18:11:38 +0200
Subject: [PATCH 124/222] Studio: follow-up fix for GGUF developer prompts
 (#6115)

* Studio: merge developer prompts for GGUF chat

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/routes/inference.py            | 13 ++--
 .../tests/test_openai_tool_passthrough.py     | 60 +++++++++++++++++++
 2 files changed, 68 insertions(+), 5 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index a2e0e5a811..81bc9ff628 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -2050,8 +2050,8 @@ def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[s
     first_image_b64: Optional[str] = None
 
     for msg in messages:
-        # ── System messages → extract as system_prompt ────────
-        if msg.role == "system":
+        # ── System / developer messages → extract as system_prompt ────────
+        if msg.role in ("system", "developer"):
             if isinstance(msg.content, str):
                 system_parts.append(msg.content)
             elif isinstance(msg.content, list):
@@ -3053,6 +3053,7 @@ async def openai_chat_completions(
             payload,
             llama_backend.is_vision,
         )
+        gguf_messages = _set_or_prepend_system_message(gguf_messages, system_prompt)
         image_b64 = None
 
         cancel_event = threading.Event()
@@ -5190,9 +5191,9 @@ def _set_or_prepend_system_message(
     if not system_prompt:
         return safe_messages
 
-    # Drop existing system turns so the backend never sees duplicate or
-    # conflicting system instructions, then prepend the resolved prompt.
-    others = [dict(msg) for msg in safe_messages if msg.get("role") != "system"]
+    # Drop existing system/developer turns so the backend never sees duplicate
+    # or conflicting system instructions, then prepend the resolved prompt.
+    others = [dict(msg) for msg in safe_messages if msg.get("role") not in ("system", "developer")]
     return [{"role": "system", "content": system_prompt}, *others]
 
 
@@ -6415,6 +6416,8 @@ def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
     leak to the backend.
     """
     messages = _openai_messages_for_passthrough(payload)
+    system_prompt, _, _ = _extract_content_parts(payload.messages)
+    messages = _set_or_prepend_system_message(messages, system_prompt)
     tool_choice = payload.tool_choice if payload.tool_choice is not None else "auto"
     # When the caller asked for a specific reasoning mode, forward it via
     # chat_template_kwargs so the Jinja template renders with (or without) the
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 495ebc434d..db4c07cdc8 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -33,6 +33,7 @@ from core.inference.anthropic_compat import (
     anthropic_tool_choice_to_openai,
 )
 from routes.inference import (
+    _build_openai_passthrough_body,
     _build_passthrough_payload,
     _clamp_finish_reason,
     _effective_max_tokens,
@@ -634,6 +635,24 @@ class TestBuildPassthroughPayloadToolChoice:
         assert body.get("repeat_penalty") == 1.1
         assert "repetition_penalty" not in body
 
+    def test_passthrough_body_merges_system_and_developer_messages(self):
+        payload = ChatCompletionRequest(
+            model = "default",
+            messages = [
+                {"role": "system", "content": "original system"},
+                {"role": "developer", "content": "developer rules"},
+                {"role": "user", "content": "hi"},
+            ],
+            tools = self._args()["openai_tools"],
+        )
+
+        body = _build_openai_passthrough_body(payload, backend_ctx = 4096)
+
+        assert body["messages"] == [
+            {"role": "system", "content": "original system\n\ndeveloper rules"},
+            {"role": "user", "content": "hi"},
+        ]
+
 
 # =====================================================================
 # OpenAI API compatibility helpers — verified spec edge cases
@@ -1092,6 +1111,47 @@ class TestGgufVisionToolRouting:
 
         assert captured["kwargs"]["disable_parallel_tool_use"] is True
 
+    def test_standard_gguf_merges_system_and_developer_messages(self, monkeypatch):
+        import routes.inference as inf_mod
+
+        captured = {}
+
+        def _generate(**kwargs):
+            captured["messages"] = kwargs["messages"]
+            yield "done"
+            yield {
+                "type": "metadata",
+                "usage": {"prompt_tokens": 3, "completion_tokens": 1, "total_tokens": 4},
+                "finish_reason": "stop",
+            }
+
+        backend = SimpleNamespace(
+            is_loaded = True,
+            is_vision = False,
+            supports_tools = False,
+            model_identifier = "test-gguf",
+            generate_chat_completion = _generate,
+        )
+        monkeypatch.setattr(inf_mod, "get_llama_cpp_backend", lambda: backend)
+
+        payload = ChatCompletionRequest(
+            model = "default",
+            messages = [
+                {"role": "system", "content": "original system"},
+                {"role": "developer", "content": "developer rules"},
+                {"role": "user", "content": "hi"},
+            ],
+        )
+
+        self._drive(
+            openai_chat_completions(payload, request = self._Request(), current_subject = "test")
+        )
+
+        assert captured["messages"] == [
+            {"role": "system", "content": "original system\n\ndeveloper rules"},
+            {"role": "user", "content": "hi"},
+        ]
+
     @pytest.mark.parametrize(
         ("seed", "expected"),
         [

From 436525d6de1dbbee2ef54ac3e010ee311616372b Mon Sep 17 00:00:00 2001
From: Nilay <118994073+NilayYadav@users.noreply.github.com>
Date: Wed, 10 Jun 2026 02:13:24 +0530
Subject: [PATCH 125/222] Studio: stop the providers dialog from resetting
 custom provider form state (#6051)

* fix custom provider state

* Address provider seeding review feedback

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: imagineer99 <samleejackson0@gmail.com>
---
 studio/frontend/src/features/chat/chat-providers-dialog.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
index 42f8e56ac5..e35a8e35e0 100644
--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
@@ -212,6 +212,7 @@ export function ChatProvidersSettings({
   onProvidersChange,
 }: ChatProvidersSettingsProps) {
   const providersRef = useRef(providers);
+  const seededProviderTypeRef = useRef<string | null>(null);
   const [page, setPage] = useState<"list" | "form">("list");
   const [providerType, setProviderType] = useState<string>("");
   const [apiKey, setApiKey] = useState("");
@@ -317,6 +318,8 @@ export function ChatProvidersSettings({
 
   useEffect(() => {
     if (!providerType || editingProviderId) return;
+    if (seededProviderTypeRef.current === providerType) return;
+    seededProviderTypeRef.current = providerType;
     const entry = registryByType.get(providerType);
     if (!entry) {
       if (isCustomProviderType(providerType)) {
@@ -363,7 +366,8 @@ export function ChatProvidersSettings({
         setProviderType((current) => {
           if (
             current &&
-            registryRows.some((entry) => entry.provider_type === current)
+            (isCustomProviderType(current) ||
+              registryRows.some((entry) => entry.provider_type === current))
           ) {
             return current;
           }

From 8848a310df7172c15b72d0e752ebc24da08c53e9 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Tue, 9 Jun 2026 21:17:04 -0700
Subject: [PATCH 126/222] Studio: clean-room compact RAG (knowledge bases,
 hybrid search, fast indexing) (#5910)

Adds a self-contained RAG stack to Studio: knowledge bases with chunked indexing, hybrid (dense + lexical) retrieval, and an automatic first-pass context inject into chat. Embeddings run through a local llama-server GGUF backend (default unsloth/bge-small-en-v1.5-GGUF) with a sentence-transformers fallback. The chat tool loop gains a search_knowledge_base tool, a per-turn re-search cap, and source citation, layered on top of the shared ToolLoopController.
---
 studio/backend/core/inference/inference.py    |    2 +
 studio/backend/core/inference/llama_cpp.py    |   41 +-
 studio/backend/core/inference/orchestrator.py |    2 +
 .../core/inference/safetensors_agentic.py     |   47 +-
 .../core/inference/tool_call_parser.py        |    9 +
 .../core/inference/tool_loop_controller.py    |    8 +-
 studio/backend/core/inference/tools.py        |  246 +-
 studio/backend/core/rag/__init__.py           |   16 +
 studio/backend/core/rag/captioner.py          |  107 +
 studio/backend/core/rag/chunking.py           |  121 +
 studio/backend/core/rag/config.py             |   41 +
 studio/backend/core/rag/embed_llama_server.py |  448 ++++
 studio/backend/core/rag/embeddings.py         |  297 +++
 studio/backend/core/rag/ingestion.py          |  251 ++
 studio/backend/core/rag/locators.py           |  182 ++
 studio/backend/core/rag/parsers.py            |  216 ++
 studio/backend/core/rag/retrieval.py          |   96 +
 studio/backend/core/rag/store.py              |  261 +++
 studio/backend/core/rag/tool.py               |  193 ++
 studio/backend/main.py                        |   20 +
 studio/backend/models/inference.py            |   10 +
 studio/backend/requirements/studio.txt        |    5 +
 studio/backend/routes/__init__.py             |    5 +
 studio/backend/routes/inference.py            |   81 +
 studio/backend/routes/models.py               |   17 +
 studio/backend/routes/prompts.py              |  101 +
 studio/backend/routes/rag.py                  |  456 ++++
 studio/backend/storage/rag_db.py              |  153 ++
 studio/backend/storage/studio_db.py           |  189 ++
 studio/backend/tests/conftest.py              |   68 +
 studio/backend/tests/test_desktop_auth.py     |    4 +
 studio/backend/tests/test_rag_captioning.py   |  105 +
 studio/backend/tests/test_rag_chunking.py     |   69 +
 .../tests/test_rag_embed_llama_server.py      |  448 ++++
 studio/backend/tests/test_rag_embeddings.py   |  222 ++
 studio/backend/tests/test_rag_ingestion.py    |  139 ++
 studio/backend/tests/test_rag_preview.py      |  174 ++
 studio/backend/tests/test_rag_retrieval.py    |  432 ++++
 studio/backend/tests/test_rag_store.py        |  125 +
 .../tests/test_safetensors_tool_loop.py       |   40 +
 studio/backend/utils/paths/__init__.py        |    9 +
 studio/backend/utils/paths/storage_roots.py   |   15 +
 studio/frontend/package-lock.json             |  348 +++
 studio/frontend/package.json                  |    1 +
 .../frontend/src/components/app-sidebar.tsx   |  155 +-
 .../components/assistant-ui/citation-utils.ts |  105 +
 .../assistant-ui/model-selector/pickers.tsx   |   11 +-
 .../components/assistant-ui/rag-sources.tsx   |   46 +
 .../src/components/assistant-ui/thread.tsx    |  513 ++++-
 .../assistant-ui/tool-ui-knowledge-base.tsx   |  141 ++
 .../src/components/ui/dropdown-menu.tsx       |    2 +-
 .../src/features/chat/api/chat-adapter.ts     |   44 +-
 .../src/features/chat/api/prompts-api.ts      |   91 +
 .../frontend/src/features/chat/chat-page.tsx  |   17 +-
 .../src/features/chat/chat-settings-sheet.tsx |    7 +
 .../chat/hooks/use-rag-tool-available.ts      |   18 +
 .../src/features/chat/mcp-composer-button.tsx |    7 +-
 .../src/features/chat/projects-page.tsx       |  228 +-
 .../prompt-storage/prompt-storage-dialog.tsx  | 2009 +++++++++++++++++
 .../src/features/chat/shared-composer.tsx     |  316 ++-
 .../chat/stores/chat-runtime-store.ts         |  147 ++
 .../src/features/chat/thread-sidebar.tsx      |  241 +-
 .../frontend/src/features/chat/types/api.ts   |   11 +
 .../components/steps/model-selection-step.tsx |    8 +-
 .../frontend/src/features/rag/api/rag-api.ts  |  203 ++
 .../rag/components/document-preview-mount.tsx |   32 +
 .../rag/components/document-preview-sheet.tsx |  474 ++++
 .../rag/components/document-status-chip.tsx   |   60 +
 .../knowledge-base-composer-button.tsx        |  198 ++
 .../rag/components/knowledge-base-dialog.tsx  |  334 +++
 .../features/rag/components/preview-store.ts  |   39 +
 .../components/retrieval-settings-section.tsx |  206 ++
 .../rag/components/thread-documents-bar.tsx   |  215 ++
 .../rag/components/use-rag-documents.ts       |  352 +++
 studio/frontend/src/features/rag/index.ts     |    8 +
 studio/frontend/src/features/rag/types/rag.ts |   70 +
 .../studio/sections/model-section.tsx         |    8 +-
 studio/frontend/src/index.css                 |   10 +
 studio/frontend/src/lib/model-size.ts         |   23 +
 79 files changed, 12022 insertions(+), 147 deletions(-)
 create mode 100644 studio/backend/core/rag/__init__.py
 create mode 100644 studio/backend/core/rag/captioner.py
 create mode 100644 studio/backend/core/rag/chunking.py
 create mode 100644 studio/backend/core/rag/config.py
 create mode 100644 studio/backend/core/rag/embed_llama_server.py
 create mode 100644 studio/backend/core/rag/embeddings.py
 create mode 100644 studio/backend/core/rag/ingestion.py
 create mode 100644 studio/backend/core/rag/locators.py
 create mode 100644 studio/backend/core/rag/parsers.py
 create mode 100644 studio/backend/core/rag/retrieval.py
 create mode 100644 studio/backend/core/rag/store.py
 create mode 100644 studio/backend/core/rag/tool.py
 create mode 100644 studio/backend/routes/prompts.py
 create mode 100644 studio/backend/routes/rag.py
 create mode 100644 studio/backend/storage/rag_db.py
 create mode 100644 studio/backend/tests/test_rag_captioning.py
 create mode 100644 studio/backend/tests/test_rag_chunking.py
 create mode 100644 studio/backend/tests/test_rag_embed_llama_server.py
 create mode 100644 studio/backend/tests/test_rag_embeddings.py
 create mode 100644 studio/backend/tests/test_rag_ingestion.py
 create mode 100644 studio/backend/tests/test_rag_preview.py
 create mode 100644 studio/backend/tests/test_rag_retrieval.py
 create mode 100644 studio/backend/tests/test_rag_store.py
 create mode 100644 studio/frontend/src/components/assistant-ui/citation-utils.ts
 create mode 100644 studio/frontend/src/components/assistant-ui/rag-sources.tsx
 create mode 100644 studio/frontend/src/components/assistant-ui/tool-ui-knowledge-base.tsx
 create mode 100644 studio/frontend/src/features/chat/api/prompts-api.ts
 create mode 100644 studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts
 create mode 100644 studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
 create mode 100644 studio/frontend/src/features/rag/api/rag-api.ts
 create mode 100644 studio/frontend/src/features/rag/components/document-preview-mount.tsx
 create mode 100644 studio/frontend/src/features/rag/components/document-preview-sheet.tsx
 create mode 100644 studio/frontend/src/features/rag/components/document-status-chip.tsx
 create mode 100644 studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
 create mode 100644 studio/frontend/src/features/rag/components/knowledge-base-dialog.tsx
 create mode 100644 studio/frontend/src/features/rag/components/preview-store.ts
 create mode 100644 studio/frontend/src/features/rag/components/retrieval-settings-section.tsx
 create mode 100644 studio/frontend/src/features/rag/components/thread-documents-bar.tsx
 create mode 100644 studio/frontend/src/features/rag/components/use-rag-documents.ts
 create mode 100644 studio/frontend/src/features/rag/index.ts
 create mode 100644 studio/frontend/src/features/rag/types/rag.ts
 create mode 100644 studio/frontend/src/lib/model-size.ts

diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index 8e202d161a..55c2c551a3 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -758,6 +758,7 @@ class InferenceBackend:
         auto_heal_tool_calls: bool = True,
         tool_call_timeout: int = 300,
         session_id: Optional[str] = None,
+        rag_scope: Optional[dict] = None,
     ):
         """Run an agentic tool loop on top of ``generate_chat_response``.
 
@@ -807,6 +808,7 @@ class InferenceBackend:
             max_tool_iterations = max_tool_iterations,
             tool_call_timeout = tool_call_timeout,
             session_id = session_id,
+            rag_scope = rag_scope,
         )
 
     def generate_chat_response(
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index ec3a216258..953c1d3141 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -50,6 +50,8 @@ from utils.subprocess_compat import (
     windows_hidden_subprocess_kwargs as _windows_hidden_subprocess_kwargs,
 )
 from core.inference.tool_call_parser import (
+    RAG_MAX_SEARCHES_PER_TURN,
+    RAG_SEARCH_CAP_NUDGE,
     TOOL_XML_SIGNALS,
     parse_tool_calls_from_text as _shared_parse_tool_calls_from_text,
 )
@@ -4303,6 +4305,7 @@ class LlamaCppBackend:
         auto_heal_tool_calls: bool = True,
         tool_call_timeout: int = 300,
         session_id: Optional[str] = None,
+        rag_scope: Optional[dict] = None,
         seed: Optional[int] = None,
         disable_parallel_tool_use: bool = False,
     ) -> Generator[dict, None, None]:
@@ -4314,12 +4317,21 @@ class LlamaCppBackend:
           {"type": "content", "text": "token"}            -- streamed content tokens (cumulative)
           {"type": "reasoning", "text": "token"}          -- streamed reasoning tokens (cumulative)
         """
-        from core.inference.tools import execute_tool
+        from core.inference.tools import build_rag_autoinject, execute_tool
 
         if not self.is_loaded:
             raise RuntimeError("llama-server is not loaded")
 
         conversation = list(messages)
+
+        # Forced first-pass RAG so a doc question doesn't lose to web_search. Emits
+        # the same tool card + citations a real call would.
+        _auto = build_rag_autoinject(conversation, rag_scope)
+        if _auto:
+            for _ev in _auto["events"]:
+                yield _ev
+            conversation.extend(_auto["messages"])
+
         url = f"{self.base_url}/v1/chat/completions"
         _accumulated_completion_tokens = 0
         _accumulated_predicted_ms = 0.0
@@ -4356,6 +4368,9 @@ class LlamaCppBackend:
 
         _MAX_BUFFER_CHARS = 32
         _append_budget_exhausted_nudge = True
+        # RAG: cap knowledge-base searches per assistant turn. The controller is
+        # tool-agnostic, so this gate stays in the loop.
+        _kb_search_count = 0
 
         # ── Re-prompt on plan-without-action ─────────────────
         # When the model describes what it intends to do (forward-looking
@@ -4996,13 +5011,23 @@ class LlamaCppBackend:
                     yield decision.tool_start_event()
 
                     _effective_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
-                    result = execute_tool(
-                        decision.tool_name,
-                        decision.arguments,
-                        cancel_event = cancel_event,
-                        timeout = _effective_timeout,
-                        session_id = session_id,
-                    )
+                    # RAG: cap paraphrased KB re-searches that slip past the dup guard.
+                    if (
+                        decision.tool_name == "search_knowledge_base"
+                        and _kb_search_count >= RAG_MAX_SEARCHES_PER_TURN
+                    ):
+                        result = RAG_SEARCH_CAP_NUDGE
+                    else:
+                        result = execute_tool(
+                            decision.tool_name,
+                            decision.arguments,
+                            cancel_event = cancel_event,
+                            timeout = _effective_timeout,
+                            session_id = session_id,
+                            rag_scope = rag_scope,
+                        )
+                        if decision.tool_name == "search_knowledge_base":
+                            _kb_search_count += 1
                     completion = tool_controller.record_result(decision, result)
                     yield completion.tool_end_event()
                     conversation.append(completion.tool_message())
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 74a011093a..e394b342f0 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -821,6 +821,7 @@ class InferenceOrchestrator:
         auto_heal_tool_calls: bool = True,
         tool_call_timeout: int = 300,
         session_id: Optional[str] = None,
+        rag_scope: Optional[dict] = None,
         use_adapter: Optional[Union[bool, str]] = None,
         stats_holder: Optional[dict] = None,
         **_unused,
@@ -881,6 +882,7 @@ class InferenceOrchestrator:
             max_tool_iterations = max_tool_iterations,
             tool_call_timeout = tool_call_timeout,
             session_id = session_id,
+            rag_scope = rag_scope,
         )
 
     def generate_with_adapter_control(
diff --git a/studio/backend/core/inference/safetensors_agentic.py b/studio/backend/core/inference/safetensors_agentic.py
index 7d498a170d..7942edb6d7 100644
--- a/studio/backend/core/inference/safetensors_agentic.py
+++ b/studio/backend/core/inference/safetensors_agentic.py
@@ -23,6 +23,8 @@ from loggers import get_logger
 from core.inference.tool_call_parser import (
     _TOOL_ALL_PATS,
     BUDGET_EXHAUSTED_NUDGE,
+    RAG_MAX_SEARCHES_PER_TURN,
+    RAG_SEARCH_CAP_NUDGE,
     TOOL_XML_SIGNALS,
     parse_tool_calls_from_text,
     strip_tool_markup,
@@ -143,6 +145,7 @@ def run_safetensors_tool_loop(
     max_tool_iterations: int = 25,
     tool_call_timeout: int = 300,
     session_id: Optional[str] = None,
+    rag_scope: Optional[dict] = None,
 ) -> Generator[dict, None, None]:
     """Drive an agentic tool loop on top of a cumulative-text generator.
 
@@ -167,11 +170,23 @@ def run_safetensors_tool_loop(
     * ``{"type": "tool_end", "tool_name", "tool_call_id", "result"}``
     """
     conversation = list(messages)
+
+    # Forced first-pass RAG (mirrors the GGUF loop) so doc Qs don't lose to web_search.
+    from core.inference.tools import build_rag_autoinject
+
+    _auto = build_rag_autoinject(conversation, rag_scope)
+    if _auto:
+        for _ev in _auto["events"]:
+            yield _ev
+        conversation.extend(_auto["messages"])
+
     unrestricted_tools = not tools
     tool_controller = ToolLoopController(
         tools = None if unrestricted_tools else tools,
         auto_heal_tool_calls = auto_heal_tool_calls,
     )
+    # RAG: cap knowledge-base searches per assistant turn (controller-agnostic).
+    kb_search_count = 0
     final_attempt_done = False
     next_call_id = 0
 
@@ -498,17 +513,27 @@ def run_safetensors_tool_loop(
             yield decision.tool_start_event()
 
             eff_timeout = None if tool_call_timeout >= 9999 else tool_call_timeout
-            try:
-                result = execute_tool(
-                    decision.tool_name,
-                    decision.arguments,
-                    cancel_event = cancel_event,
-                    timeout = eff_timeout,
-                    session_id = session_id,
-                )
-            except Exception as exc:
-                logger.exception("Tool %s raised: %s", decision.tool_name, exc)
-                result = f"Error: tool raised an exception: {exc}"
+            # RAG: cap paraphrased KB re-searches that slip past the dup guard.
+            if (
+                decision.tool_name == "search_knowledge_base"
+                and kb_search_count >= RAG_MAX_SEARCHES_PER_TURN
+            ):
+                result = RAG_SEARCH_CAP_NUDGE
+            else:
+                try:
+                    result = execute_tool(
+                        decision.tool_name,
+                        decision.arguments,
+                        cancel_event = cancel_event,
+                        timeout = eff_timeout,
+                        session_id = session_id,
+                        rag_scope = rag_scope,
+                    )
+                except Exception as exc:
+                    logger.exception("Tool %s raised: %s", decision.tool_name, exc)
+                    result = f"Error: tool raised an exception: {exc}"
+                if decision.tool_name == "search_knowledge_base":
+                    kb_search_count += 1
 
             completion = tool_controller.record_result(decision, result)
             yield completion.tool_end_event()
diff --git a/studio/backend/core/inference/tool_call_parser.py b/studio/backend/core/inference/tool_call_parser.py
index ccb777db1c..8d5d45269e 100644
--- a/studio/backend/core/inference/tool_call_parser.py
+++ b/studio/backend/core/inference/tool_call_parser.py
@@ -64,6 +64,15 @@ BUDGET_EXHAUSTED_NUDGE = (
     "any more tools."
 )
 
+# The exact-args dup guard misses paraphrased re-searches, so also cap executed
+# KB searches per turn, then nudge.
+RAG_MAX_SEARCHES_PER_TURN = 3
+RAG_SEARCH_CAP_NUDGE = (
+    "You have already searched the knowledge base several times this turn. "
+    "Do not search again. Answer the question using the passages already "
+    "retrieved above; if they do not contain the answer, say so plainly."
+)
+
 
 # Pre-compiled patterns reused by ``parse_tool_calls_from_text``.
 _TC_JSON_START_RE = re.compile(r"<tool_call>\s*\{")
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
index 667ec7a33e..cb751ede3d 100644
--- a/studio/backend/core/inference/tool_loop_controller.py
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -234,9 +234,11 @@ def is_tool_error(result: str) -> bool:
 
 
 def strip_result_for_model(result: str) -> str:
-    """Remove frontend-only image sentinels before feeding the model."""
-    if "__IMAGES__:" in result:
-        return result.split("__IMAGES__:", 1)[0].rstrip()
+    """Remove frontend-only sentinels (image paths, RAG source map) before
+    feeding the result back to the model."""
+    for sentinel in ("__IMAGES__:", "__RAG_SOURCES__:"):
+        if sentinel in result:
+            result = result.split(sentinel, 1)[0].rstrip()
     return result
 
 
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index 023cab3e5e..b27fa6ff73 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -39,6 +39,9 @@ logger = get_logger(__name__)
 
 _EXEC_TIMEOUT = 300  # 5 minutes
 
+# Splits the UI source-map from the result; loops strip it (like __IMAGES__).
+RAG_SOURCES_SENTINEL = "\n__RAG_SOURCES__:"
+
 # Import these at module level so the preexec_fn closure triggers no imports in
 # the forked child (which can deadlock multi-threaded servers).
 _libc = None
@@ -539,7 +542,41 @@ RENDER_HTML_TOOL = {
     },
 }
 
-ALL_TOOLS = [WEB_SEARCH_TOOL, PYTHON_TOOL, TERMINAL_TOOL, RENDER_HTML_TOOL]
+# Duplicated (not imported from core.rag.tool) so the registry never pulls in
+# the RAG stack; dispatch imports it lazily.
+SEARCH_KNOWLEDGE_BASE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "search_knowledge_base",
+        "description": (
+            "Search the user's uploaded documents and knowledge bases for "
+            "relevant passages. Use this whenever the question may be answered "
+            "by the attached documents, then cite the returned chunks."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Natural-language search query.",
+                },
+                "top_k": {
+                    "type": "integer",
+                    "description": "Max chunks to return.",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+}
+
+ALL_TOOLS = [
+    WEB_SEARCH_TOOL,
+    PYTHON_TOOL,
+    TERMINAL_TOOL,
+    RENDER_HTML_TOOL,
+    SEARCH_KNOWLEDGE_BASE_TOOL,
+]
 
 
 # OpenAI's function.name regex ^[a-zA-Z0-9_-]{1,64}$, enforced before streaming.
@@ -652,14 +689,19 @@ def execute_tool(
     cancel_event = None,
     timeout: int | None = _TIMEOUT_UNSET,
     session_id: str | None = None,
+    rag_scope: dict | None = None,
 ) -> str:
     """Execute a tool by name with the given arguments; returns a string.
 
     ``timeout``: int seconds, ``None`` = no limit, unset = ``_EXEC_TIMEOUT``.
     ``session_id``: optional ID for per-conversation sandbox isolation.
+    ``rag_scope``: hidden per-request RAG context the model never sees; consumed
+    by ``search_knowledge_base``.
     """
     logger.info(f"execute_tool: name={name}, session_id={session_id}, timeout={timeout}")
     effective_timeout = _EXEC_TIMEOUT if timeout is _TIMEOUT_UNSET else timeout
+    if name == "search_knowledge_base":
+        return _search_knowledge_base(arguments, rag_scope)
     if name == "render_html":
         return _render_html_result(arguments)
     if name.startswith(MCP_TOOL_PREFIX):
@@ -696,6 +738,208 @@ def execute_tool(
     return f"Unknown tool: {name}"
 
 
+def _opt_int(v) -> int | None:
+    try:
+        return int(v) if v is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _scope_retrieval_kwargs(scope: dict) -> dict:
+    """Retrieval mode from rag_scope; candidate pools and RRF come from config."""
+    mode = scope.get("mode")
+    return {"mode": mode if mode in ("hybrid", "dense", "lexical") else "hybrid"}
+
+
+def _search_knowledge_base(arguments: dict, rag_scope: dict | None) -> str:
+    """Run the RAG search bound to the hidden per-request ``rag_scope`` (the model
+    supplies only ``query``/``top_k``). Lazy import; missing sqlite-vec degrades
+    to a friendly message."""
+    scope = rag_scope or {}
+    query = (arguments or {}).get("query", "")
+    if not query or not str(query).strip():
+        return "Error: query is empty."
+    try:
+        from storage import rag_db
+        if not rag_db.RAG_AVAILABLE:
+            return "Knowledge base search is unavailable on this server."
+        from core.rag.tool import search_knowledge_base_with_sources
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("RAG tool unavailable: %s", exc)
+        return "Knowledge base search is unavailable on this server."
+
+    top_k = _opt_int((arguments or {}).get("top_k") or scope.get("default_top_k"))
+    text, sources = search_knowledge_base_with_sources(
+        query = str(query),
+        scope_kb_id = scope.get("kb_id"),
+        scope_thread_id = scope.get("thread_id"),
+        top_k = top_k,
+        **_scope_retrieval_kwargs(scope),
+    )
+    # Append the UI source-map after the sentinel; loops strip it before the model.
+    if sources:
+        import json as _json
+        return text + RAG_SOURCES_SENTINEL + _json.dumps(sources, ensure_ascii = False)
+    return text
+
+
+# Forced first-pass RAG retrieval: a high cosine floor keeps it precise (fires on
+# on-topic queries, skips weak ones) and helps small models that under-call the tool.
+# Tunable via RAG_AUTOINJECT_MIN_SCORE.
+_AUTOINJECT_DEFAULT_FLOOR = 0.70
+
+
+def _autoinject_enabled() -> bool:
+    return os.environ.get("RAG_AUTOINJECT", "1").strip().lower() not in (
+        "0",
+        "false",
+        "no",
+        "off",
+    )
+
+
+def _autoinject_floor() -> float:
+    raw = os.environ.get("RAG_AUTOINJECT_MIN_SCORE")
+    if raw is not None:
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    return _AUTOINJECT_DEFAULT_FLOOR
+
+
+# Lean: injecting the full top_k every turn prefills thousands of tokens.
+_AUTOINJECT_DEFAULT_TOP_K = 4
+
+
+def _autoinject_top_k() -> int:
+    raw = os.environ.get("RAG_AUTOINJECT_TOP_K")
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            pass
+    return _AUTOINJECT_DEFAULT_TOP_K
+
+
+def _last_user_text(conversation: list[dict]) -> str:
+    """Plain text of the most recent user turn (text parts only)."""
+    for msg in reversed(conversation):
+        if msg.get("role") != "user":
+            continue
+        content = msg.get("content")
+        if isinstance(content, str):
+            return content.strip()
+        if isinstance(content, list):
+            parts = [
+                p.get("text", "")
+                for p in content
+                if isinstance(p, dict) and p.get("type") in ("text", "input_text")
+            ]
+            return " ".join(t for t in parts if t).strip()
+        return ""
+    return ""
+
+
+def build_rag_autoinject(conversation: list[dict], rag_scope: dict | None) -> dict | None:
+    """Pre-retrieve the latest user turn; if a hit clears the cosine floor return
+    ``{"events": [...], "messages": [...]}`` to splice into the loop, else ``None``.
+    Toggle via ``rag_scope.autoinject`` (else env ``RAG_AUTOINJECT``); floor via
+    ``rag_scope.autoinject_min_score`` (else env ``RAG_AUTOINJECT_MIN_SCORE``).
+
+    Also the small-model fallback: models below ~4B often answer from memory
+    instead of calling ``search_knowledge_base``, so forcing retrieval here keeps
+    attachments consulted regardless of model size."""
+    if not rag_scope:
+        return None
+    enabled = rag_scope.get("autoinject")
+    if enabled is None:
+        enabled = _autoinject_enabled()
+    if not enabled:
+        return None
+    query = _last_user_text(conversation)
+    if not query:
+        return None
+    try:
+        from storage import rag_db
+        if not rag_db.RAG_AVAILABLE:
+            return None
+        from core.rag.tool import search_for_autoinject
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("RAG auto-inject unavailable: %s", exc)
+        return None
+
+    floor_override = rag_scope.get("autoinject_min_score")
+    floor = float(floor_override) if floor_override is not None else _autoinject_floor()
+    # Cap at the lean top_k, but honor a lower user setting.
+    lean_k = _autoinject_top_k()
+    sidebar_k = _opt_int(rag_scope.get("default_top_k"))
+    top_k = min(sidebar_k, lean_k) if sidebar_k is not None else lean_k
+    try:
+        found = search_for_autoinject(
+            query = query,
+            scope_kb_id = rag_scope.get("kb_id"),
+            scope_thread_id = rag_scope.get("thread_id"),
+            top_k = top_k,
+            min_dense_score = floor,
+            **_scope_retrieval_kwargs(rag_scope),
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("RAG auto-inject retrieval failed: %s", exc)
+        return None
+    if not found:
+        logger.info("RAG auto-inject: no passage >= %.2f; skipping", floor)
+        return None
+
+    text, sources = found
+    import json as _json
+    import uuid as _uuid
+
+    call_id = "rag_auto_" + _uuid.uuid4().hex[:12]
+    args = {"query": query}
+    full_result = text + RAG_SOURCES_SENTINEL + _json.dumps(sources, ensure_ascii = False)
+    events = [
+        {"type": "status", "text": f"Searching documents: {query[:60]}"},
+        {
+            "type": "tool_start",
+            "tool_name": "search_knowledge_base",
+            "tool_call_id": call_id,
+            "arguments": args,
+        },
+        {
+            "type": "tool_end",
+            "tool_name": "search_knowledge_base",
+            "tool_call_id": call_id,
+            "result": full_result,
+        },
+        {"type": "status", "text": ""},
+    ]
+    messages = [
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": call_id,
+                    "type": "function",
+                    "function": {
+                        "name": "search_knowledge_base",
+                        "arguments": _json.dumps(args, ensure_ascii = False),
+                    },
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "name": "search_knowledge_base",
+            "tool_call_id": call_id,
+            "content": text,
+        },
+    ]
+    logger.info("RAG auto-inject: %d passage(s) >= %.2f for %r", len(sources), floor, query[:80])
+    return {"events": events, "messages": messages}
+
+
 _MAX_PAGE_CHARS = 16000  # cap fetched page text (after HTML-to-MD conversion)
 # Raw download cap > _MAX_PAGE_CHARS because SSR pages embed large <head>
 # sections stripped during conversion; 512 KB reaches article content even
diff --git a/studio/backend/core/rag/__init__.py b/studio/backend/core/rag/__init__.py
new file mode 100644
index 0000000000..5dda48afc9
--- /dev/null
+++ b/studio/backend/core/rag/__init__.py
@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""RAG core package. Import submodules lazily; keep this free of top-level
+submodule imports to avoid pulling in heavy deps."""
+
+__all__ = [
+    "config",
+    "parsers",
+    "chunking",
+    "embeddings",
+    "store",
+    "retrieval",
+    "tool",
+    "ingestion",
+]
diff --git a/studio/backend/core/rag/captioner.py b/studio/backend/core/rag/captioner.py
new file mode 100644
index 0000000000..be8e341064
--- /dev/null
+++ b/studio/backend/core/rag/captioner.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Caption figures with the loaded vision model and splice the text into the page
+so images are searchable via the normal FTS5 + dense path. No-op (never raises)
+without a vision model or on failure; gated by ``config.CAPTION_IMAGES``."""
+
+from __future__ import annotations
+
+import base64
+import logging
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+_CAPTION_PROMPT = (
+    "Describe this figure or image from a document in one or two concise "
+    "sentences, for search indexing. State what it depicts (e.g. a diagram, "
+    "chart, table or photo) and its key content. Do not add commentary."
+)
+
+
+def vision_endpoint() -> tuple[str, str] | None:
+    """``(base_url, model)`` for a loaded vision GGUF model, else None."""
+    try:
+        from routes.inference import get_llama_cpp_backend
+        backend = get_llama_cpp_backend()
+        if getattr(backend, "is_loaded", False) and getattr(backend, "is_vision", False):
+            return backend.base_url, "local"
+    except Exception:  # noqa: BLE001 - never let discovery break ingestion
+        return None
+    return None
+
+
+def _caption_one(base_url: str, model: str, image_bytes: bytes, timeout: float) -> str | None:
+    import httpx
+
+    data_url = "data:image/png;base64," + base64.b64encode(image_bytes).decode("ascii")
+    payload = {
+        "model": model,
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": _CAPTION_PROMPT},
+                    {"type": "image_url", "image_url": {"url": data_url}},
+                ],
+            }
+        ],
+        "max_tokens": 200,
+        "temperature": 0.2,
+        "stream": False,
+        # Off: thinking models would spend the budget reasoning, returning "".
+        "chat_template_kwargs": {"enable_thinking": False},
+    }
+    try:
+        r = httpx.post(f"{base_url}/v1/chat/completions", json = payload, timeout = timeout)
+        r.raise_for_status()
+        text = r.json()["choices"][0]["message"]["content"]
+        return text.strip() or None
+    except Exception:  # noqa: BLE001 - a failed caption is non-fatal
+        logger.debug("caption request failed", exc_info = True)
+        return None
+
+
+def caption_images(
+    images: list, *, endpoint: tuple[str, str] | None = None
+) -> dict[int, list[str]]:
+    """Caption ``ParsedImage`` objects, keyed by 1-based page number; ``{}`` when
+    disabled, no vision model, or no images. Bounded by ``CAPTION_MAX_IMAGES``."""
+    if not config.CAPTION_IMAGES or not images:
+        return {}
+    ep = endpoint or vision_endpoint()
+    if ep is None:
+        return {}
+    base_url, model = ep
+
+    out: dict[int, list[str]] = {}
+    for img in images[: config.CAPTION_MAX_IMAGES]:
+        image_bytes = getattr(img, "image_bytes", None)
+        if not image_bytes:
+            continue
+        caption = _caption_one(base_url, model, image_bytes, config.CAPTION_TIMEOUT_S)
+        if caption:
+            page = getattr(img, "page_number", None) or 0
+            out.setdefault(int(page), []).append(caption)
+    return out
+
+
+def splice_captions(pages: list, captions: dict[int, list[str]]) -> list:
+    """Append captions to their page's text so the chunker indexes them, keeping
+    figures attributable in retrieved chunks. Returns new ``Page`` objects."""
+    if not captions:
+        return pages
+    from .parsers import Page
+
+    out: list = []
+    for page in pages:
+        caps = captions.get(page.page_number or 0)
+        if not caps:
+            out.append(page)
+            continue
+        extra = "".join(f"\n\n[Figure on page {page.page_number}: {c}]" for c in caps)
+        text = page.text + extra
+        out.append(Page(text = text, page_number = page.page_number, char_count = len(text)))
+    return out
diff --git a/studio/backend/core/rag/chunking.py b/studio/backend/core/rag/chunking.py
new file mode 100644
index 0000000000..c64acb4c60
--- /dev/null
+++ b/studio/backend/core/rag/chunking.py
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Page-aware recursive-separator chunking with token overlap. Each chunk records
+its ``[page_char_start, page_char_end)`` span and ``source_page_index``, used by
+the locator pass to highlight it on the PDF page."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from .parsers import Page
+
+TokenCounter = Callable[[str], int]
+SEPARATORS = ("\n# ", "\n## ", "\n### ", "\n\n", "\n", ". ", " ", "")
+
+
+@dataclass(frozen = True)
+class Chunk:
+    text: str
+    token_count: int
+    page_number: int | None
+    source_page_index: int
+    chunk_index: int
+    page_char_start: int
+    page_char_end: int
+
+
+def _split(text: str, seps: tuple[str, ...], max_tokens: int, count: TokenCounter) -> list[str]:
+    """Recursively split into pieces each <= max_tokens (best effort). Pieces
+    rejoin to ``text`` exactly, so offsets are a running length."""
+    if count(text) <= max_tokens:
+        return [text]
+    for i, sep in enumerate(seps):
+        parts = list(text) if sep == "" else text.split(sep)
+        if len(parts) <= 1:
+            continue
+        if sep:  # re-attach the separator
+            parts = [p + sep for p in parts[:-1]] + parts[-1:]
+        out: list[str] = []
+        for p in parts:
+            out.extend(
+                [p] if count(p) <= max_tokens else _split(p, seps[i + 1 :], max_tokens, count)
+            )
+        return [p for p in out if p]
+    n = max(1, max_tokens * 4)
+    return [text[j : j + n] for j in range(0, len(text), n)]
+
+
+def _merge(
+    pieces: list[str], starts: list[int], max_tokens: int, overlap: int, count: TokenCounter
+) -> list[tuple[str, int, int]]:
+    """Greedy-merge pieces into <= max_tokens chunks with token overlap.
+    ``starts[i]`` is ``pieces[i]``'s page char offset; returns
+    ``(chunk_text, char_start, char_end)`` spans."""
+    chunks: list[tuple[str, int, int]] = []
+    buf: list[str] = []
+    buf_starts: list[int] = []
+    buf_tok = 0
+
+    def _flush() -> None:
+        raw = "".join(buf)
+        stripped = raw.strip()
+        if not stripped:
+            return
+        lead = len(raw) - len(raw.lstrip())
+        trail = len(raw) - len(raw.rstrip())
+        start = buf_starts[0] + lead
+        end = buf_starts[0] + len(raw) - trail
+        chunks.append((stripped, start, end))
+
+    for piece, start in zip(pieces, starts):
+        pt = count(piece)
+        if buf and buf_tok + pt > max_tokens:
+            _flush()
+            # Bound the carry so carry + this piece fits max_tokens; else a full
+            # overlap before a near-max piece overflows the embedder.
+            carry_budget = min(overlap, max(0, max_tokens - pt))
+            carry, carry_starts, run = [], [], 0
+            for prev, prev_start in zip(reversed(buf), reversed(buf_starts)):
+                if run + count(prev) > carry_budget:
+                    break
+                carry.insert(0, prev)
+                carry_starts.insert(0, prev_start)
+                run += count(prev)
+            buf, buf_starts, buf_tok = carry, carry_starts, run
+        buf.append(piece)
+        buf_starts.append(start)
+        buf_tok += pt
+    if buf:
+        _flush()
+    return chunks
+
+
+def chunk_pages(
+    pages: list[Page], *, max_tokens: int, overlap: int, count: TokenCounter
+) -> list[Chunk]:
+    """Split each page into overlapping chunks, tracking per-page char offsets."""
+    out: list[Chunk] = []
+    for page_index, page in enumerate(pages):
+        pieces = _split(page.text, SEPARATORS, max_tokens, count)
+        # _split preserves offsets, so a running cursor gives exact ones.
+        starts: list[int] = []
+        cursor = 0
+        for piece in pieces:
+            starts.append(cursor)
+            cursor += len(piece)
+        for text, char_start, char_end in _merge(pieces, starts, max_tokens, overlap, count):
+            out.append(
+                Chunk(
+                    text = text,
+                    token_count = count(text),
+                    page_number = page.page_number,
+                    source_page_index = page_index,
+                    chunk_index = len(out),
+                    page_char_start = char_start,
+                    page_char_end = char_end,
+                )
+            )
+    return out
diff --git a/studio/backend/core/rag/config.py b/studio/backend/core/rag/config.py
new file mode 100644
index 0000000000..993423683c
--- /dev/null
+++ b/studio/backend/core/rag/config.py
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""RAG config; every value is env-overridable."""
+
+from __future__ import annotations
+
+import os
+
+EMBEDDING_MODEL = os.environ.get("RAG_EMBEDDING_MODEL", "unsloth/bge-small-en-v1.5")
+# Under bge's 512 limit, leaving headroom for the 2 special tokens (else overflow:
+# llama-server 500s, ST truncates). Keep <= embedder_max - ~12.
+CHUNK_TOKENS = int(os.environ.get("RAG_CHUNK_TOKENS", "500"))
+CHUNK_OVERLAP = int(os.environ.get("RAG_CHUNK_OVERLAP", "64"))
+TOP_K_LEXICAL = int(os.environ.get("RAG_TOP_K_LEXICAL", "30"))
+TOP_K_DENSE = int(os.environ.get("RAG_TOP_K_DENSE", "30"))
+TOP_K_HYBRID = int(os.environ.get("RAG_TOP_K_HYBRID", "10"))
+RRF_K = int(os.environ.get("RAG_RRF_K", "60"))
+
+UPLOAD_EXTS = {".pdf", ".txt", ".md", ".markdown", ".docx", ".html", ".htm"}
+
+# Figure captioning via the loaded vision model; off by default since each caption
+# is a model call. MAX_IMAGES bounds per-doc cost.
+CAPTION_IMAGES = os.environ.get("RAG_CAPTION_IMAGES", "0") == "1"
+CAPTION_MAX_IMAGES = int(os.environ.get("RAG_CAPTION_MAX_IMAGES", "8"))
+CAPTION_TIMEOUT_S = float(os.environ.get("RAG_CAPTION_TIMEOUT_S", "30"))
+
+# Embedder backend. "auto": sentence-transformers on a CUDA/ROCm GPU (torch fp16
+# wins bulk indexing), else torch-free GGUF llama-server. Switching backends changes
+# the vectors, so the index must be rebuilt.
+EMBED_BACKEND = os.environ.get("RAG_EMBED_BACKEND", "auto")
+# llama-server backend only. F16 over Q8_0: faster (no per-block dequant for this
+# tiny model) and exact vs fp32, for ~30MB more on disk.
+EMBED_GGUF_REPO = os.environ.get("RAG_EMBED_GGUF_REPO", "unsloth/bge-small-en-v1.5-GGUF")
+EMBED_GGUF_VARIANT = os.environ.get("RAG_EMBED_GGUF_VARIANT", "F16")
+EMBED_DEVICE = os.environ.get("RAG_EMBED_DEVICE", "auto")  # "auto" | "gpu" | "cpu"
+EMBED_HOST = os.environ.get("RAG_EMBED_HOST", "127.0.0.1")
+EMBED_PORT = int(os.environ.get("RAG_EMBED_PORT", "0"))  # 0 = auto-pick a free port
+EMBED_BATCH = int(os.environ.get("RAG_EMBED_BATCH", "64"))
+EMBED_STARTUP_TIMEOUT_S = float(os.environ.get("RAG_EMBED_STARTUP_TIMEOUT_S", "120"))
+EMBED_REQUEST_TIMEOUT_S = float(os.environ.get("RAG_EMBED_REQUEST_TIMEOUT_S", "60"))
diff --git a/studio/backend/core/rag/embed_llama_server.py b/studio/backend/core/rag/embed_llama_server.py
new file mode 100644
index 0000000000..2fadbcc6c6
--- /dev/null
+++ b/studio/backend/core/rag/embed_llama_server.py
@@ -0,0 +1,448 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF embedder over the bundled llama.cpp, served via HTTP (no torch).
+
+Opt-in (``RAG_EMBED_BACKEND=llama-server``). Runs a dedicated
+``llama-server --embedding`` subprocess on its own port and calls its OpenAI-style
+``/v1/embeddings`` + ``/tokenize``, fully isolated from the chat backend.
+
+Device is ``auto`` (GPU when present, else CPU, falling back to CPU if a GPU start
+fails); ``RAG_EMBED_DEVICE`` forces it. We call only llama_cpp's *static* helpers
+(no torch), copying the instance-coupled bits locally, since constructing a
+``LlamaCppBackend`` runs an ``__init__`` reaper that kills any Studio llama-server
+-- so each request re-spawns ours if it died (self-heal).
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import subprocess
+import threading
+import time
+from functools import lru_cache
+from pathlib import Path
+
+import httpx
+import numpy as np
+
+from utils.native_path_leases import child_env_without_native_path_secret
+from utils.subprocess_compat import windows_hidden_subprocess_kwargs
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+# httpx transport errors meaning "the server is gone" -> trigger a respawn.
+_TRANSPORT_ERRORS = (
+    httpx.ConnectError,
+    httpx.ReadError,
+    httpx.RemoteProtocolError,
+    httpx.WriteError,
+)
+
+
+class LlamaServerBackend:
+    """Manages a llama.cpp embedding subprocess and talks to it over HTTP."""
+
+    def __init__(self) -> None:
+        # Lifecycle (spawn/restart/kill) is serialized; HTTP requests are not.
+        self._lifecycle_lock = threading.Lock()
+        self._process: subprocess.Popen | None = None
+        self._port: int | None = None
+        self._stdout_lines: list[str] = []
+        self._stdout_thread: threading.Thread | None = None
+        self._dim: int | None = None
+        self._dim_lock = threading.Lock()
+        self._model_path: str | None = None
+        self._binary: str | None = None
+        # Sticky after an auto GPU start fails: later spawns stay on CPU.
+        self._force_cpu = False
+        # Pooled client; requests pass full URLs, so a respawn's new port needs
+        # no rebuild.
+        self._client = httpx.Client(timeout = config.EMBED_REQUEST_TIMEOUT_S)
+        atexit.register(self._shutdown)
+
+    @property
+    def _base_url(self) -> str:
+        return f"http://{config.EMBED_HOST}:{self._port}"
+
+    def _resolve_binary(self) -> str:
+        """Find llama-server, verify embeddings support, cache it. Raises if
+        missing/unsupported."""
+        if self._binary is not None:
+            return self._binary
+        from core.inference.llama_cpp import LlamaCppBackend
+
+        binary = LlamaCppBackend._find_llama_server_binary()
+        if not binary:
+            raise RuntimeError(
+                "llama-server binary not found; cannot use RAG_EMBED_BACKEND="
+                "llama-server. Install llama.cpp or set LLAMA_SERVER_PATH / "
+                "UNSLOTH_LLAMA_CPP_PATH."
+            )
+        self._assert_embedding_support(binary)
+        self._binary = binary
+        return binary
+
+    @staticmethod
+    @lru_cache(maxsize = 8)
+    def _help_text(binary: str) -> str:
+        """`llama-server --help`, cached. Ignore exit code (some builds exit
+        non-zero on --help)."""
+        try:
+            proc = subprocess.run(
+                [binary, "--help"],
+                capture_output = True,
+                text = True,
+                timeout = 30,
+                **windows_hidden_subprocess_kwargs(),
+            )
+            return (proc.stdout or "") + (proc.stderr or "")
+        except Exception as e:  # noqa: BLE001
+            logger.warning("could not run `llama-server --help`: %s", e)
+            return ""
+
+    def _assert_embedding_support(self, binary: str) -> None:
+        help_text = self._help_text(binary)
+        # Empty help -> assume capable (a missing flag still fails at spawn).
+        if help_text and "--embedding" not in help_text:
+            raise RuntimeError(
+                "the bundled llama-server build lacks --embedding support; "
+                "RAG_EMBED_BACKEND=llama-server requires an embeddings-capable build"
+            )
+
+    def _resolve_model_path(self) -> str:
+        """Download (or cache-hit) the variant-matching, non-mmproj GGUF embedder,
+        returning its local path."""
+        if self._model_path is not None:
+            return self._model_path
+        from huggingface_hub import hf_hub_download, list_repo_files
+
+        repo = config.EMBED_GGUF_REPO
+        token = os.environ.get("HF_TOKEN") or None
+        files = [f for f in list_repo_files(repo, token = token) if f.lower().endswith(".gguf")]
+        files = [f for f in files if "mmproj" not in f.lower()]
+        if not files:
+            raise RuntimeError(f"no .gguf file found in embedder repo {repo!r}")
+        variant = config.EMBED_GGUF_VARIANT.lower()
+        match = [f for f in files if variant in f.lower()] or files
+        filename = sorted(match, key = len)[0]
+        logger.info("resolving GGUF embedder %s/%s", repo, filename)
+        self._model_path = hf_hub_download(repo_id = repo, filename = filename, token = token)
+        return self._model_path
+
+    # Min free VRAM (MiB) for the embedder; below this, auto stays on CPU.
+    _MIN_GPU_FREE_MIB = 1024
+
+    def _use_gpu(self) -> bool:
+        """``RAG_EMBED_DEVICE``: ``gpu``/``cpu`` force it; ``auto`` uses a GPU when
+        present. A sticky CPU fallback (after an auto GPU start fails) wins."""
+        dev = config.EMBED_DEVICE.lower()
+        if dev == "gpu":
+            return True
+        if dev == "cpu" or self._force_cpu:
+            return False
+        return self._gpu_available()  # auto
+
+    @staticmethod
+    def _gpu_available() -> bool:
+        """Apple Metal, or an NVIDIA/ROCm GPU with enough free VRAM. Reuses
+        llama_cpp's static probe (nvidia-smi first, so the common path needs no
+        torch)."""
+        from utils.hardware import is_apple_silicon
+
+        if is_apple_silicon():
+            return True  # bundled mac build offloads to Metal
+        from core.inference.llama_cpp import LlamaCppBackend
+
+        gpus = LlamaCppBackend._get_gpu_free_memory()  # [(idx, free_mib)], honors CVD
+        return any(free >= LlamaServerBackend._MIN_GPU_FREE_MIB for _, free in gpus)
+
+    def _build_cmd(self, binary: str, model_path: str, port: int, *, use_gpu: bool) -> list[str]:
+        # No --embd-normalize (not in every build; we normalize in Python to match
+        # the ST path). --fit off: don't auto-resize ctx/offload to device memory.
+        cmd = [
+            binary,
+            "-m",
+            model_path,
+            "--host",
+            config.EMBED_HOST,
+            "--port",
+            str(port),
+            "--embedding",
+            "--pooling",
+            "cls",
+            "--fit",
+            "off",
+        ]
+        # -1 offloads every layer (matches the chat server); 0 keeps it on CPU.
+        cmd += ["-ngl", "-1" if use_gpu else "0"]
+        return cmd
+
+    def _build_env(self, binary: str, *, use_gpu: bool) -> dict[str, str]:
+        env = child_env_without_native_path_secret()
+        env["LLAMA_SET_ROWS"] = "1"  # ggml set_rows fast path
+        if use_gpu:
+            self._add_linux_cuda_libs(env, str(Path(binary).parent))
+        else:
+            # Blank devices so a CUDA build stays on CPU and reserves no VRAM.
+            env["CUDA_VISIBLE_DEVICES"] = ""
+        return env
+
+    @staticmethod
+    def _add_linux_cuda_libs(env: dict[str, str], binary_dir: str) -> None:
+        """Best-effort LD_LIBRARY_PATH so the prebuilt binary finds CUDA libs."""
+        import glob
+        import platform
+        import sys
+
+        if sys.platform == "win32":
+            return  # Windows resolves CUDA via PATH in the inherited env.
+        arch = platform.machine()
+        lib_dirs = [binary_dir]
+        for pattern in (
+            os.path.join(sys.prefix, "lib", "python*", "site-packages", "nvidia", "cu*", "lib"),
+            os.path.join(sys.prefix, "lib", "python*", "site-packages", "nvidia", "cudnn", "lib"),
+        ):
+            lib_dirs.extend(d for d in glob.glob(pattern) if os.path.isdir(d))
+        for cuda_lib in (
+            "/usr/local/cuda/lib64",
+            f"/usr/local/cuda/targets/{arch}-linux/lib",
+            "/usr/local/cuda-12/lib64",
+        ):
+            if os.path.isdir(cuda_lib):
+                lib_dirs.append(cuda_lib)
+        existing = env.get("LD_LIBRARY_PATH", "")
+        joined = ":".join(lib_dirs)
+        env["LD_LIBRARY_PATH"] = f"{joined}:{existing}" if existing else joined
+
+    def _drain_stdout(self, proc: subprocess.Popen) -> None:
+        """Drain the child's stdout so its pipe buffer never deadlocks; keep the
+        tail for crash diagnostics."""
+        try:
+            for line in proc.stdout:  # type: ignore[union-attr]
+                line = line.rstrip()
+                if line:
+                    self._stdout_lines.append(line)
+                    if len(self._stdout_lines) > 200:
+                        del self._stdout_lines[:-200]
+                    logger.debug("[llama-embed] %s", line)
+        except Exception:  # noqa: BLE001 - drain thread must never raise
+            pass
+
+    def _spawn(self) -> None:
+        """Start the embed server (caller holds the lock). On ``auto``, a failed
+        GPU start falls back to CPU once; explicit ``gpu``/``cpu`` do not."""
+        use_gpu = self._use_gpu()
+        try:
+            self._spawn_once(use_gpu)
+        except RuntimeError:
+            auto = config.EMBED_DEVICE.lower() not in ("gpu", "cpu")
+            if use_gpu and auto:
+                logger.warning("embed server GPU start failed; falling back to CPU")
+                self._force_cpu = True
+                self._spawn_once(False)
+            else:
+                raise
+
+    def _spawn_once(self, use_gpu: bool) -> None:
+        binary = self._resolve_binary()
+        model_path = self._resolve_model_path()
+        port = config.EMBED_PORT or self._find_free_port()
+        env = self._build_env(binary, use_gpu = use_gpu)
+        cmd = self._build_cmd(binary, model_path, port, use_gpu = use_gpu)
+        logger.info(
+            "starting llama-server embedder (%s): %s",
+            "gpu" if use_gpu else "cpu",
+            " ".join(cmd),
+        )
+        self._stdout_lines = []
+        proc = subprocess.Popen(
+            cmd,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.STDOUT,
+            text = True,
+            env = env,
+            **windows_hidden_subprocess_kwargs(),
+        )
+        self._process = proc
+        self._port = port
+        self._stdout_thread = threading.Thread(
+            target = self._drain_stdout,
+            args = (proc,),
+            daemon = True,
+            name = "llama-embed-stdout",
+        )
+        self._stdout_thread.start()
+        if not self._wait_for_health(config.EMBED_STARTUP_TIMEOUT_S):
+            tail = "\n".join(self._stdout_lines[-30:])
+            self._kill_process()
+            raise RuntimeError(
+                f"llama-server embedder failed to become healthy. Last output:\n{tail[:2000]}"
+            )
+
+    @staticmethod
+    def _find_free_port() -> int:
+        from core.inference.llama_cpp import LlamaCppBackend
+        return LlamaCppBackend._find_free_port()
+
+    def _wait_for_health(
+        self,
+        timeout: float,
+        interval: float = 0.5,
+    ) -> bool:
+        """Poll /health until 200; bail early if the process exits."""
+        deadline = time.monotonic() + timeout
+        url = f"{self._base_url}/health"
+        while time.monotonic() < deadline:
+            if not self._process_alive():
+                code = None if self._process is None else self._process.returncode
+                logger.error("llama-server embedder exited early (code %s)", code)
+                return False
+            try:
+                if httpx.get(url, timeout = 2.0).status_code == 200:
+                    return True
+            except (*_TRANSPORT_ERRORS, httpx.TimeoutException):
+                pass
+            time.sleep(interval)
+        logger.error("llama-server embedder health check timed out after %ss", timeout)
+        return False
+
+    def _process_alive(self) -> bool:
+        return self._process is not None and self._process.poll() is None
+
+    def _ensure_ready(self) -> None:
+        """Guarantee a live server, (re)spawning if needed. Double-checked so the
+        alive path takes no lock; self-heals after the chat reaper kills us."""
+        if self._process_alive():
+            return
+        with self._lifecycle_lock:
+            if self._process_alive():
+                return
+            self._kill_process()
+            self._spawn()
+
+    def _restart(self) -> None:
+        with self._lifecycle_lock:
+            self._kill_process()
+            self._spawn()
+
+    def _kill_process(self) -> None:
+        proc = self._process
+        if proc is None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout = 5)
+        except subprocess.TimeoutExpired:
+            logger.warning("llama-server embedder did not exit on SIGTERM; killing")
+            proc.kill()
+            try:
+                proc.wait(timeout = 5)
+            except Exception:  # noqa: BLE001
+                pass
+        except Exception as e:  # noqa: BLE001
+            logger.warning("error killing llama-server embedder: %s", e)
+        finally:
+            self._process = None
+            if self._stdout_thread is not None:
+                self._stdout_thread.join(timeout = 2)
+                self._stdout_thread = None
+
+    def _shutdown(self) -> None:
+        try:
+            self._kill_process()
+        finally:
+            try:
+                self._client.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    def _post(self, path: str, payload: dict) -> dict:
+        """POST to the server, restarting once and retrying on a dropped connection
+        (the reaper may have killed us) or a timeout (the bundled build sometimes
+        wedges a request); a fresh server unsticks both."""
+        last_exc: Exception | None = None
+        for attempt in range(2):
+            self._ensure_ready()
+            try:
+                resp = self._client.post(f"{self._base_url}{path}", json = payload)
+                resp.raise_for_status()
+                return resp.json()
+            except (*_TRANSPORT_ERRORS, httpx.TimeoutException) as e:
+                last_exc = e
+                if attempt == 0:
+                    self._restart()
+                    continue
+            except httpx.HTTPStatusError as e:
+                body = e.response.text[:500] if e.response is not None else ""
+                raise RuntimeError(
+                    f"llama-server embedder POST {path} -> {e.response.status_code}: {body}"
+                ) from e
+        raise RuntimeError(f"llama-server embedder POST {path} failed after retry") from last_exc
+
+    def encode(
+        self,
+        texts,
+        *,
+        model_name = None,
+        normalize = True,
+    ):
+        """Embed texts -> (N, dim) float32. ``model_name`` is ignored (the GGUF is
+        fixed by config). Normalizes in Python to match the ST backend."""
+        n = len(texts)
+        if n == 0:
+            return np.zeros((0, self.dim()), dtype = np.float32)
+        rows: list[list[float]] = []
+        batch = max(1, config.EMBED_BATCH)
+        for start in range(0, n, batch):
+            chunk = list(texts[start : start + batch])
+            data = self._post(
+                "/v1/embeddings",
+                {"input": chunk, "model": "embedding", "encoding_format": "float"},
+            )
+            items = data.get("data", [])
+            if len(items) != len(chunk):
+                raise RuntimeError(
+                    f"embedder returned {len(items)} vectors for {len(chunk)} inputs"
+                )
+            # OpenAI spec lets the server reorder; sort back by index.
+            items = sorted(items, key = lambda d: d.get("index", 0))
+            rows.extend(d["embedding"] for d in items)
+        arr = np.asarray(rows, dtype = np.float32)
+        if arr.ndim != 2:
+            raise RuntimeError(f"embedder returned ragged vectors: shape {arr.shape}")
+        if normalize:
+            norms = np.linalg.norm(arr, axis = 1, keepdims = True)
+            norms[norms == 0] = 1.0
+            arr = arr / norms
+        return arr
+
+    def dim(self, *, model_name = None) -> int:
+        """Embedding width, probed once via a 1-text encode and cached."""
+        if self._dim is not None:
+            return self._dim
+        with self._dim_lock:
+            if self._dim is None:
+                vec = self.encode(["x"], normalize = False)
+                self._dim = int(vec.shape[1])
+        return self._dim
+
+    def warm(self, *, model_name = None) -> None:
+        """Start the server and probe dim off the request path."""
+        self._ensure_ready()
+        self.dim()
+
+    def token_counter(self, *, model_name = None):
+        """Count tokens via the GGUF's /tokenize so chunk sizing matches the
+        embedder. Cached per text."""
+
+        @lru_cache(maxsize = 4096)
+        def _count(text: str) -> int:
+            data = self._post("/tokenize", {"content": text, "add_special": False})
+            return len(data.get("tokens", []))
+
+        return _count
diff --git a/studio/backend/core/rag/embeddings.py b/studio/backend/core/rag/embeddings.py
new file mode 100644
index 0000000000..4e76e4fcaa
--- /dev/null
+++ b/studio/backend/core/rag/embeddings.py
@@ -0,0 +1,297 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Dense embedder facade dispatching to a process-wide backend from
+``config.EMBED_BACKEND`` (``auto`` picks by hardware): ``sentence-transformers``
+(torch) or ``llama-server`` (GGUF, no torch).
+
+Backends produce different vectors, so switching requires rebuilding the index. We
+degrade to llama.cpp rather than crash when ST breaks on a machine: an init-time
+probe falls back before any vector is produced (so spaces can't mix), and a
+runtime ``encode`` failure swaps the process to llama-server for the rest of its
+life (KBs already embedded with ST should then be reindexed).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from functools import lru_cache
+from typing import Callable
+
+from utils.hardware.hardware import DeviceType, get_device
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+# "false" silences the fast tokenizer's fork warning; encode() flips it to "true"
+# only during a batch tokenize (rayon speedup), then restores it.
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+_lock = threading.Lock()
+# Serializes encode/tokenize (HF fast tokenizer isn't thread-safe). Separate from
+# _lock so a long encode never blocks a reload.
+_compute_lock = threading.Lock()
+_model = None
+_name: str | None = None
+
+
+# Studio device -> torch device string. Apple has no torch device -> CPU.
+_TORCH_DEVICE = {DeviceType.CUDA: "cuda", DeviceType.XPU: "xpu"}
+
+
+def _device() -> str:
+    return _TORCH_DEVICE.get(get_device(), "cpu")
+
+
+def _get(model_name: str | None = None):
+    """Cached SentenceTransformer, (re)loading on a name change. Loaded in fp16
+    for a ~1.5x speedup at negligible accuracy loss."""
+    global _model, _name
+    name = model_name or config.EMBEDDING_MODEL
+    with _lock:
+        if _model is None or _name != name:
+            from sentence_transformers import SentenceTransformer
+
+            device = _device()
+            logger.info("loading embedding model %s on %s", name, device)
+            _model = SentenceTransformer(
+                name, device = device, model_kwargs = {"torch_dtype": "float16"}
+            )
+            _name = name
+        return _model
+
+
+@lru_cache(maxsize = 1)
+def _inference_ctx_factory():
+    """``torch.inference_mode`` if torch imports, else ``nullcontext``. Returns the
+    factory so each call gets a fresh single-use guard."""
+    try:
+        import torch
+        return torch.inference_mode
+    except Exception:  # noqa: BLE001 - torch may be missing or broken
+        from contextlib import nullcontext
+        return nullcontext
+
+
+def _inference_ctx():
+    return _inference_ctx_factory()()
+
+
+def _st_encode(
+    texts: list[str],
+    *,
+    model_name: str | None = None,
+    normalize: bool = True,
+):
+    """ST encode -> (N, dim) float32. Serialized (fast-tokenizer borrow check),
+    under inference_mode when torch is present, with rayon enabled for the call."""
+    model = _get(model_name)
+    with _compute_lock:
+        os.environ["TOKENIZERS_PARALLELISM"] = "true"
+        try:
+            with _inference_ctx():
+                out = model.encode(
+                    texts,
+                    normalize_embeddings = normalize,
+                    convert_to_numpy = True,
+                    show_progress_bar = False,
+                )
+        finally:
+            os.environ["TOKENIZERS_PARALLELISM"] = "false"
+    # fp16 weights yield fp16 output; store float32 for sqlite-vec + stable cosine.
+    if hasattr(out, "astype"):
+        out = out.astype("float32", copy = False)
+    return out
+
+
+def _st_dim(model_name: str | None = None) -> int:
+    return _get(model_name).get_sentence_embedding_dimension()
+
+
+def _st_token_counter(model_name: str | None = None) -> Callable[[str], int]:
+    """Token counter using the model's tokenizer, under the compute lock (the same
+    fast tokenizer backs encode and isn't thread-safe), with rayon enabled for the
+    call. Mirrors ``_st_encode``."""
+    tok = _get(model_name).tokenizer
+
+    def _count(t: str) -> int:
+        with _compute_lock:
+            os.environ["TOKENIZERS_PARALLELISM"] = "true"
+            try:
+                return len(tok.encode(t, add_special_tokens = False))
+            finally:
+                os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+    return _count
+
+
+class _SentenceTransformersBackend:
+    """Default backend; delegates to the module-level ST helpers so the ``_get``
+    monkeypatch in tests keeps working."""
+
+    def encode(
+        self,
+        texts,
+        *,
+        model_name = None,
+        normalize = True,
+    ):
+        try:
+            return _st_encode(texts, model_name = model_name, normalize = normalize)
+        except Exception as st_err:  # noqa: BLE001 - runtime ST/CUDA encode failure
+            # ST loaded but this encode blew up; swap the process to the llama-server
+            # embedder (so later encodes stay in one space) and retry.
+            fallback = _switch_to_llama_fallback(st_err)
+            if fallback is None:
+                raise
+            return fallback.encode(texts, model_name = model_name, normalize = normalize)
+
+    def token_counter(self, *, model_name = None):
+        return _st_token_counter(model_name)
+
+    def dim(self, *, model_name = None):
+        return _st_dim(model_name)
+
+    def warm(self, *, model_name = None):
+        _get(model_name)
+
+
+_backend_lock = threading.Lock()
+_backend = None
+_backend_key: str | None = None
+
+_ST_ALIASES = frozenset({"sentence-transformers", "sentence_transformers", "st"})
+_LLAMA_ALIASES = frozenset(
+    {"llama-server", "llama_server", "llama", "llama.cpp", "llamacpp", "gguf"}
+)
+_AUTO_ALIASES = frozenset({"auto", ""})
+
+
+def _resolve_auto() -> str:
+    """Pick a backend for ``auto``: sentence-transformers when a CUDA/ROCm GPU is
+    present (torch fp16 wins bulk indexing), else the torch-free GGUF llama-server
+    -- or ST if its binary is missing. GPU check is torch-free (nvidia-smi)."""
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    if LlamaCppBackend._get_gpu_free_memory():
+        return "sentence-transformers"
+    if LlamaCppBackend._find_llama_server_binary():
+        return "llama-server"
+    return "sentence-transformers"
+
+
+def _try_make_llama_backend():
+    """A llama-server GGUF embedding backend if its binary is present, else None.
+    Construction is lazy -- no server starts until warm."""
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    if not LlamaCppBackend._find_llama_server_binary():
+        return None
+    from .embed_llama_server import LlamaServerBackend
+
+    return LlamaServerBackend()
+
+
+def _build_st_backend_or_fallback():
+    """Build the ST backend, probing it by loading the model now. If the probe
+    raises (no torch, CUDA mismatch, bad wheel) and the GGUF llama-server embedder
+    is available, fall back to it. The probe runs before any vector is produced, so
+    this never mixes spaces. Re-raises if no embedder can start."""
+    backend = _SentenceTransformersBackend()
+    try:
+        backend.warm(model_name = None)
+        return backend
+    except Exception as st_err:  # noqa: BLE001 - any ST/torch import or load failure
+        fallback = _try_make_llama_backend()
+        if fallback is None:
+            raise
+        logger.warning(
+            "sentence-transformers embedder unavailable (%s); falling back to the "
+            "llama-server GGUF embedder",
+            st_err,
+        )
+        return fallback
+
+
+def _switch_to_llama_fallback(err):
+    """An ST encode failed at runtime even though the model had loaded. Swap the
+    process embedder to llama-server so every later encode stays in one space, and
+    return it (None if no binary). Vectors written before the swap were ST, so any
+    KB already embedded with ST should be reindexed."""
+    global _backend, _backend_key
+    with _backend_lock:
+        if not isinstance(_backend, _SentenceTransformersBackend):
+            return _backend  # another thread already swapped (or was never ST)
+        fallback = _try_make_llama_backend()
+        if fallback is None:
+            return None
+        logger.warning(
+            "sentence-transformers encode failed (%s); switching to the llama-server "
+            "embedder for the rest of this process. Reindex any knowledge base that "
+            "was already embedded with sentence-transformers.",
+            err,
+        )
+        _backend = fallback
+        _backend_key = (config.EMBED_BACKEND or "auto").strip().lower()
+        return fallback
+
+
+def _get_backend():
+    """The process-wide embedding backend for ``config.EMBED_BACKEND``, built once.
+    Cached by the raw config value, so ``auto`` detection runs only on a miss and a
+    config change rebuilds it."""
+    global _backend, _backend_key
+    raw = (config.EMBED_BACKEND or "auto").strip().lower()
+    with _backend_lock:
+        if _backend is not None and _backend_key == raw:
+            return _backend
+        key = _resolve_auto() if raw in _AUTO_ALIASES else raw
+        if key in _ST_ALIASES:
+            _backend = _build_st_backend_or_fallback()
+        elif key in _LLAMA_ALIASES:
+            # Imported lazily so the ST path never imports llama plumbing.
+            from .embed_llama_server import LlamaServerBackend
+            _backend = LlamaServerBackend()
+        else:
+            raise ValueError(
+                f"Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected "
+                "'auto', 'sentence-transformers' or 'llama-server'"
+            )
+        _backend_key = raw
+        return _backend
+
+
+def _reset_backend() -> None:
+    """Drop the cached backend (test teardown / re-init)."""
+    global _backend, _backend_key
+    with _backend_lock:
+        _backend = None
+        _backend_key = None
+
+
+def warm(model_name: str | None = None) -> None:
+    """Eagerly load the embedder so the first real request isn't slow."""
+    _get_backend().warm(model_name = model_name)
+
+
+def encode(
+    texts: list[str],
+    *,
+    model_name: str | None = None,
+    normalize: bool = True,
+):
+    """Embed texts into an (N, dim) float32 numpy array."""
+    return _get_backend().encode(texts, model_name = model_name, normalize = normalize)
+
+
+def dim(model_name: str | None = None) -> int:
+    """Embedding dimension for the (loaded) model."""
+    return _get_backend().dim(model_name = model_name)
+
+
+def token_counter(model_name: str | None = None) -> Callable[[str], int]:
+    """Callable counting tokens with the embedder's own tokenizer."""
+    return _get_backend().token_counter(model_name = model_name)
diff --git a/studio/backend/core/rag/ingestion.py b/studio/backend/core/rag/ingestion.py
new file mode 100644
index 0000000000..5ac0639f11
--- /dev/null
+++ b/studio/backend/core/rag/ingestion.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""In-process threaded ingestion: parse -> chunk -> embed -> store.
+``start_ingestion`` returns ``(document_id, job_id)`` immediately and runs on a
+daemon thread, pushing progress onto a per-job queue (streamed as SSE by
+``job_events``). Documents are deduped by content hash per scope."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import queue
+import threading
+
+from storage import rag_db
+
+from . import captioner, chunking, config, embeddings, parsers, store
+
+logger = logging.getLogger(__name__)
+
+# Per-job event queues, drained by job_events; ``None`` ends the stream.
+_jobs: dict[str, "queue.Queue"] = {}
+_jobs_lock = threading.Lock()
+
+_EMBED_BATCH = 64  # bounds peak memory
+
+
+def _sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(1 << 20), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def _emit(job_id: str, event: dict) -> None:
+    with _jobs_lock:
+        q = _jobs.get(job_id)
+    if q is not None:
+        q.put(event)
+
+
+def _set_job(
+    conn,
+    job_id: str,
+    *,
+    status: str | None = None,
+    stage: str | None = None,
+    progress: float | None = None,
+    error: str | None = None,
+) -> None:
+    conn.execute(
+        "UPDATE ingestion_jobs SET "
+        "status=COALESCE(?, status), "
+        "stage=COALESCE(?, stage), "
+        "progress=COALESCE(?, progress), "
+        "error=COALESCE(?, error) "
+        "WHERE id=?",
+        (status, stage, progress, error, job_id),
+    )
+    conn.commit()
+
+
+def _progress(conn, job_id: str, stage: str, progress: float) -> None:
+    _set_job(conn, job_id, status = "running", stage = stage, progress = progress)
+    _emit(job_id, {"type": "progress", "stage": stage, "progress": progress})
+
+
+def _embed_all(texts: list[str], model_name: str | None):
+    """Embed texts in batches into a flat vector list."""
+    vectors: list = []
+    for i in range(0, len(texts), _EMBED_BATCH):
+        batch = texts[i : i + _EMBED_BATCH]
+        out = embeddings.encode(batch, model_name = model_name, normalize = True)
+        vectors.extend(out)
+    return vectors
+
+
+def _run(
+    job_id: str, document_id: str, scope: str, stored_path: str, model_name: str | None
+) -> None:
+    conn = rag_db.get_connection()
+    try:
+        _progress(conn, job_id, "parsing", 0.1)
+        pages = parsers.parse(stored_path)
+        if config.CAPTION_IMAGES and stored_path.lower().endswith(".pdf"):
+            # Caption figures, splice into page text (no-op without a vision model).
+            try:
+                figures = parsers.render_pdf_figures(
+                    stored_path, max_figures = config.CAPTION_MAX_IMAGES
+                )
+            except Exception:
+                logger.warning("figure rendering failed for job %s", job_id, exc_info = True)
+                figures = []
+            if figures:
+                _progress(conn, job_id, "captioning", 0.2)
+                captions = captioner.caption_images(figures)
+                pages = captioner.splice_captions(pages, captions)
+
+        _progress(conn, job_id, "chunking", 0.3)
+        count = embeddings.token_counter(model_name)
+        chunks = chunking.chunk_pages(
+            pages,
+            max_tokens = config.CHUNK_TOKENS,
+            overlap = config.CHUNK_OVERLAP,
+            count = count,
+        )
+        if not chunks:
+            store.set_document_status(conn, document_id, "completed", num_chunks = 0)
+            _set_job(conn, job_id, status = "completed", stage = "done", progress = 1.0)
+            _emit(job_id, {"type": "complete", "num_chunks": 0})
+            return
+
+        _progress(conn, job_id, "embedding", 0.5)
+        vectors = _embed_all([c.text for c in chunks], model_name)
+
+        # Locate each chunk's highlight regions (non-PDFs/failures yield none).
+        regions = None
+        if stored_path.lower().endswith(".pdf"):
+            try:
+                from . import locators
+                regions = locators.pdf_regions_for_chunks(stored_path, pages, chunks)
+            except Exception:
+                logger.warning("pdf region location failed for job %s", job_id, exc_info = True)
+                regions = None
+
+        _progress(conn, job_id, "storing", 0.9)
+        store.add_chunks(conn, scope, document_id, chunks, vectors, regions)
+        store.set_document_status(conn, document_id, "completed", num_chunks = len(chunks))
+
+        _set_job(conn, job_id, status = "completed", stage = "done", progress = 1.0)
+        _emit(job_id, {"type": "complete", "num_chunks": len(chunks)})
+    except Exception as exc:  # noqa: BLE001 - report any failure to the client
+        logger.exception("ingestion job %s failed", job_id)
+        try:
+            store.set_document_status(conn, document_id, "failed", error = str(exc))
+            _set_job(conn, job_id, status = "failed", stage = "error", error = str(exc))
+        except Exception:  # noqa: BLE001
+            logger.exception("failed to record ingestion failure for job %s", job_id)
+        _emit(job_id, {"type": "error", "stage": "error", "error": str(exc)})
+    finally:
+        conn.close()
+        _emit(job_id, None)
+
+
+def start_ingestion(
+    scope: str,
+    kb_id: str | None,
+    thread_id: str | None,
+    filename: str,
+    stored_path: str,
+    *,
+    model_name: str | None = None,
+) -> tuple[str, str]:
+    """Create the document + job rows and spawn the worker, returning
+    ``(document_id, job_id)``. A duplicate content hash in this scope returns the
+    existing id with an already-completed job (no re-ingest)."""
+    ext = os.path.splitext(stored_path)[1].lower()
+    if ext not in config.UPLOAD_EXTS:
+        raise ValueError(f"unsupported file type: {ext}")
+
+    sha = _sha256_file(stored_path)
+    conn = rag_db.get_connection()
+    try:
+        existing = store.document_by_hash(conn, scope, sha)
+        if existing is not None:
+            job_id = _new_job(conn, existing, scope, status = "completed", progress = 1.0)
+            with _jobs_lock:
+                _jobs[job_id] = queue.Queue()
+            _emit(job_id, {"type": "complete", "num_chunks": 0, "deduped": True})
+            _emit(job_id, None)
+            return existing, job_id
+
+        document_id = store.create_document(
+            conn,
+            scope = scope,
+            filename = filename,
+            sha256 = sha,
+            kb_id = kb_id,
+            thread_id = thread_id,
+            status = "pending",
+            stored_path = stored_path,
+        )
+        job_id = _new_job(conn, document_id, scope)
+    finally:
+        conn.close()
+
+    with _jobs_lock:
+        _jobs[job_id] = queue.Queue()
+    threading.Thread(
+        target = _run,
+        args = (job_id, document_id, scope, stored_path, model_name),
+        daemon = True,
+    ).start()
+    return document_id, job_id
+
+
+def _new_job(
+    conn,
+    document_id: str,
+    scope: str,
+    *,
+    status: str = "pending",
+    progress: float = 0.0,
+) -> str:
+    import uuid
+    from datetime import datetime, timezone
+
+    job_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO ingestion_jobs(id, document_id, scope, status, stage, progress, created_at) "
+        "VALUES(?,?,?,?,?,?,?)",
+        (
+            job_id,
+            document_id,
+            scope,
+            status,
+            None,
+            progress,
+            datetime.now(timezone.utc).isoformat(),
+        ),
+    )
+    conn.commit()
+    return job_id
+
+
+def job_events(job_id: str):
+    """Yield job events for SSE; ends when the worker signals completion."""
+    with _jobs_lock:
+        q = _jobs.get(job_id)
+    if q is None:
+        return
+    while True:
+        event = q.get()
+        if event is None:
+            break
+        yield event
+    with _jobs_lock:
+        _jobs.pop(job_id, None)
+
+
+def get_job_status(job_id: str) -> dict | None:
+    """Read the persisted ingestion job row (status / stage / progress / error)."""
+    conn = rag_db.get_connection()
+    try:
+        row = conn.execute("SELECT * FROM ingestion_jobs WHERE id=?", (job_id,)).fetchone()
+        return dict(row) if row else None
+    finally:
+        conn.close()
diff --git a/studio/backend/core/rag/locators.py b/studio/backend/core/rag/locators.py
new file mode 100644
index 0000000000..57c0487486
--- /dev/null
+++ b/studio/backend/core/rag/locators.py
@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Map a chunk to highlight rectangles on its page (computed at ingest).
+
+The chunk's leading phrase is anchored in the page word list (``get_text("words")``),
+so matching survives ligatures and dehyphenation that glyph-exact ``search_for``
+misses. Matched words union per line into rects normalized to 0..1. Missing
+PyMuPDF, a too-short anchor, or no unique match yields no regions (never a guess).
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+# Anchor: up to MAX interior words from the chunk's start, shrunk toward MIN
+# to recover a unique match.
+MAX_ANCHOR_WORDS = 12
+MIN_ANCHOR_WORDS = 4
+
+
+@dataclass(frozen = True)
+class LocatorMatch:
+    page_index: int
+    page_number: int | None
+    start: int
+    end: int
+
+
+def _norm_token(token: str) -> str:
+    """Canonical match form: NFKC (decomposes ligatures), casefold, strip
+    surrounding punctuation/markdown. "" if punctuation-only."""
+    token = unicodedata.normalize("NFKC", token).casefold()
+    return token.strip(" \t\r\n*#`[]()_.,;:!?\"'“”‘’-–—…|/\\")
+
+
+def _anchor_tokens(page_text: str, match: LocatorMatch) -> list[str]:
+    """Normalized anchor tokens from the chunk's leading span. Drops first and last
+    token (boundaries often slice mid-word) when long enough."""
+    segment = page_text[match.start : match.end]
+    raw = segment.split()
+    if len(raw) >= MIN_ANCHOR_WORDS + 2:
+        raw = raw[1:-1]
+    tokens = [t for t in (_norm_token(w) for w in raw) if t]
+    return tokens[:MAX_ANCHOR_WORDS]
+
+
+def _find_subsequences(haystack: list[str], needle: list[str]) -> list[int]:
+    """Start indices where ``needle`` occurs consecutively in ``haystack``."""
+    n, m = len(haystack), len(needle)
+    if m == 0 or m > n:
+        return []
+    first = needle[0]
+    out: list[int] = []
+    for i in range(n - m + 1):
+        if haystack[i] == first and haystack[i : i + m] == needle:
+            out.append(i)
+    return out
+
+
+def _locate(page_words: list, needle: list[str]) -> list[int] | None:
+    """Matched word indices for the best anchor, or None. Tries the full anchor
+    then shorter prefixes, taking the first that matches exactly once; else the
+    first hit if still ambiguous."""
+    # Skip punctuation-only words so they never break a phrase.
+    tokens: list[str] = []
+    idx_map: list[int] = []
+    for j, w in enumerate(page_words):
+        t = _norm_token(w[4])
+        if t:
+            tokens.append(t)
+            idx_map.append(j)
+
+    ambiguous_first: list[int] | None = None
+    for size in range(len(needle), MIN_ANCHOR_WORDS - 1, -1):
+        sub = needle[:size]
+        hits = _find_subsequences(tokens, sub)
+        if len(hits) == 1:
+            p = hits[0]
+            return [idx_map[p + k] for k in range(size)]
+        if hits and ambiguous_first is None:
+            p = hits[0]
+            ambiguous_first = [idx_map[p + k] for k in range(size)]
+    return ambiguous_first
+
+
+def _rects_from_words(page_words: list, indices: list[int], pw: float, ph: float):
+    """Union matched words per (block, line) into normalized page rectangles."""
+    lines: dict[tuple, list[float]] = {}
+    for j in indices:
+        w = page_words[j]
+        x0, y0, x1, y1 = float(w[0]), float(w[1]), float(w[2]), float(w[3])
+        key = (w[5], w[6])  # block, line
+        box = lines.get(key)
+        if box is None:
+            lines[key] = [x0, y0, x1, y1]
+        else:
+            box[0], box[1] = min(box[0], x0), min(box[1], y0)
+            box[2], box[3] = max(box[2], x1), max(box[3], y1)
+
+    out: list[dict[str, Any]] = []
+    for x0, y0, x1, y1 in lines.values():
+        w = x1 - x0
+        h = y1 - y0
+        if w <= 0 or h <= 0:
+            continue
+        out.append(
+            {
+                "x": max(0.0, min(1.0, x0 / pw)),
+                "y": max(0.0, min(1.0, y0 / ph)),
+                "width": max(0.0, min(1.0, w / pw)),
+                "height": max(0.0, min(1.0, h / ph)),
+            }
+        )
+    return out
+
+
+def _regions_for_match(doc: Any, page_text: str, match: LocatorMatch) -> list[dict[str, Any]]:
+    try:
+        if match.page_index < 0 or match.page_index >= len(doc):
+            return []
+        needle = _anchor_tokens(page_text, match)
+        if len(needle) < MIN_ANCHOR_WORDS:
+            return []
+        page = doc[match.page_index]
+        page_words = page.get_text("words") or []
+        if not page_words:
+            return []
+        indices = _locate(page_words, needle)
+        if not indices:
+            return []
+        pw = float(page.rect.width)
+        ph = float(page.rect.height)
+        if pw <= 0 or ph <= 0:
+            return []
+        rects = _rects_from_words(page_words, indices, pw, ph)
+        for r in rects:
+            r["pageIndex"] = match.page_index
+            r["pageNumber"] = match.page_number
+        return rects
+    except Exception:
+        return []
+
+
+def pdf_regions_for_chunks(pdf_path: Path, pages: list, chunks: list) -> list[list[dict[str, Any]]]:
+    """Region rects per chunk (parallel to ``chunks``), keyed off each chunk's
+    ``source_page_index`` / ``page_char_start`` / ``page_char_end``. Non-PDFs and
+    failures yield [], never an exception."""
+    pdf_path = Path(pdf_path)
+    if pdf_path.suffix.lower() != ".pdf":
+        return [[] for _ in chunks]
+    try:
+        import pymupdf
+        doc = pymupdf.open(str(pdf_path))
+    except Exception:
+        return [[] for _ in chunks]
+
+    regions: list[list[dict[str, Any]]] = []
+    try:
+        for chunk in chunks:
+            page_index = getattr(chunk, "source_page_index", None)
+            start = getattr(chunk, "page_char_start", None)
+            end = getattr(chunk, "page_char_end", None)
+            if page_index is None or start is None or end is None:
+                regions.append([])
+                continue
+            if page_index < 0 or page_index >= len(pages):
+                regions.append([])
+                continue
+            match = LocatorMatch(
+                page_index = int(page_index),
+                page_number = getattr(chunk, "page_number", None),
+                start = int(start),
+                end = int(end),
+            )
+            regions.append(_regions_for_match(doc, pages[page_index].text, match))
+        return regions
+    finally:
+        doc.close()
diff --git a/studio/backend/core/rag/parsers.py b/studio/backend/core/rag/parsers.py
new file mode 100644
index 0000000000..84da941762
--- /dev/null
+++ b/studio/backend/core/rag/parsers.py
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Document parsing -> list[Page], one dispatch with lazy optional deps.
+
+PDFs keep per-page boundaries (``page_number``); txt/md/docx/html return a single
+page. ``parse(path, want_images=True)`` also returns embedded images. Heavy imports
+are lazy, so importing this module never fails on a missing dep.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from html.parser import HTMLParser
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen = True)
+class Page:
+    """A unit of extracted text. ``page_number`` is 1-based (None if N/A)."""
+
+    text: str
+    page_number: int | None = None
+    char_count: int = 0
+
+
+@dataclass(frozen = True)
+class ParsedImage:
+    """A raster image embedded in a document (PDF only)."""
+
+    image_bytes: bytes
+    page_number: int | None
+    xref: int
+
+
+def _page(text: str, page_number: int | None) -> Page:
+    return Page(text = text, page_number = page_number, char_count = len(text))
+
+
+class _Stripper(HTMLParser):
+    """Collect visible text, skipping <script>/<style>."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._skip = 0
+        self.out: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag in ("script", "style"):
+            self._skip += 1
+
+    def handle_endtag(self, tag):
+        if tag in ("script", "style") and self._skip:
+            self._skip -= 1
+
+    def handle_data(self, data):
+        if not self._skip and data.strip():
+            self.out.append(data.strip())
+
+
+def _html(raw: str) -> list[Page]:
+    parser = _Stripper()
+    parser.feed(raw)
+    return [_page("\n".join(parser.out), 1)]
+
+
+def _pdf(path: str, want_images: bool) -> tuple[list[Page], list[ParsedImage]]:
+    import fitz  # PyMuPDF
+
+    pages: list[Page] = []
+    images: list[ParsedImage] = []
+    doc = fitz.open(path)
+    try:
+        for i, page in enumerate(doc):
+            text = page.get_text("text") or ""
+            pages.append(_page(text, i + 1))
+            if want_images:
+                for img in page.get_images(full = True):
+                    xref = img[0]
+                    try:
+                        extracted = doc.extract_image(xref)
+                    except Exception as exc:  # noqa: BLE001
+                        logger.debug("skipping image xref %s: %s", xref, exc)
+                        continue
+                    image_bytes = extracted.get("image")
+                    if image_bytes:
+                        images.append(
+                            ParsedImage(
+                                image_bytes = image_bytes,
+                                page_number = i + 1,
+                                xref = xref,
+                            )
+                        )
+    finally:
+        doc.close()
+    return pages, images
+
+
+def _merge_rects(boxes: list) -> list:
+    """Union overlapping rectangles (largest-first) into figure regions."""
+    import pymupdf
+
+    rects = [pymupdf.Rect(b) for b in boxes]
+    rects = [r for r in rects if r.width > 5 and r.height > 5]
+    merged: list = []
+    for box in sorted(rects, key = lambda r: -r.get_area()):
+        placed = False
+        for m in merged:
+            if m.intersects(box):
+                m |= box
+                placed = True
+                break
+        if not placed:
+            merged.append(+box)
+    return merged
+
+
+def render_pdf_figures(
+    path: str,
+    *,
+    dpi: int = 130,
+    min_area_frac: float = 0.04,
+    min_side: float = 40.0,
+    max_figures: int = 8,
+) -> list[ParsedImage]:
+    """Detect figure regions and render each to a PNG for captioning.
+
+    Academic figures are vector, so raster extraction yields fragments; instead
+    cluster vector drawings + raster placements into boxes, keep the page-spanning
+    ones, and render them. Any failure yields [], never an exception.
+    """
+    try:
+        import pymupdf
+    except Exception:
+        return []
+
+    out: list[ParsedImage] = []
+    try:
+        doc = pymupdf.open(path)
+    except Exception:
+        return []
+    try:
+        for i, page in enumerate(doc):
+            boxes: list = []
+            try:
+                boxes.extend(info["bbox"] for info in page.get_image_info())
+            except Exception:
+                pass
+            try:
+                boxes.extend(page.cluster_drawings())
+            except Exception:
+                pass
+            if not boxes:
+                continue
+            page_area = page.rect.width * page.rect.height
+            for box in _merge_rects(boxes):
+                if (
+                    box.get_area() >= min_area_frac * page_area
+                    and box.width >= min_side
+                    and box.height >= min_side
+                ):
+                    try:
+                        pix = page.get_pixmap(dpi = dpi, clip = box)
+                        out.append(
+                            ParsedImage(
+                                image_bytes = pix.tobytes("png"),
+                                page_number = i + 1,
+                                xref = 0,
+                            )
+                        )
+                    except Exception:
+                        continue
+                    if len(out) >= max_figures:
+                        return out
+        return out
+    finally:
+        doc.close()
+
+
+def _docx(path: str) -> list[Page]:
+    import docx
+
+    document = docx.Document(path)
+    text = "\n".join(p.text for p in document.paragraphs)
+    return [_page(text, None)]
+
+
+def parse(path: str, *, want_images: bool = False):
+    """Parse a file into pages by extension. Returns ``list[Page]``, or
+    ``(list[Page], list[ParsedImage])`` when ``want_images=True`` (only PDFs yield
+    images). Raises ValueError on unsupported ext."""
+    ext = os.path.splitext(path)[1].lower()
+
+    if ext == ".pdf":
+        pages, images = _pdf(path, want_images)
+        return (pages, images) if want_images else pages
+
+    if ext == ".docx":
+        pages = _docx(path)
+        return (pages, []) if want_images else pages
+
+    if ext in (".html", ".htm", ".txt", ".md", ".markdown"):
+        with open(path, encoding = "utf-8", errors = "replace") as f:
+            raw = f.read()
+        pages = _html(raw) if ext in (".html", ".htm") else [_page(raw, None)]
+        return (pages, []) if want_images else pages
+
+    raise ValueError(f"unsupported file type: {ext}")
+
+
+def parse_text(text: str) -> list[Page]:
+    """Wrap already-extracted text as a single Page (tests / in-memory ingest)."""
+    return [_page(text, None)]
diff --git a/studio/backend/core/rag/retrieval.py b/studio/backend/core/rag/retrieval.py
new file mode 100644
index 0000000000..b16e8b1c94
--- /dev/null
+++ b/studio/backend/core/rag/retrieval.py
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Lexical (FTS5) + dense (vec0 cosine) retrieval fused via Reciprocal Rank
+Fusion. ``dense_score`` is carried so callers can apply a similarity floor."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+
+from . import config, embeddings, store
+
+
+@dataclass
+class Hit:
+    chunk_id: str
+    score: float
+    lexical_score: float | None = None
+    dense_score: float | None = None
+
+
+def retrieve_lexical(
+    conn: sqlite3.Connection,
+    scope: str,
+    query: str,
+    k: int | None = None,
+) -> list[Hit]:
+    k = k or config.TOP_K_LEXICAL
+    return [Hit(cid, s, lexical_score = s) for cid, s in store.search_lexical(conn, scope, query, k)]
+
+
+def retrieve_dense(
+    conn: sqlite3.Connection,
+    scope: str,
+    query: str,
+    k: int | None = None,
+    *,
+    model_name: str | None = None,
+) -> list[Hit]:
+    k = k or config.TOP_K_DENSE
+    vec = embeddings.encode([query], model_name = model_name, normalize = True)[0]
+    return [Hit(cid, s, dense_score = s) for cid, s in store.search_dense(conn, scope, vec, k)]
+
+
+def _rrf(rankings: list[list[Hit]], rrf_k: int, top_k: int) -> list[Hit]:
+    fused: dict[str, float] = {}
+    best: dict[str, Hit] = {}
+    for ranking in rankings:
+        for rank, hit in enumerate(ranking):
+            fused[hit.chunk_id] = fused.get(hit.chunk_id, 0.0) + 1.0 / (rrf_k + rank + 1)
+            cur = best.get(hit.chunk_id)
+            if cur is None:
+                best[hit.chunk_id] = Hit(hit.chunk_id, 0.0, hit.lexical_score, hit.dense_score)
+            else:
+                cur.lexical_score = (
+                    cur.lexical_score if cur.lexical_score is not None else hit.lexical_score
+                )
+                cur.dense_score = (
+                    cur.dense_score if cur.dense_score is not None else hit.dense_score
+                )
+    out: list[Hit] = []
+    for cid, s in sorted(fused.items(), key = lambda kv: kv[1], reverse = True)[:top_k]:
+        h = best[cid]
+        h.score = s
+        out.append(h)
+    return out
+
+
+def retrieve_hybrid(
+    conn: sqlite3.Connection,
+    scope: str,
+    query: str,
+    *,
+    k: int | None = None,
+    model_name: str | None = None,
+    mode: str = "hybrid",
+) -> list[Hit]:
+    """``mode`` picks the backend: lexical-only, dense-only, or RRF of both
+    (default). Pool sizes and the RRF constant come from config."""
+    k = k if k is not None else config.TOP_K_HYBRID
+    k = int(k)  # tool-call / scope top_k may arrive as a float; LIMIT + slice need int
+    if mode == "lexical":
+        return retrieve_lexical(conn, scope, query, k)
+    if mode == "dense":
+        return retrieve_dense(conn, scope, query, k, model_name = model_name)
+    lexical = retrieve_lexical(conn, scope, query, config.TOP_K_LEXICAL)
+    dense = retrieve_dense(conn, scope, query, config.TOP_K_DENSE, model_name = model_name)
+    return _rrf([lexical, dense], config.RRF_K, k)
+
+
+def filter_min_score(hits: list[Hit], min_score: float) -> list[Hit]:
+    """Cosine floor; gates only hits with a dense_score (lexical-only pass)."""
+    if min_score <= 0:
+        return hits
+    return [h for h in hits if h.dense_score is None or h.dense_score >= min_score]
diff --git a/studio/backend/core/rag/store.py b/studio/backend/core/rag/store.py
new file mode 100644
index 0000000000..a77b9af7f8
--- /dev/null
+++ b/studio/backend/core/rag/store.py
@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Unified SQLite store: relational chunks + FTS5 lexical + sqlite-vec dense.
+
+Module-level functions each take a ``conn`` the caller opens and closes. Inserts
+are incremental: ``add_chunks`` appends one document's rows without rebuilding the
+scope. Scope ("kb_<id>" / "thread_<id>") is a column on every table and the vec0
+partition key.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import struct
+import uuid
+from datetime import datetime, timezone
+
+from storage import rag_db
+
+
+def kb_scope(kb_id: str) -> str:
+    return f"kb_{kb_id}"
+
+
+def thread_scope(thread_id: str) -> str:
+    return f"thread_{thread_id}"
+
+
+def _f32(vector) -> bytes:
+    """Pack a vector into float32 bytes for vec0."""
+    return struct.pack(f"{len(vector)}f", *(float(x) for x in vector))
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+_TOKEN = re.compile(r"\w+", re.UNICODE)
+
+
+def _match_query(query: str) -> str:
+    """User text -> safe FTS5 OR-of-quoted-terms query; quoting defuses FTS5
+    operators. "" (no tokens) means no lexical results."""
+    toks = _TOKEN.findall(query.lower())
+    return " OR ".join(f'"{t}"' for t in toks)
+
+
+def create_kb(
+    conn: sqlite3.Connection,
+    *,
+    name: str,
+    description: str | None = None,
+    embedding_model: str | None = None,
+    kb_id: str | None = None,
+) -> str:
+    kb_id = kb_id or str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO knowledge_bases(id, name, description, embedding_model, created_at) "
+        "VALUES(?,?,?,?,?)",
+        (kb_id, name, description, embedding_model, _now()),
+    )
+    conn.commit()
+    return kb_id
+
+
+def list_kbs(conn: sqlite3.Connection) -> list[dict]:
+    rows = conn.execute("SELECT * FROM knowledge_bases ORDER BY created_at").fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_kb(conn: sqlite3.Connection, kb_id: str) -> dict | None:
+    row = conn.execute("SELECT * FROM knowledge_bases WHERE id=?", (kb_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def delete_kb(conn: sqlite3.Connection, kb_id: str) -> None:
+    """Delete a knowledge base and every document (+ chunks) under it."""
+    scope = kb_scope(kb_id)
+    doc_ids = [
+        r["id"] for r in conn.execute("SELECT id FROM documents WHERE scope=?", (scope,)).fetchall()
+    ]
+    for doc_id in doc_ids:
+        delete_document(conn, doc_id)
+    conn.execute("DELETE FROM knowledge_bases WHERE id=?", (kb_id,))
+    conn.commit()
+
+
+def create_document(
+    conn: sqlite3.Connection,
+    *,
+    scope: str,
+    filename: str,
+    sha256: str,
+    kb_id: str | None = None,
+    thread_id: str | None = None,
+    status: str = "pending",
+    stored_path: str | None = None,
+    document_id: str | None = None,
+) -> str:
+    document_id = document_id or str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO documents(id, scope, kb_id, thread_id, filename, sha256, status, "
+        "stored_path, created_at) VALUES(?,?,?,?,?,?,?,?,?)",
+        (
+            document_id,
+            scope,
+            kb_id,
+            thread_id,
+            filename,
+            sha256,
+            status,
+            stored_path,
+            _now(),
+        ),
+    )
+    conn.commit()
+    return document_id
+
+
+def set_document_status(
+    conn: sqlite3.Connection,
+    document_id: str,
+    status: str,
+    *,
+    num_chunks: int | None = None,
+    error: str | None = None,
+) -> None:
+    conn.execute(
+        "UPDATE documents SET status=?, num_chunks=COALESCE(?, num_chunks), error=? WHERE id=?",
+        (status, num_chunks, error, document_id),
+    )
+    conn.commit()
+
+
+def list_documents(conn: sqlite3.Connection, scope: str) -> list[dict]:
+    rows = conn.execute(
+        "SELECT id, scope, kb_id, thread_id, filename, sha256, status, error, num_chunks, created_at "
+        "FROM documents WHERE scope=? ORDER BY created_at DESC",
+        (scope,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_document(conn: sqlite3.Connection, document_id: str) -> dict | None:
+    row = conn.execute("SELECT * FROM documents WHERE id=?", (document_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def document_by_hash(conn: sqlite3.Connection, scope: str, sha256: str) -> str | None:
+    row = conn.execute(
+        "SELECT id FROM documents WHERE scope=? AND sha256=?", (scope, sha256)
+    ).fetchone()
+    return row["id"] if row else None
+
+
+def add_chunks(
+    conn: sqlite3.Connection,
+    scope: str,
+    document_id: str,
+    chunks,
+    vectors,
+    regions = None,
+) -> None:
+    """Incrementally index one document's chunks into chunks + FTS5 + vec0.
+    ``vectors`` parallels ``chunks``; optional ``regions`` (also parallel) holds
+    per-chunk PDF highlight rects, stored as JSON."""
+    if len(vectors):
+        rag_db.ensure_vec(conn, len(vectors[0]))
+    for i, (chunk, vector) in enumerate(zip(chunks, vectors)):
+        chunk_id = f"{document_id}:{chunk.chunk_index}"
+        chunk_regions = regions[i] if regions and i < len(regions) else None
+        regions_json = json.dumps(chunk_regions) if chunk_regions else None
+        conn.execute(
+            "INSERT OR REPLACE INTO chunks("
+            "id, document_id, scope, chunk_index, text, page_number, "
+            "source_page_index, token_count, kind, pdf_regions_json) "
+            "VALUES(?,?,?,?,?,?,?,?,?,?)",
+            (
+                chunk_id,
+                document_id,
+                scope,
+                chunk.chunk_index,
+                chunk.text,
+                chunk.page_number,
+                chunk.source_page_index,
+                chunk.token_count,
+                getattr(chunk, "kind", "text"),
+                regions_json,
+            ),
+        )
+        conn.execute(
+            "INSERT INTO chunks_fts(text, chunk_id, scope) VALUES(?,?,?)",
+            (chunk.text, chunk_id, scope),
+        )
+        conn.execute(
+            "INSERT INTO chunks_vec(scope, chunk_id, embedding) VALUES(?,?,?)",
+            (scope, chunk_id, _f32(vector)),
+        )
+    conn.commit()
+
+
+def delete_document(conn: sqlite3.Connection, document_id: str) -> None:
+    """Remove a document and all its chunks (+ fts + vec rows)."""
+    ids = [
+        r["id"]
+        for r in conn.execute(
+            "SELECT id FROM chunks WHERE document_id=?", (document_id,)
+        ).fetchall()
+    ]
+    has_vec = rag_db.vec_table_exists(conn)
+    for chunk_id in ids:
+        conn.execute("DELETE FROM chunks_fts WHERE chunk_id=?", (chunk_id,))
+        if has_vec:
+            conn.execute("DELETE FROM chunks_vec WHERE chunk_id=?", (chunk_id,))
+    conn.execute("DELETE FROM chunks WHERE document_id=?", (document_id,))
+    conn.execute("DELETE FROM documents WHERE id=?", (document_id,))
+    conn.commit()
+
+
+def search_lexical(conn: sqlite3.Connection, scope: str, query: str, k: int):
+    """BM25 lexical search. Returns [(chunk_id, score)], higher = better."""
+    mq = _match_query(query)
+    if not mq:
+        return []
+    rows = conn.execute(
+        "SELECT chunk_id, bm25(chunks_fts) AS s FROM chunks_fts "
+        "WHERE chunks_fts MATCH ? AND scope=? ORDER BY s LIMIT ?",
+        (mq, scope, k),
+    ).fetchall()
+    # bm25() is negative (more negative = better); flip to higher-is-better.
+    return [(r["chunk_id"], -r["s"]) for r in rows]
+
+
+def search_dense(conn: sqlite3.Connection, scope: str, vector, k: int):
+    """Cosine KNN over vec0. Returns [(chunk_id, 1 - distance)]."""
+    if not rag_db.vec_table_exists(conn):
+        return []
+    rows = conn.execute(
+        "SELECT chunk_id, distance FROM chunks_vec "
+        "WHERE scope=? AND embedding MATCH ? ORDER BY distance LIMIT ?",
+        (scope, _f32(vector), k),
+    ).fetchall()
+    return [(r["chunk_id"], 1.0 - r["distance"]) for r in rows]
+
+
+def chunks_by_id(conn: sqlite3.Connection, ids) -> dict:
+    """Hydrate chunk rows (joined with document filename), keyed by id."""
+    if not ids:
+        return {}
+    placeholders = ",".join("?" * len(ids))
+    rows = conn.execute(
+        f"SELECT c.id, c.text, c.document_id, c.chunk_index, c.page_number, "
+        f"c.source_page_index, d.filename "
+        f"FROM chunks c JOIN documents d ON d.id=c.document_id "
+        f"WHERE c.id IN ({placeholders})",
+        list(ids),
+    ).fetchall()
+    return {r["id"]: r for r in rows}
diff --git a/studio/backend/core/rag/tool.py b/studio/backend/core/rag/tool.py
new file mode 100644
index 0000000000..1b0d87590a
--- /dev/null
+++ b/studio/backend/core/rag/tool.py
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""``search_knowledge_base`` LLM tool: scope resolution + hit formatting.
+
+KB scope wins over thread scope. Hits render as ``<chunk>`` blocks for the model,
+plus a parallel citation source-map for clickable sources. Each call opens and
+closes its own ``rag_db`` connection.
+"""
+
+from __future__ import annotations
+
+from xml.sax.saxutils import quoteattr
+
+from storage import rag_db
+
+from . import config, retrieval
+from .store import kb_scope, thread_scope
+
+SEARCH_KNOWLEDGE_BASE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "search_knowledge_base",
+        "description": (
+            "Search the user's uploaded documents and knowledge bases for relevant passages."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Natural-language search query.",
+                },
+                "top_k": {
+                    "type": "integer",
+                    "description": "Max chunks to return.",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+}
+
+
+def _resolve_scope(scope_kb_id: str | None, scope_thread_id: str | None) -> str | None:
+    if scope_kb_id:
+        return kb_scope(scope_kb_id)
+    if scope_thread_id:
+        return thread_scope(scope_thread_id)
+    return None
+
+
+def _format(rows, hits) -> tuple[str, list[dict]]:
+    """Render hits as ``<chunk>`` blocks and build a citation source-map."""
+    if not hits:
+        return "No matching chunks were found in the knowledge base.", []
+    blocks: list[str] = []
+    sources: list[dict] = []
+    for i, h in enumerate(hits, 1):
+        r = rows.get(h.chunk_id)
+        filename = (r["filename"] if r else None) or "unknown"
+        page = r["page_number"] if r else None
+        text = r["text"] if r else ""
+        src = quoteattr(filename)
+        page_attr = f" page={quoteattr(str(page))}" if page else ""
+        blocks.append(f'<chunk id="{i}" source={src}{page_attr}>\n{text}\n</chunk>')
+        sources.append(
+            {
+                "citationId": i,
+                "chunkId": h.chunk_id,
+                "documentId": r["document_id"] if r else None,
+                "filename": filename,
+                "page": page,
+                "text": text,
+                "score": round(float(h.score), 4) if h.score is not None else None,
+            }
+        )
+    return "\n\n".join(blocks), sources
+
+
+def search_knowledge_base_with_sources(
+    *,
+    query: str,
+    scope_kb_id: str | None = None,
+    scope_thread_id: str | None = None,
+    top_k: int | None = None,
+    min_score: float = 0.0,
+    model_name: str | None = None,
+    mode: str = "hybrid",
+) -> tuple[str, list[dict]]:
+    """Search -> ``(rendered_text, citation_sources)``; each source aligns with a
+    rendered ``<chunk>`` block's ``id``."""
+    if not query or not query.strip():
+        return "Error: query is empty.", []
+    scope = _resolve_scope(scope_kb_id, scope_thread_id)
+    if scope is None:
+        return "No documents are attached to this chat.", []
+
+    conn = rag_db.get_connection()
+    try:
+        hits = retrieval.retrieve_hybrid(
+            conn,
+            scope,
+            query,
+            k = top_k or config.TOP_K_HYBRID,
+            model_name = model_name,
+            mode = mode,
+        )
+        hits = retrieval.filter_min_score(hits, min_score)
+        rows = store_rows(conn, hits)
+    finally:
+        conn.close()
+    return _format(rows, hits)
+
+
+def store_rows(conn, hits):
+    """Hydrate chunk rows for a list of hits."""
+    from . import store
+    return store.chunks_by_id(conn, [h.chunk_id for h in hits])
+
+
+def search_for_autoinject(
+    *,
+    query: str,
+    scope_kb_id: str | None = None,
+    scope_thread_id: str | None = None,
+    top_k: int | None = None,
+    min_dense_score: float = 0.70,
+    model_name: str | None = None,
+    mode: str = "hybrid",
+) -> tuple[str, list[dict]] | None:
+    """Forced-retrieval variant for auto-injection.
+
+    Returns ``(rendered_text, sources)`` only if some hit's cosine clears
+    ``min_dense_score``, else ``None`` (inject nothing). The dense gate keeps
+    weak/off-topic matches out of answers. In ``lexical`` mode hits carry no
+    cosine, so the gate falls back to a dense 1-NN probe.
+    """
+    if not query or not query.strip():
+        return None
+    scope = _resolve_scope(scope_kb_id, scope_thread_id)
+    if scope is None:
+        return None
+    k = top_k or config.TOP_K_HYBRID
+    conn = rag_db.get_connection()
+    try:
+        hits = retrieval.retrieve_hybrid(
+            conn,
+            scope,
+            query,
+            k = k,
+            model_name = model_name,
+            mode = mode,
+        )
+        strong = [
+            h for h in hits if h.dense_score is not None and h.dense_score >= min_dense_score
+        ][:k]
+        if not strong and hits and mode == "lexical":
+            probe = retrieval.retrieve_dense(conn, scope, query, 1, model_name = model_name)
+            if (
+                probe
+                and probe[0].dense_score is not None
+                and (probe[0].dense_score >= min_dense_score)
+            ):
+                strong = hits[:k]
+        if not strong:
+            return None
+        rows = store_rows(conn, strong)
+    finally:
+        conn.close()
+    text, sources = _format(rows, strong)
+    return (text, sources) if sources else None
+
+
+def search_knowledge_base(
+    *,
+    query: str,
+    scope_kb_id: str | None = None,
+    scope_thread_id: str | None = None,
+    top_k: int | None = None,
+    min_score: float = 0.0,
+    model_name: str | None = None,
+) -> str:
+    """Text-only variant of :func:`search_knowledge_base_with_sources`."""
+    text, _sources = search_knowledge_base_with_sources(
+        query = query,
+        scope_kb_id = scope_kb_id,
+        scope_thread_id = scope_thread_id,
+        top_k = top_k,
+        min_score = min_score,
+        model_name = model_name,
+    )
+    return text
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 1794e0a9af..35c955405e 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -7,6 +7,7 @@ Main FastAPI application for Unsloth UI Backend
 
 import os
 import sys
+import threading
 from pathlib import Path as _Path
 import asyncio
 from dataclasses import asdict
@@ -216,6 +217,7 @@ from routes import (
     mcp_servers_router,
     models_router,
     providers_router,
+    rag_router,
     training_history_router,
     training_router,
 )
@@ -230,6 +232,7 @@ from hub.utils.download_registry import (
     terminate_active_downloads as terminate_hub_downloads,
 )
 from routes.settings import router as settings_router
+from routes.prompts import router as prompts_router
 from auth import storage
 from auth.authentication import get_current_subject
 from utils.hardware import (
@@ -374,6 +377,21 @@ async def lifespan(app: FastAPI):
 
     _start_helper_precache_if_enabled()
 
+    # Warm the RAG embedder so the first upload skips the cold load. Non-fatal.
+    def _warm_rag_embedder():
+        try:
+            from storage import rag_db
+
+            if not rag_db.RAG_AVAILABLE:
+                return
+            from core.rag import embeddings
+
+            embeddings.warm()
+        except Exception:
+            pass
+
+    threading.Thread(target = _warm_rag_embedder, daemon = True).start()
+
     # Initialize RSA key pair for API key encryption (external providers)
     from core.inference.key_exchange import init_key_pair
 
@@ -738,9 +756,11 @@ app.include_router(inference_router, prefix = "/v1", tags = ["openai-compat"])
 app.include_router(providers_router, prefix = "/api/providers", tags = ["providers"])
 app.include_router(settings_router, prefix = "/api/settings", tags = ["settings"])
 app.include_router(mcp_servers_router, prefix = "/api/mcp/servers", tags = ["mcp"])
+app.include_router(prompts_router, prefix = "/api/prompts", tags = ["prompts"])
 app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"])
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
 app.include_router(export_router, prefix = "/api/export", tags = ["export"])
+app.include_router(rag_router, prefix = "/api/rag", tags = ["rag"])
 app.include_router(training_history_router, prefix = "/api/train", tags = ["training-history"])
 app.include_router(hub_inventory_router, prefix = "/api/hub", tags = ["hub"])
 app.include_router(hub_datasets_router, prefix = "/api/hub/datasets", tags = ["hub"])
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 3482303eeb..9c12f8faac 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -694,6 +694,16 @@ class ChatCompletionRequest(BaseModel):
         None,
         description = "[x-unsloth] Session/thread ID for scoping tool execution sandbox.",
     )
+    rag_scope: Optional[dict] = Field(
+        None,
+        description = (
+            "[x-unsloth] Hidden RAG retrieval scope for the search_knowledge_base "
+            "tool: {kb_id?, thread_id?, default_top_k?, mode?, autoinject?, "
+            "autoinject_min_score?}. Candidate pools and the RRF constant come from "
+            "server config. The model never sees this; the server resolves which "
+            "documents to search."
+        ),
+    )
     cancel_id: Optional[str] = Field(
         None,
         description = "[x-unsloth] Per-request cancellation token. Frontend sends a fresh UUID per run so /inference/cancel matches one specific generation.",
diff --git a/studio/backend/requirements/studio.txt b/studio/backend/requirements/studio.txt
index d6eba73245..9bffb81549 100644
--- a/studio/backend/requirements/studio.txt
+++ b/studio/backend/requirements/studio.txt
@@ -19,3 +19,8 @@ ddgs
 cryptography>=42.0.0
 httpx>=0.27.0
 fastmcp>=3.0.2
+# RAG (knowledge bases, hybrid retrieval). sentence-transformers lives in
+# extras-no-deps.txt; these add the lexical+dense store and document parsing.
+sqlite-vec==0.1.9
+pymupdf==1.27.2.3
+python-docx==1.2.0
diff --git a/studio/backend/routes/__init__.py b/studio/backend/routes/__init__.py
index ee3ab61b6e..2a3baac631 100644
--- a/studio/backend/routes/__init__.py
+++ b/studio/backend/routes/__init__.py
@@ -17,6 +17,7 @@ from routes.training_history import router as training_history_router
 from routes.chat_history import router as chat_history_router
 from routes.providers import router as providers_router
 from routes.mcp_servers import router as mcp_servers_router
+from routes.rag import router as rag_router
 
 __all__ = [
     "training_router",
@@ -31,4 +32,8 @@ __all__ = [
     "chat_history_router",
     "providers_router",
     "mcp_servers_router",
+    "rag_router",
 ]
+
+# Bind the re-export so the import-hoist verifier counts it as used.
+_ = (rag_router,)
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 81bc9ff628..9f0bb43c9a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -81,6 +81,34 @@ def _install_httpcore_asyncgen_silencer() -> None:
 _install_httpcore_asyncgen_silencer()
 
 
+def _loaded_chat_template() -> Optional[str]:
+    """Chat template of the currently loaded GGUF model, if any."""
+    try:
+        return get_llama_cpp_backend().chat_template
+    except Exception:
+        return None
+
+
+def _template_raise_message(error_text: str, chat_template: Optional[str]) -> Optional[str]:
+    """A chat-template raise_exception message to surface, but only when it appears
+    verbatim in chat_template (simple substring check), so we never leak arbitrary
+    llama-server text. Anchors on llama.cpp's "Jinja Exception:" prefix."""
+    if not chat_template:
+        return None
+    marker = "Jinja Exception:"
+    idx = error_text.find(marker)
+    if idx == -1:
+        return None
+    candidate = error_text[idx + len(marker) :]
+    # llama-server appends JSON after the message; cut at the first boundary.
+    for stop in ('"', "\n"):
+        cut = candidate.find(stop)
+        if cut != -1:
+            candidate = candidate[:cut]
+    candidate = candidate.strip()
+    return candidate if candidate and candidate in chat_template else None
+
+
 def _friendly_error(exc: Exception) -> str:
     """Extract a user-friendly message from known llama-server errors."""
     # httpx transport failures from the async pass-through helpers. Any
@@ -106,6 +134,9 @@ def _friendly_error(exc: Exception) -> str:
         return (
             "Lost connection to the model server. It may have crashed -- try reloading the model."
         )
+    template_msg = _template_raise_message(msg, _loaded_chat_template())
+    if template_msg:
+        return f"An internal error occurred: {template_msg}"
     return "An internal error occurred"
 
 
@@ -3088,6 +3119,12 @@ async def openai_chat_completions(
             else:
                 tools_to_use = ALL_TOOLS
 
+            # Drop the RAG tool without a scope: nothing to search over.
+            if not payload.rag_scope:
+                tools_to_use = [
+                    t for t in tools_to_use if t["function"]["name"] != "search_knowledge_base"
+                ]
+
             if _mcp_allowed:
                 tools_to_use = tools_to_use + await get_enabled_mcp_tools()
 
@@ -3108,6 +3145,21 @@ async def openai_chat_completions(
                 model_name = model_name,
             )
 
+            # Nudge the model to ground in attached documents instead of memory.
+            _tool_names = {(t.get("function") or {}).get("name") for t in (tools_to_use or [])}
+            _rag_active = "search_knowledge_base" in _tool_names and payload.rag_scope
+            if _rag_active:
+                _rag_nudge = (
+                    "The user has attached documents to this conversation. Relevant "
+                    "passages are retrieved and provided to you automatically; base "
+                    "your answer on them and cite them. You can also call "
+                    "search_knowledge_base to look for more. Do not answer from "
+                    "memory when the attached documents are relevant."
+                )
+                # Prefix the date when the tool nudge is empty (RAG-only tool set).
+                _date_line = f"The current date is {_date.today().isoformat()}."
+                _nudge = _date_line + " " + _rag_nudge if not _nudge else _nudge + " " + _rag_nudge
+
             if _nudge:
                 # Append nudge to system prompt (preserve user's prompt)
                 if system_prompt:
@@ -3153,6 +3205,7 @@ async def openai_chat_completions(
                     if payload.tool_call_timeout is not None
                     else 300,
                     session_id = payload.session_id,
+                    rag_scope = payload.rag_scope,
                     disable_parallel_tool_use = payload.parallel_tool_calls is False,
                 )
 
@@ -3592,6 +3645,12 @@ async def openai_chat_completions(
         else:
             _sf_tools_to_use = ALL_TOOLS
 
+        # Drop the RAG tool unless the request carries a retrieval scope.
+        if not payload.rag_scope:
+            _sf_tools_to_use = [
+                t for t in _sf_tools_to_use if t["function"]["name"] != "search_knowledge_base"
+            ]
+
         if _sf_mcp_allowed:
             _sf_tools_to_use = _sf_tools_to_use + await get_enabled_mcp_tools()
 
@@ -3607,6 +3666,25 @@ async def openai_chat_completions(
             model_name = model_name,
         )
 
+        # RAG nudge, mirroring the GGUF path.
+        _sf_tool_names = {(t.get("function") or {}).get("name") for t in (_sf_tools_to_use or [])}
+        _sf_rag_active = "search_knowledge_base" in _sf_tool_names and payload.rag_scope
+        if _sf_rag_active:
+            _sf_rag_nudge = (
+                "The user has attached documents to this conversation. Relevant "
+                "passages are retrieved and provided to you automatically; base "
+                "your answer on them and cite them. You can also call "
+                "search_knowledge_base to look for more. Do not answer from "
+                "memory when the attached documents are relevant."
+            )
+            # Prefix the date when the tool nudge is empty (RAG-only tool set).
+            _sf_date_line = f"The current date is {_date.today().isoformat()}."
+            _sf_nudge = (
+                _sf_date_line + " " + _sf_rag_nudge
+                if not _sf_nudge
+                else _sf_nudge + " " + _sf_rag_nudge
+            )
+
         _sf_system_prompt = system_prompt
         if _sf_nudge:
             if _sf_system_prompt:
@@ -3658,6 +3736,7 @@ async def openai_chat_completions(
                 if payload.tool_call_timeout is not None
                 else 300,
                 session_id = payload.session_id,
+                rag_scope = payload.rag_scope,
                 use_adapter = payload.use_adapter,
                 stats_holder = _sf_stats_holder,
             )
@@ -5439,6 +5518,8 @@ async def anthropic_messages(
                 auto_heal_tool_calls = True,
                 tool_call_timeout = 300,
                 session_id = payload.session_id,
+                # Anthropic passthrough has no rag_scope field (RAG is local-only).
+                rag_scope = getattr(payload, "rag_scope", None),
                 disable_parallel_tool_use = _disable_parallel,
             )
 
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index ce4e41a062..7151af33f3 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -39,6 +39,18 @@ def _safe_is_dir(path) -> bool:
         return False
 
 
+def _is_hidden_model(*values: str | None) -> bool:
+    """True if any id/path is the RAG embedding model (EMBEDDING_MODEL or
+    EMBED_GGUF_REPO basename), so pickers hide it (GGUF and non-GGUF)."""
+    from core.rag import config as rag_config
+
+    needles = (
+        rag_config.EMBEDDING_MODEL.split("/")[-1].lower(),
+        rag_config.EMBED_GGUF_REPO.split("/")[-1].lower(),
+    )
+    return any(v and any(n in v.lower() for n in needles) for v in values)
+
+
 backend_path = Path(__file__).parent.parent.parent
 if str(backend_path) not in sys.path:
     sys.path.insert(0, str(backend_path))
@@ -754,6 +766,7 @@ async def list_local_models(
             key = lambda item: (item.updated_at or 0),
             reverse = True,
         )
+        models = [m for m in models if not _is_hidden_model(m.id, m.path)]
 
         return LocalModelListResponse(
             models_dir = str(models_root),
@@ -2379,6 +2392,8 @@ async def list_cached_gguf(current_subject: str = Depends(get_current_subject)):
                     if repo_info.repo_type != "model":
                         continue
                     repo_id = repo_info.repo_id
+                    if _is_hidden_model(repo_id):
+                        continue
                     total_size = _repo_gguf_size_bytes(repo_info)
                     if total_size == 0:
                         continue
@@ -2416,6 +2431,8 @@ async def list_cached_models(current_subject: str = Depends(get_current_subject)
                     if repo_info.repo_type != "model":
                         continue
                     repo_id = repo_info.repo_id
+                    if _is_hidden_model(repo_id):
+                        continue
                     if _repo_has_gguf_files(repo_info):
                         continue
                     total_size = sum(
diff --git a/studio/backend/routes/prompts.py b/studio/backend/routes/prompts.py
new file mode 100644
index 0000000000..df81008766
--- /dev/null
+++ b/studio/backend/routes/prompts.py
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""
+Prompt storage API routes backed by studio.db.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from auth.authentication import get_current_subject
+from storage.studio_db import (
+    bulk_upsert_prompt_entries,
+    bulk_upsert_prompt_lists,
+    delete_prompt_entry,
+    delete_prompt_list_db,
+    list_prompt_entries,
+    list_prompt_lists_db,
+    upsert_prompt_entry,
+    upsert_prompt_list,
+)
+
+router = APIRouter()
+
+
+class PromptEntry(BaseModel):
+    id: str = Field(max_length = 128)
+    name: str = Field(max_length = 500)
+    text: str = Field(max_length = 100_000)
+    createdAt: int
+    updatedAt: int
+
+
+class PromptList(BaseModel):
+    id: str = Field(max_length = 128)
+    name: str = Field(max_length = 500)
+    items: list[str] = Field(max_length = 10_000)
+    createdAt: int
+    updatedAt: int
+
+
+class BulkEntriesRequest(BaseModel):
+    entries: list[PromptEntry]
+
+
+class BulkListsRequest(BaseModel):
+    lists: list[PromptList]
+
+
+@router.get("/entries")
+def get_entries(current_subject: str = Depends(get_current_subject)):
+    return {"entries": list_prompt_entries()}
+
+
+@router.put("/entries/{entry_id}")
+def put_entry(
+    entry_id: str,
+    entry: PromptEntry,
+    current_subject: str = Depends(get_current_subject),
+):
+    if entry.id != entry_id:
+        raise HTTPException(status_code = 400, detail = "ID mismatch")
+    return upsert_prompt_entry(entry.model_dump())
+
+
+@router.delete("/entries/{entry_id}", status_code = 204)
+def remove_entry(entry_id: str, current_subject: str = Depends(get_current_subject)):
+    delete_prompt_entry(entry_id)
+
+
+@router.post("/entries/bulk")
+def bulk_entries(req: BulkEntriesRequest, current_subject: str = Depends(get_current_subject)):
+    count = bulk_upsert_prompt_entries([e.model_dump() for e in req.entries])
+    return {"count": count}
+
+
+@router.get("/lists")
+def get_lists(current_subject: str = Depends(get_current_subject)):
+    return {"lists": list_prompt_lists_db()}
+
+
+@router.put("/lists/{list_id}")
+def put_list(
+    list_id: str,
+    lst: PromptList,
+    current_subject: str = Depends(get_current_subject),
+):
+    if lst.id != list_id:
+        raise HTTPException(status_code = 400, detail = "ID mismatch")
+    return upsert_prompt_list(lst.model_dump())
+
+
+@router.delete("/lists/{list_id}", status_code = 204)
+def remove_list(list_id: str, current_subject: str = Depends(get_current_subject)):
+    delete_prompt_list_db(list_id)
+
+
+@router.post("/lists/bulk")
+def bulk_lists(req: BulkListsRequest, current_subject: str = Depends(get_current_subject)):
+    count = bulk_upsert_prompt_lists([l.model_dump() for l in req.lists])
+    return {"count": count}
diff --git a/studio/backend/routes/rag.py b/studio/backend/routes/rag.py
new file mode 100644
index 0000000000..8aba73caac
--- /dev/null
+++ b/studio/backend/routes/rag.py
@@ -0,0 +1,456 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""HTTP API for the RAG engine: KB CRUD, uploads, SSE ingestion, search.
+
+Single-tenant: the subject gates access, not data. Without sqlite-vec the router
+mounts but every endpoint returns 503.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import os
+import re
+import secrets
+import time
+import uuid
+
+from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse, StreamingResponse
+from pydantic import BaseModel, Field
+
+from auth.authentication import get_current_subject
+from core.rag import config, ingestion, retrieval, store
+from storage import rag_db
+from utils.paths import ensure_dir, rag_uploads_root
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _require_rag() -> None:
+    if not rag_db.RAG_AVAILABLE:
+        raise HTTPException(
+            status_code = 503,
+            detail = "RAG is unavailable: the sqlite-vec extension could not be loaded.",
+        )
+
+
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def _sanitize_filename(name: str) -> str:
+    base = os.path.basename(name or "").strip() or "document"
+    base = _SAFE.sub("_", base)
+    return base[:200]
+
+
+def _save_upload(file: UploadFile) -> tuple[str, str]:
+    """Persist an upload; returns (stored_path, filename)."""
+    filename = _sanitize_filename(file.filename or "document")
+    ext = os.path.splitext(filename)[1].lower()
+    if ext not in config.UPLOAD_EXTS:
+        raise HTTPException(
+            status_code = 400,
+            detail = f"Unsupported file type '{ext}'. Allowed: {sorted(config.UPLOAD_EXTS)}",
+        )
+    uploads = ensure_dir(rag_uploads_root())
+    stored_path = str(uploads / f"{uuid.uuid4().hex}{ext}")
+    size = 0
+    with open(stored_path, "wb") as out:
+        while True:
+            block = file.file.read(1 << 20)
+            if not block:
+                break
+            size += len(block)
+            out.write(block)
+    if size == 0:
+        os.remove(stored_path)
+        raise HTTPException(status_code = 400, detail = "Uploaded file is empty.")
+    return stored_path, filename
+
+
+def _doc_view(row: dict) -> dict:
+    return {
+        "id": row["id"],
+        "filename": row["filename"],
+        "status": row["status"],
+        "error": row.get("error"),
+        "numChunks": row.get("num_chunks") or 0,
+        "kbId": row.get("kb_id"),
+        "threadId": row.get("thread_id"),
+        "createdAt": row.get("created_at"),
+    }
+
+
+class CreateKbRequest(BaseModel):
+    name: str = Field(min_length = 1, max_length = 200)
+    description: str | None = None
+
+
+class UpdateKbRequest(BaseModel):
+    name: str | None = Field(default = None, max_length = 200)
+    description: str | None = None
+
+
+class SearchRequest(BaseModel):
+    query: str
+    kb_id: str | None = None
+    thread_id: str | None = None
+    top_k: int = Field(default = config.TOP_K_HYBRID, ge = 1, le = 50)
+    min_score: float = 0.0
+    mode: str = "hybrid"  # hybrid | lexical | dense
+
+
+@router.get("/knowledge-bases")
+def list_knowledge_bases(subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        kbs = store.list_kbs(conn)
+        out = []
+        for kb in kbs:
+            docs = store.list_documents(conn, store.kb_scope(kb["id"]))
+            out.append(
+                {
+                    "id": kb["id"],
+                    "name": kb["name"],
+                    "description": kb.get("description"),
+                    "createdAt": kb.get("created_at"),
+                    "documentCount": len(docs),
+                }
+            )
+        return {"knowledgeBases": out}
+    finally:
+        conn.close()
+
+
+@router.post("/knowledge-bases")
+def create_knowledge_base(
+    payload: CreateKbRequest, subject: str = Depends(get_current_subject)
+) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        kb_id = store.create_kb(
+            conn,
+            name = payload.name.strip(),
+            description = (payload.description or None),
+            embedding_model = config.EMBEDDING_MODEL,
+        )
+        return {"id": kb_id, "name": payload.name.strip()}
+    finally:
+        conn.close()
+
+
+@router.patch("/knowledge-bases/{kb_id}")
+def update_knowledge_base(
+    kb_id: str,
+    payload: UpdateKbRequest,
+    subject: str = Depends(get_current_subject),
+) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        if store.get_kb(conn, kb_id) is None:
+            raise HTTPException(status_code = 404, detail = "Knowledge base not found")
+        sets, params = [], []
+        if payload.name is not None:
+            sets.append("name=?")
+            params.append(payload.name.strip())
+        if payload.description is not None:
+            sets.append("description=?")
+            params.append(payload.description or None)
+        if sets:
+            params.append(kb_id)
+            conn.execute(f"UPDATE knowledge_bases SET {', '.join(sets)} WHERE id=?", params)
+            conn.commit()
+        return {"ok": True}
+    finally:
+        conn.close()
+
+
+@router.delete("/knowledge-bases/{kb_id}")
+def delete_knowledge_base(kb_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        if store.get_kb(conn, kb_id) is None:
+            raise HTTPException(status_code = 404, detail = "Knowledge base not found")
+        store.delete_kb(conn, kb_id)
+        return {"ok": True}
+    finally:
+        conn.close()
+
+
+@router.post("/knowledge-bases/{kb_id}/documents")
+async def upload_kb_document(
+    kb_id: str,
+    file: UploadFile = File(...),
+    subject: str = Depends(get_current_subject),
+) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        if store.get_kb(conn, kb_id) is None:
+            raise HTTPException(status_code = 404, detail = "Knowledge base not found")
+    finally:
+        conn.close()
+    stored_path, filename = _save_upload(file)
+    document_id, job_id = ingestion.start_ingestion(
+        store.kb_scope(kb_id), kb_id, None, filename, stored_path
+    )
+    return {"documentId": document_id, "jobId": job_id, "filename": filename}
+
+
+@router.get("/knowledge-bases/{kb_id}/documents")
+def list_kb_documents(kb_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        docs = store.list_documents(conn, store.kb_scope(kb_id))
+        return {"documents": [_doc_view(d) for d in docs]}
+    finally:
+        conn.close()
+
+
+@router.post("/threads/{thread_id}/documents")
+async def upload_thread_document(
+    thread_id: str,
+    file: UploadFile = File(...),
+    subject: str = Depends(get_current_subject),
+) -> dict:
+    _require_rag()
+    stored_path, filename = _save_upload(file)
+    document_id, job_id = ingestion.start_ingestion(
+        store.thread_scope(thread_id), None, thread_id, filename, stored_path
+    )
+    return {"documentId": document_id, "jobId": job_id, "filename": filename}
+
+
+@router.get("/threads/{thread_id}/documents")
+def list_thread_documents(thread_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        docs = store.list_documents(conn, store.thread_scope(thread_id))
+        return {"documents": [_doc_view(d) for d in docs]}
+    finally:
+        conn.close()
+
+
+@router.delete("/documents/{document_id}")
+def delete_document(document_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        if store.get_document(conn, document_id) is None:
+            raise HTTPException(status_code = 404, detail = "Document not found")
+        store.delete_document(conn, document_id)
+        return {"ok": True}
+    finally:
+        conn.close()
+
+
+@router.get("/jobs/{job_id}")
+def job_status(job_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    row = ingestion.get_job_status(job_id)
+    if row is None:
+        raise HTTPException(status_code = 404, detail = "Job not found")
+    return {
+        "id": row["id"],
+        "documentId": row["document_id"],
+        "status": row["status"],
+        "stage": row.get("stage"),
+        "progress": row.get("progress") or 0.0,
+        "error": row.get("error"),
+    }
+
+
+@router.get("/jobs/{job_id}/events")
+def job_events(job_id: str, subject: str = Depends(get_current_subject)) -> StreamingResponse:
+    _require_rag()
+
+    def gen():
+        try:
+            for event in ingestion.job_events(job_id):
+                yield f"data: {json.dumps(event)}\n\n"
+        except Exception as exc:  # noqa: BLE001
+            yield f"data: {json.dumps({'type': 'error', 'error': str(exc)})}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        gen(),
+        media_type = "text/event-stream",
+        headers = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+@router.post("/search")
+def search(payload: SearchRequest, subject: str = Depends(get_current_subject)) -> dict:
+    _require_rag()
+    if payload.kb_id:
+        scope = store.kb_scope(payload.kb_id)
+    elif payload.thread_id:
+        scope = store.thread_scope(payload.thread_id)
+    else:
+        raise HTTPException(status_code = 400, detail = "Provide kb_id or thread_id")
+
+    conn = rag_db.get_connection()
+    try:
+        if payload.mode == "lexical":
+            hits = retrieval.retrieve_lexical(conn, scope, payload.query, payload.top_k)
+        elif payload.mode == "dense":
+            hits = retrieval.retrieve_dense(conn, scope, payload.query, payload.top_k)
+        else:
+            hits = retrieval.retrieve_hybrid(conn, scope, payload.query, k = payload.top_k)
+        hits = retrieval.filter_min_score(hits, payload.min_score)
+        rows = store.chunks_by_id(conn, [h.chunk_id for h in hits])
+        results = []
+        for h in hits:
+            r = rows.get(h.chunk_id)
+            if r is None:
+                continue
+            results.append(
+                {
+                    "chunkId": h.chunk_id,
+                    "documentId": r["document_id"],
+                    "filename": r["filename"],
+                    "page": r["page_number"],
+                    "score": h.score,
+                    "text": r["text"],
+                }
+            )
+        return {"results": results}
+    finally:
+        conn.close()
+
+
+# Per-process secret so pdf.js range requests fetch the file without a bearer
+# header; tokens only work on this server instance.
+_PREVIEW_SECRET = secrets.token_bytes(32)
+_PREVIEW_TTL = 600  # seconds
+
+_CONTENT_TYPES = {
+    ".pdf": "application/pdf",
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".markdown": "text/markdown; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".htm": "text/html; charset=utf-8",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+}
+
+
+def _sign_document(document_id: str) -> str:
+    exp = int(time.time()) + _PREVIEW_TTL
+    payload = f"{document_id}.{exp}"
+    sig = hmac.new(_PREVIEW_SECRET, payload.encode(), hashlib.sha256).hexdigest()
+    return f"{payload}.{sig}"
+
+
+def _verify_document_token(token: str) -> str | None:
+    try:
+        document_id, exp_s, sig = token.rsplit(".", 2)
+    except ValueError:
+        return None
+    expected = hmac.new(
+        _PREVIEW_SECRET, f"{document_id}.{exp_s}".encode(), hashlib.sha256
+    ).hexdigest()
+    if not hmac.compare_digest(sig, expected):
+        return None
+    try:
+        if int(exp_s) < int(time.time()):
+            return None
+    except ValueError:
+        return None
+    return document_id
+
+
+@router.get("/documents/{document_id}/preview-target")
+def preview_target(
+    document_id: str,
+    chunk_id: str | None = Query(default = None),
+    subject: str = Depends(get_current_subject),
+) -> dict:
+    """Resolve a citation to filename, page, and highlight regions."""
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        doc = store.get_document(conn, document_id)
+        if doc is None:
+            raise HTTPException(status_code = 404, detail = "Document not found")
+        ext = os.path.splitext(doc["filename"])[1].lower()
+        out = {
+            "documentId": document_id,
+            "filename": doc["filename"],
+            "mediaKind": "pdf" if ext == ".pdf" else "text",
+            "targetPage": None,
+            "pdfRegions": [],
+            "text": None,
+        }
+        if chunk_id:
+            row = conn.execute(
+                "SELECT text, page_number, pdf_regions_json FROM chunks WHERE id=?",
+                (chunk_id,),
+            ).fetchone()
+            if row is not None:
+                out["text"] = row["text"]
+                out["targetPage"] = row["page_number"]
+                if row["pdf_regions_json"]:
+                    try:
+                        out["pdfRegions"] = json.loads(row["pdf_regions_json"])
+                    except Exception:
+                        out["pdfRegions"] = []
+        return out
+    finally:
+        conn.close()
+
+
+@router.get("/documents/{document_id}/file-url")
+def document_file_url(document_id: str, subject: str = Depends(get_current_subject)) -> dict:
+    """Mint a short-lived signed URL for the source file."""
+    _require_rag()
+    conn = rag_db.get_connection()
+    try:
+        doc = store.get_document(conn, document_id)
+        if doc is None or not doc.get("stored_path"):
+            raise HTTPException(status_code = 404, detail = "Document file not available")
+    finally:
+        conn.close()
+    token = _sign_document(document_id)
+    return {"url": f"/api/rag/documents/{document_id}/file-signed?token={token}"}
+
+
+@router.get("/documents/{document_id}/file-signed", response_model = None)
+def document_file_signed(document_id: str, token: str = Query(...)) -> FileResponse:
+    """Serve the source file gated by the HMAC token (no bearer) so pdf.js range
+    requests work."""
+    _require_rag()
+    signed_id = _verify_document_token(token)
+    if signed_id != document_id:
+        raise HTTPException(status_code = 401, detail = "Invalid or expired token")
+    conn = rag_db.get_connection()
+    try:
+        doc = store.get_document(conn, document_id)
+    finally:
+        conn.close()
+    stored_path = (doc or {}).get("stored_path")
+    if not doc or not stored_path or not os.path.isfile(stored_path):
+        raise HTTPException(status_code = 404, detail = "Document file not found")
+    # Confine to the uploads root (defense in depth).
+    uploads = os.path.realpath(str(rag_uploads_root()))
+    if not os.path.realpath(stored_path).startswith(uploads):
+        raise HTTPException(status_code = 403, detail = "Forbidden")
+    ext = os.path.splitext(doc["filename"])[1].lower()
+    return FileResponse(
+        stored_path,
+        media_type = _CONTENT_TYPES.get(ext, "application/octet-stream"),
+        filename = doc["filename"],
+    )
diff --git a/studio/backend/storage/rag_db.py b/studio/backend/storage/rag_db.py
new file mode 100644
index 0000000000..601fb73d0a
--- /dev/null
+++ b/studio/backend/storage/rag_db.py
@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""SQLite storage for the RAG engine.
+
+Same pattern as providers_db.py / studio_db.py (module functions, raw sqlite3,
+WAL, per-call connections, lazy schema), but every connection also loads
+sqlite-vec (vec0 needs it per-connection). If it cannot load, RAG_AVAILABLE is
+False and get_connection() raises rather than failing import.
+
+One rag.db holds the ``documents`` / ``chunks`` model, the FTS5 lexical index
+(``chunks_fts``) and the sqlite-vec dense index (``chunks_vec``, created lazily
+by ensure_vec once the embedding dim is known, since vec0 bakes the dim into the
+column type).
+"""
+
+import logging
+import sqlite3
+import threading
+
+logger = logging.getLogger(__name__)
+
+from utils.paths import rag_db_path, ensure_dir
+
+# Optional dep: import must never crash this module (imported unconditionally).
+try:
+    import sqlite_vec
+    RAG_AVAILABLE = True
+except Exception as exc:  # noqa: BLE001 - any import failure disables RAG
+    sqlite_vec = None
+    RAG_AVAILABLE = False
+    logger.warning("RAG unavailable: sqlite-vec could not be imported (%s)", exc)
+
+_RAG_UNAVAILABLE_MSG = "RAG unavailable: sqlite-vec extension could not be loaded"
+
+_schema_lock = threading.Lock()
+_schema_ready = False
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    """Create the RAG tables if absent (once per process). ``chunks_vec`` is
+    skipped: its column type needs the embedding dim, so ensure_vec() makes it
+    lazily at first ingest."""
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS knowledge_bases (
+            id TEXT NOT NULL PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT,
+            embedding_model TEXT,
+            created_at TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS documents (
+            id TEXT NOT NULL PRIMARY KEY,
+            scope TEXT NOT NULL,
+            kb_id TEXT,
+            thread_id TEXT,
+            filename TEXT NOT NULL,
+            sha256 TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            error TEXT,
+            num_chunks INTEGER NOT NULL DEFAULT 0,
+            stored_path TEXT,
+            created_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_documents_scope ON documents(scope);
+        CREATE INDEX IF NOT EXISTS idx_documents_hash ON documents(scope, sha256);
+
+        CREATE TABLE IF NOT EXISTS chunks (
+            id TEXT NOT NULL PRIMARY KEY,
+            document_id TEXT NOT NULL,
+            scope TEXT NOT NULL,
+            chunk_index INTEGER NOT NULL,
+            text TEXT NOT NULL,
+            page_number INTEGER,
+            source_page_index INTEGER,
+            token_count INTEGER,
+            kind TEXT NOT NULL DEFAULT 'text',
+            pdf_regions_json TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_chunks_scope ON chunks(scope);
+        CREATE INDEX IF NOT EXISTS idx_chunks_doc ON chunks(document_id);
+
+        CREATE TABLE IF NOT EXISTS ingestion_jobs (
+            id TEXT NOT NULL PRIMARY KEY,
+            document_id TEXT NOT NULL,
+            scope TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            stage TEXT,
+            progress REAL NOT NULL DEFAULT 0.0,
+            error TEXT,
+            created_at TEXT NOT NULL
+        );
+
+        CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+            text,
+            chunk_id UNINDEXED,
+            scope UNINDEXED,
+            tokenize='porter unicode61'
+        );
+        """
+    )
+
+
+def get_connection() -> sqlite3.Connection:
+    """Open rag.db (WAL + sqlite-vec loaded, schema created once). Raises if the extension is unavailable."""
+    global _schema_ready
+    if not RAG_AVAILABLE:
+        raise RuntimeError(_RAG_UNAVAILABLE_MSG)
+
+    db_path = rag_db_path()
+    ensure_dir(db_path.parent)
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    try:
+        conn.enable_load_extension(True)
+        sqlite_vec.load(conn)
+        conn.enable_load_extension(False)
+    except Exception as exc:  # noqa: BLE001
+        conn.close()
+        raise RuntimeError(_RAG_UNAVAILABLE_MSG) from exc
+
+    if not _schema_ready:
+        with _schema_lock:
+            if not _schema_ready:
+                try:
+                    _ensure_schema(conn)
+                    _schema_ready = True
+                except Exception:
+                    conn.close()
+                    raise
+    return conn
+
+
+def ensure_vec(conn: sqlite3.Connection, dim: int) -> None:
+    """Create the dense ``chunks_vec`` table once the embedding dim is known
+    (vec0 bakes it into the column type). Idempotent; dim fixed per db."""
+    conn.execute(
+        f"CREATE VIRTUAL TABLE IF NOT EXISTS chunks_vec USING vec0("
+        f"scope TEXT partition key, "
+        f"chunk_id TEXT, "
+        f"embedding float[{int(dim)}] distance_metric=cosine)"
+    )
+
+
+def vec_table_exists(conn: sqlite3.Connection) -> bool:
+    """True if the dense ``chunks_vec`` table exists."""
+    row = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='chunks_vec'"
+    ).fetchone()
+    return row is not None
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index a9b17fc7f5..da8d9b5e66 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -293,6 +293,195 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
         ) WITHOUT ROWID
         """
     )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS prompt_entries (
+            id TEXT NOT NULL PRIMARY KEY,
+            name TEXT NOT NULL,
+            text TEXT NOT NULL,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_prompt_entries_created_at ON prompt_entries(created_at)"
+    )
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS prompt_lists (
+            id TEXT NOT NULL PRIMARY KEY,
+            name TEXT NOT NULL,
+            items_json TEXT NOT NULL,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_prompt_lists_created_at ON prompt_lists(created_at)"
+    )
+
+
+def _prompt_entry_from_row(row: sqlite3.Row) -> dict:
+    return {
+        "id": row["id"],
+        "name": row["name"],
+        "text": row["text"],
+        "createdAt": row["created_at"],
+        "updatedAt": row["updated_at"],
+    }
+
+
+def list_prompt_entries() -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute("SELECT * FROM prompt_entries ORDER BY created_at DESC").fetchall()
+        return [_prompt_entry_from_row(r) for r in rows]
+    finally:
+        conn.close()
+
+
+def upsert_prompt_entry(entry: dict) -> dict:
+    conn = get_connection()
+    try:
+        conn.execute(
+            """
+            INSERT INTO prompt_entries (id, name, text, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                name = excluded.name,
+                text = excluded.text,
+                updated_at = excluded.updated_at
+            """,
+            (
+                entry["id"],
+                entry["name"],
+                entry["text"],
+                entry["createdAt"],
+                entry["updatedAt"],
+            ),
+        )
+        conn.commit()
+        return entry
+    finally:
+        conn.close()
+
+
+def delete_prompt_entry(entry_id: str) -> None:
+    conn = get_connection()
+    try:
+        conn.execute("DELETE FROM prompt_entries WHERE id = ?", (entry_id,))
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def bulk_upsert_prompt_entries(entries: list[dict]) -> int:
+    if not entries:
+        return 0
+    conn = get_connection()
+    try:
+        conn.executemany(
+            """
+            INSERT INTO prompt_entries (id, name, text, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                name = excluded.name,
+                text = excluded.text,
+                updated_at = excluded.updated_at
+            """,
+            [(e["id"], e["name"], e["text"], e["createdAt"], e["updatedAt"]) for e in entries],
+        )
+        conn.commit()
+        return len(entries)
+    finally:
+        conn.close()
+
+
+def _prompt_list_from_row(row: sqlite3.Row) -> dict:
+    return {
+        "id": row["id"],
+        "name": row["name"],
+        "items": json.loads(row["items_json"]),
+        "createdAt": row["created_at"],
+        "updatedAt": row["updated_at"],
+    }
+
+
+def list_prompt_lists_db() -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute("SELECT * FROM prompt_lists ORDER BY created_at DESC").fetchall()
+        return [_prompt_list_from_row(r) for r in rows]
+    finally:
+        conn.close()
+
+
+def upsert_prompt_list(lst: dict) -> dict:
+    conn = get_connection()
+    try:
+        conn.execute(
+            """
+            INSERT INTO prompt_lists (id, name, items_json, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                name = excluded.name,
+                items_json = excluded.items_json,
+                updated_at = excluded.updated_at
+            """,
+            (
+                lst["id"],
+                lst["name"],
+                json.dumps(lst["items"]),
+                lst["createdAt"],
+                lst["updatedAt"],
+            ),
+        )
+        conn.commit()
+        return lst
+    finally:
+        conn.close()
+
+
+def delete_prompt_list_db(list_id: str) -> None:
+    conn = get_connection()
+    try:
+        conn.execute("DELETE FROM prompt_lists WHERE id = ?", (list_id,))
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def bulk_upsert_prompt_lists(lists: list[dict]) -> int:
+    if not lists:
+        return 0
+    conn = get_connection()
+    try:
+        conn.executemany(
+            """
+            INSERT INTO prompt_lists (id, name, items_json, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                name = excluded.name,
+                items_json = excluded.items_json,
+                updated_at = excluded.updated_at
+            """,
+            [
+                (
+                    lst["id"],
+                    lst["name"],
+                    json.dumps(lst["items"]),
+                    lst["createdAt"],
+                    lst["updatedAt"],
+                )
+                for lst in lists
+            ],
+        )
+        conn.commit()
+        return len(lists)
+    finally:
+        conn.close()
 
 
 def get_connection() -> sqlite3.Connection:
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index a9fc185536..b0b9ee309c 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -109,3 +109,71 @@ def base_url(studio_server):
 def api_key(studio_server):
     """API key for the e2e Studio server (from ``studio_server``)."""
     return studio_server[1]
+
+
+# ── RAG fixtures ─────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def rag_home(tmp_path, monkeypatch):
+    """Isolate the RAG database under a fresh UNSLOTH_STUDIO_HOME per test.
+
+    Points the storage root at ``tmp_path`` and resets the lazy schema flag so
+    each test starts from an empty rag.db. Yields the temp home path.
+    """
+    from storage import rag_db
+
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(rag_db, "_schema_ready", False)
+    return tmp_path
+
+
+@pytest.fixture
+def rag_conn(rag_home):
+    """A fresh RAG connection bound to the isolated ``rag_home`` database."""
+    from storage import rag_db
+
+    conn = rag_db.get_connection()
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+@pytest.fixture
+def stub_embeddings(monkeypatch):
+    """Stub ``core.rag.embeddings`` with deterministic hash-based vectors.
+
+    Lets store / retrieval / ingestion tests run fast without downloading a
+    sentence-transformers model. Returns the fixed embedding dimension.
+    """
+    import hashlib
+    import math
+
+    from core.rag import embeddings
+
+    dim = 32
+
+    def _vec(text: str):
+        seed = hashlib.sha256(text.encode("utf-8")).digest()
+        raw = [seed[i % len(seed)] / 255.0 for i in range(dim)]
+        norm = math.sqrt(sum(x * x for x in raw)) or 1.0
+        return [x / norm for x in raw]
+
+    def fake_encode(
+        texts,
+        *,
+        model_name = None,
+        normalize = True,
+    ):
+        return [_vec(t) for t in texts]
+
+    monkeypatch.setattr(embeddings, "encode", fake_encode)
+    monkeypatch.setattr(embeddings, "dim", lambda model_name = None: dim)
+    monkeypatch.setattr(
+        embeddings,
+        "token_counter",
+        lambda model_name = None: (lambda t: len(t.split())),
+    )
+    monkeypatch.setattr(embeddings, "warm", lambda model_name = None: None)
+    return dim
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index e7022ee435..50bd0e89d7 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -419,6 +419,8 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
     routes_module.__path__ = []
     settings_module = ModuleType("routes.settings")
     settings_module.router = APIRouter()
+    prompts_module = ModuleType("routes.prompts")
+    prompts_module.router = APIRouter()
 
     for name, router in {
         "auth_router": APIRouter(),
@@ -431,6 +433,7 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
         "mcp_servers_router": APIRouter(),
         "models_router": APIRouter(),
         "providers_router": APIRouter(),
+        "rag_router": APIRouter(),
         "settings_router": settings_module.router,
         "training_history_router": APIRouter(),
         "training_router": APIRouter(),
@@ -440,6 +443,7 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
 
     monkeypatch.setitem(sys.modules, "routes", routes_module)
     monkeypatch.setitem(sys.modules, "routes.settings", settings_module)
+    monkeypatch.setitem(sys.modules, "routes.prompts", prompts_module)
 
     import studio.backend.main as backend_main
 
diff --git a/studio/backend/tests/test_rag_captioning.py b/studio/backend/tests/test_rag_captioning.py
new file mode 100644
index 0000000000..5d83a7d38d
--- /dev/null
+++ b/studio/backend/tests/test_rag_captioning.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Multimodal captioning tests: gating, grouping, splice, retrieval."""
+
+from __future__ import annotations
+
+from core.rag import captioner
+from core.rag.parsers import Page, ParsedImage
+
+
+def _img(page):
+    return ParsedImage(image_bytes = b"\x89PNG fake", page_number = page, xref = page)
+
+
+def test_caption_images_disabled_by_default(monkeypatch):
+    monkeypatch.setattr(captioner.config, "CAPTION_IMAGES", False)
+    assert captioner.caption_images([_img(1)], endpoint = ("http://x", "local")) == {}
+
+
+def test_caption_images_groups_by_page(monkeypatch):
+    monkeypatch.setattr(captioner.config, "CAPTION_IMAGES", True)
+    monkeypatch.setattr(captioner.config, "CAPTION_MAX_IMAGES", 8)
+    monkeypatch.setattr(captioner, "_caption_one", lambda base, model, b, t: "a chart of results")
+    out = captioner.caption_images([_img(1), _img(1), _img(3)], endpoint = ("http://x", "local"))
+    assert out == {1: ["a chart of results", "a chart of results"], 3: ["a chart of results"]}
+
+
+def test_caption_images_respects_cap(monkeypatch):
+    monkeypatch.setattr(captioner.config, "CAPTION_IMAGES", True)
+    monkeypatch.setattr(captioner.config, "CAPTION_MAX_IMAGES", 2)
+    calls = []
+    monkeypatch.setattr(captioner, "_caption_one", lambda *a: (calls.append(1) or "cap"))
+    captioner.caption_images([_img(i) for i in range(5)], endpoint = ("http://x", "local"))
+    assert len(calls) == 2
+
+
+def test_caption_images_no_endpoint(monkeypatch):
+    monkeypatch.setattr(captioner.config, "CAPTION_IMAGES", True)
+    monkeypatch.setattr(captioner, "vision_endpoint", lambda: None)
+    assert captioner.caption_images([_img(1)]) == {}
+
+
+def test_splice_captions_appends_to_right_page():
+    pages = [Page("body one", 1, 8), Page("body two", 2, 8)]
+    out = captioner.splice_captions(pages, {2: ["a diagram of X"]})
+    assert out[0].text == "body one"
+    assert "a diagram of X" in out[1].text
+    assert out[1].text.startswith("body two")
+    assert out[1].char_count == len(out[1].text)
+
+
+def test_splice_captions_noop_when_empty():
+    pages = [Page("body", 1, 4)]
+    assert captioner.splice_captions(pages, {}) is pages
+
+
+def test_render_pdf_figures_detects_drawing(tmp_path):
+    import pymupdf
+
+    from core.rag.parsers import render_pdf_figures
+
+    pdf = tmp_path / "fig.pdf"
+    doc = pymupdf.open()
+    page = doc.new_page()
+    shape = page.new_shape()
+    shape.draw_rect(pymupdf.Rect(60, 60, 540, 460))
+    for i in range(8):
+        shape.draw_line((80, 80 + i * 40), (520, 80 + i * 40))
+    shape.finish(color = (0, 0, 0), fill = (0.8, 0.8, 0.9))
+    shape.commit()
+    doc.save(str(pdf))
+    doc.close()
+
+    figs = render_pdf_figures(str(pdf))
+    assert figs, "expected at least one rendered figure region"
+    assert figs[0].image_bytes[:8] == b"\x89PNG\r\n\x1a\n"
+    assert figs[0].page_number == 1
+
+
+def test_captioned_text_is_searchable(rag_home, stub_embeddings, monkeypatch):
+    from core.rag import retrieval, store
+    from storage import rag_db
+
+    pages = [Page("Section 1 intro text about models.", 1, 33)]
+    pages = captioner.splice_captions(
+        pages, {1: ["bar chart comparing throughput across quantizations"]}
+    )
+    from core.rag import chunking, embeddings
+
+    chunks = chunking.chunk_pages(
+        pages, max_tokens = 128, overlap = 16, count = embeddings.token_counter(None)
+    )
+    vecs = embeddings.encode([c.text for c in chunks], normalize = True)
+
+    conn = rag_db.get_connection()
+    try:
+        kb_id = store.create_kb(conn, name = "kb")
+        scope = store.kb_scope(kb_id)
+        doc_id = store.create_document(conn, scope = scope, filename = "d.pdf", sha256 = "h")
+        store.add_chunks(conn, scope, doc_id, chunks, vecs)
+        hits = retrieval.retrieve_lexical(conn, scope, "throughput quantizations", k = 5)
+    finally:
+        conn.close()
+    assert hits, "spliced caption text should be retrievable via lexical search"
diff --git a/studio/backend/tests/test_rag_chunking.py b/studio/backend/tests/test_rag_chunking.py
new file mode 100644
index 0000000000..3d3c9eedd8
--- /dev/null
+++ b/studio/backend/tests/test_rag_chunking.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Chunking unit tests (no DB, no model)."""
+
+from core.rag.chunking import chunk_pages
+from core.rag.parsers import Page, parse_text
+
+WORDS = lambda t: len(t.split())  # noqa: E731
+
+
+def _page(text: str, page_number = None) -> Page:
+    return Page(text = text, page_number = page_number, char_count = len(text))
+
+
+def test_chunk_token_bounds_and_overlap():
+    text = " ".join(f"w{i}" for i in range(300))
+    chunks = chunk_pages([_page(text)], max_tokens = 128, overlap = 24, count = WORDS)
+    assert len(chunks) >= 3
+    assert all(c.token_count <= 128 for c in chunks)
+    a, b = chunks[0].text.split(), chunks[1].text.split()
+    shared = next((n for n in range(60, 0, -1) if a[-n:] == b[:n]), 0)
+    assert shared == 24  # exactly overlap tokens carried
+
+
+def test_chunk_never_exceeds_max_with_overlap_carry():
+    """Overlap carry is trimmed so no chunk exceeds max_tokens (else the embedder overflows)."""
+    s1 = " ".join("a" for _ in range(10))
+    s2 = " ".join("b" for _ in range(95))  # near max
+    chunks = chunk_pages([_page(f"{s1}. {s2}")], max_tokens = 100, overlap = 24, count = WORDS)
+    assert all(c.token_count <= 100 for c in chunks), [c.token_count for c in chunks]
+
+
+def test_chunk_indices_are_sequential():
+    chunks = chunk_pages([_page("alpha. " * 200)], max_tokens = 32, overlap = 0, count = WORDS)
+    assert [c.chunk_index for c in chunks] == list(range(len(chunks)))
+
+
+def test_chunk_tracks_source_page_index():
+    pages = [_page("alpha bravo " * 80, 1), _page("charlie delta " * 80, 2)]
+    chunks = chunk_pages(pages, max_tokens = 32, overlap = 0, count = WORDS)
+    page0 = [c for c in chunks if c.source_page_index == 0]
+    page1 = [c for c in chunks if c.source_page_index == 1]
+    assert page0 and page1
+    assert all(c.page_number == 1 for c in page0)
+    assert all(c.page_number == 2 for c in page1)
+
+
+def test_chunk_char_offsets_locate_text_in_page():
+    # Each chunk's char span must slice back to text containing it.
+    page_text = "alpha bravo charlie delta echo foxtrot golf hotel " * 30
+    pages = [_page(page_text, 1)]
+    chunks = chunk_pages(pages, max_tokens = 16, overlap = 0, count = WORDS)
+    assert len(chunks) > 1
+    for c in chunks:
+        assert 0 <= c.page_char_start < c.page_char_end <= len(page_text)
+        sliced = page_text[c.page_char_start : c.page_char_end]
+        assert c.text in sliced or sliced.strip() == c.text
+
+
+def test_empty_page_yields_no_chunks():
+    chunks = chunk_pages([_page("   \n  ")], max_tokens = 32, overlap = 0, count = WORDS)
+    assert chunks == []
+
+
+def test_parse_text_single_page():
+    pages = parse_text("hello world")
+    assert len(pages) == 1
+    assert pages[0].char_count == len("hello world")
diff --git a/studio/backend/tests/test_rag_embed_llama_server.py b/studio/backend/tests/test_rag_embed_llama_server.py
new file mode 100644
index 0000000000..8321068afd
--- /dev/null
+++ b/studio/backend/tests/test_rag_embed_llama_server.py
@@ -0,0 +1,448 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""llama-server GGUF embedder tests, every boundary mocked."""
+
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from core.rag import config, embeddings
+from core.rag import embed_llama_server as mod
+from core.rag.embed_llama_server import LlamaServerBackend
+
+
+@pytest.fixture(autouse = True)
+def _reset_backend_singleton():
+    embeddings._reset_backend()
+    yield
+    embeddings._reset_backend()
+
+
+class _FakeProc:
+    """subprocess.Popen stand-in with controllable liveness."""
+
+    def __init__(
+        self,
+        alive = True,
+        returncode = 0,
+    ):
+        self._alive = alive
+        self.returncode = returncode
+        self.stdout = iter(())  # drain thread exits immediately
+
+    def poll(self):
+        return None if self._alive else self.returncode
+
+    def terminate(self):
+        self._alive = False
+
+    def kill(self):
+        self._alive = False
+
+    def wait(self, timeout = None):
+        return self.returncode
+
+
+def _mock_auto(monkeypatch, *, gpus, binary):
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    monkeypatch.setattr(config, "EMBED_BACKEND", "auto")
+    monkeypatch.setattr(LlamaCppBackend, "_get_gpu_free_memory", staticmethod(lambda: gpus))
+    monkeypatch.setattr(LlamaCppBackend, "_find_llama_server_binary", staticmethod(lambda: binary))
+
+
+def _stub_st_load(monkeypatch):
+    # Make the ST probe succeed without importing sentence-transformers (absent in
+    # the torch-free backend CI); these tests assert selection, not a real load.
+    monkeypatch.setattr(embeddings, "_get", lambda *a, **k: object())
+
+
+def test_auto_uses_st_with_cuda(monkeypatch):
+    _stub_st_load(monkeypatch)
+    _mock_auto(monkeypatch, gpus = [(0, 40000)], binary = "/bin/llama-server")
+    assert type(embeddings._get_backend()).__name__ == "_SentenceTransformersBackend"
+
+
+def test_auto_uses_llama_without_cuda(monkeypatch):
+    _mock_auto(monkeypatch, gpus = [], binary = "/bin/llama-server")
+    assert isinstance(embeddings._get_backend(), LlamaServerBackend)
+
+
+def test_auto_falls_back_to_st_without_binary(monkeypatch):
+    _stub_st_load(monkeypatch)
+    _mock_auto(monkeypatch, gpus = [], binary = None)
+    assert type(embeddings._get_backend()).__name__ == "_SentenceTransformersBackend"
+
+
+def test_llama_backend_selected_by_config(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_BACKEND", "llama-server")
+    assert isinstance(embeddings._get_backend(), LlamaServerBackend)
+
+
+def test_unknown_backend_raises(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_BACKEND", "bogus")
+    with pytest.raises(ValueError, match = "Unknown RAG_EMBED_BACKEND"):
+        embeddings._get_backend()
+
+
+def test_explicit_backend_overrides_auto(monkeypatch):
+    _stub_st_load(monkeypatch)
+    monkeypatch.setattr(config, "EMBED_BACKEND", "sentence-transformers")
+    assert type(embeddings._get_backend()).__name__ == "_SentenceTransformersBackend"
+    monkeypatch.setattr(config, "EMBED_BACKEND", "llama-server")
+    assert isinstance(embeddings._get_backend(), LlamaServerBackend)
+
+
+def test_llama_backend_imports_no_torch():
+    # Clean subprocess so the parent's imports don't mask a regression.
+    backend_dir = Path(__file__).resolve().parents[1]
+    code = textwrap.dedent(
+        """
+        import sys
+        from core.rag import embeddings
+        b = embeddings._get_backend()
+        assert type(b).__name__ == "LlamaServerBackend", type(b).__name__
+        assert "torch" not in sys.modules, "torch was imported"
+        assert "sentence_transformers" not in sys.modules, "ST was imported"
+        print("OK")
+        """
+    )
+    env = {
+        **__import__("os").environ,
+        "RAG_EMBED_BACKEND": "llama-server",
+        "PYTHONPATH": str(backend_dir),
+    }
+    proc = subprocess.run([sys.executable, "-c", code], capture_output = True, text = True, env = env)
+    assert proc.returncode == 0, proc.stderr
+    assert "OK" in proc.stdout
+
+
+def test_build_cmd_cpu_flags():
+    b = LlamaServerBackend()
+    cmd = b._build_cmd("/bin/llama-server", "/m/bge.gguf", 9999, use_gpu = False)
+    assert "--embedding" in cmd
+    assert cmd[cmd.index("--pooling") + 1] == "cls"
+    assert cmd[cmd.index("--fit") + 1] == "off"  # deterministic, no auto-resize
+    assert cmd[cmd.index("-ngl") + 1] == "0"  # CPU keeps all off the GPU
+    assert cmd[cmd.index("--port") + 1] == "9999"
+
+
+def test_build_cmd_gpu_offloads():
+    b = LlamaServerBackend()
+    cmd = b._build_cmd("/bin/llama-server", "/m/bge.gguf", 1, use_gpu = True)
+    assert cmd[cmd.index("-ngl") + 1] == "-1"  # offload all, matching the chat server
+
+
+def test_build_env_cpu_hides_gpus():
+    b = LlamaServerBackend()
+    env = b._build_env("/bin/llama-server", use_gpu = False)
+    assert env["CUDA_VISIBLE_DEVICES"] == ""  # never contend with the chat model
+    assert env["LLAMA_SET_ROWS"] == "1"
+
+
+def test_build_env_gpu_inherits_devices(monkeypatch):
+    monkeypatch.setenv("CUDA_VISIBLE_DEVICES", "0,1")
+    b = LlamaServerBackend()
+    env = b._build_env("/bin/llama-server", use_gpu = True)
+    assert env.get("CUDA_VISIBLE_DEVICES") == "0,1"  # inherit Studio's selection
+
+
+def test_use_gpu_explicit_modes(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(config, "EMBED_DEVICE", "gpu")
+    assert b._use_gpu() is True
+    monkeypatch.setattr(config, "EMBED_DEVICE", "cpu")
+    assert b._use_gpu() is False
+
+
+def test_use_gpu_auto_follows_probe(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(config, "EMBED_DEVICE", "auto")
+    monkeypatch.setattr(LlamaServerBackend, "_gpu_available", staticmethod(lambda: True))
+    assert b._use_gpu() is True
+    monkeypatch.setattr(LlamaServerBackend, "_gpu_available", staticmethod(lambda: False))
+    assert b._use_gpu() is False
+
+
+def test_use_gpu_sticky_cpu_fallback(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(config, "EMBED_DEVICE", "auto")
+    monkeypatch.setattr(LlamaServerBackend, "_gpu_available", staticmethod(lambda: True))
+    b._force_cpu = True  # a prior GPU start failed
+    assert b._use_gpu() is False
+
+
+def test_gpu_available_reuses_studio_probe(monkeypatch):
+    import utils.hardware as uh
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    monkeypatch.setattr(uh, "is_apple_silicon", lambda: False)
+    # Ample free VRAM -> GPU; nearly full -> CPU; none -> CPU.
+    monkeypatch.setattr(LlamaCppBackend, "_get_gpu_free_memory", staticmethod(lambda: [(0, 40000)]))
+    assert LlamaServerBackend._gpu_available() is True
+    monkeypatch.setattr(LlamaCppBackend, "_get_gpu_free_memory", staticmethod(lambda: [(0, 100)]))
+    assert LlamaServerBackend._gpu_available() is False
+    monkeypatch.setattr(LlamaCppBackend, "_get_gpu_free_memory", staticmethod(lambda: []))
+    assert LlamaServerBackend._gpu_available() is False
+
+
+def test_gpu_available_apple_metal(monkeypatch):
+    import utils.hardware as uh
+    monkeypatch.setattr(uh, "is_apple_silicon", lambda: True)
+    assert LlamaServerBackend._gpu_available() is True
+
+
+def _patch_spawn_deps(
+    monkeypatch,
+    proc,
+    *,
+    free_port = 54321,
+):
+    # Force CPU so spawn never depends on a host GPU.
+    monkeypatch.setattr(config, "EMBED_DEVICE", "cpu")
+    monkeypatch.setattr(LlamaServerBackend, "_resolve_binary", lambda self: "/bin/llama-server")
+    monkeypatch.setattr(LlamaServerBackend, "_resolve_model_path", lambda self: "/m/bge.gguf")
+    monkeypatch.setattr(LlamaServerBackend, "_find_free_port", staticmethod(lambda: free_port))
+    monkeypatch.setattr(mod.subprocess, "Popen", lambda *a, **k: proc)
+
+
+def test_spawn_uses_explicit_port(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_PORT", 8123)
+    b = LlamaServerBackend()
+    _patch_spawn_deps(monkeypatch, _FakeProc(alive = True))
+    monkeypatch.setattr(b, "_wait_for_health", lambda *a, **k: True)
+    b._spawn()
+    assert b._port == 8123
+
+
+def test_spawn_uses_free_port_when_auto(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_PORT", 0)
+    b = LlamaServerBackend()
+    _patch_spawn_deps(monkeypatch, _FakeProc(alive = True), free_port = 47000)
+    monkeypatch.setattr(b, "_wait_for_health", lambda *a, **k: True)
+    b._spawn()
+    assert b._port == 47000
+
+
+def test_spawn_fails_loud_on_early_exit(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_PORT", 8124)
+    b = LlamaServerBackend()
+    _patch_spawn_deps(monkeypatch, _FakeProc(alive = False, returncode = 1))
+    with pytest.raises(RuntimeError, match = "failed to become healthy"):
+        b._spawn()
+
+
+def test_spawn_auto_falls_back_to_cpu_on_gpu_failure(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_DEVICE", "auto")
+    monkeypatch.setattr(LlamaServerBackend, "_gpu_available", staticmethod(lambda: True))
+    b = LlamaServerBackend()
+    calls = []
+
+    def fake_spawn_once(use_gpu):
+        calls.append(use_gpu)
+        if use_gpu:
+            raise RuntimeError("CUDA out of memory")
+
+    monkeypatch.setattr(b, "_spawn_once", fake_spawn_once)
+    b._spawn()
+    assert calls == [True, False]  # tried GPU, then fell back to CPU
+    assert b._force_cpu is True  # sticky, so respawns stay on CPU
+
+
+def test_spawn_explicit_gpu_does_not_fall_back(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_DEVICE", "gpu")
+    b = LlamaServerBackend()
+
+    def fake_spawn_once(use_gpu):
+        raise RuntimeError("CUDA out of memory")
+
+    monkeypatch.setattr(b, "_spawn_once", fake_spawn_once)
+    with pytest.raises(RuntimeError, match = "out of memory"):
+        b._spawn()
+    assert b._force_cpu is False  # explicit gpu never silently downgrades
+
+
+def _embed_response(vectors):
+    # Reversed so the index sort is exercised.
+    items = [{"index": i, "embedding": v} for i, v in enumerate(vectors)]
+    return {"data": list(reversed(items))}
+
+
+def test_encode_orders_and_returns_float32(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    captured = {}
+
+    def fake_post(path, payload):
+        captured["path"] = path
+        captured["input"] = payload["input"]
+        return _embed_response([[3.0, 4.0], [0.0, 5.0]])
+
+    monkeypatch.setattr(b, "_post", fake_post)
+    out = b.encode(["a", "b"], normalize = False)
+    assert captured["path"] == "/v1/embeddings"
+    assert out.dtype == np.float32
+    assert out.shape == (2, 2)
+    assert out[0].tolist() == [3.0, 4.0]  # index sort restored order
+
+
+def test_encode_normalizes(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    monkeypatch.setattr(b, "_post", lambda p, pl: _embed_response([[3.0, 4.0]]))
+    out = b.encode(["a"], normalize = True)
+    np.testing.assert_allclose(np.linalg.norm(out, axis = 1), [1.0], rtol = 1e-6)
+
+
+def test_encode_empty_returns_zero_rows(monkeypatch):
+    b = LlamaServerBackend()
+    b._dim = 384
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    out = b.encode([])
+    assert out.shape == (0, 384)
+    assert out.dtype == np.float32
+
+
+def test_encode_rejects_count_mismatch(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    monkeypatch.setattr(b, "_post", lambda p, pl: {"data": [{"index": 0, "embedding": [1.0]}]})
+    with pytest.raises(RuntimeError, match = "vectors for"):
+        b.encode(["a", "b"], normalize = False)
+
+
+def test_encode_batches(monkeypatch):
+    monkeypatch.setattr(config, "EMBED_BATCH", 2)
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    calls = []
+
+    def fake_post(path, payload):
+        chunk = payload["input"]
+        calls.append(len(chunk))
+        return _embed_response([[1.0, 0.0]] * len(chunk))
+
+    monkeypatch.setattr(b, "_post", fake_post)
+    out = b.encode(["a", "b", "c"], normalize = False)
+    assert out.shape == (3, 2)
+    assert calls == [2, 1]  # batched at EMBED_BATCH=2
+
+
+def test_dim_probes_once_and_caches(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    n_calls = {"n": 0}
+
+    def fake_post(path, payload):
+        n_calls["n"] += 1
+        return _embed_response([[0.1] * 384])
+
+    monkeypatch.setattr(b, "_post", fake_post)
+    assert b.dim() == 384
+    assert b.dim() == 384
+    assert n_calls["n"] == 1  # cached after the first probe
+
+
+def test_token_counter_hits_tokenize(monkeypatch):
+    b = LlamaServerBackend()
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    seen = {}
+
+    def fake_post(path, payload):
+        seen["path"] = path
+        seen["content"] = payload["content"]
+        return {"tokens": [1, 2, 3, 4]}
+
+    monkeypatch.setattr(b, "_post", fake_post)
+    count = b.token_counter()
+    assert count("hello world") == 4
+    assert seen["path"] == "/tokenize"
+    assert seen["content"] == "hello world"
+
+
+def test_ensure_ready_respawns_dead_process(monkeypatch):
+    b = LlamaServerBackend()
+    b._process = _FakeProc(alive = False, returncode = 0)
+    spawned = {"n": 0}
+
+    def fake_spawn():
+        spawned["n"] += 1
+        b._process = _FakeProc(alive = True)
+
+    monkeypatch.setattr(b, "_spawn", fake_spawn)
+    b._ensure_ready()
+    assert spawned["n"] == 1
+    assert b._process_alive()
+    # Already alive -> no second spawn.
+    b._ensure_ready()
+    assert spawned["n"] == 1
+
+
+def test_post_restarts_once_on_connect_error(monkeypatch):
+    import httpx
+
+    b = LlamaServerBackend()
+    b._port = 9000
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    restarts = {"n": 0}
+    monkeypatch.setattr(b, "_restart", lambda: restarts.__setitem__("n", restarts["n"] + 1))
+
+    attempts = {"n": 0}
+
+    class _Client:
+        def post(self, url, json):
+            attempts["n"] += 1
+            if attempts["n"] == 1:
+                raise httpx.ConnectError("boom")
+
+            class _R:
+                def raise_for_status(self_inner):
+                    return None
+
+                def json(self_inner):
+                    return {"tokens": [1]}
+
+            return _R()
+
+    b._client = _Client()
+    out = b._post("/tokenize", {"content": "x"})
+    assert out == {"tokens": [1]}
+    assert restarts["n"] == 1  # one self-heal restart, then success
+
+
+def test_post_restarts_once_on_read_timeout(monkeypatch):
+    # A wedged request (ReadTimeout) also triggers one restart-and-retry.
+    import httpx
+
+    b = LlamaServerBackend()
+    b._port = 9000
+    monkeypatch.setattr(b, "_ensure_ready", lambda: None)
+    restarts = {"n": 0}
+    monkeypatch.setattr(b, "_restart", lambda: restarts.__setitem__("n", restarts["n"] + 1))
+
+    attempts = {"n": 0}
+
+    class _Client:
+        def post(self, url, json):
+            attempts["n"] += 1
+            if attempts["n"] == 1:
+                raise httpx.ReadTimeout("timed out")
+
+            class _R:
+                def raise_for_status(self_inner):
+                    return None
+
+                def json(self_inner):
+                    return {"data": [{"index": 0, "embedding": [1.0, 0.0]}]}
+
+            return _R()
+
+    b._client = _Client()
+    out = b._post("/v1/embeddings", {"input": ["x"]})
+    assert out["data"][0]["embedding"] == [1.0, 0.0]
+    assert restarts["n"] == 1  # timeout self-heals like a transport error
diff --git a/studio/backend/tests/test_rag_embeddings.py b/studio/backend/tests/test_rag_embeddings.py
new file mode 100644
index 0000000000..28a2f69426
--- /dev/null
+++ b/studio/backend/tests/test_rag_embeddings.py
@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Embedder concurrency tests: the fast tokenizer isn't thread-safe, so encode
+and token counting must be serialized (else threads panic "Already borrowed")."""
+
+import os
+import threading
+import time
+
+import numpy as np
+import pytest
+
+from core.rag import config, embeddings
+
+
+@pytest.fixture(autouse = True)
+def _pin_st_backend(monkeypatch):
+    # Tests patch ST internals (_get), so force the ST backend.
+    monkeypatch.setattr(config, "EMBED_BACKEND", "sentence-transformers")
+    embeddings._reset_backend()
+    yield
+    embeddings._reset_backend()
+
+
+class _ConcurrencyProbe:
+    """Records whether two callers were in the guarded body at once."""
+
+    def __init__(self):
+        self.inside = 0
+        self.saw_overlap = False
+        self._g = threading.Lock()
+
+    def enter(self):
+        with self._g:
+            self.inside += 1
+            if self.inside > 1:
+                self.saw_overlap = True
+        time.sleep(0.005)  # widen the race window
+        with self._g:
+            self.inside -= 1
+
+
+class _FakeModel:
+    def __init__(self, probe):
+        self._probe = probe
+        self.tokenizer = _FakeTokenizer(probe)
+
+    def encode(self, texts, **_kw):
+        self._probe.enter()
+        return np.zeros((len(texts), 4), dtype = np.float32)
+
+
+class _FakeTokenizer:
+    def __init__(self, probe):
+        self._probe = probe
+
+    def encode(self, text, **_kw):
+        self._probe.enter()
+        return list(range(len(text.split())))
+
+
+def _hammer(fn, n = 8):
+    errors: list[Exception] = []
+
+    def worker():
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001
+            errors.append(exc)
+
+    threads = [threading.Thread(target = worker) for _ in range(n)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    return errors
+
+
+def test_encode_is_serialized(monkeypatch):
+    probe = _ConcurrencyProbe()
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _FakeModel(probe))
+    errors = _hammer(lambda: embeddings.encode(["alpha beta", "gamma"]))
+    assert errors == []
+    assert probe.saw_overlap is False  # compute lock serialized encode()
+
+
+def test_token_counter_is_serialized(monkeypatch):
+    probe = _ConcurrencyProbe()
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _FakeModel(probe))
+    count = embeddings.token_counter()
+    errors = _hammer(lambda: count("one two three four"))
+    assert errors == []
+    assert probe.saw_overlap is False  # counting shares the tokenizer lock
+
+
+def test_encode_enables_parallelism_only_during_call(monkeypatch):
+    seen = {}
+
+    class _M:
+        tokenizer = None
+
+        def encode(self, texts, **_kw):
+            seen["during"] = os.environ.get("TOKENIZERS_PARALLELISM")
+            return np.zeros((len(texts), 4), dtype = np.float32)
+
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _M())
+    os.environ["TOKENIZERS_PARALLELISM"] = "false"
+    embeddings.encode(["alpha", "beta"])
+    assert seen["during"] == "true"  # rayon batch tokenization enabled in-call
+    assert os.environ.get("TOKENIZERS_PARALLELISM") == "false"  # restored after
+
+
+def test_token_counter_enables_parallelism_only_during_call(monkeypatch):
+    seen = {}
+
+    class _Tok:
+        def encode(self, text, **_kw):
+            seen["during"] = os.environ.get("TOKENIZERS_PARALLELISM")
+            return list(range(len(text.split())))
+
+    class _M:
+        tokenizer = _Tok()
+
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _M())
+    os.environ["TOKENIZERS_PARALLELISM"] = "false"
+    count = embeddings.token_counter()
+    count("alpha beta gamma")
+    assert seen["during"] == "true"  # rayon enabled in-call, like _st_encode
+    assert os.environ.get("TOKENIZERS_PARALLELISM") == "false"  # restored after
+
+
+class _SentinelLlamaBackend:
+    """Stand-in for LlamaServerBackend; never spawns a real server."""
+
+
+def _force_st_load_failure(monkeypatch):
+    """Make the ST warm-probe raise."""
+
+    def _boom(model_name = None):
+        raise RuntimeError("torch is broken on this machine")
+
+    monkeypatch.setattr(embeddings, "_get", _boom)
+
+
+def _patch_llama_backend(monkeypatch, *, binary):
+    from core.inference.llama_cpp import LlamaCppBackend
+    from core.rag import embed_llama_server
+
+    monkeypatch.setattr(LlamaCppBackend, "_find_llama_server_binary", staticmethod(lambda: binary))
+    monkeypatch.setattr(embed_llama_server, "LlamaServerBackend", _SentinelLlamaBackend)
+
+
+def test_st_failure_falls_back_to_llama_server(monkeypatch):
+    # ST can't load but llama-server is available -> use it.
+    _force_st_load_failure(monkeypatch)
+    _patch_llama_backend(monkeypatch, binary = "/fake/llama-server")
+    embeddings._reset_backend()
+    backend = embeddings._get_backend()
+    assert isinstance(backend, _SentinelLlamaBackend)
+
+
+def test_st_failure_without_llama_binary_reraises(monkeypatch):
+    # No llama-server binary -> surface the failure, don't degrade to nothing.
+    _force_st_load_failure(monkeypatch)
+    _patch_llama_backend(monkeypatch, binary = None)
+    embeddings._reset_backend()
+    with pytest.raises(RuntimeError, match = "torch is broken"):
+        embeddings._get_backend()
+
+
+def test_st_success_keeps_sentence_transformers(monkeypatch):
+    # Clean ST probe -> ST backend stays selected, no fallback.
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: object())
+    _patch_llama_backend(monkeypatch, binary = "/fake/llama-server")
+    embeddings._reset_backend()
+    backend = embeddings._get_backend()
+    assert isinstance(backend, embeddings._SentenceTransformersBackend)
+
+
+class _BoomOnEncodeModel:
+    """Loads fine (init probe passes) but raises when encoding."""
+
+    tokenizer = None
+
+    def encode(self, texts, **_kw):
+        raise RuntimeError("CUDA error during encode")
+
+
+def test_st_encode_runtime_failure_switches_to_llama(monkeypatch):
+    # encode() blows up mid-run -> switch to llama-server and stay switched.
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _BoomOnEncodeModel())
+    _patch_llama_backend(monkeypatch, binary = "/fake/llama-server")
+    calls = {}
+
+    def _sentinel_encode(
+        self,
+        texts,
+        *,
+        model_name = None,
+        normalize = True,
+    ):
+        calls["used"] = True
+        return np.zeros((len(texts), 4), dtype = np.float32)
+
+    monkeypatch.setattr(_SentinelLlamaBackend, "encode", _sentinel_encode, raising = False)
+    embeddings._reset_backend()
+
+    out = embeddings.encode(["alpha", "beta"])
+    assert calls.get("used") is True  # retried on the llama fallback
+    assert out.shape == (2, 4)
+    # Switch is process-wide: later calls keep using llama, not ST.
+    assert isinstance(embeddings._get_backend(), _SentinelLlamaBackend)
+
+
+def test_st_encode_failure_without_llama_binary_reraises(monkeypatch):
+    # No llama-server binary -> surface the encode error.
+    monkeypatch.setattr(embeddings, "_get", lambda model_name = None: _BoomOnEncodeModel())
+    _patch_llama_backend(monkeypatch, binary = None)
+    embeddings._reset_backend()
+    with pytest.raises(RuntimeError, match = "CUDA error during encode"):
+        embeddings.encode(["alpha", "beta"])
diff --git a/studio/backend/tests/test_rag_ingestion.py b/studio/backend/tests/test_rag_ingestion.py
new file mode 100644
index 0000000000..c5fe15876d
--- /dev/null
+++ b/studio/backend/tests/test_rag_ingestion.py
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Ingestion lifecycle tests: pending -> completed, SSE events, dedupe, delete."""
+
+import os
+import time
+
+import pytest
+
+from core.rag import ingestion, store
+from storage import rag_db
+
+
+def _write(tmp_path, name, text):
+    path = tmp_path / name
+    path.write_text(text, encoding = "utf-8")
+    return str(path)
+
+
+def _drain(job_id):
+    return list(ingestion.job_events(job_id))
+
+
+def _wait_completed(job_id, timeout = 30.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        status = ingestion.get_job_status(job_id)
+        if status and status["status"] in ("completed", "failed"):
+            return status
+        time.sleep(0.05)
+    raise AssertionError("ingestion did not finish in time")
+
+
+def test_ingestion_lifecycle_pending_to_completed(rag_home, stub_embeddings, tmp_path):
+    path = _write(tmp_path, "doc.txt", "alpha bravo charlie " * 50)
+    scope = store.kb_scope("K1")
+    doc_id, job_id = ingestion.start_ingestion(scope, "K1", None, "doc.txt", path)
+
+    conn = rag_db.get_connection()
+    try:
+        assert store.get_document(conn, doc_id)["status"] == "pending"
+    finally:
+        conn.close()
+
+    events = _drain(job_id)
+    assert any(e["type"] == "progress" for e in events)
+    assert events[-1]["type"] == "complete"
+    assert events[-1]["num_chunks"] > 0
+
+    status = _wait_completed(job_id)
+    assert status["status"] == "completed"
+    assert status["progress"] == 1.0
+
+    conn = rag_db.get_connection()
+    try:
+        doc = store.get_document(conn, doc_id)
+        assert doc["status"] == "completed"
+        assert doc["num_chunks"] > 0
+        assert store.search_lexical(conn, scope, "alpha", 10)
+    finally:
+        conn.close()
+
+
+def test_ingestion_dedupe_by_hash(rag_home, stub_embeddings, tmp_path):
+    path = _write(tmp_path, "doc.txt", "alpha bravo charlie")
+    scope = store.kb_scope("K1")
+    doc_id, job_id = ingestion.start_ingestion(scope, "K1", None, "doc.txt", path)
+    _drain(job_id)
+    _wait_completed(job_id)
+
+    # Identical content -> same doc id, no re-ingest.
+    path2 = _write(tmp_path, "copy.txt", "alpha bravo charlie")
+    doc_id2, job_id2 = ingestion.start_ingestion(scope, "K1", None, "copy.txt", path2)
+    events = _drain(job_id2)
+    assert doc_id2 == doc_id
+    assert any(e.get("deduped") for e in events)
+
+    conn = rag_db.get_connection()
+    try:
+        assert len(store.list_documents(conn, scope)) == 1
+    finally:
+        conn.close()
+
+
+def test_ingestion_delete_removes_all_rows(rag_home, stub_embeddings, tmp_path):
+    path = _write(tmp_path, "doc.txt", "alpha bravo charlie delta")
+    scope = store.kb_scope("K1")
+    doc_id, job_id = ingestion.start_ingestion(scope, "K1", None, "doc.txt", path)
+    _drain(job_id)
+    _wait_completed(job_id)
+
+    conn = rag_db.get_connection()
+    try:
+        store.delete_document(conn, doc_id)
+        assert store.get_document(conn, doc_id) is None
+        assert store.search_lexical(conn, scope, "alpha", 10) == []
+        assert store.list_documents(conn, scope) == []
+    finally:
+        conn.close()
+
+
+def test_ingestion_rejects_unsupported_ext(rag_home, stub_embeddings, tmp_path):
+    path = _write(tmp_path, "doc.xyz", "alpha")
+    with pytest.raises(ValueError):
+        ingestion.start_ingestion(store.kb_scope("K1"), "K1", None, "doc.xyz", path)
+
+
+def test_ingestion_empty_doc_completes_with_zero_chunks(rag_home, stub_embeddings, tmp_path):
+    path = _write(tmp_path, "empty.txt", "   \n  ")
+    scope = store.kb_scope("K1")
+    doc_id, job_id = ingestion.start_ingestion(scope, "K1", None, "empty.txt", path)
+    events = _drain(job_id)
+    assert events[-1]["type"] == "complete"
+    assert events[-1]["num_chunks"] == 0
+    status = _wait_completed(job_id)
+    assert status["status"] == "completed"
+
+
+@pytest.mark.skipif(
+    os.environ.get("RAG_REAL_EMBEDDER") != "1",
+    reason = "set RAG_REAL_EMBEDDER=1 to run the real sentence-transformers test",
+)
+def test_ingestion_with_real_embedder(rag_home, tmp_path):
+    path = _write(tmp_path, "doc.txt", "The Kestrel-9 turbine is rated at 9.5 megawatts.")
+    scope = store.kb_scope("K1")
+    doc_id, job_id = ingestion.start_ingestion(scope, "K1", None, "doc.txt", path)
+    _drain(job_id)
+    status = _wait_completed(job_id, timeout = 120.0)
+    assert status["status"] == "completed"
+
+    from core.rag import retrieval
+
+    conn = rag_db.get_connection()
+    try:
+        hits = retrieval.retrieve_hybrid(conn, scope, "how much power does the turbine make?", k = 5)
+        assert hits and hits[0].chunk_id == f"{doc_id}:0"
+    finally:
+        conn.close()
diff --git a/studio/backend/tests/test_rag_preview.py b/studio/backend/tests/test_rag_preview.py
new file mode 100644
index 0000000000..e7f2a39792
--- /dev/null
+++ b/studio/backend/tests/test_rag_preview.py
@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""PDF region locator + citation preview route tests."""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+
+pytest.importorskip("pymupdf")
+pytest.importorskip("sqlite_vec")
+
+
+def _make_pdf(path) -> None:
+    import pymupdf
+
+    doc = pymupdf.open()
+    body = (
+        "BERT is designed to pre-train deep bidirectional representations.\n"
+        "The two pre-training objectives are masked language modeling and next "
+        "sentence prediction.\n"
+        "The Transformer base model uses eight attention heads in each layer.\n"
+    )
+    for _ in range(3):
+        page = doc.new_page()
+        page.insert_text((72, 72), body, fontsize = 11)
+    doc.save(str(path))
+    doc.close()
+
+
+def _ingest(home, pdf_path):
+    from core.rag import ingestion, store
+    from storage import rag_db
+
+    conn = rag_db.get_connection()
+    kb_id = store.create_kb(conn, name = "kb")
+    conn.close()
+    doc_id, job_id = ingestion.start_ingestion(
+        store.kb_scope(kb_id), kb_id, None, "doc.pdf", str(pdf_path)
+    )
+    t0 = time.time()
+    while time.time() - t0 < 30:
+        s = ingestion.get_job_status(job_id)
+        if s and s["status"] in ("completed", "failed"):
+            break
+        time.sleep(0.05)
+    assert s and s["status"] == "completed", s
+    return kb_id, doc_id
+
+
+def test_chunks_carry_pdf_regions(rag_home, stub_embeddings):
+    from utils.paths import ensure_dir, rag_uploads_root
+
+    pdf = ensure_dir(rag_uploads_root()) / "doc.pdf"
+    _make_pdf(pdf)
+    kb_id, doc_id = _ingest(rag_home, pdf)
+
+    from storage import rag_db
+
+    conn = rag_db.get_connection()
+    try:
+        rows = conn.execute(
+            "SELECT pdf_regions_json FROM chunks WHERE document_id=?", (doc_id,)
+        ).fetchall()
+        stored_path = conn.execute(
+            "SELECT stored_path FROM documents WHERE id=?", (doc_id,)
+        ).fetchone()["stored_path"]
+    finally:
+        conn.close()
+
+    assert rows, "no chunks were stored"
+    assert stored_path and stored_path.endswith(".pdf")
+    with_regions = [r for r in rows if r["pdf_regions_json"]]
+    assert with_regions, "expected at least one chunk with PDF highlight regions"
+    import json
+
+    region = json.loads(with_regions[0]["pdf_regions_json"])[0]
+    for key in ("pageIndex", "x", "y", "width", "height"):
+        assert key in region
+        if key in ("x", "y", "width", "height"):
+            assert 0.0 <= region[key] <= 1.0
+
+
+def test_preview_routes_and_signed_file(rag_home, stub_embeddings):
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    from auth.authentication import get_current_subject
+    from routes.rag import router
+
+    from utils.paths import ensure_dir, rag_uploads_root
+
+    pdf = ensure_dir(rag_uploads_root()) / "doc.pdf"
+    _make_pdf(pdf)
+    kb_id, doc_id = _ingest(rag_home, pdf)
+
+    app = FastAPI()
+    app.include_router(router, prefix = "/api/rag")
+    app.dependency_overrides[get_current_subject] = lambda: "tester"
+    c = TestClient(app)
+
+    res = c.post(
+        "/api/rag/search",
+        json = {
+            "query": "masked language modeling next sentence",
+            "kb_id": kb_id,
+            "mode": "lexical",
+        },
+    ).json()["results"]
+    assert res
+    chunk_id = res[0]["chunkId"]
+
+    pt = c.get(f"/api/rag/documents/{doc_id}/preview-target", params = {"chunk_id": chunk_id}).json()
+    assert pt["mediaKind"] == "pdf"
+    assert pt["text"]
+
+    url = c.get(f"/api/rag/documents/{doc_id}/file-url").json()["url"]
+    full = c.get(url)
+    assert full.status_code == 200 and full.content[:4] == b"%PDF"
+    rng = c.get(url, headers = {"Range": "bytes=0-99"})
+    assert rng.status_code in (200, 206)
+    assert (
+        c.get(
+            f"/api/rag/documents/{doc_id}/file-signed",
+            params = {"token": "bad.token.sig"},
+        ).status_code
+        == 401
+    )
+
+
+def test_norm_token_decomposes_ligatures():
+    # NFKC folds ligature glyphs to ASCII so anchors match (search_for misses these).
+    from core.rag.locators import _norm_token
+
+    assert _norm_token("significant") == "significant"  # fi
+    assert _norm_token("effort.") == "effort"  # ff + trailing punct
+    assert _norm_token("**Bold**") == "bold"
+    assert _norm_token("...") == ""
+
+
+def test_locator_handles_midword_anchor_and_locates_line():
+    # A span beginning mid-word still locates: first/last tokens dropped.
+    import pymupdf
+
+    from core.rag.locators import LocatorMatch, _regions_for_match
+
+    doc = pymupdf.open()
+    page = doc.new_page()
+    page.insert_text((72, 200), "alpha beta gamma delta epsilon zeta eta theta", fontsize = 12)
+    page_text = doc[0].get_text("text")  # mirrors what the parser stores
+    start = page_text.index("lpha")
+    end = page_text.index("theta") + 3
+    match = LocatorMatch(page_index = 0, page_number = 1, start = start, end = end)
+    rects = _regions_for_match(doc, page_text, match)
+    doc.close()
+
+    assert rects, "expected a located region for the interior phrase"
+    r = rects[0]
+    for k in ("pageIndex", "pageNumber", "x", "y", "width", "height"):
+        assert k in r
+    # Drawn near y=200 on a ~842pt page -> normalized y in the top half.
+    assert 0.0 < r["y"] < 0.5
+    assert r["width"] > 0 and r["height"] > 0
+
+
+def test_sign_verify_roundtrip(rag_home):
+    from routes import rag as rag_routes
+
+    tok = rag_routes._sign_document("doc-123")
+    assert rag_routes._verify_document_token(tok) == "doc-123"
+    assert rag_routes._verify_document_token("doc-123.0.deadbeef") is None  # expired/bad
+    assert rag_routes._verify_document_token("garbage") is None
diff --git a/studio/backend/tests/test_rag_retrieval.py b/studio/backend/tests/test_rag_retrieval.py
new file mode 100644
index 0000000000..69d9e90871
--- /dev/null
+++ b/studio/backend/tests/test_rag_retrieval.py
@@ -0,0 +1,432 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Retrieval + tool tests: RRF fusion, min-score floor, scope, source-map."""
+
+import math
+
+import pytest
+
+from core.rag import config, retrieval, store, tool
+from core.rag.chunking import Chunk
+
+VOCAB = ["alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel"]
+
+
+def _embed(text):
+    v = [float(text.lower().count(w)) for w in VOCAB]
+    n = math.sqrt(sum(x * x for x in v)) or 1.0
+    return [x / n for x in v]
+
+
+@pytest.fixture
+def bow_embeddings(monkeypatch):
+    """Bag-of-words embedder matching the vectors stored in the db."""
+    from core.rag import embeddings
+
+    monkeypatch.setattr(
+        embeddings,
+        "encode",
+        lambda texts, *, model_name = None, normalize = True: [_embed(t) for t in texts],
+    )
+    monkeypatch.setattr(embeddings, "dim", lambda model_name = None: len(VOCAB))
+
+
+def _chunk(
+    text,
+    index = 0,
+    page = None,
+):
+    return Chunk(
+        text = text,
+        token_count = len(text.split()),
+        page_number = page,
+        source_page_index = 0,
+        chunk_index = index,
+        page_char_start = 0,
+        page_char_end = len(text),
+    )
+
+
+def _add_doc(
+    conn,
+    scope,
+    doc_id,
+    filename,
+    sha,
+    text,
+    page = None,
+):
+    store.create_document(conn, scope = scope, filename = filename, sha256 = sha, document_id = doc_id)
+    store.add_chunks(conn, scope, doc_id, [_chunk(text, 0, page)], [_embed(text)])
+
+
+def test_rrf_ranks_doc_in_both_lists_first():
+    # A chunk near the top of both rankings beats one in a single list.
+    lexical = [
+        retrieval.Hit("a", 1.0, lexical_score = 1.0),
+        retrieval.Hit("b", 0.5, lexical_score = 0.5),
+    ]
+    dense = [
+        retrieval.Hit("a", 0.9, dense_score = 0.9),
+        retrieval.Hit("c", 0.8, dense_score = 0.8),
+    ]
+    fused = retrieval._rrf([lexical, dense], rrf_k = 60, top_k = 10)
+    assert fused[0].chunk_id == "a"
+    assert fused[0].lexical_score == 1.0 and fused[0].dense_score == 0.9
+
+
+def test_retrieve_hybrid_returns_relevant_chunk(rag_conn, bow_embeddings):
+    _add_doc(rag_conn, "kb_a", "d1", "f1", "h1", "alpha bravo charlie")
+    _add_doc(rag_conn, "kb_a", "d2", "f2", "h2", "golf hotel delta")
+    hits = retrieval.retrieve_hybrid(rag_conn, "kb_a", "alpha bravo", k = 5)
+    assert hits[0].chunk_id == "d1:0"
+
+
+def test_retrieve_dense_round_trips(rag_conn, bow_embeddings):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", "alpha alpha")
+    _add_doc(rag_conn, "kb_a", "d2", "f", "h2", "hotel golf")
+    hits = retrieval.retrieve_dense(rag_conn, "kb_a", "alpha", 5)
+    assert hits[0].chunk_id == "d1:0"
+    assert hits[0].dense_score is not None and hits[0].dense_score > 0.99
+
+
+def test_filter_min_score_gates_dense_hits():
+    hits = [
+        retrieval.Hit("a", 1.0, dense_score = 0.9),
+        retrieval.Hit("b", 0.5, dense_score = 0.2),
+        retrieval.Hit("c", 0.4, lexical_score = 0.4),  # no dense_score -> kept
+    ]
+    out = retrieval.filter_min_score(hits, 0.5)
+    ids = {h.chunk_id for h in out}
+    assert ids == {"a", "c"}  # b below floor, c lexical-only passes
+    assert retrieval.filter_min_score(hits, 0.0) == hits  # floor off = identity
+
+
+def test_tool_kb_scope_wins_over_thread(rag_conn, bow_embeddings, monkeypatch):
+    seen = {}
+
+    def fake(conn, scope, q, **k):
+        seen["scope"] = scope
+        return []
+
+    monkeypatch.setattr(retrieval, "retrieve_hybrid", fake)
+    tool.search_knowledge_base(query = "q", scope_kb_id = "K", scope_thread_id = "T")
+    assert seen["scope"] == "kb_K"
+
+
+def test_tool_empty_query_errors(rag_home):
+    assert tool.search_knowledge_base(query = "   ").startswith("Error")
+
+
+def test_tool_missing_scope_message(rag_home):
+    out = tool.search_knowledge_base(query = "hello")
+    assert "No documents" in out
+
+
+def test_tool_formats_chunks_and_sources(rag_conn, bow_embeddings, monkeypatch):
+    _add_doc(rag_conn, "kb_a", "d1", "paper.pdf", "h1", "body text here", page = 3)
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_hybrid",
+        lambda conn, scope, q, **k: [retrieval.Hit("d1:0", 1.0)],
+    )
+    text, sources = tool.search_knowledge_base_with_sources(query = "q", scope_kb_id = "a")
+    assert '<chunk id="1" source="paper.pdf" page="3">' in text
+    assert "body text here" in text
+    assert sources == [
+        {
+            "citationId": 1,
+            "chunkId": "d1:0",
+            "documentId": "d1",
+            "filename": "paper.pdf",
+            "page": 3,
+            "text": "body text here",
+            "score": 1.0,
+        }
+    ]
+
+
+def test_tool_kb_scope_retrieves_from_db(rag_conn, bow_embeddings):
+    # End-to-end (no retrieve stub): doc found via its scope_kb_id (#8).
+    _add_doc(rag_conn, "kb_K", "d1", "kb.pdf", "h1", "alpha bravo charlie", page = 1)
+    text, sources = tool.search_knowledge_base_with_sources(query = "alpha bravo", scope_kb_id = "K")
+    assert "No matching chunks" not in text
+    assert sources and sources[0]["chunkId"] == "d1:0"
+    assert sources[0]["filename"] == "kb.pdf"
+    # A different KB id sees nothing (scope isolation).
+    other, other_sources = tool.search_knowledge_base_with_sources(
+        query = "alpha bravo", scope_kb_id = "OTHER"
+    )
+    assert other_sources == [] and "No matching chunks" in other
+
+
+def test_dispatcher_appends_sources_sentinel(rag_conn, bow_embeddings, monkeypatch):
+    # JSON source-map appended after the sentinel; text before it stays clean.
+    import json
+
+    from core.inference import tools
+
+    _add_doc(rag_conn, "kb_a", "d1", "paper.pdf", "h1", "body text here", page = 3)
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_hybrid",
+        lambda conn, scope, q, **k: [retrieval.Hit("d1:0", 1.0)],
+    )
+    out = tools._search_knowledge_base({"query": "q"}, {"kb_id": "a"})
+    assert tools.RAG_SOURCES_SENTINEL in out
+    model_text, _, payload = out.partition(tools.RAG_SOURCES_SENTINEL)
+    assert "__RAG_SOURCES__" not in model_text  # model never sees the JSON
+    assert '<chunk id="1"' in model_text
+    sources = json.loads(payload)
+    assert sources[0]["documentId"] == "d1"
+    assert sources[0]["chunkId"] == "d1:0"
+    assert sources[0]["page"] == 3
+
+
+def test_dispatcher_no_sentinel_when_no_hits(rag_home, monkeypatch):
+    from core.inference import tools
+
+    monkeypatch.setattr(retrieval, "retrieve_hybrid", lambda conn, scope, q, **k: [])
+    out = tools._search_knowledge_base({"query": "hello"}, {"kb_id": "missing"})
+    assert tools.RAG_SOURCES_SENTINEL not in out
+
+
+def test_search_for_autoinject_gates_on_dense_score(rag_conn, bow_embeddings, monkeypatch):
+    _add_doc(rag_conn, "kb_a", "d1", "paper.pdf", "h1", "body text here", page = 3)
+
+    def _hits(score, **kw):
+        return lambda conn, scope, q, **k: [retrieval.Hit("d1:0", 1.0, **{kw["key"]: score})]
+
+    # Strong dense hit -> injected.
+    monkeypatch.setattr(retrieval, "retrieve_hybrid", _hits(0.8, key = "dense_score"))
+    found = tool.search_for_autoinject(query = "q", scope_kb_id = "a", min_dense_score = 0.55)
+    assert found is not None
+    text, sources = found
+    assert '<chunk id="1"' in text and sources[0]["chunkId"] == "d1:0"
+
+    # Dense below floor -> nothing injected.
+    monkeypatch.setattr(retrieval, "retrieve_hybrid", _hits(0.30, key = "dense_score"))
+    assert tool.search_for_autoinject(query = "q", scope_kb_id = "a", min_dense_score = 0.55) is None
+
+    # Lexical-only hit (no dense score) does not auto-inject.
+    monkeypatch.setattr(retrieval, "retrieve_hybrid", _hits(1.0, key = "lexical_score"))
+    assert tool.search_for_autoinject(query = "q", scope_kb_id = "a", min_dense_score = 0.55) is None
+
+
+def test_search_for_autoinject_bm25_gates_on_dense_probe(rag_conn, bow_embeddings, monkeypatch):
+    # BM25 hits carry no cosine, so the gate uses a dense 1-NN probe (#5).
+    _add_doc(rag_conn, "kb_a", "d1", "paper.pdf", "h1", "body text here", page = 3)
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_hybrid",
+        lambda conn, scope, q, **k: [retrieval.Hit("d1:0", 1.0, lexical_score = 2.5)],
+    )
+
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_dense",
+        lambda conn, scope, q, k = None, **kw: [retrieval.Hit("d1:0", 0.82, dense_score = 0.82)],
+    )
+    found = tool.search_for_autoinject(
+        query = "q", scope_kb_id = "a", mode = "lexical", min_dense_score = 0.70
+    )
+    assert found is not None and found[1][0]["chunkId"] == "d1:0"
+
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_dense",
+        lambda conn, scope, q, k = None, **kw: [retrieval.Hit("d1:0", 0.40, dense_score = 0.40)],
+    )
+    assert (
+        tool.search_for_autoinject(query = "q", scope_kb_id = "a", mode = "lexical", min_dense_score = 0.70)
+        is None
+    )
+
+
+def test_search_for_autoinject_empty_query_or_scope(rag_home):
+    assert tool.search_for_autoinject(query = "  ", scope_kb_id = "a") is None
+    assert tool.search_for_autoinject(query = "hello") is None  # no scope
+
+
+def test_build_rag_autoinject_emits_pipeline(monkeypatch):
+    # Auto-inject yields the same tool card + source-map a real call would.
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    monkeypatch.setattr(
+        tool,
+        "search_for_autoinject",
+        lambda **k: (
+            '<chunk id="1" source="d.pdf">hi</chunk>',
+            [{"citationId": 1, "filename": "d.pdf"}],
+        ),
+    )
+    conv = [{"role": "user", "content": "When was DeepSeek V4 released?"}]
+    out = tools.build_rag_autoinject(conv, {"thread_id": "t1"})
+    assert out is not None
+    kinds = [e["type"] for e in out["events"]]
+    assert "tool_start" in kinds and "tool_end" in kinds
+    te = next(e for e in out["events"] if e["type"] == "tool_end")
+    assert te["tool_name"] == "search_knowledge_base"
+    assert tools.RAG_SOURCES_SENTINEL in te["result"]
+    assert out["messages"][0]["tool_calls"][0]["function"]["name"] == "search_knowledge_base"
+    assert "__RAG_SOURCES__" not in out["messages"][1]["content"]
+
+
+def test_build_rag_autoinject_skips_without_hit(monkeypatch):
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    monkeypatch.setattr(tool, "search_for_autoinject", lambda **k: None)
+    assert (
+        tools.build_rag_autoinject([{"role": "user", "content": "hi"}], {"thread_id": "t1"}) is None
+    )
+
+
+def test_build_rag_autoinject_enabled_by_default(monkeypatch):
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.delenv("RAG_AUTOINJECT", raising = False)
+    monkeypatch.delenv("RAG_AUTOINJECT_MIN_SCORE", raising = False)
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    seen: dict = {}
+
+    def fake(**k):
+        seen.update(k)
+        return ("x", [{"citationId": 1}])
+
+    monkeypatch.setattr(tool, "search_for_autoinject", fake)
+    out = tools.build_rag_autoinject([{"role": "user", "content": "hi"}], {"thread_id": "t1"})
+    assert out is not None
+    assert seen["min_dense_score"] == 0.70  # high-precision floor by default
+
+
+def test_build_rag_autoinject_caps_top_k(monkeypatch):
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.setenv("RAG_AUTOINJECT", "1")
+    monkeypatch.setenv("RAG_AUTOINJECT_TOP_K", "4")
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    seen: dict = {}
+
+    def fake(**k):
+        seen.update(k)
+        return ("x", [{"citationId": 1}])
+
+    monkeypatch.setattr(tool, "search_for_autoinject", fake)
+    conv = [{"role": "user", "content": "q"}]
+    tools.build_rag_autoinject(conv, {"thread_id": "t1"})
+    assert seen["top_k"] == 4  # lean default
+    tools.build_rag_autoinject(conv, {"thread_id": "t1", "default_top_k": 2})
+    assert seen["top_k"] == 2  # lower user setting wins
+
+
+def test_build_rag_autoinject_disabled_by_env(monkeypatch):
+    from core.inference import tools
+
+    monkeypatch.setenv("RAG_AUTOINJECT", "0")
+    assert (
+        tools.build_rag_autoinject([{"role": "user", "content": "hi"}], {"thread_id": "t1"}) is None
+    )
+    # No scope -> also a no-op.
+    monkeypatch.delenv("RAG_AUTOINJECT", raising = False)
+    assert tools.build_rag_autoinject([{"role": "user", "content": "hi"}], None) is None
+
+
+def test_retrieve_hybrid_mode_selects_backend(monkeypatch):
+    # ``mode`` runs only the chosen backend; hybrid uses config counts + rrf_k.
+    calls: list = []
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_lexical",
+        lambda c, s, q, k = None: calls.append(("lex", k)) or [],
+    )
+    monkeypatch.setattr(
+        retrieval,
+        "retrieve_dense",
+        lambda c, s, q, k = None, *, model_name = None: calls.append(("dense", k)) or [],
+    )
+    monkeypatch.setattr(
+        retrieval,
+        "_rrf",
+        lambda rankings, rrf_k, top_k: calls.append(("rrf", rrf_k, top_k)) or [],
+    )
+
+    calls.clear()
+    retrieval.retrieve_hybrid(None, "kb_a", "q", k = 5, mode = "lexical")
+    assert [c[0] for c in calls] == ["lex"]  # dense + rrf skipped
+
+    calls.clear()
+    retrieval.retrieve_hybrid(None, "kb_a", "q", k = 5, mode = "dense")
+    assert [c[0] for c in calls] == ["dense"]
+
+    calls.clear()
+    retrieval.retrieve_hybrid(None, "kb_a", "q", k = 5, mode = "hybrid")
+    # Candidate pools + rrf_k come from config (no per-request override).
+    assert ("lex", config.TOP_K_LEXICAL) in calls
+    assert ("dense", config.TOP_K_DENSE) in calls
+    rrf = next(c for c in calls if c[0] == "rrf")
+    assert rrf[1] == config.RRF_K and rrf[2] == 5  # config rrf_k + final top_k
+
+
+def test_scope_overrides_reach_retrieval(monkeypatch):
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    seen: dict = {}
+
+    def fake_search(**kw):
+        seen.update(kw)
+        return ("text", [])
+
+    monkeypatch.setattr(tool, "search_knowledge_base_with_sources", fake_search)
+    tools._search_knowledge_base(
+        {"query": "q"},
+        {"kb_id": "a", "mode": "dense", "default_top_k": 11},
+    )
+    assert seen["mode"] == "dense"
+    assert seen["top_k"] == 11
+    # Unknown mode falls back to hybrid.
+    seen.clear()
+    tools._search_knowledge_base({"query": "q"}, {"kb_id": "a", "mode": "bogus"})
+    assert seen["mode"] == "hybrid"
+
+
+def test_build_rag_autoinject_scope_overrides_env(monkeypatch):
+    from core.inference import tools
+    from storage import rag_db
+
+    monkeypatch.setattr(rag_db, "RAG_AVAILABLE", True, raising = False)
+    seen: dict = {}
+
+    def fake_autoinject(**k):
+        seen.update(k)
+        return ('<chunk id="1" source="d.pdf">hi</chunk>', [{"citationId": 1}])
+
+    monkeypatch.setattr(tool, "search_for_autoinject", fake_autoinject)
+    conv = [{"role": "user", "content": "q"}]
+
+    # Scope enables + overrides the floor though env says off.
+    monkeypatch.setenv("RAG_AUTOINJECT", "0")
+    out = tools.build_rag_autoinject(
+        conv,
+        {
+            "thread_id": "t1",
+            "autoinject": True,
+            "autoinject_min_score": 0.8,
+            "mode": "dense",
+        },
+    )
+    assert out is not None
+    assert seen["min_dense_score"] == 0.8
+    assert seen["mode"] == "dense"
+
+    # Explicit False disables even with the env default on.
+    monkeypatch.setenv("RAG_AUTOINJECT", "1")
+    assert tools.build_rag_autoinject(conv, {"thread_id": "t1", "autoinject": False}) is None
diff --git a/studio/backend/tests/test_rag_store.py b/studio/backend/tests/test_rag_store.py
new file mode 100644
index 0000000000..4c54b02ea7
--- /dev/null
+++ b/studio/backend/tests/test_rag_store.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Store tests: incremental writes, dedupe, delete, scope, dense + lexical."""
+
+import math
+
+from core.rag import store
+from core.rag.chunking import Chunk
+
+VOCAB = ["alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel"]
+
+
+def embed(text):
+    v = [float(text.lower().count(w)) for w in VOCAB]
+    n = math.sqrt(sum(x * x for x in v)) or 1.0
+    return [x / n for x in v]
+
+
+def _chunk(
+    text,
+    index = 0,
+    page = None,
+):
+    return Chunk(
+        text = text,
+        token_count = len(text.split()),
+        page_number = page,
+        source_page_index = 0,
+        chunk_index = index,
+        page_char_start = 0,
+        page_char_end = len(text),
+    )
+
+
+def _add_doc(conn, scope, doc_id, filename, sha, texts):
+    chunks = [_chunk(t, i) for i, t in enumerate(texts)]
+    vectors = [embed(t) for t in texts]
+    store.create_document(conn, scope = scope, filename = filename, sha256 = sha, document_id = doc_id)
+    store.add_chunks(conn, scope, doc_id, chunks, vectors)
+
+
+def test_lexical_returns_only_matching_docs(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "d1.txt", "h1", ["alpha bravo charlie"])
+    _add_doc(rag_conn, "kb_a", "d2", "d2.txt", "h2", ["golf hotel india"])
+    hits = store.search_lexical(rag_conn, "kb_a", "alpha", 10)
+    assert [cid for cid, _ in hits] == ["d1:0"]  # d2 not returned (score 0)
+
+
+def test_scope_isolation(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", ["alpha bravo"])
+    _add_doc(rag_conn, "kb_b", "d2", "f", "h2", ["alpha bravo"])
+    assert [cid for cid, _ in store.search_lexical(rag_conn, "kb_b", "alpha", 10)] == ["d2:0"]
+
+
+def test_match_query_sanitizes_special_chars():
+    assert store._match_query('AND OR "quote" (paren) -dash') != ""
+
+
+def test_lexical_does_not_crash_on_punctuation(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", ["alpha bravo"])
+    # Must not raise on FTS operators in the query.
+    store.search_lexical(rag_conn, "kb_a", 'NEAR("x" AND', 5)
+
+
+def test_dense_ranks_by_cosine(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", ["alpha alpha"])
+    _add_doc(rag_conn, "kb_a", "d2", "f", "h2", ["hotel golf"])
+    ranked = store.search_dense(rag_conn, "kb_a", embed("alpha"), 10)
+    assert ranked[0][0] == "d1:0" and ranked[0][1] > 0.99
+
+
+def test_dense_empty_before_any_ingest(rag_conn):
+    # No chunks_vec table yet -> [], no crash.
+    assert store.search_dense(rag_conn, "kb_a", embed("alpha"), 10) == []
+
+
+def test_dedupe_by_hash(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "SHA", ["alpha"])
+    assert store.document_by_hash(rag_conn, "kb_a", "SHA") == "d1"
+    assert store.document_by_hash(rag_conn, "kb_a", "OTHER") is None
+
+
+def test_delete_document_purges_all_tables(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", ["alpha bravo"])
+    store.delete_document(rag_conn, "d1")
+    assert store.search_lexical(rag_conn, "kb_a", "alpha", 10) == []
+    assert store.search_dense(rag_conn, "kb_a", embed("alpha"), 10) == []
+    assert store.chunks_by_id(rag_conn, ["d1:0"]) == {}
+    assert store.get_document(rag_conn, "d1") is None
+
+
+def test_incremental_add_is_flat(rag_conn):
+    # Adding doc2 must not touch doc1's fts rowids (append, not rebuild).
+    _add_doc(rag_conn, "kb_a", "d1", "f", "h1", ["alpha bravo charlie"])
+    before = rag_conn.execute(
+        "SELECT rowid, chunk_id FROM chunks_fts WHERE scope='kb_a'"
+    ).fetchall()
+    _add_doc(rag_conn, "kb_a", "d2", "f", "h2", ["delta echo foxtrot"])
+    after = rag_conn.execute(
+        "SELECT rowid, chunk_id FROM chunks_fts WHERE scope='kb_a' AND chunk_id LIKE 'd1:%'"
+    ).fetchall()
+    before_d1 = [(r["rowid"], r["chunk_id"]) for r in before if r["chunk_id"].startswith("d1:")]
+    after_d1 = [(r["rowid"], r["chunk_id"]) for r in after]
+    assert before_d1 == after_d1
+
+
+def test_chunks_by_id_joins_filename(rag_conn):
+    _add_doc(rag_conn, "kb_a", "d1", "paper.pdf", "h1", ["body text here"])
+    rows = store.chunks_by_id(rag_conn, ["d1:0"])
+    assert rows["d1:0"]["filename"] == "paper.pdf"
+    assert rows["d1:0"]["text"] == "body text here"
+
+
+def test_kb_crud_and_delete_cascades(rag_conn):
+    kb_id = store.create_kb(rag_conn, name = "My KB", description = "d", kb_id = "K1")
+    assert store.get_kb(rag_conn, kb_id)["name"] == "My KB"
+    assert [k["id"] for k in store.list_kbs(rag_conn)] == ["K1"]
+
+    scope = store.kb_scope("K1")
+    _add_doc(rag_conn, scope, "doc1", "f", "h1", ["alpha bravo"])
+    store.delete_kb(rag_conn, "K1")
+    assert store.get_kb(rag_conn, "K1") is None
+    assert store.list_documents(rag_conn, scope) == []
+    assert store.search_lexical(rag_conn, scope, "alpha", 10) == []
diff --git a/studio/backend/tests/test_safetensors_tool_loop.py b/studio/backend/tests/test_safetensors_tool_loop.py
index 16ed1dc182..8aa6e5df4e 100644
--- a/studio/backend/tests/test_safetensors_tool_loop.py
+++ b/studio/backend/tests/test_safetensors_tool_loop.py
@@ -23,6 +23,7 @@ from core.inference.safetensors_agentic import (
     strip_tool_markup_streaming,
 )
 from core.inference.tool_call_parser import (
+    RAG_MAX_SEARCHES_PER_TURN,
     has_tool_signal,
     parse_tool_calls_from_text,
     strip_tool_markup,
@@ -205,6 +206,7 @@ class FakeExecuteTool:
         cancel_event = None,
         timeout = None,
         session_id = None,
+        rag_scope = None,
     ):
         self.calls.append((name, arguments))
         result = self.results.pop(0) if self.results else "OK"
@@ -625,6 +627,44 @@ class TestLoopBehaviour:
             for event in events
         )
 
+    def test_kb_search_capped_per_turn(self):
+        # Paraphrased KB searches differ by args (dup guard misses them); the
+        # per-turn cap stops the runaway re-search loop.
+        n = RAG_MAX_SEARCHES_PER_TURN
+        queries = [f"paraphrase {i}" for i in range(n + 1)]
+        turns = [
+            [
+                '<tool_call>{"name":"search_knowledge_base",'
+                f'"arguments":{{"query":"{q}"}}}}</tool_call>'
+            ]
+            for q in queries
+        ] + [["final answer"]]
+        turn_iter = iter(turns)
+
+        def _gen(_messages):
+            try:
+                chunks = next(turn_iter)
+            except StopIteration:
+                return
+            acc = ""
+            for c in chunks:
+                acc += c
+                yield acc
+
+        exec_fn = FakeExecuteTool([f"chunk-{i}" for i in range(n)])
+        loop = run_safetensors_tool_loop(
+            single_turn = _gen,
+            messages = [{"role": "user", "content": "hi"}],
+            tools = [{"type": "function", "function": {"name": "search_knowledge_base"}}],
+            execute_tool = exec_fn,
+        )
+        events = _collect_events(loop)
+        assert len(exec_fn.calls) == n
+        assert all(c[0] == "search_knowledge_base" for c in exec_fn.calls)
+        tool_end_events = [e for e in events if e["type"] == "tool_end"]
+        assert len(tool_end_events) == n + 1
+        assert "do not search again" in tool_end_events[n]["result"].lower()
+
     def test_image_sentinel_stripped_from_model_feed(self):
         # The image sentinel is stripped before the next turn, but tool_end still
         # carries the raw result for the UI.
diff --git a/studio/backend/utils/paths/__init__.py b/studio/backend/utils/paths/__init__.py
index 1dcc9191fd..6913a3be73 100644
--- a/studio/backend/utils/paths/__init__.py
+++ b/studio/backend/utils/paths/__init__.py
@@ -23,6 +23,9 @@ from .storage_roots import (
     auth_root,
     auth_db_path,
     studio_db_path,
+    rag_root,
+    rag_db_path,
+    rag_uploads_root,
     documents_root,
     project_workspaces_root,
     tmp_root,
@@ -66,6 +69,9 @@ __all__ = [
     "auth_root",
     "auth_db_path",
     "studio_db_path",
+    "rag_root",
+    "rag_db_path",
+    "rag_uploads_root",
     "documents_root",
     "project_workspaces_root",
     "tmp_root",
@@ -86,3 +92,6 @@ __all__ = [
     "resolve_tensorboard_dir",
     "resolve_dataset_path",
 ]
+
+# Bind the re-exports so the import-hoist verifier counts them as used.
+_ = (rag_root, rag_db_path, rag_uploads_root)
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index 63d24afd0c..10597a689b 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -96,6 +96,21 @@ def studio_db_path() -> Path:
     return studio_root() / "studio.db"
 
 
+def rag_root() -> Path:
+    """Root directory for retrieval-augmented-generation state (db + uploads)."""
+    return studio_root() / "rag"
+
+
+def rag_db_path() -> Path:
+    """SQLite file holding RAG documents, chunks, FTS5 + sqlite-vec indexes."""
+    return rag_root() / "rag.db"
+
+
+def rag_uploads_root() -> Path:
+    """Directory where uploaded source documents are stored for ingestion."""
+    return rag_root() / "uploads"
+
+
 def _xdg_user_dir(key: str) -> Path | None:
     config = Path.home() / ".config" / "user-dirs.dirs"
     try:
diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index 7d1283e94d..690da8c0c4 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -59,6 +59,7 @@
         "react": "^19.2.4",
         "react-day-picker": "^9.13.2",
         "react-dom": "^19.2.4",
+        "react-pdf": "10.4.1",
         "react-resizable-panels": "^4.6.4",
         "recharts": "3.7.0",
         "shadcn": "^4.2.0",
@@ -1661,6 +1662,256 @@
       "integrity": "sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==",
       "license": "MIT"
     },
+    "node_modules/@napi-rs/canvas": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas/-/canvas-0.1.100.tgz",
+      "integrity": "sha512-xglYA6q3XO5P3BNJYxVZ1IV7DLVjp1Py6nwag88YntrS+3vKHyYcMqXVS4ZztJmwz2uGvz1FWhI/4LgbR5uQDA==",
+      "license": "MIT",
+      "optional": true,
+      "workspaces": [
+        "e2e/*"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "optionalDependencies": {
+        "@napi-rs/canvas-android-arm64": "0.1.100",
+        "@napi-rs/canvas-darwin-arm64": "0.1.100",
+        "@napi-rs/canvas-darwin-x64": "0.1.100",
+        "@napi-rs/canvas-linux-arm-gnueabihf": "0.1.100",
+        "@napi-rs/canvas-linux-arm64-gnu": "0.1.100",
+        "@napi-rs/canvas-linux-arm64-musl": "0.1.100",
+        "@napi-rs/canvas-linux-riscv64-gnu": "0.1.100",
+        "@napi-rs/canvas-linux-x64-gnu": "0.1.100",
+        "@napi-rs/canvas-linux-x64-musl": "0.1.100",
+        "@napi-rs/canvas-win32-arm64-msvc": "0.1.100",
+        "@napi-rs/canvas-win32-x64-msvc": "0.1.100"
+      }
+    },
+    "node_modules/@napi-rs/canvas-android-arm64": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-android-arm64/-/canvas-android-arm64-0.1.100.tgz",
+      "integrity": "sha512-hjhCKhntPv9+t4ckHymdx0phYNcVW+GKQR6Lzw2zE+pOVjOplSmtx9nNNknTjbEDLcuLZqA1y8ufKg1XfgftzQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-darwin-arm64": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-darwin-arm64/-/canvas-darwin-arm64-0.1.100.tgz",
+      "integrity": "sha512-2PcswRaC7Ly645DGt88///zuFDhJxJYdKAs1uU3mfk1atYkXufgcgLfBpk6Tm12nCQBaNt1wpybuPZ4qOhTo8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-darwin-x64": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-darwin-x64/-/canvas-darwin-x64-0.1.100.tgz",
+      "integrity": "sha512-ePNZtj7pNIva/siZMg+HmbeozkIjqUIYdoymH8HaA3qK7LfzFN4WMBM8G6HQ9ZC+H3+Dnn5pqtiXpgLykaPOhw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-arm-gnueabihf": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm-gnueabihf/-/canvas-linux-arm-gnueabihf-0.1.100.tgz",
+      "integrity": "sha512-d5cDB48oWFGU8/XPhUOFAlySgb/VAu7D+s8fi55K1Pcfg8aPplHWqMgibhVLU8ky7Pyg/fuiVLz4Nf3JrSTuUA==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-arm64-gnu": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm64-gnu/-/canvas-linux-arm64-gnu-0.1.100.tgz",
+      "integrity": "sha512-rDxgxRu69RvDlX/bh9o22DxLsGr8EqsNgotL9+RwQE1S0b0cqeatqsw6aW45mukm0B42DIAaAacKaYQ8cqS1nw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-arm64-musl": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm64-musl/-/canvas-linux-arm64-musl-0.1.100.tgz",
+      "integrity": "sha512-K3mDW66N+xT2/V439u1alFANiBUjdEx2gLiNYnCmUsva5jZMxWTjafBYwTzYK+EMFMHrUoabuU+T1BIP5CgbYQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-riscv64-gnu": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-riscv64-gnu/-/canvas-linux-riscv64-gnu-0.1.100.tgz",
+      "integrity": "sha512-mooqUBTIsccZpnoQC4NgrC1v6C1vof39etLNMnBwCY+p0gajWJvAHLGQ6g/gGyS5YrpDW+GefSN4+Cvcr08UWw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-x64-gnu": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-x64-gnu/-/canvas-linux-x64-gnu-0.1.100.tgz",
+      "integrity": "sha512-1eCvkDCazm7FFhsT7DfGOdSaHgZVK3bt/dSBl5EWHOWmnz+I7j8tPseJqqD81NF+MH21jKUK4wQSDjN0mdhnTg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-linux-x64-musl": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-x64-musl/-/canvas-linux-x64-musl-0.1.100.tgz",
+      "integrity": "sha512-20arT6lnI19S68qNlii73TSEDbECNgzMz2EpldC1V3mZFuRkeujXkcebRk0LRJe9SEUAooYiLokfMViY8IX7yA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-win32-arm64-msvc": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-win32-arm64-msvc/-/canvas-win32-arm64-msvc-0.1.100.tgz",
+      "integrity": "sha512-DZFFT1wIAg37LJw37yhMRFfjATd3vTQzjZ1Yki8u2vhO6Hi5VE6BVaGQ1aaDu7xb4iMErz+9EOwjpS7xcxFeBw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@napi-rs/canvas-win32-x64-msvc": {
+      "version": "0.1.100",
+      "resolved": "https://registry.npmjs.org/@napi-rs/canvas-win32-x64-msvc/-/canvas-win32-x64-msvc-0.1.100.tgz",
+      "integrity": "sha512-MyT1j3mHC2+Lu4pBi9mKyMJhtP6U7k7EldY7sj/uS5gJA65gTXt8MefJQXLJo5d/vZbuWmfxzkEUNc/urV3pHA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
@@ -10959,6 +11210,18 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
     "node_modules/lop": {
       "version": "0.4.2",
       "resolved": "https://registry.npmjs.org/lop/-/lop-0.4.2.tgz",
@@ -10997,6 +11260,24 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
+    "node_modules/make-cancellable-promise": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/make-cancellable-promise/-/make-cancellable-promise-2.0.0.tgz",
+      "integrity": "sha512-3SEQqTpV9oqVsIWqAcmDuaNeo7yBO3tqPtqGRcKkEo0lrzD3wqbKG9mkxO65KoOgXqj+zH2phJ2LiAsdzlogSw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/wojtekmaj/make-cancellable-promise?sponsor=1"
+      }
+    },
+    "node_modules/make-event-props": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/make-event-props/-/make-event-props-2.0.0.tgz",
+      "integrity": "sha512-G/hncXrl4Qt7mauJEXSg3AcdYzmpkIITTNl5I+rH9sog5Yw0kK6vseJjCaPfOXqOqQuPUP89Rkhfz5kPS8ijtw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/wojtekmaj/make-event-props?sponsor=1"
+      }
+    },
     "node_modules/mammoth": {
       "version": "1.12.0",
       "resolved": "https://registry.npmjs.org/mammoth/-/mammoth-1.12.0.tgz",
@@ -11383,6 +11664,23 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/merge-refs": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/merge-refs/-/merge-refs-2.0.0.tgz",
+      "integrity": "sha512-3+B21mYK2IqUWnd2EivABLT7ueDhb0b8/dGK8LoFQPrU61YITeCMn14F7y7qZafWNZhUEKb24cJdiT5Wxs3prg==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/wojtekmaj/merge-refs?sponsor=1"
+      },
+      "peerDependencies": {
+        "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
@@ -12727,6 +13025,18 @@
       "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
       "license": "MIT"
     },
+    "node_modules/pdfjs-dist": {
+      "version": "5.4.296",
+      "resolved": "https://registry.npmjs.org/pdfjs-dist/-/pdfjs-dist-5.4.296.tgz",
+      "integrity": "sha512-DlOzet0HO7OEnmUmB6wWGJrrdvbyJKftI1bhMitK7O2N8W2gc757yyYBbINy9IDafXAV9wmKr9t7xsTaNKRG5Q==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=20.16.0 || >=22.3.0"
+      },
+      "optionalDependencies": {
+        "@napi-rs/canvas": "^0.1.80"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -13196,6 +13506,35 @@
       "license": "MIT",
       "peer": true
     },
+    "node_modules/react-pdf": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/react-pdf/-/react-pdf-10.4.1.tgz",
+      "integrity": "sha512-kS/35staVCBqS29verTQJQZXw7RfsRCPO3fdJoW1KXylcv7A9dw6DZ3vJXC2w+bIBgLw5FN4pOFvKSQtkQhPfA==",
+      "license": "MIT",
+      "dependencies": {
+        "clsx": "^2.0.0",
+        "dequal": "^2.0.3",
+        "make-cancellable-promise": "^2.0.0",
+        "make-event-props": "^2.0.0",
+        "merge-refs": "^2.0.0",
+        "pdfjs-dist": "5.4.296",
+        "tiny-invariant": "^1.0.0",
+        "warning": "^4.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/wojtekmaj/react-pdf?sponsor=1"
+      },
+      "peerDependencies": {
+        "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/react-redux": {
       "version": "9.2.0",
       "resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
@@ -15253,6 +15592,15 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/warning": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/warning/-/warning-4.0.3.tgz",
+      "integrity": "sha512-rpJyN222KWIvHJ/F53XSZv0Zl/accqHR8et1kpaMTD/fLCRxtV8iX8czMzY7sVZupTI3zcUTg8eycS2kNF9l6w==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.0.0"
+      }
+    },
     "node_modules/web-namespaces": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 8537b0c076..1e527813f9 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -68,6 +68,7 @@
     "react": "^19.2.4",
     "react-day-picker": "^9.13.2",
     "react-dom": "^19.2.4",
+    "react-pdf": "10.4.1",
     "react-resizable-panels": "^4.6.4",
     "recharts": "3.7.0",
     "shadcn": "^4.2.0",
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 2abc4d190b..9cb28a198b 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -49,7 +49,9 @@ import {
   CursorInfo02Icon,
   DashboardCircleIcon,
   Delete02Icon,
+  Download01Icon,
   DownloadSquare01Icon,
+  Upload01Icon,
   Edit03Icon,
   FolderAddIcon,
   FolderExportIcon,
@@ -66,6 +68,17 @@ import {
   TestTube01Icon,
   ZapIcon,
 } from "@hugeicons/core-free-icons";
+import {
+  exportConversationRawJsonl,
+  exportConversationCsv,
+  exportConversationShareGPT,
+  exportBulkConversationsMerged,
+  exportBulkConversationsSeparate,
+  importConversationsFromFile,
+  EXPORT_FORMATS_LIST,
+  type ConvExportFormat,
+} from "@/features/chat/prompt-storage/prompt-storage-dialog";
+import { listStoredChatThreads } from "@/features/chat/utils/chat-history-storage";
 import {
   Tooltip,
   TooltipContent,
@@ -245,6 +258,41 @@ export function AppSidebar() {
   const isChatRoute = pathname.startsWith("/chat");
   const isStudioRoute = pathname === "/studio" || pathname.startsWith("/studio/");
   const [chatOpen, setChatOpen] = useState(true);
+
+  const recentsImportInputRef = useRef<HTMLInputElement>(null);
+
+  async function handleImportToRecents(file: File) {
+    try {
+      const count = await importConversationsFromFile(file, null);
+      if (count === 0) {
+        toast.info("No conversations found in file.");
+      } else {
+        toast.success(`Imported ${count} conversation${count === 1 ? "" : "s"} to Recents.`);
+      }
+    } catch {
+      toast.error("Import failed.");
+    }
+  }
+
+  async function handleBulkExport(scope: "recents" | "all", fmt: ConvExportFormat, merged: boolean) {
+    try {
+      const threads = await listStoredChatThreads({
+        includeArchived: false,
+        ...(scope === "recents" ? { projectId: null } : {}),
+      });
+      const ids = [...new Set(threads.map((t) => t.id))];
+      if (ids.length === 0) { toast.info("No conversations to export."); return; }
+      const ts = new Date().toISOString().slice(0, 10);
+      const basename = scope === "all" ? `all-chats-${ts}` : `recents-${ts}`;
+      if (merged) {
+        await exportBulkConversationsMerged(ids, fmt, basename);
+      } else {
+        await exportBulkConversationsSeparate(ids, fmt, basename);
+      }
+    } catch {
+      toast.error("Export failed.");
+    }
+  }
   const [trainOpen, setTrainOpen] = useState(true);
   const [runsOpen, setRunsOpen] = useState(true);
 
@@ -644,6 +692,35 @@ export function AppSidebar() {
                 ))}
               </DropdownMenuSubContent>
             </DropdownMenuSub>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger>
+                <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon" />
+                <span>Export</span>
+              </DropdownMenuSubTrigger>
+              <DropdownMenuSubContent sideOffset={8} alignOffset={-4} className="unsloth-plus-menu w-52">
+                {[
+                  { label: "Raw JSONL", fn: exportConversationRawJsonl },
+                  { label: "CSV", fn: exportConversationCsv },
+                  { label: "ShareGPT JSONL", fn: exportConversationShareGPT },
+                ].map(({ label, fn }) => (
+                  <DropdownMenuItem
+                    key={label}
+                    onSelect={async () => {
+                      try {
+                        const ids = item.type === "single"
+                          ? [item.id]
+                          : (await listStoredChatThreads({ pairId: item.id })).map((t) => t.id);
+                        await Promise.all(ids.map((id) => fn(id)));
+                      } catch {
+                        toast.error("Export failed.");
+                      }
+                    }}
+                  >
+                    {label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
             <DropdownMenuItem
               variant="destructive"
               onSelect={() => setConfirmingDelete({ kind: "chat", item })}
@@ -659,6 +736,18 @@ export function AppSidebar() {
 
   return (
     <>
+    {/* Hidden file inputs for chat import */}
+    <input
+      ref={recentsImportInputRef}
+      type="file"
+      accept=".jsonl,.ndjson,.csv"
+      className="hidden"
+      onChange={(e) => {
+        const file = e.target.files?.[0];
+        if (file) void handleImportToRecents(file);
+        e.target.value = "";
+      }}
+    />
     <Sidebar
       collapsible="icon"
       variant="sidebar"
@@ -872,10 +961,68 @@ export function AppSidebar() {
           <Collapsible open={chatOpen} onOpenChange={setChatOpen} asChild>
             <SidebarGroup className="group-data-[collapsible=icon]:hidden px-0 py-0">
               <SidebarGroupLabel className={cn("sidebar-sticky-label sidebar-sticky-label-following", scrolled && "is-scrolled")} asChild>
-                <CollapsibleTrigger className="cursor-pointer flex w-full items-center gap-1 group/sb-collap">
-                  {t("shell.navigation.recents")}
-                  <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
-                </CollapsibleTrigger>
+                <div className="flex w-full items-center group/sb-collap">
+                  <CollapsibleTrigger className="cursor-pointer flex flex-1 items-center gap-1 min-w-0">
+                    {t("shell.navigation.recents")}
+                    <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
+                  </CollapsibleTrigger>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <button
+                        type="button"
+                        className="ml-auto flex items-center justify-center rounded-sm p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground focus:outline-none focus-visible:ring-0"
+                        title="Export recents"
+                      >
+                        <MoreHorizontalIcon className="size-3.5" />
+                      </button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent side="bottom" align="start" className="w-56">
+                      <DropdownMenuItem onSelect={() => recentsImportInputRef.current?.click()}>
+                        <HugeiconsIcon icon={Upload01Icon} strokeWidth={1.75} className="size-icon mr-1" />
+                        Import chats
+                      </DropdownMenuItem>
+                      <DropdownMenuSeparator />
+                      <DropdownMenuSub>
+                        <DropdownMenuSubTrigger>
+                          <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon mr-1" />
+                          Export Recents
+                        </DropdownMenuSubTrigger>
+                        <DropdownMenuSubContent avoidCollisions={false} className="unsloth-plus-menu w-52">
+                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                            <DropdownMenuItem key={`r-m-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, true)}>
+                              {label} — combined
+                            </DropdownMenuItem>
+                          ))}
+                          <DropdownMenuSeparator />
+                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                            <DropdownMenuItem key={`r-s-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, false)}>
+                              {label} — per chat
+                            </DropdownMenuItem>
+                          ))}
+                        </DropdownMenuSubContent>
+                      </DropdownMenuSub>
+                      <DropdownMenuSub>
+                        <DropdownMenuSubTrigger>
+                          <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon mr-1" />
+                          Export Recents + Projects
+                        </DropdownMenuSubTrigger>
+                        <DropdownMenuSubContent avoidCollisions={false} className="unsloth-plus-menu w-52">
+                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                            <DropdownMenuItem key={`a-m-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, true)}>
+                              {label} — combined
+                            </DropdownMenuItem>
+                          ))}
+                          <DropdownMenuSeparator />
+                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                            <DropdownMenuItem key={`a-s-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, false)}>
+                              {label} — per chat
+                            </DropdownMenuItem>
+                          ))}
+                        </DropdownMenuSubContent>
+                      </DropdownMenuSub>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </div>
               </SidebarGroupLabel>
               <CollapsibleContent>
                 <SidebarGroupContent className="px-2">
diff --git a/studio/frontend/src/components/assistant-ui/citation-utils.ts b/studio/frontend/src/components/assistant-ui/citation-utils.ts
new file mode 100644
index 0000000000..58000c038f
--- /dev/null
+++ b/studio/frontend/src/components/assistant-ui/citation-utils.ts
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+const RAG_SOURCES_SENTINEL = "__RAG_SOURCES__:";
+
+export interface Citation {
+  id: string;
+  filename: string;
+  page?: number | null;
+  score?: number | null;
+  text: string;
+  documentId?: string | null;
+  chunkId?: string | null;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+// null if absent so callers fall back to generic JSON shapes.
+function parseSentinelSources(result: unknown): Citation[] | null {
+  if (typeof result !== "string") return null;
+  const idx = result.indexOf(RAG_SOURCES_SENTINEL);
+  if (idx < 0) return null;
+  const payload = result.slice(idx + RAG_SOURCES_SENTINEL.length).trim();
+  let rows: unknown;
+  try {
+    rows = JSON.parse(payload);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(rows)) return [];
+  return rows.map((row, i) => {
+    const r = (row ?? {}) as Record<string, unknown>;
+    const documentId = typeof r.documentId === "string" ? r.documentId : null;
+    const chunkId = typeof r.chunkId === "string" ? r.chunkId : null;
+    const filename =
+      typeof r.filename === "string" ? r.filename : `Source ${i + 1}`;
+    return {
+      id: chunkId ?? `${filename}-${i}`,
+      filename,
+      page: asNumber(r.page),
+      score: asNumber(r.score),
+      text: typeof r.text === "string" ? r.text : "",
+      documentId,
+      chunkId,
+    };
+  });
+}
+
+export function parseCitations(result: unknown): Citation[] {
+  const sentinel = parseSentinelSources(result);
+  if (sentinel !== null) return sentinel;
+
+  let rows: unknown[] | null = null;
+  if (Array.isArray(result)) {
+    rows = result;
+  } else if (typeof result === "string") {
+    const trimmed = result.trim();
+    if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) rows = parsed;
+        else if (parsed && Array.isArray((parsed as { results?: unknown }).results)) {
+          rows = (parsed as { results: unknown[] }).results;
+        }
+      } catch {
+        rows = null;
+      }
+    }
+  } else if (result && Array.isArray((result as { results?: unknown }).results)) {
+    rows = (result as { results: unknown[] }).results;
+  }
+  if (!rows) return [];
+
+  const citations: Citation[] = [];
+  rows.forEach((row, i) => {
+    if (!row || typeof row !== "object") return;
+    const r = row as Record<string, unknown>;
+    const text =
+      typeof r.text === "string"
+        ? r.text
+        : typeof r.chunk === "string"
+          ? r.chunk
+          : typeof r.content === "string"
+            ? r.content
+            : "";
+    const filename =
+      typeof r.filename === "string"
+        ? r.filename
+        : typeof r.documentId === "string"
+          ? r.documentId
+          : `Source ${i + 1}`;
+    const chunkId =
+      typeof r.chunkId === "string" ? r.chunkId : `${filename}-${i}`;
+    citations.push({
+      id: chunkId,
+      filename,
+      page: asNumber(r.page),
+      score: asNumber(r.score),
+      text,
+    });
+  });
+  return citations;
+}
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
index 516aa409fc..4fd86ad789 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
@@ -35,6 +35,7 @@ import {
   useInfiniteScroll,
   useRecommendedModelVram,
 } from "@/hooks";
+import { extractParamLabel } from "@/lib/model-size";
 import { cn, formatCompact } from "@/lib/utils";
 import type { VramFitStatus } from "@/lib/vram";
 import { checkVramFit, estimateLoadingVram } from "@/lib/vram";
@@ -120,7 +121,7 @@ function ModelRow({
   tooltipText,
 }: {
   label: string;
-  meta?: string;
+  meta?: string | null;
   selected?: boolean;
   onClick: () => void;
   vramStatus?: VramFitStatus | null;
@@ -458,14 +459,6 @@ function isGgufRepo(id: string, hintedIsGguf?: boolean): boolean {
   return Boolean(hintedIsGguf) || hasGgufSuffix(id);
 }
 
-/** Extract param count label from model name (e.g. "Qwen3-0.6B" -> "0.6B"). */
-function extractParamLabel(id: string): string | undefined {
-  const name = id.split("/").pop() ?? id;
-  // Match patterns like "0.6B", "1B", "4B", "3.5B", "70B", "1.5B" etc.
-  const match = name.match(/(?:^|[-_])(\d+(?:\.\d+)?)[Bb](?:[-_]|$)/);
-  return match ? `${match[1]}B` : undefined;
-}
-
 // Module-level caches so re-mounting the popover shows results instantly
 let _cachedGgufCache: CachedGgufRepo[] = [];
 let _cachedModelsCache: CachedModelRepo[] = [];
diff --git a/studio/frontend/src/components/assistant-ui/rag-sources.tsx b/studio/frontend/src/components/assistant-ui/rag-sources.tsx
new file mode 100644
index 0000000000..ab7a572e52
--- /dev/null
+++ b/studio/frontend/src/components/assistant-ui/rag-sources.tsx
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { useMessage } from "@assistant-ui/react";
+import type { FC } from "react";
+
+import { type Citation, parseCitations } from "./citation-utils";
+import { CitationBadge } from "./tool-ui-knowledge-base";
+
+export const RagSourcesGroup: FC = () => {
+  const message = useMessage();
+
+  const all: Citation[] = [];
+  for (const part of message.content ?? []) {
+    if (part.type === "tool-call" && part.toolName === "search_knowledge_base") {
+      all.push(...parseCitations(part.result));
+    }
+  }
+
+  // Map updates keep first-seen order, so dedup to best-scoring chunk per doc.
+  const byDoc = new Map<string, Citation>();
+  for (const c of all) {
+    const key = c.documentId ?? c.filename;
+    const prev = byDoc.get(key);
+    if (!prev || (c.score ?? -Infinity) > (prev.score ?? -Infinity)) {
+      byDoc.set(key, c);
+    }
+  }
+  const sources = Array.from(byDoc.values());
+  if (sources.length === 0) return null;
+
+  return (
+    <div className="mt-2 mb-3">
+      <div className="mb-1 text-xs font-medium text-muted-foreground">
+        Document Sources
+      </div>
+      <div className="flex flex-wrap gap-1.5">
+        {sources.map((citation, i) => (
+          <CitationBadge key={citation.id} citation={citation} index={i} />
+        ))}
+      </div>
+    </div>
+  );
+};
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 302c107e26..b6fc554423 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -13,6 +13,7 @@ import { downloadImagePart } from "@/components/assistant-ui/image";
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
 import { MessageTiming } from "@/components/assistant-ui/message-timing";
 import { Reasoning, ReasoningGroup } from "@/components/assistant-ui/reasoning";
+import { RagSourcesGroup } from "@/components/assistant-ui/rag-sources";
 import { Sources, SourcesGroup } from "@/components/assistant-ui/sources";
 import {
   thinkEffortAriaLabel,
@@ -22,6 +23,7 @@ import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
 import { ToolGroup } from "@/components/assistant-ui/tool-group";
 import { CodeExecutionToolUI } from "@/components/assistant-ui/tool-ui-code-execution";
 import { ImageGenerationToolUI } from "@/components/assistant-ui/tool-ui-image-generation";
+import { KnowledgeBaseToolUI } from "@/components/assistant-ui/tool-ui-knowledge-base";
 import { RenderHtmlToolUI } from "@/components/assistant-ui/tool-ui-render-html";
 import { PythonToolUI } from "@/components/assistant-ui/tool-ui-python";
 import { TerminalToolUI } from "@/components/assistant-ui/tool-ui-terminal";
@@ -34,6 +36,7 @@ import {
   useScrollThreadToBottom,
 } from "@/components/assistant-ui/use-intent-aware-autoscroll";
 import { Button } from "@/components/ui/button";
+import { Spinner } from "@/components/ui/spinner";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -46,14 +49,28 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { sentAudioNames } from "@/features/chat/api/chat-adapter";
+import {
+  PromptStorageDialog,
+  exportConversationShareGPT,
+  exportConversationRawJsonl,
+  exportConversationCsv,
+} from "@/features/chat/prompt-storage/prompt-storage-dialog";
+import {
+  listPromptEntries,
+  type PromptEntry,
+} from "@/features/chat/api/prompts-api";
 import { useChatProjects } from "@/features/chat/hooks/use-chat-projects";
 import { NewProjectDialog } from "@/features/chat/components/new-project-dialog";
 import { parseExternalModelId } from "@/features/chat/external-providers";
 import { McpComposerButton } from "@/features/chat/mcp-composer-button";
 import { getExternalReasoningCapabilities } from "@/features/chat/provider-capabilities";
+import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
 import { useExternalProvidersStore } from "@/features/chat/stores/external-providers-store";
 import { deleteThreadMessage } from "@/features/chat/utils/delete-thread-message";
+import { ThreadDocumentsBar } from "@/features/rag/components/thread-documents-bar";
+import { KnowledgeBaseComposerButton } from "@/features/rag/components/knowledge-base-composer-button";
+import { DocumentPreviewMount } from "@/features/rag/components/document-preview-mount";
 import { useUserProfileStore } from "@/features/profile/stores/user-profile-store";
 import { applyQwenThinkingParams } from "@/features/chat/utils/qwen-params";
 import { isTauri } from "@/lib/api-base";
@@ -77,11 +94,13 @@ import {
 import { flushResourcesSync } from "@assistant-ui/tap";
 import {
   AttachmentIcon,
+  Bookmark02Icon,
   CodeIcon,
   Copy01Icon,
   Delete02Icon,
   Download01Icon,
   Edit03Icon,
+  FileDatabaseIcon,
   Folder01Icon,
   FolderAddIcon,
   Image03Icon,
@@ -94,7 +113,6 @@ import { useNavigate } from "@tanstack/react-router";
 import {
   ArrowDownIcon,
   ArrowUpIcon,
-  CheckIcon,
   ChevronLeftIcon,
   ChevronRightIcon,
   Columns2Icon,
@@ -128,6 +146,83 @@ import {
 // can show its "Drop files here" affordance.
 const PageDragContext = createContext(false);
 
+// Single-chat prompt queue. State lives at module level so it survives the
+// Composer remount when the first queued message creates a new thread, and
+// detection subscribes to the store's runningByThreadId rather than
+// aui.thread() (unbound on the welcome screen).
+
+import { create as _createZustand } from "zustand";
+
+// Module-level Zustand so ComposerRightControls re-renders across Composer mounts.
+interface _QueueUIState { isRunning: boolean; current: number; total: number; }
+const _useQueueUI = _createZustand<_QueueUIState>(() => ({
+  isRunning: false, current: 0, total: 0,
+}));
+
+let _qItems: string[] = [];
+let _qIndex = 0;
+let _qIsRunning = false;
+let _qPrevStoreRunning = false;
+let _qStoreUnsub: (() => void) | null = null;
+
+// Points to the current Composer's aui (updated every render), so it stays valid
+// after a remount.
+let _qGetAui: () => ReturnType<typeof useAui> = () => {
+  throw new Error("aui not initialised");
+};
+
+function _qStopSubscription() {
+  if (_qStoreUnsub) { _qStoreUnsub(); _qStoreUnsub = null; }
+  _qPrevStoreRunning = false;
+}
+
+function _qAdvance() {
+  const nextIndex = _qIndex + 1;
+  if (nextIndex >= _qItems.length) {
+    _qIsRunning = false;
+    _qItems = [];
+    _qIndex = 0;
+    _qStopSubscription();
+    _useQueueUI.setState({ isRunning: false, current: 0, total: 0 });
+    toast.success("Prompt queue complete");
+    return;
+  }
+  _qIndex = nextIndex;
+  _useQueueUI.setState({ current: nextIndex + 1, total: _qItems.length });
+  const next = _qItems[nextIndex];
+  toast(`Prompt ${nextIndex + 1} / ${_qItems.length}`, {
+    description: next.length > 80 ? next.slice(0, 80) + "…" : next,
+  });
+  _qPrevStoreRunning = false; // catch the next run
+  setTimeout(() => {
+    _qGetAui().thread().append({
+      role: "user",
+      content: [{ type: "text", text: next }],
+      createdAt: new Date(),
+    } as never);
+  }, 100);
+}
+
+function _qStartSubscription() {
+  _qStopSubscription();
+  // runningByThreadId tracks the actual thread (not aui.thread()), so detection
+  // survives navigation.
+  _qStoreUnsub = useChatRuntimeStore.subscribe((state) => {
+    if (!_qIsRunning) { _qStopSubscription(); return; }
+    const isRunning = Object.keys(state.runningByThreadId).length > 0;
+    const wasRunning = _qPrevStoreRunning;
+    _qPrevStoreRunning = isRunning;
+    if (wasRunning && !isRunning) {
+      _qAdvance();
+    }
+  });
+}
+
+interface _QueueCallbacks { startQueue: (items: string[]) => void; stopQueue: () => void; }
+const PromptQueueContext = createContext<_QueueCallbacks>({
+  startQueue: () => {}, stopQueue: () => {},
+});
+
 // Gap (px) between last message and floating composer; bottom spacer tracks
 // composer height plus this gap so chat can scroll fully above the composer.
 const COMPOSER_SCROLL_GAP_PX = 24;
@@ -443,6 +538,8 @@ export const Thread: FC<{
           )}
         </IntentAwareScrollProvider>
       </ThreadPrimitive.Root>
+      {/* Document preview, opened by citation badges. */}
+      <DocumentPreviewMount />
       </PageDragContext.Provider>
     </GeneratedImageOverlayProvider>
   );
@@ -778,10 +875,13 @@ const Composer: FC<{
   );
   const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
   const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
+  const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
+  const ragToolAvailable = useRagToolAvailable();
   // More than 4 pills: collapse to icons only. Search and Code always show;
   // Images, Canvas and MCP are conditional.
   const pillsCompact =
     2 +
+      (ragEnabled && ragToolAvailable ? 1 : 0) +
       (supportsBuiltinImageGeneration ? 1 : 0) +
       (artifactsEnabled ? 1 : 0) +
       (mcpEnabledForChat ? 1 : 0) >
@@ -847,6 +947,7 @@ const Composer: FC<{
     toolsEnabled ||
     codeToolsEnabled ||
     imageToolsEnabled ||
+    ragEnabled ||
     artifactsEnabled ||
     mcpEnabledForChat;
   // react-textarea-autosize re-measures only on value change or window resize,
@@ -890,18 +991,88 @@ const Composer: FC<{
   // Docked composer opens upward; the welcome composer opens downward by
   // default and only flips up via collision detection when it won't fit.
   const effectiveMenuSide = menuSide ?? "bottom";
+
+  // While this thread's docs index, hold the send and fire it once they finish so
+  // retrieval covers all of them.
+  const [indexingActive, setIndexingActive] = useState(false);
+  const [pendingSend, setPendingSend] = useState(false);
+  const pendingSendRef = useRef(false);
+  const waitToastRef = useRef<string | number | null>(null);
+
+  const dismissWaitToast = useCallback(() => {
+    if (waitToastRef.current !== null) {
+      toast.dismiss(waitToastRef.current);
+      waitToastRef.current = null;
+    }
+  }, []);
+
+  const cancelQueuedSend = useCallback(() => {
+    pendingSendRef.current = false;
+    setPendingSend(false);
+    dismissWaitToast();
+  }, [dismissWaitToast]);
+
+  const enqueueSend = useCallback(() => {
+    if (pendingSendRef.current) return;
+    pendingSendRef.current = true;
+    setPendingSend(true);
+    waitToastRef.current = toast("Waiting for documents to finish indexing", {
+      description:
+        "Your message will send automatically once indexing finishes.",
+      duration: Infinity,
+      cancel: { label: "Cancel", onClick: cancelQueuedSend },
+    });
+  }, [cancelQueuedSend]);
+
   const shouldBlockSend = useCallback(
     () =>
       !hasSendableContent || isComposingRef.current || hasPendingAttachments,
     [hasPendingAttachments, hasSendableContent, isComposingRef],
   );
 
-  const handleSubmit = useCallback(
-    (event: Parameters<NonNullable<ComponentProps<"form">["onSubmit"]>>[0]) => {
+  // Gate for both form submit and the Send button. Returns true when it handled
+  // the event (blocked or queued) so callers stop.
+  const interceptSend = useCallback(
+    (event: { preventDefault: () => void }) => {
       if (disabled || shouldBlockSend()) {
         event.preventDefault();
-        return;
+        return true;
       }
+      if (indexingActive && !overlay) {
+        event.preventDefault();
+        enqueueSend();
+        return true;
+      }
+      return false;
+    },
+    [disabled, shouldBlockSend, indexingActive, overlay, enqueueSend],
+  );
+
+  // Fire the parked send once indexing clears, unless the user emptied the
+  // composer while waiting (then drop it quietly).
+  useEffect(() => {
+    if (!pendingSend || indexingActive) return;
+    const { text, attachments } = aui.composer().getState();
+    pendingSendRef.current = false;
+    setPendingSend(false);
+    dismissWaitToast();
+    if (text.trim().length > 0 || attachments.length > 0) {
+      aui.composer().send();
+    }
+  }, [pendingSend, indexingActive, aui, dismissWaitToast]);
+
+  // Drop any queued send + toast on unmount (e.g. thread switch).
+  useEffect(
+    () => () => {
+      pendingSendRef.current = false;
+      if (waitToastRef.current !== null) toast.dismiss(waitToastRef.current);
+    },
+    [],
+  );
+
+  const handleSubmit = useCallback(
+    (event: Parameters<NonNullable<ComponentProps<"form">["onSubmit"]>>[0]) => {
+      if (interceptSend(event)) return;
 
       if (overlay) {
         const trimmed = composerText.trim();
@@ -949,19 +1120,58 @@ const Composer: FC<{
       aui,
       closeOverlay,
       composerText,
-      disabled,
+      interceptSend,
       overlay,
       referenceThreadId,
       setImageToolsEnabled,
       setPendingImageEditReference,
-      shouldBlockSend,
     ],
   );
 
+  // Update the getter every render so the queue always calls the current
+  // Composer's aui (post-remount).
+  _qGetAui = () => aui;
+
+  const stopQueue = useCallback(() => {
+    _qIsRunning = false;
+    _qStopSubscription();
+    _useQueueUI.setState({ isRunning: false, current: 0, total: 0 });
+    _qItems = [];
+    _qIndex = 0;
+    try { _qGetAui().thread().cancelRun(); } catch {}
+  }, []);
+
+  const startQueue = useCallback((items: string[]) => {
+    const filtered = items.filter((p) => p.trim());
+    if (!filtered.length) return;
+    _qItems = filtered;
+    _qIndex = 0;
+    _qIsRunning = true;
+    _useQueueUI.setState({ isRunning: true, current: 1, total: filtered.length });
+    toast(`Prompt 1 / ${filtered.length}`, {
+      description: filtered[0].length > 80 ? filtered[0].slice(0, 80) + "…" : filtered[0],
+    });
+    // Subscribe BEFORE appending so we don't miss a very fast completion.
+    _qStartSubscription();
+    setTimeout(() => {
+      _qGetAui().thread().append({
+        role: "user",
+        content: [{ type: "text", text: filtered[0] }],
+        createdAt: new Date(),
+      } as never);
+    }, 50);
+  }, []);
+
+  const queueContextValue: _QueueCallbacks = { startQueue, stopQueue };
+
   const composerContent = (
     <>
       <ComposerAttachments />
       <PendingAudioChip />
+      <ThreadDocumentsBar
+        threadId={referenceThreadId}
+        onIndexingChange={setIndexingActive}
+      />
       <ToolStatusDisplay />
       <div
         className="unsloth-composer-line"
@@ -977,6 +1187,7 @@ const Composer: FC<{
               <WebSearchToggle />
               <CodeToolsToggle />
               <ImagesToggle />
+              <KnowledgeBaseComposerButton side={effectiveMenuSide} />
               {artifactsEnabled ? <ArtifactsToggle /> : null}
               {mcpEnabledForChat ? (
                 <McpComposerButton side={effectiveMenuSide} />
@@ -1007,7 +1218,8 @@ const Composer: FC<{
             isComposing ||
             hasPendingAttachments
           }
-          shouldBlockSend={shouldBlockSend}
+          onSendClick={interceptSend}
+          pendingSend={pendingSend}
           menuSide={effectiveMenuSide}
         />
       </div>
@@ -1015,6 +1227,7 @@ const Composer: FC<{
   );
 
   return (
+    <PromptQueueContext.Provider value={queueContextValue}>
     <ComposerPrimitive.Root
       className="aui-composer-root relative flex w-full flex-col"
       aria-disabled={disabled}
@@ -1050,6 +1263,7 @@ const Composer: FC<{
         </ComposerPrimitive.AttachmentDropzone>
       )}
     </ComposerPrimitive.Root>
+    </PromptQueueContext.Provider>
   );
 };
 
@@ -1409,7 +1623,7 @@ const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
           side={side}
           align="end"
           avoidCollisions={true}
-          className="unsloth-plus-menu unsloth-thinking-menu min-w-0 w-[160px]"
+          className="unsloth-plus-menu unsloth-thinking-menu min-w-0 w-[176px]"
         >
           {isEffort ? (
             <>
@@ -1422,7 +1636,9 @@ const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
                     setPreserveThinking(false);
                   }}
                 >
-                  <CheckIcon
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                     className={cn(
                       "unsloth-tick size-4",
                       effectiveReasoningVisualEnabled && "opacity-0",
@@ -1447,7 +1663,9 @@ const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
                       }
                     }}
                   >
-                    <CheckIcon
+                    <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                       className={cn(
                         "unsloth-tick size-4",
                         !(
@@ -1475,7 +1693,9 @@ const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
                   }
                 }}
               >
-                <CheckIcon
+                <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                   className={cn(
                     "unsloth-tick size-4",
                     !effectiveReasoningEnabled && "opacity-0",
@@ -1499,7 +1719,9 @@ const ReasoningToggle: FC<{ side?: "top" | "bottom" }> = ({
                 }
               }}
             >
-              <CheckIcon
+              <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                 className={cn(
                   "unsloth-tick size-4",
                   !preserveThinking && "opacity-0",
@@ -1793,6 +2015,10 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const setMcpEnabledForChat = useChatRuntimeStore(
     (s) => s.setMcpEnabledForChat,
   );
+  const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
+  const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
+  // Shared gate so the menu row agrees with the RAG pill and Add Files bar.
+  const ragAvailable = useRagToolAvailable();
   // Capability gating mirrors the visible pills so menu and pills agree on
   // what a loaded model supports (a tool the backend drops must not look on).
   const modelLoaded = useChatRuntimeStore(
@@ -1857,10 +2083,42 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   }, [navigate]);
 
   const [newProjectOpen, setNewProjectOpen] = useState(false);
+  const [promptStorageOpen, setPromptStorageOpen] = useState(false);
+  const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
+  const aui = useAui();
+  // Disable Export chat until the thread has content.
+  const messageCount = useAuiState(({ thread }) => thread.messages.length);
+  const { startQueue } = useContext(PromptQueueContext);
+
+  const [recentPrompts, setRecentPrompts] = useState<PromptEntry[]>([]);
+  const refreshRecentPrompts = useCallback(async () => {
+    try {
+      const rows = await listPromptEntries();
+      setRecentPrompts(
+        [...rows].sort((a, b) => b.updatedAt - a.updatedAt).slice(0, 3),
+      );
+    } catch {
+    }
+  }, []);
 
   return (
     <>
-    <DropdownMenu>
+    <PromptStorageDialog
+      open={promptStorageOpen}
+      onOpenChange={setPromptStorageOpen}
+      onUse={(text) => {
+        aui.composer().setText(text);
+      }}
+      onRunList={(items) => {
+        setPromptStorageOpen(false);
+        startQueue(items);
+      }}
+    />
+    <DropdownMenu
+      onOpenChange={(open) => {
+        if (open) void refreshRecentPrompts();
+      }}
+    >
       <DropdownMenuTrigger asChild={true}>
         <button
           type="button"
@@ -1906,7 +2164,11 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
           <GlobeIcon />
           Web search
           {toolsEnabled && !searchDisabled ? (
-            <CheckIcon className="ml-auto" />
+            <HugeiconsIcon
+              icon={Tick02Icon}
+              strokeWidth={2}
+              className="ml-auto"
+            />
           ) : null}
         </DropdownMenuItem>
         <DropdownMenuItem
@@ -1925,7 +2187,11 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
           />
           Code
           {codeToolsEnabled && !codeDisabled ? (
-            <CheckIcon className="ml-auto" />
+            <HugeiconsIcon
+              icon={Tick02Icon}
+              strokeWidth={2}
+              className="ml-auto"
+            />
           ) : null}
         </DropdownMenuItem>
         {supportsBuiltinImageGeneration && (
@@ -1941,18 +2207,31 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
             <HugeiconsIcon icon={Image03Icon} strokeWidth={2} />
             Images
             {imageToolsEnabled && !imageDisabled ? (
-              <CheckIcon className="ml-auto" />
+              <HugeiconsIcon
+                icon={Tick02Icon}
+                strokeWidth={2}
+                className="ml-auto"
+              />
             ) : null}
           </DropdownMenuItem>
         )}
         <DropdownMenuSeparator />
         <DropdownMenuItem
-          className={artifactsEnabled ? "text-primary font-medium" : undefined}
-          onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+          disabled={!ragAvailable}
+          className={
+            ragEnabled && ragAvailable ? "text-primary font-medium" : undefined
+          }
+          onSelect={() => setRagEnabled(!ragEnabled)}
         >
-          <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
-          Canvas
-          {artifactsEnabled ? <CheckIcon className="ml-auto" /> : null}
+          <HugeiconsIcon icon={FileDatabaseIcon} strokeWidth={2} />
+          RAG
+          {ragEnabled && ragAvailable ? (
+            <HugeiconsIcon
+              icon={Tick02Icon}
+              strokeWidth={2}
+              className="ml-auto"
+            />
+          ) : null}
         </DropdownMenuItem>
         <DropdownMenuItem
           disabled={mcpDisabled}
@@ -1966,14 +2245,105 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
           <HugeiconsIcon icon={McpServerIcon} strokeWidth={2} />
           MCP
           {mcpEnabledForChat && !mcpDisabled ? (
-            <CheckIcon className="ml-auto" />
+            <HugeiconsIcon
+              icon={Tick02Icon}
+              strokeWidth={2}
+              className="ml-auto"
+            />
           ) : null}
         </DropdownMenuItem>
-        {/* RAG hidden temporarily */}
+        {/* Top-level so it stays one click away (not buried in More). */}
         <DropdownMenuItem onSelect={() => startCompare()}>
           <Columns2Icon />
           Compare chat
         </DropdownMenuItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>
+            <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
+            Saved prompts
+          </DropdownMenuSubTrigger>
+          <DropdownMenuSubContent className="unsloth-plus-menu w-[176px]">
+            {recentPrompts.map((p) => (
+              <DropdownMenuItem
+                key={p.id}
+                onSelect={() => aui.composer().setText(p.text)}
+              >
+                <span className="truncate">{p.name}</span>
+              </DropdownMenuItem>
+            ))}
+            {recentPrompts.length > 0 ? <DropdownMenuSeparator /> : null}
+            <DropdownMenuItem onSelect={() => setPromptStorageOpen(true)}>
+              All saved prompts…
+            </DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        {/* Top-level: a third-level submenu collision-flips at narrow widths
+            and is awkward to reach. */}
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger disabled={!activeThreadId || messageCount === 0}>
+            <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
+            Export chat
+          </DropdownMenuSubTrigger>
+          <DropdownMenuSubContent
+            collisionPadding={16}
+            className="unsloth-plus-menu w-[176px]"
+          >
+            <DropdownMenuItem
+              onSelect={() => {
+                if (!activeThreadId) return;
+                exportConversationRawJsonl(activeThreadId).catch(() =>
+                  toast.error("Export failed."),
+                );
+              }}
+            >
+              Raw JSONL
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onSelect={() => {
+                if (!activeThreadId) return;
+                exportConversationCsv(activeThreadId).catch(() =>
+                  toast.error("Export failed."),
+                );
+              }}
+            >
+              CSV
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onSelect={() => {
+                if (!activeThreadId) return;
+                exportConversationShareGPT(activeThreadId).catch(() =>
+                  toast.error("Export failed."),
+                );
+              }}
+            >
+              ShareGPT JSONL
+            </DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>
+            <MoreHorizontalIcon className="size-4" />
+            More
+          </DropdownMenuSubTrigger>
+          <DropdownMenuSubContent className="w-[200px]">
+            <DropdownMenuItem
+              className={
+                artifactsEnabled ? "text-primary font-medium" : undefined
+              }
+              onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+            >
+              <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
+              Canvas
+              {artifactsEnabled ? (
+                <HugeiconsIcon
+                  icon={Tick02Icon}
+                  strokeWidth={2}
+                  className="ml-auto"
+                />
+              ) : null}
+            </DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
         <DropdownMenuSeparator />
         <DropdownMenuSub>
           <DropdownMenuSubTrigger>
@@ -2015,9 +2385,14 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
 
 const ComposerRightControls: FC<{
   disabled?: boolean;
-  shouldBlockSend?: () => boolean;
+  onSendClick?: (event: { preventDefault: () => void }) => void;
+  pendingSend?: boolean;
   menuSide?: "top" | "bottom";
-}> = ({ disabled, shouldBlockSend, menuSide }) => {
+}> = ({ disabled, onSendClick, pendingSend, menuSide }) => {
+  const isQueueRunning = _useQueueUI((s) => s.isRunning);
+  const queueCurrent = _useQueueUI((s) => s.current);
+  const queueTotal = _useQueueUI((s) => s.total);
+  const { stopQueue } = useContext(PromptQueueContext);
   return (
     <div className="aui-composer-action-wrapper flex shrink-0 items-center gap-1.5">
       <ReasoningToggle side={menuSide} />
@@ -2045,40 +2420,58 @@ const ComposerRightControls: FC<{
           </TooltipIconButton>
         </ComposerPrimitive.StopDictation>
       </ComposerPrimitive.If>
-      <AuiIf condition={({ thread }) => !thread.isRunning}>
-        <ComposerPrimitive.Send asChild={true}>
-          <TooltipIconButton
-            tooltip="Send message"
-            side="bottom"
-            type="submit"
-            variant="default"
-            size="icon"
-            disabled={disabled}
-            onClick={(event) => {
-              if (shouldBlockSend?.()) {
-                event.preventDefault();
-              }
-            }}
-            className="aui-composer-send ml-1.5 size-8 rounded-full"
-            aria-label="Send message"
-          >
-            <ArrowUpIcon className="aui-composer-send-icon size-[21px] stroke-2" />
-          </TooltipIconButton>
-        </ComposerPrimitive.Send>
-      </AuiIf>
-      <AuiIf condition={({ thread }) => thread.isRunning}>
-        <ComposerPrimitive.Cancel asChild={true}>
-          <Button
-            type="button"
-            variant="default"
-            size="icon"
-            className="aui-composer-cancel ml-1.5 size-8 rounded-full"
-            aria-label="Stop generating"
-          >
-            <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
-          </Button>
-        </ComposerPrimitive.Cancel>
-      </AuiIf>
+      {isQueueRunning ? (
+        <button
+          type="button"
+          onClick={stopQueue}
+          aria-label="Stop prompt queue"
+          className="ml-1.5 flex items-center gap-1.5 rounded-full border border-border/60 bg-muted/60 px-2.5 py-1 text-xs font-semibold text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        >
+          <SquareIcon className="size-2.5 shrink-0 fill-current" />
+          <span className="tabular-nums">
+            Stop queue {queueCurrent}/{queueTotal}
+          </span>
+        </button>
+      ) : (
+        <>
+          <AuiIf condition={({ thread }) => !thread.isRunning}>
+            <ComposerPrimitive.Send asChild={true}>
+              <TooltipIconButton
+                tooltip={pendingSend ? "Waiting for documents…" : "Send message"}
+                side="bottom"
+                type="submit"
+                variant="default"
+                size="icon"
+                // Stay clickable while docs index so a click can queue the send;
+                // disabled only once a send is parked.
+                disabled={disabled || pendingSend}
+                onClick={(event) => onSendClick?.(event)}
+                className="aui-composer-send ml-1.5 size-8 rounded-full"
+                aria-label="Send message"
+              >
+                {pendingSend ? (
+                  <Spinner className="size-[18px]" />
+                ) : (
+                  <ArrowUpIcon className="aui-composer-send-icon size-[21px] stroke-2" />
+                )}
+              </TooltipIconButton>
+            </ComposerPrimitive.Send>
+          </AuiIf>
+          <AuiIf condition={({ thread }) => thread.isRunning}>
+            <ComposerPrimitive.Cancel asChild={true}>
+              <Button
+                type="button"
+                variant="default"
+                size="icon"
+                className="aui-composer-cancel ml-1.5 size-8 rounded-full"
+                aria-label="Stop generating"
+              >
+                <SquareIcon className="aui-composer-cancel-icon size-3 fill-current" />
+              </Button>
+            </ComposerPrimitive.Cancel>
+          </AuiIf>
+        </>
+      )}
     </div>
   );
 };
@@ -2141,6 +2534,7 @@ const AssistantMessage: FC = () => {
             tools: {
               by_name: {
                 web_search: WebSearchToolUI,
+                search_knowledge_base: KnowledgeBaseToolUI,
                 python: PythonToolUI,
                 terminal: TerminalToolUI,
                 code_execution: CodeExecutionToolUI,
@@ -2152,6 +2546,7 @@ const AssistantMessage: FC = () => {
           }}
         />
         <SourcesGroup />
+        <RagSourcesGroup />
         <MessageError />
       </div>
 
diff --git a/studio/frontend/src/components/assistant-ui/tool-ui-knowledge-base.tsx b/studio/frontend/src/components/assistant-ui/tool-ui-knowledge-base.tsx
new file mode 100644
index 0000000000..09d6af2d64
--- /dev/null
+++ b/studio/frontend/src/components/assistant-ui/tool-ui-knowledge-base.tsx
@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import {
+  type ToolCallMessagePartComponent,
+  useAuiState,
+} from "@assistant-ui/react";
+import { FileTextIcon, LibraryBigIcon, LoaderIcon } from "lucide-react";
+import { memo, useEffect, useMemo, useState } from "react";
+import { Badge } from "./badge";
+import {
+  ToolFallbackContent,
+  ToolFallbackRoot,
+  ToolFallbackTrigger,
+} from "./tool-fallback";
+import { useDocumentPreviewStore } from "@/features/rag/components/preview-store";
+
+import { type Citation, parseCitations } from "./citation-utils";
+
+export function CitationBadge({
+  citation,
+  index,
+}: {
+  citation: Citation;
+  index: number;
+}) {
+  const openPreview = useDocumentPreviewStore((s) => s.openPreview);
+  const clickable = Boolean(citation.documentId);
+  const label =
+    citation.page != null
+      ? `${citation.filename} · p.${citation.page}`
+      : citation.filename;
+
+  const open = () => {
+    if (!citation.documentId) return;
+    openPreview({
+      documentId: citation.documentId,
+      chunkId: citation.chunkId,
+      filename: citation.filename,
+      page: citation.page,
+    });
+  };
+
+  const badge = (
+    <Badge
+      variant="outline"
+      size="sm"
+      className={`rounded-full inline-flex items-center gap-1.5 max-w-[15rem] ${
+        clickable
+          ? "cursor-pointer hover:bg-accent hover:text-accent-foreground transition-colors"
+          : "cursor-default"
+      }`}
+    >
+      <span className="tabular-nums text-muted-foreground">{index + 1}</span>
+      <FileTextIcon className="size-3 shrink-0" />
+      <span className="truncate">{label}</span>
+    </Badge>
+  );
+
+  return clickable ? (
+    <button type="button" onClick={open} className="inline-block">
+      {badge}
+    </button>
+  ) : (
+    <span className="inline-block">{badge}</span>
+  );
+}
+
+const KnowledgeBaseToolUIImpl: ToolCallMessagePartComponent = ({
+  args,
+  result,
+  status,
+}) => {
+  const query = (args as { query?: string })?.query ?? "";
+  const isRunning = status?.type === "running";
+  const citations = useMemo(() => parseCitations(result), [result]);
+  // Citations render in RagSourcesGroup; this block keeps a one-line summary.
+  const docCount = useMemo(
+    () => new Set(citations.map((c) => c.documentId ?? c.filename)).size,
+    [citations],
+  );
+
+  const hasText = useAuiState(({ message }) =>
+    message.content.some(
+      (p) =>
+        p.type === "text" &&
+        "text" in p &&
+        (p as { text: string }).text.length > 0,
+    ),
+  );
+  const [open, setOpen] = useState(isRunning);
+  useEffect(() => {
+    if (isRunning) setOpen(true);
+    else if (hasText) setOpen(false);
+  }, [isRunning, hasText]);
+
+  return (
+    <ToolFallbackRoot open={open} onOpenChange={setOpen}>
+      <ToolFallbackTrigger
+        toolName={query ? `Searched documents for "${query}"` : "Knowledge search"}
+        status={status}
+        icon={LibraryBigIcon}
+      />
+      <ToolFallbackContent>
+        {isRunning ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <LoaderIcon className="size-3.5 animate-spin" />
+            <span>
+              {query ? (
+                <>Searching documents for &ldquo;{query}&rdquo;&hellip;</>
+              ) : (
+                <>Searching documents&hellip;</>
+              )}
+            </span>
+          </div>
+        ) : citations.length > 0 ? (
+          <div className="text-sm text-muted-foreground">
+            Retrieved {citations.length} passage
+            {citations.length === 1 ? "" : "s"} from {docCount} document
+            {docCount === 1 ? "" : "s"}. See Document Sources below.
+          </div>
+        ) : result ? (
+          <pre className="max-h-40 overflow-auto whitespace-pre-wrap break-words rounded bg-muted/50 p-2 text-xs">
+            {typeof result === "string"
+              ? result
+              : JSON.stringify(result, null, 2)}
+          </pre>
+        ) : (
+          <div className="text-sm text-muted-foreground">No matching passages.</div>
+        )}
+      </ToolFallbackContent>
+    </ToolFallbackRoot>
+  );
+};
+
+export const KnowledgeBaseToolUI = memo(
+  KnowledgeBaseToolUIImpl,
+) as unknown as ToolCallMessagePartComponent;
+KnowledgeBaseToolUI.displayName = "KnowledgeBaseToolUI";
diff --git a/studio/frontend/src/components/ui/dropdown-menu.tsx b/studio/frontend/src/components/ui/dropdown-menu.tsx
index 0f67194ee3..0ce4fd87c8 100644
--- a/studio/frontend/src/components/ui/dropdown-menu.tsx
+++ b/studio/frontend/src/components/ui/dropdown-menu.tsx
@@ -221,7 +221,7 @@ function DropdownMenuSubTrigger({
       data-slot="dropdown-menu-sub-trigger"
       data-inset={inset}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-pointer items-center outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index 91a9bffa36..f0d229b412 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -3,6 +3,7 @@
 
 import { getAuthToken } from "@/features/auth";
 import { apiUrl } from "@/lib/api-base";
+import { parseParamCountB } from "@/lib/model-size";
 import { toast } from "@/lib/toast";
 import type { MessageTiming, ToolCallMessagePart } from "@assistant-ui/core";
 import type { ChatModelAdapter } from "@assistant-ui/react";
@@ -33,6 +34,7 @@ import {
 } from "../provider-capabilities";
 import {
   type PendingImageEditReference,
+  type RagAutoInject,
   resolveToolsEnabledOnLoad,
   useChatRuntimeStore,
 } from "../stores/chat-runtime-store";
@@ -74,6 +76,18 @@ import {
   isProviderKeyRotationError,
 } from "./providers-api";
 
+// Small models (<=9B) answer from memory instead of calling search, so "auto"
+// forces retrieval for them and leaves it to larger ones.
+const AUTOINJECT_AUTO_MAX_SIZE_B = 9;
+
+function resolveAutoInject(mode: RagAutoInject, checkpoint: string): boolean {
+  if (mode === "on") return true;
+  if (mode === "off") return false;
+  const size = parseParamCountB(checkpoint);
+  // Unknown size -> enable.
+  return size === null || size <= AUTOINJECT_AUTO_MAX_SIZE_B;
+}
+
 /** Server-side usage data from llama-server (via stream_options.include_usage). */
 interface ServerUsage {
   prompt_tokens: number;
@@ -1467,6 +1481,12 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
         artifactsEnabled,
         mcpEnabledForChat,
         webFetchToolsEnabled,
+        ragEnabled,
+        ragSource,
+        ragMode,
+        ragTopK,
+        ragAutoInject,
+        ragAutoInjectMinScore,
       } = runtime;
       const externalSelection = parseExternalModelId(params.checkpoint);
       const isExternalRequest = externalSelection !== null;
@@ -2368,10 +2388,13 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
             (toolsEnabled ||
               codeToolsEnabled ||
               renderHtmlToolEnabledForThisTurn ||
-              mcpEnabledForChat)
+              mcpEnabledForChat ||
+              ragEnabled)
               ? {
                   enable_tools: true,
                   enabled_tools: [
+                    // First so retrieval is the primary tool when Docs is on.
+                    ...(ragEnabled ? ["search_knowledge_base"] : []),
                     ...(toolsEnabled ? ["web_search"] : []),
                     ...(codeToolsEnabled ? ["python", "terminal"] : []),
                     ...(renderHtmlToolEnabledForThisTurn
@@ -2379,6 +2402,25 @@ export function createOpenAIStreamAdapter(): ChatModelAdapter {
                       : []),
                   ],
                   mcp_enabled: mcpEnabledForChat,
+                  // Scope: thread_id = this thread's docs, kb_id = a KB.
+                  ...(ragEnabled
+                    ? {
+                        rag_scope: {
+                          ...(ragSource.type === "kb"
+                            ? { kb_id: ragSource.kbId }
+                            : resolvedThreadId
+                              ? { thread_id: resolvedThreadId }
+                              : {}),
+                          default_top_k: ragTopK,
+                          mode: ragMode,
+                          autoinject: resolveAutoInject(
+                            ragAutoInject,
+                            params.checkpoint,
+                          ),
+                          autoinject_min_score: ragAutoInjectMinScore,
+                        },
+                      }
+                    : {}),
                   auto_heal_tool_calls:
                     useChatRuntimeStore.getState().autoHealToolCalls,
                   max_tool_calls_per_message:
diff --git a/studio/frontend/src/features/chat/api/prompts-api.ts b/studio/frontend/src/features/chat/api/prompts-api.ts
new file mode 100644
index 0000000000..d7f28a9285
--- /dev/null
+++ b/studio/frontend/src/features/chat/api/prompts-api.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+
+export interface PromptEntry {
+  id: string;
+  name: string;
+  text: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PromptListEntry {
+  id: string;
+  name: string;
+  items: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+async function parseJsonOrThrow<T>(res: Response): Promise<T> {
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    const detail = (body as { detail?: string } | null)?.detail;
+    throw new Error(detail ?? `Request failed (${res.status})`);
+  }
+  return body as T;
+}
+
+export async function listPromptEntries(): Promise<PromptEntry[]> {
+  const res = await authFetch("/api/prompts/entries");
+  const data = await parseJsonOrThrow<{ entries: PromptEntry[] }>(res);
+  return data.entries;
+}
+
+export async function savePromptEntry(entry: PromptEntry): Promise<PromptEntry> {
+  const res = await authFetch(`/api/prompts/entries/${entry.id}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(entry),
+  });
+  return parseJsonOrThrow<PromptEntry>(res);
+}
+
+export async function deletePromptEntry(id: string): Promise<void> {
+  const res = await authFetch(`/api/prompts/entries/${id}`, { method: "DELETE" });
+  if (!res.ok) throw new Error(`Delete failed (${res.status})`);
+}
+
+export async function bulkSavePromptEntries(entries: PromptEntry[]): Promise<number> {
+  if (!entries.length) return 0;
+  const res = await authFetch("/api/prompts/entries/bulk", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ entries }),
+  });
+  const data = await parseJsonOrThrow<{ count: number }>(res);
+  return data.count;
+}
+
+export async function listPromptLists(): Promise<PromptListEntry[]> {
+  const res = await authFetch("/api/prompts/lists");
+  const data = await parseJsonOrThrow<{ lists: PromptListEntry[] }>(res);
+  return data.lists;
+}
+
+export async function savePromptList(list: PromptListEntry): Promise<PromptListEntry> {
+  const res = await authFetch(`/api/prompts/lists/${list.id}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(list),
+  });
+  return parseJsonOrThrow<PromptListEntry>(res);
+}
+
+export async function deletePromptList(id: string): Promise<void> {
+  const res = await authFetch(`/api/prompts/lists/${id}`, { method: "DELETE" });
+  if (!res.ok) throw new Error(`Delete failed (${res.status})`);
+}
+
+export async function bulkSavePromptLists(lists: PromptListEntry[]): Promise<number> {
+  if (!lists.length) return 0;
+  const res = await authFetch("/api/prompts/lists/bulk", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ lists }),
+  });
+  const data = await parseJsonOrThrow<{ count: number }>(res);
+  return data.count;
+}
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 50650416a4..4472fffe7f 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -523,7 +523,12 @@ const LoraCompareContent = memo(function LoraCompareContent({
   const [baseThreadId, setBaseThreadId] = useState<string>();
   const [loraThreadId, setLoraThreadId] = useState<string>();
 
+  const compareRunning = useChatRuntimeStore(
+    (s) => Object.keys(s.runningByThreadId).length > 0,
+  );
+
   useEffect(() => {
+    if (compareRunning) return;
     let isActive = true;
     listStoredChatThreads({ pairId })
       .then((threads) => {
@@ -539,7 +544,7 @@ const LoraCompareContent = memo(function LoraCompareContent({
     return () => {
       isActive = false;
     };
-  }, [pairId]);
+  }, [pairId, compareRunning]);
 
   return (
     <CompareShell
@@ -548,6 +553,8 @@ const LoraCompareContent = memo(function LoraCompareContent({
         <SharedComposer
           handlesRef={handlesRef}
           onExitCompare={onExitCompare}
+          model1ThreadId={baseThreadId}
+          model2ThreadId={loraThreadId}
         />
       }
     >
@@ -666,6 +673,9 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
 
   const globalCheckpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const globalGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
+  const compareRunning = useChatRuntimeStore(
+    (s) => Object.keys(s.runningByThreadId).length > 0,
+  );
   const [model1, setModel1] = useState<CompareModelSelection>({
     id: globalCheckpoint || "",
     isLora: false,
@@ -690,6 +700,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
   );
 
   useEffect(() => {
+    if (compareRunning) return;
     let isActive = true;
     listStoredChatThreads({ pairId })
       .then((threads) => {
@@ -713,7 +724,7 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
     return () => {
       isActive = false;
     };
-  }, [pairId]);
+  }, [pairId, compareRunning]);
 
   return (
     <CompareShell
@@ -724,6 +735,8 @@ const GeneralCompareContent = memo(function GeneralCompareContent({
           model1={model1}
           model2={model2}
           onExitCompare={onExitCompare}
+          model1ThreadId={model1ThreadId}
+          model2ThreadId={model2ThreadId}
         />
       }
     >
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 3b192927d6..fc5d5f8b5c 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -90,6 +90,7 @@ import {
   providerSupportsFastMode,
 } from "./provider-capabilities";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
+import { RetrievalSettingsSection } from "@/features/rag/components/retrieval-settings-section";
 import type { InferenceParams } from "./types/runtime";
 
 export { defaultInferenceParams, type Preset } from "./presets/preset-policy";
@@ -1362,6 +1363,12 @@ export function ChatSettingsPanel({
             </div>
           </CollapsibleSection>
         ) : null}
+
+        {!isExternalModel ? (
+          <CollapsibleSection label="Retrieval">
+            <RetrievalSettingsSection />
+          </CollapsibleSection>
+        ) : null}
       </div>
       </div>
       </div>
diff --git a/studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts b/studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts
new file mode 100644
index 0000000000..4463aa3cd4
--- /dev/null
+++ b/studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts
@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { parseExternalModelId } from "../external-providers";
+import { useChatRuntimeStore } from "../stores/chat-runtime-store";
+
+// Single source of truth for the RAG pill's disabled gate and the Add Files bar's
+// visibility so the bar never shows while the pill is inert.
+export function useRagToolAvailable(): boolean {
+  const modelLoaded = useChatRuntimeStore(
+    (s) => !!s.params.checkpoint && !s.modelLoading,
+  );
+  const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
+  const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
+  return (
+    modelLoaded && parseExternalModelId(checkpoint) === null && supportsTools
+  );
+}
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index 8ff9385484..348c744b2c 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import { McpServerIcon } from "@hugeicons/core-free-icons";
+import { McpServerIcon, Tick02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { CheckIcon } from "lucide-react";
 import { type FC, useCallback, useEffect, useState } from "react";
 import { toast } from "sonner";
 
@@ -215,7 +214,9 @@ export function McpComposerButton({
       }
     >
       <span className="truncate">{opts.label}</span>
-      {opts.enabled ? <CheckIcon className="ml-auto" /> : null}
+      {opts.enabled ? (
+        <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="ml-auto" />
+      ) : null}
       {opts.hint ? (
         <Tooltip open={hintKey === opts.key}>
           <TooltipTrigger asChild={true}>
diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsx
index 8c92526b63..c4cd911fdb 100644
--- a/studio/frontend/src/features/chat/projects-page.tsx
+++ b/studio/frontend/src/features/chat/projects-page.tsx
@@ -13,6 +13,10 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
@@ -35,14 +39,27 @@ import {
 } from "@/features/chat";
 import {
   Delete02Icon,
+  Download01Icon,
   Edit03Icon,
   FolderAddIcon,
   Search01Icon,
+  Upload01Icon,
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { MoreHorizontalIcon } from "lucide-react";
 import { useNavigate } from "@tanstack/react-router";
-import { useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
+import {
+  exportProjectConversations,
+  exportBulkConversationsMerged,
+  exportBulkConversationsSeparate,
+  importConversationsFromFile,
+  EXPORT_FORMATS_LIST,
+  type ConvExportFormat,
+} from "./prompt-storage/prompt-storage-dialog";
+import {
+  listStoredChatThreads,
+} from "./utils/chat-history-storage";
 
 type SortMode = "activity" | "name";
 
@@ -76,6 +93,36 @@ export function ProjectsPage() {
   const [renameDraft, setRenameDraft] = useState("");
   const [deleting, setDeleting] = useState<ProjectRecord | null>(null);
 
+  const globalImportRef = useRef<HTMLInputElement>(null);
+  const projectImportRefs = useRef<Map<string, HTMLInputElement>>(new Map());
+  const [importFile, setImportFile] = useState<File | null>(null);
+  // null = Recents
+  const [importTargetId, setImportTargetId] = useState<string | null>(null);
+
+  async function handleImport(file: File, projectId: string | null) {
+    try {
+      const count = await importConversationsFromFile(file, projectId);
+      if (count === 0) {
+        toast.info("No conversations found in file.");
+      } else {
+        const dest = projectId
+          ? (projects.find((p) => p.id === projectId)?.name ?? "project")
+          : "Recents";
+        toast.success(`Imported ${count} conversation${count === 1 ? "" : "s"} to ${dest}.`);
+      }
+    } catch {
+      toast.error("Import failed.");
+    }
+  }
+
+  async function commitImport() {
+    if (!importFile) return;
+    const file = importFile;
+    const target = importTargetId;
+    setImportFile(null);
+    await handleImport(file, target);
+  }
+
   const visibleProjects = useMemo(() => {
     const trimmed = query.trim().toLowerCase();
     const filtered = trimmed
@@ -128,6 +175,48 @@ export function ProjectsPage() {
     }
   }
 
+  async function handleProjectExport(project: ProjectRecord, fmt: ConvExportFormat) {
+    try {
+      const threads = await listStoredChatThreads({ projectId: project.id, includeArchived: false });
+      const ids = [...new Set(threads.map((t) => t.id))];
+      await exportProjectConversations(ids, fmt, project.name);
+    } catch {
+      toast.error("Export failed.");
+    }
+  }
+
+  async function handleBulkProjectExport(
+    scope: "projects" | "all",
+    fmt: ConvExportFormat,
+    merged: boolean,
+  ) {
+    try {
+      let threads;
+      if (scope === "projects") {
+        threads = (
+          await Promise.all(
+            projects.map((p) =>
+              listStoredChatThreads({ projectId: p.id, includeArchived: false }),
+            ),
+          )
+        ).flat();
+      } else {
+        threads = await listStoredChatThreads({ includeArchived: false });
+      }
+      const ids = [...new Set(threads.map((t) => t.id))];
+      if (ids.length === 0) { toast.info("No conversations to export."); return; }
+      const ts = new Date().toISOString().slice(0, 10);
+      const basename = `${scope === "all" ? "all-chats" : "all-projects"}-${ts}`;
+      if (merged) {
+        await exportBulkConversationsMerged(ids, fmt, basename);
+      } else {
+        await exportBulkConversationsSeparate(ids, fmt, basename);
+      }
+    } catch {
+      toast.error("Export failed.");
+    }
+  }
+
   async function commitDelete() {
     const target = deleting;
     if (!target) return;
@@ -143,6 +232,21 @@ export function ProjectsPage() {
 
   return (
     <main className="mx-auto w-full max-w-7xl px-4 py-8 font-heading sm:px-6">
+      {/* Global import file input */}
+      <input
+        ref={globalImportRef}
+        type="file"
+        accept=".jsonl,.ndjson,.csv"
+        className="hidden"
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          if (file) {
+            setImportTargetId(projects[0]?.id ?? null);
+            setImportFile(file);
+          }
+          e.target.value = "";
+        }}
+      />
       <div className="flex flex-wrap items-center justify-between gap-4">
         <h1 className="text-2xl font-semibold tracking-tight text-foreground">
           Projects
@@ -163,6 +267,52 @@ export function ProjectsPage() {
               </SelectContent>
             </Select>
           </div>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="outline" size="icon" title="Import / Export projects">
+                <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-56">
+              <DropdownMenuItem onSelect={() => globalImportRef.current?.click()}>
+                <HugeiconsIcon icon={Upload01Icon} strokeWidth={1.75} className="size-icon" />
+                Import chats…
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger>Export All Projects</DropdownMenuSubTrigger>
+                <DropdownMenuSubContent className="w-52">
+                  {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                    <DropdownMenuItem key={`ap-m-${fmt}`} onSelect={() => void handleBulkProjectExport("projects", fmt, true)}>
+                      {label} — combined
+                    </DropdownMenuItem>
+                  ))}
+                  <DropdownMenuSeparator />
+                  {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                    <DropdownMenuItem key={`ap-s-${fmt}`} onSelect={() => void handleBulkProjectExport("projects", fmt, false)}>
+                      {label} — per chat
+                    </DropdownMenuItem>
+                  ))}
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger>Export Projects + Recents</DropdownMenuSubTrigger>
+                <DropdownMenuSubContent className="w-52">
+                  {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                    <DropdownMenuItem key={`all-m-${fmt}`} onSelect={() => void handleBulkProjectExport("all", fmt, true)}>
+                      {label} — combined
+                    </DropdownMenuItem>
+                  ))}
+                  <DropdownMenuSeparator />
+                  {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                    <DropdownMenuItem key={`all-s-${fmt}`} onSelect={() => void handleBulkProjectExport("all", fmt, false)}>
+                      {label} — per chat
+                    </DropdownMenuItem>
+                  ))}
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+            </DropdownMenuContent>
+          </DropdownMenu>
           <Button
             onClick={() => {
               setNameDraft("");
@@ -225,6 +375,22 @@ export function ProjectsPage() {
       ) : (
         <div className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
           {visibleProjects.map((project) => (
+            <div key={`wrap-${project.id}`} className="contents">
+            <input
+              key={`import-${project.id}`}
+              type="file"
+              accept=".jsonl,.ndjson,.csv"
+              className="hidden"
+              ref={(el) => {
+                if (el) projectImportRefs.current.set(project.id, el);
+                else projectImportRefs.current.delete(project.id);
+              }}
+              onChange={(e) => {
+                const file = e.target.files?.[0];
+                if (file) void handleImport(file, project.id);
+                e.target.value = "";
+              }}
+            />
             <div
               key={project.id}
               role="button"
@@ -270,6 +436,35 @@ export function ProjectsPage() {
                       <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
                       <span>Rename</span>
                     </DropdownMenuItem>
+                    <DropdownMenuItem
+                      onSelect={(e) => {
+                        e.stopPropagation();
+                        projectImportRefs.current.get(project.id)?.click();
+                      }}
+                    >
+                      <HugeiconsIcon icon={Upload01Icon} strokeWidth={1.75} className="size-icon" />
+                      <span>Import chats</span>
+                    </DropdownMenuItem>
+                    <DropdownMenuSub>
+                      <DropdownMenuSubTrigger>
+                        <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon mr-1" />
+                        <span>Export</span>
+                      </DropdownMenuSubTrigger>
+                      <DropdownMenuSubContent className="w-52">
+                        {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                          <DropdownMenuItem
+                            key={fmt}
+                            onSelect={(e) => {
+                              e.stopPropagation();
+                              void handleProjectExport(project, fmt);
+                            }}
+                          >
+                            {label}
+                          </DropdownMenuItem>
+                        ))}
+                      </DropdownMenuSubContent>
+                    </DropdownMenuSub>
+                    <DropdownMenuSeparator />
                     <DropdownMenuItem
                       variant="destructive"
                       onSelect={() => setDeleting(project)}
@@ -289,6 +484,7 @@ export function ProjectsPage() {
                 Updated {formatUpdatedAgo(project.updatedAt)}
               </span>
             </div>
+            </div>
           ))}
         </div>
       )}
@@ -371,6 +567,36 @@ export function ProjectsPage() {
         </DialogContent>
       </Dialog>
 
+      {/* Import destination picker */}
+      <Dialog open={importFile !== null} onOpenChange={(open) => { if (!open) setImportFile(null); }}>
+        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Import chats</DialogTitle>
+          </DialogHeader>
+          <p className="text-sm text-muted-foreground">
+            <span className="font-medium text-foreground">{importFile?.name}</span> — choose where to import:
+          </p>
+          <Select
+            value={importTargetId ?? "__recents__"}
+            onValueChange={(v) => setImportTargetId(v === "__recents__" ? null : v)}
+          >
+            <SelectTrigger>
+              <SelectValue placeholder="Select destination" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="__recents__">Recents</SelectItem>
+              {projects.map((p) => (
+                <SelectItem key={p.id} value={p.id}>{p.name}</SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <DialogFooter className="flex-wrap gap-2 sm:justify-end">
+            <Button type="button" variant="ghost" onClick={() => setImportFile(null)}>Cancel</Button>
+            <Button type="button" onClick={() => void commitImport()}>Import</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
       {/* Delete project */}
       <Dialog
         open={deleting !== null}
diff --git a/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
new file mode 100644
index 0000000000..80c2de54a2
--- /dev/null
+++ b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
@@ -0,0 +1,2009 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { cn } from "@/lib/utils";
+import {
+  BookmarkIcon,
+  CheckIcon,
+  DownloadIcon,
+  GripVerticalIcon,
+  LayoutListIcon,
+  PencilIcon,
+  PlayIcon,
+  PlusIcon,
+  SearchIcon,
+  Trash2Icon,
+  UploadIcon,
+  XIcon,
+} from "lucide-react";
+import {
+  type ReactElement,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { toast } from "sonner";
+import {
+  type PromptEntry,
+  type PromptListEntry,
+  bulkSavePromptEntries,
+  bulkSavePromptLists,
+  deletePromptEntry,
+  deletePromptList,
+  listPromptEntries,
+  listPromptLists,
+  savePromptEntry,
+  savePromptList,
+} from "../api/prompts-api";
+import {
+  listStoredChatMessages,
+  saveStoredChatThread,
+  syncStoredChatMessages,
+} from "../utils/chat-history-storage";
+import { notifyChatHistoryUpdated } from "../api/chat-api";
+import type { ThreadRecord, MessageRecord } from "../types";
+
+function newId(): string {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+}
+
+function now(): number {
+  return Date.now();
+}
+
+function sanitizeFilename(name: string): string {
+  return name.replace(/[\\/:*?"<>|]/g, "_").slice(0, 80) || "export";
+}
+
+function downloadBlob(content: string | Blob, filename: string, mimeType: string): void {
+  const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+function csvEscape(val: string): string {
+  return `"${val.replace(/"/g, '""')}"`;
+}
+
+function exportPromptJsonl(entry: PromptEntry): void {
+  downloadBlob(
+    JSON.stringify({ name: entry.name, text: entry.text }),
+    `${sanitizeFilename(entry.name)}.jsonl`,
+    "application/x-ndjson",
+  );
+}
+
+function exportPromptCsv(entry: PromptEntry): void {
+  downloadBlob(
+    `name,text\n${csvEscape(entry.name)},${csvEscape(entry.text)}`,
+    `${sanitizeFilename(entry.name)}.csv`,
+    "text/csv",
+  );
+}
+
+function exportAllPromptsJsonl(entries: PromptEntry[]): void {
+  const lines = entries.map((e) => JSON.stringify({ name: e.name, text: e.text })).join("\n");
+  downloadBlob(lines, "prompts.jsonl", "application/x-ndjson");
+}
+
+function exportAllPromptsCsv(entries: PromptEntry[]): void {
+  const rows = entries.map((e) => `${csvEscape(e.name)},${csvEscape(e.text)}`).join("\n");
+  downloadBlob(`name,text\n${rows}`, "prompts.csv", "text/csv");
+}
+
+function exportListJsonl(entry: PromptListEntry): void {
+  downloadBlob(
+    JSON.stringify({ name: entry.name, items: entry.items }),
+    `${sanitizeFilename(entry.name)}.jsonl`,
+    "application/x-ndjson",
+  );
+}
+
+function exportAllListsJsonl(entries: PromptListEntry[]): void {
+  const lines = entries.map((e) => JSON.stringify({ name: e.name, items: e.items })).join("\n");
+  downloadBlob(lines, "prompt-lists.jsonl", "application/x-ndjson");
+}
+
+function exportListCsv(entry: PromptListEntry): void {
+  const rows = entry.items
+    .map((text, i) => `${csvEscape(entry.name)},${i + 1},${csvEscape(text)}`)
+    .join("\n");
+  downloadBlob(
+    `list_name,order,prompt_text\n${rows}`,
+    `${sanitizeFilename(entry.name)}.csv`,
+    "text/csv",
+  );
+}
+
+function exportAllListsCsv(entries: PromptListEntry[]): void {
+  const rows = entries
+    .flatMap((e) => e.items.map((text, i) => `${csvEscape(e.name)},${i + 1},${csvEscape(text)}`))
+    .join("\n");
+  downloadBlob(`list_name,order,prompt_text\n${rows}`, "prompt-lists.csv", "text/csv");
+}
+
+function exportCollectionJsonl(prompts: PromptEntry[], lists: PromptListEntry[]): void {
+  const lines = [
+    ...prompts.map((e) => JSON.stringify({ type: "prompt", name: e.name, text: e.text })),
+    ...lists.map((e) => JSON.stringify({ type: "prompt_list", name: e.name, items: e.items })),
+  ].join("\n");
+  downloadBlob(lines, "prompt-collection.jsonl", "application/x-ndjson");
+}
+
+function contentBlocksToText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return JSON.stringify(content);
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+      const p = part as Record<string, unknown>;
+      if (p.type === "text" && typeof p.text === "string") {
+        parts.push(p.text);
+      } else if (p.type === "reasoning" || p.type === "thinking") {
+        const thinkText =
+          typeof p.thinking === "string"
+            ? p.thinking
+            : typeof p.text === "string"
+              ? p.text
+              : "";
+        if (thinkText) {
+          parts.push("[thinking]\n" + thinkText + "\n[/thinking]");
+        }
+      } else if (p.type === "tool-call") {
+        parts.push(
+          JSON.stringify({
+            tool_call: p.toolName,
+            args: p.args,
+            result: p.result,
+          }),
+        );
+      } else if (p.type === "image") {
+        parts.push("[image attachment]");
+      } else if (p.type === "audio") {
+        parts.push("[audio attachment]");
+      }
+    }
+    return parts.join("\n\n");
+  }
+
+// Order via parentId chain: createdAt misorders turns (GPT response slots
+// predate the user's next message); the parent chain is timestamp-independent.
+type _Msg = { id: string; parentId?: string | null; createdAt?: number };
+
+function orderByParentChain<T extends _Msg>(messages: T[]): T[] {
+  const byId = new Map<string, T>(messages.map((m) => [m.id, m]));
+  const childrenOf = new Map<string | null, T[]>();
+  for (const m of messages) {
+    const pid = m.parentId ?? null;
+    if (!childrenOf.has(pid)) childrenOf.set(pid, []);
+    childrenOf.get(pid)!.push(m);
+  }
+
+  const result: T[] = [];
+  let cur: string | null = null;
+  while (childrenOf.has(cur)) {
+    const children: T[] = childrenOf.get(cur)!;
+    const next: T = children.reduce((a: T, b: T) =>
+      (a.createdAt ?? 0) >= (b.createdAt ?? 0) ? a : b,
+    );
+    result.push(next);
+    cur = next.id;
+    byId.delete(next.id);
+  }
+
+  for (const [, m] of byId) result.push(m);
+  return result;
+}
+
+async function loadConversationMessages(threadId: string) {
+  const raw = await listStoredChatMessages(threadId);
+  if (raw.length === 0) {
+    toast.info("No messages in this conversation to export.");
+    return null;
+  }
+  // No parentId = legacy flat thread (already DB createdAt-sorted); walking the
+  // chain would invert order, so keep raw order.
+  const hasParentIds = raw.some((m) => (m as { parentId?: unknown }).parentId != null);
+  if (!hasParentIds) return raw;
+  return orderByParentChain(raw) as typeof raw;
+}
+
+function exportTs(): string {
+  return new Date().toISOString().slice(0, 19).replace(/:/g, "-");
+}
+
+// Attachments live in msg.attachments[].content, not msg.content, so flatten
+// both here or they'd be dropped on export.
+function messageToText(msg: { content: unknown; attachments?: unknown }): string {
+  const parts: string[] = [];
+  const main = contentBlocksToText(msg.content);
+  if (main) parts.push(main);
+  if (Array.isArray(msg.attachments)) {
+    for (const attachment of msg.attachments as Array<{ content?: unknown }>) {
+      if (!attachment?.content) continue;
+      const attText = contentBlocksToText(attachment.content);
+      if (attText) parts.push(attText);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+// OpenAI messages array (tool-calling + multimodal fine-tuning): tool calls →
+// "tool_calls" + separate "role":"tool" messages; images → "image_url" parts;
+// audio dropped; thinking kept as a text part.
+
+type OAIContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string } };
+
+type OAIToolCall = {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+};
+
+type OAIMessage =
+  | { role: "user" | "system"; content: string | OAIContentPart[] }
+  | { role: "assistant"; content: string | null; tool_calls?: OAIToolCall[] }
+  | { role: "tool"; tool_call_id: string; name: string; content: string };
+
+function messageToOpenAI(msg: { role: unknown; content: unknown; attachments?: unknown }): OAIMessage[] {
+  const role = (msg.role as string) ?? "user";
+  const blocks = Array.isArray(msg.content) ? msg.content : [];
+  const attachments = Array.isArray(msg.attachments) ? msg.attachments : [];
+
+  const allParts: Record<string, unknown>[] = [
+    ...blocks.map((b) => b as Record<string, unknown>),
+    ...attachments.flatMap((a) => {
+      const att = a as { content?: unknown };
+      return Array.isArray(att.content)
+        ? (att.content as Record<string, unknown>[])
+        : [];
+    }),
+  ];
+
+  if (role === "assistant") {
+    const textParts: string[] = [];
+    const toolCalls: OAIToolCall[] = [];
+    const toolResults: OAIMessage[] = [];
+
+    for (const p of allParts) {
+      if (p.type === "text" && typeof p.text === "string") {
+        textParts.push(p.text);
+      } else if (p.type === "reasoning" || p.type === "thinking") {
+        const t = typeof p.thinking === "string" ? p.thinking : typeof p.text === "string" ? p.text : "";
+        if (t) textParts.push(`<thinking>\n${t}\n</thinking>`);
+      } else if (p.type === "tool-call") {
+        const id = typeof p.toolCallId === "string" ? p.toolCallId : `call_${toolCalls.length}`;
+        const name = typeof p.toolName === "string" ? p.toolName : "unknown";
+        const argsStr = p.args != null ? JSON.stringify(p.args) : (typeof p.argsText === "string" ? p.argsText : "{}");
+        toolCalls.push({ id, type: "function", function: { name, arguments: argsStr } });
+        if (p.result !== undefined && p.result !== null) {
+          const resultStr = typeof p.result === "string" ? p.result : JSON.stringify(p.result);
+          toolResults.push({ role: "tool", tool_call_id: id, name, content: resultStr });
+        }
+      }
+    }
+
+    const content = textParts.join("\n\n") || null;
+    const assistantMsg: OAIMessage = toolCalls.length > 0
+      ? { role: "assistant", content, tool_calls: toolCalls }
+      : { role: "assistant", content: content ?? "" };
+
+    return toolResults.length > 0
+      ? [assistantMsg, ...toolResults]
+      : [assistantMsg];
+  }
+
+  const contentParts: OAIContentPart[] = [];
+  let hasNonText = false;
+
+  for (const p of allParts) {
+    if (p.type === "text" && typeof p.text === "string") {
+      contentParts.push({ type: "text", text: p.text });
+    } else if (p.type === "image" && typeof p.image === "string") {
+      contentParts.push({ type: "image_url", image_url: { url: p.image } });
+      hasNonText = true;
+    }
+  }
+
+  if (!hasNonText) {
+    const text = contentParts.map((p) => (p.type === "text" ? p.text : "")).join("\n\n");
+    return text ? [{ role: role as "user" | "system", content: text }] : [];
+  }
+  return contentParts.length > 0 ? [{ role: role as "user" | "system", content: contentParts }] : [];
+}
+
+// ShareGPT training JSONL (human/gpt turns).
+export async function exportConversationShareGPT(threadId: string): Promise<void> {
+  const messages = await loadConversationMessages(threadId);
+  if (!messages) return;
+
+  const conversations: Array<{ from: string; value: string }> = [];
+  for (const msg of messages) {
+    const role = msg.role as string;
+    const from = role === "user" ? "human" : "gpt";
+    const value = messageToText(msg);
+    if (value.trim()) conversations.push({ from, value });
+  }
+
+  if (conversations.length === 0) { toast.info("No exportable content."); return; }
+  downloadBlob(
+    JSON.stringify({ conversations }),
+    "conversation-" + exportTs() + ".jsonl",
+    "application/x-ndjson",
+  );
+}
+
+// OpenAI/ChatML JSONL: {"messages": [{"role","content"}, ...]} per conversation;
+// Unsloth reads this as a ChatML dataset.
+export async function exportConversationRawJsonl(threadId: string): Promise<void> {
+  const messages = await loadConversationMessages(threadId);
+  if (!messages) return;
+
+  const oaiMsgs: OAIMessage[] = messages.flatMap((msg) => messageToOpenAI(msg));
+  if (oaiMsgs.length === 0) { toast.info("No exportable content."); return; }
+  downloadBlob(
+    JSON.stringify({ messages: oaiMsgs }),
+    "conversation-" + exportTs() + ".jsonl",
+    "application/x-ndjson",
+  );
+}
+
+export async function exportConversationCsv(threadId: string): Promise<void> {
+  const messages = await loadConversationMessages(threadId);
+  if (!messages) return;
+
+  const rows = ["role,content"];
+  for (const msg of messages) {
+    const content = messageToText(msg);
+    if (!content.trim()) continue;
+    rows.push(`${csvEscape(msg.role as string)},${csvEscape(content)}`);
+  }
+
+  if (rows.length <= 1) { toast.info("No exportable content."); return; }
+  downloadBlob(rows.join("\n"), "conversation-" + exportTs() + ".csv", "text/csv");
+}
+
+export type ConvExportFormat = "jsonl-raw" | "csv" | "sharegpt";
+
+const EXPORT_FORMAT_LABELS: Record<ConvExportFormat, string> = {
+  "jsonl-raw": "Raw JSONL",
+  csv: "CSV",
+  sharegpt: "ShareGPT JSONL",
+};
+
+export const EXPORT_FORMATS_LIST = (
+  Object.keys(EXPORT_FORMAT_LABELS) as ConvExportFormat[]
+).map((fmt) => ({ fmt, label: EXPORT_FORMAT_LABELS[fmt] }));
+
+async function buildThreadContent(
+  threadId: string,
+  format: ConvExportFormat,
+): Promise<string | null> {
+  const messages = await loadConversationMessages(threadId);
+  if (!messages) return null;
+
+  if (format === "jsonl-raw") {
+    // OpenAI/ChatML: Unsloth reads the "messages" key as ChatML.
+    const oaiMsgs: OAIMessage[] = messages.flatMap((msg) => messageToOpenAI(msg));
+    if (oaiMsgs.length === 0) return null;
+    return JSON.stringify({ messages: oaiMsgs });
+  }
+
+  if (format === "sharegpt") {
+    const conversations: Array<{ from: string; value: string }> = [];
+    for (const msg of messages) {
+      const role = msg.role as string;
+      const value = messageToText(msg);
+      if (value.trim()) conversations.push({ from: role === "user" ? "human" : "gpt", value });
+    }
+    if (conversations.length === 0) return null;
+    return JSON.stringify({ conversations });
+  }
+
+  const rows: string[] = [];
+  for (const msg of messages) {
+    const content = messageToText(msg);
+    if (!content.trim()) continue;
+    rows.push(`${csvEscape(msg.role as string)},${csvEscape(content)}`);
+  }
+  return rows.length > 0 ? rows.join("\n") : null;
+}
+
+function csvHeader(format: ConvExportFormat): string {
+  return format === "csv" ? "role,content" : "";
+}
+
+function exportExt(format: ConvExportFormat): string {
+  return format === "csv" ? "csv" : "jsonl";
+}
+
+function exportMime(format: ConvExportFormat): string {
+  return format === "csv" ? "text/csv" : "application/x-ndjson";
+}
+
+export async function exportBulkConversationsMerged(
+  threadIds: string[],
+  format: ConvExportFormat,
+  basename: string,
+): Promise<void> {
+  if (threadIds.length === 0) { toast.info("No conversations to export."); return; }
+
+  const parts: string[] = [];
+  const header = csvHeader(format);
+
+  for (const id of threadIds) {
+    const content = await buildThreadContent(id, format);
+    if (content) parts.push(content);
+  }
+
+  if (parts.length === 0) { toast.info("No exportable content."); return; }
+
+  const body = header
+    ? header + "\n" + parts.join("\n")
+    : parts.join("\n");
+
+  downloadBlob(body, `${basename}.${exportExt(format)}`, exportMime(format));
+}
+
+export async function exportBulkConversationsSeparate(
+  threadIds: string[],
+  format: ConvExportFormat,
+  basename: string,
+): Promise<void> {
+  if (threadIds.length === 0) { toast.info("No conversations to export."); return; }
+
+  const { zipSync, strToU8 } = await import("fflate");
+  const ext = exportExt(format);
+  const header = csvHeader(format);
+  const files: Record<string, Uint8Array> = {};
+
+  for (const id of threadIds) {
+    const content = await buildThreadContent(id, format);
+    if (!content) continue;
+    const body = header ? header + "\n" + content : content;
+    files[`${id}.${ext}`] = strToU8(body);
+  }
+
+  if (Object.keys(files).length === 0) { toast.info("No exportable content."); return; }
+
+  const zipped = zipSync(files);
+  downloadBlob(
+    new Blob([zipped], { type: "application/zip" }),
+    `${basename}.zip`,
+    "application/zip",
+  );
+}
+
+export async function exportProjectConversations(
+  threadIds: string[],
+  format: ConvExportFormat,
+  projectName: string,
+): Promise<void> {
+  const safe = projectName.replace(/[^a-z0-9_-]/gi, "_").slice(0, 40);
+  await exportBulkConversationsMerged(
+    threadIds,
+    format,
+    `project-${safe}-${exportTs()}`,
+  );
+}
+
+// role:"tool" results are absorbed into the preceding assistant tool-call
+// part's `result` field rather than becoming separate records.
+function oaiMessagesToRecords(
+  oaiMsgs: unknown[],
+  threadId: string,
+  baseTs: number,
+): MessageRecord[] {
+  const toolResults = new Map<string, string>();
+  for (const m of oaiMsgs) {
+    const msg = m as Record<string, unknown>;
+    if (msg.role === "tool" && typeof msg.tool_call_id === "string") {
+      toolResults.set(msg.tool_call_id, typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? ""));
+    }
+  }
+
+  const records: MessageRecord[] = [];
+  let prevId: string | null = null;
+  let idx = 0;
+
+  for (const m of oaiMsgs) {
+    const msg = m as Record<string, unknown>;
+    const role = msg.role as string;
+    if (role === "tool") continue;
+
+    const id = crypto.randomUUID();
+
+    let content: unknown[];
+
+    if (role === "assistant") {
+      const parts: unknown[] = [];
+      if (typeof msg.content === "string" && msg.content.trim()) {
+        parts.push({ type: "text", text: msg.content });
+      }
+      if (Array.isArray(msg.tool_calls)) {
+        for (const tc of msg.tool_calls) {
+          const tcObj = tc as Record<string, unknown>;
+          const fn = (tcObj.function as Record<string, unknown>) ?? {};
+          const tcId = typeof tcObj.id === "string" ? tcObj.id : crypto.randomUUID();
+          const name = typeof fn.name === "string" ? fn.name : "unknown";
+          const argsStr = typeof fn.arguments === "string" ? fn.arguments : "{}";
+          let args: unknown = {};
+          try { args = JSON.parse(argsStr); } catch { /* keep empty */ }
+          const result = toolResults.get(tcId);
+          parts.push({
+            type: "tool-call",
+            toolCallId: tcId,
+            toolName: name,
+            args,
+            argsText: argsStr,
+            ...(result !== undefined ? { result } : {}),
+          });
+        }
+      }
+      content = parts;
+    } else {
+      const raw = msg.content;
+      if (Array.isArray(raw)) {
+        content = raw.flatMap((p): unknown[] => {
+          const part = p as Record<string, unknown>;
+          if (part.type === "text" && typeof part.text === "string") {
+            return [{ type: "text", text: part.text }];
+          }
+          if (part.type === "image_url") {
+            const iu = (part.image_url as Record<string, unknown>) ?? {};
+            return [{ type: "image", image: typeof iu.url === "string" ? iu.url : "" }];
+          }
+          return [];
+        });
+      } else {
+        content = typeof raw === "string" && raw.trim() ? [{ type: "text", text: raw }] : [];
+      }
+    }
+
+    if (content.length === 0) continue;
+
+    records.push({
+      id,
+      threadId,
+      parentId: prevId,
+      role: role as MessageRecord["role"],
+      content: content as MessageRecord["content"],
+      createdAt: baseTs + idx,
+    });
+    prevId = id;
+    idx++;
+  }
+
+  return records;
+}
+
+function sharegptToRecords(
+  conversations: unknown[],
+  threadId: string,
+  baseTs: number,
+): MessageRecord[] {
+  const records: MessageRecord[] = [];
+  let prevId: string | null = null;
+  let idx = 0;
+  for (const c of conversations) {
+    const conv = c as Record<string, unknown>;
+    const from = typeof conv.from === "string" ? conv.from : "";
+    const value = typeof conv.value === "string" ? conv.value : "";
+    if (!value.trim()) continue;
+    const role: MessageRecord["role"] = from === "human" ? "user" : from === "system" ? "system" : "assistant";
+    const id = crypto.randomUUID();
+    records.push({
+      id,
+      threadId,
+      parentId: prevId,
+      role,
+      content: [{ type: "text", text: value }] as MessageRecord["content"],
+      createdAt: baseTs + idx,
+    });
+    prevId = id;
+    idx++;
+  }
+  return records;
+}
+
+function csvToRecords(csvText: string, threadId: string, baseTs: number): MessageRecord[] {
+  const lines = csvText.split(/\r?\n/);
+  const records: MessageRecord[] = [];
+  let prevId: string | null = null;
+  let idx = 0;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let role = "";
+    let content = "";
+    if (line.startsWith('"')) {
+      const m = line.match(/^"((?:[^"]|"")*)"\s*,\s*([\s\S]*)$/);
+      if (!m) continue;
+      role = m[1].replace(/""/g, '"');
+      content = m[2].startsWith('"')
+        ? m[2].slice(1, m[2].endsWith('"') ? -1 : undefined).replace(/""/g, '"')
+        : m[2];
+    } else {
+      const comma = line.indexOf(",");
+      if (comma === -1) continue;
+      role = line.slice(0, comma);
+      content = line.slice(comma + 1).startsWith('"')
+        ? line.slice(comma + 2, line.endsWith('"') ? -1 : undefined).replace(/""/g, '"')
+        : line.slice(comma + 1);
+    }
+    if (!content.trim()) continue;
+    const validRole = role === "user" || role === "assistant" || role === "system" ? role : "user";
+    const id = crypto.randomUUID();
+    records.push({
+      id,
+      threadId,
+      parentId: prevId,
+      role: validRole as MessageRecord["role"],
+      content: [{ type: "text", text: content }] as MessageRecord["content"],
+      createdAt: baseTs + idx,
+    });
+    prevId = id;
+    idx++;
+  }
+  return records;
+}
+
+interface ParsedConversation {
+  title: string;
+  threadId: string;
+  messages: MessageRecord[];
+}
+
+function parseImportText(text: string, filename: string): ParsedConversation[] {
+  const results: ParsedConversation[] = [];
+  const basename = filename.replace(/\.[^.]+$/, "");
+
+  const isJsonl = /\.(jsonl|ndjson)$/i.test(filename);
+  const isCsv = /\.csv$/i.test(filename);
+
+  if (isCsv) {
+    const threadId = crypto.randomUUID();
+    const messages = csvToRecords(text, threadId, Date.now());
+    if (messages.length > 0) {
+      results.push({ title: basename, threadId, messages });
+    }
+    return results;
+  }
+
+  if (isJsonl) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim());
+    lines.forEach((line, lineIdx) => {
+      let obj: Record<string, unknown>;
+      try { obj = JSON.parse(line); } catch { return; }
+
+      // Fresh ID: reusing the exported thread_id would clobber an existing
+      // thread on import.
+      const threadId = crypto.randomUUID();
+      const title = typeof obj.title === "string" ? obj.title : `${basename} ${lineIdx + 1}`;
+      const baseTs = typeof obj.created_at === "number" ? obj.created_at : Date.now() + lineIdx;
+
+      let messages: MessageRecord[] = [];
+
+      if (Array.isArray(obj.messages)) {
+        messages = oaiMessagesToRecords(obj.messages, threadId, baseTs);
+      } else if (Array.isArray(obj.conversations)) {
+        messages = sharegptToRecords(obj.conversations, threadId, baseTs);
+      }
+
+      if (messages.length > 0) {
+        results.push({ title, threadId, messages });
+      }
+    });
+    return results;
+  }
+
+  // Unknown extension: retry as JSONL.
+  return parseImportText(text, filename + ".jsonl");
+}
+
+export async function importConversationsFromFile(
+  file: File,
+  projectId: string | null = null,
+): Promise<number> {
+  const text = await file.text();
+  const parsed = parseImportText(text, file.name);
+  if (parsed.length === 0) return 0;
+
+  const now = Date.now();
+  await Promise.all(
+    parsed.map(async ({ title, threadId, messages }) => {
+      const thread: ThreadRecord = {
+        id: threadId,
+        title,
+        modelType: "base",
+        projectId: projectId ?? null,
+        archived: false,
+        createdAt: messages[0]?.createdAt ?? now,
+      };
+      await saveStoredChatThread(thread);
+      await syncStoredChatMessages(threadId, messages, { pruneMissing: false });
+    }),
+  );
+
+  notifyChatHistoryUpdated();
+  return parsed.length;
+}
+
+// ShareGPT training exports: prompt → one record (human turn + empty gpt slot);
+// list → one multi-turn record, each item a human turn.
+function exportPromptTrainingJsonl(entry: PromptEntry): void {
+  const record = {
+    conversations: [
+      { from: "human", value: entry.text },
+      { from: "gpt", value: "" },
+    ],
+  };
+  downloadBlob(
+    JSON.stringify(record),
+    `${sanitizeFilename(entry.name)}-training.jsonl`,
+    "application/x-ndjson",
+  );
+}
+
+function exportPromptsTrainingJsonl(entries: PromptEntry[]): void {
+  const lines = entries
+    .map((e) =>
+      JSON.stringify({
+        conversations: [
+          { from: "human", value: e.text },
+          { from: "gpt", value: "" },
+        ],
+      }),
+    )
+    .join("\n");
+  downloadBlob(lines, "prompts-training.jsonl", "application/x-ndjson");
+}
+
+function exportListTrainingJsonl(entry: PromptListEntry): void {
+  const conversations = entry.items.flatMap((text) => [
+    { from: "human", value: text },
+    { from: "gpt", value: "" },
+  ]);
+  downloadBlob(
+    JSON.stringify({ conversations }),
+    `${sanitizeFilename(entry.name)}-training.jsonl`,
+    "application/x-ndjson",
+  );
+}
+
+function exportListsTrainingJsonl(entries: PromptListEntry[]): void {
+  const lines = entries
+    .map((e) => {
+      const conversations = e.items.flatMap((text) => [
+        { from: "human", value: text },
+        { from: "gpt", value: "" },
+      ]);
+      return JSON.stringify({ conversations });
+    })
+    .join("\n");
+  downloadBlob(lines, "prompt-lists-training.jsonl", "application/x-ndjson");
+}
+
+// RFC 4180 CSV parser: handles quoted fields with embedded newlines/commas.
+function parseCsv(text: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let i = 0;
+
+  function finishRow() {
+    rows.push(row);
+    row = [];
+  }
+
+  while (i < text.length) {
+    if (text[i] === '"') {
+      i++;
+      let cell = "";
+      while (i < text.length) {
+        if (text[i] === '"') {
+          if (text[i + 1] === '"') {
+            cell += '"';
+            i += 2;
+          } else {
+            i++;
+            break;
+          }
+        } else {
+          cell += text[i++];
+        }
+      }
+      row.push(cell);
+      if (text[i] === ",") { i++; }
+      else if (text[i] === "\r") { i++; if (text[i] === "\n") i++; finishRow(); }
+      else if (text[i] === "\n") { i++; finishRow(); }
+    } else if (text[i] === "\r") {
+      i++;
+      if (text[i] === "\n") i++;
+      row.push("");
+      finishRow();
+    } else if (text[i] === "\n") {
+      i++;
+      row.push("");
+      finishRow();
+    } else {
+      let cell = "";
+      while (i < text.length && text[i] !== "," && text[i] !== "\r" && text[i] !== "\n") {
+        cell += text[i++];
+      }
+      row.push(cell);
+      if (text[i] === ",") { i++; }
+      else if (text[i] === "\r") { i++; if (text[i] === "\n") i++; finishRow(); }
+      else if (text[i] === "\n") { i++; finishRow(); }
+    }
+  }
+  if (row.length > 0) rows.push(row);
+  return rows;
+}
+
+async function importPromptsFromText(text: string, isCsv: boolean): Promise<{ count: number; skipped: number }> {
+  const entries: PromptEntry[] = [];
+  let skipped = 0;
+  if (isCsv) {
+    const rows = parseCsv(text).slice(1);
+    for (const cells of rows) {
+      const name = cells[0]?.trim();
+      const promptText = cells[1]?.trim();
+      if (promptText) {
+        entries.push({
+          id: newId(),
+          name: name || "Imported",
+          text: promptText,
+          createdAt: now(),
+          updatedAt: now(),
+        });
+      }
+    }
+  } else {
+    for (const raw of text.split("\n")) {
+      const line = raw.trim();
+      if (!line) continue;
+      try {
+        const obj = JSON.parse(line) as Record<string, unknown>;
+        if (typeof obj.text === "string" && obj.text.trim()) {
+          entries.push({
+            id: newId(),
+            name: typeof obj.name === "string" ? obj.name || "Imported" : "Imported",
+            text: obj.text.trim(),
+            createdAt: now(),
+            updatedAt: now(),
+          });
+        } else {
+          skipped++;
+        }
+      } catch {
+        skipped++;
+      }
+    }
+  }
+  if (entries.length > 0) await bulkSavePromptEntries(entries);
+  return { count: entries.length, skipped };
+}
+
+async function importListsFromText(text: string, isCsv: boolean): Promise<{ count: number; skipped: number }> {
+  const lists: PromptListEntry[] = [];
+  let skipped = 0;
+  if (isCsv) {
+    const rows = parseCsv(text).slice(1);
+    const listMap = new Map<string, Array<{ order: number; text: string }>>();
+    for (const cells of rows) {
+      const listName = cells[0]?.trim();
+      const promptText = cells[2]?.trim();
+      if (listName && promptText) {
+        const order = parseInt(cells[1] ?? "0", 10) || 0;
+        if (!listMap.has(listName)) listMap.set(listName, []);
+        listMap.get(listName)!.push({ order, text: promptText });
+      }
+    }
+    for (const [listName, items] of listMap.entries()) {
+      const sorted = items.sort((a, b) => a.order - b.order).map((x) => x.text);
+      if (sorted.length > 0) {
+        lists.push({
+          id: newId(),
+          name: listName,
+          items: sorted,
+          createdAt: now(),
+          updatedAt: now(),
+        });
+      }
+    }
+  } else {
+    for (const raw of text.split("\n")) {
+      const line = raw.trim();
+      if (!line) continue;
+      try {
+        const obj = JSON.parse(line) as Record<string, unknown>;
+        if (Array.isArray(obj.items) && obj.items.length > 0) {
+          const items = (obj.items as unknown[]).filter(
+            (x): x is string => typeof x === "string" && x.trim().length > 0,
+          );
+          if (items.length > 0) {
+            lists.push({
+              id: newId(),
+              name: typeof obj.name === "string" ? obj.name || "Imported" : "Imported",
+              items,
+              createdAt: now(),
+              updatedAt: now(),
+            });
+          } else {
+            skipped++;
+          }
+        } else {
+          skipped++;
+        }
+      } catch {
+        skipped++;
+      }
+    }
+  }
+  if (lists.length > 0) await bulkSavePromptLists(lists);
+  return { count: lists.length, skipped };
+}
+
+async function importCollectionFromText(text: string): Promise<{ prompts: number; lists: number }> {
+  const entries: PromptEntry[] = [];
+  const listEntries: PromptListEntry[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    try {
+      const obj = JSON.parse(line) as Record<string, unknown>;
+      if (obj.type === "prompt" && typeof obj.text === "string" && obj.text.trim()) {
+        entries.push({
+          id: newId(),
+          name: typeof obj.name === "string" ? obj.name || "Imported" : "Imported",
+          text: obj.text.trim(),
+          createdAt: now(),
+          updatedAt: now(),
+        });
+      } else if (obj.type === "prompt_list" && Array.isArray(obj.items) && obj.items.length > 0) {
+        const items = (obj.items as unknown[]).filter(
+          (x): x is string => typeof x === "string" && x.trim().length > 0,
+        );
+        if (items.length > 0) {
+          listEntries.push({
+            id: newId(),
+            name: typeof obj.name === "string" ? obj.name || "Imported" : "Imported",
+            items,
+            createdAt: now(),
+            updatedAt: now(),
+          });
+        }
+      }
+    } catch {
+      /* */
+    }
+  }
+  if (entries.length > 0) await bulkSavePromptEntries(entries);
+  if (listEntries.length > 0) await bulkSavePromptLists(listEntries);
+  return { prompts: entries.length, lists: listEntries.length };
+}
+
+type ExportScope = "single" | "training";
+type ExportFormat = "jsonl" | "csv";
+
+type ExportModalCtx =
+  | { kind: "prompt"; entry: PromptEntry }
+  | { kind: "list"; entry: PromptListEntry }
+  | { kind: "bulk"; tab: Tab; prompts: PromptEntry[]; lists: PromptListEntry[] };
+
+function ExportModal({
+  ctx,
+  onClose,
+}: {
+  ctx: ExportModalCtx;
+  onClose: () => void;
+}): ReactElement {
+  const [scope, setScope] = useState<ExportScope>("single");
+  const [format, setFormat] = useState<ExportFormat>("jsonl");
+
+  const csvAvailable = scope === "single";
+
+  useEffect(() => {
+    if (!csvAvailable) setFormat("jsonl");
+  }, [csvAvailable]);
+
+  const handleExport = useCallback(() => {
+    if (ctx.kind === "prompt") {
+      if (scope === "training") exportPromptTrainingJsonl(ctx.entry);
+      else if (format === "csv") exportPromptCsv(ctx.entry);
+      else exportPromptJsonl(ctx.entry);
+    } else if (ctx.kind === "list") {
+      if (scope === "training") exportListTrainingJsonl(ctx.entry);
+      else if (format === "csv") exportListCsv(ctx.entry);
+      else exportListJsonl(ctx.entry);
+    } else {
+      const { tab, prompts, lists } = ctx;
+      if (scope === "training") {
+        if (tab === "prompts") {
+          if (prompts.length === 0) { toast.info("No prompts to export"); return; }
+          exportPromptsTrainingJsonl(prompts);
+        } else {
+          if (lists.length === 0) { toast.info("No prompt lists to export"); return; }
+          exportListsTrainingJsonl(lists);
+        }
+      } else {
+        if (tab === "prompts") {
+          if (prompts.length === 0) { toast.info("No prompts to export"); return; }
+          if (format === "csv") exportAllPromptsCsv(prompts);
+          else exportAllPromptsJsonl(prompts);
+        } else {
+          if (lists.length === 0) { toast.info("No prompt lists to export"); return; }
+          if (format === "csv") exportAllListsCsv(lists);
+          else exportAllListsJsonl(lists);
+        }
+      }
+    }
+    onClose();
+  }, [ctx, scope, format, onClose]);
+
+  const singleLabel =
+    ctx.kind === "prompt"
+      ? "Single Prompt"
+      : ctx.kind === "list"
+        ? "Prompt List"
+        : ctx.kind === "bulk" && ctx.tab === "prompts"
+          ? "All Prompts"
+          : "All Prompt Lists";
+
+  const singleDesc =
+    ctx.kind === "prompt"
+      ? "Export raw prompt name and text"
+      : ctx.kind === "list"
+        ? "Export list name and all prompt items"
+        : ctx.kind === "bulk" && ctx.tab === "prompts"
+          ? "One JSONL or CSV record per saved prompt"
+          : "One JSONL or CSV record per saved list";
+
+  return (
+    <Dialog open onOpenChange={onClose}>
+      {/* */}
+      <DialogContent className="sm:max-w-[520px] gap-0 p-0 overflow-hidden">
+        <div className="flex flex-col gap-5 p-6">
+          {/* */}
+          <DialogTitle className="text-base font-semibold tracking-tight">Export</DialogTitle>
+          <DialogDescription className="sr-only">Choose export type and format.</DialogDescription>
+
+          {/* */}
+          <div className="flex flex-col gap-2">
+            <p className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">
+              Export as
+            </p>
+            <div className="flex flex-col gap-2">
+              {/* */}
+              <label
+                className={cn(
+                  "flex w-full cursor-pointer items-center gap-3 rounded-lg border px-4 py-3 transition-all",
+                  scope === "single"
+                    ? "border-primary/40 bg-primary/5 ring-1 ring-primary/20"
+                    : "border-border/60 hover:border-border hover:bg-muted/30",
+                )}
+              >
+                <input
+                  type="radio"
+                  name="export-scope"
+                  value="single"
+                  checked={scope === "single"}
+                  onChange={() => setScope("single")}
+                  className="accent-primary shrink-0"
+                />
+                <div className="min-w-0">
+                  <p className="text-sm font-semibold leading-none">{singleLabel}</p>
+                  <p className="mt-1 text-xs text-muted-foreground">{singleDesc}</p>
+                </div>
+              </label>
+
+              {/* */}
+              <label
+                className={cn(
+                  "flex w-full cursor-pointer items-start gap-3 rounded-lg border px-4 py-3 transition-all",
+                  scope === "training"
+                    ? "border-primary/40 bg-primary/5 ring-1 ring-primary/20"
+                    : "border-border/60 hover:border-border hover:bg-muted/30",
+                )}
+              >
+                <input
+                  type="radio"
+                  name="export-scope"
+                  value="training"
+                  checked={scope === "training"}
+                  onChange={() => setScope("training")}
+                  className="mt-0.5 accent-primary shrink-0"
+                />
+                <div className="min-w-0 flex-1">
+                  <p className="text-sm font-semibold leading-none">Training Style</p>
+                  <p className="mt-1 text-xs text-muted-foreground">
+                    ShareGPT format for Unsloth fine-tuning
+                  </p>
+                  <code className="mt-2 block w-full truncate rounded-md bg-muted px-2 py-1 font-mono text-[10px] text-muted-foreground/60">
+                    {`{"conversations":[{"from":"human","value":"..."},{"from":"gpt","value":""}]}`}
+                  </code>
+                </div>
+              </label>
+            </div>
+          </div>
+
+          {/* */}
+          <div className="flex flex-col gap-2">
+            <p className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">
+              Format
+            </p>
+            <div className="flex items-center gap-1 self-start rounded-lg bg-muted/60 p-1">
+              {(["jsonl", "csv"] as ExportFormat[]).map((f) => {
+                const disabled = f === "csv" && !csvAvailable;
+                return (
+                  <label
+                    key={f}
+                    className={cn(
+                      "select-none rounded-md px-6 py-1.5 text-xs font-semibold uppercase tracking-wide transition-all",
+                      disabled
+                        ? "cursor-not-allowed opacity-40 text-muted-foreground"
+                        : "cursor-pointer",
+                      format === f && !disabled
+                        ? "bg-background text-foreground shadow-sm ring-1 ring-border/40"
+                        : !disabled && "text-muted-foreground hover:text-foreground",
+                    )}
+                  >
+                    <input
+                      type="radio"
+                      name="export-format"
+                      value={f}
+                      checked={format === f}
+                      onChange={() => { if (!disabled) setFormat(f); }}
+                      disabled={disabled}
+                      className="sr-only"
+                    />
+                    {f.toUpperCase()}
+                  </label>
+                );
+              })}
+            </div>
+            {!csvAvailable && (
+              <p className="text-xs text-muted-foreground/60">
+                CSV is not available for this export type
+              </p>
+            )}
+          </div>
+        </div>
+
+        {/* */}
+        <div className="flex items-center justify-end gap-2 border-t border-border/50 px-6 py-4">
+          <Button variant="ghost" size="sm" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button size="sm" onClick={handleExport}>
+            <DownloadIcon className="mr-1.5 size-3.5" />
+            Download
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function PromptCard({
+  entry,
+  onUse,
+  onExport,
+  onRefresh,
+}: {
+  entry: PromptEntry;
+  onUse: (text: string) => void;
+  onExport: (entry: PromptEntry) => void;
+  onRefresh: () => void;
+}): ReactElement {
+  const [editing, setEditing] = useState(false);
+  const [name, setName] = useState(entry.name);
+  const [text, setText] = useState(entry.text);
+
+  const handleSave = useCallback(async () => {
+    const trimName = name.trim();
+    const trimText = text.trim();
+    if (!trimText) return;
+    await savePromptEntry({ ...entry, name: trimName || "Untitled Prompt", text: trimText, updatedAt: now() });
+    setEditing(false);
+    onRefresh();
+  }, [entry, name, text, onRefresh]);
+
+  const handleDelete = useCallback(async () => {
+    await deletePromptEntry(entry.id);
+    onRefresh();
+  }, [entry.id, onRefresh]);
+
+  if (editing) {
+    return (
+      <div className="rounded-xl border border-border/50 bg-muted/30 p-4 flex flex-col gap-3">
+        <input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="Prompt name..."
+          className="w-full rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow"
+        />
+        <textarea
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          rows={4}
+          placeholder="Prompt text..."
+          className="w-full resize-y rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow leading-relaxed"
+        />
+        <div className="flex gap-2 justify-end">
+          <Button size="sm" variant="ghost" onClick={() => { setName(entry.name); setText(entry.text); setEditing(false); }}>
+            <XIcon className="size-3.5 mr-1" />Cancel
+          </Button>
+          <Button size="sm" onClick={handleSave}>
+            <CheckIcon className="size-3.5 mr-1" />Save
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="group rounded-xl border border-border/60 bg-card p-4 flex flex-col gap-2 hover:border-border hover:shadow-sm transition-all">
+      <div className="flex items-center gap-2">
+        <span className="font-semibold text-sm flex-1 truncate tracking-tight">{entry.name}</span>
+        <div className="flex items-center gap-0.5 opacity-0 group-hover:opacity-100 transition-opacity">
+          <button
+            type="button"
+            onClick={() => onUse(entry.text)}
+            className="flex items-center gap-1.5 rounded-lg bg-primary px-2.5 py-1 text-xs font-semibold text-primary-foreground hover:bg-primary/90 transition-colors"
+            title="Load into composer"
+          >
+            <PlayIcon className="size-3" />Use
+          </button>
+          <div className="mx-1 h-4 w-px bg-border/60" />
+          <button
+            type="button"
+            onClick={() => onExport(entry)}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+            title="Export"
+          >
+            <DownloadIcon className="size-3.5" />
+          </button>
+          <button
+            type="button"
+            onClick={() => setEditing(true)}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+            title="Edit"
+          >
+            <PencilIcon className="size-3.5" />
+          </button>
+          <button
+            type="button"
+            onClick={handleDelete}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-destructive/10 hover:text-destructive transition-colors"
+            title="Delete"
+          >
+            <Trash2Icon className="size-3.5" />
+          </button>
+        </div>
+      </div>
+      <p className="text-xs text-muted-foreground line-clamp-3 leading-relaxed">{entry.text}</p>
+    </div>
+  );
+}
+
+function NewPromptForm({ onClose, onRefresh }: { onClose: () => void; onRefresh: () => void }): ReactElement {
+  const [name, setName] = useState("");
+  const [text, setText] = useState("");
+
+  const handleSave = useCallback(async () => {
+    const trimText = text.trim();
+    if (!trimText) return;
+    const ts = now();
+    await savePromptEntry({
+      id: newId(),
+      name: name.trim() || "Untitled Prompt",
+      text: trimText,
+      createdAt: ts,
+      updatedAt: ts,
+    });
+    onRefresh();
+    onClose();
+  }, [name, text, onClose, onRefresh]);
+
+  return (
+    <div className="rounded-xl border border-border/50 bg-muted/30 p-4 flex flex-col gap-3">
+      <p className="text-xs font-semibold text-muted-foreground">New Prompt</p>
+      <input
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        placeholder="Prompt name (optional)..."
+        autoFocus
+        className="w-full rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow"
+      />
+      <textarea
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        rows={4}
+        placeholder="Write your prompt here..."
+        className="w-full resize-y rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow leading-relaxed"
+      />
+      <div className="flex gap-2 justify-end">
+        <Button size="sm" variant="ghost" onClick={onClose}>
+          <XIcon className="size-3.5 mr-1" />Cancel
+        </Button>
+        <Button size="sm" onClick={handleSave} disabled={!text.trim()}>
+          <CheckIcon className="size-3.5 mr-1" />Save Prompt
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function PromptListCard({
+  entry,
+  onRunList,
+  onExport,
+  onRefresh,
+}: {
+  entry: PromptListEntry;
+  onRunList?: (items: string[]) => void;
+  onExport: (entry: PromptListEntry) => void;
+  onRefresh: () => void;
+}): ReactElement {
+  const [editing, setEditing] = useState(false);
+  const [name, setName] = useState(entry.name);
+  const [items, setItems] = useState<string[]>(entry.items);
+
+  const handleSave = useCallback(async () => {
+    const filtered = items.filter((t) => t.trim());
+    if (filtered.length === 0) return;
+    await savePromptList({ ...entry, name: name.trim() || "Untitled List", items: filtered, updatedAt: now() });
+    setEditing(false);
+    onRefresh();
+  }, [entry, name, items, onRefresh]);
+
+  const handleDelete = useCallback(async () => {
+    await deletePromptList(entry.id);
+    onRefresh();
+  }, [entry.id, onRefresh]);
+
+  const addItem = useCallback(() => setItems((prev) => [...prev, ""]), []);
+  const removeItem = useCallback(
+    (i: number) => setItems((prev) => prev.filter((_, idx) => idx !== i)),
+    [],
+  );
+  const updateItem = useCallback(
+    (i: number, val: string) =>
+      setItems((prev) => prev.map((v, idx) => (idx === i ? val : v))),
+    [],
+  );
+
+  if (editing) {
+    return (
+      <div className="rounded-xl border border-border/50 bg-muted/30 p-4 flex flex-col gap-3">
+        <input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="List name..."
+          className="w-full rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow"
+        />
+        <p className="text-xs font-semibold text-muted-foreground">Prompts (sent in order)</p>
+        <div className="flex flex-col gap-2">
+          {items.map((item, i) => (
+            <div key={i} className="flex items-start gap-2">
+              <GripVerticalIcon className="size-4 mt-2.5 shrink-0 text-muted-foreground/30 cursor-grab" />
+              <span className="text-xs font-medium text-muted-foreground/60 mt-2.5 w-5 shrink-0 text-right">{i + 1}.</span>
+              <textarea
+                value={item}
+                onChange={(e) => updateItem(i, e.target.value)}
+                rows={2}
+                placeholder={`Prompt ${i + 1}...`}
+                className="flex-1 resize-y rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow leading-relaxed"
+              />
+              <button
+                type="button"
+                onClick={() => removeItem(i)}
+                className="flex h-7 w-7 mt-1 items-center justify-center rounded-lg text-muted-foreground hover:bg-destructive/10 hover:text-destructive transition-colors shrink-0"
+                title="Remove"
+              >
+                <XIcon className="size-3.5" />
+              </button>
+            </div>
+          ))}
+        </div>
+        <button
+          type="button"
+          onClick={addItem}
+          className="flex items-center gap-1.5 text-xs font-medium text-primary hover:text-primary/80 transition-colors"
+        >
+          <PlusIcon className="size-3.5" />Add prompt
+        </button>
+        <div className="flex gap-2 justify-end">
+          <Button
+            size="sm"
+            variant="ghost"
+            onClick={() => { setName(entry.name); setItems(entry.items); setEditing(false); }}
+          >
+            <XIcon className="size-3.5 mr-1" />Cancel
+          </Button>
+          <Button
+            size="sm"
+            onClick={handleSave}
+            disabled={items.filter((t) => t.trim()).length === 0}
+          >
+            <CheckIcon className="size-3.5 mr-1" />Save List
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="group rounded-xl border border-border/60 bg-card p-4 flex flex-col gap-2.5 hover:border-border hover:shadow-sm transition-all">
+      <div className="flex items-center gap-2">
+        <span className="font-semibold text-sm flex-1 truncate tracking-tight">{entry.name}</span>
+        <span className="shrink-0 rounded-full bg-muted px-2 py-0.5 text-[11px] font-medium text-muted-foreground">
+          {entry.items.length}
+        </span>
+        <div className="flex items-center gap-0.5 opacity-0 group-hover:opacity-100 transition-opacity">
+          {onRunList && (
+            <button
+              type="button"
+              onClick={() => onRunList(entry.items)}
+              className="flex h-7 items-center gap-1.5 rounded-lg px-2.5 text-xs font-semibold text-primary hover:bg-primary/10 transition-colors"
+              title="Run list"
+            >
+              <PlayIcon className="size-3" />Run
+            </button>
+          )}
+          <div className="mx-1 h-4 w-px bg-border/60" />
+          <button
+            type="button"
+            onClick={() => onExport(entry)}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+            title="Export"
+          >
+            <DownloadIcon className="size-3.5" />
+          </button>
+          <button
+            type="button"
+            onClick={() => setEditing(true)}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+            title="Edit"
+          >
+            <PencilIcon className="size-3.5" />
+          </button>
+          <button
+            type="button"
+            onClick={handleDelete}
+            className="flex h-7 w-7 items-center justify-center rounded-lg text-muted-foreground hover:bg-destructive/10 hover:text-destructive transition-colors"
+            title="Delete"
+          >
+            <Trash2Icon className="size-3.5" />
+          </button>
+        </div>
+      </div>
+      <div className="flex flex-col gap-1">
+        {entry.items.slice(0, 3).map((item, i) => (
+          <p key={i} className="text-xs text-muted-foreground flex gap-2 leading-relaxed">
+            <span className="text-muted-foreground/40 shrink-0 tabular-nums">{i + 1}.</span>
+            <span className="line-clamp-1">{item}</span>
+          </p>
+        ))}
+        {entry.items.length > 3 && (
+          <p className="text-[11px] text-muted-foreground/50 ml-5">
+            +{entry.items.length - 3} more
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function NewPromptListForm({ onClose, onRefresh }: { onClose: () => void; onRefresh: () => void }): ReactElement {
+  const [name, setName] = useState("");
+  const [items, setItems] = useState<string[]>(["", ""]);
+
+  const handleSave = useCallback(async () => {
+    const filtered = items.filter((t) => t.trim());
+    if (filtered.length === 0) return;
+    const ts = now();
+    await savePromptList({
+      id: newId(),
+      name: name.trim() || "Untitled List",
+      items: filtered,
+      createdAt: ts,
+      updatedAt: ts,
+    });
+    onRefresh();
+    onClose();
+  }, [name, items, onClose, onRefresh]);
+
+  const addItem = useCallback(() => setItems((prev) => [...prev, ""]), []);
+  const removeItem = useCallback(
+    (i: number) => setItems((prev) => prev.filter((_, idx) => idx !== i)),
+    [],
+  );
+  const updateItem = useCallback(
+    (i: number, val: string) =>
+      setItems((prev) => prev.map((v, idx) => (idx === i ? val : v))),
+    [],
+  );
+
+  return (
+    <div className="rounded-xl border border-border/50 bg-muted/30 p-4 flex flex-col gap-3">
+      <p className="text-xs font-semibold text-muted-foreground">New Prompt List</p>
+      <input
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        placeholder="List name..."
+        autoFocus
+        className="w-full rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow"
+      />
+      <p className="text-xs font-semibold text-muted-foreground">
+        Prompts — loaded into the composer one at a time
+      </p>
+      <div className="flex flex-col gap-2">
+        {items.map((item, i) => (
+          <div key={i} className="flex items-start gap-2">
+            <span className="text-xs font-medium text-muted-foreground/60 mt-2.5 w-5 shrink-0 text-right">{i + 1}.</span>
+            <textarea
+              value={item}
+              onChange={(e) => updateItem(i, e.target.value)}
+              rows={2}
+              placeholder={`Prompt ${i + 1}...`}
+              className="flex-1 resize-y rounded-lg border-0 bg-background/80 px-3 py-2 text-sm ring-1 ring-border/60 outline-none focus:ring-primary/50 transition-shadow leading-relaxed"
+            />
+            <button
+              type="button"
+              onClick={() => removeItem(i)}
+              disabled={items.length <= 1}
+              className="flex h-7 w-7 mt-1 items-center justify-center rounded-lg text-muted-foreground hover:bg-destructive/10 hover:text-destructive transition-colors shrink-0 disabled:opacity-30 disabled:cursor-not-allowed"
+              title="Remove"
+            >
+              <XIcon className="size-3.5" />
+            </button>
+          </div>
+        ))}
+      </div>
+      <button
+        type="button"
+        onClick={addItem}
+        className="flex items-center gap-1.5 text-xs font-medium text-primary hover:text-primary/80 transition-colors"
+      >
+        <PlusIcon className="size-3.5" />Add another prompt
+      </button>
+      <div className="flex gap-2 justify-end">
+        <Button size="sm" variant="ghost" onClick={onClose}>
+          <XIcon className="size-3.5 mr-1" />Cancel
+        </Button>
+        <Button
+          size="sm"
+          onClick={handleSave}
+          disabled={items.filter((t) => t.trim()).length === 0}
+        >
+          <CheckIcon className="size-3.5 mr-1" />Save Prompt List
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+type Tab = "prompts" | "lists";
+
+export function PromptStorageDialog({
+  open,
+  onOpenChange,
+  onUse,
+  onRunList,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onUse: (text: string) => void;
+  onRunList?: (items: string[]) => void;
+}): ReactElement {
+  const [activeTab, setActiveTab] = useState<Tab>("prompts");
+  const [showNewPrompt, setShowNewPrompt] = useState(false);
+  const [showNewList, setShowNewList] = useState(false);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [showSuggestions, setShowSuggestions] = useState(false);
+  const [exportCtx, setExportCtx] = useState<ExportModalCtx | null>(null);
+  const importRef = useRef<HTMLInputElement>(null);
+
+  const [promptEntries, setPromptEntries] = useState<PromptEntry[]>([]);
+  const [promptLists, setPromptLists] = useState<PromptListEntry[]>([]);
+
+  const refreshEntries = useCallback(async () => {
+    try { setPromptEntries(await listPromptEntries()); } catch {}
+  }, []);
+  const refreshLists = useCallback(async () => {
+    try { setPromptLists(await listPromptLists()); } catch {}
+  }, []);
+
+  useEffect(() => {
+    if (open) {
+      void refreshEntries();
+      void refreshLists();
+    }
+  }, [open, refreshEntries, refreshLists]);
+
+  useEffect(() => {
+    setSearchQuery("");
+    setShowSuggestions(false);
+    setShowNewPrompt(false);
+    setShowNewList(false);
+  }, [activeTab]);
+
+  const filteredPrompts = useMemo(() => {
+    const all = promptEntries ?? [];
+    if (!searchQuery.trim()) return all;
+    const q = searchQuery.toLowerCase();
+    return all.filter(
+      (e) => e.name.toLowerCase().includes(q) || e.text.toLowerCase().includes(q),
+    );
+  }, [promptEntries, searchQuery]);
+
+  const filteredLists = useMemo(() => {
+    const all = promptLists ?? [];
+    if (!searchQuery.trim()) return all;
+    const q = searchQuery.toLowerCase();
+    return all.filter((e) => e.name.toLowerCase().includes(q));
+  }, [promptLists, searchQuery]);
+
+  const suggestions = useMemo(() => {
+    if (!searchQuery.trim()) return [];
+    const q = searchQuery.toLowerCase();
+    const source: { name: string }[] =
+      activeTab === "prompts" ? (promptEntries ?? []) : (promptLists ?? []);
+    return source
+      .filter((e) => e.name.toLowerCase().includes(q))
+      .slice(0, 7)
+      .map((e) => e.name);
+  }, [searchQuery, activeTab, promptEntries, promptLists]);
+
+  const handleUsePrompt = useCallback(
+    (text: string) => {
+      onUse(text);
+      onOpenChange(false);
+    },
+    [onUse, onOpenChange],
+  );
+
+  const handleImportFile = useCallback(
+    async (e: React.ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0];
+      if (!file) return;
+      const text = await file.text();
+      const isCsv = file.name.toLowerCase().endsWith(".csv");
+      try {
+        // Collection JSONL: first line carries a "type" field.
+        if (!isCsv) {
+          const firstLine = text.split("\n").find((l) => l.trim());
+          if (firstLine) {
+            try {
+              const probe = JSON.parse(firstLine) as Record<string, unknown>;
+              if (probe.type === "prompt" || probe.type === "prompt_list") {
+                const result = await importCollectionFromText(text);
+                const total = result.prompts + result.lists;
+                void refreshEntries();
+                void refreshLists();
+                if (total > 0) {
+                  toast.success(`Imported ${total} item${total !== 1 ? "s" : ""}`, {
+                    description: `${result.prompts} prompt${result.prompts !== 1 ? "s" : ""}, ${result.lists} list${result.lists !== 1 ? "s" : ""}`,
+                  });
+                } else {
+                  toast.warning("No items imported", {
+                    description: "The file may be empty or in an unsupported format.",
+                  });
+                }
+                e.target.value = "";
+                return;
+              }
+            } catch {
+              /* */
+            }
+          }
+        }
+
+        let count = 0;
+        let skipped = 0;
+        if (activeTab === "prompts") {
+          ({ count, skipped } = await importPromptsFromText(text, isCsv));
+          void refreshEntries();
+        } else {
+          ({ count, skipped } = await importListsFromText(text, isCsv));
+          void refreshLists();
+        }
+        if (count > 0) {
+          toast.success(`Imported ${count} item${count !== 1 ? "s" : ""}`, {
+            description: skipped > 0 ? `${skipped} line${skipped !== 1 ? "s" : ""} skipped (unrecognised format)` : undefined,
+          });
+        } else {
+          toast.warning("No items imported", {
+            description: skipped > 0
+              ? `${skipped} line${skipped !== 1 ? "s" : ""} could not be parsed.`
+              : "The file may be empty or in an unsupported format.",
+          });
+        }
+      } catch {
+        toast.error("Import failed", { description: "Could not parse the file." });
+      }
+      e.target.value = "";
+    },
+    [activeTab, refreshEntries, refreshLists],
+  );
+
+  const bulkExportDisabled =
+    (activeTab === "prompts" ? (promptEntries?.length ?? 0) : (promptLists?.length ?? 0)) === 0;
+
+  const openBulkExport = useCallback(() => {
+    setExportCtx({
+      kind: "bulk",
+      tab: activeTab,
+      prompts: promptEntries ?? [],
+      lists: promptLists ?? [],
+    });
+  }, [activeTab, promptEntries, promptLists]);
+
+  return (
+    <>
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent showCloseButton={false} className="sm:max-w-[min(1100px,88vw)] max-h-[94vh] flex flex-col gap-0 p-0 overflow-hidden">
+          {/* */}
+          <DialogHeader className="px-6 pt-5 pb-4 shrink-0 border-b border-border/50">
+            <div className="flex items-center gap-3">
+              <div className="flex-1 min-w-0">
+                <DialogTitle className="text-base font-semibold tracking-tight">
+                  Prompt Storage
+                </DialogTitle>
+                <p className="mt-0.5 text-xs text-muted-foreground">
+                  Save and reuse prompts across conversations
+                </p>
+              </div>
+              <div className="flex items-center gap-2 shrink-0">
+                <input
+                  ref={importRef}
+                  type="file"
+                  accept=".jsonl,.json,.csv"
+                  className="hidden"
+                  onChange={handleImportFile}
+                />
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => importRef.current?.click()}
+                  className="h-8 gap-1.5 text-xs"
+                  title="Import from JSONL, CSV, or collection JSONL"
+                >
+                  <UploadIcon className="size-3.5" />
+                  Import
+                </Button>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  disabled={bulkExportDisabled}
+                  onClick={openBulkExport}
+                  className="h-8 gap-1.5 text-xs"
+                >
+                  <DownloadIcon className="size-3.5" />
+                  Export
+                </Button>
+                <div className="ml-1 h-5 w-px bg-border/60 shrink-0" />
+                <DialogClose asChild>
+                  <Button variant="ghost" size="icon-sm">
+                    <XIcon className="size-4" />
+                    <span className="sr-only">Close</span>
+                  </Button>
+                </DialogClose>
+              </div>
+            </div>
+            <DialogDescription className="sr-only">
+              Save and manage reusable prompts and prompt lists.
+            </DialogDescription>
+          </DialogHeader>
+
+          {/* */}
+          <div className="px-6 pt-4 pb-3 shrink-0 flex flex-col gap-3">
+            {/* */}
+            <div className="flex items-center gap-1 self-start rounded-lg bg-muted/60 p-1">
+              {(["prompts", "lists"] as Tab[]).map((tab) => (
+                <button
+                  key={tab}
+                  type="button"
+                  onClick={() => setActiveTab(tab)}
+                  className={cn(
+                    "rounded-md px-4 py-1.5 text-xs font-medium transition-all",
+                    activeTab === tab
+                      ? "bg-background text-foreground shadow-sm ring-1 ring-border/40"
+                      : "text-muted-foreground hover:text-foreground",
+                  )}
+                >
+                  {tab === "prompts" ? "Saved Prompts" : "Prompt Lists"}
+                </button>
+              ))}
+            </div>
+
+            {/* */}
+            <div className="relative">
+              <SearchIcon className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 size-3.5 text-muted-foreground/60" />
+              <input
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                onFocus={() => setShowSuggestions(true)}
+                onBlur={() => setTimeout(() => setShowSuggestions(false), 150)}
+                placeholder={`Search ${activeTab === "prompts" ? "prompts by name or text" : "prompt lists by name"}…`}
+                className="w-full rounded-lg border-0 bg-muted/50 pl-9 pr-3 py-2 text-sm outline-none focus:ring-1 focus:ring-primary/50 placeholder:text-muted-foreground/60 transition-shadow"
+              />
+              {showSuggestions && searchQuery.trim() !== "" && suggestions.length > 0 && (
+                <div className="absolute top-full left-0 right-0 z-50 mt-1 rounded-xl border border-border/60 bg-popover shadow-lg overflow-hidden">
+                  {suggestions.map((name) => (
+                    <button
+                      key={name}
+                      type="button"
+                      onMouseDown={(e) => e.preventDefault()}
+                      onClick={() => { setSearchQuery(name); setShowSuggestions(false); }}
+                      className="flex w-full items-center gap-2.5 px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground transition-colors text-left"
+                    >
+                      <SearchIcon className="size-3 shrink-0 text-muted-foreground/60" />
+                      <span className="truncate">{name}</span>
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          </div>
+
+          {/* */}
+          <div className="flex-1 min-h-0 overflow-y-auto px-6 pb-6 flex flex-col gap-2.5">
+            {activeTab === "prompts" && (
+              <>
+                {!showNewPrompt ? (
+                  <button
+                    type="button"
+                    onClick={() => setShowNewPrompt(true)}
+                    className="flex items-center gap-2.5 rounded-xl border-2 border-dashed border-border/40 px-4 py-3 text-sm font-medium text-muted-foreground hover:border-border hover:text-foreground hover:bg-muted/50 transition-all"
+                  >
+                    <PlusIcon className="size-4" />New Prompt
+                  </button>
+                ) : (
+                  <NewPromptForm onClose={() => setShowNewPrompt(false)} onRefresh={refreshEntries} />
+                )}
+
+                {filteredPrompts.length > 0 ? (
+                  filteredPrompts.map((entry) => (
+                    <PromptCard
+                      key={entry.id}
+                      entry={entry}
+                      onUse={handleUsePrompt}
+                      onExport={(e) => setExportCtx({ kind: "prompt", entry: e })}
+                      onRefresh={refreshEntries}
+                    />
+                  ))
+                ) : (
+                  !showNewPrompt && (
+                    <div className="flex flex-col items-center justify-center py-16 text-center gap-3">
+                      {searchQuery.trim() ? (
+                        <>
+                          <div className="flex size-12 items-center justify-center rounded-2xl bg-muted/60">
+                            <SearchIcon className="size-5 text-muted-foreground/40" />
+                          </div>
+                          <div className="flex flex-col gap-1">
+                            <p className="text-sm font-medium text-muted-foreground">
+                              No prompts match &ldquo;{searchQuery}&rdquo;
+                            </p>
+                            <button
+                              type="button"
+                              onClick={() => setSearchQuery("")}
+                              className="text-xs text-primary hover:underline"
+                            >
+                              Clear search
+                            </button>
+                          </div>
+                        </>
+                      ) : (
+                        <>
+                          <div className="flex size-12 items-center justify-center rounded-2xl bg-muted/60">
+                            <BookmarkIcon className="size-5 text-muted-foreground/40" />
+                          </div>
+                          <div className="flex flex-col gap-1">
+                            <p className="text-sm font-medium text-muted-foreground">No saved prompts yet</p>
+                            <p className="text-xs text-muted-foreground/60">
+                              Save prompts you use often for quick reuse
+                            </p>
+                          </div>
+                        </>
+                      )}
+                    </div>
+                  )
+                )}
+              </>
+            )}
+
+            {activeTab === "lists" && (
+              <>
+                {!showNewList ? (
+                  <button
+                    type="button"
+                    onClick={() => setShowNewList(true)}
+                    className="flex items-center gap-2.5 rounded-xl border-2 border-dashed border-border/40 px-4 py-3 text-sm font-medium text-muted-foreground hover:border-border hover:text-foreground hover:bg-muted/50 transition-all"
+                  >
+                    <PlusIcon className="size-4" />New Prompt List
+                  </button>
+                ) : (
+                  <NewPromptListForm onClose={() => setShowNewList(false)} onRefresh={refreshLists} />
+                )}
+
+                {filteredLists.length > 0 ? (
+                  filteredLists.map((entry) => (
+                    <PromptListCard
+                      key={entry.id}
+                      entry={entry}
+                      onRunList={onRunList}
+                      onExport={(e) => setExportCtx({ kind: "list", entry: e })}
+                      onRefresh={refreshLists}
+                    />
+                  ))
+                ) : (
+                  !showNewList && (
+                    <div className="flex flex-col items-center justify-center py-16 text-center gap-3">
+                      {searchQuery.trim() ? (
+                        <>
+                          <div className="flex size-12 items-center justify-center rounded-2xl bg-muted/60">
+                            <SearchIcon className="size-5 text-muted-foreground/40" />
+                          </div>
+                          <div className="flex flex-col gap-1">
+                            <p className="text-sm font-medium text-muted-foreground">
+                              No prompt lists match &ldquo;{searchQuery}&rdquo;
+                            </p>
+                            <button
+                              type="button"
+                              onClick={() => setSearchQuery("")}
+                              className="text-xs text-primary hover:underline"
+                            >
+                              Clear search
+                            </button>
+                          </div>
+                        </>
+                      ) : (
+                        <>
+                          <div className="flex size-12 items-center justify-center rounded-2xl bg-muted/60">
+                            <LayoutListIcon className="size-5 text-muted-foreground/40" />
+                          </div>
+                          <div className="flex flex-col gap-1">
+                            <p className="text-sm font-medium text-muted-foreground">No prompt lists yet</p>
+                            <p className="text-xs text-muted-foreground/60">
+                              A prompt list queues a sequence of prompts for quick reuse
+                            </p>
+                          </div>
+                        </>
+                      )}
+                    </div>
+                  )
+                )}
+              </>
+            )}
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      {exportCtx && (
+        <ExportModal ctx={exportCtx} onClose={() => setExportCtx(null)} />
+      )}
+    </>
+  );
+}
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index e54111862c..6919d5e7a5 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -27,28 +27,39 @@ import { getImageInputUnavailableReason } from "./utils/image-input-support";
 import { useAui } from "@assistant-ui/react";
 import {
   ArrowUpIcon,
-  CheckIcon,
   Columns2Icon,
   GlobeIcon,
   HeadphonesIcon,
+  MoreHorizontalIcon,
   PlusIcon,
   SquareIcon,
   XIcon,
 } from "lucide-react";
 import {
   AttachmentIcon,
+  Bookmark02Icon,
   CodeIcon,
   Download01Icon,
+  FileDatabaseIcon,
   Folder01Icon,
   FolderAddIcon,
   Image03Icon,
   McpServerIcon,
   PencilRulerIcon,
+  Tick02Icon,
 } from "@hugeicons/core-free-icons";
 import { useNavigate } from "@tanstack/react-router";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { toast } from "@/lib/toast";
+import {
+  PromptStorageDialog,
+  exportConversationShareGPT,
+  exportConversationRawJsonl,
+  exportConversationCsv,
+} from "./prompt-storage/prompt-storage-dialog";
+import { listPromptEntries, type PromptEntry } from "./api/prompts-api";
 import { McpComposerButton } from "./mcp-composer-button";
+import { KnowledgeBaseComposerButton } from "@/features/rag/components/knowledge-base-composer-button";
 import { NewProjectDialog } from "./components/new-project-dialog";
 import { useChatProjects } from "./hooks/use-chat-projects";
 import { loadModel, validateModel } from "./api/chat-api";
@@ -389,11 +400,15 @@ export function SharedComposer({
   model1,
   model2,
   onExitCompare,
+  model1ThreadId,
+  model2ThreadId,
 }: {
   handlesRef: CompareHandles;
   model1?: CompareModelSelection;
   model2?: CompareModelSelection;
   onExitCompare?: () => void;
+  model1ThreadId?: string;
+  model2ThreadId?: string;
 }): ReactElement {
   const navigate = useNavigate();
   // Exit compare: parent's restore handler, or fresh chat if opened by URL.
@@ -415,6 +430,26 @@ export function SharedComposer({
   const [dragging, setDragging] = useState(false);
   const [isComposing, setIsComposing] = useState(false);
   const [newProjectOpen, setNewProjectOpen] = useState(false);
+  const [promptStorageOpen, setPromptStorageOpen] = useState(false);
+  const [recentPrompts, setRecentPrompts] = useState<PromptEntry[]>([]);
+  const refreshRecentPrompts = useCallback(async () => {
+    try {
+      const rows = await listPromptEntries();
+      setRecentPrompts(
+        [...rows].sort((a, b) => b.updatedAt - a.updatedAt).slice(0, 3),
+      );
+    } catch {
+    }
+  }, []);
+  const [isQueueRunning, setIsQueueRunning] = useState(false);
+  const [queueProgress, setQueueProgress] = useState({ current: 0, total: 0 });
+  const queueRef = useRef<string[]>([]);
+  const queueIndexRef = useRef(0);
+  const isQueueRunningRef = useRef(false);
+  const prevRunningRef = useRef(false);
+  const prevComparingRef = useRef(false);
+  const compareStepSucceededRef = useRef(false);
+  const sendRef = useRef<(() => void) | null>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const composingRef = useRef(false);
   const stuckImeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -486,6 +521,13 @@ export function SharedComposer({
   const setWebFetchToolsEnabled = useChatRuntimeStore(
     (s) => s.setWebFetchToolsEnabled,
   );
+  const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
+  const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
+  const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
+  // Empty until a compare run; gates Export chat off.
+  const exportThreadIds = [model1ThreadId, model2ThreadId, activeThreadId].filter(
+    (id): id is string => Boolean(id),
+  );
   const lastOpenRouterChosenModel = useChatRuntimeStore(
     (s) => s.lastOpenRouterChosenModel,
   );
@@ -614,11 +656,15 @@ export function SharedComposer({
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
   const showWebFetchPill = supportsBuiltinWebFetch;
+  // Docs (RAG) pill is local-only: search_knowledge_base needs the local runtime.
+  const ragDisabled = !modelLoaded || isExternalModel || !supportsTools;
+  const showRagPill = !isExternalModel;
   // Above 4 pills, collapse to icons only to cut clutter. Compare, Search and
   // Code always show; the rest are conditional.
   const pillsCompact =
     3 +
       (showImagePill ? 1 : 0) +
+      (showRagPill && ragEnabled && !ragDisabled ? 1 : 0) +
       (showWebFetchPill ? 1 : 0) +
       (artifactsEnabled ? 1 : 0) +
       (mcpEnabledForChat ? 1 : 0) >
@@ -647,6 +693,55 @@ export function SharedComposer({
     return () => clearInterval(id);
   }, [handlesRef]);
 
+  function advanceQueue() {
+    const nextIndex = queueIndexRef.current + 1;
+    if (nextIndex >= queueRef.current.length) {
+      isQueueRunningRef.current = false;
+      setIsQueueRunning(false);
+      queueRef.current = [];
+      queueIndexRef.current = 0;
+      setQueueProgress({ current: 0, total: 0 });
+      toast.success("Prompt queue complete");
+      return;
+    }
+    queueIndexRef.current = nextIndex;
+    setQueueProgress({ current: nextIndex + 1, total: queueRef.current.length });
+    const next = queueRef.current[nextIndex];
+    toast(`Prompt ${nextIndex + 1} / ${queueRef.current.length}`, {
+      description: next.length > 80 ? next.slice(0, 80) + "…" : next,
+    });
+    setText(next);
+    setTimeout(() => { sendRef.current?.(); }, 100);
+  }
+
+  // Compare mode: advance the queue on cycle end, but stop on a failed step so we
+  // don't burn prompts on incomplete results.
+  useEffect(() => {
+    const wasComparing = prevComparingRef.current;
+    prevComparingRef.current = comparing;
+    if (!isQueueRunningRef.current || !wasComparing || comparing) return;
+    if (!compareStepSucceededRef.current) {
+      isQueueRunningRef.current = false;
+      setIsQueueRunning(false);
+      queueRef.current = [];
+      queueIndexRef.current = 0;
+      setQueueProgress({ current: 0, total: 0 });
+      toast.error("Prompt queue stopped", {
+        description: "A compare step failed — remaining prompts were not sent.",
+      });
+      return;
+    }
+    prevRunningRef.current = false;
+    advanceQueue();
+  }, [comparing]);
+
+  useEffect(() => {
+    const wasRunning = prevRunningRef.current;
+    prevRunningRef.current = running;
+    if (!isQueueRunningRef.current || !wasRunning || running || comparing) return;
+    advanceQueue();
+  }, [running, comparing]);
+
   // Auto-expand textarea up to 6 rows, then scroll (matches regular chat composer).
   useEffect(() => {
     const ta = textareaRef.current;
@@ -946,8 +1041,10 @@ export function SharedComposer({
           await done;
         }
 
+        compareStepSucceededRef.current = true;
         toast.success("Compare complete", { id: toastId, duration: 2000 });
       } catch (err) {
+        compareStepSucceededRef.current = false;
         toast.error("Compare failed", {
           id: toastId,
           description: err instanceof Error ? err.message : "Unknown error",
@@ -963,6 +1060,7 @@ export function SharedComposer({
       }
     }
   }
+  sendRef.current = send;
 
   function stop() {
     if (isDictating) stopDictation();
@@ -1018,6 +1116,41 @@ export function SharedComposer({
         addFiles(e.dataTransfer.files);
       }}
     >
+      <PromptStorageDialog
+        open={promptStorageOpen}
+        onOpenChange={setPromptStorageOpen}
+        onUse={(t) => {
+          setText(t);
+          requestAnimationFrame(() => textareaRef.current?.focus());
+        }}
+        onRunList={(items) => {
+          const filtered = items.filter((p) => p.trim());
+          if (!filtered.length) return;
+          const hasCompareHandles = Boolean(
+            handlesRef.current["model1"] || handlesRef.current["model2"],
+          );
+          const isGeneralizedCompare =
+            hasCompareHandles && Boolean(model1?.id && model2?.id);
+          if (hasCompareHandles && !isGeneralizedCompare) {
+            toast.error("Pick a model in each pane to compare", {
+              description:
+                "Use the model dropdown above each pane, then send your prompt.",
+            });
+            return;
+          }
+          setPromptStorageOpen(false);
+          queueRef.current = filtered;
+          queueIndexRef.current = 0;
+          isQueueRunningRef.current = true;
+          setIsQueueRunning(true);
+          setQueueProgress({ current: 1, total: filtered.length });
+          toast(`Prompt 1 / ${filtered.length}`, {
+            description: filtered[0].length > 80 ? filtered[0].slice(0, 80) + "…" : filtered[0],
+          });
+          setText(filtered[0]);
+          setTimeout(() => { sendRef.current?.(); }, 100);
+        }}
+      />
       {/* Gemini-style drop affordance, mirrored from the single composer. */}
       <div
         className={`pointer-events-none absolute inset-0 z-20 flex flex-col items-center justify-center gap-1 overflow-hidden rounded-[32px] bg-background/90 backdrop-blur-sm transition-opacity duration-150 dark:bg-card/90 ${dragging ? "opacity-100" : "opacity-0"}`}
@@ -1120,7 +1253,11 @@ export function SharedComposer({
           />
           {/* Same + menu as single-chat (ComposerToolsMenu), wired to the
               compare composer's own file/audio inputs and tools. */}
-          <DropdownMenu>
+          <DropdownMenu
+            onOpenChange={(open) => {
+              if (open) void refreshRecentPrompts();
+            }}
+          >
             <DropdownMenuTrigger asChild={true}>
               <button
                 type="button"
@@ -1170,7 +1307,11 @@ export function SharedComposer({
                 <GlobeIcon />
                 Web search
                 {toolsEnabled && !searchDisabled ? (
-                  <CheckIcon className="ml-auto" />
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
+                    className="ml-auto"
+                  />
                 ) : null}
               </DropdownMenuItem>
               <DropdownMenuItem
@@ -1189,7 +1330,11 @@ export function SharedComposer({
                 />
                 Code
                 {codeToolsEnabled && !codeDisabled ? (
-                  <CheckIcon className="ml-auto" />
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
+                    className="ml-auto"
+                  />
                 ) : null}
               </DropdownMenuItem>
               {showImagePill && (
@@ -1205,20 +1350,33 @@ export function SharedComposer({
                   <HugeiconsIcon icon={Image03Icon} strokeWidth={2} />
                   Images
                   {imageToolsEnabled && !imageDisabled ? (
-                    <CheckIcon className="ml-auto" />
+                    <HugeiconsIcon
+                      icon={Tick02Icon}
+                      strokeWidth={2}
+                      className="ml-auto"
+                    />
                   ) : null}
                 </DropdownMenuItem>
               )}
               <DropdownMenuSeparator />
               <DropdownMenuItem
+                disabled={ragDisabled}
                 className={
-                  artifactsEnabled ? "text-primary font-medium" : undefined
+                  ragEnabled && !ragDisabled
+                    ? "text-primary font-medium"
+                    : undefined
                 }
-                onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+                onSelect={() => setRagEnabled(!ragEnabled)}
               >
-                <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
-                Canvas
-                {artifactsEnabled ? <CheckIcon className="ml-auto" /> : null}
+                <HugeiconsIcon icon={FileDatabaseIcon} strokeWidth={2} />
+                RAG
+                {ragEnabled && !ragDisabled ? (
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
+                    className="ml-auto"
+                  />
+                ) : null}
               </DropdownMenuItem>
               <DropdownMenuItem
                 disabled={!supportsTools}
@@ -1229,7 +1387,13 @@ export function SharedComposer({
               >
                 <HugeiconsIcon icon={McpServerIcon} strokeWidth={2} />
                 MCP
-                {mcpEnabledForChat ? <CheckIcon className="ml-auto" /> : null}
+                {mcpEnabledForChat ? (
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
+                    className="ml-auto"
+                  />
+                ) : null}
               </DropdownMenuItem>
               {/* RAG hidden temporarily */}
               {/* Always active: this menu only renders in compare mode. Ticked
@@ -1240,8 +1404,98 @@ export function SharedComposer({
               >
                 <Columns2Icon />
                 Compare chat
-                <CheckIcon className="ml-auto" />
+                <HugeiconsIcon
+                  icon={Tick02Icon}
+                  strokeWidth={2}
+                  className="ml-auto"
+                />
               </DropdownMenuItem>
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger>
+                  <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
+                  Saved prompts
+                </DropdownMenuSubTrigger>
+                <DropdownMenuSubContent className="unsloth-plus-menu w-[176px]">
+                  {recentPrompts.map((p) => (
+                    <DropdownMenuItem
+                      key={p.id}
+                      onSelect={() => {
+                        setText(p.text);
+                        requestAnimationFrame(() =>
+                          textareaRef.current?.focus(),
+                        );
+                      }}
+                    >
+                      <span className="truncate">{p.name}</span>
+                    </DropdownMenuItem>
+                  ))}
+                  {recentPrompts.length > 0 ? <DropdownMenuSeparator /> : null}
+                  <DropdownMenuItem onSelect={() => setPromptStorageOpen(true)}>
+                    All saved prompts…
+                  </DropdownMenuItem>
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+              {/* Top-level: a third-level submenu collision-flips at narrow
+                  widths and is awkward to reach. */}
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger disabled={exportThreadIds.length === 0}>
+                  <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
+                  Export chat
+                </DropdownMenuSubTrigger>
+                <DropdownMenuSubContent
+                  collisionPadding={16}
+                  className="unsloth-plus-menu w-[176px]"
+                >
+                  {[
+                    { label: "Raw JSONL", fn: exportConversationRawJsonl },
+                    { label: "CSV", fn: exportConversationCsv },
+                    {
+                      label: "ShareGPT JSONL",
+                      fn: exportConversationShareGPT,
+                    },
+                  ].map(({ label, fn }) => (
+                    <DropdownMenuItem
+                      key={label}
+                      disabled={exportThreadIds.length === 0}
+                      onSelect={() => {
+                        if (!exportThreadIds.length) {
+                          toast.error("No conversation to export yet.");
+                          return;
+                        }
+                        Promise.all(exportThreadIds.map((id) => fn(id))).catch(
+                          () => toast.error("Export failed."),
+                        );
+                      }}
+                    >
+                      {label}
+                    </DropdownMenuItem>
+                  ))}
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+              <DropdownMenuSub>
+                <DropdownMenuSubTrigger>
+                  <MoreHorizontalIcon className="size-4" />
+                  More
+                </DropdownMenuSubTrigger>
+                <DropdownMenuSubContent className="unsloth-plus-menu w-[200px]">
+                  <DropdownMenuItem
+                    className={
+                      artifactsEnabled ? "text-primary font-medium" : undefined
+                    }
+                    onSelect={() => setArtifactsEnabled(!artifactsEnabled)}
+                  >
+                    <HugeiconsIcon icon={PencilRulerIcon} strokeWidth={2} />
+                    Canvas
+                    {artifactsEnabled ? (
+                      <HugeiconsIcon
+                        icon={Tick02Icon}
+                        strokeWidth={2}
+                        className="ml-auto"
+                      />
+                    ) : null}
+                  </DropdownMenuItem>
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
               <DropdownMenuSeparator />
               <DropdownMenuSub>
                 <DropdownMenuSubTrigger>
@@ -1358,6 +1612,7 @@ export function SharedComposer({
               <span>Images</span>
             </button>
           )}
+          {showRagPill && <KnowledgeBaseComposerButton side="top" />}
           {showWebFetchPill && (
             <button
               type="button"
@@ -1445,7 +1700,9 @@ export function SharedComposer({
                             setPreserveThinking(false);
                           }}
                         >
-                          <CheckIcon
+                          <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                             className={cn(
                               "unsloth-tick size-4",
                               effectiveReasoningVisualEnabled && "opacity-0",
@@ -1474,7 +1731,9 @@ export function SharedComposer({
                               }
                             }}
                           >
-                            <CheckIcon
+                            <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                               className={cn(
                                 "unsloth-tick size-4",
                                 !(
@@ -1505,7 +1764,9 @@ export function SharedComposer({
                           }
                         }}
                       >
-                        <CheckIcon
+                        <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                           className={cn(
                             "unsloth-tick size-4",
                             !effectiveReasoningEnabled && "opacity-0",
@@ -1529,7 +1790,9 @@ export function SharedComposer({
                         }
                       }}
                     >
-                      <CheckIcon
+                      <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
                         className={cn(
                           "unsloth-tick size-4",
                           !preserveThinking && "opacity-0",
@@ -1606,7 +1869,26 @@ export function SharedComposer({
               )}
             </>
           )}
-          {busy ? (
+          {isQueueRunning ? (
+            <button
+              type="button"
+              onClick={() => {
+                isQueueRunningRef.current = false;
+                setIsQueueRunning(false);
+                queueRef.current = [];
+                queueIndexRef.current = 0;
+                setQueueProgress({ current: 0, total: 0 });
+                stop();
+              }}
+              aria-label="Stop prompt queue"
+              className="ml-1.5 flex items-center gap-1.5 rounded-full border border-border/60 bg-muted/60 px-2.5 py-1 text-xs font-semibold text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+            >
+              <SquareIcon className="size-2.5 shrink-0 fill-current" />
+              <span className="tabular-nums">
+                Stop queue {queueProgress.current}/{queueProgress.total}
+              </span>
+            </button>
+          ) : busy ? (
             <Button
               type="button"
               variant="default"
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index ebaa756501..f9fb2abe2b 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -36,6 +36,93 @@ export const CHAT_ALLOW_ARTIFACT_NETWORK_ACCESS_KEY =
 export const CHAT_MCP_ENABLED_KEY = "unsloth_chat_mcp_enabled";
 export const CHAT_WEB_FETCH_TOOLS_ENABLED_KEY =
   "unsloth_chat_web_fetch_tools_enabled";
+export const CHAT_RAG_ENABLED_KEY = "unsloth_chat_rag_enabled";
+export const CHAT_RAG_SOURCE_KEY = "unsloth_chat_rag_source";
+export const CHAT_RAG_MODE_KEY = "unsloth_chat_rag_mode";
+export const CHAT_RAG_TOP_K_KEY = "unsloth_chat_rag_top_k";
+export const CHAT_RAG_AUTOINJECT_KEY = "unsloth_chat_rag_autoinject";
+export const CHAT_RAG_AUTOINJECT_MIN_SCORE_KEY =
+  "unsloth_chat_rag_autoinject_min_score";
+
+export type RagSource =
+  | { type: "thread" }
+  | { type: "kb"; kbId: string };
+
+export type RagMode = "hybrid" | "lexical" | "dense";
+
+export const DEFAULT_RAG_SOURCE: RagSource = { type: "thread" };
+export const DEFAULT_RAG_MODE: RagMode = "hybrid";
+export const DEFAULT_RAG_TOP_K = 5;
+// `auto` forces retrieval for smaller models (<=9B); `on`/`off` force it.
+export type RagAutoInject = "auto" | "on" | "off";
+export const DEFAULT_RAG_AUTOINJECT: RagAutoInject = "auto";
+export const DEFAULT_RAG_AUTOINJECT_MIN_SCORE = 0.7;
+
+function loadRagSource(): RagSource {
+  if (typeof window === "undefined") return DEFAULT_RAG_SOURCE;
+  try {
+    const raw = window.localStorage.getItem(CHAT_RAG_SOURCE_KEY);
+    if (!raw) return DEFAULT_RAG_SOURCE;
+    const parsed = JSON.parse(raw) as RagSource;
+    if (parsed?.type === "kb" && typeof parsed.kbId === "string") {
+      return { type: "kb", kbId: parsed.kbId };
+    }
+    if (parsed?.type === "thread") return { type: "thread" };
+    return DEFAULT_RAG_SOURCE;
+  } catch {
+    return DEFAULT_RAG_SOURCE;
+  }
+}
+
+function saveRagSource(value: RagSource): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(CHAT_RAG_SOURCE_KEY, JSON.stringify(value));
+  } catch {
+  }
+}
+
+function loadRagMode(): RagMode {
+  const raw = loadString(CHAT_RAG_MODE_KEY, DEFAULT_RAG_MODE);
+  return raw === "lexical" || raw === "dense" ? raw : "hybrid";
+}
+
+function loadRagAutoInject(): RagAutoInject {
+  const raw = loadString(CHAT_RAG_AUTOINJECT_KEY, DEFAULT_RAG_AUTOINJECT);
+  if (raw === "auto" || raw === "on" || raw === "off") return raw;
+  // Legacy boolean migration: false -> Off, else Auto.
+  return raw === "false" ? "off" : "auto";
+}
+
+function loadRagTopK(): number {
+  if (typeof window === "undefined") return DEFAULT_RAG_TOP_K;
+  try {
+    const raw = window.localStorage.getItem(CHAT_RAG_TOP_K_KEY);
+    if (raw === null) return DEFAULT_RAG_TOP_K;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_RAG_TOP_K;
+  } catch {
+    return DEFAULT_RAG_TOP_K;
+  }
+}
+
+// Preserves a stored 0 (score floors can legitimately be 0).
+function loadRagNumber(
+  key: string,
+  fallback: number,
+  { min, max, integer = false }: { min: number; max: number; integer?: boolean },
+): number {
+  if (typeof window === "undefined") return fallback;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (raw === null) return fallback;
+    const parsed = integer ? Number.parseInt(raw, 10) : Number.parseFloat(raw);
+    if (!Number.isFinite(parsed)) return fallback;
+    return Math.min(max, Math.max(min, parsed));
+  } catch {
+    return fallback;
+  }
+}
 
 // External provider selection is encoded into `params.checkpoint` as
 // `external::<providerId>::<modelId>`. PersistedChatSettings omits `checkpoint`
@@ -309,6 +396,13 @@ type ChatRuntimeStore = {
   collapseHtmlArtifacts: boolean;
   allowArtifactNetworkAccess: boolean;
   mcpEnabledForChat: boolean;
+  ragEnabled: boolean;
+  ragSource: RagSource;
+  ragMode: RagMode;
+  ragTopK: number;
+  // autoInject = forced first-pass retrieval before answering.
+  ragAutoInject: RagAutoInject;
+  ragAutoInjectMinScore: number;
   /**
    * Fetch pill state, independent of `toolsEnabled` (Search). Only
    * consulted when `providerSupportsBuiltinWebFetch` is true.
@@ -386,6 +480,12 @@ type ChatRuntimeStore = {
   setAllowArtifactNetworkAccess: (enabled: boolean) => void;
   setMcpEnabledForChat: (enabled: boolean) => void;
   setWebFetchToolsEnabled: (enabled: boolean) => void;
+  setRagEnabled: (enabled: boolean, options?: { persist?: boolean }) => void;
+  setRagSource: (source: RagSource) => void;
+  setRagMode: (mode: RagMode) => void;
+  setRagTopK: (topK: number) => void;
+  setRagAutoInject: (value: RagAutoInject) => void;
+  setRagAutoInjectMinScore: (score: number) => void;
   setToolStatus: (status: string | null) => void;
   setGeneratingStatus: (status: string | null) => void;
   setAutoHealToolCalls: (enabled: boolean) => void;
@@ -646,6 +746,16 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   ),
   mcpEnabledForChat: loadBool(CHAT_MCP_ENABLED_KEY, false),
   webFetchToolsEnabled: loadBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, false),
+  ragEnabled: loadBool(CHAT_RAG_ENABLED_KEY, false),
+  ragSource: loadRagSource(),
+  ragMode: loadRagMode(),
+  ragTopK: loadRagTopK(),
+  ragAutoInject: loadRagAutoInject(),
+  ragAutoInjectMinScore: loadRagNumber(
+    CHAT_RAG_AUTOINJECT_MIN_SCORE_KEY,
+    DEFAULT_RAG_AUTOINJECT_MIN_SCORE,
+    { min: 0, max: 1 },
+  ),
   toolStatus: null,
   generatingStatus: null,
   autoHealToolCalls: true,
@@ -860,6 +970,8 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       artifactsEnabled: false,
       mcpEnabledForChat: false,
       webFetchToolsEnabled: false,
+      // Only the per-session enable pill resets; source/mode/top_k persist.
+      ragEnabled: false,
       toolStatus: null,
       kvCacheDtype: null,
       loadedKvCacheDtype: null,
@@ -960,6 +1072,41 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       saveBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, webFetchToolsEnabled);
       return { webFetchToolsEnabled };
     }),
+  setRagEnabled: (ragEnabled, options) =>
+    set(() => {
+      if (options?.persist !== false) {
+        saveBool(CHAT_RAG_ENABLED_KEY, ragEnabled);
+      }
+      return { ragEnabled };
+    }),
+  setRagSource: (ragSource) =>
+    set(() => {
+      saveRagSource(ragSource);
+      return { ragSource };
+    }),
+  setRagMode: (ragMode) =>
+    set(() => {
+      saveString(CHAT_RAG_MODE_KEY, ragMode);
+      return { ragMode };
+    }),
+  setRagTopK: (ragTopK) =>
+    set(() => {
+      saveString(CHAT_RAG_TOP_K_KEY, String(ragTopK));
+      return { ragTopK };
+    }),
+  setRagAutoInject: (ragAutoInject) =>
+    set(() => {
+      saveString(CHAT_RAG_AUTOINJECT_KEY, ragAutoInject);
+      return { ragAutoInject };
+    }),
+  setRagAutoInjectMinScore: (ragAutoInjectMinScore) =>
+    set(() => {
+      saveString(
+        CHAT_RAG_AUTOINJECT_MIN_SCORE_KEY,
+        String(ragAutoInjectMinScore),
+      );
+      return { ragAutoInjectMinScore };
+    }),
   setToolStatus: (toolStatus) => set({ toolStatus }),
   setGeneratingStatus: (generatingStatus) => set({ generatingStatus }),
   setAutoHealToolCalls: (autoHealToolCalls) =>
diff --git a/studio/frontend/src/features/chat/thread-sidebar.tsx b/studio/frontend/src/features/chat/thread-sidebar.tsx
index 320668a61c..2b255c6c14 100644
--- a/studio/frontend/src/features/chat/thread-sidebar.tsx
+++ b/studio/frontend/src/features/chat/thread-sidebar.tsx
@@ -1,30 +1,80 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
+import { useState } from "react";
 import {
   SidebarContent,
   SidebarFooter,
   SidebarGroup,
   SidebarGroupContent,
-  SidebarGroupLabel,
   SidebarHeader,
   SidebarMenu,
   SidebarMenuAction,
   SidebarMenuButton,
   SidebarMenuItem,
 } from "@/components/ui/sidebar";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
 import {
   BookOpen02Icon,
   ColumnInsertIcon,
   Delete02Icon,
+  Download01Icon,
+  MoreHorizontalIcon,
   NewReleasesIcon,
   PencilEdit02Icon,
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
+import { toast } from "sonner";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
 import type { ChatView } from "./types";
-import { deleteChatItem, useChatSidebarItems } from "./hooks/use-chat-sidebar-items";
+import {
+  deleteChatItem,
+  renameChatItem,
+  useChatSidebarItems,
+} from "./hooks/use-chat-sidebar-items";
 import type { SidebarItem } from "./hooks/use-chat-sidebar-items";
+import {
+  exportConversationRawJsonl,
+  exportConversationCsv,
+  exportConversationShareGPT,
+  exportBulkConversationsMerged,
+  exportBulkConversationsSeparate,
+  EXPORT_FORMATS_LIST,
+  type ConvExportFormat,
+} from "./prompt-storage/prompt-storage-dialog";
+import {
+  listStoredChatThreads,
+} from "./utils/chat-history-storage";
+
+const EXPORT_FORMATS = [
+  { label: "Raw JSONL", fn: exportConversationRawJsonl },
+  { label: "CSV", fn: exportConversationCsv },
+  { label: "ShareGPT JSONL", fn: exportConversationShareGPT },
+] as const;
+
+async function getThreadIdsForItem(item: SidebarItem): Promise<string[]> {
+  if (item.type === "single") return [item.id];
+  const threads = await listStoredChatThreads({ pairId: item.id });
+  return threads.map((t) => t.id);
+}
 
 export function ThreadSidebar({
   view,
@@ -48,6 +98,9 @@ export function ThreadSidebar({
         ? view.pairId
         : view.projectId;
 
+  const [renamingItem, setRenamingItem] = useState<SidebarItem | null>(null);
+  const [renameDraft, setRenameDraft] = useState("");
+
   function viewForItem(item: SidebarItem): ChatView {
     return item.type === "single"
       ? { mode: "single", threadId: item.id }
@@ -55,12 +108,65 @@ export function ThreadSidebar({
   }
 
   async function handleDelete(item: SidebarItem) {
-    // Directly set a new view with a nonce rather than going through
-    // onNewThread(), which may return early if the guard sees no
-    // threadId and no activeThreadId (after we just cleared it).
     await deleteChatItem(item, activeId ?? undefined, onSelect);
   }
 
+  function openRename(item: SidebarItem) {
+    setRenameDraft(item.title);
+    setRenamingItem(item);
+  }
+
+  async function commitRename() {
+    if (!renamingItem) return;
+    try {
+      await renameChatItem(renamingItem, renameDraft);
+    } catch {
+      toast.error("Failed to rename chat.");
+    } finally {
+      setRenamingItem(null);
+    }
+  }
+
+  async function handleExport(
+    item: SidebarItem,
+    fn: (threadId: string) => Promise<void>,
+  ) {
+    try {
+      const ids = await getThreadIdsForItem(item);
+      await Promise.all(ids.map((id) => fn(id)));
+    } catch {
+      toast.error("Export failed.");
+    }
+  }
+
+  async function getBulkThreadIds(scope: "recents" | "all"): Promise<string[]> {
+    const threads = await listStoredChatThreads({
+      includeArchived: false,
+      ...(scope === "recents" ? { projectId: null } : {}),
+    });
+    return [...new Set(threads.map((t) => t.id))];
+  }
+
+  async function handleBulkExport(
+    scope: "recents" | "all",
+    fmt: ConvExportFormat,
+    merged: boolean,
+  ) {
+    try {
+      const ids = await getBulkThreadIds(scope);
+      if (ids.length === 0) { toast.info("No conversations to export."); return; }
+      const ts = new Date().toISOString().slice(0, 10);
+      const basename = `${scope === "all" ? "all-chats" : "recents"}-${ts}`;
+      if (merged) {
+        await exportBulkConversationsMerged(ids, fmt, basename);
+      } else {
+        await exportBulkConversationsSeparate(ids, fmt, basename);
+      }
+    } catch {
+      toast.error("Export failed.");
+    }
+  }
+
   return (
     <>
       <SidebarHeader className="px-4 py-3">
@@ -88,7 +194,61 @@ export function ThreadSidebar({
           </SidebarGroupContent>
         </SidebarGroup>
         <SidebarGroup className="flex-1 px-4">
-          <SidebarGroupLabel className="text-xs font-medium text-muted-foreground/80">Your Chats</SidebarGroupLabel>
+          {/* Recents label with export-all menu */}
+          <div className="flex items-center justify-between px-2 py-1.5">
+            <span className="text-xs font-medium text-muted-foreground/80">Recents</span>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <button
+                  type="button"
+                  className="flex items-center justify-center rounded-sm p-0.5 text-muted-foreground hover:bg-accent focus:outline-none focus-visible:ring-0"
+                  title="Export options"
+                >
+                  <HugeiconsIcon icon={MoreHorizontalIcon} className="size-3.5" />
+                </button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent side="bottom" align="end" className="w-56">
+                <DropdownMenuSub>
+                  <DropdownMenuSubTrigger>
+                    <HugeiconsIcon icon={Download01Icon} className="mr-2 size-4" />
+                    Export Recents
+                  </DropdownMenuSubTrigger>
+                  <DropdownMenuSubContent avoidCollisions={false} className="w-52">
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                      <DropdownMenuItem key={`r-m-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, true)}>
+                        {label} — combined
+                      </DropdownMenuItem>
+                    ))}
+                    <DropdownMenuSeparator />
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                      <DropdownMenuItem key={`r-s-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, false)}>
+                        {label} — per chat
+                      </DropdownMenuItem>
+                    ))}
+                  </DropdownMenuSubContent>
+                </DropdownMenuSub>
+                <DropdownMenuSub>
+                  <DropdownMenuSubTrigger>
+                    <HugeiconsIcon icon={Download01Icon} className="mr-2 size-4" />
+                    Export Recents + Projects
+                  </DropdownMenuSubTrigger>
+                  <DropdownMenuSubContent avoidCollisions={false} className="w-52">
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                      <DropdownMenuItem key={`a-m-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, true)}>
+                        {label} — combined
+                      </DropdownMenuItem>
+                    ))}
+                    <DropdownMenuSeparator />
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
+                      <DropdownMenuItem key={`a-s-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, false)}>
+                        {label} — per chat
+                      </DropdownMenuItem>
+                    ))}
+                  </DropdownMenuSubContent>
+                </DropdownMenuSub>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
           <SidebarGroupContent>
             <SidebarMenu>
               {items.map((item) => (
@@ -99,13 +259,44 @@ export function ThreadSidebar({
                   >
                     <span>{item.title}</span>
                   </SidebarMenuButton>
-                  <SidebarMenuAction
-                    showOnHover={true}
-                    onClick={() => handleDelete(item)}
-                    title="Delete"
-                  >
-                    <HugeiconsIcon icon={Delete02Icon} />
-                  </SidebarMenuAction>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <SidebarMenuAction showOnHover className="focus:outline-none focus-visible:ring-0" onClick={(e) => e.stopPropagation()}>
+                        <HugeiconsIcon icon={MoreHorizontalIcon} className="size-4" />
+                        <span className="sr-only">More options</span>
+                      </SidebarMenuAction>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent side="bottom" align="end" className="w-44">
+                      <DropdownMenuItem onSelect={() => openRename(item)}>
+                        <HugeiconsIcon icon={PencilEdit02Icon} className="mr-2 size-4" />
+                        Rename
+                      </DropdownMenuItem>
+                      <DropdownMenuSub>
+                        <DropdownMenuSubTrigger>
+                          <HugeiconsIcon icon={Download01Icon} className="mr-2 size-4" />
+                          Export
+                        </DropdownMenuSubTrigger>
+                        <DropdownMenuSubContent avoidCollisions={false} className="w-52">
+                          {EXPORT_FORMATS.map(({ label, fn }) => (
+                            <DropdownMenuItem
+                              key={label}
+                              onSelect={() => handleExport(item, fn)}
+                            >
+                              {label}
+                            </DropdownMenuItem>
+                          ))}
+                        </DropdownMenuSubContent>
+                      </DropdownMenuSub>
+                      <DropdownMenuSeparator />
+                      <DropdownMenuItem
+                        className="text-destructive focus:text-destructive"
+                        onSelect={() => void handleDelete(item)}
+                      >
+                        <HugeiconsIcon icon={Delete02Icon} className="mr-2 size-4" />
+                        Delete
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
                 </SidebarMenuItem>
               ))}
             </SidebarMenu>
@@ -137,6 +328,30 @@ export function ThreadSidebar({
           <span>What&apos;s new</span>
         </a>
       </SidebarFooter>
+
+      {/* Rename dialog */}
+      <Dialog open={renamingItem !== null} onOpenChange={(open) => { if (!open) setRenamingItem(null); }}>
+        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>Rename chat</DialogTitle>
+          </DialogHeader>
+          <Input
+            value={renameDraft}
+            onChange={(e) => setRenameDraft(e.target.value)}
+            onKeyDown={(e) => { if (e.key === "Enter") void commitRename(); }}
+            autoFocus
+          />
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setRenamingItem(null)}>Cancel</Button>
+            <Button
+              onClick={() => void commitRename()}
+              disabled={!renameDraft.trim() || renameDraft.trim() === renamingItem?.title}
+            >
+              Rename
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </>
   );
 }
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index a69c216891..49524c17b4 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -274,6 +274,17 @@ export interface OpenAIChatCompletionsRequest {
   preserve_thinking?: boolean | null;
   enable_tools?: boolean | null;
   enabled_tools?: string[];
+  /** Local models + enable_tools only. */
+  mcp_enabled?: boolean;
+  /** Exactly one of `kb_id` (a KB) or `thread_id` (thread docs). */
+  rag_scope?: {
+    kb_id?: string;
+    thread_id?: string;
+    default_top_k: number;
+    mode: "hybrid" | "lexical" | "dense";
+    autoinject?: boolean;
+    autoinject_min_score?: number;
+  };
   auto_heal_tool_calls?: boolean;
   max_tool_calls_per_message?: number;
   tool_call_timeout?: number;
diff --git a/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx b/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
index 8e15fc6195..f42b83d14a 100644
--- a/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
+++ b/studio/frontend/src/features/onboarding/components/steps/model-selection-step.tsx
@@ -41,6 +41,7 @@ import {
   useHfTokenValidation,
   useInfiniteScroll,
 } from "@/hooks";
+import { extractParamLabel } from "@/lib/model-size";
 import { formatCompact } from "@/lib/utils";
 import {
   type TrainingMethod as VramTrainingMethod,
@@ -58,13 +59,6 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useShallow } from "zustand/react/shallow";
 
-/** Extract param count label from model name (e.g. "Qwen3-0.6B" -> "0.6B"). */
-function extractParamLabel(id: string): string | null {
-  const name = id.split("/").pop() ?? id;
-  const match = name.match(/(?:^|[-_])(\d+(?:\.\d+)?)[Bb](?:[-_]|$)/);
-  return match ? `${match[1]}B` : null;
-}
-
 export function ModelSelectionStep() {
   const gpu = useGpuInfo();
   const {
diff --git a/studio/frontend/src/features/rag/api/rag-api.ts b/studio/frontend/src/features/rag/api/rag-api.ts
new file mode 100644
index 0000000000..a72371cdd2
--- /dev/null
+++ b/studio/frontend/src/features/rag/api/rag-api.ts
@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+import { formatFastApiDetail } from "@/lib/format-fastapi-error";
+import type {
+  DocumentUploadResult,
+  IndexJob,
+  JobEvent,
+  KnowledgeBase,
+  PreviewTarget,
+  RagDocument,
+} from "../types/rag";
+
+const RAG_BASE = "/api/rag";
+
+function parseErrorText(status: number, body: unknown): string {
+  if (body && typeof body === "object") {
+    const { detail, message } = body as { detail?: unknown; message?: unknown };
+    const formatted = formatFastApiDetail(detail);
+    if (formatted) return formatted;
+    if (typeof message === "string" && message) return message;
+  }
+  return `Request failed (${status})`;
+}
+
+async function ragRequest<T>(
+  path: string,
+  init?: { method?: string; body?: object },
+): Promise<T> {
+  const response = await authFetch(`${RAG_BASE}${path}`, {
+    method: init?.method,
+    headers: init?.body ? { "Content-Type": "application/json" } : undefined,
+    body: init?.body ? JSON.stringify(init.body) : undefined,
+  });
+  if (response.status === 204) return undefined as T;
+  const json = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(parseErrorText(response.status, json));
+  return json as T;
+}
+
+async function ragUpload(path: string, file: File): Promise<DocumentUploadResult> {
+  const form = new FormData();
+  form.append("file", file);
+  // No Content-Type: let the browser set the multipart boundary.
+  const response = await authFetch(`${RAG_BASE}${path}`, {
+    method: "POST",
+    body: form,
+  });
+  const json = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(parseErrorText(response.status, json));
+  return json as DocumentUploadResult;
+}
+
+export async function listKnowledgeBases(): Promise<KnowledgeBase[]> {
+  const data = await ragRequest<{ knowledgeBases: KnowledgeBase[] }>(
+    "/knowledge-bases",
+  );
+  return data.knowledgeBases ?? [];
+}
+
+export function createKnowledgeBase(payload: {
+  name: string;
+  description?: string;
+}): Promise<{ id: string; name: string }> {
+  return ragRequest("/knowledge-bases", {
+    method: "POST",
+    body: {
+      name: payload.name,
+      ...(payload.description ? { description: payload.description } : {}),
+    },
+  });
+}
+
+export function updateKnowledgeBase(
+  kbId: string,
+  payload: { name?: string; description?: string },
+): Promise<{ ok: boolean }> {
+  const body: Record<string, unknown> = {};
+  if (payload.name !== undefined) body.name = payload.name;
+  if (payload.description !== undefined) body.description = payload.description;
+  return ragRequest(`/knowledge-bases/${encodeURIComponent(kbId)}`, {
+    method: "PATCH",
+    body,
+  });
+}
+
+export function deleteKnowledgeBase(kbId: string): Promise<{ ok: boolean }> {
+  return ragRequest(`/knowledge-bases/${encodeURIComponent(kbId)}`, {
+    method: "DELETE",
+  });
+}
+
+export async function listKnowledgeBaseDocuments(
+  kbId: string,
+): Promise<RagDocument[]> {
+  const data = await ragRequest<{ documents: RagDocument[] }>(
+    `/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
+  );
+  return data.documents ?? [];
+}
+
+export function uploadKnowledgeBaseDocument(
+  kbId: string,
+  file: File,
+): Promise<DocumentUploadResult> {
+  return ragUpload(
+    `/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
+    file,
+  );
+}
+
+export async function listThreadDocuments(
+  threadId: string,
+): Promise<RagDocument[]> {
+  const data = await ragRequest<{ documents: RagDocument[] }>(
+    `/threads/${encodeURIComponent(threadId)}/documents`,
+  );
+  return data.documents ?? [];
+}
+
+export function uploadThreadDocument(
+  threadId: string,
+  file: File,
+): Promise<DocumentUploadResult> {
+  return ragUpload(`/threads/${encodeURIComponent(threadId)}/documents`, file);
+}
+
+export function deleteDocument(documentId: string): Promise<{ ok: boolean }> {
+  return ragRequest(`/documents/${encodeURIComponent(documentId)}`, {
+    method: "DELETE",
+  });
+}
+
+export function getJob(jobId: string): Promise<IndexJob> {
+  return ragRequest(`/jobs/${encodeURIComponent(jobId)}`);
+}
+
+// SSE; returns on [DONE]. Transport errors propagate so callers can poll getJob.
+export async function* streamJobEvents(
+  jobId: string,
+  signal?: AbortSignal,
+): AsyncGenerator<JobEvent> {
+  const response = await authFetch(
+    `${RAG_BASE}/jobs/${encodeURIComponent(jobId)}/events`,
+    signal ? { signal } : undefined,
+  );
+  if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    throw new Error(parseErrorText(response.status, body));
+  }
+  if (!response.body) throw new Error("Stream response missing body");
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    let separatorIndex = buffer.search(/\r?\n\r?\n/);
+    while (separatorIndex >= 0) {
+      const rawEvent = buffer.slice(0, separatorIndex);
+      const separatorLength = buffer[separatorIndex] === "\r" ? 4 : 2;
+      buffer = buffer.slice(separatorIndex + separatorLength);
+
+      const dataLines: string[] = [];
+      for (const line of rawEvent.split(/\r?\n/)) {
+        if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+      }
+      if (dataLines.length > 0) {
+        const dataText = dataLines.join("\n");
+        if (dataText === "[DONE]") return;
+        try {
+          yield JSON.parse(dataText) as JobEvent;
+        } catch {
+          // Ignore unparseable frames; [DONE] still ends the loop.
+        }
+      }
+      separatorIndex = buffer.search(/\r?\n\r?\n/);
+    }
+  }
+}
+
+export function getPreviewTarget(
+  documentId: string,
+  chunkId?: string,
+): Promise<PreviewTarget> {
+  const qs = chunkId ? `?chunk_id=${encodeURIComponent(chunkId)}` : "";
+  return ragRequest(
+    `/documents/${encodeURIComponent(documentId)}/preview-target${qs}`,
+  );
+}
+
+// Signed URL (no bearer) so pdf.js can issue Range requests.
+export async function getDocumentFileUrl(documentId: string): Promise<string> {
+  const data = await ragRequest<{ url: string }>(
+    `/documents/${encodeURIComponent(documentId)}/file-url`,
+  );
+  return data.url;
+}
diff --git a/studio/frontend/src/features/rag/components/document-preview-mount.tsx b/studio/frontend/src/features/rag/components/document-preview-mount.tsx
new file mode 100644
index 0000000000..400ee5db00
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/document-preview-mount.tsx
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { Suspense, lazy, useEffect, useState } from "react";
+
+import { useDocumentPreviewStore } from "./preview-store";
+
+// pdf.js / react-pdf are heavy (~0.5 MB gzip): defer until the first citation
+// click, then keep mounted for open/close anims.
+const DocumentPreviewSheet = lazy(() =>
+  import("./document-preview-sheet").then((m) => ({
+    default: m.DocumentPreviewSheet,
+  })),
+);
+
+export function DocumentPreviewMount() {
+  const open = useDocumentPreviewStore((s) => s.open);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    if (open) setMounted(true);
+  }, [open]);
+
+  if (!mounted) return null;
+  return (
+    <Suspense fallback={null}>
+      <DocumentPreviewSheet />
+    </Suspense>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/document-preview-sheet.tsx b/studio/frontend/src/features/rag/components/document-preview-sheet.tsx
new file mode 100644
index 0000000000..fb65914ac6
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/document-preview-sheet.tsx
@@ -0,0 +1,474 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"use client";
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Document, Page, pdfjs } from "react-pdf";
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  FileTextIcon,
+  LoaderIcon,
+  ZoomInIcon,
+  ZoomOutIcon,
+} from "lucide-react";
+
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { getDocumentFileUrl, getPreviewTarget } from "../api/rag-api";
+import type { PdfRegion, PreviewTarget } from "../types/rag";
+import { useDocumentPreviewStore } from "./preview-store";
+
+// Serve the pdf.js worker from the app origin.
+pdfjs.GlobalWorkerOptions.workerSrc = new URL(
+  "pdfjs-dist/build/pdf.worker.min.mjs",
+  import.meta.url,
+).toString();
+
+// Highlight rects; coords are 0..1 of the page box.
+function RegionOverlay({ regions }: { regions: PdfRegion[] }) {
+  if (regions.length === 0) return null;
+  return (
+    <>
+      {regions.map((r, i) => (
+        <div
+          key={i}
+          className="pointer-events-none absolute rounded-sm bg-amber-300/35 ring-1 ring-amber-500/70 mix-blend-multiply"
+          style={{
+            left: `${r.x * 100}%`,
+            top: `${r.y * 100}%`,
+            width: `${r.width * 100}%`,
+            height: `${r.height * 100}%`,
+          }}
+        />
+      ))}
+    </>
+  );
+}
+
+// Zoom multiplies fit-to-panel width: 1 = fit.
+const ZOOM_MIN = 0.5;
+const ZOOM_MAX = 3;
+const ZOOM_STEP = 0.25;
+
+const clampZoom = (z: number) =>
+  Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Number(z.toFixed(2))));
+
+function PdfPreview({
+  fileUrl,
+  initialPage,
+  regions,
+}: {
+  fileUrl: string;
+  initialPage: number;
+  regions: PdfRegion[];
+}) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [width, setWidth] = useState(0);
+  const [numPages, setNumPages] = useState(0);
+  const [page, setPage] = useState(initialPage);
+  const [scale, setScale] = useState(1);
+  const [error, setError] = useState<string | null>(null);
+  const [grabbing, setGrabbing] = useState(false);
+  const [scrollable, setScrollable] = useState(false);
+  const panRef = useRef<{
+    x: number;
+    y: number;
+    left: number;
+    top: number;
+  } | null>(null);
+
+  // Reset page/zoom when a new citation reuses this viewer.
+  useEffect(() => setPage(initialPage), [initialPage, fileUrl]);
+
+  useEffect(() => setScale(1), [fileUrl]);
+
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const measure = () => setWidth(el.clientWidth);
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // Non-passive wheel listener so preventDefault can stop the panel scrolling.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const onWheel = (e: WheelEvent) => {
+      e.preventDefault();
+      setScale((s) => clampZoom(s - Math.sign(e.deltaY) * ZOOM_STEP));
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    return () => el.removeEventListener("wheel", onWheel);
+  }, []);
+
+  const onLoad = useCallback(
+    ({ numPages: n }: { numPages: number }) => {
+      setNumPages(n);
+      setPage((p) => Math.min(Math.max(p, 1), n));
+    },
+    [],
+  );
+
+  const zoomBy = useCallback(
+    (delta: number) => setScale((s) => clampZoom(s + delta)),
+    [],
+  );
+
+  // Whether the page overflows the panel (so panning matters).
+  const recheckScrollable = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    setScrollable(
+      el.scrollWidth > el.clientWidth + 1 ||
+        el.scrollHeight > el.clientHeight + 1,
+    );
+  }, []);
+
+  useEffect(() => {
+    recheckScrollable();
+  }, [recheckScrollable, width, scale, page, numPages]);
+
+  // Grab-to-pan; listen on window so the drag tracks past the panel edge.
+  useEffect(() => {
+    if (!grabbing) return;
+    const onMove = (e: MouseEvent) => {
+      const el = containerRef.current;
+      const start = panRef.current;
+      if (!el || !start) return;
+      el.scrollLeft = start.left - (e.clientX - start.x);
+      el.scrollTop = start.top - (e.clientY - start.y);
+    };
+    const onUp = () => {
+      setGrabbing(false);
+      panRef.current = null;
+    };
+    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mouseup", onUp);
+    return () => {
+      window.removeEventListener("mousemove", onMove);
+      window.removeEventListener("mouseup", onUp);
+    };
+  }, [grabbing]);
+
+  const onPanStart = useCallback(
+    (e: React.MouseEvent) => {
+      const el = containerRef.current;
+      if (!el || e.button !== 0 || !scrollable) return;
+      panRef.current = {
+        x: e.clientX,
+        y: e.clientY,
+        left: el.scrollLeft,
+        top: el.scrollTop,
+      };
+      setGrabbing(true);
+      e.preventDefault(); // stop canvas image-drag / selection
+    },
+    [scrollable],
+  );
+
+  const pageRegions = regions.filter(
+    (r) => r.pageNumber === page || r.pageIndex === page - 1,
+  );
+
+  if (error) {
+    return (
+      <div className="p-6 text-sm text-muted-foreground">
+        Could not render this PDF ({error}).
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <div
+        ref={containerRef}
+        onMouseDown={onPanStart}
+        className={cn(
+          "flex-1 overflow-auto bg-muted/30 px-4 py-3",
+          grabbing
+            ? "cursor-grabbing select-none"
+            : scrollable
+              ? "cursor-grab"
+              : "",
+        )}
+      >
+        <Document
+          file={fileUrl}
+          onLoadSuccess={onLoad}
+          onLoadError={(e) => setError(e.message)}
+          loading={
+            <div className="flex items-center gap-2 p-6 text-sm text-muted-foreground">
+              <LoaderIcon className="size-3.5 animate-spin" /> Loading PDF…
+            </div>
+          }
+        >
+          {width > 0 && (
+            // min-w-fit lets the zoomed row grow past the panel so the page stays
+            // centered and reachable on both sides.
+            <div className="flex min-w-fit justify-center">
+              <div className="relative w-fit shadow-sm">
+                <Page
+                  pageNumber={page}
+                  width={(width - 8) * scale}
+                  renderTextLayer={false}
+                  renderAnnotationLayer={false}
+                  onRenderSuccess={recheckScrollable}
+                />
+                <RegionOverlay regions={pageRegions} />
+              </div>
+            </div>
+          )}
+        </Document>
+      </div>
+      <div className="grid grid-cols-[1fr_auto_1fr] items-center border-t px-3 py-2 text-xs">
+        <div className="flex items-center gap-0.5 justify-self-start">
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-7"
+            disabled={scale <= ZOOM_MIN}
+            onClick={() => zoomBy(-ZOOM_STEP)}
+            aria-label="Zoom out"
+          >
+            <ZoomOutIcon className="size-4" />
+          </Button>
+          <button
+            type="button"
+            onClick={() => setScale(1)}
+            className="w-11 text-center tabular-nums text-muted-foreground hover:text-foreground"
+            aria-label="Reset zoom"
+          >
+            {Math.round(scale * 100)}%
+          </button>
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-7"
+            disabled={scale >= ZOOM_MAX}
+            onClick={() => zoomBy(ZOOM_STEP)}
+            aria-label="Zoom in"
+          >
+            <ZoomInIcon className="size-4" />
+          </Button>
+        </div>
+        {numPages > 1 ? (
+          <div className="flex items-center gap-3 justify-self-center">
+            <Button
+              variant="ghost"
+              size="icon"
+              className="size-7"
+              disabled={page <= 1}
+              onClick={() => setPage((p) => Math.max(1, p - 1))}
+              aria-label="Previous page"
+            >
+              <ChevronLeftIcon className="size-4" />
+            </Button>
+            <span className="tabular-nums text-muted-foreground">
+              Page {page} / {numPages}
+            </span>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="size-7"
+              disabled={page >= numPages}
+              onClick={() => setPage((p) => Math.min(numPages, p + 1))}
+              aria-label="Next page"
+            >
+              <ChevronRightIcon className="size-4" />
+            </Button>
+          </div>
+        ) : (
+          <span />
+        )}
+        <span aria-hidden />
+      </div>
+    </div>
+  );
+}
+
+// Resizable preview width (px). Default matches the prior fixed 44rem; drag the
+// left edge to widen. Persisted so it survives reopen.
+const PREVIEW_WIDTH_KEY = "unsloth-rag-preview-width";
+const MIN_PREVIEW_WIDTH = 384;
+const DEFAULT_PREVIEW_WIDTH = 704;
+
+const maxPreviewWidth = () =>
+  typeof window === "undefined"
+    ? DEFAULT_PREVIEW_WIDTH
+    : Math.round(window.innerWidth * 0.95);
+
+const clampPreviewWidth = (w: number) =>
+  Math.min(maxPreviewWidth(), Math.max(MIN_PREVIEW_WIDTH, Math.round(w)));
+
+function readStoredPreviewWidth(): number {
+  if (typeof window === "undefined") return DEFAULT_PREVIEW_WIDTH;
+  const raw = Number(window.localStorage.getItem(PREVIEW_WIDTH_KEY));
+  return Number.isFinite(raw) && raw > 0
+    ? clampPreviewWidth(raw)
+    : DEFAULT_PREVIEW_WIDTH;
+}
+
+function persistPreviewWidth(w: number) {
+  try {
+    window.localStorage.setItem(PREVIEW_WIDTH_KEY, String(Math.round(w)));
+  } catch {
+    // ignore storage errors (private mode, quota, etc.)
+  }
+}
+
+export function DocumentPreviewSheet() {
+  const { open, documentId, chunkId, filename, page, closePreview } =
+    useDocumentPreviewStore();
+  const [target, setTarget] = useState<PreviewTarget | null>(null);
+  const [fileUrl, setFileUrl] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Left-edge drag resizing of the panel.
+  const [previewWidth, setPreviewWidth] = useState<number>(
+    readStoredPreviewWidth,
+  );
+  const [resizing, setResizing] = useState(false);
+  const resizeRef = useRef<{ startX: number; startWidth: number } | null>(null);
+  const widthRef = useRef(previewWidth);
+  widthRef.current = previewWidth;
+
+  const onResizeStart = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    resizeRef.current = { startX: e.clientX, startWidth: widthRef.current };
+    setResizing(true);
+  }, []);
+
+  useEffect(() => {
+    if (!resizing) return;
+    const onMove = (e: MouseEvent) => {
+      const start = resizeRef.current;
+      if (!start) return;
+      // Right-anchored panel: dragging left (smaller clientX) widens it.
+      setPreviewWidth(
+        clampPreviewWidth(start.startWidth + (start.startX - e.clientX)),
+      );
+    };
+    const onUp = () => {
+      setResizing(false);
+      resizeRef.current = null;
+      persistPreviewWidth(widthRef.current);
+    };
+    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mouseup", onUp);
+    return () => {
+      window.removeEventListener("mousemove", onMove);
+      window.removeEventListener("mouseup", onUp);
+    };
+  }, [resizing]);
+
+  useEffect(() => {
+    if (!open || !documentId) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setTarget(null);
+    setFileUrl(null);
+    (async () => {
+      try {
+        const t = await getPreviewTarget(documentId, chunkId ?? undefined);
+        if (cancelled) return;
+        setTarget(t);
+        if (t.mediaKind === "pdf") {
+          const url = await getDocumentFileUrl(documentId);
+          if (!cancelled) setFileUrl(url);
+        }
+      } catch (e) {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [open, documentId, chunkId]);
+
+  const headerName = target?.filename ?? filename ?? "Document";
+  const headerPage = target?.targetPage ?? page ?? null;
+
+  return (
+    <Sheet open={open} onOpenChange={(o) => !o && closePreview()}>
+      <SheetContent
+        side="right"
+        style={{ width: previewWidth, maxWidth: "95vw" }}
+        className={cn(
+          "flex w-full flex-col gap-0 p-0",
+          resizing && "select-none",
+        )}
+      >
+        {/* Drag the left edge to widen the preview; double-click to reset. */}
+        <div
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize document preview"
+          onMouseDown={onResizeStart}
+          onDoubleClick={() => {
+            setPreviewWidth(DEFAULT_PREVIEW_WIDTH);
+            persistPreviewWidth(DEFAULT_PREVIEW_WIDTH);
+          }}
+          className={cn(
+            "absolute inset-y-0 left-0 z-20 w-2 cursor-col-resize transition-colors hover:bg-primary/25",
+            resizing && "bg-primary/40",
+          )}
+        />
+        <SheetHeader className="gap-1 border-b p-4">
+          {/* pr-10 reserves room for the absolute close button. */}
+          <SheetTitle className="flex items-center gap-2 pr-10 text-sm">
+            <FileTextIcon className="size-4 shrink-0" />
+            <span className="min-w-0 truncate">{headerName}</span>
+            {headerPage != null && (
+              <span className="shrink-0 text-muted-foreground">
+                · page {headerPage}
+              </span>
+            )}
+          </SheetTitle>
+        </SheetHeader>
+
+        <div className="min-h-0 flex-1">
+          {loading ? (
+            <div className="flex items-center gap-2 p-6 text-sm text-muted-foreground">
+              <LoaderIcon className="size-3.5 animate-spin" /> Resolving source…
+            </div>
+          ) : error ? (
+            <div className="p-6 text-sm text-muted-foreground">
+              Could not open this document ({error}).
+            </div>
+          ) : target && target.mediaKind === "pdf" && fileUrl ? (
+            <PdfPreview
+              fileUrl={fileUrl}
+              initialPage={target.targetPage ?? 1}
+              regions={target.pdfRegions ?? []}
+            />
+          ) : target?.text ? (
+            <div className="h-full overflow-auto p-5">
+              <p className="whitespace-pre-wrap break-words text-sm leading-relaxed text-foreground/90">
+                {target.text}
+              </p>
+            </div>
+          ) : (
+            <div className="p-6 text-sm text-muted-foreground">
+              No preview available for this source.
+            </div>
+          )}
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/document-status-chip.tsx b/studio/frontend/src/features/rag/components/document-status-chip.tsx
new file mode 100644
index 0000000000..0f2d5341c9
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/document-status-chip.tsx
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { LoaderCircleIcon, XIcon } from "lucide-react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { File02Icon } from "@hugeicons/core-free-icons";
+import { Badge } from "@/components/assistant-ui/badge";
+import { cn } from "@/lib/utils";
+import type { DocumentStatus } from "../types/rag";
+
+export function DocumentStatusChip({
+  filename,
+  status,
+  error,
+  onRemove,
+}: {
+  filename: string;
+  status: DocumentStatus;
+  progress?: number | null;
+  error?: string | null;
+  onRemove?: () => void;
+}) {
+  const processing = status === "pending" || status === "running";
+  return (
+    <Badge
+      variant="outline"
+      size="sm"
+      title={error ?? filename}
+      className={cn(
+        "rounded-full inline-flex items-center gap-1.5 max-w-[16rem]",
+        status === "failed" && "border-destructive/40 text-destructive",
+      )}
+    >
+      {/* file */}
+      <HugeiconsIcon
+        icon={File02Icon}
+        strokeWidth={2}
+        className="size-3 shrink-0"
+      />
+      <span className="truncate">{filename}</span>
+      {/* spinner while indexing, else close button */}
+      {processing ? (
+        <LoaderCircleIcon
+          className="shrink-0 animate-spin size-3.5 text-muted-foreground"
+          role="status"
+          aria-label="Loading"
+        />
+      ) : onRemove ? (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label={`Remove ${filename}`}
+          className="shrink-0 rounded-full text-muted-foreground hover:text-foreground"
+        >
+          <XIcon className="size-3" />
+        </button>
+      ) : null}
+    </Badge>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
new file mode 100644
index 0000000000..b703fca347
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { XIcon } from "lucide-react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { FileDatabaseIcon, Tick02Icon } from "@hugeicons/core-free-icons";
+import { type FC, useCallback, useEffect, useState } from "react";
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
+import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
+
+import { listKnowledgeBases } from "../api/rag-api";
+import type { KnowledgeBase } from "../types/rag";
+import { KnowledgeBaseDialog } from "./knowledge-base-dialog";
+
+// Matches the Thinking/MCP pill chevron.
+const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={1.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden={true}
+  >
+    <path d="M5.99977 9.00005L11.9998 15L17.9998 9" />
+  </svg>
+);
+
+// Picks the retrieval source. Only rendered when retrieval is on and the loaded
+// model can run search_knowledge_base.
+export function KnowledgeBaseComposerButton({
+  side = "bottom",
+}: {
+  side?: "top" | "bottom";
+} = {}) {
+  const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
+  const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
+  const ragAvailable = useRagToolAvailable();
+  const ragSource = useChatRuntimeStore((s) => s.ragSource);
+  const setRagSource = useChatRuntimeStore((s) => s.setRagSource);
+
+  const [kbs, setKbs] = useState<KnowledgeBase[]>([]);
+  const [kbsLoaded, setKbsLoaded] = useState(false);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [dialogOpen, setDialogOpen] = useState(false);
+
+  const refresh = useCallback(async () => {
+    try {
+      const rows = await listKnowledgeBases();
+      setKbs(rows);
+    } catch {
+      // Keep prior state on failure.
+    } finally {
+      setKbsLoaded(true);
+    }
+  }, []);
+
+  // Load on mount so newly created KBs show up.
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  // If the selected KB was deleted, fall back to thread source so we never send a
+  // stale kb_id. Gate on kbsLoaded, not kbs.length: deleting the last KB empties the
+  // list, so a length>0 guard would skip the reset and stick on a ghost KB.
+  useEffect(() => {
+    if (
+      kbsLoaded &&
+      ragSource.type === "kb" &&
+      !kbs.some((kb) => kb.id === ragSource.kbId)
+    ) {
+      setRagSource({ type: "thread" });
+    }
+  }, [kbs, kbsLoaded, ragSource, setRagSource]);
+
+  if (!ragEnabled || !ragAvailable) return null;
+
+  return (
+    <>
+      <DropdownMenu
+        open={menuOpen}
+        onOpenChange={(open) => {
+          setMenuOpen(open);
+          if (open) void refresh();
+        }}
+      >
+        <DropdownMenuTrigger asChild={true}>
+          <button
+            type="button"
+            className="composer-pill-btn"
+            data-active="true"
+            aria-label="Retrieval source"
+          >
+            {/* Icon doubles as an off switch: hover swaps to an X; clicking it
+                turns RAG off without opening the menu. */}
+            <span
+              role="button"
+              aria-label="Turn off retrieval"
+              tabIndex={-1}
+              onPointerDown={(e) => e.stopPropagation()}
+              onClick={(e) => {
+                e.stopPropagation();
+                setRagEnabled(false);
+              }}
+              className="composer-pill-glyph cursor-pointer"
+            >
+              <HugeiconsIcon
+                icon={FileDatabaseIcon}
+                strokeWidth={2}
+                className="size-[15px]"
+              />
+              <XIcon className="composer-pill-x" />
+            </span>
+            <span>RAG</span>
+            <ArrowDownStandardIcon className="composer-pill-caret size-[15px]" />
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent
+          side={side}
+          align="start"
+          sideOffset={2}
+          avoidCollisions={true}
+          className="unsloth-plus-menu mcp-menu w-[232px]"
+        >
+          <DropdownMenuLabel>Retrieve from</DropdownMenuLabel>
+          <DropdownMenuItem
+            onSelect={() => setRagSource({ type: "thread" })}
+            className={
+              ragSource.type === "thread"
+                ? "relative text-primary font-medium"
+                : "relative"
+            }
+          >
+            <span className="truncate">This thread's documents</span>
+            {ragSource.type === "thread" ? (
+              <HugeiconsIcon
+                icon={Tick02Icon}
+                strokeWidth={2}
+                className="ml-auto"
+              />
+            ) : null}
+          </DropdownMenuItem>
+          {kbs.length > 0 ? <DropdownMenuSeparator /> : null}
+          {kbs.map((kb) => {
+            const selected =
+              ragSource.type === "kb" && ragSource.kbId === kb.id;
+            return (
+              <DropdownMenuItem
+                key={kb.id}
+                onSelect={() => setRagSource({ type: "kb", kbId: kb.id })}
+                className={
+                  selected ? "relative text-primary font-medium" : "relative"
+                }
+              >
+                <span className="truncate">{kb.name}</span>
+                {selected ? (
+                  <HugeiconsIcon
+                    icon={Tick02Icon}
+                    strokeWidth={2}
+                    className="ml-auto"
+                  />
+                ) : null}
+              </DropdownMenuItem>
+            );
+          })}
+          <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onSelect={() => {
+              setMenuOpen(false);
+              setDialogOpen(true);
+            }}
+          >
+            Manage knowledge bases…
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <KnowledgeBaseDialog
+        open={dialogOpen}
+        onOpenChange={(next) => {
+          setDialogOpen(next);
+          if (!next) void refresh();
+        }}
+      />
+    </>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/knowledge-base-dialog.tsx b/studio/frontend/src/features/rag/components/knowledge-base-dialog.tsx
new file mode 100644
index 0000000000..1613a2a5bf
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/knowledge-base-dialog.tsx
@@ -0,0 +1,334 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  Delete02Icon,
+  Edit03Icon,
+  PlusSignIcon,
+} from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { ChevronLeftIcon, UploadIcon } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Spinner } from "@/components/ui/spinner";
+import { Textarea } from "@/components/ui/textarea";
+import { toast } from "@/lib/toast";
+
+import {
+  createKnowledgeBase,
+  deleteKnowledgeBase,
+  listKnowledgeBaseDocuments,
+  listKnowledgeBases,
+  updateKnowledgeBase,
+} from "../api/rag-api";
+import { RAG_UPLOAD_ACCEPT, type KnowledgeBase } from "../types/rag";
+import { DocumentStatusChip } from "./document-status-chip";
+import { useRagDocuments } from "./use-rag-documents";
+
+type View =
+  | { kind: "list" }
+  | { kind: "create" }
+  | { kind: "edit"; kb: KnowledgeBase }
+  | { kind: "documents"; kb: KnowledgeBase };
+
+export interface KnowledgeBaseDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function KnowledgeBaseDialog({
+  open,
+  onOpenChange,
+}: KnowledgeBaseDialogProps) {
+  const [kbs, setKbs] = useState<KnowledgeBase[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [view, setView] = useState<View>({ kind: "list" });
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [saving, setSaving] = useState(false);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      setKbs(await listKnowledgeBases());
+    } catch (err) {
+      toast.error("Failed to load knowledge bases", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+    setView({ kind: "list" });
+    void refresh();
+  }, [open, refresh]);
+
+  function startCreate() {
+    setName("");
+    setDescription("");
+    setView({ kind: "create" });
+  }
+
+  function startEdit(kb: KnowledgeBase) {
+    setName(kb.name);
+    setDescription(kb.description ?? "");
+    setView({ kind: "edit", kb });
+  }
+
+  function backToList() {
+    setView({ kind: "list" });
+  }
+
+  async function submitForm() {
+    const trimmed = name.trim();
+    if (!trimmed) {
+      toast.error("Name is required");
+      return;
+    }
+    setSaving(true);
+    try {
+      if (view.kind === "edit") {
+        await updateKnowledgeBase(view.kb.id, {
+          name: trimmed,
+          description: description.trim(),
+        });
+        toast.success("Knowledge base updated");
+      } else {
+        await createKnowledgeBase({
+          name: trimmed,
+          description: description.trim() || undefined,
+        });
+        toast.success("Knowledge base created");
+      }
+      backToList();
+      await refresh();
+    } catch (err) {
+      toast.error("Save failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  async function removeKb(kb: KnowledgeBase) {
+    if (
+      !window.confirm(
+        `Delete knowledge base "${kb.name}" and all its documents?`,
+      )
+    ) {
+      return;
+    }
+    try {
+      await deleteKnowledgeBase(kb.id);
+      await refresh();
+    } catch (err) {
+      toast.error("Delete failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  const showForm = view.kind === "create" || view.kind === "edit";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>
+            {view.kind === "documents"
+              ? view.kb.name
+              : "Knowledge bases"}
+          </DialogTitle>
+          <DialogDescription>
+            {view.kind === "documents"
+              ? "Upload documents to index for retrieval in chat."
+              : "Group documents into a reusable knowledge base for chat retrieval."}
+          </DialogDescription>
+        </DialogHeader>
+
+        {view.kind === "documents" ? (
+          <KnowledgeBaseDocuments kb={view.kb} onBack={backToList} />
+        ) : showForm ? (
+          <div className="flex flex-col gap-4">
+            <div className="grid gap-2">
+              <Label htmlFor="kb-name">Name</Label>
+              <Input
+                id="kb-name"
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                placeholder="e.g. Product docs"
+              />
+            </div>
+            <div className="grid gap-2">
+              <Label htmlFor="kb-description">Description</Label>
+              <Textarea
+                id="kb-description"
+                value={description}
+                onChange={(e) => setDescription(e.target.value)}
+                placeholder="Optional. What this knowledge base contains."
+                rows={3}
+              />
+            </div>
+            <div className="flex justify-end gap-2 pt-2">
+              <Button variant="ghost" onClick={backToList} disabled={saving}>
+                Cancel
+              </Button>
+              <Button onClick={submitForm} disabled={saving}>
+                {saving ? <Spinner /> : null}
+                {view.kind === "edit" ? "Save changes" : "Create"}
+              </Button>
+            </div>
+          </div>
+        ) : (
+          <div className="flex min-w-0 flex-col gap-3">
+            <div className="flex justify-end">
+              <Button size="sm" onClick={startCreate}>
+                <HugeiconsIcon icon={PlusSignIcon} size={14} />
+                New knowledge base
+              </Button>
+            </div>
+            {loading ? (
+              <div className="flex justify-center py-6">
+                <Spinner />
+              </div>
+            ) : kbs.length === 0 ? (
+              <div className="rounded-md border border-dashed py-6 text-center text-sm text-muted-foreground">
+                No knowledge bases yet.
+              </div>
+            ) : (
+              <ul className="flex max-h-[60vh] flex-col divide-y overflow-y-auto rounded-md border">
+                {kbs.map((kb) => (
+                  <li
+                    key={kb.id}
+                    className="flex items-center justify-between gap-3 px-3 py-2"
+                  >
+                    <button
+                      type="button"
+                      onClick={() => setView({ kind: "documents", kb })}
+                      className="min-w-0 flex-1 text-left"
+                    >
+                      <div className="truncate font-medium">{kb.name}</div>
+                      <div className="truncate text-xs text-muted-foreground">
+                        {kb.documentCount ?? 0} document
+                        {(kb.documentCount ?? 0) === 1 ? "" : "s"}
+                        {kb.description ? ` · ${kb.description}` : ""}
+                      </div>
+                    </button>
+                    <div className="flex items-center gap-1">
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={() => startEdit(kb)}
+                        aria-label="Rename knowledge base"
+                      >
+                        <HugeiconsIcon icon={Edit03Icon} size={14} />
+                      </Button>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={() => removeKb(kb)}
+                        aria-label="Delete knowledge base"
+                      >
+                        <HugeiconsIcon icon={Delete02Icon} size={14} />
+                      </Button>
+                    </div>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function KnowledgeBaseDocuments({
+  kb,
+  onBack,
+}: {
+  kb: KnowledgeBase;
+  onBack: () => void;
+}) {
+  const lister = useCallback(
+    () => listKnowledgeBaseDocuments(kb.id),
+    [kb.id],
+  );
+  const { documents, loading, uploading, upload, remove } = useRagDocuments(
+    { type: "kb", kbId: kb.id },
+    lister,
+  );
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <div className="flex min-w-0 flex-col gap-3">
+      <div className="flex items-center justify-between">
+        <Button variant="ghost" size="sm" onClick={onBack}>
+          <ChevronLeftIcon className="size-4" />
+          All knowledge bases
+        </Button>
+        <Button
+          size="sm"
+          onClick={() => fileInputRef.current?.click()}
+          disabled={uploading}
+        >
+          {uploading ? <Spinner /> : <UploadIcon className="size-3.5" />}
+          Upload
+        </Button>
+        <input
+          ref={fileInputRef}
+          type="file"
+          multiple
+          accept={RAG_UPLOAD_ACCEPT}
+          className="hidden"
+          onChange={(e) => {
+            if (e.target.files?.length) void upload(e.target.files);
+            e.target.value = "";
+          }}
+        />
+      </div>
+      {loading && documents.length === 0 ? (
+        <div className="flex justify-center py-6">
+          <Spinner />
+        </div>
+      ) : documents.length === 0 ? (
+        <div className="rounded-md border border-dashed py-6 text-center text-sm text-muted-foreground">
+          No documents yet. Upload a PDF, Markdown, DOCX, HTML, or text file.
+        </div>
+      ) : (
+        <div className="flex max-h-[55vh] flex-wrap gap-1.5 overflow-y-auto pr-0.5">
+          {documents.map((doc) => (
+            <DocumentStatusChip
+              key={doc.id}
+              filename={doc.filename}
+              status={doc.status}
+              progress={doc.progress}
+              error={doc.error}
+              onRemove={
+                doc.id.startsWith("pending_")
+                  ? undefined
+                  : () => void remove(doc.id)
+              }
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/preview-store.ts b/studio/frontend/src/features/rag/components/preview-store.ts
new file mode 100644
index 0000000000..e583c5a391
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/preview-store.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { create } from "zustand";
+
+// Global store for the shared preview Sheet, so any citation drives the one viewer
+// without prop-drilling.
+interface DocumentPreviewState {
+  open: boolean;
+  documentId: string | null;
+  /** Chunk to highlight; null opens at page 1. */
+  chunkId: string | null;
+  filename: string | null;
+  page: number | null;
+  openPreview: (args: {
+    documentId: string;
+    chunkId?: string | null;
+    filename?: string | null;
+    page?: number | null;
+  }) => void;
+  closePreview: () => void;
+}
+
+export const useDocumentPreviewStore = create<DocumentPreviewState>((set) => ({
+  open: false,
+  documentId: null,
+  chunkId: null,
+  filename: null,
+  page: null,
+  openPreview: ({ documentId, chunkId, filename, page }) =>
+    set({
+      open: true,
+      documentId,
+      chunkId: chunkId ?? null,
+      filename: filename ?? null,
+      page: page ?? null,
+    }),
+  closePreview: () => set({ open: false }),
+}));
diff --git a/studio/frontend/src/features/rag/components/retrieval-settings-section.tsx b/studio/frontend/src/features/rag/components/retrieval-settings-section.tsx
new file mode 100644
index 0000000000..d8f69d93a1
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/retrieval-settings-section.tsx
@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { ReactNode } from "react";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Slider } from "@/components/ui/slider";
+import {
+  ToggleGroup,
+  ToggleGroupItem,
+} from "@/components/ui/toggle-group";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { InfoIcon } from "lucide-react";
+import { cn } from "@/lib/utils";
+import {
+  type RagAutoInject,
+  type RagMode,
+  useChatRuntimeStore,
+} from "@/features/chat/stores/chat-runtime-store";
+
+const MODE_LABEL: Record<RagMode, string> = {
+  hybrid: "Hybrid",
+  dense: "Semantic only",
+  lexical: "BM25 only",
+};
+
+function InfoHint({ children }: { children: ReactNode }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild={true}>
+        <button
+          type="button"
+          aria-label="More info"
+          className="text-muted-foreground/50 hover:text-muted-foreground"
+        >
+          <InfoIcon className="size-3.5" />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs">{children}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+function SliderRow({
+  label,
+  value,
+  min,
+  max,
+  step,
+  onChange,
+  disabled = false,
+  format = (v: number) => String(v),
+}: {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  onChange: (v: number) => void;
+  disabled?: boolean;
+  format?: (v: number) => string;
+}) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-2",
+        disabled && "pointer-events-none opacity-50",
+      )}
+    >
+      <div className="flex items-center justify-between">
+        <span className="text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
+          {label}
+        </span>
+        <span className="text-[13px] tabular-nums text-muted-foreground">
+          {format(value)}
+        </span>
+      </div>
+      <Slider
+        value={[value]}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        onValueChange={([v]) => onChange(v)}
+        aria-label={label}
+      />
+    </div>
+  );
+}
+
+// Retrieval settings; the source itself is picked from the composer dropdown.
+export function RetrievalSettingsSection() {
+  const ragMode = useChatRuntimeStore((s) => s.ragMode);
+  const setRagMode = useChatRuntimeStore((s) => s.setRagMode);
+  const ragTopK = useChatRuntimeStore((s) => s.ragTopK);
+  const setRagTopK = useChatRuntimeStore((s) => s.setRagTopK);
+  const ragAutoInject = useChatRuntimeStore((s) => s.ragAutoInject);
+  const setRagAutoInject = useChatRuntimeStore((s) => s.setRagAutoInject);
+  const ragAutoInjectMinScore = useChatRuntimeStore(
+    (s) => s.ragAutoInjectMinScore,
+  );
+  const setRagAutoInjectMinScore = useChatRuntimeStore(
+    (s) => s.setRagAutoInjectMinScore,
+  );
+
+  return (
+    <div className="flex flex-col gap-5 pt-1">
+      <div className="flex flex-col gap-2">
+        <span className="text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
+          Search mode
+        </span>
+        <Select
+          value={ragMode}
+          onValueChange={(value) => setRagMode(value as RagMode)}
+        >
+          <SelectTrigger
+            className="panel-select-trigger h-8 w-full"
+            aria-label="Search mode"
+          >
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="hybrid">{MODE_LABEL.hybrid}</SelectItem>
+            <SelectItem value="dense">{MODE_LABEL.dense}</SelectItem>
+            <SelectItem value="lexical">{MODE_LABEL.lexical}</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between">
+          <span className="text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
+            Passages (top K)
+          </span>
+          <span className="text-[13px] tabular-nums text-muted-foreground">
+            {ragTopK}
+          </span>
+        </div>
+        <Slider
+          value={[ragTopK]}
+          min={1}
+          max={20}
+          step={1}
+          onValueChange={([value]) => setRagTopK(value)}
+          aria-label="Number of passages to retrieve"
+        />
+      </div>
+
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col">
+          <span className="flex items-center gap-1.5 text-[13px] font-medium leading-[1.25] tracking-nav text-nav-fg">
+            Auto-retrieve documents
+            <InfoHint>
+              Auto turns retrieval on for smaller models (9B and below), which
+              tend to answer from memory instead of searching, and leaves it to
+              larger ones. On and Off force it either way.
+            </InfoHint>
+          </span>
+          <span className="text-[12px] leading-[1.3] text-muted-foreground">
+            Search attached documents before answering.
+          </span>
+        </div>
+        <ToggleGroup
+          type="single"
+          variant="outline"
+          value={ragAutoInject}
+          onValueChange={(value) => {
+            // Radix clears on re-click; ignore empty so one stays selected.
+            if (value) setRagAutoInject(value as RagAutoInject);
+          }}
+          className="w-full"
+          aria-label="Auto-retrieve documents"
+        >
+          <ToggleGroupItem value="auto" className="flex-1">
+            Auto
+          </ToggleGroupItem>
+          <ToggleGroupItem value="on" className="flex-1">
+            On
+          </ToggleGroupItem>
+          <ToggleGroupItem value="off" className="flex-1">
+            Off
+          </ToggleGroupItem>
+        </ToggleGroup>
+        <SliderRow
+          label="Auto-retrieve threshold"
+          value={ragAutoInjectMinScore}
+          min={0}
+          max={1}
+          step={0.05}
+          disabled={ragAutoInject === "off"}
+          onChange={setRagAutoInjectMinScore}
+          format={(v) => v.toFixed(2)}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/thread-documents-bar.tsx b/studio/frontend/src/features/rag/components/thread-documents-bar.tsx
new file mode 100644
index 0000000000..6ba0440699
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/thread-documents-bar.tsx
@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { AttachmentIcon, FileDatabaseIcon } from "@hugeicons/core-free-icons";
+import { useAui } from "@assistant-ui/react";
+import { cn } from "@/lib/utils";
+import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
+import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
+import { toast } from "@/lib/toast";
+import { listKnowledgeBases, listThreadDocuments } from "../api/rag-api";
+import { RAG_UPLOAD_ACCEPT } from "../types/rag";
+import { DocumentStatusChip } from "./document-status-chip";
+import { useRagDocuments } from "./use-rag-documents";
+
+// Read-only chip shown when retrieval comes from a KB, so the source isn't invisible.
+function KnowledgeBaseSourceChip({ kbId }: { kbId: string }) {
+  const [name, setName] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    listKnowledgeBases()
+      .then((rows) => {
+        if (!cancelled) setName(rows.find((kb) => kb.id === kbId)?.name ?? null);
+      })
+      .catch(() => {
+        if (!cancelled) setName(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [kbId]);
+  return (
+    <div className="mb-2 flex w-full flex-row items-center gap-1.5 pl-0.5 pr-1.5 pt-0.5 pb-1">
+      <span
+        className="composer-pill-btn shrink-0 cursor-default"
+        title="This chat retrieves from a knowledge base. Change the source in RAG retrieval settings."
+      >
+        <HugeiconsIcon
+          icon={FileDatabaseIcon}
+          strokeWidth={2}
+          className="size-3.5"
+        />
+        <span>{name ? `Knowledge base: ${name}` : "Knowledge base"}</span>
+      </span>
+    </div>
+  );
+}
+
+export function ThreadDocumentsBar({
+  threadId,
+  onIndexingChange,
+}: {
+  threadId: string | null;
+  onIndexingChange?: (active: boolean) => void;
+}) {
+  const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
+  const ragAvailable = useRagToolAvailable();
+  const ragSource = useChatRuntimeStore((s) => s.ragSource);
+  const aui = useAui();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  // A fresh chat has no thread id until the first message; materialize one on demand
+  // so docs can attach (append() in runtime-provider reuses it). Track it locally:
+  // pushing to global activeThreadId would, in a project, remount this bar mid-upload
+  // (ProjectLanding's pendingNewThreadId branch) and drop the just-attached chips.
+  const [materializedId, setMaterializedId] = useState<string | null>(null);
+  const effectiveThreadId = threadId ?? materializedId;
+  useEffect(() => {
+    if (threadId) setMaterializedId(null);
+  }, [threadId]);
+
+  const lister = useCallback(
+    () =>
+      effectiveThreadId
+        ? listThreadDocuments(effectiveThreadId)
+        : Promise.resolve([]),
+    [effectiveThreadId],
+  );
+  const { documents, uploading, upload, remove } = useRagDocuments(
+    effectiveThreadId && ragEnabled && ragSource.type === "thread"
+      ? { type: "thread", threadId: effectiveThreadId }
+      : null,
+    lister,
+  );
+
+  // Tell the composer whether any doc is still indexing, so it can hold a queued
+  // send until retrieval covers them (Composer.enqueueSend). For KB / RAG-off scope
+  // is null, so `documents` is empty and this reads false.
+  const hasIndexing = documents.some(
+    (d) => d.status === "pending" || d.status === "running",
+  );
+  useEffect(() => {
+    onIndexingChange?.(hasIndexing);
+  }, [hasIndexing, onIndexingChange]);
+  useEffect(() => () => onIndexingChange?.(false), [onIndexingChange]);
+
+  // Materialize the thread id on first use; ref-deduped so a double-click can't
+  // start two threads.
+  const initPromiseRef = useRef<Promise<string | null> | null>(null);
+  const ensureThreadId = useCallback((): Promise<string | null> => {
+    if (effectiveThreadId) return Promise.resolve(effectiveThreadId);
+    if (initPromiseRef.current) return initPromiseRef.current;
+    const pending = aui
+      .threadListItem()
+      .initialize()
+      .then(({ remoteId }) => {
+        setMaterializedId(remoteId);
+        return remoteId;
+      })
+      .catch(() => {
+        toast.error("Couldn't start a chat for these documents");
+        return null;
+      })
+      .finally(() => {
+        initPromiseRef.current = null;
+      });
+    initPromiseRef.current = pending;
+    return pending;
+  }, [aui, effectiveThreadId]);
+
+  const chipScrollRef = useRef<HTMLDivElement>(null);
+  const [chipsOverflow, setChipsOverflow] = useState(false);
+  const updateChipFade = useCallback(() => {
+    const el = chipScrollRef.current;
+    if (!el) return;
+    setChipsOverflow(el.scrollHeight - el.scrollTop - el.clientHeight > 1);
+  }, []);
+  useEffect(() => {
+    updateChipFade();
+  }, [documents, updateChipFade]);
+
+  // Open the picker synchronously to keep the click's user activation. Do NOT
+  // materialize here: setActiveThreadId while the native dialog is open can remount
+  // the composer and orphan this <input>. Materialize in onChange instead.
+  const handleAddDocs = useCallback(() => {
+    fileInputRef.current?.click();
+  }, []);
+
+  // Only when the RAG pill is on: enabled AND a tool-capable model loaded.
+  if (!ragEnabled || !ragAvailable) return null;
+  // A KB source uploads via the KB dialog, not here; show which KB is active.
+  if (ragSource.type === "kb") {
+    return <KnowledgeBaseSourceChip kbId={ragSource.kbId} />;
+  }
+
+  return (
+    <div className="mb-2 flex w-full flex-row items-start gap-1.5 pl-0.5 pr-1.5 pt-0.5 pb-1">
+      <button
+        type="button"
+        onClick={handleAddDocs}
+        disabled={uploading}
+        className={cn(
+          "composer-pill-btn shrink-0 -translate-y-px !text-foreground/80",
+          // Square button so the rounded-full hover reads as a circle.
+          documents.length > 0 && "size-8 justify-center px-0",
+        )}
+        aria-label="Attach documents to this thread"
+        title="Attach documents for retrieval"
+      >
+        <HugeiconsIcon
+          icon={AttachmentIcon}
+          strokeWidth={2}
+          className="size-3.5"
+        />
+        {/* Icon-only once documents are attached. */}
+        {documents.length === 0 && <span>Add files to chat with</span>}
+      </button>
+      <input
+        ref={fileInputRef}
+        type="file"
+        multiple
+        accept={RAG_UPLOAD_ACCEPT}
+        className="hidden"
+        onChange={(e) => {
+          const files = Array.from(e.target.files ?? []);
+          e.target.value = "";
+          if (files.length === 0) return;
+          // Pass the id as a promise so upload() flips its in-flight guard before
+          // materialization re-renders us; on the first click `scope` is still null.
+          void upload(
+            files,
+            ensureThreadId().then((id) =>
+              id ? ({ type: "thread", threadId: id } as const) : null,
+            ),
+          );
+        }}
+      />
+      {/* Cap height so a large set scrolls; fade the cut-off row. */}
+      <div
+        ref={chipScrollRef}
+        onScroll={updateChipFade}
+        className={cn(
+          "flex max-h-24 flex-1 flex-row flex-wrap items-center gap-1.5 overflow-y-auto",
+          chipsOverflow && "rag-docs-bottom-fade",
+        )}
+      >
+        {documents.map((doc) => (
+          <DocumentStatusChip
+            key={doc.id}
+            filename={doc.filename}
+            status={doc.status}
+            progress={doc.progress}
+            error={doc.error}
+            onRemove={
+              doc.id.startsWith("pending_")
+                ? undefined
+                : () => void remove(doc.id)
+            }
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/studio/frontend/src/features/rag/components/use-rag-documents.ts b/studio/frontend/src/features/rag/components/use-rag-documents.ts
new file mode 100644
index 0000000000..fdca3f09eb
--- /dev/null
+++ b/studio/frontend/src/features/rag/components/use-rag-documents.ts
@@ -0,0 +1,352 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "@/lib/toast";
+import {
+  deleteDocument,
+  getJob,
+  streamJobEvents,
+  uploadKnowledgeBaseDocument,
+  uploadThreadDocument,
+} from "../api/rag-api";
+import type { DocumentStatus, RagDocument } from "../types/rag";
+
+export interface TrackedDocument extends RagDocument {
+  progress?: number | null;
+}
+
+// Client-side dedup key; backend dedups authoritatively by content hash.
+function fileSignature(file: File): string {
+  return `${file.name}|${file.size}|${file.lastModified}`;
+}
+
+export type RagDocumentScope =
+  | { type: "kb"; kbId: string }
+  | { type: "thread"; threadId: string };
+
+type Lister = () => Promise<RagDocument[]>;
+
+export function useRagDocuments(
+  scope: RagDocumentScope | null,
+  lister: Lister,
+) {
+  const [documents, setDocuments] = useState<TrackedDocument[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [uploading, setUploading] = useState(false);
+  // jobId -> abort, to avoid double-subscribing.
+  const trackedJobs = useRef<Map<string, AbortController>>(new Map());
+  // Live mirror of `documents` for synchronous dedup in upload().
+  const documentsRef = useRef<TrackedDocument[]>([]);
+  useEffect(() => {
+    documentsRef.current = documents;
+  }, [documents]);
+  // documentId -> signature; forgotten on delete, cleared on scope change.
+  const sigByDocId = useRef<Map<string, string>>(new Map());
+  const sigAttached = useCallback(
+    (sig: string) => {
+      for (const s of sigByDocId.current.values()) if (s === sig) return true;
+      return false;
+    },
+    [],
+  );
+  // True while upload() runs, so the scope-change effect can tell a real switch
+  // from lazy thread materialization mid-upload (which must not reset).
+  const uploadInFlightRef = useRef(false);
+
+  const scopeKey = scope
+    ? scope.type === "kb"
+      ? `kb:${scope.kbId}`
+      : `thread:${scope.threadId}`
+    : null;
+  const prevScopeKeyRef = useRef<string | null>(null);
+
+  const patchDoc = useCallback(
+    (documentId: string, patch: Partial<TrackedDocument>) => {
+      setDocuments((rows) =>
+        rows.map((row) =>
+          row.id === documentId ? { ...row, ...patch } : row,
+        ),
+      );
+    },
+    [],
+  );
+
+  const trackJob = useCallback(
+    (jobId: string, documentId: string, filename: string) => {
+      if (trackedJobs.current.has(jobId)) return;
+      const controller = new AbortController();
+      trackedJobs.current.set(jobId, controller);
+
+      const finish = (status: DocumentStatus, error?: string | null) => {
+        if (status === "failed") {
+          // Drop the chip rather than show "Failed"; warn via toast.
+          setDocuments((rows) => rows.filter((row) => row.id !== documentId));
+          toast.error(`Couldn't index ${filename}`, {
+            description: error ?? "Indexing failed",
+          });
+        } else {
+          patchDoc(documentId, { status, error: null, progress: 1 });
+        }
+        trackedJobs.current.delete(jobId);
+      };
+
+      (async () => {
+        try {
+          for await (const ev of streamJobEvents(jobId, controller.signal)) {
+            if (ev.type === "progress") {
+              patchDoc(documentId, {
+                status: "running",
+                progress: ev.progress ?? null,
+              });
+            } else if (ev.type === "complete") {
+              finish("completed");
+              return;
+            } else if (ev.type === "error") {
+              finish("failed", ev.error ?? "Indexing failed");
+              return;
+            }
+          }
+          // Stream ended with no terminal frame: reconcile.
+          const job = await getJob(jobId);
+          finish(
+            job.status === "completed"
+              ? "completed"
+              : job.status === "failed"
+                ? "failed"
+                : "completed",
+            job.error,
+          );
+        } catch {
+          if (controller.signal.aborted) {
+            trackedJobs.current.delete(jobId);
+            return;
+          }
+          // SSE unavailable: poll to a terminal state.
+          try {
+            for (let i = 0; i < 600; i++) {
+              if (controller.signal.aborted) break;
+              const job = await getJob(jobId);
+              if (job.status === "completed") return finish("completed");
+              if (job.status === "failed") {
+                return finish("failed", job.error ?? "Indexing failed");
+              }
+              patchDoc(documentId, {
+                status: job.status === "running" ? "running" : "pending",
+                progress: job.progress ?? null,
+              });
+              await new Promise((r) => setTimeout(r, 1500));
+            }
+          } catch {
+            trackedJobs.current.delete(jobId);
+          }
+        }
+      })();
+    },
+    [patchDoc],
+  );
+
+  const refresh = useCallback(async (opts?: { quiet?: boolean }) => {
+    if (!scope) return;
+    if (!opts?.quiet) setLoading(true);
+    try {
+      // Merge server truth with local progress so a refresh mid-index keeps a
+      // live "running %" chip. Failed docs hidden (toast warned at upload).
+      const rows = (await lister()).filter((row) => row.status !== "failed");
+      setDocuments((prev) => {
+        const merged = rows.map((row) => {
+          const tracked = prev.find((p) => p.id === row.id);
+          return tracked && tracked.progress != null && row.status !== "completed"
+            ? { ...row, progress: tracked.progress }
+            : row;
+        });
+        // Keep optimistic chips (not yet listed) so a refresh racing an upload
+        // can't make them vanish.
+        const serverIds = new Set(rows.map((row) => row.id));
+        const pendingLocal = prev.filter(
+          (row) => row.id.startsWith("pending_") && !serverIds.has(row.id),
+        );
+        return [...merged, ...pendingLocal];
+      });
+    } catch (err) {
+      toast.error("Failed to load documents", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      if (!opts?.quiet) setLoading(false);
+    }
+  }, [scope, lister]);
+
+  // A real switch (thread/KB swap) resets + reloads; first acquiring a scope just
+  // loads. Skip both during materialization mid-upload (scope null -> new thread
+  // while upload() runs) so we don't abort tracking or wipe optimistic chips.
+  useEffect(() => {
+    const prev = prevScopeKeyRef.current;
+    prevScopeKeyRef.current = scopeKey;
+    if (prev !== null && prev !== scopeKey) {
+      for (const controller of trackedJobs.current.values()) controller.abort();
+      trackedJobs.current.clear();
+      sigByDocId.current.clear();
+      setDocuments([]);
+      if (scope) void refresh();
+    } else if (prev === null && scope && !uploadInFlightRef.current) {
+      void refresh();
+    }
+    return () => {
+      // Preserve in-flight tracking when cleanup is the materialization flip,
+      // not a real switch/unmount.
+      if (uploadInFlightRef.current) return;
+      for (const controller of trackedJobs.current.values()) controller.abort();
+      trackedJobs.current.clear();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scopeKey]);
+
+  // Safety net: a big upload opens one SSE stream per doc, but HTTP/1.1 caps
+  // concurrent connections, so streams past the cap may never deliver a terminal
+  // frame and leave a chip spinning. While anything is indexing, reconcile against
+  // the document list (one request covers every doc) so chips always resolve.
+  const hasIndexing = documents.some(
+    (d) => d.status === "pending" || d.status === "running",
+  );
+  useEffect(() => {
+    if (!scopeKey || !hasIndexing) return;
+    const id = setInterval(() => void refresh({ quiet: true }), 4000);
+    return () => clearInterval(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scopeKey, hasIndexing]);
+
+  // POST one file, then swap its optimistic chip (`tempId`) to the real id; drop
+  // the chip if the backend deduped. `seenIds` holds ids present/added this batch.
+  const uploadOne = useCallback(
+    async (
+      file: File,
+      seenIds: Set<string>,
+      activeScope: RagDocumentScope,
+      tempId: string,
+    ) => {
+      try {
+        const result =
+          activeScope.type === "kb"
+            ? await uploadKnowledgeBaseDocument(activeScope.kbId, file)
+            : await uploadThreadDocument(activeScope.threadId, file);
+        sigByDocId.current.set(result.documentId, fileSignature(file));
+        if (seenIds.has(result.documentId)) {
+          setDocuments((rows) => rows.filter((row) => row.id !== tempId));
+          toast.info(`${result.filename || file.name} is already indexed - skipping`);
+          return;
+        }
+        seenIds.add(result.documentId);
+        setDocuments((rows) =>
+          rows.map((row) =>
+            row.id === tempId
+              ? {
+                  ...row,
+                  id: result.documentId,
+                  filename: result.filename || row.filename,
+                  status: "running",
+                }
+              : row,
+          ),
+        );
+        trackJob(result.jobId, result.documentId, result.filename || file.name);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Drop the chip rather than show "Failed"; warn via toast.
+        setDocuments((rows) => rows.filter((row) => row.id !== tempId));
+        toast.error(`Couldn't upload ${file.name}`, { description: message });
+      }
+    },
+    [trackJob],
+  );
+
+  // `overrideScope` lets a caller pass a freshly-resolved scope (or a promise of
+  // one), since the thread bar's id is still null on the first click; falls back to
+  // the hook scope.
+  const upload = useCallback(
+    async (
+      files: FileList | File[],
+      overrideScope?: RagDocumentScope | Promise<RagDocumentScope | null>,
+    ) => {
+      // Flip the in-flight guard synchronously, before awaiting a thread id that
+      // may still be materializing, so the scope-change effect reads it and leaves
+      // job tracking and optimistic chips alone.
+      uploadInFlightRef.current = true;
+      setUploading(true);
+      try {
+        // Show an optimistic chip per file before awaiting the thread id;
+        // materialization is a round-trip and gating chips behind it makes a slow
+        // one look like nothing happened. Dedup re-selections up front.
+        const fresh: Array<{ tempId: string; file: File }> = [];
+        for (const file of Array.from(files)) {
+          if (sigAttached(fileSignature(file))) {
+            toast.info(`${file.name} is already indexed - skipping`);
+            continue;
+          }
+          fresh.push({
+            tempId: `pending_${Math.random().toString(36).slice(2)}`,
+            file,
+          });
+        }
+        if (fresh.length === 0) return;
+        setDocuments((rows) => [
+          ...rows,
+          ...fresh.map(({ tempId, file }) => ({
+            id: tempId,
+            filename: file.name,
+            status: "pending" as const,
+            progress: null,
+          })),
+        ]);
+
+        const resolved =
+          overrideScope instanceof Promise ? await overrideScope : overrideScope;
+        const activeScope = resolved ?? scope;
+        if (!activeScope) {
+          // Materialization failed: drop the chips so they don't hang "pending".
+          const tempIds = new Set(fresh.map((f) => f.tempId));
+          setDocuments((rows) => rows.filter((row) => !tempIds.has(row.id)));
+          toast.error("Couldn't attach documents", {
+            description: "Could not start a chat to attach them to.",
+          });
+          return;
+        }
+
+        const seenIds = new Set(
+          documentsRef.current
+            .filter((d) => !d.id.startsWith("pending_"))
+            .map((d) => d.id),
+        );
+        for (const { tempId, file } of fresh) {
+          await uploadOne(file, seenIds, activeScope, tempId);
+        }
+      } finally {
+        setUploading(false);
+        uploadInFlightRef.current = false;
+      }
+    },
+    [scope, uploadOne, sigAttached],
+  );
+
+  const remove = useCallback(
+    async (documentId: string) => {
+      const prev = documents;
+      setDocuments((rows) => rows.filter((row) => row.id !== documentId));
+      // Forget the dedup signature so re-uploading re-indexes.
+      const prevSig = sigByDocId.current.get(documentId);
+      sigByDocId.current.delete(documentId);
+      try {
+        await deleteDocument(documentId);
+      } catch (err) {
+        setDocuments(prev);
+        if (prevSig !== undefined) sigByDocId.current.set(documentId, prevSig);
+        toast.error("Delete failed", {
+          description: err instanceof Error ? err.message : String(err),
+        });
+      }
+    },
+    [documents],
+  );
+
+  return { documents, loading, uploading, refresh, upload, remove };
+}
diff --git a/studio/frontend/src/features/rag/index.ts b/studio/frontend/src/features/rag/index.ts
new file mode 100644
index 0000000000..9e35e345ee
--- /dev/null
+++ b/studio/frontend/src/features/rag/index.ts
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export { KnowledgeBaseComposerButton } from "./components/knowledge-base-composer-button";
+export { KnowledgeBaseDialog } from "./components/knowledge-base-dialog";
+export { RetrievalSettingsSection } from "./components/retrieval-settings-section";
+export { ThreadDocumentsBar } from "./components/thread-documents-bar";
+export type { KnowledgeBase, RagDocument } from "./types/rag";
diff --git a/studio/frontend/src/features/rag/types/rag.ts b/studio/frontend/src/features/rag/types/rag.ts
new file mode 100644
index 0000000000..0f8c684ef7
--- /dev/null
+++ b/studio/frontend/src/features/rag/types/rag.ts
@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+export interface KnowledgeBase {
+  id: string;
+  name: string;
+  description?: string | null;
+  createdAt?: string | null;
+  documentCount?: number;
+}
+
+/** Index status: pending -> running -> completed | failed. */
+export type DocumentStatus = "pending" | "running" | "completed" | "failed";
+
+export interface RagDocument {
+  id: string;
+  filename: string;
+  status: DocumentStatus;
+  error?: string | null;
+  numChunks?: number | null;
+  kbId?: string | null;
+  threadId?: string | null;
+  createdAt?: string | null;
+}
+
+export interface DocumentUploadResult {
+  documentId: string;
+  jobId: string;
+  filename: string;
+}
+
+export type JobStatus = "pending" | "running" | "completed" | "failed";
+
+export interface IndexJob {
+  id: string;
+  documentId: string;
+  status: JobStatus;
+  stage?: string | null;
+  progress?: number | null;
+  error?: string | null;
+}
+
+/** One SSE frame from /jobs/{jobId}/events. */
+export interface JobEvent {
+  type: "progress" | "complete" | "error";
+  stage?: string | null;
+  progress?: number | null;
+  error?: string | null;
+}
+
+/** Coords 0..1, top-left origin. */
+export interface PdfRegion {
+  pageIndex: number;
+  pageNumber: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PreviewTarget {
+  documentId: string;
+  filename: string;
+  mediaKind: "pdf" | "text";
+  targetPage?: number | null;
+  pdfRegions: PdfRegion[];
+  text?: string | null;
+}
+
+export const RAG_UPLOAD_ACCEPT = ".pdf,.txt,.md,.markdown,.docx,.html,.htm";
diff --git a/studio/frontend/src/features/studio/sections/model-section.tsx b/studio/frontend/src/features/studio/sections/model-section.tsx
index cc5717692a..425f55eb53 100644
--- a/studio/frontend/src/features/studio/sections/model-section.tsx
+++ b/studio/frontend/src/features/studio/sections/model-section.tsx
@@ -45,6 +45,7 @@ import {
   useHfTokenValidation,
   useInfiniteScroll,
 } from "@/hooks";
+import { extractParamLabel } from "@/lib/model-size";
 import { formatCompact } from "@/lib/utils";
 import {
   type VramFitStatus,
@@ -78,13 +79,6 @@ const DARK_CONTENT =
 const DARK_COMBOBOX_CONTENT =
   "bg-foreground text-background shadow-xl border-background/10 dark:[--accent:rgba(2,6,23,0.08)] dark:[--accent-foreground:rgb(2,6,23)] dark:[&_[data-slot=combobox-item]]:text-slate-900 dark:[&_.text-muted-foreground]:text-slate-500";
 
-/** Extract param count label from model name (e.g. "Qwen3-0.6B" -> "0.6B"). */
-function extractParamLabel(id: string): string | null {
-  const name = id.split("/").pop() ?? id;
-  const match = name.match(/(?:^|[-_])(\d+(?:\.\d+)?)[Bb](?:[-_]|$)/);
-  return match ? `${match[1]}B` : null;
-}
-
 export function ModelSection() {
   const t = useT();
   const gpu = useGpuInfo();
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 521fe28190..07bef147d7 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -45,6 +45,16 @@
 		height: 40px;
 		background: linear-gradient(to top, var(--sidebar), transparent);
 	}
+	/* RAG chip strip: sidebar-style bottom fade while more chips sit below
+	   the scroll fold (JS-toggled). */
+	.rag-docs-bottom-fade {
+		-webkit-mask-image: linear-gradient(
+			to bottom,
+			#000 calc(100% - 16px),
+			transparent
+		);
+		mask-image: linear-gradient(to bottom, #000 calc(100% - 16px), transparent);
+	}
 }
 
 @layer base {
diff --git a/studio/frontend/src/lib/model-size.ts b/studio/frontend/src/lib/model-size.ts
new file mode 100644
index 0000000000..5e0e582639
--- /dev/null
+++ b/studio/frontend/src/lib/model-size.ts
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// The leading boundary skips family-version digits ("Qwen3-") and MoE active-param
+// notation ("A3B"), so "Qwen3-30B-A3B" reads as 30B total, not 3B active.
+const PARAM_COUNT_RE = /(?:^|[-_])(\d+(?:\.\d+)?)[Bb](?:[-_]|$)/;
+
+function matchParamCount(id: string): RegExpMatchArray | null {
+  const name = id.split("/").pop() ?? id;
+  return name.match(PARAM_COUNT_RE);
+}
+
+export function extractParamLabel(id: string): string | null {
+  const m = matchParamCount(id);
+  return m ? `${m[1]}B` : null;
+}
+
+export function parseParamCountB(id: string): number | null {
+  const m = matchParamCount(id);
+  if (!m) return null;
+  const v = Number.parseFloat(m[1]);
+  return Number.isFinite(v) ? v : null;
+}

From 03349d1e05452cf5612ccfc54bb7e151e96227f4 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Tue, 9 Jun 2026 22:52:39 -0700
Subject: [PATCH 127/222] feat: support text-only loading of Gemma 3 27B via
 FastLanguageModel (skip SiglipVisionModel) (#5816)

* feat: support text-only loading of Gemma 3 27B via FastLanguageModel (skip SiglipVisionModel)

* test: instantiate text-only Gemma3 model and assert no vision tower

Existing tests were AST source-introspection plus a config-resolves-to-
text-config check; none actually instantiated a model from the
text-only config. Add a small integration test that builds a shrunken
Gemma3TextConfig (CPU-cheap), instantiates the matching CausalLM
class, and asserts the resulting model exposes the LM head and has no
vision_tower or multi_modal_projector attribute.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Deduplicate _get_text_only_config into _utils for PR #5816

* Fall back to full model when a VLM has no text-only class for PR #5816

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Preserve quantization_config and clarify warning for text-only loading for PR #5816

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Only take text-only path when the VLM has its own text decoder for PR #5816

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Convert source string-match assertions to AST checks per Gemini review

* Load real VLM text weights on transformers 5.x for text-only mode in PR #5816

transformers >=5 changed Gemma3ForCausalLM base_model_prefix from language_model to model, so a VLM checkpoint's text weights (gemma3: language_model.model.*, gemma3n: model.language_model.*) no longer auto-strip onto the text decoder and were silently initialized random. Add a version-gated key_mapping that remaps them onto the text keys, returning None on transformers <5 where the prefix still strips and a mapping would break the load.

Apply the same family-guarded remap on the load_in_fp8 offline path and for direct FastBaseModel callers, and remap quantization llm_int8_skip_modules off the wrapper prefix after stripping.

Add a regression test that loads real VLM checkpoint weights (the prior tests only instantiated a fresh model so they missed this) and drop the bitsandbytes dependency from the quantization-config test.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Separate FP8 text-only cache and hoist the text-only guard for PR #5816

Address review of the text-only changes: (1) _offline_quantize_to_fp8 produced different artifacts for text-only vs full VLM but reused the same <name>-fp8-<mode> cache dir, so one mode could load the other's saved model; decide text-only before the cache name and add a -text-only suffix. (2) FastBaseModel.from_pretrained rewrote the VLM auto class to AutoModelForCausalLM before loading auto_config and before the family check, leaving is_vlm wrong for the fast_inference/vLLM block; hoist the family-guarded text-only decision above those checks and drop the redundant later block. (3) Wire the text-only regression test into the curated CPU pytest job so it runs in CI across the transformers matrix.

* Trim text-only code comments for PR #5816

Shorten and de-duplicate the comments added for the text-only loading work; keep the non-obvious rationale (the transformers >=5 base_model_prefix change) and drop the obvious parts. Comments only, no code changes; AST-based tests still pass on transformers 4.57.6 and 5.4.0.

* Make text-only loading opt-in via a public text_only argument for PR #5816

Rename the internal _force_text_only flag to a public text_only parameter on FastLanguageModel, FastModel and FastBaseModel (and the fp8 helper), defaulting False on all three. Text-only loading is now opt-in (text_only=True) instead of forced on by FastLanguageModel; the family guard and key remap are unchanged. Updated the AST tests for the new parameter and forwarding.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Trim text-only code comments for clarity

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .github/workflows/consolidated-tests-ci.yml   |  14 +-
 .../test_fast_language_model_text_only.py     | 433 ++++++++++++++++++
 unsloth/models/_utils.py                      |  93 ++++
 unsloth/models/loader.py                      |  36 +-
 unsloth/models/loader_utils.py                |  71 ++-
 unsloth/models/vision.py                      |  29 ++
 6 files changed, 647 insertions(+), 29 deletions(-)
 create mode 100644 tests/python/test_fast_language_model_text_only.py

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index 7e8d52525c..c6c2e1fc37 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -269,7 +269,8 @@ jobs:
             tests/saving/test_patch_saving_none_tokenizer.py \
             tests/saving/test_fix_sentencepiece_gguf_robustness.py \
             tests/utils/test_attention_masks.py \
-            tests/utils/test_trunc_normal_patch.py
+            tests/utils/test_trunc_normal_patch.py \
+            tests/python/test_fast_language_model_text_only.py
           python -m pytest --collect-only -q "$RUNNER_TEMP/unsloth-zoo/tests/"
 
       - name: import_fixes drift detectors (18 tests, HARD GATE)
@@ -333,11 +334,9 @@ jobs:
           python -m pytest -v --tb=short tests/test_callback_signature_drift.py
 
       - name: unsloth Bucket-A — CPU tests not in Repo tests (CPU)
-        # 16 tests across 5 files. They live inside tests/saving/ and
-        # tests/utils/, both of which Repo tests (CPU) excludes via --ignore
-        # because their sibling files need real GPUs / real HF weights.
-        # The five files below are pure-Python + AST/protobuf/regex tests
-        # that run cleanly on CPU. Env inherited from the job block.
+        # CPU tests across 6 files under tests/saving/, tests/utils/, tests/python/
+        # that Repo tests (CPU) --ignores. AST/protobuf/regex plus tiny CPU model
+        # loads; run cleanly here (transformers/torch installed).
         run: |
           python -m pytest -q --tb=short \
             tests/saving/test_save_shell_injection.py \
@@ -345,11 +344,12 @@ jobs:
             tests/saving/test_fix_sentencepiece_gguf_robustness.py \
             tests/utils/test_attention_masks.py \
             tests/utils/test_trunc_normal_patch.py \
+            tests/python/test_fast_language_model_text_only.py \
             --deselect 'tests/utils/test_attention_masks.py::test_run_attention_flash_varlen_receives_window_and_softcap'
           # The deselected test monkeypatches flash_attn_varlen_func, which is
           # only bound on the module when `flash_attn` is importable. flash_attn
           # requires CUDA + dev toolchain, which the CPU-only ubuntu-latest
-          # runner does not have. The other 15 Bucket-A tests pass cleanly.
+          # runner does not have. The other Bucket-A tests pass cleanly.
 
       - name: unsloth_zoo @ ${{ env.UNSLOTH_ZOO_REF }} — full pytest (CPU)
         # 106 of 111 test_* in unsloth_zoo are CPU-only. The two CUDA-skip
diff --git a/tests/python/test_fast_language_model_text_only.py b/tests/python/test_fast_language_model_text_only.py
new file mode 100644
index 0000000000..ce4dd74439
--- /dev/null
+++ b/tests/python/test_fast_language_model_text_only.py
@@ -0,0 +1,433 @@
+"""Text-only FastLanguageModel routing for vision-capable configs."""
+
+import ast
+import copy
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LOADER_PATH = REPO_ROOT / "unsloth" / "models" / "loader.py"
+VISION_PATH = REPO_ROOT / "unsloth" / "models" / "vision.py"
+UTILS_PATH = REPO_ROOT / "unsloth" / "models" / "_utils.py"
+
+
+def _source(path):
+    return path.read_text()
+
+
+def _class_method(tree, class_name, method_name):
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef) and item.name == method_name:
+                    return item
+    raise AssertionError(f"{class_name}.{method_name} not found")
+
+
+def _assigns_name(method, target_name, predicate):
+    """True when the method contains `target_name = <value>` and predicate(value)."""
+    for node in ast.walk(method):
+        if not isinstance(node, ast.Assign):
+            continue
+        for target in node.targets:
+            if isinstance(target, ast.Name) and target.id == target_name:
+                if predicate(node.value):
+                    return True
+    return False
+
+
+def _calls_function(method, func_name):
+    """True when the method calls `func_name(...)` (bare name, not attribute)."""
+    for node in ast.walk(method):
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id == func_name
+        ):
+            return True
+    return False
+
+
+def _names_in(node):
+    return {n.id for n in ast.walk(node) if isinstance(n, ast.Name)}
+
+
+def _param_default(method, name):
+    # Default-value AST node for a named parameter, or None.
+    args = method.args
+    params = list(args.args) + list(args.kwonlyargs)
+    defaults = list(args.defaults) + list(args.kw_defaults)
+    return dict(zip([p.arg for p in params][-len(defaults) :], defaults)).get(name)
+
+
+def _load_text_only_namespace():
+    # Exec the text-only helpers from _utils into one namespace (no unsloth import),
+    # in dependency order so cross-references resolve.
+    source = _source(UTILS_PATH)
+    import transformers
+    from packaging.version import Version
+
+    ns = {
+        "copy": copy,
+        "Version": Version,
+        "transformers_version": transformers.__version__,
+    }
+    funcs = {
+        node.name: ast.get_source_segment(source, node)
+        for node in ast.parse(source).body
+        if isinstance(node, ast.FunctionDef)
+    }
+    for name in (
+        "resolve_model_class",
+        "_is_family_text_decoder",
+        "_remap_text_only_skip_modules",
+        "_get_text_only_config",
+        "_get_text_only_key_mapping",
+        "_apply_text_only_key_mapping",
+    ):
+        if name in funcs:
+            exec(funcs[name], ns)
+    return ns
+
+
+def _load_text_only_helper():
+    return _load_text_only_namespace()["_get_text_only_config"]
+
+
+def test_gemma3_vision_config_resolves_to_text_config():
+    transformers = pytest.importorskip("transformers")
+    helper = _load_text_only_helper()
+
+    config = transformers.Gemma3Config()
+    text_config = helper(config, "google/gemma-3-27b-it")
+
+    assert isinstance(text_config, transformers.Gemma3TextConfig)
+    assert text_config.model_type == "gemma3_text"
+    model_class = transformers.AutoModelForCausalLM._model_mapping[type(text_config)]
+    assert model_class.__name__ == "Gemma3ForCausalLM"
+
+
+def test_text_only_helper_rejects_configs_without_text_submodel():
+    helper = _load_text_only_helper()
+
+    class VisionOnlyConfig:
+        vision_config = object()
+
+    with pytest.raises(ValueError, match = "Cannot load vision-only as text-only"):
+        helper(VisionOnlyConfig(), "vision-only")
+
+
+def test_fast_language_model_forwards_text_only_to_fast_model():
+    source = _source(LOADER_PATH)
+    method = _class_method(ast.parse(source), "FastLanguageModel", "from_pretrained")
+
+    # text_only defaults False (opt-in, not forced True), and both FastModel
+    # delegations forward it.
+    text_only_default = _param_default(method, "text_only")
+    assert isinstance(text_only_default, ast.Constant) and text_only_default.value is False
+
+    fast_model_calls = [
+        node
+        for node in ast.walk(method)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "from_pretrained"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "FastModel"
+    ]
+    assert len(fast_model_calls) == 2
+    for call in fast_model_calls:
+        kw = [k for k in call.keywords if k.arg == "text_only"]
+        assert len(kw) == 1
+        assert isinstance(kw[0].value, ast.Name) and kw[0].value.id == "text_only"
+
+
+def test_fast_model_text_only_does_not_override_explicit_auto_model():
+    # AST-based so formatting/refactors that keep the structure do not break it.
+    source = _source(LOADER_PATH)
+    method = _class_method(ast.parse(source), "FastModel", "from_pretrained")
+
+    text_only_default = _param_default(method, "text_only")
+    assert isinstance(text_only_default, ast.Constant) and text_only_default.value is False
+
+    # load_text_only is text_only AND a check that the caller did not pass auto_model.
+    def _is_guarded_bool(value):
+        names = _names_in(value)
+        has_none_check = any(
+            isinstance(n, ast.Compare) and any(isinstance(op, (ast.Is, ast.IsNot)) for op in n.ops)
+            for n in ast.walk(value)
+        )
+        return "text_only" in names and "auto_model" in names and has_none_check
+
+    assert _assigns_name(method, "load_text_only", _is_guarded_bool)
+
+    assert _calls_function(method, "_get_text_only_config")
+
+    def _forwards_kwarg(node):
+        return any(
+            isinstance(n, ast.Call)
+            and any(
+                kw.arg == "text_only"
+                and isinstance(kw.value, ast.Name)
+                and kw.value.id == "load_text_only"
+                for kw in n.keywords
+            )
+            for n in ast.walk(node)
+        )
+
+    assert _forwards_kwarg(method)
+    # Falls back to the full model unless the family has its own text decoder.
+    assert _calls_function(method, "_is_family_text_decoder")
+    assert _assigns_name(
+        method,
+        "load_text_only",
+        lambda v: isinstance(v, ast.Constant) and v.value is False,
+    )
+
+
+def test_fast_base_model_text_only_bypasses_vision_auto_model():
+    source = _source(VISION_PATH)
+    method = _class_method(ast.parse(source), "FastBaseModel", "from_pretrained")
+
+    text_only_default = _param_default(method, "text_only")
+    assert isinstance(text_only_default, ast.Constant) and text_only_default.value is False
+
+    assert _assigns_name(
+        method,
+        "auto_model",
+        lambda v: isinstance(v, ast.Name) and v.id == "AutoModelForCausalLM",
+    )
+    # Text-only path: strip config, apply the family guard, inject the key remap.
+    assert _calls_function(method, "_get_text_only_config")
+    assert _calls_function(method, "_is_family_text_decoder")
+    assert _calls_function(method, "_apply_text_only_key_mapping")
+
+
+def test_gemma3_text_only_model_class_resolves_and_has_no_vision_tower():
+    """Tiny end-to-end: build a Gemma3 text-only config, instantiate the
+    matching model class with shrunken hidden sizes, assert it has the
+    text language model attributes and no vision tower attribute.
+
+    This is the integration check the AST-only tests were missing -- it
+    proves the text-only routing actually produces a model that can be
+    instantiated and that the resulting model is purely text. We use
+    shrunken hidden sizes so the test is fast and CPU-only.
+    """
+    transformers = pytest.importorskip("transformers")
+    helper = _load_text_only_helper()
+
+    full_config = transformers.Gemma3Config()
+    text_config = helper(full_config, "google/gemma-3-27b-it")
+
+    # Shrink for a cheap CPU instantiation; keep the shape attrs read at construction.
+    text_config.num_hidden_layers = 1
+    text_config.hidden_size = 32
+    text_config.intermediate_size = 32
+    text_config.num_attention_heads = 2
+    text_config.num_key_value_heads = 1
+    text_config.head_dim = 16
+    text_config.vocab_size = 128
+
+    model_class = transformers.AutoModelForCausalLM._model_mapping[type(text_config)]
+    model = model_class(text_config)
+
+    # Positive checks: text language model surface is present.
+    assert hasattr(model, "lm_head"), "text-only Gemma3 model should expose lm_head"
+
+    # Negative checks: no vision tower / multimodal projector remains.
+    assert not hasattr(
+        model, "vision_tower"
+    ), "text-only Gemma3 model should not have a vision_tower"
+    assert not hasattr(
+        model, "multi_modal_projector"
+    ), "text-only Gemma3 model should not have a multi_modal_projector"
+
+
+def test_helper_defined_once_in_utils_and_imported():
+    # _get_text_only_config is defined only in _utils and imported by loader + vision.
+    def _defines(path):
+        return any(
+            isinstance(n, ast.FunctionDef) and n.name == "_get_text_only_config"
+            for n in ast.parse(_source(path)).body
+        )
+
+    def _imports(path):
+        return any(
+            isinstance(n, ast.ImportFrom)
+            and n.module == "_utils"
+            and any(a.name == "_get_text_only_config" for a in n.names)
+            for n in ast.walk(ast.parse(_source(path)))
+        )
+
+    assert _defines(UTILS_PATH)
+    assert not _defines(LOADER_PATH) and _imports(LOADER_PATH)
+    assert not _defines(VISION_PATH) and _imports(VISION_PATH)
+
+
+def _load_util_func(name):
+    ns = _load_text_only_namespace()
+    if name not in ns:
+        raise AssertionError(f"{name} not found")
+    return ns[name]
+
+
+def test_text_only_guard_predicate_across_vlm_families():
+    # Text-only is taken only when the resolved class remaps VLM weights.
+    transformers = pytest.importorskip("transformers")
+    from transformers import AutoModelForCausalLM
+
+    resolve = _load_util_func("resolve_model_class")
+    is_family = _load_util_func("_is_family_text_decoder")
+    helper = _load_text_only_helper()
+
+    def takes_text_only(cfg):
+        text = helper(cfg, "x")
+        return resolve(AutoModelForCausalLM, text) is not None and is_family(
+            getattr(cfg, "model_type", ""), getattr(text, "model_type", "")
+        )
+
+    # Dedicated text decoder remaps language_model.* -> strip vision.
+    assert takes_text_only(transformers.Gemma3Config()) is True
+
+    # No text class (Qwen2-VL/Mllama) or a generic reused decoder that would
+    # load random weights (Llava/PaliGemma/Idefics3/InternVL) -> keep full model.
+    for name in [
+        "Qwen2VLConfig",
+        "Qwen2_5_VLConfig",
+        "MllamaConfig",
+        "LlavaConfig",
+        "PaliGemmaConfig",
+        "Idefics3Config",
+        "InternVLConfig",
+    ]:
+        cfg_cls = getattr(transformers, name, None)
+        if cfg_cls is None:
+            continue
+        assert takes_text_only(cfg_cls()) is False, name
+
+
+def test_text_only_helper_preserves_quantization_config():
+    # quantization_config must survive the strip so pre-quantized repos still load. A
+    # sentinel object avoids a bitsandbytes dependency on transformers 4.51.3.
+    transformers = pytest.importorskip("transformers")
+    helper = _load_text_only_helper()
+    config = transformers.Gemma3Config()
+    sentinel = object()
+    config.quantization_config = sentinel
+    text_config = helper(config, "google/gemma-3-27b-it")
+    assert getattr(text_config, "quantization_config", None) is sentinel
+    # The parent's shared text sub-config must not be mutated by the carry-over.
+    assert getattr(config.get_text_config(), "quantization_config", None) is None
+
+
+def test_text_only_key_mapping_targets_published_prefixes():
+    # The mapping must remap the published VLM decoder prefixes and only apply on
+    # transformers >=5 (on 4.x base_model_prefix handles it and a mapping hurts).
+    transformers = pytest.importorskip("transformers")
+    get_key_mapping = _load_util_func("_get_text_only_key_mapping")
+    mapping = get_key_mapping(transformers.Gemma3Config(), transformers.Gemma3TextConfig())
+    if int(transformers.__version__.split(".")[0]) < 5:
+        assert mapping is None
+    else:
+        assert isinstance(mapping, dict)
+        assert mapping.get(r"^language_model\.model\.") == "model."  # gemma3
+        assert mapping.get(r"^model\.language_model\.") == "model."  # gemma3n
+        assert mapping.get(r"^language_model\.lm_head\.") == "lm_head."
+
+
+def test_gemma3_text_only_loads_real_language_weights_from_vlm_checkpoint(tmp_path):
+    # Regression for PR #5816: text-only loading of a Gemma 3 VLM checkpoint must load the
+    # real language weights, not random ones. Fails on tf >=5 without the key_mapping fix.
+    transformers = pytest.importorskip("transformers")
+    torch = pytest.importorskip("torch")
+    import shutil
+    from safetensors.torch import load_file, save_file
+
+    get_text_config = _load_text_only_helper()
+    get_key_mapping = _load_util_func("_get_text_only_key_mapping")
+
+    sentinel = 0.1234
+    text_cfg = transformers.Gemma3TextConfig(
+        hidden_size = 32,
+        intermediate_size = 64,
+        num_hidden_layers = 1,
+        num_attention_heads = 2,
+        num_key_value_heads = 1,
+        head_dim = 16,
+        vocab_size = 128,
+        max_position_embeddings = 128,
+        sliding_window = 64,
+    )
+    vision_cfg = transformers.SiglipVisionConfig(
+        hidden_size = 32,
+        intermediate_size = 64,
+        num_hidden_layers = 1,
+        num_attention_heads = 2,
+        image_size = 16,
+        patch_size = 8,
+        num_channels = 3,
+    )
+    full_config = transformers.Gemma3Config(
+        text_config = text_cfg.to_dict(),
+        vision_config = vision_cfg.to_dict(),
+    )
+    full_model = transformers.Gemma3ForConditionalGeneration(full_config)
+
+    state = full_model.state_dict()
+    text_q = [
+        k
+        for k in state
+        if "language_model" in k
+        and "vision" not in k
+        and k.endswith("layers.0.self_attn.q_proj.weight")
+    ]
+    assert text_q, [k for k in state if "q_proj" in k][:5]
+    with torch.no_grad():
+        for k in text_q:
+            state[k].fill_(sentinel)
+
+    save_dir = tmp_path / "vlm"
+    full_model.save_pretrained(save_dir, safe_serialization = True)
+
+    # tf >=5 saves under an outer "model." prefix; strip it to reproduce the real
+    # language_model.model.* layout the published Gemma 3 checkpoints use.
+    real_dir = tmp_path / "real"
+    real_dir.mkdir()
+    weights = {}
+    for f in save_dir.glob("*.safetensors"):
+        weights.update(load_file(str(f)))
+    for f in save_dir.glob("*.bin"):
+        weights.update(torch.load(f, map_location = "cpu", weights_only = True))
+    weights = {
+        (k[len("model.") :] if k.startswith("model.") else k): v.contiguous()
+        for k, v in weights.items()
+    }
+    for p in save_dir.iterdir():
+        if not p.name.endswith((".safetensors", ".bin", ".index.json")):
+            shutil.copy(p, real_dir / p.name)
+    save_file(weights, str(real_dir / "model.safetensors"))
+
+    text_config = get_text_config(full_config, "google/gemma-3-27b-it")
+    load_kwargs = {}
+    key_mapping = get_key_mapping(full_config, text_config)
+    if key_mapping is not None:
+        load_kwargs["key_mapping"] = key_mapping
+    model = transformers.AutoModelForCausalLM.from_pretrained(
+        real_dir,
+        config = text_config,
+        dtype = torch.float32,
+        local_files_only = True,
+        **load_kwargs,
+    )
+
+    loaded = model.state_dict()
+    q_key = [k for k in loaded if k.endswith("model.layers.0.self_attn.q_proj.weight")]
+    assert q_key, "text decoder q_proj weight missing from the loaded model"
+    assert float(loaded[q_key[0]].flatten()[0]) == pytest.approx(
+        sentinel
+    ), "text weights were randomly initialized instead of loaded from the checkpoint"
+    assert not any(
+        "vision_tower" in n for n, _ in model.named_modules()
+    ), "vision tower should be skipped on the text-only path"
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 486a907478..23723e1d27 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -92,6 +92,7 @@ from platform import system as platform_system
 platform_system = platform_system()
 import numpy as np
 import contextlib
+import copy
 import re
 from dataclasses import dataclass, field
 import functools
@@ -472,6 +473,98 @@ def resolve_model_class(auto_model, config):
     return result[0] if isinstance(result, (list, tuple)) else result
 
 
+def _is_family_text_decoder(parent_model_type, text_model_type):
+    # True only for the family's own text variant (gemma3 -> gemma3_text); a generic
+    # reused decoder (llava -> llama) would load random weights, so keep the full model.
+    return bool(parent_model_type) and str(text_model_type).startswith(parent_model_type)
+
+
+def _get_text_only_config(model_config, model_name):
+    # Text sub-config of a vision-language config so FastLanguageModel skips the vision tower (PR #5816).
+    text_config = None
+    if hasattr(model_config, "get_text_config"):
+        text_config = model_config.get_text_config()
+    if text_config is None:
+        text_config = getattr(model_config, "text_config", None)
+    if text_config is None:
+        raise ValueError(f"Cannot load {model_name} as text-only; use FastVisionModel")
+    # Carry over quantization_config; copy first since get_text_config() shares the parent's object.
+    qc = getattr(model_config, "quantization_config", None)
+    if qc is not None and getattr(text_config, "quantization_config", None) is None:
+        text_config = copy.copy(text_config)
+        text_config.quantization_config = _remap_text_only_skip_modules(qc)
+    return text_config
+
+
+def _remap_text_only_skip_modules(qc):
+    # Remap llm_int8_skip_modules off the VLM wrapper prefix (language_model.model.* ->
+    # model.*) after text-only stripping, and drop vision/audio entries. See PR #5816.
+    is_dict = isinstance(qc, dict)
+    skip = (
+        qc.get("llm_int8_skip_modules") if is_dict else getattr(qc, "llm_int8_skip_modules", None)
+    )
+    if not skip:
+        return qc
+    remapped = []
+    for name in skip:
+        for pref in (
+            "language_model.model.",
+            "model.language_model.",
+            "language_model.",
+        ):
+            if name.startswith(pref):
+                name = (
+                    ("model." + name[len(pref) :])
+                    if pref != "language_model."
+                    else name[len(pref) :]
+                )
+                break
+        if name.startswith(
+            (
+                "vision_tower",
+                "multi_modal_projector",
+                "audio_tower",
+                "modality_projection",
+            )
+        ):
+            continue
+        remapped.append(name)
+    remapped = list(dict.fromkeys(remapped))
+    qc = dict(qc) if is_dict else copy.copy(qc)
+    if is_dict:
+        qc["llm_int8_skip_modules"] = remapped
+    else:
+        qc.llm_int8_skip_modules = remapped
+    return qc
+
+
+def _get_text_only_key_mapping(parent_config, text_config):
+    # transformers >=5 stopped auto-stripping the VLM wrapper prefix (base_model_prefix
+    # changed language_model -> model), so remap the text weights onto the decoder keys.
+    # None on tf <5 (still strips; a mapping would break the load) or non-family. See PR #5816.
+    if Version(transformers_version) < Version("5.0.0"):
+        return None
+    if not _is_family_text_decoder(
+        getattr(parent_config, "model_type", ""),
+        getattr(text_config, "model_type", ""),
+    ):
+        return None
+    return {
+        r"^language_model\.model\.": "model.",
+        r"^model\.language_model\.": "model.",
+        r"^language_model\.lm_head\.": "lm_head.",
+    }
+
+
+def _apply_text_only_key_mapping(kwargs, parent_config, text_config):
+    # Add the text-only key_mapping to from_pretrained kwargs, under any user mapping.
+    mapping = _get_text_only_key_mapping(parent_config, text_config)
+    if not mapping:
+        return
+    user_mapping = kwargs.get("key_mapping", None)
+    kwargs["key_mapping"] = {**mapping, **user_mapping} if user_mapping else mapping
+
+
 def resolve_attention_implementation(
     model_class,
     config,
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index b0ce28969e..67d1ce9b8d 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -97,6 +97,10 @@ from ._utils import (
     process_vision_info,
     unsloth_compile_transformers,
     fast_inference_setup,
+    _get_text_only_config,
+    resolve_model_class,
+    _is_family_text_decoder,
+    _apply_text_only_key_mapping,
 )
 
 # Single source of truth is unsloth_zoo.model_lists. Re-exported so callers
@@ -256,6 +260,7 @@ class FastLanguageModel(FastLlamaModel):
         qat_scheme = None,
         load_in_fp8 = False,  # fp8 LoRA (True, False, 'block')
         unsloth_tiled_mlp = False,
+        text_only = False,  # Skip vision/audio towers and load only the text decoder
         *args,
         **kwargs,
     ):
@@ -342,6 +347,7 @@ class FastLanguageModel(FastLlamaModel):
                 qat_scheme = qat_scheme,
                 load_in_fp8 = load_in_fp8,
                 unsloth_tiled_mlp = unsloth_tiled_mlp,
+                text_only = text_only,
                 *args,
                 **kwargs,
             )
@@ -400,7 +406,7 @@ class FastLanguageModel(FastLlamaModel):
                     load_in_8bit,
                     load_in_16bit,
                 )
-                model_name = _offline_quantize_to_fp8(model_name, fp8_mode)
+                model_name = _offline_quantize_to_fp8(model_name, fp8_mode, text_only = text_only)
             else:
                 assert new_model_name is not None
                 model_name = new_model_name
@@ -687,6 +693,7 @@ class FastLanguageModel(FastLlamaModel):
                 qat_scheme = qat_scheme,
                 load_in_fp8 = load_in_fp8,
                 unsloth_tiled_mlp = unsloth_tiled_mlp,
+                text_only = text_only,
                 *args,
                 **kwargs,
             )
@@ -868,6 +875,7 @@ class FastModel(FastBaseModel):
         load_in_fp8 = False,  # fp8 LoRA (True, False, 'block')
         unsloth_tiled_mlp = False,
         target_parameters = None,  # For MoE expert parameters
+        text_only = False,  # Skip vision/audio towers and load only the text decoder
         *args,
         **kwargs,
     ):
@@ -997,7 +1005,7 @@ class FastModel(FastBaseModel):
                     load_in_8bit,
                     load_in_16bit,
                 )
-                model_name = _offline_quantize_to_fp8(model_name, fp8_mode)
+                model_name = _offline_quantize_to_fp8(model_name, fp8_mode, text_only = text_only)
             else:
                 assert new_model_name is not None
                 model_name = new_model_name
@@ -1408,6 +1416,29 @@ class FastModel(FastBaseModel):
             architectures = []
         is_vlm = any(x.endswith("ForConditionalGeneration") for x in architectures)
         is_vlm = is_vlm or hasattr(model_config, "vision_config")
+        load_text_only = text_only and auto_model is None
+        if load_text_only:
+            if hasattr(model_config, "vision_config"):
+                text_config = _get_text_only_config(model_config, old_model_name)
+                # Skip the vision tower only for families with their own text decoder (Gemma 3);
+                # others would load random weights, so keep the full model (use FastVisionModel).
+                text_class = resolve_model_class(AutoModelForCausalLM, text_config)
+                if text_class is None or not _is_family_text_decoder(
+                    getattr(model_config, "model_type", ""),
+                    getattr(text_config, "model_type", ""),
+                ):
+                    load_text_only = False
+                else:
+                    logger.warning_once(
+                        f"Loading {old_model_name} as text-only; vision/audio towers skipped. "
+                        "Use FastVisionModel for multimodal inputs."
+                    )
+                    # Remap VLM text weights (tf >=5) while model_config is still the parent. #5816
+                    _apply_text_only_key_mapping(kwargs, model_config, text_config)
+                    model_config = text_config
+                    is_vlm = False
+            else:
+                is_vlm = False
         # If num_labels is set, use AutoModelForSequenceClassification
         _num_labels = kwargs.get("num_labels", None)
         if auto_model is None:
@@ -1463,6 +1494,7 @@ class FastModel(FastBaseModel):
             max_lora_rank = max_lora_rank,
             disable_log_stats = disable_log_stats,
             load_in_fp8 = load_in_fp8,
+            text_only = load_text_only,
             *args,
             **kwargs,
         )
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index 98458ad307..06937af7db 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -264,42 +264,73 @@ def get_model_name(
     return new_model_name
 
 
-def _offline_quantize_to_fp8(model_name: str, fp8_mode: str) -> str:
+def _offline_quantize_to_fp8(
+    model_name: str,
+    fp8_mode: str,
+    *,
+    text_only: bool = False,
+) -> str:
     """Quantize the model to fp8 via torchao, save to a temp dir, return its path.
 
     For vllm >= 0.12.0, prefer dynamic quantization in vllm instead (via
     hf_overrides={"quantization_config_file": "torchao_config.json"}).
     """
+    from transformers import (
+        AutoModelForCausalLM,
+        AutoModelForImageTextToText,
+        AutoTokenizer,
+        AutoProcessor,
+        TorchAoConfig,
+        AutoConfig,
+    )
+
+    config = AutoConfig.from_pretrained(model_name)
+    is_vlm = any(
+        x.endswith(("ForConditionalGeneration", "ForVisionText2Text"))
+        for x in (getattr(config, "architectures", None) or [])
+    )
+    is_vlm = is_vlm or hasattr(config, "vision_config")
+    # Decide text-only before the cache name so the fp8 artifact and its path stay in sync. #5816
+    text_config = None
+    if text_only and hasattr(config, "vision_config"):
+        from ._utils import (
+            _get_text_only_config,
+            resolve_model_class,
+            _is_family_text_decoder,
+        )
+
+        candidate = _get_text_only_config(config, model_name)
+        text_class = resolve_model_class(AutoModelForCausalLM, candidate)
+        if text_class is not None and _is_family_text_decoder(
+            getattr(config, "model_type", ""),
+            getattr(candidate, "model_type", ""),
+        ):
+            text_config = candidate
+            is_vlm = False
+
     temp_dir = tempfile.gettempdir()
-    new_model_name = model_name.split("/")[-1] + "-fp8-" + fp8_mode
-    new_model_name = os.path.join(temp_dir, new_model_name)
+    # Cache text-only and full-VLM artifacts separately so neither reuses the other. #5816
+    cache_name = model_name.split("/")[-1] + "-fp8-" + fp8_mode
+    if text_config is not None:
+        cache_name += "-text-only"
+    new_model_name = os.path.join(temp_dir, cache_name)
     print(f"Unsloth: Quantizing '{model_name}' to fp8, using model_name='{new_model_name}' instead")
 
     if not os.path.isdir(new_model_name):
-        from transformers import (
-            AutoModelForCausalLM,
-            AutoModelForImageTextToText,
-            AutoTokenizer,
-            AutoProcessor,
-            TorchAoConfig,
-            AutoConfig,
-        )
+        from ._utils import _apply_text_only_key_mapping
 
         qconfig = _get_torchao_fp8_config(fp8_mode)
         qconfig = TorchAoConfig(qconfig)
-        config = AutoConfig.from_pretrained(model_name)
-        is_vlm = any(
-            x.endswith(("ForConditionalGeneration", "ForVisionText2Text"))
-            for x in config.architectures
-        )
-        is_vlm = is_vlm or hasattr(config, "vision_config")
+        load_kwargs = dict(torch_dtype = "auto", device_map = "auto", quantization_config = qconfig)
+        if text_config is not None:
+            _apply_text_only_key_mapping(load_kwargs, config, text_config)
+            config = text_config
         auto_model = AutoModelForImageTextToText if is_vlm else AutoModelForCausalLM
         auto_processor = AutoProcessor if is_vlm else AutoTokenizer
         model = auto_model.from_pretrained(
             model_name,
-            torch_dtype = "auto",
-            device_map = "auto",
-            quantization_config = qconfig,
+            config = config,
+            **load_kwargs,
         )
         tokenizer = auto_processor.from_pretrained(model_name)
         model.save_pretrained(new_model_name, safe_serialization = False)
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 500c6509a4..daa4a4835c 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -34,6 +34,9 @@ from ._utils import (
     _prepare_model_for_qat,
     resolve_model_class,
     resolve_attention_implementation,
+    _get_text_only_config,
+    _is_family_text_decoder,
+    _apply_text_only_key_mapping,
 )
 from ._utils import *
 from .loader_utils import _get_fp8_mode_and_check_settings
@@ -583,6 +586,7 @@ class FastBaseModel:
         disable_log_stats = False,
         unsloth_vllm_standby = False,
         load_in_fp8 = False,  # fp8 LoRA (True, False, 'block')
+        text_only = False,
         **kwargs,
     ):
         if unsloth_vllm_standby and os.environ.get("UNSLOTH_VLLM_STANDBY", "0") != "1":
@@ -597,6 +601,31 @@ class FastBaseModel:
         if os.environ.get("UNSLOTH_MODEL_NAME", "") == "":
             os.environ["UNSLOTH_MODEL_NAME"] = model_name.lower()
 
+        # Resolve text-only before the is_vlm / vLLM checks so is_vlm stays consistent;
+        # skip the vision tower only for families with their own text decoder (Gemma 3). #5816
+        if text_only and auto_config is None:
+            auto_config = AutoConfig.from_pretrained(
+                model_name,
+                token = token,
+                trust_remote_code = trust_remote_code,
+            )
+        if text_only and hasattr(auto_config, "vision_config"):
+            parent_config = auto_config
+            text_config = _get_text_only_config(parent_config, model_name)
+            text_class = resolve_model_class(AutoModelForCausalLM, text_config)
+            if text_class is not None and _is_family_text_decoder(
+                getattr(parent_config, "model_type", ""),
+                getattr(text_config, "model_type", ""),
+            ):
+                auto_config = text_config
+                auto_model = AutoModelForCausalLM
+                _apply_text_only_key_mapping(kwargs, parent_config, text_config)
+        elif text_only and auto_model in [
+            AutoModelForVision2Seq,
+            AutoModelForImageTextToText,
+        ]:
+            # Pure text model requested text-only with a VLM auto class.
+            auto_model = AutoModelForCausalLM
         is_vlm = auto_model in [AutoModelForVision2Seq, AutoModelForImageTextToText]
         is_whisper = whisper_language is not None and whisper_task is not None
         auto_processor = AutoProcessor if (is_vlm or is_whisper) else AutoTokenizer

From fcfbf166ff0e4c657c381e5f2226db6e4dd42f8d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Tue, 9 Jun 2026 23:44:24 -0700
Subject: [PATCH 128/222] studio(ui): use the --primary brand token for the
 avatar fallback color (#5987)

* studio(ui): use the --primary brand token for the avatar fallback color

The fallback profile avatar hardcoded #14b789, a slightly different green
from the app's general brand color (--primary = #17b88b, used by the send
button and every other primary-colored control). Next to primary-colored UI
-- e.g. the artifact preview/code panel -- the avatar's off-brand shade looked
inconsistent ("changes color weirdly"). Point avatarBgStyle() at
var(--primary) so the avatar always renders the general brand green and
follows the theme token.

Verified live in Studio: the avatar was rgb(20,183,137) (#14b789) while
--primary resolves to rgb(23,184,139) (#17b88b); the fix unifies them. This
is the only hardcoded brand-green left in the frontend -- every other
brand-green element already uses --primary / bg-primary.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* studio(ui): add literal fallback to the avatar --primary token

UserAvatar is a reusable component; if it is ever rendered outside the theme
root (where --primary is undefined), var(--primary) alone would compute to
transparent. Use var(--primary, #17b88b) so the avatar stays branded in that
edge case. When --primary is defined (the normal case, app-wide) it always
wins, so this changes nothing in practice -- verified in a browser:
var(--primary)=rgb(23,184,139), and an undefined var correctly falls back to
the literal.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../features/profile/utils/avatar-initials.ts    | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/features/profile/utils/avatar-initials.ts b/studio/frontend/src/features/profile/utils/avatar-initials.ts
index 254a50719b..2683b52a37 100644
--- a/studio/frontend/src/features/profile/utils/avatar-initials.ts
+++ b/studio/frontend/src/features/profile/utils/avatar-initials.ts
@@ -7,7 +7,19 @@ export function initialsFromName(name: string): string {
   return trimmed[0]!.toUpperCase();
 }
 
-/** Default Unsloth-green background for avatar fallback (readable white text). */
+/**
+ * Default Unsloth-brand background for the avatar fallback (readable white text).
+ *
+ * Uses the shared `--primary` design token instead of a one-off hardcoded
+ * shade, so the avatar always matches the app's general brand green (send
+ * button, primary buttons, etc.). It previously hardcoded a slightly different
+ * `#14b789`, which looked inconsistent next to primary-colored UI such as the
+ * artifact preview/code panel.
+ *
+ * The literal fallback (the current `--primary` value) only applies if this
+ * reusable avatar is ever rendered outside the theme root, where `--primary`
+ * is undefined -- it keeps the avatar branded instead of transparent.
+ */
 export function avatarBgStyle(): { backgroundColor: string } {
-  return { backgroundColor: "#14b789" };
+  return { backgroundColor: "var(--primary, #17b88b)" };
 }

From 256d17e2e12188b7a31f8e004a1320bca6c878d0 Mon Sep 17 00:00:00 2001
From: Darshan Poudel <poudeldarshan44@gmail.com>
Date: Wed, 10 Jun 2026 13:17:31 +0545
Subject: [PATCH 129/222] fix(studio): block arbitrary external image URLs in
 markdown renderer (#5602)

* fix(studio): block arbitrary external image URLs in markdown renderer

Model-emitted <img src="http://attacker.com/..."> tags were causing the
browser to issue HTTP requests to arbitrary origins, leaking the user's
IP address, User-Agent, and Referer header to any domain a prompt-injected
model could emit (tracking-pixel vector, issue #5596).

Add a urlTransform function passed to <Streamdown> that only allows:
  - data: URIs  (inline images, mermaid SVG, user attachments)
  - blob: URIs  (locally generated object URLs)
  - relative paths without a scheme (same-origin assets)

All other schemes (http:, https:, ftp:, etc.) return null, causing
Streamdown to omit the <img> element entirely.

Existing iframes are already stripped by Streamdown's default sanitizer;
event-handler attributes (onerror, onload, etc.) are also stripped by
the default schema.

* fix(studio): strip control chars and block backslash URL variants

Two bypass vectors found after review:

1. Backslash-normalised URLs: \\attacker.com\pixel has no colon and does
   not start with // so the earlier guards allowed it as a relative path.
   Browsers normalise leading backslash pairs to // before resolving, so
   the request still reaches the external origin.

2. Embedded control characters: /\n/attacker.com passes trim() unchanged,
   startsWith("//") is false, and no-colon check passes it as relative.
   Browsers strip ASCII controls (U+0000-U+001F, U+007F) before URL
   resolution, so the value resolves to the attacker origin.

Fix: strip all ASCII control characters from the raw URL before any guard,
then block any URL whose normalized form starts with two chars from [/\\]
to cover //, \\, /\, and \/ in one regex.

* fix(studio): delegate non-image URLs to defaultUrlTransform

Returning the raw URL for non-img nodes bypassed Streamdown's built-in
link sanitization, allowing model-emitted javascript: hrefs to reach the
DOM unfiltered. Pass non-image URLs through defaultUrlTransform so the
library's own javascript:/data: sanitization stays active for links.

* fix(studio): use scheme regex instead of includes() for colon check

A colon anywhere in the URL (e.g. /api/image?id=model:v2 or
/snapshots/2026-06-04T12:00:00Z.png) was incorrectly treated as an
explicit scheme and the URL was dropped. Replace the includes(':') check
with a proper scheme regex that only matches when a valid scheme token
appears before any path separator.

* Studio: shorten safeImageUrl comments in markdown renderer

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../components/assistant-ui/markdown-text.tsx | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/studio/frontend/src/components/assistant-ui/markdown-text.tsx b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
index fc547da0b1..ef9b33fced 100644
--- a/studio/frontend/src/components/assistant-ui/markdown-text.tsx
+++ b/studio/frontend/src/components/assistant-ui/markdown-text.tsx
@@ -13,7 +13,7 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { createMathPlugin } from "@streamdown/math";
 import { mermaid } from "@streamdown/mermaid";
 import { useEffect, useMemo, useRef, useState } from "react";
-import { Block, type BlockProps, Streamdown } from "streamdown";
+import { Block, type BlockProps, Streamdown, defaultUrlTransform, type UrlTransform } from "streamdown";
 import { createCodePlugin } from "./code-plugin";
 import "katex/dist/katex.min.css";
 import { AudioPlayer } from "./audio-player";
@@ -424,6 +424,22 @@ function useRafCoalescedText(text: string, isStreaming: boolean): string {
   return text;
 }
 
+const safeImageUrl: UrlTransform = (url, _key, node) => {
+  // Only images are restricted; links/other nodes use the default transform.
+  if (node.tagName !== "img") return defaultUrlTransform(url, _key, node);
+
+  // Strip ASCII controls first: browsers drop them mid-parse, so a value like
+  // "\t//attacker.com" would otherwise slip past the guards below.
+  // eslint-disable-next-line no-control-regex
+  const normalized = url.replace(/[\x00-\x1f\x7f]/g, "").trim();
+  const lower = normalized.toLowerCase();
+
+  if (lower.startsWith("data:") || lower.startsWith("blob:")) return normalized;
+  if (/^[/\\]{2}/.test(normalized)) return null; // protocol-relative: // \\ /\ \/
+  if (/^[a-zA-Z][a-zA-Z0-9+\-.]*:/.test(normalized)) return null; // scheme prefix (colon later in path is fine)
+  return normalized; // relative -> same-origin
+};
+
 const MarkdownTextImpl = () => {
   const { text, status } = useMessagePartText();
   const displayText = useRafCoalescedText(text, status.type === "running");
@@ -444,6 +460,7 @@ const MarkdownTextImpl = () => {
         isAnimating={status.type === "running"}
         plugins={{ code, math, mermaid }}
         components={STREAMDOWN_COMPONENTS}
+        urlTransform={safeImageUrl}
         controls={{
           code: false,
           mermaid: {

From 4d2f29ff2af0e67341246fff898c1414c57e9ef0 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 01:57:16 -0700
Subject: [PATCH 130/222] Studio: center account avatar vertically in sidebar
 footer pill (#6026)

Co-authored-by: shimmyshimmer <shimmyshimmer@users.noreply.github.com>
---
 studio/frontend/src/components/app-sidebar.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 9cb28a198b..2a633aeaf9 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -1156,7 +1156,7 @@ export function AppSidebar() {
                   aria-label={t("shell.accountMenu", { name: displayTitle })}
                   className="sidebar-nav-btn !h-[44px] gap-[9px] px-2 py-[3px] rounded-[14px]"
                 >
-                  <div className="shrink-0">
+                  <div className="flex shrink-0 items-center">
                     <UserAvatar
                       name={displayTitle}
                       imageUrl={avatarDataUrl}

From 5f622f6c2ff2d0967e6439f491b2c06c32846282 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Wed, 10 Jun 2026 02:17:21 -0700
Subject: [PATCH 131/222] fix: clearer Studio setup error when GPU driver is
 too old for the installed CUDA toolkit (#5993)

* fix: clearer Studio setup error when GPU driver is too old for the installed CUDA toolkit

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Honor optional color arg in setup.sh substep so driver/toolkit warnings render in C_WARN

* Add regression test that setup.sh _cuda_version_gt compares numerically for PR #5993

* Update Resolve-CudaToolkit test for the new driver-too-old messaging

setup.ps1 now routes the too-new-toolkit case through
Write-CudaDriverToolkitMismatch instead of the old 'is installed but
INCOMPATIBLE' banner. Extract that helper alongside Resolve-CudaToolkit so the
child pwsh can run it, and assert the new driver-too-old guidance (and the
one-line source-build error) instead of the removed INCOMPATIBLE text.

* Address review nits: document Windows hard-exit asymmetry and add toolkit/driver edge tests

setup.ps1: note that only a forced source build reaches the hard-exit branch
(the prebuilt path returned above), unlike setup.sh which degrades to CPU.
test_selection_logic.py: cover the CUDA UMD Version variant, the empty nvcc
version guard, and the too_old (< 12.4) short-circuit.

* fix(studio): allow CUDA minor-version compat and try installed toolkits before CPU fallback

The driver check now compares CUDA major versions only, per NVIDIA
minor-version compatibility, and when the selected nvcc is still too
new the setup iterates other installed toolkits and uses the newest
driver-compatible one before falling back to a CPU llama.cpp build.
Same rule mirrored in setup.ps1.

* style: apply ruff kwarg-spacing format after rebase

* Accept a same-major CUDA toolkit found only on PATH in the Windows fallback

The major-only compatibility fix updated the side-by-side scan (Find-Nvcc
-MaxVersion) and the CUDA_PATH check, but the fallback that runs when
Find-Nvcc -MaxVersion returns null still recorded any plain Find-Nvcc result
as an incompatible toolkit without re-checking the major. A same-major
toolkit discoverable only via PATH, process CUDA_PATH, or a custom location
(e.g. toolkit 13.3 with a driver supporting CUDA 13.2) was therefore rejected
even though it is compatible.

Re-apply the same major-only rule in the fallback: use the toolkit when its
major is within the driver's, otherwise record it as too-new. Adds a
regression test covering the PATH-only same-major case.

* Add CUDA driver/toolkit selection edge-case tests for Studio setup

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Tighten comments in Studio CUDA driver/toolkit setup

Collapse multi-line comments, drop obvious ones, keep the load-bearing intent
(the major-compat invariant, the Windows hard-exit vs setup.sh-CPU asymmetry,
the PATH-only fallback rationale). Comment-only; no code change.

* Clarify the Windows source-build hard-exit comment

The path is reached by any committed source build (forced, or after a
prebuilt-install failure), not only a forced one. Comment-only.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Drop two obvious comments in setup.ps1 CUDA detection

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/setup.ps1                             |  77 ++--
 studio/setup.sh                              | 182 ++++++--
 tests/studio/install/test_selection_logic.py | 443 +++++++++++++++++++
 tests/studio/test_resolve_cuda_toolkit.ps1   |  69 ++-
 4 files changed, 685 insertions(+), 86 deletions(-)

diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 4d47010136..920d1af13a 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -220,14 +220,10 @@ function Get-InstalledLlamaPrebuiltRelease {
 function Find-Nvcc {
     param([string]$MaxVersion = "")
 
-    # If MaxVersion is set, we need to find a toolkit <= that version.
-    # CUDA toolkits install side-by-side under C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y\
-
     $toolkitBase = 'C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA'
 
     if ($MaxVersion -and (Test-Path $toolkitBase)) {
         $drMajor = [int]$MaxVersion.Split('.')[0]
-        $drMinor = [int]$MaxVersion.Split('.')[1]
 
         # Get all installed CUDA dirs, sorted descending (highest first)
         $cudaDirs = Get-ChildItem -Directory $toolkitBase | Where-Object {
@@ -236,8 +232,8 @@ function Find-Nvcc {
 
         foreach ($dir in $cudaDirs) {
             if ($dir.Name -match '^v(\d+)\.(\d+)') {
-                $tkMajor = [int]$Matches[1]; $tkMinor = [int]$Matches[2]
-                $compatible = ($tkMajor -lt $drMajor) -or ($tkMajor -eq $drMajor -and $tkMinor -le $drMinor)
+                $tkMajor = [int]$Matches[1]
+                $compatible = ($tkMajor -le $drMajor)
                 if ($compatible) {
                     $nvcc = Join-Path $dir.FullName 'bin\nvcc.exe'
                     if (Test-Path $nvcc) {
@@ -278,6 +274,19 @@ function Find-Nvcc {
     return $null
 }
 
+function Write-CudaDriverToolkitMismatch {
+    param(
+        [Parameter(Mandatory = $true)][string]$ToolkitVersion,
+        [Parameter(Mandatory = $true)][string]$DriverMaxCuda,
+        [string]$Color = "Yellow"
+    )
+    $toolkitMajor = $ToolkitVersion.Split('.')[0]
+    $driverMajor = $DriverMaxCuda.Split('.')[0]
+    substep "CUDA Toolkit $ToolkitVersion is a major-version mismatch: toolkit major $toolkitMajor exceeds driver CUDA major $driverMajor ($DriverMaxCuda)." $Color
+    substep "Update the NVIDIA GPU driver to run CUDA Toolkit $ToolkitVersion, or install a CUDA $driverMajor.x toolkit." $Color
+    substep "Or let Studio use the prebuilt CUDA bundle; it does not need the local toolkit." $Color
+}
+
 # Detect CUDA Compute Capability via nvidia-smi.
 # Returns e.g. "80" for A100 (8.0), "89" for RTX 4090 (8.9), etc.
 # Returns $null if detection fails.
@@ -1062,17 +1071,13 @@ if ($vsResult) {
 # or installed. Without it, detection is best-effort and only sets the flag.
 function Resolve-CudaToolkit {
     param([switch]$RequireOrExit)
-# IMPORTANT: The CUDA Toolkit version must be <= the max CUDA version the
-# NVIDIA driver supports.  nvidia-smi reports this as "CUDA Version: X.Y".
-# If we install a toolkit newer than the driver supports, llama-server will
-# fail at runtime with "ggml_cuda_init: failed to initialize CUDA: (null)".
+# Toolkit major must be <= the driver's max CUDA major (nvidia-smi "CUDA Version: X.Y");
+# a newer-major toolkit fails at runtime ("ggml_cuda_init: failed to initialize CUDA").
 
-# -- Detect max CUDA version the driver supports --
 $DriverMaxCuda = $null
 try {
     $smiOut = & $NvidiaSmiExe 2>&1 | Out-String
-    # Newer NVIDIA drivers (e.g. 610.x) report the driver max CUDA as
-    # "CUDA UMD Version: X.Y" rather than "CUDA Version: X.Y"; accept both.
+    # Newer drivers report "CUDA UMD Version: X.Y" instead of "CUDA Version: X.Y"; accept both.
     if ($smiOut -match "CUDA(?: UMD)? Version:\s+([\d]+)\.([\d]+)") {
         $DriverMaxCuda = "$($Matches[1]).$($Matches[2])"
         substep "driver supports up to CUDA $DriverMaxCuda"
@@ -1096,7 +1101,6 @@ $NvccPath = $null
 
 if ($DriverMaxCuda) {
     $drMajorCuda = [int]$DriverMaxCuda.Split('.')[0]
-    $drMinorCuda = [int]$DriverMaxCuda.Split('.')[1]
 
     # --- Step 1: Check existing CUDA_PATH first ---
     $existingCudaPath = [Environment]::GetEnvironmentVariable('CUDA_PATH', 'Machine')
@@ -1108,7 +1112,7 @@ if ($DriverMaxCuda) {
         $verOut = & $candidateNvcc --version 2>&1 | Out-String
         if ($verOut -match 'release\s+(\d+)\.(\d+)') {
             $tkMaj = [int]$Matches[1]; $tkMin = [int]$Matches[2]
-            $isCompat = ($tkMaj -lt $drMajorCuda) -or ($tkMaj -eq $drMajorCuda -and $tkMin -le $drMinorCuda)
+            $isCompat = ($tkMaj -le $drMajorCuda)
             if ($isCompat) {
                 # Also verify the toolkit supports our GPU architecture
                 $archOk = $true
@@ -1124,7 +1128,7 @@ if ($DriverMaxCuda) {
                     substep "using existing CUDA Toolkit at CUDA_PATH (nvcc: $NvccPath)"
                 }
             } else {
-                substep "CUDA_PATH ($existingCudaPath) has CUDA $tkMaj.$tkMin which exceeds driver max $DriverMaxCuda" "Yellow"
+                substep "CUDA_PATH ($existingCudaPath) has CUDA $tkMaj.$tkMin with major $tkMaj, which exceeds driver CUDA major $drMajorCuda ($DriverMaxCuda)" "Yellow"
             }
         }
     }
@@ -1141,12 +1145,19 @@ if ($DriverMaxCuda) {
                 }
             }
         } else {
-            # Check if there's an incompatible (too new) toolkit installed
+            # No side-by-side match: a major-compatible toolkit may still be on
+            # PATH/CUDA_PATH/a custom dir; use it, else record it as too-new.
             $AnyNvcc = Find-Nvcc
             if ($AnyNvcc) {
                 $NvccOut = & $AnyNvcc --version 2>&1 | Out-String
-                if ($NvccOut -match "release\s+([\d]+\.[\d]+)") {
-                    $IncompatibleToolkit = $Matches[1]
+                if ($NvccOut -match "release\s+(\d+)\.(\d+)") {
+                    $tkMaj = [int]$Matches[1]; $tkMin = [int]$Matches[2]
+                    if ($tkMaj -le $drMajorCuda) {
+                        $NvccPath = $AnyNvcc
+                        substep "found compatible CUDA Toolkit (nvcc: $NvccPath)"
+                    } else {
+                        $IncompatibleToolkit = "$tkMaj.$tkMin"
+                    }
                 }
             }
         }
@@ -1155,26 +1166,18 @@ if ($DriverMaxCuda) {
     $NvccPath = Find-Nvcc
 }
 
-# -- If incompatible toolkit is blocking, tell user to uninstall it --
+# A newer-major toolkit blocked by the driver: explain the mismatch.
 if (-not $NvccPath -and $IncompatibleToolkit) {
+    Write-CudaDriverToolkitMismatch -ToolkitVersion $IncompatibleToolkit -DriverMaxCuda $DriverMaxCuda
     if (-not $RequireOrExit) {
-        substep "CUDA Toolkit $IncompatibleToolkit exceeds driver max $DriverMaxCuda -- skipping; prebuilt llama.cpp needs no local toolkit" "Yellow"
         $script:CudaToolkitReady = $false
         return
     }
+    # Reached only by a source build (forced, or after a prebuilt-install failure);
+    # with no compatible toolkit it must fail (setup.sh degrades to CPU instead).
     Write-Host "" -ForegroundColor Red
     Write-Host "========================================================================" -ForegroundColor Red
-    Write-Host "[ERROR] CUDA Toolkit $IncompatibleToolkit is installed but INCOMPATIBLE" -ForegroundColor Red
-    Write-Host "        with your NVIDIA driver (which supports up to CUDA $DriverMaxCuda)." -ForegroundColor Red
-    Write-Host "" -ForegroundColor Red
-    Write-Host "  This will cause 'failed to initialize CUDA' errors at runtime." -ForegroundColor Red
-    Write-Host "" -ForegroundColor Red
-    Write-Host "  To fix:" -ForegroundColor Yellow
-    Write-Host "    1. Open Control Panel -> Programs -> Uninstall a program" -ForegroundColor Yellow
-    Write-Host "    2. Uninstall 'NVIDIA CUDA Toolkit $IncompatibleToolkit'" -ForegroundColor Yellow
-    Write-Host "    3. Re-run setup.bat (it will install CUDA $DriverMaxCuda automatically)" -ForegroundColor Yellow
-    Write-Host "" -ForegroundColor Yellow
-    Write-Host "  Alternatively, update your NVIDIA driver to one that supports CUDA $IncompatibleToolkit." -ForegroundColor Gray
+    Write-Host "[ERROR] CUDA source build cannot use the installed toolkit with this driver." -ForegroundColor Red
     Write-Host "========================================================================" -ForegroundColor Red
     exit 1
 }
@@ -1187,7 +1190,6 @@ if (-not $NvccPath -and $RequireOrExit) {
         if ($DriverMaxCuda) {
             # Query winget for available CUDA Toolkit versions
             $drMajor = [int]$DriverMaxCuda.Split('.')[0]
-            $drMinor = [int]$DriverMaxCuda.Split('.')[1]
             $AvailableVersions = @()
             try {
                 $rawOutput = winget show Nvidia.CUDA --versions --accept-source-agreements 2>&1 | Out-String
@@ -1200,13 +1202,12 @@ if (-not $NvccPath -and $RequireOrExit) {
                 }
             } catch {}
 
-            # Filter to compatible versions (<= driver max) and pick the highest
+            # Filter to compatible major versions and pick the highest
             $BestVersion = $null
             foreach ($ver in $AvailableVersions) {
                 $parts = $ver.Split('.')
                 $vMajor = [int]$parts[0]
-                $vMinor = [int]$parts[1]
-                if ($vMajor -lt $drMajor -or ($vMajor -eq $drMajor -and $vMinor -le $drMinor)) {
+                if ($vMajor -le $drMajor) {
                     $BestVersion = $ver
                     break  # list is descending, first match is highest compatible
                 }
@@ -1224,7 +1225,7 @@ if (-not $NvccPath -and $RequireOrExit) {
                     substep "CUDA Toolkit $BestVersion installed (nvcc: $NvccPath)"
                 }
             } else {
-                substep "no compatible CUDA Toolkit version found in winget (need <= $DriverMaxCuda)" "Yellow"
+                substep "no compatible CUDA Toolkit version found in winget (need CUDA major <= $drMajor)" "Yellow"
             }
         } else {
             substep "Installing CUDA Toolkit (latest) via winget..."
@@ -1246,7 +1247,7 @@ if (-not $NvccPath) {
     }
     Write-Host "[ERROR] CUDA Toolkit (nvcc) is required but could not be found or installed." -ForegroundColor Red
     if ($DriverMaxCuda) {
-        Write-Host "        Install CUDA Toolkit $DriverMaxCuda from https://developer.nvidia.com/cuda-toolkit-archive" -ForegroundColor Yellow
+        Write-Host "        Install a CUDA Toolkit with major version $($DriverMaxCuda.Split('.')[0]) from https://developer.nvidia.com/cuda-toolkit-archive" -ForegroundColor Yellow
     } else {
         Write-Host "        Install CUDA Toolkit from https://developer.nvidia.com/cuda-downloads" -ForegroundColor Yellow
     }
diff --git a/studio/setup.sh b/studio/setup.sh
index 9b29def859..0db9a612c8 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -59,8 +59,9 @@ fi
 # ── Output helpers ──
 # Consistent column layout: 2-space indent, 15-char label (fits llama-quantize), then value.
 # Usage: step <label> <message> [color]   (color defaults to C_OK)
+# Usage: substep <message> [color]         (color defaults to C_DIM)
 step()    { printf "  ${C_DIM}%-15.15s${C_RST}${3:-$C_OK}%s${C_RST}\n" "$1" "$2"; }
-substep() { printf "  ${C_DIM}%-15s%s${C_RST}\n" "" "$1"; }
+substep() { printf "  %-15s${2:-$C_DIM}%s${C_RST}\n" "" "$1"; }
 
 _is_verbose() {
     [ "${UNSLOTH_VERBOSE:-0}" = "1" ]
@@ -154,6 +155,107 @@ _nvcc_meets_llama_minimum() {
     echo "$_raw"
 }
 
+_cuda_driver_max_version() {
+    command -v nvidia-smi >/dev/null 2>&1 || return 0
+    nvidia-smi 2>/dev/null \
+        | sed -nE 's/.*CUDA( UMD)? Version:[[:space:]]*([0-9]+)\.([0-9]+).*/\2.\3/p' \
+        | head -1 || true
+}
+
+_cuda_version_gt() {
+    local _left=${1:-}
+    local _right=${2:-}
+    if ! [[ "$_left" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+        return 1
+    fi
+    local _left_major=$((10#${BASH_REMATCH[1]}))
+    local _left_minor=$((10#${BASH_REMATCH[2]}))
+    if ! [[ "$_right" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+        return 1
+    fi
+    local _right_major=$((10#${BASH_REMATCH[1]}))
+    local _right_minor=$((10#${BASH_REMATCH[2]}))
+
+    if [ "$_left_major" -gt "$_right_major" ]; then
+        return 0
+    fi
+    if [ "$_left_major" -eq "$_right_major" ] && [ "$_left_minor" -gt "$_right_minor" ]; then
+        return 0
+    fi
+    return 1
+}
+
+_cuda_toolkit_major_gt_driver() {
+    local _toolkit_version=${1:-}
+    local _driver_version=${2:-}
+    if ! [[ "$_toolkit_version" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+        return 1
+    fi
+    local _toolkit_major=$((10#${BASH_REMATCH[1]}))
+    if ! [[ "$_driver_version" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+        return 1
+    fi
+    local _driver_major=$((10#${BASH_REMATCH[1]}))
+    [ "$_toolkit_major" -gt "$_driver_major" ]
+}
+
+_cuda_nvcc_candidate_paths() {
+    if command -v nvcc >/dev/null 2>&1; then
+        command -v nvcc
+    fi
+    if [ -x /usr/local/cuda/bin/nvcc ]; then
+        printf '%s\n' "/usr/local/cuda/bin/nvcc"
+    fi
+    ls -d /usr/local/cuda-*/bin/nvcc 2>/dev/null | sort -V -r 2>/dev/null || true
+}
+
+_cuda_find_compatible_nvcc_for_driver() {
+    local _driver_version=$1
+    local _exclude_path=${2:-}
+    local _candidate _seen _check _status _version
+    local _best_path="" _best_version=""
+    _seen="
+"
+    while IFS= read -r _candidate; do
+        [ -n "$_candidate" ] || continue
+        [ "$_candidate" != "$_exclude_path" ] || continue
+        [ -x "$_candidate" ] || continue
+        case "$_seen" in
+            *"
+$_candidate
+"*) continue ;;
+        esac
+        _seen="${_seen}${_candidate}
+"
+        _check="$(_nvcc_meets_llama_minimum "$_candidate")"
+        _status="$(printf '%s\n' "$_check" | sed -n '1p')"
+        _version="$(printf '%s\n' "$_check" | sed -n '2p')"
+        [ "$_status" = "ok" ] || continue
+        [ -n "$_version" ] || continue
+        if _cuda_toolkit_major_gt_driver "$_version" "$_driver_version"; then
+            continue
+        fi
+        if [ -z "$_best_version" ] || _cuda_version_gt "$_version" "$_best_version"; then
+            _best_path="$_candidate"
+            _best_version="$_version"
+        fi
+    done <<EOF
+$(_cuda_nvcc_candidate_paths)
+EOF
+    [ -n "$_best_path" ] || return 1
+    printf '%s\n%s\n' "$_best_path" "$_best_version"
+}
+
+_print_cuda_driver_toolkit_mismatch() {
+    local _toolkit_version=$1
+    local _driver_version=$2
+    local _toolkit_major=${_toolkit_version%%.*}
+    local _driver_major=${_driver_version%%.*}
+    substep "CUDA Toolkit $_toolkit_version is a major-version mismatch: toolkit major $_toolkit_major exceeds driver CUDA major $_driver_major ($_driver_version)." "$C_WARN"
+    substep "Update the NVIDIA GPU driver to run CUDA Toolkit $_toolkit_version, or install a CUDA $_driver_major.x toolkit." "$C_WARN"
+    substep "Or let Studio use the prebuilt CUDA bundle; it does not need the local toolkit." "$C_WARN"
+}
+
 print_llama_error_log() {
     local log_file=$1
     [ -s "$log_file" ] || return 0
@@ -1162,38 +1264,58 @@ else
                     GPU_BACKEND=""
                     _BUILD_DESC="building (CPU, CUDA toolkit < 12.4)"
                 else
-                    CMAKE_ARGS="$CMAKE_ARGS -DGGML_CUDA=ON"
-
-                    CUDA_ARCHS=""
-                    if command -v nvidia-smi &>/dev/null; then
-                        _raw_caps=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
-                        while IFS= read -r _cap; do
-                            _cap=$(echo "$_cap" | tr -d '[:space:]')
-                            if [[ "$_cap" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-                                _arch="${BASH_REMATCH[1]}${BASH_REMATCH[2]}"
-                                # Append if not already present
-                                case ";$CUDA_ARCHS;" in
-                                    *";$_arch;"*) ;;
-                                    *) CUDA_ARCHS="${CUDA_ARCHS:+$CUDA_ARCHS;}$_arch" ;;
-                                esac
-                            fi
-                        done <<< "$_raw_caps"
+                    _DRIVER_MAX_CUDA="$(_cuda_driver_max_version)"
+                    _CUDA_TOOLKIT_ALLOWED=true
+                    if [ -n "$_NVCC_VER" ] && [ -n "$_DRIVER_MAX_CUDA" ] && \
+                       _cuda_toolkit_major_gt_driver "$_NVCC_VER" "$_DRIVER_MAX_CUDA"; then
+                        _BLOCKED_NVCC_VER="$_NVCC_VER"
+                        if _ALT_NVCC_CHECK="$(_cuda_find_compatible_nvcc_for_driver "$_DRIVER_MAX_CUDA" "$NVCC_PATH")"; then
+                            NVCC_PATH="$(printf '%s\n' "$_ALT_NVCC_CHECK" | sed -n '1p')"
+                            _NVCC_VER="$(printf '%s\n' "$_ALT_NVCC_CHECK" | sed -n '2p')"
+                            GPU_BACKEND="cuda"
+                            export PATH="$(dirname "$NVCC_PATH"):$PATH"
+                            substep "CUDA Toolkit $_BLOCKED_NVCC_VER is a major-version mismatch with driver CUDA $_DRIVER_MAX_CUDA; using compatible CUDA Toolkit $_NVCC_VER at $NVCC_PATH." "$C_WARN"
+                        else
+                            _print_cuda_driver_toolkit_mismatch "$_NVCC_VER" "$_DRIVER_MAX_CUDA"
+                            substep "falling back to CPU llama.cpp build for this run." "$C_WARN"
+                            NVCC_PATH=""
+                            GPU_BACKEND=""
+                            _BUILD_DESC="building (CPU, CUDA toolkit major > driver)"
+                            _CUDA_TOOLKIT_ALLOWED=false
+                        fi
                     fi
 
-                    if [ -n "$CUDA_ARCHS" ]; then
-                        CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_ARCHITECTURES=${CUDA_ARCHS}"
-                        _BUILD_DESC="building (CUDA, sm_${CUDA_ARCHS//;/+sm_})"
-                    else
-                        _BUILD_DESC="building (CUDA)"
+                    if [ "$_CUDA_TOOLKIT_ALLOWED" = true ]; then
+                        CMAKE_ARGS="$CMAKE_ARGS -DGGML_CUDA=ON"
+
+                        CUDA_ARCHS=""
+                        if command -v nvidia-smi &>/dev/null; then
+                            _raw_caps=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
+                            while IFS= read -r _cap; do
+                                _cap=$(echo "$_cap" | tr -d '[:space:]')
+                                if [[ "$_cap" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+                                    _arch="${BASH_REMATCH[1]}${BASH_REMATCH[2]}"
+                                    case ";$CUDA_ARCHS;" in
+                                        *";$_arch;"*) ;;
+                                        *) CUDA_ARCHS="${CUDA_ARCHS:+$CUDA_ARCHS;}$_arch" ;;
+                                    esac
+                                fi
+                            done <<< "$_raw_caps"
+                        fi
+
+                        if [ -n "$CUDA_ARCHS" ]; then
+                            CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_ARCHITECTURES=${CUDA_ARCHS}"
+                            _BUILD_DESC="building (CUDA, sm_${CUDA_ARCHS//;/+sm_})"
+                        else
+                            _BUILD_DESC="building (CUDA)"
+                        fi
+
+                        CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_FLAGS=--threads=0"
+
+                        # Allow a host gcc/clang newer than nvcc's whitelist (else a fresh
+                        # toolkit aborts with "unsupported GNU version"); via env to avoid word-splitting.
+                        export NVCC_PREPEND_FLAGS="${NVCC_PREPEND_FLAGS:+$NVCC_PREPEND_FLAGS }-allow-unsupported-compiler"
                     fi
-
-                    CMAKE_ARGS="$CMAKE_ARGS -DCMAKE_CUDA_FLAGS=--threads=0"
-
-                    # Accept a host gcc/clang newer than nvcc's whitelist; a fresh
-                    # toolkit (e.g. CUDA 13.3) otherwise aborts with "#error --
-                    # unsupported GNU version". Via env, not CMAKE_ARGS, to avoid
-                    # word-splitting.
-                    export NVCC_PREPEND_FLAGS="${NVCC_PREPEND_FLAGS:+$NVCC_PREPEND_FLAGS }-allow-unsupported-compiler"
                 fi
             elif [ "$GPU_BACKEND" = "rocm" ]; then
                 # Resolve hipcc symlinks to find the real ROCm root
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 27cf30496f..b5a070ae41 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -11,8 +11,11 @@ No GPU, no network, no torch required -- all I/O is monkeypatched.
 """
 
 import importlib.util
+import os
 import socket
+import subprocess
 import sys
+import textwrap
 import types
 from pathlib import Path
 
@@ -3062,3 +3065,443 @@ class TestCpuFallback:
         # is gated on a degraded source build for arm64.
         assert "ggml-org/llama.cpp" in source
         assert "_LLAMA_CPP_DEGRADED" in source
+
+
+# ===========================================================================
+# setup.sh / setup.ps1: CUDA toolkit newer than driver diagnostics
+# ===========================================================================
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason = "bash-only Studio installer tests")
+class TestCudaDriverToolkitMismatchMessage:
+    _SETUP_SH = PACKAGE_ROOT / "studio" / "setup.sh"
+    _SETUP_PS1 = PACKAGE_ROOT / "studio" / "setup.ps1"
+
+    def _setup_sh_cuda_helper_fragment(self):
+        source = self._SETUP_SH.read_text(encoding = "utf-8")
+        start = source.index("_nvcc_meets_llama_minimum()")
+        end = source.index("print_llama_error_log()")
+        return source[start:end]
+
+    def _run_bash(
+        self,
+        script,
+        *,
+        env = None,
+    ):
+        proc = subprocess.run(
+            ["/bin/bash", "-c", script],
+            check = True,
+            text = True,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.PIPE,
+            env = {**os.environ, **(env or {})},
+        )
+        return proc.stdout + proc.stderr
+
+    def _fake_nvidia_smi(self, tmp_path, output):
+        mock_bin = tmp_path / "bin"
+        mock_bin.mkdir()
+        nvidia_smi = mock_bin / "nvidia-smi"
+        nvidia_smi.write_text(
+            textwrap.dedent(
+                f"""\
+                #!/usr/bin/env bash
+                cat <<'OUT'
+                {output}
+                OUT
+                """
+            ),
+            encoding = "utf-8",
+        )
+        nvidia_smi.chmod(0o755)
+        return mock_bin
+
+    def test_setup_sh_same_major_minor_mismatch_is_accepted(self, tmp_path):
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 580.95   Driver Version: 580.95   CUDA Version: 13.1 |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _driver="$(_cuda_driver_max_version)"
+            if _cuda_toolkit_major_gt_driver "13.3" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "13.3" "$_driver"
+            else
+                printf 'compatible:%s\\n' "$_driver"
+            fi
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert "compatible:13.1" in output
+        assert "major-version mismatch" not in output
+
+    def test_setup_sh_driver_major_too_old_message_names_major_mismatch(self, tmp_path):
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 570.95   Driver Version: 570.95   CUDA Version: 12.9 |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _driver="$(_cuda_driver_max_version)"
+            if _cuda_toolkit_major_gt_driver "13.3" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "13.3" "$_driver"
+            fi
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert (
+            "CUDA Toolkit 13.3 is a major-version mismatch: toolkit major 13 "
+            "exceeds driver CUDA major 12 (12.9)."
+        ) in output
+        assert (
+            "Update the NVIDIA GPU driver to run CUDA Toolkit 13.3, or install "
+            "a CUDA 12.x toolkit."
+        ) in output
+        assert "prebuilt CUDA bundle" in output
+
+    def test_setup_sh_happy_path_does_not_print_mismatch(self, tmp_path):
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 580.95   Driver Version: 580.95   CUDA Version: 13.3 |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _driver="$(_cuda_driver_max_version)"
+            if _cuda_toolkit_major_gt_driver "13.3" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "13.3" "$_driver"
+            else
+                printf 'compatible:%s\\n' "$_driver"
+            fi
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert "compatible:13.3" in output
+        assert "Unsloth supports CUDA Toolkit" not in output
+
+    def test_setup_sh_skips_check_without_nvidia_smi(self, tmp_path):
+        empty_bin = tmp_path / "empty-bin"
+        empty_bin.mkdir()
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _driver="$(_cuda_driver_max_version)"
+            if [ -n "$_driver" ] && _cuda_toolkit_major_gt_driver "13.3" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "13.3" "$_driver"
+            else
+                printf 'skipped\\n'
+            fi
+            """
+        )
+        output = self._run_bash(script, env = {"PATH": str(empty_bin)})
+        assert "skipped" in output
+        assert "Unsloth supports CUDA Toolkit" not in output
+
+    def test_setup_sh_unparsable_nvidia_smi_output_falls_back(self, tmp_path):
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 580.95   Driver Version: 580.95   CUDA Version: N/A |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _driver="$(_cuda_driver_max_version)"
+            if [ -n "$_driver" ] && _cuda_toolkit_major_gt_driver "13.3" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "13.3" "$_driver"
+            else
+                printf 'fallback:%s\\n' "${{_driver:-generic}}"
+            fi
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert "fallback:generic" in output
+        assert "Unsloth supports CUDA Toolkit" not in output
+
+    def test_setup_sh_cuda_version_gt_compares_numerically(self):
+        # 13.9 vs 13.10 is where a lexical compare goes wrong (9 > 1).
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            {self._setup_sh_cuda_helper_fragment()}
+            for pair in "13.9 13.10" "13.10 13.9" "14.0 13.9" "13.3 13.3"; do
+                if _cuda_version_gt $pair; then r=gt; else r=le; fi
+                printf '%s -> %s\\n' "$pair" "$r"
+            done
+            """
+        )
+        output = self._run_bash(script)
+        assert "13.9 13.10 -> le" in output
+        assert "13.10 13.9 -> gt" in output
+        assert "14.0 13.9 -> gt" in output
+        assert "13.3 13.3 -> le" in output
+
+    def test_setup_ps1_mirrors_driver_mismatch_guidance(self):
+        source = self._SETUP_PS1.read_text(encoding = "utf-8")
+        assert "Write-CudaDriverToolkitMismatch" in source
+        assert (
+            "CUDA Toolkit $ToolkitVersion is a major-version mismatch: toolkit "
+            "major $toolkitMajor exceeds driver CUDA major $driverMajor"
+        ) in source
+        assert (
+            "Update the NVIDIA GPU driver to run CUDA Toolkit $ToolkitVersion, "
+            "or install a CUDA $driverMajor.x toolkit." in source
+        )
+        assert (
+            "Or let Studio use the prebuilt CUDA bundle; it does not need the local toolkit."
+        ) in source
+        assert (
+            "Write-CudaDriverToolkitMismatch -ToolkitVersion $IncompatibleToolkit "
+            "-DriverMaxCuda $DriverMaxCuda"
+        ) in source
+
+    def _fake_nvcc(self, tmp_path, release):
+        mock_bin = tmp_path / f"nvcc-bin-{release.replace('.', '-')}"
+        mock_bin.mkdir()
+        nvcc = mock_bin / "nvcc"
+        nvcc.write_text(
+            textwrap.dedent(
+                f"""\
+                #!/usr/bin/env bash
+                printf '%s\\n' 'Cuda compilation tools, release {release}, V{release}.0'
+                """
+            ),
+            encoding = "utf-8",
+        )
+        nvcc.chmod(0o755)
+        return nvcc
+
+    def test_setup_sh_major_mismatch_uses_newest_compatible_detected_toolkit(self, tmp_path):
+        blocked_nvcc = self._fake_nvcc(tmp_path, "13.3")
+        older_nvcc = self._fake_nvcc(tmp_path, "12.6")
+        compatible_nvcc = self._fake_nvcc(tmp_path, "12.8")
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _cuda_nvcc_candidate_paths() {{
+                printf '%s\\n' "{blocked_nvcc}" "{older_nvcc}" "{compatible_nvcc}"
+            }}
+            NVCC_PATH="{blocked_nvcc}"
+            GPU_BACKEND="cuda"
+            _BUILD_DESC="building"
+            _NVCC_CHECK="$(_nvcc_meets_llama_minimum "$NVCC_PATH")"
+            _NVCC_STATUS="$(printf '%s\\n' "$_NVCC_CHECK" | sed -n '1p')"
+            _NVCC_VER="$(printf '%s\\n' "$_NVCC_CHECK" | sed -n '2p')"
+            _DRIVER_MAX_CUDA="12.9"
+            _CUDA_TOOLKIT_ALLOWED=true
+            if [ "$_NVCC_STATUS" != "too_old" ] && \
+               [ -n "$_NVCC_VER" ] && \
+               _cuda_toolkit_major_gt_driver "$_NVCC_VER" "$_DRIVER_MAX_CUDA"; then
+                _BLOCKED_NVCC_VER="$_NVCC_VER"
+                if _ALT_NVCC_CHECK="$(_cuda_find_compatible_nvcc_for_driver "$_DRIVER_MAX_CUDA" "$NVCC_PATH")"; then
+                    NVCC_PATH="$(printf '%s\\n' "$_ALT_NVCC_CHECK" | sed -n '1p')"
+                    _NVCC_VER="$(printf '%s\\n' "$_ALT_NVCC_CHECK" | sed -n '2p')"
+                    GPU_BACKEND="cuda"
+                    substep "CUDA Toolkit $_BLOCKED_NVCC_VER is a major-version mismatch with driver CUDA $_DRIVER_MAX_CUDA; using compatible CUDA Toolkit $_NVCC_VER at $NVCC_PATH."
+                else
+                    NVCC_PATH=""
+                    GPU_BACKEND=""
+                    _BUILD_DESC="building (CPU, CUDA toolkit major > driver)"
+                    _CUDA_TOOLKIT_ALLOWED=false
+                fi
+            fi
+            printf 'NVCC_PATH=%s\\n' "$NVCC_PATH"
+            printf 'NVCC_VER=%s\\n' "$_NVCC_VER"
+            printf 'GPU_BACKEND=%s\\n' "$GPU_BACKEND"
+            printf 'BUILD_DESC=%s\\n' "$_BUILD_DESC"
+            printf 'ALLOWED=%s\\n' "$_CUDA_TOOLKIT_ALLOWED"
+            """
+        )
+        output = self._run_bash(script)
+        assert f"NVCC_PATH={compatible_nvcc}" in output
+        assert "NVCC_VER=12.8" in output
+        assert "GPU_BACKEND=cuda" in output
+        assert "ALLOWED=true" in output
+        assert "CPU" not in output
+
+    def test_setup_sh_parses_cuda_umd_version_variant(self, tmp_path):
+        # Newer drivers report "CUDA UMD Version"; the helper must read it too.
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 610.00   Driver Version: 610.00   CUDA UMD Version: 13.0 |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            {self._setup_sh_cuda_helper_fragment()}
+            printf '%s' "$(_cuda_driver_max_version)"
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert output.strip() == "13.0"
+
+    def test_setup_sh_empty_toolkit_version_skips_mismatch(self, tmp_path):
+        # The real guard requires a non-empty nvcc version before warning.
+        mock_bin = self._fake_nvidia_smi(
+            tmp_path,
+            "| NVIDIA-SMI 580.95   Driver Version: 580.95   CUDA Version: 13.0 |",
+        )
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            _nvcc=""
+            _driver="$(_cuda_driver_max_version)"
+            if [ -n "$_nvcc" ] && [ -n "$_driver" ] && _cuda_toolkit_major_gt_driver "$_nvcc" "$_driver"; then
+                _print_cuda_driver_toolkit_mismatch "$_nvcc" "$_driver"
+            else
+                printf 'skipped\\n'
+            fi
+            """
+        )
+        output = self._run_bash(
+            script,
+            env = {"PATH": f"{mock_bin}:{os.environ.get('PATH', '')}"},
+        )
+        assert "skipped" in output
+        assert "Unsloth supports CUDA Toolkit" not in output
+
+    def test_setup_sh_nvcc_below_minimum_is_too_old(self, tmp_path):
+        # CUDA toolkit < 12.4 short-circuits to the too_old branch (no mismatch).
+        nvcc = self._fake_nvcc(tmp_path, "12.0")
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            {self._setup_sh_cuda_helper_fragment()}
+            _nvcc_meets_llama_minimum "{nvcc}"
+            """
+        )
+        output = self._run_bash(script)
+        assert output.splitlines()[0] == "too_old"
+        assert "12.0" in output
+
+    def test_setup_sh_compatible_finder_rejects_too_old_only_candidate(self, tmp_path):
+        # Only candidate is below the llama minimum: finder must fail (CPU fallback), not pick 12.0.
+        blocked_nvcc = self._fake_nvcc(tmp_path, "13.3")
+        too_old_nvcc = self._fake_nvcc(tmp_path, "12.0")
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            {self._setup_sh_cuda_helper_fragment()}
+            _cuda_nvcc_candidate_paths() {{
+                printf '%s\\n' "{blocked_nvcc}" "{too_old_nvcc}"
+            }}
+            if _ALT="$(_cuda_find_compatible_nvcc_for_driver "12.9" "{blocked_nvcc}")"; then
+                printf 'FOUND:%s\\n' "$_ALT"
+            else
+                printf 'NONE\\n'
+            fi
+            """
+        )
+        output = self._run_bash(script)
+        assert "NONE" in output
+        assert "FOUND" not in output
+
+    def _cuda_build_decision_output(self, *, nvcc_path, driver):
+        # Mirror setup.sh's source-build decision: keep the toolkit, switch, or degrade to CPU.
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            C_WARN=
+            substep() {{ printf '%s\\n' "$1"; }}
+            {self._setup_sh_cuda_helper_fragment()}
+            NVCC_PATH="{nvcc_path}"
+            GPU_BACKEND="cuda"
+            _DRIVER_MAX_CUDA="{driver}"
+            _NVCC_CHECK="$(_nvcc_meets_llama_minimum "$NVCC_PATH")"
+            _NVCC_STATUS="$(printf '%s\\n' "$_NVCC_CHECK" | sed -n '1p')"
+            _NVCC_VER="$(printf '%s\\n' "$_NVCC_CHECK" | sed -n '2p')"
+            _CUDA_TOOLKIT_ALLOWED=true
+            if [ "$_NVCC_STATUS" = "too_old" ]; then
+                NVCC_PATH=""; GPU_BACKEND=""; _CUDA_TOOLKIT_ALLOWED=false
+            elif [ -n "$_NVCC_VER" ] && [ -n "$_DRIVER_MAX_CUDA" ] && _cuda_toolkit_major_gt_driver "$_NVCC_VER" "$_DRIVER_MAX_CUDA"; then
+                if _ALT="$(_cuda_find_compatible_nvcc_for_driver "$_DRIVER_MAX_CUDA" "$NVCC_PATH")"; then
+                    NVCC_PATH="$(printf '%s\\n' "$_ALT" | sed -n '1p')"
+                    _NVCC_VER="$(printf '%s\\n' "$_ALT" | sed -n '2p')"
+                else
+                    NVCC_PATH=""; GPU_BACKEND=""; _CUDA_TOOLKIT_ALLOWED=false
+                fi
+            fi
+            printf 'NVCC_PATH=%s\\n' "$NVCC_PATH"
+            printf 'NVCC_VER=%s\\n' "$_NVCC_VER"
+            printf 'GPU_BACKEND=%s\\n' "$GPU_BACKEND"
+            printf 'ALLOWED=%s\\n' "$_CUDA_TOOLKIT_ALLOWED"
+            """
+        )
+        return self._run_bash(script)
+
+    def test_setup_sh_same_major_newer_minor_keeps_original_toolkit(self, tmp_path):
+        # Same-major newer-minor (13.3 vs driver 13.0): build CUDA with it, never fall back.
+        toolkit = self._fake_nvcc(tmp_path, "13.3")
+        output = self._cuda_build_decision_output(nvcc_path = toolkit, driver = "13.0")
+        assert f"NVCC_PATH={toolkit}" in output
+        assert "NVCC_VER=13.3" in output
+        assert "GPU_BACKEND=cuda" in output
+        assert "ALLOWED=true" in output
+
+    def test_setup_sh_missing_driver_version_still_enables_cuda(self, tmp_path):
+        # No driver CUDA version from nvidia-smi: keep CUDA enabled (pre-fix behavior), not CPU.
+        toolkit = self._fake_nvcc(tmp_path, "13.3")
+        output = self._cuda_build_decision_output(nvcc_path = toolkit, driver = "")
+        assert f"NVCC_PATH={toolkit}" in output
+        assert "GPU_BACKEND=cuda" in output
+        assert "ALLOWED=true" in output
+
+    def test_setup_sh_compatible_finder_rejects_newer_major_only_candidate(self, tmp_path):
+        # Only alternative is still newer-major than the driver: finder must fail, not pick it.
+        blocked_nvcc = self._fake_nvcc(tmp_path, "13.3")
+        other_newer_nvcc = self._fake_nvcc(tmp_path, "13.1")
+        script = textwrap.dedent(
+            f"""\
+            set -euo pipefail
+            {self._setup_sh_cuda_helper_fragment()}
+            _cuda_nvcc_candidate_paths() {{
+                printf '%s\\n' "{blocked_nvcc}" "{other_newer_nvcc}"
+            }}
+            if _ALT="$(_cuda_find_compatible_nvcc_for_driver "12.9" "{blocked_nvcc}")"; then
+                printf 'FOUND:%s\\n' "$_ALT"
+            else
+                printf 'NONE\\n'
+            fi
+            """
+        )
+        output = self._run_bash(script)
+        assert "NONE" in output
+        assert "FOUND" not in output
diff --git a/tests/studio/test_resolve_cuda_toolkit.ps1 b/tests/studio/test_resolve_cuda_toolkit.ps1
index 42076cdfe0..77fcdca59c 100644
--- a/tests/studio/test_resolve_cuda_toolkit.ps1
+++ b/tests/studio/test_resolve_cuda_toolkit.ps1
@@ -1,7 +1,7 @@
 #!/usr/bin/env pwsh
 # Unit test for Resolve-CudaToolkit in studio/setup.ps1. No GPU required: the
 # detection helpers (nvidia-smi, nvcc, Find-Nvcc, ...) are stubbed so the real
-# function logic runs against a spoofed Blackwell sm_120 / driver 13.2 host.
+# function logic runs against spoofed Blackwell sm_120 driver/toolkit scenarios.
 #
 # The function is extracted via AST and run in a child pwsh per scenario, because
 # the -RequireOrExit path calls `exit` (which would otherwise kill this harness).
@@ -22,13 +22,24 @@ $fn = $ast.FindAll({ param($n)
 if ($fn.Count -ne 1) { throw "expected exactly one Resolve-CudaToolkit, found $($fn.Count)" }
 $fnText = $fn[0].Extent.Text
 
-# --- Spoof executables: nvidia-smi reports driver max CUDA 13.2; nvcc 13.3 ---
+# Resolve-CudaToolkit calls Write-CudaDriverToolkitMismatch, so extract it too.
+$mismatchFn = $ast.FindAll({ param($n)
+    $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq "Write-CudaDriverToolkitMismatch"
+}, $true)
+if ($mismatchFn.Count -ne 1) { throw "expected exactly one Write-CudaDriverToolkitMismatch, found $($mismatchFn.Count)" }
+$mismatchText = $mismatchFn[0].Extent.Text
+
+# --- Spoof executables for driver/toolkit compatibility scenarios ---
 $work = Join-Path ([System.IO.Path]::GetTempPath()) ("rct_" + [guid]::NewGuid().ToString("N"))
 New-Item -ItemType Directory -Force -Path $work | Out-Null
-$smiFake  = Join-Path $work "nvidia-smi.ps1"
-$nvccFake = Join-Path $work "nvcc.ps1"
-Set-Content -LiteralPath $smiFake  -Value "'CUDA Version: 13.2'"
-Set-Content -LiteralPath $nvccFake -Value "'Cuda compilation tools, release 13.3, V13.3.0'"
+$smiMajorMismatchFake = Join-Path $work "nvidia-smi-12.9.ps1"
+$smiSameMajorFake     = Join-Path $work "nvidia-smi-13.2.ps1"
+$nvccIncompatibleFake = Join-Path $work "nvcc-13.3.ps1"
+$nvccCompatibleFake   = Join-Path $work "nvcc-12.8.ps1"
+Set-Content -LiteralPath $smiMajorMismatchFake -Value "'CUDA Version: 12.9'"
+Set-Content -LiteralPath $smiSameMajorFake     -Value "'CUDA Version: 13.2'"
+Set-Content -LiteralPath $nvccIncompatibleFake -Value "'Cuda compilation tools, release 13.3, V13.3.0'"
+Set-Content -LiteralPath $nvccCompatibleFake   -Value "'Cuda compilation tools, release 12.8, V12.8.0'"
 
 $failures = 0
 function Check($name, $cond) {
@@ -38,13 +49,15 @@ function Check($name, $cond) {
 
 # Build + run one scenario in a child pwsh; returns @{ Exit; Out }.
 function Run-Case {
-    param([string]$FindMode, [bool]$Require)
+    param([string]$FindMode, [bool]$Require, [string]$DriverMode = "major-mismatch")
     $requireLit = if ($Require) { '$true' } else { '$false' }
+    $smiForCase = if ($DriverMode -eq "same-major") { $smiSameMajorFake } else { $smiMajorMismatchFake }
     $child = @"
 `$ErrorActionPreference = 'Continue'
 [Environment]::SetEnvironmentVariable('CUDA_PATH', `$null, 'Process')
 `$FindNvccMode = '$FindMode'
-`$NvccFake = '$nvccFake'
+`$NvccIncompatibleFake = '$nvccIncompatibleFake'
+`$NvccCompatibleFake = '$nvccCompatibleFake'
 function substep { param(`$m, `$c) Write-Host "  `$m" }
 function step    { param(`$l, `$v, `$c) Write-Host "[`$l] `$v" }
 function Add-ToUserPath { param(`$Directory, `$Position) `$true }
@@ -57,17 +70,20 @@ function winget { `$script:WingetCalled = `$true; 'no matching versions' }
 function Find-Nvcc {
     param([string]`$MaxVersion = '')
     switch (`$FindNvccMode) {
-        'compatible'   { return `$NvccFake }
-        'incompatible' { if (`$MaxVersion) { return `$null } else { return `$NvccFake } }
+        'compatible'   { return `$NvccCompatibleFake }
+        'same-major'   { return `$NvccIncompatibleFake }
+        'incompatible' { if (`$MaxVersion) { return `$null } else { return `$NvccIncompatibleFake } }
         default        { return `$null }
     }
 }
-`$NvidiaSmiExe  = '$smiFake'
+`$NvidiaSmiExe  = '$smiForCase'
 `$VsInstallPath = `$null
 `$HasNvidiaSmi  = `$true
 `$script:CudaToolkitReady = `$false
 `$script:NvccPath = `$null; `$script:CudaToolkitRoot = `$null; `$script:CudaArch = `$null
 
+$mismatchText
+
 $fnText
 
 if ($requireLit) { Resolve-CudaToolkit -RequireOrExit } else { Resolve-CudaToolkit }
@@ -80,37 +96,54 @@ Write-Host ("RESULT ready={0} nvcc={1} winget={2}" -f `$script:CudaToolkitReady,
 }
 
 try {
-    Write-Host "Scenario 1: prebuilt path, too-new toolkit (no -RequireOrExit) -> defers, no exit"
+    Write-Host "Scenario 1: prebuilt path, newer-major toolkit (no -RequireOrExit) -> defers, no exit"
     $r = Run-Case -FindMode "incompatible" -Require $false
     Check "exits 0 (not blocked)"        ($r.Exit -eq 0)
     Check "CudaToolkitReady = false"     ($r.Out -match "ready=False")
     Check "winget NOT called"            ($r.Out -match "winget=False")
-    Check "no INCOMPATIBLE error text"   (-not ($r.Out -match "INCOMPATIBLE"))
+    Check "explains major mismatch"      ($r.Out -match "major-version mismatch")
+    Check "does not blame the toolkit"   (-not ($r.Out -match "INCOMPATIBLE"))
 
-    Write-Host "Scenario 2: forced source build, too-new toolkit (-RequireOrExit) -> hard exit"
+    Write-Host "Scenario 2: forced source build, newer-major toolkit (-RequireOrExit) -> hard exit"
     $r = Run-Case -FindMode "incompatible" -Require $true
     Check "exits non-zero"               ($r.Exit -ne 0)
-    Check "preserved INCOMPATIBLE error" ($r.Out -match "is installed but INCOMPATIBLE")
+    Check "explains major mismatch"      ($r.Out -match "major-version mismatch")
+    Check "one-line source-build error"  ($r.Out -match "CUDA source build cannot use the installed toolkit")
 
-    Write-Host "Scenario 3: compatible toolkit (-RequireOrExit) -> resolves, env set"
+    Write-Host "Scenario 3: same-major newer-minor toolkit (-RequireOrExit) -> resolves, env set"
+    $r = Run-Case -FindMode "same-major" -Require $true -DriverMode "same-major"
+    Check "exits 0"                      ($r.Exit -eq 0)
+    Check "CudaToolkitReady = true"      ($r.Out -match "ready=True")
+    Check "NvccPath published"           ($r.Out -match "nvcc=.*nvcc-13\.3")
+    Check "no mismatch warning"          (-not ($r.Out -match "major-version mismatch"))
+
+    Write-Host "Scenario 4: compatible older-major toolkit (-RequireOrExit) -> resolves, env set"
     $r = Run-Case -FindMode "compatible" -Require $true
     Check "exits 0"                      ($r.Exit -eq 0)
     Check "CudaToolkitReady = true"      ($r.Out -match "ready=True")
     Check "NvccPath published"           ($r.Out -match "nvcc=.*nvcc")
 
-    Write-Host "Scenario 4: no toolkit, prebuilt path (no -RequireOrExit) -> defers, no winget"
+    Write-Host "Scenario 5: no toolkit, prebuilt path (no -RequireOrExit) -> defers, no winget"
     $r = Run-Case -FindMode "none" -Require $false
     Check "exits 0"                      ($r.Exit -eq 0)
     Check "CudaToolkitReady = false"     ($r.Out -match "ready=False")
     Check "winget NOT called"            ($r.Out -match "winget=False")
 
-    Write-Host "Scenario 5: no toolkit, forced (-RequireOrExit) -> winget attempted then exit"
+    Write-Host "Scenario 6: no toolkit, forced (-RequireOrExit) -> winget attempted then exit"
     # The function exits before the RESULT line here, so assert on the winget-block
     # marker in output rather than the flag.
     $r = Run-Case -FindMode "none" -Require $true
     Check "winget attempted"             ($r.Out -match "installing via winget")
     Check "exits non-zero"               ($r.Exit -ne 0)
     Check "preserved nvcc-required error" ($r.Out -match "CUDA Toolkit \(nvcc\) is required")
+
+    Write-Host "Scenario 7: same-major toolkit only on PATH, missed by -MaxVersion (-RequireOrExit) -> accepted, not rejected"
+    # -MaxVersion misses it (not in side-by-side base) but plain Find-Nvcc finds it on PATH: must be used.
+    $r = Run-Case -FindMode "incompatible" -Require $true -DriverMode "same-major"
+    Check "exits 0"                      ($r.Exit -eq 0)
+    Check "CudaToolkitReady = true"      ($r.Out -match "ready=True")
+    Check "NvccPath published"           ($r.Out -match "nvcc=.*nvcc-13\.3")
+    Check "no mismatch warning"          (-not ($r.Out -match "major-version mismatch"))
 }
 finally {
     Remove-Item -Recurse -Force -LiteralPath $work -ErrorAction SilentlyContinue

From 3307561f8533578e36d530d726b8ef762d2ff45f Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 02:20:27 -0700
Subject: [PATCH 132/222] Studio: npm v12 readiness for install-script gating
 (#6128)

npm 12 (July 2026) stops running dependency install scripts unless they
are approved via allowScripts, and npm 11.16 already warns. Studio has
no git or remote URL deps anywhere, so script gating is the only
exposure:

- commit the allowScripts policy that npm approve-scripts writes for
  @biomejs/biome and msw, plus a manual fsevents entry: the tooling
  cannot match a darwin-only optional dep from Linux, but the strict
  check walks the platform independent ideal tree and flags it anyway
- drop the minimum-release-age npmrc alias; npm >=11.16 flags it as an
  unknown project config that stops working in npm 12
- approve bun's postinstall in the setup.sh / setup.ps1 bun bootstrap;
  under npm 12 defaults npm install -g bun otherwise leaves a broken
  stub and setup falls back to the slower npm install path
- fix the stale esbuild comment in studio-frontend-ci.yml: the vite 8
  chain ships napi binaries with no install scripts
---
 .github/workflows/studio-frontend-ci.yml | 11 +++++------
 studio/frontend/.npmrc                   |  7 ++-----
 studio/frontend/package.json             |  5 +++++
 studio/setup.ps1                         |  4 +++-
 studio/setup.sh                          |  4 +++-
 5 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/studio-frontend-ci.yml b/.github/workflows/studio-frontend-ci.yml
index 1270a57ef6..b5a7efb29d 100644
--- a/.github/workflows/studio-frontend-ci.yml
+++ b/.github/workflows/studio-frontend-ci.yml
@@ -69,12 +69,11 @@ jobs:
         run: python3 scripts/lockfile_supply_chain_audit.py
 
       - name: Lockfile must agree with package.json (npm ci is strict)
-        # Lifecycle scripts (esbuild native-binary postinstall, etc.) are
-        # required for `vite build`. The pre-install lockfile structural
-        # audit (lockfile_supply_chain_audit.py) is the practical defence
-        # against the npm postinstall-dropper class -- it fires BEFORE any
-        # tarball runs, on the injection pattern itself rather than an
-        # advisory-DB lookup.
+        # The vite 8 chain (rolldown, lightningcss, tailwind oxide) ships napi
+        # binaries with no install scripts. The only script-bearing deps are
+        # covered by `allowScripts` in package.json (npm >=11.16, default in
+        # npm 12). The pre-install lockfile audit above stays the first line
+        # of defence -- it fires before any tarball can run code.
         run: npm ci --no-fund --no-audit
 
       - name: npm ci must not have modified the working tree
diff --git a/studio/frontend/.npmrc b/studio/frontend/.npmrc
index 8e21abe7a2..f2d15a4f15 100644
--- a/studio/frontend/.npmrc
+++ b/studio/frontend/.npmrc
@@ -6,11 +6,8 @@
 # upstream removal. npm interprets the bare integer as DAYS; do not
 # append `d`, npm 11.x will parse `7d` as a Date string and abort.
 min-release-age=7
-# Defensive alias: `minimum-release-age` takes minutes (10080 = 7 days).
-# Some npm versions / wrappers consult one key but not the other; setting
-# both means a single setting-name parse change upstream cannot silently
-# disable the cooldown. The two keys MUST agree; do not let them drift.
-minimum-release-age=10080
+# Do not re-add the old `minimum-release-age` alias: npm >=11.16 warns on
+# unknown project configs and npm 12 stops accepting them.
 # Belt-and-braces: refuse to write back loose `^x.y.z` ranges into
 # package.json when a maintainer runs `npm install <pkg>` locally. This
 # does NOT rewrite already-present ranges (those need an explicit
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 1e527813f9..2217dd080b 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -108,5 +108,10 @@
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.55.0",
     "vite": "^8.0.1"
+  },
+  "allowScripts": {
+    "@biomejs/biome@1.9.4": true,
+    "msw@2.14.3": true,
+    "fsevents": true
   }
 }
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 920d1af13a..9a919e31e3 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -1405,7 +1405,9 @@ if ($IsPipInstall) {
         substep "installing bun (faster frontend package installs)..."
         $prevEAP_bun = $ErrorActionPreference
         $ErrorActionPreference = "Continue"
-        Invoke-SetupCommand { npm install -g bun } | Out-Null
+        # --allow-scripts=bun: npm >=11.16 gates install scripts and bun's
+        # postinstall fetches its binary; without it the install is a broken stub.
+        Invoke-SetupCommand { npm install -g bun --allow-scripts=bun } | Out-Null
         $ErrorActionPreference = $prevEAP_bun
         Refresh-Environment
         if (Get-Command bun -ErrorAction SilentlyContinue) {
diff --git a/studio/setup.sh b/studio/setup.sh
index 0db9a612c8..15a20a572f 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -435,7 +435,9 @@ verbose_substep "node check: NEED_NODE=$NEED_NODE NODE_OK=${NODE_OK:-unknown} NP
 # avoids platform-specific installers, PATH issues, and admin requirements.
 if ! command -v bun &>/dev/null; then
     substep "installing bun..."
-    if run_maybe_quiet npm install -g bun && command -v bun &>/dev/null; then
+    # --allow-scripts=bun: npm >=11.16 gates install scripts and bun's
+    # postinstall fetches its binary; without it the install is a broken stub.
+    if run_maybe_quiet npm install -g bun --allow-scripts=bun && command -v bun &>/dev/null; then
         substep "bun installed ($(bun --version))"
     else
         substep "bun install skipped (npm will be used instead)"

From 87deee7fbdc6a0d3ef672866c90b75090689c9fd Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 02:35:27 -0700
Subject: [PATCH 133/222] Studio: faithful conversation export and import round
 trips (ShareGPT system role, CSV quoted newlines) (#6131)

* fix(studio): preserve system role in ShareGPT exports

System messages in ShareGPT conversation exports were serialized as
gpt turns, which changes the semantics of exported training data.
Map role system to from system in both the single-thread and bulk
export paths, matching the importer (sharegptToRecords), which
already maps from system back to a system role.

Extracted from #5606 by @LeoBorcherding (commit 7b277913).

* fix(studio): parse quoted newlines when importing conversation CSV

csvToRecords split the file on raw newlines before parsing quotes, so
any exported message containing a newline broke on re-import (the
record was cut mid-field and remainder lines were dropped). The module
already ships an RFC 4180 parser (parseCsv) used by the prompt and
list importers; use it for conversation CSV too.

Multi-line content, embedded quotes and commas, and CRLF files now
round-trip. Unquoted commas in hand-made CSV keep the previous
behavior (rest of line is the content). Flagged in #5606 review as
'Preserve quoted newlines when importing CSV'.
---
 .../prompt-storage/prompt-storage-dialog.tsx  | 34 ++++++-------------
 1 file changed, 10 insertions(+), 24 deletions(-)

diff --git a/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
index 80c2de54a2..3908c313b6 100644
--- a/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
+++ b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
@@ -331,7 +331,7 @@ function messageToOpenAI(msg: { role: unknown; content: unknown; attachments?: u
   return contentParts.length > 0 ? [{ role: role as "user" | "system", content: contentParts }] : [];
 }
 
-// ShareGPT training JSONL (human/gpt turns).
+// ShareGPT training JSONL (human/system/gpt turns).
 export async function exportConversationShareGPT(threadId: string): Promise<void> {
   const messages = await loadConversationMessages(threadId);
   if (!messages) return;
@@ -339,7 +339,7 @@ export async function exportConversationShareGPT(threadId: string): Promise<void
   const conversations: Array<{ from: string; value: string }> = [];
   for (const msg of messages) {
     const role = msg.role as string;
-    const from = role === "user" ? "human" : "gpt";
+    const from = role === "user" ? "human" : role === "system" ? "system" : "gpt";
     const value = messageToText(msg);
     if (value.trim()) conversations.push({ from, value });
   }
@@ -413,7 +413,7 @@ async function buildThreadContent(
     for (const msg of messages) {
       const role = msg.role as string;
       const value = messageToText(msg);
-      if (value.trim()) conversations.push({ from: role === "user" ? "human" : "gpt", value });
+      if (value.trim()) conversations.push({ from: role === "user" ? "human" : role === "system" ? "system" : "gpt", value });
     }
     if (conversations.length === 0) return null;
     return JSON.stringify({ conversations });
@@ -626,30 +626,16 @@ function sharegptToRecords(
 }
 
 function csvToRecords(csvText: string, threadId: string, baseTs: number): MessageRecord[] {
-  const lines = csvText.split(/\r?\n/);
+  // parseCsv handles quoted newlines, so multi-line message content
+  // round-trips; a naive per-line split would break those records.
+  const rows = parseCsv(csvText).slice(1);
   const records: MessageRecord[] = [];
   let prevId: string | null = null;
   let idx = 0;
-  for (let i = 1; i < lines.length; i++) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    let role = "";
-    let content = "";
-    if (line.startsWith('"')) {
-      const m = line.match(/^"((?:[^"]|"")*)"\s*,\s*([\s\S]*)$/);
-      if (!m) continue;
-      role = m[1].replace(/""/g, '"');
-      content = m[2].startsWith('"')
-        ? m[2].slice(1, m[2].endsWith('"') ? -1 : undefined).replace(/""/g, '"')
-        : m[2];
-    } else {
-      const comma = line.indexOf(",");
-      if (comma === -1) continue;
-      role = line.slice(0, comma);
-      content = line.slice(comma + 1).startsWith('"')
-        ? line.slice(comma + 2, line.endsWith('"') ? -1 : undefined).replace(/""/g, '"')
-        : line.slice(comma + 1);
-    }
+  for (const row of rows) {
+    if (row.length < 2) continue;
+    const role = row[0].trim();
+    const content = row.slice(1).join(",");
     if (!content.trim()) continue;
     const validRole = role === "user" || role === "assistant" || role === "system" ? role : "user";
     const id = crypto.randomUUID();

From f41617ad9f0f34c54c0ef66d99e85f851ca4d5c0 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 02:35:37 -0700
Subject: [PATCH 134/222] Studio: auto-sync allowScripts pins after dependency
 bumps (#6136)

* Studio: npm v12 readiness for install-script gating

npm 12 (July 2026) stops running dependency install scripts unless they
are approved via allowScripts, and npm 11.16 already warns. Studio has
no git or remote URL deps anywhere, so script gating is the only
exposure:

- commit the allowScripts policy that npm approve-scripts writes for
  @biomejs/biome and msw, plus a manual fsevents entry: the tooling
  cannot match a darwin-only optional dep from Linux, but the strict
  check walks the platform independent ideal tree and flags it anyway
- drop the minimum-release-age npmrc alias; npm >=11.16 flags it as an
  unknown project config that stops working in npm 12
- approve bun's postinstall in the setup.sh / setup.ps1 bun bootstrap;
  under npm 12 defaults npm install -g bun otherwise leaves a broken
  stub and setup falls back to the slower npm install path
- fix the stale esbuild comment in studio-frontend-ci.yml: the vite 8
  chain ships napi binaries with no install scripts

* Studio: auto-sync allowScripts pins after dependency bumps

The allowScripts entries from #6128 are version pinned, so a biome or
msw bump strands the pin and the approval silently stops matching.
Dependabot cannot maintain the field, so:

- scripts/sync_allow_scripts_pins.py re-pins existing entries from the
  versions package-lock.json actually resolves. It never adds or
  removes entries, so approving a new script-bearing package stays a
  human decision. Bare names and non-exact specs are left alone.
- a pre-commit hook runs it with --fix; pre-commit.ci pushes the fix
  commit to PR branches, Dependabot's included, so stale pins heal
  without a human in the loop
- a Frontend CI step runs --check plus the offline unit tests as the
  backstop when pre-commit.ci is skipped

No dependabot.yml change needed: the /studio/frontend entry already
suppresses version PRs (security only) behind a 7 day cooldown.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Make the sync hook robust to lost executable bits

The pre-commit.ci autofix commit dropped the script's exec bit, which
breaks a shebang-style entry. Invoke via python instead and restore
the bit.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .github/workflows/studio-frontend-ci.yml     |  10 ++
 .pre-commit-config.yaml                      |  12 ++
 scripts/sync_allow_scripts_pins.py           | 143 +++++++++++++++++++
 tests/studio/test_sync_allow_scripts_pins.py | 141 ++++++++++++++++++
 4 files changed, 306 insertions(+)
 create mode 100644 scripts/sync_allow_scripts_pins.py
 create mode 100644 tests/studio/test_sync_allow_scripts_pins.py

diff --git a/.github/workflows/studio-frontend-ci.yml b/.github/workflows/studio-frontend-ci.yml
index b5a7efb29d..3abfea8450 100644
--- a/.github/workflows/studio-frontend-ci.yml
+++ b/.github/workflows/studio-frontend-ci.yml
@@ -17,6 +17,8 @@ on:
       - 'studio/frontend/**'
       - 'scripts/check_frontend_dep_removal.py'
       - 'tests/studio/test_frontend_dep_removal.py'
+      - 'scripts/sync_allow_scripts_pins.py'
+      - 'tests/studio/test_sync_allow_scripts_pins.py'
       - '.github/workflows/studio-frontend-ci.yml'
   push:
     branches: [main, pip]
@@ -68,6 +70,14 @@ jobs:
         working-directory: ${{ github.workspace }}
         run: python3 scripts/lockfile_supply_chain_audit.py
 
+      # Dependency bumps strand the version-pinned allowScripts entries.
+      # The paired pre-commit hook auto-fixes PRs; this is the backstop.
+      - name: allowScripts pins must match the lockfile
+        working-directory: ${{ github.workspace }}
+        run: |
+          python3 tests/studio/test_sync_allow_scripts_pins.py
+          python3 scripts/sync_allow_scripts_pins.py --check
+
       - name: Lockfile must agree with package.json (npm ci is strict)
         # The vite 8 chain (rolldown, lightningcss, tailwind oxide) ships napi
         # binaries with no install scripts. The only script-bearing deps are
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 56d32c9312..cffbf73cd5 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -19,3 +19,15 @@ repos:
         exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$'
         additional_dependencies:
           - ruff==0.6.9
+      # Re-pins allowScripts entries after dependency bumps. pre-commit.ci
+      # pushes the fix to PR branches, Dependabot's included, so stale pins
+      # heal without a human in the loop.
+      - id: sync-allow-scripts-pins
+        name: Sync allowScripts pins with the frontend lockfile
+        # `python <script>` not a direct exec: autofix commits can drop the
+        # executable bit, which kills shebang-style entries.
+        entry: python scripts/sync_allow_scripts_pins.py
+        args: [--fix]
+        language: python
+        files: ^studio/frontend/(package\.json|package-lock\.json)$
+        pass_filenames: false
diff --git a/scripts/sync_allow_scripts_pins.py b/scripts/sync_allow_scripts_pins.py
new file mode 100644
index 0000000000..1d9a075ab4
--- /dev/null
+++ b/scripts/sync_allow_scripts_pins.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Keep `allowScripts` pins in studio/frontend/package.json in sync with
+package-lock.json.
+
+`npm approve-scripts` writes version-pinned entries ("pkg@1.2.3": true).
+A dependency bump strands the pin, so the approval (or denial) silently
+stops matching and the package's install scripts fall back to
+"unreviewed". This tool re-pins existing entries to the versions the
+lockfile actually resolves; it never adds or removes entries, so
+approving a brand-new script-bearing package stays a human decision.
+
+Usage:
+  python scripts/sync_allow_scripts_pins.py --check   # CI: exit 1 on drift
+  python scripts/sync_allow_scripts_pins.py --fix     # rewrite package.json
+
+Pinned keys follow npm's allowScripts grammar: "name@1.2.3" or
+"name@1.2.3 || 1.2.4". Bare names (no version) match every version and
+are left alone. Entries whose range is not an exact-version disjunction
+(wildcards, tags) are left alone too.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_DIR = REPO_ROOT / "studio" / "frontend"
+
+EXACT_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$")
+
+
+def split_spec(key: str) -> tuple[str, str | None]:
+    """'@scope/name@1.2.3' -> ('@scope/name', '1.2.3'); bare names -> (key, None)."""
+    if key.startswith("@"):
+        rest = key[1:]
+        if "@" not in rest:
+            return key, None
+        name, rng = rest.split("@", 1)
+        return "@" + name, rng
+    if "@" not in key:
+        return key, None
+    name, rng = key.split("@", 1)
+    return name, rng
+
+
+def is_exact_disjunction(rng: str) -> bool:
+    parts = [p.strip() for p in rng.split("||")]
+    return all(EXACT_VERSION_RE.match(p) for p in parts) and bool(parts)
+
+
+def version_sort_key(version: str) -> tuple:
+    release = version.split("-", 1)[0].split("+", 1)[0]
+    return tuple(int(x) for x in release.split(".")), version
+
+
+def script_versions_from_lock(lock: dict) -> dict[str, list[str]]:
+    """Map package name -> sorted versions that carry install scripts."""
+    out: dict[str, set[str]] = {}
+    for path, meta in (lock.get("packages") or {}).items():
+        if not path or not meta.get("hasInstallScript"):
+            continue
+        name = path.rsplit("node_modules/", 1)[-1]
+        version = meta.get("version")
+        if name and version:
+            out.setdefault(name, set()).add(version)
+    return {n: sorted(vs, key = version_sort_key) for n, vs in out.items()}
+
+
+def desired_key(name: str, versions: list[str]) -> str:
+    return f"{name}@{' || '.join(versions)}"
+
+
+def compute_renames(policy: dict, lock_versions: dict[str, list[str]]) -> dict[str, str]:
+    renames: dict[str, str] = {}
+    for key in policy:
+        name, rng = split_spec(key)
+        if rng is None or not is_exact_disjunction(rng):
+            continue  # bare name or non-exact spec: matches by name, never stale
+        versions = lock_versions.get(name)
+        if not versions:
+            continue  # package gone or script-free now: stale pin is inert
+        want = desired_key(name, versions)
+        if key != want:
+            renames[key] = want
+    return renames
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description = __doc__)
+    mode = ap.add_mutually_exclusive_group(required = True)
+    mode.add_argument("--check", action = "store_true", help = "exit 1 if pins are stale")
+    mode.add_argument("--fix", action = "store_true", help = "rewrite package.json in place")
+    ap.add_argument(
+        "--dir",
+        type = Path,
+        default = DEFAULT_DIR,
+        help = "directory holding package.json + package-lock.json",
+    )
+    args = ap.parse_args(argv)
+
+    pkg_path = args.dir / "package.json"
+    lock_path = args.dir / "package-lock.json"
+    if not pkg_path.exists() or not lock_path.exists():
+        print(f"sync-allow-scripts: nothing to do ({args.dir} has no package.json + lockfile)")
+        return 0
+
+    pkg = json.loads(pkg_path.read_text(encoding = "utf-8"))
+    policy = pkg.get("allowScripts")
+    if not isinstance(policy, dict) or not policy:
+        print("sync-allow-scripts: no allowScripts policy in package.json, nothing to do")
+        return 0
+
+    lock = json.loads(lock_path.read_text(encoding = "utf-8"))
+    renames = compute_renames(policy, script_versions_from_lock(lock))
+
+    if not renames:
+        print(f"sync-allow-scripts: {len(policy)} allowScripts entries in sync with the lockfile")
+        return 0
+
+    for old, new in renames.items():
+        print(f'  stale pin: "{old}" -> "{new}"')
+
+    if args.check:
+        print(
+            "sync-allow-scripts: pins are stale; run "
+            "`python scripts/sync_allow_scripts_pins.py --fix` and commit the result"
+        )
+        return 1
+
+    pkg["allowScripts"] = {renames.get(k, k): v for k, v in policy.items()}
+    pkg_path.write_text(json.dumps(pkg, indent = 2, ensure_ascii = False) + "\n", encoding = "utf-8")
+    print(
+        f"sync-allow-scripts: re-pinned {len(renames)} entr{'y' if len(renames) == 1 else 'ies'} in {pkg_path}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/studio/test_sync_allow_scripts_pins.py b/tests/studio/test_sync_allow_scripts_pins.py
new file mode 100644
index 0000000000..2aa0e9368c
--- /dev/null
+++ b/tests/studio/test_sync_allow_scripts_pins.py
@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Offline tests for scripts/sync_allow_scripts_pins.py."""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+import sync_allow_scripts_pins as sync  # noqa: E402
+
+
+def write_fixture(tmp: Path, policy: dict, lock_packages: dict) -> None:
+    (tmp / "package.json").write_text(
+        json.dumps(
+            {
+                "name": "fixture",
+                "dependencies": {"a": "^1.0.0"},
+                "allowScripts": policy,
+            },
+            indent = 2,
+        )
+        + "\n"
+    )
+    (tmp / "package-lock.json").write_text(
+        json.dumps(
+            {
+                "lockfileVersion": 3,
+                "packages": lock_packages,
+            }
+        )
+        + "\n"
+    )
+
+
+LOCK = {
+    "": {"name": "fixture"},
+    "node_modules/@biomejs/biome": {"version": "1.9.9", "hasInstallScript": True},
+    "node_modules/msw": {"version": "2.15.0", "hasInstallScript": True},
+    "node_modules/vite/node_modules/fsevents": {"version": "2.3.3", "hasInstallScript": True},
+    "node_modules/clean": {"version": "3.0.0"},
+}
+
+
+def test_split_spec():
+    assert sync.split_spec("fsevents") == ("fsevents", None)
+    assert sync.split_spec("@biomejs/biome") == ("@biomejs/biome", None)
+    assert sync.split_spec("@biomejs/biome@1.9.4") == ("@biomejs/biome", "1.9.4")
+    assert sync.split_spec("msw@2.14.3 || 2.15.0") == ("msw", "2.14.3 || 2.15.0")
+
+
+def test_in_sync_is_clean():
+    with tempfile.TemporaryDirectory() as d:
+        tmp = Path(d)
+        write_fixture(
+            tmp,
+            {
+                "@biomejs/biome@1.9.9": True,
+                "msw@2.15.0": True,
+                "fsevents": True,
+            },
+            LOCK,
+        )
+        assert sync.main(["--check", "--dir", str(tmp)]) == 0
+
+
+def test_stale_pin_fails_check_and_fix_repairs():
+    with tempfile.TemporaryDirectory() as d:
+        tmp = Path(d)
+        write_fixture(
+            tmp,
+            {
+                "@biomejs/biome@1.9.4": True,  # stale, bumped to 1.9.9
+                "msw@2.14.3": False,  # stale denial, bumped to 2.15.0
+                "fsevents": True,  # bare: never stale
+                "ghost@9.9.9": True,  # not in lockfile: left alone
+                "weird@*": True,  # non-exact spec: left alone
+            },
+            LOCK,
+        )
+        assert sync.main(["--check", "--dir", str(tmp)]) == 1
+        assert sync.main(["--fix", "--dir", str(tmp)]) == 0
+        got = json.loads((tmp / "package.json").read_text())["allowScripts"]
+        assert got == {
+            "@biomejs/biome@1.9.9": True,
+            "msw@2.15.0": False,  # value and key order preserved
+            "fsevents": True,
+            "ghost@9.9.9": True,
+            "weird@*": True,
+        }
+        assert list(got) == [
+            "@biomejs/biome@1.9.9",
+            "msw@2.15.0",
+            "fsevents",
+            "ghost@9.9.9",
+            "weird@*",
+        ]
+        assert sync.main(["--check", "--dir", str(tmp)]) == 0
+
+
+def test_multi_version_disjunction():
+    lock = dict(LOCK)
+    lock["node_modules/x/node_modules/msw"] = {"version": "2.14.3", "hasInstallScript": True}
+    with tempfile.TemporaryDirectory() as d:
+        tmp = Path(d)
+        write_fixture(tmp, {"msw@2.14.3": True}, lock)
+        assert sync.main(["--fix", "--dir", str(tmp)]) == 0
+        got = json.loads((tmp / "package.json").read_text())["allowScripts"]
+        assert got == {"msw@2.14.3 || 2.15.0": True}
+
+
+def test_no_policy_is_noop():
+    with tempfile.TemporaryDirectory() as d:
+        tmp = Path(d)
+        (tmp / "package.json").write_text(json.dumps({"name": "fixture"}) + "\n")
+        (tmp / "package-lock.json").write_text(json.dumps({"packages": {}}) + "\n")
+        before = (tmp / "package.json").read_text()
+        assert sync.main(["--fix", "--dir", str(tmp)]) == 0
+        assert (tmp / "package.json").read_text() == before
+
+
+def test_missing_files_is_noop():
+    with tempfile.TemporaryDirectory() as d:
+        assert sync.main(["--check", "--dir", d]) == 0
+
+
+if __name__ == "__main__":
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                fn()
+                print(f"PASS {name}")
+            except AssertionError as e:
+                failures += 1
+                print(f"FAIL {name}: {e}")
+    sys.exit(1 if failures else 0)

From f542ffb023adb4066242dba048caf67fbcd7082a Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 03:09:37 -0700
Subject: [PATCH 135/222] Studio: unify shadows, backgrounds and dark mode
 consistency in chat UI (#6116)

* Studio: refine chat UI shadow, background and sidebar divider

- Give both chat composers a Gemini style drop shadow with a short
  transition, and add a visible shadow in dark mode.
- Set the main chat surface to a soft off white (#fbfbfc) in light mode
  so the white composer reads as a card; dark mode is unchanged.
- Remove the divider line between the side menu and the page.

* Studio: lighten chat background to #fcfcfd

* Studio: make dark mode composer shadow visible

* Studio: drop composer shadow in dark mode

* Studio: unify all light mode shadows on the chatbox shadow

* Studio: unify dark mode surface colors and make hover states visible

* Studio: fix barely visible dark mode hover in account and plus menus

* Studio: lift settings dialog off the page background in dark mode

* Studio: drop greeting periods and restyle projects page to match the chatbox

* Studio: chatbox shadow on search dialog, grey sort pill on projects

* Studio: slimmer sidebar profile row, borderless login card

* Studio: match select popups to their trigger, taller profile hover target

* Studio: bigger projects search pill with the original chatbox glow

* Studio: keep select trigger shape while open

* Studio: center and narrow the projects search pill like Gemini

* Studio: borderless export card with the chatbox shadow

* Studio: chatbox shadow for selectable pills, warmer composer, search pill tweaks

* Studio: one warm background token for every page, softer search glow

* Studio: keep off white depth when warming the page background

* Studio: distinct sidebar surface from the page background

* Studio: white sidebar on the warm page background

* Studio: soften projects search shadow

* Studio: nudge the chat zero state up 5px

* Studio: darker dark mode page background, 28.5vh welcome offset

* Studio: dark mode shadows match the chatbox geometry, borderless recipes empty state

* Studio: revert dark mode shadows, desaturate dark recipe cards

* Studio: lift dark recipe cards, no hover shadow in dark

* Studio: drop the pale hover halo on recipe cards

* Studio: lighter dark recipe text, flat dark menus, flush select popups

* Studio: page-bg shadow on model selector, flush popovers and dropdowns

* Studio: zero menu offsets so dropdowns sit flush against triggers

* Studio: one 14px radius for list menus and sidebar buttons

* Studio: 14px buttons, pill hover shapes, narrower slider inputs

* Studio: pill buttons, keep profile row rectangular

* Studio: pill Save and Delete, small gap under account menu

* Studio: skinnier dropdown popups, larger account menu gap

* Studio: dropdown popups slightly wider than their trigger

* Restore light mode sidebar separator line

* Size panel number input pills to their content

* Lighten light mode page background

* Pure white composer, nudge page background whiter

* Use inline ch width for panel number pills

* Fix panel number pills at uniform 4ch width

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../frontend/src/components/app-sidebar.tsx   |  26 ++--
 .../src/components/assistant-ui/thread.tsx    |  10 +-
 studio/frontend/src/components/ui/button.tsx  |   2 +-
 .../frontend/src/components/ui/combobox.tsx   |   2 +-
 .../src/components/ui/dropdown-menu.tsx       |  12 +-
 studio/frontend/src/components/ui/menubar.tsx |   2 +-
 studio/frontend/src/components/ui/popover.tsx |   2 +-
 studio/frontend/src/components/ui/select.tsx  |  13 +-
 studio/frontend/src/components/ui/sidebar.tsx |   3 +-
 .../frontend/src/features/auth/login-page.tsx |   2 +-
 .../frontend/src/features/chat/chat-page.tsx  |   2 +-
 .../src/features/chat/chat-settings-sheet.tsx |  20 ++-
 .../chat/components/chat-search-dialog.tsx    |   4 +-
 .../chat/components/project-switcher.tsx      |   2 +-
 .../src/features/chat/mcp-composer-button.tsx |   2 +-
 .../src/features/chat/projects-page.tsx       |  16 +-
 .../src/features/chat/shared-composer.tsx     |   2 +-
 .../data-recipes/pages/data-recipes-page.tsx  |  26 ++--
 .../src/features/export/export-page.tsx       |   2 +-
 .../features/hub/catalog/catalog-states.tsx   |   6 +-
 .../hub/catalog/gguf-download-card.tsx        |   4 +-
 .../features/hub/catalog/hub-option-menu.tsx  |   2 +-
 .../hub/catalog/local-on-device-card.tsx      |   2 +-
 .../download-manager-panel.tsx                |   4 +-
 .../profile-personalization-panel.tsx         |   2 +-
 .../models/local-recipe-model-selector.tsx    |   2 +-
 .../src/features/settings/settings-dialog.tsx |   8 +-
 .../features/tour/components/guided-tour.tsx  |   4 +-
 studio/frontend/src/index.css                 | 137 +++++++++++-------
 29 files changed, 181 insertions(+), 140 deletions(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 2a633aeaf9..6fe3c5c787 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -223,7 +223,7 @@ function NavItem({
           onClick={onClick}
           isActive={active}
           data-tour={dataTour}
-          className="sidebar-nav-btn h-[33px] rounded-[11px] gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-[10px] group-data-[collapsible=icon]:mx-auto"
+          className="sidebar-nav-btn h-[33px] rounded-full gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-full group-data-[collapsible=icon]:mx-auto"
         >
           <HugeiconsIcon icon={icon} strokeWidth={1.75} className="size-icon! shrink-0 group-hover/menu-button:animate-icon-pop" />
           <span className="text-[14.5px] leading-[19px] tracking-nav">{label}</span>
@@ -597,7 +597,7 @@ export function AppSidebar() {
         ? "sidebar-row-action group-hover/project-chat-item:opacity-100 group-hover/project-chat-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto"
         : "sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto";
     const buttonClass = cn(
-      "sidebar-nav-btn h-[33px] cursor-pointer rounded-[11px] pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
+      "sidebar-nav-btn h-[33px] cursor-pointer rounded-full pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
       variant === "project" ? "pl-[37px]" : "pl-2.5",
       variant === "project"
         ? "group-hover/project-chat-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/project-chat-item:pr-8"
@@ -647,7 +647,7 @@ export function AppSidebar() {
           <DropdownMenuContent
             side="bottom"
             align="start"
-            sideOffset={6}
+            sideOffset={0}
             className="unsloth-plus-menu menu-flat-destructive w-52"
           >
             <DropdownMenuItem onSelect={() => openRenameChat(item)}>
@@ -660,7 +660,7 @@ export function AppSidebar() {
                 <span>Move to project</span>
               </DropdownMenuSubTrigger>
               <DropdownMenuSubContent
-                sideOffset={8}
+                sideOffset={0}
                 alignOffset={-4}
                 className="unsloth-plus-menu w-52"
               >
@@ -827,7 +827,7 @@ export function AppSidebar() {
         )}
       </SidebarHeader>
 
-      <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-2 pt-[9px] pb-px shrink-0">
+      <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-1.5 pt-[9px] pb-px shrink-0">
         <SidebarGroupContent>
           <SidebarMenu>
             <NavItem
@@ -867,7 +867,7 @@ export function AppSidebar() {
           scrolled && "is-scrolled",
         )}
       >
-        <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-2 py-0 shrink-0">
+        <SidebarGroup className="group-data-[collapsible=icon]:px-0 px-1.5 py-0 shrink-0">
           <SidebarGroupContent>
             <SidebarMenu>
               <NavItem
@@ -918,7 +918,7 @@ export function AppSidebar() {
               </CollapsibleTrigger>
             </SidebarGroupLabel>
             <CollapsibleContent>
-              <SidebarGroupContent className="px-2">
+              <SidebarGroupContent className="px-1.5">
                 <SidebarMenu>
                   <NavItem
                     icon={TestTubeOutlineIcon}
@@ -1025,7 +1025,7 @@ export function AppSidebar() {
                 </div>
               </SidebarGroupLabel>
               <CollapsibleContent>
-                <SidebarGroupContent className="px-2">
+                <SidebarGroupContent className="px-1.5">
                   <SidebarMenu>
                     {recentChatItems.map((item) =>
                       renderChatSidebarItem(item, "recent"),
@@ -1065,7 +1065,7 @@ export function AppSidebar() {
                       >
                         <SidebarMenuButton
                           isActive={isActiveRun}
-                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-[11px] pl-2.5 pr-7 text-[14.5px] tracking-nav font-medium"
+                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-full pl-2.5 pr-7 text-[14.5px] tracking-nav font-medium"
                           onClick={() => {
                             setSelectedHistoryRunId(run.id);
                             closeMobileIfOpen();
@@ -1106,8 +1106,8 @@ export function AppSidebar() {
                           <DropdownMenuContent
                             side="bottom"
                             align="end"
-                            sideOffset={4}
-                            className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
+                            sideOffset={0}
+                            className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-full border-0"
                           >
                             <DropdownMenuItem onSelect={() => openRenameRun(run)}>
                               <HugeiconsIcon icon={Edit03Icon} strokeWidth={1.75} className="size-icon" />
@@ -1154,7 +1154,7 @@ export function AppSidebar() {
                 <SidebarMenuButton
                   size="lg"
                   aria-label={t("shell.accountMenu", { name: displayTitle })}
-                  className="sidebar-nav-btn !h-[44px] gap-[9px] px-2 py-[3px] rounded-[14px]"
+                  className="sidebar-nav-btn !h-[44px] -my-[3px] gap-[9px] px-2 py-[3px] rounded-[14px]"
                 >
                   <div className="flex shrink-0 items-center">
                     <UserAvatar
@@ -1174,7 +1174,7 @@ export function AppSidebar() {
               <DropdownMenuContent
                 side="top"
                 align="center"
-                sideOffset={6}
+                sideOffset={8}
                 className="app-user-menu menu-soft-surface-up ring-0 w-[16rem] px-1.5 py-2.5 font-heading rounded-[20px] border-0"
               >
                 <DropdownMenuGroup>
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index b6fc554423..8146c4603b 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -740,8 +740,8 @@ function buildWelcome(hour: number, name: string): Welcome {
   // Use the name on ~a third of lines (only direct salutations where it reads
   // naturally); the rest stay name-free so greetings don't feel repetitive.
   const base: Welcome[] = [
-    g(name ? `Good to see you, ${name}.` : "Good to see you.", "large sloth wave.png"),
-    g("Ready when you are.", "large sloth thumbs.png"),
+    g(name ? `Good to see you, ${name}` : "Good to see you", "large sloth wave.png"),
+    g("Ready when you are", "large sloth thumbs.png"),
     DEFAULT_WELCOME,
     g("How can I help?", "sloth sir large.png"),
   ];
@@ -785,7 +785,7 @@ const ThreadWelcome: FC<{
 
   return (
     <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col">
-      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[28vh]">
+      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[28.5vh]">
         <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-9 px-4">
           {/* Center the greeting (sloth + title) over the composer. */}
           <div className="flex flex-row items-center justify-center gap-[15px]">
@@ -2131,7 +2131,7 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
       <DropdownMenuContent
         side={side}
         align="start"
-        sideOffset={2}
+        sideOffset={0}
         avoidCollisions={true}
         className="unsloth-plus-menu w-[212px]"
         // Don't refocus the + on close; restored focus showed a stray ring.
@@ -2655,7 +2655,7 @@ const AssistantActionBar: FC = () => {
           side="bottom"
           align="start"
           onCloseAutoFocus={(e) => e.preventDefault()}
-          className="aui-action-bar-more-content z-50 min-w-32 overflow-hidden rounded-md [--radius:1.1rem] bg-popover p-1 text-popover-foreground shadow-[0_2px_8px_-2px_rgba(27,27,31,0.16)] dark:shadow-none"
+          className="aui-action-bar-more-content z-50 min-w-32 overflow-hidden rounded-md [--radius:1.1rem] bg-popover p-1 text-popover-foreground shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:shadow-none"
         >
           <ActionBarPrimitive.ExportMarkdown asChild={true}>
             <ActionBarMorePrimitive.Item className="aui-action-bar-more-item flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground">
diff --git a/studio/frontend/src/components/ui/button.tsx b/studio/frontend/src/components/ui/button.tsx
index 9e27446989..51fc31697e 100644
--- a/studio/frontend/src/components/ui/button.tsx
+++ b/studio/frontend/src/components/ui/button.tsx
@@ -10,7 +10,7 @@ import type * as React from "react";
 import { cn } from "@/lib/utils";
 
 export const buttonVariants = cva(
-  "focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 rounded-4xl border border-transparent text-sm font-medium focus-visible:ring-[3px] aria-invalid:ring-[3px] [&_svg:not([class*='size-'])]:size-4 inline-flex items-center justify-center whitespace-nowrap transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none shrink-0 [&_svg]:shrink-0 outline-none group/button select-none cursor-pointer",
+  "focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 rounded-full border border-transparent text-sm font-medium focus-visible:ring-[3px] aria-invalid:ring-[3px] [&_svg:not([class*='size-'])]:size-4 inline-flex items-center justify-center whitespace-nowrap transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none shrink-0 [&_svg]:shrink-0 outline-none group/button select-none cursor-pointer",
   {
     variants: {
       variant: {
diff --git a/studio/frontend/src/components/ui/combobox.tsx b/studio/frontend/src/components/ui/combobox.tsx
index 53d77415e5..7eb8b07d34 100644
--- a/studio/frontend/src/components/ui/combobox.tsx
+++ b/studio/frontend/src/components/ui/combobox.tsx
@@ -146,7 +146,7 @@ function ComboboxInput({
 function ComboboxContent({
   className,
   side = "bottom",
-  sideOffset = 6,
+  sideOffset = 0,
   align = "start",
   alignOffset = 0,
   anchor,
diff --git a/studio/frontend/src/components/ui/dropdown-menu.tsx b/studio/frontend/src/components/ui/dropdown-menu.tsx
index 0ce4fd87c8..c4f742a164 100644
--- a/studio/frontend/src/components/ui/dropdown-menu.tsx
+++ b/studio/frontend/src/components/ui/dropdown-menu.tsx
@@ -36,7 +36,7 @@ function DropdownMenuTrigger({
 function DropdownMenuContent({
   className,
   align = "start",
-  sideOffset = 4,
+  sideOffset = 0,
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
   return (
@@ -46,7 +46,7 @@ function DropdownMenuContent({
         sideOffset={sideOffset}
         align={align}
         className={cn(
-          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
+          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-[calc(var(--radix-dropdown-menu-trigger-width)_+_6px)] data-[align=start]:-translate-x-[3px] data-[align=end]:translate-x-[3px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
           className,
         )}
         {...props}
@@ -78,7 +78,7 @@ function DropdownMenuItem({
       data-inset={inset}
       data-variant={variant}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 group/dropdown-menu-item relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-full px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 group/dropdown-menu-item relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
@@ -96,7 +96,7 @@ function DropdownMenuCheckboxItem({
     <DropdownMenuPrimitive.CheckboxItem
       data-slot="dropdown-menu-checkbox-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-full py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       checked={checked}
@@ -135,7 +135,7 @@ function DropdownMenuRadioItem({
     <DropdownMenuPrimitive.RadioItem
       data-slot="dropdown-menu-radio-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-lg py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground gap-2.5 rounded-full py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
@@ -221,7 +221,7 @@ function DropdownMenuSubTrigger({
       data-slot="dropdown-menu-sub-trigger"
       data-inset={inset}
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-lg px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-full px-3 py-2 text-sm [&_svg:not([class*='size-'])]:size-4 flex cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
diff --git a/studio/frontend/src/components/ui/menubar.tsx b/studio/frontend/src/components/ui/menubar.tsx
index 14befd8b7c..35b2843102 100644
--- a/studio/frontend/src/components/ui/menubar.tsx
+++ b/studio/frontend/src/components/ui/menubar.tsx
@@ -72,7 +72,7 @@ function MenubarContent({
   className,
   align = "start",
   alignOffset = -4,
-  sideOffset = 8,
+  sideOffset = 0,
   ...props
 }: React.ComponentProps<typeof MenubarPrimitive.Content>) {
   return (
diff --git a/studio/frontend/src/components/ui/popover.tsx b/studio/frontend/src/components/ui/popover.tsx
index a3fdac2100..800bd9c7da 100644
--- a/studio/frontend/src/components/ui/popover.tsx
+++ b/studio/frontend/src/components/ui/popover.tsx
@@ -23,7 +23,7 @@ function PopoverTrigger({
 function PopoverContent({
   className,
   align = "center",
-  sideOffset = 4,
+  sideOffset = 0,
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Content>) {
   return (
diff --git a/studio/frontend/src/components/ui/select.tsx b/studio/frontend/src/components/ui/select.tsx
index 03c584fdd1..0ec21850ac 100644
--- a/studio/frontend/src/components/ui/select.tsx
+++ b/studio/frontend/src/components/ui/select.tsx
@@ -63,7 +63,9 @@ function SelectTrigger({
   children,
   icon,
   iconClassName,
-  animateRadius = true,
+  /* Off by default: the radius morph matched the old item-aligned popup
+     that overlaid the trigger; popper menus drop below it instead. */
+  animateRadius = false,
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
   size?: "sm" | "default";
@@ -111,7 +113,7 @@ function SelectTrigger({
 function SelectContent({
   className,
   children,
-  position = "item-aligned",
+  position = "popper",
   align = "center",
   container,
   ...props
@@ -125,9 +127,8 @@ function SelectContent({
         data-slot="select-content"
         data-align-trigger={position === "item-aligned"}
         className={cn(
-          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 min-w-36 rounded-xl p-1 corner-squircle duration-100 relative z-50 max-h-(--radix-select-content-available-height) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto ",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+          "bg-popover text-popover-foreground font-heading data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 min-w-36 rounded-xl p-1 corner-squircle duration-100 relative z-50 max-h-(--radix-select-content-available-height) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto ",
+          // No popper translate offset: the menu sits flush against the trigger.
           className,
         )}
         position={position}
@@ -172,7 +173,7 @@ function SelectItem({
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-xl corner-squircle py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2 relative flex w-full cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        "focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2.5 rounded-full py-2 pr-8 pl-3 text-sm [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2 relative flex w-full cursor-pointer items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
diff --git a/studio/frontend/src/components/ui/sidebar.tsx b/studio/frontend/src/components/ui/sidebar.tsx
index b3bae96ce7..eb1e1e1eaf 100644
--- a/studio/frontend/src/components/ui/sidebar.tsx
+++ b/studio/frontend/src/components/ui/sidebar.tsx
@@ -305,9 +305,8 @@ function Sidebar({
           data-sidebar="sidebar"
           data-slot="sidebar-inner"
           className={cn(
-            "bg-sidebar flex size-full flex-col overflow-hidden border-r border-sidebar-border",
+            "bg-sidebar flex size-full flex-col overflow-hidden border-r border-sidebar-border dark:border-r-0",
             "group-data-[variant=floating]:ring-sidebar-border group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1",
-            hasPinMode && "ring-1 ring-sidebar-border/60",
           )}
         >
           {children}
diff --git a/studio/frontend/src/features/auth/login-page.tsx b/studio/frontend/src/features/auth/login-page.tsx
index 6f4d03f1a1..eb33a6a71b 100644
--- a/studio/frontend/src/features/auth/login-page.tsx
+++ b/studio/frontend/src/features/auth/login-page.tsx
@@ -16,7 +16,7 @@ export function LoginPage() {
         length="70vh"
         style={{ opacity: 0.4 }}
       />
-      <Card className="relative z-10 w-full max-w-sm px-5 py-6 shadow-border ring-1 ring-border sm:px-6 sm:py-8">
+      <Card className="relative z-10 w-full max-w-sm px-5 py-6 shadow-border ring-0 sm:px-6 sm:py-8">
         <AuthForm mode="login" />
       </Card>
     </div>
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 4472fffe7f..41451d06b1 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -1009,7 +1009,7 @@ function ProjectLanding({
                             : { compare: item.id, project: projectId },
                       });
                     }}
-                    className="group flex min-h-[58px] w-full items-center gap-4 rounded-[10px] px-4 py-2 text-left transition-colors hover:bg-nav-surface-hover"
+                    className="group flex min-h-[58px] w-full items-center gap-4 rounded-full px-4 py-2 text-left transition-colors hover:bg-nav-surface-hover"
                   >
                     <div className="min-w-0 flex-1">
                       <div className="truncate text-[15px] font-semibold leading-5 text-foreground">
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index fc5d5f8b5c..776bad5244 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -187,12 +187,16 @@ function NumericValueInput({
     }
   };
 
+  const displayed = focused ? draft : (displayValue ?? String(value));
+
   return (
     <input
       type="text"
       inputMode="decimal"
       size={sizeAttr}
-      value={focused ? draft : (displayValue ?? String(value))}
+      /* Fixed 4ch pill; grows only when a longer value would clip. */
+      style={{ width: `calc(${Math.max(displayed.length, 4)}ch + 18px)` }}
+      value={displayed}
       aria-label={ariaLabel}
       onFocus={(e) => {
         cancelBlurCommitRef.current = false;
@@ -263,7 +267,7 @@ function ParamSlider({
           onChange={onChange}
           displayValue={displayValue}
           ariaLabel={label}
-          size={valueSize ?? 6}
+          size={valueSize ?? 4}
         />
       </div>
       <Slider
@@ -837,7 +841,7 @@ export function ChatSettingsPanel({
                         animateRadius={false}
                         icon={ArrowDown01Icon}
                         iconClassName="size-3.5"
-                        className="grid h-7 w-[60px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.07] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
+                        className="grid h-7 w-[60px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
                       >
                         <SelectValue />
                       </SelectTrigger>
@@ -877,7 +881,7 @@ export function ChatSettingsPanel({
                         animateRadius={false}
                         icon={ArrowDown01Icon}
                         iconClassName="size-3.5"
-                        className="grid h-7 w-[120px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.07] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
+                        className="grid h-7 w-[120px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
                         data-test-id="speculative-type-select"
                       >
                         <SelectValue />
@@ -928,7 +932,7 @@ export function ChatSettingsPanel({
                       }}
                       data-test-id="spec-draft-n-max-input"
                       aria-label="Speculative decoding draft tokens"
-                      className="h-7 w-[72px] rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.07] px-2 py-0 text-[13px] font-medium text-nav-fg outline-none focus-visible:ring-0"
+                      className="h-7 w-[72px] rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px] font-medium text-nav-fg outline-none focus-visible:ring-0"
                     />
                   </div>
                 )}
@@ -1058,7 +1062,7 @@ export function ChatSettingsPanel({
               </DropdownMenuTrigger>
               <DropdownMenuContent
                 align="start"
-                sideOffset={6}
+                sideOffset={0}
                 className="menu-soft-surface ring-0 border-0 rounded-lg p-1.5"
               >
                 {presets.map((p, index) => (
@@ -1092,7 +1096,7 @@ export function ChatSettingsPanel({
                 variant={presetSaveState.isSaveReady ? "default" : "outline"}
                 size="sm"
                 className={cn(
-                  "h-9 w-full rounded-[10px] text-[13px] font-medium tracking-nav",
+                  "h-9 w-full rounded-full text-[13px] font-medium tracking-nav",
                   presetSaveState.isSaveReady &&
                     "bg-primary text-primary-foreground hover:bg-primary/90",
                 )}
@@ -1107,7 +1111,7 @@ export function ChatSettingsPanel({
                 disabled={!(settingsHydrated && activeCustomPreset)}
                 variant="outline"
                 size="sm"
-                className="h-9 w-full rounded-[10px] text-[13px] font-medium tracking-nav text-muted-foreground"
+                className="h-9 w-full rounded-full text-[13px] font-medium tracking-nav text-muted-foreground"
                 title={
                   activeCustomPreset
                     ? activeBuiltinPreset
diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index 3d867b07f7..7a987851aa 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -64,7 +64,7 @@ export function ChatSearchDialog() {
     <CommandDialog
       open={isOpen}
       onOpenChange={setOpen}
-      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 sm:max-w-[635px]"
+      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 ring-0 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:shadow-none sm:max-w-[635px]"
       overlayClassName="bg-transparent"
     >
       <Command className="rounded-4xl p-0" filter={chatSearchFilter}>
@@ -117,7 +117,7 @@ export function ChatSearchDialog() {
                   });
                   close();
                 }}
-                className="relative flex cursor-pointer select-none items-center gap-3 rounded-lg px-3 py-2.5 text-sm outline-hidden data-selected:bg-muted data-selected:text-foreground"
+                className="relative flex cursor-pointer select-none items-center gap-3 rounded-full px-3 py-2.5 text-sm outline-hidden data-selected:bg-muted data-selected:text-foreground"
               >
                 <HugeiconsIcon
                   icon={Message01Icon}
diff --git a/studio/frontend/src/features/chat/components/project-switcher.tsx b/studio/frontend/src/features/chat/components/project-switcher.tsx
index 3deaf4701d..08e252a2c2 100644
--- a/studio/frontend/src/features/chat/components/project-switcher.tsx
+++ b/studio/frontend/src/features/chat/components/project-switcher.tsx
@@ -71,7 +71,7 @@ export function ProjectSwitcher({
       <DropdownMenuContent
         side="bottom"
         align="start"
-        sideOffset={6}
+        sideOffset={0}
         className="app-user-menu menu-soft-surface ring-0 min-w-56 max-w-72 max-h-72 py-2 font-heading rounded-[14px] border-0"
       >
         {showLoadingRow ? (
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index 348c744b2c..ae6c97528e 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -260,7 +260,7 @@ export function McpComposerButton({
           <DropdownMenuContent
             side={side}
             align="start"
-            sideOffset={2}
+            sideOffset={0}
             avoidCollisions={true}
             className="unsloth-plus-menu mcp-menu w-[232px]"
           >
diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsx
index c4cd911fdb..a9496858c0 100644
--- a/studio/frontend/src/features/chat/projects-page.tsx
+++ b/studio/frontend/src/features/chat/projects-page.tsx
@@ -258,7 +258,7 @@ export function ProjectsPage() {
               value={sortMode}
               onValueChange={(v) => setSortMode(v as SortMode)}
             >
-              <SelectTrigger className="h-9 w-[130px]">
+              <SelectTrigger className="h-9 w-[130px] rounded-full border-none bg-muted shadow-none dark:bg-card">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
@@ -324,15 +324,15 @@ export function ProjectsPage() {
         </div>
       </div>
 
-      <div className="relative mt-6">
-        <span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground">
+      <div className="relative mx-auto mt-10 w-full max-w-[720px]">
+        <span className="pointer-events-none absolute left-5 top-1/2 -translate-y-1/2 text-muted-foreground">
           <HugeiconsIcon icon={Search01Icon} strokeWidth={1.75} className="size-icon" />
         </span>
         <Input
           value={query}
           onChange={(e) => setQuery(e.target.value)}
           placeholder="Search projects..."
-          className="h-11 pl-10"
+          className="h-14 rounded-full border-none bg-background pl-13 pr-5 shadow-[0_0_20px_0_rgba(0,0,0,0.07)] dark:bg-card dark:shadow-none"
           aria-label="Search projects"
         />
       </div>
@@ -342,7 +342,7 @@ export function ProjectsPage() {
           {Array.from({ length: 6 }).map((_, index) => (
             <div
               key={index}
-              className="min-h-[160px] rounded-[14px] border border-border/70 bg-card p-5"
+              className="min-h-[160px] rounded-[14px] bg-card p-5 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:shadow-none"
             >
               <Skeleton className="h-5 w-2/3 rounded-[6px]" />
               <Skeleton className="mt-3 h-4 w-full rounded-[6px]" />
@@ -361,7 +361,7 @@ export function ProjectsPage() {
           {projects.length === 0 && (
             <Button
               variant="outline"
-              className="mt-2"
+              className="mt-2 border-none bg-background shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:bg-card dark:shadow-none"
               onClick={() => {
                 setNameDraft("");
                 setCreating(true);
@@ -402,7 +402,7 @@ export function ProjectsPage() {
                   openProject(project.id);
                 }
               }}
-              className="group/project-card relative flex min-h-[160px] cursor-pointer flex-col rounded-[14px] border border-border/70 bg-card p-5 text-left transition-colors hover:border-border hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              className="group/project-card relative flex min-h-[160px] cursor-pointer flex-col rounded-[14px] bg-card p-5 text-left shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] transition-colors hover:bg-accent/40 dark:shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             >
               <div className="flex items-start justify-between gap-2">
                 <h2 className="truncate pr-2 text-[16px] font-semibold text-foreground">
@@ -422,7 +422,7 @@ export function ProjectsPage() {
                   <DropdownMenuContent
                     side="bottom"
                     align="end"
-                    sideOffset={4}
+                    sideOffset={0}
                     onClick={(e) => e.stopPropagation()}
                     onKeyDown={(e) => e.stopPropagation()}
                     className="app-user-menu menu-soft-surface menu-flat-destructive ring-0 w-44 py-2 font-heading rounded-[14px] border-0"
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index 6919d5e7a5..f68ec6cc73 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -1270,7 +1270,7 @@ export function SharedComposer({
             <DropdownMenuContent
               side="top"
               align="start"
-              sideOffset={2}
+              sideOffset={0}
               avoidCollisions={true}
               className="unsloth-plus-menu w-[212px]"
               onCloseAutoFocus={(event) => event.preventDefault()}
diff --git a/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx b/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx
index 79566f21bf..5fee63d12d 100644
--- a/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx
+++ b/studio/frontend/src/features/data-recipes/pages/data-recipes-page.tsx
@@ -75,7 +75,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Easy",
     learningBadges: ["Seed Dataset", "LLM Text", "Prompting"],
     surfaceClassName:
-      "from-emerald-500/15 via-green-500/5 to-transparent dark:from-emerald-400/30 dark:via-green-400/14 dark:to-emerald-950/16",
+      "from-emerald-500/15 via-green-500/5 to-transparent dark:from-emerald-400/20 dark:via-green-400/10 dark:to-emerald-950/16",
     shineColor: [
       "rgb(16 185 129 / 0.45)",
       "rgb(34 197 94 / 0.4)",
@@ -91,7 +91,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Easy",
     learningBadges: ["Unstructured", "LLM Text"],
     surfaceClassName:
-      "from-violet-500/15 via-fuchsia-500/5 to-transparent dark:from-violet-400/30 dark:via-fuchsia-400/14 dark:to-violet-950/16",
+      "from-violet-500/15 via-fuchsia-500/5 to-transparent dark:from-violet-400/20 dark:via-fuchsia-400/10 dark:to-violet-950/16",
     shineColor: [
       "rgb(139 92 246 / 0.45)",
       "rgb(217 70 239 / 0.4)",
@@ -107,7 +107,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Starter",
     learningBadges: ["Vision", "LLM Text", "Image Context"],
     surfaceClassName:
-      "from-lime-500/15 via-emerald-500/5 to-transparent dark:from-lime-400/30 dark:via-emerald-400/14 dark:to-lime-950/16",
+      "from-lime-500/15 via-emerald-500/5 to-transparent dark:from-lime-400/20 dark:via-emerald-400/10 dark:to-lime-950/16",
     shineColor: [
       "rgb(132 204 22 / 0.45)",
       "rgb(16 185 129 / 0.4)",
@@ -123,7 +123,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Intermediate",
     learningBadges: ["LLM Judge", "LLM Code", "Subcategory", "Category"],
     surfaceClassName:
-      "from-amber-500/15 via-orange-500/5 to-transparent dark:from-amber-400/30 dark:via-orange-400/14 dark:to-amber-950/16",
+      "from-amber-500/15 via-orange-500/5 to-transparent dark:from-amber-400/20 dark:via-orange-400/10 dark:to-amber-950/16",
     shineColor: [
       "rgb(245 158 11 / 0.45)",
       "rgb(249 115 22 / 0.4)",
@@ -139,7 +139,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Intermediate",
     learningBadges: ["LLM Code", "Prompting", "Drop Columns"],
     surfaceClassName:
-      "from-blue-500/15 via-indigo-500/5 to-transparent dark:from-blue-400/30 dark:via-indigo-400/14 dark:to-blue-950/16",
+      "from-blue-500/15 via-indigo-500/5 to-transparent dark:from-blue-400/20 dark:via-indigo-400/10 dark:to-blue-950/16",
     shineColor: [
       "rgb(59 130 246 / 0.45)",
       "rgb(99 102 241 / 0.4)",
@@ -155,7 +155,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Advanced",
     learningBadges: ["Structured LLM", "Expression", "Jinja"],
     surfaceClassName:
-      "from-cyan-500/15 via-sky-500/5 to-transparent dark:from-cyan-400/30 dark:via-sky-400/14 dark:to-cyan-950/16",
+      "from-cyan-500/15 via-sky-500/5 to-transparent dark:from-cyan-400/20 dark:via-sky-400/10 dark:to-cyan-950/16",
     shineColor: [
       "rgb(6 182 212 / 0.45)",
       "rgb(56 189 248 / 0.4)",
@@ -171,7 +171,7 @@ const TEMPLATE_CARDS: TemplateCard[] = [
     difficulty: "Intermediate",
     learningBadges: ["GitHub", "LLM Text", "Structured LLM"],
     surfaceClassName:
-      "from-slate-500/15 via-zinc-500/5 to-transparent dark:from-slate-400/30 dark:via-zinc-400/14 dark:to-slate-950/16",
+      "from-slate-500/15 via-zinc-500/5 to-transparent dark:from-slate-400/20 dark:via-zinc-400/10 dark:to-slate-950/16",
     shineColor: [
       "rgb(71 85 105 / 0.45)",
       "rgb(100 116 139 / 0.4)",
@@ -241,7 +241,7 @@ function LearningRecipeCards({
             type="button"
             disabled={isDisabled}
             onClick={() => onSelect(template)}
-            className={`group shadow-border relative overflow-hidden rounded-2xl bg-gradient-to-br text-left transition-transform ${template.surfaceClassName} enabled:cursor-pointer enabled:hover:-translate-y-0.5 enabled:hover:shadow-md disabled:cursor-not-allowed disabled:opacity-70`}
+            className={`group shadow-border relative overflow-hidden rounded-2xl bg-gradient-to-br dark:bg-white/[0.05] text-left transition-transform ${template.surfaceClassName} enabled:cursor-pointer enabled:hover:-translate-y-0.5 disabled:cursor-not-allowed disabled:opacity-70`}
           >
             <ShineBorder
               borderWidth={1.2}
@@ -267,7 +267,7 @@ function LearningRecipeCards({
                 <p className="line-clamp-2 text-sm font-semibold leading-tight text-foreground">
                   {template.title}
                 </p>
-                <p className="line-clamp-2 text-xs text-muted-foreground">
+                <p className="line-clamp-2 text-xs text-muted-foreground dark:text-zinc-300">
                   {template.description}
                 </p>
               </div>
@@ -280,7 +280,7 @@ function LearningRecipeCards({
                       <Badge
                         key={`${template.title}-${badge}`}
                         variant="outline"
-                        className="h-5 shrink-0 px-1.5 text-[10px]"
+                        className="h-5 shrink-0 px-1.5 text-[10px] dark:text-zinc-300"
                       >
                         {badge}
                       </Badge>
@@ -288,7 +288,7 @@ function LearningRecipeCards({
                     {extraLearningBadgeCount > 0 ? (
                       <Badge
                         variant="outline"
-                        className="h-5 shrink-0 px-1.5 text-[10px]"
+                        className="h-5 shrink-0 px-1.5 text-[10px] dark:text-zinc-300"
                       >
                         +{extraLearningBadgeCount}
                       </Badge>
@@ -296,7 +296,7 @@ function LearningRecipeCards({
                     {isReady ? null : (
                       <Badge
                         variant="secondary"
-                        className="h-5 shrink-0 px-1.5 text-[10px]"
+                        className="h-5 shrink-0 px-1.5 text-[10px] dark:text-zinc-300"
                       >
                         Soon
                       </Badge>
@@ -449,7 +449,7 @@ export function DataRecipesPage(): ReactElement {
             </p>
           </div>
         ) : recipes.length === 0 ? (
-          <Empty className="mt-8 border border-dashed border-border/70">
+          <Empty className="mt-8 border border-dashed border-border/70 dark:border-none">
             <EmptyHeader>
               <EmptyMedia variant="icon">
                 <HugeiconsIcon icon={CookBookIcon} className="size-5" />
diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsx
index b1a379b582..aa18be37f7 100644
--- a/studio/frontend/src/features/export/export-page.tsx
+++ b/studio/frontend/src/features/export/export-page.tsx
@@ -539,7 +539,7 @@ export function ExportPage() {
           description="Select source, method, and quantization"
           accent="emerald"
           featured={true}
-          className="shadow-border ring-1 ring-border"
+          className="ring-0 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:shadow-none"
         >
           {/* Loading / error states */}
           {loadingCheckpoints && (
diff --git a/studio/frontend/src/features/hub/catalog/catalog-states.tsx b/studio/frontend/src/features/hub/catalog/catalog-states.tsx
index e4c8554773..1df85a6f81 100644
--- a/studio/frontend/src/features/hub/catalog/catalog-states.tsx
+++ b/studio/frontend/src/features/hub/catalog/catalog-states.tsx
@@ -58,7 +58,7 @@ export function NetworkErrorState({
         <button
           type="button"
           onClick={onRetry}
-          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.05]"
+          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.1]"
         >
           <HugeiconsIcon
             icon={RefreshIcon}
@@ -113,7 +113,7 @@ export function DiscoverFetchMoreState({
           type="button"
           onClick={onFetchMore}
           disabled={isLoadingMore}
-          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] disabled:cursor-not-allowed disabled:opacity-50 dark:hover:bg-white/[0.05]"
+          className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] disabled:cursor-not-allowed disabled:opacity-50 dark:hover:bg-white/[0.1]"
         >
           <HugeiconsIcon
             icon={RefreshIcon}
@@ -191,7 +191,7 @@ export function InventoryErrorState({
       <button
         type="button"
         onClick={onRetry}
-        className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.05]"
+        className="inline-flex h-8 items-center gap-1.5 rounded-[10px] bg-transparent px-3 text-[12px] font-medium text-foreground transition-colors hover:bg-foreground/[0.04] dark:hover:bg-white/[0.1]"
       >
         <HugeiconsIcon icon={RefreshIcon} strokeWidth={1.75} className="size-3.5" />
         Try again
diff --git a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
index c9be7b549b..72743af722 100644
--- a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
@@ -666,7 +666,7 @@ export function GgufDownloadCard({
                 e.preventDefault();
                 setOpen((o) => !o);
               }}
-              className="hub-menu-trigger flex h-9 min-w-0 flex-1 cursor-pointer items-center gap-2.5 rounded-[12px] px-3 text-left transition-colors hover:bg-foreground/[0.04] data-[state=open]:bg-foreground/[0.06] dark:hover:bg-white/[0.04] dark:data-[state=open]:bg-white/[0.06]"
+              className="hub-menu-trigger flex h-9 min-w-0 flex-1 cursor-pointer items-center gap-2.5 rounded-[12px] px-3 text-left transition-colors hover:bg-foreground/[0.04] data-[state=open]:bg-foreground/[0.06] dark:hover:bg-white/[0.1] dark:data-[state=open]:bg-white/[0.06]"
             >
               {selected ? (
                 <QuantBadge
@@ -723,7 +723,7 @@ export function GgufDownloadCard({
           <PopoverContent
             align="start"
             side="bottom"
-            sideOffset={8}
+            sideOffset={0}
             avoidCollisions={false}
             className="hub-menu-instant menu-soft-surface w-[var(--radix-popover-trigger-width)] min-w-[200px] gap-0 overflow-hidden p-0 py-2 ring-0"
           >
diff --git a/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx b/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
index 76539d43de..a6596a3d54 100644
--- a/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
+++ b/studio/frontend/src/features/hub/catalog/hub-option-menu.tsx
@@ -181,7 +181,7 @@ export function HubOptionMenu<T extends string>({
       <PopoverContent
         align={align}
         side="bottom"
-        sideOffset={8}
+        sideOffset={0}
         collisionPadding={12}
         onCloseAutoFocus={(event) => event.preventDefault()}
         className={cn(
diff --git a/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
index c5e754d982..9b3d401b99 100644
--- a/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
@@ -352,7 +352,7 @@ export function LocalOnDeviceCard({
                   <PopoverContent
                     align="start"
                     side="bottom"
-                    sideOffset={8}
+                    sideOffset={0}
                     avoidCollisions={false}
                     className="hub-menu-instant menu-soft-surface w-[var(--radix-popover-trigger-width)] min-w-[220px] gap-0 overflow-hidden p-0 py-2 ring-0"
                   >
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
index e01cd6b5cc..9833513c97 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
@@ -139,7 +139,7 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
               }
               className={cn(
                 "inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-[7px] text-muted-foreground transition-colors",
-                "hover:bg-foreground/[0.06] hover:text-foreground disabled:cursor-default disabled:opacity-50 dark:hover:bg-white/[0.06]",
+                "hover:bg-foreground/[0.06] hover:text-foreground disabled:cursor-default disabled:opacity-50 dark:hover:bg-white/[0.1]",
               )}
             >
               <HugeiconsIcon
@@ -234,7 +234,7 @@ export function DownloadManagerPanel() {
               type="button"
               aria-label="Collapse downloads"
               onClick={() => setCollapsed(true)}
-              className="inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-[7px] text-muted-foreground transition-colors hover:bg-foreground/[0.06] hover:text-foreground dark:hover:bg-white/[0.06]"
+              className="inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-[7px] text-muted-foreground transition-colors hover:bg-foreground/[0.06] hover:text-foreground dark:hover:bg-white/[0.1]"
             >
               <HugeiconsIcon
                 icon={ArrowDown01Icon}
diff --git a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
index 3b9b60e5dd..050595f636 100644
--- a/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
+++ b/studio/frontend/src/features/profile/components/profile-personalization-panel.tsx
@@ -118,7 +118,7 @@ export function ProfilePersonalizationPanel() {
         <button
           type="button"
           onClick={() => fileInputRef.current?.click()}
-          className="absolute right-0 bottom-0 -translate-x-[15.625%] -translate-y-[15.625%] flex size-8 items-center justify-center rounded-full border border-border bg-background text-foreground shadow-[0_2px_8px_-2px_rgba(27,27,31,0.16)] transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+          className="absolute right-0 bottom-0 -translate-x-[15.625%] -translate-y-[15.625%] flex size-8 items-center justify-center rounded-full border border-border bg-background text-foreground shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
           aria-label={t("settings.profile.changePicture")}
         >
           <HugeiconsIcon icon={Camera01Icon} className="size-3.5" strokeWidth={2} />
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
index 9b91bfe334..c333fd84f8 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/models/local-recipe-model-selector.tsx
@@ -591,7 +591,7 @@ export function LocalRecipeModelSelector({
       </PopoverTrigger>
       <PopoverContent
         align="start"
-        sideOffset={6}
+        sideOffset={0}
         className="menu-soft-surface nodrag nowheel gap-0 overflow-hidden p-0"
         style={{
           width:
diff --git a/studio/frontend/src/features/settings/settings-dialog.tsx b/studio/frontend/src/features/settings/settings-dialog.tsx
index 26efcde7ea..0d10ff722a 100644
--- a/studio/frontend/src/features/settings/settings-dialog.tsx
+++ b/studio/frontend/src/features/settings/settings-dialog.tsx
@@ -155,18 +155,18 @@ export function SettingsDialog() {
                     type="button"
                     onClick={() => setActiveTab(tab.id)}
                     className={cn(
-                      "relative flex h-[32px] items-center gap-2.5 rounded-[11px] pl-3 pr-2.5 text-[14.5px] leading-[19px] tracking-nav font-medium transition-colors",
+                      "relative flex h-[32px] items-center gap-2.5 rounded-full pl-3 pr-2.5 text-[14.5px] leading-[19px] tracking-nav font-medium transition-colors",
                       "max-sm:shrink-0",
                       "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                       active
                         ? "text-black dark:text-white"
-                        : "text-[#383835] dark:text-[#c7c7c4] hover:bg-[#ececec] dark:hover:bg-[#2d2f33] hover:text-black dark:hover:text-white",
+                        : "text-[#383835] dark:text-[#c7c7c4] hover:bg-[#ececec] dark:hover:bg-[#3a3d43] hover:text-black dark:hover:text-white",
                     )}
                   >
                     {active && (
                       <motion.span
                         layoutId="settings-active-pill"
-                        className="absolute inset-0 rounded-[11px] bg-[#ececec] dark:bg-[#2d2f33]"
+                        className="absolute inset-0 rounded-full bg-[#ececec] dark:bg-[#3a3d43]"
                         transition={
                           reduced
                             ? { duration: 0 }
@@ -202,7 +202,7 @@ export function SettingsDialog() {
             <button
               type="button"
               onClick={closeDialog}
-              className="absolute top-3 right-3 z-10 flex size-7 items-center justify-center rounded-full text-[#383835] dark:text-[#c7c7c4] transition-colors hover:bg-[#ececec] dark:hover:bg-[#2d2f33] hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              className="absolute top-3 right-3 z-10 flex size-7 items-center justify-center rounded-full text-[#383835] dark:text-[#c7c7c4] transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d43] hover:text-black dark:hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               aria-label={t("settings.dialog.closeAriaLabel")}
             >
               <HugeiconsIcon icon={Cancel01Icon} className="size-4" />
diff --git a/studio/frontend/src/features/tour/components/guided-tour.tsx b/studio/frontend/src/features/tour/components/guided-tour.tsx
index c13e2fefcc..a7b29fb925 100644
--- a/studio/frontend/src/features/tour/components/guided-tour.tsx
+++ b/studio/frontend/src/features/tour/components/guided-tour.tsx
@@ -332,7 +332,7 @@ export function GuidedTour({
                       <Button
                         variant="ghost"
                         size="icon-sm"
-                        className="text-foreground/60 hover:text-foreground hover:bg-black/[0.05] dark:text-zinc-300/70 dark:hover:text-zinc-100 dark:hover:bg-white/[0.08]"
+                        className="text-foreground/60 hover:text-foreground hover:bg-black/[0.05] dark:text-zinc-300/70 dark:hover:text-zinc-100 dark:hover:bg-white/[0.1]"
                         onClick={() => requestClose("skip")}
                         aria-label="Skip tour"
                       >
@@ -343,7 +343,7 @@ export function GuidedTour({
                     <div className="mt-5 flex items-center justify-between gap-3">
                       <Button
                         variant="ghost"
-                        className="text-foreground/60 hover:text-foreground hover:bg-black/[0.05] dark:text-zinc-300/70 dark:hover:text-zinc-100 dark:hover:bg-white/[0.08]"
+                        className="text-foreground/60 hover:text-foreground hover:bg-black/[0.05] dark:text-zinc-300/70 dark:hover:text-zinc-100 dark:hover:bg-white/[0.1]"
                         onClick={() => requestClose("skip")}
                       >
                         Skip
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 07bef147d7..76721eaa63 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -113,7 +113,8 @@
 	--ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
 	--ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
 
-	--background: oklch(1 0 0);
+	/* Slightly warm off white; every page (and the chat surface) shares it. */
+	--background: #fefefd;
 	--foreground: oklch(0.2686 0 0);
 	--card: oklch(1 0 0);
 	--card-foreground: oklch(0.1281 0.0179 169.2764);
@@ -137,9 +138,9 @@
 	--chart-4: oklch(0.6926 0.1112 346.5775);
 	--chart-5: oklch(0.7497 0.1003 85.0057);
 	--radius: 1.1rem;
-	/* Match the page background so the sidebar reads as one surface with the
-	   content; the faint --sidebar-border on its right edge is the separator. */
-	--sidebar: oklch(1 0 0);
+	/* White sidebar against the warm off-white page; the tone difference is
+	   the separator now that the right-edge divider is gone. */
+	--sidebar: #ffffff;
 	--sidebar-foreground: oklch(0.1281 0.0179 169.2764);
 	--sidebar-primary: #17b88b;
 	--sidebar-primary-foreground: oklch(1 0 0);
@@ -233,7 +234,8 @@
 	/* Exact palette from apps/studio/index_chat.html mockup. Using hex so the
 	   rendered surface matches the mockup pixel-for-pixel — OKLCH conversion
 	   drifted ~3% darker and shifted the neutral hue. */
-	--background: #1f2023;
+	/* Slightly darker than --sidebar so the sidebar reads as its own surface. */
+	--background: #1a1b1e;
 	--foreground: #ececee;
 	--card: #2d2e32;
 	--card-foreground: #ececee;
@@ -245,7 +247,8 @@
 	--secondary-foreground: #ececee;
 	--muted: #2e3035;
 	--muted-foreground: #999999;
-	--accent: #2e3035;
+	/* One step lighter than --popover so menu item hover reads clearly. */
+	--accent: #3a3d43;
 	--accent-foreground: #ececee;
 	--destructive: oklch(0.6368 0.2078 25.3313);
 	/* --border / --input one step lighter than --muted so outlines and form
@@ -259,14 +262,14 @@
 	--chart-3: oklch(0.7554 0.1285 197.339);
 	--chart-4: oklch(0.7503 0.1199 346.7805);
 	--chart-5: oklch(0.799 0.1196 84.6633);
-	/* Match the page background (dark); --sidebar-border is the right-edge separator. */
+	/* A step lighter than --background; the tone difference is the separator. */
 	--sidebar: #1f2023;
 	--sidebar-foreground: #ececee;
 	--sidebar-primary: #17b88b;
 	--sidebar-primary-foreground: oklch(1 0 0);
-	--sidebar-accent: #2f2f31;
+	--sidebar-accent: #2e3035;
 	--sidebar-accent-foreground: #ececee;
-	--sidebar-border: #2d2d2f;
+	--sidebar-border: #2d2e32;
 	--sidebar-ring: #17b88b;
 	--destructive-foreground: oklch(1 0 0);
 	/* Match light's radius so every rounded-* element is the same in both themes. */
@@ -293,7 +296,7 @@
 
 	--nav-fg: #c7c7c4;
 	--nav-fg-muted: #96979b;
-	--nav-surface-hover: #2e2e30;
+	--nav-surface-hover: #2e3035;
 	--nav-icon-idle: #5c5c5c;
 	--nav-beta-border: #3a3c3f;
 	--panel-surface-hover: #3a3c42;
@@ -305,7 +308,7 @@
 	--panel-surface: var(--background);
 	--panel-surface-fg: var(--foreground);
 	--panel-input-surface: #2a2b2e;
-	--panel-input-surface-hover: #2e3033;
+	--panel-input-surface-hover: #34373c;
 	/* Soft neutral gray for muted text and sliders. Pure-ish #ababab
 	   reads as quiet on the dark panel without going colored. */
 	--panel-surface-fg-muted: #ababab;
@@ -618,7 +621,7 @@
 	   prompt button, and the chat-template textarea so all three read
 	   as one quiet gray family, matching the focused-edit-number tint. */
 	.panel-input-group {
-		@apply !h-9 min-h-9 min-w-0 items-stretch gap-0 rounded-[10px] pr-0 transition-colors focus-within:ring-0 focus-within:shadow-none;
+		@apply !h-9 min-h-9 min-w-0 items-stretch gap-0 rounded-[14px] pr-0 transition-colors focus-within:ring-0 focus-within:shadow-none;
 		border: 0 !important;
 		background-color: var(--panel-input-surface);
 	}
@@ -714,13 +717,12 @@
 	/* Inline numeric input — used for slider values and Context Length.
 	   Designed to read as *editable text* rather than a pill button so
 	   it doesn't mirror the Select/dropdown components on the panel.
-	   Default: transparent box, no border, no ring, sized by the
-	   `size` HTML attribute (each consumer picks 6 / 8 / etc. chars).
-	   Hover/focus: very light bg fade-in to signal editability — just
-	   enough to read as interactive, not enough to compete with the
-	   slider row's quiet aesthetic. */
+	   Default: transparent box, no border, no ring; the component sets
+	   an inline width that hugs the value. Hover/focus: very light bg
+	   fade-in, just enough to read as interactive without competing
+	   with the slider row's quiet aesthetic. */
 	.panel-number-input {
-		@apply h-7 rounded-md border-0 bg-transparent px-1.5 text-right text-[13px]! font-medium tabular-nums text-nav-fg shadow-none transition-colors hover:bg-black/[0.04] focus:bg-black/[0.05] focus-visible:ring-0! focus-visible:outline-none md:text-[13px]!;
+		@apply h-7 min-w-8 shrink-0 rounded-full border-0 bg-transparent px-2 text-right text-[13px]! font-medium tabular-nums text-nav-fg shadow-none transition-colors hover:bg-black/[0.04] focus:bg-black/[0.05] focus-visible:ring-0! focus-visible:outline-none md:text-[13px]!;
 	}
 	.dark .panel-number-input {
 		@apply hover:bg-white/[0.04] focus:bg-white/[0.06];
@@ -779,7 +781,7 @@
 		height: 36px;
 		padding: 0 0.75rem !important;
 		gap: 9.5px !important;
-		border-radius: 12px;
+		border-radius: 9999px;
 		font-weight: 500;
 		font-size: 15px;
 		line-height: 20px;
@@ -805,6 +807,9 @@
 	.dark .app-user-menu [data-slot="dropdown-menu-item"]:focus,
 	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"]:focus,
 	.dark .app-user-menu [data-slot="dropdown-menu-sub-trigger"][data-state="open"] {
+		/* --nav-surface-hover is tuned for the page bg; on the lighter menu
+		   surface it is invisible, so use the menu hover token instead. */
+		background-color: var(--accent);
 		color: #fff;
 	}
 	.app-user-menu [data-slot="dropdown-menu-item"]:focus *,
@@ -837,14 +842,15 @@
 
 	/* Elevated surface shadow (use ring-* for borders) */
 	.shadow-border {
-		--tw-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
-		--tw-shadow-colored: 0 4px 16px var(--tw-shadow-color);
+		/* Chatbox shadow; dark mode drops it. */
+		--tw-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
+		--tw-shadow-colored: 0 2px 8px -2px var(--tw-shadow-color);
 		box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000),
 			var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow);
 	}
 
 	.dark .shadow-border {
-		--tw-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
+		box-shadow: none;
 	}
 
 	/* Settings dialog: no shadow in dark mode. */
@@ -852,6 +858,12 @@
 		box-shadow: none;
 	}
 
+	/* Lift the dialog off the page bg; halfway to --card keeps the inner
+	   bg-muted / bg-background fills readable. */
+	.dark .settings-surface {
+		background-color: color-mix(in srgb, var(--background) 50%, var(--card));
+	}
+
 	/* App-wide: every clickable control shows the hand cursor. Disabled ones
 	   (native :disabled, aria-disabled, Radix data-disabled) keep the default. */
 	button:not(:disabled):not([aria-disabled="true"]),
@@ -893,7 +905,7 @@
 		   both themes; rounded-4xl here and on the inner Command follow this. */
 		--radius: 0.625rem;
 		/* Match the chat box: soft elevation in light, none in dark. */
-		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 
 	.dark .chat-search-surface {
@@ -902,25 +914,29 @@
 
 	.menu-soft-surface,
 	.menu-soft-surface-up {
+		/* Light: chatbox shadow geometry. */
 		--menu-soft-edge: rgba(0, 0, 0, 0.14);
-		--menu-soft-shadow: rgba(0, 0, 0, 0.18);
-		--menu-soft-offset-y: 8px;
-		--menu-soft-blur: 28px;
-		--menu-soft-spread: -6px;
+		--menu-soft-shadow: rgba(0, 0, 0, 0.16);
+		--menu-soft-offset-y: 2px;
+		--menu-soft-blur: 8px;
+		--menu-soft-spread: -2px;
 		@apply bg-popover text-popover-foreground;
 		box-shadow:
 			inset 0 0 0 1px var(--menu-soft-edge),
 			0 var(--menu-soft-offset-y) var(--menu-soft-blur)
 				var(--menu-soft-spread) var(--menu-soft-shadow);
 	}
-	.menu-soft-surface-up {
-		--menu-soft-offset-y: -6px;
-		--menu-soft-spread: -8px;
-	}
 	.dark .menu-soft-surface,
 	.dark .menu-soft-surface-up {
 		--menu-soft-edge: rgba(255, 255, 255, 0.07);
 		--menu-soft-shadow: rgba(0, 0, 0, 0.28);
+		--menu-soft-offset-y: 8px;
+		--menu-soft-blur: 28px;
+		--menu-soft-spread: -6px;
+	}
+	.dark .menu-soft-surface-up {
+		--menu-soft-offset-y: -6px;
+		--menu-soft-spread: -8px;
 	}
 
 	/* Model selector: drop the inset edge ring, keep the soft drop shadow.
@@ -935,6 +951,15 @@
 		box-shadow: none;
 	}
 
+	/* List menus: one radius in both themes, slightly tighter than --radius-lg
+	   and matching the sidebar buttons. !important beats per-menu rounded-*. */
+	[data-slot="dropdown-menu-content"],
+	[data-slot="dropdown-menu-sub-content"],
+	[data-slot="select-content"],
+	[data-slot="combobox-content"] {
+		border-radius: 14px !important;
+	}
+
 	/* Every dropdown/menu/select/popover: borderless, chatbox shadow in light,
 	   none in dark. !important so it also overrides the bespoke menu shadows. */
 	[data-slot="dropdown-menu-content"],
@@ -942,7 +967,7 @@
 	[data-slot="select-content"],
 	[data-slot="combobox-content"],
 	[data-slot="popover-content"] {
-		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16) !important;
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16) !important;
 	}
 	/* Dark: keep the chat-box dropdown shadow so menus don't merge into a
 	   same-color surface (e.g. a menu overlapping the composer). */
@@ -954,6 +979,15 @@
 		box-shadow: 0 4px 14px var(--background) !important;
 	}
 
+	/* Model selector: shadow in the page-bg color so it lifts off the
+	   composer it overlaps (chatbox geometry). Account menu stays flat. */
+	.dark .unsloth-model-selector-menu {
+		box-shadow: 0 2px 8px -2px var(--background) !important;
+	}
+	.dark .app-user-menu.menu-soft-surface-up {
+		box-shadow: none !important;
+	}
+
 	/* Context menus (chat, run, project): drop the inset edge ring, keep the soft shadow. */
 	.app-user-menu.menu-soft-surface {
 		box-shadow: 0 var(--menu-soft-offset-y) var(--menu-soft-blur)
@@ -962,7 +996,7 @@
 
 	/* Account menu: drop the inset edge ring and use the composer's soft shadow. */
 	.app-user-menu.menu-soft-surface-up {
-		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 	.dark .app-user-menu.menu-soft-surface-up {
 		box-shadow: 0 8px 28px -6px rgba(0, 0, 0, 0.28);
@@ -972,16 +1006,19 @@
 		@apply relative flex w-full flex-col rounded-[32px] bg-background dark:bg-card px-1 pt-2 outline-none transition-shadow;
 		font-family: var(--font-sans);
 		background-clip: padding-box;
-		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
+		background-color: #ffffff;
+		/* Gemini-style composer shadow. */
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
+		transition: box-shadow 0.1s;
 	}
 
 	.dark .chat-composer-surface {
-		background-color: #2a2a2c;
+		background-color: var(--card);
 		box-shadow: none;
 	}
 
 	.composer-pill-btn {
-		@apply flex cursor-pointer items-center gap-1.5 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
+		@apply flex cursor-pointer items-center gap-1.5 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.1] disabled:cursor-not-allowed disabled:opacity-40;
 	}
 
 	/* Icon-only (compact) pills drop their label, so make the button a square
@@ -1058,16 +1095,18 @@
 		@apply relative flex w-full flex-col rounded-[32px] bg-background dark:bg-card px-3 py-3 outline-none transition-shadow;
 		font-family: var(--font-sans);
 		background-clip: padding-box;
-		/* Gemini search pill: soft, centered shadow, no downward offset. */
-		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+		background-color: #ffffff;
+		/* Gemini-style composer shadow. */
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
+		transition: box-shadow 0.1s;
 	}
 
 	.unsloth-composer-surface:focus-within {
-		box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.09);
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 
 	.dark .unsloth-composer-surface {
-		background-color: #2a2a2c;
+		background-color: var(--card);
 		box-shadow: none;
 	}
 
@@ -1177,7 +1216,7 @@
 	/* Right-side Thinking pill (toggle or dropdown). pl-2 matches the left
 	   pills so the hover X is not pushed in too far. */
 	.unsloth-thinking-pill {
-		@apply inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.08] disabled:cursor-not-allowed disabled:opacity-40;
+		@apply inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.1] disabled:cursor-not-allowed disabled:opacity-40;
 		/* Reserve a text line so the icon-only (inactive) pill matches the
 		   text pills' height instead of collapsing to the icon. */
 		min-height: calc(1lh + 0.75rem);
@@ -1206,9 +1245,7 @@
 		border-radius: 18px;
 		padding-top: 0.5rem;
 		padding-bottom: 0.5rem;
-		box-shadow:
-			0 1px 2px oklch(0 0 0 / 0.04),
-			0 6px 18px oklch(0 0 0 / 0.08);
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 
 	/* MCP menu is wider (232px), so nudge the radius up so it reads as round as
@@ -1218,7 +1255,7 @@
 	}
 
 	.dark .unsloth-plus-menu[data-slot] {
-		background-color: #2a2a2c;
+		background-color: var(--card);
 		/* Shadow tinted to the page bg so it blends, not a dark halo. */
 		box-shadow: 0 4px 14px var(--background);
 	}
@@ -1257,7 +1294,7 @@
 			[data-slot="dropdown-menu-item"],
 			[data-slot="dropdown-menu-sub-trigger"]
 		):is(:hover, :focus, :focus-visible, [data-highlighted], [data-state="open"]) {
-		background-color: rgba(255, 255, 255, 0.08) !important;
+		background-color: rgba(255, 255, 255, 0.1) !important;
 	}
 
 	/* Hover tints only the background; the item and every descendant (text, icons,
@@ -1302,7 +1339,7 @@
 		white-space: nowrap;
 	}
 	.artifact-panel-shell {
-		box-shadow: 0 2px 8px -2px rgba(27, 27, 31, 0.16);
+		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 
 	.dark .artifact-panel-shell {
@@ -1634,7 +1671,7 @@
    !important because Sonner injects its base rules at runtime. */
 [data-sonner-toast][data-styled='true'] {
 	padding: 12px 18px !important;
-	box-shadow: 0 2px 6px rgba(0, 0, 0, 0.08) !important;
+	box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16) !important;
 }
 
 [data-sonner-toast][data-styled='true']:has([data-close-button]):not(:has([data-cancel])) {
@@ -1671,7 +1708,7 @@
 
 /* Boost shadow on dark surfaces; mirrors .shadow-border / .menu-soft-surface pattern. */
 .dark [data-sonner-toast][data-styled='true'] {
-	background-color: #2a2a2c !important;
+	background-color: var(--card) !important;
 	box-shadow: none !important;
 }
 
@@ -1923,7 +1960,7 @@
 
 /* Keep the (borderless) close button blended with the dark toast surface. */
 .dark [data-sonner-toast][data-styled="true"] [data-close-button] {
-	background: #2a2a2c !important;
+	background: var(--card) !important;
 }
 
 [data-sonner-toast][data-styled="true"] [data-close-button] svg {

From 62191c476528369b4eb4785f8ff5c4f74b18a3cb Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 04:24:49 -0700
Subject: [PATCH 136/222] Windows/WSL installer: fix winget msstore cert
 failure, amd-smi DiskPart prompt, and enable AMD GPU (Strix Halo gfx1151)
 (#5940)

* Fix Windows installer winget msstore certificate failure

`winget install` was invoked without `--source winget`, so winget also
queried the msstore source. When msstore fails certificate pinning
(error 0x8a15005e, "The server certificate did not match any of the
expected values") winget aborts and demands `--source`, so the Python
(and uv) install fails even though the package exists in the winget
source.

- Pass `--source winget` to all winget install calls (Python x2, uv).
  Both packages live in the winget source, so this is strictly correct
  and skips the failing msstore round-trip entirely.
- Add a python.org fallback (Install-PythonFromPythonOrg) that downloads
  the official installer and runs it silently per-user (no admin/UAC)
  when winget is unavailable or fails for any reason. Mirrors the
  existing uv -> astral.sh fallback so Python installs without manual
  steps. Resolves the latest 3.13.x from python.org with a pinned
  fallback, and selects the amd64/arm64/x86 installer per architecture.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Pin remaining setup.ps1 winget calls to --source winget

Two winget invocations in studio/setup.ps1 still queried all sources and
could hit the same msstore certificate-pinning failure (0x8a15005e) that
broke the Python install in install.ps1:

- `winget show Nvidia.CUDA --versions` (CUDA Toolkit version probe)
- `winget install ... ShiningLight.OpenSSL.Dev` (OpenSSL dev for llama-server)

Every other winget call in this file already passes `--source winget`
(Git, CMake, VS Build Tools, CUDA install, Node.js, and setup.ps1's own
Python 3.12 install), so these two were stragglers. Both packages live in
the winget source; pinning it makes setup robust to an unhealthy msstore
source, matching the rest of the file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Stop amd-smi GPU probe from popping a DiskPart UAC prompt

On Windows, AMD GPU detection in install.ps1 and studio/setup.ps1 runs
`amd-smi list` / `static --asic` / `version`. amd-smi (shipped in
System32 by the Adrenalin driver) auto-elevates to read GPU/APU memory
details, surfacing a confusing DiskPart UAC prompt mid-install. The
Studio backend already documents and circuit-breaks on this in
studio/backend/utils/hardware/amd.py, but the installers did not.

Add an Invoke-AmdSmiNoElevate helper (both scripts) that runs amd-smi via
Start-Process under __COMPAT_LAYER=RunAsInvoker so it cannot auto-elevate
(no prompt), with a 30s timeout (matching amd.py) so a flaky amd-smi
cannot stall the install for minutes. On failure/timeout the existing WMI
name -> gfx fallback still resolves the arch, so detection is unchanged on
working hosts.

Verified on a Strix Halo (Radeon 8060S / gfx1151) box: the prompt is gone
and the probe is bounded.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add experimental ROCm-on-WSL setup helper for Strix Halo (gfx1151)

install.sh already routes gfx1151 (Radeon 8060S / Strix Halo) to the
repo.amd.com/rocm/whl/gfx1151 wheels once a ROCm runtime is present, but
it does not install AMD's driver/ROCm stack -- a large, admin-gated
prerequisite. scripts/install_rocm_wsl_strixhalo.sh automates the Linux
side on a dedicated Ubuntu 24.04 WSL2 distro: ROCm 7.2 (wsl usecase), the
rocr4wsl HSA runtime, a librocdxg build, env setup, and a PyTorch gfx1151
GPU smoke test. A hard preflight refuses to run until the Adrenalin
>=26.3.1 driver is actually present, so it cannot half-install.

Procedure adapted from AMD's ROCm-on-WSL docs and community gfx1151 notes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Detect AMD GPUs by name so native Windows gets a GPU llama.cpp

The gfx-arch inference from the WMI GPU name was gated behind $HasROCm,
which the hipinfo/amd-smi probe leaves false on the common Windows case
(Adrenalin driver only, no HIP SDK -- and amd-smi often cannot read the
arch without elevation). So an AMD GPU was detected by name but never
mapped to a gfx target, --rocm-gfx was not forwarded, and studio setup
fell back to a CPU llama.cpp build.

Un-gate the inference (install.ps1 + studio/setup.ps1) so it runs whenever
an AMD GPU name is available. The inferred gfx is forwarded as --rocm-gfx,
which makes install_llama_prebuilt.py download the matching lemonade-sdk
ROCm prebuilt (e.g. llama-bNNNN-windows-rocm-gfx1151-x64.zip) -- a
GPU-accelerated llama.cpp that bundles its own ROCm runtime, so it runs
with just the Adrenalin driver. PyTorch's ROCm wheels still require a
confirmed HIP SDK ($HasROCm), so this only affects llama.cpp / inference
and never pulls broken ROCm torch.

Also broaden the name->arch table to every family lemonade ships Windows
assets for: gfx120X (RDNA 4), gfx110X (RDNA 3), gfx1151/gfx1150
(RDNA 3.5), and gfx103X (RDNA 2). Unknown names still fall back to CPU.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Suppress amd-smi DiskPart UAC prompt in the Python install/runtime paths

The earlier PowerShell guard covered install.ps1 / setup.ps1, but the
Python installer (install_llama_prebuilt.py detect_host,
install_python_stack.py ROCm probes) and the Studio backend monitor
(amd.py) also shell out to amd-smi on Windows, where it auto-elevates and
pops the same DiskPart UAC prompt mid-install / at runtime.

Inject __COMPAT_LAYER=RunAsInvoker into the amd-smi subprocess env on
Windows so it runs un-elevated (no prompt). Callers already tolerate an
empty/failed result and fall back to WMI / name detection (installer) or
the existing circuit breaker (amd.py). Gated to Windows so Linux/macOS
amd-smi behaviour is unchanged.

- install_llama_prebuilt.py: handled centrally in run_capture (covers
  detect_host's `amd-smi list` and the version probe).
- install_python_stack.py: new _amd_smi_env() helper on its 3 raw
  subprocess.run amd-smi calls.
- amd.py: merge RunAsInvoker into the existing child env.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Tighten AMD GPU name->arch patterns to avoid mismatches

The W9[0-9]{3} and RX 90[0-9]{2} patterns added for RDNA 4 were
speculative and over-broad: W9xxx would also match old GCN FirePro
W9100/W9000 cards (wrong gfx1201 -> a lemonade gfx120X download that
fails validation), and RX 90[0-9]{2} was redundant with the explicit
9070/9060 entries. Drop both; keep only confirmed RDNA 4 SKUs. Unmatched
AMD names still fall back cleanly to CPU.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fetch the llama.cpp validation model via huggingface_hub

The prebuilt validation downloads a tiny GGUF test model from huggingface
via bare urllib. On Windows / proxy setups where the server sends an
incomplete TLS chain, urllib cannot complete the Amazon CA chain (it does
no AIA intermediate fetching) and fails with CERTIFICATE_VERIFY_FAILED, so
a perfectly good GPU prebuilt is rejected and the installer falls back to a
CPU source build.

Route the validation-model download through huggingface_hub
(hf_hub_download) -- the same mechanism Studio uses for model downloads,
which completes the chain where urllib cannot -- keeping the direct URL as
a fallback. This lets the lemonade ROCm prebuilt validate and install on
cert-restricted machines (verified: hf_hub_download succeeds where urllib
returns CERTIFICATE_VERIFY_FAILED).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Guard the remaining raw amd-smi version probe via run_capture

A ROCm-version detector in install_llama_prebuilt.py called amd-smi version through a raw subprocess.run that bypassed run_capture's Windows RunAsInvoker guard, so it still triggered the DiskPart UAC prompt during setup. Route it through run_capture like the other amd-smi calls.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Forward --rocm-gfx even when the ROCm runtime is unconfirmed

setup.ps1 forwarded --rocm-gfx (and picked the windows-hip llama.cpp
prebuilt) only inside `if ($HasROCm)`. On Adrenalin-only hosts (amd-smi
present but no HIP SDK, so $HasROCm stays false) the gfx arch was
name-inferred but never forwarded, so install_llama_prebuilt.py saw
has_rocm=False and installed the CPU build -- even though the lemonade
gfx1151 GPU prebuilt runs fine there (it bundles its own ROCm runtime;
verified: llama-cli --list-devices -> ROCm0: AMD Radeon 8060S, 69 GB).

Forward --rocm-gfx whenever a gfx arch is known (it is authoritative and
implies ROCm in install_llama_prebuilt.py), and treat a known gfx arch as
windows-hip in the existing-install mismatch check. --has-rocm stays gated
on the confirmed-runtime signal.

Verified on Radeon 8060S / gfx1151: the installer now selects, validates,
and installs llama-b1286-windows-rocm-gfx1151-x64.zip (ROCm DLLs present)
instead of the CPU build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Install AMD ROCm PyTorch on name-inferred gfx hosts (enables Train/Export)

setup.ps1 picked the AMD ROCm PyTorch wheels only inside `if ($HasROCm ...)`.
On Adrenalin-only hosts (amd-smi present but no HIP SDK, so $HasROCm is
false) the gfx arch was name-inferred but the ROCm-wheel branch never ran,
so the host got torch+cpu. With CPU torch, torch.cuda.is_available() is
False, so the Studio backend sets CHAT_ONLY=True and hides Train/Export.

Un-gate the ROCm PyTorch index resolution on a known gfx arch (mirrors the
llama.cpp --rocm-gfx fix). AMD's per-arch Windows wheels
(repo.amd.com/rocm/whl/<gfx>) bundle the ROCm runtime, so they work without
a HIP SDK; a failed install still falls back to CPU.

Verified on Radeon 8060S / gfx1151: torch 2.11.0+rocm7.13.0 installs and
torch.cuda.is_available() -> True, device "AMD Radeon(TM) 8060S Graphics",
GPU matmul OK -> CHAT_ONLY=False -> Train/Export enabled.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Force amd-smi un-elevated process-wide in the Python installers

Guarding individual amd-smi call sites kept missing some (install_python_stack.py's probe loop and its Windows GPU re-check), so the DiskPart UAC prompt kept reappearing. Set __COMPAT_LAYER=RunAsInvoker process-wide at the top of install_python_stack.py and install_llama_prebuilt.py on Windows so every amd-smi subprocess (current and future) runs un-elevated with no per-call guard. Safe: these scripts only spawn amd-smi/rocminfo/hipinfo probes and pip/uv. setup.ps1 keeps per-call guards because it also spawns winget installers that need elevation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix Invoke-AmdSmiNoElevate exit code on PS 5.1 + RX 7700S arch match

Start-Process -PassThru leaves the returned process object's .ExitCode
$null after WaitForExit on Windows PowerShell 5.1, so the helper set
$LASTEXITCODE to $null and every caller's `if ($LASTEXITCODE -eq 0 ...)`
was always false -- the amd-smi GPU / gfx-token / ROCm-version detection
branch was effectively dead (masked only because the un-gated WMI
name->gfx inference still ran). Reproduced on PS 5.1.26100.

Rewrite the helper to use [System.Diagnostics.Process]::Start with a
ProcessStartInfo (UseShellExecute=false), whose .ExitCode is reliable,
with async stream reads (ReadToEndAsync) to avoid a pipe-buffer deadlock
and WaitForExit(timeout) to bound a flaky amd-smi. __COMPAT_LAYER=
RunAsInvoker (inherited via the process env) still suppresses the
auto-elevation / DiskPart prompt. Also drops the temp files and the
empty-ArgumentList edge case. Verified: exit code propagates
(7 -> $LASTEXITCODE=7), output captured, env restored.

Also fix the gfx1100 name pattern `RX 7700(?! S)` -> `RX 7700(?!S)` so the
spaceless retail name "RX 7700S" is correctly excluded (it belongs to the
gfx1102 row). Both found by PR review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Address PR review follow-ups (install.sh table, update path, tests, WSL)

From the multi-agent PR review:

- install.sh: sync the AMD name->arch table with install.ps1 / setup.ps1
  (the bash table had drifted to the old narrow patterns). Adds RDNA 2
  (gfx103X), workstation PRO W SKUs, and more Strix Halo/Point names, and
  orders gfx1102 before gfx1100 so the spaceless retail name "RX 7700S"
  resolves correctly (bash case has no negative lookahead). AMD-ROCm-only:
  the name inference stays gated behind _has_amd_rocm_gpu(), so NVIDIA /
  CPU / macOS are unaffected.

- setup.ps1: the "dependencies up to date" fast path skipped the torch
  reinstall, so an existing user who had CPU torch (installed before
  ROCm-wheel support) stayed stuck in CHAT_ONLY. Now, when an AMD gfx arch
  is known AND the installed torch is CPU-only, don't skip -- force the
  dependency pass so the ROCm wheels install.

- scripts/install_rocm_wsl_strixhalo.sh: resolve the real /opt/rocm dir
  instead of hardcoding ROCM_VER for LD_LIBRARY_PATH / the librocdxg
  symlink (breaks if amdgpu-install lays ROCm under a patch-version dir);
  add a LIBROCDXG_REF pin knob and a "verified against" freshness header.

- tests/studio/install/test_pr5940_followups.py: cover _hf_resolve_url_parts,
  _fetch_validation_model_bytes (hf path + urllib fallback), run_capture's
  Windows-only amd-smi RunAsInvoker injection, and install.ps1 vs setup.ps1
  name-table parity (catches future drift). 14 tests, all passing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix DiskPart UAC prompt: skip amd-smi on Windows without a HIP SDK

On Windows, amd-smi re-initialises the ROCm runtime on every invocation
(even `amd-smi version`) and, on hosts without a working HIP runtime
(consumer APUs/dGPUs with only the Adrenalin driver), elevates a child
process at runtime -- popping a UAC/DiskPart prompt. amd-smi's own
manifest is asInvoker, so __COMPAT_LAYER=RunAsInvoker cannot suppress
that runtime elevation (verified: even `amd-smi version` hangs and
times out with RunAsInvoker set).

Replace the ineffective RunAsInvoker-only approach with a real gate:
only spawn amd-smi on Windows when a HIP SDK is detectable (hipinfo
present, so amd-smi runs un-elevated) or the user opts in with
UNSLOTH_ENABLE_AMD_SMI=1. The gfx arch is already resolved from WMI
name inference (forwarded via --rocm-gfx), so ROCm wheel + lemonade
llama.cpp selection is unaffected. Linux/macOS amd-smi never elevates
and is untouched (no regression). RunAsInvoker is kept as harmless
belt-and-suspenders for tools that DO use manifest elevation.

Applied consistently across:
  - studio/backend/utils/hardware/amd.py  (runtime GPU polling)
  - install.ps1, studio/setup.ps1         (install-time detection)
  - studio/install_llama_prebuilt.py      (prebuilt arch probe + version)
  - studio/install_python_stack.py        (ROCm version + arch probe)

Verified live on AMD Radeon 8060S (gfx1151), native Windows: fresh
install detects the GPU, installs ROCm torch (torch.cuda.is_available()
True), launches Studio with no DiskPart prompt, and inference, tool
calling, web search, LoRA finetuning, and GGUF export all run on the GPU.

Tests: add 6 _amd_smi_allowed() gating tests + PowerShell-installer gate
assertions; update the three amd-smi monitoring tests to opt in (they
mock amd-smi as available). Full suite: 267 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* install.sh: helpful WSL message when the GPU isn't exposed to ROCm

In WSL, an AMD GPU's ROCm-on-WSL runtime is only available with a recent
Adrenalin driver AND a distro AMD supports (currently Ubuntu 24.04). When
neither is in place, GPU detection (rocminfo/_has_amd_rocm_gpu) finds
nothing and we silently fall back to CPU.

Add an actionable hint in the CPU-fallback path, shown only on WSL and
only AFTER detection has already failed -- so it is forward-compatible:
the moment a driver/distro DOES expose the GPU (e.g. if AMD later adds
Ubuntu 26.04 support), detection succeeds and the hint never fires. The
message:
  - notes a GPU is plumbed in (/dev/dxg) but no ROCm runtime is exposed,
  - lists the two prerequisites (Adrenalin driver + Ubuntu 24.04),
  - if the distro is not 24.04, says AMD may not support it yet,
  - tells the user to `wsl --install Ubuntu-24.04` and re-run,
  - links AMD's ROCm-on-WSL guide + the experimental Strix Halo helper.

Verified live: on Ubuntu-24.04 the hint shows (version-warning omitted)
and the CPU install completes; on Ubuntu-26.04 the extra "this distro may
not be supported" line appears and points to 24.04.

Also fix the experimental scripts/install_rocm_wsl_strixhalo.sh: AMD's
repo.radeon.com/amdgpu-install/ is indexed by unified installer version
(30.30, 31.30, ...), NOT ROCm version, so the hard-coded
amdgpu-install/7.2.0/ path 404'd. Scan the installer dirs newest-first
for a noble .deb matching the target ROCm major.minor (ROCm 7.2 ->
30.30.x/amdgpu-install_7.2.x), falling back to the newest available.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* WSL: fix shortcut collision + pin ROCm-on-WSL driver reqs from AMD docs

Two WSL-related fixes informed by AMD's official ROCm-on-WSL docs and
field reports for Strix Halo / Ryzen AI Max+ (Radeon 8060S, gfx1151):

1. Shortcut collision (real bug). install.sh's WSL branch wrote
   "Unsloth Studio.lnk" to the SAME Desktop / Start Menu folder as the
   native-Windows installer (install.ps1 New-StudioShortcuts). Running
   install.sh in WSL therefore silently retargeted the native shortcut at
   the WSL launcher (wt.exe -> wsl.exe), so the desktop/start-menu icon
   stopped launching native GPU Studio. Now the WSL shortcut uses a
   DISTINCT name -- "Unsloth Studio (WSL - <distro>).lnk" -- and fetches
   the Unsloth .ico to %LOCALAPPDATA%\Unsloth Studio so it shows the
   proper icon. Native and WSL shortcuts now coexist.

2. Precise ROCm-on-WSL prerequisites. Research (AMD radeon-ryzen WSL
   compatibility matrix, gianni.rosagallina.com Feb-2026 guide,
   ROCm/ROCm#4952/#5509/#6022) confirms WSL GPU on Strix Halo requires
   AMD Adrenalin Edition >= 26.1.1 (26.2.2+ is the first production
   ROCDXG/WSL release) + ROCm 7.2.1 + Ubuntu 24.04; an older driver does
   not inject the ROCm/DXG runtime into /usr/lib/wsl/lib, so rocminfo sees
   only the CPU. install.sh's WSL hint and the experimental
   install_rocm_wsl_strixhalo.sh header/preflight now state the exact
   driver version (was a guessed ">=26.3.1"), bump ROCM_VER to 7.2.1, link
   AMD's radeon-ryzen docs, and document the known librocdxg caveat that
   usable VRAM is currently capped at the .wslconfig memory setting.

bash -n clean; install test suite 267 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: hint when the AMD driver is too old for ROCm-on-WSL

Adds a detect-and-guide hook for the optional WSL-GPU path. An AMD GPU on
native Windows can also be used inside WSL2, but only with AMD Adrenalin
Edition >= 26.2.2 (the first production ROCDXG/WSL release). Native Windows
GPU works with any recent driver, so this is purely about enabling the WSL
path.

We intentionally do NOT auto-install the driver: AMD referrer-gates driver
downloads (scripted curl/Invoke-WebRequest are blocked) and does not publish
Adrenalin via winget, so no installer can reliably fetch it -- and silently
swapping a live display driver is risky. Instead we point the user at AMD's
official download page (one click), after which the existing WSL detection
lights up automatically.

- install.ps1: new Show-AmdWslDriverHint -- when an AMD GPU is present and the
  installed driver predates the 26.2.2 release (DriverDate < 2026-02-01),
  print a concise tip with the AMD download URL. Handles DriverDate as either
  a CIM DateTime or a WMI string. Suppress with UNSLOTH_SKIP_AMD_DRIVER_HINT=1.
- install.sh (WSL hint): add the direct Adrenalin 26.2.2 download URL and note
  that AMD downloads are referrer-gated (open in a browser).

Verified: hint fires on a Sept-2025 driver, auto-suppresses on >= 2026-02-01;
install.ps1 parses; install.sh bash -n clean; suite 267 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* install.ps1: refresh shell icon cache after creating the shortcut

After writing the Desktop / Start Menu .lnk, nudge Explorer to refresh
its icon (ie4uinit.exe -show). Without this, a stale icon cache can show
a blank shortcut icon until the next explorer restart -- most visible
when a shortcut of the same name was rewritten (e.g. a native install
followed by a WSL install, which previously shared the name; now they use
distinct names, but the cache nudge makes the icon appear immediately
regardless). Best-effort and wrapped in try/catch so it never fails the
install. The bundled unsloth.ico itself is valid (verified it renders).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* setup.ps1: don't silently CPU-build llama.cpp on an AMD GPU

For AMD, GPU acceleration comes from the lemonade ROCm prebuilt (it bundles
the ROCm runtime, no HIP SDK needed) and is the preferred/default path. The
source-build fallback is CPU-only -- a HIP/ROCm *source* build would need the
full HIP SDK + ROCm clang toolchain, which the prebuilt exists to avoid.

Previously, if an AMD-GPU host ever fell through to the source build (e.g. the
prebuilt could not be downloaded), it printed "building llama.cpp (CPU-only,
no NVIDIA GPU detected)" and quietly produced a CPU binary -- masking the lost
GPU acceleration. Now that case emits a loud [WARN] explaining the GPU prebuilt
is the AMD path and how to restore it (re-run / check network / set
UNSLOTH_LLAMA_RELEASE_TAG), so AMD never silently degrades to CPU.

No behavior change on the happy path: AMD still gets the GPU prebuilt (verified
on gfx1151: ggml-hip.dll bundled, ~80% GPU compute during inference). NVIDIA
(CUDA source build) and CPU-only hosts are unchanged.

setup.ps1 parses; install suite 267 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* uninstall: remove shared llama.cpp build, kill lock-holders, match WSL shortcut

Three gaps found by running a real uninstall on a native-Windows + WSL host;
all fixes are scoped to Unsloth-owned paths and no-op on the other pathways
(env/custom-root, NVIDIA/AMD/CPU, Mac) so nothing else regresses.

uninstall.ps1:
  - Remove the default-mode SHARED llama.cpp build + cache. setup.ps1 installs
    them at ~/.unsloth/llama.cpp and ~/.unsloth/.cache -- SIBLINGS of studio,
    not under it -- so deleting <studio> left hundreds of MB behind. Now removed
    explicitly, then ~/.unsloth is dropped ONLY if empty (never nukes unrelated
    content). No-op in env/custom mode (llama.cpp nests under the custom root,
    removed already) and when absent. UNSLOTH_LLAMA_CPP_PATH (user-owned) is kept.
  - New _StopProcessesLockingRoots: _StopStudioProcesses only matched the venv
    unsloth/python/studio exe, so it missed (a) llama-server.exe under llama.cpp
    and (b) an orphaned multiprocessing python fork that ran from the SYSTEM
    python but loaded a venv DLL (bitsandbytes) -- on Windows an open DLL handle
    blocks the directory delete, leaving a half-removed install. The new helper
    kills any process whose image path OR loaded module is under a target root
    (module scan scoped to python/unsloth/llama-server names; vendor-agnostic).
  - _RemovePath now retries (transient post-kill handle release).

uninstall.sh:
  - Remove the default-mode ~/.unsloth/llama.cpp + ~/.unsloth/.cache; rmdir
    ~/.unsloth only if empty.
  - WSL Windows-side shortcut cleanup now matches by TARGET (any
    "Unsloth Studio*.lnk" whose target launches wsl.exe), covering both the
    legacy "Unsloth Studio.lnk" and the new "Unsloth Studio (WSL - <distro>).lnk"
    -- and never removes a native-Windows shortcut (which launches wscript.exe).

uninstall.ps1 parses; uninstall.sh passes sh -n and bash -n.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* install.ps1: invalidate Win11 Start Menu tile cache after creating shortcut

The Start Menu shortcut kept showing a blank/generic icon even after the
Explorer icon-cache rebuild, because Windows 11's StartMenuExperienceHost
keeps its OWN pre-rendered tile-icon cache
(%LOCALAPPDATA%\Packages\Microsoft.Windows.StartMenuExperienceHost_cw5n1h2txyewy\
TempState\TileCache_*.bin + StartUnifiedTileModelCache.dat), separate from
Explorer's iconcache_*.db. ie4uinit and an explorer.exe restart do not touch
it, and they don't recycle the host -- so a rewritten same-name shortcut keeps
showing the first-rendered (often the generic wscript ">") tile until the host
restarts on its own.

Fix: after creating the shortcut, drop only the Start Menu RENDER caches
(TileCache_* + StartUnifiedTileModelCache.dat) and stop StartMenuExperienceHost
(Windows auto-relaunches it), so the tile re-resolves the real icon via the
shell image factory. start2.bin (the user's pinned layout) is deliberately
preserved. Guarded by Test-Path (Windows 10 has no such host -> skipped) and
wrapped in try/catch so it can never fail the install. Windows-only
(install.ps1); no effect on Linux/macOS/Studio.

Verified live: rendering the shortcut via IShellItemImageFactory::GetImage (the
API StartMenuExperienceHost uses) returns the Unsloth sloth icon, color-matched,
after this invalidation -- previously it returned the generic script tile.

install.ps1 parses; install suite 267 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* ROCm-on-WSL for AMD Strix Halo (gfx1151): auto-setup + runtime enablement

Make Unsloth Studio set up ROCm-on-WSL automatically for AMD Strix Halo
(Radeon 8060S / gfx1151) and use the GPU at runtime, validated end-to-end
on a Ryzen AI Max+ PRO 395 (ROCm 7.2.1 + librocdxg + Adrenalin Apr-2026):
rocminfo enumerates gfx1151, torch.cuda True, ~85.8 GB UMA pool.

Every change is a strict no-op for all other configs (NVIDIA/CUDA,
discrete + native-Linux AMD ROCm, macOS/MLX, Windows, CPU-only, non-Strix
WSL) and can never abort the installer.

- scripts/install_rocm_wsl_strixhalo.sh: rewrite to the validated recipe.
  Fixes that would have broken a working box: drop the /usr/lib/wsl/lib
  preflight (a working ROCDXG host has only d3d12/dxcore there); remove the
  obsolete rocr4wsl step (gone from the 7.2.1 repo; would hard-fail and also
  rips out the standard hsa-rocr ROCDXG needs); dynamic librocdxg soname
  (was hardcoded 1.1.0; build is 1.2.0); direct apt-repo install; Windows
  SDK auto-discovery; persist env to /etc/profile.d + ~/.bashrc; idempotent.
- install.sh: _maybe_bootstrap_rocm_wsl auto-offers/runs the helper when it
  detects a Strix Halo APU in WSL (/dev/dxg) with no ROCm runtime, then
  loads the env so detection routes to the gfx1151 wheels. Fast-path when
  already configured. Fix an inaccurate WSL hint line.
- studio/backend/main.py + worker.py: set HSA_ENABLE_DXG_DETECTION=1
  in-process before torch (gated on /dev/dxg AND librocdxg.so), so the
  worker uses the GPU even when launched outside a login shell. Mirrors the
  existing BNB_ROCM_VERSION injection.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* uninstall: clean up ROCm-on-WSL artifacts + Start Menu tile cache

- uninstall.sh: remove the ROCm-on-WSL helper artifacts -- the librocdxg
  build clone (~/.unsloth/librocdxg, which otherwise blocks the empty-dir
  rmdir of ~/.unsloth), the throwaway smoke-test venv, the persisted env
  (/etc/profile.d/unsloth-rocm-wsl.sh) and the ~/.bashrc block. The system
  ROCm userspace is a shared prereq like CUDA and is kept by default;
  UNSLOTH_UNINSTALL_ROCM=1 removes it too. No-ops on macOS / non-Strix Linux.
- uninstall.ps1: invalidate the Win11 Start Menu tile cache after removing
  the shortcut so its tile disappears promptly (mirrors install.ps1),
  preserving start2.bin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: accurate AMD ROCm messaging (HIP SDK optional, not required)

The Windows installer printed "HIP SDK not found - GPU-accelerated training
unavailable" / "ROCm wheels require the HIP SDK" whenever the HIP SDK was
absent. That is misleading: for a detected AMD GPU arch (gfx1151 etc.),
setup.ps1 installs AMD's bundled-runtime ROCm PyTorch wheels (repo.amd.com)
which ship their own ROCm runtime and do NOT need the HIP SDK -- verified
end-to-end (torch 2.11.0+rocm7.13.0, cuda True, QLoRA training on GPU) on a
Radeon 8060S with no HIP SDK installed.

Gate the GPU-detection + rocm-step messages on a detected gfx arch: when one
is known, state that GPU PyTorch uses bundled-runtime wheels and the HIP SDK
is optional; only when the arch is unknown fall back to the HIP-SDK hint.
Behavior (torch routing) is unchanged; this is messaging only. No-op for
NVIDIA/CUDA, HIP-SDK-present, and CPU paths (they hit earlier branches).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: fix /opt/rocm data-loss + make WSL shortcut create/remove interop-robust

Two fixes from the 3-reviewer regression audit + live testing on a
systemd-enabled WSL distro (interop disabled):

F1 (data-loss, install_rocm_wsl_strixhalo.sh): the /opt/rocm symlink-repair
could force-delete a pre-existing REAL ROCm install. The guard only checked
that /opt/rocm is a real directory, not that it is the stray librocdxg stub.
Now it only touches /opt/rocm when it is NOT a real install (no bin/rocminfo,
bin/hipcc, or .info/version present), and MOVES it aside (rocm.unsloth-stub-bak)
instead of deleting it, so a wrong guess can never lose data.

WSL interop robustness (install.sh + uninstall.sh): both relied on
`command -v powershell.exe`, which is true even when WSL interop cannot EXECUTE
it (on systemd distros powershell.exe fails with "Exec format error"). Result:
the WSL shortcut silently failed to create (install) and to remove (uninstall).
- uninstall.sh: test that powershell.exe actually runs; if not, remove the
  "Unsloth Studio (WSL...).lnk" files directly via drvfs (/mnt/<drive>), which
  works without interop. The name is WSL-install-specific, so a native install's
  "Unsloth Studio.lnk" is never touched.
- install.sh: when the shortcut cannot be created, warn with the manual launch
  command + how to re-enable interop, instead of failing silently.

No behavior change on the interop-on path. The regression audit otherwise found
no regressions on Linux/Mac/Windows/CPU/NVIDIA install paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* install.sh: fast-path fully restores ROCm-on-WSL env when the drop-in is gone

Reinstall regression found by uninstall->reinstall testing: after a Studio
uninstall that removed /etc/profile.d/unsloth-rocm-wsl.sh but KEPT the shared
ROCm (the default), a non-login reinstall hit the bootstrap fast-path
(librocdxg present) and its else-branch only set HSA_ENABLE_DXG_DETECTION --
NOT PATH/LD_LIBRARY_PATH. So rocminfo was not on PATH, GPU detection failed,
and the installer fell back to CPU-only PyTorch.

Fix: when librocdxg is present but the env drop-in is missing, restore the
FULL env inline (HSA + TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL + PATH +
LD_LIBRARY_PATH) so rocminfo is found and detection routes to the GPU, and
recreate /etc/profile.d/unsloth-rocm-wsl.sh so future shells and the Studio
worker get it too. No change to the env-present fast-path or any other host.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: clear Explorer icon cache so shortcut icons aren't blank

Root cause of the persistent blank Desktop + Start Menu icons: Explorer caches
each shortcut's icon in iconcache_*.db and does NOT re-read the .ico when a
same-name .lnk is recreated across reinstalls. The .ico and .lnk are correct
(the shell renders them non-blank via IShellItemImageFactory; the .ico has real
image data at 16/32/48/128 px), but the stale cache entry wins. The previous
fix only ran a weak `ie4uinit -show` + the Start Menu tile-cache clear -- it
never invalidated Explorer's icon cache, so the desktop icon stayed blank.

Fix (native install.ps1 New-StudioShortcuts AND the WSL shortcut path in
install.sh):
- ie4uinit -ClearIconCache (thorough; replaces -show as the primary refresh)
- SHChangeNotify(SHCNE_ASSOCCHANGED) to force a live desktop/taskbar refresh
  WITHOUT restarting explorer
- keep the Win11 Start Menu tile-cache invalidation (and add it to the WSL
  shortcut path too, preserving start2.bin)

Non-disruptive (no explorer restart). install.ps1 parses clean; install.sh
passes bash -n + dash -n; the heredoc-generated WSL PowerShell parses clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: per-item SHChangeNotify(UPDATEITEM) reliably fixes blank icons

The blank Desktop/Start Menu shortcut icons are a stale Explorer PER-ITEM icon
cache: when a same-name .lnk is recreated across reinstalls, Explorer caches the
previously-resolved (often generic "white page") icon for that item and won't
re-extract the .ico on its own. The .ico and the .lnk's IconLocation are correct
(every icon API renders the sloth) -- only Explorer's cached display is stale.

The previous refresh (ie4uinit -ClearIconCache + a GLOBAL SHCNE_ASSOCCHANGED
broadcast) does NOT recover a stale item -- confirmed by reproduction. The
reliable, NON-disruptive fix (no explorer restart) is a PER-ITEM
SHChangeNotify(SHCNE_UPDATEITEM, SHCNF_PATHW, <lnk path>) for each created
shortcut, which forces Explorer to re-read that exact item's icon.

Verified end-to-end: deliberately staled a shortcut to the generic icon, ran the
installer's exact new refresh code, and the sloth icon recovered with NO explorer
restart (confirmed by capturing the live desktop via PrintWindow).

Applied to both native install.ps1 (New-StudioShortcuts) and the WSL shortcut
path in install.sh. Still clears the on-disk icon cache (ie4uinit) and the Win11
Start Menu tile cache (preserving start2.bin).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* uninstall: remove leftover llama.cpp .staging root so ~/.unsloth is cleaned

The llama.cpp atomic-install staging root (install_llama_prebuilt.py
INSTALL_STAGING_ROOT_NAME=.staging) is a sibling of the llama.cpp install
dir (~/.unsloth/.staging in default mode). It is normally pruned after a
successful activate, but an interrupted or retained build can leave a
<name>.staging-XXXX tree behind. The uninstallers removed llama.cpp and
.cache but not .staging, so the final empty-dir cleanup of ~/.unsloth failed
and the directory lingered. Reproduced on WSL (Ubuntu-24.04) where an empty
llama.cpp.staging-XXXX dir kept ~/.unsloth alive after uninstall.

Remove ~/.unsloth/.staging in both uninstall.sh and uninstall.ps1. No-op in
env/custom mode (staging nests under the custom root removed already) and
when absent. Cross-platform fix (the staging logic is platform-agnostic).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer: WSL-absent hint + fix here-string lint false positive

install.ps1: in the AMD WSL-ROCm driver hint, detect when wsl.exe is absent
and add a one-line "wsl --install -d Ubuntu-24.04" pointer so a Strix Halo
user with no WSL yet gets an actionable next step (the hint previously assumed
an Ubuntu-24.04 distro already existed). Best-effort, informational only.

test_rocm_support.py: test_no_here_strings did a crude substring check that
false-positived on the conda-style block marker
printf '# <<< Unsloth ROCm-on-WSL (gfx1151) <<<' -- a string literal written
into the /etc/profile.d drop-in, also used as a sed delimiter pair by
uninstall.sh, not a here-string. Strip quoted spans before the check so the
lint still catches a real here-string operator but ignores quoted literals.
install.sh remains POSIX-clean (sh -n / dash -n / bash -n all pass).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* installer: address PR review comments (gfx1150 mapping, amd-smi opt-out, WSL bootstrap, SDK path, make)

Apply the valid bot review findings on #5940; reject the ones that don't hold.

Fixed:
- AMD name->gfx table (setup.ps1 + install.ps1): Radeon 890M and Ryzen AI 9 HX
  370/375 are Strix POINT (gfx1150), not Strix Halo (gfx1151). Move 890M / HX 37x
  / AI 9 HX to the gfx1150 row and drop the bogus HX 38x pattern (no such Strix
  Halo SKU). Matches the runtime classifier in worker.py (890M/880M -> gfx1150;
  8060S/8050S -> gfx1151). Prevents Strix Point hosts from getting the wrong ROCm
  prebuilt/wheels.
- amd-smi opt-out (setup.ps1 + install.ps1): an explicit UNSLOTH_ENABLE_AMD_SMI=
  0/false/no/off now wins over the HIP-SDK heuristic, so a host with a HIP SDK
  binary but a broken runtime no longer gets the DiskPart/UAC prompt the opt-out
  exists to avoid.
- amd-smi warning probes (install_python_stack.py): _has_rocm_gpu and
  _detect_amd_gfx_codes now gate amd-smi behind _amd_smi_allowed() (and pass
  _amd_smi_env()), closing the last unguarded amd-smi spawn on Windows.
- WSL ROCm bootstrap (install.sh): the "already-usable ROCm?" early return now
  requires rocminfo to enumerate the real gfx1151 agent instead of the generic
  _has_amd_rocm_gpu (whose broad gfx[1-9][0-9] match accepts a fallback
  "gfx11-generic" ISA), so a Strix Halo box missing the ROCDXG bridge is no longer
  skipped. The shared helper is untouched (no gfx90a regression).
- install_rocm_wsl_strixhalo.sh:
  * Quote-safe Windows SDK discovery: the old for-in-$(ls -d "...Program Files
    (x86)/...") word-split on the space and never matched; use find + read loop.
  * Add `make` to apt prereqs (cmake only recommends it; minimal images lacked it
    and the librocdxg `make -j` build failed).
  * Verification requires gfx1151 exactly (not gfx1[0-9]) so a generic ISA or an
    unrelated RDNA GPU can't pass while the real GPU is absent.

Reviewed but NOT changed:
- "Forward inferred ROCm arch without HasROCm" (setup.ps1): already correct --
  --rocm-gfx is forwarded under `if ($script:ROCmGfxArch)`, not `if ($HasROCm)`.
- "Route inferred arch into install.ps1 torch path": not a bug -- install.ps1
  installs CPU torch as a base by design and setup.ps1 swaps in the ROCm wheel for
  the inferred arch (gate `($HasROCm -or $ROCmGfxArch) -and cpu`); verified live
  the native install ends on torch 2.11.0+rocm7.13.0.
- "$p null guard after Start-Process" (install.ps1/setup.ps1): redundant -- the
  amd-smi runner uses [Process]::Start wrapped in try/catch, so a null process
  already returns "" with LASTEXITCODE=1 (no uncaught exception).
- "ls -> find for /usr/lib/wsl/lib" (gemini): stale -- that heuristic was removed;
  only a comment about it remains.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer(rocm-wsl): auto-install the Windows 11 SDK via winget (fewer manual steps)

librocdxg's build needs the Windows SDK 'shared' headers on the Windows host.
Previously the helper just die()d with "install the Windows 11 SDK and re-run" if
they were missing -- a manual prerequisite that broke the otherwise-seamless
`curl ... install.sh | sh` one-liner on Strix Halo.

Now, when the headers aren't found, the helper installs the Windows 11 SDK on the
Windows host from inside WSL via winget (powershell.exe interop), then
re-discovers them. The SDK installer elevates -> ONE UAC prompt on the Windows
desktop; the headers appear under /mnt/c immediately (drvfs is live, no reboot).
The user already consented to the ROCm-on-WSL setup, so no extra prompt is added
beyond the OS UAC gate.

- New _find_win_sdk (space-safe find of the newest installed SDK 'shared' dir)
  and _install_windows_sdk_via_winget helpers.
- winget IDs tried newest-stable first: Microsoft.WindowsSDK.10.0.26100, then
  .22621. The presence of the headers (re-check) is the source of truth, not
  winget's exit code. </dev/null so winget never consumes a piped `curl|sh` stdin.
- Best-effort + non-fatal: interop-off / no-winget / declined-UAC all fall
  through to the existing clear manual-install die(). Opt out with
  UNSLOTH_SKIP_WIN_SDK_INSTALL=1.

Removes the last avoidable manual step from the WSL Strix Halo path; only the AMD
Adrenalin driver (AMD referrer-gates the download) remains manual. Verified
_find_win_sdk resolves the spaced "Program Files (x86)" path; bash -n clean; all
winget flags validated against `winget install --help`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* installer(amd): gate install-time amd-smi probe to fix DiskPart UAC prompt

install_python_stack.py's Windows "AMD GPU detected but ROCm torch missing"
warning probe ran `amd-smi list` whenever amd-smi was on PATH -- and amd-smi
ships in C:\Windows\System32 with the AMD Adrenalin driver -- without the
_amd_smi_allowed() gate that every other amd-smi call site in the file uses.
On Adrenalin-only hosts (no HIP SDK) amd-smi elevates a child at runtime and
pops a UAC/DiskPart prompt that __COMPAT_LAYER=RunAsInvoker cannot suppress
(amd-smi's manifest is asInvoker). The probe also ran before the
ROCm-torch-installed check, so it fired on every Windows AMD install.

Gate it behind _amd_smi_allowed() and pass _amd_smi_env(), matching
_has_rocm_gpu()/_detect_amd_gfx_codes(). When skipped, the only loss is the
best-effort "AMD GPU detected" note on HIP-SDK-less hosts.

Adds a per-function AST regression test asserting every function in
install_python_stack.py that names the amd-smi command and spawns a subprocess
also references _amd_smi_allowed() (flags the pre-fix code; passes after).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* studio(cli): fix `unsloth studio stop` crashing on Windows

`stop` used the POSIX `os.kill(pid, 0)` liveness probe, but on Windows
CPython raises OSError (WinError 87, "The parameter is incorrect") for
*every* pid -- alive or dead. `stop` only catches ProcessLookupError /
PermissionError, so the OSError propagated and the command crashed with
a traceback before ever reaching its (correct) `taskkill /F` path.

Add a cross-platform `_pid_alive(pid)` helper (tasklist on Windows,
signal-0 elsewhere) and use it for both the pre-check and the post-kill
wait loop. The actual kill path is unchanged.

Verified on Windows (Python 3.13): os.kill(pid,0) raises WinError 87 for
both a live and a dead pid; `_pid_alive` returns True/False correctly and
the full stop() flow (alive -> taskkill -> dead -> "stopped") passes
end-to-end against a throwaway process.

Adds tests/studio/test_cli_studio_stop_windows.py (AST guard against a
bare os.kill(pid,0) liveness probe + mock-only _pid_alive behaviour for
the win32 tasklist branch and the POSIX signal-0 branch).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* installer(amd): fix install.sh name->arch table misrouting Strix Point to gfx1151

The bash name->arch inference table in install.sh placed Strix Point
identifiers (Radeon 890M, "Ryzen AI 9 HX 370/375", "AI 9 HX") in the
gfx1151 (Strix Halo) row, diverging from the install.ps1 / setup.ps1
PowerShell tables which correctly map them to gfx1150. It also carried a
stray "HX 38" token absent from the PowerShell source-of-truth.

Align install.sh with the PowerShell tables:
  gfx1151 row: 8060S|8050S|8040S|Strix Halo|Ryzen AI Max|AI Max
  gfx1150 row: 890M|880M|860M|840M|Strix Point|Krackan|HX 37|AI 9 HX|...

Impact is low (the bash table only feeds the display label _gpu_disp_gfx
and the "set UNSLOTH_ROCM_GFX_ARCH=..." hint; wheel selection is driven
by the detected ROCm version, not this name string) but a Strix Point
user would otherwise see/copy the wrong gfx arch.

Add a parity test (test_install_sh_name_arch_agrees_with_ps_for_strix_and_non_amd)
that parses install.sh's case table and asserts Strix Halo->gfx1151,
Strix Point->gfx1150, RX 7700S->gfx1102, and NVIDIA/Intel->no match,
cross-checking against install.ps1 (the previous parity test only
compared install.ps1 <-> setup.ps1, missing install.sh).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* setup.ps1: keep prebuilt-llama ownership guard within the test's block window

The AMD additions to the prebuilt-llama.cpp block (the windows-hip vs
windows-cpu existing-install kind validation) pushed the
install_llama_prebuilt.py invocation to ~1999 chars after the
"installing prebuilt llama.cpp bundle (preferred path)" anchor, right at
the edge of the 2000-char window that
test_setup_ps1_prebuilt_llama_cpp_has_ownership_guard slices -- so the
helper string was truncated and the test failed with "substring not
found" (CI: Repo tests (CPU)).

The ownership-guard invariant (Assert-StudioOwnedOrAbsent precedes the
install_llama_prebuilt.py call) was already satisfied; only the proximity
to the anchor regressed. Move the "installing prebuilt..." substep to
immediately before the install (after the existing-install pre-cleanup),
which also reads better (validate/clean existing -> then "installing"),
shrinking anchor->helper from 1999 to 413 chars. Behaviour is unchanged
(console message ordering only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* install.sh: auto-run Strix Halo ROCm-on-WSL setup by default

`curl -fsSL https://unsloth.ai/install.sh | sh` should make a Strix Halo
(gfx1151) GPU usable inside WSL with no extra commands. Previously the
ROCm-on-WSL bootstrap was opt-in: it required UNSLOTH_ROCM_WSL_AUTO=1 or an
interactive [Y/n] at a TTY, and silently skipped under a pipe (no /dev/tty),
so the piped one-liner never set the GPU up automatically.

Flip it to auto-by-default for the single narrow case the existing guards
allow (WSL + Strix Halo + /dev/dxg + no usable ROCm yet) -- exactly the GPU
setup the user ran the installer for. Opt out with
UNSLOTH_SKIP_ROCM_WSL_SETUP=1. The Tauri desktop app keeps its own consent UI
(only auto-runs when it passes UNSLOTH_ROCM_WSL_AUTO=1). All hardware/OS
guards are unchanged, so non-Strix / non-WSL / NVIDIA / native-Linux / macOS /
CPU paths are unaffected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* PR comments: condense to be succinct (comments/docstrings only)

Shorten the verbose explanatory comments and docstrings this PR added across
the installer, scripts, backend shims, CLI, and tests -- tighter, fewer lines,
while preserving every non-obvious "why" (os.kill WinError 87, amd-smi
RunAsInvoker/UAC, /dev/dxg + librocdxg gating, the ROCm-on-WSL bootstrap guard
chain, ownership guards, etc.). No executable code, string literals, messages,
or behavior changed.

Verified comments-only: docstring-normalized AST equality (Python, 9 files),
non-comment token equality (PowerShell, 3 files), comment-stripped diff +
sh -n / bash -n (shell, 3 files). Behavior re-confirmed: get_torch_index_url +
gfx name->arch table 44/44 under dash & bash; rocm_support / pr5940_followups /
cli_studio_stop tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Installer: address PR review (amd-smi opt-out, pipefail, multi-distro, non-root)

Fixes valid findings from the Codex/Gemini PR review:
- install.ps1 / setup.ps1: gate the `amd-smi version` ROCm-version fallback with
  $amdSmiAllowed so UNSLOTH_ENABLE_AMD_SMI=0 opt-out is honored (the device
  probe was gated but this fallback wasn't), avoiding the DiskPart/UAC prompt.
- install_rocm_wsl_strixhalo.sh: make the post-verification rocminfo summary
  best-effort (|| true) so head's early pipe-close under `set -o pipefail` can't
  fail the bootstrap after gfx1151 was already enumerated; pin the Windows SDK
  `winget install` to --source winget (matches the msstore-cert fix rationale).
- install.ps1: python.org fallback installs the py launcher per-user
  (InstallLauncherAllUsers=0, avoids admin), and derives the fallback full
  version from the requested minor so a non-default UNSLOTH_PYTHON (e.g. 3.12)
  isn't silently replaced with 3.13 when the listing is unreachable.
- install.sh: recreate /etc/profile.d/unsloth-rocm-wsl.sh via `sudo tee` for a
  non-root reinstall (a plain redirect failed silently, dropping the ROCm env).
- uninstall.sh: scope WSL Windows-side shortcut removal to the current
  WSL_DISTRO_NAME (per-distro name or -d "<distro>" arg) so uninstalling one
  distro no longer deletes other distros' launchers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Studio ROCm Windows: fix field-reported issues from Strix Halo testers

Four fixes from PR #5940 field reports (Win11 native, gfx1151):

1. bitsandbytes arch-probe spam: bnb's get_rocm_gpu_arch() runs
   hipinfo.exe via subprocess PATH at import; the AMD torch wheel ships
   hipInfo.exe in the venv Scripts dir, which is only on PATH for
   activated venvs. Every bnb import logged "Could not detect ROCm GPU
   architecture: [WinError 2]" ERROR + WARNING (even with the HIP SDK
   installed, whose bin dir is not on PATH either). Prepend the Scripts
   dir to PATH before bnb imports in main.py, worker.py, and
   install_python_stack.py, gated on the file existing (only AMD wheels
   ship it). Verified on gfx1151: ROCM_GPU_ARCH now resolves to gfx1151
   with zero errors.

2. OOM-guard double-tax on native Windows unified APUs: mem_get_info's
   total is the WDDM budget the driver grants HIP (BIOS carve + ~half
   of remaining RAM) -- the OS share is already outside it. The 0.80
   unified cap on top denied loads that fit (field report: 48.49 GiB
   budget -> "38.79 GiB allowed" OOM for a 47.29 GiB load with 48.08
   free). Use 1.0 on win32 unified; Linux keeps 0.80, discrete 0.90.

3. "Missing VRAM" confusion: log the WDDM budget vs physical RAM with
   the fix (BIOS UMA frame buffer / AMD Software Variable Graphics
   Memory) when the grant is under 75% of RAM, so a 48 GiB cap on a
   96 GiB box reads as policy, not a Studio bug.

4. llama-server fit-step crash (Qwen3.6-27B-MTP + mmproj, lemonade
   gfx1151): --fit defaults to 'on' upstream, so the fit step runs even
   when Studio already placed the model via -ngl -1, and aborts in
   ggml-cuda.cu on some ROCm hosts. Retry the spawn once with --fit off
   when the server crashes during startup and Studio's own VRAM math
   had placed the model (never when use_fit or an explicit fit flag was
   passed). Also keep the TAIL of crash output in the error log (the
   diagnostic line prints last; head-truncation cut exactly that) and
   reference the full on-disk log.

Verified live on Radeon 8060S: bnb import clean, Qwen3.5-4B-MTP loads
and generates through the new spawn loop, stub-crash retry appends
--fit off and recovers, fraction probes confirm WDDM overcommit and
sub-1.0-only enforcement on current AMD wheels.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio ROCm Windows: GPU-name fallbacks so nothing depends on amd-smi

amd-smi does not reliably exist on Windows: the HIP SDK never ships a
CLI, inbox Windows Update drivers do not, and only some full Adrenalin
packages drop amd-smi.exe into System32 (field report: fresh Win11 +
Adrenalin + HIP SDK, still no amd-smi anywhere). Make every consumer
work without it:

- install_python_stack._detect_windows_gfx_arch: two new probes after
  hipinfo/amd-smi -- (2b) the venv Scripts hipInfo.exe shipped by AMD
  torch wheels (drives `studio update` on driver-only hosts), and (4) a
  last-resort GPU marketing-name -> gfx table via WMI
  (Win32_VideoController), mirroring setup.ps1's $nameArchTable so a
  standalone repair resolves the arch with zero AMD tooling installed.

- install_llama_prebuilt._resolve_exe: also probe the venv Scripts dir
  so a standalone rerun finds hipInfo.exe without HIP_PATH.

- hardware/amd.py _run_amd_smi: which() guard before spawning --
  absence now disables the poller in one step instead of burning the
  3-strike circuit breaker on FileNotFoundError; corrected the stale
  comment claiming Adrenalin ships amd-smi.

Simulated against the real detection functions on gfx1151: amd-smi
absent, present-but-crashing (exit 1), present-but-hanging (60s sleep
vs 5-10s probe timeouts), and hard opt-out -- all resolve gfx1151, no
exceptions, bounded time. Full adversarial install (broken amd-smi
stub first on PATH + UNSLOTH_ENABLE_AMD_SMI=1, fresh uninstall first):
exit 0, name-table arch inference, lemonade gfx1151 b1292 prebuilt,
torch 2.11.0+rocm7.13.0 cuda_avail=True on the 8060S, Studio boots
healthy and stops cleanly.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: per-attempt llama-server log names + amd-smi test portability

Found by cross-platform simulation of the --fit off retry (Windows +
Linux sandboxes, real load_model with stub servers):

- llama-server log filename now carries the spawn-attempt index. The
  retry can respawn within the same epoch second; reusing the name
  opened the same file with "w" and truncated the crash log the retry
  warning had just pointed the user at (proven with a frozen
  time.time: one file, crash evidence gone; with the suffix both
  attempts keep their logs). Regression-pinned in
  test_llama_cpp_wait_for_health.py.

- test_amd_primary_gpu_with_mock now mocks shutil.which alongside
  subprocess.run: the amd-smi absence guard which()-checks before
  spawning, so on hosts without a real amd-smi (Linux CI, driver-only
  Windows) the subprocess mock was never reached and the test failed.
  Surfaced by running the suite in a clean Linux sandbox.

Simulation coverage on both OSes: 67-case platform/edge matrix
(real shipped code blocks under win32/linux/darwin spoofs: OOM-guard
fractions + VGM-hint boundary, bnb PATH-prepend gates, retry
eligibility incl. equals-forms and decoy tokens, GPU-name table
adversarial set, WMI fallback without powershell, monitor absence
semantics), 6-scenario live retry matrix (crash-once/crash-always/
exit-zero/explicit-fit/hang/log-collision) against real llama-server
spawns on Windows and WSL (GPU success legs on the 8060S), and a
3-engine browser matrix (chromium/firefox/webkit) driving the live
backend's health + authed /v1 chat completion.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: classify unified-memory via props.is_integrated first

Align the ROCm OOM-guard classifier with PR #5988's UMA gate: consult
hipDeviceProp_t.integrated (props.is_integrated) before the hardcoded
arch set. Strictly additive -- truthy upgrades to unified; 0/absent
falls through to the existing gfx1150/gfx1151 + device-name logic, so
wheels that omit or zero the field cannot downgrade the known APU set.
Extends correct unified-cap treatment to APUs outside that set (e.g.
gfx1103 Phoenix iGPUs) and keeps Studio's two unified-memory consumers
on one driver signal. Verified live on gfx1151 (is_integrated == 1 on
the AMD Windows wheel -> ('gfx1151', True) via the new path).

* AMD detection: probe rocminfo with HSA_ENABLE_DXG_DETECTION and sync setup.sh gfx table

Fleet validation on a Strix Halo WSL2 box showed the system rocminfo
(HSA 1.18, ROCm 7.2.1) only enumerates the GPU over /dev/dxg when
HSA_ENABLE_DXG_DETECTION=1, and that rocminfo can sit at /opt/rocm/bin
off PATH outside login shells. Detection probes that miss either of
these report no GPU on a working ROCDXG host and select the CPU build
even though the lemonade bundle offloads fine (95.7 tok/s measured vs
64.5 CPU on the same laptop). Seed the env (a no-op on bare metal) and
the PATH fallback in install.sh, studio/setup.sh, and the installer's
Linux rocm probe, mirroring what main.py/worker.py already do for the
runtime.

Also sync studio/setup.sh's name->gfx table with install.sh: 890M and
the HX 37/AI 9 HX SKUs are Strix Point (gfx1150, not gfx1151), RX 7700S
must match gfx1102 before the gfx1100 row, and the RDNA2/workstation
rows were missing. New parity test pins the two bash tables together so
they cannot drift again.

* Studio: persist server session logs + native-crash stacks to disk

Field report (Strix Halo, 96 GB UMA carve, WSL and native Windows):
"the studio just terminates without a warning". A native crash in the
GPU runtime kills the process with no Python traceback, and a desktop-
shortcut console closes before anything can be read. The server only
ever logged to the console, so there was nothing to send back.

run_server now tees stdout/stderr to
~/.unsloth/studio/logs/server/server-<ts>-pid<n>.log (console behavior
unchanged; file copy is best-effort), arms faulthandler at the same
file so access violations / SIGSEGV leave a stack trace on disk, and
exports PYTHONFAULTHANDLER=1 so training workers inherit crash dumps
on their captured stderr. Armed before `from main import app` so even
import-time failures leave evidence. Keeps the newest 20 session logs;
opt out with UNSLOTH_STUDIO_NO_FILE_LOG=1. Prints "Session log: <path>"
at startup so users know what to attach.

Verified on this box: a forced real segfault (faulthandler._sigsegv)
leaves the full session output plus "Fatal Python error: Segmentation
fault" and the thread stack in the file while the console shows
nothing; a normal server boot captures the startup banner and serves
health as before.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* AMD probe: honor a pre-set HSA_ENABLE_DXG_DETECTION value

Match the shell helpers, which use the parameter-default form: a user
who exports HSA_ENABLE_DXG_DETECTION=0 to deliberately hide the GPU
from DXG detection should not have the probe override it.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 install.ps1                                   | 359 +++++++++++++++---
 install.sh                                    | 236 +++++++++++-
 scripts/install_rocm_wsl_strixhalo.sh         | 289 ++++++++++++++
 scripts/uninstall.ps1                         |  82 +++-
 scripts/uninstall.sh                          | 112 +++++-
 studio/backend/core/inference/llama_cpp.py    | 155 +++++---
 studio/backend/core/training/worker.py        |  87 ++++-
 studio/backend/main.py                        |  39 ++
 studio/backend/run.py                         |  99 +++++
 .../tests/test_llama_cpp_wait_for_health.py   | 108 ++++++
 studio/backend/tests/test_rocm_oom_guard.py   |  73 ++++
 .../backend/tests/test_server_disk_logging.py |  99 +++++
 studio/backend/utils/hardware/amd.py          |  68 +++-
 studio/install_llama_prebuilt.py              | 133 ++++++-
 studio/install_python_stack.py                | 157 +++++++-
 studio/setup.ps1                              | 188 +++++++--
 studio/setup.sh                               |  28 +-
 tests/studio/install/test_pr5940_followups.py | 334 ++++++++++++++++
 tests/studio/install/test_rocm_support.py     | 211 +++++++++-
 tests/studio/test_cli_studio_stop_windows.py  | 128 +++++++
 unsloth_cli/commands/studio.py                |  43 ++-
 21 files changed, 2803 insertions(+), 225 deletions(-)
 create mode 100644 scripts/install_rocm_wsl_strixhalo.sh
 create mode 100644 studio/backend/tests/test_server_disk_logging.py
 create mode 100644 tests/studio/install/test_pr5940_followups.py
 create mode 100644 tests/studio/test_cli_studio_stop_windows.py

diff --git a/install.ps1 b/install.ps1
index e57b3f670e..16337f4b9c 100644
--- a/install.ps1
+++ b/install.ps1
@@ -144,6 +144,10 @@ function Install-UnslothStudio {
 
     # UNSLOTH_PYTHON pins the version (mirrors install.sh --python); default 3.13.
     $PythonVersion = if ($env:UNSLOTH_PYTHON) { $env:UNSLOTH_PYTHON } else { "3.13" }
+    # python.org fallback patch, used only when winget is unavailable/broken AND
+    # the live python.org listing can't be fetched. The installer URL scheme is
+    # stable so an older patch still installs. Bump alongside $PythonVersion.
+    $PythonFallbackFullVersion = "3.13.13"
 
     # Resolve install destinations. Priority: UNSLOTH_STUDIO_HOME, then
     # STUDIO_HOME alias, then USERPROFILE-redirect, then default.
@@ -854,6 +858,7 @@ shell.Run cmd, 0, False
             try {
                 $wshell = New-Object -ComObject WScript.Shell
                 $createdShortcutCount = 0
+                $createdShortcutPaths = @()
                 foreach ($linkPath in @($desktopLink, $startMenuLink)) {
                     if (-not $linkPath -or [string]::IsNullOrWhiteSpace($linkPath)) { continue }
                     try {
@@ -867,12 +872,46 @@ shell.Run cmd, 0, False
                         }
                         $shortcut.Save()
                         $createdShortcutCount++
+                        $createdShortcutPaths += $linkPath
                     } catch {
                         substep "could not create shortcut at ${linkPath}: $($_.Exception.Message)" "Yellow"
                     }
                 }
                 if ($createdShortcutCount -gt 0) {
                     substep "Created Unsloth Studio shortcut"
+                    # Force Explorer to re-read each new shortcut's icon so it renders
+                    # immediately instead of a stale/generic entry (a same-name .lnk
+                    # recreated across reinstalls keeps Explorer's cached per-item icon).
+                    # The reliable, non-disruptive fix (no explorer restart) is a per-item
+                    # SHChangeNotify SHCNE_UPDATEITEM + SHCNF_PATHW per .lnk; the global
+                    # SHCNE_ASSOCCHANGED broadcast alone does NOT recover a stale item.
+                    # Also clear the on-disk icon cache (covers heavier staleness).
+                    try { & "$env:SystemRoot\System32\ie4uinit.exe" -ClearIconCache 2>$null } catch {}
+                    try { & "$env:SystemRoot\System32\ie4uinit.exe" -show 2>$null } catch {}
+                    try {
+                        Add-Type -Namespace UnslothShell -Name IconRefresh -MemberDefinition '[System.Runtime.InteropServices.DllImport("shell32.dll", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern void SHChangeNotify(int eventId, uint flags, string item1, System.IntPtr item2);' -ErrorAction SilentlyContinue
+                        # SHCNE_UPDATEITEM (0x00002000) + SHCNF_PATHW (0x0005) per shortcut
+                        foreach ($scPath in $createdShortcutPaths) {
+                            try { [UnslothShell.IconRefresh]::SHChangeNotify(0x00002000, 0x0005, $scPath, [System.IntPtr]::Zero) } catch {}
+                        }
+                        # SHCNE_ASSOCCHANGED (0x08000000) global refresh (belt-and-suspenders)
+                        [UnslothShell.IconRefresh]::SHChangeNotify(0x08000000, 0, $null, [System.IntPtr]::Zero)
+                    } catch {}
+                    # Win11's Start Menu (StartMenuExperienceHost) keeps its OWN
+                    # pre-rendered tile-icon cache that ie4uinit/explorer restart do NOT
+                    # invalidate, so a rewritten same-name shortcut shows the old tile
+                    # until the host restarts. Drop only the render caches (NEVER
+                    # start2.bin -- the pinned layout) and let the host rebuild.
+                    # Best-effort; Win10 has no such host (Test-Path skips it).
+                    try {
+                        $smehTemp = Join-Path $env:LOCALAPPDATA "Packages\Microsoft.Windows.StartMenuExperienceHost_cw5n1h2txyewy\TempState"
+                        if (Test-Path -LiteralPath $smehTemp) {
+                            Get-ChildItem -LiteralPath $smehTemp -Filter "TileCache_*" -ErrorAction SilentlyContinue |
+                                Remove-Item -Force -ErrorAction SilentlyContinue
+                            Remove-Item -LiteralPath (Join-Path $smehTemp "StartUnifiedTileModelCache.dat") -Force -ErrorAction SilentlyContinue
+                            Stop-Process -Name StartMenuExperienceHost -Force -ErrorAction SilentlyContinue
+                        }
+                    } catch {}
                 } else {
                     substep "no Unsloth Studio shortcuts were created" "Yellow"
                 }
@@ -985,6 +1024,79 @@ shell.Run cmd, 0, False
         return $null
     }
 
+    # ── Fallback: install CPython directly from python.org ──
+    # Used when winget is unavailable or fails (notably msstore cert-pinning error
+    # 0x8a15005e, which aborts `winget install` unless --source winget is given).
+    # Downloads the official installer and runs it silently as a per-user install
+    # (no UAC), putting python.exe + the py launcher on PATH. Mirrors the uv ->
+    # astral.sh fallback below. Returns @{ Version; Path } or $null.
+    function Install-PythonFromPythonOrg {
+        # python.org ships one installer per architecture.
+        $archSuffix = switch (Get-TauriDiagArch) {
+            "x86_64" { "-amd64" }
+            "arm64"  { "-arm64" }
+            "x86"    { "" }
+            default  { $null }
+        }
+        if ($null -eq $archSuffix) {
+            substep "No python.org installer is available for this architecture." "Yellow"
+            return $null
+        }
+
+        # Resolve the latest $PythonVersion.x patch from the python.org listing,
+        # falling back to a same-minor version if the listing cannot be fetched.
+        # Use the pinned full version only when it matches the requested minor so a
+        # non-default UNSLOTH_PYTHON (e.g. 3.12) doesn't silently install 3.13.
+        $full = if ($PythonFallbackFullVersion -like "$PythonVersion.*") { $PythonFallbackFullVersion } else { "$PythonVersion.0" }
+        try {
+            $listing = [string](Invoke-RestMethod -Uri "https://www.python.org/ftp/python/" -UseBasicParsing -TimeoutSec 20)
+            $patches = [regex]::Matches($listing, ([regex]::Escape($PythonVersion) + '\.(\d+)/')) |
+                ForEach-Object { [int]$_.Groups[1].Value } | Sort-Object -Descending
+            if ($patches.Count -gt 0) { $full = "$PythonVersion.$($patches[0])" }
+        } catch {}
+
+        $file = "python-$full$archSuffix.exe"
+        $url  = "https://www.python.org/ftp/python/$full/$file"
+        $dest = Join-Path ([System.IO.Path]::GetTempPath()) $file
+        substep "downloading Python $full from python.org..." "Yellow"
+        try {
+            Invoke-WebRequest -Uri $url -OutFile $dest -UseBasicParsing
+        } catch {
+            substep "python.org download failed: $($_.Exception.Message)" "Yellow"
+            return $null
+        }
+
+        # Per-user install => no UAC. PrependPath puts python + py on PATH;
+        # Include_launcher installs py.exe (preferred by Find-CompatiblePython).
+        substep "installing Python $full (silent, per-user)..."
+        $installArgs = @(
+            "/quiet",
+            "InstallAllUsers=0",
+            "PrependPath=1",
+            "Include_launcher=1",
+            # Launcher per-user too: Include_launcher defaults InstallLauncherAllUsers=1,
+            # which needs admin and would break this non-admin per-user fallback.
+            "InstallLauncherAllUsers=0",
+            "Include_pip=1",
+            "AssociateFiles=0",
+            "Shortcuts=0"
+        )
+        $rc = 1
+        try {
+            $proc = Start-Process -FilePath $dest -ArgumentList $installArgs -Wait -PassThru
+            $rc = $proc.ExitCode
+        } catch {
+            substep "python.org installer failed to start: $($_.Exception.Message)" "Yellow"
+        } finally {
+            Remove-Item -LiteralPath $dest -Force -ErrorAction SilentlyContinue
+        }
+        if ($rc -ne 0) {
+            substep "python.org installer exited with code $rc." "Yellow"
+        }
+        Refresh-SessionPath
+        return (Find-CompatiblePython)
+    }
+
     # ── Install Python if no compatible version (3.11-3.13) found ──
     # Find-CompatiblePython returns @{ Version = "3.13"; Path = "C:\...\python.exe" } or $null.
     Write-TauriLog "STEP" "Installing Python"
@@ -994,47 +1106,62 @@ shell.Run cmd, 0, False
         step "python" "Python $($DetectedPython.Version) already installed"
     }
     if (-not $DetectedPython) {
-        if (-not $script:WingetAvailable) {
-            Write-Host "[ERROR] No compatible Python (3.11-3.13) found and winget is unavailable on this host." -ForegroundColor Red
-            Write-Host "        Install Python $PythonVersion from https://www.python.org/downloads/" -ForegroundColor Yellow
-            Write-Host "        and re-run this installer (make sure 'Add Python to PATH' is checked)." -ForegroundColor Yellow
-            return (Exit-InstallFailure "winget required to install Python on this host")
-        }
         substep "installing Python ${PythonVersion}..."
         $pythonPackageId = "Python.Python.$PythonVersion"
-        # Temporarily lower ErrorActionPreference so that winget stderr
-        # (progress bars, warnings) does not become a terminating error
-        # on PowerShell 5.1 where native-command stderr is ErrorRecord.
-        $prevEAP = $ErrorActionPreference
-        $ErrorActionPreference = "Continue"
-        try {
-            winget install -e --id $pythonPackageId --accept-package-agreements --accept-source-agreements
-            $wingetExit = $LASTEXITCODE
-        } catch { $wingetExit = 1 }
-        $ErrorActionPreference = $prevEAP
-        Refresh-SessionPath
+        $wingetExit = $null
 
-        # Re-detect after install (PATH may have changed)
-        $DetectedPython = Find-CompatiblePython
-
-        if (-not $DetectedPython) {
-            # Python still not functional after winget -- force reinstall.
-            # This handles both real failures AND "already installed" codes where
-            # winget thinks Python is present but it's not actually on PATH
-            # (e.g. user partially uninstalled, or installed via a different method).
-            substep "Python not found on PATH after winget. Retrying with --force..." "Yellow"
+        if ($script:WingetAvailable) {
+            # --source winget avoids the msstore source, which can fail with
+            # cert-pinning error 0x8a15005e and abort the whole `winget install`
+            # (winget then demands --source). Python and uv both live in the
+            # winget source, so pinning it is correct and faster.
+            #
+            # Lower ErrorActionPreference so winget stderr (progress/warnings) is
+            # not a terminating error on PS 5.1 (native stderr is ErrorRecord).
+            $prevEAP = $ErrorActionPreference
             $ErrorActionPreference = "Continue"
             try {
-                winget install -e --id $pythonPackageId --accept-package-agreements --accept-source-agreements --force
+                winget install -e --id $pythonPackageId --source winget --accept-package-agreements --accept-source-agreements
                 $wingetExit = $LASTEXITCODE
             } catch { $wingetExit = 1 }
             $ErrorActionPreference = $prevEAP
             Refresh-SessionPath
+
+            # Re-detect after install (PATH may have changed)
             $DetectedPython = Find-CompatiblePython
+
+            if (-not $DetectedPython) {
+                # Python still not functional after winget -- force reinstall.
+                # This handles both real failures AND "already installed" codes where
+                # winget thinks Python is present but it's not actually on PATH
+                # (e.g. user partially uninstalled, or installed via a different method).
+                substep "Python not found on PATH after winget. Retrying with --force..." "Yellow"
+                $ErrorActionPreference = "Continue"
+                try {
+                    winget install -e --id $pythonPackageId --source winget --accept-package-agreements --accept-source-agreements --force
+                    $wingetExit = $LASTEXITCODE
+                } catch { $wingetExit = 1 }
+                $ErrorActionPreference = $prevEAP
+                Refresh-SessionPath
+                $DetectedPython = Find-CompatiblePython
+            }
+        }
+
+        # Fall back to python.org if winget is unavailable OR couldn't install a
+        # working Python (missing/broken winget, msstore cert errors --source
+        # winget can't fix). Keeps the install automatic instead of failing out.
+        if (-not $DetectedPython) {
+            if ($script:WingetAvailable) {
+                substep "winget could not install Python -- falling back to python.org..." "Yellow"
+            } else {
+                substep "winget is unavailable -- installing Python from python.org..." "Yellow"
+            }
+            $DetectedPython = Install-PythonFromPythonOrg
         }
 
         if (-not $DetectedPython) {
-            Write-Host "[ERROR] Python installation failed (exit code $wingetExit)" -ForegroundColor Red
+            $exitNote = if ($null -ne $wingetExit) { " (winget exit code $wingetExit)" } else { "" }
+            Write-Host "[ERROR] Python installation failed$exitNote" -ForegroundColor Red
             Write-Host "        Please install Python $PythonVersion manually from https://www.python.org/downloads/" -ForegroundColor Yellow
             Write-Host "        Make sure to check 'Add Python to PATH' during installation." -ForegroundColor Yellow
             Write-Host "        Then re-run this installer." -ForegroundColor Yellow
@@ -1054,7 +1181,7 @@ shell.Run cmd, 0, False
         if ($script:WingetAvailable) {
             $prevEAP = $ErrorActionPreference
             $ErrorActionPreference = "Continue"
-            try { winget install --id=astral-sh.uv -e --accept-package-agreements --accept-source-agreements } catch {}
+            try { winget install --id=astral-sh.uv -e --source winget --accept-package-agreements --accept-source-agreements } catch {}
             $ErrorActionPreference = $prevEAP
             Refresh-SessionPath
         }
@@ -1230,6 +1357,55 @@ shell.Run cmd, 0, False
         try { [System.IO.File]::WriteAllText((Join-Path $VenvDir ".unsloth-studio-owned"), "") } catch {}
     }
 
+    # ── Helper: run amd-smi without triggering a UAC elevation prompt ──
+    # amd-smi on Windows auto-elevates to read GPU/APU memory, surfacing a confusing
+    # DiskPart UAC prompt mid-install (Studio backend amd.py hits the same).
+    # __COMPAT_LAYER=RunAsInvoker forces it (and helpers it spawns) to run
+    # un-elevated; on failure the WMI name -> gfx fallback still resolves the arch.
+    function Invoke-AmdSmiNoElevate {
+        param(
+            [Parameter(Mandatory = $true, Position = 0)][string]$Exe,
+            [Parameter(Position = 1)][string[]]$SmiArgs = @(),
+            [int]$TimeoutSec = 30
+        )
+        # RunAsInvoker blocks the auto-elevation/UAC prompt; the timeout bounds a
+        # flaky amd-smi that can otherwise spin for minutes (30s mirrors amd.py).
+        $prevCompat = [Environment]::GetEnvironmentVariable('__COMPAT_LAYER', 'Process')
+        $env:__COMPAT_LAYER = 'RunAsInvoker'
+        try {
+            # [Process]::Start, NOT Start-Process -PassThru: the latter leaves
+            # .ExitCode $null after WaitForExit on PS 5.1, so $LASTEXITCODE (checked
+            # by callers) reads non-zero and kills detection. Async reads drain the
+            # pipes (no deadlock); amd-smi args have no spaces so a plain join is safe.
+            $psi = New-Object System.Diagnostics.ProcessStartInfo
+            $psi.FileName = $Exe
+            $psi.Arguments = ($SmiArgs -join ' ')
+            $psi.UseShellExecute = $false
+            $psi.RedirectStandardOutput = $true
+            $psi.RedirectStandardError = $true
+            $psi.CreateNoWindow = $true
+            $proc = [System.Diagnostics.Process]::Start($psi)
+            $outTask = $proc.StandardOutput.ReadToEndAsync()
+            $errTask = $proc.StandardError.ReadToEndAsync()
+            if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
+                try { $proc.Kill() } catch {}
+                $global:LASTEXITCODE = 124
+                return ""
+            }
+            $global:LASTEXITCODE = $proc.ExitCode
+            return ($outTask.Result + "`n" + $errTask.Result)
+        } catch {
+            $global:LASTEXITCODE = 1
+            return ""
+        } finally {
+            if ($null -eq $prevCompat) {
+                Remove-Item Env:__COMPAT_LAYER -ErrorAction SilentlyContinue
+            } else {
+                $env:__COMPAT_LAYER = $prevCompat
+            }
+        }
+    }
+
     # ── Detect GPU (robust: PATH + hardcoded fallback paths, mirrors setup.ps1) ──
     $HasNvidiaSmi = $false
     $NvidiaSmiExe = $null
@@ -1303,11 +1479,21 @@ shell.Run cmd, 0, False
                 }
             } catch {}
         }
-        if (-not $HasROCm) {
+        # On hosts without a working HIP runtime amd-smi elevates a child at runtime,
+        # popping a UAC/DiskPart prompt RunAsInvoker can't suppress (manifest is
+        # asInvoker). So only probe when a HIP SDK is present (hipinfo found ->
+        # un-elevated) or the user opts in; else fall through to WMI name inference
+        # (enough to pick ROCm wheels + lemonade llama.cpp).
+        # An explicit opt-out (UNSLOTH_ENABLE_AMD_SMI=0/false/no/off) wins over the
+        # HIP-SDK heuristic: a HIP SDK binary with a broken runtime can still pop the
+        # prompt, so $HipSdkInstalled must NOT silently re-enable it.
+        $amdSmiOptOut = $env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(0|false|no|off)$'
+        $amdSmiAllowed = (-not $amdSmiOptOut) -and ($HipSdkInstalled -or ($env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(1|true|yes|on)$'))
+        if (-not $HasROCm -and $amdSmiAllowed) {
             $amdSmiExe = Get-Command "amd-smi" -ErrorAction SilentlyContinue
             if ($amdSmiExe) {
                 try {
-                    $smiOut = & $amdSmiExe.Source list 2>&1 | Out-String
+                    $smiOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('list')
                     if ($LASTEXITCODE -eq 0 -and $smiOut -match "(?im)^GPU\s*[:\[]\s*\d") {
                         $HasROCm = $true
                         # Mirror the hipinfo path: collect all gfx tokens in enumeration
@@ -1322,7 +1508,7 @@ shell.Run cmd, 0, False
                             # Attempt 2: 'static --asic' exposes ASIC details on ROCm 6+,
                             # including the GFX target needed for wheel index selection.
                             $smiAsicOut = ""
-                            try { $smiAsicOut = & $amdSmiExe.Source static --asic 2>&1 | Out-String } catch {}
+                            try { $smiAsicOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('static','--asic') } catch {}
                             $_asicGfxTokens = @([regex]::Matches($smiAsicOut, "(?i)\b(gfx\d+[a-z]?)\b") | ForEach-Object { $_.Groups[1].Value.ToLower() })
                             if ($_asicGfxTokens.Count -gt 0) {
                                 $ROCmGfxArch = if ($_smiVisIdx -lt $_asicGfxTokens.Count) { $_asicGfxTokens[$_smiVisIdx] } else { $_asicGfxTokens[0] }
@@ -1346,9 +1532,12 @@ shell.Run cmd, 0, False
             } catch {}
         }
         # ── Arch resolution: env-var override → name inference ──────────────
-        # Covers users whose amd-smi is too old to report the GFX target and
-        # who don't have hipinfo (HIP-runtime-only, common on Strix Halo / iGPU).
-        if ($HasROCm -and -not $ROCmGfxArch) {
+        # Runs even when the hipinfo/amd-smi probe could NOT confirm a runtime
+        # ($HasROCm false): the gfx arch inferred from the WMI GPU name lets the
+        # studio setup forward --rocm-gfx and pull a GPU-accelerated (lemonade)
+        # llama.cpp, which bundles its own ROCm runtime. PyTorch's ROCm wheels
+        # still require a confirmed HIP SDK -- they stay gated on $HasROCm below.
+        if (-not $ROCmGfxArch) {
             # 1. Manual override: set UNSLOTH_ROCM_GFX_ARCH=gfx1151 before running.
             if ($env:UNSLOTH_ROCM_GFX_ARCH) {
                 $ROCmGfxArch = $env:UNSLOTH_ROCM_GFX_ARCH.Trim().ToLower()
@@ -1356,15 +1545,20 @@ shell.Run cmd, 0, False
                 substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $ROCmGfxArch" "Cyan"
             }
             # 2. Best-effort name → arch lookup from marketing name (amd-smi / WMI).
+            #    Targets only arches the lemonade-sdk ROCm prebuilts cover
+            #    (gfx120X/110X/1151/1150/103X); unknown names fall back to CPU.
             elseif ($ROCmGpuLabel) {
                 $nameArchTable = @(
-                    @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4
-                    @{ P = "9070|9060";                                            A = "gfx1200" }  # RDNA 4
-                    @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";  A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
-                    @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" } # RDNA 3.5 iGPU (Strix Point)
-                    @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                       A = "gfx1100" }  # RDNA 3 desktop
-                    @{ P = "RX 7600";                                              A = "gfx1102" }  # RDNA 3
-                    @{ P = "780M|760M|740M|Phoenix";                               A = "gfx1103" }  # RDNA 3 iGPU (Phoenix)
+                    @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4 (RX 9070 XT / 9080)
+                    @{ P = "9070|9060";                                           A = "gfx1200" }  # RDNA 4 (RX 9070 / 9060)
+                    @{ P = "8060S|8050S|8040S|Strix Halo|Ryzen AI Max|AI Max"; A = "gfx1151" }  # RDNA 3.5 (Strix Halo: Radeon 8060S/8050S/8040S iGPU, Ryzen AI Max+)
+                    @{ P = "890M|880M|860M|840M|Strix Point|Krackan|HX 37[05]|AI 9 HX|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]|AI 7 PRO 35|AI 5 33"; A = "gfx1150" }  # RDNA 3.5 (Strix/Krackan Point: Radeon 890M/880M iGPU, Ryzen AI 9 HX 370/375)
+                    @{ P = "RX 7900|RX 7800|RX 7700(?!S)|PRO W7900|PRO W7800|PRO W7700"; A = "gfx1100" }  # RDNA 3 desktop/workstation (Navi 31)
+                    @{ P = "RX 7600|RX 7700S|RX 7650|PRO W7600|PRO W7500|PRO V710"; A = "gfx1102" }  # RDNA 3 (Navi 33)
+                    @{ P = "780M|760M|740M|Phoenix|Hawk Point|Z1 Extreme|Z2 Extreme"; A = "gfx1103" }  # RDNA 3 iGPU (Phoenix / Hawk Point)
+                    @{ P = "RX 6900|RX 6800|RX 6750|RX 6700|PRO W6800|PRO W6900";  A = "gfx1030" }  # RDNA 2 (Navi 21) -- lemonade gfx103X
+                    @{ P = "RX 6650|RX 6600|PRO W6600|PRO W6650";                  A = "gfx1032" }  # RDNA 2 (Navi 23) -- lemonade gfx103X
+                    @{ P = "RX 6500|RX 6400|RX 6300|PRO W6400|PRO W6500";          A = "gfx1034" }  # RDNA 2 (Navi 24) -- lemonade gfx103X
                 )
                 foreach ($row in $nameArchTable) {
                     if ($ROCmGpuLabel -match $row.P) {
@@ -1405,11 +1599,11 @@ shell.Run cmd, 0, False
                     }
                 } catch {}
             }
-            if (-not $ROCmVersion) {
+            if (-not $ROCmVersion -and $amdSmiAllowed) {
                 $amdSmiVer = Get-Command "amd-smi" -ErrorAction SilentlyContinue
                 if ($amdSmiVer) {
                     try {
-                        $smiVerOut = & $amdSmiVer.Source version 2>&1 | Out-String
+                        $smiVerOut = Invoke-AmdSmiNoElevate $amdSmiVer.Source @('version')
                         if ($LASTEXITCODE -eq 0 -and $smiVerOut -match 'ROCm version:\s*(\d+\.\d+)') {
                             $ROCmVersion = $Matches[1]
                         }
@@ -1419,6 +1613,46 @@ shell.Run cmd, 0, False
         }
     }
 
+    # ── Optional WSL-ROCm driver hint ────────────────────────────────────────
+    # An AMD GPU can also be used inside WSL2, but only with Adrenalin >= 26.2.2
+    # (first production ROCDXG/WSL release); native Windows GPU works with any
+    # recent driver. We can't auto-install it (AMD referrer-gates downloads, no
+    # winget package), so just point at AMD's page. Shown only when the installed
+    # driver predates 26.2.2 (Feb 2026); suppress with UNSLOTH_SKIP_AMD_DRIVER_HINT=1.
+    function Show-AmdWslDriverHint {
+        if ($env:UNSLOTH_SKIP_AMD_DRIVER_HINT) { return }
+        try {
+            $amd = Get-CimInstance Win32_VideoController -ErrorAction SilentlyContinue |
+                Where-Object { $_.Name -match 'AMD|Radeon' } | Select-Object -First 1
+            if (-not $amd) { return }
+            $drvDate = $null
+            try {
+                if ($amd.DriverDate -is [datetime]) {
+                    # Get-CimInstance returns DriverDate already parsed.
+                    $drvDate = $amd.DriverDate
+                } elseif ($amd.DriverDate) {
+                    # Get-WmiObject style WMI datetime string.
+                    $drvDate = [Management.ManagementDateTimeConverter]::ToDateTime([string]$amd.DriverDate)
+                }
+            } catch {}
+            # Older than 26.2.2 (Feb 2026) => can't expose the GPU to WSL ROCm.
+            # Unreadable date => still show the hint (informational, suppressible).
+            if ($drvDate -and $drvDate -ge (Get-Date '2026-02-01')) { return }
+            substep "Tip: to use this GPU inside WSL too, install AMD Adrenalin 26.2.2+ (for WSL2)." "Cyan"
+            substep "  Your current driver predates it; native Windows GPU is unaffected. Get it from AMD:" "Cyan"
+            substep "    https://www.amd.com/en/resources/support-articles/release-notes/RN-RAD-WIN-26-2-2.html" "Cyan"
+            substep "  Then reboot and run this installer inside an Ubuntu-24.04 WSL distro." "Cyan"
+            # If WSL isn't installed yet, point at the command that provisions it
+            # (best-effort; wsl.exe absent => no WSL).
+            $hasWsl = $false
+            try { $hasWsl = [bool](Get-Command wsl.exe -ErrorAction SilentlyContinue) } catch {}
+            if (-not $hasWsl) {
+                substep "  No WSL yet? Install it first:  wsl --install -d Ubuntu-24.04" "Cyan"
+            }
+            substep "  (suppress: set UNSLOTH_SKIP_AMD_DRIVER_HINT=1)" "Cyan"
+        } catch {}
+    }
+
     if ($HasNvidiaSmi) {
         step "gpu" "NVIDIA GPU detected"
     } elseif ($HasROCm) {
@@ -1435,15 +1669,24 @@ shell.Run cmd, 0, False
         substep "       This is a driver issue, not an SDK issue." "Yellow"
         substep "       Ensure the ROCm compute driver is installed alongside the display driver:" "Yellow"
         substep "       https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+    } elseif ($ROCmGfxArch) {
+        # Known arch: Studio setup installs AMD's bundled-runtime ROCm PyTorch wheels
+        # (repo.amd.com), which ship their own runtime -- HIP SDK optional.
+        step "gpu" "AMD ROCm ($ROCmGfxArch)" "Cyan"
+        substep "Detected: $ROCmGpuLabel" "Cyan"
+        substep "GPU PyTorch uses AMD's bundled-runtime ROCm wheels -- HIP SDK not required (optional)." "Cyan"
     } elseif ($ROCmGpuLabel) {
-        step "gpu" "AMD GPU detected -- HIP SDK not found" "Yellow"
+        step "gpu" "AMD GPU detected -- arch unknown" "Yellow"
         substep "Detected: $ROCmGpuLabel" "Yellow"
-        substep "Install the HIP SDK for ROCm GPU inference:" "Yellow"
+        substep "Could not determine the GPU arch -- install the HIP SDK or set" "Yellow"
+        substep "UNSLOTH_ROCM_GFX_ARCH to enable GPU ROCm PyTorch:" "Yellow"
         substep "https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
     } else {
         step "gpu" "none (chat-only / GGUF)" "Yellow"
         substep "Training and GPU inference require an NVIDIA or AMD ROCm GPU." "Yellow"
     }
+    # On an AMD GPU (no NVIDIA), surface the optional WSL-ROCm driver hint.
+    if (-not $HasNvidiaSmi -and ($ROCmGfxArch -or $ROCmGpuLabel)) { Show-AmdWslDriverHint }
 
     # ── Choose the correct PyTorch index URL based on driver CUDA version ──
     # Mirrors Get-PytorchCudaTag in setup.ps1.
@@ -1529,16 +1772,24 @@ shell.Run cmd, 0, False
     # ── Print CPU-only hint when no GPU detected ──
     if (-not $SkipTorch -and -not $ROCmIndexUrl -and $TorchIndexUrl -like "*/cpu") {
         Write-Host ""
-        if ($HipSdkInstalled -and -not $HasROCm) {
-            substep "Installing CPU-only PyTorch (HIP SDK found but GPU not ROCm-accessible)." "Yellow"
-        } elseif ($ROCmGpuLabel) {
-            substep "Installing CPU-only PyTorch (ROCm wheels require the HIP SDK)." "Yellow"
+        if ($ROCmGfxArch) {
+            # Known AMD arch: install.ps1 lays down CPU PyTorch as a base, then
+            # setup.ps1 swaps in AMD's bundled-runtime GPU ROCm wheels (no HIP SDK).
+            substep "Installing CPU PyTorch as a base -- Studio setup installs GPU ROCm" "Cyan"
+            substep "wheels for $ROCmGfxArch next (bundled runtime; HIP SDK not required)." "Cyan"
         } else {
-            substep "No NVIDIA GPU detected." "Yellow"
+            if ($HipSdkInstalled -and -not $HasROCm) {
+                substep "Installing CPU-only PyTorch (HIP SDK found but GPU not ROCm-accessible)." "Yellow"
+            } elseif ($ROCmGpuLabel) {
+                substep "Installing CPU-only PyTorch (AMD GPU arch unknown -- install the HIP SDK" "Yellow"
+                substep "or set UNSLOTH_ROCM_GFX_ARCH to enable GPU ROCm)." "Yellow"
+            } else {
+                substep "No NVIDIA GPU detected." "Yellow"
+            }
+            substep "Installing CPU-only PyTorch. If you only need GGUF chat/inference," "Yellow"
+            substep "re-run with --no-torch for a faster, lighter install:" "Yellow"
+            substep ".\install.ps1 --no-torch" "Yellow"
         }
-        substep "Installing CPU-only PyTorch. If you only need GGUF chat/inference," "Yellow"
-        substep "re-run with --no-torch for a faster, lighter install:" "Yellow"
-        substep ".\install.ps1 --no-torch" "Yellow"
         Write-Host ""
     }
 
diff --git a/install.sh b/install.sh
index d7de8a946d..af74410397 100755
--- a/install.sh
+++ b/install.sh
@@ -1207,6 +1207,15 @@ STUB_EOF
         # Escape single quotes for PowerShell single-quoted string embedding
         _css_sc_args_ps=$(printf '%s' "$_css_sc_args" | sed "s/'/''/g")
 
+        # DISTINCT shortcut name so the WSL launcher never clobbers a native
+        # install's "Unsloth Studio.lnk" in the same folder. Per-distro suffix.
+        if [ -n "$_css_distro" ]; then
+            _css_lnk_name="Unsloth Studio (WSL - ${_css_distro}).lnk"
+        else
+            _css_lnk_name="Unsloth Studio (WSL).lnk"
+        fi
+        _css_lnk_name_ps=$(printf '%s' "$_css_lnk_name" | sed "s/'/''/g")
+
         # Create shortcuts via a temp PowerShell script to avoid escaping issues
         _css_ps1_tmp=$(mktemp /tmp/unsloth-shortcut-XXXXXX.ps1 2>/dev/null) || true
         if [ -n "$_css_ps1_tmp" ]; then
@@ -1214,19 +1223,57 @@ STUB_EOF
 \$WshShell = New-Object -ComObject WScript.Shell
 \$targetExe = (Get-Command '$_css_sc_target' -ErrorAction SilentlyContinue).Source
 if (-not \$targetExe) { exit 1 }
+# Best-effort: fetch the Unsloth icon to a stable Windows path (shared with a
+# native install if one exists) so the WSL shortcut shows the proper icon.
+\$iconDir = Join-Path \$env:LOCALAPPDATA 'Unsloth Studio'
+\$iconPath = Join-Path \$iconDir 'unsloth.ico'
+if (-not (Test-Path -LiteralPath \$iconPath)) {
+    try {
+        New-Item -ItemType Directory -Force -Path \$iconDir | Out-Null
+        Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/unslothai/unsloth/main/studio/frontend/public/unsloth.ico' -OutFile \$iconPath -UseBasicParsing -ErrorAction Stop
+    } catch {}
+}
+\$hasIcon = \$false
+if (Test-Path -LiteralPath \$iconPath) {
+    try { \$b = [System.IO.File]::ReadAllBytes(\$iconPath); if (\$b.Length -ge 4 -and \$b[0] -eq 0 -and \$b[1] -eq 0 -and \$b[2] -eq 1 -and \$b[3] -eq 0) { \$hasIcon = \$true } } catch {}
+}
 \$locations = @(
     [Environment]::GetFolderPath('Desktop'),
     (Join-Path \$env:APPDATA 'Microsoft\Windows\Start Menu\Programs')
 )
+\$created = @()
 foreach (\$dir in \$locations) {
     if (-not \$dir -or -not (Test-Path \$dir)) { continue }
-    \$linkPath = Join-Path \$dir 'Unsloth Studio.lnk'
+    \$linkPath = Join-Path \$dir '$_css_lnk_name_ps'
     \$shortcut = \$WshShell.CreateShortcut(\$linkPath)
     \$shortcut.TargetPath = \$targetExe
     \$shortcut.Arguments = '$_css_sc_args_ps'
-    \$shortcut.Description = 'Launch Unsloth Studio'
+    \$shortcut.Description = 'Launch Unsloth Studio (WSL)'
+    if (\$hasIcon) { \$shortcut.IconLocation = "\$iconPath,0" }
     \$shortcut.Save()
+    \$created += \$linkPath
 }
+# Force Explorer to re-read EACH new shortcut's icon so it renders immediately
+# instead of a stale/blank (generic) icon. The reliable, NON-disruptive fix
+# (no explorer restart) is a PER-ITEM SHChangeNotify(SHCNE_UPDATEITEM,
+# SHCNF_PATHW, <lnk>) -- the global SHCNE_ASSOCCHANGED alone does not recover a
+# stale item. Also clear the on-disk icon cache for heavier staleness.
+try { & "\$env:SystemRoot\System32\ie4uinit.exe" -ClearIconCache } catch {}
+try { & "\$env:SystemRoot\System32\ie4uinit.exe" -show } catch {}
+try {
+    Add-Type -Namespace UnslothShell -Name IconRefresh -MemberDefinition '[System.Runtime.InteropServices.DllImport("shell32.dll", CharSet = System.Runtime.InteropServices.CharSet.Unicode)] public static extern void SHChangeNotify(int e, uint f, string a, System.IntPtr b);' -ErrorAction SilentlyContinue
+    foreach (\$p in \$created) { try { [UnslothShell.IconRefresh]::SHChangeNotify(0x00002000, 0x0005, \$p, [System.IntPtr]::Zero) } catch {} }
+    [UnslothShell.IconRefresh]::SHChangeNotify(0x08000000, 0, \$null, [System.IntPtr]::Zero)
+} catch {}
+# Win11 Start Menu keeps its own tile-icon cache (preserve start2.bin).
+try {
+    \$smeh = Join-Path \$env:LOCALAPPDATA 'Packages\Microsoft.Windows.StartMenuExperienceHost_cw5n1h2txyewy\TempState'
+    if (Test-Path -LiteralPath \$smeh) {
+        Get-ChildItem -LiteralPath \$smeh -Filter 'TileCache_*' -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath (Join-Path \$smeh 'StartUnifiedTileModelCache.dat') -Force -ErrorAction SilentlyContinue
+        Stop-Process -Name StartMenuExperienceHost -Force -ErrorAction SilentlyContinue
+    }
+} catch {}
 WSLPS1_EOF
 
             # Convert WSL path to Windows path for powershell.exe
@@ -1236,6 +1283,13 @@ WSLPS1_EOF
             fi
             rm -f "$_css_ps1_tmp"
         fi
+        # If WSL interop is disabled (powershell.exe "Exec format error"), the
+        # shortcut wasn't created; tell the user how to launch / re-enable it.
+        if [ "$_css_created" -ne 1 ]; then
+            substep "Couldn't create the Windows shortcut (WSL interop may be disabled)." "$C_WARN"
+            substep "  Launch Studio from Windows:  wsl -d \"$_css_distro\" -- bash -lc 'unsloth studio'" "$C_WARN"
+            substep "  (re-enable shortcuts: turn WSL interop back on, e.g. run 'wsl --shutdown' then reopen WSL.)" "$C_WARN"
+        fi
     fi
 
     if [ "$_css_created" -eq 1 ]; then
@@ -1650,9 +1704,21 @@ _find_no_torch_runtime() {
 }
 
 # ── AMD ROCm GPU detection helper ──
+# WSL2 ROCDXG: the system rocminfo enumerates the GPU over /dev/dxg only when
+# HSA_ENABLE_DXG_DETECTION=1 (a no-op on bare metal), and /opt/rocm/bin can be
+# off PATH outside login shells (the profile.d drop-in). Seed both before any
+# rocminfo probe or a ROCDXG WSL host is misdetected as CPU-only.
+_ensure_rocm_probe_env() {
+    export HSA_ENABLE_DXG_DETECTION="${HSA_ENABLE_DXG_DETECTION:-1}"
+    if ! command -v rocminfo >/dev/null 2>&1 && [ -x /opt/rocm/bin/rocminfo ]; then
+        PATH="$PATH:/opt/rocm/bin"
+    fi
+}
+
 # Returns 0 if an AMD GPU is present. Checks rocminfo, amd-smi, then sysfs
 # KFD topology (env-var-independent fallback for when HIP/ROCR_VISIBLE_DEVICES hides devices).
 _has_amd_rocm_gpu() {
+    _ensure_rocm_probe_env
     if command -v rocminfo >/dev/null 2>&1 && \
        rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
         return 0
@@ -1914,6 +1980,122 @@ _pick_radeon_wheel() {
     esac
 }
 
+# ── ROCm-on-WSL bootstrap for AMD Strix Halo (gfx1151) ───────────────────────
+# No-op everywhere except: WSL + GPU wanted + no usable GPU yet + /dev/dxg +
+# Strix Halo APU. Every other config (NVIDIA, native-Linux ROCm, macOS, Windows,
+# CPU, non-Strix WSL) skips it and normal detection runs unchanged. NEVER aborts
+# the installer -- always returns 0. Runs the idempotent helper (ROCm 7.2 +
+# librocdxg), then sources the env it persisted so detection finds the GPU.
+_maybe_bootstrap_rocm_wsl() {
+    [ "${OS:-}" = "wsl" ] || return 0
+    [ "${SKIP_TORCH:-false}" = "false" ] || return 0
+    [ "${UNSLOTH_SKIP_ROCM_WSL_SETUP:-0}" = "1" ] && return 0
+    # Leave any already-usable GPU completely alone (NVIDIA, or working ROCm).
+    if _has_usable_nvidia_gpu; then return 0; fi
+    # "Usable ROCm" here = rocminfo enumerates the gfx1151 agent. Don't use the
+    # generic _has_amd_rocm_gpu: its broad gfx match accepts "gfx11-generic" and
+    # would skip this bootstrap while the real GPU is still unusable. awk consumes
+    # all input, so rocminfo isn't SIGPIPE'd like `grep -q` would under pipefail.
+    _ensure_rocm_probe_env
+    if command -v rocminfo >/dev/null 2>&1 && \
+       rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx1151/{found=1} END{exit !found}'; then
+        return 0
+    fi
+    # WSL GPU passthrough device must exist (present on any WSL2 GPU host).
+    [ -e /dev/dxg ] || return 0
+    # Only Strix Halo (gfx1151): rocminfo can't tell us the arch yet, so match
+    # the CPU model string WSL exposes (e.g. "AMD Ryzen AI Max+ ... Radeon 8060S").
+    grep -qiE 'Ryzen AI Max|Radeon 80[0-9]0S|Strix Halo' /proc/cpuinfo 2>/dev/null || return 0
+    command -v bash >/dev/null 2>&1 || return 0
+
+    # Fast path: already configured (librocdxg present) but launched from a
+    # non-login shell so the persisted env wasn't loaded -- just load it.
+    if [ -e /opt/rocm/lib/librocdxg.so ] || [ -e /opt/rocm/lib64/librocdxg.so ]; then
+        if [ -r /etc/profile.d/unsloth-rocm-wsl.sh ]; then
+            # shellcheck disable=SC1091
+            . /etc/profile.d/unsloth-rocm-wsl.sh || true
+        else
+            # librocdxg present but the env drop-in is gone (e.g. a Studio
+            # uninstall removed it while keeping shared ROCm). Restore the FULL
+            # env inline (so rocminfo is on PATH) and recreate the drop-in.
+            _rw_rocm=/opt/rocm
+            export HSA_ENABLE_DXG_DETECTION=1
+            export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1
+            export PATH="${_rw_rocm}/bin:${PATH}"
+            export LD_LIBRARY_PATH="${_rw_rocm}/lib:${LD_LIBRARY_PATH:-}"
+            # Persist the drop-in so later non-login Studio launches get the env
+            # too. /etc/profile.d is root-owned: a plain redirect fails for a
+            # non-root reinstall (ROCm would silently disappear after this shell),
+            # so tee through sudo when not root. Best-effort -- the current shell
+            # already has the env, so the install proceeds either way.
+            _rw_dropin="$(
+                printf '# >>> Unsloth ROCm-on-WSL (gfx1151) >>>\n'
+                printf 'export HSA_ENABLE_DXG_DETECTION=1\n'
+                printf 'export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1\n'
+                printf 'export PATH="%s/bin:${PATH}"\n' "${_rw_rocm}"
+                printf 'export LD_LIBRARY_PATH="%s/lib:${LD_LIBRARY_PATH:-}"\n' "${_rw_rocm}"
+                printf '# <<< Unsloth ROCm-on-WSL (gfx1151) <<<\n'
+            )"
+            if [ "$(id -u)" = "0" ]; then
+                printf '%s\n' "$_rw_dropin" > /etc/profile.d/unsloth-rocm-wsl.sh 2>/dev/null || true
+            elif command -v sudo >/dev/null 2>&1; then
+                printf '%s\n' "$_rw_dropin" | sudo tee /etc/profile.d/unsloth-rocm-wsl.sh >/dev/null 2>&1 || true
+            fi
+        fi
+        return 0
+    fi
+
+    echo ""
+    substep "Detected AMD Strix Halo (Radeon 8000S) in WSL with no ROCm runtime yet." "$C_WARN"
+    substep "Setting up ROCm-on-WSL (ROCm 7.2 + librocdxg) automatically to enable this GPU."
+    substep "One-time, uses sudo and a large download. (skip: re-run with UNSLOTH_SKIP_ROCM_WSL_SETUP=1)"
+
+    # Locate the helper: prefer the copy shipped beside install.sh, else fetch it.
+    _rw_helper="${_REPO_ROOT:-.}/scripts/install_rocm_wsl_strixhalo.sh"
+    _rw_tmp=""
+    if [ ! -r "$_rw_helper" ]; then
+        _rw_tmp="$(mktemp 2>/dev/null || echo /tmp/_unsloth_rocm_wsl.sh)"
+        if download "https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/install_rocm_wsl_strixhalo.sh" "$_rw_tmp" 2>/dev/null; then
+            _rw_helper="$_rw_tmp"
+        else
+            substep "Could not fetch the ROCm-on-WSL helper; using CPU fallback." "$C_WARN"
+            [ -n "$_rw_tmp" ] && rm -f "$_rw_tmp"
+            return 0
+        fi
+    fi
+
+    # Consent: the narrow guarded case is exactly the GPU setup the user ran the
+    # installer for, so it proceeds AUTOMATICALLY by default (works with no TTY,
+    # e.g. `curl ... | sh`). Opt out via UNSLOTH_SKIP_ROCM_WSL_SETUP=1 (top of
+    # function). The Tauri app drives its own consent UI, so under TAURI_MODE it
+    # only runs when the app passes UNSLOTH_ROCM_WSL_AUTO=1; else surface and wait.
+    _rw_go=1
+    if [ "${TAURI_MODE:-false}" = "true" ] && [ "${UNSLOTH_ROCM_WSL_AUTO:-0}" != "1" ]; then
+        tauri_log "ROCM_WSL_AVAILABLE" "strixhalo"
+        substep "Enable the GPU from the desktop app (or set UNSLOTH_ROCM_WSL_AUTO=1)." "$C_WARN"
+        _rw_go=0
+    fi
+
+    if [ "$_rw_go" = "1" ]; then
+        # Helper does its own sudo + is idempotent. SMOKE_TEST=0: install.sh
+        # installs torch itself right after, into the real venv.
+        if UNSLOTH_WSL_SMOKE_TEST=0 bash "$_rw_helper"; then
+            # Pull the helper's persisted env into THIS shell so detection
+            # (rocminfo) now enumerates the GPU and routes to gfx1151.
+            if [ -r /etc/profile.d/unsloth-rocm-wsl.sh ]; then
+                # shellcheck disable=SC1091
+                . /etc/profile.d/unsloth-rocm-wsl.sh || true
+            fi
+            substep "ROCm-on-WSL ready; continuing with GPU install." "$C_OK"
+        else
+            substep "ROCm-on-WSL setup did not complete; falling back to CPU-only." "$C_WARN"
+        fi
+    fi
+    [ -n "$_rw_tmp" ] && rm -f "$_rw_tmp"
+    return 0
+}
+_maybe_bootstrap_rocm_wsl || true
+
 TORCH_INDEX_URL=$(get_torch_index_url)
 
 # rocm7.2 ships torch 2.11.0 -- adjust the constraint to allow it.
@@ -2018,6 +2200,7 @@ if _has_usable_nvidia_gpu; then
     step "gpu" "NVIDIA GPU detected"
 elif case "$TORCH_INDEX_URL" in */rocm*|*/gfx*) true ;; *) false ;; esac; then
     # Probe gfx arch for the display label, honouring HIP_VISIBLE_DEVICES
+    _ensure_rocm_probe_env
     _gpu_disp_gfx_all=""
     _gpu_disp_mkt=""
     if command -v rocminfo >/dev/null 2>&1; then
@@ -2048,14 +2231,20 @@ elif case "$TORCH_INDEX_URL" in */rocm*|*/gfx*) true ;; *) false ;; esac; then
         substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $_gpu_disp_gfx"
     # Name-based arch inference when tools don't report gfx (mirrors install.ps1 nameArchTable)
     elif [ -z "$_gpu_disp_gfx" ] && [ -n "$_gpu_disp_mkt" ]; then
+        # Kept in sync with the nameArchTable in install.ps1 / setup.ps1.
+        # gfx1102 matched BEFORE gfx1100 so the spaceless "RX 7700S" lands on
+        # gfx1102 (bash case has no negative lookahead like the PS tables).
         case "$_gpu_disp_mkt" in
-            *"9070 XT"*|*9080*)                                                     _gpu_disp_gfx="gfx1201" ;;  # RDNA 4
-            *9070*|*9060*)                                                          _gpu_disp_gfx="gfx1200" ;;  # RDNA 4
-            *"8060S"*|*"890M"*|*"Strix Halo"*|*"HX 37"*|*"HX 38"*|*"AI 9 HX"*)  _gpu_disp_gfx="gfx1151" ;;  # RDNA 3.5 iGPU
-            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)        _gpu_disp_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
-            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                  _gpu_disp_gfx="gfx1100" ;;  # RDNA 3 desktop
-            *"RX 7600"*)                                                           _gpu_disp_gfx="gfx1102" ;;  # RDNA 3
-            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                               _gpu_disp_gfx="gfx1103" ;;  # RDNA 3 iGPU
+            *"9070 XT"*|*9080*)                                                                            _gpu_disp_gfx="gfx1201" ;;  # RDNA 4
+            *9070*|*9060*)                                                                                 _gpu_disp_gfx="gfx1200" ;;  # RDNA 4
+            *"8060S"*|*"8050S"*|*"8040S"*|*"Strix Halo"*|*"Ryzen AI Max"*|*"AI Max"*) _gpu_disp_gfx="gfx1151" ;;  # RDNA 3.5 (Strix Halo: Radeon 8060S/8050S/8040S iGPU, Ryzen AI Max+)
+            *"890M"*|*"880M"*|*"860M"*|*"840M"*|*"Strix Point"*|*"Krackan"*|*"HX 37"*|*"AI 9 HX"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*|*"AI 7 PRO 35"*|*"AI 5 33"*) _gpu_disp_gfx="gfx1150" ;;  # RDNA 3.5 (Strix/Krackan Point: Radeon 890M/880M iGPU, Ryzen AI 9 HX 370/375)
+            *"RX 7600"*|*"RX 7700S"*|*"RX 7650"*|*"PRO W7600"*|*"PRO W7500"*|*"PRO V710"*)                  _gpu_disp_gfx="gfx1102" ;;  # RDNA 3 (Navi 33)
+            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*|*"PRO W7900"*|*"PRO W7800"*|*"PRO W7700"*)                  _gpu_disp_gfx="gfx1100" ;;  # RDNA 3 desktop / workstation (Navi 31)
+            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*|*"Hawk Point"*|*"Z1 Extreme"*|*"Z2 Extreme"*)            _gpu_disp_gfx="gfx1103" ;;  # RDNA 3 iGPU (Phoenix / Hawk Point)
+            *"RX 6900"*|*"RX 6800"*|*"RX 6750"*|*"RX 6700"*|*"PRO W6800"*|*"PRO W6900"*)                    _gpu_disp_gfx="gfx1030" ;;  # RDNA 2 (Navi 21)
+            *"RX 6650"*|*"RX 6600"*|*"PRO W6600"*|*"PRO W6650"*)                                            _gpu_disp_gfx="gfx1032" ;;  # RDNA 2 (Navi 23)
+            *"RX 6500"*|*"RX 6400"*|*"RX 6300"*|*"PRO W6400"*|*"PRO W6500"*)                                _gpu_disp_gfx="gfx1034" ;;  # RDNA 2 (Navi 24)
         esac
         if [ -n "$_gpu_disp_gfx" ]; then
             substep "gfx arch inferred from GPU name: $_gpu_disp_gfx"
@@ -2089,7 +2278,34 @@ case "$TORCH_INDEX_URL" in
     */cpu)
         if [ "$SKIP_TORCH" = false ] && [ "$OS" != "macos" ]; then
             substep "No GPU detected -- installing CPU-only PyTorch." "$C_WARN"
-            substep "AMD ROCm users: see https://docs.unsloth.ai/get-started/install-and-update/amd"
+            if [ "$OS" = "wsl" ]; then
+                # WSL + no GPU detected (detection above found nothing). Common
+                # cause: an AMD GPU whose ROCm-on-WSL runtime isn't exposed yet --
+                # /dev/dxg present (graphics) but no ROCm runtime.
+                _wsl_ubu_ver=""
+                [ -r /etc/os-release ] && _wsl_ubu_ver=$(. /etc/os-release 2>/dev/null; printf '%s' "${VERSION_ID:-}")
+                if [ -e /dev/dxg ]; then
+                    substep "A GPU is plumbed into WSL (/dev/dxg) but no ROCm runtime is exposed to it." "$C_WARN"
+                fi
+                substep "For an AMD GPU, ROCm-on-WSL currently needs ALL of:"
+                substep "  1. AMD Adrenalin Edition 26.1.1+ on Windows (26.2.2+ for Strix Halo / Ryzen AI Max+)."
+                substep "     Older drivers lack production ROCDXG/WSL support, so ROCm can't see the GPU."
+                substep "     Get it from AMD (open in a browser -- direct downloads are referrer-gated):"
+                substep "       https://www.amd.com/en/resources/support-articles/release-notes/RN-RAD-WIN-26-2-2.html"
+                substep "  2. ROCm 7.2.1 + librocdxg inside WSL (with HSA_ENABLE_DXG_DETECTION=1)."
+                substep "  3. A WSL distro AMD supports for ROCm -- Ubuntu 24.04 is the known-good one."
+                if [ -n "$_wsl_ubu_ver" ] && [ "$_wsl_ubu_ver" != "24.04" ]; then
+                    substep "  This distro is Ubuntu $_wsl_ubu_ver, which AMD may not support for ROCm-on-WSL yet." "$C_WARN"
+                fi
+                substep "Set up the GPU in WSL with a dedicated Ubuntu 24.04 distro:"
+                substep "  wsl --install Ubuntu-24.04        # run in Windows PowerShell, then reopen WSL"
+                substep "  # then re-run this installer inside Ubuntu-24.04 -- it will detect the GPU."
+                substep "AMD ROCm-on-WSL docs: https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/"
+                substep "Strix Halo (gfx1151): this installer auto-offers ROCm-on-WSL setup once the"
+                substep "  driver is current; or run unsloth/scripts/install_rocm_wsl_strixhalo.sh yourself."
+            else
+                substep "AMD ROCm users: see https://docs.unsloth.ai/get-started/install-and-update/amd"
+            fi
             substep "Re-run with --no-torch for GGUF-only (faster, no PyTorch):"
             substep "  curl -fsSL https://unsloth.ai/install.sh | sh -s -- --no-torch"
         fi
diff --git a/scripts/install_rocm_wsl_strixhalo.sh b/scripts/install_rocm_wsl_strixhalo.sh
new file mode 100644
index 0000000000..5ef9ee386a
--- /dev/null
+++ b/scripts/install_rocm_wsl_strixhalo.sh
@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+#
+# ──────────────────────────────────────────────────────────────────────────────
+# Enable ROCm-on-WSL for AMD Strix Halo (Radeon 8060S / gfx1151)
+# ──────────────────────────────────────────────────────────────────────────────
+# install.sh already routes gfx1151 to the right ROCm wheels once a ROCm runtime
+# is present; what it does NOT do is install AMD's ROCm userspace + the WSL DXG
+# bridge. This helper automates that Linux-side prerequisite on Ubuntu 24.04
+# WSL2 and is invoked by install.sh when it sees a Strix Halo APU in WSL (via
+# /dev/dxg) but no ROCm runtime yet. Fully idempotent (re-run just re-verifies).
+#
+# Manual, admin-gated Windows prerequisite: an AMD Adrenalin driver with
+# production ROCDXG/WSL support (26.2.2+). install.ps1 offers to update it. Once
+# installed + rebooted, /dev/dxg is exposed to WSL and this script builds the rest.
+#
+# HOW ROCDXG WORKS (and why older /usr/lib/wsl/lib notes are wrong): librocdxg.so
+# is AMD's user-mode bridge between the Linux HSA runtime and the Windows driver
+# over /dev/dxg. The STANDARD hsa-rocr runtime (NOT the gone "roc4wsl" package)
+# loads it when HSA_ENABLE_DXG_DETECTION=1. No hsa/rocm libs need injecting into
+# /usr/lib/wsl/lib (it holds only d3d12/dxcore), yet rocminfo enumerates gfx1151
+# fine -- so we gate on /dev/dxg, not on WSL lib injection.
+#
+# KNOWN CAVEAT (ROCm/ROCm#6022): librocdxg can cap usable ROCm VRAM at the WSL
+# VM's RAM (.wslconfig [wsl2] memory=) on some BIOS UMA layouts, and amd-smi
+# doesn't work in WSL. On OOM below capacity, raise memory= (then wsl --shutdown)
+# and watch GPU use from Windows. Large-UMA BIOS exposes the full pool regardless.
+#
+# Verified on Ryzen AI Max+ PRO 395 / Radeon 8060S (gfx1151) with ROCm 7.2.1 +
+# Ubuntu 24.04 + WSL2 + Adrenalin. These pins MOVE; bump + re-verify on newer ROCm.
+# ──────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Tunables (override via env) ──────────────────────────────────────────────
+ROCM_VER="${UNSLOTH_WSL_ROCM_VER:-7.2.1}"            # ROCm release to install
+GFX="gfx1151"
+LIBROCDXG_REF="${UNSLOTH_LIBROCDXG_REF:-develop}"    # ROCm/librocdxg git ref to build
+# AMD's gfx1151 wheel index (same one install.sh uses); only for the smoke test.
+TORCH_INDEX="${UNSLOTH_AMD_ROCM_MIRROR:-https://repo.amd.com/rocm/whl}/${GFX}/"
+# Optional torch smoke test (throwaway venv). OFF by default: install.sh installs
+# torch itself into the real venv right after, so a duplicate download is wasteful.
+SMOKE_TEST="${UNSLOTH_WSL_SMOKE_TEST:-0}"
+# REQUIRED constraint -- without it pip prefers PyPI's newer CUDA torch over the
+# gfx1151 ROCm wheel. 2.11 carries AMD's real gfx1151 fix (matches install.sh).
+TORCH_CONSTRAINT="${UNSLOTH_WSL_TORCH_CONSTRAINT:-torch>=2.11.0,<2.12.0}"
+ROCM_DIR=""                                          # resolved after install
+
+say()  { printf '\n\033[1;36m== %s\033[0m\n' "$*"; }
+note() { printf '   %s\n' "$*"; }
+die()  { printf '\n\033[1;31m[BLOCKED] %s\033[0m\n' "$*" >&2; exit 1; }
+
+# sudo only if not already root (WSL distros often run as root)
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then
+    command -v sudo >/dev/null 2>&1 || die "Need root or sudo to install ROCm."
+    SUDO="sudo"
+fi
+
+# ── Windows 11 SDK (headers for the librocdxg build) ─────────────────────────
+# librocdxg's cmake build needs the Windows SDK 'shared' headers, which live on
+# the Windows HOST under C:\Program Files (x86)\Windows Kits\10\Include\<ver>\.
+_WIN_SDK_INC_BASE="/mnt/c/Program Files (x86)/Windows Kits/10/Include"
+
+# Print the newest installed SDK include dir with 'shared' headers, or nothing.
+# find + read loop (not `for ... in $(ls)`) since the base path has a space.
+_find_win_sdk() {
+    [ -d "$_WIN_SDK_INC_BASE" ] || return 0
+    while IFS= read -r _inc; do
+        [ -n "$_inc" ] || continue
+        if [ -d "$_inc/shared" ]; then printf '%s' "$_inc"; return 0; fi
+    done < <(find "$_WIN_SDK_INC_BASE" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort -Vr)
+    return 0
+}
+
+# Best-effort: install the Windows 11 SDK on the Windows HOST via winget so the
+# build has its headers with no manual step. Elevates -> ONE UAC prompt; headers
+# appear under /mnt/c immediately (no reboot). Never fatal -- failure falls
+# through to a manual-install message. Opt out: UNSLOTH_SKIP_WIN_SDK_INSTALL=1.
+_install_windows_sdk_via_winget() {
+    [ "${UNSLOTH_SKIP_WIN_SDK_INSTALL:-0}" = "1" ] && { note "Skipping Windows SDK auto-install (UNSLOTH_SKIP_WIN_SDK_INSTALL=1)."; return 0; }
+    command -v powershell.exe >/dev/null 2>&1 || return 0
+    # `command -v` succeeds even with WSL interop OFF (.exe on PATH but fails
+    # with "Exec format error"); verify it actually executes.
+    powershell.exe -NoProfile -Command "exit 0" >/dev/null 2>&1 || return 0
+    if ! powershell.exe -NoProfile -Command "if (Get-Command winget -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }" >/dev/null 2>&1; then
+        note "winget not available on the Windows host -- cannot auto-install the Windows SDK."
+        return 0
+    fi
+    say "Installing the Windows 11 SDK on the Windows host via winget"
+    note "librocdxg needs its headers. Approve the UAC prompt on the Windows desktop."
+    note "One-time (~1-3 GB download); opt out with UNSLOTH_SKIP_WIN_SDK_INSTALL=1."
+    # Newest SDK first, then a fallback. Header presence is the source of truth
+    # (re-check each attempt), not winget's exit code. </dev/null so winget never
+    # consumes a piped `curl | sh` stdin.
+    for _sdk_id in Microsoft.WindowsSDK.10.0.26100 Microsoft.WindowsSDK.10.0.22621; do
+        note "winget install ${_sdk_id} ..."
+        # --source winget: pin the community source so a broken default msstore
+        # source (the cert failure this PR fixes) can't abort SDK resolution.
+        powershell.exe -NoProfile -Command "winget install --id ${_sdk_id} -e --source winget --accept-source-agreements --accept-package-agreements --disable-interactivity" </dev/null || true
+        if [ -n "$(_find_win_sdk)" ]; then
+            note "Windows SDK headers present after install."
+            return 0
+        fi
+    done
+    note "Automatic Windows SDK install did not complete."
+    return 0
+}
+
+# ── PREFLIGHT ────────────────────────────────────────────────────────────────
+say "Preflight checks"
+
+# shellcheck disable=SC1091
+. /etc/os-release 2>/dev/null || true
+if [ "${VERSION_ID:-}" != "24.04" ]; then
+    die "This targets Ubuntu 24.04 (found '${VERSION_ID:-unknown}'). AMD's ROCm-on-WSL supports 24.04; create a dedicated distro:  wsl --install Ubuntu-24.04  (do not run on 26.04 -- ROCm 7.2 does not target it yet)."
+fi
+
+if [ ! -e /dev/dxg ]; then
+    die "/dev/dxg missing -- WSL GPU paravirtualization not present. Ensure this is WSL2 (not WSL1) on a recent Windows build, and that an AMD GPU + ROCDXG-capable Adrenalin driver is installed on the Windows host (then reboot)."
+fi
+note "Ubuntu 24.04 + /dev/dxg present."
+# Don't block on hsa/rocm libs in /usr/lib/wsl/lib: a working ROCDXG setup
+# doesn't need them (only d3d12/dxcore). Real readiness is checked via rocminfo.
+
+# ── Step 1: build/runtime prerequisites ──────────────────────────────────────
+say "Installing build prerequisites"
+export DEBIAN_FRONTEND=noninteractive
+$SUDO apt-get update -y
+# `make` is explicit: cmake shells out to it but Ubuntu only *recommends* it, so
+# minimal images lack it and the librocdxg `make -j` build would fail.
+$SUDO apt-get install -y cmake make gcc g++ git wget gpg ca-certificates python3-venv python3-pip
+
+# ── Step 2: ROCm ${ROCM_VER} userspace (no DKMS -- WSL uses the Windows driver) ─
+say "Installing ROCm ${ROCM_VER} userspace"
+if ! command -v rocminfo >/dev/null 2>&1 && [ ! -x /opt/rocm/bin/rocminfo ]; then
+    # Direct apt-repo install (leaner than amdgpu-install; repo is indexed by
+    # ROCm version, e.g. .../apt/7.2.1).
+    $SUDO mkdir -p /etc/apt/keyrings
+    wget -qO- https://repo.radeon.com/rocm/rocm.gpg.key \
+        | gpg --dearmor | $SUDO tee /etc/apt/keyrings/rocm.gpg >/dev/null
+    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/${ROCM_VER} noble main" \
+        | $SUDO tee /etc/apt/sources.list.d/rocm.list >/dev/null
+    printf 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600\n' \
+        | $SUDO tee /etc/apt/preferences.d/rocm-pin-600 >/dev/null
+    $SUDO apt-get update -y
+    # rocm-libs pulls everything torch links at runtime (rocblas, hipblas,
+    # miopen-hip, rccl, ...); hsa-rocr + rocminfo come as deps. Large (~5 GB
+    # download / ~23 GB installed).
+    $SUDO apt-get install -y rocm-libs rocminfo hip-runtime-amd
+else
+    note "ROCm already present -- skipping apt install."
+fi
+
+# Resolve the real ROCm dir and ensure the canonical /opt/rocm symlink. apt lays
+# ROCm under /opt/rocm-<ver> and rocm-core symlinks /opt/rocm -> that; repair if
+# an earlier partial run left /opt/rocm as a real dir blocking the symlink.
+_real="$(ls -d /opt/rocm-* 2>/dev/null | sort -V | tail -1 || true)"
+if [ -n "$_real" ] && [ ! -L /opt/rocm ] && [ -d /opt/rocm ]; then
+    # /opt/rocm is a real dir blocking the symlink. Only treat it as a removable
+    # stray stub if it's NOT a real ROCm install (a real one has bin/rocminfo /
+    # bin/hipcc / .info/version) -- this protects a user's pre-existing ROCm. Even
+    # then we MOVE IT ASIDE, never rm -rf, so a wrong guess can't lose data.
+    if [ -e /opt/rocm/bin/rocminfo ] || [ -e /opt/rocm/bin/hipcc ] || [ -e /opt/rocm/.info/version ]; then
+        note "/opt/rocm is a real ROCm install -- leaving it untouched (will install librocdxg into it)."
+    else
+        note "Moving stray /opt/rocm stub aside -> $_real (not deleting it)"
+        $SUDO cp -an /opt/rocm/. "$_real"/ 2>/dev/null || true
+        $SUDO mv /opt/rocm "/opt/rocm.unsloth-stub-bak.$(date +%s)" 2>/dev/null || true
+        [ -e /opt/rocm ] || $SUDO ln -s "$_real" /opt/rocm
+    fi
+elif [ -n "$_real" ] && [ ! -e /opt/rocm ]; then
+    $SUDO ln -s "$_real" /opt/rocm
+fi
+if [ -L /opt/rocm ] || [ -d /opt/rocm ]; then ROCM_DIR="/opt/rocm"; else ROCM_DIR="$_real"; fi
+{ [ -n "$ROCM_DIR" ] && [ -d "$ROCM_DIR" ]; } || die "ROCm not found under /opt after install."
+note "ROCm at ${ROCM_DIR}"
+
+# ── Step 3: build librocdxg (DXG <-> HSA bridge; not yet an apt package) ──────
+say "Building librocdxg (${LIBROCDXG_REF})"
+if [ -e "${ROCM_DIR}/lib/librocdxg.so" ]; then
+    note "librocdxg already installed -- skipping build."
+else
+    # Discover the newest installed Win11 SDK (version differs per machine). If
+    # absent, auto-install via winget (one UAC prompt) and re-discover; only if
+    # that ALSO fails do we stop with manual instructions.
+    _win_sdk="$(_find_win_sdk)"
+    if [ -z "$_win_sdk" ]; then
+        note "Windows 11 SDK headers not found -- attempting automatic install..."
+        _install_windows_sdk_via_winget
+        _win_sdk="$(_find_win_sdk)"
+    fi
+    [ -n "$_win_sdk" ] || die "Windows 11 SDK headers not found under 'C:\\Program Files (x86)\\Windows Kits\\10\\Include\\*\\shared', and the automatic winget install did not complete. Install it on the Windows host (e.g. 'winget install Microsoft.WindowsSDK.10.0.26100') and re-run."
+    note "Windows SDK: ${_win_sdk}"
+    _src="${HOME}/.unsloth/librocdxg"
+    rm -rf "$_src"
+    git clone --depth 1 --branch "$LIBROCDXG_REF" https://github.com/ROCm/librocdxg.git "$_src" \
+        || git clone "https://github.com/ROCm/librocdxg.git" "$_src"
+    (
+        cd "$_src"
+        git checkout "$LIBROCDXG_REF" 2>/dev/null || true
+        mkdir -p build && cd build
+        cmake .. -DWIN_SDK="${_win_sdk}/shared"
+        make -j"$(nproc)"
+        $SUDO make install
+    )
+fi
+# Ensure soname symlinks resolve to whatever version was built (e.g. 1.2.0).
+_dxg_real="$(ls -1 "${ROCM_DIR}"/lib/librocdxg.so.*.* 2>/dev/null | sort -V | tail -1 || true)"
+if [ -n "$_dxg_real" ]; then
+    _dxg_base="$(basename "$_dxg_real")"                       # librocdxg.so.1.2.0
+    _dxg_major="$(printf '%s' "$_dxg_base" | sed -E 's/librocdxg\.so\.([0-9]+).*/\1/')"
+    $SUDO ln -sf "$_dxg_base" "${ROCM_DIR}/lib/librocdxg.so.${_dxg_major}"
+    $SUDO ln -sf "librocdxg.so.${_dxg_major}" "${ROCM_DIR}/lib/librocdxg.so"
+fi
+echo "${ROCM_DIR}/lib" | $SUDO tee /etc/ld.so.conf.d/rocm.conf >/dev/null
+$SUDO ldconfig
+
+# ── Step 4: persist environment (system-wide so Studio's worker inherits it) ──
+say "Persisting ROCm-on-WSL environment"
+_envfile="/etc/profile.d/unsloth-rocm-wsl.sh"
+$SUDO tee "$_envfile" >/dev/null <<EOF
+# >>> Unsloth ROCm-on-WSL (gfx1151) >>>
+export HSA_ENABLE_DXG_DETECTION=1
+export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1
+export PATH="${ROCM_DIR}/bin:\${PATH}"
+export LD_LIBRARY_PATH="${ROCM_DIR}/lib:\${LD_LIBRARY_PATH:-}"
+# <<< Unsloth ROCm-on-WSL (gfx1151) <<<
+EOF
+# also drop into ~/.bashrc for interactive shells
+if [ -n "${HOME:-}" ] && ! grep -q "Unsloth ROCm-on-WSL" "${HOME}/.bashrc" 2>/dev/null; then
+    cat "$_envfile" >> "${HOME}/.bashrc"
+fi
+# export into the current process so verification below works immediately
+export HSA_ENABLE_DXG_DETECTION=1
+export PATH="${ROCM_DIR}/bin:${PATH}"
+export LD_LIBRARY_PATH="${ROCM_DIR}/lib:${LD_LIBRARY_PATH:-}"
+
+# ── Step 5: verify the runtime enumerates the GPU ────────────────────────────
+say "Verifying rocminfo sees ${GFX}"
+# Capture rocminfo into a var BEFORE grepping: piping into `grep -q` SIGPIPEs
+# rocminfo on first match, which under `set -o pipefail` turns a successful match
+# into a pipeline failure. Match the gfx1151 ISA "Name:" agent exactly (not a
+# broad gfx1[0-9]) so a generic fallback ISA or unrelated RDNA GPU can't pass.
+_rocminfo_out="$(rocminfo 2>/dev/null || true)"
+if ! printf '%s\n' "$_rocminfo_out" | grep -qE "Name:[[:space:]]*${GFX}([^0-9]|$)"; then
+    printf '%s\n' "$_rocminfo_out" | head -25 >&2 || true
+    die "rocminfo did not enumerate a ${GFX} GPU agent. Most common cause: the Windows AMD driver predates production ROCDXG -- update Adrenalin (install.ps1 offers this), reboot, and re-run."
+fi
+# Display-only summary: best-effort (|| true) so head's early pipe-close under
+# `set -o pipefail` can't fail the bootstrap after verification already passed.
+printf '%s\n' "$_rocminfo_out" | grep -E 'Marketing Name|Device Type|Compute Unit' | grep -iE "Radeon|GPU|Compute" | head -3 || true
+note "ROCm-on-WSL runtime is live for ${GFX}."
+
+# ── Step 6 (optional): torch smoke test from the gfx1151 index ───────────────
+if [ "$SMOKE_TEST" = "1" ]; then
+    say "Smoke-testing PyTorch on ${GFX} (throwaway venv)"
+    _venv="${HOME}/.unsloth/rocm-smoketest"
+    rm -rf "$_venv"; python3 -m venv "$_venv"
+    "$_venv/bin/pip" install --quiet --upgrade pip
+    # gfx1151 index is primary (torch + triton); PyPI only an extra for pure-py
+    # deps. The constraint keeps pip on the ROCm wheel, not a newer PyPI CUDA torch.
+    "$_venv/bin/pip" install --index-url "$TORCH_INDEX" \
+        --extra-index-url https://pypi.org/simple "$TORCH_CONSTRAINT" || \
+        die "torch install from ${TORCH_INDEX} failed."
+    "$_venv/bin/python" - <<'PY'
+import torch
+ok = torch.cuda.is_available()
+print("torch:", torch.__version__, "| cuda(rocm) available:", ok)
+if ok:
+    print("device:", torch.cuda.get_device_name(0))
+    free, total = torch.cuda.mem_get_info(0)
+    print(f"mem: free={free/1e9:.1f} GB total={total/1e9:.1f} GB")
+    import time
+    a = torch.randn(4096, 4096, device="cuda", dtype=torch.float16)
+    b = torch.randn(4096, 4096, device="cuda", dtype=torch.float16)
+    torch.cuda.synchronize(); t0 = time.time()
+    for _ in range(10): c = a @ b
+    torch.cuda.synchronize()
+    print(f"matmul ok ({(time.time()-t0)/10*1e3:.1f} ms/iter)")
+raise SystemExit(0 if ok else 1)
+PY
+    rm -rf "$_venv"
+fi
+
+say "Done."
+note "ROCm-on-WSL is ready for ${GFX}. If you ran this standalone, install Unsloth"
+note "in THIS distro and it will detect the GPU automatically:"
+note "  curl -fsSL https://unsloth.ai/install.sh | sh"
diff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1
index 25dd4af01b..f0f6e4fddc 100644
--- a/scripts/uninstall.ps1
+++ b/scripts/uninstall.ps1
@@ -16,15 +16,19 @@ function Uninstall-UnslothStudio {
     function _Step { param([string]$Msg) Write-Host $Msg }
     function _Substep { param([string]$Msg, [string]$Color = "Gray") Write-Host "  $Msg" -ForegroundColor $Color }
 
-    # Remove a file/dir/symlink only if it exists. Idempotent.
+    # Remove a file/dir/symlink if present. Idempotent; retries since a just-killed
+    # process can briefly hold a handle (Windows refuses the delete until released).
     function _RemovePath {
         param([string]$Path)
         if ([string]::IsNullOrWhiteSpace($Path)) { return }
-        if (Test-Path -LiteralPath $Path) {
+        if (-not (Test-Path -LiteralPath $Path)) { return }
+        for ($attempt = 1; $attempt -le 3; $attempt++) {
             try {
                 Remove-Item -LiteralPath $Path -Recurse -Force -ErrorAction Stop
                 _Substep "removed: $Path" "Green"
+                return
             } catch {
+                if ($attempt -lt 3) { Start-Sleep -Milliseconds 700; continue }
                 _Substep "could not remove: $Path ($($_.Exception.Message))" "Yellow"
             }
         }
@@ -236,9 +240,58 @@ function Uninstall-UnslothStudio {
         } catch { }
     }
 
+    # Stop processes that would block deleting the paths we remove. Unlike
+    # _StopStudioProcesses (venv exe only), this also catches llama-server/llama-cli,
+    # the unsloth.exe shim, and orphaned mp workers under SYSTEM python holding a
+    # venv DLL (an open DLL handle blocks the dir delete) -- found by scanning each
+    # candidate's loaded modules, not just its image path.
+    function _StopProcessesLockingRoots {
+        param([string[]]$Roots)
+        $clean = @($Roots | Where-Object { $_ } | ForEach-Object { $_.TrimEnd('\','/') })
+        if ($clean.Count -eq 0) { return }
+        $underRoot = {
+            param($p)
+            if (-not $p) { return $false }
+            foreach ($r in $clean) { if ($p -ieq $r -or $p -ilike "$r\*") { return $true } }
+            return $false
+        }
+        # 1. Image path under a target root (venv python, shim, llama-server).
+        try {
+            foreach ($proc in (Get-CimInstance Win32_Process -ErrorAction SilentlyContinue)) {
+                if ((& $underRoot $proc.ExecutablePath)) {
+                    try { Stop-Process -Id $proc.ProcessId -Force -ErrorAction SilentlyContinue } catch { }
+                }
+            }
+        } catch { }
+        # 2. A loaded module under a target root (orphaned mp-fork python holding a
+        #    venv DLL). Scoped to names that load our DLLs to keep the scan fast.
+        try {
+            $cands = Get-Process -Name python, pythonw, unsloth, llama-server, llama-cli -ErrorAction SilentlyContinue
+            foreach ($proc in $cands) {
+                $hit = $false
+                try {
+                    foreach ($m in $proc.Modules) { if ((& $underRoot $m.FileName)) { $hit = $true; break } }
+                } catch { }  # access denied enumerating modules -> skip
+                if ($hit) { try { Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue } catch { } }
+            }
+        } catch { }
+    }
+
     # Default install root + default data dir.
     $defaultStudioHome = if ($env:USERPROFILE) { Join-Path $env:USERPROFILE ".unsloth\studio" } else { $null }
     $defaultDataDir = if ($env:LOCALAPPDATA) { Join-Path $env:LOCALAPPDATA "Unsloth Studio" } else { $null }
+    # Default-mode ~/.unsloth holds a SHARED llama.cpp build + .cache that are
+    # siblings of studio (not under it), so deleting <studio> misses them -- handle
+    # explicitly. No-op in env/custom mode (nested under the custom root, removed
+    # with it). A user-set UNSLOTH_LLAMA_CPP_PATH is left alone.
+    $defaultUnslothHome = if ($env:USERPROFILE) { Join-Path $env:USERPROFILE ".unsloth" } else { $null }
+    $defaultLlamaCpp = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome "llama.cpp" } else { $null }
+    $defaultCache = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome ".cache" } else { $null }
+    # llama.cpp atomic-install staging root (install_llama_prebuilt.py .staging,
+    # sibling of the install dir). Usually pruned after activate, but an interrupted
+    # build can leave a "<name>.staging-XXXX" tree; removing it lets the empty-dir
+    # cleanup of ~/.unsloth below succeed. No-op in env/custom mode and when absent.
+    $defaultStaging = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome ".staging" } else { $null }
 
     # Build known-root list FIRST so the port-file kill can verify ownership.
     $customRoots = @(_CustomStudioRoots)
@@ -255,6 +308,9 @@ function Uninstall-UnslothStudio {
         _StopByPortFile -PortFile (Join-Path $r "share\studio.port") -KnownRoots $knownRoots
     }
     _StopStudioProcesses -KnownRoots $knownRoots
+    # Also stop anything holding a handle on the exact paths we delete (llama-server,
+    # the CLI shim, an mp-fork python with a venv DLL) so the dir delete isn't refused.
+    _StopProcessesLockingRoots -Roots (@($knownRoots) + @($defaultDataDir, $defaultLlamaCpp, $defaultCache))
 
     # ── Remove custom-root install trees ──
     _Step "Removing data and install directories..."
@@ -273,6 +329,16 @@ function Uninstall-UnslothStudio {
     if ($defaultStudioHome) { _RemovePath $defaultStudioHome }
     # Default data dir.
     if ($defaultDataDir) { _RemovePath $defaultDataDir }
+    # Default-mode shared llama.cpp build + cache (siblings of studio under
+    # ~/.unsloth). No-op in env/custom mode and when absent.
+    if ($defaultLlamaCpp) { _RemovePath $defaultLlamaCpp }
+    if ($defaultCache) { _RemovePath $defaultCache }
+    if ($defaultStaging) { _RemovePath $defaultStaging }
+    # Drop ~/.unsloth itself, but ONLY if now empty -- never nuke unrelated content.
+    if ($defaultUnslothHome -and (Test-Path -LiteralPath $defaultUnslothHome) -and
+        -not (Get-ChildItem -LiteralPath $defaultUnslothHome -Force -ErrorAction SilentlyContinue)) {
+        _RemovePath $defaultUnslothHome
+    }
 
     # ── Remove desktop and Start Menu shortcuts ──
     _Step "Removing desktop and Start Menu shortcuts..."
@@ -283,6 +349,18 @@ function Uninstall-UnslothStudio {
     if ($env:APPDATA) {
         _RemovePath (Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk")
     }
+    # Invalidate the Win11 Start Menu tile cache so the removed shortcut's tile
+    # disappears promptly instead of lingering stale (mirrors install.ps1's
+    # New-StudioShortcuts). Preserves start2.bin (the pin layout).
+    try {
+        $smehTemp = Join-Path $env:LOCALAPPDATA "Packages\Microsoft.Windows.StartMenuExperienceHost_cw5n1h2txyewy\TempState"
+        if (Test-Path -LiteralPath $smehTemp) {
+            Get-ChildItem -LiteralPath $smehTemp -Filter "TileCache_*" -ErrorAction SilentlyContinue |
+                Remove-Item -Force -ErrorAction SilentlyContinue
+            Remove-Item -LiteralPath (Join-Path $smehTemp "StartUnifiedTileModelCache.dat") -Force -ErrorAction SilentlyContinue
+            Stop-Process -Name StartMenuExperienceHost -Force -ErrorAction SilentlyContinue
+        }
+    } catch { }
 
     # ── Clean user PATH and registry backup ──
     _Step "Cleaning user PATH and registry..."
diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh
index bb830151ae..e97b28799b 100755
--- a/scripts/uninstall.sh
+++ b/scripts/uninstall.sh
@@ -212,6 +212,21 @@ _custom_studio_roots | while IFS= read -r _custom_root; do
     _remove_path "$_custom_root"
 done
 _remove_path "$HOME/.unsloth/studio"
+# Default-mode shared llama.cpp build + cache are siblings of studio (not removed
+# by deleting it). No-op in env/custom mode (they nest under the custom root) and
+# when absent. A user-set UNSLOTH_LLAMA_CPP_PATH is intentionally kept.
+_remove_path "$HOME/.unsloth/llama.cpp"
+_remove_path "$HOME/.unsloth/.cache"
+# llama.cpp atomic-install staging root (install_llama_prebuilt.py .staging).
+# Normally pruned after activate, but an interrupted build can leave it behind;
+# removing it lets the rmdir below succeed. No-op in env/custom mode and absent.
+_remove_path "$HOME/.unsloth/.staging"
+# ROCm-on-WSL helper artifacts (librocdxg build clone + smoke-test venv). No-op
+# where they don't exist; removing them lets the rmdir below succeed.
+_remove_path "$HOME/.unsloth/librocdxg"
+_remove_path "$HOME/.unsloth/rocm-smoketest"
+# Drop ~/.unsloth only if now empty (rmdir refuses non-empty, so user content is kept).
+rmdir "$HOME/.unsloth" 2>/dev/null || true
 _remove_path "$HOME/.local/share/unsloth"
 # CLI shim: only the symlink Studio created, never a pip-installed file.
 _remove_cli_shim
@@ -244,23 +259,102 @@ case "$_os" in
     Linux)
         if [ "$_is_wsl" = "1" ]; then
             echo "Removing WSL Windows-side shortcuts..."
-            # install.sh creates 'Unsloth Studio.lnk' on the Windows Desktop and
-            # Start Menu Programs folder via powershell.exe; mirror that path.
-            if command -v powershell.exe >/dev/null 2>&1; then
+            # install.sh creates per-distro 'Unsloth Studio (WSL - <distro>).lnk'
+            # on the Windows Desktop + Start Menu via powershell.exe. Scope removal
+            # to THIS distro (passed as $args[0]) so a multi-distro install keeps the
+            # other distros' launchers; the TARGET=wsl.exe check still spares a
+            # native install's "Unsloth Studio.lnk". Prefer powershell.exe; test it
+            # can EXECUTE (`command -v` succeeds even with interop OFF -- .exe then
+            # fails "Exec format error", common on systemd-enabled distros).
+            _wsl_distro="${WSL_DISTRO_NAME:-}"
+            _ps_ran=0
+            if command -v powershell.exe >/dev/null 2>&1 && \
+               powershell.exe -NoProfile -Command "exit 0" >/dev/null 2>&1; then
+                _ps_ran=1
+                # Inject the distro into the command: a -Command string does not
+                # receive trailing tokens as $args. WSL distro names are safe to
+                # embed (no quotes/$/backtick).
                 # shellcheck disable=SC2016
-                # $env:APPDATA is a PowerShell expansion; intentionally literal at shell level.
-                powershell.exe -NoProfile -Command '
-                    $names = @("Desktop","StartMenu");
+                powershell.exe -NoProfile -Command '$distro = "'"$_wsl_distro"'";
                     $dirs = @(
                         [Environment]::GetFolderPath("Desktop"),
                         (Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs")
                     );
+                    $ws = New-Object -ComObject WScript.Shell;
                     foreach ($d in $dirs) {
-                        if (-not $d) { continue }
-                        $p = Join-Path $d "Unsloth Studio.lnk";
-                        if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Force }
+                        if (-not $d -or -not (Test-Path -LiteralPath $d)) { continue }
+                        Get-ChildItem -LiteralPath $d -Filter "Unsloth Studio*.lnk" -ErrorAction SilentlyContinue | ForEach-Object {
+                            try {
+                                $sc = $ws.CreateShortcut($_.FullName);
+                                if ("$($sc.TargetPath) $($sc.Arguments)" -notmatch "wsl\.exe") { return }
+                                # When the distro is known, require the per-distro
+                                # name for this distro or its -d "<distro>" argument
+                                # so launchers for other distros are not removed.
+                                if ($distro) {
+                                    $nameMatch = ($_.Name -eq "Unsloth Studio (WSL - $distro).lnk");
+                                    $argMatch  = ($sc.Arguments -match ("-d\s+`"?" + [regex]::Escape($distro) + "`"?"));
+                                    if (-not ($nameMatch -or $argMatch)) { return }
+                                }
+                                Remove-Item -LiteralPath $_.FullName -Force -ErrorAction SilentlyContinue
+                            } catch { }
+                        }
                     }' >/dev/null 2>&1 || true
             fi
+            # Fallback when powershell.exe can't run (interop disabled): remove the
+            # WSL .lnk files via drvfs. The "Unsloth Studio (WSL..." name is
+            # WSL-specific, so a native install's "Unsloth Studio.lnk" never matches.
+            if [ "$_ps_ran" = "0" ]; then
+                for _drive in /mnt/c /mnt/d /mnt/e; do
+                    [ -d "$_drive/Users" ] || continue
+                    for _udir in "$_drive"/Users/*; do
+                        [ -d "$_udir" ] || continue
+                        for _scdir in \
+                            "$_udir/Desktop" \
+                            "$_udir/OneDrive/Desktop" \
+                            "$_udir"/OneDrive*/Desktop \
+                            "$_udir/AppData/Roaming/Microsoft/Windows/Start Menu/Programs"; do
+                            [ -d "$_scdir" ] || continue
+                            if [ -n "$_wsl_distro" ]; then
+                                # Exact per-distro name (no glob) so other distros survive.
+                                _lnk="$_scdir/Unsloth Studio (WSL - ${_wsl_distro}).lnk"
+                                [ -e "$_lnk" ] && rm -f "$_lnk" 2>/dev/null && echo "  removed: $_lnk" || true
+                            else
+                                # Distro unknown: fall back to the broad WSL prefix.
+                                for _lnk in "$_scdir"/"Unsloth Studio (WSL"*.lnk; do
+                                    [ -e "$_lnk" ] && rm -f "$_lnk" 2>/dev/null && echo "  removed: $_lnk" || true
+                                done
+                            fi
+                        done
+                    done
+                done
+            fi
+            # ── ROCm-on-WSL config (install_rocm_wsl_strixhalo.sh) ──
+            # Remove Unsloth's own ROCDXG config (the env it persisted). The system
+            # ROCm userspace is a shared prereq (like CUDA) and is LEFT IN PLACE by
+            # default; set UNSLOTH_UNINSTALL_ROCM=1 to remove it too.
+            echo "Removing ROCm-on-WSL config..."
+            _sudo=""
+            if [ "$_uid" != "0" ] && command -v sudo >/dev/null 2>&1; then _sudo="sudo"; fi
+            $_sudo rm -f /etc/profile.d/unsloth-rocm-wsl.sh 2>/dev/null || true
+            if [ -f "$HOME/.bashrc" ] && grep -q "Unsloth ROCm-on-WSL" "$HOME/.bashrc" 2>/dev/null; then
+                _bk=$(mktemp 2>/dev/null || echo "$HOME/.bashrc.unsloth.tmp")
+                if sed '/# >>> Unsloth ROCm-on-WSL/,/# <<< Unsloth ROCm-on-WSL/d' "$HOME/.bashrc" > "$_bk" 2>/dev/null; then
+                    cat "$_bk" > "$HOME/.bashrc" 2>/dev/null || true
+                    echo "  cleaned ROCm-on-WSL block from ~/.bashrc"
+                fi
+                rm -f "$_bk" 2>/dev/null || true
+            fi
+            if [ "${UNSLOTH_UNINSTALL_ROCM:-0}" = "1" ]; then
+                echo "  removing system ROCm (UNSLOTH_UNINSTALL_ROCM=1)..."
+                $_sudo rm -f /etc/apt/sources.list.d/rocm.list /etc/apt/preferences.d/rocm-pin-600 \
+                    /etc/apt/keyrings/rocm.gpg /etc/ld.so.conf.d/rocm.conf 2>/dev/null || true
+                $_sudo sh -c 'rm -rf /opt/rocm /opt/rocm-*' 2>/dev/null || true
+                if command -v ldconfig >/dev/null 2>&1; then $_sudo ldconfig 2>/dev/null || true; fi
+            elif [ -d /opt/rocm ]; then
+                echo "  Note: ROCm userspace (/opt/rocm*) left in place (shared prereq)."
+                echo "        Remove it by re-running with UNSLOTH_UNINSTALL_ROCM=1, or manually:"
+                echo "          sudo rm -rf /opt/rocm /opt/rocm-* && sudo ldconfig"
+            fi
         fi
         echo "Removing Linux .desktop entry..."
         _remove_path "$HOME/.local/share/applications/unsloth-studio.desktop"
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 953c1d3141..317c9c7f21 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3174,46 +3174,88 @@ class LlamaCppBackend:
                     except Exception as e:
                         logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 
-                # Defensive kill: drop an orphan Popen a concurrent load may
-                # have stored before we overwrite the reference (#5161).
-                self._kill_process()
+                # One-shot --fit off retry: recent llama.cpp runs a "fitting
+                # params to device memory" step by default (--fit defaults to
+                # 'on') even when -ngl is explicit. That step has aborted on
+                # some ROCm hosts (ggml-cuda.cu ROCm error during worst-case
+                # estimation, e.g. MTP + mmproj models on gfx1151). When
+                # Studio's own VRAM math already placed the model
+                # (use_fit=False), the step is redundant second-guessing --
+                # retry once with --fit off before declaring the load failed.
+                # Never retry when fit was requested (use_fit) or the caller
+                # passed an explicit fit flag via extra args.
+                _fit_retry_allowed = self._fit_off_retry_eligible(cmd, use_fit)
+                for _spawn_attempt in (0, 1):
+                    # Defensive kill: drop an orphan Popen a concurrent load may
+                    # have stored before we overwrite the reference (#5161).
+                    # Also reaps the crashed first attempt on the retry pass.
+                    self._kill_process()
 
-                self._stdout_lines = []
-                # Tee llama-server output to a dedicated log file so a
-                # post-mortem has the full trail even when the parent only kept
-                # the last 50 lines. Path is under the studio home.
-                self._llama_log_fh = None
-                try:
-                    log_dir = _swa_cache_path().parent / "logs" / "llama-server"
-                    log_dir.mkdir(parents = True, exist_ok = True)
-                    self._llama_log_path = (
-                        log_dir / f"llama-{int(time.time())}-port-{self._port}.log"
+                    self._stdout_lines = []
+                    # Tee llama-server output to a dedicated log file so a
+                    # post-mortem has the full trail even when the parent only
+                    # kept the last 50 lines. Path is under the studio home.
+                    self._llama_log_fh = None
+                    try:
+                        log_dir = _swa_cache_path().parent / "logs" / "llama-server"
+                        log_dir.mkdir(parents = True, exist_ok = True)
+                        # Include the attempt index: the --fit off retry can
+                        # respawn within the same epoch second, and reusing the
+                        # name would truncate the crash log the retry warning
+                        # just pointed the user at.
+                        self._llama_log_path = log_dir / (
+                            f"llama-{int(time.time())}-port-{self._port}"
+                            f"-try{_spawn_attempt}.log"
+                        )
+                        self._llama_log_fh = open(
+                            self._llama_log_path,
+                            "w",
+                            encoding = "utf-8",
+                            buffering = 1,
+                        )
+                        logger.info(f"llama-server stdout/stderr -> {self._llama_log_path}")
+                    except OSError as e:
+                        # Best-effort; never block the load on logging.
+                        logger.debug(f"Could not open llama-server log file: {e}")
+                        self._llama_log_path = None
+                    self._process = subprocess.Popen(
+                        cmd,
+                        stdout = subprocess.PIPE,
+                        stderr = subprocess.STDOUT,
+                        text = True,
+                        env = env,
+                        **_windows_hidden_subprocess_kwargs(),
                     )
-                    self._llama_log_fh = open(
-                        self._llama_log_path,
-                        "w",
-                        encoding = "utf-8",
-                        buffering = 1,
-                    )
-                    logger.info(f"llama-server stdout/stderr -> {self._llama_log_path}")
-                except OSError as e:
-                    # Best-effort; never block the load on logging.
-                    logger.debug(f"Could not open llama-server log file: {e}")
-                    self._llama_log_path = None
-                self._process = subprocess.Popen(
-                    cmd,
-                    stdout = subprocess.PIPE,
-                    stderr = subprocess.STDOUT,
-                    text = True,
-                    env = env,
-                    **_windows_hidden_subprocess_kwargs(),
-                )
 
-                # Background thread to drain stdout (prevents pipe deadlock)
-                self._stdout_thread = threading.Thread(
-                    target = self._drain_stdout, daemon = True, name = "llama-stdout"
-                )
-                self._stdout_thread.start()
+                    # Background thread to drain stdout (prevents pipe deadlock)
+                    self._stdout_thread = threading.Thread(
+                        target = self._drain_stdout, daemon = True, name = "llama-stdout"
+                    )
+                    self._stdout_thread.start()
+                    if self._wait_for_health(timeout = 600.0):
+                        break
+                    _startup_crashed = (
+                        self._process.poll() is not None and self._process.returncode != 0
+                    )
+                    if _spawn_attempt == 0 and _fit_retry_allowed and _startup_crashed:
+                        logger.warning(
+                            "llama-server crashed during startup (exit code %s) "
+                            "with the default memory-fit step enabled; Studio "
+                            "already verified the model fits, retrying once "
+                            "with --fit off. Crash log: %s",
+                            self._process.returncode,
+                            self._llama_log_path,
+                        )
+                        cmd = [*cmd, "--fit", "off"]
+                        continue
+                    self._kill_process()
+                    raise RuntimeError(
+                        self._classify_llama_start_failure(
+                            "\n".join(self._stdout_lines[-50:]),
+                            gguf_path,
+                            model_identifier,
+                        )
+                    )
 
                 # Store the resolved on-disk path, not the caller's kwarg: in
                 # HF mode gguf_path is None and ``model_path`` is what
@@ -3243,17 +3285,7 @@ class LlamaCppBackend:
                     max_available_ctx if max_available_ctx > 0 else self._effective_context_length
                 )
 
-                # Wait for llama-server to become healthy.
-                if not self._wait_for_health(timeout = 600.0):
-                    self._kill_process()
-                    raise RuntimeError(
-                        self._classify_llama_start_failure(
-                            "\n".join(self._stdout_lines[-50:]),
-                            gguf_path,
-                            self._model_identifier,
-                        )
-                    )
-
+                # Health was confirmed inside the spawn/retry loop above.
                 self._healthy = True
 
                 # Commit caller intent only after _healthy=True so a failed start
@@ -3917,6 +3949,23 @@ class LlamaCppBackend:
         """atexit handler to ensure llama-server is terminated."""
         self._kill_process()
 
+    @staticmethod
+    def _fit_off_retry_eligible(cmd: "list[str]", use_fit: bool) -> bool:
+        """Whether a llama-server startup crash may be retried with --fit off.
+
+        Only when Studio's own VRAM math placed the model (use_fit=False)
+        and nothing on the command line set the fit mode explicitly
+        (-fit / --fit, space- or equals-form). --fit-ctx / --fit-target /
+        -fitc / -fitt tune the fit step but do not select the mode, so
+        they do not block the retry.
+        """
+        if use_fit:
+            return False
+        for a in cmd:
+            if a in ("-fit", "--fit") or a.startswith(("-fit=", "--fit=")):
+                return False
+        return True
+
     def _wait_for_health(
         self,
         timeout: float = 120.0,
@@ -3933,9 +3982,17 @@ class LlamaCppBackend:
                 if self._stdout_thread is not None:
                     self._stdout_thread.join(timeout = 2)
                 output = "\n".join(self._stdout_lines[-50:])
+                # Keep the TAIL: crash details (abort reason, ROCm/CUDA error
+                # text) print last, after the long startup banner. Head
+                # truncation has cut off exactly the diagnostic line before.
+                _log_hint = (
+                    f" Full log: {self._llama_log_path}"
+                    if getattr(self, "_llama_log_path", None)
+                    else ""
+                )
                 logger.error(
                     f"llama-server exited with code {self._process.returncode}. "
-                    f"Output: {output[:2000]}"
+                    f"Output (tail): {output[-2000:]}{_log_hint}"
                 )
                 return False
 
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 50323478b2..f7fbaa0b69 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -26,6 +26,22 @@ import subprocess as _sp
 from pathlib import Path
 from typing import Any, Callable
 
+# ── WSL AMD Strix Halo (gfx1151): enable ROCDXG before any torch import ──────
+# Mirrors main.py. In WSL the AMD GPU is reached via the ROCDXG bridge
+# (librocdxg.so over /dev/dxg), which HSA loads only when HSA_ENABLE_DXG_
+# DETECTION=1 is set before torch touches the GPU. A worker spawned outside a
+# login shell misses the installer's persisted env and falls back to CPU.
+# Gated to no-op unless BOTH /dev/dxg and librocdxg.so exist, so native Linux
+# ROCm, NVIDIA, macOS and Windows are unaffected.
+if sys.platform.startswith("linux") and "HSA_ENABLE_DXG_DETECTION" not in os.environ:
+    try:
+        if os.path.exists("/dev/dxg") and any(
+            os.path.exists(_p + "/librocdxg.so") for _p in ("/opt/rocm/lib", "/opt/rocm/lib64")
+        ):
+            os.environ["HSA_ENABLE_DXG_DETECTION"] = "1"
+    except Exception:
+        pass
+
 logger = get_logger(__name__)
 from utils.hardware import apply_gpu_ids
 from utils.wheel_utils import (
@@ -678,8 +694,11 @@ def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
       ``set_per_process_memory_fraction`` cap to leave OS headroom.
 
     Classification priority:
-    1. ``gcnArchName`` / variant spellings (stable, naming-independent).
-    2. Device-name substring match (last resort when all arch attrs absent;
+    1. ``props.is_integrated`` truthy (hipDeviceProp_t.integrated -- the
+       driver's own unified-memory answer; covers APUs beyond the hardcoded
+       arch set, e.g. gfx1103 Phoenix iGPUs). Only ever upgrades to unified.
+    2. ``gcnArchName`` / variant spellings (stable, naming-independent).
+    3. Device-name substring match (last resort when all arch attrs absent;
        AMD SDK / Radeon wheels may not populate them):
          - gfx1150 Strix Point: ``Radeon 890M``, ``Radeon 880M``
          - gfx1151 Strix Halo:  ``Radeon 8060S`` (Ryzen AI MAX+ 395),
@@ -692,6 +711,16 @@ def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:
             gcn_arch = _v
             break
 
+    # Driver's own answer first: hipDeviceProp_t.integrated (exposed as
+    # props.is_integrated; same gate PR #5988's UMA safetensors fast-load
+    # uses). Strictly additive -- only a truthy value upgrades to unified;
+    # 0/absent falls through to the arch/name logic below, so a wheel that
+    # omits or zeroes the field can never downgrade the known APU set. This
+    # covers unified APUs outside the hardcoded arches (gfx1103 Phoenix
+    # iGPUs, future parts) with one universal signal.
+    if getattr(props, "is_integrated", 0):
+        return gcn_arch, True
+
     if gcn_arch:
         return gcn_arch, gcn_arch in {"gfx1150", "gfx1151"}
 
@@ -1982,6 +2011,19 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 os.environ["TORCHDYNAMO_DISABLE"] = "1"
                 logger.info("Windows ROCm: torch.compile (dynamo) disabled")
 
+            # bitsandbytes' import-time get_rocm_gpu_arch() probe runs
+            # `hipinfo.exe` from PATH; the AMD torch wheel ships it in the venv
+            # Scripts dir, which is on PATH only for activated venvs. Prepend
+            # it so the probe succeeds instead of logging a scary (harmless)
+            # "Could not detect ROCm GPU architecture" ERROR on every import.
+            # Normally inherited from main.py's env, but workers can also be
+            # spawned standalone (tests, CLI) -- keep the guard here too.
+            _scripts_dir = os.path.dirname(sys.executable)
+            if os.path.isfile(os.path.join(_scripts_dir, "hipInfo.exe")):
+                import shutil as _shutil
+                if not _shutil.which("hipinfo.exe"):
+                    os.environ["PATH"] = _scripts_dir + os.pathsep + os.environ.get("PATH", "")
+
             # BNB picks a rocm DLL from torch.version.hip, but AMD's Windows BNB
             # wheel may ship a DLL whose suffix doesn't match. Detect the actual
             # DLL name and override; "72" is a safe fallback. Callers may
@@ -2178,10 +2220,25 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 if _is_unified and not _gcn_arch:
                     logger.debug(
                         "ROCm OOM guard: gcnArchName absent -- inferred "
-                        "unified memory from device name %r; applying 0.80 cap",
+                        "unified memory from device name %r; applying unified cap",
                         _dev_name,
                     )
-                _mem_fraction = 0.80 if _is_unified else 0.90
+                # Unified hosts on native Windows: mem_get_info's total is the
+                # WDDM budget the driver grants HIP (BIOS carve + ~half of the
+                # remaining RAM) -- the OS share is already outside it, so the
+                # Linux 0.80 starve-protection double-taxes (48.49 GiB budget →
+                # 38.79 allowed) and blocks loads that fit in free memory.
+                # 1.0 removes the double-tax. Current AMD Windows wheels only
+                # enforce sub-1.0 fractions (measured on gfx1151: 0.5 caps,
+                # 1.0 still allocates past the budget via WDDM overcommit), so
+                # 1.0 behaves like torch's uncapped default, with WDDM
+                # arbitrating residency; on wheels that do enforce it, it caps
+                # at exactly the driver-granted budget. On Linux the total
+                # spans nearly all RAM, so keep the 0.80 OS headroom there.
+                if _is_unified:
+                    _mem_fraction = 1.0 if sys.platform == "win32" else 0.80
+                else:
+                    _mem_fraction = 0.90
                 _torch_mem.cuda.set_per_process_memory_fraction(_mem_fraction)
                 logger.info(
                     "ROCm OOM guard: set_per_process_memory_fraction(%.2f) — "
@@ -2191,6 +2248,28 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                     _dev_name,
                     _gcn_arch or "unknown arch",
                 )
+                # Unified Windows APUs: the WDDM budget is user-raisable, but
+                # nothing on the box says so -- users see "48 GB VRAM" on a
+                # 96 GB machine and assume a Studio bug. Say where the limit
+                # comes from and how to raise it.
+                if _is_unified and sys.platform == "win32":
+                    try:
+                        import psutil as _psutil
+
+                        _phys = _psutil.virtual_memory().total
+                        _granted = _torch_mem.cuda.mem_get_info(0)[1]
+                        if _granted < 0.75 * _phys:
+                            logger.info(
+                                "Windows grants the GPU %.1f GiB of %.1f GiB "
+                                "system RAM (driver/WDDM budget). To raise it: "
+                                "increase the BIOS UMA frame buffer size, or "
+                                "AMD Software > Performance > Tuning > "
+                                "Variable Graphics Memory.",
+                                _granted / 1024**3,
+                                _phys / 1024**3,
+                            )
+                    except Exception:
+                        pass
         except Exception as _oom_guard_err:
             logger.debug("Could not set GPU memory fraction: %s", _oom_guard_err)
 
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 35c955405e..38605a5009 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -63,6 +63,23 @@ if sys.platform == "win32":
     _add_rocm_dll_dirs()
     del _add_rocm_dll_dirs
 
+    # ── Windows AMD ROCm: make hipInfo.exe resolvable for subprocess probes ──
+    # bitsandbytes' get_rocm_gpu_arch() runs `hipinfo.exe` via PATH at import
+    # time; the AMD torch wheel ships it in the venv Scripts dir, which is on
+    # PATH only when the venv is activated -- Studio launches python directly.
+    # Without this, every bitsandbytes import logs a scary (but harmless)
+    # "Could not detect ROCm GPU architecture: [WinError 2]" ERROR + WARNING.
+    # Gated on the file existing: only AMD ROCm wheels ship hipInfo.exe, so
+    # NVIDIA/CPU hosts are untouched. os.add_dll_directory above does not help
+    # here -- subprocess PATH resolution ignores DLL search directories.
+    _scripts_dir = os.path.dirname(sys.executable)
+    if os.path.isfile(os.path.join(_scripts_dir, "hipInfo.exe")):
+        import shutil as _shutil
+        if not _shutil.which("hipinfo.exe"):
+            os.environ["PATH"] = _scripts_dir + os.pathsep + os.environ.get("PATH", "")
+        del _shutil
+    del _scripts_dir
+
     # ── Windows AMD ROCm: set BNB_ROCM_VERSION before any bitsandbytes import ─
     # bitsandbytes derives the rocm<ver>.dll name from torch.version.hip, but the
     # wheel ships rocm72.dll, so the server crashes ("Configured ROCm binary not
@@ -108,6 +125,28 @@ if sys.platform == "win32":
                 _bnb_rocm_ver_final,
             )
 
+# ── WSL AMD Strix Halo (gfx1151): enable ROCDXG before any torch import ──────
+# In WSL the AMD GPU is reached via the ROCDXG bridge (librocdxg.so over
+# /dev/dxg), which HSA loads only when HSA_ENABLE_DXG_DETECTION=1 is set BEFORE
+# torch touches the GPU. A worker launched outside a login shell (e.g.
+# `wsl.exe -d Ubuntu-24.04 python ...`) misses the installer's persisted env
+# and silently falls back to CPU. Set it here, gated to no-op unless BOTH
+# /dev/dxg AND librocdxg.so exist -- native Linux ROCm, NVIDIA, macOS and
+# Windows are unaffected.
+elif sys.platform.startswith("linux") and "HSA_ENABLE_DXG_DETECTION" not in os.environ:
+    try:
+        if os.path.exists("/dev/dxg") and any(
+            os.path.exists(os.path.join(_p, "librocdxg.so"))
+            for _p in ("/opt/rocm/lib", "/opt/rocm/lib64")
+        ):
+            os.environ["HSA_ENABLE_DXG_DETECTION"] = "1"
+            import logging as _logging
+            _logging.getLogger(__name__).info(
+                "WSL ROCm: set HSA_ENABLE_DXG_DETECTION=1 (librocdxg bridge present)"
+            )
+    except Exception:
+        pass
+
 # Put backend dir on sys.path so _platform_compat is importable when main.py
 # is launched directly (e.g. `uvicorn main:app`).
 _backend_dir = str(_Path(__file__).parent)
diff --git a/studio/backend/run.py b/studio/backend/run.py
index c992a4bec2..4619cb849c 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -8,6 +8,7 @@ Self-contained; can be moved to any directory.
 
 import os
 import sys
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -673,6 +674,94 @@ def _resolve_frontend_path(frontend_path: Path) -> tuple[Optional[Path], list[Pa
     return None, attempted
 
 
+class _TeeStream:
+    """Mirror writes to the original stream and a session log file.
+
+    Console behavior is unchanged (writes/returns delegate to the original
+    stream; Tauri's structured-stdout protocol and isatty probes see exactly
+    what they saw before). The file copy is best-effort: a full disk or a
+    closed handle must never break the console."""
+
+    def __init__(self, stream, log_fh):
+        self._stream = stream
+        self._log_fh = log_fh
+
+    def write(self, data):
+        try:
+            self._log_fh.write(data)
+        except Exception:
+            pass
+        return self._stream.write(data)
+
+    def flush(self):
+        try:
+            self._log_fh.flush()
+        except Exception:
+            pass
+        try:
+            self._stream.flush()
+        except Exception:
+            pass
+
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+
+def _setup_server_disk_logging():
+    """Tee stdout/stderr to ~/.unsloth/studio/logs/server/ and aim
+    faulthandler at the same file so hard crashes (access violations /
+    SIGSEGV in the GPU runtime) leave a stack trace on disk.
+
+    Also exports PYTHONFAULTHANDLER=1 so child Python processes (training
+    workers) dump native-crash stacks to their captured stderr. Keeps the
+    newest 20 session logs. Opt out with UNSLOTH_STUDIO_NO_FILE_LOG=1.
+    Returns the log path, or None when disabled/unavailable.
+    """
+    if os.environ.get("UNSLOTH_STUDIO_NO_FILE_LOG") == "1":
+        return None
+    try:
+        from utils.paths import studio_root
+        log_dir = Path(studio_root()) / "logs" / "server"
+    except Exception:
+        home = (
+            os.environ.get("UNSLOTH_STUDIO_HOME")
+            or os.environ.get("STUDIO_HOME")
+            or os.path.join(os.path.expanduser("~"), ".unsloth", "studio")
+        )
+        log_dir = Path(home) / "logs" / "server"
+    try:
+        log_dir.mkdir(parents = True, exist_ok = True)
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        log_path = log_dir / f"server-{stamp}-pid{os.getpid()}.log"
+        # Line-buffered so the tail survives a hard kill; errors="replace"
+        # so a console encoding quirk can never take the server down.
+        log_fh = open(log_path, "w", encoding = "utf-8", errors = "replace", buffering = 1)
+    except Exception:
+        return None
+
+    import faulthandler
+
+    try:
+        faulthandler.enable(file = log_fh, all_threads = True)
+    except Exception:
+        pass
+    # Children (training workers) inherit: their native-crash stacks land on
+    # the stderr the server already captures.
+    os.environ.setdefault("PYTHONFAULTHANDLER", "1")
+
+    sys.stdout = _TeeStream(sys.stdout, log_fh)
+    sys.stderr = _TeeStream(sys.stderr, log_fh)
+
+    # Best-effort retention: keep the newest 20 session logs.
+    try:
+        logs = sorted(log_dir.glob("server-*.log"), key = lambda p: p.stat().st_mtime)
+        for old in logs[:-20]:
+            old.unlink(missing_ok = True)
+    except Exception:
+        pass
+    return log_path
+
+
 def run_server(
     host: str = "127.0.0.1",
     port: int = 8888,
@@ -705,6 +794,16 @@ def run_server(
         except Exception:
             pass
 
+    # Persist a session log + native-crash stacks BEFORE importing main, so
+    # even import-time failures leave evidence on disk. Field report: Studio
+    # "terminates without a warning" -- a native crash in the GPU runtime
+    # kills the process with no Python traceback, and a desktop-shortcut
+    # console closes before anything can be read. Console-only logging made
+    # that undiagnosable.
+    _session_log = _setup_server_disk_logging()
+    if _session_log is not None and not silent:
+        print(f"Session log: {_session_log}")
+
     # Set env var BEFORE importing main so CORS middleware picks it up.
     if api_only:
         os.environ["UNSLOTH_API_ONLY"] = "1"
diff --git a/studio/backend/tests/test_llama_cpp_wait_for_health.py b/studio/backend/tests/test_llama_cpp_wait_for_health.py
index 33f9e9d803..1ba6c9f7b5 100644
--- a/studio/backend/tests/test_llama_cpp_wait_for_health.py
+++ b/studio/backend/tests/test_llama_cpp_wait_for_health.py
@@ -145,3 +145,111 @@ class TestWaitForHealthResilience:
         monkeypatch.setattr(httpx, "get", should_not_be_called)
         assert b._wait_for_health(timeout = 5.0, interval = 0.01) is False
         assert called["n"] == 0
+
+
+class TestCrashLogTail:
+    """The "exited with code X" log must keep the TAIL of the output.
+
+    Crash diagnostics (abort reason, ROCm/CUDA error text) print last,
+    after the long startup banner; head truncation has cut off exactly
+    the diagnostic line in field reports (gfx1151 fit-step abort)."""
+
+    @staticmethod
+    def _capture_error_logs(monkeypatch) -> list:
+        """Capture module-logger .error() messages directly -- immune to
+        whatever logging/structlog config sibling test modules installed."""
+        import core.inference.llama_cpp as _llama_mod
+
+        records: list = []
+        fake_logger = mock.Mock()
+        fake_logger.error = mock.Mock(side_effect = lambda msg, *a, **k: records.append(msg))
+        monkeypatch.setattr(_llama_mod, "logger", fake_logger)
+        return records
+
+    def test_crash_log_keeps_tail_not_head(self, monkeypatch):
+        records = self._capture_error_logs(monkeypatch)
+        b = _make_backend()
+        b._process.poll.return_value = 1
+        b._process.returncode = 1
+        # >2000 chars of banner, diagnostic on the final line.
+        banner = [f"load_model: tensor blk.{i} buffer ROCm0" for i in range(80)]
+        diagnostic = "ggml-cuda.cu:103: ROCm error: out of memory"
+        b._stdout_lines = banner + [diagnostic]
+
+        assert b._wait_for_health(timeout = 1.0, interval = 0.01) is False
+
+        crash_logs = [m for m in records if "exited with code" in m]
+        assert crash_logs, "crash must produce an exited-with-code log"
+        assert diagnostic in crash_logs[-1]
+        assert "Output (tail)" in crash_logs[-1]
+        # The head of the banner must be the part sacrificed to truncation.
+        assert "blk.0 buffer" not in crash_logs[-1]
+
+    def test_crash_log_mentions_log_file_when_present(self, monkeypatch):
+        records = self._capture_error_logs(monkeypatch)
+        b = _make_backend()
+        b._process.poll.return_value = 1
+        b._process.returncode = 1
+        b._stdout_lines = ["boom"]
+        b._llama_log_path = Path("C:/logs/llama-123-port-1234.log")
+
+        assert b._wait_for_health(timeout = 1.0, interval = 0.01) is False
+
+        crash_logs = [m for m in records if "exited with code" in m]
+        assert crash_logs and "llama-123-port-1234.log" in crash_logs[-1]
+
+
+class TestRetryLogFilenameUnique:
+    """The --fit off retry can respawn within the same epoch second; the log
+    filename must carry the attempt index or the second open ("w") truncates
+    the crash log the retry warning just referenced (found by simulation:
+    frozen time.time -> single file, crash evidence gone)."""
+
+    def test_log_name_includes_attempt_index(self):
+        src = (
+            Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_cpp.py"
+        ).read_text(encoding = "utf-8")
+        assert "-try{_spawn_attempt}.log" in src
+
+
+class TestFitOffRetryEligible:
+    """Gate for the one-shot --fit off startup-crash retry.
+
+    Retry only when Studio's own VRAM math placed the model and nothing
+    on the command line chose the fit mode explicitly."""
+
+    def test_eligible_for_plain_ngl_launch(self):
+        cmd = ["llama-server", "-m", "x.gguf", "-ngl", "-1", "--jinja"]
+        assert LlamaCppBackend._fit_off_retry_eligible(cmd, use_fit = False) is True
+
+    def test_not_eligible_when_use_fit(self):
+        cmd = ["llama-server", "-m", "x.gguf", "--fit", "on"]
+        assert LlamaCppBackend._fit_off_retry_eligible(cmd, use_fit = True) is False
+
+    @pytest.mark.parametrize(
+        "fit_args",
+        [
+            ["--fit", "on"],
+            ["--fit", "off"],
+            ["-fit", "off"],
+            ["--fit=on"],
+            ["-fit=off"],
+        ],
+    )
+    def test_not_eligible_with_explicit_fit_flag(self, fit_args):
+        cmd = ["llama-server", "-m", "x.gguf", *fit_args]
+        assert LlamaCppBackend._fit_off_retry_eligible(cmd, use_fit = False) is False
+
+    @pytest.mark.parametrize(
+        "tuning_args",
+        [
+            ["--fit-ctx", "8192"],
+            ["--fit-target", "1024"],
+            ["-fitc", "4096"],
+            ["-fitt", "512"],
+            ["--fit-ctx=8192"],
+        ],
+    )
+    def test_fit_tuning_flags_do_not_block_retry(self, tuning_args):
+        cmd = ["llama-server", "-m", "x.gguf", *tuning_args]
+        assert LlamaCppBackend._fit_off_retry_eligible(cmd, use_fit = False) is True
diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.py
index 21edabd142..6e70c7cde4 100644
--- a/studio/backend/tests/test_rocm_oom_guard.py
+++ b/studio/backend/tests/test_rocm_oom_guard.py
@@ -13,6 +13,7 @@ wrong headroom factor on a 128 GiB unified-memory pool.
 
 from __future__ import annotations
 
+from pathlib import Path
 from types import SimpleNamespace
 
 import pytest
@@ -28,6 +29,46 @@ def _props(**kwargs) -> SimpleNamespace:
     return SimpleNamespace(**kwargs)
 
 
+# ── Path 0: props.is_integrated (driver's own unified-memory answer) ─────────
+
+
+class TestIsIntegratedSignal:
+    """hipDeviceProp_t.integrated wins when truthy; 0/absent never downgrades.
+
+    Same universal gate PR #5988's UMA safetensors fast-load uses -- keeps
+    Studio's two unified-memory consumers on one signal."""
+
+    def test_integrated_upgrades_unknown_apu(self) -> None:
+        # gfx1103 Phoenix iGPU: outside the hardcoded arch set, but the
+        # driver says integrated -> unified.
+        props = _props(gcnArchName = "gfx1103", name = "Radeon 780M", is_integrated = 1)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == "gfx1103"
+        assert is_unified is True
+
+    def test_integrated_wins_without_any_arch(self) -> None:
+        props = _props(name = "Some Future APU", is_integrated = 1)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert gcn == ""
+        assert is_unified is True
+
+    def test_zero_does_not_downgrade_known_apu(self) -> None:
+        # A wheel that zeroes the field must not flip Strix Halo to discrete.
+        props = _props(gcnArchName = "gfx1151", name = "x", is_integrated = 0)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert is_unified is True
+
+    def test_absent_keeps_existing_behavior(self) -> None:
+        props = _props(gcnArchName = "gfx1201", name = "RX 9070 XT")
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert is_unified is False
+
+    def test_discrete_with_zero_stays_discrete(self) -> None:
+        props = _props(gcnArchName = "gfx1100", name = "RX 7900 XTX", is_integrated = 0)
+        gcn, is_unified = _rocm_classify_unified_memory(props)
+        assert is_unified is False
+
+
 # ── Path 1: canonical gcnArchName ────────────────────────────────────────────
 
 
@@ -168,3 +209,35 @@ class TestDeviceNameFallback:
         gcn, is_unified = _rocm_classify_unified_memory(props)
         assert gcn == ""
         assert is_unified is False
+
+
+# ── Fraction selection (source-pinned) ───────────────────────────────────────
+
+
+_WORKER_PY = Path(__file__).resolve().parents[1] / "core" / "training" / "worker.py"
+
+
+class TestMemFractionSelection:
+    """Pin the per-platform fraction policy in worker.py section 1g.
+
+    On native Windows, torch.cuda.mem_get_info's total is the WDDM budget
+    the driver grants HIP -- the OS share of RAM is already outside it, so
+    a 0.80 cap double-taxes (field report: 48.49 GiB budget -> '38.79 GiB
+    allowed' OOM denying a 47.29 GiB load that fit in free memory). 1.0
+    removes the double-tax; current AMD Windows wheels enforce only
+    sub-1.0 fractions, so it behaves like torch's uncapped default with
+    WDDM arbitrating residency (measured on gfx1151)."""
+
+    def test_unified_win32_uses_budget_exact_fraction(self) -> None:
+        source = _WORKER_PY.read_text(encoding = "utf-8")
+        assert '1.0 if sys.platform == "win32" else 0.80' in source
+
+    def test_discrete_keeps_090(self) -> None:
+        source = _WORKER_PY.read_text(encoding = "utf-8")
+        assert "_mem_fraction = 0.90" in source
+
+    def test_win32_unified_logs_vgm_hint(self) -> None:
+        """Users must learn the WDDM budget is raisable (BIOS UMA / AMD
+        Software Variable Graphics Memory) instead of assuming a bug."""
+        source = _WORKER_PY.read_text(encoding = "utf-8")
+        assert "Variable Graphics Memory" in source
diff --git a/studio/backend/tests/test_server_disk_logging.py b/studio/backend/tests/test_server_disk_logging.py
new file mode 100644
index 0000000000..05d03d869c
--- /dev/null
+++ b/studio/backend/tests/test_server_disk_logging.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the server session log + native-crash capture in run.py.
+
+Field regression: Studio "terminates without a warning" -- a native crash in
+the GPU runtime kills the process with no Python traceback, and a desktop-
+shortcut console closes before anything can be read. The server must tee its
+console output to disk and aim faulthandler at the same file so even hard
+crashes leave evidence.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+import run as run_mod  # noqa: E402
+
+
+class TestTeeStream:
+    def test_writes_reach_both_and_return_original(self):
+        console, log = io.StringIO(), io.StringIO()
+        tee = run_mod._TeeStream(console, log)
+        n = tee.write("hello")
+        assert console.getvalue() == "hello" == log.getvalue()
+        assert n == 5  # delegate's return value, console contract unchanged
+
+    def test_log_failure_never_breaks_console(self):
+        class Broken:
+            def write(self, data):
+                raise OSError("disk full")
+
+            def flush(self):
+                raise OSError("disk full")
+
+        console = io.StringIO()
+        tee = run_mod._TeeStream(console, Broken())
+        assert tee.write("still works") == len("still works")
+        tee.flush()  # must not raise
+        assert console.getvalue() == "still works"
+
+    def test_attribute_proxy(self):
+        console, log = io.StringIO(), io.StringIO()
+        tee = run_mod._TeeStream(console, log)
+        # isatty / encoding probes must see the original stream's answers.
+        assert tee.isatty() == console.isatty()
+
+
+class TestSetupServerDiskLogging:
+    def test_opt_out_env(self, monkeypatch):
+        monkeypatch.setenv("UNSLOTH_STUDIO_NO_FILE_LOG", "1")
+        assert run_mod._setup_server_disk_logging() is None
+
+    def test_creates_log_and_enables_faulthandler(self, monkeypatch, tmp_path):
+        import faulthandler
+
+        monkeypatch.delenv("UNSLOTH_STUDIO_NO_FILE_LOG", raising = False)
+        monkeypatch.delenv("PYTHONFAULTHANDLER", raising = False)
+        # Both resolution paths (utils.paths.studio_root and the env
+        # fallback) honor UNSLOTH_STUDIO_HOME, so this redirects the log dir.
+        monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+        orig_out, orig_err = sys.stdout, sys.stderr
+        was_enabled = faulthandler.is_enabled()
+        try:
+            log_path = run_mod._setup_server_disk_logging()
+            assert log_path is not None
+            assert Path(log_path).is_file()
+            assert "logs" in str(log_path)
+            # faulthandler armed at the file; children inherit the env switch.
+            assert faulthandler.is_enabled()
+            import os
+
+            assert os.environ.get("PYTHONFAULTHANDLER") == "1"
+            print("tee-capture-marker")
+            sys.stdout.flush()
+            assert "tee-capture-marker" in Path(log_path).read_text(
+                encoding = "utf-8", errors = "replace"
+            )
+        finally:
+            sys.stdout, sys.stderr = orig_out, orig_err
+            if not was_enabled:
+                faulthandler.disable()
+
+    def test_run_server_wires_logging_before_main_import(self):
+        src = (Path(_BACKEND_DIR) / "run.py").read_text(encoding = "utf-8")
+        call_idx = src.index("_setup_server_disk_logging()", src.index("def run_server"))
+        main_import_idx = src.index("from main import app", src.index("def run_server"))
+        assert call_idx < main_import_idx, (
+            "disk logging must be armed before importing main so import-time "
+            "failures leave evidence on disk"
+        )
diff --git a/studio/backend/utils/hardware/amd.py b/studio/backend/utils/hardware/amd.py
index 39aafe0489..27dfe187cc 100644
--- a/studio/backend/utils/hardware/amd.py
+++ b/studio/backend/utils/hardware/amd.py
@@ -12,6 +12,7 @@ import math
 import os
 import platform
 import re
+import shutil
 import subprocess
 import sys
 from typing import Any, Optional
@@ -33,24 +34,85 @@ _amd_smi_consecutive_failures = 0
 _amd_smi_disabled = False
 
 
+def _hip_sdk_present() -> bool:
+    """True if a HIP SDK is detectable (hipinfo on PATH or under HIP_PATH/
+    ROCM_PATH), meaning amd-smi has a working runtime and runs un-elevated."""
+    if shutil.which("hipinfo"):
+        return True
+    for var in ("HIP_PATH", "HIP_PATH_57", "ROCM_PATH"):
+        root = os.environ.get(var)
+        if root and os.path.exists(os.path.join(root, "bin", "hipinfo.exe")):
+            return True
+    return False
+
+
+def _amd_smi_allowed() -> bool:
+    """Whether it is safe to spawn amd-smi here.
+
+    On Windows without a working HIP runtime, amd-smi elevates a child at
+    runtime -- popping a UAC/DiskPart prompt that RunAsInvoker can't suppress
+    (its manifest is asInvoker). So only call it on Windows with a HIP SDK
+    present or UNSLOTH_ENABLE_AMD_SMI=1. Linux amd-smi never elevates.
+    """
+    if platform.system() != "Windows":
+        return True
+    flag = os.environ.get("UNSLOTH_ENABLE_AMD_SMI", "").strip().lower()
+    if flag in ("1", "true", "yes", "on"):
+        return True
+    if flag in ("0", "false", "no", "off"):
+        return False
+    return _hip_sdk_present()
+
+
 def _run_amd_smi(*args: str, timeout: int = _AMD_SMI_DEFAULT_TIMEOUT) -> Optional[Any]:
     """Run amd-smi with the given args and return parsed JSON, or None."""
     global _amd_smi_consecutive_failures, _amd_smi_disabled
     if _amd_smi_disabled:
         return None
+    if not _amd_smi_allowed():
+        # Permanently skip amd-smi on Windows w/o a HIP SDK: every call would
+        # pop a UAC/DiskPart prompt (see _amd_smi_allowed). VRAM polling is then
+        # unavailable, but that beats the prompt. Opt back in with
+        # UNSLOTH_ENABLE_AMD_SMI=1.
+        if not _amd_smi_disabled:
+            logger.info(
+                "amd-smi disabled on Windows (no HIP SDK detected) to avoid a "
+                "UAC/DiskPart elevation prompt; GPU VRAM polling unavailable. "
+                "Set UNSLOTH_ENABLE_AMD_SMI=1 to force amd-smi."
+            )
+            _amd_smi_disabled = True
+        return None
+    if shutil.which("amd-smi") is None:
+        # amd-smi does not exist on Windows (neither Adrenalin nor the HIP SDK
+        # ship a CLI) and can be absent on minimal Linux installs. Disable the
+        # poller in one step instead of burning the 3-strike circuit breaker
+        # on guaranteed FileNotFoundError spawns. Studio's VRAM display falls
+        # back to torch mem_get_info.
+        if not _amd_smi_disabled:
+            logger.info(
+                "amd-smi not found on PATH; GPU utilization polling via "
+                "amd-smi unavailable (VRAM falls back to torch mem_get_info)."
+            )
+            _amd_smi_disabled = True
+        return None
+    _amd_env = child_env_without_native_path_secret()
+    if platform.system() == "Windows":
+        # RunAsInvoker belt-and-suspenders for any manifest-elevating helper;
+        # the real guard is _amd_smi_allowed() above. Mirrors install scripts.
+        _amd_env = {**_amd_env, "__COMPAT_LAYER": "RunAsInvoker"}
     try:
         result = subprocess.run(
             ["amd-smi", *args, "--json"],
             capture_output = True,
             text = True,
             timeout = timeout,
-            env = child_env_without_native_path_secret(),
+            env = _amd_env,
             **windows_hidden_subprocess_kwargs(),
         )
     except (OSError, subprocess.TimeoutExpired) as e:
         if isinstance(e, FileNotFoundError):
-            # amd-smi ships with Adrenalin, not the HIP SDK; absence is expected
-            # on HIP SDK-only Windows setups.
+            # Raced a PATH change after the which() check above; absence is
+            # expected on Windows (no AMD product ships an amd-smi CLI there).
             logger.debug("amd-smi not found (not in PATH): %s", e)
         else:
             logger.warning("amd-smi query failed: %s", e)
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 5d3f0ed339..4509ea58ed 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -47,6 +47,38 @@ EXIT_FALLBACK = 2
 EXIT_ERROR = 1
 EXIT_BUSY = 3
 
+# DiskPart-prompt suppression. RunAsInvoker does NOT stop amd-smi's runtime
+# elevation (its manifest is asInvoker), so this is just harmless belt-and-
+# suspenders for manifest-elevating tools. The real guard is _amd_smi_allowed():
+# we don't spawn amd-smi on Windows w/o a HIP SDK (or opt-in).
+if platform.system() == "Windows":
+    os.environ.setdefault("__COMPAT_LAYER", "RunAsInvoker")
+
+
+def _amd_smi_allowed() -> bool:
+    """Whether it is safe to spawn amd-smi here.
+
+    On Windows w/o a working HIP runtime, amd-smi elevates a child and pops a
+    UAC/DiskPart prompt RunAsInvoker can't suppress. Only call it on Windows
+    when a HIP SDK is detectable (hipinfo present) or UNSLOTH_ENABLE_AMD_SMI=1;
+    Linux/macOS always allowed. When skipped, the gfx arch still arrives via the
+    forwarded --rocm-gfx, so prebuilt selection is unaffected.
+    """
+    if platform.system() != "Windows":
+        return True
+    flag = os.environ.get("UNSLOTH_ENABLE_AMD_SMI", "").strip().lower()
+    if flag in ("1", "true", "yes", "on"):
+        return True
+    if flag in ("0", "false", "no", "off"):
+        return False
+    if shutil.which("hipinfo"):
+        return True
+    for _var in ("HIP_PATH", "HIP_PATH_57", "ROCM_PATH"):
+        _root = os.environ.get(_var)
+        if _root and os.path.isfile(os.path.join(_root, "bin", "hipinfo.exe")):
+            return True
+    return False
+
 
 def windows_hidden_subprocess_kwargs() -> dict[str, object]:
     """Return Windows-only subprocess kwargs that suppress console windows."""
@@ -2672,6 +2704,15 @@ def run_capture(
     check: bool = False,
     env: dict[str, str] | None = None,
 ) -> subprocess.CompletedProcess[str]:
+    # amd-smi on Windows auto-elevates and pops a UAC/DiskPart prompt mid-install;
+    # RunAsInvoker forces it un-elevated. Callers already fall back to WMI/name
+    # detection. Mirrors install.ps1's Invoke-AmdSmiNoElevate; Windows-only.
+    if (
+        command
+        and platform.system() == "Windows"
+        and os.path.basename(command[0]).lower().startswith("amd-smi")
+    ):
+        env = {**(os.environ if env is None else env), "__COMPAT_LAYER": "RunAsInvoker"}
     result = subprocess.run(
         command,
         capture_output = True,
@@ -2857,6 +2898,13 @@ def detect_host() -> HostInfo:
     has_rocm = False
     rocm_gfx_target: str | None = None
     if is_linux:
+        # WSL2 ROCDXG: the system rocminfo enumerates the GPU over /dev/dxg
+        # only when HSA_ENABLE_DXG_DETECTION=1 (a no-op on bare metal), and
+        # rocminfo can live only under /opt/rocm/bin (the profile.d PATH
+        # drop-in reaches login shells only). Probe accordingly or a ROCDXG
+        # WSL host is misdetected as CPU-only.
+        _dxg_probe_env = {**os.environ}
+        _dxg_probe_env.setdefault("HSA_ENABLE_DXG_DETECTION", "1")
         for _cmd, _check in (
             # rocminfo: a real gfx GPU id (3-4 chars, nonzero first digit).
             # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines
@@ -2869,10 +2917,18 @@ def detect_host() -> HostInfo:
             (["amd-smi", "list"], _amd_smi_has_gpu),
         ):
             _exe = shutil.which(_cmd[0])
+            if not _exe and _cmd[0] == "rocminfo":
+                _opt_rocminfo = "/opt/rocm/bin/rocminfo"
+                if os.access(_opt_rocminfo, os.X_OK):
+                    _exe = _opt_rocminfo
             if not _exe:
                 continue
             try:
-                _result = run_capture([_exe, *_cmd[1:]], timeout = 10)
+                _result = run_capture(
+                    [_exe, *_cmd[1:]],
+                    timeout = 10,
+                    env = _dxg_probe_env if _cmd[0] == "rocminfo" else None,
+                )
             except Exception:
                 continue
             if _result.returncode == 0 and _result.stdout.strip():
@@ -2897,12 +2953,20 @@ def detect_host() -> HostInfo:
                     _candidate = os.path.join(_root, "bin", f"{name}.exe")
                     if os.path.isfile(_candidate):
                         return _candidate
+            # AMD torch wheels ship hipInfo.exe into the venv Scripts dir
+            # (next to python.exe) -- resolvable on driver-only hosts where no
+            # SDK dir exists, so a standalone rerun can still detect the GPU.
+            _venv_candidate = os.path.join(os.path.dirname(sys.executable), f"{name}.exe")
+            if os.path.isfile(_venv_candidate):
+                return _venv_candidate
             return None
 
-        for _cmd, _check in (
-            (["hipinfo"], lambda out: "gcnarchname" in out.lower()),
-            (["amd-smi", "list"], _amd_smi_has_gpu),
-        ):
+        _win_probes = [(["hipinfo"], lambda out: "gcnarchname" in out.lower())]
+        if _amd_smi_allowed():
+            # Skipped on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt);
+            # gfx arch still arrives via --rocm-gfx, so has_rocm is set by override.
+            _win_probes.append((["amd-smi", "list"], _amd_smi_has_gpu))
+        for _cmd, _check in _win_probes:
             _exe = _resolve_exe(_cmd[0])
             if not _exe:
                 continue
@@ -3522,16 +3586,12 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
                 return int(parts[0]), int(parts[1])
         except Exception:
             pass
-    amd_smi = shutil.which("amd-smi")
+    amd_smi = shutil.which("amd-smi") if _amd_smi_allowed() else None
     if amd_smi:
         try:
-            result = subprocess.run(
-                [amd_smi, "version"],
-                stdout = subprocess.PIPE,
-                stderr = subprocess.DEVNULL,
-                text = True,
-                timeout = 5,
-            )
+            # Off on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt);
+            # hipconfig below and the version-file reads above cover that case.
+            result = run_capture([amd_smi, "version"], timeout = 5)
             if result.returncode == 0:
                 m = re.search(r"ROCm version:\s*(\d+)\.(\d+)", result.stdout)
                 if m:
@@ -4809,6 +4869,46 @@ def validated_validation_model_bytes(data: bytes) -> bytes:
     return data
 
 
+def _hf_resolve_url_parts(url: str) -> tuple[str, str, str] | None:
+    """Parse a huggingface.co .../resolve/<rev>/<path> URL into
+    (repo_id, revision, filename); None if it is not such a URL."""
+    try:
+        parsed = urllib.parse.urlparse(url)
+    except Exception:
+        return None
+    if (parsed.netloc or "").lower() not in ("huggingface.co", "www.huggingface.co"):
+        return None
+    parts = parsed.path.strip("/").split("/")
+    # <owner>/<name>/resolve/<rev>/<path...>
+    if len(parts) >= 5 and parts[2] == "resolve":
+        return f"{parts[0]}/{parts[1]}", parts[3], "/".join(parts[4:])
+    return None
+
+
+def _fetch_validation_model_bytes() -> bytes:
+    """Fetch the tiny GGUF validation model. Prefer huggingface_hub (completes
+    TLS chains via AIA fetching that bare urllib can't on some Windows/proxy
+    setups); fall back to the direct URL when hf_hub is unavailable or fails."""
+    parts = _hf_resolve_url_parts(TEST_MODEL_URL)
+    if parts is not None:
+        repo_id, revision, filename = parts
+        try:
+            from huggingface_hub import hf_hub_download
+            local = hf_hub_download(repo_id = repo_id, filename = filename, revision = revision)
+            return validated_validation_model_bytes(Path(local).read_bytes())
+        except Exception as exc:
+            log(
+                f"huggingface_hub fetch of validation model failed ({exc}); "
+                "falling back to direct URL"
+            )
+    return validated_validation_model_bytes(
+        download_bytes(
+            TEST_MODEL_URL,
+            progress_label = f"Downloading {download_label_from_url(TEST_MODEL_URL)}",
+        )
+    )
+
+
 def download_validation_model(path: Path, cache_path: Path | None = None) -> None:
     try:
         data: bytes | None = None
@@ -4821,12 +4921,7 @@ def download_validation_model(path: Path, cache_path: Path | None = None) -> Non
                 data = None
         if data is None:
             log("downloading tiny GGUF validation model")
-            data = validated_validation_model_bytes(
-                download_bytes(
-                    TEST_MODEL_URL,
-                    progress_label = f"Downloading {download_label_from_url(TEST_MODEL_URL)}",
-                )
-            )
+            data = _fetch_validation_model_bytes()
             if cache_path is not None:
                 atomic_write_bytes(cache_path, data)
         atomic_write_bytes(path, data)
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 2c8f6228d4..e742d85eed 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -40,6 +40,14 @@ IS_MACOS = sys.platform == "darwin"
 IS_MAC_INTEL = IS_MACOS and platform.machine() == "x86_64"
 IS_MAC_ARM = IS_MACOS and platform.machine() == "arm64"
 IS_LINUX = sys.platform.startswith("linux")
+
+# DiskPart-prompt suppression: amd-smi auto-elevates on Windows, popping a
+# UAC/DiskPart prompt mid-install. This installer only spawns probes and pip/uv
+# (none need elevation), so set __COMPAT_LAYER=RunAsInvoker process-wide -- every
+# amd-smi subprocess then runs un-elevated, no per-call guard needed. setup.ps1
+# keeps per-call guards since it ALSO spawns winget installers that need elevation.
+if IS_WINDOWS:
+    os.environ.setdefault("__COMPAT_LAYER", "RunAsInvoker")
 # torchcodec ships wheels only for manylinux_2_28_x86_64, macosx_12_0_arm64,
 # and win_amd64. On other hosts the audio extras must be filtered out (the
 # extras-no-deps step would otherwise fail), regardless of NO_TORCH.
@@ -137,6 +145,39 @@ def _bnb_rocm_prerelease_url() -> str | None:
     return _BNB_ROCM_PRERELEASE_URLS.get(arch)
 
 
+def _amd_smi_env() -> dict[str, str] | None:
+    """On Windows, env with __COMPAT_LAYER=RunAsInvoker; None elsewhere.
+    NB: RunAsInvoker doesn't stop amd-smi's runtime elevation (its manifest is
+    asInvoker -- it elevates a child via ShellExecute). The real guard is
+    _amd_smi_allowed() below; this is harmless belt-and-suspenders."""
+    if platform.system() != "Windows":
+        return None
+    return {**os.environ, "__COMPAT_LAYER": "RunAsInvoker"}
+
+
+def _amd_smi_allowed() -> bool:
+    """Whether it is safe to spawn amd-smi here.
+
+    On Windows w/o a working HIP runtime, amd-smi elevates a child and pops a
+    UAC/DiskPart prompt RunAsInvoker can't suppress. Only call it on Windows with
+    a HIP SDK (hipinfo present) or UNSLOTH_ENABLE_AMD_SMI=1; Linux/macOS always.
+    """
+    if platform.system() != "Windows":
+        return True
+    flag = os.environ.get("UNSLOTH_ENABLE_AMD_SMI", "").strip().lower()
+    if flag in ("1", "true", "yes", "on"):
+        return True
+    if flag in ("0", "false", "no", "off"):
+        return False
+    if shutil.which("hipinfo"):
+        return True
+    for _var in ("HIP_PATH", "HIP_PATH_57", "ROCM_PATH"):
+        _root = os.environ.get(_var)
+        if _root and os.path.isfile(os.path.join(_root, "bin", "hipinfo.exe")):
+            return True
+    return False
+
+
 def _detect_rocm_version() -> tuple[int, int] | None:
     """Return (major, minor) of the installed ROCm stack, or None."""
     rocm_root = os.environ.get("ROCM_PATH") or "/opt/rocm"
@@ -155,8 +196,10 @@ def _detect_rocm_version() -> tuple[int, int] | None:
         except Exception:
             pass
 
-    # Try amd-smi version (outputs "... | ROCm version: X.Y.Z")
-    amd_smi = shutil.which("amd-smi")
+    # Try amd-smi version (outputs "... | ROCm version: X.Y.Z").
+    # Gated off on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt);
+    # hipconfig below covers that case.
+    amd_smi = shutil.which("amd-smi") if _amd_smi_allowed() else None
     if amd_smi:
         try:
             result = subprocess.run(
@@ -165,6 +208,7 @@ def _detect_rocm_version() -> tuple[int, int] | None:
                 stderr = subprocess.DEVNULL,
                 text = True,
                 timeout = 5,
+                env = _amd_smi_env(),
             )
             if result.returncode == 0:
                 import re
@@ -282,6 +326,14 @@ def _detect_windows_gfx_arch() -> str | None:
                 if os.path.isfile(_candidate):
                     hipinfo = _candidate
                     break
+    if not hipinfo:
+        # 2b. AMD torch wheels ship hipInfo.exe into the venv Scripts dir
+        # (next to python.exe); resolvable even on driver-only hosts with no
+        # SDK install at all. Lets `studio update` re-detect the arch on a
+        # venv that already has the AMD wheel.
+        _venv_hipinfo = os.path.join(os.path.dirname(sys.executable), "hipInfo.exe")
+        if os.path.isfile(_venv_hipinfo):
+            hipinfo = _venv_hipinfo
     if hipinfo:
         try:
             result = subprocess.run(
@@ -304,7 +356,9 @@ def _detect_windows_gfx_arch() -> str | None:
             pass
 
     # 3. amd-smi fallback -- runtime-only Radeon installs ship amd-smi but no hipinfo.
-    amd_smi = shutil.which("amd-smi")
+    # Gated off on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt); the arch
+    # arrives via --rocm-gfx / name inference there, so this is only needed when safe.
+    amd_smi = shutil.which("amd-smi") if _amd_smi_allowed() else None
     if amd_smi:
         for _args in (("static", "--asic"), ("list",)):
             try:
@@ -313,6 +367,7 @@ def _detect_windows_gfx_arch() -> str | None:
                     stdout = subprocess.PIPE,
                     stderr = subprocess.DEVNULL,
                     timeout = 10,
+                    env = _amd_smi_env(),
                 )
                 if result.returncode != 0:
                     continue
@@ -330,6 +385,74 @@ def _detect_windows_gfx_arch() -> str | None:
                     return _pick
             except Exception:
                 continue
+
+    # 4. Last resort: GPU marketing name via WMI → arch table. Driver-only
+    #    hosts (Adrenalin, no HIP SDK) have neither hipinfo nor amd-smi
+    #    (amd-smi does not exist on Windows at all), but the display driver
+    #    always knows the GPU name. Mirrors setup.ps1's $nameArchTable so a
+    #    standalone `studio update` can repair a CPU-only venv on such hosts.
+    try:
+        result = subprocess.run(
+            [
+                "powershell.exe",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                "(Get-CimInstance Win32_VideoController).Name",
+            ],
+            stdout = subprocess.PIPE,
+            stderr = subprocess.DEVNULL,
+            timeout = 30,
+            creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+        if result.returncode == 0:
+            _tokens = []
+            for _name in result.stdout.decode(errors = "replace").splitlines():
+                _arch = _gfx_arch_from_gpu_name(_name.strip())
+                if _arch:
+                    _tokens.append(_arch)
+            _pick = _dedup_pick(_tokens)
+            if _pick:
+                print(f"   gfx arch inferred from GPU name (WMI): {_pick}")
+                return _pick
+    except Exception:
+        pass
+    return None
+
+
+# GPU marketing-name → gfx arch table, mirroring setup.ps1's $nameArchTable.
+# Most-specific first; first match wins. Covers only arches the lemonade-sdk
+# prebuilts / AMD Windows torch indexes support; unknown names return None
+# (callers then fall back cleanly to CPU).
+_WIN_GPU_NAME_ARCH_TABLE: "list[tuple[str, str]]" = [
+    (r"9070 XT|9080", "gfx1201"),  # RDNA 4 (Radeon RX 9070 XT / 9080)
+    (r"9070|9060", "gfx1200"),  # RDNA 4 (Radeon RX 9070 / 9060)
+    # RDNA 3.5 (Strix Halo: Radeon 8060S/8050S/8040S iGPU, Ryzen AI Max+)
+    (r"8060S|8050S|8040S|Strix Halo|Ryzen AI Max|AI Max", "gfx1151"),
+    # RDNA 3.5 (Strix/Krackan Point: Radeon 890M/880M iGPU, Ryzen AI 9 HX 370/375)
+    (
+        r"890M|880M|860M|840M|Strix Point|Krackan|HX 37[05]|AI 9 HX|AI 9 36[05]"
+        r"|AI 7 35[05]|AI 5 34[05]|AI 7 PRO 35|AI 5 33",
+        "gfx1150",
+    ),
+    # RDNA 3 desktop / workstation (Navi 31)
+    (r"RX 7900|RX 7800|RX 7700(?!S)|PRO W7900|PRO W7800|PRO W7700", "gfx1100"),
+    (r"RX 7600|RX 7700S|RX 7650|PRO W7600|PRO W7500|PRO V710", "gfx1102"),  # Navi 33
+    # RDNA 3 iGPU (Phoenix / Hawk Point)
+    (r"780M|760M|740M|Phoenix|Hawk Point|Z1 Extreme|Z2 Extreme", "gfx1103"),
+    (r"RX 6900|RX 6800|RX 6750|RX 6700|PRO W6800|PRO W6900", "gfx1030"),  # Navi 21
+    (r"RX 6650|RX 6600|PRO W6600|PRO W6650", "gfx1032"),  # Navi 23
+    (r"RX 6500|RX 6400|RX 6300|PRO W6400|PRO W6500", "gfx1034"),  # Navi 24
+]
+
+
+def _gfx_arch_from_gpu_name(name: str) -> "str | None":
+    """Map a GPU marketing name to its gfx arch via _WIN_GPU_NAME_ARCH_TABLE."""
+    if not name:
+        return None
+    for _pat, _arch in _WIN_GPU_NAME_ARCH_TABLE:
+        if re.search(_pat, name, re.IGNORECASE):
+            return _arch
     return None
 
 
@@ -386,6 +509,10 @@ def _has_rocm_gpu() -> bool:
         exe = shutil.which(cmd[0])
         if not exe:
             continue
+        # Skip amd-smi on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt);
+        # rely on rocminfo / the sysfs fallback there.
+        if cmd[0] == "amd-smi" and not _amd_smi_allowed():
+            continue
         try:
             result = subprocess.run(
                 [exe, *cmd[1:]],
@@ -393,6 +520,7 @@ def _has_rocm_gpu() -> bool:
                 stderr = subprocess.DEVNULL,
                 text = True,
                 timeout = 10,
+                env = _amd_smi_env() if cmd[0] == "amd-smi" else None,
             )
         except Exception:
             continue
@@ -454,7 +582,8 @@ def _detect_amd_gfx_codes() -> list[str]:
     probes: list[list[str]] = []
     if shutil.which("rocminfo"):
         probes.append(["rocminfo"])
-    if shutil.which("amd-smi"):
+    # Gate amd-smi off on Windows w/o a HIP SDK (avoids the UAC/DiskPart prompt).
+    if shutil.which("amd-smi") and _amd_smi_allowed():
         probes.append(["amd-smi", "list"])
         probes.append(["amd-smi", "static", "--asic"])
     for cmd in probes:
@@ -465,6 +594,7 @@ def _detect_amd_gfx_codes() -> list[str]:
                 stderr = subprocess.DEVNULL,
                 text = True,
                 timeout = 15,
+                env = _amd_smi_env() if cmd[0] == "amd-smi" else None,
             )
         except Exception:
             continue
@@ -515,6 +645,18 @@ def _install_bnb_windows_rocm() -> bool:
     if "BNB_ROCM_VERSION" not in os.environ:
         _ver = _detect_bnb_rocm_dll_ver() or "72"
         os.environ["BNB_ROCM_VERSION"] = _ver
+    # Make hipInfo.exe (shipped into the venv Scripts dir by the AMD torch
+    # wheel) resolvable via PATH for this process and every child python the
+    # installer spawns (import checks, precompile): bitsandbytes runs
+    # `hipinfo.exe` at import time to detect the GPU arch and logs a scary
+    # (harmless) ERROR + WARNING on every import when it is missing. The venv
+    # Scripts dir is on PATH only when the venv is activated, which neither
+    # Studio nor the installer's child processes ever do.
+    _scripts_dir = os.path.dirname(sys.executable)
+    if os.path.isfile(os.path.join(_scripts_dir, "hipInfo.exe")) and not shutil.which(
+        "hipinfo.exe"
+    ):
+        os.environ["PATH"] = _scripts_dir + os.pathsep + os.environ.get("PATH", "")
     return True
 
 
@@ -1569,6 +1711,12 @@ def install_python_stack() -> int:
             _wexe = shutil.which(_wcmd[0])
             if not _wexe:
                 continue
+            # Skip amd-smi on Windows w/o a HIP SDK (avoids the UAC/DiskPart
+            # prompt), as _has_rocm_gpu()/_detect_amd_gfx_codes do. The only loss
+            # is the best-effort "AMD GPU detected" note; ROCm-torch state below
+            # comes from the install itself.
+            if _wcmd[0] == "amd-smi" and not _amd_smi_allowed():
+                continue
             try:
                 _wr = subprocess.run(
                     [_wexe, *_wcmd[1:]],
@@ -1576,6 +1724,7 @@ def install_python_stack() -> int:
                     stderr = subprocess.DEVNULL,
                     text = True,
                     timeout = 10,
+                    env = _amd_smi_env() if _wcmd[0] == "amd-smi" else None,
                 )
             except Exception:
                 continue
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 9a919e31e3..ce94f651f8 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -700,6 +700,55 @@ if (-not $HasNvidiaSmi) {
         }
     }
 }
+# ── Helper: run amd-smi without triggering a UAC elevation prompt ──
+# amd-smi on Windows auto-elevates to read GPU/APU memory, surfacing a confusing
+# DiskPart UAC prompt mid-install (Studio backend amd.py hits the same). RunAsInvoker
+# forces it (and helpers it spawns) to run un-elevated; on failure the WMI name ->
+# gfx fallback still resolves the arch.
+function Invoke-AmdSmiNoElevate {
+    param(
+        [Parameter(Mandatory = $true, Position = 0)][string]$Exe,
+        [Parameter(Position = 1)][string[]]$SmiArgs = @(),
+        [int]$TimeoutSec = 30
+    )
+    # RunAsInvoker blocks the auto-elevation/UAC prompt; the timeout bounds a flaky
+    # amd-smi that can otherwise spin for minutes (30s mirrors the backend amd.py).
+    $prevCompat = [Environment]::GetEnvironmentVariable('__COMPAT_LAYER', 'Process')
+    $env:__COMPAT_LAYER = 'RunAsInvoker'
+    try {
+        # [Process]::Start, NOT Start-Process -PassThru: the latter leaves .ExitCode
+        # $null after WaitForExit on PS 5.1, so $LASTEXITCODE (checked by callers)
+        # reads non-zero and kills detection. Async reads drain the pipes (no
+        # deadlock); amd-smi args have no spaces so a plain join is safe.
+        $psi = New-Object System.Diagnostics.ProcessStartInfo
+        $psi.FileName = $Exe
+        $psi.Arguments = ($SmiArgs -join ' ')
+        $psi.UseShellExecute = $false
+        $psi.RedirectStandardOutput = $true
+        $psi.RedirectStandardError = $true
+        $psi.CreateNoWindow = $true
+        $proc = [System.Diagnostics.Process]::Start($psi)
+        $outTask = $proc.StandardOutput.ReadToEndAsync()
+        $errTask = $proc.StandardError.ReadToEndAsync()
+        if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
+            try { $proc.Kill() } catch {}
+            $global:LASTEXITCODE = 124
+            return ""
+        }
+        $global:LASTEXITCODE = $proc.ExitCode
+        return ($outTask.Result + "`n" + $errTask.Result)
+    } catch {
+        $global:LASTEXITCODE = 1
+        return ""
+    } finally {
+        if ($null -eq $prevCompat) {
+            Remove-Item Env:__COMPAT_LAYER -ErrorAction SilentlyContinue
+        } else {
+            $env:__COMPAT_LAYER = $prevCompat
+        }
+    }
+}
+
 # ── AMD ROCm detection (Windows): probe hipinfo/amd-smi for actual GPU ──
 $HasROCm = $false
 $HipSdkInstalled = $false   # HIP SDK binary found (independent of device accessibility)
@@ -750,14 +799,24 @@ if (-not $HasNvidiaSmi) {
         } catch {}
     }
     # amd-smi fallback: HIP runtime present but hipinfo unavailable (no full HIP SDK).
-    # Confirms GPU visibility via 'list', then attempts 'static --asic' to extract
-    # the gfx arch that hipinfo would have provided.  Critical for Strix Halo
-    # (gfx1151) and other iGPUs where only the HIP runtime is installed.
-    if (-not $HasROCm) {
+    # 'list' confirms GPU visibility, 'static --asic' extracts the gfx arch hipinfo
+    # would give. Critical for Strix Halo (gfx1151) and other HIP-runtime-only iGPUs.
+    #
+    # BUT on hosts without a working HIP runtime amd-smi elevates a child at runtime,
+    # popping a UAC/DiskPart prompt RunAsInvoker can't suppress (its manifest is
+    # asInvoker; even 'amd-smi version' hangs). So only probe when a HIP SDK is present
+    # (hipinfo found -> un-elevated) or the user opts in; else fall through to WMI name
+    # inference (enough to pick ROCm wheels + lemonade llama.cpp).
+    # An explicit opt-out (UNSLOTH_ENABLE_AMD_SMI=0/false/no/off) wins over the HIP-SDK
+    # heuristic: a HIP SDK binary with a broken runtime can still pop the prompt, so
+    # $HipSdkInstalled must NOT silently re-enable it.
+    $amdSmiOptOut = $env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(0|false|no|off)$'
+    $amdSmiAllowed = (-not $amdSmiOptOut) -and ($HipSdkInstalled -or ($env:UNSLOTH_ENABLE_AMD_SMI -match '^(?i)(1|true|yes|on)$'))
+    if (-not $HasROCm -and $amdSmiAllowed) {
         $amdSmiExe = Get-Command "amd-smi" -ErrorAction SilentlyContinue
         if ($amdSmiExe) {
             try {
-                $smiOut = & $amdSmiExe.Source list 2>&1 | Out-String
+                $smiOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('list')
                 if ($LASTEXITCODE -eq 0 -and $smiOut -match "(?im)^GPU\s*[:\[]\s*\d") {
                     $HasROCm = $true
                     # Attempt 1: newer amd-smi versions embed the gfx arch in list output.
@@ -791,7 +850,7 @@ if (-not $HasNvidiaSmi) {
                         # Attempt 2: 'static --asic' exposes ASIC details on ROCm 6+,
                         # including the GFX target needed for wheel index selection.
                         $smiAsicOut = ""
-                        try { $smiAsicOut = & $amdSmiExe.Source static --asic 2>&1 | Out-String } catch {}
+                        try { $smiAsicOut = Invoke-AmdSmiNoElevate $amdSmiExe.Source @('static','--asic') } catch {}
                         if ($smiAsicOut -match "(?i)\b(gfx\d+[a-z]?)\b") {
                             $script:ROCmGfxArch = $Matches[1].ToLower()
                             $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
@@ -819,27 +878,34 @@ if (-not $HasNvidiaSmi) {
         } catch {}
     }
     # ── Arch resolution: env-var override → name inference ──────────────────
-    # Runs after all probe methods.  Covers users whose amd-smi version is too
-    # old to report the GFX target and who don't have hipinfo (HIP-runtime-only
-    # installs, common on Strix Halo / iGPU systems).
-    if ($HasROCm -and -not $script:ROCmGfxArch) {
+    # Runs after all probes, even when none confirmed a ROCm runtime ($HasROCm false):
+    # the Adrenalin driver alone runs the lemonade-sdk llama.cpp prebuilt (bundles its
+    # own runtime), and all it needs is the gfx arch, inferable from the WMI GPU name.
+    # Resolving it here lets setup.ps1 forward --rocm-gfx so a GPU llama.cpp is pulled
+    # instead of CPU. (PyTorch ROCm wheels still require a HIP SDK -- gated on $HasROCm
+    # below -- so this only affects llama.cpp / inference.)
+    if (-not $script:ROCmGfxArch) {
         # 1. Manual override: set UNSLOTH_ROCM_GFX_ARCH=gfx1151 before running.
         if ($env:UNSLOTH_ROCM_GFX_ARCH) {
             $script:ROCmGfxArch = $env:UNSLOTH_ROCM_GFX_ARCH.Trim().ToLower()
             $ROCmGpuLabel = "AMD ROCm ($script:ROCmGfxArch)"
             substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $script:ROCmGfxArch" "Cyan"
         }
-        # 2. Best-effort name → arch lookup from marketing name (amd-smi / WMI).
-        #    Ordered most-specific first; first match wins.
+        # 2. Best-effort name → arch lookup (amd-smi / WMI). Most-specific first,
+        #    first match wins. Covers only arches the lemonade-sdk prebuilts support
+        #    (gfx120X/110X/1151/1150/103X); unknown names fall back cleanly to CPU.
         elseif ($ROCmGpuLabel) {
             $nameArchTable = @(
-                @{ P = "9070 XT|9080";                                         A = "gfx1201" }  # RDNA 4
-                @{ P = "9070|9060";                                            A = "gfx1200" }  # RDNA 4
-                @{ P = "8060S|890M|Strix Halo|HX 37[05]|HX 38[05]|AI 9 HX";    A = "gfx1151" }  # RDNA 3.5 iGPU (Strix Halo / Radeon 8060S retail)
-                @{ P = "880M|Strix Point|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]"; A = "gfx1150" }  # RDNA 3.5 iGPU (Strix Point)
-                @{ P = "RX 7900|RX 7800|RX 7700(?! S)";                        A = "gfx1100" }  # RDNA 3 desktop
-                @{ P = "RX 7600";                                              A = "gfx1102" }  # RDNA 3
-                @{ P = "780M|760M|740M|Phoenix";                               A = "gfx1103" }  # RDNA 3 iGPU (Phoenix)
+                @{ P = "9070 XT|9080";                                        A = "gfx1201" }  # RDNA 4 (Radeon RX 9070 XT / 9080)
+                @{ P = "9070|9060";                                           A = "gfx1200" }  # RDNA 4 (Radeon RX 9070 / 9060)
+                @{ P = "8060S|8050S|8040S|Strix Halo|Ryzen AI Max|AI Max"; A = "gfx1151" }  # RDNA 3.5 (Strix Halo: Radeon 8060S/8050S/8040S iGPU, Ryzen AI Max+)
+                @{ P = "890M|880M|860M|840M|Strix Point|Krackan|HX 37[05]|AI 9 HX|AI 9 36[05]|AI 7 35[05]|AI 5 34[05]|AI 7 PRO 35|AI 5 33"; A = "gfx1150" }  # RDNA 3.5 (Strix/Krackan Point: Radeon 890M/880M iGPU, Ryzen AI 9 HX 370/375)
+                @{ P = "RX 7900|RX 7800|RX 7700(?!S)|PRO W7900|PRO W7800|PRO W7700"; A = "gfx1100" }  # RDNA 3 desktop / workstation (Navi 31)
+                @{ P = "RX 7600|RX 7700S|RX 7650|PRO W7600|PRO W7500|PRO V710"; A = "gfx1102" }  # RDNA 3 (Navi 33)
+                @{ P = "780M|760M|740M|Phoenix|Hawk Point|Z1 Extreme|Z2 Extreme"; A = "gfx1103" }  # RDNA 3 iGPU (Phoenix / Hawk Point)
+                @{ P = "RX 6900|RX 6800|RX 6750|RX 6700|PRO W6800|PRO W6900";  A = "gfx1030" }  # RDNA 2 (Navi 21) -- lemonade gfx103X
+                @{ P = "RX 6650|RX 6600|PRO W6600|PRO W6650";                  A = "gfx1032" }  # RDNA 2 (Navi 23) -- lemonade gfx103X
+                @{ P = "RX 6500|RX 6400|RX 6300|PRO W6400|PRO W6500";          A = "gfx1034" }  # RDNA 2 (Navi 24) -- lemonade gfx103X
             )
             foreach ($row in $nameArchTable) {
                 if ($ROCmGpuLabel -match $row.P) {
@@ -881,11 +947,11 @@ if (-not $HasNvidiaSmi) {
                 }
             } catch {}
         }
-        if (-not $script:ROCmVersion) {
+        if (-not $script:ROCmVersion -and $amdSmiAllowed) {
             $amdSmiVer = Get-Command "amd-smi" -ErrorAction SilentlyContinue
             if ($amdSmiVer) {
                 try {
-                    $smiVerOut = & $amdSmiVer.Source version 2>&1 | Out-String
+                    $smiVerOut = Invoke-AmdSmiNoElevate $amdSmiVer.Source @('version')
                     if ($LASTEXITCODE -eq 0 -and $smiVerOut -match 'ROCm version:\s*(\d+\.\d+)') { $script:ROCmVersion = $Matches[1] }
                 } catch {}
             }
@@ -910,11 +976,20 @@ if ($HasNvidiaSmi) {
     substep "       This is a driver issue, not an SDK issue." "Yellow"
     substep "       Ensure the ROCm compute driver is installed alongside the display driver:" "Yellow"
     substep "       https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
+} elseif ($script:ROCmGfxArch) {
+    # Known arch: PyTorch comes from AMD's bundled-runtime ROCm wheels (repo.amd.com),
+    # which ship their own runtime -- HIP SDK optional (only adds the system toolchain).
+    Write-Host ""
+    step "gpu" "AMD ROCm ($script:ROCmGfxArch)" "Cyan"
+    substep "Detected: $ROCmGpuLabel" "Cyan"
+    substep "GPU PyTorch uses AMD's bundled-runtime ROCm wheels -- HIP SDK not required (optional)." "Cyan"
+    Write-Host ""
 } elseif ($ROCmGpuLabel) {
     Write-Host ""
-    step "gpu" "AMD GPU detected -- HIP SDK not found" "Yellow"
+    step "gpu" "AMD GPU detected -- arch unknown" "Yellow"
     substep "Detected: $ROCmGpuLabel" "Yellow"
-    substep "Install the HIP SDK for ROCm GPU inference:" "Yellow"
+    substep "Could not determine the GPU arch (gfx...). Install the HIP SDK or set" "Yellow"
+    substep "UNSLOTH_ROCM_GFX_ARCH to enable GPU ROCm PyTorch:" "Yellow"
     substep "https://rocm.docs.amd.com/en/latest/deploy/windows/index.html" "Yellow"
     Write-Host ""
 } else {
@@ -1192,7 +1267,7 @@ if (-not $NvccPath -and $RequireOrExit) {
             $drMajor = [int]$DriverMaxCuda.Split('.')[0]
             $AvailableVersions = @()
             try {
-                $rawOutput = winget show Nvidia.CUDA --versions --accept-source-agreements 2>&1 | Out-String
+                $rawOutput = winget show Nvidia.CUDA --versions --source winget --accept-source-agreements 2>&1 | Out-String
                 # Parse version lines (e.g. "12.6", "12.5", "11.8")
                 foreach ($line in $rawOutput -split "`n") {
                     $line = $line.Trim()
@@ -1345,8 +1420,12 @@ $script:CudaToolkitReady = $true
 if ($HasROCm) {
     $rocmVerLabel = if ($script:ROCmVersionFull) { "ROCm $script:ROCmVersionFull" } elseif ($script:ROCmVersion) { "ROCm $script:ROCmVersion" } else { "ROCm (version unknown)" }
     step "rocm" $rocmVerLabel
+} elseif ($script:ROCmGfxArch) {
+    # GPU training/inference works via AMD's bundled-runtime ROCm PyTorch wheels;
+    # the HIP SDK is optional (only the system ROCm toolchain).
+    step "rocm" "GPU via bundled ROCm wheels ($script:ROCmGfxArch) -- HIP SDK optional" "Cyan"
 } elseif ($ROCmGpuLabel) {
-    step "rocm" "HIP SDK not found -- GPU-accelerated training unavailable" "Yellow"
+    step "rocm" "AMD GPU detected -- arch unknown; HIP SDK not found" "Yellow"
 }
 
 # ============================================
@@ -1997,6 +2076,21 @@ if ($env:SKIP_STUDIO_BASE -ne "1" -and $env:STUDIO_LOCAL_INSTALL -ne "1") {
     if ($InstalledVer -and $LatestVer -and ($InstalledVer -eq $LatestVer)) {
         step "python" "$_PkgName $InstalledVer is up to date"
         $SkipPythonDeps = $true
+        # ...but not if an AMD GPU is present and installed PyTorch is CPU-only
+        # (host predates ROCm-wheel support, or GPU added later): the fast "up to
+        # date" path would leave the user on CPU torch with Train/Export disabled.
+        # Force the dependency pass so the ROCm wheels get installed.
+        if ($script:ROCmGfxArch) {
+            $_torchIsCpu = $true
+            try {
+                & python -c "import torch, sys; sys.exit(0 if torch.cuda.is_available() else 1)" 2>$null
+                if ($LASTEXITCODE -eq 0) { $_torchIsCpu = $false }
+            } catch {}
+            if ($_torchIsCpu) {
+                substep "AMD GPU ($script:ROCmGfxArch) detected but installed PyTorch is CPU-only -- reinstalling ROCm PyTorch" "Cyan"
+                $SkipPythonDeps = $false
+            }
+        }
     } elseif ($InstalledVer -and $LatestVer) {
         substep "$_PkgName $InstalledVer -> $LatestVer available, updating..."
     } elseif (-not $LatestVer) {
@@ -2060,7 +2154,13 @@ if ($HasNvidiaSmi) {
 # Wheels bundle their own ROCm runtime; HIP SDK version is irrelevant.
 $ROCmGfxArch = $script:ROCmGfxArch
 $ROCmIndexUrl = $null
-if ($HasROCm -and $CuTag -eq "cpu") {
+# Install AMD ROCm PyTorch wheels when ROCm is confirmed OR a gfx arch is known
+# (name-inferred on Adrenalin-only hosts). The per-arch wheels bundle the runtime
+# (rocm-sdk-libraries-<gfx>), so torch.cuda.is_available() is True without a HIP
+# SDK -- which flips Studio out of chat-only (CHAT_ONLY) and enables Train/Export.
+# Gating on $HasROCm alone left Strix Halo / Radeon 8060S on CPU torch; a failed
+# ROCm install still falls back to CPU below, so this is safe.
+if (($HasROCm -or $ROCmGfxArch) -and $CuTag -eq "cpu") {
     $amdIndexBase = if ($env:UNSLOTH_ROCM_WINDOWS_MIRROR) { $env:UNSLOTH_ROCM_WINDOWS_MIRROR.TrimEnd('/') } else { "https://repo.amd.com/rocm/whl" }
     $archFamilyMap = @{
         "gfx1201" = "gfx120X-all"; "gfx1200" = "gfx120X-all"  # RDNA 4
@@ -2450,7 +2550,6 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
     substep "Skipping prebuilt install -- falling back to source build" "Yellow"
 } else {
     Write-Host ""
-    substep "installing prebuilt llama.cpp bundle (preferred path)..."
     if (Test-Path -LiteralPath $LlamaCppDir) {
         substep "Existing llama.cpp install detected -- validating staged prebuilt update before replacement"
         # If the existing install is the wrong kind (e.g. windows-cpu on a ROCm
@@ -2461,7 +2560,11 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
             try {
                 $existingMeta = Get-Content $existingMetaPath -Raw | ConvertFrom-Json
                 $existingKind = $existingMeta.install_kind
-                $expectedKind = if ($HasROCm) { "windows-hip" } elseif ($HasNvidiaSmi) { "windows-cuda" } else { "windows-cpu" }
+                # A name-inferred gfx arch (Adrenalin-only, no confirmed runtime)
+                # still wants the GPU (windows-hip) build -- the lemonade prebuilt
+                # bundles its own runtime. Treat a known arch as ROCm-capable here,
+                # mirroring the --rocm-gfx forward below.
+                $expectedKind = if ($HasROCm -or $script:ROCmGfxArch) { "windows-hip" } elseif ($HasNvidiaSmi) { "windows-cuda" } else { "windows-cpu" }
                 if ($existingKind -and $existingKind -ne $expectedKind) {
                     substep "Removing mismatched llama.cpp install (found '$existingKind', need '$expectedKind')..."
                     Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
@@ -2471,6 +2574,7 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
             }
         }
     }
+    substep "installing prebuilt llama.cpp bundle (preferred path)..."
     # why: install_llama_prebuilt.py uses os.replace(), which would displace
     # an unrelated $env:UNSLOTH_STUDIO_HOME\llama.cpp before the source-build
     # ownership check below ever runs.
@@ -2486,12 +2590,14 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
         )
         if ($HasROCm) {
             $prebuiltArgs += "--has-rocm"
-            # Forward the resolved gfx arch so the lemonade HIP prebuilt is picked
-            # even when the installer's own probe cannot report it (amd-smi-only
-            # hosts, name-inferred arch).
-            if ($script:ROCmGfxArch) {
-                $prebuiltArgs += @("--rocm-gfx", $script:ROCmGfxArch)
-            }
+        }
+        # Forward the resolved gfx arch so the lemonade HIP prebuilt is picked even
+        # when the installer's probe can't confirm the runtime (amd-smi-only /
+        # Adrenalin-only, name-inferred arch). --rocm-gfx is authoritative and
+        # implies ROCm in install_llama_prebuilt.py, so the GPU prebuilt is selected
+        # even with $HasROCm false. Gating on $HasROCm gave Strix Halo / 8060S CPU.
+        if ($script:ROCmGfxArch) {
+            $prebuiltArgs += @("--rocm-gfx", $script:ROCmGfxArch)
         }
         if ($env:UNSLOTH_LLAMA_RELEASE_TAG) {
             $prebuiltArgs += @("--published-release-tag", $env:UNSLOTH_LLAMA_RELEASE_TAG)
@@ -2586,7 +2692,7 @@ if ($NeedLlamaSourceBuild) {
         substep "installing OpenSSL dev (for HTTPS in llama-server)..."
         $HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
         if ($HasWinget) {
-            winget install -e --id ShiningLight.OpenSSL.Dev --accept-package-agreements --accept-source-agreements
+            winget install -e --id ShiningLight.OpenSSL.Dev --source winget --accept-package-agreements --accept-source-agreements
             # Re-check after install
             foreach ($root in $OpenSslRoots) {
                 if (Test-Path (Join-Path $root 'include\openssl\ssl.h')) {
@@ -2668,6 +2774,18 @@ if (-not $NeedLlamaSourceBuild) {
     Write-Host ""
     if ($HasNvidiaSmi) {
         substep "building llama.cpp with CUDA support..."
+    } elseif ($HasROCm -or $script:ROCmGfxArch) {
+        # AMD GPU present but in the CPU-only source-build fallback: a HIP source
+        # build needs the full HIP SDK + ROCm clang toolchain. AMD GPU acceleration
+        # comes from the lemonade prebuilt (bundles the runtime, no SDK) -- reaching
+        # here means it couldn't be installed. Warn loudly, don't ship a slow CPU build.
+        $_amdArch = if ($script:ROCmGfxArch) { $script:ROCmGfxArch } else { "ROCm" }
+        substep "[WARN] AMD GPU ($_amdArch) detected, but the GPU-accelerated lemonade" "Yellow"
+        substep "       llama.cpp prebuilt could not be installed -- falling back to a CPU build." "Yellow"
+        substep "       The prebuilt is the AMD GPU path (no HIP SDK required). To restore GPU" "Yellow"
+        substep "       acceleration: re-run the installer (check your network / proxy), or set" "Yellow"
+        substep "       UNSLOTH_LLAMA_RELEASE_TAG to a tag with a gfx prebuilt for your GPU." "Yellow"
+        substep "building llama.cpp (CPU-only fallback)..." "Yellow"
     } else {
         substep "building llama.cpp (CPU-only, no NVIDIA GPU detected)..."
     }
diff --git a/studio/setup.sh b/studio/setup.sh
index 15a20a572f..42e9f23626 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -773,6 +773,14 @@ fi
 fi
 
 # ── GPU detection summary (mirrors setup.ps1 step "gpu" block) ──
+# WSL2 ROCDXG: the system rocminfo enumerates the GPU over /dev/dxg only when
+# HSA_ENABLE_DXG_DETECTION=1 (a no-op on bare metal), and /opt/rocm/bin can be
+# off PATH outside login shells (the profile.d drop-in). Seed both before the
+# probes or a ROCDXG WSL host is misdetected as CPU-only.
+export HSA_ENABLE_DXG_DETECTION="${HSA_ENABLE_DXG_DETECTION:-1}"
+if ! command -v rocminfo >/dev/null 2>&1 && [ -x /opt/rocm/bin/rocminfo ]; then
+    PATH="$PATH:/opt/rocm/bin"
+fi
 _setup_amd_detected=false
 _setup_gfx_all=""
 _setup_mkt=""
@@ -810,14 +818,20 @@ elif [ "$_setup_amd_detected" = true ]; then
         substep "gfx arch from UNSLOTH_ROCM_GFX_ARCH env override: $_setup_gfx"
     # Name-based arch inference when tools don't report gfx (mirrors setup.ps1 nameArchTable)
     elif [ -z "$_setup_gfx" ] && [ -n "$_setup_mkt" ]; then
+        # Kept in sync with the table in install.sh (and the PS nameArchTable).
+        # gfx1102 matched BEFORE gfx1100 so the spaceless "RX 7700S" lands on
+        # gfx1102 (bash case has no negative lookahead like the PS tables).
         case "$_setup_mkt" in
-            *"9070 XT"*|*9080*)                                                 _setup_gfx="gfx1201" ;;  # RDNA 4
-            *9070*|*9060*)                                                      _setup_gfx="gfx1200" ;;  # RDNA 4
-            *"8060S"*|*"890M"*|*"Strix Halo"*|*"HX 37"*|*"HX 38"*|*"AI 9 HX"*)  _setup_gfx="gfx1151" ;;  # RDNA 3.5 iGPU
-            *"880M"*|*"Strix Point"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*)       _setup_gfx="gfx1150" ;;  # RDNA 3.5 iGPU
-            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*)                                _setup_gfx="gfx1100" ;;  # RDNA 3 desktop
-            *"RX 7600"*)                                                        _setup_gfx="gfx1102" ;;  # RDNA 3
-            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*)                             _setup_gfx="gfx1103" ;;  # RDNA 3 iGPU
+            *"9070 XT"*|*9080*)                                                                            _setup_gfx="gfx1201" ;;  # RDNA 4
+            *9070*|*9060*)                                                                                 _setup_gfx="gfx1200" ;;  # RDNA 4
+            *"8060S"*|*"8050S"*|*"8040S"*|*"Strix Halo"*|*"Ryzen AI Max"*|*"AI Max"*) _setup_gfx="gfx1151" ;;  # RDNA 3.5 (Strix Halo: Radeon 8060S/8050S/8040S iGPU, Ryzen AI Max+)
+            *"890M"*|*"880M"*|*"860M"*|*"840M"*|*"Strix Point"*|*"Krackan"*|*"HX 37"*|*"AI 9 HX"*|*"AI 9 36"*|*"AI 7 35"*|*"AI 5 34"*|*"AI 7 PRO 35"*|*"AI 5 33"*) _setup_gfx="gfx1150" ;;  # RDNA 3.5 (Strix/Krackan Point: Radeon 890M/880M iGPU, Ryzen AI 9 HX 370/375)
+            *"RX 7600"*|*"RX 7700S"*|*"RX 7650"*|*"PRO W7600"*|*"PRO W7500"*|*"PRO V710"*)                  _setup_gfx="gfx1102" ;;  # RDNA 3 (Navi 33)
+            *"RX 7900"*|*"RX 7800"*|*"RX 7700"*|*"PRO W7900"*|*"PRO W7800"*|*"PRO W7700"*)                  _setup_gfx="gfx1100" ;;  # RDNA 3 desktop / workstation (Navi 31)
+            *"780M"*|*"760M"*|*"740M"*|*"Phoenix"*|*"Hawk Point"*|*"Z1 Extreme"*|*"Z2 Extreme"*)            _setup_gfx="gfx1103" ;;  # RDNA 3 iGPU (Phoenix / Hawk Point)
+            *"RX 6900"*|*"RX 6800"*|*"RX 6750"*|*"RX 6700"*|*"PRO W6800"*|*"PRO W6900"*)                    _setup_gfx="gfx1030" ;;  # RDNA 2 (Navi 21)
+            *"RX 6650"*|*"RX 6600"*|*"PRO W6600"*|*"PRO W6650"*)                                            _setup_gfx="gfx1032" ;;  # RDNA 2 (Navi 23)
+            *"RX 6500"*|*"RX 6400"*|*"RX 6300"*|*"PRO W6400"*|*"PRO W6500"*)                                _setup_gfx="gfx1034" ;;  # RDNA 2 (Navi 24)
         esac
         if [ -n "$_setup_gfx" ]; then
             substep "gfx arch inferred from GPU name: $_setup_gfx"
diff --git a/tests/studio/install/test_pr5940_followups.py b/tests/studio/install/test_pr5940_followups.py
new file mode 100644
index 0000000000..583532eb74
--- /dev/null
+++ b/tests/studio/install/test_pr5940_followups.py
@@ -0,0 +1,334 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Tests for the AMD-Windows installer follow-ups (PR #5940):
+
+  * the huggingface_hub validation-model fetch + its urllib fallback,
+  * run_capture's Windows-only amd-smi __COMPAT_LAYER=RunAsInvoker injection,
+  * parity of the name->arch table between install.ps1 and setup.ps1.
+
+Mock-only; no AMD hardware or network required.
+"""
+
+import importlib.util
+import re
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+
+# install_llama_prebuilt.py is self-contained (stdlib + optional filelock), so it
+# loads without the studio backend on sys.path.
+_PREBUILT_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+_SPEC = importlib.util.spec_from_file_location(
+    "studio_install_llama_prebuilt_pr5940", _PREBUILT_PATH
+)
+assert _SPEC is not None and _SPEC.loader is not None
+prebuilt = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = prebuilt
+_SPEC.loader.exec_module(prebuilt)
+
+_INSTALL_PS1 = PACKAGE_ROOT / "install.ps1"
+_SETUP_PS1 = PACKAGE_ROOT / "studio" / "setup.ps1"
+_INSTALL_SH = PACKAGE_ROOT / "install.sh"
+
+
+# ── _hf_resolve_url_parts ────────────────────────────────────────────────────
+
+
+def test_hf_resolve_url_parts_valid():
+    assert prebuilt._hf_resolve_url_parts(
+        "https://huggingface.co/ggml-org/models/resolve/main/tinyllamas/stories260K.gguf"
+    ) == ("ggml-org/models", "main", "tinyllamas/stories260K.gguf")
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://github.com/owner/repo/releases/download/x.gguf",  # not huggingface
+        "https://huggingface.co/owner/repo",  # no /resolve/<rev>/
+        "https://huggingface.co/owner/repo/blob/main/x.gguf",  # /blob/ not /resolve/
+        "not even a url",
+    ],
+)
+def test_hf_resolve_url_parts_non_hf_returns_none(url):
+    assert prebuilt._hf_resolve_url_parts(url) is None
+
+
+# ── _fetch_validation_model_bytes ────────────────────────────────────────────
+
+
+def test_fetch_validation_model_prefers_huggingface_hub(tmp_path):
+    model = tmp_path / "stories260K.gguf"
+    model.write_bytes(b"GGUF-via-hf")
+    fake_hf = MagicMock(return_value = str(model))
+    with (
+        patch.object(prebuilt, "validated_validation_model_bytes", side_effect = lambda b: b),
+        patch.dict(sys.modules, {"huggingface_hub": MagicMock(hf_hub_download = fake_hf)}),
+    ):
+        assert prebuilt._fetch_validation_model_bytes() == b"GGUF-via-hf"
+    assert fake_hf.called  # hf path was taken, urllib not needed
+
+
+def test_fetch_validation_model_falls_back_to_urllib_on_hf_failure():
+    fake_hf = MagicMock(side_effect = RuntimeError("hf unreachable"))
+    with (
+        patch.object(prebuilt, "validated_validation_model_bytes", side_effect = lambda b: b),
+        patch.dict(sys.modules, {"huggingface_hub": MagicMock(hf_hub_download = fake_hf)}),
+        patch.object(prebuilt, "download_bytes", return_value = b"GGUF-via-urllib") as dl,
+    ):
+        assert prebuilt._fetch_validation_model_bytes() == b"GGUF-via-urllib"
+    assert dl.called  # fell back to the direct URL download
+
+
+# ── run_capture amd-smi RunAsInvoker injection ───────────────────────────────
+
+
+def _capture_env(command, system):
+    captured = {"env": "sentinel"}
+
+    def fake_run(cmd, **kwargs):
+        captured["env"] = kwargs.get("env")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+
+    with (
+        patch.object(prebuilt.subprocess, "run", side_effect = fake_run),
+        patch.object(prebuilt.platform, "system", return_value = system),
+    ):
+        prebuilt.run_capture(command)
+    return captured["env"]
+
+
+def test_run_capture_injects_runasinvoker_for_amd_smi_on_windows():
+    env = _capture_env(["amd-smi", "list"], "Windows")
+    assert env is not None and env.get("__COMPAT_LAYER") == "RunAsInvoker"
+
+
+def test_run_capture_injects_for_full_path_amd_smi_exe_on_windows():
+    env = _capture_env(["amd-smi.exe", "version"], "Windows")
+    assert env is not None and env.get("__COMPAT_LAYER") == "RunAsInvoker"
+
+
+def test_run_capture_no_injection_for_non_amd_smi_on_windows():
+    assert _capture_env(["rocminfo"], "Windows") is None
+
+
+def test_run_capture_no_injection_on_linux():
+    # amd-smi does not auto-elevate on Linux, so no env override is applied.
+    assert _capture_env(["amd-smi", "list"], "Linux") is None
+
+
+# ── name->arch table parity (install.ps1 vs setup.ps1) ───────────────────────
+
+
+def _ps_name_arch_rows(text):
+    return re.findall(r'@\{\s*P\s*=\s*"([^"]*)"\s*;\s*A\s*=\s*"(gfx[0-9a-z]+)"', text)
+
+
+def test_ps_name_arch_tables_in_sync():
+    t1 = _ps_name_arch_rows(_INSTALL_PS1.read_text(encoding = "utf-8"))
+    t2 = _ps_name_arch_rows(_SETUP_PS1.read_text(encoding = "utf-8"))
+    assert t1, "no nameArchTable found in install.ps1"
+    assert t1 == t2, f"name->arch tables drifted:\ninstall.ps1={t1}\nsetup.ps1={t2}"
+
+
+def test_rx_7700s_resolves_to_gfx1102_not_gfx1100():
+    rows = _ps_name_arch_rows(_INSTALL_PS1.read_text(encoding = "utf-8"))
+    name = "AMD Radeon RX 7700S"
+    matched = next((arch for pattern, arch in rows if re.search(pattern, name)), None)
+    assert matched == "gfx1102", f"RX 7700S matched {matched!r}, expected gfx1102"
+
+
+def test_radeon_8060s_resolves_to_gfx1151():
+    rows = _ps_name_arch_rows(_INSTALL_PS1.read_text(encoding = "utf-8"))
+    name = "AMD Radeon(TM) 8060S Graphics"
+    matched = next((arch for pattern, arch in rows if re.search(pattern, name)), None)
+    assert matched == "gfx1151"
+
+
+def _sh_name_arch_rows(text, var = "_gpu_disp_gfx"):
+    """Parse a bash `case "$..._mkt" in ... ) <var>="gfxNNNN"` name->arch
+    table into [(substr_tokens, arch), ...] preserving order."""
+    rows = []
+    for line in text.splitlines():
+        m = re.search(var + r'="(gfx[0-9a-z]+)"', line)
+        if not m or '*"' not in line:
+            continue
+        tokens = re.findall(r'\*"([^"]+)"\*', line)
+        if tokens:
+            rows.append((tokens, m.group(1)))
+    return rows
+
+
+def _sh_resolve(rows, name):
+    for tokens, arch in rows:
+        if any(tok in name for tok in tokens):  # bash *"X"* == substring
+            return arch
+    return None
+
+
+def test_install_sh_name_arch_agrees_with_ps_for_strix_and_non_amd():
+    """The bash install.sh name->arch table must agree with the PowerShell
+    source-of-truth for the Strix Halo (gfx1151) vs Strix Point (gfx1150)
+    split, and must never misclassify NVIDIA/Intel as an AMD gfx."""
+    sh_rows = _sh_name_arch_rows(_INSTALL_SH.read_text(encoding = "utf-8"))
+    ps_rows = _ps_name_arch_rows(_INSTALL_PS1.read_text(encoding = "utf-8"))
+    assert sh_rows, "no name->arch case table found in install.sh"
+    cases = {
+        "AMD Radeon(TM) 8060S Graphics": "gfx1151",  # Strix Halo
+        "AMD Ryzen AI Max+ PRO 395 w/ Radeon 8060S": "gfx1151",
+        "AMD Radeon 890M Graphics": "gfx1150",  # Strix Point (NOT gfx1151)
+        "AMD Ryzen AI 9 HX 370 w/ Radeon 890M": "gfx1150",
+        "AMD Radeon RX 7700S": "gfx1102",
+        "NVIDIA GeForce RTX 4090": None,
+        "Intel(R) Arc A770 Graphics": None,
+    }
+    for name, expect in cases.items():
+        sh = _sh_resolve(sh_rows, name)
+        assert sh == expect, f"install.sh: {name!r} -> {sh!r}, expected {expect!r}"
+        if expect is not None:  # cross-check bash agrees with the PowerShell table
+            ps = next((a for p, a in ps_rows if re.search(p, name)), None)
+            assert sh == ps, f"install.sh/install.ps1 drift for {name!r}: {sh!r} vs {ps!r}"
+
+
+def test_setup_sh_name_arch_table_in_sync_with_install_sh():
+    """studio/setup.sh keeps its own copy of the bash name->arch table (over
+    `_setup_gfx`); it must stay row-for-row identical to install.sh's, both in
+    tokens and in match order (order carries the RX 7700S -> gfx1102 rule)."""
+    install_rows = _sh_name_arch_rows(_INSTALL_SH.read_text(encoding = "utf-8"))
+    setup_rows = _sh_name_arch_rows(
+        (PACKAGE_ROOT / "studio" / "setup.sh").read_text(encoding = "utf-8"),
+        var = "_setup_gfx",
+    )
+    assert setup_rows, "no name->arch case table found in studio/setup.sh"
+    assert install_rows == setup_rows, (
+        "bash name->arch tables drifted:\n"
+        f"install.sh={install_rows}\nstudio/setup.sh={setup_rows}"
+    )
+    # The historical drift this guards against: Strix Point SKUs must be
+    # gfx1150, and the spaceless RX 7700S must match gfx1102 before gfx1100.
+    for name, expect in {
+        "AMD Radeon 890M Graphics": "gfx1150",
+        "AMD Ryzen AI 9 HX 370 w/ Radeon 890M": "gfx1150",
+        "AMD Radeon(TM) 8060S Graphics": "gfx1151",
+        "AMD Radeon RX 7700S": "gfx1102",
+    }.items():
+        got = _sh_resolve(setup_rows, name)
+        assert got == expect, f"setup.sh: {name!r} -> {got!r}, expected {expect!r}"
+
+
+# ── amd-smi gating (DiskPart UAC-prompt avoidance) ───────────────────────────
+# On Windows w/o a HIP SDK, amd-smi elevates and pops a UAC/DiskPart prompt
+# RunAsInvoker can't suppress, so _amd_smi_allowed() skips it by default;
+# HIP-SDK hosts and an explicit opt-in keep it.
+
+
+def _amd_smi_allowed_under(system, hipinfo_present, env):
+    which = (
+        (lambda name: r"C:\hip\bin\hipinfo.exe" if name == "hipinfo" else None)
+        if hipinfo_present
+        else (lambda name: None)
+    )
+    with (
+        patch.object(prebuilt.platform, "system", return_value = system),
+        patch.object(prebuilt.shutil, "which", side_effect = which),
+        patch.dict(prebuilt.os.environ, env, clear = True),
+    ):
+        return prebuilt._amd_smi_allowed()
+
+
+def test_amd_smi_allowed_on_linux_regardless():
+    # Linux amd-smi does not elevate -> always allowed (no regression on Linux).
+    assert _amd_smi_allowed_under("Linux", hipinfo_present = False, env = {}) is True
+
+
+def test_amd_smi_skipped_on_windows_without_hip_sdk():
+    # The DiskPart fix: no HIP SDK + no opt-in -> do not spawn amd-smi.
+    assert _amd_smi_allowed_under("Windows", hipinfo_present = False, env = {}) is False
+
+
+def test_amd_smi_allowed_on_windows_with_hip_sdk():
+    # hipinfo present => amd-smi runs un-elevated, so it is allowed (no regression
+    # for HIP-SDK Windows users, who never saw the prompt).
+    assert _amd_smi_allowed_under("Windows", hipinfo_present = True, env = {}) is True
+
+
+def test_amd_smi_opt_in_forces_on_windows_no_sdk():
+    assert (
+        _amd_smi_allowed_under(
+            "Windows", hipinfo_present = False, env = {"UNSLOTH_ENABLE_AMD_SMI": "1"}
+        )
+        is True
+    )
+
+
+def test_amd_smi_opt_out_overrides_hip_sdk():
+    assert (
+        _amd_smi_allowed_under("Windows", hipinfo_present = True, env = {"UNSLOTH_ENABLE_AMD_SMI": "0"})
+        is False
+    )
+
+
+def test_ps_installers_gate_amd_smi_on_windows():
+    # Both PowerShell installers must gate amd-smi behind HIP-SDK presence + the
+    # UNSLOTH_ENABLE_AMD_SMI opt-in, mirroring _amd_smi_allowed().
+    for ps in (_INSTALL_PS1, _SETUP_PS1):
+        text = ps.read_text(encoding = "utf-8")
+        assert "UNSLOTH_ENABLE_AMD_SMI" in text, f"{ps.name} missing amd-smi opt-in gate"
+        assert "amdSmiAllowed" in text, f"{ps.name} missing amd-smi gate variable"
+
+
+def test_install_python_stack_gates_every_amd_smi_spawn():
+    # Regression for the DiskPart UAC prompt: every function that both names the
+    # `amd-smi` command AND spawns a subprocess must gate it behind
+    # _amd_smi_allowed(). The "ROCm torch missing" probe once spawned `amd-smi
+    # list` ungated on Adrenalin-only hosts; not-spawning is the only fix.
+    import ast
+
+    src = (PACKAGE_ROOT / "studio" / "install_python_stack.py").read_text(encoding = "utf-8")
+    tree = ast.parse(src)
+
+    def _names_amd_smi_command(node):
+        # Exact "amd-smi"/"amd-smi.exe" constant, not a substring in a log message.
+        return any(
+            isinstance(n, ast.Constant)
+            and isinstance(n.value, str)
+            and n.value.lower() in ("amd-smi", "amd-smi.exe")
+            for n in ast.walk(node)
+        )
+
+    def _spawns_subprocess(node):
+        for n in ast.walk(node):
+            if (
+                isinstance(n, ast.Call)
+                and isinstance(n.func, ast.Attribute)
+                and isinstance(n.func.value, ast.Name)
+                and n.func.value.id == "subprocess"
+            ):
+                return True
+        return False
+
+    def _references_gate(node):
+        return any(isinstance(n, ast.Name) and n.id == "_amd_smi_allowed" for n in ast.walk(node))
+
+    offenders = [
+        node.name
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and _names_amd_smi_command(node)
+        and _spawns_subprocess(node)
+        and not _references_gate(node)
+    ]
+    assert not offenders, (
+        "install_python_stack.py spawns amd-smi without an _amd_smi_allowed() "
+        f"gate in: {offenders} -- this pops the Windows UAC/DiskPart prompt on "
+        "Adrenalin-only (no HIP SDK) hosts."
+    )
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index e0309dbd35..c761cd090f 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -550,9 +550,13 @@ class TestEnsureRocmTorch:
     @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = False)
     def test_no_rocm_skips(self, mock_nvidia, mock_pip):
         """No ROCm toolchain should skip entirely."""
-        with patch("os.path.isdir", return_value = False):
-            with patch("shutil.which", return_value = None):
-                _ensure_rocm_torch()
+        # _detect_windows_gfx_arch pinned to None: on a real AMD test host its
+        # WMI name fallback would otherwise answer and defeat the "no ROCm
+        # anywhere" premise of this test.
+        with patch.object(stack_mod, "_detect_windows_gfx_arch", return_value = None):
+            with patch("os.path.isdir", return_value = False):
+                with patch("shutil.which", return_value = None):
+                    _ensure_rocm_torch()
         mock_pip.assert_not_called()
 
     @patch.object(stack_mod, "pip_install")
@@ -692,8 +696,12 @@ class TestEnsureRocmTorch:
     @patch.object(stack_mod, "_has_rocm_gpu", return_value = False)
     def test_no_gpu_with_rocm_tools_skips(self, mock_gpu, mock_nvidia, mock_pip):
         """ROCm tools present but no actual AMD GPU should skip entirely."""
-        with patch("os.path.isdir", return_value = True):
-            _ensure_rocm_torch()
+        # Pin the Windows arch probe to None: on a real AMD test host the WMI
+        # name fallback would otherwise answer and defeat the "no actual GPU"
+        # premise (the Linux path under test uses _has_rocm_gpu, mocked False).
+        with patch.object(stack_mod, "_detect_windows_gfx_arch", return_value = None):
+            with patch("os.path.isdir", return_value = True):
+                _ensure_rocm_torch()
         mock_pip.assert_not_called()
 
 
@@ -862,7 +870,14 @@ class TestInstallShStructure:
     """Verify install.sh structural properties without running it."""
 
     def test_no_here_strings(self):
-        """install.sh must not use <<< (not POSIX)."""
+        """install.sh must not use the bash-only `<<<` here-string operator.
+
+        `<<<` inside a quoted literal (e.g. a marker in a printf) is just data,
+        not a here-string, so strip quoted spans first: this still catches a
+        real `cmd <<< word` (outside quotes) without false-positiving on data.
+        """
+        import re
+
         sh_path = PACKAGE_ROOT / "install.sh"
         source = sh_path.read_text(encoding = "utf-8")
         # <<< is bash-only; breaks dash
@@ -870,7 +885,11 @@ class TestInstallShStructure:
             stripped = line.lstrip()
             if stripped.startswith("#"):
                 continue
-            assert "<<<" not in line, f"install.sh:{i} uses non-POSIX <<< here-string"
+            # Remove quoted string literals so `<<<` inside them is ignored;
+            # a genuine here-string operator lives outside any quotes.
+            unquoted = re.sub(r"'[^']*'", "", line)
+            unquoted = re.sub(r'"[^"]*"', "", unquoted)
+            assert "<<<" not in unquoted, f"install.sh:{i} uses non-POSIX <<< here-string"
 
     def test_rocm_detection_present(self):
         """install.sh should have ROCm detection in get_torch_index_url."""
@@ -1202,6 +1221,10 @@ class TestAmdGpuMonitoring:
         ):
             monkeypatch.delenv(var, raising = False)
 
+        # amd-smi is gated off on Windows w/o a HIP SDK; this test mocks it as
+        # available, so opt in so the gate allows it on every platform.
+        monkeypatch.setenv("UNSLOTH_ENABLE_AMD_SMI", "1")
+
         mock_json = json.dumps(
             [
                 {
@@ -1216,8 +1239,12 @@ class TestAmdGpuMonitoring:
         mock_result.returncode = 0
         mock_result.stdout = mock_json
 
-        with patch.object(subprocess, "run", return_value = mock_result):
-            result = amd_mod.get_primary_gpu_utilization()
+        # The premise is "amd-smi exists and answers": the absence guard
+        # which()-checks before spawning, so hosts without a real amd-smi
+        # (Linux CI, driver-only Windows) need which mocked too.
+        with patch.object(amd_mod.shutil, "which", return_value = "/usr/bin/amd-smi"):
+            with patch.object(subprocess, "run", return_value = mock_result):
+                result = amd_mod.get_primary_gpu_utilization()
         assert result["available"] is True
         assert result["gpu_utilization_pct"] == 50.0
         assert result["temperature_c"] == 65.0
@@ -1238,7 +1265,12 @@ class TestAmdGpuMonitoring:
         except Exception:
             pytest.skip("Could not load amd module")
 
-        with patch.object(subprocess, "run", side_effect = OSError("amd-smi not found")):
+        # Opt in so the call reaches subprocess.run (gated off on Windows w/o a
+        # HIP SDK); testing the OSError handling here.
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ENABLE_AMD_SMI": "1"}),
+            patch.object(subprocess, "run", side_effect = OSError("amd-smi not found")),
+        ):
             result = amd_mod.get_primary_gpu_utilization()
         assert result["available"] is False
 
@@ -1258,10 +1290,15 @@ class TestAmdGpuMonitoring:
         except Exception:
             pytest.skip("Could not load amd module")
 
-        with patch.object(
-            subprocess,
-            "run",
-            side_effect = subprocess.TimeoutExpired("amd-smi", 5),
+        # Opt in so the call reaches subprocess.run (gated off on Windows w/o a
+        # HIP SDK); testing the timeout handling here.
+        with (
+            patch.dict(os.environ, {"UNSLOTH_ENABLE_AMD_SMI": "1"}),
+            patch.object(
+                subprocess,
+                "run",
+                side_effect = subprocess.TimeoutExpired("amd-smi", 5),
+            ),
         ):
             result = amd_mod.get_primary_gpu_utilization()
         assert result["available"] is False
@@ -1508,8 +1545,13 @@ class TestDetectWindowsGfxArch:
     """Verify hipinfo parsing for GPU arch detection on Windows."""
 
     def test_returns_none_when_hipinfo_not_on_path(self):
+        # Also neutralise the venv-hipInfo and WMI-name fallbacks: this test
+        # pins "no probe source available -> None", and the suite may run on a
+        # real AMD host where WMI would legitimately answer.
         with patch("shutil.which", return_value = None):
-            result = stack_mod._detect_windows_gfx_arch()
+            with patch("os.path.isfile", return_value = False):
+                with patch("subprocess.run", side_effect = FileNotFoundError):
+                    result = stack_mod._detect_windows_gfx_arch()
         assert result is None
 
     def test_parses_gcnarchname_from_hipinfo_output(self):
@@ -1531,11 +1573,21 @@ class TestDetectWindowsGfxArch:
         assert result is None
 
     def test_returns_none_when_no_gcnarchname_in_output(self):
+        # hipinfo answers but without a gcnArchName line. Route only the
+        # hipinfo/amd-smi probes to the mock; the WMI fallback must get
+        # nothing (FileNotFoundError) -- otherwise the mocked device name
+        # would legitimately resolve via the name table.
         mock_result = MagicMock()
         mock_result.returncode = 0
-        mock_result.stdout = b"deviceName : Radeon RX 9060 XT\n"
+        mock_result.stdout = b"deviceName : SomeUnknownDevice\n"
+
+        def _run(cmd, **kwargs):
+            if cmd and "powershell" in str(cmd[0]).lower():
+                raise FileNotFoundError(cmd[0])
+            return mock_result
+
         with patch("shutil.which", return_value = "/usr/bin/hipinfo"):
-            with patch("subprocess.run", return_value = mock_result):
+            with patch("subprocess.run", side_effect = _run):
                 result = stack_mod._detect_windows_gfx_arch()
         assert result is None
 
@@ -1558,6 +1610,99 @@ class TestDetectWindowsGfxArch:
         assert result == "gfx1201"
 
 
+# TEST: install_python_stack.py -- GPU-name / WMI fallback (no amd-smi, no hipinfo)
+
+
+class TestGfxArchNameFallback:
+    """amd-smi does not exist on Windows (neither Adrenalin consistently nor
+    the HIP SDK ship a CLI) and driver-only hosts lack hipinfo too. The
+    detection chain must still resolve the arch from the GPU marketing name
+    (WMI), mirroring setup.ps1's $nameArchTable."""
+
+    @pytest.mark.parametrize(
+        "name, expected",
+        [
+            ("AMD Radeon(TM) 8060S Graphics", "gfx1151"),
+            ("AMD Ryzen AI MAX+ 395 w/ Radeon 8060S", "gfx1151"),
+            ("AMD Radeon(TM) 890M", "gfx1150"),
+            ("AMD Ryzen AI 9 HX 370 w/ Radeon 890M", "gfx1150"),
+            ("AMD Radeon RX 9070 XT", "gfx1201"),
+            ("AMD Radeon RX 9070", "gfx1200"),
+            ("AMD Radeon RX 7700S", "gfx1102"),  # (?!S) lookahead must not hit gfx1100
+            ("AMD Radeon RX 7700 XT", "gfx1100"),
+            ("AMD Radeon(TM) 780M", "gfx1103"),
+            ("NVIDIA GeForce RTX 4090", None),
+            ("Microsoft Basic Display Adapter", None),
+            ("", None),
+        ],
+    )
+    def test_name_to_arch_mapping(self, name, expected):
+        assert stack_mod._gfx_arch_from_gpu_name(name) == expected
+
+    def test_wmi_fallback_resolves_arch_without_any_tools(self):
+        """hipinfo absent everywhere + amd-smi absent -> WMI name fallback."""
+        ps_result = MagicMock()
+        ps_result.returncode = 0
+        ps_result.stdout = b"AMD Radeon(TM) 8060S Graphics\r\nMicrosoft Basic Display Adapter\r\n"
+
+        def _run(cmd, **kwargs):
+            if cmd and "powershell.exe" in str(cmd[0]).lower():
+                return ps_result
+            raise FileNotFoundError(cmd[0])
+
+        with patch.dict(os.environ, {}, clear = False):
+            for _v in (
+                "HIP_PATH",
+                "ROCM_PATH",
+                "UNSLOTH_ROCM_GFX_ARCH",
+                "UNSLOTH_ENABLE_AMD_SMI",
+            ):
+                os.environ.pop(_v, None)
+            with patch("shutil.which", return_value = None):
+                with patch("os.path.isfile", return_value = False):
+                    with patch("subprocess.run", side_effect = _run):
+                        result = stack_mod._detect_windows_gfx_arch()
+        assert result == "gfx1151"
+
+    def test_wmi_fallback_returns_none_for_non_amd_hosts(self):
+        ps_result = MagicMock()
+        ps_result.returncode = 0
+        ps_result.stdout = b"NVIDIA GeForce RTX 4090\r\n"
+
+        def _run(cmd, **kwargs):
+            if cmd and "powershell.exe" in str(cmd[0]).lower():
+                return ps_result
+            raise FileNotFoundError(cmd[0])
+
+        with patch.dict(os.environ, {}, clear = False):
+            for _v in ("HIP_PATH", "ROCM_PATH", "UNSLOTH_ROCM_GFX_ARCH"):
+                os.environ.pop(_v, None)
+            with patch("shutil.which", return_value = None):
+                with patch("os.path.isfile", return_value = False):
+                    with patch("subprocess.run", side_effect = _run):
+                        result = stack_mod._detect_windows_gfx_arch()
+        assert result is None
+
+    def test_stack_probes_venv_hipinfo(self):
+        """The venv Scripts dir hipInfo.exe (shipped by AMD torch wheels) must
+        be a probe candidate so `studio update` works on driver-only hosts."""
+        source = _STACK_PATH.read_text(encoding = "utf-8")
+        assert 'os.path.join(os.path.dirname(sys.executable), "hipInfo.exe")' in source
+
+    def test_prebuilt_resolve_exe_probes_venv_dir(self):
+        """install_llama_prebuilt's _resolve_exe must include the venv Scripts
+        candidate for the same driver-only standalone-rerun scenario."""
+        source = _PREBUILT_PATH.read_text(encoding = "utf-8")
+        assert "_venv_candidate" in source
+
+    def test_runtime_monitor_guards_amd_smi_absence(self):
+        """amd.py must which()-check amd-smi before spawning so absence
+        disables the poller in one step (no FileNotFoundError strikes)."""
+        amd_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "amd.py"
+        source = amd_path.read_text(encoding = "utf-8")
+        assert 'shutil.which("amd-smi") is None' in source
+
+
 # TEST: install_python_stack.py -- _install_bnb_windows_rocm
 
 
@@ -2350,6 +2495,38 @@ class TestServerStartupRocmFixes:
         source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
         assert '"BNB_ROCM_VERSION" not in os.environ' in source
 
+    # ── hipInfo.exe PATH prepend (bitsandbytes arch-probe fix) ────────────────
+    # bitsandbytes' get_rocm_gpu_arch() runs `hipinfo.exe` via subprocess PATH
+    # at import time. The AMD torch wheel ships hipInfo.exe in the venv
+    # Scripts dir, which is on PATH only for activated venvs -- Studio and the
+    # installer launch python directly, so without the prepend every bnb
+    # import logs "Could not detect ROCm GPU architecture: [WinError 2]".
+
+    def test_main_py_prepends_hipinfo_dir_to_path(self):
+        """main.py must make hipInfo.exe resolvable before bnb imports."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert "hipInfo.exe" in source
+        # The prepend must come before the BNB_ROCM_VERSION block (both run
+        # pre-import; order documents that bnb sees the fixed PATH).
+        assert source.find("hipInfo.exe") < source.find("BNB_ROCM_VERSION")
+
+    def test_main_py_hipinfo_prepend_gated_on_file_presence(self):
+        """Only AMD ROCm wheels ship hipInfo.exe; NVIDIA/CPU hosts must be
+        untouched, so the prepend must check the file exists first."""
+        source = _MAIN_PY_PATH.read_text(encoding = "utf-8")
+        assert 'os.path.isfile(os.path.join(_scripts_dir, "hipInfo.exe"))' in source
+
+    def test_worker_py_prepends_hipinfo_dir_to_path(self):
+        """worker.py must mirror the prepend for standalone-spawned workers."""
+        source = _WORKER_PATH.read_text(encoding = "utf-8")
+        assert "hipInfo.exe" in source
+
+    def test_install_stack_prepends_hipinfo_dir_to_path(self):
+        """install_python_stack.py must prepend so the installer's child
+        import checks inherit a PATH where bnb's probe succeeds."""
+        source = _STACK_PATH.read_text(encoding = "utf-8")
+        assert "hipInfo.exe" in source
+
     # ── torch._C._distributed_c10d stubs in hardware.py ──────────────────────
 
     def test_hardware_py_injects_distributed_c10d_stub(self):
diff --git a/tests/studio/test_cli_studio_stop_windows.py b/tests/studio/test_cli_studio_stop_windows.py
new file mode 100644
index 0000000000..7ba3d12214
--- /dev/null
+++ b/tests/studio/test_cli_studio_stop_windows.py
@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Regression tests for `unsloth studio stop` on Windows (PR #5940).
+
+`stop` once used the POSIX `os.kill(pid, 0)` probe, which raises OSError
+(WinError 87) for every pid on Windows -- crashing before reaching taskkill.
+The fix adds a cross-platform `_pid_alive(pid)` (tasklist on Windows, signal-0
+elsewhere).
+
+AST + mock-only; no real process management, no Studio deps imported.
+"""
+
+import ast
+import os
+import subprocess
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+_STUDIO_CMD_PY = Path(__file__).resolve().parents[2] / "unsloth_cli" / "commands" / "studio.py"
+_SOURCE = _STUDIO_CMD_PY.read_text(encoding = "utf-8")
+
+
+def _func_source(name: str) -> str:
+    """Return the source of a top-level function `name` in studio.py."""
+    tree = ast.parse(_SOURCE)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == name:
+            return ast.get_source_segment(_SOURCE, node)
+    raise AssertionError(f"function {name!r} not found in studio.py")
+
+
+def _load_pid_alive(platform: str, fake_run = None):
+    """Exec just `_pid_alive` with injectable sys/subprocess, so we can drive
+    the win32 branch on any host without importing the full unsloth_cli."""
+    src = _func_source("_pid_alive")
+    fake_sys = types.SimpleNamespace(platform = platform)
+    fake_sub = types.SimpleNamespace(run = fake_run) if fake_run is not None else subprocess
+    ns = {"os": os, "sys": fake_sys, "subprocess": fake_sub}
+    exec(src, ns)
+    return ns["_pid_alive"]
+
+
+# ── AST: stop() must not use the broken bare liveness probe ──────────────────
+
+
+def test_stop_does_not_use_bare_oskill_liveness_probe():
+    """stop() must not call os.kill(pid, 0) -- it crashes on Windows."""
+    stop_src = _func_source("stop")
+    tree = ast.parse(stop_src)
+    for call in ast.walk(tree):
+        if not isinstance(call, ast.Call):
+            continue
+        f = call.func
+        is_os_kill = (
+            isinstance(f, ast.Attribute)
+            and f.attr == "kill"
+            and isinstance(f.value, ast.Name)
+            and f.value.id == "os"
+        )
+        if is_os_kill and len(call.args) == 2:
+            sig = call.args[1]
+            if isinstance(sig, ast.Constant) and sig.value == 0:
+                raise AssertionError(
+                    "stop() still uses os.kill(pid, 0); it raises WinError 87 on "
+                    "Windows. Use the cross-platform _pid_alive() helper instead."
+                )
+
+
+def test_pid_alive_helper_is_defined_and_used_by_stop():
+    assert "def _pid_alive(" in _SOURCE, "_pid_alive helper missing"
+    assert "_pid_alive(pid)" in _func_source("stop"), "stop() must use _pid_alive"
+    # The helper must special-case Windows via tasklist (os.kill(pid,0) is invalid there).
+    helper = _func_source("_pid_alive")
+    assert 'sys.platform == "win32"' in helper
+    assert "tasklist" in helper
+
+
+# ── Behavioral: the win32 tasklist branch ────────────────────────────────────
+
+
+def _fake_tasklist(returns_pid: int | None, *, raises: bool = False):
+    def _run(
+        cmd,
+        capture_output = False,
+        text = False,
+        timeout = None,
+    ):
+        assert cmd[0] == "tasklist"
+        assert "/FI" in cmd  # filtered by PID
+        if raises:
+            raise OSError("boom")
+        if returns_pid is None:
+            stdout = "INFO: No tasks are running which match the specified criteria.\n"
+        else:
+            stdout = f'"python.exe","{returns_pid}","Console","1","12,345 K"\n'
+        return types.SimpleNamespace(stdout = stdout, returncode = 0)
+
+    return _run
+
+
+def test_pid_alive_windows_true_when_tasklist_lists_pid():
+    pid_alive = _load_pid_alive("win32", fake_run = _fake_tasklist(4242))
+    assert pid_alive(4242) is True
+
+
+def test_pid_alive_windows_false_when_tasklist_empty():
+    pid_alive = _load_pid_alive("win32", fake_run = _fake_tasklist(None))
+    assert pid_alive(4242) is False
+
+
+def test_pid_alive_windows_assumes_alive_when_tasklist_errors():
+    # Can't determine -> assume alive; taskkill is the source of truth.
+    pid_alive = _load_pid_alive("win32", fake_run = _fake_tasklist(None, raises = True))
+    assert pid_alive(4242) is True
+
+
+# ── Behavioral: the POSIX signal-0 branch (skip on Windows runners) ───────────
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason = "POSIX os.kill(pid,0) branch")
+def test_pid_alive_posix_true_for_self_false_for_dead():
+    pid_alive = _load_pid_alive("linux")
+    assert pid_alive(os.getpid()) is True
+    assert pid_alive(2_000_000_000) is False
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index a458f195b4..b506f764d7 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -1130,6 +1130,33 @@ def run(
 _PID_FILE = STUDIO_HOME / "studio.pid"
 
 
+def _pid_alive(pid: int) -> bool:
+    """Return True if a process with ``pid`` exists.
+
+    ``os.kill(pid, 0)`` raises OSError (WinError 87) for every pid on Windows,
+    so use ``tasklist`` there and the signal-0 probe elsewhere.
+    """
+    if sys.platform == "win32":
+        try:
+            out = subprocess.run(
+                ["tasklist", "/FI", f"PID eq {int(pid)}", "/NH", "/FO", "CSV"],
+                capture_output = True,
+                text = True,
+                timeout = 10,
+            ).stdout
+        except Exception:
+            # Can't determine -- assume alive; taskkill no-ops if already gone.
+            return True
+        return f'"{int(pid)}"' in out
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
 @studio_app.command()
 def stop():
     """Stop a running Unsloth Studio server.
@@ -1151,15 +1178,11 @@ def stop():
 
     pid = int(pid_text)
 
-    # Check if the process is still alive
-    try:
-        os.kill(pid, 0)
-    except ProcessLookupError:
+    # Check if still alive (os.kill(pid, 0) is invalid on Windows -- see _pid_alive).
+    if not _pid_alive(pid):
         typer.echo(f"Studio server (PID {pid}) is not running. Cleaning up stale PID file.")
         _PID_FILE.unlink(missing_ok = True)
         raise typer.Exit(0)
-    except PermissionError:
-        pass  # process exists but we may not own it; try to signal anyway
 
     # Send SIGTERM (graceful shutdown) or TerminateProcess on Windows
     try:
@@ -1176,17 +1199,13 @@ def stop():
         typer.echo(f"Failed to stop Studio server (PID {pid}): {e}", err = True)
         raise typer.Exit(1)
 
-    # Wait briefly for the process to exit and clean up
+    # Wait briefly for the process to exit and clean up.
     for _ in range(10):
         time.sleep(0.5)
-        try:
-            os.kill(pid, 0)
-        except ProcessLookupError:
+        if not _pid_alive(pid):
             _PID_FILE.unlink(missing_ok = True)
             typer.echo("Studio server stopped.")
             raise typer.Exit(0)
-        except PermissionError:
-            break
 
     typer.echo("Studio server is shutting down (may take a few seconds).")
 

From dfb49fd2cbb349b78ee84da810b2aaba868db7df Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 05:11:15 -0700
Subject: [PATCH 137/222] Studio: bulk export and import in Settings Chat Data,
 MCP pill off switch (#6141)

* Studio: bulk export and import in Settings Chat Data, MCP pill off switch

- Settings -> Chat -> Data gains Export Recents and Projects (Recents or
  Recents + Projects, Raw JSONL / CSV / ShareGPT, combined or per chat)
  and Import chats, reusing the sidebar Recents menu actions
- Extract bulkExportConversationsByScope so the sidebar and Settings share
  one implementation; expose the export and import helpers via the chat
  feature index
- MCP composer pill icon now swaps to an X on hover like Search, Code and
  RAG; clicking it turns MCP off without opening the server menu
- en and zh-CN locale strings added (parity check passes)

* Reveal the pill X on hover for off-switch icons regardless of active look

The X was gated on data-active, so an MCP pill with no servers enabled
(or a RAG pill without a model) closed on icon click but never showed
the affordance. Off-switch pills only render while their feature is on,
so hover now always reveals the X.

* Replace the Recents hamburger menu with an Export all chats link to Settings

Bulk export and import now live in Settings -> Chat -> Data, so the
sidebar Recents header menu is gone. Each chat's Export submenu gains
Export all chats, which opens Settings on the Chat tab.
---
 .../frontend/src/components/app-sidebar.tsx   | 117 ++---------------
 studio/frontend/src/features/chat/index.ts    |   5 +
 .../src/features/chat/mcp-composer-button.tsx |  26 +++-
 .../prompt-storage/prompt-storage-dialog.tsx  |  31 +++++
 .../src/features/settings/tabs/chat-tab.tsx   | 123 +++++++++++++++++-
 studio/frontend/src/i18n/locales/en.ts        |  16 +++
 studio/frontend/src/i18n/locales/zh-CN.ts     |  16 +++
 studio/frontend/src/index.css                 |  14 ++
 8 files changed, 233 insertions(+), 115 deletions(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 6fe3c5c787..14131c3c1c 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -51,7 +51,6 @@ import {
   Delete02Icon,
   Download01Icon,
   DownloadSquare01Icon,
-  Upload01Icon,
   Edit03Icon,
   FolderAddIcon,
   FolderExportIcon,
@@ -72,11 +71,6 @@ import {
   exportConversationRawJsonl,
   exportConversationCsv,
   exportConversationShareGPT,
-  exportBulkConversationsMerged,
-  exportBulkConversationsSeparate,
-  importConversationsFromFile,
-  EXPORT_FORMATS_LIST,
-  type ConvExportFormat,
 } from "@/features/chat/prompt-storage/prompt-storage-dialog";
 import { listStoredChatThreads } from "@/features/chat/utils/chat-history-storage";
 import {
@@ -259,40 +253,6 @@ export function AppSidebar() {
   const isStudioRoute = pathname === "/studio" || pathname.startsWith("/studio/");
   const [chatOpen, setChatOpen] = useState(true);
 
-  const recentsImportInputRef = useRef<HTMLInputElement>(null);
-
-  async function handleImportToRecents(file: File) {
-    try {
-      const count = await importConversationsFromFile(file, null);
-      if (count === 0) {
-        toast.info("No conversations found in file.");
-      } else {
-        toast.success(`Imported ${count} conversation${count === 1 ? "" : "s"} to Recents.`);
-      }
-    } catch {
-      toast.error("Import failed.");
-    }
-  }
-
-  async function handleBulkExport(scope: "recents" | "all", fmt: ConvExportFormat, merged: boolean) {
-    try {
-      const threads = await listStoredChatThreads({
-        includeArchived: false,
-        ...(scope === "recents" ? { projectId: null } : {}),
-      });
-      const ids = [...new Set(threads.map((t) => t.id))];
-      if (ids.length === 0) { toast.info("No conversations to export."); return; }
-      const ts = new Date().toISOString().slice(0, 10);
-      const basename = scope === "all" ? `all-chats-${ts}` : `recents-${ts}`;
-      if (merged) {
-        await exportBulkConversationsMerged(ids, fmt, basename);
-      } else {
-        await exportBulkConversationsSeparate(ids, fmt, basename);
-      }
-    } catch {
-      toast.error("Export failed.");
-    }
-  }
   const [trainOpen, setTrainOpen] = useState(true);
   const [runsOpen, setRunsOpen] = useState(true);
 
@@ -719,6 +679,15 @@ export function AppSidebar() {
                     {label}
                   </DropdownMenuItem>
                 ))}
+                <DropdownMenuSeparator />
+                {/* Bulk export and import live in Settings -> Chat -> Data. */}
+                <DropdownMenuItem
+                  onSelect={() =>
+                    useSettingsDialogStore.getState().openDialog("chat")
+                  }
+                >
+                  Export all chats…
+                </DropdownMenuItem>
               </DropdownMenuSubContent>
             </DropdownMenuSub>
             <DropdownMenuItem
@@ -736,18 +705,6 @@ export function AppSidebar() {
 
   return (
     <>
-    {/* Hidden file inputs for chat import */}
-    <input
-      ref={recentsImportInputRef}
-      type="file"
-      accept=".jsonl,.ndjson,.csv"
-      className="hidden"
-      onChange={(e) => {
-        const file = e.target.files?.[0];
-        if (file) void handleImportToRecents(file);
-        e.target.value = "";
-      }}
-    />
     <Sidebar
       collapsible="icon"
       variant="sidebar"
@@ -966,62 +923,6 @@ export function AppSidebar() {
                     {t("shell.navigation.recents")}
                     <ChevronDown className="size-3.5 opacity-0 transition-[transform,opacity] duration-200 group-hover/sb-collap:opacity-100 group-focus-visible/sb-collap:opacity-100 data-[state=open]:rotate-0 [[data-state=closed]_&]:rotate-[-90deg] [[data-state=closed]_&]:opacity-100" />
                   </CollapsibleTrigger>
-                  <DropdownMenu>
-                    <DropdownMenuTrigger asChild>
-                      <button
-                        type="button"
-                        className="ml-auto flex items-center justify-center rounded-sm p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground focus:outline-none focus-visible:ring-0"
-                        title="Export recents"
-                      >
-                        <MoreHorizontalIcon className="size-3.5" />
-                      </button>
-                    </DropdownMenuTrigger>
-                    <DropdownMenuContent side="bottom" align="start" className="w-56">
-                      <DropdownMenuItem onSelect={() => recentsImportInputRef.current?.click()}>
-                        <HugeiconsIcon icon={Upload01Icon} strokeWidth={1.75} className="size-icon mr-1" />
-                        Import chats
-                      </DropdownMenuItem>
-                      <DropdownMenuSeparator />
-                      <DropdownMenuSub>
-                        <DropdownMenuSubTrigger>
-                          <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon mr-1" />
-                          Export Recents
-                        </DropdownMenuSubTrigger>
-                        <DropdownMenuSubContent avoidCollisions={false} className="unsloth-plus-menu w-52">
-                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
-                            <DropdownMenuItem key={`r-m-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, true)}>
-                              {label} — combined
-                            </DropdownMenuItem>
-                          ))}
-                          <DropdownMenuSeparator />
-                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
-                            <DropdownMenuItem key={`r-s-${fmt}`} onSelect={() => void handleBulkExport("recents", fmt, false)}>
-                              {label} — per chat
-                            </DropdownMenuItem>
-                          ))}
-                        </DropdownMenuSubContent>
-                      </DropdownMenuSub>
-                      <DropdownMenuSub>
-                        <DropdownMenuSubTrigger>
-                          <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon mr-1" />
-                          Export Recents + Projects
-                        </DropdownMenuSubTrigger>
-                        <DropdownMenuSubContent avoidCollisions={false} className="unsloth-plus-menu w-52">
-                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
-                            <DropdownMenuItem key={`a-m-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, true)}>
-                              {label} — combined
-                            </DropdownMenuItem>
-                          ))}
-                          <DropdownMenuSeparator />
-                          {EXPORT_FORMATS_LIST.map(({ fmt, label }) => (
-                            <DropdownMenuItem key={`a-s-${fmt}`} onSelect={() => void handleBulkExport("all", fmt, false)}>
-                              {label} — per chat
-                            </DropdownMenuItem>
-                          ))}
-                        </DropdownMenuSubContent>
-                      </DropdownMenuSub>
-                    </DropdownMenuContent>
-                  </DropdownMenu>
                 </div>
               </SidebarGroupLabel>
               <CollapsibleContent>
diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.ts
index ac05c8c089..bfaf29f519 100644
--- a/studio/frontend/src/features/chat/index.ts
+++ b/studio/frontend/src/features/chat/index.ts
@@ -29,6 +29,11 @@ export {
   useSelectedChatArtifact,
 } from "./artifacts/store";
 export { downloadChatExport } from "./utils/export-chat-history";
+export {
+  EXPORT_FORMATS_LIST,
+  bulkExportConversationsByScope,
+  importConversationsFromFile,
+} from "./prompt-storage/prompt-storage-dialog";
 export {
   deleteChatItem,
   renameChatItem,
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index ae6c97528e..e0f024a40e 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -3,6 +3,7 @@
 
 import { McpServerIcon, Tick02Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
+import { XIcon } from "lucide-react";
 import { type FC, useCallback, useEffect, useState } from "react";
 import { toast } from "sonner";
 
@@ -248,11 +249,26 @@ export function McpComposerButton({
               data-active={active ? "true" : "false"}
               aria-label="MCP servers"
             >
-              <HugeiconsIcon
-                icon={McpServerIcon}
-                className="size-[15px]"
-                strokeWidth={2}
-              />
+              {/* Icon doubles as an off switch: hover swaps to an X; clicking
+                  it turns MCP off without opening the menu. */}
+              <span
+                role="button"
+                aria-label="Turn off MCP"
+                tabIndex={-1}
+                onPointerDown={(e) => e.stopPropagation()}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  setMcpEnabledForChat(false);
+                }}
+                className="composer-pill-glyph cursor-pointer"
+              >
+                <HugeiconsIcon
+                  icon={McpServerIcon}
+                  className="size-[15px]"
+                  strokeWidth={2}
+                />
+                <XIcon className="composer-pill-x" />
+              </span>
               <span>MCP</span>
               <ArrowDownStandardIcon className="composer-pill-caret size-[15px]" />
             </button>
diff --git a/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
index 3908c313b6..e62f96720d 100644
--- a/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
+++ b/studio/frontend/src/features/chat/prompt-storage/prompt-storage-dialog.tsx
@@ -48,6 +48,7 @@ import {
 } from "../api/prompts-api";
 import {
   listStoredChatMessages,
+  listStoredChatThreads,
   saveStoredChatThread,
   syncStoredChatMessages,
 } from "../utils/chat-history-storage";
@@ -493,6 +494,36 @@ export async function exportBulkConversationsSeparate(
   );
 }
 
+// Scope-level bulk export shared by the sidebar Recents menu and
+// Settings -> Chat -> Data. "recents" = chats outside projects; "all" adds
+// project chats.
+export async function bulkExportConversationsByScope(
+  scope: "recents" | "all",
+  format: ConvExportFormat,
+  merged: boolean,
+): Promise<void> {
+  try {
+    const threads = await listStoredChatThreads({
+      includeArchived: false,
+      ...(scope === "recents" ? { projectId: null } : {}),
+    });
+    const ids = [...new Set(threads.map((t) => t.id))];
+    if (ids.length === 0) {
+      toast.info("No conversations to export.");
+      return;
+    }
+    const ts = new Date().toISOString().slice(0, 10);
+    const basename = scope === "all" ? `all-chats-${ts}` : `recents-${ts}`;
+    if (merged) {
+      await exportBulkConversationsMerged(ids, format, basename);
+    } else {
+      await exportBulkConversationsSeparate(ids, format, basename);
+    }
+  } catch {
+    toast.error("Export failed.");
+  }
+}
+
 export async function exportProjectConversations(
   threadIds: string[],
   format: ConvExportFormat,
diff --git a/studio/frontend/src/features/settings/tabs/chat-tab.tsx b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
index e37d56e2f7..9a81bdab0d 100644
--- a/studio/frontend/src/features/settings/tabs/chat-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/chat-tab.tsx
@@ -13,15 +13,32 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  EXPORT_FORMATS_LIST,
+  bulkExportConversationsByScope,
   clearAllChats,
   countAllChats,
   downloadChatExport,
+  importConversationsFromFile,
   useChatRuntimeStore,
 } from "@/features/chat";
 import { useT } from "@/i18n";
-import { Delete02Icon, Download01Icon } from "@hugeicons/core-free-icons";
+import {
+  Delete02Icon,
+  Download01Icon,
+  Upload01Icon,
+} from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { SettingsRow } from "../components/settings-row";
 import { SettingsSection } from "../components/settings-section";
 
@@ -61,6 +78,25 @@ export function ChatTab() {
     }
   };
 
+  const importInputRef = useRef<HTMLInputElement>(null);
+  const handleImport = async (file: File) => {
+    try {
+      const imported = await importConversationsFromFile(file, null);
+      if (imported === 0) {
+        toast.info(t("settings.chat.importNoConversations"));
+      } else {
+        toast.success(
+          imported === 1
+            ? t("settings.chat.importedOneChat")
+            : t("settings.chat.importedChatCount", { count: imported }),
+        );
+        setCount(await countAllChats().catch(() => count));
+      }
+    } catch {
+      toast.error(t("settings.chat.importFailed"));
+    }
+  };
+
   const handleClear = async () => {
     setClearing(true);
     try {
@@ -172,6 +208,89 @@ export function ChatTab() {
           </Button>
         </SettingsRow>
 
+        <SettingsRow
+          label={t("settings.chat.exportConversations")}
+          description={t("settings.chat.exportConversationsDescription")}
+        >
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild={true}>
+              <Button variant="outline" size="sm" disabled={count === 0}>
+                <HugeiconsIcon
+                  icon={Download01Icon}
+                  className="size-3.5 mr-1.5"
+                />
+                {t("settings.chat.exportConversationsAction")}
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-56">
+              {(
+                [
+                  { scope: "recents", label: "exportScopeRecents" },
+                  { scope: "all", label: "exportScopeAll" },
+                ] as const
+              ).map(({ scope, label }) => (
+                <DropdownMenuSub key={scope}>
+                  <DropdownMenuSubTrigger>
+                    <HugeiconsIcon
+                      icon={Download01Icon}
+                      className="size-3.5 mr-1"
+                    />
+                    {t(`settings.chat.${label}`)}
+                  </DropdownMenuSubTrigger>
+                  <DropdownMenuSubContent className="w-56">
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label: fmtLabel }) => (
+                      <DropdownMenuItem
+                        key={`${scope}-m-${fmt}`}
+                        onSelect={() =>
+                          void bulkExportConversationsByScope(scope, fmt, true)
+                        }
+                      >
+                        {fmtLabel} {t("settings.chat.exportCombinedSuffix")}
+                      </DropdownMenuItem>
+                    ))}
+                    <DropdownMenuSeparator />
+                    {EXPORT_FORMATS_LIST.map(({ fmt, label: fmtLabel }) => (
+                      <DropdownMenuItem
+                        key={`${scope}-s-${fmt}`}
+                        onSelect={() =>
+                          void bulkExportConversationsByScope(scope, fmt, false)
+                        }
+                      >
+                        {fmtLabel} {t("settings.chat.exportPerChatSuffix")}
+                      </DropdownMenuItem>
+                    ))}
+                  </DropdownMenuSubContent>
+                </DropdownMenuSub>
+              ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </SettingsRow>
+
+        <SettingsRow
+          label={t("settings.chat.importChats")}
+          description={t("settings.chat.importChatsDescription")}
+        >
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => importInputRef.current?.click()}
+          >
+            <HugeiconsIcon icon={Upload01Icon} className="size-3.5 mr-1.5" />
+            {t("settings.chat.importChatsAction")}
+          </Button>
+          <input
+            ref={importInputRef}
+            type="file"
+            accept=".jsonl,.ndjson,.csv"
+            className="hidden"
+            onChange={(e) => {
+              const file = e.target.files?.[0];
+              e.target.value = "";
+              if (file) void handleImport(file);
+            }}
+          />
+        </SettingsRow>
+
         <SettingsRow
           destructive
           label={t("settings.chat.clearAllChats")}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 1492c7bb2b..a0ee28fd86 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -198,6 +198,22 @@ export const en = {
         "Download all chats and messages as a JSON file.",
       exportAction: "Export",
       exportingAction: "Exporting...",
+      exportConversations: "Export Recents and Projects",
+      exportConversationsDescription:
+        "Download Recents only, or Recents plus project chats, as Raw JSONL, CSV, or ShareGPT JSONL, combined or one file per chat.",
+      exportConversationsAction: "Export",
+      exportScopeRecents: "Recents",
+      exportScopeAll: "Recents + Projects",
+      exportCombinedSuffix: "(combined)",
+      exportPerChatSuffix: "(per chat)",
+      importChats: "Import chats",
+      importChatsDescription:
+        "Add conversations from a JSONL, NDJSON, or CSV export to Recents.",
+      importChatsAction: "Import",
+      importNoConversations: "No conversations found in file.",
+      importedOneChat: "Imported 1 conversation to Recents.",
+      importedChatCount: "Imported {count} conversations to Recents.",
+      importFailed: "Import failed.",
       clearHistory: "Clear chat history",
       clearHistoryDescription: "Delete local chat history from this device.",
       clearAction: "Clear",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 3cfea1ae7a..e7d3babfe9 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -174,6 +174,22 @@ export const zhCN = {
       exportHistoryDescription: "将所有聊天和消息下载为 JSON 文件。",
       exportAction: "导出",
       exportingAction: "导出中...",
+      exportConversations: "导出最近对话与项目",
+      exportConversationsDescription:
+        "将最近对话（或加上项目内对话）导出为 Raw JSONL、CSV 或 ShareGPT JSONL，可合并为单个文件或每个对话一个文件。",
+      exportConversationsAction: "导出",
+      exportScopeRecents: "最近对话",
+      exportScopeAll: "最近对话 + 项目",
+      exportCombinedSuffix: "（合并）",
+      exportPerChatSuffix: "（每个对话）",
+      importChats: "导入对话",
+      importChatsDescription:
+        "从 JSONL、NDJSON 或 CSV 导出文件将对话导入到最近对话。",
+      importChatsAction: "导入",
+      importNoConversations: "文件中未找到对话。",
+      importedOneChat: "已导入 1 个对话到最近对话。",
+      importedChatCount: "已导入 {count} 个对话到最近对话。",
+      importFailed: "导入失败。",
       clearHistory: "清除聊天记录",
       clearHistoryDescription: "从此设备删除本地聊天记录。",
       clearAction: "清除",
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 76721eaa63..48e587953f 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -1077,6 +1077,20 @@
 		@apply opacity-100;
 	}
 
+	/* Pills whose icon is an off switch (RAG, MCP) only render while the
+	   feature is on, so reveal the X on hover even when the pill is not in
+	   its active look (MCP with no servers enabled, RAG without a model). */
+	.composer-pill-btn:has(> .composer-pill-glyph[role="button"]):hover
+		.composer-pill-glyph
+		> :not(.composer-pill-x) {
+		@apply opacity-0;
+	}
+
+	.composer-pill-btn:has(> .composer-pill-glyph[role="button"]):hover
+		.composer-pill-x {
+		@apply opacity-100;
+	}
+
 	.composer-input {
 		@apply mt-2 mb-1 mx-3 min-h-12 w-[calc(100%-1.5rem)] resize-none overflow-y-auto bg-transparent pl-2 pr-4 pt-2 pb-3 text-sm font-[450] outline-none placeholder:text-muted-foreground focus-visible:ring-0;
 	}

From 3cd0b9b18e32f3ea99dafcd24c88b2c4dcd8005b Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 05:15:00 -0700
Subject: [PATCH 138/222] Studio: fix nested dropdown submenus clipped by the
 menu alignment nudge (#6143)

* Studio: fix nested dropdown submenus clipped by the menu alignment nudge

The 3px alignment nudge on DropdownMenuContent used translate, which
makes the scroll container the containing block for nested
position:fixed submenu wrappers, so overflow clipped every submenu
(plus menu More and Projects, sidebar chat menus, Recents export).
Use margin for the same visual shift without a containing block.

* Portal dropdown submenus so ancestor styling can never clip them

Rendered inline, the fixed submenu wrapper lives inside the parent
menu's scroll container, so any transform there (like the 3px nudge)
re-enables overflow clipping. Portaling to body removes the submenu
from that subtree entirely, same as DropdownMenuContent.
---
 .../src/components/ui/dropdown-menu.tsx       | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/studio/frontend/src/components/ui/dropdown-menu.tsx b/studio/frontend/src/components/ui/dropdown-menu.tsx
index c4f742a164..a39651d939 100644
--- a/studio/frontend/src/components/ui/dropdown-menu.tsx
+++ b/studio/frontend/src/components/ui/dropdown-menu.tsx
@@ -46,7 +46,10 @@ function DropdownMenuContent({
         sideOffset={sideOffset}
         align={align}
         className={cn(
-          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-[calc(var(--radix-dropdown-menu-trigger-width)_+_6px)] data-[align=start]:-translate-x-[3px] data-[align=end]:translate-x-[3px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
+          // The 3px alignment nudge must be margin, not translate: a transform
+          // here makes this scroll container the containing block for nested
+          // position:fixed submenu wrappers, clipping every submenu.
+          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-48 rounded-lg p-1 duration-100 z-50 max-h-(--radix-dropdown-menu-content-available-height) w-[calc(var(--radix-dropdown-menu-trigger-width)_+_6px)] data-[align=start]:-ml-[3px] data-[align=end]:ml-[3px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto data-[state=closed]:overflow-hidden",
           className,
         )}
         {...props}
@@ -241,14 +244,19 @@ function DropdownMenuSubContent({
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
   return (
-    <DropdownMenuPrimitive.SubContent
-      data-slot="dropdown-menu-sub-content"
-      className={cn(
-        "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-36 rounded-lg p-1 duration-100 z-50 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden",
-        className,
-      )}
-      {...props}
-    />
+    // Portaled like DropdownMenuContent: rendered inline, the fixed popper
+    // wrapper is a descendant of the parent menu's scroll container, so any
+    // transform there turns on overflow clipping and hides the submenu.
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.SubContent
+        data-slot="dropdown-menu-sub-content"
+        className={cn(
+          "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 bg-popover text-popover-foreground min-w-36 rounded-lg p-1 duration-100 z-50 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden",
+          className,
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
   );
 }
 

From e4b5bec248dff9c84de29ae88831c67946e328da Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 05:15:12 -0700
Subject: [PATCH 139/222] Studio chat: declutter the plus menu, session-only
 pre-selectable RAG (#6140)

---
 .../src/components/assistant-ui/thread.tsx    | 160 ++++++++--------
 ...-available.ts => use-rag-tool-disabled.ts} |   9 +-
 .../src/features/chat/shared-composer.tsx     | 171 ++++++++++--------
 .../chat/stores/chat-runtime-store.ts         |  14 +-
 .../knowledge-base-composer-button.tsx        |  12 +-
 .../rag/components/thread-documents-bar.tsx   |   7 +-
 6 files changed, 190 insertions(+), 183 deletions(-)
 rename studio/frontend/src/features/chat/hooks/{use-rag-tool-available.ts => use-rag-tool-disabled.ts} (60%)

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 8146c4603b..ea660f7af8 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -64,7 +64,7 @@ import { NewProjectDialog } from "@/features/chat/components/new-project-dialog"
 import { parseExternalModelId } from "@/features/chat/external-providers";
 import { McpComposerButton } from "@/features/chat/mcp-composer-button";
 import { getExternalReasoningCapabilities } from "@/features/chat/provider-capabilities";
-import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
+import { useRagToolDisabled } from "@/features/chat/hooks/use-rag-tool-disabled";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
 import { useExternalProvidersStore } from "@/features/chat/stores/external-providers-store";
 import { deleteThreadMessage } from "@/features/chat/utils/delete-thread-message";
@@ -876,12 +876,11 @@ const Composer: FC<{
   const artifactsEnabled = useChatRuntimeStore((s) => s.artifactsEnabled);
   const mcpEnabledForChat = useChatRuntimeStore((s) => s.mcpEnabledForChat);
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
-  const ragToolAvailable = useRagToolAvailable();
   // More than 4 pills: collapse to icons only. Search and Code always show;
-  // Images, Canvas and MCP are conditional.
+  // Images, RAG, Canvas and MCP are conditional.
   const pillsCompact =
     2 +
-      (ragEnabled && ragToolAvailable ? 1 : 0) +
+      (ragEnabled ? 1 : 0) +
       (supportsBuiltinImageGeneration ? 1 : 0) +
       (artifactsEnabled ? 1 : 0) +
       (mcpEnabledForChat ? 1 : 0) >
@@ -2017,8 +2016,8 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   );
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
   const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
-  // Shared gate so the menu row agrees with the RAG pill and Add Files bar.
-  const ragAvailable = useRagToolAvailable();
+  // Shared gate so the menu row agrees with the RAG pill.
+  const ragDisabled = useRagToolDisabled();
   // Capability gating mirrors the visible pills so menu and pills agree on
   // what a loaded model supports (a tool the backend drops must not look on).
   const modelLoaded = useChatRuntimeStore(
@@ -2180,10 +2179,11 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
           }
           onSelect={() => setCodeToolsEnabled(!codeToolsEnabled)}
         >
+          {/* Scale, not width: an oversized box pushed the label out of line. */}
           <HugeiconsIcon
             icon={CodeIcon}
             strokeWidth={2}
-            className="size-[1.175rem]!"
+            className="scale-[1.12]"
           />
           Code
           {codeToolsEnabled && !codeDisabled ? (
@@ -2217,15 +2217,15 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
         )}
         <DropdownMenuSeparator />
         <DropdownMenuItem
-          disabled={!ragAvailable}
+          disabled={ragDisabled}
           className={
-            ragEnabled && ragAvailable ? "text-primary font-medium" : undefined
+            ragEnabled && !ragDisabled ? "text-primary font-medium" : undefined
           }
           onSelect={() => setRagEnabled(!ragEnabled)}
         >
           <HugeiconsIcon icon={FileDatabaseIcon} strokeWidth={2} />
-          RAG
-          {ragEnabled && ragAvailable ? (
+          Chat with Files
+          {ragEnabled && !ragDisabled ? (
             <HugeiconsIcon
               icon={Tick02Icon}
               strokeWidth={2}
@@ -2252,80 +2252,82 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
             />
           ) : null}
         </DropdownMenuItem>
-        {/* Top-level so it stays one click away (not buried in More). */}
-        <DropdownMenuItem onSelect={() => startCompare()}>
-          <Columns2Icon />
-          Compare chat
-        </DropdownMenuItem>
-        <DropdownMenuSub>
-          <DropdownMenuSubTrigger>
-            <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
-            Saved prompts
-          </DropdownMenuSubTrigger>
-          <DropdownMenuSubContent className="unsloth-plus-menu w-[176px]">
-            {recentPrompts.map((p) => (
-              <DropdownMenuItem
-                key={p.id}
-                onSelect={() => aui.composer().setText(p.text)}
-              >
-                <span className="truncate">{p.name}</span>
-              </DropdownMenuItem>
-            ))}
-            {recentPrompts.length > 0 ? <DropdownMenuSeparator /> : null}
-            <DropdownMenuItem onSelect={() => setPromptStorageOpen(true)}>
-              All saved prompts…
-            </DropdownMenuItem>
-          </DropdownMenuSubContent>
-        </DropdownMenuSub>
-        {/* Top-level: a third-level submenu collision-flips at narrow widths
-            and is awkward to reach. */}
-        <DropdownMenuSub>
-          <DropdownMenuSubTrigger disabled={!activeThreadId || messageCount === 0}>
-            <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
-            Export chat
-          </DropdownMenuSubTrigger>
-          <DropdownMenuSubContent
-            collisionPadding={16}
-            className="unsloth-plus-menu w-[176px]"
-          >
-            <DropdownMenuItem
-              onSelect={() => {
-                if (!activeThreadId) return;
-                exportConversationRawJsonl(activeThreadId).catch(() =>
-                  toast.error("Export failed."),
-                );
-              }}
-            >
-              Raw JSONL
-            </DropdownMenuItem>
-            <DropdownMenuItem
-              onSelect={() => {
-                if (!activeThreadId) return;
-                exportConversationCsv(activeThreadId).catch(() =>
-                  toast.error("Export failed."),
-                );
-              }}
-            >
-              CSV
-            </DropdownMenuItem>
-            <DropdownMenuItem
-              onSelect={() => {
-                if (!activeThreadId) return;
-                exportConversationShareGPT(activeThreadId).catch(() =>
-                  toast.error("Export failed."),
-                );
-              }}
-            >
-              ShareGPT JSONL
-            </DropdownMenuItem>
-          </DropdownMenuSubContent>
-        </DropdownMenuSub>
         <DropdownMenuSub>
           <DropdownMenuSubTrigger>
             <MoreHorizontalIcon className="size-4" />
             More
           </DropdownMenuSubTrigger>
           <DropdownMenuSubContent className="w-[200px]">
+            <DropdownMenuItem onSelect={() => startCompare()}>
+              <Columns2Icon />
+              Compare chat
+            </DropdownMenuItem>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger>
+                <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
+                Saved prompts
+              </DropdownMenuSubTrigger>
+              <DropdownMenuSubContent
+                collisionPadding={16}
+                className="unsloth-plus-menu w-[176px]"
+              >
+                {recentPrompts.map((p) => (
+                  <DropdownMenuItem
+                    key={p.id}
+                    onSelect={() => aui.composer().setText(p.text)}
+                  >
+                    <span className="truncate">{p.name}</span>
+                  </DropdownMenuItem>
+                ))}
+                {recentPrompts.length > 0 ? <DropdownMenuSeparator /> : null}
+                <DropdownMenuItem onSelect={() => setPromptStorageOpen(true)}>
+                  All saved prompts…
+                </DropdownMenuItem>
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
+            <DropdownMenuSub>
+              <DropdownMenuSubTrigger
+                disabled={!activeThreadId || messageCount === 0}
+              >
+                <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
+                Export chat
+              </DropdownMenuSubTrigger>
+              <DropdownMenuSubContent
+                collisionPadding={16}
+                className="unsloth-plus-menu w-[176px]"
+              >
+                <DropdownMenuItem
+                  onSelect={() => {
+                    if (!activeThreadId) return;
+                    exportConversationRawJsonl(activeThreadId).catch(() =>
+                      toast.error("Export failed."),
+                    );
+                  }}
+                >
+                  Raw JSONL
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  onSelect={() => {
+                    if (!activeThreadId) return;
+                    exportConversationCsv(activeThreadId).catch(() =>
+                      toast.error("Export failed."),
+                    );
+                  }}
+                >
+                  CSV
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  onSelect={() => {
+                    if (!activeThreadId) return;
+                    exportConversationShareGPT(activeThreadId).catch(() =>
+                      toast.error("Export failed."),
+                    );
+                  }}
+                >
+                  ShareGPT JSONL
+                </DropdownMenuItem>
+              </DropdownMenuSubContent>
+            </DropdownMenuSub>
             <DropdownMenuItem
               className={
                 artifactsEnabled ? "text-primary font-medium" : undefined
diff --git a/studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts b/studio/frontend/src/features/chat/hooks/use-rag-tool-disabled.ts
similarity index 60%
rename from studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts
rename to studio/frontend/src/features/chat/hooks/use-rag-tool-disabled.ts
index 4463aa3cd4..4f0912e435 100644
--- a/studio/frontend/src/features/chat/hooks/use-rag-tool-available.ts
+++ b/studio/frontend/src/features/chat/hooks/use-rag-tool-disabled.ts
@@ -4,15 +4,16 @@
 import { parseExternalModelId } from "../external-providers";
 import { useChatRuntimeStore } from "../stores/chat-runtime-store";
 
-// Single source of truth for the RAG pill's disabled gate and the Add Files bar's
-// visibility so the bar never shows while the pill is inert.
-export function useRagToolAvailable(): boolean {
+// Pre-select gate for the RAG toggle, mirroring Web search/Code/MCP: armable
+// with no model; disabled only when a loaded model can't run
+// search_knowledge_base. The send path checks supportsTools independently.
+export function useRagToolDisabled(): boolean {
   const modelLoaded = useChatRuntimeStore(
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
   return (
-    modelLoaded && parseExternalModelId(checkpoint) === null && supportsTools
+    modelLoaded && (parseExternalModelId(checkpoint) !== null || !supportsTools)
   );
 }
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index f68ec6cc73..fe71adf4d7 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -656,8 +656,10 @@ export function SharedComposer({
   // Fetch pill: Anthropic-only (web_fetch_20250910 / web_fetch_20260209).
   const webFetchDisabled = !modelLoaded || !supportsBuiltinWebFetch;
   const showWebFetchPill = supportsBuiltinWebFetch;
-  // Docs (RAG) pill is local-only: search_knowledge_base needs the local runtime.
-  const ragDisabled = !modelLoaded || isExternalModel || !supportsTools;
+  // Docs (RAG) is local-only: search_knowledge_base needs the local runtime.
+  // Disable only when a loaded model can't run it; with no model the toggle
+  // can still be pre-selected, matching Web search/Code/MCP.
+  const ragDisabled = modelLoaded && (isExternalModel || !supportsTools);
   const showRagPill = !isExternalModel;
   // Above 4 pills, collapse to icons only to cut clutter. Compare, Search and
   // Code always show; the rest are conditional.
@@ -1323,10 +1325,12 @@ export function SharedComposer({
                 }
                 onSelect={() => setCodeToolsEnabled(!codeToolsEnabled)}
               >
+                {/* Scale, not width: an oversized box pushed the label out of
+                    line. */}
                 <HugeiconsIcon
                   icon={CodeIcon}
                   strokeWidth={2}
-                  className="size-[1.175rem]!"
+                  className="scale-[1.12]"
                 />
                 Code
                 {codeToolsEnabled && !codeDisabled ? (
@@ -1369,7 +1373,7 @@ export function SharedComposer({
                 onSelect={() => setRagEnabled(!ragEnabled)}
               >
                 <HugeiconsIcon icon={FileDatabaseIcon} strokeWidth={2} />
-                RAG
+                Chat with Files
                 {ragEnabled && !ragDisabled ? (
                   <HugeiconsIcon
                     icon={Tick02Icon}
@@ -1396,88 +1400,95 @@ export function SharedComposer({
                 ) : null}
               </DropdownMenuItem>
               {/* RAG hidden temporarily */}
-              {/* Always active: this menu only renders in compare mode. Ticked
-                  like Web search/Code; click toggles it off. */}
-              <DropdownMenuItem
-                className="text-primary font-medium"
-                onSelect={handleExitCompare}
-              >
-                <Columns2Icon />
-                Compare chat
-                <HugeiconsIcon
-                  icon={Tick02Icon}
-                  strokeWidth={2}
-                  className="ml-auto"
-                />
-              </DropdownMenuItem>
-              <DropdownMenuSub>
-                <DropdownMenuSubTrigger>
-                  <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
-                  Saved prompts
-                </DropdownMenuSubTrigger>
-                <DropdownMenuSubContent className="unsloth-plus-menu w-[176px]">
-                  {recentPrompts.map((p) => (
-                    <DropdownMenuItem
-                      key={p.id}
-                      onSelect={() => {
-                        setText(p.text);
-                        requestAnimationFrame(() =>
-                          textareaRef.current?.focus(),
-                        );
-                      }}
-                    >
-                      <span className="truncate">{p.name}</span>
-                    </DropdownMenuItem>
-                  ))}
-                  {recentPrompts.length > 0 ? <DropdownMenuSeparator /> : null}
-                  <DropdownMenuItem onSelect={() => setPromptStorageOpen(true)}>
-                    All saved prompts…
-                  </DropdownMenuItem>
-                </DropdownMenuSubContent>
-              </DropdownMenuSub>
-              {/* Top-level: a third-level submenu collision-flips at narrow
-                  widths and is awkward to reach. */}
-              <DropdownMenuSub>
-                <DropdownMenuSubTrigger disabled={exportThreadIds.length === 0}>
-                  <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
-                  Export chat
-                </DropdownMenuSubTrigger>
-                <DropdownMenuSubContent
-                  collisionPadding={16}
-                  className="unsloth-plus-menu w-[176px]"
-                >
-                  {[
-                    { label: "Raw JSONL", fn: exportConversationRawJsonl },
-                    { label: "CSV", fn: exportConversationCsv },
-                    {
-                      label: "ShareGPT JSONL",
-                      fn: exportConversationShareGPT,
-                    },
-                  ].map(({ label, fn }) => (
-                    <DropdownMenuItem
-                      key={label}
-                      disabled={exportThreadIds.length === 0}
-                      onSelect={() => {
-                        if (!exportThreadIds.length) {
-                          toast.error("No conversation to export yet.");
-                          return;
-                        }
-                        Promise.all(exportThreadIds.map((id) => fn(id))).catch(
-                          () => toast.error("Export failed."),
-                        );
-                      }}
-                    >
-                      {label}
-                    </DropdownMenuItem>
-                  ))}
-                </DropdownMenuSubContent>
-              </DropdownMenuSub>
               <DropdownMenuSub>
                 <DropdownMenuSubTrigger>
                   <MoreHorizontalIcon className="size-4" />
                   More
                 </DropdownMenuSubTrigger>
                 <DropdownMenuSubContent className="unsloth-plus-menu w-[200px]">
+                  {/* Always active: this menu only renders in compare mode. Ticked
+                      like Web search/Code; click toggles it off. */}
+                  <DropdownMenuItem
+                    className="text-primary font-medium"
+                    onSelect={handleExitCompare}
+                  >
+                    <Columns2Icon />
+                    Compare chat
+                    <HugeiconsIcon
+                      icon={Tick02Icon}
+                      strokeWidth={2}
+                      className="ml-auto"
+                    />
+                  </DropdownMenuItem>
+                  <DropdownMenuSub>
+                    <DropdownMenuSubTrigger>
+                      <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
+                      Saved prompts
+                    </DropdownMenuSubTrigger>
+                    <DropdownMenuSubContent
+                      collisionPadding={16}
+                      className="unsloth-plus-menu w-[176px]"
+                    >
+                      {recentPrompts.map((p) => (
+                        <DropdownMenuItem
+                          key={p.id}
+                          onSelect={() => {
+                            setText(p.text);
+                            requestAnimationFrame(() =>
+                              textareaRef.current?.focus(),
+                            );
+                          }}
+                        >
+                          <span className="truncate">{p.name}</span>
+                        </DropdownMenuItem>
+                      ))}
+                      {recentPrompts.length > 0 ? (
+                        <DropdownMenuSeparator />
+                      ) : null}
+                      <DropdownMenuItem
+                        onSelect={() => setPromptStorageOpen(true)}
+                      >
+                        All saved prompts…
+                      </DropdownMenuItem>
+                    </DropdownMenuSubContent>
+                  </DropdownMenuSub>
+                  <DropdownMenuSub>
+                    <DropdownMenuSubTrigger
+                      disabled={exportThreadIds.length === 0}
+                    >
+                      <HugeiconsIcon icon={Download01Icon} strokeWidth={2} />
+                      Export chat
+                    </DropdownMenuSubTrigger>
+                    <DropdownMenuSubContent
+                      collisionPadding={16}
+                      className="unsloth-plus-menu w-[176px]"
+                    >
+                      {[
+                        { label: "Raw JSONL", fn: exportConversationRawJsonl },
+                        { label: "CSV", fn: exportConversationCsv },
+                        {
+                          label: "ShareGPT JSONL",
+                          fn: exportConversationShareGPT,
+                        },
+                      ].map(({ label, fn }) => (
+                        <DropdownMenuItem
+                          key={label}
+                          disabled={exportThreadIds.length === 0}
+                          onSelect={() => {
+                            if (!exportThreadIds.length) {
+                              toast.error("No conversation to export yet.");
+                              return;
+                            }
+                            Promise.all(
+                              exportThreadIds.map((id) => fn(id)),
+                            ).catch(() => toast.error("Export failed."));
+                          }}
+                        >
+                          {label}
+                        </DropdownMenuItem>
+                      ))}
+                    </DropdownMenuSubContent>
+                  </DropdownMenuSub>
                   <DropdownMenuItem
                     className={
                       artifactsEnabled ? "text-primary font-medium" : undefined
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index f9fb2abe2b..aabf1b29a6 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -36,7 +36,6 @@ export const CHAT_ALLOW_ARTIFACT_NETWORK_ACCESS_KEY =
 export const CHAT_MCP_ENABLED_KEY = "unsloth_chat_mcp_enabled";
 export const CHAT_WEB_FETCH_TOOLS_ENABLED_KEY =
   "unsloth_chat_web_fetch_tools_enabled";
-export const CHAT_RAG_ENABLED_KEY = "unsloth_chat_rag_enabled";
 export const CHAT_RAG_SOURCE_KEY = "unsloth_chat_rag_source";
 export const CHAT_RAG_MODE_KEY = "unsloth_chat_rag_mode";
 export const CHAT_RAG_TOP_K_KEY = "unsloth_chat_rag_top_k";
@@ -480,7 +479,7 @@ type ChatRuntimeStore = {
   setAllowArtifactNetworkAccess: (enabled: boolean) => void;
   setMcpEnabledForChat: (enabled: boolean) => void;
   setWebFetchToolsEnabled: (enabled: boolean) => void;
-  setRagEnabled: (enabled: boolean, options?: { persist?: boolean }) => void;
+  setRagEnabled: (enabled: boolean) => void;
   setRagSource: (source: RagSource) => void;
   setRagMode: (mode: RagMode) => void;
   setRagTopK: (topK: number) => void;
@@ -746,7 +745,8 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   ),
   mcpEnabledForChat: loadBool(CHAT_MCP_ENABLED_KEY, false),
   webFetchToolsEnabled: loadBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, false),
-  ragEnabled: loadBool(CHAT_RAG_ENABLED_KEY, false),
+  // RAG is opt-in per session: always starts off, never restored from storage.
+  ragEnabled: false,
   ragSource: loadRagSource(),
   ragMode: loadRagMode(),
   ragTopK: loadRagTopK(),
@@ -1072,13 +1072,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       saveBool(CHAT_WEB_FETCH_TOOLS_ENABLED_KEY, webFetchToolsEnabled);
       return { webFetchToolsEnabled };
     }),
-  setRagEnabled: (ragEnabled, options) =>
-    set(() => {
-      if (options?.persist !== false) {
-        saveBool(CHAT_RAG_ENABLED_KEY, ragEnabled);
-      }
-      return { ragEnabled };
-    }),
+  setRagEnabled: (ragEnabled) => set(() => ({ ragEnabled })),
   setRagSource: (ragSource) =>
     set(() => {
       saveRagSource(ragSource);
diff --git a/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
index b703fca347..e040d1842a 100644
--- a/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
+++ b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
@@ -14,7 +14,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
+import { useRagToolDisabled } from "@/features/chat/hooks/use-rag-tool-disabled";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
 
 import { listKnowledgeBases } from "../api/rag-api";
@@ -38,8 +38,8 @@ const ArrowDownStandardIcon: FC<{ className?: string }> = ({ className }) => (
   </svg>
 );
 
-// Picks the retrieval source. Only rendered when retrieval is on and the loaded
-// model can run search_knowledge_base.
+// Picks the retrieval source. Shown whenever retrieval is on; dims but stays
+// interactive (so it can be turned off) while the loaded model can't run it.
 export function KnowledgeBaseComposerButton({
   side = "bottom",
 }: {
@@ -47,7 +47,7 @@ export function KnowledgeBaseComposerButton({
 } = {}) {
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
   const setRagEnabled = useChatRuntimeStore((s) => s.setRagEnabled);
-  const ragAvailable = useRagToolAvailable();
+  const ragDisabled = useRagToolDisabled();
   const ragSource = useChatRuntimeStore((s) => s.ragSource);
   const setRagSource = useChatRuntimeStore((s) => s.setRagSource);
 
@@ -85,7 +85,7 @@ export function KnowledgeBaseComposerButton({
     }
   }, [kbs, kbsLoaded, ragSource, setRagSource]);
 
-  if (!ragEnabled || !ragAvailable) return null;
+  if (!ragEnabled) return null;
 
   return (
     <>
@@ -100,7 +100,7 @@ export function KnowledgeBaseComposerButton({
           <button
             type="button"
             className="composer-pill-btn"
-            data-active="true"
+            data-active={ragDisabled ? "false" : "true"}
             aria-label="Retrieval source"
           >
             {/* Icon doubles as an off switch: hover swaps to an X; clicking it
diff --git a/studio/frontend/src/features/rag/components/thread-documents-bar.tsx b/studio/frontend/src/features/rag/components/thread-documents-bar.tsx
index 6ba0440699..38677c27c4 100644
--- a/studio/frontend/src/features/rag/components/thread-documents-bar.tsx
+++ b/studio/frontend/src/features/rag/components/thread-documents-bar.tsx
@@ -7,7 +7,6 @@ import { AttachmentIcon, FileDatabaseIcon } from "@hugeicons/core-free-icons";
 import { useAui } from "@assistant-ui/react";
 import { cn } from "@/lib/utils";
 import { useChatRuntimeStore } from "@/features/chat/stores/chat-runtime-store";
-import { useRagToolAvailable } from "@/features/chat/hooks/use-rag-tool-available";
 import { toast } from "@/lib/toast";
 import { listKnowledgeBases, listThreadDocuments } from "../api/rag-api";
 import { RAG_UPLOAD_ACCEPT } from "../types/rag";
@@ -55,7 +54,6 @@ export function ThreadDocumentsBar({
   onIndexingChange?: (active: boolean) => void;
 }) {
   const ragEnabled = useChatRuntimeStore((s) => s.ragEnabled);
-  const ragAvailable = useRagToolAvailable();
   const ragSource = useChatRuntimeStore((s) => s.ragSource);
   const aui = useAui();
   const fileInputRef = useRef<HTMLInputElement>(null);
@@ -137,8 +135,9 @@ export function ThreadDocumentsBar({
     fileInputRef.current?.click();
   }, []);
 
-  // Only when the RAG pill is on: enabled AND a tool-capable model loaded.
-  if (!ragEnabled || !ragAvailable) return null;
+  // Shown whenever the RAG pill is on: ingestion only needs the embedder, so
+  // files can index before a chat model loads.
+  if (!ragEnabled) return null;
   // A KB source uploads via the KB dialog, not here; show which KB is active.
   if (ragSource.type === "kb") {
     return <KnowledgeBaseSourceChip kbId={ragSource.kbId} />;

From 756e12938877eb0abb5e645302544a0e0751dbd6 Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Wed, 10 Jun 2026 07:32:32 -0500
Subject: [PATCH 140/222] fix/validate dataset video paths before training
 (#5136)

* fix(vision): validate dataset video paths before training

* fix(vision): remove redundant warnings import, add pytest tests for #5085

* fix(trainer): auto-validate video paths in UnslothVisionDataCollator on first batch (#5085)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* refactor(vision): use str.removeprefix instead of slicing (Datta0 review)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* style: replace em dashes with hyphens in error message and docstring

* Update unsloth/models/vision.py

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Split: keep only 1 file(s)

* fix(vision): broaden video-path validation to all collator inputs

- check_dataset_for_missing_videos now accepts every example shape that
  UnslothVisionDataCollator forwards to process_vision_info:
  dict rows with "messages"/"conversations"/"prompt"/"completion", and raw
  message-list rows.  Earlier logic only handled {"messages": [...]}, so
  conversations/prompt/completion datasets silently skipped validation and
  raw message-list rows crashed on list.get.
- Guard against non-dict message entries; a bare string inside a message
  list no longer raises AttributeError.
- Decode file:// URIs via urllib so percent-encoded paths, absolute
  Windows URIs (file:///C:/...) and host-qualified URIs
  (file://localhost/abs/path) map back to their real filesystem path.
- Expose an optional "checked" set so callers can reuse dedup state across
  invocations.
- Docstring warns that passing a streaming IterableDataset consumes the
  iterator.

UnslothVisionDataCollator now validates every batch (not just batch 0)
and applies formatting_func before validation, matching the base
collator's own ordering so formatter-generated video paths are also
checked.  The already-checked set is shared across batches, so per-batch
cost stays proportional to newly seen paths.

* fix(vision): robust URI + scheme handling in video-path validator

- _local_path_from_video_value now treats anything with a "://" prefix
  as a URI and validates only file:// URIs.  This prevents false
  FileNotFoundError on remote schemes that were silently passed through
  before (s3://, gs://, hf://, ftp://, az://, ...).
- Non-localhost file authorities (e.g. file://nas-server/share/clip.mp4)
  are now skipped instead of being stripped and validated against the
  local filesystem; RFC 8089 only permits empty host or "localhost" for
  local files.
- Drop the explicit unquote call: urllib.request.url2pathname already
  unquotes, so the previous url2pathname(unquote(path)) double-decoded
  any filename with a literal percent (e.g. a file named "clip%20.mp4").
- Remove the Windows drive-letter strip block; nturl2path.url2pathname
  handles "/C:/foo" -> "C:\\foo" itself, leaving nothing for the guard to
  match on either OS.
- Return None when the resolved path is empty (bare "file://" or
  "file://hostname") so the caller skips it instead of reporting a
  blank "  - " entry in the error message.
- Add a runtime guard in check_dataset_for_missing_videos that warns and
  returns early when handed a datasets.IterableDataset, matching the
  docstring contract and preventing silent iterator exhaustion.

Windows native paths like "C:/path/x.mp4" stay valid because the
scheme check uses the "://" substring (not urlparse's single-letter
scheme surface).

* tests: consolidate video-path validation coverage into one file

New coverage for tests/test_video_path_validation.py:

- every-batch validation with cross-batch dedup (replaces the old
  first-batch-only assertion which no longer matches the implementation).
- all collator-supported input shapes: messages, conversations,
  prompt/completion, raw-message-list rows; non-dict message entries.
- file:// URI robustness: percent-encoded paths, localhost netloc,
  non-localhost netloc skipped, bare / hostname-only URIs skipped,
  double-encoded filenames single-unquote correctly.
- non-file remote schemes (s3, gs, hf, ftp, az) skipped without raising.
- Windows-style absolute path not mistaken for a URI scheme.
- formatting_func applied before validation inside the collator wrapper.
- IterableDataset runtime guard warns and returns without consuming.

The pre-existing test_collator_validates_only_once assertion has been
replaced by test_collator_validates_every_batch / dedupes_across_batches
because the wrapper now validates every batch.

The session-scoped AST fallback fixture was extended to extract the
helper functions that the rewritten check_dataset_for_missing_videos
depends on, so the Windows/no-triton code path still loads the module
surface.

* Fix CI iter 1

* Omit release-desktop.yml from the PR diff

The workflow file landed on origin/main after the PR branched off; our
fork-scoped push token cannot touch .github/workflows/**. Drop it from
this branch so the PR diff stays within the author's authorisable
surface. The file remains on origin/main and will return after this PR
merges upstream.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(vision): cache only validated paths in checked set

Missing paths were added to the dedup cache before the existence check,
so a caller that caught FileNotFoundError and retried with the same
collator/checked set would silently skip the bad path on the second call.

Only add a path to checked after os.path.isfile confirms it exists, so
missing paths are re-validated on every call until they are fixed.

* fix(ci): resolve two CI failures introduced by this PR

- Add __all__ to models/__init__.py so the HOISTED-IMPORT-UNUSED linter
  check passes for check_dataset_for_missing_videos
- Replace Dataset.from_list() in test helpers with plain list literals;
  the CI environment mocks datasets with a MockDataset that only has
  from_dict, but check_dataset_for_missing_videos accepts any iterable
  so no Dataset wrapper is needed
- Guard test_iterable_dataset_warns_and_skips with pytest.importorskip
  so it skips cleanly when the real datasets package is unavailable

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(ci): correct HOISTED-IMPORT-UNUSED without breaking wildcard exports

Adding __all__ to models/__init__.py was too aggressive - it restricted
from .models import * in _gpu_init.py to only check_dataset_for_missing_videos,
hiding FastLanguageModel, FastVisionModel etc and breaking
test_fast_model_class_surface_under_spoof.

Instead: remove __all__, and add an explicit named import in _gpu_init.py
so the linter sees the symbol consumed in the re-export chain.

* Deduplicate missing video paths and skip data URIs in validator

check_dataset_for_missing_videos appended a path to the missing list on every
occurrence, so a path referenced by multiple rows was reported N times and the
error header read the wrong count. Track missing paths in a per-call set so each
is listed once, kept separate from the checked cache so retries still re-check
missing files. This restores the dedup behaviour the docstring promises and the
existing test_duplicate_paths_deduplicated test asserts.

Also skip data: URIs in _local_path_from_video_value so inline base64 payloads
are not flagged as missing files.

Add tests for the data URI case, warn-only dedup, and real integration against
the unsloth_zoo UnslothVisionDataCollator base (verifying validation gates the
base call, formatting_func is applied once and restored even when the base
raises).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(trainer): declare __slots__ on UnslothVisionDataCollator subclass

* fix(ci): hoist check_dataset_for_missing_videos to trainer module level; guard IterableDataset skip

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix(vision): accept tuple message content in video path validator

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Tighten comments and docstrings for PR #5136

Comment-only pass over the new video path validation code: shorten the
collator and validator docstrings, collapse multi-line inline comments,
and reduce test docstrings to one-liners. No code changes; verified with
comment_tools.py check --strip-docstrings (3/3 code unchanged) and the
full test suite (35 passed).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 tests/test_video_path_validation.py | 570 ++++++++++++++++++++++++++++
 unsloth/models/vision.py            | 122 ++++++
 unsloth/trainer.py                  |  41 +-
 3 files changed, 732 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_video_path_validation.py

diff --git a/tests/test_video_path_validation.py b/tests/test_video_path_validation.py
new file mode 100644
index 0000000000..d1406230e3
--- /dev/null
+++ b/tests/test_video_path_validation.py
@@ -0,0 +1,570 @@
+"""
+Tests for check_dataset_for_missing_videos (issue #5085).
+
+Fixtures extract the function from vision.py via AST so the pure-Python logic
+tests run without the full unsloth import chain (triton/CUDA kernels).
+"""
+
+import ast
+import os
+import tempfile
+import warnings
+from pathlib import Path
+
+import pytest
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+
+def _extract_fns_via_ast(
+    source_path,
+    fn_names,
+    extra_ns = None,
+):
+    """Exec a set of top-level functions out of a .py file so intra-module
+    references between them resolve."""
+    source = source_path.read_text(encoding = "utf-8")
+    tree = ast.parse(source, filename = str(source_path))
+    wanted = set(fn_names)
+    nodes = [n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name in wanted]
+    missing = wanted - {n.name for n in nodes}
+    if missing:
+        pytest.fail(f"{sorted(missing)} not found in {source_path}")
+    mini = ast.Module(body = nodes, type_ignores = [])
+    ast.fix_missing_locations(mini)
+    ns = {"os": os, "warnings": warnings, "__name__": "_extracted"}
+    if extra_ns:
+        ns.update(extra_ns)
+    exec(compile(mini, str(source_path), "exec"), ns)
+    return {name: ns[name] for name in fn_names}
+
+
+def _extract_fn_via_ast(
+    source_path,
+    fn_name,
+    extra_ns = None,
+):
+    return _extract_fns_via_ast(source_path, [fn_name], extra_ns)[fn_name]
+
+
+@pytest.fixture(scope = "session")
+def check_dataset_for_missing_videos():
+    """Direct import when possible, else AST extraction from vision.py."""
+    try:
+        from unsloth.models.vision import check_dataset_for_missing_videos as fn
+        return fn
+    except Exception:
+        pass
+
+    vision_path = Path(__file__).parent.parent / "unsloth" / "models" / "vision.py"
+    fns = _extract_fns_via_ast(
+        vision_path,
+        [
+            "_looks_like_message_list",
+            "_iter_message_lists",
+            "_local_path_from_video_value",
+            "check_dataset_for_missing_videos",
+        ],
+    )
+    return fns["check_dataset_for_missing_videos"]
+
+
+@pytest.fixture(scope = "session")
+def make_auto_validating_collator(check_dataset_for_missing_videos):
+    """Factory for a minimal collator mirroring the trainer.py wrapper."""
+
+    class _FakeBase:
+        def __init__(self, formatting_func = None):
+            self.formatting_func = formatting_func
+
+        def __call__(self, examples):
+            if self.formatting_func is not None:
+                examples = [self.formatting_func(e) for e in examples]
+            return {"ok": True, "examples": examples}
+
+    class _AutoValidatingCollator(_FakeBase):
+        def __init__(self, formatting_func = None):
+            super().__init__(formatting_func = formatting_func)
+            self._checked_video_paths = set()
+
+        def __call__(self, examples):
+            formatting_func = self.formatting_func
+            if formatting_func is not None:
+                examples = [formatting_func(e) for e in examples]
+            check_dataset_for_missing_videos(
+                examples,
+                raise_error = True,
+                checked = self._checked_video_paths,
+            )
+            if formatting_func is None:
+                return super().__call__(examples)
+            self.formatting_func = None
+            try:
+                return super().__call__(examples)
+            finally:
+                self.formatting_func = formatting_func
+
+    return _AutoValidatingCollator
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _make_video_dataset(*video_paths):
+    return [
+        {"messages": [{"role": "user", "content": [{"type": "video", "video": p}]}]}
+        for p in video_paths
+    ]
+
+
+def _batch(*video_paths):
+    return _make_video_dataset(*video_paths)
+
+
+# ── Tests: check_dataset_for_missing_videos ───────────────────────────────────
+
+
+def test_missing_local_file_raises(check_dataset_for_missing_videos):
+    """Missing local path raises FileNotFoundError."""
+    ds = _make_video_dataset("/nonexistent/videos/clip.mp4")
+    with pytest.raises(FileNotFoundError):
+        check_dataset_for_missing_videos(ds)
+
+
+def test_remote_url_skipped(check_dataset_for_missing_videos):
+    """http/https URLs are not checked locally."""
+    ds = _make_video_dataset("https://example.com/video.mp4")
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_existing_file_accepted(check_dataset_for_missing_videos):
+    """Existing local file passes without error."""
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"fake video bytes")
+        tmp = f.name
+    try:
+        ds = _make_video_dataset(tmp)
+        assert check_dataset_for_missing_videos(ds) == []
+    finally:
+        os.unlink(tmp)
+
+
+def test_file_uri_scheme_stripped(check_dataset_for_missing_videos):
+    """file:// scheme is stripped before the path check."""
+    ds = _make_video_dataset("file:///nonexistent/clip.mp4")
+    with pytest.raises(FileNotFoundError):
+        check_dataset_for_missing_videos(ds)
+
+
+def test_warn_only_mode(check_dataset_for_missing_videos):
+    """raise_error=False warns and returns the missing paths."""
+    ds = _make_video_dataset("/nonexistent/videos/clip.mp4")
+    with warnings.catch_warnings(record = True) as caught:
+        warnings.simplefilter("always")
+        missing = check_dataset_for_missing_videos(ds, raise_error = False)
+
+    assert len(caught) == 1
+    assert "could not be found" in str(caught[0].message)
+    assert missing == ["/nonexistent/videos/clip.mp4"]
+
+
+def test_duplicate_paths_deduplicated(check_dataset_for_missing_videos):
+    """Repeated missing path is listed once."""
+    ds = _make_video_dataset("/nonexistent/clip.mp4", "/nonexistent/clip.mp4")
+    with pytest.raises(FileNotFoundError) as exc_info:
+        check_dataset_for_missing_videos(ds)
+    assert str(exc_info.value).count("/nonexistent/clip.mp4") == 1
+
+
+# ── Tests: UnslothVisionDataCollator auto-validation ─────────────────────────
+
+
+def test_collator_raises_on_first_batch_with_missing_video(make_auto_validating_collator):
+    """Collator raises on a missing path with no user action needed."""
+    collator = make_auto_validating_collator()
+    batch = _batch("/nonexistent/auto/clip.mp4")
+    with pytest.raises(FileNotFoundError):
+        collator(batch)
+
+
+def test_collator_passes_on_first_batch_with_valid_video(make_auto_validating_collator):
+    """Collator passes a valid batch through."""
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"fake video bytes")
+        tmp = f.name
+    try:
+        collator = make_auto_validating_collator()
+        batch = _batch(tmp)
+        result = collator(batch)
+        assert result["ok"] is True
+    finally:
+        os.unlink(tmp)
+
+
+def test_collator_validates_every_batch(make_auto_validating_collator):
+    """A missing video first appearing after batch 0 must still raise."""
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"fake video bytes")
+        tmp = f.name
+    try:
+        collator = make_auto_validating_collator()
+        collator(_batch(tmp))  # batch 0: valid
+        with pytest.raises(FileNotFoundError):
+            collator(_batch("/nonexistent/late.mp4"))
+    finally:
+        os.unlink(tmp)
+
+
+def test_collator_dedupes_across_batches(make_auto_validating_collator):
+    """The checked-path set is shared across batches."""
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"fake video bytes")
+        tmp = f.name
+    try:
+        collator = make_auto_validating_collator()
+        collator(_batch(tmp))
+        collator(_batch(tmp, tmp))
+        assert tmp in collator._checked_video_paths
+    finally:
+        os.unlink(tmp)
+
+
+def test_conversations_column_missing_detected(check_dataset_for_missing_videos):
+    """'conversations' column is scanned."""
+    ds = [
+        {
+            "conversations": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": "/nonexistent/conv.mp4"}],
+                }
+            ]
+        },
+    ]
+    with pytest.raises(FileNotFoundError):
+        check_dataset_for_missing_videos(ds)
+
+
+def test_prompt_completion_column_missing_detected(check_dataset_for_missing_videos):
+    """'prompt'/'completion' columns are scanned."""
+    ds = [
+        {
+            "prompt": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": "/nonexistent/p.mp4"}],
+                }
+            ],
+            "completion": [{"role": "assistant", "content": [{"type": "text", "text": "hi"}]}],
+        },
+    ]
+    with pytest.raises(FileNotFoundError) as exc_info:
+        check_dataset_for_missing_videos(ds)
+    assert "/nonexistent/p.mp4" in str(exc_info.value)
+
+
+def test_raw_message_list_example_missing_detected(check_dataset_for_missing_videos):
+    """Rows that are themselves message lists (no outer dict) are scanned."""
+    ds = [
+        [
+            {
+                "role": "user",
+                "content": [{"type": "video", "video": "/nonexistent/raw.mp4"}],
+            }
+        ],
+    ]
+    with pytest.raises(FileNotFoundError):
+        check_dataset_for_missing_videos(ds)
+
+
+def test_non_dict_message_entry_does_not_crash(check_dataset_for_missing_videos):
+    """Non-dict message entries are skipped."""
+    ds = [{"messages": ["not a dict", {"role": "user", "content": []}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_file_uri_percent_encoded(check_dataset_for_missing_videos, tmp_path):
+    """Percent-encoded file:// URIs decode to the real path."""
+    target = tmp_path / "my video.mp4"
+    target.write_bytes(b"x")
+    uri = "file://" + str(target).replace(" ", "%20")
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": uri}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_file_uri_localhost_host(check_dataset_for_missing_videos, tmp_path):
+    """file://localhost/<abs path> is the local machine (RFC 8089)."""
+    target = tmp_path / "clip.mp4"
+    target.write_bytes(b"x")
+    uri = f"file://localhost{target}"
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": uri}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_checked_set_reused_across_calls(check_dataset_for_missing_videos, tmp_path):
+    """A supplied checked set is populated and deduped across calls."""
+    target = tmp_path / "clip.mp4"
+    target.write_bytes(b"x")
+    shared = set()
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": str(target)}]}]}]
+    check_dataset_for_missing_videos(ds, checked = shared)
+    assert str(target) in shared
+    check_dataset_for_missing_videos(ds, checked = shared)
+    assert len(shared) == 1
+
+
+@pytest.mark.parametrize(
+    "uri",
+    [
+        "s3://bucket/clip.mp4",
+        "gs://bucket/clip.mp4",
+        "hf://datasets/u/r/clip.mp4",
+        "ftp://host/clip.mp4",
+        "az://container/clip.mp4",
+    ],
+)
+def test_non_file_remote_scheme_skipped(check_dataset_for_missing_videos, uri):
+    """Non-file URI schemes are treated as remote and skipped."""
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": uri}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_file_uri_non_localhost_host_skipped(check_dataset_for_missing_videos):
+    """file://<non-localhost>/path is remote (RFC 8089): skip local checks."""
+    ds = [
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": "file://nas-server/share/clip.mp4"}],
+                }
+            ]
+        }
+    ]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+@pytest.mark.parametrize("uri", ["file://", "file://hostname"])
+def test_degenerate_file_uri_skipped(check_dataset_for_missing_videos, uri):
+    """No path component must not produce a blank missing entry."""
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": uri}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_file_uri_double_encoded_percent(check_dataset_for_missing_videos, tmp_path):
+    """%2520 must single-unquote to 'clip%20.mp4', not 'clip .mp4'."""
+    target = tmp_path / "clip%20.mp4"
+    target.write_bytes(b"x")
+    uri = "file://" + str(target).replace("%", "%25")
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": uri}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_windows_style_absolute_path_not_mistaken_for_scheme(
+    check_dataset_for_missing_videos, tmp_path
+):
+    """'C:/...' has no '://' so it is a plain path, even where urlparse
+    would yield scheme='c'."""
+    target = tmp_path / "clip.mp4"
+    target.write_bytes(b"x")
+    path = str(target)
+    if os.name != "nt":
+        # '://'-free values must round-trip unchanged; keep the real path
+        path = str(target)
+    ds = [{"messages": [{"role": "user", "content": [{"type": "video", "video": path}]}]}]
+    assert check_dataset_for_missing_videos(ds) == []
+    ds_missing = [
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": "C:/definitely/missing.mp4"}],
+                }
+            ]
+        }
+    ]
+    with pytest.raises(FileNotFoundError) as exc:
+        check_dataset_for_missing_videos(ds_missing)
+    assert "C:/definitely/missing.mp4" in str(exc.value)
+
+
+def test_iterable_dataset_warns_and_skips(check_dataset_for_missing_videos):
+    """Streaming IterableDataset: warn, return [], do not exhaust it."""
+    datasets_mod = pytest.importorskip("datasets", reason = "real datasets package required")
+    if not hasattr(datasets_mod, "IterableDataset"):
+        pytest.skip("datasets.IterableDataset not available in this environment")
+    IterableDataset = datasets_mod.IterableDataset
+
+    def gen():
+        for p in ("/nonexistent/a.mp4", "/nonexistent/b.mp4"):
+            yield {"messages": [{"role": "user", "content": [{"type": "video", "video": p}]}]}
+
+    ds = IterableDataset.from_generator(gen)
+    with warnings.catch_warnings(record = True) as caught:
+        warnings.simplefilter("always")
+        result = check_dataset_for_missing_videos(ds)
+    assert result == []
+    assert any("IterableDataset" in str(w.message) for w in caught)
+    # generator must not have been exhausted
+    consumed = list(ds)
+    assert len(consumed) == 2
+
+
+def test_collator_applies_formatting_func_before_validation(make_auto_validating_collator):
+    """formatting_func runs before validation; super gets formatted examples
+    and must not re-apply it."""
+
+    def fmt(example):
+        return {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": example["video_id"]}],
+                }
+            ]
+        }
+
+    raise_collator = make_auto_validating_collator(formatting_func = fmt)
+    with pytest.raises(FileNotFoundError):
+        raise_collator([{"video_id": "/nonexistent/formatted.mp4"}])
+
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"x")
+        tmp = f.name
+    try:
+        ok_collator = make_auto_validating_collator(formatting_func = fmt)
+        before = ok_collator.formatting_func
+        result = ok_collator([{"video_id": tmp}])
+        assert result["ok"] is True
+        assert ok_collator.formatting_func is before
+        passed = result["examples"]
+        assert passed[0]["messages"][0]["content"][0]["video"] == tmp
+    finally:
+        os.unlink(tmp)
+
+
+def test_data_uri_skipped(check_dataset_for_missing_videos):
+    """Inline data: URIs are not flagged missing."""
+    ds = _make_video_dataset("data:video/mp4;base64,AAAABBBBCCCC")
+    assert check_dataset_for_missing_videos(ds) == []
+
+
+def test_tuple_content_entries_checked(check_dataset_for_missing_videos):
+    """Tuple message content is validated like a list."""
+    ds = [
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": ({"type": "video", "video": "/nonexistent/tuple.mp4"},),
+                }
+            ]
+        }
+    ]
+    with pytest.raises(FileNotFoundError):
+        check_dataset_for_missing_videos(ds)
+
+
+def test_duplicate_missing_deduped_in_warn_mode(check_dataset_for_missing_videos):
+    """Warn mode returns each missing path once."""
+    ds = _make_video_dataset("/nonexistent/dup.mp4", "/nonexistent/dup.mp4")
+    with warnings.catch_warnings(record = True):
+        warnings.simplefilter("always")
+        missing = check_dataset_for_missing_videos(ds, raise_error = False)
+    assert missing == ["/nonexistent/dup.mp4"]
+
+
+# ── Tests: real unsloth_zoo collator integration ─────────────────────────────
+# Exercise the real trainer.py subclass against the real zoo base (the fakes
+# above don't cover super()/formatting_func); skip when unsloth can't import.
+
+
+@pytest.fixture(scope = "session")
+def real_collator_classes():
+    try:
+        from unsloth.trainer import UnslothVisionDataCollator
+        from unsloth_zoo.vision_utils import (
+            UnslothVisionDataCollator as ZooBase,
+        )
+    except Exception as exc:  # noqa: BLE001 - skip on any import failure
+        pytest.skip(f"full unsloth import unavailable: {exc!r}")
+    return UnslothVisionDataCollator, ZooBase
+
+
+def _make_real_collator(real_collator_classes, formatting_func = None):
+    """Build the real subclass without its heavy __init__ (needs a processor)."""
+    subclass, _ = real_collator_classes
+    collator = subclass.__new__(subclass)
+    collator.formatting_func = formatting_func
+    collator._checked_video_paths = set()
+    return collator
+
+
+def test_real_collator_blocks_super_on_missing_video(real_collator_classes, monkeypatch):
+    """Missing path raises before the base __call__ runs."""
+    _, zoo_base = real_collator_classes
+    calls = []
+    monkeypatch.setattr(zoo_base, "__call__", lambda self, examples: calls.append(examples))
+    collator = _make_real_collator(real_collator_classes)
+    with pytest.raises(FileNotFoundError):
+        collator(_batch("/nonexistent/real.mp4"))
+    assert calls == []  # base collator was never reached
+
+
+def test_real_collator_calls_super_with_formatting_disabled(real_collator_classes, monkeypatch):
+    """Base must see formatting_func=None and already-formatted examples;
+    the original formatting_func is restored afterwards."""
+    seen = {}
+
+    def spy(self, examples):
+        seen["formatting_func"] = self.formatting_func
+        seen["examples"] = examples
+        return {"ok": True}
+
+    _, zoo_base = real_collator_classes
+    monkeypatch.setattr(zoo_base, "__call__", spy)
+
+    def fmt(example):
+        return {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [{"type": "video", "video": example["video_id"]}],
+                }
+            ]
+        }
+
+    with tempfile.NamedTemporaryFile(suffix = ".mp4", delete = False) as f:
+        f.write(b"x")
+        tmp = f.name
+    try:
+        collator = _make_real_collator(real_collator_classes, formatting_func = fmt)
+        result = collator([{"video_id": tmp}])
+        assert result == {"ok": True}
+        assert seen["formatting_func"] is None
+        assert seen["examples"][0]["messages"][0]["content"][0]["video"] == tmp
+        assert collator.formatting_func is fmt
+        assert tmp in collator._checked_video_paths
+    finally:
+        os.unlink(tmp)
+
+
+def test_real_collator_restores_formatting_func_when_super_raises(
+    real_collator_classes, monkeypatch
+):
+    """formatting_func is restored even when the base raises."""
+
+    def boom(self, examples):
+        raise RuntimeError("base collator failed")
+
+    _, zoo_base = real_collator_classes
+    monkeypatch.setattr(zoo_base, "__call__", boom)
+
+    def fmt(example):
+        return {"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]}
+
+    collator = _make_real_collator(real_collator_classes, formatting_func = fmt)
+    with pytest.raises(RuntimeError):
+        collator([{"anything": 1}])
+    assert collator.formatting_func is fmt
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index daa4a4835c..a75d23e710 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -1770,3 +1770,125 @@ class FastBaseModel:
         if torch_compiler_set_stance is not None:
             torch_compiler_set_stance(stance = "default", skip_guard_eval_unsafe = False)
         return model
+
+
+def _looks_like_message_list(value):
+    return isinstance(value, list) and (len(value) == 0 or isinstance(value[0], dict))
+
+
+def _iter_message_lists(example, column):
+    if _looks_like_message_list(example):
+        yield example
+        return
+    if not isinstance(example, dict):
+        return
+    seen_keys = set()
+    for key in (column, "messages", "conversations", "prompt", "completion"):
+        if key in seen_keys:
+            continue
+        seen_keys.add(key)
+        value = example.get(key)
+        if _looks_like_message_list(value):
+            yield value
+
+
+def _local_path_from_video_value(video_path):
+    # data: URIs are inline payloads, not files, and contain no "://"
+    if video_path.startswith("data:"):
+        return None
+    if "://" not in video_path:
+        return video_path
+    if not video_path.startswith("file://"):
+        return None
+    from urllib.parse import urlparse
+    from urllib.request import url2pathname
+
+    parsed = urlparse(video_path)
+    # RFC 8089: only an empty authority or "localhost" is the local machine
+    if parsed.netloc and parsed.netloc != "localhost":
+        return None
+    path = url2pathname(parsed.path)
+    return path or None
+
+
+def check_dataset_for_missing_videos(
+    dataset,
+    column = "messages",
+    raise_error = True,
+    checked = None,
+):
+    """
+    Validate that local video paths referenced in a dataset exist, catching
+    missing files before training (torchvision otherwise returns an empty
+    tensor and the model silently receives no video signal).
+
+    Args:
+        dataset:     Map-style Dataset, list of dicts, or iterable of examples
+                     (not a streaming IterableDataset - iterating consumes it).
+        column:      Chat-messages column, default "messages"; "conversations",
+                     "prompt" and "completion" are also scanned.
+        raise_error: True (default) raises FileNotFoundError listing missing
+                     files; False warns and returns them.
+        checked:     Optional set of known-good paths for cross-call dedup.
+
+    Returns:
+        List[str]: Missing file paths (empty when all exist).
+    """
+    try:
+        from datasets import IterableDataset as _IterableDataset
+        if isinstance(dataset, _IterableDataset):
+            warnings.warn(
+                "Unsloth: check_dataset_for_missing_videos received a streaming "
+                "IterableDataset; iterating would exhaust it and training would "
+                "see zero samples. Skipping validation - pass a map-style Dataset "
+                "or rely on the UnslothVisionDataCollator's per-batch check.",
+                stacklevel = 2,
+            )
+            return []
+    except ImportError:
+        pass
+
+    missing = []
+    # Report each missing path once; only confirmed-existing paths enter
+    # `checked`, so retries after an error re-check previously missing files.
+    seen_missing = set()
+    if checked is None:
+        checked = set()
+
+    for example in dataset:
+        for messages in _iter_message_lists(example, column):
+            for msg in messages:
+                if not isinstance(msg, dict):
+                    continue
+                content = msg.get("content", [])
+                if not isinstance(content, (list, tuple)):
+                    continue
+                for item in content:
+                    if not isinstance(item, dict) or item.get("type") != "video":
+                        continue
+                    video_path = item.get("video", "")
+                    if not isinstance(video_path, str) or not video_path:
+                        continue
+                    path = _local_path_from_video_value(video_path)
+                    if path is None or path in checked or path in seen_missing:
+                        continue
+                    if not os.path.isfile(path):
+                        seen_missing.add(path)
+                        missing.append(path)
+                    else:
+                        checked.add(path)
+
+    if missing:
+        missing_list = "\n".join(f"  - {p}" for p in missing)
+        error_msg = (
+            f"Unsloth: {len(missing)} video file(s) referenced in your dataset could not be found.\n"
+            "Training would silently continue with empty video tensors - the model would receive\n"
+            "no actual video signal while loss still appears to decrease.\n\n"
+            f"Missing files:\n{missing_list}\n\n"
+            "Fix: verify the video file paths in your dataset before calling the trainer."
+        )
+        if raise_error:
+            raise FileNotFoundError(error_msg)
+        warnings.warn(error_msg, stacklevel = 2)
+
+    return missing
diff --git a/unsloth/trainer.py b/unsloth/trainer.py
index 9b80b10705..8790099fe3 100644
--- a/unsloth/trainer.py
+++ b/unsloth/trainer.py
@@ -36,8 +36,9 @@ from unsloth_zoo.training_utils import (
     unsloth_train as _unsloth_train,
 )
 from unsloth_zoo.vision_utils import (
-    UnslothVisionDataCollator,
+    UnslothVisionDataCollator as _UnslothVisionDataCollatorBase,
 )
+from unsloth.models.vision import check_dataset_for_missing_videos
 from unsloth_zoo.hf_utils import get_transformers_model_type
 from unsloth_zoo.utils import Version
 import dataclasses
@@ -49,10 +50,48 @@ __all__ = [
     "_patch_trl_trainer",
     "UnslothVisionDataCollator",
     "QGaloreConfig",
+    "check_dataset_for_missing_videos",
 ]
 
 logger = logging.getLogger(__name__)
 
+
+class UnslothVisionDataCollator(_UnslothVisionDataCollatorBase):
+    """
+    Drop-in zoo collator that validates local video paths on every batch
+    (deduped across batches), applying formatting_func first so formatter-made
+    paths are checked too. Raises FileNotFoundError on missing files instead
+    of silently training on empty video tensors (issue #5085).
+    """
+
+    __slots__ = ("_checked_video_paths",)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._checked_video_paths = set()
+
+    def __call__(self, examples):
+        formatting_func = self.formatting_func
+        if formatting_func is not None:
+            examples = [formatting_func(example) for example in examples]
+
+        check_dataset_for_missing_videos(
+            examples,
+            raise_error = True,
+            checked = self._checked_video_paths,
+        )
+
+        if formatting_func is None:
+            return super().__call__(examples)
+
+        # why: base __call__ would reapply formatting_func; applied above.
+        self.formatting_func = None
+        try:
+            return super().__call__(examples)
+        finally:
+            self.formatting_func = formatting_func
+
+
 _AUTO_PADDING_FREE_ENV_DISABLED = os.environ.get(
     "UNSLOTH_DISABLE_AUTO_PADDING_FREE", ""
 ).strip().lower() in {"1", "true", "yes", "on"}

From 656a0875936c84c81dacb602e60564bfe5020d97 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 05:45:00 -0700
Subject: [PATCH 141/222] Restore config use_cache in for_inference after
 gradient checkpointing prep (#6137)

* Restore config use_cache in for_inference after gradient checkpointing prep

unsloth_zoo's prepare_model_for_training now sets use_cache=False on the
model config and nested sub-configs when gradient checkpointing is on
(unsloth-zoo PR 715) and records the original values. Wire the
counterpart into both for_inference implementations so the original
values come back for inference, and re-disable in for_training when a
record exists so resumed training keeps the config consistent. Both
calls import lazily and tolerate older unsloth_zoo without the helpers,
so version skew in either direction is a no-op. The MLX shims in
__init__.py are deliberately untouched.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/models/llama.py  | 20 ++++++++++++++++++++
 unsloth/models/vision.py | 20 ++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 6018a4ccb4..d5883e4346 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -3467,6 +3467,14 @@ class FastLlamaModel:
             embeddings = model.get_output_embeddings()
             if hasattr(embeddings, "training"):
                 embeddings.training = False
+
+        # Restore use_cache values that prepare_model_for_training disabled
+        # for gradient checkpointing (older unsloth_zoo has no restore helper)
+        try:
+            from unsloth_zoo.training_utils import restore_use_cache
+            restore_use_cache(model)
+        except ImportError:
+            pass
         return model
 
     @staticmethod
@@ -3514,6 +3522,18 @@ class FastLlamaModel:
             embeddings = model.get_output_embeddings()
             if hasattr(embeddings, "training"):
                 embeddings.training = True
+
+        # Re-disable use_cache if prepare_model_for_training had disabled it
+        # and for_inference restored it (record only exists after a disable)
+        if (
+            use_gradient_checkpointing
+            and getattr(model, "_unsloth_use_cache_originals", None) is not None
+        ):
+            try:
+                from unsloth_zoo.training_utils import disable_use_cache
+                disable_use_cache(model)
+            except ImportError:
+                pass
         return model
 
 
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index a75d23e710..34336aa80f 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -1706,6 +1706,14 @@ class FastBaseModel:
             embeddings = model.get_output_embeddings()
             if hasattr(embeddings, "training"):
                 embeddings.training = False
+        # Restore use_cache values that prepare_model_for_training disabled
+        # for gradient checkpointing (older unsloth_zoo has no restore helper)
+        try:
+            from unsloth_zoo.training_utils import restore_use_cache
+            restore_use_cache(model)
+        except ImportError:
+            pass
+
         # Must disable returning hidden states in the case for GRPO
         os.environ["UNSLOTH_RETURN_HIDDEN_STATES"] = "0"
         # Must enable returning logits
@@ -1764,6 +1772,18 @@ class FastBaseModel:
             embeddings = model.get_output_embeddings()
             if hasattr(embeddings, "training"):
                 embeddings.training = True
+        # Re-disable use_cache if prepare_model_for_training had disabled it
+        # and for_inference restored it (record only exists after a disable)
+        if (
+            use_gradient_checkpointing
+            and getattr(model, "_unsloth_use_cache_originals", None) is not None
+        ):
+            try:
+                from unsloth_zoo.training_utils import disable_use_cache
+                disable_use_cache(model)
+            except ImportError:
+                pass
+
         # Can re-enable not returning logits
         os.environ["UNSLOTH_RETURN_LOGITS"] = "0"
         # Turn off skip guards and set stance to default

From 8af9fe63a38a05435085e28034a09356acb9c692 Mon Sep 17 00:00:00 2001
From: Bubu <hbubu7896@gmail.com>
Date: Wed, 10 Jun 2026 21:01:05 +0800
Subject: [PATCH 142/222] fix: persist Windows ROCm BNB version (#6048)

* fix: persist Windows ROCm BNB version

* style: apply kwarg spacing hook

* fix: avoid persisting caller ROCm overrides

* fix: redetect managed BNB ROCm defaults

* style: apply ROCm guard test formatting

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/backend/core/training/worker.py    |  13 +-
 studio/backend/main.py                    |  10 +-
 studio/install_python_stack.py            |  94 +++++++++-
 tests/studio/install/test_rocm_support.py | 211 ++++++++++++++++++++++
 4 files changed, 315 insertions(+), 13 deletions(-)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index f7fbaa0b69..b6ec057231 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -2026,9 +2026,13 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
 
             # BNB picks a rocm DLL from torch.version.hip, but AMD's Windows BNB
             # wheel may ship a DLL whose suffix doesn't match. Detect the actual
-            # DLL name and override; "72" is a safe fallback. Callers may
-            # pre-set the var to override.
-            if "BNB_ROCM_VERSION" not in os.environ:
+            # DLL name and override; "72" is a safe fallback. Values seeded by
+            # the installer are redetectable defaults, while caller overrides
+            # remain authoritative.
+            if (
+                "BNB_ROCM_VERSION" not in os.environ
+                or os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize"
+            ):
                 _bnb_rocm_ver = None
                 try:
                     import glob as _glob
@@ -2053,8 +2057,9 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                             _bnb_rocm_ver = max(_all_vers, key = lambda v: int(v))
                 except Exception:
                     pass
-                _bnb_rocm_ver = _bnb_rocm_ver or "72"
+                _bnb_rocm_ver = _bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"
                 os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver
+                os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
                 logger.info(
                     "Windows ROCm: set BNB_ROCM_VERSION=%s "
                     "(detected from installed BNB wheel; "
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 38605a5009..74a7dbc8c5 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -86,7 +86,12 @@ if sys.platform == "win32":
     # found") without this. Detect the shipped DLL and fall back to "72" (mirrors
     # worker.py). Gate on the rocm bnb DLL / HIP_PATH rather than torch.version.hip
     # to avoid importing torch on every Windows host.
-    if "BNB_ROCM_VERSION" not in os.environ:
+    # Values seeded by the installer's sitecustomize.py are redetectable
+    # defaults; explicit caller values remain authoritative.
+    if (
+        "BNB_ROCM_VERSION" not in os.environ
+        or os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize"
+    ):
         import glob as _glob
         import logging as _logging
 
@@ -118,8 +123,9 @@ if sys.platform == "win32":
             )
         # rocm bnb DLL present, or HIP_PATH/ROCM_PATH set (DLL unparsable -> "72")
         if _found_rocm_bnb or _hip_env:
-            _bnb_rocm_ver_final = _bnb_rocm_ver or "72"
+            _bnb_rocm_ver_final = _bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"
             os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver_final
+            os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
             _logging.getLogger(__name__).info(
                 "Windows ROCm: set BNB_ROCM_VERSION=%s (from installed BNB wheel)",
                 _bnb_rocm_ver_final,
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index e742d85eed..eaab3f5559 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -18,6 +18,7 @@ import re
 import shutil
 import subprocess
 import sys
+import sysconfig
 import tempfile
 import urllib.request
 from pathlib import Path
@@ -489,6 +490,73 @@ def _detect_bnb_rocm_dll_ver() -> str | None:
     return max(all_vers, key = lambda v: int(v)) if all_vers else None
 
 
+_BNB_ROCM_SITECUSTOMIZE_BEGIN = "# BEGIN Unsloth BNB_ROCM_VERSION"
+_BNB_ROCM_SITECUSTOMIZE_END = "# END Unsloth BNB_ROCM_VERSION"
+_BNB_ROCM_VERSION_SOURCE_ENV = "UNSLOTH_BNB_ROCM_VERSION_SOURCE"
+_BNB_ROCM_VERSION_SOURCE_SITECUSTOMIZE = "sitecustomize"
+_BNB_ROCM_VERSION_SOURCE_DETECTED = "detected"
+
+
+def _persist_bnb_rocm_version(version: str) -> bool:
+    """Persist BNB_ROCM_VERSION for future Python processes in this venv."""
+    version = str(version).strip()
+    if not version:
+        return False
+
+    site_packages = sysconfig.get_path("purelib")
+    if not site_packages:
+        return False
+
+    sitecustomize_path = Path(site_packages) / "sitecustomize.py"
+    block = (
+        f"{_BNB_ROCM_SITECUSTOMIZE_BEGIN}\n"
+        "import os as _unsloth_os\n"
+        "_unsloth_existing_bnb_rocm = _unsloth_os.environ.get('BNB_ROCM_VERSION')\n"
+        f"_unsloth_os.environ.setdefault('BNB_ROCM_VERSION', {version!r})\n"
+        "if _unsloth_existing_bnb_rocm is None and "
+        f"_unsloth_os.environ.get('BNB_ROCM_VERSION') == {version!r}:\n"
+        "    _unsloth_os.environ.setdefault("
+        f"{_BNB_ROCM_VERSION_SOURCE_ENV!r}, "
+        f"{_BNB_ROCM_VERSION_SOURCE_SITECUSTOMIZE!r})\n"
+        "del _unsloth_existing_bnb_rocm\n"
+        f"{_BNB_ROCM_SITECUSTOMIZE_END}\n"
+    )
+
+    try:
+        sitecustomize_path.parent.mkdir(parents = True, exist_ok = True)
+        existing = (
+            sitecustomize_path.read_text(encoding = "utf-8") if sitecustomize_path.exists() else ""
+        )
+        # Strip all managed regions, including one whose END marker was lost to
+        # an interrupted write, then append exactly one fresh block.
+        pattern = re.compile(
+            rf"{re.escape(_BNB_ROCM_SITECUSTOMIZE_BEGIN)}.*?"
+            rf"(?:{re.escape(_BNB_ROCM_SITECUSTOMIZE_END)}\n?|\Z)",
+            re.DOTALL,
+        )
+        remainder = pattern.sub("", existing)
+        separator = "" if not remainder or remainder.endswith("\n") else "\n"
+        updated = f"{remainder}{separator}{block}"
+        tmp_path = sitecustomize_path.with_name(
+            f"{sitecustomize_path.name}.unsloth-tmp{os.getpid()}"
+        )
+        try:
+            tmp_path.write_text(updated, encoding = "utf-8")
+            if sitecustomize_path.exists():
+                shutil.copymode(sitecustomize_path, tmp_path)
+            os.replace(tmp_path, sitecustomize_path)
+        finally:
+            tmp_path.unlink(missing_ok = True)
+    except (OSError, UnicodeDecodeError) as exc:
+        print(
+            f"   Warning: could not persist BNB_ROCM_VERSION={version} "
+            f"to {sitecustomize_path}: {exc}"
+        )
+        return False
+
+    return True
+
+
 def _has_rocm_gpu() -> bool:
     """Return True only if an actual AMD GPU is visible (not just ROCm tools installed)."""
     for cmd, check_fn in (
@@ -636,15 +704,27 @@ def _install_bnb_windows_rocm() -> bool:
     )
     if not _ok:
         return False
-    # After install: detect the actual ROCm DLL suffix in the wheel and set
-    # BNB_ROCM_VERSION so bitsandbytes loads the correct DLL regardless of what
-    # torch.version.hip reports. The wheel may ship an older suffix (e.g. "72")
-    # while torch reports a newer HIP version (e.g. 7.13); the override stops
-    # bitsandbytes from failing on a non-existent DLL. The worker subprocess
-    # inherits this env var. Fall back to "72" if detection fails (no-op/dry-run).
-    if "BNB_ROCM_VERSION" not in os.environ:
+    # After install: detect the actual ROCm DLL suffix shipped in the wheel and
+    # set BNB_ROCM_VERSION so bitsandbytes loads the correct DLL regardless of
+    # what torch.version.hip reports.  The wheel may ship an older suffix (e.g.
+    # "72") while torch reports a newer HIP version (e.g. 7.13); the env var
+    # override ensures bitsandbytes does not fail looking for a non-existent DLL.
+    # The worker subprocess inherits this env var automatically.
+    # Fall back to "72" if detection fails (e.g. install was a no-op / dry-run).
+    _env_ver = os.environ.get("BNB_ROCM_VERSION")
+    _env_is_persisted_default = (
+        os.environ.get(_BNB_ROCM_VERSION_SOURCE_ENV) == _BNB_ROCM_VERSION_SOURCE_SITECUSTOMIZE
+    )
+    _persist_detected_version = False
+    if _env_ver and not _env_is_persisted_default:
+        _ver = _env_ver
+    else:
         _ver = _detect_bnb_rocm_dll_ver() or "72"
         os.environ["BNB_ROCM_VERSION"] = _ver
+        os.environ[_BNB_ROCM_VERSION_SOURCE_ENV] = _BNB_ROCM_VERSION_SOURCE_DETECTED
+        _persist_detected_version = True
+    if _persist_detected_version:
+        _persist_bnb_rocm_version(_ver)
     # Make hipInfo.exe (shipped into the venv Scripts dir by the AMD torch
     # wheel) resolvable via PATH for this process and every child python the
     # installer spawns (import checks, precompile): bitsandbytes runs
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index c761cd090f..02f52e7700 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -1709,6 +1709,17 @@ class TestGfxArchNameFallback:
 class TestInstallBnbWindowsRocm:
     """Verify AMD Windows BNB wheel install helper."""
 
+    @pytest.fixture(autouse = True)
+    def _isolate_sitecustomize_persistence(self, monkeypatch, request):
+        """Keep helper tests from writing to the active interpreter site-packages."""
+        if request.node.name.startswith("test_persist"):
+            return
+        monkeypatch.setattr(
+            stack_mod,
+            "_persist_bnb_rocm_version",
+            lambda version: True,
+        )
+
     def test_calls_pip_install_try_with_win_amd64_url(self):
         """Should call pip_install_try with the win_amd64 wheel URL via plain pip."""
         with patch.object(stack_mod, "pip_install_try", return_value = True) as mock_pip:
@@ -1762,6 +1773,7 @@ class TestInstallBnbWindowsRocm:
         """BNB_ROCM_VERSION is set from the DLL detected after install."""
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
                 with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "72"):
                     stack_mod._install_bnb_windows_rocm()
@@ -1771,6 +1783,7 @@ class TestInstallBnbWindowsRocm:
         """If AMD ships a newer DLL (e.g. rocm713.dll), that version is used."""
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
                 with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "713"):
                     stack_mod._install_bnb_windows_rocm()
@@ -1780,6 +1793,7 @@ class TestInstallBnbWindowsRocm:
         """Falls back to '72' when DLL detection returns None."""
         with patch.dict(os.environ, {}, clear = False):
             os.environ.pop("BNB_ROCM_VERSION", None)
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
                 with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = None):
                     stack_mod._install_bnb_windows_rocm()
@@ -1788,10 +1802,207 @@ class TestInstallBnbWindowsRocm:
     def test_does_not_override_existing_bnb_rocm_version(self):
         """An explicit BNB_ROCM_VERSION in the caller's env must not be clobbered."""
         with patch.dict(os.environ, {"BNB_ROCM_VERSION": "60"}):
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
             with patch.object(stack_mod, "pip_install_try", return_value = True):
                 stack_mod._install_bnb_windows_rocm()
             assert os.environ.get("BNB_ROCM_VERSION") == "60"
 
+    def test_does_not_persist_existing_bnb_rocm_version(self):
+        """A caller override must not become the venv's managed default."""
+        with patch.dict(os.environ, {"BNB_ROCM_VERSION": "60"}):
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver") as mock_detect:
+                    with patch.object(
+                        stack_mod, "_persist_bnb_rocm_version", return_value = True
+                    ) as mock_persist:
+                        stack_mod._install_bnb_windows_rocm()
+
+            assert os.environ.get("BNB_ROCM_VERSION") == "60"
+            mock_detect.assert_not_called()
+            mock_persist.assert_not_called()
+
+    def test_redetects_when_bnb_rocm_version_came_from_sitecustomize(self):
+        """Persisted defaults should not mask a newer DLL suffix after reinstall."""
+        with patch.dict(
+            os.environ,
+            {
+                "BNB_ROCM_VERSION": "72",
+                stack_mod._BNB_ROCM_VERSION_SOURCE_ENV: (
+                    stack_mod._BNB_ROCM_VERSION_SOURCE_SITECUSTOMIZE
+                ),
+            },
+        ):
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "713"):
+                    with patch.object(
+                        stack_mod, "_persist_bnb_rocm_version", return_value = True
+                    ) as mock_persist:
+                        stack_mod._install_bnb_windows_rocm()
+
+            assert os.environ.get("BNB_ROCM_VERSION") == "713"
+            assert (
+                os.environ.get(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV)
+                == stack_mod._BNB_ROCM_VERSION_SOURCE_DETECTED
+            )
+            mock_persist.assert_called_once_with("713")
+
+    def test_persists_bnb_rocm_version_for_direct_venv_python(self, tmp_path):
+        """BNB_ROCM_VERSION must apply to a fresh Python process in the venv."""
+        site_packages = tmp_path / "site-packages"
+
+        with patch.dict(os.environ, {}, clear = False):
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            os.environ.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
+            with patch.object(stack_mod, "pip_install_try", return_value = True):
+                with patch.object(stack_mod, "_detect_bnb_rocm_dll_ver", return_value = "72"):
+                    with patch.object(
+                        stack_mod.sysconfig, "get_path", return_value = str(site_packages)
+                    ):
+                        stack_mod._install_bnb_windows_rocm()
+
+        sitecustomize = site_packages / "sitecustomize.py"
+        source = sitecustomize.read_text(encoding = "utf-8")
+        assert "BNB_ROCM_VERSION" in source
+        assert stack_mod._BNB_ROCM_VERSION_SOURCE_ENV in source
+        assert "'72'" in source
+
+        probe_env = os.environ.copy()
+        probe_env.pop("BNB_ROCM_VERSION", None)
+        probe_env.pop(stack_mod._BNB_ROCM_VERSION_SOURCE_ENV, None)
+        probe_env["PYTHONPATH"] = str(site_packages)
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                (
+                    "import os; "
+                    "print(os.environ.get('BNB_ROCM_VERSION', ''), "
+                    "os.environ.get('UNSLOTH_BNB_ROCM_VERSION_SOURCE', ''))"
+                ),
+            ],
+            env = probe_env,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.PIPE,
+            text = True,
+            check = True,
+        )
+        assert result.stdout.strip() == "72 sitecustomize"
+
+    def test_persist_bnb_rocm_version_replaces_existing_managed_block(self, tmp_path):
+        """Updating sitecustomize.py must not duplicate the managed BNB block."""
+        site_packages = tmp_path / "site-packages"
+        site_packages.mkdir()
+        sitecustomize = site_packages / "sitecustomize.py"
+        sitecustomize.write_text(
+            "EXISTING = True\n"
+            "# BEGIN Unsloth BNB_ROCM_VERSION\n"
+            "import os as _unsloth_os\n"
+            "_unsloth_os.environ.setdefault('BNB_ROCM_VERSION', '72')\n"
+            "# END Unsloth BNB_ROCM_VERSION\n",
+            encoding = "utf-8",
+        )
+
+        with patch.object(stack_mod.sysconfig, "get_path", return_value = str(site_packages)):
+            assert stack_mod._persist_bnb_rocm_version("713") is True
+
+        source = sitecustomize.read_text(encoding = "utf-8")
+        assert source.count("# BEGIN Unsloth BNB_ROCM_VERSION") == 1
+        assert "EXISTING = True" in source
+        assert "'713'" in source
+        assert "'72'" not in source
+
+    def test_persist_bnb_rocm_version_handles_non_utf8_sitecustomize(self, tmp_path):
+        """A legacy non-UTF-8 sitecustomize.py should not abort installation."""
+        site_packages = tmp_path / "site-packages"
+        site_packages.mkdir()
+        sitecustomize = site_packages / "sitecustomize.py"
+        sitecustomize.write_bytes(b"\xff\xfe\x00")
+
+        with patch.object(stack_mod.sysconfig, "get_path", return_value = str(site_packages)):
+            assert stack_mod._persist_bnb_rocm_version("72") is False
+
+    def test_persist_bnb_rocm_version_repairs_truncated_block(self, tmp_path):
+        """A managed block missing its END marker is replaced, not duplicated."""
+        site_packages = tmp_path / "site-packages"
+        site_packages.mkdir()
+        sitecustomize = site_packages / "sitecustomize.py"
+        sitecustomize.write_text(
+            "EXISTING = True\n"
+            "# BEGIN Unsloth BNB_ROCM_VERSION\n"
+            "import os as _unsloth_os\n"
+            "_unsloth_os.environ.setdefault('BNB_ROCM_VERSION', '72')\n",
+            encoding = "utf-8",
+        )
+
+        with patch.object(stack_mod.sysconfig, "get_path", return_value = str(site_packages)):
+            assert stack_mod._persist_bnb_rocm_version("713") is True
+
+        source = sitecustomize.read_text(encoding = "utf-8")
+        assert source.count("# BEGIN Unsloth BNB_ROCM_VERSION") == 1
+        assert source.count("# END Unsloth BNB_ROCM_VERSION") == 1
+        assert "EXISTING = True" in source
+        assert "'713'" in source
+        assert "'72'" not in source
+
+    def test_persist_bnb_rocm_version_dedupes_duplicate_blocks(self, tmp_path):
+        """Multiple managed blocks collapse to one while preserving user content."""
+        site_packages = tmp_path / "site-packages"
+        site_packages.mkdir()
+        sitecustomize = site_packages / "sitecustomize.py"
+        block = (
+            "# BEGIN Unsloth BNB_ROCM_VERSION\n"
+            "import os as _unsloth_os\n"
+            "_unsloth_os.environ.setdefault('BNB_ROCM_VERSION', '72')\n"
+            "# END Unsloth BNB_ROCM_VERSION\n"
+        )
+        sitecustomize.write_text(block + "USER_MID = 1\n" + block, encoding = "utf-8")
+
+        with patch.object(stack_mod.sysconfig, "get_path", return_value = str(site_packages)):
+            assert stack_mod._persist_bnb_rocm_version("713") is True
+
+        source = sitecustomize.read_text(encoding = "utf-8")
+        assert source.count("# BEGIN Unsloth BNB_ROCM_VERSION") == 1
+        assert source.count("# END Unsloth BNB_ROCM_VERSION") == 1
+        assert "USER_MID = 1" in source
+        assert "'713'" in source
+        assert "'72'" not in source
+
+    def test_persist_bnb_rocm_version_atomic_no_leftover_tmp(self, tmp_path):
+        """The write-then-rename path must not leave its temp file behind."""
+        site_packages = tmp_path / "site-packages"
+        site_packages.mkdir()
+
+        with patch.object(stack_mod.sysconfig, "get_path", return_value = str(site_packages)):
+            assert stack_mod._persist_bnb_rocm_version("72") is True
+
+        leftovers = [p.name for p in site_packages.iterdir() if "unsloth-tmp" in p.name]
+        assert leftovers == []
+        assert (site_packages / "sitecustomize.py").exists()
+
+
+class TestRuntimeBnbRocmSourceGuards:
+    """Runtime entrypoints redetect managed defaults but keep caller overrides."""
+
+    _MAIN_PATH = PACKAGE_ROOT / "studio" / "backend" / "main.py"
+    _TRAINING_WORKER_PATH = PACKAGE_ROOT / "studio" / "backend" / "core" / "training" / "worker.py"
+
+    def test_main_gate_redetects_persisted_default(self):
+        source = self._MAIN_PATH.read_text(encoding = "utf-8")
+        assert 'os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize"' in source
+        assert 'os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"' in source
+
+    def test_worker_gate_redetects_persisted_default(self):
+        source = self._TRAINING_WORKER_PATH.read_text(encoding = "utf-8")
+        assert 'os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize"' in source
+        assert 'os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"' in source
+
+    def test_fallback_prefers_seeded_value_over_hardcoded_72(self):
+        """A failed redetect must not downgrade a persisted suffix to '72'."""
+        for path in (self._MAIN_PATH, self._TRAINING_WORKER_PATH):
+            source = path.read_text(encoding = "utf-8")
+            assert 'os.environ.get("BNB_ROCM_VERSION") or "72"' in source, path.name
+
 
 class TestDetectBnbRocmDllVer:
     """Unit tests for _detect_bnb_rocm_dll_ver()."""

From 7cbf428b0add57303fd98136502991a05dae956e Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 06:10:03 -0700
Subject: [PATCH 143/222] Fix JSON-mode smoke on Linux: bump quant, keep the
 hard Paris assert (#6138)

At UD-IQ2_XXS the temp-0 greedy answer to the capital-of-France probe is
hardware dependent: GitHub ubuntu runners deterministically answer
city=France while other CPUs answer Paris, because the 2-bit argmax
flips with the SIMD kernel path. Seeds do not rescue it: a staging-fork
sweep on the affected runners measured 1/5 Paris at temp 0.7 and 1/5 at
temp 1.0 (different winning seeds on different hardware), so a
retry-across-seeds assert would still flake about a third of runs.

The same sweep on UD-Q4_K_XL answered Paris 13/13 across temp 0, 0.7
and 1.0 with 5 seeds each, including 3x deterministic greedy. Bump the
job's quant (roughly 570 MiB to 1.1 GiB, cache key already includes the
variant) and leave the assertion exactly as it was.
---
 .github/workflows/studio-inference-smoke.yml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.yml
index 3a4c76a2bb..133dd601d1 100644
--- a/.github/workflows/studio-inference-smoke.yml
+++ b/.github/workflows/studio-inference-smoke.yml
@@ -20,7 +20,7 @@
 #        enable_tools / enabled_tools, and enable_thinking on/off.
 #
 #   3. JSON, images
-#        Qwen3-VL-2B-Instruct UD-IQ2_XXS (~570 MiB) + mmproj-F16 (~780 MiB).
+#        Qwen3-VL-2B-Instruct UD-Q4_K_XL (~1.1 GiB) + mmproj-F16 (~780 MiB).
 #        response_format JSON-schema decoding and OpenAI image_url
 #        (data URI) plus Anthropic source/base64 image inputs.
 #
@@ -792,8 +792,14 @@ jobs:
     timeout-minutes: 30
     env:
       GGUF_REPO: unsloth/Qwen3-VL-2B-Instruct-GGUF
-      GGUF_VARIANT: UD-IQ2_XXS
-      GGUF_FILE: Qwen3-VL-2B-Instruct-UD-IQ2_XXS.gguf
+      # UD-Q4_K_XL, not UD-IQ2_XXS: at 2-bit the temp-0 answer to the JSON
+      # step's capital-of-France probe flips with the host's SIMD kernels
+      # (GitHub runners deterministically answered France while other CPUs
+      # answer Paris; seeds do not rescue it, 1/5 Paris at temp 0.7). The
+      # Q4 quant answered Paris 13/13 across temps and seeds on the same
+      # runners, so the hard Paris assertion below stays reliable.
+      GGUF_VARIANT: UD-Q4_K_XL
+      GGUF_FILE: Qwen3-VL-2B-Instruct-UD-Q4_K_XL.gguf
       MMPROJ_FILE: mmproj-F16.gguf
       STUDIO_PORT: '18890'
       HF_HOME: ${{ github.workspace }}/hf-cache

From f3001159f91beed9ca4c5d779b6ba3761e1742be Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 06:10:16 -0700
Subject: [PATCH 144/222] Frontend CI: hard-fail unreviewed npm install scripts
 (#6139)

Completes the allowScripts rollout: upgrade CI npm to the 11.x line
(node 22 bundles 10.x, which predates the gate) with a loud version
guard so the flag can never silently degrade into a warning, then run
npm ci --strict-allow-scripts. A dependency that introduces install
scripts not covered by the committed policy now fails the job with
npm's approve-scripts/deny-scripts instructions; the pre-commit sync
hook keeps existing pins fresh after bumps.
---
 .github/workflows/studio-frontend-ci.yml | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/studio-frontend-ci.yml b/.github/workflows/studio-frontend-ci.yml
index 3abfea8450..b42086f191 100644
--- a/.github/workflows/studio-frontend-ci.yml
+++ b/.github/workflows/studio-frontend-ci.yml
@@ -62,6 +62,19 @@ jobs:
         with:
           node-version: '22'
 
+      # node 22 bundles npm 10.x, which predates allowScripts. Move to the
+      # 11.x line and fail loudly if the gate is still missing, so the
+      # strict flag below can never silently degrade into a warning.
+      - name: Upgrade npm to 11.x (allowScripts enforcement)
+        working-directory: ${{ github.workspace }}
+        run: |
+          npm install -g npm@^11 --no-fund --no-audit
+          V=$(npm -v)
+          case "$V" in
+            11.1[6-9].*|11.[2-9][0-9].*|1[2-9].*) echo "npm $V has allowScripts" ;;
+            *) echo "::error::npm $V lacks allowScripts (need >=11.16)"; exit 1 ;;
+          esac
+
       # Run the structural lockfile scan BEFORE npm ci. A compromised
       # tarball runs its `prepare` / `postinstall` during `npm ci`,
       # so any catch has to fire upstream of that. The scanner is
@@ -84,7 +97,9 @@ jobs:
         # covered by `allowScripts` in package.json (npm >=11.16, default in
         # npm 12). The pre-install lockfile audit above stays the first line
         # of defence -- it fires before any tarball can run code.
-        run: npm ci --no-fund --no-audit
+        # --strict-allow-scripts: any unreviewed install script hard-fails
+        # the job; the sync hook keeps the pins fresh after bumps.
+        run: npm ci --strict-allow-scripts --no-fund --no-audit
 
       - name: npm ci must not have modified the working tree
         working-directory: ${{ github.workspace }}

From fa01a02a6df35de7969f1ce80925f44c6a1c3a3d Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 07:28:28 -0700
Subject: [PATCH 145/222] Studio UI polish: search dialog shadow, model picker
 pills, sidebar spacing, white Hub background (#6147)

* Studio UI polish: search dialog shadow, picker pills, sidebar spacing, white Hub

- Chat search dialog: keep a page-bg shadow in dark mode so the dialog
  does not merge into same-color content behind it
- Model selector: hover and selected rows are fully rounded pills
- Sidebar: nudge nav items, recents and section labels 2px right and
  widen the hover pill 2px left so its side gaps match
- Hub: pure white page background in light mode and drop the ambient
  card glow that tinted the page gray

* Lighten sidebar border, widen model picker rows

- Sidebar border is #f2f2f2 in light mode
- Model picker rows extend 4px further left and right, lining up with
  the search bar

* Plus menu: restore the intended 18px corner radius

The global 14px !important dropdown radius overrode the menu's own
18px, so the plus menu and its submenus rendered squarer than designed.
Mark the menu radius !important so it wins.

* Projects: borderless import/export button; picker search border #f2f2f2

- The import/export button on the Projects page drops its outline
  border and matches the Sort by pill next to it
- The model picker search inputs use a #f2f2f2 border in light mode,
  dark mode keeps the default

* Model selector: align the popup with the trigger label

The popover lined up with the trigger button edge, 14px left of the
label text. A 10px alignOffset starts it just before the label.

* Model picker: shorten search placeholder to Search models

* Pill-shaped model trigger and panel controls; chat template edit button

- Select model trigger: rounded pill with slightly tighter horizontal
  padding
- KV cache, speculative decoding, draft N and preset controls in the
  chat settings panel are rounded pills
- Chat Template: replace the three-line preview box with an edit icon
  button next to the label; it opens the existing editor dialog

* Training overlay: borderless console, sloth attached to the box

- Drop the terminal border for the training start console
- Remove the gap between the sloth image and the console so they touch

* Settings panel: more left padding in pill controls, smaller template edit icon

- f16, Auto and draft N pills get 12px left padding, widths bumped 4px
  to keep the values from truncating
- Chat template edit icon shrinks to 14px and the Chat Template label
  also opens the editor

* Model picker: more padding inside row pills, hugeicons delete icon

- Row pills get 12px horizontal padding so text is not pressed against
  the highlight boundary
- The cached model delete button uses the hugeicons Delete02 icon
  instead of the lucide trash icon

* Address review: hub bg layering, dead shadow utilities, merged paddings

- Remove bg-background from the Hub root: the white rule lives in the
  base layer and the utility was winning the cascade, so the white
  background never applied
- Drop the inline shadow utilities on the chat search dialog: the
  chat-search-surface rules sit later in the utilities layer and
  already win, making the inline ones dead
- Merge symmetric pl/pr pairs into px on the sidebar group wrappers
---
 .../frontend/src/components/app-sidebar.tsx   |  6 +--
 .../assistant-ui/model-selector.tsx           | 13 ++---
 .../model-selector/model-delete-action.tsx    |  9 +++-
 .../assistant-ui/model-selector/pickers.tsx   | 14 ++---
 .../src/features/chat/chat-settings-sheet.tsx | 54 ++++++++++++-------
 .../chat/components/chat-search-dialog.tsx    |  2 +-
 .../src/features/chat/projects-page.tsx       |  7 ++-
 studio/frontend/src/features/hub/hub-page.tsx |  2 +-
 studio/frontend/src/features/hub/hub.css      |  7 ++-
 .../studio/training-start-overlay.tsx         |  4 +-
 studio/frontend/src/index.css                 | 19 ++++---
 11 files changed, 84 insertions(+), 53 deletions(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 14131c3c1c..575fd20a06 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -217,7 +217,7 @@ function NavItem({
           onClick={onClick}
           isActive={active}
           data-tour={dataTour}
-          className="sidebar-nav-btn h-[33px] rounded-full gap-[8.5px] px-2.5 font-medium group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-full group-data-[collapsible=icon]:mx-auto"
+          className="sidebar-nav-btn h-[33px] rounded-full gap-[8.5px] pl-3 pr-2.5 font-medium group-data-[collapsible=icon]:px-2.5 group-data-[collapsible=icon]:!w-[32px] group-data-[collapsible=icon]:!rounded-full group-data-[collapsible=icon]:mx-auto"
         >
           <HugeiconsIcon icon={icon} strokeWidth={1.75} className="size-icon! shrink-0 group-hover/menu-button:animate-icon-pop" />
           <span className="text-[14.5px] leading-[19px] tracking-nav">{label}</span>
@@ -558,7 +558,7 @@ export function AppSidebar() {
         : "sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto";
     const buttonClass = cn(
       "sidebar-nav-btn h-[33px] cursor-pointer rounded-full pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
-      variant === "project" ? "pl-[37px]" : "pl-2.5",
+      variant === "project" ? "pl-[39px]" : "pl-3",
       variant === "project"
         ? "group-hover/project-chat-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/project-chat-item:pr-8"
         : "group-hover/recent-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/recent-item:pr-8",
@@ -966,7 +966,7 @@ export function AppSidebar() {
                       >
                         <SidebarMenuButton
                           isActive={isActiveRun}
-                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-full pl-2.5 pr-7 text-[14.5px] tracking-nav font-medium"
+                          className="sidebar-nav-btn h-auto flex-col items-start gap-0.5 py-[5px] rounded-full pl-3 pr-7 text-[14.5px] tracking-nav font-medium"
                           onClick={() => {
                             setSelectedHistoryRunId(run.id);
                             closeMobileIfOpen();
diff --git a/studio/frontend/src/components/assistant-ui/model-selector.tsx b/studio/frontend/src/components/assistant-ui/model-selector.tsx
index f8a3ce4e20..b8d1bc0f00 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector.tsx
@@ -148,12 +148,12 @@ function ModelSelectorTrigger({
         className={cn(
           "unsloth-model-selector-trigger flex min-w-0 items-center gap-2 transition-colors",
           variant === "outline" &&
-          "rounded-[10px] border border-border/60 hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
-          variant === "ghost" && "rounded-[10px] hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
-          variant === "muted" && "rounded-[10px] bg-muted hover:bg-muted/80",
-          size === "sm" && "h-8 px-3 text-xs",
-          size === "default" && "h-9 px-3.5 text-sm",
-          size === "lg" && "h-10 px-4 text-sm",
+          "rounded-full border border-border/60 hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
+          variant === "ghost" && "rounded-full hover:bg-[#ececec] dark:hover:bg-[#2d2e32]",
+          variant === "muted" && "rounded-full bg-muted hover:bg-muted/80",
+          size === "sm" && "h-8 px-2.5 text-xs",
+          size === "default" && "h-9 px-3 text-sm",
+          size === "lg" && "h-10 px-3.5 text-sm",
           className,
         )}
       >
@@ -244,6 +244,7 @@ function ModelSelectorContent({
   return (
     <PopoverContent
       align="start"
+      alignOffset={10}
       data-tour={dataTour}
       className={cn(
         "unsloth-model-selector-menu menu-soft-surface ring-0 w-[min(440px,calc(100vw-1rem))] max-w-[calc(100vw-1rem)] min-w-0 gap-0 p-3",
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/model-delete-action.tsx b/studio/frontend/src/components/assistant-ui/model-selector/model-delete-action.tsx
index 4a9b22e103..d6afa30e05 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/model-delete-action.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/model-delete-action.tsx
@@ -12,7 +12,8 @@ import {
   AlertDialogTitle,
 } from "@/components/ui/alert-dialog";
 import { cn } from "@/lib/utils";
-import { Trash2Icon } from "lucide-react";
+import { Delete02Icon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
 import { useCallback, useState, type ReactNode } from "react";
 import { toast } from "@/lib/toast";
 
@@ -77,7 +78,11 @@ export function ModelDeleteAction({
           buttonClassName,
         )}
       >
-        <Trash2Icon className={cn("size-3.5", iconClassName)} />
+        <HugeiconsIcon
+          icon={Delete02Icon}
+          strokeWidth={1.75}
+          className={cn("size-3.5", iconClassName)}
+        />
       </button>
 
       <AlertDialog
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
index 4fd86ad789..be66f23a20 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
+++ b/studio/frontend/src/components/assistant-ui/model-selector/pickers.tsx
@@ -146,7 +146,7 @@ function ModelRow({
       type="button"
       onClick={onClick}
       className={cn(
-        "flex w-full items-center gap-2 rounded-[8px] px-2.5 py-1.5 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
+        "flex w-full items-center gap-2 rounded-full px-3 py-1.5 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
         selected && "bg-[#ececec] dark:bg-[#3a3d44]",
       )}
     >
@@ -386,7 +386,7 @@ function GgufVariantExpander({
                 handleVariantClick(v.quant, v.downloaded, v.size_bytes)
               }
               className={cn(
-                "flex min-w-0 flex-1 items-center justify-between gap-2 rounded-[8px] px-2.5 py-1 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
+                "flex min-w-0 flex-1 items-center justify-between gap-2 rounded-full px-3 py-1 text-left text-sm transition-colors hover:bg-[#ececec] dark:hover:bg-[#3a3d44]",
               )}
             >
               <span className="min-w-0 flex-1 truncate font-mono text-xs">
@@ -887,8 +887,8 @@ export function HubModelPicker({
         <Input
           value={query}
           onChange={(event) => setQuery(event.target.value)}
-          placeholder="Search Hugging Face models"
-          className="h-9 pl-8 pr-8"
+          placeholder="Search models"
+          className="h-9 border-[#f2f2f2] dark:border-input pl-8 pr-8"
         />
         {isLoading && (
           <Spinner className="pointer-events-none absolute right-2.5 top-2.5 size-4 text-muted-foreground" />
@@ -896,7 +896,7 @@ export function HubModelPicker({
       </div>
 
       <div ref={scrollRef} className="max-h-64 overflow-y-auto">
-        <div className="p-1">
+        <div className="py-1">
           {!cachedReady && !showHfSection ? (
             <div className="flex items-center gap-2 px-5 py-3">
               <Spinner className="size-3 text-muted-foreground" />
@@ -1478,12 +1478,12 @@ export function LoraModelPicker({
           value={query}
           onChange={(event) => setQuery(event.target.value)}
           placeholder="Search trained models"
-          className="h-9 pl-8"
+          className="h-9 border-[#f2f2f2] dark:border-input pl-8"
         />
       </div>
 
       <div className="max-h-64 overflow-y-auto">
-        <div className="p-1">
+        <div className="py-1">
           {grouped.length === 0 ? (
             <div className="px-2.5 py-2 text-xs text-muted-foreground">
               No trained models found.
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 776bad5244..96415c4da0 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -54,6 +54,7 @@ import { cn } from "@/lib/utils";
 import {
   ArrowDown01Icon,
   ArrowTurnBackwardIcon,
+  Edit03Icon,
   InformationCircleIcon,
   LayoutAlignRightIcon,
 } from "@hugeicons/core-free-icons";
@@ -841,7 +842,7 @@ export function ChatSettingsPanel({
                         animateRadius={false}
                         icon={ArrowDown01Icon}
                         iconClassName="size-3.5"
-                        className="grid h-7 w-[60px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
+                        className="grid h-7 w-[64px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-full border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] pl-3 pr-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
                       >
                         <SelectValue />
                       </SelectTrigger>
@@ -881,7 +882,7 @@ export function ChatSettingsPanel({
                         animateRadius={false}
                         icon={ArrowDown01Icon}
                         iconClassName="size-3.5"
-                        className="grid h-7 w-[120px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
+                        className="grid h-7 w-[124px] min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 rounded-full border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] pl-3 pr-2 py-0 text-[13px]! font-medium text-nav-fg focus-visible:ring-0 focus-visible:border-transparent [&_[data-slot=select-value]]:min-w-0 [&_[data-slot=select-value]]:truncate [&>svg]:shrink-0"
                         data-test-id="speculative-type-select"
                       >
                         <SelectValue />
@@ -932,7 +933,7 @@ export function ChatSettingsPanel({
                       }}
                       data-test-id="spec-draft-n-max-input"
                       aria-label="Speculative decoding draft tokens"
-                      className="h-7 w-[72px] rounded-[10px] border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] px-2 py-0 text-[13px] font-medium text-nav-fg outline-none focus-visible:ring-0"
+                      className="h-7 w-[76px] rounded-full border-transparent bg-black/[0.04] dark:bg-white/[0.05] hover:bg-black/[0.06] dark:hover:bg-white/[0.1] pl-3 pr-2 py-0 text-[13px] font-medium text-nav-fg outline-none focus-visible:ring-0"
                     />
                   </div>
                 )}
@@ -1563,11 +1564,15 @@ function ChatTemplateFields() {
 
   return (
     <>
-      <div className="flex flex-col gap-2">
-        <div className="flex items-center justify-between gap-2">
-          <span className="text-[13px] font-medium tracking-nav text-nav-fg">
-            Chat Template
-          </span>
+      <div className="flex items-center justify-between gap-2">
+        <button
+          type="button"
+          onClick={openEditor}
+          className="cursor-pointer text-left text-[13px] font-medium tracking-nav text-nav-fg"
+        >
+          Chat Template
+        </button>
+        <div className="flex items-center gap-1">
           {isModified && (
             <Tooltip>
               <TooltipPrimitive.Trigger asChild>
@@ -1593,17 +1598,30 @@ function ChatTemplateFields() {
               </TooltipContent>
             </Tooltip>
           )}
+          <Tooltip>
+            <TooltipPrimitive.Trigger asChild>
+              <button
+                type="button"
+                onClick={openEditor}
+                className="nav-icon-btn text-nav-icon-idle hover:bg-panel-surface-hover hover:text-black dark:hover:text-white"
+                aria-label="Edit chat template"
+              >
+                <HugeiconsIcon
+                  icon={Edit03Icon}
+                  strokeWidth={1.75}
+                  className="size-3.5"
+                />
+              </button>
+            </TooltipPrimitive.Trigger>
+            <TooltipContent
+              side="top"
+              sideOffset={6}
+              className="tooltip-compact"
+            >
+              Edit template
+            </TooltipContent>
+          </Tooltip>
         </div>
-        <button
-          type="button"
-          onClick={openEditor}
-          aria-label="Edit chat template"
-          className="panel-text-surface mt-1 flex w-full h-20 overflow-hidden cursor-pointer items-start px-3.5 py-2.5 text-left text-[13px] font-medium leading-relaxed text-nav-fg corner-squircle focus-visible:outline-none focus-visible:border-ring focus-visible:ring-[1px] focus-visible:ring-ring/40"
-        >
-          <span className="block line-clamp-3 whitespace-pre-wrap break-words">
-            {displayValue}
-          </span>
-        </button>
       </div>
       <Dialog open={editorOpen} onOpenChange={setEditorOpen}>
         <DialogContent
diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index 7a987851aa..0a6ec0c884 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -64,7 +64,7 @@ export function ChatSearchDialog() {
     <CommandDialog
       open={isOpen}
       onOpenChange={setOpen}
-      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 ring-0 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:shadow-none sm:max-w-[635px]"
+      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 ring-0 sm:max-w-[635px]"
       overlayClassName="bg-transparent"
     >
       <Command className="rounded-4xl p-0" filter={chatSearchFilter}>
diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsx
index a9496858c0..a9ce03fa47 100644
--- a/studio/frontend/src/features/chat/projects-page.tsx
+++ b/studio/frontend/src/features/chat/projects-page.tsx
@@ -269,7 +269,12 @@ export function ProjectsPage() {
           </div>
           <DropdownMenu>
             <DropdownMenuTrigger asChild>
-              <Button variant="outline" size="icon" title="Import / Export projects">
+              <Button
+                variant="outline"
+                size="icon"
+                title="Import / Export projects"
+                className="rounded-full border-none bg-muted shadow-none dark:bg-card"
+              >
                 <HugeiconsIcon icon={Download01Icon} strokeWidth={1.75} className="size-icon" />
               </Button>
             </DropdownMenuTrigger>
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
index f606a9941a..5b7fc4ad77 100644
--- a/studio/frontend/src/features/hub/hub-page.tsx
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -675,7 +675,7 @@ export function ModelsPage() {
   );
 
   return (
-    <div className="hub-page flex h-full min-h-0 flex-col bg-background">
+    <div className="hub-page flex h-full min-h-0 flex-col">
       <div className="mx-auto flex w-full max-w-[1180px] flex-1 min-h-0 flex-col gap-6 px-5 pt-8 pb-16 sm:px-9 sm:pt-10 sm:pb-24">
         <ModelsHeader
           cachedCount={effectiveCachedRows.length}
diff --git a/studio/frontend/src/features/hub/hub.css b/studio/frontend/src/features/hub/hub.css
index 66e732c7b6..7dab214e04 100644
--- a/studio/frontend/src/features/hub/hub.css
+++ b/studio/frontend/src/features/hub/hub.css
@@ -97,9 +97,8 @@
 	.hub-page .elevated-card {
 		border: 1px solid color-mix(in srgb, var(--foreground) 5%, transparent);
 		border-radius: 20px;
-		box-shadow:
-			0 12px 48px -8px color-mix(in srgb, var(--foreground) 8%, transparent),
-			0 0 100px 20px color-mix(in srgb, var(--foreground) 3%, transparent);
+		/* No ambient glow: it tinted the white page gray around the card. */
+		box-shadow: 0 12px 48px -8px color-mix(in srgb, var(--foreground) 8%, transparent);
 	}
 
 	@media (min-width: 640px) {
@@ -131,7 +130,7 @@
 	}
 
 	html:not(.dark) .hub-page {
-		background-color: var(--background);
+		background-color: #fff;
 	}
 
 	html:not(.dark) .hub-page > div > section .border-b,
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index ba80432896..b9fb34fedb 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -311,7 +311,7 @@ export function TrainingStartOverlay({
 
   return (
     <div className="pointer-events-none absolute inset-0 z-30 flex items-center justify-center rounded-2xl bg-background/45 backdrop-blur-[1px]">
-      <div className="pointer-events-auto relative flex w-[860px] max-w-[calc(100%-2rem)] flex-col items-center gap-4">
+      <div className="pointer-events-auto relative flex w-[860px] max-w-[calc(100%-2rem)] flex-col items-center">
         <img
           src="/unsloth-gem.png"
           alt="Unsloth Studio"
@@ -358,7 +358,7 @@ export function TrainingStartOverlay({
             </AlertDialogContent>
           </AlertDialog>
           <Terminal
-            className="w-full min-h-[390px] rounded-2xl px-7 py-6 text-left"
+            className="w-full min-h-[390px] rounded-2xl border-0 px-7 py-6 text-left"
             startOnView={false}
             instant={alreadyAnimated}
           >
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 48e587953f..34e4241ae2 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -146,7 +146,7 @@
 	--sidebar-primary-foreground: oklch(1 0 0);
 	--sidebar-accent: oklch(0.96 0.0279 166.55);
 	--sidebar-accent-foreground: oklch(0.2868 0.0649 159.9823);
-	--sidebar-border: oklch(0.92 0 0);
+	--sidebar-border: #f2f2f2;
 	--sidebar-ring: #17b88b;
 	--destructive-foreground: oklch(1 0 0);
 	--font-sans: "Inter Variable", ui-sans-serif, sans-serif, system-ui;
@@ -599,7 +599,7 @@
 	}
 
 	.sidebar-sticky-label {
-		@apply rounded-none bg-sidebar pt-0 pb-[8px] pl-[18px] pr-4 text-[14px]! leading-[17px] font-medium normal-case focus-visible:ring-0! focus-visible:outline-none transition-shadow duration-150;
+		@apply rounded-none bg-sidebar pt-0 pb-[8px] pl-[20px] pr-4 text-[14px]! leading-[17px] font-medium normal-case focus-visible:ring-0! focus-visible:outline-none transition-shadow duration-150;
 		/* Muted section-header gray, matching Gemini's "Notebooks"/"Recents".
 		   Lightened from #5f6368 so the label reads as a header, clearly
 		   lighter than the near-black nav items. */
@@ -621,7 +621,7 @@
 	   prompt button, and the chat-template textarea so all three read
 	   as one quiet gray family, matching the focused-edit-number tint. */
 	.panel-input-group {
-		@apply !h-9 min-h-9 min-w-0 items-stretch gap-0 rounded-[14px] pr-0 transition-colors focus-within:ring-0 focus-within:shadow-none;
+		@apply !h-9 min-h-9 min-w-0 items-stretch gap-0 rounded-full pr-0 transition-colors focus-within:ring-0 focus-within:shadow-none;
 		border: 0 !important;
 		background-color: var(--panel-input-surface);
 	}
@@ -904,12 +904,14 @@
 		/* Pin to the dark --radius so the corners are the same (less round) in
 		   both themes; rounded-4xl here and on the inner Command follow this. */
 		--radius: 0.625rem;
-		/* Match the chat box: soft elevation in light, none in dark. */
+		/* Match the chat box: soft elevation. */
 		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
 	}
 
+	/* Dark: page-bg shadow so the dialog does not merge into same-color
+	   content behind it (same convention as the dropdowns). */
 	.dark .chat-search-surface {
-		box-shadow: none;
+		box-shadow: 0 4px 14px var(--background);
 	}
 
 	.menu-soft-surface,
@@ -1255,8 +1257,9 @@
 
 	/* Soft elevation; [data-slot] outranks the component ring-1, dropping the border. */
 	.unsloth-plus-menu[data-slot] {
-		/* Pin radius so dark matches light (rounded-lg resolves smaller in dark). */
-		border-radius: 18px;
+		/* Pin radius so dark matches light (rounded-lg resolves smaller in dark).
+		   !important beats the global 14px dropdown radius. */
+		border-radius: 18px !important;
 		padding-top: 0.5rem;
 		padding-bottom: 0.5rem;
 		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);
@@ -1265,7 +1268,7 @@
 	/* MCP menu is wider (232px), so nudge the radius up so it reads as round as
 	   the narrower + menu (18 * 232/212 ~= 20px). */
 	.unsloth-plus-menu.mcp-menu[data-slot] {
-		border-radius: 20px;
+		border-radius: 20px !important;
 	}
 
 	.dark .unsloth-plus-menu[data-slot] {

From 81152a079ae381d2ae9a7783edce177efc5a8390 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 07:42:50 -0700
Subject: [PATCH 146/222] Run the HF cache redirect before import fixes that
 can freeze Hub constants (#6150)

* Run the HF cache redirect before import fixes that can freeze Hub constants

unsloth-zoo's redirect_hf_cache_if_readonly() repoints HF_HOME,
HF_HUB_CACHE, and HF_XET_CACHE at import time when the default cache is
read-only. In _gpu_init.py the early fix block can import vllm
(disable_broken_vllm), transformers (check_fbgemm_gpu_version), or
huggingface_hub (fix_huggingface_hub) before import unsloth_zoo runs
the redirect. huggingface_hub computes its cache constants when its
constants module is first executed, so those probes can freeze the old
read-only paths and the redirect then never reaches Hub.

Recent huggingface_hub and vllm releases import lazily, which masks
this, but older supported versions import eagerly: older vllm pulls in
transformers at top level, and on hub versions where is_offline_mode
still exists the hasattr probe materializes the constants module.

Load unsloth_zoo/hf_cache.py straight from its file (it is stdlib-only)
and run the redirect before the fix calls. The zoo's own call later is
an idempotent no-op, and an older unsloth_zoo without hf_cache.py is
skipped silently.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: danielhanchen <danielhanchen@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/_gpu_init.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 172c69c5d8..a7b8ac594c 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -35,6 +35,36 @@ from .import_fixes import (
     fix_huggingface_hub,
 )
 
+# Redirect a read-only Hugging Face cache before anything below can import
+# huggingface_hub / transformers / vllm (disable_broken_vllm probes
+# `import vllm`, check_fbgemm_gpu_version imports transformers, and
+# fix_huggingface_hub imports huggingface_hub itself), all of which can
+# freeze Hub's cache constants with the un-redirected paths. unsloth_zoo
+# runs the same redirect at import, but that happens after these probes.
+# hf_cache.py is stdlib-only, so load it straight from its file without
+# triggering the full unsloth_zoo package init this early; the zoo's own
+# call later is an idempotent no-op. Older unsloth_zoo without hf_cache.py
+# is skipped silently.
+try:
+    import importlib.util as _importlib_util
+    from pathlib import Path as _Path
+
+    _zoo_spec = _importlib_util.find_spec("unsloth_zoo")
+    if _zoo_spec is not None and _zoo_spec.origin:
+        _hf_cache_file = _Path(_zoo_spec.origin).with_name("hf_cache.py")
+        if _hf_cache_file.is_file():
+            _hf_cache_spec = _importlib_util.spec_from_file_location(
+                "unsloth_zoo._early_hf_cache", _hf_cache_file
+            )
+            _hf_cache = _importlib_util.module_from_spec(_hf_cache_spec)
+            _hf_cache_spec.loader.exec_module(_hf_cache)
+            _hf_cache.redirect_hf_cache_if_readonly()
+            del _hf_cache, _hf_cache_spec
+        del _hf_cache_file
+    del _zoo_spec, _importlib_util, _Path
+except Exception:
+    pass
+
 # Configure libdrm ids table path early so ROCm can resolve AMD GPU names.
 configure_amdgpu_asic_id_table_path()
 disable_broken_causal_conv1d()

From 8e2a983f582256c0141ab9c18b0056175c6024d4 Mon Sep 17 00:00:00 2001
From: Long Yixing <longyixing331@gmail.com>
Date: Wed, 10 Jun 2026 22:55:37 +0800
Subject: [PATCH 147/222] Fix Studio MLX VLM resized image layout (#6019)

* fix(studio): infer mlx vlm resized image layout

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/training/worker.py        | 123 +++++++++++++++--
 .../tests/test_mlx_training_worker_config.py  | 124 ++++++++++++++++++
 2 files changed, 237 insertions(+), 10 deletions(-)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index b6ec057231..0a3b1f2019 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1074,7 +1074,74 @@ def _mlx_vlm_max_resized_size(width: int, height: int, target: int) -> tuple[int
     return new_w, new_h
 
 
-def _resize_mlx_vlm_image(image, resize):
+_MLX_VLM_RESIZED_IMAGE_LAYOUT_CACHE = {}
+
+
+def _mlx_vlm_resized_image_layout(processor = None) -> str | None:
+    """Return the numpy image layout expected after Studio-side VLM resizing."""
+    image_processor = getattr(processor, "image_processor", None)
+    if image_processor is None:
+        return None
+    cls = image_processor.__class__
+    key = (getattr(cls, "__module__", ""), getattr(cls, "__qualname__", cls.__name__))
+    if key in _MLX_VLM_RESIZED_IMAGE_LAYOUT_CACHE:
+        return _MLX_VLM_RESIZED_IMAGE_LAYOUT_CACHE[key]
+    copied_image_processor = _copy_mlx_vlm_image_processor(image_processor)
+    layout = (
+        _probe_mlx_vlm_numpy_image_layout(copied_image_processor)
+        if copied_image_processor is not None
+        else None
+    )
+    _MLX_VLM_RESIZED_IMAGE_LAYOUT_CACHE[key] = layout
+    return layout
+
+
+def _copy_mlx_vlm_image_processor(image_processor):
+    import copy
+    try:
+        return copy.deepcopy(image_processor)
+    except Exception:
+        try:
+            return copy.copy(image_processor)
+        except Exception:
+            return None
+
+
+def _probe_mlx_vlm_numpy_image_layout(image_processor) -> str | None:
+    try:
+        import numpy as np
+    except ImportError:
+        return None
+
+    def _accepts(candidate) -> bool:
+        try:
+            image_processor(images = [candidate])
+            return True
+        except TypeError:
+            try:
+                image_processor([candidate])
+                return True
+            except Exception:
+                return False
+        except Exception:
+            return False
+
+    # Use an asymmetric image so CHW-vs-HWC mistakes are visible to processors
+    # that skip conversion for 3D numpy arrays.
+    hwc = np.zeros((64, 96, 3), dtype = np.uint8)
+    chw = np.ascontiguousarray(hwc.transpose(2, 0, 1))
+    if _accepts(hwc):
+        return None
+    if _accepts(chw):
+        return "chw"
+    return None
+
+
+def _resize_mlx_vlm_image(
+    image,
+    resize,
+    image_layout = None,
+):
     if resize is None:
         return image
     try:
@@ -1092,16 +1159,27 @@ def _resize_mlx_vlm_image(image, resize):
     # On resize, hand mlx-vlm a writable RGB ndarray so its PIL-path
     # square-resize is skipped and HF processors don't warn on non-writable
     # views. resize=None above keeps the original PIL.
-    return np.array(image, copy = True)
+    array = np.array(image, copy = True)
+    if image_layout == "chw":
+        return np.ascontiguousarray(array.transpose(2, 0, 1))
+    return array
 
 
-def _resize_mlx_vlm_images(value, resize):
+def _resize_mlx_vlm_images(
+    value,
+    resize,
+    image_layout = None,
+):
     if isinstance(value, list):
-        return [_resize_mlx_vlm_image(image, resize) for image in value]
-    return _resize_mlx_vlm_image(value, resize)
+        return [_resize_mlx_vlm_image(image, resize, image_layout = image_layout) for image in value]
+    return _resize_mlx_vlm_image(value, resize, image_layout = image_layout)
 
 
-def _adapt_for_mlx_vlm(items, resize = None):
+def _adapt_for_mlx_vlm(
+    items,
+    resize = None,
+    image_layout = None,
+):
     """Adapt GPU-path VLM dataset output for mlx-vlm.
 
     The GPU path embeds PIL images in message content as
@@ -1121,7 +1199,13 @@ def _adapt_for_mlx_vlm(items, resize = None):
                     if isinstance(part, dict) and part.get("type") == "image":
                         img = part.get("image")
                         if img is not None:
-                            images.append(_resize_mlx_vlm_image(img, resize))
+                            images.append(
+                                _resize_mlx_vlm_image(
+                                    img,
+                                    resize,
+                                    image_layout = image_layout,
+                                )
+                            )
                         new_content.append({"type": "image"})
                     else:
                         new_content.append(part)
@@ -1132,9 +1216,17 @@ def _adapt_for_mlx_vlm(items, resize = None):
         if images:
             out["image"] = images[0] if len(images) == 1 else images
         elif "image" in item:
-            out["image"] = _resize_mlx_vlm_images(item["image"], resize)
+            out["image"] = _resize_mlx_vlm_images(
+                item["image"],
+                resize,
+                image_layout = image_layout,
+            )
         elif "images" in item:
-            out["images"] = _resize_mlx_vlm_images(item["images"], resize)
+            out["images"] = _resize_mlx_vlm_images(
+                item["images"],
+                resize,
+                image_layout = image_layout,
+            )
         adapted.append(out)
     return adapted
 
@@ -1322,7 +1414,6 @@ def _run_mlx_training(event_queue, stop_queue, config):
             "status",
             status_message = f"MLX vision image resize: {vision_image_size} (max dimension)",
         )
-
     # ── 2. Apply LoRA / full FT ──
     # gradient_checkpointing stays a string ("mlx"/"unsloth"/"none"/etc.);
     # get_peft_model and MLXTrainer both accept and handle strings.
@@ -1447,9 +1538,15 @@ def _run_mlx_training(event_queue, stop_queue, config):
                 progress_callback = _fmt_progress,
             )
             if vlm_info.get("success"):
+                vision_image_layout = (
+                    _mlx_vlm_resized_image_layout(tokenizer)
+                    if vision_image_size is not None
+                    else None
+                )
                 dataset = _adapt_for_mlx_vlm(
                     vlm_info["dataset"],
                     resize = vision_image_size,
+                    image_layout = vision_image_layout,
                 )
             else:
                 errors = vlm_info.get("errors", [])
@@ -1463,9 +1560,15 @@ def _run_mlx_training(event_queue, stop_queue, config):
                     dataset_name = hf_dataset or "local",
                 )
                 if ev_info.get("success"):
+                    vision_image_layout = (
+                        _mlx_vlm_resized_image_layout(tokenizer)
+                        if vision_image_size is not None
+                        else None
+                    )
                     eval_dataset = _adapt_for_mlx_vlm(
                         ev_info["dataset"],
                         resize = vision_image_size,
+                        image_layout = vision_image_layout,
                     )
 
         elif format_type:
diff --git a/studio/backend/tests/test_mlx_training_worker_config.py b/studio/backend/tests/test_mlx_training_worker_config.py
index 811971ec36..4402031467 100644
--- a/studio/backend/tests/test_mlx_training_worker_config.py
+++ b/studio/backend/tests/test_mlx_training_worker_config.py
@@ -63,6 +63,10 @@ _worker = _load_worker_module()
 _normalize_mlx_studio_optimizer = _worker._normalize_mlx_studio_optimizer
 _normalize_mlx_studio_scheduler = _worker._normalize_mlx_studio_scheduler
 _mlx_vlm_max_resized_size = _worker._mlx_vlm_max_resized_size
+_mlx_vlm_resized_image_layout = _worker._mlx_vlm_resized_image_layout
+_copy_mlx_vlm_image_processor = _worker._copy_mlx_vlm_image_processor
+_resize_mlx_vlm_image = _worker._resize_mlx_vlm_image
+_adapt_for_mlx_vlm = _worker._adapt_for_mlx_vlm
 
 
 def test_mlx_studio_optimizer_aliases_are_explicit():
@@ -90,3 +94,123 @@ def test_mlx_vlm_resize_uses_max_dimension_like_torch_trainer():
     # Half-pixel cases must match the Torch collator (not banker's round).
     assert _mlx_vlm_max_resized_size(333, 1000, 500) == (167, 500)
     assert _mlx_vlm_max_resized_size(1000, 333, 500) == (500, 167)
+
+
+def test_mlx_vlm_resize_keeps_default_numpy_layout_hwc():
+    Image = pytest.importorskip("PIL.Image")
+    image = Image.new("RGB", (320, 200), color = (10, 20, 30))
+
+    resized = _resize_mlx_vlm_image(image, 128)
+
+    assert resized.shape == (80, 128, 3)
+    assert resized.flags.c_contiguous
+
+
+def test_mlx_vlm_resize_uses_requested_chw_numpy_layout():
+    Image = pytest.importorskip("PIL.Image")
+    image = Image.new("RGB", (320, 200), color = (10, 20, 30))
+
+    resized = _resize_mlx_vlm_image(image, 128, image_layout = "chw")
+
+    assert resized.shape == (3, 80, 128)
+    assert resized.flags.c_contiguous
+
+
+def test_mlx_vlm_resized_image_layout_probes_processor_contract():
+    class ChwOnlyImageProcessor:
+        def __call__(self, images = None):
+            image = images[0]
+            if image.shape[0] == 3:
+                return {"pixel_values": image}
+            raise ValueError("expected CHW")
+
+    class HwcImageProcessor:
+        def __call__(self, images = None):
+            image = images[0]
+            if image.shape[-1] == 3:
+                return {"pixel_values": image}
+            raise ValueError("expected HWC")
+
+    assert (
+        _mlx_vlm_resized_image_layout(
+            types.SimpleNamespace(image_processor = ChwOnlyImageProcessor())
+        )
+        == "chw"
+    )
+    assert (
+        _mlx_vlm_resized_image_layout(types.SimpleNamespace(image_processor = HwcImageProcessor()))
+        is None
+    )
+
+
+def test_mlx_vlm_layout_probe_copies_image_processor():
+    class StatefulImageProcessor:
+        def __init__(self):
+            self.calls = 0
+
+        def __call__(self, images = None):
+            self.calls += 1
+            image = images[0]
+            if image.shape[0] == 3:
+                return {"pixel_values": image}
+            raise ValueError("expected CHW")
+
+    image_processor = StatefulImageProcessor()
+
+    layout = _mlx_vlm_resized_image_layout(types.SimpleNamespace(image_processor = image_processor))
+
+    assert layout == "chw"
+    assert image_processor.calls == 0
+
+
+def test_mlx_vlm_image_processor_copy_refuses_uncopyable_processors():
+    class UncopyableImageProcessor:
+        def __copy__(self):
+            raise RuntimeError("no copy")
+
+        def __deepcopy__(self, _memo):
+            raise RuntimeError("no deepcopy")
+
+    image_processor = UncopyableImageProcessor()
+
+    assert _copy_mlx_vlm_image_processor(image_processor) is None
+
+
+def test_mlx_vlm_layout_probe_skips_uncopyable_processors():
+    class UncopyableImageProcessor:
+        def __copy__(self):
+            raise RuntimeError("no copy")
+
+        def __deepcopy__(self, _memo):
+            raise RuntimeError("no deepcopy")
+
+        def __call__(self, images = None):
+            raise AssertionError("live processor should not be probed")
+
+    assert (
+        _mlx_vlm_resized_image_layout(
+            types.SimpleNamespace(image_processor = UncopyableImageProcessor())
+        )
+        is None
+    )
+
+
+def test_mlx_vlm_adapter_applies_chw_layout_to_message_images():
+    Image = pytest.importorskip("PIL.Image")
+    image = Image.new("RGB", (320, 200), color = (10, 20, 30))
+    item = {
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": "Describe it."},
+                ],
+            }
+        ]
+    }
+
+    adapted = _adapt_for_mlx_vlm([item], resize = 128, image_layout = "chw")
+
+    assert adapted[0]["image"].shape == (3, 80, 128)
+    assert adapted[0]["messages"][0]["content"][0] == {"type": "image"}

From 154457dbf75b749a908e545e9a4945dda7665462 Mon Sep 17 00:00:00 2001
From: Long Yixing <longyixing331@gmail.com>
Date: Wed, 10 Jun 2026 22:55:50 +0800
Subject: [PATCH 148/222] fix(studio): reject unsupported mlx training modes
 (#6091)

---
 studio/backend/core/training/worker.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 0a3b1f2019..ff4329ee13 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1373,6 +1373,14 @@ def _run_mlx_training(event_queue, stop_queue, config):
         message = "LoftQ is not supported for MLX training yet."
         _send("error", error = message)
         raise NotImplementedError(message)
+    if config.get("is_embedding"):
+        message = "Embedding model training is not supported for MLX training yet."
+        _send("error", error = message)
+        raise NotImplementedError(message)
+    if config.get("training_type") == "Continued Pretraining":
+        message = "Continued Pretraining is not supported for MLX training yet."
+        _send("error", error = message)
+        raise NotImplementedError(message)
 
     optim_name = _normalize_mlx_studio_optimizer(config.get("optim", "adamw_8bit"))
     lr_scheduler_type = _normalize_mlx_studio_scheduler(config.get("lr_scheduler_type", "linear"))

From bc8b9dc917797819e6f473703fb8f50c3358e8c9 Mon Sep 17 00:00:00 2001
From: Long Yixing <longyixing331@gmail.com>
Date: Wed, 10 Jun 2026 22:56:02 +0800
Subject: [PATCH 149/222] fix(studio): forward mlx custom format mapping
 (#6094)

---
 studio/backend/core/training/worker.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index ff4329ee13..267d6689b4 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1530,6 +1530,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
     # Reuse the GPU format pipeline for VLM (auto-detects OCR/caption/llava/
     # sharegpt+images) and text (alpaca/sharegpt/chatml → "text" column).
     format_type = config.get("format_type", "")
+    custom_format_mapping = config.get("custom_format_mapping")
     try:
         from utils.datasets import format_and_template_dataset
         def _fmt_progress(status_message = "", **_kw):
@@ -1543,6 +1544,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
                 tokenizer = tokenizer,
                 is_vlm = True,
                 dataset_name = hf_dataset or "local",
+                custom_format_mapping = custom_format_mapping,
                 progress_callback = _fmt_progress,
             )
             if vlm_info.get("success"):
@@ -1566,6 +1568,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
                     tokenizer = tokenizer,
                     is_vlm = True,
                     dataset_name = hf_dataset or "local",
+                    custom_format_mapping = custom_format_mapping,
                 )
                 if ev_info.get("success"):
                     vision_image_layout = (
@@ -1588,6 +1591,8 @@ def _run_mlx_training(event_queue, stop_queue, config):
                 is_vlm = False,
                 format_type = format_type,
                 dataset_name = hf_dataset or "local",
+                custom_format_mapping = custom_format_mapping,
+                progress_callback = _fmt_progress,
             )
             if info.get("success", True):
                 dataset = info.get("dataset", dataset)
@@ -1599,6 +1604,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
                     is_vlm = False,
                     format_type = format_type,
                     dataset_name = hf_dataset or "local",
+                    custom_format_mapping = custom_format_mapping,
                 )
                 if ev.get("success", True):
                     eval_dataset = ev.get("dataset", eval_dataset)

From 184141db99036620676855cb6eb03148a81dd981 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:00:28 -0700
Subject: [PATCH 150/222] Tests + CI guard: batched left-padded generation can
 never silently regress again (#1066, #3699) (#6145)

* Add regression guard for batched left-padded generation (#1066, #3699)

Three layers of tests plus a path-filtered CI workflow so the left-padding
position_ids / attention-mask bug class cannot silently return:

- tests/utils/test_prepare_inputs_ast_guard.py: import-free AST checks on
  _fast_prepare_inputs_for_generation (cumsum-from-mask branch present,
  cache_position only as fallback, no mask truncation, model families wired)
- tests/utils/test_prepare_inputs_leftpad.py: CPU behavioral unit test with
  synthetic left-padded masks and fake caches; exact expected position_ids
  for prefill and cached decode
- tests/utils/test_batched_leftpad_generation_gpu.py: optional GPU e2e,
  solo vs batched prefix match, skipped without CUDA
- .github/workflows/batch-inference-guard.yml: ubuntu-latest CPU job running
  the two deterministic layers on PRs touching unsloth/models/**

Validated: all pass on main; both CPU layers fail at 6d0f8643~1 (pre #4100)
and at 332eabf3~1 (pre #2216), reproducing the historical bug signatures.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Cite staging proof in batch-inference-guard header (staging-2 PRs 170/171)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fold left-padding guard into consolidated Core CI; merge AST + behavioral tests

No new workflow and no new CI job: the guard now runs as one HARD GATE step
inside consolidated-tests-ci.yml, right after the callback signature drift
detector, where the CPU torch stack is already installed. The AST structural
checks and the behavioral unit tests live in a single file
(tests/utils/test_prepare_inputs_leftpad.py); the AST layer stays stdlib-only
with unsloth imported lazily inside the behavioral tests, so import breakage
cannot mask the structural checks.

Revalidated after the merge: 11 assertions pass on main, 8 fail at
6d0f8643~1 (pre #4100).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update staging proof reference for consolidated gate (PRs 170/172)

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .github/workflows/consolidated-tests-ci.yml   |  14 +
 .../test_batched_leftpad_generation_gpu.py    | 107 +++++
 tests/utils/test_prepare_inputs_leftpad.py    | 409 ++++++++++++++++++
 3 files changed, 530 insertions(+)
 create mode 100644 tests/utils/test_batched_leftpad_generation_gpu.py
 create mode 100644 tests/utils/test_prepare_inputs_leftpad.py

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index c6c2e1fc37..022c796ac4 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -333,6 +333,20 @@ jobs:
         run: |
           python -m pytest -v --tb=short tests/test_callback_signature_drift.py
 
+      - name: batched left-padding generation guard (HARD GATE)
+        # Guards _fast_prepare_inputs_for_generation against the bug class of
+        # issues #1066 / #3699: position_ids taken from cache_position (which
+        # counts left-pad tokens) or the 2D attention mask truncated to its
+        # last column. Both shipped in cc4c5d77 and were fixed by #2216 and
+        # #4100; nothing tested this path, so each regression reached users.
+        # Layer 1 in the file is stdlib-ast-only (survives unsloth import
+        # breakage), layer 2 calls the real function on CPU via the
+        # tests/conftest.py CUDA spoof. Validated to fail on the pre-#2216
+        # and pre-#4100 code states; staging proof on GPU-less runners:
+        # danielhanchen/unsloth-staging-2 PR 170 (green, gate passed in all combos) / PR 172 (red, gate failed in all combos).
+        run: |
+          python -m pytest -v --tb=short tests/utils/test_prepare_inputs_leftpad.py
+
       - name: unsloth Bucket-A — CPU tests not in Repo tests (CPU)
         # CPU tests across 6 files under tests/saving/, tests/utils/, tests/python/
         # that Repo tests (CPU) --ignores. AST/protobuf/regex plus tiny CPU model
diff --git a/tests/utils/test_batched_leftpad_generation_gpu.py b/tests/utils/test_batched_leftpad_generation_gpu.py
new file mode 100644
index 0000000000..c2610d4673
--- /dev/null
+++ b/tests/utils/test_batched_leftpad_generation_gpu.py
@@ -0,0 +1,107 @@
+"""End-to-end GPU guard for batched left-padded generation (issues #1066, #3699).
+
+For each prompt, greedy generation inside a left-padded batch must match
+generating that prompt alone at batch size 1 for the first PREFIX_TOKENS
+tokens, and the full output must not be gibberish. The bug class (#1066,
+#3699) makes padded rows diverge immediately into garbage; in contrast,
+benign batch-size-dependent kernel numerics can flip a greedy near-tie deep
+into the sequence, so an exact full-length match would be flaky. Uses a small
+instruct model (chat-templated prompts have high-margin argmaxes).
+
+Skipped automatically when CUDA is unavailable, so CPU CI is unaffected.
+Run manually on any GPU box:
+
+    python -m pytest tests/utils/test_batched_leftpad_generation_gpu.py -v
+"""
+
+import pytest
+import torch
+
+cuda_available = torch.cuda.is_available()
+
+pytestmark = pytest.mark.skipif(not cuda_available, reason = "requires a CUDA GPU")
+
+MODEL_NAME = "unsloth/Qwen2.5-0.5B-Instruct"
+MAX_NEW_TOKENS = 32
+PREFIX_TOKENS = 16
+
+PROMPTS = [
+    "Give me a short introduction to large language model.",
+    "Here is an experiment log: "
+    + " ".join(f"run {i} completed with stable throughput and no anomalies;" for i in range(1, 41))
+    + " In one sentence, what is the overall conclusion?",
+]
+
+
+@pytest.fixture(scope = "module")
+def model_and_tokenizer():
+    from unsloth import FastLanguageModel
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name = MODEL_NAME,
+        max_seq_length = 2048,
+        load_in_4bit = True,
+    )
+    FastLanguageModel.for_inference(model)
+    tokenizer.padding_side = "left"
+    if tokenizer.pad_token_id is None:
+        tokenizer.pad_token_id = tokenizer.eos_token_id
+    return model, tokenizer
+
+
+def _chat(tokenizer, prompt):
+    return tokenizer.apply_chat_template(
+        [{"role": "user", "content": prompt}],
+        tokenize = False,
+        add_generation_prompt = True,
+    )
+
+
+def _generate(model, tokenizer, texts):
+    inputs = tokenizer(texts, return_tensors = "pt", padding = True, add_special_tokens = False).to(
+        "cuda"
+    )
+    with torch.inference_mode():
+        out = model.generate(
+            **inputs,
+            max_new_tokens = MAX_NEW_TOKENS,
+            do_sample = False,
+            temperature = None,
+            top_p = None,
+            top_k = None,
+            use_cache = True,
+            pad_token_id = tokenizer.pad_token_id,
+        )
+    suffixes = out[:, inputs["input_ids"].shape[1] :]
+    return [row.tolist() for row in suffixes]
+
+
+def _looks_gibberish(text):
+    if not text.strip():
+        return True
+    exclam = text.count("!") / max(len(text), 1)
+    nonascii = sum(1 for c in text if ord(c) > 0x2FFF) / max(len(text), 1)
+    return exclam > 0.3 or nonascii > 0.5
+
+
+def test_batched_leftpad_matches_solo_generation(model_and_tokenizer):
+    model, tokenizer = model_and_tokenizer
+
+    texts = [_chat(tokenizer, p) for p in PROMPTS]
+    solo = [_generate(model, tokenizer, [t])[0] for t in texts]
+    batched = _generate(model, tokenizer, texts)
+
+    for i, prompt in enumerate(PROMPTS):
+        solo_text = tokenizer.decode(solo[i], skip_special_tokens = True)
+        batch_text = tokenizer.decode(batched[i], skip_special_tokens = True)
+        assert batched[i][:PREFIX_TOKENS] == solo[i][:PREFIX_TOKENS], (
+            f"prompt {i} ({prompt[:30]!r}...) diverged from solo generation "
+            f"within the first {PREFIX_TOKENS} tokens inside a left-padded "
+            "batch; batched left-padded generation is broken again "
+            f"(issues #1066, #3699).\n"
+            f"solo   : {solo_text!r}\nbatched: {batch_text!r}"
+        )
+        assert not _looks_gibberish(batch_text), (
+            f"prompt {i} produced gibberish in a left-padded batch "
+            f"(issues #1066, #3699): {batch_text!r}"
+        )
diff --git a/tests/utils/test_prepare_inputs_leftpad.py b/tests/utils/test_prepare_inputs_leftpad.py
new file mode 100644
index 0000000000..b773b088b5
--- /dev/null
+++ b/tests/utils/test_prepare_inputs_leftpad.py
@@ -0,0 +1,409 @@
+"""Regression guard for batched left-padded generation (issues #1066, #3699).
+
+`_fast_prepare_inputs_for_generation` in unsloth/models/llama.py is shared by
+every decoder family wired through `fix_prepare_inputs_for_generation` (llama,
+qwen2/3, qwen3_moe, mistral, gemma/2, cohere, granite). Two historical bugs
+lived in it:
+
+  (a) the 2D attention mask was truncated to its last column during cached
+      decode, losing padding information (introduced cc4c5d77, fixed by #2216);
+  (b) position_ids were taken directly from cache_position, a global counter
+      that includes left-pad tokens, so padded rows generated garbage
+      (introduced cc4c5d77, reported in #1066/#3699, fixed by #4100).
+
+Two layers in this file, both CPU-only and deterministic:
+
+  1. AST structural checks (TestAstGuard section): parse llama.py with the
+     stdlib `ast` module only, no unsloth import, so they keep working even
+     when the package itself fails to import.
+  2. Behavioral checks: call the real function with synthetic left-padded
+     masks and fake caches; unsloth is imported lazily inside each test.
+
+Both layers fail on the historical bug patterns (validated against the code
+states immediately before #2216 and before #4100). Staging proof on GPU-less
+hosted runners: danielhanchen/unsloth-staging-2 PRs 170 (green) and 171 (red).
+
+Companion manual GPU end-to-end check (skipped without CUDA):
+tests/utils/test_batched_leftpad_generation_gpu.py
+"""
+
+import ast
+from pathlib import Path
+
+import pytest
+import torch
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LLAMA_PY = REPO_ROOT / "unsloth" / "models" / "llama.py"
+
+FUNC_NAME = "_fast_prepare_inputs_for_generation"
+
+
+# --------------------------------------------------------------------------
+# Layer 1: AST structural guard (stdlib only, no unsloth import)
+# --------------------------------------------------------------------------
+
+# Model files that call fix_prepare_inputs_for_generation(...) and therefore
+# share the guarded function. glm4_moe and falcon_h1 are intentionally absent:
+# GLM4 MoE does not patch the Llama-compatible generation path (MLA attention)
+# and falcon_h1 ships its own _fast_prepare_inputs_for_generation variant.
+WIRED_MODEL_FILES = [
+    "mistral.py",
+    "gemma.py",
+    "gemma2.py",
+    "qwen2.py",
+    "qwen3.py",
+    "qwen3_moe.py",
+    "cohere.py",
+    "granite.py",
+]
+
+
+def _load_function():
+    tree = ast.parse(LLAMA_PY.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name == FUNC_NAME:
+            return node
+    raise AssertionError(
+        f"{FUNC_NAME} not found in {LLAMA_PY}; if it was renamed or moved, "
+        "update this guard so batched left-padded generation stays protected"
+    )
+
+
+def _names_in(node):
+    """All Name ids, attribute names and string constants in a subtree."""
+    found = set()
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Name):
+            found.add(sub.id)
+        elif isinstance(sub, ast.Attribute):
+            found.add(sub.attr)
+        elif isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+            found.add(sub.value)
+    return found
+
+
+def _mentions_attention_mask(node):
+    return any("attention_mask" in name for name in _names_in(node))
+
+
+def _is_kwargs_position_ids_target(target):
+    return (
+        isinstance(target, ast.Subscript)
+        and isinstance(target.value, ast.Name)
+        and target.value.id == "kwargs"
+        and isinstance(target.slice, ast.Constant)
+        and target.slice.value == "position_ids"
+    )
+
+
+def _walk_with_paths(node, path = ()):
+    yield node, path
+    for child in ast.iter_child_nodes(node):
+        yield from _walk_with_paths(child, path + (node,))
+
+
+def _find_mask_branch(func):
+    """The If whose test checks the 2D attention mask (dim() == 2)."""
+    for node in ast.walk(func):
+        if not isinstance(node, ast.If):
+            continue
+        test_names = _names_in(node.test)
+        if "dim" in test_names and any("attention_mask" in n for n in test_names):
+            return node
+    return None
+
+
+def test_mask_derived_position_ids_branch_exists():
+    func = _load_function()
+    branch = _find_mask_branch(func)
+    assert branch is not None, (
+        f"{FUNC_NAME} no longer has a branch testing the 2D attention mask "
+        "(dim() == 2); position_ids must be derived per row from the mask for "
+        "left-padded batches (see PR #4100 / issues #1066, #3699)"
+    )
+
+    body_names = set()
+    for stmt in branch.body:
+        body_names |= _names_in(stmt)
+    assert "cumsum" in body_names and _mentions_attention_mask(
+        ast.Module(body = branch.body, type_ignores = [])
+    ), (
+        "the attention-mask branch must compute position_ids via "
+        "attention_mask.cumsum(...); reintroducing cache_position-based "
+        "positions breaks left-padded batched generation (issue #3699)"
+    )
+    assert (
+        "masked_fill_" in body_names or "masked_fill" in body_names
+    ), "the attention-mask branch must mask pad positions (masked_fill on mask == 0)"
+    assigns_kwargs = any(
+        isinstance(stmt, ast.Assign)
+        and any(_is_kwargs_position_ids_target(t) for t in stmt.targets)
+        for stmt in ast.walk(ast.Module(body = branch.body, type_ignores = []))
+    )
+    assert (
+        assigns_kwargs
+    ), 'the attention-mask branch must store the derived positions into kwargs["position_ids"]'
+
+
+def test_cache_position_only_used_as_fallback_for_position_ids():
+    func = _load_function()
+    branch = _find_mask_branch(func)
+    assert branch is not None
+
+    orelse_nodes = set()
+    for stmt in branch.orelse:
+        for sub in ast.walk(stmt):
+            orelse_nodes.add(id(sub))
+
+    offenders = []
+    for node, path in _walk_with_paths(func):
+        if not isinstance(node, ast.Assign):
+            continue
+        if not any(_is_kwargs_position_ids_target(t) for t in node.targets):
+            continue
+        value_names = _names_in(node.value)
+        # Direct use of cache_position, or the local alias `cp` the current
+        # implementation builds from it inside the fallback branch.
+        derives_from_cache_position = any("cache_position" in n for n in value_names) or bool(
+            value_names & {"cp"}
+        )
+        if derives_from_cache_position and id(node) not in orelse_nodes:
+            offenders.append(ast.unparse(node))
+
+    assert not offenders, (
+        'kwargs["position_ids"] must never be assigned from cache_position '
+        "outside the fallback (orelse) of the 2D attention-mask branch; "
+        "cache_position counts left-pad tokens, so padded rows generate "
+        f"garbage (issues #1066, #3699). Offending assignments: {offenders}"
+    )
+
+
+def test_attention_mask_never_truncated_to_last_column():
+    func = _load_function()
+    offenders = []
+    for node in ast.walk(func):
+        if not isinstance(node, ast.Assign):
+            continue
+        value = node.value
+        if not isinstance(value, ast.Subscript):
+            continue
+        if not _mentions_attention_mask(value.value):
+            continue
+        # Match a trailing [-1]-style column selection: [:, [-1]] or [:, -1:]
+        sl = value.slice
+        if isinstance(sl, ast.Tuple) and len(sl.elts) == 2:
+            col = sl.elts[1]
+            is_last_col_list = (
+                isinstance(col, ast.List)
+                and len(col.elts) == 1
+                and isinstance(col.elts[0], ast.UnaryOp)
+            )
+            is_last_col_slice = (
+                isinstance(col, ast.Slice)
+                and col.lower is not None
+                and isinstance(col.lower, ast.UnaryOp)
+                and getattr(getattr(col.lower, "operand", None), "value", None) == 1
+                and col.upper is None
+            )
+            if is_last_col_list or is_last_col_slice:
+                offenders.append(ast.unparse(node))
+    assert not offenders, (
+        "the 2D attention mask must not be truncated to its last column; this "
+        "was the pre-#2216 bug that drops padding information in cached decode "
+        f"(issue #1066). Offending assignments: {offenders}"
+    )
+
+
+def test_model_families_stay_wired_to_shared_prepare_inputs():
+    missing = []
+    for fname in WIRED_MODEL_FILES:
+        path = REPO_ROOT / "unsloth" / "models" / fname
+        if not path.exists():
+            continue
+        if "fix_prepare_inputs_for_generation(" not in path.read_text():
+            missing.append(fname)
+    assert not missing, (
+        "these model files no longer call fix_prepare_inputs_for_generation, "
+        "so they lose the guarded left-padding-safe prepare_inputs path: "
+        f"{missing}"
+    )
+
+
+# --------------------------------------------------------------------------
+# Layer 2: behavioral guard (calls the real function, lazy unsloth import)
+# --------------------------------------------------------------------------
+
+PAST_LEN = 4
+
+# Three rows with different amounts of left padding (0 = pad).
+MASK = torch.tensor(
+    [
+        [0, 0, 1, 1, 1],
+        [1, 1, 1, 1, 1],
+        [0, 1, 1, 1, 1],
+    ],
+    dtype = torch.long,
+)
+BS, SEQ = MASK.shape
+
+# Per-row positions: cumsum(-1) - 1 with pad slots filled with 1.
+EXPECTED_PREFILL_POSITIONS = torch.tensor(
+    [
+        [1, 1, 0, 1, 2],
+        [0, 1, 2, 3, 4],
+        [1, 0, 1, 2, 3],
+    ],
+    dtype = torch.long,
+)
+
+
+class FakeDynamicCache:
+    """Minimal stand-in for transformers DynamicCache with a non-empty cache."""
+
+    def __init__(self, seq_length):
+        self._seq_length = seq_length
+
+    def __len__(self):
+        return 1
+
+    def get_seq_length(self):
+        return self._seq_length
+
+
+class FakeModel:
+    """Bare-minimum `self` for _fast_prepare_inputs_for_generation."""
+
+    dtype = torch.float32
+    config = None
+
+
+class FakeModelWith4DMask(FakeModel):
+    """Variant exposing the HF 4D mask builder; records what it receives."""
+
+    def __init__(self):
+        self.mask_calls = []
+
+    def _prepare_4d_causal_attention_mask_with_cache_position(
+        self,
+        attention_mask,
+        sequence_length,
+        target_length,
+        dtype,
+        device,
+        cache_position,
+        batch_size,
+        config = None,
+        past_key_values = None,
+    ):
+        self.mask_calls.append(
+            {
+                "mask_shape": tuple(attention_mask.shape) if attention_mask is not None else None,
+                "sequence_length": sequence_length,
+                "target_length": target_length,
+                "batch_size": batch_size,
+            }
+        )
+        return torch.zeros((batch_size, 1, sequence_length, target_length), dtype = dtype)
+
+
+def _prepare(model, input_ids, attention_mask, **kwargs):
+    from unsloth.models import llama as llama_mod
+    return llama_mod._fast_prepare_inputs_for_generation(
+        model, input_ids, attention_mask = attention_mask, **kwargs
+    )
+
+
+def test_prefill_position_ids_derived_from_left_padded_mask():
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    result = _prepare(FakeModel(), input_ids, MASK)
+
+    position_ids = result.get("position_ids", None)
+    assert (
+        position_ids is not None
+    ), "prefill with a left-padded 2D attention mask must populate position_ids"
+    assert torch.equal(position_ids.long().cpu(), EXPECTED_PREFILL_POSITIONS), (
+        "prefill position_ids must be derived per row from the attention mask "
+        "(cumsum - 1, pads masked), so each row starts counting at its first "
+        f"real token; got {position_ids.tolist()}"
+    )
+    assert result["input_ids"].shape == (BS, SEQ)
+
+
+@pytest.mark.parametrize("pass_cache_position", [True, False])
+def test_cached_decode_position_ids_ignore_left_padding(pass_cache_position):
+    # Decode step: PAST_LEN tokens cached, current token is the mask's last
+    # column. Row 0 has 2 pads, so its current token sits at logical position 2,
+    # NOT at cache_position == PAST_LEN. This is exactly issue #3699.
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    kwargs = {"past_key_values": FakeDynamicCache(PAST_LEN)}
+    if pass_cache_position:
+        kwargs["cache_position"] = torch.arange(PAST_LEN, PAST_LEN + 1)
+
+    result = _prepare(FakeModel(), input_ids, MASK, **kwargs)
+
+    assert result["input_ids"].shape == (
+        BS,
+        1,
+    ), "cached decode must slice input_ids to the last token only"
+    position_ids = result.get("position_ids", None)
+    assert position_ids is not None
+    expected = torch.tensor([[2], [4], [3]], dtype = torch.long)
+    assert torch.equal(position_ids.long().cpu().reshape(BS, 1), expected), (
+        "left-padded cached decode must derive per-row position_ids from the "
+        "attention mask, not from cache_position which counts pad tokens; got "
+        f"{position_ids.tolist()}, expected {expected.tolist()} "
+        "(row 0 has 2 pads: its position must be 2, not 4)"
+    )
+
+
+def test_cached_decode_does_not_truncate_2d_attention_mask():
+    # Without a 4D mask builder the original 2D mask must survive untouched.
+    # The historical bug replaced it with attention_mask[:, [-1]].
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    result = _prepare(FakeModel(), input_ids, MASK, past_key_values = FakeDynamicCache(PAST_LEN))
+    mask_out = result["attention_mask"]
+    assert mask_out is not None
+    assert mask_out.dim() != 2 or mask_out.shape[-1] == SEQ, (
+        "the 2D attention mask must not be truncated to its last column during "
+        f"cached decode (got shape {tuple(mask_out.shape)}); padding rows lose "
+        "their pad information otherwise"
+    )
+
+
+def test_cached_decode_4d_mask_builder_receives_full_target_length():
+    model = FakeModelWith4DMask()
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    result = _prepare(model, input_ids, MASK, past_key_values = FakeDynamicCache(PAST_LEN))
+    assert len(model.mask_calls) == 1
+    call = model.mask_calls[0]
+    assert call["mask_shape"] == (BS, SEQ), (
+        "the 4D mask builder must receive the full 2D padding mask, not a "
+        f"truncated one (got {call['mask_shape']})"
+    )
+    assert call["sequence_length"] == 1
+    assert call["target_length"] == SEQ, (
+        "target_length must cover the whole mask so padded positions stay "
+        f"masked (got {call['target_length']})"
+    )
+    assert result["attention_mask"].dim() == 4
+
+
+def test_caller_supplied_position_ids_are_passed_through():
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    custom = torch.full((BS, SEQ), 7, dtype = torch.long)
+    result = _prepare(FakeModel(), input_ids, MASK, position_ids = custom)
+    assert torch.equal(
+        result["position_ids"], custom
+    ), "caller-supplied position_ids must not be overwritten"
+
+
+def test_legacy_tuple_cache_still_takes_cached_decode_path():
+    # Legacy cache format: tuple of (K, V) per layer; past length from K.shape[-2].
+    k = torch.zeros((BS, 1, PAST_LEN, 8))
+    legacy_cache = ((k, k.clone()),)
+    input_ids = torch.arange(BS * SEQ).reshape(BS, SEQ)
+    result = _prepare(FakeModel(), input_ids, MASK, past_key_values = legacy_cache)
+    assert result["input_ids"].shape == (BS, 1)
+    expected = torch.tensor([[2], [4], [3]], dtype = torch.long)
+    assert torch.equal(result["position_ids"].long().cpu().reshape(BS, 1), expected)

From 2599f9fe9d9bfba144effce92de2be43eed2f203 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:05:24 -0700
Subject: [PATCH 151/222] Tests: follow Compare chat into the More submenu in
 the Playwright chat UI driver (#6153)

* tests: follow Compare chat into the More submenu in the chat UI driver

The plus-menu declutter moved the Compare chat item into a More
submenu (DropdownMenuSub in thread.tsx / shared-composer.tsx), so the
Playwright driver stopped finding it at the top level and Chat UI Tests
went red on every PR regardless of its diff. Open the More sub-trigger
(hover, then click as a fallback) before asserting the item; the direct
lookup stays first so the driver still passes if the item moves back.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 tests/studio/playwright_chat_ui.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tests/studio/playwright_chat_ui.py b/tests/studio/playwright_chat_ui.py
index dc62194be8..4739d519d9 100644
--- a/tests/studio/playwright_chat_ui.py
+++ b/tests/studio/playwright_chat_ui.py
@@ -1100,6 +1100,22 @@ with sync_playwright() as p:
         plus_btn.click(force = True)
         page.wait_for_timeout(400)
         compare_item = page.get_by_role("menuitem", name = re.compile(r"Compare chat", re.I)).first
+        if compare_item.count() == 0:
+            # The plus menu was decluttered: Compare chat now lives in the
+            # "More" submenu; hover (then click as fallback) to open it.
+            more_trigger = page.get_by_role("menuitem", name = re.compile(r"^More$", re.I)).first
+            if more_trigger.count() > 0:
+                more_trigger.hover()
+                page.wait_for_timeout(400)
+                compare_item = page.get_by_role(
+                    "menuitem", name = re.compile(r"Compare chat", re.I)
+                ).first
+                if compare_item.count() == 0:
+                    more_trigger.click(force = True)
+                    page.wait_for_timeout(400)
+                    compare_item = page.get_by_role(
+                        "menuitem", name = re.compile(r"Compare chat", re.I)
+                    ).first
         if compare_item.count() > 0:
             compare_item.click(force = True)
             page.wait_for_timeout(800)

From 265c9f5db4489018fdc134a2ec5bf51dd15778fa Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:10:55 -0700
Subject: [PATCH 152/222] Fix UnboundLocalError in ROCm version detection
 dpkg/rpm fallback (#6149)

* Fix UnboundLocalError in _detect_rocm_version dpkg/rpm fallback

A leftover local import re inside the amd-smi branch made re function
local for the whole scope. When amd-smi and hipconfig are absent and
dpkg-query or rpm reports rocm-core, the epoch strip at the dpkg/rpm
fallback hit re.sub before any local binding existed and crashed the
installer with UnboundLocalError. Drop the local import (the module
already imports re at top level) and add a regression test covering the
dpkg path without hipconfig.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/install_python_stack.py            |  1 -
 tests/studio/install/test_rocm_support.py | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index eaab3f5559..0166bfd505 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -212,7 +212,6 @@ def _detect_rocm_version() -> tuple[int, int] | None:
                 env = _amd_smi_env(),
             )
             if result.returncode == 0:
-                import re
                 m = re.search(r"ROCm version:\s*(\d+)\.(\d+)", result.stdout)
                 if m:
                     return int(m.group(1)), int(m.group(2))
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 02f52e7700..973c0a1e81 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -485,6 +485,21 @@ class TestDetectRocmVersion:
                     result = _detect_rocm_version()
                     assert result == (6, 3)
 
+    def test_dpkg_fallback_without_hipconfig(self, tmp_path):
+        """dpkg rocm-core fallback works when amd-smi and hipconfig are absent
+        (regression: a shadowing local re import raised UnboundLocalError)."""
+
+        def which(cmd):
+            return "/usr/bin/dpkg-query" if cmd == "dpkg-query" else None
+
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = "1:6.3.0-1\n"
+        with patch.dict(os.environ, {"ROCM_PATH": str(tmp_path / "nonexistent")}):
+            with patch("shutil.which", side_effect = which):
+                with patch("subprocess.run", return_value = mock_result):
+                    assert _detect_rocm_version() == (6, 3)
+
     def test_empty_version_file(self, tmp_path):
         """Empty version file should return None."""
         info_dir = tmp_path / ".info"

From d75e765a6b4d13aeebdc995e3a692fa09dfb3209 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:11:26 -0700
Subject: [PATCH 153/222] Auto-set BNB_ROCM_VERSION from the installed wheel on
 Windows + ROCm (#5986)

* Auto-set BNB_ROCM_VERSION from the installed wheel on Windows + ROCm

bitsandbytes derives its ROCm backend DLL name from `torch.version.hip`.
AMD's Windows bitsandbytes prerelease wheel ships a single
`libbitsandbytes_rocm<NN>.dll` whose suffix does not always match the torch
HIP version: e.g. `torch==2.11.0+rocm7.13.0` reports HIP 7.13, so bitsandbytes
looks for `libbitsandbytes_rocm713.dll`, but the wheel only ships
`libbitsandbytes_rocm72.dll`. The names disagree, the native library fails to
load, and every 4-bit / 8-bit path breaks for users running `import unsloth`
directly (Unsloth Studio already works around this in its worker).

Detect the suffix from the actually-installed wheel and pin BNB_ROCM_VERSION
before bitsandbytes is first imported (unsloth_zoo.device_type imports it during
`from .models import *`), so the correct backend loads. This is precisely the
override bitsandbytes itself recommends when the build/runtime ROCm versions
differ.

Strict no-op unless ALL of: running on Windows, a ROCm torch build, the var is
unset, and a `libbitsandbytes_rocm*.dll` is actually installed. Linux ROCm is
untouched (its multi-backend bitsandbytes resolves the backend correctly from
torch.version.hip). Honors a user-provided BNB_ROCM_VERSION and an explicit
opt-out (UNSLOTH_SKIP_BNB_ROCM_VERSION=1).

Verified on an AMD Radeon 8060S (gfx1151, Strix Halo) Windows 11 + ROCm box:
`import unsloth` now auto-sets BNB_ROCM_VERSION=72 and a native 4-bit
quantize/dequantize roundtrip succeeds with the var unset; previously it failed
to load `libbitsandbytes_rocm713.dll`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Gate BNB_ROCM_VERSION on the actual torch build, not runtime hints

_is_rocm_torch_build() falls back to environment and filesystem hints
(HIP_PATH, ROCM_PATH, ...) that are routinely present on Windows boxes
with the AMD HIP SDK installed but a CUDA or CPU torch. If such a box
also has a bitsandbytes wheel that ships a rocm DLL (AMD's Windows
prerelease wheel ships rocm72 alongside all the cuda DLLs), setting
BNB_ROCM_VERSION makes bitsandbytes raise at import on its CUDA build
and `import unsloth` breaks.

Add _is_hip_torch_build(): wheel version tag first (no torch import),
then torch.version.hip for untagged custom/source HIP builds, and use
it as the gate. The broader hint-based helper keeps its other callers.

Verified on a gfx1151 Windows box: True on the ROCm venv
(2.11.0+rocm7.13.0), False on a torch-less interpreter; 4 new unit
tests including the HIP-SDK-on-CUDA-box false-positive regression.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Relocate wiring so this PR composes with the bnb arch-detection PR

Both this PR and the fix_bitsandbytes_rocm_arch_detection PR anchored
their _gpu_init.py wiring and import_fixes.py additions on the same
configure_amdgpu_asic_id_table_path lines, so whichever merged second
hit a textual conflict in both files (verified by merging both onto
main in each order).

Move maybe_set_windows_rocm_bnb_version's wiring to a self-contained
block after the import-order warning (still before `import
unsloth_zoo`, which is what pulls in bitsandbytes on ROCm) and append
the helpers at the end of import_fixes.py. The hunks no longer
overlap, so the two PRs merge cleanly in either order. No behavior
change: the env var only needs to be set before bitsandbytes is first
imported, and it still is.

* Redetect sitecustomize-seeded BNB_ROCM_VERSION for PR #5986

After #6048, every Studio venv process starts with BNB_ROCM_VERSION seeded
by the managed sitecustomize.py block, which made this gate a no-op inside
Studio venvs and blind to wheel updates. Treat values marked
UNSLOTH_BNB_ROCM_VERSION_SOURCE=sitecustomize as redetectable defaults,
stamp redetected values as detected, and keep the seeded value when no DLL
is found. Explicit caller values still win and the opt-out is unchanged.
Also merges latest main.

* Make BNB_ROCM_VERSION opt-out drop the sitecustomize-seeded default for PR #5986

UNSLOTH_SKIP_BNB_ROCM_VERSION=1 previously no-opped the helper but left a
sitecustomize-seeded BNB_ROCM_VERSION in the environment, so bitsandbytes
still consumed the override the user disabled. The opt-out now removes
values carrying the sitecustomize source marker; explicit user values have
no marker and are untouched. Adds tests for the opt-out paths and the
empty-string edge.

* Tighten comments and docstrings for PR #5986

Comment-only pass: shorten verbose docstrings on the internal helpers,
collapse multi-line inline comments, and drop wording that restates the
code. Verified code-identical via the comment_tools.py AST signature
check (3/3 files unchanged).

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 tests/test_windows_rocm_bnb_version.py | 251 +++++++++++++++++++++++++
 unsloth/_gpu_init.py                   |   7 +
 unsloth/import_fixes.py                |  88 +++++++++
 3 files changed, 346 insertions(+)
 create mode 100644 tests/test_windows_rocm_bnb_version.py

diff --git a/tests/test_windows_rocm_bnb_version.py b/tests/test_windows_rocm_bnb_version.py
new file mode 100644
index 0000000000..c8439b1fcd
--- /dev/null
+++ b/tests/test_windows_rocm_bnb_version.py
@@ -0,0 +1,251 @@
+# Unsloth - 2x faster, 60% less VRAM LLM training and finetuning
+# Copyright 2023-present Daniel Han-Chen, Michael Han-Chen & the Unsloth team. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+
+"""Tests for ``maybe_set_windows_rocm_bnb_version`` (unsloth/import_fixes.py).
+
+The module is loaded in isolation (stdlib + packaging only), so no torch /
+GPU is required and unsloth's GPU init never runs."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import types
+from pathlib import Path
+
+import pytest
+
+_IMPORT_FIXES_PATH = Path(__file__).resolve().parent.parent / "unsloth" / "import_fixes.py"
+
+
+def _load_import_fixes():
+    spec = importlib.util.spec_from_file_location(
+        "unsloth_import_fixes_under_test", _IMPORT_FIXES_PATH
+    )
+    module = importlib.util.module_from_spec(spec)
+    assert spec is not None and spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture()
+def import_fixes():
+    return _load_import_fixes()
+
+
+@pytest.fixture()
+def clean_env(monkeypatch):
+    """Unset the env vars and remove them afterwards (the function writes
+    os.environ directly, which monkeypatch does not auto-revert)."""
+    for var in (
+        "BNB_ROCM_VERSION",
+        "UNSLOTH_SKIP_BNB_ROCM_VERSION",
+        "UNSLOTH_BNB_ROCM_VERSION_SOURCE",
+    ):
+        monkeypatch.delenv(var, raising = False)
+    yield monkeypatch
+    for var in (
+        "BNB_ROCM_VERSION",
+        "UNSLOTH_SKIP_BNB_ROCM_VERSION",
+        "UNSLOTH_BNB_ROCM_VERSION_SOURCE",
+    ):
+        os.environ.pop(var, None)
+
+
+def _force(import_fixes, monkeypatch, *, win, rocm, detected):
+    monkeypatch.setattr(import_fixes.sys, "platform", "win32" if win else "linux")
+    monkeypatch.setattr(import_fixes, "_is_hip_torch_build", lambda: rocm)
+    monkeypatch.setattr(import_fixes, "_detect_installed_bnb_rocm_version", lambda: detected)
+
+
+# ---------------------------------------------------------------------------
+# _detect_installed_bnb_rocm_version
+# ---------------------------------------------------------------------------
+
+
+def test_detect_picks_highest_rocm_suffix(import_fixes, tmp_path, monkeypatch):
+    pkg = tmp_path / "bitsandbytes"
+    pkg.mkdir()
+    for name in (
+        "libbitsandbytes_rocm72.dll",
+        "libbitsandbytes_rocm713.dll",  # numerically highest -> should win
+        "libbitsandbytes_cpu.dll",
+        "__init__.py",
+    ):
+        (pkg / name).write_text("")
+    fake_spec = types.SimpleNamespace(submodule_search_locations = [str(pkg)])
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: fake_spec)
+    assert import_fixes._detect_installed_bnb_rocm_version() == "713"
+
+
+def test_detect_none_when_only_non_rocm_dlls(import_fixes, tmp_path, monkeypatch):
+    pkg = tmp_path / "bitsandbytes"
+    pkg.mkdir()
+    (pkg / "libbitsandbytes_cpu.dll").write_text("")
+    (pkg / "libbitsandbytes_cuda124.dll").write_text("")
+    fake_spec = types.SimpleNamespace(submodule_search_locations = [str(pkg)])
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: fake_spec)
+    assert import_fixes._detect_installed_bnb_rocm_version() is None
+
+
+def test_detect_none_when_bnb_absent(import_fixes, monkeypatch):
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+    assert import_fixes._detect_installed_bnb_rocm_version() is None
+
+
+# ---------------------------------------------------------------------------
+# maybe_set_windows_rocm_bnb_version
+# ---------------------------------------------------------------------------
+
+
+def test_sets_bnb_version_on_windows_rocm(import_fixes, clean_env):
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() == "72"
+    assert os.environ["BNB_ROCM_VERSION"] == "72"
+    assert os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] == "detected"
+
+
+def test_noop_off_windows(import_fixes, clean_env):
+    # Linux ROCm resolves its backend correctly from torch.version.hip.
+    _force(import_fixes, clean_env, win = False, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert "BNB_ROCM_VERSION" not in os.environ
+
+
+def test_noop_when_not_rocm_torch(import_fixes, clean_env):
+    _force(import_fixes, clean_env, win = True, rocm = False, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert "BNB_ROCM_VERSION" not in os.environ
+
+
+def test_noop_when_no_rocm_dll_installed(import_fixes, clean_env):
+    # Never force a ROCm backend name when no ROCm DLL ships (avoid breaking a
+    # non-ROCm bitsandbytes that happens to sit next to a ROCm torch build).
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = None)
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert "BNB_ROCM_VERSION" not in os.environ
+
+
+def test_respects_user_provided_value(import_fixes, clean_env):
+    clean_env.setenv("BNB_ROCM_VERSION", "999")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert os.environ["BNB_ROCM_VERSION"] == "999"
+
+
+def test_explicit_opt_out(import_fixes, clean_env):
+    clean_env.setenv("UNSLOTH_SKIP_BNB_ROCM_VERSION", "1")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert "BNB_ROCM_VERSION" not in os.environ
+
+
+def test_redetects_sitecustomize_seeded_default(import_fixes, clean_env):
+    # Studio's installer persists a default via the venv sitecustomize.py; the
+    # wheel may have changed since, so the seeded value must be redetected.
+    clean_env.setenv("BNB_ROCM_VERSION", "72")
+    clean_env.setenv("UNSLOTH_BNB_ROCM_VERSION_SOURCE", "sitecustomize")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "713")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() == "713"
+    assert os.environ["BNB_ROCM_VERSION"] == "713"
+    assert os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] == "detected"
+
+
+def test_sitecustomize_default_kept_when_no_dll_found(import_fixes, clean_env):
+    # A failed redetect must not discard the seeded value.
+    clean_env.setenv("BNB_ROCM_VERSION", "72")
+    clean_env.setenv("UNSLOTH_BNB_ROCM_VERSION_SOURCE", "sitecustomize")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = None)
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert os.environ["BNB_ROCM_VERSION"] == "72"
+    assert os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] == "sitecustomize"
+
+
+def test_user_value_with_non_sitecustomize_marker_untouched(import_fixes, clean_env):
+    # Only the sitecustomize marker makes a value redetectable.
+    clean_env.setenv("BNB_ROCM_VERSION", "999")
+    clean_env.setenv("UNSLOTH_BNB_ROCM_VERSION_SOURCE", "detected")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert os.environ["BNB_ROCM_VERSION"] == "999"
+
+
+def test_opt_out_unseats_sitecustomize_seeded_value(import_fixes, clean_env):
+    # The opt-out must also drop a default our own sitecustomize block seeded,
+    # so bitsandbytes never sees the override the user disabled.
+    clean_env.setenv("BNB_ROCM_VERSION", "72")
+    clean_env.setenv("UNSLOTH_BNB_ROCM_VERSION_SOURCE", "sitecustomize")
+    clean_env.setenv("UNSLOTH_SKIP_BNB_ROCM_VERSION", "1")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "713")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert "BNB_ROCM_VERSION" not in os.environ
+    assert "UNSLOTH_BNB_ROCM_VERSION_SOURCE" not in os.environ
+
+
+def test_opt_out_keeps_explicit_user_value(import_fixes, clean_env):
+    # Opt-out must never remove a value the user set themselves (no marker).
+    clean_env.setenv("BNB_ROCM_VERSION", "999")
+    clean_env.setenv("UNSLOTH_SKIP_BNB_ROCM_VERSION", "1")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert os.environ["BNB_ROCM_VERSION"] == "999"
+
+
+def test_empty_string_value_without_marker_is_respected(import_fixes, clean_env):
+    # "" counts as present: without the sitecustomize marker it is not ours
+    # to overwrite.
+    clean_env.setenv("BNB_ROCM_VERSION", "")
+    _force(import_fixes, clean_env, win = True, rocm = True, detected = "72")
+    assert import_fixes.maybe_set_windows_rocm_bnb_version() is None
+    assert os.environ["BNB_ROCM_VERSION"] == ""
+
+
+# ---------------------------------------------------------------------------
+# _is_hip_torch_build (the strict gate -- regression for the HIP-SDK-on-a-
+# CUDA-box false positive: env hints like HIP_PATH must NOT count)
+# ---------------------------------------------------------------------------
+
+
+def _fake_torch(hip):
+    return types.SimpleNamespace(version = types.SimpleNamespace(hip = hip))
+
+
+def test_hip_build_true_from_wheel_tag(import_fixes, monkeypatch):
+    monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "2.11.0+rocm7.13.0")
+    assert import_fixes._is_hip_torch_build() is True
+
+
+def test_hip_build_true_from_torch_version_hip(import_fixes, monkeypatch):
+    # Custom/source HIP build without the +rocm tag.
+    monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "2.11.0")
+    monkeypatch.setitem(__import__("sys").modules, "torch", _fake_torch("7.2.0"))
+    assert import_fixes._is_hip_torch_build() is True
+
+
+def test_hip_build_false_for_cuda_torch_despite_rocm_env_hints(import_fixes, monkeypatch):
+    """HIP SDK env vars set but CUDA torch: the strict gate must say False,
+    otherwise BNB_ROCM_VERSION gets set and CUDA bitsandbytes raises."""
+    monkeypatch.setenv("HIP_PATH", r"C:\Program Files\AMD\ROCm\6.2")
+    monkeypatch.setenv("ROCM_PATH", r"C:\Program Files\AMD\ROCm\6.2")
+    monkeypatch.setattr(import_fixes, "importlib_version", lambda name: "2.9.0+cu126")
+    monkeypatch.setitem(__import__("sys").modules, "torch", _fake_torch(None))
+    assert import_fixes._is_hip_torch_build() is False
+
+
+def test_hip_build_false_when_torch_absent(import_fixes, monkeypatch):
+    def _raise(name):
+        raise Exception("no torch dist")
+
+    monkeypatch.setattr(import_fixes, "importlib_version", _raise)
+    monkeypatch.setitem(__import__("sys").modules, "torch", None)
+    assert import_fixes._is_hip_torch_build() is False
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index a7b8ac594c..ede97ce68e 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -96,6 +96,13 @@ if already_imported:
     )
 del already_imported, critical_modules
 
+# Pin BNB_ROCM_VERSION before bitsandbytes is first imported (`import
+# unsloth_zoo` below pulls it in on ROCm hosts).
+from .import_fixes import maybe_set_windows_rocm_bnb_version
+
+maybe_set_windows_rocm_bnb_version()
+del maybe_set_windows_rocm_bnb_version
+
 # Multi-GPU is not yet supported (beta available on request).
 
 # Fixes https://github.com/unslothai/unsloth/issues/1266
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 25f5fdb9d2..0622f73965 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -2162,3 +2162,91 @@ def disable_broken_causal_conv1d():
         "Unsloth: Detected broken causal_conv1d binary; "
         "disabling causal_conv1d fast path and continuing import."
     )
+
+
+_BNB_ROCM_DLL_RE = re.compile(r"libbitsandbytes_rocm(\d+)\.dll", re.IGNORECASE)
+
+
+def _is_hip_torch_build():
+    """True only when torch itself is a HIP/ROCm build. Env hints (HIP_PATH
+    etc.) do not count: CUDA bitsandbytes raises at import when the ROCm
+    override is set. Wheel tag first (no torch import); torch.version.hip
+    fallback for source builds."""
+    try:
+        if "rocm" in str(importlib_version("torch")).lower():
+            return True
+    except Exception:
+        pass
+    try:
+        import torch
+        return bool(getattr(torch.version, "hip", None))
+    except Exception:
+        return False
+
+
+def _detect_installed_bnb_rocm_version():
+    """Highest installed ``libbitsandbytes_rocm<NN>.dll`` suffix ("72", "713")
+    or ``None``. Listing order is unordered, so take the numeric max."""
+    try:
+        spec = importlib.util.find_spec("bitsandbytes")
+    except Exception:
+        return None
+    if spec is None or not spec.submodule_search_locations:
+        return None
+
+    suffixes = []
+    for pkg_dir in spec.submodule_search_locations:
+        try:
+            entries = os.listdir(pkg_dir)
+        except Exception:
+            continue
+        for entry in entries:
+            match = _BNB_ROCM_DLL_RE.fullmatch(entry)
+            if match is not None:
+                suffixes.append(match.group(1))
+    if not suffixes:
+        return None
+    return max(suffixes, key = lambda value: int(value))
+
+
+def maybe_set_windows_rocm_bnb_version():
+    """Pin ``BNB_ROCM_VERSION`` from the installed wheel on Windows + ROCm torch.
+
+    AMD's Windows wheel ships one ``libbitsandbytes_rocm<NN>.dll`` whose
+    suffix can disagree with ``torch.version.hip`` (HIP 7.13 vs rocm72.dll),
+    breaking the native 4-bit/8-bit paths. Pin the installed suffix before
+    bitsandbytes is first imported.
+
+    No-op unless ALL of: Windows, a real HIP torch build (env hints like
+    HIP_PATH do not count), a ROCm DLL installed, and no explicit user value.
+    Linux is untouched. Values seeded by Studio's venv sitecustomize.py
+    (marked ``UNSLOTH_BNB_ROCM_VERSION_SOURCE=sitecustomize``) are
+    redetectable defaults, not overrides; ``UNSLOTH_SKIP_BNB_ROCM_VERSION=1``
+    opts out and drops a seeded default. Returns the value set, else None.
+    """
+    if sys.platform != "win32":
+        return None
+    if os.environ.get("UNSLOTH_SKIP_BNB_ROCM_VERSION") == "1":
+        # Real opt-out: drop our seeded default (marker present); explicit
+        # user values carry no marker and are kept.
+        if os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize":
+            os.environ.pop("BNB_ROCM_VERSION", None)
+            os.environ.pop("UNSLOTH_BNB_ROCM_VERSION_SOURCE", None)
+        return None
+    if "BNB_ROCM_VERSION" in os.environ and (
+        os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") != "sitecustomize"
+    ):
+        return None
+    if not _is_hip_torch_build():
+        return None
+    version = _detect_installed_bnb_rocm_version()
+    if version is None:
+        return None
+    os.environ["BNB_ROCM_VERSION"] = version
+    os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
+    if UNSLOTH_ENABLE_LOGGING:
+        logger.info(
+            f"Unsloth: set BNB_ROCM_VERSION={version} "
+            "(detected from the installed bitsandbytes ROCm wheel on Windows)."
+        )
+    return version

From 8129994061377c4c7d4868fa1a73226e8251cbb9 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:12:54 -0700
Subject: [PATCH 154/222] Call patch_compiling_bitsandbytes on the
 FastLanguageModel path (#6144)

* Call patch_compiling_bitsandbytes on the FastLanguageModel dispatch path

* Guard the FastLanguageModel patch call so an old unsloth_zoo cannot crash loads
---
 unsloth/models/loader.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 67d1ce9b8d..0ee9e49ba1 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -722,6 +722,14 @@ class FastLanguageModel(FastLlamaModel):
             load_in_4bit_kwargs = False
             load_in_8bit_kwargs = False
 
+        # Mirror FastModel: bitsandbytes < 0.46.0 needs dynamo disabled.
+        # Best effort: never crash the load (old unsloth_zoo without the
+        # zoo #710 fix raises NameError here on Python 3.13).
+        try:
+            patch_compiling_bitsandbytes()
+        except Exception as e:
+            print(f"Unsloth: Could not patch bitsandbytes for torch.compile - {e}")
+
         model, tokenizer = dispatch_model.from_pretrained(
             model_name = model_name,
             max_seq_length = max_seq_length,

From 18d851bfebd43d4b39de16e5f31d5c8b5b9bb50f Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:22:17 -0700
Subject: [PATCH 155/222] Studio: mascot images degrade gracefully instead of
 showing alt text (#6146)

* Studio: mascot images degrade gracefully instead of showing alt text

Mascots loaded from raw public-folder URLs with no error handling, so a
missing or unreachable file (version skew during updates, subpath
mounts, transient blips) painted the alt text, like the empty mascot on
the training start overlay. A shared MascotImg now resolves against
BASE_URL, retries once with a cache-buster, then swaps to a 4 KB
fallback sloth bundled as a data URI that cannot 404. Applied to the
chat greeting, 404 page, training start overlay, auth form, onboarding
splash and wizard.

* Reset mascot retry state via key remount instead of render-time tracking

* Use MascotImg for the artifact generating panel sloth
---
 studio/frontend/src/app/router.tsx            |   7 +--
 studio/frontend/src/asset-queries.d.ts        |   9 +++
 .../frontend/src/assets/mascot-fallback.webp  | Bin 0 -> 4374 bytes
 .../src/components/assistant-ui/thread.tsx    |   6 +-
 studio/frontend/src/components/mascot-img.tsx |  54 ++++++++++++++++++
 .../features/auth/components/auth-form.tsx    |   6 +-
 .../chat/artifacts/artifact-surface.tsx       |   6 +-
 .../onboarding/components/splash-screen.tsx   |  10 ++--
 .../onboarding/components/wizard-content.tsx  |  13 +++--
 .../studio/training-start-overlay.tsx         |   7 +--
 10 files changed, 88 insertions(+), 30 deletions(-)
 create mode 100644 studio/frontend/src/asset-queries.d.ts
 create mode 100644 studio/frontend/src/assets/mascot-fallback.webp
 create mode 100644 studio/frontend/src/components/mascot-img.tsx

diff --git a/studio/frontend/src/app/router.tsx b/studio/frontend/src/app/router.tsx
index dbb74ee1a1..5c18e637e2 100644
--- a/studio/frontend/src/app/router.tsx
+++ b/studio/frontend/src/app/router.tsx
@@ -3,6 +3,7 @@
 
 import { Link, createRouter, useRouterState } from "@tanstack/react-router";
 import { Button } from "@/components/ui/button";
+import { MascotImg } from "@/components/mascot-img";
 import { useT } from "@/i18n";
 import { Route as rootRoute } from "./routes/__root";
 import { Route as dataRecipesRoute } from "./routes/data-recipes";
@@ -41,11 +42,7 @@ function DefaultNotFound() {
 
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-4 p-8 text-center">
-      <img
-        src="/Sloth%20emojis/sloth%20shy%20large.png"
-        alt="Sloth mascot"
-        className="size-24"
-      />
+      <MascotImg src="Sloth emojis/sloth shy large.png" className="size-24" />
       <div className="flex flex-col items-center gap-1">
         <h1 className="font-heading font-semibold text-2xl tracking-tight">
           {t("shell.notFound.title")}
diff --git a/studio/frontend/src/asset-queries.d.ts b/studio/frontend/src/asset-queries.d.ts
new file mode 100644
index 0000000000..2c7a1cd936
--- /dev/null
+++ b/studio/frontend/src/asset-queries.d.ts
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// Vite `?inline` imports (data URIs); vite/client only types bare extensions.
+declare module "*?inline" {
+  const src: string;
+  // biome-ignore lint/style/noDefaultExport: Vite asset modules export default.
+  export default src;
+}
diff --git a/studio/frontend/src/assets/mascot-fallback.webp b/studio/frontend/src/assets/mascot-fallback.webp
new file mode 100644
index 0000000000000000000000000000000000000000..ad50361dbbdfbd483f0eb92fbe49b5c7628a81a1
GIT binary patch
literal 4374
zcmV+x5$WzyNk&Ev5dZ*JMM6+kP&il$0000G0001A003M706|PpNFoFP00E$F+m<2Q
znh`6mZQHhO+qP}nwr$(CZCl4?MXWU+s%~aseLzG^0D3b-V9`@v`D;X<d!`NnAq4m;
zz*<j@X3HDXxB)<rB%vol6iF>bL{dr;AeinRl0}VKUj={|&@7?LVoDM1j9C76YB7>j
zzIoy!?|=KlcON}|-X>E5v5R6t^Z2tYv%&T|?RxCRH{JixL-${M>h3Geh?R#iv#otD
zo(8d7Bm$Uw$17g@V>D|I|8yt|D_Sl^RZGc*{B1GBt`Go=oc_^RHd`sVvXL~l*&6(9
zvJg5KBe2B_g=EP^jkQgU?Qd{vq>c%&;kzWW8oR%6tIi2#eUQ{*>_z3EsY2*Xh}ga#
zRoSCOcffe)XoxtM%<Nekd(7lO>_CXPg+<xZe;kyM+7<-2vBBOh<OeGu#5M^|XM??N
znR-Tmv_-Hyv-KQVj4w_PX-A4TGSkJ(pBF)D!#KF#3uX>j7E&wWpb=_LuyD}QkQxa`
zkw!NQ|C<f5Qo{bsMn^M08c#w6!P-`gu4Y~i`M-$S`kT_(%#|Unf{gnC3%xD;P-3fu
z%bDqK;igDUf;E}xk-dZnAjI*1pn7B+I|m{lIDwfi7w&?D7^WYh=2Nx{kRZ5}nNIOC
zq=@N<nmMIq14zP2%=B6LF#^IkKT(}B8#NyyR;SYI%rlX2xn;MM-%5y|QQe|(Da<vB
z=2zy4*pf!S3tz&SERGrbOmUBSM&l~C)3w5bR~=*K+I85C>X`D`un)6qpWt5CjK9V&
zsjl^zc^J*L!E4g!+d(Y8{dc8zKRiSAO!@j3z7@OvPnu`S?FYG*t<U5`Ju`A=^mR<_
z*|iXV^^D779K22S$~bBkiMZa1SIW;r0CuK&m3b2qFzp~UrwX@g!lfLerI<g)5z`|8
zaf<KQZ0=+}jR+uO#@oJpbH7tqyeZrg0ssNc<Ns;ui_zvmY(fx(@vtY0H^ZhwXwfpJ
zS6Ez8eiu=B99+)qO14{&st68Xp{vR@Ar%BmWi?j{KZp?(WBP=Jo?7P0kO~RAGt<=u
zPluplkT0!xVwpEWLIuHcH2P_oya+L%V#4XnZdfM!?SvRmHR4$oCoGeV8)t@~X84Bc
zgONjSS`-je518ODCzSskG7BI9wI=?L=7HL%<p7DO9Wc(XR0mXbV~iWn&VYAVdaqEo
zK|*^IuCUy5nWHvELYoCEQ+uow{;?7g+8)C@EWJfOG6NFYFIYy4_K@idn*)MQ3ihLw
z-YK>t#tG=GVBgGAtc9s{nc1j?5jzCIitmxMl8dtY3*Q$B9fBZi{nS7<H@+T5>n>&<
z0qGPXfT>s9ZjYVTnQP*|s9k0{bfyqHg&+~F=g71!W9BW8jsXagQW`g|L}S-$V==@o
zXqm7zOZR2o4QUTnP&gpQ3;+OdF#w$bDqsLz06uLhkwv5;p_mIE;6Mh%v;bY5396qY
zGf&2Q!eFlVXDanKw$sc%oCl*{^gH9;fE_D8;;>bGym$Ba?+<)6`up5JTP&gVaj9p=
z{{?=-`yZdb>HHh`d;KS<N34I%Z$R14^<JP}$NfA0C-wgrkLf)P`n~>-+za(z{il@o
zhW!A)m49dd$^JjxpZRb6Kjr-Nerx_S{@3|GfUo91)BoOoc>g2sP3)ug%h_Z01OKCz
zzk~ma!mNkwdb^67toH$ciW%%;w{9{ayfL}omy)T>4&4y#EBCpO)|{|J2k5CSP=A83
z;aj*gqSYk8>Gb@n>0~rtywLwV>nQP-8$-E$gA)cRH8arbRIG2|EvVC)Os=<Y3ZKn$
zuvO02rK6*aF`v~X_Y>6NDDNT)V$eALo_&dRXX!x72a+VF6<WwR7e?7<KYK4ubrZYn
z&LI=d@6|_9d<a2&^1S_hOcl5dLi3s<1gXFU`$*^0O#(FKjTUzk<&T46+Ci^xbeOze
zAP`-NqbL9X{{O?{A5)4f+O-|Dx@FjKyK}ar7PFV`-jDtJID0Iv4odxobv$!qSoypO
zPAj)7234BtO-pgALRKc^8ESPzt2SW<<>Lk!Kh&#C`DN#YK2_i}o~qL~dIfpoTfSD|
zl7XD56TwV`|8z4VIEn!T#p1-8$c)J$pdi!ceme81|5;%R!GS}r1TBFsltdBBNcvZB
zY^vowuC(``3;<5n`7>xHMj6Cy0fwBGrykV*jin4`r2U)l5&CF2Z{nW&OKC=BbEr(p
zso85X#-Ci@CreX(+r!}umA(Mc{MdC}5ygy(CTj(WQxXu0696SH=mZt$4{f<bsx|rg
zNLk^y`)<`qZ@gcO{+{kf$Kc3!jecS}a$$T00Eo_VbI3(Qere375c-qIkJJ)uX}VSj
zIfHfA{H1zb&misG`le*jvGE9JgY$`!Dw<E1K+KkifcV<Tzh^GP-j+{vi<?prY32VW
z_xjz`LzBj*BH^5_M}$DedKi~VY*Ceg1twcMI6nKz`8LH{)ATW~iFdd+$Xe`MeNUJ<
zt<=yk&$Nm(UuIuogM>OxMNs9j#7pdKl0!q}I6{o`r*{wm`I{6?{>-()>%IZ&(5m<Q
zK+6F}%ZAw}K<w{QGRwHD*^8R?aw1pyu$+H)y?#Leogridmwlr`zHdkzs~qCXy#zZm
z4xzoCBaA{Z{^_dpH?;0PP%0`yLb)cr#i-xBVnltP`9VaS9x#|38-pe3Csr^yMzkGv
zo2;q>4m7^|vB{|t_?9azbwAue@0Sm!oa1CxC08VaSN!8gfMxbBzJ!DJa`L5kdam~=
zh8FJ06t^m?t>rL!WjrtG6QYnJ-Q<kXLY0X3;I4R~_1LaOVVXctIlvm~sy69vQkGOe
zHL(I;Z_zbP1&RKTLAE*N$nM%QeVu!s*Wz?pX(<ZeXwT*HhkKZ?HQfzouho}eD;uk@
zDI?ywHke#O(16w1-ug>i=yge?mGzU4V6VK>8bjuKnWI{CcAvMp@a2|vJla%<Xu8A+
zl8ERLFUjbDB)T@&&;{*Y0#q|CA7IBrWHm~i>dy)On4kRij;4IS+ql_558lRS2CCB#
zo8(A@2RV{dLV<qOa%M!-`se{9Jw=4Q&rbdxoRM<F*gMPyP(EcFF7E|kROuIB8MXHo
zp}%=B9rlHNR}wkSohP5<1E))sOeDj&$oc)z5gb1^{~e@Z@o)dvo=O)}SLLt1D0mje
z^WQE`yR2URgf}{C{)|_jQVp&oItvc5IbX7W6W_bzfvth*-b+9wK-gp&zURM;vJGOW
z&ks$ZT*a;@k9vyx$Ty)jh2@$uh`&UVTlZ$uT4T1+KW+7nf>Y1QEpX!Mh(T>ZHhetU
zVvF&irJQ=gxy+gbZw%5MByVR#kgI$?uCX-z4R09{SlF$XYAb*~{+NiNuQyYmRJguw
z`3kp1@yz6H0`o=@R@ZU=e6xdU728F*)rFTVo_s-o8c=+-L<g#++wbL`jI$V^&1n8i
zJp_w-9_=XCI&WZIc!1U*vD$`Ifw1_tYix%5$E*@0i!kJlZN%|VK4kF$np@xuB6N8w
z|8cVQd#rn7sDK<ZO)i8)_=3?X7+7jugMAp5g8gT8efoz-Pqxw@-w{z7U|yHmMxwmB
ztWDF`wl^^{q4Iqx;ludt2!B5{Jq%1HnDrXAll*SI$0ASKI46Q^<Qj!_7!a<>TcWb<
zZ}rv5(;C3A#`n)6<VHsVQZ`KLj-CJyl{27!8Y^?3c#0<eWB~uywIKlvD!oKYKTA#X
zf(GNN7g?fXDIZpkPG{gGk@0tQs{Jy{LNGOG1$3^>e2eWTd0><2zQ-|RgEZyn5WlUD
z#ZzAc@twjBFq}Dr5Wt1`k#j0T^i?>h;-wMIUXaQ1`_k$Y<TkG*v#f2jRk#ecGu@i4
z=O<qLf<_gHDnBQol$)lR-u7fb1EDC)jr+|}*^t|YOH&Z<_-|v9ml4?)x*VFA{d*}O
zAGib*i0U7Fm?YVExOSypg$l>M`8_>ajQAsSt(j{$=k#<B{{qE<t=)|KwuExRf6Eid
zJ~^gwrf{I%0R{iFcW~Dui8u`>+J0WYe{S#<!kV}5WwoKjKonnl=JCN`;j^XNV!Ben
zKe}Fw5?;VhNoNJ6LLLF>hN>63Q$z565a`@>a4UP6i%1rx2Va18`v9s9QwUyB*o#%p
zZk}IXbfh-{U)9$GNbsOU(qA7m$YuO1HInC_9ZOkdNTib&a;aK=3B&nHXUlx_(2St!
zSy$E*y98mhmzh+#_iRfc9f;Jqjt2aoaqod{2g8*qocTL^{Ot0F(W*0q`5N!bRvyIi
zytfP@N!_(s=t_1_S&I6Q8_^Pag&IK*1KVbW`4yGp+1&X-&)T>CKj3yMeur+X6qJcx
z?t6}qgvv*WE}sAC%>Y@~ahl>2lk#Um!f6yzeTqD<P1=C(AcnUO^Hzxc_7zaF!*DQC
z9clho%5E-dWPMsWCTJ>!X4~$p=4sXsn#xk=3n)P@myjew|25GLp;1qW(6Fje3wn;=
zrn5OXk`e>y4CR>i6kz`y;7)X|JO*RpYmO?j&LCY)T4U{)7^^O^TQ<#gL`{2Fy3TIz
zR4M&>__GHDUnu7s2}2(`U~|{xX`rA?rG;{pqJ$97+PbcPiU*v20;I9Lf%i)7E_-6r
zXU+8nD>+&g3keT=zY?cV=~2WZ+v!&QW4^)N{uO`CHev?mSGMCLPF*^>$?&yXP@Bsi
zF|8Rbry1oFqW#pl!w^TbJHk8la*U@(s+U?bdmm*!5i8`>t<V%a)mO?E#ic(d<)O5)
znrLHCb<QqRNV>Y52#?s0fo^xnk$OGl4=)wxRKWGj8)p0Xx6~AW*C7B#xatCENGqUv
zzW_th-51N0;2lCxm-vIzTgWl}{jp`)R0mlEjED5!h!nk=Xef3r#O(cfVl&;h9%&}9
zqt;sseTMHNXAZU?{O3AoJR@4VIt9q@OFcPNLwKJIDIF0Dh`_(x&>}e$*kJ%XT04nq
zBpvYLND0;tZr%w_?x|0>%U4Fp(%A-fc-FQ9q`=2#QU5fj&0HStB?!HE$`n4Z)9wQ?
zBe*8A>|@+~4p?vY<NRe>DDV}u7Caa&d<;Xuay$@%0@wecIB>>gD+gw0L0R(I#ZOr|
zzG^@QSP&Dq+{jA;^}=c6PcFJH0OLxf2uyo{+&}C(Xv|B9w=sVNg!gxU`8%NXzv&af
zT&`!tH)_nJpkXmJcmdB`YgEGgfklNi)+*C*AgQ%1EQa#s<zWu=k|<@oCLvhqJH6Jk
zBTRh5_=QZX%IA0=2A(O@g0m^Bzg2w&Oaf)zk-bc<M}0lR{V5}BVlnOOVjms=%vDgK
zi-0Msye&NW)H;dw&Ov(_9==Svwn@Po{mS?H`K$Wr5;bhCIof2+!(e|{-}pr?)SV6s
zer?^aEi<nxIAYH*M;T{SqP*j|@8!#H?HM|TMC$Df??$2=Wm&bu8t7BvN~(W|TS`Rb
zyZ9Ehbd0<b5QP?T-Cvpalve$;h>eM1*Os8x77VGko698Kzb5PA;Y9}5FI(JN9dkgJ
zgo6|#)k57uG9On(Ly`8HVuL!Ccq;Sf$NzXT2u9LLfr9-rsrd^;p+4}>Vf?Z6zc><V
z0C=HV1rI*Vnk6MWzSbpB#C1mf;28}`qa@OjI9t_KGXag^%HF$9P_)mlxv+rh`nlKT
zlthOA_x1UZtU(YnX6rTbwg|iX`Ls8kw|T)61{D;_y$l8g$}?ZDg#xM9(zP;&)#|93
Q<AR_!$Ml)61uy^r0KPDQkpKVy

literal 0
HcmV?d00001

diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index ea660f7af8..3763370dcd 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -36,6 +36,7 @@ import {
   useScrollThreadToBottom,
 } from "@/components/assistant-ui/use-intent-aware-autoscroll";
 import { Button } from "@/components/ui/button";
+import { MascotImg } from "@/components/mascot-img";
 import { Spinner } from "@/components/ui/spinner";
 import {
   DropdownMenu,
@@ -781,7 +782,7 @@ const ThreadWelcome: FC<{
     setWelcome(buildWelcome(new Date().getHours(), name));
   }, [displayName]);
 
-  const currentEmojiSrc = `/Sloth emojis/${welcome.sloth}`;
+  const currentEmojiSrc = `Sloth emojis/${welcome.sloth}`;
 
   return (
     <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col">
@@ -789,9 +790,8 @@ const ThreadWelcome: FC<{
         <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-9 px-4">
           {/* Center the greeting (sloth + title) over the composer. */}
           <div className="flex flex-row items-center justify-center gap-[15px]">
-            <img
+            <MascotImg
               src={currentEmojiSrc}
-              alt="Sloth mascot"
               className="size-[44px] -translate-y-[2px]"
             />
             <h1 className="aui-thread-welcome-message-inner unsloth-welcome-title fade-in slide-in-from-bottom-1 animate-in text-3xl tracking-[-0.02em] duration-200">
diff --git a/studio/frontend/src/components/mascot-img.tsx b/studio/frontend/src/components/mascot-img.tsx
new file mode 100644
index 0000000000..cff4d54c4d
--- /dev/null
+++ b/studio/frontend/src/components/mascot-img.tsx
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { type ComponentProps, useState } from "react";
+
+// Bundled as a data URI so the fallback ships inside the JS bundle and can
+// never 404, unlike the public-folder originals.
+import fallbackMascot from "@/assets/mascot-fallback.webp?inline";
+
+const LEADING_SLASH = /^\//;
+
+// Resolve a public-folder asset against the deploy base (subpath mounts) and
+// encode the spaced sloth filenames.
+export function publicAssetUrl(path: string): string {
+  return encodeURI(import.meta.env.BASE_URL + path.replace(LEADING_SLASH, ""));
+}
+
+type MascotImgProps = { src: string } & Omit<
+  ComponentProps<"img">,
+  "src" | "onError"
+>;
+
+// Keying on src remounts the inner component, so the retry state resets
+// whenever the source changes (greeting sloths rotate).
+export function MascotImg(props: MascotImgProps) {
+  return <MascotImgInner key={props.src} {...props} />;
+}
+
+type Stage = "primary" | "retry" | "fallback";
+
+// Decorative mascot that degrades gracefully: a failed load retries once with
+// a cache-buster (transient blips, stale caches), then swaps to the bundled
+// fallback sloth. Empty alt by default so a broken image never paints text.
+function MascotImgInner({ src, alt = "", ...rest }: MascotImgProps) {
+  const [stage, setStage] = useState<Stage>("primary");
+
+  const url = publicAssetUrl(src);
+  const effectiveSrc =
+    stage === "primary"
+      ? url
+      : stage === "retry"
+        ? `${url}${url.includes("?") ? "&" : "?"}retry=1`
+        : fallbackMascot;
+
+  return (
+    <img
+      draggable={false}
+      {...rest}
+      src={effectiveSrc}
+      alt={alt}
+      onError={() => setStage((s) => (s === "primary" ? "retry" : "fallback"))}
+    />
+  );
+}
diff --git a/studio/frontend/src/features/auth/components/auth-form.tsx b/studio/frontend/src/features/auth/components/auth-form.tsx
index f2017ff0b6..d109b5f196 100644
--- a/studio/frontend/src/features/auth/components/auth-form.tsx
+++ b/studio/frontend/src/features/auth/components/auth-form.tsx
@@ -3,6 +3,7 @@
 
 import { apiUrl } from "@/lib/api-base";
 import { Button } from "@/components/ui/button";
+import { MascotImg } from "@/components/mascot-img";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Link, useNavigate } from "@tanstack/react-router";
@@ -311,9 +312,8 @@ export function AuthForm({ mode }: AuthFormProps): ReactElement | null {
   return (
     <div className="w-full max-w-sm space-y-6">
       <div className="space-y-1.5 text-center">
-        <img
-          src="/Sloth emojis/large sloth wave.png"
-          alt="Unsloth waving mascot"
+        <MascotImg
+          src="Sloth emojis/large sloth wave.png"
           className="mx-auto mb-2 h-20 w-20 object-contain"
         />
         <h2 className="text-2xl font-semibold text-foreground">{title}</h2>
diff --git a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
index a685515253..22066b6fc3 100644
--- a/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
+++ b/studio/frontend/src/features/chat/artifacts/artifact-surface.tsx
@@ -9,6 +9,7 @@ import {
   unslothDarkTheme,
   unslothLightTheme,
 } from "@/components/assistant-ui/code-themes";
+import { MascotImg } from "@/components/mascot-img";
 import { Button } from "@/components/ui/button";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { cn } from "@/lib/utils";
@@ -78,9 +79,8 @@ function ArtifactGeneratingPanel() {
   return (
     <div className="flex h-full min-h-0 flex-col items-center justify-center bg-muted/10 px-6 text-center">
       <div className="max-w-[30ch] space-y-1.5">
-        <img
-          src="/Sloth%20emojis/sloth%20w%20pc%20transparent.png"
-          alt=""
+        <MascotImg
+          src="Sloth emojis/sloth w pc transparent.png"
           aria-hidden={true}
           className="mx-auto mb-3 size-20 object-contain"
         />
diff --git a/studio/frontend/src/features/onboarding/components/splash-screen.tsx b/studio/frontend/src/features/onboarding/components/splash-screen.tsx
index 70438a04d8..47d9c25efe 100644
--- a/studio/frontend/src/features/onboarding/components/splash-screen.tsx
+++ b/studio/frontend/src/features/onboarding/components/splash-screen.tsx
@@ -3,6 +3,7 @@
 
 import { Button } from "@/components/ui/button";
 import { Card } from "@/components/ui/card";
+import { MascotImg } from "@/components/mascot-img";
 import { motion } from "motion/react";
 
 interface SplashScreenProps {
@@ -19,10 +20,7 @@ export function SplashScreen({
       <Card className="w-full max-w-md px-8 py-8 shadow-border ring-1 ring-border">
         {/* Mascot */}
         <div className="flex justify-center">
-          <motion.img
-            src={`${import.meta.env.BASE_URL}Sloth emojis/Sloth loca pc.png`}
-            alt="Sloth mascot"
-            className="size-30"
+          <motion.div
             initial={{ opacity: 0, y: 40, scale: 0.95 }}
             animate={{ opacity: 1, y: 0, scale: 1 }}
             transition={{
@@ -31,7 +29,9 @@ export function SplashScreen({
               bounce: 0.3,
               delay: 0.1,
             }}
-          />
+          >
+            <MascotImg src="Sloth emojis/Sloth loca pc.png" className="size-30" />
+          </motion.div>
         </div>
 
         {/* Brand text */}
diff --git a/studio/frontend/src/features/onboarding/components/wizard-content.tsx b/studio/frontend/src/features/onboarding/components/wizard-content.tsx
index 6906b87f8f..40d290a73e 100644
--- a/studio/frontend/src/features/onboarding/components/wizard-content.tsx
+++ b/studio/frontend/src/features/onboarding/components/wizard-content.tsx
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
+import { MascotImg } from "@/components/mascot-img";
 import { STEPS } from "@/config/training";
 import { useTrainingConfigStore } from "@/features/training";
 import type { StepNumber } from "@/types/training";
@@ -19,11 +20,11 @@ const STEP_COMPONENTS = {
 } as const;
 
 const STEP_MASCOTS: Record<StepNumber, string> = {
-  1: `${import.meta.env.BASE_URL}Sloth emojis/large sloth wave.png`,
-  2: `${import.meta.env.BASE_URL}Sloth emojis/sloth magnify final.png`,
-  3: `${import.meta.env.BASE_URL}Sloth emojis/sloth huglove large.png`,
-  4: `${import.meta.env.BASE_URL}Sloth emojis/large sloth glasses.png`,
-  5: `${import.meta.env.BASE_URL}Sloth emojis/large sloth yay.png`,
+  1: "Sloth emojis/large sloth wave.png",
+  2: "Sloth emojis/sloth magnify final.png",
+  3: "Sloth emojis/sloth huglove large.png",
+  4: "Sloth emojis/large sloth glasses.png",
+  5: "Sloth emojis/large sloth yay.png",
 };
 
 export function WizardContent() {
@@ -35,7 +36,7 @@ export function WizardContent() {
   return (
     <main className="flex-1 flex flex-col overflow-y-auto">
       <header className="flex flex-wrap items-start gap-3 p-4 pb-3 sm:p-6 sm:pb-4">
-        <img src={mascotSrc} alt="Unsloth mascot" className="size-12 sm:size-14" />
+        <MascotImg src={mascotSrc} className="size-12 sm:size-14" />
         <div className="flex flex-col min-w-0">
           <h1 className="text-lg font-semibold sm:text-xl">{stepConfig.title}</h1>
           <p className="text-sm text-muted-foreground">
diff --git a/studio/frontend/src/features/studio/training-start-overlay.tsx b/studio/frontend/src/features/studio/training-start-overlay.tsx
index b9fb34fedb..3b0cce658b 100644
--- a/studio/frontend/src/features/studio/training-start-overlay.tsx
+++ b/studio/frontend/src/features/studio/training-start-overlay.tsx
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
+import { MascotImg } from "@/components/mascot-img";
 import {
   AlertDialog,
   AlertDialogAction,
@@ -312,11 +313,7 @@ export function TrainingStartOverlay({
   return (
     <div className="pointer-events-none absolute inset-0 z-30 flex items-center justify-center rounded-2xl bg-background/45 backdrop-blur-[1px]">
       <div className="pointer-events-auto relative flex w-[860px] max-w-[calc(100%-2rem)] flex-col items-center">
-        <img
-          src="/unsloth-gem.png"
-          alt="Unsloth Studio"
-          className="size-24 object-contain"
-        />
+        <MascotImg src="unsloth-gem.png" className="size-24 object-contain" />
         <div className="relative w-full">
           <AlertDialog open={cancelDialogOpen} onOpenChange={setCancelDialogOpen}>
             <Button

From 6e057ffebeb418ff02c175e4a6eace0f0feb3a0a Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:22:47 -0700
Subject: [PATCH 156/222] Studio: training survives a non-writable HF datasets
 cache (#6148)

* Studio: training survives a non-writable HF datasets cache

A shared HF datasets cache can contain subtrees owned by another user
(for example populated by an earlier root-run job). datasets then dies
with "[Errno 13] Permission denied: ..._builder.lock" while locking
the cached builder and the training run fails. load_dataset in the
training worker and trainer now goes through a wrapper that catches the
EACCES and rebuilds the dataset in a Studio-owned cache under
cache_root()/hf-datasets, logging the fallback.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Scope the HF_DATASETS_CACHE override to the fallback load

* Route non-streaming dataset preview loads through the cache-safe wrapper

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/training/trainer.py       |  3 +-
 studio/backend/core/training/worker.py        |  5 +-
 .../hub/services/datasets/formatting.py       |  5 +-
 studio/backend/hub/services/datasets/local.py |  3 +-
 studio/backend/routes/datasets.py             |  3 +-
 studio/backend/utils/datasets/cache_safe.py   | 51 +++++++++++++++++++
 6 files changed, 64 insertions(+), 6 deletions(-)
 create mode 100644 studio/backend/utils/datasets/cache_safe.py

diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 3d6ab2411c..57342b2453 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -58,7 +58,8 @@ from pathlib import Path
 from typing import Optional, Callable
 from dataclasses import dataclass
 import pandas as pd
-from datasets import Dataset, load_dataset
+from datasets import Dataset
+from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
 
 from core.inference.llama_cpp import _hf_offline_if_dns_dead
 from utils.models import is_vision_model, detect_audio_type
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 267d6689b4..357f9712fe 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1353,7 +1353,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
             "(unsloth_zoo.mlx.loader / unsloth_zoo.mlx.trainer). Reinstall via "
             "install.sh on Apple Silicon."
         ) from e
-    from datasets import load_dataset
+    from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
 
     if mx.metal.is_available():
         info = mx.device_info()
@@ -2879,7 +2879,8 @@ def _run_embedding_training(event_queue: Any, stop_queue: Any, config: dict) ->
         )
         from sentence_transformers.losses import MultipleNegativesRankingLoss
         from sentence_transformers.training_args import BatchSamplers
-        from datasets import load_dataset, Dataset
+        from datasets import Dataset
+        from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
         from transformers import TrainerCallback
         from utils.paths import datasets_root, resolve_output_dir
     except ImportError as e:
diff --git a/studio/backend/hub/services/datasets/formatting.py b/studio/backend/hub/services/datasets/formatting.py
index 8b0ff39f63..1c78d80e21 100644
--- a/studio/backend/hub/services/datasets/formatting.py
+++ b/studio/backend/hub/services/datasets/formatting.py
@@ -223,7 +223,10 @@ def _load_processed_hf_preview_slice(
     if not _is_valid_repo_id(request.dataset_name):
         return None
     try:
-        from datasets import DownloadConfig, load_dataset
+        from datasets import DownloadConfig
+
+        # Non-streaming loads take the cached builder lock; use the EACCES-safe wrapper.
+        from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
     except Exception:
         return None
 
diff --git a/studio/backend/hub/services/datasets/local.py b/studio/backend/hub/services/datasets/local.py
index 2d2c7c3a0d..8d48c4f735 100644
--- a/studio/backend/hub/services/datasets/local.py
+++ b/studio/backend/hub/services/datasets/local.py
@@ -224,7 +224,8 @@ def _stream_file_preview_slice(path: Path, preview_size: int):
 
 
 def _load_local_preview_slice(*, dataset_path: Path, train_split: str, preview_size: int):
-    from datasets import load_dataset
+    # Non-streaming loads take the cached builder lock; use the EACCES-safe wrapper.
+    from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
 
     if dataset_path.is_dir():
         parquet_dir = (
diff --git a/studio/backend/routes/datasets.py b/studio/backend/routes/datasets.py
index 859f2958f9..46319ca2ba 100644
--- a/studio/backend/routes/datasets.py
+++ b/studio/backend/routes/datasets.py
@@ -412,7 +412,8 @@ def _build_local_dataset_items() -> list[LocalDatasetItem]:
 
 
 def _load_local_preview_slice(*, dataset_path: Path, train_split: str, preview_size: int):
-    from datasets import load_dataset
+    # Non-streaming loads take the cached builder lock; use the EACCES-safe wrapper.
+    from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
 
     if dataset_path.is_dir():
         parquet_dir = (
diff --git a/studio/backend/utils/datasets/cache_safe.py b/studio/backend/utils/datasets/cache_safe.py
new file mode 100644
index 0000000000..e629210f33
--- /dev/null
+++ b/studio/backend/utils/datasets/cache_safe.py
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Permission-safe wrapper around datasets.load_dataset.
+
+A shared HF datasets cache can contain subtrees owned by another user (for
+example populated by an earlier root-run job). datasets then raises
+"[Errno 13] Permission denied: ..._builder.lock" while locking the cached
+builder, killing the training run even though the dataset itself is fine.
+Retry such loads in a Studio-owned cache so the run proceeds; the worst case
+is one rebuild of the dataset in the fallback location.
+"""
+
+import logging
+import os
+
+from utils.paths.storage_roots import cache_root
+
+logger = logging.getLogger(__name__)
+
+
+def studio_datasets_cache() -> str:
+    path = cache_root() / "hf-datasets"
+    path.mkdir(parents = True, exist_ok = True)
+    return str(path)
+
+
+def load_dataset_cache_safe(*args, **kwargs):
+    """datasets.load_dataset, retried in a Studio-owned cache on EACCES."""
+    from datasets import load_dataset
+    try:
+        return load_dataset(*args, **kwargs)
+    except PermissionError as error:
+        fallback = studio_datasets_cache()
+        logger.warning(
+            "HF datasets cache is not writable (%s); rebuilding in %s",
+            error,
+            fallback,
+        )
+        kwargs["cache_dir"] = fallback
+        # Nested builders consult the env var while the load runs; restore it
+        # after so other datasets keep trying the shared cache first.
+        old_env = os.environ.get("HF_DATASETS_CACHE")
+        os.environ["HF_DATASETS_CACHE"] = fallback
+        try:
+            return load_dataset(*args, **kwargs)
+        finally:
+            if old_env is None:
+                os.environ.pop("HF_DATASETS_CACHE", None)
+            else:
+                os.environ["HF_DATASETS_CACHE"] = old_env

From 1d7f9b56f44c83c5fddf6751e62f39c382a755c8 Mon Sep 17 00:00:00 2001
From: danielhanchen <michaelhan2050@gmail.com>
Date: Wed, 10 Jun 2026 15:29:27 +0000
Subject: [PATCH 157/222] Installer: never plan a non-sm_120 CUDA build on
 Blackwell, never plan CPU on an NVIDIA host

Two hardening fixes from the fleet-validation audit.

Blackwell Windows hosts drop windows-cuda attempts that cannot offload
sm_120 instead of leaving them ranked behind the b9360 pin. A cuda-12.4
upstream build loads and passes the functional validator but runs the
model on a slow non-native path (an RTX 5090 measured 7.1 tok/s vs
551.2 on cuda-13.3), so one failed pin download away from that is too
close. The coverage check now also reads manifest SM metadata first, so
published cuda12 app bundles (toolkit 12.8, sm_120 included) stay
selectable and make the pin go dormant correctly.

The fork-release Linux planner no longer appends the linux-cpu bundle
for NVIDIA hosts whose CUDA selection produced nothing; it raises so
the caller walks back to an older release with a usable CUDA line,
mirroring the deliberate ROCm policy. Today's walk-back only works
because partial releases ship no CPU bundle; this keeps it working if
a future partial release does.
---
 studio/install_llama_prebuilt.py             |  50 +++++-
 tests/studio/install/test_selection_logic.py | 175 ++++++++++++++++++-
 2 files changed, 220 insertions(+), 5 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 4509ea58ed..91b1105832 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -1410,10 +1410,16 @@ def direct_linux_release_plan(
         )
         if lemonade_choice is not None:
             attempts.append(lemonade_choice)
-    else:
+    elif not host.has_usable_nvidia:
         cpu_choice = published_asset_choice_for_kind(bundle, "linux-cpu")
         if cpu_choice is not None:
             attempts.append(cpu_choice)
+    # NVIDIA hosts whose CUDA selection produced nothing fall through to the
+    # raise below (mirroring the ROCm policy above): the caller then walks
+    # back to an older release that still ships a usable CUDA line instead of
+    # silently installing a CPU binary on a GPU host. Today's walk-back only
+    # works because partial releases ship no CPU bundle; this keeps it working
+    # if a future partial release does.
     if not attempts:
         raise PrebuiltFallback("no compatible Linux prebuilt asset was found")
     approved_checksums = synthetic_checksums_for_release(
@@ -1476,6 +1482,7 @@ def direct_upstream_release_plan(
                     torch_preference.selection_log,
                 )
             )
+            attempts[:] = _drop_blackwell_incapable_windows_cuda(host, attempts)
             # Blackwell on a 13.1/13.2 driver: prefer the pinned cuda-13.1 GPU
             # build over the CPU-only cuda-12.4 left by in-release gating.
             pinned = _pinned_windows_cuda_fallback(host, attempts)
@@ -3315,14 +3322,50 @@ def windows_cuda_attempts(
 
 
 def _windows_cuda_attempt_covers_blackwell(attempt: AssetChoice) -> bool:
-    """True if an in-release windows-cuda attempt's toolkit covers Blackwell
-    sm_120 (>= 12.8), read from its asset name's CUDA minor."""
+    """True if an in-release windows-cuda attempt covers Blackwell sm_120.
+
+    Manifest-backed app bundles carry their compiled SM list, so trust that
+    first (the published cuda12 bundles are toolkit-12.8 builds that include
+    sm_120 even though their runtime line says cuda12). Upstream ggml-org
+    zips have no manifest metadata; infer from the CUDA minor in the asset
+    name (sm_120 needs toolkit >= 12.8)."""
     if attempt.install_kind != "windows-cuda":
         return False
+    if attempt.max_sm is not None:
+        return attempt.max_sm >= _BLACKWELL_MIN_SM
+    if attempt.supported_sms:
+        sms = normalize_compute_caps(attempt.supported_sms)
+        if sms:
+            return int(sms[-1]) >= _BLACKWELL_MIN_SM
     m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
     return m is not None and (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
 
 
+def _host_is_blackwell(host: HostInfo) -> bool:
+    caps = normalize_compute_caps(host.compute_caps)
+    return bool(caps) and int(caps[-1]) >= _BLACKWELL_MIN_SM
+
+
+def _drop_blackwell_incapable_windows_cuda(
+    host: HostInfo, attempts: list[AssetChoice]
+) -> list[AssetChoice]:
+    """On a Blackwell host, drop windows-cuda attempts that cannot offload
+    sm_120 (e.g. upstream cuda-12.4, toolkit 12.4). Such a build loads and
+    passes the functional validator but runs the model on a slow non-native
+    path (an RTX 5090 measured 7.1 tok/s vs 551.2 on cuda-13.3), so it must
+    not sit in the fallback chain behind the pin or an in-release cuda13.
+    Non-cuda attempts (windows-cpu, windows-hip, ...) pass through so the
+    host still degrades to an honest CPU install when no CUDA 13 exists."""
+    if not _host_is_blackwell(host):
+        return attempts
+    return [
+        attempt
+        for attempt in attempts
+        if attempt.install_kind != "windows-cuda"
+        or _windows_cuda_attempt_covers_blackwell(attempt)
+    ]
+
+
 def _pinned_windows_cuda_fallback(
     host: HostInfo, existing_cuda_attempts: list[AssetChoice]
 ) -> AssetChoice | None:
@@ -3405,6 +3448,7 @@ def _with_pinned_windows_cuda_fallback(
     """Insert the Blackwell pin ahead of the Windows CUDA attempts and keep it
     through apply_approved_hashes, or return inputs unchanged when dormant.
     Gives the published install path the same GPU fallback as the simple path."""
+    attempts = _drop_blackwell_incapable_windows_cuda(host, attempts)
     pin = _pinned_windows_cuda_fallback(host, attempts)
     if pin is None:
         return attempts, checksums
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index b5a070ae41..05da6585de 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -2401,7 +2401,10 @@ class TestDirectUpstreamBlackwellPin:
         )
         plan = direct_upstream_release_plan(self._release(), host, UPSTREAM_REPO, "latest")
         order = [(a.tag, a.runtime_line or a.install_kind) for a in plan.attempts]
-        assert order == [("b9360", "cuda13"), (self.TAG, "cuda12"), (self.TAG, "windows-cpu")]
+        # cuda-12.4 (toolkit 12.4, no sm_120) is dropped entirely on Blackwell:
+        # behind the pin it would still be attempted if the pin download failed,
+        # and the functional validator accepts its slow non-native path.
+        assert order == [("b9360", "cuda13"), (self.TAG, "windows-cpu")]
         assert plan.attempts[0].name == "llama-b9360-bin-win-cuda-13.1-x64.zip"
         # Direct/upstream path stays unverified-by-manifest (no approved hashes).
         assert plan.approved_checksums.artifacts == {}
@@ -2422,6 +2425,172 @@ class TestDirectUpstreamBlackwellPin:
         assert plan.attempts[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
 
 
+# N.1c2. Blackwell never falls to a non-sm_120 windows-cuda attempt
+
+
+class TestBlackwellCuda124Exclusion:
+    """A Blackwell host must never have a windows-cuda attempt that cannot
+    offload sm_120 anywhere in its chain: behind the pin it is one failed
+    download away from a validated-but-7-tok/s install."""
+
+    def _bw_host(self):
+        return make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 1),
+            compute_caps = ["120"],
+        )
+
+    def _upstream_cuda(self, minor, tag = "b9365"):
+        return AssetChoice(
+            repo = "ggml-org/llama.cpp",
+            tag = tag,
+            name = f"llama-{tag}-bin-win-cuda-{minor}-x64.zip",
+            url = f"https://example.com/{minor}",
+            source_label = "upstream",
+            install_kind = "windows-cuda",
+            runtime_line = "cuda" + minor.split(".")[0],
+        )
+
+    def test_drops_124_keeps_133_on_blackwell(self):
+        kept = INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(
+            self._bw_host(),
+            [self._upstream_cuda("13.3"), self._upstream_cuda("12.4")],
+        )
+        assert [a.name for a in kept] == ["llama-b9365-bin-win-cuda-13.3-x64.zip"]
+
+    def test_keeps_manifest_cuda12_bundle_with_sm120(self):
+        # Published cuda12 app bundles are toolkit-12.8 builds that include
+        # sm_120; the manifest SM metadata must keep them on Blackwell.
+        bundle = AssetChoice(
+            repo = "unslothai/llama.cpp",
+            tag = "b9585",
+            name = "app-b9585-windows-x64-cuda12-portable.zip",
+            url = "https://example.com/app",
+            source_label = "published",
+            install_kind = "windows-cuda",
+            runtime_line = "cuda12",
+            supported_sms = ["70", "120"],
+            max_sm = 120,
+        )
+        kept = INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(
+            self._bw_host(), [bundle]
+        )
+        assert kept == [bundle]
+        assert _windows_cuda_attempt_covers_blackwell(bundle)
+
+    def test_manifest_bundle_without_sm120_dropped(self):
+        bundle = AssetChoice(
+            repo = "unslothai/llama.cpp",
+            tag = "b9585",
+            name = "app-b9585-windows-x64-cuda12-older.zip",
+            url = "https://example.com/app",
+            source_label = "published",
+            install_kind = "windows-cuda",
+            runtime_line = "cuda12",
+            supported_sms = ["70", "75", "80"],
+            max_sm = 80,
+        )
+        assert (
+            INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(
+                self._bw_host(), [bundle]
+            )
+            == []
+        )
+
+    def test_non_blackwell_host_unfiltered(self):
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (12, 9),
+            compute_caps = ["89"],
+        )
+        attempts = [self._upstream_cuda("12.4")]
+        assert (
+            INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(host, attempts)
+            == attempts
+        )
+
+    def test_non_cuda_attempts_pass_through(self):
+        cpu = AssetChoice(
+            repo = "ggml-org/llama.cpp",
+            tag = "b9365",
+            name = "llama-b9365-bin-win-cpu-x64.zip",
+            url = "https://example.com/cpu",
+            source_label = "upstream",
+            install_kind = "windows-cpu",
+        )
+        kept = INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(
+            self._bw_host(), [self._upstream_cuda("12.4"), cpu]
+        )
+        assert kept == [cpu]
+
+
+# N.1c3. direct_linux_release_plan -- no silent CPU on NVIDIA hosts
+
+
+class TestDirectLinuxNvidiaCpuGate:
+    """When a release ships a linux-cpu bundle but no CUDA line this NVIDIA
+    host can use, the planner must raise (so the caller walks back to an older
+    release with a usable CUDA line) instead of silently planning a CPU
+    install on a GPU host. CPU-only hosts keep taking the CPU bundle."""
+
+    def _bundle_cpu_only(self):
+        return make_release(
+            [
+                make_artifact(
+                    "llama-b8508-bin-ubuntu-x64.tar.gz",
+                    install_kind = "linux-cpu",
+                    runtime_line = None,
+                    coverage_class = None,
+                    supported_sms = [],
+                    min_sm = None,
+                    max_sm = None,
+                    bundle_profile = None,
+                ),
+            ]
+        )
+
+    def _patch(self, monkeypatch):
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "parse_direct_linux_release_bundle",
+            lambda repo, release: self._bundle_cpu_only(),
+        )
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "detect_torch_cuda_runtime_preference",
+            lambda host: CudaRuntimePreference(runtime_line = None, selection_log = []),
+        )
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "detected_linux_runtime_lines",
+            lambda: (["cuda13"], {"cuda13": ["/usr/local/cuda/lib64"]}),
+        )
+
+    def test_nvidia_host_without_cuda_line_raises_for_walkback(self, monkeypatch):
+        self._patch(monkeypatch)
+        host = make_host(driver_cuda_version = (13, 1), compute_caps = ["100"])
+        with pytest.raises(PrebuiltFallback, match = "no compatible Linux prebuilt"):
+            INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
+                {"tag_name": "b8508"}, host, "unslothai/llama.cpp", "latest"
+            )
+
+    def test_cpu_host_still_gets_cpu_bundle(self, monkeypatch):
+        self._patch(monkeypatch)
+        host = make_host(
+            nvidia_smi = None,
+            driver_cuda_version = None,
+            compute_caps = [],
+            has_physical_nvidia = False,
+            has_usable_nvidia = False,
+        )
+        plan = INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
+            {"tag_name": "b8508"}, host, "unslothai/llama.cpp", "latest"
+        )
+        assert [a.install_kind for a in plan.attempts] == ["linux-cpu"]
+
+
 # N.1d. published_windows_cuda_attempts -- version-dynamic ordering seed
 
 
@@ -2549,7 +2718,9 @@ class TestResolveReleaseAssetChoicePin:
         # augmented checksums (the pin survives the approved-hash gate).
         assert result[0].expected_sha256 and len(result[0].expected_sha256) == 64
         assert result[0].runtime_sha256 and len(result[0].runtime_sha256) == 64
-        assert any(a.runtime_line == "cuda12" for a in result)
+        # The sm_120-incapable upstream cuda-12.4 zip is excluded on Blackwell
+        # rather than left behind the pin as a slow-path fallback.
+        assert not any(a.runtime_line == "cuda12" for a in result)
 
     def test_pin_dormant_on_published_path_for_13_3(self, monkeypatch):
         mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])

From 1d9090ff6bb5c3c384be4c12b953272e518e9b98 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:30:31 +0000
Subject: [PATCH 158/222] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/install_llama_prebuilt.py             |  3 +--
 tests/studio/install/test_selection_logic.py | 10 ++++++----
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 91b1105832..bc4fe555c1 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -3361,8 +3361,7 @@ def _drop_blackwell_incapable_windows_cuda(
     return [
         attempt
         for attempt in attempts
-        if attempt.install_kind != "windows-cuda"
-        or _windows_cuda_attempt_covers_blackwell(attempt)
+        if attempt.install_kind != "windows-cuda" or _windows_cuda_attempt_covers_blackwell(attempt)
     ]
 
 
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index 05da6585de..dfa2378ef5 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -2441,7 +2441,11 @@ class TestBlackwellCuda124Exclusion:
             compute_caps = ["120"],
         )
 
-    def _upstream_cuda(self, minor, tag = "b9365"):
+    def _upstream_cuda(
+        self,
+        minor,
+        tag = "b9365",
+    ):
         return AssetChoice(
             repo = "ggml-org/llama.cpp",
             tag = tag,
@@ -2492,9 +2496,7 @@ class TestBlackwellCuda124Exclusion:
             max_sm = 80,
         )
         assert (
-            INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(
-                self._bw_host(), [bundle]
-            )
+            INSTALL_LLAMA_PREBUILT._drop_blackwell_incapable_windows_cuda(self._bw_host(), [bundle])
             == []
         )
 

From 0f00bc1e2ad7216d3f096aafa755c2274682f9dc Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Wed, 10 Jun 2026 16:39:07 +0100
Subject: [PATCH 159/222] Studio: fix Gemma-4-12B-it not loading (#6054)

* Fix Studio Python, Gemma 4 Unified sidecar, and worker crash messages

* Clean up Gemma 4 sidecar test patch contexts

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Polish inference worker crash message

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address transformers tier review feedback

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Route Gemma 4 assistant models to transformers 5.10

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/orchestrator.py |  48 ++-
 studio/backend/core/training/worker.py        |   2 +-
 ...st_inference_orchestrator_crash_message.py |  33 ++
 .../tests/test_transformers_version.py        | 224 ++++++++++++-
 studio/backend/utils/models/model_config.py   |   2 +-
 studio/backend/utils/transformers_version.py  | 302 +++++++++++++-----
 studio/setup.ps1                              | 122 ++++++-
 studio/setup.sh                               |  34 +-
 8 files changed, 662 insertions(+), 105 deletions(-)
 create mode 100644 studio/backend/tests/test_inference_orchestrator_crash_message.py

diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index e394b342f0..32bb25c976 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -17,6 +17,7 @@ Pattern follows core/training/training.py.
 import atexit
 import base64
 import os
+import signal
 import structlog
 from loggers import get_logger
 import multiprocessing as mp
@@ -239,6 +240,43 @@ class InferenceOrchestrator:
         """True if the subprocess is alive."""
         return self._proc is not None and self._proc.is_alive()
 
+    def _subprocess_crash_message(self, context: str) -> str:
+        """Return a user-facing crash message with the worker exit status."""
+        context_label = {
+            "wait": "loading the model",
+            "generation": "generating a response",
+            "audio generation": "generating audio",
+            "audio input generation": "processing audio input",
+        }.get(context, context)
+        message = f"The inference worker stopped unexpectedly while {context_label}."
+
+        if self._proc is None:
+            return f"{message} Details: process missing."
+
+        exitcode = self._proc.exitcode
+        pid = self._proc.pid
+        if exitcode is None:
+            return f"{message} Details: pid={pid}."
+
+        if exitcode < 0:
+            signum = -exitcode
+            try:
+                sig_name = signal.Signals(signum).name
+            except ValueError:
+                sig_name = f"SIG{signum}"
+
+            suffix = ""
+            if sig_name == "SIGKILL":
+                suffix = (
+                    " This usually means the system killed it under memory pressure. "
+                    "Try a smaller model, lower context length, or close other GPU-heavy apps."
+                )
+            return (
+                f"{message}{suffix} " f"Details: pid={pid}, signal={sig_name}, exitcode={exitcode}."
+            )
+
+        return f"{message} Details: pid={pid}, exitcode={exitcode}."
+
     # ------------------------------------------------------------------
     # Queue helpers
     # ------------------------------------------------------------------
@@ -286,7 +324,7 @@ class InferenceOrchestrator:
             if resp is None:
                 # Check subprocess health
                 if not self._ensure_subprocess_alive():
-                    raise RuntimeError("Inference subprocess crashed during wait")
+                    raise RuntimeError(self._subprocess_crash_message("wait"))
                 continue
 
             rtype = resp.get("type", "")
@@ -510,7 +548,7 @@ class InferenceOrchestrator:
                 except queue.Empty:
                     # Timeout — check subprocess health
                     if not self._ensure_subprocess_alive():
-                        yield "Error: Inference subprocess crashed during generation"
+                        yield f"Error: {self._subprocess_crash_message('generation')}"
                         return
                     continue
 
@@ -1028,7 +1066,7 @@ class InferenceOrchestrator:
             if resp is None:
                 # Check subprocess health
                 if not self._ensure_subprocess_alive():
-                    yield "Error: Inference subprocess crashed during generation"
+                    yield f"Error: {self._subprocess_crash_message('generation')}"
                     return
                 continue
 
@@ -1125,7 +1163,7 @@ class InferenceOrchestrator:
 
             if resp is None:
                 if not self._ensure_subprocess_alive():
-                    raise RuntimeError("Inference subprocess crashed during audio generation")
+                    raise RuntimeError(self._subprocess_crash_message("audio generation"))
                 continue
 
             rtype = resp.get("type", "")
@@ -1247,7 +1285,7 @@ class InferenceOrchestrator:
 
                 if resp is None:
                     if not self._ensure_subprocess_alive():
-                        yield "Error: Inference subprocess crashed during audio input generation"
+                        yield ("Error: " + self._subprocess_crash_message("audio input generation"))
                         return
                     continue
 
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 357f9712fe..b50e17e5aa 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1951,7 +1951,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                 }
             )
             return
-        # Activate correct transformers version (Gemma-4 needs 5.5.0, etc.)
+        # Activate correct transformers version (Gemma-4 needs a 5.x sidecar, etc.)
         # before any transformers/mlx-lm imports in _run_mlx_training.
         try:
             _activate_transformers_version(model_name)
diff --git a/studio/backend/tests/test_inference_orchestrator_crash_message.py b/studio/backend/tests/test_inference_orchestrator_crash_message.py
new file mode 100644
index 0000000000..be1a673e62
--- /dev/null
+++ b/studio/backend/tests/test_inference_orchestrator_crash_message.py
@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from pathlib import Path
+from types import SimpleNamespace
+import importlib.util
+import sys
+
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+
+def test_subprocess_crash_message_includes_signal_and_oom_hint():
+    spec = importlib.util.spec_from_file_location(
+        "inference_orchestrator_under_test",
+        Path(__file__).resolve().parent.parent / "core/inference/orchestrator.py",
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    orchestrator = module.InferenceOrchestrator.__new__(module.InferenceOrchestrator)
+    orchestrator._proc = SimpleNamespace(pid = 1234, exitcode = -9)
+
+    msg = orchestrator._subprocess_crash_message("wait")
+
+    assert msg.startswith("The inference worker stopped unexpectedly while loading the model.")
+    assert "memory pressure" in msg
+    assert "smaller model" in msg
+    assert "Details:" in msg
+    assert "signal=SIGKILL" in msg
+    assert "exitcode=-9" in msg
diff --git a/studio/backend/tests/test_transformers_version.py b/studio/backend/tests/test_transformers_version.py
index 915bc4b13b..7c497ba1b1 100644
--- a/studio/backend/tests/test_transformers_version.py
+++ b/studio/backend/tests/test_transformers_version.py
@@ -30,8 +30,11 @@ sys.modules.setdefault("loggers", _loggers_stub)
 from utils.transformers_version import (
     _resolve_base_model,
     _check_tokenizer_config_needs_v5,
+    _check_config_needs_510,
     _check_config_needs_550,
+    _config_json_cache,
     _tokenizer_class_cache,
+    _config_needs_510_cache,
     _config_needs_550_cache,
     needs_transformers_5,
     get_transformers_tier,
@@ -200,6 +203,7 @@ class TestCheckConfigNeeds550:
     """Tests for _check_config_needs_550() local config.json checks."""
 
     def setup_method(self):
+        _config_json_cache.clear()
         _config_needs_550_cache.clear()
 
     def test_gemma4_architecture(self, tmp_path: Path):
@@ -253,6 +257,106 @@ class TestCheckConfigNeeds550:
             mock_urlopen.assert_not_called()
 
 
+# ---------------------------------------------------------------------------
+# _check_config_needs_510 — config.json architecture/model_type check
+# ---------------------------------------------------------------------------
+
+
+class TestCheckConfigNeeds510:
+    """Tests for _check_config_needs_510() local config.json checks."""
+
+    def setup_method(self):
+        _config_json_cache.clear()
+        _config_needs_510_cache.clear()
+
+    def test_gemma4_unified_architecture(self, tmp_path: Path):
+        """config.json with Gemma4UnifiedForConditionalGeneration should return True."""
+        cfg = {
+            "architectures": ["Gemma4UnifiedForConditionalGeneration"],
+            "model_type": "gemma4_unified",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_unified_model_type_only(self, tmp_path: Path):
+        """config.json with model_type=gemma4_unified should return True."""
+        cfg = {"model_type": "gemma4_unified"}
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_unified_assistant_architecture(self, tmp_path: Path):
+        """Assistant Gemma 4 Unified configs should return True."""
+        cfg = {
+            "architectures": ["Gemma4UnifiedAssistantForCausalLM"],
+            "model_type": "gemma4_unified_assistant",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_unified_assistant_model_type_only(self, tmp_path: Path):
+        """Assistant Gemma 4 Unified model_type should return True."""
+        cfg = {"model_type": "gemma4_unified_assistant"}
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_assistant_architecture(self, tmp_path: Path):
+        """Assistant Gemma 4 configs should return True."""
+        cfg = {
+            "architectures": ["Gemma4AssistantForCausalLM"],
+            "model_type": "gemma4_assistant",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_assistant_model_type_only(self, tmp_path: Path):
+        """Assistant Gemma 4 model_type should return True."""
+        cfg = {"model_type": "gemma4_assistant"}
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is True
+
+    def test_gemma4_non_unified_returns_false(self, tmp_path: Path):
+        """Older Gemma 4 config should stay on the 550 tier."""
+        cfg = {
+            "architectures": ["Gemma4ForConditionalGeneration"],
+            "model_type": "gemma4",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert _check_config_needs_510(str(tmp_path)) is False
+
+    def test_no_config_json(self, tmp_path: Path):
+        """Missing config.json should return False (fail-open)."""
+        # Patch network call to avoid real fetch
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = Exception("no network")
+            assert _check_config_needs_510(str(tmp_path)) is False
+
+    def test_result_is_cached(self, tmp_path: Path):
+        """Subsequent calls should use the cache."""
+        cfg = {"architectures": ["Gemma4UnifiedForConditionalGeneration"]}
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        key = str(tmp_path)
+        _check_config_needs_510(key)
+        assert key in _config_needs_510_cache
+        assert _config_needs_510_cache[key] is True
+
+    def test_local_file_skips_network(self, tmp_path: Path):
+        """When local config.json exists, no network request should be made."""
+        cfg = {"architectures": ["LlamaForCausalLM"]}
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            _check_config_needs_510(str(tmp_path))
+            mock_urlopen.assert_not_called()
+
+
 # ---------------------------------------------------------------------------
 # get_transformers_tier — tier detection
 # ---------------------------------------------------------------------------
@@ -263,11 +367,19 @@ class TestGetTransformersTier:
 
     def setup_method(self):
         _tokenizer_class_cache.clear()
+        _config_json_cache.clear()
+        _config_needs_510_cache.clear()
         _config_needs_550_cache.clear()
 
     def test_gemma4_substring_returns_550(self):
         assert get_transformers_tier("google/gemma-4-E2B-it") == "550"
 
+    def test_gemma4_12b_substring_returns_510(self):
+        assert get_transformers_tier("unsloth/gemma-4-12b-it") == "510"
+
+    def test_gemma4_assistant_substring_returns_510(self):
+        assert get_transformers_tier("google/gemma-4-E2B-it-assistant") == "510"
+
     def test_gemma4_alt_substring_returns_550(self):
         assert get_transformers_tier("unsloth/gemma4-E4B-it") == "550"
 
@@ -281,17 +393,92 @@ class TestGetTransformersTier:
 
         assert get_transformers_tier(str(tmp_path)) == "550"
 
+    def test_gemma4_unified_config_json_returns_510(self, tmp_path: Path):
+        """Local checkpoint with Gemma4 Unified architecture → 510."""
+        cfg = {
+            "architectures": ["Gemma4UnifiedForConditionalGeneration"],
+            "model_type": "gemma4_unified",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert get_transformers_tier(str(tmp_path)) == "510"
+
+    def test_gemma4_assistant_config_json_returns_510(self, tmp_path: Path):
+        """Local checkpoint with Gemma4 Assistant architecture → 510."""
+        cfg = {
+            "architectures": ["Gemma4AssistantForCausalLM"],
+            "model_type": "gemma4_assistant",
+        }
+        (tmp_path / "config.json").write_text(json.dumps(cfg))
+
+        assert get_transformers_tier(str(tmp_path)) == "510"
+
+    def test_local_config_json_short_circuits_path_substrings(self, tmp_path: Path):
+        """Local config.json should prevent false matches from parent directory names."""
+        model_dir = tmp_path / "gemma-4-12b-experiment" / "llama-checkpoint"
+        model_dir.mkdir(parents = True)
+        (model_dir / "config.json").write_text(
+            json.dumps(
+                {
+                    "architectures": ["LlamaForCausalLM"],
+                    "model_type": "llama",
+                }
+            )
+        )
+        (model_dir / "tokenizer_config.json").write_text(
+            json.dumps({"tokenizer_class": "LlamaTokenizerFast"})
+        )
+
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            assert get_transformers_tier(str(model_dir)) == "default"
+            mock_urlopen.assert_not_called()
+
+    def test_remote_config_json_is_fetched_once_for_config_tiers(self):
+        """510 and 550 slow-path checks should share one config.json fetch."""
+
+        class _Response:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+            def read(self):
+                return json.dumps(
+                    {
+                        "architectures": ["Gemma4ForConditionalGeneration"],
+                        "model_type": "gemma4",
+                    }
+                ).encode()
+
+        with patch("urllib.request.urlopen", return_value = _Response()) as mock_urlopen:
+            assert get_transformers_tier("org/no-fast-substring-model") == "550"
+
+        assert mock_urlopen.call_count == 1
+
     def test_qwen35_returns_530(self):
-        with patch(
-            "utils.transformers_version._check_config_needs_550",
-            return_value = False,
+        with (
+            patch(
+                "utils.transformers_version._check_config_needs_550",
+                return_value = False,
+            ),
+            patch(
+                "utils.transformers_version._check_config_needs_510",
+                return_value = False,
+            ),
         ):
             assert get_transformers_tier("Qwen/Qwen3.5-9B") == "530"
 
     def test_ministral_returns_530(self):
-        with patch(
-            "utils.transformers_version._check_config_needs_550",
-            return_value = False,
+        with (
+            patch(
+                "utils.transformers_version._check_config_needs_550",
+                return_value = False,
+            ),
+            patch(
+                "utils.transformers_version._check_config_needs_510",
+                return_value = False,
+            ),
         ):
             assert get_transformers_tier("mistralai/Ministral-3-8B-Instruct-2512") == "530"
 
@@ -301,6 +488,10 @@ class TestGetTransformersTier:
                 "utils.transformers_version._check_config_needs_550",
                 return_value = False,
             ),
+            patch(
+                "utils.transformers_version._check_config_needs_510",
+                return_value = False,
+            ),
             patch(
                 "utils.transformers_version._check_tokenizer_config_needs_v5",
                 return_value = False,
@@ -309,15 +500,22 @@ class TestGetTransformersTier:
             assert get_transformers_tier("meta-llama/Llama-3-8B") == "default"
 
     def test_550_checked_before_530(self):
-        """5.5.0 is checked first — a model matching both gets 550."""
+        """5.5.0 is checked before 5.3.0 - a model matching both gets 550."""
         assert get_transformers_tier("gemma-4-model") == "550"
 
     def test_needs_transformers_5_compat(self):
-        """needs_transformers_5 should return True for both 530 and 550 models."""
+        """needs_transformers_5 should return True for 510, 530, and 550 models."""
+        assert needs_transformers_5("unsloth/gemma-4-12b-it") is True
         assert needs_transformers_5("google/gemma-4-E2B-it") is True
-        with patch(
-            "utils.transformers_version._check_config_needs_550",
-            return_value = False,
+        with (
+            patch(
+                "utils.transformers_version._check_config_needs_550",
+                return_value = False,
+            ),
+            patch(
+                "utils.transformers_version._check_config_needs_510",
+                return_value = False,
+            ),
         ):
             assert needs_transformers_5("Qwen/Qwen3.5-9B") is True
         with (
@@ -325,6 +523,10 @@ class TestGetTransformersTier:
                 "utils.transformers_version._check_config_needs_550",
                 return_value = False,
             ),
+            patch(
+                "utils.transformers_version._check_config_needs_510",
+                return_value = False,
+            ),
             patch(
                 "utils.transformers_version._check_tokenizer_config_needs_v5",
                 return_value = False,
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 0df7a1a477..9dc01f83c5 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -510,7 +510,7 @@ _VLM_MODEL_TYPES = {
 _AUDIO_ONLY_MODEL_TYPES = {"csm", "whisper"}
 
 # Pre-computed .venv_t5 paths and backend dir for subprocess version switching.
-# Vision check uses 5.5.0 (newest, recognizes all architectures).
+# Vision check uses the Gemma 4 5.5 sidecar for existing Gemma 4 architectures.
 from utils.paths.storage_roots import studio_root as _studio_root  # noqa: E402
 
 _VENV_T5_DIR = str(_studio_root() / ".venv_t5_550")
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index bf8d14b7cb..6e1571d5ce 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -3,12 +3,27 @@
 
 """Automatic transformers version switching.
 
-Some newer architectures need transformers>=5.3.0 (.venv_t5_530/); Gemma 4
-needs >=5.5.0 (.venv_t5_550/). Everything else uses the default 4.57.x. A
-custom-named LoRA adapter's base model is resolved from adapter_config.json.
+Some newer model architectures (Ministral-3, GLM-4.7-Flash, Qwen3-30B-A3B MoE,
+tiny_qwen3_moe) require transformers>=5.3.0, while Gemma 4 models require a
+newer 5.x sidecar.  Everything else needs the default 4.57.x that ships with
+Unsloth.
 
-Training/inference run in subprocesses that activate the right version via
-sys.path; export (in-process) uses ensure_transformers_version() for the swap.
+Two separate target directories are maintained:
+  - .venv_t5_530/  — transformers 5.3.0 (Ministral-3, GLM, Qwen3 MoE, etc.)
+  - .venv_t5_550/  — transformers 5.5.0 (Gemma 4)
+  - .venv_t5_510/  — transformers 5.10.2 (Gemma 4 Unified / 12B)
+
+When loading a LoRA adapter with a custom name, we resolve the base model from
+``adapter_config.json`` and check *that* against the model list.
+
+Strategy:
+  Training and inference run in subprocesses that activate the correct version
+  via sys.path (prepending the appropriate .venv_t5_*/ directory). See:
+    - core/training/worker.py
+    - core/inference/worker.py
+
+  For export (still in-process), ensure_transformers_version() does a lightweight
+  sys.path swap using the same directories pre-installed by setup.sh.
 """
 
 import importlib
@@ -53,13 +68,32 @@ TRANSFORMERS_5_MODEL_SUBSTRINGS: tuple[str, ...] = (
     "lfm2.5-vl-450m",  # LiquidAI/LFM2.5-VL-450M
 )
 
-# Lowercase substrings for models that require transformers 5.5.0 (checked first).
+# Lowercase substrings for models that require transformers 5.10.x (checked first).
+TRANSFORMERS_510_MODEL_SUBSTRINGS: tuple[str, ...] = (
+    "gemma-4-12b",  # Gemma 4 Unified 12B
+    "gemma4-12b",
+)
+
+# Lowercase substrings for models that require the Gemma 4 transformers 5.5 sidecar.
 TRANSFORMERS_550_MODEL_SUBSTRINGS: tuple[str, ...] = (
     "gemma-4",  # Gemma-4 (E2B-it, E4B-it, 31B-it, 26B-A4B-it)
     "gemma4",  # Gemma-4 alternate naming
     "qwen3.6",
 )
 
+# Architecture classes / model_type values that require transformers 5.10.x.
+# Checked via config.json (local or HuggingFace).
+_TRANSFORMERS_510_ARCHITECTURES: set[str] = {
+    "Gemma4UnifiedForConditionalGeneration",
+    "Gemma4AssistantForCausalLM",
+    "Gemma4UnifiedAssistantForCausalLM",
+}
+_TRANSFORMERS_510_MODEL_TYPES: set[str] = {
+    "gemma4_unified",
+    "gemma4_assistant",
+    "gemma4_unified_assistant",
+}
+
 # Architecture classes / model_type values that require transformers 5.5.0.
 # Checked via config.json (local or HuggingFace).
 _TRANSFORMERS_550_ARCHITECTURES: set[str] = {
@@ -78,21 +112,26 @@ _TRANSFORMERS_5_TOKENIZER_CLASSES: set[str] = {
 _tokenizer_class_cache: dict[str, bool] = {}
 
 # Cache for dynamic config.json lookups (architecture/model_type checks).
+_config_json_cache: dict[str, dict | None] = {}
+_config_needs_510_cache: dict[str, bool] = {}
 _config_needs_550_cache: dict[str, bool] = {}
 
 # Versions
+TRANSFORMERS_510_VERSION = "5.10.2"
 TRANSFORMERS_550_VERSION = "5.5.0"
 TRANSFORMERS_530_VERSION = "5.3.0"
 TRANSFORMERS_DEFAULT_VERSION = "4.57.6"
-# Backwards-compat alias — points to 5.5.0 (the highest 5.x tier).
-# Consumers should prefer TRANSFORMERS_530_VERSION / TRANSFORMERS_550_VERSION.
-TRANSFORMERS_5_VERSION = TRANSFORMERS_550_VERSION
+# Backwards-compat alias — points to the highest 5.x tier.
+# Consumers should prefer TRANSFORMERS_510_VERSION / TRANSFORMERS_550_VERSION /
+# TRANSFORMERS_530_VERSION.
+TRANSFORMERS_5_VERSION = TRANSFORMERS_510_VERSION
 
 # Pre-installed directories — created by setup.sh / setup.ps1.
 from utils.paths.storage_roots import studio_root as _studio_root  # noqa: E402
 
 _VENV_T5_530_DIR = str(_studio_root() / ".venv_t5_530")
 _VENV_T5_550_DIR = str(_studio_root() / ".venv_t5_550")
+_VENV_T5_510_DIR = str(_studio_root() / ".venv_t5_510")
 # Backwards-compat alias
 _VENV_T5_DIR = _VENV_T5_550_DIR
 
@@ -108,15 +147,34 @@ def activate_transformers_for_subprocess(model_name: str) -> None:
     resolved = _resolve_base_model(model_name)
     tier = get_transformers_tier(resolved)
 
-    if tier == "550":
+    if tier == "510":
+        if not _ensure_venv_t5_510_exists():
+            raise RuntimeError(
+                f"Cannot activate transformers {TRANSFORMERS_510_VERSION}: "
+                f".venv_t5_510 missing at {_VENV_T5_510_DIR}"
+            )
+        if _VENV_T5_510_DIR not in sys.path:
+            sys.path.insert(0, _VENV_T5_510_DIR)
+        logger.info(
+            "Activated transformers %s from %s",
+            TRANSFORMERS_510_VERSION,
+            _VENV_T5_510_DIR,
+        )
+        _pp = os.environ.get("PYTHONPATH", "")
+        os.environ["PYTHONPATH"] = _VENV_T5_510_DIR + (os.pathsep + _pp if _pp else "")
+    elif tier == "550":
         if not _ensure_venv_t5_550_exists():
             raise RuntimeError(
-                f"Cannot activate transformers 5.5.0: "
+                f"Cannot activate transformers {TRANSFORMERS_550_VERSION}: "
                 f".venv_t5_550 missing at {_VENV_T5_550_DIR}"
             )
         if _VENV_T5_550_DIR not in sys.path:
             sys.path.insert(0, _VENV_T5_550_DIR)
-        logger.info("Activated transformers 5.5.0 from %s", _VENV_T5_550_DIR)
+        logger.info(
+            "Activated transformers %s from %s",
+            TRANSFORMERS_550_VERSION,
+            _VENV_T5_550_DIR,
+        )
         _pp = os.environ.get("PYTHONPATH", "")
         os.environ["PYTHONPATH"] = _VENV_T5_550_DIR + (os.pathsep + _pp if _pp else "")
     elif tier == "530":
@@ -260,6 +318,67 @@ def _check_tokenizer_config_needs_v5(model_name: str) -> bool:
         return False
 
 
+def _load_config_json(model_name: str) -> dict | None:
+    """Return parsed ``config.json`` for *model_name*, checking local files first."""
+    if model_name in _config_json_cache:
+        return _config_json_cache[model_name]
+
+    local_cfg = Path(model_name) / "config.json"
+    if local_cfg.is_file():
+        try:
+            with open(local_cfg) as f:
+                cfg = json.load(f)
+            _config_json_cache[model_name] = cfg
+            return cfg
+        except Exception as exc:
+            logger.debug("Could not read %s: %s", local_cfg, exc)
+            _config_json_cache[model_name] = None
+            return None
+
+    if _env_offline():
+        _config_json_cache[model_name] = None
+        return None
+
+    import urllib.request
+
+    url = f"https://huggingface.co/{model_name}/raw/main/config.json"
+    try:
+        req = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio"})
+        with urllib.request.urlopen(req, timeout = 10) as resp:
+            cfg = json.loads(resp.read().decode())
+        _config_json_cache[model_name] = cfg
+        return cfg
+    except Exception as exc:
+        logger.debug("Could not fetch config.json for '%s': %s", model_name, exc)
+        _config_json_cache[model_name] = None
+        return None
+
+
+def _config_matches_tier(cfg: dict, architectures: set[str], model_types: set[str]) -> bool:
+    archs = cfg.get("architectures", [])
+    if any(a in architectures for a in archs):
+        return True
+    if cfg.get("model_type") in model_types:
+        return True
+    return False
+
+
+def _config_needs_550(cfg: dict) -> bool:
+    return _config_matches_tier(
+        cfg,
+        _TRANSFORMERS_550_ARCHITECTURES,
+        _TRANSFORMERS_550_MODEL_TYPES,
+    )
+
+
+def _config_needs_510(cfg: dict) -> bool:
+    return _config_matches_tier(
+        cfg,
+        _TRANSFORMERS_510_ARCHITECTURES,
+        _TRANSFORMERS_510_MODEL_TYPES,
+    )
+
+
 def _check_config_needs_550(model_name: str) -> bool:
     """True if ``config.json`` has architectures/model_type needing transformers
     5.5.0 (e.g. Gemma 4).
@@ -270,81 +389,88 @@ def _check_config_needs_550(model_name: str) -> bool:
     if model_name in _config_needs_550_cache:
         return _config_needs_550_cache[model_name]
 
-    def _check_cfg(cfg: dict) -> bool:
-        archs = cfg.get("architectures", [])
-        if any(a in _TRANSFORMERS_550_ARCHITECTURES for a in archs):
-            return True
-        if cfg.get("model_type") in _TRANSFORMERS_550_MODEL_TYPES:
-            return True
-        return False
-
-    # --- Check local config.json first ------------------------------------
-    local_path = Path(model_name)
-    local_cfg = local_path / "config.json"
-    if local_cfg.is_file():
-        try:
-            with open(local_cfg) as f:
-                cfg = json.load(f)
-            result = _check_cfg(cfg)
-            if result:
-                logger.info(
-                    "Local config.json check: %s needs transformers 5.5.0 "
-                    "(architectures=%s, model_type=%s)",
-                    model_name,
-                    cfg.get("architectures", []),
-                    cfg.get("model_type"),
-                )
-            _config_needs_550_cache[model_name] = result
-            return result
-        except Exception as exc:
-            logger.debug("Could not read %s: %s", local_cfg, exc)
-
-    # Offline: skip the 10s urllib fetch (fail-open to lower tier).
-    if _env_offline():
+    cfg = _load_config_json(model_name)
+    if cfg is None:
         _config_needs_550_cache[model_name] = False
         return False
 
-    # --- Fall back to fetching from HuggingFace ---------------------------
-    import urllib.request
+    result = _config_needs_550(cfg)
+    if result:
+        logger.info(
+            "config.json check: %s needs transformers %s (architectures=%s, model_type=%s)",
+            model_name,
+            TRANSFORMERS_550_VERSION,
+            cfg.get("architectures", []),
+            cfg.get("model_type"),
+        )
+    _config_needs_550_cache[model_name] = result
+    return result
 
-    url = f"https://huggingface.co/{model_name}/raw/main/config.json"
-    try:
-        req = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio"})
-        with urllib.request.urlopen(req, timeout = 10) as resp:
-            cfg = json.loads(resp.read().decode())
-        result = _check_cfg(cfg)
-        if result:
-            logger.info(
-                "Dynamic config.json check: %s needs transformers 5.5.0 "
-                "(architectures=%s, model_type=%s)",
-                model_name,
-                cfg.get("architectures", []),
-                cfg.get("model_type"),
-            )
-        _config_needs_550_cache[model_name] = result
-        return result
-    except Exception as exc:
-        logger.debug("Could not fetch config.json for '%s': %s", model_name, exc)
-        _config_needs_550_cache[model_name] = False
+
+def _check_config_needs_510(model_name: str) -> bool:
+    """Check ``config.json`` for Gemma 4 Unified / 12B architectures."""
+    if model_name in _config_needs_510_cache:
+        return _config_needs_510_cache[model_name]
+
+    cfg = _load_config_json(model_name)
+    if cfg is None:
+        _config_needs_510_cache[model_name] = False
         return False
 
+    result = _config_needs_510(cfg)
+    if result:
+        logger.info(
+            "config.json check: %s needs transformers %s (architectures=%s, model_type=%s)",
+            model_name,
+            TRANSFORMERS_510_VERSION,
+            cfg.get("architectures", []),
+            cfg.get("model_type"),
+        )
+    _config_needs_510_cache[model_name] = result
+    return result
+
 
 def get_transformers_tier(model_name: str) -> str:
     """Return the transformers tier required for *model_name*.
 
-    ``"550"`` for transformers 5.5.0 (e.g. Gemma 4), ``"530"`` for 5.3.0
-    (e.g. Ministral-3, Qwen3 MoE), or ``"default"`` for everything else (4.57.x).
-    The 5.5.0 check runs first, then 5.3.0.
+    Returns ``"510"`` for models needing transformers 5.10.x (Gemma 4 Unified),
+    ``"550"`` for models needing transformers 5.5.0 (Gemma 4),
+    ``"530"`` for models needing transformers 5.3.0 (e.g. Ministral-3, Qwen3 MoE),
+    or ``"default"`` for everything else (4.57.x).
+
+    Higher 5.x tiers run first.
     """
     lowered = model_name.lower()
 
+    # Local checkpoint names can contain architecture substrings in their
+    # directory names (for example a pytest temp dir). If config.json exists,
+    # trust it before using name heuristics.
+    local_cfg = Path(model_name) / "config.json"
+    if local_cfg.is_file():
+        cfg = _load_config_json(model_name)
+        if cfg is not None and _config_needs_510(cfg):
+            return "510"
+        if cfg is not None and _config_needs_550(cfg):
+            return "550"
+        if cfg is not None:
+            local_tc = Path(model_name) / "tokenizer_config.json"
+            if local_tc.is_file() and _check_tokenizer_config_needs_v5(model_name):
+                return "530"
+            return "default"
+
     # --- Fast substring checks (no I/O) ------------------------------------
+    if "assistant" in lowered and ("gemma-4" in lowered or "gemma4" in lowered):
+        return "510"
+    if any(sub in lowered for sub in TRANSFORMERS_510_MODEL_SUBSTRINGS):
+        return "510"
     if any(sub in lowered for sub in TRANSFORMERS_550_MODEL_SUBSTRINGS):
         return "550"
     if any(sub in lowered for sub in TRANSFORMERS_5_MODEL_SUBSTRINGS):
         return "530"
 
-    # --- Slow config fallbacks (local file first, then network) -----------
+    # --- Slow config fallbacks (network for HF IDs) ------------------------
+    if _check_config_needs_510(model_name):
+        return "510"
     if _check_config_needs_550(model_name):
         return "550"
     if _check_tokenizer_config_needs_v5(model_name):
@@ -419,6 +545,13 @@ _VENV_T5_530_PACKAGES = (
     "tiktoken",
 )
 
+_VENV_T5_510_PACKAGES = (
+    f"transformers=={TRANSFORMERS_510_VERSION}",
+    "huggingface_hub==1.8.0",
+    "hf_xet==1.4.2",
+    "tiktoken",
+)
+
 _VENV_T5_550_PACKAGES = (
     f"transformers=={TRANSFORMERS_550_VERSION}",
     "huggingface_hub==1.8.0",
@@ -475,7 +608,7 @@ def _venv_dir_is_valid(venv_dir: str, packages: tuple[str, ...]) -> bool:
 
 
 def _venv_t5_is_valid() -> bool:
-    """Backwards-compat: check the 5.5.0 venv."""
+    """Backwards-compat: check the Gemma 4 sidecar venv."""
     return _venv_dir_is_valid(_VENV_T5_550_DIR, _VENV_T5_550_PACKAGES)
 
 
@@ -553,11 +686,24 @@ def _ensure_venv_t5_530_exists() -> bool:
 
 def _ensure_venv_t5_550_exists() -> bool:
     """Ensure .venv_t5_550/ exists with transformers 5.5.0."""
-    return _ensure_venv_dir(_VENV_T5_550_DIR, _VENV_T5_550_PACKAGES, "transformers 5.5.0")
+    return _ensure_venv_dir(
+        _VENV_T5_550_DIR,
+        _VENV_T5_550_PACKAGES,
+        f"transformers {TRANSFORMERS_550_VERSION}",
+    )
+
+
+def _ensure_venv_t5_510_exists() -> bool:
+    """Ensure .venv_t5_510/ exists with transformers 5.10.x."""
+    return _ensure_venv_dir(
+        _VENV_T5_510_DIR,
+        _VENV_T5_510_PACKAGES,
+        f"transformers {TRANSFORMERS_510_VERSION}",
+    )
 
 
 def _ensure_venv_t5_exists() -> bool:
-    """Backwards-compat: ensure the 5.5.0 venv exists."""
+    """Backwards-compat: ensure the Gemma 4 5.5 sidecar venv exists."""
     return _ensure_venv_t5_550_exists()
 
 
@@ -577,7 +723,7 @@ def _activate_venv(venv_dir: str, label: str) -> None:
 
 def _deactivate_5x() -> None:
     """Remove all .venv_t5_*/ dirs from sys.path, purge stale modules, reimport."""
-    for d in (_VENV_T5_530_DIR, _VENV_T5_550_DIR):
+    for d in (_VENV_T5_530_DIR, _VENV_T5_550_DIR, _VENV_T5_510_DIR):
         while d in sys.path:
             sys.path.remove(d)
     logger.info("Removed venv_t5 dirs from sys.path")
@@ -593,7 +739,9 @@ def _deactivate_5x() -> None:
 def ensure_transformers_version(model_name: str) -> None:
     """Ensure the correct ``transformers`` version is active for *model_name*.
 
-    Uses sys.path with .venv_t5_530/ or .venv_t5_550/ (pre-installed by setup.sh):
+    Uses sys.path with .venv_t5_510/, .venv_t5_550/, or .venv_t5_530/
+    (pre-installed by setup.sh):
+      • Need 5.10.x → prepend .venv_t5_510/ to sys.path, purge modules.
       • Need 5.5.0 → prepend .venv_t5_550/ to sys.path, purge modules.
       • Need 5.3.0 → prepend .venv_t5_530/ to sys.path, purge modules.
       • Need 4.x  → remove all .venv_t5_*/ from sys.path, purge modules.
@@ -608,7 +756,11 @@ def ensure_transformers_version(model_name: str) -> None:
     resolved = _resolve_base_model(model_name)
     tier = get_transformers_tier(resolved)
 
-    if tier == "550":
+    if tier == "510":
+        target_version = TRANSFORMERS_510_VERSION
+        venv_dir = _VENV_T5_510_DIR
+        ensure_fn = _ensure_venv_t5_510_exists
+    elif tier == "550":
         target_version = TRANSFORMERS_550_VERSION
         venv_dir = _VENV_T5_550_DIR
         ensure_fn = _ensure_venv_t5_550_exists
@@ -643,7 +795,7 @@ def ensure_transformers_version(model_name: str) -> None:
                 model_name,
             )
             return
-        # Different 5.x → must switch (e.g. 5.3.0 loaded but need 5.5.0).
+        # Different 5.x -> need to switch (e.g. 5.3.0 loaded but need 5.10.x).
         in_memory_major = int(in_memory.split(".")[0])
         if in_memory_major == target_major and venv_dir is None:
             # Both are default (4.x) — close enough.
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index ce94f651f8..c4ee08a15f 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -1499,13 +1499,60 @@ if ($IsPipInstall) {
     }
 }
 
-# 1g. Python (>= 3.11 and < 3.14). Prefer py.exe so a 3.14 ahead of 3.13 on PATH does not trip the gate.
+# 1g. Python (>= 3.11 and < 3.14). Prefer the Studio venv that install.ps1
+# just created, then py.exe so a 3.14 ahead of 3.13 on PATH does not trip the gate.
 $HasPython = $null -ne (Get-Command python -ErrorAction SilentlyContinue)
 $PyLauncher = Get-Command py -CommandType Application -ErrorAction SilentlyContinue
 $PythonOk = $false
 $DetectedPyVer = $null
 
-if ($PyLauncher) {
+function Get-CompatiblePythonVersion {
+    param([string]$PythonExe)
+    try {
+        $out = & $PythonExe --version 2>&1 | Out-String
+        if ($out -match 'Python (3\.(11|12|13)(\.\d+)?)') {
+            return $Matches[1]
+        }
+    } catch { }
+    return $null
+}
+
+function Add-PythonDirToProcessPath {
+    param([string]$PythonExe)
+    try {
+        if ($PythonExe -and (Test-Path -LiteralPath $PythonExe)) {
+            $resolvedDir = Split-Path -Parent $PythonExe
+            $alreadyOnPath = ($env:PATH -split ';' | Where-Object { $_.TrimEnd('\') -ieq $resolvedDir.TrimEnd('\') }).Count -gt 0
+            if (-not $alreadyOnPath) {
+                $env:PATH = "$resolvedDir;$env:PATH"
+            }
+            $script:HasPython = $true
+        }
+    } catch { }
+}
+
+$_prereqStudioHome = $null
+if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) {
+    $_prereqStudioHome = $env:UNSLOTH_STUDIO_HOME.Trim()
+} elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) {
+    $_prereqStudioHome = $env:STUDIO_HOME.Trim()
+} else {
+    $_prereqStudioHome = Join-Path $env:USERPROFILE ".unsloth\studio"
+}
+if ($_prereqStudioHome -eq "~" -or $_prereqStudioHome -like "~/*" -or $_prereqStudioHome -like "~\*") {
+    $_prereqStudioHome = (Join-Path $env:USERPROFILE $_prereqStudioHome.Substring(1).TrimStart('/','\'))
+}
+$_prereqVenvPython = Join-Path $_prereqStudioHome "unsloth_studio\Scripts\python.exe"
+if (Test-Path -LiteralPath $_prereqVenvPython) {
+    $_venvPyVer = Get-CompatiblePythonVersion $_prereqVenvPython
+    if ($_venvPyVer) {
+        $DetectedPyVer = $_venvPyVer
+        Add-PythonDirToProcessPath $_prereqVenvPython
+        $PythonOk = $true
+    }
+}
+
+if (-not $PythonOk -and $PyLauncher) {
     foreach ($minor in @("3.13", "3.12", "3.11")) {
         try {
             $out = & $PyLauncher.Source "-$minor" --version 2>&1 | Out-String
@@ -1517,12 +1564,7 @@ if ($PyLauncher) {
                 try {
                     $resolvedExe = (& $PyLauncher.Source "-$minor" -c "import sys; print(sys.executable)" 2>$null | Select-Object -First 1)
                     if ($resolvedExe -and (Test-Path $resolvedExe)) {
-                        $resolvedDir = Split-Path -Parent $resolvedExe
-                        $alreadyOnPath = ($env:PATH -split ';' | Where-Object { $_.TrimEnd('\') -ieq $resolvedDir.TrimEnd('\') }).Count -gt 0
-                        if (-not $alreadyOnPath) {
-                            $env:PATH = "$resolvedDir;$env:PATH"
-                        }
-                        $HasPython = $true
+                        Add-PythonDirToProcessPath $resolvedExe
                     }
                 } catch { }
                 $PythonOk = $true
@@ -2340,14 +2382,35 @@ if ($stackExit -ne 0) {
     $ErrorActionPreference = $prevEAP
 }
 
-# ── Pre-install transformers 5.x into .venv_t5_530/ and .venv_t5_550/ ──
+# ── Pre-install transformers 5.x into .venv_t5_530/, .venv_t5_550/, and .venv_t5_510/ ──
 # Runs outside the deps fast-path gate so that upgrades from the legacy
 # single .venv_t5 are always migrated to the tiered layout.
 # T5 sidecar venvs live under the resolved $StudioHome so custom installs are self-contained.
 $VenvT5_530Dir = Join-Path $StudioHome ".venv_t5_530"
 $VenvT5_550Dir = Join-Path $StudioHome ".venv_t5_550"
+$VenvT5_510Dir = Join-Path $StudioHome ".venv_t5_510"
 $VenvT5Legacy = Join-Path $StudioHome ".venv_t5"
 
+function Test-TargetPackageVersion {
+    param(
+        [Parameter(Mandatory = $true)][string]$TargetDir,
+        [Parameter(Mandatory = $true)][string]$PackageName,
+        [Parameter(Mandatory = $true)][string]$ExpectedVersion
+    )
+    if (-not (Test-Path -LiteralPath $TargetDir -PathType Container)) { return $false }
+    $packageNorm = $PackageName.Replace("-", "_")
+    foreach ($pattern in @("$packageNorm-*.dist-info", "$PackageName-*.dist-info")) {
+        foreach ($distInfo in @(Get-ChildItem -LiteralPath $TargetDir -Directory -Filter $pattern -ErrorAction SilentlyContinue)) {
+            $metadata = Join-Path $distInfo.FullName "METADATA"
+            if (-not (Test-Path -LiteralPath $metadata -PathType Leaf)) { continue }
+            foreach ($line in (Get-Content -LiteralPath $metadata -ErrorAction SilentlyContinue)) {
+                if ($line -eq "Version: $ExpectedVersion") { return $true }
+            }
+        }
+    }
+    return $false
+}
+
 $_NeedT5Install = $false
 if (Test-Path -LiteralPath $VenvT5Legacy) {
     Assert-StudioOwnedOrAbsent -Path $VenvT5Legacy -Label "legacy transformers sidecar venv"
@@ -2356,6 +2419,10 @@ if (Test-Path -LiteralPath $VenvT5Legacy) {
 }
 if (-not (Test-Path -LiteralPath $VenvT5_530Dir)) { $_NeedT5Install = $true }
 if (-not (Test-Path -LiteralPath $VenvT5_550Dir)) { $_NeedT5Install = $true }
+if (-not (Test-Path -LiteralPath $VenvT5_510Dir)) { $_NeedT5Install = $true }
+if (-not (Test-TargetPackageVersion -TargetDir $VenvT5_530Dir -PackageName "transformers" -ExpectedVersion "5.3.0")) { $_NeedT5Install = $true }
+if (-not (Test-TargetPackageVersion -TargetDir $VenvT5_550Dir -PackageName "transformers" -ExpectedVersion "5.5.0")) { $_NeedT5Install = $true }
+if (-not (Test-TargetPackageVersion -TargetDir $VenvT5_510Dir -PackageName "transformers" -ExpectedVersion "5.10.2")) { $_NeedT5Install = $true }
 # Also reinstall when python deps were updated
 if (-not $SkipPythonDeps) { $_NeedT5Install = $true }
 
@@ -2433,9 +2500,44 @@ if ($script:UnslothVerbose) {
 if ($tiktokenInstallExit -ne 0) {
     substep "Could not install tiktoken into .venv_t5_550/ -- Qwen tokenizers may fail" "Yellow"
 }
-$ErrorActionPreference = $prevEAP_t5
 step "transformers" "5.5.0 pre-installed"
 
+# --- .venv_t5_510 (transformers 5.10.2) ---
+substep "pre-installing transformers 5.10.2 for Gemma 4 Unified support..."
+Assert-StudioOwnedOrAbsent -Path $VenvT5_510Dir -Label "transformers 5.10 sidecar venv"
+if (Test-Path -LiteralPath $VenvT5_510Dir) { Remove-Item -LiteralPath $VenvT5_510Dir -Recurse -Force }
+[System.IO.Directory]::CreateDirectory($VenvT5_510Dir) | Out-Null
+Mark-StudioOwned -Path $VenvT5_510Dir
+foreach ($pkg in @("transformers==5.10.2", "huggingface_hub==1.8.0", "hf_xet==1.4.2")) {
+    if ($script:UnslothVerbose) {
+        Fast-Install --target $VenvT5_510Dir --no-deps $pkg
+        $t5PkgExit = $LASTEXITCODE
+        $output = ""
+    } else {
+        $output = Fast-Install --target $VenvT5_510Dir --no-deps $pkg | Out-String
+        $t5PkgExit = $LASTEXITCODE
+    }
+    if ($t5PkgExit -ne 0) {
+        Write-Host "[FAIL] Could not install $pkg into .venv_t5_510/" -ForegroundColor Red
+        Write-Host $output -ForegroundColor Red
+        $ErrorActionPreference = $prevEAP_t5
+        exit 1
+    }
+}
+if ($script:UnslothVerbose) {
+    Fast-Install --target $VenvT5_510Dir tiktoken
+    $tiktokenInstallExit = $LASTEXITCODE
+    $output = ""
+} else {
+    $output = Fast-Install --target $VenvT5_510Dir tiktoken | Out-String
+    $tiktokenInstallExit = $LASTEXITCODE
+}
+if ($tiktokenInstallExit -ne 0) {
+    substep "Could not install tiktoken into .venv_t5_510/ -- Qwen tokenizers may fail" "Yellow"
+}
+$ErrorActionPreference = $prevEAP_t5
+step "transformers" "5.10.2 pre-installed"
+
 } # end $_NeedT5Install
 
 # ==========================================================================
diff --git a/studio/setup.sh b/studio/setup.sh
index 42e9f23626..3e9c9ef3d6 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -587,6 +587,7 @@ fi
 VENV_DIR="$STUDIO_HOME/unsloth_studio"
 VENV_T5_530_DIR="$STUDIO_HOME/.venv_t5_530"
 VENV_T5_550_DIR="$STUDIO_HOME/.venv_t5_550"
+VENV_T5_510_DIR="$STUDIO_HOME/.venv_t5_510"
 
 [ -d "$REPO_ROOT/.venv" ] && rm -rf "$REPO_ROOT/.venv"
 [ -d "$REPO_ROOT/.venv_overlay" ] && rm -rf "$REPO_ROOT/.venv_overlay"
@@ -700,9 +701,9 @@ else
     verbose_substep "python deps check: installed=$_PKG_NAME@${INSTALLED_VER:-unknown} latest=${LATEST_VER:-unknown}"
 fi
 
-# ── 6b. Pre-install transformers 5.x into .venv_t5_530/ and .venv_t5_550/ ──
+# ── 6b. Pre-install transformers 5.x into .venv_t5_530/, .venv_t5_550/, and .venv_t5_510/ ──
 # Models like GLM-4.7-Flash, Qwen3 MoE need transformers>=5.3.0.
-# Gemma 4 models need transformers>=5.5.0.
+# Gemma 4 models need transformers>=5.5.0; Gemma 4 Unified needs 5.10.x.
 # Pre-install into separate directories to avoid runtime pip overhead.
 # The training subprocess prepends the appropriate dir to sys.path.
 #
@@ -737,6 +738,21 @@ _assert_studio_owned_or_absent() {
         exit 1
     fi
 }
+_target_has_pkg_version() {
+    _thpv_dir="$1"
+    _thpv_pkg="$2"
+    _thpv_version="$3"
+    [ -d "$_thpv_dir" ] || return 1
+    _thpv_pkg_norm=$(printf '%s' "$_thpv_pkg" | tr '-' '_')
+    for _thpv_metadata in \
+        "$_thpv_dir"/"$_thpv_pkg_norm"-*.dist-info/METADATA \
+        "$_thpv_dir"/"$_thpv_pkg"-*.dist-info/METADATA
+    do
+        [ -f "$_thpv_metadata" ] || continue
+        grep -qx "Version: $_thpv_version" "$_thpv_metadata" && return 0
+    done
+    return 1
+}
 _NEED_T5_INSTALL=false
 if [ -d "$STUDIO_HOME/.venv_t5" ]; then
     # Legacy layout — migrate
@@ -746,6 +762,10 @@ if [ -d "$STUDIO_HOME/.venv_t5" ]; then
 fi
 [ ! -d "$VENV_T5_530_DIR" ] && _NEED_T5_INSTALL=true
 [ ! -d "$VENV_T5_550_DIR" ] && _NEED_T5_INSTALL=true
+[ ! -d "$VENV_T5_510_DIR" ] && _NEED_T5_INSTALL=true
+_target_has_pkg_version "$VENV_T5_530_DIR" "transformers" "5.3.0" || _NEED_T5_INSTALL=true
+_target_has_pkg_version "$VENV_T5_550_DIR" "transformers" "5.5.0" || _NEED_T5_INSTALL=true
+_target_has_pkg_version "$VENV_T5_510_DIR" "transformers" "5.10.2" || _NEED_T5_INSTALL=true
 # Also reinstall when python deps were updated (packages may need rebuild)
 [ "$_SKIP_PYTHON_DEPS" = false ] && _NEED_T5_INSTALL=true
 
@@ -769,6 +789,16 @@ if [ "$_NEED_T5_INSTALL" = true ]; then
     run_quiet "install hf_xet for t5_550" fast_install --target "$VENV_T5_550_DIR" --no-deps "hf_xet==1.4.2"
     run_quiet "install tiktoken for t5_550" fast_install --target "$VENV_T5_550_DIR" "tiktoken"
     step "transformers" "5.5.0 pre-installed"
+
+    _assert_studio_owned_or_absent "$VENV_T5_510_DIR" "transformers 5.10 sidecar venv"
+    [ -d "$VENV_T5_510_DIR" ] && rm -rf "$VENV_T5_510_DIR"
+    mkdir -p "$VENV_T5_510_DIR"
+    : > "$VENV_T5_510_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || true
+    run_quiet "install transformers 5.10.2" fast_install --target "$VENV_T5_510_DIR" --no-deps "transformers==5.10.2"
+    run_quiet "install huggingface_hub for t5_510" fast_install --target "$VENV_T5_510_DIR" --no-deps "huggingface_hub==1.8.0"
+    run_quiet "install hf_xet for t5_510" fast_install --target "$VENV_T5_510_DIR" --no-deps "hf_xet==1.4.2"
+    run_quiet "install tiktoken for t5_510" fast_install --target "$VENV_T5_510_DIR" "tiktoken"
+    step "transformers" "5.10.2 pre-installed"
 fi
 fi
 

From 2b319e8d3a21b09494784509281988481aad0e31 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Wed, 10 Jun 2026 12:45:12 -0300
Subject: [PATCH 160/222] Studio: support separate-file MTP GGUF drafters
 (Gemma 4) (#6125)

* Studio: support separate-file MTP GGUF drafters (Gemma 4)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: fix review findings for separate-file MTP drafters

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: pair local MTP drafters by name and include them in reload dedup

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: manage --model-draft in extras and reject MTP/ copies as models

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    | 521 +++++++++++++-----
 .../core/inference/llama_server_args.py       |   8 +-
 studio/backend/hub/services/models/common.py  |   7 +-
 .../backend/hub/services/models/deletion.py   |   6 +-
 .../hub/services/models/gguf_variants.py      |   9 +-
 studio/backend/hub/utils/gguf.py              |  36 +-
 studio/backend/hub/utils/gguf_plan.py         |  77 ++-
 studio/backend/hub/utils/inventory_scan.py    |   9 +-
 studio/backend/models/inference.py            |   2 +-
 studio/backend/routes/inference.py            | 102 +++-
 .../backend/tests/test_llama_server_args.py   |  25 +
 .../tests/test_mtp_drafter_companion.py       | 276 ++++++++++
 studio/backend/utils/models/model_config.py   | 120 +++-
 13 files changed, 1008 insertions(+), 190 deletions(-)
 create mode 100644 studio/backend/tests/test_mtp_drafter_companion.py

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 317c9c7f21..ead962aac7 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -23,7 +23,7 @@ import sys
 import threading
 import time
 from pathlib import Path
-from typing import Generator, Iterable, List, Optional
+from typing import Callable, Generator, Iterable, List, Optional
 
 import httpx
 
@@ -481,6 +481,45 @@ def _is_mtp_model_name(model_identifier: Optional[str], gguf_path: Optional[str]
     return False
 
 
+def _is_companion_gguf_path(path: str) -> bool:
+    """True for a non-main GGUF: vision mmproj or a separate MTP drafter
+    (repo-root ``mtp-*.gguf`` or the ``MTP/`` subdir copies, Gemma 4).
+
+    Mirrors hub.utils.gguf so variant resolution never picks a companion as
+    the main model -- e.g. a Gemma ``Q8_0`` request must not resolve to the
+    ``MTP/...-Q8_0-MTP.gguf`` drafter, which sorts ahead of the real weight.
+    """
+    p = path.lower()
+    if not p.endswith(".gguf"):
+        return False
+    if "mmproj" in p:
+        return True
+    name = p.rsplit("/", 1)[-1]
+    return name.startswith("mtp-") or "/mtp/" in f"/{p}"
+
+
+# Below this many B params, draft-mtp regresses vs spec-off (bench in
+# _build_speculative_flags); auto mode drops MTP under it.
+_MTP_MIN_SIZE_B = 3.0
+
+# Context-fit VRAM budget: tighter than _GPU_PIN_VRAM_FRACTION (0.95) on
+# purpose -- over-promising context OOMs at runtime (#5106).
+_CTX_FIT_VRAM_FRACTION = 0.90
+
+# Extra VRAM fraction reserved when MTP will engage: the draft model's
+# weights, KV cache, and compute buffers live outside the main model's
+# estimate. Applied to BOTH the ctx-fit budget and the GPU pin thresholds --
+# tightening only the fit lets a load whose weights land between the two
+# fractions pin without any room for the drafter.
+_MTP_VRAM_RESERVE_FRAC = 0.05
+
+
+def _auto_mode_drops_mtp(req_mode: Optional[str], size_b: Optional[float]) -> bool:
+    """Auto mode drops MTP below _MTP_MIN_SIZE_B (draft-mtp regresses there);
+    forced mtp / mtp+ngram engage regardless of size."""
+    return req_mode == "auto" and size_b is not None and size_b < _MTP_MIN_SIZE_B
+
+
 def _extra_args_set_spec_type(extra_args: Optional[Iterable[str]]) -> bool:
     """User passed --spec-type / --spec-default? llama-server takes one
     --spec-type (comma-separated to chain), so suppress auto-emit."""
@@ -625,6 +664,9 @@ class LlamaCppBackend:
         self._model_identifier: Optional[str] = None
         self._gguf_path: Optional[str] = None
         self._hf_repo: Optional[str] = None
+        # Separate MTP drafter launched with the current model; reload-dedup
+        # key so a drafter that appears next to the weights forces a reload.
+        self._mtp_draft_path: Optional[str] = None
         self._hf_variant: Optional[str] = None
         self._is_vision: bool = False
         self._healthy = False
@@ -732,6 +774,14 @@ class LlamaCppBackend:
     def hf_variant(self) -> Optional[str]:
         return self._hf_variant
 
+    @property
+    def gguf_path(self) -> Optional[str]:
+        return self._gguf_path
+
+    @property
+    def mtp_draft_path(self) -> Optional[str]:
+        return self._mtp_draft_path
+
     @property
     def extra_args(self) -> Optional[List[str]]:
         """Extra llama-server flags from the last load (a copy). None =
@@ -1484,13 +1534,16 @@ class LlamaCppBackend:
 
     @staticmethod
     def _select_gpus(
-        model_size_bytes: int, gpus: list[tuple[int, int]]
+        model_size_bytes: int,
+        gpus: list[tuple[int, int]],
+        usable_fraction: Optional[float] = None,
     ) -> tuple[Optional[list[int]], bool]:
         """Pick GPU(s) for a model from estimated VRAM and free memory.
 
         ``model_size_bytes`` should include weights and estimated KV cache.
-        ``_GPU_PIN_VRAM_FRACTION`` provides headroom for compute buffers,
-        CUDA context, and other runtime overhead.
+        ``usable_fraction`` (default ``_GPU_PIN_VRAM_FRACTION``) provides
+        headroom for compute buffers, CUDA context, and other runtime
+        overhead; callers lower it when MTP reserves VRAM for a draft model.
 
         Returns (gpu_indices, use_fit):
           - ([1], False)       fits on 1 GPU at the headroom threshold
@@ -1501,7 +1554,8 @@ class LlamaCppBackend:
             return None, True
 
         model_size_mib = model_size_bytes / (1024 * 1024)
-        usable_fraction = LlamaCppBackend._GPU_PIN_VRAM_FRACTION
+        if usable_fraction is None:
+            usable_fraction = LlamaCppBackend._GPU_PIN_VRAM_FRACTION
 
         # Sort GPUs by free memory descending
         ranked = sorted(gpus, key = lambda g: g[1], reverse = True)
@@ -1749,8 +1803,8 @@ class LlamaCppBackend:
             ctx_checkpoints = ctx_checkpoints,
         )
 
-        # MTP needs a tighter budget; drop from 0.90 to 0.85.
-        budget_frac = 0.85 if mtp_engaged else 0.90
+        # MTP engaged: carve the drafter's reserve out of the fit budget.
+        budget_frac = _CTX_FIT_VRAM_FRACTION - (_MTP_VRAM_RESERVE_FRAC if mtp_engaged else 0.0)
         budget_bytes = available_mib * 1024 * 1024 * budget_frac
         model_footprint = model_size_bytes
 
@@ -1808,7 +1862,9 @@ class LlamaCppBackend:
             from huggingface_hub import get_paths_info, list_repo_files
 
             files = list_repo_files(hf_repo, token = hf_token)
-            gguf_files = [f for f in files if f.endswith(".gguf") and "mmproj" not in f.lower()]
+            gguf_files = [
+                f for f in files if f.endswith(".gguf") and not _is_companion_gguf_path(f)
+            ]
             if not gguf_files:
                 return None
 
@@ -2169,7 +2225,11 @@ class LlamaCppBackend:
                     r"(?<![a-zA-Z0-9])" + re.escape(variant_lower) + r"(?![a-zA-Z0-9])"
                 )
                 gguf_files = sorted(
-                    f for f in files if f.endswith(".gguf") and boundary.search(f.lower())
+                    f
+                    for f in files
+                    if f.endswith(".gguf")
+                    and boundary.search(f.lower())
+                    and not _is_companion_gguf_path(f)
                 )
                 if gguf_files:
                     gguf_filename = gguf_files[0]
@@ -2199,7 +2259,7 @@ class LlamaCppBackend:
                         matches = sorted(
                             p.relative_to(snap).as_posix()
                             for p in snap.rglob("*.gguf")
-                            if "mmproj" not in p.name.lower()
+                            if not _is_companion_gguf_path(p.relative_to(snap).as_posix())
                             and boundary.search(p.relative_to(snap).as_posix().lower())
                         )
                         if not matches:
@@ -2303,7 +2363,7 @@ class LlamaCppBackend:
                                 for f in all_gguf_files
                                 if f.startswith(_prefix)
                                 and f != gguf_filename
-                                and "mmproj" not in f.lower()
+                                and not _is_companion_gguf_path(f)
                             )
                         else:
                             gguf_extra_shards = []
@@ -2357,6 +2417,58 @@ class LlamaCppBackend:
             logger.info(f"GGUF downloaded in {dl_elapsed:.1f}s: {local_path}")
         return local_path
 
+    def _download_companion_gguf(
+        self,
+        *,
+        hf_repo: str,
+        hf_token: Optional[str],
+        pick: Callable[[list[str]], Optional[str]],
+        label: str,
+    ) -> Optional[str]:
+        """Resolve and fetch a companion GGUF (mmproj / MTP drafter) by name.
+
+        Tries the live repo file list, then the local HF cache snapshots
+        (offline, same fallback as _download_gguf), then hf_hub_download.
+        Runs WITHOUT self._lock (like _download_gguf); honors _cancel_event so
+        an /unload between the main download and here skips the fetch.
+        """
+        if self._cancel_event.is_set():
+            return None
+
+        target: Optional[str] = None
+        try:
+            from huggingface_hub import list_repo_files
+            target = pick(list_repo_files(hf_repo, token = hf_token))
+        except Exception as e:
+            logger.debug(f"Could not list repo files for {label}: {e}")
+
+        if target is None:
+            try:
+                from utils.models.model_config import _iter_hf_cache_snapshots
+                for snap in _iter_hf_cache_snapshots(hf_repo):
+                    rel_files = [p.relative_to(snap).as_posix() for p in snap.rglob("*.gguf")]
+                    target = pick(rel_files)
+                    if target is not None:
+                        logger.info("Resolved %s %s from local HF cache", label, target)
+                        break
+            except Exception as e:
+                logger.debug(f"Offline cache lookup for {label} failed: {e}")
+
+        if target is None or self._cancel_event.is_set():
+            return None
+
+        try:
+            from huggingface_hub import hf_hub_download
+            logger.info(f"Downloading {label}: {hf_repo}/{target}")
+            return hf_hub_download(
+                repo_id = hf_repo,
+                filename = target,
+                token = hf_token,
+            )
+        except Exception as e:
+            logger.warning(f"Could not download {label}: {e}")
+            return None
+
     def _download_mmproj(
         self,
         *,
@@ -2382,43 +2494,43 @@ class LlamaCppBackend:
                     return f
             return mmproj_files[0]
 
-        target: Optional[str] = None
-        try:
-            from huggingface_hub import list_repo_files
-            target = _pick_mmproj(list_repo_files(hf_repo, token = hf_token))
-        except Exception as e:
-            logger.debug(f"Could not list repo files for mmproj: {e}")
+        return self._download_companion_gguf(
+            hf_repo = hf_repo,
+            hf_token = hf_token,
+            pick = _pick_mmproj,
+            label = "mmproj",
+        )
 
-        # Offline: resolve mmproj from the local HF cache snapshot, same as
-        # _download_gguf's offline fallback above.
-        if target is None:
-            try:
-                from utils.models.model_config import _iter_hf_cache_snapshots
-                for snap in _iter_hf_cache_snapshots(hf_repo):
-                    rel_files = [p.relative_to(snap).as_posix() for p in snap.rglob("*.gguf")]
-                    target = _pick_mmproj(rel_files)
-                    if target is not None:
-                        logger.info("Resolved mmproj %s from local HF cache", target)
-                        break
-            except Exception as e:
-                logger.debug(f"Offline cache lookup for mmproj failed: {e}")
+    def _download_mtp(
+        self,
+        *,
+        hf_repo: str,
+        hf_token: Optional[str] = None,
+    ) -> Optional[str]:
+        """Download the separate MTP drafter (speculative head) from a GGUF repo.
 
-        if target is None:
-            return None
+        Targets the repo-root ``mtp-*.gguf`` companion -- the Q8_0 drafter
+        unsloth mirrors there for llama.cpp ``-hf`` auto-discovery (smallest,
+        recommended for speculation). Repos that bake the MTP head into the
+        main GGUF (e.g. Qwen) ship no such sibling and this returns None. The
+        higher-precision copies under ``MTP/`` are for explicit selection and
+        are intentionally skipped. Returns the local path, or None.
+        """
 
-        try:
-            from huggingface_hub import hf_hub_download
-
-            logger.info(f"Downloading mmproj: {hf_repo}/{target}")
-            local_path = hf_hub_download(
-                repo_id = hf_repo,
-                filename = target,
-                token = hf_token,
+        def _pick_mtp(candidates: list[str]) -> Optional[str]:
+            mtp_files = sorted(
+                f
+                for f in candidates
+                if f.lower().endswith(".gguf") and Path(f).name.lower().startswith("mtp-")
             )
-            return local_path
-        except Exception as e:
-            logger.warning(f"Could not download mmproj: {e}")
-            return None
+            return mtp_files[0] if mtp_files else None
+
+        return self._download_companion_gguf(
+            hf_repo = hf_repo,
+            hf_token = hf_token,
+            pick = _pick_mtp,
+            label = "MTP drafter",
+        )
 
     def _resolve_launch_mmproj_path(
         self, *, model_path: str, mmproj_path: Optional[str]
@@ -2446,6 +2558,19 @@ class LlamaCppBackend:
 
         return str(mmproj)
 
+    def _resolve_launch_mtp_path(self, *, mtp_draft_path: Optional[str]) -> Optional[str]:
+        """Return mtp_draft_path iff it exists on disk, else None.
+
+        No family check needed: the drafter is only ever auto-resolved from
+        the same repo as the main GGUF (see _download_mtp).
+        """
+        if not mtp_draft_path:
+            return None
+        if not Path(mtp_draft_path).is_file():
+            logger.warning(f"MTP drafter file not found: {mtp_draft_path}")
+            return None
+        return str(mtp_draft_path)
+
     # ── Lifecycle ─────────────────────────────────────────────────
 
     # GGUF ``general.architecture`` values for diffusion / image models.
@@ -2550,6 +2675,8 @@ class LlamaCppBackend:
         gguf_path: Optional[str] = None,
         # Vision projection (mmproj) for local vision models
         mmproj_path: Optional[str] = None,
+        # Separate MTP drafter for local Gemma loads (HF loads auto-resolve it)
+        mtp_draft_path: Optional[str] = None,
         # HF mode: let llama-server download via -hf "repo:quant"
         hf_repo: Optional[str] = None,
         hf_variant: Optional[str] = None,
@@ -2582,6 +2709,7 @@ class LlamaCppBackend:
             # live server already satisfies this request.
             if self._already_in_target_state(
                 gguf_path = gguf_path,
+                mtp_draft_path = mtp_draft_path,
                 model_identifier = model_identifier,
                 hf_variant = hf_variant,
                 n_ctx = n_ctx,
@@ -2653,6 +2781,8 @@ class LlamaCppBackend:
                 )
 
             # ── Phase 2: download (NO lock held, so cancel can proceed) ──
+            # mtp_draft_path arrives set for local Gemma loads (detected
+            # sibling); for -hf loads it's None here and resolved just below.
             # Scope HF_HUB_OFFLINE to the download block only when DNS is
             # dead; cleanup runs even on exception so a transient hiccup
             # can't quarantine future loads.
@@ -2669,6 +2799,28 @@ class LlamaCppBackend:
                             hf_repo = hf_repo,
                             hf_token = hf_token,
                         )
+                    # Auto-download the separate MTP drafter (e.g. Gemma) when
+                    # the requested spec mode can use it. Repos with the head
+                    # baked into the main GGUF (Qwen) have no mtp- sibling and
+                    # this no-ops. Skipped when the user disabled MTP, drives
+                    # --spec-type manually via extra_args, or in auto mode on a
+                    # sub-3B model (e.g. Gemma E2B) where the resolver drops
+                    # MTP anyway -- no point fetching a drafter it never uses.
+                    # Forced mtp / mtp+ngram still download (user override).
+                    _spec_canon = _canonicalize_spec_mode(speculative_type) or "auto"
+                    _auto_drops_mtp = _auto_mode_drops_mtp(
+                        _spec_canon, _extract_model_size_b(model_identifier)
+                    )
+                    if (
+                        not mtp_draft_path
+                        and _spec_canon in ("auto", "mtp", "mtp+ngram")
+                        and not _auto_drops_mtp
+                        and not _extra_args_set_spec_type(extra_args)
+                    ):
+                        mtp_draft_path = self._download_mtp(
+                            hf_repo = hf_repo,
+                            hf_token = hf_token,
+                        )
             elif gguf_path:
                 if not Path(gguf_path).is_file():
                     raise FileNotFoundError(f"GGUF file not found: {gguf_path}")
@@ -2736,12 +2888,15 @@ class LlamaCppBackend:
                     # Will MTP engage on this load? If so, auto-fit reserves
                     # extra VRAM for the draft model. Mirrors
                     # _build_speculative_flags' resolver: forced mtp / mtp+ngram
-                    # always engage; auto only on an MTP GGUF >= 3B; ngram /
-                    # ngram-simple / off never engage MTP.
+                    # always engage; auto only on an MTP model >= 3B; ngram /
+                    # ngram-simple / off never engage MTP. A separate drafter
+                    # (Gemma) counts as an MTP model just like a baked-in head.
                     _mtp_canonical = _canonicalize_spec_mode(speculative_type)
                     _mtp_effective = _mtp_canonical or "auto"
                     _mtp_size_for_fit = _extract_model_size_b(model_identifier)
-                    _mtp_sub_3b_for_fit = _mtp_size_for_fit is not None and _mtp_size_for_fit < 3.0
+                    _mtp_sub_3b_for_fit = (
+                        _mtp_size_for_fit is not None and _mtp_size_for_fit < _MTP_MIN_SIZE_B
+                    )
                     _mtp_will_engage = bool(
                         not _extra_args_set_spec_type(extra_args)
                         and (
@@ -2751,6 +2906,7 @@ class LlamaCppBackend:
                                 and (
                                     bool(self._nextn_predict_layers)
                                     or _is_mtp_model_name(model_identifier, model_path)
+                                    or bool(mtp_draft_path)
                                 )
                                 and not _mtp_sub_3b_for_fit
                             )
@@ -2766,6 +2922,11 @@ class LlamaCppBackend:
                     #     context, since multi-GPU is slower.
                     gpu_indices, use_fit = None, True
                     explicit_ctx = requested_ctx > 0
+                    # MTP draft model lives outside the main estimates; carve
+                    # its reserve out of every fit budget and pin threshold so
+                    # a load can't pin into the drafter's headroom.
+                    _mtp_reserve = _MTP_VRAM_RESERVE_FRAC if _mtp_will_engage else 0.0
+                    _pin_fraction = self._GPU_PIN_VRAM_FRACTION - _mtp_reserve
 
                     if gpus and self._can_estimate_kv() and effective_ctx > 0:
                         # Largest hardware-aware cap from the native context
@@ -2790,7 +2951,7 @@ class LlamaCppBackend:
                                     capped, cache_type_kv, n_parallel = n_parallel
                                 )
                                 total_mib = (model_size + kv) / (1024 * 1024)
-                                if total_mib <= pool_mib * 0.90:
+                                if total_mib <= pool_mib * (_CTX_FIT_VRAM_FRACTION - _mtp_reserve):
                                     best_cap = max(best_cap, capped)
                             if best_cap > 0:
                                 max_available_ctx = best_cap
@@ -2807,13 +2968,15 @@ class LlamaCppBackend:
                             requested_total = model_size + self._estimate_kv_cache_bytes(
                                 effective_ctx, cache_type_kv, n_parallel = n_parallel
                             )
-                            gpu_indices, use_fit = self._select_gpus(requested_total, gpus)
+                            gpu_indices, use_fit = self._select_gpus(
+                                requested_total, gpus, usable_fraction = _pin_fraction
+                            )
                             # No silent shrink: effective_ctx stays == requested_ctx.
                         else:
                             # Auto context: prefer fewer GPUs, cap to fit. Same
                             # headroom threshold as _select_gpus (#5106).
                             ranked = sorted(gpus, key = lambda g: g[1], reverse = True)
-                            pin_fraction = self._GPU_PIN_VRAM_FRACTION
+                            pin_fraction = _pin_fraction
                             for n_gpus in range(1, len(ranked) + 1):
                                 subset = ranked[:n_gpus]
                                 pool_mib = sum(free for _, free in subset)
@@ -2861,7 +3024,9 @@ class LlamaCppBackend:
                             "Falling back to file-size-only GPU selection",
                             model_size_gb = round(model_size / (1024**3), 2),
                         )
-                        gpu_indices, use_fit = self._select_gpus(model_size, gpus)
+                        gpu_indices, use_fit = self._select_gpus(
+                            model_size, gpus, usable_fraction = _pin_fraction
+                        )
                         if use_fit and not explicit_ctx:
                             # Weights don't fit on any subset; default UI to 4096
                             # so the slider isn't on an unusable native ctx.
@@ -2978,6 +3143,9 @@ class LlamaCppBackend:
 
                 # Speculative decoding. See _build_speculative_flags for the
                 # mode resolution, benchmarks, and llama.cpp references.
+                launch_mtp_draft_path = self._resolve_launch_mtp_path(
+                    mtp_draft_path = mtp_draft_path,
+                )
                 spec_flags = self._build_speculative_flags(
                     speculative_type = speculative_type,
                     spec_draft_n_max = spec_draft_n_max,
@@ -2986,7 +3154,11 @@ class LlamaCppBackend:
                     model_path = model_path,
                     gpus = bool(gpus),
                     binary = binary,
+                    mtp_draft_path = launch_mtp_draft_path,
                 )
+                # Remember where the spec block sits so a drafter-load failure
+                # can be retried with these flags swapped out (see below).
+                _spec_start = len(cmd)
                 cmd.extend(spec_flags)
 
                 # Apply custom chat template override if provided.
@@ -3184,84 +3356,87 @@ class LlamaCppBackend:
                 # retry once with --fit off before declaring the load failed.
                 # Never retry when fit was requested (use_fit) or the caller
                 # passed an explicit fit flag via extra args.
-                _fit_retry_allowed = self._fit_off_retry_eligible(cmd, use_fit)
-                for _spawn_attempt in (0, 1):
-                    # Defensive kill: drop an orphan Popen a concurrent load may
-                    # have stored before we overwrite the reference (#5161).
-                    # Also reaps the crashed first attempt on the retry pass.
-                    self._kill_process()
+                def _spawn_and_wait(run_cmd, *, label = ""):
+                    """Start llama-server with run_cmd and wait for health.
 
-                    self._stdout_lines = []
-                    # Tee llama-server output to a dedicated log file so a
-                    # post-mortem has the full trail even when the parent only
-                    # kept the last 50 lines. Path is under the studio home.
-                    self._llama_log_fh = None
-                    try:
-                        log_dir = _swa_cache_path().parent / "logs" / "llama-server"
-                        log_dir.mkdir(parents = True, exist_ok = True)
-                        # Include the attempt index: the --fit off retry can
-                        # respawn within the same epoch second, and reusing the
-                        # name would truncate the crash log the retry warning
-                        # just pointed the user at.
-                        self._llama_log_path = log_dir / (
-                            f"llama-{int(time.time())}-port-{self._port}"
-                            f"-try{_spawn_attempt}.log"
-                        )
-                        self._llama_log_fh = open(
-                            self._llama_log_path,
-                            "w",
-                            encoding = "utf-8",
-                            buffering = 1,
-                        )
-                        logger.info(f"llama-server stdout/stderr -> {self._llama_log_path}")
-                    except OSError as e:
-                        # Best-effort; never block the load on logging.
-                        logger.debug(f"Could not open llama-server log file: {e}")
-                        self._llama_log_path = None
-                    self._process = subprocess.Popen(
-                        cmd,
-                        stdout = subprocess.PIPE,
-                        stderr = subprocess.STDOUT,
-                        text = True,
-                        env = env,
-                        **_windows_hidden_subprocess_kwargs(),
-                    )
+                    Retries once with --fit off when the first attempt
+                    crashes during startup and run_cmd is eligible (see
+                    _fit_off_retry_eligible).
+                    """
+                    _fit_retry_allowed = self._fit_off_retry_eligible(run_cmd, use_fit)
+                    for _spawn_attempt in (0, 1):
+                        # Defensive kill: drop an orphan Popen a concurrent load may
+                        # have stored before we overwrite the reference (#5161).
+                        # Also reaps the crashed first attempt on the retry pass.
+                        self._kill_process()
 
-                    # Background thread to drain stdout (prevents pipe deadlock)
-                    self._stdout_thread = threading.Thread(
-                        target = self._drain_stdout, daemon = True, name = "llama-stdout"
-                    )
-                    self._stdout_thread.start()
-                    if self._wait_for_health(timeout = 600.0):
-                        break
-                    _startup_crashed = (
-                        self._process.poll() is not None and self._process.returncode != 0
-                    )
-                    if _spawn_attempt == 0 and _fit_retry_allowed and _startup_crashed:
-                        logger.warning(
-                            "llama-server crashed during startup (exit code %s) "
-                            "with the default memory-fit step enabled; Studio "
-                            "already verified the model fits, retrying once "
-                            "with --fit off. Crash log: %s",
-                            self._process.returncode,
-                            self._llama_log_path,
+                        self._stdout_lines = []
+                        # Tee llama-server output to a dedicated log file so a
+                        # post-mortem has the full trail even when the parent only
+                        # kept the last 50 lines. Path is under the studio home.
+                        # ``label`` (MTP fallback) and the attempt index (--fit
+                        # off retry) keep a respawn within the same epoch second
+                        # from truncating the crash log a retry warning just
+                        # pointed the user at.
+                        self._llama_log_fh = None
+                        try:
+                            log_dir = _swa_cache_path().parent / "logs" / "llama-server"
+                            log_dir.mkdir(parents = True, exist_ok = True)
+                            self._llama_log_path = log_dir / (
+                                f"llama-{int(time.time())}{label}-port-{self._port}"
+                                f"-try{_spawn_attempt}.log"
+                            )
+                            self._llama_log_fh = open(
+                                self._llama_log_path,
+                                "w",
+                                encoding = "utf-8",
+                                buffering = 1,
+                            )
+                            logger.info(f"llama-server stdout/stderr -> {self._llama_log_path}")
+                        except OSError as e:
+                            # Best-effort; never block the load on logging.
+                            logger.debug(f"Could not open llama-server log file: {e}")
+                            self._llama_log_path = None
+                        self._process = subprocess.Popen(
+                            run_cmd,
+                            stdout = subprocess.PIPE,
+                            stderr = subprocess.STDOUT,
+                            text = True,
+                            env = env,
+                            **_windows_hidden_subprocess_kwargs(),
                         )
-                        cmd = [*cmd, "--fit", "off"]
-                        continue
-                    self._kill_process()
-                    raise RuntimeError(
-                        self._classify_llama_start_failure(
-                            "\n".join(self._stdout_lines[-50:]),
-                            gguf_path,
-                            model_identifier,
+
+                        # Background thread to drain stdout (prevents pipe deadlock)
+                        self._stdout_thread = threading.Thread(
+                            target = self._drain_stdout, daemon = True, name = "llama-stdout"
                         )
-                    )
+                        self._stdout_thread.start()
+                        if self._wait_for_health(timeout = 600.0):
+                            return True
+                        _startup_crashed = (
+                            self._process.poll() is not None and self._process.returncode != 0
+                        )
+                        if _spawn_attempt == 0 and _fit_retry_allowed and _startup_crashed:
+                            logger.warning(
+                                "llama-server crashed during startup (exit code %s) "
+                                "with the default memory-fit step enabled; Studio "
+                                "already verified the model fits, retrying once "
+                                "with --fit off. Crash log: %s",
+                                self._process.returncode,
+                                self._llama_log_path,
+                            )
+                            run_cmd = [*run_cmd, "--fit", "off"]
+                            continue
+                        return False
 
                 # Store the resolved on-disk path, not the caller's kwarg: in
                 # HF mode gguf_path is None and ``model_path`` is what
-                # llama-server mmap's, which downstream consumers need.
+                # llama-server mmap's, which downstream consumers need. Must be
+                # set BEFORE the spawn: load_progress() reads _gguf_path for
+                # the mmap progress total while the health wait runs.
                 self._gguf_path = model_path
                 self._hf_repo = hf_repo
+                self._mtp_draft_path = launch_mtp_draft_path
                 # For local GGUF files, extract variant from filename if absent
                 if hf_variant:
                     self._hf_variant = hf_variant
@@ -3285,7 +3460,76 @@ class LlamaCppBackend:
                     max_available_ctx if max_available_ctx > 0 else self._effective_context_length
                 )
 
-                # Health was confirmed inside the spawn/retry loop above.
+                healthy = _spawn_and_wait(cmd)
+                # A separate MTP drafter (e.g. Gemma's gemma4-assistant head)
+                # can fail to load on a llama-server that advertises the
+                # --spec-type draft-mtp flag but predates the drafter's
+                # architecture -- and that aborts the whole server. Retry once
+                # with the whole spec block replaced by --spec-default so the
+                # main model still loads (without speculation). Replacing the
+                # slice -- rather than re-resolving with mtp_draft_path=None --
+                # is what guarantees MTP is off even for a forced mtp / mtp+ngram
+                # request (which would otherwise re-emit --spec-type draft-mtp).
+                # _requested_spec_mode (the user's choice) is left intact so a
+                # duplicate /load doesn't thrash a reload.
+                # Gate on the flag actually being in the command, not on the
+                # drafter merely existing on disk: local loads pass the path
+                # even in off/ngram modes (and auto drops MTP sub-3B), where a
+                # retry would blame the drafter for an unrelated failure and
+                # override the user's spec choice. The cancel check keeps an
+                # /unload that killed the first attempt from respawning.
+                if (
+                    not healthy
+                    and "--model-draft" in spec_flags
+                    and not self._cancel_event.is_set()
+                ):
+                    # Only blame the binary's age when the output shows the
+                    # drafter actually failing (unknown arch / draft load);
+                    # an unrelated crash (e.g. OOM) gets a neutral message.
+                    # Substrings are upstream llama.cpp messages
+                    # (llama_model_load / srv load_model [spec]); if they
+                    # drift, only the wording degrades -- the retry fires
+                    # either way.
+                    _attempt_output = "\n".join(self._stdout_lines)
+                    if (
+                        "unknown model architecture" in _attempt_output
+                        or "failed to measure draft model memory" in _attempt_output
+                    ):
+                        _retry_reason = (
+                            "the prebuilt may predate its architecture; retrying "
+                            "without speculative decoding -- run "
+                            "`unsloth studio update` for MTP"
+                        )
+                    else:
+                        _retry_reason = (
+                            "retrying without speculative decoding in case the "
+                            "drafter is the cause"
+                        )
+                    logger.warning(
+                        "llama-server failed to start with MTP drafter %s; %s.",
+                        Path(launch_mtp_draft_path).name,
+                        _retry_reason,
+                    )
+                    self._kill_process()
+                    fallback_cmd = (
+                        cmd[:_spec_start]
+                        + ["--spec-default"]
+                        + cmd[_spec_start + len(spec_flags) :]
+                    )
+                    healthy = _spawn_and_wait(fallback_cmd, label = "-retry")
+                    if healthy:
+                        self._speculative_type = "default"
+
+                if not healthy:
+                    self._kill_process()
+                    raise RuntimeError(
+                        self._classify_llama_start_failure(
+                            "\n".join(self._stdout_lines[-50:]),
+                            gguf_path,
+                            self._model_identifier,
+                        )
+                    )
+
                 self._healthy = True
 
                 # Commit caller intent only after _healthy=True so a failed start
@@ -3373,6 +3617,7 @@ class LlamaCppBackend:
         model_path: Optional[str],
         gpus: bool,
         binary: Optional[str],
+        mtp_draft_path: Optional[str] = None,
     ) -> List[str]:
         """Return the llama-server flag list for the requested spec mode.
 
@@ -3417,12 +3662,16 @@ class LlamaCppBackend:
         # Canonical UI-facing requested mode (legacy values mapped via
         # _canonicalize_spec_mode).
         canonical_mode = _canonicalize_spec_mode(speculative_type)
-        is_mtp_model = bool(self._nextn_predict_layers) or (
-            _is_mtp_model_name(model_identifier, model_path)
+        # MTP signals: head baked into the main GGUF (Qwen, via metadata or
+        # name), or a separate drafter resolved from the repo (Gemma).
+        is_mtp_model = (
+            bool(self._nextn_predict_layers)
+            or _is_mtp_model_name(model_identifier, model_path)
+            or bool(mtp_draft_path)
         )
         user_owns_spec_type = _extra_args_set_spec_type(extra_args)
         _mtp_size_b = _extract_model_size_b(model_identifier)
-        _mtp_too_small = _mtp_size_b is not None and _mtp_size_b < 3.0
+        _mtp_too_small = _mtp_size_b is not None and _mtp_size_b < _MTP_MIN_SIZE_B
 
         if user_owns_spec_type:
             # User --spec-type wins outright; suppress auto-emit to avoid a
@@ -3457,6 +3706,12 @@ class LlamaCppBackend:
                 return False
             draft_n_max = _resolved_draft_n_max()
             n_max_flag = caps.get("spec_draft_n_max_flag") or "--spec-draft-n-max"
+            # Separate-file drafter (Gemma): point llama-server at it. Baked-in
+            # heads (Qwen) pass no path -- llama-server reads them from the
+            # main GGUF.
+            if mtp_draft_path:
+                flags.extend(["--model-draft", mtp_draft_path])
+                logger.info(f"Using separate MTP drafter: {mtp_draft_path}")
             if chain_ngram:
                 ngram_knobs = _build_ngram_mod_flags(caps)
                 if ngram_knobs:
@@ -3589,6 +3844,7 @@ class LlamaCppBackend:
         is_vision: bool,
         gguf_path: Optional[str] = None,
         spec_draft_n_max: Optional[int] = None,
+        mtp_draft_path: Optional[str] = None,
     ) -> bool:
         """True iff the live server already satisfies these load kwargs.
 
@@ -3647,6 +3903,22 @@ class LlamaCppBackend:
         if (self._chat_template_override or None) != (chat_template_override or None):
             return False
 
+        # A drafter appearing/disappearing next to a local GGUF changes the
+        # launch command (--model-draft) when the mode can use it; without
+        # this, adding mtp-*.gguf after a load is deduped away and MTP can't
+        # engage short of an unload. HF loads resolve the drafter inside
+        # load_model (gguf_path is None here), so only local paths compare;
+        # the route-level probe covers HF cache repos. No sub-3B gate: both
+        # sides come from the same config detection, so a sub-3B mismatch
+        # only happens when a drafter genuinely appeared (one benign reload,
+        # then the stored path converges).
+        if (
+            gguf_path is not None
+            and req_mode in ("auto", "mtp", "mtp+ngram")
+            and (mtp_draft_path or None) != (self._mtp_draft_path or None)
+        ):
+            return False
+
         # extra_args=None means "no opinion" (inherit handled at the route
         # layer); only an explicit list forces equality.
         if extra_args is not None:
@@ -3688,6 +3960,7 @@ class LlamaCppBackend:
             self._model_identifier = None
             self._gguf_path = None
             self._hf_repo = None
+            self._mtp_draft_path = None
             self._hf_variant = None
             self._is_vision = False
             self._is_audio = False
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index 66c7f10d42..1862c9c5de 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -132,7 +132,13 @@ _SPEC_FLAGS: frozenset[str] = frozenset(
         "--spec-ngram-size",
         "--draft-min",
         "--draft-max",
-        # MTP path (llama.cpp #22673).
+        # MTP path (llama.cpp #22673). --model-draft and aliases are
+        # Studio-managed since the separate-drafter support (Gemma 4): an
+        # inherited copy must not last-wins-override the auto-detected
+        # drafter. Explicit extras for the current load are never stripped.
+        "--model-draft",
+        "-md",
+        "--spec-draft-model",
         "--spec-draft-n-max",
         "--spec-draft-n-min",
         "--spec-draft-p-min",
diff --git a/studio/backend/hub/services/models/common.py b/studio/backend/hub/services/models/common.py
index 688d324a60..f381bffe9c 100644
--- a/studio/backend/hub/services/models/common.py
+++ b/studio/backend/hub/services/models/common.py
@@ -21,6 +21,7 @@ from hub.utils.gguf import (
     extract_quant_label,
     is_gguf_filename as _is_gguf_filename,
     is_mmproj_filename as _is_mmproj_filename,
+    is_mtp_drafter_path as _is_mtp_drafter_path,
 )
 from hub.utils.paths import is_valid_repo_id as _is_valid_repo_id
 
@@ -71,7 +72,7 @@ def _is_model_directory(d: Path) -> bool:
         if suffix == ".safetensors":
             return True
         if suffix == ".gguf":
-            return "mmproj" not in f.name.lower()
+            return "mmproj" not in f.name.lower() and not _is_mtp_drafter_path(f.name)
         if suffix == ".bin":
             name = f.name.lower()
             return (
@@ -276,7 +277,9 @@ def _classify_non_gguf_model_format(
 
 
 def _is_main_gguf_filename(name: str) -> bool:
-    return _is_gguf_filename(name) and not _is_mmproj_filename(name)
+    return (
+        _is_gguf_filename(name) and not _is_mmproj_filename(name) and not _is_mtp_drafter_path(name)
+    )
 
 
 def _iter_gguf_paths(root: Path):
diff --git a/studio/backend/hub/services/models/deletion.py b/studio/backend/hub/services/models/deletion.py
index d4aed0d59f..ecc9f8426d 100644
--- a/studio/backend/hub/services/models/deletion.py
+++ b/studio/backend/hub/services/models/deletion.py
@@ -32,6 +32,7 @@ from hub.services.models.common import (
     _is_gguf_filename,
     _is_main_gguf_filename,
     _is_mmproj_filename,
+    _is_mtp_drafter_path,
 )
 
 logger = get_logger(__name__)
@@ -139,7 +140,10 @@ def _delete_gguf_variant_from_repos(
         if matched and not sibling_active and not _has_remaining_main_gguf(target_repo):
             companion_matches = _repo_file_matches(
                 target_repo,
-                lambda name: _is_gguf_filename(name) and _is_mmproj_filename(name),
+                # Companions: mmproj and the MTP drafter -- downloaded with
+                # every variant, so the last variant's delete reclaims them.
+                lambda name: _is_gguf_filename(name)
+                and (_is_mmproj_filename(name) or _is_mtp_drafter_path(name)),
             )
             for snap, _blob, name in companion_matches:
                 try:
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index efe6bdf6c4..0b4671c6d2 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -38,6 +38,7 @@ from hub.utils.paths import (
 )
 from hub.services.models.common import (
     _is_mmproj_filename,
+    _is_mtp_drafter_path,
     _iter_gguf_paths,
 )
 from hub.utils.gguf_plan import (
@@ -479,7 +480,7 @@ async def get_gguf_variants_response(
                         continue
                     key = rel.lower()
                     by_filename[key] = max(by_filename.get(key, 0), size)
-                    if _is_mmproj_filename(f.name):
+                    if _is_mmproj_filename(f.name) or _is_mtp_drafter_path(rel):
                         continue
                     q = extract_quant_label(rel).lower()
                     by_quant[q] = by_quant.get(q, 0) + size
@@ -593,7 +594,11 @@ async def get_gguf_variants_response(
                 requirement = requirements_by_quant.get(variant.quant.lower())
                 if requirement is None:
                     continue
-                if requirement.mmproj_hashes & incomplete_hashes and _filenames_cached(
+                # companion_hashes adds the MTP drafter (mmproj_hashes covers
+                # every mmproj precision in the repo, not just the planned one).
+                if (
+                    (requirement.mmproj_hashes | requirement.companion_hashes) & incomplete_hashes
+                ) and _filenames_cached(
                     requirement.main_filenames,
                     requirement.main_size_bytes,
                 ):
diff --git a/studio/backend/hub/utils/gguf.py b/studio/backend/hub/utils/gguf.py
index 4bd1961c33..c9b3ce97e3 100644
--- a/studio/backend/hub/utils/gguf.py
+++ b/studio/backend/hub/utils/gguf.py
@@ -83,6 +83,28 @@ def is_mmproj_filename(filename: str) -> bool:
     return "mmproj" in filename.lower()
 
 
+def is_mtp_drafter_path(path: str) -> bool:
+    """True for a separate-file MTP drafter (speculative head), a companion to
+    the main model rather than a selectable quant.
+
+    Covers the repo-root ``mtp-*.gguf`` (the Q8_0 copy unsloth ships for
+    llama.cpp ``-hf`` auto-discovery) and the ``MTP/`` subdir copies (Gemma 4).
+    Repos that bake the head into the main GGUF (Qwen) have no such file, so
+    this is False for them. Must be excluded from main-model selection
+    everywhere mmproj is.
+
+    CANONICAL COPY. Layering keeps two mirrors that must change in lockstep:
+    utils/models/model_config.py ``_is_mtp_drafter`` (utils cannot import
+    hub) and core/inference/llama_cpp.py ``_is_companion_gguf_path`` (core
+    avoids hub imports; bundles the mmproj check).
+    """
+    p = path.lower()
+    if not p.endswith(".gguf"):
+        return False
+    name = p.rsplit("/", 1)[-1]
+    return name.startswith("mtp-") or "/mtp/" in f"/{p}"
+
+
 def is_gguf_filename(filename: str) -> bool:
     return filename.lower().endswith(".gguf")
 
@@ -119,7 +141,9 @@ def iter_gguf_files(directory: Path, recursive: bool = False):
 
 def pick_best_gguf(filenames: list[str]) -> Optional[str]:
     gguf_files = [
-        name for name in filenames if is_gguf_filename(name) and not is_mmproj_filename(name)
+        name
+        for name in filenames
+        if is_gguf_filename(name) and not is_mmproj_filename(name) and not is_mtp_drafter_path(name)
     ]
     if not gguf_files:
         return None
@@ -270,6 +294,12 @@ def list_partial_gguf_variants_from_state(
             for expected in manifest.expected_files:
                 if not is_gguf_filename(expected.path):
                     continue
+                if is_mtp_drafter_path(expected.path):
+                    # Downloaded with every variant (like mmproj) but not a
+                    # selectable quant; count it so the shown download size
+                    # matches what is fetched.
+                    companion_bytes += max(0, int(expected.size or 0))
+                    continue
                 if is_mmproj_filename(expected.path):
                     has_vision = True
                     companion_bytes += max(0, int(expected.size or 0))
@@ -336,6 +366,8 @@ def list_gguf_variants(
         filename = getattr(sibling, "rfilename", None)
         if not isinstance(filename, str) or not is_gguf_filename(filename):
             continue
+        if is_mtp_drafter_path(filename):
+            continue
         if is_mmproj_filename(filename):
             has_vision = True
             continue
@@ -389,6 +421,8 @@ def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], boo
         except OSError:
             size = 0
         rel = file.relative_to(root).as_posix()
+        if is_mtp_drafter_path(rel):
+            continue
         quant = extract_quant_label(rel)
         quant_totals[quant] = quant_totals.get(quant, 0) + size
         quant_first_file.setdefault(quant, rel)
diff --git a/studio/backend/hub/utils/gguf_plan.py b/studio/backend/hub/utils/gguf_plan.py
index 03ec847f4c..60782fa109 100644
--- a/studio/backend/hub/utils/gguf_plan.py
+++ b/studio/backend/hub/utils/gguf_plan.py
@@ -7,7 +7,12 @@ from dataclasses import dataclass
 from typing import Optional, Sequence
 
 from hub.utils.download_manifest import ExpectedFile
-from hub.utils.gguf import extract_quant_label, is_gguf_filename, is_mmproj_filename
+from hub.utils.gguf import (
+    extract_quant_label,
+    is_gguf_filename,
+    is_mmproj_filename,
+    is_mtp_drafter_path,
+)
 
 
 @dataclass(frozen = True)
@@ -53,24 +58,30 @@ def expected_file_from_sibling(sibling) -> Optional[ExpectedFile]:
 
 
 def is_companion_gguf_path(path: str) -> bool:
-    return is_gguf_filename(path) and is_mmproj_filename(path)
+    """Companion (non-main) GGUF downloaded alongside a variant: the vision
+    mmproj or the separate MTP drafter (Gemma 4)."""
+    return is_gguf_filename(path) and (is_mmproj_filename(path) or is_mtp_drafter_path(path))
 
 
 def is_main_gguf_variant_path(path: str, variant: str) -> bool:
     return (
         is_gguf_filename(path)
         and not is_mmproj_filename(path)
+        and not is_mtp_drafter_path(path)
         and extract_quant_label(path).lower() == variant.lower()
     )
 
 
+def _gguf_rfilename(sibling) -> Optional[str]:
+    """The sibling's rfilename when it is a GGUF, else None."""
+    name = getattr(sibling, "rfilename", None)
+    if isinstance(name, str) and is_gguf_filename(name):
+        return name
+    return None
+
+
 def mmproj_siblings(siblings: Sequence) -> list:
-    return [
-        s
-        for s in siblings
-        if isinstance(getattr(s, "rfilename", None), str)
-        and is_companion_gguf_path(getattr(s, "rfilename"))
-    ]
+    return [s for s in siblings if (name := _gguf_rfilename(s)) and is_mmproj_filename(name)]
 
 
 def preferred_mmproj_sibling(siblings: Sequence) -> Optional[object]:
@@ -83,6 +94,25 @@ def preferred_mmproj_sibling(siblings: Sequence) -> Optional[object]:
     )
 
 
+def preferred_mtp_sibling(siblings: Sequence) -> Optional[object]:
+    """The separate MTP drafter to fetch with every variant: the repo-root
+    ``mtp-*.gguf`` copy unsloth ships for llama.cpp ``-hf`` auto-discovery
+    (Gemma 4). Same pick as the loader's drafter resolution (``mtp-`` basename
+    prefix, first in sort order) so download and load resolve the same file;
+    the higher-precision ``MTP/`` subdir copies are for explicit selection and
+    are not auto-fetched. None for repos with the head baked into the main
+    GGUF (Qwen)."""
+    candidates = sorted(
+        (
+            s
+            for s in siblings
+            if (name := _gguf_rfilename(s)) and name.lower().rsplit("/", 1)[-1].startswith("mtp-")
+        ),
+        key = lambda s: getattr(s, "rfilename"),
+    )
+    return candidates[0] if candidates else None
+
+
 def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
     main: dict[str, list] = {}
     all_mmproj = mmproj_siblings(siblings)
@@ -94,12 +124,20 @@ def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
     all_mmproj_hashes = frozenset(h for h in (sibling_sha256(s) for s in all_mmproj) if h)
     companion = preferred_mmproj_sibling(siblings)
     companion_expected = expected_file_from_sibling(companion) if companion is not None else None
+    mtp_sibling = preferred_mtp_sibling(siblings)
+    mtp_expected = expected_file_from_sibling(mtp_sibling) if mtp_sibling is not None else None
+    companions_expected = tuple(
+        file for file in (companion_expected, mtp_expected) if file is not None
+    )
 
     for sibling in siblings:
-        name = getattr(sibling, "rfilename", None)
-        if not isinstance(name, str) or not is_gguf_filename(name):
+        name = _gguf_rfilename(sibling)
+        if name is None:
             continue
-        if is_mmproj_filename(name):
+        # Companions are folded into every plan below; keep them out of the
+        # quant grouping so a drafter never lands in a variant's main files
+        # (the root mtp-*.gguf carries a quant label, e.g. Q8_0).
+        if is_mmproj_filename(name) or is_mtp_drafter_path(name):
             continue
         quant = extract_quant_label(name).lower()
         main.setdefault(quant, []).append(sibling)
@@ -111,11 +149,7 @@ def build_gguf_variant_plans(siblings: Sequence) -> dict[str, GgufVariantPlan]:
             for sibling in target_main_siblings
             if (file := expected_file_from_sibling(sibling)) is not None
         )
-        expected_files = (
-            (*main_expected, companion_expected)
-            if companion_expected is not None
-            else main_expected
-        )
+        expected_files = (*main_expected, *companions_expected)
         plans[quant] = plan_from_expected_files(
             quant,
             expected_files,
@@ -135,6 +169,9 @@ def plan_from_expected_files(
     expected = tuple(expected_files)
     main_files = tuple(file for file in expected if is_main_gguf_variant_path(file.path, variant))
     companion_files = tuple(file for file in expected if is_companion_gguf_path(file.path))
+    # Manifest-resume fallback for the mmproj fields below: companion_files
+    # also holds the MTP drafter, so keep an mmproj-only view.
+    mmproj_files = tuple(file for file in companion_files if is_mmproj_filename(file.path))
     main_hashes = frozenset(file.sha256 for file in main_files if file.sha256)
     companion_hashes = frozenset(file.sha256 for file in companion_files if file.sha256)
     required_hashes = frozenset(file.sha256 for file in expected if file.sha256)
@@ -149,9 +186,13 @@ def plan_from_expected_files(
         mmproj_filenames = (
             all_mmproj_filenames
             if all_mmproj_filenames is not None
-            else frozenset(file.path for file in companion_files)
+            else frozenset(file.path for file in mmproj_files)
+        ),
+        mmproj_hashes = (
+            all_mmproj_hashes
+            if all_mmproj_hashes is not None
+            else frozenset(file.sha256 for file in mmproj_files if file.sha256)
         ),
-        mmproj_hashes = (all_mmproj_hashes if all_mmproj_hashes is not None else companion_hashes),
         expected_files = expected,
         main_size_bytes = main_size,
         download_size_bytes = download_size,
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.py
index a7281ad8b3..fe3aadfd38 100644
--- a/studio/backend/hub/utils/inventory_scan.py
+++ b/studio/backend/hub/utils/inventory_scan.py
@@ -25,7 +25,12 @@ from loggers import get_logger
 
 logger = get_logger(__name__)
 
-from hub.utils.gguf import extract_quant_label, is_gguf_filename, is_mmproj_filename
+from hub.utils.gguf import (
+    extract_quant_label,
+    is_gguf_filename,
+    is_mmproj_filename,
+    is_mtp_drafter_path,
+)
 from hub.utils.state_dir import RepoType
 
 from hub.utils.hf_cache_state import (
@@ -336,7 +341,7 @@ def _completed_gguf_variants(snapshot_dir: Optional[Path]) -> set[str]:
         except OSError:
             continue
         rel = path.relative_to(snapshot_dir).as_posix()
-        if not is_gguf_filename(rel) or is_mmproj_filename(rel):
+        if not is_gguf_filename(rel) or is_mmproj_filename(rel) or is_mtp_drafter_path(rel):
             continue
         quant = extract_quant_label(rel)
         split = _GGUF_SPLIT_RE.search(path.name)
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 9c12f8faac..96f24887bd 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -72,7 +72,7 @@ class LoadRequest(BaseModel):
             "ngram-mod+draft-mtp chain on both platforms), 'off' (disabled). "
             "Legacy values 'default' (-> auto), 'draft-mtp' (-> mtp), "
             "'ngram-mod' (-> ngram), and 'ngram-simple' (kept as-is) are "
-            "still accepted. Ignored for non-GGUF and vision models."
+            "still accepted. Ignored for non-GGUF models."
         ),
     )
     spec_draft_n_max: Optional[int] = Field(
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 9f0bb43c9a..418206e938 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -417,7 +417,9 @@ try:
         LlamaCppBackend,
         _DEFAULT_MAX_TOKENS_FLOOR,
         _DEFAULT_T_MAX_PREDICT_MS,
+        _auto_mode_drops_mtp,
         _canonicalize_spec_mode,
+        _extra_args_set_spec_type,
         _hf_offline_if_dns_dead,
         detect_reasoning_flags,
     )
@@ -427,7 +429,11 @@ try:
     )
     from utils.models import ModelConfig
     from utils.inference import load_inference_config
-    from utils.models.model_config import load_model_defaults
+    from utils.models.model_config import (
+        detect_mtp_file,
+        extract_model_size_b,
+        load_model_defaults,
+    )
     from utils.native_path_leases import (
         NativePathLeaseError,
         display_label_for_native_path,
@@ -444,7 +450,9 @@ except ImportError:
         LlamaCppBackend,
         _DEFAULT_MAX_TOKENS_FLOOR,
         _DEFAULT_T_MAX_PREDICT_MS,
+        _auto_mode_drops_mtp,
         _canonicalize_spec_mode,
+        _extra_args_set_spec_type,
         _hf_offline_if_dns_dead,
         detect_reasoning_flags,
     )
@@ -454,7 +462,11 @@ except ImportError:
     )
     from utils.models import ModelConfig
     from utils.inference import load_inference_config
-    from utils.models.model_config import load_model_defaults
+    from utils.models.model_config import (
+        detect_mtp_file,
+        extract_model_size_b,
+        load_model_defaults,
+    )
     from utils.native_path_leases import (
         NativePathLeaseError,
         display_label_for_native_path,
@@ -927,35 +939,42 @@ def _strip_tool_xml_for_display(text: str, *, auto_heal_tool_calls: bool) -> str
 logger = get_logger(__name__)
 
 
-def _validate_native_mmproj_companion(mmproj_path: str | None, gguf_path: str | None) -> None:
-    if not mmproj_path or not gguf_path:
+def _validate_native_gguf_companion(
+    companion_path: str | None, gguf_path: str | None, label: str
+) -> None:
+    """Reject a companion GGUF (mmproj / MTP drafter) that a native-lease load
+    would otherwise hand to llama-server: must be a regular file (no symlink
+    escaping the leased directory) living next to the selected GGUF."""
+    if not companion_path or not gguf_path:
         return
     import stat as _stat_module
 
-    mm = Path(mmproj_path)
+    companion = Path(companion_path)
     gguf = Path(gguf_path)
     try:
-        mm_lstat = os.lstat(mm)
+        companion_lstat = os.lstat(companion)
     except OSError as exc:
         raise HTTPException(
             status_code = 400,
-            detail = "Native vision companion is no longer accessible.",
+            detail = f"Native {label} is no longer accessible.",
         ) from exc
-    if _stat_module.S_ISLNK(mm_lstat.st_mode) or not _stat_module.S_ISREG(mm_lstat.st_mode):
+    if _stat_module.S_ISLNK(companion_lstat.st_mode) or not _stat_module.S_ISREG(
+        companion_lstat.st_mode
+    ):
         raise HTTPException(
             status_code = 400,
-            detail = "Native vision companion must be a regular file.",
+            detail = f"Native {label} must be a regular file.",
         )
     try:
-        if mm.resolve(strict = True).parent != gguf.resolve(strict = True).parent:
+        if companion.resolve(strict = True).parent != gguf.resolve(strict = True).parent:
             raise HTTPException(
                 status_code = 400,
-                detail = "Native vision companion must live next to the selected GGUF.",
+                detail = f"Native {label} must live next to the selected GGUF.",
             )
     except OSError as exc:
         raise HTTPException(
             status_code = 400,
-            detail = "Native vision companion is no longer accessible.",
+            detail = f"Native {label} is no longer accessible.",
         ) from exc
 
 
@@ -980,13 +999,11 @@ def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaC
         llama_backend.cache_type_kv
     ):
         return False
-    # Vision loads silently drop speculative decoding (llama_cpp.py gates spec
-    # on ``not is_vision``), so treat the request as ``off`` against the
-    # backend's ``None`` to avoid a redundant reload.
-    if llama_backend.is_vision:
-        req_mode = "off"
-    else:
-        req_mode = _canonicalize_spec_mode(request.speculative_type) or "auto"
+    # Spec decoding works on vision models too (MTP is mmproj-compatible,
+    # llama.cpp #22673; the old ``not is_vision`` gate is gone), so compare
+    # the real requested mode -- coercing vision to ``off`` here used to
+    # swallow every spec-mode change on a vision model as already_loaded.
+    req_mode = _canonicalize_spec_mode(request.speculative_type) or "auto"
     backend_mode = llama_backend.requested_spec_mode or "auto"
     if req_mode != backend_mode:
         return False
@@ -1008,6 +1025,35 @@ def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaC
     else:
         if list(request.llama_extra_args) != backend_extra:
             return False
+    # A drafter that appeared next to the loaded weights since the last load
+    # changes the launch command (--model-draft) when the mode can use it;
+    # without this, a duplicate /load is deduped and MTP can't engage short
+    # of an unload. Runs last: it stats the filesystem (two dir scans against
+    # the resolved weight path -- covers local dirs and HF cache snapshots
+    # alike), so every pure-memory comparison above short-circuits first.
+    # Skipped when auto drops MTP anyway (sub-3B) or the user owns
+    # --spec-type, where a drafter changes nothing. Resolve both sides: the
+    # stored launch path may be a snapshot symlink while detect_mtp_file
+    # returns the resolved blob.
+    if req_mode in ("auto", "mtp", "mtp+ngram") and llama_backend.gguf_path:
+        effective_extras = (
+            request.llama_extra_args
+            if request.llama_extra_args is not None
+            else llama_backend.extra_args
+        )
+        size_b = extract_model_size_b(llama_backend.model_identifier or "")
+        if not _auto_mode_drops_mtp(req_mode, size_b) and not _extra_args_set_spec_type(
+            effective_extras
+        ):
+            detected = detect_mtp_file(llama_backend.gguf_path)
+            stored = llama_backend.mtp_draft_path
+            try:
+                detected_resolved = Path(detected).resolve() if detected else None
+                stored_resolved = Path(stored).resolve() if stored else None
+            except OSError:
+                return False
+            if detected_resolved != stored_resolved:
+                return False
     return True
 
 
@@ -1313,12 +1359,26 @@ async def load_model(
                 )
             else:
                 # Local mode: llama-server loads via -m <path>
-                if native_grant_backed and config.gguf_mmproj_file:
-                    _validate_native_mmproj_companion(config.gguf_mmproj_file, config.gguf_file)
+                if native_grant_backed:
+                    if config.gguf_mmproj_file:
+                        _validate_native_gguf_companion(
+                            config.gguf_mmproj_file, config.gguf_file, "vision companion"
+                        )
+                    if config.gguf_mtp_file:
+                        # The drafter is optional (unlike mmproj for a vision
+                        # model): drop it rather than fail the load.
+                        try:
+                            _validate_native_gguf_companion(
+                                config.gguf_mtp_file, config.gguf_file, "MTP drafter"
+                            )
+                        except HTTPException as exc:
+                            logger.warning("Dropping MTP drafter for native load: %s", exc.detail)
+                            config.gguf_mtp_file = None
                 success = await asyncio.to_thread(
                     llama_backend.load_model,
                     gguf_path = config.gguf_file,
                     mmproj_path = config.gguf_mmproj_file,
+                    mtp_draft_path = config.gguf_mtp_file,
                     # Pass the resolved variant so _extra_args_source keys off
                     # the same string the inheritance check at the top of /load
                     # uses (#5401 followup).
diff --git a/studio/backend/tests/test_llama_server_args.py b/studio/backend/tests/test_llama_server_args.py
index 52e3848157..09775707ee 100644
--- a/studio/backend/tests/test_llama_server_args.py
+++ b/studio/backend/tests/test_llama_server_args.py
@@ -507,3 +507,28 @@ def test_strip_shadowing_flags_defaults_strip_everything():
         ["-c", "4096", "--cache-type-k", "q8_0", "--spec-default", "--jinja"]
     )
     assert out == []
+
+
+def test_strip_shadowing_flags_drops_model_draft_with_spec():
+    # --model-draft (and aliases) are Studio-managed since the separate
+    # MTP drafter support: an inherited copy must not last-wins-override
+    # the auto-detected drafter.
+    out = strip_shadowing_flags(
+        ["--model-draft", "/old/mtp.gguf", "-md", "/old2.gguf", "--top-k", "20"],
+        strip_context = False,
+        strip_cache = False,
+        strip_spec = True,
+        strip_template = False,
+    )
+    assert out == ["--top-k", "20"]
+
+
+def test_strip_shadowing_flags_keeps_model_draft_without_spec():
+    out = strip_shadowing_flags(
+        ["--model-draft", "/custom/mtp.gguf"],
+        strip_context = True,
+        strip_cache = False,
+        strip_spec = False,
+        strip_template = False,
+    )
+    assert out == ["--model-draft", "/custom/mtp.gguf"]
diff --git a/studio/backend/tests/test_mtp_drafter_companion.py b/studio/backend/tests/test_mtp_drafter_companion.py
new file mode 100644
index 0000000000..d5e8d13652
--- /dev/null
+++ b/studio/backend/tests/test_mtp_drafter_companion.py
@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Separate-file MTP drafter (Gemma 4) contracts.
+
+Pins: the drafter-path predicate and its two layering mirrors, Gemma
+effective-size extraction, companion classification in variant plans
+(including resume from pre-fix manifests where the drafter leaked into a
+quant's main files), and local drafter detection / self-pairing rejection.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from hub.utils.download_manifest import ExpectedFile
+from hub.utils.gguf import is_mtp_drafter_path
+from hub.utils.gguf_plan import build_gguf_variant_plans, plan_from_expected_files
+from utils.models.model_config import (
+    _is_mtp_drafter,
+    detect_gguf_model,
+    detect_mtp_file,
+    extract_model_size_b,
+)
+
+
+# ── Predicate + layering mirrors ─────────────────────────────────────
+
+DRAFTER_CASES = [
+    ("mtp-gemma-4-12b-it.gguf", True),
+    ("MTP/gemma-4-12b-it-Q8_0-MTP.gguf", True),
+    ("foo/MTP/bar.gguf", True),
+    ("gemma-4-12b-it-Q8_0.gguf", False),
+    # Baked-in Qwen MTP repos: the head is inside the main GGUF, the file
+    # IS the model -- must never be classified as a companion.
+    ("Qwen3.6-27B-MTP-Q4_K_M.gguf", False),
+    ("prompt-mtp-test.gguf", False),
+    ("smtp/model.gguf", False),
+    ("mtp-readme.txt", False),
+]
+
+
+@pytest.mark.parametrize("path,expected", DRAFTER_CASES)
+def test_drafter_predicate_and_mirrors_agree(path, expected):
+    from core.inference.llama_cpp import _is_companion_gguf_path
+
+    assert is_mtp_drafter_path(path) is expected
+    assert _is_mtp_drafter(path) is expected
+    # The core mirror bundles mmproj; none of these inputs are mmproj, so
+    # it must agree with the canonical predicate.
+    assert _is_companion_gguf_path(path) is expected
+
+
+# ── Gemma effective-size extraction ──────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "model_id,size_b",
+    [
+        ("unsloth/gemma-4-E2B-it-GGUF", 2.0),
+        ("unsloth/gemma-4-E4B-it", 4.0),
+        ("unsloth/gemma-3n-E4B-it", 4.0),
+        # MoE active params beat effective and total notation.
+        ("unsloth/Qwen3.5-35B-A3B", 3.0),
+        ("unsloth/gemma-4-12b-it-GGUF", 12.0),
+        ("unsloth/Qwen3.5-9B-MTP-GGUF", 9.0),
+        ("no-size-here", None),
+    ],
+)
+def test_extract_model_size_b(model_id, size_b):
+    assert extract_model_size_b(model_id) == size_b
+
+
+# ── Variant plan companion classification ────────────────────────────
+
+
+def _sib(name: str, size: int, sha: str):
+    return SimpleNamespace(rfilename = name, size = size, lfs = {"sha256": sha})
+
+
+GEMMA_SIBLINGS = [
+    _sib("gemma-4-12b-it-Q4_K_M.gguf", 4_000, "main-q4"),
+    _sib("gemma-4-12b-it-Q8_0.gguf", 8_000, "main-q8"),
+    _sib("mtp-gemma-4-12b-it.gguf", 100, "drafter"),
+    _sib("MTP/gemma-4-12b-it-Q8_0-MTP.gguf", 100, "mtp-sub-q8"),
+    _sib("MTP/gemma-4-12b-it-BF16-MTP.gguf", 200, "mtp-sub-bf16"),
+    _sib("mmproj-F16.gguf", 500, "mmproj"),
+]
+
+
+def test_variant_plans_carry_drafter_as_companion():
+    plans = build_gguf_variant_plans(GEMMA_SIBLINGS)
+
+    # No phantom quants from the drafter's Q8_0 label or the MTP/ copies.
+    assert set(plans) == {"q4_k_m", "q8_0"}
+    for plan in plans.values():
+        assert "mtp-gemma-4-12b-it.gguf" in plan.target_filenames
+        assert not any("MTP/" in name for name in plan.target_filenames)
+        assert "drafter" in plan.companion_hashes
+        assert "drafter" not in plan.main_hashes
+        assert plan.mmproj_filenames == frozenset({"mmproj-F16.gguf"})
+
+    q4 = plans["q4_k_m"]
+    assert q4.main_filenames == frozenset({"gemma-4-12b-it-Q4_K_M.gguf"})
+    assert q4.main_size_bytes == 4_000
+    # Download size = main + mmproj + drafter.
+    assert q4.download_size_bytes == 4_600
+
+
+def test_baked_in_repo_plans_unchanged():
+    plans = build_gguf_variant_plans([_sib("Qwen3.6-27B-MTP-Q4_K_M.gguf", 4_000, "q4")])
+    assert plans["q4_k_m"].target_filenames == ("Qwen3.6-27B-MTP-Q4_K_M.gguf",)
+
+
+def test_old_manifest_resume_reclassifies_drafter():
+    # Pre-fix manifests could leak the drafter into a quant's expected
+    # files; resume must classify it as a companion, not a main shard.
+    old = [
+        ExpectedFile(path = "gemma-4-12b-it-Q8_0.gguf", size = 8_000, sha256 = "main-q8"),
+        ExpectedFile(path = "mtp-gemma-4-12b-it.gguf", size = 100, sha256 = "drafter"),
+    ]
+    plan = plan_from_expected_files("Q8_0", old)
+    assert plan.main_hashes == frozenset({"main-q8"})
+    assert plan.companion_hashes == frozenset({"drafter"})
+    assert plan.mmproj_filenames == frozenset()
+
+
+# ── Local detection / self-pairing ───────────────────────────────────
+
+
+def test_detect_mtp_file_finds_root_sibling(tmp_path):
+    (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-model.gguf").write_bytes(b"x")
+    (tmp_path / "MTP").mkdir()
+    (tmp_path / "MTP" / "model-Q8_0-MTP.gguf").write_bytes(b"x")
+
+    found = detect_mtp_file(str(tmp_path / "model-Q4_K_M.gguf"))
+    assert found is not None
+    assert found.endswith("mtp-model.gguf")
+
+
+def test_detect_mtp_file_none_without_sibling(tmp_path):
+    (tmp_path / "model-Q4_K_M.gguf").write_bytes(b"x")
+    assert detect_mtp_file(str(tmp_path / "model-Q4_K_M.gguf")) is None
+
+
+def test_detect_gguf_model_rejects_drafter_file(tmp_path):
+    drafter = tmp_path / "mtp-model.gguf"
+    drafter.write_bytes(b"x")
+    assert detect_gguf_model(str(drafter)) is None
+
+
+def test_detect_gguf_model_dir_skips_companions(tmp_path):
+    main = tmp_path / "model-Q4_K_M.gguf"
+    main.write_bytes(b"xxxx")
+    # Companions are larger so a size-sorted pick would wrongly win.
+    (tmp_path / "mtp-model.gguf").write_bytes(b"x" * 64)
+    (tmp_path / "mmproj-F16.gguf").write_bytes(b"x" * 128)
+
+    assert detect_gguf_model(str(tmp_path)) == str(main.resolve())
+
+
+def test_detect_mtp_file_pairs_by_weight_name(tmp_path):
+    # Multi-model folder: each weight must get its own drafter, never the
+    # first-sorted foreign one.
+    (tmp_path / "gemma-4-12b-it-Q4_K_M.gguf").write_bytes(b"x")
+    (tmp_path / "gemma-4-31B-it-Q4_K_M.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-gemma-4-12b-it.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-gemma-4-31B-it.gguf").write_bytes(b"x")
+
+    found = detect_mtp_file(str(tmp_path / "gemma-4-31B-it-Q4_K_M.gguf"))
+    assert found is not None and found.endswith("mtp-gemma-4-31B-it.gguf")
+
+
+def test_detect_mtp_file_skips_foreign_drafter(tmp_path):
+    (tmp_path / "qwen3-8b-Q4_K_M.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-gemma-4-12b-it.gguf").write_bytes(b"x")
+    assert detect_mtp_file(str(tmp_path / "qwen3-8b-Q4_K_M.gguf")) is None
+
+
+def test_detect_mtp_file_qat_prefix_layout(tmp_path):
+    # unsloth's qat repo: drafter stem omits the -qat suffix but prefixes
+    # the weight name (mtp-gemma-4-12B-it.gguf / gemma-4-12B-it-qat-Q4_0.gguf).
+    (tmp_path / "gemma-4-12B-it-qat-Q4_0.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-gemma-4-12B-it.gguf").write_bytes(b"x")
+    found = detect_mtp_file(str(tmp_path / "gemma-4-12B-it-qat-Q4_0.gguf"))
+    assert found is not None and found.endswith("mtp-gemma-4-12B-it.gguf")
+
+
+def test_detect_mtp_file_search_root(tmp_path):
+    # Weight in a quant subdir, drafter at the granted directory root.
+    sub = tmp_path / "Q4_K_M"
+    sub.mkdir()
+    (sub / "gemma-4-12b-it-Q4_K_M.gguf").write_bytes(b"x")
+    (tmp_path / "mtp-gemma-4-12b-it.gguf").write_bytes(b"x")
+    found = detect_mtp_file(str(sub / "gemma-4-12b-it-Q4_K_M.gguf"), search_root = str(tmp_path))
+    assert found is not None and found.endswith("mtp-gemma-4-12b-it.gguf")
+
+
+# ── Reload dedup includes the drafter ────────────────────────────────
+
+
+def _loaded_backend(weight, drafter_path):
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    b = LlamaCppBackend()
+    # Shape matches atexit cleanup expectations (terminate/wait/kill).
+    b._process = SimpleNamespace(
+        poll = lambda: None,
+        terminate = lambda: None,
+        wait = lambda timeout = None: 0,
+        kill = lambda: None,
+    )
+    b._healthy = True
+    b._model_identifier = "local-gemma"
+    b._gguf_path = str(weight)
+    b._hf_variant = None
+    b._requested_n_ctx = 4096
+    b._cache_type_kv = None
+    b._requested_spec_mode = "auto"
+    b._speculative_type = "draft-mtp" if drafter_path else "default"
+    b._spec_draft_n_max = None
+    b._chat_template_override = None
+    b._extra_args = None
+    b._mtp_draft_path = drafter_path
+    return b
+
+
+def _target_state_kwargs(weight, mtp_draft_path):
+    return dict(
+        model_identifier = "local-gemma",
+        hf_variant = None,
+        n_ctx = 4096,
+        cache_type_kv = None,
+        speculative_type = "auto",
+        spec_draft_n_max = None,
+        chat_template_override = None,
+        extra_args = None,
+        is_vision = False,
+        gguf_path = str(weight),
+        mtp_draft_path = mtp_draft_path,
+    )
+
+
+def test_already_in_target_state_bounces_on_new_drafter(tmp_path):
+    weight = tmp_path / "gemma-4-12b-it-Q4_K_M.gguf"
+    weight.write_bytes(b"x")
+    drafter = tmp_path / "mtp-gemma-4-12b-it.gguf"
+    drafter.write_bytes(b"x")
+
+    # Loaded without a drafter; one now exists on disk -> must reload.
+    b = _loaded_backend(weight, None)
+    assert not b._already_in_target_state(**_target_state_kwargs(weight, str(drafter)))
+    # Same drafter as launched -> still deduped.
+    b = _loaded_backend(weight, str(drafter))
+    assert b._already_in_target_state(**_target_state_kwargs(weight, str(drafter)))
+
+
+def test_detect_gguf_model_rejects_mtp_subdir_copy(tmp_path):
+    # Direct selection of an MTP/ copy: the basename alone has no mtp-
+    # prefix, so rejection relies on the parent dir name.
+    sub = tmp_path / "MTP"
+    sub.mkdir()
+    copy = sub / "gemma-4-12b-it-BF16-MTP.gguf"
+    copy.write_bytes(b"x")
+    assert detect_gguf_model(str(copy)) is None
+    # Selecting the MTP dir itself must not surface the copies as models.
+    assert detect_gguf_model(str(sub)) is None
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 9dc01f83c5..f61c210cf6 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -58,25 +58,28 @@ import re as _re
 _MODEL_SIZE_RE = _re.compile(r"(?:^|[-_/])(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
 # MoE active-parameter pattern: "A3B", "A3.5B", etc.
 _ACTIVE_SIZE_RE = _re.compile(r"(?:^|[-_/])a(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
+# Gemma 3n/4 effective-parameter pattern: "E2B", "E4B" -- the runtime
+# footprint (MatFormer + per-layer embeddings), which is the size that
+# matters for size-gated policies like sub-3B speculative-decoding fallback.
+_EFFECTIVE_SIZE_RE = _re.compile(r"(?:^|[-_/])e(\d+\.?\d*)\s*([bm])(?:$|[-_/])", _re.IGNORECASE)
 
 
 def extract_model_size_b(model_id: str) -> float | None:
     """Extract model size in billions from a model identifier.
 
     Prefers MoE active-parameter notation (e.g. ``A3B`` in
-    ``Qwen3.5-35B-A3B``) over total params. Handles ``B`` (billions)
-    and ``M`` (millions) suffixes.
+    ``Qwen3.5-35B-A3B``), then Gemma effective-parameter notation
+    (e.g. ``E2B``), over total params. Handles ``B`` (billions) and
+    ``M`` (millions) suffixes.
     """
     mid = (model_id or "").lower()
-    active = _ACTIVE_SIZE_RE.search(mid)
-    if active:
-        val = float(active.group(1))
-        return val / 1000.0 if active.group(2).lower() == "m" else val
-    size = _MODEL_SIZE_RE.search(mid)
-    if not size:
-        return None
-    val = float(size.group(1))
-    return val / 1000.0 if size.group(2).lower() == "m" else val
+    # First match wins, in priority order: active > effective > total.
+    for pattern in (_ACTIVE_SIZE_RE, _EFFECTIVE_SIZE_RE, _MODEL_SIZE_RE):
+        m = pattern.search(mid)
+        if m:
+            val = float(m.group(1))
+            return val / 1000.0 if m.group(2).lower() == "m" else val
+    return None
 
 
 # Maps equivalent model names to their canonical YAML config file.
@@ -930,6 +933,24 @@ def _is_mmproj(filename: str) -> bool:
     return "mmproj" in filename.lower()
 
 
+def _is_mtp_drafter(path: str) -> bool:
+    """True for a separate-file MTP drafter (speculative head), a companion
+    to the main model rather than a selectable quant: the repo-root
+    ``mtp-*.gguf`` or the ``MTP/`` subdir copies (Gemma 4).
+
+    Mirrors hub.utils.gguf.is_mtp_drafter_path (utils cannot import hub).
+    Must be excluded everywhere mmproj is, or the drafter leaks into variant
+    menus (a phantom quant) and quant-matched file lookups -- e.g. a ``Q8_0``
+    request must not resolve to ``MTP/...-Q8_0-MTP.gguf``, which sorts ahead
+    of the real weight.
+    """
+    p = path.lower()
+    if not p.endswith(".gguf"):
+        return False
+    name = p.rsplit("/", 1)[-1]
+    return name.startswith("mtp-") or "/mtp/" in f"/{p}"
+
+
 # Family tokens for #5347's filename fallback. Lowercase; order irrelevant.
 _MODEL_FAMILY_TOKENS: tuple[str, ...] = (
     "qwen",
@@ -1137,6 +1158,48 @@ def detect_mmproj_file(path: str, search_root: Optional[str] = None) -> Optional
     return str(best[1])
 
 
+def detect_mtp_file(path: str, search_root: Optional[str] = None) -> Optional[str]:
+    """Find the separate MTP drafter (``mtp-*.gguf``) for a local GGUF model.
+
+    The drafter that pairs with the main weights sits at the repo/snapshot
+    root (Gemma 4); the weight itself may be at the root or in a quant subdir,
+    so scan the weight's directory and ``search_root``. Matches by the
+    ``mtp-`` filename prefix unsloth uses for ``-hf`` auto-discovery -- the
+    same signal as the HF download path. Repos that bake the head into the
+    main GGUF (Qwen) have no such sibling, so this returns None.
+
+    Pairs by name so a multi-model folder can't attach a foreign drafter:
+    unsloth names the drafter ``mtp-<model>.gguf`` where ``<model>`` prefixes
+    the weight filename across all Gemma 4 repos (e.g.
+    ``mtp-gemma-4-12B-it.gguf`` next to ``gemma-4-12B-it-qat-Q4_0.gguf``).
+    An unmatched drafter is skipped (fail-safe: no MTP).
+    """
+    p = Path(path)
+    weight_name = p.name.lower() if p.suffix.lower() == ".gguf" else None
+    start_dir = p.parent if p.is_file() else p
+    dirs = [start_dir]
+    if search_root is not None:
+        dirs.append(Path(search_root))
+    for d in dirs:
+        try:
+            entries = sorted(d.iterdir())
+        except OSError:
+            continue
+        for f in entries:
+            name = f.name.lower()
+            if not (name.startswith("mtp-") and name.endswith(".gguf")):
+                continue
+            stem = name[len("mtp-") : -len(".gguf")]
+            if not stem or (weight_name is not None and not weight_name.startswith(stem)):
+                continue
+            try:
+                if f.is_file():
+                    return str(f.resolve())
+            except OSError:
+                continue
+    return None
+
+
 def detect_gguf_model(path: str) -> Optional[str]:
     """Check if a local path is or contains a GGUF model file.
 
@@ -1148,7 +1211,12 @@ def detect_gguf_model(path: str) -> Optional[str]:
 
     # Case 1: direct .gguf file
     if p.suffix.lower() == ".gguf":
-        if _is_mmproj(p.name):
+        # Companions are not models: rejecting a drafter here also keeps
+        # detect_mtp_file from pairing the same file with itself
+        # (-m drafter --model-draft drafter). Include the immediate parent
+        # dir so the MTP/ subdir copies are caught -- the basename alone
+        # (...-MTP.gguf) doesn't match the predicate's mtp- prefix.
+        if _is_mmproj(p.name) or _is_mtp_drafter(f"{p.parent.name}/{p.name}"):
             return None
         # Extension is authoritative: don't gate on is_file()/exists(), which
         # can fail in the Windows lock window after llama-server is killed.
@@ -1160,10 +1228,14 @@ def detect_gguf_model(path: str) -> Optional[str]:
             return str(p.absolute())  # absolute() keeps symlink names readable
         # Directory named "*.gguf": fall through to the dir scan below.
 
-    # Case 2: directory containing .gguf files (skip mmproj)
+    # Case 2: directory containing .gguf files (skip mmproj / MTP drafter)
     if p.is_dir():
         gguf_files = sorted(
-            (f for f in _iter_gguf_files(p) if not _is_mmproj(f.name)),
+            (
+                f
+                for f in _iter_gguf_files(p)
+                if not _is_mmproj(f.name) and not _is_mtp_drafter(f"{f.parent.name}/{f.name}")
+            ),
             key = lambda f: f.stat().st_size,
             reverse = True,
         )
@@ -1393,6 +1465,9 @@ def list_gguf_variants(
         if "mmproj" in fname.lower():
             has_vision = True
             continue
+        # MTP drafters are speculative-decoding companions, not quants.
+        if _is_mtp_drafter(fname):
+            continue
 
         quant = _extract_quant_label(fname)
         quant_totals[quant] = quant_totals.get(quant, 0) + size
@@ -1468,6 +1543,8 @@ def list_local_gguf_variants(directory: str) -> tuple[list[GgufVariantInfo], boo
         # Use the relative path so ``BF16/foo.gguf`` and ``Q4_K_M/foo.gguf``
         # get distinct quant labels instead of collapsing on basename.
         rel = f.relative_to(p).as_posix()
+        if _is_mtp_drafter(rel):
+            continue
         quant = _extract_quant_label(rel)
         quant_totals[quant] = quant_totals.get(quant, 0) + size
         if quant not in quant_first_file:
@@ -1504,7 +1581,9 @@ def _find_local_gguf_by_variant(directory: str, variant: str) -> Optional[str]:
     matches = sorted(
         f
         for f in _iter_gguf_files(p, recursive = True)
-        if not _is_mmproj(f.name) and _extract_quant_label(f.relative_to(p).as_posix()) == variant
+        if not _is_mmproj(f.name)
+        and not _is_mtp_drafter(f.relative_to(p).as_posix())
+        and _extract_quant_label(f.relative_to(p).as_posix()) == variant
     )
     if matches:
         return str(matches[0].resolve())
@@ -1519,9 +1598,9 @@ def _detect_gguf_from_hf_cache(repo_id: str) -> Optional[str]:
     """
     for snap in _iter_hf_cache_snapshots(repo_id):
         rel_files = [
-            f.relative_to(snap).as_posix()
+            rel
             for f in _iter_gguf_files(snap, recursive = True)
-            if not _is_mmproj(f.name)
+            if not _is_mtp_drafter(rel := f.relative_to(snap).as_posix()) and not _is_mmproj(f.name)
         ]
         if rel_files:
             return _pick_best_gguf(rel_files)
@@ -2068,6 +2147,7 @@ class ModelConfig:
     has_audio_input: bool = False  # Accepts audio input (ASR/speech understanding)
     gguf_file: Optional[str] = None  # Full path to the .gguf file (local mode)
     gguf_mmproj_file: Optional[str] = None  # Full path to the mmproj .gguf file (vision projection)
+    gguf_mtp_file: Optional[str] = None  # Full path to the separate MTP drafter (local mode)
     gguf_hf_repo: Optional[str] = (
         None  # HF repo ID for -hf mode (e.g. "unsloth/gemma-3-4b-it-GGUF")
     )
@@ -2207,6 +2287,11 @@ class ModelConfig:
                 elif base_is_vision:
                     logger.warning(f"Base model is vision but no mmproj file found in {gguf_dir}")
 
+                # Separate MTP drafter sibling (Gemma 4), mirroring mmproj.
+                mtp_file = detect_mtp_file(gguf_file, search_root = path)
+                if mtp_file:
+                    logger.info(f"Detected MTP drafter: {mtp_file}")
+
                 return cls(
                     identifier = identifier,
                     display_name = display_name,
@@ -2218,6 +2303,7 @@ class ModelConfig:
                     is_gguf = True,
                     gguf_file = gguf_file,
                     gguf_mmproj_file = mmproj_file,
+                    gguf_mtp_file = mtp_file,
                 )
         else:
             # Does the HF repo contain GGUF files?

From 8bca7bcfc9f0d942f17fb3d67ae428fbb3dfbc7d Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 08:45:30 -0700
Subject: [PATCH 161/222] Studio: accept audio files through Add photos & files
 and fix the audio gate for Gemma 4 models (#6064)

* Studio: sync detected model capabilities into models[] after load

The chat composer gates audio upload on activeModel.hasAudioInput, but
/api/models/list omits audio fields for default and active-GGUF entries
and the single chat load path never wrote the load response's
capability flags back into the store. Audio-capable models such as the
Gemma 4 GGUFs therefore never unlocked audio input in the main chat,
while the compare composer (which does sync) worked.

Add syncModelCapabilities and call it after a successful load and after
the status fetch in refresh, so the flags also survive F5 and are not
clobbered by stale catalog data.

* Studio: merge audio upload into the Add photos & files picker

Remove the separate Upload audio row from the composer plus menu and
register an AudioAttachmentAdapter in the shared attachment pipeline,
so the standard picker and drag-drop accept wav, mp3, m4a, ogg, flac
and webm directly. Gating matches images: the picker always lists
audio and models without audio input get a toast at add() time. The
50MB limit is kept and the file shows as a normal attachment chip.

On send the adapter emits an audio content part on the attachment and
findLatestUserAudioBase64 now also scans attachment content, so the
request still carries audio_base64 exactly as before.

* Studio: extract AudioAttachmentAdapter into its own module

Move the adapter out of runtime-provider.tsx so it is importable in
isolation, export the audio send-path and capability-sync helpers for
tests, and guard attachment id generation for non-secure contexts
(crypto.randomUUID is undefined over plain HTTP on a LAN, matching the
existing guard in startCompare).

* Studio: do not claim .webm by extension in the audio adapter

A video/webm file would match the .webm extension entry and route to
the audio adapter. Real audio webm (MediaRecorder output) always
reports the audio/webm MIME, so matching webm by MIME only keeps video
files out while keeping recorded audio working.

* Studio: only send audio from the newest user message

audio_base64 switches the backend onto the audio generation path
(generate_whisper_response ignores chat messages entirely and
generate_audio_input_response bypasses the normal streaming path), so
replaying audio from an older turn hijacked text-only follow-ups:
Whisper would retranscribe the stale clip instead of erroring cleanly,
and audio VLMs lost tools and streaming. Stop the scan at the newest
user message, matching the consumed-on-send semantics of the legacy
pendingAudio path. Regenerating the audio turn itself still resends
its audio since it is the newest user message in that run.

Also guard extractAudioPartBase64 against null parts in deserialized
history content.

* Studio: forward audio input to llama-server for GGUF models (#6096)

* Studio: forward audio input to llama-server for GGUF models

* Studio: harden GGUF audio input handling (multi-format decode, size cap)

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: carry GGUF audio in the message list so it works with tools

* Studio: bound decoded audio length and make the soundfile decoder optional

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Handle audio attachment edge cases

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: gate audio file picker by loaded model capability (#6142)

* Gate audio attachments by loaded model

* Use conditional spread for audio attachment adapter

* Preserve audio fallback while filtering picker

---------

Co-authored-by: Unsloth <michaelhan@Michaels-MacBook-Pro.local>
Co-authored-by: oobabooga <oobabooga4@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: imagineer99 <samleejackson0@gmail.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/backend/models/inference.py            |   3 +-
 studio/backend/routes/inference.py            | 204 +++++++++++++++++-
 .../src/components/assistant-ui/thread.tsx    | 129 ++++++-----
 .../src/features/chat/api/chat-adapter.ts     |  49 ++++-
 .../features/chat/audio-attachment-adapter.ts |  96 +++++++++
 .../chat/hooks/use-chat-model-runtime.ts      |  49 +++++
 .../src/features/chat/runtime-provider.tsx    |   2 +
 7 files changed, 450 insertions(+), 82 deletions(-)
 create mode 100644 studio/frontend/src/features/chat/audio-attachment-adapter.ts

diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 96f24887bd..c83c8ecc1b 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -631,7 +631,8 @@ class ChatCompletionRequest(BaseModel):
         None, description = "[x-unsloth] Base64-encoded image for vision models"
     )
     audio_base64: Optional[str] = Field(
-        None, description = "[x-unsloth] Base64-encoded WAV for audio-input models (ASR)"
+        None,
+        description = "[x-unsloth] Base64-encoded audio (wav/mp3/ogg/flac/m4a) for audio-input models",
     )
     use_adapter: Optional[Union[bool, str]] = Field(
         None,
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 418206e938..70a5a3efe7 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -2124,6 +2124,172 @@ def _decode_audio_base64(b64: str) -> np.ndarray:
     return waveform.squeeze(0).numpy()
 
 
+# Reject oversized audio before decoding. base64 inflates raw bytes by ~4/3, so
+# cap the encoded length to bound the upload. _MAX_AUDIO_SECONDS additionally
+# bounds the *decoded* length, since a small compressed file (opus/flac/etc.)
+# can expand to a far larger PCM array than the encoded-size cap implies.
+_MAX_AUDIO_RAW_BYTES = 25 * 1024 * 1024
+_MAX_AUDIO_B64_CHARS = _MAX_AUDIO_RAW_BYTES * 4 // 3
+_MAX_AUDIO_SECONDS = 30 * 60
+_WAV_HEADER_BYTES = 44
+_MIN_TRANSCODE_AUDIO_SAMPLE_RATE = 8000
+
+
+def _sniff_audio_container(raw: bytes) -> Optional[str]:
+    """Return 'wav' or 'mp3' if the bytes are a container llama-server accepts
+    directly (so we can forward them untouched), else None (needs transcoding)."""
+    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE":
+        return "wav"
+    # mp3: ID3 tag, or an MPEG audio frame sync (no other accepted format leads
+    # with 0xFF, so the simple sync check doesn't collide).
+    if raw[:3] == b"ID3" or (len(raw) >= 2 and raw[0] == 0xFF and (raw[1] & 0xE0) == 0xE0):
+        return "mp3"
+    return None
+
+
+def _mono_f32_to_wav_bytes(arr: np.ndarray, sample_rate: int) -> bytes:
+    """Encode a mono float32 array as 16-bit PCM WAV bytes.
+
+    Torch-free (numpy + stdlib only) so it works on no-torch GGUF-only installs;
+    the shared audio_codecs helper pulls in torch at import time.
+    """
+    import io
+    import wave
+
+    arr = np.nan_to_num(np.asarray(arr, dtype = np.float32).flatten(), posinf = 0.0, neginf = 0.0)
+    if arr.size == 0:
+        raise ValueError("decoded audio is empty")
+    peak = float(np.abs(arr).max())
+    if peak > 1.0:
+        arr = arr / peak
+    pcm = (arr * 32767.0).astype(np.int16)
+
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(int(sample_rate))
+        wf.writeframes(pcm.tobytes())
+    return buf.getvalue()
+
+
+def _resample_mono_linear(arr: np.ndarray, source_rate: int, target_rate: int) -> np.ndarray:
+    """Small numpy-only resampler for upload size limiting."""
+    if source_rate <= 0 or target_rate <= 0 or source_rate == target_rate:
+        return arr
+    duration = len(arr) / float(source_rate)
+    target_len = max(1, int(round(duration * target_rate)))
+    if target_len == len(arr):
+        return arr
+    source_x = np.linspace(0.0, duration, num = len(arr), endpoint = False)
+    target_x = np.linspace(0.0, duration, num = target_len, endpoint = False)
+    return np.interp(target_x, source_x, arr).astype(np.float32)
+
+
+def _fit_transcoded_audio_to_wav_cap(arr: np.ndarray, sample_rate: int) -> tuple[np.ndarray, int]:
+    """Downsample only when needed so transcoded WAV stays within the upload cap."""
+    if sample_rate <= 0:
+        raise ValueError("decoded audio has an invalid sample rate")
+    wav_bytes = _WAV_HEADER_BYTES + len(arr) * 2
+    if wav_bytes <= _MAX_AUDIO_RAW_BYTES:
+        return arr, sample_rate
+
+    duration = len(arr) / float(sample_rate)
+    max_samples = max(1, (_MAX_AUDIO_RAW_BYTES - _WAV_HEADER_BYTES) // 2)
+    target_rate = int(max_samples // duration)
+    if target_rate < _MIN_TRANSCODE_AUDIO_SAMPLE_RATE:
+        raise ValueError("decoded audio exceeds the transcoded WAV size limit")
+    target_rate = min(sample_rate, target_rate)
+    fitted = _resample_mono_linear(arr, sample_rate, target_rate)
+    if _WAV_HEADER_BYTES + len(fitted) * 2 > _MAX_AUDIO_RAW_BYTES:
+        raise ValueError("decoded audio exceeds the transcoded WAV size limit")
+    return fitted, target_rate
+
+
+def _decode_audio_mono(raw: bytes) -> tuple[np.ndarray, int]:
+    """Decode audio bytes to (mono float32 array, native sample_rate).
+
+    soundfile (libsndfile) reads wav/mp3/ogg/flac straight from memory. librosa
+    (ffmpeg-backed) additionally covers m4a/webm but needs a real path and is
+    absent on no-torch GGUF-only installs. Both imports are inside the fallback
+    so a missing decoder degrades to the next one (and finally a clear error)
+    rather than crashing.
+    """
+    import io
+
+    try:
+        import soundfile as sf
+        arr, sr = sf.read(io.BytesIO(raw), dtype = "float32")
+    except Exception:
+        try:
+            import librosa
+        except ModuleNotFoundError as e:
+            raise RuntimeError(
+                "this audio format needs librosa, which is not installed in "
+                "GGUF-only environments; use wav, mp3, ogg or flac"
+            ) from e
+        import os
+        import tempfile
+        from utils.paths import ensure_dir, tmp_root
+
+        with tempfile.NamedTemporaryFile(
+            suffix = ".audio",
+            delete = False,
+            dir = str(ensure_dir(tmp_root())),
+        ) as tmp:
+            tmp.write(raw)
+            tmp_path = tmp.name
+        try:
+            arr, sr = librosa.load(tmp_path, sr = None, mono = True)
+        finally:
+            os.unlink(tmp_path)
+    if arr.ndim > 1:
+        arr = arr.mean(axis = 1)
+    if sr > 0 and len(arr) > sr * _MAX_AUDIO_SECONDS:
+        raise ValueError(f"decoded audio exceeds the {_MAX_AUDIO_SECONDS // 60}-minute limit")
+    return arr, sr
+
+
+def _prepare_audio_for_llama(b64: str) -> tuple[str, str]:
+    """Return (base64, format) ready for llama-server's input_audio part.
+
+    llama-server's API only accepts wav/mp3, and decodes/resamples/down-mixes
+    them itself, so wav and mp3 uploads are forwarded untouched (no decode, no
+    PCM payload inflation). Other containers (m4a/ogg/webm/flac) are decoded to
+    a mono WAV. Blocking; call via a thread from async paths.
+    """
+    if b64.startswith("data:"):
+        b64 = b64.split(",", 1)[1] if "," in b64 else ""
+    raw = base64.b64decode(b64)
+    passthrough = _sniff_audio_container(raw)
+    if passthrough is not None:
+        return b64, passthrough
+
+    arr, sr = _decode_audio_mono(raw)
+    arr, sr = _fit_transcoded_audio_to_wav_cap(arr, sr)
+    return base64.b64encode(_mono_f32_to_wav_bytes(arr, sr)).decode("ascii"), "wav"
+
+
+def _inject_audio_part(messages: list[dict], audio_b64: str, audio_format: str) -> None:
+    """Append an input_audio part to the last user message, in place.
+
+    Audio rides in the message list like image_url parts do, so it flows through
+    both the plain and tool-calling generation paths.
+    """
+    part = {
+        "type": "input_audio",
+        "input_audio": {"data": audio_b64, "format": audio_format},
+    }
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            content = msg.get("content")
+            if isinstance(content, list):
+                content.append(part)
+            else:
+                msg["content"] = [{"type": "text", "text": content or ""}, part]
+            return
+
+
 def _extract_content_parts(messages: list) -> tuple[str, list[dict], "Optional[str]"]:
     """
     Parse OpenAI-format messages into components the inference backend expects.
@@ -3081,9 +3247,12 @@ async def openai_chat_completions(
         if _wants_multiple_choices(payload):
             _raise_unsupported_n("GGUF tool or response_format passthrough")
         if payload.audio_base64:
+            # This path forwards the request verbatim, so the transcoded audio
+            # never gets injected. (The agentic tool loop below does support
+            # audio.)
             raise HTTPException(
                 status_code = 400,
-                detail = "Audio input is not supported for GGUF chat models yet.",
+                detail = "Audio input is not supported together with guided decoding or client-supplied tools yet.",
             )
 
         # Preserve the vision guard from the non-passthrough path below:
@@ -3134,11 +3303,34 @@ async def openai_chat_completions(
 
     # ── GGUF path: proxy to llama-server /v1/chat/completions ──
     if using_gguf:
+        # Forward uploaded audio as an input_audio part. wav/mp3 pass through
+        # untouched (llama-server decodes and resamples them via the mmproj
+        # audio encoder); other containers are transcoded to WAV here. The part
+        # is injected into the message list below so it rides through both the
+        # plain and tool-calling paths, exactly like image_url parts.
+        audio_b64 = None
+        audio_format = "wav"
         if payload.audio_base64:
-            raise HTTPException(
-                status_code = 400,
-                detail = "Audio input is not supported for GGUF chat models yet.",
-            )
+            if not getattr(llama_backend, "_has_audio_input", False):
+                raise HTTPException(
+                    status_code = 400,
+                    detail = "Audio provided but current GGUF model does not support audio input.",
+                )
+            if len(payload.audio_base64) > _MAX_AUDIO_B64_CHARS:
+                raise HTTPException(
+                    status_code = 413,
+                    detail = "Audio file is too large (max ~25 MB).",
+                )
+            try:
+                audio_b64, audio_format = await asyncio.to_thread(
+                    _prepare_audio_for_llama, payload.audio_base64
+                )
+            except Exception as e:
+                logger.warning("Audio decode failed: %s", e, exc_info = True)
+                raise HTTPException(
+                    status_code = 400,
+                    detail = "Could not decode the provided audio file.",
+                )
 
         gguf_messages, _ = _openai_messages_for_gguf_chat(
             payload,
@@ -3146,6 +3338,8 @@ async def openai_chat_completions(
         )
         gguf_messages = _set_or_prepend_system_message(gguf_messages, system_prompt)
         image_b64 = None
+        if audio_b64:
+            _inject_audio_part(gguf_messages, audio_b64, audio_format)
 
         cancel_event = threading.Event()
 
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 3763370dcd..0a165724d0 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -75,7 +75,6 @@ import { DocumentPreviewMount } from "@/features/rag/components/document-preview
 import { useUserProfileStore } from "@/features/profile/stores/user-profile-store";
 import { applyQwenThinkingParams } from "@/features/chat/utils/qwen-params";
 import { isTauri } from "@/lib/api-base";
-import { AUDIO_ACCEPT, MAX_AUDIO_SIZE, fileToBase64 } from "@/lib/audio-utils";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { toast } from "@/lib/toast";
 import { cn } from "@/lib/utils";
@@ -1388,63 +1387,6 @@ function useImeComposerInputHandlers() {
   };
 }
 
-// Audio upload row, only for audio-input models.
-const ComposerAudioMenuItem: FC = () => {
-  const setPendingAudio = useChatRuntimeStore((s) => s.setPendingAudio);
-  const activeModel = useChatRuntimeStore((s) => {
-    const checkpoint = s.params.checkpoint;
-    return s.models.find((m) => m.id === checkpoint);
-  });
-
-  const handleAudioFile = useCallback(
-    async (file: File) => {
-      if (file.size > MAX_AUDIO_SIZE) {
-        return;
-      }
-      try {
-        const base64 = await fileToBase64(file);
-        setPendingAudio(base64, file.name);
-      } catch {
-        // skip
-      }
-    },
-    [setPendingAudio],
-  );
-
-  // Build the input on document.body, not in the menu: selecting the item
-  // closes the dropdown, unmounting a menu-rendered input before the OS picker
-  // returns and dropping the file.
-  const pickAudio = useCallback(() => {
-    const input = document.createElement("input");
-    input.type = "file";
-    input.accept = AUDIO_ACCEPT;
-    input.hidden = true;
-    document.body.appendChild(input);
-    input.onchange = () => {
-      const file = input.files?.[0];
-      if (file) handleAudioFile(file);
-      document.body.removeChild(input);
-    };
-    input.oncancel = () => {
-      if (!input.files || input.files.length === 0) {
-        document.body.removeChild(input);
-      }
-    };
-    input.click();
-  }, [handleAudioFile]);
-
-  if (!activeModel?.hasAudioInput) {
-    return null;
-  }
-
-  return (
-    <DropdownMenuItem onSelect={() => pickAudio()}>
-      <HeadphonesIcon />
-      Upload audio
-    </DropdownMenuItem>
-  );
-};
-
 // Phosphor microphone. Inlined to avoid a new icon dependency.
 const MicIcon: FC<{ className?: string }> = ({ className }) => (
   <svg
@@ -2000,6 +1942,21 @@ const ToolStatusDisplay: FC = () => {
 };
 // Plus menu: attachment and workflow actions. Opens downward in the welcome
 // composer; the docked composer passes side="top" to open upward.
+const AUDIO_ACCEPT_TOKEN_RE =
+  /^(audio\/|\.(?:wav|mp3|m4a|ogg|oga|flac)$)/i;
+
+function attachmentAcceptForPicker(accept: string, audioEnabled: boolean): string {
+  if (audioEnabled || accept === "*") {
+    return accept;
+  }
+  const filtered = accept
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => token && !AUDIO_ACCEPT_TOKEN_RE.test(token))
+    .join(",");
+  return filtered || accept;
+}
+
 const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   side = "bottom",
 }) => {
@@ -2023,6 +1980,14 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const modelLoaded = useChatRuntimeStore(
     (s) => !!s.params.checkpoint && !s.modelLoading,
   );
+  const audioAttachmentsEnabled = useChatRuntimeStore((s) => {
+    const activeCheckpoint = s.params.checkpoint;
+    if (!activeCheckpoint || s.modelLoading) {
+      return false;
+    }
+    const activeModel = s.models.find((m) => m.id === activeCheckpoint);
+    return Boolean(activeModel?.hasAudioInput);
+  });
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const supportsTools = useChatRuntimeStore((s) => s.supportsTools);
   const supportsBuiltinWebSearch = useChatRuntimeStore(
@@ -2085,6 +2050,40 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
   const [promptStorageOpen, setPromptStorageOpen] = useState(false);
   const activeThreadId = useChatRuntimeStore((s) => s.activeThreadId);
   const aui = useAui();
+  const composerCanAddAttachments = useAuiState(
+    ({ composer }) => composer.isEditing,
+  );
+  const pickAttachment = useCallback(() => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.multiple = true;
+    input.hidden = true;
+
+    const attachmentAccept = attachmentAcceptForPicker(
+      aui.composer().getState().attachmentAccept,
+      audioAttachmentsEnabled,
+    );
+    if (attachmentAccept !== "*") {
+      input.accept = attachmentAccept;
+    }
+
+    document.body.appendChild(input);
+    input.onchange = (event) => {
+      const files = (event.target as HTMLInputElement).files;
+      if (files) {
+        for (const file of files) {
+          void aui.composer().addAttachment(file);
+        }
+      }
+      document.body.removeChild(input);
+    };
+    input.oncancel = () => {
+      if (!input.files || input.files.length === 0) {
+        document.body.removeChild(input);
+      }
+    };
+    input.click();
+  }, [aui, audioAttachmentsEnabled]);
   // Disable Export chat until the thread has content.
   const messageCount = useAuiState(({ thread }) => thread.messages.length);
   const { startQueue } = useContext(PromptQueueContext);
@@ -2136,13 +2135,13 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
         // Don't refocus the + on close; restored focus showed a stray ring.
         onCloseAutoFocus={(event) => event.preventDefault()}
       >
-        <ComposerPrimitive.AddAttachment asChild={true}>
-          <DropdownMenuItem>
-            <HugeiconsIcon icon={AttachmentIcon} strokeWidth={2} />
-            Add photos &amp; files
-          </DropdownMenuItem>
-        </ComposerPrimitive.AddAttachment>
-        <ComposerAudioMenuItem />
+        <DropdownMenuItem
+          disabled={!composerCanAddAttachments}
+          onSelect={() => pickAttachment()}
+        >
+          <HugeiconsIcon icon={AttachmentIcon} strokeWidth={2} />
+          Add photos &amp; files
+        </DropdownMenuItem>
         <DropdownMenuItem
           disabled={searchDisabled}
           className={
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index f0d229b412..d944c7ab74 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -986,24 +986,51 @@ function findLatestUserImageBase64(messages: RunMessages): string | undefined {
   return undefined;
 }
 
-function findLatestUserAudioBase64(messages: RunMessages): string | undefined {
-  // Message content parts (compare view CompareMessagePart type: "audio").
+function extractAudioPartBase64(
+  part: { type: string } | null | undefined,
+): string | undefined {
+  if (!part || part.type !== "audio" || !("audio" in part)) return undefined;
+  const audioPart = (
+    part as unknown as {
+      type: "audio";
+      audio: string | { data: string; format: string };
+    }
+  ).audio;
+  const raw = typeof audioPart === "string" ? audioPart : audioPart?.data;
+  if (!raw) return undefined;
+  return raw.startsWith("data:") ? raw.split(",")[1] : raw;
+}
+
+// Exported for tests.
+export function findLatestUserAudioBase64(
+  messages: RunMessages,
+): string | undefined {
   for (let i = messages.length - 1; i >= 0; i -= 1) {
     const message = messages[i];
     if (!message || message.role !== "user") continue;
 
+    // Message content parts (from compare view's CompareMessagePart with type: "audio")
     for (const part of message.content ?? []) {
-      if (part.type === "audio" && "audio" in part) {
-        const audioPart = (
-          part as unknown as {
-            type: "audio";
-            audio: string | { data: string; format: string };
-          }
-        ).audio;
-        const raw = typeof audioPart === "string" ? audioPart : audioPart?.data;
-        if (raw) return raw.startsWith("data:") ? raw.split(",")[1] : raw;
+      const base64 = extractAudioPartBase64(part);
+      if (base64) return base64;
+    }
+
+    // Attachment content parts (from AudioAttachmentAdapter)
+    if ("attachments" in message) {
+      for (const attachment of message.attachments ?? []) {
+        for (const part of attachment.content ?? []) {
+          const base64 = extractAudioPartBase64(part);
+          if (base64) return base64;
+        }
       }
     }
+
+    // Only the newest user message counts. audio_base64 switches the
+    // backend onto the audio generation path, so replaying audio from an
+    // older turn would hijack text follow-ups (Whisper would retranscribe
+    // the stale clip). Matches the consumed-on-send semantics of the
+    // legacy pendingAudio path.
+    break;
   }
 
   // Runtime store (main composer's audio upload).
diff --git a/studio/frontend/src/features/chat/audio-attachment-adapter.ts b/studio/frontend/src/features/chat/audio-attachment-adapter.ts
new file mode 100644
index 0000000000..148f025e57
--- /dev/null
+++ b/studio/frontend/src/features/chat/audio-attachment-adapter.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import {
+  AUDIO_ACCEPT,
+  MAX_AUDIO_SIZE,
+  fileToBase64,
+} from "@/lib/audio-utils";
+import type {
+  Attachment,
+  AttachmentAdapter,
+  CompleteAttachment,
+  PendingAttachment,
+} from "@assistant-ui/react";
+import { toast } from "sonner";
+import { useChatRuntimeStore } from "./stores/chat-runtime-store";
+
+// crypto.randomUUID is undefined in non-secure contexts (HTTP over a LAN IP).
+function newAttachmentId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// Audio shares the "Add photos & files" picker. Like VisionImageAdapter,
+// unsupported models are rejected at add() time with a toast.
+export class AudioAttachmentAdapter implements AttachmentAdapter {
+  // MIME is unreliable for some containers (m4a), so also match by
+  // extension. No .webm extension: it would claim video/webm files; real
+  // audio webm (MediaRecorder) always reports the audio/webm MIME.
+  accept = `${AUDIO_ACCEPT},audio/x-m4a,.wav,.mp3,.m4a,.ogg,.oga,.flac`;
+  private readonly attachmentIds = new Set<string>();
+
+  async add({ file }: { file: File }): Promise<PendingAttachment> {
+    const state = useChatRuntimeStore.getState();
+    const checkpoint = state.params.checkpoint;
+    const activeModel = state.models.find((m) => m.id === checkpoint);
+    const modelLoaded = !!checkpoint && !state.modelLoading;
+    let unavailableReason: string | null = null;
+    if (!modelLoaded) {
+      unavailableReason = "Load a model before adding audio files.";
+    } else if (!activeModel?.hasAudioInput) {
+      const label = activeModel?.name || checkpoint || "Current model";
+      unavailableReason = `${label} cannot accept audio. Load an audio-input model before attaching audio files.`;
+    }
+    if (unavailableReason) {
+      toast.error(unavailableReason);
+      throw new Error(unavailableReason);
+    }
+    if (file.size > MAX_AUDIO_SIZE) {
+      const sizeReason = "Audio size exceeds 50MB limit";
+      toast.error(sizeReason);
+      throw new Error(sizeReason);
+    }
+    if (this.attachmentIds.size > 0 || state.pendingAudioBase64) {
+      const duplicateReason = "Only one audio file can be attached per message.";
+      toast.error(duplicateReason);
+      throw new Error(duplicateReason);
+    }
+
+    const id = newAttachmentId();
+    this.attachmentIds.add(id);
+    return {
+      id,
+      type: "file",
+      name: file.name,
+      contentType: file.type,
+      file,
+      status: { type: "requires-action", reason: "composer-send" },
+    };
+  }
+
+  async send(attachment: PendingAttachment): Promise<CompleteAttachment> {
+    try {
+      const base64 = await fileToBase64(attachment.file);
+      // Backend takes raw base64; format only satisfies the part type.
+      const format = attachment.contentType === "audio/mpeg" ? "mp3" : "wav";
+      return {
+        id: attachment.id,
+        type: "file",
+        name: attachment.name,
+        contentType: attachment.contentType,
+        content: [{ type: "audio", audio: { data: base64, format } }],
+        status: { type: "complete" },
+      };
+    } finally {
+      this.attachmentIds.delete(attachment.id);
+    }
+  }
+
+  remove(attachment: Attachment): Promise<void> {
+    this.attachmentIds.delete(attachment.id);
+    return Promise.resolve();
+  }
+}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index a152cbb358..66ee2d04e4 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -142,6 +142,50 @@ function toChatModelSummary(model: {
   };
 }
 
+// Merge capability flags from a load/status response into the matching
+// models[] entry. /api/models/list omits audio capability for default and
+// active-GGUF entries, so the attach gates (`activeModel?.hasAudioInput`)
+// would otherwise stay false. Mirrors the compare composer's sync.
+// Exported for tests.
+export function syncModelCapabilities(
+  modelId: string,
+  resp: {
+    display_name?: string | null;
+    is_vision?: boolean;
+    is_lora?: boolean;
+    is_gguf?: boolean;
+    is_audio?: boolean;
+    audio_type?: string | null;
+    has_audio_input?: boolean;
+  },
+): void {
+  const store = useChatRuntimeStore.getState();
+  const models = store.models;
+  const synced = {
+    isVision: Boolean(resp.is_vision),
+    isGguf: Boolean(resp.is_gguf),
+    isAudio: Boolean(resp.is_audio),
+    audioType: resp.audio_type ?? null,
+    hasAudioInput: Boolean(resp.has_audio_input),
+  };
+  const idx = models.findIndex((m) => m.id === modelId);
+  if (idx === -1) {
+    store.setModels([
+      ...models,
+      {
+        id: modelId,
+        name: resp.display_name || modelId,
+        isLora: Boolean(resp.is_lora),
+        ...synced,
+      },
+    ]);
+  } else {
+    const next = [...models];
+    next[idx] = { ...next[idx], ...synced };
+    store.setModels(next);
+  }
+}
+
 function toLoraSummary(lora: {
   display_name: string;
   adapter_path: string;
@@ -390,6 +434,9 @@ export function useChatModelRuntime() {
               loadedChatTemplateOverride: statusRes.chat_template_override,
             }),
         });
+        // setModels(listRes...) above used catalog data, which omits audio
+        // capability. Re-apply live status so attach gates survive a refresh.
+        syncModelCapabilities(statusRes.active_model, statusRes);
 
         // Set reasoning default for Qwen3.5/3.6 small models
         if (
@@ -736,6 +783,8 @@ export function useChatModelRuntime() {
               loadedIsMultimodal: isMultimodalResponse(loadResponse),
               activeNativePathToken: nativePathToken ?? null,
             });
+            // Unlock attach menus for capabilities the catalog entry lacked.
+            syncModelCapabilities(modelId, loadResponse);
             // Qwen3/3.5/3.6: apply thinking-mode-specific params after load
             if (
               modelId.toLowerCase().includes("qwen3") &&
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 8d9e5a10e3..359301e182 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -51,6 +51,7 @@ import {
   readActiveOpenDocumentAttachmentContent,
   readOpenDocumentAttachmentContent,
 } from "./open-document";
+import { AudioAttachmentAdapter } from "./audio-attachment-adapter";
 import { useChatRuntimeStore } from "./stores/chat-runtime-store";
 import type { MessageRecord, ModelType, ThreadRecord } from "./types";
 import {
@@ -983,6 +984,7 @@ function useStudioRuntimeAdapters(
     () =>
       new CompositeAttachmentAdapter([
         new VisionImageAdapter(),
+        new AudioAttachmentAdapter(),
         new TextAttachmentAdapter(),
         new HtmlAttachmentAdapter(),
         new PDFAttachmentAdapter(),

From cc1a724efcbd393a8b2c3f1e4ff361bcc3e8919b Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Wed, 10 Jun 2026 12:49:57 -0300
Subject: [PATCH 162/222] Source llama.cpp prebuilts from unslothai/llama.cpp
 (CUDA, ROCm, macOS) (#5963)

* Studio: route arm64 Linux CUDA hosts to linux-arm64-cuda prebuilts

* Studio: SM-aware selection for windows-cuda app bundles

* Studio: select published ROCm bundles by gfx target (linux + windows)

* Studio: route macOS installs to the fork's prebuilt bundles

* Studio: fix windows cuda13 driver-13.0 gate and ROCm gfx prefix overreach

* Fix Blackwell Windows pin shadowing native app-bundle (b9360 over b9457)

* Match Windows cuda12 driver floor to Linux (12.x minor-version compat)

* Fix Windows app-bundle dropped when runtime DLLs come from torch/lib

* Fold the manifest resolver into the simple-path resolver (one entry, no dormant full path)

* Remove unused UNSLOTH_LLAMA_PUBLISHED_REPO override

* Route Windows GPU hosts to the fork prebuilts in setup.ps1

* Document sm_103 path divergence and mark --simple-policy as a no-op

* Note sm_103 coverage now comes from the producer manifest

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Remove the now-vestigial --simple-policy flag (one resolver handles all hosts)

* Unify the fork onto the manifest path; drop the linux-x64 filename path and hardcoded coverage tables

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Strip whitespace from manifest gfx_target/mapped_targets when parsing

* Windows CUDA: sort coverage-unknown bundles last so they can't outrank targeted ones

* Share the SM-coverage sort key between the linux and windows selectors via _sm_range

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: reject approved releases with an exact source archive but no source repo to clone from

* Studio: accept the fork's windows-rocm kind in the Windows reinstall check

* Studio: accept a manifest-bundle source repo in the exact-source release check

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: route Linux hosts to the fork only when a usable GPU is present

* Fix Windows AMD lemonade tag resolution for PR #5963

The fork release scan passes each scanned release's upstream tag
(b9518, ...) to the lemonade lookup, but lemonade publishes its own tag
series (b1292, ...) that never contains upstream tag numbers. On a
Windows AMD host every scanned release therefore 404s the lemonade
fetch twice, the upstream HIP zip is dropped by the approved-hash gate,
and the scan walks the whole release history until it dies on the
unauthenticated GitHub rate limit or falls to a HIP source build. The
Linux path already passes the requested tag ("latest") and works.

Thread the requested tag through resolve_release_asset_choice ->
resolve_asset_choice -> resolve_upstream_asset_choice as lemonade_tag,
used only by the lemonade lookups. Upstream asset names keep the
concrete per-release tag and all new parameters default to the old
behavior.

Verified on a gfx1151 box: before, the native Windows install scanned
b9518..b8811 and aborted on rate limit; after, it selects
llama-b1292-windows-rocm-gfx1151-x64.zip (lemonade) from fork release
b9518, passes staged validation, and the installed llama-server
enumerates ROCm0. WSL keeps selecting the matching ubuntu bundle.
Adds a regression test pinning that the Windows fork path resolves
lemonade via /releases/latest, never /releases/tags/<fork-tag>.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Plan lemonade for Linux ROCm hosts on the ggml-org direct path for PR #5963

Audit follow-up to 72f32364 across the other selection pathways. The
ggml-org direct planner kept its lemonade attempt for Windows ROCm
hosts but planned only the CPU tarball for Linux ROCm hosts, so an AMD
Linux box routed to ggml-org (for example a --published-repo override)
silently installed the CPU build. That lemonade planning used to live
in the --simple-policy dispatcher this PR removed.

Add the lemonade attempt ahead of the CPU tarball in the Linux x86_64
branch, mirroring the Windows branch, with the lookup keyed to the
requested tag. Adds a regression test asserting lemonade is the first
attempt for a Linux ROCm host on the direct path.

Also re-verified the other pathways on a gfx1151 box: the fork-routed
flows pass the requested tag everywhere, repeat runs over an existing
lemonade install correctly skip with "already matches selected release
b9518" on both native Windows and WSL, and macOS, CUDA and CPU
selection are untouched. Suites: 328 passed on Linux, Windows matches
the pre-existing baseline.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 .../test_lemonade_llamacpp_rocm_bins_mock.py  | 229 ++--
 studio/install_llama_prebuilt.py              | 990 ++++++++++--------
 studio/setup.ps1                              |  28 +-
 studio/setup.sh                               |  50 +-
 .../test_install_llama_prebuilt_logic.py      | 342 +-----
 .../install/test_llama_pr_force_and_source.py |   7 +-
 tests/studio/install/test_pr4562_bugfixes.py  |  24 +-
 tests/studio/install/test_selection_logic.py  | 695 ++++++++----
 8 files changed, 1308 insertions(+), 1057 deletions(-)

diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
index 3443f53a12..57bbc84fb0 100644
--- a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -1,10 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-"""Validates that the installer resolves lemonade ROCm prebuilt assets.
+"""Validates that the installer correctly resolves lemonade ROCm prebuilt assets.
 
-Uses a faked HostInfo so no AMD GPU is needed. The lemonade GitHub API calls
-are stubbed so the suite runs offline and isn't subject to rate limits.
+Uses a faked HostInfo so no AMD GPU is needed. Network calls to the lemonade
+GitHub API are stubbed out so the suite runs without internet access and is
+not subject to rate limits.
 """
 
 from __future__ import annotations
@@ -32,7 +33,7 @@ if resolve_lemonade_rocm_choice is None or _LEMONADE_GFX_FAMILIES is None:
 @pytest.fixture(autouse = True)
 def _clear_lemonade_release_cache():
     """Prevent cross-test pollution of the lemonade release lru_cache when
-    tests vary the fetch_json mock return value."""
+    future tests vary the fetch_json mock return value."""
     _cache = getattr(_mod, "_fetch_lemonade_release_cached", None)
     if _cache is not None and hasattr(_cache, "cache_clear"):
         _cache.cache_clear()
@@ -89,7 +90,9 @@ def _lookup_family(gfx: str) -> str | None:
     return None
 
 
+# ---------------------------------------------------------------------------
 # GPU family mapping
+# ---------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -111,7 +114,9 @@ def test_unknown_gpu_not_in_families():
     assert _lookup_family("gfx999") is None
 
 
+# ---------------------------------------------------------------------------
 # Asset resolution - hits real lemonade GitHub API
+# ---------------------------------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -141,59 +146,71 @@ def test_unknown_gpu_falls_through_to_upstream():
     assert result is None
 
 
-# Simple-policy dispatcher must plan a lemonade ROCm attempt for AMD-only hosts.
-# This is the path setup.sh invokes (via --simple-policy), so the lemonade
-# integration is useless if it isn't wired in here.
+# ---------------------------------------------------------------------------
+# The Linux attempt builder must plan a lemonade ROCm attempt for AMD-only hosts.
+# This is the path setup.sh actually invokes (fork hosts now select from the
+# manifest), so the lemonade integration is useless if it isn't wired in here.
+# ---------------------------------------------------------------------------
 
-direct_linux_release_plan = getattr(_mod, "direct_linux_release_plan", None)
+_linux_published_attempts = getattr(_mod, "_linux_published_attempts", None)
 direct_upstream_release_plan = getattr(_mod, "direct_upstream_release_plan", None)
 
+PublishedLlamaArtifact = _mod.PublishedLlamaArtifact
+PublishedReleaseBundle = _mod.PublishedReleaseBundle
 
-def _stub_unsloth_release(release_tag: str = "b9022") -> dict:
-    # Minimal payload parse_direct_linux_release_bundle accepts. It needs at
-    # least one `app-{label}-linux-x64*.tar.gz` asset to recognise the bundle;
-    # we ship a bare CPU one so the planner has a baseline non-ROCm fallback.
-    asset_name = f"app-{release_tag}-linux-x64.tar.gz"
-    return {
-        "tag_name": release_tag,
-        "name": release_tag,
-        "assets": [
-            {
-                "name": asset_name,
-                "browser_download_url": f"https://example.invalid/{asset_name}",
-            },
-        ],
-    }
+
+def _rocm_bundle(gfx_family: str, mapped_targets: list[str]) -> "PublishedReleaseBundle":
+    """A fork manifest bundle exposing a per-gfx linux-rocm artifact, so
+    published_rocm_choice_for_host can match the host before the lemonade
+    fallback is appended."""
+    asset_name = f"app-b9457-linux-x64-rocm-{gfx_family}.tar.gz"
+    artifact = PublishedLlamaArtifact(
+        asset_name = asset_name,
+        install_kind = "linux-rocm",
+        runtime_line = None,
+        coverage_class = None,
+        supported_sms = [],
+        min_sm = None,
+        max_sm = None,
+        bundle_profile = None,
+        rank = 1000,
+        gfx_target = gfx_family,
+        mapped_targets = mapped_targets,
+    )
+    return PublishedReleaseBundle(
+        repo = "unslothai/llama.cpp",
+        release_tag = "v1.0",
+        upstream_tag = "b9457",
+        assets = {asset_name: f"https://example.invalid/{asset_name}"},
+        artifacts = [artifact],
+    )
 
 
 @pytest.mark.skipif(
-    direct_linux_release_plan is None,
-    reason = "simple-policy dispatcher not present on this branch",
+    _linux_published_attempts is None,
+    reason = "Linux attempt builder not present on this branch",
 )
-def test_simple_policy_plans_lemonade_for_rocm_host():
+def test_linux_attempts_include_fork_rocm_and_lemonade_for_rocm_host():
     host = _make_rocm_host("gfx1151")
+    bundle = _rocm_bundle("gfx1151", ["gfx1151"])
     with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
-        plan = direct_linux_release_plan(
-            _stub_unsloth_release(),
-            host,
-            "unslothai/llama.cpp",
-            "latest",
-        )
-    assert plan is not None, "ROCm host should not be skipped by simple-policy planner"
-    kinds = [a.install_kind for a in plan.attempts]
-    assert (
-        "linux-rocm" in kinds
-    ), f"simple-policy planner did not include a lemonade ROCm attempt; got {kinds}"
-    rocm_attempt = next(a for a in plan.attempts if a.install_kind == "linux-rocm")
-    assert rocm_attempt.source_label == "lemonade"
-    assert "gfx1151" in rocm_attempt.name
+        attempts = _linux_published_attempts(host, bundle, "latest")
+    kinds = [a.install_kind for a in attempts]
+    assert "linux-rocm" in kinds, f"builder did not include any linux-rocm attempt; got {kinds}"
+    sources = {a.source_label for a in attempts if a.install_kind == "linux-rocm"}
+    # The fork's own per-gfx bundle is preferred, with the lemonade prebuilt as
+    # the fallback -- both must be present for a covered ROCm host.
+    assert "published" in sources, f"fork ROCm bundle missing; got {sources}"
+    assert "lemonade" in sources, f"lemonade ROCm fallback missing; got {sources}"
+    lemonade_attempt = next(a for a in attempts if a.source_label == "lemonade")
+    assert "gfx1151" in lemonade_attempt.name
 
 
 @pytest.mark.skipif(
     direct_upstream_release_plan is None,
-    reason = "simple-policy dispatcher not present on this branch",
+    reason = "direct release planners not present on this branch",
 )
-def test_simple_policy_plans_lemonade_for_windows_hip_host():
+def test_direct_upstream_plan_includes_lemonade_for_windows_hip_host():
     host = _make_rocm_host("gfx1151", windows = True)
     release = {
         "tag_name": "b9022",
@@ -204,16 +221,14 @@ def test_simple_policy_plans_lemonade_for_windows_hip_host():
         plan = direct_upstream_release_plan(release, host, "ggml-org/llama.cpp", "latest")
     assert plan is not None, "Windows ROCm host should plan a lemonade HIP attempt"
     kinds = [a.install_kind for a in plan.attempts]
-    assert (
-        "windows-hip" in kinds
-    ), f"simple-policy planner did not include a lemonade HIP attempt; got {kinds}"
+    assert "windows-hip" in kinds, f"planner did not include a lemonade HIP attempt; got {kinds}"
 
 
 @pytest.mark.skipif(
     direct_upstream_release_plan is None,
-    reason = "simple-policy dispatcher not present on this branch",
+    reason = "direct release planners not present on this branch",
 )
-def test_simple_policy_windows_hip_falls_back_to_upstream_when_lemonade_unavailable():
+def test_windows_hip_falls_back_to_upstream_when_lemonade_unavailable():
     """If lemonade returns None (e.g. gfx999 or transient API failure), the planner
     must still include the upstream HIP asset rather than silently downgrading to CPU."""
     host = _make_rocm_host("gfx999", windows = True)
@@ -247,8 +262,9 @@ def test_lemonade_release_api_url_pinned_tag():
 
 
 def test_lemonade_release_api_url_encodes_tag():
-    """Slashes / hashes in the tag must be URL-encoded so the URL can't be
-    reshaped (defence in depth -- tags should already be sanitised upstream)."""
+    """Unexpected slashes / hashes in the tag must be URL-encoded so the URL
+    cannot be reshaped (defence in depth -- tags should already be sanitised
+    upstream)."""
     url = _mod._lemonade_release_api_for("b1260/../latest")
     assert "/releases/tags/b1260%2F..%2Flatest" in url
     assert "//latest" not in url.split("/releases/tags/", 1)[1]
@@ -263,9 +279,9 @@ def test_lemonade_resolver_skipped_by_opt_out_env(monkeypatch):
 
 
 def test_lemonade_resolver_rejects_non_github_url(monkeypatch):
-    """If the GitHub API response contained an off-host download URL, the
-    resolver must refuse it (lemonade assets aren't in the approved-hash
-    manifest)."""
+    """If the GitHub API response somehow contained an off-host download URL,
+    the resolver must refuse to use it (lemonade assets are not in the
+    approved-hash manifest)."""
     bad_release = {
         "tag_name": _STUB_TAG,
         "assets": [
@@ -289,7 +305,7 @@ def test_lemonade_resolver_rejects_http_scheme():
 
 
 def test_lemonade_resolver_accepts_github_cdn():
-    # Real GitHub release CDN URLs carry the /github-production-release-asset- prefix
+    # Real GitHub release CDN URLs carry the /github-production-release-asset- prefix.
     assert _mod._is_trusted_github_release_url(
         "https://objects.githubusercontent.com/github-production-release-asset-abc123/456/789?token=x",
         "lemonade-sdk/llamacpp-rocm",
@@ -297,7 +313,7 @@ def test_lemonade_resolver_accepts_github_cdn():
 
 
 def test_lemonade_resolver_rejects_arbitrary_cdn_path():
-    # A CDN URL without the release-asset path prefix must be rejected
+    # A CDN URL without the release-asset path prefix must be rejected.
     assert not _mod._is_trusted_github_release_url(
         "https://objects.githubusercontent.com/abc/def",
         "lemonade-sdk/llamacpp-rocm",
@@ -339,7 +355,7 @@ def test_lemonade_runtime_patterns_include_hip_runtime():
 
     Lemonade ZIPs carry transitive deps (libamd_comgr, libLLVM, libclang-cpp,
     ...) whose names change across ROCm releases. A broad ``lib*.so*`` glob
-    avoids enumerating every transitive dependency by name.
+    avoids having to enumerate every transitive dependency by name.
     """
     from install_llama_prebuilt import runtime_patterns_for_choice, AssetChoice
 
@@ -353,7 +369,7 @@ def test_lemonade_runtime_patterns_include_hip_runtime():
     )
     pats = runtime_patterns_for_choice(choice)
     # The broad glob must be present so every .so in the lemonade bundle
-    # (including future transitive deps) gets overlaid.
+    # (including transitive deps added in future ROCm releases) gets overlaid.
     assert "lib*.so*" in pats, f"'lib*.so*' missing from linux-rocm patterns: {pats}"
 
 
@@ -365,9 +381,9 @@ _pick_rocm_gfx_target = getattr(_mod, "_pick_rocm_gfx_target", None)
     reason = "_pick_rocm_gfx_target not present on this branch",
 )
 def test_pick_rocm_gfx_target_honors_cuda_visible_devices(monkeypatch):
-    """AMD HIP honours CUDA_VISIBLE_DEVICES like HIP_VISIBLE_DEVICES; on a
-    gfx1151 + gfx1100 mixed host, CUDA_VISIBLE_DEVICES=1 must select gfx1100."""
-    # Two GPUs; rocminfo reports each token twice (as in real tool output).
+    """AMD HIP honours CUDA_VISIBLE_DEVICES identically to HIP_VISIBLE_DEVICES;
+    on a gfx1151 + gfx1100 mixed host, CUDA_VISIBLE_DEVICES=1 must select gfx1100."""
+    # Two GPUs; rocminfo reports each token twice (as in the real tool output).
     probe_out = "gfx1151\ngfx1151\ngfx1100\ngfx1100"
     monkeypatch.delenv("HIP_VISIBLE_DEVICES", raising = False)
     monkeypatch.delenv("ROCR_VISIBLE_DEVICES", raising = False)
@@ -396,7 +412,7 @@ def test_pick_rocm_gfx_target_same_arch_multi_gpu(monkeypatch):
     """Regression: [gfx1100, gfx1100, gfx1151] with HIP_VISIBLE_DEVICES=2 must
     return gfx1151, not fall back to GPU 0 due to dict.fromkeys collapsing the
     two gfx1100 entries into one and making index 2 out of range."""
-    # rocminfo output for 3 GPUs (2x gfx1100 dGPU + 1x gfx1151 APU).
+    # Simulate rocminfo output for 3 GPUs (2x gfx1100 dGPU + 1x gfx1151 APU).
     # Each GPU gets its own Agent section with a few token mentions.
     probe_out = (
         "***\nAgent 1\n***\n  gfx1100 some info\n  gfx1100\n"
@@ -407,3 +423,96 @@ def test_pick_rocm_gfx_target_same_arch_multi_gpu(monkeypatch):
     monkeypatch.delenv("CUDA_VISIBLE_DEVICES", raising = False)
     monkeypatch.setenv("HIP_VISIBLE_DEVICES", "2")
     assert _pick_rocm_gfx_target(probe_out) == "gfx1151"
+
+
+# ---------------------------------------------------------------------------
+# Fork release scan: Windows ROCm resolves lemonade by the requested tag
+# ---------------------------------------------------------------------------
+
+_resolve_release_asset_choice = getattr(_mod, "resolve_release_asset_choice", None)
+_ApprovedReleaseChecksums = getattr(_mod, "ApprovedReleaseChecksums", None)
+
+
+@pytest.mark.skipif(
+    _resolve_release_asset_choice is None or _ApprovedReleaseChecksums is None,
+    reason = "fork release planner not present on this branch",
+)
+def test_fork_scan_windows_rocm_resolves_lemonade_by_requested_tag():
+    """The fork release scan pins llama_tag to per-release upstream tags
+    (b9457, ...) that lemonade's own tag series never contains, so the
+    lemonade lookup must use the requested tag ("latest") instead. Pinning
+    lemonade to the per-release tag 404s on every scanned release and a
+    Windows ROCm host ends in a rate-limited fatal instead of the lemonade
+    prebuilt."""
+    host = _make_rocm_host("gfx1151", windows = True)
+    # No windows-rocm artifact in the bundle, matching current fork releases.
+    bundle = _rocm_bundle("gfx1151", ["gfx1151"])
+    checksums = _ApprovedReleaseChecksums(
+        repo = "unslothai/llama.cpp",
+        release_tag = "v1.0",
+        upstream_tag = "b9457",
+        artifacts = {},
+    )
+    seen_urls: list[str] = []
+
+    def _fake_fetch(api_url, *args, **kwargs):
+        seen_urls.append(api_url)
+        if "lemonade-sdk" in api_url:
+            if api_url.endswith("/releases/latest"):
+                return _stub_lemonade_release()
+            raise RuntimeError(f"unexpected pinned lemonade fetch: {api_url}")
+        # ggml-org asset listing for the upstream HIP/CPU filename fallbacks.
+        return {"tag_name": "b9457", "assets": []}
+
+    with patch.object(_mod, "fetch_json", side_effect = _fake_fetch):
+        attempts = _resolve_release_asset_choice(
+            host,
+            "b9457",  # concrete per-release upstream tag from the scan loop
+            bundle,
+            checksums,
+            requested_tag = "latest",
+        )
+
+    lemonade = [a for a in attempts if a.source_label == "lemonade"]
+    assert lemonade, f"lemonade attempt missing for Windows ROCm host; got {attempts}"
+    assert "gfx1151" in lemonade[0].name
+    assert any(
+        u.endswith("/releases/latest") for u in seen_urls
+    ), f"lemonade was never resolved via /releases/latest; fetches: {seen_urls}"
+    assert not any(
+        "lemonade-sdk" in u and "/releases/tags/" in u for u in seen_urls
+    ), f"lemonade lookup was pinned to the fork release tag: {seen_urls}"
+
+
+@pytest.mark.skipif(
+    direct_upstream_release_plan is None,
+    reason = "direct release planners not present on this branch",
+)
+def test_direct_upstream_plan_includes_lemonade_for_linux_rocm_host():
+    """A Linux ROCm host on the ggml-org direct path (e.g. a --published-repo
+    override) must plan lemonade before the CPU tarball, mirroring the Windows
+    branch. The lemonade planning previously lived in the removed
+    --simple-policy dispatcher, so without this leg such hosts silently
+    install the CPU build."""
+    host = _make_rocm_host("gfx1151")
+    release = {
+        "tag_name": "b9022",
+        "name": "b9022",
+        "assets": [
+            {
+                "name": "llama-b9022-bin-ubuntu-x64.tar.gz",
+                "browser_download_url": (
+                    "https://github.com/ggml-org/llama.cpp/releases/download/"
+                    "b9022/llama-b9022-bin-ubuntu-x64.tar.gz"
+                ),
+            }
+        ],
+    }
+    with patch.object(_mod, "fetch_json", return_value = _stub_lemonade_release()):
+        plan = direct_upstream_release_plan(release, host, "ggml-org/llama.cpp", "latest")
+    assert plan is not None, "Linux ROCm host should produce a direct plan"
+    kinds = [a.install_kind for a in plan.attempts]
+    sources = [a.source_label for a in plan.attempts]
+    assert "linux-rocm" in kinds, f"lemonade ROCm attempt missing; got {kinds}"
+    assert sources[0] == "lemonade", f"lemonade must be the first attempt; got {sources}"
+    assert "gfx1151" in plan.attempts[0].name
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index bc4fe555c1..822a32ddb8 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -121,9 +121,9 @@ def env_int(
     return value
 
 
-# Prefer "latest" over "master": "master" bypasses the prebuilt resolver
+# Prefer "latest" over "master" -- "master" bypasses the prebuilt resolver
 # (no matching GitHub release), forces a source build, and causes HTTP 422
-# errors. Use "master" only temporarily when the latest release lacks
+# errors. Only use "master" temporarily when the latest release is missing
 # support for a new model architecture.
 DEFAULT_LLAMA_TAG = os.environ.get("UNSLOTH_LLAMA_TAG", "latest")
 # Default published repo for prebuilt release resolution. Linux uses
@@ -145,13 +145,21 @@ LEMONADE_ROCM_RELEASES_API = f"https://api.github.com/repos/{LEMONADE_ROCM_REPO}
 
 
 def _lemonade_release_api_for(llama_tag: str) -> str:
-    """GitHub API URL for the lemonade release matching a llama.cpp tag.
+    """Return the GitHub API URL for the lemonade release that matches a
+    requested llama.cpp tag.
 
-    "latest"/unset -> /releases/latest; a pinned tag -> the same lemonade tag.
-    Lemonade tracks ggml-org build tags but may lag, so a tag it skipped 404s
-    and the caller falls back to the upstream tarball (keeps pinned installs
-    reproducible). Do NOT pass a fork tag -- the fork namespace always 404s.
-    Tag is URL-encoded (safe="") to prevent URL injection.
+    When llama_tag is unset or "latest", point at /releases/latest. When the
+    caller has pinned a specific tag (e.g. "b1260"), point at the same tag in
+    lemonade. Lemonade tracks `ggml-org/llama.cpp` build tags (e.g. "b1260")
+    but is NOT guaranteed to publish every upstream build -- lemonade may be
+    several builds behind ggml-org. Pinning to a specific tag that lemonade
+    skipped will produce a 404 and the caller falls through to the upstream
+    tarball; that is intentional so pinned installs stay reproducible.
+    Do NOT pass a `unslothai/llama.cpp` fork tag -- the fork uses its own
+    namespace and will always 404 against lemonade.
+
+    The tag is URL-encoded with `safe=""` so an unexpected slash / hash / query
+    character cannot reshape the URL.
     """
     normalized = (llama_tag or "").strip()
     if not normalized or normalized.lower() == "latest":
@@ -186,90 +194,35 @@ DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS = env_int(
     2,
     minimum = 1,
 )
-# Deeper macOS-only walk-back: upstream can ship a run of prebuilts built for
-# a newer macOS than the host, caught only at validate time, so an older host
-# must skip the whole run. Free on new hosts (first plan validates).
+# Deeper macOS-only walk-back: upstream can ship a run of prebuilts built for a
+# newer macOS than the host, only caught at validate time, so an older host must
+# skip the whole run. Free on new hosts (first plan validates, extras unused).
 DEFAULT_MAX_MACOS_RELEASE_FALLBACKS = env_int(
     "UNSLOTH_LLAMA_MAX_MACOS_RELEASE_FALLBACKS",
     16,
     minimum = 1,
 )
 # Deterministic macOS pin. At b9428 ggml-org's macOS runner moved to macOS 26
-# (Tahoe), so b9428+ prebuilts load only on macOS 26+. b9415 is the last build
-# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on 13.3/14/15/26.
+# (Tahoe), so b9428+ prebuilts only load on macOS 26+. b9415 is the last build
+# stamped below 26 (arm64 minos 14, x64 minos 13.3); loads on macOS 13.3/14/15/26.
 _PINNED_MACOS_FALLBACK_TAG = "b9415"
 _PINNED_MACOS_LATEST_FLOOR = (26, 0)
 FORCE_COMPILE_DEFAULT_REF = os.environ.get("UNSLOTH_LLAMA_FORCE_COMPILE_REF", "master")
 
-# sm_103 (B300 / GB300 Blackwell Ultra) is not built natively but runs on the
-# bundled base compute_100 PTX, which the driver JIT-compiles forward to sm_103.
-# Listed in every bundle that ships the sm_100 build (the "newer" and
-# "portable" classes) so those hosts get a prebuilt, not a source compile.
-DIRECT_LINUX_BUNDLE_PROFILES: dict[str, dict[str, Any]] = {
-    "cuda12-older": {
-        "runtime_line": "cuda12",
-        "coverage_class": "older",
-        "supported_sms": ["70", "75", "80", "86", "89"],
-        "min_sm": 70,
-        "max_sm": 89,
-        "rank": 10,
-    },
-    "cuda12-newer": {
-        "runtime_line": "cuda12",
-        "coverage_class": "newer",
-        "supported_sms": ["86", "89", "90", "100", "103", "120"],
-        "min_sm": 86,
-        "max_sm": 120,
-        "rank": 20,
-    },
-    "cuda12-portable": {
-        "runtime_line": "cuda12",
-        "coverage_class": "portable",
-        "supported_sms": ["70", "75", "80", "86", "89", "90", "100", "103", "120"],
-        "min_sm": 70,
-        "max_sm": 120,
-        "rank": 30,
-    },
-    "cuda13-older": {
-        "runtime_line": "cuda13",
-        "coverage_class": "older",
-        "supported_sms": ["75", "80", "86", "89"],
-        "min_sm": 75,
-        "max_sm": 89,
-        "rank": 40,
-    },
-    "cuda13-newer": {
-        "runtime_line": "cuda13",
-        "coverage_class": "newer",
-        "supported_sms": ["86", "89", "90", "100", "103", "120"],
-        "min_sm": 86,
-        "max_sm": 120,
-        "rank": 50,
-    },
-    "cuda13-portable": {
-        "runtime_line": "cuda13",
-        "coverage_class": "portable",
-        "supported_sms": ["75", "80", "86", "89", "90", "100", "103", "120"],
-        "min_sm": 75,
-        "max_sm": 120,
-        "rank": 60,
-    },
-}
-
 # Lowest CUDA major we ship prebuilts for, and the highest major we probe for
 # installed runtime libraries. Detection and runtime-line derivation are
-# generated per major so a new toolkit (cuda14, ...) needs no code change as
-# long as llama.cpp keeps the cudart64_<major>.dll / libcudart.so.<major> naming.
+# generated per major so a new toolkit (cuda14, ...) needs no code change while
+# llama.cpp keeps the cudart64_<major>.dll / libcudart.so.<major> naming.
 _MIN_CUDA_MAJOR = 12
 _MAX_PROBE_CUDA_MAJOR = 19
 
 # Last ggml-org release whose Windows win-cuda-13 build is still sub-13.3
 # (cuda-13.1, b9360, 2026-05-27). Upstream bumped win-cuda-13 to 13.3 at b9365
 # and now ships only cuda-12.4 + cuda-13.3. cuda-12.4 predates Blackwell (ggml
-# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a
-# 13.0/13.1/13.2 driver is gated off 13.3 and would drop to CPU-only 12.4.
-# b9360 is immutable, so we pin its cuda-13.1 build (plus paired cudart) as a
-# GPU fallback for exactly those hosts. See unslothai/unsloth#5887.
+# compiles sm_120 only at toolkit >= 12.8), so a Blackwell host on a 13.0/13.1/13.2
+# driver is gated off 13.3 and would drop to a CPU-only 12.4 build. b9360 is
+# immutable, so we pin its cuda-13.1 build (plus paired cudart) as a GPU
+# fallback for exactly those hosts. See unslothai/unsloth#5887.
 _PINNED_BLACKWELL_FALLBACK_TAG = "b9360"
 _PINNED_BLACKWELL_FALLBACK_RUNTIME = "13.1"
 # Floor at 13.0: b9360 ships native sm_120a SASS (no PTX/JIT) and a bundled
@@ -279,46 +232,19 @@ _PINNED_BLACKWELL_DRIVER_FLOOR = (13, 0)
 _BLACKWELL_MIN_SM = 120
 # ggml compiles Blackwell sm_120 only at toolkit >= 12.8, so an in-release
 # windows-cuda build at or above this already covers Blackwell and makes the
-# pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
+# older pinned 13.1 fallback unnecessary (cuda-12.4 is below it).
 _BLACKWELL_MIN_TOOLKIT = (12, 8)
 _PINNED_BLACKWELL_LLAMA_SHA256 = "31ddb8b42d7ab4a47cab8c48c397519f580ca502df7e73f3ab396eacc16c8e8d"
 _PINNED_BLACKWELL_CUDART_SHA256 = "f96935e7e385e3b2d0189239077c10fe8fd7e95690fea4afec455b1b6c7e3f18"
 
 
 def _cuda_runtime_lines_for_major(major: int) -> list[str]:
-    """Runtime lines a driver of this CUDA major can use, newest first down to
-    the minimum we ship. A driver runs its own major and any older one
+    """Runtime lines a driver of this CUDA major can use, newest major first
+    down to the minimum we ship. A driver runs its own major and any older one
     (backward compatibility)."""
     return [f"cuda{m}" for m in range(major, _MIN_CUDA_MAJOR - 1, -1)]
 
 
-def _resolve_linux_bundle_profile(bundle_profile: str) -> "dict[str, Any] | None":
-    """Profile (runtime line + sm coverage) for a linux-x64-cuda<major>-<class>
-    bundle. Known majors use their published coverage; an unknown future major
-    reuses the newest known major's coverage for the same class as a forward
-    default, with the post-build GPU smoke test as backstop."""
-    known = DIRECT_LINUX_BUNDLE_PROFILES.get(bundle_profile)
-    if known is not None:
-        return known
-    m = re.fullmatch(r"cuda(?P<major>\d+)-(?P<klass>older|newer|portable)", bundle_profile)
-    if not m:
-        return None
-    base_key = max(
-        (
-            k
-            for k, v in DIRECT_LINUX_BUNDLE_PROFILES.items()
-            if v["coverage_class"] == m.group("klass")
-        ),
-        key = lambda k: int(re.match(r"cuda(\d+)-", k).group(1)),
-        default = None,
-    )
-    if base_key is None:
-        return None
-    profile = dict(DIRECT_LINUX_BUNDLE_PROFILES[base_key])
-    profile["runtime_line"] = f"cuda{m.group('major')}"
-    return profile
-
-
 @dataclass
 class HostInfo:
     system: str
@@ -349,8 +275,8 @@ class AssetChoice:
     url: str
     source_label: str
     # Paired runtime archive (Windows CUDA cudart bundle). When set,
-    # install_from_archives also downloads it and overlays its DLLs on top
-    # of the main install. See unslothai/unsloth#5106.
+    # install_from_archives also downloads it and overlays its DLLs on
+    # top of the main install. See unslothai/unsloth#5106.
     runtime_name: str | None = None
     runtime_url: str | None = None
     runtime_sha256: str | None = None
@@ -377,6 +303,10 @@ class PublishedLlamaArtifact:
     max_sm: int | None
     bundle_profile: str | None
     rank: int
+    # ROCm bundles only: the umbrella gfx target (e.g. "gfx110X") and the
+    # concrete gfx archs it covers (e.g. ["gfx1100", "gfx1101", ...]).
+    gfx_target: str | None = None
+    mapped_targets: list[str] = field(default_factory = list)
 
 
 @dataclass
@@ -577,13 +507,14 @@ def is_github_api_url(url: str | None) -> bool:
 
 def is_retryable_url_error(exc: Exception) -> bool:
     if isinstance(exc, urllib.error.HTTPError):
-        # GitHub returns 403 (not 429) when the API rate limit is hit.
-        # Anonymous calls share a 60-req/hour bucket per runner IP, which
-        # CI fleets exhaust trivially. Treat 403 against api.github.com as
-        # retryable so we get a backoff cycle or two before the source-build
-        # fallback fires; sleep_backoff honours Retry-After /
-        # X-RateLimit-Reset for accurate waits. Real 403s on other hosts
-        # (private artefact downloads, auth failures) stay non-retryable.
+        # GitHub returns 403 (not the standard 429) when the API rate
+        # limit is hit. Anonymous calls share a 60-req/hour bucket per
+        # runner IP, which CI fleets can exhaust trivially. Treat 403
+        # against api.github.com as retryable so we get one or two
+        # backoff cycles before the source-build fallback fires; honour
+        # Retry-After / X-RateLimit-Reset in sleep_backoff for accurate
+        # waits. Real 403s on other hosts (private artefact downloads,
+        # auth failures) stay non-retryable.
         if exc.code == 403:
             return is_github_api_url(getattr(exc, "url", None))
         return exc.code in RETRYABLE_HTTP_STATUS
@@ -602,9 +533,9 @@ _RATE_LIMIT_WAIT_CAP_SECONDS = 60.0
 def _http_error_retry_delay(exc: Exception) -> float | None:
     """Extract a recommended wait from rate-limit headers on a 403/429.
 
-    Returns None when no header is present or the wait exceeds
-    _RATE_LIMIT_WAIT_CAP_SECONDS (the caller should not block then -- the
-    source-build fallback is faster).
+    Returns None when no header is present or the indicated wait is
+    longer than _RATE_LIMIT_WAIT_CAP_SECONDS (in which case the caller
+    should not block on it -- the source-build fallback is faster).
     """
     if not isinstance(exc, urllib.error.HTTPError):
         return None
@@ -813,12 +744,12 @@ def refs_match(candidate_ref: str | None, requested_ref: str | None) -> bool:
 
 
 def checkout_friendly_ref(ref_kind: str | None, ref: str | None) -> str | None:
-    """Normalize a source ref to a form ``git clone --branch`` accepts.
+    """Normalize a source ref to a form that ``git clone --branch`` accepts.
 
-    Fully qualified branch refs (``refs/heads/main``) are stripped to
-    ``main``; tag refs (``refs/tags/b8508``) to ``b8508``. Pull refs
-    (``refs/pull/123/head``) are left as-is since they are fetched
-    explicitly rather than cloned with ``--branch``.
+    Fully qualified branch refs like ``refs/heads/main`` are stripped to
+    ``main``; tag refs like ``refs/tags/b8508`` are stripped to ``b8508``.
+    Pull refs like ``refs/pull/123/head`` are left as-is since they are
+    always fetched explicitly rather than cloned with ``--branch``.
     """
     if not isinstance(ref, str) or not ref:
         return ref
@@ -868,8 +799,8 @@ def _published_windows_cuda_runtime(
     """Highest cuda-<major>.<minor> published upstream that `driver` can run by
     default CUDA compatibility, i.e. (major, minor) <= driver. None if nothing
     qualifies. Gating on the driver (not just the major) keeps a 13.3 build off
-    a 13.1-only driver, where it would rely on the unguaranteed
-    minor-version-compatibility path."""
+    a driver that only advertises 13.1, where it would otherwise rely on the
+    unguaranteed minor-version-compatibility path."""
     if driver is None:
         return None
     best: int | None = None
@@ -1484,7 +1415,7 @@ def direct_upstream_release_plan(
             )
             attempts[:] = _drop_blackwell_incapable_windows_cuda(host, attempts)
             # Blackwell on a 13.1/13.2 driver: prefer the pinned cuda-13.1 GPU
-            # build over the CPU-only cuda-12.4 left by in-release gating.
+            # build over the CPU-only cuda-12.4 the in-release gating leaves.
             pinned = _pinned_windows_cuda_fallback(host, attempts)
             if pinned is not None:
                 attempts.insert(0, pinned)
@@ -1522,9 +1453,9 @@ def direct_upstream_release_plan(
             )
     elif host.is_windows and host.is_arm64:
         # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-win-cpu-arm64.zip
-        # (in the b9334 release manifest). Without this branch the selector
-        # returned 0 attempts and fell back to a source build on every
-        # Windows ARM64 host.
+        # (visible in the b9334 release manifest). Without this branch the
+        # selector returned 0 attempts and the installer fell back to a
+        # source build on every Windows ARM64 host.
         cpu_asset = f"llama-{release_tag}-bin-win-cpu-arm64.zip"
         cpu_url = assets.get(cpu_asset)
         if cpu_url:
@@ -1567,6 +1498,14 @@ def direct_upstream_release_plan(
                 )
             )
     elif host.is_linux and host.is_x86_64 and not host.has_usable_nvidia:
+        if host.has_rocm:
+            # Lemonade first, mirroring the Windows ROCm branch above, so a
+            # ROCm host routed to ggml-org does not silently get the CPU build.
+            lemonade_choice = resolve_lemonade_rocm_choice(
+                host, "ubuntu", "linux-rocm", llama_tag = requested_tag
+            )
+            if lemonade_choice is not None:
+                attempts.append(lemonade_choice)
         asset_name = f"llama-{release_tag}-bin-ubuntu-x64.tar.gz"
         asset_url = assets.get(asset_name)
         if asset_url:
@@ -1582,10 +1521,10 @@ def direct_upstream_release_plan(
             )
     elif host.is_linux and host.is_arm64 and not host.has_usable_nvidia:
         # Upstream ggml-org/llama.cpp ships llama-bNNNN-bin-ubuntu-arm64.tar.gz
-        # (in the b9334 release manifest). Without this branch the selector
-        # returned 0 attempts and fell back to a source build on every Linux
-        # ARM64 host (DGX Spark, Ampere Altra, GitHub ubuntu-24.04-arm
-        # runners, etc.).
+        # (visible in the b9334 release manifest). Without this branch the
+        # selector returned 0 attempts and the installer fell back to a
+        # source build on every Linux ARM64 host (DGX Spark, Ampere
+        # Altra, GitHub-hosted ubuntu-24.04-arm runners, etc.).
         asset_name = f"llama-{release_tag}-bin-ubuntu-arm64.tar.gz"
         asset_url = assets.get(asset_name)
         if asset_url:
@@ -1615,9 +1554,9 @@ def direct_upstream_release_plan(
 
 
 def pinned_macos_release_tag(host: HostInfo, repo: str) -> str | None:
-    """Pin b9415 (last upstream macOS build that loads below macOS 26) for a
-    known pre-26 host on ggml-org upstream; None keeps latest selection. The
-    unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64
+    """Pin b9415 (the last upstream macOS build that loads below macOS 26) for a
+    known pre-26 host on ggml-org upstream; return None to keep latest selection.
+    The unslothai/llama.cpp fork ships its own prebuilts (arm64 minos 14, x64
     minos 13.3) and needs no pin, so this is a no-op there and for macOS 26+,
     unknown version, non-macOS."""
     if repo != UPSTREAM_REPO:
@@ -1641,20 +1580,22 @@ def resolve_simple_install_release_plans(
     max_release_fallbacks: int = DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS,
 ) -> tuple[str, list[InstallReleasePlan]]:
     repo = published_repo or DEFAULT_PUBLISHED_REPO
-    requested_tag = normalized_requested_llama_tag(llama_tag)
-    # The unslothai/llama.cpp fork ships only linux-x64 bundles. An arm64 Linux
-    # host with a GPU (GH200/GB200/DGX Spark) routes here; it must not install
-    # an x64 binary, so fall back to a GPU-targeting source build rather than
-    # the wrong arch (or silently dropping to a CPU arm64 build).
-    if host.is_linux and not host.is_x86_64 and repo == DEFAULT_PUBLISHED_REPO:
-        raise PrebuiltFallback(
-            f"{repo} ships only linux-x64 prebuilts; "
-            f"{host.machine or 'non-x64'} Linux falls back to source build"
+    # The fork (unslothai) ships a manifest describing every bundle's GPU/arch
+    # coverage, so all fork hosts select from it. Upstream (ggml-org) ships no
+    # manifest and is selected by asset filename in the loop below.
+    if repo == DEFAULT_PUBLISHED_REPO:
+        return _fork_manifest_release_plans(
+            llama_tag,
+            host,
+            published_repo,
+            published_release_tag,
+            max_release_fallbacks = max_release_fallbacks,
         )
+    requested_tag = normalized_requested_llama_tag(llama_tag)
     allow_older_release_fallback = requested_tag == "latest" and not published_release_tag
     # macOS: pin the last upstream build that loads on a pre-26 host instead of
     # fetching the latest (macOS 26 only) build and walking back release by
-    # release. No-op on macOS 26+, unknown version, non-macOS, the fork.
+    # release. No-op on macOS 26+, unknown version, non-macOS, and the fork.
     if allow_older_release_fallback:
         pinned_macos = pinned_macos_release_tag(host, repo)
         if pinned_macos is not None:
@@ -1668,10 +1609,7 @@ def resolve_simple_install_release_plans(
         releases = iter_release_payloads_by_time(repo, published_release_tag, requested_tag)
         for release in releases:
             try:
-                if host.is_linux and repo == "unslothai/llama.cpp":
-                    plan = direct_linux_release_plan(release, host, repo, requested_tag)
-                else:
-                    plan = direct_upstream_release_plan(release, host, repo, requested_tag)
+                plan = direct_upstream_release_plan(release, host, repo, requested_tag)
                 if plan is None:
                     continue
             except PrebuiltFallback as exc:
@@ -1940,6 +1878,18 @@ def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
         rank = int(rank_raw)
     except (TypeError, ValueError):
         raise ValueError(f"artifact {asset_name} rank was not an integer")
+    gfx_target_raw = raw.get("gfx_target")
+    gfx_target = (
+        gfx_target_raw.strip()
+        if isinstance(gfx_target_raw, str) and gfx_target_raw.strip()
+        else None
+    )
+    mapped_raw = raw.get("mapped_targets", [])
+    mapped_targets = (
+        [value.strip() for value in mapped_raw if isinstance(value, str) and value.strip()]
+        if isinstance(mapped_raw, (list, tuple))
+        else []
+    )
     return PublishedLlamaArtifact(
         asset_name = asset_name,
         install_kind = install_kind,
@@ -1954,6 +1904,8 @@ def parse_published_artifact(raw: Any) -> PublishedLlamaArtifact | None:
         if isinstance(bundle_profile, str) and bundle_profile
         else None,
         rank = rank,
+        gfx_target = gfx_target,
+        mapped_targets = mapped_targets,
     )
 
 
@@ -1969,8 +1921,8 @@ def parse_published_release_bundle(
     if not manifest_url:
         return None
 
-    # Mixed repos are filtered by an explicit release-side manifest, not by
-    # release tag or asset filename conventions.
+    # Mixed repos are filtered by an explicit release-side manifest rather than
+    # by release tag or asset filename conventions.
     manifest_bytes = download_bytes(
         manifest_url,
         timeout = 30,
@@ -2190,6 +2142,25 @@ def iter_published_release_bundles(
         yield bundle
 
 
+def _artifact_covers_sms(artifact: PublishedLlamaArtifact, host_sms: Iterable[str]) -> bool:
+    """True when every host SM is listed in the artifact's supported_sms and
+    falls within its [min_sm, max_sm] range."""
+    if not artifact.supported_sms or artifact.min_sm is None or artifact.max_sm is None:
+        return False
+    supported = {str(value) for value in artifact.supported_sms}
+    return all(sm in supported and artifact.min_sm <= int(sm) <= artifact.max_sm for sm in host_sms)
+
+
+def _sm_range(artifact: PublishedLlamaArtifact) -> int:
+    """SM-coverage span used as a sort key, where a tighter (smaller) range wins.
+    A bundle with no SM metadata (legacy/upstream-named) gets a max range so it
+    sorts last and can't outrank a real targeted bundle whose tight range would
+    otherwise sort first."""
+    if artifact.min_sm is not None and artifact.max_sm is not None:
+        return artifact.max_sm - artifact.min_sm
+    return 9999
+
+
 def linux_cuda_choice_from_release(
     host: HostInfo,
     release: PublishedReleaseBundle,
@@ -2229,8 +2200,12 @@ def linux_cuda_choice_from_release(
                 else "none"
             )
         )
+    # arm64 CUDA hosts (DGX Spark / Grace Hopper) consume linux-arm64-cuda
+    # bundles; x64 hosts consume linux-cuda. The SM / runtime-line matching
+    # below is arch-agnostic and applies to both.
+    cuda_install_kind = "linux-arm64-cuda" if host.is_arm64 else "linux-cuda"
     published_artifacts = [
-        artifact for artifact in release.artifacts if artifact.install_kind == "linux-cuda"
+        artifact for artifact in release.artifacts if artifact.install_kind == cuda_install_kind
     ]
     published_asset_names = sorted(artifact.asset_name for artifact in published_artifacts)
     selection_log.append(
@@ -2281,7 +2256,7 @@ def linux_cuda_choice_from_release(
                 url = asset_url,
                 source_label = "published",
                 is_ready_bundle = True,
-                install_kind = "linux-cuda",
+                install_kind = cuda_install_kind,
                 bundle_profile = artifact.bundle_profile,
                 runtime_line = artifact.runtime_line,
                 coverage_class = artifact.coverage_class,
@@ -2363,7 +2338,7 @@ def linux_cuda_choice_from_release(
             artifact, url = sorted(
                 coverage_candidates,
                 key = lambda item: (
-                    (item[0].max_sm or 0) - (item[0].min_sm or 0),
+                    _sm_range(item[0]),
                     item[0].rank,
                     item[0].max_sm or 0,
                 ),
@@ -2422,11 +2397,20 @@ def validated_checksums_for_bundle(
             raise PrebuiltFallback(
                 "published manifest checksum did not match the approved checksum asset"
             )
-    # Accept bundles carrying only an exact-commit source archive
-    # (llama.cpp-source-commit-<sha>.tar.gz) without requiring the legacy
-    # llama.cpp-source-<upstream_tag>.tar.gz entry.
+    # Accept bundles that carry only an exact-commit source archive
+    # (e.g. llama.cpp-source-commit-<sha>.tar.gz) without requiring the
+    # legacy llama.cpp-source-<upstream_tag>.tar.gz entry.
     if exact_source_archive_hash(checksums) is None:
         require_approved_source_hash(checksums, bundle.upstream_tag)
+    elif source_clone_url_for_release(checksums, bundle) is None:
+        # No source repo in either the checksum payload or the manifest bundle:
+        # preferred_source_archive would silently fall back to ggml-org source at
+        # the upstream tag, pairing the prebuilt with a possibly mismatched tree.
+        # Fail closed so the resolver skips this release.
+        raise PrebuiltFallback(
+            f"approved checksum asset for {repo}@{bundle.release_tag} declared an "
+            "exact source archive without a source repo to clone it from"
+        )
     return checksums
 
 
@@ -2560,22 +2544,23 @@ def resolve_requested_llama_tag(
 
     Resolution order:
       1. Concrete tag (e.g. "b8508") -- returned as-is.
-      2. "latest" with published_repo -- the latest usable Unsloth published
-         bundle's upstream_tag (matches the published prebuilt metadata).
-      3. "latest" without published_repo, or if (2) fails -- query upstream
-         ggml-org/llama.cpp. May return a newer, untested tag.
+      2. "latest" with published_repo -- resolve the latest usable Unsloth
+         published release bundle and return its upstream_tag. This is the
+         preferred version that matches the published prebuilt metadata.
+      3. "latest" without published_repo or if (2) fails -- query the upstream
+         ggml-org/llama.cpp repo. This may return a newer, untested tag.
 
-    The Unsloth repo is preferred because its releases are pinned to upstream
-    tags validated with Unsloth Studio; the upstream bleeding-edge tag risks
-    API/ABI incompatibilities.
+    The Unsloth repo is preferred because its releases are pinned to specific
+    upstream tags that have been validated with Unsloth Studio. Using the
+    upstream bleeding-edge tag risks API/ABI incompatibilities.
     """
     normalized_requested = normalized_requested_llama_tag(requested_tag)
     if normalized_requested != "latest":
         return normalized_requested
     # Prefer the Unsloth release repo tag (tested/approved) over bleeding-edge
-    # upstream. E.g. unslothai/llama.cpp may publish b8508 while ggml-org
-    # latest is b8514. The source-build fallback should compile the same
-    # version the prebuilt path would have installed.
+    # upstream. For example, unslothai/llama.cpp may publish b8508 while
+    # ggml-org/llama.cpp latest is b8514. The source-build fallback should
+    # compile the same version the prebuilt path would have installed.
     if published_repo:
         try:
             return resolve_published_release(
@@ -2585,7 +2570,7 @@ def resolve_requested_llama_tag(
             ).bundle.upstream_tag
         except Exception:
             pass
-    # Fall back to the upstream ggml-org latest release tag
+    # Fall back to upstream ggml-org latest release tag
     return latest_upstream_release_tag()
 
 
@@ -2607,8 +2592,16 @@ def exact_source_archive_hash(checksums: ApprovedReleaseChecksums) -> ApprovedAr
     return checksums.artifacts.get(exact_source_archive_logical_name(checksums.source_commit))
 
 
-def source_clone_url_from_checksums(checksums: ApprovedReleaseChecksums) -> str | None:
-    return source_repo_clone_url(checksums.source_repo, checksums.source_repo_url)
+def source_clone_url_for_release(
+    checksums: ApprovedReleaseChecksums, bundle: PublishedReleaseBundle
+) -> str | None:
+    # Single source of truth for "where do we clone source from", shared by the
+    # validation gate and source_build_plan_for_release: take the repo from the
+    # checksum payload, falling back field by field to the manifest bundle.
+    return source_repo_clone_url(
+        checksums.source_repo or bundle.source_repo,
+        checksums.source_repo_url or bundle.source_repo_url,
+    )
 
 
 def source_build_plan_for_release(release: ResolvedPublishedRelease) -> SourceBuildPlan:
@@ -2620,7 +2613,7 @@ def source_build_plan_for_release(release: ResolvedPublishedRelease) -> SourceBu
     resolved_source_ref = checksums.resolved_source_ref or release.bundle.resolved_source_ref
     source_commit = checksums.source_commit or release.bundle.source_commit
     source_ref_kind = checksums.source_ref_kind or release.bundle.source_ref_kind
-    source_url = source_repo_clone_url(source_repo, source_repo_url)
+    source_url = source_clone_url_for_release(checksums, release.bundle)
     if exact_source is not None and source_url and source_commit:
         return SourceBuildPlan(
             source_url = source_url,
@@ -2741,38 +2734,38 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
     A bare first-match picked the wrong device on mixed APU + dGPU hosts
     (e.g. Strix Halo gfx1151 + discrete RX 7900 gfx1100). Respect
     HIP_VISIBLE_DEVICES / ROCR_VISIBLE_DEVICES / CUDA_VISIBLE_DEVICES so the
-    asset matches what HIP runs on; falls back to the first GPU with no env
-    var set.
+    asset matches what HIP actually runs on. Falls back to the first GPU when
+    no env var is set.
 
     rocminfo / hipinfo print the same gfx token multiple times per GPU (Name,
-    ISA, marketing-name). We first split the output on per-GPU section headers
-    (rocminfo: "Agent N" blocks, hipinfo: "device#N" entries) and take exactly
-    one gfx token per section -- this gives the correct per-GPU list even on
-    same-arch multi-GPU hosts (e.g. two RX 7900 XTX) where global dict.fromkeys
-    dedup would collapse both to one entry and make HIP_VISIBLE_DEVICES=1 point
-    out of range.
+    ISA, marketing-name). We first try to split the output on per-GPU section
+    headers (rocminfo: "Agent N" blocks, hipinfo: "device#N" entries) and take
+    exactly one gfx token per section. This gives the correct per-GPU list even
+    on same-arch multi-GPU hosts (e.g. two RX 7900 XTX cards) where global
+    dict.fromkeys dedup would collapse both cards to a single entry and make
+    HIP_VISIBLE_DEVICES=1 point out of range.
 
     Falls back to insertion-order dedup when the output has no recognisable
     section markers (flat gfx-string inputs, unit-test stubs, etc.).
 
     Empty / "-1" env values mean no AMD GPU is visible to HIP: return None.
     """
-    # Build a per-GPU token list by splitting on section boundaries. rocminfo
-    # sections start with "Agent N" lines (optionally between rows of
-    # asterisks); hipinfo sections with "device#N".
+    # Try to build a per-GPU token list by splitting on section boundaries.
+    # rocminfo sections are introduced by "Agent N" lines (optionally between
+    # rows of asterisks). hipinfo sections start with "device#N".
     _sections = re.split(
         r"(?mi)^\s*\*+\s*$\s*agent\s+\d+\s*$|\bdevice\s*#\s*\d+\b",
         out,
     )
     if len(_sections) > 1:
-        # One gfx token per GPU section preserves physical order.
+        # Section-based: one gfx token per GPU section preserves physical order.
         _tokens: list[str] = []
         for _sec in _sections[1:]:
             _m = re.search(r"gfx[1-9][0-9a-z]{2,3}", _sec.lower())
             if _m:
                 _tokens.append(_m.group(0))
     else:
-        # Fallback: insertion-order dedup (flat strings / unknown formats).
+        # Fallback: insertion-order dedup (handles flat strings / unknown formats).
         _raw = re.findall(r"gfx[1-9][0-9a-z]{2,3}", out.lower())
         _tokens = list(dict.fromkeys(_raw))
 
@@ -2788,7 +2781,7 @@ def _pick_rocm_gfx_target(out: str) -> str | None:
             break
     if _vis_raw is not None:
         _vis = _vis_raw.strip()
-        # Empty or "-1" means "no AMD GPU visible" (matches the rest of Studio)
+        # Empty or "-1" means "no AMD GPU visible" (matches the rest of Studio).
         if _vis == "" or _vis == "-1":
             return None
         _first = _vis.split(",")[0].strip()
@@ -2820,10 +2813,11 @@ def detect_host() -> HostInfo:
     has_physical_nvidia = False
     has_usable_nvidia = False
     if nvidia_smi:
-        # Require `nvidia-smi -L` to list a GPU before treating the host as
-        # NVIDIA. The "NVIDIA-SMI ..." banner prints even when the command
-        # can't reach the driver (e.g. stale container leftovers), which
-        # would misclassify an AMD ROCm host as NVIDIA and skip the ROCm path.
+        # Require `nvidia-smi -L` to actually list a GPU before treating the
+        # host as NVIDIA. The banner text "NVIDIA-SMI ..." is printed even
+        # when the command fails to communicate with the driver (e.g. stale
+        # container leftovers), which would otherwise misclassify an AMD
+        # ROCm host as NVIDIA and short-circuit the ROCm path.
         try:
             listing = run_capture([nvidia_smi, "-L"], timeout = 20)
             gpu_lines = [line for line in listing.stdout.splitlines() if line.startswith("GPU ")]
@@ -2836,9 +2830,9 @@ def detect_host() -> HostInfo:
         try:
             result = run_capture([nvidia_smi], timeout = 20)
             merged = "\n".join(part for part in (result.stdout, result.stderr) if part)
-            # Newer NVIDIA drivers (e.g. 610.x on Windows) print "CUDA UMD
-            # Version: X.Y" instead of the legacy "CUDA Version: X.Y"; accept
-            # both spellings.
+            # Newer NVIDIA drivers (e.g. 610.x on Windows) print
+            # "CUDA UMD Version: X.Y" instead of the legacy
+            # "CUDA Version: X.Y"; accept both spellings.
             cuda_match = re.search(
                 r"CUDA(?: UMD)? Version:\s*(\d+)\.(\d+)",
                 merged,
@@ -2881,10 +2875,10 @@ def detect_host() -> HostInfo:
 
             if visible_gpu_rows:
                 has_usable_nvidia = True
-                # Older nvidia-smi (pre -L support) hits the except in the
-                # first try block but still succeeds here, leaving
-                # has_physical_nvidia unset. Mirror the -L path so downstream
-                # diagnostics on line ~4390 still run.
+                # Older nvidia-smi versions (pre -L support) hit the
+                # except in the first try block but still succeed here,
+                # leaving has_physical_nvidia unset. Mirror the -L path
+                # so downstream diagnostics on line ~4390 still run.
                 if not has_physical_nvidia:
                     has_physical_nvidia = True
             elif visible_device_tokens == []:
@@ -2913,10 +2907,10 @@ def detect_host() -> HostInfo:
         _dxg_probe_env = {**os.environ}
         _dxg_probe_env.setdefault("HSA_ENABLE_DXG_DETECTION", "1")
         for _cmd, _check in (
-            # rocminfo: a real gfx GPU id (3-4 chars, nonzero first digit).
-            # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines
-            # ("gfx11-generic", "gfx9-4-generic") with only 1-2 digits before
-            # the dash, which must not be treated as a real GPU.
+            # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
+            # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines like
+            # "gfx11-generic" or "gfx9-4-generic" which only have 1-2 digits before
+            # the dash and must not be treated as a real GPU.
             (
                 ["rocminfo"],
                 lambda out: bool(re.search(r"gfx[1-9][0-9a-z]{2,3}", out.lower())),
@@ -2944,13 +2938,14 @@ def detect_host() -> HostInfo:
                     rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
     elif is_windows:
-        # Windows: prefer active probes that validate GPU presence. hipinfo /
-        # amd-smi are often NOT on PATH -- the HIP SDK installer sets HIP_PATH
-        # / ROCM_PATH but doesn't always add the bin dir to PATH. Mirror
-        # setup.ps1's fallback: check the env-var bin dirs before giving up so
-        # `has_rocm` isn't silently False when PATH isn't updated yet.
+        # Windows: prefer active probes that validate GPU presence.
+        # hipinfo / amd-smi are often NOT on PATH -- the HIP SDK installer
+        # sets HIP_PATH / ROCM_PATH but does not always add the bin dir to
+        # the system PATH.  Mirror setup.ps1's fallback: check the env-var
+        # bin dirs before giving up so that `has_rocm` is not silently False
+        # on machines where the PATH is not yet updated.
         def _resolve_exe(name: str) -> str | None:
-            """Full path to `name`, checking PATH then HIP_PATH/ROCM_PATH bin."""
+            """Return full path to `name`, checking PATH then HIP_PATH/ROCM_PATH bin."""
             found = shutil.which(name)
             if found:
                 return found
@@ -2987,8 +2982,8 @@ def detect_host() -> HostInfo:
                     # hipinfo reports "gcnArchName: gfx1100" -- extract if present
                     rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
-        # Note: amdhip64.dll presence alone is NOT GPU evidence -- the HIP SDK
-        # can be installed without an AMD GPU.
+        # Note: amdhip64.dll presence alone is NOT treated as GPU evidence
+        # since the HIP SDK can be installed without an AMD GPU.
 
     return HostInfo(
         system = system,
@@ -3013,7 +3008,7 @@ def detect_host() -> HostInfo:
 def _normalize_forwarded_gfx(value: str | None) -> str | None:
     """Extract a single gfx token from a forwarded --rocm-gfx / env value.
     setup.sh/setup.ps1 already picked the active GPU, so take the token as-is
-    without re-applying visible-device selection. Ignore malformed input."""
+    without re-applying visible-device selection. Ignore anything malformed."""
     if not value:
         return None
     m = re.search(r"gfx[1-9][0-9a-z]{2,3}", value.lower())
@@ -3029,8 +3024,8 @@ def _apply_host_overrides(
 ) -> HostInfo:
     """Fold setup.sh/setup.ps1's forwarded detection into the host profile.
     A forwarded gfx (--rocm-gfx or UNSLOTH_ROCM_GFX_ARCH) is authoritative and
-    implies ROCm: the installer's own hipinfo/amd-smi probe can miss the arch
-    on amd-smi-only hosts or when setup inferred it from the GPU name, leaving
+    implies ROCm: the installer's own hipinfo/amd-smi probe can miss the arch on
+    amd-smi-only hosts or when setup inferred it from the GPU name, leaving
     rocm_gfx_target None and no lemonade prebuilt selected. force_cpu is the
     opposite explicit signal (arm64 Linux GPU host whose source build failed):
     drop GPU attributes so the CPU prebuilt for this OS/arch is selected."""
@@ -3072,7 +3067,7 @@ def compatible_linux_runtime_lines(host: HostInfo) -> list[str]:
 
 def windows_runtime_line_info() -> dict[str, tuple[str, ...]]:
     # Generated per CUDA major (newest first) so a new toolkit is detected
-    # without code changes while the cudart64_<major>.dll naming holds.
+    # without a code change while the cudart64_<major>.dll naming holds.
     return {
         f"cuda{m}": (
             f"cudart64_{m}*.dll",
@@ -3098,9 +3093,10 @@ def detected_windows_runtime_lines() -> tuple[list[str], dict[str, list[str]]]:
 def compatible_windows_runtime_lines(host: HostInfo) -> list[str]:
     if not host.driver_cuda_version:
         return []
-    major, minor = host.driver_cuda_version
-    # cuda12 prebuilts need a 12.4+ driver; cuda13+ any minor.
-    if major < _MIN_CUDA_MAJOR or (major == _MIN_CUDA_MAJOR and minor < 4):
+    major, _minor = host.driver_cuda_version
+    # cuda12 app bundles are toolkit-12.8 builds with bundled runtime libs; CUDA
+    # minor-version compatibility runs them on any 12.x driver, same as Linux.
+    if major < _MIN_CUDA_MAJOR:
         return []
     return _cuda_runtime_lines_for_major(major)
 
@@ -3239,8 +3235,8 @@ def windows_cuda_attempts(
     runtime_order.extend(
         runtime_line for runtime_line in normal_runtime_lines if runtime_line not in runtime_order
     )
-    # Keep every driver-compatible line reachable as a fallback, so a line
-    # gated out by driver version still drops to an older major (cuda13->cuda12).
+    # Keep every driver-compatible line reachable as a fallback, so a line gated
+    # out by the driver version still drops to an older major (cuda13 -> cuda12).
     runtime_order.extend(
         runtime_line
         for runtime_line in compatible_runtime_lines
@@ -3259,7 +3255,7 @@ def windows_cuda_attempts(
     for runtime_line in runtime_order:
         major = int(runtime_line.removeprefix("cuda"))
         # Track whatever minor llama.cpp actually ships for this major
-        # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release lacks a
+        # (cuda13 -> 13.1, 13.3, ...). Skip the line when the release has no
         # matching asset instead of guessing a now-missing name.
         runtime = _published_windows_cuda_runtime(upstream_assets, major, host.driver_cuda_version)
         if runtime is None:
@@ -3280,10 +3276,10 @@ def windows_cuda_attempts(
                 + ",".join(windows_cuda_upstream_asset_names(llama_tag, runtime))
             )
             continue
-        # Pair the cudart bundle when upstream ships it; otherwise the binary
-        # needs a system CUDA toolkit on PATH at runtime (#5106). Only pair
-        # when the selected main archive is the binary archive, not the cudart
-        # archive itself.
+        # Pair the cudart bundle when upstream ships it. Without this
+        # the binary needs a system CUDA toolkit on PATH at runtime
+        # (#5106). Only pair when the selected main archive is the
+        # binary archive, not the cudart archive itself.
         runtime_archive_name: str | None = None
         runtime_archive_url: str | None = None
         if selected_name.startswith("llama-"):
@@ -3322,23 +3318,19 @@ def windows_cuda_attempts(
 
 
 def _windows_cuda_attempt_covers_blackwell(attempt: AssetChoice) -> bool:
-    """True if an in-release windows-cuda attempt covers Blackwell sm_120.
-
-    Manifest-backed app bundles carry their compiled SM list, so trust that
-    first (the published cuda12 bundles are toolkit-12.8 builds that include
-    sm_120 even though their runtime line says cuda12). Upstream ggml-org
-    zips have no manifest metadata; infer from the CUDA minor in the asset
-    name (sm_120 needs toolkit >= 12.8)."""
+    """True if an in-release windows-cuda attempt yields a Blackwell sm_120
+    capable build. The fork's app-named bundles declare their SM coverage
+    directly; legacy upstream-named bundles instead encode their CUDA toolkit
+    minor in the filename (covers Blackwell at toolkit >= 12.8)."""
     if attempt.install_kind != "windows-cuda":
         return False
-    if attempt.max_sm is not None:
-        return attempt.max_sm >= _BLACKWELL_MIN_SM
-    if attempt.supported_sms:
-        sms = normalize_compute_caps(attempt.supported_sms)
-        if sms:
-            return int(sms[-1]) >= _BLACKWELL_MIN_SM
+    # Legacy upstream-named bundles encode their toolkit minor; it is the binding
+    # constraint (a 12.4 toolkit cannot offload sm_120 whatever its metadata says).
     m = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", attempt.name)
-    return m is not None and (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
+    if m is not None:
+        return (int(m.group(1)), int(m.group(2))) >= _BLACKWELL_MIN_TOOLKIT
+    # App-named bundles carry no minor and declare their SM coverage directly.
+    return attempt.max_sm is not None and attempt.max_sm >= _BLACKWELL_MIN_SM
 
 
 def _host_is_blackwell(host: HostInfo) -> bool:
@@ -3369,16 +3361,16 @@ def _pinned_windows_cuda_fallback(
     host: HostInfo, existing_cuda_attempts: list[AssetChoice]
 ) -> AssetChoice | None:
     """Pinned GPU fallback for a Blackwell host the in-release build gates off.
-    Upstream stopped publishing a sub-13.3 Windows cuda13 build after b9360,
-    and cuda-12.4 cannot offload sm_120, so a 13.1/13.2 driver would land on
-    CPU. b9360's cuda-13.1 build is immutable and runs on those drivers.
-    Returns None (dormant) whenever the in-release selection already offers a
-    Blackwell-capable build (toolkit >= 12.8, e.g. a runnable cuda13/cuda14),
-    so it self-disables once upstream ships a driver-runnable build again.
+    Upstream stopped publishing a sub-13.3 Windows cuda13 build after b9360, and
+    cuda-12.4 cannot offload sm_120, so a 13.1/13.2 driver would land on CPU.
+    b9360's cuda-13.1 build is immutable and runs on those drivers. Returns None
+    (dormant) whenever the in-release selection already offers a Blackwell-capable
+    build (toolkit >= 12.8, e.g. a runnable cuda13/cuda14), so it self-disables
+    once upstream ships a driver-runnable build again.
 
-    The b9360 binary reuses the current release's source tree and convert
-    scripts and is recorded via binary_release_tag, the same binary/source
-    split used for the lemonade prebuilt."""
+    The b9360 binary reuses the current release's source tree and convert scripts
+    and is recorded via binary_release_tag, the same binary/source split used for
+    the lemonade prebuilt."""
     if not (host.is_windows and host.is_x86_64 and host.has_usable_nvidia):
         return None
     driver = host.driver_cuda_version
@@ -3420,8 +3412,8 @@ def _pinned_windows_cuda_fallback(
 def _augment_checksums_with_pin(
     checksums: ApprovedReleaseChecksums, pin: AssetChoice
 ) -> ApprovedReleaseChecksums:
-    """Add the pin's verified hashes to a copy of the approved checksums so
-    apply_approved_hashes keeps it on the published path (b9360 isn't in the
+    """Add the pin's own verified hashes to a copy of the approved checksums so
+    apply_approved_hashes keeps it on the published path (b9360 is not in the
     release manifest)."""
     artifacts = dict(checksums.artifacts)
     if pin.expected_sha256:
@@ -3445,7 +3437,7 @@ def _with_pinned_windows_cuda_fallback(
     host: HostInfo, attempts: list[AssetChoice], checksums: ApprovedReleaseChecksums
 ) -> tuple[list[AssetChoice], ApprovedReleaseChecksums]:
     """Insert the Blackwell pin ahead of the Windows CUDA attempts and keep it
-    through apply_approved_hashes, or return inputs unchanged when dormant.
+    through apply_approved_hashes, or return the inputs unchanged when dormant.
     Gives the published install path the same GPU fallback as the simple path."""
     attempts = _drop_blackwell_incapable_windows_cuda(host, attempts)
     pin = _pinned_windows_cuda_fallback(host, attempts)
@@ -3461,30 +3453,6 @@ def published_windows_cuda_attempts(
     selection_preamble: Iterable[str] = (),
 ) -> list[AssetChoice]:
     selection_log = list(release.selection_log) + list(selection_preamble)
-    # Seed the runtime-line ordering from the real published windows-cuda minors
-    # (their names encode the minor), so a future CUDA major published here is
-    # ordered too rather than a hardcoded cuda12/cuda13 pair. Keys mirror the
-    # upstream naming so windows_cuda_attempts can match them; fall back to the
-    # long-standing default when the release lists no windows-cuda asset.
-    published_minors: list[str] = []
-    for artifact in release.artifacts:
-        if artifact.install_kind != "windows-cuda":
-            continue
-        m = re.search(r"-bin-win-cuda-(\d+\.\d+)-x64\.zip$", artifact.asset_name)
-        if m:
-            published_minors.append(m.group(1))
-    if not published_minors:
-        published_minors = ["12.4", "13.1"]
-    runtime_order = windows_cuda_attempts(
-        host,
-        release.upstream_tag,
-        {
-            f"llama-{release.upstream_tag}-bin-win-cuda-{minor}-x64.zip": "published"
-            for minor in published_minors
-        },
-        preferred_runtime_line,
-        selection_log,
-    )
     published_artifacts = [
         artifact for artifact in release.artifacts if artifact.install_kind == "windows-cuda"
     ]
@@ -3494,61 +3462,147 @@ def published_windows_cuda_attempts(
             continue
         artifacts_by_runtime.setdefault(artifact.runtime_line, []).append(artifact)
 
+    # Order the runtime lines to try. Legacy upstream-named bundles encode a CUDA
+    # minor in the filename and are driver-gated per minor. The fork's app-named
+    # bundles carry no minor: their runtime line (cuda12/cuda13) is gated at the
+    # CUDA *major* level (a 13.0 driver runs any cuda13 build) and by what torch
+    # actually provides on the host, preferring the torch line. Routing them
+    # through the synthetic-minor path wrongly dropped cuda13 on a 13.0 driver.
+    legacy_minors: list[str] = []
+    for artifact in published_artifacts:
+        m = re.search(r"-bin-win-cuda-(\d+\.\d+)-x64\.zip$", artifact.asset_name)
+        if m:
+            legacy_minors.append(m.group(1))
+    if legacy_minors:
+        ordered_lines = [
+            attempt.runtime_line
+            for attempt in windows_cuda_attempts(
+                host,
+                release.upstream_tag,
+                {
+                    f"llama-{release.upstream_tag}-bin-win-cuda-{minor}-x64.zip": "published"
+                    for minor in legacy_minors
+                },
+                preferred_runtime_line,
+                selection_log,
+            )
+            if attempt.runtime_line
+        ]
+    else:
+        detected, _ = detected_windows_runtime_lines()
+        compatible = compatible_windows_runtime_lines(host)
+        # Prefer lines whose runtime DLLs are on disk, but fall back to the
+        # driver-derived order when none are detected (Windows torch bundles
+        # cudart in torch/lib, which probing misses) or when detected DLLs are
+        # incompatible with the driver. The app bundle ships its own runtime, so
+        # the driver major is the real constraint. Mirrors the legacy
+        # windows_cuda_attempts fallback; without it a torch-only host gets no
+        # fork attempt and silently drops to the upstream build.
+        ordered_lines = [line for line in compatible if line in detected] or list(compatible)
+        if preferred_runtime_line and preferred_runtime_line in ordered_lines:
+            ordered_lines = [preferred_runtime_line] + [
+                line for line in ordered_lines if line != preferred_runtime_line
+            ]
+        selection_log.append(
+            "windows_cuda_selection: app-bundle runtime lines (major-gated)="
+            + (",".join(ordered_lines) if ordered_lines else "none")
+        )
+
+    host_sms = normalize_compute_caps(host.compute_caps)
     attempts: list[AssetChoice] = []
-    for ordered_attempt in runtime_order:
-        runtime_line = ordered_attempt.runtime_line
+    for runtime_line in ordered_lines:
         if not runtime_line:
             continue
-        candidates = sorted(
-            artifacts_by_runtime.get(runtime_line, []),
-            key = lambda artifact: (artifact.rank, artifact.asset_name),
-        )
-        for artifact in candidates:
+        # Pick the artifact whose SM coverage fits the host, preferring the
+        # tightest targeted bundle and falling back to portable -- the same
+        # policy as linux_cuda_choice_from_release. Without this, app-named
+        # bundles (no minor in the filename) skip the SM filter and the
+        # lowest-rank "older" bundle is chosen for every host, breaking newer
+        # GPUs (e.g. Blackwell sm120 on a cuda12-older bundle capped at sm89).
+        targeted: list[tuple[PublishedLlamaArtifact, str, re.Match[str] | None]] = []
+        portable: tuple[PublishedLlamaArtifact, str, re.Match[str] | None] | None = None
+        for artifact in artifacts_by_runtime.get(runtime_line, []):
             asset_url = release.assets.get(artifact.asset_name)
             if not asset_url:
                 continue
             am = re.search(r"-bin-win-cuda-(\d+)\.(\d+)-x64\.zip$", artifact.asset_name)
-            # Gate the published minor against the driver so it can never
-            # bypass the driver-version gate.
+            # Legacy upstream-named bundles encode the minor; gate it against the
+            # driver. app-named bundles carry no minor and are driver-gated at the
+            # runtime-line level by windows_cuda_attempts above.
             if (
                 am is not None
                 and host.driver_cuda_version is not None
                 and (int(am.group(1)), int(am.group(2))) > host.driver_cuda_version
             ):
                 continue
-            # See windows_cuda_attempts: pair the cudart bundle for the real minor.
-            runtime_archive_name: str | None = None
-            runtime_archive_url: str | None = None
-            if am is not None and artifact.asset_name.startswith("llama-"):
-                runtime = f"{am.group(1)}.{am.group(2)}"
-                cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
-                cudart_url = release.assets.get(cudart_name)
-                if cudart_url and cudart_url != asset_url:
-                    runtime_archive_name = cudart_name
-                    runtime_archive_url = cudart_url
-            attempt_log = list(ordered_attempt.selection_log or []) + [
-                "windows_cuda_selection: selected published asset "
-                f"{artifact.asset_name} for runtime_line={runtime_line}"
-            ]
-            if runtime_archive_name:
-                attempt_log.append(
-                    f"windows_cuda_selection: paired published runtime archive {runtime_archive_name}"
-                )
-            attempts.append(
-                AssetChoice(
-                    repo = release.repo,
-                    tag = release.release_tag,
-                    name = artifact.asset_name,
-                    url = asset_url,
-                    source_label = "published",
-                    install_kind = "windows-cuda",
-                    runtime_line = runtime_line,
-                    runtime_name = runtime_archive_name,
-                    runtime_url = runtime_archive_url,
-                    selection_log = attempt_log,
-                )
+            # Only SM-filter artifacts that declare full SM metadata (the app
+            # bundles). Legacy/upstream-named artifacts without it keep the old
+            # rank-based selection rather than being dropped.
+            has_sm_info = (
+                bool(artifact.supported_sms)
+                and artifact.min_sm is not None
+                and artifact.max_sm is not None
             )
-            break
+            if host_sms and has_sm_info and not _artifact_covers_sms(artifact, host_sms):
+                continue
+            if not host_sms and has_sm_info and artifact.coverage_class != "portable":
+                continue
+            if artifact.coverage_class == "portable":
+                portable = (artifact, asset_url, am)
+            else:
+                targeted.append((artifact, asset_url, am))
+        chosen: tuple[PublishedLlamaArtifact, str, re.Match[str] | None] | None = None
+        if targeted:
+            chosen = sorted(
+                targeted,
+                key = lambda item: (
+                    _sm_range(item[0]),
+                    item[0].rank,
+                    item[0].max_sm or 0,
+                ),
+            )[0]
+        elif portable is not None:
+            chosen = portable
+        if chosen is None:
+            continue
+        artifact, asset_url, am = chosen
+        # See windows_cuda_attempts: pair the cudart bundle for the real minor.
+        runtime_archive_name: str | None = None
+        runtime_archive_url: str | None = None
+        if am is not None and artifact.asset_name.startswith("llama-"):
+            runtime = f"{am.group(1)}.{am.group(2)}"
+            cudart_name = f"cudart-llama-bin-win-cuda-{runtime}-x64.zip"
+            cudart_url = release.assets.get(cudart_name)
+            if cudart_url and cudart_url != asset_url:
+                runtime_archive_name = cudart_name
+                runtime_archive_url = cudart_url
+        attempt_log = list(selection_log) + [
+            "windows_cuda_selection: selected published asset "
+            f"{artifact.asset_name} for runtime_line={runtime_line}"
+        ]
+        if runtime_archive_name:
+            attempt_log.append(
+                f"windows_cuda_selection: paired published runtime archive {runtime_archive_name}"
+            )
+        attempts.append(
+            AssetChoice(
+                repo = release.repo,
+                tag = release.release_tag,
+                name = artifact.asset_name,
+                url = asset_url,
+                source_label = "published",
+                install_kind = "windows-cuda",
+                runtime_line = runtime_line,
+                runtime_name = runtime_archive_name,
+                runtime_url = runtime_archive_url,
+                bundle_profile = artifact.bundle_profile,
+                coverage_class = artifact.coverage_class,
+                supported_sms = artifact.supported_sms,
+                min_sm = artifact.min_sm,
+                max_sm = artifact.max_sm,
+                selection_log = attempt_log,
+            )
+        )
     return attempts
 
 
@@ -3610,9 +3664,9 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
     """Return (major, minor) of the installed ROCm runtime, or None.
 
     Best-effort read from /opt/rocm/.info/version, amd-smi version, and
-    hipconfig --version. Used to pick a compatible upstream llama.cpp ROCm
-    prebuilt rather than the numerically newest one (which can be newer than
-    the host runtime).
+    hipconfig --version. Used to pick a compatible upstream llama.cpp
+    ROCm prebuilt rather than always taking the numerically newest one
+    (which can be newer than the host runtime).
     """
     rocm_root = os.environ.get("ROCM_PATH") or "/opt/rocm"
     for path in (
@@ -3622,9 +3676,9 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
         try:
             with open(path) as fh:
                 parts = fh.read().strip().split("-")[0].split(".")
-            # Explicit length guard so we don't rely on the broad except
-            # below to swallow IndexError when the version file has a single
-            # component (e.g. "6\n" on a partial install).
+            # Explicit length guard avoids relying on the broad except
+            # below to swallow IndexError when the version file contains
+            # a single component (e.g. "6\n" on a partial install).
             if len(parts) >= 2:
                 return int(parts[0]), int(parts[1])
         except Exception:
@@ -3661,8 +3715,8 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
 
     # Distro package-manager fallbacks. Mirrors install.sh::get_torch_index_url
     # and _detect_rocm_version() in install_python_stack.py so package-managed
-    # ROCm hosts without /opt/rocm/.info/version still report a usable version,
-    # letting the <= host version filter in resolve_upstream_asset_choice pick
+    # ROCm hosts without /opt/rocm/.info/version still report a usable version
+    # and the <= host version filter in resolve_upstream_asset_choice picks
     # the correct upstream prebuilt instead of the newest-regardless fallback.
     for _cmd in (
         ["dpkg-query", "-W", "-f=${Version}\n", "rocm-core"],
@@ -3684,7 +3738,7 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
         if _result.returncode != 0 or not _result.stdout.strip():
             continue
         _raw = _result.stdout.strip()
-        # dpkg can prepend an epoch ("1:6.3.0-1"); strip it first.
+        # dpkg can prepend an epoch ("1:6.3.0-1"); strip it before parsing.
         _raw = re.sub(r"^\d+:", "", _raw)
         _m = re.match(r"(\d+)[.-](\d+)", _raw)
         if _m:
@@ -3693,7 +3747,7 @@ def _detect_host_rocm_version() -> tuple[int, int] | None:
 
 
 # Map detected gfx IDs to lemonade-sdk asset family suffixes.
-# More-specific prefixes must precede shorter ones (e.g. gfx1151 before gfx110).
+# More-specific prefixes must come before shorter ones (e.g. gfx1151 before gfx110).
 _LEMONADE_GFX_FAMILIES: list[tuple[str, str]] = [
     ("gfx1151", "gfx1151"),
     ("gfx1150", "gfx1150"),
@@ -3711,14 +3765,56 @@ def _lemonade_gfx_family(gfx_id: str) -> str | None:
     return None
 
 
+def published_rocm_choice_for_host(
+    release: PublishedReleaseBundle, host: HostInfo, install_kind: str
+) -> AssetChoice | None:
+    """Select the published ROCm bundle whose gfx target covers the host GPU.
+
+    The manifest's gfx_target uses the same umbrella family labels that
+    _lemonade_gfx_family produces (gfx110X, gfx120X, ...), so the host's detected
+    gfx is matched either to that family or to the bundle's concrete
+    mapped_targets list. Returns None when no published bundle covers the GPU, so
+    the caller can fall back (lemonade / upstream HIP)."""
+    if not host.rocm_gfx_target:
+        return None
+    gfx = host.rocm_gfx_target.lower().strip()
+    for artifact in release.artifacts:
+        if artifact.install_kind != install_kind:
+            continue
+        # Match on the concrete built-arch list, not the family prefix: an
+        # in-generation-but-unbuilt arch (e.g. gfx1033 in the gfx103 prefix) must
+        # NOT be served the family bundle. None makes the caller fall back to a
+        # source build for that GPU.
+        if gfx not in {target.lower() for target in artifact.mapped_targets}:
+            continue
+        asset_url = release.assets.get(artifact.asset_name)
+        if not asset_url:
+            continue
+        return AssetChoice(
+            repo = release.repo,
+            tag = release.release_tag,
+            name = artifact.asset_name,
+            url = asset_url,
+            source_label = "published",
+            install_kind = install_kind,
+            selection_log = list(release.selection_log)
+            + [
+                f"rocm_selection: gpu={host.rocm_gfx_target} "
+                f"selected published {artifact.asset_name}"
+            ],
+        )
+    return None
+
+
 def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
     """Validate a release asset URL points at GitHub's expected hosts.
 
     Accepts:
       https://github.com/{expected_repo}/releases/download/...
       https://objects.githubusercontent.com/...   (GitHub's release CDN)
-    Anything else (http://, raw.githubusercontent.com, gist, etc.) is rejected
-    so a malicious API response can't redirect downloads to an attacker host.
+    Anything else (including http://, raw.githubusercontent.com, gist, etc.)
+    is rejected so a malicious API response cannot redirect downloads to an
+    attacker-chosen host.
     """
     if not isinstance(url, str) or not url:
         return False
@@ -3731,8 +3827,8 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
     host = (parsed.netloc or "").lower()
     if host == "objects.githubusercontent.com":
         # GitHub's release CDN. Restrict to release-asset paths so a tampered
-        # API response pointing at an arbitrary CDN object is rejected. Real
-        # release asset URLs carry the "/github-production-release-asset-"
+        # API response pointing at an arbitrary CDN object is still rejected.
+        # Real release asset URLs carry the "/github-production-release-asset-"
         # prefix; gist / raw / avatar CDN paths do not.
         return parsed.path.startswith("/github-production-release-asset-")
     if host == "github.com":
@@ -3744,12 +3840,12 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
 def _fetch_lemonade_release_cached(api_url: str, llama_tag: str) -> "dict | None":
     """Cached wrapper around fetch_json for lemonade release lookups.
 
-    resolve_lemonade_rocm_choice() is called twice per install (direct planner
-    + resolve_upstream_asset_choice) with identical arguments. Without
-    memoisation each install hits api.github.com twice, doubling the
-    rate-limit failure surface on busy CI runners. Cache is process-scoped;
-    tests that vary fetch_json's return value across calls should call
-    cache_clear().
+    resolve_lemonade_rocm_choice() is called twice per install (once from the
+    direct planner, once from resolve_upstream_asset_choice) with identical
+    arguments. Without memoisation, each install hits api.github.com twice,
+    doubling the rate-limit failure surface on busy CI runners. Cache is
+    process-scoped; tests that need to vary fetch_json's return value across
+    invocations should call cache_clear().
     """
     try:
         return fetch_json(api_url)
@@ -3775,21 +3871,23 @@ def resolve_lemonade_rocm_choice(
 
     os_prefix:   lemonade's asset filename label, NOT a host-distro filter.
                  Pass "ubuntu" for any Linux host (Arch, Fedora, openSUSE,
-                 Debian, ...) -- lemonade publishes one Linux variant, a
-                 manylinux-style glibc build that runs on any distro with a
-                 recent-enough glibc. Pass "windows" for Windows hosts.
+                 Debian, ...) -- lemonade only publishes one Linux variant
+                 and it is a manylinux-style glibc build that runs on any
+                 distro with a recent-enough glibc. Pass "windows" for
+                 Windows hosts.
     install_kind: "linux-rocm" or "windows-hip"
     llama_tag:   the requested upstream llama.cpp tag ("latest" or a pinned
-                 release like "b1260"). When pinned, fetch the matching
-                 lemonade release; if lemonade hasn't published that tag, skip
-                 silently (caller falls through to upstream) rather than drift
-                 to whatever lemonade ships as latest.
+                 release like "b1260"). When pinned, the resolver fetches
+                 the matching lemonade release. When the pinned tag is not
+                 published by lemonade we skip silently (and the caller
+                 falls through to upstream) rather than drift to whatever
+                 lemonade ships as latest.
     """
     if not host.rocm_gfx_target:
         return None
     # Opt-out for users who want the upstream HIP build path only -- lemonade
-    # binaries lack approved-hash manifest entries, so their integrity gate is
-    # functional validation only.
+    # binaries are downloaded without entries in the approved-hash manifest, so
+    # the integrity gate is functional validation only.
     if os.environ.get("UNSLOTH_DISABLE_LEMONADE_ROCM", "").strip().lower() in (
         "1",
         "true",
@@ -3822,7 +3920,7 @@ def resolve_lemonade_rocm_choice(
         return None
     asset_url = assets[asset_name]
     if not asset_url:
-        # release_asset_map defaults to "" when an asset row lacks
+        # release_asset_map defaults to "" when an asset row is missing
         # browser_download_url; skip cleanly instead of letting
         # download_file("") raise a less obvious error downstream.
         log(
@@ -3831,9 +3929,9 @@ def resolve_lemonade_rocm_choice(
         )
         return None
     # Defence in depth: lemonade browser_download_url should be on github.com
-    # or githubusercontent.com. A compromised GitHub API response redirecting
-    # to an attacker host would otherwise be honoured silently (lemonade
-    # assets are not in the approved-hash manifest).
+    # or githubusercontent.com. A compromised GitHub API response that
+    # redirects to an attacker-chosen host would otherwise be honoured
+    # silently (lemonade assets are not in the approved-hash manifest).
     if not _is_trusted_github_release_url(asset_url, LEMONADE_ROCM_REPO):
         log(
             f"{LEMONADE_ROCM_REPO}@{release_tag} asset {asset_name!r} points "
@@ -3841,9 +3939,9 @@ def resolve_lemonade_rocm_choice(
             "lemonade prebuilt"
         )
         return None
-    # Note: lemonade tags Linux assets "ubuntu" but the binary is a generic
-    # glibc build that runs on any distro (Arch, Fedora, ...), so this attempt
-    # is selected for all Linux ROCm hosts, not just Ubuntu.
+    # Note: lemonade tags Linux assets with "ubuntu" but the binary is a
+    # generic glibc build that runs on any distro (Arch, Fedora, ...), so
+    # this attempt is selected for all Linux ROCm hosts, not just Ubuntu.
     log(
         f"AMD GPU {host.rocm_gfx_target!r} ({gfx_family}) -- "
         f"trying lemonade-sdk ROCm prebuilt {asset_name} "
@@ -3866,30 +3964,40 @@ def resolve_lemonade_rocm_choice(
     )
 
 
-def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice:
+def resolve_upstream_asset_choice(
+    host: HostInfo,
+    llama_tag: str,
+    lemonade_tag: "str | None" = None,
+) -> AssetChoice:
+    # lemonade_tag: tag for the lemonade lookup only. The release scan pins
+    # llama_tag to per-release upstream tags (b9518, ...) that lemonade's own
+    # tag series (b1292, ...) never contains, so pinning lemonade to them 404s
+    # on every scanned release. Scan callers pass the original request
+    # (normally "latest") here; upstream asset names keep the pinned tag.
     upstream_assets = github_release_assets(UPSTREAM_REPO, llama_tag)
     if host.is_linux and host.is_x86_64:
-        # AMD ROCm: try upstream ROCm prebuilt first, then a source build. The
-        # source build (via setup.sh) compiles with -DGGML_HIP=ON and
-        # auto-detects the exact GPU target via rocminfo, more reliable for
-        # consumer GPUs (e.g. gfx1151) that may not be in the prebuilt.
+        # AMD ROCm: try upstream ROCm prebuilt first, then fall back to source build.
+        # Source build (via setup.sh) compiles with -DGGML_HIP=ON and auto-detects
+        # the exact GPU target via rocminfo, which is more reliable for consumer
+        # GPUs (e.g. gfx1151) that may not be in the prebuilt.
         if host.has_rocm and not host.has_usable_nvidia:
-            # Try lemonade-sdk per-GPU prebuilt first: built against specific
-            # gfx targets and bundle all required ROCm runtime libs.
+            # Try lemonade-sdk per-GPU prebuilt first: these are built against
+            # specific gfx targets and bundle all required ROCm runtime libs.
             lemonade_choice = resolve_lemonade_rocm_choice(
-                host, "ubuntu", "linux-rocm", llama_tag = llama_tag
+                host, "ubuntu", "linux-rocm", llama_tag = lemonade_tag or llama_tag
             )
             if lemonade_choice is not None:
                 return lemonade_choice
 
-            # Fall back to the upstream combined ROCm tarball. Scan for any
-            # rocm-<version> prebuilt; when the host ROCm version is known,
-            # pick the newest candidate whose major.minor is <= host version
-            # -- otherwise a ROCm 6.4 host downloads the rocm-7.2 tarball,
-            # fails preflight, and source-builds even though a 6.4 prebuilt
-            # exists. If none is compatible (host older than every published
-            # prebuilt), fall back to the numerically newest so we try
-            # something.
+            # Fall back to upstream combined ROCm tarball.
+            # Scan upstream assets for any rocm-<version> prebuilt. When the
+            # host ROCm runtime version is known, pick the newest candidate
+            # whose major.minor is <= host version -- otherwise a ROCm 6.4
+            # host would download the rocm-7.2 tarball, fail preflight, and
+            # fall back to a source build even though a compatible 6.4
+            # prebuilt exists. If no compatible candidate matches (e.g. host
+            # runtime is older than every published prebuilt), fall back to
+            # the numerically newest so we at least try something.
             _rocm_pattern = re.compile(
                 rf"llama-{re.escape(llama_tag)}-bin-ubuntu-rocm-([0-9]+(?:\.[0-9]+)*)-x64\.tar\.gz"
             )
@@ -3908,10 +4016,10 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                     item for item in rocm_candidates if item[0][:2] <= _host_rocm_version
                 ]
             if rocm_candidates and not _compatible:
-                # Fall back to the newest candidate so we don't force a source
-                # build when the host runtime is older than every published
-                # prebuilt: preflight still catches a true incompatibility and
-                # triggers a fallback.
+                # Fall back to the newest candidate so a source build is
+                # not forced when the host runtime is older than every
+                # published prebuilt: preflight will still catch a true
+                # incompatibility and trigger a fallback.
                 _compatible = rocm_candidates[:1]
             if _compatible:
                 rocm_name = _compatible[0][1]
@@ -3934,7 +4042,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
                     source_label = "upstream",
                     install_kind = "linux-rocm",
                 )
-            # No ROCm prebuilt available -- fall back to a source build
+            # No ROCm prebuilt available -- fall back to source build
             raise PrebuiltFallback(
                 "AMD ROCm detected but no upstream ROCm prebuilt found; "
                 "falling back to source build with HIP support"
@@ -3962,7 +4070,7 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
         # AMD ROCm on Windows: try lemonade per-GPU prebuilt first, then upstream HIP
         if host.has_rocm:
             lemonade_choice = resolve_lemonade_rocm_choice(
-                host, "windows", "windows-hip", llama_tag = llama_tag
+                host, "windows", "windows-hip", llama_tag = lemonade_tag or llama_tag
             )
             if lemonade_choice is not None:
                 return lemonade_choice
@@ -4021,12 +4129,16 @@ def resolve_upstream_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice
     raise PrebuiltFallback(f"no prebuilt policy exists for {host.system} {host.machine}")
 
 
-def resolve_asset_choice(host: HostInfo, llama_tag: str) -> AssetChoice:
+def resolve_asset_choice(
+    host: HostInfo,
+    llama_tag: str,
+    lemonade_tag: "str | None" = None,
+) -> AssetChoice:
     if host.is_linux and host.is_x86_64 and host.has_usable_nvidia:
         raise PrebuiltFallback(
             "Linux CUDA installs require a compatible published bundle; upstream fallback is not available"
         )
-    return resolve_upstream_asset_choice(host, llama_tag)
+    return resolve_upstream_asset_choice(host, llama_tag, lemonade_tag = lemonade_tag)
 
 
 def resolve_release_asset_choice(
@@ -4034,6 +4146,7 @@ def resolve_release_asset_choice(
     llama_tag: str,
     release: PublishedReleaseBundle,
     checksums: ApprovedReleaseChecksums,
+    requested_tag: "str | None" = None,
 ) -> list[AssetChoice]:
     if host.is_windows and host.is_x86_64 and host.has_usable_nvidia:
         torch_preference = detect_torch_cuda_runtime_preference(host)
@@ -4064,13 +4177,15 @@ def resolve_release_asset_choice(
 
     published_choice: AssetChoice | None = None
     if host.is_windows and host.is_x86_64:
-        # AMD Windows hosts prefer a hash-approved published Windows HIP
-        # bundle when one exists, otherwise fall through to
-        # resolve_asset_choice() so the upstream HIP prebuilt is tried before
-        # the CPU fallback. Hard-pinning the published windows-cpu bundle here
-        # would make the HIP path unreachable.
+        # AMD Windows hosts prefer the fork's per-gfx windows-rocm bundle when one
+        # covers the GPU; otherwise fall through to resolve_asset_choice(). Note
+        # that on the fork repo the upstream win-hip archive has no approved hash,
+        # so apply_approved_hashes drops it and an uncovered gfx lands on a HIP
+        # source build (auto-detecting its exact gfx) rather than an upstream
+        # prebuilt. We still avoid hard-pinning windows-cpu here so a CPU bundle
+        # never shadows that ROCm path.
         if host.has_rocm:
-            published_choice = published_asset_choice_for_kind(release, "windows-hip")
+            published_choice = published_rocm_choice_for_host(release, host, "windows-rocm")
         else:
             published_choice = published_asset_choice_for_kind(release, "windows-cpu")
     elif host.is_macos and host.is_arm64:
@@ -4087,7 +4202,10 @@ def resolve_release_asset_choice(
                 f"{release.repo}@{release.release_tag} {published_choice.name} ({exc})"
             )
 
-    return apply_approved_hashes([resolve_asset_choice(host, llama_tag)], checksums)
+    return apply_approved_hashes(
+        [resolve_asset_choice(host, llama_tag, lemonade_tag = requested_tag)],
+        checksums,
+    )
 
 
 def extract_archive(archive_path: Path, destination: Path) -> None:
@@ -4472,7 +4590,13 @@ def runtime_patterns_for_choice(choice: AssetChoice) -> list[str]:
     # libraries between b9279 and b9283) without us re-enumerating
     # every new file. Studio only invokes llama-server and llama-quantize;
     # other CLIs upstream ships (llama-cli, llama-bench, ...) are skipped.
-    if choice.install_kind in {"linux-cpu", "linux-cuda", "linux-rocm", "linux-arm64"}:
+    if choice.install_kind in {
+        "linux-cpu",
+        "linux-cuda",
+        "linux-arm64-cuda",
+        "linux-rocm",
+        "linux-arm64",
+    }:
         return ["llama-server", "llama-quantize", "lib*.so*"]
     if choice.install_kind in {"macos-arm64", "macos-x64"}:
         return ["llama-server", "llama-quantize", "lib*.dylib"]
@@ -4480,6 +4604,7 @@ def runtime_patterns_for_choice(choice: AssetChoice) -> list[str]:
         "windows-cpu",
         "windows-cuda",
         "windows-hip",
+        "windows-rocm",
         "windows-arm64",
     }:
         return ["llama-server.exe", "llama-quantize.exe", "*.dll"]
@@ -4494,10 +4619,7 @@ def runtime_subdirs_for_choice(choice: AssetChoice) -> list[str]:
     (hipblaslt/library/<gfx>/ and rocblas/library/<gfx>/) to sit next to
     their shared libraries at runtime.  These trees are multi-level and
     cannot be handled by copy_globs (filename-only matching, flat copy)."""
-    if choice.source_label == "lemonade" and choice.install_kind in {
-        "linux-rocm",
-        "windows-hip",
-    }:
+    if choice.install_kind in {"linux-rocm", "windows-rocm", "windows-hip"}:
         return ["hipblaslt", "rocblas"]
     return []
 
@@ -5494,9 +5616,11 @@ def validate_server(
         # pass one (keeps backwards compatibility with older call sites).
         _gpu_kinds = {
             "linux-cuda",
+            "linux-arm64-cuda",
             "linux-rocm",
             "windows-cuda",
             "windows-hip",
+            "windows-rocm",
             "macos-arm64",
         }
         if install_kind is not None:
@@ -5815,7 +5939,7 @@ def selected_source_archive_metadata(
 def resolve_install_attempts(
     llama_tag: str, host: HostInfo, published_repo: str, published_release_tag: str
 ) -> tuple[str, str, list[AssetChoice], ApprovedReleaseChecksums]:
-    requested_tag, plans = resolve_install_release_plans(
+    requested_tag, plans = _fork_manifest_release_plans(
         llama_tag,
         host,
         published_repo,
@@ -5827,7 +5951,50 @@ def resolve_install_attempts(
     return requested_tag, plan.llama_tag, plan.attempts, plan.approved_checksums
 
 
-def resolve_install_release_plans(
+def _linux_published_attempts(
+    host: HostInfo, bundle: PublishedReleaseBundle, requested_tag: str
+) -> list[AssetChoice]:
+    """Build the install attempts for a fork Linux host from a manifest-described
+    bundle: CUDA (with a CPU fallback), per-gfx ROCm (with a lemonade fallback),
+    or CPU. Same selection the upstream filename path used, just sourced from the
+    manifest instead of reconstructed from asset names."""
+    attempts: list[AssetChoice] = []
+    if host.has_usable_nvidia:
+        # Prefer the cudart major Studio loads at runtime (torch's bundled
+        # libcudart), not the newest detected on disk. Without this a stray
+        # cuda13 runtime outranks the torch cuda12 the binary links against.
+        torch_preference = detect_torch_cuda_runtime_preference(host)
+        selection = linux_cuda_choice_from_release(
+            host,
+            bundle,
+            preferred_runtime_line = torch_preference.runtime_line,
+            selection_preamble = torch_preference.selection_log,
+        )
+        if selection is not None:
+            attempts.extend(selection.attempts)
+    if host.has_rocm and not host.has_usable_nvidia:
+        # Prefer the fork's own per-gfx ROCm bundle (hash-approved, ships the
+        # full ROCm runtime) and fall back to the external lemonade prebuilt.
+        # Do NOT append the CPU asset for ROCm-only hosts: if lemonade fails
+        # validation we want validate_prebuilt_attempts to raise PrebuiltFallback
+        # so the caller triggers the HIP source build, not silently install a
+        # CPU-only binary.
+        published_rocm = published_rocm_choice_for_host(bundle, host, "linux-rocm")
+        if published_rocm is not None:
+            attempts.append(published_rocm)
+        lemonade_choice = resolve_lemonade_rocm_choice(
+            host, "ubuntu", "linux-rocm", llama_tag = requested_tag
+        )
+        if lemonade_choice is not None:
+            attempts.append(lemonade_choice)
+    else:
+        cpu_choice = published_asset_choice_for_kind(bundle, "linux-cpu")
+        if cpu_choice is not None:
+            attempts.append(cpu_choice)
+    return attempts
+
+
+def _fork_manifest_release_plans(
     llama_tag: str,
     host: HostInfo,
     published_repo: str,
@@ -5835,6 +6002,10 @@ def resolve_install_release_plans(
     *,
     max_release_fallbacks: int = DEFAULT_MAX_PREBUILT_RELEASE_FALLBACKS,
 ) -> tuple[str, list[InstallReleasePlan]]:
+    """Manifest-reading branch of resolve_simple_install_release_plans, used for
+    the fork's bundles whose GPU/arch coverage lives in
+    llama-prebuilt-manifest.json rather than in the filename: arm64 CUDA, Windows
+    CUDA, per-gfx ROCm, and macOS. Linux x64 takes the faster filename path."""
     requested_tag = normalized_requested_llama_tag(llama_tag)
     allow_older_release_fallback = requested_tag == "latest" and not published_release_tag
     release_limit = max(1, max_release_fallbacks)
@@ -5854,18 +6025,22 @@ def resolve_install_release_plans(
         checksums = resolved_release.checksums
         resolved_tag = bundle.upstream_tag
         try:
-            if host.is_linux and host.is_x86_64 and host.has_usable_nvidia:
-                linux_cuda_selection = resolve_linux_cuda_choice(host, bundle)
-                attempts = apply_approved_hashes(linux_cuda_selection.attempts, checksums)
+            if host.is_linux:
+                linux_attempts = _linux_published_attempts(host, bundle, requested_tag)
+                if not linux_attempts:
+                    raise PrebuiltFallback("no compatible Linux prebuilt asset was found")
+                attempts = apply_approved_hashes(linux_attempts, checksums)
                 if not attempts:
-                    raise PrebuiltFallback("no compatible Linux CUDA asset was found")
-                log_lines(linux_cuda_selection.selection_log)
+                    raise PrebuiltFallback("no compatible Linux prebuilt asset was found")
+                if attempts[0].selection_log:
+                    log_lines(attempts[0].selection_log)
             else:
                 attempts = resolve_release_asset_choice(
                     host,
                     resolved_tag,
                     bundle,
                     checksums,
+                    requested_tag = requested_tag,
                 )
                 if not attempts:
                     raise PrebuiltFallback("no compatible prebuilt asset was found")
@@ -6021,7 +6196,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             ["libggml-cpu*.so*"],
             ["libmtmd.so*"],
         ]
-    if choice.install_kind == "linux-cuda":
+    if choice.install_kind in {"linux-cuda", "linux-arm64-cuda"}:
         return [
             ["libllama-common.so*"],
             ["libllama.so*"],
@@ -6064,7 +6239,7 @@ def runtime_payload_health_groups(choice: AssetChoice) -> list[list[str]]:
             groups.append(["cublas64_*.dll"])
             groups.append(["cublasLt64_*.dll"])
         return groups
-    if choice.install_kind == "windows-hip":
+    if choice.install_kind in {"windows-hip", "windows-rocm"}:
         return [["llama.dll"], ["*hip*.dll"]]
     return []
 
@@ -6333,7 +6508,6 @@ def install_prebuilt(
     published_repo: str,
     published_release_tag: str,
     *,
-    simple_policy: bool = False,
     override_has_rocm: bool = False,
     override_rocm_gfx: str | None = None,
     force_cpu: bool = False,
@@ -6356,20 +6530,14 @@ def install_prebuilt(
                 log(
                     f"no existing llama.cpp install detected at {install_dir}; performing fresh prebuilt install"
                 )
-            if simple_policy:
-                requested_tag, release_plans = resolve_simple_install_release_plans(
-                    llama_tag,
-                    host,
-                    published_repo,
-                    published_release_tag,
-                )
-            else:
-                requested_tag, release_plans = resolve_install_release_plans(
-                    llama_tag,
-                    host,
-                    published_repo,
-                    published_release_tag,
-                )
+            # Single resolver: linux-x64 takes the fast filename path internally,
+            # every other fork host reads the manifest.
+            requested_tag, release_plans = resolve_simple_install_release_plans(
+                llama_tag,
+                host,
+                published_repo,
+                published_release_tag,
+            )
             if release_plans and existing_install_matches_plan(install_dir, host, release_plans[0]):
                 current = release_plans[0]
                 log(
@@ -6469,11 +6637,6 @@ def parse_args() -> argparse.Namespace:
             "until a usable published llama.cpp release bundle is found."
         ),
     )
-    parser.add_argument(
-        "--simple-policy",
-        action = "store_true",
-        help = "Use the simplified platform-specific prebuilt selection policy.",
-    )
     parser.add_argument(
         "--has-rocm",
         action = "store_true",
@@ -6620,7 +6783,6 @@ def main() -> int:
         llama_tag = args.llama_tag,
         published_repo = args.published_repo,
         published_release_tag = args.published_release_tag or "",
-        simple_policy = args.simple_policy,
         override_has_rocm = args.has_rocm,
         override_rocm_gfx = args.rocm_gfx,
         force_cpu = args.cpu_fallback,
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index c4ee08a15f..e707cfda7a 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -2556,7 +2556,9 @@ $LlamaCppDir = Join-Path $UnslothHome "llama.cpp"
 $NeedLlamaSourceBuild = $false
 $SkipPrebuiltInstall = $false
 $RequestedLlamaTag = if ($env:UNSLOTH_LLAMA_TAG) { $env:UNSLOTH_LLAMA_TAG } else { $DefaultLlamaTag }
-$HelperReleaseRepo = "ggml-org/llama.cpp"
+# GPU Windows (CUDA / ROCm) installs the fork's app-* prebuilts; CPU-only stays
+# on ggml-org (the fork ships no windows-cpu bundle). Mirrors setup.sh's routing.
+$HelperReleaseRepo = if ($HasNvidiaSmi -or $HasROCm) { "unslothai/llama.cpp" } else { "ggml-org/llama.cpp" }
 $LlamaPr = if ($env:UNSLOTH_LLAMA_PR) { $env:UNSLOTH_LLAMA_PR.Trim() } else { "" }
 
 $LlamaPrForce = if ($env:UNSLOTH_LLAMA_PR_FORCE) { $env:UNSLOTH_LLAMA_PR_FORCE.Trim() } else { $DefaultLlamaPrForce }
@@ -2655,20 +2657,25 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
     if (Test-Path -LiteralPath $LlamaCppDir) {
         substep "Existing llama.cpp install detected -- validating staged prebuilt update before replacement"
         # If the existing install is the wrong kind (e.g. windows-cpu on a ROCm
-        # machine that should have windows-hip), remove it so the installer is
+        # machine that should have windows-rocm), remove it so the installer is
         # forced to download the correct variant rather than skipping on tag match.
         $existingMetaPath = Join-Path $LlamaCppDir "UNSLOTH_PREBUILT_INFO.json"
         if (Test-Path $existingMetaPath) {
             try {
                 $existingMeta = Get-Content $existingMetaPath -Raw | ConvertFrom-Json
                 $existingKind = $existingMeta.install_kind
-                # A name-inferred gfx arch (Adrenalin-only, no confirmed runtime)
-                # still wants the GPU (windows-hip) build -- the lemonade prebuilt
-                # bundles its own runtime. Treat a known arch as ROCm-capable here,
-                # mirroring the --rocm-gfx forward below.
-                $expectedKind = if ($HasROCm -or $script:ROCmGfxArch) { "windows-hip" } elseif ($HasNvidiaSmi) { "windows-cuda" } else { "windows-cpu" }
-                if ($existingKind -and $existingKind -ne $expectedKind) {
-                    substep "Removing mismatched llama.cpp install (found '$existingKind', need '$expectedKind')..."
+                # A ROCm host may legitimately carry the fork's windows-rocm bundle
+                # or the upstream windows-hip fallback, so accept either and never
+                # treat a valid ROCm install as mismatched. A name-inferred gfx
+                # arch (Adrenalin-only, no confirmed runtime) still counts as
+                # ROCm-capable -- the lemonade prebuilt bundles its own runtime,
+                # mirroring the --rocm-gfx forward below. NOTE: this block is
+                # currently inert -- write_prebuilt_metadata does not persist an
+                # install_kind key, so $existingKind is always null. If that changes,
+                # add the remaining host kinds (e.g. windows-arm64) before relying on it.
+                $expectedKinds = if ($HasROCm -or $script:ROCmGfxArch) { @("windows-rocm", "windows-hip") } elseif ($HasNvidiaSmi) { @("windows-cuda") } else { @("windows-cpu") }
+                if ($existingKind -and ($existingKind -notin $expectedKinds)) {
+                    substep "Removing mismatched llama.cpp install (found '$existingKind', need one of: $($expectedKinds -join ', '))..."
                     Remove-Item -Recurse -Force -LiteralPath $LlamaCppDir -ErrorAction SilentlyContinue
                 }
             } catch {
@@ -2687,8 +2694,7 @@ if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {
             "$PSScriptRoot\install_llama_prebuilt.py",
             "--install-dir", $LlamaCppDir,
             "--llama-tag", $RequestedLlamaTag,
-            "--published-repo", $HelperReleaseRepo,
-            "--simple-policy"
+            "--published-repo", $HelperReleaseRepo
         )
         if ($HasROCm) {
             $prebuiltArgs += "--has-rocm"
diff --git a/studio/setup.sh b/studio/setup.sh
index 3e9c9ef3d6..66c03da391 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -812,6 +812,7 @@ if ! command -v rocminfo >/dev/null 2>&1 && [ -x /opt/rocm/bin/rocminfo ]; then
     PATH="$PATH:/opt/rocm/bin"
 fi
 _setup_amd_detected=false
+_setup_nvidia_usable=false
 _setup_gfx_all=""
 _setup_mkt=""
 if command -v rocminfo >/dev/null 2>&1 && \
@@ -832,6 +833,7 @@ fi
 
 if command -v nvidia-smi >/dev/null 2>&1 && \
    nvidia-smi -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
+    _setup_nvidia_usable=true
     step "gpu" "NVIDIA GPU detected"
 elif [ "$_setup_amd_detected" = true ]; then
     _setup_vis="${HIP_VISIBLE_DEVICES:-${ROCR_VISIBLE_DEVICES:-}}"
@@ -910,34 +912,46 @@ _HOST_SYSTEM="$(uname -s 2>/dev/null || true)"
 _HOST_MACHINE="$(uname -m 2>/dev/null || true)"
 
 # Pick the release repo install_llama_prebuilt.py plans against.
-# unslothai/llama.cpp ships only Linux CUDA bundles, so CPU-only Linux
-# x86_64 routes to ggml-org for bin-ubuntu-x64.tar.gz. Anything with a
-# GPU tool installed stays on unslothai (CUDA bundle / ROCm source build).
+# The fork ships CUDA (Linux x64/arm64, Windows), ROCm (Linux/Windows) and
+# macOS bundles. Only the plain CPU/Vulkan bundles still come from ggml-org, so
+# CPU-only Linux (x86_64 and arm64) routes there; GPU Linux, Windows and macOS
+# use unslothai.
 _LINUX_HAS_GPU=false
-for _GPU_TOOL in nvidia-smi rocminfo amd-smi hipconfig hipinfo; do
-    if command -v "$_GPU_TOOL" >/dev/null 2>&1; then
-        _LINUX_HAS_GPU=true
-        break
-    fi
-done
+# Route to the fork only for a usable GPU. NVIDIA counts only when a device is
+# actually enumerated (_setup_nvidia_usable, from the nvidia-smi -L probe above)
+# AND not hidden via CUDA_VISIBLE_DEVICES=-1 -- mirroring install_llama_prebuilt.py's
+# has_usable_nvidia. Mere nvidia-smi presence (CPU-only CUDA-toolkit containers,
+# broken drivers) or a hidden GPU therefore takes the ggml-org CPU prebuilt
+# instead of a slow source build. AMD is deliberately left on tooling presence,
+# not usability: an unusable NVIDIA host has a good CPU prebuilt to fall back to,
+# whereas tightening AMD would regress ROCm hosts exposing only hipconfig/hipinfo
+# into an unnecessary CPU build.
+if [ "$_setup_nvidia_usable" = true ] && [ "${CUDA_VISIBLE_DEVICES:-}" != "-1" ]; then
+    _LINUX_HAS_GPU=true
+else
+    for _GPU_TOOL in rocminfo amd-smi hipconfig hipinfo; do
+        if command -v "$_GPU_TOOL" >/dev/null 2>&1; then
+            _LINUX_HAS_GPU=true
+            break
+        fi
+    done
+fi
 
-if [ "$_HOST_SYSTEM" = "Darwin" ]; then
-    _HELPER_RELEASE_REPO="ggml-org/llama.cpp"
-elif [ "$_HOST_SYSTEM" = "Linux" ] \
+if [ "$_HOST_SYSTEM" = "Linux" ] \
         && [ "$_HOST_MACHINE" = "x86_64" ] \
         && [ "$_LINUX_HAS_GPU" = false ]; then
     _HELPER_RELEASE_REPO="ggml-org/llama.cpp"
 elif [ "$_HOST_SYSTEM" = "Linux" ] \
         && { [ "$_HOST_MACHINE" = "aarch64" ] || [ "$_HOST_MACHINE" = "arm64" ]; } \
         && [ "$_LINUX_HAS_GPU" = false ]; then
-    # Linux ARM64 (Ampere Altra, Raspberry Pi 5, GitHub `ubuntu-24.04-arm`,
-    # CPU-only Jetson rescue mode, ...). unslothai/llama.cpp only ships
-    # the Linux CUDA bundles, so without this branch the prebuilt
-    # resolver returns 0 attempts on every release and the installer
-    # falls all the way back to a source build. Upstream ggml-org ships
+    # CPU-only Linux ARM64 (Ampere Altra, Raspberry Pi 5, GitHub
+    # `ubuntu-24.04-arm`, CPU-only Jetson rescue mode, ...). The fork ships no
+    # arm64 CPU bundle, so without this branch the prebuilt resolver returns 0
+    # attempts and the installer falls back to a source build. ggml-org ships
     # llama-bNNNN-bin-ubuntu-arm64.tar.gz from at least b9072 onward.
     _HELPER_RELEASE_REPO="ggml-org/llama.cpp"
 else
+    # GPU Linux (x64 CUDA/ROCm, arm64 CUDA), Windows (CUDA/ROCm), and macOS.
     _HELPER_RELEASE_REPO="unslothai/llama.cpp"
 fi
 unset _GPU_TOOL
@@ -1000,7 +1014,6 @@ else
         --install-dir "$LLAMA_CPP_DIR"
         --llama-tag "$_REQUESTED_LLAMA_TAG"
         --published-repo "$_HELPER_RELEASE_REPO"
-        --simple-policy
     )
     if [ -n "${UNSLOTH_LLAMA_RELEASE_TAG:-}" ]; then
         _PREBUILT_CMD+=(--published-release-tag "$UNSLOTH_LLAMA_RELEASE_TAG")
@@ -1555,7 +1568,6 @@ if [ "$_LLAMA_CPP_DEGRADED" = true ] \
         --install-dir "$LLAMA_CPP_DIR"
         --llama-tag "$_REQUESTED_LLAMA_TAG"
         --published-repo "ggml-org/llama.cpp"
-        --simple-policy
         --cpu-fallback
     )
     # Trust the installer's exit code: it validates the server before exiting 0,
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index de3808469c..057612d27b 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -338,336 +338,6 @@ def test_validate_prebuilt_choice_creates_repo_shaped_linux_install(
     assert (install_dir / "BUILD_INFO.txt").exists()
 
 
-def test_simple_linux_direct_release_uses_published_source_checksums_for_branch(
-    monkeypatch: pytest.MonkeyPatch,
-):
-    source_commit = "25b1bc9c2f9aa0a390b968ee1ffd9ff01340a3fe"
-    release = {
-        "tag_name": "llama-prebuilt-master-3a92bc9",
-        "assets": [
-            {
-                "name": "app-master-linux-x64-cuda13-newer.tar.gz",
-                "browser_download_url": "https://example.test/app-master-linux-x64-cuda13-newer.tar.gz",
-            },
-            {
-                "name": "llama-prebuilt-sha256.json",
-                "browser_download_url": "https://example.test/llama-prebuilt-sha256.json",
-            },
-        ],
-    }
-    checksums = ApprovedReleaseChecksums(
-        repo = "unslothai/llama.cpp",
-        release_tag = "llama-prebuilt-master-3a92bc9",
-        upstream_tag = "b9174",
-        source_commit = source_commit,
-        source_repo = "ggml-org/llama.cpp",
-        source_repo_url = "https://github.com/ggml-org/llama.cpp",
-        source_ref_kind = "branch",
-        requested_source_ref = "master",
-        resolved_source_ref = "master",
-        artifacts = {
-            "app-master-linux-x64-cuda13-newer.tar.gz": ApprovedArtifactHash(
-                asset_name = "app-master-linux-x64-cuda13-newer.tar.gz",
-                sha256 = "a" * 64,
-                repo = "unslothai/llama.cpp",
-                kind = "linux-cuda-app",
-            ),
-            INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
-                source_commit
-            ): ApprovedArtifactHash(
-                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(source_commit),
-                sha256 = "b" * 64,
-                repo = "ggml-org/llama.cpp",
-                kind = "exact-source",
-            ),
-        },
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "load_approved_release_checksums",
-        lambda repo, release_tag: checksums,
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "detected_linux_runtime_lines",
-        lambda: (["cuda13"], {"cuda13": ["/usr/local/cuda/lib64"]}),
-    )
-    host = HostInfo(
-        system = "Linux",
-        machine = "x86_64",
-        is_windows = False,
-        is_linux = True,
-        is_macos = False,
-        is_x86_64 = True,
-        is_arm64 = False,
-        nvidia_smi = None,
-        driver_cuda_version = (13, 1),
-        compute_caps = ["100"],
-        visible_cuda_devices = None,
-        has_physical_nvidia = True,
-        has_usable_nvidia = True,
-    )
-
-    plan = INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
-        release,
-        host,
-        "unslothai/llama.cpp",
-        "latest",
-    )
-
-    assert plan is not None
-    assert plan.llama_tag == "master"
-    assert plan.approved_checksums.upstream_tag == "b9174"
-    assert plan.approved_checksums.source_commit == source_commit
-    assert plan.attempts[0].expected_sha256 == "a" * 64
-    source_repo, source_ref, _source_archive, exact_source = (
-        INSTALL_LLAMA_PREBUILT.preferred_source_archive(plan.approved_checksums, plan.llama_tag)
-    )
-    assert source_repo == "ggml-org/llama.cpp"
-    assert source_ref == source_commit
-    assert exact_source is True
-
-
-def test_simple_linux_direct_release_honors_torch_cudart_preference(
-    monkeypatch: pytest.MonkeyPatch,
-):
-    # Regression: a Blackwell host (sm_120, driver 13.0) with BOTH cudart majors
-    # visible -- a stray cuda13 wheel plus torch's cuda12 -- must install the
-    # cuda12 build that matches the runtime torch, not the newest-major cuda13
-    # build (which loads no GPU and silently falls back to CPU).
-    release = {
-        "tag_name": "b9334",
-        "assets": [
-            {
-                "name": f"app-b9334-linux-x64-{profile}.tar.gz",
-                "browser_download_url": f"https://example.test/app-b9334-linux-x64-{profile}.tar.gz",
-            }
-            for profile in (
-                "cuda12-newer",
-                "cuda12-portable",
-                "cuda13-newer",
-                "cuda13-portable",
-            )
-        ],
-    }
-    # cuda13 detected first (newest-major order); both compatible with driver 13.0.
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "detected_linux_runtime_lines",
-        lambda: (
-            ["cuda13", "cuda12"],
-            {
-                "cuda13": ["/usr/local/lib/python3.13/site-packages/nvidia/cu13/lib"],
-                "cuda12": ["/venv/lib/python3.13/site-packages/nvidia/cuda_runtime/lib"],
-            },
-        ),
-    )
-    host = HostInfo(
-        system = "Linux",
-        machine = "x86_64",
-        is_windows = False,
-        is_linux = True,
-        is_macos = False,
-        is_x86_64 = True,
-        is_arm64 = False,
-        nvidia_smi = "nvidia-smi",
-        driver_cuda_version = (13, 0),
-        compute_caps = ["120"],
-        visible_cuda_devices = None,
-        has_physical_nvidia = True,
-        has_usable_nvidia = True,
-    )
-
-    def first_asset_for_torch(line):
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT,
-            "detect_torch_cuda_runtime_preference",
-            lambda h: INSTALL_LLAMA_PREBUILT.CudaRuntimePreference(
-                runtime_line = line, selection_log = []
-            ),
-        )
-        plan = INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
-            release, host, "unslothai/llama.cpp", "latest"
-        )
-        return plan.attempts[0]
-
-    # torch reports cuda12 (the cu128 runtime) -> install the cuda12 build.
-    primary = first_asset_for_torch("cuda12")
-    assert primary.name == "app-b9334-linux-x64-cuda12-newer.tar.gz"
-    assert primary.runtime_line == "cuda12"
-
-    # torch unavailable -> unchanged newest-major fallback (documents the residual).
-    assert first_asset_for_torch(None).name == "app-b9334-linux-x64-cuda13-newer.tar.gz"
-
-
-@pytest.mark.parametrize(
-    "mutate, expected_match",
-    [
-        # Missing source_commit.
-        (
-            lambda c: setattr(c, "source_commit", None) or setattr(c, "source_commit_short", None),
-            "exact source provenance",
-        ),
-        # source_commit present, but no exact-source archive hash.
-        (
-            lambda c: c.artifacts.pop(
-                INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(c.source_commit),
-                None,
-            ),
-            "exact source provenance",
-        ),
-        # source_commit + exact-source archive present, but no source_repo.
-        (
-            lambda c: setattr(c, "source_repo", None) or setattr(c, "source_repo_url", None),
-            "exact source provenance",
-        ),
-    ],
-    ids = [
-        "missing_source_commit",
-        "missing_exact_source_artifact",
-        "missing_source_repo",
-    ],
-)
-def test_simple_linux_direct_release_rejects_branch_without_exact_source_metadata(
-    monkeypatch: pytest.MonkeyPatch, mutate, expected_match
-):
-    source_commit = "25b1bc9c2f9aa0a390b968ee1ffd9ff01340a3fe"
-    release = {
-        "tag_name": "llama-prebuilt-master-3a92bc9",
-        "assets": [
-            {
-                "name": "app-master-linux-x64-cuda13-newer.tar.gz",
-                "browser_download_url": "https://example.test/app-master-linux-x64-cuda13-newer.tar.gz",
-            },
-            {
-                "name": "llama-prebuilt-sha256.json",
-                "browser_download_url": "https://example.test/llama-prebuilt-sha256.json",
-            },
-        ],
-    }
-    checksums = ApprovedReleaseChecksums(
-        repo = "unslothai/llama.cpp",
-        release_tag = "llama-prebuilt-master-3a92bc9",
-        upstream_tag = "b9174",
-        source_commit = source_commit,
-        source_repo = "ggml-org/llama.cpp",
-        source_repo_url = "https://github.com/ggml-org/llama.cpp",
-        source_ref_kind = "branch",
-        requested_source_ref = "master",
-        resolved_source_ref = "master",
-        artifacts = {
-            "app-master-linux-x64-cuda13-newer.tar.gz": ApprovedArtifactHash(
-                asset_name = "app-master-linux-x64-cuda13-newer.tar.gz",
-                sha256 = "a" * 64,
-                repo = "unslothai/llama.cpp",
-                kind = "linux-cuda-app",
-            ),
-            INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(
-                source_commit
-            ): ApprovedArtifactHash(
-                asset_name = INSTALL_LLAMA_PREBUILT.exact_source_archive_logical_name(source_commit),
-                sha256 = "b" * 64,
-                repo = "ggml-org/llama.cpp",
-                kind = "exact-source",
-            ),
-        },
-    )
-    mutate(checksums)
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "load_approved_release_checksums",
-        lambda repo, release_tag: checksums,
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "detected_linux_runtime_lines",
-        lambda: (["cuda13"], {"cuda13": ["/usr/local/cuda/lib64"]}),
-    )
-    host = HostInfo(
-        system = "Linux",
-        machine = "x86_64",
-        is_windows = False,
-        is_linux = True,
-        is_macos = False,
-        is_x86_64 = True,
-        is_arm64 = False,
-        nvidia_smi = None,
-        driver_cuda_version = (13, 1),
-        compute_caps = ["100"],
-        visible_cuda_devices = None,
-        has_physical_nvidia = True,
-        has_usable_nvidia = True,
-    )
-
-    with pytest.raises(PrebuiltFallback, match = expected_match):
-        INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
-            release,
-            host,
-            "unslothai/llama.cpp",
-            "latest",
-        )
-
-
-def test_simple_linux_direct_release_keeps_legacy_b_tag_path_without_checksums(
-    monkeypatch: pytest.MonkeyPatch,
-):
-    release = {
-        "tag_name": "b9999",
-        "assets": [
-            {
-                "name": "app-b9999-linux-x64-cuda13-newer.tar.gz",
-                "browser_download_url": "https://example.test/app-b9999-linux-x64-cuda13-newer.tar.gz",
-            },
-            {
-                "name": "llama-prebuilt-sha256.json",
-                "browser_download_url": "https://example.test/llama-prebuilt-sha256.json",
-            },
-        ],
-    }
-
-    def unexpected_checksum_load(repo: str, release_tag: str):
-        raise AssertionError("legacy b-tag direct releases should not require checksum metadata")
-
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "load_approved_release_checksums",
-        unexpected_checksum_load,
-    )
-    monkeypatch.setattr(
-        INSTALL_LLAMA_PREBUILT,
-        "detected_linux_runtime_lines",
-        lambda: (["cuda13"], {"cuda13": ["/usr/local/cuda/lib64"]}),
-    )
-    host = HostInfo(
-        system = "Linux",
-        machine = "x86_64",
-        is_windows = False,
-        is_linux = True,
-        is_macos = False,
-        is_x86_64 = True,
-        is_arm64 = False,
-        nvidia_smi = None,
-        driver_cuda_version = (13, 1),
-        compute_caps = ["100"],
-        visible_cuda_devices = None,
-        has_physical_nvidia = True,
-        has_usable_nvidia = True,
-    )
-
-    plan = INSTALL_LLAMA_PREBUILT.direct_linux_release_plan(
-        release,
-        host,
-        "unslothai/llama.cpp",
-        "latest",
-    )
-
-    assert plan is not None
-    assert plan.llama_tag == "b9999"
-    assert plan.release_tag == "b9999"
-    assert plan.approved_checksums.source_commit is None
-    assert plan.attempts[0].expected_sha256 is None
-
-
 def test_validate_prebuilt_choice_creates_repo_shaped_windows_install(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ):
@@ -993,7 +663,7 @@ def test_install_prebuilt_falls_back_to_older_release_plan(
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [first_plan, second_plan],
@@ -1921,7 +1591,7 @@ def test_install_prebuilt_skips_download_when_existing_install_matches(
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [plan],
@@ -2011,7 +1681,7 @@ def test_install_prebuilt_does_not_skip_unhealthy_existing_install(
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [plan],
@@ -2139,7 +1809,7 @@ def test_install_prebuilt_skips_when_older_release_fallback_matches_existing_ins
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [latest_plan, fallback_plan],
@@ -2286,7 +1956,7 @@ def test_install_prebuilt_skips_same_release_fallback_attempt_when_installed(
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [plan],
@@ -2405,7 +2075,7 @@ def test_install_prebuilt_same_tag_upstream_failure_uses_older_unsloth_release_p
     monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "detect_host", lambda: host)
     monkeypatch.setattr(
         INSTALL_LLAMA_PREBUILT,
-        "resolve_install_release_plans",
+        "resolve_simple_install_release_plans",
         lambda llama_tag, host, published_repo, published_release_tag: (
             "latest",
             [latest_plan, older_plan],
diff --git a/tests/studio/install/test_llama_pr_force_and_source.py b/tests/studio/install/test_llama_pr_force_and_source.py
index 8e2a56ae39..6c780057ad 100644
--- a/tests/studio/install/test_llama_pr_force_and_source.py
+++ b/tests/studio/install/test_llama_pr_force_and_source.py
@@ -463,8 +463,13 @@ class TestSourcePatternsPs1:
         assert "$LlamaSource = $DefaultLlamaSource" in self.content
 
     def test_release_repo_override_removed(self):
+        # No env-based release-repo override; the repo is chosen by GPU detection
+        # (GPU -> fork, CPU -> ggml-org), mirroring setup.sh.
         assert "$HelperReleaseRepo = if ($env:UNSLOTH_LLAMA_RELEASE_REPO)" not in self.content
-        assert '$HelperReleaseRepo = "ggml-org/llama.cpp"' in self.content
+        assert (
+            "$HelperReleaseRepo = if ($HasNvidiaSmi -or $HasROCm) "
+            '{ "unslothai/llama.cpp" } else { "ggml-org/llama.cpp" }' in self.content
+        )
 
     def test_force_compile_skips_prebuilt_resolution_early(self):
         assert 'if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {' in self.content
diff --git a/tests/studio/install/test_pr4562_bugfixes.py b/tests/studio/install/test_pr4562_bugfixes.py
index 5b1c4a44e5..9dfa4e0005 100644
--- a/tests/studio/install/test_pr4562_bugfixes.py
+++ b/tests/studio/install/test_pr4562_bugfixes.py
@@ -686,14 +686,26 @@ class TestSourceCodePatterns:
         assert "_RESOLVED_SOURCE_REF_KIND" in content
         assert "_RESOLVED_SOURCE_REF" in content
 
-    def test_setup_sh_prebuilt_install_uses_simple_policy_only(self):
-        """Shell prebuilt path should use the simplified helper install entrypoint."""
+    def test_setup_sh_prebuilt_install_entrypoint(self):
+        """Shell prebuilt path should call the helper install entrypoint, not the
+        old tag-resolution / releases-latest flow."""
         content = SETUP_SH.read_text()
-        assert "--simple-policy" in content
         assert "--resolve-install-tag" not in content
         assert "_HELPER_RELEASE_REPO}/releases/latest" not in content
         assert "ggml-org/llama.cpp/releases/latest" not in content
 
+    def test_setup_sh_routes_to_fork_only_on_usable_gpu(self):
+        """Linux fork-vs-ggml routing must gate NVIDIA on actual GPU usability,
+        not mere nvidia-smi presence, so CPU-only / hidden-GPU hosts (e.g.
+        CUDA_VISIBLE_DEVICES=-1) get the ggml CPU prebuilt instead of a source
+        build. Guards against a silent revert to the old presence-only loop."""
+        content = SETUP_SH.read_text()
+        assert '[ "$_setup_nvidia_usable" = true ]' in content
+        assert "CUDA_VISIBLE_DEVICES" in content
+        # nvidia-smi must NOT be back in the bare presence loop.
+        assert "for _GPU_TOOL in nvidia-smi" not in content
+        assert "for _GPU_TOOL in rocminfo amd-smi hipconfig hipinfo" in content
+
     def test_setup_sh_reports_installed_prebuilt_release(self):
         """Shell wrapper should report the installed prebuilt release from metadata."""
         content = SETUP_SH.read_text()
@@ -832,10 +844,10 @@ class TestSourceCodePatterns:
                 if "LlamaCppDir" in context:
                     pytest.fail(f"Found 'git pull' in llama.cpp build section at line {i+1}")
 
-    def test_setup_ps1_prebuilt_install_uses_simple_policy_only(self):
-        """PS1 prebuilt path should use the simplified helper install entrypoint."""
+    def test_setup_ps1_prebuilt_install_entrypoint(self):
+        """PS1 prebuilt path should call the helper install entrypoint, not the
+        old tag-resolution / releases-latest flow."""
         content = SETUP_PS1.read_text()
-        assert '"--simple-policy"' in content
         assert "--resolve-install-tag" not in content
         assert "$HelperReleaseRepo/releases/latest" not in content
         assert "ggml-org/llama.cpp/releases/latest" not in content
diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.py
index dfa2378ef5..a4fc09a183 100644
--- a/tests/studio/install/test_selection_logic.py
+++ b/tests/studio/install/test_selection_logic.py
@@ -54,12 +54,11 @@ compatible_windows_runtime_lines = INSTALL_LLAMA_PREBUILT.compatible_windows_run
 runtime_line_from_cuda_version = INSTALL_LLAMA_PREBUILT.runtime_line_from_cuda_version
 apply_approved_hashes = INSTALL_LLAMA_PREBUILT.apply_approved_hashes
 linux_cuda_choice_from_release = INSTALL_LLAMA_PREBUILT.linux_cuda_choice_from_release
-parse_direct_linux_release_bundle = INSTALL_LLAMA_PREBUILT.parse_direct_linux_release_bundle
 windows_cuda_attempts = INSTALL_LLAMA_PREBUILT.windows_cuda_attempts
 resolve_upstream_asset_choice = INSTALL_LLAMA_PREBUILT.resolve_upstream_asset_choice
 resolve_requested_install_tag = INSTALL_LLAMA_PREBUILT.resolve_requested_install_tag
 resolve_install_attempts = INSTALL_LLAMA_PREBUILT.resolve_install_attempts
-resolve_install_release_plans = INSTALL_LLAMA_PREBUILT.resolve_install_release_plans
+_fork_manifest_release_plans = INSTALL_LLAMA_PREBUILT._fork_manifest_release_plans
 resolve_published_release = INSTALL_LLAMA_PREBUILT.resolve_published_release
 resolve_source_build_plan = INSTALL_LLAMA_PREBUILT.resolve_source_build_plan
 validated_checksums_for_bundle = INSTALL_LLAMA_PREBUILT.validated_checksums_for_bundle
@@ -114,7 +113,9 @@ def load_studio_run_module(monkeypatch):
     return module
 
 
+# ---------------------------------------------------------------------------
 # Helper factories
+# ---------------------------------------------------------------------------
 
 
 def make_host(**overrides):
@@ -272,7 +273,9 @@ def mock_windows_runtime(monkeypatch, lines):
     )
 
 
+# ===========================================================================
 # Studio run.py localhost warning
+# ===========================================================================
 
 
 class TestStudioLocalhostIpv6Warning:
@@ -453,7 +456,9 @@ class TestStudioLocalhostIpv6Warning:
         assert calls["stop_hint"] == 1
 
 
+# ===========================================================================
 # A. normalize_compute_cap
+# ===========================================================================
 
 
 class TestNormalizeComputeCap:
@@ -485,7 +490,9 @@ class TestNormalizeComputeCap:
         assert normalize_compute_cap("9.0") == "90"
 
 
+# ===========================================================================
 # B. normalize_compute_caps
+# ===========================================================================
 
 
 class TestNormalizeComputeCaps:
@@ -502,7 +509,9 @@ class TestNormalizeComputeCaps:
         assert normalize_compute_caps([]) == []
 
 
+# ===========================================================================
 # C. parse_cuda_visible_devices
+# ===========================================================================
 
 
 class TestParseCudaVisibleDevices:
@@ -525,7 +534,9 @@ class TestParseCudaVisibleDevices:
         assert parse_cuda_visible_devices(" 0 , 1 ") == ["0", "1"]
 
 
+# ===========================================================================
 # D. supports_explicit_visible_device_matching
+# ===========================================================================
 
 
 class TestSupportsExplicitVisibleDeviceMatching:
@@ -545,7 +556,9 @@ class TestSupportsExplicitVisibleDeviceMatching:
         assert supports_explicit_visible_device_matching(["0", "MIG-device"]) is False
 
 
+# ===========================================================================
 # E. select_visible_gpu_rows
+# ===========================================================================
 
 
 class TestSelectVisibleGpuRows:
@@ -578,7 +591,9 @@ class TestSelectVisibleGpuRows:
         assert result == []
 
 
+# ===========================================================================
 # F. compatible_linux_runtime_lines
+# ===========================================================================
 
 
 class TestCompatibleLinuxRuntimeLines:
@@ -604,38 +619,9 @@ class TestCompatibleLinuxRuntimeLines:
         assert compatible_linux_runtime_lines(host) == ["cuda14", "cuda13", "cuda12"]
 
 
-class TestParseDirectLinuxReleaseBundle:
-    def _release(self, *targets):
-        names = [f"app-bTEST-linux-x64-{t}.tar.gz" for t in targets]
-        return {
-            "tag_name": "bTEST",
-            "assets": [{"name": n, "browser_download_url": "https://x/" + n} for n in names],
-        }
-
-    def _cuda_artifact(self, bundle):
-        return [a for a in bundle.artifacts if a.install_kind == "linux-cuda"][0]
-
-    def test_parses_known_cuda13_bundle(self):
-        bundle = parse_direct_linux_release_bundle(
-            "unslothai/llama.cpp", self._release("cuda13-newer")
-        )
-        assert bundle is not None
-        assert self._cuda_artifact(bundle).runtime_line == "cuda13"
-
-    def test_parses_future_cuda_major_with_forward_profile(self):
-        # A future major name parses and inherits the newest known major's
-        # coverage for the same class as a forward default.
-        bundle = parse_direct_linux_release_bundle(
-            "unslothai/llama.cpp", self._release("cuda14-newer")
-        )
-        assert bundle is not None
-        art = self._cuda_artifact(bundle)
-        assert art.runtime_line == "cuda14"
-        assert art.coverage_class == "newer"
-        assert art.max_sm == 120  # inherited from cuda13-newer
-
-
+# ===========================================================================
 # G. pick_windows_cuda_runtime + compatible_windows_runtime_lines
+# ===========================================================================
 
 
 class TestPickWindowsCudaRuntime:
@@ -669,6 +655,14 @@ class TestCompatibleWindowsRuntimeLines:
         host = make_host(driver_cuda_version = (12, 4))
         assert compatible_windows_runtime_lines(host) == ["cuda12"]
 
+    @pytest.mark.parametrize("minor", [0, 1, 2, 3])
+    def test_cuda12_runs_on_any_12_x_driver(self, minor):
+        # cuda12 app bundles are toolkit-12.8 builds with bundled runtime; CUDA
+        # minor-version compatibility runs them on any 12.x driver, same as Linux.
+        # Previously Windows wrongly gated cuda12 below a 12.4 driver.
+        host = make_host(driver_cuda_version = (12, minor))
+        assert compatible_windows_runtime_lines(host) == ["cuda12"]
+
     def test_driver_13_1(self):
         host = make_host(driver_cuda_version = (13, 1))
         assert compatible_windows_runtime_lines(host) == ["cuda13", "cuda12"]
@@ -682,7 +676,9 @@ class TestCompatibleWindowsRuntimeLines:
         assert compatible_windows_runtime_lines(host) == ["cuda14", "cuda13", "cuda12"]
 
 
+# ===========================================================================
 # H. runtime_line_from_cuda_version
+# ===========================================================================
 
 
 class TestRuntimeLineFromCudaVersion:
@@ -702,7 +698,9 @@ class TestRuntimeLineFromCudaVersion:
         assert runtime_line_from_cuda_version("") is None
 
 
+# ===========================================================================
 # I. apply_approved_hashes
+# ===========================================================================
 
 
 class TestApplyApprovedHashes:
@@ -816,7 +814,9 @@ class TestApplyApprovedHashes:
             apply_approved_hashes([], checksums)
 
 
+# ===========================================================================
 # J. published release resolution
+# ===========================================================================
 
 
 class TestPublishedReleaseResolution:
@@ -948,6 +948,7 @@ class TestPublishedReleaseResolution:
                 [],
                 release_tag = release_tag,
                 upstream_tag = "b9000",
+                source_repo = "example/custom-llama.cpp",
                 source_commit = commit,
             ),
         )
@@ -1149,8 +1150,55 @@ class TestValidatedChecksumsForBundle:
         with pytest.raises(PrebuiltFallback, match = "manifest checksum"):
             validated_checksums_for_bundle("unslothai/llama.cpp", bundle)
 
+    def test_rejects_exact_source_without_repo(self, monkeypatch):
+        # An exact source archive with no source repo to clone from would let
+        # preferred_source_archive silently fall back to upstream source at the
+        # tag, so validation must fail closed (clean source build instead).
+        bundle = make_release([], release_tag = "r1", upstream_tag = "b8508")
+        checksums = make_checksums_with_source(
+            [], release_tag = "r1", upstream_tag = "b8508", source_commit = "a" * 40
+        )  # exact source archive, but no source_repo
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "load_approved_release_checksums",
+            lambda repo, release_tag: checksums,
+        )
 
+        with pytest.raises(PrebuiltFallback, match = "exact source archive"):
+            validated_checksums_for_bundle("unslothai/llama.cpp", bundle)
+
+    def test_accepts_exact_source_when_only_bundle_has_repo(self, monkeypatch):
+        # The source repo can live only in the manifest bundle, not the checksum
+        # payload. source_build_plan_for_release coalesces checksums-or-bundle, so
+        # validation must accept the bundle's repo rather than failing closed.
+        bundle = make_release(
+            [],
+            release_tag = "r1",
+            upstream_tag = "b8508",
+            source_repo = "ggml-org/llama.cpp",
+            source_repo_url = "https://github.com/ggml-org/llama.cpp",
+        )
+        checksums = make_checksums_with_source(
+            [], release_tag = "r1", upstream_tag = "b8508", source_commit = "a" * 40
+        )  # exact source archive, repo only on the bundle
+        monkeypatch.setattr(
+            INSTALL_LLAMA_PREBUILT,
+            "load_approved_release_checksums",
+            lambda repo, release_tag: checksums,
+        )
+
+        assert validated_checksums_for_bundle("unslothai/llama.cpp", bundle) is checksums
+        plan = INSTALL_LLAMA_PREBUILT.source_build_plan_for_release(
+            INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(bundle = bundle, checksums = checksums)
+        )
+        assert plan.source_url == "https://github.com/ggml-org/llama.cpp"
+        assert plan.source_ref_kind == "commit"
+        assert plan.source_ref == "a" * 40
+
+
+# ===========================================================================
 # K. linux_cuda_choice_from_release -- core selection
+# ===========================================================================
 
 
 class TestLinuxCudaChoiceFromRelease:
@@ -1200,6 +1248,36 @@ class TestLinuxCudaChoiceFromRelease:
         log_entries = result.selection_log
         assert any("unavailable_on_host" in entry for entry in log_entries)
 
+    def test_arm64_host_selects_linux_arm64_cuda_kind(self, monkeypatch):
+        # An arm64 CUDA host (DGX Spark / Grace Hopper) selects the
+        # linux-arm64-cuda bundle and ignores the x64 linux-cuda one.
+        mock_linux_runtime(monkeypatch, ["cuda13"])
+        host = make_host(
+            machine = "aarch64",
+            driver_cuda_version = (13, 0),
+            compute_caps = ["90"],
+        )
+        arm = make_artifact(
+            "app-b9457-linux-arm64-cuda13-portable.tar.gz",
+            install_kind = "linux-arm64-cuda",
+            runtime_line = "cuda13",
+            coverage_class = "portable",
+            supported_sms = ["90", "100", "120", "121"],
+            min_sm = 90,
+            max_sm = 121,
+            bundle_profile = "cuda13-portable",
+        )
+        x64 = make_artifact(
+            "app-b9457-linux-x64-cuda13-portable.tar.gz",
+            install_kind = "linux-cuda",
+            runtime_line = "cuda13",
+        )
+        release = make_release([arm, x64])
+        result = linux_cuda_choice_from_release(host, release)
+        assert result is not None
+        assert result.primary.install_kind == "linux-arm64-cuda"
+        assert result.primary.name == "app-b9457-linux-arm64-cuda13-portable.tar.gz"
+
     # --- SM matching ---
 
     def test_exact_sm_match(self, monkeypatch):
@@ -1404,80 +1482,9 @@ class TestLinuxCudaChoiceFromRelease:
         assert result is None
 
 
-def make_profile_artifact(asset_name, profile_name, **overrides):
-    profile = INSTALL_LLAMA_PREBUILT.DIRECT_LINUX_BUNDLE_PROFILES[profile_name]
-    defaults = dict(
-        runtime_line = profile["runtime_line"],
-        coverage_class = profile["coverage_class"],
-        supported_sms = [str(value) for value in profile["supported_sms"]],
-        min_sm = int(profile["min_sm"]),
-        max_sm = int(profile["max_sm"]),
-        bundle_profile = profile_name,
-        rank = int(profile["rank"]),
-    )
-    defaults.update(overrides)
-    return make_artifact(asset_name, **defaults)
-
-
-class TestBlackwellUltraSm103Coverage:
-    """sm_103 (B300 / GB300) runs on the bundled base compute_100 PTX via JIT."""
-
-    def test_profiles_list_sm103_wherever_sm100_is_shipped(self):
-        for (
-            name,
-            profile,
-        ) in INSTALL_LLAMA_PREBUILT.DIRECT_LINUX_BUNDLE_PROFILES.items():
-            sms = {str(value) for value in profile["supported_sms"]}
-            if "100" in sms:
-                assert "103" in sms, name
-            else:
-                assert "103" not in sms, name
-
-    def test_b300_selects_cuda13_newer_prebuilt(self, monkeypatch):
-        mock_linux_runtime(monkeypatch, ["cuda13"])
-        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
-        art = make_profile_artifact("cuda13-newer.tar.gz", "cuda13-newer")
-        release = make_release([art])
-        result = linux_cuda_choice_from_release(host, release)
-        assert result is not None
-        assert result.primary.name == "cuda13-newer.tar.gz"
-
-    def test_b300_selects_cuda12_newer_prebuilt(self, monkeypatch):
-        mock_linux_runtime(monkeypatch, ["cuda12"])
-        host = make_host(compute_caps = ["103"], driver_cuda_version = (12, 8))
-        art = make_profile_artifact("cuda12-newer.tar.gz", "cuda12-newer")
-        release = make_release([art])
-        result = linux_cuda_choice_from_release(host, release)
-        assert result is not None
-        assert result.primary.name == "cuda12-newer.tar.gz"
-
-    def test_b300_reported_as_decimal_normalizes_and_matches(self, monkeypatch):
-        mock_linux_runtime(monkeypatch, ["cuda13"])
-        host = make_host(compute_caps = ["10.3"], driver_cuda_version = (13, 0))
-        art = make_profile_artifact("cuda13-portable.tar.gz", "cuda13-portable")
-        release = make_release([art])
-        result = linux_cuda_choice_from_release(host, release)
-        assert result is not None
-
-    def test_b300_falls_back_to_portable_when_only_portable_present(self, monkeypatch):
-        mock_linux_runtime(monkeypatch, ["cuda13"])
-        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
-        art = make_profile_artifact("cuda13-portable.tar.gz", "cuda13-portable")
-        release = make_release([art])
-        result = linux_cuda_choice_from_release(host, release)
-        assert result is not None
-        assert result.primary.name == "cuda13-portable.tar.gz"
-
-    def test_older_bundle_still_rejects_b300(self, monkeypatch):
-        mock_linux_runtime(monkeypatch, ["cuda13"])
-        host = make_host(compute_caps = ["103"], driver_cuda_version = (13, 0))
-        art = make_profile_artifact("cuda13-older.tar.gz", "cuda13-older")
-        release = make_release([art])
-        result = linux_cuda_choice_from_release(host, release)
-        assert result is None
-
-
+# ===========================================================================
 # L. resolve_install_attempts
+# ===========================================================================
 
 
 class TestResolveInstallAttempts:
@@ -1602,7 +1609,11 @@ class TestResolveInstallAttempts:
         assert attempts[0].expected_sha256 == "a" * 64
         assert approved.release_tag == "llama-prebuilt-latest"
 
-    def test_linux_cpu_uses_same_tag_upstream_asset(self, monkeypatch):
+    def test_linux_cpu_fork_without_bundle_raises_no_upstream_fallback(self, monkeypatch):
+        # A CPU-only Linux host on the fork no longer falls back to the ggml-org
+        # CPU asset: production routes CPU-only Linux to ggml-org, never the fork.
+        # With no fork CPU bundle in the manifest the resolver raises rather than
+        # quietly reaching for an upstream asset.
         host = make_host(
             has_usable_nvidia = False,
             has_physical_nvidia = False,
@@ -1610,7 +1621,7 @@ class TestResolveInstallAttempts:
         )
         release = make_release([], release_tag = "llama-prebuilt-latest", upstream_tag = "b9000")
         checksums = make_checksums_with_source(
-            ["llama-b9000-bin-ubuntu-x64.tar.gz"],
+            [],
             release_tag = release.release_tag,
             upstream_tag = "b9000",
         )
@@ -1630,22 +1641,13 @@ class TestResolveInstallAttempts:
         monkeypatch.setattr(
             INSTALL_LLAMA_PREBUILT,
             "github_release_assets",
-            lambda repo, tag: {
-                f"llama-{tag}-bin-ubuntu-x64.tar.gz": f"https://example.com/llama-{tag}-bin-ubuntu-x64.tar.gz"
-            },
+            lambda repo, tag: (_ for _ in ()).throw(
+                AssertionError("fork CPU host must not query upstream assets")
+            ),
         )
 
-        _requested_tag, resolved_tag, attempts, _approved = resolve_install_attempts(
-            "latest",
-            host,
-            "unslothai/llama.cpp",
-            "",
-        )
-
-        assert resolved_tag == "b9000"
-        assert attempts[0].name == "llama-b9000-bin-ubuntu-x64.tar.gz"
-        assert attempts[0].source_label == "upstream"
-        assert attempts[0].expected_sha256 == "a" * 64
+        with pytest.raises(PrebuiltFallback, match = "no compatible Linux prebuilt asset was found"):
+            resolve_install_attempts("latest", host, "unslothai/llama.cpp", "")
 
     def test_linux_cuda_does_not_fall_back_to_upstream_cpu(self, monkeypatch):
         host = make_host(system = "Linux", machine = "x86_64", compute_caps = ["86"])
@@ -1670,7 +1672,7 @@ class TestResolveInstallAttempts:
         )
         mock_linux_runtime(monkeypatch, ["cuda12"])
 
-        with pytest.raises(PrebuiltFallback, match = "no compatible published Linux CUDA bundle"):
+        with pytest.raises(PrebuiltFallback, match = "no compatible Linux prebuilt asset was found"):
             resolve_install_attempts("latest", host, "unslothai/llama.cpp", "")
 
     def test_windows_cpu_prefers_published_asset(self, monkeypatch):
@@ -1866,37 +1868,35 @@ class TestResolveInstallAttempts:
 
 
 class TestResolveInstallReleasePlans:
-    def test_latest_collects_multiple_older_release_plans_up_to_limit(self, monkeypatch):
-        host = make_host(
-            has_usable_nvidia = False,
-            has_physical_nvidia = False,
-            nvidia_smi = None,
+    def _cuda_bundle(self, asset_name, release_tag, upstream_tag):
+        # A fork CUDA bundle that covers the default NVIDIA host (sm 86,
+        # cuda12 runtime), so each release yields a plan via
+        # linux_cuda_choice_from_release.
+        art = make_artifact(
+            asset_name,
+            install_kind = "linux-cuda",
+            runtime_line = "cuda12",
+            coverage_class = "portable",
+            supported_sms = ["75", "80", "86", "89", "90"],
+            min_sm = 75,
+            max_sm = 90,
         )
+        return INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
+            bundle = make_release([art], release_tag = release_tag, upstream_tag = upstream_tag),
+            checksums = make_checksums_with_source(
+                [asset_name],
+                release_tag = release_tag,
+                upstream_tag = upstream_tag,
+            ),
+        )
+
+    def test_latest_collects_multiple_older_release_plans_up_to_limit(self, monkeypatch):
+        mock_linux_runtime(monkeypatch, ["cuda12"])
+        host = make_host(system = "Linux", machine = "x86_64", compute_caps = ["86"])
         releases = [
-            INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
-                bundle = make_release([], release_tag = "r3", upstream_tag = "b9003"),
-                checksums = make_checksums_with_source(
-                    ["llama-b9003-bin-ubuntu-x64.tar.gz"],
-                    release_tag = "r3",
-                    upstream_tag = "b9003",
-                ),
-            ),
-            INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
-                bundle = make_release([], release_tag = "r2", upstream_tag = "b9002"),
-                checksums = make_checksums_with_source(
-                    ["llama-b9002-bin-ubuntu-x64.tar.gz"],
-                    release_tag = "r2",
-                    upstream_tag = "b9002",
-                ),
-            ),
-            INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
-                bundle = make_release([], release_tag = "r1", upstream_tag = "b9001"),
-                checksums = make_checksums_with_source(
-                    ["llama-b9001-bin-ubuntu-x64.tar.gz"],
-                    release_tag = "r1",
-                    upstream_tag = "b9001",
-                ),
-            ),
+            self._cuda_bundle("app-b9003-linux-x64-cuda12.tar.gz", "r3", "b9003"),
+            self._cuda_bundle("app-b9002-linux-x64-cuda12.tar.gz", "r2", "b9002"),
+            self._cuda_bundle("app-b9001-linux-x64-cuda12.tar.gz", "r1", "b9001"),
         ]
 
         monkeypatch.setattr(
@@ -1904,15 +1904,8 @@ class TestResolveInstallReleasePlans:
             "iter_resolved_published_releases",
             lambda requested_tag, published_repo, published_release_tag = "": iter(releases),
         )
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT,
-            "github_release_assets",
-            lambda repo, tag: {
-                f"llama-{tag}-bin-ubuntu-x64.tar.gz": f"https://example.com/llama-{tag}-bin-ubuntu-x64.tar.gz"
-            },
-        )
 
-        requested_tag, plans = resolve_install_release_plans(
+        requested_tag, plans = _fork_manifest_release_plans(
             "latest",
             host,
             "unslothai/llama.cpp",
@@ -1925,12 +1918,10 @@ class TestResolveInstallReleasePlans:
         assert [plan.llama_tag for plan in plans] == ["b9003", "b9002"]
 
     def test_latest_skips_non_installable_release_and_keeps_searching(self, monkeypatch):
-        host = make_host(
-            has_usable_nvidia = False,
-            has_physical_nvidia = False,
-            nvidia_smi = None,
-        )
+        mock_linux_runtime(monkeypatch, ["cuda12"])
+        host = make_host(system = "Linux", machine = "x86_64", compute_caps = ["86"])
         releases = [
+            # r2 ships no fork bundle, so it yields no plan and is skipped.
             INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
                 bundle = make_release([], release_tag = "r2", upstream_tag = "b9002"),
                 checksums = make_checksums_with_source(
@@ -1939,14 +1930,7 @@ class TestResolveInstallReleasePlans:
                     upstream_tag = "b9002",
                 ),
             ),
-            INSTALL_LLAMA_PREBUILT.ResolvedPublishedRelease(
-                bundle = make_release([], release_tag = "r1", upstream_tag = "b9001"),
-                checksums = make_checksums_with_source(
-                    ["llama-b9001-bin-ubuntu-x64.tar.gz"],
-                    release_tag = "r1",
-                    upstream_tag = "b9001",
-                ),
-            ),
+            self._cuda_bundle("app-b9001-linux-x64-cuda12.tar.gz", "r1", "b9001"),
         ]
 
         monkeypatch.setattr(
@@ -1954,19 +1938,8 @@ class TestResolveInstallReleasePlans:
             "iter_resolved_published_releases",
             lambda requested_tag, published_repo, published_release_tag = "": iter(releases),
         )
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT,
-            "github_release_assets",
-            lambda repo, tag: (
-                {}
-                if tag == "b9002"
-                else {
-                    f"llama-{tag}-bin-ubuntu-x64.tar.gz": f"https://example.com/llama-{tag}-bin-ubuntu-x64.tar.gz"
-                }
-            ),
-        )
 
-        _requested_tag, plans = resolve_install_release_plans(
+        _requested_tag, plans = _fork_manifest_release_plans(
             "latest",
             host,
             "unslothai/llama.cpp",
@@ -1998,7 +1971,9 @@ class TestResolveInstallReleasePlans:
             sys.modules.pop(spec.name, None)
 
 
+# ===========================================================================
 # N. windows_cuda_attempts
+# ===========================================================================
 
 
 class TestWindowsCudaAttempts:
@@ -2216,7 +2191,9 @@ class TestWindowsCudaAttempts:
         assert result[0].name == f"llama-{self.TAG}-bin-win-cuda-13.3-x64.zip"
 
 
+# ===========================================================================
 # N.1b. _pinned_windows_cuda_fallback -- pinned b9360 cuda-13.1 Blackwell fallback
+# ===========================================================================
 
 
 class TestPinnedBlackwellCudaFallback:
@@ -2357,8 +2334,49 @@ class TestPinnedBlackwellCudaFallback:
         )
         assert _windows_cuda_attempt_covers_blackwell(cpu) is False
 
+    def _app_attempt(self, profile, runtime_line, max_sm):
+        # The fork's app-named windows-cuda bundle: no toolkit minor in the name,
+        # SM coverage declared directly (as published_windows_cuda_attempts sets it).
+        return AssetChoice(
+            repo = UPSTREAM_REPO,
+            tag = self.TAG,
+            name = f"app-{self.TAG}-windows-x64-{runtime_line}-{profile}.zip",
+            url = "https://example.com/x",
+            source_label = "published",
+            install_kind = "windows-cuda",
+            runtime_line = runtime_line,
+            coverage_class = "newer" if profile == "newer" else profile,
+            max_sm = max_sm,
+            min_sm = 80,
+            supported_sms = ["120"] if max_sm >= 120 else ["86", "89"],
+        )
 
+    @pytest.mark.parametrize(
+        "profile, runtime_line, max_sm, covers",
+        [
+            ("newer", "cuda13", 120, True),  # native Blackwell build
+            ("newer", "cuda12", 120, True),  # 12.8 toolkit app bundle reaches sm120
+            ("older", "cuda12", 89, False),  # 12.4 toolkit app bundle stops at Ada
+        ],
+    )
+    def test_attempt_covers_blackwell_app_bundle(self, profile, runtime_line, max_sm, covers):
+        # App-named bundles carry no toolkit minor; coverage is read from max_sm.
+        attempt = self._app_attempt(profile, runtime_line, max_sm)
+        assert _windows_cuda_attempt_covers_blackwell(attempt) is covers
+
+    def test_pin_dormant_when_app_bundle_covers_blackwell(self):
+        # Regression: the fork's app-named cuda13 bundle covers Blackwell, so the
+        # b9360 pin must retire instead of being prepended ahead of the native
+        # in-release build (previously the coverage check only matched legacy
+        # -bin-win-cuda-X.Y-x64.zip names, so the pin never went dormant).
+        host = self._win_host((13, 1), ["120"])
+        existing = [self._app_attempt("newer", "cuda13", 120)]
+        assert _pinned_windows_cuda_fallback(host, existing) is None
+
+
+# ===========================================================================
 # N.1c. direct_upstream_release_plan -- pinned Blackwell fallback ordering
+# ===========================================================================
 
 
 class TestDirectUpstreamBlackwellPin:
@@ -2593,7 +2611,9 @@ class TestDirectLinuxNvidiaCpuGate:
         assert [a.install_kind for a in plan.attempts] == ["linux-cpu"]
 
 
+# ===========================================================================
 # N.1d. published_windows_cuda_attempts -- version-dynamic ordering seed
+# ===========================================================================
 
 
 class TestPublishedWindowsCudaAttemptsDynamicMajor:
@@ -2608,6 +2628,7 @@ class TestPublishedWindowsCudaAttemptsDynamicMajor:
             f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip",
             install_kind = "windows-cuda",
             runtime_line = runtime_line,
+            supported_sms = ["75", "80", "86", "89", "90", "100", "120"],
             max_sm = 120,
         )
 
@@ -2659,12 +2680,14 @@ class TestPublishedWindowsCudaAttemptsDynamicMajor:
         assert result[0].runtime_line == "cuda12"
 
 
+# ===========================================================================
 # N.1e. resolve_release_asset_choice -- pin on the published install path
+# ===========================================================================
 
 
 class TestResolveReleaseAssetChoicePin:
-    """The published (non --simple-policy) install path reaches the same b9360
-    Blackwell pin as the simple path, with its verified hash threaded."""
+    """The manifest install path reaches the same b9360 Blackwell pin as the
+    filename path, with its verified hash threaded."""
 
     TAG = "b8508"
 
@@ -2674,6 +2697,7 @@ class TestResolveReleaseAssetChoicePin:
                 f"llama-{self.TAG}-bin-win-cuda-{minor}-x64.zip",
                 install_kind = "windows-cuda",
                 runtime_line = line,
+                supported_sms = ["75", "80", "86", "89", "90", "100", "120"],
                 max_sm = 120,
             )
             for minor, line in minors_lines
@@ -2754,7 +2778,243 @@ class TestResolveReleaseAssetChoicePin:
         assert "b9360" not in [a.tag for a in result]
 
 
+class TestPublishedWindowsCudaAppBundleSmSelection:
+    """app-named windows-cuda bundles carry no minor in the filename, so the
+    driver-minor gate is skipped. Selection must instead filter by SM coverage,
+    or every host gets the lowest-rank "older" bundle regardless of its GPU."""
+
+    TAG = "b9457"
+
+    def _app(self, klass, supported, min_sm, max_sm, rank):
+        return make_artifact(
+            f"app-{self.TAG}-windows-x64-cuda12-{klass}.zip",
+            install_kind = "windows-cuda",
+            runtime_line = "cuda12",
+            coverage_class = klass,
+            supported_sms = supported,
+            min_sm = min_sm,
+            max_sm = max_sm,
+            bundle_profile = f"cuda12-{klass}",
+            rank = rank,
+        )
+
+    def test_blackwell_sm120_skips_older_bundle(self, monkeypatch):
+        mock_windows_runtime(monkeypatch, ["cuda12"])
+        older = self._app("older", ["70", "75", "80", "86", "89"], 70, 89, 10)
+        newer = self._app("newer", ["86", "89", "90", "100", "120"], 86, 120, 20)
+        portable = self._app(
+            "portable", ["70", "75", "80", "86", "89", "90", "100", "120"], 70, 120, 30
+        )
+        release = make_release([older, newer, portable], upstream_tag = self.TAG)
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (12, 8),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, None)
+        assert result, "expected a windows-cuda attempt for an sm120 host"
+        # The lowest-rank "older" bundle (max_sm 89) must not be chosen, and the
+        # tightest covering bundle is cuda12-newer (range 86-120).
+        assert result[0].name == f"app-{self.TAG}-windows-x64-cuda12-newer.zip"
+
+    def _line(self, line, klass, rank):
+        return make_artifact(
+            f"app-{self.TAG}-windows-x64-{line}-{klass}.zip",
+            install_kind = "windows-cuda",
+            runtime_line = line,
+            coverage_class = klass,
+            supported_sms = ["86", "89", "90", "100", "120"],
+            min_sm = 86,
+            max_sm = 120,
+            bundle_profile = f"{line}-{klass}",
+            rank = rank,
+        )
+
+    def test_cuda13_reachable_on_driver_13_0(self, monkeypatch):
+        # app-named cuda13 bundles must be reachable on a 13.0 driver. The old
+        # synthetic '13.1' minor gate dropped the whole cuda13 line (13.1 > 13.0),
+        # so a cu13 host fell to cuda12. cuda13 is gated at the major level now.
+        mock_windows_runtime(monkeypatch, ["cuda13", "cuda12"])
+        release = make_release(
+            [self._line("cuda12", "newer", 20), self._line("cuda13", "newer", 50)],
+            upstream_tag = self.TAG,
+        )
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 0),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, "cuda13")
+        assert result
+        assert result[0].runtime_line == "cuda13"
+        assert result[0].name == f"app-{self.TAG}-windows-x64-cuda13-newer.zip"
+
+    def test_app_bundle_offered_when_no_runtime_dll_detected(self, monkeypatch):
+        # Windows torch bundles cudart in torch/lib, which runtime-DLL probing
+        # misses, so detected_windows_runtime_lines() returns nothing. The app
+        # bundle ships its own runtime, so selection must fall back to the
+        # driver-derived order instead of yielding no attempt (which would drop
+        # the host to the upstream build).
+        mock_windows_runtime(monkeypatch, [])
+        release = make_release(
+            [self._line("cuda12", "newer", 20), self._line("cuda13", "newer", 50)],
+            upstream_tag = self.TAG,
+        )
+        host = make_host(
+            system = "Windows",
+            machine = "AMD64",
+            driver_cuda_version = (13, 0),
+            compute_caps = ["120"],
+        )
+        result = published_windows_cuda_attempts(host, release, "cuda13")
+        assert result, "torch-only host must still get the fork app bundle"
+        assert result[0].name == f"app-{self.TAG}-windows-x64-cuda13-newer.zip"
+
+
+class TestPublishedRocmGfxSelection:
+    """Published ROCm bundles are matched by the host's detected gfx family, not
+    by rank -- rank ties would alphabetically hand every AMD GPU the gfx103X
+    bundle (e.g. a gfx1151 Strix Halo host)."""
+
+    GFX = ["gfx103X", "gfx110X", "gfx120X", "gfx1150", "gfx1151"]
+    MEMBERS = {
+        "gfx103X": ["gfx1030", "gfx1031", "gfx1032", "gfx1034"],
+        "gfx110X": ["gfx1100", "gfx1101", "gfx1102", "gfx1103"],
+        "gfx120X": ["gfx1200", "gfx1201"],
+        "gfx1150": ["gfx1150"],
+        "gfx1151": ["gfx1151"],
+    }
+
+    def _release(self, install_kind, prefix):
+        artifacts = [
+            make_artifact(
+                f"{prefix}-{gfx}.{'zip' if 'windows' in install_kind else 'tar.gz'}",
+                install_kind = install_kind,
+                runtime_line = None,
+                coverage_class = None,
+                supported_sms = [],
+                min_sm = None,
+                max_sm = None,
+                bundle_profile = None,
+                rank = 1000,
+                gfx_target = gfx,
+                mapped_targets = self.MEMBERS[gfx],
+            )
+            for gfx in self.GFX
+        ]
+        return make_release(artifacts, upstream_tag = "b9457")
+
+    def _host(self, gfx):
+        return make_host(
+            machine = "x86_64",
+            nvidia_smi = None,
+            driver_cuda_version = None,
+            compute_caps = [],
+            has_physical_nvidia = False,
+            has_usable_nvidia = False,
+            has_rocm = True,
+            rocm_gfx_target = gfx,
+        )
+
+    def test_gfx1100_selects_gfx110X_family(self):
+        release = self._release("linux-rocm", "app-b9457-linux-x64-rocm")
+        choice = INSTALL_LLAMA_PREBUILT.published_rocm_choice_for_host(
+            release, self._host("gfx1100"), "linux-rocm"
+        )
+        assert choice is not None
+        assert choice.name == "app-b9457-linux-x64-rocm-gfx110X.tar.gz"
+
+    def test_gfx1151_strix_halo_not_handed_gfx103X(self):
+        release = self._release("linux-rocm", "app-b9457-linux-x64-rocm")
+        choice = INSTALL_LLAMA_PREBUILT.published_rocm_choice_for_host(
+            release, self._host("gfx1151"), "linux-rocm"
+        )
+        assert choice is not None
+        assert choice.name == "app-b9457-linux-x64-rocm-gfx1151.tar.gz"
+
+    def test_windows_rocm_gfx_match(self):
+        release = self._release("windows-rocm", "app-b9457-windows-x64-rocm")
+        choice = INSTALL_LLAMA_PREBUILT.published_rocm_choice_for_host(
+            release, self._host("gfx1201"), "windows-rocm"
+        )
+        assert choice is not None
+        assert choice.name == "app-b9457-windows-x64-rocm-gfx120X.zip"
+
+    def test_uncovered_gpu_returns_none(self):
+        release = self._release("linux-rocm", "app-b9457-linux-x64-rocm")
+        assert (
+            INSTALL_LLAMA_PREBUILT.published_rocm_choice_for_host(
+                release, self._host("gfx900"), "linux-rocm"
+            )
+            is None
+        )
+
+    def test_in_prefix_but_unbuilt_arch_returns_none(self):
+        # gfx1033 shares the gfx103 prefix but is not in any bundle's
+        # mapped_targets, so it must fall back to source, not be served gfx103X.
+        release = self._release("linux-rocm", "app-b9457-linux-x64-rocm")
+        for unbuilt in ("gfx1033", "gfx1035", "gfx1104", "gfx1202"):
+            assert (
+                INSTALL_LLAMA_PREBUILT.published_rocm_choice_for_host(
+                    release, self._host(unbuilt), "linux-rocm"
+                )
+                is None
+            ), unbuilt
+
+
+class TestPublishedMacosForkSelection:
+    """macOS now routes to the fork (setup.sh), which ships
+    llama-<tag>-bin-macos-<arch>.tar.gz with pinned deployment targets, selected
+    by install_kind."""
+
+    def _release(self):
+        arts = [
+            make_artifact(
+                "llama-b9457-bin-macos-arm64.tar.gz",
+                install_kind = "macos-arm64",
+                runtime_line = None,
+                coverage_class = None,
+                supported_sms = [],
+                min_sm = None,
+                max_sm = None,
+                bundle_profile = "macos-metal-arm64",
+                rank = 50,
+            ),
+            make_artifact(
+                "llama-b9457-bin-macos-x64.tar.gz",
+                install_kind = "macos-x64",
+                runtime_line = None,
+                coverage_class = None,
+                supported_sms = [],
+                min_sm = None,
+                max_sm = None,
+                bundle_profile = "macos-cpu-x64",
+                rank = 50,
+            ),
+        ]
+        return make_release(arts, upstream_tag = "b9457")
+
+    def test_macos_arm64_selects_fork_bundle(self):
+        choice = INSTALL_LLAMA_PREBUILT.published_asset_choice_for_kind(
+            self._release(), "macos-arm64"
+        )
+        assert choice is not None
+        assert choice.name == "llama-b9457-bin-macos-arm64.tar.gz"
+        assert choice.install_kind == "macos-arm64"
+
+    def test_macos_x64_selects_fork_bundle(self):
+        choice = INSTALL_LLAMA_PREBUILT.published_asset_choice_for_kind(
+            self._release(), "macos-x64"
+        )
+        assert choice is not None
+        assert choice.name == "llama-b9457-bin-macos-x64.tar.gz"
+
+
+# ===========================================================================
 # N.1. apply_approved_hashes -- runtime archive checksum threading
+# ===========================================================================
 
 
 class TestApplyApprovedHashesRuntimePair:
@@ -2826,7 +3086,9 @@ class TestApplyApprovedHashesRuntimePair:
         assert result[0].runtime_sha256 is None
 
 
+# ===========================================================================
 # O. resolve_upstream_asset_choice -- platform routing
+# ===========================================================================
 
 
 class TestResolveUpstreamAssetChoice:
@@ -2969,7 +3231,9 @@ class TestResolveUpstreamAssetChoice:
         assert result.name == cuda_name
 
 
+# ===========================================================================
 # N.2. Deterministic macOS prebuilt pin (b9415)
+# ===========================================================================
 
 
 def _macos_host(machine = "arm64", version = (15, 5)):
@@ -3092,37 +3356,47 @@ class TestResolveSimpleMacosPin:
         assert calls[0][2] == "latest"
 
 
+# ===========================================================================
 # Linux arm64 + GPU must not install the x64-only fork bundle
+# ===========================================================================
 
 
 class TestLinuxArm64ForkFallsBackToSource:
-    """The unslothai/llama.cpp fork ships only linux-x64 bundles. An arm64
-    Linux host with a GPU (GH200/GB200/DGX Spark) routes to the fork and must
-    fall back to a source build instead of selecting an x64 binary."""
+    """The fork now ships linux-arm64-cuda bundles (GH200/GB200/DGX Spark). An
+    arm64 Linux host on the fork no longer hard-fails on the simple path; it
+    delegates to the manifest-aware resolver, which selects the arm64 CUDA
+    bundle (or falls back to source only if none matches)."""
 
-    def test_arm64_nvidia_fork_raises_before_fetching_releases(self, monkeypatch):
-        # Guard fires before any release is fetched: poison the iterator to prove
-        # it is never called.
-        def _boom(*_a, **_k):
-            raise AssertionError("iterator must not run for arm64 fork hosts")
+    def test_arm64_nvidia_fork_delegates_to_manifest_resolver(self, monkeypatch):
+        # arm64 fork hosts are no longer blocked up front; the simple resolver
+        # hands them to the manifest-aware resolver instead.
+        called = {}
 
-        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "iter_release_payloads_by_time", _boom)
+        def _full(llama_tag, host, repo, tag, **_kw):
+            called["args"] = (host.machine, repo)
+            return "b9457", ["plan"]
+
+        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "_fork_manifest_release_plans", _full)
         host = make_host(system = "Linux", machine = "aarch64")
-        with pytest.raises(PrebuiltFallback, match = "linux-x64 prebuilts"):
-            resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
+        tag, plans = resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
+        assert called.get("args") == ("aarch64", "unslothai/llama.cpp")
+        assert plans == ["plan"]
 
-    def test_x86_64_fork_is_not_blocked_by_the_arch_guard(self, monkeypatch):
-        # x64 host must pass the guard and reach the iterator (here empty, so it
-        # raises the generic message, not the arch one).
-        monkeypatch.setattr(
-            INSTALL_LLAMA_PREBUILT,
-            "iter_release_payloads_by_time",
-            lambda *_a, **_k: iter(()),
-        )
+    def test_x86_64_fork_delegates_to_manifest_resolver(self, monkeypatch):
+        # The old linux-x64 arch guard is gone: an x64 fork host is routed to the
+        # manifest resolver exactly like every other fork host, not down a
+        # separate filename-parsing path.
+        called = {}
+
+        def _full(llama_tag, host, repo, tag, **_kw):
+            called["args"] = (host.machine, repo)
+            return "b9457", ["plan"]
+
+        monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "_fork_manifest_release_plans", _full)
         host = make_host(system = "Linux", machine = "x86_64")
-        with pytest.raises(PrebuiltFallback) as exc:
-            resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
-        assert "linux-x64 prebuilts" not in str(exc.value)
+        tag, plans = resolve_simple_install_release_plans("latest", host, "unslothai/llama.cpp", "")
+        assert called.get("args") == ("x86_64", "unslothai/llama.cpp")
+        assert plans == ["plan"]
 
     def test_arm64_cpu_on_ggml_org_is_not_blocked(self, monkeypatch):
         # CPU-only arm64 routes to ggml-org (not the fork), so the guard must not
@@ -3146,7 +3420,9 @@ class TestLinuxArm64ForkFallsBackToSource:
         assert "linux-x64 prebuilts" not in str(exc.value)
 
 
+# ===========================================================================
 # arm64 Linux GPU: CPU prebuilt fallback after a failed source build (--cpu-fallback)
+# ===========================================================================
 
 
 class TestCpuFallback:
@@ -3187,7 +3463,6 @@ class TestCpuFallback:
                 llama_tag = "latest",
                 published_repo = "ggml-org/llama.cpp",
                 published_release_tag = "",
-                simple_policy = True,
                 force_cpu = True,
             )
         host = captured["host"]

From b21c419a51e226305883495ff739e36d5e0890e4 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 08:58:39 -0700
Subject: [PATCH 163/222] Studio: fall back to text-only when llama.cpp is too
 old for a model's vision projector (#6075)

* Studio: fall back to text-only when llama.cpp is too old for a model's vision projector

Loading a GGUF vision model starts llama-server with --mmproj <projector>. When the installed llama.cpp prebuilt predates the model's projector format, llama-server aborts at startup with 'clip.cpp: Unknown projector type' (exit -6), and the whole load failed even though the base GGUF is a fine text/tools chat model. Seen with gemma-4 on a 3-day-old prebuilt (build b9496).

load_model now retries the launch once without --mmproj when the captured startup output indicates a projector-format incompatibility. The retry runs the model text-only, marks the session non-vision (is_vision False, mmproj audio dropped) so the status/capabilities the frontend reads stay consistent, and warns the user to update llama.cpp. Detection is generic, not model-specific, and conservative: OOM, bad GGUF, port-bind, missing-file and other failures keep their existing handling and never retry. If the text-only retry also fails, it errors out with the real reason.

Adds _is_projector_incompatibility and _strip_mmproj_args (unit-tested with the real gemma-4 abort plus negatives) and extracts _start_llama_process so both the initial start and the retry share one spawn path and each logs its argv.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Reformat mmproj fallback files to match main (ruff line-length 100 + kwarg spacing)

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 studio/backend/core/inference/llama_cpp.py    | 144 +++++++++++++-
 .../tests/test_llama_cpp_mmproj_fallback.py   | 187 ++++++++++++++++++
 2 files changed, 325 insertions(+), 6 deletions(-)
 create mode 100644 studio/backend/tests/test_llama_cpp_mmproj_fallback.py

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index ead962aac7..3c582a695f 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -2668,6 +2668,107 @@ class LlamaCppBackend:
             "Check that the GGUF file is valid and you have enough memory."
         )
 
+    @staticmethod
+    def _is_projector_incompatibility(output: str) -> bool:
+        """True when llama-server aborted because it cannot load the model's
+        vision/audio projector (mmproj), typically an installed llama.cpp
+        that predates the projector format. Conservative: only matches
+        projector-format errors so unrelated failures (OOM, bad GGUF, port
+        bind, ...) keep their own handling, and a bare 'clip'/'mmproj'
+        mention in a normal startup log does not match.
+        """
+        text = (output or "").lower()
+        if any(
+            m in text
+            for m in (
+                "unknown projector type",
+                "unsupported projector",
+                "unsupported mmproj",
+            )
+        ):
+            return True
+        # Builds that phrase it via clip.cpp without the exact words above.
+        return (
+            "clip" in text
+            and "projector" in text
+            and ("unknown" in text or "unsupported" in text or "not supported" in text)
+        )
+
+    @staticmethod
+    def _strip_mmproj_args(cmd: list[str]) -> list[str]:
+        """Return cmd without the '--mmproj <path>' pair (text-only retry).
+        Every other flag is preserved; a no-op when --mmproj is absent.
+        """
+        out: list[str] = []
+        skip_value = False
+        for tok in cmd:
+            if skip_value:
+                skip_value = False
+                continue
+            if tok == "--mmproj":
+                skip_value = True
+                continue
+            out.append(tok)
+        return out
+
+    def _start_llama_process(self, cmd: list[str], env: dict) -> None:
+        """Spawn llama-server from cmd and start draining its output.
+
+        Caller holds self._lock. Resets the stdout buffer, opens a fresh
+        per-attempt tee log, launches the process, and starts the drain
+        thread. Used for the initial start and the text-only mmproj retry.
+        """
+        # Defensive kill: if a concurrent load slipped past Phase 1
+        # (because its `self._process` was None at the time) and already
+        # stored a Popen handle here, drop that orphan before we overwrite
+        # the reference. See issue #5161.
+        self._kill_process()
+
+        self._stdout_lines = []
+        # Tee llama-server output to a dedicated log file so a post-mortem
+        # in CI (or after a remote-debug session) has the full subprocess
+        # trail even when the parent only stored the last 50 lines.
+        self._llama_log_fh = None
+        try:
+            log_dir = _swa_cache_path().parent / "logs" / "llama-server"
+            log_dir.mkdir(parents = True, exist_ok = True)
+            self._llama_log_path = log_dir / f"llama-{int(time.time())}-port-{self._port}.log"
+            self._llama_log_fh = open(
+                self._llama_log_path,
+                "w",
+                encoding = "utf-8",
+                buffering = 1,
+            )
+            logger.info(f"llama-server stdout/stderr -> {self._llama_log_path}")
+        except OSError as e:
+            # Best-effort; never block the load on logging.
+            logger.debug(f"Could not open llama-server log file: {e}")
+            self._llama_log_path = None
+
+        # Log the argv per attempt (the text-only mmproj retry re-enters here
+        # with --mmproj stripped), redacting the API key.
+        _log_cmd = list(cmd)
+        if "--api-key" in _log_cmd:
+            _ki = _log_cmd.index("--api-key") + 1
+            if _ki < len(_log_cmd):
+                _log_cmd[_ki] = "<redacted>"
+        logger.info(f"Starting llama-server: {' '.join(_log_cmd)}")
+
+        self._process = subprocess.Popen(
+            cmd,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.STDOUT,
+            text = True,
+            env = env,
+            **_windows_hidden_subprocess_kwargs(),
+        )
+
+        # Start background thread to drain stdout and prevent pipe deadlock
+        self._stdout_thread = threading.Thread(
+            target = self._drain_stdout, daemon = True, name = "llama-stdout"
+        )
+        self._stdout_thread.start()
+
     def load_model(
         self,
         *,
@@ -3346,6 +3447,9 @@ class LlamaCppBackend:
                     except Exception as e:
                         logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 
+                # Captured before any text-only fallback strips it from cmd.
+                launched_with_mmproj = "--mmproj" in cmd
+
                 # One-shot --fit off retry: recent llama.cpp runs a "fitting
                 # params to device memory" step by default (--fit defaults to
                 # 'on') even when -ngl is explicit. That step has aborted on
@@ -3520,15 +3624,43 @@ class LlamaCppBackend:
                     if healthy:
                         self._speculative_type = "default"
 
+                # A vision GGUF launched with --mmproj can abort when the
+                # installed llama.cpp is too old for the model's projector
+                # ("Unknown projector type"); in that one case retry once
+                # text-only rather than failing the whole load.
                 if not healthy:
+                    out = "\n".join(self._stdout_lines[-50:])
                     self._kill_process()
-                    raise RuntimeError(
-                        self._classify_llama_start_failure(
-                            "\n".join(self._stdout_lines[-50:]),
-                            gguf_path,
-                            self._model_identifier,
+                    if launched_with_mmproj and self._is_projector_incompatibility(out):
+                        logger.warning(
+                            "llama-server could not load this model's vision "
+                            "projector (--mmproj). The installed llama.cpp build is "
+                            "likely too old for it. Loading text-only for this "
+                            "session; run 'unsloth studio update' to enable vision."
+                        )
+                        cmd = self._strip_mmproj_args(cmd)
+                        self._is_vision = False
+                        self._mmproj_has_audio = False
+                        self._start_llama_process(cmd, env)
+                        if not self._wait_for_health(timeout = 600.0):
+                            self._kill_process()
+                            raise RuntimeError(
+                                "Vision projector incompatible with this llama.cpp "
+                                "build, and the text-only retry also failed: "
+                                + self._classify_llama_start_failure(
+                                    "\n".join(self._stdout_lines[-50:]),
+                                    gguf_path,
+                                    self._model_identifier,
+                                )
+                            )
+                    else:
+                        raise RuntimeError(
+                            self._classify_llama_start_failure(
+                                out,
+                                gguf_path,
+                                self._model_identifier,
+                            )
                         )
-                    )
 
                 self._healthy = True
 
diff --git a/studio/backend/tests/test_llama_cpp_mmproj_fallback.py b/studio/backend/tests/test_llama_cpp_mmproj_fallback.py
new file mode 100644
index 0000000000..6ef94545fe
--- /dev/null
+++ b/studio/backend/tests/test_llama_cpp_mmproj_fallback.py
@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the llama-server mmproj text-only fallback.
+
+A GGUF vision model is launched with ``--mmproj <projector>``. When the
+installed llama.cpp prebuilt is older than the model's projector format,
+llama-server aborts at startup with ``clip.cpp:NNNN: Unknown projector
+type`` (exit -6). load_model now retries once WITHOUT ``--mmproj`` so the
+base model still loads text-only, warns the user to update llama.cpp, and
+marks the session non-vision. These tests pin the two decision helpers:
+``_is_projector_incompatibility`` (when to retry) and ``_strip_mmproj_args``
+(how the retry argv is built). Unrelated failures must NOT trigger a retry.
+"""
+
+from __future__ import annotations
+
+import sys
+import types as _types
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+# Match the stubbing pattern in sibling tests so the module imports in a
+# lightweight env without fastapi.
+_loggers_stub = _types.ModuleType("loggers")
+_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
+sys.modules.setdefault("loggers", _loggers_stub)
+_structlog_stub = _types.ModuleType("structlog")
+_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("structlog")
+sys.modules.setdefault("structlog", _structlog_stub)
+if not hasattr(sys.modules["structlog"], "get_logger"):
+    sys.modules["structlog"].get_logger = _structlog_stub.get_logger
+
+from core.inference.llama_cpp import LlamaCppBackend  # noqa: E402
+
+_detect = LlamaCppBackend._is_projector_incompatibility
+_strip = LlamaCppBackend._strip_mmproj_args
+
+# Real abort captured loading gemma-4 on a 3-day-old prebuilt (build b9496).
+_GEMMA4_OLD_LLAMACPP_OUT = (
+    "srv    load_model: loading model 'gemma-4-E2B-it-UD-Q4_K_XL.gguf'\n"
+    "/build_work/src/llama.cpp-b9496/tools/mtmd/clip.cpp:4391: "
+    "Unknown projector type\n"
+    "libggml-base.so.0(ggml_abort+0x152)\n"
+    "libmtmd.so.0(clip_n_mmproj_embd)\n"
+)
+# Unrelated failures that must keep their own handling (no projector retry).
+_OOM_OUT = (
+    "ggml_backend_cuda_buffer_type_alloc_buffer: allocating 12000.00 MiB on "
+    "device 0: cudaMalloc failed: out of memory"
+)
+_BAD_ARCH_OUT = "llama_model_load: error loading model: unknown model architecture: 'qwen_image'"
+_PORT_OUT = "srv start: failed to bind: address already in use"
+_MISSING_OUT = "error: failed to open GGUF file: no such file or directory"
+# A healthy startup log that merely mentions the projector must not match.
+_HEALTHY_VISION_OUT = (
+    "Using mmproj for vision: /cache/mmproj-F16.gguf\n"
+    "clip_model_loader: loaded meta data with 20 key-value pairs\n"
+    "srv  update_slots: all slots are idle"
+)
+
+
+class TestProjectorIncompatibilityDetector:
+    def test_gemma4_on_old_llamacpp_triggers_retry(self):
+        # Headline case: a 3-day-old llama.cpp aborts on Gemma-4's projector.
+        assert _detect(_GEMMA4_OLD_LLAMACPP_OUT) is True
+
+    @pytest.mark.parametrize(
+        "out",
+        [
+            "clip.cpp:4391: Unknown projector type",
+            "error: unsupported projector type for this model",
+            "llama_mmproj: unsupported mmproj file version",
+            "clip.cpp: projector type 'gemma4' is not supported",
+        ],
+    )
+    def test_projector_format_errors_match(self, out):
+        assert _detect(out) is True
+
+    def test_case_insensitive(self):
+        assert _detect("UNKNOWN PROJECTOR TYPE") is True
+
+    @pytest.mark.parametrize(
+        "out",
+        [
+            _OOM_OUT,
+            _BAD_ARCH_OUT,
+            _PORT_OUT,
+            _MISSING_OUT,
+            _HEALTHY_VISION_OUT,
+            "",
+            # bare multimodal words without a failure term must not match
+            "loading clip model",
+            "mmproj file resolved from cache",
+        ],
+    )
+    def test_unrelated_failures_do_not_retry(self, out):
+        assert _detect(out) is False
+
+
+# A realistic vision launch argv (mirrors the live "Starting llama-server"
+# command), projector pair at the end.
+_VISION_CMD = [
+    "/home/u/.unsloth/llama.cpp/build/bin/llama-server",
+    "-m",
+    "/cache/gemma-4-E2B-it-UD-Q4_K_XL.gguf",
+    "--port",
+    "55473",
+    "-c",
+    "131072",
+    "--parallel",
+    "1",
+    "--flash-attn",
+    "on",
+    "--no-context-shift",
+    "-ngl",
+    "-1",
+    "--threads",
+    "-1",
+    "--jinja",
+    "--spec-default",
+    "--mmproj",
+    "/cache/mmproj-F16.gguf",
+]
+
+
+class TestStripMmprojArgs:
+    def test_removes_mmproj_pair(self):
+        stripped = _strip(_VISION_CMD)
+        assert "--mmproj" not in stripped
+        assert "/cache/mmproj-F16.gguf" not in stripped
+
+    def test_preserves_every_text_flag(self):
+        stripped = _strip(_VISION_CMD)
+        for flag in (
+            "-m",
+            "/cache/gemma-4-E2B-it-UD-Q4_K_XL.gguf",
+            "--port",
+            "55473",
+            "-c",
+            "131072",
+            "-ngl",
+            "-1",
+            "--jinja",
+            "--spec-default",
+            "--flash-attn",
+            "on",
+        ):
+            assert flag in stripped
+        # Exactly the two projector tokens are dropped.
+        assert len(stripped) == len(_VISION_CMD) - 2
+
+    def test_strips_mmproj_in_the_middle(self):
+        cmd = ["llama-server", "--mmproj", "/p/mm.gguf", "-c", "4096", "--jinja"]
+        assert _strip(cmd) == ["llama-server", "-c", "4096", "--jinja"]
+
+    def test_noop_when_no_mmproj(self):
+        cmd = ["llama-server", "-m", "/p/model.gguf", "-c", "4096", "--jinja"]
+        assert _strip(cmd) == cmd
+
+    def test_returns_new_list(self):
+        cmd = ["llama-server", "--mmproj", "/p/mm.gguf"]
+        out = _strip(cmd)
+        assert out is not cmd
+        assert cmd[-1] == "/p/mm.gguf"  # input untouched
+
+
+class TestRetryContract:
+    """The two helpers compose into the load_model retry decision."""
+
+    def test_gemma4_failure_yields_valid_text_only_command(self):
+        # Old-llama.cpp projector abort -> retry, and the retry argv is a
+        # valid text-only launch (model + context kept, projector gone).
+        assert _detect(_GEMMA4_OLD_LLAMACPP_OUT) is True
+        retry_cmd = _strip(_VISION_CMD)
+        assert "--mmproj" not in retry_cmd
+        assert "-m" in retry_cmd and "--jinja" in retry_cmd
+
+    def test_oom_does_not_retry_text_only(self):
+        # An OOM with --mmproj present must NOT be treated as a projector
+        # problem: load_model errors out instead of dropping vision.
+        assert _detect(_OOM_OUT) is False

From c689dc586a46010ab5fcbd7253119950c89c7707 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 09:22:39 -0700
Subject: [PATCH 164/222] Chat UI polish: template editor reset, circular
 action button hovers (#6151)

* Chat template: restore the preview box with a smaller font

Bring back the template preview under the Chat Template label at 10px
instead of 13px, clamped to four lines. The label is a plain span
again; the preview box and the edit icon open the editor.

* Circular hover for chat action buttons; smaller template edit icon

- Message action bar buttons (copy, retry, delete, more) and the
  branch picker chevrons hover as circles instead of 10px rectangles
- The three dot button next to sidebar chats gets the same circular
  hover and open state
- Chat template pencil icon drops from 14px to 12px

* Chat template: drop the preview box, add Reset to the editor dialog

- Remove the template preview under the Chat Template label; the row
  is just the label with the revert and edit icons
- The Apply and Reset buttons in the panel no longer trigger on
  template-only changes, they remain for model settings that need a
  reload
- The editor dialog gets a Reset button that restores the default
  template in the draft, disabled when the draft already matches

* Sidebar: Gemini-style row vs action hover; clickable template label

- Hovering the 3 dot action next to a chat shows only the action's
  hover circle; the row pill highlight is suppressed while the action
  is hovered and applies only when hovering the row itself
- Chat Template label opens the editor and the gap below the row is
  slightly tighter

* Plus menu More submenu styling and order; sidebar action contrast

- The More submenu was missing the unsloth-plus-menu class, so its
  items hovered with the green accent instead of the shared grey
- Saved prompts moves above Compare chat
- Opening the 3 dot menu no longer highlights the whole chat row, only
  the action circle; the circle is a step darker than the row hover so
  the two read separately
- Panel icon buttons (template pencil, revert) hover as circles

* Chat template: confirm saves with a toast

Template-only edits no longer surface the panel Apply button, so a
saved override sat pending with no indicator. Saving now shows a toast
stating the change applies on the next model reload, with a separate
message when the save clears the override.

* Chat welcome: raise the greeting block to 27.5vh

* Composer: tighten trailing padding on caret pills

The RAG and MCP pills end in a chevron that carries its own
whitespace, so their hover pill looked over padded on the right.
Pills with a caret drop from 10px to 6px right padding; label only
pills keep the wider padding.

* Compact RAG and MCP pills open their menu instead of toggling off

When the composer collapses pills to icons, the RAG and MCP glyph is
the whole button, so its turn-off click handler made the menu
unreachable. In compact mode the glyph click now falls through to the
dropdown trigger, and the hover X swap is skipped since the click no
longer turns the pill off. Full size pills keep the icon-as-off-switch
behavior.

* Compact pills: name tooltip on hover; pill shaped tooltips

- Collapsed composer icons (Search, Code, Images, Fetch, Canvas, RAG,
  MCP) show their name in a hover tooltip via data-pill-label, since
  the label itself is hidden in compact mode
- Tooltips (.tooltip-compact and the new pill tooltip) are rounded
  pills instead of 10px rectangles

* System prompt edit icon and reset; soft borderless dialogs

- System Prompt section header gets the same pencil icon as Chat
  Template, opening the prompt editor; CollapsibleSection grows an
  optional headerAction slot so the icon is not a button inside the
  toggle button
- The prompt editor dialog gets a Reset button that clears the draft,
  disabled when already empty
- All dialogs swap the border for a shared dialog-soft-surface class:
  borderless with the chatbox shadow in light mode, flat card surface
  with no shadow in dark mode

* Editor dialogs: borderless text areas

The system prompt and chat template textareas drop their border to
match the borderless dialog surface; the soft fill alone defines the
input area.

* System prompt: tighten the gap between the header and the text box
---
 .../frontend/src/components/app-sidebar.tsx   |   6 +-
 .../src/components/assistant-ui/thread.tsx    |  20 ++-
 .../src/features/chat/chat-settings-sheet.tsx | 146 ++++++++++++++----
 .../chat/components/new-project-dialog.tsx    |   2 +-
 .../src/features/chat/mcp-composer-button.tsx |  11 +-
 .../src/features/chat/projects-page.tsx       |   8 +-
 .../src/features/chat/shared-composer.tsx     |   5 +
 .../src/features/chat/thread-sidebar.tsx      |   2 +-
 .../knowledge-base-composer-button.tsx        |  11 +-
 studio/frontend/src/index.css                 |  79 +++++++---
 10 files changed, 214 insertions(+), 76 deletions(-)

diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 575fd20a06..7baa69571c 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -1169,7 +1169,7 @@ export function AppSidebar() {
         }
       }}
     >
-      <DialogContent className="menu-flat-destructive corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+      <DialogContent className="menu-flat-destructive corner-squircle dialog-soft-surface sm:max-w-md">
         <DialogHeader>
           <DialogTitle>
             {confirmingDelete?.kind === "run"
@@ -1249,7 +1249,7 @@ export function AppSidebar() {
         if (!open) setRenamingTarget(null);
       }}
     >
-      <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+      <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
         <DialogHeader>
           <DialogTitle>
             {renamingTarget?.kind === "run"
@@ -1314,7 +1314,7 @@ export function AppSidebar() {
         }
       }}
     >
-      <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+      <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
         <DialogHeader>
           <DialogTitle>
             {projectCreateMoveTarget ? "Move to new project" : "New project"}
diff --git a/studio/frontend/src/components/assistant-ui/thread.tsx b/studio/frontend/src/components/assistant-ui/thread.tsx
index 0a165724d0..84e1654079 100644
--- a/studio/frontend/src/components/assistant-ui/thread.tsx
+++ b/studio/frontend/src/components/assistant-ui/thread.tsx
@@ -785,7 +785,7 @@ const ThreadWelcome: FC<{
 
   return (
     <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col">
-      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[28.5vh]">
+      <div className="aui-thread-welcome-center flex w-full grow flex-col items-center justify-start pt-[27.5vh]">
         <div className="aui-thread-welcome-message flex w-full flex-col justify-center gap-9 px-4">
           {/* Center the greeting (sloth + title) over the composer. */}
           <div className="flex flex-row items-center justify-center gap-[15px]">
@@ -1767,6 +1767,7 @@ const WebSearchToggle: FC = () => {
         }
       }}
       className="composer-pill-btn"
+      data-pill-label="Search"
       data-active={toolsEnabled && !disabled ? "true" : "false"}
       aria-label={toolsEnabled ? "Disable web search" : "Enable web search"}
     >
@@ -1802,6 +1803,7 @@ const CodeToolsToggle: FC = () => {
       disabled={disabled}
       onClick={() => setCodeToolsEnabled(!codeToolsEnabled)}
       className="composer-pill-btn"
+      data-pill-label="Code"
       data-active={codeToolsEnabled && !disabled ? "true" : "false"}
       aria-label={
         codeToolsEnabled ? "Disable code execution" : "Enable code execution"
@@ -1843,6 +1845,7 @@ const ImagesToggle: FC = () => {
       disabled={disabled}
       onClick={() => setImageToolsEnabled(!imageToolsEnabled)}
       className="composer-pill-btn"
+      data-pill-label="Images"
       data-active={imageToolsEnabled && !disabled ? "true" : "false"}
       aria-label={
         imageToolsEnabled
@@ -1869,6 +1872,7 @@ const ArtifactsToggle: FC = () => {
       type="button"
       onClick={() => setArtifactsEnabled(false)}
       className="composer-pill-btn"
+      data-pill-label="Canvas"
       data-active="true"
       aria-label="Disable canvas"
     >
@@ -2256,11 +2260,7 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
             <MoreHorizontalIcon className="size-4" />
             More
           </DropdownMenuSubTrigger>
-          <DropdownMenuSubContent className="w-[200px]">
-            <DropdownMenuItem onSelect={() => startCompare()}>
-              <Columns2Icon />
-              Compare chat
-            </DropdownMenuItem>
+          <DropdownMenuSubContent className="unsloth-plus-menu w-[200px]">
             <DropdownMenuSub>
               <DropdownMenuSubTrigger>
                 <HugeiconsIcon icon={Bookmark02Icon} strokeWidth={2} />
@@ -2284,6 +2284,10 @@ const ComposerToolsMenu: FC<{ side?: "top" | "bottom" }> = ({
                 </DropdownMenuItem>
               </DropdownMenuSubContent>
             </DropdownMenuSub>
+            <DropdownMenuItem onSelect={() => startCompare()}>
+              <Columns2Icon />
+              Compare chat
+            </DropdownMenuItem>
             <DropdownMenuSub>
               <DropdownMenuSubTrigger
                 disabled={!activeThreadId || messageCount === 0}
@@ -2634,7 +2638,7 @@ const AssistantActionBar: FC = () => {
   return (
     <ActionBarPrimitive.Root
       hideWhenRunning={true}
-      className="aui-assistant-action-bar-root col-start-3 row-start-2 flex items-center gap-1 text-chat-icon-fg [&_button:not([data-slot=message-timing-trigger])]:size-8 [&_button]:!rounded-[10px] [&_button:hover]:bg-chat-icon-bg-hover [&_button:hover]:text-chat-icon-fg-hover"
+      className="aui-assistant-action-bar-root col-start-3 row-start-2 flex items-center gap-1 text-chat-icon-fg [&_button:not([data-slot=message-timing-trigger])]:size-8 [&_button]:!rounded-full [&_button:hover]:bg-chat-icon-bg-hover [&_button:hover]:text-chat-icon-fg-hover"
     >
       <CopyButton />
       <ActionBarPrimitive.Reload asChild={true}>
@@ -2714,7 +2718,7 @@ const UserActionBar: FC = () => {
   return (
     <ActionBarPrimitive.Root
       autohide="always"
-      className="aui-user-action-bar-root flex gap-1 text-chat-icon-fg [&_button]:size-8 [&_button]:!rounded-[10px] [&_button:hover]:bg-chat-icon-bg-hover [&_button:hover]:text-chat-icon-fg-hover"
+      className="aui-user-action-bar-root flex gap-1 text-chat-icon-fg [&_button]:size-8 [&_button]:!rounded-full [&_button:hover]:bg-chat-icon-bg-hover [&_button:hover]:text-chat-icon-fg-hover"
     >
       <CopyButton />
       <ActionBarPrimitive.Edit asChild={true}>
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 96415c4da0..0bd9d8eee6 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -323,6 +323,7 @@ function saveCollapsibleOpen(label: string, open: boolean) {
 function CollapsibleSection({
   label,
   labelHref,
+  headerAction,
   children,
   defaultOpen = false,
   first = false,
@@ -334,6 +335,12 @@ function CollapsibleSection({
    * are siblings rather than an <a> nested in a <button> (invalid HTML).
    */
   labelHref?: string;
+  /**
+   * Optional control rendered before the chevron (e.g. an edit icon). The
+   * label and chevron become sibling toggles so the action is not a button
+   * nested in a button.
+   */
+  headerAction?: ReactNode;
   children?: ReactNode;
   defaultOpen?: boolean;
   first?: boolean;
@@ -383,6 +390,29 @@ function CollapsibleSection({
             />
           </button>
         </div>
+      ) : headerAction ? (
+        <div className={headerClasses}>
+          <button
+            type="button"
+            onClick={toggle}
+            className="flex min-w-0 flex-1 cursor-pointer items-center text-left leading-none transition-colors hover:text-nav-fg"
+          >
+            <span className="leading-none">{label}</span>
+          </button>
+          <span className="flex shrink-0 items-center gap-1">
+            {headerAction}
+            <button
+              type="button"
+              onClick={toggle}
+              aria-label={open ? `Collapse ${label}` : `Expand ${label}`}
+              className="flex shrink-0 cursor-pointer items-center leading-none transition-colors hover:text-nav-fg"
+            >
+              <ChevronDown
+                className={cn("size-3.5", open ? "rotate-0" : "-rotate-90")}
+              />
+            </button>
+          </span>
+        </div>
       ) : (
         <button
           type="button"
@@ -497,16 +527,12 @@ export function ChatSettingsPanel({
   const specDirty = speculativeType !== loadedSpeculativeType;
   const specDraftDirty = specDraftNMax !== loadedSpecDraftNMax;
   const modelSettingsDirty = kvDirty || ctxDirty || specDirty || specDraftDirty;
-  const chatTemplateOverride = useChatRuntimeStore(
-    (s) => s.chatTemplateOverride,
-  );
   const loadedChatTemplateOverride = useChatRuntimeStore(
     (s) => s.loadedChatTemplateOverride,
   );
   const setChatTemplateOverride = useChatRuntimeStore(
     (s) => s.setChatTemplateOverride,
   );
-  const templateDirty = chatTemplateOverride !== loadedChatTemplateOverride;
   const [presetNameInput, setPresetNameInput] = useState(activePreset);
   const [systemPromptEditorOpen, setSystemPromptEditorOpen] = useState(false);
   const [systemPromptDraft, setSystemPromptDraft] = useState("");
@@ -972,7 +998,7 @@ export function ChatSettingsPanel({
               </>
             )}
             <ChatTemplateFields />
-            {(modelSettingsDirty || templateDirty) && (
+            {modelSettingsDirty && (
               <div className="flex flex-wrap gap-1.5 pt-1">
                 <Button
                   type="button"
@@ -1223,13 +1249,41 @@ export function ChatSettingsPanel({
           </CollapsibleSection>
         ) : null}
 
-        <CollapsibleSection label="System Prompt" defaultOpen={true}>
+        <CollapsibleSection
+          label="System Prompt"
+          defaultOpen={true}
+          headerAction={
+            <Tooltip>
+              <TooltipPrimitive.Trigger asChild>
+                <button
+                  type="button"
+                  onClick={openSystemPromptEditor}
+                  className="nav-icon-btn text-nav-icon-idle hover:bg-panel-surface-hover hover:text-black dark:hover:text-white"
+                  aria-label="Edit system prompt"
+                >
+                  <HugeiconsIcon
+                    icon={Edit03Icon}
+                    strokeWidth={1.75}
+                    className="size-3"
+                  />
+                </button>
+              </TooltipPrimitive.Trigger>
+              <TooltipContent
+                side="top"
+                sideOffset={6}
+                className="tooltip-compact"
+              >
+                Edit prompt
+              </TooltipContent>
+            </Tooltip>
+          }
+        >
           <button
             type="button"
             onClick={openSystemPromptEditor}
             aria-label="Edit system prompt"
             className={cn(
-              "panel-text-surface mt-1 flex w-full h-20 overflow-hidden cursor-pointer items-start px-3.5 py-2.5 text-left text-[13px] font-medium leading-relaxed corner-squircle focus-visible:outline-none focus-visible:border-ring focus-visible:ring-[1px] focus-visible:ring-ring/40",
+              "panel-text-surface -mt-1 flex w-full h-20 overflow-hidden cursor-pointer items-start px-3.5 py-2.5 text-left text-[13px] font-medium leading-relaxed corner-squircle focus-visible:outline-none focus-visible:border-ring focus-visible:ring-[1px] focus-visible:ring-ring/40",
               params.systemPrompt
                 ? "text-nav-fg"
                 : "text-muted-foreground",
@@ -1384,7 +1438,7 @@ export function ChatSettingsPanel({
         }}
       >
         <DialogContent
-          className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-3xl"
+          className="corner-squircle dialog-soft-surface sm:max-w-3xl"
           overlayClassName="bg-background/35 supports-backdrop-filter:backdrop-blur-[1px]"
         >
           <DialogHeader>
@@ -1407,7 +1461,7 @@ export function ChatSettingsPanel({
               onChange={(event) => setSystemPromptDraft(event.target.value)}
               placeholder="You are a helpful assistant..."
               fieldSizing="fixed"
-              className="min-h-[24rem] max-h-[50vh] overflow-y-auto text-sm leading-6 corner-squircle focus-visible:border-input focus-visible:ring-0"
+              className="min-h-[24rem] max-h-[50vh] overflow-y-auto border-0 text-sm leading-6 corner-squircle focus-visible:ring-0"
               rows={14}
             />
           </div>
@@ -1415,20 +1469,31 @@ export function ChatSettingsPanel({
             <Button
               type="button"
               variant="ghost"
-              onClick={() => {
-                setSystemPromptDraft(params.systemPrompt);
-                setSystemPromptEditorOpen(false);
-              }}
+              onClick={() => setSystemPromptDraft("")}
+              disabled={systemPromptDraft.length === 0}
+              className="text-muted-foreground"
             >
-              Cancel
-            </Button>
-            <Button
-              type="button"
-              onClick={saveSystemPromptEditor}
-              disabled={!systemPromptEditorDirty}
-            >
-              Save
+              Reset
             </Button>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                type="button"
+                variant="ghost"
+                onClick={() => {
+                  setSystemPromptDraft(params.systemPrompt);
+                  setSystemPromptEditorOpen(false);
+                }}
+              >
+                Cancel
+              </Button>
+              <Button
+                type="button"
+                onClick={saveSystemPromptEditor}
+                disabled={!systemPromptEditorDirty}
+              >
+                Save
+              </Button>
+            </div>
           </DialogFooter>
         </DialogContent>
       </Dialog>
@@ -1556,15 +1621,19 @@ function ChatTemplateFields() {
     setEditorOpen(true);
   };
   const saveEditor = () => {
-    setOverride(
-      draft.trim().length === 0 || draft === defaultTemplate ? null : draft,
-    );
+    const cleared = draft.trim().length === 0 || draft === defaultTemplate;
+    setOverride(cleared ? null : draft);
     setEditorOpen(false);
+    toast.success(
+      cleared
+        ? "Chat template reset to default. It applies on the next model reload."
+        : "Chat template saved. It applies on the next model reload.",
+    );
   };
 
   return (
     <>
-      <div className="flex items-center justify-between gap-2">
+      <div className="-mb-1.5 flex items-center justify-between gap-2">
         <button
           type="button"
           onClick={openEditor}
@@ -1609,7 +1678,7 @@ function ChatTemplateFields() {
                 <HugeiconsIcon
                   icon={Edit03Icon}
                   strokeWidth={1.75}
-                  className="size-3.5"
+                  className="size-3"
                 />
               </button>
             </TooltipPrimitive.Trigger>
@@ -1625,7 +1694,7 @@ function ChatTemplateFields() {
       </div>
       <Dialog open={editorOpen} onOpenChange={setEditorOpen}>
         <DialogContent
-          className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-3xl"
+          className="corner-squircle dialog-soft-surface sm:max-w-3xl"
           overlayClassName="bg-background/35 supports-backdrop-filter:backdrop-blur-[1px]"
         >
           <DialogHeader>
@@ -1646,7 +1715,7 @@ function ChatTemplateFields() {
               value={draft}
               onChange={(event) => setDraft(event.target.value)}
               fieldSizing="fixed"
-              className="min-h-[24rem] max-h-[50vh] overflow-y-auto font-mono text-xs leading-5 corner-squircle focus-visible:border-input focus-visible:ring-0"
+              className="min-h-[24rem] max-h-[50vh] overflow-y-auto border-0 font-mono text-xs leading-5 corner-squircle focus-visible:ring-0"
               rows={14}
               spellCheck={false}
             />
@@ -1655,13 +1724,24 @@ function ChatTemplateFields() {
             <Button
               type="button"
               variant="ghost"
-              onClick={() => setEditorOpen(false)}
+              onClick={() => setDraft(defaultTemplate)}
+              disabled={draft === defaultTemplate}
+              className="text-muted-foreground"
             >
-              Cancel
-            </Button>
-            <Button type="button" onClick={saveEditor} disabled={!draftDirty}>
-              Save
+              Reset
             </Button>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                type="button"
+                variant="ghost"
+                onClick={() => setEditorOpen(false)}
+              >
+                Cancel
+              </Button>
+              <Button type="button" onClick={saveEditor} disabled={!draftDirty}>
+                Save
+              </Button>
+            </div>
           </DialogFooter>
         </DialogContent>
       </Dialog>
diff --git a/studio/frontend/src/features/chat/components/new-project-dialog.tsx b/studio/frontend/src/features/chat/components/new-project-dialog.tsx
index 38b0983e10..880129ac6c 100644
--- a/studio/frontend/src/features/chat/components/new-project-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/new-project-dialog.tsx
@@ -56,7 +56,7 @@ export function NewProjectDialog({
         onOpenChange(next);
       }}
     >
-      <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+      <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
         <DialogHeader>
           <DialogTitle>New project</DialogTitle>
         </DialogHeader>
diff --git a/studio/frontend/src/features/chat/mcp-composer-button.tsx b/studio/frontend/src/features/chat/mcp-composer-button.tsx
index e0f024a40e..aecfe9b430 100644
--- a/studio/frontend/src/features/chat/mcp-composer-button.tsx
+++ b/studio/frontend/src/features/chat/mcp-composer-button.tsx
@@ -246,17 +246,24 @@ export function McpComposerButton({
             <button
               type="button"
               className="composer-pill-btn"
+              data-pill-label="MCP"
               data-active={active ? "true" : "false"}
               aria-label="MCP servers"
             >
               {/* Icon doubles as an off switch: hover swaps to an X; clicking
-                  it turns MCP off without opening the menu. */}
+                  it turns MCP off without opening the menu. In compact
+                  icon-only mode the glyph is the whole button, so clicks fall
+                  through to the trigger and open the menu instead. */}
               <span
                 role="button"
                 aria-label="Turn off MCP"
                 tabIndex={-1}
-                onPointerDown={(e) => e.stopPropagation()}
+                onPointerDown={(e) => {
+                  if (e.currentTarget.closest('[data-pill-compact="true"]')) return;
+                  e.stopPropagation();
+                }}
                 onClick={(e) => {
+                  if (e.currentTarget.closest('[data-pill-compact="true"]')) return;
                   e.stopPropagation();
                   setMcpEnabledForChat(false);
                 }}
diff --git a/studio/frontend/src/features/chat/projects-page.tsx b/studio/frontend/src/features/chat/projects-page.tsx
index a9ce03fa47..724cd0a755 100644
--- a/studio/frontend/src/features/chat/projects-page.tsx
+++ b/studio/frontend/src/features/chat/projects-page.tsx
@@ -501,7 +501,7 @@ export function ProjectsPage() {
           if (!open) setCreating(false);
         }}
       >
-        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
           <DialogHeader>
             <DialogTitle>New project</DialogTitle>
           </DialogHeader>
@@ -538,7 +538,7 @@ export function ProjectsPage() {
           if (!open) setRenaming(null);
         }}
       >
-        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
           <DialogHeader>
             <DialogTitle>Rename project</DialogTitle>
           </DialogHeader>
@@ -574,7 +574,7 @@ export function ProjectsPage() {
 
       {/* Import destination picker */}
       <Dialog open={importFile !== null} onOpenChange={(open) => { if (!open) setImportFile(null); }}>
-        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-md">
           <DialogHeader>
             <DialogTitle>Import chats</DialogTitle>
           </DialogHeader>
@@ -609,7 +609,7 @@ export function ProjectsPage() {
           if (!open) setDeleting(null);
         }}
       >
-        <DialogContent className="menu-flat-destructive corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-md">
+        <DialogContent className="menu-flat-destructive corner-squircle dialog-soft-surface sm:max-w-md">
           <DialogHeader>
             <DialogTitle>Delete project</DialogTitle>
           </DialogHeader>
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index fe71adf4d7..74ab4a1b9e 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -1567,6 +1567,7 @@ export function SharedComposer({
               }
             }}
             className="composer-pill-btn"
+            data-pill-label="Search"
             data-active={toolsEnabled && !searchDisabled ? "true" : "false"}
             aria-label={
               toolsEnabled ? "Disable web search" : "Enable web search"
@@ -1582,6 +1583,7 @@ export function SharedComposer({
             disabled={codeDisabled}
             onClick={() => setCodeToolsEnabled(!codeToolsEnabled)}
             className="composer-pill-btn"
+            data-pill-label="Code"
             data-active={codeToolsEnabled && !codeDisabled ? "true" : "false"}
             aria-label={
               codeToolsEnabled
@@ -1604,6 +1606,7 @@ export function SharedComposer({
               disabled={imageDisabled}
               onClick={() => setImageToolsEnabled(!imageToolsEnabled)}
               className="composer-pill-btn"
+              data-pill-label="Images"
               data-active={
                 imageToolsEnabled && !imageDisabled ? "true" : "false"
               }
@@ -1630,6 +1633,7 @@ export function SharedComposer({
               disabled={webFetchDisabled}
               onClick={() => setWebFetchToolsEnabled(!webFetchToolsEnabled)}
               className="composer-pill-btn"
+              data-pill-label="Fetch"
               data-active={
                 webFetchToolsEnabled && !webFetchDisabled ? "true" : "false"
               }
@@ -1648,6 +1652,7 @@ export function SharedComposer({
               type="button"
               onClick={() => setArtifactsEnabled(false)}
               className="composer-pill-btn"
+              data-pill-label="Canvas"
               data-active="true"
               aria-label="Disable canvas"
             >
diff --git a/studio/frontend/src/features/chat/thread-sidebar.tsx b/studio/frontend/src/features/chat/thread-sidebar.tsx
index 2b255c6c14..0d35facb2a 100644
--- a/studio/frontend/src/features/chat/thread-sidebar.tsx
+++ b/studio/frontend/src/features/chat/thread-sidebar.tsx
@@ -331,7 +331,7 @@ export function ThreadSidebar({
 
       {/* Rename dialog */}
       <Dialog open={renamingItem !== null} onOpenChange={(open) => { if (!open) setRenamingItem(null); }}>
-        <DialogContent className="corner-squircle border border-border/60 bg-background/98 shadow-none sm:max-w-sm">
+        <DialogContent className="corner-squircle dialog-soft-surface sm:max-w-sm">
           <DialogHeader>
             <DialogTitle>Rename chat</DialogTitle>
           </DialogHeader>
diff --git a/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
index e040d1842a..e3c9c9b41f 100644
--- a/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
+++ b/studio/frontend/src/features/rag/components/knowledge-base-composer-button.tsx
@@ -100,17 +100,24 @@ export function KnowledgeBaseComposerButton({
           <button
             type="button"
             className="composer-pill-btn"
+            data-pill-label="RAG"
             data-active={ragDisabled ? "false" : "true"}
             aria-label="Retrieval source"
           >
             {/* Icon doubles as an off switch: hover swaps to an X; clicking it
-                turns RAG off without opening the menu. */}
+                turns RAG off without opening the menu. In compact icon-only
+                mode the glyph is the whole button, so clicks fall through to
+                the trigger and open the menu instead. */}
             <span
               role="button"
               aria-label="Turn off retrieval"
               tabIndex={-1}
-              onPointerDown={(e) => e.stopPropagation()}
+              onPointerDown={(e) => {
+                if (e.currentTarget.closest('[data-pill-compact="true"]')) return;
+                e.stopPropagation();
+              }}
               onClick={(e) => {
+                if (e.currentTarget.closest('[data-pill-compact="true"]')) return;
                 e.stopPropagation();
                 setRagEnabled(false);
               }}
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 34e4241ae2..0aa9ac0152 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -524,7 +524,7 @@
 	}
 
 	.nav-icon-btn {
-		@apply inline-flex h-7 w-7 items-center justify-center rounded-[10px] transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring;
+		@apply inline-flex h-7 w-7 items-center justify-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring;
 	}
 
 	/* Standard icon size — drives every nav/menu/action-bar icon
@@ -544,31 +544,26 @@
 	.sidebar-nav-btn {
 		color: var(--nav-fg);
 	}
+	/* Gemini-style: hovering or opening the row action (3 dots) shows only
+	   the action's circle; the row highlights only when hovering the row
+	   itself. */
 	.sidebar-nav-btn:hover,
 	.sidebar-nav-btn[data-active="true"],
 	.sidebar-nav-btn[data-state="open"],
-	.group\/project-item:hover .sidebar-nav-btn,
-	.group\/project-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.group\/project-chat-item:hover .sidebar-nav-btn,
-	.group\/project-chat-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.group\/recent-item:hover .sidebar-nav-btn,
-	.group\/recent-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.group\/run-item:hover .sidebar-nav-btn,
-	.group\/run-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn {
+	.group\/project-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.group\/project-chat-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.group\/recent-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.group\/run-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn {
 		background-color: var(--nav-surface-hover) !important;
 		color: #000 !important;
 	}
 	.dark .sidebar-nav-btn:hover,
 	.dark .sidebar-nav-btn[data-active="true"],
 	.dark .sidebar-nav-btn[data-state="open"],
-	.dark .group\/project-item:hover .sidebar-nav-btn,
-	.dark .group\/project-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.dark .group\/project-chat-item:hover .sidebar-nav-btn,
-	.dark .group\/project-chat-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.dark .group\/recent-item:hover .sidebar-nav-btn,
-	.dark .group\/recent-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn,
-	.dark .group\/run-item:hover .sidebar-nav-btn,
-	.dark .group\/run-item:has(.sidebar-row-action[data-state="open"]) .sidebar-nav-btn {
+	.dark .group\/project-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.dark .group\/project-chat-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.dark .group\/recent-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.dark .group\/run-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn {
 		color: #fff !important;
 	}
 
@@ -579,19 +574,21 @@
 		@apply opacity-100 pointer-events-auto;
 	}
 	.sidebar-row-action-glyph {
-		@apply inline-flex size-6 items-center justify-center rounded-[10px] text-sidebar-foreground/55;
+		@apply inline-flex size-6 items-center justify-center rounded-full text-sidebar-foreground/55;
 	}
 
 	/* Branch picker chevron buttons sit beside action bar icon buttons
-	   (size-8, rounded-[10px]). Height + radius match for visual
+	   (size-8, rounded-full). Height + radius match for visual
 	   alignment, but width is tighter so the small chevron glyph reads
 	   as a compact control rather than a full-size icon button. */
 	.aui-branch-chevron-btn {
-		@apply inline-flex h-8 w-6 cursor-pointer items-center justify-center rounded-[10px] p-0 text-chat-icon-fg transition-colors hover:bg-chat-icon-bg-hover hover:text-chat-icon-fg-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-30 disabled:hover:bg-transparent;
+		@apply inline-flex h-8 w-6 cursor-pointer items-center justify-center rounded-full p-0 text-chat-icon-fg transition-colors hover:bg-chat-icon-bg-hover hover:text-chat-icon-fg-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-30 disabled:hover:bg-transparent;
 	}
 	.sidebar-row-action:hover .sidebar-row-action-glyph,
 	.sidebar-row-action[data-state="open"] .sidebar-row-action-glyph {
-		@apply bg-nav-surface-hover text-nav-fg;
+		@apply text-nav-fg;
+		/* A step darker than the row hover so the circle reads on top of it. */
+		background-color: color-mix(in srgb, var(--foreground) 11%, transparent);
 	}
 	.dark .sidebar-row-action:hover .sidebar-row-action-glyph,
 	.dark .sidebar-row-action[data-state="open"] .sidebar-row-action-glyph {
@@ -752,7 +749,13 @@
 	   visually anchored to its trigger rather than reading as a much
 	   larger floating pill. */
 	.tooltip-compact {
-		@apply rounded-[10px] border-transparent bg-black px-2 py-1.5 text-[11px] font-medium leading-snug text-white shadow-md;
+		@apply rounded-full border-transparent bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug text-white shadow-md;
+	}
+
+	/* Dialog popups: borderless; chatbox shadow in light, flat card
+	   surface in dark. */
+	.dialog-soft-surface {
+		@apply border-0 ring-0 bg-background/98 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:bg-card dark:shadow-none;
 	}
 
 	/* Rich tooltip — used for the context-usage and token-counter
@@ -1023,6 +1026,12 @@
 		@apply flex cursor-pointer items-center gap-1.5 rounded-full py-1.5 pl-2 pr-2.5 text-[14px] font-medium text-muted-foreground/70 transition-colors hover:bg-primary/10 dark:hover:bg-white/[0.1] disabled:cursor-not-allowed disabled:opacity-40;
 	}
 
+	/* Caret pills (RAG, MCP): the chevron carries its own whitespace, so the
+	   trailing padding is tightened to keep the hover pill balanced. */
+	.composer-pill-btn:has(.composer-pill-caret) {
+		@apply pr-1.5;
+	}
+
 	/* Icon-only (compact) pills drop their label, so make the button a square
 	   and center the glyph; the rounded-full hover highlight then reads as a
 	   circle around the icon rather than a wide rounded rectangle. */
@@ -1068,6 +1077,32 @@
 		@apply size-[15px] bg-transparent p-0 dark:bg-transparent;
 	}
 
+	/* Compact pills hide their labels, so surface the name as a hover
+	   tooltip styled like .tooltip-compact. */
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label])[data-pill-label] {
+		position: relative;
+	}
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label])[data-pill-label]:hover::after {
+		content: attr(data-pill-label);
+		@apply pointer-events-none absolute bottom-[calc(100%+6px)] left-1/2 z-50 -translate-x-1/2 rounded-full bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug whitespace-nowrap text-white shadow-md;
+	}
+
+	/* Compact caret pills (RAG, MCP) open their menu on click instead of
+	   toggling off, so keep the icon and skip the X swap. */
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label]):has(.composer-pill-caret)[data-active="true"]:hover
+		.composer-pill-glyph
+		> :not(.composer-pill-x) {
+		opacity: 1;
+	}
+	[data-pill-compact="true"]
+		.composer-pill-btn:not([data-keep-label]):has(.composer-pill-caret)
+		.composer-pill-x {
+		display: none;
+	}
+
 	/* Hovering an active pill swaps the icon for an X (click to turn off). */
 	.composer-pill-btn[data-active="true"]:hover .composer-pill-glyph > :not(.composer-pill-x),
 	.unsloth-thinking-pill[data-active="true"]:hover .composer-pill-glyph > :not(.composer-pill-x) {

From cae12b793f13a40cd5cd02e1699cf646c181161d Mon Sep 17 00:00:00 2001
From: Eyera <hauzin@hotmail.com>
Date: Wed, 10 Jun 2026 19:04:17 +0200
Subject: [PATCH 165/222] feat(hub): enable Run/New Chat for downloaded GGUF
 models, fix README (#6152)

* feat(hub): enable Run/New Chat for downloaded GGUF models, fix README bottom spacing

- enable the Run / New Chat action for GGUF models that are already downloaded, across the download card, on-device card, and hub page
- remove the extra bottom spacing under the model inspector README

* fix(hub): sync active GGUF variant on mount

* feat(hub): open a new chat immediately when Run is clicked

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/frontend/src/features/chat/index.ts    |  1 +
 .../hub/catalog/gguf-download-card.tsx        |  5 +-
 .../hub/catalog/local-on-device-card.tsx      | 11 ++-
 .../features/hub/catalog/model-inspector.tsx  |  2 -
 studio/frontend/src/features/hub/hub-page.tsx | 99 ++++++++++++++-----
 .../src/features/hub/lib/hub-feature-flags.ts |  5 +-
 6 files changed, 84 insertions(+), 39 deletions(-)

diff --git a/studio/frontend/src/features/chat/index.ts b/studio/frontend/src/features/chat/index.ts
index bfaf29f519..dde3a75475 100644
--- a/studio/frontend/src/features/chat/index.ts
+++ b/studio/frontend/src/features/chat/index.ts
@@ -19,6 +19,7 @@ export {
 export { useChatRuntimeStore } from "./stores/chat-runtime-store";
 export { useChatSearchStore } from "./stores/chat-search-store";
 export { useChatModelRuntime } from "./hooks/use-chat-model-runtime";
+export { isExternalModelId } from "./external-providers";
 export { ChatSearchDialog } from "./components/chat-search-dialog";
 export { setTrainingCompareHandoff } from "./lib/training-compare-handoff";
 export type { ProjectRecord } from "./types";
diff --git a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
index 72743af722..e0178c3472 100644
--- a/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/gguf-download-card.tsx
@@ -20,7 +20,7 @@ import {
 import { type GgufVariantDetail, deleteCachedModel } from "../inventory";
 import { formatBytes } from "../lib/format";
 import { type GgufFitClass, classifyGgufFit } from "../lib/gguf-fit";
-import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import { HUB_GGUF_RUN_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
 import {
   ggufVariantsMatch,
   normalizeGgufVariantIdentity,
@@ -794,8 +794,7 @@ export function GgufDownloadCard({
             downloadingThisVariant &&
               !cancelling &&
               "hover:bg-rose-500/10 hover:text-rose-600 dark:hover:text-rose-400",
-            // Hide post-download CTAs (Run / New Chat) for this PR.
-            !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE &&
+            !HUB_GGUF_RUN_ACTIONS_VISIBLE &&
               !downloadingThisVariant &&
               !cancelling &&
               !isLoadingThisModel &&
diff --git a/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
index 9b3d401b99..0dd50f0a41 100644
--- a/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
+++ b/studio/frontend/src/features/hub/catalog/local-on-device-card.tsx
@@ -2,7 +2,10 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { TrainIcon } from "../components/train-icon";
-import { HUB_POST_DOWNLOAD_ACTIONS_VISIBLE } from "../lib/hub-feature-flags";
+import {
+  HUB_GGUF_RUN_ACTIONS_VISIBLE,
+  HUB_POST_DOWNLOAD_ACTIONS_VISIBLE,
+} from "../lib/hub-feature-flags";
 import {
   Popover,
   PopoverContent,
@@ -295,6 +298,9 @@ export function LocalOnDeviceCard({
   const formatTone =
     modelFormat === "adapter" ? "adapter" : isGguf ? "gguf" : "checkpoint";
   const showOldCacheHint = source === "hf_cache" && !!unsupportedReason;
+  const runActionsVisible = isGguf
+    ? HUB_GGUF_RUN_ACTIONS_VISIBLE
+    : HUB_POST_DOWNLOAD_ACTIONS_VISIBLE;
 
   return (
     <div className="flex w-full flex-col gap-2">
@@ -440,11 +446,10 @@ export function LocalOnDeviceCard({
               className="ml-1 mr-0 h-5 w-px shrink-0 bg-foreground/[0.06] opacity-100 transition-opacity duration-150 group-hover/dl:opacity-0 dark:bg-white/[0.04]"
             />
           )}
-          {/* Run + Train pair hidden until Hub->chat/train pickers ship. */}
           <div
             className={cn(
               "group/pair flex h-9 shrink-0 items-stretch gap-1.5",
-              !HUB_POST_DOWNLOAD_ACTIONS_VISIBLE && "hidden",
+              !runActionsVisible && "hidden",
             )}
           >
             {onTrain && (
diff --git a/studio/frontend/src/features/hub/catalog/model-inspector.tsx b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
index 54165aa5e6..a3a73f2714 100644
--- a/studio/frontend/src/features/hub/catalog/model-inspector.tsx
+++ b/studio/frontend/src/features/hub/catalog/model-inspector.tsx
@@ -725,8 +725,6 @@ export const ModelInspector = memo(function ModelInspector({
           />
         )}
       </div>
-
-      <div aria-hidden="true" className="h-3 shrink-0" />
     </div>
   );
 });
diff --git a/studio/frontend/src/features/hub/hub-page.tsx b/studio/frontend/src/features/hub/hub-page.tsx
index 5b7fc4ad77..7324bed262 100644
--- a/studio/frontend/src/features/hub/hub-page.tsx
+++ b/studio/frontend/src/features/hub/hub-page.tsx
@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-// Hub page: browse + download surface only. Train CTA hidden until Hub->train picker ships.
 import { useHubInventory } from "@/features/hub/inventory";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
 import { useGpuInfo } from "@/hooks/use-gpu-info";
@@ -12,9 +11,15 @@ import {
 import { useOnlineStatus } from "@/features/hub/hooks/use-online-status";
 import { useIsHubDesktop } from "@/features/hub/hooks/use-is-hub-desktop";
 import { useHubInfiniteScroll } from "@/features/hub/hooks/use-hub-infinite-scroll";
-import { modelIdsMatch } from "@/features/hub/lib/model-identity";
+import { ggufVariantsMatch, modelIdsMatch } from "@/features/hub/lib/model-identity";
 import { cn } from "@/lib/utils";
 import { useHfTokenStore } from "@/features/hub/stores/hf-token-store";
+import {
+  getInferenceStatus,
+  isExternalModelId,
+  useChatModelRuntime,
+  useChatRuntimeStore,
+} from "@/features/chat";
 import { ArrowLeft01Icon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { useNavigate, useSearch } from "@tanstack/react-router";
@@ -179,14 +184,35 @@ export function ModelsPage() {
   const gpu = useGpuInfo();
   const online = useOnlineStatus();
 
-  // "Use in chat" just navigates to /chat; checkpoint/variant handoff lands with the Hub-aware picker.
-  const activeCheckpoint: string | null = null;
-  const activeGgufVariant: string | null = null;
-  // Stubs so the inspector + load-status memo still typecheck; cast keeps the shape from narrowing to `never`.
-  const loadingModel = null as { id: string } | null;
-  const loadProgress = null as {
-    phase?: "downloading" | "starting";
-  } | null;
+  const { selectModel, loadingModel, loadProgress, ejectModel } =
+    useChatModelRuntime();
+  const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
+  const activeCheckpoint =
+    checkpoint && !isExternalModelId(checkpoint) ? checkpoint : null;
+  const activeGgufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
+
+  useEffect(() => {
+    let cancelled = false;
+    void getInferenceStatus()
+      .then((status) => {
+        if (cancelled || !status.active_model) return;
+        const store = useChatRuntimeStore.getState();
+        if (
+          !isExternalModelId(store.params.checkpoint) &&
+          (!modelIdsMatch(store.params.checkpoint, status.active_model) ||
+            !ggufVariantsMatch(
+              store.activeGgufVariant,
+              status.gguf_variant ?? null,
+            ))
+        ) {
+          store.setCheckpoint(status.active_model, status.gguf_variant ?? null);
+        }
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, []);
 
   const { tab, setTab: setModelsTab } = useModelsTabState();
   const [query, setQuery] = useState("");
@@ -522,8 +548,8 @@ export function ModelsPage() {
   );
 
   const isLoadingThisModel = useMemo(() => {
-    if (!loadingModel) return false;
-    return selectedRepoMatchesRuntime(selectedModel, loadingModel.id, null);
+    if (!loadingModel || !selectedModel) return false;
+    return modelIdsMatch(loadingModel.id, selectedModel.resource.runId);
   }, [loadingModel, selectedModel]);
 
   const { vramInfo, minMemory } = useHubModelVram(selectedModel, gpu);
@@ -536,22 +562,41 @@ export function ModelsPage() {
       ? `${Math.floor(gpu.systemRamAvailableGb)} GB`
       : "Unavailable";
 
-  // Load / use-in-chat / train handlers are stubs; they wire in once the
-  // Hub-aware chat and train pickers ship.
+  const openNewChat = useCallback(() => {
+    void navigate({ to: "/chat", search: { new: crypto.randomUUID() } });
+  }, [navigate]);
+  const runSelectedModel = useCallback(
+    (opts: ModelLoadOptions, isDownloaded: boolean) => {
+      if (!selectedModel) return;
+      const runId = selectedModel.resource.runId;
+      void selectModel({
+        id: runId,
+        ggufVariant: opts.ggufVariant,
+        isDownloaded,
+        expectedBytes: opts.expectedBytes,
+        throwOnError: true,
+      })
+        .then(() => {
+          const store = useChatRuntimeStore.getState();
+          if (!modelIdsMatch(store.params.checkpoint, runId)) {
+            store.setCheckpoint(runId, opts.ggufVariant ?? null);
+          }
+        })
+        .catch(() => undefined);
+      openNewChat();
+    },
+    [openNewChat, selectModel, selectedModel],
+  );
   const handleLoad = useCallback(
-    (_opts: ModelLoadOptions) => undefined,
-    [],
+    (opts: ModelLoadOptions) =>
+      runSelectedModel(opts, selectedModel?.isDownloaded ?? true),
+    [runSelectedModel, selectedModel],
   );
   const handleLoadLocal = useCallback(
-    (_opts: ModelLoadOptions = {}) => undefined,
-    [],
+    (opts: ModelLoadOptions = {}) => runSelectedModel(opts, true),
+    [runSelectedModel],
   );
-  const handleUseInChat = useCallback(() => {
-    void navigate({ to: "/chat" });
-  }, [navigate]);
-  const handleTrain = useCallback(() => {
-    // Train CTA hidden until Hub->train picker ships.
-  }, []);
+  const handleTrain = useCallback(() => undefined, []);
 
   const inspectorRuntime = useMemo(
     () => ({
@@ -582,14 +627,14 @@ export function ModelsPage() {
     () => ({
       onLoad: handleLoad,
       onLoadLocal: handleLoadLocal,
-      onUseInChat: handleUseInChat,
+      onUseInChat: openNewChat,
       onTrain: handleTrain,
       onInventoryChange: refreshInventory,
     }),
     [
       handleLoad,
       handleLoadLocal,
-      handleUseInChat,
+      openNewChat,
       handleTrain,
       refreshInventory,
     ],
@@ -685,7 +730,7 @@ export function ModelsPage() {
           ramLabel={ramLabel}
           activeCheckpoint={activeCheckpoint}
           activeGgufVariant={activeGgufVariant}
-          onEject={() => undefined}
+          onEject={() => void ejectModel()}
         />
 
         <section className="elevated-card flex min-h-0 flex-1 flex-col overflow-hidden bg-card">
diff --git a/studio/frontend/src/features/hub/lib/hub-feature-flags.ts b/studio/frontend/src/features/hub/lib/hub-feature-flags.ts
index cf28403725..d0d527b720 100644
--- a/studio/frontend/src/features/hub/lib/hub-feature-flags.ts
+++ b/studio/frontend/src/features/hub/lib/hub-feature-flags.ts
@@ -1,8 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-// Hub feature flags for staged rollout. Each gates a CTA whose integration ships
-// in a later PR; JSX/wiring stay in place so flipping here is the only re-enable edit.
-
-// Post-download Run / chat / Train CTAs, hidden until the Hub-aware chat and train pickers ship.
 export const HUB_POST_DOWNLOAD_ACTIONS_VISIBLE = false;
+export const HUB_GGUF_RUN_ACTIONS_VISIBLE = true;

From dab0b77673abd28789fbbd5fba09dcf41402cea1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 10:04:26 -0700
Subject: [PATCH 166/222] Studio: in-app Update llama.cpp button to install the
 latest prebuilt (#6097)

Adds an in-app "Update llama.cpp" banner and button to Unsloth Studio. When the installed prebuilt is behind the latest published release, a non-invasive banner appears; clicking Update downloads the latest prebuilt for this host and swaps it in place in the background, with no restart.

Detection reuses the freshness check from #5529. The update re-runs install_llama_prebuilt.py the same way setup.sh and setup.ps1 do after #5963: it forwards the published repo and the AMD gfx target derived from the install marker, and does not pass the removed --simple-policy or the arm64-only --cpu-fallback.

While the installer swaps binaries the backend enters a maintenance state (flag set under the serial load lock, active server unloaded) so a concurrent load cannot start a server from a half-swapped binary; the next load uses the new build. The banner also handles refused responses and jobs started in another tab so it never sticks on "Updating...".

Verified end to end on an NVIDIA B200: installed b9493, detected the update, applied it, and confirmed the binary at the same path advanced to b9585 in the same process. Hermetic backend tests and the frontend type-check pass.
---
 studio/backend/core/inference/llama_cpp.py    |   7 +
 studio/backend/main.py                        |   2 +
 studio/backend/routes/llama.py                |  75 +++
 studio/backend/tests/test_desktop_auth.py     |   4 +
 studio/backend/tests/test_llama_cpp_update.py | 444 ++++++++++++++++++
 studio/backend/utils/llama_cpp_update.py      | 317 +++++++++++++
 studio/frontend/src/app/provider.tsx          |  18 +-
 .../src/components/llama-update-banner.tsx    | 109 +++++
 .../src/hooks/use-llama-update-check.ts       | 236 ++++++++++
 9 files changed, 1211 insertions(+), 1 deletion(-)
 create mode 100644 studio/backend/routes/llama.py
 create mode 100644 studio/backend/tests/test_llama_cpp_update.py
 create mode 100644 studio/backend/utils/llama_cpp_update.py
 create mode 100644 studio/frontend/src/components/llama-update-banner.tsx
 create mode 100644 studio/frontend/src/hooks/use-llama-update-check.ts

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 3c582a695f..e608a4b552 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -719,6 +719,9 @@ class LlamaCppBackend:
         # Wraps load_model() end-to-end so concurrent loads serialise and never
         # coexist as two llama-server processes (#5401).
         self._serial_load_lock = threading.Lock()
+        # Set by the in-app updater while it swaps prebuilt binaries; load_model()
+        # rejects fast so no server starts from a half-swapped binary.
+        self._llama_update_in_progress = False
         # Last extra_args / requested n_ctx, preserved across unload so the chat
         # UI's /unload+/load Apply path can inherit them (#5401).
         # ``_extra_args_source`` records the (model_identifier, hf_variant) the
@@ -2806,6 +2809,10 @@ class LlamaCppBackend:
         # Serialise the whole load so concurrent /load calls never leave two
         # llama-server processes alive (#5401 / #5161). Doesn't block /unload.
         with self._serial_load_lock:
+            # In-app update swapping binaries: refuse fast (set under this lock,
+            # so any in-flight load has drained) instead of using a half-swapped one.
+            if getattr(self, "_llama_update_in_progress", False):
+                raise RuntimeError("llama.cpp is updating; try again in a moment.")
             # Duplicate /load that raced past the route check: do nothing if the
             # live server already satisfies this request.
             if self._already_in_target_state(
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 74a7dbc8c5..dc3d802b78 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -266,6 +266,7 @@ from routes import (
     training_history_router,
     training_router,
 )
+from routes.llama import router as llama_router
 from hub.routes import (
     inventory_router as hub_inventory_router,
     datasets_router as hub_datasets_router,
@@ -804,6 +805,7 @@ app.include_router(mcp_servers_router, prefix = "/api/mcp/servers", tags = ["mcp
 app.include_router(prompts_router, prefix = "/api/prompts", tags = ["prompts"])
 app.include_router(datasets_router, prefix = "/api/datasets", tags = ["datasets"])
 app.include_router(data_recipe_router, prefix = "/api/data-recipe", tags = ["data-recipe"])
+app.include_router(llama_router, prefix = "/api/llama", tags = ["llama"])
 app.include_router(export_router, prefix = "/api/export", tags = ["export"])
 app.include_router(rag_router, prefix = "/api/rag", tags = ["rag"])
 app.include_router(training_history_router, prefix = "/api/train", tags = ["training-history"])
diff --git a/studio/backend/routes/llama.py b/studio/backend/routes/llama.py
new file mode 100644
index 0000000000..11cc4c798e
--- /dev/null
+++ b/studio/backend/routes/llama.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""llama.cpp prebuilt update endpoints.
+
+GET  /api/llama/update-status  -> is a newer prebuilt available + job state
+POST /api/llama/update         -> download + atomically swap to the latest
+
+Detection reuses utils.llama_cpp_freshness; the swap reuses
+install_llama_prebuilt.py via utils.llama_cpp_update. Both fail open so the UI
+never blocks on a missing marker / offline GitHub.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel, Field
+
+from auth.authentication import get_current_subject
+from utils.llama_cpp_update import get_update_status, start_update
+
+router = APIRouter()
+
+
+class LlamaUpdateJob(BaseModel):
+    state: str = Field("idle", description = "idle | running | success | error")
+    message: str = ""
+    from_tag: Optional[str] = None
+    to_tag: Optional[str] = None
+    error: Optional[str] = None
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+
+
+class LlamaUpdateStatusResponse(BaseModel):
+    supported: bool = Field(
+        False,
+        description = "True when the install came from an Unsloth prebuilt (has a marker).",
+    )
+    update_available: bool = Field(False, description = "True when installed_tag != latest_tag.")
+    stale: bool = Field(
+        False, description = "Update available AND install older than the staleness threshold."
+    )
+    installed_tag: Optional[str] = None
+    latest_tag: Optional[str] = None
+    published_repo: Optional[str] = None
+    installed_at_utc: Optional[str] = None
+    age_days: Optional[int] = None
+    job: LlamaUpdateJob = Field(default_factory = LlamaUpdateJob)
+
+
+class LlamaUpdateActionResponse(BaseModel):
+    started: bool
+    reason: Optional[str] = None
+    message: Optional[str] = None
+    job: LlamaUpdateJob = Field(default_factory = LlamaUpdateJob)
+
+
+@router.get("/update-status", response_model = LlamaUpdateStatusResponse)
+async def llama_update_status(
+    force_refresh: bool = Query(
+        False, description = "Bypass the 24h release cache for an explicit check."
+    ),
+    current_subject: str = Depends(get_current_subject),
+) -> LlamaUpdateStatusResponse:
+    return LlamaUpdateStatusResponse(**get_update_status(force_refresh = force_refresh))
+
+
+@router.post("/update", response_model = LlamaUpdateActionResponse)
+async def llama_update(
+    current_subject: str = Depends(get_current_subject),
+) -> LlamaUpdateActionResponse:
+    return LlamaUpdateActionResponse(**start_update())
diff --git a/studio/backend/tests/test_desktop_auth.py b/studio/backend/tests/test_desktop_auth.py
index 50bd0e89d7..b4b39ba1a9 100644
--- a/studio/backend/tests/test_desktop_auth.py
+++ b/studio/backend/tests/test_desktop_auth.py
@@ -419,6 +419,8 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
     routes_module.__path__ = []
     settings_module = ModuleType("routes.settings")
     settings_module.router = APIRouter()
+    llama_module = ModuleType("routes.llama")
+    llama_module.router = APIRouter()
     prompts_module = ModuleType("routes.prompts")
     prompts_module.router = APIRouter()
 
@@ -440,9 +442,11 @@ def test_health_response_reports_desktop_capability_fields(monkeypatch):
     }.items():
         setattr(routes_module, name, router)
     routes_module.settings = settings_module
+    routes_module.llama = llama_module
 
     monkeypatch.setitem(sys.modules, "routes", routes_module)
     monkeypatch.setitem(sys.modules, "routes.settings", settings_module)
+    monkeypatch.setitem(sys.modules, "routes.llama", llama_module)
     monkeypatch.setitem(sys.modules, "routes.prompts", prompts_module)
 
     import studio.backend.main as backend_main
diff --git a/studio/backend/tests/test_llama_cpp_update.py b/studio/backend/tests/test_llama_cpp_update.py
new file mode 100644
index 0000000000..d2c854cdee
--- /dev/null
+++ b/studio/backend/tests/test_llama_cpp_update.py
@@ -0,0 +1,444 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hermetic tests for the in-app llama.cpp update orchestration.
+
+No network, no real install: the GitHub release lookup and the installer
+subprocess are both monkeypatched. Verifies detection (update_available) and
+the apply flow (job lifecycle, installer invocation, post-swap re-read).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parents[1]
+if str(_BACKEND) not in sys.path:
+    sys.path.insert(0, str(_BACKEND))
+
+import utils.llama_cpp_freshness as freshness  # noqa: E402
+import utils.llama_cpp_update as upd  # noqa: E402
+
+MARKER = "UNSLOTH_PREBUILT_INFO.json"
+
+
+def _write_install(
+    dir_: Path,
+    tag: str,
+    repo: str = "unslothai/llama.cpp",
+    asset: str | None = None,
+) -> str:
+    """Create a fake prebuilt install tree and return the llama-server path.
+
+    ``asset`` is the bundle filename recorded in the marker; omit it to model an
+    older marker that predates asset-based ROCm forwarding (backward compat)."""
+    bin_dir = dir_ / "build" / "bin"
+    bin_dir.mkdir(parents = True, exist_ok = True)
+    binary = bin_dir / "llama-server"
+    binary.write_text("#!/bin/sh\necho stub\n")
+    marker = {
+        "tag": tag,
+        "release_tag": tag,
+        "published_repo": repo,
+        "installed_at_utc": "2020-01-01T00:00:00Z",
+        "bundle_profile": "cuda13-newer",
+        "runtime_line": "cuda13",
+    }
+    if asset is not None:
+        marker["asset"] = asset
+    (dir_ / MARKER).write_text(json.dumps(marker))
+    return str(binary)
+
+
+@pytest.fixture(autouse = True)
+def _clean_state(monkeypatch):
+    freshness.reset_caches()
+    upd._reset_job_for_tests()
+    # Never hit the network in these tests.
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: None)
+    yield
+    freshness.reset_caches()
+    upd._reset_job_for_tests()
+
+
+def test_status_no_marker(monkeypatch, tmp_path):
+    binary = tmp_path / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")  # no marker file alongside
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    st = upd.get_update_status()
+    assert st["supported"] is False
+    assert st["update_available"] is False
+    assert st["installed_tag"] is None
+
+
+def test_status_update_available(monkeypatch, tmp_path):
+    binary = _write_install(tmp_path, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+    st = upd.get_update_status(force_refresh = True)
+    assert st["supported"] is True
+    assert st["installed_tag"] == "b9493"
+    assert st["latest_tag"] == "b9518"
+    assert st["update_available"] is True
+
+
+def test_status_up_to_date(monkeypatch, tmp_path):
+    binary = _write_install(tmp_path, "b9518")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+    st = upd.get_update_status(force_refresh = True)
+    assert st["installed_tag"] == "b9518"
+    assert st["latest_tag"] == "b9518"
+    assert st["update_available"] is False
+
+
+def test_start_update_no_marker_refuses(monkeypatch, tmp_path):
+    binary = tmp_path / "llama-server"
+    binary.write_text("stub")  # no marker
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    res = upd.start_update()
+    assert res["started"] is False
+    assert res["reason"] == "no_prebuilt_marker"
+
+
+def test_start_update_happy_path(monkeypatch, tmp_path):
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+
+    captured = {}
+
+    class _Proc:
+        returncode = 0
+        stdout = "installed"
+        stderr = ""
+
+    def _fake_run(cmd, **kwargs):
+        captured["cmd"] = cmd
+        # Simulate the installer writing a new marker with the latest tag.
+        _write_install(install_dir, "b9518")
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+
+    res = upd.start_update()
+    assert res["started"] is True
+    assert res["job"]["from_tag"] == "b9493"
+
+    # Wait for the background worker.
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        job = upd.get_update_status()["job"]
+        if job["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    assert job["state"] == "success", job
+    assert job["to_tag"] == "b9518"
+    # Installer was invoked with the resolved install dir + latest + repo.
+    assert "--install-dir" in captured["cmd"]
+    assert str(install_dir) in captured["cmd"]
+    assert "--llama-tag" in captured["cmd"] and "latest" in captured["cmd"]
+    assert "unslothai/llama.cpp" in captured["cmd"]
+
+
+def test_start_update_installer_failure_reports_error(monkeypatch, tmp_path):
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+
+    class _Proc:
+        returncode = 2
+        stdout = ""
+        stderr = "boom: network error"
+
+    monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+
+    res = upd.start_update()
+    assert res["started"] is True
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        job = upd.get_update_status()["job"]
+        if job["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    assert job["state"] == "error"
+    assert "boom" in (job["error"] or "")
+
+
+# --- installer-argument construction (mirrors the post-#5963 setup scripts) ---
+
+
+def test_rocm_install_args_lemonade_gfx():
+    # Lemonade HIP app bundle: gfx family lives in the asset name.
+    assert upd._rocm_install_args("app-b9585-linux-x64-rocm-gfx110X.tar.gz") == [
+        "--rocm-gfx",
+        "gfx110x",
+    ]
+    assert upd._rocm_install_args("app-b9585-windows-x64-rocm-gfx1150.zip") == [
+        "--rocm-gfx",
+        "gfx1150",
+    ]
+
+
+def test_rocm_install_args_fork_version_bundle():
+    # Fork ROCm bundles encode a ROCm version, not a gfx -> forward --has-rocm.
+    assert upd._rocm_install_args("llama-b9334-bin-ubuntu-rocm-6.4-x64.tar.gz") == ["--has-rocm"]
+
+
+def test_rocm_install_args_windows_hip():
+    assert upd._rocm_install_args("llama-b9334-bin-win-hip-radeon-x64.zip") == ["--has-rocm"]
+
+
+def test_rocm_install_args_non_rocm_and_missing():
+    assert upd._rocm_install_args("llama-b9334-bin-ubuntu-x64.tar.gz") == []
+    assert upd._rocm_install_args("app-b9585-linux-x64-cuda13.tar.gz") == []
+    assert upd._rocm_install_args(None) == []
+
+
+def _capture_install_cmd(
+    monkeypatch,
+    tmp_path,
+    *,
+    tag = "b9493",
+    repo = "unslothai/llama.cpp",
+    asset = None,
+    latest = "b9518",
+) -> list:
+    """Run start_update() with the installer subprocess stubbed; return the argv."""
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, tag, repo = repo, asset = asset)
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: latest)
+
+    captured = {}
+
+    class _Proc:
+        returncode = 0
+        stdout = "installed"
+        stderr = ""
+
+    def _fake_run(cmd, **kwargs):
+        captured["cmd"] = list(cmd)
+        _write_install(install_dir, latest, repo = repo, asset = asset)
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+
+    res = upd.start_update()
+    assert res["started"] is True, res
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        if upd.get_update_status()["job"]["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    return captured.get("cmd", [])
+
+
+def test_install_cmd_rocm_marker_forwards_gfx(monkeypatch, tmp_path):
+    cmd = _capture_install_cmd(
+        monkeypatch, tmp_path, asset = "app-b9585-linux-x64-rocm-gfx110X.tar.gz"
+    )
+    assert "--rocm-gfx" in cmd
+    assert cmd[cmd.index("--rocm-gfx") + 1] == "gfx110x"
+    assert "--has-rocm" not in cmd
+    assert "--cpu-fallback" not in cmd
+    assert "--simple-policy" not in cmd
+    assert "--published-repo" in cmd and "unslothai/llama.cpp" in cmd
+
+
+def test_install_cmd_fork_rocm_marker_forwards_has_rocm(monkeypatch, tmp_path):
+    cmd = _capture_install_cmd(
+        monkeypatch, tmp_path, asset = "llama-b9334-bin-ubuntu-rocm-6.4-x64.tar.gz"
+    )
+    assert "--has-rocm" in cmd
+    assert "--rocm-gfx" not in cmd
+
+
+def test_install_cmd_ggml_cpu_marker_has_no_cpu_fallback(monkeypatch, tmp_path):
+    # CPU installs come from ggml-org. Re-running into the same install-dir/repo
+    # reproduces the same CPU bundle; --cpu-fallback (which force-drops GPU
+    # detection) is reserved for setup.sh's arm64 rescue and must not appear here.
+    cmd = _capture_install_cmd(
+        monkeypatch,
+        tmp_path,
+        repo = "ggml-org/llama.cpp",
+        asset = "llama-b9334-bin-ubuntu-x64.tar.gz",
+    )
+    assert "--cpu-fallback" not in cmd
+    assert "--rocm-gfx" not in cmd
+    assert "--has-rocm" not in cmd
+    assert "--simple-policy" not in cmd
+    assert "--published-repo" in cmd and "ggml-org/llama.cpp" in cmd
+
+
+def test_install_cmd_cuda_marker_minimal_and_backward_compatible(monkeypatch, tmp_path):
+    # Marker without an asset field (older install): no ROCm flags, no crash, and
+    # never the obsolete --simple-policy that #5963 removed from setup.
+    cmd = _capture_install_cmd(monkeypatch, tmp_path, asset = None)
+    assert "--simple-policy" not in cmd
+    assert "--rocm-gfx" not in cmd
+    assert "--has-rocm" not in cmd
+    assert "--cpu-fallback" not in cmd
+
+
+# --- refusal + maintenance-state coordination ---
+
+
+def test_start_update_already_running_refuses(monkeypatch, tmp_path):
+    binary = _write_install(tmp_path / "llama.cpp", "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    with upd._job_lock:
+        upd._job.update(state = upd._JOB_RUNNING)
+    res = upd.start_update()
+    assert res["started"] is False
+    assert res["reason"] == "already_running"
+
+
+def test_start_update_installer_missing_refuses(monkeypatch, tmp_path):
+    binary = _write_install(tmp_path / "llama.cpp", "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: None)
+    res = upd.start_update()
+    assert res["started"] is False
+    assert res["reason"] == "installer_missing"
+
+
+class _FakeBackend:
+    """Minimal stand-in for LlamaCppBackend's update-coordination surface."""
+
+    def __init__(self):
+        import threading
+
+        self._serial_load_lock = threading.Lock()
+        self._llama_update_in_progress = False
+        self.is_active = True
+        self.unloaded = False
+
+    def unload_model(self):
+        self.unloaded = True
+
+
+def _inject_backend(monkeypatch, backend):
+    routes_pkg = ModuleType("routes")
+    routes_pkg.__path__ = []
+    inference_mod = ModuleType("routes.inference")
+    inference_mod.get_llama_cpp_backend = lambda: backend
+    monkeypatch.setitem(sys.modules, "routes", routes_pkg)
+    monkeypatch.setitem(sys.modules, "routes.inference", inference_mod)
+
+
+def test_update_sets_maintenance_flag_and_unloads(monkeypatch, tmp_path):
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+
+    backend = _FakeBackend()
+    _inject_backend(monkeypatch, backend)
+
+    seen = {}
+
+    class _Proc:
+        returncode = 0
+        stdout = "ok"
+        stderr = ""
+
+    def _fake_run(cmd, **kwargs):
+        # The maintenance flag must be set while the installer runs.
+        seen["flag_during_install"] = backend._llama_update_in_progress
+        _write_install(install_dir, "b9518")
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+
+    res = upd.start_update()
+    assert res["started"] is True
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        if upd.get_update_status()["job"]["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+
+    assert backend.unloaded is True
+    assert seen.get("flag_during_install") is True
+    # Cleared in the finally so model loads work again after the swap.
+    assert backend._llama_update_in_progress is False
+
+
+def test_update_clears_maintenance_flag_on_installer_failure(monkeypatch, tmp_path):
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+
+    backend = _FakeBackend()
+    _inject_backend(monkeypatch, backend)
+
+    class _Proc:
+        returncode = 1
+        stdout = ""
+        stderr = "boom"
+
+    monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+
+    res = upd.start_update()
+    assert res["started"] is True
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        if upd.get_update_status()["job"]["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    assert upd.get_update_status()["job"]["state"] == "error"
+    assert backend._llama_update_in_progress is False
+
+
+def test_update_fails_open_when_backend_unavailable(monkeypatch, tmp_path):
+    install_dir = tmp_path / "llama.cpp"
+    binary = _write_install(install_dir, "b9493")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+
+    def _raise():
+        raise RuntimeError("no backend")
+
+    inference_mod = ModuleType("routes.inference")
+    inference_mod.get_llama_cpp_backend = lambda: _raise()
+    routes_pkg = ModuleType("routes")
+    routes_pkg.__path__ = []
+    monkeypatch.setitem(sys.modules, "routes", routes_pkg)
+    monkeypatch.setitem(sys.modules, "routes.inference", inference_mod)
+
+    class _Proc:
+        returncode = 0
+        stdout = "ok"
+        stderr = ""
+
+    def _fake_run(cmd, **kwargs):
+        _write_install(install_dir, "b9518")
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+
+    res = upd.start_update()
+    assert res["started"] is True
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        job = upd.get_update_status()["job"]
+        if job["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    assert job["state"] == "success", job
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
new file mode 100644
index 0000000000..19946b7966
--- /dev/null
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -0,0 +1,317 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""In-app llama.cpp prebuilt update.
+
+Builds on utils.llama_cpp_freshness (which detects whether a newer prebuilt
+release exists) and adds the *apply* half: run install_llama_prebuilt.py to
+download the newest bundle for this host and atomically swap it in place, so
+the next model load uses it.
+
+Design notes:
+- Detection is delegated to check_prebuilt_freshness(). We surface an
+  ``update_available`` flag (installed_tag != latest_tag) which is laxer than
+  freshness' ``stale`` (which additionally requires the install to be >= 3 days
+  old). The UI shows the "Update llama.cpp" affordance on update_available.
+- The install is slow (download + extract + validate), so it runs on a daemon
+  thread; callers poll get_update_status() for the job state.
+- Everything fails open: a missing marker / offline GitHub / source build just
+  reports update_available=False and never blocks the app.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+import structlog
+
+from utils.llama_cpp_freshness import (
+    _INSTALL_MARKER_NAME,
+    check_prebuilt_freshness,
+    latest_published_release,
+    read_install_marker,
+    reset_caches,
+)
+
+logger = structlog.get_logger(__name__)
+
+DEFAULT_PUBLISHED_REPO = "unslothai/llama.cpp"
+_INSTALL_TIMEOUT_SECONDS = 1800  # 30 min ceiling for download + build/validate
+
+# Background job state. Single in-flight update at a time, guarded by _job_lock.
+_JOB_IDLE = "idle"
+_JOB_RUNNING = "running"
+_JOB_SUCCESS = "success"
+_JOB_ERROR = "error"
+
+_job_lock = threading.Lock()
+_job: dict = {
+    "state": _JOB_IDLE,
+    "message": "",
+    "from_tag": None,
+    "to_tag": None,
+    "error": None,
+    "started_at": None,
+    "finished_at": None,
+}
+
+
+def _utcnow() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _find_binary() -> Optional[str]:
+    """Locate the active llama-server binary via the inference backend's own
+    resolver, so update targets exactly what Studio runs. Lazy import keeps the
+    heavy inference module off this module's import path."""
+    try:
+        from core.inference.llama_cpp import LlamaCppBackend
+        return LlamaCppBackend._find_llama_server_binary()
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("llama update: binary discovery failed", error = str(exc))
+        return None
+
+
+def _install_dir_for(binary_path: Optional[str]) -> Optional[Path]:
+    """The directory holding UNSLOTH_PREBUILT_INFO.json -- i.e. the install root
+    install_llama_prebuilt.py wrote and the one we re-install into. Walks up from
+    the binary the same way read_install_marker() does."""
+    if not binary_path:
+        return None
+    p = Path(binary_path)
+    for parent in p.parents[:5]:
+        if (parent / _INSTALL_MARKER_NAME).is_file():
+            return parent
+    return None
+
+
+def _installer_script() -> Optional[Path]:
+    """Locate install_llama_prebuilt.py. Honours UNSLOTH_LLAMA_INSTALLER, then
+    searches up from this file for both ``<root>/install_llama_prebuilt.py`` and
+    ``<root>/studio/install_llama_prebuilt.py`` so it works in the dev tree and
+    in an installed Studio layout."""
+    env = os.environ.get("UNSLOTH_LLAMA_INSTALLER")
+    if env and Path(env).is_file():
+        return Path(env)
+    here = Path(__file__).resolve()
+    for up in here.parents:
+        for cand in (up / "install_llama_prebuilt.py", up / "studio" / "install_llama_prebuilt.py"):
+            if cand.is_file():
+                return cand
+    return None
+
+
+def get_update_status(*, force_refresh: bool = False) -> dict:
+    """Report whether a newer prebuilt exists plus the current job state.
+
+    force_refresh bypasses the 24h release cache for an explicit "check now".
+    """
+    binary = _find_binary()
+    marker = read_install_marker(binary)
+    repo = (marker or {}).get("published_repo") or DEFAULT_PUBLISHED_REPO
+
+    if force_refresh and repo:
+        # Prime the cache so the freshness read below sees the newest tag.
+        try:
+            latest_published_release(repo, force_refresh = True)
+        except Exception as exc:  # pragma: no cover - network defensive
+            logger.debug("llama update: force refresh failed", error = str(exc))
+
+    freshness = check_prebuilt_freshness(binary)
+    installed = freshness.get("installed_tag")
+    latest = freshness.get("latest_tag")
+    update_available = bool(
+        freshness.get("has_marker") and installed and latest and installed != latest
+    )
+
+    with _job_lock:
+        job = dict(_job)
+
+    return {
+        "supported": bool(freshness.get("has_marker")),
+        "update_available": update_available,
+        "stale": bool(freshness.get("stale")),
+        "installed_tag": installed,
+        "latest_tag": latest,
+        "published_repo": freshness.get("published_repo") or repo,
+        "installed_at_utc": freshness.get("installed_at_utc"),
+        "age_days": freshness.get("age_days"),
+        "job": job,
+    }
+
+
+def _rocm_install_args(asset: Optional[str]) -> list[str]:
+    """Forward --rocm-gfx/--has-rocm from the marker asset, mirroring setup.sh.
+    The installer probe can miss the gfx arch on amd-smi-only hosts; lemonade
+    bundles carry the family in the name (rocm-gfx110X), fork bundles only rocm/hip."""
+    if not asset:
+        return []
+    low = asset.lower()
+    if "rocm" not in low and "hip" not in low:
+        return []
+    gfx = re.search(r"-gfx[0-9a-z]+", low)
+    if gfx:
+        # _normalize_forwarded_gfx accepts the family form (gfx110x -> gfx110X).
+        return ["--rocm-gfx", gfx.group(0).lstrip("-")]
+    return ["--has-rocm"]
+
+
+def _run_update(install_dir: Path, repo: str, asset: Optional[str], script: Path) -> None:
+    """Worker: put the backend into a maintenance state, run the installer for
+    the latest prebuilt, then refresh caches so the next load uses the new build."""
+    backend = None
+    model_was_active = False
+    try:
+        # Maintenance state so no load starts a server from the half-swapped binary
+        # (and the old binary is freed for the swap). Fails open without a backend.
+        try:
+            from routes.inference import get_llama_cpp_backend
+            backend = get_llama_cpp_backend()
+        except Exception as exc:
+            logger.debug(
+                "llama update: backend unavailable, skipping load coordination", error = str(exc)
+            )
+            backend = None
+
+        if backend is not None:
+            try:
+                with backend._serial_load_lock:
+                    backend._llama_update_in_progress = True
+                    # is_active covers the loading/unhealthy window is_loaded misses
+                    # (a live process also locks the exe on Windows during the swap).
+                    if getattr(backend, "is_active", False):
+                        model_was_active = True
+                        backend.unload_model()
+            except Exception as exc:
+                logger.debug("llama update: load coordination failed", error = str(exc))
+
+        cmd = [
+            sys.executable,
+            str(script),
+            "--install-dir",
+            str(install_dir),
+            "--llama-tag",
+            "latest",
+            "--published-repo",
+            repo,
+        ]
+        cmd.extend(_rocm_install_args(asset))
+        logger.info("llama update: installing", cmd = " ".join(cmd))
+        proc = subprocess.run(
+            cmd,
+            capture_output = True,
+            text = True,
+            timeout = _INSTALL_TIMEOUT_SECONDS,
+        )
+        if proc.returncode != 0:
+            tail = (proc.stderr or proc.stdout or "").strip()[-1500:]
+            raise RuntimeError(f"installer exited {proc.returncode}: {tail or 'no output'}")
+
+        # New UNSLOTH_PREBUILT_INFO.json is on disk; drop caches so the next
+        # status read reflects the freshly installed tag.
+        reset_caches()
+        new_marker = read_install_marker(_find_binary())
+        new_tag = (new_marker or {}).get("tag") or (new_marker or {}).get("release_tag")
+
+        with _job_lock:
+            _job.update(
+                state = _JOB_SUCCESS,
+                message = (
+                    f"Updated llama.cpp to {new_tag}."
+                    + (" Reload your model to use it." if model_was_active else "")
+                ),
+                to_tag = new_tag,
+                error = None,
+                finished_at = _utcnow(),
+            )
+        logger.info("llama update: success", to_tag = new_tag)
+    except Exception as exc:
+        logger.warning("llama update: failed", error = str(exc))
+        with _job_lock:
+            _job.update(
+                state = _JOB_ERROR,
+                message = "llama.cpp update failed.",
+                error = str(exc),
+                finished_at = _utcnow(),
+            )
+    finally:
+        # Lift the maintenance state so model loads work again, success or not.
+        if backend is not None:
+            try:
+                backend._llama_update_in_progress = False
+            except Exception:  # pragma: no cover - defensive
+                pass
+
+
+def start_update() -> dict:
+    """Kick off a background update. Idempotent: a second call while one is
+    running returns the in-flight job rather than starting another."""
+    binary = _find_binary()
+    install_dir = _install_dir_for(binary)
+    marker = read_install_marker(binary)
+    if install_dir is None or not marker:
+        return {
+            "started": False,
+            "reason": "no_prebuilt_marker",
+            "message": (
+                "This llama.cpp install was not provisioned from an Unsloth "
+                "prebuilt (source build or custom path); in-app update is "
+                "unavailable."
+            ),
+            "job": get_update_status()["job"],
+        }
+    script = _installer_script()
+    if script is None:
+        return {
+            "started": False,
+            "reason": "installer_missing",
+            "message": "install_llama_prebuilt.py could not be located.",
+            "job": get_update_status()["job"],
+        }
+    repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
+    from_tag = marker.get("tag") or marker.get("release_tag")
+    asset = marker.get("asset")
+
+    with _job_lock:
+        if _job["state"] == _JOB_RUNNING:
+            return {"started": False, "reason": "already_running", "job": dict(_job)}
+        _job.update(
+            state = _JOB_RUNNING,
+            message = "Downloading and installing the latest llama.cpp prebuilt...",
+            from_tag = from_tag,
+            to_tag = None,
+            error = None,
+            started_at = _utcnow(),
+            finished_at = None,
+        )
+        job_snapshot = dict(_job)
+
+    thread = threading.Thread(
+        target = _run_update,
+        args = (install_dir, repo, asset, script),
+        name = "llama-cpp-update",
+        daemon = True,
+    )
+    thread.start()
+    return {"started": True, "reason": None, "job": job_snapshot}
+
+
+def _reset_job_for_tests() -> None:
+    """Test-only: return the job tracker to idle."""
+    with _job_lock:
+        _job.update(
+            state = _JOB_IDLE,
+            message = "",
+            from_tag = None,
+            to_tag = None,
+            error = None,
+            started_at = None,
+            finished_at = None,
+        )
diff --git a/studio/frontend/src/app/provider.tsx b/studio/frontend/src/app/provider.tsx
index 25dbfdc780..91d99e238e 100644
--- a/studio/frontend/src/app/provider.tsx
+++ b/studio/frontend/src/app/provider.tsx
@@ -11,6 +11,7 @@ import {
 import { Toaster } from "@/components/ui/sonner";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { WebUpdateBanner } from "@/components/web/update-banner";
+import { LlamaUpdateBanner } from "@/components/llama-update-banner";
 import { DownloadManagerPanel } from "@/features/hub/download-manager";
 import { getTauriAuthFailure, tauriAutoAuth } from "@/features/auth";
 import { NativeIntentDrain } from "@/features/native-intents/native-intent-drain";
@@ -259,6 +260,7 @@ function TauriWrapper({ children }: { children: ReactNode }) {
         {children}
         <DownloadManagerPanel />
         <WebUpdateBanner enabled={!WEB_UPDATE_HIDDEN_ROUTES.has(pathname)} />
+        <LlamaUpdateBanner enabled={!WEB_UPDATE_HIDDEN_ROUTES.has(pathname)} />
       </>
     );
   }
@@ -294,7 +296,18 @@ function TauriWrapper({ children }: { children: ReactNode }) {
     />
   );
 
-  if (!shouldUseCustomWindowTitlebar()) return content;
+  if (!shouldUseCustomWindowTitlebar()) {
+    // macOS desktop uses the native titlebar and returns here before the
+    // custom-titlebar branch, so mount the updater banner on this path too.
+    return (
+      <>
+        {content}
+        <LlamaUpdateBanner
+          enabled={showApp && !HIDDEN_TITLEBAR_SIDEBAR_ROUTES.has(pathname)}
+        />
+      </>
+    );
+  }
 
   const showSidebarSurface =
     showApp && !HIDDEN_TITLEBAR_SIDEBAR_ROUTES.has(pathname);
@@ -305,6 +318,9 @@ function TauriWrapper({ children }: { children: ReactNode }) {
       <div className="min-h-0 flex-1 overflow-hidden">
         {content}
       </div>
+      <LlamaUpdateBanner
+        enabled={showApp && !HIDDEN_TITLEBAR_SIDEBAR_ROUTES.has(pathname)}
+      />
     </div>
   );
 }
diff --git a/studio/frontend/src/components/llama-update-banner.tsx b/studio/frontend/src/components/llama-update-banner.tsx
new file mode 100644
index 0000000000..8919c24cc7
--- /dev/null
+++ b/studio/frontend/src/components/llama-update-banner.tsx
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { Button } from "@/components/ui/button";
+import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
+import { toast } from "@/lib/toast";
+import { AnimatePresence, motion } from "motion/react";
+import { type ReactElement } from "react";
+
+const EASE_OUT_QUART: [number, number, number, number] = [0.165, 0.84, 0.44, 1];
+
+interface LlamaUpdateBannerProps {
+  enabled?: boolean;
+}
+
+/**
+ * Non-invasive "Update llama.cpp" affordance. Appears bottom-right when a newer
+ * prebuilt is available, fades on its own after ~10s, and re-surfaces hourly.
+ * Clicking Update swaps the prebuilt in place via POST /api/llama/update.
+ */
+export function LlamaUpdateBanner({
+  enabled = true,
+}: LlamaUpdateBannerProps): ReactElement | null {
+  const { status, visible, applying, apply, dismiss } = useLlamaUpdateCheck({
+    enabled,
+  });
+
+  async function handleUpdate() {
+    const result = await apply();
+    if (result?.ok) {
+      toast.success(
+        `llama.cpp updated to ${result.tag ?? "the latest build"}. Reload your model to use it.`,
+      );
+    } else if (result) {
+      toast.error(`llama.cpp update failed: ${result.error ?? "unknown error"}`);
+    }
+  }
+
+  const show = visible && status != null && (status.update_available || applying);
+
+  return (
+    <AnimatePresence>
+      {show ? (
+        <motion.div
+          initial={{ opacity: 0, y: 12, scale: 0.96 }}
+          animate={{ opacity: 1, y: 0, scale: 1 }}
+          exit={{ opacity: 0, y: 8, scale: 0.97 }}
+          transition={{ duration: 0.35, ease: EASE_OUT_QUART }}
+          className="fixed bottom-4 right-4 z-[9998] w-[calc(100vw-2rem)] max-w-[340px]"
+          data-testid="llama-update-banner"
+        >
+          <div className="corner-squircle relative overflow-hidden border border-border/60 bg-background/95 px-4 py-3 shadow-lg backdrop-blur-md">
+            {!applying ? (
+              <button
+                type="button"
+                onClick={dismiss}
+                className="absolute top-2.5 right-2.5 flex size-5 items-center justify-center rounded-md text-muted-foreground/60 transition-colors hover:bg-muted hover:text-foreground"
+                aria-label="Dismiss llama.cpp update notification"
+              >
+                <svg
+                  aria-hidden="true"
+                  width="12"
+                  height="12"
+                  viewBox="0 0 14 14"
+                  fill="none"
+                  xmlns="http://www.w3.org/2000/svg"
+                >
+                  <path
+                    d="M11 3L3 11M3 3l8 8"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              </button>
+            ) : null}
+
+            <div className="flex items-center gap-2 pr-5">
+              <span className="text-base" aria-hidden="true">
+                🦥
+              </span>
+              <p className="text-sm font-medium text-foreground">
+                {applying ? "Updating llama.cpp..." : "New llama.cpp prebuilt"}
+              </p>
+            </div>
+            <p className="mt-0.5 pl-7 text-xs text-muted-foreground">
+              {status?.installed_tag ?? "unknown"} &rarr;{" "}
+              <span className="font-medium text-foreground">
+                {status?.latest_tag ?? ""}
+              </span>
+            </p>
+
+            <div className="mt-2.5 pl-7">
+              <Button
+                size="sm"
+                className="corner-squircle"
+                onClick={handleUpdate}
+                disabled={applying}
+                data-testid="llama-update-button"
+              >
+                {applying ? "Updating..." : "Update llama.cpp"}
+              </Button>
+            </div>
+          </div>
+        </motion.div>
+      ) : null}
+    </AnimatePresence>
+  );
+}
diff --git a/studio/frontend/src/hooks/use-llama-update-check.ts b/studio/frontend/src/hooks/use-llama-update-check.ts
new file mode 100644
index 0000000000..801576534c
--- /dev/null
+++ b/studio/frontend/src/hooks/use-llama-update-check.ts
@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch, getAuthToken } from "@/features/auth";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// First check shortly after load, then re-surface as an hourly reminder.
+const FIRST_CHECK_DELAY_MS = 8000;
+const REMINDER_INTERVAL_MS = 60 * 60 * 1000; // ~1 hour
+// The banner fades on its own after this long (non-invasive). It re-appears on
+// the next hourly reminder while an update is still available.
+const AUTO_HIDE_MS = 10000;
+// While an update is applying, poll the job state at this cadence.
+const JOB_POLL_INTERVAL_MS = 3000;
+
+export interface LlamaUpdateJob {
+  state: "idle" | "running" | "success" | "error";
+  message: string;
+  from_tag: string | null;
+  to_tag: string | null;
+  error: string | null;
+}
+
+export interface LlamaUpdateStatus {
+  supported: boolean;
+  update_available: boolean;
+  installed_tag: string | null;
+  latest_tag: string | null;
+  job: LlamaUpdateJob;
+}
+
+function parseStatus(value: unknown): LlamaUpdateStatus | null {
+  if (!value || typeof value !== "object") return null;
+  const s = value as Record<string, unknown>;
+  const job = (s.job ?? {}) as Record<string, unknown>;
+  return {
+    supported: s.supported === true,
+    update_available: s.update_available === true,
+    installed_tag: typeof s.installed_tag === "string" ? s.installed_tag : null,
+    latest_tag: typeof s.latest_tag === "string" ? s.latest_tag : null,
+    job: {
+      state: (job.state as LlamaUpdateJob["state"]) ?? "idle",
+      message: typeof job.message === "string" ? job.message : "",
+      from_tag: typeof job.from_tag === "string" ? job.from_tag : null,
+      to_tag: typeof job.to_tag === "string" ? job.to_tag : null,
+      error: typeof job.error === "string" ? job.error : null,
+    },
+  };
+}
+
+async function fetchStatus(forceRefresh = false): Promise<LlamaUpdateStatus | null> {
+  if (!getAuthToken()) return null;
+  try {
+    const res = await authFetch(
+      `/api/llama/update-status${forceRefresh ? "?force_refresh=true" : ""}`,
+    );
+    if (!res.ok) return null;
+    return parseStatus(await res.json());
+  } catch {
+    return null;
+  }
+}
+
+interface UseLlamaUpdateCheckOptions {
+  enabled?: boolean;
+}
+
+export interface LlamaApplyResult {
+  ok: boolean;
+  tag?: string | null;
+  error?: string | null;
+}
+
+/**
+ * Polls the backend for a newer llama.cpp prebuilt. When one exists, `visible`
+ * is true for a 10s window (fades on its own), and re-surfaces every ~hour as a
+ * gentle reminder. `apply()` triggers the in-place swap and tracks the job.
+ */
+export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptions = {}) {
+  const [status, setStatus] = useState<LlamaUpdateStatus | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [applying, setApplying] = useState(false);
+  const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pollTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const clearHideTimer = useCallback(() => {
+    if (hideTimer.current) {
+      clearTimeout(hideTimer.current);
+      hideTimer.current = null;
+    }
+  }, []);
+
+  const armAutoHide = useCallback(() => {
+    clearHideTimer();
+    hideTimer.current = setTimeout(() => setVisible(false), AUTO_HIDE_MS);
+  }, [clearHideTimer]);
+
+  const clearPollTimer = useCallback(() => {
+    if (pollTimer.current) {
+      clearInterval(pollTimer.current);
+      pollTimer.current = null;
+    }
+  }, []);
+
+  // Poll the job to completion. Shared by apply() and surfaceIfAvailable() so a
+  // job is tracked once whoever noticed it; onDone resolves with the result.
+  const startJobPoll = useCallback(
+    (onDone?: (result: LlamaApplyResult) => void) => {
+      clearPollTimer();
+      pollTimer.current = setInterval(async () => {
+        const s = await fetchStatus();
+        if (!s) return;
+        setStatus(s);
+        if (s.job.state === "running") return;
+        clearPollTimer();
+        setApplying(false);
+        if (s.job.state === "success") {
+          setVisible(false);
+          onDone?.({ ok: true, tag: s.job.to_tag });
+        } else if (s.job.state === "error") {
+          armAutoHide();
+          onDone?.({ ok: false, error: s.job.error });
+        } else {
+          // idle without a terminal result (job reset): stop so the banner
+          // does not stick on "Updating...".
+          armAutoHide();
+          onDone?.({ ok: false, error: "update did not complete" });
+        }
+      }, JOB_POLL_INTERVAL_MS);
+    },
+    [armAutoHide, clearPollTimer],
+  );
+
+  // Surface the banner for the auto-hide window when an update is available.
+  const surfaceIfAvailable = useCallback(
+    (next: LlamaUpdateStatus | null) => {
+      if (!next) return;
+      setStatus(next);
+      if (next.job.state === "running") {
+        // Swap in progress (e.g. another tab): keep the banner up and track the
+        // job so "Updating..." clears when it finishes instead of sticking.
+        setApplying(true);
+        setVisible(true);
+        clearHideTimer();
+        if (!pollTimer.current) startJobPoll();
+        return;
+      }
+      if (next.update_available) {
+        setVisible(true);
+        armAutoHide();
+      }
+    },
+    [armAutoHide, clearHideTimer, startJobPoll],
+  );
+
+  useEffect(() => {
+    if (!enabled) return;
+    let canceled = false;
+
+    const firstTimer = setTimeout(() => {
+      fetchStatus().then((s) => {
+        if (!canceled) surfaceIfAvailable(s);
+      });
+    }, FIRST_CHECK_DELAY_MS);
+
+    const reminder = setInterval(() => {
+      fetchStatus().then((s) => {
+        if (!canceled) surfaceIfAvailable(s);
+      });
+    }, REMINDER_INTERVAL_MS);
+
+    return () => {
+      canceled = true;
+      clearTimeout(firstTimer);
+      clearInterval(reminder);
+      clearHideTimer();
+      clearPollTimer();
+    };
+  }, [enabled, surfaceIfAvailable, clearHideTimer, clearPollTimer]);
+
+  const dismiss = useCallback(() => {
+    clearHideTimer();
+    setVisible(false);
+  }, [clearHideTimer]);
+
+  const apply = useCallback(async (): Promise<LlamaApplyResult> => {
+    if (applying) return { ok: false, error: "already running" };
+    setApplying(true);
+    setVisible(true);
+    clearHideTimer();
+    let action: {
+      started?: boolean;
+      reason?: string | null;
+      message?: string | null;
+    } | null = null;
+    try {
+      const res = await authFetch("/api/llama/update", { method: "POST" });
+      if (!res.ok) {
+        setApplying(false);
+        armAutoHide();
+        return { ok: false, error: `HTTP ${res.status}` };
+      }
+      try {
+        action = await res.json();
+      } catch {
+        action = null;
+      }
+    } catch (e) {
+      setApplying(false);
+      armAutoHide();
+      return { ok: false, error: String(e) };
+    }
+
+    // 200 without a started job (no marker / installer missing) leaves it idle,
+    // so surface the reason instead of polling forever. already_running is the
+    // exception: a job is in flight, so track it to completion below.
+    if (action && action.started === false && action.reason !== "already_running") {
+      setApplying(false);
+      armAutoHide();
+      return {
+        ok: false,
+        error: action.message ?? action.reason ?? "update was not started",
+      };
+    }
+
+    return await new Promise<LlamaApplyResult>((resolve) => startJobPoll(resolve));
+  }, [applying, armAutoHide, clearHideTimer, startJobPoll]);
+
+  return {
+    status: enabled ? status : null,
+    visible: enabled && visible,
+    applying,
+    apply,
+    dismiss,
+  };
+}

From 50e4e9c45902cd6241f75ed2b4aeb8a56bbb8928 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 10:47:51 -0700
Subject: [PATCH 167/222] Studio: gracefully disable MTP when the model has no
 head or drafter (#6159)

* Studio: gracefully disable MTP when the model has no head or drafter

Selecting MTP or MTP+Ngram in Speculative Decoding on a GGUF with no nextn
head and no separate drafter aborted the whole load. llama-server does not
no-op an empty draft-mtp request: it exits with 'failed to measure MTP
context memory: failed to create llama_context', surfaced to the user as a
generic 'llama-server failed to start. Check that the GGUF file is valid
and you have enough memory.'

Build-time fix in _build_speculative_flags: when a forced mtp / mtp+ngram
mode targets a model with no MTP head and no drafter (is_mtp_model is
False), default back instead of emitting draft-mtp. mtp falls back to
--spec-default; mtp+ngram keeps the ngram-mod half, which needs no head.
Real MTP models (embedded head or separate drafter), sub-3B MTP overrides,
and the auto path are unchanged.

Runtime hardening: the existing post-launch MTP retry only fired for
separate-file drafters (--model-draft in spec_flags), so an embedded-head
model that the binary cannot build still hard-failed. Gate the retry on the
spec block requesting MTP, recognise the embedded-head abort strings
('failed to measure MTP context memory', 'failed to create llama_context'),
and make the drafter name None-safe in the warning.

Tests: extend the resolver matrix (forced mtp / mtp+ngram on a non-MTP
model) and add two cases asserting the default-back emission.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    | 104 +++++++++---------
 .../tests/test_llama_cpp_mtp_detection.py     |  45 +++++++-
 2 files changed, 94 insertions(+), 55 deletions(-)

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index e608a4b552..85ca32eaf5 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3572,53 +3572,43 @@ class LlamaCppBackend:
                 )
 
                 healthy = _spawn_and_wait(cmd)
-                # A separate MTP drafter (e.g. Gemma's gemma4-assistant head)
-                # can fail to load on a llama-server that advertises the
-                # --spec-type draft-mtp flag but predates the drafter's
-                # architecture -- and that aborts the whole server. Retry once
-                # with the whole spec block replaced by --spec-default so the
-                # main model still loads (without speculation). Replacing the
-                # slice -- rather than re-resolving with mtp_draft_path=None --
-                # is what guarantees MTP is off even for a forced mtp / mtp+ngram
-                # request (which would otherwise re-emit --spec-type draft-mtp).
-                # _requested_spec_mode (the user's choice) is left intact so a
-                # duplicate /load doesn't thrash a reload.
-                # Gate on the flag actually being in the command, not on the
-                # drafter merely existing on disk: local loads pass the path
-                # even in off/ngram modes (and auto drops MTP sub-3B), where a
-                # retry would blame the drafter for an unrelated failure and
-                # override the user's spec choice. The cancel check keeps an
-                # /unload that killed the first attempt from respawning.
-                if (
-                    not healthy
-                    and "--model-draft" in spec_flags
-                    and not self._cancel_event.is_set()
-                ):
-                    # Only blame the binary's age when the output shows the
-                    # drafter actually failing (unknown arch / draft load);
-                    # an unrelated crash (e.g. OOM) gets a neutral message.
-                    # Substrings are upstream llama.cpp messages
-                    # (llama_model_load / srv load_model [spec]); if they
-                    # drift, only the wording degrades -- the retry fires
-                    # either way.
-                    _attempt_output = "\n".join(self._stdout_lines)
+                # Any MTP request can abort the server: a separate drafter
+                # (Gemma) on a binary that predates its arch, or an embedded
+                # head (Qwen) the binary cannot build. Retry once with the
+                # spec slice replaced by --spec-default so the main model still
+                # loads. Gate on the spec block (not the drafter path, which
+                # off/ngram local loads also carry) and keep
+                # _requested_spec_mode so a duplicate /load doesn't thrash. The
+                # cancel check stops an /unload-killed attempt respawning.
+                _spec_requested_mtp = any("mtp" in str(t).lower() for t in spec_flags)
+                if not healthy and _spec_requested_mtp and not self._cancel_event.is_set():
+                    # Blame the binary only when the output shows MTP itself
+                    # failing (unknown arch / draft or context build); an
+                    # unrelated crash (e.g. OOM) gets a neutral message.
+                    _lo = "\n".join(self._stdout_lines).lower()
                     if (
-                        "unknown model architecture" in _attempt_output
-                        or "failed to measure draft model memory" in _attempt_output
+                        "unknown model architecture" in _lo
+                        or "failed to measure draft model memory" in _lo
+                        or "failed to measure mtp context memory" in _lo
+                        or "failed to create llama_context" in _lo
                     ):
                         _retry_reason = (
-                            "the prebuilt may predate its architecture; retrying "
-                            "without speculative decoding -- run "
-                            "`unsloth studio update` for MTP"
+                            "the prebuilt may predate it; retrying without "
+                            "speculative decoding -- run `unsloth studio "
+                            "update` for MTP"
                         )
                     else:
                         _retry_reason = (
-                            "retrying without speculative decoding in case the "
-                            "drafter is the cause"
+                            "retrying without speculative decoding in case MTP is the cause"
                         )
+                    _drafter = (
+                        Path(launch_mtp_draft_path).name
+                        if launch_mtp_draft_path
+                        else "embedded head"
+                    )
                     logger.warning(
-                        "llama-server failed to start with MTP drafter %s; %s.",
-                        Path(launch_mtp_draft_path).name,
+                        "llama-server failed to start with MTP (%s); %s.",
+                        _drafter,
                         _retry_reason,
                     )
                     self._kill_process()
@@ -3790,8 +3780,9 @@ class LlamaCppBackend:
           2B   CPU: chained n=2   = 0.83x vs OFF; ngram-only = 1.01x
           4B+ GPU/CPU: spec on is a net win (1.08x-1.46x).
         Auto falls back to ngram-mod (zero-VRAM, near-zero idle cost on
-        diverse content); forced MTP variants engage anyway and just log a
-        warning per the user's choice.
+        diverse content); forced MTP on a model with no head/drafter defaults
+        back (mtp -> spec-default, mtp+ngram -> ngram-mod) since llama-server
+        aborts otherwise; sub-3B real-MTP engages with a warning.
         """
         flags: List[str] = []
         # Reset; emit branches re-set on the resolved emission.
@@ -3909,33 +3900,40 @@ class LlamaCppBackend:
             _emit_ngram_mod()
             return flags
         if effective_mode == "mtp":
+            if not is_mtp_model:
+                # No head and no drafter: llama-server aborts on draft-mtp
+                # instead of no-op'ing, so default back.
+                logger.warning(
+                    "MTP requested but this GGUF has no MTP head or drafter; "
+                    "loading without speculative decoding."
+                )
+                flags.append("--spec-default")
+                self._speculative_type = "default"
+                return flags
             if _mtp_too_small:
                 logger.warning(
                     f"Forcing MTP on a {_mtp_size_b:.1f}B model; "
                     "the bench shows draft-mtp regresses below 3B. "
                     "Engaging anyway (user override)."
                 )
-            elif not is_mtp_model:
-                logger.warning(
-                    "Forcing MTP on a non-MTP GGUF; llama-server may "
-                    "fall back to spec-off if no nextn head is present. "
-                    "Engaging anyway (user override)."
-                )
             _emit_mtp(chain_ngram = False)
             return flags
         if effective_mode == "mtp+ngram":
+            if not is_mtp_model:
+                # No head/drafter: keep the ngram half (needs no head),
+                # drop the draft-mtp chain that would abort the server.
+                logger.warning(
+                    "MTP+Ngram requested but this GGUF has no MTP head or "
+                    "drafter; loading ngram-mod only."
+                )
+                _emit_ngram_mod()
+                return flags
             if _mtp_too_small:
                 logger.warning(
                     f"Forcing MTP+Ngram on a {_mtp_size_b:.1f}B model; "
                     "the bench shows the chain regresses below 3B. "
                     "Engaging anyway (user override)."
                 )
-            elif not is_mtp_model:
-                logger.warning(
-                    "Forcing MTP+Ngram on a non-MTP GGUF; llama-server "
-                    "may fall back to ngram-only if no nextn head is "
-                    "present. Engaging anyway (user override)."
-                )
             _emit_mtp(chain_ngram = True)
             return flags
 
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index 784ab1b259..25ce71a774 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -1056,8 +1056,8 @@ _SUB_3B_MTP_MODEL = "unsloth/Qwen3.5-0.8B-MTP-GGUF"
         ("mtp", False, _MTP_MODEL, "draft-mtp", "3", False),
         # ── mtp forced on sub-3B: engage anyway ──
         ("mtp", True, _SUB_3B_MTP_MODEL, "draft-mtp", "2", False),
-        # ── mtp forced on non-MTP: engage anyway ──
-        ("mtp", True, _NON_MTP_MODEL, "draft-mtp", "2", False),
+        # ── mtp forced on non-MTP: default back (no head/drafter) ──
+        ("mtp", True, _NON_MTP_MODEL, None, None, False),
         # ── ngram forced: ngram-mod alone on BOTH platforms ──
         ("ngram", True, _MTP_MODEL, "ngram-mod", None, True),
         ("ngram", False, _MTP_MODEL, "ngram-mod", None, True),
@@ -1066,6 +1066,8 @@ _SUB_3B_MTP_MODEL = "unsloth/Qwen3.5-0.8B-MTP-GGUF"
         ("mtp+ngram", True, _MTP_MODEL, "ngram-mod,draft-mtp", "2", True),
         ("mtp+ngram", False, _MTP_MODEL, "ngram-mod,draft-mtp", "3", True),
         ("mtp+ngram", True, _SUB_3B_MTP_MODEL, "ngram-mod,draft-mtp", "2", True),
+        # ── mtp+ngram forced on non-MTP: keep ngram, drop draft-mtp ──
+        ("mtp+ngram", True, _NON_MTP_MODEL, "ngram-mod", None, True),
         # ── off: nothing emitted ──
         ("off", True, _MTP_MODEL, None, None, False),
         ("off", False, _MTP_MODEL, None, None, False),
@@ -1178,3 +1180,42 @@ def test_build_speculative_flags_mtp_token_missing_logs_and_skips(monkeypatch):
     # choice is still reflected in _requested_spec_mode.
     assert backend.requested_spec_mode == "mtp"
     assert backend.speculative_type is None
+
+
+def test_forced_mtp_on_non_mtp_model_defaults_back(monkeypatch):
+    # Forcing MTP on a model with no head/drafter must NOT emit draft-mtp:
+    # llama-server aborts on it ("failed to measure MTP context memory")
+    # rather than no-op'ing. Default back to --spec-default instead.
+    backend = _resolver_backend(monkeypatch)
+    flags = backend._build_speculative_flags(
+        speculative_type = "mtp",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _NON_MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    assert "--spec-type" not in flags
+    assert "--spec-default" in flags
+    assert backend.speculative_type == "default"
+    assert backend.requested_spec_mode == "mtp"
+
+
+def test_forced_mtp_ngram_on_non_mtp_model_keeps_ngram(monkeypatch):
+    # mtp+ngram on a non-MTP model drops the doomed draft-mtp chain but keeps
+    # the ngram half, which needs no head.
+    backend = _resolver_backend(monkeypatch)
+    flags = backend._build_speculative_flags(
+        speculative_type = "mtp+ngram",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _NON_MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    parsed = _flags_dict(flags)
+    assert parsed.get("--spec-type") == "ngram-mod"
+    assert backend.speculative_type == "ngram-mod"
+    assert backend.requested_spec_mode == "mtp+ngram"

From aa3b46f4c1c452ea342075c3a8094bcafcc75d63 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 10:48:44 -0700
Subject: [PATCH 168/222] Studio: show the llama.cpp update banner sooner and
 keep it until dismissed (#6162)

Follow-up to #6097. The update banner appeared 8s after load and auto-hid after
about 10s. Show it about 1s after a newer prebuilt is detected and keep it up
until the user dismisses it (click outside or the X) or runs the update; it
stays during an in-progress update so the progress is visible.

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
---
 .../src/components/llama-update-banner.tsx    | 38 +++++++---
 .../src/hooks/use-llama-update-check.ts       | 71 ++++++++-----------
 2 files changed, 59 insertions(+), 50 deletions(-)

diff --git a/studio/frontend/src/components/llama-update-banner.tsx b/studio/frontend/src/components/llama-update-banner.tsx
index 8919c24cc7..c8a4dd1e40 100644
--- a/studio/frontend/src/components/llama-update-banner.tsx
+++ b/studio/frontend/src/components/llama-update-banner.tsx
@@ -5,7 +5,7 @@ import { Button } from "@/components/ui/button";
 import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
 import { toast } from "@/lib/toast";
 import { AnimatePresence, motion } from "motion/react";
-import { type ReactElement } from "react";
+import { type ReactElement, useEffect, useRef } from "react";
 
 const EASE_OUT_QUART: [number, number, number, number] = [0.165, 0.84, 0.44, 1];
 
@@ -14,9 +14,9 @@ interface LlamaUpdateBannerProps {
 }
 
 /**
- * Non-invasive "Update llama.cpp" affordance. Appears bottom-right when a newer
- * prebuilt is available, fades on its own after ~10s, and re-surfaces hourly.
- * Clicking Update swaps the prebuilt in place via POST /api/llama/update.
+ * Non-invasive "Update llama.cpp" affordance. Appears bottom-right ~1s after a
+ * newer prebuilt is detected and stays up until dismissed (click outside / X)
+ * or updated. Clicking Update swaps the prebuilt in place via POST /api/llama/update.
  */
 export function LlamaUpdateBanner({
   enabled = true,
@@ -32,16 +32,38 @@ export function LlamaUpdateBanner({
         `llama.cpp updated to ${result.tag ?? "the latest build"}. Reload your model to use it.`,
       );
     } else if (result) {
-      toast.error(`llama.cpp update failed: ${result.error ?? "unknown error"}`);
+      toast.error(
+        `llama.cpp update failed: ${result.error ?? "unknown error"}`,
+      );
     }
   }
 
-  const show = visible && status != null && (status.update_available || applying);
+  const show =
+    visible && status != null && (status.update_available || applying);
+  const bannerRef = useRef<HTMLDivElement>(null);
+
+  // Dismiss when the user clicks anything outside the banner. Kept off while an
+  // update is applying so the progress stays visible.
+  useEffect(() => {
+    if (!show || applying) return;
+    function onPointerDown(event: PointerEvent) {
+      if (
+        bannerRef.current &&
+        !bannerRef.current.contains(event.target as Node)
+      ) {
+        dismiss();
+      }
+    }
+    document.addEventListener("pointerdown", onPointerDown, true);
+    return () =>
+      document.removeEventListener("pointerdown", onPointerDown, true);
+  }, [show, applying, dismiss]);
 
   return (
     <AnimatePresence>
       {show ? (
         <motion.div
+          ref={bannerRef}
           initial={{ opacity: 0, y: 12, scale: 0.96 }}
           animate={{ opacity: 1, y: 0, scale: 1 }}
           exit={{ opacity: 0, y: 8, scale: 0.97 }}
@@ -50,7 +72,7 @@ export function LlamaUpdateBanner({
           data-testid="llama-update-banner"
         >
           <div className="corner-squircle relative overflow-hidden border border-border/60 bg-background/95 px-4 py-3 shadow-lg backdrop-blur-md">
-            {!applying ? (
+            {applying ? null : (
               <button
                 type="button"
                 onClick={dismiss}
@@ -73,7 +95,7 @@ export function LlamaUpdateBanner({
                   />
                 </svg>
               </button>
-            ) : null}
+            )}
 
             <div className="flex items-center gap-2 pr-5">
               <span className="text-base" aria-hidden="true">
diff --git a/studio/frontend/src/hooks/use-llama-update-check.ts b/studio/frontend/src/hooks/use-llama-update-check.ts
index 801576534c..1ac5d9768e 100644
--- a/studio/frontend/src/hooks/use-llama-update-check.ts
+++ b/studio/frontend/src/hooks/use-llama-update-check.ts
@@ -4,12 +4,10 @@
 import { authFetch, getAuthToken } from "@/features/auth";
 import { useCallback, useEffect, useRef, useState } from "react";
 
-// First check shortly after load, then re-surface as an hourly reminder.
-const FIRST_CHECK_DELAY_MS = 8000;
+// First check shortly after load, then re-surface as an hourly reminder. The
+// banner stays up until the user dismisses it (click outside / X) or updates.
+const FIRST_CHECK_DELAY_MS = 1000;
 const REMINDER_INTERVAL_MS = 60 * 60 * 1000; // ~1 hour
-// The banner fades on its own after this long (non-invasive). It re-appears on
-// the next hourly reminder while an update is still available.
-const AUTO_HIDE_MS = 10000;
 // While an update is applying, poll the job state at this cadence.
 const JOB_POLL_INTERVAL_MS = 3000;
 
@@ -48,7 +46,9 @@ function parseStatus(value: unknown): LlamaUpdateStatus | null {
   };
 }
 
-async function fetchStatus(forceRefresh = false): Promise<LlamaUpdateStatus | null> {
+async function fetchStatus(
+  forceRefresh = false,
+): Promise<LlamaUpdateStatus | null> {
   if (!getAuthToken()) return null;
   try {
     const res = await authFetch(
@@ -73,28 +73,18 @@ export interface LlamaApplyResult {
 
 /**
  * Polls the backend for a newer llama.cpp prebuilt. When one exists, `visible`
- * is true for a 10s window (fades on its own), and re-surfaces every ~hour as a
- * gentle reminder. `apply()` triggers the in-place swap and tracks the job.
+ * becomes true ~1s after load and stays up until the user dismisses it (click
+ * outside / X) or updates; it re-surfaces every ~hour as a reminder. `apply()`
+ * triggers the in-place swap and tracks the job.
  */
-export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptions = {}) {
+export function useLlamaUpdateCheck({
+  enabled = true,
+}: UseLlamaUpdateCheckOptions = {}) {
   const [status, setStatus] = useState<LlamaUpdateStatus | null>(null);
   const [visible, setVisible] = useState(false);
   const [applying, setApplying] = useState(false);
-  const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const pollTimer = useRef<ReturnType<typeof setInterval> | null>(null);
 
-  const clearHideTimer = useCallback(() => {
-    if (hideTimer.current) {
-      clearTimeout(hideTimer.current);
-      hideTimer.current = null;
-    }
-  }, []);
-
-  const armAutoHide = useCallback(() => {
-    clearHideTimer();
-    hideTimer.current = setTimeout(() => setVisible(false), AUTO_HIDE_MS);
-  }, [clearHideTimer]);
-
   const clearPollTimer = useCallback(() => {
     if (pollTimer.current) {
       clearInterval(pollTimer.current);
@@ -118,20 +108,19 @@ export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptio
           setVisible(false);
           onDone?.({ ok: true, tag: s.job.to_tag });
         } else if (s.job.state === "error") {
-          armAutoHide();
+          // Leave the banner up so the user can retry; clearing applying drops
+          // the "Updating..." state.
           onDone?.({ ok: false, error: s.job.error });
         } else {
-          // idle without a terminal result (job reset): stop so the banner
-          // does not stick on "Updating...".
-          armAutoHide();
+          // idle without a terminal result (job reset): stop tracking.
           onDone?.({ ok: false, error: "update did not complete" });
         }
       }, JOB_POLL_INTERVAL_MS);
     },
-    [armAutoHide, clearPollTimer],
+    [clearPollTimer],
   );
 
-  // Surface the banner for the auto-hide window when an update is available.
+  // Surface the banner when an update is available; it stays up until dismissed.
   const surfaceIfAvailable = useCallback(
     (next: LlamaUpdateStatus | null) => {
       if (!next) return;
@@ -141,16 +130,14 @@ export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptio
         // job so "Updating..." clears when it finishes instead of sticking.
         setApplying(true);
         setVisible(true);
-        clearHideTimer();
         if (!pollTimer.current) startJobPoll();
         return;
       }
       if (next.update_available) {
         setVisible(true);
-        armAutoHide();
       }
     },
-    [armAutoHide, clearHideTimer, startJobPoll],
+    [startJobPoll],
   );
 
   useEffect(() => {
@@ -173,21 +160,18 @@ export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptio
       canceled = true;
       clearTimeout(firstTimer);
       clearInterval(reminder);
-      clearHideTimer();
       clearPollTimer();
     };
-  }, [enabled, surfaceIfAvailable, clearHideTimer, clearPollTimer]);
+  }, [enabled, surfaceIfAvailable, clearPollTimer]);
 
   const dismiss = useCallback(() => {
-    clearHideTimer();
     setVisible(false);
-  }, [clearHideTimer]);
+  }, []);
 
   const apply = useCallback(async (): Promise<LlamaApplyResult> => {
     if (applying) return { ok: false, error: "already running" };
     setApplying(true);
     setVisible(true);
-    clearHideTimer();
     let action: {
       started?: boolean;
       reason?: string | null;
@@ -197,7 +181,6 @@ export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptio
       const res = await authFetch("/api/llama/update", { method: "POST" });
       if (!res.ok) {
         setApplying(false);
-        armAutoHide();
         return { ok: false, error: `HTTP ${res.status}` };
       }
       try {
@@ -207,24 +190,28 @@ export function useLlamaUpdateCheck({ enabled = true }: UseLlamaUpdateCheckOptio
       }
     } catch (e) {
       setApplying(false);
-      armAutoHide();
       return { ok: false, error: String(e) };
     }
 
     // 200 without a started job (no marker / installer missing) leaves it idle,
     // so surface the reason instead of polling forever. already_running is the
     // exception: a job is in flight, so track it to completion below.
-    if (action && action.started === false && action.reason !== "already_running") {
+    if (
+      action &&
+      action.started === false &&
+      action.reason !== "already_running"
+    ) {
       setApplying(false);
-      armAutoHide();
       return {
         ok: false,
         error: action.message ?? action.reason ?? "update was not started",
       };
     }
 
-    return await new Promise<LlamaApplyResult>((resolve) => startJobPoll(resolve));
-  }, [applying, armAutoHide, clearHideTimer, startJobPoll]);
+    return await new Promise<LlamaApplyResult>((resolve) =>
+      startJobPoll(resolve),
+    );
+  }, [applying, startJobPoll]);
 
   return {
     status: enabled ? status : null,

From d8231caf45b0fe78e4cc738e711c5956446ba0df Mon Sep 17 00:00:00 2001
From: Eyera <hauzin@hotmail.com>
Date: Wed, 10 Jun 2026 20:05:59 +0200
Subject: [PATCH 169/222] fix(studio): round compact tooltip corners to 9px
 (#6163)

---
 studio/frontend/src/index.css | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 0aa9ac0152..797e17420e 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -741,15 +741,8 @@
 		background-color: #ffffff !important;
 	}
 
-	/* Compact tooltip — small black pill with white text. Used for short
-	   hover labels on chat-area icon buttons (Copy, Edit, Delete,
-	   Refresh, More, code-block actions) and the panel's info-icon
-	   hints. Corner radius is fixed at 8px so it tracks with the
-	   underlying icon button corners (also 8px) — keeps the tooltip
-	   visually anchored to its trigger rather than reading as a much
-	   larger floating pill. */
 	.tooltip-compact {
-		@apply rounded-full border-transparent bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug text-white shadow-md;
+		@apply rounded-[9px] border-transparent bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug text-white shadow-md;
 	}
 
 	/* Dialog popups: borderless; chatbox shadow in light, flat card
@@ -1086,7 +1079,7 @@
 	[data-pill-compact="true"]
 		.composer-pill-btn:not([data-keep-label])[data-pill-label]:hover::after {
 		content: attr(data-pill-label);
-		@apply pointer-events-none absolute bottom-[calc(100%+6px)] left-1/2 z-50 -translate-x-1/2 rounded-full bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug whitespace-nowrap text-white shadow-md;
+		@apply pointer-events-none absolute bottom-[calc(100%+6px)] left-1/2 z-50 -translate-x-1/2 rounded-[9px] bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug whitespace-nowrap text-white shadow-md;
 	}
 
 	/* Compact caret pills (RAG, MCP) open their menu on click instead of

From 52aa2482bb64c1ccdeaa9c634d68b360c861206d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 11:09:16 -0700
Subject: [PATCH 170/222] Update CODEOWNERS

---
 .github/CODEOWNERS | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2802f461b6..a9694036cf 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -6,10 +6,10 @@
 /unsloth/models/rl_replacements.py @Datta0 @pluesclues @danielhanchen
 /unsloth/trainer.py @danielhanchen
 /unsloth/models/sentence_transformer.py @Etherll @danielhanchen
-/unsloth/save.py @rolandtannous @danielhanchen
+/unsloth/save.py @danielhanchen
 /unsloth/tokenizer_utils.py @mmathew23 @danielhanchen
-/unsloth/chat_templates.py @rolandtannous @danielhanchen
-/unsloth/ollama_template_mappers.py @rolandtannous @danielhanchen
+/unsloth/chat_templates.py @danielhanchen
+/unsloth/ollama_template_mappers.py @danielhanchen
 /unsloth/kernels/moe/*.py @Datta0
 /unsloth/import_fixes.py @danielhanchen
 /unsloth/device_type.py @danielhanchen
@@ -45,14 +45,14 @@
 /unsloth/utils/hf_hub.py @mmathew23
 /unsloth/utils/packing.py @mmathew23
 
-/cli/ @rolandtannous @Manan17
-/studio/frontend/ @Shine1i @rolandtannous @Manan17
+/cli/ @Manan17
+/studio/frontend/ @Shine1i @Manan17
 /studio/frontend/public/ @Shine1i
-/studio/backend/ @rolandtannous
-/studio/backend/core/data_recipe/ @rolandtannous
-/studio/backend/tests/ @rolandtannous @danielhanchen
-/tests/ @rolandtannous @danielhanchen
-/scripts/ @rolandtannous @danielhanchen
+/studio/backend/
+/studio/backend/core/data_recipe/
+/studio/backend/tests/ @danielhanchen
+/tests/ @danielhanchen
+/scripts/ @danielhanchen
 
 # Snapshot data for the notebook linter / Colab oracle. Drift in these
 # files changes the pin floor for every Unsloth notebook, so refreshes

From 3b662d16b90058a38842aa020cf23e4186f376c2 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 11:10:22 -0700
Subject: [PATCH 171/222] Update _utils.py

---
 unsloth/models/_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 23723e1d27..1a86ff8eb6 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2026.6.1"
+__version__ = "2026.6.2"
 
 __all__ = [
     "SUPPORTS_BFLOAT16",

From 5f1118263449adab8b55fc923e6e46020660e8ff Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 11:10:51 -0700
Subject: [PATCH 172/222] Update pyproject.toml

---
 pyproject.toml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 713146ff32..79c14c907c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,7 +69,7 @@ triton = [
 ]
 
 huggingfacenotorch = [
-    "unsloth_zoo>=2026.6.1",
+    "unsloth_zoo>=2026.6.2",
     "wheel>=0.42.0",
     "packaging",
     "numpy",
@@ -90,7 +90,7 @@ huggingfacenotorch = [
 ]
 huggingface = [
     "unsloth[huggingfacenotorch]",
-    "unsloth_zoo>=2026.6.1",
+    "unsloth_zoo>=2026.6.2",
     "torchvision",
     "unsloth[triton]",
 ]
@@ -580,7 +580,7 @@ colab-ampere-torch220 = [
     "flash-attn>=2.6.3 ; ('linux' in sys_platform)",
 ]
 colab-new = [
-    "unsloth_zoo>=2026.6.1",
+    "unsloth_zoo>=2026.6.2",
     "packaging",
     "tyro",
     "transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",

From ec46a5556836de2ee3e4daaf4c54c422b6c6b188 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 11:24:39 -0700
Subject: [PATCH 173/222] Bump install.sh / install.ps1 pin to
 unsloth>=2026.6.2 (#6165)

---
 install.ps1 | 10 +++++-----
 install.sh  | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/install.ps1 b/install.ps1
index 16337f4b9c..cbc7b206c8 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1830,7 +1830,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Resolve pydantic WITH deps so pip pins pydantic-core
                 # to the matching version (no-torch-runtime.txt below
@@ -1844,7 +1844,7 @@ shell.Run cmd, 0, False
                 }
             }
         } else {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
         }
         if ($baseInstallExit -ne 0) {
             Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
@@ -1891,7 +1891,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.6.1" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Same pydantic-with-deps trick as the migrated branch.
                 $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython pydantic }
@@ -1903,7 +1903,7 @@ shell.Run cmd, 0, False
                 }
             }
         } elseif ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.6.1" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.6.2" unsloth-zoo }
         } else {
             $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth -- "$PackageName" }
         }
@@ -1931,7 +1931,7 @@ shell.Run cmd, 0, False
         Write-TauriLog "STEP" "Installing unsloth"
         substep "installing unsloth (this may take a few minutes)..."
         if ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.6.1" --torch-backend=auto }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.6.2" --torch-backend=auto }
             if ($baseInstallExit -ne 0) {
                 Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
                 return (Exit-InstallFailure "Failed to install unsloth (exit code $baseInstallExit)" $baseInstallExit)
diff --git a/install.sh b/install.sh
index af74410397..befcaaa186 100755
--- a/install.sh
+++ b/install.sh
@@ -2333,7 +2333,7 @@ if [ "$_MIGRATED" = true ]; then
         # to prevent transitive torch resolution.
         run_install_cmd "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.6.1" unsloth-zoo
+            "unsloth>=2026.6.2" unsloth-zoo
         # Resolve pydantic WITH deps so pip pins pydantic-core to the
         # matching version (no-torch-runtime.txt below is --no-deps).
         # All transitive deps are torch-free.
@@ -2346,7 +2346,7 @@ if [ "$_MIGRATED" = true ]; then
     else
         run_install_cmd "install unsloth (migrated)" uv pip install --python "$_VENV_PY" \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.6.1" unsloth-zoo
+            "unsloth>=2026.6.2" unsloth-zoo
     fi
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         substep "overlaying local repo (editable)..."
@@ -2550,7 +2550,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
         run_install_cmd "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --upgrade-package unsloth --upgrade-package unsloth-zoo \
-            "unsloth>=2026.6.1" unsloth-zoo
+            "unsloth>=2026.6.2" unsloth-zoo
         # Same pydantic-with-deps trick as the migrated branch.
         run_install_cmd "install pydantic (with deps for compatible core)" \
             uv pip install --python "$_VENV_PY" pydantic
@@ -2568,7 +2568,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         fi
     elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         run_install_cmd "install unsloth (local)" uv pip install --python "$_VENV_PY" \
-            --upgrade-package unsloth "unsloth>=2026.6.1" unsloth-zoo
+            --upgrade-package unsloth "unsloth>=2026.6.2" unsloth-zoo
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."
@@ -2600,7 +2600,7 @@ else
     tauri_log "STEP" "Installing Unsloth"
     substep "installing unsloth (this may take a few minutes)..."
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
-        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.6.1" --torch-backend=auto
+        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.6.2" --torch-backend=auto
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."

From bf2cd745b15922f0fed4649cbd67d563fbc2ec25 Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Wed, 10 Jun 2026 23:00:11 -0500
Subject: [PATCH 174/222] Fix installer selecting ROCm torch on NVIDIA Linux
 hosts (#6174)

* fix: prevent ROCm torch from installing on NVIDIA Linux hosts

NVIDIA's open kernel module (driver 560+) registers GPU topology nodes in
the KFD sysfs hierarchy with non-zero gpu_id values. The _has_amd_rocm_gpu
(install.sh) and _has_rocm_gpu (install_python_stack.py) sysfs fallbacks
previously treated any non-zero gpu_id as proof of an AMD GPU, so an
NVIDIA-only host with the open kernel driver was misrouted to the ROCm
install path, replacing the correctly-installed CUDA torch with ROCm wheels.

Fixes:

1. install.sh _has_amd_rocm_gpu sysfs fallback: require vendor_id 4098
   (AMD 0x1002) in the KFD node properties file before declaring an AMD
   GPU present. NVIDIA KFD nodes carry vendor_id 4318 (0x10DE) and are
   now skipped.

2. install_python_stack.py _has_rocm_gpu sysfs fallback: same vendor_id
   guard. Also preserves the existing fallback for older kernels that
   don't ship a properties file (trusts gpu_id alone there).

3. install.sh now exports UNSLOTH_TORCH_BACKEND ("cuda"/"rocm"/"cpu")
   immediately after get_torch_index_url() resolves the wheel family.
   install_python_stack.py reads this as _TORCH_BACKEND and short-circuits
   _ensure_rocm_torch() entirely on cuda/cpu hosts, providing a second
   layer of defense that is independent of subprocess GPU detection.

Tests: 9 new cases in TestHasRocmGpuKfdVendorGuard,
TestEnsureRocmTorch, and TestInstallShStructure cover all three changes.
Full test_rocm_support.py suite: 289 passed, 2 skipped, 0 failed.

Closes #6172

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: show actual torch backend in progress step labels

The 'ROCm torch check' and 'ROCm torch (final)' step labels were
hardcoded regardless of whether the installer was targeting CUDA, ROCm,
or CPU. On NVIDIA hosts they showed 'ROCm' even though no ROCm wheels
were being installed, which was misleading.

Add _torch_step_label(suffix) which reads UNSLOTH_TORCH_BACKEND (set by
install.sh) and formats the label as e.g. 'torch check (cuda)' or
'torch final (rocm)'. Falls back to live GPU detection for standalone
studio update runs that bypass install.sh.

* fix: make KFD sysfs vendor check conservative -- skip if no properties file

The previous implementation fell through to `return True` when the KFD
node's properties file was missing (OSError), intending to support older
kernels. But NVIDIA open driver KFD nodes can also lack a properties file
on some kernel versions, so the fallback still produced a false positive.

Change the `except OSError: pass` to `continue` so any node without a
readable properties file is skipped rather than trusted. KFD properties
files exist on every kernel version that actually exposes /sys/class/kfd,
so this does not regress real AMD GPU detection -- if the directory exists
at all, properties files will be present for genuine GPU nodes.

* fix: bulletproof NVIDIA vs AMD GPU detection

Four changes that together ensure ROCm torch can never be installed on an
NVIDIA host regardless of which detection path fires:

1. _has_rocm_gpu() (Python): NVIDIA guard at the top -- returns False
   immediately when _has_usable_nvidia_gpu() is True, blocking rocminfo,
   amd-smi, and KFD sysfs from producing a false positive even when ROCm
   tools are co-installed alongside the NVIDIA driver.

2. _has_amd_rocm_gpu() (install.sh): same NVIDIA guard -- calls
   _has_usable_nvidia_gpu first and returns 1 if it succeeds.

3. _has_usable_nvidia_gpu() (Python): adds /proc/driver/nvidia/gpus/
   sysfs fallback. The NVIDIA driver populates this directory on Linux
   regardless of nvidia-smi state, so a subprocess PATH gap, timeout, or
   driver initialisation race can no longer silence NVIDIA detection.

4. _has_usable_nvidia_gpu() (install.sh): same /proc/driver/nvidia/gpus
   fallback, tried after nvidia-smi -L rather than instead of it.

Together: NVIDIA wins at every decision point. If nvidia-smi works, it
confirms NVIDIA. If it fails, /proc/driver/nvidia confirms NVIDIA. If
somehow both fail, _has_rocm_gpu still checks NVIDIA first before any AMD
path runs.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: two KFD/proc-only corner cases from Codex review

1. KFD awk state not reset per node file (Ryzen+NVIDIA false positive):
   The awk glob processes all topology node properties files in one pass.
   Without FNR==1 reset, a Ryzen+NVIDIA host where an AMD CPU-agent node
   sets amd=1 (vendor_id 4098, gpu_id 0) can combine with a later NVIDIA
   node setting gpu=1 (gpu_id > 0), triggering found=1 before vendor_id
   4318 is seen. Added FNR==1{ gpu=0; amd=0 } to reset per file.

2. proc-only NVIDIA not reaching CUDA wheel selection:
   _has_usable_nvidia_gpu returning true via /proc/driver/nvidia fallback
   left _smi empty, so get_torch_index_url entered the AMD/CPU branch and
   selected CPU wheels despite NVIDIA being confirmed. Introduced
   _nvidia_detected flag (separate from _smi) so the AMD branch is skipped
   whenever NVIDIA is confirmed by any path, while _cuda_ver reads from
   _smi when available (with the existing cu126 fallback when _smi is absent).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 install.sh                                |  49 ++++-
 studio/install_python_stack.py            | 115 +++++++++--
 tests/studio/install/test_rocm_support.py | 233 +++++++++++++++++++++-
 3 files changed, 366 insertions(+), 31 deletions(-)

diff --git a/install.sh b/install.sh
index befcaaa186..44d1c39d02 100755
--- a/install.sh
+++ b/install.sh
@@ -1717,8 +1717,15 @@ _ensure_rocm_probe_env() {
 
 # Returns 0 if an AMD GPU is present. Checks rocminfo, amd-smi, then sysfs
 # KFD topology (env-var-independent fallback for when HIP/ROCR_VISIBLE_DEVICES hides devices).
+# Always returns 1 (false) when an NVIDIA GPU is present: blocks every
+# detection path (rocminfo, amd-smi, KFD sysfs) from producing a false
+# positive on NVIDIA-only or NVIDIA-primary hosts, even when ROCm tools
+# are co-installed.
 _has_amd_rocm_gpu() {
     _ensure_rocm_probe_env
+    if _has_usable_nvidia_gpu; then
+        return 1
+    fi
     if command -v rocminfo >/dev/null 2>&1 && \
        rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
         return 0
@@ -1726,27 +1733,42 @@ _has_amd_rocm_gpu() {
          amd-smi list 2>/dev/null | awk '/^GPU[[:space:]]*[:\[][[:space:]]*[0-9]/{ found=1 } END{ exit !found }'; then
         return 0
     elif [ -e /dev/kfd ] && \
-         awk '/gpu_id/{ if ($2+0 > 0) found=1 } END{ exit !found }' \
+         awk 'FNR==1{ gpu=0; amd=0 } /gpu_id/{ gpu=($2+0>0) } /vendor_id/{ amd=($2==4098) } \
+              gpu && amd { found=1 } END{ exit !found }' \
              /sys/class/kfd/kfd/topology/nodes/*/properties 2>/dev/null; then
+        # vendor_id 4098 = 0x1002 (AMD). NVIDIA open kernel module (driver
+        # 560+) can register KFD topology nodes with non-zero gpu_id but
+        # vendor_id 4318 (0x10DE). Require AMD vendor to avoid misrouting
+        # NVIDIA-only hosts to the ROCm install path.
         return 0
     fi
     return 1
 }
 
 # ── NVIDIA usable-GPU helper ──
-# Returns 0 (true) only if nvidia-smi is present AND actually lists a GPU.
-# Prevents AMD-only hosts with a stale nvidia-smi on PATH from being routed
-# into the CUDA branch.
+# Returns 0 (true) if an NVIDIA GPU is present and usable.
+# Primary probe: nvidia-smi -L. Fallback: /proc/driver/nvidia/gpus/ sysfs,
+# which the NVIDIA driver populates on Linux regardless of nvidia-smi state
+# -- handles PATH gaps, subprocess timeouts, and driver init races that
+# could otherwise cause nvidia-smi to fail and silence NVIDIA detection.
 _has_usable_nvidia_gpu() {
     _nvsmi=""
     if command -v nvidia-smi >/dev/null 2>&1; then
         _nvsmi="nvidia-smi"
     elif [ -x "/usr/bin/nvidia-smi" ]; then
         _nvsmi="/usr/bin/nvidia-smi"
-    else
-        return 1
     fi
-    "$_nvsmi" -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'
+    if [ -n "$_nvsmi" ]; then
+        if "$_nvsmi" -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
+            return 0
+        fi
+    fi
+    # Fallback: NVIDIA driver exposes one subdir per GPU under this path.
+    if [ -d /proc/driver/nvidia/gpus ] && \
+       [ -n "$(ls -A /proc/driver/nvidia/gpus 2>/dev/null)" ]; then
+        return 0
+    fi
+    return 1
 }
 
 # ── Detect GPU and choose PyTorch index URL ──
@@ -1763,14 +1785,16 @@ get_torch_index_url() {
     # packages) is not sufficient: otherwise an AMD-only host would
     # silently install CUDA wheels.
     _smi=""
+    _nvidia_detected=0
     if _has_usable_nvidia_gpu; then
+        _nvidia_detected=1
         if command -v nvidia-smi >/dev/null 2>&1; then
             _smi="nvidia-smi"
         elif [ -x "/usr/bin/nvidia-smi" ]; then
             _smi="/usr/bin/nvidia-smi"
         fi
     fi
-    if [ -z "$_smi" ]; then
+    if [ "$_nvidia_detected" -eq 0 ]; then
         # No NVIDIA GPU -- check for AMD ROCm GPU.
         # PyTorch only publishes ROCm wheels for linux-x86_64; skip the
         # ROCm branch entirely on aarch64 / arm64 / other architectures
@@ -2098,6 +2122,15 @@ _maybe_bootstrap_rocm_wsl || true
 
 TORCH_INDEX_URL=$(get_torch_index_url)
 
+# Export the resolved torch backend ("cuda", "rocm", or "cpu") so that
+# downstream scripts (setup.sh -> install_python_stack.py) know what was
+# chosen here and can skip ROCm-specific repair steps on CUDA/CPU hosts.
+case "$TORCH_INDEX_URL" in
+    */rocm*|*/gfx*) export UNSLOTH_TORCH_BACKEND="rocm" ;;
+    */cpu)          export UNSLOTH_TORCH_BACKEND="cpu"  ;;
+    *)              export UNSLOTH_TORCH_BACKEND="cuda" ;;
+esac
+
 # rocm7.2 ships torch 2.11.0 -- adjust the constraint to allow it.
 # All other ROCm tags and CUDA stay within <2.11.0.
 case "$TORCH_INDEX_URL" in
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 0166bfd505..0460580922 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -557,7 +557,15 @@ def _persist_bnb_rocm_version(version: str) -> bool:
 
 
 def _has_rocm_gpu() -> bool:
-    """Return True only if an actual AMD GPU is visible (not just ROCm tools installed)."""
+    """Return True only if an actual AMD GPU is visible (not just ROCm tools installed).
+
+    Always returns False when an NVIDIA GPU is present -- NVIDIA takes
+    priority on mixed hosts and prevents every detection path below
+    (rocminfo, amd-smi, KFD sysfs) from producing a false positive even
+    if ROCm tools are installed alongside the NVIDIA driver.
+    """
+    if _has_usable_nvidia_gpu():
+        return False
     for cmd, check_fn in (
         # rocminfo: look for a real gfx GPU id (3-4 chars, nonzero first digit).
         # gfx000 is the CPU agent; ROCm 6.1+ also emits generic ISA lines like
@@ -598,6 +606,13 @@ def _has_rocm_gpu() -> bool:
     # runtime-only detection. On minimal package-managed installs (no
     # rocminfo / no amd-smi tools), the kernel exposes AMD GPUs via
     # /sys/class/kfd so `studio update` can still detect and repair.
+    #
+    # Guard: reject any KFD node whose properties file reports a non-AMD
+    # vendor. With the NVIDIA open kernel module (driver 560+), NVIDIA GPUs
+    # can register KFD topology nodes with a non-zero gpu_id; those nodes
+    # have vendor_id 4318 (0x10DE) rather than the AMD value 4098 (0x1002).
+    # Without this check the fallback returns True on NVIDIA-only systems,
+    # causing _ensure_rocm_torch to install ROCm wheels on NVIDIA hardware.
     if sys.platform != "win32":
         try:
             kfd_nodes = "/sys/class/kfd/kfd/topology/nodes"
@@ -609,29 +624,61 @@ def _has_rocm_gpu() -> bool:
                             gpu_id = fh.read().strip()
                     except OSError:
                         continue
-                    if gpu_id and gpu_id != "0":  # gpu_id 0 = CPU node
-                        return True
+                    if not gpu_id or gpu_id == "0":  # gpu_id 0 = CPU node
+                        continue
+                    # Require AMD vendor_id 4098 (0x1002) in the properties file.
+                    # KFD properties files exist on every kernel that exposes
+                    # /sys/class/kfd, so absence of the file means we cannot
+                    # confirm AMD ownership -- skip the node rather than risk a
+                    # false positive (e.g. NVIDIA open driver KFD nodes that
+                    # lack a properties file on some kernel versions).
+                    props_path = os.path.join(kfd_nodes, entry, "properties")
+                    try:
+                        with open(props_path) as fh:
+                            props = fh.read()
+                    except OSError:
+                        continue  # can't confirm vendor -- skip
+                    if not re.search(r"\bvendor_id\s+4098\b", props):
+                        continue
+                    return True
         except OSError:
             pass
     return False
 
 
 def _has_usable_nvidia_gpu() -> bool:
-    """Return True only when nvidia-smi exists AND reports at least one GPU."""
+    """Return True when an NVIDIA GPU is present and usable.
+
+    Primary probe: nvidia-smi -L (subprocess).
+    Fallback: /proc/driver/nvidia/gpus/ sysfs (Linux only) -- handles the
+    case where nvidia-smi is present but the subprocess fails (PATH gap,
+    timeout, driver initialisation race). If either probe confirms an
+    NVIDIA GPU the function returns True so _has_rocm_gpu() is blocked.
+    """
     exe = shutil.which("nvidia-smi")
-    if not exe:
-        return False
-    try:
-        result = subprocess.run(
-            [exe, "-L"],
-            stdout = subprocess.PIPE,
-            stderr = subprocess.DEVNULL,
-            text = True,
-            timeout = 10,
-        )
-    except Exception:
-        return False
-    return result.returncode == 0 and "GPU " in result.stdout
+    if exe:
+        try:
+            result = subprocess.run(
+                [exe, "-L"],
+                stdout = subprocess.PIPE,
+                stderr = subprocess.DEVNULL,
+                text = True,
+                timeout = 10,
+            )
+            if result.returncode == 0 and "GPU " in result.stdout:
+                return True
+        except Exception:
+            pass
+    # Fallback: the NVIDIA driver exposes one subdirectory per GPU under
+    # /proc/driver/nvidia/gpus/ on Linux regardless of nvidia-smi state.
+    if sys.platform != "win32":
+        try:
+            gpu_dir = "/proc/driver/nvidia/gpus"
+            if os.path.isdir(gpu_dir) and os.listdir(gpu_dir):
+                return True
+        except OSError:
+            pass
+    return False
 
 
 def _detect_amd_gfx_codes() -> list[str]:
@@ -749,6 +796,13 @@ def _ensure_rocm_torch() -> None:
     Uses pip_install() to respect uv, constraints, and --python targeting.
     """
     global _rocm_windows_torch_installed
+    # install.sh sets UNSLOTH_TORCH_BACKEND to the resolved wheel family
+    # ("cuda", "rocm", "cpu"). Skip ROCm operations entirely when install.sh
+    # already selected a non-ROCm backend -- this is the authoritative signal
+    # and avoids re-running GPU detection in a subprocess that may see a
+    # different environment (different PATH, CUDA_VISIBLE_DEVICES, etc.).
+    if _TORCH_BACKEND in ("cuda", "cpu"):
+        return
     # setup.ps1 sets this after installing AMD wheels; skip the probe only when
     # torch is actually importable as ROCm. If the venv was wiped between runs,
     # the stale env-var would suppress a needed reinstall.
@@ -1088,6 +1142,29 @@ def _infer_no_torch() -> bool:
 
 NO_TORCH = _infer_no_torch()
 
+# UNSLOTH_TORCH_BACKEND is set by install.sh after get_torch_index_url() so
+# that this script knows which torch variant was selected without re-running
+# GPU detection. Values: "cuda", "rocm", or "cpu". Empty means unknown
+# (standalone `unsloth studio update` runs, where we re-detect normally).
+_TORCH_BACKEND: str = os.environ.get("UNSLOTH_TORCH_BACKEND", "").lower()
+
+
+def _torch_step_label(suffix: str) -> str:
+    """Return a progress label like 'torch check (cuda)' using the known backend.
+
+    Falls back to GPU detection when UNSLOTH_TORCH_BACKEND is not set (e.g.
+    standalone `unsloth studio update` runs that bypass install.sh).
+    """
+    backend = _TORCH_BACKEND
+    if not backend:
+        if _has_usable_nvidia_gpu():
+            backend = "cuda"
+        elif _has_rocm_gpu():
+            backend = "rocm"
+        else:
+            backend = "cpu"
+    return f"torch {suffix} ({backend})"
+
 
 # -- Verbosity control ----------------------------------------------------------
 # By default the installer shows a minimal in-place one-line progress bar.
@@ -1770,7 +1847,7 @@ def install_python_stack() -> int:
     #     venv got CPU-only torch (common when pip resolves torch from PyPI).
     #     Must follow base packages so torch is present for inspection.
     if not IS_MACOS and not NO_TORCH:
-        _progress("ROCm torch check")
+        _progress(_torch_step_label("check"))
         _ensure_rocm_torch()
 
     # Windows + AMD GPU: warn if ROCm torch was not installed (wrong Python
@@ -1955,7 +2032,7 @@ def install_python_stack() -> int:
     #     Running the repair last ensures ROCm torch is in place at runtime,
     #     whichever intermediate step clobbered it.
     if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:
-        _progress("ROCm torch (final)")
+        _progress(_torch_step_label("final"))
         _ensure_rocm_torch()
 
     # 14. Final check (silent; third-party conflicts are expected)
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 973c0a1e81..6bc94e3d0f 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -719,6 +719,143 @@ class TestEnsureRocmTorch:
                 _ensure_rocm_torch()
         mock_pip.assert_not_called()
 
+    @patch.object(stack_mod, "pip_install")
+    @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
+    @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = True)
+    def test_torch_backend_cuda_env_skips_entirely(self, mock_nvidia, mock_gpu, mock_pip):
+        """UNSLOTH_TORCH_BACKEND=cuda must short-circuit before any GPU probe."""
+        with patch.dict(os.environ, {"UNSLOTH_TORCH_BACKEND": "cuda"}):
+            # Reload _TORCH_BACKEND from the patched environment.
+            with patch.object(stack_mod, "_TORCH_BACKEND", "cuda"):
+                _ensure_rocm_torch()
+        mock_pip.assert_not_called()
+
+    @patch.object(stack_mod, "pip_install")
+    @patch.object(stack_mod, "_has_rocm_gpu", return_value = True)
+    @patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = True)
+    def test_torch_backend_cpu_env_skips_entirely(self, mock_nvidia, mock_gpu, mock_pip):
+        """UNSLOTH_TORCH_BACKEND=cpu must short-circuit before any GPU probe."""
+        with patch.dict(os.environ, {"UNSLOTH_TORCH_BACKEND": "cpu"}):
+            with patch.object(stack_mod, "_TORCH_BACKEND", "cpu"):
+                _ensure_rocm_torch()
+        mock_pip.assert_not_called()
+
+
+# TEST: install_python_stack.py -- _has_rocm_gpu KFD sysfs vendor_id guard
+
+
+class TestHasRocmGpuKfdVendorGuard:
+    """Verify that the KFD sysfs fallback rejects non-AMD (NVIDIA) KFD nodes.
+
+    These tests are source-level: they verify the regex and logic present in
+    the _has_rocm_gpu implementation rather than running the sysfs traversal
+    (which requires Linux path conventions).
+    """
+
+    def _src(self) -> str:
+        """Return the source of _has_rocm_gpu from install_python_stack.py."""
+        import inspect
+        return inspect.getsource(stack_mod._has_rocm_gpu)
+
+    def test_vendor_id_check_present(self):
+        """_has_rocm_gpu sysfs fallback must check vendor_id 4098 (AMD 0x1002)."""
+        src = self._src()
+        assert "vendor_id" in src, (
+            "_has_rocm_gpu KFD sysfs fallback must read the properties file "
+            "to check vendor_id and exclude NVIDIA KFD nodes"
+        )
+        assert "4098" in src, (
+            "_has_rocm_gpu must require AMD vendor_id 4098 (0x1002) in the "
+            "KFD node properties to avoid false positives on NVIDIA systems"
+        )
+
+    def test_vendor_regex_pattern_anchored(self):
+        """The vendor_id regex must use a word boundary to avoid partial matches."""
+        import re as _re
+
+        src = self._src()
+        # The pattern should have a word boundary before and after the number
+        # so "vendor_id 41098" doesn't match "vendor_id 4098".
+        assert (
+            _re.search(r"\\b.*vendor_id.*\\b", src) or "\\bvendor_id" in src
+        ), "_has_rocm_gpu vendor_id check should use word boundary anchors"
+
+    def test_sysfs_fallback_guarded_by_non_win32(self):
+        """KFD sysfs fallback must be Linux-only (guarded by sys.platform != 'win32')."""
+        src = self._src()
+        assert "win32" in src, "_has_rocm_gpu sysfs fallback must be guarded by sys.platform check"
+
+    def test_cpu_node_excluded(self):
+        """gpu_id == '0' must be excluded (CPU topology nodes)."""
+        src = self._src()
+        assert (
+            '!= "0"' in src or "== '0'" in src or "!= '0'" in src or '"0"' in src
+        ), "_has_rocm_gpu must skip gpu_id 0 nodes (CPU nodes)"
+
+    def test_install_sh_has_vendor_check(self):
+        """_has_amd_rocm_gpu in install.sh sysfs fallback must also check vendor_id 4098."""
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("_has_amd_rocm_gpu()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert "vendor_id" in func_body, "_has_amd_rocm_gpu sysfs fallback must check vendor_id"
+        assert "4098" in func_body, "_has_amd_rocm_gpu must require AMD vendor_id 4098 (0x1002)"
+
+    def test_has_rocm_gpu_returns_false_when_nvidia_present(self):
+        """_has_rocm_gpu must return False immediately when _has_usable_nvidia_gpu is True.
+
+        This is the primary guard: even if rocminfo, amd-smi, or KFD sysfs
+        produce a false positive, an NVIDIA GPU always wins.
+        """
+        with patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = True):
+            with patch("shutil.which", return_value = "/usr/bin/rocminfo"):
+                # Simulate rocminfo claiming an AMD GPU is present
+                mock_result = MagicMock()
+                mock_result.returncode = 0
+                mock_result.stdout = "Name: gfx1100\n"
+                with patch("subprocess.run", return_value = mock_result):
+                    assert not stack_mod._has_rocm_gpu(), (
+                        "_has_rocm_gpu must return False when NVIDIA GPU is detected, "
+                        "regardless of what rocminfo reports"
+                    )
+
+    def test_install_sh_has_rocm_gpu_nvidia_guard(self):
+        """_has_amd_rocm_gpu in install.sh must call _has_usable_nvidia_gpu and return 1 if true."""
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("_has_amd_rocm_gpu()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert (
+            "_has_usable_nvidia_gpu" in func_body
+        ), "_has_amd_rocm_gpu must call _has_usable_nvidia_gpu to block NVIDIA hosts"
+        assert (
+            "return 1" in func_body
+        ), "_has_amd_rocm_gpu must return 1 (false) when NVIDIA GPU is detected"
+
+    def test_has_usable_nvidia_gpu_proc_fallback_present(self):
+        """`_has_usable_nvidia_gpu` must have a /proc/driver/nvidia fallback."""
+        import inspect
+
+        src = inspect.getsource(stack_mod._has_usable_nvidia_gpu)
+        assert "/proc/driver/nvidia" in src, (
+            "_has_usable_nvidia_gpu must fall back to /proc/driver/nvidia/gpus when "
+            "nvidia-smi subprocess fails, to handle PATH gaps and driver init races"
+        )
+
+    def test_install_sh_has_usable_nvidia_gpu_proc_fallback(self):
+        """_has_usable_nvidia_gpu in install.sh must also have a /proc/driver/nvidia fallback."""
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("_has_usable_nvidia_gpu()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert "/proc/driver/nvidia" in func_body, (
+            "_has_usable_nvidia_gpu in install.sh must fall back to "
+            "/proc/driver/nvidia/gpus when nvidia-smi fails"
+        )
+
 
 # TEST: install_python_stack.py -- _ROCM_TORCH_INDEX mapping
 
@@ -927,16 +1064,21 @@ class TestInstallShStructure:
         source = sh_path.read_text(encoding = "utf-8")
         body = _extract_sh_function_body(source, "get_torch_index_url")
         nvidia_call = body.find("_has_usable_nvidia_gpu")
-        no_nvidia_branch = body.find('if [ -z "$_smi" ]')
+        # Gate changed from [ -z "$_smi" ] to [ "$_nvidia_detected" -eq 0 ] to
+        # handle proc-only NVIDIA hosts where nvidia-smi is absent but _has_usable_nvidia_gpu
+        # returns true via /proc/driver/nvidia/gpus.
+        no_nvidia_branch = body.find('if [ "$_nvidia_detected" -eq 0 ]')
+        if no_nvidia_branch < 0:
+            no_nvidia_branch = body.find('if [ -z "$_smi" ]')
         rocm_call = body.find("_has_amd_rocm_gpu")
         assert nvidia_call >= 0, "get_torch_index_url should call _has_usable_nvidia_gpu"
-        assert no_nvidia_branch >= 0, "get_torch_index_url should gate ROCm on no-nvidia-smi"
+        assert no_nvidia_branch >= 0, "get_torch_index_url should gate ROCm on no-nvidia branch"
         assert (
             rocm_call > no_nvidia_branch
-        ), "ROCm detection should sit inside the 'no nvidia-smi' branch"
+        ), "ROCm detection should sit inside the 'no NVIDIA' branch"
         assert (
             nvidia_call < no_nvidia_branch
-        ), "NVIDIA detection should run before the no-nvidia-smi branch"
+        ), "NVIDIA detection should run before the no-NVIDIA branch"
 
     def test_bitsandbytes_amd_install(self):
         """install.sh should install bitsandbytes for AMD when ROCm detected."""
@@ -1018,6 +1160,89 @@ class TestInstallShStructure:
         rocm_pos = func_body.find("amd-smi")
         assert darwin_pos < rocm_pos, "macOS check should come before ROCm detection"
 
+    def test_unsloth_torch_backend_exported_after_get_torch_index_url(self):
+        """install.sh must export UNSLOTH_TORCH_BACKEND after TORCH_INDEX_URL is set.
+
+        This lets install_python_stack.py skip ROCm torch operations on CUDA
+        and CPU hosts without re-running GPU detection in a subprocess.
+        """
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        torch_url_pos = source.find("TORCH_INDEX_URL=$(get_torch_index_url)")
+        backend_pos = source.find("UNSLOTH_TORCH_BACKEND")
+        assert backend_pos > 0, "UNSLOTH_TORCH_BACKEND must be set in install.sh"
+        assert (
+            backend_pos > torch_url_pos
+        ), "UNSLOTH_TORCH_BACKEND must be set AFTER TORCH_INDEX_URL is resolved"
+        # Verify all three cases are covered
+        assert '"cuda"' in source[backend_pos : backend_pos + 500]
+        assert '"rocm"' in source[backend_pos : backend_pos + 500]
+        assert '"cpu"' in source[backend_pos : backend_pos + 500]
+        # Must be exported so subprocesses (setup.sh, install_python_stack.py) see it
+        assert "export UNSLOTH_TORCH_BACKEND" in source
+
+    def test_kfd_sysfs_amd_vendor_check_in_has_amd_rocm_gpu(self):
+        """_has_amd_rocm_gpu sysfs fallback must require AMD vendor_id 4098.
+
+        NVIDIA open kernel module (560+) registers KFD nodes with vendor_id
+        4318 (0x10DE). Without the vendor check, _has_amd_rocm_gpu returns 0
+        (true) on NVIDIA-only hosts that have the nvidia-open driver, causing
+        get_torch_index_url to select a ROCm wheel index.
+        """
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("_has_amd_rocm_gpu()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert (
+            "vendor_id" in func_body
+        ), "_has_amd_rocm_gpu sysfs fallback must check vendor_id to exclude NVIDIA KFD nodes"
+        assert (
+            "4098" in func_body
+        ), "_has_amd_rocm_gpu sysfs fallback must require AMD vendor_id 4098 (0x1002)"
+
+    def test_kfd_awk_resets_state_per_file(self):
+        """KFD sysfs awk must reset gpu/amd state per file (FNR==1).
+
+        Without the reset, a Ryzen+NVIDIA host where node 0 is an AMD CPU
+        agent (vendor_id 4098, gpu_id 0) and node 1 is an NVIDIA GPU
+        (gpu_id > 0, vendor_id 4318) can produce a false positive: node 0
+        sets amd=1, node 1 sets gpu=1, and the combined state triggers found=1
+        before vendor_id 4318 is seen on node 1.
+        """
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("_has_amd_rocm_gpu()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert "FNR==1" in func_body, (
+            "_has_amd_rocm_gpu KFD awk must reset state per file with FNR==1 "
+            "to avoid false positives on Ryzen+NVIDIA hosts with multiple KFD nodes"
+        )
+
+    def test_get_torch_index_url_uses_nvidia_detected_flag(self):
+        """get_torch_index_url must track NVIDIA detection independently of _smi.
+
+        When _has_usable_nvidia_gpu returns true via /proc/driver/nvidia fallback
+        but nvidia-smi is not on PATH, _smi stays empty. Without a separate
+        _nvidia_detected flag, the function falls into the AMD/CPU branch even
+        though NVIDIA was confirmed, silently installing CPU wheels instead of CUDA.
+        """
+        sh_path = PACKAGE_ROOT / "install.sh"
+        source = sh_path.read_text(encoding = "utf-8")
+        func_start = source.find("get_torch_index_url()")
+        func_end = source.find("\n}", func_start)
+        func_body = source[func_start:func_end]
+        assert "_nvidia_detected" in func_body, (
+            "get_torch_index_url must use a _nvidia_detected flag (separate from "
+            "_smi) so that proc-only NVIDIA detection still selects CUDA wheels"
+        )
+        # The AMD/ROCm branch must be gated on _nvidia_detected being 0, not on
+        # _smi being empty.
+        assert (
+            '_nvidia_detected" -eq 0' in func_body or "_nvidia_detected" in func_body
+        ), "get_torch_index_url AMD branch must be skipped when _nvidia_detected=1"
+
 
 # TEST: Live regression on current host (NVIDIA B200 expected)
 

From 9e2d17cc2d298b088876110b4192fc1ca28b9383 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Wed, 10 Jun 2026 21:51:16 -0700
Subject: [PATCH 175/222] Tests: follow Compare chat into the More submenu in
 the extra UI driver (#6177)

PR #6153 taught the chat UI driver to find Compare chat inside the
decluttered plus menu (#6140) but the extra UI driver kept looking for
the old top-level item, so all three Studio UI CI workflows have been
red on main since (Compare nav not found). Mirror the same
hover-then-click More fallback here.
---
 tests/studio/playwright_extra_ui.py | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/tests/studio/playwright_extra_ui.py b/tests/studio/playwright_extra_ui.py
index 20c7bda87c..26c3c244ca 100644
--- a/tests/studio/playwright_extra_ui.py
+++ b/tests/studio/playwright_extra_ui.py
@@ -332,6 +332,21 @@ with sync_playwright() as p:
         plus_btn.click(force = True)
         page.wait_for_timeout(400)
         compare_item = page.get_by_role("menuitem", name = re.compile(r"Compare chat", re.I)).first
+        if compare_item.count() == 0:
+            # Compare chat moved into the "More" submenu; hover, then click fallback.
+            more_trigger = page.get_by_role("menuitem", name = re.compile(r"^More$", re.I)).first
+            if more_trigger.count() > 0:
+                more_trigger.hover()
+                page.wait_for_timeout(400)
+                compare_item = page.get_by_role(
+                    "menuitem", name = re.compile(r"Compare chat", re.I)
+                ).first
+                if compare_item.count() == 0:
+                    more_trigger.click(force = True)
+                    page.wait_for_timeout(400)
+                    compare_item = page.get_by_role(
+                        "menuitem", name = re.compile(r"Compare chat", re.I)
+                    ).first
         if compare_item.count() > 0:
             compare_item.click(force = True)
             compare_opened = True

From 8961cf154fd518fad5d1479784e5d920142066fa Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 22:21:03 -0700
Subject: [PATCH 176/222] Give dark mode toasts a shadow and background
 separation (#6186)

---
 studio/frontend/src/index.css | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 797e17420e..cb54d95e68 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -1751,10 +1751,11 @@
 	margin: 0 !important;
 }
 
-/* Boost shadow on dark surfaces; mirrors .shadow-border / .menu-soft-surface pattern. */
+/* Composer shadow on the dark background color so toasts
+   do not merge into card-colored surfaces behind them. */
 .dark [data-sonner-toast][data-styled='true'] {
-	background-color: var(--card) !important;
-	box-shadow: none !important;
+	background-color: var(--background) !important;
+	box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16) !important;
 }
 
 /* Selectable toast text; non-selectable toast buttons. */

From 53af33798dd72681c4826b4f6b32d75767e2027a Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Thu, 11 Jun 2026 02:55:43 -0300
Subject: [PATCH 177/222] Studio: forward `preserve_thinking` +
 `reasoning_effort` on the OpenAI passthrough (#6171)

* Studio: forward preserve_thinking + reasoning_effort on the OpenAI passthrough

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Provide _request_reasoning_kwargs on the responses passthrough test backend mock

The OpenAI passthrough body builder now asks the active backend for
capability-gated reasoning kwargs. The responses stream adapter test fakes
the backend with a bare SimpleNamespace, so give it the same method a
non-reasoning template would expose (returns None, keeping
chat_template_kwargs out of the captured body).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Shorten the backend mock comment

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 studio/backend/routes/inference.py            | 37 ++++++--
 .../tests/test_openai_tool_passthrough.py     | 94 +++++++++++++++++++
 .../tests/test_responses_tool_passthrough.py  |  4 +
 3 files changed, 125 insertions(+), 10 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 70a5a3efe7..4cc76e7c2a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -5037,7 +5037,9 @@ async def _responses_stream(
             detail = "Image provided but current GGUF model does not support vision.",
         )
 
-    body = _build_openai_passthrough_body(chat_req, backend_ctx = llama_backend.context_length)
+    body = _build_openai_passthrough_body(
+        chat_req, backend_ctx = llama_backend.context_length, llama_backend = llama_backend
+    )
     body["stream_options"] = {"include_usage": True}
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
 
@@ -6743,7 +6745,11 @@ def _extract_response_format(payload):
     return rf if isinstance(rf, dict) else None
 
 
-def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
+def _build_openai_passthrough_body(
+    payload,
+    backend_ctx = None,
+    llama_backend = None,
+) -> dict:
     """Assemble the llama-server request body from a ChatCompletionRequest.
 
     Only known OpenAI / llama-server fields are forwarded, so Studio-specific
@@ -6754,12 +6760,19 @@ def _build_openai_passthrough_body(payload, backend_ctx = None) -> dict:
     system_prompt, _, _ = _extract_content_parts(payload.messages)
     messages = _set_or_prepend_system_message(messages, system_prompt)
     tool_choice = payload.tool_choice if payload.tool_choice is not None else "auto"
-    # When the caller asked for a specific reasoning mode, forward it via
-    # chat_template_kwargs so the Jinja template renders with (or without) the
-    # reasoning preamble.
-    tpl_kwargs = None
-    if payload.enable_thinking is not None:
-        tpl_kwargs = {"enable_thinking": bool(payload.enable_thinking)}
+    # Forward per-request reasoning fields (enable_thinking / reasoning_effort /
+    # preserve_thinking) via chat_template_kwargs so the Jinja template renders
+    # in the caller's mode, gated on the active template's capabilities exactly
+    # like the non-passthrough paths.
+    tpl_kwargs = (
+        llama_backend._request_reasoning_kwargs(
+            payload.enable_thinking,
+            payload.reasoning_effort,
+            payload.preserve_thinking,
+        )
+        if llama_backend is not None
+        else None
+    )
     return _build_passthrough_payload(
         messages,
         payload.tools,
@@ -6794,7 +6807,9 @@ async def _openai_passthrough_stream(
     the client sees a standard OpenAI response.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
-    body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
+    body = _build_openai_passthrough_body(
+        payload, backend_ctx = llama_backend.context_length, llama_backend = llama_backend
+    )
 
     _cancel_keys = (payload.cancel_id, payload.session_id, completion_id)
     _tracker = _TrackedCancel(cancel_event, *_cancel_keys)
@@ -6939,7 +6954,9 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
     ``tool_calls``, and accurate ``usage`` token counts.
     """
     target_url = f"{llama_backend.base_url}/v1/chat/completions"
-    body = _build_openai_passthrough_body(payload, backend_ctx = llama_backend.context_length)
+    body = _build_openai_passthrough_body(
+        payload, backend_ctx = llama_backend.context_length, llama_backend = llama_backend
+    )
 
     try:
         async with httpx.AsyncClient() as client:
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index db4c07cdc8..d8a965c1f2 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -654,6 +654,100 @@ class TestBuildPassthroughPayloadToolChoice:
         ]
 
 
+# =====================================================================
+# Passthrough reasoning kwargs — enable_thinking / reasoning_effort /
+# preserve_thinking must reach llama-server via chat_template_kwargs,
+# gated on template capabilities like the non-passthrough paths.
+# =====================================================================
+
+
+def _reasoning_backend(
+    supports_reasoning = True,
+    reasoning_style = "enable_thinking",
+    reasoning_always_on = False,
+    supports_preserve_thinking = False,
+):
+    """Bare LlamaCppBackend with just the reasoning capability flags set,
+    so _build_openai_passthrough_body exercises the real
+    _request_reasoning_kwargs gating."""
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    backend = LlamaCppBackend.__new__(LlamaCppBackend)
+    backend._supports_reasoning = supports_reasoning
+    backend._reasoning_style = reasoning_style
+    backend._reasoning_always_on = reasoning_always_on
+    backend._supports_preserve_thinking = supports_preserve_thinking
+    return backend
+
+
+class TestPassthroughReasoningKwargs:
+    def _payload(self, **fields):
+        return ChatCompletionRequest(
+            model = "default",
+            messages = [{"role": "user", "content": "hi"}],
+            **fields,
+        )
+
+    def test_enable_thinking_forwarded(self):
+        body = _build_openai_passthrough_body(
+            self._payload(enable_thinking = False),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(),
+        )
+        assert body["chat_template_kwargs"] == {"enable_thinking": False}
+
+    def test_preserve_thinking_forwarded_when_template_supports_it(self):
+        body = _build_openai_passthrough_body(
+            self._payload(enable_thinking = True, preserve_thinking = True),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(supports_preserve_thinking = True),
+        )
+        assert body["chat_template_kwargs"] == {
+            "enable_thinking": True,
+            "preserve_thinking": True,
+        }
+
+    def test_preserve_thinking_dropped_when_template_lacks_it(self):
+        body = _build_openai_passthrough_body(
+            self._payload(preserve_thinking = True),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(supports_preserve_thinking = False),
+        )
+        assert "chat_template_kwargs" not in body
+
+    def test_reasoning_effort_forwarded_for_effort_style_models(self):
+        body = _build_openai_passthrough_body(
+            self._payload(reasoning_effort = "high"),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(reasoning_style = "reasoning_effort"),
+        )
+        assert body["chat_template_kwargs"] == {"reasoning_effort": "high"}
+
+    def test_enable_thinking_maps_to_effort_for_effort_style_models(self):
+        body = _build_openai_passthrough_body(
+            self._payload(enable_thinking = False),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(reasoning_style = "reasoning_effort"),
+        )
+        assert body["chat_template_kwargs"] == {"reasoning_effort": "low"}
+
+    def test_always_on_reasoning_skips_thinking_kwargs(self):
+        body = _build_openai_passthrough_body(
+            self._payload(enable_thinking = False),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(reasoning_always_on = True),
+        )
+        assert "chat_template_kwargs" not in body
+
+    def test_no_reasoning_fields_omits_chat_template_kwargs(self):
+        body = _build_openai_passthrough_body(
+            self._payload(),
+            backend_ctx = 4096,
+            llama_backend = _reasoning_backend(supports_preserve_thinking = True),
+        )
+        assert "chat_template_kwargs" not in body
+
+
 # =====================================================================
 # OpenAI API compatibility helpers — verified spec edge cases
 # =====================================================================
diff --git a/studio/backend/tests/test_responses_tool_passthrough.py b/studio/backend/tests/test_responses_tool_passthrough.py
index f0f2714214..beeee66b77 100644
--- a/studio/backend/tests/test_responses_tool_passthrough.py
+++ b/studio/backend/tests/test_responses_tool_passthrough.py
@@ -533,6 +533,10 @@ class TestResponsesStreamAdapter:
                 is_vision = False,
                 context_length = 4096,
                 base_url = "http://llama.test",
+                # Non-reasoning template: the real backend returns None here.
+                _request_reasoning_kwargs = (
+                    lambda enable_thinking = None, reasoning_effort = None, preserve_thinking = None: None
+                ),
             ),
         )
 

From c8a7ba46438fa2cdfb0b170377af7260bb679439 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Wed, 10 Jun 2026 23:55:20 -0700
Subject: [PATCH 178/222] Tone down the green glow on the login and password
 setup pages (#6185)

* Make the auth page background glow much more subtle

* Keep light mode rays at 0.35 opacity, dark mode at 0.15
---
 studio/frontend/src/features/auth/change-password-page.tsx | 4 ++--
 studio/frontend/src/features/auth/login-page.tsx           | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/studio/frontend/src/features/auth/change-password-page.tsx b/studio/frontend/src/features/auth/change-password-page.tsx
index 96ee8dd1a8..30f840faca 100644
--- a/studio/frontend/src/features/auth/change-password-page.tsx
+++ b/studio/frontend/src/features/auth/change-password-page.tsx
@@ -10,11 +10,11 @@ export function ChangePasswordPage() {
     <div className="relative flex min-h-[calc(100dvh-var(--studio-titlebar-height,0px))] items-center justify-center overflow-hidden bg-background px-4 py-8 sm:px-6 sm:py-10 md:px-10">
       <LightRays
         count={6}
-        color="rgba(34, 197, 94, 0.25)"
+        color="rgba(34, 197, 94, 0.1)"
         blur={34}
         speed={15}
         length="70vh"
-        style={{ opacity: 0.4 }}
+        className="opacity-35 dark:opacity-15"
       />
       <Card className="relative z-10 w-full max-w-sm px-5 py-6 shadow-border ring-1 ring-border sm:px-6 sm:py-8">
         <AuthForm mode="change-password" />
diff --git a/studio/frontend/src/features/auth/login-page.tsx b/studio/frontend/src/features/auth/login-page.tsx
index eb33a6a71b..638df7d362 100644
--- a/studio/frontend/src/features/auth/login-page.tsx
+++ b/studio/frontend/src/features/auth/login-page.tsx
@@ -10,11 +10,11 @@ export function LoginPage() {
     <div className="relative flex min-h-[calc(100dvh-var(--studio-titlebar-height,0px))] items-center justify-center overflow-hidden bg-background px-4 py-8 sm:px-6 sm:py-10 md:px-10">
       <LightRays
         count={6}
-        color="rgba(34, 197, 94, 0.25)"
+        color="rgba(34, 197, 94, 0.1)"
         blur={34}
         speed={15}
         length="70vh"
-        style={{ opacity: 0.4 }}
+        className="opacity-35 dark:opacity-15"
       />
       <Card className="relative z-10 w-full max-w-sm px-5 py-6 shadow-border ring-0 sm:px-6 sm:py-8">
         <AuthForm mode="login" />

From 27d43a31f452b6761a7511a24e47df8389704402 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 00:00:50 -0700
Subject: [PATCH 179/222] MLX CI: drop removed --simple-policy and stale
 ggml-org pin from the prebuilt step (#6189)

#5963 folded the manifest resolver into the simple-path resolver,
removed the installer's --simple-policy flag, and moved macOS prebuilts
to the unslothai/llama.cpp fork. The MLX CI prebuilt step still passed
the deleted flag, so argparse exits 2 and the workflow has been red on
every main push since. Point the step at the fork with no extra flags,
exactly like studio/setup.sh on macOS.
---
 .github/workflows/mlx-ci.yml | 51 +++++++++---------------------------
 1 file changed, 12 insertions(+), 39 deletions(-)

diff --git a/.github/workflows/mlx-ci.yml b/.github/workflows/mlx-ci.yml
index 75940832a0..221e86f235 100644
--- a/.github/workflows/mlx-ci.yml
+++ b/.github/workflows/mlx-ci.yml
@@ -231,33 +231,14 @@ jobs:
             tests/studio/test_is_mlx_dispatch_gate.py \
             tests/studio/test_mlx_training_worker_behaviors.py
 
-      # Studio prebuilt llama.cpp install + GGUF inference. Drives the
-      # exact path Studio's setup.sh takes on macOS: invokes
-      # studio/install_llama_prebuilt.py with --published-repo
-      # ggml-org/llama.cpp and --published-release-tag b9049 (the
-      # latest llama.cpp release at the time this step was added; bump
-      # via UNSLOTH_LLAMA_TAG / DEFAULT_LLAMA_TAG when refreshing).
-      # The installer downloads llama-b9049-bin-macos-arm64.tar.gz,
-      # which is the universal Apple Silicon (arm64) build -- the
-      # same artifact works on M1/M2/M3/M4 because llama.cpp compiles
-      # against the ARMv8.2 baseline.
-      #
-      # The b9049 release also publishes:
-      #   - llama-b9049-bin-macos-arm64-kleidiai.tar.gz
-      #     KleidiAI dispatches at runtime; on M1 it falls back where
-      #     ISA features (e.g. I8MM) are missing, so this asset also
-      #     runs on M1 -- Studio just doesn't choose it by default.
-      #   - llama-b9049-bin-macos-x64.tar.gz
-      #     Intel-only; would only run on M1 via Rosetta 2 emulation,
-      #     which we explicitly avoid.
-      #   - iOS XCFramework
-      #     iOS-app build artifact, unrelated to a macOS desktop CI.
-      #
-      # After install, downloads a small published GGUF
-      # (unsloth/gemma-3-270m-it-GGUF, Q4_K_M) from HuggingFace and
-      # runs the prebuilt llama-cli on it. Asserts the prompt echo
-      # appears in stdout. If the install fails OR the binary exits
-      # non-zero, that's an Unsloth/Studio bug.
+      # Studio prebuilt llama.cpp install + GGUF inference. Mirrors the
+      # path Studio's setup.sh takes on macOS since #5963: plan against
+      # the unslothai/llama.cpp fork's latest release, which ships the
+      # bin-macos-arm64 bundle plus the llama-prebuilt-manifest.json the
+      # default policy reads. After install, downloads a small published
+      # GGUF (unsloth/gemma-3-270m-it-GGUF, Q4_K_M) and validates
+      # llama-server /completion end to end. An install failure or a
+      # non-zero binary exit is an Unsloth/Studio bug.
       - name: Studio prebuilt llama.cpp install + GGUF inference (Mac M1)
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
@@ -272,20 +253,12 @@ jobs:
           set -euo pipefail
           INSTALL_DIR="$HOME/.unsloth-studio-prebuilt-test/llama.cpp"
           rm -rf "$INSTALL_DIR"
-          # --simple-policy is required when --published-repo points
-          # at upstream ggml-org/llama.cpp; that repo doesn't ship the
-          # llama-prebuilt-manifest.json asset Studio's default policy
-          # expects, so the simple platform-specific policy maps
-          # Darwin+arm64 -> bin-macos-arm64 directly. studio/setup.sh
-          # passes both --published-repo ggml-org/llama.cpp AND
-          # --simple-policy automatically on macOS, so this CI step
-          # exercises the same code path users hit when they run
-          # `curl -fsSL https://unsloth.ai/install.sh | sh`.
+          # Mirror studio/setup.sh on macOS (the install.sh user path):
+          # it plans against the unslothai/llama.cpp fork's latest
+          # release with no policy or tag flags.
           python studio/install_llama_prebuilt.py \
             --install-dir "$INSTALL_DIR" \
-            --published-repo ggml-org/llama.cpp \
-            --published-release-tag b9049 \
-            --simple-policy
+            --published-repo unslothai/llama.cpp
 
           # Studio bundles only llama-server + llama-quantize from the
           # prebuilt (not llama-cli) -- inference goes through

From 898d3dd0b5937625f1724665e3892c7a905efbe7 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 02:45:12 -0700
Subject: [PATCH 180/222] Studio: offer the in-app llama.cpp update for
 source-build (markerless) installs (#6188)

* Studio: offer the in-app llama.cpp update for source-build (markerless) installs

Source-build installs have no UNSLOTH_PREBUILT_INFO.json marker, so freshness
reported supported=False and the Update button never showed (notably on macOS,
where the fork shipped no prebuilt before b9585 and setup fell back to a source
build). When an install has no marker but an official prebuilt now exists for
the host, surface the update and let one click swap it in place.

- install_llama_prebuilt.py: published_repo_for_host() (the setup.sh host->repo
  rule in Python) and a --resolve-prebuilt mode that reports whether a prebuilt
  exists for this host without downloading.
- llama_cpp_update.py: markerless branch in get_update_status/start_update,
  version-suppressed so source builds already newer than latest are not nagged;
  fail-open throughout.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: run llama update detection off the event loop, expose source_build

The markerless source-build check probes the host and reads GitHub, so run
get_update_status and start_update in a worker thread to keep the API
responsive. Expose source_build in the status response so the banner can label
the source-build switch.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Keep the llama-route auth stub out of sys.modules for the rest of the suite

test_llama_route.py replaced sys.modules['auth.authentication'] with a
bare stub at collection time and never restored it, so every later test
importing create_access_token got the stub: 17 failures across
test_desktop_auth, test_middleware, test_openai_tool_passthrough and
test_rag_preview on all four Backend CI Python versions. Import the
real module when its deps are available and only stub in minimal envs,
popping the stubs after the standalone route load either way.

* Studio: address review on the source-build update path

- published_repo_for_host: route CPU-only Windows to ggml-org too (mirrors
  setup.ps1; the fork ships no win-cpu bundle), macOS always the fork.
- markerless detection compares/display the upstream llama_tag, not a possible
  fork wrapper release_tag, so a source build is not wrongly judged newer.
- do not offer when there is no resolvable install root (a pinned
  LLAMA_SERVER_PATH outside a managed dir): an apply would not take effect.

* Ignore version probes in the update tests' subprocess capture

The status polls in these tests trigger the new source-build detection,
which shells out to llama-server --version through the same patched
subprocess.run. On slow runners that probe lands after the installer
call and clobbers the single captured argv, failing the flag
assertions (seen on the 3.10/3.11 Backend CI jobs). Skip probe calls
in all three fakes so only the installer invocation is captured.

* Skip markerless re-detection while the update job is swapping the tree

On a source-build install the frontend polls update-status every 3s
during an apply, and each poll ran _source_build_status, which execs
the very llama-server binary the job is concurrently replacing. On
Windows that exec can hold the exe long enough to fail the installer's
os.replace; everywhere it is a per-poll subprocess spawn for a status
the poller does not read (it only consumes job progress). Gate the
markerless branch on the job not running; the marked path is probe-free
and still returns the live job state.

* Studio: tighten source-build update root, repo routing, and downgrade guard

Only manage a markerless install when the active binary lives under a
resolvable llama.cpp root (marker dir, UNSLOTH_LLAMA_CPP_PATH it sits in,
or a llama.cpp ancestor); a pinned LLAMA_SERVER_PATH or a PATH/system
binary is left alone so an apply cannot install where it would not take
effect. Gate start_update on the same suppression as detection so a
direct POST cannot downgrade a source build newer than the latest
prebuilt. Route Linux hosts with AMD tooling (rocminfo/amd-smi/hipconfig/
hipinfo) to the fork in --resolve-prebuilt, matching setup.sh, so a HIP
source build is not offered an upstream CPU prebuilt.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: cover inactive env root and pinned llama.cpp checkout in update root tests

---------

Co-authored-by: danielhanchen <michaelhan2050@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/routes/llama.py                |  11 +-
 .../tests/test_install_resolve_prebuilt.py    | 173 ++++++++++
 studio/backend/tests/test_llama_cpp_update.py | 325 +++++++++++++++++-
 studio/backend/tests/test_llama_route.py      | 111 ++++++
 studio/backend/utils/llama_cpp_update.py      | 209 ++++++++++-
 studio/install_llama_prebuilt.py              |  65 ++++
 6 files changed, 873 insertions(+), 21 deletions(-)
 create mode 100644 studio/backend/tests/test_install_resolve_prebuilt.py
 create mode 100644 studio/backend/tests/test_llama_route.py

diff --git a/studio/backend/routes/llama.py b/studio/backend/routes/llama.py
index 11cc4c798e..b30c0f5aea 100644
--- a/studio/backend/routes/llama.py
+++ b/studio/backend/routes/llama.py
@@ -13,6 +13,7 @@ never blocks on a missing marker / offline GitHub.
 
 from __future__ import annotations
 
+import asyncio
 from typing import Optional
 
 from fastapi import APIRouter, Depends, Query
@@ -48,6 +49,9 @@ class LlamaUpdateStatusResponse(BaseModel):
     published_repo: Optional[str] = None
     installed_at_utc: Optional[str] = None
     age_days: Optional[int] = None
+    source_build: bool = Field(
+        False, description = "True when there is no marker (source build) but a prebuilt is offered."
+    )
     job: LlamaUpdateJob = Field(default_factory = LlamaUpdateJob)
 
 
@@ -65,11 +69,14 @@ async def llama_update_status(
     ),
     current_subject: str = Depends(get_current_subject),
 ) -> LlamaUpdateStatusResponse:
-    return LlamaUpdateStatusResponse(**get_update_status(force_refresh = force_refresh))
+    # Off the event loop: detection may probe the host and read GitHub.
+    status = await asyncio.to_thread(get_update_status, force_refresh = force_refresh)
+    return LlamaUpdateStatusResponse(**status)
 
 
 @router.post("/update", response_model = LlamaUpdateActionResponse)
 async def llama_update(
     current_subject: str = Depends(get_current_subject),
 ) -> LlamaUpdateActionResponse:
-    return LlamaUpdateActionResponse(**start_update())
+    action = await asyncio.to_thread(start_update)
+    return LlamaUpdateActionResponse(**action)
diff --git a/studio/backend/tests/test_install_resolve_prebuilt.py b/studio/backend/tests/test_install_resolve_prebuilt.py
new file mode 100644
index 0000000000..ede5629664
--- /dev/null
+++ b/studio/backend/tests/test_install_resolve_prebuilt.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""install_llama_prebuilt.py: host->repo mapping and the --resolve-prebuilt mode.
+
+These back the in-app update for source-build (markerless) installs: the backend
+asks the installer whether an official prebuilt exists for this host without
+downloading. Network and host detection are stubbed; no GPU or internet needed.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+_studio = Path(__file__).resolve().parent.parent.parent
+if str(_studio) not in sys.path:
+    sys.path.insert(0, str(_studio))
+
+ilp = importlib.import_module("install_llama_prebuilt")
+
+if not hasattr(ilp, "published_repo_for_host") or not hasattr(
+    ilp, "resolve_simple_install_release_plans"
+):
+    pytest.skip("PR symbols not present - check branch", allow_module_level = True)
+
+FORK = ilp.DEFAULT_PUBLISHED_REPO  # unslothai/llama.cpp
+UPSTREAM = ilp.UPSTREAM_REPO  # ggml-org/llama.cpp
+
+
+def _host(**kw):
+    base = dict(
+        system = "Linux",
+        machine = "x86_64",
+        is_windows = False,
+        is_linux = False,
+        is_macos = False,
+        is_x86_64 = False,
+        is_arm64 = False,
+        nvidia_smi = None,
+        driver_cuda_version = None,
+        compute_caps = [],
+        visible_cuda_devices = None,
+        has_physical_nvidia = False,
+        has_usable_nvidia = False,
+        has_rocm = False,
+        rocm_gfx_target = None,
+        macos_version = None,
+    )
+    base.update(kw)
+    return ilp.HostInfo(**base)
+
+
+def test_published_repo_for_host():
+    # CPU-only Linux (x64 and arm64) -> ggml-org upstream.
+    assert ilp.published_repo_for_host(_host(is_linux = True, is_x86_64 = True)) == UPSTREAM
+    assert (
+        ilp.published_repo_for_host(_host(is_linux = True, is_arm64 = True, machine = "aarch64"))
+        == UPSTREAM
+    )
+    # GPU Linux -> fork.
+    assert (
+        ilp.published_repo_for_host(_host(is_linux = True, is_x86_64 = True, has_usable_nvidia = True))
+        == FORK
+    )
+    assert ilp.published_repo_for_host(_host(is_linux = True, is_x86_64 = True, has_rocm = True)) == FORK
+    # CPU-only Windows -> ggml-org (setup.ps1: the fork ships no win-cpu bundle).
+    assert (
+        ilp.published_repo_for_host(_host(system = "Windows", is_windows = True, is_x86_64 = True))
+        == UPSTREAM
+    )
+    # GPU Windows -> fork.
+    assert (
+        ilp.published_repo_for_host(
+            _host(system = "Windows", is_windows = True, is_x86_64 = True, has_usable_nvidia = True)
+        )
+        == FORK
+    )
+    # macOS -> fork regardless of GPU (ggml-org macOS bundles need too-new macOS).
+    assert (
+        ilp.published_repo_for_host(
+            _host(system = "Darwin", is_macos = True, is_arm64 = True, machine = "arm64")
+        )
+        == FORK
+    )
+    # Linux with AMD tooling but no probed GPU -> fork (setup.sh routes on tooling).
+    assert (
+        ilp.published_repo_for_host(
+            _host(is_linux = True, is_x86_64 = True), linux_amd_tooling_present = True
+        )
+        == FORK
+    )
+    # The tooling hint is Linux-only: Windows CPU stays on ggml-org.
+    assert (
+        ilp.published_repo_for_host(
+            _host(system = "Windows", is_windows = True, is_x86_64 = True),
+            linux_amd_tooling_present = True,
+        )
+        == UPSTREAM
+    )
+
+
+def _run_resolve(monkeypatch, capsys, plans_or_exc):
+    monkeypatch.setattr(
+        ilp,
+        "detect_host",
+        lambda: _host(system = "Darwin", is_macos = True, is_arm64 = True, machine = "arm64"),
+    )
+
+    def _resolver(tag, host, repo, published_release_tag):
+        if isinstance(plans_or_exc, Exception):
+            raise plans_or_exc
+        return ("b9585", plans_or_exc)
+
+    monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _resolver)
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        ["install_llama_prebuilt.py", "--resolve-prebuilt", "latest", "--output-format", "json"],
+    )
+    rc = ilp.main()
+    assert rc == ilp.EXIT_SUCCESS
+    return json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+
+
+def test_resolve_prebuilt_available(monkeypatch, capsys):
+    plan = SimpleNamespace(
+        release_tag = "b9585",
+        llama_tag = "b9585",
+        attempts = [
+            SimpleNamespace(name = "llama-b9585-bin-macos-arm64.tar.gz", install_kind = "macos-arm64")
+        ],
+    )
+    out = _run_resolve(monkeypatch, capsys, [plan])
+    assert out["prebuilt_available"] is True
+    assert out["repo"] == FORK
+    assert out["release_tag"] == "b9585"
+    assert out["asset"] == "llama-b9585-bin-macos-arm64.tar.gz"
+    assert out["install_kind"] == "macos-arm64"
+
+
+def test_resolve_prebuilt_unavailable(monkeypatch, capsys):
+    out = _run_resolve(monkeypatch, capsys, ilp.PrebuiltFallback("no macOS asset"))
+    assert out["prebuilt_available"] is False
+    assert out["repo"] == FORK
+
+
+def test_resolve_prebuilt_linux_amd_tooling_routes_to_fork(monkeypatch, capsys):
+    # CPU-probed Linux host but rocminfo on PATH: the dispatch must route to the
+    # fork so a HIP source build is not offered an upstream CPU prebuilt.
+    monkeypatch.setattr(ilp, "detect_host", lambda: _host(is_linux = True, is_x86_64 = True))
+    monkeypatch.setattr(ilp.shutil, "which", lambda tool: tool == "rocminfo")
+    seen = {}
+
+    def _resolver(tag, host, repo, published_release_tag):
+        seen["repo"] = repo
+        raise ilp.PrebuiltFallback("no asset")
+
+    monkeypatch.setattr(ilp, "resolve_simple_install_release_plans", _resolver)
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        ["install_llama_prebuilt.py", "--resolve-prebuilt", "latest", "--output-format", "json"],
+    )
+    assert ilp.main() == ilp.EXIT_SUCCESS
+    out = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+    assert seen["repo"] == FORK
+    assert out["repo"] == FORK
diff --git a/studio/backend/tests/test_llama_cpp_update.py b/studio/backend/tests/test_llama_cpp_update.py
index d2c854cdee..05a107377c 100644
--- a/studio/backend/tests/test_llama_cpp_update.py
+++ b/studio/backend/tests/test_llama_cpp_update.py
@@ -60,24 +60,151 @@ def _write_install(
 def _clean_state(monkeypatch):
     freshness.reset_caches()
     upd._reset_job_for_tests()
+    upd._resolve_memo.clear()
+    # Deterministic markerless paths: no host-pinned binary, no custom dir.
+    monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+    monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
     # Never hit the network in these tests.
     monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: None)
     yield
     freshness.reset_caches()
     upd._reset_job_for_tests()
+    upd._resolve_memo.clear()
 
 
-def test_status_no_marker(monkeypatch, tmp_path):
+def _no_prebuilt(monkeypatch):
+    """Stub the host prebuilt probe to 'none available' (no source-build offer)."""
+    monkeypatch.setattr(upd, "_resolve_prebuilt_for_host", lambda *, force_refresh = False: None)
+
+
+def _prebuilt(
+    monkeypatch,
+    *,
+    repo = "unslothai/llama.cpp",
+    release_tag = "b9585",
+    llama_tag = None,
+    asset = None,
+):
+    """Stub the host prebuilt probe to report an available prebuilt."""
+    payload = {
+        "prebuilt_available": True,
+        "repo": repo,
+        "release_tag": release_tag,
+        "llama_tag": llama_tag or release_tag,
+        "asset": asset or f"llama-{release_tag}-bin-macos-arm64.tar.gz",
+        "install_kind": "macos-arm64",
+    }
+    monkeypatch.setattr(upd, "_resolve_prebuilt_for_host", lambda *, force_refresh = False: payload)
+
+
+def test_status_no_marker_no_prebuilt(monkeypatch, tmp_path):
+    # No marker AND no prebuilt available for the host -> unsupported (the genuine
+    # source-build-with-nothing-to-offer case).
     binary = tmp_path / "build" / "bin" / "llama-server"
     binary.parent.mkdir(parents = True)
     binary.write_text("stub")  # no marker file alongside
     monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    _no_prebuilt(monkeypatch)
     st = upd.get_update_status()
     assert st["supported"] is False
     assert st["update_available"] is False
     assert st["installed_tag"] is None
 
 
+def test_status_source_build_offers_prebuilt(monkeypatch, tmp_path):
+    # Markerless source build with a prebuilt now available for the host: surface
+    # the update. Unknown installed version (source build) is treated as behind.
+    binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    _prebuilt(monkeypatch, release_tag = "b9585")
+    monkeypatch.setattr(upd, "_installed_build_number", lambda b: None)
+    st = upd.get_update_status()
+    assert st["supported"] is True
+    assert st["update_available"] is True
+    assert st["source_build"] is True
+    assert st["latest_tag"] == "b9585"
+    assert st["published_repo"] == "unslothai/llama.cpp"
+
+
+def test_status_source_build_compares_llama_tag(monkeypatch, tmp_path):
+    # release_tag may be a fork wrapper (v1.0); compare/display the upstream
+    # llama_tag (b9457) so a source build is not wrongly judged newer.
+    binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    _prebuilt(monkeypatch, release_tag = "v1.0", llama_tag = "b9457")
+    monkeypatch.setattr(upd, "_installed_build_number", lambda b: 9000)
+    st = upd.get_update_status()
+    assert st["latest_tag"] == "b9457"  # not the wrapper tag
+    assert st["update_available"] is True  # 9000 < 9457
+
+
+def test_status_source_build_pinned_binary_not_offered(monkeypatch, tmp_path):
+    # LLAMA_SERVER_PATH pins a custom binary outside any llama.cpp dir; an apply
+    # could not take effect, so the button must not surface.
+    binary = tmp_path / "custom" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setenv("LLAMA_SERVER_PATH", str(binary))
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    _prebuilt(monkeypatch)
+    st = upd.get_update_status()
+    assert st["supported"] is False
+    assert st["update_available"] is False
+
+
+def test_llama_install_root_pinned_returns_none(monkeypatch, tmp_path):
+    binary = tmp_path / "custom" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setenv("LLAMA_SERVER_PATH", str(binary))
+    assert upd._llama_install_root(str(binary)) is None
+
+
+def test_status_source_build_suppressed_when_newer(monkeypatch, tmp_path):
+    # A source build already newer than the latest prebuilt is not nagged.
+    binary = tmp_path / "llama.cpp" / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    _prebuilt(monkeypatch, release_tag = "b9518")
+    monkeypatch.setattr(upd, "_installed_build_number", lambda b: 9600)
+    st = upd.get_update_status()
+    assert st["supported"] is True
+    assert st["update_available"] is False
+    assert st["installed_tag"] == "b9600"
+
+
+def test_status_source_build_skips_probe_while_job_runs(monkeypatch, tmp_path):
+    # While the updater swaps the tree, status polls must not exec the binary
+    # being replaced (on Windows that exec can fail the installer's os.replace);
+    # the 3s poller only consumes job progress.
+    binary = tmp_path / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    probes = {"resolve": 0, "version": 0}
+
+    def _count_resolve(*, force_refresh = False):
+        probes["resolve"] += 1
+        return None
+
+    def _count_version(b):
+        probes["version"] += 1
+        return None
+
+    monkeypatch.setattr(upd, "_resolve_prebuilt_for_host", _count_resolve)
+    monkeypatch.setattr(upd, "_installed_build_number", _count_version)
+    with upd._job_lock:
+        upd._job["state"] = upd._JOB_RUNNING
+    st = upd.get_update_status()
+    assert st["job"]["state"] == "running"
+    assert probes == {"resolve": 0, "version": 0}
+
+
 def test_status_update_available(monkeypatch, tmp_path):
     binary = _write_install(tmp_path, "b9493")
     monkeypatch.setattr(upd, "_find_binary", lambda: binary)
@@ -99,13 +226,62 @@ def test_status_up_to_date(monkeypatch, tmp_path):
     assert st["update_available"] is False
 
 
-def test_start_update_no_marker_refuses(monkeypatch, tmp_path):
+def test_start_update_no_marker_no_prebuilt_refuses(monkeypatch, tmp_path):
     binary = tmp_path / "llama-server"
     binary.write_text("stub")  # no marker
     monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    _no_prebuilt(monkeypatch)
     res = upd.start_update()
     assert res["started"] is False
-    assert res["reason"] == "no_prebuilt_marker"
+    assert res["reason"] == "no_prebuilt_available"
+
+
+def test_start_update_source_build_installs_prebuilt(monkeypatch, tmp_path):
+    # Markerless install + available prebuilt: install in place into the resolved
+    # root, with the asset-derived ROCm forwarding and the resolved repo.
+    install_dir = tmp_path / "llama.cpp"
+    binary = install_dir / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")  # no marker
+    monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    _prebuilt(
+        monkeypatch, repo = "unslothai/llama.cpp", asset = "app-b9585-linux-x64-rocm-gfx110X.tar.gz"
+    )
+
+    captured = {}
+
+    class _Proc:
+        returncode = 0
+        stdout = "installed"
+        stderr = ""
+
+    def _fake_run(cmd, **kwargs):
+        cmd = list(cmd)
+        # Status polls probe `llama-server --version`; keep the installer argv.
+        if "--version" in cmd:
+            return _Proc()
+        captured["cmd"] = cmd
+        _write_install(install_dir, "b9585")  # installer writes the marker
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+
+    res = upd.start_update()
+    assert res["started"] is True, res
+    deadline = time.time() + 10
+    while time.time() < deadline:
+        if upd.get_update_status()["job"]["state"] in ("success", "error"):
+            break
+        time.sleep(0.05)
+    cmd = captured["cmd"]
+    assert "--install-dir" in cmd and str(install_dir) in cmd
+    assert "--published-repo" in cmd and "unslothai/llama.cpp" in cmd
+    assert "--llama-tag" in cmd and "latest" in cmd
+    assert cmd[cmd.index("--rocm-gfx") + 1] == "gfx110x"
+    assert "--simple-policy" not in cmd and "--cpu-fallback" not in cmd
 
 
 def test_start_update_happy_path(monkeypatch, tmp_path):
@@ -123,6 +299,10 @@ def test_start_update_happy_path(monkeypatch, tmp_path):
         stderr = ""
 
     def _fake_run(cmd, **kwargs):
+        cmd = list(cmd)
+        # Status polls probe `llama-server --version`; keep the installer argv.
+        if "--version" in cmd:
+            return _Proc()
         captured["cmd"] = cmd
         # Simulate the installer writing a new marker with the latest tag.
         _write_install(install_dir, "b9518")
@@ -229,7 +409,11 @@ def _capture_install_cmd(
         stderr = ""
 
     def _fake_run(cmd, **kwargs):
-        captured["cmd"] = list(cmd)
+        cmd = list(cmd)
+        # Status polls probe `llama-server --version`; keep the installer argv.
+        if "--version" in cmd:
+            return _Proc()
+        captured["cmd"] = cmd
         _write_install(install_dir, latest, repo = repo, asset = asset)
         return _Proc()
 
@@ -442,3 +626,136 @@ def test_update_fails_open_when_backend_unavailable(monkeypatch, tmp_path):
             break
         time.sleep(0.05)
     assert job["state"] == "success", job
+
+
+# --- markerless helper units ---
+
+
+def test_resolve_prebuilt_parses_and_caches(monkeypatch, tmp_path):
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    calls = {"n": 0}
+
+    class _Proc:
+        returncode = 0
+        # stderr noise plus the JSON line on stdout (installer logs to stderr).
+        stdout = (
+            '{"prebuilt_available": true, "repo": "unslothai/llama.cpp", "release_tag": "b9585"}'
+        )
+        stderr = "[llama-prebuilt] some log\n"
+
+    def _fake_run(cmd, **kwargs):
+        calls["n"] += 1
+        assert "--resolve-prebuilt" in cmd
+        return _Proc()
+
+    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    res = upd._resolve_prebuilt_for_host()
+    assert res["prebuilt_available"] is True and res["release_tag"] == "b9585"
+    # Second call is memoized (no second subprocess).
+    upd._resolve_prebuilt_for_host()
+    assert calls["n"] == 1
+
+
+def test_resolve_prebuilt_fails_open(monkeypatch, tmp_path):
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+
+    def _boom(cmd, **kwargs):
+        raise OSError("subprocess failed")
+
+    monkeypatch.setattr(upd.subprocess, "run", _boom)
+    assert upd._resolve_prebuilt_for_host() is None
+    # Failures are not cached: a later success is observed.
+
+    class _Proc:
+        returncode = 0
+        stdout = '{"prebuilt_available": false}'
+        stderr = ""
+
+    monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+    assert upd._resolve_prebuilt_for_host() == {"prebuilt_available": False}
+
+
+def test_installed_build_number(monkeypatch):
+    def _ver(text):
+        class _Proc:
+            returncode = 0
+            stdout = ""
+            stderr = text
+
+        monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+        return upd._installed_build_number("/bin/llama-server")
+
+    assert _ver("version: 9585 (abc1234)\nbuilt with clang\n") == 9585
+    assert _ver("version: 1 (deadbee)\n") is None  # source build without tags
+    assert _ver("no version here") is None
+    assert upd._installed_build_number(None) is None
+
+
+def test_llama_install_root_finds_llama_cpp_ancestor(monkeypatch, tmp_path):
+    root = tmp_path / "llama.cpp"
+    binary = root / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
+    assert upd._llama_install_root(str(binary)) == root
+
+
+def test_llama_install_root_unmanaged_path_returns_none(monkeypatch, tmp_path):
+    # A binary on PATH (no marker, no env pin, no llama.cpp ancestor) is foreign:
+    # installing elsewhere would not replace it, so report no manageable root.
+    binary = tmp_path / "usr" / "local" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
+    assert upd._llama_install_root(str(binary)) is None
+
+
+def test_llama_install_root_unsloth_env_dir(monkeypatch, tmp_path):
+    # UNSLOTH_LLAMA_CPP_PATH dir holding the active binary is the managed root.
+    root = tmp_path / "vendor" / "llama"
+    binary = root / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(root))
+    assert upd._llama_install_root(str(binary)) == root
+
+
+def test_llama_install_root_ignores_inactive_env_root(monkeypatch, tmp_path):
+    # UNSLOTH_LLAMA_CPP_PATH set but the active binary is not under it: do not
+    # target the stale env root, resolve from the binary's own llama.cpp tree.
+    inactive = tmp_path / "custom-empty"
+    inactive.mkdir()
+    active = tmp_path / "llama.cpp"
+    binary = active / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(inactive))
+    assert upd._llama_install_root(str(binary)) == active
+
+
+def test_llama_install_root_refuses_pinned_checkout_under_llama_cpp(monkeypatch, tmp_path):
+    # The LLAMA_SERVER_PATH pin guard must run before the ancestor scan, or a
+    # user's own llama.cpp checkout could be handed to the installer.
+    root = tmp_path / "my-project" / "llama.cpp"
+    binary = root / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")
+    monkeypatch.setenv("LLAMA_SERVER_PATH", str(binary))
+    monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
+    assert upd._llama_install_root(str(binary)) is None
+
+
+def test_start_update_source_build_refuses_when_newer(monkeypatch, tmp_path):
+    # A direct POST on a source build already newer than the prebuilt must not
+    # downgrade it; start_update mirrors the detection suppression.
+    install_dir = tmp_path / "llama.cpp"
+    binary = install_dir / "build" / "bin" / "llama-server"
+    binary.parent.mkdir(parents = True)
+    binary.write_text("stub")  # no marker
+    monkeypatch.setattr(upd, "_find_binary", lambda: str(binary))
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    _prebuilt(monkeypatch, release_tag = "b9518")
+    monkeypatch.setattr(upd, "_installed_build_number", lambda b: 9600)
+    res = upd.start_update()
+    assert res["started"] is False
+    assert res["reason"] == "up_to_date"
diff --git a/studio/backend/tests/test_llama_route.py b/studio/backend/tests/test_llama_route.py
new file mode 100644
index 0000000000..bf0c4b731f
--- /dev/null
+++ b/studio/backend/tests/test_llama_route.py
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""routes/llama.py: the source_build field is exposed and the handlers run the
+(now subprocess-touching) detection off the event loop via a worker thread.
+
+The route file is loaded standalone with a stubbed auth dependency so the test
+does not pull the whole routes package (matplotlib-heavy training router) and
+works in a minimal env.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import sys
+import threading
+import types
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parents[1]
+if str(_BACKEND) not in sys.path:
+    sys.path.insert(0, str(_BACKEND))
+
+pytest.importorskip("fastapi")
+
+
+def _load_route():
+    # Prefer the real auth module; stub it only in minimal envs where its
+    # deps are absent. Stubs are popped after the load so they never leak
+    # into sys.modules for the rest of the suite.
+    stubbed = []
+    try:
+        import auth.authentication  # noqa: F401
+    except Exception:
+        auth_pkg = types.ModuleType("auth")
+        auth_pkg.__path__ = []
+        auth_mod = types.ModuleType("auth.authentication")
+        auth_mod.get_current_subject = lambda: "test"
+        for name, stub in (("auth", auth_pkg), ("auth.authentication", auth_mod)):
+            if name not in sys.modules:
+                sys.modules[name] = stub
+                stubbed.append(name)
+    try:
+        spec = importlib.util.spec_from_file_location(
+            "llama_route_under_test", str(_BACKEND / "routes" / "llama.py")
+        )
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules["llama_route_under_test"] = mod  # so pydantic resolves forward refs
+        spec.loader.exec_module(mod)
+        return mod
+    finally:
+        for name in stubbed:
+            sys.modules.pop(name, None)
+
+
+rl = _load_route()
+
+
+def test_status_response_exposes_source_build():
+    payload = {
+        "supported": True,
+        "update_available": True,
+        "stale": False,
+        "installed_tag": None,
+        "latest_tag": "b9585",
+        "published_repo": "unslothai/llama.cpp",
+        "installed_at_utc": None,
+        "age_days": None,
+        "source_build": True,
+        "job": {"state": "idle"},
+    }
+    model = rl.LlamaUpdateStatusResponse(**payload)
+    assert model.model_dump()["source_build"] is True
+    # Extra/unknown keys must not crash the response model.
+    rl.LlamaUpdateStatusResponse(**{**payload, "unexpected": 1})
+
+
+def test_status_handler_runs_off_event_loop(monkeypatch):
+    seen = {}
+
+    def fake_status(force_refresh = False):
+        seen["thread"] = threading.current_thread()
+        return {
+            "supported": True,
+            "update_available": True,
+            "source_build": True,
+            "latest_tag": "b9585",
+            "job": {"state": "idle"},
+        }
+
+    monkeypatch.setattr(rl, "get_update_status", fake_status)
+    out = asyncio.run(rl.llama_update_status(force_refresh = False, current_subject = "t"))
+    assert out.source_build is True
+    # Detection ran in a worker thread, not the event-loop thread.
+    assert seen["thread"] is not threading.main_thread()
+
+
+def test_update_handler_runs_off_event_loop(monkeypatch):
+    seen = {}
+
+    def fake_start():
+        seen["thread"] = threading.current_thread()
+        return {"started": True, "reason": None, "job": {"state": "running"}}
+
+    monkeypatch.setattr(rl, "start_update", fake_start)
+    out = asyncio.run(rl.llama_update(current_subject = "t"))
+    assert out.started is True
+    assert seen["thread"] is not threading.main_thread()
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index 19946b7966..b138b29af3 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -21,6 +21,7 @@ Design notes:
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import subprocess
@@ -108,6 +109,143 @@ def _installer_script() -> Optional[Path]:
     return None
 
 
+# Markerless (source-build) installs have no UNSLOTH_PREBUILT_INFO.json, so we
+# ask the installer whether an official prebuilt now exists for this host. Memo
+# is 24h; only successful answers are cached so a network blip retries.
+_RESOLVE_TTL_SECONDS = 24 * 60 * 60
+_resolve_memo: dict = {}
+
+
+def _resolve_prebuilt_for_host(*, force_refresh: bool = False) -> Optional[dict]:
+    """Run install_llama_prebuilt.py --resolve-prebuilt (no download) and return
+    {prebuilt_available, repo, release_tag, llama_tag, asset, install_kind} or
+    None. Fail-open: any error -> None so a source build never blocks the app."""
+    now = time.time()
+    if not force_refresh and _resolve_memo:
+        if now - _resolve_memo.get("at", 0.0) < _RESOLVE_TTL_SECONDS:
+            return _resolve_memo.get("value")
+    script = _installer_script()
+    if script is None:
+        return None
+    value: Optional[dict] = None
+    try:
+        proc = subprocess.run(
+            [
+                sys.executable,
+                str(script),
+                "--resolve-prebuilt",
+                "latest",
+                "--output-format",
+                "json",
+            ],
+            capture_output = True,
+            text = True,
+            timeout = 60,
+        )
+        out = (proc.stdout or "").strip()
+        if proc.returncode == 0 and out:
+            parsed = json.loads(out.splitlines()[-1])
+            if isinstance(parsed, dict):
+                value = parsed
+    except Exception as exc:  # pragma: no cover - subprocess/json defensive
+        logger.debug("llama update: resolve-prebuilt failed", error = str(exc))
+        value = None
+    if value is not None:  # cache real answers; let failures retry next poll
+        _resolve_memo.update(at = now, value = value)
+    return value
+
+
+def _installed_build_number(binary: Optional[str]) -> Optional[int]:
+    """Best-effort build number from ``llama-server --version`` (e.g.
+    'version: 9585 (abc)'). None when unparseable or <= 1: a source build with
+    no git tags reports 'version: 1', which we treat as unknown (offer update)."""
+    if not binary:
+        return None
+    try:
+        proc = subprocess.run([binary, "--version"], capture_output = True, text = True, timeout = 20)
+    except Exception:  # pragma: no cover - defensive
+        return None
+    m = re.search(r"version:\s*(\d+)", (proc.stderr or "") + (proc.stdout or ""))
+    if not m:
+        return None
+    n = int(m.group(1))
+    return n if n > 1 else None
+
+
+def _is_under(path: Path, root: Path) -> bool:
+    try:
+        p, r = path.resolve(), root.resolve()
+    except (OSError, ValueError):
+        p, r = path, root
+    return p == r or r in p.parents
+
+
+def _llama_install_root(binary: Optional[str]) -> Optional[Path]:
+    """The Studio-managed llama.cpp root the active binary lives under, or None
+    when the binary is unmanaged. Installing anywhere the active binary is not
+    would not replace what _find_llama_server_binary runs (which prefers a pinned
+    LLAMA_SERVER_PATH, then UNSLOTH_LLAMA_CPP_PATH, then a llama.cpp tree), so we
+    refuse rather than silently install into an inactive or foreign tree."""
+    marked = _install_dir_for(binary)
+    if marked is not None:
+        return marked
+    if not binary:
+        return None
+    # LLAMA_SERVER_PATH is an explicit user pin that always wins in discovery;
+    # never auto-replace its tree (even a user's own llama.cpp checkout).
+    if os.environ.get("LLAMA_SERVER_PATH"):
+        return None
+    p = Path(binary)
+    env = os.environ.get("UNSLOTH_LLAMA_CPP_PATH")
+    if env and _is_under(p, Path(env)):
+        return Path(env)
+    for parent in p.parents:
+        if parent.name == "llama.cpp":
+            return parent
+    # PATH / system / custom install: not a managed tree, so do not offer.
+    return None
+
+
+def _source_build_status(binary: str, *, force_refresh: bool) -> Optional[dict]:
+    """Update status for a markerless (source-build) install: offer the official
+    prebuilt when one exists for this host and is newer than the installed
+    binary. None -> caller falls through to the no-marker default (unsupported)."""
+    res = _resolve_prebuilt_for_host(force_refresh = force_refresh)
+    if not res or not res.get("prebuilt_available"):
+        return None
+    # llama_tag is the upstream build (bNNNN, what --version reports); release_tag
+    # can be a fork wrapper tag, so compare/display against llama_tag.
+    latest = res.get("llama_tag") or res.get("release_tag")
+    if not latest:
+        return None
+    # No resolvable install root (e.g. a pinned LLAMA_SERVER_PATH we cannot
+    # manage) means an apply would not take effect, so do not offer.
+    if _llama_install_root(binary) is None:
+        return None
+    installed_build = _installed_build_number(binary)
+    m = re.search(r"(\d+)", latest)
+    latest_build = int(m.group(1)) if m else None
+    # Suppress only when the source build is reliably newer/equal; unknown
+    # version (the involuntary source-build case) is treated as behind.
+    update_available = (
+        installed_build is None or latest_build is None or installed_build < latest_build
+    )
+    with _job_lock:
+        job = dict(_job)
+    return {
+        "supported": True,
+        "update_available": update_available,
+        "stale": False,
+        "installed_tag": (f"b{installed_build}" if installed_build else None),
+        "latest_tag": latest,
+        "published_repo": res.get("repo"),
+        "installed_at_utc": None,
+        "age_days": None,
+        "source_build": True,
+        "job": job,
+    }
+
+
 def get_update_status(*, force_refresh: bool = False) -> dict:
     """Report whether a newer prebuilt exists plus the current job state.
 
@@ -115,6 +253,20 @@ def get_update_status(*, force_refresh: bool = False) -> dict:
     """
     binary = _find_binary()
     marker = read_install_marker(binary)
+
+    with _job_lock:
+        job_running = _job["state"] == _JOB_RUNNING
+
+    # No marker = source build / custom path. Offer the official prebuilt if one
+    # now exists for this host (this is why macOS source builds showed no button).
+    # Skipped while the updater swaps the tree: each 3s poll would exec the
+    # half-replaced binary (on Windows that exec can make the installer's
+    # os.replace fail) and the poller only consumes job progress.
+    if marker is None and binary is not None and not job_running:
+        src = _source_build_status(binary, force_refresh = force_refresh)
+        if src is not None:
+            return src
+
     repo = (marker or {}).get("published_repo") or DEFAULT_PUBLISHED_REPO
 
     if force_refresh and repo:
@@ -143,6 +295,7 @@ def get_update_status(*, force_refresh: bool = False) -> dict:
         "published_repo": freshness.get("published_repo") or repo,
         "installed_at_utc": freshness.get("installed_at_utc"),
         "age_days": freshness.get("age_days"),
+        "source_build": False,
         "job": job,
     }
 
@@ -254,19 +407,7 @@ def start_update() -> dict:
     """Kick off a background update. Idempotent: a second call while one is
     running returns the in-flight job rather than starting another."""
     binary = _find_binary()
-    install_dir = _install_dir_for(binary)
     marker = read_install_marker(binary)
-    if install_dir is None or not marker:
-        return {
-            "started": False,
-            "reason": "no_prebuilt_marker",
-            "message": (
-                "This llama.cpp install was not provisioned from an Unsloth "
-                "prebuilt (source build or custom path); in-app update is "
-                "unavailable."
-            ),
-            "job": get_update_status()["job"],
-        }
     script = _installer_script()
     if script is None:
         return {
@@ -275,9 +416,47 @@ def start_update() -> dict:
             "message": "install_llama_prebuilt.py could not be located.",
             "job": get_update_status()["job"],
         }
-    repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
-    from_tag = marker.get("tag") or marker.get("release_tag")
-    asset = marker.get("asset")
+
+    if marker:
+        install_dir = _install_dir_for(binary)
+        repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
+        from_tag = marker.get("tag") or marker.get("release_tag")
+        asset = marker.get("asset")
+    else:
+        # Source build / custom path: only proceed when the same detection logic
+        # would offer the update (prebuilt exists, install is behind, root is
+        # manageable), so a direct POST cannot downgrade a newer source build.
+        src = _source_build_status(binary, force_refresh = True) if binary else None
+        if src is None:
+            return {
+                "started": False,
+                "reason": "no_prebuilt_available",
+                "message": (
+                    "No official llama.cpp prebuilt is available for this host, "
+                    "so the source build cannot be swapped automatically."
+                ),
+                "job": get_update_status()["job"],
+            }
+        if not src.get("update_available"):
+            return {
+                "started": False,
+                "reason": "up_to_date",
+                "message": "The installed llama.cpp build is already at or newer than the latest prebuilt.",
+                "job": get_update_status()["job"],
+            }
+        res = _resolve_prebuilt_for_host()
+        install_dir = _llama_install_root(binary)
+        repo = (res or {}).get("repo") or DEFAULT_PUBLISHED_REPO
+        from_tag = None
+        asset = (res or {}).get("asset")
+
+    if install_dir is None:
+        return {
+            "started": False,
+            "reason": "no_install_dir",
+            "message": "Could not determine the llama.cpp install directory.",
+            "job": get_update_status()["job"],
+        }
 
     with _job_lock:
         if _job["state"] == _JOB_RUNNING:
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 822a32ddb8..f9425f5c4f 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -3045,6 +3045,21 @@ def _apply_host_overrides(
     return host
 
 
+def published_repo_for_host(host: HostInfo, *, linux_amd_tooling_present: bool = False) -> str:
+    """The release repo setup.sh / setup.ps1 pick for this host: macOS always the
+    fork (ggml-org macOS bundles need too-new macOS); else CPU-only Linux/Windows
+    -> ggml-org upstream (the fork ships no CPU bundle) and any usable GPU (NVIDIA
+    or ROCm) -> the fork. linux_amd_tooling_present mirrors setup.sh routing Linux
+    hosts that expose AMD tooling (rocminfo/amd-smi/hipconfig/hipinfo) to the fork
+    even when the probe cannot confirm an active GPU. Mirrors the shell routing."""
+    if host.is_macos:
+        return DEFAULT_PUBLISHED_REPO
+    has_gpu = (
+        host.has_usable_nvidia or host.has_rocm or (host.is_linux and linux_amd_tooling_present)
+    )
+    return DEFAULT_PUBLISHED_REPO if has_gpu else UPSTREAM_REPO
+
+
 def pick_windows_cuda_runtime(host: HostInfo) -> str | None:
     if not host.driver_cuda_version:
         return None
@@ -6690,6 +6705,16 @@ def parse_args() -> argparse.Namespace:
         const = "latest",
         help = ("Resolve the source-build fallback plan."),
     )
+    resolve_group.add_argument(
+        "--resolve-prebuilt",
+        nargs = "?",
+        const = "latest",
+        help = (
+            "Report whether an official prebuilt exists for this host without "
+            "downloading. Picks the host's published repo when --published-repo "
+            "is left at the default. Use --output-format json."
+        ),
+    )
     parser.add_argument(
         "--output-format",
         choices = ("plain", "json"),
@@ -6774,6 +6799,46 @@ def main() -> int:
         )
         return EXIT_SUCCESS
 
+    if args.resolve_prebuilt is not None:
+        # Host-aware "is a prebuilt available" probe, no download. A default repo
+        # means "pick the repo for this host"; PrebuiltFallback == source build.
+        host = _apply_host_overrides(
+            detect_host(),
+            override_has_rocm = args.has_rocm,
+            override_rocm_gfx = args.rocm_gfx,
+            force_cpu = args.cpu_fallback,
+        )
+        # setup.sh routes Linux hosts with AMD tooling to the fork even when no GPU
+        # is probed; mirror that so a HIP source build is not offered a CPU prebuilt.
+        amd_tooling = host.is_linux and any(
+            shutil.which(t) for t in ("rocminfo", "amd-smi", "hipconfig", "hipinfo")
+        )
+        repo = (
+            published_repo_for_host(host, linux_amd_tooling_present = amd_tooling)
+            if args.published_repo == DEFAULT_PUBLISHED_REPO
+            else args.published_repo
+        )
+        try:
+            _requested, plans = resolve_simple_install_release_plans(
+                args.resolve_prebuilt, host, repo, args.published_release_tag or ""
+            )
+            choice = plans[0].attempts[0] if plans and plans[0].attempts else None
+            if choice is None:
+                payload = {"prebuilt_available": False, "repo": repo}
+            else:
+                payload = {
+                    "prebuilt_available": True,
+                    "repo": repo,
+                    "release_tag": plans[0].release_tag,
+                    "llama_tag": plans[0].llama_tag,
+                    "asset": choice.name,
+                    "install_kind": choice.install_kind,
+                }
+        except PrebuiltFallback:
+            payload = {"prebuilt_available": False, "repo": repo}
+        emit_resolver_output(payload, output_format = args.output_format)
+        return EXIT_SUCCESS
+
     if not args.install_dir:
         raise SystemExit(
             "install_llama_prebuilt.py: --install-dir is required unless --resolve-llama-tag, --resolve-install-tag, or --resolve-source-build is used"

From fbaf5277870d79651c7787d3a25099d5cb0ff39d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 04:02:56 -0700
Subject: [PATCH 181/222] Add FastDiffusionModel slow path for text-diffusion
 models (DiffusionGemma) (#6158)

* Add FastDiffusionModel slow path for text-diffusion models (DiffusionGemma)

Text-diffusion models (DiffusionGemma) use a block-diffusion generate loop and a novel
backbone, so Unsloth's autoregressive kernel/compile patching does not apply. FastDiffusionModel
loads the unmodified HuggingFace model (outputs stay bit-identical to transformers) and adds only
the safe conveniences: 4bit/8bit loading, PEFT LoRA (attention + dense MLP; the fused 3D MoE
experts are noted as a follow-up), the (model, tokenizer) API, and for_inference/for_training.

FastModel.from_pretrained auto-routes diffusion model_types to this path, including a fallback that
aliases the legacy "diffusion_gemma" config to the "diffusion_gemma4" classes current transformers
ships. New file unsloth/models/diffusion.py; loader.py adds the dispatch and the slow-path-aware
get_peft_model / for_inference / for_training.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* FastDiffusionModel: use unsloth's standard dtype resolution

Match the FastModel loader instead of the one-line bf16/fp16 pick:
SUPPORTS_BFLOAT16 = is_bfloat16_supported(), default to bf16 when supported
else fp16, downgrade an explicit bf16 on unsupported hardware with a warning,
and assert a valid dtype.

---------

Co-authored-by: danielhanchen <danielhanchen@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/models/diffusion.py | 301 ++++++++++++++++++++++++++++++++++++
 unsloth/models/loader.py    |  51 ++++++
 2 files changed, 352 insertions(+)
 create mode 100644 unsloth/models/diffusion.py

diff --git a/unsloth/models/diffusion.py b/unsloth/models/diffusion.py
new file mode 100644
index 0000000000..12596b432e
--- /dev/null
+++ b/unsloth/models/diffusion.py
@@ -0,0 +1,301 @@
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+FastDiffusionModel: a transformers-only slow path for text-diffusion models (e.g. DiffusionGemma).
+
+These models use a block-diffusion sampling loop (custom generate) and a novel backbone, so we skip
+Unsloth's autoregressive kernel/compile patching and load the unmodified HF model (outputs stay
+bit-identical to transformers), keeping only the safe conveniences: 4bit/8bit loading, PEFT LoRA, the
+(model, tokenizer) API, and for_inference/for_training. Extend DIFFUSION_MODEL_TYPES as more land.
+"""
+
+import os
+import torch
+from transformers import AutoConfig, AutoProcessor, AutoTokenizer
+
+from ._utils import is_bfloat16_supported
+from .llama import logger
+
+__all__ = ["FastDiffusionModel", "DIFFUSION_MODEL_TYPES", "is_diffusion_model_type"]
+
+# transformers model_type strings routed to this slow path
+DIFFUSION_MODEL_TYPES = ("diffusion_gemma", "diffusion_gemma4")
+
+# Default LoRA targets: standard nn.Linear modules in the shared Gemma-4 backbone. The 128 MoE experts
+# are fused 3D Parameters (gate_up_proj/down_proj), not nn.Linear, so PEFT LoRA cannot target them.
+DIFFUSION_LORA_TARGETS = [
+    "q_proj",
+    "k_proj",
+    "v_proj",
+    "o_proj",  # attention
+    "gate_proj",
+    "up_proj",
+    "down_proj",  # dense (non-expert) MLP
+]
+
+# Vision tower uses a custom Linear with the same suffix names; exclude it so only the text path is wrapped.
+DIFFUSION_LORA_EXCLUDE = r".*(vision_tower|embed_vision).*"
+
+
+def is_diffusion_model_type(model_types):
+    """model_types: str or iterable -> True if any is a known diffusion model_type."""
+    if isinstance(model_types, str):
+        model_types = (model_types,)
+    return any(mt in DIFFUSION_MODEL_TYPES for mt in model_types)
+
+
+def _resolve_diffusion_model_class(config):
+    """Resolve the HF model class for a diffusion checkpoint from config.architectures."""
+    import transformers
+
+    archs = getattr(config, "architectures", None) or []
+    for arch in archs:
+        cls = getattr(transformers, arch, None)
+        if cls is not None:
+            return cls
+    # Fallbacks across naming revisions.
+    for name in (
+        "DiffusionGemmaForBlockDiffusion",
+        "DiffusionGemma4ModelForBlockDiffusion",
+        "DiffusionGemma4ForBlockDiffusion",
+    ):
+        cls = getattr(transformers, name, None)
+        if cls is not None:
+            return cls
+    raise RuntimeError(
+        f"Unsloth: could not resolve a diffusion model class from architectures={archs}. "
+        "Ensure you have the transformers build that ships the DiffusionGemma implementation."
+    )
+
+
+def _load_diffusion_config(model_name, token, trust_remote_code, revision, local_files_only):
+    """Load the config, aliasing the legacy ``diffusion_gemma`` model_type to the ``diffusion_gemma4``
+    classes current transformers ships. AutoConfig raises on the legacy type; catch that, rewrite the
+    type/arch names in-memory, and rebuild."""
+    try:
+        return AutoConfig.from_pretrained(
+            model_name,
+            token = token,
+            trust_remote_code = trust_remote_code,
+            revision = revision,
+            local_files_only = local_files_only,
+        )
+    except ValueError as e:
+        if "diffusion_gemma" not in str(e):
+            raise
+        import json
+        from transformers.utils import cached_file
+
+        cfg_path = cached_file(
+            model_name,
+            "config.json",
+            token = token,
+            revision = revision,
+            local_files_only = local_files_only,
+        )
+        with open(cfg_path, encoding = "utf-8") as f:
+            cd = json.load(f)
+        cd["model_type"] = "diffusion_gemma4"
+        cd.setdefault("architectures", ["DiffusionGemma4ModelForBlockDiffusion"])
+        if isinstance(cd.get("text_config"), dict):
+            cd["text_config"]["model_type"] = "diffusion_gemma4_text"
+        if isinstance(cd.get("vision_config"), dict):
+            cd["vision_config"]["model_type"] = "diffusion_gemma4_vision"
+        from transformers import DiffusionGemma4Config
+
+        return DiffusionGemma4Config.from_dict(cd)
+
+
+class FastDiffusionModel:
+    """transformers-only slow path for text-diffusion models."""
+
+    @staticmethod
+    def from_pretrained(
+        model_name = "google/diffusiongemma-26B-A4B-it",
+        max_seq_length = None,  # API-compat; diffusion uses canvas_length
+        dtype = None,
+        load_in_4bit = False,
+        load_in_8bit = False,
+        load_in_16bit = False,
+        full_finetuning = False,
+        token = None,
+        device_map = "auto",
+        trust_remote_code = False,
+        attn_implementation = "eager",  # exact match with the reference golden logits
+        revision = None,
+        return_tokenizer = True,
+        **kwargs,
+    ):
+        SUPPORTS_BFLOAT16 = is_bfloat16_supported()
+        if dtype is None:
+            dtype = torch.float16 if not SUPPORTS_BFLOAT16 else torch.bfloat16
+        elif dtype == torch.bfloat16 and not SUPPORTS_BFLOAT16:
+            logger.warning_once("Device does not support bfloat16. Will change to float16.")
+            dtype = torch.float16
+        assert dtype in (torch.float16, torch.bfloat16, torch.float32)
+
+        # Honor an explicit local_files_only; else fall back to the offline env vars.
+        local_files_only = kwargs.pop("local_files_only", None)
+        if local_files_only is None:
+            local_files_only = (
+                os.environ.get("HF_HUB_OFFLINE", "0") == "1"
+                or os.environ.get("TRANSFORMERS_OFFLINE", "0") == "1"
+            )
+        config = _load_diffusion_config(
+            model_name,
+            token,
+            trust_remote_code,
+            revision,
+            local_files_only,
+        )
+        model_type = getattr(config, "model_type", None)
+        if not is_diffusion_model_type(model_type):
+            raise RuntimeError(
+                f"Unsloth: FastDiffusionModel only supports diffusion model_types {DIFFUSION_MODEL_TYPES}, "
+                f"got '{model_type}'. Use FastModel/FastLanguageModel for autoregressive models."
+            )
+
+        model_cls = _resolve_diffusion_model_class(config)
+
+        load_kwargs = dict(
+            dtype = dtype,
+            device_map = device_map,
+            token = token,
+            trust_remote_code = trust_remote_code,
+            attn_implementation = attn_implementation,
+            revision = revision,
+            local_files_only = local_files_only,
+        )
+
+        # Optional bitsandbytes quant. The MoE experts (3D Parameters) are not nn.Linear so bnb skips
+        # them; only attention + dense MLP Linears quantize, lm_head/embeddings stay full precision.
+        if load_in_4bit or load_in_8bit:
+            from transformers import BitsAndBytesConfig
+            if load_in_4bit:
+                qcfg = BitsAndBytesConfig(
+                    load_in_4bit = True,
+                    bnb_4bit_use_double_quant = True,
+                    bnb_4bit_quant_type = "nf4",
+                    bnb_4bit_compute_dtype = dtype,
+                    llm_int8_skip_modules = [
+                        "lm_head",
+                        "embed_tokens",
+                        "experts",
+                        "self_conditioning",
+                        "router",
+                    ],
+                )
+            else:
+                qcfg = BitsAndBytesConfig(load_in_8bit = True)
+            load_kwargs["quantization_config"] = qcfg
+
+        print(f"==((  Unsloth: FastDiffusionModel (slow / transformers-only path)  ))==")
+        print(f"   Model: {model_name}  | class: {model_cls.__name__}  | model_type: {model_type}")
+        print(
+            f"   dtype: {dtype} | 4bit: {load_in_4bit} | 8bit: {load_in_8bit} | attn: {attn_implementation}"
+        )
+
+        model = model_cls.from_pretrained(model_name, **load_kwargs).eval()
+        # Mark before any early return so get_peft_model/for_* route to the slow path.
+        model._unsloth_slow_diffusion = True
+
+        if not return_tokenizer:
+            return model, None
+
+        # Prefer the processor (chat template + tokenizer); fall back to a bare tokenizer. Returned as
+        # "tokenizer" to match the Unsloth (model, tokenizer) contract.
+        try:
+            tokenizer = AutoProcessor.from_pretrained(
+                model_name,
+                token = token,
+                trust_remote_code = trust_remote_code,
+                revision = revision,
+                local_files_only = local_files_only,
+            )
+        except Exception:
+            tokenizer = AutoTokenizer.from_pretrained(
+                model_name,
+                token = token,
+                trust_remote_code = trust_remote_code,
+                revision = revision,
+                local_files_only = local_files_only,
+            )
+
+        return model, tokenizer
+
+    @staticmethod
+    def get_peft_model(
+        model,
+        r = 16,
+        target_modules = None,
+        lora_alpha = 16,
+        lora_dropout = 0.0,
+        bias = "none",
+        use_gradient_checkpointing = True,
+        random_state = 3407,
+        task_type = None,
+        **kwargs,
+    ):
+        """Attach a PEFT LoRA to the diffusion backbone (attention + dense MLP). No fused kernels."""
+        from peft import LoraConfig, get_peft_model as peft_get_peft_model
+
+        if target_modules is None:
+            target_modules = DIFFUSION_LORA_TARGETS
+
+        lora_kwargs = dict(
+            r = r,
+            lora_alpha = lora_alpha,
+            lora_dropout = lora_dropout,
+            bias = bias,
+            target_modules = target_modules,
+            task_type = task_type,  # None: diffusion has no standard CAUSAL_LM head
+            **{k: v for k, v in kwargs.items() if k in ("modules_to_save", "init_lora_weights")},
+        )
+        # Exclude the vision tower's custom (non-Linear) modules that share suffix names.
+        exclude = kwargs.get("exclude_modules", DIFFUSION_LORA_EXCLUDE)
+        try:
+            lora_config = LoraConfig(exclude_modules = exclude, **lora_kwargs)
+        except TypeError:
+            # Older PEFT without exclude_modules: scope the target to the text decoder by regex.
+            lora_kwargs["target_modules"] = (
+                r".*model\.decoder\.layers\.\d+\.(self_attn\.[qkvo]_proj|mlp\.(gate|up|down)_proj)"
+            )
+            lora_config = LoraConfig(**lora_kwargs)
+        if use_gradient_checkpointing:
+            model.gradient_checkpointing_enable()
+            if hasattr(model, "enable_input_require_grads"):
+                model.enable_input_require_grads()
+
+        model = peft_get_peft_model(model, lora_config)
+        model._unsloth_slow_diffusion = True
+        try:
+            model.print_trainable_parameters()
+        except Exception:
+            pass
+        return model
+
+    @staticmethod
+    def for_inference(model):
+        model.eval()
+        for _, m in model.named_modules():
+            if hasattr(m, "gradient_checkpointing"):
+                m.gradient_checkpointing = False
+        return model
+
+    @staticmethod
+    def for_training(model, use_gradient_checkpointing = True):
+        model.train()
+        if use_gradient_checkpointing and hasattr(model, "gradient_checkpointing_enable"):
+            model.gradient_checkpointing_enable()
+        return model
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 0ee9e49ba1..4dc3046928 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -829,6 +829,7 @@ from ..kernels import (
     post_patch_loss_function,
 )
 from .vision import FastBaseModel
+from .diffusion import FastDiffusionModel, is_diffusion_model_type
 from transformers import (
     AutoModelForCausalLM,
 )
@@ -846,6 +847,25 @@ class FastModel(FastBaseModel):
         model = _prepare_model_for_qat(model, qat_scheme)
         return model
 
+    @staticmethod
+    def get_peft_model(model, *args, **kwargs):
+        # Route text-diffusion models (slow path) to the transformers-only PEFT helper.
+        if getattr(model, "_unsloth_slow_diffusion", False):
+            return FastDiffusionModel.get_peft_model(model, *args, **kwargs)
+        return FastBaseModel.get_peft_model(model, *args, **kwargs)
+
+    @staticmethod
+    def for_inference(model):
+        if getattr(model, "_unsloth_slow_diffusion", False):
+            return FastDiffusionModel.for_inference(model)
+        return FastBaseModel.for_inference(model)
+
+    @staticmethod
+    def for_training(model, use_gradient_checkpointing = True):
+        if getattr(model, "_unsloth_slow_diffusion", False):
+            return FastDiffusionModel.for_training(model, use_gradient_checkpointing)
+        return FastBaseModel.for_training(model, use_gradient_checkpointing)
+
     @staticmethod
     def from_pretrained(
         model_name = "unsloth/Llama-3.2-11B-Vision-Instruct-bnb-4bit",
@@ -1065,6 +1085,24 @@ class FastModel(FastBaseModel):
                 local_files_only = True
                 kwargs["local_files_only"] = True
 
+        # Text-diffusion slow-path dispatch, factored so both the normal route (below) and the
+        # legacy-config fallback (in the AutoConfig except handler) share one call site.
+        def _dispatch_diffusion():
+            return FastDiffusionModel.from_pretrained(
+                model_name = model_name,
+                max_seq_length = max_seq_length,
+                dtype = dtype,
+                load_in_4bit = load_in_4bit,
+                load_in_8bit = load_in_8bit,
+                load_in_16bit = load_in_16bit,
+                full_finetuning = full_finetuning,
+                token = token,
+                device_map = device_map,
+                trust_remote_code = trust_remote_code,
+                revision = revision,
+                **kwargs,
+            )
+
         try:
             model_config = AutoConfig.from_pretrained(
                 model_name,
@@ -1078,6 +1116,12 @@ class FastModel(FastBaseModel):
             raise
         except Exception as error:
             autoconfig_error = str(error)
+            # Legacy text-diffusion configs use model_type "diffusion_gemma", which current
+            # transformers does not register by name (it ships "diffusion_gemma4"). AutoConfig
+            # raises before we can dispatch; route straight to the diffusion slow path, whose
+            # loader aliases the legacy type to the gemma4 classes.
+            if "diffusion_gemma" in autoconfig_error and is_diffusion_model_type("diffusion_gemma"):
+                return _dispatch_diffusion()
             if "architecture" in autoconfig_error:
                 if "qwen3_5" in autoconfig_error:
                     raise ImportError(
@@ -1126,6 +1170,13 @@ class FastModel(FastBaseModel):
         )
         model_types_all = ",".join(model_types) + ","
 
+        # ---- Text-diffusion models (e.g. DiffusionGemma) take a transformers-only slow path. ----
+        # These use a custom block-diffusion `generate` and a novel backbone, so we skip Unsloth's
+        # autoregressive kernel/compile patching and load the unmodified HF model (bit-identical to
+        # naive transformers), keeping only 4bit/8bit + PEFT LoRA conveniences.
+        if is_diffusion_model_type(model_types):
+            return _dispatch_diffusion()
+
         # Save model types and loading method
         lowered_model_name = model_name.lower()
         string = os.environ.get("UNSLOTH_MODEL_NAME", "") + model_types_all

From 28fe978549096004b5112385776dab9850d35b17 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 04:23:41 -0700
Subject: [PATCH 182/222] Lint CI: diff import-hoist check against the PR
 merge-base, not the base tip (#6190)

The import-hoist safety step built its changed-file list with a two-dot
diff against the base branch tip on a shallow clone. Once the base
branch moves past a PR's branch point, that diff includes every file
the base changed since, and the verifier compares newer base code
(BEFORE) against the PR's older snapshot (AFTER). This time-reversed
comparison reports the base branch's own refactors as blockers on PRs
that never touched those files, forcing branch updates or admin merges.

Resolve the true merge-base through the compare API, fetch that single
commit by SHA (clone stays shallow), and use it for both the file list
and --before. Verified against the PR 6137 failure: with the base tip
the step flags studio files from a later main commit; with the
merge-base the file list contains only the PR's own files and the
verifier passes.
---
 .github/workflows/lint-ci.yml | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/lint-ci.yml b/.github/workflows/lint-ci.yml
index 8cb3535075..bd859a6e9e 100644
--- a/.github/workflows/lint-ci.yml
+++ b/.github/workflows/lint-ci.yml
@@ -105,29 +105,37 @@ jobs:
         # exactly where a hoist refactor lives, and it skips brand-new
         # files whose re-export imports would otherwise look "unused".
         #
-        # actions/checkout uses fetch-depth: 1, so the base branch is not
-        # present locally. Fetch the single base commit with an explicit
-        # refspec so origin/<base> is reliably created (a bare
-        # `git fetch origin <ref>` only updates FETCH_HEAD in some
-        # configs). Two-dot diff avoids needing a merge-base on a shallow
-        # clone.
+        # Diff against the true merge-base, not the base tip. A two-dot
+        # diff against the tip re-lints every file the base branch
+        # changed after the PR branched, comparing newer base code
+        # (BEFORE) against the PR's older snapshot (AFTER) - a
+        # time-reversed comparison that flags the base branch's own
+        # refactors as blockers on PRs that never touched those files.
+        # The compare API returns the merge-base without needing local
+        # history, and fetching that single commit by SHA keeps the
+        # shallow (fetch-depth: 1) clone.
         if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          git fetch --no-tags --depth=1 origin \
-            "${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"
+          MERGE_BASE=$(gh api \
+            "repos/${{ github.repository }}/compare/${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}" \
+            --jq .merge_base_commit.sha)
+          git fetch --no-tags --depth=1 origin "$MERGE_BASE"
           mapfile -t CHANGED < <(
             git diff --name-only --diff-filter=M \
-              "origin/${{ github.base_ref }}" HEAD -- '*.py' \
+              "$MERGE_BASE" HEAD -- '*.py' \
               | grep -vE '(^|/)(unsloth_compiled_cache|node_modules|build|dist)/' || true
           )
           if [ "${#CHANGED[@]}" -eq 0 ]; then
             echo "no in-place-modified Python files to check"
             exit 0
           fi
+          printf 'merge base: %s\n' "$MERGE_BASE"
           printf 'checking %d file(s):\n' "${#CHANGED[@]}"
           printf '  %s\n' "${CHANGED[@]}"
           python scripts/verify_import_hoist.py \
-            --before "origin/${{ github.base_ref }}" --after HEAD "${CHANGED[@]}"
+            --before "$MERGE_BASE" --after HEAD "${CHANGED[@]}"
 
       - name: No leftover debugger / pdb / breakpoint calls
         # Catches the "I'll just stick a breakpoint() here" mistake

From 2db9fad4b5450daffce6c56dbf37292562ee602d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 05:06:02 -0700
Subject: [PATCH 183/222] Installer: GPU detection follow-ups after #6174
 (poisoned venv repair, llama.cpp routing, probe bounds) (#6183)

* Installer: harden GPU detection follow-ups after #6174

Ports the NVIDIA-priority and /proc/driver/nvidia/gpus hardening from #6174
to the remaining pathways and adds recovery for already-poisoned venvs:

- install_python_stack.py: add _ensure_cuda_torch so 'unsloth studio update'
  force-reinstalls CUDA torch when the venv carries a ROCm build on an NVIDIA
  Linux host (the pre-#6174 poisoning signature). Honors UNSLOTH_TORCH_BACKEND,
  UNSLOTH_ROCM_TORCH_INSTALLED, and CUDA_VISIBLE_DEVICES=-1/'' opt-outs; never
  touches healthy CUDA, deliberate CPU wheels, macOS, or Windows.
- install_llama_prebuilt.py: detect_host gains the /proc NVIDIA fallback and
  skips ROCm probes when NVIDIA is usable; forwarded --rocm-gfx/--has-rocm
  overrides still win.
- setup.sh: GPU summary classifies NVIDIA first through a timeout-bounded
  probe with the /proc fallback; AMD probes are bounded and gain a KFD
  vendor_id 4098 fallback; the llama.cpp source build only selects
  GGML_CUDA/GGML_HIP when the matching GPU is actually detected.
- install.sh: bound both nvidia-smi calls with a 10s timeout (no behavior
  change when healthy or when the timeout binary is absent); classify the
  exported UNSLOTH_TORCH_BACKEND on the final index path segment so custom
  mirrors containing 'rocm'/'gfx' in their base path are not mislabeled.
- install.ps1 + setup.ps1: NVIDIA probes now require a real 'GPU N:' row from
  nvidia-smi -L under a 10s bound instead of bare exit code 0; later CUDA
  version and compute_cap queries are bounded too.

Tests: 3 new test files (50+ tests), suite at 788 passed.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix Resolve-CudaToolkit driver probe for extracted-function unit test

tests/studio/test_resolve_cuda_toolkit.ps1 extracts Resolve-CudaToolkit alone
into a child pwsh and stubs nvidia-smi with a .ps1 script. The bounded runner
is not in scope there (and ProcessStartInfo cannot dispatch .ps1 stubs), so
the DriverMaxCuda parse silently returned nothing and the major-mismatch
scenarios failed. Fall back to direct invocation when Invoke-NvidiaSmiBounded
is unavailable; production setup.ps1 always has it defined and keeps the
10s bound.

* Treat CUDA_VISIBLE_DEVICES empty or -1 as hidden in NVIDIA-first guards

The NVIDIA-first guards added in this branch only special-cased
CUDA_VISIBLE_DEVICES=-1 at two setup.sh gates and ignored the empty-string
form entirely, while the Python detector (install_llama_prebuilt.py)
already treats both as hidden. On a mixed AMD+NVIDIA host steered to the
AMD card via CUDA_VISIBLE_DEVICES, the guards suppressed the AMD probes,
so setup.sh fell to a CPU llama.cpp build and install.sh picked CUDA
wheels instead of ROCm.

Move the policy into the helpers so every consumer agrees:

- install.sh: new _cvd_hides_nvidia checked first in _has_usable_nvidia_gpu
- studio/setup.sh: same via _setup_cvd_hides_nvidia; the two ad-hoc
  CUDA_VISIBLE_DEVICES=-1 gate conditions are now redundant and removed
- studio/install_python_stack.py: _has_usable_nvidia_gpu returns False
  when CUDA_VISIBLE_DEVICES is set to  or -1 (whitespace tolerated)

Tests: 5 new sh scenarios (hidden via , -1, padded -1, visible device,
and mixed host with hidden NVIDIA restoring the ROCm route) plus a pytest
class covering all three implementations behaviourally.

Addresses the review comment on the NVIDIA-first setup.sh block.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Retrigger CI after PyPI 503 outage during the previous run

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 install.ps1                                   |  55 +-
 install.sh                                    |  51 +-
 studio/install_llama_prebuilt.py              |  24 +-
 studio/install_python_stack.py                | 155 ++++++
 studio/setup.ps1                              |  81 ++-
 studio/setup.sh                               | 166 ++++--
 tests/sh/test_get_torch_index_url.sh          |  51 +-
 tests/studio/install/test_cuda_repair.py      | 248 +++++++++
 .../install/test_gpu_detection_followups.py   | 480 ++++++++++++++++++
 tests/studio/install/test_probe_timeouts.py   | 202 ++++++++
 10 files changed, 1439 insertions(+), 74 deletions(-)
 create mode 100644 tests/studio/install/test_cuda_repair.py
 create mode 100644 tests/studio/install/test_gpu_detection_followups.py
 create mode 100644 tests/studio/install/test_probe_timeouts.py

diff --git a/install.ps1 b/install.ps1
index cbc7b206c8..2938d4334f 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1406,14 +1406,58 @@ shell.Run cmd, 0, False
         }
     }
 
+    # ── Helper: run nvidia-smi under a timeout ──
+    # A wedged NVIDIA driver can make nvidia-smi block during init or after a
+    # reset; WaitForExit bounds it (mirrors Invoke-AmdSmiNoElevate) so detection
+    # cannot hang the installer. No RunAsInvoker compat layer: nvidia-smi does
+    # not auto-elevate. Returns combined stdout+stderr; "" on timeout/failure.
+    function Invoke-NvidiaSmiBounded {
+        param(
+            [Parameter(Mandatory = $true, Position = 0)][string]$Exe,
+            [Parameter(Position = 1)][string[]]$SmiArgs = @(),
+            [int]$TimeoutSec = 10
+        )
+        try {
+            $psi = New-Object System.Diagnostics.ProcessStartInfo
+            $psi.FileName = $Exe
+            $psi.Arguments = ($SmiArgs -join ' ')
+            $psi.UseShellExecute = $false
+            $psi.RedirectStandardOutput = $true
+            $psi.RedirectStandardError = $true
+            $psi.CreateNoWindow = $true
+            $proc = [System.Diagnostics.Process]::Start($psi)
+            $outTask = $proc.StandardOutput.ReadToEndAsync()
+            $errTask = $proc.StandardError.ReadToEndAsync()
+            if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
+                try { $proc.Kill() } catch {}
+                $global:LASTEXITCODE = 124
+                return ""
+            }
+            $global:LASTEXITCODE = $proc.ExitCode
+            return ($outTask.Result + "`n" + $errTask.Result)
+        } catch {
+            $global:LASTEXITCODE = 1
+            return ""
+        }
+    }
+
+    # ── Helper: nvidia-smi -L lists at least one real GPU ──
+    # Exit code 0 alone is not enough: a stale/driverless nvidia-smi can exit 0
+    # while listing no GPU, which would mark an AMD host NVIDIA and suppress
+    # ROCm detection. Require a "GPU <n>:" data row.
+    function Test-NvidiaSmiHasGpu {
+        param([Parameter(Mandatory = $true)][string]$Exe)
+        $out = Invoke-NvidiaSmiBounded $Exe @('-L')
+        return ($LASTEXITCODE -eq 0 -and $out -match '(?m)^GPU\s+\d+:')
+    }
+
     # ── Detect GPU (robust: PATH + hardcoded fallback paths, mirrors setup.ps1) ──
     $HasNvidiaSmi = $false
     $NvidiaSmiExe = $null
     try {
         $nvSmiCmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
-        if ($nvSmiCmd) {
-            & $nvSmiCmd.Source *> $null
-            if ($LASTEXITCODE -eq 0) { $HasNvidiaSmi = $true; $NvidiaSmiExe = $nvSmiCmd.Source }
+        if ($nvSmiCmd -and (Test-NvidiaSmiHasGpu $nvSmiCmd.Source)) {
+            $HasNvidiaSmi = $true; $NvidiaSmiExe = $nvSmiCmd.Source
         }
     } catch {}
     if (-not $HasNvidiaSmi) {
@@ -1423,8 +1467,7 @@ shell.Run cmd, 0, False
         )) {
             if (Test-Path $p) {
                 try {
-                    & $p *> $null
-                    if ($LASTEXITCODE -eq 0) { $HasNvidiaSmi = $true; $NvidiaSmiExe = $p; break }
+                    if (Test-NvidiaSmiHasGpu $p) { $HasNvidiaSmi = $true; $NvidiaSmiExe = $p; break }
                 } catch {}
             }
         }
@@ -1694,7 +1737,7 @@ shell.Run cmd, 0, False
         $baseUrl = if ($env:UNSLOTH_PYTORCH_MIRROR) { $env:UNSLOTH_PYTORCH_MIRROR.TrimEnd('/') } else { "https://download.pytorch.org/whl" }
         if (-not $NvidiaSmiExe) { return "$baseUrl/cpu" }
         try {
-            $output = & $NvidiaSmiExe 2>&1 | Out-String
+            $output = Invoke-NvidiaSmiBounded $NvidiaSmiExe
             # Newer NVIDIA drivers (e.g. 610.x on Windows) print
             # "CUDA UMD Version: X.Y" instead of the legacy "CUDA Version: X.Y".
             # Accept both spellings so we don't fall through to the cu126 default.
diff --git a/install.sh b/install.sh
index 44d1c39d02..df9eca65c7 100755
--- a/install.sh
+++ b/install.sh
@@ -1745,13 +1745,42 @@ _has_amd_rocm_gpu() {
     return 1
 }
 
+# ── Bounded command runner ──
+# Runs a command under a 10s timeout when the `timeout` binary is available,
+# otherwise runs it unbounded. Keeps a wedged nvidia-smi (blocking during
+# driver init or after a reset) from hanging the installer: a timed-out probe
+# exits nonzero and is treated exactly like a failed probe. No-op semantics on
+# hosts without `timeout` (e.g. macOS) or when the probe is healthy.
+_run_bounded() {
+    if command -v timeout >/dev/null 2>&1; then
+        timeout 10 "$@"
+    else
+        "$@"
+    fi
+}
+
+# Returns 0 (true) when CUDA_VISIBLE_DEVICES is set to "" or "-1", i.e. every
+# NVIDIA device is deliberately hidden (mixed AMD+NVIDIA hosts steering work to
+# the AMD card). Unset means all devices visible. nvidia-smi ignores this env
+# var, so the probes below cannot see the distinction on their own.
+_cvd_hides_nvidia() {
+    [ "${CUDA_VISIBLE_DEVICES+set}" = "set" ] || return 1
+    _cvd_trim=$(printf '%s' "$CUDA_VISIBLE_DEVICES" | tr -d '[:space:]')
+    [ -z "$_cvd_trim" ] || [ "$_cvd_trim" = "-1" ]
+}
+
 # ── NVIDIA usable-GPU helper ──
 # Returns 0 (true) if an NVIDIA GPU is present and usable.
 # Primary probe: nvidia-smi -L. Fallback: /proc/driver/nvidia/gpus/ sysfs,
 # which the NVIDIA driver populates on Linux regardless of nvidia-smi state
 # -- handles PATH gaps, subprocess timeouts, and driver init races that
 # could otherwise cause nvidia-smi to fail and silence NVIDIA detection.
+# A GPU hidden via CUDA_VISIBLE_DEVICES=""/-1 counts as NOT usable (matches
+# install_llama_prebuilt.py has_usable_nvidia), so AMD/CPU routing still runs.
 _has_usable_nvidia_gpu() {
+    if _cvd_hides_nvidia; then
+        return 1
+    fi
     _nvsmi=""
     if command -v nvidia-smi >/dev/null 2>&1; then
         _nvsmi="nvidia-smi"
@@ -1759,7 +1788,7 @@ _has_usable_nvidia_gpu() {
         _nvsmi="/usr/bin/nvidia-smi"
     fi
     if [ -n "$_nvsmi" ]; then
-        if "$_nvsmi" -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
+        if _run_bounded "$_nvsmi" -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
             return 0
         fi
     fi
@@ -1871,7 +1900,11 @@ get_torch_index_url() {
     # of the legacy "CUDA Version: X.Y"; accept both with two BRE expressions
     # (POSIX sed does not support "?" without -E).  The two patterns are
     # mutually exclusive per line, so head -1 picks the first emitted match.
-    _cuda_ver=$(LC_ALL=C $_smi 2>/dev/null \
+    # Bound the call (a wedged nvidia-smi would otherwise hang here) and force
+    # the C locale for stable parsing. LC_ALL is exported inside this command
+    # substitution subshell so it reaches nvidia-smi through _run_bounded
+    # without depending on `env`; the export is scoped to the subshell.
+    _cuda_ver=$(export LC_ALL=C; _run_bounded "$_smi" 2>/dev/null \
         | sed -n \
             -e 's/.*CUDA UMD Version:[[:space:]]*\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
             -e 's/.*CUDA Version:[[:space:]]*\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' \
@@ -2125,10 +2158,16 @@ TORCH_INDEX_URL=$(get_torch_index_url)
 # Export the resolved torch backend ("cuda", "rocm", or "cpu") so that
 # downstream scripts (setup.sh -> install_python_stack.py) know what was
 # chosen here and can skip ROCm-specific repair steps on CUDA/CPU hosts.
-case "$TORCH_INDEX_URL" in
-    */rocm*|*/gfx*) export UNSLOTH_TORCH_BACKEND="rocm" ;;
-    */cpu)          export UNSLOTH_TORCH_BACKEND="cpu"  ;;
-    *)              export UNSLOTH_TORCH_BACKEND="cuda" ;;
+# Classify on the FINAL path segment only: a custom UNSLOTH_PYTORCH_MIRROR
+# whose base path happens to contain "rocm" or "gfx" must not mislabel a
+# cu*/cpu index as ROCm (radeon repo URLs end in rocm-rel-X.Y/, Strix
+# overrides in gfxNNNN/, so the trailing slash is stripped first).
+_torch_index_leaf="${TORCH_INDEX_URL%/}"
+_torch_index_leaf="${_torch_index_leaf##*/}"
+case "$_torch_index_leaf" in
+    rocm*|gfx*) export UNSLOTH_TORCH_BACKEND="rocm" ;;
+    cpu)        export UNSLOTH_TORCH_BACKEND="cpu"  ;;
+    *)          export UNSLOTH_TORCH_BACKEND="cuda" ;;
 esac
 
 # rocm7.2 ships torch 2.11.0 -- adjust the constraint to allow it.
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index f9425f5c4f..22fab82923 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -2890,7 +2890,27 @@ def detect_host() -> HostInfo:
         except Exception:
             pass
 
+    # Linux /proc/driver/nvidia/gpus fallback: the NVIDIA driver exposes one
+    # subdir per GPU here regardless of nvidia-smi state, so a host whose
+    # nvidia-smi is absent from PATH, wedged, or failing is still recognised as
+    # NVIDIA. Mirrors the fallback added to install.sh / install_python_stack.py
+    # in PR 6174 so the prebuilt installer does not misroute such hosts to ROCm
+    # or CPU. driver_cuda_version / compute_caps stay unset here; downstream
+    # CUDA asset selection treats unknown SMs as "prefer portable" and an
+    # unknown driver runtime line as "no published CUDA match" (returns None,
+    # no crash), so planning falls back to a source build with GGML_CUDA=ON.
+    if is_linux and not has_physical_nvidia:
+        try:
+            proc_gpu_dir = "/proc/driver/nvidia/gpus"
+            if os.path.isdir(proc_gpu_dir) and os.listdir(proc_gpu_dir):
+                has_physical_nvidia = True
+                has_usable_nvidia = visible_device_tokens != []
+        except OSError:
+            pass
+
     # Detect AMD ROCm (HIP) -- require actual GPU, not just tools installed
+    # NVIDIA takes precedence: when an NVIDIA GPU is usable, skip ROCm probing
+    # entirely so co-installed ROCm tools cannot misroute the host (PR 6174).
 
     def _amd_smi_has_gpu(stdout: str) -> bool:
         """Check for 'GPU: <number>' data rows, not just a table header."""
@@ -2898,7 +2918,7 @@ def detect_host() -> HostInfo:
 
     has_rocm = False
     rocm_gfx_target: str | None = None
-    if is_linux:
+    if is_linux and not has_usable_nvidia:
         # WSL2 ROCDXG: the system rocminfo enumerates the GPU over /dev/dxg
         # only when HSA_ENABLE_DXG_DETECTION=1 (a no-op on bare metal), and
         # rocminfo can live only under /opt/rocm/bin (the profile.d PATH
@@ -2937,7 +2957,7 @@ def detect_host() -> HostInfo:
                     has_rocm = True
                     rocm_gfx_target = _pick_rocm_gfx_target(_result.stdout)
                     break
-    elif is_windows:
+    elif is_windows and not has_usable_nvidia:
         # Windows: prefer active probes that validate GPU presence.
         # hipinfo / amd-smi are often NOT on PATH -- the HIP SDK installer
         # sets HIP_PATH / ROCM_PATH but does not always add the bin dir to
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 0460580922..e540aac305 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -90,6 +90,18 @@ _PYTORCH_WHL_BASE = (
     os.environ.get("UNSLOTH_PYTORCH_MIRROR") or "https://download.pytorch.org/whl"
 ).rstrip("/")
 
+# CUDA torch repair specs (see _ensure_cuda_torch). torchvision/torchaudio are
+# pinned to the torch<2.11 family rather than left bare: the install uses an
+# exclusive --index-url (no PyPI fallback), so a bare name could resolve a
+# torchvision built against a different torch major (e.g. 0.27 for torch 2.12)
+# and fail at runtime with an ABI mismatch. Same bounds as the _default ROCm
+# spec above, which targets the same torch family.
+_CUDA_TORCH_PKG_SPEC: tuple[str, str, str] = (
+    "torch>=2.4,<2.11.0",
+    "torchvision>=0.19,<0.26.0",
+    "torchaudio>=2.4,<2.11.0",
+)
+
 # AMD Windows ROCm wheels (repo.amd.com/rocm/whl/{arch_family}/).
 # Override with UNSLOTH_ROCM_WINDOWS_MIRROR for air-gapped/mirror installs.
 _ROCM_WINDOWS_INDEX_BASE = (
@@ -654,7 +666,15 @@ def _has_usable_nvidia_gpu() -> bool:
     case where nvidia-smi is present but the subprocess fails (PATH gap,
     timeout, driver initialisation race). If either probe confirms an
     NVIDIA GPU the function returns True so _has_rocm_gpu() is blocked.
+
+    CUDA_VISIBLE_DEVICES set to "" or "-1" hides every NVIDIA device (mixed
+    AMD+NVIDIA hosts steering work to the AMD card); neither probe honours
+    that env var, so check it first and report the GPU as not usable. Unset
+    means all devices visible.
     """
+    cvd = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if cvd is not None and cvd.strip() in ("", "-1"):
+        return False
     exe = shutil.which("nvidia-smi")
     if exe:
         try:
@@ -786,6 +806,139 @@ def _install_bnb_windows_rocm() -> bool:
     return True
 
 
+def _detect_cuda_torch_index_url() -> str:
+    """Return the pytorch.org CUDA wheel index URL for the host's NVIDIA driver.
+
+    Mirrors install.sh::get_torch_index_url's CUDA ladder so `studio update`
+    repairs to the same wheel family a fresh `curl | sh` install would pick.
+    Probes nvidia-smi (PATH, then /usr/bin/nvidia-smi) and parses both the
+    legacy "CUDA Version:" and the newer "CUDA UMD Version:" spellings.
+    Defaults to cu126 when nvidia-smi is missing or the version is unreadable
+    (e.g. NVIDIA detected only via the /proc/driver/nvidia/gpus fallback).
+    """
+    exe = shutil.which("nvidia-smi")
+    if not exe and os.path.isfile("/usr/bin/nvidia-smi"):
+        exe = "/usr/bin/nvidia-smi"
+    tag = "cu126"  # default when the driver CUDA version cannot be read
+    if exe:
+        try:
+            result = subprocess.run(
+                [exe],
+                stdout = subprocess.PIPE,
+                stderr = subprocess.DEVNULL,
+                text = True,
+                timeout = 10,
+            )
+            if result.returncode == 0:
+                m = re.search(r"CUDA(?: UMD)? Version:\s*(\d+)\.(\d+)", result.stdout)
+                if m:
+                    major, minor = int(m.group(1)), int(m.group(2))
+                    if major >= 13:
+                        tag = "cu130"
+                    elif major == 12 and minor >= 8:
+                        tag = "cu128"
+                    elif major == 12 and minor >= 6:
+                        tag = "cu126"
+                    elif major >= 12:
+                        tag = "cu124"
+                    elif major >= 11:
+                        tag = "cu118"
+                    else:
+                        tag = "cpu"  # ancient driver: no usable CUDA wheels
+        except Exception:
+            pass
+    return f"{_PYTORCH_WHL_BASE}/{tag}"
+
+
+def _ensure_cuda_torch() -> None:
+    """Repair a venv whose torch is a ROCm build on an NVIDIA host.
+
+    Counterpart to _ensure_rocm_torch. A venv poisoned by the pre-fix KFD
+    gpu_id false positive (ROCm torch installed on an NVIDIA-only machine)
+    keeps that broken torch on `studio update`, because a torch+rocm wheel
+    satisfies the version constraint and nothing force-reinstalls it. This
+    detects that exact case and reinstalls CUDA torch.
+
+    Only repairs when torch actually links against HIP/ROCm. Healthy CUDA
+    torch and deliberate CPU-only torch are left untouched.
+    """
+    # Respect an explicit backend choice from install.sh: only "" (standalone
+    # `studio update`) or "cuda" should ever force CUDA wheels. "rocm"/"cpu"
+    # (or any unrecognised value) are deliberate and must not be overridden.
+    if _TORCH_BACKEND not in ("", "cuda"):
+        return
+    # No CUDA torch on macOS; Windows venv/torch lifecycle is owned by
+    # install.ps1 (and the KFD poisoning bug is Linux-only), so skip both.
+    if IS_MACOS or IS_WINDOWS or NO_TORCH:
+        return
+    # Never undo a deliberate ROCm install (setup.ps1 sets this marker).
+    if os.environ.get("UNSLOTH_ROCM_TORCH_INSTALLED") == "1":
+        return
+    # CUDA_VISIBLE_DEVICES="" / "-1" deliberately hides the NVIDIA GPU (for
+    # example a mixed AMD+NVIDIA host that runs ROCm torch on the AMD card);
+    # never force CUDA wheels over that choice.
+    _cvd = os.environ.get("CUDA_VISIBLE_DEVICES")
+    if _cvd is not None and _cvd.strip() in ("", "-1"):
+        return
+    # Only NVIDIA hosts should carry CUDA torch. _has_usable_nvidia_gpu()
+    # covers the /proc/driver/nvidia/gpus fallback when nvidia-smi is absent.
+    if not _has_usable_nvidia_gpu():
+        return
+
+    # Classify the installed torch: "hip" (ROCm build -- the poisoning
+    # signature), "cuda" (healthy), or "cpu" (deliberate CPU wheel). A
+    # non-zero exit means torch is missing or un-importable; the base install
+    # step handles that, so leave it alone.
+    try:
+        probe = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                (
+                    "import torch; "
+                    "hip = getattr(torch.version, 'hip', '') or ''; "
+                    "cuda = getattr(torch.version, 'cuda', '') or ''; "
+                    "ver = getattr(torch, '__version__', '').lower(); "
+                    "print('hip' if (hip or 'rocm' in ver) else ('cuda' if cuda else 'cpu'))"
+                ),
+            ],
+            stdout = subprocess.PIPE,
+            stderr = subprocess.DEVNULL,
+            timeout = 90,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return
+    if probe.returncode != 0:
+        return
+    # Take the last non-empty stdout line: stray output from sitecustomize or
+    # an import hook must not mask the marker (fail-closed either way).
+    _marker_lines = [
+        line.strip() for line in probe.stdout.decode(errors = "replace").splitlines() if line.strip()
+    ]
+    if not _marker_lines or _marker_lines[-1] != "hip":
+        return  # healthy CUDA torch, or a deliberate CPU wheel -- leave as-is
+
+    index_url = _detect_cuda_torch_index_url()
+    _torch_pkg, _vision_pkg, _audio_pkg = _CUDA_TORCH_PKG_SPEC
+    print(
+        f"   torch is a ROCm build on an NVIDIA host -- reinstalling "
+        f"CUDA torch from {index_url}\n"
+        f"   (set UNSLOTH_TORCH_BACKEND=rocm to keep a deliberate ROCm torch "
+        f"on a mixed AMD+NVIDIA host)"
+    )
+    pip_install(
+        "CUDA torch repair",
+        "--force-reinstall",
+        "--no-cache-dir",
+        _torch_pkg,
+        _vision_pkg,
+        _audio_pkg,
+        "--index-url",
+        index_url,
+        constrain = False,
+    )
+
+
 def _ensure_rocm_torch() -> None:
     """Reinstall torch with ROCm wheels when the venv received CPU-only torch.
 
@@ -1848,6 +2001,7 @@ def install_python_stack() -> int:
     #     Must follow base packages so torch is present for inspection.
     if not IS_MACOS and not NO_TORCH:
         _progress(_torch_step_label("check"))
+        _ensure_cuda_torch()
         _ensure_rocm_torch()
 
     # Windows + AMD GPU: warn if ROCm torch was not installed (wrong Python
@@ -2033,6 +2187,7 @@ def install_python_stack() -> int:
     #     whichever intermediate step clobbered it.
     if not IS_WINDOWS and not IS_MACOS and not NO_TORCH:
         _progress(_torch_step_label("final"))
+        _ensure_cuda_torch()
         _ensure_rocm_torch()
 
     # 14. Final check (silent; third-party conflicts are expected)
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index e707cfda7a..29350e3932 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -299,7 +299,10 @@ function Get-CudaComputeCapability {
     if (-not $smiExe) { return $null }
 
     try {
-        $raw = & $smiExe --query-gpu=compute_cap --format=csv,noheader 2>$null
+        # Bounded: a wedged nvidia-smi must not hang setup after the initial
+        # -L probe succeeded (the helper merges stderr after stdout, so the
+        # first line is still the compute_cap value).
+        $raw = Invoke-NvidiaSmiBounded $smiExe @('--query-gpu=compute_cap', '--format=csv,noheader')
         if ($LASTEXITCODE -ne 0 -or -not $raw) { return $null }
 
         # nvidia-smi may return multiple GPUs; take the first one
@@ -363,10 +366,10 @@ function Get-PytorchCudaTag {
     if (-not $smiExe) { return "cu126" }
 
     try {
-        # 2>&1 | Out-String merges stderr into stdout then converts to a single
-        # string.  Plain 2>$null doesn't fully suppress stderr in PS 5.1 --
-        # ErrorRecord objects leak into $output and break the -match.
-        $output = & $smiExe 2>&1 | Out-String
+        # Bounded: a wedged nvidia-smi must not hang setup. The helper merges
+        # stderr into the returned string, matching the old 2>&1 | Out-String
+        # shape (plain 2>$null leaks ErrorRecord objects in PS 5.1).
+        $output = Invoke-NvidiaSmiBounded $smiExe
         # Newer NVIDIA drivers (e.g. 610.x on Windows) print
         # "CUDA UMD Version: X.Y" instead of the legacy "CUDA Version: X.Y".
         # Accept both spellings so we don't fall through to the cu126 default.
@@ -667,16 +670,58 @@ try {
 # ============================================
 # 1a. GPU detection
 # ============================================
+# ── Helper: run nvidia-smi under a timeout ──
+# A wedged NVIDIA driver can make nvidia-smi block during init or after a reset;
+# WaitForExit bounds it (mirrors Invoke-AmdSmiNoElevate below) so detection
+# cannot hang setup. No RunAsInvoker compat layer: nvidia-smi does not
+# auto-elevate. Returns combined stdout+stderr; "" on timeout/failure.
+function Invoke-NvidiaSmiBounded {
+    param(
+        [Parameter(Mandatory = $true, Position = 0)][string]$Exe,
+        [Parameter(Position = 1)][string[]]$SmiArgs = @(),
+        [int]$TimeoutSec = 10
+    )
+    try {
+        $psi = New-Object System.Diagnostics.ProcessStartInfo
+        $psi.FileName = $Exe
+        $psi.Arguments = ($SmiArgs -join ' ')
+        $psi.UseShellExecute = $false
+        $psi.RedirectStandardOutput = $true
+        $psi.RedirectStandardError = $true
+        $psi.CreateNoWindow = $true
+        $proc = [System.Diagnostics.Process]::Start($psi)
+        $outTask = $proc.StandardOutput.ReadToEndAsync()
+        $errTask = $proc.StandardError.ReadToEndAsync()
+        if (-not $proc.WaitForExit($TimeoutSec * 1000)) {
+            try { $proc.Kill() } catch {}
+            $global:LASTEXITCODE = 124
+            return ""
+        }
+        $global:LASTEXITCODE = $proc.ExitCode
+        return ($outTask.Result + "`n" + $errTask.Result)
+    } catch {
+        $global:LASTEXITCODE = 1
+        return ""
+    }
+}
+
+# ── Helper: nvidia-smi -L lists at least one real GPU ──
+# Exit code 0 alone is not enough: a stale/driverless nvidia-smi can exit 0
+# while listing no GPU, which would mark an AMD host NVIDIA and suppress ROCm
+# detection. Require a "GPU <n>:" data row.
+function Test-NvidiaSmiHasGpu {
+    param([Parameter(Mandatory = $true)][string]$Exe)
+    $out = Invoke-NvidiaSmiBounded $Exe @('-L')
+    return ($LASTEXITCODE -eq 0 -and $out -match '(?m)^GPU\s+\d+:')
+}
+
 $HasNvidiaSmi = $false
 $NvidiaSmiExe = $null  # Absolute path -- survives Refresh-Environment
 try {
     $nvSmiCmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
-    if ($nvSmiCmd) {
-        & $nvSmiCmd.Source *> $null
-        if ($LASTEXITCODE -eq 0) {
-            $HasNvidiaSmi = $true
-            $NvidiaSmiExe = $nvSmiCmd.Source
-        }
+    if ($nvSmiCmd -and (Test-NvidiaSmiHasGpu $nvSmiCmd.Source)) {
+        $HasNvidiaSmi = $true
+        $NvidiaSmiExe = $nvSmiCmd.Source
     }
 } catch {}
 # Fallback: nvidia-smi may not be on PATH even though a GPU + driver exist.
@@ -689,8 +734,7 @@ if (-not $HasNvidiaSmi) {
     foreach ($p in $nvSmiDefaults) {
         if (Test-Path $p) {
             try {
-                & $p *> $null
-                if ($LASTEXITCODE -eq 0) {
+                if (Test-NvidiaSmiHasGpu $p) {
                     $HasNvidiaSmi = $true
                     $NvidiaSmiExe = $p
                     Write-Host "   Found nvidia-smi at $(Split-Path $p -Parent)" -ForegroundColor Gray
@@ -1151,7 +1195,16 @@ function Resolve-CudaToolkit {
 
 $DriverMaxCuda = $null
 try {
-    $smiOut = & $NvidiaSmiExe 2>&1 | Out-String
+    # Bounded: source-build toolkit resolution must not hang on a wedged smi.
+    # test_resolve_cuda_toolkit.ps1 extracts this function alone into a child
+    # pwsh (no Invoke-NvidiaSmiBounded in scope) and stubs nvidia-smi with a
+    # .ps1 script, so fall back to direct invocation when the bounded runner
+    # is unavailable; production setup.ps1 always has it defined.
+    $smiOut = if (Get-Command Invoke-NvidiaSmiBounded -ErrorAction SilentlyContinue) {
+        Invoke-NvidiaSmiBounded $NvidiaSmiExe
+    } else {
+        & $NvidiaSmiExe 2>&1 | Out-String
+    }
     # Newer drivers report "CUDA UMD Version: X.Y" instead of "CUDA Version: X.Y"; accept both.
     if ($smiOut -match "CUDA(?: UMD)? Version:\s+([\d]+)\.([\d]+)") {
         $DriverMaxCuda = "$($Matches[1]).$($Matches[2])"
diff --git a/studio/setup.sh b/studio/setup.sh
index 66c03da391..a8603bd0da 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -155,9 +155,60 @@ _nvcc_meets_llama_minimum() {
     echo "$_raw"
 }
 
+# Run a GPU probe under a 10s timeout when `timeout` is available so a wedged
+# NVIDIA driver cannot hang setup; fall back to a bare call where it is not.
+_setup_run_smi() {
+    if command -v timeout >/dev/null 2>&1; then
+        timeout 10 "$@"
+    else
+        "$@"
+    fi
+}
+
+# Returns 0 when CUDA_VISIBLE_DEVICES is set to "" or "-1", i.e. every NVIDIA
+# device is deliberately hidden (mixed AMD+NVIDIA hosts steering work to the
+# AMD card). Unset means all devices visible. nvidia-smi ignores this env var,
+# so the probes below cannot see the distinction on their own.
+_setup_cvd_hides_nvidia() {
+    [ "${CUDA_VISIBLE_DEVICES+set}" = "set" ] || return 1
+    _setup_cvd_trim=$(printf '%s' "$CUDA_VISIBLE_DEVICES" | tr -d '[:space:]')
+    [ -z "$_setup_cvd_trim" ] || [ "$_setup_cvd_trim" = "-1" ]
+}
+
+# Returns 0 when an NVIDIA GPU is present and usable. Primary probe is
+# `nvidia-smi -L` (timeout-bounded). Fallback is /proc/driver/nvidia/gpus,
+# which the driver populates per GPU regardless of nvidia-smi state -- handles
+# PATH gaps and driver init races. Mirrors install.sh _has_usable_nvidia_gpu
+# (PR 6174) so setup routes the same way as the torch installer. A GPU hidden
+# via CUDA_VISIBLE_DEVICES=""/-1 counts as NOT usable (matches
+# install_llama_prebuilt.py has_usable_nvidia), so the AMD probes still run
+# and a mixed host steered to its AMD card keeps the ROCm route.
+_setup_has_usable_nvidia_gpu() {
+    if _setup_cvd_hides_nvidia; then
+        return 1
+    fi
+    _setup_nvsmi=""
+    if command -v nvidia-smi >/dev/null 2>&1; then
+        _setup_nvsmi="nvidia-smi"
+    elif [ -x "/usr/bin/nvidia-smi" ]; then
+        _setup_nvsmi="/usr/bin/nvidia-smi"
+    fi
+    if [ -n "$_setup_nvsmi" ]; then
+        if _setup_run_smi "$_setup_nvsmi" -L 2>/dev/null \
+           | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
+            return 0
+        fi
+    fi
+    if [ -d /proc/driver/nvidia/gpus ] && \
+       [ -n "$(ls -A /proc/driver/nvidia/gpus 2>/dev/null)" ]; then
+        return 0
+    fi
+    return 1
+}
+
 _cuda_driver_max_version() {
     command -v nvidia-smi >/dev/null 2>&1 || return 0
-    nvidia-smi 2>/dev/null \
+    _setup_run_smi nvidia-smi 2>/dev/null \
         | sed -nE 's/.*CUDA( UMD)? Version:[[:space:]]*([0-9]+)\.([0-9]+).*/\2.\3/p' \
         | head -1 || true
 }
@@ -815,25 +866,42 @@ _setup_amd_detected=false
 _setup_nvidia_usable=false
 _setup_gfx_all=""
 _setup_mkt=""
-if command -v rocminfo >/dev/null 2>&1 && \
-   rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
-    _setup_amd_detected=true
-    _setup_gfx_all=$(rocminfo 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
-    _setup_mkt=$(rocminfo 2>/dev/null | awk -F': ' \
-        '/Marketing Name:/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
-elif command -v amd-smi >/dev/null 2>&1 && \
-     amd-smi list 2>/dev/null | awk '/^GPU[[:space:]]*[:\[][[:space:]]*[0-9]/{ found=1 } END{ exit !found }'; then
-    _setup_amd_detected=true
-    _setup_gfx_all=$(amd-smi list 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
-    [ -z "$_setup_gfx_all" ] && \
-        _setup_gfx_all=$(amd-smi static --asic 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
-    _setup_mkt=$(amd-smi static --asic 2>/dev/null | awk -F'[:|]' \
-        '/[Mm]arket.?[Nn]ame/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+# NVIDIA priority: classify NVIDIA first and skip the AMD probes entirely on
+# a usable-NVIDIA host (mirrors _has_rocm_gpu in install_python_stack.py).
+# This also keeps a wedged rocminfo/amd-smi from hanging setup before the
+# host is classified; the AMD probes themselves run under _setup_run_smi.
+if _setup_has_usable_nvidia_gpu; then
+    _setup_nvidia_usable=true
+fi
+if [ "$_setup_nvidia_usable" != true ]; then
+    if command -v rocminfo >/dev/null 2>&1 && \
+       _setup_run_smi rocminfo 2>/dev/null | awk '/Name:[[:space:]]*gfx[1-9][0-9]/{found=1} END{exit !found}'; then
+        _setup_amd_detected=true
+        _setup_gfx_all=$(_setup_run_smi rocminfo 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+        _setup_mkt=$(_setup_run_smi rocminfo 2>/dev/null | awk -F': ' \
+            '/Marketing Name:/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+    elif command -v amd-smi >/dev/null 2>&1 && \
+         _setup_run_smi amd-smi list 2>/dev/null | awk '/^GPU[[:space:]]*[:\[][[:space:]]*[0-9]/{ found=1 } END{ exit !found }'; then
+        _setup_amd_detected=true
+        _setup_gfx_all=$(_setup_run_smi amd-smi list 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+        [ -z "$_setup_gfx_all" ] && \
+            _setup_gfx_all=$(_setup_run_smi amd-smi static --asic 2>/dev/null | grep -oE 'gfx[1-9][0-9a-z]{2,3}' || true)
+        _setup_mkt=$(_setup_run_smi amd-smi static --asic 2>/dev/null | awk -F'[:|]' \
+            '/[Mm]arket.?[Nn]ame/{gsub(/^[[:space:]]+|[[:space:]]+$/,"", $2); if($2){print $2; exit}}' || true)
+    elif [ -e /dev/kfd ] && \
+         awk 'FNR==1{ gpu=0; amd=0 } /gpu_id/{ gpu=($2+0>0) } /vendor_id/{ amd=($2==4098) } \
+              gpu && amd { found=1 } END{ exit !found }' \
+             /sys/class/kfd/kfd/topology/nodes/*/properties 2>/dev/null; then
+        # KFD sysfs fallback, AMD vendor_id 4098 only (mirrors install.sh
+        # _has_amd_rocm_gpu): covers AMD hosts where rocminfo/amd-smi are
+        # missing but the kernel exposes the GPU, so the source-build gate
+        # below does not drop them to a CPU llama.cpp build. No gfx arch is
+        # available from this path; name-based inference handles it.
+        _setup_amd_detected=true
+    fi
 fi
 
-if command -v nvidia-smi >/dev/null 2>&1 && \
-   nvidia-smi -L 2>/dev/null | awk '/^GPU[[:space:]]+[0-9]+:/{found=1} END{exit !found}'; then
-    _setup_nvidia_usable=true
+if [ "$_setup_nvidia_usable" = true ]; then
     step "gpu" "NVIDIA GPU detected"
 elif [ "$_setup_amd_detected" = true ]; then
     _setup_vis="${HIP_VISIBLE_DEVICES:-${ROCR_VISIBLE_DEVICES:-}}"
@@ -918,15 +986,15 @@ _HOST_MACHINE="$(uname -m 2>/dev/null || true)"
 # use unslothai.
 _LINUX_HAS_GPU=false
 # Route to the fork only for a usable GPU. NVIDIA counts only when a device is
-# actually enumerated (_setup_nvidia_usable, from the nvidia-smi -L probe above)
-# AND not hidden via CUDA_VISIBLE_DEVICES=-1 -- mirroring install_llama_prebuilt.py's
-# has_usable_nvidia. Mere nvidia-smi presence (CPU-only CUDA-toolkit containers,
-# broken drivers) or a hidden GPU therefore takes the ggml-org CPU prebuilt
-# instead of a slow source build. AMD is deliberately left on tooling presence,
-# not usability: an unusable NVIDIA host has a good CPU prebuilt to fall back to,
-# whereas tightening AMD would regress ROCm hosts exposing only hipconfig/hipinfo
-# into an unnecessary CPU build.
-if [ "$_setup_nvidia_usable" = true ] && [ "${CUDA_VISIBLE_DEVICES:-}" != "-1" ]; then
+# actually enumerated and not hidden via CUDA_VISIBLE_DEVICES=""/-1
+# (_setup_nvidia_usable, from _setup_has_usable_nvidia_gpu above) -- mirroring
+# install_llama_prebuilt.py's has_usable_nvidia. Mere nvidia-smi presence
+# (CPU-only CUDA-toolkit containers, broken drivers) or a hidden GPU therefore
+# takes the ggml-org CPU prebuilt instead of a slow source build. AMD is
+# deliberately left on tooling presence, not usability: an unusable NVIDIA host
+# has a good CPU prebuilt to fall back to, whereas tightening AMD would regress
+# ROCm hosts exposing only hipconfig/hipinfo into an unnecessary CPU build.
+if [ "$_setup_nvidia_usable" = true ]; then
     _LINUX_HAS_GPU=true
 else
     for _GPU_TOOL in rocminfo amd-smi hipconfig hipinfo; do
@@ -1271,23 +1339,35 @@ else
 
             GPU_BACKEND=""
             NVCC_PATH=""
-            if command -v nvcc &>/dev/null; then
-                NVCC_PATH="$(command -v nvcc)"
-                GPU_BACKEND="cuda"
-            elif [ -x /usr/local/cuda/bin/nvcc ]; then
-                NVCC_PATH="/usr/local/cuda/bin/nvcc"
-                export PATH="/usr/local/cuda/bin:$PATH"
-                GPU_BACKEND="cuda"
-            elif ls /usr/local/cuda-*/bin/nvcc &>/dev/null 2>&1; then
-                # Pick the newest cuda-XX.X directory
-                NVCC_PATH="$(ls -d /usr/local/cuda-*/bin/nvcc 2>/dev/null | sort -V | tail -1)"
-                export PATH="$(dirname "$NVCC_PATH"):$PATH"
-                GPU_BACKEND="cuda"
+            # Gate the CUDA toolkit search on an actually-usable NVIDIA GPU
+            # (_setup_nvidia_usable, computed in the GPU summary block above;
+            # already false when hidden via CUDA_VISIBLE_DEVICES=""/-1).
+            # A CUDA toolkit alone (CPU-only build container, leftover packages)
+            # is not proof of a GPU: building with -DGGML_CUDA=ON there yields a
+            # binary that fails at runtime, so fall through to the CPU build.
+            if [ "$_setup_nvidia_usable" = true ]; then
+                if command -v nvcc &>/dev/null; then
+                    NVCC_PATH="$(command -v nvcc)"
+                    GPU_BACKEND="cuda"
+                elif [ -x /usr/local/cuda/bin/nvcc ]; then
+                    NVCC_PATH="/usr/local/cuda/bin/nvcc"
+                    export PATH="/usr/local/cuda/bin:$PATH"
+                    GPU_BACKEND="cuda"
+                elif ls /usr/local/cuda-*/bin/nvcc &>/dev/null 2>&1; then
+                    # Pick the newest cuda-XX.X directory
+                    NVCC_PATH="$(ls -d /usr/local/cuda-*/bin/nvcc 2>/dev/null | sort -V | tail -1)"
+                    export PATH="$(dirname "$NVCC_PATH"):$PATH"
+                    GPU_BACKEND="cuda"
+                fi
             fi
 
-            # Check for ROCm (AMD) only if CUDA was not already selected
+            # Check for ROCm (AMD) only if CUDA was not already selected, and
+            # only when an AMD GPU was actually detected (_setup_amd_detected).
+            # hipcc presence alone (HIP SDK, no GPU) must not select a HIP build.
+            # NVIDIA-usable hosts never build HIP (defense in depth: the AMD
+            # probes above are already skipped when NVIDIA is usable).
             ROCM_HIPCC=""
-            if [ -z "$GPU_BACKEND" ]; then
+            if [ -z "$GPU_BACKEND" ] && [ "$_setup_nvidia_usable" != true ] && [ "$_setup_amd_detected" = true ]; then
                 if command -v hipcc &>/dev/null; then
                     ROCM_HIPCC="$(command -v hipcc)"
                     GPU_BACKEND="rocm"
@@ -1349,7 +1429,7 @@ else
 
                         CUDA_ARCHS=""
                         if command -v nvidia-smi &>/dev/null; then
-                            _raw_caps=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
+                            _raw_caps=$(_setup_run_smi nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>/dev/null || true)
                             while IFS= read -r _cap; do
                                 _cap=$(echo "$_cap" | tr -d '[:space:]')
                                 if [[ "$_cap" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
@@ -1455,7 +1535,7 @@ else
                     CMAKE_ARGS="$CMAKE_ARGS -DGPU_TARGETS=${GPU_TARGETS}"
                     _BUILD_DESC="building (ROCm, ${GPU_TARGETS//;/+})"
                 fi
-            elif [ -d /usr/local/cuda ] || nvidia-smi &>/dev/null; then
+            elif [ -d /usr/local/cuda ] || _setup_run_smi nvidia-smi &>/dev/null; then
                 _BUILD_DESC="building (CPU, CUDA driver found but nvcc missing)"
             elif [ -d /opt/rocm ] || command -v rocm-smi &>/dev/null; then
                 _BUILD_DESC="building (CPU, ROCm driver found but hipcc missing)"
diff --git a/tests/sh/test_get_torch_index_url.sh b/tests/sh/test_get_torch_index_url.sh
index e20fd1ca86..3dece1f69a 100755
--- a/tests/sh/test_get_torch_index_url.sh
+++ b/tests/sh/test_get_torch_index_url.sh
@@ -13,6 +13,10 @@ FAIL=0
 _FUNC_FILE=$(mktemp)
 _FAKE_SMI_DIR=$(mktemp -d)
 {
+    sed -n '/^_run_bounded()/,/^}/p' "$INSTALL_SH"
+    echo ""
+    sed -n '/^_cvd_hides_nvidia()/,/^}/p' "$INSTALL_SH"
+    echo ""
     sed -n '/^_has_amd_rocm_gpu()/,/^}/p' "$INSTALL_SH"
     echo ""
     sed -n '/^_has_usable_nvidia_gpu()/,/^}/p' "$INSTALL_SH"
@@ -107,7 +111,7 @@ MOCK
 # Build a minimal tools directory with symlinks to essential commands
 # (uname, grep, head, etc.) but WITHOUT nvidia-smi or amd-smi.
 _TOOLS_DIR=$(mktemp -d)
-for _cmd in uname grep sed head sh bash cat awk printf; do
+for _cmd in uname grep sed head sh bash cat awk printf tr; do
     _real=$(command -v "$_cmd" 2>/dev/null || true)
     [ -n "$_real" ] && ln -sf "$_real" "$_TOOLS_DIR/$_cmd"
 done
@@ -116,12 +120,19 @@ done
 # $1 = directory with mock nvidia-smi (prepended to PATH), or "none" for no-GPU test
 run_func() {
     _mock_dir="$1"
+    # Default: strip CUDA_VISIBLE_DEVICES so the host environment cannot leak
+    # in; a second argument sets it explicitly (hidden-GPU scenarios).
+    if [ "$#" -ge 2 ]; then
+        _cvd_setup="export CUDA_VISIBLE_DEVICES='$2'"
+    else
+        _cvd_setup="unset CUDA_VISIBLE_DEVICES"
+    fi
     if [ "$_mock_dir" = "none" ]; then
         # Minimal PATH with only basic tools, no nvidia-smi anywhere
-        PATH="$_TOOLS_DIR" bash -c ". '$_FUNC_FILE'; get_torch_index_url" 2>/dev/null
+        PATH="$_TOOLS_DIR" bash -c "$_cvd_setup; . '$_FUNC_FILE'; get_torch_index_url" 2>/dev/null
     else
         # Put mock nvidia-smi dir first, then basic tools
-        PATH="$_mock_dir:$_TOOLS_DIR" bash -c ". '$_FUNC_FILE'; get_torch_index_url" 2>/dev/null
+        PATH="$_mock_dir:$_TOOLS_DIR" bash -c "$_cvd_setup; . '$_FUNC_FILE'; get_torch_index_url" 2>/dev/null
     fi
 }
 
@@ -332,6 +343,40 @@ _result=$(run_func "$_dir")
 assert_eq "CUDA Version 13.7 -> cu130" "https://download.pytorch.org/whl/cu130" "$_result"
 rm -rf "$_dir"
 
+# 34) CUDA_VISIBLE_DEVICES="" hides the NVIDIA GPU -> cpu (no AMD present)
+_dir=$(make_mock_smi "12.8")
+_result=$(run_func "$_dir" "")
+assert_eq "CVD='' hides NVIDIA -> cpu" "https://download.pytorch.org/whl/cpu" "$_result"
+rm -rf "$_dir"
+
+# 35) CUDA_VISIBLE_DEVICES=-1 hides the NVIDIA GPU -> cpu (no AMD present)
+_dir=$(make_mock_smi "12.8")
+_result=$(run_func "$_dir" "-1")
+assert_eq "CVD=-1 hides NVIDIA -> cpu" "https://download.pytorch.org/whl/cpu" "$_result"
+rm -rf "$_dir"
+
+# 36) Mixed AMD+NVIDIA host with NVIDIA hidden -> ROCm route is restored
+_cuda_dir=$(make_mock_smi "12.6")
+_amd_dir=$(make_mock_amd_smi "6.4")
+_combined_dir=$(mktemp -d)
+ln -sf "$_cuda_dir/nvidia-smi" "$_combined_dir/nvidia-smi"
+ln -sf "$_amd_dir/amd-smi" "$_combined_dir/amd-smi"
+_result=$(run_func "$_combined_dir" "-1")
+assert_eq "CUDA+ROCm with CVD=-1 -> rocm6.4" "https://download.pytorch.org/whl/rocm6.4" "$_result"
+rm -rf "$_cuda_dir" "$_amd_dir" "$_combined_dir"
+
+# 37) CUDA_VISIBLE_DEVICES=0 (a visible device) must NOT hide the GPU
+_dir=$(make_mock_smi "12.8")
+_result=$(run_func "$_dir" "0")
+assert_eq "CVD=0 keeps NVIDIA -> cu128" "https://download.pytorch.org/whl/cu128" "$_result"
+rm -rf "$_dir"
+
+# 38) Whitespace-padded "-1" still hides the GPU
+_dir=$(make_mock_smi "12.8")
+_result=$(run_func "$_dir" " -1 ")
+assert_eq "CVD=' -1 ' hides NVIDIA -> cpu" "https://download.pytorch.org/whl/cpu" "$_result"
+rm -rf "$_dir"
+
 rm -f "$_FUNC_FILE"
 rm -rf "$_FAKE_SMI_DIR"
 rm -rf "$_TOOLS_DIR"
diff --git a/tests/studio/install/test_cuda_repair.py b/tests/studio/install/test_cuda_repair.py
new file mode 100644
index 0000000000..83c2d962e8
--- /dev/null
+++ b/tests/studio/install/test_cuda_repair.py
@@ -0,0 +1,248 @@
+"""Tests for CUDA torch repair on poisoned NVIDIA venvs.
+
+Verifies _ensure_cuda_torch (studio/install_python_stack.py) reinstalls CUDA
+torch when a venv on an NVIDIA host carries a ROCm torch build (the pre-fix KFD
+gpu_id false positive), without touching healthy CUDA, deliberate CPU wheels,
+ROCm hosts, macOS, or Windows. All tests use mocks -- no GPU required.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ── Load module under test (mirrors test_rocm_support.py) ────────────────────
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+
+_STACK_PATH = PACKAGE_ROOT / "studio" / "install_python_stack.py"
+_STACK_SPEC = importlib.util.spec_from_file_location("studio_install_python_stack", _STACK_PATH)
+assert _STACK_SPEC is not None and _STACK_SPEC.loader is not None
+stack_mod = importlib.util.module_from_spec(_STACK_SPEC)
+sys.modules[_STACK_SPEC.name] = stack_mod
+_STACK_SPEC.loader.exec_module(stack_mod)
+
+_ensure_cuda_torch = stack_mod._ensure_cuda_torch
+_detect_cuda_torch_index_url = stack_mod._detect_cuda_torch_index_url
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _make_run(
+    torch_state = "hip",
+    cuda_version = "12.8",
+    torch_rc = 0,
+    smi_rc = 0,
+):
+    """Build a subprocess.run side_effect.
+
+    The torch-classify probe runs sys.executable and reads bytes stdout; the
+    nvidia-smi version probe runs the smi path with text=True. Distinguish by
+    the executable.
+    """
+
+    def _run(cmd, *args, **kwargs):
+        result = MagicMock()
+        exe = str(cmd[0]) if cmd else ""
+        if exe == sys.executable:
+            result.returncode = torch_rc
+            result.stdout = (torch_state + "\n").encode()
+            return result
+        # nvidia-smi version probe (text = True)
+        result.returncode = smi_rc
+        out = f"CUDA Version: {cuda_version}\n" if cuda_version else "No devices found\n"
+        result.stdout = out if kwargs.get("text") else out.encode()
+        return result
+
+    return _run
+
+
+def _run_cuda_repair(
+    *,
+    backend = "",
+    nvidia = True,
+    torch_state = "hip",
+    cuda_version = "12.8",
+    torch_rc = 0,
+    smi_rc = 0,
+    is_macos = False,
+    is_windows = False,
+    no_torch = False,
+    rocm_marker = False,
+    smi_path = "/usr/bin/nvidia-smi",
+    cvd = None,
+):
+    """Invoke _ensure_cuda_torch under a fully mocked host; return the pip mock.
+
+    cvd controls CUDA_VISIBLE_DEVICES: None removes it from the environment
+    (the host machine may export one), any string sets it explicitly.
+    """
+    env = {}
+    if rocm_marker:
+        env["UNSLOTH_ROCM_TORCH_INSTALLED"] = "1"
+    if cvd is not None:
+        env["CUDA_VISIBLE_DEVICES"] = cvd
+
+    def _which(name, *a, **k):
+        if name == "nvidia-smi":
+            return smi_path
+        return None
+
+    with (
+        patch.object(stack_mod, "_TORCH_BACKEND", backend),
+        patch.object(stack_mod, "IS_MACOS", is_macos),
+        patch.object(stack_mod, "IS_WINDOWS", is_windows),
+        patch.object(stack_mod, "NO_TORCH", no_torch),
+        patch.object(stack_mod, "_has_usable_nvidia_gpu", return_value = nvidia),
+        patch.object(stack_mod.shutil, "which", side_effect = _which),
+        patch.object(stack_mod.os.path, "isfile", return_value = bool(smi_path)),
+        patch.object(stack_mod, "pip_install") as mock_pip,
+        patch.object(
+            stack_mod.subprocess,
+            "run",
+            side_effect = _make_run(torch_state, cuda_version, torch_rc, smi_rc),
+        ),
+        patch.dict(stack_mod.os.environ, env, clear = False),
+    ):
+        if not rocm_marker:
+            stack_mod.os.environ.pop("UNSLOTH_ROCM_TORCH_INSTALLED", None)
+        if cvd is None:
+            stack_mod.os.environ.pop("CUDA_VISIBLE_DEVICES", None)
+        _ensure_cuda_torch()
+    return mock_pip
+
+
+def _index_url(mock_pip) -> str:
+    """Return the --index-url value from the recorded pip_install call."""
+    args = [str(a) for a in mock_pip.call_args.args]
+    return args[args.index("--index-url") + 1]
+
+
+# ── Repair fires only on the poisoning signature ─────────────────────────────
+
+
+class TestCudaRepairFires:
+    def test_hip_build_on_nvidia_triggers_repair(self):
+        mock_pip = _run_cuda_repair(torch_state = "hip", cuda_version = "12.8")
+        assert mock_pip.call_count == 1
+        call_args = [str(a) for a in mock_pip.call_args.args]
+        assert "--force-reinstall" in call_args
+        assert "--no-cache-dir" in call_args
+        assert "cu128" in _index_url(mock_pip)
+        assert mock_pip.call_args.kwargs["constrain"] is False
+
+    def test_rocm_in_version_string_triggers_repair(self):
+        # AMD SDK / Radeon wheels may not set torch.version.hip but encode
+        # rocm in __version__; the probe prints "hip" for both.
+        mock_pip = _run_cuda_repair(torch_state = "hip")
+        assert mock_pip.call_count == 1
+
+
+# ── No-op cases ──────────────────────────────────────────────────────────────
+
+
+class TestCudaRepairSkips:
+    def test_healthy_cuda_torch_no_repair(self):
+        mock_pip = _run_cuda_repair(torch_state = "cuda")
+        mock_pip.assert_not_called()
+
+    def test_deliberate_cpu_wheel_no_repair(self):
+        mock_pip = _run_cuda_repair(torch_state = "cpu")
+        mock_pip.assert_not_called()
+
+    def test_backend_rocm_skips(self):
+        mock_pip = _run_cuda_repair(backend = "rocm", torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_backend_cpu_skips(self):
+        mock_pip = _run_cuda_repair(backend = "cpu", torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_unknown_backend_skips(self):
+        mock_pip = _run_cuda_repair(backend = "auto", torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_no_nvidia_gpu_skips(self):
+        mock_pip = _run_cuda_repair(nvidia = False, torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_torch_missing_skips(self):
+        # Non-zero probe exit = torch missing / un-importable.
+        mock_pip = _run_cuda_repair(torch_state = "hip", torch_rc = 1)
+        mock_pip.assert_not_called()
+
+    def test_macos_skips(self):
+        mock_pip = _run_cuda_repair(is_macos = True, torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_windows_skips(self):
+        mock_pip = _run_cuda_repair(is_windows = True, torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_no_torch_mode_skips(self):
+        mock_pip = _run_cuda_repair(no_torch = True, torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_rocm_install_marker_skips(self):
+        mock_pip = _run_cuda_repair(rocm_marker = True, torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_cvd_minus_one_skips(self):
+        # CUDA_VISIBLE_DEVICES=-1 deliberately hides the NVIDIA GPU (mixed
+        # AMD+NVIDIA host running ROCm torch on the AMD card).
+        mock_pip = _run_cuda_repair(cvd = "-1", torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_cvd_empty_skips(self):
+        mock_pip = _run_cuda_repair(cvd = "", torch_state = "hip")
+        mock_pip.assert_not_called()
+
+    def test_cvd_explicit_device_still_repairs(self):
+        mock_pip = _run_cuda_repair(cvd = "0", torch_state = "hip")
+        assert mock_pip.call_count == 1
+
+
+# ── CUDA index ladder ────────────────────────────────────────────────────────
+
+
+class TestCudaIndexResolution:
+    def test_cuda_128_selects_cu128(self):
+        assert "cu128" in _index_url(_run_cuda_repair(cuda_version = "12.8"))
+
+    def test_cuda_130_selects_cu130(self):
+        assert "cu130" in _index_url(_run_cuda_repair(cuda_version = "13.0"))
+
+    def test_cuda_126_selects_cu126(self):
+        assert "cu126" in _index_url(_run_cuda_repair(cuda_version = "12.6"))
+
+    def test_cuda_124_selects_cu124(self):
+        assert "cu124" in _index_url(_run_cuda_repair(cuda_version = "12.4"))
+
+    def test_cuda_118_selects_cu118(self):
+        assert "cu118" in _index_url(_run_cuda_repair(cuda_version = "11.8"))
+
+    def test_unreadable_version_defaults_cu126(self):
+        # nvidia-smi runs but prints no CUDA version line (or fails).
+        mock_pip = _run_cuda_repair(cuda_version = "", smi_rc = 1)
+        assert "cu126" in _index_url(mock_pip)
+
+    def test_proc_fallback_no_smi_defaults_cu126(self):
+        # NVIDIA usable via /proc fallback, nvidia-smi absent entirely.
+        mock_pip = _run_cuda_repair(smi_path = None)
+        assert "cu126" in _index_url(mock_pip)
+
+    def test_detect_index_url_uses_pytorch_base(self):
+        with (
+            patch.object(stack_mod.shutil, "which", return_value = None),
+            patch.object(stack_mod.os.path, "isfile", return_value = False),
+        ):
+            url = _detect_cuda_torch_index_url()
+        assert url == f"{stack_mod._PYTORCH_WHL_BASE}/cu126"
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))
diff --git a/tests/studio/install/test_gpu_detection_followups.py b/tests/studio/install/test_gpu_detection_followups.py
new file mode 100644
index 0000000000..983969a4d3
--- /dev/null
+++ b/tests/studio/install/test_gpu_detection_followups.py
@@ -0,0 +1,480 @@
+"""Tests for the GPU-detection follow-ups to PR 6174.
+
+PR 6174 made NVIDIA take precedence and added a /proc/driver/nvidia/gpus
+fallback in install.sh and studio/install_python_stack.py. These tests cover the
+same hardening ported to the llama.cpp prebuilt installer
+(studio/install_llama_prebuilt.py) and the Studio shell setup (studio/setup.sh):
+
+  * detect_host() recognises NVIDIA via /proc/driver/nvidia/gpus when nvidia-smi
+    is unavailable, and skips ROCm probing when NVIDIA is usable.
+  * setup.sh routes through a timeout-bounded NVIDIA probe with a /proc fallback
+    and only selects a CUDA/ROCm source build when the matching GPU is detected.
+
+All tests use mocks or source-level assertions -- no GPU, network, or real
+nvidia-smi/rocminfo invocation.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+
+# Load studio/install_llama_prebuilt.py the same way the sibling suite does.
+_MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+_SPEC = importlib.util.spec_from_file_location(
+    "studio_install_llama_prebuilt_followups", _MODULE_PATH
+)
+assert _SPEC is not None and _SPEC.loader is not None
+prebuilt_mod = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = prebuilt_mod
+_SPEC.loader.exec_module(prebuilt_mod)
+
+detect_host = prebuilt_mod.detect_host
+_apply_host_overrides = prebuilt_mod._apply_host_overrides
+
+SETUP_SH = PACKAGE_ROOT / "studio" / "setup.sh"
+
+
+def _make_run_capture(rocminfo_stdout: str = ""):
+    """Return a fake run_capture: rocminfo reports rocminfo_stdout, everything
+    else (nvidia-smi, amd-smi) returns empty so only the patched probes matter."""
+
+    def _run_capture(cmd, *args, **kwargs):
+        exe = str(cmd[0]) if cmd else ""
+        result = MagicMock()
+        if exe.endswith("rocminfo"):
+            result.returncode = 0
+            result.stdout = rocminfo_stdout
+        else:
+            result.returncode = 1
+            result.stdout = ""
+        result.stderr = ""
+        return result
+
+    return _run_capture
+
+
+def _run_detect_host(
+    *,
+    machine: str = "x86_64",
+    system: str = "Linux",
+    which_map: dict | None = None,
+    proc_dir_entries: list | None = None,
+    rocminfo_stdout: str = "",
+    env: dict | None = None,
+):
+    """Drive detect_host() against a fully synthetic host."""
+    which_map = which_map or {}
+    proc_dir_entries = proc_dir_entries if proc_dir_entries is not None else []
+
+    real_isdir = prebuilt_mod.os.path.isdir
+    real_listdir = prebuilt_mod.os.listdir
+    proc_path = "/proc/driver/nvidia/gpus"
+
+    def fake_isdir(p):
+        if str(p) == proc_path:
+            return bool(proc_dir_entries)
+        return real_isdir(p)
+
+    def fake_listdir(p):
+        if str(p) == proc_path:
+            if not proc_dir_entries:
+                raise OSError("no such dir")
+            return list(proc_dir_entries)
+        return real_listdir(p)
+
+    patches = [
+        patch.object(prebuilt_mod.platform, "system", return_value = system),
+        patch.object(prebuilt_mod.platform, "machine", return_value = machine),
+        patch.object(prebuilt_mod.platform, "mac_ver", return_value = ("", ("", "", ""), "")),
+        patch.object(prebuilt_mod.shutil, "which", side_effect = lambda n: which_map.get(n)),
+        patch.object(prebuilt_mod, "run_capture", side_effect = _make_run_capture(rocminfo_stdout)),
+        patch.object(prebuilt_mod.os.path, "isdir", side_effect = fake_isdir),
+        patch.object(prebuilt_mod.os, "listdir", side_effect = fake_listdir),
+        patch.object(prebuilt_mod.os, "access", return_value = False),
+        patch.dict(prebuilt_mod.os.environ, env or {}, clear = False),
+    ]
+    for p in patches:
+        p.start()
+    try:
+        # Ensure CUDA_VISIBLE_DEVICES does not leak in from the test host unless
+        # the scenario sets it explicitly.
+        if env is None or "CUDA_VISIBLE_DEVICES" not in env:
+            prebuilt_mod.os.environ.pop("CUDA_VISIBLE_DEVICES", None)
+        return detect_host()
+    finally:
+        for p in patches:
+            p.stop()
+
+
+# ── install_llama_prebuilt.detect_host(): /proc NVIDIA fallback ──────────────
+
+
+class TestDetectHostProcFallback:
+    def test_proc_fallback_marks_physical_nvidia_when_smi_absent(self):
+        """No nvidia-smi, but /proc/driver/nvidia/gpus is populated -> NVIDIA."""
+        host = _run_detect_host(
+            which_map = {},  # nvidia-smi resolves to None
+            proc_dir_entries = ["0000:01:00.0"],
+        )
+        assert host.has_physical_nvidia is True
+
+    def test_proc_fallback_has_usable_nvidia_when_devices_visible(self):
+        """Default CUDA_VISIBLE_DEVICES (unset) -> visible tokens non-empty -> usable."""
+        host = _run_detect_host(
+            which_map = {},
+            proc_dir_entries = ["0000:01:00.0"],
+        )
+        assert host.has_usable_nvidia is True
+
+    def test_proc_fallback_not_usable_when_devices_hidden(self):
+        """CUDA_VISIBLE_DEVICES='' hides all GPUs -> physical yes, usable no."""
+        host = _run_detect_host(
+            which_map = {},
+            proc_dir_entries = ["0000:01:00.0"],
+            env = {"CUDA_VISIBLE_DEVICES": ""},
+        )
+        assert host.has_physical_nvidia is True
+        assert host.has_usable_nvidia is False
+
+    def test_empty_proc_dir_does_not_mark_nvidia(self):
+        """A driver dir that exists but is empty must not assert a GPU."""
+        host = _run_detect_host(which_map = {}, proc_dir_entries = [])
+        assert host.has_physical_nvidia is False
+
+    def test_proc_fallback_is_linux_only(self):
+        """The /proc fallback must not run on Windows (path is Linux-only)."""
+        host = _run_detect_host(
+            system = "Windows",
+            machine = "amd64",
+            which_map = {},
+            proc_dir_entries = ["0000:01:00.0"],
+        )
+        assert host.has_physical_nvidia is False
+
+
+# ── install_llama_prebuilt.detect_host(): NVIDIA precedence over ROCm ────────
+
+
+class TestDetectHostNvidiaPrecedence:
+    def test_rocm_probe_skipped_when_proc_nvidia_present(self):
+        """rocminfo reports gfx1100, but a proc-detected NVIDIA GPU wins."""
+        host = _run_detect_host(
+            which_map = {"rocminfo": "/usr/bin/rocminfo"},
+            proc_dir_entries = ["0000:01:00.0"],
+            rocminfo_stdout = "  Name:                    gfx1100\n",
+        )
+        assert host.has_usable_nvidia is True
+        assert host.has_rocm is False
+
+    def test_rocm_detected_when_no_nvidia(self):
+        """With no NVIDIA signal at all, rocminfo gfx1100 -> has_rocm True."""
+        host = _run_detect_host(
+            which_map = {"rocminfo": "/usr/bin/rocminfo"},
+            proc_dir_entries = [],
+            rocminfo_stdout = "  Name:                    gfx1100\n",
+        )
+        assert host.has_usable_nvidia is False
+        assert host.has_rocm is True
+
+
+# ── _apply_host_overrides: forwarded --rocm-gfx / --has-rocm still win ───────
+
+
+class TestOverridesStillWin:
+    def test_forwarded_gfx_forces_rocm_on_non_nvidia_host(self):
+        host = _run_detect_host(which_map = {}, proc_dir_entries = [])
+        assert host.has_rocm is False
+        overridden = _apply_host_overrides(host, override_rocm_gfx = "gfx1100")
+        assert overridden.has_rocm is True
+        assert overridden.rocm_gfx_target == "gfx1100"
+
+    def test_override_has_rocm_forces_rocm(self):
+        host = _run_detect_host(which_map = {}, proc_dir_entries = [])
+        overridden = _apply_host_overrides(host, override_has_rocm = True)
+        assert overridden.has_rocm is True
+
+    def test_force_cpu_drops_nvidia_attributes(self):
+        host = _run_detect_host(which_map = {}, proc_dir_entries = ["0000:01:00.0"])
+        assert host.has_usable_nvidia is True
+        overridden = _apply_host_overrides(host, force_cpu = True)
+        assert overridden.has_usable_nvidia is False
+        assert overridden.has_physical_nvidia is False
+        assert overridden.has_rocm is False
+
+
+# ── setup.sh source-level guarantees ────────────────────────────────────────
+
+
+class TestSetupShHardening:
+    @pytest.fixture(scope = "class")
+    def setup_src(self) -> str:
+        return SETUP_SH.read_text(encoding = "utf-8")
+
+    def test_has_usable_nvidia_helper_exists(self, setup_src):
+        assert "_setup_has_usable_nvidia_gpu()" in setup_src
+
+    def test_helper_uses_proc_fallback(self, setup_src):
+        start = setup_src.find("_setup_has_usable_nvidia_gpu()")
+        end = setup_src.find("\n}", start)
+        body = setup_src[start:end]
+        assert (
+            "/proc/driver/nvidia/gpus" in body
+        ), "_setup_has_usable_nvidia_gpu must fall back to /proc/driver/nvidia/gpus"
+
+    def test_gpu_summary_uses_helper(self, setup_src):
+        assert "if _setup_has_usable_nvidia_gpu; then" in setup_src
+
+    def test_timeout_wrapper_exists(self, setup_src):
+        start = setup_src.find("_setup_run_smi()")
+        assert start >= 0, "_setup_run_smi timeout wrapper must exist"
+        end = setup_src.find("\n}", start)
+        body = setup_src[start:end]
+        assert "timeout 10" in body
+        assert "command -v timeout" in body
+
+    def test_cuda_source_build_gated_on_usable_nvidia(self, setup_src):
+        """The nvcc source-build search must be gated on _setup_nvidia_usable.
+
+        The hidden-GPU policy (CUDA_VISIBLE_DEVICES=""/-1) lives inside
+        _setup_has_usable_nvidia_gpu, so the gate itself only needs the flag.
+        """
+        anchor = setup_src.find('NVCC_PATH=""\n')
+        assert anchor >= 0
+        window = setup_src[anchor : anchor + 700]
+        assert (
+            'if [ "$_setup_nvidia_usable" = true ]' in window
+        ), "CUDA toolkit search must require a usable NVIDIA GPU, not just nvcc"
+
+    def test_nvidia_helper_honours_hidden_cvd(self, setup_src):
+        """_setup_has_usable_nvidia_gpu must consult the hidden-CVD helper so
+        CUDA_VISIBLE_DEVICES=""/-1 suppresses NVIDIA before the AMD probes are
+        gated (mixed hosts steered to the AMD card keep the ROCm route)."""
+        assert "_setup_cvd_hides_nvidia()" in setup_src
+        start = setup_src.find("_setup_has_usable_nvidia_gpu() {")
+        end = setup_src.find("\n}", start)
+        body = setup_src[start:end]
+        assert "_setup_cvd_hides_nvidia" in body
+
+    def test_rocm_source_build_gated_on_amd_detected(self, setup_src):
+        """The hipcc source-build search must be gated on _setup_amd_detected."""
+        anchor = setup_src.find('ROCM_HIPCC=""')
+        assert anchor >= 0
+        window = setup_src[anchor : anchor + 400]
+        assert (
+            '[ "$_setup_amd_detected" = true ]' in window
+        ), "ROCm toolkit search must require a detected AMD GPU, not just hipcc"
+
+    def test_compute_cap_probe_timeout_wrapped(self, setup_src):
+        assert "_setup_run_smi nvidia-smi --query-gpu=compute_cap" in setup_src
+
+    def test_driver_version_probe_timeout_wrapped(self, setup_src):
+        start = setup_src.find("_cuda_driver_max_version()")
+        end = setup_src.find("\n}", start)
+        body = setup_src[start:end]
+        assert "_setup_run_smi nvidia-smi" in body
+
+
+# TEST: install.sh -- UNSLOTH_TORCH_BACKEND classified on the final path segment
+
+
+class TestBackendExportLeafClassification:
+    """A custom UNSLOTH_PYTORCH_MIRROR whose base path contains "rocm" or
+    "gfx" must not mislabel a cu*/cpu index as ROCm; classification uses the
+    final path segment of TORCH_INDEX_URL only."""
+
+    @pytest.fixture(scope = "class")
+    def install_src(self) -> str:
+        return (PACKAGE_ROOT / "install.sh").read_text(encoding = "utf-8")
+
+    def test_export_block_uses_leaf(self, install_src):
+        anchor = install_src.find("_torch_index_leaf=")
+        assert anchor >= 0, "backend export must classify on the final path segment"
+        window = install_src[anchor : anchor + 500]
+        assert 'export UNSLOTH_TORCH_BACKEND="rocm"' in window
+        assert 'export UNSLOTH_TORCH_BACKEND="cpu"' in window
+        assert 'export UNSLOTH_TORCH_BACKEND="cuda"' in window
+
+    def test_leaf_classification_behaviour(self, tmp_path):
+        import subprocess as sp
+
+        script = tmp_path / "leaf.sh"
+        src = (PACKAGE_ROOT / "install.sh").read_text(encoding = "utf-8")
+        anchor = src.find("_torch_index_leaf=")
+        block = src[anchor : src.find("esac", anchor) + 4]
+        # Drive the extracted block with adversarial mirror URLs.
+        script.write_text(
+            "#!/bin/sh\n"
+            'TORCH_INDEX_URL="$1"\n' + block + "\n"
+            'printf "%s" "$UNSLOTH_TORCH_BACKEND"\n'
+        )
+        cases = {
+            "https://download.pytorch.org/whl/cu128": "cuda",
+            "https://download.pytorch.org/whl/cpu": "cpu",
+            "https://download.pytorch.org/whl/rocm6.4": "rocm",
+            "https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2.1/": "rocm",
+            "https://repo.amd.com/rocm/whl/gfx1151/": "rocm",
+            "https://mirror.local/rocm-cache/cu128": "cuda",
+            "https://mirror.local/gfx-cache/cpu": "cpu",
+        }
+        for url, expected in cases.items():
+            out = sp.run(
+                ["sh", str(script), url], capture_output = True, text = True, timeout = 30
+            ).stdout.strip()
+            assert out == expected, f"{url} classified as {out!r}, expected {expected!r}"
+
+
+# TEST: CUDA_VISIBLE_DEVICES=""/-1 hides NVIDIA in every usable-GPU helper
+
+
+_STACK_PATH = PACKAGE_ROOT / "studio" / "install_python_stack.py"
+_STACK_SPEC = importlib.util.spec_from_file_location(
+    "studio_install_python_stack_followups", _STACK_PATH
+)
+assert _STACK_SPEC is not None and _STACK_SPEC.loader is not None
+stack_mod = importlib.util.module_from_spec(_STACK_SPEC)
+sys.modules[_STACK_SPEC.name] = stack_mod
+_STACK_SPEC.loader.exec_module(stack_mod)
+
+
+def _stack_nvidia_usable(cvd):
+    """Drive install_python_stack._has_usable_nvidia_gpu with a mocked
+    nvidia-smi that always reports a GPU; cvd = None removes the env var."""
+
+    def fake_run(cmd, *args, **kwargs):
+        result = MagicMock()
+        result.returncode = 0
+        result.stdout = "GPU 0: NVIDIA Fake (UUID: GPU-x)\n"
+        return result
+
+    env = {} if cvd is None else {"CUDA_VISIBLE_DEVICES": cvd}
+    with (
+        patch.object(
+            stack_mod.shutil,
+            "which",
+            side_effect = lambda n: "/usr/bin/nvidia-smi" if n == "nvidia-smi" else None,
+        ),
+        patch.object(stack_mod.subprocess, "run", side_effect = fake_run),
+        patch.dict(stack_mod.os.environ, env, clear = False),
+    ):
+        if cvd is None:
+            stack_mod.os.environ.pop("CUDA_VISIBLE_DEVICES", None)
+        return stack_mod._has_usable_nvidia_gpu()
+
+
+class TestHiddenCvdNotUsable:
+    """CUDA_VISIBLE_DEVICES set to "" or "-1" deliberately hides every NVIDIA
+    device (mixed AMD+NVIDIA hosts steering work to the AMD card). All three
+    _has_usable_nvidia_gpu implementations (install_python_stack.py, install.sh,
+    setup.sh) must report the GPU as not usable so the AMD/CPU routes run,
+    matching install_llama_prebuilt.py's has_usable_nvidia."""
+
+    def test_python_unset_cvd_is_usable(self):
+        assert _stack_nvidia_usable(None) is True
+
+    def test_python_empty_cvd_not_usable(self):
+        assert _stack_nvidia_usable("") is False
+
+    def test_python_minus_one_not_usable(self):
+        assert _stack_nvidia_usable("-1") is False
+
+    def test_python_padded_minus_one_not_usable(self):
+        assert _stack_nvidia_usable(" -1 ") is False
+
+    def test_python_explicit_device_is_usable(self):
+        assert _stack_nvidia_usable("0") is True
+
+    def test_python_device_list_is_usable(self):
+        assert _stack_nvidia_usable("0,1") is True
+
+    def test_hidden_nvidia_restores_rocm_detection(self):
+        """Mixed host, NVIDIA hidden via CVD=-1, rocminfo reports gfx1100:
+        _has_rocm_gpu must proceed past the NVIDIA guard and return True
+        (before this fix the guard ignored CVD and blocked ROCm)."""
+
+        def fake_run(cmd, *args, **kwargs):
+            result = MagicMock()
+            result.returncode = 0
+            exe = str(cmd[0])
+            if exe.endswith("rocminfo"):
+                result.stdout = "  Name:                    gfx1100\n"
+            else:
+                result.stdout = "GPU 0: NVIDIA Fake (UUID: GPU-x)\n"
+            return result
+
+        which_map = {
+            "rocminfo": "/usr/bin/rocminfo",
+            "nvidia-smi": "/usr/bin/nvidia-smi",
+        }
+        with (
+            patch.object(stack_mod.shutil, "which", side_effect = which_map.get),
+            patch.object(stack_mod.subprocess, "run", side_effect = fake_run),
+            patch.dict(stack_mod.os.environ, {"CUDA_VISIBLE_DEVICES": "-1"}, clear = False),
+        ):
+            assert stack_mod._has_rocm_gpu() is True
+
+    @staticmethod
+    def _run_sh_helper(tmp_path, src: str, fn_names: list, cvd):
+        """Extract shell functions, run the usable-GPU one against a fake
+        nvidia-smi, and return "usable"/"not_usable"."""
+        import os as _os
+        import subprocess as sp
+
+        blocks = []
+        for name in fn_names:
+            start = src.find(f"{name}() {{")
+            assert start >= 0, f"{name} missing"
+            end = src.find("\n}", start) + 2
+            blocks.append(src[start:end])
+        fake_bin = tmp_path / "bin"
+        fake_bin.mkdir(exist_ok = True)
+        smi = fake_bin / "nvidia-smi"
+        smi.write_text("#!/bin/sh\necho 'GPU 0: NVIDIA Fake (UUID: GPU-x)'\n")
+        smi.chmod(0o755)
+        script = tmp_path / "probe.sh"
+        script.write_text(
+            "#!/bin/sh\n" + "\n".join(blocks) + "\n"
+            f"if {fn_names[-1]}; then echo usable; else echo not_usable; fi\n"
+        )
+        env = dict(_os.environ)
+        env["PATH"] = f"{fake_bin}:{env['PATH']}"
+        if cvd is None:
+            env.pop("CUDA_VISIBLE_DEVICES", None)
+        else:
+            env["CUDA_VISIBLE_DEVICES"] = cvd
+        return sp.run(
+            ["sh", str(script)], capture_output = True, text = True, timeout = 30, env = env
+        ).stdout.strip()
+
+    @pytest.mark.parametrize(
+        "cvd, expected",
+        [(None, "usable"), ("", "not_usable"), ("-1", "not_usable"), ("0", "usable")],
+    )
+    def test_install_sh_helper_cvd(self, tmp_path, cvd, expected):
+        src = (PACKAGE_ROOT / "install.sh").read_text(encoding = "utf-8")
+        out = self._run_sh_helper(
+            tmp_path,
+            src,
+            ["_run_bounded", "_cvd_hides_nvidia", "_has_usable_nvidia_gpu"],
+            cvd,
+        )
+        assert out == expected
+
+    @pytest.mark.parametrize(
+        "cvd, expected",
+        [(None, "usable"), ("", "not_usable"), ("-1", "not_usable"), ("0", "usable")],
+    )
+    def test_setup_sh_helper_cvd(self, tmp_path, cvd, expected):
+        src = SETUP_SH.read_text(encoding = "utf-8")
+        out = self._run_sh_helper(
+            tmp_path,
+            src,
+            ["_setup_run_smi", "_setup_cvd_hides_nvidia", "_setup_has_usable_nvidia_gpu"],
+            cvd,
+        )
+        assert out == expected
diff --git a/tests/studio/install/test_probe_timeouts.py b/tests/studio/install/test_probe_timeouts.py
new file mode 100644
index 0000000000..acea0ed34d
--- /dev/null
+++ b/tests/studio/install/test_probe_timeouts.py
@@ -0,0 +1,202 @@
+"""Tests that NVIDIA probes in the installers are bounded by a timeout.
+
+Covers audit findings 5 and 6: a wedged nvidia-smi must not hang the installer,
+and the Windows probe must require a real GPU listing (not just exit code 0).
+
+Source-level assertions verify the guards are present in install.sh / install.ps1
+/ setup.ps1; one behavioral shell test confirms the bash helper actually returns
+within the timeout when nvidia-smi hangs.
+"""
+
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+INSTALL_SH = PACKAGE_ROOT / "install.sh"
+INSTALL_PS1 = PACKAGE_ROOT / "install.ps1"
+SETUP_PS1 = PACKAGE_ROOT / "studio" / "setup.ps1"
+
+
+def _extract_sh_function_body(source: str, name: str) -> str:
+    """Return a shell function body from `source` by brace matching."""
+    needle = f"{name}() {{"
+    start = source.find(needle)
+    if start < 0:
+        return ""
+    depth = 0
+    i = start + len(needle) - 1
+    n = len(source)
+    while i < n:
+        ch = source[i]
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return source[start : i + 1]
+        i += 1
+    return source[start:]
+
+
+# ── install.sh: _run_bounded helper and its use at every nvidia-smi call ──
+
+
+class TestInstallShBoundedProbe:
+    def _src(self) -> str:
+        return INSTALL_SH.read_text(encoding = "utf-8")
+
+    def test_run_bounded_helper_defined(self):
+        body = _extract_sh_function_body(self._src(), "_run_bounded")
+        assert body, "install.sh must define a _run_bounded helper"
+        assert (
+            "command -v timeout" in body
+        ), "_run_bounded must check for the `timeout` binary before using it"
+        assert "timeout 10" in body, "_run_bounded must apply a 10s timeout"
+        # Must fall back to running unbounded when `timeout` is unavailable
+        # (e.g. macOS) so semantics are unchanged there.
+        assert (
+            "else" in body and '"$@"' in body
+        ), "_run_bounded must run the command unbounded when `timeout` is absent"
+
+    def test_nvidia_smi_dash_l_probe_is_bounded(self):
+        body = _extract_sh_function_body(self._src(), "_has_usable_nvidia_gpu")
+        assert body, "install.sh must define _has_usable_nvidia_gpu"
+        # The -L probe must go through the bounded runner, not call nvidia-smi raw.
+        assert (
+            '_run_bounded "$_nvsmi" -L' in body
+        ), "_has_usable_nvidia_gpu must run nvidia-smi -L through _run_bounded"
+        # The /proc fallback from PR 6174 must still be present.
+        assert "/proc/driver/nvidia" in body
+
+    def test_cuda_version_parse_is_bounded(self):
+        body = _extract_sh_function_body(self._src(), "get_torch_index_url")
+        assert body, "install.sh must define get_torch_index_url"
+        assert (
+            "_run_bounded" in body
+        ), "get_torch_index_url CUDA-version parse must run nvidia-smi through _run_bounded"
+        # The locale must be forced without depending on `env` being on PATH.
+        assert "LC_ALL=C" in body
+        # _nvidia_detected gating from PR 6174 must remain.
+        assert "_nvidia_detected" in body
+
+    def test_no_unbounded_nvidia_smi_invocation_remains(self):
+        """Every nvidia-smi *execution* in install.sh goes through _run_bounded.
+
+        `command -v nvidia-smi` and `-x /usr/bin/nvidia-smi` are resolution
+        checks, not executions, and are allowed. An execution looks like
+        `"$_nvsmi" ...` / `$_smi ...` / `nvidia-smi -L`.
+        """
+        body_nvidia = _extract_sh_function_body(self._src(), "_has_usable_nvidia_gpu")
+        body_torch = _extract_sh_function_body(self._src(), "get_torch_index_url")
+        # In _has_usable_nvidia_gpu the only execution of $_nvsmi must be bounded.
+        assert '"$_nvsmi" -L' not in body_nvidia.replace(
+            '_run_bounded "$_nvsmi" -L', ""
+        ), "found an unbounded nvidia-smi -L execution in _has_usable_nvidia_gpu"
+        # In get_torch_index_url the $_smi execution must be bounded.
+        assert (
+            "LC_ALL=C $_smi" not in body_torch
+        ), "found an unbounded LC_ALL=C $_smi execution in get_torch_index_url"
+
+
+# ── install.ps1 / setup.ps1: bounded, GPU-row-validated Windows probe ──
+
+
+class TestPowerShellBoundedProbe:
+    @pytest.mark.parametrize("path", [INSTALL_PS1, SETUP_PS1])
+    def test_bounded_helper_present(self, path):
+        src = path.read_text(encoding = "utf-8")
+        assert (
+            "function Invoke-NvidiaSmiBounded" in src
+        ), f"{path.name} must define Invoke-NvidiaSmiBounded"
+        assert (
+            "WaitForExit($TimeoutSec * 1000)" in src
+        ), f"{path.name} bounded probe must use WaitForExit with a timeout"
+        # Kill + sentinel on timeout, mirroring Invoke-AmdSmiNoElevate.
+        assert (
+            "$proc.Kill()" in src and "124" in src
+        ), f"{path.name} must kill nvidia-smi and signal a timeout exit code"
+
+    @pytest.mark.parametrize("path", [INSTALL_PS1, SETUP_PS1])
+    def test_probe_requires_gpu_row(self, path):
+        src = path.read_text(encoding = "utf-8")
+        assert (
+            "function Test-NvidiaSmiHasGpu" in src
+        ), f"{path.name} must define Test-NvidiaSmiHasGpu"
+        assert "@('-L')" in src, f"{path.name} must probe nvidia-smi with -L"
+        assert (
+            "^GPU\\s+\\d+:" in src
+        ), f"{path.name} must require a 'GPU <n>:' data row, not just exit code 0"
+
+    @pytest.mark.parametrize("path", [INSTALL_PS1, SETUP_PS1])
+    def test_detection_uses_validated_probe(self, path):
+        src = path.read_text(encoding = "utf-8")
+        # The exit-code-only pattern must be gone from the detection block.
+        assert (
+            "& $nvSmiCmd.Source *> $null" not in src
+        ), f"{path.name} must not use the exit-code-only nvidia-smi probe"
+        assert (
+            "Test-NvidiaSmiHasGpu $nvSmiCmd.Source" in src
+        ), f"{path.name} PATH probe must use Test-NvidiaSmiHasGpu"
+        assert (
+            "Test-NvidiaSmiHasGpu $p" in src
+        ), f"{path.name} hardcoded-path fallback must use Test-NvidiaSmiHasGpu"
+
+
+# ── Behavioral: a hanging nvidia-smi must not hang _has_usable_nvidia_gpu ──
+
+
+def _have_timeout() -> bool:
+    return shutil.which("timeout") is not None
+
+
+@pytest.mark.skipif(not _have_timeout(), reason = "`timeout` binary not available")
+def test_has_usable_nvidia_gpu_returns_under_timeout():
+    """Extract _run_bounded + _has_usable_nvidia_gpu, point them at a fake
+    nvidia-smi that sleeps 30s, and assert the probe returns well under that.
+    """
+    src = INSTALL_SH.read_text(encoding = "utf-8")
+    helper = _extract_sh_function_body(src, "_run_bounded")
+    fn = _extract_sh_function_body(src, "_has_usable_nvidia_gpu")
+    assert helper and fn
+
+    workdir = tempfile.mkdtemp(prefix = "pr6174_timeout_", dir = str(PACKAGE_ROOT.parent))
+    try:
+        fake_dir = Path(workdir, "bin")
+        fake_dir.mkdir()
+        fake_smi = fake_dir / "nvidia-smi"
+        fake_smi.write_text("#!/bin/sh\nsleep 30\n")
+        fake_smi.chmod(fake_smi.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+        # Build a minimal PATH that includes the fake nvidia-smi plus the real
+        # `timeout`/`awk`/`ls` it needs. Use the fake dir first so it wins.
+        real_bins = {Path(shutil.which(c)).parent for c in ("timeout", "awk", "ls", "sh")}
+        path_env = os.pathsep.join([str(fake_dir)] + [str(p) for p in real_bins])
+
+        # Force the /proc fallback off so the result depends only on the probe,
+        # and so a host with real NVIDIA does not mask the timeout behaviour.
+        script = (
+            f"{helper}\n{fn}\n"
+            "if _has_usable_nvidia_gpu; then echo DETECTED; else echo NONE; fi\n"
+        )
+        proc = subprocess.run(
+            ["sh", "-c", script],
+            env = {"PATH": path_env},
+            stdout = subprocess.PIPE,
+            stderr = subprocess.DEVNULL,
+            text = True,
+            timeout = 20,  # generous: the internal timeout is 10s, sleep is 30s
+        )
+        # The probe must have returned (not hung). On this CI host /proc/driver/
+        # nvidia/gpus is absent, so a timed-out smi yields NONE; on a real NVIDIA
+        # host the /proc fallback yields DETECTED. Either way it must not hang.
+        assert proc.stdout.strip() in {"NONE", "DETECTED"}
+    finally:
+        shutil.rmtree(workdir, ignore_errors = True)

From 49024462f39e79a3b477306f46ea2f9f1dd18e73 Mon Sep 17 00:00:00 2001
From: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Date: Thu, 11 Jun 2026 13:13:27 +0100
Subject: [PATCH 184/222] Studio: ignore unsupported env proxy during Studio
 startup (#6102)

* fix: ignore unsupported env proxy during Studio startup

* fix: handle missing socksio env proxy at startup

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Match printf logging style and inline the proxy predicate for PR #6102

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../core/inference/external_provider.py       | 21 ++++-
 .../tests/test_external_provider_proxy_env.py | 80 +++++++++++++++++++
 2 files changed, 98 insertions(+), 3 deletions(-)
 create mode 100644 studio/backend/tests/test_external_provider_proxy_env.py

diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index a7d44b992d..cae001c34d 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -469,9 +469,24 @@ def _apply_mistral_reasoning_controls(
 
 
 # Shared client reused across all requests for HTTP connection pooling.
-# Auth headers and timeouts are per-request, so one client handles every
-# provider without storing credentials.
-_http_client = httpx.AsyncClient()
+# Auth headers and timeouts are passed per-request, so a single client
+# handles every provider without storing credentials.
+def _create_shared_http_client() -> httpx.AsyncClient:
+    # Unsupported env proxy schemes (socks:// etc) raise at construction and
+    # would crash Studio startup (#6090); retry ignoring env proxies instead.
+    try:
+        return httpx.AsyncClient()
+    except (ImportError, ValueError) as exc:
+        exc_str = str(exc)
+        if "Unknown scheme for proxy URL" not in exc_str and "socksio" not in exc_str:
+            raise
+        logger.warning(
+            "Ignoring unsupported environment proxy for the shared HTTP client: %s", exc_str
+        )
+        return httpx.AsyncClient(trust_env = False)
+
+
+_http_client = _create_shared_http_client()
 
 
 # Cap per-image fetch well below Gemini's ~20 MB total request budget.
diff --git a/studio/backend/tests/test_external_provider_proxy_env.py b/studio/backend/tests/test_external_provider_proxy_env.py
new file mode 100644
index 0000000000..f17b655908
--- /dev/null
+++ b/studio/backend/tests/test_external_provider_proxy_env.py
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from pathlib import Path
+import importlib.util
+import sys
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+_EXTERNAL_PROVIDER_PATH = (
+    Path(__file__).resolve().parent.parent / "core/inference/external_provider.py"
+)
+
+
+def _load_external_provider_module():
+    spec = importlib.util.spec_from_file_location(
+        "external_provider_under_test",
+        _EXTERNAL_PROVIDER_PATH,
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_shared_http_client_ignores_unsupported_proxy_scheme(monkeypatch):
+    ep_mod = _load_external_provider_module()
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, **kwargs):
+            calls.append(kwargs)
+            if kwargs.get("trust_env") is not False:
+                raise ValueError("Unknown scheme for proxy URL URL('socks4://127.0.0.1:12345')")
+
+    monkeypatch.setattr(ep_mod.httpx, "AsyncClient", FakeAsyncClient)
+
+    client = ep_mod._create_shared_http_client()
+
+    assert isinstance(client, FakeAsyncClient)
+    assert calls == [{}, {"trust_env": False}]
+
+
+def test_shared_http_client_ignores_missing_socksio(monkeypatch):
+    ep_mod = _load_external_provider_module()
+    calls = []
+
+    class FakeAsyncClient:
+        def __init__(self, **kwargs):
+            calls.append(kwargs)
+            if kwargs.get("trust_env") is not False:
+                raise ImportError(
+                    "Using SOCKS proxy, but the 'socksio' package is not installed. "
+                    "Make sure to install httpx using `pip install httpx[socks]`."
+                )
+
+    monkeypatch.setattr(ep_mod.httpx, "AsyncClient", FakeAsyncClient)
+
+    client = ep_mod._create_shared_http_client()
+
+    assert isinstance(client, FakeAsyncClient)
+    assert calls == [{}, {"trust_env": False}]
+
+
+def test_shared_http_client_reraises_other_value_errors(monkeypatch):
+    ep_mod = _load_external_provider_module()
+
+    class FakeAsyncClient:
+        def __init__(self, **kwargs):
+            raise ValueError("different httpx setup error")
+
+    monkeypatch.setattr(ep_mod.httpx, "AsyncClient", FakeAsyncClient)
+
+    try:
+        ep_mod._create_shared_http_client()
+    except ValueError as exc:
+        assert str(exc) == "different httpx setup error"
+    else:
+        raise AssertionError("expected ValueError")

From d0ffe2638321ff5f6abbcfe8d0567e1170cc3a74 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 05:18:12 -0700
Subject: [PATCH 185/222] Keep audio feature extractors right padded when
 loading processors (#6157)

* Keep audio feature extractors right padded when loading processors

FastBaseModel.from_pretrained passes padding_side=left to
AutoProcessor.from_pretrained for generation, and ProcessorMixin forwards
the kwarg to every sub-component, including audio feature extractors.
Stock transformers right-pads audio: frame-validity masks assume trailing
padding. The leaked left padding shifts mel content to the end of the 30s
window for Whisper and gives Gemma 4 one extra valid mel frame on clip
lengths off the hop boundary, desyncing audio features from placeholder
tokens and crashing training on transformers 5.5.0 to 5.9.x with 'Audio
features and audio tokens do not match'.

Reset the feature extractor to right padding at the single processor
finalization point. Text tokenizer padding stays left. Verified on
transformers 5.5.0: the loaded processor now matches a fresh stock
AutoProcessor exactly, and a 9-combination Gemma 4 audio forward probe
goes from 4 failures to none.

* Add explicit None check before reading feature extractor attributes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Tighten comments

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 unsloth/models/vision.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 34336aa80f..58814699b3 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -1280,6 +1280,15 @@ class FastBaseModel:
         tokenizer.padding_side = "left"  # Force inference
         if hasattr(tokenizer, "tokenizer"):
             tokenizer.tokenizer.padding_side = "left"  # Force inference
+        # Audio feature extractors must stay right padded: left (a text setting,
+        # forwarded by from_pretrained) shifts Whisper mels and desyncs Gemma 4
+        # audio token counts (crash on transformers < 5.10).
+        feature_extractor = getattr(tokenizer, "feature_extractor", None)
+        if (
+            feature_extractor is not None
+            and getattr(feature_extractor, "padding_side", None) == "left"
+        ):
+            feature_extractor.padding_side = "right"
         m = model
         while hasattr(m, "model"):
             m.max_seq_length = max_seq_length

From 36bc0394d93ad5168ade756ad8021e643caca0f5 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 05:22:38 -0700
Subject: [PATCH 186/222] Studio: fetch the release source asset for exact
 (mix) source builds (#6195)

* Studio: fetch the release source asset for exact (mix) source builds

The source-build fallback rebuilt the codeload/archive URL from the
source repo and commit. A mix build's merged tree is never pushed to any
repo (it ships only as the release's llama.cpp-source-commit-<sha>.tar.gz
asset), so codeload 404s on the merge commit and an uncovered host could
not build from source. When an exact-source asset exists, fetch it
directly from the release and keep codeload as the fallback for vanilla
builds whose commit is real.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/install_llama_prebuilt.py              |  30 ++++-
 .../test_install_llama_prebuilt_logic.py      | 104 ++++++++++++++++++
 2 files changed, 133 insertions(+), 1 deletion(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 22fab82923..6c3be0e09f 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -1095,6 +1095,20 @@ def commit_source_archive_urls(repo: str, source_commit: str) -> list[str]:
     ]
 
 
+def release_asset_download_url(
+    repo: str | None, release_tag: str | None, asset_name: str | None
+) -> str | None:
+    """Direct download URL for a release asset, or None if any part is missing.
+    A mix build's merged commit is never pushed, so its source tree is only
+    reachable as this asset (codeload would 404 on the merge commit)."""
+    if not repo or not release_tag or not asset_name:
+        return None
+    return (
+        f"https://github.com/{repo}/releases/download/"
+        f"{urllib.parse.quote(release_tag, safe = '')}/{urllib.parse.quote(asset_name, safe = '')}"
+    )
+
+
 def github_release_assets(repo: str, tag: str) -> dict[str, str]:
     payload = fetch_json(
         f"https://api.github.com/repos/{repo}/releases/tags/{urllib.parse.quote(tag, safe = '')}"
@@ -4495,13 +4509,17 @@ def hydrate_source_tree(
     expected_sha256: str | None,
     source_label: str | None = None,
     exact_source: bool = False,
+    asset_url: str | None = None,
 ) -> None:
     archive_path = work_dir / f"llama.cpp-source-{source_ref}.tar.gz"
-    source_urls = (
+    repo_urls = (
         commit_source_archive_urls(source_repo, source_ref)
         if exact_source
         else upstream_source_archive_urls(source_ref)
     )
+    # Prefer the published release asset (the only copy of a mix build's merged
+    # tree); fall back to codeload/archive for vanilla builds whose commit is real.
+    source_urls = ([asset_url] if asset_url else []) + repo_urls
     label = source_label or f"llama.cpp source tree for {source_ref}"
     extract_dir = Path(tempfile.mkdtemp(prefix = "source-extract-", dir = work_dir))
 
@@ -6404,6 +6422,15 @@ def validate_prebuilt_choice(
     source_repo, source_ref, source_archive, exact_source = preferred_source_archive(
         approved_checksums, llama_tag
     )
+    # For an exact (mix) source the merge commit lives only in the release asset,
+    # not in any repo, so fetch the asset directly; codeload stays the fallback.
+    asset_url = (
+        release_asset_download_url(
+            approved_checksums.repo, approved_checksums.release_tag, source_archive.asset_name
+        )
+        if exact_source and source_archive is not None
+        else None
+    )
     if exact_source:
         log(f"hydrating exact llama.cpp source for {source_repo}@{source_ref} into {install_dir}")
     else:
@@ -6420,6 +6447,7 @@ def validate_prebuilt_choice(
             else f"llama.cpp source tree for {llama_tag}"
         ),
         exact_source = exact_source,
+        asset_url = asset_url,
     )
     log(f"overlaying prebuilt bundle {choice.name} into {install_dir}")
     server_path, quantize_path = install_from_archives(choice, host, install_dir, work_dir)
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 057612d27b..7ca87aa8c4 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -206,6 +206,110 @@ def test_hydrate_source_tree_extracts_upstream_archive_contents(
     assert not (install_dir / f"llama.cpp-{upstream_tag}").exists()
 
 
+def test_release_asset_download_url():
+    fn = INSTALL_LLAMA_PREBUILT.release_asset_download_url
+    assert fn(
+        "unslothai/llama.cpp", "b9000-mix-abc1234", "llama.cpp-source-commit-deadbeef.tar.gz"
+    ) == (
+        "https://github.com/unslothai/llama.cpp/releases/download/"
+        "b9000-mix-abc1234/llama.cpp-source-commit-deadbeef.tar.gz"
+    )
+    # Any missing component -> None (no asset url, caller falls back to codeload).
+    assert fn(None, "b9000", "x.tar.gz") is None
+    assert fn("unslothai/llama.cpp", None, "x.tar.gz") is None
+    assert fn("unslothai/llama.cpp", "b9000", None) is None
+
+
+def _mk_source_tarball(path: Path, tag: str) -> None:
+    with tarfile.open(path, "w:gz") as archive:
+        add_bytes_to_tar(
+            archive, f"llama.cpp-{tag}/CMakeLists.txt", b"cmake_minimum_required(VERSION 3.14)\n"
+        )
+        add_bytes_to_tar(
+            archive,
+            f"llama.cpp-{tag}/convert_hf_to_gguf.py",
+            b"#!/usr/bin/env python3\nimport gguf\n",
+        )
+        add_bytes_to_tar(archive, f"llama.cpp-{tag}/gguf-py/gguf/__init__.py", b"__all__ = []\n")
+
+
+def test_hydrate_source_tree_prefers_release_asset_for_mix(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    # A mix build's merge commit is in no repo, so the codeload/archive URLs 404.
+    # hydrate must fetch the release asset and never touch codeload.
+    commit = "a" * 40
+    archive_path = tmp_path / "merged-source.tar.gz"
+    _mk_source_tarball(archive_path, f"b9000-mix-{commit[:7]}")
+    asset_url = INSTALL_LLAMA_PREBUILT.release_asset_download_url(
+        "unslothai/llama.cpp", "b9000-mix-abc1234", f"llama.cpp-source-commit-{commit}.tar.gz"
+    )
+    codeload_urls = set(
+        INSTALL_LLAMA_PREBUILT.commit_source_archive_urls("unslothai/llama.cpp", commit)
+    )
+    seen = []
+
+    def fake_download_file(url: str, destination: Path) -> None:
+        seen.append(url)
+        if url in codeload_urls:
+            raise AssertionError("codeload was hit even though the release asset was available")
+        assert url == asset_url
+        destination.write_bytes(archive_path.read_bytes())
+
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "download_file", fake_download_file)
+
+    install_dir = tmp_path / "install"
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    hydrate_source_tree(
+        commit,
+        install_dir,
+        work_dir,
+        source_repo = "unslothai/llama.cpp",
+        expected_sha256 = sha256_file(archive_path),
+        exact_source = True,
+        asset_url = asset_url,
+    )
+    assert seen == [asset_url]
+    assert (install_dir / "CMakeLists.txt").exists()
+    assert (install_dir / "convert_hf_to_gguf.py").exists()
+
+
+def test_hydrate_source_tree_falls_back_to_codeload_when_asset_missing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    # If the release asset 404s, fall back to codeload/archive (vanilla path).
+    commit = "b" * 40
+    archive_path = tmp_path / "vanilla-source.tar.gz"
+    _mk_source_tarball(archive_path, f"commit-{commit[:7]}")
+    asset_url = INSTALL_LLAMA_PREBUILT.release_asset_download_url(
+        "unslothai/llama.cpp", "b9000", f"llama.cpp-source-commit-{commit}.tar.gz"
+    )
+    codeload_urls = INSTALL_LLAMA_PREBUILT.commit_source_archive_urls("unslothai/llama.cpp", commit)
+
+    def fake_download_file(url: str, destination: Path) -> None:
+        if url == asset_url:
+            raise RuntimeError("404 Not Found")
+        assert url in codeload_urls
+        destination.write_bytes(archive_path.read_bytes())
+
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "download_file", fake_download_file)
+
+    install_dir = tmp_path / "install"
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    hydrate_source_tree(
+        commit,
+        install_dir,
+        work_dir,
+        source_repo = "unslothai/llama.cpp",
+        expected_sha256 = sha256_file(archive_path),
+        exact_source = True,
+        asset_url = asset_url,
+    )
+    assert (install_dir / "CMakeLists.txt").exists()
+
+
 def test_validate_prebuilt_choice_creates_repo_shaped_linux_install(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ):

From 8628439ede1a71203285db36286e85ad98662f03 Mon Sep 17 00:00:00 2001
From: Dariton4000 <184837391+Dariton4000@users.noreply.github.com>
Date: Thu, 11 Jun 2026 14:27:13 +0200
Subject: [PATCH 187/222] fix: running unsloth inside of System32 now refuses
 to run and quits with an error (#5934)

* -Added catch for unsloth running inside of system32 (for windows)
- changed import statement to import os as _os instead of only os.path as _osp
- replaced __osp mention with __os.path

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Adressed geminis codereview. Did not change Error message as "System32" is precise enough and the _system32 variable is lowercase only

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Etherll <61019402+Etherll@users.noreply.github.com>
---
 unsloth_cli/__init__.py | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.py
index c8ec4c66c0..e1047a6515 100644
--- a/unsloth_cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import os.path as _osp
+import os as _os
 import sys as _sys
 
 import typer
@@ -20,7 +20,7 @@ from unsloth_cli.commands.studio import (
 
 # Canonicalise `-np<N>` only under the `unsloth` console-script;
 # third-party scripts that import unsloth_cli keep their argv intact.
-_entry_base = _osp.basename(_sys.argv[0]).lower() if _sys.argv else ""
+_entry_base = _os.path.basename(_sys.argv[0]).lower() if _sys.argv else ""
 if _entry_base in {"unsloth", "unsloth.exe"}:
     _expand_attached_np_short()
 del _entry_base
@@ -53,7 +53,21 @@ def main(
         help = "Show version and exit.",
     ),
 ):
-    pass
+    if (
+        _sys.platform == "win32"
+    ):  # this block catches unsloth running inside of System32 or any subdirs, this WILL cause errors if not prevented.
+        _cwd = _os.path.normcase(_os.path.normpath(_os.getcwd()))
+        _system32 = _os.path.normcase(
+            _os.path.normpath(_os.path.join(_os.environ.get("WINDIR", r"C:\Windows"), "System32"))
+        )
+        if _cwd == _system32 or _cwd.startswith(_system32 + _os.sep):
+            typer.secho(
+                "Refusing to run Unsloth inside System32 as it will lead to Errors.\n"
+                "cd to a normal working directory and try again.",
+                fg = "red",
+                err = True,
+            )
+            raise typer.Exit(code = 1)
 
 
 app.command()(train)

From c3604d01f7a009eba021a38aa1ab71b51b46e43d Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 05:27:46 -0700
Subject: [PATCH 188/222] Studio: enable MTP for sub-3B Gemma separate-drafter
 GGUFs (#6191)

* Studio: enable MTP for sub-3B Gemma separate-drafter GGUFs

The sub-3B auto-drop to ngram-mod was tuned for an embedded draft head
(Qwen), whose per-token cost regresses below 3B. Gemma ships the head as a
separate root mtp-*.gguf drafter, a tiny standalone model that is cheap
enough to win below 3B: B200 Q4_K_XL bench, draft-mtp n=2 vs spec-off,
gemma-4-E2B (2B) = 1.21x (accept ~0.65) while ngram-mod is 1.00x.

Exempt a separate drafter from the sub-3B gate everywhere the threshold is
applied: the resolver (_mtp_too_small), the auto-fit VRAM reserve, the
drafter auto-download decision, and the reload-skip mirror via a
has_separate_drafter flag on _auto_mode_drops_mtp. Embedded sub-3B heads
(Qwen) still drop to ngram-mod. A drafter the binary cannot build (older
prebuilt, or a CUDA kernel limit) still aborts the spawn and the load
retries once without speculative decoding.

Adds the full Qwen3.5 + Gemma-4 (regular and QAT) auto/off/forced resolver
matrix, plus explicit sub-3B exemption tests.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Always compare the separate drafter in the reload-skip mirror

The sub-3B wrapper around the drafter compare could skip it when the drafter
was deleted out from under a running sub-3B server (detected None, stored set),
leaving a stale launch. The resolved-path compare is cheap and already handles
every case, so drop the _auto_mode_drops_mtp guard (and its now-unused imports)
and always compare when the mode can use a drafter and the user does not own
--spec-type. Addresses review feedback on #6191.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    |  60 ++++--
 studio/backend/routes/inference.py            |  26 +--
 .../tests/test_llama_cpp_mtp_detection.py     | 180 ++++++++++++++++++
 3 files changed, 230 insertions(+), 36 deletions(-)

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 85ca32eaf5..7d67097d09 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -514,9 +514,18 @@ _CTX_FIT_VRAM_FRACTION = 0.90
 _MTP_VRAM_RESERVE_FRAC = 0.05
 
 
-def _auto_mode_drops_mtp(req_mode: Optional[str], size_b: Optional[float]) -> bool:
-    """Auto mode drops MTP below _MTP_MIN_SIZE_B (draft-mtp regresses there);
-    forced mtp / mtp+ngram engage regardless of size."""
+def _auto_mode_drops_mtp(
+    req_mode: Optional[str],
+    size_b: Optional[float],
+    *,
+    has_separate_drafter: bool = False,
+) -> bool:
+    """Auto mode drops MTP below _MTP_MIN_SIZE_B for an embedded draft head
+    (its per-token cost regresses there); a separate drafter (Gemma) is a tiny
+    standalone model that still speeds up below 3B, so it never drops. Forced
+    mtp / mtp+ngram engage regardless of size."""
+    if has_separate_drafter:
+        return False
     return req_mode == "auto" and size_b is not None and size_b < _MTP_MIN_SIZE_B
 
 
@@ -2910,19 +2919,14 @@ class LlamaCppBackend:
                     # Auto-download the separate MTP drafter (e.g. Gemma) when
                     # the requested spec mode can use it. Repos with the head
                     # baked into the main GGUF (Qwen) have no mtp- sibling and
-                    # this no-ops. Skipped when the user disabled MTP, drives
-                    # --spec-type manually via extra_args, or in auto mode on a
-                    # sub-3B model (e.g. Gemma E2B) where the resolver drops
-                    # MTP anyway -- no point fetching a drafter it never uses.
-                    # Forced mtp / mtp+ngram still download (user override).
+                    # this no-ops, so the size gate stays out of it: a separate
+                    # drafter speeds up even sub-3B (Gemma E2B), and the resolver
+                    # below decides the final emission. Skipped only when the
+                    # user disabled MTP or drives --spec-type manually.
                     _spec_canon = _canonicalize_spec_mode(speculative_type) or "auto"
-                    _auto_drops_mtp = _auto_mode_drops_mtp(
-                        _spec_canon, _extract_model_size_b(model_identifier)
-                    )
                     if (
                         not mtp_draft_path
                         and _spec_canon in ("auto", "mtp", "mtp+ngram")
-                        and not _auto_drops_mtp
                         and not _extra_args_set_spec_type(extra_args)
                     ):
                         mtp_draft_path = self._download_mtp(
@@ -3002,8 +3006,12 @@ class LlamaCppBackend:
                     _mtp_canonical = _canonicalize_spec_mode(speculative_type)
                     _mtp_effective = _mtp_canonical or "auto"
                     _mtp_size_for_fit = _extract_model_size_b(model_identifier)
+                    # Sub-3B drops MTP only for an embedded head; a separate
+                    # drafter (Gemma) engages and needs its VRAM reserved.
                     _mtp_sub_3b_for_fit = (
-                        _mtp_size_for_fit is not None and _mtp_size_for_fit < _MTP_MIN_SIZE_B
+                        _mtp_size_for_fit is not None
+                        and _mtp_size_for_fit < _MTP_MIN_SIZE_B
+                        and not bool(mtp_draft_path)
                     )
                     _mtp_will_engage = bool(
                         not _extra_args_set_spec_type(extra_args)
@@ -3771,18 +3779,26 @@ class LlamaCppBackend:
               https://github.com/ggml-org/llama.cpp/pull/18471
               MTP guide: unsloth.ai/docs/models/qwen3.6#mtp-guide
 
-        Sub-3B dense MTP regresses vs spec-off: the draft head's per-token
-        cost exceeds the acceptance savings at this scale. Q4_K_XL clean
-        bench (each prompt once after an unrelated warmup) on B200 + x86 CPU:
+        Sub-3B dense MTP regresses vs spec-off when the head is baked into the
+        main GGUF (Qwen): the draft head's per-token cost exceeds the
+        acceptance savings at this scale. Q4_K_XL clean bench (each prompt once
+        after an unrelated warmup) on B200 + x86 CPU:
           0.8B GPU: draft-mtp n=2 = 0.58x vs OFF; ngram-only = 1.10x
           2B   GPU: draft-mtp n=2 = 0.82x vs OFF; OFF or ngram = 1.00x
           0.8B CPU: chained n=2   = 0.86x vs OFF; ngram-only = 1.19x
           2B   CPU: chained n=2   = 0.83x vs OFF; ngram-only = 1.01x
           4B+ GPU/CPU: spec on is a net win (1.08x-1.46x).
+        A separate drafter (Gemma's root mtp-*.gguf) is a different, cheaper
+        mechanism that wins even below 3B, so it is exempt from the sub-3B drop
+        (``mtp_draft_path`` set -> not too small). B200 Q4_K_XL bench, draft-mtp
+        n=2 vs OFF: gemma-4-E2B (2B) = 1.21x, accept ~0.65 (vs ngram = 1.00x);
+        gemma-4-E4B (4B) and 12B engage as usual.
         Auto falls back to ngram-mod (zero-VRAM, near-zero idle cost on
-        diverse content); forced MTP on a model with no head/drafter defaults
-        back (mtp -> spec-default, mtp+ngram -> ngram-mod) since llama-server
-        aborts otherwise; sub-3B real-MTP engages with a warning.
+        diverse content) for an embedded sub-3B head; forced MTP on a model
+        with no head/drafter defaults back (mtp -> spec-default, mtp+ngram ->
+        ngram-mod) since llama-server aborts otherwise; a drafter the binary
+        cannot build (older prebuilt, or a CUDA kernel limit) aborts the spawn
+        and the load retries once without speculative decoding.
         """
         flags: List[str] = []
         # Reset; emit branches re-set on the resolved emission.
@@ -3801,7 +3817,11 @@ class LlamaCppBackend:
         )
         user_owns_spec_type = _extra_args_set_spec_type(extra_args)
         _mtp_size_b = _extract_model_size_b(model_identifier)
-        _mtp_too_small = _mtp_size_b is not None and _mtp_size_b < _MTP_MIN_SIZE_B
+        # The sub-3B regression is an embedded-head cost; a separate drafter
+        # (Gemma) is a cheap standalone model that wins below 3B, so exempt it.
+        _mtp_too_small = (
+            _mtp_size_b is not None and _mtp_size_b < _MTP_MIN_SIZE_B and not bool(mtp_draft_path)
+        )
 
         if user_owns_spec_type:
             # User --spec-type wins outright; suppress auto-emit to avoid a
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 4cc76e7c2a..ef67f8bb59 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -417,7 +417,6 @@ try:
         LlamaCppBackend,
         _DEFAULT_MAX_TOKENS_FLOOR,
         _DEFAULT_T_MAX_PREDICT_MS,
-        _auto_mode_drops_mtp,
         _canonicalize_spec_mode,
         _extra_args_set_spec_type,
         _hf_offline_if_dns_dead,
@@ -431,7 +430,6 @@ try:
     from utils.inference import load_inference_config
     from utils.models.model_config import (
         detect_mtp_file,
-        extract_model_size_b,
         load_model_defaults,
     )
     from utils.native_path_leases import (
@@ -450,7 +448,6 @@ except ImportError:
         LlamaCppBackend,
         _DEFAULT_MAX_TOKENS_FLOOR,
         _DEFAULT_T_MAX_PREDICT_MS,
-        _auto_mode_drops_mtp,
         _canonicalize_spec_mode,
         _extra_args_set_spec_type,
         _hf_offline_if_dns_dead,
@@ -464,7 +461,6 @@ except ImportError:
     from utils.inference import load_inference_config
     from utils.models.model_config import (
         detect_mtp_file,
-        extract_model_size_b,
         load_model_defaults,
     )
     from utils.native_path_leases import (
@@ -1025,14 +1021,15 @@ def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaC
     else:
         if list(request.llama_extra_args) != backend_extra:
             return False
-    # A drafter that appeared next to the loaded weights since the last load
-    # changes the launch command (--model-draft) when the mode can use it;
-    # without this, a duplicate /load is deduped and MTP can't engage short
-    # of an unload. Runs last: it stats the filesystem (two dir scans against
-    # the resolved weight path -- covers local dirs and HF cache snapshots
-    # alike), so every pure-memory comparison above short-circuits first.
-    # Skipped when auto drops MTP anyway (sub-3B) or the user owns
-    # --spec-type, where a drafter changes nothing. Resolve both sides: the
+    # A separate drafter (Gemma's root mtp-*.gguf) appearing or disappearing
+    # next to the loaded weights changes the launch command (--model-draft),
+    # so a duplicate /load must reload rather than dedupe. Always compare the
+    # detected vs stored drafter when the mode can use one and the user does
+    # not own --spec-type: the resolved-path compare is cheap and handles all
+    # four cases (both None -> match; one None -> reload; equal -> match;
+    # different -> reload), including a drafter deleted out from under a
+    # running server. Runs last: it stats the filesystem, so every pure-memory
+    # comparison above short-circuits first. Resolve both sides since the
     # stored launch path may be a snapshot symlink while detect_mtp_file
     # returns the resolved blob.
     if req_mode in ("auto", "mtp", "mtp+ngram") and llama_backend.gguf_path:
@@ -1041,10 +1038,7 @@ def _request_matches_loaded_settings(request: LoadRequest, llama_backend: LlamaC
             if request.llama_extra_args is not None
             else llama_backend.extra_args
         )
-        size_b = extract_model_size_b(llama_backend.model_identifier or "")
-        if not _auto_mode_drops_mtp(req_mode, size_b) and not _extra_args_set_spec_type(
-            effective_extras
-        ):
+        if not _extra_args_set_spec_type(effective_extras):
             detected = detect_mtp_file(llama_backend.gguf_path)
             stored = llama_backend.mtp_draft_path
             try:
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index 25ce71a774..a7f30d2951 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -1219,3 +1219,183 @@ def test_forced_mtp_ngram_on_non_mtp_model_keeps_ngram(monkeypatch):
     assert parsed.get("--spec-type") == "ngram-mod"
     assert backend.speculative_type == "ngram-mod"
     assert backend.requested_spec_mode == "mtp+ngram"
+
+
+# ── Full named-repo resolver matrix (the shipping Studio families) ─────
+#
+# Locks auto / off / forced-mtp routing for every Qwen3.5 (MTP + plain) and
+# gemma-4 (regular + QAT) GGUF repo, including the giant MoEs that stay
+# resolver-only (122B-A10B / 397B-A17B). Expectations are derived from the
+# same signals load_model uses -- _extract_model_size_b (active>effective>
+# total, so E2B->2, A3B->3, A10B->10, A17B->17), _is_mtp_model_name, and the
+# separate-drafter flag -- so each row mirrors what the loader emits on a
+# B200 (GPU default, n=2). gemma carries no -MTP marker; its MTP comes from
+# the root mtp-*.gguf drafter, modelled here by passing mtp_draft_path.
+#
+# auto_spec: "draft-mtp" = head/drafter engaged (>=3B MTP, or any size with a
+# separate drafter); "ngram-mod" = embedded sub-3B drop (zero-VRAM); None =
+# non-MTP -> llama-server --spec-default.
+
+_GEMMA_DRAFTER = "/snap/mtp-gemma-4-it.gguf"  # stand-in separate drafter
+
+_REAL_REPO_MATRIX = [
+    # repo, drafter, auto_spec, auto_ngram_knobs
+    ("unsloth/Qwen3.5-0.8B-MTP-GGUF", None, "ngram-mod", True),
+    ("unsloth/Qwen3.5-2B-MTP-GGUF", None, "ngram-mod", True),
+    ("unsloth/Qwen3.5-4B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-9B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-27B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-35B-A3B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-122B-A10B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-397B-A17B-MTP-GGUF", None, "draft-mtp", False),
+    ("unsloth/Qwen3.5-0.8B-GGUF", None, None, False),
+    ("unsloth/Qwen3.5-2B-GGUF", None, None, False),
+    ("unsloth/Qwen3.5-4B-GGUF", None, None, False),
+    ("unsloth/Qwen3.5-9B-GGUF", None, None, False),
+    # E2B is 2B but ships a separate drafter -> exempt from the sub-3B drop.
+    ("unsloth/gemma-4-E2B-it-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-E4B-it-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-12b-it-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-26B-A4B-it-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-31B-it-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-E2B-it-qat-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-E4B-it-qat-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-12b-it-qat-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-26B-A4B-it-qat-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+    ("unsloth/gemma-4-31B-it-qat-GGUF", _GEMMA_DRAFTER, "draft-mtp", False),
+]
+
+
+def _resolve_real(monkeypatch, repo, drafter, mode):
+    backend = _resolver_backend(monkeypatch)
+    flags = backend._build_speculative_flags(
+        speculative_type = mode,
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = repo,
+        model_path = None,
+        gpus = True,  # B200 default
+        binary = "/fake/llama-server",
+        mtp_draft_path = drafter,
+    )
+    return backend, flags, _flags_dict(flags)
+
+
+@pytest.mark.parametrize(
+    "repo, drafter, auto_spec, auto_ngram_knobs",
+    _REAL_REPO_MATRIX,
+    ids = [r[0].split("/")[-1] for r in _REAL_REPO_MATRIX],
+)
+def test_real_repo_auto_routing(monkeypatch, repo, drafter, auto_spec, auto_ngram_knobs):
+    # Auto is the default mode the dropdown ships with.
+    backend, flags, parsed = _resolve_real(monkeypatch, repo, drafter, "auto")
+    if auto_spec is None:
+        # Non-MTP: no draft-mtp, hand off to llama-server's own default.
+        assert "--spec-type" not in parsed
+        assert "--spec-default" in flags
+        assert backend.speculative_type == "default"
+    elif auto_spec == "draft-mtp":
+        assert parsed.get("--spec-type") == "draft-mtp"
+        assert parsed.get("--spec-draft-n-max") == "2"
+        assert backend.speculative_type == "draft-mtp"
+        # gemma ships a separate drafter; Qwen bakes the head into the GGUF.
+        assert (
+            (parsed.get("--model-draft") == drafter) if drafter else ("--model-draft" not in parsed)
+        )
+    else:  # ngram-mod (sub-3B MTP drop)
+        assert parsed.get("--spec-type") == "ngram-mod"
+        assert "--model-draft" not in parsed  # draft head dropped
+        assert backend.speculative_type == "ngram-mod"
+    if auto_ngram_knobs:
+        assert "--spec-ngram-mod-n-match" in parsed
+    assert backend.requested_spec_mode == "auto"
+
+
+@pytest.mark.parametrize(
+    "repo, drafter",
+    [(r[0], r[1]) for r in _REAL_REPO_MATRIX],
+    ids = [r[0].split("/")[-1] for r in _REAL_REPO_MATRIX],
+)
+def test_real_repo_off_emits_nothing(monkeypatch, repo, drafter):
+    # Off must suppress speculative decoding for every family.
+    backend, flags, _ = _resolve_real(monkeypatch, repo, drafter, "off")
+    assert flags == []
+    assert backend.speculative_type is None
+    assert backend.requested_spec_mode == "off"
+
+
+@pytest.mark.parametrize(
+    "repo, drafter",
+    [(r[0], r[1]) for r in _REAL_REPO_MATRIX],
+    ids = [r[0].split("/")[-1] for r in _REAL_REPO_MATRIX],
+)
+def test_real_repo_forced_mtp_never_aborts(monkeypatch, repo, drafter):
+    # Forcing MTP on the dropdown: real MTP models (name marker or separate
+    # drafter) engage draft-mtp even below 3B; non-MTP models default back to
+    # --spec-default instead of emitting a draft-mtp llama-server will abort on.
+    backend, flags, parsed = _resolve_real(monkeypatch, repo, drafter, "mtp")
+    is_real_mtp = _is_mtp_model_name(repo) or bool(drafter)
+    if is_real_mtp:
+        assert parsed.get("--spec-type") == "draft-mtp"
+        assert backend.speculative_type == "draft-mtp"
+        assert (
+            (parsed.get("--model-draft") == drafter) if drafter else ("--model-draft" not in parsed)
+        )
+    else:
+        assert "--spec-type" not in parsed
+        assert "--spec-default" in flags
+        assert backend.speculative_type == "default"
+    assert backend.requested_spec_mode == "mtp"
+
+
+# ── Sub-3B separate-drafter exemption (Gemma) ─────────────────────────
+#
+# The sub-3B MTP drop is an embedded-head cost (Qwen). A separate drafter
+# (Gemma's root mtp-*.gguf) is a cheap standalone model that wins below 3B
+# (B200 Q4_K_XL: gemma-4-E2B draft-mtp n=2 = 1.21x vs OFF), so it is exempt.
+
+
+def test_sub3b_gemma_separate_drafter_engages_mtp(monkeypatch):
+    backend = _resolver_backend(monkeypatch)
+    flags = backend._build_speculative_flags(
+        speculative_type = "auto",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = "unsloth/gemma-4-E2B-it-GGUF",  # 2B
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+        mtp_draft_path = "/snap/mtp-gemma-4-E2B-it.gguf",  # separate drafter
+    )
+    parsed = _flags_dict(flags)
+    assert parsed.get("--spec-type") == "draft-mtp"
+    assert parsed.get("--model-draft") == "/snap/mtp-gemma-4-E2B-it.gguf"
+    assert "--spec-ngram-mod-n-match" not in parsed
+    assert backend.speculative_type == "draft-mtp"
+
+
+def test_sub3b_qwen_embedded_head_still_drops_to_ngram(monkeypatch):
+    backend = _resolver_backend(monkeypatch)
+    flags = backend._build_speculative_flags(
+        speculative_type = "auto",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = "unsloth/Qwen3.5-2B-MTP-GGUF",  # 2B, embedded head
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+        mtp_draft_path = None,  # no separate drafter
+    )
+    parsed = _flags_dict(flags)
+    assert parsed.get("--spec-type") == "ngram-mod"
+    assert "--model-draft" not in parsed
+    assert backend.speculative_type == "ngram-mod"
+
+
+def test_auto_mode_drops_mtp_exempts_separate_drafter():
+    from core.inference.llama_cpp import _auto_mode_drops_mtp
+
+    assert _auto_mode_drops_mtp("auto", 2.0) is True
+    assert _auto_mode_drops_mtp("auto", 2.0, has_separate_drafter = True) is False
+    assert _auto_mode_drops_mtp("auto", 4.0) is False
+    assert _auto_mode_drops_mtp("mtp", 2.0) is False  # forced engages regardless

From a22169941d0a7789b0ef16b314767c5bd2d463db Mon Sep 17 00:00:00 2001
From: Tai An <antai12232931@outlook.com>
Date: Thu, 11 Jun 2026 05:30:08 -0700
Subject: [PATCH 189/222] fix(studio): fall back to copy when os.replace is
 blocked during install activation (#6133)

* fix(studio): fall back to copy when os.replace is blocked during install activation

On Windows ARM64 the antivirus scanner can transiently hold a freshly
extracted DLL open while MoveFileEx runs, so activating the staged
llama.cpp prebuilt fails with [WinError 5] Access is denied. Attempt
os.replace first, then fall back to a file-by-file copytree which
bypasses the rename.

* address review: keep os.replace for rollback, scope copy-fallback to staging

The copy + rmtree fallback could silently corrupt a live install if the
existing directory is busy. Restrict it to freshly extracted staging
trees (renamed activate_staged_dir) and keep strict os.replace for the
rollback move so a busy active install raises immediately.

* fix(studio): scope copy-fallback to busy-lock errors, log it, and add tests

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: Etherll <61019402+Etherll@users.noreply.github.com>
---
 studio/install_llama_prebuilt.py              | 31 ++++++++++++-
 .../test_install_llama_prebuilt_logic.py      | 44 +++++++++++++++++++
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 6c3be0e09f..64ea255803 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -4870,6 +4870,35 @@ def confirm_install_tree(install_dir: Path, host: HostInfo) -> None:
         raise RuntimeError("activated install was missing expected files: " + ", ".join(missing))
 
 
+def activate_staged_dir(staging_dir: Path, dst: Path) -> None:
+    """Move a freshly extracted ``staging_dir`` onto ``dst``.
+
+    ``os.replace`` is attempted first as the fast path. On Windows ARM64 the
+    antivirus scanner can transiently hold a freshly extracted DLL open at the
+    moment ``MoveFileEx`` runs, surfacing as ``[WinError 5] Access is denied``;
+    a file-by-file copy bypasses the rename entirely.
+
+    This fallback is intentionally limited to staging trees we just extracted.
+    It must not be used to move an existing/active install aside: there an
+    ``os.replace`` failure means the directory is genuinely in use, and a
+    silent copy + ``rmtree`` could partially delete a live install.
+
+    Only busy/lock errors (``is_busy_lock_error``) trigger the copy; anything
+    else (disk full, cross-device, missing path) re-raises so it cannot leave
+    a partially copied install behind. A copy is preferred over retrying the
+    rename because antivirus scans of large DLLs can outlast any reasonable
+    retry window.
+    """
+    try:
+        os.replace(staging_dir, dst)
+    except OSError as exc:
+        if not is_busy_lock_error(exc):
+            raise
+        log(f"os.replace failed ({exc!r}); falling back to file-by-file copy of staging tree")
+        shutil.copytree(staging_dir, dst, dirs_exist_ok = True)
+        remove_tree(staging_dir)
+
+
 def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo) -> None:
     rollback_dir: Path | None = None
     failed_dir: Path | None = None
@@ -4881,7 +4910,7 @@ def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo)
             log(f"moved existing install to rollback path {rollback_dir.name}")
 
         log(f"activating staged install {staging_dir} -> {install_dir}")
-        os.replace(staging_dir, install_dir)
+        activate_staged_dir(staging_dir, install_dir)
         log(f"activated staged install at {install_dir}")
         log(f"confirming activated install tree at {install_dir}")
         confirm_install_tree(install_dir, host)
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 7ca87aa8c4..000c5a7ace 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -1,3 +1,4 @@
+import errno
 import importlib.util
 import io
 import json
@@ -28,6 +29,7 @@ ApprovedReleaseChecksums = INSTALL_LLAMA_PREBUILT.ApprovedReleaseChecksums
 hydrate_source_tree = INSTALL_LLAMA_PREBUILT.hydrate_source_tree
 validate_prebuilt_choice = INSTALL_LLAMA_PREBUILT.validate_prebuilt_choice
 activate_install_tree = INSTALL_LLAMA_PREBUILT.activate_install_tree
+activate_staged_dir = INSTALL_LLAMA_PREBUILT.activate_staged_dir
 create_install_staging_dir = INSTALL_LLAMA_PREBUILT.create_install_staging_dir
 sha256_file = INSTALL_LLAMA_PREBUILT.sha256_file
 source_archive_logical_name = INSTALL_LLAMA_PREBUILT.source_archive_logical_name
@@ -666,6 +668,48 @@ def test_activate_install_tree_cleans_all_paths_when_rollback_restore_fails(
     assert "removing rollback path" in output
 
 
+def test_activate_staged_dir_copies_when_replace_hits_busy_lock(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    staging_dir = tmp_path / "llama.cpp.staging-test"
+    (staging_dir / "bin").mkdir(parents = True)
+    (staging_dir / "bin" / "ggml-base.dll").write_bytes(b"fake dll")
+    dst = tmp_path / "llama.cpp"
+
+    def denied_replace(src, dst_arg):
+        raise PermissionError(errno.EACCES, "Access is denied", str(src))
+
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", denied_replace)
+
+    activate_staged_dir(staging_dir, dst)
+
+    assert (dst / "bin" / "ggml-base.dll").read_bytes() == b"fake dll"
+    assert not staging_dir.exists()
+
+    captured = capsys.readouterr()
+    assert "falling back to file-by-file copy" in captured.out + captured.err
+
+
+def test_activate_staged_dir_reraises_non_busy_errors(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    staging_dir = tmp_path / "llama.cpp.staging-test"
+    staging_dir.mkdir()
+    (staging_dir / "new.txt").write_text("new install\n")
+    dst = tmp_path / "llama.cpp"
+
+    def out_of_space_replace(src, dst_arg):
+        raise OSError(errno.ENOSPC, "No space left on device", str(src))
+
+    monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", out_of_space_replace)
+
+    with pytest.raises(OSError, match = "No space left on device"):
+        activate_staged_dir(staging_dir, dst)
+
+    assert not dst.exists()
+    assert (staging_dir / "new.txt").read_text() == "new install\n"
+
+
 def test_binary_env_linux_includes_binary_parent_in_ld_library_path(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ):

From ab9689c034ace6fef573ce017bbb30908826b114 Mon Sep 17 00:00:00 2001
From: Prathamesh Jadhav <55660103+lollinng@users.noreply.github.com>
Date: Thu, 11 Jun 2026 18:00:54 +0530
Subject: [PATCH 190/222] Handle canonical inputs_embeds kwarg in
 unsloth_base_fast_generate (#3082) (#6015)

The kwarg-dispatch in unsloth_base_fast_generate recognized input_ids,
input, input_features and the misspelled input_embeds, but not HF's
canonical inputs_embeds. So generate(inputs_embeds=...) fell through to the
'first kwarg' fallback, which picks whatever kwarg happens to come first
(e.g. attention_mask) and uses it as input_ids -- giving the wrong tensor /
batch size, or the KeyError reported in #3082 on older versions.

Add an explicit inputs_embeds branch so embedding inputs (e.g. multimodal
audio+text) are routed correctly regardless of kwarg order.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Etherll <61019402+Etherll@users.noreply.github.com>
---
 unsloth/models/vision.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 58814699b3..a52ab359bd 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -283,6 +283,9 @@ def unsloth_base_fast_generate(self, *args, **kwargs):
         input_ids = kwargs["input"]
     elif "input_features" in kwargs:
         input_ids = kwargs["input_features"]
+    elif "inputs_embeds" in kwargs:
+        # canonical HF name for embedding inputs (e.g. multimodal generate)
+        input_ids = kwargs["inputs_embeds"]
     elif "input_embeds" in kwargs:
         input_ids = kwargs["input_embeds"]
     elif "inputs" in kwargs:

From c84ba48dd64cb04ce16d171cdeadc6d13a77e6c4 Mon Sep 17 00:00:00 2001
From: Abhinav <abhinaaavvv07187@gmail.com>
Date: Thu, 11 Jun 2026 18:08:35 +0530
Subject: [PATCH 191/222] fix: don't block the event loop with time.sleep in
 async load_checkpoint (#6135)

The export route's load_checkpoint waits for the training subprocess to
exit by calling time.sleep(0.5) in a loop (up to 30s) inside an async
function. time.sleep blocks the whole event loop, so every other request
to the server stalls for that duration. Use await asyncio.sleep(0.5),
matching the async pattern already used elsewhere in this file
(asyncio.to_thread, await asyncio.sleep).

Co-authored-by: Wasim Yousef Said <wasimysdev@gmail.com>
---
 studio/backend/routes/export.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index abb89a13da..ef37daa158 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -78,8 +78,7 @@ async def load_checkpoint(
                 for _ in range(60):  # up to 30s
                     if not trn.is_training_active():
                         break
-                    import time
-                    time.sleep(0.5)
+                    await asyncio.sleep(0.5)
                 else:
                     logger.warning("Training subprocess did not exit within 30s, proceeding anyway")
         except Exception as e:

From 22e2b63d2ebd30411bb9b92710952c0b1cd90ff8 Mon Sep 17 00:00:00 2001
From: ashzak <ashzak@gmail.com>
Date: Thu, 11 Jun 2026 07:39:15 -0500
Subject: [PATCH 192/222] fix(studio): prevent UI freeze when switching tabs
 from heavy pages (#5978)

* fix(studio): prevent UI freeze when switching tabs from heavy pages

Change AnimatePresence mode from "wait" to "popLayout" to fix issue
where switching tabs from Export (or other heavy pages) would cause
the URL to update but the UI to freeze.

With mode="wait", the exit animation must complete before the new
component mounts. If the exiting page has expensive computations,
this blocks the UI. mode="popLayout" allows the new route to mount
immediately while the old one animates out.

Fixes #5850

* fix: add relative positioning for popLayout mode

AnimatePresence mode='popLayout' applies position: absolute to the
exiting element, so the parent container needs position: relative
to prevent layout jumps during transitions.

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/frontend/src/app/routes/__root.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index c8e47902b9..c05b0e6451 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -140,9 +140,14 @@ function RootLayout() {
           <SidebarInset className={isChatRoute ? "overflow-hidden" : "overflow-y-auto"}>
             <Navbar />
             <div
-              className={`flex min-h-0 min-w-0 flex-1 basis-0 flex-col ${isChatRoute ? "overflow-hidden" : "overflow-visible"} ${isChatRoute ? "" : "pt-14 md:pt-0"}`}
+              className={`relative flex min-h-0 min-w-0 flex-1 basis-0 flex-col ${isChatRoute ? "overflow-hidden" : "overflow-visible"} ${isChatRoute ? "" : "pt-14 md:pt-0"}`}
             >
-              <AnimatePresence initial={false} mode="wait">
+              {/* Use mode="popLayout" instead of "wait" to prevent UI freezes when
+                  switching from heavy pages (like Export with many checkpoints).
+                  "popLayout" allows the new route to mount immediately while the
+                  old one animates out, avoiding blocking on expensive exit renders.
+                  See issue #5850. */}
+              <AnimatePresence initial={false} mode="popLayout">
                 <motion.div
                   key={pathname}
                   initial={{ opacity: 0 }}

From a5d6e6928d4b7bbffb1b8516c07bdeda8a294cb4 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 06:10:17 -0700
Subject: [PATCH 193/222] Studio: surface the llama.cpp update affordance when
 MTP is disabled (#6192)

* Studio: surface the llama.cpp update affordance when MTP is disabled

When a model asks for MTP (auto on an MTP model, or forced mtp / mtp+ngram)
but it gets disabled, the load already degrades gracefully and serves without
speculative decoding. Until now the UI gave no hint why, or that an update
would fix it.

Record why MTP was dropped on the backend (spec_fallback_reason): the probe
found no mtp token (binary_no_mtp), the spawn aborted with an outdated-arch /
context-build error such as a prebuilt that predates the Gemma drafter
(binary_outdated), or the current build could not run it, e.g. a CUDA kernel
limit (runtime_error). Expose it in the inference status. In the chat
Speculative Decoding section, show a short note and, for the two update-fixable
reasons, an inline Update llama.cpp button that reuses the existing update flow.
A runtime_error gets the note without an update push, since a newer build may
not fix it.

Backend tests cover the reason being set / cleared. Frontend typechecks.

* Address review: tighten the update hint to genuinely outdated binaries

Reserve binary_outdated (which surfaces the Update llama.cpp affordance) for an
unknown-architecture abort, which proves the prebuilt predates the model;
classify the generic memory/context build failures as runtime_error, where an
update may not help. Frontend: only append the "Update llama.cpp to enable it"
sentence when an update is actually available, so the text never points at an
action the UI is not offering.
---
 studio/backend/core/inference/llama_cpp.py    | 24 +++++++-
 studio/backend/models/inference.py            | 11 ++++
 studio/backend/routes/inference.py            |  1 +
 .../tests/test_llama_cpp_mtp_detection.py     | 59 +++++++++++++++++++
 .../src/features/chat/chat-settings-sheet.tsx | 50 +++++++++++++++-
 .../chat/hooks/use-chat-model-runtime.ts      |  1 +
 .../chat/stores/chat-runtime-store.ts         |  7 +++
 .../frontend/src/features/chat/types/api.ts   |  6 ++
 8 files changed, 157 insertions(+), 2 deletions(-)

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 7d67097d09..e46d464784 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -676,6 +676,11 @@ class LlamaCppBackend:
         # Separate MTP drafter launched with the current model; reload-dedup
         # key so a drafter that appears next to the weights forces a reload.
         self._mtp_draft_path: Optional[str] = None
+        # Why MTP was disabled on the last load that asked for it (auto on an
+        # MTP model, or forced mtp / mtp+ngram), else None. Drives the "update
+        # llama.cpp" hint in the UI. "binary_no_mtp" / "binary_outdated" ->
+        # a newer prebuilt would help; "runtime_error" -> it may not.
+        self._spec_fallback_reason: Optional[str] = None
         self._hf_variant: Optional[str] = None
         self._is_vision: bool = False
         self._healthy = False
@@ -794,6 +799,11 @@ class LlamaCppBackend:
     def mtp_draft_path(self) -> Optional[str]:
         return self._mtp_draft_path
 
+    @property
+    def spec_fallback_reason(self) -> Optional[str]:
+        """Why MTP was disabled on the last MTP-requesting load, else None."""
+        return self._spec_fallback_reason
+
     @property
     def extra_args(self) -> Optional[List[str]]:
         """Extra llama-server flags from the last load (a copy). None =
@@ -3594,8 +3604,13 @@ class LlamaCppBackend:
                     # failing (unknown arch / draft or context build); an
                     # unrelated crash (e.g. OOM) gets a neutral message.
                     _lo = "\n".join(self._stdout_lines).lower()
+                    # Only an unknown architecture proves the prebuilt predates
+                    # this MTP model (an update fixes it). The memory/context
+                    # build failures are generic (VRAM / ctx pressure), where an
+                    # update may not help, so classify those as runtime_error.
+                    _arch_unsupported = "unknown model architecture" in _lo
                     if (
-                        "unknown model architecture" in _lo
+                        _arch_unsupported
                         or "failed to measure draft model memory" in _lo
                         or "failed to measure mtp context memory" in _lo
                         or "failed to create llama_context" in _lo
@@ -3605,10 +3620,14 @@ class LlamaCppBackend:
                             "speculative decoding -- run `unsloth studio "
                             "update` for MTP"
                         )
+                        self._spec_fallback_reason = (
+                            "binary_outdated" if _arch_unsupported else "runtime_error"
+                        )
                     else:
                         _retry_reason = (
                             "retrying without speculative decoding in case MTP is the cause"
                         )
+                        self._spec_fallback_reason = "runtime_error"
                     _drafter = (
                         Path(launch_mtp_draft_path).name
                         if launch_mtp_draft_path
@@ -3804,6 +3823,7 @@ class LlamaCppBackend:
         # Reset; emit branches re-set on the resolved emission.
         self._spec_draft_n_max = None
         self._speculative_type = None
+        self._spec_fallback_reason = None
 
         # Canonical UI-facing requested mode (legacy values mapped via
         # _canonicalize_spec_mode).
@@ -3853,6 +3873,7 @@ class LlamaCppBackend:
                     "run `unsloth studio update`. Loading without "
                     "speculative decoding."
                 )
+                self._spec_fallback_reason = "binary_no_mtp"
                 return False
             draft_n_max = _resolved_draft_n_max()
             n_max_flag = caps.get("spec_draft_n_max_flag") or "--spec-draft-n-max"
@@ -4118,6 +4139,7 @@ class LlamaCppBackend:
             self._gguf_path = None
             self._hf_repo = None
             self._mtp_draft_path = None
+            self._spec_fallback_reason = None
             self._hf_variant = None
             self._is_vision = False
             self._is_audio = False
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index c83c8ecc1b..f58a76d16e 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -346,6 +346,17 @@ class InferenceStatusResponse(BaseModel):
             "False -> recommend `unsloth studio update`."
         ),
     )
+    spec_fallback_reason: Optional[str] = Field(
+        None,
+        description = (
+            "Why MTP was disabled on the loaded model despite being requested "
+            "(auto on an MTP model, or forced mtp / mtp+ngram). "
+            "'binary_no_mtp' / 'binary_outdated' -> a newer prebuilt would "
+            "re-enable it (show the update affordance); 'runtime_error' -> the "
+            "current build could not run it. None when MTP engaged or was not "
+            "requested."
+        ),
+    )
     llama_cpp_prebuilt_stale: bool = Field(
         False,
         description = (
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index ef67f8bb59..0244956b72 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -1906,6 +1906,7 @@ async def get_status(current_subject: str = Depends(get_current_subject)):
                 speculative_type = llama_backend.requested_spec_mode,
                 spec_draft_n_max = llama_backend.spec_draft_n_max,
                 llama_cpp_supports_mtp = _supports_mtp,
+                spec_fallback_reason = llama_backend.spec_fallback_reason,
                 llama_cpp_prebuilt_stale = _stale,
                 llama_cpp_installed_tag = _installed_tag,
                 llama_cpp_latest_tag = _latest_tag,
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index a7f30d2951..b00cd7169e 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -1399,3 +1399,62 @@ def test_auto_mode_drops_mtp_exempts_separate_drafter():
     assert _auto_mode_drops_mtp("auto", 2.0, has_separate_drafter = True) is False
     assert _auto_mode_drops_mtp("auto", 4.0) is False
     assert _auto_mode_drops_mtp("mtp", 2.0) is False  # forced engages regardless
+
+
+# ── spec_fallback_reason (drives the "update llama.cpp" UI hint) ───────
+
+
+def test_spec_fallback_reason_set_when_binary_lacks_mtp(monkeypatch):
+    # Outdated llama-server with no mtp token: a forced MTP request can't emit
+    # draft-mtp, so record the reason for the UI update affordance.
+    backend = _resolver_backend(monkeypatch, mtp_token = None)
+    backend._build_speculative_flags(
+        speculative_type = "mtp",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    assert backend.spec_fallback_reason == "binary_no_mtp"
+
+
+def test_spec_fallback_reason_none_when_mtp_engages(monkeypatch):
+    backend = _resolver_backend(monkeypatch)
+    backend._build_speculative_flags(
+        speculative_type = "auto",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    assert backend.speculative_type == "draft-mtp"
+    assert backend.spec_fallback_reason is None
+
+
+def test_spec_fallback_reason_reset_on_off(monkeypatch):
+    # A subsequent off load must clear a stale reason.
+    backend = _resolver_backend(monkeypatch, mtp_token = None)
+    backend._build_speculative_flags(
+        speculative_type = "mtp",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    assert backend.spec_fallback_reason == "binary_no_mtp"
+    backend._build_speculative_flags(
+        speculative_type = "off",
+        spec_draft_n_max = None,
+        extra_args = None,
+        model_identifier = _MTP_MODEL,
+        model_path = None,
+        gpus = True,
+        binary = "/fake/llama-server",
+    )
+    assert backend.spec_fallback_reason is None
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 0bd9d8eee6..03c183fe76 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -50,6 +50,7 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { useIsMobile } from "@/hooks/use-mobile";
+import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
 import { cn } from "@/lib/utils";
 import {
   ArrowDown01Icon,
@@ -62,7 +63,7 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { ChevronDown, ExternalLink } from "lucide-react";
 import { Tooltip as TooltipPrimitive } from "radix-ui";
 import { Fragment, type ReactNode } from "react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "@/lib/toast";
 import { OpenAICodeExecSection } from "./components/openai-code-exec-section";
 import {
@@ -487,6 +488,27 @@ export function ChatSettingsPanel({
   const loadedSpeculativeType = useChatRuntimeStore(
     (s) => s.loadedSpeculativeType,
   );
+  const specFallbackReason = useChatRuntimeStore((s) => s.specFallbackReason);
+  // "binary_no_mtp" / "binary_outdated" mean a newer prebuilt would re-enable
+  // MTP; "runtime_error" means the current build cannot run it (no update push).
+  const mtpUpdatable =
+    specFallbackReason === "binary_no_mtp" ||
+    specFallbackReason === "binary_outdated";
+  const {
+    status: llamaUpdateStatus,
+    applying: llamaUpdating,
+    apply: applyLlamaUpdate,
+  } = useLlamaUpdateCheck({ enabled: mtpUpdatable });
+  const handleMtpUpdate = useCallback(async () => {
+    const result = await applyLlamaUpdate();
+    if (result.ok) {
+      toast.success(
+        `llama.cpp updated to ${result.tag ?? "the latest build"}. Reload your model to enable MTP.`,
+      );
+    } else {
+      toast.error(`llama.cpp update failed: ${result.error ?? "unknown error"}`);
+    }
+  }, [applyLlamaUpdate]);
   const specDraftNMax = useChatRuntimeStore((s) => s.specDraftNMax);
   const setSpecDraftNMax = useChatRuntimeStore((s) => s.setSpecDraftNMax);
   const loadedSpecDraftNMax = useChatRuntimeStore(
@@ -923,6 +945,32 @@ export function ChatSettingsPanel({
                     </Select>
                   </div>
                 </div>
+                {specFallbackReason &&
+                  (speculativeType === "auto" ||
+                    speculativeType === "mtp" ||
+                    speculativeType === "mtp+ngram") && (
+                    <div className="rounded-lg bg-amber-500/[0.08] px-3 py-2 text-[12px] leading-[1.4] text-nav-fg/80">
+                      <p>
+                        {specFallbackReason === "runtime_error"
+                          ? "MTP could not start for this model on the installed llama.cpp build, so it is running without speculative decoding."
+                          : "MTP is not available in the installed llama.cpp build, so this model is running without it." +
+                            (llamaUpdateStatus?.update_available
+                              ? " Update llama.cpp to enable it."
+                              : "")}
+                      </p>
+                      {mtpUpdatable && llamaUpdateStatus?.update_available && (
+                        <Button
+                          size="sm"
+                          className="corner-squircle mt-2 h-7 text-[12px]"
+                          onClick={handleMtpUpdate}
+                          disabled={llamaUpdating}
+                          data-test-id="mtp-update-button"
+                        >
+                          {llamaUpdating ? "Updating..." : "Update llama.cpp"}
+                        </Button>
+                      )}
+                    </div>
+                  )}
                 {(speculativeType === "mtp" ||
                   speculativeType === "mtp+ngram") && (
                   <div className="flex items-center justify-between gap-3">
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 66ee2d04e4..4bd36e00d4 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -412,6 +412,7 @@ export function useChatModelRuntime() {
             statusRes.requires_trust_remote_code ?? false,
           defaultChatTemplate: nextDefaultChatTemplate,
           loadedIsMultimodal: isMultimodalResponse(statusRes),
+          specFallbackReason: statusRes.spec_fallback_reason ?? null,
           ...(prevState.loadedSpeculativeType === null && {
             speculativeType: currentSpecType,
             loadedSpeculativeType: currentSpecType,
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index aabf1b29a6..3ef63d2945 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -416,6 +416,11 @@ type ChatRuntimeStore = {
   loadedKvCacheDtype: string | null;
   speculativeType: string | null;
   loadedSpeculativeType: string | null;
+  /**
+   * Why MTP was disabled on the loaded model despite being requested, or null.
+   * Mirrors InferenceStatusResponse.spec_fallback_reason.
+   */
+  specFallbackReason: string | null;
   /** User --spec-draft-n-max override (null = platform default). */
   specDraftNMax: number | null;
   loadedSpecDraftNMax: number | null;
@@ -765,6 +770,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
   loadedKvCacheDtype: null,
   speculativeType: "auto",
   loadedSpeculativeType: null,
+  specFallbackReason: null,
   specDraftNMax: null,
   loadedSpecDraftNMax: null,
   loadedIsMultimodal: false,
@@ -977,6 +983,7 @@ export const useChatRuntimeStore = create<ChatRuntimeStore>((set, get) => ({
       loadedKvCacheDtype: null,
       speculativeType: "auto",
       loadedSpeculativeType: null,
+      specFallbackReason: null,
       specDraftNMax: null,
       loadedSpecDraftNMax: null,
       loadedIsMultimodal: false,
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 49524c17b4..a0e5d5355e 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -174,6 +174,12 @@ export interface InferenceStatusResponse {
   /** Canonical UI-facing mode currently active. See LoadModelRequest. */
   speculative_type?: string | null;
   spec_draft_n_max?: number | null;
+  /**
+   * Why MTP was disabled on the loaded model despite being requested.
+   * "binary_no_mtp" / "binary_outdated" -> updating llama.cpp would re-enable
+   * it; "runtime_error" -> the current build could not run it. Null otherwise.
+   */
+  spec_fallback_reason?: string | null;
 }
 
 export interface AudioGenerationResponse {

From 12a890e0cfc603df27352c7ec9796abecf2e184f Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 06:27:39 -0700
Subject: [PATCH 194/222] Fix bitsandbytes ROCm GPU arch and warp size
 detection on Windows (#6127)

* Fix bitsandbytes ROCm GPU arch and warp size detection on Windows

bitsandbytes resolves the ROCm GPU architecture (and warp size on
0.49.x) by shelling out to rocminfo / hipinfo.exe via PATH at import
time. On Windows neither tool is normally on PATH (AMD torch wheels
ship hipInfo.exe into the venv Scripts dir, only on PATH while
activated), so every `import bitsandbytes` logs an ERROR and WARNING,
ROCM_GPU_ARCH degrades to unknown, and the 0.49.x warp size defaults
to 64, which is wrong on RDNA (wave 32) and silently disables
pre-quantized 4-bit models via ALLOW_PREQUANTIZED_MODELS.

Install a one-shot MetaPathFinder before unsloth_zoo is imported (the
first bitsandbytes import on ROCm) that swaps get_rocm_gpu_arch and
get_rocm_warpsize for torch-device-properties-first implementations
right after bitsandbytes.cuda_specs executes, before cextension reads
them. Falls back to running hipInfo.exe by absolute path (venv
Scripts, conda Scripts, HIP SDK / AMD installer dirs). Repairs the
constants in place when bitsandbytes was imported first. Strict no-op
on non-Windows, non-ROCm builds, missing bitsandbytes, and versions
that fix this upstream. Opt out with UNSLOTH_DISABLE_BNB_ROCM_FIX=1.

Proposed upstream in bitsandbytes-foundation/bitsandbytes#1969;
shipped here so all bitsandbytes versions are covered. Verified on
gfx1151 Strix Halo, Windows 11, torch 2.11.0+rocm7.13.0 against
bitsandbytes main, 0.49.2, and a torch-props-fixed variant.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Tighten comments in the bitsandbytes ROCm detection fix

Comment and docstring pass only. AST comparison with docstrings
stripped confirms every definition is identical to the version the
12 scenario suite ran against, and the suite plus the drift test
pass unchanged on the edited files.

* Keep the bitsandbytes cuda_specs finder installed for reload support

Simulation testing caught a regression in the one-shot design:
importlib.reload(bitsandbytes.cuda_specs) re-resolves the spec through
sys.meta_path, so with the finder already removed the reload reinstalled
the unpatched upstream detector and the Windows ROCm noise returned.
Keep the finder on sys.meta_path permanently, matching the lifecycle of
the existing causal_conv1d and vllm import blockers. The finder matches
a single module name and patching stays idempotent via the sentinel
flags, so repeat hits are no-ops.

Validated on gfx1151 Windows 11: 22 simulation scenarios (conda and
embedded layouts, Program Files scan ordering, paths with spaces and
unicode, hanging probe timeout, lru-wrapped and C-function helper
shapes, reload, failed-import retry, threads, spawn, dormant finder,
Studio PATH coexistence, early fix-block ordering, bnb 0.45.5 / 0.47.0
/ 0.49.2 / main / upstream-fixed) plus the original 12 scenario suite,
CPU-torch and stale-HIP_PATH sandboxes, Python 3.10 to 3.13 gates, and
a WSL Linux leg proving byte-identical Linux behavior with and without
the fix, with and without rocminfo on PATH.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 tests/test_import_fixes_drift.py |  51 +++++
 unsloth/_gpu_init.py             |   4 +
 unsloth/import_fixes.py          | 334 +++++++++++++++++++++++++++++++
 3 files changed, 389 insertions(+)

diff --git a/tests/test_import_fixes_drift.py b/tests/test_import_fixes_drift.py
index 373830ae4a..6c75a4b886 100644
--- a/tests/test_import_fixes_drift.py
+++ b/tests/test_import_fixes_drift.py
@@ -584,3 +584,54 @@ def test_accelerate_utils_imports_module_present():
         "accelerate.utils.imports.is_wandb_available is gone; "
         "disable_broken_wandb cannot patch the source module."
     )
+
+
+# ===========================================================================
+# bitsandbytes -- ROCm arch / warp-size detection shape
+# ===========================================================================
+
+
+def test_bitsandbytes_rocm_detection_helpers_recognizable():
+    """``fix_bitsandbytes_rocm_arch_detection`` swaps bnb's ROCm helpers
+    only when they shell out via subprocess and never consult torch device
+    props; a third shape is declined by design, silently restoring Windows
+    ROCm noise. Fail so the sniff gets updated. Reads source, no import."""
+    spec = importlib.util.find_spec("bitsandbytes")
+    if spec is None:
+        pytest.skip("bitsandbytes not installed -- nothing to drift-check.")
+    cuda_specs_path = None
+    for location in spec.submodule_search_locations or []:
+        candidate = os.path.join(location, "cuda_specs.py")
+        if os.path.isfile(candidate):
+            cuda_specs_path = candidate
+            break
+    if cuda_specs_path is None:
+        pytest.skip("bitsandbytes has no cuda_specs.py (pre-ROCm version).")
+
+    import ast
+
+    with open(cuda_specs_path, "r", encoding = "utf-8") as f:
+        source = f.read()
+    helpers = [
+        node
+        for node in ast.walk(ast.parse(source))
+        if isinstance(node, ast.FunctionDef)
+        and node.name in ("get_rocm_gpu_arch", "get_rocm_warpsize")
+    ]
+    if not helpers:
+        pytest.skip("bitsandbytes cuda_specs has no ROCm detection helpers.")
+    for node in helpers:
+        segment = ast.get_source_segment(source, node) or ""
+        recognized = (
+            "subprocess" in segment
+            or "get_device_properties" in segment
+            or "gcnArchName" in segment
+        )
+        if not recognized:
+            pytest.fail(
+                f"DRIFT DETECTED: bitsandbytes.cuda_specs.{node.name} uses "
+                "neither subprocess nor torch device properties; "
+                "fix_bitsandbytes_rocm_arch_detection's shape sniff will "
+                "decline to patch it and Windows ROCm import-time noise / "
+                "wrong ROCM_GPU_ARCH may return."
+            )
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index ede97ce68e..5da1e27a9d 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -30,6 +30,7 @@ from .import_fixes import (
     disable_broken_causal_conv1d,
     disable_broken_vllm,
     configure_amdgpu_asic_id_table_path,
+    fix_bitsandbytes_rocm_arch_detection,
     torchvision_compatibility_check,
     fix_diffusers_warnings,
     fix_huggingface_hub,
@@ -67,6 +68,8 @@ except Exception:
 
 # Configure libdrm ids table path early so ROCm can resolve AMD GPU names.
 configure_amdgpu_asic_id_table_path()
+# Must precede `import unsloth_zoo` below, which imports bnb on ROCm.
+fix_bitsandbytes_rocm_arch_detection()
 disable_broken_causal_conv1d()
 disable_broken_vllm()
 fix_message_factory_issue()
@@ -75,6 +78,7 @@ torchvision_compatibility_check()
 fix_diffusers_warnings()
 fix_huggingface_hub()
 del configure_amdgpu_asic_id_table_path
+del fix_bitsandbytes_rocm_arch_detection
 del disable_broken_causal_conv1d
 del disable_broken_vllm
 del fix_message_factory_issue
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index 0622f73965..695a6a577a 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -1823,6 +1823,340 @@ def configure_amdgpu_asic_id_table_path():
     return None
 
 
+# ---------------------------------------------------------------------------
+# bitsandbytes Windows ROCm fix: cextension.py runs get_rocm_gpu_arch()
+# (bnb >= 0.47) and get_rocm_warpsize() (0.49.x) at import, shelling out to
+# rocminfo / hipinfo.exe via PATH. Neither is on PATH on Windows (AMD torch
+# wheels put hipInfo.exe in venv Scripts), so every import logs ERROR +
+# WARNING, ROCM_GPU_ARCH becomes "unknown", and warp size defaults to 64:
+# wrong on RDNA (wave 32), breaking 4-bit blocksizes and
+# ALLOW_PREQUANTIZED_MODELS. Upstream fix unmerged (bitsandbytes#1969), so a
+# MetaPathFinder swaps both helpers for torch-device-props-first versions
+# right after bitsandbytes.cuda_specs executes, before cextension reads
+# them. Must run before `import unsloth_zoo` (imports bnb on ROCm).
+# ---------------------------------------------------------------------------
+
+_BNB_CUDA_SPECS_MODULE = "bitsandbytes.cuda_specs"
+_BNB_ROCM_FIX_FINDER_SENTINEL = "_unsloth_bnb_rocm_fix_finder"
+_BNB_ROCM_FIX_FUNCTION_FLAG = "__unsloth_bnb_rocm_fix__"
+
+
+def _torch_rocm_device_props():
+    """Device-0 props on a ROCm torch build with a visible GPU, else None.
+    Never raises; bnb's own import initializes the device context anyway."""
+    try:
+        import torch
+
+        if not getattr(getattr(torch, "version", None), "hip", None):
+            return None
+        if not torch.cuda.is_available():
+            return None
+        return torch.cuda.get_device_properties(0)
+    except Exception:
+        return None
+
+
+def _iter_hipinfo_paths():
+    """Yield existing hipInfo.exe paths: PATH, interpreter scripts dir (venv
+    and conda layouts), then HIP SDK / AMD installer locations."""
+    import shutil
+    import sysconfig
+
+    candidates = []
+    try:
+        resolved = shutil.which("hipinfo.exe")
+        if resolved:
+            candidates.append(resolved)
+    except Exception:
+        pass
+    try:
+        scripts_dir = sysconfig.get_path("scripts")
+        if scripts_dir:
+            candidates.append(os.path.join(scripts_dir, "hipInfo.exe"))
+    except Exception:
+        pass
+    executable_dir = os.path.dirname(sys.executable or "")
+    if executable_dir:
+        candidates.append(os.path.join(executable_dir, "hipInfo.exe"))
+        candidates.append(os.path.join(executable_dir, "Scripts", "hipInfo.exe"))
+    for env_key in ("HIP_PATH", "ROCM_PATH"):
+        root = os.environ.get(env_key, "").strip()
+        if root:
+            candidates.append(os.path.join(root, "bin", "hipInfo.exe"))
+    rocm_root = os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "AMD", "ROCm")
+    try:
+        if os.path.isdir(rocm_root):
+            for version_dir in sorted(os.listdir(rocm_root), reverse = True):
+                candidates.append(os.path.join(rocm_root, version_dir, "bin", "hipInfo.exe"))
+    except Exception:
+        pass
+
+    seen = set()
+    for candidate in candidates:
+        try:
+            key = os.path.normcase(os.path.normpath(candidate))
+            if key in seen:
+                continue
+            seen.add(key)
+            if os.path.isfile(candidate):
+                yield candidate
+        except Exception:
+            continue
+
+
+def _run_hipinfo(hipinfo_path):
+    """Run hipInfo.exe and return its stdout, or "" on any failure."""
+    import subprocess
+    try:
+        result = subprocess.run(
+            [hipinfo_path],
+            capture_output = True,
+            text = True,
+            timeout = 15,
+            creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+        return result.stdout or ""
+    except Exception as e:
+        _log_rocm_detection(f"Unsloth: `{hipinfo_path}` failed: {e}")
+        return ""
+
+
+def _unsloth_get_rocm_gpu_arch():
+    """Replaces bnb's get_rocm_gpu_arch: torch device props first (no
+    subprocess), then hipInfo.exe by absolute path, then a quiet "unknown"."""
+    try:
+        import torch
+        if not getattr(getattr(torch, "version", None), "hip", None):
+            return "unknown"
+    except Exception:
+        return "unknown"
+    props = _torch_rocm_device_props()
+    if props is not None:
+        try:
+            # gcnArchName may carry feature flags, e.g. "gfx90a:sramecc+:xnack-"
+            arch = str(props.gcnArchName).split(":")[0].strip()
+            if arch.startswith("gfx"):
+                return arch
+        except Exception:
+            pass
+    for hipinfo_path in _iter_hipinfo_paths():
+        match = re.search(r"gcnArchName:\s+gfx([a-zA-Z\d]+)", _run_hipinfo(hipinfo_path))
+        if match:
+            return "gfx" + match.group(1)
+    _log_rocm_detection(
+        "Unsloth: Could not detect the ROCm GPU architecture - bitsandbytes will see `unknown`."
+    )
+    return "unknown"
+
+
+def _unsloth_get_rocm_warpsize():
+    """Replaces bnb 0.49.x get_rocm_warpsize: upstream defaults to 64 when
+    rocminfo is missing, wrong on RDNA (wave 32)."""
+    try:
+        import torch
+        if not getattr(getattr(torch, "version", None), "hip", None):
+            return 32  # upstream behavior: NVIDIA warp size is always 32
+    except Exception:
+        return 64  # upstream behavior: default to 64 on failure
+    props = _torch_rocm_device_props()
+    if props is not None:
+        # torch 2.11 ROCm exposes warp_size; some builds used warpSize.
+        for attribute_name in ("warp_size", "warpSize"):
+            warp_size = getattr(props, attribute_name, None)
+            if isinstance(warp_size, int) and warp_size in (32, 64):
+                return warp_size
+    for hipinfo_path in _iter_hipinfo_paths():
+        match = re.search(r"^\s*warpSize:\s+(\d+)", _run_hipinfo(hipinfo_path), re.MULTILINE)
+        if match and int(match.group(1)) in (32, 64):
+            return int(match.group(1))
+    _log_rocm_detection(
+        "Unsloth: Could not detect the ROCm warp size - defaulting to 64 "
+        "(bitsandbytes' own default)."
+    )
+    return 64
+
+
+setattr(_unsloth_get_rocm_gpu_arch, _BNB_ROCM_FIX_FUNCTION_FLAG, True)
+setattr(_unsloth_get_rocm_warpsize, _BNB_ROCM_FIX_FUNCTION_FLAG, True)
+
+
+def _bnb_rocm_helper_is_broken(function):
+    """True only for upstream's subprocess-only detectors; co_names works
+    where getsource fails. Versions consulting torch props are untouched."""
+    if function is None or not callable(function):
+        return False
+    if getattr(function, _BNB_ROCM_FIX_FUNCTION_FLAG, False):
+        return False  # Already ours.
+    try:
+        function = inspect.unwrap(function)
+    except Exception:
+        pass
+    code = getattr(function, "__code__", None)
+    co_names = getattr(code, "co_names", ()) if code is not None else ()
+    if not co_names:
+        return False  # C function or opaque wrapper -- do not touch.
+    if "get_device_properties" in co_names or "gcnArchName" in co_names:
+        return False  # Fixed upstream -- no-op.
+    return "subprocess" in co_names
+
+
+def _patch_bnb_cuda_specs_module(module):
+    """Swap broken ROCm detection helpers on an executed cuda_specs module.
+    Returns True when the module ends up patched (now or previously)."""
+    patched = False
+    for attribute_name, replacement in (
+        ("get_rocm_gpu_arch", _unsloth_get_rocm_gpu_arch),
+        ("get_rocm_warpsize", _unsloth_get_rocm_warpsize),
+    ):
+        original = getattr(module, attribute_name, None)
+        if getattr(original, _BNB_ROCM_FIX_FUNCTION_FLAG, False):
+            patched = True  # Already ours.
+            continue
+        if not _bnb_rocm_helper_is_broken(original):
+            continue
+        setattr(module, attribute_name, replacement)
+        patched = True
+        logger.info(
+            f"Unsloth: Patched bitsandbytes.cuda_specs.{attribute_name} - "
+            f"avoids PATH-dependent subprocess GPU detection on Windows ROCm."
+        )
+    return patched
+
+
+class _BnbCudaSpecsPatchLoader(importlib.abc.Loader):
+    __slots__ = ("_loader",)
+
+    def __init__(self, loader):
+        self._loader = loader
+
+    def create_module(self, spec):
+        create_module = getattr(self._loader, "create_module", None)
+        if create_module is None:
+            return None
+        return create_module(spec)
+
+    def exec_module(self, module):
+        self._loader.exec_module(module)
+        # Patch after the module body ran, before cextension calls it. The
+        # finder stays on sys.meta_path (same lifecycle as the blockers
+        # above) so importlib.reload(bitsandbytes.cuda_specs) re-patches.
+        try:
+            _patch_bnb_cuda_specs_module(module)
+        except Exception as e:
+            _log_rocm_detection(f"Unsloth: bitsandbytes ROCm detection patch failed: {e}")
+
+    def __getattr__(self, name):
+        # Delegate get_source / get_filename etc. so introspection works.
+        return getattr(self._loader, name)
+
+
+class _BnbCudaSpecsPatchFinder(importlib.abc.MetaPathFinder):
+    __slots__ = (_BNB_ROCM_FIX_FINDER_SENTINEL,)
+
+    def __init__(self):
+        setattr(self, _BNB_ROCM_FIX_FINDER_SENTINEL, True)
+
+    def find_spec(
+        self,
+        fullname,
+        path = None,
+        target = None,
+    ):
+        if fullname != _BNB_CUDA_SPECS_MODULE:
+            return None
+        # Delegate to remaining finders (editable installs, frozen apps)
+        # and wrap the loader that would actually be used.
+        spec = None
+        for finder in sys.meta_path:
+            if finder is self or getattr(finder, _BNB_ROCM_FIX_FINDER_SENTINEL, False):
+                continue
+            finder_find_spec = getattr(finder, "find_spec", None)
+            if finder_find_spec is None:
+                continue
+            try:
+                spec = finder_find_spec(fullname, path, target)
+            except Exception:
+                spec = None
+            if spec is not None:
+                break
+        if spec is None or spec.loader is None:
+            return None
+        if not hasattr(spec.loader, "exec_module"):
+            return None  # Legacy loader -- let the stock machinery handle it.
+        spec.loader = _BnbCudaSpecsPatchLoader(spec.loader)
+        return spec
+
+
+def _repair_imported_bitsandbytes_rocm_constants():
+    """bnb imported before unsloth: noise already fired, but fix detectors
+    and cached constants, incl. by-value ROCM_WARP_SIZE_64 copies."""
+    cuda_specs = sys.modules.get(_BNB_CUDA_SPECS_MODULE)
+    if cuda_specs is None:
+        return
+    if not _patch_bnb_cuda_specs_module(cuda_specs):
+        return
+
+    try:
+        arch = cuda_specs.get_rocm_gpu_arch()
+    except Exception:
+        arch = "unknown"
+    warp_size_64 = None
+    get_rocm_warpsize = getattr(cuda_specs, "get_rocm_warpsize", None)
+    if callable(get_rocm_warpsize):
+        try:
+            warp_size_64 = get_rocm_warpsize() == 64
+        except Exception:
+            warp_size_64 = None
+
+    for module_name, module in list(sys.modules.items()):
+        if module is None or module is cuda_specs:
+            continue
+        if module_name != "bitsandbytes" and not module_name.startswith("bitsandbytes."):
+            continue
+        try:
+            if arch != "unknown" and getattr(module, "ROCM_GPU_ARCH", None) == "unknown":
+                module.ROCM_GPU_ARCH = arch
+            if warp_size_64 is not None and isinstance(
+                getattr(module, "ROCM_WARP_SIZE_64", None), bool
+            ):
+                module.ROCM_WARP_SIZE_64 = warp_size_64
+        except Exception:
+            continue
+    logger.info("Unsloth: Repaired bitsandbytes ROCm arch / warp-size constants in place.")
+
+
+def fix_bitsandbytes_rocm_arch_detection():
+    """Fix bnb's import-time ROCm arch / warp-size detection on Windows
+    (see header above). No-op on non-Windows, non-ROCm, missing or
+    upstream-fixed bnb. Idempotent. Opt out: UNSLOTH_DISABLE_BNB_ROCM_FIX=1."""
+    if os.environ.get("UNSLOTH_DISABLE_BNB_ROCM_FIX", "0") == "1":
+        return
+    if sys.platform != "win32":
+        return
+    if not _is_rocm_torch_build():
+        return
+
+    # Already imported: prevention impossible, repair in place instead.
+    if _BNB_CUDA_SPECS_MODULE in sys.modules:
+        try:
+            _repair_imported_bitsandbytes_rocm_constants()
+        except Exception:
+            pass
+        return
+
+    try:
+        if importlib.util.find_spec("bitsandbytes") is None:
+            return
+    except Exception:
+        return
+
+    for finder in sys.meta_path:
+        if getattr(finder, _BNB_ROCM_FIX_FINDER_SENTINEL, False):
+            return  # Already installed -- idempotent.
+    sys.meta_path.insert(0, _BnbCudaSpecsPatchFinder())
+    _log_rocm_detection("Unsloth: Installed the bitsandbytes ROCm arch detection patch hook.")
+
+
 def _is_causal_conv1d_name(module_name: str) -> bool:
     return module_name == _CAUSAL_CONV1D_PREFIX or module_name.startswith(
         _CAUSAL_CONV1D_PREFIX + "."

From 73973435ad66084157efd843b25577dd65b999ae Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 06:52:38 -0700
Subject: [PATCH 195/222] Studio: require an installed ROCm DLL before forcing
 BNB_ROCM_VERSION; drop shadowing shutil imports in save.py (#6194)

* Require a found ROCm DLL before forcing BNB_ROCM_VERSION in Studio paths

main.py previously set BNB_ROCM_VERSION=72 whenever HIP_PATH or ROCM_PATH
was set, and the training worker fell back to a blind 72 when DLL
detection found nothing. On a Windows machine with the AMD HIP SDK
installed but CUDA or CPU torch, that forces a ROCm backend onto a
non-ROCm bitsandbytes wheel, which raises at import. Both paths now only
write the override when a libbitsandbytes_rocm DLL actually exists (or a
seeded value is already present), matching the strict gates in
unsloth/import_fixes.py.

Also removes four redundant local import shutil statements in
unsloth/save.py that shadow the module-level import, the same pattern
that caused the UnboundLocalError fixed in #6149.

* Worker: gate the BNB override on a found ROCm DLL, preserving seeded marker

Review follow-ups: track _found_rocm_bnb in the worker like main.py so a
ROCm DLL with an unparsable name still gets the seeded or 72 fallback,
and skip the env write entirely when no DLL exists so a seeded value
keeps its sitecustomize marker and stays redetectable by later import
fixes.
---
 studio/backend/core/training/worker.py    | 30 ++++++++++++++---------
 studio/backend/main.py                    | 15 ++++++------
 tests/studio/install/test_rocm_support.py | 22 ++++++++++++++---
 unsloth/save.py                           |  4 ---
 4 files changed, 45 insertions(+), 26 deletions(-)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index b50e17e5aa..fb5e9b5137 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -2143,14 +2143,14 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
 
             # BNB picks a rocm DLL from torch.version.hip, but AMD's Windows BNB
             # wheel may ship a DLL whose suffix doesn't match. Detect the actual
-            # DLL name and override; "72" is a safe fallback. Values seeded by
-            # the installer are redetectable defaults, while caller overrides
-            # remain authoritative.
+            # DLL name and override. Values seeded by the installer are
+            # redetectable defaults, while caller overrides remain authoritative.
             if (
                 "BNB_ROCM_VERSION" not in os.environ
                 or os.environ.get("UNSLOTH_BNB_ROCM_VERSION_SOURCE") == "sitecustomize"
             ):
                 _bnb_rocm_ver = None
+                _found_rocm_bnb = False
                 try:
                     import glob as _glob
                     import importlib.util as _ilu
@@ -2163,6 +2163,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                             for _dll in _glob.glob(
                                 os.path.join(_pkg_dir, "libbitsandbytes_rocm*.dll")
                             ):
+                                _found_rocm_bnb = True
                                 _m = _re.search(
                                     r"libbitsandbytes_rocm(\d+)\.dll",
                                     os.path.basename(_dll),
@@ -2174,15 +2175,20 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
                             _bnb_rocm_ver = max(_all_vers, key = lambda v: int(v))
                 except Exception:
                     pass
-                _bnb_rocm_ver = _bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"
-                os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver
-                os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
-                logger.info(
-                    "Windows ROCm: set BNB_ROCM_VERSION=%s "
-                    "(detected from installed BNB wheel; "
-                    "overrides torch.version.hip auto-detection)",
-                    _bnb_rocm_ver,
-                )
+                # Only when a ROCm bnb DLL actually exists (mirrors main.py):
+                # without one the seeded value and its marker stay untouched,
+                # so later import fixes can still redetect or opt out. DLL
+                # with unparsable name -> seeded value or "72".
+                if _found_rocm_bnb:
+                    _bnb_rocm_ver = _bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"
+                    os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver
+                    os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
+                    logger.info(
+                        "Windows ROCm: set BNB_ROCM_VERSION=%s "
+                        "(detected from installed BNB wheel; "
+                        "overrides torch.version.hip auto-detection)",
+                        _bnb_rocm_ver,
+                    )
 
             # Parse HIP version for the kernel-fix gate below, falling back to
             # the rocm version embedded in torch.__version__ when version.hip is
diff --git a/studio/backend/main.py b/studio/backend/main.py
index dc3d802b78..2b34b11fef 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -83,9 +83,9 @@ if sys.platform == "win32":
     # ── Windows AMD ROCm: set BNB_ROCM_VERSION before any bitsandbytes import ─
     # bitsandbytes derives the rocm<ver>.dll name from torch.version.hip, but the
     # wheel ships rocm72.dll, so the server crashes ("Configured ROCm binary not
-    # found") without this. Detect the shipped DLL and fall back to "72" (mirrors
-    # worker.py). Gate on the rocm bnb DLL / HIP_PATH rather than torch.version.hip
-    # to avoid importing torch on every Windows host.
+    # found") without this. Detect the shipped DLL (mirrors worker.py); gate on
+    # the rocm bnb DLL rather than torch.version.hip to avoid importing torch on
+    # every Windows host.
     # Values seeded by the installer's sitecustomize.py are redetectable
     # defaults; explicit caller values remain authoritative.
     if (
@@ -95,7 +95,6 @@ if sys.platform == "win32":
         import glob as _glob
         import logging as _logging
 
-        _hip_env = bool(os.environ.get("HIP_PATH") or os.environ.get("ROCM_PATH"))
         _bnb_rocm_ver = None
         _found_rocm_bnb = False
         try:
@@ -118,11 +117,13 @@ if sys.platform == "win32":
                     _bnb_rocm_ver = max(_all_vers_main, key = lambda v: int(v))
         except Exception as _e:
             _logging.getLogger(__name__).warning(
-                "Windows ROCm: BNB DLL detection failed (%s); falling back to version '72'",
+                "Windows ROCm: BNB DLL detection failed (%s); leaving BNB_ROCM_VERSION as is",
                 _e,
             )
-        # rocm bnb DLL present, or HIP_PATH/ROCM_PATH set (DLL unparsable -> "72")
-        if _found_rocm_bnb or _hip_env:
+        # Only when a ROCm bnb DLL actually exists: HIP_PATH/ROCM_PATH alone
+        # (HIP SDK on a CUDA/CPU box) must not force a ROCm backend onto a
+        # non-ROCm bitsandbytes, which raises at import. DLL unparsable -> "72".
+        if _found_rocm_bnb:
             _bnb_rocm_ver_final = _bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"
             os.environ["BNB_ROCM_VERSION"] = _bnb_rocm_ver_final
             os.environ["UNSLOTH_BNB_ROCM_VERSION_SOURCE"] = "detected"
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 6bc94e3d0f..7d1ae535fd 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -2241,7 +2241,22 @@ class TestRuntimeBnbRocmSourceGuards:
         """A failed redetect must not downgrade a persisted suffix to '72'."""
         for path in (self._MAIN_PATH, self._TRAINING_WORKER_PATH):
             source = path.read_text(encoding = "utf-8")
-            assert 'os.environ.get("BNB_ROCM_VERSION") or "72"' in source, path.name
+            assert (
+                '_bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION") or "72"' in source
+            ), path.name
+
+    def test_main_requires_found_rocm_dll(self):
+        """HIP_PATH/ROCM_PATH alone (HIP SDK on a CUDA/CPU box) must not force
+        a ROCm backend onto a non-ROCm bitsandbytes."""
+        source = self._MAIN_PATH.read_text(encoding = "utf-8")
+        assert "if _found_rocm_bnb:" in source
+        assert "_hip_env" not in source
+
+    def test_worker_requires_found_rocm_dll(self):
+        """No DLL found: the worker must not write any override or touch the
+        seeded marker (later import fixes must still see sitecustomize)."""
+        source = self._TRAINING_WORKER_PATH.read_text(encoding = "utf-8")
+        assert "if _found_rocm_bnb:" in source
 
 
 class TestDetectBnbRocmDllVer:
@@ -2443,8 +2458,9 @@ class TestWorkerWindowsRocmPatches:
         assert "BNB_ROCM_VERSION" in source
         # Detection helper must be used
         assert "_detect_bnb_rocm_dll_ver" in source or "libbitsandbytes_rocm" in source
-        # "72" must appear as the safe fallback
-        assert '"72"' in source or "'72'" in source
+        # Falls back to the seeded value, never a blind "72" (which would
+        # force a ROCm backend onto a non-ROCm bitsandbytes wheel)
+        assert '_bnb_rocm_ver or os.environ.get("BNB_ROCM_VERSION")' in source
 
     def test_bnb_rocm_version_set_before_ml_imports(self):
         """BNB_ROCM_VERSION must appear in section 1f, before section 2 ML imports."""
diff --git a/unsloth/save.py b/unsloth/save.py
index 4ff56cc477..629cbb9548 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -1092,7 +1092,6 @@ def unsloth_save_model(
     gc.collect()
 
     # Remove temporary location
-    import shutil
 
     shutil.rmtree(temporary_location, ignore_errors = True)
 
@@ -1224,7 +1223,6 @@ def install_llama_cpp_old(version = -10):
         for i in range(30):
             print(f"**[WARNING]** Deleting llama.cpp directory... {30-i} seconds left.")
             time.sleep(1)
-        import shutil
 
         shutil.rmtree("llama.cpp", ignore_errors = True)
 
@@ -2494,7 +2492,6 @@ def unsloth_push_to_hub_gguf(
 
     except Exception as e:
         if cleanup_temp:
-            import shutil
             for d in [save_directory, f"{save_directory}_gguf"]:
                 try:
                     shutil.rmtree(d)
@@ -2681,7 +2678,6 @@ This model was finetuned and converted to GGUF format using [Unsloth](https://gi
         # Clean up temporary directory
         if cleanup_temp:
             print("Unsloth: Cleaning up temporary files...")
-            import shutil
             for d in [save_directory, f"{save_directory}_gguf"]:
                 if os.path.exists(d):
                     try:

From 2e29363ad9fc943b2322765609dd3b66d55a25e1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 06:57:48 -0700
Subject: [PATCH 196/222] Studio CI: stop HF 429 rate limits from sinking the
 llama.cpp prebuilt path (#6199)

* Stop HF 429 rate limits from sinking the llama.cpp prebuilt path in Studio CI

The Windows Studio API smoke job failed when anonymous huggingface.co
fetches of the tiny GGUF validation model (stories260K.gguf) hit HTTP 429
on the shared runner IP. The installer correctly refused the unvalidated
prebuilt and fell back to a source build, which the prebuilt assert then
flags. Three layers fix this:

1. Installer: auth_headers sends HF_TOKEN (or HUGGING_FACE_HUB_TOKEN) to
   huggingface.co hosts, mirroring the existing GH_TOKEN handling for the
   GitHub API rate limit. A redirect handler strips Authorization when a
   download is redirected off-host (CDN signed URLs reject foreign auth;
   urllib forwards headers on redirect, unlike requests/huggingface_hub).

2. Workflows: the HF_HOME prime steps also prefetch the validation model
   so the install's hf_hub_download resolves from the local cache even
   when the Hub is rate limiting; cache keys bumped v1 to v2 to repopulate.
   This also covers fork PRs, which cannot see secrets.

3. Workflows: every Install Studio / update step that already passes
   GH_TOKEN now also passes HF_TOKEN, so both the huggingface_hub path and
   the direct URL fallback are authenticated.

Tests: tests/studio/install/test_hf_auth.py covers token-to-host routing,
the cross-host redirect strip, and the download_bytes wiring (offline).
Verified live: authenticated download of the validation model through the
new opener (CDN redirect exercised, pinned sha matches) and an offline
hf_hub_download cache hit against an HF_HOME primed by the new step.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .github/workflows/studio-api-smoke.yml        |   6 +-
 .github/workflows/studio-inference-smoke.yml  |  13 +-
 .github/workflows/studio-mac-api-smoke.yml    |   6 +-
 .../workflows/studio-mac-inference-smoke.yml  |   8 +-
 .../workflows/studio-mac-install-matrix.yml   |   1 +
 .github/workflows/studio-mac-ui-smoke.yml     |   6 +-
 .github/workflows/studio-mac-update-smoke.yml |   3 +
 .github/workflows/studio-ui-smoke.yml         |   6 +-
 .github/workflows/studio-update-smoke.yml     |   3 +
 .../workflows/studio-windows-api-smoke.yml    |   6 +-
 .../studio-windows-inference-smoke.yml        |  13 +-
 .github/workflows/studio-windows-ui-smoke.yml |   6 +-
 .../workflows/studio-windows-update-smoke.yml |   3 +
 studio/install_llama_prebuilt.py              |  35 +++++-
 tests/studio/install/test_hf_auth.py          | 114 ++++++++++++++++++
 15 files changed, 205 insertions(+), 24 deletions(-)
 create mode 100644 tests/studio/install/test_hf_auth.py

diff --git a/.github/workflows/studio-api-smoke.yml b/.github/workflows/studio-api-smoke.yml
index 53514e2ce1..b196805cf7 100644
--- a/.github/workflows/studio-api-smoke.yml
+++ b/.github/workflows/studio-api-smoke.yml
@@ -77,7 +77,7 @@ jobs:
           path: hf-cache
           # Same key as studio-ui-smoke.yml so the two jobs share a
           # single GGUF download across CI.
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -88,17 +88,19 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.yml
index 133dd601d1..cffb33f71d 100644
--- a/.github/workflows/studio-inference-smoke.yml
+++ b/.github/workflows/studio-inference-smoke.yml
@@ -91,7 +91,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -102,17 +102,19 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -375,6 +377,7 @@ jobs:
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -829,7 +832,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v2
 
       - name: Prime HF_HOME with the GGUF + mmproj
         id: prime-hf
@@ -841,17 +844,19 @@ jobs:
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$MMPROJ_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }} (model + mmproj)
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-mac-api-smoke.yml b/.github/workflows/studio-mac-api-smoke.yml
index 8839b559fd..412726538c 100644
--- a/.github/workflows/studio-mac-api-smoke.yml
+++ b/.github/workflows/studio-mac-api-smoke.yml
@@ -62,7 +62,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -73,17 +73,19 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-mac-inference-smoke.yml b/.github/workflows/studio-mac-inference-smoke.yml
index e08ac6ca68..c794a34acd 100644
--- a/.github/workflows/studio-mac-inference-smoke.yml
+++ b/.github/workflows/studio-mac-inference-smoke.yml
@@ -85,7 +85,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -96,6 +96,7 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       # Save partial caches on cancel/timeout -- hf download resumes by
       # content hash. `outcome != skipped` keeps cache-hit a no-op.
@@ -104,11 +105,12 @@ jobs:
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -361,6 +363,7 @@ jobs:
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -749,6 +752,7 @@ jobs:
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-mac-install-matrix.yml b/.github/workflows/studio-mac-install-matrix.yml
index 4e2722d1cd..da944d4b5c 100644
--- a/.github/workflows/studio-mac-install-matrix.yml
+++ b/.github/workflows/studio-mac-install-matrix.yml
@@ -63,6 +63,7 @@ jobs:
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-mac-ui-smoke.yml b/.github/workflows/studio-mac-ui-smoke.yml
index 0176b0a168..4f9f94b534 100644
--- a/.github/workflows/studio-mac-ui-smoke.yml
+++ b/.github/workflows/studio-mac-ui-smoke.yml
@@ -62,7 +62,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -73,17 +73,19 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-mac-update-smoke.yml b/.github/workflows/studio-mac-update-smoke.yml
index 1eca227096..f554a16415 100644
--- a/.github/workflows/studio-mac-update-smoke.yml
+++ b/.github/workflows/studio-mac-update-smoke.yml
@@ -62,6 +62,7 @@ jobs:
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -73,6 +74,7 @@ jobs:
       - name: First update should be a no-op (prebuilt already validated)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update.log
@@ -91,6 +93,7 @@ jobs:
       - name: Second update must also be a no-op
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update2.log
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.yml
index 455fe4b7e1..de106e201f 100644
--- a/.github/workflows/studio-ui-smoke.yml
+++ b/.github/workflows/studio-ui-smoke.yml
@@ -76,7 +76,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -87,17 +87,19 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Install Studio (--local, --no-torch)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
diff --git a/.github/workflows/studio-update-smoke.yml b/.github/workflows/studio-update-smoke.yml
index 057aeacbd4..307bb51972 100644
--- a/.github/workflows/studio-update-smoke.yml
+++ b/.github/workflows/studio-update-smoke.yml
@@ -71,6 +71,7 @@ jobs:
         # prebuilt path falls back to source build.
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           mkdir -p logs
           set -o pipefail
@@ -85,6 +86,7 @@ jobs:
         # idempotency regressed.
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update.log
@@ -107,6 +109,7 @@ jobs:
         # the first one.
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update2.log
diff --git a/.github/workflows/studio-windows-api-smoke.yml b/.github/workflows/studio-windows-api-smoke.yml
index eee61516c7..78efe918ac 100644
--- a/.github/workflows/studio-windows-api-smoke.yml
+++ b/.github/workflows/studio-windows-api-smoke.yml
@@ -69,7 +69,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -80,13 +80,14 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
         shell: pwsh
@@ -123,6 +124,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 captures Write-Host (Information stream) output;
diff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.yml
index 6148856016..a772a6d102 100644
--- a/.github/workflows/studio-windows-inference-smoke.yml
+++ b/.github/workflows/studio-windows-inference-smoke.yml
@@ -101,7 +101,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -114,6 +114,7 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME cache for ${{ env.GGUF_REPO }}
         # Only write a fresh cache entry when we actually rebuilt the
@@ -123,7 +124,7 @@ jobs:
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
         shell: pwsh
@@ -160,6 +161,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 captures Write-Host (Information stream) output;
@@ -504,6 +506,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 captures Write-Host (Information stream) output;
@@ -879,7 +882,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v2
 
       - name: Prime HF_HOME with the GGUF + mmproj
         id: prime-hf
@@ -891,13 +894,14 @@ jobs:
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$MMPROJ_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME cache for ${{ env.GGUF_REPO }} (model + mmproj)
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-${{ env.MMPROJ_FILE }}-v2
 
       - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
         shell: pwsh
@@ -934,6 +938,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 captures Write-Host (Information stream) output;
diff --git a/.github/workflows/studio-windows-ui-smoke.yml b/.github/workflows/studio-windows-ui-smoke.yml
index e3c8642122..40d8e530cd 100644
--- a/.github/workflows/studio-windows-ui-smoke.yml
+++ b/.github/workflows/studio-windows-ui-smoke.yml
@@ -85,7 +85,7 @@ jobs:
         continue-on-error: true
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Prime HF_HOME with the GGUF
         id: prime-hf
@@ -96,13 +96,14 @@ jobs:
           python -m pip install --upgrade huggingface_hub
           mkdir -p hf-cache
           bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
+          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
 
       - name: Save HF_HOME for ${{ env.GGUF_REPO }}
         if: always() && steps.prime-hf.outcome == 'success'
         uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
         with:
           path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v1
+          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
 
       - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
         shell: pwsh
@@ -143,6 +144,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 redirects ALL PowerShell streams (stdout, stderr,
diff --git a/.github/workflows/studio-windows-update-smoke.yml b/.github/workflows/studio-windows-update-smoke.yml
index aa3e35f052..4a4806cfb1 100644
--- a/.github/workflows/studio-windows-update-smoke.yml
+++ b/.github/workflows/studio-windows-update-smoke.yml
@@ -133,6 +133,7 @@ jobs:
         shell: pwsh
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           New-Item -ItemType Directory -Force -Path logs | Out-Null
           # *>&1 captures Write-Host (Information stream) output;
@@ -179,6 +180,7 @@ jobs:
       - name: First update should be a no-op (prebuilt already validated)
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update.log
@@ -197,6 +199,7 @@ jobs:
       - name: Second update must also be a no-op
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
         run: |
           set -o pipefail
           unsloth studio update --local 2>&1 | tee logs/update2.log
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 64ea255803..2b42a7a058 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -177,6 +177,7 @@ VALIDATION_MODEL_CACHE_FILENAME = "stories260K.gguf"
 INSTALL_LOCK_TIMEOUT_SECONDS = 300
 INSTALL_STAGING_ROOT_NAME = ".staging"
 GITHUB_AUTH_HOSTS = {"api.github.com", "github.com"}
+HF_AUTH_HOSTS = {"huggingface.co", "www.huggingface.co"}
 RETRYABLE_HTTP_STATUS = {408, 429, 500, 502, 503, 504}
 HTTP_FETCH_ATTEMPTS = 4
 HTTP_FETCH_BASE_DELAY_SECONDS = 0.75
@@ -484,6 +485,10 @@ def should_send_github_auth(url: str | None) -> bool:
     return parsed_hostname(url) in GITHUB_AUTH_HOSTS
 
 
+def should_send_hf_auth(url: str | None) -> bool:
+    return parsed_hostname(url) in HF_AUTH_HOSTS
+
+
 def auth_headers(url: str | None = None) -> dict[str, str]:
     headers = {
         "User-Agent": "unsloth-studio-llama-prebuilt",
@@ -491,9 +496,35 @@ def auth_headers(url: str | None = None) -> dict[str, str]:
     token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
     if token and should_send_github_auth(url):
         headers["Authorization"] = f"Bearer {token}"
+        return headers
+    # Anonymous huggingface.co fetches share a per-IP rate limit that CI
+    # fleets exhaust (HTTP 429), sinking the prebuilt path into a source
+    # build. Authenticate when a token is available.
+    hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if hf_token and should_send_hf_auth(url):
+        headers["Authorization"] = f"Bearer {hf_token}"
     return headers
 
 
+class _CrossHostAuthStrippingRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Drop Authorization when a redirect leaves the original host.
+
+    huggingface.co redirects file downloads to CDN hosts whose signed URLs
+    can reject foreign Authorization headers; urllib forwards headers to
+    redirect targets by default (requests/huggingface_hub strip them).
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new_request = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_request is not None and parsed_hostname(newurl) != parsed_hostname(req.full_url):
+            new_request.headers.pop("Authorization", None)
+            new_request.unredirected_hdrs.pop("Authorization", None)
+        return new_request
+
+
+_URL_OPENER = urllib.request.build_opener(_CrossHostAuthStrippingRedirectHandler())
+
+
 def github_api_headers(url: str | None = None) -> dict[str, str]:
     return {
         "Accept": "application/vnd.github+json",
@@ -936,7 +967,7 @@ def download_bytes(
     for attempt in range(1, attempts + 1):
         try:
             request = urllib.request.Request(url, headers = headers or auth_headers(url))
-            with urllib.request.urlopen(request, timeout = timeout) as response:
+            with _URL_OPENER.open(request, timeout = timeout) as response:
                 total_bytes: int | None = None
                 content_length = response.headers.get("Content-Length")
                 if content_length and content_length.isdigit():
@@ -1015,7 +1046,7 @@ def download_file(url: str, destination: Path) -> None:
                 delete = False,
             ) as handle:
                 tmp_path = Path(handle.name)
-                with urllib.request.urlopen(request, timeout = 120) as response:
+                with _URL_OPENER.open(request, timeout = 120) as response:
                     total_bytes: int | None = None
                     content_length = response.headers.get("Content-Length")
                     if content_length and content_length.isdigit():
diff --git a/tests/studio/install/test_hf_auth.py b/tests/studio/install/test_hf_auth.py
new file mode 100644
index 0000000000..7c3296d4fd
--- /dev/null
+++ b/tests/studio/install/test_hf_auth.py
@@ -0,0 +1,114 @@
+"""Tests for Hugging Face auth on the llama.cpp prebuilt installer's fetches.
+
+Anonymous huggingface.co downloads (tiny GGUF validation model) share a
+per-IP rate limit that CI fleets exhaust (HTTP 429), forcing the prebuilt
+path into a source build. auth_headers now sends HF_TOKEN to huggingface.co
+hosts, and a redirect handler strips Authorization when the download is
+redirected to a different host (CDN signed URLs). All tests are offline.
+"""
+
+import importlib.util
+import sys
+import urllib.request
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+
+_MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+_SPEC = importlib.util.spec_from_file_location(
+    "studio_install_llama_prebuilt_hf_auth", _MODULE_PATH
+)
+assert _SPEC is not None and _SPEC.loader is not None
+mod = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = mod
+_SPEC.loader.exec_module(mod)
+
+_TOKEN_VARS = ("GH_TOKEN", "GITHUB_TOKEN", "HF_TOKEN", "HUGGING_FACE_HUB_TOKEN")
+HF_URL = "https://huggingface.co/ggml-org/models/resolve/main/tinyllamas/stories260K.gguf"
+GH_URL = "https://api.github.com/repos/unslothai/llama.cpp/releases"
+
+
+def _headers(url, env):
+    """auth_headers under a fully controlled token environment."""
+    with patch.dict(mod.os.environ, env, clear = False):
+        for var in _TOKEN_VARS:
+            if var not in env:
+                mod.os.environ.pop(var, None)
+        return mod.auth_headers(url)
+
+
+class TestAuthHeaderRouting:
+    def test_hf_token_sent_to_huggingface(self):
+        headers = _headers(HF_URL, {"HF_TOKEN": "hf_x"})
+        assert headers.get("Authorization") == "Bearer hf_x"
+
+    def test_hub_token_fallback(self):
+        headers = _headers(HF_URL, {"HUGGING_FACE_HUB_TOKEN": "hf_y"})
+        assert headers.get("Authorization") == "Bearer hf_y"
+
+    def test_hf_token_not_sent_to_github(self):
+        headers = _headers(GH_URL, {"HF_TOKEN": "hf_x"})
+        assert "Authorization" not in headers
+
+    def test_hf_token_not_sent_to_other_hosts(self):
+        headers = _headers("https://cdn-lfs.huggingface.co/x", {"HF_TOKEN": "hf_x"})
+        assert "Authorization" not in headers
+
+    def test_gh_token_not_sent_to_huggingface(self):
+        headers = _headers(HF_URL, {"GH_TOKEN": "gh_x"})
+        assert "Authorization" not in headers
+
+    def test_gh_token_still_wins_on_github(self):
+        headers = _headers(GH_URL, {"GH_TOKEN": "gh_x", "HF_TOKEN": "hf_x"})
+        assert headers.get("Authorization") == "Bearer gh_x"
+
+    def test_no_tokens_no_auth(self):
+        assert "Authorization" not in _headers(HF_URL, {})
+
+    def test_validation_model_url_is_hf(self):
+        assert mod.should_send_hf_auth(mod.TEST_MODEL_URL) is True
+
+
+class TestCrossHostRedirectStripsAuth:
+    def _redirect(self, newurl):
+        req = urllib.request.Request(HF_URL, headers = {"Authorization": "Bearer hf_x"})
+        handler = mod._CrossHostAuthStrippingRedirectHandler()
+        return handler.redirect_request(req, None, 302, "Found", {}, newurl)
+
+    def test_cross_host_redirect_drops_authorization(self):
+        new_request = self._redirect("https://cdn-lfs.huggingface.co/signed/blob")
+        assert new_request is not None
+        assert "Authorization" not in new_request.headers
+        assert "Authorization" not in new_request.unredirected_hdrs
+
+    def test_same_host_redirect_keeps_authorization(self):
+        new_request = self._redirect("https://huggingface.co/elsewhere/blob")
+        assert new_request is not None
+        assert new_request.headers.get("Authorization") == "Bearer hf_x"
+
+
+class TestDownloadBytesWiring:
+    def test_download_bytes_sends_hf_auth(self):
+        response = MagicMock()
+        response.__enter__ = lambda s: s
+        response.__exit__ = lambda s, *a: False
+        response.headers.get.return_value = None
+        response.read.side_effect = [b"data", b""]
+        with (
+            patch.object(mod._URL_OPENER, "open", return_value = response) as opened,
+            patch.dict(mod.os.environ, {"HF_TOKEN": "hf_x"}, clear = False),
+        ):
+            for var in ("GH_TOKEN", "GITHUB_TOKEN"):
+                mod.os.environ.pop(var, None)
+            data = mod.download_bytes(HF_URL)
+        assert data == b"data"
+        request = opened.call_args.args[0]
+        assert request.headers.get("Authorization") == "Bearer hf_x"
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))

From de8d9b0691ec5ea776292ad2132060ae5ec41f18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E0=A4=B9=E0=A4=BF=E0=A4=AE=E0=A4=BE=E0=A4=82=E0=A4=B6?=
 =?UTF-8?q?=E0=A5=81?= <sharmahimanshu15082007@gmail.com>
Date: Thu, 11 Jun 2026 19:33:47 +0530
Subject: [PATCH 197/222] center the search dialog and change the wrong borders
 (#6184)

* center the search dialog and change the wrong borders

* fix the  mistake of 1 to l

* Fix/adjust search dialog radius for PR #6184

---------

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: wasimysaid <wasimysdev@gmail.com>
---
 .../src/features/chat/components/chat-search-dialog.tsx       | 4 ++--
 studio/frontend/src/index.css                                 | 3 +--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
index 0a6ec0c884..b0fd3c5f27 100644
--- a/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
+++ b/studio/frontend/src/features/chat/components/chat-search-dialog.tsx
@@ -64,10 +64,10 @@ export function ChatSearchDialog() {
     <CommandDialog
       open={isOpen}
       onOpenChange={setOpen}
-      className="chat-search-surface corner-squircle top-[25%] w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 ring-0 sm:max-w-[635px]"
+      className="chat-search-surface rounded-3xl! top-1/2 -translate-y-1/2 w-[635px] max-w-[calc(100%-2rem)] gap-0 p-0 ring-0 sm:max-w-[635px]"
       overlayClassName="bg-transparent"
     >
-      <Command className="rounded-4xl p-0" filter={chatSearchFilter}>
+      <Command className="rounded-3xl p-0" filter={chatSearchFilter}>
         <div className="flex items-center gap-3 border-b border-border/40 px-4 py-3">
           <HugeiconsIcon
             icon={SearchIcon}
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index cb54d95e68..0d3b1698e1 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -897,8 +897,7 @@
 	/* Chat search box: borderless, soft Gemini-style elevation. */
 	.chat-search-surface {
 		border: none;
-		/* Pin to the dark --radius so the corners are the same (less round) in
-		   both themes; rounded-4xl here and on the inner Command follow this. */
+		/* Pin to the dark --radius so rounded-3xl corners stay consistent. */
 		--radius: 0.625rem;
 		/* Match the chat box: soft elevation. */
 		box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16);

From 582fb0a0ceb104112545ba34725482733d3d7b25 Mon Sep 17 00:00:00 2001
From: Etherll <61019402+Etherll@users.noreply.github.com>
Date: Thu, 11 Jun 2026 17:07:26 +0300
Subject: [PATCH 198/222] fix(studio): reuse venv Python in setup instead of
 re-probing system (#6033)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(studio): reuse venv Python in setup instead of re-probing system

* Reuse venv Python for studio setup

Pass the venv interpreter from install.ps1 to studio/setup.ps1 via UNSLOTH_SETUP_PYTHON and prefer it over probing the system. Added Resolve-ReusedSetupPython to accept the handed-off path (or derive the venv python when setup runs standalone), validate it (Python 3.11–3.13 and non-conda), and inject its Scripts dir onto PATH. When a reused interpreter is accepted, py.exe enumeration and further system probing are skipped. install.ps1 also sets the env var before running setup and removes it on cleanup to avoid leaving state behind. This prevents setup from being tripped by unsupported Python 3.14 or Windows Store stubs on PATH.

* Harden setup Python detection for PR #6033: py -All, shared conda check, bare ~ guard

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 install.ps1      |  17 +++++--
 studio/setup.ps1 | 121 ++++++++++++++++++++++++++++++-----------------
 2 files changed, 90 insertions(+), 48 deletions(-)

diff --git a/install.ps1 b/install.ps1
index 2938d4334f..fd7d3f4a81 100644
--- a/install.ps1
+++ b/install.ps1
@@ -983,10 +983,13 @@ shell.Run cmd, 0, False
     function Find-CompatiblePython {
         # Try the Python Launcher first (most reliable on Windows)
         # py.exe resolves to the standard CPython install, not conda.
-        $pyLauncher = Get-Command py -CommandType Application -ErrorAction SilentlyContinue
-        if ($pyLauncher -and $pyLauncher.Source -notmatch $script:CondaSkipPattern) {
-            # Prefer the requested $PythonVersion, then newest-first fallback.
-            $minors = @($PythonVersion) + (@("3.13", "3.12", "3.11") | Where-Object { $_ -ne $PythonVersion })
+        # Prefer the requested $PythonVersion, then newest-first fallback.
+        $minors = @($PythonVersion) + (@("3.13", "3.12", "3.11") | Where-Object { $_ -ne $PythonVersion })
+        # Enumerate every py.exe on PATH with -All (Windows PowerShell 5.1
+        # returns only the first launcher without it) and search each for a
+        # supported, non-conda interpreter.
+        foreach ($pyLauncher in @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue)) {
+            if ($pyLauncher.Source -match $script:CondaSkipPattern) { continue }
             foreach ($minor in $minors) {
                 try {
                     $out = & $pyLauncher.Source "-$minor" --version 2>&1 | Out-String
@@ -2089,6 +2092,11 @@ shell.Run cmd, 0, False
     $studioArgs = @('studio', 'setup')
     if ($script:UnslothVerbose) { $studioArgs += '--verbose' }
     $env:UNSLOTH_INSTALL_ROLLBACK_MANAGED = "1"
+    # Hand the venv interpreter to setup.ps1 so it reuses the Python we already
+    # resolved and built the venv with, instead of re-probing the system (which
+    # can trip over an unsupported `python` 3.14 or a Store stub on PATH even
+    # though the venv is fine). setup.ps1 Test-Path-guards this before use.
+    $env:UNSLOTH_SETUP_PYTHON = Join-Path $VenvDir "Scripts\python.exe"
     try {
         & $UnslothExe @studioArgs
         $setupExit = $LASTEXITCODE
@@ -2099,6 +2107,7 @@ shell.Run cmd, 0, False
             Remove-Item Env:UNSLOTH_STUDIO_HOME -ErrorAction SilentlyContinue
         }
         Remove-Item Env:UNSLOTH_INSTALL_ROLLBACK_MANAGED -ErrorAction SilentlyContinue
+        Remove-Item Env:UNSLOTH_SETUP_PYTHON -ErrorAction SilentlyContinue
     }
     if ($setupExit -ne 0) {
         Write-Host "[ERROR] unsloth studio setup failed (exit code $setupExit)" -ForegroundColor Red
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 29350e3932..94817b561a 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -1552,10 +1552,48 @@ if ($IsPipInstall) {
     }
 }
 
-# 1g. Python (>= 3.11 and < 3.14). Prefer the Studio venv that install.ps1
-# just created, then py.exe so a 3.14 ahead of 3.13 on PATH does not trip the gate.
+# Conda CPython ships modified DLL search paths that break torch's c10.dll
+# loading on Windows; a venv made from conda Python inherits its base_prefix,
+# so check the executable path AND sys.base_prefix.
+$CondaSkipPattern = '(?i)(conda|miniconda|anaconda|miniforge|mambaforge)'
+function Test-IsConda {
+    param([string]$Exe)
+    if ($Exe -match $CondaSkipPattern) { return $true }
+    try {
+        $basePrefix = (& $Exe -c "import sys; print(sys.base_prefix)" 2>$null | Out-String).Trim()
+        if ($basePrefix -match $CondaSkipPattern) { return $true }
+    } catch { }
+    return $false
+}
+
+# 1g. Python (>= 3.11 and < 3.14). Prefer the interpreter install.ps1 already
+# resolved and built the venv with (UNSLOTH_SETUP_PYTHON), or the existing
+# venv python, before re-probing a system where a 3.14 or a WindowsApps stub
+# ahead on PATH would trip the gate. setup.ps1 only updates packages in that
+# venv, so the handoff is safe to reuse once validated.
+function Resolve-ReusedSetupPython {
+    if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_SETUP_PYTHON) -and
+        (Test-Path -LiteralPath $env:UNSLOTH_SETUP_PYTHON)) {
+        return $env:UNSLOTH_SETUP_PYTHON
+    }
+    # Standalone `unsloth studio setup/update` (install.ps1 did not run): derive
+    # the venv python from the studio root, mirroring the resolver below.
+    $root = if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) { $env:UNSLOTH_STUDIO_HOME.Trim() }
+            elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) { $env:STUDIO_HOME.Trim() }
+            else { Join-Path $env:USERPROFILE ".unsloth\studio" }
+    if ($root -eq "~") {
+        # Join-Path with an empty child throws on Windows PowerShell 5.1.
+        $root = $env:USERPROFILE
+    } elseif ($root -like "~/*" -or $root -like "~\*") {
+        $root = Join-Path $env:USERPROFILE $root.Substring(1).TrimStart('/', '\')
+    }
+    $venvPy = Join-Path $root "unsloth_studio\Scripts\python.exe"
+    if (Test-Path -LiteralPath $venvPy) { return $venvPy }
+    return $null
+}
+$ReusedSetupPython = Resolve-ReusedSetupPython
+
 $HasPython = $null -ne (Get-Command python -ErrorAction SilentlyContinue)
-$PyLauncher = Get-Command py -CommandType Application -ErrorAction SilentlyContinue
 $PythonOk = $false
 $DetectedPyVer = $null
 
@@ -1584,28 +1622,24 @@ function Add-PythonDirToProcessPath {
     } catch { }
 }
 
-$_prereqStudioHome = $null
-if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) {
-    $_prereqStudioHome = $env:UNSLOTH_STUDIO_HOME.Trim()
-} elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) {
-    $_prereqStudioHome = $env:STUDIO_HOME.Trim()
-} else {
-    $_prereqStudioHome = Join-Path $env:USERPROFILE ".unsloth\studio"
-}
-if ($_prereqStudioHome -eq "~" -or $_prereqStudioHome -like "~/*" -or $_prereqStudioHome -like "~\*") {
-    $_prereqStudioHome = (Join-Path $env:USERPROFILE $_prereqStudioHome.Substring(1).TrimStart('/','\'))
-}
-$_prereqVenvPython = Join-Path $_prereqStudioHome "unsloth_studio\Scripts\python.exe"
-if (Test-Path -LiteralPath $_prereqVenvPython) {
-    $_venvPyVer = Get-CompatiblePythonVersion $_prereqVenvPython
-    if ($_venvPyVer) {
-        $DetectedPyVer = $_venvPyVer
-        Add-PythonDirToProcessPath $_prereqVenvPython
+# Reuse the install.ps1 / venv interpreter before any system probe.
+if ($ReusedSetupPython) {
+    $_reusedVer = Get-CompatiblePythonVersion $ReusedSetupPython
+    if ($_reusedVer -and -not (Test-IsConda $ReusedSetupPython)) {
+        $DetectedPyVer = $_reusedVer
+        Add-PythonDirToProcessPath $ReusedSetupPython
         $PythonOk = $true
     }
 }
 
-if (-not $PythonOk -and $PyLauncher) {
+# Fall back to every py.exe on PATH (all-users and per-user launchers can both
+# register). -All is required: Windows PowerShell 5.1 returns only the first
+# launcher without it, and the PowerShell 7 multi-match array breaks the call
+# operator if used directly.
+$PyLaunchers = if ($PythonOk) { @() } else { @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue) }
+
+foreach ($PyLauncher in $PyLaunchers) {
+    if ($PyLauncher.Source -match $CondaSkipPattern) { continue }
     foreach ($minor in @("3.13", "3.12", "3.11")) {
         try {
             $out = & $PyLauncher.Source "-$minor" --version 2>&1 | Out-String
@@ -1625,6 +1659,7 @@ if (-not $PythonOk -and $PyLauncher) {
             }
         } catch { }
     }
+    if ($PythonOk) { break }
 }
 
 if (-not $PythonOk -and $HasPython) {
@@ -1857,36 +1892,33 @@ if (Test-Path $OxcValidatorDir) {
 Write-Host ""
 substep "setting up Python environment..."
 
-# Find Python -- skip Anaconda/Miniconda distributions.
-# Conda-bundled CPython ships modified DLL search paths that break
-# torch's c10.dll loading on Windows. Standalone CPython (python.org,
-# winget, uv) does not have this issue.
-# Uses Get-Command -All to look past conda entries that shadow a valid
-# standalone Python further down PATH, and probes py.exe (the Python
-# Launcher) which reliably finds python.org installs.
-#
-# NOTE: A venv created from conda Python inherits conda's base_prefix
-# even though the venv path itself does not contain "conda". We check
-# both the executable path AND sys.base_prefix to catch this case.
-$CondaSkipPattern = '(?i)(conda|miniconda|anaconda|miniforge|mambaforge)'
+# Find Python -- skip Anaconda/Miniconda distributions ($CondaSkipPattern and
+# Test-IsConda are defined above the 1g gate). Standalone CPython (python.org,
+# winget, uv) does not have conda's torch c10.dll loading issue.
 $PythonCmd = $null
 
-# Helper: check if a Python executable is conda-based by inspecting
-# both the path and sys.base_prefix (catches venvs created from conda).
-function Test-IsConda {
-    param([string]$Exe)
-    if ($Exe -match $CondaSkipPattern) { return $true }
+# 0. Reuse the interpreter install.ps1 already resolved and built the venv with
+#    (UNSLOTH_SETUP_PYTHON, or the existing venv python) before probing the
+#    system -- it is already validated as supported and non-conda.
+if ($ReusedSetupPython) {
     try {
-        $basePrefix = (& $Exe -c "import sys; print(sys.base_prefix)" 2>$null | Out-String).Trim()
-        if ($basePrefix -match $CondaSkipPattern) { return $true }
+        $out = & $ReusedSetupPython --version 2>&1 | Out-String
+        if ($out -match 'Python 3\.(\d+)') {
+            $pyMinor = [int]$Matches[1]
+            if ($pyMinor -ge 11 -and $pyMinor -le 13 -and -not (Test-IsConda $ReusedSetupPython)) {
+                $PythonCmd = $ReusedSetupPython
+            }
+        }
     } catch { }
-    return $false
 }
 
 # 1. Try the Python Launcher (py.exe) first -- most reliable on Windows.
-#    py.exe is installed by python.org and resolves to standalone CPython.
-$pyLauncher = Get-Command py -CommandType Application -ErrorAction SilentlyContinue
-if ($pyLauncher -and $pyLauncher.Source -notmatch $CondaSkipPattern) {
+#    Enumerate every launcher with -All (Windows PowerShell 5.1 returns only
+#    the first match without it) and search each for a supported, non-conda
+#    interpreter.
+$PyLaunchersResolve = if ($PythonCmd) { @() } else { @(Get-Command py -All -CommandType Application -ErrorAction SilentlyContinue) }
+foreach ($pyLauncher in $PyLaunchersResolve) {
+    if ($pyLauncher.Source -match $CondaSkipPattern) { continue }
     foreach ($minor in @("3.13", "3.12", "3.11")) {
         try {
             $out = & $pyLauncher.Source "-$minor" --version 2>&1 | Out-String
@@ -1904,6 +1936,7 @@ if ($pyLauncher -and $pyLauncher.Source -notmatch $CondaSkipPattern) {
             }
         } catch { }
     }
+    if ($PythonCmd) { break }
 }
 
 # 2. Fall back to scanning python3.x / python3 / python on PATH.

From 5a5ecc8fc0ed3c0199b0ac39ea57b65d944096fb Mon Sep 17 00:00:00 2001
From: Prathamesh Jadhav <55660103+lollinng@users.noreply.github.com>
Date: Thu, 11 Jun 2026 19:38:34 +0530
Subject: [PATCH 199/222] Strip trailing whitespace in construct_chat_template
 (fixes #992) (#6008)

* Strip trailing whitespace in construct_chat_template (fixes #992)

construct_chat_template() only lstrip()s the template, so a template ending
in a newline (e.g. the default Llama-3 template + a trailing '\n') keeps the
trailing whitespace. That breaks the rfind-based repeated-example detection
and, on current main, also the regex fallback, which then raises
"Could not recover a two-example structure from chat_template".

Surrounding whitespace is not significant to the template here (the left side
is already stripped), so strip() both ends. Verified that the valid no-newline
template still parses via the primary path and that the meaningful trailing
token (e.g. <|eot_id|>) is preserved.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Fix trailing whitespace handling via parse retry for PR #6008

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 unsloth/chat_templates.py | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/unsloth/chat_templates.py b/unsloth/chat_templates.py
index b96f8cb7a0..fe078c5025 100644
--- a/unsloth/chat_templates.py
+++ b/unsloth/chat_templates.py
@@ -2341,13 +2341,15 @@ extra_eos_tokens = None,
 
     You must use {INPUT}, {OUTPUT} twice, and {SYSTEM} is optional.
     """
-    # Strip only the left
+    # Strip only the left: trailing whitespace can be part of the repeated example
+    # (e.g. "{OUTPUT}\n"). Accidental trailing whitespace (#992) is retried on failure.
     chat_template = chat_template.lstrip()
 
     assert(tokenizer is not None)
 
     if extra_eos_tokens is None: extra_eos_tokens = []
     elif type(extra_eos_tokens) is str: extra_eos_tokens = [extra_eos_tokens,]
+    original_extra_eos_tokens = list(extra_eos_tokens)
 
     vocab = tokenizer.get_vocab()
     for extra_eos in extra_eos_tokens:
@@ -2454,6 +2456,20 @@ extra_eos_tokens = None,
                 f"{left_changed}"
             )
     except:
+        # Accidental trailing whitespace (#992) desyncs the two-example detection,
+        # so retry once without it. Templates that parse as-is are never altered.
+        rstripped_chat_template = chat_template.rstrip()
+        if rstripped_chat_template != chat_template:
+            try:
+                return construct_chat_template(
+                    tokenizer = tokenizer,
+                    chat_template = rstripped_chat_template,
+                    default_system_message = default_system_message,
+                    extra_eos_tokens = original_extra_eos_tokens,
+                )
+            except Exception:
+                pass
+
         output_pos = chat_template.find("{OUTPUT}")
         input_pos  = chat_template.find("{INPUT}")
         if output_pos == -1 or input_pos == -1:

From 1a99980b469c757091fe00b654ca78804b17a808 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 07:10:08 -0700
Subject: [PATCH 200/222] Studio: auto Cloudflare tunnel for 0.0.0.0 launches
 (#6204)

* Studio: auto Cloudflare tunnel for 0.0.0.0 launches

Binding Studio to 0.0.0.0 for remote access often leaves the raw
http://<ip>:<port> URL unreachable (https-vs-http, blocked high ports,
closed cloud security groups). On a wildcard bind, auto-start a free
cloudflared quick tunnel and show its https://*.trycloudflare.com URL in
the startup banner:

  Secure link access via Cloudflare: https://<random>.trycloudflare.com

- new studio/backend/cloudflare_tunnel.py: find or download+cache the
  cloudflared binary (per-OS/arch GitHub release, safe .tgz extract),
  start the tunnel, parse the URL, tear it down. Stdlib only; best-effort
  and non-fatal throughout (a missing binary or offline box never blocks
  or slows startup).
- run_server starts the tunnel for 0.0.0.0 only (skips loopback, api-only
  and Colab), prints the line in the banner, and _graceful_shutdown stops
  the child so it never orphans.
- --cloudflare/--no-cloudflare flag (default on) on `unsloth studio` and
  `unsloth studio run`, forwarded through the re-exec into run_server.
- tests for the helper, the CLI flag forwarding, and the run.py defaults.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio cloudflare: send a User-Agent on the cloudflared download

GitHub's CDN can 403 the default Python-urllib User-Agent on release asset
downloads. Set an explicit UA and pin it with a test.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio cloudflare: address review (opt-out for subcommands, tunnel teardown)

- reject --no-cloudflare placed before a subcommand (it would not reach the
  subcommand), mirroring the --parallel guard
- register the tunnel before waiting for its URL so a shutdown during the wait
  stops cloudflared instead of orphaning it
- tear the server + children down if `unsloth studio run` startup aborts
  (health timeout, model-load error, Ctrl+C) before the wait loop

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/cloudflare_tunnel.py           | 302 +++++++++++++
 studio/backend/run.py                         |  52 +++
 .../backend/tests/test_cloudflare_tunnel.py   | 425 ++++++++++++++++++
 studio/backend/utils/paths/storage_roots.py   |   5 +
 unsloth_cli/commands/studio.py                |  96 ++--
 .../tests/test_studio_cloudflare_flag.py      | 292 ++++++++++++
 6 files changed, 1147 insertions(+), 25 deletions(-)
 create mode 100644 studio/backend/cloudflare_tunnel.py
 create mode 100644 studio/backend/tests/test_cloudflare_tunnel.py
 create mode 100644 unsloth_cli/tests/test_studio_cloudflare_flag.py

diff --git a/studio/backend/cloudflare_tunnel.py b/studio/backend/cloudflare_tunnel.py
new file mode 100644
index 0000000000..7c088b6e1e
--- /dev/null
+++ b/studio/backend/cloudflare_tunnel.py
@@ -0,0 +1,302 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Free Cloudflare quick tunnel for Studio's 0.0.0.0 launches.
+
+The raw http://<ip>:<port> is often unreachable (https-vs-http, blocked ports,
+closed security groups); a cloudflared quick tunnel gives a free
+https://*.trycloudflare.com URL that works anywhere, with no account or domain.
+
+Best-effort throughout: any failure collapses to "no URL" and Studio keeps
+running. Stdlib only (back-end imports are lazy) so it is safe to import early.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Optional, Tuple
+
+# cloudflared logs the quick-tunnel URL; match only the URL so we do not depend
+# on the surrounding wording, which Cloudflare may change.
+_URL_RE = re.compile(r"https://[A-Za-z0-9-]+\.trycloudflare\.com")
+
+_RELEASE_BASE = "https://github.com/cloudflare/cloudflared/releases/latest/download"
+
+_URL_TIMEOUT = 15.0  # seconds to wait for the public URL before giving up
+_DOWNLOAD_TIMEOUT = 60  # urlopen timeout for the one-time binary download
+
+
+def _windows_hidden_kwargs() -> dict:
+    """Suppress a child console window on Windows; no-op elsewhere."""
+    if sys.platform != "win32":
+        return {}
+    flags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+    return {"creationflags": flags} if flags else {}
+
+
+def _asset_name() -> Optional[Tuple[str, bool]]:
+    """(release asset filename, is_tgz) for this OS/arch, or None if unsupported."""
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    is_x64 = machine in ("x86_64", "amd64", "x64")
+    is_arm64 = machine in ("aarch64", "arm64")
+    is_x86 = machine in ("i386", "i686", "x86")
+    if system == "linux":
+        if is_x64:
+            return ("cloudflared-linux-amd64", False)
+        if is_arm64:
+            return ("cloudflared-linux-arm64", False)
+    elif system == "darwin":
+        if is_arm64:
+            return ("cloudflared-darwin-arm64.tgz", True)
+        if is_x64:
+            return ("cloudflared-darwin-amd64.tgz", True)
+    elif system == "windows":
+        if is_x64:
+            return ("cloudflared-windows-amd64.exe", False)
+        if is_x86:
+            return ("cloudflared-windows-386.exe", False)
+    return None
+
+
+def _cache_path() -> Optional[Path]:
+    """studio_bin_root()/cloudflared(.exe), or None if the studio home is unresolvable."""
+    try:
+        from utils.paths.storage_roots import studio_bin_root  # lazy: backend-only import
+    except Exception:
+        return None
+    name = "cloudflared.exe" if sys.platform == "win32" else "cloudflared"
+    return studio_bin_root() / name
+
+
+def find_cloudflared() -> Optional[str]:
+    """Locate an existing cloudflared: PATH first, then the Studio bin cache."""
+    on_path = shutil.which("cloudflared")
+    if on_path:
+        return on_path
+    cached = _cache_path()
+    if cached is not None and cached.is_file() and os.access(cached, os.X_OK):
+        return str(cached)
+    return None
+
+
+def _download(url: str, dest: Path) -> bool:
+    """Download url to dest via urllib (temp file + atomic rename). Best-effort -> bool."""
+    import tempfile
+    import urllib.request
+
+    tmp_path: Optional[Path] = None
+    try:
+        dest.parent.mkdir(parents = True, exist_ok = True)
+        with tempfile.NamedTemporaryFile(
+            prefix = dest.name + ".tmp-", dir = dest.parent, delete = False
+        ) as handle:
+            tmp_path = Path(handle.name)
+            # GitHub's CDN 403s the default Python-urllib User-Agent.
+            req = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio"})
+            with urllib.request.urlopen(req, timeout = _DOWNLOAD_TIMEOUT) as response:
+                shutil.copyfileobj(response, handle)
+        if tmp_path.stat().st_size == 0:
+            raise RuntimeError("empty download")
+        os.replace(tmp_path, dest)
+        return True
+    except Exception:
+        if tmp_path is not None:
+            try:
+                tmp_path.unlink(missing_ok = True)
+            except Exception:
+                pass
+        return False
+
+
+def _extract_tgz_member(tgz_path: Path, dest: Path) -> bool:
+    """Extract just the `cloudflared` member from a darwin .tgz to dest.
+
+    Rejects absolute paths and `..` traversal so a hostile archive cannot write
+    outside dest. Best-effort -> bool.
+    """
+    import tarfile
+    try:
+        with tarfile.open(tgz_path, "r:gz") as tar:
+            member = None
+            for m in tar.getmembers():
+                if not m.isfile() or os.path.basename(m.name) != "cloudflared":
+                    continue
+                if m.name.startswith("/") or ".." in Path(m.name).parts:
+                    continue
+                member = m
+                break
+            if member is None:
+                return False
+            src = tar.extractfile(member)
+            if src is None:
+                return False
+            with src, open(dest, "wb") as out:
+                shutil.copyfileobj(src, out)
+        return True
+    except Exception:
+        return False
+
+
+def ensure_cloudflared() -> Optional[str]:
+    """Return a cloudflared path, downloading + caching the binary once if missing."""
+    existing = find_cloudflared()
+    if existing:
+        return existing
+    asset = _asset_name()
+    cached = _cache_path()
+    if asset is None or cached is None:
+        return None
+    name, is_tgz = asset
+    url = f"{_RELEASE_BASE}/{name}"
+    try:
+        cached.parent.mkdir(parents = True, exist_ok = True)
+        if is_tgz:
+            tgz = cached.with_suffix(".tgz")
+            if not _download(url, tgz) or not _extract_tgz_member(tgz, cached):
+                tgz.unlink(missing_ok = True)
+                return None
+            tgz.unlink(missing_ok = True)
+        elif not _download(url, cached):
+            return None
+        if sys.platform != "win32":
+            os.chmod(cached, 0o755)
+        return str(cached)
+    except Exception:
+        return None
+
+
+class CloudflareTunnel:
+    """A cloudflared quick tunnel to http://localhost:<port>. Best-effort throughout.
+
+    Use localhost (not the wildcard bind) as the tunnel origin so cloudflared's
+    upstream stays local-only.
+    """
+
+    def __init__(self, port: int, binary: str):
+        self.port = port
+        self.binary = binary
+        self._proc: Optional[subprocess.Popen] = None
+        self._lock = threading.Lock()
+        self._url_event = threading.Event()
+        self.url: Optional[str] = None
+        self.error: Optional[str] = None
+
+    def start(self) -> None:
+        cmd = [
+            self.binary,
+            "tunnel",
+            "--url",
+            f"http://localhost:{self.port}",
+            "--no-autoupdate",
+        ]
+        proc = subprocess.Popen(
+            cmd,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.STDOUT,
+            stdin = subprocess.DEVNULL,
+            text = True,
+            errors = "replace",
+            bufsize = 1,
+            **_windows_hidden_kwargs(),
+        )
+        with self._lock:
+            self._proc = proc
+        threading.Thread(
+            target = self._reader, args = (proc,), name = "cloudflared-reader", daemon = True
+        ).start()
+
+    def _reader(self, proc: subprocess.Popen) -> None:
+        # Drain cloudflared's output, capture the first trycloudflare URL, and
+        # keep draining so it never blocks on a full pipe.
+        try:
+            if proc.stdout is not None:
+                for line in proc.stdout:
+                    if self.url is None:
+                        match = _URL_RE.search(line)
+                        if match:
+                            self.url = match.group(0)
+                            self._url_event.set()
+        except Exception:
+            pass
+        finally:
+            if self.url is None:
+                self.error = "cloudflared exited before emitting a tunnel URL"
+                self._url_event.set()
+
+    def wait_for_url(self, timeout: float = _URL_TIMEOUT) -> Optional[str]:
+        self._url_event.wait(timeout)
+        return self.url
+
+    def stop(self) -> None:
+        """Terminate the tunnel. Idempotent and safe to call from a signal handler."""
+        with self._lock:
+            proc, self._proc = self._proc, None
+        if proc is None:
+            return
+        try:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout = 5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    try:
+                        proc.wait(timeout = 5)
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+
+
+# Single serving process per Studio launch, so one module-level tunnel handle is
+# enough; the lock guards the start/stop/shutdown races.
+_active_tunnel: Optional[CloudflareTunnel] = None
+_active_lock = threading.Lock()
+
+
+def start_studio_tunnel(port: int, timeout: float = _URL_TIMEOUT) -> Optional[str]:
+    """Start a quick tunnel and return its public URL, or None (best-effort).
+
+    On any failure (no binary, no URL within timeout, early crash) the tunnel is
+    stopped and None is returned, so the caller prints a hint and continues.
+    """
+    global _active_tunnel
+    binary = ensure_cloudflared()
+    if not binary:
+        return None
+    tunnel = CloudflareTunnel(port, binary)
+    # Register before start/wait so a shutdown during the URL wait can stop it.
+    with _active_lock:
+        prior, _active_tunnel = _active_tunnel, tunnel
+    if prior is not None:
+        prior.stop()
+    try:
+        tunnel.start()
+        url = tunnel.wait_for_url(timeout)
+    except Exception:
+        url = None
+    if url:
+        return url
+    # No URL (or crash): drop it unless a concurrent shutdown already replaced it.
+    with _active_lock:
+        if _active_tunnel is tunnel:
+            _active_tunnel = None
+    tunnel.stop()
+    return None
+
+
+def stop_studio_tunnel() -> None:
+    """Terminate the active tunnel, if any. Idempotent."""
+    global _active_tunnel
+    with _active_lock:
+        tunnel, _active_tunnel = _active_tunnel, None
+    if tunnel is not None:
+        tunnel.stop()
diff --git a/studio/backend/run.py b/studio/backend/run.py
index 4619cb849c..32dfe06a18 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -414,9 +414,26 @@ def _emit_startup_output(host: str, port: int, display_host: str) -> None:
         print_studio_stop_hint()
     elif wildcard_bind:
         _verify_global_reachability(display_host, port)
+        _print_cloudflare_line()
         print_studio_stop_hint()
 
 
+def _print_cloudflare_line() -> None:
+    """Print the Cloudflare quick-tunnel URL for 0.0.0.0 binds, if one is up.
+
+    Reads the module-level URL set by ``run_server``. Prints nothing when the
+    tunnel is disabled or failed -- failures are silently ignored.
+    """
+    if not _cloudflare_url:
+        return
+    from startup_banner import stdout_supports_color
+
+    accent = "\033[38;5;150;1m"
+    reset = "\033[0m"
+    line = f"  Secure link access via Cloudflare: {_cloudflare_url}"
+    print(f"{accent}{line}{reset}" if stdout_supports_color() else line)
+
+
 def _get_pid_on_port(port: int) -> "tuple[int, str] | None":
     """Return (pid, process_name) listening on *port*, or None.
 
@@ -584,6 +601,13 @@ def _graceful_shutdown(server = None):
     except Exception as e:
         logger.warning("Error shutting down llama-server: %s", e)
 
+    # 6. Stop the Cloudflare tunnel (if started).
+    try:
+        from cloudflare_tunnel import stop_studio_tunnel
+        stop_studio_tunnel()
+    except Exception as e:
+        logger.warning("Error stopping Cloudflare tunnel: %s", e)
+
     logger.info("All subprocesses cleaned up")
 
 
@@ -594,6 +618,10 @@ _server = None
 # Shutdown event -- wakes the main loop on signal.
 _shutdown_event = None
 
+# trycloudflare.com URL for 0.0.0.0 binds (set by run_server, read by the banner);
+# None when there is no tunnel (loopback, disabled, or a silently-ignored failure).
+_cloudflare_url = None
+
 
 _DEFAULT_FRONTEND_PATH = Path(__file__).resolve().parent.parent / "frontend" / "dist"
 
@@ -769,6 +797,7 @@ def run_server(
     silent: bool = False,
     api_only: bool = False,
     llama_parallel_slots: int = 1,
+    cloudflare: bool = True,
 ):
     """
     Start the FastAPI server.
@@ -973,6 +1002,21 @@ def run_server(
     if api_only:
         print(f"TAURI_PORT={port}", flush = True)
 
+    # Free trycloudflare.com tunnel for 0.0.0.0 binds (the raw ip:port is often
+    # unreachable). Started pre-banner and even when silent so the CLI banner can
+    # read app.state.cloudflare_url; torn down by _graceful_shutdown.
+    global _cloudflare_url
+    _cloudflare_url = None
+    app.state.cloudflare_url = None
+    _cloudflare_enabled = cloudflare and host == "0.0.0.0" and not api_only and not _IS_COLAB
+    if _cloudflare_enabled:
+        try:  # best-effort: any failure must not block startup
+            from cloudflare_tunnel import start_studio_tunnel
+            _cloudflare_url = start_studio_tunnel(port)
+            app.state.cloudflare_url = _cloudflare_url
+        except Exception as e:
+            logger.debug("Cloudflare tunnel skipped: %s", e)
+
     if not silent:
         _emit_startup_output(host, port, display_host)
 
@@ -1011,6 +1055,13 @@ if __name__ == "__main__":
         action = "store_true",
         help = "API server only, no frontend (for Tauri)",
     )
+    parser.add_argument(
+        "--cloudflare",
+        action = argparse.BooleanOptionalAction,
+        default = True,
+        help = "Auto-create a free Cloudflare HTTPS tunnel when bound to 0.0.0.0 "
+        "(default on; --no-cloudflare to disable)",
+    )
     # Mirror unsloth_cli/commands/studio.py's _PARALLEL_*. Default 1 is for direct
     # backend launches; `unsloth studio run` always passes its own value (4).
     _PARALLEL_MIN = 1
@@ -1037,6 +1088,7 @@ if __name__ == "__main__":
         silent = args.silent,
         api_only = args.api_only,
         llama_parallel_slots = args.parallel,
+        cloudflare = args.cloudflare,
     )
     if args.frontend is not None:
         kwargs["frontend_path"] = Path(args.frontend)
diff --git a/studio/backend/tests/test_cloudflare_tunnel.py b/studio/backend/tests/test_cloudflare_tunnel.py
new file mode 100644
index 0000000000..8208f7f83f
--- /dev/null
+++ b/studio/backend/tests/test_cloudflare_tunnel.py
@@ -0,0 +1,425 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the Cloudflare quick-tunnel helper and run.py wiring.
+
+cloudflare_tunnel.py is stdlib-only (storage_roots is imported lazily), so it
+loads via spec_from_file_location without the studio venv. run.py defaults are
+checked by AST so we never import its heavy deps (uvicorn/structlog).
+"""
+
+import ast
+import importlib.util
+import io
+import sys
+import tarfile
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parent.parent
+_CT_PY = _BACKEND / "cloudflare_tunnel.py"
+_RUN_PY = _BACKEND / "run.py"
+
+
+def _load_ct():
+    spec = importlib.util.spec_from_file_location("cloudflare_tunnel", _CT_PY)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+ct = _load_ct()
+
+
+# ── URL parsing ──────────────────────────────────────────────────────
+
+
+def test_url_regex_extracts_and_ignores_noise():
+    blob = (
+        "2026-06-11T10:00:00Z INF Thank you for trying Cloudflare Tunnel.\n"
+        "2026-06-11T10:00:01Z INF Requesting new quick Tunnel on trycloudflare.com...\n"
+        "2026-06-11T10:00:01Z INF |  https://setting-democracy-gathering.trycloudflare.com  |\n"
+        "2026-06-11T10:00:02Z INF Registered tunnel connection https://not-the-url.example.com\n"
+    )
+    m = ct._URL_RE.search(blob)
+    assert m is not None
+    assert m.group(0) == "https://setting-democracy-gathering.trycloudflare.com"
+
+
+def test_url_regex_no_match_on_unrelated():
+    assert ct._URL_RE.search("INF connecting to https://api.cloudflare.com/v4") is None
+
+
+# ── asset mapping ────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "system,machine,expected",
+    [
+        ("Linux", "x86_64", ("cloudflared-linux-amd64", False)),
+        ("Linux", "aarch64", ("cloudflared-linux-arm64", False)),
+        ("Darwin", "arm64", ("cloudflared-darwin-arm64.tgz", True)),
+        ("Darwin", "x86_64", ("cloudflared-darwin-amd64.tgz", True)),
+        ("Windows", "AMD64", ("cloudflared-windows-amd64.exe", False)),
+        ("Windows", "x86", ("cloudflared-windows-386.exe", False)),
+        ("Linux", "mips", None),
+        ("Plan9", "x86_64", None),
+    ],
+)
+def test_asset_name(monkeypatch, system, machine, expected):
+    monkeypatch.setattr(ct.platform, "system", lambda: system)
+    monkeypatch.setattr(ct.platform, "machine", lambda: machine)
+    assert ct._asset_name() == expected
+
+
+# ── binary discovery ─────────────────────────────────────────────────
+
+
+def test_find_cloudflared_prefers_path(monkeypatch):
+    monkeypatch.setattr(ct.shutil, "which", lambda name: "/usr/local/bin/cloudflared")
+    assert ct.find_cloudflared() == "/usr/local/bin/cloudflared"
+
+
+def test_find_cloudflared_falls_back_to_cache(monkeypatch, tmp_path):
+    cached = tmp_path / "cloudflared"
+    cached.write_text("#!/bin/sh\n")
+    cached.chmod(0o755)
+    monkeypatch.setattr(ct.shutil, "which", lambda name: None)
+    monkeypatch.setattr(ct, "_cache_path", lambda: cached)
+    assert ct.find_cloudflared() == str(cached)
+
+
+def test_find_cloudflared_none_when_missing(monkeypatch, tmp_path):
+    monkeypatch.setattr(ct.shutil, "which", lambda name: None)
+    monkeypatch.setattr(ct, "_cache_path", lambda: tmp_path / "absent")
+    assert ct.find_cloudflared() is None
+
+
+# ── ensure / download ────────────────────────────────────────────────
+
+
+def test_ensure_downloads_and_chmods_when_missing(monkeypatch, tmp_path):
+    cached = tmp_path / "cloudflared"
+    monkeypatch.setattr(ct, "find_cloudflared", lambda: None)
+    monkeypatch.setattr(ct, "_asset_name", lambda: ("cloudflared-linux-amd64", False))
+    monkeypatch.setattr(ct, "_cache_path", lambda: cached)
+
+    def fake_download(url, dest):
+        assert url.endswith("/cloudflared-linux-amd64")
+        dest.write_bytes(b"ELF-ish")
+        return True
+
+    monkeypatch.setattr(ct, "_download", fake_download)
+    monkeypatch.setattr(ct.sys, "platform", "linux")
+    path = ct.ensure_cloudflared()
+    assert path == str(cached)
+    assert cached.exists()
+    assert cached.stat().st_mode & 0o111  # executable bit set
+
+
+def test_ensure_returns_none_on_download_failure(monkeypatch, tmp_path):
+    monkeypatch.setattr(ct, "find_cloudflared", lambda: None)
+    monkeypatch.setattr(ct, "_asset_name", lambda: ("cloudflared-linux-amd64", False))
+    monkeypatch.setattr(ct, "_cache_path", lambda: tmp_path / "cloudflared")
+    monkeypatch.setattr(ct, "_download", lambda url, dest: False)
+    assert ct.ensure_cloudflared() is None
+
+
+def test_ensure_returns_none_for_unsupported_arch(monkeypatch, tmp_path):
+    monkeypatch.setattr(ct, "find_cloudflared", lambda: None)
+    monkeypatch.setattr(ct, "_asset_name", lambda: None)
+    monkeypatch.setattr(ct, "_cache_path", lambda: tmp_path / "cloudflared")
+    assert ct.ensure_cloudflared() is None
+
+
+def test_download_sets_user_agent(monkeypatch, tmp_path):
+    import urllib.request
+
+    captured = {}
+
+    class _Resp:
+        _sent = False
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def read(self, n = -1):
+            if self._sent:
+                return b""
+            self._sent = True
+            return b"payload"
+
+    def fake_urlopen(req, timeout = None):
+        captured["ua"] = req.get_header("User-agent")
+        return _Resp()
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    dest = tmp_path / "cloudflared"
+    assert ct._download("https://github.com/cloudflare/cloudflared/x", dest) is True
+    assert captured["ua"] == "unsloth-studio"  # GitHub CDN 403s the default UA
+    assert dest.read_bytes() == b"payload"
+
+
+# ── cross-platform: Windows (.exe), macOS (.tgz) ─────────────────────
+
+
+def test_cache_path_uses_exe_on_windows(monkeypatch, tmp_path):
+    import types
+
+    fake_sr = types.ModuleType("utils.paths.storage_roots")
+    fake_sr.studio_bin_root = lambda: tmp_path
+    monkeypatch.setitem(sys.modules, "utils.paths.storage_roots", fake_sr)
+    monkeypatch.setattr(ct.sys, "platform", "win32")
+    assert ct._cache_path() == tmp_path / "cloudflared.exe"
+
+
+def test_ensure_windows_downloads_exe(monkeypatch, tmp_path):
+    cached = tmp_path / "cloudflared.exe"
+    monkeypatch.setattr(ct, "find_cloudflared", lambda: None)
+    monkeypatch.setattr(ct, "_asset_name", lambda: ("cloudflared-windows-amd64.exe", False))
+    monkeypatch.setattr(ct, "_cache_path", lambda: cached)
+    monkeypatch.setattr(ct.sys, "platform", "win32")
+
+    def fake_download(url, dest):
+        assert url.endswith("/cloudflared-windows-amd64.exe")
+        dest.write_bytes(b"MZ")  # PE header magic
+        return True
+
+    monkeypatch.setattr(ct, "_download", fake_download)
+    # chmod is skipped on Windows; would raise on a path that does not exist yet.
+    monkeypatch.setattr(ct.os, "chmod", lambda *a, **k: pytest.fail("chmod called on win32"))
+    assert ct.ensure_cloudflared() == str(cached)
+    assert cached.read_bytes() == b"MZ"
+
+
+def test_ensure_macos_extracts_tgz_and_chmods(monkeypatch, tmp_path):
+    cached = tmp_path / "cloudflared"
+    monkeypatch.setattr(ct, "find_cloudflared", lambda: None)
+    monkeypatch.setattr(ct, "_asset_name", lambda: ("cloudflared-darwin-arm64.tgz", True))
+    monkeypatch.setattr(ct, "_cache_path", lambda: cached)
+    monkeypatch.setattr(ct.sys, "platform", "darwin")
+
+    def fake_download(url, dest):
+        # dest is cached.with_suffix(".tgz"); write a real archive there.
+        assert url.endswith("/cloudflared-darwin-arm64.tgz")
+        with tarfile.open(dest, "w:gz") as tar:
+            data = b"mach-o"
+            info = tarfile.TarInfo(name = "cloudflared")
+            info.size = len(data)
+            tar.addfile(info, io.BytesIO(data))
+        return True
+
+    monkeypatch.setattr(ct, "_download", fake_download)
+    path = ct.ensure_cloudflared()
+    assert path == str(cached)
+    assert cached.read_bytes() == b"mach-o"
+    assert cached.stat().st_mode & 0o111  # chmod applied on posix
+    assert not cached.with_suffix(".tgz").exists()  # temp archive cleaned up
+
+
+# ── .tgz extraction (darwin) ─────────────────────────────────────────
+
+
+def _make_tgz(
+    tmp_path,
+    member_name,
+    data = b"bin",
+):
+    tgz = tmp_path / "cf.tgz"
+    with tarfile.open(tgz, "w:gz") as tar:
+        info = tarfile.TarInfo(name = member_name)
+        info.size = len(data)
+        tar.addfile(info, io.BytesIO(data))
+    return tgz
+
+
+def test_tgz_extraction_extracts_clean_member(tmp_path):
+    tgz = _make_tgz(tmp_path, "cloudflared")
+    dest = tmp_path / "out"
+    assert ct._extract_tgz_member(tgz, dest) is True
+    assert dest.read_bytes() == b"bin"
+
+
+def test_tgz_extraction_rejects_traversal(tmp_path):
+    tgz = _make_tgz(tmp_path, "../cloudflared")
+    dest = tmp_path / "out"
+    assert ct._extract_tgz_member(tgz, dest) is False
+    assert not dest.exists()
+
+
+def test_tgz_extraction_missing_member(tmp_path):
+    tgz = _make_tgz(tmp_path, "README")
+    dest = tmp_path / "out"
+    assert ct._extract_tgz_member(tgz, dest) is False
+
+
+# ── tunnel lifecycle ─────────────────────────────────────────────────
+
+
+class _FakePopen:
+    def __init__(self):
+        self.terminated = False
+        self.killed = False
+        self._alive = True
+
+    def poll(self):
+        return None if self._alive else 0
+
+    def terminate(self):
+        self.terminated = True
+        self._alive = False
+
+    def wait(self, timeout = None):
+        if self._alive:
+            raise ct.subprocess.TimeoutExpired(cmd = "cloudflared", timeout = timeout)
+        return 0
+
+    def kill(self):
+        self.killed = True
+        self._alive = False
+
+
+def test_stop_terminates_process():
+    t = ct.CloudflareTunnel(8080, "/bin/cloudflared")
+    fake = _FakePopen()
+    t._proc = fake
+    t.stop()
+    assert fake.terminated is True
+    assert t._proc is None
+    # second stop is a no-op (idempotent)
+    t.stop()
+
+
+def test_wait_for_url_times_out_without_blocking():
+    t = ct.CloudflareTunnel(8080, "/bin/cloudflared")
+    assert t.wait_for_url(timeout = 0.05) is None
+
+
+def test_start_studio_tunnel_no_binary(monkeypatch):
+    monkeypatch.setattr(ct, "ensure_cloudflared", lambda: None)
+    assert ct.start_studio_tunnel(8080) is None
+
+
+def test_start_studio_tunnel_registers_before_wait(monkeypatch):
+    # The tunnel must be visible to stop_studio_tunnel() during the URL wait,
+    # else a shutdown in that window orphans cloudflared.
+    seen = {}
+
+    class _Stub:
+        def __init__(self, port, binary):
+            self.url = None
+
+        def start(self):
+            pass
+
+        def wait_for_url(self, timeout):
+            seen["active_during_wait"] = ct._active_tunnel is self
+            self.url = "https://x.trycloudflare.com"
+            return self.url
+
+        def stop(self):
+            seen["stopped"] = True
+
+    monkeypatch.setattr(ct, "ensure_cloudflared", lambda: "/bin/cloudflared")
+    monkeypatch.setattr(ct, "CloudflareTunnel", _Stub)
+    try:
+        assert ct.start_studio_tunnel(8080) == "https://x.trycloudflare.com"
+        assert seen["active_during_wait"] is True
+    finally:
+        ct.stop_studio_tunnel()
+
+
+def test_start_studio_tunnel_clears_and_stops_on_no_url(monkeypatch):
+    seen = {}
+
+    class _Stub:
+        def __init__(self, port, binary):
+            self.url = None
+
+        def start(self):
+            pass
+
+        def wait_for_url(self, timeout):
+            return None
+
+        def stop(self):
+            seen["stopped"] = True
+
+    monkeypatch.setattr(ct, "ensure_cloudflared", lambda: "/bin/cloudflared")
+    monkeypatch.setattr(ct, "CloudflareTunnel", _Stub)
+    assert ct.start_studio_tunnel(8080) is None
+    assert seen.get("stopped") is True
+    assert ct._active_tunnel is None
+
+
+def test_start_studio_tunnel_returns_url(monkeypatch):
+    class _StubTunnel:
+        def __init__(self, port, binary):
+            self.url = None
+
+        def start(self):
+            self.url = "https://stub-xyz.trycloudflare.com"
+
+        def wait_for_url(self, timeout):
+            return self.url
+
+        def stop(self):
+            pass
+
+    monkeypatch.setattr(ct, "ensure_cloudflared", lambda: "/bin/cloudflared")
+    monkeypatch.setattr(ct, "CloudflareTunnel", _StubTunnel)
+    try:
+        assert ct.start_studio_tunnel(8080) == "https://stub-xyz.trycloudflare.com"
+    finally:
+        ct.stop_studio_tunnel()
+
+
+# ── run.py source-level pins (AST / source, no heavy import) ─────────
+
+
+def _func_param_defaults(source, func_name):
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == func_name:
+            args = node.args.args
+            defaults = node.args.defaults
+            offset = len(args) - len(defaults)
+            out = {}
+            for i, d in enumerate(defaults):
+                if isinstance(d, ast.Constant):
+                    out[args[offset + i].arg] = d.value
+            return out
+    return {}
+
+
+def _argparse_default(source, option):
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr == "add_argument" and node.args:
+                a0 = node.args[0]
+                if isinstance(a0, ast.Constant) and a0.value == option:
+                    for kw in node.keywords:
+                        if kw.arg == "default" and isinstance(kw.value, ast.Constant):
+                            return kw.value.value
+    return None
+
+
+def test_run_server_cloudflare_default_true():
+    defaults = _func_param_defaults(_RUN_PY.read_text(), "run_server")
+    assert defaults.get("cloudflare") is True
+
+
+def test_argparse_cloudflare_default_true():
+    assert _argparse_default(_RUN_PY.read_text(), "--cloudflare") is True
+
+
+def test_run_server_gates_tunnel_on_wildcard():
+    # Guard against accidentally widening the trigger beyond 0.0.0.0.
+    source = _RUN_PY.read_text()
+    assert "_cloudflare_enabled" in source
+    assert 'host == "0.0.0.0"' in source
diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.py
index 10597a689b..2d4f5ac243 100644
--- a/studio/backend/utils/paths/storage_roots.py
+++ b/studio/backend/utils/paths/storage_roots.py
@@ -60,6 +60,11 @@ def cache_root() -> Path:
     return studio_root() / "cache"
 
 
+def studio_bin_root() -> Path:
+    """Dir for Studio-managed executables (the `unsloth` shim, downloaded tools like cloudflared)."""
+    return studio_root() / "bin"
+
+
 def assets_root() -> Path:
     return studio_root() / "assets"
 
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index b506f764d7..7493b87eee 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -597,6 +597,11 @@ def studio_default(
             f"defaults to {_PARALLEL_DEFAULT_RUN}."
         ),
     ),
+    cloudflare: bool = typer.Option(
+        True,
+        "--cloudflare/--no-cloudflare",
+        help = "Auto-create a free Cloudflare HTTPS tunnel when bound to 0.0.0.0 (default on).",
+    ),
 ):
     """Launch the Unsloth Studio server."""
     # Runs before every subcommand (run/setup/update/...).
@@ -614,6 +619,16 @@ def studio_default(
                 err = True,
             )
             raise typer.Exit(2)
+        # Same for --no-cloudflare: it would not reach the subcommand.
+        if not cloudflare:
+            typer.echo(
+                f"Error: --no-cloudflare on `unsloth studio` applies to the "
+                f"plain-server path only. For `unsloth studio "
+                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
+                f"`unsloth studio {ctx.invoked_subcommand} --no-cloudflare ...`",
+                err = True,
+            )
+            raise typer.Exit(2)
         return
 
     # Use the studio venv if it exists and we aren't already in it.
@@ -648,6 +663,8 @@ def studio_default(
                 args.append("--silent")
             if api_only:
                 args.append("--api-only")
+            # Forward the explicit polarity (matches run.py's BooleanOptionalAction).
+            args.append("--cloudflare" if cloudflare else "--no-cloudflare")
             # On Windows os.execvp keeps the parent alive, so Ctrl+C
             # would orphan the child; use Popen+wait instead.
             if sys.platform == "win32":
@@ -689,6 +706,7 @@ def studio_default(
         silent = silent,
         api_only = api_only,
         llama_parallel_slots = parallel,
+        cloudflare = cloudflare,
     )
     if frontend is not None:
         run_kwargs["frontend_path"] = frontend
@@ -861,6 +879,11 @@ def run(
             f"{_PARALLEL_DEFAULT_RUN} (pre-PR hardcoded value)."
         ),
     ),
+    cloudflare: bool = typer.Option(
+        True,
+        "--cloudflare/--no-cloudflare",
+        help = "Auto-create a free Cloudflare HTTPS tunnel when bound to 0.0.0.0 (default on).",
+    ),
 ):
     """Start Studio, load a model, print an API key -- one-liner server.
 
@@ -980,6 +1003,8 @@ def run(
         # Typer claims --parallel outside ctx.args; without this the
         # child reverts to its default and silently drops the value.
         args.extend(["--parallel", str(parallel)])
+        # Forward the explicit polarity (same rationale as --load-in-4bit above).
+        args.append("--cloudflare" if cloudflare else "--no-cloudflare")
         # llama-server pass-through extras → child ctx.args → load payload.
         if extra_llama_args:
             args.extend(extra_llama_args)
@@ -997,7 +1022,13 @@ def run(
     # ── 2. Start server (always suppress built-in banner) ─────────────
     from studio.backend.run import run_server, _resolve_external_ip
 
-    run_kwargs = dict(host = host, port = port, silent = True, llama_parallel_slots = parallel)
+    run_kwargs = dict(
+        host = host,
+        port = port,
+        silent = True,
+        llama_parallel_slots = parallel,
+        cloudflare = cloudflare,
+    )
     if frontend is not None:
         run_kwargs["frontend_path"] = frontend
     app = run_server(**run_kwargs)
@@ -1011,32 +1042,41 @@ def run(
 
     set_tool_policy(enable_tools)
 
-    # 3. Wait for server health.
-    if not silent:
-        typer.echo("Starting Unsloth Studio...")
-    if not _wait_for_server(actual_port):
-        typer.echo("Error: server did not become healthy within 30 seconds.", err = True)
-        raise typer.Exit(1)
+    # Steps 3-5 can abort (health timeout, model-load error, or Ctrl+C during the
+    # slow load); tear the server and its children (llama-server, cloudflared) down
+    # on any abort so they never orphan.
+    from studio.backend.run import _graceful_shutdown, _server
 
-    # 4. Create API key in-process.
-    api_key = _create_api_key_inprocess(api_key_name)
-
-    # 5. Load model via HTTP.
-    if not silent:
-        typer.echo(f"Loading model: {model}...")
     try:
-        result = _load_model_via_http(
-            port = actual_port,
-            api_key = api_key,
-            model = model,
-            gguf_variant = gguf_variant,
-            max_seq_length = max_seq_length,
-            load_in_4bit = load_in_4bit,
-            llama_extra_args = extra_llama_args,
-        )
-    except RuntimeError as exc:
-        typer.echo(f"Error: {exc}", err = True)
-        raise typer.Exit(1)
+        # 3. Wait for server health.
+        if not silent:
+            typer.echo("Starting Unsloth Studio...")
+        if not _wait_for_server(actual_port):
+            typer.echo("Error: server did not become healthy within 30 seconds.", err = True)
+            raise typer.Exit(1)
+
+        # 4. Create API key in-process.
+        api_key = _create_api_key_inprocess(api_key_name)
+
+        # 5. Load model via HTTP.
+        if not silent:
+            typer.echo(f"Loading model: {model}...")
+        try:
+            result = _load_model_via_http(
+                port = actual_port,
+                api_key = api_key,
+                model = model,
+                gguf_variant = gguf_variant,
+                max_seq_length = max_seq_length,
+                load_in_4bit = load_in_4bit,
+                llama_extra_args = extra_llama_args,
+            )
+        except RuntimeError as exc:
+            typer.echo(f"Error: {exc}", err = True)
+            raise typer.Exit(1)
+    except BaseException:
+        _graceful_shutdown(_server)
+        raise
 
     loaded_model = result.get("model", model)
     display_variant = f" ({gguf_variant})" if gguf_variant else ""
@@ -1045,6 +1085,8 @@ def run(
     display_host = _resolve_external_ip() if host == "0.0.0.0" else host
     base_url = f"http://{display_host}:{actual_port}"
     sdk_base_url = f"{base_url}/v1"
+    # run_server started the tunnel during the silent run above (0.0.0.0 only).
+    _cf_url = getattr(app.state, "cloudflare_url", None)
 
     # Orange so the tool-policy notice stands out; printed under
     # --silent / --yes too so the policy is never invisible.
@@ -1074,6 +1116,8 @@ def run(
         typer.echo("")
         typer.echo("=" * 56)
         typer.echo(f"  Unsloth Studio running at {base_url}")
+        if _cf_url:
+            typer.echo(f"  Secure link access via Cloudflare: {_cf_url}")
         typer.echo(f"  Model loaded: {loaded_model}{display_variant}")
         typer.echo(f"  API Key:      {api_key}")
         typer.echo("")
@@ -1107,6 +1151,8 @@ def run(
     else:
         # Silent still prints URL + API key + tool-status policy.
         typer.echo(f"URL:     {base_url}")
+        if _cf_url:
+            typer.echo(f"Secure link access via Cloudflare: {_cf_url}")
         typer.echo(f"API Key: {api_key}")
         typer.secho(_tool_notice, fg = _tool_notice_fg, bold = True)
 
diff --git a/unsloth_cli/tests/test_studio_cloudflare_flag.py b/unsloth_cli/tests/test_studio_cloudflare_flag.py
new file mode 100644
index 0000000000..5c2a039547
--- /dev/null
+++ b/unsloth_cli/tests/test_studio_cloudflare_flag.py
@@ -0,0 +1,292 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the `--cloudflare/--no-cloudflare` Studio flag.
+
+Pins the typer Option (default on) on both `unsloth studio` and
+`unsloth studio run`, and that the chosen polarity reaches the re-exec'd
+child and run_server. Modeled on test_studio_run_parallel_flag.py.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+
+def _studio():
+    from unsloth_cli.commands import studio as _studio_mod
+    return _studio_mod
+
+
+_BASE = ["--model", "unsloth/Qwen3-1.7B-GGUF"]
+
+
+# ── option registration ──────────────────────────────────────────────
+
+
+def test_run_exposes_cloudflare_option_default_on():
+    import inspect
+
+    sig = inspect.signature(_studio().run)
+    assert "cloudflare" in sig.parameters
+    opt = sig.parameters["cloudflare"].default
+    decls = set(getattr(opt, "param_decls", []) or [])
+    assert "--cloudflare/--no-cloudflare" in decls
+    assert getattr(opt, "default", None) is True
+
+
+def test_studio_default_exposes_cloudflare_option_default_on():
+    import inspect
+
+    sig = inspect.signature(_studio().studio_default)
+    assert "cloudflare" in sig.parameters
+    opt = sig.parameters["cloudflare"].default
+    assert getattr(opt, "default", None) is True
+
+
+# ── re-exec forwarding: `unsloth studio run` ─────────────────────────
+
+
+class _ExecCaptured(SystemExit):
+    def __init__(self, argv):
+        super().__init__(0)
+        self.argv = list(argv)
+
+
+def _install_run_reexec_capture(monkeypatch, *, platform = "linux"):
+    studio_mod = _studio()
+    captured = []
+
+    monkeypatch.setattr(sys, "prefix", "/nonexistent/outer/venv")
+    fake_venv = Path("/fake/studio/venv/unsloth_studio")
+    monkeypatch.setattr(studio_mod, "_studio_venv_python", lambda: fake_venv / "bin" / "python")
+    fake_bin = fake_venv / "bin" / "unsloth"
+    real_is_file = Path.is_file
+    monkeypatch.setattr(
+        Path,
+        "is_file",
+        lambda self: True if str(self) == str(fake_bin) else real_is_file(self),
+    )
+    from unsloth_cli import _tool_policy as _tp_mod
+
+    monkeypatch.setattr(
+        _tp_mod,
+        "resolve_tool_policy",
+        lambda host, flag, yes, silent: False if flag is None else bool(flag),
+    )
+    monkeypatch.setattr(sys, "platform", platform)
+
+    def fake_execvp(file, argv):
+        captured.append(list(argv))
+        raise _ExecCaptured(argv)
+
+    monkeypatch.setattr(studio_mod.os, "execvp", fake_execvp)
+    return captured
+
+
+def _invoke_run(monkeypatch, args):
+    import typer as _typer
+
+    studio_mod = _studio()
+    captured = _install_run_reexec_capture(monkeypatch)
+    app = _typer.Typer()
+    app.command(
+        context_settings = {"allow_extra_args": True, "ignore_unknown_options": True},
+    )(studio_mod.run)
+    CliRunner().invoke(app, args, catch_exceptions = True)
+    return captured
+
+
+@pytest.mark.parametrize(
+    "user_flag,expected,unexpected",
+    [
+        (None, "--cloudflare", "--no-cloudflare"),  # default on
+        ("--cloudflare", "--cloudflare", "--no-cloudflare"),
+        ("--no-cloudflare", "--no-cloudflare", "--cloudflare"),
+    ],
+)
+def test_run_reexec_forwards_cloudflare_polarity(monkeypatch, user_flag, expected, unexpected):
+    extras = [user_flag] if user_flag else []
+    captured = _invoke_run(monkeypatch, _BASE + extras)
+    assert len(captured) == 1, captured
+    argv = captured[0]
+    assert expected in argv, f"expected {expected} in child argv; got {argv}"
+    assert unexpected not in argv, f"unexpected {unexpected} in child argv; got {argv}"
+
+
+# ── re-exec forwarding: plain `unsloth studio` ───────────────────────
+
+
+def _invoke_studio_default(
+    monkeypatch,
+    args,
+    *,
+    platform = "linux",
+):
+    import typer as _typer
+
+    studio_mod = _studio()
+    captured = []
+
+    monkeypatch.setattr(sys, "prefix", "/nonexistent/outer/venv")
+    monkeypatch.setattr(studio_mod, "_ensure_studio_env_exported", lambda: None)
+    fake_venv = Path("/fake/studio/venv/unsloth_studio")
+    monkeypatch.setattr(studio_mod, "_studio_venv_python", lambda: fake_venv / "bin" / "python")
+    monkeypatch.setattr(studio_mod, "_find_run_py", lambda: Path("/fake/studio/run.py"))
+    monkeypatch.setattr(studio_mod, "_find_frontend_dist", lambda: None)
+    monkeypatch.setattr(sys, "platform", platform)
+
+    def fake_execvp(file, argv):
+        captured.append(list(argv))
+        raise _ExecCaptured(argv)
+
+    monkeypatch.setattr(studio_mod.os, "execvp", fake_execvp)
+
+    app = _typer.Typer()
+    app.command()(studio_mod.studio_default)
+    CliRunner().invoke(app, args, catch_exceptions = True)
+    return captured
+
+
+@pytest.mark.parametrize(
+    "user_flag,expected,unexpected",
+    [
+        (None, "--cloudflare", "--no-cloudflare"),
+        ("--no-cloudflare", "--no-cloudflare", "--cloudflare"),
+    ],
+)
+def test_studio_default_reexec_forwards_cloudflare(monkeypatch, user_flag, expected, unexpected):
+    extras = [user_flag] if user_flag else []
+    captured = _invoke_studio_default(monkeypatch, ["-H", "0.0.0.0"] + extras)
+    assert len(captured) == 1, captured
+    argv = captured[0]
+    assert expected in argv, f"expected {expected}; got {argv}"
+    assert unexpected not in argv, f"unexpected {unexpected}; got {argv}"
+
+
+# ── in-venv path forwards cloudflare into run_server ─────────────────
+
+
+class _RunServerCaptured(SystemExit):
+    def __init__(self, kwargs):
+        super().__init__(0)
+        self.kwargs = dict(kwargs)
+
+
+@pytest.mark.parametrize("user_flag,expected", [(None, True), ("--no-cloudflare", False)])
+def test_run_in_venv_passes_cloudflare_to_run_server(monkeypatch, user_flag, expected):
+    import types
+
+    studio_mod = _studio()
+    fake_venv = Path("/fake/studio/venv/unsloth_studio")
+    monkeypatch.setattr(sys, "prefix", str(fake_venv))
+    monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)
+
+    from unsloth_cli import _tool_policy as _tp_mod
+
+    monkeypatch.setattr(
+        _tp_mod,
+        "resolve_tool_policy",
+        lambda host, flag, yes, silent: False if flag is None else bool(flag),
+    )
+
+    captured: dict = {}
+
+    def fake_run_server(**kwargs):
+        captured.update(kwargs)
+        raise _RunServerCaptured(kwargs)
+
+    fake_backend_run = sys.modules.setdefault(
+        "studio.backend.run", types.ModuleType("studio.backend.run")
+    )
+    fake_backend_run.run_server = fake_run_server
+    fake_backend_run._resolve_external_ip = lambda: "127.0.0.1"
+
+    import typer as _typer
+
+    app = _typer.Typer()
+    app.command(
+        context_settings = {"allow_extra_args": True, "ignore_unknown_options": True},
+    )(studio_mod.run)
+    extras = [user_flag] if user_flag else []
+    CliRunner().invoke(app, _BASE + extras, catch_exceptions = True)
+
+    assert captured.get("cloudflare") is expected, captured
+
+
+# ── parent-level --no-cloudflare with a subcommand is rejected ───────
+
+
+def test_studio_default_rejects_no_cloudflare_with_subcommand(monkeypatch):
+    # `unsloth studio --no-cloudflare run ...` would not reach the subcommand,
+    # so it must error (mirrors --parallel) rather than silently still tunnel.
+    import typer as _typer
+
+    studio_mod = _studio()
+    app = _typer.Typer()
+    app.add_typer(studio_mod.studio_app, name = "studio")
+    result = CliRunner().invoke(app, ["studio", "--no-cloudflare", "run", "--model", "X"])
+    assert result.exit_code == 2, result.output
+    combined = (result.output or "") + (getattr(result, "stderr", "") or "")
+    assert "--no-cloudflare" in combined, combined
+
+
+# ── run() tears the server + tunnel down if startup aborts ───────────
+
+
+def test_run_in_venv_shuts_down_on_startup_abort(monkeypatch):
+    import types
+
+    studio_mod = _studio()
+    fake_venv = Path("/fake/studio/venv/unsloth_studio")
+    monkeypatch.setattr(sys, "prefix", str(fake_venv))
+    monkeypatch.setattr(studio_mod, "STUDIO_HOME", fake_venv.parent)
+
+    from unsloth_cli import _tool_policy as _tp_mod
+
+    monkeypatch.setattr(
+        _tp_mod,
+        "resolve_tool_policy",
+        lambda host, flag, yes, silent: False if flag is None else bool(flag),
+    )
+
+    class _App:
+        class state:
+            server_port = 8888
+
+    shutdown_calls = []
+    backend = sys.modules.setdefault("studio.backend.run", types.ModuleType("studio.backend.run"))
+    backend.run_server = lambda **k: _App()
+    backend._resolve_external_ip = lambda: "1.2.3.4"
+    backend._server = object()
+    backend._shutdown_event = None
+    backend._graceful_shutdown = lambda server: shutdown_calls.append(server)
+
+    # set_tool_policy is imported as `from state.tool_policy import set_tool_policy`.
+    state_mod = sys.modules.setdefault("state", types.ModuleType("state"))
+    tp_mod = sys.modules.setdefault("state.tool_policy", types.ModuleType("state.tool_policy"))
+    tp_mod.set_tool_policy = lambda *a, **k: None
+    state_mod.tool_policy = tp_mod
+
+    # Force the health check to fail so startup aborts after run_server().
+    monkeypatch.setattr(studio_mod, "_wait_for_server", lambda *a, **k: False)
+
+    import typer as _typer
+
+    app = _typer.Typer()
+    app.command(
+        context_settings = {"allow_extra_args": True, "ignore_unknown_options": True},
+    )(studio_mod.run)
+    result = CliRunner().invoke(app, _BASE + ["-H", "0.0.0.0"], catch_exceptions = True)
+
+    assert result.exit_code == 1, result.output
+    assert len(shutdown_calls) == 1, "startup abort must call _graceful_shutdown"

From 14f679da8acd3f083a9f2a5e2fe84d2e38f06351 Mon Sep 17 00:00:00 2001
From: BardiaKoopah <bkoop2003@gmail.com>
Date: Thu, 11 Jun 2026 07:25:24 -0700
Subject: [PATCH 201/222] fix(studio): surface NaN loss honestly instead of
 laundering to last finite value (#6016)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When training produced a NaN or Inf loss event, the handler filtered the
value to None but never updated progress.loss — clients kept seeing the
last finite value as if everything were fine.

Now: on non-finite loss, clear progress.loss to None and log a one-shot
warning. Training continues (no phase=error, no _should_stop), matching
the expected behavior for a non-fatal numerical event.

Test: tests/test_training_nan_loss_handling.py with 6 cases covering
finite, NaN, +/-Inf, idempotency of the one-shot warning, and recovery
when a finite step follows a non-finite one.
---
 studio/backend/core/training/training.py      |  19 +++-
 .../tests/test_training_nan_loss_handling.py  | 106 ++++++++++++++++++
 2 files changed, 124 insertions(+), 1 deletion(-)
 create mode 100644 studio/backend/tests/test_training_nan_loss_handling.py

diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index c5bc3dbad5..5bd9bc5338 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -534,8 +534,21 @@ class TrainingBackend:
                 except (TypeError, ValueError):
                     logger.debug("Could not convert loss to float: %s", _raw_loss)
                     _safe_loss = None
-                if _safe_loss is not None and not math.isfinite(_safe_loss):
+                _loss_is_nonfinite = (
+                    _safe_loss is not None and not math.isfinite(_safe_loss)
+                )
+                if _loss_is_nonfinite:
+                    # Drop the value rather than laundering it back to the last
+                    # finite loss; clients see loss=None at this step so the NaN
+                    # is not hidden behind a stale value. Training continues.
                     _safe_loss = None
+                    if not getattr(self._progress, "_nonfinite_loss_warned", False):
+                        self._progress._nonfinite_loss_warned = True
+                        logger.warning(
+                            "Training produced non-finite loss at step %s; "
+                            "loss field will report null until it recovers.",
+                            event.get("step", "?"),
+                        )
                 try:
                     _safe_lr = float(_raw_lr) if _raw_lr is not None else None
                 except (TypeError, ValueError):
@@ -545,6 +558,10 @@ class TrainingBackend:
                     _safe_lr = None
                 if _safe_loss is not None:
                     self._progress.loss = _safe_loss
+                elif _loss_is_nonfinite:
+                    # Clear stale finite loss so the API doesn't keep
+                    # reporting the last good value while NaN is happening.
+                    self._progress.loss = None
                 if _safe_lr is not None:
                     self._progress.learning_rate = _safe_lr
                 self._progress.total_steps = event.get("total_steps", self._progress.total_steps)
diff --git a/studio/backend/tests/test_training_nan_loss_handling.py b/studio/backend/tests/test_training_nan_loss_handling.py
new file mode 100644
index 0000000000..0ab444f9bb
--- /dev/null
+++ b/studio/backend/tests/test_training_nan_loss_handling.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Pin Studio's behavior when a training event reports non-finite (NaN/Inf) loss.
+
+The training event handler used to filter NaN/Inf to None silently while
+leaving the previous finite loss in progress.loss — so the API kept reporting
+the stale value as if everything were fine. We now drop the stale value:
+clients see loss=None at the affected step and a one-shot warning is logged.
+Training continues; the run is not marked failed.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import sys
+
+import pytest
+
+_BACKEND = os.path.join(os.path.dirname(__file__), "..")
+if _BACKEND not in sys.path:
+    sys.path.insert(0, _BACKEND)
+
+from core.training.training import TrainingBackend
+
+
+def _make_backend() -> TrainingBackend:
+    return TrainingBackend()
+
+
+def _progress_event(step: int, loss: float, lr: float = 1e-4) -> dict:
+    return {
+        "type": "progress",
+        "step": step,
+        "loss": loss,
+        "learning_rate": lr,
+        "epoch": 0.0,
+        "total_steps": 100,
+    }
+
+
+class TestNonfiniteLossSoftHandling:
+    def test_finite_loss_updates_progress_normally(self):
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=0.97))
+        assert b._progress.loss == pytest.approx(0.97)
+        assert b._progress.error is None
+        assert b._should_stop is False
+        assert getattr(b._progress, "_nonfinite_loss_warned", False) is False
+
+    def test_nan_loss_clears_progress_loss(self):
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=0.97))
+        assert b._progress.loss == pytest.approx(0.97)
+        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        # Stale finite loss must NOT leak through
+        assert b._progress.loss is None
+        # Run is not marked failed
+        assert b._progress.error is None
+        assert b._should_stop is False
+        # Warning flag is set so we don't re-log on every subsequent NaN step
+        assert b._progress._nonfinite_loss_warned is True
+
+    def test_inf_loss_clears_progress_loss(self):
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=float("inf")))
+        assert b._progress.loss is None
+        assert b._progress.error is None
+        assert b._should_stop is False
+        assert b._progress._nonfinite_loss_warned is True
+
+    def test_negative_inf_loss_clears_progress_loss(self):
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=float("-inf")))
+        assert b._progress.loss is None
+        assert b._progress.error is None
+        assert b._should_stop is False
+        assert b._progress._nonfinite_loss_warned is True
+
+    def test_repeated_nan_only_warns_once(self):
+        """Subsequent NaN events must not re-fire the warning flag setter.
+        The flag should already be True after the first NaN."""
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=0.97))
+        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        assert b._progress._nonfinite_loss_warned is True
+        # Further NaN steps don't change anything we care about
+        b._handle_event(_progress_event(step=3, loss=float("nan")))
+        b._handle_event(_progress_event(step=4, loss=float("nan")))
+        assert b._progress._nonfinite_loss_warned is True
+        assert b._progress.loss is None
+        assert b._progress.error is None
+        assert b._should_stop is False
+
+    def test_recovery_updates_loss_when_finite_again(self):
+        """If a NaN step is followed by a finite step, progress.loss must
+        reflect the new finite value (not stay stuck at None)."""
+        b = _make_backend()
+        b._handle_event(_progress_event(step=1, loss=0.97))
+        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        assert b._progress.loss is None
+        b._handle_event(_progress_event(step=3, loss=0.85))
+        assert b._progress.loss == pytest.approx(0.85)
+        # Warning flag stays set (we don't reset it on recovery)
+        assert b._progress._nonfinite_loss_warned is True

From 0ac051177ab03c597af64d679b2063f05443a397 Mon Sep 17 00:00:00 2001
From: BardiaKoopah <bkoop2003@gmail.com>
Date: Thu, 11 Jun 2026 07:29:05 -0700
Subject: [PATCH 202/222] fix(mlx): forward resume_from_checkpoint to
 MLXTrainer.train() (#6173)

Studio's frontend exposes a Resume action and submits requests with
resume_from_checkpoint set to a previous run's output_dir. The CUDA
training paths in worker.py read this field from config and pass it to
trainer.train() (see lines 2729-2787 and 3108-3229). The MLX path
_run_mlx_training did neither: it never read config['resume_from_checkpoint']
and called trainer.train() with no args. The MLX trainer also did not
accept the kwarg, so even threading it through would have been a no-op.

With this PR + the unsloth-zoo companion PR adding the trainer-side
support (saves optimizer_state + trainer_state, accepts and applies
resume_from_checkpoint in MLXTrainer.train()), MLX Resume now works
end-to-end. Verified on M2 16GB with Qwen3-0.6B + unsloth/LaTeX_OCR:
loss at every post-resume step matches a fresh run bit for bit
(2.168627977371216 == 2.168627977371216 at step 6, etc).

Two lines: read the field near the other config.get() extractions in
_run_mlx_training, pass it as a kwarg at the trainer.train() call site.

Companion PR: unslothai/unsloth-zoo#751
---
 studio/backend/core/training/worker.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index fb5e9b5137..427687451c 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1389,6 +1389,12 @@ def _run_mlx_training(event_queue, stop_queue, config):
     # Force text-only for non-image datasets even on vision-capable models
     # (e.g. Qwen3.5-VL trained on plain alpaca text).
     _send("status", status_message = f"Loading {model_name}...")
+    # Pull through resume_from_checkpoint so MLXTrainer.train() can restore
+    # optimizer + step state and continue cleanly. Was previously dropped on
+    # the floor for the MLX path, so the Resume UI button silently restarted
+    # from step 0 (the CUDA path at lines 2729 / 3108 has been forwarding
+    # this all along).
+    resume_from_checkpoint = config.get("resume_from_checkpoint") or None
     is_dataset_image = bool(config.get("is_dataset_image", False))
     training_type = config.get("training_type", "LoRA/QLoRA")
     use_lora = training_type == "LoRA/QLoRA"
@@ -1852,7 +1858,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
     # ── 11. Run training ──
     gc.collect()
     mx.synchronize()
-    trainer.train()
+    trainer.train(resume_from_checkpoint=resume_from_checkpoint)
 
     # ── 12. Save and finalize ──
     if trainer.stop_requested and not _stop_save[0]:

From 7467064c6650b401665beb03d285cd6d19cb6776 Mon Sep 17 00:00:00 2001
From: Burak Emir <burak.emir@gmail.com>
Date: Thu, 11 Jun 2026 16:45:10 +0200
Subject: [PATCH 203/222] Bump hono to 4.12.21, fixes CVE-2026-47676 (#6014)

---
 studio/frontend/package-lock.json | 6 +++---
 studio/frontend/package.json      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index 690da8c0c4..a521552d79 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -10264,9 +10264,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.18",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.18.tgz",
-      "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==",
+      "version": "4.12.21",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.21.tgz",
+      "integrity": "sha512-uV63apnb0kyPtAUwoWgaGh9HyIFcv8lgmzPZSiTBQAFOFGIzka5EZ1dZocmGnn0XdX0+XTqJ6Tqv7selMuGLRQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 2217dd080b..c49b62ab50 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -86,7 +86,7 @@
     "@tanstack/router-core": "1.169.2",
     "@tanstack/history": "1.161.6",
     "mermaid": "11.15.0",
-    "hono": "4.12.18",
+    "hono": "4.12.21",
     "qs": "6.15.2",
     "ip-address": "10.1.1",
     "brace-expansion@5.0.5": "5.0.6"

From d24ee77f1736b9bdcf87296905e18ca0ef5147d4 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 07:48:21 -0700
Subject: [PATCH 204/222] Fix Llama 3.1+ rope scaling dropped on the
 FastLanguageModel path (long inputs become gibberish past ~29K tokens)
 (#6197)

* Fix config.rope_scaling being dropped by the replaced rotary embedding (#2405)

On modern transformers, LlamaModel builds its rotary embedding from config
using unsloth's replacement LlamaRotaryEmbedding class, whose config path
computed vanilla inv_freq and ignored config.rope_scaling entirely. The
llama3/linear/longrope dispatch in patch_llama_rope_scaling rewrites
LlamaAttention.__init__, which no longer constructs rotary embeddings, so it
never fires; the model-level rotary is then copied onto every attention
layer. Result: Llama-3.1/3.2/3.3 ran with unscaled RoPE on the
FastLanguageModel path and collapsed into repetition loops past roughly 29K
tokens (PASS at 28867, FAIL at 31767 in needle retrieval). FastModel was
unaffected because vision.py keeps transformers' own rotary. qwen2, qwen3,
qwen3_moe, mistral and cohere assign the same base class, so any rope-scaled
config of those families was equally exposed.

The fix makes the base class config path compute inv_freq and
attention_scaling via transformers' ROPE_INIT_FUNCTIONS (covers llama3,
linear, dynamic, yarn, longrope), with an inline llama3 fallback reading
factors from config for older transformers, degrading to prior behavior on
any failure. attention_scaling is applied in _set_cos_sin_cache (1.0 default,
exact no-op for unscaled paths) and persists across extend_rope_embedding.
A type(self) guard prevents double-scaling via the legacy scaled subclasses.

Adds tests/utils/test_rope_scaling_drift.py (AST tripwire + behavioral
inv_freq/cos-cache/extension checks, validated to fail 4 of 5 on the unfixed
code) and wires it into the existing consolidated CI HARD GATE step.

Verified on GPU: 48K-token needle retrieval flips FAIL to PASS for
FastLanguageModel in bf16 and 4bit, 20K stays PASS, scaled inv_freq matches
transformers exactly, and the left-padded batch generation guard still gets
exact solo-vs-batched token matches.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address review: normalize object-style rope_scaling, vectorize llama3 fallback

config.rope_scaling can be a config object rather than a dict on newer
transformers; _rope_scaling_as_dict normalizes it (to_dict/dict/vars
fallbacks) before any .get() access, with a regression test using a
dataclass stand-in. The inline llama3 fallback now uses torch.where instead
of a per-frequency Python loop; verified bit-for-bit equal to transformers
ROPE_INIT_FUNCTIONS for factor 8 (Llama-3.1) and factor 32 (Llama-3.2).

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address review: CPU-safe rope guard tests, normalized config for delegation

The rotary constructor builds per-device CUDA caches, so the behavioral tests
that instantiate it cannot run on GPU-less CI. Restructured into three layers:
the AST tripwire now also asserts the constructor stays wired to
_compute_config_rope_inv_freq; the CPU layer tests that pure helper directly
(llama3 dict, llama3 object, linear object, default type) with no
instantiation; the instantiation and cache tests are gated behind a real CUDA
probe (actual tensor allocation, so import-time CUDA spoofs cannot fool the
gate). Verified: 9 passed with GPU; 5 passed 4 skipped with CUDA hidden; 5
failed 4 skipped on the unfixed code in CPU mode.

Delegation to ROPE_INIT_FUNCTIONS now retries with a shallow config copy
carrying the normalized rope_scaling dict when the original was an object the
installed transformers cannot read; covered by a linear-object test, which has
no inline fallback and passes only through that retry path.

* Tighten comments in rope scaling fix and guard test

Comment and docstring reduction only; verified code-identical with
scripts/comment_tools.py check --strip-docstrings (AST signature match on
both Python files). All guard tests unchanged: 20 passed with GPU, 5 passed
4 skipped with CUDA hidden.

* Apply repo kwarg-spacing format

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 .github/workflows/consolidated-tests-ci.yml |  21 +-
 tests/utils/test_rope_scaling_drift.py      | 312 ++++++++++++++++++++
 unsloth/models/llama.py                     | 123 +++++++-
 3 files changed, 436 insertions(+), 20 deletions(-)
 create mode 100644 tests/utils/test_rope_scaling_drift.py

diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index 022c796ac4..f7c338d76b 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -333,19 +333,16 @@ jobs:
         run: |
           python -m pytest -v --tb=short tests/test_callback_signature_drift.py
 
-      - name: batched left-padding generation guard (HARD GATE)
-        # Guards _fast_prepare_inputs_for_generation against the bug class of
-        # issues #1066 / #3699: position_ids taken from cache_position (which
-        # counts left-pad tokens) or the 2D attention mask truncated to its
-        # last column. Both shipped in cc4c5d77 and were fixed by #2216 and
-        # #4100; nothing tested this path, so each regression reached users.
-        # Layer 1 in the file is stdlib-ast-only (survives unsloth import
-        # breakage), layer 2 calls the real function on CPU via the
-        # tests/conftest.py CUDA spoof. Validated to fail on the pre-#2216
-        # and pre-#4100 code states; staging proof on GPU-less runners:
-        # danielhanchen/unsloth-staging-2 PR 170 (green, gate passed in all combos) / PR 172 (red, gate failed in all combos).
+      - name: generation correctness guards (HARD GATE)
+        # Deterministic CPU guards, each validated to fail on its pre-fix code:
+        # leftpad = batched left-padded generation (#1066/#3699, fixed by
+        # #2216 + #4100; staging proof: unsloth-staging-2 PRs 170/172);
+        # rope_scaling_drift = config.rope_scaling dropped by replaced rotary
+        # classes (#2405). AST checks run first so import breakage cannot mask them.
         run: |
-          python -m pytest -v --tb=short tests/utils/test_prepare_inputs_leftpad.py
+          python -m pytest -v --tb=short \
+            tests/utils/test_prepare_inputs_leftpad.py \
+            tests/utils/test_rope_scaling_drift.py
 
       - name: unsloth Bucket-A — CPU tests not in Repo tests (CPU)
         # CPU tests across 6 files under tests/saving/, tests/utils/, tests/python/
diff --git a/tests/utils/test_rope_scaling_drift.py b/tests/utils/test_rope_scaling_drift.py
new file mode 100644
index 0000000000..fae5a7d8a8
--- /dev/null
+++ b/tests/utils/test_rope_scaling_drift.py
@@ -0,0 +1,312 @@
+"""Guard for config.rope_scaling being silently dropped (issue #2405).
+
+Unsloth's replacement rotary classes ignored rope_scaling when constructed
+from a config (the modern-transformers path), so Llama-3.1 ran with unscaled
+RoPE and collapsed into gibberish past ~32K tokens.
+
+Layers: (1) AST tripwire, stdlib only; (2) CPU checks of the pure helper
+_compute_config_rope_inv_freq against transformers' ROPE_INIT_FUNCTIONS;
+(3) CUDA checks instantiating the real class (skipped without a real device,
+probed by allocating a tensor so import-time CUDA spoofs cannot fool the gate).
+Layers 2 and 3 fail on the unfixed code.
+"""
+
+import ast
+import math
+from pathlib import Path
+
+import pytest
+import torch
+
+
+def _has_real_cuda():
+    try:
+        torch.zeros(1).to("cuda")
+        return True
+    except Exception:
+        return False
+
+
+HAS_REAL_CUDA = _has_real_cuda()
+requires_cuda = pytest.mark.skipif(
+    not HAS_REAL_CUDA,
+    reason = "LlamaRotaryEmbedding builds per-device CUDA caches in __init__",
+)
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+LLAMA_PY = REPO_ROOT / "unsloth" / "models" / "llama.py"
+
+CLASS_NAME = "LlamaRotaryEmbedding"
+
+# Llama-3.1-style rope_scaling.
+LLAMA3_ROPE_SCALING = {
+    "rope_type": "llama3",
+    "factor": 8.0,
+    "low_freq_factor": 1.0,
+    "high_freq_factor": 4.0,
+    "original_max_position_embeddings": 8192,
+}
+ROPE_THETA = 500000.0
+HEAD_DIM = 128
+MAX_POS = 131072
+
+
+# --- Layer 1: AST structural tripwire (stdlib only, no unsloth import) ---
+
+
+def _load_class_init():
+    tree = ast.parse(LLAMA_PY.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and node.name == CLASS_NAME:
+            for sub in node.body:
+                if isinstance(sub, ast.FunctionDef) and sub.name == "__init__":
+                    return sub
+    raise AssertionError(
+        f"{CLASS_NAME}.__init__ not found in {LLAMA_PY}; if it was renamed or "
+        "moved, update this guard so RoPE scaling stays protected (issue #2405)"
+    )
+
+
+def _config_branch(init_fn):
+    """The `if config is not None:` block at the top of __init__."""
+    for node in init_fn.body:
+        if isinstance(node, ast.If):
+            test = node.test
+            is_config_test = (
+                isinstance(test, ast.Compare)
+                and isinstance(test.left, ast.Name)
+                and test.left.id == "config"
+            )
+            if is_config_test:
+                return node
+    return None
+
+
+def test_config_path_inspects_rope_scaling():
+    init_fn = _load_class_init()
+    branch = _config_branch(init_fn)
+    assert branch is not None, (
+        f"{CLASS_NAME}.__init__ no longer has an `if config is not None:` "
+        "branch; the config constructor path must read config.rope_scaling so "
+        "scaled models (llama3/linear/longrope) are not silently unscaled "
+        "(issue #2405)"
+    )
+
+    names = set()
+    for stmt in branch.body:
+        for sub in ast.walk(stmt):
+            if isinstance(sub, ast.Attribute):
+                names.add(sub.attr)
+            elif isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+                names.add(sub.value)
+    assert "rope_scaling" in names, (
+        f"{CLASS_NAME}.__init__ config path does not reference `rope_scaling`. "
+        "When a rotary class is built straight from a config (the path modern "
+        "transformers takes, since rotary moved to LlamaModel), the llama3 / "
+        "linear / longrope scaling must still be applied; otherwise long inputs "
+        "produce repeated-pattern gibberish (issue #2405)."
+    )
+
+    called = {
+        sub.func.id
+        for stmt in branch.body
+        for sub in ast.walk(stmt)
+        if isinstance(sub, ast.Call) and isinstance(sub.func, ast.Name)
+    }
+    assert "_compute_config_rope_inv_freq" in called, (
+        f"{CLASS_NAME}.__init__ config path no longer calls "
+        "_compute_config_rope_inv_freq; the CPU behavioral tests below cover "
+        "that helper directly, so the constructor must stay wired to it or "
+        "scaled configs silently lose RoPE scaling again (issue #2405)."
+    )
+
+
+# --- Layer 2: CPU behavioral guard (pure helper, no instantiation) ---
+
+
+def _make_config(rope_scaling):
+    from transformers import LlamaConfig
+    return LlamaConfig(
+        hidden_size = 256,
+        num_attention_heads = 2,
+        num_key_value_heads = 2,
+        head_dim = HEAD_DIM,
+        rope_theta = ROPE_THETA,
+        max_position_embeddings = MAX_POS,
+        rope_scaling = rope_scaling,
+    )
+
+
+def _unsloth_rotary(config):
+    from unsloth.models import llama as llama_mod
+    return llama_mod.LlamaRotaryEmbedding(config = config)
+
+
+def _reference_inv_freq(config, rope_type):
+    from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+    inv_freq, _attention_factor = ROPE_INIT_FUNCTIONS[rope_type](config, "cpu")
+    return inv_freq.float().cpu()
+
+
+def _vanilla_inv_freq():
+    return 1.0 / (
+        ROPE_THETA ** (torch.arange(0, HEAD_DIM, 2, dtype = torch.int64).float() / HEAD_DIM)
+    )
+
+
+def _compute_helper(config, rope_scaling):
+    from unsloth.models.llama import _compute_config_rope_inv_freq
+    return _compute_config_rope_inv_freq(config, rope_scaling)
+
+
+def test_llama3_scaling_applied_to_inv_freq():
+    config = _make_config(LLAMA3_ROPE_SCALING)
+    got, attention_scaling = _compute_helper(config, config.rope_scaling)
+    expected = _reference_inv_freq(config, "llama3")
+    vanilla = _vanilla_inv_freq()
+
+    # Guard against a vacuous test.
+    assert not torch.allclose(
+        expected, vanilla, rtol = 1e-4
+    ), "test setup error: llama3-scaled inv_freq should differ from vanilla"
+    assert got is not None, (
+        "_compute_config_rope_inv_freq returned None for a llama3 config; the "
+        "config path is dropping config.rope_scaling, so long-context inference "
+        "degrades into repeated-pattern gibberish (issue #2405)."
+    )
+    got = got.float().cpu()
+    assert torch.allclose(got, expected, rtol = 1e-4, atol = 1e-6), (
+        "inv_freq for a llama3 config does not match transformers' llama3 RoPE "
+        "scaling (issue #2405).\n"
+        f"got[:6]={got[:6].tolist()}\nexpected[:6]={expected[:6].tolist()}"
+    )
+
+
+def test_default_rope_type_matches_vanilla_inv_freq():
+    config = _make_config(None)
+    got, attention_scaling = _compute_helper(config, {"rope_type": "default"})
+    assert got is not None
+    vanilla = _vanilla_inv_freq()
+    assert torch.allclose(got.float().cpu(), vanilla, rtol = 1e-4, atol = 1e-6), (
+        "default rope_type must equal the vanilla inv_freq; "
+        f"got[:6]={got[:6].tolist()} vanilla[:6]={vanilla[:6].tolist()}"
+    )
+
+
+def _cos_at_position(rot, position):
+    """cos row at one position, built like _set_cos_sin_cache but CPU-only."""
+    inv_freq = rot.inv_freq.float().cpu()
+    t = torch.tensor([position], dtype = torch.float32)
+    t = rot._apply_time_scaling(t.clone()) if hasattr(rot, "_apply_time_scaling") else t
+    freqs = torch.outer(t, inv_freq)
+    emb = torch.cat((freqs, freqs), dim = -1)
+    return emb.cos().squeeze(0)
+
+
+# --- Layer 3: CUDA behavioral guard (real instantiation needs a device) ---
+
+
+@requires_cuda
+def test_constructor_applies_llama3_scaling():
+    config = _make_config(LLAMA3_ROPE_SCALING)
+    rot = _unsloth_rotary(config)
+    got = rot.inv_freq.float().cpu()
+    expected = _reference_inv_freq(config, "llama3")
+    assert torch.allclose(
+        got, expected, rtol = 1e-4, atol = 1e-6
+    ), "LlamaRotaryEmbedding built from a llama3 config produced unscaled inv_freq (issue #2405)."
+
+
+@requires_cuda
+def test_constructor_unscaled_config_uses_vanilla_inv_freq():
+    rot = _unsloth_rotary(_make_config(None))
+    got = rot.inv_freq.float().cpu()
+    vanilla = _vanilla_inv_freq()
+    assert torch.allclose(
+        got, vanilla, rtol = 1e-4, atol = 1e-6
+    ), "LlamaRotaryEmbedding with no rope_scaling must use the vanilla inv_freq"
+
+
+@requires_cuda
+def test_cos_cache_differs_between_scaled_and_unscaled_at_long_position():
+    scaled = _unsloth_rotary(_make_config(LLAMA3_ROPE_SCALING))
+    unscaled = _unsloth_rotary(_make_config(None))
+
+    pos = 10000
+    cos_scaled = _cos_at_position(scaled, pos)
+    cos_unscaled = _cos_at_position(unscaled, pos)
+    assert not torch.allclose(cos_scaled, cos_unscaled, rtol = 1e-4, atol = 1e-5), (
+        f"cos values at position {pos} are identical for a llama3-scaled and an "
+        "unscaled rotary embedding, which means scaling was dropped (issue "
+        "#2405). With correct llama3 scaling the low-frequency bands shrink by "
+        "up to 8x and must change the angles at long positions."
+    )
+
+
+@requires_cuda
+def test_extended_cache_keeps_scaling_after_growth():
+    scaled = _unsloth_rotary(_make_config(LLAMA3_ROPE_SCALING))
+    # Grow past the initial cache size (mirrors long-context decode).
+    dummy = torch.zeros(1, dtype = torch.float32)
+    scaled.extend_rope_embedding(dummy, seq_len = 40960)
+
+    config = _make_config(LLAMA3_ROPE_SCALING)
+    expected = _reference_inv_freq(config, "llama3")
+    got = scaled.inv_freq.float().cpu()
+    assert torch.allclose(got, expected, rtol = 1e-4, atol = 1e-6), (
+        "growing the RoPE cache (extend_rope_embedding) must preserve llama3 "
+        "scaling of inv_freq; long-context decode loses scaling otherwise "
+        "(issue #2405)."
+    )
+
+
+def test_object_style_rope_scaling_does_not_crash():
+    # Object-style rope_scaling must be normalized, not .get()'d directly.
+    from dataclasses import dataclass
+
+    from unsloth.models.llama import _compute_config_rope_inv_freq
+
+    @dataclass
+    class FakeRopeScalingConfig:
+        rope_type: str = "llama3"
+        factor: float = 8.0
+        low_freq_factor: float = 1.0
+        high_freq_factor: float = 4.0
+        original_max_position_embeddings: int = 8192
+
+    config = _make_config(LLAMA3_ROPE_SCALING)
+    inv_freq, attention_scaling = _compute_config_rope_inv_freq(config, FakeRopeScalingConfig())
+    assert inv_freq is not None, (
+        "object-style (non-dict) config.rope_scaling must be normalized, not "
+        "dropped; otherwise scaled models silently lose RoPE scaling again "
+        "(issue #2405)."
+    )
+    expected = _reference_inv_freq(config, "llama3")
+    assert torch.allclose(inv_freq.float().cpu(), expected, rtol = 1e-4, atol = 1e-6)
+
+
+def test_object_style_rope_scaling_on_config_delegates_correctly():
+    # 'linear' has no inline fallback; only the normalized-config retry passes this.
+    from dataclasses import dataclass
+
+    from unsloth.models.llama import _compute_config_rope_inv_freq
+
+    @dataclass
+    class FakeLinearRopeScalingConfig:
+        rope_type: str = "linear"
+        factor: float = 4.0
+
+    dict_config = _make_config({"rope_type": "linear", "factor": 4.0})
+    expected = _reference_inv_freq(dict_config, "linear")
+
+    object_config = _make_config({"rope_type": "linear", "factor": 4.0})
+    object_config.rope_scaling = FakeLinearRopeScalingConfig()
+    inv_freq, attention_scaling = _compute_config_rope_inv_freq(
+        object_config, object_config.rope_scaling
+    )
+    assert inv_freq is not None, (
+        "linear rope_scaling exposed as a config object was silently dropped; "
+        "delegation must retry with a config copy carrying the normalized dict "
+        "(issue #2405)."
+    )
+    assert torch.allclose(inv_freq.float().cpu(), expected, rtol = 1e-4, atol = 1e-6)
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index d5883e4346..2d31f71ab1 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -1622,6 +1622,93 @@ def _get_rope_theta(config, default = 10000.0):
     return default
 
 
+def _rope_scaling_as_dict(rope_scaling):
+    """Normalize config.rope_scaling (dict or config object) to a dict; {} on failure."""
+    if isinstance(rope_scaling, dict):
+        return rope_scaling
+    for converter in ("to_dict", "dict"):
+        fn = getattr(rope_scaling, converter, None)
+        if callable(fn):
+            try:
+                d = fn()
+                if isinstance(d, dict):
+                    return d
+            except Exception:
+                pass
+    try:
+        return {k: v for k, v in vars(rope_scaling).items() if not k.startswith("_")}
+    except TypeError:
+        return {}
+
+
+def _llama3_inv_freq_from_config(
+    config,
+    rope_scaling,
+    device = "cpu",
+):
+    """llama3 inv_freq with factors from config; fallback when modeling_rope_utils is missing."""
+    base = _get_rope_theta(config, default = 10000.0)
+    dim = getattr(config, "head_dim", None)
+    if dim is None:
+        dim = int(config.hidden_size // config.num_attention_heads)
+    inv_freq = 1.0 / (
+        base ** (torch.arange(0, dim, 2, dtype = torch.int64, device = device).float() / dim)
+    )
+
+    scale_factor = rope_scaling.get("factor", 8.0)
+    low_freq_factor = rope_scaling.get("low_freq_factor", 1.0)
+    high_freq_factor = rope_scaling.get("high_freq_factor", 4.0)
+    old_context_len = rope_scaling.get("original_max_position_embeddings", 8192)
+
+    low_freq_wavelen = old_context_len / low_freq_factor
+    high_freq_wavelen = old_context_len / high_freq_factor
+    assert low_freq_wavelen != high_freq_wavelen
+
+    # Vectorized meta-llama bands: high freqs kept, low divided by factor, medium blended.
+    wavelen = 2 * math.pi / inv_freq
+    scaled = torch.where(wavelen > low_freq_wavelen, inv_freq / scale_factor, inv_freq)
+    smooth = (old_context_len / wavelen - low_freq_factor) / (high_freq_factor - low_freq_factor)
+    smoothed = (1 - smooth) * inv_freq / scale_factor + smooth * inv_freq
+    is_medium = (wavelen >= high_freq_wavelen) & (wavelen <= low_freq_wavelen)
+    return torch.where(is_medium, smoothed, scaled)
+
+
+def _compute_config_rope_inv_freq(config, rope_scaling):
+    """(inv_freq, attention_scaling) per config.rope_scaling via transformers'
+    ROPE_INIT_FUNCTIONS, with an inline llama3 fallback; (None, 1.0) on failure."""
+    original_rope_scaling = rope_scaling
+    rope_scaling = _rope_scaling_as_dict(rope_scaling)
+    rope_type = rope_scaling.get("rope_type", None) or rope_scaling.get("type", None)
+    try:
+        from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+
+        rope_init_fn = ROPE_INIT_FUNCTIONS[rope_type]
+        try:
+            inv_freq, attention_scaling = rope_init_fn(config, torch.device("cpu"))
+        except Exception:
+            # Object-style rope_scaling: retry with a config copy carrying the plain dict.
+            if isinstance(original_rope_scaling, dict):
+                raise
+            import copy as _copy
+
+            config_copy = _copy.copy(config)
+            config_copy.rope_scaling = rope_scaling
+            inv_freq, attention_scaling = rope_init_fn(config_copy, torch.device("cpu"))
+        return inv_freq.to(dtype = torch.float32, device = "cpu"), float(attention_scaling)
+    except Exception as exception:
+        if rope_type == "llama3":
+            try:
+                return _llama3_inv_freq_from_config(config, rope_scaling), 1.0
+            except Exception:
+                pass
+        logger.warning_once(
+            f"Unsloth: Could not apply RoPE scaling '{rope_type}' from config "
+            f"({type(exception).__name__}: {exception}); falling back to unscaled RoPE. "
+            "Long-context generation may degrade."
+        )
+        return None, 1.0
+
+
 # Solves https://github.com/unslothai/unsloth/issues/168
 # Static KV Cache was introduced in 4.38.0, causing training to be much slower.
 # Inference can now be CUDAGraphed, but we shall retain the old rotary embeddings.
@@ -1640,6 +1727,12 @@ class LlamaRotaryEmbedding(torch.nn.Module):
         config = None,  # [TODO] Hack to pass in config - need to remove later
     ):
         super().__init__()
+        # cos/sin multiplier (1.0 except yarn / longrope); set before any cache build.
+        self.attention_scaling = 1.0
+        # Base-class-from-config path (modern transformers): derive inv_freq like
+        # transformers so config.rope_scaling is not dropped (#2405). Scaled
+        # subclasses are excluded to avoid double-scaling.
+        config_inv_freq = None
         if config is not None:
             # [TODO] Hack to pass in config - need to remove later
             base = _get_rope_theta(config, default = base)
@@ -1652,6 +1745,13 @@ class LlamaRotaryEmbedding(torch.nn.Module):
             device = DEVICE_TYPE_TORCH
             max_position_embeddings = config.max_position_embeddings
 
+            rope_scaling = getattr(config, "rope_scaling", None)
+            if rope_scaling is not None and type(self) is LlamaRotaryEmbedding:
+                config_inv_freq, self.attention_scaling = _compute_config_rope_inv_freq(
+                    config,
+                    rope_scaling,
+                )
+
         self.dim = dim
         self.max_position_embeddings = max_position_embeddings
         self.base = base
@@ -1660,12 +1760,17 @@ class LlamaRotaryEmbedding(torch.nn.Module):
         self.multi_gpu_cos_cached = [None] * DEVICE_COUNT
         self.multi_gpu_sin_cached = [None] * DEVICE_COUNT
 
-        # Normal Llama-3 RoPE
-        inv_freq = 1.0 / (
-            self.base
-            ** (torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float() / self.dim)
-        )
-        inv_freq = self._apply_inv_freq_scaling(inv_freq)
+        if config_inv_freq is not None:
+            inv_freq = config_inv_freq  # already scaled; skip subclass scaling
+        else:
+            # Normal Llama-3 RoPE
+            inv_freq = 1.0 / (
+                self.base
+                ** (
+                    torch.arange(0, self.dim, 2, dtype = torch.int64, device = "cpu").float() / self.dim
+                )
+            )
+            inv_freq = self._apply_inv_freq_scaling(inv_freq)
         self.register_buffer("inv_freq", inv_freq, persistent = False)
 
         # Build here to make `torch.jit.trace` work.
@@ -1704,8 +1809,10 @@ class LlamaRotaryEmbedding(torch.nn.Module):
         freqs = torch.outer(t, self.inv_freq)
         # Different from paper, but it uses a different permutation in order to obtain the same calculation
         emb = torch.cat((freqs, freqs), dim = -1)
-        cos = emb.cos().to(dtype = dtype, device = device, non_blocking = True)
-        sin = emb.sin().to(dtype = dtype, device = device, non_blocking = True)
+        # Applied here so attention_scaling survives extend_rope_embedding rebuilds;
+        # default 1.0 keeps unscaled paths bit-identical.
+        cos = (emb.cos() * self.attention_scaling).to(dtype = dtype, device = device, non_blocking = True)
+        sin = (emb.sin() * self.attention_scaling).to(dtype = dtype, device = device, non_blocking = True)
         self.multi_gpu_cos_cached[device.index] = cos
         self.multi_gpu_sin_cached[device.index] = sin
         return cos, sin

From bc85ecd145ed5ceae8dab662e3686485c1e6a559 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 07:49:55 -0700
Subject: [PATCH 205/222] Studio: report the real llama-server context window
 and add an opt-in overflow policy for OpenAI-compatible serving (#6164)

* Studio: report the real llama-server context window and add an opt-in overflow policy for OpenAI-compatible serving

A community report showed OpenCode failing tool calls every few minutes
against Studio's OpenAI-compatible API while the same GGUF was stable on
LM Studio. Root cause: Studio advertises the requested context length, but
llama-server can allocate less (memory-fit step on small GPUs, --parallel
slot split), so clients budget against a window that does not exist. Their
generations truncate mid tool call at the real wall (finish_reason=length
with cut JSON arguments) and eventually the prompt itself exceeds the real
window, returning a 400 that agentic clients treat as non-retryable.

Changes:
- After llama-server health, read default_generation_settings.n_ctx from
  /props and adopt it whenever it is below Studio's computed context, with
  a warning. The load response, status route, UI value, and the passthrough
  max_tokens ceiling all become honest automatically.
- Expose context_length and max_context_length on /v1/models so clients can
  budget against the enforced window.
- Accept empty role=tool content (commands with no output are routine in
  agentic loops; OpenAI and llama-server both accept it) instead of a 400.
- Add context_overflow=truncate_middle (per request, or server-wide via
  UNSLOTH_CONTEXT_OVERFLOW=truncate_middle): on exceed_context_size_error
  the passthrough drops whole middle turn-groups (system prompt, first turn,
  and recent turns kept; tool calls stay paired with their results), clips
  oversized contents middle-out when group-dropping is not enough, clamps
  max_tokens to the generation headroom, and retries. Default stays 'error'
  with code=context_length_exceeded so clients running their own compaction
  keep full control.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Studio: allocate the requested context for real (kv-unified, fit-ctx floor)

Two launch-flag gaps caused the advertised vs allocated divergence at the
source:
- llama-server enables --kv-unified only when the slot count is auto; Studio
  always passes --parallel N, which silently splits -c into per-slot windows
  of -c/N. Pass --kv-unified when N > 1 so a single request can use the full
  advertised window (same total KV memory, shared pool).
- with --fit on the fit step may set ctx as low as 4096; pass
  --fit-ctx <requested> for explicit requests so fit offloads or fails into
  the existing --fit off retry instead of silently shrinking the window.

Both flags are gated on --help capability probing so older builds keep the
current behavior, where the /props readback remains the backstop. Verified
live: -c 98304 --parallel 4 now serves per-slot n_ctx 98304 (was 24576),
48k-token requests pass through the passthrough, and the readback warning no
longer fires.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py    |  78 +++++
 studio/backend/models/inference.py            |  16 +-
 studio/backend/routes/inference.py            | 288 +++++++++++++++---
 .../tests/test_context_overflow_truncation.py | 277 +++++++++++++++++
 .../tests/test_llama_cpp_props_readback.py    | 254 +++++++++++++++
 .../tests/test_openai_tool_passthrough.py     |   9 +-
 .../tests/test_tool_message_empty_content.py  |  53 ++++
 7 files changed, 924 insertions(+), 51 deletions(-)
 create mode 100644 studio/backend/tests/test_context_overflow_truncation.py
 create mode 100644 studio/backend/tests/test_llama_cpp_props_readback.py
 create mode 100644 studio/backend/tests/test_tool_message_empty_content.py

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index e46d464784..2560f9e5ac 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -1153,6 +1153,8 @@ class LlamaCppBackend:
                 "ngram_mod_flavor": None,
                 "supports_ngram_mod": False,
                 "spec_draft_n_max_flag": None,
+                "supports_kv_unified": False,
+                "supports_fit_ctx": False,
             }
         try:
             mtime = int(Path(bin_path).stat().st_mtime)
@@ -1166,6 +1168,8 @@ class LlamaCppBackend:
         mtp_token: Optional[str] = None
         ngram_mod_flavor: Optional[str] = None
         spec_draft_n_max_flag: Optional[str] = None
+        supports_kv_unified = False
+        supports_fit_ctx = False
         try:
             result = subprocess.run(
                 [bin_path, "--help"],
@@ -1253,6 +1257,9 @@ class LlamaCppBackend:
                 spec_draft_n_max_flag = "--spec-draft-n-max"
             elif _is_real("--draft-max"):
                 spec_draft_n_max_flag = "--draft-max"
+
+            supports_kv_unified = _is_real("--kv-unified")
+            supports_fit_ctx = _is_real("--fit-ctx")
         except (OSError, subprocess.SubprocessError) as exc:
             logger.debug(f"llama-server --help probe failed: {exc}")
 
@@ -1263,6 +1270,8 @@ class LlamaCppBackend:
             "ngram_mod_flavor": ngram_mod_flavor,
             "supports_ngram_mod": ngram_mod_flavor is not None,
             "spec_draft_n_max_flag": spec_draft_n_max_flag,
+            "supports_kv_unified": supports_kv_unified,
+            "supports_fit_ctx": supports_fit_ctx,
         }
         cls._capability_cache[cache_key] = info
         return info
@@ -3232,6 +3241,16 @@ class LlamaCppBackend:
                     # Fits on selected GPU(s) -- offload all layers
                     cmd.extend(["-ngl", "-1"])
 
+                cmd.extend(
+                    self._ctx_integrity_flags(
+                        n_parallel,
+                        use_fit,
+                        requested_ctx,
+                        effective_ctx,
+                        self.probe_server_capabilities(binary),
+                    )
+                )
+
                 # -1 = llama.cpp auto-detect (physical cores). Pass explicitly
                 # so we don't inherit llama-server's internal default, which
                 # has varied (hardware concurrency incl. hyperthreads on some
@@ -3585,6 +3604,7 @@ class LlamaCppBackend:
                 self._effective_context_length = (
                     effective_ctx if effective_ctx > 0 else self._context_length
                 )
+                self._reconcile_effective_ctx_with_server()
                 self._max_context_length = (
                     max_available_ctx if max_available_ctx > 0 else self._effective_context_length
                 )
@@ -4468,6 +4488,64 @@ class LlamaCppBackend:
         logger.error(f"llama-server health check timed out after {timeout}s")
         return False
 
+    @staticmethod
+    def _ctx_integrity_flags(
+        n_parallel: int, use_fit: bool, requested_ctx: int, effective_ctx: int, caps: dict
+    ) -> list[str]:
+        """Flags that keep the per-request window equal to the advertised ctx.
+
+        Explicit ``--parallel`` disables llama-server's auto-slots
+        ``--kv-unified`` default, silently splitting ``-c`` into per-slot
+        windows of ``-c / N``; restore the shared pool so one request can use
+        the full context. With ``--fit on``, ``--fit-ctx`` floors the fit step
+        at an explicitly requested ctx (default floor is 4096) so it offloads
+        or fails instead of silently shrinking the window.
+        """
+        flags: list[str] = []
+        if n_parallel > 1 and caps.get("supports_kv_unified"):
+            flags.append("--kv-unified")
+        if use_fit and requested_ctx > 0 and effective_ctx > 0 and caps.get("supports_fit_ctx"):
+            flags.extend(["--fit-ctx", str(effective_ctx)])
+        return flags
+
+    def _query_server_n_ctx(self) -> Optional[int]:
+        """Per-slot context llama-server actually allocated, from ``/props``.
+
+        The memory-fit step or ``--parallel`` slot split can leave this below
+        the requested ``-c``; requests are validated against this value.
+        """
+        url = f"http://127.0.0.1:{self._port}/props"
+        try:
+            resp = httpx.get(url, timeout = 5.0)
+            if resp.status_code != 200:
+                return None
+            settings = resp.json().get("default_generation_settings") or {}
+            n_ctx = settings.get("n_ctx")
+            return int(n_ctx) if n_ctx else None
+        except Exception:
+            return None
+
+    def _reconcile_effective_ctx_with_server(self) -> None:
+        """Adopt the server's real ``n_ctx`` when it is below Studio's value.
+
+        Keeps ``context_length`` (load response, status route, passthrough
+        ``max_tokens`` ceiling) honest; clients sized to the requested value
+        would otherwise hit ``exceed_context_size_error`` 400s early.
+        """
+        actual_n_ctx = self._query_server_n_ctx()
+        if not actual_n_ctx or actual_n_ctx <= 0:
+            return
+        if self._effective_context_length and actual_n_ctx < self._effective_context_length:
+            logger.warning(
+                "llama-server allocated a smaller per-request context than "
+                f"requested ({self._effective_context_length} -> {actual_n_ctx}; "
+                "memory fit or --parallel slot split); clients must treat "
+                f"{actual_n_ctx} as the real context window."
+            )
+            self._effective_context_length = actual_n_ctx
+        elif not self._effective_context_length:
+            self._effective_context_length = actual_n_ctx
+
     # ── Message building (OpenAI format) ──────────────────────────
 
     @staticmethod
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index f58a76d16e..f94d5366eb 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -544,8 +544,10 @@ class ChatMessage(BaseModel):
 
         if self.role == "tool":
             # tool_call_id resolution happens at ChatCompletionRequest scope.
-            if not self.content:
-                raise ValueError('role="tool" messages require non-empty "content".')
+            # OpenAI accepts empty tool results (commands with no output);
+            # normalize to "" instead of a 400 agentic clients treat as fatal.
+            if self.content is None or self.content == []:
+                self.content = ""
         elif self.role == "assistant":
             # Post-Stop sentinel: collapse content="" / [] to None.
             if (self.content == "" or self.content == []) and not self.tool_calls:
@@ -692,6 +694,16 @@ class ChatCompletionRequest(BaseModel):
         True,
         description = "[x-unsloth] Auto-detect and fix malformed tool calls from model output.",
     )
+    context_overflow: Optional[Literal["error", "truncate_middle"]] = Field(
+        None,
+        description = (
+            "[x-unsloth] Passthrough behavior when the prompt exceeds the real "
+            "context window. 'error' (default) returns a 400 with "
+            "code=context_length_exceeded. 'truncate_middle' drops middle "
+            "turn-groups (system prompt, first turn, and recent turns kept; "
+            "tool calls stay paired with their results) and retries."
+        ),
+    )
     max_tool_calls_per_message: Optional[int] = Field(
         25,
         ge = 0,
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 0244956b72..9dc9feb920 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -242,6 +242,169 @@ def _openai_passthrough_error(status_code, text) -> "HTTPException":
     )
 
 
+_OVERFLOW_TRUNCATE_MAX_RETRIES = 3
+# Truncated-prompt share of the real window; the rest is generation headroom
+# so a near-full prompt cannot cut a tool call mid-JSON at the wall.
+_OVERFLOW_PROMPT_TARGET_FRACTION = 0.75
+
+
+def _overflow_truncation_requested(payload) -> bool:
+    """True when the request (or the UNSLOTH_CONTEXT_OVERFLOW server default,
+    for clients that cannot send custom fields) opted into truncation."""
+    requested = getattr(payload, "context_overflow", None)
+    if requested is not None:
+        return requested == "truncate_middle"
+    return os.environ.get("UNSLOTH_CONTEXT_OVERFLOW", "").strip().lower() == "truncate_middle"
+
+
+def _parse_overflow_counts(err_text: str):
+    """(n_prompt_tokens, n_ctx) from an exceed_context_size_error body, or
+    None. Tolerates \\" around keys (body may be a re-wrapped JSON string)."""
+    m_prompt = _re.search(r'n_prompt_tokens\\?"?\s*:\s*(\d+)', err_text)
+    m_ctx = _re.search(r'n_ctx\\?"?\s*:\s*(\d+)', err_text)
+    if m_prompt and m_ctx:
+        return int(m_prompt.group(1)), int(m_ctx.group(1))
+    return None
+
+
+def _estimate_message_tokens(msg: dict) -> int:
+    try:
+        return max(1, len(json.dumps(msg, ensure_ascii = False)) // 4)
+    except Exception:
+        return 1
+
+
+def _truncate_middle_messages(messages: list, keep_ratio: float):
+    """Drop whole turn-groups from the middle of an OpenAI message list.
+
+    Always kept: leading system message(s), the first group (task anchor),
+    and the trailing groups. A group is a user message, or an assistant
+    message plus its following tool results, so surviving tool_calls stay
+    paired with their results as chat templates require.
+    Returns (new_messages, dropped_message_count).
+    """
+    if not messages or keep_ratio >= 1.0:
+        return messages, 0
+
+    head: list = []
+    idx = 0
+    while idx < len(messages) and messages[idx].get("role") in ("system", "developer"):
+        head.append(messages[idx])
+        idx += 1
+
+    groups: list[list] = []
+    for msg in messages[idx:]:
+        role = msg.get("role")
+        if role == "tool" and groups:
+            groups[-1].append(msg)
+        elif role == "tool":
+            groups.append([msg])  # orphan tool result; treat as its own group
+        else:
+            groups.append([msg])
+
+    # Anchor group plus the last 3 groups stay.
+    protected_tail = min(3, max(1, len(groups) - 1))
+    if len(groups) <= 1 + protected_tail:
+        return messages, 0
+
+    total_est = sum(_estimate_message_tokens(m) for m in messages)
+    target_est = int(total_est * keep_ratio)
+
+    anchor = groups[0]
+    middle = groups[1:-protected_tail]
+    tail = groups[-protected_tail:]
+
+    current_est = total_est
+    kept_middle: list[list] = list(middle)
+    dropped = 0
+    # Drop oldest-first until the estimate fits the target.
+    while kept_middle and current_est > target_est:
+        victim = kept_middle.pop(0)
+        dropped += len(victim)
+        current_est -= sum(_estimate_message_tokens(m) for m in victim)
+
+    if dropped == 0:
+        return messages, 0
+
+    new_messages = head + anchor
+    for grp in kept_middle:
+        new_messages.extend(grp)
+    for grp in tail:
+        new_messages.extend(grp)
+    return new_messages, dropped
+
+
+_CLIP_MARKER = "\n[... truncated by context_overflow=truncate_middle ...]\n"
+# Generous head+tail first; cut harder if the estimate still misses the target.
+_CLIP_KEEP_CHARS = (1500, 400)
+
+
+def _clip_long_contents(messages: list, target_est: int) -> int:
+    """Clip oversized string contents middle-out until ``target_est`` is met.
+
+    Tool results first, then earlier user turns, the final message last.
+    Message count and roles never change, so tool pairing holds even when
+    group-dropping could not free enough. Returns messages clipped.
+    """
+
+    def _candidates():
+        tools = [m for m in messages if m.get("role") == "tool"]
+        users = [m for m in messages[:-1] if m.get("role") == "user"]
+        last = [messages[-1]] if messages else []
+        return tools + users + last
+
+    clipped = 0
+    for keep in _CLIP_KEEP_CHARS:
+        for msg in _candidates():
+            if sum(_estimate_message_tokens(m) for m in messages) <= target_est:
+                return clipped
+            content = msg.get("content")
+            if not isinstance(content, str) or len(content) <= 2 * keep + len(_CLIP_MARKER):
+                continue
+            msg["content"] = content[:keep] + _CLIP_MARKER + content[-keep:]
+            clipped += 1
+    return clipped
+
+
+def _apply_overflow_truncation(body: dict, err_text: str) -> bool:
+    """Shrink a passthrough body after an upstream context overflow: drop
+    middle turn-groups, clip still-oversized contents, clamp ``max_tokens``
+    to the generation headroom. Returns False when nothing could shrink."""
+    counts = _parse_overflow_counts(err_text)
+    messages = body.get("messages") or []
+    total_est = sum(_estimate_message_tokens(m) for m in messages)
+    if counts:
+        n_prompt, n_ctx = counts
+        keep_ratio = min(0.95, (_OVERFLOW_PROMPT_TARGET_FRACTION * n_ctx) / max(1, n_prompt))
+        # Scale the server-token target into char-estimate units.
+        target_est = int(total_est * keep_ratio)
+    else:
+        n_ctx = None
+        keep_ratio = 0.6  # no counts in the error; cut conservatively
+        target_est = int(total_est * keep_ratio)
+
+    new_messages, dropped = _truncate_middle_messages(messages, keep_ratio)
+    if dropped:
+        body["messages"] = new_messages
+    clipped = 0
+    if sum(_estimate_message_tokens(m) for m in body.get("messages") or []) > target_est:
+        clipped = _clip_long_contents(body.get("messages") or [], target_est)
+    if not dropped and not clipped:
+        return False
+    if n_ctx:
+        headroom = max(1024, int(n_ctx * (1.0 - _OVERFLOW_PROMPT_TARGET_FRACTION)))
+        cur_max = body.get("max_tokens")
+        body["max_tokens"] = min(cur_max, headroom) if cur_max else headroom
+    logger.warning(
+        "context_overflow=truncate_middle: dropped %d middle messages, clipped "
+        "%d contents (keep_ratio %.2f); retrying within the real window",
+        dropped,
+        clipped,
+        keep_ratio,
+    )
+    return True
+
+
 def _anthropic_stream_error_event(exc):
     """Anthropic in-band SSE ``error`` event for a mid-stream failure, or ``None``
     to fall through to a normal message_delta finish. Returns an event only for a
@@ -4456,26 +4619,35 @@ def _openai_model_objects() -> list[dict]:
     # Check GGUF backend
     llama_backend = get_llama_cpp_backend()
     if llama_backend.is_loaded:
-        models.append(
-            {
-                "id": llama_backend.model_identifier,
-                "object": "model",
-                "created": _created,
-                "owned_by": "local",
-            }
-        )
+        entry = {
+            "id": llama_backend.model_identifier,
+            "object": "model",
+            "created": _created,
+            "owned_by": "local",
+        }
+        # Extension fields: the real per-request window (post /props readback)
+        # so clients can budget/compact against the enforced limit.
+        if llama_backend.context_length:
+            entry["context_length"] = llama_backend.context_length
+        if llama_backend.max_context_length:
+            entry["max_context_length"] = llama_backend.max_context_length
+        models.append(entry)
 
     # Check Unsloth backend
     backend = get_inference_backend()
     if backend.active_model_name:
-        models.append(
-            {
-                "id": backend.active_model_name,
-                "object": "model",
-                "created": _created,
-                "owned_by": "local",
-            }
+        entry = {
+            "id": backend.active_model_name,
+            "object": "model",
+            "created": _created,
+            "owned_by": "local",
+        }
+        _sf_ctx = getattr(backend, "context_length", None) or getattr(
+            backend, "max_seq_length", None
         )
+        if _sf_ctx:
+            entry["context_length"] = _sf_ctx
+        models.append(entry)
 
     return models
 
@@ -6822,27 +6994,32 @@ async def _openai_passthrough_stream(
             limits = httpx.Limits(max_keepalive_connections = 0),
         )
         resp = None
-        try:
-            req = client.build_request("POST", target_url, json = body)
-            resp = await client.send(req, stream = True)
-        except httpx.RequestError as e:
-            # llama-server subprocess crashed / starting / unreachable.
-            logger.error("openai passthrough stream: upstream unreachable: %s", e)
-            if resp is not None:
+        _truncate_budget = (
+            _OVERFLOW_TRUNCATE_MAX_RETRIES if _overflow_truncation_requested(payload) else 0
+        )
+        while True:
+            try:
+                req = client.build_request("POST", target_url, json = body)
+                resp = await client.send(req, stream = True)
+            except httpx.RequestError as e:
+                # llama-server subprocess crashed / starting / unreachable.
+                logger.error("openai passthrough stream: upstream unreachable: %s", e)
+                if resp is not None:
+                    try:
+                        await resp.aclose()
+                    except Exception:
+                        pass
                 try:
-                    await resp.aclose()
+                    await client.aclose()
                 except Exception:
                     pass
-            try:
-                await client.aclose()
-            except Exception:
-                pass
-            raise HTTPException(
-                status_code = 502,
-                detail = _friendly_error(e),
-            )
+                raise HTTPException(
+                    status_code = 502,
+                    detail = _friendly_error(e),
+                )
 
-        if resp.status_code != 200:
+            if resp.status_code == 200:
+                break
             err_bytes = await resp.aread()
             err_text = err_bytes.decode("utf-8", errors = "replace")
             logger.error(
@@ -6855,6 +7032,14 @@ async def _openai_passthrough_stream(
                 await resp.aclose()
             except Exception:
                 pass
+            # Opt-in overflow policy: shrink and retry instead of a fatal 400.
+            if (
+                _truncate_budget > 0
+                and _classify_llama_generation_error(Exception(err_text))
+                and _apply_overflow_truncation(body, err_text)
+            ):
+                _truncate_budget -= 1
+                continue
             try:
                 await client.aclose()
             except Exception:
@@ -6953,20 +7138,33 @@ async def _openai_passthrough_non_streaming(llama_backend, payload, model_name):
         payload, backend_ctx = llama_backend.context_length, llama_backend = llama_backend
     )
 
-    try:
-        async with httpx.AsyncClient() as client:
-            resp = await client.post(target_url, json = body, timeout = 600)
-    except httpx.RequestError as e:
-        # llama-server subprocess crashed / starting / unreachable. Surface the
-        # same friendly message the sync chat path emits so operators don't see
-        # a bare 500 with no diagnostic.
-        logger.error("openai passthrough non-streaming: upstream unreachable: %s", e)
-        raise HTTPException(
-            status_code = 502,
-            detail = _friendly_error(e),
-        )
+    _truncate_budget = (
+        _OVERFLOW_TRUNCATE_MAX_RETRIES if _overflow_truncation_requested(payload) else 0
+    )
+    while True:
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.post(target_url, json = body, timeout = 600)
+        except httpx.RequestError as e:
+            # llama-server subprocess crashed / starting / unreachable. Surface the
+            # same friendly message the sync chat path emits so operators don't see
+            # a bare 500 with no diagnostic.
+            logger.error("openai passthrough non-streaming: upstream unreachable: %s", e)
+            raise HTTPException(
+                status_code = 502,
+                detail = _friendly_error(e),
+            )
 
-    if resp.status_code != 200:
+        if resp.status_code == 200:
+            break
+        # Opt-in overflow policy: shrink and retry instead of a fatal 400.
+        if (
+            _truncate_budget > 0
+            and _classify_llama_generation_error(Exception(resp.text))
+            and _apply_overflow_truncation(body, resp.text)
+        ):
+            _truncate_budget -= 1
+            continue
         raise _openai_passthrough_error(resp.status_code, resp.text)
 
     # The guided-decoding fence wraps each choice's JSON content in a
diff --git a/studio/backend/tests/test_context_overflow_truncation.py b/studio/backend/tests/test_context_overflow_truncation.py
new file mode 100644
index 0000000000..4f4c240934
--- /dev/null
+++ b/studio/backend/tests/test_context_overflow_truncation.py
@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the opt-in ``context_overflow="truncate_middle"`` passthrough policy.
+
+On ``exceed_context_size_error`` the passthrough drops middle turn-groups and
+retries inside the real window instead of surfacing a fatal 400. Truncation
+keeps the system prompt, the first turn, and recent turns, and never orphans
+a tool result from its tool_calls turn. Also covers ``/v1/models`` exposing
+the real post-readback context window.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from routes.inference import (
+    _apply_overflow_truncation,
+    _clip_long_contents,
+    _CLIP_MARKER,
+    _estimate_message_tokens,
+    _openai_model_objects,
+    _overflow_truncation_requested,
+    _parse_overflow_counts,
+    _truncate_middle_messages,
+)
+import routes.inference as routes_mod
+
+
+# Nick's actual error body from the Discord report logs.
+_NICK_ERROR = (
+    '{"detail":"llama-server error: {\\"error\\":{\\"code\\":400,'
+    '\\"message\\":\\"request (70494 tokens) exceeds the available context size '
+    '(67584 tokens), try increasing it\\",\\"type\\":\\"exceed_context_size_error\\",'
+    '\\"n_prompt_tokens\\":70494,\\"n_ctx\\":67584}}"}'
+)
+
+
+def _tool_turn(i: int, result_chars: int = 400) -> list[dict]:
+    """An assistant tool_calls turn paired with its tool result."""
+    return [
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [
+                {
+                    "id": f"call_{i}",
+                    "type": "function",
+                    "function": {"name": "read", "arguments": f'{{"filePath":"/f{i}"}}'},
+                }
+            ],
+        },
+        {"role": "tool", "tool_call_id": f"call_{i}", "content": "x" * result_chars},
+    ]
+
+
+def _conversation(n_tool_turns: int = 12) -> list[dict]:
+    msgs = [
+        {"role": "system", "content": "You are an agent." * 20},
+        {"role": "user", "content": "Do the big task." * 20},
+    ]
+    for i in range(n_tool_turns):
+        msgs.extend(_tool_turn(i))
+    msgs.append({"role": "assistant", "content": "halfway summary"})
+    msgs.append({"role": "user", "content": "keep going"})
+    return msgs
+
+
+# ---------------------------------------------------------------------------
+# _parse_overflow_counts
+# ---------------------------------------------------------------------------
+
+
+def test_parse_overflow_counts_nick_error():
+    assert _parse_overflow_counts(_NICK_ERROR) == (70494, 67584)
+
+
+def test_parse_overflow_counts_missing_fields():
+    assert _parse_overflow_counts('{"error":"something else"}') is None
+
+
+# ---------------------------------------------------------------------------
+# _truncate_middle_messages
+# ---------------------------------------------------------------------------
+
+
+def test_truncation_drops_middle_keeps_anchors():
+    msgs = _conversation()
+    new, dropped = _truncate_middle_messages(msgs, keep_ratio = 0.5)
+    assert dropped > 0
+    assert len(new) == len(msgs) - dropped
+    # System prompt and task anchor survive.
+    assert new[0]["role"] == "system"
+    assert new[1] == msgs[1]
+    # The most recent turns survive verbatim.
+    assert new[-1] == msgs[-1]
+    assert new[-2] == msgs[-2]
+
+
+def test_truncation_never_orphans_tool_results():
+    msgs = _conversation()
+    new, dropped = _truncate_middle_messages(msgs, keep_ratio = 0.4)
+    assert dropped > 0
+    surviving_call_ids = {
+        tc["id"] for m in new if m.get("role") == "assistant" for tc in (m.get("tool_calls") or [])
+    }
+    for m in new:
+        if m.get("role") == "tool":
+            assert m["tool_call_id"] in surviving_call_ids
+
+
+def test_truncation_reduces_estimated_size_toward_target():
+    msgs = _conversation()
+    total = sum(_estimate_message_tokens(m) for m in msgs)
+    new, dropped = _truncate_middle_messages(msgs, keep_ratio = 0.5)
+    new_total = sum(_estimate_message_tokens(m) for m in new)
+    assert dropped > 0
+    assert new_total < total
+    # Should land at or below the requested share, modulo one whole group.
+    biggest_group = max(
+        _estimate_message_tokens(a) + _estimate_message_tokens(b)
+        for a, b in zip(msgs[2:-2:2], msgs[3:-2:2])
+    )
+    assert new_total <= int(total * 0.5) + biggest_group
+
+
+def test_truncation_noop_when_keep_ratio_full():
+    msgs = _conversation()
+    new, dropped = _truncate_middle_messages(msgs, keep_ratio = 1.0)
+    assert dropped == 0
+    assert new == msgs
+
+
+def test_truncation_noop_when_only_protected_turns_remain():
+    msgs = [
+        {"role": "system", "content": "sys"},
+        {"role": "user", "content": "task"},
+        *_tool_turn(0),
+        {"role": "user", "content": "latest"},
+    ]
+    new, dropped = _truncate_middle_messages(msgs, keep_ratio = 0.1)
+    assert dropped == 0
+    assert new == msgs
+
+
+# ---------------------------------------------------------------------------
+# _apply_overflow_truncation
+# ---------------------------------------------------------------------------
+
+
+def test_apply_overflow_truncation_mutates_body_and_clamps_max_tokens():
+    body = {"messages": _conversation(), "max_tokens": 32000}
+    assert _apply_overflow_truncation(body, _NICK_ERROR) is True
+    assert len(body["messages"]) < len(_conversation())
+    # Generation headroom: max_tokens clamped to the non-prompt share of n_ctx.
+    assert body["max_tokens"] <= max(1024, int(67584 * 0.25))
+
+
+def test_apply_overflow_truncation_returns_false_when_nothing_droppable():
+    body = {
+        "messages": [
+            {"role": "system", "content": "sys"},
+            {"role": "user", "content": "task"},
+            {"role": "user", "content": "latest"},
+        ],
+        "max_tokens": 32000,
+    }
+    assert _apply_overflow_truncation(body, _NICK_ERROR) is False
+
+
+def test_apply_overflow_truncation_clips_giant_protected_tool_results():
+    """One giant burst (few turn-groups, all protected) must still shrink:
+    stage 2 clips oversized tool contents instead of giving up."""
+    msgs = [
+        {"role": "system", "content": "sys"},
+        {"role": "user", "content": "task"},
+        *_tool_turn(0, result_chars = 60000),
+        *_tool_turn(1, result_chars = 60000),
+    ]
+    body = {"messages": msgs, "max_tokens": 32000}
+    n_before = len(msgs)
+    assert _apply_overflow_truncation(body, _NICK_ERROR) is True
+    # No message disappeared (pairing intact), but contents were clipped.
+    assert len(body["messages"]) == n_before
+    clipped = [m for m in body["messages"] if _CLIP_MARKER in str(m.get("content"))]
+    assert clipped, "expected at least one clipped tool result"
+    surviving_call_ids = {
+        tc["id"]
+        for m in body["messages"]
+        if m.get("role") == "assistant"
+        for tc in (m.get("tool_calls") or [])
+    }
+    for m in body["messages"]:
+        if m.get("role") == "tool":
+            assert m["tool_call_id"] in surviving_call_ids
+
+
+def test_clip_long_contents_reaches_target_and_keeps_structure():
+    msgs = [
+        {"role": "system", "content": "sys"},
+        {"role": "user", "content": "task"},
+        *_tool_turn(0, result_chars = 40000),
+        {"role": "user", "content": "latest question"},
+    ]
+    total = sum(_estimate_message_tokens(m) for m in msgs)
+    clipped = _clip_long_contents(msgs, target_est = total // 4)
+    assert clipped >= 1
+    assert sum(_estimate_message_tokens(m) for m in msgs) <= total // 4
+    # Roles and count unchanged; the short final user message untouched.
+    assert [m["role"] for m in msgs] == ["system", "user", "assistant", "tool", "user"]
+    assert msgs[-1]["content"] == "latest question"
+
+
+def test_overflow_truncation_requested_reads_field(monkeypatch):
+    monkeypatch.delenv("UNSLOTH_CONTEXT_OVERFLOW", raising = False)
+
+    class _P:
+        context_overflow = "truncate_middle"
+
+    class _Q:
+        context_overflow = None
+
+    assert _overflow_truncation_requested(_P()) is True
+    assert _overflow_truncation_requested(_Q()) is False
+    assert _overflow_truncation_requested(object()) is False
+
+
+def test_overflow_truncation_server_default_env(monkeypatch):
+    """UNSLOTH_CONTEXT_OVERFLOW enables the policy for clients that cannot
+    send custom body fields; an explicit per-request 'error' still wins."""
+
+    class _Unset:
+        context_overflow = None
+
+    class _ExplicitError:
+        context_overflow = "error"
+
+    monkeypatch.setenv("UNSLOTH_CONTEXT_OVERFLOW", "truncate_middle")
+    assert _overflow_truncation_requested(_Unset()) is True
+    assert _overflow_truncation_requested(_ExplicitError()) is False
+    monkeypatch.setenv("UNSLOTH_CONTEXT_OVERFLOW", "error")
+    assert _overflow_truncation_requested(_Unset()) is False
+
+
+# ---------------------------------------------------------------------------
+# /v1/models context metadata
+# ---------------------------------------------------------------------------
+
+
+class _FakeLlamaBackend:
+    is_loaded = True
+    model_identifier = "unsloth/Qwen3.6-27B-GGUF"
+    context_length = 67584
+    max_context_length = 262144
+
+
+class _FakeEmptyBackend:
+    active_model_name = None
+
+
+def test_v1_models_exposes_real_context_window(monkeypatch):
+    monkeypatch.setattr(routes_mod, "get_llama_cpp_backend", lambda: _FakeLlamaBackend())
+    monkeypatch.setattr(routes_mod, "get_inference_backend", lambda: _FakeEmptyBackend())
+    models = _openai_model_objects()
+    assert len(models) == 1
+    entry = models[0]
+    assert entry["id"] == "unsloth/Qwen3.6-27B-GGUF"
+    # The REAL (post /props readback) window, not the requested one.
+    assert entry["context_length"] == 67584
+    assert entry["max_context_length"] == 262144
diff --git a/studio/backend/tests/test_llama_cpp_props_readback.py b/studio/backend/tests/test_llama_cpp_props_readback.py
new file mode 100644
index 0000000000..d87c05f2c6
--- /dev/null
+++ b/studio/backend/tests/test_llama_cpp_props_readback.py
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the post-launch /props context readback.
+
+llama-server's memory-fit step or --parallel slot split can allocate less
+context than the requested -c while Studio keeps advertising the requested
+value; clients sized to it then die on exceed_context_size_error 400s.
+``_reconcile_effective_ctx_with_server`` must adopt the server's real
+``default_generation_settings.n_ctx`` whenever it is smaller.
+
+Stubbed httpx; no subprocess, GPU, or network. Cross-platform.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import types as _types
+from pathlib import Path
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Stub heavy/unavailable deps before importing the module under test.
+# Mirrors test_llama_cpp_context_fit.py.
+# ---------------------------------------------------------------------------
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+# Prefer the real modules so importing this file first cannot poison later
+# test modules with stubs; only stub what the environment genuinely lacks.
+try:
+    import loggers  # noqa: F401
+except ImportError:
+    _loggers_stub = _types.ModuleType("loggers")
+    _loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
+    sys.modules.setdefault("loggers", _loggers_stub)
+
+try:
+    import structlog  # noqa: F401
+except ImportError:
+    sys.modules.setdefault("structlog", _types.ModuleType("structlog"))
+
+try:
+    import httpx  # noqa: F401
+except ImportError:
+    _httpx_stub = _types.ModuleType("httpx")
+    for _exc_name in (
+        "ConnectError",
+        "TimeoutException",
+        "ReadTimeout",
+        "ReadError",
+        "RemoteProtocolError",
+        "CloseError",
+        "WriteError",
+        "HTTPError",
+    ):
+        setattr(_httpx_stub, _exc_name, type(_exc_name, (Exception,), {}))
+
+    class _FakeTimeout:
+        def __init__(self, *a, **kw):
+            pass
+
+    _httpx_stub.Timeout = _FakeTimeout
+    _httpx_stub.Client = type(
+        "Client",
+        (),
+        {
+            "__init__": lambda self, **kw: None,
+            "__enter__": lambda self: self,
+            "__exit__": lambda self, *a: None,
+        },
+    )
+    _httpx_stub.get = lambda *a, **kw: (_ for _ in ()).throw(RuntimeError("unstubbed httpx.get"))
+    sys.modules.setdefault("httpx", _httpx_stub)
+
+from core.inference.llama_cpp import LlamaCppBackend
+import core.inference.llama_cpp as llama_cpp_mod
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _FakeResponse:
+    def __init__(
+        self,
+        status_code = 200,
+        body = None,
+    ):
+        self.status_code = status_code
+        self._body = body or {}
+
+    def json(self):
+        return self._body
+
+
+def _make_backend(effective_ctx = 98304, port = 51234):
+    inst = LlamaCppBackend.__new__(LlamaCppBackend)
+    inst._port = port
+    inst._effective_context_length = effective_ctx
+    inst._context_length = 262144
+    return inst
+
+
+def _stub_props(
+    monkeypatch,
+    status_code = 200,
+    body = None,
+    exc = None,
+):
+    def fake_get(url, timeout = None):
+        assert url.endswith("/props")
+        if exc is not None:
+            raise exc
+        return _FakeResponse(status_code, body)
+
+    monkeypatch.setattr(llama_cpp_mod.httpx, "get", fake_get, raising = False)
+
+
+# ---------------------------------------------------------------------------
+# _query_server_n_ctx parsing
+# ---------------------------------------------------------------------------
+
+
+def test_query_n_ctx_reads_default_generation_settings(monkeypatch):
+    _stub_props(
+        monkeypatch,
+        body = {"default_generation_settings": {"n_ctx": 67584}},
+    )
+    assert _make_backend()._query_server_n_ctx() == 67584
+
+
+def test_query_n_ctx_non_200_returns_none(monkeypatch):
+    _stub_props(monkeypatch, status_code = 503)
+    assert _make_backend()._query_server_n_ctx() is None
+
+
+def test_query_n_ctx_missing_key_returns_none(monkeypatch):
+    _stub_props(monkeypatch, body = {"default_generation_settings": {}})
+    assert _make_backend()._query_server_n_ctx() is None
+
+
+def test_query_n_ctx_swallows_transport_errors(monkeypatch):
+    _stub_props(monkeypatch, exc = RuntimeError("connection refused"))
+    assert _make_backend()._query_server_n_ctx() is None
+
+
+# ---------------------------------------------------------------------------
+# _reconcile_effective_ctx_with_server decisions
+# ---------------------------------------------------------------------------
+
+
+def test_fit_shrunk_ctx_overwrites_advertised_value(monkeypatch):
+    """The Nick repro: requested/advertised 98304, server really at 67584."""
+    inst = _make_backend(effective_ctx = 98304)
+    _stub_props(
+        monkeypatch,
+        body = {"default_generation_settings": {"n_ctx": 67584}},
+    )
+    inst._reconcile_effective_ctx_with_server()
+    assert inst._effective_context_length == 67584
+    assert inst.context_length == 67584
+
+
+def test_matching_ctx_is_left_alone(monkeypatch):
+    inst = _make_backend(effective_ctx = 98304)
+    _stub_props(
+        monkeypatch,
+        body = {"default_generation_settings": {"n_ctx": 98304}},
+    )
+    inst._reconcile_effective_ctx_with_server()
+    assert inst._effective_context_length == 98304
+
+
+def test_larger_server_ctx_does_not_inflate_advertised_value(monkeypatch):
+    """Never advertise more than the user asked for, even if the server could."""
+    inst = _make_backend(effective_ctx = 32768)
+    _stub_props(
+        monkeypatch,
+        body = {"default_generation_settings": {"n_ctx": 65536}},
+    )
+    inst._reconcile_effective_ctx_with_server()
+    assert inst._effective_context_length == 32768
+
+
+def test_unset_effective_ctx_adopts_server_value(monkeypatch):
+    inst = _make_backend(effective_ctx = None)
+    inst._context_length = None
+    _stub_props(
+        monkeypatch,
+        body = {"default_generation_settings": {"n_ctx": 40960}},
+    )
+    inst._reconcile_effective_ctx_with_server()
+    assert inst._effective_context_length == 40960
+
+
+def test_props_failure_keeps_studio_value(monkeypatch):
+    """A flaky /props must never wipe the computed context."""
+    inst = _make_backend(effective_ctx = 98304)
+    _stub_props(monkeypatch, exc = RuntimeError("boom"))
+    inst._reconcile_effective_ctx_with_server()
+    assert inst._effective_context_length == 98304
+
+
+# ---------------------------------------------------------------------------
+# _ctx_integrity_flags: keep the per-request window equal to the advertised ctx
+# ---------------------------------------------------------------------------
+
+_CAPS_ALL = {"supports_kv_unified": True, "supports_fit_ctx": True}
+_CAPS_NONE = {"supports_kv_unified": False, "supports_fit_ctx": False}
+
+
+def test_kv_unified_added_for_multi_slot():
+    """Explicit --parallel N disables llama-server's auto-slots kv-unified
+    default, splitting -c into per-slot windows of -c/N; Studio must restore
+    the shared pool so one request can use the full advertised context."""
+    flags = LlamaCppBackend._ctx_integrity_flags(4, False, 98304, 98304, _CAPS_ALL)
+    assert "--kv-unified" in flags
+
+
+def test_kv_unified_skipped_for_single_slot_or_old_build():
+    assert "--kv-unified" not in LlamaCppBackend._ctx_integrity_flags(
+        1, False, 98304, 98304, _CAPS_ALL
+    )
+    assert "--kv-unified" not in LlamaCppBackend._ctx_integrity_flags(
+        4, False, 98304, 98304, _CAPS_NONE
+    )
+
+
+def test_fit_ctx_floors_explicit_request_under_fit():
+    flags = LlamaCppBackend._ctx_integrity_flags(1, True, 98304, 98304, _CAPS_ALL)
+    assert flags[flags.index("--fit-ctx") + 1] == "98304"
+
+
+def test_fit_ctx_skipped_without_fit_or_explicit_ctx_or_support():
+    assert "--fit-ctx" not in LlamaCppBackend._ctx_integrity_flags(
+        1, False, 98304, 98304, _CAPS_ALL
+    )
+    assert "--fit-ctx" not in LlamaCppBackend._ctx_integrity_flags(1, True, 0, 262144, _CAPS_ALL)
+    assert "--fit-ctx" not in LlamaCppBackend._ctx_integrity_flags(
+        1, True, 98304, 98304, _CAPS_NONE
+    )
+
+
+def test_probe_missing_binary_reports_new_capabilities_false():
+    info = LlamaCppBackend.probe_server_capabilities(binary = "/nonexistent/llama-server")
+    assert info["found"] is False
+    assert info["supports_kv_unified"] is False
+    assert info["supports_fit_ctx"] is False
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index d8a965c1f2..1d994b46c0 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -166,10 +166,11 @@ class TestChatMessageToolRoles:
         with pytest.raises(ValidationError):
             ChatMessage(role = "user", content = [])
 
-    def test_tool_empty_content_rejected(self):
-        with pytest.raises(ValidationError) as exc_info:
-            ChatMessage(role = "tool", tool_call_id = "call_1", content = "")
-        assert "content" in str(exc_info.value)
+    def test_tool_empty_content_accepted(self):
+        # Empty tool output (mkdir, git add, ...) is routine in agentic loops;
+        # OpenAI and llama-server both accept it, so Studio must not 400.
+        msg = ChatMessage(role = "tool", tool_call_id = "call_1", content = "")
+        assert msg.content == ""
 
     def test_assistant_without_content_or_tool_calls_tolerated(self):
         # Stop-button leaves an empty assistant turn; tolerate for replay.
diff --git a/studio/backend/tests/test_tool_message_empty_content.py b/studio/backend/tests/test_tool_message_empty_content.py
new file mode 100644
index 0000000000..d63b16ce80
--- /dev/null
+++ b/studio/backend/tests/test_tool_message_empty_content.py
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Empty ``role="tool"`` content must be accepted on the OpenAI-compat surface.
+
+Agentic clients send ``content: ""`` when a command produced no output;
+OpenAI and llama-server both accept it. Studio used to 400, which standard
+clients treat as non-retryable and kill the session. The validator must
+normalize empty/missing tool content to ``""`` instead of raising.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
+if _BACKEND_DIR not in sys.path:
+    sys.path.insert(0, _BACKEND_DIR)
+
+from models.inference import ChatMessage
+
+
+def test_tool_message_empty_string_content_is_accepted():
+    msg = ChatMessage(role = "tool", content = "", tool_call_id = "call_1")
+    assert msg.content == ""
+
+
+def test_tool_message_none_content_normalizes_to_empty_string():
+    msg = ChatMessage(role = "tool", content = None, tool_call_id = "call_1")
+    assert msg.content == ""
+
+
+def test_tool_message_empty_list_content_normalizes_to_empty_string():
+    msg = ChatMessage(role = "tool", content = [], tool_call_id = "call_1")
+    assert msg.content == ""
+
+
+def test_tool_message_real_content_is_preserved():
+    msg = ChatMessage(role = "tool", content = "ok", tool_call_id = "call_1")
+    assert msg.content == "ok"
+
+
+def test_user_message_still_requires_content():
+    with pytest.raises(ValueError):
+        ChatMessage(role = "user", content = None)
+
+
+def test_assistant_empty_content_still_collapses_to_none():
+    msg = ChatMessage(role = "assistant", content = "")
+    assert msg.content is None

From 3733e0b2741e666ebdd677424c2741c348dc9cfc Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 07:50:13 -0700
Subject: [PATCH 206/222] fix(studio): surface live step with null loss through
 the SSE progress stream (#6206)

* fix(studio): surface live step with null loss through the SSE progress stream

The metric histories skip non-finite steps, so during a NaN stretch the
SSE live loop and final complete event replayed the last finite
step/loss pair. Follow the live progress step when it is ahead of the
history tail and report its loss honestly (null until recovery).

Completes the NaN honesty fix for the SSE consumer flagged in review.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply live-step handling to inactive streams and clear the UI loss on null for PR #6206

Fresh /progress connections after a finished run took the inactive branch
which still replayed the last finite step and loss pair; apply the same
live-step correction there. On the frontend, applyProgress kept the stale
currentLoss when a payload advanced the step with a null loss; clear it so
the display shows -- until the loss recovers. Widen the runtime state type
to number | null, which the view layer already handles.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/training/training.py      |   4 +-
 studio/backend/core/training/worker.py        |   2 +-
 studio/backend/routes/training.py             |  31 ++++-
 .../tests/test_training_nan_loss_handling.py  |  30 ++--
 .../test_training_progress_stream_nan.py      | 129 ++++++++++++++++++
 .../training/stores/training-runtime-store.ts |   5 +-
 .../src/features/training/types/runtime.ts    |   3 +-
 7 files changed, 180 insertions(+), 24 deletions(-)
 create mode 100644 studio/backend/tests/test_training_progress_stream_nan.py

diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index 5bd9bc5338..2764101d93 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -534,9 +534,7 @@ class TrainingBackend:
                 except (TypeError, ValueError):
                     logger.debug("Could not convert loss to float: %s", _raw_loss)
                     _safe_loss = None
-                _loss_is_nonfinite = (
-                    _safe_loss is not None and not math.isfinite(_safe_loss)
-                )
+                _loss_is_nonfinite = _safe_loss is not None and not math.isfinite(_safe_loss)
                 if _loss_is_nonfinite:
                     # Drop the value rather than laundering it back to the last
                     # finite loss; clients see loss=None at this step so the NaN
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 427687451c..18b25cb4fe 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1858,7 +1858,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
     # ── 11. Run training ──
     gc.collect()
     mx.synchronize()
-    trainer.train(resume_from_checkpoint=resume_from_checkpoint)
+    trainer.train(resume_from_checkpoint = resume_from_checkpoint)
 
     # ── 12. Save and finalize ──
     if trainer.stop_requested and not _stop_save[0]:
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index 96403e21a5..d7687ffdee 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -665,10 +665,17 @@ async def stream_training_progress(
 
             # If not active, send final state and exit
             if not is_active:
-                if backend.step_history:
-                    final_step = backend.step_history[-1]
+                _live = (getattr(tp, "step", 0) or 0) if tp else 0
+                if backend.step_history or _live > 0:
+                    final_step = backend.step_history[-1] if backend.step_history else 0
                     final_loss = backend.loss_history[-1] if backend.loss_history else None
                     final_lr = backend.lr_history[-1] if backend.lr_history else None
+                    # Histories skip non-finite steps; report the live step with
+                    # loss=None instead of the last finite pair.
+                    if _live > final_step:
+                        final_step = _live
+                        final_loss = getattr(tp, "loss", None)
+                        final_lr = getattr(tp, "learning_rate", final_lr)
                     final_total_steps = getattr(tp, "total_steps", final_step) if tp else final_step
                     final_epoch = getattr(tp, "epoch", None) if tp else None
                     payload = build_progress(
@@ -697,11 +704,18 @@ async def stream_training_progress(
 
         while backend.is_training_active():
             try:
-                if backend.step_history:
-                    current_step = backend.step_history[-1]
+                tp_inner = getattr(getattr(backend, "trainer", None), "training_progress", None)
+                live_step = (getattr(tp_inner, "step", 0) or 0) if tp_inner else 0
+                if backend.step_history or live_step > 0:
+                    current_step = backend.step_history[-1] if backend.step_history else 0
                     current_loss = backend.loss_history[-1] if backend.loss_history else None
                     current_lr = backend.lr_history[-1] if backend.lr_history else None
-                    tp_inner = getattr(getattr(backend, "trainer", None), "training_progress", None)
+                    # Histories skip non-finite steps; follow the live progress
+                    # step and report its loss (None until it recovers).
+                    if live_step > current_step:
+                        current_step = live_step
+                        current_loss = getattr(tp_inner, "loss", None)
+                        current_lr = getattr(tp_inner, "learning_rate", current_lr)
                     current_total_steps = (
                         getattr(tp_inner, "total_steps", current_step) if tp_inner else current_step
                     )
@@ -798,6 +812,13 @@ async def stream_training_progress(
         final_loss = backend.loss_history[-1] if backend.loss_history else None
         final_lr = backend.lr_history[-1] if backend.lr_history else None
         final_tp = getattr(getattr(backend, "trainer", None), "training_progress", None)
+        # If the run ended on a non-finite stretch, report the live step with
+        # loss=None instead of rolling back to the last finite pair.
+        _final_live_step = (getattr(final_tp, "step", 0) or 0) if final_tp else 0
+        if _final_live_step > (final_step if final_step is not None else -1):
+            final_step = _final_live_step
+            final_loss = getattr(final_tp, "loss", None)
+            final_lr = getattr(final_tp, "learning_rate", final_lr)
         final_total_steps = getattr(final_tp, "total_steps", final_step) if final_tp else final_step
         final_epoch = getattr(final_tp, "epoch", None) if final_tp else None
         final_payload = build_progress(
diff --git a/studio/backend/tests/test_training_nan_loss_handling.py b/studio/backend/tests/test_training_nan_loss_handling.py
index 0ab444f9bb..a2dc78bee2 100644
--- a/studio/backend/tests/test_training_nan_loss_handling.py
+++ b/studio/backend/tests/test_training_nan_loss_handling.py
@@ -29,7 +29,11 @@ def _make_backend() -> TrainingBackend:
     return TrainingBackend()
 
 
-def _progress_event(step: int, loss: float, lr: float = 1e-4) -> dict:
+def _progress_event(
+    step: int,
+    loss: float,
+    lr: float = 1e-4,
+) -> dict:
     return {
         "type": "progress",
         "step": step,
@@ -43,7 +47,7 @@ def _progress_event(step: int, loss: float, lr: float = 1e-4) -> dict:
 class TestNonfiniteLossSoftHandling:
     def test_finite_loss_updates_progress_normally(self):
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=0.97))
+        b._handle_event(_progress_event(step = 1, loss = 0.97))
         assert b._progress.loss == pytest.approx(0.97)
         assert b._progress.error is None
         assert b._should_stop is False
@@ -51,9 +55,9 @@ class TestNonfiniteLossSoftHandling:
 
     def test_nan_loss_clears_progress_loss(self):
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=0.97))
+        b._handle_event(_progress_event(step = 1, loss = 0.97))
         assert b._progress.loss == pytest.approx(0.97)
-        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        b._handle_event(_progress_event(step = 2, loss = float("nan")))
         # Stale finite loss must NOT leak through
         assert b._progress.loss is None
         # Run is not marked failed
@@ -64,7 +68,7 @@ class TestNonfiniteLossSoftHandling:
 
     def test_inf_loss_clears_progress_loss(self):
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=float("inf")))
+        b._handle_event(_progress_event(step = 1, loss = float("inf")))
         assert b._progress.loss is None
         assert b._progress.error is None
         assert b._should_stop is False
@@ -72,7 +76,7 @@ class TestNonfiniteLossSoftHandling:
 
     def test_negative_inf_loss_clears_progress_loss(self):
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=float("-inf")))
+        b._handle_event(_progress_event(step = 1, loss = float("-inf")))
         assert b._progress.loss is None
         assert b._progress.error is None
         assert b._should_stop is False
@@ -82,12 +86,12 @@ class TestNonfiniteLossSoftHandling:
         """Subsequent NaN events must not re-fire the warning flag setter.
         The flag should already be True after the first NaN."""
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=0.97))
-        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        b._handle_event(_progress_event(step = 1, loss = 0.97))
+        b._handle_event(_progress_event(step = 2, loss = float("nan")))
         assert b._progress._nonfinite_loss_warned is True
         # Further NaN steps don't change anything we care about
-        b._handle_event(_progress_event(step=3, loss=float("nan")))
-        b._handle_event(_progress_event(step=4, loss=float("nan")))
+        b._handle_event(_progress_event(step = 3, loss = float("nan")))
+        b._handle_event(_progress_event(step = 4, loss = float("nan")))
         assert b._progress._nonfinite_loss_warned is True
         assert b._progress.loss is None
         assert b._progress.error is None
@@ -97,10 +101,10 @@ class TestNonfiniteLossSoftHandling:
         """If a NaN step is followed by a finite step, progress.loss must
         reflect the new finite value (not stay stuck at None)."""
         b = _make_backend()
-        b._handle_event(_progress_event(step=1, loss=0.97))
-        b._handle_event(_progress_event(step=2, loss=float("nan")))
+        b._handle_event(_progress_event(step = 1, loss = 0.97))
+        b._handle_event(_progress_event(step = 2, loss = float("nan")))
         assert b._progress.loss is None
-        b._handle_event(_progress_event(step=3, loss=0.85))
+        b._handle_event(_progress_event(step = 3, loss = 0.85))
         assert b._progress.loss == pytest.approx(0.85)
         # Warning flag stays set (we don't reset it on recovery)
         assert b._progress._nonfinite_loss_warned is True
diff --git a/studio/backend/tests/test_training_progress_stream_nan.py b/studio/backend/tests/test_training_progress_stream_nan.py
new file mode 100644
index 0000000000..899527a04d
--- /dev/null
+++ b/studio/backend/tests/test_training_progress_stream_nan.py
@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The SSE progress stream must follow the live progress step during
+non-finite-loss stretches (loss reported as null) instead of replaying the
+last finite step/loss pair from the metric histories, which skip NaN steps."""
+
+import asyncio
+import json
+import sys
+import types
+
+import pytest
+
+if "structlog" not in sys.modules:
+
+    class _DummyLogger:
+        def __getattr__(self, _name):
+            return lambda *args, **kwargs: None
+
+    sys.modules["structlog"] = types.SimpleNamespace(
+        BoundLogger = _DummyLogger,
+        get_logger = lambda *args, **kwargs: _DummyLogger(),
+    )
+
+import routes.training as rt
+
+
+class _Progress:
+    def __init__(self):
+        self.step = 5
+        self.total_steps = 10
+        self.loss = None  # cleared by the NaN honesty fix in core training
+        self.learning_rate = 8e-5
+        self.epoch = 0.1
+        self.grad_norm = None
+        self.num_tokens = None
+        self.eval_loss = None
+        self.elapsed_seconds = None
+        self.eta_seconds = None
+
+
+class _FakeBackend:
+    """Finite history stops at step 2; live progress is at step 5 with NaN
+    (loss=None). Active for a few polls, then done."""
+
+    def __init__(self, active_polls = 2):
+        self.current_job_id = "job-1"
+        self.step_history = [1, 2]
+        self.loss_history = [2.0, 1.5]
+        self.lr_history = [1e-4, 9e-5]
+        self.eval_enabled = False
+        self._active_calls = 0
+        self._active_polls = active_polls
+        self.trainer = types.SimpleNamespace(training_progress = _Progress())
+
+    def is_training_active(self):
+        self._active_calls += 1
+        return self._active_calls <= self._active_polls
+
+
+class _FakeRequest:
+    headers = {}
+
+
+def _collect_events(response, timeout = 15):
+    async def _drain():
+        chunks = []
+        async for chunk in response.body_iterator:
+            chunks.append(chunk)
+        return "".join(c.decode() if isinstance(c, bytes) else c for c in chunks)
+
+    return asyncio.run(asyncio.wait_for(_drain(), timeout))
+
+
+def _progress_payloads(raw):
+    payloads = []
+    for block in raw.split("\n\n"):
+        lines = block.strip().splitlines()
+        data = next((l[6:] for l in lines if l.startswith("data: ")), None)
+        if data:
+            payloads.append(json.loads(data))
+    return payloads
+
+
+def test_stream_reports_live_step_with_null_loss_during_nan(monkeypatch):
+    backend = _FakeBackend(active_polls = 2)
+    monkeypatch.setattr(rt, "get_training_backend", lambda: backend)
+
+    response = asyncio.run(rt.stream_training_progress(_FakeRequest(), current_subject = "tester"))
+    raw = _collect_events(response)
+    payloads = _progress_payloads(raw)
+    assert payloads, f"no SSE payloads parsed from: {raw!r}"
+
+    live = [p for p in payloads if p.get("step") == 5]
+    assert live, (
+        "stream never advanced to the live progress step during the NaN "
+        f"stretch; steps seen: {[p.get('step') for p in payloads]}"
+    )
+    assert live[0]["loss"] is None
+    # The stale finite pair must not be re-emitted as the latest progress.
+    stale = [p for p in payloads if p.get("step") == 2 and p.get("loss") == 1.5]
+    assert not stale
+
+
+def test_inactive_stream_completes_with_live_step_and_null_loss(monkeypatch):
+    # Fresh connection after the run already ended during a NaN stretch: the
+    # immediate complete event must not replay the stale finite pair either.
+    backend = _FakeBackend(active_polls = 0)
+    monkeypatch.setattr(rt, "get_training_backend", lambda: backend)
+
+    response = asyncio.run(rt.stream_training_progress(_FakeRequest(), current_subject = "tester"))
+    payloads = _progress_payloads(_collect_events(response))
+    final = payloads[-1]
+    assert final["step"] == 5
+    assert final["loss"] is None
+
+
+def test_stream_uses_finite_history_when_progress_in_sync(monkeypatch):
+    backend = _FakeBackend(active_polls = 2)
+    # Live progress agrees with the history tail: normal finite behavior.
+    backend.trainer.training_progress.step = 2
+    backend.trainer.training_progress.loss = 1.5
+    monkeypatch.setattr(rt, "get_training_backend", lambda: backend)
+
+    response = asyncio.run(rt.stream_training_progress(_FakeRequest(), current_subject = "tester"))
+    payloads = _progress_payloads(_collect_events(response))
+    finite = [p for p in payloads if p.get("step") == 2]
+    assert finite and finite[0]["loss"] == 1.5
diff --git a/studio/frontend/src/features/training/stores/training-runtime-store.ts b/studio/frontend/src/features/training/stores/training-runtime-store.ts
index f1966f03fb..97fbd32d57 100644
--- a/studio/frontend/src/features/training/stores/training-runtime-store.ts
+++ b/studio/frontend/src/features/training/stores/training-runtime-store.ts
@@ -274,7 +274,10 @@ export const useTrainingRuntimeStore = create<TrainingRuntimeStore>()((set) => (
         jobId: payload.job_id || state.jobId,
         currentStep: step,
         totalSteps: Math.max(payload.total_steps, state.totalSteps),
-        currentLoss: currentLoss ?? state.currentLoss,
+        // A null loss at a new step means the backend reported a non-finite
+        // loss; clear the display instead of keeping the stale value.
+        currentLoss:
+          currentLoss ?? (step > state.currentStep ? null : state.currentLoss),
         currentLearningRate: currentLearningRate ?? state.currentLearningRate,
         progressPercent: payload.progress_percent,
         currentEpoch: payload.epoch ?? state.currentEpoch,
diff --git a/studio/frontend/src/features/training/types/runtime.ts b/studio/frontend/src/features/training/types/runtime.ts
index d30c3f75c2..5fd8286d22 100644
--- a/studio/frontend/src/features/training/types/runtime.ts
+++ b/studio/frontend/src/features/training/types/runtime.ts
@@ -90,7 +90,8 @@ export interface TrainingRuntimeState {
   currentStep: number;
   totalSteps: number;
   currentEpoch: number;
-  currentLoss: number;
+  // null while the latest reported loss is non-finite
+  currentLoss: number | null;
   currentLearningRate: number;
   progressPercent: number;
   elapsedSeconds: number | null;

From f64c3c8abaecf017061ff5d9e149542bee29a25b Mon Sep 17 00:00:00 2001
From: Nilay <118994073+NilayYadav@users.noreply.github.com>
Date: Thu, 11 Jun 2026 20:39:34 +0530
Subject: [PATCH 207/222] Studio: add `unsloth chat` CLI command (#6170)

* Studio: add `unsloth chat` CLI command

Interactive chat REPL on the shared Studio backend: trained-model picker
when no model is given, /think and /compare toggles (adapter toggle on
CUDA, side-by-side base-model load on MLX), markdown streaming, and
connect-if-running Studio server mode so models stay warm across
sessions and are shared with the UI.

* fix settings

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix error handling and compare base precision

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix chat CLI backend imports and GGUF drafter loading

* Hide split thinking tags in chat CLI streams

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: imagineer99 <samleejackson0@gmail.com>
---
 pyproject.toml                           |   1 +
 unsloth_cli/__init__.py                  |   2 +
 unsloth_cli/_inference.py                | 417 +++++++++++++++++++++++
 unsloth_cli/commands/chat.py             | 340 ++++++++++++++++++
 unsloth_cli/commands/inference.py        |  87 ++---
 unsloth_cli/tests/test_inference_chat.py | 401 ++++++++++++++++++++++
 6 files changed, 1208 insertions(+), 40 deletions(-)
 create mode 100644 unsloth_cli/_inference.py
 create mode 100644 unsloth_cli/commands/chat.py
 create mode 100644 unsloth_cli/tests/test_inference_chat.py

diff --git a/pyproject.toml b/pyproject.toml
index 79c14c907c..9f6465d3a3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -26,6 +26,7 @@ classifiers = [
 ]
 dependencies = [
     "typer",
+    "rich",
     "pydantic",
     "pyyaml",
     "nest-asyncio",
diff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.py
index e1047a6515..08d7e17e8c 100644
--- a/unsloth_cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -10,6 +10,7 @@ from importlib.metadata import version as package_version, PackageNotFoundError
 
 from unsloth_cli.commands.train import train
 from unsloth_cli.commands.inference import inference
+from unsloth_cli.commands.chat import chat
 from unsloth_cli.commands.export import export, list_checkpoints
 from unsloth_cli.commands.studio import (
     run as studio_run,
@@ -72,6 +73,7 @@ def main(
 
 app.command()(train)
 app.command()(inference)
+app.command()(chat)
 app.command()(export)
 app.command("list-checkpoints")(list_checkpoints)
 app.add_typer(studio_app, name = "studio", help = "Unsloth Studio commands.")
diff --git a/unsloth_cli/_inference.py b/unsloth_cli/_inference.py
new file mode 100644
index 0000000000..5e734ee2a1
--- /dev/null
+++ b/unsloth_cli/_inference.py
@@ -0,0 +1,417 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Model loading and streaming shared by `inference` and `chat`."""
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+_THINK_OPEN = "<think>"
+_THINK_BLOCK = re.compile(rf"{re.escape(_THINK_OPEN)}.*?</think>", re.DOTALL)
+
+
+def ensure_studio_backend_path() -> None:
+    backend_dir = str(Path(__file__).resolve().parents[1] / "studio" / "backend")
+    if backend_dir not in sys.path:
+        sys.path.insert(0, backend_dir)
+
+
+def configure_quiet_logging() -> None:
+    import logging
+
+    import structlog
+
+    # The CLI never configures structlog, so without this every backend INFO
+    # line prints. LOG_LEVEL is exported so the worker subprocess inherits it.
+    level_name = os.environ.setdefault("LOG_LEVEL", "WARNING").upper()
+    level = getattr(logging, level_name, logging.WARNING)
+    structlog.configure(wrapper_class = structlog.make_filtering_bound_logger(level))
+    os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+
+def visible_text(text: str, show_thinking: bool) -> str:
+    if show_thinking:
+        return text
+    text = _THINK_BLOCK.sub("", text)
+    # Hold back an unclosed trailing <think> so reasoning never leaks mid-stream.
+    open_idx = text.find(_THINK_OPEN)
+    if open_idx != -1:
+        text = text[:open_idx]
+    max_prefix = min(len(text), len(_THINK_OPEN) - 1)
+    for size in range(max_prefix, 0, -1):
+        if _THINK_OPEN.startswith(text[-size:]):
+            return text[:-size]
+    return text
+
+
+def stream_to_stdout(stream, show_thinking: bool) -> str:
+    # Backends yield the full text-so-far on each step (llama.cpp ends with a
+    # metadata dict, skipped); print the growing tail, return the raw text.
+    raw = ""
+    shown = ""
+    for chunk in stream:
+        if not isinstance(chunk, str):
+            continue
+        raw = chunk
+        rendered = visible_text(chunk, show_thinking)
+        delta = rendered[len(shown) :]
+        if delta:
+            sys.stdout.write(delta)
+            sys.stdout.flush()
+        shown = rendered
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    return raw
+
+
+def stream_markdown(stream, show_thinking: bool, *, console) -> str:
+    from rich.live import Live
+    from rich.markdown import Markdown
+    from rich.text import Text
+
+    raw = ""
+    with Live(console = console, refresh_per_second = 12, vertical_overflow = "visible") as live:
+        for chunk in stream:
+            if not isinstance(chunk, str):
+                continue
+            raw = chunk
+            visible = visible_text(chunk, show_thinking)
+            live.update(Markdown(visible) if visible.strip() else Text(""))
+    return raw
+
+
+def collect_stream(stream, show_thinking: bool) -> str:
+    raw = ""
+    for chunk in stream:
+        if isinstance(chunk, str):
+            raw = chunk
+    return visible_text(raw, show_thinking)
+
+
+def render_columns(
+    left_label: str,
+    left_text: str,
+    right_label: str,
+    right_text: str,
+    *,
+    console = None,
+) -> None:
+    from rich import box
+    from rich.console import Console
+    from rich.table import Table
+
+    table = Table(box = box.MINIMAL, expand = True, padding = (0, 1), pad_edge = False)
+    table.add_column(left_label, header_style = "bold yellow", ratio = 1, overflow = "fold")
+    table.add_column(right_label, header_style = "bold magenta", ratio = 1, overflow = "fold")
+    table.add_row(left_text or "", right_text or "")
+    (console or Console()).print(table)
+
+
+class ChatBackend:
+    """Uniform stream()/close() over the llama-server and Unsloth backends."""
+
+    def __init__(self, kind: str, backend) -> None:
+        self._kind = kind  # "gguf" | "unsloth"
+        self._backend = backend
+
+    def stream(
+        self,
+        messages: list,
+        *,
+        system_prompt: str,
+        temperature: float,
+        top_p: float,
+        top_k: int,
+        max_new_tokens: int,
+        repetition_penalty: float,
+        enable_thinking: bool,
+        use_adapter: Optional[bool] = None,
+    ):
+        if self._kind == "gguf":
+            # llama-server takes the system prompt as the first message.
+            msgs = list(messages)
+            if system_prompt:
+                msgs = [{"role": "system", "content": system_prompt}, *msgs]
+            return self._backend.generate_chat_completion(
+                messages = msgs,
+                temperature = temperature,
+                top_p = top_p,
+                top_k = top_k,
+                max_tokens = max_new_tokens,
+                repetition_penalty = repetition_penalty,
+                enable_thinking = enable_thinking,
+            )
+        gen_kwargs = dict(
+            messages = messages,
+            system_prompt = system_prompt,
+            temperature = temperature,
+            top_p = top_p,
+            top_k = top_k,
+            max_new_tokens = max_new_tokens,
+            repetition_penalty = repetition_penalty,
+            enable_thinking = enable_thinking,
+        )
+        if use_adapter is not None:
+            return self._backend.generate_with_adapter_control(
+                use_adapter = use_adapter, **gen_kwargs
+            )
+        return self._backend.generate_chat_response(**gen_kwargs)
+
+    def close(self) -> None:
+        # Shut the worker down directly: the graceful unload_model waits for
+        # an ack that compare mode can swallow, hanging exit for minutes.
+        try:
+            if self._kind == "gguf":
+                self._backend.unload_model()
+            else:
+                self._backend._shutdown_subprocess(timeout = 2.0)
+        except Exception:
+            pass
+
+
+def resolve_model_config(model: str, *, hf_token: Optional[str]):
+    ensure_studio_backend_path()
+    from utils.models import ModelConfig
+
+    model_config = ModelConfig.from_identifier(model_id = model, hf_token = hf_token)
+    if not model_config:
+        typer.echo("Could not resolve model config", err = True)
+        raise typer.Exit(code = 1)
+    return model_config
+
+
+def _load_gguf_backend(model_config, *, hf_token, max_seq_length):
+    ensure_studio_backend_path()
+    from core.inference.llama_cpp import LlamaCppBackend
+
+    llama_backend = LlamaCppBackend()
+    common = dict(
+        hf_variant = model_config.gguf_variant,
+        model_identifier = model_config.identifier,
+        is_vision = model_config.is_vision,
+        n_ctx = max_seq_length,
+    )
+    if model_config.gguf_hf_repo:
+        loaded = llama_backend.load_model(
+            hf_repo = model_config.gguf_hf_repo, hf_token = hf_token, **common
+        )
+    else:
+        loaded = llama_backend.load_model(
+            gguf_path = model_config.gguf_file,
+            mmproj_path = model_config.gguf_mmproj_file,
+            mtp_draft_path = model_config.gguf_mtp_file,
+            **common,
+        )
+    if not loaded:
+        typer.echo("Model load failed", err = True)
+        raise typer.Exit(code = 1)
+    return ChatBackend("gguf", llama_backend)
+
+
+def load_chat_backend(
+    model: str,
+    *,
+    hf_token: Optional[str],
+    max_seq_length: int,
+    load_in_4bit: bool,
+    model_config = None,
+    fresh_backend: bool = False,
+):
+    """Load `model` in-process: GGUF via llama-server, else the orchestrator.
+
+    fresh_backend uses a private orchestrator so a second model (compare's
+    base column) can run alongside the main one.
+    """
+    if model_config is None:
+        model_config = resolve_model_config(model, hf_token = hf_token)
+
+    typer.echo(f"Loading {model}", err = True)
+
+    if model_config.is_gguf:
+        return _load_gguf_backend(model_config, hf_token = hf_token, max_seq_length = max_seq_length)
+
+    if fresh_backend:
+        ensure_studio_backend_path()
+        from core.inference import InferenceOrchestrator
+        backend = InferenceOrchestrator()
+    else:
+        ensure_studio_backend_path()
+        from core.inference import get_inference_backend
+        backend = get_inference_backend()
+    if not backend.load_model(
+        config = model_config,
+        max_seq_length = max_seq_length,
+        load_in_4bit = load_in_4bit,
+        hf_token = hf_token,
+    ):
+        typer.echo("Model load failed", err = True)
+        raise typer.Exit(code = 1)
+    return ChatBackend("unsloth", backend)
+
+
+def find_studio_server(timeout: float = 0.4) -> Optional[str]:
+    import urllib.request
+    base = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
+    try:
+        with urllib.request.urlopen(f"{base}/api/health", timeout = timeout):
+            return base
+    except Exception:
+        return None
+
+
+def _studio_token() -> Optional[str]:
+    """Self-issue a JWT: the CLI runs as the same OS user as the server, so it
+    signs with the same stored secret the server validates against."""
+    try:
+        import studio.backend.core  # noqa: F401  puts studio/backend on sys.path
+
+        from studio.backend.auth import storage
+        from studio.backend.auth.authentication import create_access_token
+
+        row = storage.get_connection().execute("SELECT username FROM auth_user LIMIT 1").fetchone()
+        return create_access_token(row[0], desktop = True) if row else None
+    except Exception:
+        return None
+
+
+class HttpChatBackend:
+    """Chat against a running Studio server over its OpenAI-compatible API.
+
+    close() leaves the model loaded on purpose — the next session (or the
+    UI) starts instantly.
+    """
+
+    def __init__(self, base_url: str, token: str) -> None:
+        self._base = base_url
+        self._token = token
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload = None,
+        timeout = None,
+    ):
+        import json
+        import urllib.request
+
+        request = urllib.request.Request(
+            self._base + path,
+            data = None if payload is None else json.dumps(payload).encode(),
+            headers = {
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+            },
+            method = method,
+        )
+        return urllib.request.urlopen(request, timeout = timeout)
+
+    def ensure_loaded(self, model: str, *, hf_token, max_seq_length, load_in_4bit) -> None:
+        typer.echo(f"Loading {model} on the Studio server", err = True)
+        try:
+            self._request(
+                "POST",
+                "/api/inference/load",
+                {
+                    "model_path": model,
+                    "hf_token": hf_token,
+                    "max_seq_length": max_seq_length,
+                    "load_in_4bit": load_in_4bit,
+                },
+            ).close()
+        except Exception as exc:
+            typer.echo(f"Model load failed: {exc}", err = True)
+            raise typer.Exit(code = 1)
+
+    def stream(
+        self,
+        messages: list,
+        *,
+        system_prompt: str,
+        temperature: float,
+        top_p: float,
+        top_k: int,
+        max_new_tokens: int,
+        repetition_penalty: float,
+        enable_thinking: bool,
+        use_adapter: Optional[bool] = None,
+    ):
+        import json
+
+        msgs = list(messages)
+        if system_prompt:
+            msgs = [{"role": "system", "content": system_prompt}, *msgs]
+        resp = self._request(
+            "POST",
+            "/v1/chat/completions",
+            {
+                "model": "default",
+                "messages": msgs,
+                "stream": True,
+                "temperature": temperature,
+                "top_p": top_p,
+                "top_k": top_k,
+                "max_tokens": max_new_tokens,
+                "repetition_penalty": repetition_penalty,
+                "enable_thinking": enable_thinking,
+            },
+        )
+
+        def cumulative():
+            # Accumulate SSE deltas into the full-text-so-far convention the
+            # stream helpers expect.
+            text = ""
+            with resp:
+                for raw_line in resp:
+                    line = raw_line.decode("utf-8", "replace").strip()
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[len("data:") :].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        parsed = json.loads(data)
+                    except ValueError:
+                        continue
+                    if "error" in parsed:
+                        raise RuntimeError(
+                            f"Server error: {parsed['error'].get('message', 'Unknown server error')}"
+                        )
+                    try:
+                        delta = parsed["choices"][0]["delta"].get("content")
+                    except (KeyError, IndexError):
+                        continue
+                    if not delta:
+                        continue
+                    text += delta
+                    # An emoji can arrive split across two deltas as lone
+                    # surrogate halves: hold back a trailing half, merge pairs.
+                    visible = text
+                    if "\ud800" <= visible[-1] <= "\udbff":
+                        visible = visible[:-1]
+                    yield visible.encode("utf-16", "surrogatepass").decode("utf-16", "replace")
+
+        return cumulative()
+
+    def close(self) -> None:
+        pass
+
+
+def connect_studio_server(model: str, *, hf_token, max_seq_length, load_in_4bit):
+    """Backend on a running Studio server, or None (caller loads locally)."""
+    base_url = find_studio_server()
+    if not base_url:
+        return None
+    token = _studio_token()
+    if not token:
+        return None
+    backend = HttpChatBackend(base_url, token)
+    backend.ensure_loaded(
+        model, hf_token = hf_token, max_seq_length = max_seq_length, load_in_4bit = load_in_4bit
+    )
+    return backend
diff --git a/unsloth_cli/commands/chat.py b/unsloth_cli/commands/chat.py
new file mode 100644
index 0000000000..c62916bc75
--- /dev/null
+++ b/unsloth_cli/commands/chat.py
@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from unsloth_cli._inference import (
+    collect_stream,
+    configure_quiet_logging,
+    connect_studio_server,
+    ensure_studio_backend_path,
+    load_chat_backend,
+    render_columns,
+    resolve_model_config,
+    stream_markdown,
+    visible_text,
+)
+
+_HELP = (
+    "Commands: /exit (quit), /reset (clear history), "
+    "/think (toggle reasoning), /compare (base vs tuned), /help"
+)
+
+
+def _you_prompt(colors: bool) -> str:
+    # The prompt must go through input(), not a separate print — readline
+    # redraws erase anything they didn't draw, eating the label. GNU readline
+    # wants colors wrapped in \001/\002; libedit (macOS) prints those
+    # literally, so it gets raw ANSI.
+    try:
+        import readline
+    except ImportError:
+        return "\n\x1b[1;36mYou: \x1b[0m" if colors else "\nYou: "
+    libedit = (
+        "libedit" in (readline.__doc__ or "") or getattr(readline, "backend", "") == "editline"
+    )
+    if not colors:
+        return "\nYou: "
+    if libedit:
+        return "\n\x1b[1;36mYou: \x1b[0m"
+    return "\n\001\x1b[1;36m\002You: \001\x1b[0m\002"
+
+
+def _compare_blocked_reason(model_config) -> Optional[str]:
+    if model_config.is_gguf:
+        return (
+            "GGUF models can't toggle adapters — load a LoRA fine-tune "
+            "(transformers backend) to compare base vs tuned."
+        )
+    if not model_config.is_lora:
+        return (
+            "this isn't a LoRA adapter — compare turns the adapter off for the "
+            "'base' column, so there's nothing to compare against."
+        )
+    return None
+
+
+def _get_base_load_in_4bit(model_config) -> bool:
+    """Determine load_in_4bit for base model based on tuned adapter precision."""
+    if not model_config.is_lora or not model_config.path:
+        # Fallback to default if not a LoRA or no path
+        return True
+
+    try:
+        import json
+        from pathlib import Path
+
+        adapter_cfg_path = Path(model_config.path) / "adapter_config.json"
+        if not adapter_cfg_path.exists():
+            return True
+
+        with open(adapter_cfg_path) as f:
+            adapter_cfg = json.load(f)
+
+        training_method = adapter_cfg.get("unsloth_training_method")
+        if training_method == "lora":
+            return False
+        elif training_method == "qlora":
+            return True
+        elif not training_method:
+            # Fallback: check base model name for -bnb-4bit suffix
+            if model_config.base_model and "-bnb-4bit" not in model_config.base_model.lower():
+                return False
+            return True
+        return True
+    except Exception:
+        return True
+
+
+def _compare_needs_second_model() -> bool:
+    # MLX can't toggle the adapter off, so compare loads the base separately.
+    # detect_hardware() would print into the chat (and import torch), so
+    # probe its MLX condition quietly: Apple Silicon with mlx installed.
+    try:
+        from studio.backend.utils.hardware import hardware as hw
+
+        if hw.DEVICE is not None:
+            return hw.DEVICE == hw.DeviceType.MLX
+        if not hw.is_apple_silicon():
+            return False
+        import mlx.core  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _pick_trained_model(console) -> str:
+    ensure_studio_backend_path()
+    from utils.models import scan_trained_models
+
+    trained = scan_trained_models()
+    if not trained:
+        typer.echo(
+            "No trained models found in your outputs folder. "
+            "Pass a model id or path: `unsloth chat <model>`.",
+            err = True,
+        )
+        raise typer.Exit(code = 1)
+
+    console.print("Your trained models (newest first):", style = "bold")
+    for i, (display_name, _, model_type) in enumerate(trained, 1):
+        console.print(f"  {i}. {display_name}  ({model_type})", markup = False)
+
+    while True:
+        try:
+            raw = input(f"Chat with [1-{len(trained)}, Enter = 1]: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            raise typer.Exit(code = 1)
+        if not raw:
+            return trained[0][1]
+        if raw.isdigit() and 1 <= int(raw) <= len(trained):
+            return trained[int(raw) - 1][1]
+        console.print(f"Pick a number between 1 and {len(trained)}.", style = "yellow")
+
+
+def chat(
+    model: Optional[str] = typer.Argument(
+        None, help = "HF model id or local path. Omit to pick one of your trained models."
+    ),
+    hf_token: Optional[str] = typer.Option(
+        None, "--hf-token", envvar = "HF_TOKEN", help = "Hugging Face token if needed."
+    ),
+    temperature: float = typer.Option(0.7, "--temperature"),
+    top_p: float = typer.Option(0.9, "--top-p"),
+    top_k: int = typer.Option(40, "--top-k"),
+    max_new_tokens: int = typer.Option(512, "--max-new-tokens"),
+    repetition_penalty: float = typer.Option(1.1, "--repetition-penalty"),
+    system_prompt: str = typer.Option(
+        "", "--system-prompt", help = "Optional system prompt for the conversation."
+    ),
+    max_seq_length: int = typer.Option(4096, "--max-seq-length"),
+    load_in_4bit: bool = typer.Option(True, "--load-in-4bit/--no-load-in-4bit"),
+    think: bool = typer.Option(
+        False,
+        "--think/--no-think",
+        help = "Start with the model's <think> reasoning shown. Toggle live with /think.",
+    ),
+    compare: bool = typer.Option(
+        False,
+        "--compare/--no-compare",
+        help = "Answer each prompt twice — base vs fine-tuned — side by side. "
+        "Needs a LoRA adapter. Toggle live with /compare.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help = "Show backend and llama-server logs."
+    ),
+    no_server: bool = typer.Option(
+        False,
+        "--no-server",
+        help = "Load the model in-process even if a Studio server is running.",
+    ),
+):
+    """Start an interactive chat with a model (loads once, stays warm)."""
+    if not verbose:
+        configure_quiet_logging()
+
+    console = Console()
+    err = Console(stderr = True)
+
+    if model is None:
+        model = _pick_trained_model(console)
+
+    # Resolve first so --compare can be rejected before the slow load.
+    model_config = resolve_model_config(model, hf_token = hf_token)
+    compare_blocked = _compare_blocked_reason(model_config)
+    if compare and compare_blocked:
+        err.print(f"--compare unavailable: {compare_blocked}", style = "red", markup = False)
+        raise typer.Exit(code = 1)
+
+    load_opts = dict(hf_token = hf_token, max_seq_length = max_seq_length, load_in_4bit = load_in_4bit)
+
+    # Prefer a running Studio server: instant starts, model shared with the UI.
+    chat_backend = None if no_server else connect_studio_server(model, **load_opts)
+    server_mode = chat_backend is not None
+    if server_mode:
+        console.print(
+            "(Studio server connected — model stays warm after /exit)",
+            style = "bright_black",
+        )
+    else:
+        chat_backend = load_chat_backend(model, model_config = model_config, **load_opts)
+
+    name = model_config.display_name or model
+    show_thinking = think
+    compare_mode = compare
+    messages = []
+
+    # Compare's base column: server mode keeps the tuned model remote and
+    # loads the base locally; local MLX (no adapter toggle) does the same;
+    # local CUDA just toggles the adapter on the one loaded model.
+    dual_compare = compare_blocked is None and (server_mode or _compare_needs_second_model())
+    base_backend = None
+
+    def load_base_for_compare():
+        nonlocal base_backend
+        if base_backend is not None:
+            return True
+        base_id = model_config.base_model
+        if not base_id:
+            console.print(
+                "(compare unavailable: this adapter doesn't record its base model)",
+                style = "yellow",
+            )
+            return False
+        console.print(
+            f"(loading base model {base_id} for compare — keeps two models in memory)",
+            style = "bright_black",
+            markup = False,
+        )
+        try:
+            # Use the same precision as the tuned model for fair comparison
+            base_load_opts = dict(load_opts)  # Copy original options
+            base_load_opts["load_in_4bit"] = _get_base_load_in_4bit(model_config)
+            base_backend = load_chat_backend(base_id, fresh_backend = True, **base_load_opts)
+        except Exception as exc:
+            err.print(f"(base model load failed: {exc})", style = "red", markup = False)
+            return False
+        return True
+
+    if compare and dual_compare and not load_base_for_compare():
+        raise typer.Exit(code = 1)
+
+    def generate(backend = None, use_adapter = None):
+        # Reads messages and show_thinking live, so /reset and /think apply.
+        return (backend or chat_backend).stream(
+            messages,
+            system_prompt = system_prompt,
+            temperature = temperature,
+            top_p = top_p,
+            top_k = top_k,
+            max_new_tokens = max_new_tokens,
+            repetition_penalty = repetition_penalty,
+            enable_thinking = show_thinking,
+            use_adapter = use_adapter,
+        )
+
+    console.print()
+    console.print(f"Chatting with {name}", style = "bold green", markup = False)
+    console.print(_HELP, style = "bright_black")
+
+    # legacy_windows: pre-VT consoles print raw ANSI as ←[1;36m garbage.
+    you_prompt = _you_prompt(console.is_terminal and not console.legacy_windows)
+    assistant_label = "[bold magenta]Assistant:[/bold magenta]"
+
+    try:
+        while True:
+            try:
+                user = input(you_prompt).strip()
+            except (EOFError, KeyboardInterrupt):
+                console.print()
+                break
+
+            if not user:
+                continue
+            if user in ("/exit", "/quit"):
+                break
+            if user == "/reset":
+                messages = []
+                console.print("(history cleared)", style = "bright_black")
+                continue
+            if user == "/think":
+                show_thinking = not show_thinking
+                state = "on" if show_thinking else "off"
+                console.print(f"(thinking {state})", style = "bright_black")
+                continue
+            if user == "/compare":
+                if compare_blocked:
+                    console.print(f"(compare unavailable: {compare_blocked})", style = "yellow")
+                    continue
+                if not compare_mode and dual_compare and not load_base_for_compare():
+                    continue
+                compare_mode = not compare_mode
+                state = "on" if compare_mode else "off"
+                console.print(f"(compare {state})", style = "bright_black")
+                continue
+            if user in ("/help", "/?"):
+                console.print(_HELP, style = "bright_black")
+                continue
+
+            messages.append({"role": "user", "content": user})
+
+            try:
+                if compare_mode:
+                    console.print("(comparing base vs tuned…)", style = "bright_black")
+                    if dual_compare:
+                        base_text = collect_stream(generate(backend = base_backend), show_thinking)
+                        tuned_text = collect_stream(generate(), show_thinking)
+                    else:
+                        base_text = collect_stream(generate(use_adapter = False), show_thinking)
+                        tuned_text = collect_stream(generate(use_adapter = True), show_thinking)
+                    console.print()
+                    render_columns(
+                        "base", base_text, f"{name} (tuned)", tuned_text, console = console
+                    )
+                    # History continues as the tuned model; base is just the reference.
+                    answer = tuned_text
+                else:
+                    console.print(assistant_label)
+                    answer = stream_markdown(generate(), show_thinking, console = console)
+            except KeyboardInterrupt:
+                # Ctrl-C aborts this answer only; drop the unanswered turn.
+                console.print("\n(interrupted)", style = "bright_black")
+                messages.pop()
+                continue
+            except Exception as exc:
+                err.print(f"\n(error: {exc})", style = "red", markup = False)
+                messages.pop()
+                continue
+
+            messages.append(
+                {"role": "assistant", "content": visible_text(answer, show_thinking = False)}
+            )
+    finally:
+        chat_backend.close()
+        if base_backend is not None:
+            base_backend.close()
+        err.print("\nBye.", style = "bright_black")
diff --git a/unsloth_cli/commands/inference.py b/unsloth_cli/commands/inference.py
index 18de68c4d9..5dbc32c7d2 100644
--- a/unsloth_cli/commands/inference.py
+++ b/unsloth_cli/commands/inference.py
@@ -1,11 +1,17 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import sys
 from typing import Optional
 
 import typer
 
+from unsloth_cli._inference import (
+    configure_quiet_logging,
+    connect_studio_server,
+    load_chat_backend,
+    stream_to_stdout,
+)
+
 
 def inference(
     model: str = typer.Argument(..., help = "HF model id or local path."),
@@ -25,45 +31,46 @@ def inference(
     ),
     max_seq_length: int = typer.Option(2048, "--max-seq-length"),
     load_in_4bit: bool = typer.Option(True, "--load-in-4bit/--no-load-in-4bit"),
+    think: bool = typer.Option(
+        False,
+        "--think/--no-think",
+        help = "Show the model's <think> reasoning. Off by default so reasoning "
+        "models answer directly instead of spending the token budget thinking.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help = "Show backend and llama-server logs (otherwise only the answer).",
+    ),
+    no_server: bool = typer.Option(
+        False,
+        "--no-server",
+        help = "Load the model in-process even if a Studio server is running.",
+    ),
 ):
     """Run a single inference using the specified model."""
-    from studio.backend.core import ModelConfig, get_inference_backend
+    if not verbose:
+        configure_quiet_logging()
 
-    inference_backend = get_inference_backend()
-    model_config = ModelConfig.from_ui_selection(
-        dropdown_value = model, search_value = None, hf_token = hf_token, is_lora = False
-    )
-    if not model_config:
-        typer.echo("Could not resolve model config", err = True)
-        raise typer.Exit(code = 1)
-
-    if not inference_backend.load_model(
-        config = model_config,
-        max_seq_length = max_seq_length,
-        load_in_4bit = load_in_4bit,
-        hf_token = hf_token,
-    ):
-        typer.echo("Model load failed", err = True)
-        raise typer.Exit(code = 1)
-
-    messages = [{"role": "user", "content": prompt}]
-    stream = inference_backend.generate_chat_response(
-        messages = messages,
-        system_prompt = system_prompt,
-        temperature = temperature,
-        top_p = top_p,
-        top_k = top_k,
-        max_new_tokens = max_new_tokens,
-        repetition_penalty = repetition_penalty,
-    )
-
-    typer.echo("Assistant:", nl = True)
-    previous = ""
-    for chunk in stream:
-        delta = chunk[len(previous) :]
-        if delta:
-            sys.stdout.write(delta)
-            sys.stdout.flush()
-        previous = chunk
-    sys.stdout.write("\n")
-    sys.stdout.flush()
+    # A running Studio server keeps the model warm between runs, which is
+    # exactly what a one-shot command wants.
+    load_opts = dict(hf_token = hf_token, max_seq_length = max_seq_length, load_in_4bit = load_in_4bit)
+    chat_backend = None if no_server else connect_studio_server(model, **load_opts)
+    if chat_backend is None:
+        chat_backend = load_chat_backend(model, **load_opts)
+    try:
+        stream = chat_backend.stream(
+            [{"role": "user", "content": prompt}],
+            system_prompt = system_prompt,
+            temperature = temperature,
+            top_p = top_p,
+            top_k = top_k,
+            max_new_tokens = max_new_tokens,
+            repetition_penalty = repetition_penalty,
+            enable_thinking = think,
+        )
+        typer.echo("Assistant:")
+        stream_to_stdout(stream, show_thinking = think)
+    finally:
+        chat_backend.close()
diff --git a/unsloth_cli/tests/test_inference_chat.py b/unsloth_cli/tests/test_inference_chat.py
new file mode 100644
index 0000000000..629cb46405
--- /dev/null
+++ b/unsloth_cli/tests/test_inference_chat.py
@@ -0,0 +1,401 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for the `unsloth chat` / `unsloth inference` CLI — fakes only, no model loads."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+import types
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+
+import typer
+from rich.console import Console
+from typer.testing import CliRunner
+
+import unsloth_cli.commands.chat as chatmod
+from unsloth_cli._inference import (
+    ChatBackend,
+    HttpChatBackend,
+    collect_stream,
+    render_columns,
+    visible_text,
+)
+
+
+class _FakeConfig:
+    is_gguf = False
+    is_lora = True
+    display_name = "fake-model"
+    base_model = "fake/base"
+    path = None
+
+
+def _chat_app():
+    cli = typer.Typer()
+    cli.command()(chatmod.chat)
+    return cli
+
+
+def test_visible_text_passthrough_when_shown():
+    text = "<think>reasoning</think>answer"
+    assert visible_text(text, show_thinking = True) == text
+
+
+def test_visible_text_strips_closed_think_block():
+    text = "<think>step 1\nstep 2</think>The answer is 42."
+    assert visible_text(text, show_thinking = False) == "The answer is 42."
+
+
+def test_visible_text_holds_unclosed_think():
+    # An open <think> is held back so partial reasoning never leaks mid-stream.
+    assert visible_text("<think>still thinking", show_thinking = False) == ""
+    assert visible_text("done.<think>more thinking", show_thinking = False) == "done."
+
+
+def test_visible_text_holds_partial_think_prefix():
+    # Streams are cumulative, so the opening tag can arrive as "<", "<thi",
+    # then "<think>". Hold possible tag prefixes until they are disambiguated.
+    assert visible_text("<", show_thinking = False) == ""
+    assert visible_text("<thi", show_thinking = False) == ""
+    assert visible_text("done.<thi", show_thinking = False) == "done."
+    assert visible_text("2 < 3", show_thinking = False) == "2 < 3"
+
+
+def _option(command_fn, name):
+    return inspect.signature(command_fn).parameters[name].default
+
+
+def test_inference_think_defaults_off():
+    from unsloth_cli.commands.inference import inference
+
+    opt = _option(inference, "think")
+    assert getattr(opt, "default", None) is False
+    # typer stores a flag/--no-flag pair as one combined decl.
+    assert "--think/--no-think" in (getattr(opt, "param_decls", None) or [])
+
+
+def test_chat_command_is_registered_with_options():
+    params = inspect.signature(chatmod.chat).parameters
+    assert "model" in params
+
+    think = _option(chatmod.chat, "think")
+    assert "--think/--no-think" in (getattr(think, "param_decls", None) or [])
+
+    compare = _option(chatmod.chat, "compare")
+    assert "--compare/--no-compare" in (getattr(compare, "param_decls", None) or [])
+
+    verbose = _option(chatmod.chat, "verbose")
+    assert {"--verbose", "-v"} <= set(getattr(verbose, "param_decls", None) or [])
+
+
+class _FakeBackend:
+    def __init__(self):
+        self.calls = []
+
+    def generate_chat_response(self, **kwargs):
+        self.calls.append(("plain", None, kwargs))
+        return iter(["hi"])
+
+    def generate_with_adapter_control(self, *, use_adapter, **kwargs):
+        self.calls.append(("adapter", use_adapter, kwargs))
+        return iter(["hi"])
+
+
+_STREAM_KWARGS = dict(
+    system_prompt = "",
+    temperature = 0.7,
+    top_p = 0.9,
+    top_k = 40,
+    max_new_tokens = 8,
+    repetition_penalty = 1.1,
+    enable_thinking = False,
+)
+
+
+def test_chatbackend_routes_compare_to_adapter_control():
+    fake = _FakeBackend()
+    backend = ChatBackend("unsloth", fake)
+
+    list(backend.stream([{"role": "user", "content": "x"}], use_adapter = False, **_STREAM_KWARGS))
+    list(backend.stream([{"role": "user", "content": "x"}], use_adapter = True, **_STREAM_KWARGS))
+
+    assert [(path, flag) for path, flag, _ in fake.calls] == [
+        ("adapter", False),
+        ("adapter", True),
+    ]
+
+
+def test_chatbackend_normal_path_skips_adapter_control():
+    fake = _FakeBackend()
+    backend = ChatBackend("unsloth", fake)
+
+    list(backend.stream([{"role": "user", "content": "x"}], **_STREAM_KWARGS))
+
+    assert fake.calls[0][0] == "plain"
+
+
+def test_collect_stream_returns_last_cumulative_think_stripped():
+    stream = iter(["<think>r</think>hel", "<think>r</think>hello"])
+    assert collect_stream(stream, show_thinking = False) == "hello"
+
+
+def test_render_columns_emits_both_answers_with_separator(capsys):
+    render_columns("base", "alpha", "tuned", "beta")
+    out = capsys.readouterr().out
+    assert "base" in out and "tuned" in out
+    assert "alpha" in out and "beta" in out
+    assert "│" in out
+
+
+def test_you_prompt_matches_readline_backend(monkeypatch):
+    gnu = types.ModuleType("readline")
+    gnu.__doc__ = "Importing this module enables command line editing using GNU readline."
+    monkeypatch.setitem(sys.modules, "readline", gnu)
+    prompt = chatmod._you_prompt(colors = True)
+    assert "You: " in prompt and "\001" in prompt
+
+    libedit = types.ModuleType("readline")
+    libedit.__doc__ = "Importing this module enables command line editing using libedit readline."
+    monkeypatch.setitem(sys.modules, "readline", libedit)
+    assert chatmod._you_prompt(colors = True) == "\n\x1b[1;36mYou: \x1b[0m"
+    assert chatmod._you_prompt(colors = False) == "\nYou: "
+
+    # Windows: no readline module at all; the console's own line editing
+    # handles backspace, so plain ANSI color (no markers) is safe.
+    monkeypatch.setitem(sys.modules, "readline", None)
+    assert chatmod._you_prompt(colors = True) == "\n\x1b[1;36mYou: \x1b[0m"
+    assert chatmod._you_prompt(colors = False) == "\nYou: "
+
+
+def test_chat_registered_on_app():
+    from unsloth_cli import app
+
+    # cmd.name is None until typer resolves it from the callback name.
+    names = {(cmd.name or cmd.callback.__name__) for cmd in app.registered_commands}
+    assert "chat" in names
+
+
+def test_chat_exits_cleanly_on_slash_exit(monkeypatch):
+    closed = []
+
+    class _FakeChatBackend:
+        def stream(self, *a, **k):
+            return iter(["hello"])
+
+        def close(self):
+            closed.append(True)
+
+    monkeypatch.setattr(chatmod, "resolve_model_config", lambda *a, **k: _FakeConfig())
+    monkeypatch.setattr(chatmod, "load_chat_backend", lambda *a, **k: _FakeChatBackend())
+    monkeypatch.setattr(chatmod, "_compare_needs_second_model", lambda: False)
+    monkeypatch.setattr(chatmod, "connect_studio_server", lambda *a, **k: None)
+
+    runner = CliRunner()
+    for args in (["fake-model"], ["fake-model", "--compare"]):
+        closed.clear()
+        result = runner.invoke(_chat_app(), args, input = "hi\n/exit\n")
+        assert result.exit_code == 0, result.output
+        assert closed == [True]
+        assert "Bye." in result.output
+        # The prompt must go through input() (readline-safe), not a print.
+        assert "You: " in result.output
+        assert "You: You:" not in result.output
+
+
+def test_pick_trained_model_lists_and_selects(monkeypatch):
+    fake_models = types.ModuleType("utils.models")
+    fake_models.scan_trained_models = lambda: [
+        ("run-new", "outputs/run-new", "lora"),
+        ("run-old", "outputs/run-old", "merged"),
+    ]
+    monkeypatch.setitem(sys.modules, "utils.models", fake_models)
+
+    monkeypatch.setattr("builtins.input", lambda prompt = "": "2")
+    assert chatmod._pick_trained_model(Console()) == "outputs/run-old"
+
+    monkeypatch.setattr("builtins.input", lambda prompt = "": "")
+    assert chatmod._pick_trained_model(Console()) == "outputs/run-new"
+
+
+def test_chat_no_arg_chats_with_picked_trained_model(monkeypatch):
+    class _FakeChatBackend:
+        def stream(self, *a, **k):
+            return iter(["hello"])
+
+        def close(self):
+            pass
+
+    resolved = []
+    monkeypatch.setattr(chatmod, "_pick_trained_model", lambda console: "outputs/run-42")
+    monkeypatch.setattr(
+        chatmod,
+        "resolve_model_config",
+        lambda model, **k: (resolved.append(model), _FakeConfig())[1],
+    )
+    monkeypatch.setattr(chatmod, "load_chat_backend", lambda *a, **k: _FakeChatBackend())
+    monkeypatch.setattr(chatmod, "_compare_needs_second_model", lambda: False)
+    monkeypatch.setattr(chatmod, "connect_studio_server", lambda *a, **k: None)
+
+    result = CliRunner().invoke(_chat_app(), [], input = "/exit\n")
+    assert result.exit_code == 0, result.output
+    assert resolved == ["outputs/run-42"]
+
+
+def test_find_studio_server_none_when_not_running(monkeypatch):
+    import urllib.request
+
+    from unsloth_cli import _inference
+
+    def refuse(*a, **k):
+        raise OSError("connection refused")
+
+    monkeypatch.setattr(urllib.request, "urlopen", refuse)
+    assert _inference.find_studio_server() is None
+
+
+class _FakeSSEResponse:
+    def __init__(self, lines):
+        self._lines = lines
+
+    def __iter__(self):
+        return iter(self._lines)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def test_http_backend_streams_cumulative_text(monkeypatch):
+    backend = HttpChatBackend("http://localhost:8888", "token")
+    response = _FakeSSEResponse(
+        [
+            b'data: {"choices":[{"delta":{"content":"He"}}]}\n',
+            b"\n",
+            b'data: {"choices":[{"delta":{"content":"llo"}}]}\n',
+            b"data: [DONE]\n",
+        ]
+    )
+    monkeypatch.setattr(backend, "_request", lambda *a, **k: response)
+
+    out = list(backend.stream([{"role": "user", "content": "hi"}], **_STREAM_KWARGS))
+    assert out == ["He", "Hello"]
+
+
+def test_http_backend_merges_emoji_split_across_deltas(monkeypatch):
+    backend = HttpChatBackend("http://localhost:8888", "token")
+    response = _FakeSSEResponse(
+        [
+            b'data: {"choices":[{"delta":{"content":"hi "}}]}\n',
+            b'data: {"choices":[{"delta":{"content":"\\ud83d"}}]}\n',
+            b'data: {"choices":[{"delta":{"content":"\\ude0a"}}]}\n',
+            b"data: [DONE]\n",
+        ]
+    )
+    monkeypatch.setattr(backend, "_request", lambda *a, **k: response)
+
+    out = list(backend.stream([{"role": "user", "content": "hi"}], **_STREAM_KWARGS))
+    # The lone high surrogate is held back, then merged with its other half.
+    assert out == ["hi ", "hi ", "hi 😊"]
+
+
+def test_chat_prefers_running_studio_server(monkeypatch):
+    closed = []
+
+    class _FakeHttpBackend:
+        def stream(self, *a, **k):
+            return iter(["hello"])
+
+        def close(self):
+            closed.append("http")
+
+    local_loads = []
+    monkeypatch.setattr(chatmod, "resolve_model_config", lambda *a, **k: _FakeConfig())
+    monkeypatch.setattr(chatmod, "connect_studio_server", lambda *a, **k: _FakeHttpBackend())
+    monkeypatch.setattr(chatmod, "load_chat_backend", lambda *a, **k: local_loads.append(1))
+    monkeypatch.setattr(chatmod, "_compare_needs_second_model", lambda: False)
+
+    result = CliRunner().invoke(_chat_app(), ["fake-model"], input = "hi\n/exit\n")
+
+    assert result.exit_code == 0, result.output
+    assert local_loads == []
+    assert "stays warm" in result.output
+    assert closed == ["http"]
+
+
+def test_chat_server_mode_compare_loads_base_locally(monkeypatch):
+    streamed, closed, base_loads = [], [], []
+
+    class _FakeHttpBackend:
+        def stream(self, *a, **k):
+            streamed.append("tuned")
+            return iter(["tuned-answer"])
+
+        def close(self):
+            closed.append("http")
+
+    class _FakeBaseBackend:
+        def stream(self, *a, **k):
+            streamed.append("base")
+            return iter(["base-answer"])
+
+        def close(self):
+            closed.append("base")
+
+    def fake_local_load(model, **kwargs):
+        base_loads.append((model, kwargs.get("fresh_backend", False)))
+        return _FakeBaseBackend()
+
+    monkeypatch.setattr(chatmod, "resolve_model_config", lambda *a, **k: _FakeConfig())
+    monkeypatch.setattr(chatmod, "connect_studio_server", lambda *a, **k: _FakeHttpBackend())
+    monkeypatch.setattr(chatmod, "load_chat_backend", fake_local_load)
+
+    result = CliRunner().invoke(_chat_app(), ["tuned-run"], input = "/compare\nhi\n/exit\n")
+
+    assert result.exit_code == 0, result.output
+    assert "(compare on)" in result.output
+    # Only the base model loaded locally, on its own private backend.
+    assert base_loads == [("fake/base", True)]
+    assert streamed == ["base", "tuned"]
+    assert set(closed) == {"http", "base"}
+
+
+def test_chat_compare_on_mlx_loads_base_model_side_by_side(monkeypatch):
+    loads, streamed, closed = [], [], []
+
+    class _FakeLocalBackend:
+        def __init__(self, role):
+            self.role = role
+
+        def stream(self, *a, **k):
+            streamed.append((self.role, k.get("use_adapter")))
+            return iter([f"{self.role}-answer"])
+
+        def close(self):
+            closed.append(self.role)
+
+    def fake_load(model, **kwargs):
+        fresh = kwargs.get("fresh_backend", False)
+        loads.append((model, fresh))
+        return _FakeLocalBackend("base" if fresh else "tuned")
+
+    monkeypatch.setattr(chatmod, "resolve_model_config", lambda *a, **k: _FakeConfig())
+    monkeypatch.setattr(chatmod, "load_chat_backend", fake_load)
+    monkeypatch.setattr(chatmod, "_compare_needs_second_model", lambda: True)
+    monkeypatch.setattr(chatmod, "connect_studio_server", lambda *a, **k: None)
+
+    result = CliRunner().invoke(_chat_app(), ["tuned-run", "--compare"], input = "hi\n/exit\n")
+
+    assert result.exit_code == 0, result.output
+    assert loads == [("tuned-run", False), ("fake/base", True)]
+    # Both models answered the turn, via plain generation (no adapter toggle).
+    assert ("base", None) in streamed and ("tuned", None) in streamed
+    assert set(closed) == {"tuned", "base"}

From 004577c9cd4b156d02e9d10b1ede822c2822e22f Mon Sep 17 00:00:00 2001
From: Nilay <118994073+NilayYadav@users.noreply.github.com>
Date: Thu, 11 Jun 2026 20:47:22 +0530
Subject: [PATCH 208/222] studio: show MCP "Import config" on the add-server
 form (#6030)

* studio: import MCP servers from a config file

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* import config' on the add-server form

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: defensively handle MCP config imports

* fix: address MCP import review follow-ups

* fix: preserve apostrophes in Windows MCP commands

* fix: preserve apostrophe-wrapped Windows MCP args

* fix: align Windows MCP parsing with list2cmdline

* fix: preserve explicit MCP remote transport intent

* fix: trim MCP remote URLs before transport checks

---------

Co-authored-by: Roland Tannous <rolandtannous@gravityq.ai>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Roland Tannous <115670425+rolandtannous@users.noreply.github.com>
Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
Co-authored-by: imagineer99 <samleejackson0@gmail.com>
---
 studio/backend/core/inference/mcp_client.py   |  81 ++++-
 .../core/inference/mcp_config_import.py       | 169 +++++++++
 studio/backend/models/mcp_servers.py          |  11 +
 studio/backend/routes/mcp_servers.py          |  43 +++
 .../backend/tests/test_mcp_config_import.py   | 341 ++++++++++++++++++
 .../src/features/chat/api/mcp-servers-api.ts  |  15 +
 .../features/chat/chat-mcp-servers-dialog.tsx |  88 ++++-
 7 files changed, 739 insertions(+), 9 deletions(-)
 create mode 100644 studio/backend/core/inference/mcp_config_import.py
 create mode 100644 studio/backend/tests/test_mcp_config_import.py

diff --git a/studio/backend/core/inference/mcp_client.py b/studio/backend/core/inference/mcp_client.py
index 9a7fd1f074..a0d79bbdf4 100644
--- a/studio/backend/core/inference/mcp_client.py
+++ b/studio/backend/core/inference/mcp_client.py
@@ -25,16 +25,85 @@ def is_stdio(address: str) -> bool:
     return not address.strip().lower().startswith(("http://", "https://"))
 
 
+def _split_windows_command_line(address: str) -> list[str]:
+    """Parse a Windows command line using the same backslash/quote rules that
+    subprocess.list2cmdline() writes. This keeps trailing backslashes before a
+    closing quote from being doubled in the resulting argv."""
+    parts: list[str] = []
+    current: list[str] = []
+    in_quotes = False
+    backslashes = 0
+    arg_started = False
+    i = 0
+
+    while i < len(address):
+        ch = address[i]
+        if ch == "\\":
+            backslashes += 1
+            i += 1
+            continue
+        if ch == '"':
+            current.extend("\\" * (backslashes // 2))
+            if backslashes % 2:
+                current.append('"')
+            else:
+                in_quotes = not in_quotes
+            arg_started = True
+            backslashes = 0
+            i += 1
+            continue
+        if ch.isspace() and not in_quotes:
+            if backslashes:
+                current.extend("\\" * backslashes)
+                arg_started = True
+                backslashes = 0
+            if arg_started or current:
+                parts.append("".join(current))
+                current = []
+                arg_started = False
+            i += 1
+            while i < len(address) and address[i].isspace():
+                i += 1
+            continue
+        if backslashes:
+            current.extend("\\" * backslashes)
+            arg_started = True
+            backslashes = 0
+        current.append(ch)
+        arg_started = True
+        i += 1
+
+    if backslashes:
+        current.extend("\\" * backslashes)
+        arg_started = True
+    if in_quotes:
+        raise ValueError("No closing quotation")
+    if arg_started or current:
+        parts.append("".join(current))
+    return parts
+
+
 def parse_stdio_command(address: str) -> list[str]:
     """Split a stdio command line into argv. Shared by route validation and the
     transport so both agree on quoting (notably Windows backslash paths)."""
     posix = sys.platform != "win32"
-    parts = shlex.split(address, posix = posix)
-    if not posix:
-        # posix=False keeps backslash paths but also keeps surrounding quotes;
-        # strip a matched pair so argv reaches the subprocess clean.
-        parts = [p[1:-1] if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'" else p for p in parts]
-    return parts
+    if posix:
+        return shlex.split(address, posix = posix)
+    if address.lstrip().startswith("'"):
+        raise ValueError("Single-quoted executables are not supported on Windows")
+    return _split_windows_command_line(address)
+
+
+def join_stdio_command(parts: list[str]) -> str:
+    """Inverse of parse_stdio_command: join argv into a single command string
+    that parse_stdio_command() splits back into ``parts`` on this platform.
+    Config files (issue #5936) carry structured command + args; storage holds
+    one string in the url field. Windows uses list2cmdline so spaced/backslash
+    paths round-trip through the posix=False quote-strip; posix uses shlex."""
+    if sys.platform == "win32":
+        import subprocess
+        return subprocess.list2cmdline(parts)
+    return shlex.join(parts)
 
 
 def stdio_mcp_enabled() -> bool:
diff --git a/studio/backend/core/inference/mcp_config_import.py b/studio/backend/core/inference/mcp_config_import.py
new file mode 100644
index 0000000000..534ed84c1d
--- /dev/null
+++ b/studio/backend/core/inference/mcp_config_import.py
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Parse a standard ``mcpServers`` JSON config (Claude Desktop / Cursor / Cline
+/ VS Code) into entries the existing MCP storage understands. See issue #5936.
+
+A stdio entry (``command`` + ``args`` + ``env``) is joined into the single
+command string the ``url`` field already stores; a remote entry (``url`` +
+``headers``) maps straight through. Parsing never raises on a single bad entry:
+it returns ``(entries, errors)`` so one malformed server can't sink the import.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from core.inference.mcp_client import join_stdio_command
+
+_SCALAR = (str, int, float, bool)
+_UNSUPPORTED_STDIO_FIELDS = ("cwd", "envFile")
+_UNSUPPORTED_TIMEOUT_FIELDS = ("timeout", "timeoutMs", "timeoutSeconds")
+_HTTP_REMOTE_TYPES = ("http", "streamableHttp")
+
+
+@dataclass
+class ParsedMcpEntry:
+    display_name: str
+    url: str  # joined command (stdio) or http(s) url (remote)
+    headers: Optional[dict[str, str]]  # env vars (stdio) or http headers (remote)
+    is_stdio: bool
+    is_enabled: bool = True
+    use_oauth: bool = False
+
+
+def _coerce_str_dict(value: dict) -> dict[str, str]:
+    return {str(k): str(v) for k, v in value.items()}
+
+
+def _has_variable_reference(value: object) -> bool:
+    if isinstance(value, str):
+        return "${" in value
+    if isinstance(value, list):
+        return any(_has_variable_reference(item) for item in value)
+    if isinstance(value, dict):
+        return any(_has_variable_reference(item) for item in value.values())
+    return False
+
+
+def _has_null_value(value: object) -> bool:
+    return isinstance(value, dict) and any(item is None for item in value.values())
+
+
+def _enabled_from_spec(label: str, spec: dict) -> tuple[Optional[bool], Optional[str]]:
+    disabled = spec.get("disabled")
+    if disabled is None:
+        return True, None
+    if not isinstance(disabled, bool):
+        return None, f"{label}: 'disabled' must be true or false."
+    return not disabled, None
+
+
+def _parse_entry(name: str, spec: object) -> tuple[Optional[ParsedMcpEntry], Optional[str]]:
+    label = str(name).strip()
+    if not label:
+        return None, "Server entry has an empty name."
+    if not isinstance(spec, dict):
+        return None, f"{label}: entry must be an object."
+    if _has_variable_reference(spec):
+        return None, f"{label}: VS Code variable references are not supported by import."
+
+    is_enabled, error = _enabled_from_spec(label, spec)
+    if error:
+        return None, error
+
+    has_command = bool(spec.get("command"))
+    has_url = bool(spec.get("url"))
+    if has_command and has_url:
+        return None, f"{label}: entry has both 'command' and 'url'; use one."
+    if not has_command and not has_url:
+        return None, f"{label}: entry needs a 'command' (stdio) or 'url' (remote)."
+
+    if has_command:
+        command = spec["command"]
+        if not isinstance(command, str):
+            return None, f"{label}: 'command' must be a string."
+        entry_type = spec.get("type")
+        if entry_type is not None and entry_type != "stdio":
+            return None, f"{label}: stdio entry has unsupported type {entry_type!r}."
+        sandbox_enabled = spec.get("sandboxEnabled")
+        if sandbox_enabled is not None and not isinstance(sandbox_enabled, bool):
+            return None, f"{label}: 'sandboxEnabled' must be true or false."
+        if sandbox_enabled:
+            return None, f"{label}: sandboxed stdio servers cannot be preserved by import."
+        unsupported = [field for field in _UNSUPPORTED_STDIO_FIELDS if spec.get(field) is not None]
+        if unsupported:
+            return None, f"{label}: import cannot preserve {', '.join(unsupported)}."
+        if spec.get("oauth") is not None:
+            return None, f"{label}: 'oauth' is only supported for remote servers."
+        args = spec.get("args") or []
+        if not isinstance(args, list) or not all(isinstance(a, _SCALAR) for a in args):
+            return None, f"{label}: 'args' must be a list of strings."
+        env = spec.get("env")
+        if env is not None and not isinstance(env, dict):
+            return None, f"{label}: 'env' must be an object."
+        if _has_null_value(env):
+            return None, f"{label}: null environment values are not supported by import."
+        url = join_stdio_command([command, *(str(a) for a in args)])
+        headers = _coerce_str_dict(env) if env else None
+        return ParsedMcpEntry(label, url, headers, True, is_enabled = is_enabled), None
+
+    url = spec["url"]
+    if not isinstance(url, str):
+        return None, f"{label}: 'url' must be a string."
+    url = url.strip()
+    entry_type = spec.get("type")
+    if entry_type is not None and entry_type not in (*_HTTP_REMOTE_TYPES, "sse"):
+        return None, f"{label}: remote entry has unsupported type {entry_type!r}."
+    unsupported_timeout = [
+        field for field in _UNSUPPORTED_TIMEOUT_FIELDS if spec.get(field) is not None
+    ]
+    if unsupported_timeout:
+        return None, f"{label}: import cannot preserve {', '.join(unsupported_timeout)}."
+    url_infers_sse = url.rstrip("/").endswith("/sse")
+    if entry_type == "sse" and not url_infers_sse:
+        return None, f"{label}: explicit SSE transport cannot be preserved for this URL."
+    if entry_type in _HTTP_REMOTE_TYPES and url_infers_sse:
+        return None, f"{label}: explicit HTTP transport cannot be preserved for this URL."
+    oauth_raw = spec.get("oauth")
+    if oauth_raw is not None and not isinstance(oauth_raw, dict):
+        return None, f"{label}: 'oauth' must be an object."
+    headers_raw = spec.get("headers")
+    if headers_raw is not None and not isinstance(headers_raw, dict):
+        return None, f"{label}: 'headers' must be an object."
+    if _has_null_value(headers_raw):
+        return None, f"{label}: null header values are not supported by import."
+    headers = _coerce_str_dict(headers_raw) if headers_raw else None
+    return ParsedMcpEntry(
+        label,
+        url,
+        headers,
+        False,
+        is_enabled = is_enabled,
+        use_oauth = oauth_raw is not None,
+    ), None
+
+
+def parse_mcp_config(config: object) -> tuple[list[ParsedMcpEntry], list[str]]:
+    """Parse a Claude-Desktop/Cursor/Cline/VS Code config. Accepts the
+    ``mcpServers`` key (primary) or ``servers`` (VS Code alias). Returns
+    ``(entries, errors)``; a bad entry adds an error rather than raising."""
+    if not isinstance(config, dict):
+        return [], ["Config must be a JSON object."]
+    servers_key = "mcpServers" if "mcpServers" in config else "servers"
+    servers = config.get(servers_key)
+    if servers is None:
+        return [], ["Config has no 'mcpServers' (or 'servers') object."]
+    if not isinstance(servers, dict):
+        return [], [f"'{servers_key}' must be an object mapping name -> server."]
+
+    entries: list[ParsedMcpEntry] = []
+    errors: list[str] = []
+    for name, spec in servers.items():
+        entry, error = _parse_entry(name, spec)
+        if error:
+            errors.append(error)
+        elif entry:
+            entries.append(entry)
+    return entries, errors
diff --git a/studio/backend/models/mcp_servers.py b/studio/backend/models/mcp_servers.py
index c696eb0faa..606c2423bf 100644
--- a/studio/backend/models/mcp_servers.py
+++ b/studio/backend/models/mcp_servers.py
@@ -44,3 +44,14 @@ class McpServerProbeResult(BaseModel):
     ok: bool
     tool_count: int = 0
     error: Optional[str] = None
+
+
+class McpServerImportRequest(BaseModel):
+    # A standard mcpServers JSON config (Claude Desktop / Cursor / Cline / VS Code).
+    config: dict
+
+
+class McpServerImportResult(BaseModel):
+    created: list[McpServerResponse] = Field(default_factory = list)
+    skipped: list[str] = Field(default_factory = list)  # display names skipped as duplicates
+    errors: list[str] = Field(default_factory = list)
diff --git a/studio/backend/routes/mcp_servers.py b/studio/backend/routes/mcp_servers.py
index 098c64fe39..3001c6b7c9 100644
--- a/studio/backend/routes/mcp_servers.py
+++ b/studio/backend/routes/mcp_servers.py
@@ -18,8 +18,11 @@ from core.inference.mcp_client import (
     probe_timeout,
     stdio_mcp_enabled,
 )
+from core.inference.mcp_config_import import parse_mcp_config
 from models.mcp_servers import (
     McpServerCreate,
+    McpServerImportRequest,
+    McpServerImportResult,
     McpServerProbeResult,
     McpServerResponse,
     McpServerTestRequest,
@@ -240,6 +243,46 @@ async def refresh_mcp_server_tools(
     return McpServerProbeResult(ok = True, tool_count = len(tools))
 
 
+@router.post("/import", response_model = McpServerImportResult)
+async def import_mcp_servers(
+    payload: McpServerImportRequest, current_subject: str = Depends(get_current_subject)
+):
+    """Bulk-register servers from a standard mcpServers JSON config (issue
+    #5936). Each entry rides the existing create path: _validate_url applies
+    the same stdio gate (a stdio entry becomes a per-entry error when stdio is
+    off; http still imports), and entries whose url already exists are skipped
+    so re-importing the same file is idempotent. One bad entry never 400s the
+    whole batch -- failures are reported per entry."""
+    entries, errors = parse_mcp_config(payload.config)
+    created: list[McpServerResponse] = []
+    skipped: list[str] = []
+    seen_urls = {row["url"] for row in mcp_servers_db.list_servers()}
+
+    for entry in entries:
+        try:
+            url = _validate_url(entry.url)
+        except HTTPException as exc:
+            errors.append(f"{entry.display_name}: {exc.detail}")
+            continue
+        if url in seen_urls:
+            skipped.append(entry.display_name)
+            continue
+        headers = _normalize_headers(entry.headers)
+        server_id = uuid.uuid4().hex[:16]
+        mcp_servers_db.create_server(
+            id = server_id,
+            display_name = entry.display_name,
+            url = url,
+            headers_json = json.dumps(headers) if headers else None,
+            is_enabled = entry.is_enabled,
+            use_oauth = entry.use_oauth and not is_stdio(url),
+        )
+        seen_urls.add(url)
+        created.append(_row_to_response(mcp_servers_db.get_server(server_id)))
+
+    return McpServerImportResult(created = created, skipped = skipped, errors = errors)
+
+
 @router.post("/test", response_model = McpServerProbeResult)
 async def test_mcp_server(
     payload: McpServerTestRequest, current_subject: str = Depends(get_current_subject)
diff --git a/studio/backend/tests/test_mcp_config_import.py b/studio/backend/tests/test_mcp_config_import.py
new file mode 100644
index 0000000000..4082733490
--- /dev/null
+++ b/studio/backend/tests/test_mcp_config_import.py
@@ -0,0 +1,341 @@
+"""Tests for MCP config-file import (issue #5936).
+
+Covers the round-trip-safe command join/split inverse (join_stdio_command ↔
+parse_stdio_command, on both posix and win32 using the issue's Windows
+fixtures), the pure config parser (parse_mcp_config), and the POST /import
+route (stdio gate on/off, url dedup, one bad entry not sinking the batch).
+
+Run from studio/backend:  python -m pytest tests/test_mcp_config_import.py -q
+"""
+
+import sys
+
+import pytest
+
+from core.inference import mcp_client
+from core.inference.mcp_config_import import parse_mcp_config
+from storage import mcp_servers_db
+
+
+def _reset_db(tmp_path, monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+    monkeypatch.setattr(mcp_servers_db, "_schema_ready", False)
+
+
+def _enable(monkeypatch):
+    monkeypatch.setenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", "1")
+
+
+def _disable(monkeypatch):
+    monkeypatch.delenv("UNSLOTH_STUDIO_ALLOW_STDIO_MCP", raising = False)
+
+
+# ── 1. join_stdio_command ↔ parse_stdio_command round-trip ──────────
+
+
+@pytest.mark.parametrize(
+    "parts",
+    [
+        ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+        ["python", "-m", "mod", "--name", "a b"],
+        ["uvx", "some-server", "--flag"],
+        ["/usr/local/bin/my-server"],
+        ["mcp-server-sqlite"],
+    ],
+)
+def test_join_parse_roundtrip_posix(monkeypatch, parts):
+    monkeypatch.setattr(sys, "platform", "linux")
+    joined = mcp_client.join_stdio_command(parts)
+    assert mcp_client.parse_stdio_command(joined) == parts
+
+
+@pytest.mark.parametrize(
+    "parts",
+    [
+        # Issue #5936's literal Windows examples: absolute .exe with a path, and
+        # backslash drive/dir args must survive the join→split round-trip intact.
+        [
+            "C:\\Users\\user\\Documents\\Office-Word-MCP-Server\\.venv\\Scripts\\python.exe",
+            "C:\\Users\\user\\Documents\\Office-Word-MCP-Server\\word_mcp_server.py",
+        ],
+        [
+            "node",
+            "C:\\Users\\user\\Documents\\DesktopCommanderMCP\\dist\\index.js",
+            "--no-onboarding",
+        ],
+        [
+            "node",
+            "C:\\Users\\user\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
+            "D:\\",
+            "O:\\",
+        ],
+        # A command path with spaces is the case that actually needs quoting.
+        ["C:\\Program Files\\node\\node.exe", "server.js"],
+        ["C:\\Program Files\\Foo\\", "server.js"],
+        ["C:\\Program Files\\Foo\\", '{"foo":"bar"}'],
+        ["'C:\\Program Files\\node\\node.exe'", "server.js"],
+        ["node", "O'Reilly"],
+        ["node", "C:\\Users\\O'Reilly\\server.js"],
+        ["node", "'draft'"],
+        ["node", "'open", "close'"],
+        ["node", ""],
+    ],
+)
+def test_join_parse_roundtrip_win32(monkeypatch, parts):
+    monkeypatch.setattr(sys, "platform", "win32")
+    joined = mcp_client.join_stdio_command(parts)
+    assert mcp_client.parse_stdio_command(joined) == parts
+
+
+def test_parse_rejects_manual_single_quoted_windows_executable(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "win32")
+    command = "'C:\\Program Files\\node\\node.exe' server.js"
+    with pytest.raises(ValueError):
+        mcp_client.parse_stdio_command(command)
+
+
+def test_parse_windows_apostrophes_as_literals(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "win32")
+    assert mcp_client.parse_stdio_command("node O'Reilly") == ["node", "O'Reilly"]
+    assert mcp_client.parse_stdio_command("node C:\\Users\\O'Reilly\\server.js") == [
+        "node",
+        "C:\\Users\\O'Reilly\\server.js",
+    ]
+    assert mcp_client.parse_stdio_command("node 'draft'") == ["node", "'draft'"]
+    assert mcp_client.parse_stdio_command("node 'open close'") == ["node", "'open", "close'"]
+
+
+def test_parse_rejects_unterminated_windows_double_quote(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "win32")
+    with pytest.raises(ValueError):
+        mcp_client.parse_stdio_command('node "C:\\path with spaces')
+
+
+# ── 2. parse_mcp_config ─────────────────────────────────────────────
+
+
+def test_parse_stdio_entry():
+    cfg = {
+        "mcpServers": {
+            "fs": {
+                "command": "npx",
+                "args": ["-y", "server", "/tmp"],
+                "env": {"K": "v"},
+            }
+        }
+    }
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert len(entries) == 1
+    entry = entries[0]
+    assert entry.display_name == "fs"
+    assert entry.is_stdio is True
+    assert entry.headers == {"K": "v"}
+    assert mcp_client.parse_stdio_command(entry.url) == ["npx", "-y", "server", "/tmp"]
+
+
+def test_parse_remote_entry():
+    cfg = {
+        "mcpServers": {
+            "remote": {
+                "url": "https://example.com/mcp",
+                "headers": {"Authorization": "Bearer x"},
+            }
+        }
+    }
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert entries[0].url == "https://example.com/mcp"
+    assert entries[0].is_stdio is False
+    assert entries[0].headers == {"Authorization": "Bearer x"}
+
+
+def test_parse_preserves_disabled_and_oauth():
+    cfg = {
+        "servers": {
+            "remote": {
+                "type": "http",
+                "url": "https://example.com/mcp",
+                "oauth": {"clientId": "client"},
+                "disabled": True,
+            }
+        }
+    }
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert entries[0].is_enabled is False
+    assert entries[0].use_oauth is True
+
+
+def test_parse_accepts_cline_streamable_http_alias():
+    cfg = {
+        "mcpServers": {
+            "remote": {
+                "type": "streamableHttp",
+                "url": "https://example.com/mcp",
+            }
+        }
+    }
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert entries[0].url == "https://example.com/mcp"
+    assert entries[0].is_stdio is False
+
+
+@pytest.mark.parametrize(
+    "server",
+    [
+        {"command": "node", "args": ["server.js"], "cwd": "/tmp/server"},
+        {"command": "node", "args": ["server.js"], "envFile": ".env"},
+        {"command": "node", "args": ["server.js"], "env": {"API_KEY": "${input:api-key}"}},
+        {"command": "node", "args": ["${workspaceFolder}/server.js"]},
+        {"command": "node", "args": ["server.js"], "env": {"HTTP_PROXY": None}},
+        {"command": "node", "args": ["server.js"], "sandboxEnabled": True},
+        {"url": "https://example.com/mcp", "headers": {"Authorization": "Bearer ${input:token}"}},
+        {"url": "https://example.com/mcp", "headers": {"Authorization": None}},
+        {"type": "http", "url": "https://example.com/sse"},
+        {"type": "http", "url": "https://example.com/sse "},
+        {"type": "streamableHttp", "url": "https://example.com/sse"},
+        {"url": "https://example.com/mcp", "timeout": 120},
+        {"url": "https://example.com/mcp", "timeoutMs": 120000},
+        {"url": "https://example.com/mcp", "timeoutSeconds": 120},
+        {"type": "sse", "url": "https://example.com/custom"},
+    ],
+)
+def test_parse_rejects_unrepresentable_imports(server):
+    entries, errors = parse_mcp_config({"servers": {"bad": server}})
+    assert entries == []
+    assert len(errors) == 1
+
+
+def test_servers_alias_key():
+    # VS Code uses "servers" instead of "mcpServers".
+    cfg = {"servers": {"fs": {"command": "node", "args": ["x.js"]}}}
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert len(entries) == 1
+
+
+def test_env_and_args_values_coerced_to_str():
+    cfg = {"mcpServers": {"fs": {"command": "node", "args": [8080], "env": {"PORT": 8080}}}}
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert entries[0].headers == {"PORT": "8080"}
+    assert mcp_client.parse_stdio_command(entries[0].url) == ["node", "8080"]
+
+
+def test_args_optional():
+    cfg = {"mcpServers": {"sqlite": {"command": "mcp-server-sqlite"}}}
+    entries, errors = parse_mcp_config(cfg)
+    assert errors == []
+    assert entries[0].url == "mcp-server-sqlite"
+    assert entries[0].headers is None
+
+
+def test_bad_entry_does_not_sink_batch():
+    cfg = {
+        "mcpServers": {
+            "good": {"command": "node", "args": ["x.js"]},
+            "both": {"command": "node", "url": "https://x/mcp"},
+            "neither": {"name": "oops"},
+            "bad_args": {"command": "node", "args": "x.js"},
+            "bad_env": {"command": "node", "env": ["NOT", "A", "DICT"]},
+        }
+    }
+    entries, errors = parse_mcp_config(cfg)
+    assert {e.display_name for e in entries} == {"good"}
+    assert len(errors) == 4
+
+
+def test_not_a_dict():
+    entries, errors = parse_mcp_config([])
+    assert entries == []
+    assert len(errors) == 1
+
+
+def test_missing_servers_key():
+    entries, errors = parse_mcp_config({"foo": {}})
+    assert entries == []
+    assert len(errors) == 1
+
+
+def test_servers_alias_error_names_actual_key():
+    entries, errors = parse_mcp_config({"servers": []})
+    assert entries == []
+    assert errors == ["'servers' must be an object mapping name -> server."]
+
+
+# ── 3. POST /import route ───────────────────────────────────────────
+
+
+def test_import_route_creates_and_dedups(tmp_path, monkeypatch):
+    import asyncio
+
+    from models.mcp_servers import McpServerImportRequest
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    _enable(monkeypatch)
+    cfg = {
+        "mcpServers": {
+            "fs": {
+                "command": "npx",
+                "args": ["-y", "server", "/tmp"],
+                "env": {"API_KEY": "sk"},
+            },
+            "remote": {"url": "https://example.com/mcp"},
+            "oauth": {
+                "type": "http",
+                "url": "https://auth.example.com/mcp",
+                "oauth": {"clientId": "client"},
+            },
+            "disabled": {
+                "url": "https://disabled.example.com/mcp",
+                "disabled": True,
+            },
+        }
+    }
+    res = asyncio.run(
+        routes_mcp.import_mcp_servers(McpServerImportRequest(config = cfg), current_subject = "u")
+    )
+    assert res.errors == []
+    assert res.skipped == []
+    assert {c.display_name for c in res.created} == {"fs", "remote", "oauth", "disabled"}
+    fs = next(c for c in res.created if c.display_name == "fs")
+    assert fs.headers == {"API_KEY": "sk"}
+    assert fs.use_oauth is False
+    assert fs.is_enabled is True
+    oauth = next(c for c in res.created if c.display_name == "oauth")
+    assert oauth.use_oauth is True
+    disabled = next(c for c in res.created if c.display_name == "disabled")
+    assert disabled.is_enabled is False
+
+    # Re-importing the same config skips both by url.
+    res2 = asyncio.run(
+        routes_mcp.import_mcp_servers(McpServerImportRequest(config = cfg), current_subject = "u")
+    )
+    assert res2.created == []
+    assert set(res2.skipped) == {"fs", "remote", "oauth", "disabled"}
+
+
+def test_import_route_gates_stdio_when_disabled(tmp_path, monkeypatch):
+    import asyncio
+
+    from models.mcp_servers import McpServerImportRequest
+    import routes.mcp_servers as routes_mcp
+
+    _reset_db(tmp_path, monkeypatch)
+    _disable(monkeypatch)
+    cfg = {
+        "mcpServers": {
+            "fs": {"command": "npx", "args": ["server"]},
+            "remote": {"url": "https://example.com/mcp"},
+        }
+    }
+    res = asyncio.run(
+        routes_mcp.import_mcp_servers(McpServerImportRequest(config = cfg), current_subject = "u")
+    )
+    # Remote still imports; the stdio entry is rejected per-entry (gate off).
+    assert {c.display_name for c in res.created} == {"remote"}
+    assert any("fs" in err for err in res.errors)
+    assert len(mcp_servers_db.list_servers()) == 1
diff --git a/studio/frontend/src/features/chat/api/mcp-servers-api.ts b/studio/frontend/src/features/chat/api/mcp-servers-api.ts
index be88d12664..0dc0719da4 100644
--- a/studio/frontend/src/features/chat/api/mcp-servers-api.ts
+++ b/studio/frontend/src/features/chat/api/mcp-servers-api.ts
@@ -21,6 +21,12 @@ export interface McpServerProbeResult {
   error: string | null;
 }
 
+export interface McpServerImportResult {
+  created: McpServerConfig[];
+  skipped: string[];
+  errors: string[];
+}
+
 function parseErrorText(status: number, body: unknown): string {
   if (body && typeof body === "object") {
     const { detail, message } = body as { detail?: unknown; message?: unknown };
@@ -114,3 +120,12 @@ export function testMcpServer(payload: {
     },
   });
 }
+
+// Bulk-import servers from a standard mcpServers JSON config (Claude Desktop,
+// Cursor, Cline, VS Code). The backend skips duplicates and reports per-entry
+// errors instead of failing the whole batch.
+export function importMcpServers(
+  config: unknown,
+): Promise<McpServerImportResult> {
+  return mcpRequest("/import", { method: "POST", body: { config } });
+}
diff --git a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
index f78784b436..17d6d1e9ec 100644
--- a/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-mcp-servers-dialog.tsx
@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
-import { useCallback, useEffect, useState } from "react";
+import { type ChangeEvent, useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import { Delete02Icon, Edit03Icon, PlusSignIcon } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
-import { RefreshCwIcon } from "lucide-react";
+import { RefreshCwIcon, UploadIcon } from "lucide-react";
 
 import { Button } from "@/components/ui/button";
 import {
@@ -23,6 +23,7 @@ import {
   type McpServerConfig,
   createMcpServer,
   deleteMcpServer,
+  importMcpServers,
   listMcpServers,
   refreshMcpServerTools,
   testMcpServer,
@@ -194,7 +195,9 @@ export function ChatMcpServersDialog({
   const [form, setForm] = useState<FormState>(EMPTY_FORM);
   const [saving, setSaving] = useState(false);
   const [testing, setTesting] = useState(false);
+  const [importing, setImporting] = useState(false);
   const [refreshingId, setRefreshingId] = useState<string | null>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
 
   const refresh = useCallback(async () => {
     setLoading(true);
@@ -315,6 +318,49 @@ export function ChatMcpServersDialog({
     }
   }
 
+  async function onImportFile(e: ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    e.target.value = ""; // let the user re-pick the same file later
+    if (!file) return;
+    let config: unknown;
+    try {
+      config = JSON.parse(await file.text());
+    } catch {
+      toast.error("Invalid JSON file");
+      return;
+    }
+    setImporting(true);
+    try {
+      const result = await importMcpServers(config);
+      const parts = [`${result.created.length} added`];
+      if (result.skipped.length) parts.push(`${result.skipped.length} skipped`);
+      if (result.errors.length) {
+        parts.push(
+          `${result.errors.length} error${result.errors.length === 1 ? "" : "s"}`,
+        );
+      }
+      const summary = parts.join(", ");
+      if (result.errors.length) {
+        toast.warning(summary, {
+          description: (
+            <div className="whitespace-pre-line">
+              {result.errors.slice(0, 5).join("\n")}
+            </div>
+          ),
+        });
+      } else {
+        toast.success(summary);
+      }
+      await refresh();
+    } catch (err) {
+      toast.error("Import failed", {
+        description: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setImporting(false);
+    }
+  }
+
   async function removeServer(server: McpServerConfig) {
     const ok = window.confirm(`Delete MCP server "${server.display_name}"?`);
     if (!ok) return;
@@ -385,9 +431,35 @@ export function ChatMcpServersDialog({
             Register remote (HTTP) or local (stdio command) MCP servers.
           </DialogDescription>
         </DialogHeader>
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept="application/json,.json"
+          className="hidden"
+          onChange={onImportFile}
+        />
 
         {showForm ? (
           <div className="flex flex-col gap-4">
+            {view.kind === "create" && (
+              <div className="flex items-center justify-between gap-3 rounded-md border border-dashed px-3 py-2">
+                <span className="text-xs text-muted-foreground">
+                  Import servers from a config file.
+                </span>
+                <Button
+                  type="button"
+                  size="sm"
+                  variant="outline"
+                  className="shrink-0"
+                  onClick={() => fileInputRef.current?.click()}
+                  disabled={importing}
+                  title="Import servers from a mcpServers JSON config (Claude Desktop, Cursor, VS Code…)"
+                >
+                  {importing ? <Spinner /> : <UploadIcon size={14} />}
+                  Import config
+                </Button>
+              </div>
+            )}
             <div className="grid gap-2">
               <Label htmlFor="mcp-display-name">Display name</Label>
               <Input
@@ -467,7 +539,17 @@ export function ChatMcpServersDialog({
           </div>
         ) : (
           <div className="flex min-w-0 flex-col gap-3">
-            <div className="flex justify-end">
+            <div className="flex justify-end gap-2">
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={() => fileInputRef.current?.click()}
+                disabled={importing}
+                title="Import servers from a mcpServers JSON config (Claude Desktop, Cursor, VS Code…)"
+              >
+                {importing ? <Spinner /> : <UploadIcon size={14} />}
+                Import config
+              </Button>
               <Button size="sm" onClick={startCreate}>
                 <HugeiconsIcon icon={PlusSignIcon} size={14} />
                 Add server

From 120daf9d8b93aa737dd32f5f17558ac509ec7142 Mon Sep 17 00:00:00 2001
From: Viktor Ferenczi <viktor@ferenczi.eu>
Date: Thu, 11 Jun 2026 17:21:48 +0200
Subject: [PATCH 209/222] fix(studio/rocm): don't stack ROCR_VISIBLE_DEVICES on
 HIP_VISIBLE_DEVICES (#6176)

When pinning GPUs for the llama-server child, the ROCm path set both
HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES to the same physical
indices. These masks filter at different layers and stack:
ROCR_VISIBLE_DEVICES reduces the visible set at the HSA/ROCr layer and
re-indexes from 0, then HIP_VISIBLE_DEVICES indexes into that reduced
set. _select_gpus ranks by free VRAM and picks the most-free card, so a
single non-zero pin (e.g. "1") becomes out of range at the HIP layer,
HIP enumerates 0 devices, and the model silently runs on CPU
("ggml_cuda_init: failed to initialize ROCm: no ROCm-capable device is
detected").

Set only HIP_VISIBLE_DEVICES (which narrows correctly on its own) and
clear any inherited ROCR mask so it can't double up.

Verified on a 2x Radeon AI PRO R9700 (gfx1201) host, ROCm 7.1.1: the
same selected=[1] load that fell back to CPU (~7.7 tok/s) now runs on
the GPU (~78 tok/s).

Fixes #6175

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 studio/backend/core/inference/llama_cpp.py | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 2560f9e5ac..b83e4e6961 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3479,7 +3479,7 @@ class LlamaCppBackend:
 
                 # Pin to selected GPU(s). On ROCm, narrowing only
                 # CUDA_VISIBLE_DEVICES leaves an AMD child seeing the full
-                # HIP/ROCR set, so set those too.
+                # set, so set HIP_VISIBLE_DEVICES too.
                 if gpu_indices is not None:
                     pinned = ",".join(str(i) for i in gpu_indices)
                     env["CUDA_VISIBLE_DEVICES"] = pinned
@@ -3487,7 +3487,19 @@ class LlamaCppBackend:
                         import torch as _torch
                         if getattr(_torch.version, "hip", None) is not None:
                             env["HIP_VISIBLE_DEVICES"] = pinned
-                            env["ROCR_VISIBLE_DEVICES"] = pinned
+                            # Do NOT also set ROCR_VISIBLE_DEVICES to the same
+                            # value. ROCR_VISIBLE_DEVICES filters at the HSA/ROCr
+                            # layer and HIP_VISIBLE_DEVICES at the HIP layer, so
+                            # setting both with the same physical indices applies
+                            # the mask twice: ROCR reduces the visible set and
+                            # re-indexes it from 0, then HIP indexes into the
+                            # already-reduced set. A single non-zero pin (e.g.
+                            # "1") then points out of range at the HIP layer, HIP
+                            # enumerates 0 devices, and llama.cpp falls back to
+                            # CPU ("ggml_cuda_init: no ROCm-capable device is
+                            # detected"). The HIP mask alone narrows correctly;
+                            # clear any inherited ROCR mask so it can't double up.
+                            env.pop("ROCR_VISIBLE_DEVICES", None)
                     except Exception as e:
                         logger.debug("Failed to set ROCm visibility env vars for child: %s", e)
 

From 181288e1184746bf904dc0976ff15f1b63dfef50 Mon Sep 17 00:00:00 2001
From: Ritwij Aryan Parmar <88580521+RitwijParmar@users.noreply.github.com>
Date: Thu, 11 Jun 2026 11:35:50 -0400
Subject: [PATCH 210/222] fix(studio): handle empty Responses tool output
 (#6167)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

• fix: handle empty responses tool output

Normalize empty Responses `function_call_output.output` values before converting them into Chat Completions `role="tool"` messages. Empty strings, whitespace-only strings, and empty arrays now use the existing no-output sentinel, while non-empty text and content arrays are preserved.

Add regression coverage for empty tool outputs, image payloads outside `output`, content-array serialization, validator round trips, and preserving non-empty text.

---------

Co-authored-by: wasimysaid <wasimysdev@gmail.com>
Co-authored-by: Tai An <antai12232931@outlook.com>
Co-authored-by: Datta Nimmaturi <venkatadattasainimmaturi@gmail.com>
---
 studio/backend/routes/inference.py            |  18 ++-
 .../tests/test_responses_tool_passthrough.py  | 109 ++++++++++++++++++
 2 files changed, 123 insertions(+), 4 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 9dc9feb920..3333db9d07 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -4897,6 +4897,17 @@ def _responses_message_text(content: Union[str, list]) -> str:
     return "\n".join(parts)
 
 
+def _responses_tool_output_text(output: Union[str, list]) -> str:
+    """Return Chat Completions-safe content for a Responses tool result."""
+    if isinstance(output, str):
+        return output if output.strip() else "(no output)"
+
+    if output:
+        return json.dumps(output)
+
+    return "(no output)"
+
+
 def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
     """Convert a ResponsesRequest's ``input`` into a Chat-format ``ChatMessage`` list.
 
@@ -4956,10 +4967,9 @@ def _normalise_responses_input(payload: ResponsesRequest) -> list[ChatMessage]:
 
         if isinstance(item, ResponsesFunctionCallOutputInputItem):
             # Chat Completions `role="tool"` requires string content; serialize
-            # a Responses content-array output.
-            output = item.output
-            if not isinstance(output, str):
-                output = json.dumps(output)
+            # a Responses content-array output and keep empty outputs from
+            # tripping the stricter ChatMessage role validator.
+            output = _responses_tool_output_text(item.output)
             messages.append(
                 ChatMessage(
                     role = "tool",
diff --git a/studio/backend/tests/test_responses_tool_passthrough.py b/studio/backend/tests/test_responses_tool_passthrough.py
index beeee66b77..69fb0a78c2 100644
--- a/studio/backend/tests/test_responses_tool_passthrough.py
+++ b/studio/backend/tests/test_responses_tool_passthrough.py
@@ -58,6 +58,7 @@ from routes.inference import (
     _build_chat_request,
     _chat_tool_calls_to_responses_output,
     _normalise_responses_input,
+    _responses_tool_output_text,
     _responses_stream,
     _translate_responses_tool_choice_to_chat,
     _translate_responses_tools_to_chat,
@@ -393,6 +394,100 @@ class TestNormaliseResponsesInputWithTools:
         # Content is serialised so llama-server sees a string.
         assert json.loads(msgs[0].content) == [{"type": "output_text", "text": "ok"}]
 
+    def test_empty_function_call_output_gets_no_output_sentinel(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": "",
+                }
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        assert msgs[0].role == "tool"
+        assert msgs[0].tool_call_id == "call_1"
+        assert msgs[0].content == "(no output)"
+        ChatMessage(**msgs[0].model_dump(exclude_none = True))
+
+    def test_whitespace_function_call_output_gets_no_output_sentinel(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": "   \n\t",
+                }
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        assert msgs[0].content == "(no output)"
+
+    def test_empty_content_array_output_gets_no_output_sentinel(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": [],
+                }
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        assert msgs[0].content == "(no output)"
+
+    def test_image_content_array_tool_output_is_serialised(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": "iVBORw0KGgo=",
+                            },
+                        }
+                    ],
+                }
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        assert msgs[0].role == "tool"
+        assert json.loads(msgs[0].content)[0]["type"] == "image"
+
+    def test_image_payload_outside_output_gets_no_output_sentinel(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_1",
+                    "output": "",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": "iVBORw0KGgo=",
+                            },
+                        }
+                    ],
+                }
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        assert msgs[0].role == "tool"
+        assert msgs[0].tool_call_id == "call_1"
+        assert msgs[0].content == "(no output)"
+
+    def test_tool_output_serializer_preserves_non_empty_text(self):
+        assert _responses_tool_output_text("done") == "done"
+        assert _responses_tool_output_text("  done  ") == "  done  "
+
 
 # =====================================================================
 # Response mapping — tool_calls → function_call output items
@@ -810,3 +905,17 @@ class TestTranslatedMessagesValidate:
             # Building a fresh ChatMessage from the dump round-trips the
             # role-shape validator — the passthrough's key invariant.
             ChatMessage(**m.model_dump(exclude_none = True))
+
+    def test_empty_tool_output_round_trips_through_chat_message_validator(self):
+        payload = ResponsesRequest(
+            input = [
+                {
+                    "type": "function_call_output",
+                    "call_id": "call_empty",
+                    "output": "",
+                },
+            ],
+        )
+        msgs = _normalise_responses_input(payload)
+        for m in msgs:
+            ChatMessage(**m.model_dump(exclude_none = True))

From 3964f44f02e4736a471e96cc6926bf717e0d4add Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Thu, 11 Jun 2026 10:39:36 -0500
Subject: [PATCH 211/222] fix(rocm): stop overwriting ROCR_VISIBLE_DEVICES in
 apply_gpu_ids (#6123)

* fix(rocm): stop overwriting ROCR_VISIBLE_DEVICES in apply_gpu_ids

ROCR_VISIBLE_DEVICES uses HSA agent-level indexing, not physical GPU
indices. Setting it to a bare integer breaks multi-GPU ROCm systems
where the parent already set ROCR_VISIBLE_DEVICES=0,1: narrowing to
1 causes torch.cuda.is_available() to return False in the training
worker, producing a misleading 'no HIP accelerator' error even on a
correctly configured ROCm host.

HIP_VISIBLE_DEVICES is sufficient for GPU selection on ROCm.
Leave ROCR_VISIBLE_DEVICES inherited from the parent environment.

* test(rocm): update apply_gpu_ids test to assert ROCR_VISIBLE_DEVICES is not overwritten
---
 studio/backend/utils/hardware/hardware.py |  8 +++++++-
 tests/studio/install/test_rocm_support.py | 10 +++++++---
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index 7292fa185f..893d0364f7 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -1818,7 +1818,13 @@ def apply_gpu_ids(gpu_ids) -> None:
             )
     if _is_rocm:
         os.environ["HIP_VISIBLE_DEVICES"] = value
-        os.environ["ROCR_VISIBLE_DEVICES"] = value
+        # ROCR_VISIBLE_DEVICES operates at the HSA agent level and uses
+        # different indexing semantics to HIP_VISIBLE_DEVICES. Setting it
+        # to a physical GPU index breaks multi-GPU ROCm systems where the
+        # parent already set ROCR_VISIBLE_DEVICES (e.g. "0,1"): narrowing
+        # to "1" causes torch.cuda.is_available() to return False in the
+        # worker subprocess. HIP_VISIBLE_DEVICES is sufficient for GPU
+        # selection on ROCm -- leave ROCR_VISIBLE_DEVICES inherited.
     _visible_gpu_count = None
     if _is_rocm:
         logger.info("Applied gpu_ids: CUDA_VISIBLE_DEVICES='%s' (rocm)", value)
diff --git a/tests/studio/install/test_rocm_support.py b/tests/studio/install/test_rocm_support.py
index 7d1ae535fd..9aa06b6ff7 100644
--- a/tests/studio/install/test_rocm_support.py
+++ b/tests/studio/install/test_rocm_support.py
@@ -1614,14 +1614,18 @@ class TestApplyGpuIdsRocmFallback:
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert 'getattr(_torch.version, "hip", None)' in func_body
 
-    def test_apply_gpu_ids_sets_hip_and_rocr_visible_devices(self):
-        """apply_gpu_ids should set both HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES on ROCm."""
+    def test_apply_gpu_ids_sets_hip_but_not_rocr_visible_devices(self):
+        """apply_gpu_ids should set HIP_VISIBLE_DEVICES but leave ROCR_VISIBLE_DEVICES inherited.
+
+        ROCR_VISIBLE_DEVICES uses HSA agent-level indexing, not physical GPU indices.
+        Overwriting it breaks multi-GPU ROCm systems (see issue #6118).
+        """
         hw_path = PACKAGE_ROOT / "studio" / "backend" / "utils" / "hardware" / "hardware.py"
         source = hw_path.read_text(encoding = "utf-8")
         func_start = source.find("def apply_gpu_ids")
         func_body = source[func_start : source.find("\ndef ", func_start + 1)]
         assert 'os.environ["HIP_VISIBLE_DEVICES"] = value' in func_body
-        assert 'os.environ["ROCR_VISIBLE_DEVICES"] = value' in func_body
+        assert 'os.environ["ROCR_VISIBLE_DEVICES"] = value' not in func_body
 
     def test_apply_gpu_ids_rocm_fallback_is_guarded_by_try_except(self):
         """torch import in apply_gpu_ids must be wrapped in try/except so a missing torch never crashes."""

From 73eed19ce4b3cbf11366f8f433614a3be8f30254 Mon Sep 17 00:00:00 2001
From: Tai An <antai12232931@outlook.com>
Date: Thu, 11 Jun 2026 08:53:13 -0700
Subject: [PATCH 212/222] fix(_utils): coerce _is_package_available tuple to
 bool for flash_attn/vllm checks (#6168)

transformers >= 5.x makes _is_package_available always return a
(exists, version) tuple, which is truthy even when the package is
absent. The flash_attn and vLLM availability checks treated the result
as a bool, so they always entered the "package present" branch:

- flash_attn (CUDA + HIP): the inner import raises when flash-attn is
  not installed, printing a false "Flash Attention 2 installation seems
  to be broken" warning before falling back to xformers.
- is_vLLM_available(): always reported vLLM as installed.

Add a small _package_available() helper that normalises the result to a
bool (handling both the new tuple and the legacy bool return), and route
the three call sites through it.

Fixes #6155

Co-authored-by: Lee Jackson <130007945+Imagineer99@users.noreply.github.com>
---
 unsloth/models/_utils.py | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 1a86ff8eb6..a2ab3149f1 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -1264,6 +1264,18 @@ if is_openai_available():
 from transformers import AutoTokenizer
 from transformers.utils.import_utils import _is_package_available
 
+
+def _package_available(pkg_name: str) -> bool:
+    # transformers >= 5.x makes `_is_package_available` always return a
+    # `(exists, version)` tuple, which is truthy even when the package is
+    # absent; older versions returned a plain bool. Normalise to a bool so
+    # callers don't take "package present" branches for missing packages.
+    result = _is_package_available(pkg_name)
+    if isinstance(result, tuple):
+        return bool(result[0])
+    return bool(result)
+
+
 SUPPORTS_BFLOAT16 = False
 HAS_FLASH_ATTENTION = False
 HAS_FLASH_ATTENTION_SOFTCAPPING = False
@@ -1274,7 +1286,7 @@ if DEVICE_TYPE == "cuda":
 
     if major_version >= 8:
         SUPPORTS_BFLOAT16 = True
-        if _is_package_available("flash_attn"):
+        if _package_available("flash_attn"):
             # Check for CUDA linking errors "undefined symbol: _ZNK3c106SymIntltEl"
             try:
                 try:
@@ -1319,7 +1331,7 @@ if DEVICE_TYPE == "cuda":
         HAS_FLASH_ATTENTION = False
 elif DEVICE_TYPE == "hip":
     SUPPORTS_BFLOAT16 = True
-    if _is_package_available("flash_attn"):
+    if _package_available("flash_attn"):
         # Check for CUDA linking errors "undefined symbol: _ZNK3c106SymIntltEl"
         try:
             try:
@@ -1981,7 +1993,7 @@ def is_bfloat16_supported():
 
 
 def is_vLLM_available():
-    return _is_package_available("vllm")
+    return _package_available("vllm")
 
 
 # Patches models to add RoPE Scaling

From bda67b549150835af13686bcec1eea644c6c89e4 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 09:18:39 -0700
Subject: [PATCH 213/222] Update _utils.py

---
 unsloth/models/_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index a2ab3149f1..6baa9a1398 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2026.6.2"
+__version__ = "2026.6.3"
 
 __all__ = [
     "SUPPORTS_BFLOAT16",

From ddaa8a9cb5862515d020f8aa53b8e936ae86d1e6 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 09:19:10 -0700
Subject: [PATCH 214/222] Update pyproject.toml

---
 pyproject.toml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 9f6465d3a3..16fd9f833f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,7 +70,7 @@ triton = [
 ]
 
 huggingfacenotorch = [
-    "unsloth_zoo>=2026.6.2",
+    "unsloth_zoo>=2026.6.3",
     "wheel>=0.42.0",
     "packaging",
     "numpy",
@@ -91,7 +91,7 @@ huggingfacenotorch = [
 ]
 huggingface = [
     "unsloth[huggingfacenotorch]",
-    "unsloth_zoo>=2026.6.2",
+    "unsloth_zoo>=2026.6.3",
     "torchvision",
     "unsloth[triton]",
 ]
@@ -581,7 +581,7 @@ colab-ampere-torch220 = [
     "flash-attn>=2.6.3 ; ('linux' in sys_platform)",
 ]
 colab-new = [
-    "unsloth_zoo>=2026.6.2",
+    "unsloth_zoo>=2026.6.3",
     "packaging",
     "tyro",
     "transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",

From b2b1dcd6ad72addde9a4324d15a2966fd0df6437 Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Thu, 11 Jun 2026 09:27:34 -0700
Subject: [PATCH 215/222] Studio: llama.cpp update banner redesign, About tab
 license info, UI polish (#6196)

* Studio: llama.cpp update banner redesign, About tab license info, inline system prompt editing, naming cleanup

- Redesign the llama.cpp update banner to match the chat composer surface
  (borderless rounded card, composer shadow, Hellix Medium title), rename
  actions to Update and add a 15 minute Remind me later snooze
- Keep the banner up until the user explicitly acts on it; drop the
  outside click dismissal
- Add a Settings > General > Notifications toggle to disable the banner
  for training-only setups (on by default)
- Rename the Help settings tab to About and add a License section
  (Unsloth Studio AGPL-3.0, Unsloth Core Apache-2.0) linking to the
  license files in this repo
- Make the run settings system prompt box an inline editable textarea;
  the popup editor opens when the prompt overflows the box
- Pointer cursor on the preset dropdown chevron
- Dark mode toasts use the chat composer surface color
- Replace standalone Studio with Unsloth in user facing strings; keep
  Unsloth Studio, LM Studio, Fine-tuning Studio, Recipe Studio and CLI
  commands unchanged

* Studio: open the system prompt popup on box click, balance banner padding

- The system prompt box opens the Edit System Prompt dialog on click,
  matching the pencil action
- Slightly more bottom padding on the llama.cpp update banner so the
  spacing reads even next to the action pills

* Studio: replace unsloth studio update with the installer commands in update guidance

- The unsloth studio update command no longer works, so the About tab
  update section now shows the one-line installer (curl or irm) for
  PyPI and unknown installs, and git pull plus the local installer for
  checkouts
- Add a short note that unsloth studio update is no longer supported
- Link the Installation, Updating and Windows install docs pages
- The package update banner now copies the platform installer command
  instead of unsloth studio update

* Studio: rounder account menu, inline system prompt box with popup from the label

- Account menu corners go from 14px to 18px via a specific override,
  since list menus pin border-radius globally
- llama.cpp banner bottom padding 22px
- System prompt is an inline editable textarea again; clicking the
  System Prompt label opens the popup editor, and an overflowing
  prompt opens it on box click

* Studio: show the standard install commands in the About update section

- Both one-line install commands (MacOS/Linux/WSL and Windows
  PowerShell) are always shown, labeled like the docs, since running
  them again updates an existing install
- Drop the unsloth studio update deprecation note
- Add the Mac install guide to the docs links

* Studio: clearer platform toggle and layout in the About update section

- Section heading is Update
- Platform picker is a pair of pill buttons, MacOS / Linux and Windows,
  and only the selected platform's install command is shown
- Intro reads: To install or update Unsloth
- Local update heading separates checkout guidance from the standard
  install command

* Studio: report GitHub branch instead of dev for source checkouts

A source checkout not on an exact release tag now shows
GitHub <branch> (e.g. GitHub main) as the Studio version in About.
Detached or unusual HEADs still fall back to dev.

* Studio: tighten the About update section copy and toggle styling

- Platform toggle buttons are borderless pills
- Shorter local update wording and restart note
- Docs links read Mac and Windows

* Studio: tighten line spacing in the sidebar account button

* Studio: fix vanishing compact MCP icon on hover, single line pill tooltips

- Compact caret pills (MCP, RAG) keep their icon on hover for inactive
  pills too; the off switch hover rules hid the icon while compact mode
  hid the X, leaving an empty slot
- Compact icon tooltips and single line compact tooltips render as full
  pills; wrapped tooltips keep the 9px corners. TooltipContent measures
  line count in a ref callback since Radix mounts portal content
  without re-rendering the wrapper
- 1px gap between the name and Unsloth lines in the sidebar account
  button

* Studio: Projects hover plus button, align recents with the label

- Hovering the Projects nav item reveals a plus button that opens the
  New project dialog, with the same circular hover treatment as the
  chat row actions
- Recent chat titles start at the same x as the Recents label
- The system prompt overflow lock only engages for a non-empty prompt
  with a laid-out box, so a mis-measure cannot turn clicks into the
  popup

* Clip system prompt overflow inside the rounded box

Wrap the inline system prompt textarea in a rounded overflow-hidden
surface so scrolled text and the scrollbar stay inside the box. The
focus ring moves to the wrapper via focus-within.

* Add updating progress bar to llama banner and shorten settings copy

While an update is applying, the banner action row becomes an
indeterminate progress bar that keeps animating under reduced motion,
matching the other loading indicators. Settings descriptions across
General, Profile, Appearance, Chat, Connections, API, and About are
trimmed without losing meaning.

* Address review: desktop update note, server platform detection, zh-CN keys

The About tab no longer shows terminal install commands in the desktop
app, where the bundled backend updates through the built-in updater;
it shows a short note and the docs links instead.

fetchDeviceType now sends the auth token to /api/health, which only
reports the server platform to authed callers, and caches only a
server-reported value. Copied install commands then match the host
platform rather than the browser when they differ (WSL, SSH).

zh-CN gains translations for the new notification and license keys,
the renamed About tab title, and the desktop update note.

* Real download progress for llama.cpp updates, prompt and sidebar polish

The update worker now streams the installer output and parses its
download percent lines into job progress, exposed via the update-status
API. The installer emits finer non-tty milestones when
UNSLOTH_PROGRESS_PERCENT_STEP is set; the worker requests 5 percent
steps. The banner renders a determinate bar from the reported fraction
and falls back to the sweep until the first percent arrives.

Also removes the focus ring on the inline system prompt box and
slightly shrinks the Projects hover plus icon.
---
 studio/backend/routes/llama.py                |   1 +
 studio/backend/tests/test_llama_cpp_update.py | 130 +++++----
 studio/backend/utils/llama_cpp_update.py      |  53 +++-
 studio/backend/utils/studio_version.py        |  35 ++-
 .../frontend/src/components/app-sidebar.tsx   |  29 +-
 .../src/components/llama-update-banner.tsx    | 117 ++++----
 .../src/components/tauri/startup-screen.tsx   |   2 +-
 studio/frontend/src/components/ui/tooltip.tsx |  18 ++
 .../src/components/web/update-banner.tsx      |  16 +-
 studio/frontend/src/config/env.ts             |  20 +-
 studio/frontend/src/features/auth/api.ts      |   2 +-
 .../src/features/auth/tauri-auto-auth.ts      |   2 +-
 .../studio-web-speech-dictation-adapter.ts    |   4 +-
 .../features/chat/chat-providers-dialog.tsx   |   2 +-
 .../src/features/chat/chat-settings-sheet.tsx |  61 +++-
 .../frontend/src/features/chat/tour/steps.tsx |   4 +-
 .../chat/utils/chat-history-storage.ts        |   2 +-
 .../src/features/hub/download-manager/api.ts  |   6 +-
 .../download-manager/download-api-adapter.ts  |   2 +-
 .../executions/execution-data-tab.tsx         |   2 +-
 .../executions/execution-overview-tab.tsx     |   2 +-
 .../runtime/execution-progress-island.tsx     |   2 +-
 .../dialogs/seed/seed-dialog.tsx              |   6 +-
 .../components/update-studio-instructions.tsx | 265 +++++++++++-------
 .../src/features/settings/tabs/about-tab.tsx  |  33 ++-
 .../features/settings/tabs/general-tab.tsx    |  21 ++
 .../src/features/studio/tour/steps/nav.tsx    |   2 +-
 .../src/hooks/use-llama-update-check.ts       |  33 ++-
 .../src/hooks/use-llama-update-pref.ts        |  49 ++++
 .../frontend/src/hooks/use-tauri-backend.ts   |  22 +-
 studio/frontend/src/i18n/locales/en.ts        | 107 ++++---
 studio/frontend/src/i18n/locales/zh-CN.ts     |  65 +++--
 studio/frontend/src/index.css                 |  41 ++-
 studio/install_llama_prebuilt.py              |  14 +-
 34 files changed, 831 insertions(+), 339 deletions(-)
 create mode 100644 studio/frontend/src/hooks/use-llama-update-pref.ts

diff --git a/studio/backend/routes/llama.py b/studio/backend/routes/llama.py
index b30c0f5aea..47a5bc1dd3 100644
--- a/studio/backend/routes/llama.py
+++ b/studio/backend/routes/llama.py
@@ -31,6 +31,7 @@ class LlamaUpdateJob(BaseModel):
     from_tag: Optional[str] = None
     to_tag: Optional[str] = None
     error: Optional[str] = None
+    progress: Optional[float] = Field(None, description = "0..1 while running, 1 on success.")
     started_at: Optional[str] = None
     finished_at: Optional[str] = None
 
diff --git a/studio/backend/tests/test_llama_cpp_update.py b/studio/backend/tests/test_llama_cpp_update.py
index 05a107377c..d21d653b76 100644
--- a/studio/backend/tests/test_llama_cpp_update.py
+++ b/studio/backend/tests/test_llama_cpp_update.py
@@ -28,6 +28,55 @@ import utils.llama_cpp_update as upd  # noqa: E402
 MARKER = "UNSLOTH_PREBUILT_INFO.json"
 
 
+class _FakeInstallerPopen:
+    """Stands in for the streamed installer process in _run_update."""
+
+    def __init__(
+        self,
+        cmd,
+        *,
+        returncode = 0,
+        lines = None,
+        on_start = None,
+        captured_kwargs = None,
+        **kwargs,
+    ):
+        if captured_kwargs is not None:
+            captured_kwargs.update(kwargs)
+        if on_start is not None:
+            on_start(list(cmd))
+        self.returncode = returncode
+        self.stdout = iter(lines or [])
+
+    def wait(self):
+        return self.returncode
+
+    def kill(self):
+        pass
+
+
+def _patch_installer_popen(
+    monkeypatch,
+    *,
+    returncode = 0,
+    lines = None,
+    on_start = None,
+    captured_kwargs = None,
+):
+    monkeypatch.setattr(
+        upd.subprocess,
+        "Popen",
+        lambda cmd, **kw: _FakeInstallerPopen(
+            cmd,
+            returncode = returncode,
+            lines = lines,
+            on_start = on_start,
+            captured_kwargs = captured_kwargs,
+            **kw,
+        ),
+    )
+
+
 def _write_install(
     dir_: Path,
     tag: str,
@@ -260,14 +309,15 @@ def test_start_update_source_build_installs_prebuilt(monkeypatch, tmp_path):
 
     def _fake_run(cmd, **kwargs):
         cmd = list(cmd)
-        # Status polls probe `llama-server --version`; keep the installer argv.
-        if "--version" in cmd:
-            return _Proc()
-        captured["cmd"] = cmd
-        _write_install(install_dir, "b9585")  # installer writes the marker
+        assert "--version" in cmd  # only status polls still use run()
         return _Proc()
 
+    def _on_start(cmd):
+        captured["cmd"] = cmd
+        _write_install(install_dir, "b9585")  # installer writes the marker
+
     monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    _patch_installer_popen(monkeypatch, on_start = _on_start)
 
     res = upd.start_update()
     assert res["started"] is True, res
@@ -298,21 +348,27 @@ def test_start_update_happy_path(monkeypatch, tmp_path):
         stdout = "installed"
         stderr = ""
 
-    def _fake_run(cmd, **kwargs):
-        cmd = list(cmd)
-        # Status polls probe `llama-server --version`; keep the installer argv.
-        if "--version" in cmd:
-            return _Proc()
+    def _on_start(cmd):
         captured["cmd"] = cmd
         # Simulate the installer writing a new marker with the latest tag.
         _write_install(install_dir, "b9518")
-        return _Proc()
 
-    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    popen_kwargs: dict = {}
+    _patch_installer_popen(
+        monkeypatch,
+        lines = [
+            "[llama-prebuilt] resolving release\n",
+            "Downloading llama.zip:  35.0% (12.0 MiB/35.0 MiB) at 9.0 MiB/s\n",
+            "Downloading llama.zip:  80.0% (28.0 MiB/35.0 MiB) at 9.0 MiB/s\n",
+        ],
+        on_start = _on_start,
+        captured_kwargs = popen_kwargs,
+    )
 
     res = upd.start_update()
     assert res["started"] is True
     assert res["job"]["from_tag"] == "b9493"
+    assert res["job"]["progress"] == 0.0
 
     # Wait for the background worker.
     deadline = time.time() + 10
@@ -328,6 +384,10 @@ def test_start_update_happy_path(monkeypatch, tmp_path):
     assert str(install_dir) in captured["cmd"]
     assert "--llama-tag" in captured["cmd"] and "latest" in captured["cmd"]
     assert "unslothai/llama.cpp" in captured["cmd"]
+    # Progress lines were parsed and success pins progress at 1.0.
+    assert job["progress"] == 1.0
+    # The worker asks the installer for fine-grained progress milestones.
+    assert popen_kwargs["env"]["UNSLOTH_PROGRESS_PERCENT_STEP"] == "5"
 
 
 def test_start_update_installer_failure_reports_error(monkeypatch, tmp_path):
@@ -336,12 +396,7 @@ def test_start_update_installer_failure_reports_error(monkeypatch, tmp_path):
     monkeypatch.setattr(upd, "_find_binary", lambda: binary)
     monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
 
-    class _Proc:
-        returncode = 2
-        stdout = ""
-        stderr = "boom: network error"
-
-    monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+    _patch_installer_popen(monkeypatch, returncode = 2, lines = ["boom: network error\n"])
 
     res = upd.start_update()
     assert res["started"] is True
@@ -410,14 +465,15 @@ def _capture_install_cmd(
 
     def _fake_run(cmd, **kwargs):
         cmd = list(cmd)
-        # Status polls probe `llama-server --version`; keep the installer argv.
-        if "--version" in cmd:
-            return _Proc()
-        captured["cmd"] = cmd
-        _write_install(install_dir, latest, repo = repo, asset = asset)
+        assert "--version" in cmd  # only status polls still use run()
         return _Proc()
 
+    def _on_start(cmd):
+        captured["cmd"] = cmd
+        _write_install(install_dir, latest, repo = repo, asset = asset)
+
     monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    _patch_installer_popen(monkeypatch, on_start = _on_start)
 
     res = upd.start_update()
     assert res["started"] is True, res
@@ -535,18 +591,12 @@ def test_update_sets_maintenance_flag_and_unloads(monkeypatch, tmp_path):
 
     seen = {}
 
-    class _Proc:
-        returncode = 0
-        stdout = "ok"
-        stderr = ""
-
-    def _fake_run(cmd, **kwargs):
+    def _on_start(cmd):
         # The maintenance flag must be set while the installer runs.
         seen["flag_during_install"] = backend._llama_update_in_progress
         _write_install(install_dir, "b9518")
-        return _Proc()
 
-    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    _patch_installer_popen(monkeypatch, on_start = _on_start)
 
     res = upd.start_update()
     assert res["started"] is True
@@ -571,12 +621,7 @@ def test_update_clears_maintenance_flag_on_installer_failure(monkeypatch, tmp_pa
     backend = _FakeBackend()
     _inject_backend(monkeypatch, backend)
 
-    class _Proc:
-        returncode = 1
-        stdout = ""
-        stderr = "boom"
-
-    monkeypatch.setattr(upd.subprocess, "run", lambda cmd, **kw: _Proc())
+    _patch_installer_popen(monkeypatch, returncode = 1, lines = ["boom\n"])
 
     res = upd.start_update()
     assert res["started"] is True
@@ -606,16 +651,7 @@ def test_update_fails_open_when_backend_unavailable(monkeypatch, tmp_path):
     monkeypatch.setitem(sys.modules, "routes", routes_pkg)
     monkeypatch.setitem(sys.modules, "routes.inference", inference_mod)
 
-    class _Proc:
-        returncode = 0
-        stdout = "ok"
-        stderr = ""
-
-    def _fake_run(cmd, **kwargs):
-        _write_install(install_dir, "b9518")
-        return _Proc()
-
-    monkeypatch.setattr(upd.subprocess, "run", _fake_run)
+    _patch_installer_popen(monkeypatch, on_start = lambda cmd: _write_install(install_dir, "b9518"))
 
     res = upd.start_update()
     assert res["started"] is True
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index b138b29af3..55bf4b3d84 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -59,10 +59,17 @@ _job: dict = {
     "from_tag": None,
     "to_tag": None,
     "error": None,
+    "progress": None,
     "started_at": None,
     "finished_at": None,
 }
 
+# Matches the installer's download progress lines, e.g.
+# "Downloading x.zip:  35.0% (12.3 MiB/35.1 MiB) at 8.2 MiB/s".
+_PROGRESS_LINE_RE = re.compile(r"(\d+(?:\.\d+)?)%\s*\(")
+# The download dominates the update; extract/validate fill the last slice.
+_DOWNLOAD_PROGRESS_CEILING = 0.95
+
 
 def _utcnow() -> str:
     return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
@@ -357,15 +364,46 @@ def _run_update(install_dir: Path, repo: str, asset: Optional[str], script: Path
         ]
         cmd.extend(_rocm_install_args(asset))
         logger.info("llama update: installing", cmd = " ".join(cmd))
-        proc = subprocess.run(
+        # Stream the installer output so download percent lines feed
+        # job["progress"]; finer milestones via UNSLOTH_PROGRESS_PERCENT_STEP.
+        env = dict(os.environ, UNSLOTH_PROGRESS_PERCENT_STEP = "5")
+        proc = subprocess.Popen(
             cmd,
-            capture_output = True,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.STDOUT,
             text = True,
-            timeout = _INSTALL_TIMEOUT_SECONDS,
+            env = env,
         )
-        if proc.returncode != 0:
-            tail = (proc.stderr or proc.stdout or "").strip()[-1500:]
-            raise RuntimeError(f"installer exited {proc.returncode}: {tail or 'no output'}")
+        timed_out = threading.Event()
+
+        def _kill_on_timeout() -> None:
+            timed_out.set()
+            proc.kill()
+
+        watchdog = threading.Timer(_INSTALL_TIMEOUT_SECONDS, _kill_on_timeout)
+        watchdog.daemon = True
+        watchdog.start()
+        tail_lines: list[str] = []
+        try:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                tail_lines.append(line)
+                if len(tail_lines) > 80:
+                    del tail_lines[0]
+                m = _PROGRESS_LINE_RE.search(line)
+                if m is None:
+                    continue
+                fraction = min(float(m.group(1)) / 100.0, 1.0) * _DOWNLOAD_PROGRESS_CEILING
+                with _job_lock:
+                    _job["progress"] = max(_job.get("progress") or 0.0, fraction)
+            returncode = proc.wait()
+        finally:
+            watchdog.cancel()
+        if timed_out.is_set():
+            raise RuntimeError(f"installer timed out after {_INSTALL_TIMEOUT_SECONDS}s")
+        if returncode != 0:
+            tail = "".join(tail_lines).strip()[-1500:]
+            raise RuntimeError(f"installer exited {returncode}: {tail or 'no output'}")
 
         # New UNSLOTH_PREBUILT_INFO.json is on disk; drop caches so the next
         # status read reflects the freshly installed tag.
@@ -382,6 +420,7 @@ def _run_update(install_dir: Path, repo: str, asset: Optional[str], script: Path
                 ),
                 to_tag = new_tag,
                 error = None,
+                progress = 1.0,
                 finished_at = _utcnow(),
             )
         logger.info("llama update: success", to_tag = new_tag)
@@ -467,6 +506,7 @@ def start_update() -> dict:
             from_tag = from_tag,
             to_tag = None,
             error = None,
+            progress = 0.0,
             started_at = _utcnow(),
             finished_at = None,
         )
@@ -491,6 +531,7 @@ def _reset_job_for_tests() -> None:
             from_tag = None,
             to_tag = None,
             error = None,
+            progress = None,
             started_at = None,
             finished_at = None,
         )
diff --git a/studio/backend/utils/studio_version.py b/studio/backend/utils/studio_version.py
index 98c48fe45c..9c18070fbb 100644
--- a/studio/backend/utils/studio_version.py
+++ b/studio/backend/utils/studio_version.py
@@ -15,6 +15,7 @@ _DEV_VERSION = "dev"
 _GIT_TIMEOUT_SECONDS = 1.0
 _STUDIO_TAG_RE = re.compile(r"^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.][0-9A-Za-z.-]*)?$")
 _GIT_DESCRIBE_SUFFIX_RE = re.compile(r"-\d+-g[0-9A-Fa-f]+(?:-dirty)?$")
+_GIT_BRANCH_RE = re.compile(r"^[0-9A-Za-z._/-]+$")
 _MAX_VERSION_LENGTH = 64
 
 
@@ -71,6 +72,35 @@ def _exact_git_studio_tag(repo_root: Path) -> str | None:
     return tag if is_valid_studio_release_version(tag) else None
 
 
+def _git_branch(repo_root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd = repo_root,
+            check = False,
+            stdout = subprocess.PIPE,
+            stderr = subprocess.DEVNULL,
+            text = True,
+            timeout = _GIT_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    branch = result.stdout.strip()
+    # "HEAD" means detached, e.g. a tag or commit checkout.
+    if (
+        not branch
+        or branch == "HEAD"
+        or len(branch) > _MAX_VERSION_LENGTH
+        or _GIT_BRANCH_RE.fullmatch(branch) is None
+    ):
+        return None
+    return branch
+
+
 def get_studio_version(repo_root: Path | None = None) -> str:
     """Return the installed Studio release tag for display, or ``dev``.
 
@@ -81,7 +111,10 @@ def get_studio_version(repo_root: Path | None = None) -> str:
 
     if _is_source_checkout(resolved_repo_root):
         git_tag = _exact_git_studio_tag(resolved_repo_root)
-        return git_tag if git_tag is not None else _DEV_VERSION
+        if git_tag is not None:
+            return git_tag
+        branch = _git_branch(resolved_repo_root)
+        return f"GitHub {branch}" if branch is not None else _DEV_VERSION
 
     stamped_version = _studio_release_build.STUDIO_RELEASE_VERSION
     if is_valid_studio_release_version(stamped_version):
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 7baa69571c..f1a200b09b 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -60,6 +60,7 @@ import {
   Logout05Icon,
   MoreVerticalIcon,
   Search01Icon,
+  PlusSignIcon,
   PowerIcon,
   PencilEdit02Icon,
   LayoutAlignLeftIcon,
@@ -558,7 +559,8 @@ export function AppSidebar() {
         : "sidebar-row-action group-hover/recent-item:opacity-100 group-hover/recent-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto";
     const buttonClass = cn(
       "sidebar-nav-btn h-[33px] cursor-pointer rounded-full pr-4 text-[14.5px] leading-[19px] tracking-nav font-medium",
-      variant === "project" ? "pl-[39px]" : "pl-3",
+      // pl-3.5 starts the title at the same x as the Recents label text.
+      variant === "project" ? "pl-[39px]" : "pl-3.5",
       variant === "project"
         ? "group-hover/project-chat-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/project-chat-item:pr-8"
         : "group-hover/recent-item:pr-8 group-has-[.sidebar-row-action[data-state=open]]/recent-item:pr-8",
@@ -837,7 +839,28 @@ export function AppSidebar() {
                   navigate({ to: "/projects" });
                   closeMobileIfOpen();
                 }}
-              />
+                className="group/projects-item relative"
+              >
+                <button
+                  type="button"
+                  aria-label="New project"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    setProjectCreateMoveTarget(null);
+                    setProjectNameDraft("");
+                    setCreatingProject(true);
+                  }}
+                  className="sidebar-row-action group-hover/projects-item:opacity-100 group-hover/projects-item:pointer-events-auto focus-visible:opacity-100 focus-visible:pointer-events-auto group-data-[collapsible=icon]:hidden"
+                >
+                  <span className="sidebar-row-action-glyph">
+                    <HugeiconsIcon
+                      icon={PlusSignIcon}
+                      strokeWidth={1.75}
+                      className="size-4"
+                    />
+                  </span>
+                </button>
+              </NavItem>
               <NavItem
                 icon={DashboardCircleIcon}
                 label={t("shell.navigation.hub")}
@@ -1065,7 +1088,7 @@ export function AppSidebar() {
                       className="!size-[32px]"
                     />
                   </div>
-                  <div className="flex flex-col gap-0.5 leading-tight group-data-[collapsible=icon]:hidden">
+                  <div className="flex flex-col gap-px leading-tight group-data-[collapsible=icon]:hidden">
                     <span className="truncate font-heading text-[13.5px] tracking-[0.025em] dark:tracking-[0.04em] font-semibold text-nav-fg">{displayTitle}</span>
                     <span className="truncate text-[11.5px] tracking-nav text-muted-foreground">Unsloth</span>
                   </div>
diff --git a/studio/frontend/src/components/llama-update-banner.tsx b/studio/frontend/src/components/llama-update-banner.tsx
index c8a4dd1e40..83320f8e15 100644
--- a/studio/frontend/src/components/llama-update-banner.tsx
+++ b/studio/frontend/src/components/llama-update-banner.tsx
@@ -3,9 +3,10 @@
 
 import { Button } from "@/components/ui/button";
 import { useLlamaUpdateCheck } from "@/hooks/use-llama-update-check";
+import { useShowLlamaUpdateBanner } from "@/hooks/use-llama-update-pref";
 import { toast } from "@/lib/toast";
 import { AnimatePresence, motion } from "motion/react";
-import { type ReactElement, useEffect, useRef } from "react";
+import type { ReactElement } from "react";
 
 const EASE_OUT_QUART: [number, number, number, number] = [0.165, 0.84, 0.44, 1];
 
@@ -15,15 +16,19 @@ interface LlamaUpdateBannerProps {
 
 /**
  * Non-invasive "Update llama.cpp" affordance. Appears bottom-right ~1s after a
- * newer prebuilt is detected and stays up until dismissed (click outside / X)
- * or updated. Clicking Update swaps the prebuilt in place via POST /api/llama/update.
+ * newer prebuilt is detected and stays up until the user explicitly acts on it
+ * (X, Update, or Remind me later). Clicking Update swaps the prebuilt in place
+ * via POST /api/llama/update. Can be turned off entirely in Settings ->
+ * General -> Notifications (on by default).
  */
 export function LlamaUpdateBanner({
   enabled = true,
 }: LlamaUpdateBannerProps): ReactElement | null {
-  const { status, visible, applying, apply, dismiss } = useLlamaUpdateCheck({
-    enabled,
-  });
+  const showBannerPref = useShowLlamaUpdateBanner();
+  const { status, visible, applying, apply, dismiss, snooze } =
+    useLlamaUpdateCheck({
+      enabled: enabled && showBannerPref,
+    });
 
   async function handleUpdate() {
     const result = await apply();
@@ -40,30 +45,12 @@ export function LlamaUpdateBanner({
 
   const show =
     visible && status != null && (status.update_available || applying);
-  const bannerRef = useRef<HTMLDivElement>(null);
-
-  // Dismiss when the user clicks anything outside the banner. Kept off while an
-  // update is applying so the progress stays visible.
-  useEffect(() => {
-    if (!show || applying) return;
-    function onPointerDown(event: PointerEvent) {
-      if (
-        bannerRef.current &&
-        !bannerRef.current.contains(event.target as Node)
-      ) {
-        dismiss();
-      }
-    }
-    document.addEventListener("pointerdown", onPointerDown, true);
-    return () =>
-      document.removeEventListener("pointerdown", onPointerDown, true);
-  }, [show, applying, dismiss]);
+  const updateProgress = status?.job.progress ?? null;
 
   return (
     <AnimatePresence>
       {show ? (
         <motion.div
-          ref={bannerRef}
           initial={{ opacity: 0, y: 12, scale: 0.96 }}
           animate={{ opacity: 1, y: 0, scale: 1 }}
           exit={{ opacity: 0, y: 8, scale: 0.97 }}
@@ -71,12 +58,12 @@ export function LlamaUpdateBanner({
           className="fixed bottom-4 right-4 z-[9998] w-[calc(100vw-2rem)] max-w-[340px]"
           data-testid="llama-update-banner"
         >
-          <div className="corner-squircle relative overflow-hidden border border-border/60 bg-background/95 px-4 py-3 shadow-lg backdrop-blur-md">
+          <div className="relative overflow-hidden rounded-[24px] bg-white px-4 pb-[22px] pl-6 pt-5 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.16)] dark:bg-card dark:shadow-[0_8px_28px_-6px_rgba(0,0,0,0.28)]">
             {applying ? null : (
               <button
                 type="button"
                 onClick={dismiss}
-                className="absolute top-2.5 right-2.5 flex size-5 items-center justify-center rounded-md text-muted-foreground/60 transition-colors hover:bg-muted hover:text-foreground"
+                className="absolute top-2.5 right-3 flex size-6 items-center justify-center rounded-full text-muted-foreground/60 transition-colors hover:bg-muted hover:text-foreground"
                 aria-label="Dismiss llama.cpp update notification"
               >
                 <svg
@@ -97,32 +84,64 @@ export function LlamaUpdateBanner({
               </button>
             )}
 
-            <div className="flex items-center gap-2 pr-5">
-              <span className="text-base" aria-hidden="true">
-                🦥
-              </span>
-              <p className="text-sm font-medium text-foreground">
-                {applying ? "Updating llama.cpp..." : "New llama.cpp prebuilt"}
+            <div className="min-w-0 pr-6">
+              <p className="font-heading text-base font-medium text-foreground">
+                {applying ? "Updating llama.cpp..." : "New llama.cpp version"}
+              </p>
+              <p className="mt-0.5 text-xs text-muted-foreground">
+                {status?.installed_tag ?? "unknown"} &rarr;{" "}
+                <span className="font-medium text-foreground">
+                  {status?.latest_tag ?? ""}
+                </span>
               </p>
             </div>
-            <p className="mt-0.5 pl-7 text-xs text-muted-foreground">
-              {status?.installed_tag ?? "unknown"} &rarr;{" "}
-              <span className="font-medium text-foreground">
-                {status?.latest_tag ?? ""}
-              </span>
-            </p>
 
-            <div className="mt-2.5 pl-7">
-              <Button
-                size="sm"
-                className="corner-squircle"
-                onClick={handleUpdate}
-                disabled={applying}
-                data-testid="llama-update-button"
+            {applying ? (
+              <div
+                className="mb-1.5 mt-4 h-1 overflow-hidden rounded-full bg-muted"
+                role="progressbar"
+                aria-label="Updating llama.cpp"
+                aria-valuemin={0}
+                aria-valuemax={100}
+                aria-valuenow={
+                  updateProgress != null
+                    ? Math.round(updateProgress * 100)
+                    : undefined
+                }
+                data-testid="llama-update-progress"
               >
-                {applying ? "Updating..." : "Update llama.cpp"}
-              </Button>
-            </div>
+                {updateProgress != null && updateProgress > 0 ? (
+                  <div
+                    className="h-full rounded-full bg-primary transition-[width] duration-700 ease-out"
+                    style={{ width: `${Math.round(updateProgress * 100)}%` }}
+                  />
+                ) : (
+                  // No percent yet (resolving the release): sweep until the
+                  // first download progress arrives.
+                  <div className="loading-bar-slide h-full w-1/3 rounded-full bg-primary" />
+                )}
+              </div>
+            ) : (
+              <div className="mt-3 flex items-center gap-2">
+                <Button
+                  size="sm"
+                  className="h-auto rounded-full px-3.5 py-2 text-[13px]"
+                  onClick={handleUpdate}
+                  data-testid="llama-update-button"
+                >
+                  Update
+                </Button>
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  className="h-auto rounded-full px-2.5 py-2 text-[13px] text-muted-foreground hover:text-foreground"
+                  onClick={snooze}
+                  data-testid="llama-update-snooze-button"
+                >
+                  Remind me later
+                </Button>
+              </div>
+            )}
           </div>
         </motion.div>
       ) : null}
diff --git a/studio/frontend/src/components/tauri/startup-screen.tsx b/studio/frontend/src/components/tauri/startup-screen.tsx
index 1eb3f81d10..8e373c82a0 100644
--- a/studio/frontend/src/components/tauri/startup-screen.tsx
+++ b/studio/frontend/src/components/tauri/startup-screen.tsx
@@ -228,7 +228,7 @@ function RepairingContent({
       </div>
       <div className="mb-10 flex flex-col items-center gap-2">
         <TealSpinner />
-        <p className="text-sm font-bold text-foreground">Updating existing Studio install...</p>
+        <p className="text-sm font-bold text-foreground">Updating existing Unsloth install...</p>
         {latest && (
           <p className="max-w-xs text-center text-xs text-muted-foreground">{latest}</p>
         )}
diff --git a/studio/frontend/src/components/ui/tooltip.tsx b/studio/frontend/src/components/ui/tooltip.tsx
index 954b1871f3..cbc1a09a8f 100644
--- a/studio/frontend/src/components/ui/tooltip.tsx
+++ b/studio/frontend/src/components/ui/tooltip.tsx
@@ -98,9 +98,27 @@ function TooltipContent({
 }: React.ComponentProps<typeof TooltipPrimitive.Content> & {
   variant?: TooltipVariant;
 }) {
+  // Single-line compact tooltips render as a full pill; wrapped ones keep
+  // the squarer corners so tall pills do not look like capsules. A ref
+  // callback measures on mount: Radix mounts the portal content without
+  // re-rendering this wrapper, so an effect here would never see the node.
+  const measureRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (!el || variant !== "default") return;
+      const cs = getComputedStyle(el);
+      const lineHeight = Number.parseFloat(cs.lineHeight) || 16;
+      const innerHeight =
+        el.clientHeight -
+        Number.parseFloat(cs.paddingTop) -
+        Number.parseFloat(cs.paddingBottom);
+      el.classList.toggle("rounded-full!", innerHeight < lineHeight * 1.5);
+    },
+    [variant],
+  );
   return (
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
+        ref={measureRef}
         data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
diff --git a/studio/frontend/src/components/web/update-banner.tsx b/studio/frontend/src/components/web/update-banner.tsx
index 685a8aa3dc..164d922baa 100644
--- a/studio/frontend/src/components/web/update-banner.tsx
+++ b/studio/frontend/src/components/web/update-banner.tsx
@@ -2,13 +2,16 @@
 // Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 import { Button } from "@/components/ui/button";
+import { usePlatformStore } from "@/config/env";
 import { useWebUpdateCheck } from "@/hooks/use-web-update-check";
 import { isTauri } from "@/lib/api-base";
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { AnimatePresence, motion } from "motion/react";
 import { type ReactElement, useEffect, useRef, useState } from "react";
 
-const STUDIO_UPDATE_CMD = "unsloth studio update";
+const STUDIO_INSTALL_UNIX_CMD =
+  "curl -fsSL https://unsloth.ai/install.sh | sh";
+const STUDIO_INSTALL_WINDOWS_CMD = "irm https://unsloth.ai/install.ps1 | iex";
 const RELEASE_NOTES_URL = "https://unsloth.ai/docs/new/changelog";
 const EASE_OUT_QUART: [number, number, number, number] = [0.165, 0.84, 0.44, 1];
 
@@ -20,6 +23,11 @@ export function WebUpdateBanner({
   enabled = true,
 }: WebUpdateBannerProps): ReactElement | null {
   const { status, dismiss } = useWebUpdateCheck({ enabled });
+  const deviceType = usePlatformStore((s) => s.deviceType);
+  const installCmd =
+    deviceType === "windows"
+      ? STUDIO_INSTALL_WINDOWS_CMD
+      : STUDIO_INSTALL_UNIX_CMD;
   const [copiedVersion, setCopiedVersion] = useState<string | null>(null);
   const dismissTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -36,7 +44,7 @@ export function WebUpdateBanner({
   }
 
   async function handleCopyCommand() {
-    if (!(await copyToClipboard(STUDIO_UPDATE_CMD))) {
+    if (!(await copyToClipboard(installCmd))) {
       return;
     }
     setCopiedVersion(status?.latestVersion ?? null);
@@ -89,8 +97,8 @@ export function WebUpdateBanner({
                   Package update available: {status.latestVersion}
                 </p>
                 <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
-                  Installed package: {status.currentVersion}. To update Studio,
-                  run this in your terminal, then restart Studio.
+                  Installed package: {status.currentVersion}. To update Unsloth,
+                  run this in your terminal, then restart Unsloth.
                 </p>
               </div>
             </div>
diff --git a/studio/frontend/src/config/env.ts b/studio/frontend/src/config/env.ts
index 92dad2ae27..61ab111d45 100644
--- a/studio/frontend/src/config/env.ts
+++ b/studio/frontend/src/config/env.ts
@@ -46,12 +46,28 @@ export async function fetchDeviceType(): Promise<DeviceType> {
   if (fetched) return usePlatformStore.getState().deviceType;
 
   try {
-    const res = await fetch(apiUrl("/api/health"));
+    // /api/health only reports the server's device_type to authed callers.
+    // Read the token from storage directly: importing features/auth here
+    // would be an import cycle (auth/session imports this store).
+    const token =
+      typeof window === "undefined"
+        ? null
+        : localStorage.getItem("unsloth_auth_token");
+    const res = await fetch(apiUrl("/api/health"), {
+      headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+    });
     if (res.ok) {
       const data = (await res.json()) as { device_type?: string; chat_only?: boolean };
       const deviceType = data.device_type ?? detectLocalPlatform();
       const chatOnly = data.chat_only ?? false;
-      usePlatformStore.setState({ deviceType, chatOnly, fetched: true });
+      // Cache only a server-reported platform. Unauthenticated responses fall
+      // back to the browser platform, which can differ from the host (WSL,
+      // SSH); keeping fetched=false retries once a token exists.
+      usePlatformStore.setState({
+        deviceType,
+        chatOnly,
+        fetched: data.device_type !== undefined,
+      });
       return deviceType;
     }
   } catch {
diff --git a/studio/frontend/src/features/auth/api.ts b/studio/frontend/src/features/auth/api.ts
index 6356f89378..144e85d40a 100644
--- a/studio/frontend/src/features/auth/api.ts
+++ b/studio/frontend/src/features/auth/api.ts
@@ -175,7 +175,7 @@ export async function authFetch(
           "You appear to be offline. Check your network connection and try again.",
         );
       }
-      throw new Error("Studio isn't running -- please relaunch it.");
+      throw new Error("Unsloth isn't running -- please relaunch it.");
     }
     throw err;
   }
diff --git a/studio/frontend/src/features/auth/tauri-auto-auth.ts b/studio/frontend/src/features/auth/tauri-auto-auth.ts
index 760af26395..e825d5de31 100644
--- a/studio/frontend/src/features/auth/tauri-auto-auth.ts
+++ b/studio/frontend/src/features/auth/tauri-auto-auth.ts
@@ -26,7 +26,7 @@ let pending: { promise: Promise<boolean>; force: boolean } | null = null;
 let lastTauriAuthFailure: string | null = null;
 
 const TAURI_AUTH_FAILURE_FALLBACK =
-  "Desktop authentication failed. Update or repair the managed Studio install, then restart Studio.";
+  "Desktop authentication failed. Update or repair the managed Unsloth install, then restart Unsloth.";
 const BACKEND_NOT_READY_MESSAGE = "Backend is not ready";
 
 function authFailureMessage(error: unknown): string {
diff --git a/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts b/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
index a679e8ed83..146a12bd40 100644
--- a/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
+++ b/studio/frontend/src/features/chat/adapters/studio-web-speech-dictation-adapter.ts
@@ -18,7 +18,7 @@ const describeMediaError = (error: unknown): string => {
     return "Dictation could not access the microphone.";
   }
   if (error.name === "NotAllowedError") {
-    return "Microphone access is blocked. Allow microphone access for this Studio page, then try again.";
+    return "Microphone access is blocked. Allow microphone access for this Unsloth page, then try again.";
   }
   if (error.name === "NotFoundError") {
     return "No microphone was found for dictation.";
@@ -31,7 +31,7 @@ const describeMediaError = (error: unknown): string => {
 
 const describeSpeechError = (error: string, message?: string): string => {
   if (error === "not-allowed") {
-    return "Speech recognition was blocked by the browser. Check microphone permissions for this Studio page.";
+    return "Speech recognition was blocked by the browser. Check microphone permissions for this Unsloth page.";
   }
   if (error === "service-not-allowed") {
     return "Speech recognition is blocked by the browser speech service.";
diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
index e35a8e35e0..0594b55083 100644
--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
@@ -1511,7 +1511,7 @@ export function ChatProvidersSettings({
         <div className="flex min-w-0 flex-col gap-1">
           <h1 className="font-heading text-lg font-semibold">Connections</h1>
           <p className="text-xs leading-relaxed text-muted-foreground">
-            Manage model connections for chat through the Studio proxy.
+            Manage model connections for chat.
           </p>
         </div>
       </header>
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index 03c183fe76..5751a1a426 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -325,6 +325,7 @@ function CollapsibleSection({
   label,
   labelHref,
   headerAction,
+  onLabelClick,
   children,
   defaultOpen = false,
   first = false,
@@ -342,6 +343,8 @@ function CollapsibleSection({
    * nested in a button.
    */
   headerAction?: ReactNode;
+  /** When set, clicking the label runs this instead of toggling collapse. */
+  onLabelClick?: () => void;
   children?: ReactNode;
   defaultOpen?: boolean;
   first?: boolean;
@@ -395,7 +398,7 @@ function CollapsibleSection({
         <div className={headerClasses}>
           <button
             type="button"
-            onClick={toggle}
+            onClick={onLabelClick ?? toggle}
             className="flex min-w-0 flex-1 cursor-pointer items-center text-left leading-none transition-colors hover:text-nav-fg"
           >
             <span className="leading-none">{label}</span>
@@ -558,6 +561,9 @@ export function ChatSettingsPanel({
   const [presetNameInput, setPresetNameInput] = useState(activePreset);
   const [systemPromptEditorOpen, setSystemPromptEditorOpen] = useState(false);
   const [systemPromptDraft, setSystemPromptDraft] = useState("");
+  // When the prompt overflows the inline box, clicking opens the popup editor.
+  const systemPromptBoxRef = useRef<HTMLTextAreaElement>(null);
+  const [systemPromptOverflows, setSystemPromptOverflows] = useState(false);
   const [activePresetBaseline, setActivePresetBaseline] = useState(params);
   const presets = useMemo(() => {
     return getOrderedPresets(customPresets);
@@ -762,6 +768,16 @@ export function ChatSettingsPanel({
     }
   }, [open]);
 
+  useEffect(() => {
+    const el = systemPromptBoxRef.current;
+    setSystemPromptOverflows(
+      params.systemPrompt.length > 0 &&
+        el != null &&
+        el.clientHeight > 0 &&
+        el.scrollHeight > el.clientHeight + 1,
+    );
+  }, [params.systemPrompt, open]);
+
   const settingsScrollRef = useRef<HTMLDivElement>(null);
 
   const settingsContent = (
@@ -1119,7 +1135,7 @@ export function ChatSettingsPanel({
                     />
                     <InputGroupAddon
                       align="inline-end"
-                      className="min-h-0 shrink-0 gap-0 self-stretch border-0 py-0 pl-0 !pr-1 has-[>button]:mr-0"
+                      className="min-h-0 shrink-0 gap-0 self-stretch border-0 py-0 pl-0 !pr-1 has-[>button]:mr-0 !cursor-pointer"
                     >
                       <span
                         className="!h-7 min-h-7 !w-7 min-w-7 shrink-0 self-center inline-flex items-center justify-center rounded-full border-0 px-0 text-[#a0a097] dark:text-nav-fg pointer-events-none"
@@ -1300,6 +1316,7 @@ export function ChatSettingsPanel({
         <CollapsibleSection
           label="System Prompt"
           defaultOpen={true}
+          onLabelClick={openSystemPromptEditor}
           headerAction={
             <Tooltip>
               <TooltipPrimitive.Trigger asChild>
@@ -1326,22 +1343,36 @@ export function ChatSettingsPanel({
             </Tooltip>
           }
         >
-          <button
-            type="button"
-            onClick={openSystemPromptEditor}
-            aria-label="Edit system prompt"
+          {/* Rounded wrapper clips overflowing text and the scrollbar. */}
+          <div
             className={cn(
-              "panel-text-surface -mt-1 flex w-full h-20 overflow-hidden cursor-pointer items-start px-3.5 py-2.5 text-left text-[13px] font-medium leading-relaxed corner-squircle focus-visible:outline-none focus-visible:border-ring focus-visible:ring-[1px] focus-visible:ring-ring/40",
-              params.systemPrompt
-                ? "text-nav-fg"
-                : "text-muted-foreground",
+              "panel-text-surface -mt-1 h-20 w-full overflow-hidden corner-squircle",
+              systemPromptOverflows && "cursor-pointer",
             )}
           >
-            <span className="block line-clamp-3 whitespace-pre-wrap break-words">
-              {params.systemPrompt ||
-                "Example: You are a helpful assistant..."}
-            </span>
-          </button>
+            <textarea
+              ref={systemPromptBoxRef}
+              value={params.systemPrompt}
+              onChange={(e) => set("systemPrompt")(e.target.value)}
+              onMouseDown={(e) => {
+                // Overflowing prompt: click opens the popup editor instead.
+                // While focused, clicks still move the caret normally.
+                if (
+                  systemPromptOverflows &&
+                  document.activeElement !== e.currentTarget
+                ) {
+                  e.preventDefault();
+                  openSystemPromptEditor();
+                }
+              }}
+              placeholder="Example: You are a helpful assistant..."
+              aria-label="System prompt"
+              className={cn(
+                "block size-full resize-none bg-transparent px-3.5 py-2.5 text-left text-[13px] font-medium leading-relaxed text-nav-fg outline-none placeholder:text-muted-foreground",
+                systemPromptOverflows && "cursor-pointer",
+              )}
+            />
+          </div>
         </CollapsibleSection>
 
         <CollapsibleSection label="Sampling" defaultOpen={true}>
diff --git a/studio/frontend/src/features/chat/tour/steps.tsx b/studio/frontend/src/features/chat/tour/steps.tsx
index de27e93c88..cbbb7bae4f 100644
--- a/studio/frontend/src/features/chat/tour/steps.tsx
+++ b/studio/frontend/src/features/chat/tour/steps.tsx
@@ -28,7 +28,7 @@ export function buildChatTourSteps({
       body: (
         <>
           This selects what’s loaded for inference. Hub = base models. Fine-tuned
-          = trained Studio outputs, including LoRA adapters and full finetunes.
+          = trained Unsloth outputs, including LoRA adapters and full finetunes.
         </>
       ),
     },
@@ -38,7 +38,7 @@ export function buildChatTourSteps({
       title: "Two tabs",
       body: (
         <>
-          Hub: search Hugging Face models. Fine-tuned: local Studio outputs you’ve
+          Hub: search Hugging Face models. Fine-tuned: local Unsloth outputs you’ve
           trained or exported. If results look off, compare base vs fine-tuned
           outputs to see what changed.
         </>
diff --git a/studio/frontend/src/features/chat/utils/chat-history-storage.ts b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
index 0e9b30a5cc..2023ae30b1 100644
--- a/studio/frontend/src/features/chat/utils/chat-history-storage.ts
+++ b/studio/frontend/src/features/chat/utils/chat-history-storage.ts
@@ -134,7 +134,7 @@ export function isExpectedBackgroundChatStorageError(error: unknown): boolean {
     (error.message === "Invalid or expired token" ||
       error.message === "Not authenticated" ||
       error.message === "Request failed (401)" ||
-      error.message === "Studio isn't running -- please relaunch it.")
+      error.message === "Unsloth isn't running -- please relaunch it.")
   );
 }
 
diff --git a/studio/frontend/src/features/hub/download-manager/api.ts b/studio/frontend/src/features/hub/download-manager/api.ts
index ca987f1643..2c55b90edd 100644
--- a/studio/frontend/src/features/hub/download-manager/api.ts
+++ b/studio/frontend/src/features/hub/download-manager/api.ts
@@ -12,14 +12,14 @@ function parseErrorText(status: number, body: unknown): string {
     const detail = (body as { detail?: unknown }).detail;
     const formatted = formatFastApiDetail(detail);
     if (status === 405) {
-      return `${formatted || "Method Not Allowed"} - the Studio backend did not accept this API method. Restart Studio so the frontend and backend are on the same build.`;
+      return `${formatted || "Method Not Allowed"} - the Unsloth backend did not accept this API method. Restart Unsloth so the frontend and backend are on the same build.`;
     }
     if (formatted) return formatted;
     const message = (body as { message?: unknown }).message;
     if (typeof message === "string" && message) return message;
   }
   if (status === 405) {
-    return "Method Not Allowed - the Studio backend did not accept this API method. Restart Studio so the frontend and backend are on the same build.";
+    return "Method Not Allowed - the Unsloth backend did not accept this API method. Restart Unsloth so the frontend and backend are on the same build.";
   }
   return `Request failed (${status})`;
 }
@@ -137,7 +137,7 @@ const DOWNLOAD_TRANSPORT_CAPABILITIES_FALLBACK: DownloadTransportCapabilities =
   http: { available: true, reason: null },
   xet: {
     available: null,
-    reason: "Couldn't verify Xet support with the Studio backend.",
+    reason: "Couldn't verify Xet support with the Unsloth backend.",
   },
 };
 let downloadTransportCapabilitiesCache: DownloadTransportCapabilities | null =
diff --git a/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts b/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
index 6942dfbbb9..a6518ec656 100644
--- a/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
+++ b/studio/frontend/src/features/hub/download-manager/download-api-adapter.ts
@@ -184,7 +184,7 @@ export async function effectiveTransportMode(
     return preferred;
   }
   const reason =
-    capabilities.xet.reason ?? "Studio will use HTTP downloads instead.";
+    capabilities.xet.reason ?? "Unsloth will use HTTP downloads instead.";
   if (lastXetUnavailableWarningReason !== reason) {
     lastXetUnavailableWarningReason = reason;
     toast.warning("Xet download transport unavailable", {
diff --git a/studio/frontend/src/features/recipe-studio/components/executions/execution-data-tab.tsx b/studio/frontend/src/features/recipe-studio/components/executions/execution-data-tab.tsx
index a3e5dbe962..1616f6f77d 100644
--- a/studio/frontend/src/features/recipe-studio/components/executions/execution-data-tab.tsx
+++ b/studio/frontend/src/features/recipe-studio/components/executions/execution-data-tab.tsx
@@ -45,7 +45,7 @@ function formatGitHubSourceMessage(execution: RecipeExecutionRecord): string {
     return "Collecting repository threads before rows are available.";
   }
   if (source.status === "rate_limited") {
-    return source.message ?? "Waiting for GitHub rate limit. Studio will resume automatically.";
+    return source.message ?? "Waiting for GitHub rate limit. Unsloth will resume automatically.";
   }
   return source.message ?? "Collecting repository threads before rows are available.";
 }
diff --git a/studio/frontend/src/features/recipe-studio/components/executions/execution-overview-tab.tsx b/studio/frontend/src/features/recipe-studio/components/executions/execution-overview-tab.tsx
index 72624738fc..5ff9d644e7 100644
--- a/studio/frontend/src/features/recipe-studio/components/executions/execution-overview-tab.tsx
+++ b/studio/frontend/src/features/recipe-studio/components/executions/execution-overview-tab.tsx
@@ -41,7 +41,7 @@ function formatSourceMessage(execution: RecipeExecutionRecord): string {
       typeof source.retry_after_sec === "number" && source.retry_after_sec > 0
         ? ` Waiting ~${formatMetricValue(source.retry_after_sec)}s.`
         : "";
-    return `Waiting for GitHub rate limit. Studio will resume automatically.${wait}`;
+    return `Waiting for GitHub rate limit. Unsloth will resume automatically.${wait}`;
   }
   return source.message ?? "Crawling GitHub source.";
 }
diff --git a/studio/frontend/src/features/recipe-studio/components/runtime/execution-progress-island.tsx b/studio/frontend/src/features/recipe-studio/components/runtime/execution-progress-island.tsx
index 563280c55f..1a194ba857 100644
--- a/studio/frontend/src/features/recipe-studio/components/runtime/execution-progress-island.tsx
+++ b/studio/frontend/src/features/recipe-studio/components/runtime/execution-progress-island.tsx
@@ -68,7 +68,7 @@ function formatGitHubSourceSummary(
       typeof source.retry_after_sec === "number" && source.retry_after_sec > 0
         ? ` ~${formatMetricValue(source.retry_after_sec)}s`
         : "";
-    return `Waiting for GitHub rate limit${wait}. Studio will resume automatically.`;
+    return `Waiting for GitHub rate limit${wait}. Unsloth will resume automatically.`;
   }
   if (source.status === "retrying") {
     return source.message ?? "GitHub request failed; retrying automatically.";
diff --git a/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx b/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
index 878f9eba7c..0ed7eeed75 100644
--- a/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
+++ b/studio/frontend/src/features/recipe-studio/dialogs/seed/seed-dialog.tsx
@@ -334,8 +334,8 @@ export function GithubRepoSeedForm({
         />
         <p id={tokenHelpId} className="text-xs text-muted-foreground">
           {usingEnvToken
-            ? "Studio detected a server env token, so saved/shared recipes can leave this blank."
-            : "Blank is safest for saved/shared recipes because Studio will read the server environment at run time."}
+            ? "Unsloth detected a server env token, so saved/shared recipes can leave this blank."
+            : "Blank is safest for saved/shared recipes because Unsloth will read the server environment at run time."}
         </p>
         {hasToken && (
           <p className="rounded-md bg-amber-500/10 px-2 py-1.5 text-xs text-amber-700 dark:text-amber-300">
@@ -450,7 +450,7 @@ export function GithubRepoSeedForm({
       </fieldset>
 
       <p className="text-xs text-muted-foreground">
-        Backed by Studio's built-in <code>github_repo</code> seed reader. Large
+        Backed by Unsloth's built-in <code>github_repo</code> seed reader. Large
         repos can take minutes, so start with small limits for previews.
       </p>
     </div>
diff --git a/studio/frontend/src/features/settings/components/update-studio-instructions.tsx b/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
index 90f66483b7..ef6bbf3c18 100644
--- a/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
+++ b/studio/frontend/src/features/settings/components/update-studio-instructions.tsx
@@ -4,21 +4,29 @@
 import { copyToClipboard } from "@/lib/copy-to-clipboard";
 import { useT } from "@/i18n";
 import { cn } from "@/lib/utils";
-import { Copy01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
+import {
+  ArrowUpRight01Icon,
+  Copy01Icon,
+  Tick02Icon,
+} from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import type { ReactElement } from "react";
 import { useEffect, useRef, useState } from "react";
 
-const STUDIO_UPDATE_CMD = "unsloth studio update";
-const STUDIO_UPDATE_FALLBACK_UNIX_CMD =
+const STUDIO_INSTALL_UNIX_CMD =
   "curl -fsSL https://unsloth.ai/install.sh | sh";
-const STUDIO_UPDATE_FALLBACK_WINDOWS_CMD =
-  "irm https://unsloth.ai/install.ps1 | iex";
+const STUDIO_INSTALL_WINDOWS_CMD = "irm https://unsloth.ai/install.ps1 | iex";
 const STUDIO_LOCAL_PULL_CMD = "git pull --ff-only";
-const STUDIO_LOCAL_UPDATE_CMD = "unsloth studio update --local";
-const STUDIO_LOCAL_FALLBACK_UNIX_CMD = "./install.sh --local";
-const STUDIO_LOCAL_FALLBACK_WINDOWS_CMD = ".\\install.ps1 --local";
+const STUDIO_LOCAL_INSTALL_UNIX_CMD = "./install.sh --local";
+const STUDIO_LOCAL_INSTALL_WINDOWS_CMD = ".\\install.ps1 --local";
+
+const DOCS_INSTALL_URL = "https://unsloth.ai/docs/get-started/install";
+const DOCS_UPDATING_URL =
+  "https://unsloth.ai/docs/get-started/install/updating";
+const DOCS_MAC_URL = "https://unsloth.ai/docs/get-started/install/mac";
+const DOCS_WINDOWS_URL =
+  "https://unsloth.ai/docs/get-started/install/windows-installation";
 
 export type UpdateShell = "windows" | "unix";
 export type UpdateInstallSource =
@@ -30,15 +38,6 @@ export type UpdateInstallSource =
   | "unknown";
 type UpdateInstallSourceState = UpdateInstallSource | "loading";
 
-function getStudioUpdateInstructionLine(
-  shell: UpdateShell,
-  t: ReturnType<typeof useT>,
-): string {
-  return shell === "windows"
-    ? t("settings.about.update.openPowerShell")
-    : t("settings.about.update.openTerminal");
-}
-
 function isLocalInstallSource(
   installSource?: UpdateInstallSourceState | null,
 ): boolean {
@@ -128,6 +127,77 @@ function CopyableCommand({
   );
 }
 
+function DocsLink({
+  href,
+  label,
+}: {
+  href: string;
+  label: string;
+}): ReactElement {
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="inline-flex items-center gap-0.5 font-medium text-muted-foreground hover:text-foreground"
+    >
+      {label}
+      <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
+    </a>
+  );
+}
+
+function UpdateDocsLinks(): ReactElement {
+  const t = useT();
+  return (
+    <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground leading-relaxed">
+      {t("settings.about.update.docs")}
+      <DocsLink
+        href={DOCS_INSTALL_URL}
+        label={t("settings.about.update.docsInstall")}
+      />
+      <DocsLink
+        href={DOCS_UPDATING_URL}
+        label={t("settings.about.update.docsUpdating")}
+      />
+      <DocsLink
+        href={DOCS_MAC_URL}
+        label={t("settings.about.update.docsMac")}
+      />
+      <DocsLink
+        href={DOCS_WINDOWS_URL}
+        label={t("settings.about.update.docsWindows")}
+      />
+    </p>
+  );
+}
+
+function ShellToggleButton({
+  active,
+  label,
+  onClick,
+}: {
+  active: boolean;
+  label: string;
+  onClick: () => void;
+}): ReactElement {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={cn(
+        "rounded-full px-2.5 py-1 text-[11px] font-medium transition-colors",
+        active
+          ? "bg-foreground/[0.08] text-foreground dark:bg-white/[0.12]"
+          : "text-muted-foreground hover:text-foreground",
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: keep source-specific update guidance in one component so the command matrix stays visible.
 export function UpdateStudioInstructions({
   className,
@@ -145,6 +215,9 @@ export function UpdateStudioInstructions({
   const shell = shellOverride ?? defaultShell;
   const prefersReducedMotion = useReducedMotion();
   const windows = shell === "windows";
+  // null means the desktop app: its bundled backend updates through the
+  // built-in updater, so terminal commands would target the wrong install.
+  const desktopManaged = installSource === null;
   const localInstallSource = isLocalInstallSource(installSource);
   const checkoutInstallSource =
     installSource === "editable" || installSource === "local_repo";
@@ -163,6 +236,22 @@ export function UpdateStudioInstructions({
     ? { opacity: 1 }
     : { opacity: 0, y: -2 };
 
+  if (desktopManaged) {
+    return (
+      <div className={cn("flex flex-col gap-3", className)}>
+        {showTitle ? (
+          <p className="shrink-0 whitespace-nowrap text-sm font-semibold font-heading">
+            {t("settings.about.update.title")}
+          </p>
+        ) : null}
+        <p className="text-xs text-muted-foreground leading-relaxed">
+          {t("settings.about.update.desktopManaged")}
+        </p>
+        <UpdateDocsLinks />
+      </div>
+    );
+  }
+
   return (
     <div className={cn("flex flex-col gap-3", className)}>
       <div
@@ -176,42 +265,55 @@ export function UpdateStudioInstructions({
             {t("settings.about.update.title")}
           </p>
         ) : null}
-        <div className="flex shrink-0 items-center gap-0.5 text-[11px]">
-          <button
-            type="button"
-            onClick={() => setShellOverride("windows")}
-            className={cn(
-              "px-0.5 py-0.5 font-medium transition-colors",
-              windows
-                ? "text-foreground"
-                : "text-muted-foreground hover:text-emerald-600",
-            )}
-            aria-pressed={windows}
-          >
-            Windows
-          </button>
-          <span className="text-border">/</span>
-          <button
-            type="button"
+        <div className="flex shrink-0 items-center gap-1.5">
+          <ShellToggleButton
+            active={!windows}
+            label="MacOS / Linux"
             onClick={() => setShellOverride("unix")}
-            className={cn(
-              "px-0.5 py-0.5 font-medium transition-colors",
-              windows
-                ? "text-muted-foreground hover:text-emerald-600"
-                : "text-foreground",
-            )}
-            aria-pressed={!windows}
-          >
-            macOS/Linux
-          </button>
+          />
+          <ShellToggleButton
+            active={windows}
+            label="Windows"
+            onClick={() => setShellOverride("windows")}
+          />
         </div>
       </div>
       {loadingInstallSource ? (
         <p className="text-xs text-muted-foreground leading-relaxed">
           {t("settings.about.update.checkingInstall")}
         </p>
-      ) : localInstallSource ? (
+      ) : (
         <>
+          <p className="text-xs text-muted-foreground leading-relaxed">
+            {t("settings.about.update.installIntro")}
+          </p>
+          <AnimatePresence mode="wait" initial={false}>
+            <motion.div
+              key={`install-${shell}`}
+              initial={fadeInitial}
+              animate={fadeAnimate}
+              exit={fadeExit}
+              transition={fadeTransition}
+            >
+              <CopyableCommand
+                command={
+                  windows ? STUDIO_INSTALL_WINDOWS_CMD : STUDIO_INSTALL_UNIX_CMD
+                }
+                copyLabel={
+                  windows
+                    ? t("settings.about.update.installCommandWindows")
+                    : t("settings.about.update.installCommandUnix")
+                }
+              />
+            </motion.div>
+          </AnimatePresence>
+        </>
+      )}
+      {loadingInstallSource ? null : localInstallSource ? (
+        <>
+          <p className="text-xs font-semibold text-foreground">
+            {t("settings.about.update.localUpdateHeading")}
+          </p>
           <p className="text-xs text-muted-foreground leading-relaxed">
             {t("settings.about.update.localInstallDetected")}
           </p>
@@ -224,16 +326,9 @@ export function UpdateStudioInstructions({
                 command={STUDIO_LOCAL_PULL_CMD}
                 copyLabel={t("settings.about.update.gitPullCommand")}
               />
-              <CopyableCommand
-                command={STUDIO_LOCAL_UPDATE_CMD}
-                copyLabel={t("settings.about.update.localUpdateCommand")}
-              />
-              <p className="text-xs text-muted-foreground leading-relaxed">
-                {t("settings.about.update.localInstallerFallback")}
-              </p>
               <AnimatePresence mode="wait" initial={false}>
                 <motion.div
-                  key={`local-fallback-${shell}`}
+                  key={`local-installer-${shell}`}
                   initial={fadeInitial}
                   animate={fadeAnimate}
                   exit={fadeExit}
@@ -242,8 +337,8 @@ export function UpdateStudioInstructions({
                   <CopyableCommand
                     command={
                       windows
-                        ? STUDIO_LOCAL_FALLBACK_WINDOWS_CMD
-                        : STUDIO_LOCAL_FALLBACK_UNIX_CMD
+                        ? STUDIO_LOCAL_INSTALL_WINDOWS_CMD
+                        : STUDIO_LOCAL_INSTALL_UNIX_CMD
                     }
                     copyLabel={t("settings.about.update.localInstallerCommand")}
                   />
@@ -261,7 +356,7 @@ export function UpdateStudioInstructions({
               </p>
               <AnimatePresence mode="wait" initial={false}>
                 <motion.div
-                  key={`source-fallback-${shell}`}
+                  key={`source-installer-${shell}`}
                   initial={fadeInitial}
                   animate={fadeAnimate}
                   exit={fadeExit}
@@ -270,8 +365,8 @@ export function UpdateStudioInstructions({
                   <CopyableCommand
                     command={
                       windows
-                        ? STUDIO_LOCAL_FALLBACK_WINDOWS_CMD
-                        : STUDIO_LOCAL_FALLBACK_UNIX_CMD
+                        ? STUDIO_LOCAL_INSTALL_WINDOWS_CMD
+                        : STUDIO_LOCAL_INSTALL_UNIX_CMD
                     }
                     copyLabel={t("settings.about.update.localInstallerCommand")}
                   />
@@ -282,54 +377,22 @@ export function UpdateStudioInstructions({
           <p className="text-xs text-muted-foreground leading-relaxed">
             {t("settings.about.update.restartAfterUpdate")}
           </p>
+          <UpdateDocsLinks />
         </>
       ) : unknownInstallSource ? (
         <>
           <p className="text-xs text-muted-foreground leading-relaxed">
             {t("settings.about.update.unknownInstall")}
           </p>
-          <p className="text-xs text-muted-foreground leading-relaxed">
-            {t("settings.about.update.curlOrPypi")}
+          <p className="text-xs font-semibold text-foreground">
+            {t("settings.about.update.localUpdateHeading")}
           </p>
-          <CopyableCommand
-            command={STUDIO_UPDATE_CMD}
-            copyLabel={t("settings.about.update.updateCommand")}
-          />
           <p className="text-xs text-muted-foreground leading-relaxed">
             {t("settings.about.update.localCheckout")}
           </p>
-          <CopyableCommand
-            command={STUDIO_LOCAL_UPDATE_CMD}
-            copyLabel={t("settings.about.update.localUpdateCommand")}
-          />
-          <p className="text-xs text-muted-foreground leading-relaxed">
-            {t("settings.about.update.restartAfterUpdate")}
-          </p>
-        </>
-      ) : (
-        <>
-          <AnimatePresence mode="wait" initial={false}>
-            <motion.p
-              key={`instruction-${shell}`}
-              initial={fadeInitial}
-              animate={fadeAnimate}
-              exit={fadeExit}
-              transition={fadeTransition}
-              className="text-xs text-muted-foreground leading-relaxed"
-            >
-              {getStudioUpdateInstructionLine(shell, t)}
-            </motion.p>
-          </AnimatePresence>
-          <CopyableCommand
-            command={STUDIO_UPDATE_CMD}
-            copyLabel={t("settings.about.update.updateCommand")}
-          />
-          <p className="text-xs text-muted-foreground leading-relaxed">
-            {t("settings.about.update.fallbackInstruction")}
-          </p>
           <AnimatePresence mode="wait" initial={false}>
             <motion.div
-              key={`fallback-${shell}`}
+              key={`local-installer-${shell}`}
               initial={fadeInitial}
               animate={fadeAnimate}
               exit={fadeExit}
@@ -338,16 +401,24 @@ export function UpdateStudioInstructions({
               <CopyableCommand
                 command={
                   windows
-                    ? STUDIO_UPDATE_FALLBACK_WINDOWS_CMD
-                    : STUDIO_UPDATE_FALLBACK_UNIX_CMD
+                    ? STUDIO_LOCAL_INSTALL_WINDOWS_CMD
+                    : STUDIO_LOCAL_INSTALL_UNIX_CMD
                 }
-                copyLabel={t("settings.about.update.fallbackCommand")}
+                copyLabel={t("settings.about.update.localInstallerCommand")}
               />
             </motion.div>
           </AnimatePresence>
           <p className="text-xs text-muted-foreground leading-relaxed">
             {t("settings.about.update.restartAfterUpdate")}
           </p>
+          <UpdateDocsLinks />
+        </>
+      ) : (
+        <>
+          <p className="text-xs text-muted-foreground leading-relaxed">
+            {t("settings.about.update.restartAfterUpdate")}
+          </p>
+          <UpdateDocsLinks />
         </>
       )}
     </div>
diff --git a/studio/frontend/src/features/settings/tabs/about-tab.tsx b/studio/frontend/src/features/settings/tabs/about-tab.tsx
index e73ad802de..69c4aa6ef1 100644
--- a/studio/frontend/src/features/settings/tabs/about-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/about-tab.tsx
@@ -142,7 +142,7 @@ export function AboutTab() {
         </p>
       </header>
 
-      <SettingsSection title="Studio">
+      <SettingsSection title="Unsloth">
         <SettingsRow label={t("settings.about.studioVersion")}>
           <code className="font-mono text-xs text-muted-foreground">
             {studioVersion}
@@ -207,6 +207,37 @@ export function AboutTab() {
         </SettingsRow>
       </SettingsSection>
 
+      <SettingsSection title={t("settings.about.license.sectionTitle")}>
+        <SettingsRow
+          label={t("settings.about.license.studioLabel")}
+          description={t("settings.about.license.studioDescription")}
+        >
+          <a
+            href="https://github.com/unslothai/unsloth/blob/main/studio/LICENSE.AGPL-3.0"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-1 font-mono text-xs font-medium text-muted-foreground hover:text-foreground"
+          >
+            {t("settings.about.license.studioLicense")}
+            <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
+          </a>
+        </SettingsRow>
+        <SettingsRow
+          label={t("settings.about.license.libraryLabel")}
+          description={t("settings.about.license.libraryDescription")}
+        >
+          <a
+            href="https://github.com/unslothai/unsloth/blob/main/LICENSE"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-1 font-mono text-xs font-medium text-muted-foreground hover:text-foreground"
+          >
+            {t("settings.about.license.libraryLicense")}
+            <HugeiconsIcon icon={ArrowUpRight01Icon} className="size-3" />
+          </a>
+        </SettingsRow>
+      </SettingsSection>
+
       <SettingsSection title={t("settings.about.dangerZone")}>
         <SettingsRow
           destructive={true}
diff --git a/studio/frontend/src/features/settings/tabs/general-tab.tsx b/studio/frontend/src/features/settings/tabs/general-tab.tsx
index 8a15eb4985..135f21caf5 100644
--- a/studio/frontend/src/features/settings/tabs/general-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/general-tab.tsx
@@ -15,6 +15,10 @@ import { Switch } from "@/components/ui/switch";
 import { usePlatformStore } from "@/config/env";
 import { resetOnboardingDone } from "@/features/auth";
 import { useChatRuntimeStore } from "@/features/chat";
+import {
+  setShowLlamaUpdateBanner,
+  useShowLlamaUpdateBanner,
+} from "@/hooks/use-llama-update-pref";
 import {
   loadHelperPrecacheSettings,
   updateHelperPrecacheSettings,
@@ -68,6 +72,8 @@ const PREFS_KEYS: string[] = [
   "unsloth_user_profile",
   // Guided tour flags
   "tour:studio:v1",
+  // Update notifications
+  "unsloth_show_llama_update_banner",
 ];
 
 // Set by resetAllPrefs so the unmount-commit effect skips writing back the
@@ -106,6 +112,7 @@ export function GeneralTab() {
   const autoTitle = useChatRuntimeStore((s) => s.autoTitle);
   const setAutoTitle = useChatRuntimeStore((s) => s.setAutoTitle);
   const chatOnly = usePlatformStore((s) => s.chatOnly);
+  const showLlamaUpdates = useShowLlamaUpdateBanner();
   const redirectTo = `${pathname}${search}`;
 
   const [draftToken, setDraftToken] = useState(hfToken ?? "");
@@ -315,6 +322,20 @@ export function GeneralTab() {
         </SettingsRow>
       </SettingsSection>
 
+      <SettingsSection title={t("settings.general.notifications.sectionTitle")}>
+        <SettingsRow
+          label={t("settings.general.notifications.showLlamaUpdates")}
+          description={t(
+            "settings.general.notifications.showLlamaUpdatesDescription",
+          )}
+        >
+          <Switch
+            checked={showLlamaUpdates}
+            onCheckedChange={setShowLlamaUpdateBanner}
+          />
+        </SettingsRow>
+      </SettingsSection>
+
       <SettingsSection title={t("settings.general.uploads.sectionTitle")}>
         <SettingsRow
           label={t("settings.general.uploads.maxUploadSize")}
diff --git a/studio/frontend/src/features/studio/tour/steps/nav.tsx b/studio/frontend/src/features/studio/tour/steps/nav.tsx
index 41c107888c..8a8da8cab0 100644
--- a/studio/frontend/src/features/studio/tour/steps/nav.tsx
+++ b/studio/frontend/src/features/studio/tour/steps/nav.tsx
@@ -9,7 +9,7 @@ export const studioNavStep: TourStep = {
   title: "Quick orientation",
   body: (
     <>
-      Studio: pick base model, dataset, hyperparams, then start training. After
+      Unsloth: pick base model, dataset, hyperparams, then start training. After
       you start, you’ll see a Training view with live loss/metrics. Chat is for
       testing base vs LoRA adapters. Export packages checkpoints for deployment.{" "}
       <ReadMore href="https://unsloth.ai/docs/get-started/fine-tuning-for-beginners" />
diff --git a/studio/frontend/src/hooks/use-llama-update-check.ts b/studio/frontend/src/hooks/use-llama-update-check.ts
index 1ac5d9768e..5c609558d6 100644
--- a/studio/frontend/src/hooks/use-llama-update-check.ts
+++ b/studio/frontend/src/hooks/use-llama-update-check.ts
@@ -5,11 +5,14 @@ import { authFetch, getAuthToken } from "@/features/auth";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 // First check shortly after load, then re-surface as an hourly reminder. The
-// banner stays up until the user dismisses it (click outside / X) or updates.
+// banner stays up until the user explicitly acts on it (X, Update, or
+// Remind me later).
 const FIRST_CHECK_DELAY_MS = 1000;
 const REMINDER_INTERVAL_MS = 60 * 60 * 1000; // ~1 hour
+// "Remind me later" re-surfaces sooner than the hourly reminder.
+const SNOOZE_DELAY_MS = 15 * 60 * 1000; // ~15 minutes
 // While an update is applying, poll the job state at this cadence.
-const JOB_POLL_INTERVAL_MS = 3000;
+const JOB_POLL_INTERVAL_MS = 1500;
 
 export interface LlamaUpdateJob {
   state: "idle" | "running" | "success" | "error";
@@ -17,6 +20,8 @@ export interface LlamaUpdateJob {
   from_tag: string | null;
   to_tag: string | null;
   error: string | null;
+  // Download fraction (0..1) while running, 1 on success, null when unknown.
+  progress: number | null;
 }
 
 export interface LlamaUpdateStatus {
@@ -42,6 +47,7 @@ function parseStatus(value: unknown): LlamaUpdateStatus | null {
       from_tag: typeof job.from_tag === "string" ? job.from_tag : null,
       to_tag: typeof job.to_tag === "string" ? job.to_tag : null,
       error: typeof job.error === "string" ? job.error : null,
+      progress: typeof job.progress === "number" ? job.progress : null,
     },
   };
 }
@@ -73,9 +79,10 @@ export interface LlamaApplyResult {
 
 /**
  * Polls the backend for a newer llama.cpp prebuilt. When one exists, `visible`
- * becomes true ~1s after load and stays up until the user dismisses it (click
- * outside / X) or updates; it re-surfaces every ~hour as a reminder. `apply()`
- * triggers the in-place swap and tracks the job.
+ * becomes true ~1s after load and stays up until the user dismisses it (X),
+ * snoozes it ("Remind me later", ~15 min), or updates; it re-surfaces every
+ * ~hour as a reminder. `apply()` triggers the in-place swap and tracks the
+ * job.
  */
 export function useLlamaUpdateCheck({
   enabled = true,
@@ -84,6 +91,7 @@ export function useLlamaUpdateCheck({
   const [visible, setVisible] = useState(false);
   const [applying, setApplying] = useState(false);
   const pollTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+  const snoozeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const clearPollTimer = useCallback(() => {
     if (pollTimer.current) {
@@ -161,6 +169,10 @@ export function useLlamaUpdateCheck({
       clearTimeout(firstTimer);
       clearInterval(reminder);
       clearPollTimer();
+      if (snoozeTimer.current) {
+        clearTimeout(snoozeTimer.current);
+        snoozeTimer.current = null;
+      }
     };
   }, [enabled, surfaceIfAvailable, clearPollTimer]);
 
@@ -168,6 +180,16 @@ export function useLlamaUpdateCheck({
     setVisible(false);
   }, []);
 
+  // Hide now, re-check and re-surface after SNOOZE_DELAY_MS.
+  const snooze = useCallback(() => {
+    setVisible(false);
+    if (snoozeTimer.current) clearTimeout(snoozeTimer.current);
+    snoozeTimer.current = setTimeout(() => {
+      snoozeTimer.current = null;
+      fetchStatus().then(surfaceIfAvailable);
+    }, SNOOZE_DELAY_MS);
+  }, [surfaceIfAvailable]);
+
   const apply = useCallback(async (): Promise<LlamaApplyResult> => {
     if (applying) return { ok: false, error: "already running" };
     setApplying(true);
@@ -219,5 +241,6 @@ export function useLlamaUpdateCheck({
     applying,
     apply,
     dismiss,
+    snooze,
   };
 }
diff --git a/studio/frontend/src/hooks/use-llama-update-pref.ts b/studio/frontend/src/hooks/use-llama-update-pref.ts
new file mode 100644
index 0000000000..33a21965c4
--- /dev/null
+++ b/studio/frontend/src/hooks/use-llama-update-pref.ts
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { useSyncExternalStore } from "react";
+
+// Whether the llama.cpp update banner may appear. On by default; only an
+// explicit "false" (Settings -> General -> Notifications) disables it.
+const STORAGE_KEY = "unsloth_show_llama_update_banner";
+
+const listeners = new Set<() => void>();
+
+export function getShowLlamaUpdateBanner(): boolean {
+  try {
+    return localStorage.getItem(STORAGE_KEY) !== "false";
+  } catch {
+    return true;
+  }
+}
+
+export function setShowLlamaUpdateBanner(show: boolean): void {
+  try {
+    if (show) {
+      // Remove rather than store "true" so the default stays on.
+      localStorage.removeItem(STORAGE_KEY);
+    } else {
+      localStorage.setItem(STORAGE_KEY, "false");
+    }
+  } catch {
+    // storage unavailable
+  }
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  // Sync toggles made in another tab.
+  const onStorage = (event: StorageEvent) => {
+    if (event.key === STORAGE_KEY) listener();
+  };
+  window.addEventListener("storage", onStorage);
+  return () => {
+    listeners.delete(listener);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+
+export function useShowLlamaUpdateBanner(): boolean {
+  return useSyncExternalStore(subscribe, getShowLlamaUpdateBanner);
+}
diff --git a/studio/frontend/src/hooks/use-tauri-backend.ts b/studio/frontend/src/hooks/use-tauri-backend.ts
index b376cb3a37..086cfc8090 100644
--- a/studio/frontend/src/hooks/use-tauri-backend.ts
+++ b/studio/frontend/src/hooks/use-tauri-backend.ts
@@ -56,23 +56,23 @@ function wait(ms: number) {
 function externalConflictMessage(preflight: DesktopPreflightResult) {
   if (preflight.reason === "desktop_owned_backend_active") {
     return preflight.port
-      ? `A desktop-owned Studio server for this install is already running on port ${preflight.port}. Quit the other desktop app instance, then try again.`
-      : "A desktop-owned Studio server for this install is already running. Quit the other desktop app instance, then try again.";
+      ? `A desktop-owned Unsloth server for this install is already running on port ${preflight.port}. Quit the other desktop app instance, then try again.`
+      : "A desktop-owned Unsloth server for this install is already running. Quit the other desktop app instance, then try again.";
   }
 
   if (preflight.reason === "desktop_owned_backend_starting") {
-    return "The desktop-owned Studio backend is still starting. Wait a moment, then try again.";
+    return "The desktop-owned Unsloth backend is still starting. Wait a moment, then try again.";
   }
 
   if (preflight.reason?.startsWith("desktop_owned_backend_unmanageable:")) {
     return preflight.port
-      ? `A desktop-owned Studio backend on port ${preflight.port} cannot be safely controlled by this desktop app. Stop that backend, then reopen Studio.`
-      : "A desktop-owned Studio backend cannot be safely controlled by this desktop app. Stop that backend, then reopen Studio.";
+      ? `A desktop-owned Unsloth backend on port ${preflight.port} cannot be safely controlled by this desktop app. Stop that backend, then reopen Unsloth.`
+      : "A desktop-owned Unsloth backend cannot be safely controlled by this desktop app. Stop that backend, then reopen Unsloth.";
   }
 
   return preflight.port
-    ? `A Studio server for this install is already running from a terminal on port ${preflight.port}. Stop that server, or run \`unsloth studio update\` from that terminal before using the desktop app.`
-    : "A Studio server for this install is already running from a terminal. Stop that server, or run `unsloth studio update` from that terminal before using the desktop app.";
+    ? `A Unsloth server for this install is already running from a terminal on port ${preflight.port}. Stop that server, or run \`unsloth studio update\` from that terminal before using the desktop app.`
+    : "A Unsloth server for this install is already running from a terminal. Stop that server, or run `unsloth studio update` from that terminal before using the desktop app.";
 }
 
 async function waitForManagedServerReady(
@@ -248,8 +248,8 @@ export function useTauriBackend() {
           } else {
             setBackendError(
               preflight.disposition === "owned_stale"
-                ? "Desktop-owned Studio backend is too old for this desktop app. Run `unsloth studio update`, then restart Studio."
-                : "Managed Studio install is too old. Run `unsloth studio update`.",
+                ? "Desktop-owned Unsloth backend is too old for this desktop app. Run `unsloth studio update`, then restart Unsloth."
+                : "Managed Unsloth install is too old. Run `unsloth studio update`.",
             );
           }
           return;
@@ -304,7 +304,7 @@ export function useTauriBackend() {
       if (msg.includes("already running")) {
         startingRef.current = false;
         setBackendError(
-          "Managed server is already running but did not report a port. Restart Studio and try again.",
+          "Managed server is already running but did not report a port. Restart Unsloth and try again.",
         );
         return;
       }
@@ -596,7 +596,7 @@ export function useTauriBackend() {
       const detail =
         event instanceof CustomEvent && typeof event.detail === "string"
           ? event.detail
-          : "Desktop authentication failed. Update or repair the managed Studio install, then restart Studio.";
+          : "Desktop authentication failed. Update or repair the managed Unsloth install, then restart Unsloth.";
       setAuthFailure(detail);
     };
     window.addEventListener("tauri-auth-failed", onAuthFailed);
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index a0ee28fd86..19863d42bb 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -83,7 +83,7 @@ export const en = {
     title: "Settings",
     dialog: {
       title: "Settings",
-      description: "Manage your Unsloth Studio preferences.",
+      description: "Manage your Unsloth preferences.",
       closeAriaLabel: "Close settings",
     },
     tabs: {
@@ -93,11 +93,11 @@ export const en = {
       chat: "Chat",
       connections: "Connections",
       apiKeys: "API",
-      about: "Help",
+      about: "About",
     },
     general: {
       title: "General",
-      description: "Global preferences for Unsloth Studio.",
+      description: "Global preferences for Unsloth.",
       account: "Account",
       huggingFaceToken: "Hugging Face token",
       huggingFaceTokenDescription:
@@ -112,38 +112,44 @@ export const en = {
         sectionTitle: "Helper LLM",
         preloadOnStartup: "Pre-cache Helper LLM on startup",
         preloadOnStartupDescription:
-          "Download and cache the AI Assist helper model in the background when Studio starts. Off by default; AI Assist can still download it on demand when clicked.",
+          "Download the AI Assist helper model in the background on startup. Off by default; AI Assist can still fetch it on demand.",
         disabledByEnv:
           "Disabled by UNSLOTH_HELPER_MODEL_DISABLE in the backend environment.",
         loadError: "Failed to load Helper LLM settings.",
         saveError: "Failed to save Helper LLM settings.",
       },
+      notifications: {
+        sectionTitle: "Notifications",
+        showLlamaUpdates: "llama.cpp update notifications",
+        showLlamaUpdatesDescription:
+          "Notify when a newer llama.cpp build is available. Turn off if you only train.",
+      },
       gettingStarted: "Getting started",
       startOnboarding: "Start onboarding",
       startOnboardingDescription:
-        "Open the setup wizard again without changing your account.",
+        "Reopen the setup wizard without changing your account.",
       startOnboardingAction: "Start onboarding",
       uploads: {
         sectionTitle: "Uploads",
         maxUploadSize: "Training dataset upload cap",
         maxUploadSizeDescription:
-          "Applies to training dataset uploads. Default is {defaultSize} MB.",
+          "Default is {defaultSize} MB.",
       },
       resetPreferences: {
         sectionTitle: "Danger zone",
         label: "Reset all local preferences",
         description:
-          "Clears local-only preferences. Chats, API access, and DB-backed settings are not affected.",
+          "Clears local-only preferences. Chats, API access, and DB-backed settings are kept.",
         action: "Reset preferences",
         confirmTitle: "Reset all local preferences?",
         confirmDescription:
-          "This clears local-only preferences, then reloads Studio. Chats, API access, and DB-backed settings are not affected.",
+          "Clears local-only preferences and reloads Unsloth. Chats, API access, and DB-backed settings are kept.",
         confirmAction: "Reset and reload",
       },
     },
     profile: {
       title: "Profile",
-      description: "Update how your profile appears in Studio.",
+      description: "How your profile appears in Unsloth.",
       changePicture: "Change profile picture",
       displayName: "Display name",
       nameSaved: "Profile name saved",
@@ -163,7 +169,7 @@ export const en = {
       theme: {
         title: "Theme",
         label: "Color scheme",
-        description: "Choose light, dark, or follow your system.",
+        description: "Light, dark, or follow your system.",
         system: "System",
         light: "Light",
         dark: "Dark",
@@ -171,7 +177,7 @@ export const en = {
       language: {
         title: "Language",
         label: "Display language",
-        description: "Choose the language used by Studio.",
+        description: "The language used by Unsloth.",
       },
       layout: {
         title: "Layout",
@@ -182,25 +188,25 @@ export const en = {
     },
     chat: {
       title: "Chat",
-      description: "Manage your chat history stored on this device.",
+      description: "Manage chat history stored on this device.",
       artifacts: {
         title: "Artifacts",
         collapseHtmlBlocks: "Collapse HTML blocks",
         collapseHtmlBlocksDescription:
-          "Artifacts mode collapses full HTML fallback automatically. Turn this on to also collapse full fenced HTML documents when Artifacts is off.",
+          "Artifacts mode collapses full HTML automatically. Turn on to also collapse fenced HTML documents when Artifacts is off.",
         allowNetworkAccess: "Allow artifact network access",
         allowNetworkAccessDescription:
-          "Let artifact previews load scripts, styles, fonts, media, fetch, and WebSocket resources from HTTP(S) CDNs. Keep off for fully offline previews.",
+          "Let artifact previews load scripts, styles, fonts, media, and network resources from CDNs. Keep off for fully offline previews.",
       },
       data: "Data",
       exportHistory: "Export chat history",
       exportHistoryDescription:
-        "Download all chats and messages as a JSON file.",
+        "Download all chats and messages as JSON.",
       exportAction: "Export",
       exportingAction: "Exporting...",
       exportConversations: "Export Recents and Projects",
       exportConversationsDescription:
-        "Download Recents only, or Recents plus project chats, as Raw JSONL, CSV, or ShareGPT JSONL, combined or one file per chat.",
+        "Download Recents or Recents plus project chats as Raw JSONL, CSV, or ShareGPT JSONL, combined or per chat.",
       exportConversationsAction: "Export",
       exportScopeRecents: "Recents",
       exportScopeAll: "Recents + Projects",
@@ -208,14 +214,14 @@ export const en = {
       exportPerChatSuffix: "(per chat)",
       importChats: "Import chats",
       importChatsDescription:
-        "Add conversations from a JSONL, NDJSON, or CSV export to Recents.",
+        "Import a JSONL, NDJSON, or CSV export into Recents.",
       importChatsAction: "Import",
       importNoConversations: "No conversations found in file.",
       importedOneChat: "Imported 1 conversation to Recents.",
       importedChatCount: "Imported {count} conversations to Recents.",
       importFailed: "Import failed.",
       clearHistory: "Clear chat history",
-      clearHistoryDescription: "Delete local chat history from this device.",
+      clearHistoryDescription: "Delete chat history from this device.",
       clearAction: "Clear",
       clearAllChats: "Clear all chats",
       clearAllChatsDescription: "Permanently delete every chat on this device.",
@@ -228,7 +234,7 @@ export const en = {
       clearOneChatTitle: "Clear 1 chat?",
       clearChatsTitle: "Clear {count} chats?",
       clearChatsConfirmDescription:
-        "This permanently deletes every chat and message stored on this device. This cannot be undone.",
+        "Permanently deletes every chat on this device. This cannot be undone.",
       clearingAction: "Clearing...",
       clearOneChatAction: "Clear 1 chat",
       clearChatCountAction: "Clear {count} chats",
@@ -251,12 +257,12 @@ export const en = {
     },
     connections: {
       title: "Connections",
-      description: "Manage providers and external service connections.",
+      description: "Manage providers and external connections.",
     },
     apiKeys: {
       title: "API",
       description:
-        "Access Unsloth programmatically via the OpenAI-compatible API.",
+        "Access Unsloth via the OpenAI-compatible API.",
       readDocs: "Read the API docs",
       noAccess: "No API access yet.",
       newBadge: "New",
@@ -296,62 +302,71 @@ export const en = {
       revokeToken: "Revoke token",
       revokeTitle: 'Revoke access token "{name}"?',
       revokeDescription:
-        "Applications using this token will immediately lose access. This cannot be undone.",
+        "Apps using this token immediately lose access. This cannot be undone.",
       revokeAction: 'Revoke "{name}"',
       revoking: "Revoking...",
     },
     about: {
       title: "About",
       description:
-        "Documentation, release notes, feedback, and Studio build info.",
-      studioVersion: "Studio Version",
+        "Docs, release notes, feedback, and build info.",
+      studioVersion: "Unsloth Version",
       packageVersion: "Package Version",
-      updates: "Updates",
+      updates: "Update",
       help: "Help",
       documentation: "Documentation",
       releaseNotes: "Release notes",
       whatsNew: "What's new",
       feedback: "Feedback",
       reportIssue: "Report an issue",
+      license: {
+        sectionTitle: "License",
+        studioLabel: "Unsloth Studio",
+        studioLicense: "AGPL-3.0",
+        studioDescription:
+          "Open source under the GNU AGPL v3.0.",
+        libraryLabel: "Unsloth Core",
+        libraryLicense: "Apache-2.0",
+        libraryDescription: "Licensed under Apache 2.0.",
+      },
       dangerZone: "Danger zone",
       shutDownStudio: "Shut down Unsloth Studio",
       shutDownStudioDescription:
-        "Stops the Studio server process and ends your session.",
+        "Stops the Unsloth server and ends your session.",
       shutDown: "Shut down",
       update: {
         title: "Update Unsloth Studio",
-        openPowerShell: "Open PowerShell and run:",
-        openTerminal: "Open Terminal and run:",
         commandText: "{label} text",
         copied: "Copied",
         copyCommand: "Copy command",
         commandCopied: "{label} copied",
         copyNamedCommand: "Copy {label}",
-        checkingInstall: "Checking how Studio was installed...",
+        checkingInstall: "Checking how Unsloth was installed...",
+        installIntro: "To install or update Unsloth:",
+        localUpdateHeading: "Local update",
+        installCommandUnix: "macOS/Linux install command",
+        installCommandWindows: "Windows install command",
         localInstallDetected:
-          "Source or local install detected. To avoid replacing it with PyPI, update from the checkout or source you originally installed from.",
-        pullThenUpdate:
-          "Pull latest changes from your Unsloth repo checkout, then update Studio locally:",
+          "Local install detected. Update from your original checkout to avoid replacing it with PyPI.",
+        pullThenUpdate: "Pull the latest changes, then run the local installer:",
         gitPullCommand: "git pull command",
-        localUpdateCommand: "local update command",
-        localInstallerFallback:
-          "If the Studio update command is unavailable, run the local installer from that checkout:",
         localInstallerCommand: "local installer command",
         sourceInstallDetected:
-          "This looks like a source or VCS package install. Reinstall from the original local path or Git URL you used.",
+          "Source or VCS package install detected. Reinstall from the original local path or Git URL.",
         repoCheckoutFallback:
-          "If you still have the Unsloth repo checkout, run the local installer from that checkout:",
-        restartAfterUpdate:
-          "Restart Studio after updating for changes to take effect.",
+          "If you still have the repo checkout, run the local installer from it:",
+        restartAfterUpdate: "Restart Unsloth after updating.",
+        desktopManaged:
+          "The desktop app keeps its bundled backend updated and will prompt when a new version is available.",
         unknownInstall:
-          "Studio could not detect how it was installed. Check how you installed Studio first, then choose the matching update path.",
-        curlOrPypi: "For curl or PyPI installs, run:",
-        updateCommand: "update command",
+          "Could not detect how Unsloth was installed. For installer or PyPI installs, use the commands above.",
         localCheckout:
-          "For local checkout installs, update from that checkout instead and use the local update command:",
-        fallbackInstruction:
-          "If that fails or unsloth studio update is unavailable, run:",
-        fallbackCommand: "fallback command",
+          "For local checkout installs, run the local installer from that checkout:",
+        docs: "Install docs:",
+        docsInstall: "Installation",
+        docsUpdating: "Updating",
+        docsMac: "Mac",
+        docsWindows: "Windows",
       },
     },
   },
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index e7d3babfe9..5173f9fa74 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -93,7 +93,7 @@ export const zhCN = {
       chat: "聊天",
       connections: "连接",
       apiKeys: "API",
-      about: "帮助",
+      about: "关于",
     },
     general: {
       title: "通用",
@@ -106,6 +106,12 @@ export const zhCN = {
       chatDefaults: "聊天默认设置",
       autoTitleNewChats: "自动为新聊天命名",
       autoTitleNewChatsDescription: "根据第一条消息生成简短标题。",
+      notifications: {
+        sectionTitle: "通知",
+        showLlamaUpdates: "llama.cpp 更新通知",
+        showLlamaUpdatesDescription:
+          "有新的 llama.cpp 构建时提醒。如果只用于训练可以关闭。",
+      },
       gettingStarted: "入门",
       startOnboarding: "开始引导",
       startOnboardingDescription: "重新打开设置向导，不会更改你的账号。",
@@ -124,13 +130,13 @@ export const zhCN = {
         action: "重置偏好设置",
         confirmTitle: "重置所有本地偏好设置？",
         confirmDescription:
-          "这会清除仅保存在本地的偏好设置，然后重新加载 Studio。聊天、API 访问权限和数据库中的设置不会受到影响。",
+          "这会清除仅保存在本地的偏好设置，然后重新加载 Unsloth。聊天、API 访问权限和数据库中的设置不会受到影响。",
         confirmAction: "重置并重新加载",
       },
     },
     profile: {
       title: "个人资料",
-      description: "更新你在 Studio 中显示的个人资料。",
+      description: "更新你在 Unsloth 中显示的个人资料。",
       changePicture: "更换头像",
       displayName: "显示名称",
       nameSaved: "个人资料名称已保存",
@@ -150,7 +156,7 @@ export const zhCN = {
       language: {
         title: "语言",
         label: "显示语言",
-        description: "选择 Studio 使用的语言。",
+        description: "选择 Unsloth 使用的语言。",
       },
       theme: {
         title: "主题",
@@ -274,9 +280,9 @@ export const zhCN = {
       revoking: "撤销中...",
     },
     about: {
-      title: "帮助",
-      description: "文档、发布说明、反馈和 Studio 构建信息。",
-      studioVersion: "Studio 版本",
+      title: "关于",
+      description: "文档、发布说明、反馈和 Unsloth 构建信息。",
+      studioVersion: "Unsloth 版本",
       packageVersion: "包版本",
       updates: "更新",
       help: "帮助",
@@ -285,43 +291,52 @@ export const zhCN = {
       whatsNew: "最新内容",
       feedback: "反馈",
       reportIssue: "报告问题",
+      license: {
+        sectionTitle: "许可证",
+        studioLabel: "Unsloth Studio",
+        studioLicense: "AGPL-3.0",
+        studioDescription: "基于 GNU AGPL v3.0 开源。",
+        libraryLabel: "Unsloth Core",
+        libraryLicense: "Apache-2.0",
+        libraryDescription: "基于 Apache License 2.0 许可。",
+      },
       dangerZone: "危险区域",
       shutDownStudio: "关闭 Unsloth Studio",
-      shutDownStudioDescription: "停止 Studio 服务进程并结束你的会话。",
+      shutDownStudioDescription: "停止 Unsloth 服务进程并结束你的会话。",
       shutDown: "关闭",
       update: {
         title: "更新 Unsloth Studio",
-        openPowerShell: "打开 PowerShell 并运行：",
-        openTerminal: "打开终端并运行：",
         commandText: "{label} 文本",
         copied: "已复制",
         copyCommand: "复制命令",
         commandCopied: "{label} 已复制",
         copyNamedCommand: "复制 {label}",
-        checkingInstall: "正在检查 Studio 的安装方式...",
+        checkingInstall: "正在检查 Unsloth 的安装方式...",
+        installIntro: "安装或更新 Unsloth：",
+        localUpdateHeading: "本地更新",
+        installCommandUnix: "macOS/Linux 安装命令",
+        installCommandWindows: "Windows 安装命令",
         localInstallDetected:
-          "检测到源码或本地安装。为避免替换为 PyPI 版本，请从最初安装时使用的 checkout 或源码位置更新。",
-        pullThenUpdate:
-          "从你的 Unsloth 仓库 checkout 拉取最新变更，然后本地更新 Studio：",
+          "检测到本地安装。请从最初的 checkout 更新，以免被 PyPI 版本替换。",
+        pullThenUpdate: "拉取最新变更，然后运行本地安装器：",
         gitPullCommand: "git pull 命令",
-        localUpdateCommand: "本地更新命令",
-        localInstallerFallback:
-          "如果 Studio 更新命令不可用，请从该 checkout 运行本地安装器：",
         localInstallerCommand: "本地安装器命令",
         sourceInstallDetected:
           "这看起来是源码或 VCS 包安装。请从最初使用的本地路径或 Git URL 重新安装。",
         repoCheckoutFallback:
           "如果你仍保留 Unsloth 仓库 checkout，请从该 checkout 运行本地安装器：",
-        restartAfterUpdate: "更新后重启 Studio，使变更生效。",
+        restartAfterUpdate: "更新后请重启 Unsloth。",
+        desktopManaged:
+          "桌面应用会自动更新其内置后端，有新版本时会提示。",
         unknownInstall:
-          "Studio 无法检测安装方式。请先确认你如何安装 Studio，然后选择匹配的更新方式。",
-        curlOrPypi: "对于 curl 或 PyPI 安装，请运行：",
-        updateCommand: "更新命令",
+          "Unsloth 无法检测安装方式。如果你使用一键安装器或 PyPI 安装，请使用上面的命令。",
         localCheckout:
-          "对于本地 checkout 安装，请改为从该 checkout 更新并使用本地更新命令：",
-        fallbackInstruction:
-          "如果失败，或 unsloth studio update 不可用，请运行：",
-        fallbackCommand: "备用命令",
+          "对于本地 checkout 安装，请改为从该 checkout 运行本地安装器：",
+        docs: "安装文档：",
+        docsInstall: "安装",
+        docsUpdating: "更新",
+        docsMac: "Mac",
+        docsWindows: "Windows",
       },
     },
   },
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 0d3b1698e1..9e394a31e7 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -552,6 +552,7 @@
 	.sidebar-nav-btn[data-state="open"],
 	.group\/project-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.group\/project-chat-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.group\/projects-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.group\/recent-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.group\/run-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn {
 		background-color: var(--nav-surface-hover) !important;
@@ -562,6 +563,7 @@
 	.dark .sidebar-nav-btn[data-state="open"],
 	.dark .group\/project-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.dark .group\/project-chat-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
+	.dark .group\/projects-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.dark .group\/recent-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn,
 	.dark .group\/run-item:hover:not(:has(.sidebar-row-action:hover)) .sidebar-nav-btn {
 		color: #fff !important;
@@ -957,6 +959,11 @@
 		border-radius: 14px !important;
 	}
 
+	/* Account menu: a touch rounder than standard list menus. */
+	[data-slot="dropdown-menu-content"].app-user-menu.menu-soft-surface-up {
+		border-radius: 18px !important;
+	}
+
 	/* Every dropdown/menu/select/popover: borderless, chatbox shadow in light,
 	   none in dark. !important so it also overrides the bespoke menu shadows. */
 	[data-slot="dropdown-menu-content"],
@@ -1078,13 +1085,16 @@
 	[data-pill-compact="true"]
 		.composer-pill-btn:not([data-keep-label])[data-pill-label]:hover::after {
 		content: attr(data-pill-label);
-		@apply pointer-events-none absolute bottom-[calc(100%+6px)] left-1/2 z-50 -translate-x-1/2 rounded-[9px] bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug whitespace-nowrap text-white shadow-md;
+		/* Always one nowrap line, so always a full pill. */
+		@apply pointer-events-none absolute bottom-[calc(100%+6px)] left-1/2 z-50 -translate-x-1/2 rounded-full bg-black px-2.5 py-1.5 text-[11px] font-medium leading-snug whitespace-nowrap text-white shadow-md;
 	}
 
 	/* Compact caret pills (RAG, MCP) open their menu on click instead of
-	   toggling off, so keep the icon and skip the X swap. */
+	   toggling off, so keep the icon and skip the X swap. No data-active
+	   requirement: the off-switch glyph rules below hide the icon on hover
+	   even for inactive pills, which left a blank slot in compact mode. */
 	[data-pill-compact="true"]
-		.composer-pill-btn:not([data-keep-label]):has(.composer-pill-caret)[data-active="true"]:hover
+		.composer-pill-btn:not([data-keep-label]):has(.composer-pill-caret):hover
 		.composer-pill-glyph
 		> :not(.composer-pill-x) {
 		opacity: 1;
@@ -1512,6 +1522,20 @@
 		}
 	}
 
+	/* Indeterminate loading bar: a 1/3-width segment sweeping the track. */
+	.loading-bar-slide {
+		animation: loading-bar-slide 1.3s ease-in-out infinite;
+	}
+
+	@keyframes loading-bar-slide {
+		from {
+			transform: translateX(-110%);
+		}
+		to {
+			transform: translateX(420%);
+		}
+	}
+
 	@keyframes artifact-loading-line {
 		0% {
 			transform: translate3d(-125%, 0, 0) scaleX(0.78);
@@ -1750,10 +1774,10 @@
 	margin: 0 !important;
 }
 
-/* Composer shadow on the dark background color so toasts
-   do not merge into card-colored surfaces behind them. */
+/* Dark toasts share the chatbox surface color (.chat-composer-surface
+   uses var(--card) in dark); the composer shadow lifts them off the page. */
 .dark [data-sonner-toast][data-styled='true'] {
-	background-color: var(--background) !important;
+	background-color: var(--card) !important;
 	box-shadow: 0 2px 8px -2px rgba(0, 0, 0, 0.16) !important;
 }
 
@@ -2099,6 +2123,11 @@
 		animation-iteration-count: infinite !important;
 	}
 
+	.loading-bar-slide {
+		animation-duration: 1.3s !important;
+		animation-iteration-count: infinite !important;
+	}
+
 	/* Keep the plus/x morph animating under reduced motion (small rotation,
 	   like the spinners above). */
 	.unsloth-composer-plus svg {
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 2b42a7a058..bd8c90dc9c 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -856,6 +856,16 @@ def format_byte_count(num_bytes: float) -> str:
     return f"{num_bytes:.1f} B"
 
 
+def _progress_percent_step() -> int:
+    """Non-tty milestone granularity. The in-app updater sets
+    UNSLOTH_PROGRESS_PERCENT_STEP=5 to stream finer progress lines."""
+    try:
+        step = int(os.environ.get("UNSLOTH_PROGRESS_PERCENT_STEP", "25"))
+    except ValueError:
+        return 25
+    return min(max(step, 1), 50)
+
+
 class DownloadProgress:
     def __init__(self, label: str, total_bytes: int | None) -> None:
         self.label = label
@@ -868,6 +878,7 @@ class DownloadProgress:
         )
         self.is_tty = term_ok and self.stream.isatty()
         self.completed = False
+        self.milestone_step = _progress_percent_step()
         self.last_milestone_percent = -1
         self.last_milestone_bytes = 0
         self.has_rendered_tty_progress = False
@@ -918,7 +929,8 @@ class DownloadProgress:
         should_emit = False
         if self.total_bytes is not None:
             percent = int((downloaded_bytes * 100) / max(self.total_bytes, 1))
-            milestone_percent = min((percent // 25) * 25, 100)
+            step = self.milestone_step
+            milestone_percent = min((percent // step) * step, 100)
             if milestone_percent > self.last_milestone_percent and milestone_percent < 100:
                 self.last_milestone_percent = milestone_percent
                 should_emit = True

From 983c1f0616b65e3c26a3dc3eeee389e8c9a28ae7 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 09:33:28 -0700
Subject: [PATCH 216/222] Bump install.sh / install.ps1 pin to
 unsloth>=2026.6.3 (#6212)

PyPI release unsloth 2026.6.3 is now live. Bump the pinned floor in
install.sh and install.ps1 from unsloth>=2026.6.2 to unsloth>=2026.6.3
so fresh installs resolve to the new wheel.
---
 install.ps1 | 10 +++++-----
 install.sh  | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/install.ps1 b/install.ps1
index fd7d3f4a81..cf7bb63cdf 100644
--- a/install.ps1
+++ b/install.ps1
@@ -1876,7 +1876,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.3" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Resolve pydantic WITH deps so pip pins pydantic-core
                 # to the matching version (no-torch-runtime.txt below
@@ -1890,7 +1890,7 @@ shell.Run cmd, 0, False
                 }
             }
         } else {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --reinstall-package unsloth --reinstall-package unsloth-zoo "unsloth>=2026.6.3" unsloth-zoo }
         }
         if ($baseInstallExit -ne 0) {
             Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
@@ -1937,7 +1937,7 @@ shell.Run cmd, 0, False
         if ($SkipTorch) {
             # No-torch: install unsloth + unsloth-zoo with --no-deps, then
             # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.6.2" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "unsloth>=2026.6.3" unsloth-zoo }
             if ($baseInstallExit -eq 0) {
                 # Same pydantic-with-deps trick as the migrated branch.
                 $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython pydantic }
@@ -1949,7 +1949,7 @@ shell.Run cmd, 0, False
                 }
             }
         } elseif ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.6.2" unsloth-zoo }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth "unsloth>=2026.6.3" unsloth-zoo }
         } else {
             $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython --upgrade-package unsloth -- "$PackageName" }
         }
@@ -1977,7 +1977,7 @@ shell.Run cmd, 0, False
         Write-TauriLog "STEP" "Installing unsloth"
         substep "installing unsloth (this may take a few minutes)..."
         if ($StudioLocalInstall) {
-            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.6.2" --torch-backend=auto }
+            $baseInstallExit = Invoke-InstallCommand { uv pip install --python $VenvPython unsloth-zoo "unsloth>=2026.6.3" --torch-backend=auto }
             if ($baseInstallExit -ne 0) {
                 Write-Host "[ERROR] Failed to install unsloth (exit code $baseInstallExit)" -ForegroundColor Red
                 return (Exit-InstallFailure "Failed to install unsloth (exit code $baseInstallExit)" $baseInstallExit)
diff --git a/install.sh b/install.sh
index df9eca65c7..532ac61bc0 100755
--- a/install.sh
+++ b/install.sh
@@ -2405,7 +2405,7 @@ if [ "$_MIGRATED" = true ]; then
         # to prevent transitive torch resolution.
         run_install_cmd "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.6.2" unsloth-zoo
+            "unsloth>=2026.6.3" unsloth-zoo
         # Resolve pydantic WITH deps so pip pins pydantic-core to the
         # matching version (no-torch-runtime.txt below is --no-deps).
         # All transitive deps are torch-free.
@@ -2418,7 +2418,7 @@ if [ "$_MIGRATED" = true ]; then
     else
         run_install_cmd "install unsloth (migrated)" uv pip install --python "$_VENV_PY" \
             --reinstall-package unsloth --reinstall-package unsloth-zoo \
-            "unsloth>=2026.6.2" unsloth-zoo
+            "unsloth>=2026.6.3" unsloth-zoo
     fi
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         substep "overlaying local repo (editable)..."
@@ -2622,7 +2622,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         # runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
         run_install_cmd "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
             --upgrade-package unsloth --upgrade-package unsloth-zoo \
-            "unsloth>=2026.6.2" unsloth-zoo
+            "unsloth>=2026.6.3" unsloth-zoo
         # Same pydantic-with-deps trick as the migrated branch.
         run_install_cmd "install pydantic (with deps for compatible core)" \
             uv pip install --python "$_VENV_PY" pydantic
@@ -2640,7 +2640,7 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
         fi
     elif [ "$STUDIO_LOCAL_INSTALL" = true ]; then
         run_install_cmd "install unsloth (local)" uv pip install --python "$_VENV_PY" \
-            --upgrade-package unsloth "unsloth>=2026.6.2" unsloth-zoo
+            --upgrade-package unsloth "unsloth>=2026.6.3" unsloth-zoo
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."
@@ -2672,7 +2672,7 @@ else
     tauri_log "STEP" "Installing Unsloth"
     substep "installing unsloth (this may take a few minutes)..."
     if [ "$STUDIO_LOCAL_INSTALL" = true ]; then
-        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.6.2" --torch-backend=auto
+        run_install_cmd "install unsloth (auto torch backend)" uv pip install --python "$_VENV_PY" unsloth-zoo "unsloth>=2026.6.3" --torch-backend=auto
         substep "overlaying local repo (editable)..."
         run_install_cmd "overlay local repo" uv pip install --python "$_VENV_PY" -e "$_REPO_ROOT" --no-deps
         substep "overlaying unsloth-zoo from git main..."

From 672d8f058199978d06e434ad509f2354f9b8989c Mon Sep 17 00:00:00 2001
From: alkinun <alkinunl@gmail.com>
Date: Thu, 11 Jun 2026 22:13:53 +0300
Subject: [PATCH 217/222] Expose runtime context length for hub models (#6154)

* expose runtime context length for hub models

* runtime context helper review

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Etherll <61019402+Etherll@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 studio/backend/core/inference/inference.py    |  9 ++++
 .../backend/core/inference/mlx_inference.py   |  2 +
 studio/backend/core/inference/orchestrator.py |  1 +
 .../backend/core/inference/runtime_context.py | 22 +++++++++
 studio/backend/core/inference/worker.py       | 13 ++++++
 studio/backend/models/inference.py            |  2 +-
 studio/backend/routes/inference.py            | 45 ++++++++++++++-----
 .../tests/test_native_context_length.py       | 39 ++++++++++++++++
 unsloth_cli/commands/studio.py                | 23 +++++++++-
 .../tests/test_studio_run_parallel_flag.py    | 37 +++++++++++++++
 10 files changed, 180 insertions(+), 13 deletions(-)
 create mode 100644 studio/backend/core/inference/runtime_context.py

diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.py
index 55c2c551a3..2b9517692f 100644
--- a/studio/backend/core/inference/inference.py
+++ b/studio/backend/core/inference/inference.py
@@ -25,6 +25,7 @@ from utils.hardware import (
     get_visible_gpu_count,
 )
 from core.inference.audio_codecs import AudioCodecManager
+from core.inference.runtime_context import runtime_context_length
 from io import StringIO
 import structlog
 from loggers import get_logger
@@ -405,6 +406,10 @@ class InferenceBackend:
 
                 # Reject CPU/disk offload for audio models too
                 raise_if_offloaded(self.models[model_name]["model"], device_map, "Inference")
+                self.models[model_name]["context_length"] = runtime_context_length(
+                    self.models[model_name].get("model"),
+                    max_seq_length,
+                )
 
                 self.active_model_name = model_name
                 self.loading_models.discard(model_name)
@@ -485,6 +490,10 @@ class InferenceBackend:
                 self.models[model_name]["tokenizer"] = tokenizer
 
             raise_if_offloaded(self.models[model_name]["model"], device_map, "Inference")
+            self.models[model_name]["context_length"] = runtime_context_length(
+                self.models[model_name].get("model"),
+                max_seq_length,
+            )
 
             self._load_chat_template_info(model_name)
 
diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index fbbdb9a773..5c7799152f 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -7,6 +7,7 @@ instead of torch/transformers for model loading and generation.
 
 import threading
 from typing import Optional, Generator
+from core.inference.runtime_context import runtime_context_length
 from loggers import get_logger
 
 logger = get_logger(__name__)
@@ -175,6 +176,7 @@ class MLXInferenceBackend:
             "is_audio": False,
             "audio_type": None,
             "has_audio_input": False,
+            "context_length": runtime_context_length(self._model, max_seq_length),
         }
         # Capture chat_template_info so the worker IPC reply ships it back and
         # the route layer classifies capabilities like the other paths.
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 32bb25c976..4e4788ace9 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -727,6 +727,7 @@ class InferenceOrchestrator:
                         "is_audio": model_info.get("is_audio", False),
                         "audio_type": model_info.get("audio_type"),
                         "has_audio_input": model_info.get("has_audio_input", False),
+                        "context_length": model_info.get("context_length"),
                     }
                     # Mirror chat_template_info so routes can classify caps
                     # without re-entering the subprocess.
diff --git a/studio/backend/core/inference/runtime_context.py b/studio/backend/core/inference/runtime_context.py
new file mode 100644
index 0000000000..8b881628be
--- /dev/null
+++ b/studio/backend/core/inference/runtime_context.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Runtime context length helpers shared by inference backends."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def runtime_context_length(model: Any, fallback: Optional[int] = None) -> Optional[int]:
+    """Return the effective context length Unsloth attached to a loaded model."""
+    for value in (getattr(model, "max_seq_length", None), fallback):
+        if isinstance(value, bool):
+            continue
+        try:
+            value_int = int(value)
+        except (TypeError, ValueError):
+            continue
+        if value_int > 0:
+            return value_int
+    return None
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 4f5b985234..cc79654087 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -315,6 +315,18 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
                 "audio_type": getattr(mc, "audio_type", None),
                 "has_audio_input": getattr(mc, "has_audio_input", False),
             }
+            try:
+                _bm = getattr(backend, "models", {}) or {}
+                _entry = (
+                    _bm.get(mc.identifier)
+                    or _bm.get(getattr(backend, "active_model_name", None))
+                    or {}
+                )
+                _context_length = _entry.get("context_length")
+                if _context_length is not None:
+                    model_info["context_length"] = int(_context_length)
+            except Exception as _ctx_exc:
+                logger.warning("context_length forward failed: %s", _ctx_exc)
             # Forward chat_template_info so the parent can classify capabilities.
             try:
                 _bm = getattr(backend, "models", {}) or {}
@@ -881,6 +893,7 @@ def run_inference_process(*, cmd_queue: Any, resp_queue: Any, cancel_event, conf
                             name: {
                                 "is_vision": info.get("is_vision", False),
                                 "is_lora": info.get("is_lora", False),
+                                "context_length": info.get("context_length"),
                             }
                             for name, info in backend.models.items()
                         },
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index f94d5366eb..b70202d6ff 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -171,7 +171,7 @@ class LoadResponse(BaseModel):
         description = "Whether the model defaults require trust_remote_code to be enabled for loading.",
     )
     context_length: Optional[int] = Field(
-        None, description = "Model's native context length (from GGUF metadata)"
+        None, description = "Runtime context length in tokens for the loaded model"
     )
     max_context_length: Optional[int] = Field(
         None, description = "Maximum context length currently available on this hardware"
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 3333db9d07..3850d0cbb2 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -29,6 +29,16 @@ from utils.models import extract_model_size_b as _extract_model_size_b
 from utils.api_errors import openai_error_body, anthropic_error_body
 
 
+def _positive_int_or_none(value: Any) -> Optional[int]:
+    if isinstance(value, bool):
+        return None
+    try:
+        value_int = int(value)
+    except (TypeError, ValueError):
+        return None
+    return value_int if value_int > 0 else None
+
+
 def _install_httpcore_asyncgen_silencer() -> None:
     """Silence benign httpx/httpcore asyncgen GC noise on Python 3.13.
 
@@ -1390,6 +1400,7 @@ async def load_model(
                     reasoning_always_on = _sf_flags["reasoning_always_on"],
                     supports_preserve_thinking = _sf_flags["supports_preserve_thinking"],
                     supports_tools = _sf_flags["supports_tools"],
+                    context_length = _positive_int_or_none(_model_info.get("context_length")),
                     chat_template = _chat_template,
                 )
 
@@ -1731,6 +1742,7 @@ async def load_model(
             reasoning_always_on = _sf_flags["reasoning_always_on"],
             supports_preserve_thinking = _sf_flags["supports_preserve_thinking"],
             supports_tools = _sf_flags["supports_tools"],
+            context_length = _positive_int_or_none(_model_info.get("context_length")),
             chat_template = _chat_template,
         )
 
@@ -2119,6 +2131,7 @@ async def get_status(current_subject: str = Depends(get_current_subject)):
             reasoning_always_on = _sf_flags["reasoning_always_on"],
             supports_preserve_thinking = _sf_flags["supports_preserve_thinking"],
             supports_tools = _sf_flags["supports_tools"],
+            context_length = _positive_int_or_none(model_info.get("context_length")),
             chat_template = chat_template,
             llama_cpp_supports_mtp = _supports_mtp,
             llama_cpp_prebuilt_stale = _stale,
@@ -4625,28 +4638,38 @@ def _openai_model_objects() -> list[dict]:
             "created": _created,
             "owned_by": "local",
         }
-        # Extension fields: the real per-request window (post /props readback)
-        # so clients can budget/compact against the enforced limit.
-        if llama_backend.context_length:
-            entry["context_length"] = llama_backend.context_length
-        if llama_backend.max_context_length:
-            entry["max_context_length"] = llama_backend.max_context_length
+        _ctx = _positive_int_or_none(getattr(llama_backend, "context_length", None))
+        if _ctx is not None:
+            entry["context_length"] = _ctx
+        _max_ctx = _positive_int_or_none(getattr(llama_backend, "max_context_length", None))
+        if _max_ctx is not None:
+            entry["max_context_length"] = _max_ctx
+        _native_ctx = _positive_int_or_none(getattr(llama_backend, "native_context_length", None))
+        if _native_ctx is not None:
+            entry["native_context_length"] = _native_ctx
         models.append(entry)
 
     # Check Unsloth backend
     backend = get_inference_backend()
     if backend.active_model_name:
+        model_info = backend.models.get(backend.active_model_name, {})
         entry = {
             "id": backend.active_model_name,
             "object": "model",
             "created": _created,
             "owned_by": "local",
         }
-        _sf_ctx = getattr(backend, "context_length", None) or getattr(
-            backend, "max_seq_length", None
-        )
-        if _sf_ctx:
-            entry["context_length"] = _sf_ctx
+        _ctx = _positive_int_or_none(model_info.get("context_length"))
+        if _ctx is None:
+            for _candidate in (
+                getattr(backend, "context_length", None),
+                getattr(backend, "max_seq_length", None),
+            ):
+                _ctx = _positive_int_or_none(_candidate)
+                if _ctx is not None:
+                    break
+        if _ctx is not None:
+            entry["context_length"] = _ctx
         models.append(entry)
 
     return models
diff --git a/studio/backend/tests/test_native_context_length.py b/studio/backend/tests/test_native_context_length.py
index 0290bb1308..de1ca0649e 100644
--- a/studio/backend/tests/test_native_context_length.py
+++ b/studio/backend/tests/test_native_context_length.py
@@ -271,6 +271,7 @@ class TestPydanticModels:
     def test_load_response_has_field(self):
         """Field exists in LoadResponse.model_fields."""
         assert "native_context_length" in LoadResponse.model_fields
+        assert "context_length" in LoadResponse.model_fields
 
     def test_load_response_defaults_none(self):
         """Omitting native_context_length defaults to None."""
@@ -319,6 +320,7 @@ class TestPydanticModels:
     def test_status_response_has_field(self):
         """Field exists in InferenceStatusResponse.model_fields."""
         assert "native_context_length" in InferenceStatusResponse.model_fields
+        assert "context_length" in InferenceStatusResponse.model_fields
 
     def test_status_response_has_chat_template_field(self):
         """Status includes chat_template so the UI can rehydrate after refresh."""
@@ -347,6 +349,18 @@ class TestPydanticModels:
         roundtripped = LoadResponse.model_validate_json(resp.model_dump_json())
         assert roundtripped.native_context_length == 131072
 
+    def test_context_length_roundtrip(self):
+        """Runtime context_length serializes for non-GGUF/hub models."""
+        resp = LoadResponse(
+            status = "loaded",
+            model = "test",
+            display_name = "Test",
+            inference = {},
+            context_length = 8192,
+        )
+        roundtripped = LoadResponse.model_validate_json(resp.model_dump_json())
+        assert roundtripped.context_length == 8192
+
 
 # =====================================================================
 # D. TestRouteCompleteness -- source-level verification
@@ -408,6 +422,16 @@ class TestRouteCompleteness:
                 "native_context_length" not in block
             ), f"Non-GGUF LoadResponse should not set native_context_length:\n{block[:200]}"
 
+    def test_non_gguf_load_responses_set_runtime_context_length(self):
+        """Non-GGUF LoadResponse blocks report runtime context_length."""
+        blocks = self._find_construction_blocks("LoadResponse")
+        non_gguf = [b for b in blocks if "is_gguf = True" not in b and "is_gguf=True" not in b]
+        assert non_gguf, "Expected at least one non-GGUF LoadResponse block"
+        for block in non_gguf:
+            assert (
+                "context_length" in block
+            ), f"Non-GGUF LoadResponse should set context_length:\n{block[:200]}"
+
     def test_status_path(self):
         """InferenceStatusResponse construction with llama_backend has the field."""
         blocks = self._find_construction_blocks("InferenceStatusResponse")
@@ -420,6 +444,21 @@ class TestRouteCompleteness:
             found
         ), "No InferenceStatusResponse block with llama_backend has native_context_length"
 
+    def test_non_gguf_status_path_reports_runtime_context_length(self):
+        """Non-GGUF InferenceStatusResponse reports context_length from model_info."""
+        blocks = self._find_construction_blocks("InferenceStatusResponse")
+        found = False
+        for block in blocks:
+            if "is_gguf = False" in block and "context_length" in block:
+                found = True
+                break
+        assert found, "No non-GGUF InferenceStatusResponse block with context_length"
+
+    def test_openai_models_listing_reports_context_length(self):
+        """/v1/models includes context_length when the backend knows it."""
+        assert 'entry["context_length"]' in self._source
+        assert 'model_info.get("context_length")' in self._source
+
 
 # =====================================================================
 # E. TestEdgeCases
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 7493b87eee..fb63fbf208 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -570,6 +570,19 @@ def _load_model_via_http(
         raise RuntimeError(f"Model load failed (HTTP {exc.code}): {body}") from exc
 
 
+def _format_context_length_line(load_result: dict) -> Optional[str]:
+    value = load_result.get("context_length")
+    if isinstance(value, bool):
+        return None
+    try:
+        value_int = int(value)
+    except (TypeError, ValueError):
+        return None
+    if value_int <= 0:
+        return None
+    return f"  Context length: {value_int} tokens"
+
+
 # ── unsloth studio (server) ──────────────────────────────────────────
 
 
@@ -841,7 +854,10 @@ def run(
         None, "--gguf-variant", help = "GGUF quant variant (e.g. UD-Q4_K_XL)"
     ),
     max_seq_length: int = typer.Option(
-        0, "--max-seq-length", help = "Max sequence length (0 = model default)"
+        0,
+        "--max-seq-length",
+        "--context-length",
+        help = "Runtime context length in tokens (0 = model default for GGUF; 2048 for hub models)",
     ),
     load_in_4bit: bool = typer.Option(True, "--load-in-4bit/--no-load-in-4bit"),
     api_key_name: str = typer.Option(
@@ -1080,6 +1096,7 @@ def run(
 
     loaded_model = result.get("model", model)
     display_variant = f" ({gguf_variant})" if gguf_variant else ""
+    context_length_line = _format_context_length_line(result)
 
     # 6. Print banner.
     display_host = _resolve_external_ip() if host == "0.0.0.0" else host
@@ -1119,6 +1136,8 @@ def run(
         if _cf_url:
             typer.echo(f"  Secure link access via Cloudflare: {_cf_url}")
         typer.echo(f"  Model loaded: {loaded_model}{display_variant}")
+        if context_length_line:
+            typer.echo(context_length_line)
         typer.echo(f"  API Key:      {api_key}")
         typer.echo("")
         typer.echo("  OpenAI / Anthropic SDK base URL:")
@@ -1153,6 +1172,8 @@ def run(
         typer.echo(f"URL:     {base_url}")
         if _cf_url:
             typer.echo(f"Secure link access via Cloudflare: {_cf_url}")
+        if context_length_line:
+            typer.echo(context_length_line.strip())
         typer.echo(f"API Key: {api_key}")
         typer.secho(_tool_notice, fg = _tool_notice_fg, bold = True)
 
diff --git a/unsloth_cli/tests/test_studio_run_parallel_flag.py b/unsloth_cli/tests/test_studio_run_parallel_flag.py
index abc0b3c7c4..8870fa348d 100644
--- a/unsloth_cli/tests/test_studio_run_parallel_flag.py
+++ b/unsloth_cli/tests/test_studio_run_parallel_flag.py
@@ -51,6 +51,18 @@ def test_parallel_option_is_registered():
         assert required in flags, f"flag {required!r} missing from --parallel option"
 
 
+def test_context_length_alias_is_registered():
+    """`--context-length` is an operator-facing alias for --max-seq-length."""
+    studio_mod = _load_run_command()
+    import inspect
+
+    sig = inspect.signature(studio_mod.run)
+    opt = sig.parameters["max_seq_length"].default
+    flags = set(getattr(opt, "param_decls", None) or [])
+    assert "--max-seq-length" in flags
+    assert "--context-length" in flags
+
+
 def test_parallel_default_is_four():
     """Default must stay at 4 so plain `unsloth studio run` is unchanged."""
     studio_mod = _load_run_command()
@@ -249,6 +261,15 @@ def test_reexec_np_is_first_class_alias(monkeypatch):
     assert _value_after(argv, "--port") == "8888", argv
 
 
+def test_reexec_forwards_context_length_alias(monkeypatch):
+    """Alias should normalize to the existing child --max-seq-length flag."""
+    result, captured = _invoke_run(monkeypatch, _BASE + ["--context-length", "8192"])
+    assert len(captured) == 1, result.output
+    argv = captured[0]["argv"]
+    assert _value_after(argv, "--max-seq-length") == "8192", argv
+    assert "--context-length" not in argv, argv
+
+
 def test_reexec_mixed_parallel_with_passthrough(monkeypatch):
     """--parallel + llama-server pass-through flags must all reach the child."""
     result, captured = _invoke_run(
@@ -262,6 +283,22 @@ def test_reexec_mixed_parallel_with_passthrough(monkeypatch):
     assert _value_after(argv, "--temp") == "0.7", argv
 
 
+def test_context_length_banner_line_formats_ints():
+    studio_mod = _load_run_command()
+    assert studio_mod._format_context_length_line({"context_length": 4096}) == (
+        "  Context length: 4096 tokens"
+    )
+    assert studio_mod._format_context_length_line({"context_length": "8192"}) == (
+        "  Context length: 8192 tokens"
+    )
+
+
+@pytest.mark.parametrize("value", [None, 0, -1, True, ""])
+def test_context_length_banner_line_omits_unknown_values(value):
+    studio_mod = _load_run_command()
+    assert studio_mod._format_context_length_line({"context_length": value}) is None
+
+
 @pytest.mark.parametrize(
     "user_flag,expected_in_child",
     [

From fb56b82a383469dd707f92b8ee35e0fdc0d6fb07 Mon Sep 17 00:00:00 2001
From: oobabooga <oobabooga4@gmail.com>
Date: Thu, 11 Jun 2026 23:23:14 -0300
Subject: [PATCH 218/222] Studio: fix llama.cpp update banner offering a
 downgrade / sticking on mix releases (#6219)

---
 studio/backend/routes/llama.py                |   4 +-
 .../backend/tests/test_llama_cpp_freshness.py | 134 +++++++++++++++++-
 studio/backend/tests/test_llama_cpp_update.py |  52 ++++++-
 studio/backend/utils/llama_cpp_freshness.py   |  87 ++++++++++--
 studio/backend/utils/llama_cpp_update.py      |  33 ++++-
 5 files changed, 290 insertions(+), 20 deletions(-)

diff --git a/studio/backend/routes/llama.py b/studio/backend/routes/llama.py
index 47a5bc1dd3..3aae6f4209 100644
--- a/studio/backend/routes/llama.py
+++ b/studio/backend/routes/llama.py
@@ -41,7 +41,9 @@ class LlamaUpdateStatusResponse(BaseModel):
         False,
         description = "True when the install came from an Unsloth prebuilt (has a marker).",
     )
-    update_available: bool = Field(False, description = "True when installed_tag != latest_tag.")
+    update_available: bool = Field(
+        False, description = "True when the latest release is genuinely newer than the install."
+    )
     stale: bool = Field(
         False, description = "Update available AND install older than the staleness threshold."
     )
diff --git a/studio/backend/tests/test_llama_cpp_freshness.py b/studio/backend/tests/test_llama_cpp_freshness.py
index cb17e0d5e7..f8e4619ded 100644
--- a/studio/backend/tests/test_llama_cpp_freshness.py
+++ b/studio/backend/tests/test_llama_cpp_freshness.py
@@ -21,12 +21,25 @@ _BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
 if _BACKEND_DIR not in sys.path:
     sys.path.insert(0, _BACKEND_DIR)
 
+
+class _NoopLogger:
+    """structlog-style logger: every method swallows positional + kwargs.
+
+    A stdlib logging.Logger rejects structlog's keyword fields (e.g.
+    ``logger.warning(msg, error=...)``), which leaked into the update module's
+    error path and failed only when this file's stub loaded first.
+    """
+
+    def __getattr__(self, _name):
+        return lambda *a, **k: None
+
+
 _loggers_stub = _types.ModuleType("loggers")
-_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
+_loggers_stub.get_logger = lambda *a, **k: _NoopLogger()
 sys.modules.setdefault("loggers", _loggers_stub)
 
 _structlog_stub = _types.ModuleType("structlog")
-_structlog_stub.get_logger = lambda *a, **k: __import__("logging").getLogger("stub")
+_structlog_stub.get_logger = lambda *a, **k: _NoopLogger()
 sys.modules.setdefault("structlog", _structlog_stub)
 
 import pytest
@@ -51,6 +64,11 @@ def _write_marker(install_dir: Path, **overrides) -> Path:
         .replace("+00:00", "Z"),
     }
     payload.update(overrides)
+    # The installer always writes `tag` and `release_tag` from the same release
+    # (a normalized base vs the full release tag), so keep the pair consistent
+    # when a test overrides only `tag`.
+    if "tag" in overrides and "release_tag" not in overrides:
+        payload["release_tag"] = overrides["tag"]
     install_dir.mkdir(parents = True, exist_ok = True)
     (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(json.dumps(payload))
     return install_dir / "UNSLOTH_PREBUILT_INFO.json"
@@ -303,3 +321,115 @@ def test_format_stale_warning_singular_day():
     msg = fr.format_stale_warning({"installed_tag": "b9190", "latest_tag": "b9300", "age_days": 1})
     assert "1 day" in msg
     assert "1 days" not in msg
+
+
+# parse_base_build / is_behind.
+
+
+def test_parse_base_build():
+    assert fr.parse_base_build("b9596") == 9596
+    assert fr.parse_base_build(" b9596 ") == 9596
+    assert fr.parse_base_build("b9596-mix-e6f2453") == 9596  # mix suffix doesn't defeat it
+    assert fr.parse_base_build("9596") is None
+    assert fr.parse_base_build("master-abc") is None
+    assert fr.parse_base_build("") is None
+    assert fr.parse_base_build(None) is None
+
+
+@pytest.mark.parametrize(
+    "installed, latest, expected",
+    [
+        (
+            "b9596-mix-e6f2453",
+            "b9596-mix-e6f2453",
+            False,
+        ),  # already on the mix latest -> not behind
+        ("b9596", "b9594", False),  # latest is an older build -> downgrade guard
+        ("b9596", "b9594-mix-xxx", False),  # older mix latest -> still guarded
+        ("b9500", "b9596-mix-e6f2453", True),  # newer base -> behind
+        ("b9596-mix-aaa", "b9596-mix-bbb", True),  # new mix at same base -> behind
+        ("b9596", "b9596-mix-bbb", True),  # clean -> mix at same base -> behind
+        ("b9596-mix-aaa", "b9596", False),  # bare base never supersedes a mix install
+        ("b9596", "b9596", False),  # identical -> not behind
+        (" b9596 ", "b9596", False),  # whitespace-only diff -> not behind
+        ("master-abc", "master-def", True),  # non-bNNNN both -> plain inequality
+        ("master-abc", "master-abc", False),
+        (None, "b9596", False),
+        ("b9596", None, False),
+    ],
+)
+def test_is_behind(installed, latest, expected):
+    assert fr.is_behind(installed, latest) is expected
+
+
+def test_check_prebuilt_freshness_not_behind_on_mix_latest(monkeypatch, tmp_path):
+    # Installed the mix latest: marker base tag b9596, full release_tag with sha,
+    # GitHub latest is that same full tag. Must not report behind (sticky bug).
+    install_dir = tmp_path / "llama.cpp"
+    _write_marker(install_dir, tag = "b9596", release_tag = "b9596-mix-e6f2453")
+    bin_path = _fake_binary(install_dir, layout = "root")
+    monkeypatch.setattr(
+        fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9596-mix-e6f2453"
+    )
+    info = fr.check_prebuilt_freshness(str(bin_path))
+    assert info["behind"] is False
+    assert info["stale"] is False
+
+
+def test_check_prebuilt_freshness_downgrade_guard(monkeypatch, tmp_path):
+    # A lagging latest (older build than installed) must never read as behind/stale.
+    install_dir = tmp_path / "llama.cpp"
+    _write_marker(
+        install_dir,
+        tag = "b9585",
+        installed_at_utc = (datetime.now(tz = timezone.utc) - timedelta(days = 30))
+        .isoformat()
+        .replace("+00:00", "Z"),
+    )
+    bin_path = _fake_binary(install_dir, layout = "root")
+    monkeypatch.setattr(fr, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+    info = fr.check_prebuilt_freshness(str(bin_path))
+    assert info["behind"] is False
+    assert info["stale"] is False
+
+
+def test_fetch_latest_release_tag_uses_publish_time(monkeypatch):
+    # Resolves newest by published_at (like the installer), skips drafts/prereleases,
+    # and does NOT just take GitHub's first/`/releases/latest` item.
+    import urllib.request
+
+    class _Resp:
+        def __init__(self, payload):
+            self._p = json.dumps(payload).encode()
+
+        def read(self):
+            return self._p
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    payload = [
+        {
+            "tag_name": "b9518",
+            "draft": False,
+            "prerelease": False,
+            "published_at": "2026-06-04T21:11:19Z",
+        },
+        {
+            "tag_name": "b9596-mix-e6f2453",
+            "draft": False,
+            "prerelease": False,
+            "published_at": "2026-06-11T22:50:41Z",
+        },
+        {
+            "tag_name": "b9999-draft",
+            "draft": True,
+            "prerelease": False,
+            "published_at": "2026-06-12T00:00:00Z",
+        },
+    ]
+    monkeypatch.setattr(urllib.request, "urlopen", lambda req, timeout = 5.0: _Resp(payload))
+    assert fr._fetch_latest_release_tag("unslothai/llama.cpp") == "b9596-mix-e6f2453"
diff --git a/studio/backend/tests/test_llama_cpp_update.py b/studio/backend/tests/test_llama_cpp_update.py
index d21d653b76..3b8f511a7c 100644
--- a/studio/backend/tests/test_llama_cpp_update.py
+++ b/studio/backend/tests/test_llama_cpp_update.py
@@ -82,18 +82,21 @@ def _write_install(
     tag: str,
     repo: str = "unslothai/llama.cpp",
     asset: str | None = None,
+    release_tag: str | None = None,
 ) -> str:
     """Create a fake prebuilt install tree and return the llama-server path.
 
     ``asset`` is the bundle filename recorded in the marker; omit it to model an
-    older marker that predates asset-based ROCm forwarding (backward compat)."""
+    older marker that predates asset-based ROCm forwarding (backward compat).
+    ``release_tag`` is the full release tag (e.g. a ``b9596-mix-<sha>`` mix
+    build); defaults to ``tag`` for a plain prebuilt."""
     bin_dir = dir_ / "build" / "bin"
     bin_dir.mkdir(parents = True, exist_ok = True)
     binary = bin_dir / "llama-server"
     binary.write_text("#!/bin/sh\necho stub\n")
     marker = {
         "tag": tag,
-        "release_tag": tag,
+        "release_tag": release_tag or tag,
         "published_repo": repo,
         "installed_at_utc": "2020-01-01T00:00:00Z",
         "bundle_profile": "cuda13-newer",
@@ -106,10 +109,13 @@ def _write_install(
 
 
 @pytest.fixture(autouse = True)
-def _clean_state(monkeypatch):
+def _clean_state(monkeypatch, tmp_path):
     freshness.reset_caches()
     upd._reset_job_for_tests()
     upd._resolve_memo.clear()
+    # Isolate the freshness disk cache so the suite never writes the real
+    # ~/.unsloth cache (the default when storage_roots can't be imported).
+    monkeypatch.setattr(freshness, "_cache_dir", lambda: tmp_path / ".freshness_cache")
     # Deterministic markerless paths: no host-pinned binary, no custom dir.
     monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
     monkeypatch.delenv("UNSLOTH_LLAMA_CPP_PATH", raising = False)
@@ -395,6 +401,7 @@ def test_start_update_installer_failure_reports_error(monkeypatch, tmp_path):
     binary = _write_install(install_dir, "b9493")
     monkeypatch.setattr(upd, "_find_binary", lambda: binary)
     monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
 
     _patch_installer_popen(monkeypatch, returncode = 2, lines = ["boom: network error\n"])
 
@@ -617,6 +624,7 @@ def test_update_clears_maintenance_flag_on_installer_failure(monkeypatch, tmp_pa
     binary = _write_install(install_dir, "b9493")
     monkeypatch.setattr(upd, "_find_binary", lambda: binary)
     monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
 
     backend = _FakeBackend()
     _inject_backend(monkeypatch, backend)
@@ -795,3 +803,41 @@ def test_start_update_source_build_refuses_when_newer(monkeypatch, tmp_path):
     res = upd.start_update()
     assert res["started"] is False
     assert res["reason"] == "up_to_date"
+
+
+# --- mix-tag detection + apply guard (the reported banner bug) ---
+
+
+def test_status_not_offered_on_mix_latest(monkeypatch, tmp_path):
+    # Installed the mix latest; GitHub latest is that same full tag -> no banner.
+    binary = _write_install(tmp_path / "llama.cpp", "b9596", release_tag = "b9596-mix-e6f2453")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(
+        freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9596-mix-e6f2453"
+    )
+    st = upd.get_update_status()
+    assert st["update_available"] is False
+    assert st["installed_tag"] == "b9596"
+    assert st["latest_tag"] == "b9596-mix-e6f2453"
+
+
+def test_status_not_offered_when_latest_lags(monkeypatch, tmp_path):
+    # A lagging latest (older build than installed) must never be offered.
+    binary = _write_install(tmp_path / "llama.cpp", "b9585")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9518")
+    st = upd.get_update_status()
+    assert st["update_available"] is False
+
+
+def test_start_update_marked_refuses_when_not_behind(monkeypatch, tmp_path):
+    # A direct POST / stale banner must not reinstall when already on the latest.
+    binary = _write_install(tmp_path / "llama.cpp", "b9596", release_tag = "b9596-mix-e6f2453")
+    monkeypatch.setattr(upd, "_find_binary", lambda: binary)
+    monkeypatch.setattr(upd, "_installer_script", lambda: tmp_path / "install_llama_prebuilt.py")
+    monkeypatch.setattr(
+        freshness, "_fetch_latest_release_tag", lambda repo, timeout = 5.0: "b9596-mix-e6f2453"
+    )
+    res = upd.start_update()
+    assert res["started"] is False
+    assert res["reason"] == "up_to_date"
diff --git a/studio/backend/utils/llama_cpp_freshness.py b/studio/backend/utils/llama_cpp_freshness.py
index 3e5066ca2d..f5fd745334 100644
--- a/studio/backend/utils/llama_cpp_freshness.py
+++ b/studio/backend/utils/llama_cpp_freshness.py
@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import time
 from datetime import datetime, timezone
 from pathlib import Path
@@ -104,11 +105,18 @@ def _save_disk_cache(repo: str, latest_tag: Optional[str]) -> None:
 
 
 def _fetch_latest_release_tag(repo: str, timeout: float = 5.0) -> Optional[str]:
-    """GitHub API call. None on any failure (offline, rate-limited, etc)."""
+    """Newest published release tag for `repo`, by publish time.
+
+    Resolves "latest" the way install_llama_prebuilt.py does (newest
+    non-draft/non-prerelease by ``published_at``), NOT via GitHub's
+    ``/releases/latest`` pointer. That pointer sorts by commit date and can lag
+    behind the build the installer actually installs, so detection and apply
+    disagreed -- the cause of the downgrade/sticky banner. None on any failure
+    (offline, rate-limited, etc)."""
     import urllib.error
     import urllib.request
 
-    url = f"https://api.github.com/repos/{repo}/releases/latest"
+    url = f"https://api.github.com/repos/{repo}/releases?per_page=30"
     headers = {
         "Accept": "application/vnd.github+json",
         "User-Agent": "unsloth-studio-freshness-check",
@@ -128,8 +136,21 @@ def _fetch_latest_release_tag(repo: str, timeout: float = 5.0) -> Optional[str]:
     ) as exc:
         logger.debug("freshness fetch failed", repo = repo, error = str(exc))
         return None
-    tag = data.get("tag_name")
-    return tag if isinstance(tag, str) and tag else None
+    if not isinstance(data, list):
+        return None
+    published = [
+        r
+        for r in data
+        if isinstance(r, dict)
+        and not r.get("draft")
+        and not r.get("prerelease")
+        and isinstance(r.get("tag_name"), str)
+        and r.get("tag_name")
+    ]
+    if not published:
+        return None
+    newest = max(published, key = lambda r: r.get("published_at") or "")
+    return newest["tag_name"]
 
 
 def latest_published_release(repo: str, *, force_refresh: bool = False) -> Optional[str]:
@@ -172,19 +193,58 @@ def _parse_installed_at(value: object) -> Optional[datetime]:
     return dt
 
 
+def parse_base_build(tag: object) -> Optional[int]:
+    """Numeric base build from a release tag. Handles both a plain ``bNNNN`` and
+    a mix-build tag like ``b9596-mix-<sha>`` (anchored at the start, so the mix
+    suffix doesn't defeat it). None for anything not starting with ``bNNNN``."""
+    if not isinstance(tag, str):
+        return None
+    m = re.match(r"b(\d+)", tag.strip())
+    return int(m.group(1)) if m else None
+
+
+def is_behind(installed: Optional[str], latest: Optional[str]) -> bool:
+    """Whether `installed` is genuinely behind `latest`, comparing the FULL
+    release identity (so a mix build can legitimately be the latest) with a
+    base-build guard so a lagging GitHub /releases/latest can never read as an
+    update or a downgrade.
+
+    - identical tags -> not behind (clears the sticky banner post-update)
+    - higher base build on `latest` -> behind; lower -> NOT behind (downgrade guard)
+    - same base build: a different/new mix -> behind, but a bare ``bNNNN`` never
+      supersedes a mix build (extra PRs) at that base -> not behind
+    - non-bNNNN tags -> behind (plain inequality, since they already differ)
+    """
+    if not installed or not latest:
+        return False
+    installed, latest = installed.strip(), latest.strip()
+    if installed == latest:
+        return False
+    ib, lb = parse_base_build(installed), parse_base_build(latest)
+    if ib is None or lb is None:
+        return True
+    if lb != ib:
+        return lb > ib
+    # Same base build, different tags: offer a mix (latest carries a suffix), but
+    # never offer a bare base over a mix install at the same base.
+    return latest != f"b{lb}"
+
+
 def check_prebuilt_freshness(
     binary_path: Optional[str],
     *,
     threshold_days: int = STALENESS_THRESHOLD_DAYS,
     now: Optional[datetime] = None,
 ) -> dict:
-    """Returns {has_marker, stale, installed_tag, latest_tag,
+    """Returns {has_marker, stale, behind, installed_tag, latest_tag,
     installed_at_utc, age_days, published_repo, threshold_days}.
-    stale = True iff installed != latest AND age >= threshold.
-    Fails open on missing data (stale stays False)."""
+    behind = installed genuinely older than latest (see is_behind).
+    stale = behind AND age >= threshold.
+    Fails open on missing data (behind/stale stay False)."""
     out: dict = {
         "has_marker": False,
         "stale": False,
+        "behind": False,
         "installed_tag": None,
         "latest_tag": None,
         "installed_at_utc": None,
@@ -196,16 +256,25 @@ def check_prebuilt_freshness(
     if not marker:
         return out
     out["has_marker"] = True
+    # Display prefers the normalized base ("tag"); comparison below prefers the
+    # full "release_tag" -- deliberately opposite fallbacks.
     out["installed_tag"] = marker.get("tag") or marker.get("release_tag")
     out["installed_at_utc"] = marker.get("installed_at_utc")
     out["published_repo"] = marker.get("published_repo")
 
+    # The marker records both a normalized base tag ("tag", e.g. b9596) and the
+    # full release tag ("release_tag", e.g. b9596-mix-<sha>). Compare against the
+    # FULL identity, since GitHub /releases/latest returns the full tag_name --
+    # comparing the normalized base against the full latest is what produced the
+    # permanent "downgrade" banner on every mix release.
+    installed_full = marker.get("release_tag") or marker.get("tag")
     repo = out["published_repo"]
-    if not repo or not out["installed_tag"]:
+    if not repo or not installed_full:
         return out
     latest = latest_published_release(repo)
     out["latest_tag"] = latest
-    if not latest or latest == out["installed_tag"]:
+    out["behind"] = is_behind(installed_full, latest)
+    if not out["behind"]:
         return out
 
     installed_at = _parse_installed_at(out["installed_at_utc"])
diff --git a/studio/backend/utils/llama_cpp_update.py b/studio/backend/utils/llama_cpp_update.py
index 55bf4b3d84..654ade6cd4 100644
--- a/studio/backend/utils/llama_cpp_update.py
+++ b/studio/backend/utils/llama_cpp_update.py
@@ -286,9 +286,10 @@ def get_update_status(*, force_refresh: bool = False) -> dict:
     freshness = check_prebuilt_freshness(binary)
     installed = freshness.get("installed_tag")
     latest = freshness.get("latest_tag")
-    update_available = bool(
-        freshness.get("has_marker") and installed and latest and installed != latest
-    )
+    # `behind` compares the full release identity with a base-build guard, so a
+    # lagging /releases/latest or a mix-tagged latest can't show a false update
+    # (see llama_cpp_freshness.is_behind).
+    update_available = bool(freshness.get("has_marker") and freshness.get("behind"))
 
     with _job_lock:
         job = dict(_job)
@@ -405,9 +406,14 @@ def _run_update(install_dir: Path, repo: str, asset: Optional[str], script: Path
             tail = "".join(tail_lines).strip()[-1500:]
             raise RuntimeError(f"installer exited {returncode}: {tail or 'no output'}")
 
-        # New UNSLOTH_PREBUILT_INFO.json is on disk; drop caches so the next
-        # status read reflects the freshly installed tag.
+        # New UNSLOTH_PREBUILT_INFO.json is on disk; drop in-memory caches and
+        # re-prime the 24h disk freshness cache with the true newest, so the
+        # banner can't linger on a stale same-base value after the swap.
         reset_caches()
+        try:
+            latest_published_release(repo, force_refresh = True)
+        except Exception as exc:  # pragma: no cover - network defensive
+            logger.debug("llama update: post-install freshness refresh failed", error = str(exc))
         new_marker = read_install_marker(_find_binary())
         new_tag = (new_marker or {}).get("tag") or (new_marker or {}).get("release_tag")
 
@@ -456,7 +462,24 @@ def start_update() -> dict:
             "job": get_update_status()["job"],
         }
 
+    # A job already in flight wins over any freshness re-check below (and skips
+    # its network call). The final lock block re-checks to close the TOCTOU.
+    with _job_lock:
+        if _job["state"] == _JOB_RUNNING:
+            return {"started": False, "reason": "already_running", "job": dict(_job)}
+
     if marker:
+        # Mirror the detection guard: a direct POST or a stale banner must not
+        # start an install when the latest is not actually newer (force a fresh
+        # check so a stale 24h cache can't wrongly block a real update either).
+        status = get_update_status(force_refresh = True)
+        if not status.get("update_available"):
+            return {
+                "started": False,
+                "reason": "up_to_date",
+                "message": "The installed llama.cpp build is already at the latest prebuilt.",
+                "job": status["job"],
+            }
         install_dir = _install_dir_for(binary)
         repo = marker.get("published_repo") or DEFAULT_PUBLISHED_REPO
         from_tag = marker.get("tag") or marker.get("release_tag")

From 0793775c01c24099cd4f31432d89ba0e9635931c Mon Sep 17 00:00:00 2001
From: Michael Han <107991372+shimmyshimmer@users.noreply.github.com>
Date: Thu, 11 Jun 2026 20:07:37 -0700
Subject: [PATCH 219/222] Fix kwarg spacing in training files to satisfy
 pre-commit (#6209)

The ruff-format-with-kwargs hook reformats these three files, so
pre-commit.ci fails on every PR. Formatting only, no behavior change.

From 11d5f64eeb81a3dacd5a4c0c8eb1b45268be00e1 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 20:07:51 -0700
Subject: [PATCH 220/222] Studio: reword the Cloudflare line when the public
 probe fails (#6217)

On a 0.0.0.0 bind whose public ip:port is not reachable (cloud firewall),
the banner still printed "Secure link access via Cloudflare: <url>" right
after "is NOT reachable from the public internet", which reads as if the
tunnel might also be blocked. The Cloudflare quick-tunnel works regardless.

Thread the reachability probe result through a module-level _public_reachable
tri-state and, when the public probe definitively failed but the tunnel is
up, print "Also, the secure link access via Cloudflare works: <url>".
Reachable or undecided cases keep the existing wording.
---
 studio/backend/run.py                         | 20 ++++++-
 .../backend/tests/test_cloudflare_tunnel.py   | 54 +++++++++++++++++++
 2 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/studio/backend/run.py b/studio/backend/run.py
index 32dfe06a18..a883154c4a 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -232,6 +232,9 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
     public internet. Synchronous so output lands between the banner URLs and the
     stop hint. Bounded at ~15s; failures swallowed (verifier failing != Studio
     failing). Only meaningful for a wildcard bind."""
+    global _public_reachable
+    # Reset to "unknown" each run; set True/False only when the probe decides.
+    _public_reachable = None
     import ipaddress
     import json
     import time
@@ -324,12 +327,14 @@ def _verify_global_reachability(display_host: str, port: int) -> None:
 
         print("", flush = True)
         if ok_nodes:
+            _public_reachable = True
             print(
                 f"{ok_c}  Reachability check: {url}/ is reachable from the "
                 f"public internet ({ok_nodes}/{total} probe nodes connected).{reset}",
                 flush = True,
             )
         elif err_nodes:
+            _public_reachable = False
             print(
                 f"{err_c}  Reachability check: {url}/ is NOT reachable from "
                 f"the public internet ({err_nodes}/{total} probe nodes failed).{reset}",
@@ -422,7 +427,9 @@ def _print_cloudflare_line() -> None:
     """Print the Cloudflare quick-tunnel URL for 0.0.0.0 binds, if one is up.
 
     Reads the module-level URL set by ``run_server``. Prints nothing when the
-    tunnel is disabled or failed -- failures are silently ignored.
+    tunnel is disabled or failed -- failures are silently ignored. When the public
+    reachability probe just failed (``_public_reachable is False``) but the tunnel
+    is up, reword to point the user at the Cloudflare link as the way in.
     """
     if not _cloudflare_url:
         return
@@ -430,7 +437,10 @@ def _print_cloudflare_line() -> None:
 
     accent = "\033[38;5;150;1m"
     reset = "\033[0m"
-    line = f"  Secure link access via Cloudflare: {_cloudflare_url}"
+    if _public_reachable is False:
+        line = f"  Use the secure link access via Cloudflare instead: {_cloudflare_url}"
+    else:
+        line = f"  Secure link access via Cloudflare: {_cloudflare_url}"
     print(f"{accent}{line}{reset}" if stdout_supports_color() else line)
 
 
@@ -622,6 +632,12 @@ _shutdown_event = None
 # None when there is no tunnel (loopback, disabled, or a silently-ignored failure).
 _cloudflare_url = None
 
+# Public reachability from the last _verify_global_reachability run, read by the
+# Cloudflare banner line. True when the public ip:port probe confirmed reachable,
+# False when it confirmed NOT reachable, None when the probe did not run or could
+# not decide (timeout, blocked, private address).
+_public_reachable = None
+
 
 _DEFAULT_FRONTEND_PATH = Path(__file__).resolve().parent.parent / "frontend" / "dist"
 
diff --git a/studio/backend/tests/test_cloudflare_tunnel.py b/studio/backend/tests/test_cloudflare_tunnel.py
index 8208f7f83f..873547631d 100644
--- a/studio/backend/tests/test_cloudflare_tunnel.py
+++ b/studio/backend/tests/test_cloudflare_tunnel.py
@@ -13,6 +13,7 @@ import importlib.util
 import io
 import sys
 import tarfile
+import types
 from pathlib import Path
 
 import pytest
@@ -423,3 +424,56 @@ def test_run_server_gates_tunnel_on_wildcard():
     source = _RUN_PY.read_text()
     assert "_cloudflare_enabled" in source
     assert 'host == "0.0.0.0"' in source
+
+
+def _run_print_cloudflare_line(monkeypatch, *, cloudflare_url, public_reachable):
+    """Exec the real _print_cloudflare_line source in isolation (run.py has heavy
+    deps), with the two module globals injected and startup_banner stubbed."""
+    src = _RUN_PY.read_text()
+    tree = ast.parse(src)
+    func_src = next(
+        ast.get_source_segment(src, n)
+        for n in ast.walk(tree)
+        if isinstance(n, ast.FunctionDef) and n.name == "_print_cloudflare_line"
+    )
+    stub = types.ModuleType("startup_banner")
+    stub.stdout_supports_color = lambda: False
+    monkeypatch.setitem(sys.modules, "startup_banner", stub)
+    captured: list[str] = []
+    ns = {
+        "_cloudflare_url": cloudflare_url,
+        "_public_reachable": public_reachable,
+        "print": lambda *a, **k: captured.append(" ".join(str(x) for x in a)),
+    }
+    exec(compile(func_src, "<print_cloudflare_line>", "exec"), ns)
+    ns["_print_cloudflare_line"]()
+    return "\n".join(captured)
+
+
+def test_cloudflare_line_reworded_when_public_unreachable(monkeypatch):
+    out = _run_print_cloudflare_line(
+        monkeypatch, cloudflare_url = "https://x.trycloudflare.com", public_reachable = False
+    )
+    assert "Use the secure link access via Cloudflare instead: https://x.trycloudflare.com" in out
+
+
+def test_cloudflare_line_default_wording_when_reachable(monkeypatch):
+    out = _run_print_cloudflare_line(
+        monkeypatch, cloudflare_url = "https://x.trycloudflare.com", public_reachable = True
+    )
+    assert "Secure link access via Cloudflare: https://x.trycloudflare.com" in out
+    assert "Use the secure link" not in out
+
+
+def test_cloudflare_line_default_wording_when_unknown(monkeypatch):
+    # Probe did not run / could not decide -> keep the existing wording.
+    out = _run_print_cloudflare_line(
+        monkeypatch, cloudflare_url = "https://x.trycloudflare.com", public_reachable = None
+    )
+    assert "Secure link access via Cloudflare: https://x.trycloudflare.com" in out
+    assert "Use the secure link" not in out
+
+
+def test_cloudflare_line_prints_nothing_without_tunnel(monkeypatch):
+    out = _run_print_cloudflare_line(monkeypatch, cloudflare_url = None, public_reachable = False)
+    assert out == ""

From 84b42c92830bef8914f2bb12fe99cba208addb23 Mon Sep 17 00:00:00 2001
From: Leo Borcherding <borchborchmail@gmail.com>
Date: Thu, 11 Jun 2026 22:14:22 -0500
Subject: [PATCH 221/222] fix: deduplicate lemonade ROCm prebuilt selection log
 (#6021)

* fix: deduplicate lemonade ROCm prebuilt selection log

resolve_lemonade_rocm_choice() is called twice per install (direct
planner + resolve_upstream_asset_choice). The API fetch is already
memoised via _fetch_lemonade_release_cached but the selection log
lines were still emitted on both calls, printing the 'trying
lemonade-sdk ROCm prebuilt' banner and hash-manifest NOTE twice.

Add _lemonade_selection_logged set keyed on (gfx_target, asset_name)
and guard the two log() calls behind a membership check so they print
exactly once per process regardless of call count.

Also extend the _clear_lemonade_release_cache test fixture to clear
the new set between tests to prevent cross-test state bleed.

Fixes #6020

* fix: write log() output to stdout to avoid PowerShell NativeCommandError

On Windows, PowerShell treats any stderr output from a native process as
an error record and prefixes it with 'python.exe :' and sets the
ErrorId to NativeCommandError. Since log() wrote to sys.stderr, every
[llama-prebuilt] status line triggered this, making normal progress
output look like errors in the installer console.

Switch log() to sys.stdout. The download progress bar (DownloadProgress)
retains its stderr/tty logic unchanged -- that path is for interactive
terminal rendering, not status logging.

* fix: remove redundant 'or ""' in lemonade log_key

host.rocm_gfx_target is already guaranteed truthy by the early
return at the top of resolve_lemonade_rocm_choice. The fallback
was dead code.

* Keep resolver stdout machine-readable, route install logs to stdout

log() sending everything to stdout breaks the resolver modes: setup.sh
json.load()s the whole stdout, so one helper log line (network retry,
release-tag scan) corrupts the parse and silently drops back to building
"latest". Default log() to stderr and flip to stdout only on the install
path, where PowerShell otherwise renders stderr as NativeCommandError
noise. Also tighten the lemonade dedup comments.

---------

Co-authored-by: Daniel Han <danielhanchen@gmail.com>
---
 .../test_lemonade_llamacpp_rocm_bins_mock.py  |  9 +++-
 studio/install_llama_prebuilt.py              | 45 +++++++++++++------
 2 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
index 57bbc84fb0..7c6c514b8f 100644
--- a/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
+++ b/studio/backend/tests/test_lemonade_llamacpp_rocm_bins_mock.py
@@ -32,14 +32,19 @@ if resolve_lemonade_rocm_choice is None or _LEMONADE_GFX_FAMILIES is None:
 
 @pytest.fixture(autouse = True)
 def _clear_lemonade_release_cache():
-    """Prevent cross-test pollution of the lemonade release lru_cache when
-    future tests vary the fetch_json mock return value."""
+    """Prevent cross-test pollution of the lemonade release lru_cache and
+    selection-log dedup set when tests vary the fetch_json mock return value."""
     _cache = getattr(_mod, "_fetch_lemonade_release_cached", None)
+    _logged: set | None = getattr(_mod, "_lemonade_selection_logged", None)
     if _cache is not None and hasattr(_cache, "cache_clear"):
         _cache.cache_clear()
+    if _logged is not None:
+        _logged.clear()
     yield
     if _cache is not None and hasattr(_cache, "cache_clear"):
         _cache.cache_clear()
+    if _logged is not None:
+        _logged.clear()
 
 
 _STUB_TAG = "b1262"
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index bd8c90dc9c..bed7a27a63 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -460,8 +460,14 @@ def is_busy_lock_error(exc: BaseException) -> bool:
     return False
 
 
+# Status logs default to stderr so resolver modes keep stdout machine-readable
+# (setup.sh json.load()s the whole stdout). main() flips this for the install
+# path, where PowerShell otherwise renders stderr as NativeCommandError noise.
+_LOG_TO_STDOUT = False
+
+
 def log(message: str) -> None:
-    print(f"[llama-prebuilt] {message}", file = sys.stderr)
+    print(f"[llama-prebuilt] {message}", file = sys.stdout if _LOG_TO_STDOUT else sys.stderr)
 
 
 def log_lines(lines: Iterable[str]) -> None:
@@ -3928,6 +3934,12 @@ def _is_trusted_github_release_url(url: str, expected_repo: str) -> bool:
     return False
 
 
+# (gfx_target, asset_name) pairs already logged. resolve_lemonade_rocm_choice()
+# runs twice per install (direct planner + resolve_upstream_asset_choice), so
+# this stops its selection banner and hash-manifest NOTE printing twice.
+_lemonade_selection_logged: "set[tuple[str, str]]" = set()
+
+
 @functools.lru_cache(maxsize = 8)
 def _fetch_lemonade_release_cached(api_url: str, llama_tag: str) -> "dict | None":
     """Cached wrapper around fetch_json for lemonade release lookups.
@@ -4034,18 +4046,22 @@ def resolve_lemonade_rocm_choice(
     # Note: lemonade tags Linux assets with "ubuntu" but the binary is a
     # generic glibc build that runs on any distro (Arch, Fedora, ...), so
     # this attempt is selected for all Linux ROCm hosts, not just Ubuntu.
-    log(
-        f"AMD GPU {host.rocm_gfx_target!r} ({gfx_family}) -- "
-        f"trying lemonade-sdk ROCm prebuilt {asset_name} "
-        f"(works on any glibc Linux, not just Ubuntu)"
-    )
-    log(
-        f"NOTE: lemonade-sdk/llamacpp-rocm releases are not covered by the "
-        f"Unsloth approved-hash manifest; download integrity relies on "
-        f"functional validation (llama-bench / llama-server smoke tests) "
-        f"after extraction. Set UNSLOTH_DISABLE_LEMONADE_ROCM=1 to skip "
-        f"lemonade and fall back to the upstream HIP build path."
-    )
+    # Log once per (gfx_target, asset); see _lemonade_selection_logged.
+    log_key = (host.rocm_gfx_target, asset_name)
+    if log_key not in _lemonade_selection_logged:
+        _lemonade_selection_logged.add(log_key)
+        log(
+            f"AMD GPU {host.rocm_gfx_target!r} ({gfx_family}) -- "
+            f"trying lemonade-sdk ROCm prebuilt {asset_name} "
+            f"(works on any glibc Linux, not just Ubuntu)"
+        )
+        log(
+            f"NOTE: lemonade-sdk/llamacpp-rocm releases are not covered by the "
+            f"Unsloth approved-hash manifest; download integrity relies on "
+            f"functional validation (llama-bench / llama-server smoke tests) "
+            f"after extraction. Set UNSLOTH_DISABLE_LEMONADE_ROCM=1 to skip "
+            f"lemonade and fall back to the upstream HIP build path."
+        )
     return AssetChoice(
         repo = LEMONADE_ROCM_REPO,
         tag = release_tag,
@@ -6963,6 +6979,9 @@ def main() -> int:
         raise SystemExit(
             "install_llama_prebuilt.py: --install-dir is required unless --resolve-llama-tag, --resolve-install-tag, or --resolve-source-build is used"
         )
+    # Install path only: route status logs to stdout (see _LOG_TO_STDOUT note).
+    global _LOG_TO_STDOUT
+    _LOG_TO_STDOUT = True
     install_prebuilt(
         install_dir = Path(args.install_dir).expanduser().resolve(),
         llama_tag = args.llama_tag,

From 6dae2f525b5218143f85cc8f401313e182bccac3 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Thu, 11 Jun 2026 20:37:01 -0700
Subject: [PATCH 222/222] Stop false RoPE 'default' warning and fix rope drift
 gate on transformers 5 (#6223)

* Handle rope_type 'default' on transformers 5 to stop false RoPE warning

transformers 5 reports rope_type="default" for every plain (unscaled) config
and dropped "default" from ROPE_INIT_FUNCTIONS. _compute_config_rope_inv_freq
then did ROPE_INIT_FUNCTIONS["default"], hit KeyError, returned None and logged
"Could not apply RoPE scaling 'default'; long-context generation may degrade"
on every model load. The inv_freq was still correct (the constructor recomputes
vanilla on None), but the warning is a false alarm for unscaled models.

Compute the unscaled inv_freq directly for rope_type "default"/None instead of
going through ROPE_INIT_FUNCTIONS, so plain configs return the right value with
no warning. Scaled types (llama3/linear/yarn/...) are unchanged.

Also skip test_object_style_rope_scaling_on_config_delegates_correctly when
transformers strict-validates rope_scaling (5.x): it rejects a non-dict object
on config.rope_scaling, so the object-style delegation path cannot be set up
there. The test still runs and asserts on transformers <5.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 tests/utils/test_rope_scaling_drift.py |  9 ++++++++-
 unsloth/models/llama.py                | 14 ++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/tests/utils/test_rope_scaling_drift.py b/tests/utils/test_rope_scaling_drift.py
index fae5a7d8a8..193cb830f5 100644
--- a/tests/utils/test_rope_scaling_drift.py
+++ b/tests/utils/test_rope_scaling_drift.py
@@ -300,7 +300,14 @@ def test_object_style_rope_scaling_on_config_delegates_correctly():
     expected = _reference_inv_freq(dict_config, "linear")
 
     object_config = _make_config({"rope_type": "linear", "factor": 4.0})
-    object_config.rope_scaling = FakeLinearRopeScalingConfig()
+    try:
+        object_config.rope_scaling = FakeLinearRopeScalingConfig()
+    except Exception:
+        pytest.skip(
+            "transformers strict-validates rope_scaling to dict/RopeParameters/None, "
+            "so object-style config.rope_scaling (and the delegation retry it "
+            "exercises) is unreachable on this version."
+        )
     inv_freq, attention_scaling = _compute_config_rope_inv_freq(
         object_config, object_config.rope_scaling
     )
diff --git a/unsloth/models/llama.py b/unsloth/models/llama.py
index 2d31f71ab1..a60edf3fbe 100644
--- a/unsloth/models/llama.py
+++ b/unsloth/models/llama.py
@@ -1673,12 +1673,26 @@ def _llama3_inv_freq_from_config(
     return torch.where(is_medium, smoothed, scaled)
 
 
+def _vanilla_inv_freq_from_config(config, device = "cpu"):
+    """Unscaled RoPE inv_freq (rope_type 'default'/None), matching the constructor's fallback."""
+    base = _get_rope_theta(config, default = 10000.0)
+    dim = getattr(config, "head_dim", None)
+    if dim is None:
+        dim = int(config.hidden_size // config.num_attention_heads)
+    return 1.0 / (base ** (torch.arange(0, dim, 2, dtype = torch.int64, device = device).float() / dim))
+
+
 def _compute_config_rope_inv_freq(config, rope_scaling):
     """(inv_freq, attention_scaling) per config.rope_scaling via transformers'
     ROPE_INIT_FUNCTIONS, with an inline llama3 fallback; (None, 1.0) on failure."""
     original_rope_scaling = rope_scaling
     rope_scaling = _rope_scaling_as_dict(rope_scaling)
     rope_type = rope_scaling.get("rope_type", None) or rope_scaling.get("type", None)
+    # "default"/unset means unscaled RoPE. transformers >=5 reports
+    # rope_type="default" for every plain config and dropped "default" from
+    # ROPE_INIT_FUNCTIONS, so compute it directly instead of warning per load.
+    if rope_type in (None, "default"):
+        return _vanilla_inv_freq_from_config(config).to(dtype = torch.float32, device = "cpu"), 1.0
     try:
         from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS